Agent client SDK (`tappass-agent`)

Agent client SDK (tappass-agent)

What it does: The library the agent imports — read-only access to its own keyring; observes live policy changes; provides configured LLM + MCP clients.

1. Vision context

Every governed agent depends on this one library. It's the contract between the architecture (the keyring) and the agent application code (LangChain ReAct, custom Python, whatever).

Critically: this SDK has no upward channel. It cannot ask TapPass for more capabilities. There is no request_more_scopes(), no rotate_token(), no negotiate(). Sync is unidirectional. This is enforced by package design (no admin-API client classes), by transport (kernel egress allowlist), and by authentication (scoped sandbox token, no admin scope).

This is the architectural moat: subagents reading this file should understand that adding an upward API to this SDK breaks the entire security story. Don't.

2. Functional specification

Library (primary surface):

from tappass_agent import Keyring, Client

kr = Keyring.load()                  # reads $TAPPASS_KEYRING_PATH (set by tappass-host)
client = Client(kr)                  # opens read-only sync observer

llm = client.gateway_client()        # configured langchain-openai client
mcp = client.mcp_client()            # configured MCP client

@client.on_keyring_change
def reconfigure(new_kr):
    # called when host writes a new keyring
    pass

Thin CLI:

• tappass-agent status — sanitized keyring (scopes shown, tokens redacted)
• tappass-agent watch — live sync events (great for stage demos)
• tappass-agent ping — connectivity check

3. Technical design

Lives at tappass-agent/. Pure Python; minimal dependencies (httpx, mcp client, watchdog/inotify).

4. Definition of done

• All acceptance_criteria pass.
• Library API stable; semver from v1.0.
• Type hints + mypy clean.
• No client class for admin API exists (verified by linter — block any future PR that adds one).
• Pipx-installable.

5. Coordination notes

With host-runtime-cli: env-var contract: TAPPASS_KEYRING_PATH set by host. Coordinate on the keyring file format (JSON; schema in policy-to-sandbox-config-builder).

With pre-deployment-evaluator: evaluator drives agents through the SDK identically to production. No mode flag needed.

6. Out of scope

• Agent task implementation (that's the agent package, e.g. collibra-agent).
• Bootstrap exchange (host-runtime-cli's job).
• Anything that asks TapPass for more capabilities — by design, forever.