Unify command execution under shell

benchmarks/startup.sh

@@ -153,21 +153,6 @@ HOME="$SESSION_FIXTURE_HOME" hyperfine \
 
 echo ""
 
-# Benchmark 5: fx background --json (file I/O path)
-echo "--- fx background --json ---"
-(
-  cd "$SESSION_FIXTURE_WORKSPACE"
-  HOME="$SESSION_FIXTURE_HOME" hyperfine \
-    "${SHELL_OPTS[@]}" \
-    --runs "$RUNS" \
-    --warmup "$WARMUP" \
-    --export-json "${RESULTS_DIR}/background.json" \
-    --command-name "fx background --json" \
-    "$FX_BIN background --json"
-)
-
-echo ""
-
 # Combine results into a single summary for CI
 echo "--- summary ---"
 python3 "${REPO_ROOT}/benchmarks/summarize.py"

sdk/AGENTS.md

@@ -15,7 +15,7 @@ The SDK has two WebAssembly surfaces and one shared JavaScript host layer:
 | Interactive terminal entry point for `fx-term.wasm` | `src/wasm_term_main.zig` and `runWasmTerminal` in `src/main.zig` |
 | Native and WebAssembly capability policy | `src/core/hosts/runtime_profile.zig` |
 | Host-backed terminal session persistence | `src/core/app/app_session_runtime.zig` and `sdk/fx-sdk.js` |
-| Browser workspace contract and `terminal.exec` bridge | `src/core/hosts/js_host_workspace.zig` and `src/tools/terminal/browser_terminal.zig` |
+| Browser workspace contract and `shell.run` bridge | `src/core/hosts/js_host_workspace.zig` and `src/tools/shell/browser_shell.zig` |
 | Browser device login, OAuth session persistence, and URL opening | `src/core/auth/js_host_auth.zig`, `src/core/auth/oauth_session.zig`, and `src/core/hosts/js_host_url_opener.zig` |
 | WASI target, optimization mode, threading, and artifact names | `build.zig` |
 | Core browser fixture and its automation contract | `sdk/index.html` and `sdk/tests/test-core-browser.mjs` |
@@ -31,7 +31,7 @@ Do not treat the demos or this file as the implementation contract. When prose a
 - Detect JavaScript Promise Integration (JSPI) by capability through `supportsJspi()`. Do not replace feature detection with browser or version sniffing. Keep loader errors, demo fallback states, and the compatibility statement in `sdk/README.md` consistent.
 - Treat JavaScript host stores as durable contracts. Session and OAuth snapshots are opaque bytes with optimistic revisions. Preserve `FX_SESSION_REVISION_CONFLICT` and `FX_OAUTH_SESSION_REVISION_CONFLICT`. Persist configuration only after fx accepts it, and do not collapse prompt-history outcomes into generic success.
 - Preserve cancellation and lifecycle behavior. Fetch cancellation must reach the host `AbortSignal`; terminal subscriptions must be released exactly once; `abort()` must settle `exited` and must not leave input or resize listeners attached.
-- The WebAssembly runtime is not the native runtime. Keep native tools disabled. The optional workspace host may expose only foreground `terminal.exec` through its typed boundary and permission policy. Its schema is exactly `{ action: "exec", command }`; native profiles and durable terminal actions are unavailable. Any additional capability requires its own typed host boundary, permission review where applicable, and coverage on the affected surface.
+- The WebAssembly runtime is not the native runtime. Keep native tools disabled. The optional workspace host may expose only completion-only `shell.run` through its typed boundary and permission policy. Its schema is exactly `{ action: "run", command }`; native profiles, TTYs, and managed running handles are unavailable. Any additional capability requires its own typed host boundary, permission review where applicable, and coverage on the affected surface.
 - Keep workspace version 1 constrained to an ephemeral, non-git workspace whose normalized `cwd` equals `root`. Preserve command and output limits, the 30-second maximum deadline, and Ctrl+C cancellation through the shared host-effect abort path.
 - `window.__fxCoreTest` and `document.body.dataset.state` are test interfaces for the core debugger. If either changes intentionally, update the browser test in the same change.
 - The live demos may pass a locally stored credential into the WebAssembly environment. Never print, serialize into artifacts, or add test assertions containing that credential.

sdk/README.md

@@ -308,14 +308,14 @@ The WebAssembly runtime intentionally does not provide:
 - Public web fetch, web search, and general outbound network access
 
 The embedded runtime tells the model not to retry unavailable network work
-through terminal commands. Use locally installed fx when the full native tool
+through shell commands. Use locally installed fx when the full native tool
 suite is required.
 
