@mathew-macharia/black-mamba 1.0.3 → 1.0.4

package/src/session/graph.js

@@ -1,182 +0,0 @@
-// Session graph: the mapping between pi's session tree and DeepSeek's chat trees.
-//
-// One Session per pi session id. One Node per LLM request pi made, keyed by the pi entry id at which the
-// request was made (x-entry-id). Each node records which DeepSeek chat session and message it produced and a
-// fingerprint of the context that produced it. DeepSeek message ids are never used as keys because they
-// restart in every DeepSeek chat session.
-
-import { CONFIG } from "../config.js";
-import { createLogger } from "../logger.js";
-import { SESSION_SCHEMA_VERSION, SessionStore } from "./store.js";
-
-/**
- * @typedef {object} Node
- * @property {string} piEntryId                 pi entry id at which the request was made
- * @property {string|null} piParentEntryId      pi entry id of the node this request attached to (null for seeds)
- * @property {string} strategy                  how the node was created (root_seed | delta | reseed_* ...)
- * @property {string|null} reason
- * @property {{ sessionId: string, messageId: number|string, parentMessageId: number|string|null }} deepseek
- * @property {{ messageCount: number, systemHash: string, prefixHash: string, assistant: { textHash: string, toolCalls: {name:string, argsHash:string}[] } }} context
- * @property {{ turnTokens: number, cachedTokens: number }} usage
- * @property {number} createdAt
- */
-
-export class SessionGraph {
-  constructor({ sessionsDir = CONFIG.sessions.dir, ttlMs = CONFIG.sessions.ttlMs, maxEntries = CONFIG.sessions.maxEntries, logger = createLogger("SessionGraph") } = {}) {
-    this.logger = logger;
-    this.ttlMs = ttlMs;
-    this.maxEntries = maxEntries;
-    this.store = new SessionStore({ dir: sessionsDir, ttlMs, logger });
-    this.sessions = new Map(); // piSessionId -> Session
-    this.cleanupTimer = null;
-  }
-
-  async init() {
-    await this.store.init();
-    await this.pruneExpired();
-  }
-
-  async getSession(piSessionId) {
-    if (!piSessionId) return null;
-    const key = String(piSessionId);
-    let session = this.sessions.get(key);
-    if (!session) {
-      session = await this.store.read(key);
-      if (session) this.sessions.set(key, session);
-    }
-    if (session) session.lastAccessedAt = Date.now();
-    return session ?? null;
-  }
-
-  async createSession(piSessionId) {
-    const key = String(piSessionId);
-    if (!key) throw new Error("piSessionId is required");
-    const existing = await this.getSession(key);
-    if (existing) return existing;
-
-    const now = Date.now();
-    const session = {
-      schemaVersion: SESSION_SCHEMA_VERSION,
-      piSessionId: key,
-      createdAt: now,
-      lastAccessedAt: now,
-      forkedFrom: null,
-      nodes: {},
-    };
-    this.sessions.set(key, session);
-    await this.store.write(key, session);
-    return session;
-  }
-
-  getNode(session, piEntryId) {
-    if (!session || piEntryId === null || piEntryId === undefined) return null;
-    return session.nodes[String(piEntryId)] ?? null;
-  }
-
-  nodeCount(session) {
-    return session ? Object.keys(session.nodes).length : 0;
-  }
-
-  /** Records (or replaces) the node for a pi entry id and persists the session. */
-  async putNode(session, node) {
-    if (!node?.piEntryId) throw new Error("node.piEntryId is required");
-    const key = String(node.piEntryId);
-    if (session.nodes[key]) {
-      this.logger.warn(`Node ${key} in session ${session.piSessionId} already existed and was replaced (pi re-used a leaf entry id).`);
-    }
-    session.nodes[key] = node;
-    session.lastAccessedAt = Date.now();
-    await this.store.write(session.piSessionId, session);
-    return node;
-  }
-
-  /** Copies every node of `source` into `target` (used when pi forks a session; entry ids are preserved by pi). */
-  async adoptNodes(target, source) {
-    for (const [key, node] of Object.entries(source.nodes)) {
-      if (!target.nodes[key]) target.nodes[key] = node;
-    }
-    target.forkedFrom = { piSessionId: source.piSessionId, adoptedAt: Date.now() };
-    target.lastAccessedAt = Date.now();
-    await this.store.write(target.piSessionId, target);
-  }
-
-  /**
-   * Tokens DeepSeek already holds in context when attaching to `node`: the node's own turn plus every
-   * ancestor turn in the same DeepSeek chat session.
-   */
-  branchCachedTokens(session, node) {
-    let total = 0;
-    const visited = new Set();
-    let current = node;
-    while (current && !visited.has(current.piEntryId)) {
-      visited.add(current.piEntryId);
-      if (current.deepseek.sessionId !== node.deepseek.sessionId) break;
-      total += current.usage?.turnTokens || 0;
-      current = current.piParentEntryId ? this.getNode(session, current.piParentEntryId) : null;
-    }
-    return total;
-  }
-
-  async deleteSession(piSessionId) {
-    const key = String(piSessionId);
-    const existed = this.sessions.delete(key);
-    await this.store.remove(key);
-    return existed;
-  }
-
-  async pruneExpired(now = Date.now()) {
-    for (const [key, session] of this.sessions.entries()) {
-      if (now - (session.lastAccessedAt || 0) > this.ttlMs) {
-        this.sessions.delete(key);
-        await this.store.remove(key);
-      }
-    }
-    await this.store.pruneOlderThan(now);
-
-    if (this.sessions.size > this.maxEntries) {
-      const sorted = Array.from(this.sessions.entries()).sort(([, a], [, b]) => (a.lastAccessedAt || 0) - (b.lastAccessedAt || 0));
-      for (const [key] of sorted.slice(0, this.sessions.size - this.maxEntries)) {
-        // Evict from memory only; the file stays until its TTL so the session can be reloaded.
-        this.sessions.delete(key);
-      }
-    }
-  }
-
-  startPeriodicPrune(intervalMs = 60 * 60 * 1000) {
-    this.stopPeriodicPrune();
-    this.cleanupTimer = setInterval(() => {
-      this.pruneExpired().catch((err) => this.logger.warn("Periodic prune error:", err.message));
-    }, intervalMs);
-    this.cleanupTimer.unref?.();
-  }
-
-  stopPeriodicPrune() {
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = null;
-    }
-  }
-
-  /** Read-only view for the inspection endpoint. */
-  describeSession(session) {
-    return {
-      piSessionId: session.piSessionId,
-      createdAt: new Date(session.createdAt).toISOString(),
-      lastAccessedAt: new Date(session.lastAccessedAt).toISOString(),
-      forkedFrom: session.forkedFrom,
-      nodeCount: this.nodeCount(session),
-      nodes: Object.values(session.nodes)
-        .sort((a, b) => a.createdAt - b.createdAt)
-        .map((n) => ({
-          piEntryId: n.piEntryId,
-          piParentEntryId: n.piParentEntryId,
-          strategy: n.strategy,
-          reason: n.reason,
-          deepseek: n.deepseek,
-          messageCount: n.context.messageCount,
-          turnTokens: n.usage.turnTokens,
-          createdAt: new Date(n.createdAt).toISOString(),
-        })),
-    };
-  }
-}

