@frockbot/plugin-computer 0.2.4 → 0.3.0

package/src/protocol.ts

@@ -9,6 +9,7 @@ export const COMPUTER_COMMAND_TYPES = [
   "releaseControl",
   "refreshControl",
   "refreshViewer",
+  "closeViewer",
   "runDoctor",
 ] as const;
 
@@ -70,6 +71,15 @@ export interface ComputerProgressStepViewV1 {
   status: ComputerProgressStepStatusV1;
 }
 
+export interface ComputerProvisioningProgressViewV1 {
+  version: 1;
+  kind: "provision" | "update";
+  label: string;
+  index: number;
+  total: number;
+  resumed: boolean;
+}
+
 /** Durable progress projected from the Bot authority; it contains no secrets. */
 export interface ComputerProgressViewV1 {
   version: 1;
@@ -78,6 +88,7 @@ export interface ComputerProgressViewV1 {
   updatedAt: string;
   index: number;
   total: number;
+  provisioning?: ComputerProvisioningProgressViewV1;
   steps: ComputerProgressStepViewV1[];
 }
 
@@ -136,6 +147,22 @@ export type ComputerCommandReceiptV1 =
       failure: string;
     };
 
+/**
+ * A connect command has been durably admitted and scheduled. Version 2 is a
+ * distinct wire shape from the terminal version 1 receipt: it never claims
+ * that the Computer effect has completed.
+ */
+export interface ComputerCommandAcceptedV2 {
+  version: 2;
+  commandId: string;
+  type: "connect";
+  status: "accepted";
+  admittedAt: string;
+}
+
+export type ComputerCommandResponse =
+  ComputerCommandReceiptV1 | ComputerCommandAcceptedV2;
+
 export class ComputerProtocolDecodeError extends Error {
   override readonly name = "ComputerProtocolDecodeError";
 }
@@ -238,6 +265,46 @@ function decodeProgressStepV1(value: unknown): ComputerProgressStepViewV1 {
   };
 }
 
+function decodeProvisioningProgressV1(
+  value: unknown,
+): ComputerProvisioningProgressViewV1 {
+  const candidate = record(value, "Computer provisioning progress");
+  exactKeys(
+    candidate,
+    ["version", "kind", "label", "index", "total", "resumed"],
+    [],
+    "Computer provisioning progress",
+  );
+  if (
+    candidate.version !== 1 ||
+    (candidate.kind !== "provision" && candidate.kind !== "update") ||
+    typeof candidate.resumed !== "boolean"
+  ) {
+    throw new ComputerProtocolDecodeError(
+      "Computer provisioning progress is invalid",
+    );
+  }
+  const total = boundedInteger(
+    candidate.total,
+    1,
+    1_000,
+    "Computer provisioning progress total",
+  );
+  return {
+    version: 1,
+    kind: candidate.kind,
+    label: text(candidate.label, "Computer provisioning progress label"),
+    index: boundedInteger(
+      candidate.index,
+      0,
+      total,
+      "Computer provisioning progress index",
+    ),
+    total,
+    resumed: candidate.resumed,
+  };
+}
+
 export function decodeComputerProgressViewV1(
   value: unknown,
 ): ComputerProgressViewV1 {
@@ -245,7 +312,7 @@ export function decodeComputerProgressViewV1(
   exactKeys(
     candidate,
     ["version", "kind", "startedAt", "updatedAt", "index", "total", "steps"],
-    [],
+    ["provisioning"],
     "Computer progress",
   );
   if (
@@ -282,6 +349,11 @@ export function decodeComputerProgressViewV1(
     updatedAt: timestamp(candidate.updatedAt, "Computer progress updatedAt"),
     index,
     total,
+    ...(candidate.provisioning === undefined
+      ? {}
+      : {
+          provisioning: decodeProvisioningProgressV1(candidate.provisioning),
+        }),
     steps,
   };
 }
@@ -507,6 +579,44 @@ export function decodeComputerCommandReceiptV1(
   );
 }
 
+export function decodeComputerCommandResponse(
+  value: unknown,
+): ComputerCommandResponse {
+  if (
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    (value as Record<string, unknown>).version === 2
+  ) {
+    const candidate = record(value, "Computer command acceptance");
+    exactKeys(
+      candidate,
+      ["version", "commandId", "type", "status", "admittedAt"],
+      [],
+      "Computer command acceptance",
+    );
+    if (candidate.type !== "connect" || candidate.status !== "accepted") {
+      throw new ComputerProtocolDecodeError(
+        "Computer command acceptance is invalid",
+      );
+    }
+    return {
+      version: 2,
+      commandId: text(
+        candidate.commandId,
+        "Computer command acceptance commandId",
+      ),
+      type: "connect",
+      status: "accepted",
+      admittedAt: timestamp(
+        candidate.admittedAt,
+        "Computer command acceptance admittedAt",
+      ),
+    };
+  }
+  return decodeComputerCommandReceiptV1(value);
+}
+
 export function computerCommandFingerprintV1(
   command: ComputerCommandV1,
 ): string {

package/src/screenshot.test.ts

@@ -9,6 +9,7 @@ import { describe, expect, test } from "bun:test";
 import { SystemPromptRegistry } from "@frockbot/plugin-prompt";
 import { ToolRegistry } from "@frockbot/plugin-tools";
 import {
+  ComputerError,
   ComputerRegistry,
   computerBotPathKeyV1,
   type ComputerHandle,
@@ -47,12 +48,27 @@ function providerWith(
         tenant,
         workspace,
         screenshot: { capture: () => capture() },
+        exec: {
+          execute: () =>
+            Promise.resolve({
+              exitCode: 0,
+              stdout: new TextEncoder().encode("done"),
+              stderr: new Uint8Array(),
+              outputTruncated: false,
+            }),
+        },
         close: () => Promise.resolve(),
       }),
   };
 }
 
