@certscore/mcp 0.2.20 → 0.2.22

package/dist/tools.js

@@ -1,4 +1,17 @@
-import { CertScoreError } from "@certscore/sdk";
+import { apiV2GpcResponseSchema, apiV2ChoicePathExecutionSchema } 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;
+}
+function canonicalChoicePathExecutionText(observation) {
+    const parsed = apiV2ChoicePathExecutionSchema.safeParse(observation.execution);
+    if (!parsed.success)
+        return null;
+    const execution = parsed.data;
+    return `execution=${execution.status}; click completed=${execution.clickCompleted}; observation completed=${execution.observationCompleted}; consent confirmed=${execution.consentConfirmed}.`;
+}
 const MAX_ERROR_RESPONSE_BODY_CHARS = 2_000;
 export const MAX_EVIDENCE_PACKET_CHARS = 250_000;
 const EVIDENCE_STRING_CHARS = 4_000;
@@ -9,10 +22,13 @@ const LEGAL_REVIEW_DISCLAIMER = "CertScore results are automated public-web obse
 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-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 CHOICE_PATH_INTERPRETATION_STATEMENT = "Count execution.status succeeded and succeeded_with_confirmation as successful paths, with confirmation as a separate subset. A click alone is insufficient; registered paths may omit afterAction. Missing legacy execution remains unavailable. ";
 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 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; active workspace members receive self-serve scan access; 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;
