@frockbot/plugin-computer 0.0.0 → 0.1.1

package/src/client/application.ts

@@ -0,0 +1,359 @@
+/// <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;
+        // The `updating` record is written when the host refused a connect
+        // mid-update; it only changes when someone connects again. While the
+        // User has the Computer open, rejoin the update each poll so the
+        // viewer arrives the moment the host finishes (P4).
+        if (machine.phase === "updating" && machine.expanded) {
+          void execute("connect").catch(() => {
+            // A refusal keeps the updating phase; the next poll asks again.
+          });
+          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;
+      // Idle wakes. Updating rejoins: the host either hands back the viewer
+      // because the update has finished, or refuses again with its phase.
+      const wake = machine.phase === "idle" || machine.phase === "updating";
+      apply({ type: "viewer-expanded" });
+      if (!wake) return;
+      if (machine.phase === "updating") {
+        await execute("connect").catch(() => {
+          // Still updating; the projection poll keeps rejoining.
+        });
+        return;
+      }
+      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;

package/src/client/cordis-client-shim.d.ts

@@ -0,0 +1,16 @@
+import type { Component, Ref } from "vue";
+
+export interface Context {
+  client: {
+    router: {
+      slot(options: {
+        type: string;
+        name?: string;
+        order?: number;
+        component: Component;
+      }): void;
+    };
+  };
+}
+
+export declare function useRpc<T>(): Ref<T>;

package/src/client/dialog-focus.ts

@@ -0,0 +1,13 @@
+/** Return the wrapped focus target, or undefined when Tab stays in the dialog. */
+export function dialogFocusWrapTarget<T>(
+  controls: readonly T[],
+  active: T | null,
+  reverse: boolean,
+): T | undefined {
+  const first = controls[0];
+  const last = controls.at(-1);
+  if (!first || !last) return undefined;
+  if (reverse && active === first) return last;
+  if (!reverse && active === last) return first;
+  return undefined;
+}

package/src/client/index.ts

@@ -0,0 +1,28 @@
+/// <reference path="../env.d.ts" />
+
+import type { Context } from "@cordisjs/client";
+import ComputerCard from "./ComputerCard.vue";
+import ComputerStrip from "./ComputerStrip.vue";
+import ComputerViewerOverlay from "./ComputerViewerOverlay.vue";
+import "./styles.css";
+
+// The viewer UI is shared by every provider capable of publishing a viewer.
+const computerWebPlugin = (ctx: Context) => {
+  ctx.client.router.slot({
+    type: "frockbot.computer",
+    order: 10,
+    component: ComputerCard,
+  });
+  ctx.client.router.slot({
+    type: "frockbot.sidebar-computer",
+    order: 10,
+    component: ComputerStrip,
+  });
+  ctx.client.router.slot({
+    type: "frockbot.overlays",
+    order: 20,
+    component: ComputerViewerOverlay,
+  });
+};
+
+export default computerWebPlugin;

package/src/client/state-machine.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from "bun:test";
+import {
+  initialComputerMachineState,
+  transitionComputerState,
+} from "./state-machine.js";
+
+describe("Computer client state machine", () => {
+  test("moves through every viewer and control transition used by the card", () => {
+    let state = transitionComputerState(initialComputerMachineState(), {
+      type: "configured",
+      botId: "scout",
+      providerLabel: "Fly Sprites",
+      configured: true,
+      message: "Persistent Fly Sprite computer",
+    });
+    expect(state.phase).toBe("idle");
+    state = transitionComputerState(state, { type: "connect-requested" });
+    expect(state.phase).toBe("provisioning");
+    state = transitionComputerState(state, {
+      type: "connected",
+      viewerUrl: "https://viewer.invalid/session",
+    });
+    expect(state).toMatchObject({ phase: "ready", takingControl: false });
+    state = transitionComputerState(state, {
+      type: "take-control-requested",
+    });
+    expect(state.phase).toBe("taking-control");
+    state = transitionComputerState(state, { type: "control-acquired" });
+    expect(state).toMatchObject({
+      phase: "human-control",
+      takingControl: true,
+    });
+    state = transitionComputerState(state, { type: "control-released" });
+    expect(state).toMatchObject({ phase: "ready", takingControl: false });
+  });
+
+  test("moves to error without discarding whether control was held", () => {
+    const state = transitionComputerState(
+      {
+        ...initialComputerMachineState(),
+        phase: "human-control",
+        takingControl: true,
+      },
+      { type: "failed", message: "lease was lost" },
+    );
+    expect(state).toMatchObject({
+      phase: "error",
+      message: "lease was lost",
+      takingControl: true,
+    });
+  });
+
+  test("retry returns an error state to provisioning", () => {
+    const failed = transitionComputerState(initialComputerMachineState(), {
+      type: "failed",
+      message: "wake failed",
+    });
+    const retried = transitionComputerState(failed, {
+      type: "retry-requested",
+    });
+    expect(retried).toMatchObject({
+      phase: "provisioning",
+      takingControl: false,
+    });
+  });
+
+  test("moves into updating with its label and out when connection completes", () => {
+    const updating = transitionComputerState(initialComputerMachineState(), {
+      type: "update-reported",
+      message: "Updating the Computer runtime",
+    });
+    const ready = transitionComputerState(updating, {
+      type: "connected",
+      viewerUrl: "https://viewer.invalid/session",
+    });
+
+    expect(updating).toMatchObject({
+      phase: "updating",
+      message: "Updating the Computer runtime",
+      viewerUrl: undefined,
+    });
+    expect(ready).toMatchObject({
+      phase: "ready",
+      message: "Computer ready",
+      viewerUrl: "https://viewer.invalid/session",
+    });
+  });
+
+  test("marks a dead viewer disconnected and clears the frozen session", () => {
+    const disconnected = transitionComputerState(
+      {
+        ...initialComputerMachineState(),
+        phase: "ready",
+        viewerUrl: "https://viewer.invalid/secret",
+      },
+      { type: "viewer-disconnected", message: "Viewer session expired" },
+    );
+
+    expect(disconnected).toMatchObject({
+      phase: "disconnected",
+      message: "Viewer session expired",
+      viewerUrl: undefined,
+      takingControl: false,
+    });
+  });
+
+  test("a dead viewer preserves a held control lease so close can release it", () => {
+    const disconnected = transitionComputerState(
+      {
+        ...initialComputerMachineState(),
+        phase: "human-control",
+        viewerUrl: "https://viewer.invalid/secret",
+        takingControl: true,
+      },
+      { type: "viewer-disconnected", message: "Viewer session expired" },
+    );
+
+    expect(disconnected).toMatchObject({
+      phase: "disconnected",
+      viewerUrl: undefined,
+      takingControl: true,
+    });
+  });
+
+  test("an idle strip click expands before its connect request", () => {
+    const idle = {
+      ...initialComputerMachineState(),
+      phase: "idle" as const,
+    };
+    const expanded = transitionComputerState(idle, {
+      type: "viewer-expanded",
+    });
+    const connecting = transitionComputerState(expanded, {
+      type: "connect-requested",
+    });
+
+    expect(expanded).toMatchObject({ phase: "idle", expanded: true });
+    expect(connecting).toMatchObject({
+      phase: "provisioning",
+      expanded: true,
+    });
+  });
+
+  test("keeps the durable capture object until its content hash changes", () => {
+    const first = {
+      version: 1 as const,
+      path: "scout/first.png",
+      capturedAt: "2026-09-02T00:00:00.000Z",
+      contentHash: "sha256:first",
+      url: "/workspace/first",
+    };
+    const state = {
+      ...initialComputerMachineState(),
+      screenshots: [first],
+    };
+    const unchanged = transitionComputerState(state, {
+      type: "projection-received",
+      projection: {
+        version: 1,
+        botId: "scout",
+        providerLabel: "Fake Computer",
+        phase: "idle",
+        message: "Computer available",
+        screenshots: [{ ...first, url: "/workspace/reissued" }],
+      },
+    });
+    const changed = transitionComputerState(unchanged, {
+      type: "projection-received",
+      projection: {
+        version: 1,
+        botId: "scout",
+        providerLabel: "Fake Computer",
+        phase: "idle",
+        message: "Computer available",
+        screenshots: [
+          {
+            ...first,
+            contentHash: "sha256:second",
+            url: "/workspace/second",
+          },
+        ],
+      },
+    });
+
+    expect(unchanged.screenshots[0]).toBe(first);
+    expect(changed.screenshots[0]).not.toBe(first);
+  });
+
+  test("reset explicitly clears viewer secrets from an existing projection", () => {
+    const projected = {
+      ...initialComputerMachineState(),
+      phase: "ready" as const,
+      viewerUrl: "https://viewer.invalid/secret",
+    };
+
+    Object.assign(projected, initialComputerMachineState());
+
+    expect(projected.viewerUrl).toBeUndefined();
+  });
+});