thatgfsj-code 1.0.3 → 3.0.0

package/src/app/index.ts

@@ -1,108 +1,180 @@
-/**
- * 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 type { ChatMessage, ChatResponse } from '../types.js';
-
-export class App {
-  config: ConfigManager;
-  llm: LLMService;
-  session: SessionManager;
-  tools: ToolRegistry;
-  hooks: HookManager;
-  prompts: SystemPromptBuilder;
-  skills: SkillRegistry;
-
-  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)
-   */
-  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 after saving partial response
-      if (fullResponse) {
-        this.session.addMessage('assistant', fullResponse);
-      }
-      throw err;
-    }
-
-    console.log();
-    this.session.addMessage('assistant', fullResponse);
-    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);
+    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 */ }
+      }
+      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';

package/src/cache/smartModel.ts

@@ -0,0 +1,52 @@
+/**
+ * Smart-model routing (P3 of the Reasonix plan).
+ *
+ * Idea: classify the user's input as "simple" or "complex" and route
+ * simple queries to a cheaper / faster model while keeping the main model
+ * for complex work. The classification is intentionally trivial — prompt
+ * length + presence of recent tool calls — because the cost of a
+ * misclassification (a slightly worse answer on a simple query) is much
+ * lower than the cost of running a frontier model on every greeting.
+ *
+ * Trade-off: each routing decision adds one model swap (different
+ * `model` field on the wire). If the cache prefix is keyed on the model
+ * string, the cache miss rate can spike on every simple query. To keep
+ * the prefix stable, callers should pass a *family* (e.g. "anthropic" or
+ * "deepseek") rather than a specific model name when forwarding the
+ * prompt to the downstream provider — that's outside the scope of this
+ * hook; this module only answers the question "should I downgrade?".
+ *
+ * v3.0.0: shipped as a stub. Real decision logic is conservative
+ * (downgrade only when prompt is short AND no recent tool activity).
+ * Future iterations can add heuristic or classifier-based routing.
+ */
+
+import type { ChatMessage } from '../types.js';
+
+export interface SmartModelDecision {
+  /** Should we route this turn to a cheaper model? */
+  downgrade: boolean;
+  /** Why we made this call — useful for `/cache` debug output. */
+  reason: string;
+}
+
+/**
+ * Heuristic: downgrade when
+ *   1. The latest user message is short (< 200 chars), AND
+ *   2. The last 3 messages contain no assistant tool_calls.
+ *
+ * This covers greetings, one-line questions, and simple follow-ups
+ * ("thanks", "ok", "explain this one line") while routing anything
+ * that triggered a tool to the main model.
+ */
+export function shouldDowngrade(messages: ChatMessage[], lastUserInput: string): SmartModelDecision {
+  if (lastUserInput.length > 200) {
+    return { downgrade: false, reason: 'prompt-too-long' };
+  }
+  const recent = messages.slice(-3);
+  const hasRecentToolCalls = recent.some(m => m.tool_calls && m.tool_calls.length > 0);
+  if (hasRecentToolCalls) {
+    return { downgrade: false, reason: 'recent-tool-call' };
+  }
+  return { downgrade: true, reason: 'short-no-tools' };
+}

package/src/cache/stats.ts

