@frockbot/plugin-fly-sprite 0.2.4 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-fly-sprite",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -25,16 +25,16 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/computer-core": "0.2.4",
-    "@frockbot/computer-host-protocol": "0.2.4",
-    "@frockbot/computer-host-runtime": "0.2.4",
-    "@frockbot/kernel-contracts": "0.2.4",
-    "@frockbot/plugin-computer": "0.2.4",
+    "@frockbot/computer-core": "0.3.0",
+    "@frockbot/computer-host-protocol": "0.3.0",
+    "@frockbot/computer-host-runtime": "0.3.0",
+    "@frockbot/kernel-contracts": "0.3.0",
+    "@frockbot/plugin-computer": "0.3.0",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {
-    "@frockbot/plugin-testkit": "0.2.4",
-    "@frockbot/workspace-store": "0.2.4",
+    "@frockbot/plugin-testkit": "0.3.0",
+    "@frockbot/workspace-store": "0.3.0",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "typescript": "5.9.3"

package/src/computer.test.ts

@@ -1,6 +1,7 @@
 /// <reference types="bun" />
 
 import { describe, expect, test } from "bun:test";
+import type { ComputerConnectionProgressV1 } from "@frockbot/computer-core";
 import { verifyPluginPackage } from "@frockbot/plugin-testkit";
 import { DESKTOP_GUI_LEASE_KEY } from "@frockbot/computer-host-runtime";
 import manifest from "../frockbot.json" with { type: "json" };
@@ -251,6 +252,67 @@ describe("Fly Sprite computer", () => {
     ]);
   });
 
