@davesheffer/hunch 1.13.0 → 1.13.1

package/README.md

@@ -16,8 +16,8 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
-> **New in v1.13.0:** CLI, MCP, and edit hooks now share one provenance-checked, hard-budgeted
-> delivery envelope, and local receipts record exactly what reached the agent and why.
+> **New in v1.13.1:** `hunch_context` exposes that provenance-checked, hard-budgeted delivery
+> envelope as MCP structured output and records exactly which returned items reached the client.
 
 See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
 
@@ -82,7 +82,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.13.0
+npm i -g @davesheffer/hunch@1.13.1
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -97,7 +97,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.13.0
+npm i -g @davesheffer/hunch@1.13.1
 git pull
 hunch init
 hunch doctor

package/dist/mcp/server.js

@@ -21,7 +21,9 @@ import { refreshExistingGrounding } from "../integrations/providers.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, workingFiles, workingDiff, pullHunchStatus, sameRemoteUrl } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, overlayMatchesTeamRemote, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
-import { formatContext, formatStructure } from "../core/format.js";
+import { formatStructure } from "../core/format.js";
+import { buildDeliveryEnvelope } from "../core/delivery.js";
+import { recordServed } from "../core/served.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { ConstitutionService, policyEvaluationEnvelope } from "../constitution/service.js";
@@ -82,6 +84,61 @@ const FINDINGS_CAP = 12; // hunch_findings listing
 const SEV_CONSTRAINT = { blocking: 3, warning: 2, advisory: 1 };
 const SEV_BUG = { critical: 4, high: 3, medium: 2, low: 1 };
 const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
+/** 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. */
+const DELIVERY_OUTPUT_SCHEMA = z.object({
+    text: z.string(),
+    delivered: z.array(z.object({
+        kind: z.enum(["constraints", "decisions", "bugs", "findings"]),
+        record_id: z.string(),
+        rank: z.number().int().positive(),
+        delivery_reason: z.enum(["ranked", "blocking-reserved"]),
+        provenance_status: z.enum(["current", "unverified", "stale"]),
+        token_cost: z.number().int().nonnegative(),
+    })),
+    supplements: z.array(z.object({
+        id: z.string(),
+        kind: z.string(),
+        delivered: z.boolean(),
+        reason: z.enum(["supplemental", "budget", "empty"]),
+        rank: z.number().int().positive(),
+        token_cost: z.number().int().nonnegative(),
+    })),
+    omitted: z.array(z.object({
+        kind: z.enum(["constraints", "decisions", "bugs", "findings"]),
+        record_id: z.string(),
+        reason: z.enum(["budget", "stale-provenance", "retired"]),
+        detail: z.string(),
+    })),
+    budget_tokens: z.number().int().nonnegative(),
+    used_chars: z.number().int().nonnegative(),
+    blocking_overflow: z.boolean(),
+});
+/** Return the same human-readable brief older clients consume plus the exact
+ *  machine-readable envelope. Receipt recording is deliberately best-effort:
+ *  recordServed never throws, so telemetry can never cost a delivery. */
+function deliveredContext(root, target, envelope, sessionId) {
+    // Validate before recording: if a future envelope change drifts from the
+    // advertised MCP contract, the SDK will reject the call and the local ledger
+    // must not claim that response was served.
+    const structuredContent = DELIVERY_OUTPUT_SCHEMA.parse(envelope);
+    recordServed(root, structuredContent.delivered.map((item) => ({
+        event: "served",
+        kind: item.kind,
+        record_id: item.record_id,
+        target,
+        session_id: sessionId,
+        rank: item.rank,
+        delivery_reason: item.delivery_reason,
+        provenance_status: item.provenance_status,
+        token_cost: item.token_cost,
+    })));
+    return {
+        content: [{ type: "text", text: structuredContent.text }],
+        structuredContent,
+    };
+}
 // Capture-session tokens live in src/core/capturetoken.ts (pure + testable). These
 // thin wrappers bind the process clock and id source at the call site (§5 Stage 1).
 const issueCaptureToken = () => issueToken(randomUUID, Date.now());
@@ -589,11 +646,19 @@ export function buildServerWithRootControl(initialRoot) {
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
             as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
         },
-    }, async ({ target, budget_tokens, as_of }) => {
+        outputSchema: DELIVERY_OUTPUT_SCHEMA,
+    }, async ({ target, budget_tokens, as_of }, extra) => {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
             return err(`Could not resolve as_of "${as_of}" to a commit.`);
         const ctx = store.assembleContext(target, budget_tokens ?? 1500, { asOf });
+        const options = {
+            root,
+            symbols: store.recs("symbols"),
+            components: store.recs("components"),
+            decisionCorpus: store.recs("decisions"),
+            historical: !!asOf,
+        };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
         // FTS so the assistant always leaves with the closest matches, not a shrug.
@@ -601,17 +666,30 @@ export function buildServerWithRootControl(initialRoot) {
         if (empty && !asOf) {
             const hits = store.search(target, 8);
             if (hits.length) {
-                const lines = hits.map((h) => `• ${h.ref} — ${h.title}\n    ${h.snippet}`);
-                return ok(`No file/symbol resolves for "${target}" — closest graph matches instead:\n\n${lines.join("\n")}\n\n(For a file/symbol brief pass a concrete target; free-text goes through the same search as hunch_query.)`);
+                const resolved = hits.map((hit) => ({ hit, record: store.resolve(hit.ref)?.record }));
+                const fallback = {
+                    ...ctx,
+                    constraints: resolved.filter(({ hit, record }) => hit.kind === "constraints" && !!record).map(({ record }) => record),
+                    decisions: resolved.filter(({ hit, record }) => hit.kind === "decisions" && !!record).map(({ record }) => record),
+                    bugs: resolved.filter(({ hit, record }) => hit.kind === "bugs" && !!record).map(({ record }) => record),
+                    findings: resolved.filter(({ hit, record }) => hit.kind === "findings" && !!record).map(({ record }) => record),
+                };
+                const envelope = buildDeliveryEnvelope(fallback, {
+                    ...options,
+                    supplements: hits
+                        .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind))
+                        .map((hit, index) => ({
+                        id: hit.ref,
+                        kind: `search-${hit.kind}`,
+                        text: `${hit.ref} — ${hit.title}: ${hit.snippet}`,
+                        priority: 100 - index,
+                    })),
+                });
+                return deliveredContext(root, target, envelope, extra.sessionId);
             }
         }
-        return ok(formatContext(ctx, {
-            root,
-            symbols: store.recs("symbols"),
-            components: store.recs("components"),
-            decisionCorpus: store.recs("decisions"),
-            historical: !!asOf,
-        }));
+        const envelope = buildDeliveryEnvelope(ctx, options);
+        return deliveredContext(root, as_of ? `${target} (as_of:${as_of})` : target, envelope, extra.sessionId);
     });
     // -- hunch_now (the hot view: recent activity + roadmap) --------------------
     // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.13.0",
+      "version": "1.13.1",
       "runtimeHint": "npx",
       "packageArguments": [
         {