@frockbot/plugin-user-machine 0.0.0 → 0.1.0

package/src/client/index.ts

@@ -0,0 +1,180 @@
+/// <reference path="../env.d.ts" />
+
+// The Computer settings section: the user's own machines, live.
+//
+// Everything here goes through `ctx.transport.hostedRequest`, which is the
+// session, and through `@frockbot/machine-protocol`'s decoders, which are the
+// seam. The one thing that does not is the desktop bridge — `window
+// .frockbotMachineAgent`, exposed by the Electron preload — and its answers
+// are decoded too, because a different runtime is a seam whoever owns it.
+//
+// The pairing UX is two-sided on purpose:
+//
+//   * in the **desktop shell**, "Pair this computer" mints a code and hands it
+//     straight to the agent in the main process; the code never leaves the
+//     app. There is also a field to paste a code minted elsewhere, which is
+//     what "enter pairing code" means when the browser and the laptop are two
+//     different devices.
+//   * in a **browser**, there is no agent to hand a code to, so the section
+//     shows the code and its expiry and says where to type it.
+//
+// Revoking is the browser's, always: a machine cannot un-revoke itself, and
+// the token dies on the next verify wherever the laptop is.
+
+import {
+  clientSurfaceRegistryKey,
+  type ClientPlugin,
+} from "@frockbot/client-core";
+import {
+  decodeMachineListViewV1,
+  decodeMachinePairingOfferV1,
+  machineRoutePathV1,
+} from "@frockbot/machine-protocol";
+import { ref } from "vue";
+import { decodeMachineDeviceAgentStatusV1 } from "../device.js";
+import MachineSection from "./MachineSection.vue";
+import MachineSurface from "./MachineSurface.vue";
+import {
+  machinesStateKey,
+  type MachineAgentBridgeV1,
+  type MachinesClientState,
+} from "./state.js";
+
+/** The surface the section opens. Not a settings anchor: a registered surface. */
+export const MACHINE_SURFACE_ID_V1 = "user-machines";
+
+function message(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}
+
+/** The desktop bridge, if this client is running inside the Electron shell. */
+export function machineAgentBridgeV1(): MachineAgentBridgeV1 | undefined {
+  const bridge = (globalThis as { frockbotMachineAgent?: MachineAgentBridgeV1 })
+    .frockbotMachineAgent;
+  return typeof bridge?.pair === "function" ? bridge : undefined;
+}
+
+export const userMachineClientPlugin: ClientPlugin = (ctx) => {
+  const surfaces = ctx.inject(clientSurfaceRegistryKey);
+  const bridge = machineAgentBridgeV1();
+  const request = (
+    path: string,
+    method?: "GET" | "POST",
+    body?: string,
+  ): Promise<unknown> => {
+    if (!ctx.transport.hostedRequest) {
+      throw new Error("Registered machines are unavailable on this client");
+    }
+    return ctx.transport.hostedRequest(path, method, body);
+  };
+
+  const mintOffer = async (label?: string): Promise<void> => {
+    state.value.offer = decodeMachinePairingOfferV1(
+      await request(
+        machineRoutePathV1("pair"),
+        "POST",
+        JSON.stringify(label === undefined ? {} : { label }),
+      ),
+    );
+  };
+
+  const readAgent = async (): Promise<void> => {
+    if (!bridge) return;
+    state.value.agent = decodeMachineDeviceAgentStatusV1(await bridge.status());
+  };
+
+  const guarded = async (work: () => Promise<void>): Promise<void> => {
+    state.value.busy = true;
+    try {
+      await work();
+      state.value.error = undefined;
+    } catch (error) {
+      state.value.error = message(error, "The machine registry refused");
+    } finally {
+      state.value.busy = false;
+    }
+  };
+
+  const state = ref<MachinesClientState>({
+    busy: false,
+    desktop: bridge !== undefined,
+    async load() {
+      await guarded(async () => {
+        state.value.view = decodeMachineListViewV1(
+          await request(machineRoutePathV1("list")),
+        );
+        await readAgent();
+      });
+    },
+    async requestCode(label?: string) {
+      await guarded(() => mintOffer(label));
+    },
+    async pairThisComputer() {
+      await guarded(async () => {
+        if (!bridge) throw new Error("This client is not the desktop app");
+        await mintOffer();
+        const offer = state.value.offer;
+        if (!offer) throw new Error("No pairing code was issued");
+        state.value.agent = decodeMachineDeviceAgentStatusV1(
+          await bridge.pair(offer.code),
+        );
+        // The code is one-time: once it has been spent it is not a secret to
+        // keep showing, and showing it invites a second, failing, attempt.
+        state.value.offer = undefined;
+        state.value.view = decodeMachineListViewV1(
+          await request(machineRoutePathV1("list")),
+        );
+      });
+    },
+    async enterCode(code: string) {
+      await guarded(async () => {
+        if (!bridge) throw new Error("This client is not the desktop app");
+        state.value.agent = decodeMachineDeviceAgentStatusV1(
+          await bridge.pair(code.trim()),
+        );
+        state.value.offer = undefined;
+        state.value.view = decodeMachineListViewV1(
+          await request(machineRoutePathV1("list")),
+        );
+      });
+    },
+    async revoke(machineId: string) {
+      await guarded(async () => {
+        // Revocation answers with the whole registry, so the row's new state
+        // comes from the authority rather than from a local edit.
+        state.value.view = decodeMachineListViewV1(
+          await request(
+            machineRoutePathV1("revoke", { machineId }),
+            "POST",
+            JSON.stringify({}),
+          ),
+        );
+        if (state.value.agent?.machineId === machineId) await readAgent();
+      });
+    },
+    async forgetThisComputer() {
+      await guarded(async () => {
+        if (!bridge) throw new Error("This client is not the desktop app");
+        state.value.agent = decodeMachineDeviceAgentStatusV1(
+          await bridge.unpair(),
+        );
+      });
+    },
+  });
+
+  return [
+    ctx.provide(machinesStateKey, state),
+    surfaces.register({
+      id: MACHINE_SURFACE_ID_V1,
+      title: "Registered machines",
+      component: MachineSurface,
+    }),
+    ctx.slot({
+      slot: "frockbot.user-settings-sections",
+      order: 30,
+      component: MachineSection,
+    }),
+  ];
+};
+
+export default userMachineClientPlugin;

