@certscore/mcp 0.2.16 → 0.2.18

package/dist/server.d.ts

@@ -10,6 +10,7 @@ export interface CertScoreMcpOptions {
     anonymousSurface?: "mcp_light" | "mcp_anonymous" | null;
     timeout?: number;
     toolProfile?: "full" | "light";
+    initialPreConsentPreviewWaitMs?: number;
     exampleDomainDemoUrl?: string | null;
     onToolInvocation?: (observation: McpToolInvocationObservation, requestContext: McpToolInvocationRequestContext) => void | Promise<void>;
 }
@@ -33,16 +34,6 @@ export type McpToolInvocationObservation = {
     toolName: string;
     transportOutcome: "mcp_result" | "mcp_error";
 };
-export declare function resolveMcpScanSiteWaitBudget(input: {
-    maxWaitSeconds?: number;
-    startedAtMs: number;
-    nowMs: number;
-}): {
-    elapsedMs: number;
-    remainingWaitMs: number;
-    responseReserveMs: number;
-    totalBudgetMs: number;
-};
 export declare function projectMcpToolInvocationObservation(input: {
     args: unknown;
     durationMs: number;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAItE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9E,gCAAgC,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvD,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,gBAAgB,CAAC,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gBAAgB,CAAC,EAAE,CACjB,WAAW,EAAE,4BAA4B,EACzC,cAAc,EAAE,+BAA+B,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAID,MAAM,MAAM,+BAA+B,GAAG;IAC5C,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;CACxC,CAAC;AA4BF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;IAC9C,YAAY,EAAE,SAAS,GAAG,cAAc,CAAC;IACzC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,qBAAqB,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;IACtE,YAAY,EAAE,QAAQ,GAAG,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC;IAClE,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC;CAC9C,CAAC;AAOF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;;;;;EAYA;AAoJD,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,4BAA4B,CAqD/B;AAkBD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aA8XzE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAItE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9E,gCAAgC,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvD,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,gBAAgB,CAAC,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gBAAgB,CAAC,EAAE,CACjB,WAAW,EAAE,4BAA4B,EACzC,cAAc,EAAE,+BAA+B,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAID,MAAM,MAAM,+BAA+B,GAAG;IAC5C,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;CACxC,CAAC;AA4BF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;IAC9C,YAAY,EAAE,SAAS,GAAG,cAAc,CAAC;IACzC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,qBAAqB,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;IACtE,YAAY,EAAE,QAAQ,GAAG,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC;IAClE,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC;CAC9C,CAAC;AAqKF,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,4BAA4B,CAqD/B;AAkBD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aAwZzE"}

package/dist/server.js

@@ -2,21 +2,12 @@ import { CertScoreClient } from "@certscore/sdk";
 import { certScoreMcpToolContracts, isCanonicalScanId } from "@certscore/api-contracts";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CERTSCORE_MCP_VERSION } from "./version.js";
-import { boundEvidencePacket, buildScanBundle, exportFindings, findingListText, limitPreConsentRows, markdownReportText, MAX_EVIDENCE_PACKET_CHARS, normalizeDetail, normalizeFormat, paginateFindingList, preConsentInventoryText, pulseReportText, scanBundleText, scanStatusText, toInvalidArgumentsToolError, toInvalidScanIdToolError, toToolError, toToolResult, withMcpAgentGuidance, withMcpScanProvenanceGuidance } from "./tools.js";
-const DEFAULT_MCP_SCAN_TOOL_BUDGET_MS = 25_000;
-const MAX_MCP_SCAN_TOOL_BUDGET_MS = 45_000;
-const MCP_SCAN_TOOL_RESPONSE_RESERVE_MS = 1_000;
+import { boundEvidencePacket, buildScanBundle, exportFindings, findingListText, limitPreConsentRows, markdownReportText, MAX_EVIDENCE_PACKET_CHARS, normalizeDetail, normalizeFormat, paginateFindingList, preConsentInventoryText, pulseReportText, scanBundleText, scanSiteText, scanStatusText, toInvalidArgumentsToolError, toInvalidScanIdToolError, toToolError, toToolResult, withMcpAgentGuidance, withMcpScanProvenanceGuidance } from "./tools.js";
 const LIGHT_MCP_BUNDLE_RESPONSE_CEILING_BYTES = 25_000;
-export function resolveMcpScanSiteWaitBudget(input) {
-    const totalBudgetMs = Math.min(input.maxWaitSeconds ? input.maxWaitSeconds * 1_000 : DEFAULT_MCP_SCAN_TOOL_BUDGET_MS, MAX_MCP_SCAN_TOOL_BUDGET_MS);
-    const elapsedMs = Math.max(0, input.nowMs - input.startedAtMs);
-    return {
-        elapsedMs,
-        remainingWaitMs: Math.max(0, totalBudgetMs - elapsedMs - MCP_SCAN_TOOL_RESPONSE_RESERVE_MS),
-        responseReserveMs: MCP_SCAN_TOOL_RESPONSE_RESERVE_MS,
-        totalBudgetMs,
-    };
-}
+const MCP_SCAN_SITE_TARGET_RESPONSE_MS = 11_000;
+const MCP_SCAN_SITE_TARGET_RESPONSE_RESERVE_MS = 250;
+const MCP_SCAN_SITE_PREVIEW_POLL_INTERVAL_MS = 750;
+const MCP_SCAN_SITE_MAX_PREVIEW_WAIT_MS = 10_000;
 function exampleDomainDemoSubstitution(requestedUrl, demoUrl) {
     if (!demoUrl)
         return null;
@@ -41,11 +32,9 @@ function withExampleDomainDemo(value, substitution) {
     return substitution ? { ...value, demoSubstitution: substitution } : value;
 }
 function exampleDomainDemoText(value, substitution) {
-    if (!substitution)
-        return undefined;
-    const status = typeof value.status === "string" ? ` Status=${value.status}.` : "";
-    const scanId = typeof value.scanId === "string" ? ` ScanId=${value.scanId}.` : "";
-    return `${substitution.message}${status}${scanId} Full result and substitution provenance are in structuredContent.`;
+    return scanSiteText(value, substitution
+        ? [`${substitution.message} Substitution provenance is in structuredContent.`]
+        : []);
 }
 async function retryTransientOriginFailure(operation) {
     try {
@@ -73,6 +62,15 @@ function scanCreationMetadata(value) {
         upgradeMessage: value.upgradeMessage
     };
 }
+function activeScan(value) {
+    return value.status === "queued" || value.status === "running" || value.status === "finalizing";
+}
+function hasPreConsentPreview(value) {
+    return Boolean(value.preConsentPreview && typeof value.preConsentPreview === "object" && !Array.isArray(value.preConsentPreview));
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function toolContract(name) {
     const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
     if (!contract) {
@@ -302,6 +300,7 @@ export function createCertScoreMcpServer(options = {}) {
     };
     registerTool("certscore_scan_site", toolContract("certscore_scan_site"), async (input, extra) => {
         const toolStartedAtMs = Date.now();
+        const creationStartedAtMs = toolStartedAtMs;
         const client = clientForRequest(extra);
         const demoSubstitution = exampleDomainDemoSubstitution(input.url, options.exampleDomainDemoUrl);
         const effectiveUrl = demoSubstitution?.effectiveUrl ?? input.url;
@@ -310,63 +309,84 @@ export function createCertScoreMcpServer(options = {}) {
                 freshness: input.freshness ?? "latest",
                 scanFrom: input.scanFrom
             });
-            if (input.waitForCompletion === false || created.type === "certscore_scan") {
-                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
-                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
-            }
-            const waitBudget = resolveMcpScanSiteWaitBudget({
-                maxWaitSeconds: input.maxWaitSeconds,
-                nowMs: Date.now(),
-                startedAtMs: toolStartedAtMs,
-            });
-            if (waitBudget.remainingWaitMs === 0) {
-                console.warn(JSON.stringify({
-                    event: "mcp.certscore_scan_site.wait_budget_consumed",
-                    jobId: created.jobId ?? null,
-                    scanId: created.scanId ?? created.scan_id ?? null,
-                    status: created.status ?? null,
-                    ...waitBudget,
+            console.log(JSON.stringify({
+                event: "mcp.certscore_scan_site.creation_completed",
+                durationMs: Date.now() - creationStartedAtMs,
+                executionMode: created.executionMode ?? null,
+                hasScanId: Boolean(created.scanId ?? created.scan_id),
+                reused: created.reused === true,
+                status: created.status ?? null,
+            }));
+            let initialResult = created;
+            const stableScanId = typeof created.scanId === "string" && created.scanId
+                ? created.scanId
+                : typeof created.scan_id === "string" && created.scan_id
+                    ? created.scan_id
+                    : typeof created.jobId === "string" && created.jobId
+                        ? created.jobId
+                        : null;
+            const configuredPreviewWaitMs = options.toolProfile === "light"
+                ? Math.min(Math.max(0, options.initialPreConsentPreviewWaitMs ?? 10_000), MCP_SCAN_SITE_MAX_PREVIEW_WAIT_MS)
+                : 0;
+            const totalRemainingMs = Math.max(0, toolStartedAtMs + MCP_SCAN_SITE_TARGET_RESPONSE_MS - MCP_SCAN_SITE_TARGET_RESPONSE_RESERVE_MS - Date.now());
+            const previewWaitMs = Math.min(configuredPreviewWaitMs, totalRemainingMs);
+            if (stableScanId && previewWaitMs > 0 && activeScan(initialResult)) {
+                const previewWaitStartedAtMs = Date.now();
+                const previewDeadlineMs = previewWaitStartedAtMs + previewWaitMs;
+                let internalReadCount = 0;
+                try {
+                    while (Date.now() < previewDeadlineMs && activeScan(initialResult) && !hasPreConsentPreview(initialResult)) {
+                        await delay(Math.min(MCP_SCAN_SITE_PREVIEW_POLL_INTERVAL_MS, previewDeadlineMs - Date.now()));
+                        const requestRemainingMs = previewDeadlineMs - Date.now();
+                        if (requestRemainingMs <= 0)
+                            break;
+                        const waitAbortController = new AbortController();
+                        const waitAbortTimer = setTimeout(() => waitAbortController.abort(), requestRemainingMs);
+                        try {
+                            internalReadCount += 1;
+                            const status = await client.scans.status(stableScanId, {
+                                internalMcpOperation: { operation: "scan_site_wait", scanId: stableScanId },
+                                signal: waitAbortController.signal,
+                            });
+                            initialResult = {
+                                ...status,
+                                ...scanCreationMetadata(created),
+                            };
+                        }
+                        finally {
+                            clearTimeout(waitAbortTimer);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.warn(JSON.stringify({
+                        event: "mcp.certscore_scan_site.preview_wait_deferred",
+                        durationMs: Date.now() - previewWaitStartedAtMs,
+                        errorName: error instanceof Error ? error.name : "UnknownError",
+                        hasPreview: hasPreConsentPreview(initialResult),
+                        internalReadCount,
+                        scanId: stableScanId,
+                    }));
+                }
+                console.log(JSON.stringify({
+                    event: "mcp.certscore_scan_site.preview_wait_completed",
+                    durationMs: Date.now() - previewWaitStartedAtMs,
+                    hasPreview: hasPreConsentPreview(initialResult),
+                    internalReadCount,
+                    scanId: stableScanId,
+                    status: initialResult.status ?? null,
+                    totalDurationMs: Date.now() - toolStartedAtMs,
                 }));
-                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
-                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
-            }
-            const waitAbortController = new AbortController();
-            const waitAbortTimer = setTimeout(() => waitAbortController.abort(), waitBudget.remainingWaitMs);
-            try {
-                const internalMcpOperation = { operation: "scan_site_wait", scanId: created.scanId ?? created.scan_id ?? created.jobId };
-                const completed = await client.scans.wait(created, {
-                    maxWaitMs: waitBudget.remainingWaitMs,
-                    internalMcpOperation,
-                    signal: waitAbortController.signal,
-                });
-                const guided = withExampleDomainDemo(withMcpAgentGuidance({
-                    ...completed,
-                    ...scanCreationMetadata(created)
-                }), demoSubstitution);
-                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
-            }
-            catch (error) {
-                const scanId = created.scanId ?? created.scan_id;
-                console.warn(JSON.stringify({
-                    event: "mcp.certscore_scan_site.wait_deferred",
-                    errorName: error instanceof Error ? error.name : "UnknownError",
-                    jobId: created.jobId ?? null,
-                    scanId: scanId ?? null,
-                    status: created.status ?? null,
-                    ...waitBudget,
-                }));
-                // Waiting is a convenience layered on top of scan creation. Once the
-                // API has accepted a scan, never turn a transient polling or hydration
-                // failure into an identity-less tool error that encourages callers to
-                // submit a second, non-idempotent certscore_scan_site request.
-                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
-                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
-            }
-            finally {
-                clearTimeout(waitAbortTimer);
             }
+            const guided = withExampleDomainDemo(withMcpAgentGuidance(initialResult, "unknown", "scan_creation"), demoSubstitution);
+            return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
         }
         catch (error) {
+            console.warn(JSON.stringify({
+                event: "mcp.certscore_scan_site.creation_failed",
+                durationMs: Date.now() - creationStartedAtMs,
+                errorName: error instanceof Error ? error.name : "UnknownError",
+            }));
             return toToolError(error);
         }
     });

package/dist/tools.d.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { type FindingList, type JobStatus, type PreConsentCookiesTrackers, type PulseDetail, type PulseFormat, type PulseResult, type ScanResource, type TopFinding } from "@certscore/sdk";
 export declare const MAX_EVIDENCE_PACKET_CHARS = 250000;
+type McpPollGuidanceContext = "scan_creation" | "scan_status" | "upstream";
 type ScanProvenanceMode = "new_scan_started" | "existing_completed_scan_reused" | "existing_scan_retrieved" | "unknown";
 type ActionableError = {
     code: string;
@@ -15,7 +16,7 @@ export declare function toToolResult(payload: unknown, text?: string): CallToolR
 export declare function toToolError(error: unknown): CallToolResult;
 export declare function toInvalidArgumentsToolError(errorMessage: string): CallToolResult;
 export declare function toInvalidScanIdToolError(): CallToolResult;
-export declare function withMcpAgentGuidance<T extends Record<string, any>>(value: T, fallbackProvenanceMode?: ScanProvenanceMode): T & {
+export declare function withMcpAgentGuidance<T extends Record<string, any>>(value: T, fallbackProvenanceMode?: ScanProvenanceMode, pollGuidanceContext?: McpPollGuidanceContext): T & {
     error: ActionableError | null;
     observationOnlyDisclaimer: string;
 };
@@ -65,6 +66,7 @@ export declare function limitPreConsentRows<T extends Record<string, unknown>>(p
     maxRows?: number;
 }): T;
 export declare function scanStatusText(value: Record<string, any>): string;
+export declare function scanSiteText(value: Record<string, any>, leadingLines?: string[]): string;
 export declare function findingListText(value: Record<string, any>, label?: string): string;
 export declare function preConsentInventoryText(value: Record<string, any>): string;
 export declare function pulseReportText(value: Record<string, any>, label?: string): string;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -8,11 +8,14 @@ const MAX_TOOL_TEXT_CHARS = 8_000;
 const LEGAL_REVIEW_DISCLAIMER = "CertScore results are automated public-web observations for human and agentic review, not legal advice, certification, or a compliance determination.";
 const SCAN_PROVENANCE_GROUNDING = "retrievalMode describes how the current tool response obtained the scan; creationDecision describes whether the original scan request created or reused a scan only when that decision is retained. Never infer an unknown creationDecision from scan_id_lookup. For a reused or retrieved existing scan, use only persisted scanFrom and timestamps. Never infer its original scan region from the current request, the user's location, or a default execution region. If persisted region or timestamps are unavailable, report them as unavailable.";
 const INTERPRETATION_STATEMENT = "The CertScore score covers observable public-web scan signals only. Do not infer technologies that are not listed in the returned evidence or any legal compliance status.";
-const SCAN_BUNDLE_RESPONSE_CONTRACT = `Response contract: Report only observed CertScore evidence and CertScore classifications. criticality, priority, and confidence are CertScore metadata; regulatory review lenses are non-determinative CertScore review context—not legal severity, legal exposure, or a compliance determination. Absence of captured consent-action evidence does not establish what happens after Accept, Reject, or Decline. A confirmed post-refusal observation with termination.kind=evidence_satisfied means the observer intentionally stopped after retaining qualifying evidence; do not treat that termination as uncertainty about the returned observation. Keep any separately returned coverage limitation scoped to what was not measured. Do not extrapolate an observed embed, vendor, or request into unobserved cookies, fingerprinting, tracking, or processing, and do not infer violations or compliance beyond what CertScore observed. ${SCAN_PROVENANCE_GROUNDING}`;
-const SCAN_BUNDLE_INTERPRETATION_STATEMENT = "Report only observed CertScore evidence and persisted CertScore classifications. Without corresponding captured post-action evidence, do not infer what Accept, Reject, Decline, or another consent action would do; say the scan does not establish what happens after that action. When postRefusalObservation is confirmed and termination.kind is evidence_satisfied, state the returned post-refusal observation directly and explain that observation stopped intentionally after qualifying evidence was retained. Do not characterize that termination as uncertainty about the observation; mention unmeasured longer-term persistence only when relevant. Do not speculate that an observed embed, vendor, or request may cause additional cookies, fingerprinting, tracking, or processing unless CertScore observed that behavior. Treat returned priority or severity as a CertScore classification, not regulatory criticality or legal exposure; prefer ‘observed privacy risk signal’ or ‘CertScore finding’. Do not infer unobserved technologies, legal compliance, or a legal violation from scores or findings.";
+const SCAN_BUNDLE_RESPONSE_CONTRACT = `Response contract: Report only observed CertScore evidence and CertScore classifications. criticality, priority, and confidence are CertScore metadata; regulatory review lenses are non-determinative CertScore review context—not legal severity, legal exposure, or a compliance determination. Absence of captured consent-action evidence does not establish what happens after Accept, Reject, or Decline. A confirmed post-action observation with termination.kind=evidence_satisfied means the observer intentionally stopped after retaining qualifying evidence; do not treat that termination as uncertainty about the returned observation. Keep any separately returned coverage limitation scoped to what was not measured. Do not extrapolate an observed embed, vendor, or request into unobserved cookies, fingerprinting, tracking, or processing, and do not infer violations or compliance beyond what CertScore observed. ${SCAN_PROVENANCE_GROUNDING}`;
+const SCAN_BUNDLE_INTERPRETATION_STATEMENT = "Report only observed CertScore evidence and persisted CertScore classifications. For gpcResponse, use only GPC response, No observable GPC response, or indeterminate; do not call the result a GPC violation or say GPC was not honored. Keep its jurisdiction-neutral comparison separate from any explicitly returned California scoring policy. Without corresponding captured post-action evidence, do not infer what Accept, Reject, Decline, or another consent action would do; say the scan does not establish what happens after that action. When postAcceptObservation or postRefusalObservation is confirmed and termination.kind is evidence_satisfied, state the returned observation directly and explain that observation stopped intentionally after qualifying evidence was retained. Do not characterize that termination as uncertainty about the observation; mention unmeasured longer-term persistence only when relevant. Treat post-Accept activity as a score-neutral behavior baseline unless a separately projected finding says otherwise. Do not speculate that an observed embed, vendor, or request may cause additional cookies, fingerprinting, tracking, or processing unless CertScore observed that behavior. Treat returned priority or severity as a CertScore classification, not regulatory criticality or legal exposure; prefer ‘observed privacy risk signal’ or ‘CertScore finding’. Do not infer unobserved technologies, legal compliance, or a legal violation from scores or findings.";
 const COMPACT_SCAN_BUNDLE_INTERPRETATION_STATEMENT = "Use only returned CertScore observations and classifications. Do not infer unobserved technologies, post-consent behavior, legal compliance, or violations. Treat priority and severity as CertScore metadata.";
 const OBSERVATION_ONLY_DISCLAIMER = `${LEGAL_REVIEW_DISCLAIMER} No-go, not-observed, and limited-coverage results are not proof of compliance.`;
 const COMPACT_OBSERVATION_ONLY_DISCLAIMER = "Automated public-web observation, not legal advice or a compliance determination; missing or limited evidence is not proof of compliance.";
+const MCP_SCAN_CREATION_POLL_DELAY_SECONDS = 15;
+const MCP_QUEUED_POLL_DELAY_SECONDS = 10;
+const MCP_RUNNING_POLL_DELAY_SECONDS = 5;
 function interpretationGuidance(statement = INTERPRETATION_STATEMENT) {
     return {
         scoreLabel: "CertScore score",
@@ -31,6 +34,15 @@ function toolResultSummary(payload) {
     const status = typeof record.status === "string" ? `; status=${record.status}` : "";
     const scanId = typeof record.scanId === "string" ? `; scanId=${record.scanId}` : "";
     const score = typeof record.score === "number" ? `; CertScore score=${record.score}` : "";
+    const preview = record.preConsentPreview && typeof record.preConsentPreview === "object" && !Array.isArray(record.preConsentPreview)
+        ? record.preConsentPreview
+        : null;
+    const previewSummary = preview?.summary && typeof preview.summary === "object" && !Array.isArray(preview.summary)
+        ? preview.summary
+        : null;
+    const preliminary = preview
+        ? `; preliminary pre-consent preview=cookies ${previewSummary?.cookieCount ?? "unknown"}, trackers ${previewSummary?.trackerCount ?? "unknown"}, third-party requests ${previewSummary?.thirdPartyRequestCount ?? "unknown"}; preview is not final—continue status polling`
+        : "";
     const recordLinks = record.links && typeof record.links === "object" && !Array.isArray(record.links)
         ? record.links
         : null;
@@ -50,7 +62,7 @@ function toolResultSummary(payload) {
         : typeof provenanceRecord?.mode === "string"
             ? `; provenance=${provenanceRecord.mode}`
             : "";
-    return `CertScore ${type}${status}${scanId}${score}${provenance}${report}. Full result is in structuredContent.`;
+    return `CertScore ${type}${status}${scanId}${score}${preliminary}${provenance}${report}. Full result is in structuredContent.`;
 }
 export function toToolResult(payload, text) {
     const structuredContent = payload !== null && typeof payload === "object" && !Array.isArray(payload)
@@ -85,6 +97,7 @@ export function toToolError(error) {
                 ? 30
                 : null;
     const code = error instanceof CertScoreError ? error.code : "internal_error";
+    const reasonCode = terminalError?.reasonCode === "non_public_target" ? "non_public_target" : null;
     const message = error instanceof Error ? error.message : "Unknown CertScore MCP error.";
     const creationRateLimit = terminalError?.creationRateLimit && typeof terminalError.creationRateLimit === "object" && !Array.isArray(terminalError.creationRateLimit)
         ? terminalError.creationRateLimit
@@ -99,6 +112,7 @@ export function toToolError(error) {
     const payload = {
         error: {
             code,
+            reasonCode,
             message,
             retryable,
             retryAfterSeconds,
@@ -271,16 +285,29 @@ function scanProvenance(value, fallbackMode) {
         freshnessDecision: typeof value.freshnessDecision === "string" ? value.freshnessDecision : null
     };
 }
-export function withMcpAgentGuidance(value, fallbackProvenanceMode = "unknown") {
+export function withMcpAgentGuidance(value, fallbackProvenanceMode = "unknown", pollGuidanceContext = "upstream") {
     const status = String(value.status ?? "");
     const active = status === "queued" || status === "running" || status === "finalizing";
     const usable = status === "completed" || status === "completed_limited";
+    const upstreamRetryAfterSeconds = typeof value.retryAfterSeconds === "number" && Number.isFinite(value.retryAfterSeconds)
+        ? Math.max(1, Math.ceil(value.retryAfterSeconds))
+        : null;
+    const retryAfterSeconds = active && pollGuidanceContext === "scan_creation"
+        ? MCP_SCAN_CREATION_POLL_DELAY_SECONDS
+        : active && pollGuidanceContext === "scan_status"
+            ? status === "queued"
+                ? MCP_QUEUED_POLL_DELAY_SECONDS
+                : MCP_RUNNING_POLL_DELAY_SECONDS
+            : upstreamRetryAfterSeconds;
     const error = terminalErrorForResult(value);
     const stableScanId = typeof value.scanId === "string" && value.scanId.trim()
         ? value.scanId.trim()
         : typeof value.scan_id === "string" && value.scan_id.trim()
             ? value.scan_id.trim()
             : null;
+    const hasPreConsentPreview = Boolean(value.preConsentPreview &&
+        typeof value.preConsentPreview === "object" &&
+        !Array.isArray(value.preConsentPreview));
     const reportUrl = usable
         ? typeof value.reportUrl === "string" && value.reportUrl.trim()
             ? value.reportUrl.trim()
@@ -290,24 +317,30 @@ export function withMcpAgentGuidance(value, fallbackProvenanceMode = "unknown")
                     ? `https://certscore.ai/scan/${encodeURIComponent(stableScanId)}`
                     : null
         : null;
+    const returnedNextAction = typeof value.recommendedNextAction === "string" && value.recommendedNextAction.trim()
+        ? value.recommendedNextAction.trim()
+        : null;
+    const activePollAction = `${retryAfterSeconds === null ? "Wait for the recommended delay" : `Wait at least ${retryAfterSeconds} seconds`}, then call certscore_get_scan_status once with scanId ${stableScanId ?? value.jobId}.`;
+    const activeNextAction = `${hasPreConsentPreview ? "The returned preConsentPreview is a partial preview of passive evidence. Its counts are checkpoint-only partial counts, not the full scan tally; do not present them as final totals or stop the workflow. " : ""}${activePollAction} Continue with certscore_get_scan_status using the unchanged scanId ${stableScanId ?? value.jobId}. Do not poll in parallel or resubmit certscore_scan_site while this scan is active. After completed or completed_limited, call certscore_get_scan_bundle for the completed scan's final returned tally, canonical findings, and limitations.`;
     return {
         ...value,
+        retryAfterSeconds,
         error,
         reportUrl,
         scoreLabel: "CertScore score",
         provenance: scanProvenance(value, fallbackProvenanceMode),
         interpretationGuidance: interpretationGuidance(),
         recommendedNextTool: active ? "certscore_get_scan_status" : usable ? "certscore_get_scan_bundle" : null,
-        recommendedNextAction: error?.recommendedNextAction ?? value.recommendedNextAction ?? (active
-            ? `Poll certscore_get_scan_status with scanId ${value.scanId ?? value.jobId} after the recommended delay.`
-            : usable
-                ? `Call certscore_get_scan_bundle with scanId ${value.scanId ?? value.jobId} for the canonical findings and limitations.`
-                : "Review the result and retained limitations."),
+        recommendedNextAction: error?.recommendedNextAction ?? (active
+            ? activeNextAction
+            : returnedNextAction ?? (usable
+                ? `Call certscore_get_scan_bundle with scanId ${stableScanId ?? value.jobId} for the completed scan's final returned tally, canonical findings, and limitations.`
+                : "Review the result and retained limitations.")),
         observationOnlyDisclaimer: OBSERVATION_ONLY_DISCLAIMER
     };
 }
 export function withMcpScanProvenanceGuidance(value, fallbackProvenanceMode) {
-    const guided = withMcpAgentGuidance(value, fallbackProvenanceMode);
+    const guided = withMcpAgentGuidance(value, fallbackProvenanceMode, "scan_status");
     return {
         ...guided,
         interpretationGuidance: interpretationGuidance(`${INTERPRETATION_STATEMENT} ${SCAN_PROVENANCE_GROUNDING}`)
@@ -960,14 +993,162 @@ function canonicalScanProvenanceText(value) {
 }
 export function scanStatusText(value) {
     const reportUrl = reportUrlFor(value);
-    return [
+    const nextAction = typeof value.recommendedNextAction === "string" && value.recommendedNextAction.trim()
+        ? value.recommendedNextAction.trim()
+        : "Review the returned status and retained limitations.";
+    return boundedPreviewResultText([
         `CertScore scan status: status=${value.status ?? "unknown"}.`,
+    ], [...preConsentPreviewTextLines(value), ...terminalLaneResultTextLines(value)], [
+        `Next: ${nextAction}`,
         canonicalScanProvenanceText(value),
         `Full report: ${reportUrl ?? "not available"}.`,
         OBSERVATION_ONLY_DISCLAIMER,
         INTERPRETATION_STATEMENT,
         SCAN_PROVENANCE_GROUNDING
-    ].join("\n");
+    ]);
+}
+export function scanSiteText(value, leadingLines = []) {
+    const scanId = extractScanId(value) ?? "unknown";
+    const active = value.status === "queued" || value.status === "running" || value.status === "finalizing";
+    const nextAction = typeof value.recommendedNextAction === "string" && value.recommendedNextAction.trim()
+        ? value.recommendedNextAction.trim()
+        : active
+            ? `Call certscore_get_scan_status sequentially with scanId ${scanId}; do not resubmit certscore_scan_site.`
+            : "Review the returned result and retained limitations.";
+    return boundedPreviewResultText([...leadingLines,
+        `CertScore scan accepted: scanId=${scanId}; status=${value.status ?? "unknown"}.`,
+    ], [...preConsentPreviewTextLines(value), ...terminalLaneResultTextLines(value)], [
+        `Next: ${nextAction}`,
+        `Provenance: retrieval=${value.provenance?.retrievalMode ?? "unknown"}; creation=${value.provenance?.creationDecision ?? "unknown"}.`,
+        canonicalScanProvenanceText(value),
+        OBSERVATION_ONLY_DISCLAIMER,
+        INTERPRETATION_STATEMENT,
+    ]);
+}
+function terminalLaneResultTextLines(value) {
+    const lines = [];
+    const gpcResponse = value.gpcResponse && typeof value.gpcResponse === "object" && !Array.isArray(value.gpcResponse)
+        ? value.gpcResponse
+        : null;
+    if (gpcResponse) {
+        lines.push(`GPC response: ${gpcResponse.findingTitle ?? "GPC response"}; status=${gpcResponse.status ?? "indeterminate"}; Sec-GPC: 1 proof retained on ${gpcResponse.comparison?.enabledProof?.requestsWithSecGpc ?? 0} request(s).`);
+    }
+    for (const [field, label] of [["postAcceptObservation", "Accept Path"], ["postRefusalObservation", "Reject Path"]]) {
+        const observation = value[field] && typeof value[field] === "object" && !Array.isArray(value[field])
+            ? value[field]
+            : null;
+        if (observation && typeof observation.interpretation === "string") {
+            lines.push(`${label}: ${observation.interpretation}`);
+        }
+    }
+    return lines;
+}
+function compactPreviewValue(value, fallback = "unknown", maxChars = 280) {
+    if (value === null || value === undefined)
+        return fallback;
+    const normalized = String(value).replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return fallback;
+    return normalized.length > maxChars ? `${normalized.slice(0, Math.max(1, maxChars - 1))}…` : normalized;
+}
+function previewObservedTiming(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? `${Math.round(value)}ms (t+${(value / 1_000).toFixed(3)}s)`
+        : "unavailable";
+}
+function preConsentPreviewTextLines(value) {
+    const preview = value.preConsentPreview && typeof value.preConsentPreview === "object" && !Array.isArray(value.preConsentPreview)
+        ? value.preConsentPreview
+        : null;
+    if (!preview)
+        return [];
+    const cookies = Array.isArray(preview.cookies) ? preview.cookies : [];
+    const trackers = Array.isArray(preview.trackers) ? preview.trackers : [];
+    const operationalVendors = Array.isArray(preview.operationalVendors) ? preview.operationalVendors : [];
+    const summary = preview.summary && typeof preview.summary === "object" && !Array.isArray(preview.summary)
+        ? preview.summary
+        : {};
+    const coverage = preview.runtimeCoverage && typeof preview.runtimeCoverage === "object" && !Array.isArray(preview.runtimeCoverage)
+        ? preview.runtimeCoverage
+        : {};
+    const capturedCookieCount = summary.cookieCount ?? cookies.length;
+    const returnedCookieCount = summary.returnedCookieCount ?? cookies.length;
+    const capturedTrackingVendorCount = summary.trackingVendorCount ?? summary.trackerCount ?? trackers.length;
+    const returnedTrackingVendorCount = summary.returnedTrackingVendorCount ?? trackers.length;
+    const capturedOperationalVendorCount = summary.operationalVendorCount ?? operationalVendors.length;
+    const returnedOperationalVendorCount = summary.returnedOperationalVendorCount ?? operationalVendors.length;
+    const lines = [
+        `Partial pre-consent runtime preview: generated=${compactPreviewValue(preview.generatedAt, "unavailable", 80)}; lane=${compactPreviewValue(preview.sourceLane, "runtime_evidence", 80)}; coverage=${compactPreviewValue(coverage.status, "unknown", 80)}; cookies captured=${capturedCookieCount}; cookie identities returned=${returnedCookieCount}; tracking vendors captured=${capturedTrackingVendorCount}; tracking vendor identities returned=${returnedTrackingVendorCount}; operational/security/consent vendors captured=${capturedOperationalVendorCount}; operational identities returned=${returnedOperationalVendorCount}; all classified vendor observations=${summary.vendorCount ?? "unknown"}; third-party requests=${summary.thirdPartyRequestCount ?? "unknown"}.`,
+        "PARTIAL PREVIEW: These are checkpoint-only partial counts, not the full scan tally. Do not present them as final totals or stop the workflow. Wait for terminal scan status, then call certscore_get_scan_bundle for the completed scan's final returned tally, canonical findings, and coverage limitations.",
+        "Metric scope: tracking vendors exclude operational, security, and consent-management vendors. The completed inventory's broader trackerCount may include those categories, so do not compare that field directly with trackingVendorCount.",
+    ];
+    if (cookies.length > 0) {
+        lines.push("Cookies observed before a consent choice (metadata only; no cookie values):");
+        for (const candidate of cookies) {
+            const cookie = candidate && typeof candidate === "object" && !Array.isArray(candidate)
+                ? candidate
+                : {};
+            lines.push(`- Cookie ${compactPreviewValue(cookie.name, "unnamed", 256)}; domain=${compactPreviewValue(cookie.domain, "unavailable", 253)}; party=${compactPreviewValue(cookie.party, "unknown", 40)}; category/purpose=${compactPreviewValue(cookie.purpose, "unknown", 80)}; essentiality=${compactPreviewValue(cookie.essentiality, "unknown", 40)}; observedAtMs=${previewObservedTiming(cookie.observedAtMs)}.`);
+        }
+    }
+    else {
+        lines.push("Cookies observed before a consent choice: none returned in this preliminary preview.");
+    }
+    if (trackers.length > 0) {
+        lines.push("Tracking vendors/products observed before a consent choice:");
+        for (const candidate of trackers) {
+            const tracker = candidate && typeof candidate === "object" && !Array.isArray(candidate)
+                ? candidate
+                : {};
+            const domains = Array.isArray(tracker.domains)
+                ? tracker.domains.map((domain) => compactPreviewValue(domain, "unknown", 253)).join(", ")
+                : "none returned";
+            lines.push(`- Tracking vendor ${compactPreviewValue(tracker.vendor, "unknown", 160)}; product=${compactPreviewValue(tracker.product, "unavailable", 160)}; category/purpose=${compactPreviewValue(tracker.purpose, "unknown", 80)}; confidence=${compactPreviewValue(tracker.confidence, "unknown", 20)}; domains=${compactPreviewValue(domains, "none returned", 800)}.`);
+        }
+        lines.push("Tracker timing: per-tracker first-seen milliseconds are not part of the preliminary preview contract; do not infer them from cookie timing.");
+    }
+    else {
+        lines.push("Tracking vendors/products observed before a consent choice: none returned in this partial preview.");
+    }
+    if (operationalVendors.length > 0) {
+        lines.push("Operational, security, or consent-management vendors observed (separate from trackingVendorCount):");
+        for (const candidate of operationalVendors) {
+            const vendor = candidate && typeof candidate === "object" && !Array.isArray(candidate)
+                ? candidate
+                : {};
+            const domains = Array.isArray(vendor.domains)
+                ? vendor.domains.map((domain) => compactPreviewValue(domain, "unknown", 253)).join(", ")
+                : "none returned";
+            lines.push(`- Operational vendor ${compactPreviewValue(vendor.vendor, "unknown", 160)}; product=${compactPreviewValue(vendor.product, "unavailable", 160)}; category/purpose=${compactPreviewValue(vendor.purpose, "unknown", 80)}; confidence=${compactPreviewValue(vendor.confidence, "unknown", 20)}; domains=${compactPreviewValue(domains, "none returned", 800)}.`);
+        }
+    }
+    if (String(capturedCookieCount) !== String(returnedCookieCount) ||
+        String(capturedTrackingVendorCount) !== String(returnedTrackingVendorCount) ||
+        String(capturedOperationalVendorCount) !== String(returnedOperationalVendorCount)) {
+        lines.push(`Preview identity lists are bounded: ${capturedCookieCount} cookies captured/${returnedCookieCount} identities returned; ${capturedTrackingVendorCount} tracking vendors captured/${returnedTrackingVendorCount} identities returned; ${capturedOperationalVendorCount} operational vendors captured/${returnedOperationalVendorCount} identities returned. Use captured counts for checkpoint coverage and returned arrays for names.`);
+    }
+    const disclaimer = typeof preview.observationOnlyDisclaimer === "string" && preview.observationOnlyDisclaimer.trim()
+        ? preview.observationOnlyDisclaimer.trim()
+        : "Preliminary passive observations only; not findings, a score, or a final result.";
+    lines.push(`${compactPreviewValue(disclaimer, "Preliminary passive observations only.", 500)} Continue sequential status polling until terminal status; at completed or completed_limited, retrieve certscore_get_scan_bundle before reporting the full scan results or final returned tally.`);
+    return lines;
+}
+function boundedPreviewResultText(prefix, bodyLines, suffix) {
+    const lines = [...prefix];
+    let rendered = 0;
+    for (const line of bodyLines) {
+        if ([...lines, line, ...suffix].join("\n").length > MAX_TOOL_TEXT_CHARS)
+            break;
+        lines.push(line);
+        rendered += 1;
+    }
+    if (rendered < bodyLines.length) {
+        const omitted = `${bodyLines.length - rendered} additional preliminary preview line${bodyLines.length - rendered === 1 ? " was" : "s were"} omitted from TextContent to preserve the size limit; all bounded rows remain in structuredContent.`;
+        if ([...lines, omitted, ...suffix].join("\n").length <= MAX_TOOL_TEXT_CHARS)
+            lines.push(omitted);
+    }
+    lines.push(...suffix);
+    return lines.join("\n");
 }
 function boundedResultText(header, bodyLines, value) {
     const footer = [OBSERVATION_ONLY_DISCLAIMER, INTERPRETATION_STATEMENT];
@@ -1066,6 +1247,34 @@ export function scanBundleText(bundle) {
     if (coverage) {
         append(`Coverage: status=${coverage.status ?? "unknown"}; ${coverage.summary ?? "Review limitations before interpreting absence."}`);
     }
+    const gpcResponse = bundle.gpcResponse && typeof bundle.gpcResponse === "object" && !Array.isArray(bundle.gpcResponse)
+        ? bundle.gpcResponse
+        : null;
+    if (gpcResponse) {
+        const proof = gpcResponse.comparison?.enabledProof;
+        const californiaPolicy = gpcResponse.californiaPolicy;
+        append(`GPC response: ${gpcResponse.findingTitle ?? "GPC response"}; status=${gpcResponse.status ?? "indeterminate"}; Sec-GPC: 1 proof retained on ${proof?.requestsWithSecGpc ?? 0} request(s).`);
+        if (californiaPolicy?.applied === true && californiaPolicy.deductionPoints === 15) {
+            append("California scoring policy: −15 points. This score effect is separate from the jurisdiction-neutral GPC comparison.");
+        }
+    }
+    const postAccept = bundle.postAcceptObservation && typeof bundle.postAcceptObservation === "object" && !Array.isArray(bundle.postAcceptObservation)
+        ? bundle.postAcceptObservation
+        : null;
+    if (postAccept && typeof postAccept.interpretation === "string") {
+        const termination = postAccept.termination && typeof postAccept.termination === "object" && !Array.isArray(postAccept.termination)
+            ? postAccept.termination
+            : null;
+        const intentionalEvidenceStop = termination?.kind === "evidence_satisfied" && termination.intentional === true
+            ? " The observation then stopped intentionally because qualifying evidence had been captured."
+            : "";
+        append(`Accept Path: ${postAccept.interpretation}${intentionalEvidenceStop}`);
+        for (const limitation of Array.isArray(postAccept.coverageLimitations)
+            ? postAccept.coverageLimitations.slice(0, 3)
+            : []) {
+            append(`Accept Path coverage limitation: ${limitation}`);
+        }
+    }
     const postRefusal = bundle.postRefusalObservation && typeof bundle.postRefusalObservation === "object" && !Array.isArray(bundle.postRefusalObservation)
         ? bundle.postRefusalObservation
         : null;
@@ -1270,6 +1479,8 @@ export function buildScanBundle(input) {
         scoreVersion: input.scan.scoreVersion ?? null,
         scoreUpdatedAt: input.scan.scoreUpdatedAt ?? null,
         riskLevel: input.scan.riskLevel ?? null,
+        ...(input.scan.gpcResponse ? { gpcResponse: input.scan.gpcResponse } : {}),
+        postAcceptObservation: input.scan.postAcceptObservation ?? null,
         postRefusalObservation: input.scan.postRefusalObservation ?? null,
         provenance: scanProvenance(input.scan, "existing_scan_retrieved"),
         interpretationGuidance: interpretationGuidance(SCAN_BUNDLE_INTERPRETATION_STATEMENT),
@@ -1524,6 +1735,8 @@ export function buildScanBundle(input) {
             scoreVersion: bundle.scoreVersion,
             scoreUpdatedAt: bundle.scoreUpdatedAt,
             riskLevel: bundle.riskLevel,
+            ...(bundle.gpcResponse ? { gpcResponse: bundle.gpcResponse } : {}),
+            postAcceptObservation: bundle.postAcceptObservation,
             postRefusalObservation: bundle.postRefusalObservation,
             provenance: bundle.provenance,
             interpretationGuidance: bundle.interpretationGuidance,