package/src/session/planner.js

@@ -1,177 +0,0 @@
-// Mapping planner: decides, for one pi request, exactly which DeepSeek chat/parent to attach to and what text to
-// send. Every outcome is a named strategy with a reason. There is no implicit fallback: either the parent node
-// exists and the context pi sent verifiably extends it (-> delta), or DeepSeek has no matching context and a
-// fresh chat is seeded with the full history (-> seed). Both outcomes reproduce pi's context exactly.
-//
-// Strategies
-//   stateless_seed           no x-session-id: full history into a throwaway DeepSeek chat, nothing recorded
-//   root_seed                stateful request with no usable parent node (first turn, unknown session, /tree to root)
-//   delta                    parent node found and verified: send only the messages DeepSeek has not seen
-//   reseed_context_diverged  parent node found but pi's context no longer extends it (compaction, context_edit, ...)
-//   reseed_upstream_rejected DeepSeek rejected the stored chat/parent (chat deleted or expired on their side)
-
-import { BadRequestError, HttpError } from "../errors.js";
-import {
-  assistantFingerprintFromMessage,
-  contentToText,
-  fingerprintsEqual,
-  hasLeadingSystem,
-  isCompactionSummaryMessage,
-  normalizeRole,
-  prefixHash,
-  systemHash,
-} from "../pi/messages.js";
-import { renderDeltaPrompt, renderSeedPrompt, renderSystemPrompt } from "../pi/prompt.js";
-
-export const STRATEGY = Object.freeze({
-  STATELESS_SEED: "stateless_seed",
-  ROOT_SEED: "root_seed",
-  DELTA: "delta",
-  RESEED_DIVERGED: "reseed_context_diverged",
-  RESEED_UPSTREAM: "reseed_upstream_rejected",
-});
-
-function contextFingerprint(messages) {
-  return { messageCount: messages.length, systemHash: systemHash(messages), prefixHash: prefixHash(messages) };
-}
-
-/**
- * Checks that `messages` is exactly "the parent's request context + the parent's reply + new messages".
- * @returns {{ ok: true } | { ok: false, reason: string, details: object }}
- */
-export function verifyContextExtendsNode(messages, node) {
-  const parentCount = node.context.messageCount;
-  const firstBody = hasLeadingSystem(messages) ? 1 : 0;
-  // pi replaces the history with a summary message on compaction; the context then no longer extends any earlier node.
-  const startsWithCompaction = messages.length > firstBody && isCompactionSummaryMessage(messages[firstBody]);
-
-  if (messages.length <= parentCount) {
-    return {
-      ok: false,
-      reason: startsWithCompaction ? "compaction" : "context_shorter_than_parent",
-      details: { messageCount: messages.length, parentMessageCount: parentCount },
-    };
-  }
-  const expectedPrefix = prefixHash(messages, parentCount);
-  if (expectedPrefix !== node.context.prefixHash) {
-    return {
-      ok: false,
-      reason: startsWithCompaction ? "compaction" : "context_prefix_changed",
-      details: { parentMessageCount: parentCount, expectedPrefixHash: node.context.prefixHash, actualPrefixHash: expectedPrefix },
-    };
-  }
-  const reply = messages[parentCount];
-  if (normalizeRole(reply.role) !== "assistant") {
-    return { ok: false, reason: "parent_reply_missing", details: { indexOfReply: parentCount, roleFound: normalizeRole(reply.role) } };
-  }
-  if (!fingerprintsEqual(assistantFingerprintFromMessage(reply), node.context.assistant)) {
-    return { ok: false, reason: "parent_reply_modified", details: { indexOfReply: parentCount } };
-  }
-  return { ok: true };
-}
-
-function seedPlan({ request, strategy, reason, details = null, session = null, parentNode = null }) {
-  const { messages, tools, routing } = request;
-  return Object.freeze({
-    strategy,
-    reason,
-    details,
-    session,
-    parentNode,
-    prompt: renderSeedPrompt(messages, tools),
-    deepseek: { sessionId: null, parentMessageId: null }, // null sessionId => the handler creates a fresh DeepSeek chat
-    cachedTokens: 0,
-    deltaMessageCount: messages.length,
-    record: routing
-      ? { piEntryId: routing.entryId, piParentEntryId: routing.parentEntryId, context: contextFingerprint(messages) }
-      : null,
-  });
-}
-
-/** Resolves the parent node, adopting a forked session's graph when pi tells us where it was forked from. */
-async function resolveParent({ graph, routing, logger }) {
-  let session = await graph.getSession(routing.sessionId);
-  let parentNode = null;
-  let adoptedFrom = null;
-
-  if (routing.parentEntryId) {
-    parentNode = graph.getNode(session, routing.parentEntryId);
-
-    if (!parentNode && routing.parentSessionId && routing.parentSessionId !== routing.sessionId) {
-      const parentSession = await graph.getSession(routing.parentSessionId);
-      const candidate = graph.getNode(parentSession, routing.parentEntryId);
-      if (candidate) {
-        session = session ?? (await graph.createSession(routing.sessionId));
-        await graph.adoptNodes(session, parentSession);
-        parentNode = graph.getNode(session, routing.parentEntryId);
-        adoptedFrom = routing.parentSessionId;
-        logger.info(`Fork detected: session ${routing.sessionId} adopted ${graph.nodeCount(parentSession)} node(s) from ${routing.parentSessionId}.`);
-      }
-    }
-  }
-
-  if (!session) session = await graph.createSession(routing.sessionId);
-  return { session, parentNode, adoptedFrom };
-}
-
-/**
- * @param {{ request: ReturnType<import("../pi/request.js").parseChatRequest>, graph: import("./graph.js").SessionGraph, logger: object }} deps
- */
-export async function planCompletion({ request, graph, logger }) {
-  const { messages, tools, routing } = request;
-
-  if (!routing) {
-    return seedPlan({ request, strategy: STRATEGY.STATELESS_SEED, reason: "no_session_routing" });
-  }
-
-  const { session, parentNode, adoptedFrom } = await resolveParent({ graph, routing, logger });
-
-  if (!parentNode) {
-    let reason = "no_parent_entry";
-    if (routing.parentEntryId) reason = graph.nodeCount(session) === 0 ? "session_unknown" : "parent_entry_unknown";
-    return seedPlan({ request, strategy: STRATEGY.ROOT_SEED, reason, session, details: { parentEntryId: routing.parentEntryId } });
-  }
-
-  const verification = verifyContextExtendsNode(messages, parentNode);
-  if (!verification.ok) {
-    return seedPlan({
-      request,
-      strategy: STRATEGY.RESEED_DIVERGED,
-      reason: verification.reason,
-      details: { ...verification.details, parentEntryId: parentNode.piEntryId },
-      session,
-      parentNode,
-    });
-  }
-
-  const deltaMessages = messages.slice(parentNode.context.messageCount + 1);
-  if (deltaMessages.length === 0) {
-    throw new HttpError(409, "Request contains no messages after the parent node's reply; nothing to send to DeepSeek.", {
-      code: "no_new_messages",
-      details: { parentEntryId: parentNode.piEntryId, messageCount: messages.length },
-    });
-  }
-
-  const fingerprint = contextFingerprint(messages);
-  const systemChanged = fingerprint.systemHash !== parentNode.context.systemHash;
-  const systemUpdate = systemChanged ? renderSystemPrompt(hasLeadingSystem(messages) ? contentToText(messages[0].content) : "", tools) : null;
-
-  return Object.freeze({
-    strategy: STRATEGY.DELTA,
-    reason: adoptedFrom ? `forked_from:${adoptedFrom}` : systemChanged ? "system_prompt_changed" : null,
-    details: null,
-    session,
-    parentNode,
-    prompt: renderDeltaPrompt(deltaMessages, tools, { systemUpdate }),
-    deepseek: { sessionId: parentNode.deepseek.sessionId, parentMessageId: parentNode.deepseek.messageId },
-    cachedTokens: graph.branchCachedTokens(session, parentNode),
-    deltaMessageCount: deltaMessages.length,
-    record: { piEntryId: routing.entryId, piParentEntryId: parentNode.piEntryId, context: fingerprint },
-  });
-}
-
-/** Explicit re-seed after DeepSeek rejected the chat/parent a delta plan referenced. */
-export function reseedAfterUpstreamRejection(request, plan, details) {
-  if (!plan.session) throw new BadRequestError("Cannot re-seed a stateless request", "reseed_without_session");
-  return seedPlan({ request, strategy: STRATEGY.RESEED_UPSTREAM, reason: "upstream_context_rejected", details, session: plan.session, parentNode: plan.parentNode });
-}

