API, SDK, JSON-RPC, and ACP

Conclusion: this is not “one API,” but four protocols with different ownership models

The shortest useful distinction is this: the browser API serves a UI shipped with the Host; Remote projects compile-time descriptors onto that same browser carrier; the SDK owns a local subprocess on behalf of its caller; and ACP serves automation clients that understand the standard protocol. When the wrong boundary is chosen, the first thing to become ambiguous is usually not the type system, but who owns the process, who may cancel work, and who restores state after a disconnect.

1. Four protocol surfaces: separate them by consumer and lifecycle first

2. Browser API grammar: a four-quadrant message model, not a loose set of fetch calls

ApiProxy separates messages from carriers into four forms: client-request, server-response, server-request, and client-response. The initiator creates an rpcId, and the responder echoes it unchanged. A server request may represent an approval or question that requires an answer, or a pure push; whether a reply is required is statically determined by the method. Client answers return through POST /api/respond, while late or duplicate responses receive only a carrier receipt.API-RPC-MODEL

Parsing follows a two-stage discipline. The first stage recognizes only the four envelope forms, rpcId, and the error union, leaving payload/value as unknown. The second stage parses the method-specific business schema. This lets the transport report a malformed envelope with correlation while preserving a precise business contract instead of diluting everything into one broad JSON schema.API-RPC-SCHEMAS

3. Browser API version posture: ship together instead of negotiating the protocol

HostApi explicitly states that client and Host are shipped together, so there is currently no protocolVersion. host.describe.version is defined as the Host application version, not a wire version. Protocol version negotiation is deferred until independently shipped clients exist.API-HOST-VERSION-CONTRACT

4. Browser carriers: HTTP uplink and WebSocket downlink have asymmetric error layers

The generic Remote/Connection RPC handler accepts only POST with application/json, and requires the URL endpoint to match the envelope method. Invalid envelopes and mismatched methods return typed bad-request results. An unexpected business-handler exception becomes a direct HTTP 500, which the browser carrier then treats as a transport failure. This scope excludes the event WebSocket upgrades and session-export route on the same /api surface.API-HTTP-HANDLERAPI-HTTP-CLIENT

Every /api request first passes Host authority, Fetch Metadata, and Origin fences. These defend against DNS rebinding and cross-site browser requests, but the source explicitly says they are not an authentication layer. Configuring a trusted host only permits requests bearing that authority through this fence; it proves neither network reachability nor requester identity.API-TRUST-FENCE

The trusted-host LAN surface does not give every method equal authority either. Privileged methods for settings, credentials, native dialogs, agent-preset management, and model discovery with draft credentials are separately pinned to loopback authority through an empty trusted-host set and still pass the shared Fetch-Metadata and Origin-authority checks; HTTP and both WebSocket upgrades pass the base trust fence. This is not a full scheme/host/port same-origin test: Origin may be absent, and when present only its authority is compared.API-PRIVILEGED-LOOPBACK

The HTTP bridge buffers the whole request body in memory, with a default 160 MiB limit. Browser disconnect is translated through response close into a Fetch AbortSignal, and the response stream observes socket drain for backpressure. The signal can notify downstream work, but it cannot forcibly stop in-process business logic that ignores cancellation.API-HTTP-BRIDGE

5. The two WebSockets are downlink-only streams; malformed frames and disconnects are different failures

The Host opens one downlink-only WebSocket for mux events and another for Host events. Any business message sent by the client closes the socket with a policy violation. If a source throws, the Host attempts to send stream/error first; on close it aborts the source and waits for all pumps to converge.API-WS-HOST

On the browser side, binary frames, invalid JSON, invalid envelopes, and invalid business frames are logged and dropped rather than terminating the generation. Schema corruption therefore does not automatically reconnect; only socket termination ends the stream.API-WS-CLIENT

6. Browser reconnection replaces the entire generation, not one broken socket

Each generation starts mux, Host, and host.describe concurrently. Normal readiness requires both streams to open and describe to succeed; if a proxy never emits open, a three-second guard allows degraded connection readiness. Provided describe/handshake converges, either stream ending aborts the whole generation and rebuilds both streams. Backoff grows exponentially from 500ms to a 10s cap, with delay jittered between half the cap and the cap. A successful handshake resets the attempt counter. A business sink exception is logged without killing the pump.API-CONNECTION-LOOP

7. Typert Remote: compile-time descriptors become live Service calls at runtime

