@mathew-macharia/black-mamba 0.0.0-stage → 1.0.0

package/.env.example

@@ -0,0 +1,13 @@
+PORT=3000
+
+# Human pacing delay between turns (800ms - 2000ms with jitter to mimic human reading pace and avoid Cloudflare CHALLENGE_REQUIRED)
+# MIN_TURN_DELAY_MS=800
+# MAX_TURN_DELAY_MS=2000
+
+# DeepSeek biz codes that mean "the chat session / parent message you referenced no longer exists".
+# Only these (plus a narrow "chat_session|parent_message ... not found|invalid|expired" message match) trigger an
+# explicit re-seed of a branch (strategy reseed_upstream_rejected). Every other upstream error surfaces as 502.
+# DEEPSEEK_STALE_CONTEXT_BIZ_CODES=40401,40002
+
+# Verbose mapping/decoder logging
+# BM_DEBUG=1

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# Black Mamba
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenAI-compatible proxy. One process, one URL. Each DeepSeek login is a folder under `accounts/`.
+
+Requires Node.js 18 or newer.
+
+```
+npm install -g @mathew-macharia/black-mamba
+```
+
+Run `bm` in the folder that holds your data. That folder is where it reads `accounts/`, `.env`, and `sha3_wasm_bg.wasm`.
+
+```
+accounts/<name>/api-key.txt
+accounts/<name>/curl.txt
+```
+
+`api-key.txt` is the bearer key your app sends. `curl.txt` is a copied DeepSeek web request (bearer token and cookies). The process creates `logs.txt` and `.session/` in that same folder.
+
+```
+bm
+```
+
+If there are no account folders, the process prints `No accounts found!` and exits. Details are in `docs/`.

package/docs/accounts.md

@@ -0,0 +1,37 @@
+# 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

@@ -0,0 +1,40 @@
+# 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 wasm file is separate. If `sha3_wasm_bg.wasm` is missing from the working directory, it is downloaded from DeepSeek's static file host and saved there. That download URL does not follow `DEEPSEEK_BASE_URL`.

package/docs/http.md

@@ -0,0 +1,171 @@
+# 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. |

package/docs/install.md

@@ -0,0 +1,71 @@
+# Install
+
+Requires Node.js 18 or newer.
+
+```
+npm install -g @mathew-macharia/black-mamba
+```
+
+The command is `bm`. Run it in the directory that holds your data. That working directory (`process.cwd()`) is where `bm` reads `accounts/`, `.env`, and `sha3_wasm_bg.wasm`.
+
+```
+<data-directory>/
+  .env                  optional
+  sha3_wasm_bg.wasm     created on first start if missing
+  accounts/
+    <name>/
+      api-key.txt
+      curl.txt
+```
+
+`<name>` is the account folder name. It is the name printed in the terminal lines below. One folder is one DeepSeek login. Every account folder must contain both files. See [accounts.md](accounts.md) for the other files the process creates, and [config.md](config.md) for `.env`.
+
+`accounts/<name>/api-key.txt` is one line: the bearer key your app sends as `Authorization: Bearer <key>`. The line is trimmed. An empty file, or the same key in two account folders, stops startup.
+
+`accounts/<name>/curl.txt` is a Chrome DevTools copy of a `chat.deepseek.com` request: "Copy as cURL", "Copy as PowerShell", or a `fetch()` snippet. It must contain an `Authorization: Bearer <deepseek-bearer>` header or a `Cookie` header (or both). A placeholder shape:
+
+```
+curl "<deepseek-url>" -H "authorization: Bearer <deepseek-bearer>" -H "cookie: <cookie>"
+```
+
+Do not commit `accounts/` or `.env`.
+
+From the data directory:
+
+```
+bm
+```
+
+If `sha3_wasm_bg.wasm` is missing from that directory, startup downloads it and saves it there. The terminal shows two `[WASM]` lines: one when the download starts, and one when the file is saved.
+
+When the server is up, stdout has:
+
+```
+[Server] 🚀 Black Mamba listening on http://localhost:3000
+```
+
+The port is `PORT` (default 3000). Each account then prints one line. Stdout on success:
+
+```
+[Server] <name> logged in successfully
+```
+
+Stderr when the DeepSeek check failed:
+
+```
+[Server] <name> log in failed
+```
+
+The failure reason is appended to `accounts/<name>/logs.txt`, not to that terminal line.
+
+If a login that had succeeded later fails (the 30-minute check, or a DeepSeek auth error on a request), stderr prints:
+
+```
+[Server] <name> logged out
+```
+
+The reason is written to that account's `logs.txt` before the terminal line.
+
+If `accounts/` is missing or has no account folders, stderr is `No accounts found!` and the process exits with status 1. A missing `api-key.txt` or `curl.txt`, or a `curl.txt` that has neither a bearer token nor a cookie, prints `[Startup] Fatal error:` and exits with status 1.
+
+`SIGINT` and `SIGTERM` stop the process. The terminal prints `Received <signal>. Shutting down gracefully...` and the process exits with status 0.

