@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/llm/stream-watchdog.js

@@ -0,0 +1,70 @@
+/**
+ * Stream Idle Watchdog — guarantees an upper bound on the time a streaming
+ * LLM call can spend with no bytes arriving. Without this, a wedged HTTP/2
+ * connection can hang the session indefinitely; the SDK's request timeout
+ * only covers the initial fetch, not the streaming body.
+ *
+ * Disabled by default. Enabled via env CODESHELL_ENABLE_STREAM_WATCHDOG=1.
+ */
+export class StreamIdleTimeoutError extends Error {
+    idleMs;
+    requestId;
+    kind = "stream-idle-timeout";
+    constructor(idleMs, requestId) {
+        super(`Stream idle for ${idleMs}ms — aborted`);
+        this.idleMs = idleMs;
+        this.requestId = requestId;
+        this.name = "StreamIdleTimeoutError";
+    }
+}
+export function createStreamWatchdog(opts) {
+    const warnMs = opts.warningMs ?? Math.floor(opts.idleTimeoutMs / 2);
+    let idleTimer = null;
+    let warnTimer = null;
+    let disposed = false;
+    function arm() {
+        if (disposed)
+            return;
+        if (opts.onWarning) {
+            warnTimer = setTimeout(() => {
+                if (disposed)
+                    return;
+                opts.onWarning?.(warnMs);
+            }, warnMs);
+        }
+        idleTimer = setTimeout(() => {
+            if (disposed)
+                return;
+            opts.onTimeout();
+        }, opts.idleTimeoutMs);
+    }
+    function clear() {
+        if (idleTimer !== null) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+        if (warnTimer !== null) {
+            clearTimeout(warnTimer);
+            warnTimer = null;
+        }
+    }
+    arm();
+    return {
+        reset() {
+            if (disposed)
+                return;
+            clear();
+            arm();
+        },
+        dispose() {
+            disposed = true;
+            clear();
+        },
+    };
+}
+/** Environment-driven defaults. Read once at import time is fine — these never change inside a process. */
+export const STREAM_WATCHDOG_CONFIG = {
+    enabled: process.env.CODESHELL_ENABLE_STREAM_WATCHDOG === "1",
+    idleTimeoutMs: parseInt(process.env.CODESHELL_STREAM_IDLE_TIMEOUT_MS || "", 10) || 90_000,
+    retries: parseInt(process.env.CODESHELL_STREAM_WATCHDOG_RETRIES || "", 10) || 2,
+};

package/dist/llm/token-counter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Token counter — best-effort live token count for streaming output.
+ *
+ * Uses gpt-tokenizer's cl100k_base encoding. It's exact for GPT-4 family and
+ * close enough (within ~10%) for Claude/DeepSeek/Qwen for the purpose of a
+ * live counter in the UI. The authoritative number is still the provider's
+ * `usage` field, captured at end-of-stream.
+ *
+ * The encoder is lazy-initialized on first use so we don't pay the cost on
+ * startup for sessions that never stream.
+ */
+/**
+ * Count tokens in `text`. Synchronous. If the encoder isn't loaded yet,
+ * falls back to chars/4 — only happens for the very first stream chunk in a
+ * cold process.
+ */
+export declare function countTokens(text: string): number;

package/dist/llm/token-counter.js

@@ -0,0 +1,36 @@
+/**
+ * Token counter — best-effort live token count for streaming output.
+ *
+ * Uses gpt-tokenizer's cl100k_base encoding. It's exact for GPT-4 family and
+ * close enough (within ~10%) for Claude/DeepSeek/Qwen for the purpose of a
+ * live counter in the UI. The authoritative number is still the provider's
+ * `usage` field, captured at end-of-stream.
+ *
+ * The encoder is lazy-initialized on first use so we don't pay the cost on
+ * startup for sessions that never stream.
+ */
+let encoderPromise = null;
+async function getEncoder() {
+    if (!encoderPromise) {
+        encoderPromise = import("gpt-tokenizer").then((mod) => mod.encode);
+    }
+    return encoderPromise;
+}
+let encoderSync = null;
+// Kick off the import so synchronous callers can use it on the next tick.
+// First call still falls back to a length estimate.
+void getEncoder().then((fn) => {
+    encoderSync = fn;
+});
+/**
+ * Count tokens in `text`. Synchronous. If the encoder isn't loaded yet,
+ * falls back to chars/4 — only happens for the very first stream chunk in a
+ * cold process.
+ */
+export function countTokens(text) {
+    if (!text)
+        return 0;
+    if (encoderSync)
+        return encoderSync(text).length;
+    return Math.ceil(text.length / 4);
+}

