@frockbot/plugin-computer 0.0.0 → 0.1.0

package/src/shared-provider.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { ComputerRegistry } from "@frockbot/computer-core";
+import { Context } from "cordis";
+import {
+  createSharedComputerProviderPlugin,
+  SHARED_COMPUTER_PROVIDER_ID,
+} from "./shared-provider.js";
+
+describe("shared Computer provider", () => {
+  test("forwards stable effect identity through the provider-neutral host", async () => {
+    const requests: unknown[] = [];
+    const root = new Context();
+    await root.plugin(ComputerRegistry);
+    await root.plugin(
+      createSharedComputerProviderPlugin({
+        effect: (request) => {
+          requests.push(request);
+          return Promise.resolve({
+            schemaVersion: 1,
+            effectId: request.effectId,
+            status: "completed",
+            result: {
+              type: "exec",
+              result: {
+                exitCode: 0,
+                stdout: Uint8Array.from([111, 107]),
+                stderr: new Uint8Array(),
+                outputTruncated: false,
+              },
+            },
+          });
+        },
+      }),
+    );
+    const identity = { userId: "user-1" };
+    const tenant = { botId: "bot-1" };
+    root.computers.assign(identity, SHARED_COMPUTER_PROVIDER_ID);
+    const computer = await root.computers.open(identity, tenant);
+    const result = await computer.exec?.execute(
+      { executable: "/bin/true" },
+      { effectId: "tool:1:1:0" },
+    );
+
+    expect(result?.stdout).toEqual(Uint8Array.from([111, 107]));
+    expect(requests).toMatchObject([
+      {
+        schemaVersion: 1,
+        effectId: "tool:1:1:0",
+        identity,
+        tenant,
+        operation: { type: "exec", request: { executable: "/bin/true" } },
+      },
+    ]);
+    await root.fiber.dispose();
+  });
+});

package/src/shared-provider.ts

@@ -0,0 +1,121 @@
+import {
+  ComputerError,
+  type ComputerAssignment,
+  type ComputerHandle,
+  type ComputerOperationOptions,
+  type ComputerIdentityV1,
+  type ComputerProvider,
+  type ComputerTenantV1,
+} from "@frockbot/computer-core";
+import type {
+  ComputerHostEffectRequestV1,
+  ComputerHostEffectResponseV1,
+} from "@frockbot/computer-core/host-protocol";
+import type { Plugin } from "cordis";
+
+export const SHARED_COMPUTER_PROVIDER_ID = "shared-computer";
+
+export interface SharedComputerHostClient {
+  effect(
+    request: ComputerHostEffectRequestV1,
+    options?: ComputerOperationOptions,
+  ): Promise<ComputerHostEffectResponseV1>;
+}
+
+function effectId(options: ComputerOperationOptions | undefined): string {
+  const value = options?.effectId?.trim();
+  if (!value) {
+    throw new ComputerError(
+      "invalid-request",
+      "Computer effect identity is required",
+    );
+  }
+  return value;
+}
+
+function completed(
+  response: ComputerHostEffectResponseV1,
+): Extract<ComputerHostEffectResponseV1, { status: "completed" }> {
+  if (response.status === "completed") return response;
+  throw new ComputerError(
+    response.status === "rejected" ? "provider-failure" : "conflict",
+    response.failure,
+    response.status === "unresolved",
+  );
+}
+
+class SharedComputerProvider implements ComputerProvider {
+  readonly id = SHARED_COMPUTER_PROVIDER_ID;
+
+  constructor(private readonly host: SharedComputerHostClient) {}
+
+  open(
+    identity: ComputerIdentityV1,
+    tenant: ComputerTenantV1,
+    assignment: ComputerAssignment,
+  ): Promise<ComputerHandle> {
+    return Promise.resolve({
+      assignment,
+      identity,
+      tenant,
+      exec: {
+        execute: async (request, options) => {
+          const response = completed(
+            await this.host.effect(
+              {
+                schemaVersion: 1,
+                effectId: effectId(options),
+                identity,
+                tenant,
+                assignment,
+                operation: { type: "exec", request },
+              },
+              options,
+            ),
+          );
+          if (response.result.type !== "exec") {
+            throw new ComputerError(
+              "provider-failure",
+              "Computer host returned the wrong effect result",
+            );
+          }
+          return response.result.result;
+        },
+      },
+      browser: {
+        perform: async (action, options) => {
+          const response = completed(
+            await this.host.effect(
+              {
+                schemaVersion: 1,
+                effectId: effectId(options),
+                identity,
+                tenant,
+                assignment,
+                operation: { type: "browser", action },
+              },
+              options,
+            ),
+          );
+          if (response.result.type !== "browser") {
+            throw new ComputerError(
+              "provider-failure",
+              "Computer host returned the wrong effect result",
+            );
+          }
+          return response.result.result;
+        },
+      },
+      close: () => Promise.resolve(),
+    });
+  }
+}
+
+export function createSharedComputerProviderPlugin(
+  host: SharedComputerHostClient,
+): Plugin.Function {
+  const plugin: Plugin.Function = (ctx) =>
+    ctx.computers.register(new SharedComputerProvider(host));
+  plugin.inject = ["computers"];
+  return plugin;
+}

