feat: createAdcpServer with domain-grouped handlers and governance helper

[bokelley]

Summary

• createAdcpServer — declarative server builder that wires domain-grouped handlers to input schemas, Zod validation, response builders, and auto-generated capabilities
• checkGovernance + governanceDeniedError — composable helpers for governance checks in financial handlers (create_media_buy, update_media_buy, activate_signal)
• resolveAccount middleware — auto-resolves AccountReference on every tool with an account field
• 7 domain groups: mediaBuy, signals, creative, governance, accounts, eventTracking, sponsoredIntelligence
• MCP tool annotations — readOnlyHint, destructiveHint, idempotentHint set automatically per tool
• DX safety nets — tool coherence warnings, unknown handler key warnings, handler error catching

Design decisions

• Governance is a composable helper, not framework middleware. Only 3 tools have financial commitment, and update_media_buy doesn't have an account field. Sellers call checkGovernance() explicitly — 3 visible lines beats invisible middleware.
• Account resolution IS framework middleware. It applies to ~15 tools and is pure boilerplate elimination.
• Domain grouping separates concerns (mediaBuy vs eventTracking vs creative) instead of a flat 47-tool namespace.

Related protocol issues

• update_media_buy: add required account field for governance parity with create_media_buy adcp#2174 — update_media_buy needs required account field for governance parity
• preview_creative: flatten union schema into single object with request_type discriminant adcp#2175 — preview_creative union schema should be flattened for server.tool() compatibility

Test plan

• 36 unit tests covering all features (domain grouping, capabilities, response builders, account resolution, error handling, annotations, coherence warnings, unknown keys)
• Full suite: 2952 pass, 0 fail
• CI passes

🤖 Generated with Claude Code

[bokelley]

Session state persistence needed in HandlerContext

We hit a production bug where create_property_list → get_property_list returns not_found on the training agent. Root cause: training agent session state (property lists, media buys, creatives, etc.) lives in an in-memory Map, but production runs 2 Fly.io machines (min_machines_running = 2). Create lands on machine A, get lands on machine B — different in-memory stores.

The PostgresTaskStore already solves this for MCP tasks. But CRUD state (the stuff handlers actually read/write) has no equivalent.

Proposal

createAdcpServer should accept an optional StateStore (or SessionStore) in config, and pass it through HandlerContext:

interface HandlerContext<TAccount = unknown> {
  account?: TAccount;
  state: StateStore;  // <-- new
}

Where StateStore is a simple key-value interface with two implementations:

• InMemoryStateStore — default, for single-instance / tests
• PostgresStateStore — for multi-instance production

This way handlers don't manage their own storage — they get it from the framework, same as they get account from resolveAccount.

This would fix the training agent bug (swap in PostgresStateStore) and give every createAdcpServer user multi-instance safety out of the box.

[bokelley]

Code Review: createAdcpServer

Overall design is solid — domain grouping is clean, handler signature (params, ctx) is simple, governance as composable helpers (not middleware) matches the design spec, and auto-generated capabilities from registered tools is the right pattern. Coherence warnings are a nice touch.

Must Fix

1. Four hasAccount flags are wrong — account resolution silently skipped

get_creative_delivery, get_signals, si_initiate_session, si_terminate_session are marked hasAccount: false in TOOL_META but their Zod schemas include account fields. si_initiate_session has account as required (not nullish). Account resolution and ACCOUNT_NOT_FOUND errors will never fire for these tools.

Better fix: derive hasAccount from the Zod schema at init time ('account' in schema.shape) instead of hand-coding flags. Eliminates this entire class of drift bug.

2. InMemoryStateStore cursor pagination broken with filters

state-store.ts cursor logic indexes into unfiltered Map keys using filtered array indices:

const cursorIndex = items.findIndex((_, i) => {
  const keys = [...col.keys()];  // unfiltered keys
  return keys[i] === options.cursor;  // i is index in filtered items
});

After filtering, items[i] no longer corresponds to col.keys()[i]. Will skip items or return duplicates. Also O(n²) from reconstructing [...col.keys()] on each iteration.

Fix: maintain (id, data) pairs through the filter/pagination pipeline.

Should Fix

3. Module JSDoc still shows resolveGovernance — the top-of-file example references a config property that doesn't exist. Contradicts the actual design (governance is composable helper, not middleware).

4. checkGovernance does unsafe cast — raw as CheckGovernanceResponse with no Zod validation. Malformed governance agent responses will produce confusing property-access errors instead of clear "invalid response" errors. Use CheckGovernanceResponseSchema.safeParse(raw).

5. TOOL_REQUEST_SCHEMAS and TOOL_META are two sources of truth for tool→schema mappings. Drift risk — if a tool is added to one but not the other, they'll silently disagree. Should be a single source.

6. Tests use server._registeredTools — MCP SDK private API. Will break if SDK changes internals. Isolate the access or use a public test transport.

7. No test for required account field — account resolution tests use get_products where account is optional. No test for tools where account is required (e.g., create_media_buy).

Consider

• genericResponse always returns "OK" — not helpful for agents. At minimum include the tool name.
• Capabilities building uses as any casting extensively — won't catch type changes.
• governanceDeniedError also accepts GovernanceConditions — name implies denial-only.
• State store list ordering is undocumented (relies on Map insertion order).

Systemic concern

Items 1 and 5 are symptoms of the same problem: hand-coded metadata that should be derived from schemas. TOOL_META maintains hasAccount flags, annotations, and schema references that could be generated. Once #538 lands the full schema pipeline, these should come from a single generated source, not hand-maintained tables.

[bokelley]

Already implemented in this PR! HandlerContext now has ctx.store: AdcpStateStore with:

• InMemoryStateStore — default (dev/testing)
• PostgresStateStore — production (JSONB table, same PgQueryable pattern as PostgresTaskStore)

Interface: get, put, patch, delete, list by collection + id. Handlers use ctx.store.put('media_buys', id, data) etc.

// Dev (default — zero config)
createAdcpServer({ name: 'Agent', version: '1.0.0', mediaBuy: { ... } })

// Production
const stateStore = new PostgresStateStore(pool);
createAdcpServer({ name: 'Agent', version: '1.0.0', stateStore, mediaBuy: { ... } })

Migration: await pool.query(getAdcpStateMigration()) at startup.

The training agent can swap InMemoryStateStore → PostgresStateStore and the multi-machine bug goes away.