@adcp/sdk 6.5.0 → 6.7.0

package/dist/lib/server/create-adcp-server.js

@@ -36,7 +36,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADCP_SIGNED_REQUESTS_STATE = exports.ADCP_PRE_TRANSPORT = void 0;
+exports.ADCP_INSTRUCTIONS_FN = exports.ADCP_SIGNED_REQUESTS_STATE = exports.ADCP_PRE_TRANSPORT = void 0;
 exports.requireSessionKey = requireSessionKey;
 exports.createAdcpServer = createAdcpServer;
 const zod_1 = require("zod");
@@ -47,6 +47,9 @@ const protocols_1 = require("../protocols");
 const adcp_server_1 = require("./adcp-server");
 const tasks_1 = require("./tasks");
 const errors_1 = require("./errors");
+const errors_2 = require("../errors");
+const async_outcome_1 = require("./decisioning/async-outcome");
+const redact_1 = require("./redact");
 const envelope_allowlist_1 = require("./envelope-allowlist");
 const state_store_1 = require("./state-store");
 const responses_1 = require("./responses");
@@ -139,6 +142,17 @@ exports.ADCP_PRE_TRANSPORT = Symbol.for('@adcp/client.preTransport');
  * tests or boot diagnostics.
  */
 exports.ADCP_SIGNED_REQUESTS_STATE = Symbol.for('@adcp/client.signedRequestsState');
+/**
+ * Symbol marking that a server's `instructions` was supplied as a function
+ * (lazy / per-session form) rather than a static string. `serve()` reads
+ * this to refuse `reuseAgent: true` — the function is captured once at
+ * construction and would not re-evaluate per session under server reuse.
+ *
+ * Internal contract between `createAdcpServer` and `serve()`. Adopters
+ * who instantiate `McpServer` directly (without `createAdcpServer`) and
+ * want their own marker semantics should not import this symbol.
+ */
+exports.ADCP_INSTRUCTIONS_FN = Symbol.for('@adcp/client.instructionsFn');
 /**
  * Clamp idempotency replay TTL to spec bounds (1h–7d).
  */
