dsh-context-mode 0.1.3 → 0.2.0

package/vendor/context-mode/src/session/index.ts

@@ -0,0 +1,130 @@
+/**
+ * Public session ingestion API for external host integrations.
+ *
+ * Host adapters keep their own durable session log and use this recorder to
+ * project selected events into context-mode's analytics database. The recorder
+ * owns database lifecycle and never exposes the SQLite implementation.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { EventPriority, type SessionEvent } from "../types.js";
+import { resolveSessionDbPath, SessionDB, type EventBytes } from "./db.js";
+import type { AttributionSource } from "./project-attribution.js";
+
+/** One event supplied by an external host adapter. */
+export interface SessionRecorderEvent {
+  /** Stable event type used by timeline and resume queries. */
+  readonly type: string;
+  /** Event category used by analytics and priority filters. */
+  readonly category: string;
+  /** Serialized event payload. */
+  readonly data: string;
+  /** Retention priority; defaults to {@link EventPriority.NORMAL}. */
+  readonly priority?: number;
+  /** Bytes kept out of the model context for this event. */
+  readonly bytesAvoided?: number;
+  /** Bytes returned to the model for this event. */
+  readonly bytesReturned?: number;
+}
+
+/** Configuration for one project-scoped recorder. */
+export interface SessionRecorderOptions {
+  /** Absolute or relative project directory used for DB sharding and attribution. */
+  readonly projectDir: string;
+  /** Context-mode storage root; the recorder uses its `sessions` child directory. */
+  readonly storageDir: string;
+  /** Attribution label stored on projected events. */
+  readonly source?: AttributionSource;
+  /** Attribution confidence stored on projected events. */
+  readonly confidence?: number;
+}
+
+/** Stable host-facing session projection API. */
+export interface SessionRecorder {
+  /** Ensure a session metadata row exists before tool-side analytics arrive. */
+  ensureSession(sessionId: string): void;
+  /** Append one projected event to the session database. */
+  append(sessionId: string, event: SessionRecorderEvent, sourceHook?: string): void;
+  /** Append several projected events in one database transaction. */
+  appendBatch(sessionId: string, events: readonly SessionRecorderEvent[], sourceHook?: string): void;
+  /** Close the recorder's database connection. */
+  close(): void;
+}
+
+/**
+ * Open a project-scoped recorder for an external host integration.
+ *
+ * @param options - storage, attribution, and project settings.
+ * @returns an owned recorder; callers must invoke `close()` during teardown.
+ */
+export function createSessionRecorder(options: SessionRecorderOptions): SessionRecorder {
+  const projectDir = resolve(options.projectDir);
+  const storageDir = resolve(options.storageDir);
+  const sessionsDir = join(storageDir, "sessions");
+  mkdirSync(sessionsDir, { recursive: true });
+  const source: AttributionSource = options.source ?? "unknown";
+  const confidenceValue = options.confidence ?? 1;
+  const confidence = Number.isFinite(confidenceValue) ? Math.max(0, Math.min(1, confidenceValue)) : 1;
+  const dbPath = resolveSessionDbPath({
+    projectDir,
+    sessionsDir,
+  });
+  const db = new SessionDB({ dbPath });
+
+  const ensureSession = (sessionId: string): void => {
+    db.ensureSession(sessionId, projectDir);
+  };
+
+  const toDbEvent = (event: SessionRecorderEvent): Omit<SessionEvent, "data_hash"> & { data_hash?: string } => ({
+    type: event.type,
+    category: event.category,
+    data: event.data,
+    priority: event.priority ?? EventPriority.NORMAL,
+    project_dir: projectDir,
+    attribution_source: source,
+    attribution_confidence: confidence,
+  });
+
+  const append = (sessionId: string, event: SessionRecorderEvent, sourceHook = source): void => {
+    ensureSession(sessionId);
+    const bytes: EventBytes = {
+      bytesAvoided: event.bytesAvoided,
+      bytesReturned: event.bytesReturned,
+    };
+    db.insertEvent(sessionId, toDbEvent(event), sourceHook, {
+      projectDir,
+      source,
+      confidence,
+    }, bytes);
+  };
+
+  const appendBatch = (
+    sessionId: string,
+    events: readonly SessionRecorderEvent[],
+    sourceHook = source,
+  ): void => {
+    if (events.length === 0) return;
+    ensureSession(sessionId);
+    const bytes = events.map(event => ({
+      bytesAvoided: event.bytesAvoided,
+      bytesReturned: event.bytesReturned,
+    }));
+    db.bulkInsertEvents(
+      sessionId,
+      events.map(toDbEvent) as SessionEvent[],
+      sourceHook,
+      events.map(() => ({ projectDir, source, confidence })),
+      bytes,
+    );
+  };
+
+  return {
+    ensureSession,
+    append,
+    appendBatch,
+    close: () => db.close(),
+  };
+}
+
+export type { EventBytes } from "./db.js";

