07 - Client mirror: Python ServerClient and the Node CLI

Status: archive. Not the current specification.

Status: target design, not implemented. The shipped server uses endpoint ids and one policy engine; see README section 1 for what exists and section 2 for what does not.

Part of Server SDK v2. Rule R5. Supersedes client-server-alignment.md sections on naming/errors (its gap analysis of envd vs server remains valid input). v2.1: ONE client error range (E3100-E3111, E9xxx is dropped, in-flight class names kept), a wire-code -> exception table, Authorization vs X-Access-Token precedence, a machine-checkable parity ledger covering every op (including the 18 ops, browser.* and ext.* the feasibility review found missing), Sandbox.server versus the declarative sandbox.server.start namespace. Findings: IF-07, IF-10, IF-11, IF-17, IF-26, IF-27, IF-28, N-3, N-8.

1. Principle

The client does not hand-write a method per endpoint. Both clients are generated from the server catalog (operations.json, 02 section 7.1), have the same namespace tree as the server, and are checked by contract tests that replay every catalog operation against a real server.

sb = await Sandbox.connect(sandbox_id)          # existing
srv = sb.server                                  # ServerClient bound to the sandbox's port 9000 (gateway headers added)

await srv.files.list("/tmp")                     # op files.list
data = await srv.files.download("/tmp/a.txt")    # bytes (decoded); op files.download
await srv.commands.run("ls /tmp")                # op commands.run -> CommandResult-like
await srv.agents.codex.run("fix the failing test")           # op agents.codex.run
sess = await srv.agents.codex.sessions.create(environment={"type": "self_hosted", "id": "env_local", "remote_url": srv.base_url},
                                              input="fix the failing test")      # same shape as the official SDK (05 section 5); no `workspace=` shorthand
await srv.custom.grade(submission="...")         # user-defined op, dynamic tree from GET /ops
await srv.call("custom.grade", submission="...") # generic escape hatch (also takes ops.* nodes)

• Method name = last ID segment; namespace attributes mirror the ID: srv.system.env.get(), srv.agents.claude_code.run(...).
• Sync twins: srv.files.list_sync("/tmp") for every method (library convention).
• IDs are importable: from agent_sandbox import ops returns the same OpRef tree as the server's (ops.files.list), so policy code, client calls and docs share spelling. (agent_sandbox.ops is generated from the catalog; the server's agent_sandbox.server.ops is the same declaration; the contract test asserts equality of the two trees.)
• srv.describe(), srv.ops (tree), srv.capabilities() for discovery.
• Parameters are keyword-friendly and typed; results are TypedDicts (dict at runtime) (v2.1, IF-11): the generated ServerClient may emit the existing pydantic result models of models/server.py (the working tree already uses them for 48 endpoints) instead of TypedDicts; the generator has one switch (--result-style typeddict|pydantic, default pydantic for the client wheel because pydantic is already a client dependency; the server package stays stdlib-only). Both are dict-compatible at the boundary. The base exception class is the existing SandboxError (there is no EasySandboxError).
• Compat aliases of the in-flight client (v2.1). The working tree's hand-written ServerClient (api/server_client.py) keeps its method names as deprecated aliases of the generated tree for two minors: srv.process.shell = srv.commands.run, shell_stream = commands.stream, srv.files.upload_legacy/download_legacy stay, srv.system.env()/set_env() = system.env.get/set, srv.devtools.run_code = devtools.code.run, srv.pty.* = srv.terminal.*. A test asserts each alias resolves to the same op id.

2. Generation and drift control

server registry --(agent-sandbox-server gen-client --lang python)--> client-sdk/src/agent_sandbox/api/server/_generated.py
                --(--lang ts)------------------------------------> cli/src/server/generated/catalog.ts, client.ts
                --(--lang openapi)-------------------------------> catalog/openapi.json (shipped, also a release asset)
                --(describe --markdown)--------------------------> tables in 04-builtin-modules.md

• Generated files carry a header with catalog_version, the registry digest, and "DO NOT EDIT". They are committed, so the client wheel has no build-time dependency on the server package and no runtime import of it (AGENTS.md layering stays).
• Drift test (monorepo CI, needs both packages installed from source): regenerate in memory, compare with committed files -> fail on diff. Separate contract test starts a server with full_access, plus fake agent binaries, and for each catalog op calls the generated client method with schema-derived minimal arguments from tests/contract/cases.py (hand-written argument fixtures only; one per op), asserting status class, result keys, and client/server error mapping. A new op without a case fails the suite (case coverage test).
• Dynamic fallback for ops the generated client does not know (custom ops, newer server): ServerClient fetches GET /ops lazily on first unknown attribute access and builds callables from the schema; arguments are validated client-side; results are returned as dicts. This is also how srv.custom.<name> works without codegen. One GET /ops per client instance, cached for the session.

3. Capability awareness (no hidden traffic)

