@adcp/sdk 5.25.1 → 6.0.0

package/skills/build-seller-agent/deployment.md

@@ -15,8 +15,9 @@ Companion to [`SKILL.md`](./SKILL.md). Read this only when you need deployment s
 Pass functions for `publicUrl` and `protectedResource`, branch on `ctx.host` in the factory, and turn on `trustForwardedHost` when a proxy terminates TLS:
 
 ```typescript
-import { serve, createAdcpServer, UnknownHostError, hostname } from '@adcp/sdk';
+import { UnknownHostError, hostname } from '@adcp/sdk';
 import { verifyBearer } from '@adcp/sdk/server';
+import { serve, createAdcpServer } from '@adcp/sdk/server/legacy/v5';
 
 // Host → adapter config. Whatever shape suits your deployment (DB, env, static).
 // Cache the CONFIG (not the AdcpServer). serve() still instantiates the
@@ -116,7 +117,8 @@ When your agent is _both_ an OAuth 2.1 AS (issues tokens) and a protected resour
 
 ```typescript
 import express from 'express';
-import { createAdcpServer, createExpressAdapter, verifyBearer, anyOf, verifyApiKey } from '@adcp/sdk/server';
+import { createExpressAdapter, verifyBearer, anyOf, verifyApiKey } from '@adcp/sdk/server';
+import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
 
