@clien-ai/mcp 0.15.0 → 0.15.1

package/dist/types/receipt-url.js

@@ -0,0 +1,105 @@
+/**
+ * FUL-1219 / FUL-1225: which stored source URLs and platform labels an MCP channel may SHOW, and how a
+ * receipt whose URL the projection withheld still answers the questions its URL used to answer.
+ *
+ * Imports nothing, so `hypothesis-semantics.ts` (which `report.ts` imports) can read it too.
+ *
+ * ⚠️ THE MARKERS BELOW ARE TRUSTED ONLY ON PROJECTED DATA. `projectReportDataForMcp` deletes any
+ * stored copy before it sets them, so a reader must be handed the output of exactly one projection:
+ * on unprojected report JSON a forged `urlWithheld` would read as a reachable receipt.
+ */
+/**
+ * The `href` of a stored source URL an MCP channel may show, 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 safeSourceUrl(value) {
+    if (typeof value !== 'string' || !/^https?:\/\/[\x21-\x7e]+$/i.test(value))
+        return null;
+    return isSafeHttpDestination(value) ? new URL(value).href : null;
+}
+/**
+ * FUL-1225: a stored `platform` label an MCP channel may show: printable ASCII on one line (space
+ * allowed), else null. Anything else (a newline, a bidi or zero-width mark) was not a host label.
+ */
+export function safeSourcePlatform(value) {
+    return typeof value === 'string' && /^[\x20-\x7e]*$/.test(value) ? value : null;
+}
+/**
+ * FUL-534's reachability test: a non-credentialed http(s) URL the WHATWG parser accepts. Decides
+ * whether a receipt earns its GROUNDED / Cited presentation. It is deliberately NOT the display
+ * test ({@link safeSourceUrl}): tightening it would downgrade claims, which FUL-1225 must not do.
+ */
+export function isSafeHttpDestination(value) {
+    if (typeof value !== 'string' || !/^https?:\/\//i.test(value))
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'http:' || url.protocol === 'https:') && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Set by the projection on a `reportEvidence` or persona-source row whose URL it blanked
+ * (`url: ''`) because the URL is unsafe to show, while the stored URL still passed
+ * {@link isSafeHttpDestination}. It means "still a receipt, link withheld".
+ */
+export const RECEIPT_URL_WITHHELD_KEY = 'urlWithheld';
+/**
+ * Set beside {@link RECEIPT_URL_WITHHELD_KEY}: the withheld URL's hostname (ASCII by WHATWG
+ * construction, and re-checked). Integrity checks that compare hosts (`sameNamedVendor`) read it,
+ * so withholding a URL for display never changes an integrity or coverage decision.
+ */
+export const RECEIPT_URL_WITHHELD_HOST_KEY = 'urlWithheldHost';
+/** The hostname the projection preserves for a withheld URL, or null. */
+export function withheldUrlHost(value) {
+    if (!isSafeHttpDestination(value))
+        return null;
+    const host = new URL(value).hostname;
+    return /^[a-z0-9.-]+$/.test(host) ? host : null;
+}
+function asRow(row) {
+    return row !== null && typeof row === 'object' && !Array.isArray(row) ? row : null;
+}
+function isWithheld(record) {
+    return record[RECEIPT_URL_WITHHELD_KEY] === true && record.url === '';
+}
+/**
+ * FUL-534 + FUL-1225: does a receipt row have a safe destination, shown or withheld? Every
+ * receipt-granting reader calls this instead of testing `row.url`, so blanking an unprintable URL
+ * never changes a claim's state or tally.
+ */
+export function receiptRowHasSafeDestination(row) {
+    const record = asRow(row);
+    if (!record)
+        return false;
+    if (isWithheld(record))
+        return true;
+    return isSafeHttpDestination(record.url);
+}
+/** The hostname behind a receipt row's URL, shown or withheld, or null. */
+export function receiptRowHostname(row) {
+    const record = asRow(row);
+    if (!record)
+        return null;
+    if (isWithheld(record)) {
+        const host = record[RECEIPT_URL_WITHHELD_HOST_KEY];
+        return typeof host === 'string' && /^[a-z0-9.-]+$/.test(host) ? host : null;
+    }
+    if (typeof record.url !== 'string')
+        return null;
+    try {
+        return new URL(record.url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=receipt-url.js.map

package/dist/types/receipt-url.js.map

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

package/dist/types/report.js

@@ -13,6 +13,7 @@
  */
 import { z } from 'zod';
 import { CONFIDENCE_BASES, CONFIDENCE_LEVELS, EVIDENCE_SUFFICIENCY_LEVELS, HYPOTHESIS_PRIORITIES, HYPOTHESIS_SEMANTICS_VERSION, LEGACY_HYPOTHESIS_SEMANTICS_VERSION, ROBUSTNESS_OUTCOMES, VERDICT_STATUSES, finalClauseCoverageMatchesIntegrity, hasCoherentRobustnessWorking, hypothesisWebReceiptAuthenticates, normalizeFinalHypothesisState, readRobustnessCounts, reportClaimNeedsIndependentMarketAuthority, robustnessWorkingContradictsSummary, sourceAuthenticatesMarketEconomics, } from '../hypothesis-semantics.js';
+import { RECEIPT_URL_WITHHELD_HOST_KEY, RECEIPT_URL_WITHHELD_KEY, receiptRowHasSafeDestination, safeSourcePlatform, safeSourceUrl, withheldUrlHost, } from './receipt-url.js';
 // ⚠️ A types module importing from `tools/` reads backwards, and it is deliberate.
 // `content-type-display.ts` imports NOTHING — it is the package's content-type vocabulary, which
 // happens to live beside the two renderers that were its first callers, and the FUL-341 coupling
@@ -696,29 +697,9 @@ export function isModelAttestedReportClaim(claim) {
     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;
-    }
-}
+// FUL-1219 / FUL-1225: the URL display and reachability helpers live in `receipt-url.ts` (it imports
+// nothing, so `hypothesis-semantics.ts` can read them too); re-exported for this module's callers.
+export { RECEIPT_URL_WITHHELD_HOST_KEY, RECEIPT_URL_WITHHELD_KEY, isSafeHttpDestination, receiptRowHasSafeDestination, safeSourcePlatform, safeSourceUrl, } from './receipt-url.js';
 /**
  * A single REPORT-level (market/competitor) claim. Shape mirrors {@link ClaimSchema}
  * but carries a `section` instead of a `personaId` — report claims are not attributed
@@ -1208,7 +1189,7 @@ export const ResearchReportDataSchema = z
     reportEvidence: 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.'),
+        .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. A row with `url: ""` and `urlWithheld: true` (plus `urlWithheldHost`) is still a receipt whose stored URL was unsafe to show; its claims keep their state.'),
     /**
      * 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.
@@ -1387,18 +1368,6 @@ export function projectReportDataForMcp(raw) {
     const asProjectionRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
         ? value
         : null;
-    const safeProjectionUrl = (value) => {
-        if (typeof value !== 'string' || !/^https?:\/\//i.test(value))
-            return false;
-        try {
-            const url = new URL(value);
-            return (url.protocol === 'http:' || url.protocol === 'https:') &&
-                !url.username && !url.password;
-        }
-        catch {
-            return false;
-        }
-    };
     const hasProjectionVisibleContent = (value) => typeof value === 'string' &&
         value.replace(/[\p{C}\p{Z}\p{Default_Ignorable_Code_Point}]/gu, '').length > 0;
     const hasHighlights = Object.prototype.hasOwnProperty.call(record, 'interviewHighlights');
@@ -1451,6 +1420,27 @@ export function projectReportDataForMcp(raw) {
         if (!source)
             return rawSource;
         const next = { ...source };
+        // FUL-1225: a URL the display check refuses is blanked, with the host-derived `platform`, so
+        // no channel carries it. The row itself stays, so every RRCP-s{n} / RCP-p{i}-s{j} keeps its
+        // index, and the markers keep FUL-534's reachability answer and the hostname for every
+        // receipt-granting or host-comparing reader (`receiptRowHasSafeDestination`,
+        // `receiptRowHostname`): no claim or integrity decision changes. Stored markers are untrusted.
+        delete next[RECEIPT_URL_WITHHELD_KEY];
+        delete next[RECEIPT_URL_WITHHELD_HOST_KEY];
+        if (Object.prototype.hasOwnProperty.call(source, 'url') && source.url !== '' && !safeSourceUrl(source.url)) {
+            next.url = '';
+            if (Object.prototype.hasOwnProperty.call(source, 'platform'))
+                next.platform = '';
+            const host = withheldUrlHost(source.url);
+            if (host !== null) {
+                next[RECEIPT_URL_WITHHELD_KEY] = true;
+                next[RECEIPT_URL_WITHHELD_HOST_KEY] = host;
+            }
+        }
+        else if (Object.prototype.hasOwnProperty.call(source, 'platform') && safeSourcePlatform(source.platform) === null) {
+            // A platform label that is not printable ASCII on one line reaches no channel either.
+            next.platform = '';
+        }
         if (Object.prototype.hasOwnProperty.call(source, 'quote')) {
             if (typeof source.quote === 'string' && !isDisplaySuitableExcerpt(source.quote)) {
                 // `undefined` is absent on the JSON wire but remains distinguishable from a historical
@@ -1550,6 +1540,14 @@ export function projectReportDataForMcp(raw) {
                     if (!thread)
                         return rawThread;
                     const nextThread = { ...thread };
+                    // FUL-1225: a thread URL is display-only (every forum receipt renders from its cached
+                    // excerpt without one), so an unsafe one is simply dropped.
+                    if (Object.prototype.hasOwnProperty.call(thread, 'url') && thread.url !== '' && !safeSourceUrl(thread.url)) {
+                        delete nextThread.url;
+                    }
+                    if (Object.prototype.hasOwnProperty.call(thread, 'platform') && safeSourcePlatform(thread.platform) === null) {
+                        delete nextThread.platform;
+                    }
                     if (Array.isArray(thread.relevantQuotes)) {
                         nextThread.relevantQuotes = thread.relevantQuotes.filter(isDisplaySuitableExcerpt);
                     }
@@ -1615,9 +1613,9 @@ export function projectReportDataForMcp(raw) {
     const unverifiedEvidence = Array.isArray(record.unverifiedEvidence)
         ? record.unverifiedEvidence.map((rawRow) => {
             const row = asProjectionRecord(rawRow);
-            if (!row || !safeUnverifiedEvidenceUrl(row.url))
+            if (!row || !safeSourceUrl(row.url))
                 return undefined;
-            return Object.fromEntries(Object.keys(UnverifiedEvidenceSchema.shape).filter((key) => key in row).map((key) => [key, row[key]]));
+            return Object.fromEntries(Object.keys(UnverifiedEvidenceSchema.shape).filter((key) => key in row).map((key) => [key, key === 'platform' ? safeSourcePlatform(row[key]) ?? '' : row[key]]));
         })
         : [];
     if (hasUnverifiedEvidence) {
@@ -1653,7 +1651,7 @@ export function projectReportDataForMcp(raw) {
             const row = index === null ? undefined : unverifiedEvidence[index];
             if (!parsed.success || !row || row.section !== claim.section)
                 return [];
-            const href = safeUnverifiedEvidenceUrl(row.url);
+            const href = safeSourceUrl(row.url);
             if (!href || seen.has(href))
                 return [];
             seen.add(href);
@@ -1897,7 +1895,7 @@ export function projectReportDataForMcp(raw) {
                     ? projected.reportEvidence[Number(match[1])]
                     : undefined);
                 return Boolean(source &&
-                    safeProjectionUrl(source.url) &&
+                    receiptRowHasSafeDestination(source) &&
                     (!Object.prototype.hasOwnProperty.call(source, 'quote') ||
                         isDisplaySuitableExcerpt(source.quote)) &&
                     (source.section === 'market' || source.section === 'competitor' || source.section === 'summary'));