@frockbot/plugin-shell 0.0.0 → 0.1.0

package/src/backend-contracts.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
+import { requireStoredRunV1, type StoredRun } from "./backend-contracts.js";
+
+function storedRun(): StoredRun {
+  return {
+    runId: "run-1",
+    commandFingerprint: "fingerprint",
+    sessionId: "user:primary",
+    acceptedAt: "2026-08-29T00:00:00.000Z",
+    input: "continue",
+    events: [],
+    effectAdmissions: [],
+    status: "running",
+    phase: "admitted",
+    compositionGenerationId: "test-composition-generation",
+    configurationSnapshot: initializeBotSettingsV1("primary"),
+    previousEventCount: 0,
+  };
+}
+
+describe("StoredRun durable contract", () => {
+  test("uses the public run identifier grammar", () => {
+    expect(() =>
+      requireStoredRunV1({ ...storedRun(), runId: "run:1" }),
+    ).toThrow("invalid runId");
+  });
+
+  test("rejects compatibility statuses and invalid status fields", () => {
+    expect(() =>
+      requireStoredRunV1({ ...storedRun(), status: "interrupted" }),
+    ).toThrow("valid status");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "failed",
+        phase: "executing",
+        failure: "",
+      }),
+    ).toThrow("invalid failure");
+    expect(() =>
+      requireStoredRunV1({ ...storedRun(), responseText: "unexpected" }),
+    ).toThrow("completion fields");
+  });
+
+  test("strictly bounds exact durable effect admission outcomes", () => {
+    expect(
+      requireStoredRunV1({
+        ...storedRun(),
+        effectAdmissions: [
+          { kind: "model", effectId: "request-1", outcome: "fenced" },
+          { kind: "tool", effectId: "tool:1:1:0", outcome: "admitted" },
+        ],
+      }).effectAdmissions,
+    ).toEqual([
+      { kind: "model", effectId: "request-1", outcome: "fenced" },
+      { kind: "tool", effectId: "tool:1:1:0", outcome: "admitted" },
+    ]);
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        effectAdmissions: [
+          {
+            kind: "model",
+            effectId: "request-1",
+            outcome: "fenced",
+            extra: true,
+          },
+        ],
+      }),
+    ).toThrow("invalid effect admission fields");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        effectAdmissions: [
+          { kind: "model", effectId: "same", outcome: "fenced" },
+          { kind: "tool", effectId: "same", outcome: "admitted" },
+        ],
+      }),
+    ).toThrow("colliding effect admissions");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        effectAdmissions: Array.from({ length: 257 }, (_, index) => ({
+          kind: "model",
+          effectId: `request-${index}`,
+          outcome: "admitted",
+        })),
+      }),
+    ).toThrow("invalid effect admissions");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        effectAdmissions: [
+          { kind: "model", effectId: "🧪".repeat(129), outcome: "admitted" },
+        ],
+      }),
+    ).toThrow("invalid effect admission id");
+    const symbolEntry = {
+      kind: "model",
+      effectId: "request-1",
+      outcome: "admitted",
+      [Symbol("hidden")]: true,
+    };
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        effectAdmissions: [symbolEntry],
+      }),
+    ).toThrow("invalid effect admission fields");
+  });
+
+  test("rejects hidden and symbol top-level durable fields", () => {
+    const hidden = { ...storedRun() };
+    Object.defineProperty(hidden, "future", {
+      value: true,
+      enumerable: false,
+    });
+    expect(() => requireStoredRunV1(hidden)).toThrow("invalid fields");
+
+    const symbol = { ...storedRun(), [Symbol("future")]: true };
+    expect(() => requireStoredRunV1(symbol)).toThrow("invalid fields");
+  });
+
+  test("keeps Stop intent orthogonal and required for cancellation", () => {
+    expect(
+      requireStoredRunV1({
+        ...storedRun(),
+        phase: "executing",
+        stopRequestedAt: "2026-08-29T00:00:05.000Z",
+      }),
+    ).toMatchObject({
+      status: "running",
+      phase: "executing",
+      stopRequestedAt: "2026-08-29T00:00:05.000Z",
+    });
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "cancelled",
+        phase: "executing",
+      }),
+    ).toThrow("no durable stop intent");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "cancelled",
+        phase: "executing",
+        stopRequestedAt: "whenever",
+      }),
+    ).toThrow("invalid stopRequestedAt");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "cancelled",
+        phase: "executing",
+        stopRequestedAt: "2026-08-29T00:00:05.000Z",
+        failure: "stopped",
+      }),
+    ).toThrow("invalid failure fields");
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "reconciliation-required",
+        phase: "executing",
+        failure: "uncertain",
+      }),
+    ).toThrow("inconsistent recovery state");
+  });
+
+  test("accepts completed output up to the public wire byte limit", () => {
+    expect(
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "completed",
+        phase: "executing",
+        responseText: "x".repeat(64_000),
+      }).responseText,
+    ).toHaveLength(64_000);
+    expect(() =>
+      requireStoredRunV1({
+        ...storedRun(),
+        status: "completed",
+        phase: "executing",
+        responseText: "🧪".repeat(16_001),
+      }),
+    ).toThrow("invalid responseText");
+  });
+});

