@davesheffer/hunch 1.41.6 → 1.42.0

package/dist/mcp/server.d.ts

@@ -7,6 +7,7 @@
  * diagnostics go to stderr.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 import { HunchStore } from "../store/hunchStore.js";
 import { type StateFacet } from "../core/stateContract.js";
 import type { Symbol } from "../core/types.js";
@@ -135,6 +136,493 @@ export declare const FILE_EVIDENCE_FIELD: Record<StateFacet, string | null>;
  *  construction, so anything other than an array of strings reads as no
  *  evidence instead of throwing. */
 export declare function fileEvidenceFor(facet: StateFacet, record: Record<string, unknown>): string[];
+/** The list view's gist of an observation: whole sentences until the gist says
+ *  something (≥ FINDING_GIST_MIN chars), clipped to FINDING_GIST_CHARS. A
+ *  period after an abbreviation or a list number is not a sentence end. */
+export declare const firstSentence: (text: string) => string;
+/** Public MCP shape for the canonical delivery envelope. Keeping the schema on
+ *  the tool means orchestrators can consume receipt facts without scraping the
+ *  backward-compatible text block. */
+declare const DELIVERY_OUTPUT_SCHEMA: z.ZodObject<{
+    schema_version: z.ZodLiteral<"hunch.delivery-envelope/1">;
+    profile: z.ZodEnum<{
+        reviewer: "reviewer";
+        builder: "builder";
+        architect: "architect";
+    }>;
+    ranking_policy: z.ZodLiteral<"hunch.delivery-profile/1">;
+    receipt_id: z.ZodString;
+    text: z.ZodString;
+    delivered: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            decisions: "decisions";
+            constraints: "constraints";
+            resources: "resources";
+            bugs: "bugs";
+            findings: "findings";
+            relationships: "relationships";
+        }>;
+        record_id: z.ZodString;
+        rank: z.ZodNumber;
+        delivery_reason: z.ZodEnum<{
+            ranked: "ranked";
+            "blocking-reserved": "blocking-reserved";
+        }>;
+        provenance_status: z.ZodEnum<{
+            current: "current";
+            stale: "stale";
+            unverified: "unverified";
+        }>;
+        token_cost: z.ZodNumber;
+    }, z.core.$strip>>;
+    hypotheses: z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"decision">;
+        record_id: z.ZodString;
+        rank: z.ZodNumber;
+        why: z.ZodString;
+        where: z.ZodArray<z.ZodString>;
+        historical_pattern: z.ZodString;
+        verify: z.ZodString;
+        disprove: z.ZodString;
+        obligations: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            origin: z.ZodEnum<{
+                memory: "memory";
+                manual: "manual";
+                episode: "episode";
+            }>;
+            category: z.ZodEnum<{
+                evidence: "evidence";
+                types: "types";
+                behavior: "behavior";
+                serialization: "serialization";
+                compatibility: "compatibility";
+                other: "other";
+            }>;
+            phase: z.ZodEnum<{
+                session: "session";
+                "after-edit": "after-edit";
+            }>;
+            description: z.ZodString;
+            command_alternatives: z.ZodArray<z.ZodArray<z.ZodString>>;
+            expected: z.ZodObject<{
+                success: z.ZodBoolean;
+                output_includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                output_excludes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    obligations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        origin: z.ZodEnum<{
+            memory: "memory";
+            manual: "manual";
+            episode: "episode";
+        }>;
+        category: z.ZodEnum<{
+            evidence: "evidence";
+            types: "types";
+            behavior: "behavior";
+            serialization: "serialization";
+            compatibility: "compatibility";
+            other: "other";
+        }>;
+        phase: z.ZodEnum<{
+            session: "session";
+            "after-edit": "after-edit";
+        }>;
+        description: z.ZodString;
+        command_alternatives: z.ZodArray<z.ZodArray<z.ZodString>>;
+        expected: z.ZodObject<{
+            success: z.ZodBoolean;
+            output_includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            output_excludes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    supplements: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        delivered: z.ZodBoolean;
+        reason: z.ZodEnum<{
+            empty: "empty";
+            budget: "budget";
+            supplemental: "supplemental";
+            abstained: "abstained";
+        }>;
+        rank: z.ZodNumber;
+        token_cost: z.ZodNumber;
+    }, z.core.$strip>>;
+    omitted: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            decisions: "decisions";
+            constraints: "constraints";
+            resources: "resources";
+            bugs: "bugs";
+            findings: "findings";
+            relationships: "relationships";
+        }>;
+        record_id: z.ZodString;
+        reason: z.ZodEnum<{
+            retired: "retired";
+            "low-confidence": "low-confidence";
+            "landscape-cap": "landscape-cap";
+            budget: "budget";
+            "stale-provenance": "stale-provenance";
+            "endpoint-not-delivered": "endpoint-not-delivered";
+            "insufficient-context": "insufficient-context";
+            "low-relevance": "low-relevance";
+            "actionability-cap": "actionability-cap";
+            "profile-cap": "profile-cap";
+        }>;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    omitted_total: z.ZodOptional<z.ZodNumber>;
+    omitted_truncated: z.ZodOptional<z.ZodBoolean>;
+    omitted_by_reason: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    landscape: z.ZodNullable<z.ZodObject<{
+        schema: z.ZodLiteral<"hunch.landscape-fragment/1">;
+        authority: z.ZodLiteral<"human_confirmed">;
+        target: z.ZodString;
+        resources: z.ZodArray<z.ZodObject<{
+            selectionReason: z.ZodEnum<{
+                "exact-target": "exact-target";
+                "task-match": "task-match";
+                "orientation-root": "orientation-root";
+                "graph-neighbor": "graph-neighbor";
+                "graph-connection": "graph-connection";
+            }>;
+            selectionRank: z.ZodNumber;
+            rank: z.ZodNumber;
+            deliveryReason: z.ZodLiteral<"ranked">;
+            required: z.ZodLiteral<false>;
+            blocking: z.ZodLiteral<false>;
+            provenanceStatus: z.ZodLiteral<"current">;
+            tokenCost: z.ZodNumber;
+            record: z.ZodObject<{
+                schema: z.ZodLiteral<"hunch.resource/1">;
+                id: z.ZodString;
+                kind: z.ZodString;
+                name: z.ZodString;
+                scope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                locator: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                lifecycle: z.ZodDefault<z.ZodEnum<{
+                    active: "active";
+                    deprecated: "deprecated";
+                    retired: "retired";
+                    planned: "planned";
+                }>>;
+                criticality: z.ZodOptional<z.ZodEnum<{
+                    low: "low";
+                    medium: "medium";
+                    high: "high";
+                    critical: "critical";
+                }>>;
+                contract_version: z.ZodOptional<z.ZodString>;
+                provenance: z.ZodObject<{
+                    source: z.ZodString;
+                    confidence: z.ZodNumber;
+                    evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    last_verified: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>;
+                currentness: z.ZodObject<{
+                    status: z.ZodEnum<{
+                        current: "current";
+                        stale: "stale";
+                        unverified: "unverified";
+                    }>;
+                    verified_at: z.ZodOptional<z.ZodString>;
+                    source_revision: z.ZodOptional<z.ZodString>;
+                    source_content_hash: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+                created_at: z.ZodString;
+                updated_at: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strip>>;
+        relationships: z.ZodArray<z.ZodObject<{
+            selectionRank: z.ZodNumber;
+            rank: z.ZodNumber;
+            deliveryReason: z.ZodLiteral<"ranked">;
+            required: z.ZodLiteral<false>;
+            blocking: z.ZodLiteral<false>;
+            provenanceStatus: z.ZodLiteral<"current">;
+            tokenCost: z.ZodNumber;
+            selectionReason: z.ZodLiteral<"graph-connection">;
+            record: z.ZodObject<{
+                schema: z.ZodDefault<z.ZodEnum<{
+                    "hunch.resource-relationship/1": "hunch.resource-relationship/1";
+                    "hunch.edge/1": "hunch.edge/1";
+                }>>;
+                id: z.ZodString;
+                from: z.ZodString;
+                to: z.ZodString;
+                type: z.ZodEnum<{
+                    depends_on: "depends_on";
+                    calls: "calls";
+                    imports: "imports";
+                    contains: "contains";
+                    implements: "implements";
+                    supersedes: "supersedes";
+                    related_to: "related_to";
+                    references: "references";
+                    provides: "provides";
+                    belongs_to: "belongs_to";
+                    implemented_by: "implemented_by";
+                    invokes: "invokes";
+                    exposes: "exposes";
+                    publishes: "publishes";
+                    consumes: "consumes";
+                    reads_from: "reads_from";
+                    writes_to: "writes_to";
+                    builds: "builds";
+                    tests: "tests";
+                    deploys: "deploys";
+                    deployed_on: "deployed_on";
+                    owned_by: "owned_by";
+                    monitored_by: "monitored_by";
+                    governed_by: "governed_by";
+                    source_of_truth_for: "source_of_truth_for";
+                    compatible_with: "compatible_with";
+                    replaces: "replaces";
+                }>;
+                reason: z.ZodDefault<z.ZodString>;
+                strength: z.ZodDefault<z.ZodNumber>;
+                provenance: z.ZodObject<{
+                    source: z.ZodString;
+                    confidence: z.ZodNumber;
+                    evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    last_verified: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>;
+                currentness: z.ZodOptional<z.ZodObject<{
+                    status: z.ZodEnum<{
+                        current: "current";
+                        stale: "stale";
+                        unverified: "unverified";
+                    }>;
+                    verified_at: z.ZodOptional<z.ZodString>;
+                    source_revision: z.ZodOptional<z.ZodString>;
+                    source_content_hash: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+                environment: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                criticality: z.ZodOptional<z.ZodEnum<{
+                    low: "low";
+                    medium: "medium";
+                    high: "high";
+                    critical: "critical";
+                }>>;
+                contract_version: z.ZodOptional<z.ZodString>;
+                metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>>;
+            }, z.core.$strict>;
+        }, z.core.$strip>>;
+        omitted: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                resources: "resources";
+                relationships: "relationships";
+            }>;
+            recordId: z.ZodString;
+            reason: z.ZodEnum<{
+                "landscape-cap": "landscape-cap";
+                budget: "budget";
+                "stale-provenance": "stale-provenance";
+                "endpoint-not-delivered": "endpoint-not-delivered";
+            }>;
+            detail: z.ZodString;
+        }, z.core.$strip>>;
+        reviewIds: z.ZodArray<z.ZodString>;
+        discoveryHashes: z.ZodArray<z.ZodString>;
+        sourceRevisions: z.ZodArray<z.ZodString>;
+        fragmentHash: z.ZodString;
+    }, z.core.$strip>>;
+    budget_tokens: z.ZodNumber;
+    used_chars: z.ZodNumber;
+    accounted_chars: z.ZodNumber;
+    blocking_overflow: z.ZodBoolean;
+    abstention: z.ZodObject<{
+        active: z.ZodBoolean;
+        withheld: z.ZodNumber;
+        reasons: z.ZodObject<{
+            "low-confidence": z.ZodNumber;
+            "insufficient-context": z.ZodNumber;
+            "low-relevance": z.ZodNumber;
+        }, z.core.$strip>;
+        retry_hint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** What tools/list advertises for hunch_context (#368). The landscape fragment embeds
+ *  the full Resource and Edge record schemas (~7k of the ~13k chars), which every
+ *  schema-loading host would pay on every session; it is advertised by its identity
+ *  fields only. The handler still parses the result with the full
+ *  DELIVERY_OUTPUT_SCHEMA, so the delivered shape is exactly as strict as before. */
+declare const DELIVERY_ADVERTISED_OUTPUT_SCHEMA: z.ZodObject<{
+    schema_version: z.ZodLiteral<"hunch.delivery-envelope/1">;
+    profile: z.ZodEnum<{
+        reviewer: "reviewer";
+        builder: "builder";
+        architect: "architect";
+    }>;
+    ranking_policy: z.ZodLiteral<"hunch.delivery-profile/1">;
+    receipt_id: z.ZodString;
+    text: z.ZodString;
+    hypotheses: z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"decision">;
+        record_id: z.ZodString;
+        rank: z.ZodNumber;
+        why: z.ZodString;
+        where: z.ZodArray<z.ZodString>;
+        historical_pattern: z.ZodString;
+        verify: z.ZodString;
+        disprove: z.ZodString;
+        obligations: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            origin: z.ZodEnum<{
+                memory: "memory";
+                manual: "manual";
+                episode: "episode";
+            }>;
+            category: z.ZodEnum<{
+                evidence: "evidence";
+                types: "types";
+                behavior: "behavior";
+                serialization: "serialization";
+                compatibility: "compatibility";
+                other: "other";
+            }>;
+            phase: z.ZodEnum<{
+                session: "session";
+                "after-edit": "after-edit";
+            }>;
+            description: z.ZodString;
+            command_alternatives: z.ZodArray<z.ZodArray<z.ZodString>>;
+            expected: z.ZodObject<{
+                success: z.ZodBoolean;
+                output_includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                output_excludes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    obligations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        origin: z.ZodEnum<{
+            memory: "memory";
+            manual: "manual";
+            episode: "episode";
+        }>;
+        category: z.ZodEnum<{
+            evidence: "evidence";
+            types: "types";
+            behavior: "behavior";
+            serialization: "serialization";
+            compatibility: "compatibility";
+            other: "other";
+        }>;
+        phase: z.ZodEnum<{
+            session: "session";
+            "after-edit": "after-edit";
+        }>;
+        description: z.ZodString;
+        command_alternatives: z.ZodArray<z.ZodArray<z.ZodString>>;
+        expected: z.ZodObject<{
+            success: z.ZodBoolean;
+            output_includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            output_excludes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    omitted_total: z.ZodOptional<z.ZodNumber>;
+    omitted_truncated: z.ZodOptional<z.ZodBoolean>;
+    omitted_by_reason: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    budget_tokens: z.ZodNumber;
+    used_chars: z.ZodNumber;
+    accounted_chars: z.ZodNumber;
+    blocking_overflow: z.ZodBoolean;
+    abstention: z.ZodObject<{
+        active: z.ZodBoolean;
+        withheld: z.ZodNumber;
+        reasons: z.ZodObject<{
+            "low-confidence": z.ZodNumber;
+            "insufficient-context": z.ZodNumber;
+            "low-relevance": z.ZodNumber;
+        }, z.core.$strip>;
+        retry_hint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    delivered: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            decisions: "decisions";
+            constraints: "constraints";
+            resources: "resources";
+            bugs: "bugs";
+            findings: "findings";
+            relationships: "relationships";
+        }>;
+        record_id: z.ZodString;
+        rank: z.ZodOptional<z.ZodNumber>;
+        delivery_reason: z.ZodOptional<z.ZodEnum<{
+            ranked: "ranked";
+            "blocking-reserved": "blocking-reserved";
+        }>>;
+        provenance_status: z.ZodOptional<z.ZodEnum<{
+            current: "current";
+            stale: "stale";
+            unverified: "unverified";
+        }>>;
+        token_cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    supplements: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        delivered: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodEnum<{
+            empty: "empty";
+            budget: "budget";
+            supplemental: "supplemental";
+            abstained: "abstained";
+        }>>;
+        rank: z.ZodOptional<z.ZodNumber>;
+        token_cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    omitted: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            decisions: "decisions";
+            constraints: "constraints";
+            resources: "resources";
+            bugs: "bugs";
+            findings: "findings";
+            relationships: "relationships";
+        }>;
+        record_id: z.ZodString;
+        reason: z.ZodEnum<{
+            retired: "retired";
+            "low-confidence": "low-confidence";
+            "landscape-cap": "landscape-cap";
+            budget: "budget";
+            "stale-provenance": "stale-provenance";
+            "endpoint-not-delivered": "endpoint-not-delivered";
+            "insufficient-context": "insufficient-context";
+            "low-relevance": "low-relevance";
+            "actionability-cap": "actionability-cap";
+            "profile-cap": "profile-cap";
+        }>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    landscape: z.ZodNullable<z.ZodObject<{
+        schema: z.ZodLiteral<"hunch.landscape-fragment/1">;
+        target: z.ZodString;
+        fragmentHash: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+/** What the MCP result names per record: enough to drill down (hunch_why), no
+ *  more. A host shows the model either `content` or `structuredContent`, and
+ *  `text` is the only brief a structured-only host sees, so every other field
+ *  repeats what the brief already says; rank, costs and provenance stay in the
+ *  receipt. Undelivered supplements are dropped (the brief never showed them). */
+export declare function compactEnvelope(envelope: z.infer<typeof DELIVERY_OUTPUT_SCHEMA>): z.infer<typeof DELIVERY_ADVERTISED_OUTPUT_SCHEMA>;
+/** The budget must govern the whole tool result, not only the brief: a host
+ *  that shows the model structuredContent otherwise pays for one repeated
+ *  sentence per withheld record (104 of them measured on this repo, issue #371).
+ *  Keep a few ids — round-robin across reasons so every reason the brief cites
+ *  keeps an id to pass to hunch_why, budget first — and count all of them by
+ *  reason. Runs after recordServed and after the full envelope validated, so
+ *  receipts and receipt_id are unchanged. */
+export declare function compactOmissions(envelope: z.infer<typeof DELIVERY_OUTPUT_SCHEMA>): z.infer<typeof DELIVERY_ADVERTISED_OUTPUT_SCHEMA>;
 /** Resolve a free-form target (symbol id / name / file path) to symbol records.
  *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
  *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
@@ -173,3 +661,4 @@ export declare function buildServer(root: string): McpServer;
 export declare function wireClientRoots(control: RootControlledServer, fallback: string): void;
 /** Start the stdio server (called by `hunch mcp`). */
 export declare function startServer(cwd?: string, options?: RootControlOptions): Promise<void>;
+export {};