examples

ARCP TypeScript Examples

Twenty-three end-to-end examples covering ARCP v1.1 plus the host-integration middlewares. Each one is a pair of two processes — a runtime (server.ts) and a client (client.ts) — that talk over a real Transport. No mocks. No in-memory shortcuts. Each example exits 0 on success.

Core

Example	Demonstrates	Spec
submit-and-stream/	One-shot job. The agent emits 7 of 8 reserved event kinds (status, log, thought, metric, tool_call, tool_result, artifact_ref) and the client streams them to stdout.	§13.1, §7.1, §8.2
delegate/	Parent agent delegates a child job via a delegate event; child inherits trace_id; child lease is a subset of parent.	§13.2, §10
resume/	Disconnect mid-stream and resume the same session; runtime replays events with event_seq > last_event_seq; fresh resume_token rotated.	§13.3, §6.3
idempotent-retry/	Same (principal, idempotency_key) returns the same job_id; same key + different agent yields DUPLICATE_KEY.	§13.5, §7.2
lease-violation/	An out-of-lease tool call surfaces as a tool_result carrying PERMISSION_DENIED; the job continues and succeeds.	§13.4, §9.3
cancel/	Client submits a long-running job and sends job.cancel; the agent observes ctx.signal, exits, and the runtime emits job.error { final_status: "cancelled" }.	§7.4
stdio/	The runtime runs as a child subprocess; the client spawns it and talks ARCP over stdin/stdout via StdioTransport. Single-command run.	§4.2, §22
vendor-extensions/	Agent emits a custom x-vendor.acme.progress event kind and declares an x-vendor.acme.metrics lease namespace. Client shows both behaviours: a naïve handler that ignores unknown kinds, and a vendor-aware handler that renders the custom kind.	§8.2, §9.2, §15
custom-auth/	Custom BearerVerifier implementation (stateless HMAC-signed tokens). Demonstrates the integration seam for JWT, JWKS, or HTTP auth providers; bad tokens are rejected with UNAUTHENTICATED at handshake.	§6.1

v1.1 features

Example	Demonstrates	Spec
heartbeat/	session.ping / session.pong keepalive; runtime declares heartbeat_interval_sec in session.welcome.	§6.4
ack-backpressure/	session.ack flow control; runtime detects consumer lag and emits a status { phase: "back_pressure" } event.	§6.5, §8.2
list-jobs/	session.list_jobs read-only inventory with status filter + pagination via next_cursor.	§6.6
subscribe/	Two clients on the same principal: one submits, the other discovers via list_jobs, subscribes with history: true, replays + tails live; cross-session cancel is denied with PERMISSION_DENIED.	§7.6, §6.6
agent-versions/	name@version grammar; default-version resolution for bare names; AGENT_VERSION_NOT_AVAILABLE on unregistered version.	§7.5, §12
lease-expires-at/	lease_constraints.expires_at deadline; agent's validateLeaseOp and runtime watchdog both trip LEASE_EXPIRED.	§9.5, §12
cost-budget/	cost.budget lease capability; cost.* metrics auto-decrement the counter; runtime emits debounced cost.budget.remaining; final call hits BUDGET_EXHAUSTED.	§9.6, §12
progress/	progress event kind; client renders a text progress bar.	§8.2.1
result-chunk/	ctx.streamResult() writes ~30 chunks; terminal job.result carries result_id + result_size; client handle.collectChunks() reassembles.	§8.4

Host integrations

Example	Demonstrates	Spec
tracing/	@arcp/middleware-otel wired on BOTH sides; W3C trace context propagated through extensions["x-vendor.opentelemetry.tracecontext"]; spans printed via ConsoleSpanExporter.	§11
express/	@arcp/express — one Node HTTP server serving both Express routes and the ARCP WS upgrade at /arcp, with allowedHosts DNS-rebind protection.	§4.1
fastify/	@arcp/fastify — Fastify HTTP routes alongside ARCP on a single port, with Fastify's pino logger and per-request req.id.	§4.1
bun/	@arcp/bun — serveArcp({...}) listener running under Bun (no ws dependency); Node and Bun clients both interoperate.	§4.1

Running

Each example is two terminals (or processes), with one exception:

# Terminal 1:
pnpm tsx examples/<dir>/server.ts

# Terminal 2:
pnpm tsx examples/<dir>/client.ts

The stdio/ example is single-command — the client spawns its own runtime as a child:

pnpm tsx examples/stdio/client.ts

Each example's README.md documents the demonstration, the spec sections it touches, and the env vars (ARCP_DEMO_PORT, ARCP_DEMO_URL, ARCP_DEMO_TOKEN). Default ports are unique so multiple examples can run simultaneously.

Conventions

• TypeScript with NodeNext module resolution.
• Each example is a self-contained directory: server.ts, client.ts, README.md. No shared fixtures.
• Runtime and client run as separate Node processes, talking either over WebSocket (loopback) or stdio (parent/child pipe). This matches how production deployments actually look.
• Code is intentionally minimal — the SDK provides the heavy lifting (ARCPServer, ARCPClient, the transports). Each example adds one small agent and one demonstration assertion.