@frockbot/plugin-shell 0.0.0 → 0.1.1

package/src/terminal-records.ts

@@ -0,0 +1,150 @@
+/**
+ * Everything the Shell writes in the transaction that settles a Turn.
+ *
+ * Three policies share the kernel's one `terminalRecords` seam and none of them
+ * knows about the others: unread state advances for a conversational Turn, an
+ * automation Turn writes its completion-inbox entry and the pending input it
+ * hands off, and any Turn that asked for an approval writes the durable pending
+ * decision. The kernel writes the returned keys without reading them, so this
+ * is the only place their composition is decided.
+ *
+ * Two rules the composition itself has to keep, and they are why this is a
+ * function with a test rather than three spreads in a method body.
+ *
+ *  * **Each producer runs exactly once per settlement.** A settlement that ran
+ *    a producer twice would write two records where the Turn earned one — a
+ *    firing with two inbox entries, say — and the second would be invisible
+ *    until somebody counted.
+ *
+ *  * **No producer may silently overwrite another.** A spread lets a later key
+ *    clobber an earlier one with no sign; a collision here is a bug in the key
+ *    spaces two Packages chose, so it throws rather than picking a winner.
+ *
+ * One settlement also gets one `now`. Three producers each reading their own
+ * clock would stamp one transaction with three different instants.
+ */
+import {
+  advanceUnreadActivityV1,
+  optionalUnreadStateV1,
+  sidebarMessagePreviewForTurnV1,
+  SIDEBAR_PREVIEW_KEY,
+  UNREAD_STATE_KEY,
+} from "./unread.js";
+import { approvalTerminalRecordsV1 } from "./approvals.js";
+import { routineTerminalRecordsForRunV1 } from "./backend-routines.js";
+
+/** The settled run a terminal record set is computed from. */
+export interface ShellTerminalRunV1 {
+  runId: string;
+  sessionId: string;
+  acceptedAt: string;
+  input: string;
+  events: readonly { type: string }[];
+  responseText?: string;
+  admission?: {
+    turnType?: string;
+    // Wide on purpose: the kernel records one origin shape per producer, and
+    // this module only asks which producer it was.
+    origin?: { kind: string; routineId?: string };
+  };
+}
+
+export interface ShellTerminalInputV1 {
+  run: ShellTerminalRunV1;
+  /** The admission-index cursor the Turn was admitted under. */
+  cursor: string;
+  /** The one instant this settlement is stamped with. */
+  now: string;
+  /** Reader bound to the transaction that is settling the Turn. */
+  read<T>(key: string): Promise<T | undefined>;
+}
+
+/**
+ * The unread record — FrockBot's `lastTurnSettlement`. Activity advances
+ * whatever the Bot's notification policy says: muting silences the intent,
+ * never the badge. Only a chat Turn advances it; an automation Turn reaches
+ * the User through its own inbox entry.
+ */
+async function unreadRecordsV1(
+  input: ShellTerminalInputV1,
+): Promise<Record<string, unknown>> {
+  if ((input.run.admission?.turnType ?? "chat") !== "chat") return {};
+  const current = optionalUnreadStateV1(
+    await input.read<unknown>(UNREAD_STATE_KEY),
+  );
+  const next = advanceUnreadActivityV1(current, {
+    cursor: input.cursor,
+    at: input.now,
+  });
+  const preview = sidebarMessagePreviewForTurnV1(input.run, input.now);
+  return {
+    [UNREAD_STATE_KEY]: next,
+    // `advanceUnreadActivityV1` returns the current object for a replay or an
+    // older settlement. The preview follows that same monotonic decision, so
+    // recovery cannot replace a newer row with an older Turn.
+    ...(next === current || preview === undefined
+      ? {}
+      : { [SIDEBAR_PREVIEW_KEY]: preview }),
+  };
+}
+
+/**
+ * The completion-inbox entry and pending wake an automation Turn contributes.
+ * Nothing for a conversational one, so a chat Turn's settlement is
+ * byte-for-byte what it was before Routines existed.
+ */
+async function routineRecordsV1(
+  input: ShellTerminalInputV1,
+): Promise<Record<string, unknown>> {
+  const contributed = await routineTerminalRecordsForRunV1({
+    run: input.run,
+    read: input.read,
+    now: input.now,
+  });
+  return contributed?.records ?? {};
+}
+
+/**
+ * The pending decisions the Turn asked for. "A request for more becomes a
+ * durable pending decision for the User, never a grant": the card the User
+ * sees and the record their answer is written against become durable in one
+ * transaction, so there is no instant at which the question has been asked and
+ * the answer has nowhere to go.
+ */
+async function approvalRecordsV1(
+  input: ShellTerminalInputV1,
+): Promise<Record<string, unknown>> {
+  return approvalTerminalRecordsV1({
+    run: {
+      runId: input.run.runId,
+      sessionId: input.run.sessionId,
+      events: input.run.events,
+    },
+    now: input.now,
+    read: input.read,
+  });
+}
+
+/** The producers, in the order they are composed. Each is called once. */
+const SHELL_TERMINAL_PRODUCERS_V1 = [
+  unreadRecordsV1,
+  routineRecordsV1,
+  approvalRecordsV1,
+] as const;
+
+export async function shellTerminalRecordsV1(
+  input: ShellTerminalInputV1,
+): Promise<Record<string, unknown>> {
+  const records: Record<string, unknown> = {};
+  for (const produce of SHELL_TERMINAL_PRODUCERS_V1) {
+    for (const [key, value] of Object.entries(await produce(input))) {
+      if (Object.hasOwn(records, key)) {
+        throw new Error(
+          `two terminal-record producers both wrote "${key}"; one would have silently overwritten the other`,
+        );
+      }
+      records[key] = value;
+    }
+  }
+  return records;
+}

