@productbrain/mcp 0.0.1-beta.8702 → 0.0.1-beta.8719

package/dist/{chunk-RPKS4G3K.js → chunk-ZOYUYCKV.js}

@@ -1,6 +1,8 @@
 import {
   KernelCallError,
+  PASS_SESSION_ID,
   cacheScope,
+  classifyError,
   closeAgentSession,
   formatGatewaySeamSummary,
   getAgentSessionId,
@@ -15,10 +17,13 @@ import {
   kernelCallEnvelope,
   kernelMutation,
   kernelQuery,
+  orientationRefusal,
   recordSessionActivity,
   requireActiveSession,
   requireVendorTriageAccess,
   requireWriteAccess,
+  retryIsFutile,
+  runWithSeatedSession,
   runWithToolContext,
   setSessionOriented,
   startAgentSession,
@@ -37,223 +42,16 @@ import {
   trackQualityCheck,
   trackQualityVerdict,
   trackSessionCaptureRate,
-  trackZeroCaptureAuditFired
-} from "./chunk-FZWP45AU.js";
+  trackZeroCaptureAuditFired,
+  validateCallerSession
+} from "./chunk-2UJDIWEX.js";
 
 // src/server.ts
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-// src/lib/createEntryPreviewResult.ts
-async function resolvePreviewPreflight(result2, links) {
-  if (!links?.length) return result2.preflight;
-  try {
-    return await kernelQuery("chain.preflightEntry", {
-      collectionSlug: result2.collection,
-      canonicalKey: result2.preflight.kind ?? void 0,
-      links: links.map((link) => ({ entryId: link.to, type: link.type }))
-    });
-  } catch {
-    return {
-      ...result2.preflight,
-      checks: [
-        ...result2.preflight.checks,
-        {
-          id: "link-recheck",
-          status: "not_checked",
-          blocking: false,
-          message: "Selected links could not be rechecked now; target existence and relation policy are checked at capture."
-        }
-      ]
-    };
-  }
-}
-function formatPreflightCheck(check) {
-  if (check.status === "missing" && check.blocking) return `Blocked: ${check.message}`;
-  if (check.status === "incomplete") return `Unverified: ${check.message}`;
-  if (check.status === "not_checked") return `Checked later: ${check.message}`;
-  return check.message;
-}
-function renderEntryPreflight(preflight) {
-  return [
-    ...preflight.checks.map(formatPreflightCheck),
-    ...preflight.requiredFields.length ? [`Required information: ${preflight.requiredFields.join(", ")}.`] : [],
-    preflight.notice
-  ];
-}
-function isPreviewCreateEntryResult(result2) {
-  return "preview" in result2 && result2.preview === true;
-}
-function resolveEffectiveCollection(result2, preview, fallbackCollection) {
-  return preview && result2 && isPreviewCreateEntryResult(result2) ? result2.collection ?? fallbackCollection : fallbackCollection;
-}
-
-// src/tools/entries.ts
-import { z as z11 } from "zod/v3";
+import { z as z34 } from "zod/v3";
 
 // src/envelope.ts
 import { z } from "zod/v3";
-
-// src/errors.ts
-var MCP_CALL_ERROR_RE = /^MCP call "([^"]+)" failed \(\d+\): (.+)$/s;
-function asKernelCallError(err) {
-  if (!(err instanceof Error)) return void 0;
-  const e = err;
-  if (typeof e.code !== "string") return void 0;
-  const match = MCP_CALL_ERROR_RE.exec(e.message);
-  if (!match) return void 0;
-  return {
-    code: e.code,
-    fn: match[1],
-    cleanMessage: match[2],
-    // NOTE: match[2] not match[1] — group 1 is now fn scope (DEC-798)
-    missingRequiredFields: Array.isArray(e.missingRequiredFields) ? e.missingRequiredFields : void 0,
-    fieldErrors: Array.isArray(e.fieldErrors) ? e.fieldErrors : void 0
-  };
-}
-var GateError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "GateError";
-  }
-};
-var BackendError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "BackendError";
-  }
-};
-var ValidationError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ValidationError";
-  }
-};
-var GATE_PATTERNS = [
-  {
-    pattern: /session required|no active.*session|call.*session.*start/i,
-    code: "SESSION_REQUIRED",
-    recovery: "Start an agent session first.",
-    action: { tool: "session", description: "Start session", parameters: { action: "start" } }
-  },
-  {
-    pattern: /session.*closed/i,
-    code: "SESSION_CLOSED",
-    recovery: "Start a new session.",
-    action: { tool: "session", description: "Start new session", parameters: { action: "start" } }
-  },
-  {
-    pattern: /orientation required|call.*orient/i,
-    code: "ORIENTATION_REQUIRED",
-    recovery: "Run orient with a task, then retry.",
-    action: { tool: "orient", description: "Orient with a task", parameters: { action: "task" } }
-  },
-  {
-    pattern: /read.?only.*scope/i,
-    code: "READONLY_SCOPE",
-    recovery: "This API key cannot write. Use a readwrite key.",
-    action: { tool: "workspace", description: "Check key scope", parameters: { action: "whoami" } }
-  }
-];
-function orientationRefusal(err) {
-  const gate = GATE_PATTERNS.find((g) => g.code === "ORIENTATION_REQUIRED");
-  const mcpErr = asKernelCallError(err);
-  const message = mcpErr?.cleanMessage ?? (err instanceof Error ? err.message : String(err));
-  if (!gate || !gate.pattern.test(message)) return null;
-  return { code: gate.code, message, recovery: gate.recovery, availableActions: [gate.action] };
-}
-function classifyError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  if (err instanceof GateError) {
-    return {
-      code: "PERMISSION_DENIED",
-      message,
-      recovery: "Check permissions or use a readwrite API key.",
-      availableActions: [{ tool: "workspace", description: "Check key scope", parameters: { action: "whoami" } }]
-    };
-  }
-  if (err instanceof BackendError) {
-    return { code: "BACKEND_ERROR", message, recovery: "Retry the operation or check backend health." };
-  }
-  if (err instanceof ValidationError) {
-    return { code: "VALIDATION_ERROR", message };
-  }
-  const mcpErr = asKernelCallError(err);
-  if (mcpErr) {
-    const { code: convexCode, fn, cleanMessage, missingRequiredFields, fieldErrors } = mcpErr;
-    if (convexCode === "VALIDATION_FAILED") {
-      const hasDiagnostics = missingRequiredFields?.length || fieldErrors?.length;
-      return {
-        code: "VALIDATION_ERROR",
-        fn,
-        message: cleanMessage,
-        ...hasDiagnostics ? {
-          diagnostics: {
-            ...missingRequiredFields?.length ? { missingRequiredFields } : {},
-            ...fieldErrors?.length ? { fieldErrors } : {}
-          }
-        } : {}
-      };
-    }
-    if (convexCode === "NOT_FOUND") {
-      return {
-        code: "NOT_FOUND",
-        fn,
-        message: cleanMessage,
-        recovery: "Use entries action=search to find the correct ID.",
-        availableActions: [{ tool: "entries", description: "Search entries", parameters: { action: "search" } }]
-      };
-    }
-    if (convexCode?.startsWith("AUTHZ_")) {
-      return {
-        code: "PERMISSION_DENIED",
-        fn,
-        message: cleanMessage,
-        recovery: "Check permissions or use a readwrite API key.",
-        availableActions: [{ tool: "workspace", description: "Check key scope", parameters: { action: "whoami" } }]
-      };
-    }
-    if (convexCode === "WORKSPACE_SLUG_TAKEN" || convexCode === "PERSON_ALREADY_EXISTS") {
-      return {
-        code: "DUPLICATE",
-        fn,
-        message: cleanMessage,
-        recovery: "Use entries action=get to inspect the existing entry.",
-        availableActions: [{ tool: "entries", description: "Get entry", parameters: { action: "get" } }]
-      };
-    }
-    if (convexCode === "rate-limited") {
-      return {
-        code: "rate-limited",
-        fn,
-        message: cleanMessage,
-        recovery: "Rate limit hit for this API key. Wait the number of seconds in the message (Retry-After), then retry the same call unchanged \u2014 it is safe to retry."
-      };
-    }
-    return { code: convexCode, fn, message: cleanMessage };
-  }
-  for (const { pattern, code, recovery, action } of GATE_PATTERNS) {
-    if (pattern.test(message)) {
-      return { code, message, recovery, availableActions: [action] };
-    }
-  }
-  if (err?.name === "GatewayTimeoutError") {
-    const mayHaveLanded = err.mayHaveLanded === true;
-    return {
-      code: "GATEWAY_TIMEOUT",
-      message,
-      recovery: mayHaveLanded ? "The server was reachable and may have completed this write \u2014 verify before retrying, since a blind retry can duplicate it." : "The server was reachable but did not answer in time. Nothing was written \u2014 safe to retry."
-    };
-  }
-  if (/network error|fetch failed|ECONNREFUSED|ETIMEDOUT/i.test(message)) {
-    return { code: "BACKEND_UNAVAILABLE", message, recovery: "Retry in a few seconds." };
-  }
-  return { code: "INTERNAL_ERROR", message: message || "An unexpected error occurred." };
-}
-function retryIsFutile(code) {
-  return code === "VALIDATION_ERROR";
-}
-
-// src/envelope.ts
 function success(summary, data, next) {
   return {
     ok: true,
@@ -376,6 +174,53 @@ function orientationRefusalResult(err, lines) {
 }
 var ORIENT_REQUIRED_NOTE = "workflow checkpoints and organisation-structure writes (membership, ownership, parent) still require an oriented session.";
 
+// src/lib/createEntryPreviewResult.ts
+async function resolvePreviewPreflight(result2, links) {
+  if (!links?.length) return result2.preflight;
+  try {
+    return await kernelQuery("chain.preflightEntry", {
+      collectionSlug: result2.collection,
+      canonicalKey: result2.preflight.kind ?? void 0,
+      links: links.map((link) => ({ entryId: link.to, type: link.type }))
+    });
+  } catch {
+    return {
+      ...result2.preflight,
+      checks: [
+        ...result2.preflight.checks,
+        {
+          id: "link-recheck",
+          status: "not_checked",
+          blocking: false,
+          message: "Selected links could not be rechecked now; target existence and relation policy are checked at capture."
+        }
+      ]
+    };
+  }
+}
+function formatPreflightCheck(check) {
+  if (check.status === "missing" && check.blocking) return `Blocked: ${check.message}`;
+  if (check.status === "incomplete") return `Unverified: ${check.message}`;
+  if (check.status === "not_checked") return `Checked later: ${check.message}`;
+  return check.message;
+}
+function renderEntryPreflight(preflight) {
+  return [
+    ...preflight.checks.map(formatPreflightCheck),
+    ...preflight.requiredFields.length ? [`Required information: ${preflight.requiredFields.join(", ")}.`] : [],
+    preflight.notice
+  ];
+}
+function isPreviewCreateEntryResult(result2) {
+  return "preview" in result2 && result2.preview === true;
+}
+function resolveEffectiveCollection(result2, preview, fallbackCollection) {
+  return preview && result2 && isPreviewCreateEntryResult(result2) ? result2.collection ?? fallbackCollection : fallbackCollection;
+}
+
+// src/tools/entries.ts
+import { z as z11 } from "zod/v3";
+
 // src/tools/knowledge-helpers.ts
 import { z as z2 } from "zod/v3";
 
@@ -11738,14 +11583,16 @@ var sessionSchema = z24.object({
   ),
   // DEC-1715 (WP-753 O1a)
   role: z24.string().max(200).optional().describe(
-    "For 'start': role to act as this session \u2014 only needed if you hold more than one; the error lists your roles if omitted."
+    "For 'start': role to act as this session, by the '<PREFIX>-<n>' id a start reply prints beside the role name \u2014 only needed if you hold more than one; the error lists your roles if omitted."
   )
 });
 var sessionStartVariant = z24.object({
   action: z24.literal("start"),
   // DEC-1715 (WP-753 O1a): the role to act as this session — only needed when the person holds
   // more than one role; the server refuses and lists the choices when it's required and omitted.
-  role: z24.string().max(200).optional().describe("Role to act as this session \u2014 only needed if you hold more than one; the error lists your roles if omitted.")
+  role: z24.string().max(200).optional().describe(
+    "Role to act as this session, by the '<PREFIX>-<n>' id a start reply prints beside the role name \u2014 only needed if you hold more than one; the error lists your roles if omitted."
+  )
 });
 var sessionCloseVariant = z24.object({ action: z24.literal("close") });
 var sessionStatusVariant = z24.object({ action: z24.literal("status") });
@@ -11810,10 +11657,10 @@ async function handleStart2(data) {
   const result2 = await startAgentSession(data?.role);
   const lines = [];
   lines.push(
-    `Session ${result2.sessionId} active. Initiated by ${result2.initiatedBy}. Workspace ${result2.workspaceName}. Scope: ${result2.toolsScope}. Orient with a task before substantive work: it is advice for captures, relations, accepts, ticks and questions; workflow checkpoints and organisation-structure writes still require it.`
+    `Session ${result2.sessionId} active. Pass sessionId="${result2.sessionId}" on every write: the connection does not remember your session between calls. Initiated by ${result2.initiatedBy}. Workspace ${result2.workspaceName}. Scope: ${result2.toolsScope}. Orient with a task before substantive work: it is advice for captures, relations, accepts, ticks and questions; workflow checkpoints and organisation-structure writes still require it.`
   );
   if (result2.roleEntryId) {
-    lines.push(`Acting as role: ${result2.roleName ?? result2.roleEntryId}.`);
+    lines.push(`Acting as role: ${result2.roleName ?? result2.roleEntryId}${result2.roleRef ? ` (${result2.roleRef})` : ""}.`);
   }
   lines.push(FEEDBACK_SUBMIT_HINT);
   const questionNotice = result2.notices?.find((n) => n.source === QUESTION_ACK_GATE_SOURCE_ID);
@@ -11829,7 +11676,7 @@ async function handleStart2(data) {
     openQuestionsTruncated: questionNotice?.payload?.truncated === true,
     surface: "mcp"
   }));
