@certscore/mcp 0.2.19 → 0.2.21

package/dist/tools.js

@@ -1,4 +1,10 @@
-import { CertScoreError } from "@certscore/sdk";
+import { apiV2GpcResponseSchema } from "@certscore/api-contracts";
+import { withResponseCapture, transferResponseCapture } from "./response-capture.js";
+import { getCertScoreErrorContext, CertScoreError } from "@certscore/sdk";
+function canonicalGpcObservationSummary(value) {
+    const parsed = apiV2GpcResponseSchema.safeParse(value);
+    return parsed.success && parsed.data.contractVersion === "certscore.gpc-response-assessment.v3" ? parsed.data.summary : null;
+}
 const MAX_ERROR_RESPONSE_BODY_CHARS = 2_000;
 export const MAX_EVIDENCE_PACKET_CHARS = 250_000;
 const EVIDENCE_STRING_CHARS = 4_000;
@@ -13,6 +19,8 @@ const SCAN_BUNDLE_INTERPRETATION_STATEMENT = "Report only observed CertScore evi
 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 PREVIEW_OBSERVATION_ONLY_DISCLAIMER = "Preliminary passive observations only; not findings, a score, or a final result.";
+const SUCCESSFUL_BUNDLE_TRIAL_CTA = "Optional user follow-up: To try CertScore with an account, start a 7-day CertScore trial at https://certscore.ai/login?mode=create_account&utm_source=mcp_light&utm_medium=agent&utm_campaign=scan_bundle. Paid plans add scan history, higher limits, and team or production access. OAuth-capable clients can use https://mcp.certscore.ai/mcp after account authorization and any required workspace scope grant; Light remains no-auth.";
 const MCP_SCAN_CREATION_POLL_DELAY_SECONDS = 15;
 const MCP_QUEUED_POLL_DELAY_SECONDS = 10;
 const MCP_RUNNING_POLL_DELAY_SECONDS = 5;
@@ -30,6 +38,9 @@ function toolResultSummary(payload) {
         return "CertScore tool call completed. Read structuredContent for the result.";
     }
     const record = payload;
+    const noGoText = canonicalNoGoText(record);
+    if (noGoText)
+        return noGoText;
     const type = typeof record.type === "string" ? record.type : "result";
     const status = typeof record.status === "string" ? `; status=${record.status}` : "";
     const scanId = typeof record.scanId === "string" ? `; scanId=${record.scanId}` : "";