package/src/session/store.js

@@ -1,100 +0,0 @@
-// Disk persistence for session graphs: one JSON file per pi session, atomic writes, TTL pruning.
-
-import crypto from "node:crypto";
-import path from "node:path";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, rename, stat as statFs, unlink, writeFile } from "node:fs/promises";
-
-export const SESSION_SCHEMA_VERSION = 2;
-
-export function sanitizeSessionFilename(sessionId) {
-  const safePrefix = String(sessionId).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 48);
-  const hash = crypto.createHash("sha256").update(String(sessionId)).digest("hex").slice(0, 16);
-  return `${safePrefix}_${hash}.json`;
-}
-
-export class SessionStore {
-  constructor({ dir, ttlMs, logger }) {
-    this.dir = dir;
-    this.ttlMs = ttlMs;
-    this.logger = logger;
-  }
-
-  filePath(sessionId) {
-    return path.join(this.dir, sanitizeSessionFilename(sessionId));
-  }
-
-  async init() {
-    if (!existsSync(this.dir)) await mkdir(this.dir, { recursive: true });
-  }
-
-  /**
-   * Returns the stored session or null. Expired files are removed. Files written by the pre-v2 schema are
-   * ignored (their node keys mixed pi and DeepSeek ids and cannot be trusted); they are reported once and
-   * left to TTL pruning.
-   */
-  async read(sessionId, now = Date.now()) {
-    const filePath = this.filePath(sessionId);
-    if (!existsSync(filePath)) return null;
-
-    let parsed;
-    try {
-      parsed = JSON.parse(await readFile(filePath, "utf8"));
-    } catch (err) {
-      this.logger.warn(`Session file ${path.basename(filePath)} is unreadable (${err.message}); treating session as unknown.`);
-      return null;
-    }
-    if (!parsed || typeof parsed !== "object") return null;
-
-    if (parsed.schemaVersion !== SESSION_SCHEMA_VERSION) {
-      this.logger.warn(
-        `Session file ${path.basename(filePath)} uses schema ${parsed.schemaVersion ?? 1} (expected ${SESSION_SCHEMA_VERSION}); ignoring it. The branch will be re-seeded.`
-      );
-      return null;
-    }
-    if (now - (parsed.lastAccessedAt || parsed.createdAt || 0) > this.ttlMs) {
-      await unlink(filePath).catch(() => {});
-      return null;
-    }
-    return parsed;
-  }
-
-  async write(sessionId, session) {
-    await this.init();
-    const filePath = this.filePath(sessionId);
-    const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
-    const json = JSON.stringify(session, null, 2);
-    await writeFile(tmpPath, json, "utf8");
-    try {
-      await rename(tmpPath, filePath);
-    } catch (err) {
-      // Windows can refuse to replace a file that another process has open; write in place instead.
-      this.logger.warn(`Atomic rename failed for ${path.basename(filePath)} (${err.message}); writing in place.`);
-      await writeFile(filePath, json, "utf8");
-      await unlink(tmpPath).catch(() => {});
-    }
-  }
-
-  async remove(sessionId) {
-    await unlink(this.filePath(sessionId)).catch(() => {});
-  }
-
-  async pruneOlderThan(now = Date.now()) {
-    if (!existsSync(this.dir)) return 0;
-    let removed = 0;
-    for (const file of await readdir(this.dir)) {
-      if (!file.endsWith(".json")) continue;
-      const filePath = path.join(this.dir, file);
-      try {
-        const info = await statFs(filePath);
-        if (now - info.mtimeMs > this.ttlMs) {
-          await unlink(filePath);
-          removed++;
-        }
-      } catch {
-        // file vanished concurrently
-      }
-    }
-    return removed;
-  }
-}

package/src/utils/hash.js

@@ -1,27 +0,0 @@
-import crypto from "node:crypto";
-
-export function sha256Hex(input) {
-  return crypto.createHash("sha256").update(input, "utf8").digest("hex");
-}
-
-/** Short (16 hex chars) digest used for fingerprints that are compared, never used as a key. */
-export function shortHash(input) {
-  return sha256Hex(input).slice(0, 16);
-}
-
-/** Deterministic JSON: object keys sorted recursively so semantically equal values hash equally. */
-export function canonicalJson(value) {
-  return JSON.stringify(sortKeys(value));
-}
-
-function sortKeys(value) {
-  if (Array.isArray(value)) return value.map(sortKeys);
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const key of Object.keys(value).sort()) {
-      out[key] = sortKeys(value[key]);
-    }
-    return out;
-  }
-  return value;
-}