package/src/backend-contracts.ts

@@ -0,0 +1,44 @@
+// The Bot Durable Object's run records are kernel authority; this module binds
+// the kernel codec to the Shell Package's configuration snapshot decoder.
+import {
+  createStoredRunCodecV1,
+  type StoredRunCodecV1,
+  type StoredRunV1,
+} from "@frockbot/kernel-do";
+import {
+  decodeBotSettingsViewV1,
+  isPublicIdentifier,
+  type BotSettingsViewV1,
+} from "@frockbot/configuration-core";
+
+export {
+  botStopCommandFingerprintV1,
+  botTurnCommandFingerprintV1,
+  type BotNotificationIntent,
+  type BotStopCommand,
+  type BotTurnCommand,
+  type BotTurnCompletion,
+  type StoredEffectAdmission,
+  type StoredEffectAdmissionOutcome,
+  type StoredRunPhase,
+  type StoredRunStatus,
+} from "@frockbot/kernel-do";
+
+export type StoredRun = StoredRunV1<BotSettingsViewV1>;
+
+export function decodeRunIdV1(value: unknown): string {
+  if (!isPublicIdentifier(value)) {
+    throw new Error("runId is invalid");
+  }
+  return value;
+}
+
+export const storedRunCodecV1: StoredRunCodecV1<BotSettingsViewV1> =
+  createStoredRunCodecV1<BotSettingsViewV1>({
+    decodeRunId: decodeRunIdV1,
+    decodeConfigurationSnapshot: decodeBotSettingsViewV1,
+  });
+
+export function requireStoredRunV1(input: unknown): StoredRun {
+  return storedRunCodecV1.require(input);
+}