@@ -40,8 +51,9 @@ function toolResultSummary(payload) {
     const previewSummary = preview?.summary && typeof preview.summary === "object" && !Array.isArray(preview.summary)
         ? preview.summary
         : null;
+    const active = record.status === "queued" || record.status === "running" || record.status === "finalizing";
     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`
+        ? `; preliminary pre-consent preview=cookies ${previewSummary?.cookieCount ?? "unknown"}, trackers ${previewSummary?.trackerCount ?? "unknown"}, third-party requests ${previewSummary?.thirdPartyRequestCount ?? "unknown"}; preview is not final—${active ? "continue status polling" : "follow the terminal result guidance"}`
         : "";
     const recordLinks = record.links && typeof record.links === "object" && !Array.isArray(record.links)
         ? record.links
@@ -68,7 +80,7 @@ export function toToolResult(payload, text) {
     const structuredContent = payload !== null && typeof payload === "object" && !Array.isArray(payload)
         ? payload
         : { value: payload };
-    return {
+    return transferResponseCapture(payload, {
         structuredContent,
         content: [
             {
@@ -76,9 +88,9 @@ export function toToolResult(payload, text) {
                 text: text ?? toolResultSummary(payload)
             }
         ]
-    };
+    });
 }
-export function toToolError(error) {
+export function toToolError(error, context = {}) {
     const responseRecord = error instanceof CertScoreError && error.responseBody && typeof error.responseBody === "object" && !Array.isArray(error.responseBody)
         ? error.responseBody
         : null;
@@ -97,26 +109,33 @@ 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 reasonCode = typeof terminalError?.reasonCode === "string" && ["non_public_target", "domain_not_found", "dns_unavailable"].includes(terminalError.reasonCode) ? terminalError.reasonCode : null;
+    const targetRejected = context.scanCreation === true && code === "invalid_url" && status === 400;
+    const originalMessage = error instanceof Error ? error.message : "Unknown CertScore MCP error.";
+    const message = targetRejected ? `Scan target rejected. No scan was started. ${originalMessage}` : originalMessage;
     const creationRateLimit = terminalError?.creationRateLimit && typeof terminalError.creationRateLimit === "object" && !Array.isArray(terminalError.creationRateLimit)
         ? terminalError.creationRateLimit
         : null;
-    const recommendedNextAction = typeof terminalError?.recommendedNextAction === "string"
-        ? terminalError.recommendedNextAction
-        : creationRateLimit
-            ? `No scan was created. Wait ${retryAfterSeconds ?? 30} seconds, then retry the same request. If the limit continues after that delay, contact support@certscore.ai.`
-            : retryable
-                ? `Wait ${retryAfterSeconds ?? 30} seconds, then retry the same request. Stop and contact support@certscore.ai if the error repeats.`
-                : "Correct the request using the error details, then retry only if the requested operation is still appropriate.";
+    const recommendedNextAction = targetRejected
+        ? reasonCode === "non_public_target"
+            ? "Ask for a publicly reachable HTTP or HTTPS website, then call certscore_scan_site with that URL. Do not retry this private or ineligible target or try to bypass the public-target checks."
+            : 'Check the spelling and DNS of the intended hostname, then call certscore_scan_site with the actual public website URL, for example {"url":"https://example.com"}. A bare domain is accepted, but example.com and www.example.com are different hostnames; use www only if it is the intended site. Do not repeat the same invalid request. If the correct URL is unclear, ask the user.'
+        : typeof terminalError?.recommendedNextAction === "string"
+            ? terminalError.recommendedNextAction
+            : creationRateLimit
+                ? `No scan was created. Wait ${retryAfterSeconds ?? 30} seconds, then retry the same request. If the limit continues after that delay, contact support@certscore.ai.`
+                : retryable
+                    ? `Wait ${retryAfterSeconds ?? 30} seconds, then retry the same request. Stop and contact support@certscore.ai if the error repeats.`
+                    : "Correct the request using the error details, then retry only if the requested operation is still appropriate.";
     const payload = {
         error: {
             code,
             reasonCode,
             message,
-            retryable,
-            retryAfterSeconds,
+            retryable: targetRejected ? false : retryable,
+            retryAfterSeconds: targetRejected ? null : retryAfterSeconds,
             recommendedNextAction,
+            ...(targetRejected ? { field: "url", scanStarted: false, inputCorrectionRequired: true } : {}),
             ...(creationRateLimit
                 ? { creationRateLimit }
                 : {}),
@@ -127,26 +146,31 @@ export function toToolError(error) {
             } : {})
         }
     };
-    return {
-        content: [{ type: "text", text: JSON.stringify(payload) }],
+    return withResponseCapture({
+        content: [
+            { type: "text", text: JSON.stringify(payload) },
+            ...(targetRejected ? [{ type: "text", text: `${message} ${recommendedNextAction}` }] : []),
+        ],
         isError: true
-    };
+    }, { ...(targetRejected || typeof terminalError?.recommendedNextAction !== "string" ? { recommendedNextAction } : {}), ...(getCertScoreErrorContext(error) ? { upstream: getCertScoreErrorContext(error) } : {}) });
 }
-export function toInvalidArgumentsToolError(errorMessage) {
-    const tool = errorMessage.match(/tool ([a-z_]+)/i)?.[1] ?? null;
-    const field = errorMessage.match(/\bat ([a-zA-Z0-9_.-]+)/)?.[1]
+export function toInvalidArgumentsToolError(errorMessage, validation) {
+    const tool = validation?.tool ?? errorMessage.match(/tool ([a-z_]+)/i)?.[1] ?? null;
+    const field = validation?.issues[0]?.field ?? errorMessage.match(/\bat ([a-zA-Z0-9_.-]+)/)?.[1]
         ?? (errorMessage.includes("url") ? "url" : errorMessage.includes("scanId") ? "scanId" : null);
-    const missing = /required|expected string, received undefined/i.test(errorMessage);
-    const message = field
-        ? missing
-            ? `The ${field} field is required.`
-            : `The ${field} field is invalid.`
-        : `The arguments for ${tool ?? "this tool"} are invalid.`;
+    const missing = validation?.issues[0]?.required === true || /required|expected string, received undefined/i.test(errorMessage);
+    const message = validation && validation.issues.length > 1
+        ? `Invalid arguments in fields: ${validation.issues.map(issue => issue.field).join(", ")}.`
+        : field
+            ? missing
+                ? `The ${field} field is required.`
+                : `The ${field} field is invalid.`
+            : `The arguments for ${tool ?? "this tool"} are invalid.`;
     const recommendedNextAction = field === "url"
         ? "Provide a public URL or domain."
         : field === "scanId"
             ? "Provide the stable scanId returned by certscore_scan_site."
-            : "Correct the named fields using the tool input schema, then retry.";
+            : "Correct the named fields using the tool input schema. Omit optional parameters to use defaults; do not send null. Refresh tool discovery (tools/list) for the accepted types, values and limits, then retry.";
     const error = {
         code: "invalid_arguments",
         message,
@@ -154,7 +178,8 @@ export function toInvalidArgumentsToolError(errorMessage) {
         retryable: false,
         retryAfterSeconds: null,
         recommendedNextAction,
-        mcpCode: -32602
+        mcpCode: -32602,
+        ...(validation ? { issues: validation.issues } : {})
     };
     const payload = tool === "certscore_scan_site"
         ? {
@@ -169,28 +194,31 @@ export function toInvalidArgumentsToolError(errorMessage) {
             observationOnlyDisclaimer: OBSERVATION_ONLY_DISCLAIMER
         }
         : { error };
-    return {
+    return withResponseCapture({
         content: [{ type: "text", text: JSON.stringify(payload) }],
         ...(tool === "certscore_scan_site" ? { structuredContent: payload } : {}),
         isError: true
-    };
+    }, { message: error.message, recommendedNextAction: error.recommendedNextAction });
 }
 export function toInvalidScanIdToolError() {
     const error = {
         code: "invalid_scan_id",
         field: "scanId",
-        message: "The scanId must be the canonical UUID returned by certscore_scan_site.",
+        message: "Invalid scanId. Use the unchanged UUID returned by certscore_scan_site. This request did not start a scan.",
         retryable: false,
         retryAfterSeconds: null,
         recommendedNextAction: "Use the unchanged scanId returned by certscore_scan_site. Do not use placeholders, report URLs, domains, or job IDs.",
         mcpCode: -32602
     };
-    return {
+    return withResponseCapture({
         content: [{ type: "text", text: JSON.stringify({ error }) }],
         isError: true
-    };
+    }, { message: error.message, recommendedNextAction: error.recommendedNextAction });
 }
 function terminalErrorForResult(value) {
+    const terminalGuidance = value.status === "failed" || value.status === "expired"
+        ? ` This scan is terminal; polling the same scanId will not resume it. A freshness=refresh request starts a new scan and uses scan quota. Stop if the failure repeats.${typeof value.scanId === "string" && /^[a-f0-9-]{36}$/i.test(value.scanId) ? ` Support reference: ${value.scanId}.` : ""}`
+        : "";
     const existing = value.error && typeof value.error === "object" && !Array.isArray(value.error)
         ? value.error
         : null;
@@ -201,11 +229,11 @@ function terminalErrorForResult(value) {
             message: typeof existing.message === "string" ? existing.message : "The scan did not produce a canonical result.",
             retryable,
             retryAfterSeconds: typeof existing.retryAfterSeconds === "number" ? existing.retryAfterSeconds : retryable ? 30 : null,
-            recommendedNextAction: typeof existing.recommendedNextAction === "string"
+            recommendedNextAction: (typeof existing.recommendedNextAction === "string"
                 ? existing.recommendedNextAction
                 : retryable
                     ? "Wait for the recommended delay, then retry certscore_scan_site with freshness=refresh."
-                    : "Stop and review the scan limitations before deciding whether to change the URL."
+                    : "Stop and review the scan limitations before deciding whether to change the URL.") + (typeof existing.recommendedNextAction === "string" && existing.recommendedNextAction.endsWith(terminalGuidance) ? "" : terminalGuidance)
         };
     }
     if (value.status === "completed_limited" && value.noGo) {
@@ -243,7 +271,8 @@ function terminalErrorForResult(value) {
             recommendedNextAction: "Wait for the recommended delay, then retry the same certscore_scan_site request."
         }
     };
-    return fallback[String(value.status)] ?? null;
+    const error = fallback[String(value.status)];
+    return error ? { ...error, recommendedNextAction: error.recommendedNextAction + terminalGuidance } : null;
 }
 function scanProvenance(value, fallbackMode) {
     const executionMode = value.executionMode === "new_scan" || value.executionMode === "reused_scan"
@@ -308,6 +337,12 @@ export function withMcpAgentGuidance(value, fallbackProvenanceMode = "unknown",
     const hasPreConsentPreview = Boolean(value.preConsentPreview &&
         typeof value.preConsentPreview === "object" &&
         !Array.isArray(value.preConsentPreview));
+    const preConsentPreview = hasPreConsentPreview
+        ? {
+            ...value.preConsentPreview,
+            observationOnlyDisclaimer: PREVIEW_OBSERVATION_ONLY_DISCLAIMER,
+        }
+        : value.preConsentPreview;
     const reportUrl = usable
         ? typeof value.reportUrl === "string" && value.reportUrl.trim()
             ? value.reportUrl.trim()
@@ -322,8 +357,9 @@ export function withMcpAgentGuidance(value, fallbackProvenanceMode = "unknown",
         : 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 {
+    return withResponseCapture({
         ...value,
+        preConsentPreview,
         retryAfterSeconds,
         error,
         reportUrl,
@@ -337,14 +373,14 @@ export function withMcpAgentGuidance(value, fallbackProvenanceMode = "unknown",
                 ? `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
-    };
+    }, error && !value.error && !value.noGo ? { message: error.message, recommendedNextAction: error.recommendedNextAction } : {});
 }
 export function withMcpScanProvenanceGuidance(value, fallbackProvenanceMode) {
     const guided = withMcpAgentGuidance(value, fallbackProvenanceMode, "scan_status");
-    return {
+    return transferResponseCapture(guided, {
         ...guided,
         interpretationGuidance: interpretationGuidance(`${INTERPRETATION_STATEMENT} ${SCAN_PROVENANCE_GROUNDING}`)
-    };
+    });
 }
 export function boundEvidencePacket(payload, maxSerializedChars = MAX_EVIDENCE_PACKET_CHARS) {
     const originalSerializedChars = measureSerializedChars(payload);
@@ -991,8 +1027,37 @@ function canonicalScanProvenanceText(value) {
     const numeric = (field) => typeof field === "number" && Number.isFinite(field) ? String(field) : "unavailable";
     return `Canonical scan provenance: scanId=${present(extractScanId(value))}; scanFrom/execution region=${present(value.scanFrom)}; completedAt=${present(value.completedAt)}; startedAt=${present(value.startedAt)}; createdAt=${present(value.createdAt)}; retrieval mode=${present(value.provenance?.retrievalMode)}; original creation decision=${present(value.provenance?.creationDecision)}; scan age seconds=${numeric(value.provenance?.scanAgeSeconds)}; compatibility provenance mode=${present(value.provenance?.mode)}.`;
 }
+/** Present only the API's retained disposition; never infer blockers from raw evidence. */
+function canonicalNoGo(value) {
+    return value.resultDisposition === "no_go" && value.noGo && typeof value.noGo === "object" && !Array.isArray(value.noGo)
+        ? value.noGo
+        : null;
+}
+function canonicalNoGoText(value) {
+    const noGo = canonicalNoGo(value);
+    if (!noGo)
+        return null;
+    return [
+        `CertScore scan: ${boundedText(noGo.title, 240) ?? "Scan access limitation"}; status=${value.status ?? "completed_limited"}; Not scored.`,
+        boundedText(noGo.explanation, 1_200),
+        boundedText(noGo.summary, 600),
+        noGo.evidenceExcerpt ? `Retained evidence: ${boundedText(noGo.evidenceExcerpt, 1_200)}` : null,
+        noGo.recommendedNextAction ? `Next: ${boundedText(noGo.recommendedNextAction, 1_000)}` : null,
+        typeof noGo.retryLikelyToHelp === "boolean" ? `Retry likely to help: ${noGo.retryLikelyToHelp ? "yes" : "no"}.` : null,
+        value.mcpMetadata?.truncated ? "Additional retained details were omitted to fit the response budget; see omission metadata and the report URL." : null,
+        canonicalScanProvenanceText(value),
+        `Full report: ${reportUrlFor(value) ?? "not available"}.`,
+        OBSERVATION_ONLY_DISCLAIMER,
+        SCAN_PROVENANCE_GROUNDING,
+    ].filter(Boolean).join("\n");
+}
 export function scanStatusText(value) {
-    const reportUrl = reportUrlFor(value);
+    const noGoText = canonicalNoGoText(value);
+    if (noGoText)
+        return noGoText;
+    const reportUrl = value.status === "completed" || value.status === "completed_limited"
+        ? reportUrlFor(value)
+        : null;
     const nextAction = typeof value.recommendedNextAction === "string" && value.recommendedNextAction.trim()
         ? value.recommendedNextAction.trim()
         : "Review the returned status and retained limitations.";
@@ -1008,6 +1073,9 @@ export function scanStatusText(value) {
     ]);
 }
 export function scanSiteText(value, leadingLines = []) {
+    const noGoText = canonicalNoGoText(value);
+    if (noGoText)
+        return noGoText;
     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()
@@ -1031,6 +1099,9 @@ function terminalLaneResultTextLines(value) {
         ? value.gpcResponse
         : null;
     if (gpcResponse) {
+        const observationSummary = canonicalGpcObservationSummary(gpcResponse);
+        if (observationSummary)
+            lines.push(`GPC observation: ${observationSummary}`);
         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"]]) {
@@ -1077,9 +1148,17 @@ function preConsentPreviewTextLines(value) {
     const returnedTrackingVendorCount = summary.returnedTrackingVendorCount ?? trackers.length;
     const capturedOperationalVendorCount = summary.operationalVendorCount ?? operationalVendors.length;
     const returnedOperationalVendorCount = summary.returnedOperationalVendorCount ?? operationalVendors.length;
+    const status = String(value.status ?? "");
+    const active = status === "queued" || status === "running" || status === "finalizing";
+    const usable = status === "completed" || status === "completed_limited";
+    const previewWorkflowGuidance = active
+        ? "Wait for terminal scan status, then call certscore_get_scan_bundle for the completed scan's final returned tally, canonical findings, and coverage limitations."
+        : usable
+            ? "This scan is terminal. Do not use these checkpoint counts as the final tally; call certscore_get_scan_bundle for the canonical findings and coverage limitations."
+            : "This scan is terminal without a completed result. Treat this preview as retained diagnostic context only, do not continue polling, and follow the terminal Next guidance.";
     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.",
+        `PARTIAL PREVIEW: These are checkpoint-only partial counts, not the full scan tally. ${previewWorkflowGuidance}`,
         "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) {
@@ -1127,10 +1206,11 @@ function preConsentPreviewTextLines(value) {
         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.`);
+    lines.push(`${PREVIEW_OBSERVATION_ONLY_DISCLAIMER} ${active
+        ? "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."
+        : usable
+            ? "The scan is terminal; retrieve certscore_get_scan_bundle before reporting the full scan results or final returned tally."
+            : "The scan is terminal without a completed result; do not continue polling or report this preview as a final result."}`);
     return lines;
 }
 function boundedPreviewResultText(prefix, bodyLines, suffix) {
@@ -1203,6 +1283,9 @@ export function preConsentInventoryText(value) {
     return boundedResultText(`Pre-consent cookie/tracker evidence for ${domain}; scanId=${scanId}; ${returned} of ${total} rows returned${truncated ? " (truncated)" : ""}. Enumerate only these observed rows.`, rows.map((row) => preConsentRowText(compactPreConsentRow(row))), value);
 }
 export function pulseReportText(value, label = "CertScore report") {
+    const noGoText = canonicalNoGoText(value);
+    if (noGoText)
+        return noGoText;
     const scanId = extractScanId(value) ?? "unknown";
     const domain = typeof value.domain === "string" ? value.domain : "unknown domain";
     const score = typeof value.summary?.score === "number"
@@ -1226,8 +1309,11 @@ export function markdownReportText(value) {
     return boundedResultText(`CertScore report for scanId=${extractScanId(value) ?? "unknown"}. The following is a bounded canonical report excerpt.`, excerpt ? [excerpt] : ["No Markdown report body was returned."], value);
 }
 export function scanBundleText(bundle) {
+    const noGoText = canonicalNoGoText(bundle);
+    if (noGoText)
+        return noGoText;
     const score = typeof bundle.score === "number" ? `; CertScore score=${bundle.score}` : "";
-    const footer = [OBSERVATION_ONLY_DISCLAIMER, SCAN_BUNDLE_INTERPRETATION_STATEMENT];
+    const footer = [SUCCESSFUL_BUNDLE_TRIAL_CTA, OBSERVATION_ONLY_DISCLAIMER, SCAN_BUNDLE_INTERPRETATION_STATEMENT];
     const lines = [
         SCAN_BUNDLE_RESPONSE_CONTRACT,
         `CertScore scan bundle for ${bundle.domain ?? "unknown domain"}; status=${bundle.status ?? "unknown"}${score}; scanId=${bundle.scanId ?? "unknown"}.`,
@@ -1251,6 +1337,9 @@ export function scanBundleText(bundle) {
         ? bundle.gpcResponse
         : null;
     if (gpcResponse) {
+        const observationSummary = canonicalGpcObservationSummary(gpcResponse);
+        if (observationSummary)
+            append(`GPC observation: ${observationSummary}`);
         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).`);
@@ -1483,7 +1572,9 @@ export function buildScanBundle(input) {
         postAcceptObservation: input.scan.postAcceptObservation ?? null,
         postRefusalObservation: input.scan.postRefusalObservation ?? null,
         provenance: scanProvenance(input.scan, "existing_scan_retrieved"),
-        interpretationGuidance: interpretationGuidance(SCAN_BUNDLE_INTERPRETATION_STATEMENT),
+        interpretationGuidance: interpretationGuidance(input.scan.gpcResponse?.contractVersion === "certscore.gpc-response-assessment.v3"
+            ? SCAN_BUNDLE_INTERPRETATION_STATEMENT.replace("For gpcResponse,", "For the paired gpcResponse.status,") + " Report the separate bounded observation, CMP-recorded state and directly observed requests. Observation completion does not mean GPC was honored."
+            : SCAN_BUNDLE_INTERPRETATION_STATEMENT),
         resultDisposition: input.scan.resultDisposition ?? null,
         noGo: input.scan.noGo ?? null,
         coverage: input.scan.coverage ?? null,
@@ -1516,7 +1607,7 @@ export function buildScanBundle(input) {
         ...(detail === "evidence" || detail === "full"
             ? { evidenceSummary: bundleEvidenceSummary(evidence, allFindings, links, detail === "full") }
             : {}),
-        ...(detail === "full" ? {
+        ...(detail === "full" && Object.keys(report).length > 0 ? {
             fullReport: compactEvidenceValue(deduplicatedReport.residual, {
                 arrayItems: 50,
                 depth: 8,
@@ -1588,14 +1679,27 @@ export function buildScanBundle(input) {
         bundle.mcpMetadata.nextRecommendedMaxBytes = completeBytes <= responseCeilingBytes
             ? Math.max(5_000, Math.ceil(completeBytes / 1_000) * 1_000)
             : null;
-        bundle.recommendedNextAction = canonicalFindingsComplete
+        bundle.recommendedNextAction = canonicalNoGo(bundle)?.recommendedNextAction ?? (canonicalFindingsComplete
             ? "Canonical findings complete; retry only for omitted envelope detail."
             : bundle.mcpMetadata.nextRecommendedMaxBytes
                 ? `Retry with maxBytes=${bundle.mcpMetadata.nextRecommendedMaxBytes} to retrieve the complete requested tier, or open ${bundle.reportUrl ? "the report URL" : "an available content URL"}.`
-                : `The complete requested tier exceeds the MCP byte ceiling; open ${bundle.reportUrl ? "the report URL" : "an available content URL"}.`;
+                : `The complete requested tier exceeds the MCP byte ceiling; open ${bundle.reportUrl ? "the report URL" : "an available content URL"}.`);
         refresh();
     };
     captureFullPayloadBytes();
+    // Access disposition and its remedy outrank optional lane detail in a no-go envelope.
+    // Retained evidence remains available through the reported content URLs.
+    if (canonicalNoGo(bundle)) {
+        for (const section of ["gpcResponse", "postAcceptObservation", "postRefusalObservation"]) {
+            if (bundle.mcpMetadata.actualBytes <= maxBytes)
+                break;
+            if (bundle[section]) {
+                markBudgetOmitted(section, "lane_detail_omitted_to_preserve_no_go");
+                delete bundle[section];
+                refresh();
+            }
+        }
+    }
     if (bundle.mcpMetadata.actualBytes > maxBytes && bundle.fullReport) {
         markBudgetOmitted("fullReport", "full_report_omitted_to_byte_limit");
         delete bundle.fullReport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certscore/mcp",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "mcpName": "ai.certscore/mcp",
   "private": false,
   "description": "MCP server for CertScore public website risk-signal workflows.",
@@ -69,6 +69,7 @@
   },
   "devDependencies": {
     "@certscore/api-contracts": "workspace:*",
-    "@certscore/sdk": "workspace:*"
+    "@certscore/sdk": "workspace:*",
+    "@website-signal-risk-scanner/shared": "workspace:*"
   }
 }

package/server-light.json

@@ -24,7 +24,7 @@
       "theme": "dark"
     }
   ],
-  "version": "0.2.19",
+  "version": "0.2.21",
   "remotes": [
     {
       "type": "streamable-http",

package/server.json

@@ -8,7 +8,7 @@
     "url": "https://github.com/ergoveritas1-alt/certscore.ai",
     "source": "github"
   },
-  "version": "0.2.19",
+  "version": "0.2.21",
   "remotes": [
     {
       "type": "streamable-http",
@@ -20,7 +20,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@certscore/mcp",
-      "version": "0.2.19",
+      "version": "0.2.21",
       "transport": {
         "type": "stdio"
       },