@frockbot/plugin-computer 0.0.0 → 0.1.0

package/src/client/application.test.ts

@@ -0,0 +1,373 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  ClientPluginContext,
+  ClientSlotRegistration,
+} from "@frockbot/client-core";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { nextTick, ref } from "vue";
+import { computerKey, type ComputerState } from "../shared.js";
+import {
+  createComputerClientPlugin,
+  PROJECTION_POLL_INTERVAL_MS,
+  VIEWER_REFRESH_INTERVAL_MS,
+  type ComputerClientRuntime,
+} from "./application.js";
+
+class FakeRuntime implements ComputerClientRuntime {
+  visible = true;
+  readonly intervals = new Map<
+    number,
+    { callback: () => void; milliseconds: number }
+  >();
+  private visibilityListener?: () => void;
+  private nextTimer = 0;
+
+  setInterval(callback: () => void, milliseconds: number): unknown {
+    const id = ++this.nextTimer;
+    this.intervals.set(id, { callback, milliseconds });
+    return id;
+  }
+
+  clearInterval(handle: unknown): void {
+    this.intervals.delete(handle as number);
+  }
+
+  isVisible(): boolean {
+    return this.visible;
+  }
+
+  onVisibilityChange(listener: () => void): () => void {
+    this.visibilityListener = listener;
+    return () => {
+      if (this.visibilityListener === listener) {
+        this.visibilityListener = undefined;
+      }
+    };
+  }
+
+  setVisible(visible: boolean): void {
+    this.visible = visible;
+    this.visibilityListener?.();
+  }
+
+  tick(milliseconds: number): void {
+    for (const interval of [...this.intervals.values()]) {
+      if (interval.milliseconds === milliseconds) interval.callback();
+    }
+  }
+
+  count(milliseconds: number): number {
+    return [...this.intervals.values()].filter(
+      (interval) => interval.milliseconds === milliseconds,
+    ).length;
+  }
+}
+
+type Phase = "idle" | "updating" | "ready" | "human-control" | "disconnected";
+
+function mountHostedProvider() {
+  const shell = ref({ activeBotId: "scout" });
+  const calls: Array<[string, string | undefined, string | undefined]> = [];
+  const runtime = new FakeRuntime();
+  let phase: Phase = "idle";
+  let controlHeld = false;
+  let renewFails = false;
+  let state: { value: ComputerState } | undefined;
+  const slots: ClientSlotRegistration[] = [];
+  const context: ClientPluginContext = {
+    transport: {
+      turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+      hostedRequest: (path, method, body) => {
+        calls.push([path, method, body]);
+        if (method === "POST") {
+          const command = JSON.parse(body ?? "{}") as {
+            commandId: string;
+            type:
+              "connect" | "takeControl" | "releaseControl" | "refreshViewer";
+          };
+          if (command.type === "connect") phase = "ready";
+          if (command.type === "takeControl") {
+            phase = "human-control";
+            controlHeld = true;
+          }
+          if (command.type === "releaseControl") {
+            controlHeld = false;
+            if (phase !== "disconnected") phase = "ready";
+          }
+          if (command.type === "refreshViewer" && renewFails) {
+            phase = "disconnected";
+          }
+          return Promise.resolve({
+            version: 1,
+            commandId: command.commandId,
+            type: command.type,
+            status:
+              command.type === "refreshViewer" && renewFails
+                ? "rejected"
+                : "applied",
+            completedAt: "2026-09-02T00:00:00.000Z",
+            ...(command.type === "refreshViewer" && renewFails
+              ? { failure: "viewer session expired" }
+              : {}),
+          });
+        }
+        return Promise.resolve({
+          version: 1,
+          botId: "scout",
+          providerLabel: "Fake Computer",
+          phase,
+          message:
+            phase === "idle"
+              ? "Persistent Computer available"
+              : phase === "updating"
+                ? "Updating the Computer runtime"
+                : "Computer ready",
+          ...(phase === "idle" || phase === "disconnected"
+            ? {}
+            : {
+                viewerSession: {
+                  version: 1,
+                  id: "viewer-1",
+                  url: "https://viewer.invalid/secret#view_only=1",
+                  expiresAt: "2099-09-02T00:01:30.000Z",
+                },
+              }),
+          ...(controlHeld
+            ? {
+                controlLease: {
+                  version: 1,
+                  ownerId: "owner-1",
+                  acquiredAt: "2026-09-02T00:00:00.000Z",
+                  expiresAt: "2099-09-02T00:01:30.000Z",
+                },
+              }
+            : {}),
+          screenshots: [],
+        });
+      },
+    },
+    inject: (key) => {
+      if (key === frockBotWebDataKey) return shell as never;
+      throw new Error("unexpected client injection");
+    },
+    provide: (key, value) => {
+      if (key === computerKey) state = value as { value: ComputerState };
+      return () => {};
+    },
+    slot: (registration) => {
+      slots.push(registration);
+      return () => {};
+    },
+  };
+  const disposers = createComputerClientPlugin(runtime)(context);
+  return {
+    calls,
+    runtime,
+    shell,
+    slots,
+    get state() {
+      if (!state) throw new Error("Computer state was not provided");
+      return state.value;
+    },
+    failRenewal() {
+      renewFails = true;
+    },
+    setUpdating() {
+      phase = "updating";
+    },
+    dispose() {
+      if (Array.isArray(disposers)) {
+        for (const dispose of disposers.toReversed()) dispose();
+      } else if (typeof disposers === "function") disposers();
+    },
+  };
+}
+
+async function flush(): Promise<void> {
+  await nextTick();
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function postedTypes(
+  calls: Array<[string, string | undefined, string | undefined]>,
+): string[] {
+  return calls
+    .filter(([, method]) => method === "POST")
+    .map(([, , body]) => (JSON.parse(body ?? "{}") as { type: string }).type);
+}
+
+describe("hosted Computer provider", () => {
+  test("mounts the card and strip without connecting the Computer", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+
+    expect(mounted.state.phase).toBe("idle");
+    expect(mounted.slots.map((slot) => slot.slot)).toEqual([
+      "frockbot.computer",
+      "frockbot.sidebar-computer",
+      "frockbot.overlays",
+    ]);
+    expect(postedTypes(mounted.calls)).toEqual([]);
+
+    await mounted.state.openViewer();
+    expect(mounted.state).toMatchObject({ phase: "ready", expanded: true });
+    expect(postedTypes(mounted.calls)).toEqual(["connect"]);
+    mounted.dispose();
+  });
+
+  test("refreshes the viewer only while the overlay is expanded", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(0);
+
+    await mounted.state.openViewer();
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(1);
+    mounted.runtime.tick(VIEWER_REFRESH_INTERVAL_MS);
+    await flush();
+    expect(postedTypes(mounted.calls)).toEqual(["connect", "refreshViewer"]);
+
+    await mounted.state.closeViewer();
+    expect(mounted.runtime.count(VIEWER_REFRESH_INTERVAL_MS)).toBe(0);
+    mounted.runtime.tick(VIEWER_REFRESH_INTERVAL_MS);
+    await flush();
+    expect(postedTypes(mounted.calls)).toEqual(["connect", "refreshViewer"]);
+    mounted.dispose();
+  });
+
+  test("an updating strip click only expands the progress view", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    mounted.setUpdating();
+    mounted.runtime.tick(PROJECTION_POLL_INTERVAL_MS);
+    await flush();
+    expect(mounted.state).toMatchObject({
+      phase: "updating",
+      message: "Updating the Computer runtime",
+      expanded: false,
+    });
+
+    await mounted.state.openViewer();
+
+    expect(mounted.state).toMatchObject({
+      phase: "updating",
+      expanded: true,
+    });
+    expect(postedTypes(mounted.calls)).toEqual([]);
+    mounted.dispose();
+  });
+
+  test("moves a failed viewer renewal to disconnected", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    await mounted.state.openViewer();
+    mounted.failRenewal();
+
+    mounted.runtime.tick(VIEWER_REFRESH_INTERVAL_MS);
+    await flush();
+
+    expect(mounted.state).toMatchObject({
+      phase: "disconnected",
+      viewerUrl: undefined,
+      takingControl: false,
+    });
+    mounted.dispose();
+  });
+
+  test("a viewer failure under human control still releases on close", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    await mounted.state.openViewer();
+    await mounted.state.takeControl();
+    mounted.failRenewal();
+
+    mounted.runtime.tick(VIEWER_REFRESH_INTERVAL_MS);
+    await flush();
+    expect(mounted.state).toMatchObject({
+      phase: "disconnected",
+      takingControl: true,
+    });
+
+    await mounted.state.closeViewer();
+    expect(
+      postedTypes(mounted.calls).filter((type) => type !== "refreshControl"),
+    ).toEqual(["connect", "takeControl", "refreshViewer", "releaseControl"]);
+    expect(mounted.state.expanded).toBe(false);
+    mounted.dispose();
+  });
+
+  test("closing the overlay releases control before it collapses", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    await mounted.state.openViewer();
+    await mounted.state.takeControl();
+
+    await mounted.state.closeViewer();
+
+    expect(mounted.state).toMatchObject({
+      phase: "ready",
+      takingControl: false,
+      expanded: false,
+    });
+    expect(postedTypes(mounted.calls)).toEqual([
+      "connect",
+      "takeControl",
+      "releaseControl",
+    ]);
+    mounted.dispose();
+  });
+
+  test("polls the wake-free projection only while the tab is visible", async () => {
+    const mounted = mountHostedProvider();
+    await flush();
+    const initialReads = mounted.calls.filter(([, method]) => !method).length;
+    expect(mounted.runtime.count(PROJECTION_POLL_INTERVAL_MS)).toBe(1);
+
+    mounted.runtime.setVisible(false);
+    expect(mounted.runtime.count(PROJECTION_POLL_INTERVAL_MS)).toBe(0);
+    mounted.runtime.tick(PROJECTION_POLL_INTERVAL_MS);
+    await flush();
+    expect(mounted.calls.filter(([, method]) => !method)).toHaveLength(
+      initialReads,
+    );
+
+    mounted.runtime.setVisible(true);
+    await flush();
+    expect(mounted.runtime.count(PROJECTION_POLL_INTERVAL_MS)).toBe(1);
+    expect(
+      mounted.calls.filter(([, method]) => !method).length,
+    ).toBeGreaterThan(initialReads);
+    mounted.dispose();
+  });
+});
+
+test("the hosted provider stays absent when only the local RPC transport exists", () => {
+  let provides = 0;
+  const slots: string[] = [];
+  const context: ClientPluginContext = {
+    transport: {
+      turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+    },
+    inject: () => {
+      throw new Error("the local path must not inject hosted state");
+    },
+    provide: () => {
+      provides += 1;
+      return () => {};
+    },
+    slot: (registration) => {
+      slots.push(registration.slot);
+      return () => {};
+    },
+  };
+
+  const dispose = createComputerClientPlugin(new FakeRuntime())(context);
+
+  expect(provides).toBe(0);
+  expect(slots).toEqual([
+    "frockbot.computer",
+    "frockbot.sidebar-computer",
+    "frockbot.overlays",
+  ]);
+  if (typeof dispose === "function") dispose();
+});