@@ -388,7 +390,7 @@ You own: the `mcpAuthRouter` wiring (provider-specific), the per-request `transp
 
 ```typescript
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createAdcpServer } from '@adcp/sdk/server';
+import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';
 
 const server = createAdcpServer({
   name: 'Local Seller',

package/skills/build-seller-agent/specialisms/audience-sync.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `audience-sync`.
 
-
 Storyboard: `audience_sync`. Track is `audiences` — separate from the core seller lifecycle, but lives in this skill because identifier sync and account discovery sit next to media-buying.
 
 Required tools: `sync_audiences` and `list_accounts`. `sync_audiences` is overloaded — it handles three cases through its request payload:
@@ -60,4 +59,3 @@ createAdcpServer({
 **Identifier rules:** each `add` entry is a single-identifier object (`{hashed_email}` OR `{hashed_phone}`, not both). Values are SHA-256 of lowercased, trimmed input. Salting/normalization is out-of-band between buyer and platform — document your expected input format.
 
 **Platform types:** destinations span `['dsp', 'retail_media', 'social', 'audio', 'pmax']`. Each has its own `activation_key` shape — see `skills/build-signals-agent/SKILL.md` for activation patterns, which are shared across signals and audience sync.
-

package/skills/build-seller-agent/specialisms/sales-broadcast-tv.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-broadcast-tv`.
 
-
 Storyboard: `media_buy_broadcast_seller`. Broadcast has four protocol surfaces not used in digital.
 
 **Pricing** — unit-based (cost per spot). Until a `pricing_model: 'unit'` lands, express as CPM with a very high `fixed_price` that represents the cost per thousand spots equivalent, or use a custom pricing option ID and clarify in `description`.
@@ -68,4 +67,3 @@ Don't declare `measurement_windows: ['live', 'c3', 'c7']` — the Zod schema rej
 **Measurement windows on delivery** — each delivery row tags `measurement_window: 'live' | 'c3' | 'c7'`, `is_final: boolean`, and `supersedes_window` (for window upgrades). Live ratings mature in 24h, C3 in ~4d, C7 in ~8d. Final reconciliation lands ~15d after last air date.
 
 **Emit window_update webhooks** via `ctx.emitWebhook` (see [§ Webhooks](#webhooks-async-completion-signed-outbound) above). Use `operation_id: \`window_update.${media_buy_id}.${stage}\`` so C3 → C7 supersession retries share a stable idempotency_key.
-

package/skills/build-seller-agent/specialisms/sales-guaranteed.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-guaranteed`.
 
-
 Storyboard: `sales_guaranteed`. `create_media_buy` has **three return shapes**. Route on request signals FIRST — the specialism's name is about IO signing, but the baseline `media_buy_seller` storyboard exercises all three in sequence.
 
 | Request signal                                                         | Return                                                                                                                  | Why                                                                                                     |
@@ -64,4 +63,3 @@ When the task completes, emit the final `create_media_buy` result (carrying `med
 Declare `requires_io_approval` in your `capabilities.features` for this path. For deterministic compliance testing, implement `forceTaskStatus` (not `forceMediaBuyStatus`) in your `TestControllerStore` to drive the task from `submitted → completed` without waiting for a human.
 
 **Governance denial (`GOVERNANCE_DENIED`).** Baseline `media_buy_seller/governance_denied*` scenarios exercise governance refusal. For sellers that compose with a governance agent, call `checkGovernance(...)` from `@adcp/sdk/server` at the top of `create_media_buy`. If the governance agent returns denial, surface with `governanceDeniedError(result)` so the error code is `GOVERNANCE_DENIED` and context echoes. Sellers that don't compose with governance will see these scenarios fail with `INVALID_REQUEST` — expected until upstream gates the scenarios behind a composition-claim specialism (tracked at adcontextprotocol/adcp#2521).
-

package/skills/build-seller-agent/specialisms/sales-non-guaranteed.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-non-guaranteed`.
 
-
 Storyboard: `media_buy_non_guaranteed`. The specialism hinges on `bid_price` and `update_media_buy`, neither of which the baseline example shows.
 
 Packages on `create_media_buy` carry `bid_price`. Validate it against the product's `floor_price`:
@@ -36,4 +35,3 @@ updateMediaBuy: async (params, ctx) => {
 ```
 
 `valid_actions` on an active non-guaranteed buy should include `pause`, `update_bid`, `get_delivery`. The framework auto-populates this when `createMediaBuy`/`updateMediaBuy` return with `status: 'active'`.
-

package/skills/build-seller-agent/specialisms/sales-proposal-mode.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-proposal-mode`.
 
-
 Storyboard: `media_buy_proposal_mode`. The acceptance path inverts the baseline — buyer sends `proposal_id` + `total_budget`, no `packages`.
 
 `get_products` returns a `proposals[]` array alongside products:
@@ -48,4 +47,3 @@ createMediaBuy: async (params, ctx) => {
   // ... fall through to baseline packages path
 },
 ```
-

package/skills/build-seller-agent/specialisms/sales-social.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `sales-social`.
 
-
 Storyboard: `social_platform` (category `sales_social`, track `audiences`).
 
 **`sales-social` is additive, not a replacement.** The storyboard's own metadata declares `interaction_model: media_buy_seller` with `capabilities: [sells_media, accepts_briefs, supports_non_guaranteed]` and lists Snap, Meta, TikTok, and Pinterest as example agents — all of which have product catalogs (ad formats, placements, audience offerings as products) AND accept media buys (campaigns with flights, budgets, ad sets). The storyboard only exercises the audience / catalog / native-creative / events / financials leg because the baseline buyer-flow is covered by `sales-non-guaranteed` (or `sales-guaranteed`). Claim BOTH specialisms and implement the full surface.
@@ -27,4 +26,3 @@ Storyboard: `social_platform` (category `sales_social`, track `audiences`).
 **Handler grouping in `createAdcpServer`:** `sync_audiences`, `sync_catalogs`, and `log_event` live under `eventTracking`, NOT `mediaBuy`. `get_account_financials` and `sync_accounts` live under `accounts`. Baseline `get_products`/`create_media_buy`/etc. stay under `mediaBuy`.
 
 **Don't** rip out `get_products` or `create_media_buy` when adding `sales-social` — you need them. The failure mode from doing so: buyers who discover your agent via `get_adcp_capabilities` expecting a media-buy seller hit immediate compliance failures when every baseline storyboard fails with "tool not registered," and your entire `sales-non-guaranteed` bundle regresses to 0/N passing.
-

package/skills/build-seller-agent/specialisms/signed-requests.md

@@ -2,7 +2,6 @@
 
 Companion to [`../SKILL.md`](../SKILL.md). The SKILL.md baseline applies; this file covers only the deltas for `signed-requests`.
 
-
 Storyboard: `signed_requests`. Transport-layer security specialism — certifies that your agent correctly verifies incoming RFC 9421 HTTP Signatures on mutating AdCP operations.
 
 **If you run this behind OAuth or combine it with idempotency,** also read [§ Composing OAuth, signing, and idempotency](#composing-oauth-signing-and-idempotency) for middleware mount order, 401 disambiguation (Bearer vs Signature challenge), and how the verified signing `keyid` threads into the idempotency principal.
@@ -86,4 +85,3 @@ npx @adcp/sdk@latest storyboard run http://localhost:3001/mcp signed_requests --
 ```
 
 Every negative vector must return the exact `expected_outcome.error_code` in `WWW-Authenticate: Signature error="<code>"`. A non-claiming agent is not graded against this specialism.
-

package/skills/build-si-agent/SKILL.md

@@ -25,7 +25,7 @@ A sponsored intelligence (SI) agent serves conversational sponsored content with
 
 | Specialism   | Status | Delta                                                                                                                                                                                     |
 | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| _(none yet)_ | —      | SI has no specialisms in AdCP 3.0 — pass the `sponsored-intelligence` protocol baseline. Specialism storyboards for conversational-ad-specific patterns are pending future AdCP releases. |
+| _(none yet)_ | —      | SI has no specialisms in AdCP 3.0 — pass the `sponsored_intelligence` *protocol* baseline (declared via `supported_protocols: ['sponsored_intelligence']`). Specialism storyboards for conversational-ad-specific patterns are pending future AdCP releases. |
 
 ## Before Writing Code
 
@@ -51,7 +51,7 @@ How should the agent respond during a session?
 >
 > **Cross-cutting pitfalls matrix runs keep catching:**
 >
-> - **Declare `capabilities: { specialisms: ['sponsored-intelligence'] }` on `createAdcpServer`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.
+> - **Do NOT declare a `sponsored-intelligence` specialism.** SI is a *protocol* in AdCP 3.0 — declared via `supported_protocols: ['sponsored_intelligence']` on the `get_adcp_capabilities` response. There is no SI specialism in the `AdCPSpecialism` enum yet, so adopters wire SI through the v5 handler-bag path (`createAdcpServer` from `@adcp/sdk/server/legacy/v5`). The v6 `DecisioningPlatform` interface does not yet expose a `sponsoredIntelligence` field. (Tracking: SI specialism + auto-hydration of `req.session` is planned for a later v6.x — adopters today persist sessions explicitly via `ctx.store`.)
 
 **`get_adcp_capabilities`** — register first, empty `{}` schema
 
@@ -113,7 +113,7 @@ taskToolResponse({
 
 ### Context and Ext Passthrough
 
-`createAdcpServer` auto-echoes the request's `context` into every response — **do not set `context` yourself** on responses for tools whose request-side `context` is the protocol echo object (`core/context.json`).
+The framework auto-echoes the request's `context` into every response — **do not set `context` yourself** on responses for tools whose request-side `context` is the protocol echo object (`core/context.json`).
 
 **SI override.** `si_get_offering` and `si_initiate_session` override `context` on the request as a domain-specific **string** (natural-language intent hint, per spec: _'mens size 14 near Cincinnati'_). The response schema still keeps `context` as the protocol echo object. The framework detects this mismatch and skips the auto-echo for non-object values — your response simply won't carry a `context` field unless you populate it. If you want correlation tracking for SI responses, construct the context object in your handler (e.g., from a buyer-supplied `ext.correlation_id` or your own generator) and return it on the response.
 
@@ -121,16 +121,16 @@ taskToolResponse({
 
 ## SDK Quick Reference
 
-| SDK piece                                           | Usage                                                                      |
-| --------------------------------------------------- | -------------------------------------------------------------------------- |
-| `createAdcpServer({ name, sponsoredIntelligence })` | Create server with domain-grouped handlers and auto-generated capabilities |
-| `serve(() => createAdcpServer(...))`                | Start HTTP server on `:3001/mcp`                                           |
-| `ctx.store`                                         | State persistence — `get/put/patch/delete/list` domain objects             |
-| `adcpError(code, { message })`                      | Structured error                                                           |
+| SDK piece                                                            | Usage                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `createAdcpServer(config)` *(use this for SI)*                       | v5 handler-bag entry. The only path that ships SI dispatch (the `sponsoredIntelligence: { getOffering, initiateSession, sendMessage, terminateSession }` sub-bag). Reach via `@adcp/sdk/server/legacy/v5`. v6 `createAdcpServerFromPlatform` does not yet expose an SI specialism — when it does, this skill will document the migration. |
+| `serve(() => createAdcpServer(config))`                              | Start HTTP server on `:3001/mcp`                                                                                                                                                                                                                                                                                                                                                |
+| `ctx.store`                                                          | State persistence — `get/put/patch/delete/list` domain objects. SI sessions live here today (no auto-hydration yet).                                                                                                                                                                                                                                                            |
+| `adcpError(code, { message })`                                       | Structured error                                                                                                                                                                                                                                                                                                                                                               |
 
 Handlers return raw data objects. The framework auto-wraps responses and auto-generates `get_adcp_capabilities` from registered handlers.
 
-Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk';`
+Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk/server/legacy/v5';`
 
 ## Setup
 
@@ -159,16 +159,21 @@ Minimal `tsconfig.json`:
 
 ## Implementation
 
-1. Single `.ts` file — use `createAdcpServer` with the `sponsoredIntelligence` domain group
+1. Single `.ts` file — wire `createAdcpServer` from `@adcp/sdk/server/legacy/v5` with a `sponsoredIntelligence` handler bag
 2. Do not register `get_adcp_capabilities` — the framework generates it from registered handlers
 3. Return raw data objects from handlers — the framework wraps responses automatically
-4. Use `ctx.store` to persist active sessions — track state: active → terminated
-5. Handlers receive `(params, ctx)` — `ctx.store` for state, `ctx.account` for resolved account
+4. Use `ctx.store` to persist active sessions — track state: active → terminated. **Sessions are NOT auto-hydrated yet** (planned for v6.x). Read `req.session_id` and look the session up in `ctx.store` on every `si_send_message`.
+5. Handlers receive `(params, ctx)` — `ctx.store` for state, `ctx.account` (when `resolveAccount` is wired) for resolved account
 
 ```typescript
 import { randomUUID } from 'node:crypto';
-import { createAdcpServer, serve, adcpError } from '@adcp/sdk';
-import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';
+import {
+  createAdcpServer,
+  serve,
+  adcpError,
+  createIdempotencyStore,
+  memoryBackend,
+} from '@adcp/sdk/server/legacy/v5';
 
 const idempotency = createIdempotencyStore({
   backend: memoryBackend(),
@@ -180,21 +185,22 @@ serve(() =>
     name: 'SI Agent',
     version: '1.0.0',
     idempotency,
-    // Principal scope for idempotency. MUST never return undefined. A
-    // constant is fine for a demo; for multi-tenant production, type the
-    // account via `createAdcpServer<MyAccount>({...})` and use
-    // `(ctx) => ctx.account?.id`. The framework additionally auto-scopes
-    // `si_send_message` by `session_id`, so the same key under two
-    // sessions doesn't cross-replay.
+    // Principal scope for idempotency. MUST never return undefined. The
+    // framework additionally auto-scopes `si_send_message` by `session_id`,
+    // so the same key under two sessions doesn't cross-replay.
     resolveSessionKey: () => 'default-principal',
-
+    capabilities: {
+      // SI is a *protocol*, not a specialism. Declare it here; the framework
+      // adds it to `get_adcp_capabilities.supported_protocols`.
+      supported_protocols: ['sponsored_intelligence'],
+    },
     sponsoredIntelligence: {
-      getOffering: async (params, ctx) => ({
+      getOffering: async (req, ctx) => ({
         available: true,
         offering_token: `tok_${randomUUID()}`,
         ttl_seconds: 300,
       }),
-      initiateSession: async (params, ctx) => {
+      initiateSession: async (req, ctx) => {
         // session_id MUST be high-entropy (≥122 bits) per spec — it's the
         // scope key for conversational isolation. Never use Date.now() or
         // predictable counters; a guessable session_id lets one buyer
@@ -206,14 +212,17 @@ serve(() =>
           session_status: 'active',
         };
       },
-      sendMessage: async (params, ctx) => {
-        const session = await ctx.store.get('session', params.session_id);
+      sendMessage: async (req, ctx) => {
+        // No auto-hydration of sessions yet — read explicitly. (v6.x will
+        // attach `req.session` for free; until then this lookup is your
+        // session-loss guard.)
+        const session = await ctx.store.get('session', req.session_id);
         // Return the error — the framework echoes returned adcpError
         // responses verbatim. Thrown errors are caught and converted to
         // SERVICE_UNAVAILABLE, which hides your custom code from the buyer.
         if (!session) return adcpError('RESOURCE_NOT_FOUND', { message: 'Session not found' });
         return {
-          session_id: params.session_id,
+          session_id: req.session_id,
           session_status: 'active' as const,
           response: {
             content: 'Sponsored content response',
@@ -221,10 +230,10 @@ serve(() =>
           },
         };
       },
-      terminateSession: async (params, ctx) => {
-        await ctx.store.delete('session', params.session_id);
+      terminateSession: async (req, ctx) => {
+        await ctx.store.delete('session', req.session_id);
         return {
-          session_id: params.session_id,
+          session_id: req.session_id,
           terminated: true,
         };
       },
@@ -254,8 +263,7 @@ Idempotency is wired in the example above. What the framework handles for you:
 **An AdCP agent that accepts unauthenticated requests is non-compliant** (see `security_baseline` in the universal storyboard bundle). Ask the operator: "API key, OAuth, or both?" — then wire one of these into `serve()`.
 
 ```typescript
-import { serve } from '@adcp/sdk';
-import { verifyApiKey, verifyBearer, anyOf } from '@adcp/sdk/server';
+import { serve, verifyApiKey, verifyBearer, anyOf } from '@adcp/sdk/server/legacy/v5';
 
 // API key — simplest, good for B2B integrations
 serve(createAgent, {

package/skills/build-signals-agent/SKILL.md

@@ -32,7 +32,7 @@ A signals agent serves audience segments to buyers for campaign targeting. Two t
 
 Full treatment lives in `skills/build-seller-agent/SKILL.md` §Protocol-Wide Requirements and §Composing. Minimum viable pointers for a signals agent:
 
-- **`idempotency_key`** on every mutating request (`activate_signal`, and any future mutating signals tools). Wire `createIdempotencyStore` into `createAdcpServer({ idempotency })`.
+- **`idempotency_key`** on every mutating request (`activate_signal`, and any future mutating signals tools). Pass `createIdempotencyStore` to `createAdcpServerFromPlatform(platform, { idempotency })`.
 - **Authentication** via `serve({ authenticate })` with `verifyApiKey`/`verifyBearer` from `@adcp/sdk/server`. Unauthenticated agents fail the universal `security_baseline` storyboard.
 - **Signature-header transparency**: accept requests with `Signature-Input`/`Signature` headers even if you don't claim `signed-requests`.
 
@@ -77,9 +77,9 @@ If implementing `activate_signal`:
 >
 > **Cross-cutting pitfalls matrix runs keep catching:**
 >
-> - **Declare `capabilities: { specialisms: ['signal-marketplace'] }` (or `'signal-owned'`) on `createAdcpServer`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.
+> - **Declare `capabilities.specialisms: ['signal-marketplace'] as const` (or `'signal-owned'`) on the `DecisioningPlatform` you pass to `createAdcpServerFromPlatform`.** Value is `string[]` of enum ids (not `[{id, version}]`). Agents that don't declare their specialism fail the grader with "No applicable tracks found" even if every tool works — tracks are gated on the specialism claim.
 
-**`get_adcp_capabilities`** — auto-generated by `createAdcpServer` from registered handlers. Do not register manually.
+**`get_adcp_capabilities`** — auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform`. Do not register manually.
 
 **`get_signals`** — handled by `signals.getSignals`
 
@@ -158,7 +158,7 @@ activateSignalResponse({
 
 ### Context and Ext Passthrough
 
-`createAdcpServer` auto-echoes the request's `context` into every response — **do not set `context` yourself in your handler return values.** The framework injects it post-handler only when the field isn't already present.
+The framework auto-echoes the request's `context` into every response — **do not set `context` yourself in your handler return values.** It's injected post-handler only when the field isn't already present.
 
 **Crucial:** `context` is schema-typed as an object. If your handler hand-sets a string or narrative description, validation fails with `/context: must be object` and the framework does not overwrite. Leave the field out entirely; the framework handles it.
 
@@ -168,19 +168,20 @@ Some schemas also define an `ext` field for vendor-namespaced extensions. If you
 
 | SDK piece                                             | Usage                                                                          |
 | ----------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `createAdcpServer(config)`                            | Create server with domain-grouped handlers and auto-capabilities               |
-| `serve(() => createAdcpServer(config))`               | Start HTTP server on `:3001/mcp`                                               |
+| `createAdcpServerFromPlatform(platform, opts)`        | Create server from a typed `DecisioningPlatform` — compile-time specialism enforcement, auto-capabilities |
+| `createAdcpServer(config)` *(legacy)*                 | v5 handler-bag entry. Mid-migration / escape-hatch only; reach via `@adcp/sdk/server/legacy/v5`            |
+| `serve(() => createAdcpServerFromPlatform(platform, opts))` | Start HTTP server on `:3001/mcp`                                                                       |
 | `signals: { getSignals, activateSignal }`             | Domain group — register handlers by name                                       |
 | `ctx.store.put(collection, id, data)`                 | Persist state (activations, segment cache) across requests                     |
 | `ctx.store.get(collection, id)`                       | Retrieve persisted state                                                       |
 | `getSignalsResponse(data)`                            | Auto-applied response builder (don't call manually)                            |
 | `activateSignalResponse(data)`                        | Auto-applied response builder (don't call manually)                            |
 | `adcpError(code, { message })`                        | Structured error (`SIGNAL_NOT_FOUND`, `INVALID_DESTINATION`)                   |
-| `createIdempotencyStore({ backend, ttlSeconds })`     | Required on every mutating tool — pass via `createAdcpServer({ idempotency })` |
-| `memoryBackend()` / `pgBackend(pool)`                 | Idempotency backends (from `@adcp/sdk/server`)                              |
+| `createIdempotencyStore({ backend, ttlSeconds })`     | Required on every mutating tool — pass via `createAdcpServerFromPlatform(platform, { idempotency })` |
+| `memoryBackend()` / `pgBackend(pool)`                 | Idempotency backends (from `@adcp/sdk/server`)                                 |
 | `type Signal = GetSignalsResponse['signals'][number]` | Type for a single signal object                                                |
 
-Import: `import { createAdcpServer, serve, adcpError } from '@adcp/sdk';`
+Import: `import { createAdcpServerFromPlatform, serve, adcpError } from '@adcp/sdk/server';`
 Server-only: `import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';`
 Types: `import type { GetSignalsResponse } from '@adcp/sdk';`
 
@@ -212,20 +213,41 @@ Minimal `tsconfig.json`:
 ## Implementation
 
 1. Single `.ts` file — all tools in one file
-2. Use `createAdcpServer` with a `signals` domain group — `get_adcp_capabilities` is auto-generated
+2. Use `createAdcpServerFromPlatform` with `signals: SignalsPlatform` on a typed `DecisioningPlatform` class — `get_adcp_capabilities` is auto-generated
 3. Handlers return raw data objects — response builders (`getSignalsResponse`, `activateSignalResponse`) are auto-applied
 4. Use `ctx.store` for persisting signal activations across requests (InMemoryStateStore by default)
 5. Set `sandbox: true` for mock/demo data
 6. Context passthrough is handled by the framework — no need to manually echo `args.context`
 
 ```typescript
-import { createAdcpServer, serve, adcpError } from '@adcp/sdk';
-import { createIdempotencyStore, memoryBackend } from '@adcp/sdk/server';
-
-const signals = [
-  /* your signal objects */
+import {
+  createAdcpServerFromPlatform,
+  serve,
+  AdcpError,
+  createIdempotencyStore,
+  memoryBackend,
+  type DecisioningPlatform,
+  type SignalsPlatform,
+  type AccountStore,
+} from '@adcp/sdk/server';
+import type { GetSignalsResponse } from '@adcp/sdk';
+
+// Type the catalog explicitly. Each entry MUST include `signal_agent_segment_id`
+// — it's the key buyers pass to `activate_signal` and the field the framework
+// uses to auto-store the signal for hydration on the activate call. If you
+// omit it, `tsc` flags every entry; the response validator rejects the
+// `get_signals` reply at runtime in dev/test (strict mode default).
+type Signal = GetSignalsResponse['signals'][number];
+const signals: Signal[] = [
+  /* your signal objects — `signal_agent_segment_id` is required on each */
 ];
 
+// Publisher-internal storage for activations. Persist to your real DB in
+// production; this Map is for the worked example. Note: a module-level Map
+// is fine for single-tenant agents but leaks across tenants in a
+// multi-tenant deployment — partition by `account.id` if you front many.
+const activations = new Map<string, { destinations: unknown[]; activated_at: string }>();
+
 // Idempotency — required for v3 compliance. `activate_signal` is mutating;
 // `get_signals` is read-only and exempt from key validation.
 const idempotency = createIdempotencyStore({
@@ -233,86 +255,110 @@ const idempotency = createIdempotencyStore({
   ttlSeconds: 86400, // 24 hours (spec bounds: 1h–7d)
 });
 
-serve(() =>
-  createAdcpServer({
-    name: 'My Signals Agent',
-    version: '1.0.0',
-    idempotency,
-
-    // Principal scoping for idempotency. MUST never return undefined — or
-    // every mutating request rejects as SERVICE_UNAVAILABLE. A constant
-    // works for a demo; for multi-tenant use ctx.account.
-    resolveSessionKey: () => 'default-principal',
+class MySignals implements DecisioningPlatform {
+  capabilities = {
+    specialisms: ['signal-marketplace'] as const,
+    config: {},
+  };
+
+  // Single-tenant agent: AccountStore.resolve returns the same synthetic
+  // account every request. `upsert` and `list` are optional — omit them on
+  // stateless platforms (the framework returns `UNSUPPORTED_FEATURE` to
+  // buyers calling `sync_accounts` / `list_accounts`).
+  accounts: AccountStore = {
+    resolve: async () => ({
+      id: 'sg_acc_1',
+      operator: 'me',
+      ctx_metadata: {},
+    }),
+  };
+
+  signals: SignalsPlatform = {
+    getSignals: async params => {
+      let results = signals;
+      if (params.signal_spec) {
+        const query = params.signal_spec.toLowerCase();
+        results = results.filter(
+          s => s.name.toLowerCase().includes(query) || s.description.toLowerCase().includes(query)
+        );
+      }
+      if (params.signal_ids) {
+        results = results.filter(s => params.signal_ids!.some(id => id.id === s.signal_id.id));
+      }
+      return { signals: results, sandbox: true };
+    },
 
-    signals: {
-      getSignals: async (params, ctx) => {
-        let results = signals;
-        if (params.signal_spec) {
-          const query = params.signal_spec.toLowerCase();
-          results = results.filter(
-            s => s.name.toLowerCase().includes(query) || s.description.toLowerCase().includes(query)
-          );
-        }
-        if (params.signal_ids) {
-          results = results.filter(s => params.signal_ids!.some(id => id.id === s.signal_id.id));
-        }
-        return { signals: results, sandbox: true };
-      },
-
-      activateSignal: async (params, ctx) => {
-        const signal = signals.find(s => s.signal_agent_segment_id === params.signal_agent_segment_id);
-        // Return the error — the framework echoes returned adcpError
-        // responses verbatim. Thrown errors are caught and converted to
-        // SERVICE_UNAVAILABLE, which hides your custom code from the buyer.
-        if (!signal)
-          return adcpError('SIGNAL_NOT_FOUND', { message: `Unknown segment: ${params.signal_agent_segment_id}` });
-
-        // Persist activation in state store
-        await ctx.store.put('activations', params.signal_agent_segment_id, {
-          signal_agent_segment_id: params.signal_agent_segment_id,
-          destinations: params.destinations,
-          activated_at: new Date().toISOString(),
+    activateSignal: async params => {
+      const signal = signals.find(s => s.signal_agent_segment_id === params.signal_agent_segment_id);
+      // Throw `AdcpError` for buyer-fixable rejection. The framework
+      // catches the throw, projects to the spec's error envelope, and
+      // returns it to the buyer. Returning `adcpError(...)` from the
+      // success arm doesn't typecheck — `activateSignal` is declared
+      // `Promise<ActivateSignalSuccess>`, error is the throw path.
+      if (!signal) {
+        throw new AdcpError('SIGNAL_NOT_FOUND', {
+          recovery: 'correctable',
+          message: `Unknown segment: ${params.signal_agent_segment_id}`,
         });
+      }
 
-        // Platform (DSP) activation is ASYNC per spec — return `is_live: false`
-        // with `estimated_activation_duration_minutes`. The buyer polls
-        // (a subsequent `activate_signal` with the same destinations, or a
-        // provider-specific status tool) until `is_live: true`.
-        //
-        // Agent (sales-agent) activation is SYNC — return `is_live: true` with
-        // `activation_key.type: 'key_value'` and a `deployed_at` timestamp.
-        //
-        // Both shapes include `activation_key` so the buyer knows how to
-        // reference the segment when building media buys through the DSP or SA.
-        const deployments = params.destinations.map(dest => {
-          if (dest.type === 'platform') {
-            return {
-              type: 'platform' as const,
-              platform: dest.platform,
-              is_live: false,
-              estimated_activation_duration_minutes: 30,
-              // Return activation_key even while is_live is false — the
-              // buyer needs to know the planned segment_id now so it can
-              // reference it in downstream media buys. `is_live` just
-              // flags whether the DSP has confirmed provisioning;
-              // `activation_key` is the agent's commitment.
-              activation_key: {
-                type: 'segment_id' as const,
-                segment_id: `${dest.platform}_${signal.signal_id.id}`,
-              },
-            };
-          }
+      // Persist activation. Single-tenant: module-level Map is fine.
+      // Multi-tenant: partition by ctx.account.id (passed as 2nd arg).
+      activations.set(params.signal_agent_segment_id, {
+        destinations: params.destinations,
+        activated_at: new Date().toISOString(),
+      });
+
+      // Platform (DSP) activation is ASYNC per spec — return `is_live: false`
+      // with `estimated_activation_duration_minutes`. The buyer polls
+      // (a subsequent `activate_signal` with the same destinations, or a
+      // provider-specific status tool) until `is_live: true`.
+      //
+      // Agent (sales-agent) activation is SYNC — return `is_live: true` with
+      // `activation_key.type: 'key_value'` and a `deployed_at` timestamp.
+      //
+      // Both shapes include `activation_key` so the buyer knows how to
+      // reference the segment when building media buys through the DSP or SA.
+      const deployments = params.destinations.map(dest => {
+        if (dest.type === 'platform') {
           return {
-            type: 'agent' as const,
-            agent_url: dest.agent_url,
-            is_live: true,
-            activation_key: { type: 'key_value' as const, key: 'audience', value: signal.signal_id.id },
-            deployed_at: new Date().toISOString(),
+            type: 'platform' as const,
+            platform: dest.platform,
+            is_live: false,
+            estimated_activation_duration_minutes: 30,
+            // Return activation_key even while is_live is false — the
+            // buyer needs to know the planned segment_id now so it can
+            // reference it in downstream media buys. `is_live` just
+            // flags whether the DSP has confirmed provisioning;
+            // `activation_key` is the agent's commitment.
+            activation_key: {
+              type: 'segment_id' as const,
+              segment_id: `${dest.platform}_${signal.signal_id.id}`,
+            },
           };
-        });
-        return { deployments, sandbox: true };
-      },
+        }
+        return {
+          type: 'agent' as const,
+          agent_url: dest.agent_url,
+          is_live: true,
+          activation_key: { type: 'key_value' as const, key: 'audience', value: signal.signal_id.id },
+          deployed_at: new Date().toISOString(),
+        };
+      });
+      return { deployments, sandbox: true };
     },
+  };
+}
+
+const platform = new MySignals();
+
+serve(() =>
+  createAdcpServerFromPlatform(platform, {
+    name: 'My Signals Agent',
+    version: '1.0.0',
+    idempotency,
+    // Principal scoping for idempotency. MUST never return undefined.
+    resolveSessionKey: () => 'default-principal',
   })
 );
 ```
@@ -335,7 +381,7 @@ Scoping is per-principal via `resolveSessionKey` (override with `resolveIdempote
 
 ```ts
 const store = createIdempotencyStore({ backend: pgBackend(pool), ttlSeconds: 86400 });
-pool.on('error', (err) => console.error('pg pool error', err)); // prevent crash on idle-client errors
+pool.on('error', err => console.error('pg pool error', err)); // prevent crash on idle-client errors
 serve(createAgent, {
   readinessCheck: () => store.probe(), // throws with a descriptive error if pool/table is broken
 });
@@ -417,9 +463,10 @@ Common failure decoder:
 
 | Mistake                                           | Fix                                                                                                         |
 | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Using `createTaskCapableServer` + `server.tool()` | Use `createAdcpServer` with `signals` domain group                                                          |
+| Using `createTaskCapableServer` + `server.tool()` | Use `createAdcpServerFromPlatform` with `signals: SignalsPlatform` on a typed `DecisioningPlatform` class    |
+| Calling `createAdcpServer` directly in new code   | Reach for `createAdcpServerFromPlatform`; `createAdcpServer` lives at `@adcp/sdk/server/legacy/v5` for mid-migration / escape-hatch only |
 | Using module-level Maps for state                 | Use `ctx.store.put/get` — framework provides `InMemoryStateStore` by default                                |
-| Manually registering `get_adcp_capabilities`      | Auto-generated by `createAdcpServer` from registered handlers                                               |
+| Manually registering `get_adcp_capabilities`      | Auto-generated by `createAdcpServerFromPlatform` from your typed `DecisioningPlatform`                      |
 | Calling response builders manually                | Handlers return raw data — `getSignalsResponse`/`activateSignalResponse` are auto-applied                   |
 | Missing `signal_agent_segment_id` on signals      | Buyers can't activate without it                                                                            |
 | Wrong `signal_id` shape                           | Marketplace: `{ source: "catalog", data_provider_domain, id }`. Owned: `{ source: "agent", agent_url, id }` |

package/skills/call-adcp-agent.previous/SKILL.md

@@ -205,6 +205,7 @@ Returns `{ signals: [{ signal_agent_segment_id, match_rate, pricing, ... }] }`.
 ## Transport notes
 
 - **MCP**: `tools/call` with `{ name: 'tool_name', arguments: {...} }`. Returns `{ content, structuredContent, isError? }`. Read `structuredContent` for the typed response.
+  - **Use the official `@modelcontextprotocol/sdk` client.** The Streamable HTTP transport requires `Accept: application/json, text/event-stream` on every request — a raw `fetch()` with only `Accept: application/json` gets an unhelpful `406 Not Acceptable` from the server before any AdCP framing runs. The official client sets the header correctly; reach for it instead of rolling your own HTTP plumbing.
 - **A2A**: `message/send` with a `DataPart` of shape `{ skill: 'tool_name', input: {...} }` (the legacy key `parameters` is also accepted). Returns an A2A `Task`; the typed response is at `task.artifacts[0].parts[0].data`.
 
 Both transports share: idempotency, error shape, schema enforcement, and handler semantics. If a call works on one, the equivalent call works on the other.
@@ -232,6 +233,10 @@ Quick lookup before reading the full envelope. Match what you see in `adcp_error
 | `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
 | Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | Poll via `tasks/get` (A2A) or the MCP async task extension using `task_id`. |
 | `recovery: 'transient'` (rate limit, 5xx, timeout) | Server-side, retry-safe | Retry with the **same** `idempotency_key`. |
+<<<<<<< Updated upstream
+| `406 Not Acceptable` before any AdCP framing | Hand-rolled HTTP without `Accept: text/event-stream` (MCP transport) | Use `@modelcontextprotocol/sdk` client; it sets the right Accept header. |
+=======
+>>>>>>> Stashed changes
 | `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. |
 | `recovery: 'terminal'` (account suspended, payment required, …) | Requires human action | Don't retry. Surface to the user. |
 | HTTP 401 with `WWW-Authenticate` header | Missing or expired credential | Add `Authorization` per the agent's auth spec; re-auth if applicable. |