@adcp/sdk 17.0.0-beta.0 → 17.0.0-beta.2

package/dist/lib/webhooks/media-buy-delivery.mjs

@@ -0,0 +1,94 @@
+import { TextDecoder } from "node:util";
+import { assertAccountChangeJsonSize } from "../client/account-change-json.mjs";
+import { ConfigurationError } from "../errors/index.mjs";
+import { isPre31AdcpVersion, resolveAdcpVersion } from "../utils/adcp-version-config.mjs";
+import { getMediaBuyDeliveryEnvelopeValidator, getSchemaValidatorByRef } from "../validation/schema-loader.mjs";
+const MAX_BODY_BYTES = 16 * 1024 * 1024;
+const ENVELOPE_FIELDS = ["result", "task_type", "task_id", "operation_id", "idempotency_key", "timestamp"];
+function prepareMediaBuyDeliveryWebhookValidation(version) {
+  const adcpVersion = resolveAdcpVersion(version);
+  const validateEnvelope = getMediaBuyDeliveryEnvelopeValidator(adcpVersion);
+  const validateResult = getSchemaValidatorByRef(
+    isPre31AdcpVersion(adcpVersion) ? "media-buy/get-media-buy-delivery-response.json" : "media-buy/media-buy-delivery-webhook-result.json",
+    adcpVersion
+  );
+  if (!validateEnvelope || !validateResult) {
+    throw new ConfigurationError("Bundled delivery webhook schemas are unavailable.", "adcpVersion");
+  }
+  return { adcpVersion, validateEnvelope, validateResult };
+}
+function parseMediaBuyDeliveryWebhook(body, options = {}) {
+  const { adcpVersion, validateEnvelope, validateResult } = prepareMediaBuyDeliveryWebhookValidation(
+    options.adcpVersion
+  );
+  let parsed;
+  try {
+    if (typeof body === "string" || body instanceof Uint8Array) {
+      if ((typeof body === "string" ? Buffer.byteLength(body) : body.byteLength) > MAX_BODY_BYTES) {
+        throw new Error("Body is too large");
+      }
+      parsed = JSON.parse(
+        typeof body === "string" ? body : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body)
+      );
+    } else {
+      parsed = body;
+    }
+    assertAccountChangeJsonSize(parsed, MAX_BODY_BYTES);
+    parsed = structuredClone(parsed);
+  } catch {
+    return failure("webhook_envelope_invalid", [
+      "Webhook body must be valid JSON within 16 MiB and 64 nesting levels."
+    ]);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return failure("webhook_envelope_invalid", ["Webhook body must be an object."]);
+  }
+  const envelope = parsed;
+  const bare = Object.hasOwn(envelope, "media_buy_deliveries") && !ENVELOPE_FIELDS.some((field) => Object.hasOwn(envelope, field));
+  if (bare && options.acceptBareDeliveryReport !== true) {
+    return failure("webhook_unsupported_payload", [
+      "Bare delivery reports require acceptBareDeliveryReport: true; the default expects an MCP envelope with result."
+    ]);
+  }
+  if (!bare) {
+    if (typeof envelope.task_type === "string" && envelope.task_type !== "media_buy_delivery") {
+      return failure("webhook_unsupported_payload", ["task_type must be media_buy_delivery."]);
+    }
+    if (!validateEnvelope(envelope)) return failure("webhook_envelope_invalid", diagnostics(validateEnvelope.errors));
+  }
+  const result = bare ? envelope : envelope.result;
+  if (!validateResult(result))
+    return failure("webhook_result_invalid", diagnostics(validateResult.errors, bare ? "" : "result"));
+  if (bare)
+    return { ok: true, wireFormat: "bare_delivery_report", adcpVersion, result };
+  return {
+    ok: true,
+    wireFormat: "mcp_envelope",
+    adcpVersion,
+    envelope,
+    result
+  };
+}
+function failure(code, errors) {
+  return { ok: false, code, message: errors.join("; "), errors };
+}
+function diagnostics(errors, prefix = "") {
+  if (!errors?.length) return [`${prefix || "body"} is invalid`];
+  return errors.slice(0, 20).map((error) => {
+    const fields = error.instancePath.split("/").slice(1).map((field) => field.replace(/~1/g, "/").replace(/~0/g, "~"));
+    if (error.keyword === "required" && typeof error.params.missingProperty === "string")
+      fields.push(error.params.missingProperty);
+    if (error.keyword === "additionalProperties" && typeof error.params.additionalProperty === "string")
+      fields.push(error.params.additionalProperty);
+    let path = prefix;
+    for (const field of fields) {
+      const bounded = field.length > 80 ? field.slice(0, 80) + "\u2026" : field;
+      path += /^(0|[1-9][0-9]*)$/.test(bounded) ? `[${bounded}]` : /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(bounded) ? `${path ? "." : ""}${bounded}` : `[${JSON.stringify(bounded)}]`;
+    }
+    return `${path || "body"} ${error.keyword === "required" ? "is required" : error.message ?? "is invalid"}`;
+  });
+}
+export {
+  parseMediaBuyDeliveryWebhook,
+  prepareMediaBuyDeliveryWebhookValidation
+};

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-25
-> @adcp/sdk v17.0.0-beta.0
+> Generated at: 2026-10-27
+> @adcp/sdk v17.0.0-beta.2
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/guides/COLLECTION-FIXTURE-FOUNDATION.md