package/vendor/context-mode/src/session/model-prices.json

@@ -0,0 +1,429 @@
+{
+  "claude-opus-4-8": {
+    "input_per_mtok": 5,
+    "output_per_mtok": 25,
+    "cache_read_per_mtok": 0.5,
+    "cache_write_per_mtok": 6.25,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-opus-4-7": {
+    "input_per_mtok": 5,
+    "output_per_mtok": 25,
+    "cache_read_per_mtok": 0.5,
+    "cache_write_per_mtok": 6.25,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-opus-4-6": {
+    "input_per_mtok": 5,
+    "output_per_mtok": 25,
+    "cache_read_per_mtok": 0.5,
+    "cache_write_per_mtok": 6.25,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-opus-4-5": {
+    "input_per_mtok": 5,
+    "output_per_mtok": 25,
+    "cache_read_per_mtok": 0.5,
+    "cache_write_per_mtok": 6.25,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-sonnet-4-6": {
+    "input_per_mtok": 3,
+    "output_per_mtok": 15,
+    "cache_read_per_mtok": 0.3,
+    "cache_write_per_mtok": 3.75,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-sonnet-4-5": {
+    "input_per_mtok": 3,
+    "output_per_mtok": 15,
+    "cache_read_per_mtok": 0.3,
+    "cache_write_per_mtok": 3.75,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-haiku-4-5": {
+    "input_per_mtok": 1,
+    "output_per_mtok": 5,
+    "cache_read_per_mtok": 0.1,
+    "cache_write_per_mtok": 1.25,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-3-7-sonnet": {
+    "input_per_mtok": 3,
+    "output_per_mtok": 15,
+    "cache_read_per_mtok": 0.3,
+    "cache_write_per_mtok": 3.75,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "claude-3-5-haiku": {
+    "input_per_mtok": 0.8,
+    "output_per_mtok": 4,
+    "cache_read_per_mtok": 0.08,
+    "cache_write_per_mtok": 1,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "claude-fable-5": {
+    "input_per_mtok": 10,
+    "output_per_mtok": 50,
+    "cache_read_per_mtok": 1,
+    "cache_write_per_mtok": 12.5,
+    "source": "https://platform.claude.com/docs/en/about-claude/pricing"
+  },
+  "gpt-5": {
+    "input_per_mtok": 1.25,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": 0.125,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-5-mini": {
+    "input_per_mtok": 0.25,
+    "output_per_mtok": 2,
+    "cache_read_per_mtok": 0.025,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-5-nano": {
+    "input_per_mtok": 0.05,
+    "output_per_mtok": 0.4,
+    "cache_read_per_mtok": 0.005,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-5-codex": {
+    "input_per_mtok": 1.25,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": 0.125,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-4.1": {
+    "input_per_mtok": 2,
+    "output_per_mtok": 8,
+    "cache_read_per_mtok": 0.5,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-4.1-mini": {
+    "input_per_mtok": 0.4,
+    "output_per_mtok": 1.6,
+    "cache_read_per_mtok": 0.1,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-4.1-nano": {
+    "input_per_mtok": 0.1,
+    "output_per_mtok": 0.4,
+    "cache_read_per_mtok": 0.025,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-4o": {
+    "input_per_mtok": 2.5,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": 1.25,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gpt-4o-mini": {
+    "input_per_mtok": 0.15,
+    "output_per_mtok": 0.6,
+    "cache_read_per_mtok": 0.075,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "o3": {
+    "input_per_mtok": 2,
+    "output_per_mtok": 8,
+    "cache_read_per_mtok": 0.5,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "o4-mini": {
+    "input_per_mtok": 1.1,
+    "output_per_mtok": 4.4,
+    "cache_read_per_mtok": 0.275,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "o3-mini": {
+    "input_per_mtok": 1.1,
+    "output_per_mtok": 4.4,
+    "cache_read_per_mtok": 0.55,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "codex-mini-latest": {
+    "input_per_mtok": 1.5,
+    "output_per_mtok": 6,
+    "cache_read_per_mtok": 0.375,
+    "cache_write_per_mtok": null,
+    "source": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+  },
+  "gemini-2.5-pro": {
+    "input_per_mtok": 1.25,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": 0.125,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "gemini-2.5-flash": {
+    "input_per_mtok": 0.3,
+    "output_per_mtok": 2.5,
+    "cache_read_per_mtok": 0.03,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "gemini-2.5-flash-lite": {
+    "input_per_mtok": 0.1,
+    "output_per_mtok": 0.4,
+    "cache_read_per_mtok": 0.01,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "gemini-2.0-flash": {
+    "input_per_mtok": 0.1,
+    "output_per_mtok": 0.4,
+    "cache_read_per_mtok": 0.025,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "gemini-2.0-flash-lite": {
+    "input_per_mtok": 0.075,
+    "output_per_mtok": 0.3,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "gemini-3-pro-preview": {
+    "input_per_mtok": 2,
+    "output_per_mtok": 12,
+    "cache_read_per_mtok": 0.2,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "gemini-3-flash-preview": {
+    "input_per_mtok": 0.5,
+    "output_per_mtok": 3,
+    "cache_read_per_mtok": 0.05,
+    "cache_write_per_mtok": null,
+    "source": "https://ai.google.dev/gemini-api/docs/pricing"
+  },
+  "qwen3-coder": {
+    "input_per_mtok": 1,
+    "output_per_mtok": 5,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.alibabacloud.com/help/en/model-studio/models"
+  },
+  "qwen-max": {
+    "input_per_mtok": 1.6,
+    "output_per_mtok": 6.4,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.alibabacloud.com/help/en/model-studio/models"
+  },
+  "qwen-plus": {
+    "input_per_mtok": 0.4,
+    "output_per_mtok": 1.2,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.alibabacloud.com/help/en/model-studio/models"
+  },
+  "qwen-turbo": {
+    "input_per_mtok": 0.05,
+    "output_per_mtok": 0.2,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.alibabacloud.com/help/en/model-studio/models"
+  },
+  "qwen3-max": {
+    "input_per_mtok": 1.2,
+    "output_per_mtok": 6,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.alibabacloud.com/help/en/model-studio/models"
+  },
+  "kimi-k2": {
+    "input_per_mtok": 0.6,
+    "output_per_mtok": 2.5,
+    "cache_read_per_mtok": 0.15,
+    "cache_write_per_mtok": null,
+    "source": "https://platform.moonshot.ai/docs/pricing/chat"
+  },
+  "kimi-k2-turbo": {
+    "input_per_mtok": 1.15,
+    "output_per_mtok": 8,
+    "cache_read_per_mtok": 0.15,
+    "cache_write_per_mtok": null,
+    "source": "https://platform.moonshot.ai/docs/pricing/chat"
+  },
+  "moonshot-v1-8k": {
+    "input_per_mtok": 0.2,
+    "output_per_mtok": 2,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://platform.moonshot.ai/docs/pricing"
+  },
+  "moonshot-v1-32k": {
+    "input_per_mtok": 1,
+    "output_per_mtok": 3,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://platform.moonshot.ai/docs/pricing"
+  },
+  "moonshot-v1-128k": {
+    "input_per_mtok": 2,
+    "output_per_mtok": 5,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://platform.moonshot.ai/docs/pricing"
+  },
+  "deepseek-v3": {
+    "input_per_mtok": 0.27,
+    "output_per_mtok": 1.1,
+    "cache_read_per_mtok": 0.07,
+    "cache_write_per_mtok": 0,
+    "source": "https://api-docs.deepseek.com/quick_start/pricing"
+  },
+  "deepseek-r1": {
+    "input_per_mtok": 0.55,
+    "output_per_mtok": 2.19,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://api-docs.deepseek.com/quick_start/pricing"
+  },
+  "deepseek-chat": {
+    "input_per_mtok": 0.14,
+    "output_per_mtok": 0.28,
+    "cache_read_per_mtok": 0.0028,
+    "cache_write_per_mtok": null,
+    "source": "https://api-docs.deepseek.com/quick_start/pricing"
+  },
+  "deepseek-reasoner": {
+    "input_per_mtok": 0.14,
+    "output_per_mtok": 0.28,
+    "cache_read_per_mtok": 0.0028,
+    "cache_write_per_mtok": null,
+    "source": "https://api-docs.deepseek.com/quick_start/pricing"
+  },
+  "glm-4.6": {
+    "input_per_mtok": 0.6,
+    "output_per_mtok": 2.2,
+    "cache_read_per_mtok": 0.11,
+    "cache_write_per_mtok": null,
+    "source": "https://docs.z.ai/guides/overview/pricing"
+  },
+  "glm-4-air": {
+    "input_per_mtok": 0.2,
+    "output_per_mtok": 1.1,
+    "cache_read_per_mtok": 0.03,
+    "cache_write_per_mtok": null,
+    "source": "https://docs.z.ai/guides/overview/pricing"
+  },
+  "grok-4": {
+    "input_per_mtok": 3,
+    "output_per_mtok": 15,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://docs.x.ai/docs/pricing"
+  },
+  "grok-3": {
+    "input_per_mtok": 3,
+    "output_per_mtok": 15,
+    "cache_read_per_mtok": 0.75,
+    "cache_write_per_mtok": null,
+    "source": "https://docs.x.ai/docs/pricing"
+  },
+  "grok-code-fast-1": {
+    "input_per_mtok": 0.2,
+    "output_per_mtok": 1.5,
+    "cache_read_per_mtok": 0.02,
+    "cache_write_per_mtok": null,
+    "source": "https://docs.x.ai/docs/pricing"
+  },
+  "grok-2": {
+    "input_per_mtok": 2,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://docs.x.ai/docs/pricing"
+  },
+  "mistral-large-latest": {
+    "input_per_mtok": 0.5,
+    "output_per_mtok": 1.5,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://mistral.ai/pricing"
+  },
+  "codestral-latest": {
+    "input_per_mtok": 0.3,
+    "output_per_mtok": 0.9,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://mistral.ai/pricing"
+  },
+  "devstral": {
+    "input_per_mtok": 0.4,
+    "output_per_mtok": 2,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://mistral.ai/pricing"
+  },
+  "mistral-medium": {
+    "input_per_mtok": 0.4,
+    "output_per_mtok": 2,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://mistral.ai/pricing"
+  },
+  "llama-4-maverick": {
+    "input_per_mtok": 0.27,
+    "output_per_mtok": 0.85,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.together.ai/pricing"
+  },
+  "llama-4-scout": {
+    "input_per_mtok": 0.08,
+    "output_per_mtok": 0.3,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.together.ai/pricing"
+  },
+  "llama-3.3-70b": {
+    "input_per_mtok": 0.88,
+    "output_per_mtok": 0.88,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://www.together.ai/pricing"
+  },
+  "command-a": {
+    "input_per_mtok": 2.5,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://cohere.com/pricing"
+  },
+  "command-r-plus": {
+    "input_per_mtok": 2.5,
+    "output_per_mtok": 10,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://cohere.com/pricing"
+  },
+  "amazon-nova-pro": {
+    "input_per_mtok": 0.8,
+    "output_per_mtok": 3.2,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://aws.amazon.com/bedrock/pricing/"
+  },
+  "amazon-nova-lite": {
+    "input_per_mtok": 0.06,
+    "output_per_mtok": 0.24,
+    "cache_read_per_mtok": null,
+    "cache_write_per_mtok": null,
+    "source": "https://aws.amazon.com/bedrock/pricing/"
+  }
+}

package/vendor/context-mode/src/session/persist-tool-calls.ts

@@ -0,0 +1,128 @@
+/**
+ * persist-tool-calls — runtime glue between MCP server's in-memory
+ * `sessionStats` and the on-disk `tool_calls` SessionDB table.
+ *
+ * Why this module exists
+ * ──────────────────────
+ * Commit 4742160 (May 2 16:58) added the SessionDB write path so the
+ * statusline counters survived `npm update -g context-mode` and
+ * `claude --continue`. Commit b392c2f (May 2 21:43) — the concurrency
+ * refactor — silently dropped that wiring as collateral. Same-session
+ * `/ctx-upgrade` flips the statusline back to `0 calls / $0.00`
+ * because the new PID starts with an empty `sessionStats` and never
+ * looks at the table the old PID was writing to.
+ *
+ * This module re-introduces the write path AND adds the read-side
+ * restore that 4742160 never shipped — both pure helpers so the
+ * server.ts wiring is a one-liner and the unit tests don't need to
+ * boot the MCP server.
+ */
+
+import { existsSync } from "node:fs";
+import { SessionDB } from "./db.js";
+
+/**
+ * Shape returned by {@link restoreSessionStats}. Subset of the in-memory
+ * `sessionStats` object the MCP server keeps — only the fields that can
+ * be recovered from SessionDB.
+ */
+export interface RestoredSessionStats {
+  /** Per-tool call counts. */
+  calls: Record<string, number>;
+  /** Per-tool returned bytes. */
+  bytesReturned: Record<string, number>;
+  /**
+   * Epoch-ms for `session_meta.started_at` of the latest session, so the
+   * statusline `uptime_ms` reflects the original session start instead of
+   * resetting to `Date.now()` on every PID change.
+   */
+  sessionStart: number;
+}
+
+/**
+ * Increment the persistent tool-call counter for `toolName` under whatever
+ * session_id `session_meta` currently treats as the most recent. This is
+ * called from {@link trackResponse} on every tool response and must be
+ * cheap, non-throwing, and best-effort — a stats failure must never break
+ * the MCP tool call.
+ */
+export function persistToolCallCounter(
+  sessionDbPath: string,
+  toolName: string,
+  bytes: number,
+): void {
+  try {
+    if (!existsSync(sessionDbPath)) return;
+    const sdb = new SessionDB({ dbPath: sessionDbPath });
+    try {
+      const sid = sdb.getLatestSessionId();
+      if (!sid) return;
+      sdb.incrementToolCall(sid, toolName, bytes);
+    } finally {
+      sdb.close();
+    }
+  } catch {
+    // Best-effort: counter must never throw and break the parent tool call.
+  }
+}
+
+/**
+ * Read the latest session's tool-call totals back out of SessionDB so the
+ * MCP server can hydrate its in-memory `sessionStats` on startup. Returns
+ * `null` when the DB is missing or empty so the caller can keep the
+ * default zero-state without branching twice.
+ *
+ * Used during MCP server boot (BEFORE the heartbeat fires) so the
+ * statusline doesn't briefly flash `0 calls / $0.00` after upgrade.
+ */
+export function restoreSessionStats(
+  sessionDbPath: string,
+): RestoredSessionStats | null {
+  try {
+    if (!existsSync(sessionDbPath)) return null;
+    const sdb = new SessionDB({ dbPath: sessionDbPath });
+    try {
+      const sid = sdb.getLatestSessionId();
+      if (!sid) return null;
+
+      const stats = sdb.getToolCallStats(sid);
+      const calls: Record<string, number> = {};
+      const bytesReturned: Record<string, number> = {};
+      for (const [tool, row] of Object.entries(stats.byTool)) {
+        calls[tool] = row.calls;
+        bytesReturned[tool] = row.bytesReturned;
+      }
+
+      // started_at is "YYYY-MM-DD HH:MM:SS" in UTC (SQLite datetime() default);
+      // append "Z" so Date.parse interprets it as UTC, matching how the
+      // session was actually persisted.
+      let sessionStart = Date.now();
+      try {
+        const meta = sdb.getSessionStats(sid);
+        if (meta?.started_at) {
+          const parsed = Date.parse(`${meta.started_at}Z`);
+          if (Number.isFinite(parsed) && parsed > 0) sessionStart = parsed;
+        }
+      } catch {
+        // best-effort — keep `Date.now()` fallback
+      }
+
+      // Skip empty restores so callers can `if (restored)` and not stomp
+      // their already-zero default with another zero.
+      if (
+        Object.keys(calls).length === 0 &&
+        Object.keys(bytesReturned).length === 0
+      ) {
+        // Still useful to return sessionStart so uptime_ms doesn't reset
+        // even when no tool calls were made — but only if we found a session.
+        return { calls, bytesReturned, sessionStart };
+      }
+
+      return { calls, bytesReturned, sessionStart };
+    } finally {
+      sdb.close();
+    }
+  } catch {
+    return null;
+  }
+}