@@ -307,6 +321,24 @@ function isErrorResponse(response) {
  * `[object Object]` inside a SERVICE_UNAVAILABLE wrapper — the dispatcher
  * unwraps and returns the envelope directly when the shape matches.
  */
+/**
+ * Project a thrown {@link AdcpError} to the wire envelope. Used by the
+ * account-resolution and tool-handler catch blocks so adopters can throw
+ * typed errors at any depth and have the framework project the structured
+ * fields verbatim — without coercion to `SERVICE_UNAVAILABLE`. Mirrors the
+ * `isThrownAdcpError` unwrap, but for the in-process class throw rather
+ * than the already-projected envelope throw.
+ */
+function projectThrownAdcpError(err) {
+    return (0, errors_1.adcpError)(err.code, {
+        recovery: err.recovery,
+        message: err.message,
+        ...(err.field !== undefined && { field: err.field }),
+        ...(err.suggestion !== undefined && { suggestion: err.suggestion }),
+        ...(err.retry_after !== undefined && { retry_after: err.retry_after }),
+        ...(err.details !== undefined && { details: err.details }),
+    });
+}
 function isThrownAdcpError(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -431,6 +463,7 @@ const TOOL_META = {
     get_brand_identity: { wrap: null, annotations: RO },
     get_rights: { wrap: null, annotations: RO },
     acquire_rights: { wrap: responses_1.acquireRightsResponse, annotations: MUT },
+    update_rights: { wrap: responses_1.updateRightsResponse, annotations: MUT },
 };
 const MEDIA_BUY_ENTRIES = [
     { handlerKey: 'getProducts', toolName: 'get_products' },
@@ -502,6 +535,7 @@ const BRAND_RIGHTS_ENTRIES = [
     { handlerKey: 'getBrandIdentity', toolName: 'get_brand_identity' },
     { handlerKey: 'getRights', toolName: 'get_rights' },
     { handlerKey: 'acquireRights', toolName: 'acquire_rights' },
+    { handlerKey: 'updateRights', toolName: 'update_rights' },
 ];
 // ---------------------------------------------------------------------------
 // Protocol detection
@@ -1002,7 +1036,7 @@ function buildSupportedVersionsList(capConfig, serverPin) {
  * `get_adcp_capabilities` is auto-generated from registered tools.
  */
 function createAdcpServer(config) {
-    const { name, version, adcpVersion: configuredAdcpVersion, resolveAccount, resolveAccountFromAuth, resolveSessionKey, exposeErrorDetails = process.env.NODE_ENV !== 'production', stateStore = DEFAULT_STATE_STORE, logger = noopLogger, capabilities: capConfig, idempotency: idempotencyConfig, resolveIdempotencyPrincipal, instructions, taskStore, taskMessageQueue, webhooks, signedRequests, validation: validationConfig, testController: testControllerBridge, } = config;
+    const { name, version, adcpVersion: configuredAdcpVersion, resolveAccount, resolveAccountFromAuth, resolveSessionKey, agentRegistry, exposeErrorDetails = process.env.NODE_ENV !== 'production', stateStore = DEFAULT_STATE_STORE, logger = noopLogger, capabilities: capConfig, idempotency: idempotencyConfig, resolveIdempotencyPrincipal, instructions: instructionsOption, onInstructionsError = 'skip', taskStore, taskMessageQueue, webhooks, signedRequests, validation: validationConfig, testController: testControllerBridge, } = config;
     // Resolve `adcpVersion` early — the validator-call closures below capture
     // it by reference and would hit a TDZ ReferenceError if any of them ran
     // synchronously during setup. They don't today (`createAdcpServer`
@@ -1233,10 +1267,62 @@ function createAdcpServer(config) {
     // bound method so per-request code calls `ctx.emitWebhook(...)` without
     // knowing about the emitter's construction or options.
     const webhookEmitter = webhooks ? (0, webhook_emitter_1.createWebhookEmitter)(webhooks) : undefined;
+    // Resolve `instructions` — function form is evaluated at construction.
+    // Under `serve({ reuseAgent: false })` (the default) the factory runs
+    // per HTTP request, so the function fires per session. Under
+    // `reuseAgent: true` the function would fire once and never again —
+    // `serve()` refuses that combination via `ADCP_INSTRUCTIONS_FN`.
+    const instructionsIsFn = typeof instructionsOption === 'function';
+    let resolvedInstructions;
+    if (typeof instructionsOption === 'string') {
+        resolvedInstructions = instructionsOption;
+    }
+    else if (instructionsIsFn) {
+        try {
+            const result = instructionsOption({});
+            // Promise detection — must guard for null + non-object before reading
+            // `.then`, otherwise `typeof null.then` throws TypeError and the user
+            // sees a confusing framework-internal stack instead of their own bug.
+            const isThenable = result !== null && typeof result === 'object' && typeof result.then === 'function';
+            if (isThenable) {
+                throw new errors_2.ConfigurationError('createAdcpServer: function-form `instructions` returned a Promise, but async resolution is not yet ' +
+                    'supported. Pre-resolve before invoking createAdcpServer (e.g., `instructions: await fetchProse()`), ' +
+                    'or wrap your async loader in a sync cache.');
+            }
+            // Reject non-string non-undefined returns instead of silently coercing
+            // (`String({})` → "[object Object]" would ship as instructions otherwise).
+            // The TS signature already constrains return to `string | undefined`;
+            // this catches `as any` escapees and untyped JS callers. Routed through
+            // the same try/catch as user-thrown errors so `onInstructionsError`
+            // governs both — a buggy callback is the same shape of problem either
+            // way (Promise return is the exception: framework can't recover, so
+            // it throws ConfigurationError unconditionally above).
+            if (result !== undefined && typeof result !== 'string') {
+                throw new Error(`function-form \`instructions\` must return string | undefined, got ${result === null ? 'null' : typeof result}. ` +
+                    `Return a string for the prose, or undefined for "no instructions on this session."`);
+            }
+            resolvedInstructions = result;
+        }
+        catch (err) {
+            if (err instanceof errors_2.ConfigurationError)
+                throw err;
+            if (onInstructionsError === 'fail') {
+                throw err;
+            }
+            // 'skip' — log server-side, surface no instructions to MCP `initialize`.
+            logger.warn('[adcp/createAdcpServer] instructions() threw; skipping (onInstructionsError: "skip")', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            resolvedInstructions = undefined;
+        }
+    }
+    else {
+        resolvedInstructions = undefined;
+    }
     const server = (0, tasks_1.createTaskCapableServer)(name, version, {
         taskStore,
         taskMessageQueue,
-        instructions,
+        instructions: resolvedInstructions,
     });
     const registeredToolNames = new Set();
     // Collect all domain handlers into a flat toolName → handler map
@@ -1280,8 +1366,27 @@ function createAdcpServer(config) {
             const wrap = meta?.wrap ?? ((data, summary) => genericResponse(toolName, data, summary));
             const toolHandler = async (params, extra) => {
                 const ctx = { store: stateStore };
-                if (extra?.authInfo)
+                if (extra?.authInfo) {
                     ctx.authInfo = extra.authInfo;
+                    // Hoist the kind-discriminated credential from MCP's `extra`
+                    // shape onto top-level `ctx.authInfo.credential` so adopter
+                    // `resolveAccount` callbacks and the `BuyerAgentRegistry` can
+                    // route on it directly without unpacking `extra`. Stage 3 of
+                    // #1269 — the built-in authenticators stamp this in
+                    // `serve.ts:attachAuthInfo`. Custom `authenticate` callbacks
+                    // that don't populate `credential` see `ctx.authInfo.credential`
+                    // stay undefined; downstream code branches on `credential
+                    // !== undefined` for the new path and falls back to the
+                    // `@deprecated` legacy fields (`token`, `clientId`, `scopes`)
+                    // for the old path. Both paths coexist for two minors.
+                    const authInfo = ctx.authInfo;
+                    if (authInfo !== undefined) {
+                        const inboundCredential = authInfo.extra?.credential;
+                        if (inboundCredential !== undefined && authInfo.credential === undefined) {
+                            authInfo.credential = inboundCredential;
+                        }
+                    }
+                }
                 if (webhookEmitter)
                     ctx.emitWebhook = webhookEmitter.emit.bind(webhookEmitter);
                 // Echo params.context into any response (success or error) so buyers
@@ -1302,6 +1407,107 @@ function createAdcpServer(config) {
                     injectVersionIntoResponse(response, servedAdcpVersion);
                     return response;
                 };
+                // --- Buyer-agent registry resolution (Phase 1 of #1269) ---
+                // Runs after `authInfo` is populated and before account resolution
+                // so adopters' `resolveAccount` callbacks see `ctx.agent`. The
+                // registry receives the kind-discriminated `credential` (Stage 3)
+                // synthesized by the framework's built-in authenticators in
+                // `serve.ts:attachAuthInfo`; factories route on `credential.kind`
+                // and return null when no credential was stamped (custom adopter
+                // auth callbacks that haven't migrated).
+                //
+                // Phase 1 does NOT enforce status (suspended/blocked → 403) or
+                // billing capability — those land in Stage 4 and Phase 2 (#1292).
+                if (agentRegistry !== undefined) {
+                    try {
+                        // Stage 3 of #1269: pass the kind-discriminated `credential`
+                        // synthesized in `serve.ts:attachAuthInfo` (and hoisted to
+                        // top-level above) into the registry. Factory functions
+                        // (`signingOnly` / `bearerOnly` / `mixed`) route on
+                        // `credential.kind`; absent credential → factories return
+                        // null → ctx.agent stays undefined.
+                        const resolved = await agentRegistry.resolve({
+                            ...(ctx.authInfo?.credential !== undefined && { credential: ctx.authInfo.credential }),
+                            ...(ctx.authInfo?.extra !== undefined && { extra: ctx.authInfo.extra }),
+                        });
+                        if (resolved != null) {
+                            // Shallow-freeze the resolved record so downstream code cannot
+                            // accidentally mutate `status`, `agent_url`, or other own
+                            // properties. NOTE: `Object.freeze` on the `billing_capabilities`
+                            // Set locks the Set object's own properties but does NOT
+                            // protect the internal `[[SetData]]` slot — `.add()` /
+                            // `.delete()` / `.clear()` still mutate. `ReadonlySet` is a
+                            // TypeScript-only contract; adopters constructing a Set MUST
+                            // NOT rely on freeze preventing membership changes at runtime.
+                            // Phase 2's billing-capability check only reads via `.has()`,
+                            // so adopter mis-mutation would only affect the same request's
+                            // own logic — no cross-request leak.
+                            if (!Object.isFrozen(resolved)) {
+                                // Map-backed wrappers and other Set-shaped types skip the
+                                // Set-freeze branch; the outer record's freeze still applies.
+                                if (resolved.billing_capabilities instanceof Set) {
+                                    Object.freeze(resolved.billing_capabilities);
+                                }
+                                Object.freeze(resolved);
+                            }
+                            ctx.agent = resolved;
+                            // Adopters reading the registry's view of `agent_url` get it
+                            // from `ctx.agent.agent_url` (the resolved `BuyerAgent`
+                            // record). Stage 3 of #1269 deliberately does NOT stamp a
+                            // top-level `agent_url` on `ctx.authInfo` — that would
+                            // invite handler code to gate on a non-cryptographically-
+                            // verified URL while the spec (adcontextprotocol/adcp#3831)
+                            // requires verified `agent_url` reads to come from the
+                            // `http_sig` credential variant. Adopters who use bearer or
+                            // OAuth credentials get a registry-resolved `ctx.agent` but
+                            // NO verified `agent_url` — that's correct: bearer auth
+                            // doesn't prove the agent_url cryptographically.
+                            // --- Status enforcement (Stage 4 of #1269) ---
+                            // Reject new requests from `suspended` / `blocked` agents
+                            // with PERMISSION_DENIED + `details.scope: 'agent'`.
+                            // In-flight tasks owned by a now-suspended agent are NOT
+                            // retroactively cancelled — this seam runs once per
+                            // synchronous request, not on `tasks_get` polls or
+                            // background webhook deliveries. Sellers who need hard
+                            // cutoff implement that in their platform method via
+                            // `BuyerAgent.status` checks (the resolved record is
+                            // available on every method that takes ctx.agent).
+                            //
+                            // Phase 2 (#1292) may swap to upstream `AGENT_SUSPENDED` /
+                            // `AGENT_BLOCKED` codes if those land via separate spec PR;
+                            // until then, `PERMISSION_DENIED + scope:'agent'` carries
+                            // the structured signal a buyer can dispatch on without
+                            // parsing prose.
+                            if (resolved.status === 'suspended' || resolved.status === 'blocked') {
+                                // `PERMISSION_DENIED`'s spec-default `recovery` is
+                                // `correctable`, but the agent-status semantics are
+                                // different per status:
+                                //   - `'suspended'` is transient: re-onboarding /
+                                //     contacting the seller may restore access.
+                                //   - `'blocked'` is terminal: a buyer agent that's
+                                //     been permanently denied SHOULD NOT loop.
+                                // Setting recovery explicitly per status lets buyers
+                                // dispatch retry-vs-escalate without parsing
+                                // `details.status` prose.
+                                return finalize((0, errors_1.adcpError)('PERMISSION_DENIED', {
+                                    message: resolved.status === 'suspended'
+                                        ? 'Buyer agent is suspended. Contact the seller to restore access.'
+                                        : 'Buyer agent is blocked.',
+                                    recovery: resolved.status === 'suspended' ? 'transient' : 'terminal',
+                                    details: { scope: 'agent', status: resolved.status },
+                                }));
+                            }
+                        }
+                    }
+                    catch (err) {
+                        const reason = err instanceof Error ? err.message : String(err);
+                        logger.error('Buyer-agent registry resolution failed', { tool: toolName, error: reason });
+                        return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
+                            message: 'Buyer-agent registry resolution failed',
+                            ...(exposeErrorDetails && { details: { reason: (0, redact_1.redactCredentialPatterns)(reason) } }),
+                        }));
+                    }
+                }
                 const toolIsMutating = (0, idempotency_1.isMutatingTask)(toolName);
                 // Field-disagreement detection per spec PR `adcontextprotocol/adcp#3493`:
                 // when the request carries both `adcp_version` (string, AdCP 3.1+)
@@ -1403,10 +1609,11 @@ function createAdcpServer(config) {
                                 // stripped schemaPath even in dev — asymmetric with response-side.
                                 const payload = (0, schema_errors_1.buildAdcpValidationErrorPayload)(toolName, 'request', issues, {
                                     exposeSchemaPath: exposeErrorDetails,
+                                    rootSchemaId: outcome.schemaId,
                                 });
                                 return finalize((0, errors_1.adcpError)('VALIDATION_ERROR', payload));
                             }
-                            logger.warn(`Schema validation warning (request) for ${toolName}: ${(0, schema_validator_1.formatIssues)(issues)}`, {
+                            logger.warn(`Schema validation warning (request) for ${toolName}: ${(0, schema_validator_1.formatIssues)(issues, 3, { rootSchemaId: outcome.schemaId })}`, {
                                 tool: toolName,
                                 issues,
                             });
@@ -1419,6 +1626,7 @@ function createAdcpServer(config) {
                         const account = await resolveAccount(params.account, {
                             toolName: toolName,
                             authInfo: ctx.authInfo,
+                            ...(ctx.agent != null && { agent: ctx.agent }),
                         });
                         if (account == null) {
                             logger.warn('Account not found', { tool: toolName, account: params.account });
@@ -1431,11 +1639,24 @@ function createAdcpServer(config) {
                         ctx.account = account;
                     }
                     catch (err) {
+                        // Typed errors propagate verbatim — both the already-projected
+                        // envelope shape (`isThrownAdcpError`) and the raw class throw
+                        // (`AdcpError instanceof`). Resolvers can surface
+                        // `INVALID_REQUEST` for inline `account_id` against an
+                        // `'implicit'`-resolution platform (#1364), or any other typed
+                        // wire error, without coercion. Generic exceptions still
+                        // project to SERVICE_UNAVAILABLE so upstream leaks don't cross
+                        // the trust boundary.
+                        if (isThrownAdcpError(err))
+                            return finalize(err);
+                        if (err instanceof async_outcome_1.AdcpError) {
+                            return finalize(projectThrownAdcpError(err));
+                        }
                         const reason = err instanceof Error ? err.message : String(err);
                         logger.error('Account resolution failed', { tool: toolName, error: reason });
                         return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
                             message: 'Account resolution failed',
-                            ...(exposeErrorDetails && { details: { reason } }),
+                            ...(exposeErrorDetails && { details: { reason: (0, redact_1.redactCredentialPatterns)(reason) } }),
                         }));
                     }
                 }
@@ -1450,19 +1671,57 @@ function createAdcpServer(config) {
                         const account = await resolveAccountFromAuth({
                             toolName: toolName,
                             authInfo: ctx.authInfo,
+                            ...(ctx.agent != null && { agent: ctx.agent }),
                         });
                         if (account != null)
                             ctx.account = account;
                     }
                     catch (err) {
+                        // Same typed-error pass-through as the explicit `resolveAccount`
+                        // catch above — both the already-projected envelope shape and
+                        // the raw `AdcpError` class throw propagate verbatim. Generic
+                        // exceptions project to SERVICE_UNAVAILABLE.
+                        if (isThrownAdcpError(err))
+                            return finalize(err);
+                        if (err instanceof async_outcome_1.AdcpError) {
+                            return finalize(projectThrownAdcpError(err));
+                        }
                         const reason = err instanceof Error ? err.message : String(err);
                         logger.error('Auth-derived account resolution failed', { tool: toolName, error: reason });
                         return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
                             message: 'Account resolution failed',
-                            ...(exposeErrorDetails && { details: { reason } }),
+                            ...(exposeErrorDetails && { details: { reason: (0, redact_1.redactCredentialPatterns)(reason) } }),
                         }));
                     }
                 }
+                // --- Sandbox-only enforcement (Phase 1.5 of #1269) ---
+                // Runs after account resolution so we can compare the resolved
+                // account's `sandbox` flag against the agent's `sandbox_only`
+                // capability. Account-less tools (provide_performance_feedback,
+                // list_creative_formats, etc.) pass the gate — they don't
+                // operate on a specific account, so the sandbox/production axis
+                // doesn't apply.
+                //
+                // Defense-in-depth for test agents (CI runners, internal QA
+                // agents, partner pre-prod environments): if a sandbox-only
+                // agent's credential leaks, blast radius is bounded to sandbox
+                // accounts. Production agents leave `sandbox_only` unset.
+                // Strict-by-default: any non-Account shape (legacy v5 adopters,
+                // bespoke account types) lacking the `sandbox` field reads as
+                // `undefined !== true → reject`. That's correct: a sandbox-only
+                // agent operating against an unknown-shape account is the
+                // case where rejection is the safe default — adopters who want
+                // to opt in either flip the agent's `sandbox_only` off or
+                // populate `sandbox: true` on their resolved account.
+                if (ctx.agent?.sandbox_only === true &&
+                    ctx.account !== undefined &&
+                    ctx.account.sandbox !== true) {
+                    return finalize((0, errors_1.adcpError)('PERMISSION_DENIED', {
+                        message: 'Buyer agent is sandbox-only; this request targets a non-sandbox account.',
+                        recovery: 'terminal',
+                        details: { scope: 'agent', reason: 'sandbox-only' },
+                    }));
+                }
                 // --- Session key resolution ---
                 if (resolveSessionKey) {
                     try {
@@ -1470,6 +1729,7 @@ function createAdcpServer(config) {
                             toolName: toolName,
                             params,
                             account: ctx.account,
+                            ...(ctx.agent != null && { agent: ctx.agent }),
                         });
                         if (sessionKey !== undefined)
                             ctx.sessionKey = sessionKey;
@@ -1479,7 +1739,7 @@ function createAdcpServer(config) {
                         logger.error('Session key resolution failed', { tool: toolName, error: reason });
                         return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
                             message: 'Session key resolution failed',
-                            ...(exposeErrorDetails && { details: { reason } }),
+                            ...(exposeErrorDetails && { details: { reason: (0, redact_1.redactCredentialPatterns)(reason) } }),
                         }));
                     }
                 }
