@mathew-macharia/black-mamba 1.0.4 → 1.0.5

package/src/config.js

@@ -30,7 +30,6 @@ export function loadConfig(env = process.env, rootDir = ROOT_DIR) {
   return Object.freeze({
     rootDir,
     port: readNumber(env.PORT, 3000),
-    apiKey: (env.API_KEY || env.BM_API_KEY || "").trim(),
     debug: env.BM_DEBUG === "1" || env.BM_DEBUG === "true",
 
     deepseek: Object.freeze({
@@ -45,6 +44,9 @@ export function loadConfig(env = process.env, rootDir = ROOT_DIR) {
       healthCheckIntervalMs: 30 * 60 * 1000,
       estimatedWafTtlMs: 4 * 24 * 60 * 60 * 1000,
       estimatedSessionTtlMs: 30 * 24 * 60 * 60 * 1000,
+      // DeepSeek biz codes that mean "the chat session / parent message you referenced no longer exists".
+      // Only these (plus a narrow message pattern) trigger an explicit re-seed of a stateful branch.
+      staleContextBizCodes: readList(env.DEEPSEEK_STALE_CONTEXT_BIZ_CODES).map(Number),
     }),
 
     server: Object.freeze({
@@ -52,6 +54,12 @@ export function loadConfig(env = process.env, rootDir = ROOT_DIR) {
       keepAliveIntervalMs: 10_000,
     }),
 
+    sessions: Object.freeze({
+      dir: path.join(rootDir, ".sessions"),
+      ttlMs: 14 * 24 * 60 * 60 * 1000,
+      maxEntries: 1000,
+    }),
+
     pacing: Object.freeze({
       minTurnDelayMs: readNumber(env.MIN_TURN_DELAY_MS, 800),
       maxTurnDelayMs: readNumber(env.MAX_TURN_DELAY_MS, 2000),

package/src/deepseek/auth-cli.js

@@ -0,0 +1,119 @@
+// Terminal interaction for loading DeepSeek credentials and keeping them healthy.
+
+import readline from "node:readline";
+import { CONFIG } from "../config.js";
+import { createLogger } from "../logger.js";
+import { parseCurlCommand } from "./curl-parser.js";
+
+const log = createLogger("Auth");
+
+export function readCurlFromTerminal(promptLabel, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve, reject) => {
+    const rl = readline.createInterface({ input, output, terminal: Boolean(input.isTTY) });
+    console.log(`\n${promptLabel}`);
+    console.log("  (Chrome DevTools -> Network -> right-click 'completion' -> Copy as cURL or Copy as PowerShell, paste below, then press Enter)\n");
+
+    const lines = [];
+    let resolved = false;
+    const finish = () => {
+      if (resolved) return;
+      resolved = true;
+      rl.close();
+      resolve(lines.join("\n"));
+    };
+
+    rl.on("line", (line) => {
+      const trimmed = line.trim();
+      if (trimmed === "" && lines.length > 0) {
+        const prev = lines[lines.length - 1].trim();
+        if (!prev.endsWith("^") && !prev.endsWith("\\") && !prev.endsWith("`")) {
+          finish();
+          return;
+        }
+      }
+      if (trimmed !== "" || lines.length > 0) lines.push(line);
+    });
+
+    rl.on("close", () => {
+      if (resolved) return;
+      resolved = true;
+      if (lines.length === 0) reject(new Error("Input stream closed before receiving cURL command"));
+      else resolve(lines.join("\n"));
+    });
+  });
+}
+
+/**
+ * Owns the interactive credential lifecycle: initial paste, re-prompt on expiry, periodic health checks.
+ * @param {{ auth: import("./auth.js").DeepSeekAuth, fetchImpl?: typeof fetch, sanitize: (err: unknown) => string, port?: number }} deps
+ */
+export function createAuthSupervisor({ auth, fetchImpl = fetch, sanitize, port = CONFIG.port, config = CONFIG.deepseek }) {
+  let promptInProgress = false;
+  let healthTimer = null;
+
+  function printSummary() {
+    const summary = auth.statusSummary();
+    log.info(`Session active | Bearer token: ${auth.token ? "yes" : "no"} | Cookies in RAM: ${auth.cookies.size}`);
+    if (summary.next_due_expiry) {
+      log.info(`Earliest cookie due: "${summary.next_due_expiry.cookie}" in ${summary.next_due_expiry.remaining}`);
+    }
+    log.info(`Live expiry details available anytime at GET http://localhost:${port}/`);
+  }
+
+  async function promptAndLoad(promptLabel = "📋 Paste your DeepSeek cURL command:") {
+    if (promptInProgress) return;
+    promptInProgress = true;
+    try {
+      while (true) {
+        const rawCurl = await readCurlFromTerminal(promptLabel);
+        try {
+          auth.applyParsedSession(parseCurlCommand(rawCurl));
+          await auth.verify(fetchImpl);
+          printSummary();
+          return;
+        } catch (err) {
+          log.error(`❌ ${sanitize(err)}`);
+          if (!process.stdin.isTTY) throw err;
+          promptLabel = "📋 Please paste a fresh, valid DeepSeek cURL command:";
+        }
+      }
+    } finally {
+      promptInProgress = false;
+    }
+  }
+
+  function reprompt(reason) {
+    auth.markInvalid();
+    log.warn(`⚠️ ${reason}`);
+    if (process.stdin.isTTY && !promptInProgress) {
+      promptAndLoad("🔄 Session expired! Paste a fresh DeepSeek cURL command to resume:").catch((err) => {
+        log.error("Failed to reload session:", sanitize(err));
+      });
+    }
+  }
+
+  function startHealthMonitor() {
+    stopHealthMonitor();
+    healthTimer = setInterval(async () => {
+      if (!auth.verified || promptInProgress) return;
+      try {
+        await auth.verify(fetchImpl);
+        const summary = auth.statusSummary();
+        const expiryInfo = summary.next_due_expiry ? `${summary.next_due_expiry.cookie} due in ${summary.next_due_expiry.remaining}` : "active";
+        log.info(`Health check OK (age: ${summary.session_age}, ${expiryInfo})`);
+      } catch (err) {
+        reprompt(sanitize(err));
+      }
+    }, config.healthCheckIntervalMs);
+    healthTimer.unref?.();
+  }
+
+  function stopHealthMonitor() {
+    if (healthTimer) {
+      clearInterval(healthTimer);
+      healthTimer = null;
+    }
+  }
+
+  return Object.freeze({ promptAndLoad, reprompt, startHealthMonitor, stopHealthMonitor });
+}

package/src/deepseek/classify.js

@@ -35,3 +35,18 @@ export function deepSeekAuthFacts(res, jsonBody = null) {
   }
   return facts;
 }
+
+/**
+ * True only when DeepSeek tells us the chat session or parent message we referenced is gone.
+ * Deliberately narrow: anything else is a real failure that must surface to the client.
+ */
+export function isStaleContextRejection(res, jsonBody, staleBizCodes = []) {
+  if (!(res.status === 400 || res.status === 404 || res.status === 200)) return false;
+  const bizCode = jsonBody?.data?.biz_code ?? jsonBody?.code;
+  if (typeof bizCode === "number" && staleBizCodes.includes(bizCode)) return true;
+  const msg = String(jsonBody?.data?.biz_msg || jsonBody?.msg || "").toLowerCase();
+  if (!msg) return false;
+  const mentionsContext = /(chat[_ ]?session|parent[_ ]?message|message[_ ]?id)/.test(msg);
+  const mentionsGone = /(not\s*found|invalid|expired|deleted|does not exist|not exist)/.test(msg);
+  return mentionsContext && mentionsGone;
+}

package/src/deepseek/client.js

@@ -1,11 +1,12 @@
 // HTTP client for the DeepSeek web API. Every failure is classified and thrown; nothing is papered over.
 
 import { CONFIG } from "../config.js";
-import { DeepSeekAuthError, UpstreamError } from "../errors.js";
+import { DeepSeekAuthError, UpstreamContextRejectedError, UpstreamError } from "../errors.js";
 import {
   deepSeekAuthFacts,
   isDeepSeekAuthFailure,
   isHumanChallengeRequired,
+  isStaleContextRejection,
   isWafChallengeResponse,
   upstreamReason,
 } from "./classify.js";
@@ -95,19 +96,21 @@ export function createDeepSeekClient({ auth, powSolver, fetchImpl = fetch, confi
   }
 
   /**
-   * Opens a completion stream on a fresh DeepSeek chat session. Returns the raw SSE body; decoding lives in sse.js.
-   * @param {{ prompt: string, thinkingEnabled: boolean, searchEnabled: boolean, chatSessionId?: string, signal?: AbortSignal }} params
+   * Opens a completion stream. Returns the raw SSE body; decoding lives in sse.js.
+   * @param {{ chatSessionId: string, parentMessageId: number|null, prompt: string, thinkingEnabled: boolean, searchEnabled: boolean, signal?: AbortSignal }} params
    */
-  async function openCompletionStream({ prompt, thinkingEnabled, searchEnabled, chatSessionId, signal }) {
+  async function openCompletionStream({ chatSessionId, parentMessageId, prompt, thinkingEnabled, searchEnabled, signal }) {
     ensureCredentials();
-    const sessionId = chatSessionId || (await createChatSession());
+    if (typeof chatSessionId !== "string" || !chatSessionId) {
+      throw new Error("openCompletionStream requires a DeepSeek chat session id");
+    }
 
     const powHeader = powSolver.solve(await fetchPowChallenge());
     const res = await postJson(
       config.chatCompletionUrl,
       {
-        chat_session_id: sessionId,
-        parent_message_id: null,
+        chat_session_id: chatSessionId,
+        parent_message_id: parentMessageId,
         model_type: "default",
         prompt,
         ref_file_ids: [],
@@ -136,7 +139,10 @@ export function createDeepSeekClient({ auth, powSolver, fetchImpl = fetch, confi
       if (isDeepSeekAuthFailure(res, errJson)) {
         throw authFailure(isHumanChallengeRequired(errJson) ? HUMAN_CHALLENGE_NOTICE : SESSION_EXPIRED_NOTICE, res, errJson);
       }
-      const details = { status: res.status, body: errJson ?? rawText.slice(0, 500), chat_session_id: sessionId };
+      const details = { status: res.status, body: errJson ?? rawText.slice(0, 500), chat_session_id: chatSessionId, parent_message_id: parentMessageId };
+      if (isStaleContextRejection(res, errJson, config.staleContextBizCodes)) {
+        throw new UpstreamContextRejectedError(`DeepSeek rejected the referenced chat context: ${upstreamReason(errJson, rawText, res.status)}`, details);
+      }
       throw new UpstreamError(`DeepSeek completion failed: ${upstreamReason(errJson, rawText, res.status)}`, { details });
     }
 
@@ -145,7 +151,7 @@ export function createDeepSeekClient({ auth, powSolver, fetchImpl = fetch, confi
     }
 
     auth.markVerified();
-    return { streamBody: res.body, chatSessionId: sessionId };
+    return { streamBody: res.body };
   }
 
   return Object.freeze({ createChatSession, openCompletionStream, fetchPowChallenge });

package/src/errors.js

@@ -45,3 +45,14 @@ export class UpstreamError extends HttpError {
     this.name = "UpstreamError";
   }
 }
+
+/**
+ * Raised when DeepSeek explicitly rejected the chat session / parent message we referenced.
+ * The completion handler converts this into an explicit, logged re-seed for stateful branches.
+ */
+export class UpstreamContextRejectedError extends UpstreamError {
+  constructor(message, details) {
+    super(message, { statusCode: 502, code: "deepseek_context_rejected", details });
+    this.name = "UpstreamContextRejectedError";
+  }
+}

package/src/pi/messages.js

@@ -0,0 +1,130 @@
+// Canonical view of OpenAI-format messages and the fingerprints Black Mamba uses to verify that the context pi sends
+// matches the context DeepSeek already holds. Hashes are compared, never used as keys.
+
+import { BadRequestError } from "../errors.js";
+import { canonicalJson, sha256Hex, shortHash } from "../utils/hash.js";
+
+/** Exact prefix pi uses when it turns a compaction entry into a user message (pi-coding-agent core/messages.js). */
+export const PI_COMPACTION_SUMMARY_PREFIX =
+  "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
+/** Exact prefix pi uses for branch summaries after /tree navigation. */
+export const PI_BRANCH_SUMMARY_PREFIX = "The following is a summary of a branch that this conversation came back from:\n\n<summary>\n";
+
+export function normalizeRole(role) {
+  return typeof role === "string" ? role.trim().toLowerCase() : "";
+}
+
+/**
+ * Renders message content to text. Non-text parts are made visible as explicit placeholders instead of being dropped.
+ */
+export function contentToText(content) {
+  if (content === null || content === undefined) return "";
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (!part || typeof part !== "object") return "[unsupported content part]";
+        if (part.type === "text") return String(part.text ?? "");
+        if (part.type === "image_url" || part.type === "image") return "[image omitted: Black Mamba forwards text only]";
+        return `[unsupported content part: ${String(part.type)}]`;
+      })
+      .join("\n");
+  }
+  throw new BadRequestError("Message 'content' must be a string or an array of content parts", "invalid_message");
+}
+
+/** Parses tool-call arguments; returns { value, raw } where raw is kept only when the string is not valid JSON. */
+export function parseToolArguments(args) {
+  if (args === undefined || args === null) return { value: {} };
+  if (typeof args === "object") return { value: args };
+  if (typeof args === "string") {
+    try {
+      return { value: JSON.parse(args) };
+    } catch {
+      return { value: null, raw: args };
+    }
+  }
+  return { value: null, raw: String(args) };
+}
+
+export function toolCallName(tc) {
+  return tc?.function?.name ?? tc?.name ?? "";
+}
+
+export function toolCallArguments(tc) {
+  return tc?.function?.arguments ?? tc?.arguments;
+}
+
+/** Structural view of a message that ignores presentation-only fields (reasoning_content, name, ids). */
+export function canonicalizeMessage(msg) {
+  const role = normalizeRole(msg.role);
+  const canonical = { role, content: msg.content === null || msg.content === undefined ? null : contentToText(msg.content) };
+  if (role === "assistant" && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
+    canonical.tool_calls = msg.tool_calls.map((tc) => {
+      const parsed = parseToolArguments(toolCallArguments(tc));
+      return { name: toolCallName(tc), arguments: parsed.raw !== undefined ? parsed.raw : canonicalJson(parsed.value) };
+    });
+  }
+  if (role === "tool") canonical.tool_call_id = msg.tool_call_id ?? null;
+  return canonical;
+}
+
+export function messageHash(msg) {
+  return shortHash(canonicalJson(canonicalizeMessage(msg)));
+}
+
+export function hasLeadingSystem(messages) {
+  const role = normalizeRole(messages[0]?.role);
+  return role === "system" || role === "developer";
+}
+
+/** Hash of the leading system message (or "none"). The system prompt is verified separately from the conversation body. */
+export function systemHash(messages) {
+  return hasLeadingSystem(messages) ? messageHash(messages[0]) : "none";
+}
+
+/**
+ * Chain hash over the conversation body (every message except a leading system message) of the first `count` messages.
+ * Order-sensitive, so insertions, omissions and edits anywhere in the prefix are detected.
+ */
+export function prefixHash(messages, count = messages.length) {
+  const start = hasLeadingSystem(messages) ? 1 : 0;
+  let acc = "bm-v2";
+  for (let i = start; i < count; i++) {
+    acc = sha256Hex(`${acc}:${messageHash(messages[i])}`);
+  }
+  return acc.slice(0, 32);
+}
+
+/** Fingerprint of an assistant reply as Black Mamba produced it (streamed text + emitted tool calls). */
+export function assistantFingerprint({ text, toolCalls = [] }) {
+  return {
+    textHash: shortHash((text ?? "").trim()),
+    toolCalls: toolCalls.map((tc) => {
+      const parsed = parseToolArguments(tc.argumentsString ?? tc.arguments);
+      return { name: tc.name, argsHash: shortHash(parsed.raw !== undefined ? parsed.raw : canonicalJson(parsed.value)) };
+    }),
+  };
+}
+
+/** Fingerprint of an assistant message as pi replays it in a later request. */
+export function assistantFingerprintFromMessage(msg) {
+  return assistantFingerprint({
+    text: contentToText(msg.content),
+    toolCalls: Array.isArray(msg.tool_calls) ? msg.tool_calls.map((tc) => ({ name: toolCallName(tc), arguments: toolCallArguments(tc) })) : [],
+  });
+}
+
+export function fingerprintsEqual(a, b) {
+  if (!a || !b) return false;
+  if (a.textHash !== b.textHash || a.toolCalls.length !== b.toolCalls.length) return false;
+  return a.toolCalls.every((tc, i) => tc.name === b.toolCalls[i].name && tc.argsHash === b.toolCalls[i].argsHash);
+}
+
+export function isCompactionSummaryMessage(msg) {
+  return normalizeRole(msg?.role) === "user" && contentToText(msg.content).startsWith(PI_COMPACTION_SUMMARY_PREFIX);
+}
+
+export function isBranchSummaryMessage(msg) {
+  return normalizeRole(msg?.role) === "user" && contentToText(msg.content).startsWith(PI_BRANCH_SUMMARY_PREFIX);
+}

package/src/{prompt.js → pi/prompt.js}

@@ -1,56 +1,11 @@
 // Renders OpenAI-format messages into the single text prompt DeepSeek web accepts.
-// Stateless: dumps the entire conversation history into a fresh DeepSeek chat.
+// Two shapes: a *seed* (full history, starts a DeepSeek chat) and a *delta* (only what DeepSeek has not seen yet).
 
-import { BadRequestError } from "./errors.js";
+import { contentToText, normalizeRole, parseToolArguments, toolCallArguments, toolCallName } from "./messages.js";
 
 const ASSISTANT_LABEL_WITH_TOOLS = "M3GAN";
 const ASSISTANT_LABEL_PLAIN = "ASSISTANT";
 
-export function normalizeRole(role) {
-  return typeof role === "string" ? role.trim().toLowerCase() : "";
-}
-
-/**
- * Renders message content to text. Non-text parts are made visible as explicit placeholders instead of being dropped.
- */
-export function contentToText(content) {
-  if (content === null || content === undefined) return "";
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    return content
-      .map((part) => {
-        if (!part || typeof part !== "object") return "[unsupported content part]";
-        if (part.type === "text") return String(part.text ?? "");
-        if (part.type === "image_url" || part.type === "image") return "[image omitted: Black Mamba forwards text only]";
-        return `[unsupported content part: ${String(part.type)}]`;
-      })
-      .join("\n");
-  }
-  throw new BadRequestError("Message 'content' must be a string or an array of content parts", "invalid_message");
-}
-
-/** Parses tool-call arguments; returns { value, raw } where raw is kept only when the string is not valid JSON. */
-export function parseToolArguments(args) {
-  if (args === undefined || args === null) return { value: {} };
-  if (typeof args === "object") return { value: args };
-  if (typeof args === "string") {
-    try {
-      return { value: JSON.parse(args) };
-    } catch {
-      return { value: null, raw: args };
-    }
-  }
-  return { value: null, raw: String(args) };
-}
-
-export function toolCallName(tc) {
-  return tc?.function?.name ?? tc?.name ?? "";
-}
-
-export function toolCallArguments(tc) {
-  return tc?.function?.arguments ?? tc?.arguments;
-}
-
 function toolNames(tools) {
   return (Array.isArray(tools) ? tools : []).map((t) => t.function?.name || t.name).filter(Boolean);
 }
@@ -158,6 +113,7 @@ function renderDsmlToolBlock(tc) {
   return `<｜DSML｜invoke name="${name}">\n${params}\n</｜DSML｜invoke>`;
 }
 
+/** Assistant text followed by its tool calls rendered as native DSML blocks. */
 export function renderAssistantContent(msg) {
   let content = contentToText(msg.content);
   if (Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
@@ -185,9 +141,8 @@ function trailingDirective(lastMessage, tools) {
 }
 
 /**
- * Full-history prompt dumped to start a fresh DeepSeek chat session.
- * 1. With tools (e.g. Pi): M3GAN persona + tool definitions + history + trailing directive.
- * 2. Without tools (e.g. other apps): Plain transcript (SYSTEM: ..., USER: ..., ASSISTANT: ...).
+ * Full-history prompt used to start (or restart) a DeepSeek chat session.
+ * With tools: persona system prompt + labelled transcript. Without tools: plain labelled transcript.
  */
 export function renderSeedPrompt(messages, tools = []) {
   const hasTools = Array.isArray(tools) && tools.length > 0;
@@ -226,3 +181,42 @@ export function renderSeedPrompt(messages, tools = []) {
   if (directive) prompt += `\n${directive}`;
   return prompt;
 }
+
+/**
+ * Prompt for one DeepSeek turn containing only the messages DeepSeek has not seen.
+ * @param {object[]} deltaMessages  Messages after the last DeepSeek reply (never empty).
+ * @param {object[]} tools
+ * @param {{ systemUpdate?: string|null }} [options]  New full system prompt when it changed since the parent node.
+ */
+export function renderDeltaPrompt(deltaMessages, tools = [], { systemUpdate = null } = {}) {
+  if (!Array.isArray(deltaMessages) || deltaMessages.length === 0) {
+    throw new Error("renderDeltaPrompt requires at least one message");
+  }
+  const multiple = deltaMessages.length > 1;
+  const parts = [];
+
+  if (systemUpdate) {
+    parts.push(`<<System prompt update>>\nThe system prompt changed. The complete current system prompt follows:\n${systemUpdate}`);
+  }
+
+  deltaMessages.forEach((msg, i) => {
+    const role = normalizeRole(msg.role);
+    if (role === "tool") {
+      const label = multiple ? `Result for tool call ${i + 1}:` : null;
+      parts.push(renderToolResultBlock(msg, label));
+    } else if (role === "user") {
+      const text = contentToText(msg.content);
+      parts.push(multiple ? `USER: ${text}` : text);
+    } else if (role === "assistant") {
+      parts.push(`${ASSISTANT_LABEL_WITH_TOOLS}: ${renderAssistantContent(msg)}`);
+    } else if (role === "system" || role === "developer") {
+      parts.push(`<<System update>>\n${contentToText(msg.content)}`);
+    } else {
+      parts.push(`${role.toUpperCase()}: ${contentToText(msg.content)}`);
+    }
+  });
+
+  const directive = trailingDirective(deltaMessages[deltaMessages.length - 1], tools);
+  if (directive) parts.push(directive);
+  return parts.join("\n\n");
+}

package/src/{request.js → pi/request.js}

@@ -1,9 +1,29 @@
-// Validates an OpenAI-compatible chat completion request.
+// Validates an OpenAI-compatible chat completion request and extracts the pi routing contract.
+//
+// Routing contract (sent by the pi extension in pi-extension/black-mamba.ts):
+//   x-session-id         pi session id (also sent natively by pi-ai when sessionAffinityFormat = "openrouter")
+//   x-entry-id           pi session entry id at which this request is made (the future parent of the assistant entry)
+//   x-parent-id          entry id at which the previous *successful* assistant on this branch was requested
+//   x-parent-session-id  when the session was created by /fork: the pi session id it was forked from
+//
+// Without x-session-id the request is treated as stateless. With x-session-id but without x-entry-id the request is
+// rejected: there is no way to map it onto the DeepSeek tree precisely, and silently degrading would hide the problem.
 
-import { BadRequestError } from "./errors.js";
+import { BadRequestError } from "../errors.js";
 
 const DEFAULT_MODEL = "deepseek-chat";
 
+function getHeader(headers, name) {
+  if (!headers || typeof headers !== "object") return "";
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== lower) continue;
+    const str = Array.isArray(value) ? value[0] : value;
+    return typeof str === "string" ? str.trim() : str != null ? String(str).trim() : "";
+  }
+  return "";
+}
+
 function validateToolCall(tc, index) {
   if (!tc || typeof tc !== "object") throw new BadRequestError(`tool_calls[${index}] must be an object`, "invalid_tool_call");
   const fn = tc.function;
@@ -59,10 +79,27 @@ function resolveThinking(body, lowerModel) {
   return lowerModel.includes("reasoner") || lowerModel.includes("r1") || lowerModel.includes("think");
 }
 
+function extractRouting(headers) {
+  const sessionId = getHeader(headers, "x-session-id");
+  if (!sessionId) return null;
+
+  const entryId = getHeader(headers, "x-entry-id");
+  if (!entryId) {
+    throw new BadRequestError(
+      "x-session-id was sent without x-entry-id. Black Mamba maps pi's session tree onto DeepSeek precisely and needs the pi extension " +
+        "(pi-extension/black-mamba.ts -> ~/.pi/agent/extensions/) to send x-entry-id and x-parent-id. Remove x-session-id for stateless use.",
+      "missing_entry_id"
+    );
+  }
+  const parentEntryId = getHeader(headers, "x-parent-id") || null;
+  const parentSessionId = getHeader(headers, "x-parent-session-id") || null;
+  return Object.freeze({ sessionId, entryId, parentEntryId, parentSessionId });
+}
+
 /**
- * @returns {{ messages: object[], tools: object[], model: string, stream: boolean, includeUsage: boolean, thinkingEnabled: boolean, searchEnabled: boolean }}
+ * @returns {{ messages: object[], tools: object[], model: string, stream: boolean, includeUsage: boolean, thinkingEnabled: boolean, searchEnabled: boolean, routing: {sessionId:string, entryId:string, parentEntryId:string|null, parentSessionId:string|null}|null }}
  */
-export function parseChatRequest(body) {
+export function parseChatRequest(body, headers = {}) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
     throw new BadRequestError("Request body must be a JSON object", "invalid_body");
   }
@@ -82,5 +119,6 @@ export function parseChatRequest(body) {
     includeUsage: Boolean(body.stream_options && body.stream_options.include_usage),
     thinkingEnabled: resolveThinking(body, lowerModel),
     searchEnabled: lowerModel.includes("search") || lowerModel.endsWith(":online"),
+    routing: extractRouting(headers),
   });
 }

package/src/{response.js → pi/response.js}

@@ -1,6 +1,6 @@
 // OpenAI-compatible response payloads (JSON and SSE chunks) and usage accounting.
 
-import { estimateTokenCount } from "./tokens.js";
+import { estimateTokenCount } from "../utils/tokens.js";
 
 export function createCompletionMetadata(nowMs = Date.now()) {
   return { completionId: `chatcmpl-${nowMs}`, created: Math.floor(nowMs / 1000) };
@@ -34,11 +34,27 @@ export function buildUsageStats({ prompt, reply, turnTokens = 0, cachedTokens =
   return usage;
 }
 
+/** Extra, non-OpenAI fields that make every mapping decision visible to the caller. */
+export function buildMappingInfo({ sessionId, deepseekSessionId, messageId, parentMessageId, strategy, reason, deltaMessageCount }) {
+  const info = {
+    chat_session_id: sessionId,
+    deepseek_session_id: deepseekSessionId ?? null,
+    deepseek_message_id: messageId !== null && messageId !== undefined ? String(messageId) : null,
+    black_mamba: {
+      strategy,
+      reason: reason ?? null,
+      deepseek_parent_message_id: parentMessageId !== null && parentMessageId !== undefined ? String(parentMessageId) : null,
+    },
+  };
+  if (deltaMessageCount !== undefined) info.black_mamba.delta_messages = deltaMessageCount;
+  return info;
+}
+
 function baseChunk({ completionId, created, model }, choices, extra = {}) {
   return { id: completionId, object: "chat.completion.chunk", created, model, choices, ...extra };
 }
 
-export function formatCompletionResponse({ completionId, created, model, content, toolCalls = [], usage }) {
+export function formatCompletionResponse({ completionId, created, model, content, toolCalls = [], usage, mapping }) {
   const hasTools = toolCalls.length > 0;
   const message = { role: "assistant", content: hasTools ? content || null : content };
   if (hasTools) message.tool_calls = toolCalls;
@@ -49,6 +65,7 @@ export function formatCompletionResponse({ completionId, created, model, content
     model,
     choices: [{ index: 0, message, finish_reason: hasTools ? "tool_calls" : "stop" }],
     usage,
+    ...(mapping ?? {}),
   };
 }
 
@@ -80,8 +97,8 @@ export function formatStreamToolCallArgsEvent(meta, { toolCallIndex, argumentsCh
   return sseFrame(baseChunk(meta, [{ index: 0, delta: { tool_calls: [{ index: toolCallIndex, function: { arguments: argumentsChunk } }] }, finish_reason: null }]));
 }
 
-export function formatStreamFinishEvent(meta, { finishReason = "stop" } = {}) {
-  return sseFrame(baseChunk(meta, [{ index: 0, delta: {}, finish_reason: finishReason }]));
+export function formatStreamFinishEvent(meta, { finishReason = "stop", mapping } = {}) {
+  return sseFrame(baseChunk(meta, [{ index: 0, delta: {}, finish_reason: finishReason }], mapping ?? {}));
 }
 
 export function formatStreamUsageEvent(meta, usage) {