@productbrain/mcp 0.0.1-beta.190 → 0.0.1-beta.191

package/dist/{chunk-ZF6N62QQ.js → chunk-GJFGULJV.js}

@@ -351,7 +351,11 @@ var TOUCH_EXCLUDED = /* @__PURE__ */ new Set([
   "agent.markOriented",
   "agent.recordActivity",
   "agent.recordWrapup",
-  "agent.closeSession"
+  "agent.closeSession",
+  // WP-376 α.3: orient byte report is itself a heartbeat-equivalent observability
+  // write that already patches the same agentSessions row. A follow-up touchSession
+  // would create a redundant second write per orient call (DEC-50 OCC anti-pattern).
+  "agent.reportOrientMetric"
 ]);
 async function callGateway(fn, args) {
   const siteUrl = await resolveDeploymentUrl();
@@ -13387,6 +13391,15 @@ function formatScanReport(result) {
 // src/tools/orient.ts
 import { z as z22 } from "zod";
 var PURPOSE_GAP_PREFIX = "purpose-gap-";
+function reportOrientWrapperBytes(toolResult, truncated) {
+  try {
+    const fullToolOutput = JSON.stringify({ content: toolResult.content ?? [] });
+    const bytes = Buffer.byteLength(fullToolOutput, "utf8");
+    void kernelMutation("agent.reportOrientMetric", { bytes, truncated }).catch(() => {
+    });
+  } catch {
+  }
+}
 async function markOrientedWithSnapshotFallback(agentSessionId, coherenceSnapshot) {
   try {
     await kernelCall("agent.markOriented", {
@@ -13589,7 +13602,7 @@ function registerOrientTool(server) {
             orientationStatus2 = "failed";
           }
         }
-        return {
+        const blankResult = {
           content: [{ type: "text", text: scanLines.join("\n") }],
           structuredContent: success(
             "Workspace is blank. Use the start tool for guided setup.",
@@ -13597,6 +13610,8 @@ function registerOrientTool(server) {
             [{ tool: "start", description: "Guided workspace setup", parameters: {} }]
           )
         };
+        reportOrientWrapperBytes(blankResult, false);
+        return blankResult;
       }
       const lines = [];
       const isLowReadiness = readiness && readiness.score < 50;
@@ -13740,7 +13755,7 @@ function registerOrientTool(server) {
           lines.push("");
           for (const err of errors) lines.push(`- ${err}`);
         }
-        return {
+        const briefResult = {
           content: [{ type: "text", text: lines.join("\n") }],
           structuredContent: success(
             `Oriented (brief). Stage: ${readiness?.stage ?? "unknown"}.`,
@@ -13756,6 +13771,8 @@ function registerOrientTool(server) {
             }
           )
         };
+        reportOrientWrapperBytes(briefResult, orientEntries?._truncated === true);
+        return briefResult;
       }
       const orientStage = readiness?.stage ?? "seeded";
       if (isLowReadiness && wsCtx?.createdAt) {
@@ -14123,7 +14140,7 @@ function registerOrientTool(server) {
         lines.push("---");
         lines.push("_No active agent session. Call `session action=start` to begin a tracked session._");
       }
-      return {
+      const fullResult = {
         content: [{ type: "text", text: lines.join("\n") }],
         structuredContent: success(
           `Oriented (full). Stage: ${orientStage}. ${isLowReadiness ? "Low readiness \u2014 gaps remain." : "Ready."}`,
@@ -14140,6 +14157,8 @@ function registerOrientTool(server) {
           }
         )
       };
+      reportOrientWrapperBytes(fullResult, orientEntries?._truncated === true);
+      return fullResult;
     })
   );
 }
@@ -14897,6 +14916,109 @@ function registerGovernanceTools(server) {
   trackWriteTool(tool);
 }
 
+// src/tools/documents.ts
+import { z as z26 } from "zod";
+var DOCUMENTS_ACTIONS = ["get-last-verified-brief"];
+var documentsSchema = z26.object({
+  action: z26.enum(DOCUMENTS_ACTIONS).describe(
+    "'get-last-verified-brief': fetch the most recent verified brief snapshot for a (templateId, scopeKey) pair. Returns the verified summary so agents can build delta narratives ('since you last verified, X workstreams advanced')."
+  ),
+  templateId: z26.string().describe(
+    "Brief template identifier \u2014 currently 'steering-brief' is the only registered template."
+  ),
+  scopeKey: z26.string().describe(
+    "Canonical scope key. Use 'workspace:<workspaceId>' for the full workspace brief, or 'initiative:<INI-ID>' for an initiative-scoped brief. The same formula is applied at write time (chainwork/docKernel/scopeKey.ts), so passing the wrong shape returns exists:false."
+  )
+});
+function registerDocumentsTools(server) {
+  server.registerTool(
+    "documents",
+    {
+      title: "Documents",
+      description: "Read agent-facing snapshots of verified briefs.\n\n**Actions:**\n- `get-last-verified-brief`: returns the most recent verified-brief snapshot for a (templateId, scopeKey) pair, including the at-a-glance markdown, workstream snapshots, cited entry IDs, and verification timestamp.\n\nUse this to build delta narratives ('since the last verified brief on Tuesday, two workstreams advanced and one new tension was captured').\n\nReturns `{ exists: false }` when no row matches. Returns `{ exists: true, summary: <snapshot>, verifiedAt }` when an S4 row is found, or `{ exists: true, summary: undefined, verifiedAt }` for legacy backfilled rows that pre-date snapshot capture.",
+      inputSchema: documentsSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    thinWrapper(async (args) => {
+      const parsed = parseOrFail(documentsSchema, args);
+      if (!parsed.ok) return parsed.result;
+      const { action, templateId, scopeKey } = parsed.data;
+      return runWithToolContext(
+        { tool: "documents", action },
+        () => handleGetLastVerifiedBrief(templateId, scopeKey)
+      );
+    })
+  );
+}
+async function handleGetLastVerifiedBrief(templateId, scopeKey) {
+  const result = await kernelQuery(
+    "chainwork.getLastVerifiedBrief",
+    { templateId, scopeKey }
+  );
+  if (!result.exists) {
+    const text = `No verified brief found for template '${templateId}', scope '${scopeKey}'.
+
+This is normal for a never-verified initiative or workspace. If you expected a row here, check that the scope key matches the format produced at write time: 'workspace:<workspaceId>' or 'initiative:<INI-ID>'.`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: success(
+        `No verified brief found for ${templateId} / ${scopeKey}.`,
+        { exists: false }
+      )
+    };
+  }
+  const verifiedAtIso = new Date(result.verifiedAt).toISOString();
+  if (result.summary === void 0) {
+    const text = `Verified brief found for template '${templateId}', scope '${scopeKey}', verified at ${verifiedAtIso}.
+
+This row pre-dates snapshot capture (legacy backfill), so no summary is available. The verification timestamp itself is still authoritative \u2014 you can reason about staleness, just not delta narratives.`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: success(
+        `Legacy verified brief at ${verifiedAtIso} (no summary).`,
+        { exists: true, summary: void 0, verifiedAt: result.verifiedAt }
+      )
+    };
+  }
+  const summary = result.summary;
+  const lines = [
+    `## Last verified brief \u2014 ${templateId} / ${scopeKey}`,
+    `Verified at: ${verifiedAtIso} by ${summary.verifiedBy}`,
+    `Chain synced at: ${new Date(summary.chainSyncedAt).toISOString()}`,
+    "",
+    `### At a glance (verbatim)`,
+    summary.verifiedAtGlance || "(empty)",
+    "",
+    `### Workstreams at verification (${summary.verifiedWorkstreams.length})`
+  ];
+  for (const ws of summary.verifiedWorkstreams) {
+    lines.push(
+      `- **${ws.entryId}** ${ws.name} \u2014 status: ${ws.status}` + (ws.whatChanged ? ` \u2014 ${ws.whatChanged}` : "")
+    );
+  }
+  if (summary.citedEntryIds.length > 0) {
+    lines.push("");
+    lines.push(`### Cited entries (${summary.citedEntryIds.length})`);
+    lines.push(summary.citedEntryIds.join(", "));
+  }
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: success(
+      `Verified brief found at ${verifiedAtIso} with ${summary.verifiedWorkstreams.length} workstream snapshot(s).`,
+      {
+        exists: true,
+        summary,
+        verifiedAt: result.verifiedAt
+      }
+    )
+  };
+}
+
 // src/resources/index.ts
 import { existsSync as existsSync4 } from "fs";
 import { dirname as dirname2, join, resolve as resolve5 } from "path";
@@ -15402,12 +15524,12 @@ ${entry.labels.map((l) => `- ${l.name ?? l.slug}`).join("\n")}`);
 }
 
 // src/prompts/index.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 function registerPrompts(server) {
   server.prompt(
     "review-against-rules",
     "Review code or a design decision against all business rules for a given domain. Fetches the rules and asks you to do a structured compliance review.",
-    { domain: z26.string().describe("Business rule domain (e.g. 'Identity & Access', 'Governance & Decision-Making')") },
+    { domain: z27.string().describe("Business rule domain (e.g. 'Identity & Access', 'Governance & Decision-Making')") },
     async ({ domain }) => {
       const entries = await kernelQuery("chain.listEntries", { collectionSlug: "business-rules" });
       const rules = entries.filter((e) => e.data?.domain === domain);
@@ -15460,7 +15582,7 @@ Provide a structured review with a compliance status for each rule (COMPLIANT /
   server.prompt(
     "name-check",
     "Check variable names, field names, or API names against the glossary for terminology alignment. Flags drift from canonical terms.",
-    { names: z26.string().describe("Comma-separated list of names to check (e.g. 'vendor_id, compliance_level, formulator_type')") },
+    { names: z27.string().describe("Comma-separated list of names to check (e.g. 'vendor_id, compliance_level, formulator_type')") },
     async ({ names }) => {
       const terms = await kernelQuery("chain.listEntries", { collectionSlug: "glossary" });
       const glossaryContext = terms.map(
@@ -15496,7 +15618,7 @@ Format as a table: Name | Status | Canonical Form | Action Needed`
   server.prompt(
     "draft-decision-record",
     "Draft a structured decision record from a description of what was decided. Includes context from recent decisions and relevant rules.",
-    { context: z26.string().describe("Description of the decision (e.g. 'We decided to use MRSL v3.1 as the conformance baseline because...')") },
+    { context: z27.string().describe("Description of the decision (e.g. 'We decided to use MRSL v3.1 as the conformance baseline because...')") },
     async ({ context }) => {
       const recentDecisions = await kernelQuery("chain.listEntries", { collectionSlug: "decisions" });
       const sorted = [...recentDecisions].sort((a, b) => (b.data?.date ?? "") > (a.data?.date ?? "") ? 1 : -1).slice(0, 5);
@@ -15534,8 +15656,8 @@ After drafting, I can log it using the capture tool with collection "decisions".
     "draft-rule-from-context",
     "Draft a new business rule from an observation or discovery made while coding. Fetches existing rules for the domain to ensure consistency.",
     {
-      observation: z26.string().describe("What you observed or discovered (e.g. 'Suppliers can have multiple org types in Gateway')"),
-      domain: z26.string().describe("Which domain this rule belongs to (e.g. 'Governance & Decision-Making')")
+      observation: z27.string().describe("What you observed or discovered (e.g. 'Suppliers can have multiple org types in Gateway')"),
+      domain: z27.string().describe("Which domain this rule belongs to (e.g. 'Governance & Decision-Making')")
     },
     async ({ observation, domain }) => {
       const allRules = await kernelQuery("chain.listEntries", { collectionSlug: "business-rules" });
@@ -15679,6 +15801,7 @@ function createProductBrainServer() {
   registerFacilitateTools(server);
   registerAuditTools(server);
   registerGovernanceTools(server);
+  registerDocumentsTools(server);
   registerResources(server);
   registerPrompts(server);
   return server;
@@ -15723,4 +15846,4 @@ export {
   createProductBrainServer,
   initFeatureFlags
 };
-//# sourceMappingURL=chunk-ZF6N62QQ.js.map
+//# sourceMappingURL=chunk-GJFGULJV.js.map