@adcp/sdk 7.2.0 → 7.4.0

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

@@ -246,6 +246,42 @@ function stampReplayed(response) {
         }
     }
 }
+/**
+ * Stamp a non-normative `_bridge` marker on a response that the
+ * `testController` bridge augmented with seeded fixtures.
+ *
+ * Mirrors {@link stampReplayed} — sets `_bridge` on `structuredContent`
+ * AND on the parsed JSON in `content[0].text`, so A2A/REST adapters that
+ * consume the text body see the same envelope MCP does.
+ *
+ * Only call this AFTER a successful merge — for singleton-replace tools
+ * (`get_account_financials`, `get_brand_identity`, `si_get_offering`,
+ * `get_property_list`, `get_collection_list`, `get_content_standards`)
+ * gate on `merged !== sc` so the marker only fires when the seeded fixture
+ * actually replaced the handler payload.
+ */
+function stampBridge(response, callback, tool, mergedCount) {
+    if (!response.structuredContent || typeof response.structuredContent !== 'object')
+        return;
+    const marker = { callback, tool, merged_count: mergedCount };
+    const sc = response.structuredContent;
+    sc._bridge = marker;
+    if (Array.isArray(response.content)) {
+        const first = response.content[0];
+        if (first && first.type === 'text' && typeof first.text === 'string') {
+            try {
+                const parsed = JSON.parse(first.text);
+                if (parsed && typeof parsed === 'object') {
+                    parsed._bridge = marker;
+                    first.text = JSON.stringify(parsed);
+                }
+            }
+            catch {
+                // Text isn't JSON — leave it alone (implausible for AdCP responses).
+            }
+        }
+    }
+}
 /**
  * Remove per-request echo fields (`context`) from a formatted MCP response
  * before caching. The buyer's `correlation_id` is scoped to the individual
@@ -1204,6 +1240,29 @@ function buildSupportedVersionsList(capConfig, serverPin) {
  */
 function createAdcpServer(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, credentialPolicy, testController: testControllerBridge, } = config;
+    // One-shot construction-time warn when `testController` is wired without
+    // any account resolver. The dispatch-time sandbox gate admits requests
+    // where `ctx.account === undefined`, so without a resolver the only
+    // remaining check is buyer-supplied `account.sandbox` / `context.sandbox`
+    // on the request — caller-controlled, not a trust boundary. Storyboard
+    // runners legitimately have no account scoping and should ignore this
+    // warning; production bindings need to wire `resolveAccount` (or
+    // `resolveAccountFromAuth` for OAuth-passthrough setups) so the gate's
+    // account-side check has teeth.
+    //
+    // Dual-emit: `process.emitWarning` writes to stderr by default so the
+    // signal is visible even when `logger` is the default `noopLogger`
+    // (the day-one case where the misconfig is most likely). `logger.warn`
+    // also fires so adopters with configured logging pipelines see it in
+    // their normal channel. The `code` lets adopters silence it via
+    // `--no-warnings=ADCP_BRIDGE_NO_RESOLVER` if they're knowingly running
+    // a storyboard-runner config. See `AdcpServerConfig.testController`
+    // JSDoc § "Security — trust boundary" and #1784.
+    if (testControllerBridge != null && resolveAccount === undefined && resolveAccountFromAuth === undefined) {
+        const message = '[adcp/createAdcpServer] testController is wired but no account resolver — configure resolveAccount (or resolveAccountFromAuth) for production. Storyboard runners without account scoping can ignore. Details: https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/VALIDATE-YOUR-AGENT.md';
+        process.emitWarning(message, { type: 'AdcpServerConfigWarning', code: 'ADCP_BRIDGE_NO_RESOLVER' });
+        logger.warn(message);
+    }
     // Pre-resolve credential-policy patterns once. The patterns config is
     // a stable property of `CredentialPolicyConfig`; pulling it out here
     // keeps the per-call hot path (`scanArgsForCredentials`) free of the
