@frockbot/plugin-shell 0.0.0 → 0.1.0

package/src/backend-image.ts

@@ -0,0 +1,180 @@
+// The Bot Durable Object's half of the image-generation seam.
+//
+// The Image Package consumes a narrow `ImageModelV1` — one method, answering
+// raw image bytes — and knows nothing about Workers AI. This module is the
+// adapter: it takes the `AI` binding off the Durable Object's environment,
+// normalizes the three shapes a Workers AI text-to-image model answers in, and
+// hands the Package a seam with no platform vocabulary in it. "Electron,
+// Cloudflare, provider SDK, and Computer implementation types remain inside
+// their adapters."
+//
+// The binding is optional, exactly as `PACKAGE_BUNDLER` is. A deployment with
+// no Workers AI binding still mounts the Package, and `generate_image` then
+// refuses visibly on the Turn that calls it — which is a better answer than a
+// tool that silently vanishes from the catalog, and a far better one than a
+// `TypeError` inside the Agent loop.
+//
+// HIBERNATION. Nothing here reaches the Computer. The image lands in object
+// storage through `WORKSPACE_FILES`, with its generation recorded in this
+// Durable Object, so `generate_image` works with the Computer hibernated.
+import type { WorkspaceFilesV1 } from "@frockbot/kernel-contracts";
+import type { ImageRuntimeHostV1 } from "@frockbot/plugin-image/agent";
+import type {
+  ImageModelInputV1,
+  ImageModelV1,
+} from "@frockbot/plugin-image/model";
+
+/** The Bot and User a generated image is attributed to. */
+export interface BotImageIdentity {
+  userId: string;
+  botId: string;
+}
+
+/** The run, Turn and Session a generated image records as its provenance. */
+export interface BotImageTurn {
+  runId: string;
+  turnId: string;
+  sessionId: string;
+}
+
+/**
+ * The Workers AI binding, declared structurally so this module names no
+ * Cloudflare type it does not have to. `run` is the whole of what an image
+ * model needs from it.
+ */
+export interface WorkersAiBindingV1 {
+  run(model: string, input: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * The narrow slice of the Durable Object environment this module reads. Named
+ * as its own type so the binding's absence is a typed state, not a cast.
+ */
+export interface BotImageEnv {
+  AI?: WorkersAiBindingV1;
+  WORKSPACE_FILES?: WorkspaceFilesV1;
+}
+
+function decodeBase64(text: string): Uint8Array {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+async function readStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<ArrayBuffer> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  const reader = stream.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+      total += value.byteLength;
+    }
+  }
+  const joined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return joined.buffer as ArrayBuffer;
+}
+
+/**
+ * The bytes inside whatever a Workers AI text-to-image model answered.
+ *
+ * The catalog does not agree with itself: `flux-1-schnell` and the FLUX.2
+ * models answer `{ image: "<base64>" }`, the Stable Diffusion models answer a
+ * binary `ReadableStream`, and the binding may hand back an `ArrayBuffer`
+ * directly. Every one of those is an image; none of them is the Package's
+ * problem.
+ */
+export async function decodeWorkersAiImageV1(
+  answer: unknown,
+): Promise<ArrayBuffer> {
+  if (answer instanceof ArrayBuffer) return answer;
+  if (ArrayBuffer.isView(answer)) {
+    const view = answer as ArrayBufferView;
+    return view.buffer.slice(
+      view.byteOffset,
+      view.byteOffset + view.byteLength,
+    ) as ArrayBuffer;
+  }
+  if (answer instanceof ReadableStream) {
+    return await readStream(answer as ReadableStream<Uint8Array>);
+  }
+  if (answer instanceof Response) {
+    return await answer.arrayBuffer();
+  }
+  if (answer && typeof answer === "object") {
+    const image = (answer as { image?: unknown }).image;
+    if (typeof image === "string" && image.length > 0) {
+      return decodeBase64(image).buffer as ArrayBuffer;
+    }
+  }
+  throw new Error("the image model answered something that is not an image");
+}
+
+/**
+ * The Workers AI binding as an {@link ImageModelV1}.
+ *
+ * `width` and `height` are passed through: the Stable Diffusion models accept
+ * them, and the FLUX models ignore unknown fields rather than refusing. The
+ * Package never trusts them to have been honoured — it reads the dimensions
+ * back out of the bytes.
+ */
+export function createWorkersAiImageModelV1(
+  binding: WorkersAiBindingV1,
+): ImageModelV1 {
+  return {
+    async run(model: string, input: ImageModelInputV1): Promise<ArrayBuffer> {
+      const answer = await binding.run(model, {
+        prompt: input.prompt,
+        width: input.width,
+        height: input.height,
+      });
+      return await decodeWorkersAiImageV1(answer);
+    },
+  };
+}
+
+/**
+ * The image-generation seam one admitted Turn runs under, or `undefined` when
+ * the Bot's Workspace file surface is unavailable.
+ *
+ * The Workspace is the hard requirement, not the model: an image with nowhere
+ * durable to land is not a capability, while a missing model binding is a
+ * refusal the Bot can read and report. So a host with a Workspace and no `AI`
+ * still mounts the Package, with `model` absent.
+ */
+export function createBotImageHost(
+  identity: BotImageIdentity,
+  turn: BotImageTurn,
+  env: object,
+  modelId?: string,
+): ImageRuntimeHostV1 | undefined {
+  // SAFETY: the Workspace file surface is constructed onto the Durable Object
+  // environment rather than declared in the generated `Env`, because it is not
+  // a Worker binding. Absence is a supported state, not an error.
+  const bindings = env as BotImageEnv;
+  const files = bindings.WORKSPACE_FILES;
+  if (!files) return undefined;
+  return {
+    owner: { userId: identity.userId, botId: identity.botId },
+    writer: {
+      sessionId: turn.sessionId,
+      turnId: turn.turnId,
+      runId: turn.runId,
+    },
+    files,
+    ...(bindings.AI ? { model: createWorkersAiImageModelV1(bindings.AI) } : {}),
+    ...(modelId ? { modelId } : {}),
+  };
+}