package/src/backend-debug.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test } from "bun:test";
+import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
+import { createShellBotBackendContribution } from "./backend.js";
+import type { StoredRun } from "./backend-contracts.js";
+
+class MemoryStorage {
+  readonly values = new Map<string, unknown>();
+  alarmAt: number | undefined;
+
+  get<T>(key: string): Promise<T | undefined> {
+    return Promise.resolve(this.values.get(key) as T | undefined);
+  }
+
+  put(key: string | Record<string, unknown>, value?: unknown): Promise<void> {
+    if (typeof key === "string") this.values.set(key, structuredClone(value));
+    else {
+      for (const [entry, item] of Object.entries(key)) {
+        this.values.set(entry, structuredClone(item));
+      }
+    }
+    return Promise.resolve();
+  }
+
+  delete(key: string): Promise<boolean> {
+    return Promise.resolve(this.values.delete(key));
+  }
+
+  list<T>(options: {
+    prefix?: string;
+    end?: string;
+    reverse?: boolean;
+    limit?: number;
+  }): Promise<Map<string, T>> {
+    const entries = [...this.values.entries()]
+      .filter(
+        ([key]) =>
+          key.startsWith(options.prefix ?? "") &&
+          (options.end === undefined || key < options.end),
+      )
+      .sort(([left], [right]) => left.localeCompare(right));
+    if (options.reverse) entries.reverse();
+    return Promise.resolve(
+      new Map(entries.slice(0, options.limit) as Array<[string, T]>),
+    );
+  }
+
+  transaction<T>(callback: (storage: MemoryStorage) => Promise<T>): Promise<T> {
+    return callback(this);
+  }
+
+  setAlarm(scheduledTime: number): Promise<void> {
+    this.alarmAt = scheduledTime;
+    return Promise.resolve();
+  }
+
+  deleteAlarm(): Promise<void> {
+    this.alarmAt = undefined;
+    return Promise.resolve();
+  }
+}
+
+const IDENTITY = { userId: "user-1", botId: "primary" };
+
+function storedRun(overrides: Partial<StoredRun> = {}): StoredRun {
+  return {
+    runId: "run-1",
+    commandFingerprint: "fingerprint",
+    sessionId: "user:primary",
+    acceptedAt: "2026-08-28T00:00:00.000Z",
+    input: "hello",
+    events: [],
+    effectAdmissions: [],
+    status: "running",
+    phase: "executing",
+    compositionGenerationId: "test-composition-generation",
+    configurationSnapshot: initializeBotSettingsV1("primary"),
+    previousEventCount: 0,
+    ...overrides,
+  } as StoredRun;
+}
+
+function contributionOver(storage: MemoryStorage) {
+  return createShellBotBackendContribution({
+    state: { storage } as unknown as DurableObjectState,
+    env: {} as never,
+  });
+}
+
+describe("Bot debug snapshot", () => {
+  test("reports the wedged active run with the events the client view hides", async () => {
+    const storage = new MemoryStorage();
+    const run = storedRun({
+      events: [
+        { type: "turn/start", turn: 1, seq: 1, timestamp: IDENTITY.userId },
+        {
+          type: "tool/call",
+          turn: 1,
+          step: 1,
+          occurrenceId: "call-1",
+          name: "shell",
+          input: { command: "ls" },
+          seq: 2,
+          timestamp: "2026-08-28T00:00:01.000Z",
+        },
+      ] as StoredRun["events"],
+    });
+    await storage.put({
+      identity: IDENTITY,
+      "active-run": run.runId,
+      [`run:${run.runId}`]: run,
+      [`run-index:${run.acceptedAt}:${run.runId}`]: run.runId,
+    });
+
+    const snapshot = await contributionOver(storage).debugSnapshot(IDENTITY, {
+      schemaVersion: 1,
+      events: true,
+    });
+
+    expect(snapshot.activeRunId).toBe("run-1");
+    expect(snapshot.runs).toHaveLength(1);
+    expect(snapshot.runs[0]).toMatchObject({
+      runId: "run-1",
+      status: "running",
+      phase: "executing",
+      eventCount: 2,
+    });
+    // The client projection drops `input`; the operator view is the reason
+    // this surface exists.
+    expect(snapshot.runs[0]!.events).toContainEqual(
+      expect.objectContaining({ name: "shell", input: { command: "ls" } }),
+    );
+  });
+
+  test("carries the failure of a failed run", async () => {
+    const storage = new MemoryStorage();
+    const run = storedRun({
+      runId: "run-failed",
+      status: "failed",
+      failure: "model connection is unavailable",
+    });
+    await storage.put({
+      identity: IDENTITY,
+      [`run:${run.runId}`]: run,
+      [`run-index:${run.acceptedAt}:${run.runId}`]: run.runId,
+    });
+
+    const snapshot = await contributionOver(storage).debugSnapshot(IDENTITY);
+
+    expect(snapshot.runs[0]).toMatchObject({
+      runId: "run-failed",
+      status: "failed",
+      failure: "model connection is unavailable",
+    });
+    expect(snapshot.activeRunId).toBeUndefined();
+  });
+
+  test("includes an active run older than the page it would otherwise fall off", async () => {
+    const storage = new MemoryStorage();
+    const stale = storedRun({
+      runId: "run-stale",
+      acceptedAt: "2026-08-27T00:00:00.000Z",
+    });
+    const recent = storedRun({
+      runId: "run-recent",
+      acceptedAt: "2026-08-29T00:00:00.000Z",
+      status: "completed",
+      phase: "admitted",
+      responseText: "done",
+    });
+    await storage.put({
+      identity: IDENTITY,
+      "active-run": stale.runId,
+      [`run:${stale.runId}`]: stale,
+      [`run:${recent.runId}`]: recent,
+      [`run-index:${stale.acceptedAt}:${stale.runId}`]: stale.runId,
+      [`run-index:${recent.acceptedAt}:${recent.runId}`]: recent.runId,
+    });
+
+    const snapshot = await contributionOver(storage).debugSnapshot(IDENTITY, {
+      schemaVersion: 1,
+      limit: 1,
+    });
+
+    expect(snapshot.runs.map((run) => run.runId)).toContain("run-stale");
+  });
+
+  test("does not disturb the run it is looking at", async () => {
+    const storage = new MemoryStorage();
+    const run = storedRun({ runId: "run-wedged" });
+    await storage.put({
+      identity: IDENTITY,
+      "active-run": run.runId,
+      [`run:${run.runId}`]: run,
+      [`run-index:${run.acceptedAt}:${run.runId}`]: run.runId,
+    });
+
+    await contributionOver(storage).debugSnapshot(IDENTITY);
+
+    expect(await storage.get<string>("active-run")).toBe("run-wedged");
+    expect(await storage.get<StoredRun>(`run:${run.runId}`)).toEqual(run);
+  });
+});