package/src/client/state.ts

@@ -0,0 +1,49 @@
+import type {
+  MachineListViewV1,
+  MachinePairingOfferV1,
+} from "@frockbot/machine-protocol";
+import type { InjectionKey, Ref } from "vue";
+import type { MachineDeviceAgentStatusV1 } from "../device.js";
+
+/**
+ * The Electron preload bridge, as the renderer sees it.
+ *
+ * Present only inside the desktop shell. In a browser it is absent, which is
+ * exactly the difference the section renders: a browser can register *other*
+ * machines by handing them a code, but it cannot register itself.
+ */
+export interface MachineAgentBridgeV1 {
+  status(): Promise<unknown>;
+  pair(code: string): Promise<unknown>;
+  unpair(): Promise<unknown>;
+}
+
+export interface MachinesClientState {
+  /** The registry, as the browser reads it. `connected` is the server's word. */
+  view?: MachineListViewV1;
+  /** The outstanding pairing code, once asked for. One-time, five minutes. */
+  offer?: MachinePairingOfferV1;
+  /** This laptop's own agent, when the app is the desktop shell. */
+  agent?: MachineDeviceAgentStatusV1;
+  /** True while a request is in flight; every button reads it. */
+  busy: boolean;
+  /** The last refusal, verbatim from the backend. Never swallowed. */
+  error?: string;
+  /** Whether this client can pair itself — i.e. it is the desktop shell. */
+  readonly desktop: boolean;
+  load(): Promise<void>;
+  /** Mint a pairing code for a machine that is not this one. */
+  requestCode(label?: string): Promise<void>;
+  /** Mint a code and hand it straight to this laptop's agent. */
+  pairThisComputer(): Promise<void>;
+  /** Hand a code typed by hand to this laptop's agent. */
+  enterCode(code: string): Promise<void>;
+  /** Kill every token a machine holds. The row stays as evidence. */
+  revoke(machineId: string): Promise<void>;
+  /** Forget the token on this laptop without touching the registry. */
+  forgetThisComputer(): Promise<void>;
+}
+
+export const machinesStateKey: InjectionKey<Ref<MachinesClientState>> = Symbol(
+  "user-machines-state",
+);

package/src/delivery.ts

