@frockbot/plugin-computer 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-computer",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -29,21 +29,21 @@
   },
   "dependencies": {
     "@cordisjs/client": "0.8.2",
-    "@frockbot/client-core": "0.3.0",
-    "@frockbot/client-ui": "0.3.0",
-    "@frockbot/computer-core": "0.3.0",
-    "@frockbot/computer-host-runtime": "0.3.0",
-    "@frockbot/kernel-agent-loop": "0.3.0",
-    "@frockbot/kernel-contracts": "0.3.0",
-    "@frockbot/plugin-prompt": "0.3.0",
-    "@frockbot/plugin-shell": "0.3.0",
-    "@frockbot/plugin-tools": "0.3.0",
+    "@frockbot/client-core": "0.3.2",
+    "@frockbot/client-ui": "0.3.2",
+    "@frockbot/computer-core": "0.3.2",
+    "@frockbot/computer-host-runtime": "0.3.2",
+    "@frockbot/kernel-agent-loop": "0.3.2",
+    "@frockbot/kernel-contracts": "0.3.2",
+    "@frockbot/plugin-prompt": "0.3.2",
+    "@frockbot/plugin-shell": "0.3.2",
+    "@frockbot/plugin-tools": "0.3.2",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
-    "@frockbot/plugin-models": "0.3.0",
-    "@frockbot/plugin-testkit": "0.3.0",
+    "@frockbot/plugin-models": "0.3.2",
+    "@frockbot/plugin-testkit": "0.3.2",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.ts

@@ -312,13 +312,105 @@ function text(bytes: Uint8Array): string {
   return new TextDecoder().decode(bytes);
 }
 
+/**
+ * Appends one `computer/sync` outcome to a Session and flushes it.
+ *
+ * The single place a sync becomes a durable record, so the Turn's own policy
+ * and the one sanctioned caller outside it ({@link syncWorkspaceRootNowV1})
+ * cannot record the same fact in two shapes. A Session that is gone or
+ * disposed records nothing: a sync is never a reason to fail anything.
+ */
+async function recordComputerSyncV1(
+  sessions: SessionStore,
+  sessionId: string,
+  turn: number,
+  reason: ComputerSyncReasonV1,
+  summary: ComputerSyncSummaryV1,
+): Promise<void> {
+  const session = sessions.get(sessionId);
+  if (!session || session.disposed) return;
+  session.append({
+    type: "computer/sync",
+    turn: Math.max(1, turn),
+    reason,
+    ...summary,
+  });
+  // The record is durable before anything reports the sync happened.
+  await session.flush();
+}
+
+/**
+ * Reconciles ONE declared durable root now, outside the Turn's sync policy.
+ *
+ * THE ONE SANCTIONED EXTRA CALLER. {@link ComputerTurnSync} was deliberately
+ * narrowed — "a caller cannot get the policy wrong because there is no way to
+ * ask for a sync at another time" — and this function is the single, named
+ * exception to that sentence, added for Applet publish (ADR 0022 decision 7):
+ * "Publishing reads the built artifact from the durable root through the
+ * Workspace file surface." `applet build` writes `<appletId>/dist/` on the
+ * Computer with an ordinary shell write, and the publish reads it from the
+ * *store*. Without a push between those two the publish would read the
+ * previous build, or nothing, and record a generation for bytes that never
+ * existed — a wrong artifact rather than a visible failure. The Turn's own
+ * `turn-end` push is too late: publish happens inside the Turn.
+ *
+ * It stays narrow in four ways, and the narrowness is the reason it is
+ * allowed. It reconciles one root and not the Workspace. It wakes nothing: it
+ * takes an already-open {@link ComputerHandle}, so a hibernated Computer stays
+ * hibernated and this can never become a reason one starts. It records its
+ * outcome exactly as the Turn's policy does, under its own `publish` reason,
+ * so a Session log still says what every sync run moved and why. And it never
+ * throws — an unavailable Computer is a summary its caller reads and refuses
+ * the publish on, not an exception on the Turn.
+ *
+ * A provider with no per-root reconciliation answers `refused`, and so does a
+ * root this Computer does not sync. Neither is silently upgraded to a full
+ * `reconcile`: the caller asked for one root's bytes to be durable and is owed
+ * a true answer about that root.
+ */
+export async function syncWorkspaceRootNowV1(request: {
+  computer: ComputerHandle;
+  sessions: SessionStore;
+  sessionId: string;
+  turn: number;
+  root: WorkspaceRootV1;
+  signal?: AbortSignal;
+}): Promise<ComputerSyncSummaryV1> {
+  const { computer, sessions, sessionId, turn, root, signal } = request;
+  const sync = computer.sync;
+  let summary: ComputerSyncSummaryV1;
+  if (!sync?.reconcileRoot) {
+    summary = computerSyncSummaryV1(
+      "refused",
+      "this Computer cannot reconcile a single durable root",
+    );
+  } else {
+    try {
+      summary = await sync.reconcileRoot(
+        root,
+        "publish",
+        signal ? { signal } : undefined,
+      );
+    } catch (error) {
+      summary = computerSyncSummaryV1(
+        "unavailable",
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+  await recordComputerSyncV1(sessions, sessionId, turn, "publish", summary);
+  return summary;
+}
+
 /**
  * The Turn's sync state, and the only place this Package decides to sync.
  *
  * Deep and small on purpose: `beforeUse` and `afterTurn` are the whole
  * surface, they never throw, and every path through them either records a
  * `computer/sync` event or has nothing to record. A caller cannot get the
- * policy wrong because there is no way to ask for a sync at another time.
+ * policy wrong because there is no way to ask for a sync at another time —
+ * with exactly one named exception, {@link syncWorkspaceRootNowV1}, which
+ * reconciles a single root for an Applet publish and is documented there.
  */
 class ComputerTurnSync {
   #turn = 0;
@@ -405,21 +497,18 @@ class ComputerTurnSync {
     );
   }
 
-  private async record(
+  private record(
     sessionId: string,
     reason: ComputerSyncReasonV1,
     summary: ComputerSyncSummaryV1,
   ): Promise<void> {
-    const session = this.sessions.get(sessionId);
-    if (!session || session.disposed) return;
-    session.append({
-      type: "computer/sync",
-      turn: Math.max(1, this.#turn),
+    return recordComputerSyncV1(
+      this.sessions,
+      sessionId,
+      this.#turn,
       reason,
-      ...summary,
-    });
-    // The record is durable before anything reports the sync happened.
-    await session.flush();
+      summary,
+    );
   }
 }
 

package/src/backend.ts

@@ -11,6 +11,7 @@ import {
   type ComputerCommandV1,
   type ComputerProjectionV1,
 } from "./protocol.js";
+import { defineGatewayContribution } from "@frockbot/kernel-contracts/contributions";
 
 export interface ComputerGatewayHost {
   readComputer(userId: string, botId: string): Promise<ComputerProjectionV1>;
@@ -161,3 +162,16 @@ export function createComputerBackendPlugin(
 ): Plugin {
   return () => lifecycle.mount(createComputerBackendContribution(host));
 }
+
+/**
+ * The manifest's gateway `backend` entry, resolved by specifier. The
+ * application looks this descriptor up in its Contribution table; it never
+ * branches on which Package it belongs to.
+ */
+export const backendContribution = defineGatewayContribution<
+  ComputerGatewayHost,
+  ComputerBackendRouteContribution
+>({
+  specifier: "@frockbot/plugin-computer/backend",
+  create: createComputerBackendPlugin,
+});

package/src/bot.ts

@@ -49,6 +49,7 @@ import {
   isStoredComputerControlFreshV1,
   type StoredComputerControlV1,
 } from "./control-record.js";
+import { defineBotBackendContribution } from "@frockbot/kernel-contracts/contributions";
 
 export { COMPUTER_CONTROL_RECORD_KEY } from "./control-record.js";
 
@@ -1374,3 +1375,26 @@ export function createComputerBotBackendPlugin(
 ): Plugin {
   return () => lifecycle.mount(createComputerBotBackendContribution(host));
 }
+
+/**
+ * What an application hands this Contribution: the Bot's view of its User's Computer, under the
+ * Package's own key so one wide host object can satisfy every Package's slice
+ * without their fields colliding.
+ */
+export interface ComputerBotApplicationHostV1 {
+  computer: ComputerBotBackendHost;
+}
+
+/**
+ * The manifest's `bot` entry, resolved by specifier. The
+ * application looks this descriptor up in its Contribution table; it never
+ * branches on which Package it belongs to.
+ */
+export const botContribution = defineBotBackendContribution<
+  ComputerBotApplicationHostV1,
+  ComputerBotBackendContribution
+>({
+  specifier: "@frockbot/plugin-computer/bot",
+  create: (host, lifecycle) =>
+    createComputerBotBackendPlugin(host.computer, lifecycle),
+});

package/src/client/application.ts

@@ -20,6 +20,7 @@ import {
   type ComputerMachineEvent,
 } from "./state-machine.js";
 import "./styles.css";
+import { defineClientContribution } from "@frockbot/kernel-contracts/contributions";
 
 export const PROJECTION_POLL_INTERVAL_MS = 20_000;
 export const ACTIVE_PROJECTION_POLL_INTERVAL_MS = 1_500;
@@ -443,3 +444,13 @@ export function createComputerClientPlugin(
 export const computerClientPlugin = createComputerClientPlugin();
 
 export default computerClientPlugin;
+
+/**
+ * The manifest's `client` entry, resolved by specifier. The application looks
+ * this descriptor up in its Contribution table; it never branches on which
+ * Package it belongs to.
+ */
+export const clientContribution = defineClientContribution<ClientPlugin>({
+  specifier: "@frockbot/plugin-computer/client",
+  plugin: computerClientPlugin,
+});

package/src/sync.test.ts

@@ -10,6 +10,7 @@ import { describe, expect, test } from "bun:test";
 import {
   ComputerRegistry,
   computerSyncSummaryV1,
+  type ComputerHandle,
   type ComputerProvider,
   type ComputerSyncSummaryV1,
 } from "@frockbot/computer-core";
@@ -19,12 +20,13 @@ import {
   SessionStore,
   type LlmProvider,
   type SessionEvent,
+  type WorkspaceRootV1,
 } from "@frockbot/kernel-contracts";
 import { LlmRegistry } from "@frockbot/plugin-models";
 import { SystemPromptRegistry } from "@frockbot/plugin-prompt";
 import { ToolRegistry } from "@frockbot/plugin-tools";
 import { Context, type Plugin } from "cordis";
-import { createComputerAgentPlugin } from "./agent.js";
+import { createComputerAgentPlugin, syncWorkspaceRootNowV1 } from "./agent.js";
 
 const COMPOSITION = {
   generationId: "1970-01-01T00:00:00.000Z:0123456789abcdef",
@@ -253,3 +255,142 @@ describe("the Computer Package as the sync's caller", () => {
     expect(syncEvents(events)[0]?.detail).toContain("paused");
   });
 });
+
+/**
+ * The one sanctioned caller outside the Turn's own sync policy (ADR 0022
+ * decision 7). `applet build` writes `dist/` on the Computer with a shell, and
+ * an Applet publish reads those bytes from the *store*; without a push in
+ * between it would publish the previous build, or nothing.
+ */
+describe("syncWorkspaceRootNowV1", () => {
+  const appletsRoot: WorkspaceRootV1 = {
+    kind: "package-declared",
+    userId: "user-1",
+    packageId: "applets",
+    rootId: "source",
+  };
+
+  async function sessionHarness() {
+    const context = new Context();
+    await context.plugin(SessionStore, {});
+    const session = context.sessions.create("session-1");
+    return {
+      sessions: context.sessions,
+      session,
+      dispose: () => context.fiber.dispose(),
+    };
+  }
+
+  function handleWith(sync: ComputerHandle["sync"]): ComputerHandle {
+    return {
+      assignment: { providerId: "recording", generation: 1 },
+      identity: { userId: "user-1" },
+      tenant: { botId: "bot-1" },
+      ...(sync ? { sync } : {}),
+      close: () => Promise.resolve(),
+    };
+  }
+
+  test("reconciles one root and records the outcome as `publish`", async () => {
+    const calls: string[] = [];
+    const computer = handleWith({
+      reconcile: () => {
+        calls.push("reconcile");
+        return Promise.resolve(computerSyncSummaryV1("ok"));
+      },
+      reconcileRoot: (asked, reason) => {
+        calls.push(`reconcileRoot:${reason}:${asked.kind}`);
+        return Promise.resolve({ ...computerSyncSummaryV1("ok"), pushed: 1 });
+      },
+      signal: () => Promise.resolve(undefined),
+    });
+    const harness = await sessionHarness();
+
+    const summary = await syncWorkspaceRootNowV1({
+      computer,
+      sessions: harness.sessions,
+      sessionId: "session-1",
+      turn: 3,
+      root: appletsRoot,
+    });
+
+    expect(summary.status).toBe("ok");
+    // One root, never the whole Workspace: the Turn's own policy still owns
+    // `open`, `signal`, and `turn-end`, and this borrows none of them.
+    expect(calls).toEqual(["reconcileRoot:publish:package-declared"]);
+    const recorded = syncEvents([...harness.session.events]);
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0]).toMatchObject({
+      turn: 3,
+      reason: "publish",
+      status: "ok",
+      pushed: 1,
+    });
+    await harness.dispose();
+  });
+
+  test("a provider that cannot sync one root refuses, and never syncs all of them", async () => {
+    const calls: string[] = [];
+    const computer = handleWith({
+      reconcile: () => {
+        calls.push("reconcile");
+        return Promise.resolve(computerSyncSummaryV1("ok"));
+      },
+      signal: () => Promise.resolve(undefined),
+    });
+    const harness = await sessionHarness();
+
+    const summary = await syncWorkspaceRootNowV1({
+      computer,
+      sessions: harness.sessions,
+      sessionId: "session-1",
+      turn: 1,
+      root: appletsRoot,
+    });
+
+    expect(summary.status).toBe("refused");
+    expect(calls).toEqual([]);
+    expect(syncEvents([...harness.session.events])[0]?.reason).toBe("publish");
+    await harness.dispose();
+  });
+
+  test("a provider that throws is a recorded outcome, never an exception", async () => {
+    const computer = handleWith({
+      reconcile: () => Promise.resolve(computerSyncSummaryV1("ok")),
+      reconcileRoot: () =>
+        Promise.reject(new Error("the Computer is paused")) as Promise<never>,
+      signal: () => Promise.resolve(undefined),
+    });
+    const harness = await sessionHarness();
+
+    const summary = await syncWorkspaceRootNowV1({
+      computer,
+      sessions: harness.sessions,
+      sessionId: "session-1",
+      turn: 1,
+      root: appletsRoot,
+    });
+
+    expect(summary.status).toBe("unavailable");
+    expect(summary.detail).toContain("paused");
+    expect(syncEvents([...harness.session.events])).toHaveLength(1);
+    await harness.dispose();
+  });
+
+  test("a Computer with no sync records the refusal rather than nothing", async () => {
+    const computer = handleWith(undefined);
+    const harness = await sessionHarness();
+
+    const summary = await syncWorkspaceRootNowV1({
+      computer,
+      sessions: harness.sessions,
+      sessionId: "session-1",
+      turn: 1,
+      root: appletsRoot,
+    });
+
+    expect(summary.status).toBe("refused");
+    expect(syncEvents([...harness.session.events])).toHaveLength(1);
+    await harness.dispose();
+  });
+});