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

package/dist/run/RunManager.js

@@ -33,6 +33,17 @@ export class RunManager {
     abortControllers = new Map();
     /** Active execution handles — used to resolve pending approvals/input while Engine is suspended */
     executionHandles = new Map();
+    /**
+     * Runs with a resume()/cancel() decision currently being applied. Guards the
+     * approval/input resume race: resume() and cancel() each have multiple await
+     * points, and the status check at the top of resume() reads a value that
+     * stays `waiting_*` until a later `await transition()` lands. Two concurrent
+     * resumes (double-click approve), or resume racing cancel, would both pass
+     * that check and both drive transitions / resolve the handle. The handle's
+     * resolve is idempotent, but the duplicate transitions and (worse) the
+     * mismatched-input re-queue path are not. We serialize per-run here.
+     */
+    resolvingRuns = new Set();
     constructor(config) {
         this.store = config.store;
         this.queue = new RunQueue({ concurrency: config.concurrency ?? 1 });
@@ -99,6 +110,23 @@ export class RunManager {
     }
     // ─── Resume ────────────────────────────────────────────────────
     async resume(runId, input) {
+        // Serialize resume/cancel decisions per run. Without this, two concurrent
+        // resumes (or resume racing cancel) both pass the status check below —
+        // status stays `waiting_*` until a later `await transition()` — and both
+        // drive transitions / the re-queue path. Reject the late arrival rather
+        // than letting it double-resolve.
+        if (this.resolvingRuns.has(runId)) {
+            throw new Error(`Cannot resume run ${runId}: another resume/cancel is already in progress`);
+        }
+        this.resolvingRuns.add(runId);
+        try {
+            await this.resumeInner(runId, input);
+        }
+        finally {
+            this.resolvingRuns.delete(runId);
+        }
+    }
+    async resumeInner(runId, input) {
         const run = await this.getOrThrow(runId);
         if (run.status !== "waiting_input" &&
             run.status !== "waiting_approval" &&
@@ -137,6 +165,13 @@ export class RunManager {
                 handle.resolveInput(input.userInput);
                 return;
             }
+            // A handle exists (Engine is live and suspended) but the input doesn't
+            // match what it's waiting for — e.g. userInput supplied for a
+            // waiting_approval run. Falling through to Case 2 would re-enqueue a
+            // FRESH execution while the suspended Engine still dangles (duplicate
+            // run + leaked handle). Reject with a clear message instead.
+            throw new Error(`Cannot resume run ${runId}: it is ${run.status} but the provided input does not match ` +
+                `(expected ${run.status === "waiting_approval" ? "approvalDecision" : "userInput"}).`);
         }
         // Case 2: No active handle (process restarted, or blocked state)
         // Re-queue the run for a fresh execution attempt

package/dist/run/factory.d.ts

@@ -18,7 +18,7 @@
  * ```
  */
 import type { LLMConfig, PermissionMode } from "../types.js";
-import type { EngineConfig, EngineHookConfig } from "../engine/engine.js";
+import type { EngineConfig, EngineHookConfig } from "../engine/types.js";
 import type { Evaluator } from "./Evaluator.js";
 import { RunManager } from "./RunManager.js";
 export interface CreateRunManagerOptions {

package/dist/runtime/background-shell.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 type { SandboxBackend } from "../tool-system/sandbox/index.js";
+export type BgShellStatus = "starting" | "running" | "exited" | "killed" | "orphaned";
+/** Per-session soft cap on background shells (design §7 — fork-bomb guard). */
+export declare const MAX_SHELLS_PER_SESSION = 16;
+interface PidfileRecord {
+    shellId: string;
+    pgid: number;
+    command: string;
+    port?: number;
+    startedAt: number;
+    sessionId: string;
+}
+export interface BgShell {
+    shellId: string;
+    sessionId: string;
+    command: string;
+    cwd: string;
+    pgid: number;
+    status: BgShellStatus;
+    startedAt: number;
+    exitedAt?: number;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    detectedPort?: number;
+    /** Absolute stream position (RingFile.totalWritten) already returned to the
+     *  agent. Absolute — not window-relative — so it survives ring wraparound. */
+    agentReadOffset: number;
+    /** Total bytes the shell has written so far (monotonic, survives ring
+     *  wraparound). Lets the UI show live progress for long jobs like downloads
+     *  ("↑ 1.1 GB") even though the panel doesn't parse the output itself. */
+    totalBytes: number;
+    didWrap: boolean;
+    diskAvailable: boolean;
+}
+export interface SpawnBackgroundOptions {
+    command: string;
+    cwd: string;
+    sessionId: string;
+    shell?: string;
+    sandbox?: SandboxBackend;
+    /**
+     * Project `localEnvironment.env` to layer on top of the base shell env
+     * (see mergeShellEnv). Same source as the foreground Bash tool's
+     * `ctx.shellEnv` — passed through so a background dev server sees the same
+     * project env as a one-shot command.
+     */
+    shellEnv?: Record<string, string>;
+}
+export type SpawnResult = {
+    ok: true;
+    shellId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type ReadResult = {
+    ok: true;
+    text: string;
+    header: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type KillResult = {
+    ok: true;
+    alreadyExited?: boolean;
+    status: BgShellStatus;
+} | {
+    ok: false;
+    error: string;
+};
+export declare class BackgroundShellManager {
+    private shells;
+    spawnBackground(opts: SpawnBackgroundOptions): SpawnResult;
+    private finalize;
+    private enqueueExitNotification;
+    private updatePidfilePort;
+    get(shellId: string): BgShell | undefined;
+    /** Raw retained output (no cleaning) — test/UI helper. */
+    readOutputRaw(shellId: string): string | undefined;
+    listForSession(sessionId: string): BgShell[];
+    /**
+     * 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: string, mode?: "incremental" | "all", expectSessionId?: string): ReadResult;
+    /**
+     * 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).
+     */
+    private buildHeader;
+    /** Terminate a shell (its whole process group). Idempotent. */
+    kill(shellId: string, expectSessionId?: string): Promise<KillResult>;
+    /** Kill every background shell belonging to `sessionId`. */
+    killSession(sessionId: string): Promise<void>;
+    /** Kill every background shell (app/worker exit). */
+    killAll(): Promise<void>;
+    /**
+     * 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(): PidfileRecord[];
+    private registerOrphan;
+    /** Test/reset helper — clears the registry without killing (used in tests). */
+    _clear(): void;
+    private toPublic;
+}
+/** Process-local singleton, mirroring asyncAgentRegistry's lifetime contract. */
+export declare const backgroundShellManager: BackgroundShellManager;
+export {};