package/src/client/application.ts

@@ -0,0 +1,340 @@
+/// <reference path="../env.d.ts" />
+
+// The hosted Computer client projects the Bot Durable Object and submits one
+// versioned command per action. The viewer bearer URL is held only on this
+// in-memory state object and is never copied into browser navigation state.
+import type { ClientPlugin } from "@frockbot/client-core";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { ref, watch } from "vue";
+import {
+  decodeComputerCommandReceiptV1,
+  decodeComputerProjectionV1,
+  type ComputerCommandTypeV1,
+} from "../protocol.js";
+import { computerKey, type ComputerState } from "../shared.js";
+import ComputerCard from "./ComputerCard.vue";
+import ComputerStrip from "./ComputerStrip.vue";
+import ComputerViewerOverlay from "./ComputerViewerOverlay.vue";
+import {
+  initialComputerMachineState,
+  transitionComputerState,
+  type ComputerMachineEvent,
+  type ComputerMachineState,
+} from "./state-machine.js";
+import "./styles.css";
+
+export const PROJECTION_POLL_INTERVAL_MS = 20_000;
+export const VIEWER_REFRESH_INTERVAL_MS = 30_000;
+const CONTROL_REFRESH_INTERVAL_MS = 30_000;
+
+export interface ComputerClientRuntime {
+  setInterval(callback: () => void, milliseconds: number): unknown;
+  clearInterval(handle: unknown): void;
+  isVisible(): boolean;
+  onVisibilityChange(listener: () => void): () => void;
+}
+
+const browserRuntime: ComputerClientRuntime = {
+  setInterval: (callback, milliseconds) =>
+    globalThis.setInterval(callback, milliseconds),
+  clearInterval: (handle) =>
+    globalThis.clearInterval(handle as ReturnType<typeof setInterval>),
+  isVisible: () =>
+    typeof document === "undefined" || document.visibilityState === "visible",
+  onVisibilityChange: (listener) => {
+    if (typeof document === "undefined") return () => {};
+    document.addEventListener("visibilitychange", listener);
+    return () => document.removeEventListener("visibilitychange", listener);
+  },
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Builds the lifecycle-owned hosted provider.
+ *
+ * The runtime argument is the browser clock and visibility seam. Tests drive
+ * it without sleeping; production uses `document.visibilityState`, ensuring a
+ * hidden tab submits neither a projection poll nor a wake command (P1/P4).
+ */
+export function createComputerClientPlugin(
+  runtime: ComputerClientRuntime = browserRuntime,
+): ClientPlugin {
+  return (ctx) => {
+    const slots = [
+      ctx.slot({
+        slot: "frockbot.computer",
+        order: 10,
+        component: ComputerCard,
+      }),
+      ctx.slot({
+        slot: "frockbot.sidebar-computer",
+        order: 10,
+        component: ComputerStrip,
+      }),
+      ctx.slot({
+        slot: "frockbot.overlays",
+        order: 20,
+        component: ComputerViewerOverlay,
+      }),
+    ];
+    // The Cordis local host publishes through `useRpc`; when no hosted
+    // transport exists we deliberately provide nothing, so that provider wins.
+    if (!ctx.transport.hostedRequest) return slots;
+
+    const request = ctx.transport.hostedRequest.bind(ctx.transport);
+    const shell = ctx.inject(frockBotWebDataKey);
+    let machine = initialComputerMachineState();
+    let controlHeartbeat: unknown;
+    let viewerHeartbeat: unknown;
+    let projectionPoll: unknown;
+    let controlRequest: Promise<void> | undefined;
+
+    const state = ref<ComputerState>({
+      ...machine,
+      connect: () => connect("connect-requested"),
+      openViewer: () => openViewer(),
+      closeViewer: () => closeViewer(),
+      takeControl: () => takeControl(),
+      releaseControl: () => releaseControl(),
+      runDoctor: () => execute("runDoctor"),
+      retry: () => connect("retry-requested"),
+    });
+
+    function apply(event: ComputerMachineEvent): void {
+      machine = transitionComputerState(machine, event);
+      Object.assign(state.value, machine);
+      syncControlHeartbeat();
+      syncViewerHeartbeat();
+    }
+
+    function stopControlHeartbeat(): void {
+      if (controlHeartbeat !== undefined) {
+        runtime.clearInterval(controlHeartbeat);
+      }
+      controlHeartbeat = undefined;
+    }
+
+    function syncControlHeartbeat(): void {
+      if (machine.phase !== "human-control") {
+        stopControlHeartbeat();
+        return;
+      }
+      if (controlHeartbeat === undefined) {
+        controlHeartbeat = runtime.setInterval(
+          () => void refreshControl(),
+          CONTROL_REFRESH_INTERVAL_MS,
+        );
+      }
+    }
+
+    function stopViewerHeartbeat(): void {
+      if (viewerHeartbeat !== undefined) {
+        runtime.clearInterval(viewerHeartbeat);
+      }
+      viewerHeartbeat = undefined;
+    }
+
+    function syncViewerHeartbeat(): void {
+      if (!machine.expanded || !machine.viewerUrl) {
+        stopViewerHeartbeat();
+        return;
+      }
+      if (viewerHeartbeat === undefined) {
+        // This command, not the strip and not a projection read, is the only
+        // client activity that keeps a watched desktop's slot live (P3).
+        viewerHeartbeat = runtime.setInterval(
+          () => void refreshViewer(),
+          VIEWER_REFRESH_INTERVAL_MS,
+        );
+      }
+    }
+
+    function stopProjectionPoll(): void {
+      if (projectionPoll !== undefined) runtime.clearInterval(projectionPoll);
+      projectionPoll = undefined;
+    }
+
+    function syncProjectionPoll(): void {
+      stopProjectionPoll();
+      if (!shell.value.activeBotId || !runtime.isVisible()) return;
+      projectionPoll = runtime.setInterval(() => {
+        const selectedBotId = shell.value.activeBotId;
+        if (!selectedBotId || !runtime.isVisible()) return;
+        void load(selectedBotId).catch((error) =>
+          apply({ type: "failed", message: errorMessage(error) }),
+        );
+      }, PROJECTION_POLL_INTERVAL_MS);
+    }
+
+    function botId(): string {
+      const selected = shell.value.activeBotId?.trim();
+      if (!selected)
+        throw new Error("Select a Bot before opening its Computer");
+      return selected;
+    }
+
+    async function load(selectedBotId = botId()): Promise<void> {
+      const projection = decodeComputerProjectionV1(
+        await request(
+          `/api/bots/${encodeURIComponent(selectedBotId)}/computer`,
+        ),
+      );
+      if (projection.botId !== selectedBotId) {
+        throw new Error("Computer projection does not match the selected Bot");
+      }
+      apply({ type: "projection-received", projection });
+    }
+
+    async function post(type: ComputerCommandTypeV1): Promise<void> {
+      const selectedBotId = botId();
+      const receipt = decodeComputerCommandReceiptV1(
+        await request(
+          `/api/bots/${encodeURIComponent(selectedBotId)}/computer/commands`,
+          "POST",
+          JSON.stringify({
+            version: 1,
+            commandId: crypto.randomUUID(),
+            botId: selectedBotId,
+            type,
+          }),
+        ),
+      );
+      if (receipt.status === "rejected") throw new Error(receipt.failure);
+    }
+
+    async function execute(type: ComputerCommandTypeV1): Promise<void> {
+      try {
+        await post(type);
+        await load();
+      } catch (error) {
+        // A connect can be refused because the host is already applying an
+        // update. The Bot authority records that typed phase even though the
+        // command receipt is rejected, so read its durable projection before
+        // deciding this is a generic client error.
+        try {
+          await load();
+        } catch {
+          // The original command failure remains the useful answer.
+        }
+        if (type === "connect" && machine.phase === "updating") return;
+        apply({ type: "failed", message: errorMessage(error) });
+        throw error;
+      }
+    }
+
+    async function connect(
+      event: "connect-requested" | "retry-requested",
+    ): Promise<void> {
+      apply({ type: event });
+      await execute("connect");
+    }
+
+    async function openViewer(): Promise<void> {
+      if (machine.expanded) return;
+      const wake = machine.phase === "idle";
+      apply({ type: "viewer-expanded" });
+      if (wake) await connect("connect-requested");
+    }
+
+    async function closeViewer(): Promise<void> {
+      if (!machine.expanded) return;
+      if (controlRequest) {
+        try {
+          await controlRequest;
+        } catch {
+          // The failed acquisition already projected its error. There is no
+          // lease to release before this explicit close finishes.
+        }
+      }
+      if (machine.takingControl) await releaseControl();
+      apply({ type: "viewer-collapsed" });
+    }
+
+    function takeControl(): Promise<void> {
+      if (controlRequest) return controlRequest;
+      const pending = (async () => {
+        if (!machine.viewerUrl) await connect("connect-requested");
+        if (!machine.viewerUrl) return;
+        apply({ type: "take-control-requested" });
+        await execute("takeControl");
+      })();
+      controlRequest = pending.finally(() => {
+        controlRequest = undefined;
+      });
+      return controlRequest;
+    }
+
+    async function releaseControl(): Promise<void> {
+      await execute("releaseControl");
+    }
+
+    async function refreshControl(): Promise<void> {
+      try {
+        await post("refreshControl");
+        await load();
+      } catch (error) {
+        apply({
+          type: "failed",
+          message: `Human control lease was lost: ${errorMessage(error)}`,
+          takingControl: false,
+        });
+      }
+    }
+
+    async function refreshViewer(): Promise<void> {
+      try {
+        await post("refreshViewer");
+        await load();
+      } catch (error) {
+        apply({
+          type: "viewer-disconnected",
+          message: `Viewer disconnected: ${errorMessage(error)}`,
+        });
+      }
+    }
+
+    const stopSelection = watch(
+      () => shell.value.activeBotId,
+      (selectedBotId) => {
+        stopControlHeartbeat();
+        stopViewerHeartbeat();
+        machine = initialComputerMachineState();
+        Object.assign(state.value, machine);
+        syncProjectionPoll();
+        if (!selectedBotId || !runtime.isVisible()) return;
+        void load(selectedBotId).catch((error) =>
+          apply({ type: "failed", message: errorMessage(error) }),
+        );
+      },
+      { immediate: true },
+    );
+    const stopVisibility = runtime.onVisibilityChange(() => {
+      syncProjectionPoll();
+      const selectedBotId = shell.value.activeBotId;
+      if (!selectedBotId || !runtime.isVisible()) return;
+      void load(selectedBotId).catch((error) =>
+        apply({ type: "failed", message: errorMessage(error) }),
+      );
+    });
+
+    const provided = ctx.provide(computerKey, state);
+    return [
+      ...slots,
+      provided,
+      () => {
+        stopSelection();
+        stopVisibility();
+        stopControlHeartbeat();
+        stopViewerHeartbeat();
+        stopProjectionPoll();
+      },
+    ];
+  };
+}
+
+export const computerClientPlugin = createComputerClientPlugin();
+
+export default computerClientPlugin;