Enforcing wire, identity, and approval contracts in an agent platform
Making each boundary in an agent platform checkable: shared SDK fixtures, three-state delegated identity, and approval receipts that can be spent only once across replicas.

A Python client retries an error that a TypeScript client against the same server treats as fatal, and both sides can cite the specification. Prose specifications are useful for orienting engineers, which is why we keep writing them, yet they fail as an authority once independent implementations start resolving edge cases. The same drift affects any boundary built on a promise made elsewhere; chasing SDK feature parity, forwarding a user header behind a shared service key, and storing an approval as a boolean all leave the actual contract unstated.
Writing the PHP server for OpenSocial taught me the hard lesson of multi-implementation web standards: any promise crossing independently written components has to be a machine-checkable artifact, verified at the point of use.
I applied that rule on an agent platform built around a JSON-RPC 2.0 protocol for conversations, tools, and streamed output. Operations are defined apart from their HTTP, WebSocket, SSE, and stdio bindings, with SDKs in TypeScript, Go, Python, Rust, and Swift. A replicated gateway authenticates users and routes their requests and their agents’ approval prompts to internal services. Three boundaries required explicit contracts: between SDKs, between services, and between a person and a tool call.
Shared wire contracts across five SDKs
Convenience layers and transports should stay idiomatic per language; forcing Go, Rust, and Swift to mirror TypeScript produces awkward libraries without catching wire drift. What must match is everything a server or downstream consumer can observe: wire shape, error retryability, verified identity fields, and event ordering. In one agent runtime on the platform, the Python side wrapped each streamed update in an envelope the TypeScript side omitted, breaking a downstream event translator on the extra nesting.
Rather than letting each SDK transcribe a spec in its own tests, I put the contract into shared JSON fixtures read directly by each language’s test suite. One fixture lists 20 error codes and whether each is retryable; Go, Python, TypeScript, and Rust all test against that single file. Others pin verified identity fields with their accepted aliases, tool-use event ordering, and sequence numbers on reconnect. Alongside those tests, a black-box suite reads a server’s advertised method list and fails if any method goes unexercised. Coverage remains uneven, with TypeScript reading four fixture families and the others two, and parity means wire shape rather than identical client APIs.
Delegated identity between services
Once the gateway authenticates a user, internal services still need to know which service is calling and on whose behalf. Pairing a shared service credential with a forwarded user header is easy to wire up, yet it turns the service key into ambient authority: any holder can assert an arbitrary user or tenant.
To separate caller identity from user authority, cross-service requests carry a service credential alongside an independent signed delegated token, verified by each receiving service. Verifiers resolve that token into three states: absent, invalid, and verified. Collapsing validation into a two-way branch creates a fail-open escalation bug: when a service also accepts direct service-to-service calls without a user context, falling back to that path whenever verification yields no user claims hands a malformed or expired token service-wide authority. With three states, only an absent token may take the direct service path, and an invalid one is rejected.
Verifiers also check the token’s audience claim against their own service identity, the idea behind RFC 8707’s OAuth resource indicators, so a valid delegated token minted for one service cannot be replayed against another. Because identity enforcement lives inside individual services, it remains configuration-dependent, governed by whether a service registers a verifier and permits direct service calls.
Binding human approvals to a single call
Interactive approval prompts are a reasonable gate for sensitive tool calls, yet storing a user’s click as a boolean leaves the invocation unbound: between approval and execution, arguments can change, permission policy can tighten, or a retry can hit another gateway replica.
To bind the decision to the exact call, the agent hashes the canonicalized tool arguments and sends that digest with the prompt, while the active permission policy reduces to a revision hash. When the user approves, the gateway mints an HMAC-signed receipt, valid for five minutes by default, bound to the tool name, input digest, policy revision, conversation, and turn. Any drift in arguments, policy, or session context fails verification.
An HMAC signature detects tampering, while preventing replay across replicas requires an atomic insert-if-absent in a shared store keyed on the approval’s authority. If two gateway processes each mint a receipt for the same approval, they produce distinct receipt IDs, so keying the store by receipt ID lets both inserts succeed and spends the approval twice; keying on the bound authority instead causes the second insert to collide and fail. Because the gateway both issues and consumes receipts, that write guarantees an approval is spent once across replicas without making tool execution itself exactly once; downstream side effects still need their own idempotency.
Chris Chabot, August 2026