@@ -0,0 +1,199 @@
+/**
+ * Cache statistics store.
+ *
+ * Tracks per-round cache hit/miss token counts across the user's local
+ * sessions and persists them to `~/.thatgfsj/cache-stats.json`. The store
+ * is consumed by:
+ *   - the TUI Header (`⚡ 命中率 87%`)
+ *   - the /cache CLI command (detailed breakdown)
+ *   - the /cache reset command (clears the file)
+ *
+ * Provider-agnostic. Anthropic reports cache_creation_input_tokens /
+ * cache_read_input_tokens; DeepSeek reports prompt_cache_hit_tokens /
+ * prompt_cache_miss_tokens; OpenAI does not surface any cache stats at
+ * all (their automatic cache is invisible to the client). We normalize
+ * both shapes into a single internal model.
+ *
+ * Cost estimation is intentionally simplified:
+ *   - cache_read = 10% of normal input price
+ *   - cache_creation = 125% of normal input price (Anthropic charges extra
+ *     on first write)
+ *   - We compare against the baseline "what would this have cost without
+ *     caching" and report the delta as estimated savings.
+ *
+ * Prices are in CNY per million tokens. Defaults reflect Anthropic Claude
+ * Sonnet on the official API; users on cheaper providers may see savings
+ * proportional to their actual price floor. The numbers are *estimates*
+ * — the goal is to give the user a sense of order of magnitude, not a
+ * billable invoice.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+import type { Usage } from '../types.js';
+
+/** Per-million-token price in CNY. Adjust if your provider differs significantly. */
+const PRICE = {
+  normalInput: 3,
+  cacheRead: 0.3,
+  cacheCreation: 3.75,
+  output: 15,
+};
+
+/** Maximum number of recent rounds kept in the history array (rolling window). */
+const HISTORY_LIMIT = 50;
+
+export interface CacheStats {
+  /** Total tokens served from cache (Anthropic cache_read / DeepSeek hit). */
+  totalReadTokens: number;
+  /** Total tokens written into cache (Anthropic cache_creation / DeepSeek miss prefix written). */
+  totalCreationTokens: number;
+  /** Total input tokens (prompt_tokens). */
+  totalInputTokens: number;
+  /** Total output tokens. */
+  totalOutputTokens: number;
+  /** Number of completed rounds. */
+  totalRequests: number;
+  /** Last N round snapshots (oldest first). */
+  history: Array<{
+    ts: number;
+    read: number;
+    creation: number;
+    input: number;
+    output: number;
+    hitRate: number;
+  }>;
+}
+
+export interface CacheSnapshot extends CacheStats {
+  /** 0..1 ratio of cached tokens to total input tokens. */
+  hitRate: number;
+  /** Estimated CNY saved vs uncached baseline. */
+  estimatedSavingsCNY: number;
+}
+
+const EMPTY_STATS: CacheStats = {
+  totalReadTokens: 0,
+  totalCreationTokens: 0,
+  totalInputTokens: 0,
+  totalOutputTokens: 0,
+  totalRequests: 0,
+  history: [],
+};
+
+/**
+ * Estimate the CNY saved by cache_read vs a hypothetical uncached baseline.
+ * Negative values are clamped to zero (e.g. a relay station that returned
+ * bogus cache stats).
+ */
+export function estimateSavingsCNY(stats: CacheStats): number {
+  const baselineCost = (stats.totalReadTokens / 1e6) * PRICE.normalInput;
+  const cachedCost = (stats.totalReadTokens / 1e6) * PRICE.cacheRead;
+  return Math.max(0, baselineCost - cachedCost);
+}
+
+/**
+ * Persists cache stats to disk. Safe to call from a hot path — uses atomic
+ * write (write to .tmp, rename) to avoid corruption on crash.
+ */
+export class CacheStatsStore {
+  private stats: CacheStats;
+  private path: string;
+
+  constructor(path?: string) {
+    this.path = path ?? join(homedir(), '.thatgfsj', 'cache-stats.json');
+    this.stats = this.load();
+  }
+
+  /**
+   * Record a single round's usage. Provider-agnostic: accepts both Anthropic
+   * (cache_creation_input_tokens / cache_read_input_tokens) and DeepSeek
+   * (prompt_cache_hit_tokens / prompt_cache_miss_tokens) shapes. If a
+   * provider returned neither (e.g. OpenAI), the call is a no-op apart
+   * from updating totalRequest count.
+   */
+  record(usage: Usage): void {
+    const read = usage.cache_read_input_tokens ?? usage.prompt_cache_hit_tokens ?? 0;
+    const creation = usage.cache_creation_input_tokens
+      ?? (usage.prompt_cache_miss_tokens ?? 0);
+    const input = usage.prompt_tokens ?? 0;
+    const output = usage.completion_tokens ?? 0;
+
+    // Avoid double-counting: if the provider reported both cache_creation
+    // and prompt_cache_miss_tokens we'd otherwise sum them. The ?? in the
+    // chain above only uses prompt_cache_miss_tokens when
+    // cache_creation_input_tokens is undefined, which is what we want.
+
+    this.stats.totalReadTokens += read;
+    this.stats.totalCreationTokens += creation;
+    this.stats.totalInputTokens += input;
+    this.stats.totalOutputTokens += output;
+    this.stats.totalRequests += 1;
+
+    // Per-round snapshot (for /cache command history view).
+    const total = read + (input - read);
+    const hitRate = total > 0 ? read / total : 0;
+    this.stats.history.push({ ts: Date.now(), read, creation, input, output, hitRate });
+    if (this.stats.history.length > HISTORY_LIMIT) {
+      this.stats.history.splice(0, this.stats.history.length - HISTORY_LIMIT);
+    }
+
+    this.save();
+  }
+
+  /**
+   * Reset the stats. Used by `/cache reset`.
+   */
+  reset(): void {
+    this.stats = { ...EMPTY_STATS, history: [] };
+    this.save();
+  }
+
+  /**
+   * Read-only snapshot for rendering (TUI Header, /cache command).
+   */
+  snapshot(): CacheSnapshot {
+    const input = this.stats.totalInputTokens;
+    const read = this.stats.totalReadTokens;
+    const hitRate = input > 0 ? read / input : 0;
+    return {
+      ...this.stats,
+      hitRate,
+      estimatedSavingsCNY: estimateSavingsCNY(this.stats),
+    };
+  }
+
+  /** Direct accessor for tests. */
+  get raw(): CacheStats { return this.stats; }
+
+  // -- I/O --
+
+  private load(): CacheStats {
+    try {
+      if (!existsSync(this.path)) return { ...EMPTY_STATS, history: [] };
+      const txt = readFileSync(this.path, 'utf-8');
+      const parsed = JSON.parse(txt);
+      // Tolerate partial / older shapes.
+      return {
+        totalReadTokens: parsed.totalReadTokens ?? 0,
+        totalCreationTokens: parsed.totalCreationTokens ?? 0,
+        totalInputTokens: parsed.totalInputTokens ?? 0,
+        totalOutputTokens: parsed.totalOutputTokens ?? 0,
+        totalRequests: parsed.totalRequests ?? 0,
+        history: Array.isArray(parsed.history) ? parsed.history : [],
+      };
+    } catch {
+      return { ...EMPTY_STATS, history: [] };
+    }
+  }
+
+  private save(): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      writeFileSync(this.path, JSON.stringify(this.stats, null, 2), 'utf-8');
+    } catch {
+      // best-effort persistence; do not crash the chat loop on disk errors
+    }
+  }
+}