@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.2

package/dist/runtime/background-shell.js

@@ -0,0 +1,495 @@
+/**
+ * BackgroundShellManager — session-scoped registry + lifecycle for
+ * fire-and-forget background shells (design §4).
+ *
+ * A background shell is a long-lived process (typically `npm run dev`)
+ * started via `Bash(run_in_background=true)`. Unlike the foreground Bash
+ * path (which awaits the command to completion), this:
+ *
+ *   - spawns the command **detached** so it owns its own process group
+ *     (so KillShell can reap the whole `sh → npm → node vite` tree, §难点2);
+ *   - returns a `shell_id` immediately, never blocking the turn;
+ *   - streams output to an in-memory ring buffer + a wrap-around disk file,
+ *     stripping ANSI/progress noise only when handed to the agent (§难点4);
+ *   - detects a served port best-effort from the output (§难点3);
+ *   - is **completely separate** from `asyncAgentRegistry` so Engine.run's
+ *     wait-for-background loop never waits on a dev server (§难点5);
+ *   - on exit, enqueues a one-line completion notification (no output body,
+ *     §难点6 / D6) keyed by sessionId.
+ *
+ * Lifetime is process-local and session-scoped: `killSession(sid)` on
+ * explicit session deletion, `killAll()` on app/worker exit. Crashing the
+ * worker leaks the detached children as orphans — pidfiles let a restarted
+ * worker discover and reap them (§难点1, `reapOrphansFromPidfiles`).
+ */
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, writeFileSync, rmSync, existsSync, readdirSync, readFileSync, } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { utf8SafeCutLength } from "./utf8-cut.js";
+import { resolveSpawnTarget, buildSandboxEnv, mergeShellEnv, killProcessGroup, groupAlive, defaultShellBinary } from "./spawn-common.js";
+import { RingFile } from "./ring-file.js";
+import { cleanOutput } from "./output-clean.js";
+import { notificationQueue } from "../tool-system/builtin/agent-notifications.js";
+import { logger } from "../logging/logger.js";
+/** Per-session soft cap on background shells (design §7 — fork-bomb guard). */
+export const MAX_SHELLS_PER_SESSION = 16;
+/** Disk ring-file cap: keep the most recent 8MB of raw output (design §6). */
+const DISK_CAP_BYTES = 8 * 1024 * 1024;
+/** BashOutput single-return cap (strip后尾部 ~16KB) so one read can't blow context. */
+const READ_RETURN_CAP = 16 * 1024;
+const KILL_GRACE_MS = 3000;
+let shellCounter = 0;
+function nextShellId() {
+    shellCounter += 1;
+    // Short, collision-resistant enough within a process: counter + base36 of
+    // a monotonic-ish value. Avoids Date.now()/Math.random() (banned in some
+    // contexts and unnecessary here).
+    return `bg_${shellCounter.toString(36)}${(shellCounter * 2654435761 % 0xffffff).toString(36)}`;
+}
+function bgShellsRoot() {
+    const base = process.env.CODE_SHELL_HOME ?? process.env.HOME ?? homedir();
+    return join(base, ".code-shell", "bg-shells");
+}
+const PORT_REGEXES = [
+    /localhost:(\d{2,5})/i,
+    /127\.0\.0\.1:(\d{2,5})/,
+    /0\.0\.0\.0:(\d{2,5})/,
+    /:(\d{4,5})\b/,
+];
+function detectPort(text) {
+    for (const re of PORT_REGEXES) {
+        const m = re.exec(text);
+        if (m) {
+            const p = Number(m[1]);
+            if (p >= 1 && p <= 65535)
+                return p;
+        }
+    }
+    return undefined;
+}
+export class BackgroundShellManager {
+    shells = new Map();
+    spawnBackground(opts) {
+        // Defense-in-depth: sessionId becomes a directory under bgShellsRoot()
+        // (`join(root, sessionId)`, below). It's engine-generated/validated today,
+        // but a `..`/separator/empty id would write the shell log + record OUTSIDE
+        // the bg-shells root — refuse rather than trust the caller. Mirrors
+        // SessionManager.assertSafeSessionId without importing across the layer.
+        const sid = opts.sessionId;
+        if (typeof sid !== "string" || sid.length === 0 || sid.includes("..") || sid.includes("/") || sid.includes("\\")) {
+            return { ok: false, error: `invalid sessionId for background shell` };
+        }
+        // Per-session soft cap (fork-bomb guard, §7).
+        const live = [...this.shells.values()].filter((s) => s.sessionId === opts.sessionId && (s.status === "running" || s.status === "starting"));
+        if (live.length >= MAX_SHELLS_PER_SESSION) {
+            return {
+                ok: false,
+                error: `Too many background shells for this session (max ${MAX_SHELLS_PER_SESSION}). KillShell some first.`,
+            };
+        }
+        const shell = opts.shell ?? defaultShellBinary();
+        const { file, args } = resolveSpawnTarget(opts.command, {
+            cwd: opts.cwd,
+            shell,
+            sandbox: opts.sandbox,
+        });
+        const baseEnv = opts.sandbox && opts.sandbox.name !== "off" ? buildSandboxEnv() : { ...process.env };
+        const env = mergeShellEnv(baseEnv, opts.shellEnv);
+        let child;
+        try {
+            child = spawn(file, args, {
+                cwd: opts.cwd,
+                env,
+                // POSIX: detached → own process group so a negative-pid signal reaps
+                // the whole tree (npm → node → vite). Windows has no process groups;
+                // detached there spawns a separate console window instead, so we keep
+                // it attached and rely on `taskkill /T` (killProcessGroup's win32
+                // branch) to reap the tree. windowsHide stops a console flashing up.
+                detached: process.platform !== "win32",
+                windowsHide: true,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            return { ok: false, error: `Failed to spawn background shell: ${err.message}` };
+        }
+        if (child.pid === undefined) {
+            return { ok: false, error: "Failed to spawn background shell: no pid" };
+        }
+        const shellId = nextShellId();
+        const pgid = child.pid; // detached ⇒ pgid == pid
+        const dir = join(bgShellsRoot(), opts.sessionId);
+        const pidfilePath = join(dir, `${shellId}.json`);
+        const logPath = join(dir, `${shellId}.log`);
+        let ring;
+        try {
+            mkdirSync(dir, { recursive: true });
+            ring = new RingFile(logPath, DISK_CAP_BYTES);
+        }
+        catch {
+            // Disk unavailable — degrade to a memory-only ring at a temp-less path.
+            ring = new RingFile(join(dir, `${shellId}.log`), DISK_CAP_BYTES);
+        }
+        const startedAt = Date.now();
+        const rec = {
+            shellId,
+            pgid,
+            command: opts.command,
+            startedAt,
+            sessionId: opts.sessionId,
+        };
+        try {
+            writeFileSync(pidfilePath, JSON.stringify(rec), "utf8");
+        }
+        catch {
+            /* pidfile is best-effort; orphan reaping just won't see this one */
+        }
+        const sh = {
+            shellId,
+            sessionId: opts.sessionId,
+            command: opts.command,
+            cwd: opts.cwd,
+            pgid,
+            status: "running",
+            startedAt,
+            exitCode: null,
+            signal: null,
+            agentReadOffset: 0,
+            didWrap: false,
+            diskAvailable: ring.diskAvailable(),
+            child,
+            ring,
+            pidfilePath,
+            stdoutDec: new StringDecoder("utf-8"),
+            stderrDec: new StringDecoder("utf-8"),
+            portScanBuf: "",
+        };
+        this.shells.set(shellId, sh);
+        const onData = (chunk) => {
+            sh.ring.write(chunk);
+            sh.didWrap = sh.ring.didWrap();
+            if (sh.detectedPort === undefined) {
+                // Scan a bounded recent window of decoded text for a port.
+                sh.portScanBuf = (sh.portScanBuf + chunk.toString("utf8")).slice(-4096);
+                const p = detectPort(sh.portScanBuf);
+                if (p !== undefined) {
+                    sh.detectedPort = p;
+                    this.updatePidfilePort(sh, p);
+                }
+            }
+        };
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.on("error", (err) => {
+            logger.warn("bg_shell.child_error", { shellId, error: err.message });
+        });
+        child.on("exit", (code, sig) => {
+            // Only natural exits land here as "exited"; kill() sets "killed" first.
+            if (sh.status === "killed") {
+                this.finalize(sh, code, sig);
+                return;
+            }
+            sh.status = "exited";
+            this.finalize(sh, code, sig);
+            this.enqueueExitNotification(sh);
+        });
+        return { ok: true, shellId };
+    }
+    finalize(sh, code, sig) {
+        sh.exitCode = code;
+        sh.signal = sig;
+        sh.exitedAt = Date.now();
+        sh.child = null;
+        try {
+            sh.ring.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            rmSync(sh.pidfilePath, { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    enqueueExitNotification(sh) {
+        const ok = sh.exitCode === 0;
+        const exitDesc = sh.signal
+            ? `signal ${sh.signal}`
+            : `exit ${sh.exitCode ?? "?"}`;
+        notificationQueue.enqueue({
+            agentId: sh.shellId,
+            // English description is the agent-facing wakeup text. The UI ignores
+            // it for the toast and uses workKind + command to build a localized
+            // label (see bgCompletionText in desktop renderer types.ts). No `name`
+            // so legacy UIs fall back to their own default rather than showing the
+            // English "background shell" brand string.
+            description: `Background shell exited (${exitDesc}): ${sh.command}`,
+            status: ok ? "completed" : "failed",
+            workKind: "shell",
+            command: sh.command,
+            error: ok ? undefined : `Background shell ${sh.shellId} exited with ${exitDesc}. Use BashOutput("${sh.shellId}") to inspect.`,
+            enqueuedAt: Date.now(),
+        }, sh.sessionId);
+    }
+    updatePidfilePort(sh, port) {
+        try {
+            const rec = {
+                shellId: sh.shellId,
+                pgid: sh.pgid,
+                command: sh.command,
+                port,
+                startedAt: sh.startedAt,
+                sessionId: sh.sessionId,
+            };
+            writeFileSync(sh.pidfilePath, JSON.stringify(rec), "utf8");
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    get(shellId) {
+        const sh = this.shells.get(shellId);
+        return sh ? this.toPublic(sh) : undefined;
+    }
+    /** Raw retained output (no cleaning) — test/UI helper. */
+    readOutputRaw(shellId) {
+        return this.shells.get(shellId)?.ring.readAll();
+    }
+    listForSession(sessionId) {
+        return [...this.shells.values()]
+            .filter((s) => s.sessionId === sessionId)
+            .map((s) => this.toPublic(s));
+    }
+    /**
+     * Read a shell's output. `mode=incremental` (default) returns text since the
+     * agent's last read; `mode=all` returns the full retained buffer. Output is
+     * ANSI-stripped and progress-folded, capped at the last READ_RETURN_CAP
+     * chars. `expectSessionId`, when given, enforces session ownership.
+     */
+    readOutput(shellId, mode = "incremental", expectSessionId) {
+        const sh = this.shells.get(shellId);
+        if (!sh)
+            return { ok: false, error: `Unknown shell_id: ${shellId}` };
+        if (expectSessionId !== undefined && sh.sessionId !== expectSessionId) {
+            return { ok: false, error: `Unknown shell_id: ${shellId}` };
+        }
+        let rawSlice;
+        let capped = false;
+        if (mode === "all") {
+            // Snapshot of the full retained buffer. This is explicitly a "show me the
+            // tail" view — when it exceeds the cap we keep the LAST 16KB (most recent
+            // output) and don't touch the incremental cursor.
+            rawSlice = sh.ring.readAll();
+            let text = cleanOutput(rawSlice);
+            if (text.length > READ_RETURN_CAP) {
+                text = text.slice(-READ_RETURN_CAP);
+                capped = true;
+            }
+            return { ok: true, text, header: this.buildHeader(sh, capped, "all") };
+        }
+        // Incremental: deliver bytes since the agent's last read WITHOUT dropping
+        // any. A single burst larger than the cap is paginated across successive
+        // reads — we consume only the leading READ_RETURN_CAP *raw* bytes this call
+        // and advance the absolute cursor by exactly that many, so the remainder is
+        // returned next read. (Truncating to the trailing 16KB while advancing the
+        // cursor to the end silently dropped the earliest bytes forever — #5.)
+        //
+        // Absolute stream cursor — survives ring wraparound (a window-relative
+        // offset would silently skip new bytes once the window slides).
+        const sliceBuf = sh.ring.sliceFromAbsolute(sh.agentReadOffset);
+        let consumedBytes = sliceBuf.length;
+        let rawBuf = sliceBuf;
+        if (rawBuf.length > READ_RETURN_CAP) {
+            // Cap on RAW bytes (not cleaned length): cleanOutput only ever shrinks,
+            // so the cleaned result of the first 16KB raw bytes is itself ≤ 16KB and
+            // won't need a second truncation. Advancing the cursor by exactly
+            // consumedBytes keeps the next read seamless.
+            // Back the cut off to the last complete UTF-8 char boundary so a
+            // multibyte char straddling the 16KB line isn't split into a `�` — and
+            // so consumedBytes lands on a boundary and the next read resumes cleanly.
+            // Guard against a pathological 0 (buffer starting mid-char) to guarantee
+            // forward progress.
+            const safeCut = utf8SafeCutLength(rawBuf, READ_RETURN_CAP) || READ_RETURN_CAP;
+            rawBuf = rawBuf.subarray(0, safeCut);
+            consumedBytes = safeCut;
+            capped = true;
+        }
+        rawSlice = rawBuf.toString("utf8");
+        sh.agentReadOffset += consumedBytes;
+        const text = cleanOutput(rawSlice);
+        return { ok: true, text, header: this.buildHeader(sh, capped, "incremental") };
+    }
+    /**
+     * Build the status header line for a readOutput result. `mode` shapes the cap
+     * note: `all` keeps the trailing 16KB (older output omitted from THIS view),
+     * while incremental paginates (more output available on the next read).
+     */
+    buildHeader(sh, capped, mode) {
+        const portPart = sh.detectedPort !== undefined ? ` port=${sh.detectedPort}` : "";
+        const exitPart = sh.status === "exited" || sh.status === "killed"
+            ? sh.signal
+                ? ` signal=${sh.signal}`
+                : ` exit=${sh.exitCode ?? "?"}`
+            : "";
+        const wrapNote = sh.didWrap ? " (older output discarded)" : "";
+        const capNote = capped
+            ? mode === "all"
+                ? " (showing last 16KB)"
+                : " (16KB this read; call again for more)"
+            : "";
+        const diskNote = sh.diskAvailable ? "" : " (disk buffer unavailable)";
+        return `[${sh.shellId} status=${sh.status}${portPart}${exitPart}]${wrapNote}${capNote}${diskNote}`;
+    }
+    /** Terminate a shell (its whole process group). Idempotent. */
+    async kill(shellId, expectSessionId) {
+        const sh = this.shells.get(shellId);
+        if (!sh)
+            return { ok: false, error: `Unknown shell_id: ${shellId}` };
+        if (expectSessionId !== undefined && sh.sessionId !== expectSessionId) {
+            return { ok: false, error: `Unknown shell_id: ${shellId}` };
+        }
+        if (sh.status === "exited" || sh.status === "killed") {
+            return { ok: true, alreadyExited: true, status: sh.status };
+        }
+        sh.status = "killed";
+        await killProcessGroup(sh.pgid, { graceMs: KILL_GRACE_MS });
+        // The 'exit' handler runs finalize(); if the child already detached/died
+        // without firing it, finalize defensively.
+        if (sh.exitedAt === undefined) {
+            this.finalize(sh, sh.exitCode, sh.signal);
+        }
+        return { ok: true, status: "killed" };
+    }
+    /** Kill every background shell belonging to `sessionId`. */
+    async killSession(sessionId) {
+        const ids = [...this.shells.values()]
+            .filter((s) => s.sessionId === sessionId && (s.status === "running" || s.status === "starting"))
+            .map((s) => s.shellId);
+        await Promise.all(ids.map((id) => this.kill(id)));
+    }
+    /** Kill every background shell (app/worker exit). */
+    async killAll() {
+        const ids = [...this.shells.values()]
+            .filter((s) => s.status === "running" || s.status === "starting")
+            .map((s) => s.shellId);
+        await Promise.all(ids.map((id) => this.kill(id)));
+    }
+    /**
+     * Scan pidfiles left by a previous (crashed) worker. For each: if the pgid
+     * is still alive it's an orphan (the dev server outlived its worker) — list
+     * it as `orphaned` so KillShell can clean it up; if dead, delete the stale
+     * pidfile. Returns the orphaned records found.
+     */
+    reapOrphansFromPidfiles() {
+        const root = bgShellsRoot();
+        if (!existsSync(root))
+            return [];
+        const orphans = [];
+        let sessionDirs;
+        try {
+            sessionDirs = readdirSync(root);
+        }
+        catch {
+            return [];
+        }
+        for (const sid of sessionDirs) {
+            const dir = join(root, sid);
+            let files;
+            try {
+                files = readdirSync(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const f of files) {
+                if (!f.endsWith(".json"))
+                    continue;
+                const path = join(dir, f);
+                let rec;
+                try {
+                    rec = JSON.parse(readFileSync(path, "utf8"));
+                }
+                catch {
+                    try {
+                        rmSync(path, { force: true });
+                    }
+                    catch { /* ignore */ }
+                    continue;
+                }
+                // Skip ones we already track in-process (this worker's own).
+                if (this.shells.has(rec.shellId))
+                    continue;
+                if (groupAlive(rec.pgid)) {
+                    orphans.push(rec);
+                    this.registerOrphan(rec, path);
+                }
+                else {
+                    try {
+                        rmSync(path, { force: true });
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+        return orphans;
+    }
+    registerOrphan(rec, pidfilePath) {
+        // A minimal entry: we have no live child/ring (different process), but
+        // ListShells should show it and KillShell should be able to reap it.
+        const sh = {
+            shellId: rec.shellId,
+            sessionId: rec.sessionId,
+            command: rec.command,
+            cwd: "",
+            pgid: rec.pgid,
+            status: "orphaned",
+            startedAt: rec.startedAt,
+            exitCode: null,
+            signal: null,
+            detectedPort: rec.port,
+            agentReadOffset: 0,
+            didWrap: false,
+            diskAvailable: false,
+            child: null,
+            // Read the orphan's ALREADY-captured output from its on-disk .log (the
+            // live process in the other worker owns/writes it). Opening it read-only
+            // surfaces the real tail instead of a fresh EMPTY .orphan ring that made
+            // a recovered shell always show "(无输出)". (#7)
+            ring: new RingFile(join(bgShellsRoot(), rec.sessionId, `${rec.shellId}.log`), DISK_CAP_BYTES, true),
+            pidfilePath,
+            stdoutDec: new StringDecoder("utf-8"),
+            stderrDec: new StringDecoder("utf-8"),
+            portScanBuf: "",
+        };
+        this.shells.set(rec.shellId, sh);
+    }
+    /** Test/reset helper — clears the registry without killing (used in tests). */
+    _clear() {
+        this.shells.clear();
+    }
+    toPublic(s) {
+        return {
+            shellId: s.shellId,
+            sessionId: s.sessionId,
+            command: s.command,
+            cwd: s.cwd,
+            pgid: s.pgid,
+            status: s.status,
+            startedAt: s.startedAt,
+            exitedAt: s.exitedAt,
+            exitCode: s.exitCode,
+            signal: s.signal,
+            detectedPort: s.detectedPort,
+            agentReadOffset: s.agentReadOffset,
+            totalBytes: s.ring.totalWritten(),
+            didWrap: s.didWrap,
+            diskAvailable: s.diskAvailable,
+        };
+    }
+}
+/** Process-local singleton, mirroring asyncAgentRegistry's lifetime contract. */
+export const backgroundShellManager = new BackgroundShellManager();

package/dist/runtime/output-clean.d.ts

@@ -0,0 +1,24 @@
+/**
+ * output-clean — sanitize raw process output before it's handed to the LLM.
+ *
+ * Background dev servers (`npm run dev`, vite, webpack) emit two kinds of
+ * noise that are worthless — and token-expensive — in a model's context
+ * (design §难点4):
+ *
+ *   - ANSI escape sequences (colors, cursor moves, line erases).
+ *   - `\r`-driven progress redraws (`▕███░ 45%\r▕████ 100%`) where every
+ *     frame but the last is stale.
+ *
+ * The *raw* bytes are still persisted to disk untouched (so a user `tail`ing
+ * the file keeps colors); this cleanup only applies to what `BashOutput`
+ * returns to the agent.
+ */
+export declare function stripAnsi(s: string): string;
+/**
+ * Collapse carriage-return progress redraws. Within a single line (text
+ * between `\n`s), `\r` means "redraw from column 0" — only the segment after
+ * the last `\r` survives. Newlines are preserved as line separators.
+ */
+export declare function foldProgressLines(s: string): string;
+/** Strip ANSI then fold progress frames — the full agent-facing cleanup. */
+export declare function cleanOutput(s: string): string;

package/dist/runtime/output-clean.js

@@ -0,0 +1,41 @@
+/**
+ * output-clean — sanitize raw process output before it's handed to the LLM.
+ *
+ * Background dev servers (`npm run dev`, vite, webpack) emit two kinds of
+ * noise that are worthless — and token-expensive — in a model's context
+ * (design §难点4):
+ *
+ *   - ANSI escape sequences (colors, cursor moves, line erases).
+ *   - `\r`-driven progress redraws (`▕███░ 45%\r▕████ 100%`) where every
+ *     frame but the last is stale.
+ *
+ * The *raw* bytes are still persisted to disk untouched (so a user `tail`ing
+ * the file keeps colors); this cleanup only applies to what `BashOutput`
+ * returns to the agent.
+ */
+// Matches CSI sequences (ESC [ ... final-byte) plus a few common non-CSI
+// escapes (ESC ] OSC, single-char escapes). Good enough for dev-server output;
+// we deliberately don't pull in a full terminal parser.
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /[›][[\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-ntqry=><~]/g;
+export function stripAnsi(s) {
+    return s.replace(ANSI_REGEX, "");
+}
+/**
+ * Collapse carriage-return progress redraws. Within a single line (text
+ * between `\n`s), `\r` means "redraw from column 0" — only the segment after
+ * the last `\r` survives. Newlines are preserved as line separators.
+ */
+export function foldProgressLines(s) {
+    return s
+        .split("\n")
+        .map((line) => {
+        const lastCr = line.lastIndexOf("\r");
+        return lastCr === -1 ? line : line.slice(lastCr + 1);
+    })
+        .join("\n");
+}
+/** Strip ANSI then fold progress frames — the full agent-facing cleanup. */
+export function cleanOutput(s) {
+    return foldProgressLines(stripAnsi(s));
+}

package/dist/runtime/ring-file.d.ts

@@ -0,0 +1,64 @@
+/**
+ * RingFile — a bounded, wrap-around output sink for a background shell's
+ * stdout/stderr (design §6 "落盘 8MB 环绕覆盖").
+ *
+ * Semantics: the logical stream is unbounded, but only the **last N bytes**
+ * are retained. When the stream exceeds the cap, the oldest bytes are
+ * dropped (`didWrap()` flips true). A dev server's startup banner is
+ * disposable; the recent tail is what the agent/user wants.
+ *
+ * Implementation: an in-memory tail Buffer is authoritative (so `readAll`
+ * and the manager's offset math never touch disk), mirrored to a file so a
+ * user can `tail`/open it with external tools. The disk mirror is
+ * best-effort — if the path is unwritable the in-memory buffer still works
+ * and the manager degrades to memory-only (design §7).
+ *
+ * The on-disk file holds the same retained tail as memory (rewritten on
+ * wrap, appended otherwise). We accept the cost of an occasional full
+ * rewrite on wrap; for line-oriented dev output at the 8MB cap this is rare
+ * and cheap relative to the process's own work.
+ */
+export declare class RingFile {
+    private readonly path;
+    private readonly capBytes;
+    private buf;
+    private wrapped;
+    private fd;
+    private diskOk;
+    private readonlyMode;
+    /** Total bytes ever written to the logical stream (monotonic, NOT capped).
+     *  The retained window is the last `min(total, cap)` of these. Readers track
+     *  an ABSOLUTE position in this stream so incremental reads survive
+     *  wraparound (a window-relative offset would silently skip new data once
+     *  the window starts sliding). */
+    private total;
+    constructor(path: string, capBytes: number, 
+    /** Read-only: load the EXISTING file's tail into memory and never truncate
+     *  or write. Used to surface a recovered orphan shell's already-captured
+     *  output (the live process owns the .log in another worker). */
+    readonlyExisting?: boolean);
+    /** True if the disk mirror is usable (false → memory-only degraded mode). */
+    diskAvailable(): boolean;
+    write(chunk: Buffer): void;
+    /** Whether any bytes have been discarded by wraparound. */
+    didWrap(): boolean;
+    /** The retained tail, decoded as UTF-8. */
+    readAll(): string;
+    /** Current retained byte length (for the agent read offset math). */
+    byteLength(): number;
+    /** Bytes from `offset` (within the retained window) to the end. */
+    sliceFrom(offset: number): Buffer;
+    /** Total bytes ever written to the logical stream (monotonic). Readers use
+     *  this as their next cursor after a read. */
+    totalWritten(): number;
+    /**
+     * Bytes from an ABSOLUTE stream position to the current end. `absOffset` is
+     * a value previously returned by {@link totalWritten}. If it points before
+     * the retained window (the bytes were discarded by wraparound), returns the
+     * whole window. If it's at/after the end, returns empty.
+     */
+    sliceFromAbsolute(absOffset: number): Buffer;
+    close(): void;
+    private appendToDisk;
+    private rewriteDisk;
+}