@frockbot/plugin-flock 0.3.11 → 0.3.13

package/src/client/delivered-notifications.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import {
+  claimNotificationDeliveryV1,
+  deliveredNotificationKeyV1,
+  DELIVERED_NOTIFICATIONS_KEY,
+  DELIVERED_NOTIFICATIONS_LIMIT,
+  releaseNotificationDeliveryV1,
+} from "./delivered-notifications.js";
+
+/** The half of `localStorage` the ledger uses, shared as a browser shares it. */
+function storage(initial?: string): Pick<Storage, "getItem" | "setItem"> {
+  const values = new Map<string, string>(
+    initial === undefined ? [] : [[DELIVERED_NOTIFICATIONS_KEY, initial]],
+  );
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => {
+      values.set(key, value);
+    },
+  };
+}
+
+describe("the delivered-notification ledger", () => {
+  test("the first claim wins and every later one loses", () => {
+    const shared = storage();
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(false);
+    // A second tab reads the same storage, so it loses too — which is the
+    // whole point: one notification per message, not one per tab.
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(false);
+    // A different message is still news.
+    expect(
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1("beta", "run-2"),
+        shared,
+      ),
+    ).toBe(true);
+  });
+
+  test("a claim survives the reload that empties the page's own set", () => {
+    const values = new Map<string, string>();
+    const persistent = (): Pick<Storage, "getItem" | "setItem"> => ({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+    });
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, persistent())).toBe(true);
+    // A brand-new page, the same browser.
+    expect(claimNotificationDeliveryV1(key, persistent())).toBe(false);
+  });
+
+  test("a notification that could not be shown gives its claim back", () => {
+    const shared = storage();
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+    releaseNotificationDeliveryV1(key, shared);
+    expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+  });
+
+  test("the ledger is bounded, oldest first", () => {
+    const shared = storage();
+    for (let index = 0; index <= DELIVERED_NOTIFICATIONS_LIMIT; index += 1) {
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1("beta", `run-${index}`),
+        shared,
+      );
+    }
+    // The oldest fell off; the newest is still remembered.
+    expect(
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1("beta", "run-0"),
+        shared,
+      ),
+    ).toBe(true);
+    expect(
+      claimNotificationDeliveryV1(
+        deliveredNotificationKeyV1(
+          "beta",
+          `run-${DELIVERED_NOTIFICATIONS_LIMIT}`,
+        ),
+        shared,
+      ),
+    ).toBe(false);
+  });
+
+  test("junk in storage is not a reason to go silent", () => {
+    for (const junk of ["", "{", "null", '{"not":"an array"}', "[1,2,3]"]) {
+      const key = deliveredNotificationKeyV1("beta", "run-1");
+      const shared = storage(junk);
+      expect(claimNotificationDeliveryV1(key, shared)).toBe(true);
+      expect(claimNotificationDeliveryV1(key, shared)).toBe(false);
+    }
+  });
+
+  test("no storage at all still shows the notification", () => {
+    const key = deliveredNotificationKeyV1("beta", "run-1");
+    expect(claimNotificationDeliveryV1(key, undefined)).toBe(true);
+    expect(claimNotificationDeliveryV1(key, undefined)).toBe(true);
+  });
+});

package/src/client/delivered-notifications.ts

