apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/tools/bash.js

@@ -11,7 +11,10 @@ import { waitForChildProcess } from "../../utils/child-process.js";
 import { getShellConfig, getShellEnv, killProcessTree, trackDetachedChildPid, untrackDetachedChildPid, } from "../../utils/shell.js";
 import { setApexEnvironment } from "../environment.js";
 import { getExperimentalToolSampling } from "../experimental.js";
+import { escalationRootFor, extractRefusedPath, looksLikeSandboxRefusal, requestCommandEscalation, } from "../sandbox/rpc/command-client.js";
+import { createBackgroundShellRegistry } from "./background-shell.js";
 import { classifyBashCommand } from "./bash-command-segments.js";
+import { toolUnion } from "./contract.js";
 import { OutputAccumulator } from "./output-accumulator.js";
 import { getTextOutput, invalidArgText, str } from "./render-utils.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
@@ -30,10 +33,26 @@ function resolveTimeoutMs(timeout) {
     }
     return timeoutMs;
 }
-const bashSchema = Type.Object({
-    command: Type.String({ description: "Bash command to execute" }),
+const bashSchemaProperties = {
+    command: Type.String({ description: "Shell command to execute" }),
     timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
-});
+    background: Type.Optional(Type.Boolean({
+        description: "Run in the background and return a handle immediately. Retrieve with { handle }; kill with { handle, kill: true }.",
+    })),
+    handle: Type.String({
+        description: "Handle from a background launch. Supply it alone to retrieve output and status; add kill: true to terminate.",
+    }),
+    kill: Type.Literal(true, { description: "Set to true with a background handle to terminate its command." }),
+};
+const bashSchema = toolUnion([
+    Type.Object({
+        command: Type.String(),
+        timeout: Type.Optional(Type.Number()),
+        background: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object({ handle: Type.String() }),
+    Type.Object({ handle: Type.String(), kill: Type.Literal(true) }),
+], bashSchemaProperties);
 export const bashToolSystemPromptContribution = {
     snippet: "Execute bash commands (ls, grep, find, etc.)",
     guidelines: ["You can inspect PI_* environment variables for current model and session details."],
@@ -48,9 +67,13 @@ function normalizeSegment(text) {
  * matches `git commit` and `git commit -m x`, but not `git commitment` (word
  * boundary enforced) and not an unrelated segment in the same chained command.
  */
+function hasGrammarSensitiveStructure(value) {
+    return /["'\\\t\n#]/.test(value);
+}
 function segmentMatchesRule(segment, ruleContent) {
-    const normalizedSegment = normalizeSegment(segment);
-    const normalizedRule = normalizeSegment(ruleContent);
+    const sensitive = hasGrammarSensitiveStructure(segment) || hasGrammarSensitiveStructure(ruleContent);
+    const normalizedSegment = sensitive ? segment : normalizeSegment(segment);
+    const normalizedRule = sensitive ? ruleContent : normalizeSegment(ruleContent);
     if (normalizedRule.endsWith(":*")) {
         const prefix = normalizedRule.slice(0, -2).trim();
         if (!prefix)
@@ -71,45 +94,78 @@ function segmentMatchesRule(segment, ruleContent) {
  * one would either over-authorize (if loose) or be indistinguishable from an exact
  * match (if not) — `null` correctly forces `ask` for "always allow this" on a chain.
  */
+/**
+ * Reserved rule content for retrieve/kill calls on background handles. These
+ * perform no new execution -- the command they operate on was already gated at
+ * launch -- so `defaultBehaviorFor` allows them when no rule matches, while a
+ * `Bash(background-handle)` rule (allow *or* deny) still governs them
+ * explicitly.
+ */
+const BACKGROUND_HANDLE_RULE = "background-handle";
 export function createBashPermissionSpec() {
     return {
         defaultBehavior: "ask",
+        defaultBehaviorFor(params) {
+            return "command" in params ? undefined : "allow";
+        },
         matches(ruleContent, params) {
+            if (!("command" in params))
+                return ruleContent === BACKGROUND_HANDLE_RULE;
             const classification = classifyBashCommand(params.command);
-            if (classification.type !== "segments")
-                return false;
-            return classification.segments.every((segment) => segmentMatchesRule(segment, ruleContent));
+            return (classification.type === "segments" &&
+                classification.segments.every((segment) => segmentMatchesRule(segment, ruleContent)));
+        },
+        matchesDeny(ruleContent, params) {
+            if (!("command" in params))
+                return ruleContent === BACKGROUND_HANDLE_RULE;
+            const classification = classifyBashCommand(params.command);
+            return (classification.type === "segments" &&
+                classification.segments.some((segment) => segmentMatchesRule(segment, ruleContent)));
+        },
+        isUnknown(params) {
+            return "command" in params && classifyBashCommand(params.command).type !== "segments";
         },
         describe(ruleContent) {
+            if (ruleContent === BACKGROUND_HANDLE_RULE) {
+                return "Retrieve or kill background shell commands";
+            }
             return `Run bash commands matching "${ruleContent}"`;
         },
+        previewCall(params) {
+            // The command string is the entire effect being authorized. There is
+            // nothing to read and nothing to summarise: showing it exactly, including
+            // whitespace the rule grammar treats as significant, is the preview.
+            if (!("command" in params)) {
+                return { kind: "summary", lines: ["Retrieve or kill a background shell command"] };
+            }
+            return { kind: "summary", lines: [String(params.command)] };
+        },
         ruleForCall(params) {
+            if (!("command" in params)) {
+                return BACKGROUND_HANDLE_RULE;
+            }
             const classification = classifyBashCommand(params.command);
             if (classification.type !== "segments" || classification.segments.length !== 1)
                 return null;
-            return normalizeSegment(classification.segments[0]);
+            const segment = classification.segments[0];
+            return hasGrammarSensitiveStructure(segment) ? segment : normalizeSegment(segment);
         },
     };
 }
-/**
- * Create bash operations using pi's built-in local shell execution backend.
- *
- * This is useful for extensions that intercept user_bash and still want pi's
- * standard local shell behavior while wrapping or rewriting commands.
- */
-export function createLocalBashOperations(options) {
+/** Shared process execution used by the built-in shell tools. */
+export function createLocalShellOperations(shellName, resolveShellConfig) {
     return {
         exec: async (command, cwd, { onData, signal, timeout, env }) => {
             const timeoutMs = resolveTimeoutMs(timeout);
             if (signal?.aborted) {
                 throw new Error("aborted");
             }
-            const shellConfig = getShellConfig(options?.shellPath);
+            const shellConfig = resolveShellConfig();
             try {
                 await fsAccess(cwd, constants.F_OK);
             }
             catch {
-                throw new Error(`Working directory does not exist: ${cwd}\nCannot execute bash commands.`);
+                throw new Error(`Working directory does not exist: ${cwd}\nCannot execute ${shellName} commands.`);
             }
             const commandFromStdin = shellConfig.commandTransport === "stdin";
             const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
@@ -174,8 +230,47 @@ export function createLocalBashOperations(options) {
                     signal.removeEventListener("abort", onAbort);
             }
         },
+        spawnBackground: async (command, cwd, { onData, env }) => {
+            const shellConfig = resolveShellConfig();
+            try {
+                await fsAccess(cwd, constants.F_OK);
+            }
+            catch {
+                throw new Error(`Working directory does not exist: ${cwd}\nCannot execute ${shellName} commands.`);
+            }
+            const commandFromStdin = shellConfig.commandTransport === "stdin";
+            const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
+                cwd,
+                detached: process.platform !== "win32",
+                env: env ?? getShellEnv(),
+                stdio: [commandFromStdin ? "pipe" : "ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            if (commandFromStdin) {
+                child.stdin?.on("error", () => { });
+                child.stdin?.end(command);
+            }
+            if (child.pid)
+                trackDetachedChildPid(child.pid);
+            child.stdout?.on("data", onData);
+            child.stderr?.on("data", onData);
+            const exited = waitForChildProcess(child).finally(() => {
+                if (child.pid)
+                    untrackDetachedChildPid(child.pid);
+            });
+            return { pid: child.pid, exited };
+        },
     };
 }
+/**
+ * Create bash operations using pi's built-in local shell execution backend.
+ *
+ * This is useful for extensions that intercept user_bash and still want pi's
+ * standard local shell behavior while wrapping or rewriting commands.
+ */
+export function createLocalBashOperations(options) {
+    return createLocalShellOperations("bash", () => getShellConfig(options?.shellPath));
+}
 function resolveSpawnContext(command, cwd, spawnHook, exposeSessionEnvironment, ctx) {
     const env = { ...getShellEnv() };
     setApexEnvironment("APEX_CODE_SESSION_ID", undefined, env);
@@ -211,12 +306,17 @@ class BashResultRenderComponent extends Container {
 function formatDuration(ms) {
     return `${(ms / 1000).toFixed(1)}s`;
 }
-function formatBashCall(args) {
+function formatShellCall(args, prompt) {
     const command = str(args?.command);
+    const handle = str(args?.handle);
+    if (!command && handle) {
+        const suffix = args?.kill === true ? " · kill" : "";
+        return theme.fg("toolTitle", theme.bold(`${prompt} ${handle}${suffix}`));
+    }
     const timeout = args?.timeout;
     const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
     const commandDisplay = command === null ? invalidArgText(theme) : command ? command : theme.fg("toolOutput", "...");
-    return theme.fg("toolTitle", theme.bold(`$ ${commandDisplay}`)) + timeoutSuffix;
+    return theme.fg("toolTitle", theme.bold(`${prompt} ${commandDisplay}`)) + timeoutSuffix;
 }
 function rebuildBashResultRenderComponent(component, result, options, showImages, startedAt, endedAt) {
     const state = component.state;
@@ -283,17 +383,63 @@ function rebuildBashResultRenderComponent(component, result, options, showImages
         component.addChild(new Text(`\n${theme.fg("muted", `${label} ${formatDuration(endTime - startedAt)}`)}`, 0, 0));
     }
 }
-export function createBashToolDefinition(cwd, options) {
+export function createShellToolDefinition(cwd, config, options) {
     const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });
     const commandPrefix = options?.commandPrefix;
     const exposeSessionEnvironment = options?.exposeSessionEnvironment ?? true;
     const spawnHook = options?.spawnHook;
+    const registry = options?.backgroundRegistry ?? createBackgroundShellRegistry();
+    // Background handle calls (retrieve and kill) never touch the foreground
+    // execution path, so the post-hoc escalation offer below is unreachable from
+    // them by construction; the refusal note in `executeHandleCall` tells the
+    // model a foreground rerun gets the offer (spec, Non-goals).
+    const unknownHandleError = (handle) => {
+        const known = registry.handles();
+        return new ToolExecutionError(`Unknown background handle: ${handle}.${known.length > 0 ? ` Known handles: ${known.join(", ")}` : " No background commands have been launched."}`, undefined);
+    };
+    const executeHandleCall = async (handleInput) => {
+        if ("kill" in handleInput && handleInput.kill) {
+            const status = registry.kill(handleInput.handle);
+            if (!status)
+                throw unknownHandleError(handleInput.handle);
+            const state = status.running ? "kill signal sent" : `already exited (code ${status.exitCode})`;
+            return {
+                content: [{ type: "text", text: `[background] ${handleInput.handle}: ${state}` }],
+                details: undefined,
+            };
+        }
+        const retrieved = await registry.retrieve(handleInput.handle);
+        if (!retrieved)
+            throw unknownHandleError(handleInput.handle);
+        const { status, snapshot } = retrieved;
+        const elapsed = ((Date.now() - status.startedAt) / 1000).toFixed(1);
+        const header = status.running
+            ? `[background] ${handleInput.handle}: running ${elapsed}s`
+            : `[background] ${handleInput.handle}: ${status.killed ? "killed" : "exited"} (code ${status.exitCode}) after ${elapsed}s`;
+        let text = `${header}\n\n${snapshot.content || "(no output)"}`;
+        const truncation = snapshot.truncation;
+        if (truncation.truncated && snapshot.fullOutputPath) {
+            const startLine = truncation.totalLines - truncation.outputLines + 1;
+            text += `\n\n[Showing lines ${startLine}-${truncation.totalLines} of ${truncation.totalLines}. Full output: ${snapshot.fullOutputPath}]`;
+        }
+        if (!status.running && looksLikeSandboxRefusal(snapshot.content)) {
+            text += `\n\n[Sandbox refusal: background runs are not offered escalation. Rerun this command in the foreground to get the escalation offer.]`;
+        }
+        return {
+            content: [{ type: "text", text }],
+            details: {
+                truncation: truncation.truncated ? truncation : undefined,
+                fullOutputPath: snapshot.fullOutputPath,
+                execution: { cwd, exitCode: status.exitCode ?? null },
+            },
+        };
+    };
     return {
-        name: "bash",
-        label: "bash",
-        description: `Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
-        promptSnippet: bashToolSystemPromptContribution.snippet,
-        promptGuidelines: exposeSessionEnvironment ? [...bashToolSystemPromptContribution.guidelines] : undefined,
+        name: config.name,
+        label: config.label,
+        description: `Execute a ${config.shellName} command in the current working directory. Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
+        promptSnippet: config.promptSnippet,
+        promptGuidelines: exposeSessionEnvironment && config.promptGuidelines ? [...config.promptGuidelines] : undefined,
         parameters: bashSchema,
         contract: {
             capabilities: new Set(["exec"]),
@@ -303,17 +449,48 @@ export function createBashToolDefinition(cwd, options) {
                 emits: new Set(["command"]),
                 capture: (params, result) => {
                     const execution = result.details?.execution;
-                    return execution
-                        ? [{ kind: "command", command: params.command, ...execution }]
-                        : [{ kind: "command", command: params.command }];
+                    // Retrieve and kill calls carry a handle; resolve it back to the
+                    // command that produced the output so the record shows what ran.
+                    const command = "command" in params ? params.command : (registry.commandFor(params.handle) ?? params.handle);
+                    return execution ? [{ kind: "command", command, ...execution }] : [{ kind: "command", command }];
                 },
             },
         },
         constrainedSampling: getExperimentalToolSampling(),
-        async execute(_toolCallId, { command, timeout }, signal, onUpdate, ctx) {
+        async execute(_toolCallId, input, signal, onUpdate, ctx) {
+            if ("handle" in input) {
+                return await executeHandleCall(input);
+            }
+            const { command, timeout, background } = input;
             const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
             const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook, exposeSessionEnvironment, ctx);
-            const output = new OutputAccumulator({ tempFilePrefix: "apex-code-bash" });
+            if (background) {
+                const spawnBg = ops.spawnBackground;
+                if (!spawnBg) {
+                    throw new ToolExecutionError("This shell backend does not support background execution. Run the command in the foreground instead.", undefined);
+                }
+                const output = new OutputAccumulator({ tempFilePrefix: config.tempFilePrefix });
+                const launched = await spawnBg(spawnContext.command, spawnContext.cwd, {
+                    env: spawnContext.env,
+                    onData: (data) => output.append(data),
+                });
+                const handle = registry.launch({
+                    command: spawnContext.command,
+                    pid: launched.pid,
+                    output,
+                    exited: launched.exited,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `[background] launched with handle ${handle}\nRetrieve its output: { "handle": "${handle}" }\nKill it: { "handle": "${handle}", "kill": true }`,
+                        },
+                    ],
+                    details: { execution: { cwd: spawnContext.cwd, exitCode: null } },
+                };
+            }
+            const output = new OutputAccumulator({ tempFilePrefix: config.tempFilePrefix });
             let acceptingOutput = true;
             let updateTimer;
             let updateDirty = false;
@@ -432,6 +609,24 @@ export function createBashToolDefinition(cwd, options) {
                 const { text: outputText, details } = formatOutput(snapshot);
                 const resultDetails = { ...details, execution };
                 if (exitCode !== 0 && exitCode !== null) {
+                    // The OS boundary refuses a write in the kernel, so by the time this runs
+                    // the syscall has already failed and nothing inside this namespace can
+                    // widen it. Offering the command to the supervisor is the only remaining
+                    // move, and it is the supervisor that shows the human the exact command
+                    // and root before anything runs -- so a wrong guess at the path is
+                    // refused by someone reading it, never granted quietly.
+                    const escalated = await escalateRefusedCommand(command, outputText);
+                    if (escalated) {
+                        // The reported exit code has to be the escalated run's, not the
+                        // refused one's. Leaving the original would have the details say the
+                        // command failed while the content says it succeeded, and anything
+                        // reading the facts rather than the text would disagree with the
+                        // model about what happened.
+                        return {
+                            content: [{ type: "text", text: escalated.text }],
+                            details: { ...resultDetails, execution: { ...execution, exitCode: 0 } },
+                        };
+                    }
                     throw new ToolExecutionError(appendStatus(outputText, `Command exited with code ${exitCode}`), {
                         execution,
                     });
@@ -449,7 +644,7 @@ export function createBashToolDefinition(cwd, options) {
                 state.endedAt = undefined;
             }
             const text = context.lastComponent ?? new Text("", 0, 0);
-            text.setText(formatBashCall(args));
+            text.setText(formatShellCall(args, config.prompt));
             return text;
         },
         renderResult(result, options, _theme, context) {
@@ -471,6 +666,18 @@ export function createBashToolDefinition(cwd, options) {
         },
     };
 }
+const bashToolConfig = {
+    name: "bash",
+    label: "bash",
+    shellName: "bash",
+    prompt: "$",
+    promptSnippet: bashToolSystemPromptContribution.snippet,
+    promptGuidelines: bashToolSystemPromptContribution.guidelines,
+    tempFilePrefix: "apex-code-bash",
+};
+export function createBashToolDefinition(cwd, options) {
+    return createShellToolDefinition(cwd, bashToolConfig, options);
+}
 export function createBashTool(cwd, options) {
     const definition = createBashToolDefinition(cwd, options);
     const tool = wrapToolDefinition(definition);
@@ -480,4 +687,29 @@ export function createBashTool(cwd, options) {
     });
     return tool;
 }
+/**
+ * Offer a command the sandbox refused to the supervisor, once.
+ *
+ * Returns the escalated output when a human approved it and it ran, and undefined for
+ * every other outcome -- no channel, no recognisable refusal, no path in the message, a
+ * refused prompt -- because the caller's behaviour is the same in all of them: report
+ * what originally happened.
+ */
+async function escalateRefusedCommand(command, output) {
+    if (!looksLikeSandboxRefusal(output))
+        return undefined;
+    const refusedPath = extractRefusedPath(output);
+    if (!refusedPath)
+        return undefined;
+    const outcome = await requestCommandEscalation({ command, writableRoot: escalationRootFor(refusedPath) });
+    if (!outcome || outcome.code !== 0)
+        return undefined;
+    const combined = [outcome.stdout, outcome.stderr]
+        .filter((part) => part.length > 0)
+        .join("\n")
+        .trim();
+    // A silent success still has to say something, or the model reads an empty result as
+    // the command having had no effect.
+    return { text: combined.length > 0 ? combined : "Command ran with approved escalated access." };
+}
 //# sourceMappingURL=bash.js.map