package/src/unread.test.ts

@@ -0,0 +1,362 @@
+import { describe, expect, test } from "bun:test";
+import {
+  advanceUnreadActivityV1,
+  botUnreadCommandFingerprintV1,
+  decodeSidebarMessagePreviewV1,
+  decodeBotNotificationDirectoryViewV1,
+  decodeBotUnreadCommandV1,
+  decodeBotUnreadDirectoryViewV1,
+  decodeUnreadStateV1,
+  emptyUnreadStateV1,
+  markUnreadReadV1,
+  markUnreadV1,
+  optionalUnreadStateV1,
+  projectBotUnreadViewV1,
+  sidebarMessagePreviewForTurnV1,
+  UNREAD_COUNT_CAP,
+  type UnreadStateV1,
+} from "./unread.js";
+
+/** A cursor in the exact shape the Bot's admission index writes. */
+function cursor(minute: number, runId = `run-${minute}`): string {
+  const at = new Date(Date.UTC(2026, 7, 31, 0, minute, 0)).toISOString();
+  return `run-index:${at}:${runId}`;
+}
+
+/** Newest-first, exactly as `listRunIndex` returns it. */
+function index(count: number): string[] {
+  return Array.from({ length: count }, (_, offset) => cursor(count - offset));
+}
+
+describe("the unread codec", () => {
+  test("accepts the empty record and a full one", () => {
+    expect(decodeUnreadStateV1(emptyUnreadStateV1())).toEqual({
+      schemaVersion: 1,
+      manuallyUnread: false,
+    });
+    const full: UnreadStateV1 = {
+      schemaVersion: 1,
+      lastActivityCursor: cursor(2),
+      lastActivityAt: "2026-08-31T00:02:00.000Z",
+      lastSeenCursor: cursor(1),
+      lastViewedAt: "2026-08-31T00:01:30.000Z",
+      manuallyUnread: true,
+    };
+    expect(decodeUnreadStateV1(full)).toEqual(full);
+  });
+
+  test("refuses anything that is not the record it claims to be", () => {
+    const base = emptyUnreadStateV1();
+    for (const invalid of [
+      undefined,
+      null,
+      [],
+      "unread",
+      { ...base, schemaVersion: 2 },
+      { ...base, manuallyUnread: "yes" },
+      { ...base, surprise: true },
+      { schemaVersion: 1 },
+      // A cursor that is not an admission-index key.
+      { ...base, lastSeenCursor: "yesterday", lastViewedAt: base.lastViewedAt },
+      { ...base, lastSeenCursor: cursor(1) },
+      { ...base, lastActivityAt: "2026-08-31T00:01:00.000Z" },
+      {
+        ...base,
+        lastActivityCursor: cursor(1),
+        lastActivityAt: "not-a-time",
+      },
+    ]) {
+      expect(() => decodeUnreadStateV1(invalid)).toThrow();
+    }
+  });
+
+  test("reads an absent record as the empty one", () => {
+    expect(optionalUnreadStateV1(undefined)).toEqual(emptyUnreadStateV1());
+    expect(() => optionalUnreadStateV1({ schemaVersion: 3 })).toThrow();
+  });
+});
+
+describe("the sidebar message preview", () => {
+  const preview = {
+    schemaVersion: 1 as const,
+    text: "Done",
+    at: "2026-08-31T00:02:00.000Z",
+    role: "assistant" as const,
+  };
+
+  test("decodes the exact bounded projection", () => {
+    expect(decodeSidebarMessagePreviewV1(preview)).toEqual(preview);
+    for (const invalid of [
+      { ...preview, extra: true },
+      { ...preview, text: "" },
+      { ...preview, text: "x".repeat(121) },
+      { ...preview, at: "yesterday" },
+      { ...preview, role: "system" },
+    ]) {
+      expect(() => decodeSidebarMessagePreviewV1(invalid)).toThrow();
+    }
+  });
+
+  test("prefers assistant text, falls back to the User, and bounds both", () => {
+    expect(
+      sidebarMessagePreviewForTurnV1(
+        {
+          acceptedAt: "2026-08-31T00:01:00.000Z",
+          input: "Question",
+          responseText: "Answer",
+        },
+        preview.at,
+      ),
+    ).toMatchObject({ text: "Answer", at: preview.at, role: "assistant" });
+    expect(
+      sidebarMessagePreviewForTurnV1(
+        {
+          acceptedAt: "2026-08-31T00:01:00.000Z",
+          input: "Q".repeat(140),
+          responseText: "",
+        },
+        preview.at,
+      ),
+    ).toMatchObject({
+      text: "Q".repeat(120),
+      at: "2026-08-31T00:01:00.000Z",
+      role: "user",
+    });
+  });
+});
+
+describe("unread transitions", () => {
+  test("activity is monotonic, so a re-settled Turn cannot move it", () => {
+    const first = advanceUnreadActivityV1(emptyUnreadStateV1(), {
+      cursor: cursor(2),
+      at: "2026-08-31T00:02:00.000Z",
+    });
+    // Recovery settling the same Turn again, and an older Turn arriving late.
+    const replayed = advanceUnreadActivityV1(first, {
+      cursor: cursor(2),
+      at: "2026-08-31T00:09:00.000Z",
+    });
+    expect(replayed).toEqual(first);
+    expect(
+      advanceUnreadActivityV1(first, {
+        cursor: cursor(1),
+        at: "2026-08-31T00:01:00.000Z",
+      }),
+    ).toEqual(first);
+    const later = advanceUnreadActivityV1(first, {
+      cursor: cursor(3),
+      at: "2026-08-31T00:03:00.000Z",
+    });
+    expect(later.lastActivityCursor).toBe(cursor(3));
+  });
+
+  test("mark-read takes the max, so out-of-order marks are safe", () => {
+    const read = markUnreadReadV1(emptyUnreadStateV1(), {
+      upToCursor: cursor(5),
+      at: "2026-08-31T00:05:00.000Z",
+    });
+    const stale = markUnreadReadV1(read, {
+      upToCursor: cursor(2),
+      at: "2026-08-31T00:02:00.000Z",
+    });
+    expect(stale.lastSeenCursor).toBe(cursor(5));
+    expect(stale.lastViewedAt).toBe("2026-08-31T00:05:00.000Z");
+    const newer = markUnreadReadV1(stale, {
+      upToCursor: cursor(7),
+      at: "2026-08-31T00:07:00.000Z",
+    });
+    expect(newer.lastSeenCursor).toBe(cursor(7));
+  });
+
+  test("a later mark-read clears manual unread", () => {
+    const marked = markUnreadV1(
+      markUnreadReadV1(emptyUnreadStateV1(), {
+        upToCursor: cursor(1),
+        at: "2026-08-31T00:01:00.000Z",
+      }),
+    );
+    expect(marked.manuallyUnread).toBe(true);
+    // Even a mark that moves no cursor: the User is looking at the thread.
+    const read = markUnreadReadV1(marked, {
+      upToCursor: cursor(1),
+      at: "2026-08-31T00:04:00.000Z",
+    });
+    expect(read).toMatchObject({
+      manuallyUnread: false,
+      lastSeenCursor: cursor(1),
+    });
+  });
+});
+
+describe("the unread projection", () => {
+  test("counts only settled chat Turns the User has not seen", () => {
+    const state: UnreadStateV1 = {
+      schemaVersion: 1,
+      lastActivityCursor: cursor(3),
+      lastActivityAt: "2026-08-31T00:03:00.000Z",
+      lastSeenCursor: cursor(1),
+      lastViewedAt: "2026-08-31T00:01:00.000Z",
+      manuallyUnread: false,
+    };
+    // Four admitted Turns; the newest has not settled, so it is not counted.
+    const view = projectBotUnreadViewV1("alpha", state, index(4));
+    expect(view).toMatchObject({ botId: "alpha", count: 2, unread: true });
+  });
+
+  test("a manual mark shows unread with no count", () => {
+    const view = projectBotUnreadViewV1(
+      "alpha",
+      markUnreadV1(emptyUnreadStateV1()),
+      [],
+    );
+    expect(view).toMatchObject({
+      count: 0,
+      unread: true,
+      manuallyUnread: true,
+    });
+  });
+
+  test("caps the count and says so", () => {
+    const entries = index(UNREAD_COUNT_CAP + 1);
+    const state = advanceUnreadActivityV1(emptyUnreadStateV1(), {
+      cursor: entries[0]!,
+      at: "2026-08-31T02:00:00.000Z",
+    });
+    const view = projectBotUnreadViewV1("alpha", state, entries);
+    expect(view).toMatchObject({ count: UNREAD_COUNT_CAP, capped: true });
+  });
+
+  test("nothing settled means nothing unread", () => {
+    const view = projectBotUnreadViewV1(
+      "alpha",
+      emptyUnreadStateV1(),
+      index(3),
+    );
+    expect(view).toMatchObject({ count: 0, capped: false, unread: false });
+  });
+
+  test("carries the already-bounded latest message without deriving it", () => {
+    const preview = decodeSidebarMessagePreviewV1({
+      schemaVersion: 1,
+      text: "Latest answer",
+      at: "2026-08-31T00:03:00.000Z",
+      role: "assistant",
+    });
+    const projected = projectBotUnreadViewV1(
+      "alpha",
+      emptyUnreadStateV1(),
+      [],
+      preview,
+    );
+    expect(
+      decodeBotUnreadDirectoryViewV1({
+        schemaVersion: 1,
+        unread: [projected],
+      }).unread[0]?.lastMessage,
+    ).toEqual(preview);
+    expect(() =>
+      decodeBotUnreadDirectoryViewV1({
+        schemaVersion: 1,
+        unread: [{ ...projected, lastMessage: { ...preview, extra: true } }],
+      }),
+    ).toThrow();
+  });
+});
+
+describe("the unread command", () => {
+  test("decodes each type and refuses a mismatched cursor", () => {
+    expect(
+      decodeBotUnreadCommandV1({
+        schemaVersion: 1,
+        type: "bot/mark-read",
+        commandId: "mark-1",
+        botId: "alpha",
+        upToCursor: cursor(1),
+      }),
+    ).toMatchObject({ type: "bot/mark-read", upToCursor: cursor(1) });
+    expect(
+      decodeBotUnreadCommandV1({
+        schemaVersion: 1,
+        type: "bot/mark-unread",
+        commandId: "mark-2",
+        botId: "alpha",
+      }),
+    ).toMatchObject({ type: "bot/mark-unread" });
+    for (const invalid of [
+      // mark-read with no cursor, mark-unread with one.
+      {
+        schemaVersion: 1,
+        type: "bot/mark-read",
+        commandId: "mark-3",
+        botId: "alpha",
+      },
+      {
+        schemaVersion: 1,
+        type: "bot/mark-unread",
+        commandId: "mark-4",
+        botId: "alpha",
+        upToCursor: cursor(1),
+      },
+      {
+        schemaVersion: 1,
+        type: "bot/archive",
+        commandId: "mark-5",
+        botId: "alpha",
+      },
+    ]) {
+      expect(() => decodeBotUnreadCommandV1(invalid)).toThrow();
+    }
+  });
+
+  test("fingerprints the meaning, not the command id", () => {
+    const command = decodeBotUnreadCommandV1({
+      schemaVersion: 1,
+      type: "bot/mark-read",
+      commandId: "mark-1",
+      botId: "alpha",
+      upToCursor: cursor(1),
+    });
+    expect(botUnreadCommandFingerprintV1(command)).toBe(
+      botUnreadCommandFingerprintV1({ ...command, commandId: "mark-2" }),
+    );
+    expect(botUnreadCommandFingerprintV1(command)).not.toBe(
+      botUnreadCommandFingerprintV1({ ...command, upToCursor: cursor(2) }),
+    );
+  });
+});
+
+describe("the fan-out views", () => {
+  test("decode exactly what the routes answer", () => {
+    expect(
+      decodeBotUnreadDirectoryViewV1({
+        schemaVersion: 1,
+        unread: [projectBotUnreadViewV1("alpha", emptyUnreadStateV1(), [])],
+      }).unread,
+    ).toHaveLength(1);
+    expect(() =>
+      decodeBotUnreadDirectoryViewV1({ schemaVersion: 1, unread: [{}] }),
+    ).toThrow();
+    expect(
+      decodeBotNotificationDirectoryViewV1({
+        schemaVersion: 1,
+        notifications: [
+          {
+            schemaVersion: 1,
+            botId: "alpha",
+            notificationId: "run-1",
+            runId: "run-1",
+            createdAt: "2026-08-31T00:01:00.000Z",
+            title: "Alpha replied",
+            body: "hello",
+          },
+        ],
+      }).notifications,
+    ).toHaveLength(1);
+    expect(() =>
+      decodeBotNotificationDirectoryViewV1({
+        schemaVersion: 1,
+        notifications: [{ schemaVersion: 1, botId: "alpha" }],
+      }),
+    ).toThrow();
+  });
+});