cosmos-agent-sdk — Python client

RPC-first Python client for the Auggie v2 SDK / RPC protocol. It implements the shared spec under ../../spec and passes the shared ../../conformance fixtures, in lockstep with the TypeScript client.

Layers

• Transport (cosmos_agent_sdk.transport) — JSONL framing, request/response correlation by id, protocol-version handshake, and message routing. Spawns auggie-v2 --mode rpc (SubprocessTransport); a FakeTransport replays canned wire messages through the same code paths for tests/conformance. Single session per process (multi-session = a client-side process pool).
• Protocol (cosmos_agent_sdk.protocol) — typed command / response / event / extension-UI models mirroring the four JSON Schemas. Deep external structures are forwarded verbatim as permissive objects (see the spec's "Permissiveness policy").
• Facade (cosmos_agent_sdk.client.AgentClient) — the ergonomic API: prompt, wait_for_idle (idle = the agent_end event), the full typed command surface, and bidirectional extension-UI round-trips (reply-expecting methods are answered; fire-and-forget methods are not).

from cosmos_agent_sdk import AgentClient, SubprocessTransport

transport = SubprocessTransport("auggie-v2")
transport.start()
with AgentClient(transport) as client:
    client.prompt("List the files in this repo")
    client.wait_for_idle()
    print(client.get_last_assistant_text()["data"]["text"])

Toolchain

• uv for environment management and building.
• ruff for lint / format.
• mypy for type-checking.
• pytest for the unit suite.

Commands

uv sync --extra dev          # create a venv and install dev dependencies
uv run ruff check .          # lint
uv run ruff format .         # format
uv run mypy cosmos_agent_sdk # type-check
uv run pytest                # unit tests
uv build                     # build the sdist + wheel

Conformance

The cross-client conformance runner is JavaScript. The Python client binds to it through a thin JS shim, conformance-adapter.mjs, that shells out to the real Python client (python -m cosmos_agent_sdk.conformance) driven over an in-memory fake transport replaying the fixture wire messages through the real parsing / correlation / extension-UI code paths (v0 does not spawn a real auggie-v2 binary).

# from clients/python/ — requires the conformance deps installed once:
( cd ../../conformance && npm install )
uv sync --extra dev
make conformance             # or: node conformance-adapter.mjs

Exits non-zero if any of the 40 shared vectors fails.