package/docs/mapping.md

@@ -0,0 +1,11 @@
+# Mapping
+
+`stateless_seed`: A request with no `x-session-id` sends the full history into a new DeepSeek chat and records nothing.
+
+`root_seed`: A sessioned request with no stored parent node (first turn, unknown session, or unknown parent entry) sends the full history into a new DeepSeek chat and records the node.
+
+`delta`: The parent node exists and this request's history is that node's context plus its reply plus new messages, so only those new messages are sent on the stored DeepSeek chat and parent message.
+
+`reseed_context_diverged`: The parent node exists, but the history no longer extends it (shorter context, a changed prefix, a missing or edited assistant reply, or a compaction summary), so the full history is sent into a new DeepSeek chat.
+
+`reseed_upstream_rejected`: DeepSeek rejected the chat or parent message a `delta` turn referenced, so the full history is sent into a new DeepSeek chat and that result is the one returned.

package/docs/overview.md

@@ -0,0 +1,25 @@
+# Overview
+
+Black Mamba is an HTTP server. It accepts OpenAI-style chat completion requests and sends each turn to DeepSeek web chat. A client chooses an account with `Authorization: Bearer <key>`, where `<key>` is the text in that account's `api-key.txt`.
+
+The process keeps a local map from Pi session entries to DeepSeek chat ids and message ids. A later turn on the same branch continues that DeepSeek chat and sends only the new messages. A request with no `x-session-id` is stateless: the full history goes to a new DeepSeek chat and nothing is stored.
+
+Credentials come from `accounts/<name>/curl.txt` (DeepSeek bearer token and cookies). They stay in memory. `Set-Cookie` on DeepSeek responses updates the cookie jar. The files are not rewritten.
+
+At startup each account is checked with `GET <DEEPSEEK_BASE_URL>/api/v0/users/current`. A verified account is checked again every 30 minutes.
+
+## Request path
+
+1. The app sends `POST /v1/chat/completions` with the account bearer key and a JSON body whose `messages` array is the conversation so far.
+2. The key selects the account. The body is validated. If `x-session-id` is set, `x-entry-id` is required, and the session graph under `accounts/<name>/.session/` is loaded.
+3. The planner chooses one strategy and renders a single text prompt. A seed strategy sends the full history. `delta` sends only the messages after the stored parent reply. See [mapping.md](mapping.md).
+4. The account waits, when a previous turn has just finished, until the gap since that finish is a random time between `MIN_TURN_DELAY_MS` and `MAX_TURN_DELAY_MS`. The first turn of a process does not wait.
+5. If the plan has no DeepSeek chat id, Black Mamba creates one with `POST <DEEPSEEK_BASE_URL>/api/v0/chat_session/create`.
+6. It requests a proof-of-work challenge from `POST <DEEPSEEK_BASE_URL>/api/v0/chat/create_pow_challenge`, solves it with `sha3_wasm_bg.wasm`, and posts the prompt to `POST <DEEPSEEK_BASE_URL>/api/v0/chat/completion`. The JSON body includes the chat id, the parent message id (`null` for a new chat), `thinking_enabled`, and `search_enabled`. The proof-of-work answer is the `x-ds-pow-response` header.
+7. DeepSeek replies with a server-sent event stream. Black Mamba reads the reply text, any thinking text, `response_message_id`, and the change in accumulated token usage. Citation markers of the form `[reference:N]` and `[citation:N]` are removed from the text.
+8. If the request included `tools`, DSML tool-call blocks in the reply are converted to OpenAI `tool_calls` and removed from the assistant text. Image parts in the request are not forwarded; they are replaced with the text `[image omitted: Black Mamba forwards text only]`.
+9. For a request that carried `x-session-id`, the Pi entry id, the DeepSeek chat id, the DeepSeek message id, and a fingerprint of the context are written under `accounts/<name>/.session/`. A stateless request is not written.
+10. The app receives one JSON chat completion, or an SSE stream when `stream` is true. The response header `x-black-mamba-strategy` names the strategy that was used.
+11. If DeepSeek rejects the stored chat or parent message on a `delta` turn, Black Mamba opens a new chat, sends the full history (`reseed_upstream_rejected`), and answers from that second stream. If that second call fails, or if any other upstream call fails, the error is returned to the app. Upstream failures use HTTP 502.
+
+If the app closes the connection before the response is finished, the DeepSeek request is aborted and the turn is not recorded.

