@frockbot/plugin-computer 0.3.20 → 0.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-computer",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "private": false,
   "type": "module",
   "exports": {
@@ -29,21 +29,21 @@
   },
   "dependencies": {
     "@cordisjs/client": "0.8.2",
-    "@frockbot/client-core": "0.3.20",
-    "@frockbot/client-ui": "0.3.20",
-    "@frockbot/computer-core": "0.3.20",
-    "@frockbot/computer-host-runtime": "0.3.20",
-    "@frockbot/kernel-agent-loop": "0.3.20",
-    "@frockbot/kernel-contracts": "0.3.20",
-    "@frockbot/plugin-prompt": "0.3.20",
-    "@frockbot/plugin-shell": "0.3.20",
-    "@frockbot/plugin-tools": "0.3.20",
+    "@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.20",
-    "@frockbot/plugin-testkit": "0.3.20",
+    "@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

@@ -14,6 +14,7 @@ import { SessionStore } from "@frockbot/kernel-contracts";
 import manifest from "../frockbot.json" with { type: "json" };
 import packageJson from "../package.json" with { type: "json" };
 import {
+  COMPUTER_OVERLOADED_TOOL_MESSAGE_V1,
   createComputerAgentPlugin,
   HUMAN_CONTROL_PROMPT_LINE,
 } from "./agent.js";
@@ -180,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",
@@ -223,6 +300,50 @@ describe("computer agent contribution", () => {
     await harness.dispose();
   });
 
+  test("computer_exec maps overloaded transport failures to one bounded plain reason", async () => {
+    for (const message of [
+      "Computer command failed: WebSocket keepalive timeout after 45000ms",
+      "The Computer effect was cancelled",
+    ]) {
+      const provider: ComputerProvider = {
+        id: "fixture",
+        open: async (identity, tenant, assignment) => ({
+          assignment,
+          identity,
+          tenant,
+          exec: {
+            execute: () => Promise.reject(new Error(message)),
+          },
+          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",
+        }),
+      );
+
+      await expect(
+        execute(harness, "computer_exec", { command: "pwd" }),
+      ).resolves.toEqual({
+        content: COMPUTER_OVERLOADED_TOOL_MESSAGE_V1,
+        isError: true,
+      });
+      expect(COMPUTER_OVERLOADED_TOOL_MESSAGE_V1.length).toBeLessThanOrEqual(
+        160,
+      );
+      await harness.dispose();
+    }
+  });
+
   test("injects and records the human-control line only while the durable lease is fresh", async () => {
     const records = new Map<string, unknown>([
       [

package/src/agent.ts

@@ -153,6 +153,48 @@ export interface ComputerAgentPluginConfig {
 export const HUMAN_CONTROL_PROMPT_LINE =
   "Your User is currently controlling the Computer; do not use it this Turn.";
 
+/** Bounded copy for the two transport failures an overloaded Sprite emits. */
+export const COMPUTER_OVERLOADED_TOOL_MESSAGE_V1 =
+  "The Computer is overloaded; a browser tab using too much memory was closed. Try again.";
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isOverloadedTransportFailure(error: unknown): boolean {
+  const message = errorMessage(error).toLowerCase();
+  return (
+    message.includes("websocket keepalive timeout") ||
+    message.includes("computer effect was cancelled")
+  );
+}
+
+/** A local HTTP origin an Applet preview can own; public sites never qualify. */
+export function localPreviewOriginV1(value: string): string | undefined {
+  try {
+    const url = new URL(value);
+    const local = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+    return local && (url.protocol === "http:" || url.protocol === "https:")
+      ? url.origin
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function localPreviewOriginsV1(value: string): string[] {
+  const found = new Set<string>();
+  for (const match of value.matchAll(/https?:\/\/[^\s"'<>]+/g)) {
+    const origin = localPreviewOriginV1(match[0].replace(/[),.;!?]+$/g, ""));
+    if (origin) found.add(origin);
+  }
+  return [...found];
+}
+
+function runsAppletPreviewV1(command: string): boolean {
+  return /(?:^|[\s;&|])(?:[^\s;&|]*\/)?applet\s+dev(?:\s|$)/.test(command);
+}
+
 /** The wake-free, Turn-scoped projection shared by prompt render and its log. */
 class ComputerControlPromptProjection {
   #line = "";
@@ -224,6 +266,7 @@ function base64Of(bytes: Uint8Array): string {
 interface ExecInput {
   command: string;
   background: boolean;
+  cwd?: string;
 }
 
 function record(input: unknown): Record<string, unknown> | undefined {
@@ -233,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. */
@@ -345,6 +446,9 @@ function decodeBrowser(input: unknown): ComputerBrowserAction | undefined {
 }
 
 function failure(error: unknown): { content: string; isError: true } {
+  if (isOverloadedTransportFailure(error)) {
+    return { content: COMPUTER_OVERLOADED_TOOL_MESSAGE_V1, isError: true };
+  }
   if (error instanceof ComputerError) {
     if (error.code === "human-control-active") {
       // The holder is named, so a second Bot of the same User — and the User
@@ -367,7 +471,7 @@ function failure(error: unknown): { content: string; isError: true } {
     return { content: error.message, isError: true };
   }
   return {
-    content: error instanceof Error ? error.message : String(error),
+    content: errorMessage(error),
     isError: true,
   };
 }
@@ -621,6 +725,8 @@ export function createComputerAgentPlugin(
     // Agent loop knows it; a tool context does not, so it is caught where the
     // loop already announces it.
     let currentTurn = 1;
+    /** Local preview origins this Bot navigated to during the current Turn. */
+    const previewOrigins = new Set<string>();
     // One cadence per mounted plugin, which is one per Turn: a Turn's first
     // Computer action always gets its capture, and the rest are debounced.
     const progressCadence = createComputerCaptureCadenceV1(
@@ -660,6 +766,24 @@ export function createComputerAgentPlugin(
       await selfCheck(computer, botId, signal);
       return computer;
     };
+    const closePreviewTabs = async (
+      computer: ComputerHandle,
+      origins: readonly string[],
+      effectId: string,
+      signal?: AbortSignal,
+    ): Promise<void> => {
+      if (!computer.browser) return;
+      const unique = [...new Set(origins)];
+      for (let offset = 0; offset < unique.length; offset += 16) {
+        await computer.browser.perform(
+          { type: "close-origins", origins: unique.slice(offset, offset + 16) },
+          {
+            ...(signal ? { signal } : {}),
+            effectId: `${effectId}:${Math.floor(offset / 16)}`,
+          },
+        );
+      }
+    };
 
     const execTool: ToolDefinition = {
       name: "computer_exec",
@@ -676,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.`,
@@ -685,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:
@@ -694,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
@@ -714,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",
@@ -735,6 +875,7 @@ export function createComputerAgentPlugin(
                 {
                   executable: "/bin/bash",
                   args: ["-lc", decoded.command],
+                  ...(decoded.cwd ? { cwd: decoded.cwd } : {}),
                   timeoutMs: 120_000,
                   maxOutputBytes: 30_000,
                 },
@@ -1039,6 +1180,22 @@ export function createComputerAgentPlugin(
               // A mirror that could not be written never withholds an outcome
               // that was read.
             }
+            if (
+              action === "stop" &&
+              runsAppletPreviewV1(held.command) &&
+              computer.browser
+            ) {
+              const origins = localPreviewOriginsV1(observed.logTail);
+              if (origins.length > 0) {
+                await closePreviewTabs(
+                  computer,
+                  origins,
+                  `${context.effectId}:close-preview-tabs`,
+                  context.signal,
+                );
+                for (const origin of origins) previewOrigins.delete(origin);
+              }
+            }
             if (action === "logs") {
               return {
                 content: observed.logTail || "(no output yet)",
@@ -1355,7 +1512,7 @@ export function createComputerAgentPlugin(
         subagentRoles: ["executor", "computerUse"],
       },
       description:
-        "Run the Computer's self-check and read the report: disk, the shared scratch, the desktop gateway, your display, the browser profile and what the browser announces itself as, the durable-root sync and its conflicts, the reference docs, the browser launcher, the clock, and DNS. Read-only; it changes nothing and repairs nothing.",
+        "Run the Computer's self-check and read the report: disk, the shared scratch, the desktop gateway, your display, the browser profile, renderer-watchdog actions, top memory consumers, the durable-root sync and its conflicts, the reference docs, the browser launcher, the clock, and DNS. Read-only; it changes nothing and repairs nothing.",
       inputSchema: {
         type: "object",
         properties: {},
@@ -1575,6 +1732,10 @@ export function createComputerAgentPlugin(
                 signal: context.signal,
                 effectId: context.effectId,
               });
+              if (action.type === "navigate") {
+                const origin = localPreviewOriginV1(action.url);
+                if (origin) previewOrigins.add(origin);
+              }
               await fileProgressCapture(computer, context.botId, context);
               return {
                 content: result.accessibilitySnapshot,
@@ -1605,6 +1766,7 @@ export function createComputerAgentPlugin(
       ctx.on("agent/pre-step", async (agent, _inputs, turn, _step, next) => {
         if (turn !== currentTurn) {
           projectionWrites.clear();
+          previewOrigins.clear();
           // Every Turn's first Computer action is worth a capture, however
           // soon after the previous Turn's last one it happens.
           progressCadence.reset();
@@ -1630,6 +1792,15 @@ export function createComputerAgentPlugin(
           return;
         }
         try {
+          if (computer.browser && previewOrigins.size > 0) {
+            const origins = [...previewOrigins];
+            await closePreviewTabs(
+              computer,
+              origins,
+              `computer:${writer?.runId ?? agent.session.id}:${turn}:close-preview-tabs`,
+            );
+            previewOrigins.clear();
+          }
           if (writer && computer.workspace) {
             const root: WorkspaceRootV1 = {
               kind: "package-declared",
@@ -1681,7 +1852,7 @@ export function createComputerAgentPlugin(
             "Use computer_exec to inspect the filesystem before claiming that a path or file exists.",
             "Use computer_screenshot to see your own desktop; each capture is filed in your durable screenshots root.",
             "For a job that outlasts this Turn, use computer_exec with background:true and check it later with computer_process_check. Do not poll it in a loop.",
-            "Use computer_doctor when the Computer misbehaves; it reports disk, desktop, sync, and network in one read-only call.",
+            "Use computer_doctor when the Computer misbehaves; it reports disk, desktop, renderer-watchdog actions, top memory consumers, sync, and network in one read-only call.",
             ...(controlPrompt?.current() ? [controlPrompt.current()] : []),
             "Never invent a directory listing.",
           ].join("\n"),

package/src/processes.test.ts

@@ -92,6 +92,20 @@ function fakeComputer(options: { launchFails?: boolean } = {}): Computer {
             },
             generation: () => Promise.resolve(computer.generation),
           },
+          browser: {
+            perform: (action) => {
+              const cleanup = action as {
+                type: string;
+                origins?: readonly string[];
+              };
+              calls.push(
+                cleanup.type === "close-origins"
+                  ? `browser:close-origins:${cleanup.origins?.join(",") ?? ""}`
+                  : `browser:${cleanup.type}`,
+              );
+              return Promise.resolve({ accessibilitySnapshot: "" });
+            },
+          },
           close: () => Promise.resolve(),
         }),
     },
@@ -418,4 +432,69 @@ describe("stopping a background process", () => {
     ]);
     await harness.dispose();
   });
+
+  test("closes the Bot's tabs on an applet dev origin when its process stops", async () => {
+    const computer = fakeComputer();
+    const held = storage();
+    const harness = await mount(computer, held);
+    const launched = JSON.parse(
+      (
+        await call(harness, "computer_exec", {
+          command: "applet dev --port 8787",
+          background: true,
+        })
+      ).content,
+    ) as { processId: string };
+    await call(harness, "computer_browser", {
+      action: "navigate",
+      url: "http://127.0.0.1:8787/",
+    });
+    computer.state = {
+      alive: false,
+      exitCode: 143,
+      logTail: "http://127.0.0.1:8787/\nterminated",
+    };
+
+    const stopped = await call(harness, "computer_process_stop", {
+      processId: launched.processId,
+    });
+
+    expect(stopped.isError).toBe(false);
+    expect(computer.calls).toEqual([
+      `launch:${launched.processId}:applet dev --port 8787`,
+      "browser:navigate",
+      `stop:${launched.processId}`,
+      "browser:close-origins:http://127.0.0.1:8787",
+    ]);
+    await harness.dispose();
+  });
+});
+
+describe("releasing a Bot's Turn", () => {
+  test("closes local preview origins the Bot navigated during the Turn", async () => {
+    const computer = fakeComputer();
+    const harness = await mount(computer, storage());
+    const session = harness.root.sessions.create("session-1");
+    const agent = { botId: "bot-1", session };
+    await harness.root.waterfall(
+      "agent/pre-step",
+      agent as never,
+      [],
+      1,
+      1,
+      () => Promise.resolve({ kind: "enter" as const, inputs: [] }),
+    );
+    await call(harness, "computer_browser", {
+      action: "navigate",
+      url: "http://localhost:8787/preview",
+    });
+
+    await harness.root.serial("agent/turn-stopping", agent as never, 1);
+
+    expect(computer.calls).toEqual([
+      "browser:navigate",
+      "browser:close-origins:http://localhost:8787",
+    ]);
+    await harness.dispose();
+  });
 });