@productbrain/mcp 0.0.1-beta.160 → 0.0.1-beta.162

package/dist/{chunk-LKUFRQUO.js → chunk-EPAHRXLQ.js}

@@ -1838,7 +1838,15 @@ var captureSchema = z2.object({
   sourceRef: z2.string().optional().describe("URI or path of the source document backing this entry (e.g. 'meeting-2026-03-28.md', 'import://batch-5'). Stored as top-level entry field, not in data."),
   sourceExcerpt: z2.string().optional().describe("Verbatim excerpt from the source that backs this entry's claims. Stored as top-level entry field, not in data."),
   // WP-316 S3: Preview gate — dry-run mode. Returns what would happen, no DB writes.
-  preview: z2.boolean().optional().describe("If true, validates the capture without writing. Returns what would happen. Default false.")
+  preview: z2.boolean().optional().describe("If true, validates the capture without writing. Returns what would happen. Default false."),
+  // WP-318 S2: Pre-write grounding — run link suggestion before creating entry.
+  suggestOnly: z2.boolean().optional().describe(
+    "If true, runs pre-write grounding (suggestLinksForCapture) and returns a groundingReport WITHOUT creating any entry. Use to preview graph participation before committing. Default false."
+  ),
+  // WP-318 S2: Format for groundingReport in response.
+  format: z2.enum(["agent", "human"]).optional().describe(
+    "Response format for grounding data. 'agent' (default): full JSON groundingReport. 'human': compressed summary string appended to the capture summary."
+  )
 });
 var batchCaptureSchema = z2.object({
   entries: z2.array(z2.object({
@@ -2266,7 +2274,7 @@ function registerSmartCaptureTools(server) {
       inputSchema: captureSchema.shape,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    withEnvelope(async ({ collection, name, description, context, entryId, canonicalKey, data: userData, links, autoCommit, sourceRef, sourceExcerpt, preview }) => {
+    withEnvelope(async ({ collection, name, description, context, entryId, canonicalKey, data: userData, links, autoCommit, sourceRef, sourceExcerpt, preview, suggestOnly, format }) => {
       requireWriteAccess();
       const timingStart = Date.now();
       const wsCtx = await getWorkspaceContext();
@@ -2341,6 +2349,71 @@ Or use \`collections action=list\` to see available collections.`
           )
         };
       }
+      const skipAutoDiscoveryEarly = links && links.length > 0;
+      const groundingStart = Date.now();
+      const groundingPromise = !skipAutoDiscoveryEarly && (name || description) ? mcpQuery("chain.suggestLinksForCapture", {
+        entries: [{ name, description: description ?? "", collectionHint: resolvedCollection }],
+        limit: 5,
+        threshold: 2
+      }).catch(() => null) : Promise.resolve(null);
+      const groundingRaw = await groundingPromise;
+      const groundingElapsedMs = Date.now() - groundingStart;
+      const groundingEntry = groundingRaw?.[0] ?? null;
+      const groundingRelated = groundingEntry?.related ?? [];
+      const groundingDuplicates = groundingEntry?.duplicates ?? [];
+      const groundingGovernance = (groundingEntry?.governance ?? []).map((g) => ({
+        entryId: g.entryId,
+        name: g.name,
+        collectionSlug: g.collectionSlug
+      }));
+      const groundingReport = {
+        related: groundingRelated.map((r) => ({
+          entryId: r.entryId,
+          name: r.name,
+          collectionSlug: r.collectionSlug,
+          overlapRatio: r.overlapRatio,
+          recommendedRelationType: r.recommendedRelationType,
+          reasoning: r.reasoning
+        })),
+        duplicates: groundingDuplicates.map((d) => ({
+          entryId: d.entryId,
+          name: d.name,
+          collectionSlug: d.collectionSlug,
+          matchType: d.matchType,
+          overlapRatio: d.overlapRatio
+        })),
+        governance: groundingGovernance
+      };
+      if (suggestOnly) {
+        const hasSuggestions = groundingReport.related.length > 0 || groundingReport.duplicates.length > 0;
+        const summaryText = hasSuggestions ? `Grounding preview for "${name}": ${groundingReport.related.length} related, ${groundingReport.duplicates.length} possible duplicates. No entry created.` : `Grounding preview for "${name}": no similar entries found. Safe to capture.`;
+        return {
+          content: [{
+            type: "text",
+            text: `# Grounding Preview \u2014 No Entry Created
+
+${summaryText}
+
+` + (groundingReport.related.length > 0 ? `## Related entries
+${groundingReport.related.map((r) => `- **${r.entryId}** ${r.name} [${r.collectionSlug}] \u2014 ${r.reasoning}`).join("\n")}
+
+` : "") + (groundingReport.duplicates.length > 0 ? `## Possible duplicates
+${groundingReport.duplicates.map((d) => `- **${d.entryId}** ${d.name} [${d.collectionSlug}] (${d.matchType}, overlap: ${d.overlapRatio})`).join("\n")}
+
+` : "") + (groundingReport.governance.length > 0 ? `## Governance entries to review
+${groundingReport.governance.map((g) => `- **${g.entryId}** ${g.name} [${g.collectionSlug}]`).join("\n")}
+
+` : "") + `_Call \`capture\` without \`suggestOnly\` to proceed with entry creation._`
+          }],
+          structuredContent: {
+            ...success(
+              summaryText,
+              { groundingReport, outcome: "suggest_only" },
+              [{ tool: "capture", description: "Capture for real", parameters: { collection: resolvedCollection, name, description } }]
+            )
+          }
+        };
+      }
       const data = buildDataFromFields(col.fields ?? [], profile.descriptionField, description);
       for (const def of profile.defaults) {
         if (def.value !== "infer" && def.value !== "today") {
@@ -2429,6 +2502,14 @@ Or use \`collections action=list\` to see available collections.`
           ...preview ? { preview: true } : {}
         });
         if (result?.preview) {
+          const hasGrounding = groundingReport.related.length > 0 || groundingReport.duplicates.length > 0 || groundingReport.governance.length > 0;
+          const groundingSummary = hasGrounding ? `
+
+**Grounding:** ${[
+            groundingReport.duplicates.length > 0 && `${groundingReport.duplicates.length} possible duplicate${groundingReport.duplicates.length > 1 ? "s" : ""}`,
+            groundingReport.related.length > 0 && `${groundingReport.related.length} related entr${groundingReport.related.length > 1 ? "ies" : "y"}`,
+            groundingReport.governance.length > 0 && `${groundingReport.governance[0]?.entryId} may govern this`
+          ].filter(Boolean).join(", ")}.` : "";
           const previewEnvelope = success(
             `Preview: would capture "${name}" \u2014 no DB writes`,
             {
@@ -2436,7 +2517,8 @@ Or use \`collections action=list\` to see available collections.`
               name,
               collection: resolvedCollection,
               outcome: "preview",
-              warnings: result.warnings ?? []
+              warnings: result.warnings ?? [],
+              groundingReport
             },
             [{ tool: "capture", description: "Capture for real", parameters: { collection: resolvedCollection, name, description } }]
           );
@@ -2448,7 +2530,7 @@ Or use \`collections action=list\` to see available collections.`
 
 No DB writes \u2014 call without \`preview:true\` to capture for real.${result.warnings?.length ? `
 
-**Warnings:** ${result.warnings.join("; ")}` : ""}` }],
+**Warnings:** ${result.warnings.join("; ")}` : ""}${groundingSummary}` }],
             structuredContent: previewEnvelope
           };
         }
@@ -2485,6 +2567,17 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
         throw error;
       }
       const tAfterCreate = Date.now();
+      void mcpMutation("chain.recordGroundingOutcome", {
+        surface: "mcp",
+        promptShown: groundingReport.governance.length > 0,
+        highestRatio: Math.max(
+          ...groundingReport.duplicates.map((d) => d.overlapRatio),
+          ...groundingReport.related.map((r) => r.overlapRatio),
+          0
+        ),
+        hadGovernance: groundingReport.governance.length > 0,
+        grounding_ms: groundingElapsedMs
+      }).catch(() => void 0);
       const linksCreated = [];
       const linksSuggested = [];
       const userLinkResults = [];
@@ -2770,6 +2863,19 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
           lines.push(`${i + 1}. **${s.entryId ?? "(no ID)"}**: ${s.name} [${s.collection}]${preview2}`);
         }
       }