package/src/backend-execution.ts

@@ -0,0 +1,55 @@
+import type { AgentEffectAdmission } from "@frockbot/kernel-agent-loop/agent";
+import type {
+  PersistSessionEvents,
+  SessionEvent,
+} from "@frockbot/kernel-contracts";
+import type {
+  BotExecutionPlanV1,
+  BotSettingsViewV1,
+  ConnectionView,
+} from "@frockbot/configuration-core";
+import type { BotTurnCommand, BotTurnCompletion } from "./backend-contracts.js";
+
+export interface BotResidentProjection {
+  generation: number;
+  userId: string;
+  botId: string;
+  settings: BotSettingsViewV1;
+  executionPlan: BotExecutionPlanV1;
+  systemPromptSection: string;
+  authorizeConnection(
+    assignment: BotSettingsViewV1["assignments"][number],
+  ): Promise<ConnectionView>;
+}
+
+export interface BotResidentTurnExecution {
+  botId: string;
+  command: BotTurnCommand;
+  previousEvents: readonly SessionEvent[];
+  persistSessionEvents: PersistSessionEvents;
+  /**
+   * Runs after the exact resident handle is addressable but before Agent input
+   * or recovery is activated. False means durable state fenced execution.
+   */
+  beforeStart(): Promise<boolean>;
+  /** Serializes each new provider/tool effect against durable Stop intent. */
+  admitEffect(effect: AgentEffectAdmission): Promise<boolean>;
+  resume?: boolean;
+}
+
+/** Narrow cancellation request bound to one exact resident run. */
+export interface BotResidentCancellation {
+  botId: string;
+  sessionId: string;
+  runId: string;
+  reason: "user";
+}
+
+/** The Bot host's sole resident Agent-runtime seam. */
+export interface BotResidentExecution {
+  project(projection: BotResidentProjection): Promise<void>;
+  execute(execution: BotResidentTurnExecution): Promise<BotTurnCompletion>;
+  /** Signals the resident Agent; true only when that exact run was signalled. */
+  cancel(cancellation: BotResidentCancellation): Promise<boolean>;
+  generation(): number | undefined;
+}

