@adcp/sdk 15.4.0 → 15.6.0

package/dist/lib/version.js

@@ -31,7 +31,7 @@ __export(version_exports, {
   toReleasePrecisionVersion: () => toReleasePrecisionVersion
 });
 module.exports = __toCommonJS(version_exports);
-const LIBRARY_VERSION = "15.4.0";
+const LIBRARY_VERSION = "15.6.0";
 const ADCP_VERSION = "3.2.3";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -97,10 +97,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.3"
 ];
 const VERSION_INFO = {
-  library: "15.4.0",
+  library: "15.6.0",
   adcp: "3.2.3",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-08T17:53:59.048Z"
+  generatedAt: "2026-10-09T11:44:03.363Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/dist/lib/version.mjs

@@ -1,4 +1,4 @@
-const LIBRARY_VERSION = "15.4.0";
+const LIBRARY_VERSION = "15.6.0";
 const ADCP_VERSION = "3.2.3";
 const ADCP_MAJOR_VERSION = 3;
 const COMPATIBLE_ADCP_VERSIONS = [
@@ -64,10 +64,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
   "3.2.3"
 ];
 const VERSION_INFO = {
-  library: "15.4.0",
+  library: "15.6.0",
   adcp: "3.2.3",
   compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
-  generatedAt: "2026-10-08T17:53:59.048Z"
+  generatedAt: "2026-10-09T11:44:03.363Z"
 };
 function getAdcpVersion() {
   return ADCP_VERSION;

package/docs/README.md

@@ -23,7 +23,7 @@ list_products → buy_products → control_media_buy
 
 Use the [buyer quick start](./guides/BUYER-QUICKSTART-3.2.md). For the complete
 tool and type inventory, use [llms.txt](./llms.txt) and the
-[type summary](./TYPE-SUMMARY.md).
+[type summary](./TYPE-SUMMARY.md). For server-side callers that create a client per request, see [discovery caching and MCP session reuse](./guides/DISCOVERY-CACHE-AND-SESSION-REUSE.md).
 
 ## Upgrade from SDK 14.0
 

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-08
-> @adcp/sdk v15.4.0
+> Generated at: 2026-10-09
+> @adcp/sdk v15.6.0
 
 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`.
 
@@ -56,6 +56,39 @@ interface TransportOptions {
   legacyCompat?: A2ALegacyCompatOptions; // A2A only
 }
 
+// Selected transport observer fields; correlate all events by transportRequestId.
+type TransportActivityType = 'request_started' | 'response_received' | 'response_completed' | 'request_failed';
+type TransportResponseOutcome = 'ended' | 'errored' | 'aborted' | 'cancelled';
+interface TransportActivity {
+  type: TransportActivityType;
+  transportRequestId: string;
+  durationMs?: number; // response_received: time to headers; response_completed: total time
+  streaming?: boolean; // Uncaptured body: terminal observation follows consumption or abort
+  outcome?: TransportResponseOutcome; // response_completed only
+  bytes?: number; // Bytes forwarded before the terminal outcome; no stream payload retained
+}
+
+// Share discovery across request-local clients using an application-owned authorization identity.
+interface AgentDiscoveryCacheConfig {
+  cache: AgentDiscoveryCache; // get / set / delete; synchronous or asynchronous
+  authIdentity: string; // Trusted principal and authorization scope; never a token
+  ttlMs?: number; // Default: five minutes; maximum: 24 hours
+}
+const discoveryCache = createInMemoryAgentDiscoveryCache({ maxEntries: 256 });
+const client = new SingleAgentClient(agentConfig, {
+  discoveryCache: { cache: discoveryCache, authIdentity: 'tenant:buyer-scope', ttlMs: 300_000 },
+});
+// Public from @adcp/sdk, @adcp/sdk/client, and @adcp/sdk/advanced.
+await withMCPConnectionScope(async () => { await client.getCapabilities(); /* ...tool calls... */ });
+// closeScopedConnections() can close the current workflow early.
+interface AgentDiscoverySeed {
+  capabilities: AdcpCapabilities; // Authoritative evidence, never synthetic
+  toolSchemas?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  endpoint?: { agentUri: string; mcpEra?: 'legacy' | 'modern' }; // Same origin, no URL userinfo
+}
+// client.primeDiscoveryCache(seed): Promise<boolean>; also available on AgentClient.
+// client.invalidateDiscoveryCache(): Promise<void>; refresh after a seller change.
+
 interface TaskOptions {
   skipStatusHandlers?: boolean; // Skip inline completion handlers, including continuations
   timeout?: number;             // Absolute whole-task deadline

package/docs/ZOD-SCHEMAS.md

@@ -20,6 +20,18 @@ if (result.success) {
 }
 ```
 
+### Browser / UI bundles
+
+Browser widgets, dashboards, and forms should import runtime validators from `@adcp/sdk/schemas/browser`:
+
+```typescript
+import { EventSourceHealthSchema } from '@adcp/sdk/schemas/browser';
+
+const health = EventSourceHealthSchema.parse(rawHealth);
+```
+
+This entry has no Node built-ins in its import graph and shares the Node entry's portable validators, including canonical and legacy get-products selectors. JSON Schema loading and tool registration helpers are available from `@adcp/sdk/schemas`. Importing one schema can still retain the full generated module; per-schema tree-shaking is tracked in [#3178](https://github.com/adcontextprotocol/adcp-client/issues/3178).
+
 ## Why Zod Schemas?
 
 - ✅ **Runtime validation** - Catch data issues at runtime, not just compile time
@@ -131,7 +143,7 @@ const authority = resolvePreviewAuthority({
 ```typescript
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { CreateMediaBuyRequestSchema } from '@adcp/sdk/schemas';
+import { CreateMediaBuyRequestSchema } from '@adcp/sdk/schemas/browser';
 
 function MediaBuyForm() {
   const { register, handleSubmit } = useForm({

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

@@ -0,0 +1,142 @@
+# Discovery cache and MCP session reuse
+
+A server-side caller that makes one AdCP call per incoming request, building a `SingleAgentClient` (or `AgentClient`) per request because auth, headers or deadlines differ, used to pay for the SDK's whole setup sequence on every call: an endpoint probe, a `tools/list` and a `get_adcp_capabilities`, each on its own MCP session. Against a slow seller that comes straight out of the caller's deadline.
+
+Two independent mechanisms remove that cost:
+
+1. an **opt-in shared discovery cache** so client instances for the same agent and principal reuse one endpoint / `tools/list` / capabilities observation, and
+2. **reusable MCP connections** that per-call correlation headers, `AbortSignal`s and timeouts no longer split, plus a public **connection scope** to run a whole workflow on one session.
+
+## Shared discovery cache
+
+```ts
+import { AgentClient, createInMemoryAgentDiscoveryCache } from '@adcp/sdk';
+
+// One per process (or implement AgentDiscoveryCache over your own store).
+const discoveryCache = createInMemoryAgentDiscoveryCache({ maxEntries: 256 });
+
+function clientFor(request: IncomingRequest) {
+  return new AgentClient(
+    {
+      id: 'seller',
+      name: 'Seller',
+      agent_uri: 'https://seller.example/mcp',
+      protocol: 'mcp',
+      auth_token: request.token,
+    },
+    {
+      discoveryCache: {
+        cache: discoveryCache,
+        authIdentity: request.authorizationScopeId, // principal + tenant + granted permissions
+        ttlMs: 5 * 60_000, // default 5 minutes, max 24 hours
+      },
+    }
+  );
+}
+```
+
+### What is shared, and for how long
+
+An entry holds the endpoint that discovery resolved, the `tools/list` input-schema map and the capabilities from an authoritative `get_adcp_capabilities` response. Every entry carries `observedAt` / `expiresAt`; the SDK enforces the TTL on read, whatever your backend does. A reader also applies its own `ttlMs`, so a short-TTL client cannot inherit a longer writer's freshness window. A long-lived client honors that bound for both endpoints and capabilities in its own in-memory copy.
+
+### Isolation (the part to get right)
+
+The key is a SHA-256 over:
+
+| Input                                                | Why                                                                                                                    |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| agent URL and protocol                               | endpoint identity                                                                                                      |
+| `authIdentity`                                       | **caller-owned** principal. Deliberately _not_ derived from the token: you decide who may share evidence               |
+| credential kind (anonymous, bearer, OAuth or header) | Keeps anonymous and authenticated discovery separate while allowing token rotation                                     |
+| configured `adcpVersion` / `wireAdcpVersion`         | negotiated version                                                                                                     |
+| every non-correlation, non-credential header         | unknown `x-*` tenant / routing / policy headers can select a different upstream view, so they fail closed into the key. This includes `baggage`, **ambient OpenTelemetry baggage included** |
+| request-signing identity and policy                  | `kind`, `kid`, `alg`, agent URL and signing policy; never the private key                                              |
+| effective `allowPrivateIp`, `maxResponseBytes`       | the transport policy the evidence was gathered under (per-call `transport` overrides included)                         |
+
+Not part of the key: correlation headers (`x-request-id`, `x-correlation-id`, `traceparent`, ...), and credential header values (`Authorization`, `x-adcp-auth`) — OAuth and `auth_token` credentials are also owned by `authIdentity`; a token rotation for the same authorization scope keeps the entry. **Choose `authIdentity` at least as narrow as the credential's authorization scope.** Change the identity or invalidate the cache when permissions change or access is revoked; use a distinct identity for anonymous access. Two principals must never share an identity. Keys are hashes and never contain the identity, token or header values.
+
+Never shared:
+
+- **Synthetic capabilities** (a seller with no `get_adcp_capabilities`, or whose capabilities call failed) stay private to the instance that built them.
+- **Scoped `trustedFetchFn` calls** bypass the cache in both directions: their network boundary is per call.
+- Entries are copied in and out, so mutating a returned capabilities object cannot poison the cache.
+
+### Concurrency, cancellation, failures
+
+- Cold concurrent clients for the same key share one in-process discovery: one leader discovers, followers wait for it under **their own** signal and request timeout. A leader that is cancelled or fails never fails its followers; they discover for themselves.
+- A cache backend that throws, returns a malformed entry or hangs costs a rediscovery, never a failed call. Each cache read or mutation wait is bounded by a 2 second deadline and, for reads and automatic writes, by the caller's `AbortSignal`. Mutations of one key are ordered in-process. A timed-out backend mutation retains its place until it settles, so a late writer cannot overwrite or delete a newer seed; later mutation waits also time out while discovery proceeds live. The queue is bounded: a write whose caller already stopped waiting is dropped if it has not started, a full per-key queue refuses further writes (a failed write, never a failed call), and invalidations queued behind a hung delete coalesce into one follow-up delete. Nothing is ever replayed automatically.
+- The shared cache is in-process singleflight. Across processes each cold process still discovers once.
+
+### Invalidation
+
+- `client.invalidateDiscoveryCache()` drops this client's local evidence and the shared entry. `SingleAgentClient.refreshCapabilities()` does the same and re-discovers; on `AgentClient`, call `invalidateDiscoveryCache()` and then `getCapabilities()`.
+- A feature check (`require`, or the pre-flight check before a task) that fails against **shared** evidence invalidates it and re-decides on live capabilities before refusing the call.
+- A seller error of `VERSION_UNSUPPORTED`, `UNSUPPORTED_FEATURE`, `FEATURE_UNSUPPORTED`, `TOOL_NOT_FOUND`, `METHOD_NOT_FOUND` or `UNKNOWN_TOOL` invalidates the shared entry, on every task path including `executeTask()` and the typed methods. Each such live re-check costs one rediscovery; a seller that genuinely lacks a feature pays it on every refused call.
+- A malformed or expired entry is deleted and treated as a miss. An entry older than this reader's shorter TTL is also a miss.
+- Invalidation by any client sharing the cache in this process also drops other instances' local evidence and endpoint for that key (application-owned `primeCapabilities` evidence keeps its own freshness bound). In this process an invalidation leaves a tombstone, so a shared entry observed before it is a miss even when the backend delete failed or is still queued; the tombstone record set is bounded and, once pruned, errs toward a miss. Other processes still rely on the backend delete.
+- In-process invalidation takes precedence over an earlier discovery still in flight. External backends with concurrent writers in other processes must supply their own atomic invalidation/versioning if they need that guarantee across processes.
+
+### Pre-seeding
+
+| Method                | Lifetime                                                       | Result                                              |
+| --------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
+| `primeCapabilities`   | One client, bound to its capability scope                      | Synchronous; `true` if accepted, otherwise `false`  |
+| `primeDiscoveryCache` | Shared cache, bound to explicit authorization identity and TTL | Asynchronous; `true` if accepted, otherwise `false` |
+
+```ts
+const ok = await client.primeDiscoveryCache({
+  capabilities, // authoritative, non-synthetic
+  toolSchemas, // optional when capabilities.discoveredTools is present
+  endpoint: { agentUri: 'https://seller.example/mcp', mcpEra: 'modern' }, // optional
+});
+```
+
+Unlike [`primeCapabilities`](../TYPE-SUMMARY.md) — which stays client-bound and scope-keyed — seeded evidence outlives the instance. It returns `true` only once the backing cache accepted the entry, and `false` (seeding nothing) for synthetic, malformed, uncloneable or foreign-origin evidence. When the cache rejects the write or does not answer within the 2 second deadline, `false` means *not confirmed*, not *empty*: a write already handed to the backend may still land later, while one still queued behind earlier operations is dropped. After such a `false`, seed again or invalidate rather than assuming nothing was stored. Without `endpoint` the first call of a cold client still runs the endpoint probe once.
+
+## Reusable MCP connections
+
+This behavior applies by default, including calls that pass a signal or timeout outside a connection scope. The process-wide legacy/OAuth session cache retains at most 20 connections per cache with LRU eviction and has no idle expiry. For request workflows with many distinct credentials, use a scope to bound session lifetime. At process shutdown, `closeConnections()` from `@adcp/sdk/advanced` closes the process-wide connections.
+
+A reusable session is keyed only by what changes the _connection_: endpoint, credential, tenant / routing headers, signing identity, `allowPrivateIp`, a caller-injected fetch, and the workflow scope. These no longer choose or split a session:
+
+- **Correlation headers**: `traceparent`, `tracestate`, `x-request-id`, `x-correlation-id`, `x-trace-id`, `x-span-id`, `x-debug-id`, `x-client-request-id`, `x-b3-*`, `x-amzn-trace-id`, `x-cloud-trace-context`, `x-datadog-*`, `sentry-trace`, and vendor-prefixed `x-<vendor>-request-id` / `-correlation-id` / `-trace-id` / `-span-id` / `-debug-id`. Names suggesting credentials or tenant/routing identity (including `auth`, `token`, `tenant`, `account`, `workspace`, `seat`, `advertiser`, `publisher`, `buyer` and `seller`) are never treated as correlation. **`baggage` stays in the key**: it can carry tenant or routing members. Any header outside the list above also stays in the key (fail closed).
+- **`AbortSignal`** and **`requestTimeoutMs`**: they bound a call.
+
+Each call still sends _its own_ correlation headers, deadline and cancellation on every request over the shared session (including concurrent calls), through per-call context rather than values frozen at connect time. Explicit caller headers win over ambient OpenTelemetry context.
+
+Isolation properties:
+
+- A cancelled or timed-out call tears down only its own request. It does not evict or terminate a session other calls are using; other failures retire the session and close it once its in-flight calls finish. A session the seller has expired may fail the current call once; the SDK retires that connection and never replays a dispatched call, so a caller must reconcile the outcome of a mutation that failed that way (for example by re-reading it) before retrying with the same `idempotency_key`.
+- A caller that joins another caller's in-flight connect waits under its own signal and timeout. If the creator cancels the connect, the joiner retries for itself, with at most two retries after foreign aborts.
+- A caller-injected `fetchFn` (a per-call network trust boundary) keeps its own one-shot session outside a connection scope; inside a scope its identity is part of the key.
+- Connections are never shared across credentials, tenant headers, signing identities or `allowPrivateIp` settings.
+
+### Public connection scope
+
+```ts
+import { withMCPConnectionScope } from '@adcp/sdk'; // also from '@adcp/sdk/advanced'
+
+await withMCPConnectionScope(async () => {
+  await client.syncAccounts(accounts);
+  await client.getCapabilities();
+  await client.getProducts(brief); // same MCP session
+}); // the session is terminated once, here
+```
+
+Await every operation before the scope callback returns; the callback owns the session lifetime. Open process-wide sessions can keep sockets alive, so close them at shutdown.
+
+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 }`.
+
+### 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.
+
+### Troubleshooting cache misses
+
+Unknown headers participate in identity. A varying header such as `x-forwarded-for` causes a cache miss even when `authIdentity` matches, and so does varying `baggage`, including ambient OpenTelemetry baggage that differs per request. Ambient OpenTelemetry context is not a way to split or merge keys: set the baggage identically for callers that should share evidence, or keep it out of routing. Calls with a scoped `trustedFetchFn` bypass the cache entirely, so a client that always passes one never hits it. Also check version, transport policy, signing policy and TTL before assuming the cache backend failed.
+
+The cache holds capabilities, schemas and the endpoint URL. Endpoint sharing excludes URLs with userinfo, a query string or a fragment; those endpoints stay local while their capabilities and schemas can still be shared. `primeDiscoveryCache` refuses such an endpoint. Put credentials in authentication headers. Treat a custom `AgentDiscoveryCache` backend as trusted storage.
+
+## Related
+
+- [Session reuse for multi-tool workflows](https://github.com/adcontextprotocol/adcp-client/issues/2118).

package/docs/guides/EXISTING-PLATFORM.md

@@ -77,22 +77,53 @@ The submitted continuation's `waitForCompletion` function is deliberately proces
 Do not catch every outcome into a string. Switch on `result.status`; use `result.adcpError` for failed results, and catch thrown cancellation/configuration errors separately. Internal transport retries reuse an idempotency key. A new application intent must receive a new key; after an ambiguous timeout, reconcile by the persisted natural key before deciding to retry.
 
 Transport diagnostics never delay delivery of the operational `Response`.
-SSE, non-text, and explicitly over-limit bodies are not cloned; their single
-response event is emitted immediately with `responseBodyTruncated: true`. Other
-diagnostic text bodies, including chunked responses without `Content-Length`
-and responses with an invalid length, are cloned synchronously and captured in
-the background up to 64 KiB for at most `BODY_SNIPPET_TIMEOUT_MS` (currently 1
-second). Their single response event is emitted when capture completes,
-truncates, or expires, while the original response stream remains exclusively
-available to the protocol client. The enclosing task then waits within
+Each request emits `request_started`, then `response_received`, then (for
+streamed replies) `response_completed`. `response_received` means **response
+headers arrived**: its `durationMs` is time to headers. For an MCP server that
+answers over `text/event-stream`, that is not the end of the reply, so do not
+record it as a finished call.
+
+Bodies are captured only when they are text-like and declare a finite
+`Content-Length` of at most 64 KiB. Those are cloned synchronously and read in
+the background for at most `BODY_SNIPPET_TIMEOUT_MS` (currently 1 second), and
+their single `response_received` event is emitted when capture completes,
+truncates, or expires. The enclosing task then waits within
 `OBSERVER_FLUSH_TIMEOUT_MS` for that event's asynchronous observer, so
-short-lived processes do not lose the final audit record. Observer
-failures remain isolated. Applications should synchronously enqueue each event into their own
-bounded in-memory or durable queue and return promptly; flushing that queue is
-an application lifecycle concern.
+short-lived processes do not lose the final audit record.
+
+Every other body is never cloned or buffered: SSE, non-text content, chunked
+responses or responses with a missing or invalid `Content-Length`, and bodies
+declared over the limit. Their `response_received` event is emitted
+immediately with `responseBodyTruncated: true` and, when the body can be observed, `streaming: true`; `streaming` is the signal that a `response_completed` event will follow. The body
+is passed through an observing stream with the same bytes, status, headers,
+`url`, `redirected`, and `type`, and with pull-driven backpressure. When the
+caller finishes with it, exactly one `response_completed` event reports
+`outcome`, total `bytes`, and `durationMs` measured from `startedAt`:
+
+| `outcome`   | Meaning                                                                    |
+| ----------- | -------------------------------------------------------------------------- |
+| `ended`     | The caller read the stream to EOF.                                         |
+| `errored`   | The stream failed (`errorName` / sanitized `errorMessage` are set).        |
+| `aborted`   | The request's `AbortSignal` fired (also when the body is cancelled after it fired), or the stream failed with an abort error. |
+| `cancelled` | The consumer cancelled the body, including SDK cleanup after delivering a successful MCP result. |
+
+A streamed call that never answers therefore shows `response_received` with no
+matching `response_completed` until the caller aborts it (for example, when its
+deadline fires an `AbortSignal` on the request), then an `aborted` completion. `response_completed` is fire-and-forget: it can arrive
+after the diagnostics scope exits, the scope never waits for it, and a body
+that is never read or aborted never emits one. It carries the request correlation
+fields, `httpStatus`, and `statusText`, but no request or response bodies and no
+response headers. The SDK does not parse SSE messages, so it cannot say whether
+a stream carried a final result.
+
+Observer failures remain isolated. Applications should synchronously enqueue
+each event into their own bounded in-memory or durable queue and return
+promptly; flushing that queue is an application lifecycle concern.
 
 ## Reuse scoped capability evidence
 
+For evidence shared across separate client instances, use the opt-in [discovery cache](./DISCOVERY-CACHE-AND-SESSION-REUSE.md). That guide also covers MCP connection scopes and per-call session reuse.
+
 An application factory that already performs a bounded seller preflight can
 construct and prime the specific client instance before exposing it for task
 dispatch:

package/docs/guides/OAUTH-ISSUER-BINDING.md

@@ -38,6 +38,12 @@ stage DCR privately and reconstruct for callback. Applications provide ownership
 and atomic generation replacement. No distributed refresh coordination,
 grant/client CAS or spent-grant cancellation: quiesce background callers for recovery.
 
+Pending flows written by an older store that omitted `authorizationServerIssuer`
+fail at callback with `oauth_issuer_required` and must restart sign-in. The SDK parser
+can read these legacy rows, but cannot recreate their historical issuer trust.
+Use the shared serializer and run `assertPendingWebFlowStoreRoundTrip` in CI to
+catch dropped fields on upgrade; see [Web OAuth storage](WEB-OAUTH.md#storage-and-errors).
+
 Custom providers must preserve issuer in getters/saves. Upstream
 `ClientCredentialsProvider`, `PrivateKeyJwtProvider`, `StaticPrivateKeyJwtProvider`,
 `CrossAppAccessProvider` need independent `expectedIssuer`. Direct exchange/refresh