@withpica/mcp-server 1.3.0

package/dist/tools/exports.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Export Tools - MCP tools for exporting catalog data
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class ExportTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private exportCatalogCsv;
+    private exportSongRegistration;
+    private exportIndustryReady;
+    private exportCatalogAssetReport;
+    private exportAiConsent;
+}
+//# sourceMappingURL=exports.d.ts.map

package/dist/tools/exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.d.ts","sourceRoot":"","sources":["../../src/tools/exports.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAItE,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA8H3D,gBAAgB;YAShB,sBAAsB;YAuBtB,mBAAmB;YAOnB,wBAAwB;YAgDxB,eAAe;CAS9B"}

package/dist/tools/exports.js

@@ -0,0 +1,184 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatAsText, formatSuccess } from "@withpica/mcp-utils";
+import { withBillingGate } from "@withpica/mcp-utils";
+export class ExportTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_export_catalog_csv",
+                    description: "Export the full works catalog as CSV or JSON data. " +
+                        "Returns the data inline. If the user wants to save it as a file, " +
+                        "use pica_download to offer a download card, or share the data directly " +
+                        "and suggest they copy it. Alternatively, exports are available at " +
+                        "https://withpica.com/workspace via the export button.",
+                    workflows: ["export-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            format: {
+                                type: "string",
+                                enum: ["csv", "json"],
+                                description: "Export format (default: csv)",
+                            },
+                        },
+                    },
+                },
+                executor: this.exportCatalogCsv.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_export_song_registration",
+                    description: "Export catalog in song registration format (CWR-compatible) for PRO/CMO registration.",
+                    workflows: ["export-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: withBillingGate(this.pica, "song registration export", this.exportSongRegistration.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_export_industry_ready",
+                    description: "Export industry-ready metadata package — formatted for distribution to publishers, labels, and sync agents.",
+                    workflows: ["export-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: withBillingGate(this.pica, "industry-ready export", this.exportIndustryReady.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_export_catalog_asset_report",
+                    description: "Generate a Catalog Asset Report (CAR) — a unified ZIP bundle with cover PDF, evidence folders, and integrity manifest. Maps creative portfolio data to property-lending equivalents for financial institutions, insurers, PROs, and distributors. Sections include: ownership (title deed equivalent), valuation (surveyor's report), physical assets (contents schedule), agreements (mortgage deed), catalog intelligence (condition report), and summary with equivalence map.",
+                    workflows: ["export-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            sections: {
+                                type: "object",
+                                description: "Which sections to include in the export. Ownership is always included.",
+                                properties: {
+                                    valuation: {
+                                        type: "boolean",
+                                        description: "Include earnings, audio intelligence, DSP presence, completeness scores",
+                                    },
+                                    assets: {
+                                        type: "boolean",
+                                        description: "Include physical asset register with insurance and valuations",
+                                    },
+                                    agreements: {
+                                        type: "boolean",
+                                        description: "Include agreements structure and AI consent status",
+                                    },
+                                    intelligence: {
+                                        type: "boolean",
+                                        description: "Include gap analysis, carbon footprint, diligence readiness",
+                                    },
+                                    audio: {
+                                        type: "boolean",
+                                        description: "Include audio master files (large, opt-in)",
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                executor: withBillingGate(this.pica, "catalog asset report", this.exportCatalogAssetReport.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_export_ai_consent",
+                    description: "Export AI usage consent declarations for all works — " +
+                        "shows which works are human-made, AI-assisted, or AI-generated, " +
+                        "with contributor-level consent tracking for AI model training and licensing.",
+                    workflows: ["export-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.exportAiConsent.bind(this),
+            },
+        ];
+    }
+    async exportCatalogCsv(args) {
+        const result = await this.pica.exports.catalogCsv({
+            format: args.format,
+        });
+        return formatAsText(result);
+    }
+    async exportSongRegistration(_args) {
+        const result = await this.pica.exports.songRegistration();
+        const data = result?.data ?? result;
+        // ADR-146: Surface export gate warnings
+        const parts = ["Song registration export generated"];
+        if (data?.exportReadiness?.blockers?.length > 0) {
+            parts.push(`\n--- export gate (${data.exportReadiness.mode} mode) ---`);
+            for (const b of data.exportReadiness.blockers) {
+                parts.push(`${b.type}: ${b.workTitle} — ${b.resolutionHint}`);
+            }
+            if (data.exportReadiness.mode === "advisory") {
+                parts.push("These issues will block export when enforcement mode is enabled.");
+            }
+        }
+        return formatSuccess(parts.join("\n"), data);
+    }
+    async exportIndustryReady(_args) {
+        const result = await this.pica.exports.industryReady();
+        return formatSuccess("Industry-ready export generated", result);
+    }
+    async exportCatalogAssetReport(args) {
+        const sections = {
+            ownership: true,
+            valuation: args.sections?.valuation ?? true,
+            assets: args.sections?.assets ?? true,
+            agreements: args.sections?.agreements ?? true,
+            intelligence: args.sections?.intelligence ?? true,
+            audio: args.sections?.audio ?? false,
+        };
+        const result = await this.pica.exports.catalogAssetReport({
+            sections,
+            attestation: {
+                signer_name: "MCP Agent",
+                declaration_accepted: true,
+            },
+        });
+        const data = result?.data ?? result;
+        let summary = [
+            `Catalog Asset Report generated`,
+            `Stage: ${data.stage ?? "unknown"}`,
+            `PICA Score: ${data.pica_score ?? "N/A"}${data.pica_grade ? ` (${data.pica_grade})` : ""}`,
+            `Sections: ownership${sections.valuation ? ", valuation" : ""}${sections.assets ? ", assets" : ""}${sections.agreements ? ", agreements" : ""}${sections.intelligence ? ", intelligence" : ""}${sections.audio ? ", audio" : ""}`,
+            data.file_size_bytes
+                ? `Size: ${(data.file_size_bytes / 1024).toFixed(1)} KB`
+                : null,
+            data.download_url ? `Download: ${data.download_url}` : null,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        // ADR-146: Surface export gate warnings
+        if (data?.exportReadiness?.blockers?.length > 0) {
+            summary += `\nExport gate (${data.exportReadiness.mode} mode): ${data.exportReadiness.blockers.length} blocker(s)`;
+            for (const b of data.exportReadiness.blockers.slice(0, 5)) {
+                summary += `\n  ${b.type}: ${b.workTitle} — ${b.resolutionHint}`;
+            }
+            if (data.exportReadiness.blockers.length > 5) {
+                summary += `\n  ... and ${data.exportReadiness.blockers.length - 5} more`;
+            }
+        }
+        return formatSuccess(summary, data);
+    }
+    async exportAiConsent(_args) {
+        const result = await this.pica.exports.aiConsent();
+        return formatSuccess("AI consent declarations exported — shows disclosure level and training rights per work", result);
+    }
+}
+//# sourceMappingURL=exports.js.map

package/dist/tools/exports.js.map

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

package/dist/tools/feedback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Feedback Tools — MCP tool for agent-submitted feedback (ADR-184 slice 8).
+ *
+ * Thin wrapper over the existing /api/feedback → feedbackService pipeline.
+ * Routes via `general_<category>` actionType so the downstream
+ * teamTasksService.createFromGeneralFeedback fan-out handles role routing.
+ *
+ * ADR-187 compliance: response carries content[].text (narratable) — card
+ * rendering deferred to a follow-on per the text-block-is-the-contract rule.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class FeedbackTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private submitFeedback;
+}
+//# sourceMappingURL=feedback.d.ts.map

package/dist/tools/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/tools/feedback.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAK/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAWtE,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAwB3D,cAAc;CAuE7B"}

package/dist/tools/feedback.js

@@ -0,0 +1,100 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { SUBMIT_FEEDBACK_WRITE_PROPERTIES, SUBMIT_FEEDBACK_REQUIRED, } from "@withpica/mcp-utils";
+const VALID_CATEGORIES = ["bug_report", "feature_request", "question", "other"];
+const ROUTING = {
+    bug_report: "devops",
+    feature_request: "ceo",
+    question: "comms",
+    other: "category-mapped",
+};
+export class FeedbackTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_submit_feedback",
+                    description: "File a bug report, feature request, question, or general note " +
+                        "without leaving the conversation. Routes to the correct team " +
+                        "role (bug_report→devops, feature_request→ceo, question→comms, " +
+                        "other→category-mapped) and creates a team_tasks row the " +
+                        "founder reviews directly. Subject is always " +
+                        "the authenticated user; no user_id parameter accepted.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: SUBMIT_FEEDBACK_WRITE_PROPERTIES,
+                        required: SUBMIT_FEEDBACK_REQUIRED,
+                    },
+                },
+                executor: this.submitFeedback.bind(this),
+            },
+        ];
+    }
+    async submitFeedback(args) {
+        const category = args.category;
+        const description = args.description;
+        if (!category) {
+            return {
+                content: [{ type: "text", text: "Error: category is required." }],
+                isError: true,
+            };
+        }
+        if (!VALID_CATEGORIES.includes(category)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: category must be one of ${VALID_CATEGORIES.join(", ")}.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (typeof description !== "string" || description.trim().length === 0) {
+            return {
+                content: [{ type: "text", text: "Error: description is required." }],
+                isError: true,
+            };
+        }
+        // ADR-184 rule 2: reject caller-supplied user_id defensively. The
+        // subject is always the authenticated session/API-key user.
+        const sentiment = args.sentiment === "positive" || args.sentiment === "negative"
+            ? args.sentiment
+            : category === "bug_report"
+                ? "negative"
+                : "positive";
+        const result = await this.pica.feedback.submit({
+            actionType: `general_${category}`,
+            sentiment,
+            comment: description.trim(),
+            portal: "mcp",
+        });
+        const data = result?.data || result;
+        const id = data?.id ?? "unknown";
+        const routed = ROUTING[category];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Feedback submitted as ${category.replace("_", " ")}; ` +
+                        `routed to ${routed} team. Reference ID: ${id}.`,
+                },
+            ],
+            structuredContent: {
+                kind: "pica.card.feedback_submitted",
+                version: 1,
+                data: {
+                    id,
+                    category,
+                    routed_to: routed,
+                    sentiment,
+                },
+            },
+        };
+    }
+}
+//# sourceMappingURL=feedback.js.map

package/dist/tools/feedback.js.map

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

package/dist/tools/forbidden-keywords.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ADR-180 Rule 9 (2026-05-02 amendment) — description hygiene.
+ *
+ * Two filter lists govern what's allowed in tool descriptions:
+ *
+ *   PUBLIC_FORBIDDEN_KEYWORDS: broad. Bans data-source names + concept
+ *   vocabulary so the unauthenticated lobby surface (anon `tools/list`,
+ *   directory tools) gives no architectural intel to callers who haven't
+ *   authenticated yet. Used by `public-filter.ts` to sanitise descriptions
+ *   before they cross the lobby boundary.
+ *
+ *   AUTHENTICATED_FORBIDDEN_KEYWORDS: narrow. Bans only infra / vendor /
+ *   library names whose presence is always wrong regardless of audience —
+ *   they leak hosting + integration choices that aren't load-bearing for
+ *   any agent. Used by the lint at `scripts/lint-mcp-tools.ts` to enforce
+ *   on every tool description, authenticated or not.
+ *
+ * Concept vocabulary that legitimately helps the agent (Tier A/B, cascade,
+ * "→ then:", MCP Apps) stays permitted on the authenticated surface — those
+ * are user-facing concepts the agent can reason about, not implementation
+ * leakage. Data-source names (MLC, ISNI, MusicBrainz, etc.) similarly stay
+ * permitted on the authenticated surface because the agent benefits from
+ * knowing which sources resolved a query.
+ *
+ * The two lists are explicitly disjoint by design — sanitisation for the
+ * lobby surface uses the union (PUBLIC ∪ AUTHENTICATED) since everything
+ * banned for authenticated surfaces is also banned for unauthenticated.
+ */
+/**
+ * Banned on the unauthenticated lobby surface (also banned on authenticated
+ * via union — see PUBLIC_FORBIDDEN_KEYWORDS_FULL below).
+ *
+ * Notably absent: "Spotify" and "YouTube" are public product surface that
+ * customers see in tool names like `pica_import_from_spotify` — hiding
+ * them in lobby descriptions would gut the utility-signal of those tools
+ * without protecting any algorithm.
+ */
+export declare const PUBLIC_FORBIDDEN_KEYWORDS: readonly string[];
+/**
+ * Banned on every tool description, authenticated or not. These are infra /
+ * vendor / library names whose presence in a tool description is always
+ * implementation leakage — agents derive zero useful signal from knowing
+ * the email vendor, audio analysis library, or hosting platform.
+ *
+ * Stripe and Telegram are intentionally NOT banned — those are user-facing
+ * product surfaces (Stripe Checkout, Telegram reminders) the agent must
+ * reference in tool descriptions to drive correct behaviour.
+ */
+export declare const AUTHENTICATED_FORBIDDEN_KEYWORDS: readonly string[];
+/**
+ * The full lobby filter is the union of both lists — anything banned on
+ * authenticated surfaces is also banned on unauthenticated.
+ */
+export declare const PUBLIC_FORBIDDEN_KEYWORDS_FULL: readonly string[];
+/**
+ * Pattern matching any ADR reference (`ADR-123`, `ADR-1`, `ADR-9999` ...).
+ * The `\b` word boundaries prevent false matches on substrings like
+ * `LADRADR-`. ADR references are forbidden in every tool description on
+ * every surface.
+ */
+export declare const ADR_REFERENCE_REGEX: RegExp;
+//# sourceMappingURL=forbidden-keywords.d.ts.map

package/dist/tools/forbidden-keywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden-keywords.d.ts","sourceRoot":"","sources":["../../src/tools/forbidden-keywords.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAetD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAkB7D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAG3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAgB,CAAC"}

package/dist/tools/forbidden-keywords.js

@@ -0,0 +1,99 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * ADR-180 Rule 9 (2026-05-02 amendment) — description hygiene.
+ *
+ * Two filter lists govern what's allowed in tool descriptions:
+ *
+ *   PUBLIC_FORBIDDEN_KEYWORDS: broad. Bans data-source names + concept
+ *   vocabulary so the unauthenticated lobby surface (anon `tools/list`,
+ *   directory tools) gives no architectural intel to callers who haven't
+ *   authenticated yet. Used by `public-filter.ts` to sanitise descriptions
+ *   before they cross the lobby boundary.
+ *
+ *   AUTHENTICATED_FORBIDDEN_KEYWORDS: narrow. Bans only infra / vendor /
+ *   library names whose presence is always wrong regardless of audience —
+ *   they leak hosting + integration choices that aren't load-bearing for
+ *   any agent. Used by the lint at `scripts/lint-mcp-tools.ts` to enforce
+ *   on every tool description, authenticated or not.
+ *
+ * Concept vocabulary that legitimately helps the agent (Tier A/B, cascade,
+ * "→ then:", MCP Apps) stays permitted on the authenticated surface — those
+ * are user-facing concepts the agent can reason about, not implementation
+ * leakage. Data-source names (MLC, ISNI, MusicBrainz, etc.) similarly stay
+ * permitted on the authenticated surface because the agent benefits from
+ * knowing which sources resolved a query.
+ *
+ * The two lists are explicitly disjoint by design — sanitisation for the
+ * lobby surface uses the union (PUBLIC ∪ AUTHENTICATED) since everything
+ * banned for authenticated surfaces is also banned for unauthenticated.
+ */
+/**
+ * Banned on the unauthenticated lobby surface (also banned on authenticated
+ * via union — see PUBLIC_FORBIDDEN_KEYWORDS_FULL below).
+ *
+ * Notably absent: "Spotify" and "YouTube" are public product surface that
+ * customers see in tool names like `pica_import_from_spotify` — hiding
+ * them in lobby descriptions would gut the utility-signal of those tools
+ * without protecting any algorithm.
+ */
+export const PUBLIC_FORBIDDEN_KEYWORDS = [
+    "MLC",
+    "ISNI",
+    "MusicBrainz",
+    "Wikidata",
+    "Discogs",
+    "ACRCloud",
+    "cascade",
+    "Tier A",
+    "Tier B",
+    "ADR-164",
+    "ADR-179",
+    "identity graph",
+    "identity-graph",
+    "CAR scoring",
+];
+/**
+ * Banned on every tool description, authenticated or not. These are infra /
+ * vendor / library names whose presence in a tool description is always
+ * implementation leakage — agents derive zero useful signal from knowing
+ * the email vendor, audio analysis library, or hosting platform.
+ *
+ * Stripe and Telegram are intentionally NOT banned — those are user-facing
+ * product surfaces (Stripe Checkout, Telegram reminders) the agent must
+ * reference in tool descriptions to drive correct behaviour.
+ */
+export const AUTHENTICATED_FORBIDDEN_KEYWORDS = [
+    "Railway",
+    "Postmark",
+    // SendGrid + Resend intentionally omitted:
+    //   - SendGrid: not in use. CLAUDE.md still lists it as "legacy" but
+    //     this is stale per a 2026-05-02 confirmation; the codebase
+    //     transactional email path is Postmark-only.
+    //   - "Resend" the email vendor collides with the English verb "resend"
+    //     used in tool names (`pica_collaborators_invite_resend`,
+    //     `pica_send_resend`) and their descriptions ("Resend a pending
+    //     collaboration invite"). Too close to the verb to lint safely;
+    //     PR review catches the rare vendor-name leakage.
+    "Librosa",
+    "Groq",
+    "Whisper",
+    "Supabase",
+    "Sentry",
+    "Vercel",
+];
+/**
+ * The full lobby filter is the union of both lists — anything banned on
+ * authenticated surfaces is also banned on unauthenticated.
+ */
+export const PUBLIC_FORBIDDEN_KEYWORDS_FULL = [
+    ...PUBLIC_FORBIDDEN_KEYWORDS,
+    ...AUTHENTICATED_FORBIDDEN_KEYWORDS,
+];
+/**
+ * Pattern matching any ADR reference (`ADR-123`, `ADR-1`, `ADR-9999` ...).
+ * The `\b` word boundaries prevent false matches on substrings like
+ * `LADRADR-`. ADR references are forbidden in every tool description on
+ * every surface.
+ */
+export const ADR_REFERENCE_REGEX = /\bADR-\d+\b/;
+//# sourceMappingURL=forbidden-keywords.js.map

package/dist/tools/forbidden-keywords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden-keywords.js","sourceRoot":"","sources":["../../src/tools/forbidden-keywords.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC1D,KAAK;IACL,MAAM;IACN,aAAa;IACb,UAAU;IACV,SAAS;IACT,UAAU;IACV,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,SAAS;IACT,gBAAgB;IAChB,gBAAgB;IAChB,aAAa;CACd,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAsB;IACjE,SAAS;IACT,UAAU;IACV,2CAA2C;IAC3C,qEAAqE;IACrE,gEAAgE;IAChE,iDAAiD;IACjD,wEAAwE;IACxE,8DAA8D;IAC9D,oEAAoE;IACpE,oEAAoE;IACpE,sDAAsD;IACtD,SAAS;IACT,MAAM;IACN,SAAS;IACT,UAAU;IACV,QAAQ;IACR,QAAQ;CACT,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAsB;IAC/D,GAAG,yBAAyB;IAC5B,GAAG,gCAAgC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC"}

package/dist/tools/gap-hints.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ADR-193 Surface 2 — gap_hints envelope
+ *
+ * Proactive capability-named hints appended to read-tool results. When
+ * a real gap exists on an entity, a hint names the peer-MCP capability
+ * that could fill it (email_search, drive_search, filesystem_search,
+ * notes_search, calendar_search — never vendor names like gmail/notion
+ * per ADR-190 Principle 2) and pre-fills the `then_call` shape the
+ * agent should emit back into PICA.
+ *
+ * Gated by MCP_GAP_HINTS_ENABLED=1. Off in prod by default; staging
+ * enables for holdout verification. Empty array means no real gap —
+ * the envelope is additive, never misleading (ADR-193 AC 7).
+ *
+ * Separate from `CompletionHint` (mcp-utils/formatting.ts): that is a
+ * reactive "what's missing" summary; this is a proactive "what to do
+ * next, via which peer capability" pointer with a concrete call shape.
+ */
+export type GapCapability = "email_search" | "drive_search" | "filesystem_search" | "notes_search" | "calendar_search" | "web_search";
+export interface GapHint {
+    gap: string;
+    capability: GapCapability;
+    rationale: string;
+    query_shape: string;
+    then_call: string;
+    then_args_shape: Record<string, unknown>;
+}
+/**
+ * Read MCP_GAP_HINTS_ENABLED at call time. Not cached so tests can flip
+ * it per-case. Returns true only for the explicit "1" value, mirroring
+ * the MCP_LAYERED_DISCOVERY pattern at mcp-server/src/config.ts.
+ */
+export declare function gapHintsEnabled(): boolean;
+/**
+ * A work is missing an executed agreement when:
+ *  - the `agreements` section is empty, OR
+ *  - none of its agreements have a fully-executed status
+ *
+ * We stay conservative — only fire when there's a clear gap, not when
+ * the caller just didn't request the agreements section.
+ */
+export declare function computeWorkGapHints(workResult: Record<string, unknown>): GapHint[];
+export declare function computeAgreementGapHints(agreementResult: Record<string, unknown>): GapHint[];
+export declare function computePersonGapHints(personResult: Record<string, unknown>): GapHint[];
+/**
+ * When the pending-proposals list is empty, surface a hint reminding
+ * the agent that peer MCPs may hold evidence that would produce
+ * proposals. This is the weakest of the four surfaces — the list tool
+ * doesn't know which entity's proposals are missing — so we only fire
+ * on the empty case and cite the generic flow.
+ */
+export declare function computeProposalListGapHints(listResult: Array<unknown> | undefined): GapHint[];
+//# sourceMappingURL=gap-hints.d.ts.map

package/dist/tools/gap-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gap-hints.d.ts","sourceRoot":"","sources":["../../src/tools/gap-hints.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,cAAc,GACd,mBAAmB,GACnB,cAAc,GACd,iBAAiB,GACjB,YAAY,CAAC;AAEjB,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,EAAE,CAsDX;AAMD,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvC,OAAO,EAAE,CAuEX;AAMD,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,EAAE,CAyEX;AAMD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS,GACrC,OAAO,EAAE,CA4BX"}