-async function mount(provider: ComputerProvider, writer = true) {
+async function mount(
+  provider: ComputerProvider,
+  writer = true,
+  projectionFiles?: {
+    invalidate(botId: string, kind: "screenshots" | "doctor"): void;
+  },
+) {
   const harness = await createPluginHarness([
     ComputerRegistry,
     ToolRegistry,
@@ -73,13 +89,16 @@ async function mount(provider: ComputerProvider, writer = true) {
             },
           }
         : {}),
+      ...(projectionFiles ? { projectionFiles } : {}),
     }),
   );
   return harness;
 }
 
-async function capture(
+async function executeTool(
   harness: Awaited<ReturnType<typeof createPluginHarness>>,
+  name: string,
+  input: unknown,
 ) {
   const context = {
     botId: "bot-1",
@@ -91,13 +110,17 @@ async function capture(
     signal: new AbortController().signal,
   };
   const prepared = await harness.root.tools.prepare(
-    { id: crypto.randomUUID(), name: "computer_screenshot", input: {} },
+    { id: crypto.randomUUID(), name, input },
     context,
   );
   if (prepared.kind !== "ready") throw new Error(prepared.result.content);
   return harness.root.tools.executePrepared(prepared, context);
 }
 
+function capture(harness: Awaited<ReturnType<typeof createPluginHarness>>) {
+  return executeTool(harness, "computer_screenshot", {});
+}
+
 describe("computer_screenshot", () => {
   test("files the capture through the Workspace with the Bot as its writer", async () => {
     const workspace = new FakeWorkspace();
@@ -239,6 +262,80 @@ describe("computer_screenshot", () => {
     ).not.toContain("computer_screenshot");
     await harness.dispose();
   });
+
+  test("captures a final frame after a Turn that used the Computer", async () => {
+    const workspace = new FakeWorkspace();
+    const invalidations: string[] = [];
+    const harness = await mount(
+      providerWith(workspace, () =>
+        Promise.resolve({
+          bytes: png(1280, 720),
+          mediaType: "image/png" as const,
+          display: ":100",
+          capturedAt: "2026-09-03T00:00:10.000Z",
+        }),
+      ),
+      true,
+      {
+        invalidate: (botId, kind) => invalidations.push(`${botId}:${kind}`),
+      },
+    );
+    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 executeTool(harness, "computer_exec", { command: "pwd" });
+
+    await harness.root.serial("agent/turn-stopping", agent as never, 1);
+
+    expect(workspace.writes).toHaveLength(1);
+    expect(workspace.writes[0]?.writer).toEqual({
+      kind: "bot",
+      botId: "bot-1",
+      sessionId: "session-1",
+      turnId: "run-9",
+      runId: "run-9",
+    });
+    expect(invalidations).toEqual(["bot-1:screenshots"]);
+    await harness.dispose();
+  });
+
+  test("a final-frame capture is refused while the User holds control", async () => {
+    const workspace = new FakeWorkspace();
+    let captures = 0;
+    const harness = await mount(
+      providerWith(workspace, () => {
+        captures += 1;
+        return Promise.reject(
+          new ComputerError("human-control-active", "held by User"),
+        );
+      }),
+    );
+    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 executeTool(harness, "computer_exec", { command: "pwd" });
+
+    await expect(
+      harness.root.serial("agent/turn-stopping", agent as never, 1),
+    ).resolves.toBeUndefined();
+    expect(captures).toBe(1);
+    expect(workspace.writes).toHaveLength(0);
+    await harness.dispose();
+  });
 });
 
 describe("pngDimensionsV1", () => {

package/src/workspace-fixture.ts

@@ -38,6 +38,8 @@ export class FakeWorkspace implements ComputerWorkspace {
     { bytes: Uint8Array; generation: WorkspaceGenerationV1 }
   >();
   readonly deleted: string[] = [];
+  readonly reads: WorkspacePathV1[] = [];
+  readonly lists: { root: WorkspaceRootV1; prefix?: string }[] = [];
   /**
    * Every write, in order, with the root it named.
    *
@@ -57,6 +59,7 @@ export class FakeWorkspace implements ComputerWorkspace {
   }
 
   read(path: WorkspacePathV1) {
+    this.reads.push(path);
     const held = this.files.get(this.key(path));
     return Promise.resolve(
       held
@@ -81,6 +84,7 @@ export class FakeWorkspace implements ComputerWorkspace {
   }
 
   list(request: { root: WorkspaceRootV1; prefix?: string }) {
+    this.lists.push(request);
     const entries: WorkspaceEntryV1[] = [...this.files.entries()]
       .filter(([path]) => !request.prefix || path.startsWith(request.prefix))
       .map(([path, held]) => ({

package/src/client/ComputerStrip.test.ts

@@ -1,54 +0,0 @@
-import { expect, test } from "bun:test";
-import { readFileSync } from "node:fs";
-import { parse } from "@vue/compiler-sfc";
-import {
-  initialComputerMachineState,
-  transitionComputerState,
-} from "./state-machine.js";
-
-test("the Vue strip keys its durable capture only by contentHash", () => {
-  const source = readFileSync(
-    new URL("./ComputerStrip.vue", import.meta.url),
-    "utf8",
-  );
-  const parsed = parse(source, { filename: "ComputerStrip.vue" });
-  expect(parsed.errors).toEqual([]);
-  const template = parsed.descriptor.template?.content ?? "";
-
-  expect(template).toContain(':key="screenshot.contentHash"');
-  expect(template).toContain(':src="screenshot.url"');
-  expect(template).not.toContain("viewerUrl");
-});
-
-test("a repeated screenshot projection preserves the rendered capture", () => {
-  const first = {
-    version: 1 as const,
-    path: "scout/latest.png",
-    capturedAt: "2026-09-02T00:00:00.000Z",
-    contentHash: "sha256:first",
-    url: "/workspace/first",
-  };
-  const state = {
-    ...initialComputerMachineState(),
-    screenshots: [first],
-  };
-  const project = (contentHash: string) => ({
-    type: "projection-received" as const,
-    projection: {
-      version: 1 as const,
-      botId: "scout",
-      providerLabel: "Fake Computer",
-      phase: "idle" as const,
-      message: "Computer available",
-      screenshots: [
-        { ...first, contentHash, url: `/workspace/${contentHash}` },
-      ],
-    },
-  });
-
-  const unchanged = transitionComputerState(state, project("sha256:first"));
-  const changed = transitionComputerState(unchanged, project("sha256:second"));
-
-  expect(unchanged.screenshots[0]).toBe(first);
-  expect(changed.screenshots[0]).not.toBe(first);
-});

package/src/client/ComputerStrip.vue

@@ -1,55 +0,0 @@
-<script setup lang="ts">
-import { useRpc } from "@cordisjs/client";
-import { UiIcon } from "@frockbot/client-ui";
-import { computed, inject, ref } from "vue";
-import { computerKey, type ComputerState } from "../shared.ts";
-
-const computer = inject(computerKey) ?? useRpc<ComputerState>();
-const busy = ref(false);
-const state = computed(() => computer.value);
-const screenshot = computed(() => state.value.screenshots?.[0]);
-const phaseLabel = computed(() =>
-  state.value.phase === "updating"
-    ? state.value.message
-    : state.value.phase.replaceAll("-", " "),
-);
-
-async function open(): Promise<void> {
-  if (busy.value) return;
-  busy.value = true;
-  try {
-    await state.value.openViewer();
-  } catch {
-    // The shared state already holds the visible failure.
-  } finally {
-    busy.value = false;
-  }
-}
-</script>
-
-<template>
-  <button
-    type="button"
-    class="computer-strip"
-    :disabled="busy"
-    :aria-label="`Open Computer, ${phaseLabel}`"
-    @click="open"
-  >
-    <span class="computer-strip-capture">
-      <img
-        v-if="screenshot"
-        :key="screenshot.contentHash"
-        :src="screenshot.url"
-        alt=""
-        draggable="false"
-      />
-      <span v-else class="computer-strip-placeholder" aria-hidden="true">
-        <UiIcon name="sparkle" size="sm" />
-      </span>
-    </span>
-    <span class="computer-strip-phase">
-      <span class="computer-strip-dot" :class="`phase-${state.phase}`" />
-      <span>{{ phaseLabel }}</span>
-    </span>
-  </button>
-</template>