@frockbot/plugin-computer 0.3.21 → 0.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-computer",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "private": false,
   "type": "module",
   "exports": {
@@ -29,21 +29,21 @@
   },
   "dependencies": {
     "@cordisjs/client": "0.8.2",
-    "@frockbot/client-core": "0.3.21",
-    "@frockbot/client-ui": "0.3.21",
-    "@frockbot/computer-core": "0.3.21",
-    "@frockbot/computer-host-runtime": "0.3.21",
-    "@frockbot/kernel-agent-loop": "0.3.21",
-    "@frockbot/kernel-contracts": "0.3.21",
-    "@frockbot/plugin-prompt": "0.3.21",
-    "@frockbot/plugin-shell": "0.3.21",
-    "@frockbot/plugin-tools": "0.3.21",
+    "@frockbot/client-core": "0.3.22",
+    "@frockbot/client-ui": "0.3.22",
+    "@frockbot/computer-core": "0.3.22",
+    "@frockbot/computer-host-runtime": "0.3.22",
+    "@frockbot/kernel-agent-loop": "0.3.22",
+    "@frockbot/kernel-contracts": "0.3.22",
+    "@frockbot/plugin-prompt": "0.3.22",
+    "@frockbot/plugin-shell": "0.3.22",
+    "@frockbot/plugin-tools": "0.3.22",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-models": "0.3.21",
-    "@frockbot/plugin-testkit": "0.3.21",
+    "@frockbot/plugin-models": "0.3.22",
+    "@frockbot/plugin-testkit": "0.3.22",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.test.ts

@@ -181,6 +181,82 @@ describe("computer agent contribution", () => {
     await harness.dispose();
   });
 
+  // Production, 2026-09-04: the model sent a `cwd` the tool did not have, the
+  // key was dropped without a word, and `cat server.ts` ran in the home
+  // directory. Four steps went into working that out. The directory is carried
+  // now, and an argument the tool does not know is refused by name.
+  test("computer_exec runs in the cwd it is given and names an argument it does not know", async () => {
+    const requests: Array<{ cwd?: string; command?: string }> = [];
+    const provider: ComputerProvider = {
+      id: "fixture",
+      open: async (identity, tenant, assignment) => ({
+        assignment,
+        identity,
+        tenant,
+        exec: {
+          execute: async (request) => {
+            requests.push({
+              ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
+              ...(request.args?.[1] === undefined
+                ? {}
+                : { command: request.args[1] }),
+            });
+            return {
+              exitCode: 0,
+              stdout: new TextEncoder().encode("server.ts ui.tsx"),
+              stderr: new Uint8Array(),
+              outputTruncated: false,
+            };
+          },
+        },
+        close: () => Promise.resolve(),
+      }),
+    };
+    const harness = await createPluginHarness([
+      ComputerRegistry,
+      ToolRegistry,
+      SystemPromptRegistry,
+      SessionStore,
+    ]);
+    harness.root.computers.register(provider);
+    await harness.mount(
+      createComputerAgentPlugin({
+        userId: "user-1",
+        defaultProviderId: "fixture",
+      }),
+    );
+
+    const listed = await execute(harness, "computer_exec", {
+      command: "ls",
+      cwd: "/home/box/agent-data/source/todo",
+    });
+    expect(listed).toMatchObject({
+      content: "server.ts ui.tsx",
+      isError: false,
+    });
+    expect(requests).toEqual([
+      { cwd: "/home/box/agent-data/source/todo", command: "ls" },
+    ]);
+
+    const relative = await execute(harness, "computer_exec", {
+      command: "ls",
+      cwd: "todo",
+    });
+    expect(relative.isError).toBe(true);
+    expect(relative.content).toContain('"cwd" must be an absolute path');
+
+    const misspelled = await execute(harness, "computer_exec", {
+      command: "ls",
+      directory: "/home/box",
+    });
+    expect(misspelled.isError).toBe(true);
+    expect(misspelled.content).toContain('"directory"');
+    expect(misspelled.content).toContain('It takes "command"');
+    // Refused, never run with the argument quietly dropped.
+    expect(requests).toHaveLength(1);
+    await harness.dispose();
+  });
+
   test("computer_exec during an update returns an actionable tool failure", async () => {
     const provider: ComputerProvider = {
       id: "fixture",

package/src/agent.ts

@@ -266,6 +266,7 @@ function base64Of(bytes: Uint8Array): string {
 interface ExecInput {
   command: string;
   background: boolean;
+  cwd?: string;
 }
 
 function record(input: unknown): Record<string, unknown> | undefined {
@@ -275,17 +276,75 @@ function record(input: unknown): Record<string, unknown> | undefined {
 }
 
 const MAX_EXEC_COMMAND_LENGTH = 20_000;
+/** An absolute path on the Computer, at the Computer host's own path bound. */
+const MAX_EXEC_CWD_LENGTH = 4_096;
+
+/** One shell word, whatever the path holds. */
+function shellQuoteV1(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/** Every key `computer_exec` accepts; anything else is refused by name. */
+const EXEC_INPUT_KEYS = ["command", "background", "cwd"] as const;
 
 function decodeExec(input: unknown): ExecInput | undefined {
   const value = record(input);
-  const command = value?.command;
+  if (!value) return undefined;
+  if (
+    Object.keys(value).some(
+      (key) => !(EXEC_INPUT_KEYS as readonly string[]).includes(key),
+    )
+  ) {
+    return undefined;
+  }
+  const command = value.command;
   if (typeof command !== "string" || !command.trim()) return undefined;
   if (command.length > MAX_EXEC_COMMAND_LENGTH) return undefined;
-  const background = value?.background;
+  const background = value.background;
   if (background !== undefined && typeof background !== "boolean") {
     return undefined;
   }
-  return { command, background: background === true };
+  const cwd = value.cwd;
+  if (cwd !== undefined) {
+    if (typeof cwd !== "string") return undefined;
+    if (!cwd.startsWith("/") || cwd.length > MAX_EXEC_CWD_LENGTH) {
+      return undefined;
+    }
+    if (/[\0\n\r]/.test(cwd)) return undefined;
+  }
+  return {
+    command,
+    background: background === true,
+    ...(typeof cwd === "string" ? { cwd } : {}),
+  };
+}
+
+/**
+ * Why a `computer_exec` input could not be used, in the words that fix it.
+ *
+ * An argument the tool does not know used to be dropped on the way in, so a
+ * `cwd` the model sent was silently ignored and the command ran somewhere else
+ * — four wasted steps on production (2026-09-04) working out why `cat` could
+ * not see a file that was plainly there. An unknown key is refused now, and the
+ * refusal names it, which is the only reason refusing is better than dropping.
+ */
+export function execInputRefusalV1(input: unknown): string {
+  const value = record(input);
+  const unknown = Object.keys(value ?? {}).filter(
+    (key) => !(EXEC_INPUT_KEYS as readonly string[]).includes(key),
+  );
+  if (unknown.length > 0) {
+    return `computer_exec input is invalid: ${unknown
+      .map((key) => `"${key}"`)
+      .join(", ")} ${unknown.length === 1 ? "is not a" : "are not"} field${
+      unknown.length === 1 ? "" : "s"
+    } of this tool. It takes "command", optional "cwd", and optional "background".`;
+  }
+  const cwd = value?.cwd;
+  if (cwd !== undefined && (typeof cwd !== "string" || !cwd.startsWith("/"))) {
+    return `computer_exec input is invalid: "cwd" must be an absolute path of at most ${MAX_EXEC_CWD_LENGTH} characters, such as "/home/box/agent-data".`;
+  }
+  return `computer_exec input is invalid: "command" must be a shell command of at most ${MAX_EXEC_COMMAND_LENGTH} characters.`;
 }
 
 /** The durable root a finished process's log tail is mirrored into. */
@@ -741,6 +800,7 @@ export function createComputerAgentPlugin(
       idempotent: config.idempotentEffects === true,
       description: [
         "Run a shell command in the Bot's selected persistent Computer. New calls are blocked while the user has taken control.",
+        "Pass cwd as an absolute path to run the command in that directory instead of the home directory.",
         "With background:true the command keeps running after this call returns and after this Turn ends, and you get a processId to check later.",
         "A background process runs only while the Computer is awake. Nothing keeps it awake for you: if the Computer hibernates first, the outcome is reported as unknown, with whatever log was durable at the time.",
         `${SCRATCH_ROOT} (also $FROCKBOT_SCRATCH) is scratch shared with your User's other Bots: it survives hibernation but is not durable and never reaches storage, so keep nothing there you cannot lose.`,
@@ -750,6 +810,12 @@ export function createComputerAgentPlugin(
         type: "object",
         properties: {
           command: { type: "string", maxLength: MAX_EXEC_COMMAND_LENGTH },
+          cwd: {
+            type: "string",
+            maxLength: MAX_EXEC_CWD_LENGTH,
+            description:
+              "Absolute path to run the command in. Defaults to the Bot's home directory.",
+          },
           background: {
             type: "boolean",
             description:
@@ -759,14 +825,15 @@ export function createComputerAgentPlugin(
         required: ["command"],
         additionalProperties: false,
       },
-      validate: (input) => decodeExec(input) !== undefined,
+      // Deliberately permissive, for the same reason `computer_browser` is: a
+      // wrong shape reaches `execute`, which names the field. A `false` here is
+      // the loop's generic "Invalid input for tool", which names nothing.
+      validate: (input) => !!record(input),
       execute: async (input, context) => {
         const decoded = decodeExec(input);
-        if (!decoded)
-          return {
-            content: `A command of at most ${MAX_EXEC_COMMAND_LENGTH} characters is required`,
-            isError: true,
-          };
+        if (!decoded) {
+          return { content: execInputRefusalV1(input), isError: true };
+        }
         // "The GUI is never driven from the shell" (parity row 33), refused at
         // the seam where the model can be told why. This is policy and not a
         // boundary — a regex over a shell string is defeatable, and the
@@ -779,7 +846,15 @@ export function createComputerAgentPlugin(
         }
         if (decoded.background) {
           return processes
-            ? launchBackground(decoded.command, context)
+            ? // A launch carries a command and not a directory, so the
+              // directory becomes part of the command. `cd` failing stops the
+              // process before it starts, which is what a wrong path deserves.
+              launchBackground(
+                decoded.cwd
+                  ? `cd ${shellQuoteV1(decoded.cwd)} && ${decoded.command}`
+                  : decoded.command,
+                context,
+              )
             : {
                 content:
                   "A background process is recorded before it is launched; this runtime has nowhere durable to record it",
@@ -800,6 +875,7 @@ export function createComputerAgentPlugin(
                 {
                   executable: "/bin/bash",
                   args: ["-lc", decoded.command],
+                  ...(decoded.cwd ? { cwd: decoded.cwd } : {}),
                   timeoutMs: 120_000,
                   maxOutputBytes: 30_000,
                 },