+  test("projects streamed provisioning under waking without regressing", async () => {
+    const host = fakeHost();
+    const phase = {
+      kind: "provision" as const,
+      total: 5,
+      status: "running" as const,
+      resumed: false,
+    };
+    host.openProgress.push(
+      {
+        ...phase,
+        phase: "packages",
+        label: "installing the desktop packages",
+        index: 2,
+      },
+      {
+        ...phase,
+        phase: "layout",
+        label: "preparing the Computer layout",
+        index: 1,
+      },
+      {
+        ...phase,
+        phase: "browser",
+        label: "installing the browser",
+        index: 4,
+      },
+    );
+    const provider = new FlySpriteComputerProvider(attach(host));
+    const computer = await provider.open(
+      { userId: "owner" },
+      { botId: "general" },
+      { providerId: "fly-sprite", generation: 1 },
+    );
+    const progress: ComputerConnectionProgressV1[] = [];
+
+    await computer.presence?.connect({
+      onProgress: (step) => {
+        progress.push(step);
+      },
+    });
+
+    expect(progress.map((step) => step.index)).toEqual([1, 1, 2, 3, 4, 5]);
+    expect(
+      progress.flatMap((step) =>
+        step.provisioning ? [step.provisioning.index] : [],
+      ),
+    ).toEqual([2, 4]);
+    expect(progress[0]).toMatchObject({
+      kind: "connect",
+      step: "waking",
+      label: "Waking the Computer",
+      provisioning: {
+        version: 1,
+        kind: "provision",
+        label: "installing the desktop packages",
+        resumed: false,
+      },
+    });
+  });
+
   test("an unconfigured Computer refuses rather than pretending", async () => {
     const computer = new FlySpriteComputer({ spriteName: "frockbot-test" });
     expect(computer.configured).toBe(false);

package/src/computer.ts

@@ -40,6 +40,7 @@ import type {
   ComputerHostCallOptions,
   ComputerHostExecCommandV1,
   ComputerHostExecOutcomeV1,
+  ComputerHostOpenOptionsV1,
 } from "./host-client.js";
 
 // The Computer's on-Sprite layout, its provisioning script, and its declared
@@ -85,7 +86,7 @@ const TIMEOUTS = {
  * tenant means on a Computer.
  */
 export interface ComputerHostSurfaceV1 {
-  open(options?: ComputerHostCallOptions): Promise<ComputerHostOpenResultV1>;
+  open(options?: ComputerHostOpenOptionsV1): Promise<ComputerHostOpenResultV1>;
   exec(
     command: ComputerHostExecCommandV1,
     options?: ComputerHostCallOptions,
@@ -1214,12 +1215,49 @@ export class FlySpriteComputer {
     const signal = options?.signal;
     const effectId = options?.effectId;
     const host = this.hostFor(layout);
+    let lastIndex = 0;
+    let lastProvisioningIndex = -1;
+    const report = async (
+      progress: Parameters<
+        NonNullable<ComputerConnectionOptionsV1["onProgress"]>
+      >[0],
+    ): Promise<void> => {
+      if (progress.index < lastIndex) return;
+      if (
+        progress.provisioning &&
+        progress.provisioning.index < lastProvisioningIndex
+      ) {
+        return;
+      }
+      lastIndex = progress.index;
+      if (progress.provisioning) {
+        lastProvisioningIndex = progress.provisioning.index;
+      }
+      await options?.onProgress?.(progress);
+    };
     let opened: ComputerHostOpenResultV1;
     try {
       opened = await host.open({
         signal,
         timeoutMs: TIMEOUTS.open,
         ...(effectId ? { effectId: `${effectId}:open` } : {}),
+        onProgress: (progress) =>
+          report({
+            version: 1,
+            kind: "connect",
+            step: "waking",
+            label: "Waking the Computer",
+            index: 1,
+            total: 5,
+            provisioning: {
+              version: 1,
+              kind: progress.kind,
+              label: progress.label,
+              index: progress.index,
+              total: progress.total,
+              resumed: progress.resumed,
+            },
+          }),
       });
     } catch (error) {
       // Every display belonging to a tenant this Computer still has open is a
@@ -1243,7 +1281,7 @@ export class FlySpriteComputer {
       opened.provisioning?.kind === "update" &&
       opened.provisioning.status === "running";
     if (updating && opened.provisioning) {
-      await options?.onProgress?.({
+      await report({
         version: 1,
         kind: "update",
         step: opened.provisioning.phase,
@@ -1255,7 +1293,7 @@ export class FlySpriteComputer {
       // `host.open` owns the wake, tenant attachment and declared desktop
       // start. Keep the durable wake step active while that long call is in
       // flight, then record both boundaries before moving to viewer minting.
-      await options?.onProgress?.({
+      await report({
         version: 1,
         kind: "connect",
         step: "attaching",
@@ -1263,7 +1301,7 @@ export class FlySpriteComputer {
         index: 2,
         total: 5,
       });
-      await options?.onProgress?.({
+      await report({
         version: 1,
         kind: "connect",
         step: "starting-desktop",
@@ -1281,7 +1319,7 @@ export class FlySpriteComputer {
       );
     }
     if (!updating) {
-      await options?.onProgress?.({
+      await report({
         version: 1,
         kind: "connect",
         step: "minting-viewer",
@@ -1303,7 +1341,7 @@ export class FlySpriteComputer {
       );
     }
     if (!updating) {
-      await options?.onProgress?.({
+      await report({
         version: 1,
         kind: "connect",
         step: "connecting",

package/src/host-client.test.ts

@@ -6,7 +6,10 @@ import {
   COMPUTER_HOST_TOKEN_HEADER,
   computerHostProblemV1,
   encodeComputerHostExecFrameV1,
+  encodeComputerHostOpenFrameV1,
   type ComputerHostExecFrameV1,
+  type ComputerHostOpenFrameV1,
+  type ComputerHostProvisioningV1,
 } from "@frockbot/computer-host-protocol";
 import {
   ComputerHostClient,
@@ -96,6 +99,29 @@ function ndjson(
   );
 }
 
+function openNdjson(
+  frames: readonly ComputerHostOpenFrameV1[],
+  size: number,
+): Response {
+  const bytes = new TextEncoder().encode(
+    frames.map(encodeComputerHostOpenFrameV1).join(""),
+  );
+  let offset = 0;
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      pull(controller) {
+        if (offset >= bytes.byteLength) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(bytes.subarray(offset, offset + size));
+        offset += size;
+      },
+    }),
+    { headers: { "content-type": COMPUTER_HOST_STREAM_MEDIA_TYPE } },
+  );
+}
+
 function client(
   fetcher: ComputerHostFetcherV1,
   overrides: Partial<ConstructorParameters<typeof ComputerHostClient>[0]> = {},
@@ -185,6 +211,119 @@ describe("ComputerHostClient envelope", () => {
   });
 });
 
+describe("ComputerHostClient open", () => {
+  const starting: ComputerHostProvisioningV1 = {
+    kind: "provision",
+    phase: "starting",
+    label: "starting the Computer provisioner",
+    index: 0,
+    total: 5,
+    status: "running",
+    resumed: false,
+  };
+  const installing: ComputerHostProvisioningV1 = {
+    ...starting,
+    phase: "desktop",
+    label: "installing the desktop packages",
+    index: 2,
+  };
+
+  test("streams provisioning progress before the terminal open result", async () => {
+    const result = {
+      version: 1 as const,
+      effectId: "effect-1",
+      spriteName: "frockbot-abc",
+      directory: "/home/box/agent-data/agents/bot-1",
+      generation: 1,
+      provisioning: {
+        ...installing,
+        phase: "ready",
+        label: "the Computer is ready",
+        status: "complete" as const,
+        index: 5,
+      },
+    };
+    const { fetcher, calls } = recorder(() =>
+      openNdjson(
+        [
+          { type: "progress", progress: starting },
+          { type: "progress", progress: installing },
+          { type: "result", result },
+        ],
+        3,
+      ),
+    );
+    const seen: ComputerHostProvisioningV1[] = [];
+
+    const opened = await client(fetcher).open({
+      onProgress: (progress: ComputerHostProvisioningV1) => {
+        seen.push(progress);
+      },
+    });
+
+    expect(calls[0]?.body.stream).toBe(true);
+    expect(seen).toEqual([starting, installing]);
+    expect(opened).toEqual(result);
+  });
+
+  test("an older host that rejects `stream` is asked again without it", async () => {
+    const result = {
+      version: 1 as const,
+      effectId: "effect-1",
+      spriteName: "frockbot-abc",
+      directory: "/home/box/agent-data/agents/bot-1",
+      generation: 1,
+    };
+    // Staging binds to the production Computer host, so an app Worker on main
+    // meets a host that no version tag has moved yet. The host refuses while
+    // decoding, before it touches a Sprite, so asking again without progress
+    // starts no second effect.
+    let attempt = 0;
+    const { fetcher, calls } = recorder(() => {
+      attempt += 1;
+      return attempt === 1
+        ? new Response(
+            JSON.stringify({
+              version: 1,
+              code: "invalid-request",
+              message: "Computer host request has an unknown field: stream",
+              retryable: false,
+            }),
+            { status: 400, headers: { "content-type": "application/json" } },
+          )
+        : new Response(JSON.stringify(result), {
+            headers: { "content-type": "application/json" },
+          });
+    });
+    const seen: ComputerHostProvisioningV1[] = [];
+
+    const opened = await client(fetcher).open({
+      onProgress: (progress: ComputerHostProvisioningV1) => {
+        seen.push(progress);
+      },
+    });
+
+    expect(calls[0]?.body.stream).toBe(true);
+    expect(calls[1]?.body.stream).toBeUndefined();
+    expect(calls).toHaveLength(2);
+    expect(seen).toEqual([]);
+    expect(opened).toEqual(result);
+  });
+
+  test("a stream that ends before its result is unavailable and retryable", async () => {
+    const { fetcher } = recorder(() =>
+      openNdjson([{ type: "progress", progress: starting }], 5),
+    );
+    const error = await client(fetcher)
+      .open({ onProgress: () => undefined })
+      .catch((thrown: unknown) => thrown);
+
+    expect(error).toBeInstanceOf(ComputerError);
+    expect((error as ComputerError).code).toBe("provider-unavailable");
+    expect((error as ComputerError).retryable).toBe(true);
+  });
+});
+
 describe("ComputerHostClient exec", () => {
   test("ships the script in the body and never on an argv", async () => {
     const script = "echo hello\n".repeat(400);

package/src/host-client.ts

@@ -20,10 +20,10 @@
  * Two behaviours are load-bearing and are the reason this is a class rather
  * than a function:
  *
- * - **Framing.** A streamed exec answers NDJSON, and a transport chunk
+ * - **Framing.** Streamed open and exec answer NDJSON, and a transport chunk
  *   boundary means nothing: a frame may be split across two chunks or three
- *   frames may arrive in one. `ComputerHostExecFrameReaderV1` finds the
- *   newline; this client never reads a chunk as a frame.
+ *   frames may arrive in one. Their frame readers find the newline; this
+ *   client never reads a chunk as a frame.
  * - **Cancellation.** "Connections to the Computer are expected to drop on
  *   every pause." A caller's abort aborts the fetch *and* posts a `cancel` for
  *   the same `effectId`, because a dropped connection alone leaves the process
@@ -37,6 +37,7 @@ import {
   COMPUTER_HOST_ROUTES,
   COMPUTER_HOST_TOKEN_HEADER,
   ComputerHostExecFrameReaderV1,
+  ComputerHostOpenFrameReaderV1,
   decodeComputerHostCancelResultV1,
   decodeComputerHostControlResultV1,
   decodeComputerHostExecResultV1,
@@ -63,6 +64,7 @@ import {
   type ComputerHostOpenResultV1,
   type ComputerHostOperationKindV1,
   type ComputerHostOperationV1,
+  type ComputerHostProvisioningV1,
   type ComputerHostServiceResultV1,
   type ComputerHostViewerResultV1,
 } from "@frockbot/computer-host-protocol";
@@ -129,6 +131,14 @@ export interface ComputerHostCallOptions {
   timeoutMs?: number;
 }
 
+export interface ComputerHostOpenOptionsV1 extends ComputerHostCallOptions {
+  /**
+   * Receives each provisioning phase while `open` remains in flight. Its
+   * presence selects the NDJSON response; without it `open` stays buffered.
+   */
+  onProgress?(progress: ComputerHostProvisioningV1): void | Promise<void>;
+}
+
 export interface ComputerHostExecCommandV1 {
   /** Shell source delivered on the command's stdin. Never on its argv. */
   script: string;
@@ -323,8 +333,57 @@ export class ComputerHostClient {
     });
   }
 
-  open(options?: ComputerHostCallOptions): Promise<ComputerHostOpenResultV1> {
-    return this.json({ kind: "open" }, decodeComputerHostOpenResultV1, options);
+  async open(
+    options?: ComputerHostOpenOptionsV1,
+  ): Promise<ComputerHostOpenResultV1> {
+    if (!options?.onProgress) {
+      return this.json(
+        { kind: "open" },
+        decodeComputerHostOpenResultV1,
+        options,
+      );
+    }
+    const effectId = this.effectIdFor(options);
+    const lease = this.lease(COMPUTER_HOST_DEFAULT_TIMEOUT_MS, options);
+    try {
+      const response = await this.send(
+        { kind: "open", stream: true },
+        effectId,
+        lease,
+      );
+      return await this.readOpenStream(
+        response,
+        lease,
+        effectId,
+        options.onProgress,
+      );
+    } catch (error) {
+      // A host that predates streamed `open` rejects the request while
+      // decoding it — "unknown field: stream" — and the decode is the first
+      // thing it does, before it touches a Sprite. So this exact refusal is
+      // the one failure here that provably started no work, and asking again
+      // without progress is a second first attempt rather than a retry of an
+      // admitted effect.
+      //
+      // The skew is real and expected: `apps/cloudflare/wrangler.jsonc` binds
+      // staging to the *production* Computer host, so every merge to main
+      // meets a host that a version tag has not yet moved. Losing the progress
+      // report is the correct price; failing every Computer open until the tag
+      // lands is not.
+      if (
+        !(error instanceof ComputerError) ||
+        error.code !== ERROR_CODES["invalid-request"]
+      ) {
+        throw error;
+      }
+      return await this.json(
+        { kind: "open" },
+        decodeComputerHostOpenResultV1,
+        options,
+      );
+    } finally {
+      lease.release();
+    }
   }
 
   /**
@@ -616,6 +675,83 @@ export class ComputerHostClient {
     }
   }
 
+  /**
+   * Reads an NDJSON open stream to its terminal result.
+   *
+   * The body is drained even after a progress callback fails, because the
+   * result is what makes the already-admitted open's outcome known. An EOF
+   * without that result is the shape of a container restart and is therefore
+   * retryable unavailability, exactly as it is for streamed exec.
+   */
+  private async readOpenStream(
+    response: Response,
+    lease: CallLease,
+    effectId: string,
+    onProgress: (progress: ComputerHostProvisioningV1) => void | Promise<void>,
+  ): Promise<ComputerHostOpenResultV1> {
+    if (!response.body) {
+      throw new ComputerError(
+        "provider-failure",
+        "The Computer host answered an open stream with no body",
+      );
+    }
+    const reader = response.body.getReader();
+    const frames = new ComputerHostOpenFrameReaderV1();
+    let result: ComputerHostOpenResultV1 | undefined;
+    let failure: ComputerError | undefined;
+    let callbackFailed = false;
+    let callbackFailure: unknown;
+
+    const consume = async (
+      batch: ReturnType<ComputerHostOpenFrameReaderV1["push"]>,
+    ): Promise<void> => {
+      for (const frame of batch) {
+        if (frame.type === "progress") {
+          if (!callbackFailed) {
+            try {
+              await onProgress(frame.progress);
+            } catch (error) {
+              callbackFailed = true;
+              callbackFailure = error;
+            }
+          }
+        } else if (frame.type === "result") {
+          result = frame.result;
+        } else {
+          failure ??= new ComputerError(
+            ERROR_CODES[frame.code],
+            frame.message,
+            frame.retryable,
+          );
+        }
+      }
+    };
+
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) await consume(frames.push(value));
+      }
+      await consume(frames.end());
+    } catch (error) {
+      throw this.refuse(error, lease, effectId, true);
+    } finally {
+      reader.releaseLock();
+    }
+
+    if (callbackFailed) throw callbackFailure;
+    if (failure) throw failure;
+    if (!result) {
+      throw new ComputerError(
+        "provider-unavailable",
+        "The Computer host open stream ended before the Computer opened",
+        true,
+      );
+    }
+    return result;
+  }
+
   /**
    * Reads an NDJSON exec stream to its end.
    *

package/src/host-double.ts

@@ -33,6 +33,7 @@ import type {
   ComputerHostCallOptions,
   ComputerHostExecCommandV1,
   ComputerHostExecOutcomeV1,
+  ComputerHostOpenOptionsV1,
 } from "./host-client.ts";
 
 /** What a suite's runner says one script did. */
@@ -84,6 +85,7 @@ export class FakeComputerHost {
   display: string | undefined = ":100";
   generation = 1;
   provisioning?: ComputerHostProvisioningV1;
+  readonly openProgress: 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. */
@@ -110,12 +112,15 @@ export class FakeComputerHost {
     const host = this;
     const botKey = computerBotKey(botId);
     return {
-      open(
-        options?: ComputerHostCallOptions,
+      async open(
+        options?: ComputerHostOpenOptionsV1,
       ): Promise<ComputerHostOpenResultV1> {
         options?.signal?.throwIfAborted();
-        if (host.openFailure) return Promise.reject(host.openFailure);
-        return Promise.resolve({
+        if (host.openFailure) throw host.openFailure;
+        for (const progress of host.openProgress) {
+          await options?.onProgress?.(progress);
+        }
+        return {
           version: 1,
           effectId: options?.effectId ?? "effect-open",
           spriteName: host.spriteName,
@@ -123,7 +128,7 @@ export class FakeComputerHost {
           ...(host.display ? { display: host.display } : {}),
           generation: host.generation,
           ...(host.provisioning ? { provisioning: host.provisioning } : {}),
-        });
+        };
       },
 
       async exec(