Agent mode phase 2: persistent, interactive terminals

Agent mode's only process-management tool (start_background_command) spawns
with stdio: ["ignore", ...] — there's no way to send input to a running
process, so answering an interactive prompt or driving a REPL was
impossible; output was poll-only, never streamed.

- New app/src/terminal-manager.ts, backed by node-pty (real pseudo-terminal,
  not a plain pipe): create/write/resize/close/list, workspace-scoped
  cleanup wired into the same lifecycle hooks phase 0 built for background
  tasks (agent:closeWorkspace, window-all-closed, before-quit). Reuses phase
  1's command-sandbox.ts for filesystem confinement where the platform
  supports it, defaulting to network allowed (unlike run_command's per-call
  default) since this is an interactive session a human can see and type
  into directly, not a one-shot command the model composed unsupervised.

- Two separate paths reach it, deliberately: a human opening the terminal
  panel goes through a dedicated terminal:create IPC channel with live
  push-streamed output (mirrors the existing chat:chunk streaming pattern)
  and never touches tool approval, since the human is driving their own
  keystrokes. The model gets four new agent tools — create_terminal,
  write_to_terminal, read_terminal_output, close_terminal — that poll
  instead of stream, going through the normal approval-card pipeline like
  every other tool. Kept start_background_command's existing four tools
  unchanged rather than folding them into this, so no schema break for
  prompts/evals that already know them.

- New frontend/src/components/terminal-panel.tsx (xterm.js + fit addon):
  one mounted terminal instance, tab-switching replays each session's
  buffered output rather than keeping N instances alive at once.

- Extracted resolveSafePath out of agent-tools.ts into workspace-path.ts so
  terminal-manager.ts could reuse the same workspace-containment logic
  without agent-tools.ts <-> terminal-manager.ts becoming a circular import
  (agent-tools.ts's own new create_terminal/write_to_terminal/etc tool
  cases need to import terminal-manager.ts, which already needed
  resolveSafePath).

New dependencies: node-pty (main, native — added to asarUnpack alongside
the other native deps; electron-builder rebuilds it for Electron's ABI
automatically, same as the existing node-llama-cpp dependency already
relies on), @xterm/xterm + @xterm/addon-fit (renderer).

17 new tests across terminal-manager.test.ts and 3 new agent-tools.test.ts
cases for the tool-call dispatch path, all exercising a real spawned pty
rather than mocking node-pty.

Author: voidstackloop

app/package-lock.json

@@ -33,7 +33,8 @@
       "**/node_modules/tesseract.js/**",
       "**/node_modules/tesseract.js-core/**",
       "**/node_modules/node-llama-cpp/**",