@@ -2202,50 +2261,499 @@ function createAdcpServer(config) {
                     else {
                         formatted = wrap(result);
                     }
-                    // --- Test-controller bridge: augment get_products with seeded fixtures. ---
-                    // Only runs when the seller opted in via `testController.getSeededProducts`
-                    // AND the request carries a sandbox marker (account.sandbox === true or
-                    // context.sandbox === true). When `resolveAccount` returned a concrete
-                    // account, we additionally require `ctx.account.sandbox === true` so a
-                    // request that happens to include `account.sandbox: true` can't leak
-                    // fixtures into a non-sandbox resolved account (belt-and-suspenders).
-                    // Seeded products append to whatever the handler returned; `product_id`
-                    // collisions resolve with the seeded entry winning, so storyboards that
-                    // override default inventory see their fixture.
-                    if (toolName === 'get_products' &&
-                        testControllerBridge?.getSeededProducts &&
+                    // --- Test-controller bridge: augment read-side tools with seeded fixtures. ---
+                    // Each per-tool callback (`getSeededProducts`, `getSeededCreatives`, ...)
+                    // is opt-in by presence on the bridge interface. All callbacks share the
+                    // same triply-gated contract:
+                    //   1. The bridge is registered AND has the matching callback;
+                    //   2. The handler returned a success envelope (not an `adcp_error`);
+                    //   3. The request carries a sandbox marker (account.sandbox === true or
+                    //      context.sandbox === true) AND, if `resolveAccount` produced a
+                    //      record, that record is flagged `sandbox: true` too.
+                    // For array-collection tools, seeded entries append to the handler's
+                    // response with seeded winning on id collision (same as `getSeededProducts`).
+                    // `get_account_financials` is the exception — singleton response, so the
+                    // seeded entry REPLACES the handler payload when its `account.account_id`
+                    // matches the request's `account.account_id`.
+                    // Diagnostic for adopters chasing "why aren't my fixtures showing":
+                    // when the request carries a sandbox marker but the resolved account
+                    // is explicitly non-sandbox, the gate rejects silently. Emit a
+                    // `debug` line so the rejection is observable in dev logs without
+                    // adding noise to production traffic (where the gate's first check
+                    // — `isSandboxRequestForSeeding` — fails first and never reaches
+                    // this branch).
+                    if (testControllerBridge &&
+                        !isErrorResponse(formatted) &&
+                        (0, test_controller_bridge_1.isSandboxRequest)(params) &&
+                        ctx.account !== undefined &&
+                        !(typeof ctx.account === 'object' &&
+                            ctx.account !== null &&
+                            ctx.account.sandbox === true)) {
+                        // Include the resolved account_id so the log line is self-
+                        // diagnostic — an adopter chasing "why aren't my fixtures
+                        // showing" can match the rejected account against their
+                        // resolveAccount source without correlating across log lines.
+                        // account_ids appear in normal request logs already; no new
+                        // PII surface.
+                        const resolvedAccountId = typeof ctx.account === 'object' &&
+                            ctx.account !== null &&
+                            typeof ctx.account.account_id === 'string'
+                            ? ctx.account.account_id
+                            : undefined;
+                        logger.debug('test-controller bridge: request is sandbox-flagged but resolved account is not sandbox; skipping merge', { tool: toolName, resolved_account_id: resolvedAccountId });
+                    }
+                    if (testControllerBridge &&
                         !isErrorResponse(formatted) &&
                         (0, test_controller_bridge_1.isSandboxRequest)(params) &&
-                        // If resolveAccount produced a record, require it to be flagged
-                        // sandbox too. If no account was resolved, the request-signal
-                        // check above is the only line of defense — keep that contract.
                         (ctx.account === undefined ||
                             (typeof ctx.account === 'object' &&
                                 ctx.account !== null &&
                                 ctx.account.sandbox === true))) {
-                        try {
-                            const bridgeCtx = { input: params };
-                            if (ctx.account !== undefined)
-                                bridgeCtx.account = ctx.account;
-                            const rawSeeded = await testControllerBridge.getSeededProducts(bridgeCtx);
-                            const seeded = (0, test_controller_bridge_1.filterValidSeededProducts)(rawSeeded, logger);
-                            if (seeded.length > 0) {
-                                const sc = formatted.structuredContent;
-                                if (sc && typeof sc === 'object') {
-                                    const merged = (0, test_controller_bridge_1.mergeSeededProductsIntoResponse)(sc, seeded);
-                                    formatted = wrap(merged);
+                        const bridgeCtx = { input: params };
+                        if (ctx.account !== undefined)
+                            bridgeCtx.account = ctx.account;
+                        // get_products
+                        if (toolName === 'get_products' && testControllerBridge.getSeededProducts) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededProducts(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededProducts)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededProductsIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededProducts', toolName, seeded.length);
+                                    }
                                 }
                             }
+                            catch (err) {
+                                // Bridge failures are sandbox-only by construction, so logging +
+                                // returning the handler's response is the right default — a broken
+                                // test fixture shouldn't tank the request under test.
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededProducts failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
                         }
-                        catch (err) {
-                            // Bridge failures are sandbox-only by construction, so logging +
-                            // returning the handler's response is the right default — a broken
-                            // test fixture shouldn't tank the request under test.
-                            const reason = err instanceof Error ? err.message : String(err);
-                            logger.warn('testController.getSeededProducts failed; returning handler response unchanged', {
-                                tool: toolName,
-                                error: reason,
-                            });
+                        // list_creatives
+                        else if (toolName === 'list_creatives' && testControllerBridge.getSeededCreatives) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededCreatives(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededCreatives)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededCreativesIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededCreatives', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededCreatives failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_media_buys
+                        else if (toolName === 'get_media_buys' && testControllerBridge.getSeededMediaBuys) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededMediaBuys(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededMediaBuys)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededMediaBuysIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededMediaBuys', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededMediaBuys failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_media_buy_delivery
+                        else if (toolName === 'get_media_buy_delivery' && testControllerBridge.getSeededMediaBuyDelivery) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededMediaBuyDelivery(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededMediaBuyDeliveries)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededMediaBuyDeliveryIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededMediaBuyDelivery', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededMediaBuyDelivery failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // list_accounts
+                        else if (toolName === 'list_accounts' && testControllerBridge.getSeededAccounts) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededAccounts(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededAccounts)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededAccountsIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededAccounts', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededAccounts failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_account_financials (singleton — replace, not append)
+                        else if (toolName === 'get_account_financials' && testControllerBridge.getSeededAccountFinancials) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededAccountFinancials(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededAccountFinancials)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        // Brand+operator `AccountReference` variants don't carry
+                                        // `account_id` on the wire — the framework's resolved
+                                        // account does, so prefer it for the match key.
+                                        const resolvedAccountId = ctx.account && typeof ctx.account === 'object' && !Array.isArray(ctx.account)
+                                            ? ctx.account.account_id
+                                            : undefined;
+                                        const merged = (0, test_controller_bridge_1.replaceAccountFinancialsIfSeeded)(params, sc, seeded, typeof resolvedAccountId === 'string' && resolvedAccountId.length > 0
+                                            ? resolvedAccountId
+                                            : undefined);
+                                        if (merged !== sc) {
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededAccountFinancials', toolName, seeded.length);
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededAccountFinancials failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // list_creative_formats
+                        else if (toolName === 'list_creative_formats' && testControllerBridge.getSeededCreativeFormats) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededCreativeFormats(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededCreativeFormats)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededCreativeFormatsIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededCreativeFormats', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededCreativeFormats failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // list_property_lists / get_property_list — one seeded fixture array
+                        // feeds both. List path: append-merge with seeded-wins on `list_id`
+                        // collision. Get path: pick by request.list_id and replace the
+                        // response's `list` field, preserving handler's resolved data
+                        // (`identifiers` / `pagination` / `resolved_at` / `cache_valid_until`
+                        // / `coverage_gaps` / `context` / `ext`).
+                        else if ((toolName === 'list_property_lists' || toolName === 'get_property_list') &&
+                            testControllerBridge.getSeededPropertyLists) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededPropertyLists(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededPropertyLists)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    if (toolName === 'list_property_lists') {
+                                        const sc = formatted.structuredContent;
+                                        if (sc && typeof sc === 'object') {
+                                            const merged = (0, test_controller_bridge_1.mergeSeededPropertyListsIntoResponse)(sc, seeded);
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededPropertyLists', toolName, seeded.length);
+                                        }
+                                    }
+                                    else {
+                                        const sc = formatted.structuredContent;
+                                        if (sc && typeof sc === 'object') {
+                                            const merged = (0, test_controller_bridge_1.replacePropertyListIfSeeded)(params, sc, seeded);
+                                            if (merged !== sc) {
+                                                formatted = wrap(merged);
+                                                stampBridge(formatted, 'getSeededPropertyLists', toolName, seeded.length);
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededPropertyLists failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // list_collection_lists / get_collection_list — symmetric with
+                        // property lists.
+                        else if ((toolName === 'list_collection_lists' || toolName === 'get_collection_list') &&
+                            testControllerBridge.getSeededCollectionLists) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededCollectionLists(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededCollectionLists)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    if (toolName === 'list_collection_lists') {
+                                        const sc = formatted.structuredContent;
+                                        if (sc && typeof sc === 'object') {
+                                            const merged = (0, test_controller_bridge_1.mergeSeededCollectionListsIntoResponse)(sc, seeded);
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededCollectionLists', toolName, seeded.length);
+                                        }
+                                    }
+                                    else {
+                                        const sc = formatted.structuredContent;
+                                        if (sc && typeof sc === 'object') {
+                                            const merged = (0, test_controller_bridge_1.replaceCollectionListIfSeeded)(params, sc, seeded);
+                                            if (merged !== sc) {
+                                                formatted = wrap(merged);
+                                                stampBridge(formatted, 'getSeededCollectionLists', toolName, seeded.length);
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededCollectionLists failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_signals — append-merge by signal_id. Works uniformly across
+                        // signal-marketplace and signal-owned specialisms (one bridge, both
+                        // dispatched on the same tool; the per-signal `signal_type` field
+                        // is the marketplace-vs-owned discriminator).
+                        else if (toolName === 'get_signals' && testControllerBridge.getSeededSignals) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededSignals(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededSignals)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededSignalsIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededSignals', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededSignals failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_creative_delivery — append-merge by creative_id;
+                        // `pagination.total` (when set by the handler) updates by the
+                        // count of new non-colliding seeded entries. No aggregated-totals
+                        // recomputation — this response has no top-level totals envelope.
+                        else if (toolName === 'get_creative_delivery' && testControllerBridge.getSeededCreativeDelivery) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededCreativeDelivery(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededCreativeDelivery)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededCreativeDeliveryIntoResponse)(sc, seeded);
+                                        formatted = wrap(merged);
+                                        stampBridge(formatted, 'getSeededCreativeDelivery', toolName, seeded.length);
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededCreativeDelivery failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_creative_features — `oneOf` envelope. Success arm: merge
+                        // seeded `CreativeFeatureResult[]` into `results` (dedup by
+                        // `feature_id`, seeded wins). Error arm: no-op (the helper
+                        // discriminates by presence of `results: []`).
+                        else if (toolName === 'get_creative_features' && testControllerBridge.getSeededCreativeFeatures) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededCreativeFeatures(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededCreativeFeatures)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededCreativeFeaturesIntoResponse)(sc, seeded);
+                                        if (merged !== sc) {
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededCreativeFeatures', toolName, seeded.length);
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededCreativeFeatures failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_brand_identity — singleton replace keyed by `brand_id`.
+                        // Seeded fixture is authoritative on the GetBrandIdentitySuccess
+                        // body; handler's `context` / `ext` round-trip. The response is
+                        // a union (success | error) — the dispatcher already gated on
+                        // `!isErrorResponse`, so we narrow defensively when reading.
+                        else if (toolName === 'get_brand_identity' && testControllerBridge.getSeededBrandIdentity) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededBrandIdentity(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededBrandIdentity)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.replaceBrandIdentityIfSeeded)(params, sc, seeded);
+                                        if (merged !== sc) {
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededBrandIdentity', toolName, seeded.length);
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededBrandIdentity failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // get_rights — append-merge keyed by `rights_id`. Discovery /
+                        // search tool (NL `query`); the response carries `rights[]`.
+                        // Drops to a no-op on the error arm of the response union.
+                        else if (toolName === 'get_rights' && testControllerBridge.getSeededRights) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededRights(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededRights)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.mergeSeededRightsIntoResponse)(sc, seeded);
+                                        if (merged !== sc) {
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededRights', toolName, seeded.length);
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededRights failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // si_get_offering — singleton replace keyed by `offering_id`.
+                        // Stateless catalog lookup; the response's `offering_token` is
+                        // produced for a future session but the lookup itself does not
+                        // consume one. Handler's `context` / `ext` round-trip.
+                        else if (toolName === 'si_get_offering' && testControllerBridge.getSeededSiOffering) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededSiOffering(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededSiOffering)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    const sc = formatted.structuredContent;
+                                    if (sc && typeof sc === 'object') {
+                                        const merged = (0, test_controller_bridge_1.replaceSiOfferingIfSeeded)(params, sc, seeded);
+                                        if (merged !== sc) {
+                                            formatted = wrap(merged);
+                                            stampBridge(formatted, 'getSeededSiOffering', toolName, seeded.length);
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededSiOffering failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
+                        }
+                        // list_content_standards / get_content_standards — list returns
+                        // `{ standards: ContentStandards[] }` (success arm of a union; the
+                        // error arm is gated out upstream). Get returns `ContentStandards`
+                        // directly (success arm); replace the ContentStandards body and
+                        // round-trip handler's `context` / `ext` (both are framework-
+                        // managed envelope fields per the spec).
+                        else if ((toolName === 'list_content_standards' || toolName === 'get_content_standards') &&
+                            testControllerBridge.getSeededContentStandards) {
+                            try {
+                                const rawSeeded = await testControllerBridge.getSeededContentStandards(bridgeCtx);
+                                const seeded = (0, test_controller_bridge_1.filterValidSeededContentStandards)(rawSeeded, logger);
+                                if (seeded.length > 0) {
+                                    if (toolName === 'list_content_standards') {
+                                        const sc = formatted.structuredContent;
+                                        if (sc && typeof sc === 'object') {
+                                            const merged = (0, test_controller_bridge_1.mergeSeededContentStandardsIntoResponse)(sc, seeded);
+                                            if (merged !== sc) {
+                                                formatted = wrap(merged);
+                                                stampBridge(formatted, 'getSeededContentStandards', toolName, seeded.length);
+                                            }
+                                        }
+                                    }
+                                    else {
+                                        const sc = formatted.structuredContent;
+                                        if (sc && typeof sc === 'object') {
+                                            const merged = (0, test_controller_bridge_1.replaceContentStandardsIfSeeded)(params, sc, seeded);
+                                            if (merged !== sc) {
+                                                formatted = wrap(merged);
+                                                stampBridge(formatted, 'getSeededContentStandards', toolName, seeded.length);
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            catch (err) {
+                                const reason = err instanceof Error ? err.message : String(err);
+                                logger.warn('testController.getSeededContentStandards failed; returning handler response unchanged', {
+                                    tool: toolName,
+                                    error: reason,
+                                });
+                            }
                         }
                     }
                     // --- Response schema validation (opt-in) ---