@withpica/mcp-server/dist/tools/gap-hints.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * 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