@frockbot/plugin-shell 0.0.0 → 0.1.0

package/src/backend-bot-identity.test.ts

@@ -0,0 +1,215 @@
+// Slice B, the durable half: the partial profile command, the provenance it
+// records, and the rename announcement it appends to the Bot's Session.
+import { describe, expect, test } from "bun:test";
+import type { BotSettingsViewV1 } from "@frockbot/configuration-core";
+import { createShellBotBackendContribution } from "./backend.js";
+import { BOT_ANNOUNCEMENT_RETENTION } from "./backend.js";
+
+class MemoryStorage {
+  readonly values = new Map<string, unknown>();
+
+  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 | string[]): Promise<boolean | number> {
+    if (Array.isArray(key)) {
+      let removed = 0;
+      for (const entry of key) if (this.values.delete(entry)) removed += 1;
+      return Promise.resolve(removed);
+    }
+    return Promise.resolve(this.values.delete(key));
+  }
+
+  list<T>(options: { prefix?: string }): Promise<Map<string, T>> {
+    return Promise.resolve(
+      new Map(
+        [...this.values.entries()]
+          .filter(([key]) => key.startsWith(options.prefix ?? ""))
+          .sort(([left], [right]) => left.localeCompare(right)) as Array<
+          [string, T]
+        >,
+      ),
+    );
+  }
+
+  transaction<T>(callback: (storage: MemoryStorage) => Promise<T>): Promise<T> {
+    return callback(this);
+  }
+
+  setAlarm(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  deleteAlarm(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+const identity = { userId: "user-1", botId: "primary" };
+
+function contributionOn(storage: MemoryStorage) {
+  return createShellBotBackendContribution({
+    state: { storage } as unknown as DurableObjectState,
+    env: {} as never,
+  });
+}
+
+async function setProfile(
+  contribution: ReturnType<typeof contributionOn>,
+  commandId: string,
+  expectedRevision: number,
+  profile: Record<string, unknown>,
+  namedBy?: "user" | "bot",
+  writer?: Record<string, unknown>,
+): Promise<void> {
+  await contribution.executeConfiguration({
+    schemaVersion: 1,
+    userId: identity.userId,
+    botId: identity.botId,
+    command: {
+      schemaVersion: 1,
+      type: "bot/set-profile",
+      commandId,
+      botId: identity.botId,
+      expectedRevision,
+      ...(namedBy ? { namedBy } : {}),
+      ...(writer ? { writer } : {}),
+      profile,
+    },
+  });
+}
+
+describe("bot/set-profile", () => {
+  test("changes only the fields the command carries", async () => {
+    const storage = new MemoryStorage();
+    const contribution = contributionOn(storage);
+    await contribution.materializeSettings(identity, { name: "Housework" });
+    await setProfile(contribution, "title-1", 0, {
+      title: "Chief of staff",
+      description: "Keeps things tidy.",
+    });
+    await setProfile(contribution, "hide-1", 1, { hiddenFromSidebar: true });
+
+    const settings = (await storage.get(
+      "bot-configuration",
+    )) as BotSettingsViewV1;
+    expect(settings.profile).toEqual({
+      name: "Housework",
+      title: "Chief of staff",
+      description: "Keeps things tidy.",
+      hiddenFromSidebar: true,
+    });
+    expect(settings.revision).toBe(2);
+    // Neither command touched the name, so neither recorded a writer for it.
+    expect(settings.profile.namedBy).toBeUndefined();
+  });
+
+  test("records the writer of a rename and announces it in the Session", async () => {
+    const storage = new MemoryStorage();
+    const contribution = contributionOn(storage);
+    await contribution.materializeSettings(identity, { name: "Housework" });
+    await setProfile(contribution, "rename-1", 0, { name: "Atlas" }, "bot");
+
+    const settings = (await storage.get(
+      "bot-configuration",
+    )) as BotSettingsViewV1;
+    expect(settings.profile).toEqual({ name: "Atlas", namedBy: "bot" });
+    const announcements = await contribution.listAnnouncements();
+    expect(announcements).toHaveLength(1);
+    expect(announcements[0]).toMatchObject({
+      type: "bot/renamed",
+      seq: 0,
+      from: "Housework",
+      to: "Atlas",
+      namedBy: "bot",
+    });
+  });
+
+  test("a Bot's self-rename carries its writer into the announcement", async () => {
+    const storage = new MemoryStorage();
+    const contribution = contributionOn(storage);
+    const writer = {
+      kind: "bot",
+      botId: identity.botId,
+      sessionId: "user-1:primary",
+      turnId: "turn-4",
+    };
+    await contribution.materializeSettings(identity, { name: "Housework" });
+    await setProfile(
+      contribution,
+      "rename-1",
+      0,
+      { name: "Atlas" },
+      "bot",
+      writer,
+    );
+    // A User edit that happens to carry no writer still announces as before.
+    await setProfile(contribution, "rename-2", 1, { name: "Housework" });
+
+    const announcements = await contribution.listAnnouncements();
+    expect(announcements[0]).toMatchObject({ namedBy: "bot", writer });
+    expect(announcements[1]).toMatchObject({ namedBy: "user" });
+    expect(announcements[1]).not.toHaveProperty("writer");
+  });
+
+  test("announces a User rename by default and never for an unchanged name", async () => {
+    const storage = new MemoryStorage();
+    const contribution = contributionOn(storage);
+    await contribution.materializeSettings(identity, { name: "Housework" });
+    await setProfile(contribution, "rename-1", 0, { name: "Atlas" });
+    await setProfile(contribution, "same-1", 1, { name: "Atlas" });
+    await setProfile(contribution, "title-1", 2, { title: "Chief" });
+
+    const announcements = await contribution.listAnnouncements();
+    expect(announcements).toHaveLength(1);
+    expect(announcements[0]).toMatchObject({ namedBy: "user", to: "Atlas" });
+  });
+
+  test("bounds the announcement log and keeps the newest renames", async () => {
+    const storage = new MemoryStorage();
+    const contribution = contributionOn(storage);
+    await contribution.materializeSettings(identity, { name: "name-0" });
+    const renames = BOT_ANNOUNCEMENT_RETENTION + 3;
+    for (let index = 1; index <= renames; index += 1) {
+      await setProfile(contribution, `rename-${index}`, index - 1, {
+        name: `name-${index}`,
+      });
+    }
+    const announcements = await contribution.listAnnouncements();
+    expect(announcements).toHaveLength(BOT_ANNOUNCEMENT_RETENTION);
+    expect(announcements.at(-1)).toMatchObject({ to: `name-${renames}` });
+    expect(announcements[0]).toMatchObject({
+      to: `name-${renames - BOT_ANNOUNCEMENT_RETENTION + 1}`,
+    });
+  });
+
+  test("a rename announcement rides the run list the Session shows", async () => {
+    const storage = new MemoryStorage();
+    const contribution = contributionOn(storage);
+    await contribution.materializeSettings(identity, { name: "Housework" });
+    await setProfile(contribution, "rename-1", 0, { name: "Atlas" }, "user");
+
+    const page = await contribution.listRuns({ schemaVersion: 1 });
+    expect(page.announcements).toEqual([
+      {
+        type: "bot/renamed",
+        announcementId: "announcement-0",
+        at: expect.any(String),
+        from: "Housework",
+        to: "Atlas",
+        namedBy: "user",
+      },
+    ]);
+  });
+});

package/src/backend-completion.test.ts

@@ -0,0 +1,289 @@
+import { describe, expect, test } from "bun:test";
+import { type SessionEvent } from "@frockbot/kernel-contracts";
+import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
+import {
+  botTurnCommandFingerprintV1,
+  type BotTurnCompletion,
+  type StoredRun,
+} from "./backend-contracts.js";
+import {
+  completeStoredRun,
+  failStoredRun,
+  requireStoredRunReconciliation,
+  type RunTerminalKeys,
+  type RunTerminalStorage,
+} from "./backend-completion.js";
+
+const keys: RunTerminalKeys = {
+  run: "run:run-1",
+  activeRun: "active-run",
+  latestEvents: "latest-events",
+  notificationPrefix: "notification:",
+};
+
+const ended = {
+  type: "turn/end" as const,
+  seq: 0,
+  timestamp: "2026-08-28T00:00:00.000Z",
+  turn: 1,
+  outcome: "completed" as const,
+};
+
+function storedRun(): StoredRun {
+  return {
+    runId: "run-1",
+    commandFingerprint: botTurnCommandFingerprintV1({
+      userId: "user-1",
+      botId: "primary",
+      runId: "run-1",
+      sessionId: "user:primary",
+      acceptedAt: "2026-08-28T00:00:00.000Z",
+      text: "hello",
+    }),
+    sessionId: "user:primary",
+    acceptedAt: "2026-08-28T00:00:00.000Z",
+    input: "hello",
+    events: [ended],
+    effectAdmissions: [],
+    status: "running",
+    phase: "executing",
+    compositionGenerationId: "test-composition-generation",
+    configurationSnapshot: initializeBotSettingsV1("primary"),
+    previousEventCount: 0,
+  };
+}
+
+function result(): BotTurnCompletion {
+  return {
+    runId: "run-1",
+    text: "Done",
+    events: [ended],
+    notification: {
+      notificationId: "run-1",
+      runId: "run-1",
+      createdAt: "2026-08-28T00:00:01.000Z",
+      title: "Bot replied",
+      body: "Done",
+    },
+  };
+}
+
+class MemoryRunStorage implements RunTerminalStorage {
+  readonly values = new Map<string, unknown>([
+    [keys.run, storedRun()],
+    [keys.activeRun, "run-1"],
+    [keys.latestEvents, []],
+  ]);
+  putFailure: Error | undefined;
+  putBatches: Array<Record<string, unknown>> = [];
+
+  get<T>(key: string): Promise<T | undefined> {
+    return Promise.resolve(this.values.get(key) as T | undefined);
+  }
+
+  put(entries: Record<string, unknown>): Promise<void> {
+    this.putBatches.push(structuredClone(entries));
+    if (this.putFailure) return Promise.reject(this.putFailure);
+    for (const [key, value] of Object.entries(entries)) {
+      this.values.set(key, structuredClone(value));
+    }
+    return Promise.resolve();
+  }
+
+  delete(key: string): Promise<boolean> {
+    return Promise.resolve(this.values.delete(key));
+  }
+}
+
+describe("Bot run terminal persistence", () => {
+  test("commits completion and notification in one durable batch", async () => {
+    const storage = new MemoryRunStorage();
+
+    await completeStoredRun(storage, keys, "run-1", [], result());
+
+    expect(storage.putBatches).toHaveLength(1);
+    expect(storage.putBatches[0]).toHaveProperty(keys.run);
+    expect(storage.putBatches[0]).toHaveProperty("notification:run-1");
+    expect(storage.values.get(keys.run)).toMatchObject({ status: "completed" });
+    expect(storage.values.has(keys.activeRun)).toBe(false);
+  });
+
+  test("cancels without notifying when Stop wins the terminal transaction", async () => {
+    const storage = new MemoryRunStorage();
+    storage.values.set(keys.run, {
+      ...storedRun(),
+      stopRequestedAt: "2026-08-30T00:00:00.000Z",
+    } satisfies StoredRun);
+
+    await expect(
+      completeStoredRun(storage, keys, "run-1", [], result()),
+    ).resolves.toBe("cancelled");
+
+    expect(storage.values.get(keys.run)).toMatchObject({
+      status: "cancelled",
+      stopRequestedAt: "2026-08-30T00:00:00.000Z",
+    });
+    expect(storage.values.has("notification:run-1")).toBe(false);
+    expect(storage.values.has(keys.activeRun)).toBe(false);
+  });
+
+  test("rejects malformed terminal events before clearing active work", async () => {
+    const storage = new MemoryRunStorage();
+    const malformed = {
+      ...result(),
+      events: [
+        {
+          type: "model/request",
+          seq: 0,
+          timestamp: "2026-08-28T00:00:00.000Z",
+          turn: 1,
+          step: 1,
+        },
+      ] as SessionEvent[],
+    };
+
+    await expect(
+      completeStoredRun(storage, keys, "run-1", [], malformed),
+    ).rejects.toThrow();
+
+    expect(storage.values.get(keys.run)).toMatchObject({ status: "running" });
+    expect(storage.values.get(keys.activeRun)).toBe("run-1");
+  });
+
+  test("persists responses up to the public wire limit", async () => {
+    const storage = new MemoryRunStorage();
+
+    await completeStoredRun(storage, keys, "run-1", [], {
+      ...result(),
+      text: "x".repeat(64_000),
+    });
+
+    expect(storage.values.get(keys.run)).toMatchObject({
+      status: "completed",
+      responseText: "x".repeat(64_000),
+    });
+  });
+
+  test("does not leave a success notification when completion rolls back", async () => {
+    const storage = new MemoryRunStorage();
+    storage.putFailure = new Error("completion transaction failed");
+
+    await expect(
+      completeStoredRun(storage, keys, "run-1", [], result()),
+    ).rejects.toThrow("completion transaction failed");
+    storage.putFailure = undefined;
+    await failStoredRun(
+      storage,
+      keys,
+      "run-1",
+      [],
+      [ended],
+      "completion transaction failed",
+    );
+
+    expect(storage.values.get(keys.run)).toMatchObject({ status: "failed" });
+    expect(storage.values.has("notification:run-1")).toBe(false);
+  });
+
+  test("cancels instead of failing when Stop wins the failure transaction", async () => {
+    const storage = new MemoryRunStorage();
+    storage.values.set(keys.run, {
+      ...storedRun(),
+      stopRequestedAt: "2026-08-30T00:00:00.000Z",
+    } satisfies StoredRun);
+
+    await expect(
+      failStoredRun(storage, keys, "run-1", [], [ended], "late failure"),
+    ).resolves.toBe("cancelled");
+
+    expect(storage.values.get(keys.run)).toMatchObject({ status: "cancelled" });
+    expect(storage.values.has(keys.activeRun)).toBe(false);
+  });
+
+  test("terminalizes an explicitly abandoned reconciliation", async () => {
+    const storage = new MemoryRunStorage();
+    storage.values.set(keys.run, {
+      ...storedRun(),
+      status: "reconciliation-required",
+      phase: "reconciliation-required",
+      failure: "provider outcome is uncertain",
+    } satisfies StoredRun);
+
+    await failStoredRun(
+      storage,
+      keys,
+      "run-1",
+      [],
+      [ended],
+      "reconciliation abandoned",
+    );
+
+    expect(storage.values.get(keys.run)).toMatchObject({
+      status: "failed",
+      phase: "executing",
+      failure: "reconciliation abandoned",
+    });
+    expect(storage.values.has(keys.activeRun)).toBe(false);
+  });
+
+  test("preserves committed success after an uncertain response", async () => {
+    const storage = new MemoryRunStorage();
+    await completeStoredRun(storage, keys, "run-1", [], result());
+
+    await expect(
+      failStoredRun(
+        storage,
+        keys,
+        "run-1",
+        [],
+        [
+          {
+            ...ended,
+            outcome: "model-error",
+          } satisfies SessionEvent,
+        ],
+        "completion response lost",
+      ),
+    ).resolves.toBe("preserved-completion");
+
+    expect(storage.values.get(keys.run)).toMatchObject({ status: "completed" });
+    expect(storage.values.has("notification:run-1")).toBe(true);
+  });
+
+  test("keeps an unretrievable effect active and reconciliation-required", async () => {
+    const storage = new MemoryRunStorage();
+    const request = {
+      type: "model/request" as const,
+      seq: 0,
+      timestamp: "2026-08-28T00:00:00.000Z",
+      turn: 1,
+      step: 1,
+      request: {
+        requestId: "effect-1",
+        provider: "openai-compatible",
+        model: "model-1",
+        system: "",
+        messages: [],
+        tools: [],
+      },
+    } satisfies SessionEvent;
+    storage.values.set(keys.run, { ...storedRun(), events: [request] });
+
+    await requireStoredRunReconciliation(
+      storage,
+      keys,
+      "run-1",
+      [],
+      [request],
+      "provider-bound retrieval unavailable",
+    );
+
+    expect(storage.values.get(keys.run)).toMatchObject({
+      status: "reconciliation-required",
+      phase: "reconciliation-required",
+      failure: "provider-bound retrieval unavailable",
+    });
+    expect(storage.values.get(keys.activeRun)).toBe("run-1");
+    expect(storage.values.get(keys.latestEvents)).toEqual([request]);
+  });
+});

package/src/backend-completion.ts

@@ -0,0 +1,95 @@
+// Kernel run-terminal transitions, bound to the Shell Package's run codec.
+import { type SessionEvent } from "@frockbot/kernel-contracts";
+import {
+  cancelStoredRun as cancelKernelStoredRun,
+  completeStoredRun as completeKernelStoredRun,
+  failStoredRun as failKernelStoredRun,
+  requireStoredRunReconciliation as requireKernelStoredRunReconciliation,
+  type TerminalPackageRecords,
+} from "@frockbot/kernel-do";
+import {
+  storedRunCodecV1,
+  type BotTurnCompletion,
+} from "./backend-contracts.js";
+import type { BotSettingsViewV1 } from "@frockbot/configuration-core";
+
+export type { RunTerminalKeys, RunTerminalStorage } from "@frockbot/kernel-do";
+import type { RunTerminalKeys, RunTerminalStorage } from "@frockbot/kernel-do";
+
+export function completeStoredRun(
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  result: BotTurnCompletion,
+  packageRecords?: TerminalPackageRecords<BotSettingsViewV1>,
+): Promise<"completed" | "cancelled"> {
+  return completeKernelStoredRun(
+    storedRunCodecV1,
+    storage,
+    keys,
+    runId,
+    previous,
+    result,
+    packageRecords,
+  );
+}
+
+export function failStoredRun(
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+  failure: string,
+): Promise<"failed" | "cancelled" | "preserved-completion" | "missing"> {
+  return failKernelStoredRun(
+    storedRunCodecV1,
+    storage,
+    keys,
+    runId,
+    previous,
+    events,
+    failure,
+  );
+}
+
+/**
+ * Settles a stopped run as terminal `cancelled` and clears its active marker.
+ * A cancelled run produces no response text, no failure, and no notification.
+ */
+export function cancelStoredRun(
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+): Promise<"cancelled" | "preserved-completion" | "missing"> {
+  return cancelKernelStoredRun(
+    storedRunCodecV1,
+    storage,
+    keys,
+    runId,
+    previous,
+    events,
+  );
+}
+
+export function requireStoredRunReconciliation(
+  storage: RunTerminalStorage,
+  keys: RunTerminalKeys,
+  runId: string,
+  previous: readonly SessionEvent[],
+  events: readonly SessionEvent[],
+  failure: string,
+): Promise<void> {
+  return requireKernelStoredRunReconciliation(
+    storedRunCodecV1,
+    storage,
+    keys,
+    runId,
+    previous,
+    events,
+    failure,
+  );
+}