package/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Black Mamba — OpenAI-compatible proxy that maps pi's session tree onto DeepSeek web chat precisely.
+// This file only wires the modules together; see src/ for the implementation.
+
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { findAccount, listAccountDirs, loadAccounts } from "./src/accounts.js";
+import { CONFIG } from "./src/config.js";
+import { createLogger } from "./src/logger.js";
+import { createPowSolver, loadWasm } from "./src/deepseek/pow.js";
+import { createRequestHandler } from "./src/server/http.js";
+import { createSanitizer } from "./src/utils/sanitize.js";
+
+export function createAccountsApp({ slots, logger = createLogger("Server") }) {
+  const sanitize = createSanitizer(() => slots.flatMap((slot) => [slot.apiKey, ...slot.auth.secrets()]));
+  const handleRequest = createRequestHandler({
+    resolveAccount: (authorization) => findAccount(slots, authorization),
+    sanitize,
+    logger,
+  });
+  return { slots, handleRequest, sanitize, log: logger };
+}
+
+function stopApp(app) {
+  for (const slot of app.slots) {
+    slot.graph.stopPeriodicPrune();
+    slot.stopHealthMonitor();
+  }
+}
+
+async function main() {
+  let app;
+  try {
+    const accountNames = await listAccountDirs();
+    if (accountNames.length === 0) {
+      console.error("No accounts found!");
+      process.exit(1);
+    }
+
+    const log = createLogger("Server");
+    const wasm = await loadWasm({ logger: createLogger("WASM") });
+    const slots = await loadAccounts({ powSolver: createPowSolver(wasm), onLoggedOut: (name) => log.error(`${name} logged out`) });
+    app = createAccountsApp({ slots, logger: log });
+    for (const slot of slots) {
+      slot.graph.startPeriodicPrune();
+      slot.startHealthMonitor();
+    }
+
+    const server = http.createServer((req, res) => {
+      app.handleRequest(req, res);
+    });
+    server.listen(CONFIG.port, () => {
+      app.log.info(`🚀 Black Mamba listening on http://localhost:${CONFIG.port}`);
+      for (const slot of slots) {
+        if (slot.auth.verified) app.log.info(`${slot.name} logged in successfully`);
+        else app.log.error(`${slot.name} log in failed`);
+      }
+    });
+
+    const shutdown = (signal) => {
+      app.log.info(`Received ${signal}. Shutting down gracefully...`);
+      stopApp(app);
+      server.close(() => process.exit(0));
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+  } catch (err) {
+    console.error("[Startup] Fatal error:", app ? app.sanitize(err) : err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+
+const isMainModule = Boolean(process.argv[1]) && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMainModule) main();

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@mathew-macharia/black-mamba",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "OpenAI-compatible proxy that maps chat sessions onto DeepSeek web chat",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "bm": "index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "docs",
+    ".env.example",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test --test-concurrency=1 \"test/**/*.test.js\""
+  },
+  "dependencies": {
+    "dotenv": "^16.4.7"
+  }
+}

package/src/accounts.js

@@ -0,0 +1,107 @@
+// One folder per DeepSeek login: app key, cURL, log file, and session store.
+
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+
+import { CONFIG } from "./config.js";
+import { createDeepSeekClient } from "./deepseek/client.js";
+import { DeepSeekAuth } from "./deepseek/auth.js";
+import { parseCurlCommand } from "./deepseek/curl-parser.js";
+import { createLogger, createFileSink } from "./logger.js";
+import { createCompletionHandler } from "./server/completions.js";
+import { createPacer } from "./server/pacing.js";
+import { validateApiKey } from "./server/http.js";
+import { SessionGraph } from "./session/graph.js";
+import { createSanitizer } from "./utils/sanitize.js";
+
+function accountsDir(rootDir) {
+  return path.join(rootDir, "accounts");
+}
+
+export async function listAccountDirs(rootDir = CONFIG.rootDir) {
+  const dir = accountsDir(rootDir);
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+
+export function findAccount(slots, authorizationHeader) {
+  const req = { headers: { authorization: authorizationHeader } };
+  return slots.find((slot) => validateApiKey(req, slot.apiKey)) ?? null;
+}
+
+export async function loadAccounts({ rootDir = CONFIG.rootDir, powSolver, fetchImpl = fetch, minDelayMs, maxDelayMs, onLoggedOut = () => {} } = {}) {
+  const names = await listAccountDirs(rootDir);
+  if (names.length === 0) return [];
+
+  const specs = [];
+  const seen = new Map();
+  for (const name of names) {
+    const dir = path.join(accountsDir(rootDir), name);
+    const apiKey = (await readFile(path.join(dir, "api-key.txt"), "utf8")).trim();
+    const curl = await readFile(path.join(dir, "curl.txt"), "utf8");
+    if (!apiKey) throw new Error(`accounts/${name}/api-key.txt is empty`);
+    if (seen.has(apiKey)) throw new Error(`Duplicate api key in accounts/${seen.get(apiKey)} and accounts/${name}`);
+    seen.set(apiKey, name);
+    let parsed;
+    try {
+      parsed = parseCurlCommand(curl);
+    } catch (err) {
+      throw new Error(`accounts/${name}/curl.txt: ${err.message}`);
+    }
+    specs.push({ name, dir, apiKey, parsed });
+  }
+
+  const slots = [];
+  for (const spec of specs) {
+    const logger = createLogger(spec.name, { sink: createFileSink(path.join(spec.dir, "logs.txt")) });
+    const auth = new DeepSeekAuth();
+    auth.applyParsedSession(spec.parsed);
+    const sanitize = createSanitizer(() => [spec.apiKey, ...auth.secrets()]);
+    const graph = new SessionGraph({ sessionsDir: path.join(spec.dir, ".session"), logger });
+    await graph.init();
+    const pacer = createPacer({ logger, minDelayMs, maxDelayMs });
+    let connected = false;
+    const noteDisconnect = (reason) => {
+      logger.error(sanitize(reason));
+      if (!connected) return;
+      connected = false;
+      onLoggedOut(spec.name);
+    };
+    const deepseek = createDeepSeekClient({ auth, powSolver, fetchImpl, onAuthFailure: noteDisconnect });
+    const handleChatCompletions = createCompletionHandler({ deepseek, graph, pacer, logger });
+
+    let healthTimer = null;
+    const stopHealthMonitor = () => {
+      if (healthTimer) clearInterval(healthTimer);
+      healthTimer = null;
+    };
+    const startHealthMonitor = () => {
+      stopHealthMonitor();
+      healthTimer = setInterval(async () => {
+        if (!auth.verified) return;
+        try {
+          await auth.verify(fetchImpl);
+          const summary = auth.statusSummary();
+          const expiry = summary.next_due_expiry ? `${summary.next_due_expiry.cookie} due in ${summary.next_due_expiry.remaining}` : "active";
+          logger.info(`Health check OK (age: ${summary.session_age}, ${expiry})`);
+        } catch (err) {
+          noteDisconnect(err);
+        }
+      }, CONFIG.deepseek.healthCheckIntervalMs);
+      healthTimer.unref?.();
+    };
+
+    try {
+      await auth.verify(fetchImpl);
+      connected = true;
+      logger.info("DeepSeek login verified");
+    } catch (err) {
+      logger.error(sanitize(err));
+    }
+
+    slots.push(Object.freeze({ name: spec.name, apiKey: spec.apiKey, auth, graph, logger, handleChatCompletions, startHealthMonitor, stopHealthMonitor }));
+  }
+  return slots;
+}