thatgfsj-code 2.2.9 → 3.0.1

package/dist/types.js

@@ -1,6 +1,13 @@
 /**
  * Global shared types for Thatgfsj Code
  * Only the most fundamental types used across modules
+ *
+ * v3.0.0+: Extended for Reasonix-style prompt caching:
+ *   - ChatMessage.content now accepts ContentBlock[] (Anthropic-style)
+ *   - cache_control field for explicit Anthropic cache breakpoints
+ *   - usage extended with cache_creation_input_tokens / cache_read_input_tokens
+ *     (Anthropic) and prompt_cache_hit_tokens / prompt_cache_miss_tokens (DeepSeek)
+ *   - StreamChunk now has 'thinking' / 'usage' variants for structured streaming
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/utils/stableStringify.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic JSON serializer.
+ *
+ * JSON.stringify in V8 iterates keys in insertion order, which means objects
+ * built with literal `{a, b, c}` are stable, but anything built via spread,
+ * Object.fromEntries, or merged maps can produce different byte sequences
+ * between requests. That byte-sequence instability is fatal for prompt-cache
+ * hit-rate: a single reordered key invalidates the cache fingerprint.
+ *
+ * stableStringify sorts object keys lexicographically before recursing, so
+ * any pair of structurally equal objects produces identical JSON text.
+ *
+ * Performance note: O(n log n) on key counts per object. For typical request
+ * bodies (<200 KB) the overhead is negligible (<5 ms). The main hot path is
+ * the tool/parameters tree which is small and stable in practice.
+ *
+ * Reference: Reasonix-style "stableStringify" requirement for prefix-cache
+ * byte-level stability (see DeepSeek Reasonix, Section 3).
+ */
+export declare function stableStringify(value: unknown): string;
+//# sourceMappingURL=stableStringify.d.ts.map

package/dist/utils/stableStringify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stableStringify.d.ts","sourceRoot":"","sources":["../../src/utils/stableStringify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD"}

package/dist/utils/stableStringify.js

@@ -0,0 +1,53 @@
+/**
+ * Deterministic JSON serializer.
+ *
+ * JSON.stringify in V8 iterates keys in insertion order, which means objects
+ * built with literal `{a, b, c}` are stable, but anything built via spread,
+ * Object.fromEntries, or merged maps can produce different byte sequences
+ * between requests. That byte-sequence instability is fatal for prompt-cache
+ * hit-rate: a single reordered key invalidates the cache fingerprint.
+ *
+ * stableStringify sorts object keys lexicographically before recursing, so
+ * any pair of structurally equal objects produces identical JSON text.
+ *
+ * Performance note: O(n log n) on key counts per object. For typical request
+ * bodies (<200 KB) the overhead is negligible (<5 ms). The main hot path is
+ * the tool/parameters tree which is small and stable in practice.
+ *
+ * Reference: Reasonix-style "stableStringify" requirement for prefix-cache
+ * byte-level stability (see DeepSeek Reasonix, Section 3).
+ */
+export function stableStringify(value) {
+    return stringify(value);
+}
+function stringify(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'null'; // OpenAI wire format does not carry undefined
+    const t = typeof value;
+    if (t === 'string')
+        return JSON.stringify(value);
+    if (t === 'number')
+        return Number.isFinite(value) ? String(value) : 'null';
+    if (t === 'boolean')
+        return value ? 'true' : 'false';
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => stringify(v)).join(',') + ']';
+    }
+    if (t === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const parts = [];
+        for (const k of keys) {
+            const v = obj[k];
+            if (v === undefined)
+                continue; // omit undefined to match OpenAI/Anthropic convention
+            parts.push(JSON.stringify(k) + ':' + stringify(v));
+        }
+        return '{' + parts.join(',') + '}';
+    }
+    // functions / symbols / bigints: drop
+    return 'null';
+}
+//# sourceMappingURL=stableStringify.js.map