package/src/shared.ts

@@ -0,0 +1,54 @@
+import type { InjectionKey, Ref } from "vue";
+import type {
+  ComputerDoctorViewV1,
+  ComputerPhase,
+  ComputerScreenshotViewV1,
+} from "./protocol.js";
+
+export * from "./protocol.js";
+
+/**
+ * One capture in the Bot's durable screenshots root, as the card renders it.
+ *
+ * `url` addresses the Workspace read route rather than the Computer: the
+ * capture is durable content in object storage, so showing it wakes nothing.
+ */
+export type { ComputerScreenshotViewV1 };
+
+/**
+ * The Computer's last self-check, as the card renders it.
+ *
+ * The report is the Computer's own answer, decoded at the provider seam; the
+ * card only draws it. A Computer that has never been asked has none, which is
+ * a different thing from one whose checks all passed.
+ */
+export type { ComputerDoctorViewV1, ComputerPhase };
+
+/** Provider-neutral state published by the selected Computer adapter. */
+export interface ComputerState {
+  phase: ComputerPhase;
+  botId: string;
+  providerLabel: string;
+  message: string;
+  viewerUrl?: string;
+  /** Whether the one live viewer is open over the hosted shell. */
+  expanded: boolean;
+  takingControl: boolean;
+  /** Newest first. Empty where the host publishes no captures. */
+  screenshots?: ComputerScreenshotViewV1[];
+  /** The last self-check, absent until one has been run. */
+  doctor?: ComputerDoctorViewV1;
+  /** Absent where the host cannot run one; the card hides the button. */
+  runDoctor?(): Promise<void>;
+  connect(): Promise<void>;
+  /** Explicit User open. An idle Computer may wake; rendering never does. */
+  openViewer(): Promise<void>;
+  /** Closes the viewer, releasing human control before it disappears. */
+  closeViewer(): Promise<void>;
+  takeControl(): Promise<void>;
+  releaseControl(): Promise<void>;
+  retry(): Promise<void>;
+}
+
+export const computerKey: InjectionKey<Ref<ComputerState>> =
+  Symbol("computer-data");

package/src/sync.test.ts