@@ -0,0 +1,145 @@
+// The one message that travels from the User Durable Object back to a Bot.
+//
+// A machine answers the backend, not the Bot: the result lands on the User
+// object, which is the queue's authority. The Bot is owed the fact that it
+// landed, and it is owed it durably — "its outcome is delivered to the Bot's
+// next conversational Turn as durable input" — so the User object hands the Bot
+// this, and the Bot enqueues a `PendingBotInputV1` from it.
+//
+// It carries a *preview*, never the output. A machine command may return a
+// megabyte of stdout, and a preamble line that carried it would push a person's
+// own words out of the model's context to say something the Bot can read in
+// full whenever it wants, with `machine_command_check`.
+import {
+  MACHINE_LIMITS_V1,
+  MachineDecodeError,
+  MACHINE_COMMAND_OUTCOMES_V1,
+  type MachineCommandOutcomeV1,
+  type MachineCommandResultV1,
+  type MachineCommandV1,
+} from "@frockbot/machine-protocol";
+
+/** The longest preview a delivery carries. One line, not a transcript. */
+export const MACHINE_RESULT_PREVIEW_MAX = 400;
+
+export interface MachineResultDeliveryV1 {
+  schemaVersion: 1;
+  botId: string;
+  runId: string;
+  machineId: string;
+  commandId: string;
+  outcome: MachineCommandOutcomeV1;
+  finishedAt: string;
+  preview: string;
+}
+
+/** A single readable line about what the machine said. Pure. */
+export function machineResultPreviewV1(result: MachineCommandResultV1): string {
+  const parts: string[] = [];
+  if (result.exitCode !== undefined) parts.push(`exit ${result.exitCode}`);
+  const text =
+    result.message ??
+    (result.stdout && result.stdout.length > 0
+      ? result.stdout
+      : (result.stderr ?? ""));
+  const flattened = text.replace(/\s+/g, " ").trim();
+  if (flattened.length > 0) parts.push(flattened);
+  if (result.truncated) parts.push("(output truncated)");
+  if (result.bytesBase64 !== undefined) {
+    parts.push(`(${result.bytesBase64.length} base64 characters returned)`);
+  }
+  const joined = parts.join(" — ");
+  return (joined.length === 0 ? result.outcome : joined).slice(
+    0,
+    MACHINE_RESULT_PREVIEW_MAX,
+  );
+}
+
+/** The delivery one recorded result owes the Bot that asked for it. Pure. */
+export function machineResultDeliveryV1(
+  command: MachineCommandV1,
+  result: MachineCommandResultV1,
+): MachineResultDeliveryV1 {
+  return {
+    schemaVersion: 1,
+    botId: command.botId,
+    runId: command.runId,
+    machineId: command.machineId,
+    commandId: result.commandId,
+    outcome: result.outcome,
+    finishedAt: result.finishedAt,
+    preview: machineResultPreviewV1(result),
+  };
+}
+
+function text(value: unknown, maximum: number, label: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new MachineDecodeError(`${label} must be a non-empty string`);
+  }
+  if (value.length > maximum) {
+    throw new MachineDecodeError(`${label} exceeds ${maximum} characters`);
+  }
+  return value;
+}
+
+export function decodeMachineResultDeliveryV1(
+  input: unknown,
+  label = "machine result delivery",
+): MachineResultDeliveryV1 {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new MachineDecodeError(`${label} must be an object`);
+  }
+  const value = input as Record<string, unknown>;
+  const allowed = [
+    "schemaVersion",
+    "botId",
+    "runId",
+    "machineId",
+    "commandId",
+    "outcome",
+    "finishedAt",
+    "preview",
+  ];
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      throw new MachineDecodeError(`${label} has an unexpected key "${key}"`);
+    }
+  }
+  if (value.schemaVersion !== 1) {
+    throw new MachineDecodeError(`${label} schemaVersion is unsupported`);
+  }
+  if (
+    typeof value.outcome !== "string" ||
+    !MACHINE_COMMAND_OUTCOMES_V1.includes(
+      value.outcome as MachineCommandOutcomeV1,
+    )
+  ) {
+    throw new MachineDecodeError(`${label} outcome is invalid`);
+  }
+  const finishedAt = text(value.finishedAt, 64, `${label} finishedAt`);
+  if (Number.isNaN(Date.parse(finishedAt))) {
+    throw new MachineDecodeError(`${label} finishedAt is not a timestamp`);
+  }
+  return {
+    schemaVersion: 1,
+    botId: text(value.botId, MACHINE_LIMITS_V1.identifier, `${label} botId`),
+    runId: text(value.runId, MACHINE_LIMITS_V1.identifier, `${label} runId`),
+    machineId: text(
+      value.machineId,
+      MACHINE_LIMITS_V1.identifier,
+      `${label} machineId`,
+    ),
+    commandId: text(
+      value.commandId,
+      MACHINE_LIMITS_V1.identifier,
+      `${label} commandId`,
+    ),
+    outcome: value.outcome as MachineCommandOutcomeV1,
+    finishedAt,
+    preview: text(
+      value.preview,
+      MACHINE_RESULT_PREVIEW_MAX,
+      `${label} preview`,
+    ),
+  };
+}

