@frockbot/plugin-fly-sprite 0.0.0 → 0.1.1

package/src/host-double.ts

@@ -0,0 +1,268 @@
+/**
+ * Test support: a double for the shared Computer host (ADR 0004).
+ *
+ * It is a module under `src` rather than a fixture inside one test file
+ * because three suites need the same one — `computer.test.ts`,
+ * `workspace.test.ts`, and `sync.test.ts` all drive a `FlySpriteComputer`, and
+ * a double per suite would let three of them drift from one contract. It is
+ * deliberately absent from this Package's `exports`, so nothing outside can
+ * reach it, and it is not a `*.test.ts` file, so `bun test` never runs it as
+ * one.
+ *
+ * What it stands in for is the host, not the Computer: it holds the
+ * human-control leases the Sprite's `flock` would hold, answers `open` and
+ * `viewer` with the shape the container answers, and hands every script to a
+ * runner the suite supplies. What it does not do is HTTP — the wire is
+ * `host-client.test.ts`'s subject and the workerd suite's, and repeating it
+ * here would test the transport three more times and the provider none.
+ */
+import type {
+  ComputerHostControlResultV1,
+  ComputerHostFileReadResultV1,
+  ComputerHostOpenResultV1,
+  ComputerHostProvisioningV1,
+  ComputerHostViewerResultV1,
+} from "@frockbot/computer-host-protocol";
+import { DESKTOP_GUI_LEASE_KEY } from "@frockbot/computer-host-runtime";
+import {
+  computerBotKey,
+  type ComputerHostFactoryV1,
+  type ComputerHostSurfaceV1,
+} from "./computer.ts";
+import type {
+  ComputerHostCallOptions,
+  ComputerHostExecCommandV1,
+  ComputerHostExecOutcomeV1,
+} from "./host-client.ts";
+
+/** What a suite's runner says one script did. */
+export interface FakeComputerRunV1 {
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+  outputTruncated?: boolean;
+}
+
+export type FakeComputerRunnerV1 = (
+  script: string,
+) => FakeComputerRunV1 | Promise<FakeComputerRunV1>;
+
+/** One script the host was asked to run, in order. */
+export interface FakeComputerCommandV1 {
+  botId: string;
+  script: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+}
+
+interface FakeLease {
+  owner: string;
+  fresh: boolean;
+}
+
+const GUARD = /control\.sh assert-agent '([^']+)' '([^']+)' '([^']+)'/;
+/** The exit code the Computer's control script uses for a refused assertion. */
+const HUMAN_CONTROL_EXIT = 73;
+const HUMAN_CONTROL_MESSAGE = "The user is controlling this agent's computer";
+
+const encoder = new TextEncoder();
+
+/**
+ * A Computer host whose Computer is whatever the suite's runner says.
+ *
+ * One instance is one User's Computer: `factory` hands out a per-tenant
+ * surface, and the leases are shared across them exactly as one Sprite's
+ * `flock` is shared across a User's Bots.
+ */
+export class FakeComputerHost {
+  readonly commands: FakeComputerCommandV1[] = [];
+  readonly leases = new Map<string, FakeLease>();
+  readonly viewerSessions: Array<{ botId: string; action: string }> = [];
+  spriteName = "frockbot-test";
+  viewerUrl =
+    "https://frockbot-test-123.sprites.app/vnc.html#autoconnect=1&password=secret-pass";
+  display: string | undefined = ":100";
+  generation = 1;
+  provisioning?: ComputerHostProvisioningV1;
+  /** Set to refuse the next `open`, the way an exhausted slot pool does. */
+  openFailure?: Error;
+  /** The bytes `file/read` answers with, by absolute path on the Computer. */
+  readonly files = new Map<string, Uint8Array>();
+  /** Every `file/read` the host was asked for, in order. */
+  readonly reads: Array<{ botId: string; path: string }> = [];
+
+  constructor(private runner: FakeComputerRunnerV1 = () => ({})) {}
+
+  /** Replaces the runner, so a suite can change behaviour mid-test. */
+  runs(runner: FakeComputerRunnerV1): void {
+    this.runner = runner;
+  }
+
+  /** The scripts this host ran, joined — what a suite usually asserts on. */
+  get scripts(): string[] {
+    return this.commands.map((command) => command.script);
+  }
+
+  readonly factory: ComputerHostFactoryV1 = (_identity, tenant) =>
+    this.surface(tenant.botId);
+
+  surface(botId: string): ComputerHostSurfaceV1 {
+    const host = this;
+    const botKey = computerBotKey(botId);
+    return {
+      open(
+        options?: ComputerHostCallOptions,
+      ): Promise<ComputerHostOpenResultV1> {
+        options?.signal?.throwIfAborted();
+        if (host.openFailure) return Promise.reject(host.openFailure);
+        return Promise.resolve({
+          version: 1,
+          effectId: options?.effectId ?? "effect-open",
+          spriteName: host.spriteName,
+          directory: `/home/box/agent-data/agents/${botKey}`,
+          ...(host.display ? { display: host.display } : {}),
+          generation: host.generation,
+          ...(host.provisioning ? { provisioning: host.provisioning } : {}),
+        });
+      },
+
+      async exec(
+        command: ComputerHostExecCommandV1,
+        options?: ComputerHostCallOptions,
+      ): Promise<ComputerHostExecOutcomeV1> {
+        options?.signal?.throwIfAborted();
+        host.commands.push({
+          botId,
+          script: command.script,
+          ...(command.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: command.timeoutMs }),
+          ...(command.maxOutputBytes === undefined
+            ? {}
+            : { maxOutputBytes: command.maxOutputBytes }),
+        });
+        const refused = host.assert(command.script);
+        if (refused) return refused;
+        const run = await host.runner(command.script);
+        return {
+          effectId: options?.effectId ?? "effect-exec",
+          exitCode: run.exitCode ?? 0,
+          stdout: encoder.encode(run.stdout ?? ""),
+          stderr: encoder.encode(run.stderr ?? ""),
+          outputTruncated: run.outputTruncated ?? false,
+        };
+      },
+
+      fileRead(
+        path: string,
+        options?: ComputerHostCallOptions,
+      ): Promise<ComputerHostFileReadResultV1> {
+        options?.signal?.throwIfAborted();
+        host.reads.push({ botId, path });
+        const bytes = host.files.get(path);
+        if (!bytes) {
+          return Promise.reject(new Error(`no such file: ${path}`));
+        }
+        return Promise.resolve({
+          version: 1,
+          effectId: options?.effectId ?? "effect-file-read",
+          entry: {
+            path,
+            kind: "file",
+            size: bytes.byteLength,
+            mode: 0o600,
+          },
+          bytesBase64: Buffer.from(bytes).toString("base64"),
+        });
+      },
+
+      control(
+        action: "acquire" | "renew" | "release",
+        ownerId: string,
+        maxAgeSeconds: number,
+        options?: ComputerHostCallOptions & {
+          scope?: "bot" | "desktop-gui";
+        },
+      ): Promise<ComputerHostControlResultV1> {
+        options?.signal?.throwIfAborted();
+        const leaseKey =
+          options?.scope === "desktop-gui" ? DESKTOP_GUI_LEASE_KEY : botKey;
+        const lease = host.leases.get(leaseKey);
+        if (action === "acquire") {
+          if (lease?.fresh && lease.owner !== ownerId) {
+            return Promise.reject(new Error("human control is active"));
+          }
+          host.leases.set(leaseKey, { owner: ownerId, fresh: true });
+        } else if (action === "renew") {
+          if (lease?.owner !== ownerId) {
+            return Promise.reject(new Error("lease owner changed"));
+          }
+          lease.fresh = true;
+        } else if (lease?.owner === ownerId) {
+          host.leases.delete(leaseKey);
+        }
+        return Promise.resolve({
+          version: 1,
+          effectId: options?.effectId ?? "effect-control",
+          action,
+          ownerId,
+          ...(action === "release"
+            ? {}
+            : {
+                expiresAt: new Date(
+                  Date.now() + maxAgeSeconds * 1_000,
+                ).toISOString(),
+              }),
+        });
+      },
+
+      viewer(
+        action: "open" | "renew" | "revoke",
+        options?: ComputerHostCallOptions & { sessionId?: string },
+      ): Promise<ComputerHostViewerResultV1> {
+        options?.signal?.throwIfAborted();
+        host.viewerSessions.push({ botId, action });
+        return Promise.resolve({
+          version: 1,
+          effectId: options?.effectId ?? "effect-viewer",
+          ...(action === "revoke"
+            ? {}
+            : {
+                session: {
+                  id: "secret-token",
+                  url: host.viewerUrl,
+                  expiresAt: new Date(Date.now() + 900_000).toISOString(),
+                },
+              }),
+        });
+      },
+    };
+  }
+
+  /**
+   * Applies the human-control guard the script carries.
+   *
+   * The guard is a line of bash on a real Computer, so a double that ignored
+   * it would let a suite prove the provider respects a lease it never
+   * consulted. Exit 73 is what the Computer's own control script answers.
+   */
+  private assert(script: string): ComputerHostExecOutcomeV1 | undefined {
+    const match = GUARD.exec(script);
+    if (!match) return undefined;
+    const [, botKey = "", desktopKey = "", owner = ""] = match;
+    for (const key of [botKey, desktopKey]) {
+      const lease = this.leases.get(key);
+      if (lease?.fresh && lease.owner !== owner) {
+        return {
+          effectId: "effect-refused",
+          exitCode: HUMAN_CONTROL_EXIT,
+          stdout: encoder.encode(""),
+          stderr: encoder.encode(`${HUMAN_CONTROL_MESSAGE}: ${lease.owner}`),
+          outputTruncated: false,
+        };
+      }
+      if (lease && !lease.fresh) this.leases.delete(key);
+    }
+    return undefined;
+  }
+}