@@ -0,0 +1,255 @@
+// When the Computer Package runs the durable-root sync (ADR 0013), and when it
+// refuses to.
+//
+// The provider here records every call the provider-neutral Computer interface
+// receives, in order, so the claims are about ordering and about absence:
+// the pull lands before the Bot's first Computer tool call, the push lands
+// after the Turn, a Turn that never touches the Computer syncs nothing at all,
+// and a sync that cannot run is a recorded outcome rather than a failed Turn.
+import { describe, expect, test } from "bun:test";
+import {
+  ComputerRegistry,
+  computerSyncSummaryV1,
+  type ComputerProvider,
+  type ComputerSyncSummaryV1,
+} from "@frockbot/computer-core";
+import { AgentRegistry } from "@frockbot/kernel-agent-loop/agent";
+import { AgentLoop } from "@frockbot/kernel-agent-loop";
+import {
+  SessionStore,
+  type LlmProvider,
+  type SessionEvent,
+} from "@frockbot/kernel-contracts";
+import { LlmRegistry } from "@frockbot/plugin-models";
+import { SystemPromptRegistry } from "@frockbot/plugin-prompt";
+import { ToolRegistry } from "@frockbot/plugin-tools";
+import { Context, type Plugin } from "cordis";
+import { createComputerAgentPlugin } from "./agent.js";
+
+const COMPOSITION = {
+  generationId: "1970-01-01T00:00:00.000Z:0123456789abcdef",
+  artifactSetHash: "a".repeat(64),
+};
+
+interface SyncFixture {
+  calls: string[];
+  provider: ComputerProvider;
+  /** The change signal the on-Computer watcher reports; move it to force a sync. */
+  signal: { value: string | undefined };
+  /** What every `reconcile` answers. */
+  answer: (reason: string) => ComputerSyncSummaryV1 | Promise<never>;
+}
+
+function fixture(
+  answer: SyncFixture["answer"] = () => computerSyncSummaryV1("ok"),
+): SyncFixture {
+  const calls: string[] = [];
+  const signal = { value: "signal-1" as string | undefined };
+  const provider: ComputerProvider = {
+    id: "recording",
+    open: (identity, tenant, assignment) => {
+      calls.push(`open:${tenant.botId}`);
+      return Promise.resolve({
+        assignment,
+        identity,
+        tenant,
+        sync: {
+          reconcile: async (reason) => {
+            calls.push(`sync:${reason}`);
+            return await answer(reason);
+          },
+          signal: () => {
+            calls.push("signal");
+            return Promise.resolve(signal.value);
+          },
+        },
+        exec: {
+          execute: () => {
+            calls.push("exec");
+            return Promise.resolve({
+              exitCode: 0,
+              stdout: new TextEncoder().encode("done"),
+              stderr: new Uint8Array(),
+              outputTruncated: false,
+            });
+          },
+        },
+        close: () => Promise.resolve(),
+      });
+    },
+  };
+  return { calls, provider, signal, answer };
+}
+
+/**
+ * A model that runs the Computer tool once per listed command and then stops.
+ * `[]` is a Turn that never touches the Computer.
+ */
+function modelRunning(
+  commands: readonly string[],
+  beforeStep?: (step: number) => void,
+): LlmProvider {
+  let issued = 0;
+  let step = 0;
+  return {
+    id: "scripted",
+    async *stream() {
+      step += 1;
+      beforeStep?.(step);
+      const command = commands[issued];
+      if (command !== undefined) {
+        issued += 1;
+        yield {
+          type: "tool-call",
+          call: {
+            id: `call-${issued}`,
+            name: "computer_exec",
+            input: { command },
+          },
+        };
+        yield { type: "finish", reason: "tool-calls" };
+        return;
+      }
+      yield { type: "text-delta", text: "done" };
+      yield { type: "finish", reason: "completed" };
+    },
+  };
+}
+
+async function runTurn(
+  provider: ComputerProvider,
+  model: LlmProvider,
+): Promise<SessionEvent[]> {
+  const root = new Context();
+  await root.plugin(SessionStore, {});
+  await root.plugin(SystemPromptRegistry);
+  await root.plugin(LlmRegistry);
+  await root.plugin(ToolRegistry);
+  await root.plugin(ComputerRegistry);
+  await root.plugin(AgentRegistry);
+  const providerPlugin: Plugin.Function = (ctx) => {
+    const disposeModel = ctx.llm.register(model);
+    const disposeComputer = ctx.computers.register(provider);
+    return () => {
+      disposeComputer();
+      disposeModel();
+    };
+  };
+  providerPlugin.inject = ["llm", "computers"];
+  await root.plugin(providerPlugin);
+  await root.plugin(
+    createComputerAgentPlugin({
+      userId: "user-1",
+      defaultProviderId: "recording",
+    }),
+  );
+  await root.plugin(AgentLoop, { maxSteps: 4, composition: COMPOSITION });
+
+  const handle = await root.agents.create({
+    botId: "bot-1",
+    sessionId: "session-1",
+    provider: model.id,
+    model: "test-model",
+    admitEffect: () => Promise.resolve(true),
+  });
+  handle.agent.send("use the Computer");
+  await handle.agent.whenIdle();
+  const events = [...handle.agent.session.events];
+  await root.fiber.dispose();
+  return events;
+}
+
+function syncEvents(events: readonly SessionEvent[]) {
+  return events.filter(
+    (event): event is Extract<SessionEvent, { type: "computer/sync" }> =>
+      event.type === "computer/sync",
+  );
+}
+
+describe("the Computer Package as the sync's caller", () => {
+  test("pulls before the Turn's first Computer tool call and pushes after the Turn", async () => {
+    const { calls, provider } = fixture();
+
+    const events = await runTurn(provider, modelRunning(["pwd"]));
+
+    // The pull is between opening the Computer and the Bot's first look at it,
+    // so the Workspace the command sees is the one object storage holds.
+    expect(calls.slice(0, 4)).toEqual([
+      "open:bot-1",
+      "sync:open",
+      // The baseline the watcher's signal is compared against next time.
+      "signal",
+      "exec",
+    ]);
+    expect(calls.at(-1)).toBe("sync:turn-end");
+    // Both runs are visible in durable state, on the Turn that caused them.
+    expect(
+      syncEvents(events).map((event) => [
+        event.turn,
+        event.reason,
+        event.status,
+      ]),
+    ).toEqual([
+      [1, "open", "ok"],
+      [1, "turn-end", "ok"],
+    ]);
+  });
+
+  test("a Turn that never uses the Computer never syncs, so nothing wakes", async () => {
+    const { calls, provider } = fixture();
+
+    const events = await runTurn(provider, modelRunning([]));
+
+    expect(calls).toEqual([]);
+    expect(syncEvents(events)).toEqual([]);
+  });
+
+  test("syncs again inside a Turn only when the watcher's change signal moved", async () => {
+    const { calls, provider, signal } = fixture();
+    // The watcher reports a change before the third step's tool call, and
+    // reports nothing new before the second: only one extra sync may follow.
+    const model = modelRunning(["first", "second", "third"], (step) => {
+      if (step === 3) signal.value = "signal-2";
+    });
+
+    const events = await runTurn(provider, model);
+
+    expect(calls.filter((call) => call.startsWith("sync:"))).toEqual([
+      "sync:open",
+      "sync:signal",
+      "sync:turn-end",
+    ]);
+    expect(syncEvents(events).map((event) => event.reason)).toEqual([
+      "open",
+      "signal",
+      "turn-end",
+    ]);
+  });
+
+  test("an unavailable sync is recorded on the Turn and never fails it", async () => {
+    const { provider } = fixture((reason) => {
+      if (reason === "open") {
+        return Promise.reject(
+          new Error("the Computer is paused"),
+        ) as Promise<never>;
+      }
+      return computerSyncSummaryV1("unavailable", "the Computer is paused");
+    });
+
+    const events = await runTurn(provider, modelRunning(["pwd"]));
+
+    // The Turn completed: the tool ran and the Turn closed normally.
+    expect(
+      events.some(
+        (event) => event.type === "turn/end" && event.outcome === "completed",
+      ),
+    ).toBe(true);
+    expect(
+      syncEvents(events).map((event) => [event.reason, event.status]),
+    ).toEqual([
+      ["open", "unavailable"],
+      ["turn-end", "unavailable"],
+    ]);
+    expect(syncEvents(events)[0]?.detail).toContain("paused");
+  });
+});