+      if (format === "human") {
+        const hasDuplicates = groundingReport.duplicates.length > 0;
+        const hasRelated = groundingReport.related.length > 0;
+        const hasGov = groundingReport.governance.length > 0;
+        if (hasDuplicates || hasRelated || hasGov) {
+          lines.push("");
+          const parts = [];
+          if (hasDuplicates) parts.push(`${groundingReport.duplicates.length} possible duplicate${groundingReport.duplicates.length > 1 ? "s" : ""}`);
+          if (hasRelated) parts.push(`${groundingReport.related.length} related entr${groundingReport.related.length > 1 ? "ies" : "y"}`);
+          if (hasGov) parts.push(`${groundingReport.governance[0]?.entryId} may govern this`);
+          lines.push(`_Grounding: ${parts.join(", ")}. Review and link if relevant._`);
+        }
+      }
       lines.push("");
       lines.push(formatQualityReport(quality));
       const failedChecks = quality.checks.filter((c) => !c.passed);
@@ -2946,7 +3052,9 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
               // BET-272 S3: Advisory quality hints — always included (empty array when all criteria pass)
               qualityHints: formativeHints,
               // BET-272 S5: Advisory relation suggestions from graph (BR-144, STD-147)
-              relationSuggestions: relationSuggestionsFromCreate
+              relationSuggestions: relationSuggestionsFromCreate,
+              // WP-318 S2: Pre-write grounding report — always included (empty arrays when no suggestions)
+              groundingReport
             },
             next
           ),
