@frockbot/plugin-image 0.0.0 → 0.1.1

package/src/bytes.ts

@@ -0,0 +1,125 @@
+// What the bytes an image model returned actually are.
+//
+// The tool records `mimeType`, `width` and `height` in its durable
+// `tool/result`, and those must describe the stored object rather than the
+// request: Workers AI's `flux-1-schnell` accepts no size at all, so echoing
+// the requested width back would put a number in the durable log that no file
+// on disk agrees with. Reading the container header is the only honest source.
+//
+// Pure, total, and the Package's whole image-format surface. A byte string
+// this cannot identify is not written: an unidentifiable blob under a durable
+// root is data nothing can render and nothing can attribute a format to.
+
+/** A decoded image container. */
+export interface ImageDimensionsV1 {
+  mimeType: string;
+  width: number;
+  height: number;
+}
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const;
+
+function readUint32BE(bytes: Uint8Array, offset: number): number {
+  return (
+    ((bytes[offset] ?? 0) << 24) +
+    ((bytes[offset + 1] ?? 0) << 16) +
+    ((bytes[offset + 2] ?? 0) << 8) +
+    (bytes[offset + 3] ?? 0)
+  );
+}
+
+function readUint16BE(bytes: Uint8Array, offset: number): number {
+  return ((bytes[offset] ?? 0) << 8) + (bytes[offset + 1] ?? 0);
+}
+
+function decodePng(bytes: Uint8Array): ImageDimensionsV1 | undefined {
+  if (bytes.byteLength < 24) return undefined;
+  if (PNG_SIGNATURE.some((byte, index) => bytes[index] !== byte)) {
+    return undefined;
+  }
+  // The first chunk of a PNG is always IHDR, and its payload starts at 16.
+  if (
+    bytes[12] !== 0x49 ||
+    bytes[13] !== 0x48 ||
+    bytes[14] !== 0x44 ||
+    bytes[15] !== 0x52
+  ) {
+    return undefined;
+  }
+  const width = readUint32BE(bytes, 16);
+  const height = readUint32BE(bytes, 20);
+  if (width < 1 || height < 1) return undefined;
+  return { mimeType: "image/png", width, height };
+}
+
+/** SOF markers carrying a frame header. SOF4/8/12 are not frame starts. */
+function isStartOfFrame(marker: number): boolean {
+  return (
+    marker >= 0xc0 &&
+    marker <= 0xcf &&
+    marker !== 0xc4 &&
+    marker !== 0xc8 &&
+    marker !== 0xcc
+  );
+}
+
+function decodeJpeg(bytes: Uint8Array): ImageDimensionsV1 | undefined {
+  if (bytes.byteLength < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) {
+    return undefined;
+  }
+  let offset = 2;
+  while (offset + 3 < bytes.byteLength) {
+    if (bytes[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    const marker = bytes[offset + 1] ?? 0;
+    // Padding fill bytes, and the standalone markers that carry no length.
+    if (marker === 0xff) {
+      offset += 1;
+      continue;
+    }
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {
+      offset += 2;
+      continue;
+    }
+    const length = readUint16BE(bytes, offset + 2);
+    if (length < 2) return undefined;
+    if (isStartOfFrame(marker)) {
+      if (offset + 9 >= bytes.byteLength) return undefined;
+      const height = readUint16BE(bytes, offset + 5);
+      const width = readUint16BE(bytes, offset + 7);
+      if (width < 1 || height < 1) return undefined;
+      return { mimeType: "image/jpeg", width, height };
+    }
+    offset += 2 + length;
+  }
+  return undefined;
+}
+
+/**
+ * The container these bytes are, or `undefined` when they are neither a PNG
+ * nor a JPEG. Those two are what every Workers AI text-to-image model returns
+ * today; anything else is refused rather than guessed at.
+ */
+export function decodeImageDimensionsV1(
+  bytes: Uint8Array,
+): ImageDimensionsV1 | undefined {
+  return decodePng(bytes) ?? decodeJpeg(bytes);
+}
+
+/** The sha-256 content address of some bytes, hex encoded. */
+export async function sha256HexV1(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    bytes.slice().buffer as ArrayBuffer,
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** The sha-256 of a string, for the prompt hash the intent event records. */
+export function sha256HexOfTextV1(text: string): Promise<string> {
+  return sha256HexV1(new TextEncoder().encode(text));
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./agent.js";
+export * from "./bytes.js";
+export { default as imageManifest } from "./manifest.js";
+export * from "./model.js";
+export * from "./root.js";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;

package/src/model.ts

@@ -0,0 +1,63 @@
+// The narrow image-model interface this Package consumes, and the models it
+// knows how to ask for.
+//
+// "The kernel declares the narrow interfaces it consumes ... and owns no
+// implementation of them." The same discipline applies one level down: this
+// Package declares what it needs from an image model and implements none of
+// it. The host — `apps/cloudflare` through `plugin-shell` — adapts Workers AI's
+// `AI` binding to this shape, so no Cloudflare type and no provider response
+// envelope reaches the tool.
+//
+// `run` answers raw image bytes, never base64 and never a provider envelope.
+// Workers AI's text-to-image models disagree about which they return
+// (`flux-1-schnell` answers `{ image: "<base64>" }`, the Stable Diffusion
+// models answer a binary stream), and normalizing that is exactly the
+// adapter's job.
+
+/** The image model seam. One method, one direction, no provider vocabulary. */
+export interface ImageModelV1 {
+  run(model: string, input: ImageModelInputV1): Promise<ArrayBuffer>;
+}
+
+/**
+ * What the tool asks for. `width` and `height` are a *request*: not every
+ * Workers AI text-to-image model accepts them (`flux-1-schnell` does not), so
+ * the tool reports the dimensions it decodes from the returned bytes rather
+ * than echoing these back as if they were honoured.
+ */
+export interface ImageModelInputV1 {
+  prompt: string;
+  width: number;
+  height: number;
+}
+
+/**
+ * The default model. Cloudflare's own catalog calls FLUX.1 [schnell] the
+ * fastest text-to-image model on Workers AI, and it is the one the parity
+ * slice was specified against (`docs/plans/` slice O, §2). Overridable through
+ * the `image.model` Package setting.
+ */
+export const DEFAULT_IMAGE_MODEL_V1 = "@cf/black-forest-labs/flux-1-schnell";
+
+/**
+ * The models the `image.model` setting accepts, mirroring the manifest's
+ * `enum`. A model outside this list is refused rather than passed through: the
+ * host binding would happily run an image-to-image or a text model and answer
+ * something this tool cannot store.
+ */
+export const IMAGE_MODELS_V1: readonly string[] = [
+  "@cf/black-forest-labs/flux-1-schnell",
+  "@cf/black-forest-labs/flux-2-klein-4b",
+  "@cf/stabilityai/stable-diffusion-xl-base-1.0",
+  "@cf/bytedance/stable-diffusion-xl-lightning",
+];
+
+/** The setting's value, or the default; an unknown model is refused. */
+export function resolveImageModelV1(configured?: string): string {
+  const named = configured?.trim();
+  if (!named) return DEFAULT_IMAGE_MODEL_V1;
+  if (!IMAGE_MODELS_V1.includes(named)) {
+    throw new Error(`image model "${named}" is not one this Package offers`);
+  }
+  return named;
+}

package/src/root.ts

@@ -0,0 +1,84 @@
+// Where a generated image lives, and why there.
+//
+// The durable Workspace, under a root this Package's manifest declares:
+// `{kind: "package-declared", userId, packageId: "image", rootId: "generated"}`
+// (`kernel-contracts/src/workspace.ts`). Object storage backs it, every write
+// records its writer and produces a generation, and the durable-root sync
+// (ADR 0013) presents it on the Computer as a real file the Bot can open with
+// ordinary file tools — none of which is true of a data URL in the event log,
+// the Durable Object's own storage, or a Memory root (single-writer,
+// Markdown-only, and never written through the kernel file surface).
+//
+// `package-declared` roots are User-scoped, so one User's Bots share the root
+// and each Bot's images sit under its own directory. That is the constitution's
+// own rule for a Computer: "Bots of one User may read each other's Workspace
+// files"; separation between them is organizational.
+//
+// The object is named by the *effect*, not by the prompt or a random id. That
+// is the reconciliation fence: an interrupted Turn asks the Workspace whether
+// the object for its effect exists, and the answer settles the effect without
+// running — and therefore without billing — the model a second time.
+import {
+  normalizeWorkspaceRelativePathV1,
+  type WorkspacePathV1,
+  type WorkspaceRootV1,
+} from "@frockbot/kernel-contracts";
+
+/** The Package id the declared root belongs to. Matches `frockbot.json`. */
+export const IMAGE_PACKAGE_ID_V1 = "image";
+/** The declared root generated images are written under. */
+export const IMAGE_GENERATED_ROOT_ID_V1 = "generated";
+
+/** The Bot and User a generated image is attributed to. */
+export interface ImageOwnerV1 {
+  userId: string;
+  botId: string;
+}
+
+/** The Package-declared Workspace root this Package writes. */
+export function generatedImageRootV1(userId: string): WorkspaceRootV1 {
+  return {
+    kind: "package-declared",
+    userId,
+    packageId: IMAGE_PACKAGE_ID_V1,
+    rootId: IMAGE_GENERATED_ROOT_ID_V1,
+  };
+}
+
+/**
+ * One path segment made safe. An `effectId` is minted by the Agent loop as
+ * `tool:<turn>:<step>:<index>`; a Bot id is arbitrary durable text. Neither is
+ * a filename, so both are folded to a conservative alphabet rather than
+ * trusted — the Workspace would accept a colon, but a Computer's filesystem is
+ * where these land and there is no reason to find out which ones it dislikes.
+ */
+export function imagePathSegmentV1(value: string): string {
+  const folded = value
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!folded) throw new Error("image path segment is empty");
+  return folded.slice(0, 128);
+}
+
+/**
+ * The object one effect writes. Effect-keyed, so reconciliation reads exactly
+ * the object the interrupted attempt would have written.
+ */
+export function generatedImagePathV1(
+  owner: ImageOwnerV1,
+  effectId: string,
+  extension: string,
+): WorkspacePathV1 {
+  return {
+    root: generatedImageRootV1(owner.userId),
+    path: normalizeWorkspaceRelativePathV1(
+      `${imagePathSegmentV1(owner.botId)}/${imagePathSegmentV1(effectId)}.${imagePathSegmentV1(extension)}`,
+      "generated image path",
+    ),
+  };
+}
+
+/** The file extension for a container this Package writes. */
+export function imageExtensionV1(mimeType: string): string {
+  return mimeType === "image/jpeg" ? "jpg" : "png";
+}

package/src/testing.ts

@@ -0,0 +1,145 @@
+// Test doubles for this Package, and nothing production imports.
+//
+// The Workspace fake is local rather than borrowed from `plugin-skills`: that
+// one seeds text, and everything here is bytes. It records every call so a
+// test can prove reconciliation read the store and never the model.
+import {
+  workspaceRootKeyV1,
+  type WorkspaceDeleteRequestV1,
+  type WorkspaceEntryV1,
+  type WorkspaceFilesV1,
+  type WorkspaceGenerationV1,
+  type WorkspaceListOutcomeV1,
+  type WorkspaceListRequestV1,
+  type WorkspacePathV1,
+  type WorkspaceReadOutcomeV1,
+  type WorkspaceStatOutcomeV1,
+  type WorkspaceWriteOutcomeV1,
+  type WorkspaceWriteRequestV1,
+} from "@frockbot/kernel-contracts";
+import { sha256HexV1 } from "./bytes.js";
+import type { ImageModelInputV1, ImageModelV1 } from "./model.js";
+
+interface StoredFile {
+  entry: WorkspaceEntryV1;
+  bytes: Uint8Array;
+}
+
+/** An in-memory `WorkspaceFilesV1` over bytes. Records every call it served. */
+export class FakeImageWorkspace implements WorkspaceFilesV1 {
+  readonly calls: string[] = [];
+  #files = new Map<string, StoredFile>();
+  #sequence = 0;
+  /** Set to make the next `write` answer this outcome instead of storing. */
+  nextWriteOutcome?: WorkspaceWriteOutcomeV1;
+
+  #key(path: WorkspacePathV1): string {
+    return `${workspaceRootKeyV1(path.root)}::${path.path}`;
+  }
+
+  #nextGenerationId(): string {
+    this.#sequence += 1;
+    return `gen-${String(this.#sequence).padStart(4, "0")}`;
+  }
+
+  read(path: WorkspacePathV1): Promise<WorkspaceReadOutcomeV1> {
+    this.calls.push(`read:${path.path}`);
+    const stored = this.#files.get(this.#key(path));
+    if (!stored) {
+      return Promise.resolve({ status: "not-found", reason: "no such file" });
+    }
+    return Promise.resolve({
+      status: "ok",
+      file: { ...stored.entry, bytes: stored.bytes },
+    });
+  }
+
+  stat(path: WorkspacePathV1): Promise<WorkspaceStatOutcomeV1> {
+    this.calls.push(`stat:${path.path}`);
+    const stored = this.#files.get(this.#key(path));
+    if (!stored) {
+      return Promise.resolve({ status: "not-found", reason: "no such file" });
+    }
+    return Promise.resolve({ status: "ok", entry: stored.entry });
+  }
+
+  list(request: WorkspaceListRequestV1): Promise<WorkspaceListOutcomeV1> {
+    this.calls.push(`list:${workspaceRootKeyV1(request.root)}`);
+    const key = workspaceRootKeyV1(request.root);
+    const entries = [...this.#files.values()]
+      .filter((stored) => workspaceRootKeyV1(stored.entry.path.root) === key)
+      .map((stored) => stored.entry);
+    return Promise.resolve({ status: "ok", entries });
+  }
+
+  async write(
+    request: WorkspaceWriteRequestV1,
+  ): Promise<WorkspaceWriteOutcomeV1> {
+    this.calls.push(`write:${request.path.path}`);
+    const scripted = this.nextWriteOutcome;
+    if (scripted) {
+      this.nextWriteOutcome = undefined;
+      return scripted;
+    }
+    const key = this.#key(request.path);
+    const existing = this.#files.get(key);
+    const seen = existing?.entry.generation.generationId ?? null;
+    if (seen !== request.expectedGenerationId) {
+      return { status: "conflict", reason: "unexpected generation" };
+    }
+    const generation: WorkspaceGenerationV1 = {
+      schemaVersion: 1,
+      generationId: this.#nextGenerationId(),
+      contentHash: await sha256HexV1(request.bytes),
+      size: request.bytes.byteLength,
+      writer: request.writer,
+      writtenAt: new Date(0).toISOString(),
+    };
+    this.#files.set(key, {
+      entry: { path: request.path, generation },
+      bytes: request.bytes,
+    });
+    return { status: "ok", generation };
+  }
+
+  delete(request: WorkspaceDeleteRequestV1): Promise<WorkspaceWriteOutcomeV1> {
+    this.calls.push(`delete:${request.path.path}`);
+    this.#files.delete(this.#key(request.path));
+    return Promise.resolve({
+      status: "refused",
+      reason: "the fake does not tombstone",
+    });
+  }
+}
+
+/** The smallest valid PNG header this Package can decode, at a given size. */
+export function fakePngBytesV1(width: number, height: number): Uint8Array {
+  const bytes = new Uint8Array(64);
+  bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0);
+  // IHDR length (13) and type.
+  bytes.set([0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52], 8);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(16, width);
+  view.setUint32(20, height);
+  bytes[24] = 8;
+  bytes[25] = 6;
+  return bytes;
+}
+
+/** An image model that answers fixed bytes and counts every call. */
+export class FakeImageModel implements ImageModelV1 {
+  readonly calls: Array<{ model: string; input: ImageModelInputV1 }> = [];
+  #bytes: Uint8Array;
+  /** Set to make the next `run` reject with this message. */
+  failure?: string;
+
+  constructor(bytes: Uint8Array = fakePngBytesV1(1024, 1024)) {
+    this.#bytes = bytes;
+  }
+
+  run(model: string, input: ImageModelInputV1): Promise<ArrayBuffer> {
+    this.calls.push({ model, input });
+    if (this.failure) return Promise.reject(new Error(this.failure));
+    return Promise.resolve(this.#bytes.slice().buffer as ArrayBuffer);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-image
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.