package/dist/utils/stableStringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stableStringify.js","sourceRoot":"","sources":["../../src/utils/stableStringify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,CAAC,8CAA8C;IACtF,MAAM,CAAC,GAAG,OAAO,KAAK,CAAC;IACvB,IAAI,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAe,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACrF,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACjB,IAAI,CAAC,KAAK,SAAS;gBAAE,SAAS,CAAC,sDAAsD;YACrF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;IACD,sCAAsC;IACtC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/thinking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thinking.d.ts","sourceRoot":"","sources":["../../src/utils/thinking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,QAAA,MAAM,iBAAiB,EAAE,MAAM,EAO9B,CAAC;AAEF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAqB5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,OAAe,GAAG,MAAM,CAMvF;AAoBD,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"thinking.d.ts","sourceRoot":"","sources":["../../src/utils/thinking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,QAAA,MAAM,iBAAiB,EAAE,MAAM,EAI9B,CAAC;AAEF,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAqB5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAM9D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,OAAe,GAAG,MAAM,CAMvF;AAoBD,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/utils/thinking.js

@@ -32,11 +32,8 @@
  */
 const THINKING_PATTERNS = [
     /<think>[\s\S]*?<\/think>/gi,
-    /<thinking>[\s\S]*?<\/thinking>/gi,
     /<reasoning>[\s\S]*?<\/reasoning>/gi,
-    /<THINK>[\s\S]*?<\/THINK>/gi, // v2.2.7 edge: case variant
     /\[THINK\][\s\S]*?\[\/THINK\]/gi,
-    /\[\/?think\]/gi, // bare [think] / [/think] (rare)
 ];
 export function splitThinking(content) {
     if (!content) {

package/dist/utils/thinking.js.map

@@ -1 +1 @@
-{"version":3,"file":"thinking.js","sourceRoot":"","sources":["../../src/utils/thinking.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"thinking.js","sourceRoot":"","sources":["../../src/utils/thinking.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "thatgfsj-code",
-  "version": "2.2.9",
-  "description": "Thatgfsj Code - AI Coding Assistant",
+  "version": "3.0.1",
+  "description": "Thatgfsj Code - AI Coding Assistant with Reasonix-style prompt caching",
   "main": "dist/cmd/index.js",
   "type": "module",
   "bin": {
@@ -13,9 +13,8 @@
     "start": "node dist/cmd/index.js",
     "dev": "tsc && node dist/cmd/index.js",
     "link": "npm link",
-    "test": "node tests/smoke-thinking.mjs && node tests/smoke-tool.mjs && node tests/smoke-pollution.mjs && node tests/edge-thinking.mjs && node tests/edge-tool.mjs && node tests/edge-pollution.mjs && node tests/edge-session.mjs && node tests/edge-cli.mjs",
-    "test:single": "node tests/",
-    "prepublishOnly": "npm run build && npm test"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "ai",
@@ -43,6 +42,8 @@
     "@types/marked-terminal": "^6.1.1",
     "@types/node": "^20.10.0",
     "@types/react": "^19.2.17",
-    "typescript": "^5.3.0"
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.10"
   }
 }

package/src/app/index.ts

@@ -1,124 +1,189 @@
-/**
- * App - Core application singleton
- * Simplified: directly uses LLMService (which has built-in agent loop)
- */
-
-import { ConfigManager } from '../config/index.js';
-import { LLMService } from '../llm/index.js';
-import { SessionManager } from '../session/index.js';
-import { ToolRegistry } from '../tools/index.js';
-import { HookManager } from '../hooks/index.js';
-import { SystemPromptBuilder } from '../prompts/index.js';
-import { SkillRegistry } from '../skills/index.js';
-import { compressThinking } from '../utils/thinking.js';
-import type { ChatMessage, ChatResponse } from '../types.js';
-
-export class App {
-  config: ConfigManager;
-  llm: LLMService;
-  session: SessionManager;
-  tools: ToolRegistry;
-  hooks: HookManager;
-  prompts: SystemPromptBuilder;
-  skills: SkillRegistry;
-  /**
-   * v2.2.5 (product 0.4.2): toggle <think> block compression. Default
-   * true. Toggled by `--show-thinking` on the CLI or `/thinking on|off`
-   * in the REPL.
-   */
-  showThinking: boolean = false;
-
-  private constructor(
-    config: ConfigManager,
-    llm: LLMService,
-    session: SessionManager,
-    tools: ToolRegistry,
-    hooks: HookManager,
-    prompts: SystemPromptBuilder,
-    skills: SkillRegistry,
-  ) {
-    this.config = config;
-    this.llm = llm;
-    this.session = session;
-    this.tools = tools;
-    this.hooks = hooks;
-    this.prompts = prompts;
-    this.skills = skills;
-  }
-
-  static async create(): Promise<App> {
-    const config = await ConfigManager.load();
-    const aiConfig = config.getAIConfig();
-
-    const llm = LLMService.fromConfig(aiConfig);
-    const session = new SessionManager(config.get().contextLength || 50);
-    const tools = new ToolRegistry();
-    const hooks = new HookManager();
-    const skills = new SkillRegistry();
-
-    // Register tools with LLM service
-    llm.registerTools(tools.list());
-
-    // Auto-init NWT timeline
-    const nwtTool = tools.get('nwt');
-    if (nwtTool) {
-      await nwtTool.execute({ action: 'init' });
-    }
-
-    // Build system prompt with active skills
-    const prompts = new SystemPromptBuilder({
-      cwd: process.cwd(),
-      tools: tools.list(),
-      permissionMode: 'ask',
-      skillsPrompt: skills.getActivePrompts(),
-    });
-    session.addMessage('system', prompts.build());
-
-    return new App(config, llm, session, tools, hooks, prompts, skills);
-  }
-
-  /**
-   * Stream a response for the current session messages.
-   * The LLMService handles the full agent loop internally.
-   */
-  async *streamResponse(messages?: ChatMessage[]): AsyncGenerator<string, void> {
-    const msgs = messages || this.session.getMessages();
-    for await (const chunk of this.llm.chatStream(msgs)) {
-      yield chunk;
-    }
-  }
-
-  /**
-   * Run a single prompt (non-interactive mode)
-   *
-   * v2.2.4 (port from v2.1.0): persistence of the assistant message
-   * uses addMessageSafe, which drops the message if it contains
-   * pollution markers like "[已中断]".
-   *
-   * v2.2.5 (product 0.4.2): persistence also strips <think> blocks
-   * (and similar reasoning delimiters) when showThinking is false,
-   * so the conversation log stays compact.
-   */
-  async runPrompt(prompt: string): Promise<string> {
-    this.session.addMessage('user', prompt);
-
-    let fullResponse = '';
-    try {
-      for await (const chunk of this.streamResponse()) {
-        process.stdout.write(chunk);
-        fullResponse += chunk;
-      }
-    } catch (err) {
-      // Re-throw without persisting partial response. Persisting
-      // truncated output here was the source of the [已中断] loop in
-      // v2.2.3.
-      throw err;
-    }
-
-    console.log();
-    // v2.2.5: compress <think> blocks before persisting.
-    const toPersist = compressThinking(fullResponse, this.showThinking);
-    this.session.addMessageSafe('assistant', toPersist);
-    return fullResponse;
-  }
-}
+/**
+ * App - Core application singleton
+ * Simplified: directly uses LLMService (which has built-in agent loop)
+ *
+ * v3.0.0+: streamResponse yields structured StreamChunk
+ *   - runPrompt streams { type: 'text' } chunks to stdout and captures the
+ *     final usage for cache stats recording.
+ */
+
+import { ConfigManager } from '../config/index.js';
+import { LLMService } from '../llm/index.js';
+import { SessionManager } from '../session/index.js';
+import { ToolRegistry } from '../tools/index.js';
+import { HookManager } from '../hooks/index.js';
+import { SystemPromptBuilder } from '../prompts/index.js';
+import { SkillRegistry } from '../skills/index.js';
+import { CacheStatsStore } from '../cache/stats.js';
+import { compressThinking } from '../utils/thinking.js';
+import type { ChatMessage, ChatResponse, StreamChunk, Usage } from '../types.js';
+
+export class App {
+  config: ConfigManager;
+  llm: LLMService;
+  session: SessionManager;
+  tools: ToolRegistry;
+  hooks: HookManager;
+  prompts: SystemPromptBuilder;
+  skills: SkillRegistry;
+  /**
+   * v3.0.0: persistent cache stats store. The single source of truth for
+   * cache hit-rate and estimated savings, surfaced through the TUI Header
+   * and the /cache command.
+   */
+  cacheStats: CacheStatsStore;
+  /**
+   * v2.2.5 (product 0.4.2): toggle  block compression. Default
+   * true. Toggled by `--show-thinking` on the CLI or `/thinking on|off`
+   * in the REPL.
+   */
+  showThinking: boolean = false;
+
+  private constructor(
+    config: ConfigManager,
+    llm: LLMService,
+    session: SessionManager,
+    tools: ToolRegistry,
+    hooks: HookManager,
+    prompts: SystemPromptBuilder,
+    skills: SkillRegistry,
+    cacheStats: CacheStatsStore,
+  ) {
+    this.config = config;
+    this.llm = llm;
+    this.session = session;
+    this.tools = tools;
+    this.hooks = hooks;
+    this.prompts = prompts;
+    this.skills = skills;
+    this.cacheStats = cacheStats;
+  }
+
+  static async create(): Promise<App> {
+    const config = await ConfigManager.load();
+    const aiConfig = config.getAIConfig();
+
+    const llm = LLMService.fromConfig(aiConfig);
+    const cacheStats = new CacheStatsStore();
+    const session = new SessionManager(config.get().contextLength || 50);
+    // v3.0.0: do not mutate messages when context grows — instead, surface
+    // a "consider /new" toast via onSuggestNewSession. The TUI wires this
+    // up in app.tsx; in CLI single-prompt mode it's a no-op (one-shot).
+    session.onSuggestNewSession = (info) => {
+      console.warn(
+        `\n  ⚠️  上下文较长（${info.currentLength}/${info.max}）。` +
+        `建议调 /new 开新会话（NWT 已自动归档历史）\n`,
+      );
+    };
+    const tools = new ToolRegistry();
+    const hooks = new HookManager();
+    const skills = new SkillRegistry();
+
+    // Register tools with LLM service
+    llm.registerTools(tools.list());
+
+    // Auto-init NWT timeline
+    const nwtTool = tools.get('nwt');
+    if (nwtTool) {
+      await nwtTool.execute({ action: 'init' });
+    }
+
+    // Build system prompt with active skills
+    const prompts = new SystemPromptBuilder({
+      cwd: process.cwd(),
+      tools: tools.list(),
+      permissionMode: 'ask',
+      skillsPrompt: skills.getActivePrompts(),
+    });
+    session.addMessage('system', prompts.build());
+
+    return new App(config, llm, session, tools, hooks, prompts, skills, cacheStats);
+  }
+
+  /**
+   * Stream a response for the current session messages.
+   * The LLMService handles the full agent loop internally.
+   *
+   * Yields structured StreamChunks. Returns the final ChatResponse (with usage
+   * if the provider reported it) so the caller can record cache stats.
+   *
+   * Implementation note: we drain the inner stream manually so the final
+   * ChatResponse returned by LLMService.chatStream is propagated as this
+   * generator's return value. Using yield* doesn't carry the return value
+   * through TS's AsyncGenerator<T, R> type inference in this version of
+   * TypeScript, so we wrap with an inner for-await and explicit return.
+   */
+  async *streamResponse(messages?: ChatMessage[]): AsyncGenerator<StreamChunk, ChatResponse> {
+    const msgs = messages || this.session.getMessages();
+    const inner = this.llm.chatStream(msgs);
+    const debugUsage = !!process.env.GFCODE_DEBUG_USAGE;
+    let next = await inner.next();
+    while (!next.done) {
+      // Forward chunks unchanged, but capture usage into the persistent
+      // cache stats store so the TUI Header / /cache command can read it.
+      if (next.value && next.value.type === 'usage') {
+        try { this.cacheStats.record(next.value.usage); } catch { /* best-effort */ }
+        if (debugUsage) {
+          // v3.0.0 DEBUG: dump raw usage fields to stderr so the user can
+          // confirm whether the upstream provider/relay forwards cache stats.
+          // Enable with: GFCODE_DEBUG_USAGE=1 gfcode ...
+          process.stderr.write(
+            '[debug_usage] ' + JSON.stringify(next.value.usage) + '\n'
+          );
+        }
+      }
+      yield next.value;
+      next = await inner.next();
+    }
+    // The generator's return value (ChatResponse with usage) is propagated
+    // to callers via `for await ... await streamResponse.next()` semantics.
+    return next.value;
+  }
+
+  /**
+   * Run a single prompt (non-interactive mode)
+   *
+   * v2.2.4 (port from v2.1.0): persistence of the assistant message
+   * uses addMessageSafe, which drops the message if it contains
+   * pollution markers like "[已中断]".
+   *
+   * v2.2.5 (product 0.4.2): persistence also strips  blocks
+   * (and similar reasoning delimiters) when showThinking is false,
+   * so the conversation log stays compact.
+   *
+   * v3.0.0: yields structured StreamChunks; final usage is captured
+   * into onUsage callback for cache stats persistence.
+   */
+  async runPrompt(prompt: string, onUsage?: (usage: Usage) => void): Promise<string> {
+    this.session.addMessage('user', prompt);
+
+    let fullResponse = '';
+    let finalUsage: ChatResponse['usage'] | undefined;
+    try {
+      for await (const chunk of this.streamResponse()) {
+        if (chunk.type === 'text' && chunk.content) {
+          process.stdout.write(chunk.content);
+          fullResponse += chunk.content;
+        } else if (chunk.type === 'usage') {
+          finalUsage = chunk.usage;
+        }
+      }
+    } catch (err) {
+      // Re-throw without persisting partial response. Persisting
+      // truncated output here was the source of the [已中断] loop in
+      // v2.2.3.
+      throw err;
+    }
+
+    console.log();
+    // v2.2.5: compress  blocks before persisting.
+    const toPersist = compressThinking(fullResponse, this.showThinking);
+    this.session.addMessageSafe('assistant', toPersist);
+
+    // v3.0.0: forward usage to caller (CLI single-shot mode records stats too)
+    if (finalUsage && onUsage) {
+      try { onUsage(finalUsage); } catch { /* best-effort */ }
+    }
+    return fullResponse;
+  }
+}

package/src/cache/fingerprint.ts

@@ -0,0 +1,101 @@
+/**
+ * Cache fingerprints — small, stable hashes used to detect when the
+ * "cacheable prefix" of an LLM request changes between rounds.
+ *
+ * Why this exists:
+ *   Anthropic prompt cache and DeepSeek automatic prefix cache both break
+ *   when the request body changes upstream of the cache breakpoint. To
+ *   debug "why is my hit-rate 0%", we want a quick fingerprint of the
+ *   things that *should* be cacheable (tools + system prefix) so we can
+ *   log it on every request and compare across rounds.
+ *
+ *   The fingerprint itself is NOT used to decide anything (the upstream
+ *   provider does the actual cache lookup). It's purely a debug /
+ *   observability tool — same role as `reasoning_content` in the message
+ *   schema: captured for transparency, not for control flow.
+ *
+ * Implementation:
+ *   - Uses stableStringify (sibling module) so logically equal objects
+ *     always produce the same JSON.
+ *   - Hashes with sha256 (Node built-in `crypto`), truncated to 16 chars.
+ *     16 hex chars = 64 bits, which is plenty for collision-resistance
+ *     across a single user's session.
+ */
+
+import { createHash } from 'crypto';
+import type { Tool } from '../tools/types.js';
+import type { SystemSegment } from '../prompts/index.js';
+
+/**
+ * Hash a stable JSON representation of `value` and return a 16-char hex prefix.
+ * Recursively normalizes object keys (sorted) so insertion order does not
+ * affect the output.
+ */
+export function fingerprint(value: unknown): string {
+  // stableStringify is imported lazily to avoid a circular dep — fingerprint
+  // is consumed by both providers (which sit above utils/) and the cache
+  // stats store (which sits next to fingerprint). Top-level import works
+  // because utils has no other consumers besides fingerprint, so we just
+  // import statically.
+  return createHash('sha256')
+    .update(stableStringifyLocal(value))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/**
+ * Compute a fingerprint of the registered tool schemas.
+ *
+ * We deliberately pick only `name`, `description`, and `inputSchema` — the
+ * three fields that matter for the upstream prompt cache. Other Tool
+ * metadata (version strings, descriptions of internal handlers, etc) is
+ * ignored because it never reaches the wire.
+ */
+export function fingerprintTools(tools: Tool[]): string {
+  const minimal = tools.map(t => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  }));
+  return fingerprint({ tools: minimal });
+}
+
+/**
+ * Compute a fingerprint of the system prompt's *immutable* portion.
+ *
+ * Volatile segments (NWT history, current time) are deliberately excluded
+ * because they change between rounds and would defeat the fingerprint's
+ * purpose as a "did the cacheable prefix change?" signal.
+ */
+export function fingerprintSystemPrefix(segments: SystemSegment[]): string {
+  const immutable = segments.filter(s => !s.volatile);
+  return fingerprint({ system: immutable.map(s => ({ name: s.name, content: s.content })) });
+}
+
+// -- Local copy of stableStringify to avoid a circular dep. This must stay
+//    byte-for-byte identical to src/utils/stableStringify.ts. If you change
+//    one, change both.
+
+function stableStringifyLocal(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'null';
+  const t = typeof value;
+  if (t === 'string') return JSON.stringify(value);
+  if (t === 'number') return Number.isFinite(value as number) ? String(value) : 'null';
+  if (t === 'boolean') return value ? 'true' : 'false';
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => stableStringifyLocal(v)).join(',') + ']';
+  }
+  if (t === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    const parts: string[] = [];
+    for (const k of keys) {
+      const v = obj[k];
+      if (v === undefined) continue;
+      parts.push(JSON.stringify(k) + ':' + stableStringifyLocal(v));
+    }
+    return '{' + parts.join(',') + '}';
+  }
+  return 'null';
+}

package/src/cache/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Cache subsystem barrel. Re-exports the public surface used by the TUI,
+ * the App singleton, and the LLM service.
+ *
+ * Modules:
+ *   - fingerprint.ts: stable hashes for tools + immutable system prefix
+ *   - stats.ts:       CacheStatsStore — per-round hit/miss + cost savings
+ *   - volatile.ts:    VolatileScratch — per-round scratch that never reaches the API
+ *   - smartModel.ts:  smart-model routing hook (simple → mini, complex → main)
+ */
+
+export { fingerprint, fingerprintTools, fingerprintSystemPrefix } from './fingerprint.js';
+export { CacheStatsStore, estimateSavingsCNY, type CacheStats, type CacheSnapshot } from './stats.js';
+export { VolatileScratch } from './volatile.js';
+export { shouldDowngrade, type SmartModelDecision } from './smartModel.js';