package/src/desktop.test.ts

@@ -0,0 +1,233 @@
+// The `trusted-main` Contribution, mounted on fake capabilities.
+//
+// No Electron here — and that is the assertion as much as the convenience: the
+// contribution is wired through cordis services, so the same plugin the
+// desktop shell mounts runs under `bun test` against a fake host and a fake
+// keychain.
+
+import { describe, expect, test } from "bun:test";
+import {
+  DesktopCommandRegistry,
+  DesktopMachineHostCapability,
+  DesktopSecretStoreCapability,
+  type DesktopMachineExecResult,
+  type DesktopMachineFileResult,
+  type DesktopMachineIdentity,
+} from "@frockbot/desktop-core";
+import { Context } from "cordis";
+import {
+  MACHINE_AGENT_PAIR_COMMAND_V1,
+  MACHINE_AGENT_STATUS_COMMAND_V1,
+  MACHINE_AGENT_UNPAIR_COMMAND_V1,
+  MACHINE_DESKTOP_CAPABILITIES_V1,
+  machineDesktopCapabilitiesV1,
+  MACHINE_TOKEN_SECRET_KEY_V1,
+  decodeMachineEmptyCommandInputV1,
+  decodeMachinePairCommandInputV1,
+  machineDesktopPlugin,
+  machineSecretStoreV1,
+} from "./desktop.js";
+import {
+  decodeMachineDeviceAgentStatusV1,
+  type MachineDeviceAgentStatusV1,
+} from "./device.js";
+
+const ORIGIN = "https://bot.example.com";
+
+class FakeMachineHost extends DesktopMachineHostCapability {
+  identity(): DesktopMachineIdentity {
+    return { label: "Tims-M5-MacBook-Pro.local", platform: "macos" };
+  }
+  exec(): Promise<DesktopMachineExecResult> {
+    return Promise.resolve({
+      exitCode: 0,
+      stdout: "",
+      stderr: "",
+      truncated: false,
+      timedOut: false,
+    });
+  }
+  readFile(): Promise<DesktopMachineFileResult> {
+    return Promise.resolve({ bytesBase64: "", truncated: false });
+  }
+}
+
+class MemorySecretStore extends DesktopSecretStoreCapability {
+  readonly held = new Map<string, string>();
+  read(key: string): Promise<string | undefined> {
+    return Promise.resolve(this.held.get(key));
+  }
+  write(key: string, value: string): Promise<void> {
+    this.held.set(key, value);
+    return Promise.resolve();
+  }
+  clear(key: string): Promise<void> {
+    this.held.delete(key);
+    return Promise.resolve();
+  }
+}
+
+async function mount(
+  fetchImpl: (input: string, init?: RequestInit) => Promise<Response>,
+): Promise<{ root: Context; secrets: MemorySecretStore }> {
+  const root = new Context();
+  await root.plugin(DesktopCommandRegistry);
+  await root.plugin(FakeMachineHost);
+  await root.plugin(MemorySecretStore);
+  await root.plugin(machineDesktopPlugin, {
+    origin: ORIGIN,
+    agentVersion: "0.0.1",
+    fetch: fetchImpl,
+    autoStart: false,
+  });
+  return { root, secrets: root.desktopSecretStore as MemorySecretStore };
+}
+
+describe("machine desktop contribution inputs", () => {
+  test("a pairing code is required, trimmed, and alone", () => {
+    expect(decodeMachinePairCommandInputV1({ code: " abc " })).toEqual({
+      code: "abc",
+    });
+    expect(() => decodeMachinePairCommandInputV1({ code: "" })).toThrow();
+    expect(() =>
+      decodeMachinePairCommandInputV1({ code: "abc", extra: 1 }),
+    ).toThrow();
+    expect(() => decodeMachinePairCommandInputV1("abc")).toThrow();
+  });
+
+  test("the other two commands take nothing at all", () => {
+    expect(decodeMachineEmptyCommandInputV1({})).toEqual({});
+    expect(() => decodeMachineEmptyCommandInputV1({ code: "x" })).toThrow();
+  });
+
+  test("the secret store is narrowed to the agent's own key", async () => {
+    const keys: string[] = [];
+    const narrowed = machineSecretStoreV1({
+      read: (key: string) => {
+        keys.push(key);
+        return Promise.resolve(undefined);
+      },
+      write: (key: string) => {
+        keys.push(key);
+        return Promise.resolve();
+      },
+      clear: (key: string) => {
+        keys.push(key);
+        return Promise.resolve();
+      },
+    });
+    await narrowed.read();
+    await narrowed.write("value");
+    await narrowed.clear();
+    expect(new Set(keys)).toEqual(new Set([MACHINE_TOKEN_SECRET_KEY_V1]));
+  });
+});
+
+describe("machine desktop contribution", () => {
+  test("registers exactly three commands and removes them on disposal", async () => {
+    const { root } = await mount(() =>
+      Promise.resolve(new Response("{}", { status: 200 })),
+    );
+    expect(
+      root.desktopCommands
+        .list()
+        .map((entry) => entry.id)
+        .sort(),
+    ).toEqual(
+      [
+        MACHINE_AGENT_PAIR_COMMAND_V1,
+        MACHINE_AGENT_STATUS_COMMAND_V1,
+        MACHINE_AGENT_UNPAIR_COMMAND_V1,
+      ].sort(),
+    );
+    const commands = root.desktopCommands;
+    await root.fiber.dispose();
+    await expect(
+      commands.invoke(MACHINE_AGENT_STATUS_COMMAND_V1, {}),
+    ).rejects.toThrow("is unavailable");
+  });
+
+  test("pairing enrols with the host's own identity and keeps the token", async () => {
+    const bodies: string[] = [];
+    const { root, secrets } = await mount((input, init) => {
+      bodies.push(typeof init?.body === "string" ? init.body : "");
+      if (input.endsWith("/enroll")) {
+        return Promise.resolve(
+          Response.json({
+            schemaVersion: 1,
+            machineId: "m-1",
+            token: "machine-token",
+            keyVersion: 1,
+          }),
+        );
+      }
+      return Promise.resolve(
+        Response.json({
+          schemaVersion: 1,
+          commands: [],
+          serverTime: "2026-09-01T00:00:00.000Z",
+        }),
+      );
+    });
+
+    const status = decodeMachineDeviceAgentStatusV1(
+      await root.desktopCommands.invoke<MachineDeviceAgentStatusV1>(
+        MACHINE_AGENT_PAIR_COMMAND_V1,
+        { code: "pairing-code" },
+      ),
+    );
+
+    expect(status.enrolled).toBe(true);
+    expect(status.label).toBe("Tims-M5-MacBook-Pro.local");
+    expect(JSON.parse(bodies[0] ?? "{}")).toMatchObject({
+      label: "Tims-M5-MacBook-Pro.local",
+      platform: "macos",
+      // Row 57g's second gate: no agent reports `messages` until the macOS
+      // handlers exist.
+      capabilities: [...MACHINE_DESKTOP_CAPABILITIES_V1],
+    });
+    expect(secrets.held.get(MACHINE_TOKEN_SECRET_KEY_V1)).toContain(
+      "machine-token",
+    );
+
+    await root.desktopCommands.invoke(MACHINE_AGENT_UNPAIR_COMMAND_V1, {});
+    expect(secrets.held.has(MACHINE_TOKEN_SECRET_KEY_V1)).toBe(false);
+    await root.fiber.dispose();
+  });
+
+  test("status is readable before anything has been paired", async () => {
+    const { root } = await mount(() =>
+      Promise.reject(new Error("nothing should be dialled")),
+    );
+    expect(
+      decodeMachineDeviceAgentStatusV1(
+        await root.desktopCommands.invoke(MACHINE_AGENT_STATUS_COMMAND_V1, {}),
+      ),
+    ).toMatchObject({ enrolled: false, running: false, failures: 0 });
+    await root.fiber.dispose();
+  });
+});
+
+describe("what this agent claims it can do (register row 57g)", () => {
+  test("messages is claimed only by a Mac with handlers behind it", () => {
+    expect(machineDesktopCapabilitiesV1("macos", true)).toEqual([
+      "exec",
+      "files",
+      "messages",
+    ]);
+    // A Mac whose shell wired none: claiming it would mean every Messages
+    // command reaching an agent that can only refuse.
+    expect(machineDesktopCapabilitiesV1("macos", false)).toEqual([
+      "exec",
+      "files",
+    ]);
+    // Not a Mac. The enrollment decoder refuses the claim anyway; this is the
+    // same fact on the agent's own side of the wire.
+    for (const platform of ["windows", "linux"] as const) {
+      expect(machineDesktopCapabilitiesV1(platform, true)).toEqual([
+        "exec",
+        "files",
+      ]);
+    }
+  });
+});