-The optional browser workspace exposes foreground terminal execution through
+The optional browser workspace exposes completion-only shell execution through
 the typed contract:
 
 ```js
-{ action: "exec", command }
+{ action: "run", command }
 ```
 
 The host remains responsible for admitting commands, enforcing limits, and

sdk/node/test-term-workspace.mjs

@@ -75,23 +75,23 @@ function sse(events) {
 
 function toolCall(id, command) {
   return sse([
-    { type: "tool-call", toolCallId: id, toolName: "terminal", input: { action: "exec", command } },
+    { type: "tool-call", toolCallId: id, toolName: "shell", input: { action: "run", command } },
     { type: "finish", finishReason: { unified: "tool-calls", raw: "tool-calls" } },
   ]);
 }
 
-function terminalToolCalls(calls) {
+function shellToolCalls(calls) {
   const events = calls.flatMap(({ id, input }) => {
     const serialized = JSON.stringify(input);
     const deltas = [];
     for (let offset = 0; offset < serialized.length; offset += 4096) {
       deltas.push({ type: "tool-input-delta", id, delta: serialized.slice(offset, offset + 4096) });
     }
     return [
-      { type: "tool-input-start", id, toolName: "terminal" },
+      { type: "tool-input-start", id, toolName: "shell" },
       ...deltas,
       { type: "tool-input-end", id },
-      { type: "tool-call", toolCallId: id, toolName: "terminal" },
+      { type: "tool-call", toolCallId: id, toolName: "shell" },
     ];
   });
   const responseEvents = [
@@ -177,16 +177,16 @@ const fetch = async (_url, init = {}) => {
     checkedBrowserCapabilityContext = true;
   }
   if (!checkedToolProjection) {
-    if (body.tools?.length !== 1 || body.tools[0]?.name !== "terminal") {
+    if (body.tools?.length !== 1 || body.tools[0]?.name !== "shell") {
       throw new Error(`workspace advertised unexpected tools: ${JSON.stringify(body.tools)}`);
     }
     const schema = body.tools[0]?.inputSchema;
     if (JSON.stringify(schema?.required) !== JSON.stringify(["action", "command"]) ||
-        schema?.properties?.action?.enum?.[0] !== "exec" ||
+        schema?.properties?.action?.enum?.[0] !== "run" ||
         schema?.properties?.command?.maxLength !== 65_536 ||
         Object.keys(schema?.properties || {}).join(",") !== "action,command" ||
         schema?.additionalProperties !== false) {
-      throw new Error(`workspace advertised unexpected terminal schema: ${JSON.stringify(schema)}`);
+      throw new Error(`workspace advertised unexpected shell schema: ${JSON.stringify(schema)}`);
     }
     checkedToolProjection = true;
   }
@@ -211,9 +211,9 @@ const fetch = async (_url, init = {}) => {
   }
   if (toolResult(body, "workspace-oversized")) {
     requireResult(body, "workspace-oversized", ["exceeds 65536 bytes"]);
-    requireResult(body, "workspace-profile", ["accepts only the", "action", "command", "fields"]);
-    requireResult(body, "workspace-durable", ["action must be", "exec"]);
-    requireResult(body, "workspace-unknown", ["accepts only the", "action", "command", "fields"]);
+    requireResult(body, "workspace-profile", ["accepts only action and command"]);
+    requireResult(body, "workspace-durable", ["action must be run"]);
+    requireResult(body, "workspace-unknown", ["accepts only action and command"]);
     return textResponse("invalid boundaries checked");
   }
   const prompt = latestUserText(body);
@@ -222,11 +222,11 @@ const fetch = async (_url, init = {}) => {
   if (prompt.includes("workspace timeout")) return toolCall("workspace-timeout", "timeout-command");
   if (prompt.includes("workspace abort")) return toolCall("workspace-abort", "hold-command");
   if (prompt.includes("workspace invalid boundaries")) {
-    return terminalToolCalls([
-      { id: "workspace-oversized", input: { action: "exec", command: "x".repeat(65_537) } },
-      { id: "workspace-profile", input: { action: "exec", command: "must-not-run", profile: "clean" } },
-      { id: "workspace-durable", input: { action: "start", command: "must-not-run" } },
-      { id: "workspace-unknown", input: { action: "exec", command: "must-not-run", unexpected: true } },
+    return shellToolCalls([
+      { id: "workspace-oversized", input: { action: "run", command: "x".repeat(65_537) } },
+      { id: "workspace-profile", input: { action: "run", command: "must-not-run", profile: "clean" } },
+      { id: "workspace-durable", input: { action: "wait", session_id: "must-not-run" } },
+      { id: "workspace-unknown", input: { action: "run", command: "must-not-run", unexpected: true } },
     ]);
   }
   if (prompt.includes("unsupported web request")) {

src/acp/prompt.zig

@@ -303,7 +303,6 @@ const AcpContext = struct {
                 .retain_grant_fn = retainAcpGrant,
             } else null,
             .cancel_flag = &session.cancel_flag,
-            .background = &self.state.background,
             .session = &session.session_rt,
             .session_allocator = self.alloc,
             .skills_dir = self.state.skills.dir,
@@ -314,13 +313,13 @@ const AcpContext = struct {
             .on_output_chunk = onCommandOutputChunk,
             .mcp_progress_ctx = @ptrCast(self),
             .on_mcp_progress = onMcpProgress,
-            .background_url_ctx = @ptrCast(self),
-            .on_background_url_ready = onBackgroundUrlReady,
             .session_child_capability = if (session.writable) |*writable|
                 writable.childCapability() catch null
             else
                 null,
             .terminal_client = &self.state.terminal_client,
+            .managed_executions = &self.state.managed_executions,
+            .ephemeral_command_replay = self.state.managed_executions.replayStore(),
             .web_fetch_runtime = &self.state.web_fetch_runtime,
             .web_fetch_artifact_store = session.session_rt.webFetchArtifactStore(),
             .web_fetch_artifact_error = session.session_rt.webFetchArtifactError(),
@@ -1205,8 +1204,6 @@ fn appendRuntimeContext(raw_ctx: *anyopaque, arena: Allocator, messages: *std.Ar
         .interactive = false,
         .permission_mode = ctx.captured_permission_mode orelse session.permission_mode,
         .tracker = null,
-        .background = &ctx.state.background,
-        .session = &session.session_rt,
     }, arena, messages);
 }
 
@@ -2501,8 +2498,6 @@ fn activeMcp(ctx: *AcpContext) ?*mcp_runtime.McpRuntime {
     return session.mcp;
 }
 
-fn onBackgroundUrlReady(_: *anyopaque, _: u64, _: []const u8) void {}
-
 pub fn mapToolKind(tool_name: []const u8) acp_types.ToolCallKind {
     if (tool_presentation.isProviderSearchAlias(tool_name)) return .search;
     if (std.mem.eql(u8, tool_name, "glob_files")) return .read;
@@ -2512,6 +2507,7 @@ pub fn mapToolKind(tool_name: []const u8) acp_types.ToolCallKind {
     if (std.mem.eql(u8, tool_name, "web_search")) return .search;
     if (std.mem.eql(u8, tool_name, "write_file")) return .edit;
     if (std.mem.eql(u8, tool_name, "edit_file")) return .edit;
+    if (std.mem.eql(u8, tool_name, "shell")) return .execute;
     if (std.mem.eql(u8, tool_name, "terminal")) return .execute;
     if (std.mem.eql(u8, tool_name, "run_command")) return .execute;
     if (std.mem.eql(u8, tool_name, "skill")) return .other;
@@ -2544,15 +2540,15 @@ fn describeToolTitle(registry: tool_dispatch.Registry, arena: Allocator, call: T
     return std.fmt.allocPrint(arena, "{s}", .{call.name});
 }
 
-test "ACP terminal title uses the call-aware action label" {
+test "ACP shell title uses the call-aware action label" {
     const alloc = std.testing.allocator;
     const title = try describeToolTitle(builtin_tools.registry, alloc, .{
         .id = "close",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"close\",\"session_id\":\"terminal-a\",\"close_policy\":\"graceful\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"stop\",\"session_id\":\"terminal-a\"}",
     });
     defer alloc.free(title);
-    try std.testing.expectEqualStrings("Closing", title);
+    try std.testing.expectEqualStrings("Stopping", title);
 }
 
 test "ACP lifecycle action preserves dynamic MCP availability boundaries" {
@@ -2581,7 +2577,7 @@ test "ACP lifecycle action preserves dynamic MCP availability boundaries" {
     defer alloc.free(missing_label);
     try std.testing.expectEqualStrings("Working: mcp_lookup", missing_label);
 
-    const builtin = dynamicMcpToolAvailable(builtin_tools.registry, "terminal", &.{"terminal"}, @ptrCast(&fixture), Fixture.hasTool, .unrestricted);
+    const builtin = dynamicMcpToolAvailable(builtin_tools.registry, "terminal", &.{"shell"}, @ptrCast(&fixture), Fixture.hasTool, .unrestricted);
     try std.testing.expect(!builtin);
     try std.testing.expectEqual(@as(usize, 1), fixture.calls);
 }
@@ -3537,8 +3533,8 @@ test "ACP pending tool_call updates keep provider ids stable and dedupe" {
 
     const call = ToolCall{
         .id = "provider_call_7",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"ls\",\"api_key\":\"secret-value\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"ls\",\"api_key\":\"secret-value\"}",
     };
     const first = try ctx.sendToolCallPending(alloc, call);
     const second = try ctx.sendToolCallPending(alloc, call);
@@ -3566,9 +3562,9 @@ test "ACP pending tool_call updates keep provider ids stable and dedupe" {
         try std.testing.expectEqualStrings("tool_call", update.get("sessionUpdate").?.string);
         const call_id = update.get("toolCallId").?.string;
         if (std.mem.eql(u8, call_id, "provider_call_7")) {
-            try std.testing.expectEqualStrings("terminal", update.get("name").?.string);
+            try std.testing.expectEqualStrings("shell", update.get("name").?.string);
             const raw_input = update.get("rawInput").?.object;
-            try std.testing.expectEqualStrings("exec", raw_input.get("action").?.string);
+            try std.testing.expectEqualStrings("run", raw_input.get("action").?.string);
             try std.testing.expectEqualStrings("ls", raw_input.get("command").?.string);
             try std.testing.expectEqualStrings("[REDACTED]", raw_input.get("api_key").?.string);
             pending_count += 1;
@@ -4083,25 +4079,25 @@ test "ACP default user commands require configured authority or review" {
 
     const direct = (try requestToolPermissionOutcome(&ctx, arena, .{
         .id = "direct",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"pwd\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"pwd\"}",
     }, .ask, &.{}, &.{}));
     try std.testing.expectEqual(ToolPermissionDecision.permission_required, direct.decision);
     try std.testing.expect(direct.execution_authority == null);
 
     const blocked = (try requestToolPermissionOutcome(&ctx, arena, .{
         .id = "blocked",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"touch blocked.txt\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"touch blocked.txt\"}",
     }, .ask, &.{}, &.{}));
     try std.testing.expectEqual(ToolPermissionDecision.permission_required, blocked.decision);
     try std.testing.expect(blocked.execution_authority == null);
 
     state.active_session.?.permission_rules = try testPermissionRuleSet(alloc, "bash", "touch *", .allow);
     const configured = (try requestToolPermissionOutcome(&ctx, arena, .{
         .id = "configured",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"touch configured.txt\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"touch configured.txt\"}",
     }, .ask, &.{}, &.{}));
     switch ((configured.execution_authority orelse return error.TestExpectedEqual).run_command) {
         .direct_only => return error.TestExpectedShellAllowed,
@@ -4112,8 +4108,8 @@ test "ACP default user commands require configured authority or review" {
     state.active_session.?.permission_rules = .{};
     const automatic = (try requestToolPermissionOutcome(&ctx, arena, .{
         .id = "automatic",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"touch automatic.txt\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"touch automatic.txt\"}",
     }, .auto, &.{}, &.{}));
     try std.testing.expectEqual(ToolPermissionDecision.deny, automatic.decision);
     try std.testing.expectEqual(types.ToolPermissionDenialReason.review_unavailable, automatic.denial_reason.?);
@@ -4161,8 +4157,8 @@ test "ACP auto mode uses automatic review clear and caution without prompting" {
 
     const direct_call: ToolCall = .{
         .id = "direct",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"pwd\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"pwd\"}",
     };
     var direct_review = TestReviewTurn.init("Inspect the workspace.", direct_call);
     const direct = try requestToolPermissionOutcomeWithRequest(
@@ -4184,8 +4180,8 @@ test "ACP auto mode uses automatic review clear and caution without prompting" {
 
     const accepted_call: ToolCall = .{
         .id = "accepted",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"touch accepted.txt\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"touch accepted.txt\"}",
     };
     var accepted_review = TestReviewTurn.init("Create accepted.txt.", accepted_call);
     const accepted = try requestToolPermissionOutcomeWithRequest(&ctx, arena, accepted_call, accepted_review.context(), .auto, &.{}, null, null, &.{});
@@ -4205,8 +4201,8 @@ test "ACP auto mode uses automatic review clear and caution without prompting" {
     fake.decision = .caution;
     const blocked_call: ToolCall = .{
         .id = "check",
-        .name = "terminal",
-        .arguments_json = "{\"action\":\"exec\",\"command\":\"touch check.txt\"}",
+        .name = "shell",
+        .arguments_json = "{\"action\":\"run\",\"command\":\"touch check.txt\"}",
     };
     var blocked_review = TestReviewTurn.init("Check whether this is allowed.", blocked_call);
     const blocked = try requestToolPermissionOutcomeWithRequest(&ctx, arena, blocked_call, blocked_review.context(), .auto, &.{}, null, null, &.{});