The carrier-independent Remote request shape contains only namespace, method, exact named arguments, and a signal injected only for methods that declare cancellation. The Gateway also declares a stable set of boundary failure categories.REMOTE-GATEWAY-TYPES

For every invocation, the Host reloads the current strict descriptor, validates the field set, resolves lookup or Context identity, binds the current Service, and validates the result before returning it. If a strict endpoint appeared and was later withdrawn, the Gateway fails closed instead of falling back to weaker SRC inference. This prevents a hot-unloaded method name from silently acquiring a broader contract.REMOTE-HOST-DISPATCH

Cancellation is not universal: methods without a cancellation descriptor receive no signal. If a method that declares cancellation throws after its signal has aborted, the wire maps the outcome to cancelled. Existing RpcError values from lookup policy are preserved, while most other Gateway or business exceptions collapse to internal; rich in-process error categories therefore do not all cross the wire.REMOTE-HOST-ERRORS

8. Remote mounting, withdrawal, and events are explicit capabilities

A client contribution accepts only a strict codec. Before publishing methods, it checks for duplicate descriptors, namespaces, and Service conflicts; a partial installation failure rolls back in reverse order. Each mount token owns an AbortController. Withdrawal marks the mount inactive, aborts in-flight calls, and then removes the methods.REMOTE-CLIENT-MOUNT

The caller converts positional arguments into descriptor-named fields and combines the caller signal with mount lifetime. The returned value is parsed again on the client. At invocation, before entering the carrier try, a missing active Connection still throws directly; after a Connection exists, RPC rejection, abort, and malformed responses fold into the error branch of RemoteResult.REMOTE-CLIENT-INVOKE

Events are not forwarded automatically either. The current surface is an 11-item allowlist that preserves the original Cordis event name and argument list without projection, renaming, or redaction.REMOTE-EVENT-ALLOWLIST Before enqueueing, the Host proves only that the arguments are JSON-safe and then wraps them as host/remote-event.REMOTE-EVENT-FORWARD

Agent and Session identity lookup is part of the BFF lifecycle policy. A live Agent is reused directly; concurrent cold resumes of an ordinary Session are coalesced by ID. Before cold resume, subagent ownership is fenced at entry, after durable inspection, and immediately before calling resume. If a publication race makes resume fail, the catch path rechecks the published identity and maps the relevant collision to agent-busy, preventing the general API from taking over a child owned by another router.REMOTE-AGENT-RESOLVE

9. SDK JSONL: JSON-RPC 2.0 outbound, lenient classification inbound

The SDK transport writes "jsonrpc":"2.0" on outbound requests, responses, and notifications, with one compact frame per line. Inbound, it classifies frames only by the presence of id and method; it does not validate the jsonrpc field or a complete JSON-RPC envelope. StringDecoder prevents a chunk boundary from splitting multibyte UTF-8. Invalid JSON lines, non-objects, and unknown response IDs are ignored. A missing handler returns -32601; a handler rejection returns -32603.SDK-JSONL-TRANSPORT

The application vocabulary has only three client requests: initialize, session/prompt, and shutdown; and four server notifications: session.event, session.status, subagent.started, and subagent.finished. A prompt response is only a durable queue receipt containing messageId. The full SessionEvent crosses the wire, making the Session event vocabulary part of the compatibility surface too.SDK-WIRE-METHODS

initialize ───────────────→ serverInfo
session/prompt ───────────→ messageId  (queue receipt only)
       ├─ session.event ──→ durable facts
       ├─ session.status ─→ whole-agent running / idle
       └─ subagent.* ─────→ in-process child lineage / completion
shutdown ─────────────────→ {}

10. SDK compatibility and security posture: no version negotiation, wire auth, or prompt cancellation

The published limitations state directly that serverInfo.version is fixed at 0.0.1, clients do not compare it with an expected version, prompt cancellation and session close do not exist, and server-to-client requests have no current producer. The transport retains that last capability only for a future approval flow.SDK-WIRE-LIMITS

11. SDK server: global event sources, with session-tree filtering delegated to clients

At construction, the server subscribes to every Session event and Agent status in the Context, not only Sessions created by the SDK. Child-created events are likewise reported globally. A subagent-finished notification is emitted only when the service snapshot says local is true; locality cannot be inferred from a matching ID or parent lineage.SDK-SERVER-EVENTS

initialize parses cwd, stores provider/model/maxTokens, and automatically mounts the DeepSeek fallback only when no owner exists. The class comment says reinitialization is unsupported, but the implementation has no handshake-state field; handleRequest also does not prevent a pre-initialize prompt.SDK-SERVER-INIT