package/src/backend-flock.ts

@@ -0,0 +1,96 @@
+// The Bot Durable Object's half of the Bot self-management seam.
+//
+// The Flock Package offers a Bot two tools over its own identity and its
+// User's flock. This module decides, for one admitted Turn, what provenance
+// those writes record and which authorities they may reach. It implements
+// neither: the profile write is the Bot Durable Object's own configuration
+// command, and the create is the User Durable Object's `bot/create` — the
+// same two paths the hosted client drives.
+//
+// AUTHORITY. "Self-modification never widens authority." The host handed to
+// the Package exposes exactly four calls, all of them things the User's own
+// surfaces already do, and the `botId` on every one of them is fixed here
+// rather than taken from the model's arguments. A Bot cannot address another
+// Bot's settings through this seam because the seam never accepts a target.
+//
+// HIBERNATION. Nothing here reaches the Computer registry, a Computer
+// provider, or a Sprite: identity is Durable Object state, so self-management
+// works while the Computer is hibernated and does not wake it.
+import type {
+  BotSettingsViewV1,
+  ConfigurationCommandV1,
+  OperationReceiptV1,
+} from "@frockbot/configuration-core";
+import type {
+  BotDirectoryViewV1,
+  CreateBotCommandV1,
+  FlockReceiptV1,
+  FlockSelfRuntimeHostV1,
+} from "@frockbot/plugin-flock/agent";
+
+/** The Bot and User whose identity a Turn may change. */
+export interface BotSelfManagementIdentity {
+  userId: string;
+  botId: string;
+}
+
+/** The run, Turn, and Session a self-management write records. */
+export interface BotSelfManagementTurn {
+  runId: string;
+  turnId: string;
+  sessionId: string;
+}
+
+/**
+ * The authorities this seam borrows, supplied by the Durable Object that owns
+ * them. Named as its own type so each one is an explicit grant rather than a
+ * reach into an environment.
+ */
+export interface BotSelfManagementAuthorities {
+  readSettings(identity: BotSelfManagementIdentity): Promise<BotSettingsViewV1>;
+  executeConfiguration(
+    identity: BotSelfManagementIdentity,
+    command: Extract<ConfigurationCommandV1, { botId: string }>,
+  ): Promise<OperationReceiptV1>;
+  listBots(userId: string): Promise<BotDirectoryViewV1>;
+  createBot(
+    userId: string,
+    command: CreateBotCommandV1,
+  ): Promise<FlockReceiptV1>;
+}
+
+/**
+ * The self-management seam one admitted Turn runs under. There is no
+ * `undefined` case: identity is Durable Object state that is always present,
+ * unlike a Workspace surface a host may not have bound.
+ */
+export function createBotSelfManagementHost(
+  identity: BotSelfManagementIdentity,
+  turn: BotSelfManagementTurn,
+  authorities: BotSelfManagementAuthorities,
+): FlockSelfRuntimeHostV1 {
+  const owner = { userId: identity.userId, botId: identity.botId };
+  return {
+    owner,
+    // A Bot changes itself only inside a Turn whose Session and Turn its
+    // provenance names — the same rule Memory, Skills and Package authoring
+    // follow.
+    writer: {
+      kind: "bot",
+      botId: identity.botId,
+      sessionId: turn.sessionId,
+      turnId: turn.turnId,
+    },
+    readSelf: () => authorities.readSettings(identity),
+    commandSelf: (command) => {
+      // The target is this Bot, decided here. A command aimed anywhere else
+      // never reaches an authority.
+      if (command.botId !== identity.botId) {
+        throw new Error("a Bot may only change its own configuration");
+      }
+      return authorities.executeConfiguration(identity, command);
+    },
+    listBots: () => authorities.listBots(identity.userId),
+    createBot: (command) => authorities.createBot(identity.userId, command),
+  };
+}