package/dist/llm/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * LLM-specific internal types.
+ */
+import type { Message, ToolDefinition, LLMStreamChunk, TokenUsage } from "../types.js";
+export interface CreateMessageOptions {
+    systemPrompt: string;
+    messages: Message[];
+    tools?: ToolDefinition[];
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    onChunk?: (chunk: LLMStreamChunk) => void;
+    signal?: AbortSignal;
+    /**
+     * If false, this call's usage is excluded from the client's usage tracker
+     * and from the process-wide onUsage hook. Used for auxiliary sub-calls
+     * (tool-summary, future helper prompts) that should not appear in
+     * session_end.cost or skew turn/requestCount semantics.
+     * @default true
+     */
+    recordUsage?: boolean;
+    /**
+     * DeepSeek V4 thinking-mode switch. "enabled" is the endpoint default;
+     * "disabled" turns reasoning off (faster, cheaper, no `reasoning_content`
+     * on the reply). Ignored by every provider except DeepSeek V4 — the OpenAI
+     * SDK forwards unknown top-level fields verbatim, so it's harmless on
+     * other compatible endpoints.
+     */
+    thinking?: "enabled" | "disabled";
+}
+export interface LLMUsageTracker {
+    records: TokenUsage[];
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalTokens: number;
+    requestCount: number;
+}

package/dist/llm/types.js

@@ -0,0 +1,4 @@
+/**
+ * LLM-specific internal types.
+ */
+export {};

package/dist/logging/logger.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Unified file logger for code-shell.
+ *
+ * Sinks (JSON Lines), routed by `cat`:
+ *   ~/.code-shell/logs/ui-ink-YYYY-MM-DD.log
+ *     — UI/ink chatter: stream events, ctx render, ink screen diffs.
+ *   ~/.code-shell/logs/engine-YYYY-MM-DD.log
+ *     — everything else: engine, llm, tool, context, mcp, sandbox, ...
+ *
+ * Routing is by entry `cat`: cat ∈ {ui, ink, render, stream} → ui-ink bucket;
+ * anything else → engine bucket. Run scripts/logs.sh to query both at once
+ * (merge sorted by timestamp, filter by sid, etc).
+ *
+ * Level defaults:
+ *   - Local dev (CODE_SHELL_DEV=1, or running from src/, or --debug)   → "debug"
+ *   - Otherwise                                                         → "info"
+ *   - CODE_SHELL_LOG_LEVEL overrides everything.
+ *
+ * Category filter (--debug=mcp,api or CODE_SHELL_DEBUG=mcp,api):
+ *   When set, only debug logs whose `cat` matches are written.
+ *
+ * Disable entirely: CODE_SHELL_LOG=0
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Override the directory log files are written into. Pass `null` to
+ * revert to the default `~/.code-shell/logs`. Affects all future writes
+ * AND `getLogsDir()` / `getRecentLogs()` reads, so call this before any
+ * log activity if you want a clean redirected stream.
+ */
+export declare function setLogsDir(dir: string | null): void;
+export declare function setCurrentSid(sid: string): void;
+export declare function getCurrentSid(): string;
+/**
+ * Run `fn` inside an ALS scope tagged with `sid`. All log lines emitted
+ * synchronously or via `await` inside `fn` resolve `getCurrentSid()` to
+ * this `sid` — concurrent Engine.run invocations no longer race on a
+ * module global.
+ */
+export declare function runWithSid<T>(sid: string, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Bind `sid` to the *current* async context without needing a callback.
+ * The binding lasts until the current async stack unwinds; concurrent
+ * sibling async chains keep their own bindings. Engine.run uses this so
+ * we don't have to indent the entire (long) method body into a callback.
+ */
+export declare function enterSid(sid: string): void;
+export declare function getInMemoryErrors(): ReadonlyArray<{
+    msg: string;
+    t: string;
+    data?: unknown;
+}>;
+export type ErrorLogSink = {
+    logError: (error: Error) => void;
+    logMCPError: (serverName: string, error: unknown) => void;
+    logMCPDebug: (serverName: string, message: string) => void;
+    getErrorsPath: () => string;
+    getMCPLogsPath: (serverName: string) => string;
+};
+export declare function attachErrorLogSink(sink: ErrorLogSink): void;
+export interface LogContext {
+    cat?: string;
+    sid?: string;
+    [key: string]: unknown;
+}
+declare class Logger {
+    private readonly context;
+    private readonly enabled;
+    private readonly minLevel;
+    private readonly categoryFilter;
+    private readonly stderrEcho;
+    private dirReady;
+    constructor(context?: LogContext);
+    child(extra: LogContext): Logger;
+    /**
+     * Set the session id stamped on every subsequent log entry written by
+     * any logger in the process. Called by Engine once a run's
+     * authoritative session id is known.
+     */
+    setSid(sid: string): void;
+    getSid(): string;
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msgOrErr: string | Error | unknown, data?: Record<string, unknown> | Error): void;
+    private recordError;
+    private write;
+    getMinLevel(): LogLevel;
+    isCategoryActive(cat: string): boolean;
+    /**
+     * Open a span: writes a `<name>.begin` debug entry now and returns a handle
+     * whose `end()` writes `<name>.end` with `duration_ms` populated. Use for
+     * any "I want begin → end + how long" pattern (tool exec, LLM request,
+     * permission ask, etc.) so the begin/end pair is grouped under one cat
+     * and the duration is computed once instead of by hand from timestamps.
+     */
+    span(name: string, data?: Record<string, unknown>): LogSpan;
+}
+export interface LogSpan {
+    end(extra?: Record<string, unknown>): void;
+    fail(err: unknown, extra?: Record<string, unknown>): void;
+}
+export declare const logger: Logger;
+export declare function getLogsDir(): string;
+export declare function getRecentLogs(n?: number): string[];
+export declare function rotateLogs(): void;
+/** @internal — for tests */
+export declare function _resetLoggerStateForTesting(): void;
+export {};