A Session is created lazily on its first prompt, and concurrent creation for the same ID is coalesced through a promise map. Every prompt verifies that the retained handle still equals the live registry instance. Shutdown closes admission, waits for creation to converge, removes subscriptions, and uses allSettled for every Agent and the fallback adapter, reporting multiple failures together.SDK-SERVER-SESSIONS

After the protocol shutdown response is written, the next event-loop turn flushes the transport, disposes the root fiber, and calls exit(0). The successful plugin-only unmount path shuts down the server, then closes the transport without exiting the process; however, the disposer has no finally, so a server-teardown rejection skips transport close.SDK-SERVER-SHUTDOWN

12. TypeScript SDK: run spans receipt-to-idle, not a one-to-one turn result

The low-level HarnessClient spawns the runtime lazily. Initialize requires only that the returned name and version are strings; it does not validate expected values. A request timeout only abandons the local pending-map entry, while server work continues until the runtime is closed. JSON-RPC errors preserve code/data, and transport failures add the exit code plus at most 400 lines of stderr tail.SDK-TS-CLIENT

High-level run() subscribes to the Session tree before sending the prompt. After receiving messageId, it drops notifications before the matching durable inbox receipt and then collects until the root Agent next becomes idle. finalResponse is the last committed assistant text in that interval. Work admitted by another producer before idle may also contribute, so it is not a response uniquely attributable to that prompt.SDK-TS-RUN

Close is a locally authoritative termination sequence: bounded best-effort shutdown, then stdin EOF → POSIX SIGTERM → SIGKILL, resolving only after process exit is observed. Windows proceeds directly to the forced-termination tier.SDK-TS-DISPOSE

13. The Python SDK speaks the same wire, but is not a mechanical translation of the TypeScript API

Python HarnessClient is synchronous and sends the same three requests. It additionally exposes next_request(), respond(), and respond_error() for future server requests; the current server does not send such a request. Python copies the parent environment and then merges explicit overrides by default, unlike TypeScript, where an explicit env replaces the whole environment. Its initialize-response model also permits serverInfo, name, and version to be absent.SDK-PY-CLIENTSDK-PY-MODELS

The reader thread routes responses by ID into waiter queues, fans notifications out to subscriptions, and places frames with id+method into a server-request queue. Timeout removes the waiter and adds exit/stderr diagnostics, but likewise sends no cancellation to the runtime. A filter exception terminates only its own subscription.SDK-PY-READER

High-level Python Session.run() also uses a receipt-to-idle interval, but additionally extracts the final turn/end.reason.kind as finish_reason. A missing string kind raises SdkProtocolError. This is still an interval summary, not a prompt-specific verdict.SDK-PY-RUN

The TypeScript public type fixes env replacement and a four-field RunResult.SDK-TS-RESULT Python configuration adds session-root, base-URL, and API-key conveniences, and returns additional fields.SDK-PY-RESULT

14. SDK drift and enforcement gap: documented intent is not a wire state machine

15. ACP: a standard protocol version with a deliberately narrow automation baseline

The adapter is a public 0.1.0-rc.5 package and pins @agentclientprotocol/sdk 0.25.1.ACP-PACKAGE At runtime it imports PROTOCOL_VERSION, ndJsonStream, and AgentSideConnection directly from that SDK, then constructs the connection over the standard stream. Framing, method machinery, and the protocol constant therefore come from the SDK rather than a custom wire.ACP-SDK-IMPORTSACP-SDK-CONNECTION

Regardless of which version the client requests, initialize returns the PROTOCOL_VERSION supported by this build, advertises only the capabilities needed for a text/resource-link baseline, returns an empty authMethods, and implements authenticate as a no-op. session/new creates only fresh Sessions, requires an absolute cwd, and rejects nonempty additional directories and MCP servers.ACP-HANDSHAKE

16. ACP output and errors: committed answers only, trading token latency for a clean result

The bridge does not forward raw deltas, reasoning, tool traces, plans, or titles. It emits only committed assistant/message text as agent_message_chunk, and turns images into explicit attachment placeholders. A transport/write rejection from sessionUpdate() is caught and warned; because a JSON-RPC notification has no response, a client-handler failure cannot feed back over that notification. For tool-call approvals it owns, the bridge sends a one-shot allow/reject permission request; cancellation or an unknown choice does not grant permission.ACP-OUTPUT-PERMISSION