-  const summary = `Session ${result2.sessionId} active. Workspace ${result2.workspaceName}. Orient with a task first; workflow checkpoints and organisation-structure writes still require it.`;
+  const summary = `Session ${result2.sessionId} active. Workspace ${result2.workspaceName}. Pass sessionId="${result2.sessionId}" on every write. Orient with a task first; workflow checkpoints and organisation-structure writes still require it.`;
   return {
     content: [{ type: "text", text: lines.join("\n") }],
     structuredContent: success(summary, {
@@ -11839,6 +11686,8 @@ async function handleStart2(data) {
       toolsScope: result2.toolsScope,
       roleEntryId: result2.roleEntryId,
       roleName: result2.roleName,
+      roleRef: result2.roleRef,
+      // TASK-583
       feedbackQueueNew: result2.feedbackQueueNew,
       feedbackOldestNewAt: result2.feedbackOldestNewAt,
       notices: result2.notices ?? [],
@@ -11852,17 +11701,18 @@ async function handleStart2(data) {
       // the guided-setup entrypoint this session just opened write access for.
       // FEAT-1409 spine core: notice next-actions are appended through this SAME existing
       // `next` field (HARD CONSTRAINT 2) — never a parallel action list.
-    }, [{ tool: "orient", description: "Orient session", parameters: { action: "start" } }, ...noticesToNextActions(result2.notices)])
+      // TASK-583 (DEC-1907): every next action carries the sessionId, since the next call may arrive on a new connection.
+    }, [{ tool: "orient", description: "Orient session", parameters: { action: "start" } }, ...noticesToNextActions(result2.notices)].map((next) => ({ ...next, parameters: { ...next.parameters, sessionId: result2.sessionId } })))
   };
 }
 async function handleClose() {
   const sessionId = getAgentSessionId();
   if (!sessionId) {
     return failureResult(
-      "No active agent session to close.",
+      `No active agent session to close. Pass the sessionId to close as \`sessionId\`. ${PASS_SESSION_ID}`,
       "SESSION_REQUIRED",
       "No active agent session to close.",
-      "Start a session first.",
+      PASS_SESSION_ID,
       [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
     );
   }
@@ -11953,10 +11803,10 @@ async function handleStatus() {
   const sessionId = getAgentSessionId();
   if (!sessionId) {
     return failureResult(
-      "No active agent session. Call session action=start to begin.",
+      `No active agent session on this connection. Pass your sessionId as \`sessionId\` to read it. ${PASS_SESSION_ID}`,
       "SESSION_REQUIRED",
       "No active agent session.",
-      "Call session action=start to begin.",
+      PASS_SESSION_ID,
       [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
     );
   }
@@ -11977,6 +11827,7 @@ async function handleStatus() {
   const modified = session.entriesModified?.length ?? 0;
   const lines = [
     `Session ${sessionId} ${session.status}.`,
+    `Pass sessionId="${sessionId}" on every write: the connection does not remember your session between calls.`,
     `Initiated by ${session.initiatedBy}.`,
     `Scope: ${session.toolsScope}.`,
     `Oriented: ${oriented ? "yes" : "no"}.`,
@@ -14216,6 +14067,7 @@ var INSTRUCTIONS = [
   "## Writing",
   "",
   "Write actions (capture, entries update and commit, relations create, batch-create, dismiss and delete) need an active session and a readwrite key.",
+  "Pass the `sessionId` that `session action=start` returned on every write: the connection does not remember it.",
   "Use `capture` to create an entry and read its reply: an entry that came back accepted needs no `entries action=commit`.",
   "Link with `relations action=suggest`, then `relations action=create`.",
   "Finish with `session action=wrapup-review`, then `session action=close`.",
@@ -14225,11 +14077,46 @@ var INSTRUCTIONS = [
   "",
   "Every tool and action: `productbrain://agent-cheatsheet`."
 ].join("\n");
+var sessionIdArg = z34.string().max(200).optional().describe(
+  "The sessionId `session action=start` returned. Pass it on every write: the connection does not remember your session between calls."
+);
+function acceptSessionIdOnEveryTool(server) {
+  const register = server.registerTool.bind(server);
+  server.registerTool = (name, config, cb) => register(
+    name,
+    { ...config, inputSchema: config.inputSchema.extend({ sessionId: sessionIdArg }) },
+    async ({ sessionId, ...args }, extra) => {
+      if (typeof sessionId === "string" && sessionId.length > 0 && !(name === "session" && args.action === "start")) {
+        const seated = await validateOrRefuse(sessionId);
+        if ("refused" in seated) return seated.refused;
+        return runWithSeatedSession(seated.lc, () => cb(args, extra));
+      }
+      return cb(args, extra);
+    }
+  );
+}
+async function validateOrRefuse(sessionId) {
+  try {
+    return { lc: await validateCallerSession(sessionId) };
+  } catch (err) {
+    const { code, message, recovery } = classifyError(err);
+    const reason = message.split("\n")[0].replace(/\.?\s*$/, ".");
+    const result2 = err instanceof KernelCallError && err.status >= 400 && err.status < 500 && err.status !== 429 ? failureResult(
+      `[SESSION_INVALID] The sessionId you passed (${sessionId}) was refused: ${reason} ${PASS_SESSION_ID}`,
+      "SESSION_INVALID",
+      `sessionId refused: ${reason}`,
+      PASS_SESSION_ID,
+      [{ tool: "session", description: "Start a session", parameters: { action: "start" } }]
+    ) : failureResult(`[${code}] ${message}`, code, message, recovery);
+    return { refused: { ...result2, isError: true } };
+  }
+}
 function createProductBrainServer() {
   const server = new McpServer2(
     { name: "Product Brain", version: SERVER_VERSION },
     { capabilities: { logging: {} }, instructions: INSTRUCTIONS }
   );
+  acceptSessionIdOnEveryTool(server);
   registerSessionTools(server);
   registerEntriesTools(server);
   registerRelationsTools(server);
@@ -14280,4 +14167,4 @@ export {
   createProductBrainServer,
   initFeatureFlags
 };
-//# sourceMappingURL=chunk-RPKS4G3K.js.map
+//# sourceMappingURL=chunk-ZOYUYCKV.js.map