@@ -1580,7 +1840,7 @@ function createAdcpServer(config) {
                         logger.error('Idempotency check failed', { tool: toolName, error: reason });
                         return finalize((0, errors_1.adcpError)('SERVICE_UNAVAILABLE', {
                             message: 'Idempotency check failed',
-                            ...(exposeErrorDetails && { details: { reason } }),
+                            ...(exposeErrorDetails && { details: { reason: (0, redact_1.redactCredentialPatterns)(reason) } }),
                         }));
                     }
                 }
@@ -1678,7 +1938,7 @@ function createAdcpServer(config) {
                         const payload = formatted.structuredContent;
                         const outcome = (0, schema_validator_1.validateResponse)(toolName, payload, adcpVersion);
                         if (!outcome.valid) {
-                            logger.warn(`Schema validation warning (response) for ${toolName}: ${(0, schema_validator_1.formatIssues)(outcome.issues)}`, {
+                            logger.warn(`Schema validation warning (response) for ${toolName}: ${(0, schema_validator_1.formatIssues)(outcome.issues, 3, { rootSchemaId: outcome.schemaId })}`, {
                                 tool: toolName,
                                 issues: outcome.issues,
                                 variant: outcome.variant,
@@ -1686,6 +1946,7 @@ function createAdcpServer(config) {
                             if (responseValidationMode === 'strict') {
                                 const errPayload = (0, schema_errors_1.buildAdcpValidationErrorPayload)(toolName, 'response', outcome.issues, {
                                     exposeSchemaPath: exposeErrorDetails,
+                                    rootSchemaId: outcome.schemaId,
                                 });
                                 const errEnvelope = (0, errors_1.adcpError)('VALIDATION_ERROR', errPayload);
                                 if (idempotencyCheck && idempotency) {
@@ -1833,6 +2094,22 @@ function createAdcpServer(config) {
                         });
                         return finalize(err);
                     }
+                    // Raw `AdcpError` class throws — distinct from the
+                    // already-projected envelope above. The framework has long
+                    // documented `throw new AdcpError(...)` as the canonical way
+                    // to signal structured rejection from any specialism method
+                    // (see `AdcpError` JSDoc). Project to the typed envelope so
+                    // the buyer sees the typed code, not `SERVICE_UNAVAILABLE`.
+                    if (err instanceof async_outcome_1.AdcpError) {
+                        logger.warn('Handler threw an AdcpError', {
+                            tool: toolName,
+                            handler: handlerKey,
+                            code: err.code,
+                            message: err.message,
+                            stack: err.stack,
+                        });
+                        return finalize(projectThrownAdcpError(err));
+                    }
                     const reason = err instanceof Error ? err.message : String(err);
                     // Log the full stack — `logger.error` with just the message turned
                     // every "Handler failed" into a guessing game for agent authors.
@@ -1850,9 +2127,11 @@ function createAdcpServer(config) {
                         // of diagnostic time on the matrix harness — dev callers want
                         // the real reason at the call site, not hidden in server logs.
                         message: exposeErrorDetails
-                            ? `Tool ${toolName} handler threw: ${reason}`
+                            ? `Tool ${toolName} handler threw: ${(0, redact_1.redactCredentialPatterns)(reason)}`
                             : `Tool ${toolName} encountered an internal error`,
-                        ...(exposeErrorDetails && { details: { reason, handler: handlerKey } }),
+                        ...(exposeErrorDetails && {
+                            details: { reason: (0, redact_1.redactCredentialPatterns)(reason), handler: handlerKey },
+                        }),
                     }));
                 }
             };
@@ -1917,13 +2196,32 @@ function createAdcpServer(config) {
             if (!custom)
                 continue;
             const { description, title, inputSchema, outputSchema, annotations, handler } = custom;
+            // Wrap the adopter-supplied handler so `throw new AdcpError(...)` and
+            // `throw adcpError(...)` from inside it project to the typed envelope —
+            // matching the behavior framework-registered tools get from the catch
+            // at line ~3494. Without the wrap, AdcpError throws escape to the MCP
+            // SDK as generic JSON-RPC errors and the buyer loses the typed code.
+            // The framework's own `tasks_get` is registered through this path.
+            const rawHandler = handler;
+            const wrappedHandler = (async (...args) => {
+                try {
+                    return await rawHandler(...args);
+                }
+                catch (err) {
+                    if (isThrownAdcpError(err))
+                        return err;
+                    if (err instanceof async_outcome_1.AdcpError)
+                        return projectThrownAdcpError(err);
+                    throw err;
+                }
+            });
             server.registerTool(customName, {
                 ...(description != null && { description }),
                 ...(title != null && { title }),
                 ...(inputSchema != null && { inputSchema }),
                 ...(outputSchema != null && { outputSchema }),
                 ...(annotations != null && { annotations }),
-            }, handler);
+            }, wrappedHandler);
             registeredToolNames.add(customName);
         }
     }
@@ -2123,6 +2421,17 @@ function createAdcpServer(config) {
         configurable: true,
         writable: false,
     });
+    // Mark when `instructions` was supplied as a function, so `serve()` can
+    // refuse `reuseAgent: true` — the function is captured once at construction
+    // and would not re-evaluate per session under server reuse.
+    if (instructionsIsFn) {
+        Object.defineProperty(wrapped, exports.ADCP_INSTRUCTIONS_FN, {
+            value: true,
+            enumerable: false,
+            configurable: true,
+            writable: false,
+        });
+    }
     // Expose the capabilitiesData object so post-registration helpers
     // (registerTestController) can add spec-defined capability blocks
     // — comply_test_controller is registered AFTER createAdcpServer,