Each Session permits only one in-flight prompt. The bridge creates a slot keyed by the user messageId and captures its turn on agent/inbox/claimed. turn/end for that captured turn is correlated exactly, while ordinary endings still wait for whole-agent idle. A separate agent/error fallback rejects the current slot only when the turn is not yet captured or differs, with no message-level causality: a prior autonomous-turn failure, or a competing-turn failure after the prompt turn but before idle, may be misattributed to the waiting ACP prompt. Output likewise includes every committed assistant message for that Session through idle, not only the prompt turn. session/cancel is a no-op for an unknown ID; for a known ID it cancels only the corresponding Agent and immediately settles that prompt as cancelled.ACP-PROMPT-CANCEL

The content codec concatenates text unchanged, renders a resource link as a bracketed reference containing its name and URI, and rejects richer blocks. Mapping turn endings to ACP stop reasons is lossy. The codec itself maps max-token to max_tokens, but at whole-agent-idle settlement the prompt wrapper separately lowers it to end_turn because it does not claim a prompt-specific turn outcome.ACP-CODECACP-PROMPT-CANCEL

17. ACP lifecycle: one connection may own multiple Sessions, but there is no per-Session close

Connection close and plugin disposal share one memoized quiesce operation. It synchronously closes admission, clears the map, cancels Agents, and settles every prompt. It then drains only continuable descendants beneath those top-level Agents and disposes handles in parallel. Descendant-drain failure only warns and continues; only handle-disposal failures are aggregated and thrown. Forests owned by other frontends in the same Context are not swept accidentally.ACP-QUIESCE

18. ACP is also a child backend: every run is a fresh-process transaction

The out-of-process provider explicitly advertises no output-schema, depth-limit, tool-filter, or persona support, and does not inherit the parent conversation. Child cwd must come from explicit configuration or the delegating parent Session. Missing workspace fails loudly instead of falling back to server-process cwd.ACP-CHILD-CAPABILITIES

Every run starts a fresh process. The parent creates a separate lifecycle ID so identical ACP Session IDs in different children cannot collide. A handle is published only after spawn, initialize, and session/new all succeed; an error or cancellation before that point first reclaims the private process. A shared subprocess policy removes credential-shaped and DSH_* ambient names, after which the local spawn layer merges explicit child env.ACP-CHILD-STARTACP-CHILD-ENV-POLICYACP-CHILD-ENV-MERGE

Caller abort may immediately return the text collected so far with aborted, while sending best-effort ACP cancel; this does not prove the child has stopped. dispose() is the authoritative quiescence path: it ensures best-effort cancellation has been requested if not already, then performs stdin EOF → termination escalation → whole-tree exit proof.ACP-CHILD-CANCEL

19. Version, authentication, cancellation, reconnect, and recovery matrix

20. Comparison with the public Codex App Server contract

21. Choosing safely: select by required guarantees, not familiar syntax

22. Verification scope and reproducible result

This chapter uses commit 47f943859bef60e4160492346772ded9b24f765a as its fixed baseline. Focused Vitest coverage includes SDK transport/server/client, ACP bridge/codec/permission/multi-session/disposal, the ACP child backend, Typert Gateway, Remote identity resolution, and browser trust/HTTP bridge/WebSocket/reconnect. The SDK transport suite pins framing and error semantics.TEST-SDK-PROTOCOL The ACP bridge suite pins version, auth, fresh-session, and input boundaries.TEST-ACP

The connection suite pins two-stream generations and reconnect behavior.TEST-CONNECTION The Remote client suite pins strict mounting, withdrawal cancellation, scope, and error folding.TEST-REMOTE

pnpm exec vitest run \
  packages/sdk/protocol/tests/transport.spec.ts \
  packages/sdk/server/tests/{server,plugin-apply,plugin-shape}.spec.ts \
  packages/sdk/client/tests/{sdk-client,dispose}.spec.ts \
  packages/acp/acp/tests/{approval,bridge,codec,dispose,edges,multi-session,turns}.spec.ts \
  packages/subagent/subagent-acp/tests/subagent-acp.spec.ts \
  packages/api/gateway/tests/{gateway.client,gateway.host}.spec.ts \
  packages/api/remotes/tests/agent-lookup.spec.ts \
  packages/client/connection/tests/{api-request-trust.host,http-bridge.host,websocket-downlink.host,connection.client}.spec.ts \
  --reporter=verbose

Result: all 21 test files passed; 313/313 tests passed.
Duration: 21.01s (reported by Vitest).