package/src/host.ts

@@ -0,0 +1,331 @@
+import type { Entry } from "@cordisjs/plugin-webui";
+import { ComputerError } from "@frockbot/computer-core";
+import type { ComputerState } from "@frockbot/plugin-computer/shared";
+import { computerUpdateLabelV1 } from "@frockbot/plugin-computer/protocol";
+import {
+  initialComputerMachineState,
+  transitionComputerState,
+  type ComputerMachineEvent,
+  type ComputerMachineState,
+} from "@frockbot/plugin-computer/client-state-machine";
+import type { Context, Plugin } from "cordis";
+import {
+  type ComputerBotIdentity,
+  type FlySpriteAgentComputer,
+  FlySpriteComputer,
+} from "./computer.ts";
+import { flySpriteNameForComputer } from "./provider.ts";
+
+export function configuredFlyBotId(
+  environment: { FROCKBOT_BOT_ID?: string } = process.env as {
+    FROCKBOT_BOT_ID?: string;
+  },
+): string {
+  return environment.FROCKBOT_BOT_ID?.trim() || "barebones";
+}
+
+class FlySpriteHostController {
+  private readonly computer: FlySpriteAgentComputer;
+  private readonly configured: boolean;
+  private readonly entry: Entry<ComputerState>;
+  private readonly data: ComputerState;
+  private machine: ComputerMachineState;
+  private controlHeartbeat?: ReturnType<typeof setInterval>;
+  private viewerHeartbeat?: ReturnType<typeof setInterval>;
+  private viewerSessionId?: string;
+  private controlRequest?: Promise<void>;
+  private takingControl = false;
+
+  constructor(
+    ctx: Context,
+    computer: FlySpriteComputer,
+    identity: ComputerBotIdentity,
+  ) {
+    this.computer = computer.bot(identity);
+    this.configured = computer.configured;
+    this.machine = transitionComputerState(initialComputerMachineState(), {
+      type: "configured",
+      botId: this.computer.botId,
+      providerLabel: "Fly Sprites",
+      configured: computer.configured,
+      message: computer.configured
+        ? "Persistent Fly Sprite computer"
+        : "Set SPRITES_TOKEN to attach a computer",
+    });
+    const data: ComputerState = {
+      ...this.machine,
+      connect: () => this.connect(),
+      openViewer: () => this.openViewer(),
+      closeViewer: () => this.closeViewer(),
+      takeControl: () => this.takeOver(),
+      releaseControl: () => this.release(),
+      runDoctor: () => this.runDoctor(),
+      retry: () => this.connect(),
+    };
+    this.data = data;
+    this.entry = ctx.webui.addEntry(
+      {
+        modulePath: "@frockbot/plugin-computer",
+        baseUrl: import.meta.resolve("@frockbot/plugin-computer/package.json"),
+        source: "./src/client/index.ts",
+        manifest: "./dist/manifest.json",
+      },
+      data,
+    );
+  }
+
+  async dispose(): Promise<void> {
+    this.stopControlHeartbeat();
+    this.stopViewerHeartbeat();
+    if (this.takingControl) {
+      try {
+        await this.computer.releaseControl();
+      } catch {
+        // Best-effort cleanup during application shutdown.
+      }
+    }
+    this.entry.dispose();
+  }
+
+  private async connect(): Promise<void> {
+    if (!this.configured) return;
+    this.apply({ type: "connect-requested" });
+    try {
+      const connection = await this.computer.connect();
+      this.viewerSessionId = connection.viewerSessionId;
+      this.apply({ type: "connected", viewerUrl: connection.viewerUrl });
+      const updateLabel = computerUpdateLabelV1(connection.message);
+      if (updateLabel) {
+        this.apply({ type: "update-reported", message: updateLabel });
+      }
+    } catch (error) {
+      this.fail(error);
+    }
+  }
+
+  private async openViewer(): Promise<void> {
+    if (this.machine.expanded) return;
+    const wake = this.machine.phase === "idle";
+    this.apply({ type: "viewer-expanded" });
+    if (wake) await this.connect();
+  }
+
+  private async closeViewer(): Promise<void> {
+    if (!this.machine.expanded) return;
+    if (this.controlRequest) {
+      try {
+        await this.controlRequest;
+      } catch {
+        // The acquisition failure is already the visible machine state.
+      }
+    }
+    if (this.takingControl) await this.release();
+    this.apply({ type: "viewer-collapsed" });
+  }
+
+  private takeOver(): Promise<void> {
+    if (this.controlRequest) return this.controlRequest;
+    const pending = this.acquireControl();
+    this.controlRequest = pending.finally(() => {
+      this.controlRequest = undefined;
+    });
+    return this.controlRequest;
+  }
+
+  private async acquireControl(): Promise<void> {
+    if (!this.configured || this.takingControl) return;
+    if (!this.current().viewerUrl) await this.connect();
+    if (!this.current().viewerUrl) return;
+    this.apply({ type: "take-control-requested" });
+    try {
+      await this.computer.takeControl();
+      this.takingControl = true;
+      this.startControlHeartbeat();
+      this.apply({ type: "control-acquired" });
+    } catch (error) {
+      this.fail(error);
+    }
+  }
+
+  private async release(): Promise<void> {
+    if (!this.takingControl) return;
+    try {
+      await this.computer.releaseControl();
+      this.stopControlHeartbeat();
+      this.takingControl = false;
+      this.apply({ type: "control-released" });
+    } catch (error) {
+      this.fail(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Runs the Computer's self-check and publishes the report.
+   *
+   * A failed run is reported as a failed run rather than as a Computer in an
+   * error phase: the self-check not answering is a fact about the self-check,
+   * and the desktop beside it may be perfectly fine.
+   */
+  private async runDoctor(): Promise<void> {
+    if (!this.configured) return;
+    try {
+      const report = await this.computer.doctor(new AbortController().signal);
+      this.apply({
+        type: "doctor-updated",
+        doctor: {
+          version: 1,
+          capturedAt: report.capturedAt,
+          summary: report.summary,
+          checks: report.checks.map((check) => ({ version: 1, ...check })),
+        },
+      });
+    } catch (error) {
+      this.apply({
+        type: "doctor-updated",
+        doctor: {
+          version: 1,
+          capturedAt: new Date().toISOString(),
+          summary: "the self-check could not be run",
+          checks: [
+            {
+              version: 1,
+              name: "self-check",
+              status: "fail",
+              detail: error instanceof Error ? error.message : String(error),
+            },
+          ],
+        },
+      });
+    }
+  }
+
+  private current(): ComputerState {
+    return this.data;
+  }
+
+  private startControlHeartbeat(): void {
+    this.stopControlHeartbeat();
+    this.controlHeartbeat = setInterval(
+      () => void this.refreshControl(),
+      30_000,
+    );
+  }
+
+  private stopControlHeartbeat(): void {
+    if (this.controlHeartbeat) clearInterval(this.controlHeartbeat);
+    this.controlHeartbeat = undefined;
+  }
+
+  private syncViewerHeartbeat(): void {
+    if (!this.machine.expanded || !this.viewerSessionId) {
+      this.stopViewerHeartbeat();
+      return;
+    }
+    if (!this.viewerHeartbeat) {
+      this.viewerHeartbeat = setInterval(
+        () => void this.refreshViewer(),
+        30_000,
+      );
+    }
+  }
+
+  private stopViewerHeartbeat(): void {
+    if (this.viewerHeartbeat) clearInterval(this.viewerHeartbeat);
+    this.viewerHeartbeat = undefined;
+  }
+
+  private async refreshViewer(): Promise<void> {
+    const sessionId = this.viewerSessionId;
+    if (!sessionId) return;
+    try {
+      await this.computer.refreshViewer(sessionId);
+      const viewerUrl = this.current().viewerUrl;
+      if (this.machine.phase === "updating" && viewerUrl) {
+        this.apply({ type: "connected", viewerUrl });
+      }
+    } catch (error) {
+      this.viewerSessionId = undefined;
+      const detail = error instanceof Error ? error.message : String(error);
+      this.apply({
+        type: "viewer-disconnected",
+        message: `Viewer disconnected: ${detail}`,
+      });
+    }
+  }
+
+  private async refreshControl(): Promise<void> {
+    try {
+      await this.computer.refreshControl();
+    } catch (error) {
+      this.stopControlHeartbeat();
+      this.takingControl = false;
+      const detail = error instanceof Error ? error.message : String(error);
+      this.apply({
+        type: "failed",
+        message: `Human control lease was lost: ${detail}`,
+        takingControl: false,
+      });
+    }
+  }
+
+  private apply(event: ComputerMachineEvent): void {
+    this.machine = transitionComputerState(this.machine, event);
+    Object.assign(this.data, this.machine);
+    this.entry.mutate((data) => Object.assign(data, this.machine));
+    this.syncViewerHeartbeat();
+  }
+
+  private fail(error: unknown): void {
+    if (error instanceof ComputerError && error.code === "updating") {
+      this.apply({
+        type: "update-reported",
+        message: computerUpdateLabelV1(error.message) ?? error.message,
+      });
+      return;
+    }
+    this.apply({
+      type: "failed",
+      message: error instanceof Error ? error.message : String(error),
+      takingControl: this.takingControl,
+    });
+  }
+}
+
+export function createFlySpriteHostPlugin(
+  computer: FlySpriteComputer,
+  identity: ComputerBotIdentity = {
+    id: configuredFlyBotId(),
+    name: process.env.FROCKBOT_AGENT_NAME?.trim() || "Barebones",
+  },
+): Plugin.Function {
+  const plugin: Plugin.Function = (ctx) => {
+    const controller = new FlySpriteHostController(ctx, computer, identity);
+    return () => controller.dispose();
+  };
+  plugin.inject = ["webui"];
+  return plugin;
+}
+
+const defaultUserId = process.env.FROCKBOT_USER_ID?.trim() || "local-user";
+const defaultBotId = configuredFlyBotId();
+
+const selectedProvider =
+  process.env.FROCKBOT_COMPUTER_PROVIDER?.trim() || "fly-sprite";
+
+export const flySpriteHostPlugin: Plugin.Function =
+  selectedProvider === "fly-sprite"
+    ? createFlySpriteHostPlugin(
+        new FlySpriteComputer({
+          respectHumanControl: true,
+          // One Sprite per User (ADR 0012): the Bot is a tenant on it.
+          spriteName: flySpriteNameForComputer({ userId: defaultUserId }),
+        }),
+        {
+          id: defaultBotId,
+          name: process.env.FROCKBOT_AGENT_NAME?.trim() || "Barebones",
+        },
+      )
+    : () => undefined;
+
+export default flySpriteHostPlugin;

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./computer.js";
+export * from "./host.js";
+export * from "./host-client.js";
+export { default as flySpriteManifest } from "./manifest.js";
+export * from "./provider.js";
+export * from "./sync.js";
+export * from "./workspace.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;