package/src/backend-isolate.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  LlmStreamEvent,
+  NormalizedModelRequest,
+} from "@frockbot/kernel-contracts";
+import {
+  createIsolateCapabilityHost,
+  isolateModelEventStreamV1,
+  ISOLATE_MODEL_FAILURE_MESSAGE,
+  ISOLATE_MODEL_REQUEST_PREFIX,
+  matchingModelAssignmentV1,
+  type IsolateAssignmentV1,
+  type IsolateModelBindingV1,
+  type IsolateModelRequestRecordV1,
+} from "./backend-isolate.ts";
+
+const ASSIGNMENT: IsolateAssignmentV1 = {
+  assignmentId: "model-assignment",
+  packageId: "provider-ollama-cloud",
+  capabilityId: "ollama-cloud-models",
+  kind: "model",
+  connectionId: "connection-1",
+  providerModelId: "glm-5.3-flash:cloud",
+};
+
+const BINDING: IsolateModelBindingV1 = {
+  assignmentId: "model-assignment",
+  packageId: "provider-ollama-cloud",
+  capabilityId: "ollama-cloud-models",
+  connectionId: "connection-1",
+  provider: "ollama-cloud",
+  providerModelId: "glm-5.3-flash:cloud",
+  connectionGeneration: "generation-1",
+};
+
+function request(
+  overrides: Partial<NormalizedModelRequest> = {},
+): NormalizedModelRequest {
+  return {
+    requestId: "request-1",
+    provider: "ollama-cloud",
+    model: "glm-5.3-flash:cloud",
+    system: "",
+    messages: [{ role: "user", content: "hello" }],
+    tools: [],
+    ...overrides,
+  };
+}
+
+function memoryStorage() {
+  const values = new Map<string, unknown>();
+  return {
+    values,
+    put: (key: string, value: unknown) => {
+      values.set(key, structuredClone(value));
+      return Promise.resolve();
+    },
+    get: <T>(key: string) => Promise.resolve(values.get(key) as T | undefined),
+    list: <T>(options: { prefix: string }) =>
+      Promise.resolve(
+        new Map(
+          [...values.entries()].filter(([key]) =>
+            key.startsWith(options.prefix),
+          ) as [string, T][],
+        ),
+      ),
+  };
+}
+
+function host(
+  options: {
+    binding?: IsolateModelBindingV1;
+    stream?: (request: NormalizedModelRequest) => AsyncIterable<LlmStreamEvent>;
+  } = {},
+) {
+  const storage = memoryStorage();
+  const forwarded: NormalizedModelRequest[] = [];
+  let minted = 0;
+  const binding = options.binding ?? BINDING;
+  return {
+    storage,
+    forwarded,
+    host: createIsolateCapabilityHost({
+      storage,
+      botId: "bot-1",
+      packageId: "bot-authored",
+      generationId: "generation-1",
+      assignments: [ASSIGNMENT],
+      modelBinding: binding,
+      modelPath: {
+        stream: (value) => {
+          forwarded.push(structuredClone(value));
+          return (
+            options.stream?.(value) ??
+            (async function* () {
+              yield { type: "text-delta", text: "hi" } as LlmStreamEvent;
+            })()
+          );
+        },
+      },
+      newId: () => `minted-${(minted += 1)}`,
+      now: () => new Date("2026-08-31T00:00:00.000Z"),
+    }),
+  };
+}
+
+describe("an isolate model request is bound to its Assignment", () => {
+  test("matches only the exact assigned provider and model", () => {
+    expect(
+      matchingModelAssignmentV1([ASSIGNMENT], BINDING, request()),
+    ).toMatchObject({ assignmentId: "model-assignment" });
+    expect(
+      matchingModelAssignmentV1(
+        [ASSIGNMENT],
+        BINDING,
+        request({ provider: "foundation" }),
+      ),
+    ).toBeUndefined();
+    expect(
+      matchingModelAssignmentV1(
+        [ASSIGNMENT],
+        BINDING,
+        request({ model: "some-other-model" }),
+      ),
+    ).toBeUndefined();
+    // No durable binding at all: an enabled Assignment on its own authorizes
+    // nothing.
+    expect(
+      matchingModelAssignmentV1([ASSIGNMENT], undefined, request()),
+    ).toBeUndefined();
+  });
+
+  test("ignores a Bot-supplied model binding", () => {
+    expect(
+      matchingModelAssignmentV1(
+        [ASSIGNMENT],
+        BINDING,
+        request({
+          provider: "foundation",
+          model: "deterministic-v1",
+          modelBinding: { connectionId: "connection-1" },
+        }),
+      ),
+    ).toBeUndefined();
+  });
+
+  test("a request for an unassigned provider is a pending decision", async () => {
+    const subject = host();
+    const outcome = await subject.host.invokeModel(
+      request({ provider: "foundation", model: "deterministic-v1" }),
+    );
+
+    expect(outcome).toMatchObject({ status: "pending-user-decision" });
+    expect(await subject.host.recordedModelRequests()).toHaveLength(0);
+    expect(subject.forwarded).toHaveLength(0);
+  });
+
+  test("forwards the authority's binding, never the Bot's", async () => {
+    const subject = host();
+    await subject.host.invokeModel(
+      request({
+        modelBinding: {
+          connectionId: "another-users-connection",
+          connectionGeneration: "forged",
+        },
+      }),
+    );
+
+    expect(subject.forwarded[0]?.modelBinding).toEqual({
+      connectionId: "connection-1",
+      connectionGeneration: "generation-1",
+    });
+  });
+});
+
+describe("the isolate model request record", () => {
+  test("two invocations reusing one Bot request id produce two records", async () => {
+    const subject = host();
+
+    await subject.host.invokeModel(request());
+    await subject.host.invokeModel(request());
+
+    const recorded = await subject.host.recordedModelRequests();
+    expect(recorded).toHaveLength(2);
+    expect(recorded.map((entry) => entry.requestId)).toEqual([
+      "request-1",
+      "request-1",
+    ]);
+    expect(new Set(recorded.map((entry) => entry.recordId)).size).toBe(2);
+    expect(
+      [...subject.storage.values.keys()].filter((key) =>
+        key.startsWith(ISOLATE_MODEL_REQUEST_PREFIX),
+      ),
+    ).toHaveLength(2);
+  });
+
+  test("refuses an unbounded Bot request id", async () => {
+    const subject = host();
+    await expect(
+      subject.host.invokeModel(request({ requestId: "r".repeat(257) })),
+    ).rejects.toThrow("requestId is not bounded");
+  });
+
+  test("records the request that was forwarded", async () => {
+    const subject = host();
+    await subject.host.invokeModel(request());
+    const recorded = (await subject.host.recordedModelRequests())[0] as
+      IsolateModelRequestRecordV1 | undefined;
+    expect(recorded?.request.modelBinding).toEqual({
+      connectionId: "connection-1",
+      connectionGeneration: "generation-1",
+    });
+    expect(recorded?.capabilityId).toBe("ollama-cloud-models");
+  });
+});
+
+describe("provider errors crossing into Bot code", () => {
+  test("are normalized before the isolate can read them", async () => {
+    const stream = isolateModelEventStreamV1(
+      (async function* (): AsyncIterable<LlmStreamEvent> {
+        yield { type: "text-delta", text: "partial" };
+        throw new Error(
+          "ollama.com refused key sk-live-123 for account acct-9",
+        );
+      })(),
+    );
+    const reader = stream.getReader();
+    await reader.read();
+
+    const failure = await reader.read().then(
+      () => undefined,
+      (error: unknown) => (error instanceof Error ? error.message : ""),
+    );
+    expect(failure).toBe(ISOLATE_MODEL_FAILURE_MESSAGE);
+    expect(failure).not.toContain("sk-live-123");
+    expect(failure).not.toContain("ollama.com");
+  });
+});