@@ -11114,7 +11222,16 @@ async function tryMarkOriented(agentSessionId, coherenceSnapshot) {
     setSessionOriented(true);
     return { oriented: true, orientationStatus: "complete" };
   } catch {
-    return { oriented: false, orientationStatus: "failed" };
+    if (!coherenceSnapshot) {
+      return { oriented: false, orientationStatus: "failed" };
+    }
+    try {
+      await mcpCall("agent.markOriented", { sessionId: agentSessionId });
+      setSessionOriented(true);
+      return { oriented: true, orientationStatus: "complete" };
+    } catch {
+      return { oriented: false, orientationStatus: "failed" };
+    }
   }
 }
 var startSchema = z17.object({
@@ -13361,6 +13478,25 @@ function formatScanReport(result) {
 // src/tools/orient.ts
 import { z as z22 } from "zod";
 var PURPOSE_GAP_PREFIX = "purpose-gap-";
+async function markOrientedWithSnapshotFallback(agentSessionId, coherenceSnapshot) {
+  try {
+    await mcpCall("agent.markOriented", {
+      sessionId: agentSessionId,
+      ...coherenceSnapshot ? { coherenceSnapshot } : {}
+    });
+    setSessionOriented(true);
+    return true;
+  } catch {
+    if (!coherenceSnapshot) return false;
+    try {
+      await mcpCall("agent.markOriented", { sessionId: agentSessionId });
+      setSessionOriented(true);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
 function extractSessionEntryIds(priorSessions) {
   const allSeen = /* @__PURE__ */ new Set();
   const all = [];
@@ -13648,16 +13784,12 @@ function registerOrientTool(server) {
         }
         let orientationStatus2 = "no_session";
         if (agentSessionId && hasTaskGrounding) {
-          try {
-            await mcpCall("agent.markOriented", {
-              sessionId: agentSessionId,
-              ...coherenceSnapshot ? { coherenceSnapshot } : {}
-            });
-            setSessionOriented(true);
+          const orientedOk = await markOrientedWithSnapshotFallback(agentSessionId, coherenceSnapshot);
+          if (orientedOk) {
             orientationStatus2 = "complete";
             lines.push("---");
             lines.push(`Orientation complete. Session ${agentSessionId}. Write tools available.`);
-          } catch {
+          } else {
             orientationStatus2 = "failed";
             lines.push("---");
             lines.push("_Warning: Could not mark session as oriented. Write tools may be restricted._");
@@ -14019,16 +14151,12 @@ function registerOrientTool(server) {
       }
       let orientationStatus = "no_session";
       if (agentSessionId && hasTaskGrounding) {
-        try {
-          await mcpCall("agent.markOriented", {
-            sessionId: agentSessionId,
-            ...fullCoherenceSnapshot ? { coherenceSnapshot: fullCoherenceSnapshot } : {}
-          });
-          setSessionOriented(true);
+        const orientedOk = await markOrientedWithSnapshotFallback(agentSessionId, fullCoherenceSnapshot);
+        if (orientedOk) {
           orientationStatus = "complete";
           lines.push("---");
           lines.push(`Orientation complete. Session ${agentSessionId}. Write tools available.`);
-        } catch {
+        } else {
           orientationStatus = "failed";
           lines.push("---");
           lines.push("_Warning: Could not mark session as oriented. Write tools may be restricted._");
@@ -15629,7 +15757,6 @@ export {
   hashKey,
   runWithAuth,
   getAgentSessionId,
-  startAgentSession,
   orphanAgentSession,
   bootstrap,
   bootstrapHttp,
@@ -15639,4 +15766,4 @@ export {
   SERVER_VERSION,
   createProductBrainServer
 };
-//# sourceMappingURL=chunk-LKUFRQUO.js.map
+//# sourceMappingURL=chunk-EPAHRXLQ.js.map