Examples across the family

Every repo in the family ships numbered examples under examples/NN-name.ts, runnable as npm run example:NN (or npx tsx examples/NN-name.ts) against an in-process mock — no network, no API keys, no subprocess. The two .tsx entries at the end of the mcp-query set are the exception: illustrative React/browser code that compiles but needs a bundler and DOM. This page indexes all of them by what you’re trying to do, since the interesting patterns (approvals, policy, invalidation) repeat across protocols.

The four sets:

• agent-query-core — 8 examples of the shared engine, protocol-free
• mcp-query — 8 for MCP
• a2a-query — 13 for A2A
• acp-query — 11 for ACP

Start here — the smallest useful program

• mcp-query 01 · minimal — connect, list, call one tool against the in-memory mock.
• a2a-query 01 · hello task — send a message, get a TaskHandle, await the result, print the artifact text.
• acp-query 01 · basic turn — connect, prompt, watch the session state stream in.
• agent-query-core 01 · cache basics — write, read, staleness, and subscription on the bare engine (injectable clock).

Query a server’s tools and route across servers

• mcp-query 01 · minimal — listTools is a synchronous cache read after connect; callTool("server.tool", args) is namespaced.
• mcp-query 04 · multi-server — one client multiplexing several servers: routing by namespace and by URI scheme, with isolated failure.
• a2a-query 05 · multi-agent — one A2AQuery over several agents, tasks in flight on both, a mini dashboard rendered purely from cache snapshots.
• acp-query 05 · multi-session — two sessions on one connection, prompts in flight simultaneously, updates interleaving on the wire.

Watch a task or turn stream live

• a2a-query 02 · live status — subscribe() to a task’s cache entry; structural sharing keeps idle polls silent.
• a2a-query 08 · streaming — the card advertises capabilities.streaming, and the same TaskHandle surface is driven by sendMessageStream/resubscribeTask instead of polling.
• acp-query 02 · tool calls — the tool_call → tool_call_update lifecycle, rendered live.
• mcp-query 03 · live subscriptions — subscribe to a resource; a server push (notifications/resources/updated) invalidates the cache with no polling.
• a2a-query 12 · push webhook — the disconnected-client story: register a webhook on the send and let the agent POST every update instead of polling.

Caching, tags, and invalidation

• agent-query-core 02 · tags & invalidation — RTK-Query-style declared tags, plus a simulated protocol push driving invalidation.
• mcp-query 02 · cache & invalidation — reads cached and de-duped; a mutation invalidates by tag so the next read refetches.
• acp-query 10 · session list/load caching — the thin cacheable-read surface on an otherwise stream-shaped protocol.
• a2a-query 09 · artifact store — artifacts under their own cache keys, so large outputs are individually readable and invalidatable.

Optimistic updates

• agent-query-core 03 · optimistic updates — patch immediately, roll back when the mutation fails. The pattern the TanStack bridges lean on instead of reimplementing onMutate.

Human-in-the-loop approvals

The same InteractionBroker engine, applied per protocol:

• agent-query-core 04 · approval broker — policy allow/deny/ask, a simulated UI resolving the queue, and the audit printout.
• mcp-query 05 · human-in-the-loop — a server tool elicits input, then requests sampling; the broker queues both.
• a2a-query 03 · approval inbox — the agent pauses INPUT_REQUIRED; the broker queues it; a “human” answers.
• a2a-query 04 · manual resume — no broker at all: the app watches the cached snapshot, notices the pause itself, and resumes by hand.
• acp-query 03 · permission inbox — session/request_permission queued for a human, approved by a simulated UI, recorded in the audit trail.

Policy autopilot — no human in the loop

• a2a-query 06 · policy autopilot — the broker’s trust policy decides; “allow” auto-answers a form-filling agent from app state.
• acp-query 04 · policy rules — auto-answer permissions by trust policy; “allow” picks the first allow_* option the agent offered.
• a2a-query 13 · x402 autopilot — the same broker/policy pattern applied to x402 machine-native payments.

Resilience: retries, flaky networks, connection status

• agent-query-core 07 · connection status — a flaky peer walked through the gRPC-style connectivity state machine.
• agent-query-core 08 · retry policy — backoff with an explicit idempotency contract (injected random, deterministic).
• a2a-query 07 · devtools & resilience — a flaky network, a retry policy, live connectivity status, and a devtools timeline of everything that happened.
• acp-query 06 · cancel — stop a turn mid-flight, including the spec-required answer to the session’s pending permission.

Devtools and wire observability

• a2a-query 10 · wire log — devtoolsWire: true taps the injected fetch and emits per-call wire summaries (bodies excluded).
• acp-query 07 · devtools timeline — a DevtoolsHub capturing a scripted turn: chunks, a tool call, a permission ask.
• acp-query 09 · wire timeline — the same turn over a real stream transport (in-memory duplex; ndJsonStream over stdio in production).

Engine plumbing: interceptors and persistence

• agent-query-core 05 · interceptors — an auth interceptor and a timing interceptor wrapped Koa-onion style around an operation.
• agent-query-core 06 · persistence — dehydrate/hydrate across “sessions”, plus persistCache against a storage shim.

Ergonomics and codegen

• acp-query 08 · client capabilities — supply fs + terminal callbacks (in-memory fakes; node:fs/child_process in a real client) and advertise them.
• acp-query 11 · attached session — newAttachedSession() returns a handle so prompt/cancel/state don’t need the session id threaded through.
• a2a-query 11 · skill codegen — an AgentCard’s skills turned into a typed invocation module (the orval / connect-query shape).

Living alongside agents and other clients

• mcp-query 06 · alongside another client — mcp-query is a non-agentic data layer; it runs beside your agent or other MCP clients, not instead of them.
• mcp-query 07 · hybrid agent + UI — illustrative (.tsx; compiles, needs a bundler/DOM + an LLM): the agent acts while mcp-query renders reactive state.
• mcp-query 08 · WebMCP bridge — experimental, illustrative: document.modelContext makes the page itself an agent-controllable server, both directions in one browser app.

The mcp-query monorepo also carries smaller example sets in its sibling packages — mcp-gate’s library mode, plus recorded-cassette and contract fixtures under mcp-record and mcp-contract — and cross-package examples at the monorepo root composing client + gate + record + contract in one flow.