@@ -562,6 +562,17 @@ guarantees:
   retain their host-owned identity. A drift refusal after contact cannot undo
   earlier calls; their evidence goes only to the private audit sink.
 
+  After authorization and capability discovery, preparation evaluates the same
+  root `requires_capability`, `requires_all_capabilities`, `required_any_of_tools`,
+  and `required_tools` applicability gates as execution. `required_tools` accepts
+  any listed tool; every `required_any_of_tools` family must have a match.
+  Routed preparation unions advertised tools across routes. Root capability
+  predicates belong to `default_agent` when set; otherwise each selected step
+  route is evaluated separately, and preparation skips only when all decline.
+  Unmet gates return `status: 'unsupported', reason: 'not_applicable'` with a
+  discovery phase before any catalog read or controller seeding. Hosts can pass
+  the preparation authorizer directly without doing their own discovery first.
+
   The existing `PreparedFixturesLookup.binding` stays required and its gate
   union stays `run | pass | step`. Existing reuse authorizers need no migration.
   A host can explicitly share one implementation between the two options:

package/docs/guides/DELIVERY-WEBHOOK-PARSING.md

@@ -0,0 +1,142 @@
+# Parsing media-buy delivery webhooks
+
+Use `parseMediaBuyDeliveryWebhook` from `@adcp/sdk/webhooks` after your receiver
+has authenticated the original HTTP body and enforced replay protection. It
+validates delivery content without requiring an `AgentClient`, an SDK callback
+registry, or a signature-verification strategy. It performs no authentication
+itself; `ok: true` means the payload is valid, not that its sender is trusted.
+
+```typescript
+import { parseMediaBuyDeliveryWebhook } from '@adcp/sdk/webhooks';
+
+// Call only after signature verification. Load the version from the registered
+// seller/buy record, rather than trusting a version claim in the request body.
+function parseAuthenticatedDelivery(verifiedRawBody: Uint8Array, negotiatedVersion: string) {
+  const parsed = parseMediaBuyDeliveryWebhook(verifiedRawBody, {
+    adcpVersion: negotiatedVersion,
+  });
+  if (!parsed.ok) {
+    // Suitable for a 400 response: paths are readable and omit report values (map key names can appear in paths).
+    // e.g. result.media_buy_deliveries[0].by_package is required
+    return { status: 400, error: parsed.message, errors: parsed.errors };
+  }
+  return { status: 200, report: parsed.result };
+}
+```
+
+Pass the exact bytes you authenticated to avoid parsing a different body from
+JSON middleware. The parser also accepts a parsed JSON object or a JSON string. It returns
+a detached copy of validated data and preserves the seller's fields. It does
+not add a task status, operation ID, currency, package breakdown, or other
+missing data. Bodies are limited to 16 MiB and 64 nesting levels before schema
+validation. Schema diagnostics use fail-fast validation and readable paths.
+Invalid bodies return one of:
+
+| Code | Meaning |
+| --- | --- |
+| `webhook_envelope_invalid` | Malformed JSON, invalid envelope metadata, or a missing result. |
+| `webhook_result_invalid` | The nested delivery report fails the selected release's schema. |
+| `webhook_unsupported_payload` | Another task type, or an unenveloped report without explicit opt-in. |
+
+An invalid or unbundled `adcpVersion` is a caller configuration error and throws
+`ConfigurationError`. Omission selects the SDK's protocol pin. The body does not
+select its own validation release.
+
+## Select the release used for the buy
+
+A reporting webhook does not provide a trustworthy negotiated-version field.
+Keep that release with the callback/buy registration and supply it for every
+report. Stable patch pins select their bundled minor contract; preview pins
+remain exact.
+
+| Release | Report validation | Envelope details |
+| --- | --- | --- |
+| 3.0 | `get-media-buy-delivery-response.json`; report-wide currency is required. | `operation_id` is optional and remains absent when omitted. The parser accepts the documented `media_buy_delivery` discriminator even though the old task enum omits it. |
+| 3.1 | `media-buy-delivery-webhook-result.json`; report-wide currency is required. | `operation_id` is required. |
+| 3.2 | Dedicated webhook-result schema; report-wide currency is optional. | `operation_id` is required. |
+| 3.3 beta | Exact bundled beta webhook-result schema; report-wide currency is optional. | `operation_id` is required. |
+
+All releases require `by_package` on each delivery row. The SDK's schema loader
+handles both relative and absolute schema IDs. No external `$ref` traversal or
+network fetch is needed.
+
+The registered reporting-delivery branch of `verifyAndParseWebhook` uses this
+same parser after authentication. Its new `adcpVersion` request option selects
+the stored seller/buy release; omission retains the client's configured pin.
+This option changes payload validation only, not signature policy or trusted
+sender/route selection. Schema configuration is prepared before nonce consumption;
+invalid receiver configuration returns `webhook_verification_unavailable`.
+Routing `metadata.operationId` always comes from the trusted registration;
+the seller's original `operation_id` remains in the envelope. Existing legacy task-webhook normalization remains a
+separate compatibility path.
+
+## Bare-report compatibility is explicit
+
+The default rejects a body with top-level `media_buy_deliveries` and no MCP
+envelope. For a temporary migration, opt in explicitly:
+
+```typescript
+const parsed = parseMediaBuyDeliveryWebhook(verifiedRawBody, {
+  adcpVersion: savedBuy.adcpVersion,
+  acceptBareDeliveryReport: true,
+});
+if (parsed.ok && parsed.wireFormat === 'bare_delivery_report') {
+  // Record the seller's protocol violation and repair its callback format.
+  // parsed.envelope is undefined; no transport identity has been invented.
+}
+```
+
+The report still undergoes release-specific validation. A poll-shaped report
+with only a task `status` and no envelope identity is also bare; any such field
+is preserved when the selected report schema permits it. An incomplete or invalid
+envelope never falls back to bare-report acceptance. A normal envelope returns
+`wireFormat: 'mcp_envelope'` and the validated `envelope`. Authentication and
+sender, account, media-buy authorization, and deduplication remain the receiver's
+responsibility in either format.
+
+## A shared delivery body for polling and pushing
+
+`MediaBuyDeliveryReport` imports from `@adcp/sdk/types` or `@adcp/sdk/webhooks`.
+`MediaBuyDeliveryReportSchema` imports from `@adcp/sdk/schemas` and
+`@adcp/sdk/schemas/browser`. This payload-only shape accepts a polled report or a
+webhook result without requiring a task-level `status`. The shared TypeScript type and these Zod schemas describe
+the SDK's current pin; use the parser above for older release-specific checks.
+
+`GetMediaBuyDeliveryResponseSchema` still requires task status through its
+referenced `core/protocol-envelope.json`. The absence of `status` from the
+response document's own `required` list does not remove that inherited
+requirement. Use the shared body schema for ingestion, and the full response
+schema for a poll's protocol envelope. `MediaBuyDeliveryWebhookResultSchema`
+now retains the canonical required row fields, including `by_package`.
+
+## Envelope status and notification type are independent
+
+The parser accepts the selected release's task-status enum; it does not require
+`completed` for all reporting messages. For example, `notification_type:
+'delayed'` may accompany `status: 'working'` when a valid report is present.
+`delayed` itself is not a task status. A progress-only message without a report
+is not a delivery-data webhook.
+
+`notification_type: 'final'` concerns report scheduling; envelope `completed`
+does not mean the media buy has finished. Per-buy state remains in
+`media_buy_deliveries[].status`. This follows the protocol's
+[envelope/result distinction](https://github.com/adcontextprotocol/adcp/blob/v3.3.0-beta.0/docs/building/by-layer/L3/webhooks.mdx#payload-anatomy-envelope-vs-result).
+
+The protocol also requires receivers to ignore `aggregated_totals` in pushed
+reports as an authority source. The parser preserves that field for auditing
+when supplied; reconcile authoritative totals through a poll or per-delivery
+rows instead.
+
+For offline tooling that needs all raw JSON Schema diagnostics,
+`@adcp/sdk/schemas` also exports `getSchemaValidatorByRef`. Its default is
+fail-fast; complete diagnostics are an explicit option:
+
+```typescript
+import { getSchemaValidatorByRef } from '@adcp/sdk/schemas';
+const validate = getSchemaValidatorByRef(
+  'media-buy/media-buy-delivery-webhook-result.json',
+  '3.1',
+  undefined,
+  { allErrors: true },
+);
+```

package/docs/guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md

@@ -115,7 +115,18 @@ const client = new AgentClient(seller, {
 
 The partition is local configuration. It is hashed into MCP connection, discovery, and signing-policy cache keys and never sent in headers or tool arguments. Keep it stable for the same authorization scope, and use distinct values for different principals even when they share a seller token. Partitions also separate sessions within a single `withMCPConnectionScope` workflow.
 
-Outside a connection scope, calls now open and close their own MCP sessions by default. To retain process-wide reuse, provide a nonempty `connectionPartition`, or set `transport: { connectionReuse: 'process' }` when every caller with the same credentials and routing headers represents one principal. A supplied `trustedFetchFn` continues to use one-shot sessions outside an explicit scope, including with a partition or process opt-in.
+Outside a connection scope, calls now open and close their own MCP sessions by default. To retain process-wide reuse, provide a nonempty `connectionPartition`, or set `transport: { connectionReuse: 'process' }` when every caller with the same credentials and routing headers represents one principal. Low-level calls with a supplied `trustedFetchFn` continue to use one-shot sessions outside a scope, including with a partition or process opt-in.
+
+High-level `SingleAgentClient` task and discovery methods create a scope for
+one operation when the caller has not configured reuse. Endpoint discovery,
+`tools/list`, capability preflight, and dispatch share that operation's sessions,
+which close when it finishes. Caller-owned scopes and explicit process reuse
+keep their existing lifetimes. A supplied `trustedFetchFn` shares sessions
+within this operation scope, including when a principal partition is set;
+it never enables process-wide session reuse. A cold legacy endpoint still needs one v2 era
+classification handshake and one v1 Tasks-capable session; the credential- and
+policy-scoped classification is cached for five minutes, so later operations
+can go straight to their v1 session. Different credentials remain isolated.
 
 Successful calls and ordinary errors terminate one-shot sessions. When a call throws because it was cancelled or timed out, the SDK closes its client without sending DELETE, so it does not terminate work still running on the seller; remaining server session state follows the seller's TTL.
 
@@ -162,6 +173,21 @@ Await every operation before the scope callback returns; the callback owns the s
 
 Inside a scope the endpoint probe, capability discovery, `tools/list` and tool calls share one negotiated session per identity. `closeScopedConnections()` closes the current MCP scope's sessions early and does nothing when no MCP scope is active (A2A connections are not scoped). Nested `withMCPConnectionScope` calls join the outer scope unless you pass `{ isolate: true }`.
 
+An implicit high-level task scope closes local transports without sending session
+`DELETE` when its final result is accepted `submitted`, `working`, `input-required`,
+`auth-required`, or `deferred` work. (`deferred` is a task/HITL result, not an MCP
+wire status.) The owning task's final result decides; an earlier nested result
+cannot change a completed owner's cleanup. Completed tasks keep normal session
+termination.
+
+An explicit `withMCPConnectionScope` workflow remains caller-owned: its final
+cleanup terminates its sessions even if a call inside returned `submitted` or
+`working`. End that callback only when you intend to relinquish those sessions.
+Implicit preservation means avoiding termination, not retaining a connection for
+resumption: local clients are closed and evicted, later calls open fresh sessions,
+and the seller owns expiration of its retained sessions. A preserved implicit
+scope can include discovery sessions as well as the dispatch session.
+
 ### One exception: the first legacy handoff
 
 For a seller on the pre-2026 MCP protocol era, the SDK negotiates with the v2 client first and then hands the call to the v1 client so 2025 Tasks keep working. That handoff is a cold cost the SDK cannot avoid: the first scope against such a seller opens one classification handshake plus one shared v1 session. Within the scope everything after that (probe aside) shares the v1 session, including `tools/list`, and the classification is remembered across scopes for five minutes, so a later scope opens only its own session. Modern-era sellers need a single negotiation per scope.

package/docs/guides/REPORTING-LEDGER.md

@@ -116,6 +116,99 @@ returned `sourceScope`, then applies the source contract and existing ledger
 immutability checks. Return the resulting secret-free configuration state from
 your `sync_accounts` implementation.
 
+### Reporting history before installation
+
+Trusted host code can grant an account reporting history independently of when
+its configuration was installed. Supply the entitlement in the install context,
+then extend it when the account upgrades:
+
+```ts
+const installed = await reporting.installConfiguration(declaration, {
+  account: ctx.account,
+  historyStart: accountEntitlement.historyStart, // ISO instant from trusted commercial state
+});
+
+await reporting.extendConfigurationHistory({
+  configurationId: installed.configurationId,
+  historyStart: upgradedEntitlement.historyStart,
+});
+
+await reporting.runCycle({
+  accountId: ctx.account.id,
+  maxHistorySlicesPerSource: 5,
+});
+```
+
+Without `historyStart`, ownership still starts at the first scheduled boundary
+at or after `max(anchor, installedAt)`. With it, ownership starts at the first
+boundary **at or after the requested instant**, even when that boundary predates
+the anchor. Source-calendar days use source-local boundaries, including 23- and
+25-hour days. The entire historical span is validated against the source's
+window bounds and calendar rules before ownership is accepted.
+
+The requested instant must fall within the source offering's rolling
+`retentionDays` window (`now - retentionDays * 24 hours`) and must not be in the
+future. Out-of-range requests are refused, never silently clamped. Instants
+require a timezone and at most millisecond precision. Extension can move the
+aligned boundary earlier or leave it unchanged; it cannot move it later.
+An unchanged replay remains valid as source retention advances.
+
+History changes preserve the configuration ID, version, semantic fingerprint,
+real `installedAt`, frozen calendar rules, and existing obligations and
+publications. Reinstalling without a history option returns the current stored
+ownership. A repeated install requesting a later history start also keeps the
+already owned earlier range, so rolling entitlement timestamps do not shrink
+ownership or break replay. Use `extendConfigurationHistory` for an earlier
+boundary. On a successor version, omit `historyStart`; extend the earliest
+relevant stored generation separately when the entitlement grows. History cannot overlap
+another generation's owned periods: extend the earliest relevant generation to
+recover periods before a successor's handoff. Coverage and status count the
+entire continuous owned range, so unplanned closed history counts as a coverage
+gap just like missing live obligations. Run a cycle after install or extension
+to populate it. Public deadlines remain tied to the historical period:
+unpublished periods past their public recovery deadline report `action_required`
+/ `REPORT_OVERDUE`, including period status notifications, until publication
+satisfies them. Recent historical periods retain the normal waiting/delayed
+progression. The private retry
+window controls execution retries and does not postpone buyer-visible deadlines.
+Pausing history intentionally leaves those obligations outstanding. Source
+retention is checked when history is granted; delayed execution may age beyond
+the source's availability, so schedule the oldest slices promptly and leave
+headroom when choosing entitlement boundaries.
+
+Planning visits live periods across all configurations before history. Execution
+also claims live work first, including when history is already queued. Each
+worker pass executes at most `maxHistorySlicesPerSource` historical claims per
+source offering, defaulting to **10**; zero pauses history execution. The same
+option is accepted by `start()`. The optional
+`maxHistoryObligationsPerSource` limits historical planning; by default history
+shares the existing `maxObligations` cap (1,000). Zero pauses historical planning.
+Fully plan historical ownership before a tzdb/ICU runtime upgrade, or retain
+a worker with the generation's pinned runtime rules until planning is complete;
+frozen calendar ownership cannot be silently reinterpreted after an upgrade.
+Both budgets include retries, where applicable, and are shared by configurations
+using the same offering within that pass. Scheduler budgets apply to each
+account cycle, and concurrent workers have separate budgets. The adapter or host
+must coordinate any shared upstream API quota across accounts and workers using
+the source's `rateLimitConstraints`; these limits do not implement a distributed
+rate limiter. Initial history requests use the source contract's `backfill`
+trigger; retries use `retry` and receive a durable private retry window from the
+first execution attempt while public deadlines remain period-based.
+
+The low-level producer accepts `installConfiguration(input, { historyStart })`
+and exposes the same extension method. A custom ledger store must persist
+`historyStart` and `historyStartOrdinal`, implement atomic
+`extendConfigurationHistory`, enforce newly owned range overlap checks atomically
+at both install and extension, and honor live priority and
+`excludeHistoryOfferingIds` in `claimObligation`. PostgreSQL supplies these
+operations; reapply `REPORTING_LEDGER_MIGRATION` to add its nullable
+`history_start` audit column (mirroring the configuration JSON) and live-priority
+claim indexes before upgrading the workers. Existing rows retain their original
+ownership. Grant or extend history only after every worker has been upgraded;
+older workers cannot honor the new retry windows and pacing contract. For long feeds using the inline source executor, configure
+`inlineReplayRetention` or supply a durable executor so a year of history does
+not exhaust its default 100-slice lifetime scope limit.
+
 For tenant-partitioned jobs, call `runCycle({ accountId })`, or configure
 `start({ accountIds: [...] })`. Every planner and worker call receives that
 same account boundary. A deployment-owned worker must explicitly pass

package/docs/guides/REPORTING-STABILITY.md

@@ -21,7 +21,7 @@ This follows how the AdCP protocol treats experimental surfaces (`x-status: expe
 
 **The storage interfaces in `@adcp/sdk`.** The contract the package implements stays in the SDK, and it changes together with the package, so it is experimental too: the store, transaction, lease, row-read and revision-metadata interfaces in `@adcp/sdk/reporting/ledger` (`ReportingLedgerStore` and the types it uses), `ReportingReceiptSyncStoreV1`, the store-contract error classes (`ReportingLedgerLeaseLostError`, `ReportingLedgerPeriodRetiredError`, `ReportingLedgerContinuityError`) and the row-storage error types. Their TSDoc carries the `@experimental` tag. A breaking change to one ships as a minor of `@adcp/sdk` together with a matching minor of `@adcp/reporting-storage`, and the changesets say which pair to install.
 
-**Storage-facing building blocks in `@adcp/sdk`.** A few exports exist so a store can be written against public API only, and they are covered by the same policy even where their TSDoc is silent: the schedule, instant and evidence helpers on `@adcp/sdk/reporting/ledger` (`compareReportingInstants`, `reportingPeriodDate`, `reportingPeriodSchedule`, `isFrozenCalendarRulesMismatch`, the receipt and verification evidence guards, `isWellFormedUnicodeString`, `getReportingDeliveryOfferingValidatorV1`), and the scheduler primitives and `REPORTING_MANAGED_DELIVERY_COMPOSITION_V1` on `@adcp/sdk/reporting/service`. Application code should not depend on them.
+**Storage-facing building blocks in `@adcp/sdk`.** A few exports exist so a store can be written against public API only, and they are covered by the same policy even where their TSDoc is silent: the schedule, instant and evidence helpers on `@adcp/sdk/reporting/ledger` (`compareReportingInstants`, `reportingPeriodDate`, `reportingPeriodSchedule`, `isFrozenCalendarRulesMismatch`, `assertReportingLedgerHistoryDoesNotOverlap`, the receipt and verification evidence guards, `isWellFormedUnicodeString`, `getReportingDeliveryOfferingValidatorV1`), and the scheduler primitives and `REPORTING_MANAGED_DELIVERY_COMPOSITION_V1` on `@adcp/sdk/reporting/service`. Application code should not depend on them.
 
 ### Not experimental
 

package/docs/guides/TYPED-CLIENT-TOOLS.md

@@ -0,0 +1,49 @@
+# Typed client tools
+
+`SingleAgentClient` and `AgentClient` expose a camelCase method for every tool
+in the bundled AdCP manifest. Each method uses the normal request validation,
+idempotency-key generation, and per-client version negotiation. `executeTask`
+also has typed request and response mappings for every tool.
+
+```ts
+const result = await client.getTaskStatus({ task_id: sellerTaskId, include_result: true });
+if (result.success) console.log(result.data.status, result.data.result);
+
+const tasks = await client.listTasks({}); // Queries the seller's list_tasks tool.
+```
+
+`getTaskStatus({ task_id })` returns the protocol response inside `TaskResult`.
+The observed task's `status` and `error` remain data: querying a failed or working
+task completes the query without resubmitting or following that task.
+
+For compatibility, `getTaskStatus(taskId)` still returns mapped `TaskInfo`, and
+`listTasks()` with no arguments still lists locally tracked tasks. Use
+`trackTask()` or a submitted result's `waitForCompletion()` to observe completion.
+The object overload calls `get_task_status` directly and requires a seller that
+supports that tool. Use the string overload or task tracking for negotiated
+compatibility with older sellers.
+The typed response preserves the seller's `task_id`; callers should compare it
+with the requested ID. The string overload and completion tracking enforce that
+identity check automatically. Discovery and authorization failures are surfaced
+rather than treated as evidence that only the legacy tool is supported.
+
+SDK polling chooses `get_task_status` when advertised by the seller, falling back
+to `tasks_get` for MCP or `tasks/get` for A2A otherwise.
+
+The supported tools `listCreativeFormats`, `buildCreative`, `listTransformers`,
+`getContentStandards`, `listContentStandards`, `calibrateContent`, and
+`validateContentDelivery` have ordinary typed methods. Their existing `*Legacy`
+aliases remain available. These tool methods return their protocol wire shapes;
+the SDK's canonical creative discovery and delivery helpers remain available too.
+On the SDK 16 line these are the AdCP 3.2 wire shapes, including any legacy
+`format_id` fields the protocol still supports. Generic `preview_creative`
+execution uses the canonical preview helper; use `previewCreativeLegacy` for
+raw named-format requests.
+
+Direct `SingleAgentClient.syncPlans` and `getPlanAuditLogs` calls use the
+configured governance agent when present. Without one, the client requires its
+own agent to advertise the governance tool before sending the request.
+
+`complyTestController` is typed for conformance testing against a seller that
+advertises it. Its availability does not imply that a production seller enables
+test controls.

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-10-25
-> Library: @adcp/sdk v17.0.0-beta.0
+> Generated at: 2026-10-27
+> Library: @adcp/sdk v17.0.0-beta.2
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag.

package/docs/migration-14.x-rc-worksheet.md

@@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball.
 
 | Fact | Value |
 | --- | --- |
-| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.0` |
-| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.0 dist.integrity` |
+| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.2` |
+| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.2 dist.integrity` |
 | Node.js runtime | `^20.19.0 || >=22.12.0` |
 | Default AdCP wire release | `3.3.0-beta.0` |
 | Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.3.0-beta.0`, `3.3-beta.0` |
@@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball.
 For a checkout at the published release commit, install the exact package version:
 
 ```bash
-npm install --save-exact '@adcp/sdk@17.0.0-beta.0'
-npm view '@adcp/sdk@17.0.0-beta.0' dist.integrity
+npm install --save-exact '@adcp/sdk@17.0.0-beta.2'
+npm view '@adcp/sdk@17.0.0-beta.2' dist.integrity
 ```
 
 ### Required and optional peers