caps = await srv.discover()                 # explicit GET /capabilities (never implicit)
caps.can(ops.files.download)                # bool, for this principal
caps.limit(ops.files.download, "max_bytes") # effective limit or None
caps.paths(ops.files.download)              # PathScope summary (roots, readonly) if the server exposes scopes
caps.require(ops.files.upload)              # raises OperationNotEnabledError (E3103) before any network call
await caps.check(ops.files.download, path="/etc/passwd")   # server-side dry-run: core.check
caps.legacy                                 # True for pre-v2 servers (no `ops` key): groups mapped through the golden lists in 04

• Methods consult a populated cache and fail fast with OperationNotEnabledError / PolicyDeniedError-typed errors only when discover() was called; server responses stay authoritative and produce the same exceptions. No request is made on the user's behalf except the call itself.
• ServerClient(strict=True) makes discover() mandatory before calls (useful in agents that must not probe).
• Discovery body detection (v2.1, IF-26). The server serves a union body (02 section 7). The client detects in this order: ops (v2.1 server) -> endpoints (in-flight v1.x capability server) -> groups (v1 server; golden lists in 04). ServerCapabilities.legacy is true only for the last. The compat keys stay for two minors, then are removed in a catalog_version bump.
• Credentials (v2.1, IF-17). The client sends one credential: Authorization: Bearer <token>. X-Access-Token is sent only when ServerClient(legacy_auth=True) (needed for pre-v2.1 servers; the discovery of a v1 server switches it on automatically). Both headers are never sent together. The server rule (03 section 5): Bearer wins, the legacy header is an alias, both present and different -> 401 auth.conflicting_credentials (client class ServerAuthError, message names the conflict), both equal -> accepted. The gateway's own header (X-Access-Token for the Alibaba gateway) is added by the transport and never forwarded as the server credential; when a deployment sits behind such a gateway, set gateway_token= (transport header) and token= (server Bearer) separately.

4. Errors: ONE range, E3100-E3111 (v2.1, IF-10)

The repository has three schemes today: the working tree uses E9000-E9005 (models/errors.py, header "E9xxx = In-sandbox server API errors"), the in-flight capability design proposed E8xxx, and v2.0 proposed E3100-E3111. Decision (D29): the server plane uses E3100-E3111 only, next to the execution family (E3000-E3006); E8000-E8030 stays exclusively with the providers package (providers/), E9xxx is removed from every plan and document.

Attributes (kept + extended). The working tree's ServerAPIError(status_code, error_type, error_code, endpoint) is kept unchanged (existing user code reads them); v2.1 adds op (the op id; equals endpoint for in-flight servers), request_id, details (dict), status (alias of status_code). The attribute .code remains the E-code ("E3102"), never the wire code; the wire code is .error_code. This removes the v2.0 clash of .code meaning two things.

Wire code -> exception (N-8). Most specific first:

What in-flight code must change (hand-over list): 1. client-sdk/src/agent_sandbox/models/errors.py: header comment E9xxx -> E31xx; code = "E9000..E9005" -> "E3100..E3105"; add ServerInstallError, ServerAgentError, ServerUnavailableError, ServerInternalError, ContractMismatchError, ServerConfigError, ServerArgumentError; add op, request_id, details, status; export in models/__init__.py. 2. client-sdk/src/agent_sandbox/api/server_client.py (error_from_response): map by the table above (prefers the wire code, falls back to the legacy type/status rules). 3. Tests: tests/test_api/server_e2e/test_server_client_models.py (2 hits), test_server_client_policy.py (1 hit): E9xxx -> E31xx. 4. Docs (en and zh pairs): reference/error-codes.md (9), reference/api-reference.md (4), design/fine-grained-capabilities.md (E8xxx text, 5), design/client-server-alignment.md, design/cli-followups.md, root CHANGELOG.md entry. 5. CLI (/workspace/cli): exit-code mapping uses the wire family, not E-codes; nothing to rename. 6. fine-grained-capabilities.md section 7 proposes E8000-E8005: superseded banner; the providers keep E8000-E8030 untouched. A repository test (tests/test_error_codes_unique.py) asserts that no two classes share an E-code except documented subclass pairs and that no class outside providers/ uses E8xxx and none uses E9xxx.

Specific legacy mappings are preserved: files.* 404 -> FileNotFoundError_; commands.run timeout -> CommandTimeoutError (E3001); unknown named command -> CommandNotFoundError (E3005, also EndpointNotAvailableError); non-zero exit remains a result, not an exception (as in ProcessError only when the caller asks check=True). 202 install.job is a result: the generated client polls it with srv.agents.<a>.install.wait(job) or surfaces InstallPending(job_id, retry_after) when wait=False.

5. Sandbox integration