package/dist/logging/logger.js

@@ -0,0 +1,390 @@
+/**
+ * Unified file logger for code-shell.
+ *
+ * Sinks (JSON Lines), routed by `cat`:
+ *   ~/.code-shell/logs/ui-ink-YYYY-MM-DD.log
+ *     — UI/ink chatter: stream events, ctx render, ink screen diffs.
+ *   ~/.code-shell/logs/engine-YYYY-MM-DD.log
+ *     — everything else: engine, llm, tool, context, mcp, sandbox, ...
+ *
+ * Routing is by entry `cat`: cat ∈ {ui, ink, render, stream} → ui-ink bucket;
+ * anything else → engine bucket. Run scripts/logs.sh to query both at once
+ * (merge sorted by timestamp, filter by sid, etc).
+ *
+ * Level defaults:
+ *   - Local dev (CODE_SHELL_DEV=1, or running from src/, or --debug)   → "debug"
+ *   - Otherwise                                                         → "info"
+ *   - CODE_SHELL_LOG_LEVEL overrides everything.
+ *
+ * Category filter (--debug=mcp,api or CODE_SHELL_DEBUG=mcp,api):
+ *   When set, only debug logs whose `cat` matches are written.
+ *
+ * Disable entirely: CODE_SHELL_LOG=0
+ */
+import { appendFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, readFileSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { AsyncLocalStorage } from "node:async_hooks";
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function defaultLogsDir() {
+    return join(homedir(), ".code-shell", "logs");
+}
+// Mutable so non-CLI hosts (Electron renderer, headless containers, tests)
+// can redirect writes without touching every callsite. Reads go through
+// getLogsDir() so a single setLogsDir() call propagates everywhere.
+let _logsDir = null;
+function logsDir() {
+    return _logsDir ?? defaultLogsDir();
+}
+/**
+ * Override the directory log files are written into. Pass `null` to
+ * revert to the default `~/.code-shell/logs`. Affects all future writes
+ * AND `getLogsDir()` / `getRecentLogs()` reads, so call this before any
+ * log activity if you want a clean redirected stream.
+ */
+export function setLogsDir(dir) {
+    _logsDir = dir;
+}
+const MAX_LOG_FILES = 7;
+const MAX_IN_MEMORY_ERRORS = 100;
+/**
+ * Map a log entry's `cat` to a file bucket: "ui-ink" for UI/render logs,
+ * "engine" for everything else (engine, llm, tool, context, mcp, ...).
+ * Buckets are date-suffixed: ui-ink-2026-05-14.log / engine-2026-05-14.log.
+ *
+ * UI/ink lives in its own file because it's the chattiest (200ms spinner
+ * ticks, every stream event) and was drowning out engine traces. Keeping
+ * both date-suffixed lets one `grep "sid":"<id>"` over both files
+ * reconstruct a full session timeline if needed.
+ */
+const INK_CATS = new Set(["ui", "ink", "render", "stream"]);
+function routeBucket(cat, fallbackCat) {
+    const c = (cat ?? fallbackCat ?? "").toLowerCase();
+    if (INK_CATS.has(c))
+        return "ui-ink";
+    return "engine";
+}
+// ─── Local-dev detection ───────────────────────────────────────────
+function isLocalDev() {
+    if (process.env.CODE_SHELL_DEV === "1")
+        return true;
+    if (process.argv.includes("--debug") || process.argv.includes("-d"))
+        return true;
+    if (process.argv.some((a) => a.startsWith("--debug=")))
+        return true;
+    // Don't silently raise the level under tests — they have their own
+    // diagnostic story and shouldn't spam the daily log file.
+    if (process.env.NODE_ENV === "test" || process.env.BUN_TEST === "1")
+        return false;
+    if (process.argv.some((a) => a.includes("/tests/") || a.endsWith(".test.ts")))
+        return false;
+    // Running directly from src/ (bun run src/cli/main.ts) — not a packaged install.
+    const entry = process.argv[1] ?? "";
+    if (entry.includes(`${"/"}src${"/"}`))
+        return true;
+    return false;
+}
+function resolveDefaultLevel() {
+    const raw = process.env.CODE_SHELL_LOG_LEVEL?.toLowerCase().trim();
+    if (raw && Object.hasOwn(LEVEL_ORDER, raw))
+        return raw;
+    return isLocalDev() ? "debug" : "info";
+}
+// ─── Category filter (--debug=mcp,api) ─────────────────────────────
+function resolveCategoryFilter() {
+    // CLI: --debug=a,b
+    const cliArg = process.argv.find((a) => a.startsWith("--debug="));
+    let raw;
+    if (cliArg)
+        raw = cliArg.slice("--debug=".length);
+    // Env: CODE_SHELL_DEBUG=a,b (but "1" / "true" mean "all on", not a filter)
+    else {
+        const env = process.env.CODE_SHELL_DEBUG;
+        if (env && env !== "1" && env !== "true")
+            raw = env;
+    }
+    if (!raw)
+        return null;
+    const set = new Set(raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean));
+    return set.size > 0 ? set : null;
+}
+// ─── Session id resolution ─────────────────────────────────────────
+//
+// Two mechanisms, layered:
+//
+// 1. `runWithSid(sid, fn)` — preferred. Engine.run wraps its entire body
+//    in this AsyncLocalStorage scope, so every log line emitted inside the
+//    (possibly deeply async) call tree picks up the right sid. Concurrent
+//    parent + child Engines coexist because each `await` boundary preserves
+//    the ALS context — they don't trample each other like a single module
+//    global would.
+//
+// 2. `_currentSidFallback` — module-level mutable, written by `setCurrentSid`.
+//    Used only as a fallback when a code path runs outside any ALS scope
+//    (bootstrap, top-level CLI, sid-stamping for /sid command). Tools like
+//    `recordToolCall` reading `getCurrentSid()` inside an Engine.run will
+//    transparently get the ALS value first.
+//
+// Why both? Background sub-agents kick off detached via `void runSubAgent(...)`
+// — they're still inside the parent's ALS scope at spawn time and inherit
+// it correctly. But the *parent* Engine's later turns also need the parent
+// sid, which ALS gives us automatically (the parent's scope outlives the
+// child's). The module global is just a safety net for code that has no
+// scope, like the initial setup before any Engine has started.
+const _sidAls = new AsyncLocalStorage();
+let _currentSidFallback = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+export function setCurrentSid(sid) {
+    _currentSidFallback = sid;
+}
+export function getCurrentSid() {
+    return _sidAls.getStore() ?? _currentSidFallback;
+}
+/**
+ * Run `fn` inside an ALS scope tagged with `sid`. All log lines emitted
+ * synchronously or via `await` inside `fn` resolve `getCurrentSid()` to
+ * this `sid` — concurrent Engine.run invocations no longer race on a
+ * module global.
+ */
+export function runWithSid(sid, fn) {
+    return _sidAls.run(sid, fn);
+}
+/**
+ * Bind `sid` to the *current* async context without needing a callback.
+ * The binding lasts until the current async stack unwinds; concurrent
+ * sibling async chains keep their own bindings. Engine.run uses this so
+ * we don't have to indent the entire (long) method body into a callback.
+ */
+export function enterSid(sid) {
+    _sidAls.enterWith(sid);
+}
+// ─── In-memory error ring (for bug reports) ─────────────────────────
+const inMemoryErrors = [];
+export function getInMemoryErrors() {
+    return inMemoryErrors;
+}
+let errorLogSink = null;
+export function attachErrorLogSink(sink) {
+    if (errorLogSink !== null)
+        return;
+    errorLogSink = sink;
+}
+class Logger {
+    context;
+    enabled;
+    minLevel;
+    categoryFilter;
+    stderrEcho;
+    dirReady = false;
+    constructor(context = {}) {
+        this.context = context;
+        this.enabled = process.env.CODE_SHELL_LOG !== "0";
+        this.minLevel = resolveDefaultLevel();
+        this.categoryFilter = resolveCategoryFilter();
+        this.stderrEcho =
+            process.env.CODE_SHELL_DEBUG === "1" ||
+                process.argv.includes("--debug-to-stderr") ||
+                process.argv.includes("-d2e");
+    }
+    child(extra) {
+        return new Logger({ ...this.context, ...extra });
+    }
+    /**
+     * Set the session id stamped on every subsequent log entry written by
+     * any logger in the process. Called by Engine once a run's
+     * authoritative session id is known.
+     */
+    setSid(sid) {
+        setCurrentSid(sid);
+    }
+    getSid() {
+        return getCurrentSid();
+    }
+    debug(msg, data) {
+        this.write("debug", msg, data);
+    }
+    info(msg, data) {
+        this.write("info", msg, data);
+    }
+    warn(msg, data) {
+        this.write("warn", msg, data);
+    }
+    error(msgOrErr, data) {
+        let msg;
+        let entryData;
+        let errObj;
+        if (typeof msgOrErr === "string") {
+            msg = msgOrErr;
+            if (data instanceof Error) {
+                errObj = data;
+                entryData = { error: data.message, stack: data.stack };
+            }
+            else {
+                entryData = data;
+            }
+        }
+        else if (msgOrErr instanceof Error) {
+            msg = msgOrErr.message;
+            errObj = msgOrErr;
+            entryData = { stack: msgOrErr.stack };
+        }
+        else {
+            msg = String(msgOrErr);
+        }
+        this.recordError(msg, entryData);
+        this.write("error", msg, entryData);
+        if (errObj)
+            errorLogSink?.logError(errObj);
+    }
+    recordError(msg, data) {
+        if (inMemoryErrors.length >= MAX_IN_MEMORY_ERRORS)
+            inMemoryErrors.shift();
+        inMemoryErrors.push({ msg, t: new Date().toISOString(), data });
+    }
+    write(level, msg, data) {
+        if (!this.enabled)
+            return;
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[this.minLevel])
+            return;
+        const cat = data?.cat ?? this.context.cat;
+        // Category filter narrows the *debug* firehose only — info/warn/error
+        // always go through so a `--debug=mcp` invocation doesn't accidentally
+        // swallow unrelated errors.
+        if (level === "debug" && this.categoryFilter) {
+            if (!cat || !this.categoryFilter.has(cat.toLowerCase()))
+                return;
+        }
+        const t = new Date().toISOString();
+        const entry = { t, l: level, msg, ...this.context };
+        if (cat && !entry.cat)
+            entry.cat = cat;
+        // Stamp the current process-wide session id unless this logger's
+        // own context overrode it (rare). Doing it at write time means
+        // children created before Engine.run() still pick up the real sid.
+        if (entry.sid === undefined)
+            entry.sid = getCurrentSid();
+        if (data)
+            entry.d = data;
+        const line = JSON.stringify(entry) + "\n";
+        if (this.stderrEcho) {
+            process.stderr.write(line);
+            return;
+        }
+        try {
+            const dir = logsDir();
+            if (!this.dirReady) {
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                this.dirReady = true;
+            }
+            const dateStr = t.slice(0, 10);
+            // Route to per-area file. UI / ink events go to ui-ink-*.log so the
+            // engine log isn't drowned by 200ms spinner ticks and per-event traces.
+            // Everything else lands in engine-*.log (engine, turn-loop, llm, tool,
+            // context, mcp, sandbox, settings, ...). One-line grep across both with
+            // scripts/logs.sh.
+            const bucket = routeBucket(cat, this.context.cat);
+            const file = join(dir, `${bucket}-${dateStr}.log`);
+            appendFileSync(file, line, "utf-8");
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    getMinLevel() {
+        return this.minLevel;
+    }
+    isCategoryActive(cat) {
+        return !this.categoryFilter || this.categoryFilter.has(cat.toLowerCase());
+    }
+    /**
+     * Open a span: writes a `<name>.begin` debug entry now and returns a handle
+     * whose `end()` writes `<name>.end` with `duration_ms` populated. Use for
+     * any "I want begin → end + how long" pattern (tool exec, LLM request,
+     * permission ask, etc.) so the begin/end pair is grouped under one cat
+     * and the duration is computed once instead of by hand from timestamps.
+     */
+    span(name, data) {
+        const startedAt = Date.now();
+        this.write("debug", `${name}.begin`, data);
+        return {
+            end: (extra) => {
+                const duration_ms = Date.now() - startedAt;
+                this.write("info", `${name}.end`, { ...data, ...extra, duration_ms });
+            },
+            fail: (err, extra) => {
+                const duration_ms = Date.now() - startedAt;
+                const message = err instanceof Error ? err.message : String(err);
+                this.write("error", `${name}.fail`, { ...data, ...extra, duration_ms, error: message });
+            },
+        };
+    }
+}
+export const logger = new Logger();
+// ─── Maintenance helpers ───────────────────────────────────────────
+export function getLogsDir() {
+    return logsDir();
+}
+export function getRecentLogs(n = 50) {
+    const dateStr = new Date().toISOString().slice(0, 10);
+    const dir = logsDir();
+    // Merge across all buckets (engine + ui-ink) for the day, sort by
+    // timestamp so the tail represents a real chronological tail.
+    const all = [];
+    for (const bucket of ["engine", "ui-ink"]) {
+        const file = join(dir, `${bucket}-${dateStr}.log`);
+        if (!existsSync(file))
+            continue;
+        try {
+            for (const line of readFileSync(file, "utf-8").split("\n")) {
+                if (!line)
+                    continue;
+                // Cheap timestamp extraction: lines start with {"t":"<iso>",...
+                const m = line.match(/^\{"t":"([^"]+)"/);
+                all.push({ t: m?.[1] ?? "", line });
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    all.sort((a, b) => a.t.localeCompare(b.t));
+    return all.slice(-n).map((x) => x.line);
+}
+export function rotateLogs() {
+    try {
+        const dir = logsDir();
+        if (!existsSync(dir))
+            return;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith(".log"))
+            .sort();
+        if (files.length <= MAX_LOG_FILES)
+            return;
+        for (const f of files.slice(0, files.length - MAX_LOG_FILES)) {
+            try {
+                unlinkSync(join(dir, f));
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    catch {
+        // Best-effort.
+    }
+}
+/** @internal — for tests */
+export function _resetLoggerStateForTesting() {
+    inMemoryErrors.length = 0;
+    errorLogSink = null;
+}
+// dirname is exported only to satisfy unused-import rules if reorganized later.
+void dirname;