@frockbot/plugin-computer 0.0.0 → 0.1.0

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();
+  });
+});

package/src/client/state-machine.ts

@@ -0,0 +1,172 @@
+import type {
+  ComputerDoctorViewV1,
+  ComputerPhase,
+  ComputerProjectionV1,
+  ComputerScreenshotViewV1,
+} from "../protocol.js";
+
+export interface ComputerMachineState {
+  phase: ComputerPhase;
+  botId: string;
+  providerLabel: string;
+  message: string;
+  viewerUrl?: string;
+  expanded: boolean;
+  takingControl: boolean;
+  screenshots: ComputerScreenshotViewV1[];
+  doctor?: ComputerDoctorViewV1;
+}
+
+export type ComputerMachineEvent =
+  | {
+      type: "configured";
+      botId: string;
+      providerLabel: string;
+      configured: boolean;
+      message: string;
+    }
+  | { type: "connect-requested" }
+  | { type: "update-reported"; message: string }
+  | { type: "connected"; viewerUrl: string }
+  | { type: "take-control-requested" }
+  | { type: "control-acquired" }
+  | { type: "control-released" }
+  | { type: "viewer-expanded" }
+  | { type: "viewer-collapsed" }
+  | { type: "viewer-disconnected"; message: string }
+  | { type: "retry-requested" }
+  | { type: "failed"; message: string; takingControl?: boolean }
+  | { type: "doctor-updated"; doctor: ComputerDoctorViewV1 }
+  | { type: "projection-received"; projection: ComputerProjectionV1 };
+
+export function initialComputerMachineState(): ComputerMachineState {
+  return {
+    phase: "unconfigured",
+    botId: "unconfigured",
+    providerLabel: "unconfigured",
+    message: "No Computer provider is configured for this host",
+    viewerUrl: undefined,
+    expanded: false,
+    takingControl: false,
+    screenshots: [],
+    doctor: undefined,
+  };
+}
+
+/**
+ * The single phase transition table shared by local and hosted Computers.
+ * The client only projects authority and transient request progress; it never
+ * invents a durable lease or decides whether a Computer is actually awake.
+ */
+export function transitionComputerState(
+  state: ComputerMachineState,
+  event: ComputerMachineEvent,
+): ComputerMachineState {
+  switch (event.type) {
+    case "configured":
+      return {
+        ...state,
+        phase: event.configured ? "idle" : "unconfigured",
+        botId: event.botId,
+        providerLabel: event.providerLabel,
+        message: event.message,
+        viewerUrl: undefined,
+        takingControl: false,
+      };
+    case "connect-requested":
+    case "retry-requested":
+      return {
+        ...state,
+        phase: "provisioning",
+        message: "Waking and preparing the Computer…",
+        viewerUrl: undefined,
+        takingControl: false,
+      };
+    case "connected":
+      return {
+        ...state,
+        phase: "ready",
+        message: "Computer ready",
+        viewerUrl: event.viewerUrl,
+        takingControl: false,
+      };
+    case "update-reported":
+      return {
+        ...state,
+        phase: "updating",
+        message: event.message,
+        takingControl: false,
+      };
+    case "take-control-requested":
+      return {
+        ...state,
+        phase: "taking-control",
+        message: "Pausing new agent computer actions…",
+      };
+    case "control-acquired":
+      return {
+        ...state,
+        phase: "human-control",
+        message: "You have control. Release when finished with private data.",
+        takingControl: true,
+      };
+    case "control-released":
+      return {
+        ...state,
+        phase: "ready",
+        message: "Computer ready",
+        takingControl: false,
+      };
+    case "viewer-expanded":
+      return { ...state, expanded: true };
+    case "viewer-collapsed":
+      return { ...state, expanded: false };
+    case "viewer-disconnected":
+      return {
+        ...state,
+        phase: "disconnected",
+        message: event.message,
+        viewerUrl: undefined,
+      };
+    case "failed":
+      return {
+        ...state,
+        phase: "error",
+        message: event.message,
+        takingControl: event.takingControl ?? state.takingControl,
+      };
+    case "doctor-updated":
+      return { ...state, doctor: event.doctor };
+    case "projection-received": {
+      const projection = event.projection;
+      // A Workspace read URL may be reissued on every projection, but the
+      // durable bytes have not changed until their content hash does. Holding
+      // the object stable keeps Vue from replacing the visible capture merely
+      // because a wake-free poll returned another DTO instance (P1).
+      const currentCapture = state.screenshots[0];
+      const projectedCapture = projection.screenshots[0];
+      const screenshots =
+        currentCapture &&
+        projectedCapture?.contentHash === currentCapture.contentHash
+          ? [currentCapture, ...projection.screenshots.slice(1)]
+          : projection.screenshots;
+      return {
+        phase: projection.phase,
+        botId: projection.botId,
+        providerLabel: projection.providerLabel,
+        message: projection.message,
+        viewerUrl:
+          projection.phase === "disconnected"
+            ? undefined
+            : projection.viewerSession?.url,
+        expanded: state.expanded,
+        // A dead viewer and a live control lease can coexist. Keep projecting
+        // the lease so Close/Escape can release it explicitly instead of
+        // falling back to expiry merely because the frame disappeared (P2).
+        takingControl: projection.controlLease !== undefined,
+        screenshots,
+        doctor: projection.doctor,
+      };
+    }
+  }
+}