@adcp/sdk 6.0.0 → 6.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -35,6 +35,11 @@
       "require": "./dist/lib/types/index.js",
       "types": "./dist/lib/types/index.d.ts"
     },
+    "./types/v2-5": {
+      "import": "./dist/lib/types/v2-5/index.js",
+      "require": "./dist/lib/types/v2-5/index.js",
+      "types": "./dist/lib/types/v2-5/index.d.ts"
+    },
     "./testing": {
       "import": "./dist/lib/testing/index.js",
       "require": "./dist/lib/testing/index.js",
@@ -121,6 +126,9 @@
       "types": [
         "dist/lib/types/index.d.ts"
       ],
+      "types/v2-5": [
+        "dist/lib/types/v2-5/index.d.ts"
+      ],
       "testing": [
         "dist/lib/testing/index.d.ts"
       ],
@@ -178,12 +186,12 @@
   ],
   "scripts": {
     "prepare": "node scripts/install-hooks.js 2>/dev/null || true",
-    "prepublishOnly": "npm run clean && npm run sync-schemas && (test -f src/lib/types/tools.generated.ts || npm run generate-types) && npm run build:lib && node --test-timeout=60000 --test-force-exit --test test/lib/adcp-client.test.js test/lib/validation.test.js test/lib/zod-schemas.test.js",
+    "prepublishOnly": "npm run clean && npm run sync-schemas:all && (test -f src/lib/types/tools.generated.ts || npm run generate-types) && npm run build:lib && node --test-timeout=60000 --test-force-exit --test test/lib/adcp-client.test.js test/lib/validation.test.js test/lib/zod-schemas.test.js",
     "build": "npm run build:lib",
     "build:lib": "npm run sync-version && tsc --project tsconfig.lib.json && tsx scripts/copy-schemas-to-dist.ts",
     "build:test-agents": "npm run build:lib && tsc -p test-agents/tsconfig.json --rootDir test-agents",
-    "test": "node --test-timeout=60000 --test-force-exit --test test/*.test.js test/lib/*.test.js",
-    "test:lib": "node --test-timeout=60000 --test-force-exit --test test/lib/*.test.js",
+    "test": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test test/*.test.js test/lib/*.test.js",
+    "test:lib": "NODE_ENV=test node --test-timeout=60000 --test-force-exit --test test/lib/*.test.js",
     "test:e2e": "node test/e2e/adcp-e2e.test.js",
     "test:protocols": "node test/run-protocol-tests.js",
     "changeset": "changeset",
@@ -196,8 +204,12 @@
     "test:protocol-comparison": "node test/utils/comprehensive-protocol-comparison.js",
     "test:status-report": "node test/utils/final-status-report.js",
     "sync-schemas": "tsx scripts/sync-schemas.ts",
+    "sync-schemas:v2.5": "tsx scripts/sync-v2-5-schemas.ts",
+    "sync-schemas:all": "npm run sync-schemas && npm run sync-schemas:v2.5",
     "schema-diff": "tsx scripts/schema-diff.ts",
     "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts",
+    "generate-types:v2.5": "tsx scripts/generate-v2-5-types.ts",
+    "generate-types:all": "npm run generate-types && npm run generate-types:v2.5",
     "generate-registry-types": "tsx scripts/generate-registry-types.ts",
     "generate-enum-arrays": "tsx scripts/generate-enum-arrays.ts",
     "generate-inline-enum-arrays": "tsx scripts/generate-inline-enum-arrays.ts",
@@ -272,7 +284,7 @@
     "@modelcontextprotocol/sdk": "^1.17.5",
     "@opentelemetry/api": "^1.0.0",
     "pg": "^8.0.0",
-    "zod": "^4.1.0"
+    "zod": "^4.1.5"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {

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

@@ -41,6 +41,11 @@ Every sales-_ specialism (including `sales-social`, `sales-broadcast-tv`, `sales
 | `list_creatives`         | Read the creative library back with pagination                                     | `sales.listCreatives`    |
 | `get_media_buy_delivery` | Delivery + spend reporting with `reporting_period`, per-package billing rows       | `sales.getMediaBuyDelivery` |
 
+> **`sales-guaranteed` minimum tool surface** — register ALL of these or storyboard scenarios will cascade-skip with `skip_reason: missing_tool`:
+> `get_adcp_capabilities`, `sync_accounts`, `list_accounts`, `get_products`, `list_creative_formats`, `create_media_buy`, `update_media_buy`, `get_media_buys`, `sync_creatives`, `get_media_buy_delivery`
+>
+> (`list_creatives` is optional — only required if the seller hosts its own creative library; creative-agent delegates omit it)
+
 **Minimum platform skeleton** — every sales-\* seller starts here, then adds specialism-specific behavior on top:
 
 ```ts
@@ -522,7 +527,17 @@ productsResponse({
 
 **`create_media_buy`** — `CreateMediaBuyRequestSchema.shape`
 
-Validate the request before creating the buy. Return an error response (not `adcpError`) when business validation fails:
+Return `adcpError(...)` for all business validation failures. Error-code matrix — all spec-defined rejections on `create_media_buy` / `update_media_buy`:
+
+| Tool | Condition | Code |
+| --- | --- | --- |
+| `create_media_buy` | `performance_standards` or `measurement_terms` on a package are unacceptable | `adcpError('TERMS_REJECTED', { message: '...' })` |
+| `create_media_buy` | `product_id` on a package not in catalog | `adcpError('PRODUCT_NOT_FOUND', { field: 'packages[N].product_id' })` |
+| `create_media_buy` | product exists but inventory sold out / unavailable for the requested flight | `adcpError('PRODUCT_UNAVAILABLE', { field: 'packages[N].product_id' })` |
+| `create_media_buy` | budget below the product's floor price | `adcpError('BUDGET_TOO_LOW', { message: '...' })` |
+| `create_media_buy` | reversed dates, schema violation | `adcpError('INVALID_REQUEST', { message: '...' })` |
+| `update_media_buy` | `media_buy_id` not found | `adcpError('MEDIA_BUY_NOT_FOUND', { field: 'media_buy_id' })` |
+| `update_media_buy` | `package_id` within a valid buy not found | `adcpError('PACKAGE_NOT_FOUND', { field: 'package_id' })` |
 
 ```
 // Success — revision, confirmed_at, and valid_actions are auto-set:
@@ -900,7 +915,7 @@ import {
   type SalesPlatform,
   type AccountStore,
 } from '@adcp/sdk/server';
-import type { ServeContext } from '@adcp/sdk';
+import type { ServeContext, MediaBuyStatus } from '@adcp/sdk';
 
 // Publisher-typed metadata blob round-tripped via Account.ctx_metadata.
 // Whatever shape your adapter wants — the SDK doesn't inspect it.
@@ -1032,11 +1047,28 @@ class MySeller implements DecisioningPlatform<{}, MySellerMeta> {
       // wholesale. The patch carries envelope fields (idempotency_key,
       // context) that have no business in your domain state. Spreading
       // them pollutes `get_media_buys` responses and breaks dedup.
-      const updated = { ...existing, status: patch.paused === true ? 'paused' : 'active' };
+
+      // State machine: creative_assignments arriving advances pending_creatives.
+      // pending_creatives → pending_start (start_time in future) or active (start_time now/past).
+      let status = existing.status as MediaBuyStatus;
+      if (patch.paused === true) {
+        status = 'paused';
+      } else if (
+        status === 'pending_creatives' &&
+        (patch.packages ?? []).some((p: { creative_assignments?: unknown[] }) =>
+          (p.creative_assignments ?? []).length > 0)
+      ) {
+        const startTime = existing.start_time ? new Date(existing.start_time as string) : null;
+        status = startTime && startTime > new Date() ? 'pending_start' : 'active';
+      } else if (patch.paused === false && status === 'paused') {
+        status = 'active';
+      }
+
+      const updated = { ...existing, status };
       await ctx.store.put('media_buys', mediaBuyId, updated);
       return {
         media_buy_id: mediaBuyId,
-        status: updated.status as 'paused' | 'active',
+        status: updated.status as MediaBuyStatus,
         // `affected_packages` is `Package[]` (per `/schemas/latest/core/package.json`)
         // — objects with at minimum `package_id`. Don't return bare strings;
         // the update-media-buy-response oneOf discriminates against them and
@@ -1103,8 +1135,9 @@ Key points:
 3. Response builders are auto-applied — just return the data
 4. Use `ctx.store` for state — persists across stateless HTTP requests
 5. Set `sandbox: true` on all mock/demo responses
-6. Use `adcpError()` for business validation failures
+6. Use `adcpError()` for business validation failures — see the error-code matrix in § create_media_buy above
 7. Use `as const` on string literal arrays and union-typed fields in product definitions — TypeScript infers `string[]` from `['display', 'olv']` but the SDK requires specific union types like `MediaChannel[]`. Apply `as const` to `channels`, `delivery_type`, `selection_type`, and `pricing_model` values.
+8. `pending_creatives` is a transient state — `update_media_buy` MUST advance it to `pending_start` or `active` when `creative_assignments` arrive (see state-machine logic in § update_media_buy above)
 
 ## Governance
 

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

@@ -30,8 +30,7 @@ createMediaBuy: async (params, ctx) => {
     product_id: pkg.product_id,
     pricing_option_id: pkg.pricing_option_id,
     budget: pkg.budget,
-    property_list: pkg.property_list,     // persist inventory-list refs verbatim
-    collection_list: pkg.collection_list,
+    targeting_overlay: pkg.targeting_overlay, // persists property_list / collection_list verbatim
     creative_assignments: pkg.creative_assignments ?? [],
   }));
   const buy = {
@@ -45,7 +44,9 @@ createMediaBuy: async (params, ctx) => {
 },
 ```
 
-**`get_media_buys` must echo `packages[].property_list` / `collection_list`.** The `inventory_list_targeting` baseline scenarios call `create_media_buy` with list references, then call `get_media_buys` expecting those same `list_id` values to appear at `media_buys[].packages[].property_list.list_id` / `.collection_list.list_id`. Persist verbatim, echo verbatim. `update_media_buy` should merge new list refs without dropping prior ones.
+**`get_media_buys` must echo `packages[].targeting_overlay.property_list` / `.collection_list`.** Per the AdCP types, `property_list` and `collection_list` live inside `TargetingOverlay`, not directly on `Package` (see `/schemas/latest/core/package.json` and `/schemas/latest/core/targeting.json`). The `inventory_list_targeting` baseline scenarios send list refs at `packages[].targeting_overlay.{property_list,collection_list}`; `get_media_buys` must echo them back at the same nested path. Persist the full `targeting_overlay` verbatim; echo verbatim. `update_media_buy` should merge new targeting overlays without dropping prior refs.
+
+**State transition: `pending_creatives → pending_start / active`.** When `update_media_buy` attaches `creative_assignments` to a buy in `pending_creatives` status, the buy MUST advance: `pending_start` if `start_time` is in the future, `active` if `start_time` is now or past. See the `updateMediaBuy` state-machine logic in `../SKILL.md` § update_media_buy.
 
 **Task envelope — when IO signing is required.** Use `registerAdcpTaskTool` from `@adcp/sdk/server` so `tasks/get` returns the completion artifact:
 

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

@@ -233,14 +233,93 @@ 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: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. (See exceptions below — four codes are technically `correctable` but operator-semantically human-escalate.) |
 | `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. |
 
+> **⚠️ Four codes are technically `correctable` but operator-semantically human-escalate. Don't auto-tweak.**
+>
+> - **`POLICY_VIOLATION`** — buyer's content/targeting violates seller policy. Auto-mutating creative or targeting and resubmitting **looks like evasion** to the seller's governance reviewer. Surface to a human.
+> - **`COMPLIANCE_UNSATISFIED`** — required disclosure can't be satisfied by the chosen format. Auto-relaxing the compliance section IS the compliance failure. Surface to a human.
+> - **`GOVERNANCE_DENIED`** — registered governance agent rejected the spend. Auto-shrinking budget and retrying looks like governance evasion. Surface to the plan operator.
+> - **`AUTH_REQUIRED`** — conflates missing creds (genuinely correctable) with revoked / expired creds (operator must rotate). Until [adcontextprotocol/adcp#3730](https://github.com/adcontextprotocol/adcp/issues/3730) splits this into `auth_missing` + `auth_invalid`, treat as escalate-after-one-attempt.
+>
+> Spec recovery on these is `correctable`; operator behavior is human-in-loop. The pattern: read `error.message` + `error.suggestion`, surface to the user, **don't loop**.
+
+### Operationalize the recovery rules — `decideRetry`
+
+`@adcp/sdk` exports `decideRetry(error, ctx?)` which encodes the operator-grade defaults from the table above plus this section. It returns a discriminated `RetryDecision` so the type system enforces the same-vs-fresh `idempotency_key` rule:
+
+```typescript
+import { decideRetry } from '@adcp/sdk';
+import { randomUUID } from 'node:crypto';
+
+async function callWithRetry(toolName: string, params: Record<string, unknown>): Promise<unknown> {
+  let attempt = 1;
+  let idempotencyKey = randomUUID();
+
+  while (true) {
+    try {
+      return await agent.call(toolName, { ...params, idempotency_key: idempotencyKey });
+    } catch (e) {
+      const error = extractAdcpError(e); // your SDK's error extractor
+      if (!error) throw e; // not an AdCP-shaped failure — let it bubble
+
+      const decision = decideRetry(error, { attempt });
+
+      if (decision.action === 'retry') {
+        // Server-side transient (RATE_LIMITED, SERVICE_UNAVAILABLE, CONFLICT).
+        // Replay with the SAME idempotency_key after the suggested delay.
+        await sleep(decision.delayMs);
+        attempt++;
+        continue;
+      }
+
+      if (decision.action === 'mutate-and-retry') {
+        // Buyer-fixable. Apply the seller's correction (decision.field /
+        // decision.suggestion) and mint a FRESH idempotency_key — payload
+        // changed, so the seller's replay-window must NOT dedupe.
+        params = applyCorrection(params, error, decision); // your domain logic
+        idempotencyKey = randomUUID();
+        await sleep(decision.delayMs); // small jitter (~125-250ms by default)
+        attempt++;
+        continue;
+      }
+
+      // 'escalate' — stop the loop and surface to a human. Includes
+      // commercial-relationship signals (POLICY_VIOLATION etc.), auth
+      // failures, IDEMPOTENCY_EXPIRED (do a natural-key check first!),
+      // attempt-cap exhaustion, and unknown vendor codes.
+      throw new EscalationRequired(decision.reason, decision.message);
+    }
+  }
+}
+```
+
+The discriminated union means TypeScript narrows correctly in each branch — `decision.delayMs` is only available on retry/mutate-and-retry, `decision.field` only on mutate-and-retry, `decision.message` only on escalate.
+
+For per-vertical overrides (e.g., a creative-template platform that legitimately auto-fixes `CREATIVE_REJECTED` format mismatches), instantiate `BuyerRetryPolicy` directly:
+
+```typescript
+import { BuyerRetryPolicy } from '@adcp/sdk';
+
+const policy = new BuyerRetryPolicy({
+  overrides: {
+    CREATIVE_REJECTED: (error) => {
+      if (error.field === 'creative.format' && /unsupported_format/.test(error.message)) {
+        return { action: 'mutate-and-retry', delayMs: 0, attemptCap: 2, sameIdempotencyKey: false, reason: 'capability' };
+      }
+      return null; // fall through to default (escalate as commercial)
+    },
+  },
+});
+
+const decision = policy.decide(error, { attempt });
+```
+
+Default policy is intentionally conservative — see the source comments in `src/lib/utils/buyer-retry-policy.ts` for per-code reasoning.
+
 If your symptom isn't here, fall through to the next section.
 
 ## If you get stuck