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

package/dist/{chunk-FZWP45AU.js → chunk-2UJDIWEX.js}

@@ -925,6 +925,167 @@ function recordGatewayCall(params) {
 // src/client.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 
+// 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 PASS_SESSION_ID = "Call `session action=start`, then pass the sessionId it returns as `sessionId` on every write: the connection does not remember your session between calls.";
+var GATE_PATTERNS = [
+  {
+    pattern: /session required|no active.*session|call.*session.*start/i,
+    code: "SESSION_REQUIRED",
+    recovery: PASS_SESSION_ID,
+    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/lib/conversation.ts
 import { createHash as createHash2 } from "crypto";
 var MAX_RAW_LEN = 128;
@@ -990,7 +1151,7 @@ async function probeDeploymentCandidates(candidates, apiKey) {
 var _conversationId;
 function getConversationId() {
   const mcpSid = getRequestMcpSessionId();
-  if (mcpSid) return `mcp:${mcpSid}`;
+  if (mcpSid) return sessionLifecycle().conversationId ?? `mcp:${mcpSid}`;
   if (getRequestApiKey()) return null;
   if (_conversationId === void 0) _conversationId = resolveConversationId();
   return _conversationId;
@@ -1076,6 +1237,8 @@ function getActiveApiKey() {
 var _sessionLifecycleByStream = /* @__PURE__ */ new Map();
 var MAX_SESSION_STREAMS = 500;
 function sessionLifecycle() {
+  const seated = seatedSessionStore.getStore();
+  if (seated) return seated;
   const mcpSid = getRequestMcpSessionId();
   if (!mcpSid) return state();
   const key = `${cacheScope()}:${mcpSid}`;
@@ -1102,6 +1265,13 @@ function setSessionOriented(value) {
 function getApiKeyScope() {
   return state().apiKeyScope;
 }
+var seatedSessionStore = new AsyncLocalStorage2();
+async function validateCallerSession(sessionId) {
+  const session = await kernelCall("agent.validateSession", { sessionId, workspaceId: await getWorkspaceId(), requireActive: true });
+  return { agentSessionId: session._id, sessionOriented: session.oriented, sessionClosed: false, conversationId: session.conversationId ?? null };
+}
+var runWithSeatedSession = (lc, fn) => seatedSessionStore.run(lc, fn);
+var forgetStreamLifecycle = (keyHash, mcpSessionId) => _sessionLifecycleByStream.delete(`${keyHash}:${mcpSessionId}`);
 async function startAgentSession(role) {
   const workspaceId = await getWorkspaceId();
   const s = state();
@@ -1419,9 +1589,7 @@ function requireWriteAccess() {
   const lc = sessionLifecycle();
   const s = state();
   if (!lc.agentSessionId) {
-    throw new Error(
-      "Agent session required for write operations. Call `session action=start` first."
-    );
+    throw new Error(`Agent session required for write operations. ${PASS_SESSION_ID}`);
   }
   if (lc.sessionClosed) {
     throw new Error(
@@ -1518,6 +1686,10 @@ export {
   MCP_NPX_PACKAGE,
   resolveClient,
   writeClientConfig,
+  PASS_SESSION_ID,
+  orientationRefusal,
+  classifyError,
+  retryIsFutile,
   warnOnProdFallthrough,
   getConversationId,
   runWithToolContext,
@@ -1527,6 +1699,9 @@ export {
   isSessionOriented,
   setSessionOriented,
   getApiKeyScope,
+  validateCallerSession,
+  runWithSeatedSession,
+  forgetStreamLifecycle,
   startAgentSession,
   closeAgentSession,
   orphanAgentSession,
@@ -1544,4 +1719,4 @@ export {
   requireVendorTriageAccess,
   recoverSessionState
 };
-//# sourceMappingURL=chunk-FZWP45AU.js.map
+//# sourceMappingURL=chunk-2UJDIWEX.js.map