package/src/workspace-fixture.ts

@@ -0,0 +1,126 @@
+// Test support: an in-memory `ComputerWorkspace`.
+//
+// A module under `src` rather than a fixture inside one test file because two
+// suites need the same one — the screenshot tool and the background-process
+// tools both write through the Workspace, and a fixture per suite would let
+// two of them drift from one contract. Deliberately absent from this Package's
+// `exports`, and not a `*.test.ts` file, so `bun test` never runs it as one.
+import type {
+  ComputerWorkspace,
+  WorkspaceLayoutV1,
+} from "@frockbot/computer-core";
+import type {
+  WorkspaceEntryV1,
+  WorkspaceGenerationV1,
+  WorkspacePathV1,
+  WorkspaceRootV1,
+  WorkspaceWriterV1,
+} from "@frockbot/kernel-contracts";
+
+export const FAKE_WORKSPACE_LAYOUT: WorkspaceLayoutV1 = {
+  schemaVersion: 1,
+  home: "/home/box",
+  roots: [
+    {
+      kind: "package-declared",
+      scope: "user",
+      mountPath: "/home/box/agent-data/user-packages/{package}/{root}",
+      access: "read-write",
+    },
+  ],
+};
+
+/** An in-memory `ComputerWorkspace` that records every write it admitted. */
+export class FakeWorkspace implements ComputerWorkspace {
+  readonly layout = FAKE_WORKSPACE_LAYOUT;
+  readonly files = new Map<
+    string,
+    { bytes: Uint8Array; generation: WorkspaceGenerationV1 }
+  >();
+  readonly deleted: string[] = [];
+  /**
+   * Every write, in order, with the root it named.
+   *
+   * The file map is keyed by path alone, so it cannot answer *which durable
+   * root* a Package wrote to — and that is the question a test about writer
+   * attribution has to ask.
+   */
+  readonly writes: {
+    path: WorkspacePathV1;
+    bytes: Uint8Array;
+    writer: WorkspaceWriterV1;
+  }[] = [];
+  private sequence = 0;
+
+  private key(path: WorkspacePathV1): string {
+    return path.path;
+  }
+
+  read(path: WorkspacePathV1) {
+    const held = this.files.get(this.key(path));
+    return Promise.resolve(
+      held
+        ? {
+            status: "ok" as const,
+            file: { path, generation: held.generation, bytes: held.bytes },
+          }
+        : { status: "not-found" as const, reason: "no such file" },
+    );
+  }
+
+  stat(path: WorkspacePathV1) {
+    const held = this.files.get(this.key(path));
+    return Promise.resolve(
+      held
+        ? {
+            status: "ok" as const,
+            entry: { path, generation: held.generation },
+          }
+        : { status: "not-found" as const, reason: "no such file" },
+    );
+  }
+
+  list(request: { root: WorkspaceRootV1; prefix?: string }) {
+    const entries: WorkspaceEntryV1[] = [...this.files.entries()]
+      .filter(([path]) => !request.prefix || path.startsWith(request.prefix))
+      .map(([path, held]) => ({
+        path: { root: request.root, path },
+        generation: held.generation,
+      }));
+    return Promise.resolve({ status: "ok" as const, entries });
+  }
+
+  write(request: {
+    path: WorkspacePathV1;
+    bytes: Uint8Array;
+    writer: WorkspaceWriterV1;
+  }) {
+    this.sequence += 1;
+    this.writes.push(request);
+    const generation: WorkspaceGenerationV1 = {
+      schemaVersion: 1,
+      generationId: `gen-${this.sequence}`,
+      // A stand-in digest with the shape the decoders require.
+      contentHash: this.sequence.toString(16).padStart(64, "a"),
+      size: request.bytes.byteLength,
+      writer: request.writer,
+      writtenAt: new Date(1_700_000_000_000 + this.sequence).toISOString(),
+    };
+    this.files.set(this.key(request.path), {
+      bytes: request.bytes,
+      generation,
+    });
+    return Promise.resolve({ status: "ok" as const, generation });
+  }
+
+  delete(request: { path: WorkspacePathV1 }) {
+    const held = this.files.get(this.key(request.path));
+    this.deleted.push(request.path.path);
+    this.files.delete(this.key(request.path));
+    return Promise.resolve(
+      held
+        ? { status: "ok" as const, generation: held.generation }
+        : { status: "not-found" as const, reason: "no such file" },
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "paths": {
+      "@cordisjs/client": ["src/client/cordis-client-shim.d.ts"]
+    },
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "types": ["bun", "node", "vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url";
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [vue()],
+  build: {
+    outDir: fileURLToPath(new URL("./dist", import.meta.url)),
+    emptyOutDir: true,
+    manifest: "manifest.json",
+    lib: {
+      entry: fileURLToPath(new URL("./src/client/index.ts", import.meta.url)),
+      formats: ["es"],
+    },
+    rollupOptions: {
+      external: ["vue", "@cordisjs/client"],
+      output: {
+        entryFileNames: "assets/computer-[hash].js",
+        chunkFileNames: "assets/chunk-[hash].js",
+        assetFileNames: "assets/[name]-[hash][extname]",
+      },
+    },
+  },
+});

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-computer
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.