@clien-ai/mcp 0.13.8 → 0.15.0

package/dist/types/report.js

@@ -627,6 +627,98 @@ export const ReportClaimAttestationSchema = z
     quote: z.string().describe('The captured snapshot window an independent judge attested — verbatim from OUR snapshot, no exact claim-span pinned.'),
 })
     .passthrough();
+/**
+ * FUL-1219: why an unverified source sits beside a claim. MIRROR of the agent's
+ * `UNVERIFIED_SOURCE_LABELS`; the coupling test pins the values.
+ */
+export const UNVERIFIED_SOURCE_LABELS = ['paid_market_report', 'company_own_page', 'related_source'];
+/** FUL-1219: MIRROR of the agent's `UNVERIFIED_SOURCE_REASONS` (drop reasons + relevance outcomes). */
+export const UNVERIFIED_SOURCE_REASONS = [
+    'no_snapshot',
+    'self_serving_market_source',
+    'market_source_not_independent',
+    'span_unverified',
+    'no_window',
+    'evidence_gate',
+    'unsupported_clause',
+    'relevance_partial',
+    'relevance_abstained',
+];
+/**
+ * FUL-1219: one labelled page found for a NO_RECEIPT claim that did NOT verify. Never a receipt.
+ * MIRROR of the agent's `ReportClaimUnverifiedSourceSchema`. `label` and `reason` stay strict so an
+ * unknown value is never rendered as a guess; the claim-level `.catch(undefined)` absorbs it.
+ */
+export const ReportClaimUnverifiedSourceSchema = z
+    .object({
+    sourceId: z
+        .string()
+        .describe('Pointer ("RUVS-s{n}") into `unverifiedEvidence`. NOT a receipt and never an "RRCP-" id: the page did not verify, and the claim\'s `state` is unchanged by it.'),
+    label: z
+        .enum(UNVERIFIED_SOURCE_LABELS)
+        .describe('Why the page is shown although it did not verify: paid_market_report (a report seller), company_own_page (the subject\'s own site), related_source (on-topic but does not fully support the claim).'),
+    reason: z
+        .enum(UNVERIFIED_SOURCE_REASONS)
+        .describe('The code-owned rejection behind the label (a verifier drop reason or a relevance outcome).'),
+})
+    .passthrough();
+/**
+ * FUL-1219: the `unverifiedEvidence` index an `RUVS-s{n}` id points at, or null. Anchored on
+ * `RUVS-`, so a receipt id (`RRCP-s0`) never resolves into the unverified pool. The schema types
+ * `sourceId` as any string, so every reader resolves through this, never a prefix-stripped index.
+ */
+export function parseUnverifiedSourceId(sourceId) {
+    if (typeof sourceId !== 'string')
+        return null;
+    const match = /^RUVS-s(0|[1-9]\d*)$/.exec(sourceId);
+    if (!match)
+        return null;
+    const index = Number(match[1]);
+    return Number.isSafeInteger(index) ? index : null;
+}
+/**
+ * FUL-1219: whether a report claim is model-ATTESTED — stored `NO_RECEIPT` with an attestation
+ * marker whose `sourceId` and `quote` are both non-blank strings. MIRROR of the app's
+ * `isModelAttestedClaim` (`app/lib/validation/claim-states.ts`).
+ *
+ * ⚠️ Such a claim renders `cited → RRCP-s{n} (NOT a receipt)`. An unverified-source line beside
+ * "cited" would read as support (plan stop condition (d)), so every MCP reader of
+ * `unverifiedSources` skips an attested claim, exactly as the app's `claimUnverifiedSources` does.
+ * Keyed on the marker, not on whether the attested receipt resolves: the app does the same.
+ */
+export function isModelAttestedReportClaim(claim) {
+    if (claim === null || typeof claim !== 'object' || Array.isArray(claim))
+        return false;
+    const { state, attestation } = claim;
+    if (state !== 'NO_RECEIPT' || attestation === null || typeof attestation !== 'object')
+        return false;
+    const { sourceId, quote } = attestation;
+    return typeof sourceId === 'string' && sourceId.trim().length > 0 &&
+        typeof quote === 'string' && quote.trim().length > 0;
+}
+/**
+ * FUL-1219: the `href` of an `unverifiedEvidence` row's URL, or null.
+ *
+ * The producer writes each URL through `normalizeUrl` (`agent/src/exa-fetch-tool.ts`), i.e. a WHATWG
+ * `URL` serialisation, which is always printable ASCII. So a stored URL with any other character —
+ * a newline, a tab, a bidi or zero-width mark, a `←` — was not written by the producer and is
+ * refused. `new URL()` alone would NOT refuse it: the parser silently strips tabs and newlines, so
+ * the raw string would pass and reach `structuredContent` unchanged. Also refuses non-http(s) and
+ * credential-carrying URLs.
+ */
+export function safeUnverifiedEvidenceUrl(value) {
+    if (typeof value !== 'string' || !/^https?:\/\/[\x21-\x7e]+$/i.test(value))
+        return null;
+    try {
+        const url = new URL(value);
+        if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.username || url.password)
+            return null;
+        return url.href;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * A single REPORT-level (market/competitor) claim. Shape mirrors {@link ClaimSchema}
  * but carries a `section` instead of a `personaId` — report claims are not attributed
@@ -657,6 +749,24 @@ export const ReportClaimSchema = z
         .optional()
         .describe('Further receipts for this same GROUNDED claim ("RRCP-s{n}" + verbatim span), each independently code-verified and judged relevant. At most 2; absent on older reports.'),
     attestation: ReportClaimAttestationSchema.optional().describe('MODEL_ATTESTED marker on a NO_RECEIPT claim (forward-prep; presence never implies grounding).'),
+    // Per entry, like the app reader: a label a newer producer adds drops only its own entry, so an
+    // older published client keeps every label it knows on that claim.
+    unverifiedSources: z
+        .array(z.unknown())
+        .transform((items) => items.flatMap((item) => {
+        const parsed = ReportClaimUnverifiedSourceSchema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    }))
+        .optional()
+        .catch(undefined)
+        .describe('Pages the research found for a NO_RECEIPT claim that did NOT verify, each labelled with why ("RUVS-s{n}" into unverifiedEvidence). Never receipts: they change no state and count toward no grounded number. Absent on older reports.'),
+    unverifiedSourcesOmitted: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .catch(undefined)
+        .describe('How many further unverified sources were found beyond the three listed. Absent when none.'),
 })
     .passthrough();
 /**
@@ -698,6 +808,23 @@ export const ReportEvidenceSchema = z
     marketEconomicsAuthority: z.enum(['independent', 'commercial_report_seller', 'unknown']).optional(),
 })
     .passthrough();
+/**
+ * FUL-1219: one row of `unverifiedEvidence`, the pool "RUVS-s{n}" indexes. MIRROR of the agent's
+ * `UnverifiedEvidenceSourceSchema`, with the same lenient scalars as {@link ReportEvidenceSchema}.
+ * Deliberately a separate pool from `reportEvidence`: nothing here is a receipt. No quote, no
+ * title.
+ */
+export const UnverifiedEvidenceSchema = z
+    .object({
+    section: ReportClaimSectionSchema,
+    url: z.string().describe('The captured page URL (normalised by the producer).'),
+    platform: z.string().describe('The host the page came from.'),
+    retrievedAt: z.string().describe('ISO-8601 timestamp of when the page was captured (our run time, NOT a publication date).'),
+    contentType: z.string().optional().describe('Durable content-type stamped from the source by code; absent means unclassified.'),
+    publisherSubjectRelationship: z.enum(['independent', 'self', 'unknown']).optional(),
+    marketEconomicsAuthority: z.enum(['independent', 'commercial_report_seller', 'unknown']).optional(),
+})
+    .passthrough();
 /**
  * FUL-586's completeness confession — see the field's doc comment on
  * {@link ResearchReportDataSchema} for what it means and why it crosses to this surface.
@@ -1082,6 +1209,15 @@ export const ResearchReportDataSchema = z
         .array(ReportEvidenceSchema)
         .optional()
         .describe('The reportClaims receipt pool: cached market/competitor evidence pages ("RRCP-s{n}" indexes this array) with the verbatim highlight a claim\'s span was matched against.'),
+    /**
+     * FUL-1219: the pool behind `reportClaims[].unverifiedSources`. Soft per row so one bad row
+     * becomes a hole and every other "RUVS-s{n}" keeps its index.
+     */
+    unverifiedEvidence: z
+        .array(UnverifiedEvidenceSchema.optional().catch(undefined))
+        .optional()
+        .catch(undefined)
+        .describe('Pages found but NOT verified ("RUVS-s{n}" indexes this array). Never receipts; kept apart from reportEvidence so no receipt pointer resolves here. Absent on older reports.'),
     /**
      * FUL-586 — what this run FAILED to deliver.
      *
@@ -1270,6 +1406,7 @@ export function projectReportDataForMcp(raw) {
     const hasClaims = Object.prototype.hasOwnProperty.call(record, 'claims');
     const hasReportClaims = Object.prototype.hasOwnProperty.call(record, 'reportClaims');
     const hasReportEvidence = Object.prototype.hasOwnProperty.call(record, 'reportEvidence');
+    const hasUnverifiedEvidence = Object.prototype.hasOwnProperty.call(record, 'unverifiedEvidence');
     const hasReportTitle = Object.prototype.hasOwnProperty.call(record, 'reportTitle');
     const hasOverview = Object.prototype.hasOwnProperty.call(record, 'marketOverview') ||
         Object.prototype.hasOwnProperty.call(record, 'communityOverview');
@@ -1285,7 +1422,7 @@ export function projectReportDataForMcp(raw) {
         typeof methodology === 'object' &&
         !Array.isArray(methodology) &&
         Object.prototype.hasOwnProperty.call(methodology, 'redditRetrieval');
-    if (!hasHighlights && !hasRedditNote && !hasHypothesisResults && !hasClaims && !hasReportClaims && !hasReportEvidence && !hasOverview && !hasReportTitle && !hasCrossCutting && !hasPersonas && !hasForumResearch && !hasHypothesisSemanticsVersion && !hasDecisionSpineMetadata)
+    if (!hasHighlights && !hasRedditNote && !hasHypothesisResults && !hasClaims && !hasReportClaims && !hasReportEvidence && !hasUnverifiedEvidence && !hasOverview && !hasReportTitle && !hasCrossCutting && !hasPersonas && !hasForumResearch && !hasHypothesisSemanticsVersion && !hasDecisionSpineMetadata)
         return raw;
     const projected = { ...record };
     // These fields authenticate producer-owned repair, but are not report evidence and never cross
@@ -1471,6 +1608,66 @@ export function projectReportDataForMcp(raw) {
         delete next.attestation;
         return next;
     };
+    // FUL-1219: an unverified-evidence row whose URL is not a plain, credential-free, printable-ASCII
+    // http(s) URL becomes a hole, so no channel carries it and every other RUVS-s{n} keeps its index. A
+    // kept row carries only its declared keys: the pool is text-free by contract, and anything else is
+    // untrusted JSON.
+    const unverifiedEvidence = Array.isArray(record.unverifiedEvidence)
+        ? record.unverifiedEvidence.map((rawRow) => {
+            const row = asProjectionRecord(rawRow);
+            if (!row || !safeUnverifiedEvidenceUrl(row.url))
+                return undefined;
+            return Object.fromEntries(Object.keys(UnverifiedEvidenceSchema.shape).filter((key) => key in row).map((key) => [key, row[key]]));
+        })
+        : [];
+    if (hasUnverifiedEvidence) {
+        projected.unverifiedEvidence = Array.isArray(record.unverifiedEvidence) ? unverifiedEvidence : undefined;
+    }
+    // FUL-1219: unverified sources belong only to a plain (non-attested) NO_RECEIPT claim, and each
+    // entry must resolve through the anchored RUVS parser to a surviving pool row of the claim's own
+    // section; a URL already kept for the claim is dropped (parity with the app's
+    // `claimUnverifiedSources`). Only the three entry fields are copied: other keys are untrusted JSON
+    // (FUL-1067). The omitted count survives only beside a kept entry: a bare "+N more" would point at
+    // nothing. The attestation marker is read on the STORED claim as well, because the projection
+    // above may have dropped an unsuitable attestation: the app still badges that claim "Cited".
+    const projectUnverifiedSources = (value, storedClaim) => {
+        const claim = asProjectionRecord(value);
+        if (!claim)
+            return value;
+        const hasEntries = Object.prototype.hasOwnProperty.call(claim, 'unverifiedSources');
+        const hasOmitted = Object.prototype.hasOwnProperty.call(claim, 'unverifiedSourcesOmitted');
+        if (!hasEntries && !hasOmitted)
+            return claim;
+        const next = { ...claim };
+        delete next.unverifiedSources;
+        delete next.unverifiedSourcesOmitted;
+        if (claim.state !== 'NO_RECEIPT')
+            return next;
+        if (isModelAttestedReportClaim(claim) || isModelAttestedReportClaim(storedClaim))
+            return next;
+        const seen = new Set();
+        const kept = (Array.isArray(claim.unverifiedSources) ? claim.unverifiedSources : []).flatMap((raw) => {
+            const entry = asProjectionRecord(raw);
+            const index = parseUnverifiedSourceId(entry?.sourceId);
+            const parsed = ReportClaimUnverifiedSourceSchema.safeParse(entry);
+            const row = index === null ? undefined : unverifiedEvidence[index];
+            if (!parsed.success || !row || row.section !== claim.section)
+                return [];
+            const href = safeUnverifiedEvidenceUrl(row.url);
+            if (!href || seen.has(href))
+                return [];
+            seen.add(href);
+            return [{ sourceId: parsed.data.sourceId, label: parsed.data.label, reason: parsed.data.reason }];
+        });
+        if (kept.length === 0)
+            return next;
+        next.unverifiedSources = kept;
+        const omitted = claim.unverifiedSourcesOmitted;
+        if (typeof omitted === 'number' && Number.isSafeInteger(omitted) && omitted > 0) {
+            next.unverifiedSourcesOmitted = omitted;
+        }
+        return next;
+    };
     if (hasReportClaims) {
         projected.reportClaims = Array.isArray(record.reportClaims)
             ? record.reportClaims.map((rawClaim) => {
@@ -1536,7 +1733,7 @@ export function projectReportDataForMcp(raw) {
                     return next;
                 }
                 return { ...claim };
-            })
+            }).map((claim, index) => projectUnverifiedSources(claim, record.reportClaims[index]))
             : [];
     }
     if (Object.prototype.hasOwnProperty.call(record, 'claims')) {
@@ -2046,6 +2243,7 @@ export const MCP_REDACTED_PIPELINE_KEYS = [
     'structuredOutputRejection',
     // FUL-1094: internal primary-synthesis diagnostics (hook denial codes, SDK result codes, bytes).
     'synthesisDiagnostics',
+    'personaDiagnostics',
 ];
 export function normalizeMcpPipelineKeyName(key) {
     return key.replace(/[_\-\s]/g, '').toLowerCase();