@frockbot/plugin-user-machine 0.0.0 → 0.1.0

package/src/desktop.ts

@@ -0,0 +1,238 @@
+// The registered machine's device agent, as a `trusted-main` Contribution.
+//
+// The plan's open decision 6: the device agent is the FrockBot desktop app
+// itself. It needs no new binary, no notarization and no installer, and it
+// matches the register's own evidence that "registered machines" is a section
+// of GrokBot's desktop Settings. `connected` reports exactly what is true —
+// the app is running.
+//
+// This file is the wiring and nothing else. It imports no `electron` and no
+// `node:*`, because the house rule is that Electron authority lives in one
+// file in `apps/desktop` and reaches Packages as a cordis capability. What it
+// does is:
+//
+//   * build `MachineDeviceAgentV1` (the loop, in `./device.ts`) over the
+//     `desktopMachineHost` and `desktopSecretStore` capabilities,
+//   * register three desktop commands so the renderer can pair, unpair and
+//     read status, and
+//   * start the loop, and stop it on disposal.
+//
+// Everything decidable is in `./device.ts` and `./device-runner.ts`, both of
+// which run under `bun test` with no Electron at all.
+
+import type { DesktopCommand } from "@frockbot/desktop-core";
+import {
+  MACHINE_LIMITS_V1,
+  type MachineCapabilityV1,
+  type MachinePlatformV1,
+} from "@frockbot/machine-protocol";
+import type { Plugin } from "cordis";
+import {
+  createMachineDeviceRunnerV1,
+  type MachineMessagesOpRunnerV1,
+} from "./device-runner.js";
+import {
+  MachineDeviceAgentV1,
+  type MachineDeviceAgentStatusV1,
+  type MachineSecretStoreV1,
+} from "./device.js";
+
+/** The key the machine token rests under in the OS secure store. */
+export const MACHINE_TOKEN_SECRET_KEY_V1 = "frockbot.machine-token";
+
+export const MACHINE_AGENT_STATUS_COMMAND_V1 = "machine.agent.status";
+export const MACHINE_AGENT_PAIR_COMMAND_V1 = "machine.agent.pair";
+export const MACHINE_AGENT_UNPAIR_COMMAND_V1 = "machine.agent.unpair";
+
+export interface MachineDesktopConfigV1 {
+  /** The deployment this laptop dials. Never a path — an origin. */
+  origin: string;
+  /** What the agent reports as its own version at enrollment. */
+  agentVersion: string;
+  /** Injected in tests; the platform's `fetch` otherwise. */
+  fetch?(input: string, init?: RequestInit): Promise<Response>;
+  /**
+   * Row 57g's Messages handlers, supplied by the Electron shell on macOS.
+   *
+   * Absent — every other platform, and a macOS build whose shell wired none —
+   * and this agent does not report the `messages` capability at all, so the
+   * backend never registers a Messages tool against it. Two halves of one gate:
+   * the enrollment decoder refuses `messages` from a non-macOS agent, and this
+   * refuses to claim it without something behind it.
+   */
+  messages?: MachineMessagesOpRunnerV1;
+  /** Started on mount unless a test wants to drive cycles by hand. */
+  autoStart?: boolean;
+}
+
+export interface MachinePairCommandInputV1 {
+  code: string;
+}
+
+export function decodeMachinePairCommandInputV1(
+  input: unknown,
+): MachinePairCommandInputV1 {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new Error("machine pairing input must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 1 || keys[0] !== "code") {
+    throw new Error("machine pairing input takes only a code");
+  }
+  const code = typeof value.code === "string" ? value.code.trim() : "";
+  if (!code || code.length > MACHINE_LIMITS_V1.pairingCode) {
+    throw new Error("machine pairing code is required");
+  }
+  return { code };
+}
+
+/** The two commands with no input at all take no input at all. */
+export function decodeMachineEmptyCommandInputV1(
+  input: unknown,
+): Record<string, never> {
+  if (
+    typeof input !== "object" ||
+    input === null ||
+    Array.isArray(input) ||
+    Reflect.ownKeys(input).length > 0
+  ) {
+    throw new Error("this machine agent command takes no input");
+  }
+  return {};
+}
+
+/**
+ * The secret store, narrowed to one key.
+ *
+ * The capability is a general key-value store because the shell may hold other
+ * secrets later; the agent should not be able to read them, so it is handed a
+ * closure over its own key and nothing else.
+ */
+export function machineSecretStoreV1(
+  store: {
+    read(key: string): Promise<string | undefined>;
+    write(key: string, value: string): Promise<void>;
+    clear(key: string): Promise<void>;
+  },
+  key: string = MACHINE_TOKEN_SECRET_KEY_V1,
+): MachineSecretStoreV1 {
+  return {
+    read: () => store.read(key),
+    write: (value) => store.write(key, value),
+    clear: () => store.clear(key),
+  };
+}
+
+/**
+ * What this agent reports it can do on every platform the shell runs on.
+ */
+export const MACHINE_DESKTOP_CAPABILITIES_V1: readonly MachineCapabilityV1[] = [
+  "exec",
+  "files",
+];
+
+/**
+ * What this agent reports, given its platform and what the shell wired.
+ *
+ * Row 57g's second gate, and it is deliberately conjunctive: `messages` is
+ * claimed only by a macOS agent that actually has handlers behind it. Pure, so
+ * the gate is asserted rather than inferred from a running Electron app.
+ */
+export function machineDesktopCapabilitiesV1(
+  platform: MachinePlatformV1,
+  messages: boolean,
+): MachineCapabilityV1[] {
+  return [
+    ...MACHINE_DESKTOP_CAPABILITIES_V1,
+    ...(platform === "macos" && messages
+      ? (["messages"] as MachineCapabilityV1[])
+      : []),
+  ];
+}
+
+export const machineDesktopPlugin: Plugin.Function<MachineDesktopConfigV1> = (
+  ctx,
+  config,
+) => {
+  const identity = ctx.desktopMachineHost.identity();
+  const capabilities = machineDesktopCapabilitiesV1(
+    identity.platform,
+    config.messages !== undefined,
+  );
+  const agent = new MachineDeviceAgentV1({
+    origin: config.origin,
+    fetch: config.fetch ?? ((input, init) => fetch(input, init)),
+    secrets: machineSecretStoreV1(ctx.desktopSecretStore),
+    runner: createMachineDeviceRunnerV1({
+      host: ctx.desktopMachineHost,
+      capabilities,
+      ...(config.messages === undefined ? {} : { messages: config.messages }),
+    }),
+    label: identity.label,
+    platform: identity.platform,
+    agentVersion: config.agentVersion,
+    capabilities,
+  });
+
+  const status: DesktopCommand<
+    Record<string, never>,
+    MachineDeviceAgentStatusV1
+  > = {
+    id: MACHINE_AGENT_STATUS_COMMAND_V1,
+    decode: decodeMachineEmptyCommandInputV1,
+    execute: async () => {
+      await agent.paired();
+      return agent.status();
+    },
+  };
+
+  const pair: DesktopCommand<
+    MachinePairCommandInputV1,
+    MachineDeviceAgentStatusV1
+  > = {
+    id: MACHINE_AGENT_PAIR_COMMAND_V1,
+    decode: decodeMachinePairCommandInputV1,
+    execute: async (input) => {
+      const paired = await agent.pair(input.code);
+      // The loop is what makes the machine read `connected`, so pairing starts
+      // it rather than waiting for the next launch.
+      agent.start();
+      return paired;
+    },
+  };
+
+  const unpair: DesktopCommand<
+    Record<string, never>,
+    MachineDeviceAgentStatusV1
+  > = {
+    id: MACHINE_AGENT_UNPAIR_COMMAND_V1,
+    decode: decodeMachineEmptyCommandInputV1,
+    execute: () => agent.unpair(),
+  };
+
+  const registrations = [
+    ctx.desktopCommands.register(status),
+    ctx.desktopCommands.register(pair),
+    ctx.desktopCommands.register(unpair),
+  ];
+
+  if (config.autoStart !== false) {
+    // Only if this laptop already holds a token: an unpaired agent has nothing
+    // to poll, and the loop would otherwise idle against a door it has no key
+    // to.
+    void agent.paired().then((paired) => {
+      if (paired) agent.start();
+    });
+  }
+
+  return [...registrations, () => void agent.stop()];
+};
+
+machineDesktopPlugin.inject = [
+  "desktopCommands",
+  "desktopMachineHost",
+  "desktopSecretStore",
+];
+
+export default machineDesktopPlugin;