package/src/backend-image.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import {
+  FakeImageWorkspace,
+  fakePngBytesV1,
+} from "@frockbot/plugin-image/testing";
+import {
+  createBotImageHost,
+  createWorkersAiImageModelV1,
+  decodeWorkersAiImageV1,
+} from "./backend-image.ts";
+
+const IDENTITY = { userId: "user-1", botId: "bot-1" };
+const TURN = { runId: "run-9", turnId: "turn-4", sessionId: "user-1:bot-1" };
+
+function base64(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes));
+}
+
+describe("the Bot image seam", () => {
+  test("mounts nothing when the Workspace file surface is unbound", () => {
+    expect(createBotImageHost(IDENTITY, TURN, { AI: { run: () => {} } })).toBe(
+      undefined,
+    );
+  });
+
+  test("mounts with no model when Workers AI is unbound, so the refusal is visible", () => {
+    const workspace = new FakeImageWorkspace();
+    const host = createBotImageHost(IDENTITY, TURN, {
+      WORKSPACE_FILES: workspace,
+    });
+    expect(host).toBeDefined();
+    expect(host?.model).toBeUndefined();
+    expect(host?.files).toBe(workspace);
+    // The seam reaches the Workspace and nothing else: no Computer is opened
+    // to build it, so a hibernated Computer changes none of this.
+    expect(workspace.calls).toEqual([]);
+  });
+
+  test("binds the Bot's provenance and the adapted model when both are present", () => {
+    const workspace = new FakeImageWorkspace();
+    const host = createBotImageHost(IDENTITY, TURN, {
+      WORKSPACE_FILES: workspace,
+      AI: { run: () => Promise.resolve({ image: "" }) },
+    });
+    expect(host?.owner).toEqual(IDENTITY);
+    expect(host?.writer).toEqual({
+      sessionId: "user-1:bot-1",
+      turnId: "turn-4",
+      runId: "run-9",
+    });
+    expect(host?.model).toBeDefined();
+  });
+});
+
+describe("normalizing what Workers AI answered", () => {
+  const png = fakePngBytesV1(64, 32);
+
+  test("accepts the base64 envelope the FLUX models answer", async () => {
+    const buffer = await decodeWorkersAiImageV1({ image: base64(png) });
+    expect([...new Uint8Array(buffer)]).toEqual([...png]);
+  });
+
+  test("accepts the binary stream the Stable Diffusion models answer", async () => {
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(png.slice(0, 8));
+        controller.enqueue(png.slice(8));
+        controller.close();
+      },
+    });
+    expect([...new Uint8Array(await decodeWorkersAiImageV1(stream))]).toEqual([
+      ...png,
+    ]);
+  });
+
+  test("accepts a raw buffer or view", async () => {
+    expect([
+      ...new Uint8Array(await decodeWorkersAiImageV1(png.slice().buffer)),
+    ]).toEqual([...png]);
+    expect([...new Uint8Array(await decodeWorkersAiImageV1(png))]).toEqual([
+      ...png,
+    ]);
+  });
+
+  test("refuses anything else rather than storing it", async () => {
+    for (const answer of [undefined, null, 7, "hello", { image: 3 }, {}]) {
+      await expect(decodeWorkersAiImageV1(answer)).rejects.toThrow(
+        "not an image",
+      );
+    }
+  });
+
+  test("passes the requested size through to the binding", async () => {
+    const calls: Array<[string, Record<string, unknown>]> = [];
+    const model = createWorkersAiImageModelV1({
+      run: (name, input) => {
+        calls.push([name, input]);
+        return Promise.resolve({ image: base64(png) });
+      },
+    });
+
+    await model.run("@cf/black-forest-labs/flux-1-schnell", {
+      prompt: "a red barn",
+      width: 512,
+      height: 512,
+    });
+
+    expect(calls).toEqual([
+      [
+        "@cf/black-forest-labs/flux-1-schnell",
+        { prompt: "a red barn", width: 512, height: 512 },
+      ],
+    ]);
+  });
+});