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

package/dist/tool-system/builtin/apply-patch/applier.js

@@ -10,9 +10,10 @@
 // Algorithm uses code adapted from codex-rs/apply-patch/src/lib.rs (Apache-2.0)
 // for the chunk-replacement phase (compute_replacements, apply_replacements).
 import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { seekSequence } from "./seek-sequence.js";
+import { detectEol, toLf, applyEol } from "../eol.js";
 /**
  * Plan and commit the patch atomically.
  *
@@ -76,8 +77,15 @@ async function planHunks(hunks, cwd) {
         if (!stats) {
             throw new Error(`Failed to update file: ${sourcePath} does not exist`);
         }
-        const originalText = await readFile(sourcePath, "utf-8");
-        const newText = applyChunksToText(originalText, hunk.chunks, sourcePath);
+        const originalRaw = await readFile(sourcePath, "utf-8");
+        // CRLF handling: patch context lines are LF (the model emits LF). Match in
+        // LF space, then write back in the file's original EOL so a CRLF file isn't
+        // silently converted to LF (which would diff the whole file). originalText
+        // (LF) is what we compare; originalRaw is preserved for rollback so a
+        // restore writes back the exact bytes. See eol.ts.
+        const eol = detectEol(originalRaw);
+        const originalText = toLf(originalRaw);
+        const newText = applyEol(applyChunksToText(originalText, hunk.chunks, sourcePath), eol);
         if (hunk.movePath !== undefined) {
             const destPath = resolveAgainst(hunk.movePath, cwd);
             if (destPath === sourcePath) {
@@ -85,7 +93,7 @@ async function planHunks(hunks, cwd) {
                 schedule(sourcePath, {
                     path: sourcePath,
                     newContent: newText,
-                    originalContent: originalText,
+                    originalContent: originalRaw,
                 });
             }
             else {
@@ -93,7 +101,7 @@ async function planHunks(hunks, cwd) {
                 schedule(sourcePath, {
                     path: sourcePath,
                     newContent: null,
-                    originalContent: originalText,
+                    originalContent: originalRaw,
                 });
                 schedule(destPath, {
                     path: destPath,
@@ -107,7 +115,7 @@ async function planHunks(hunks, cwd) {
             schedule(sourcePath, {
                 path: sourcePath,
                 newContent: newText,
-                originalContent: originalText,
+                originalContent: originalRaw,
             });
             set.modified.push(original);
         }
@@ -229,8 +237,58 @@ async function writeChange(change) {
     await writeFile(change.path, change.newContent, "utf-8");
 }
 // ─── helpers ──────────────────────────────────────────────────────
+/**
+ * Resolve a patch-relative (or absolute) path against cwd, then HARD-ENFORCE
+ * that the result stays inside cwd.
+ *
+ * This is the applier's own containment guard, independent of the executor-level
+ * pathPolicy. apply-patch is reachable with the path gate bypassed (e.g.
+ * bypassPermissions, or a direct call), so the last line of defense lives here.
+ *
+ * Containment is checked against the REAL paths: we realpath cwd and walk the
+ * target up to its nearest existing ancestor and realpath that. This defeats a
+ * symlink planted inside cwd that points outside — a plain string `resolve()`
+ * would look contained while the write follows the link out.
+ */
 function resolveAgainst(p, cwd) {
-    return isAbsolute(p) ? p : resolve(cwd, p);
+    const resolved = isAbsolute(p) ? p : resolve(cwd, p);
+    const realCwd = nearestRealPath(cwd);
+    const realTarget = nearestRealPath(resolved);
+    if (!isInside(realTarget, realCwd)) {
+        throw new Error(`Refusing to apply patch outside the working directory: "${p}" resolves to "${realTarget}", which escapes "${realCwd}".`);
+    }
+    return resolved;
+}
+/**
+ * Realpath the nearest existing ancestor of `abs`, then re-attach the
+ * not-yet-existing trailing segments. Mirrors path-policy.safeRealpath so
+ * symlinked ancestors are resolved even when the leaf doesn't exist yet.
+ */
+function nearestRealPath(abs) {
+    let candidate = abs;
+    const segments = [];
+    for (let i = 0; i < 64; i++) {
+        try {
+            const real = realpathSync(candidate);
+            if (segments.length === 0)
+                return real;
+            return resolve(real, ...segments.reverse());
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return abs;
+            segments.push(candidate.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
+            candidate = parent;
+        }
+    }
+    return abs;
+}
+function isInside(child, parent) {
+    if (child === parent)
+        return true;
+    const p = parent.endsWith(sep) ? parent : parent + sep;
+    return child.startsWith(p);
 }
 async function safeStat(path) {
     try {

package/dist/tool-system/builtin/apply-patch/backup-targets.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Which files an ApplyPatch would modify-in-place or delete — i.e. the files
+ * that already exist and therefore have pre-patch content worth snapshotting
+ * for /undo. Pure (parse-only, no fs): given the patch text and the cwd to
+ * resolve relative paths against, return absolute target paths.
+ *
+ * "add" hunks are excluded: a newly-created file has no prior content to back
+ * up (undo of an add = delete, handled separately if/when /undo grows that).
+ */
+export declare function patchBackupTargets(patchText: string, cwd: string): string[];

package/dist/tool-system/builtin/apply-patch/backup-targets.js

@@ -0,0 +1,30 @@
+/**
+ * Which files an ApplyPatch would modify-in-place or delete — i.e. the files
+ * that already exist and therefore have pre-patch content worth snapshotting
+ * for /undo. Pure (parse-only, no fs): given the patch text and the cwd to
+ * resolve relative paths against, return absolute target paths.
+ *
+ * "add" hunks are excluded: a newly-created file has no prior content to back
+ * up (undo of an add = delete, handled separately if/when /undo grows that).
+ */
+import { resolve as resolvePath } from "node:path";
+import { parsePatch } from "./parser.js";
+export function patchBackupTargets(patchText, cwd) {
+    let parsed;
+    try {
+        parsed = parsePatch(patchText, "lenient");
+    }
+    catch {
+        // Unparseable patch → nothing to back up; the tool itself will reject it.
+        return [];
+    }
+    const out = [];
+    for (const hunk of parsed.hunks) {
+        if (hunk.kind === "update" || hunk.kind === "delete") {
+            out.push(resolvePath(cwd, hunk.path));
+        }
+    }
+    // De-dupe while preserving order (a patch shouldn't target one file twice,
+    // but be defensive — saveSnapshot is idempotent on identical content anyway).
+    return [...new Set(out)];
+}

package/dist/tool-system/builtin/apply-patch/index.js

@@ -17,7 +17,6 @@
 import { fileCache } from "../file-cache.js";
 import { applyPatch } from "./applier.js";
 import { parsePatch } from "./parser.js";
-import { enforcePathPolicy } from "../../path-policy.js";
 import { resolve as resolvePath } from "node:path";
 export const applyPatchToolDef = {
     name: "ApplyPatch",
@@ -70,20 +69,6 @@ export async function applyPatchTool(args, ctx) {
     // A4: resolve relative patch paths against the Engine's cwd, not the
     // host process cwd. See standard §S5.
     const cwd = ctx?.cwd ?? process.cwd();
-    // Path-policy gate every target before any IO. A multi-file patch is
-    // atomic — if *any* target is blocked the whole patch must reject so we
-    // don't end up writing some files and refusing others.
-    for (const hunk of parsed.hunks) {
-        const targets = [resolvePath(cwd, hunk.path)];
-        if (hunk.kind === "update" && hunk.movePath) {
-            targets.push(resolvePath(cwd, hunk.movePath));
-        }
-        for (const t of targets) {
-            const blocked = enforcePathPolicy(t, "write", cwd);
-            if (blocked)
-                return blocked;
-        }
-    }
     let result;
     try {
         result = await applyPatch(parsed.hunks, { cwd });

package/dist/tool-system/builtin/background-jobs.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Registry of NON-agent background jobs (GenerateVideo poll loops, DriveAgent
+ * external CLI runs). Mirrors the role `asyncAgentRegistry` plays for background
+ * sub-agents, but a job is not an agent — it has no transcript, no abort(), and
+ * must NOT show up in AgentStatus.
+ *
+ * The engine's wait-for-background loop parks the turn until a session has no
+ * more RUNNING jobs, so the goal-stop-hook doesn't force the model to busy-loop
+ * with `sleep` while a video renders (the s-mqe0ox7n-a8d11c26 bug).
+ *
+ * Finished jobs are RETAINED (status flips to completed/failed, result stored)
+ * so the background panel can show them + let the user open the result — they
+ * don't vanish the instant they complete (#2/#5). Retention is bounded:
+ *   - event-driven: a session's jobs are dropped when the session is deleted
+ *     (dropForSession, wired to session close/delete);
+ *   - a generous per-session cap on TERMINAL jobs is a pure memory backstop for
+ *     a session that spawns hundreds of jobs and is never deleted.
+ *
+ * Process-local singleton, same pattern as asyncAgentRegistry. The video/Drive
+ * loops run in the main engine process, so start/finish and the engine's wait
+ * loop observe the same instance.
+ */
+type Listener = () => void;
+export type BackgroundJobStatus = "running" | "completed" | "failed";
+/** A background job, running or finished. */
+export interface BackgroundJobEntry {
+    jobId: string;
+    sessionId: string;
+    /** Human description (e.g. "Generating video: <prompt>"). Shown to the goal
+     *  judge (running) and in the background panel (all). */
+    description: string;
+    status: BackgroundJobStatus;
+    startedAt: number;
+    /** Set when status flips to a terminal state. */
+    finishedAt?: number;
+    /** Result summary (video URL, DriveAgent final text) or error message. */
+    finalText?: string;
+    /** External CLI session id, when the job is a DriveAgent run — lets the host
+     *  read that CLI's transcript to attribute file changes (#6). */
+    ccSessionId?: string;
+    /** Files the external agent changed (parsed from its transcript, #6). */
+    changedFiles?: string[];
+}
+/** Outcome passed to finish() to record how a job ended. */
+export interface BackgroundJobOutcome {
+    status?: "completed" | "failed";
+    finalText?: string;
+    ccSessionId?: string;
+    changedFiles?: string[];
+}
+declare class BackgroundJobRegistry {
+    private jobs;
+    private listeners;
+    /** Register a running job. Invalid sessionId is ignored (cannot be waited on). */
+    start(jobId: string, sessionId: string, description?: string): void;
+    /** Mark a job terminal (retained, not deleted). Unknown id is a no-op (no
+     *  notify) so a double-finish or a finish after reset stays quiet. */
+    finish(jobId: string, outcome?: BackgroundJobOutcome): void;
+    /** True while any RUNNING job spawned by `sessionId` remains. */
+    hasRunningForSession(sessionId: string): boolean;
+    /** Running jobs spawned by `sessionId`. Feeds the goal judge's task list. */
+    listRunningForSession(sessionId: string): BackgroundJobEntry[];
+    /** All jobs (running + retained terminal) for `sessionId`. Feeds the panel. */
+    listForSession(sessionId: string): BackgroundJobEntry[];
+    /** Drop every job of a session — called when the session is deleted/closed. */
+    dropForSession(sessionId: string): void;
+    subscribe: (cb: Listener) => (() => void);
+    /** Test helper: drop all tracked jobs. */
+    reset(): void;
+    /** Backstop: keep at most MAX_TERMINAL_JOBS_PER_SESSION terminal jobs per
+     *  session, evicting the oldest (insertion order). Running jobs never evicted. */
+    private evictTerminalOverCap;
+    private notify;
+}
+export declare const backgroundJobRegistry: BackgroundJobRegistry;
+export {};

package/dist/tool-system/builtin/background-jobs.js

@@ -0,0 +1,124 @@
+/**
+ * Registry of NON-agent background jobs (GenerateVideo poll loops, DriveAgent
+ * external CLI runs). Mirrors the role `asyncAgentRegistry` plays for background
+ * sub-agents, but a job is not an agent — it has no transcript, no abort(), and
+ * must NOT show up in AgentStatus.
+ *
+ * The engine's wait-for-background loop parks the turn until a session has no
+ * more RUNNING jobs, so the goal-stop-hook doesn't force the model to busy-loop
+ * with `sleep` while a video renders (the s-mqe0ox7n-a8d11c26 bug).
+ *
+ * Finished jobs are RETAINED (status flips to completed/failed, result stored)
+ * so the background panel can show them + let the user open the result — they
+ * don't vanish the instant they complete (#2/#5). Retention is bounded:
+ *   - event-driven: a session's jobs are dropped when the session is deleted
+ *     (dropForSession, wired to session close/delete);
+ *   - a generous per-session cap on TERMINAL jobs is a pure memory backstop for
+ *     a session that spawns hundreds of jobs and is never deleted.
+ *
+ * Process-local singleton, same pattern as asyncAgentRegistry. The video/Drive
+ * loops run in the main engine process, so start/finish and the engine's wait
+ * loop observe the same instance.
+ */
+function isValidSessionId(sid) {
+    return typeof sid === "string" && sid.length > 0;
+}
+/** Generous per-session cap on retained terminal jobs — a leak backstop, not a
+ *  UX limit; a human never spawns this many background jobs in one session. */
+const MAX_TERMINAL_JOBS_PER_SESSION = 50;
+class BackgroundJobRegistry {
+    jobs = new Map(); // jobId -> entry (insertion-ordered)
+    listeners = new Set();
+    /** Register a running job. Invalid sessionId is ignored (cannot be waited on). */
+    start(jobId, sessionId, description = "") {
+        if (!isValidSessionId(sessionId))
+            return;
+        this.jobs.set(jobId, {
+            jobId,
+            sessionId,
+            description,
+            status: "running",
+            startedAt: Date.now(),
+        });
+        this.notify();
+    }
+    /** Mark a job terminal (retained, not deleted). Unknown id is a no-op (no
+     *  notify) so a double-finish or a finish after reset stays quiet. */
+    finish(jobId, outcome) {
+        const entry = this.jobs.get(jobId);
+        if (!entry)
+            return;
+        entry.status = outcome?.status ?? "completed";
+        entry.finishedAt = Date.now();
+        if (outcome?.finalText !== undefined)
+            entry.finalText = outcome.finalText;
+        if (outcome?.ccSessionId !== undefined)
+            entry.ccSessionId = outcome.ccSessionId;
+        if (outcome?.changedFiles !== undefined)
+            entry.changedFiles = outcome.changedFiles;
+        this.evictTerminalOverCap(entry.sessionId);
+        this.notify();
+    }
+    /** True while any RUNNING job spawned by `sessionId` remains. */
+    hasRunningForSession(sessionId) {
+        for (const e of this.jobs.values()) {
+            if (e.sessionId === sessionId && e.status === "running")
+                return true;
+        }
+        return false;
+    }
+    /** Running jobs spawned by `sessionId`. Feeds the goal judge's task list. */
+    listRunningForSession(sessionId) {
+        return [...this.jobs.values()].filter((e) => e.sessionId === sessionId && e.status === "running");
+    }
+    /** All jobs (running + retained terminal) for `sessionId`. Feeds the panel. */
+    listForSession(sessionId) {
+        return [...this.jobs.values()].filter((e) => e.sessionId === sessionId);
+    }
+    /** Drop every job of a session — called when the session is deleted/closed. */
+    dropForSession(sessionId) {
+        let removed = false;
+        for (const [id, e] of this.jobs) {
+            if (e.sessionId === sessionId) {
+                this.jobs.delete(id);
+                removed = true;
+            }
+        }
+        if (removed)
+            this.notify();
+    }
+    subscribe = (cb) => {
+        this.listeners.add(cb);
+        return () => {
+            this.listeners.delete(cb);
+        };
+    };
+    /** Test helper: drop all tracked jobs. */
+    reset() {
+        this.jobs.clear();
+    }
+    /** Backstop: keep at most MAX_TERMINAL_JOBS_PER_SESSION terminal jobs per
+     *  session, evicting the oldest (insertion order). Running jobs never evicted. */
+    evictTerminalOverCap(sessionId) {
+        const terminal = [...this.jobs.values()].filter((e) => e.sessionId === sessionId && e.status !== "running");
+        const over = terminal.length - MAX_TERMINAL_JOBS_PER_SESSION;
+        if (over <= 0)
+            return;
+        // Map iteration is insertion order → the first `over` terminal entries are
+        // the oldest.
+        for (let i = 0; i < over; i++) {
+            this.jobs.delete(terminal[i].jobId);
+        }
+    }
+    notify() {
+        for (const cb of this.listeners) {
+            try {
+                cb();
+            }
+            catch {
+                // isolate per-listener errors
+            }
+        }
+    }
+}
+export const backgroundJobRegistry = new BackgroundJobRegistry();

package/dist/tool-system/builtin/background-shell-tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Background-shell tools — BashOutput / KillShell / ListShells.
+ *
+ * Companions to `Bash(run_in_background=true)` (design §5.2–5.4). They
+ * operate on the {@link BackgroundShellManager} (threaded via
+ * `ctx.backgroundShells`, falling back to the process-local singleton).
+ *
+ * All three are session-scoped: a shell started in session A is invisible
+ * and unreachable from session B (the manager enforces this; we pass
+ * `ctx.sessionId` so cross-session ids report a plain "unknown shell_id"
+ * rather than leaking another session's processes).
+ */
+import type { ToolContext } from "../context.js";
+import type { ToolDefinition } from "../../types.js";
+export declare const bashOutputToolDef: ToolDefinition;
+export declare function bashOutputTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const killShellToolDef: ToolDefinition;
+export declare function killShellTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const listShellsToolDef: ToolDefinition;
+export declare function listShellsTool(_args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/background-shell-tools.js

@@ -0,0 +1,108 @@
+/**
+ * Background-shell tools — BashOutput / KillShell / ListShells.
+ *
+ * Companions to `Bash(run_in_background=true)` (design §5.2–5.4). They
+ * operate on the {@link BackgroundShellManager} (threaded via
+ * `ctx.backgroundShells`, falling back to the process-local singleton).
+ *
+ * All three are session-scoped: a shell started in session A is invisible
+ * and unreachable from session B (the manager enforces this; we pass
+ * `ctx.sessionId` so cross-session ids report a plain "unknown shell_id"
+ * rather than leaking another session's processes).
+ */
+import { backgroundShellManager } from "../../runtime/background-shell.js";
+function managerFor(ctx) {
+    return ctx?.backgroundShells ?? backgroundShellManager;
+}
+// ─── BashOutput ──────────────────────────────────────────────────────
+export const bashOutputToolDef = {
+    name: "BashOutput",
+    description: "Read output from a background shell started via Bash(run_in_background=true). " +
+        "Returns new output since your last read (incremental by default). ANSI colors and progress bars are stripped. " +
+        "Use this only for an on-demand peek at a STILL-RUNNING process — you do NOT need to poll it to wait for " +
+        "completion: when the background command finishes you are automatically woken with the result, so end your " +
+        "turn instead of looping Sleep + BashOutput.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            shell_id: {
+                type: "string",
+                description: "The shell_id returned by Bash(run_in_background=true).",
+            },
+            mode: {
+                type: "string",
+                enum: ["incremental", "all"],
+                description: "incremental (default): output since your last read. all: the full retained buffer.",
+            },
+        },
+        required: ["shell_id"],
+    },
+};
+export async function bashOutputTool(args, ctx) {
+    const shellId = args.shell_id;
+    if (!shellId)
+        return "Error: shell_id is required";
+    const mode = args.mode === "all" ? "all" : "incremental";
+    const res = managerFor(ctx).readOutput(shellId, mode, ctx?.sessionId);
+    if (!res.ok)
+        return `Error: ${res.error}`;
+    const body = res.text.length > 0 ? res.text : "(no new output)";
+    return `${res.header}\n${body}`;
+}
+// ─── KillShell ───────────────────────────────────────────────────────
+export const killShellToolDef = {
+    name: "KillShell",
+    description: "Terminate a background shell (and its whole process group) started via Bash(run_in_background=true).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            shell_id: { type: "string", description: "The shell_id to terminate." },
+        },
+        required: ["shell_id"],
+    },
+};
+export async function killShellTool(args, ctx) {
+    const shellId = args.shell_id;
+    if (!shellId)
+        return "Error: shell_id is required";
+    const res = await managerFor(ctx).kill(shellId, ctx?.sessionId);
+    if (!res.ok)
+        return `Error: ${res.error}`;
+    if (res.alreadyExited) {
+        return `Background shell ${shellId} had already exited (status=${res.status}).`;
+    }
+    return `Background shell ${shellId} terminated (status=${res.status}).`;
+}
+// ─── ListShells ──────────────────────────────────────────────────────
+export const listShellsToolDef = {
+    name: "ListShells",
+    description: "List background shells for the current session, with status and detected port.",
+    inputSchema: { type: "object", properties: {} },
+};
+function ago(ms) {
+    const s = Math.max(0, Math.round((Date.now() - ms) / 1000));
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    return `${Math.round(m / 60)}h ago`;
+}
+export async function listShellsTool(_args, ctx) {
+    const sessionId = ctx?.sessionId;
+    if (!sessionId)
+        return "No background shells (no session context).";
+    const shells = managerFor(ctx).listForSession(sessionId);
+    if (shells.length === 0)
+        return "No background shells for this session.";
+    const rows = shells.map((s) => {
+        const portPart = s.detectedPort !== undefined ? `  port=${s.detectedPort}` : "";
+        const exitPart = s.status === "exited"
+            ? s.signal
+                ? `  signal=${s.signal}`
+                : `  exit=${s.exitCode ?? "?"}`
+            : "";
+        return `${s.shellId}  ${s.status}${portPart}${exitPart}  ${s.command}  (started ${ago(s.startedAt)})`;
+    });
+    return rows.join("\n");
+}

package/dist/tool-system/builtin/background-work.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Unified view over the THREE kinds of async background work — background
+ * sub-agents (asyncAgentRegistry), background jobs / video polls
+ * (backgroundJobRegistry), and background shells (backgroundShellManager).
+ *
+ * Used by the goal-stop-hook to show the judge LLM what's still running, so it
+ * can tell "the goal is done except for a finite task that will wake me" (a
+ * download / video render → allow stop, wait for the wakeup) from "a long-lived
+ * service that the goal doesn't depend on" (a dev server → judge the goal
+ * normally). Replacing the old mechanical `hasRunningForSession` short-circuit:
+ * a boolean can't distinguish a finite download from a never-ending dev server,
+ * but the judge — given each task's kind + command — can.
+ */
+import { type AsyncAgentStatus } from "./agent-registry.js";
+import { type BackgroundJobStatus } from "./background-jobs.js";
+import { type BgShell } from "../../runtime/background-shell.js";
+export type BackgroundWorkKind = "subagent" | "job" | "shell";
+export interface BackgroundWorkItem {
+    kind: BackgroundWorkKind;
+    /** Human description for the judge (sub-agent task / video prompt / shell command). */
+    description: string;
+    /**
+     * For kind === "shell": a port the shell is listening on, if detected. A
+     * listening port is a strong signal the shell is a long-lived service (dev
+     * server) rather than a finite task — fed to the judge so it doesn't mistake
+     * `make serve` / an opaquely-named server script for something to "wait on".
+     */
+    detectedPort?: number;
+}
+/** List every still-running background work item spawned by `sessionId`. */
+export declare function listRunningBackgroundWork(sessionId: string): BackgroundWorkItem[];
+/** One background-work row for the desktop panel, discriminated by `kind`. */
+export type BackgroundWorkEntry = {
+    kind: "shell";
+    /** Full shell snapshot — the panel already renders this shape (output/kill
+     *  still go through the dedicated agent/backgroundShells RPC by shellId). */
+    shell: BgShell;
+} | {
+    kind: "subagent";
+    agentId: string;
+    name?: string;
+    agentType?: string;
+    description: string;
+    status: AsyncAgentStatus;
+    startedAt: number;
+    finishedAt?: number;
+} | {
+    kind: "job";
+    jobId: string;
+    description: string;
+    status: BackgroundJobStatus;
+    startedAt: number;
+    finishedAt?: number;
+    /** Result summary / error, once finished. */
+    finalText?: string;
+    /** Files an external agent (DriveAgent) changed, parsed from its transcript. */
+    changedFiles?: string[];
+};
+/**
+ * Every background-work item spawned by `sessionId`, with per-kind detail, for
+ * the desktop panel. Includes finished sub-agents that are still within their
+ * fade window (so a just-completed agent doesn't vanish before the user sees
+ * it); shells carry their own terminal status and the panel decides how long to
+ * keep them. Jobs are only ever present while running (the registry drops them
+ * on finish).
+ */
+export declare function listBackgroundWorkForUI(sessionId: string): BackgroundWorkEntry[];

package/dist/tool-system/builtin/background-work.js

@@ -0,0 +1,86 @@
+/**
+ * Unified view over the THREE kinds of async background work — background
+ * sub-agents (asyncAgentRegistry), background jobs / video polls
+ * (backgroundJobRegistry), and background shells (backgroundShellManager).
+ *
+ * Used by the goal-stop-hook to show the judge LLM what's still running, so it
+ * can tell "the goal is done except for a finite task that will wake me" (a
+ * download / video render → allow stop, wait for the wakeup) from "a long-lived
+ * service that the goal doesn't depend on" (a dev server → judge the goal
+ * normally). Replacing the old mechanical `hasRunningForSession` short-circuit:
+ * a boolean can't distinguish a finite download from a never-ending dev server,
+ * but the judge — given each task's kind + command — can.
+ */
+import { asyncAgentRegistry } from "./agent-registry.js";
+import { backgroundJobRegistry } from "./background-jobs.js";
+import { backgroundShellManager } from "../../runtime/background-shell.js";
+/** List every still-running background work item spawned by `sessionId`. */
+export function listRunningBackgroundWork(sessionId) {
+    const items = [];
+    for (const a of asyncAgentRegistry.listForSession(sessionId)) {
+        if (a.status === "running") {
+            items.push({
+                kind: "subagent",
+                description: a.description || a.name || a.agentType || "(background sub-agent)",
+            });
+        }
+    }
+    for (const j of backgroundJobRegistry.listRunningForSession(sessionId)) {
+        items.push({ kind: "job", description: j.description || "(background job)" });
+    }
+    for (const s of backgroundShellManager.listForSession(sessionId)) {
+        if (s.status === "running" || s.status === "starting") {
+            items.push({
+                kind: "shell",
+                description: s.command,
+                ...(s.detectedPort != null ? { detectedPort: s.detectedPort } : {}),
+            });
+        }
+    }
+    return items;
+}
+/**
+ * Every background-work item spawned by `sessionId`, with per-kind detail, for
+ * the desktop panel. Includes finished sub-agents that are still within their
+ * fade window (so a just-completed agent doesn't vanish before the user sees
+ * it); shells carry their own terminal status and the panel decides how long to
+ * keep them. Jobs are only ever present while running (the registry drops them
+ * on finish).
+ */
+export function listBackgroundWorkForUI(sessionId) {
+    const entries = [];
+    for (const s of backgroundShellManager.listForSession(sessionId)) {
+        entries.push({ kind: "shell", shell: s });
+    }
+    const now = Date.now();
+    for (const a of asyncAgentRegistry.listForSession(sessionId)) {
+        // Keep running agents, plus finished ones still inside their fade window so
+        // a completion is briefly visible. (finishedFadeAt = finishedAt + 30s.)
+        const fresh = a.status === "running" || (a.finishedFadeAt != null && a.finishedFadeAt > now);
+        if (!fresh)
+            continue;
+        entries.push({
+            kind: "subagent",
+            agentId: a.agentId,
+            name: a.name,
+            agentType: a.agentType,
+            description: a.description,
+            status: a.status,
+            startedAt: a.startedAt,
+            finishedAt: a.finishedAt,
+        });
+    }
+    for (const j of backgroundJobRegistry.listForSession(sessionId)) {
+        entries.push({
+            kind: "job",
+            jobId: j.jobId,
+            description: j.description,
+            status: j.status,
+            startedAt: j.startedAt,
+            ...(j.finishedAt != null ? { finishedAt: j.finishedAt } : {}),
+            ...(j.finalText != null ? { finalText: j.finalText } : {}),
+            ...(j.changedFiles && j.changedFiles.length ? { changedFiles: j.changedFiles } : {}),
+        });
+    }
+    return entries;
+}