-      "**/node_modules/@node-llama-cpp/**"
+      "**/node_modules/@node-llama-cpp/**",
+      "**/node_modules/node-pty/**"
     ],
     "extraResources": [
       {
@@ -91,6 +92,7 @@
     "electron-updater": "^6.6.2",
     "ffmpeg-static": "^5.3.0",
     "node-llama-cpp": "^3.19.1",
+    "node-pty": "^1.1.0",
     "pdf-parse": "^2.4.5",
     "pidusage": "^4.0.1",
     "tesseract.js": "^5.1.1"

app/package.json

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { execSync } from "node:child_process";
+import { closeAll as closeAllTerminals } from "./terminal-manager";
 import {
     readFile,
     writeFile,
@@ -393,6 +394,48 @@ describe("agent-tools", () => {
         });
     });
 
+    describe("terminal tools", () => {
+        afterEach(() => {
+            closeAllTerminals();
+        });
+
+        function waitFor(predicate: () => boolean | Promise<boolean>, timeoutMs = 5000): Promise<void> {
+            const start = Date.now();
+            return new Promise((resolve, reject) => {
+                const check = async () => {
+                    if (await predicate()) return resolve();
+                    if (Date.now() - start > timeoutMs) return reject(new Error("timed out waiting"));
+                    setTimeout(check, 20);
+                };
+                check();
+            });
+        }
+
+        it("creates a terminal, writes a command to it, and reads the output back", async () => {
+            const created = (await executeTool(workspace, "create_terminal", { name: "test" })) as { id: string; name: string };
+            expect(created.id).toBeTruthy();
+
+            await executeTool(workspace, "write_to_terminal", { terminal_id: created.id, input: "echo from-agent-terminal\r" });
+
+            await waitFor(async () => {
+                const output = (await executeTool(workspace, "read_terminal_output", { terminal_id: created.id })) as string;
+                return output.includes("from-agent-terminal");
+            });
+            const output = (await executeTool(workspace, "read_terminal_output", { terminal_id: created.id })) as string;
+            expect(output).toContain("from-agent-terminal");
+        });
+
+        it("closes a terminal so further reads/writes fail", async () => {
+            const created = (await executeTool(workspace, "create_terminal", {})) as { id: string; name: string };
+            await executeTool(workspace, "close_terminal", { terminal_id: created.id });
+            await expect(executeTool(workspace, "read_terminal_output", { terminal_id: created.id })).rejects.toThrow(/No terminal/);
+        });
+
+        it("throws for an unknown terminal id", async () => {
+            await expect(executeTool(workspace, "write_to_terminal", { terminal_id: "nope", input: "x" })).rejects.toThrow(/No terminal/);
+        });
+    });
+
     describe("run_command", () => {
         it("captures stdout and a zero exit code from a successful command", async () => {
             const output = await executeTool(workspace, "run_command", { command: "echo hello" });

app/src/agent-tools.test.ts

@@ -11,6 +11,8 @@ import { killProcessTree } from "./process-tree";
 import { applySandbox } from "./command-sandbox";
 import { monitorProcess } from "./resource-monitor";
 import * as settingsStore from "./settings-store";
+import { resolveSafePath } from "./workspace-path";
+import * as terminalManager from "./terminal-manager";
 
 const execAsync = promisify(exec);
 
@@ -202,6 +204,54 @@ export const AGENT_TOOLS: ToolDefinition[] = [
         description: "List all background commands from this session with their status.",
         parameters: { type: "object", properties: {}, required: [] },
     },
+    {
+        name: "create_terminal",
+        description:
+            "Open a real interactive shell (a pseudo-terminal) in the workspace and return its id. Unlike run_command/start_background_command, this can be driven interactively over multiple turns — write_to_terminal to send input (including to a program already waiting for it, e.g. a REPL or a confirmation prompt), read_terminal_output to see what happened. Use this instead of start_background_command when you need to send input after the process has already started, not just read its output.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Short human-readable label (e.g. \"debug session\")." },
+                cwd: { type: "string", description: 'Working directory, relative to the workspace root. Defaults to "."' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "write_to_terminal",
+        description: "Send input to a terminal opened with create_terminal, as if typed at the keyboard. Include \\n (or \\r) to press Enter and actually run a typed command — without it, the text is typed but not submitted.",
+        parameters: {
+            type: "object",
+            properties: {
+                terminal_id: { type: "string", description: "The id returned by create_terminal." },
+                input: { type: "string", description: "The text to send." },
+            },
+            required: ["terminal_id", "input"],
+        },
+    },
+    {
+        name: "read_terminal_output",
+        description: "Read the recent output of a terminal opened with create_terminal.",
+        parameters: {
+            type: "object",
+            properties: {
+                terminal_id: { type: "string", description: "The id returned by create_terminal." },
+                tail_chars: { type: "number", description: "How many characters of recent output to return, from the end. Defaults to 4000." },
+            },
+            required: ["terminal_id"],
+        },
+    },
+    {
+        name: "close_terminal",
+        description: "Close a terminal opened with create_terminal, ending its shell process.",
+        parameters: {
+            type: "object",
+            properties: {
+                terminal_id: { type: "string", description: "The id returned by create_terminal." },
+            },
+            required: ["terminal_id"],
+        },
+    },
     {
         name: "git_status",
         description: "Show the working tree status (git status) for the workspace.",
@@ -415,38 +465,6 @@ const MAX_COMMAND_OUTPUT_CHARS = 50_000;
 const COMMAND_TIMEOUT_MS = 60_000;
 const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", "out", "release", "__pycache__"]);
 
-// Every tool call is confined to the chosen workspace directory — this
-// resolves the (possibly relative, possibly attacker-crafted via a prompt
-// injection in file content the model read) path and throws if it would
-// escape that directory via ../ or an absolute path elsewhere on disk.
-function resolveSafePath(workspaceRoot: string, relativePath: string): string {
-    const root = path.resolve(workspaceRoot);
-    const resolved = path.resolve(root, relativePath || ".");
-    const isWithin = (parent: string, child: string): boolean => {
-        const relative = path.relative(parent, child);
-        return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
-    };
-    if (!isWithin(root, resolved)) {
-        throw new Error(`Path "${relativePath}" is outside the workspace directory.`);
-    }
-
-    // Lexical checks alone are bypassable through a symlink inside the
-    // workspace that points elsewhere. Resolve the target, or its nearest
-    // existing parent for new files, and verify the real path too.
-    const realRoot = fs.realpathSync(root);
-    let existing = resolved;
-    while (!fs.existsSync(existing)) {
-        const parent = path.dirname(existing);
-        if (parent === existing) break;
-        existing = parent;
-    }
-    const realExisting = fs.realpathSync(existing);
-    if (!isWithin(realRoot, realExisting)) {
-        throw new Error(`Path "${relativePath}" resolves outside the workspace directory through a symbolic link.`);
-    }
-    return resolved;
-}
-
 export function readFile(workspaceRoot: string, relativePath: string, startLine?: number, endLine?: number): string {
     const target = resolveSafePath(workspaceRoot, relativePath);
     const stat = fs.statSync(target);
@@ -1467,6 +1485,26 @@ export async function executeTool(workspaceRoot: string, name: string, args: Rec
             return stopBackgroundCommand(String(args.task_id ?? ""));
         case "list_background_commands":
             return listBackgroundCommands();
+        case "create_terminal":
+            // No-op streaming callbacks: the model drives this by polling
+            // read_terminal_output rather than receiving push events — live
+            // streaming is reserved for the human-facing terminal panel,
+            // which goes through the dedicated terminal:create IPC channel
+            // instead of this tool-call path.
+            return terminalManager.createTerminal(
+                workspaceRoot,
+                { name: args.name ? String(args.name) : undefined, cwd: args.cwd ? String(args.cwd) : undefined },
+                () => {},
+                () => {}
+            );
+        case "write_to_terminal":
+            terminalManager.writeToTerminal(String(args.terminal_id ?? ""), String(args.input ?? ""));
+            return { ok: true };
+        case "read_terminal_output":
+            return terminalManager.readTerminalOutput(String(args.terminal_id ?? ""), typeof args.tail_chars === "number" ? args.tail_chars : undefined);
+        case "close_terminal":
+            terminalManager.closeTerminal(String(args.terminal_id ?? ""));
+            return { ok: true };
         case "git_status":
             return gitStatus(workspaceRoot);
         case "git_diff":

app/src/agent-tools.ts

@@ -24,11 +24,34 @@ function commandExists(cmd: string): boolean {
     }
 }
 
-// `hasCommand` is injectable so tests can simulate "bwrap is/isn't on PATH"
+// bwrap being on PATH isn't sufficient on its own — modern Ubuntu (23.10+)
+// restricts unprivileged user-namespace creation by default (AppArmor
+// policy), which makes bwrap fail at runtime with a permission error even
+// when it's installed. A plain `which bwrap` check wouldn't catch that and
+// would report false confidence, so this actually runs a trivial sandboxed
+// no-op and checks it really works.
+function canUseBubblewrap(): boolean {
+    if (!commandExists("bwrap")) return false;
+    try {
+        execFileSync("bwrap", ["--unshare-all", "--dev", "/dev", "--proc", "/proc", "true"], {
+            stdio: "ignore",
+            timeout: 5000,
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function defaultAvailabilityCheck(cmd: string): boolean {
+    return cmd === "bwrap" ? canUseBubblewrap() : commandExists(cmd);
+}
+
+// `hasCommand` is injectable so tests can simulate "bwrap is/isn't usable"
 // without actually shelling out.
 export function detectSandboxCapabilities(
     platform: NodeJS.Platform = process.platform,
-    hasCommand: (cmd: string) => boolean = commandExists
+    hasCommand: (cmd: string) => boolean = defaultAvailabilityCheck
 ): SandboxCapabilities {
     if (platform === "linux") {
         if (hasCommand("bwrap")) return { filesystemConfinement: true, networkDenial: true, mechanism: "bubblewrap" };
@@ -65,7 +88,7 @@ export function wrapCommand(
     command: string,
     opts: WrapCommandOptions,
     platform: NodeJS.Platform = process.platform,
-    hasCommand: (cmd: string) => boolean = commandExists
+    hasCommand: (cmd: string) => boolean = defaultAvailabilityCheck
 ): WrappedCommand | null {
     const caps = detectSandboxCapabilities(platform, hasCommand);
     const root = path.resolve(opts.workspaceRoot);
@@ -144,7 +167,7 @@ export function applySandbox(
     command: string,
     opts: WrapCommandOptions,
     platform: NodeJS.Platform = process.platform,
-    hasCommand: (cmd: string) => boolean = commandExists
+    hasCommand: (cmd: string) => boolean = defaultAvailabilityCheck
 ): string {
     const wrapped = wrapCommand(command, opts, platform, hasCommand);
     if (!wrapped) return command;

app/src/command-sandbox.ts

@@ -15,6 +15,7 @@ import * as dataTransfer from "./data-transfer";
 import * as rag from "./rag";
 import * as agentTools from "./agent-tools";
 import { detectSandboxCapabilities } from "./command-sandbox";
+import * as terminalManager from "./terminal-manager";
 import * as mcpClient from "./mcp-client";
 import * as figma from "./figma";
 import * as ocr from "./ocr";
@@ -763,11 +764,50 @@ function registerIpcHandlers(): void {
     ipcMain.handle("agent:closeWorkspace", (_event: IpcMainInvokeEvent, workspaceRoot: string) => {
         requireString(workspaceRoot, "workspace root");
         const killedBackgroundTasks = agentTools.killBackgroundCommandsForWorkspace(workspaceRoot);
-        return { killedBackgroundTasks };
+        const killedTerminals = terminalManager.closeAllForWorkspace(workspaceRoot);
+        return { killedBackgroundTasks, killedTerminals };
     });
 
     ipcMain.handle("agent:getSandboxCapabilities", () => detectSandboxCapabilities());
 
+    ipcMain.handle(
+        "terminal:create",
+        (
+            event: IpcMainInvokeEvent,
+            { workspaceRoot, opts }: { workspaceRoot: string; opts?: { cwd?: string; name?: string } }
+        ) => {
+            requireString(workspaceRoot, "workspace root");
+            // `id` is referenced inside these callbacks before it's assigned
+            // below, but that's safe: node-pty never calls onData/onExit
+            // synchronously during createTerminal() itself, only later once
+            // its own async event loop runs — by which point `id` is set.
+            const { id, name } = terminalManager.createTerminal(
+                workspaceRoot,
+                opts ?? {},
+                (chunk) => event.sender.send(`terminal:data:${id}`, chunk),
+                (exitCode) => event.sender.send(`terminal:exit:${id}`, exitCode)
+            );
+            return { id, name };
+        }
+    );
+
+    ipcMain.handle("terminal:write", (_event: IpcMainInvokeEvent, { id, data }: { id: string; data: string }) => {
+        requireString(id, "terminal id");
+        terminalManager.writeToTerminal(id, typeof data === "string" ? data : "");
+    });
+
+    ipcMain.handle("terminal:resize", (_event: IpcMainInvokeEvent, { id, cols, rows }: { id: string; cols: number; rows: number }) => {
+        requireString(id, "terminal id");
+        terminalManager.resizeTerminal(id, Number(cols) || 80, Number(rows) || 24);
+    });
+
+    ipcMain.handle("terminal:close", (_event: IpcMainInvokeEvent, id: string) => {
+        requireString(id, "terminal id");
+        terminalManager.closeTerminal(id);
+    });
+
+    ipcMain.handle("terminal:list", (_event: IpcMainInvokeEvent, workspaceRoot?: string) => terminalManager.listTerminals(workspaceRoot));
+
     ipcMain.handle("mcp:connect", async (_event: IpcMainInvokeEvent, config: McpServerConfig) => {
         try {
             const { tools } = await mcpClient.connectServer(config);
@@ -824,6 +864,7 @@ app.on("window-all-closed", () => {
     ollama.stop();
     localServers.stopAll();
     agentTools.killAllBackgroundCommands();
+    terminalManager.closeAll();
     mcpClient.disconnectAll();
     if (process.platform !== "darwin") app.quit();
 });
@@ -832,5 +873,6 @@ app.on("before-quit", () => {
     ollama.stop();
     localServers.stopAll();
     agentTools.killAllBackgroundCommands();
+    terminalManager.closeAll();
     void llamacpp.dispose();
 });