@@ -0,0 +1,100 @@
+/**
+ * Which notification intents this browser has already shown.
+ *
+ * "One notification per message" is a promise about the *person*, not about
+ * the page. The durable acknowledgement the Bot records is what closes an
+ * intent, but it lands after the notification is shown, and in that window a
+ * second tab polling the same fan-out — or the same tab after a reload —
+ * showed the identical intent again. A set on the page could not see either.
+ *
+ * `localStorage` can, because both tabs of one browser share it. It is a
+ * ledger of ids, never of content: an id already here is one this browser has
+ * spoken. It is bounded and oldest-first, so a long-lived session cannot grow
+ * it without limit; an id that falls off the end is one whose acknowledgement
+ * settled long ago.
+ */
+
+export const DELIVERED_NOTIFICATIONS_KEY =
+  "frockbot.flock.delivered-notifications.v1";
+
+/** How many ids one browser remembers. Comfortably past any in-flight burst. */
+export const DELIVERED_NOTIFICATIONS_LIMIT = 200;
+
+type WritableStorage = Pick<Storage, "getItem" | "setItem">;
+
+function browserStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === "undefined" ? undefined : localStorage;
+  } catch {
+    // A browser with storage denied still shows notifications; it only loses
+    // the cross-tab half of the promise.
+    return undefined;
+  }
+}
+
+/** The key one intent is remembered under. */
+export function deliveredNotificationKeyV1(
+  botId: string,
+  notificationId: string,
+): string {
+  return `${botId}:${notificationId}`;
+}
+
+function parse(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const value: unknown = JSON.parse(raw);
+    return Array.isArray(value)
+      ? value.filter((entry): entry is string => typeof entry === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Claims the right to show the intent behind `key`, returning `false` when
+ * some other tab — or this one, before a reload — already has it.
+ *
+ * Check-and-write in one call, and the write happens *before* the notification
+ * is shown, because the gap between showing and recording is exactly where the
+ * duplicate got in.
+ */
+export function claimNotificationDeliveryV1(
+  key: string,
+  storage: WritableStorage | undefined = browserStorage(),
+): boolean {
+  if (!storage) return true;
+  try {
+    const existing = parse(storage.getItem(DELIVERED_NOTIFICATIONS_KEY));
+    if (existing.includes(key)) return false;
+    const next = [...existing, key].slice(-DELIVERED_NOTIFICATIONS_LIMIT);
+    storage.setItem(DELIVERED_NOTIFICATIONS_KEY, JSON.stringify(next));
+    return true;
+  } catch {
+    // Storage that will not take the ledger must not silence the notification.
+    return true;
+  }
+}
+
+/**
+ * Gives a claim back, for the one case where the notification was never
+ * actually shown: no permission yet. Without this the intent would be
+ * remembered as spoken and stay silent after the User granted it.
+ */
+export function releaseNotificationDeliveryV1(
+  key: string,
+  storage: WritableStorage | undefined = browserStorage(),
+): void {
+  if (!storage) return;
+  try {
+    const existing = parse(storage.getItem(DELIVERED_NOTIFICATIONS_KEY));
+    if (!existing.includes(key)) return;
+    storage.setItem(
+      DELIVERED_NOTIFICATIONS_KEY,
+      JSON.stringify(existing.filter((entry) => entry !== key)),
+    );
+  } catch {
+    // Nothing to undo that anybody can see.
+  }
+}

package/src/client/index.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import type { ClientPluginContext } from "@frockbot/client-core";
 import type { FrockBotWebData } from "@frockbot/plugin-shell/shared";
-import { ref, type Ref } from "vue";
+import { nextTick, ref, type Ref } from "vue";
 import { randomSheepRecipeV1 } from "../shared.js";
 import { flockClientPlugin } from "./index.js";
 import { pendingCreateKey, pendingSheepKey } from "./pending-create.js";
@@ -281,7 +281,8 @@ describe("Flock client reconciliation", () => {
 
     await state.value.load();
 
-    expect(state.value.error).toBe("Directory changed");
+    // The sidebar says what failed, not what the deployment called it.
+    expect(state.value.error).toBe("Couldn't load your Bots.");
     expect(storage.has(pendingCreateKey("user-a"))).toBe(false);
   });
 
@@ -410,6 +411,114 @@ describe("Flock client reconciliation", () => {
     expect(state.value.directory.bots).toEqual([]);
   });
 
+  test("deletes with confirmation and drops the Bot from the list", async () => {
+    installStorage();
+    const location = { href: "https://app.example/?bot=alpha" };
+    Object.defineProperty(globalThis, "window", {
+      configurable: true,
+      value: {
+        location,
+        history: {
+          state: null,
+          replaceState: (_state: unknown, _title: string, url: URL) => {
+            location.href = url.href;
+          },
+        },
+      },
+    });
+    const sheep = randomSheepRecipeV1(() => 0);
+    // A deleted Bot leaves the directory outright, unlike an archived one.
+    let bots = ["alpha", "beta"];
+    let deleteCommands = 0;
+    const state = mount((path, method, body) => {
+      if (path === "/api/bots/identities")
+        return Promise.resolve({ schemaVersion: 1, identities: [] });
+      if (path === "/api/bots/alpha/lifecycle" && method === "POST") {
+        const command = JSON.parse(body ?? "") as {
+          commandId: string;
+          botId: string;
+          type: string;
+        };
+        expect(command.type).toBe("bot/delete");
+        deleteCommands += 1;
+        bots = bots.filter((botId) => botId !== "alpha");
+        return Promise.resolve({
+          schemaVersion: 1,
+          commandId: command.commandId,
+          botId: command.botId,
+          status: "applied",
+          lifecycle: {
+            schemaVersion: 1,
+            botId: command.botId,
+            status: "deleted",
+            revision: 1,
+          },
+        });
+      }
+      if (path === "/api/bots")
+        return Promise.resolve({
+          schemaVersion: 1,
+          revision: 3,
+          bots: bots.map((botId) => ({
+            schemaVersion: 1,
+            botId,
+            registeredAt: new Date(0).toISOString(),
+            initialName: botId,
+            sheep,
+          })),
+        });
+      if (path === "/api/bots/lifecycles")
+        return Promise.resolve({
+          schemaVersion: 1,
+          lifecycles: bots.map((botId) => ({
+            schemaVersion: 1,
+            botId,
+            status: "active",
+            revision: 0,
+          })),
+        });
+      if (path.endsWith("/sheep")) {
+        const botId = path.split("/")[3]!;
+        return Promise.resolve({ schemaVersion: 1, botId, revision: 0, sheep });
+      }
+      return Promise.reject(new Error(`unexpected request: ${path}`));
+    });
+    const selected: string[] = [];
+    const forgotten: (string | undefined)[] = [];
+    state.value.bindShell(
+      ref({
+        activeBotId: "alpha",
+        selectBot: (botId: string) => {
+          selected.push(botId);
+          return Promise.resolve();
+        },
+        transcripts: {
+          rememberViewport: () => undefined,
+          viewportFor: () => undefined,
+          forget: (botId?: string) => forgotten.push(botId),
+        },
+      }) as unknown as Ref<FrockBotWebData>,
+    );
+    await state.value.load();
+    state.value.openDelete("alpha");
+    expect(state.value.overlay).toBe("delete");
+    expect(state.value.lifecyclePending).toBe("alpha");
+    await state.value.deleteBot();
+    expect(deleteCommands).toBe(1);
+    expect(state.value.overlay).toBeUndefined();
+    expect(state.value.directory.bots.map((bot) => bot.botId)).toEqual([
+      "beta",
+    ]);
+    expect(selected.at(-1)).toBe("beta");
+    expect(new URL(location.href).searchParams.get("bot")).toBe("beta");
+    // The held transcript goes with the Bot: unlike an archive, there is no
+    // Bot left to read it back from.
+    expect(forgotten).toEqual(["alpha"]);
+    // A Bot that is no longer in the directory cannot be confirmed for delete.
+    state.value.openDelete("alpha");
+    expect(state.value.overlay).toBeUndefined();
+  });
+
   test("archives with confirmation, hides archived Bots, and selects a fallback", async () => {
     installStorage();
     const location = { href: "https://app.example/?bot=alpha" };
@@ -481,6 +590,7 @@ describe("Flock client reconciliation", () => {
       return Promise.reject(new Error(`unexpected request: ${path}`));
     });
     const selected: string[] = [];
+    const forgotten: (string | undefined)[] = [];
     state.value.bindShell(
       ref({
         activeBotId: "alpha",
@@ -488,6 +598,11 @@ describe("Flock client reconciliation", () => {
           selected.push(botId);
           return Promise.resolve();
         },
+        transcripts: {
+          rememberViewport: () => undefined,
+          viewportFor: () => undefined,
+          forget: (botId?: string) => forgotten.push(botId),
+        },
       }) as unknown as Ref<FrockBotWebData>,
     );
     state.value.openArchive("alpha");
@@ -496,6 +611,9 @@ describe("Flock client reconciliation", () => {
     expect(state.value.lifecycles.alpha).toBe("archived");
     expect(selected.at(-1)).toBe("beta");
     expect(new URL(location.href).searchParams.get("bot")).toBe("beta");
+    // The archived Bot's held transcript goes with it, so restoring it later
+    // reads from the Bot rather than redrawing what the cache still had.
+    expect(forgotten).toEqual(["alpha"]);
   });
 
   test("reconciles a lost sheep response and clears the exact pending command", async () => {
@@ -532,3 +650,88 @@ describe("Flock client reconciliation", () => {
     expect(storage.has(pendingSheepKey("user-a", "alpha"))).toBe(false);
   });
 });
+
+describe("Flock sidebar rows follow the transcript", () => {
+  test("a settled Turn updates the row without waiting for the poll", async () => {
+    installStorage();
+    const reads: string[] = [];
+    let reply: string | undefined;
+    const state = mount((path) => {
+      if (path !== "/api/bots/unread")
+        return Promise.reject(new Error(`unexpected request: ${path}`));
+      reads.push(path);
+      return Promise.resolve({
+        schemaVersion: 1,
+        unread: [
+          {
+            schemaVersion: 1,
+            botId: "alpha",
+            count: 0,
+            capped: false,
+            unread: false,
+            manuallyUnread: false,
+            ...(reply === undefined
+              ? {}
+              : {
+                  lastMessage: {
+                    schemaVersion: 1,
+                    text: reply,
+                    at: "2026-08-31T00:00:01.000Z",
+                    role: "assistant",
+                  },
+                }),
+          },
+        ],
+      });
+    });
+    const shell = ref({
+      activeBotId: "alpha",
+      activeRunId: "run-1",
+      messages: [
+        {
+          id: "m1",
+          runId: "run-1",
+          role: "user",
+          text: "hello",
+          status: "completed",
+        },
+      ],
+    } as unknown as FrockBotWebData);
+    state.value.bindShell(shell as unknown as Ref<FrockBotWebData>);
+    // Binding a Shell is not itself a beat: nothing has settled, so nothing is
+    // re-read.
+    await nextTick();
+    expect(reads).toHaveLength(0);
+    expect(state.value.unread.alpha).toBeUndefined();
+
+    // The Turn settles: its reply is in the transcript, no run is in flight.
+    reply = "Ollama reply";
+    shell.value = {
+      ...shell.value,
+      activeRunId: undefined,
+      messages: [
+        ...shell.value.messages,
+        {
+          id: "m2",
+          runId: "run-1",
+          role: "assistant",
+          text: reply,
+          status: "completed",
+        },
+      ],
+    } as unknown as FrockBotWebData;
+    await nextTick();
+    // Draining the read the watcher started. A rendered frame does this on its
+    // own; the claim under test is that no 15-second poll was involved.
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(reads).toHaveLength(1);
+    expect(state.value.unread.alpha?.lastMessage).toMatchObject({
+      text: "Ollama reply",
+      at: "2026-08-31T00:00:01.000Z",
+      role: "assistant",
+    });
+  });
+});

package/src/client/state.ts

@@ -24,12 +24,14 @@ export interface FlockWebData {
    * Whether a directory read has ever completed.
    *
    * "No Bots yet." is a fact about the User's account, and it can only be
-   * stated once the account has been read. Before that — the first paint, and
-   * the reload after a Bot is created — the list is unknown, not empty.
+   * stated once the account has been read. Before that — the first paint, the
+   * reload after a Bot is created, and every read that failed — the list is
+   * unknown, not empty, and offering to create a first Bot to someone who
+   * already has several is the worst thing this column can say.
    */
   loaded: boolean;
   error?: string;
-  overlay?: "create" | "edit" | "archive";
+  overlay?: "create" | "edit" | "archive" | "delete";
   lifecycles: Record<string, BotLifecycleStatusV1>;
   showArchived: boolean;
   lifecyclePending?: string;
@@ -50,6 +52,9 @@ export interface FlockWebData {
   toggleHidden(): void;
   openArchive(botId: string): void;
   archive(): Promise<void>;
+  /** Confirmation first: deleting a Bot destroys its chat history. */
+  openDelete(botId: string): void;
+  deleteBot(): Promise<void>;
   restore(botId: string): Promise<void>;
   closeOverlay(): void;
   reroll(): void;

package/src/client/styles.css

@@ -70,6 +70,11 @@
   color: var(--frock-text);
 }
 
+.flock-lifecycle--danger,
+.flock-lifecycle--danger:hover {
+  color: var(--frock-danger-text);
+}
+
 /*
  * Pinned Bots. A wrapping row of large round tiles above the labelled groups,
  * each one a whole Bot rather than a line of text about it.
@@ -357,6 +362,24 @@
   color: var(--frock-danger-text);
 }
 
+/* The way to try the read again, beside the sentence that says it failed. */
+.flock-retry {
+  display: inline-block;
+  margin-top: 6px;
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-control);
+  background: transparent;
+  color: var(--frock-text);
+  padding: 2px 8px;
+  font: inherit;
+  font-size: var(--frock-text-xs);
+  cursor: pointer;
+}
+
+.flock-retry:hover {
+  background: var(--frock-fill-hover);
+}
+
 /* Header identity */
 
 .flock-identity-button {
@@ -606,6 +629,17 @@
   background: var(--frock-action-primary-pressed);
 }
 
+/* The one irreversible action in this dialog set, and it says so. */
+.flock-actions .danger {
+  border-color: var(--frock-danger-strong);
+  background: var(--frock-danger-strong);
+  color: var(--frock-on-accent);
+}
+
+.flock-actions .danger:hover {
+  background: var(--frock-danger-text);
+}
+
 @media (max-width: 600px) {
   .flock-backdrop {
     padding: 10px;

package/src/shared.test.ts

@@ -4,11 +4,13 @@ import {
   decodeBotIdentityViewV1,
   decodeBotLifecycleCommandV1,
   decodeBotLifecycleReceiptV1,
+  decodeBotLifecycleViewV1,
   decodeBotMembershipViewV1,
   decodeBotRegistrationV1,
   decodeCreateBotCommandV1,
   decodeDirectoryViewV1,
   decodeSheepRecipeV1,
+  lifecycleTargetStatusV1,
   migrateStoredBotDirectoryV1,
   randomSheepRecipeV1,
   sheepCatalog,
@@ -38,6 +40,45 @@ describe("Flock v1 contracts", () => {
     ).toThrow("unknown or missing field");
   });
 
+  test("strictly decodes the delete command and its terminal status", () => {
+    const command = {
+      schemaVersion: 1 as const,
+      type: "bot/delete" as const,
+      commandId: "delete-1",
+      botId: "alpha",
+    };
+    expect(decodeBotLifecycleCommandV1(command)).toEqual(command);
+    expect(lifecycleTargetStatusV1("bot/delete")).toBe("deleted");
+    expect(lifecycleTargetStatusV1("bot/archive")).toBe("archived");
+    expect(lifecycleTargetStatusV1("bot/restore")).toBe("active");
+    expect(
+      decodeBotLifecycleReceiptV1({
+        schemaVersion: 1,
+        commandId: "delete-1",
+        botId: "alpha",
+        status: "applied",
+        lifecycle: {
+          schemaVersion: 1,
+          botId: "alpha",
+          status: "deleted",
+          revision: 1,
+        },
+      }),
+    ).toMatchObject({ lifecycle: { status: "deleted" } });
+    // A near-miss is still a rejection: the union is exact, not prefixed.
+    expect(() =>
+      decodeBotLifecycleCommandV1({ ...command, type: "bot/delete-all" }),
+    ).toThrow("unsupported Bot lifecycle command");
+    expect(() =>
+      decodeBotLifecycleViewV1({
+        schemaVersion: 1,
+        botId: "alpha",
+        status: "removed",
+        revision: 1,
+      }),
+    ).toThrow("Bot lifecycle is invalid");
+  });
+
   test("strictly decodes archive and restore DTOs", () => {
     const command = {
       schemaVersion: 1 as const,

package/src/shared.ts

@@ -52,7 +52,12 @@ export interface BotDirectoryViewV1 {
   revision: number;
   bots: BotRegistrationV1[];
 }
-export type BotLifecycleStatusV1 = "active" | "archived";
+/**
+ * A Bot's durable lifecycle. `deleted` is terminal: the Bot and its chat
+ * history are gone, and the status survives only as a tombstone so a late
+ * command or Turn is refused rather than resurrecting the Bot.
+ */
+export type BotLifecycleStatusV1 = "active" | "archived" | "deleted";
 export interface BotLifecycleViewV1 {
   schemaVersion: 1;
   botId: string;
@@ -65,7 +70,7 @@ export interface BotLifecycleDirectoryViewV1 {
 }
 export interface BotLifecycleCommandV1 {
   schemaVersion: 1;
-  type: "bot/archive" | "bot/restore";
+  type: "bot/archive" | "bot/restore" | "bot/delete";
   commandId: string;
   botId: string;
 }
@@ -162,6 +167,19 @@ export class FlockConflictError extends Error {
     this.name = "FlockConflictError";
   }
 }
+/**
+ * The status a lifecycle command settles on. The saga on the User side and the
+ * Bot Durable Object both read the target from here rather than each writing
+ * out the same mapping.
+ */
+export function lifecycleTargetStatusV1(
+  type: BotLifecycleCommandV1["type"],
+): BotLifecycleStatusV1 {
+  if (type === "bot/archive") return "archived";
+  if (type === "bot/delete") return "deleted";
+  return "active";
+}
+
 export class BotNotFoundError extends Error {
   constructor(readonly botId: string) {
     super(`Bot "${botId}" is not registered`);
@@ -456,7 +474,9 @@ export function decodeBotLifecycleCommandV1(
   exact(value, ["schemaVersion", "type", "commandId", "botId"]);
   if (
     value.schemaVersion !== 1 ||
-    (value.type !== "bot/archive" && value.type !== "bot/restore")
+    (value.type !== "bot/archive" &&
+      value.type !== "bot/restore" &&
+      value.type !== "bot/delete")
   )
     throw new FlockDecodeError("unsupported Bot lifecycle command");
   return {
@@ -472,7 +492,9 @@ export function decodeBotLifecycleViewV1(input: unknown): BotLifecycleViewV1 {
   exact(value, ["schemaVersion", "botId", "status", "revision"]);
   if (
     value.schemaVersion !== 1 ||
-    (value.status !== "active" && value.status !== "archived")
+    (value.status !== "active" &&
+      value.status !== "archived" &&
+      value.status !== "deleted")
   )
     throw new FlockDecodeError("Bot lifecycle is invalid");
   return {