@@ -43,8 +59,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
@@ -71,7 +88,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: [
             {
@@ -79,9 +96,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;
@@ -91,7 +108,7 @@ export function toToolError(error) {
     const status = error instanceof CertScoreError ? error.status : undefined;
     const retryable = typeof terminalError?.retryable === "boolean"
         ? terminalError.retryable
-        : status === 429 || (typeof status === "number" && status >= 500);
+        : (error instanceof Error && error.name === "TimeoutError") || status === 429 || (typeof status === "number" && status >= 500);
     const retryAfterSeconds = typeof terminalError?.retryAfterSeconds === "number"
         ? terminalError.retryAfterSeconds
         : error instanceof CertScoreError && "retryAfterSeconds" in error && typeof error.retryAfterSeconds === "number"
@@ -100,28 +117,39 @@ 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
+    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.'
         : 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.";
+            ? `No scan was created. Wait at least ${retryAfterSeconds ?? 30} seconds before retrying. To answer now, use certscore_get_latest_domain_scan if an existing scan meets the user's needs. Do not reconnect or create duplicate requests to bypass a quota.`
+            : typeof terminalError?.recommendedNextAction === "string"
+                ? terminalError.recommendedNextAction
+                : 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,
+            ...((status === 403 || status === 429) ? { upgradeSupportEmail: "support@certscore.ai" } : {}),
+            ...(context.scanCreation && status === 403 ? { scanStarted: false, alternativeTool: "certscore_get_latest_domain_scan" } : {}),
+            ...(targetRejected ? { field: "url", scanStarted: false, inputCorrectionRequired: true } : {}),
             ...(creationRateLimit
-                ? { creationRateLimit }
+                ? { creationRateLimit, scanStarted: false, quotaConsumed: false,
+                    alternativeTool: "certscore_get_latest_domain_scan",
+                    recovery: { action: "wait_for_quota", retryAfterSeconds, requiresReauthorization: false } }
                 : {}),
             ...(error instanceof CertScoreError ? {
                 name: error.name,
@@ -130,26 +158,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,
@@ -157,7 +190,8 @@ export function toInvalidArgumentsToolError(errorMessage) {
         retryable: false,
         retryAfterSeconds: null,
         recommendedNextAction,
-        mcpCode: -32602
+        mcpCode: -32602,
+        ...(validation ? { issues: validation.issues } : {})
     };
     const payload = tool === "certscore_scan_site"
         ? {
@@ -172,28 +206,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;
@@ -204,11 +241,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) {
@@ -246,7 +283,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"
@@ -311,6 +349,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()
@@ -325,8 +369,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,
@@ -340,14 +385,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);
@@ -762,6 +807,10 @@ export function findingsFromReport(report) {
 export function exportFindings(report) {
     return {
         type: "certscore_mcp_findings_export",
+        exportVersion: "certscore.findings-export.v1",
+        exportedAt: new Date().toISOString(),
+        returnedFindingCount: findingsFromReport(report).length,
+        completeness: "canonical findings returned by the report; not a complete inventory of website behavior",
         scanId: scanIdFromPulse(report),
         domain: report.domain ?? report.request?.domain ?? null,
         summary: report.summary ?? null,
@@ -940,7 +989,11 @@ function findingText(finding, priorityLabel = "criticality") {
     const nextStep = typeof finding.nextStep === "string" && finding.nextStep.trim()
         ? `; canonical next step=${boundedText(finding.nextStep.trim(), 180)}`
         : "";
-    return `- ${finding.label ?? finding.id ?? "Projected finding"}; ${priorityLabel}=${finding.criticality ?? "unknown"}; confidence=${finding.confidence ?? "unknown"}; observation=${finding.plainEnglish ?? evidence.summary ?? "No compact description available"}; evidence=${evidence.basis ?? "unknown"}/${evidence.phase ?? "phase unknown"}: ${evidence.summary ?? "No compact evidence summary available"}; review lenses=${lenses}${nextStep}.`;
+    const identity = typeof finding.id === "string" ? `; findingId=${finding.id}` : "";
+    if (finding.plainEnglish == null && evidence.summary == null) {
+        return `- ${finding.label ?? finding.id ?? "Projected finding"}${identity}; ${priorityLabel}=${finding.criticality ?? "unknown"}; confidence=${finding.confidence ?? "unknown"}; description and evidence detail are not included in this response tier.`;
+    }
+    return `- ${finding.label ?? finding.id ?? "Projected finding"}${identity}; ${priorityLabel}=${finding.criticality ?? "unknown"}; confidence=${finding.confidence ?? "unknown"}; observation=${finding.plainEnglish ?? evidence.summary ?? "No compact description available"}; evidence=${evidence.basis ?? "unknown"}/${evidence.phase ?? "phase unknown"}: ${evidence.summary ?? "No compact evidence summary available"}; review lenses=${lenses}${nextStep}.`;
 }
 function executiveOverviewText(summary) {
     if (!summary)
@@ -1022,7 +1075,9 @@ export function scanStatusText(value) {
     const noGoText = canonicalNoGoText(value);
     if (noGoText)
         return noGoText;
-    const reportUrl = reportUrlFor(value);
+    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.";
@@ -1064,6 +1119,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"]]) {
@@ -1071,6 +1129,9 @@ function terminalLaneResultTextLines(value) {
             ? value[field]
             : null;
         if (observation && typeof observation.interpretation === "string") {
+            const execution = canonicalChoicePathExecutionText(observation);
+            if (execution)
+                lines.push(`${label} execution: ${execution}`);
             lines.push(`${label}: ${observation.interpretation}`);
         }
     }
@@ -1110,9 +1171,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) {
@@ -1160,10 +1229,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) {
@@ -1251,7 +1321,10 @@ export function pulseReportText(value, label = "CertScore report") {
     const body = [
         ...(overview ? [overview] : []),
         `Canonical projected findings returned in this ${label.toLocaleLowerCase()}: ${findings.length}.`,
-        ...findings.map((finding) => findingText(finding))
+        ...findings.map((finding) => findingText(finding)),
+        ...(findings.some((finding) => finding.plainEnglish == null && finding.evidence?.summary == null)
+            ? [`For finding descriptions and evidence, call certscore_list_findings with scanId=${scanId}, or certscore_explain_finding with that scanId and a returned findingId. No new scan is needed.`]
+            : [])
     ];
     return boundedResultText(`${label} for ${domain}; scanId=${scanId}${score === null ? "" : `; CertScore score=${score}`}.`, body, value);
 }
@@ -1261,15 +1334,19 @@ export function markdownReportText(value) {
     const excerpt = markdown.length > excerptLimit ? `${markdown.slice(0, excerptLimit)}\n…[markdown truncated for MCP TextContent]` : markdown;
     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) {
+export function scanBundleText(bundle, options = {}) {
     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 = [...(options.lightTrialCta ? [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"}.`,
+        `Risk: ${bundle.riskLevel ?? "unknown"}. Finding IDs (returned): ${Array.isArray(bundle.findings) ? bundle.findings.slice(0, 20).map((finding) => String(finding.id ?? "unknown").slice(0, 120)).join(", ") || "none" : "unavailable"}.`,
+        bundle.preConsentCookiesTrackers
+            ? `Pre-consent inventory: total=${bundle.preConsentCookiesTrackers.total ?? "unknown"}; returned=${bundle.preConsentCookiesTrackers.rows?.length ?? "unknown"}. Counts describe retained coverage, not consent compliance.`
+            : `Pre-consent inventory: ${bundle.mcpMetadata?.omittedSections?.includes("preConsentCookiesTrackers") ? "omitted to fit the response byte limit" : "not included in this response"}. Call certscore_get_pre_consent_cookies_trackers with scanId=${bundle.scanId ?? "unknown"} for retained rows and counts; no new scan is needed.`,
         canonicalScanProvenanceText(bundle),
         `Full report: ${bundle.reportUrl ?? (bundle.scanId ? `https://certscore.ai/scan/${encodeURIComponent(String(bundle.scanId))}` : "not available")}.`
     ];
@@ -1290,6 +1367,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).`);
@@ -1307,6 +1387,9 @@ export function scanBundleText(bundle) {
         const intentionalEvidenceStop = termination?.kind === "evidence_satisfied" && termination.intentional === true
             ? " The observation then stopped intentionally because qualifying evidence had been captured."
             : "";
+        const execution = canonicalChoicePathExecutionText(postAccept);
+        if (execution)
+            append(`Accept Path execution: ${execution}`);
         append(`Accept Path: ${postAccept.interpretation}${intentionalEvidenceStop}`);
         for (const limitation of Array.isArray(postAccept.coverageLimitations)
             ? postAccept.coverageLimitations.slice(0, 3)
@@ -1324,6 +1407,9 @@ export function scanBundleText(bundle) {
         const intentionalEvidenceStop = termination?.kind === "evidence_satisfied" && termination.intentional === true
             ? " The observation then stopped intentionally because qualifying evidence had been captured."
             : "";
+        const execution = canonicalChoicePathExecutionText(postRefusal);
+        if (execution)
+            append(`Reject Path execution: ${execution}`);
         append(`Reject Path: ${postRefusal.interpretation}${intentionalEvidenceStop}`);
         for (const limitation of Array.isArray(postRefusal.coverageLimitations)
             ? postRefusal.coverageLimitations.slice(0, 3)
@@ -1388,9 +1474,6 @@ export function scanBundleText(bundle) {
             append(`${rows.length - rowsRendered} additional returned pre-consent row${rows.length - rowsRendered === 1 ? " was" : "s were"} omitted from TextContent to preserve the size limit; see structuredContent or the report URL.`);
         }
     }
-    else {
-        append("No row-level pre-consent inventory was available for this result; review coverage and limitations before interpreting absence.");
-    }
     lines.push(...footer);
     return lines.join("\n");
 }
@@ -1522,7 +1605,10 @@ 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.postAcceptObservation || input.scan.postRefusalObservation ? CHOICE_PATH_INTERPRETATION_STATEMENT : "") +
+            (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,
@@ -1703,7 +1789,9 @@ export function buildScanBundle(input) {
     }
     if (bundle.mcpMetadata.actualBytes > maxBytes) {
         markBudgetOmitted("duplicateGuidance", "guidance_compacted_to_preserve_priority_content");
-        bundle.interpretationGuidance = interpretationGuidance(COMPACT_SCAN_BUNDLE_INTERPRETATION_STATEMENT);
+        bundle.interpretationGuidance = interpretationGuidance((bundle.postAcceptObservation || bundle.postRefusalObservation
+            ? "Both execution success statuses count; confirmation is separate. Missing execution is unavailable. " : "") +
+            COMPACT_SCAN_BUNDLE_INTERPRETATION_STATEMENT);
         bundle.observationOnlyDisclaimer = COMPACT_OBSERVATION_ONLY_DISCLAIMER;
         bundle.disclaimer = null;
         refresh();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certscore/mcp",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "mcpName": "ai.certscore/mcp",
   "private": false,
   "description": "MCP server for CertScore public website risk-signal workflows.",

package/server-light.json

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

package/server.json

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