package/src/device-runner.test.ts

@@ -0,0 +1,326 @@
+// What a command becomes, with a fake laptop underneath.
+//
+// Every classification the agent makes about an op's result is here, which is
+// the point of the split: `apps/desktop`'s host spawns and reads, and decides
+// nothing, so the decisions are all provable in CI.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  DesktopMachineExecResult,
+  DesktopMachineFileResult,
+} from "@frockbot/desktop-core";
+import type { MachineCommandV1, MachineOpV1 } from "@frockbot/machine-protocol";
+import {
+  createMachineDeviceRunnerV1,
+  machineRefusalV1,
+  type MachineDeviceHostV1,
+} from "./device-runner.js";
+
+const NOW = Date.parse("2026-09-01T00:00:05.000Z");
+
+function commandFor(op: MachineOpV1): MachineCommandV1 {
+  return {
+    schemaVersion: 1,
+    commandId: "tool-0-1-0",
+    machineId: "m-1",
+    botId: "scout",
+    runId: "run-1",
+    turn: 1,
+    approvalId: "tool-0-1-0",
+    op,
+    issuedAt: "2026-09-01T00:00:00.000Z",
+    status: "claimed",
+  };
+}
+
+function host(overrides: Partial<MachineDeviceHostV1> = {}): {
+  host: MachineDeviceHostV1;
+  execCalls: unknown[];
+  readCalls: unknown[];
+} {
+  const execCalls: unknown[] = [];
+  const readCalls: unknown[] = [];
+  return {
+    execCalls,
+    readCalls,
+    host: {
+      identity: () => ({ label: "Laptop", platform: "macos" }),
+      exec: (request) => {
+        execCalls.push(request);
+        return Promise.resolve({
+          exitCode: 0,
+          stdout: "",
+          stderr: "",
+          truncated: false,
+          timedOut: false,
+        } satisfies DesktopMachineExecResult);
+      },
+      readFile: (request) => {
+        readCalls.push(request);
+        return Promise.resolve({
+          bytesBase64: "aGk=",
+          truncated: false,
+        } satisfies DesktopMachineFileResult);
+      },
+      ...overrides,
+    },
+  };
+}
+
+function runner(
+  fake: MachineDeviceHostV1,
+  capabilities: Array<"exec" | "files"> = ["exec", "files"],
+): ReturnType<typeof createMachineDeviceRunnerV1> {
+  return createMachineDeviceRunnerV1({
+    host: fake,
+    capabilities,
+    now: () => NOW,
+  });
+}
+
+const signal = new AbortController().signal;
+
+describe("machine device runner", () => {
+  test("an exec that exits zero is ok, and the bounds are the op's", async () => {
+    const requests: unknown[] = [];
+    const fake = host({
+      exec: (request) => {
+        requests.push(request);
+        return Promise.resolve({
+          exitCode: 0,
+          stdout: "hello\n",
+          stderr: "",
+          truncated: false,
+          timedOut: false,
+        });
+      },
+    });
+    const report = await runner(fake.host).run(
+      commandFor({
+        kind: "exec",
+        command: "echo hello",
+        cwd: "/tmp",
+        timeoutMs: 1_000,
+        maxOutputBytes: 64,
+      }),
+      signal,
+    );
+
+    expect(report).toEqual({
+      finishedAt: "2026-09-01T00:00:05.000Z",
+      outcome: "ok",
+      truncated: false,
+      exitCode: 0,
+      stdout: "hello\n",
+      stderr: "",
+    });
+    expect(requests[0]).toEqual({
+      command: "echo hello",
+      cwd: "/tmp",
+      timeoutMs: 1_000,
+      maxOutputBytes: 64,
+    });
+  });
+
+  test("a non-zero exit is an error, and a killed command is a timeout", async () => {
+    const failing = host({
+      exec: () =>
+        Promise.resolve({
+          exitCode: 2,
+          stdout: "",
+          stderr: "no such file\n",
+          truncated: false,
+          timedOut: false,
+        }),
+    });
+    expect(
+      await runner(failing.host).run(
+        commandFor({
+          kind: "exec",
+          command: "cat missing",
+          timeoutMs: 1_000,
+          maxOutputBytes: 64,
+        }),
+        signal,
+      ),
+    ).toMatchObject({
+      outcome: "error",
+      exitCode: 2,
+      stderr: "no such file\n",
+    });
+
+    const killed = host({
+      exec: () =>
+        Promise.resolve({
+          stdout: "partial",
+          stderr: "",
+          truncated: true,
+          timedOut: true,
+        }),
+    });
+    const report = await runner(killed.host).run(
+      commandFor({
+        kind: "exec",
+        command: "sleep 60",
+        timeoutMs: 25,
+        maxOutputBytes: 4,
+      }),
+      signal,
+    );
+    expect(report).toMatchObject({
+      outcome: "timeout",
+      truncated: true,
+      message: "the command was killed after 25ms",
+    });
+    // A killed process has no exit code, and one is not invented.
+    expect(report.exitCode).toBeUndefined();
+  });
+
+  test("a read answers base64 and carries truncation through", async () => {
+    const fake = host({
+      readFile: () =>
+        Promise.resolve({ bytesBase64: "dHJ1bmM=", truncated: true }),
+    });
+    const report = await runner(fake.host).run(
+      commandFor({ kind: "read", path: "/etc/hosts", maxBytes: 8 }),
+      signal,
+    );
+    expect(report).toEqual({
+      finishedAt: "2026-09-01T00:00:05.000Z",
+      outcome: "ok",
+      truncated: true,
+      bytesBase64: "dHJ1bmM=",
+    });
+  });
+
+  test("a copy to the Computer reads the machine's file", async () => {
+    const fake = host();
+    const report = await runner(fake.host).run(
+      commandFor({
+        kind: "copy-to-computer",
+        path: "/Users/tim/notes.txt",
+        workspacePath: "notes.txt",
+      }),
+      signal,
+    );
+    expect(report.outcome).toBe("ok");
+    expect(fake.readCalls[0]).toMatchObject({ path: "/Users/tim/notes.txt" });
+  });
+
+  test("a copy from the Computer refuses visibly, because v1 carries no bytes", async () => {
+    const fake = host();
+    const report = await runner(fake.host).run(
+      commandFor({
+        kind: "copy-from-computer",
+        path: "/Users/tim/notes.txt",
+        workspacePath: "notes.txt",
+      }),
+      signal,
+    );
+    expect(report.outcome).toBe("refused");
+    expect(report.message).toStartWith("Refused: ");
+    expect(fake.readCalls).toEqual([]);
+    expect(fake.execCalls).toEqual([]);
+  });
+
+  test("an op the agent never reported the capability for is refused, not run", async () => {
+    const fake = host();
+    const report = await runner(fake.host, ["files"]).run(
+      commandFor({
+        kind: "exec",
+        command: "rm -rf /",
+        timeoutMs: 1_000,
+        maxOutputBytes: 64,
+      }),
+      signal,
+    );
+    expect(report.message).toBe(
+      machineRefusalV1("this machine's agent does not offer shell execution"),
+    );
+    expect(fake.execCalls).toEqual([]);
+  });
+
+  test("a host that throws becomes an error result, never an escape", async () => {
+    const fake = host({
+      readFile: () => Promise.reject(new Error("ENOENT: no such file")),
+    });
+    expect(
+      await runner(fake.host).run(
+        commandFor({ kind: "read", path: "/nope", maxBytes: 8 }),
+        signal,
+      ),
+    ).toMatchObject({ outcome: "error", message: "ENOENT: no such file" });
+  });
+});
+
+describe("a messages op (register row 57g)", () => {
+  const messagesOp: MachineOpV1 = {
+    kind: "messages",
+    call: { kind: "activity", limit: 5 },
+  };
+
+  test("is handed to the handler the shell wired, verbatim", async () => {
+    const seen: unknown[] = [];
+    const runner = createMachineDeviceRunnerV1({
+      host: host().host,
+      capabilities: ["exec", "files", "messages"],
+      now: () => NOW,
+      messages: (call) => {
+        seen.push(call);
+        return Promise.resolve({
+          finishedAt: "2026-09-01T00:00:05.000Z",
+          outcome: "ok",
+          truncated: false,
+          stdout: '{"kind":"items","items":[]}',
+        });
+      },
+    });
+    const report = await runner.run(
+      commandFor(messagesOp),
+      new AbortController().signal,
+    );
+    expect(seen).toEqual([{ kind: "activity", limit: 5 }]);
+    expect(report.outcome).toBe("ok");
+  });
+
+  test("an agent with no handler refuses rather than answering an empty inbox", async () => {
+    const runner = createMachineDeviceRunnerV1({
+      host: host().host,
+      // The record says it can; this build cannot. Saying so is the only
+      // honest answer — an empty result would read as an empty Messages app.
+      capabilities: ["exec", "files", "messages"],
+      now: () => NOW,
+    });
+    const report = await runner.run(
+      commandFor(messagesOp),
+      new AbortController().signal,
+    );
+    expect(report.outcome).toBe("refused");
+    expect(report.message).toBe(
+      machineRefusalV1("this machine's agent does not offer Messages access"),
+    );
+  });
+
+  test("an agent that never reported the capability refuses before the handler", async () => {
+    let called = false;
+    const runner = createMachineDeviceRunnerV1({
+      host: host().host,
+      capabilities: ["exec", "files"],
+      now: () => NOW,
+      messages: () => {
+        called = true;
+        return Promise.resolve({
+          finishedAt: "2026-09-01T00:00:05.000Z",
+          outcome: "ok",
+          truncated: false,
+        });
+      },
+    });
+    const report = await runner.run(
+      commandFor(messagesOp),
+      new AbortController().signal,
+    );
+    expect(report.outcome).toBe("refused");
+    expect(called).toBe(false);
+  });
+});