@mathew-macharia/black-mamba 1.0.3 → 1.0.4

package/src/{server/http.js → http.js}

@@ -1,17 +1,18 @@
 // HTTP plumbing: routing, body parsing, API-key validation, JSON/SSE writers, error rendering.
 
 import crypto from "node:crypto";
-import { CONFIG } from "../config.js";
-import { BadRequestError, HttpError } from "../errors.js";
-import { createLogger } from "../logger.js";
-import { formatStreamErrorEvent } from "../pi/response.js";
+import { CONFIG } from "./config.js";
+import { BadRequestError, HttpError } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { formatStreamErrorEvent } from "./response.js";
 
 const SUPPORTED_MODEL_IDS = Object.freeze(["deepseek-chat", "deepseek-reasoner", "deepseek-chat-search", "deepseek-reasoner-search"]);
-const CORS_HEADERS = "Content-Type, Authorization, X-Session-Id, X-Entry-Id, X-Parent-Id, X-Parent-Session-Id";
+const CORS_HEADERS = "Content-Type, Authorization";
 
 export function validateApiKey(req, apiKey) {
+  if (!apiKey) return true; // if no apiKey configured, allow all
   const authHeader = req.headers["authorization"];
-  if (typeof authHeader !== "string" || !authHeader.startsWith("Bearer ") || !apiKey) return false;
+  if (typeof authHeader !== "string" || !authHeader.startsWith("Bearer ")) return false;
   const expected = Buffer.from(apiKey, "utf8");
   const provided = Buffer.from(authHeader.slice("Bearer ".length), "utf8");
   return expected.length === provided.length && crypto.timingSafeEqual(expected, provided);
@@ -68,7 +69,7 @@ export function errorBody(err, sanitize) {
   return { message: sanitize(err instanceof Error ? err.message : "Internal server error"), code: "internal_error" };
 }
 
-async function routeAuthed(req, res, pathname, { handleChatCompletions, graph }) {
+async function routeAuthed(req, res, pathname, { handleChatCompletions }) {
   if (req.method === "GET" && pathname === "/v1/models") {
     const created = Math.floor(Date.now() / 1000);
     sendJson(res, 200, { object: "list", data: SUPPORTED_MODEL_IDS.map((id) => ({ id, object: "model", created, owned_by: "deepseek" })) });
@@ -79,41 +80,22 @@ async function routeAuthed(req, res, pathname, { handleChatCompletions, graph })
     return;
   }
 
-  const sessionMatch = pathname.match(/^\/v1\/sessions\/([^/]+)$/);
-  if (sessionMatch) {
-    const piSessionId = decodeURIComponent(sessionMatch[1]);
-    if (req.method === "GET") {
-      const session = await graph.getSession(piSessionId);
-      if (!session) {
-        sendJson(res, 404, { error: { message: `No mapping for pi session ${piSessionId}`, code: "session_not_found" } });
-      } else {
-        sendJson(res, 200, graph.describeSession(session));
-      }
-      return;
-    }
-    if (req.method === "DELETE") {
-      const existed = await graph.deleteSession(piSessionId);
-      sendJson(res, 200, { deleted: existed, piSessionId, note: "The next request for this session will seed a fresh DeepSeek chat." });
-      return;
-    }
-  }
-
   sendJson(res, 404, { error: { message: "Route not found", code: "not_found" } });
 }
 
 /**
  * @param {object} deps
- * @param {(req, res) => Promise<void>} [deps.handleChatCompletions]
+ * @param {(req, res) => Promise<void>} deps.handleChatCompletions
  * @param {() => object} [deps.getStatus]
- * @param {import("../session/graph.js").SessionGraph} [deps.graph]
  * @param {(err: unknown) => string} deps.sanitize
- * @param {(authorizationHeader: string) => object|null} [deps.resolveAccount]
+ * @param {string} [deps.apiKey]
+ * @param {object} [deps.logger]
  */
-export function createRequestHandler({ handleChatCompletions, getStatus, graph, sanitize, apiKey = "", logger = createLogger("Server"), resolveAccount = null }) {
+export function createRequestHandler({ handleChatCompletions, getStatus = () => ({ status: "ok" }), sanitize, apiKey = CONFIG.apiKey, logger = createLogger("Server") }) {
   return async function handleRequest(req, res) {
     res.setHeader("Access-Control-Allow-Origin", "*");
     res.setHeader("Access-Control-Allow-Headers", CORS_HEADERS);
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
 
     if (req.method === "OPTIONS") {
       res.writeHead(204);
@@ -122,24 +104,8 @@ export function createRequestHandler({ handleChatCompletions, getStatus, graph,
     }
 
     const pathname = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`).pathname;
-    let requestLog = logger;
 
     try {
-      if (resolveAccount) {
-        const account = resolveAccount(req.headers.authorization);
-        if (!account) {
-          sendJson(res, 401, { error: { message: "Invalid API key", code: "invalid_api_key" } });
-          return;
-        }
-        requestLog = account.logger;
-        if (req.method === "GET" && pathname === "/") {
-          sendJson(res, 200, account.auth.statusSummary());
-          return;
-        }
-        await routeAuthed(req, res, pathname, { handleChatCompletions: account.handleChatCompletions, graph: account.graph });
-        return;
-      }
-
       if (req.method === "GET" && pathname === "/") {
         sendJson(res, 200, getStatus());
         return;
@@ -148,12 +114,12 @@ export function createRequestHandler({ handleChatCompletions, getStatus, graph,
         sendJson(res, 401, { error: { message: "Invalid API key", code: "invalid_api_key" } });
         return;
       }
-      await routeAuthed(req, res, pathname, { handleChatCompletions, graph });
+      await routeAuthed(req, res, pathname, { handleChatCompletions });
     } catch (err) {
       const statusCode = err instanceof HttpError ? err.statusCode : 500;
       const body = errorBody(err, sanitize);
-      if (statusCode >= 500) requestLog.error(`Request error (${req.method} ${pathname}):`, body.message, body.details ? JSON.stringify(body.details) : "");
-      else requestLog.warn(`Request rejected (${req.method} ${pathname}) ${statusCode}:`, body.message);
+      if (statusCode >= 500) logger.error(`Request error (${req.method} ${pathname}):`, body.message, body.details ? JSON.stringify(body.details) : "");
+      else logger.warn(`Request rejected (${req.method} ${pathname}) ${statusCode}:`, body.message);
 
       if (!res.headersSent) {
         sendJson(res, statusCode, { error: body });

package/src/{server/pacing.js → pacing.js}

@@ -1,6 +1,6 @@
 // Human-like pacing between consecutive DeepSeek turns (DeepSeek web challenges rapid-fire automation).
 
-import { CONFIG } from "../config.js";
+import { CONFIG } from "./config.js";
 
 export function calculateTurnPacingDelay({ lastFinishedAt, now = Date.now(), minDelayMs = CONFIG.pacing.minTurnDelayMs, maxDelayMs = CONFIG.pacing.maxTurnDelayMs, randomFn = Math.random }) {
   if (!lastFinishedAt || lastFinishedAt <= 0) return 0;

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

@@ -1,11 +1,56 @@
 // Renders OpenAI-format messages into the single text prompt DeepSeek web accepts.
-// Two shapes: a *seed* (full history, starts a DeepSeek chat) and a *delta* (only what DeepSeek has not seen yet).
+// Stateless: dumps the entire conversation history into a fresh DeepSeek chat.
 
-import { contentToText, normalizeRole, parseToolArguments, toolCallArguments, toolCallName } from "./messages.js";
+import { BadRequestError } from "./errors.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);
 }
@@ -113,7 +158,6 @@ 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) {
@@ -141,8 +185,9 @@ function trailingDirective(lastMessage, tools) {
 }
 
 /**
- * Full-history prompt used to start (or restart) a DeepSeek chat session.
- * With tools: persona system prompt + labelled transcript. Without tools: plain labelled transcript.
+ * 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: ...).
  */
 export function renderSeedPrompt(messages, tools = []) {
   const hasTools = Array.isArray(tools) && tools.length > 0;
@@ -181,42 +226,3 @@ 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/{pi/request.js → request.js}

@@ -1,29 +1,9 @@
-// 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.
+// Validates an OpenAI-compatible chat completion request.
 
-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;
@@ -79,27 +59,10 @@ 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, routing: {sessionId:string, entryId:string, parentEntryId:string|null, parentSessionId:string|null}|null }}
+ * @returns {{ messages: object[], tools: object[], model: string, stream: boolean, includeUsage: boolean, thinkingEnabled: boolean, searchEnabled: boolean }}
  */
-export function parseChatRequest(body, headers = {}) {
+export function parseChatRequest(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
     throw new BadRequestError("Request body must be a JSON object", "invalid_body");
   }
@@ -119,6 +82,5 @@ export function parseChatRequest(body, headers = {}) {
     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/{pi/response.js → response.js}

@@ -1,6 +1,6 @@
 // OpenAI-compatible response payloads (JSON and SSE chunks) and usage accounting.
 
-import { estimateTokenCount } from "../utils/tokens.js";
+import { estimateTokenCount } from "./tokens.js";
 
 export function createCompletionMetadata(nowMs = Date.now()) {
   return { completionId: `chatcmpl-${nowMs}`, created: Math.floor(nowMs / 1000) };
@@ -34,27 +34,11 @@ 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, mapping }) {
+export function formatCompletionResponse({ completionId, created, model, content, toolCalls = [], usage }) {
   const hasTools = toolCalls.length > 0;
   const message = { role: "assistant", content: hasTools ? content || null : content };
   if (hasTools) message.tool_calls = toolCalls;
@@ -65,7 +49,6 @@ export function formatCompletionResponse({ completionId, created, model, content
     model,
     choices: [{ index: 0, message, finish_reason: hasTools ? "tool_calls" : "stop" }],
     usage,
-    ...(mapping ?? {}),
   };
 }
 
@@ -97,8 +80,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", mapping } = {}) {
-  return sseFrame(baseChunk(meta, [{ index: 0, delta: {}, finish_reason: finishReason }], mapping ?? {}));
+export function formatStreamFinishEvent(meta, { finishReason = "stop" } = {}) {
+  return sseFrame(baseChunk(meta, [{ index: 0, delta: {}, finish_reason: finishReason }]));
 }
 
 export function formatStreamUsageEvent(meta, usage) {

package/docs/accounts.md

@@ -1,37 +0,0 @@
-# Accounts
-
-Each subdirectory of `accounts/` is one DeepSeek login. Folder names are read in sorted order. Only directories are accounts. `bm` reads these files from the working directory where you started it.
-
-```
-accounts/<name>/
-  api-key.txt    bearer key the app sends to Black Mamba
-  curl.txt       DeepSeek bearer token and cookies, from a browser copy
-  logs.txt       this account's log, created on the first write
-  .session/      one JSON file per Pi session id
-```
-
-`api-key.txt` and `curl.txt` are required before startup. `logs.txt` and `.session/` are created by the process.
-
-`api-key.txt` is a single trimmed line. The HTTP server compares `Authorization: Bearer <key>` with that line. This key is the key you choose for the app. It is separate from the DeepSeek token inside `curl.txt`.
-
-`curl.txt` is parsed once at startup. Accepted input is a cURL command, a PowerShell `Invoke-WebRequest` command, or a `fetch()` snippet. The parser keeps the bearer token, the cookie header, and these client headers when they are present: `user-agent`, `x-device-id`, `x-client-version`, `x-client-locale`, `x-client-timezone-offset`, `x-client-platform`, `x-client-bundle-id`. The token and cookies are kept in memory and updated from `Set-Cookie`. `curl.txt` is not rewritten. Replacing it takes effect on the next start of `bm`.
-
-Two account folders cannot contain the same `api-key.txt` value. Startup throws `Duplicate api key in accounts/<first> and accounts/<second>`.
-
-## Terminal and logs.txt
-
-The terminal shows the `Server` log: the listen line, `<name> logged in successfully`, `<name> log in failed`, and `<name> logged out`. Those lines are not copied into `logs.txt`.
-
-`accounts/<name>/logs.txt` is this account only. Lines are appended. Each line starts with an ISO timestamp and `INFO`, `WARN`, or `ERROR`, then `[<name>]`. Startup writes either `DeepSeek login verified` or the verification error. Later lines include the mapping plan for each completion, pacing waits, recorded session nodes, health checks (`Health check OK ...` every 30 minutes while the login is verified), and request errors for this account.
-
-`<name> logged out` is printed on the terminal only after startup verification succeeded. The same failure text is written to `logs.txt`. If startup verification failed, the 30-minute timer still fires, and its callback returns without calling DeepSeek until a later successful DeepSeek response marks the login verified.
-
-Error text that is sent to clients, and the account errors that are passed through the redactor, replace the account key, the DeepSeek bearer token, and the cookie string with `[REDACTED]`.
-
-## .session/
-
-`.session/` holds the map for this account. One JSON file per Pi session id (schema version 2). The file name is a sanitized prefix of the id plus a short hash, not the raw id alone.
-
-A file is dropped when it has not been accessed for 14 days. The process also prunes about once an hour. Up to 1000 sessions are kept in memory; older ones are dropped from memory and reloaded from disk if the file is still inside the 14-day window.
-
-`DELETE /v1/sessions/<id>` removes that session's file. It does not delete the chat on DeepSeek. The next request for that Pi session starts a new DeepSeek chat.

package/docs/config.md

@@ -1,40 +0,0 @@
-# Config
-
-Settings are environment variables. A `.env` file in the working directory (the directory where you run `bm`) supplies variables that are not already set in the process environment. There is no `API_KEY` in `.env`. The bearer key for each account is `accounts/<name>/api-key.txt`.
-
-A non-numeric value for a numeric variable stops startup with `Expected a numeric environment value, got "<value>"`. An empty value uses the default.
-
-## PORT
-
-TCP port. Default `3000`. The process logs `http://localhost:<port>`.
-
-## MIN_TURN_DELAY_MS
-
-Shortest pause between the end of one DeepSeek turn and the start of the next turn on the same account. Default `800`. The first turn of a process is not delayed. Values below 0 are treated as 0.
-
-## MAX_TURN_DELAY_MS
-
-Longest pause for that same gap. Default `2000`. Each wait picks a random target between the minimum and the maximum, then sleeps only for the part of that target still remaining. If this value is lower than the minimum, the minimum is used as both ends.
-
-## DEEPSEEK_STALE_CONTEXT_BIZ_CODES
-
-Comma-separated DeepSeek `biz_code` numbers. Whitespace around each code is ignored. Unset means an empty list.
-
-On a completion response that is JSON rather than an event stream, with HTTP status 400, 404, or 200, the chat context is treated as gone when either of these is true:
-
-- `data.biz_code` or `code` is a number in this list, or
-- the message mentions a chat session, parent message, or message id, and also says that it was not found, invalid, expired, deleted, or does not exist.
-
-On a `delta` turn that rejection is turned into `reseed_upstream_rejected` (one new chat, full history). Every other upstream error is returned as HTTP 502.
-
-Login failures are classified first and are not re-seeds. Those are HTTP 401, an HTTP 202 or `x-amzn-waf-action: challenge` WAF response, biz codes `401`, `40001`, `40002`, and `40003`, and messages that contain `CHALLENGE_REQUIRED` or `UNAUTHORIZED`. A code that is both in this list and in that auth set is handled as a login failure.
-
-## BM_DEBUG
-
-Set to `1` or `true` to enable the logger's debug method. Any other value leaves it off. Debug lines use the same destination as the other lines for that logger: the terminal for the server log, and `accounts/<name>/logs.txt` for an account.
-
-## DEEPSEEK_BASE_URL
-
-DeepSeek web origin. Default `https://chat.deepseek.com`. Trailing slashes are removed. Login, chat create, the proof-of-work challenge, and completion are called under this origin at `/api/v0/users/current`, `/api/v0/chat_session/create`, `/api/v0/chat/create_pow_challenge`, and `/api/v0/chat/completion`.
-
-The proof-of-work file `sha3_wasm_bg.wasm` lives in `src/deepseek/` and is published with `src`. If that installed file is missing, startup downloads it from DeepSeek's static file host and saves it there. That download URL does not follow `DEEPSEEK_BASE_URL`.

package/docs/http.md

@@ -1,171 +0,0 @@
-# HTTP
-
-Base URL: `http://localhost:<PORT>` (`PORT` defaults to 3000).
-
-Every route below requires:
-
-```
-Authorization: Bearer <key>
-```
-
-`<key>` is the line in one account's `api-key.txt`. The comparison is exact, including length. A missing or unknown key returns HTTP 401:
-
-```json
-{ "error": { "message": "Invalid API key", "code": "invalid_api_key" } }
-```
-
-`OPTIONS` on any path returns 204. CORS allows origin `*`, methods `GET`, `POST`, `DELETE`, and `OPTIONS`, and headers `Content-Type`, `Authorization`, `X-Session-Id`, `X-Entry-Id`, `X-Parent-Id`, `X-Parent-Session-Id`.
-
-The JSON body limit on `POST /v1/chat/completions` is 10 MiB. Errors use `{ "error": { "message", "code", "details" } }`. `details` is omitted when there are none. If the failure happens after an SSE response has started, the same object is a `data:` event, followed by `data: [DONE]`.
-
-## GET /
-
-Returns the selected account's login summary.
-
-```json
-{
-  "status": "ok",
-  "authenticated": true,
-  "session_age": "<duration since curl.txt was loaded>",
-  "last_verified_at": "<ISO time>",
-  "auth_cookies": { "<cookie-name>": "<remaining>" },
-  "next_due_expiry": { "cookie": "<cookie-name>", "remaining": "<remaining>" }
-}
-```
-
-`session_age`, `last_verified_at`, `auth_cookies`, and `next_due_expiry` appear only when there is something to report. A remaining time that starts with `~` is an estimate. `authenticated` is false when the DeepSeek check has failed.
-
-## GET /v1/models
-
-The body is `{ "object": "list", "data": [ ... ] }`. `data` has one object per id: `deepseek-chat`, `deepseek-reasoner`, `deepseek-chat-search`, `deepseek-reasoner-search`. Each object is `{ "id", "object": "model", "created", "owned_by": "deepseek" }`. `created` is the current Unix time in seconds.
-
-## POST /v1/chat/completions
-
-Body fields that are read:
-
-| Field | Behavior |
-| --- | --- |
-| `messages` | Required non-empty array. Each item needs `role`. `content` is a string or an array of parts, unless an assistant message has `tool_calls`. A `tool` message needs `tool_call_id`. |
-| `model` | String. Default `deepseek-chat`. Any other string is accepted. |
-| `stream` | `true` returns SSE. Any other value returns one JSON object. |
-| `stream_options.include_usage` | When `stream` is true and this value is truthy, a usage event is sent before `[DONE]`. |
-| `tools` | Array of tools. When non-empty, DSML blocks in the reply become `tool_calls`. |
-| `thinking` | `{ "type": "enabled" }` or `{ "type": "disabled" }`. `false` turns thinking off. |
-| `thinking_enabled` | Boolean override. |
-| `reasoning` | `false` turns thinking off. |
-
-Other JSON fields are ignored.
-
-Thinking is on when the lowercased model contains `reasoner`, `r1`, or `think`, unless a field above turns it off. Search is on when the lowercased model contains `search` or ends with `:online`. Of the four listed models, `deepseek-chat` is neither, `deepseek-reasoner` is thinking, `deepseek-chat-search` is search, and `deepseek-reasoner-search` is both. The completion body sent to DeepSeek sets `model_type` to `default`.
-
-### Stateless calls and Pi headers
-
-No `x-session-id`: the call is stateless. The full `messages` array is sent to a new DeepSeek chat. Nothing is written to `.session/`. The strategy is `stateless_seed`.
-
-`x-session-id` without `x-entry-id`: HTTP 400, code `missing_entry_id`.
-
-With both, the call is stored and later turns can continue the same DeepSeek chat:
-
-| Header | Role |
-| --- | --- |
-| `x-session-id` | Pi session id. The session file key. |
-| `x-entry-id` | Pi entry id of this request. The node is stored under this id. |
-| `x-parent-id` | Entry id of the previous successful assistant request on this branch. Omitted on the first turn. |
-| `x-parent-session-id` | When this session was forked, the Pi session it was forked from. If the parent entry is not in the current session, nodes are copied from that session. |
-
-Header names are case-insensitive.
-
-### stream false
-
-HTTP 200, `Content-Type: application/json`, header `x-black-mamba-strategy: <strategy>`.
-
-Read these fields:
-
-- `choices[0].message.content` — assistant text. `null` when the message is only tool calls and the text is empty.
-- `choices[0].message.tool_calls` — present when tools were requested and the reply contained DSML calls. Each item has `id`, `type` (`function`), and `function.name` plus `function.arguments` (a JSON string).
-- `choices[0].finish_reason` — `stop`, or `tool_calls` when `tool_calls` is present.
-- `usage.prompt_tokens`, `usage.completion_tokens`, `usage.total_tokens`.
-- `usage.prompt_tokens_details.cached_tokens` — present when this DeepSeek branch already has a token total from earlier turns. It is the sum of those turn totals, not a field DeepSeek returns on this response.
-- `black_mamba.strategy` — one of the names in [mapping.md](mapping.md).
-- `black_mamba.reason` — why that strategy was chosen, or `null`.
-- `black_mamba.delta_messages` — how many messages were rendered into the prompt.
-- `black_mamba.usage_source` — `deepseek` when the token total came from DeepSeek's stream, `estimated` when it was counted from the prompt and reply text.
-- `black_mamba.deepseek_parent_message_id` — parent message id sent to DeepSeek, or `null` for a new chat.
-- `deepseek_session_id`, `deepseek_message_id` — ids from this turn. `deepseek_message_id` is null if DeepSeek sent none (a stateless turn can still return text in that case).
-- `chat_session_id` — the Pi session id, or the DeepSeek chat id when the call was stateless.
-
-`id` is `chatcmpl-<milliseconds>`, `object` is `chat.completion`, `created` is Unix seconds, `model` echoes the request model.
-
-Thinking text is only on the SSE stream, as `reasoning_content`.
-
-### stream true
-
-HTTP 200, `Content-Type: text/event-stream`, same `x-black-mamba-strategy` header. Comment lines `: keep-alive` are sent about every 10 seconds while DeepSeek is still streaming.
-
-Read the `data:` JSON events:
-
-- First event: `choices[0].delta.role` is `assistant`.
-- Reply text: concatenate `choices[0].delta.content`.
-- Thinking text: concatenate `choices[0].delta.reasoning_content`.
-- Tool calls: `choices[0].delta.tool_calls[]` with `index`, `id`, `type`, `function.name`, then `function.arguments`.
-- Finish event: `choices[0].finish_reason` is `stop` or `tool_calls`, and the mapping fields listed above sit on that event next to `id` and `choices`.
-- Usage event, only when `stream_options.include_usage` is true: top-level `usage` with the same token fields, and an empty `choices` array.
-- The stream ends with `data: [DONE]`.
-
-## GET /v1/sessions/<id>
-
-`<id>` is the Pi session id (`x-session-id`), URL-decoded. Unknown id: HTTP 404, code `session_not_found`.
-
-A known session returns:
-
-```json
-{
-  "piSessionId": "<id>",
-  "createdAt": "<ISO time>",
-  "lastAccessedAt": "<ISO time>",
-  "forkedFrom": null,
-  "nodeCount": 1,
-  "nodes": [
-    {
-      "piEntryId": "<entry>",
-      "piParentEntryId": "<parent entry or null>",
-      "strategy": "<strategy>",
-      "reason": "<reason or null>",
-      "deepseek": {
-        "sessionId": "<deepseek chat id>",
-        "messageId": "<deepseek message id>",
-        "parentMessageId": null
-      },
-      "messageCount": 0,
-      "turnTokens": 0,
-      "createdAt": "<ISO time>"
-    }
-  ]
-}
-```
-
-`forkedFrom` is `{ "piSessionId", "adoptedAt" }` when this session copied nodes from another Pi session. `nodes` are ordered by `createdAt`.
-
-## DELETE /v1/sessions/<id>
-
-Removes the local session file and the in-memory copy. The DeepSeek chat is left as it is. HTTP 200:
-
-```json
-{
-  "deleted": true,
-  "piSessionId": "<id>",
-  "note": "The next request for this session will seed a fresh DeepSeek chat."
-}
-```
-
-`deleted` is true when that id was loaded in memory. The file is removed either way. The next completion for this `x-session-id` uses a new DeepSeek chat (`root_seed` or another seed strategy).
-
-## Status codes on completions
-
-| HTTP | When |
-| --- | --- |
-| 400 | Body or headers fail validation, including `missing_entry_id`. |
-| 401 | Bad account key, or DeepSeek rejected the saved login (`deepseek_auth`). |
-| 409 | `no_new_messages`: a `delta` plan found the parent, and there is no message after that parent's reply. |
-| 502 | DeepSeek failed, or a sessioned turn ended without `response_message_id` (`deepseek_missing_message_id`). |
-| 500 | Anything else, including a proof-of-work solve failure. |