• Sandbox.server versus the declarative namespace (v2.1, IF-07). Today the declarative layer has sandbox.server.start(...) / sandbox.server.register.*. The attribute Sandbox.server is one object (ServerNamespace): it forwards attribute access to the generated ServerClient tree (sb.server.files.list(...)) and keeps the declarative methods start, register, enable_builtin, restart as members (names that are not op namespaces; the generator refuses to emit a namespace named start, register, restart, enable_builtin). A test pins both uses.
• Sandbox.server -> ServerClient for port 9000 using the sandbox's port URL and gateway headers; Sandbox.server_at(port, token=...) for other ports/tokens; the Bearer token comes from server_token= / ABX_SERVER_TOKEN. Both X-Access-Token and Authorization: Bearer are sent per transport (server accepts either).
• Sandbox.start_server(...) (remote start + readiness via healthcheck) as in the base-image design.
• Sandbox.custom(name, **kw) and list_commands() remain unchanged (template mechanism A, server mechanism B) and are re-implemented over srv.custom.* when the server reports v2; for v1 servers they use the old routes.
• Official OpenAI SDK helper: srv.agents.openai_client() returns openai.OpenAI(base_url=<port-url>/v1, api_key=<token>) when openai is installed (lazy import).

6. Parity: client counterpart of every server op (v2.1, IF-27)

Rule: every op has a counterpart on the generated ServerClient tree (same dotted path; R5). Where the experience differs (stream, raw bytes, admin guard, dynamic, reserved, refused) the row says so in Kind and, where it matters, carries an asymmetry id (A1..A7, listed below). The ledger would be tests/contract/client_parity.json, generated by make gen and checked by a drift test. The 18 ops the feasibility review found without a client (files.search, files.upload_stream, files.download_stream, files.archive, process.get, process.output, terminal.list, terminal.get, system.info, system.env.get, system.env.set, system.ports, system.packages, devtools.git.status, devtools.git.diff, core.openapi, core.reload, core.describe), all of browser.* and ext.* are rows below.

6.1 Documented asymmetries

6.2 Plane map (envd vs server)

The two planes keep their own method names (sandbox.files.make_dir on envd, sandbox.server.files.mkdir on the server plane, the latter always equal to the op ID verb); the envd twin column is the map. Applications choose the plane explicitly; there is no transparent fallback between planes (hidden fallbacks would make "was this call policy-checked?" unanswerable). Not mirrored on the server by design: network, pause/resume, timeout, templates (platform plane), envd signed file URLs (envd only).

6.3 Ledger (generated; do not edit by hand)

Per-adapter rows are identical for codex, claude_code, qwen_code, cursor, qoder (the table shows codex; the ledger test expands all five).

7. Node CLI (abx) mirror

The CLI (/workspace/cli, TypeScript, ESM) is a first-class consumer:

• Downstream consumer, separate release train (v2.1, IF-28). The CLI is a separate package (/workspace/cli, its own package.json, vitest, release train). It is fed, not generated in-tree: the SDK release publishes operations.json (+ openapi.json) as a release asset agent-sandbox-server-catalog-<version>.json; the CLI repo's scripts/sync-catalog downloads the pinned version, writes catalog.ts/client.ts and records the digest. The SDK CI does not build the CLI; the CLI CI fails on digest drift.
• Generated cli/src/server/generated/catalog.ts (const catalog + types) and client.ts (ServerClient with the same namespace tree, fetch-based) from operations.json through agent-sandbox-server gen-client --lang ts (run by a script in the CLI repo against the pinned wheel, or fed the catalog file published as a release asset agent-sandbox-server-catalog-<version>.json). scripts/sync-catalog records the catalog digest; CI fails on drift.
• Spelling parity: the TypeScript client uses the op IDs and parameter names exactly as spelled on the wire (snake_case: client.agents.claude_code.run({prompt}), max_entries), no camelCase renaming, so docs, policies and logs read identically in both languages.
• Commands (all generic, so new ops need no CLI release): abx server ops [--json] (list effective ops), abx server describe <op>, abx server call <op> [--arg k=v ...|--json '{...}'], abx server check <op> [--arg ...] (dry-run policy), abx server doctor (remote core.capabilities + health). Friendly wrappers for common namespaces (abx files ls --plane server, abx agents ... per the agents CLI follow-ups) are thin and generated from the catalog where possible.
• Error mapping: the CLI exit codes follow the existing table; server error families map as: auth.* -> auth exit code, policy.*/op.not_enabled -> permission exit code, limit.*/install.* -> retryable code, others -> 1.
• The same catalog/OpenAPI makes other languages (Go, Java, ...) a generator invocation away (operationId = op ID). No hand-maintained clients beyond Python and TypeScript are promised.

8. Versioning and compatibility

• Client sends X-ABX-Client with its catalog version; the server never rejects on it.
• Older client / newer server: works (IDs append-only). Newer client / older server: calls to ops the server does not list raise ContractMismatchError naming the server sdk_version, or transparently use the legacy REST binding when the catalog says the op existed in v1 under another route.
• v1 servers (no ops in /capabilities): ServerCapabilities.legacy = True, group-level gating only via golden lists.