@frockbot/plugin-shell 0.3.11 → 0.3.13

package/src/focus.test.ts

@@ -0,0 +1,222 @@
+// The rule the User stated, checked as arithmetic:
+//
+//   "This is one notification per message for a bot that is out of focus. If I
+//    have the bot open then that shouldn't raise a notification (or a badge on
+//    the list of bots). And when I open a chat that should clear the badge."
+//
+// Everything here composes the real durable pieces — `advanceUnreadActivityV1`
+// for a settled Turn, `projectBotUnreadViewV1` for the count, `markUnreadReadV1`
+// for the read receipt — with the focus rule on top, so a change to either side
+// has to keep the sentence true rather than only its own unit test.
+import { describe, expect, test } from "bun:test";
+import {
+  isBotFocusedV1,
+  readViewerFocusV1,
+  shouldNotifyForBotV1,
+  suppressUnreadWhileFocusedV1,
+  type ViewerFocusV1,
+} from "./focus.js";
+import {
+  advanceUnreadActivityV1,
+  emptyUnreadStateV1,
+  markUnreadReadV1,
+  projectBotUnreadViewV1,
+  type BotUnreadViewV1,
+  type UnreadStateV1,
+} from "./unread.js";
+
+const BOT = "alpha";
+const OTHER = "beta";
+
+/** A cursor in the exact shape the Bot's admission index writes. */
+function cursor(minute: number): string {
+  const at = new Date(Date.UTC(2026, 8, 4, 0, minute, 0)).toISOString();
+  return `run-index:${at}:run-${minute}`;
+}
+
+function at(minute: number): string {
+  return new Date(Date.UTC(2026, 8, 4, 0, minute, 0)).toISOString();
+}
+
+/** Newest-first, exactly as the Bot's run index returns it. */
+function index(minutes: readonly number[]): string[] {
+  return [...minutes].sort((a, b) => b - a).map(cursor);
+}
+
+/** One settled chat Turn landing on the Bot's durable unread record. */
+function settle(state: UnreadStateV1, minute: number): UnreadStateV1 {
+  return advanceUnreadActivityV1(state, {
+    cursor: cursor(minute),
+    at: at(minute),
+  });
+}
+
+/**
+ * What the sidebar actually renders for a Bot: the Durable Object's own
+ * projection, with the focus rule applied by the client that knows which chat
+ * is on screen.
+ */
+function rowFor(
+  state: UnreadStateV1,
+  minutes: readonly number[],
+  focus: ViewerFocusV1,
+  botId = BOT,
+): BotUnreadViewV1 {
+  const view = projectBotUnreadViewV1(botId, state, index(minutes));
+  return isBotFocusedV1(focus, botId)
+    ? suppressUnreadWhileFocusedV1(view)
+    : view;
+}
+
+const OPEN_AND_LOOKING: ViewerFocusV1 = {
+  activeBotId: BOT,
+  visible: true,
+  focused: true,
+};
+
+describe("what counts as focused", () => {
+  test("all three, and nothing less", () => {
+    expect(isBotFocusedV1(OPEN_AND_LOOKING, BOT)).toBe(true);
+    // A different chat is open.
+    expect(isBotFocusedV1(OPEN_AND_LOOKING, OTHER)).toBe(false);
+    expect(isBotFocusedV1({ visible: true, focused: true }, BOT)).toBe(false);
+    // The chat is open in a tab nobody can see.
+    expect(isBotFocusedV1({ ...OPEN_AND_LOOKING, visible: false }, BOT)).toBe(
+      false,
+    );
+    // Visible, but behind another window.
+    expect(isBotFocusedV1({ ...OPEN_AND_LOOKING, focused: false }, BOT)).toBe(
+      false,
+    );
+  });
+
+  test("notifying is exactly the inverse", () => {
+    for (const focus of [
+      OPEN_AND_LOOKING,
+      { ...OPEN_AND_LOOKING, visible: false },
+      { ...OPEN_AND_LOOKING, focused: false },
+      { visible: true, focused: true },
+    ] satisfies ViewerFocusV1[]) {
+      for (const botId of [BOT, OTHER]) {
+        expect(shouldNotifyForBotV1(focus, botId)).toBe(
+          !isBotFocusedV1(focus, botId),
+        );
+      }
+    }
+  });
+
+  test("a document that cannot be read is not a focused one", () => {
+    // Bun has no DOM: the reader answers for the environment it is in rather
+    // than assuming the User is watching.
+    expect(readViewerFocusV1(BOT)).toEqual({
+      activeBotId: BOT,
+      visible: false,
+      focused: false,
+    });
+    expect(readViewerFocusV1()).toEqual({ visible: false, focused: false });
+  });
+});
+
+describe("a message while the Bot is focused", () => {
+  test("raises no notification and no badge", () => {
+    const state = settle(emptyUnreadStateV1(), 1);
+    expect(shouldNotifyForBotV1(OPEN_AND_LOOKING, BOT)).toBe(false);
+    expect(rowFor(state, [1], OPEN_AND_LOOKING)).toMatchObject({
+      count: 0,
+      capped: false,
+      unread: false,
+    });
+  });
+
+  test("and neither does the tenth one", () => {
+    let state = emptyUnreadStateV1();
+    for (const minute of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) {
+      state = settle(state, minute);
+      expect(
+        rowFor(state, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], OPEN_AND_LOOKING),
+      ).toMatchObject({ count: 0, unread: false });
+    }
+  });
+
+  test("but a Bot the User marked unread on purpose stays bold", () => {
+    // Intent is not arithmetic: suppression clears a count, never a decision.
+    const state = { ...settle(emptyUnreadStateV1(), 1), manuallyUnread: true };
+    expect(rowFor(state, [1], OPEN_AND_LOOKING)).toMatchObject({
+      unread: true,
+      manuallyUnread: true,
+    });
+  });
+});
+
+describe("a message while the Bot is not focused", () => {
+  test("is one badge per message, not one per burst", () => {
+    let state = emptyUnreadStateV1();
+    const away: ViewerFocusV1 = { ...OPEN_AND_LOOKING, activeBotId: OTHER };
+    const settled: number[] = [];
+    const counts: number[] = [];
+    for (const minute of [1, 2, 3]) {
+      settled.push(minute);
+      state = settle(state, minute);
+      counts.push(rowFor(state, settled, away).count);
+    }
+    expect(counts).toEqual([1, 2, 3]);
+  });
+
+  test("counts for the open chat too when the tab is hidden", () => {
+    const state = settle(settle(emptyUnreadStateV1(), 1), 2);
+    const backgrounded = { ...OPEN_AND_LOOKING, visible: false };
+    expect(shouldNotifyForBotV1(backgrounded, BOT)).toBe(true);
+    expect(rowFor(state, [1, 2], backgrounded)).toMatchObject({
+      count: 2,
+      unread: true,
+    });
+  });
+
+  test("and when the window is behind another one", () => {
+    const state = settle(emptyUnreadStateV1(), 1);
+    const behind = { ...OPEN_AND_LOOKING, focused: false };
+    expect(shouldNotifyForBotV1(behind, BOT)).toBe(true);
+    expect(rowFor(state, [1], behind)).toMatchObject({ count: 1 });
+  });
+});
+
+describe("opening the chat", () => {
+  test("clears the badge, and it stays clear for the next message read there", () => {
+    let state = settle(settle(emptyUnreadStateV1(), 1), 2);
+    const away = { ...OPEN_AND_LOOKING, activeBotId: OTHER };
+    expect(rowFor(state, [1, 2], away).count).toBe(2);
+
+    // Opening is the authenticated read receipt, up to the cursor the fan-out
+    // named. Nothing about focus is stored: the durable record is a cursor.
+    const opened = projectBotUnreadViewV1(BOT, state, index([1, 2]));
+    state = markUnreadReadV1(state, {
+      upToCursor: opened.lastActivityCursor ?? cursor(2),
+      at: at(3),
+    });
+    expect(rowFor(state, [1, 2], OPEN_AND_LOOKING).count).toBe(0);
+    // Durable, not remembered: the same record read by any other tab is 0 too.
+    expect(projectBotUnreadViewV1(BOT, state, index([1, 2]))).toMatchObject({
+      count: 0,
+      unread: false,
+    });
+
+    // A reply that arrives while the chat is open and read renders nothing,
+    // and the receipt that follows keeps it that way after the tab is closed.
+    state = settle(state, 4);
+    expect(rowFor(state, [1, 2, 4], OPEN_AND_LOOKING).count).toBe(0);
+    state = markUnreadReadV1(state, { upToCursor: cursor(4), at: at(5) });
+    expect(projectBotUnreadViewV1(BOT, state, index([1, 2, 4]))).toMatchObject({
+      count: 0,
+      unread: false,
+    });
+  });
+
+  test("clears a manual unread as well", () => {
+    let state = { ...settle(emptyUnreadStateV1(), 1), manuallyUnread: true };
+    state = markUnreadReadV1(state, { upToCursor: cursor(1), at: at(2) });
+    expect(rowFor(state, [1], OPEN_AND_LOOKING)).toMatchObject({
+      unread: false,
+      manuallyUnread: false,
+    });
+  });
+});

package/src/focus.ts

@@ -0,0 +1,93 @@
+/**
+ * One definition of "focused", shared by every surface that has to decide
+ * whether a Bot's message is something the User is already looking at.
+ *
+ * The rule, stated once so the Shell and the Flock sidebar cannot drift:
+ *
+ * > A Bot is **focused** when its chat is the open one, the tab is visible,
+ * > and the window holds focus.
+ *
+ * All three, because each one on its own gets a case wrong. Only the open Bot
+ * is being read, so another Bot's reply is news however attentive the User is.
+ * A tab in the background is not being read even though its chat is still
+ * "open" — `document.visibilityState` is what says so. And a visible tab
+ * behind another window is not being read either, which only
+ * `document.hasFocus()` can tell: without it, a Bot that replied while the
+ * User was in another app stayed silent and left no badge, so the message was
+ * never heard about at all.
+ *
+ * A focused Bot raises no notification and carries no unread badge. Every
+ * other message raises exactly one of each.
+ */
+import type { BotUnreadViewV1 } from "./unread.js";
+
+/** What the rule needs to know about the browser, captured as plain data. */
+export interface ViewerFocusV1 {
+  /** The Bot whose chat is open, if any. */
+  activeBotId?: string;
+  /** `document.visibilityState === "visible"`. */
+  visible: boolean;
+  /** `document.hasFocus()`. */
+  focused: boolean;
+}
+
+/**
+ * Reads the rule's three inputs out of the live document.
+ *
+ * Outside a browser there is no viewer, so nothing is focused and every
+ * message counts — the conservative answer, since a badge can be cleared and
+ * an unheard message cannot be un-missed.
+ */
+export function readViewerFocusV1(activeBotId?: string): ViewerFocusV1 {
+  const identity = activeBotId === undefined ? {} : { activeBotId };
+  if (typeof document === "undefined") {
+    return { visible: false, focused: false, ...identity };
+  }
+  return {
+    visible: document.visibilityState === "visible",
+    // A document without `hasFocus` is not a background window; it is a
+    // runtime that does not report focus, and refusing to believe it would
+    // badge the chat the User is reading.
+    focused:
+      typeof document.hasFocus === "function" ? document.hasFocus() : true,
+    ...identity,
+  };
+}
+
+/** The rule itself. */
+export function isBotFocusedV1(focus: ViewerFocusV1, botId: string): boolean {
+  return focus.activeBotId === botId && focus.visible && focus.focused;
+}
+
+/**
+ * Whether a message from this Bot should raise a notification. The inverse of
+ * the rule, named so the call site reads as the sentence it implements: one
+ * notification per message, for a Bot that is out of focus.
+ */
+export function shouldNotifyForBotV1(
+  focus: ViewerFocusV1,
+  botId: string,
+): boolean {
+  return !isBotFocusedV1(focus, botId);
+}
+
+/**
+ * The unread view a focused Bot renders: none.
+ *
+ * The Bot Durable Object counts every settled Turn, because it cannot know
+ * which chat is on screen. A fan-out that returned mid-read would therefore
+ * paint a badge on the row the User is looking at, for as long as it took the
+ * read receipt to land. The receipt is still sent — "read" is durable, and it
+ * is what makes the badge stay gone on the next reload and the next tab — but
+ * the row never renders a count it is about to lose.
+ *
+ * `manuallyUnread` is the exception: a Bot the User deliberately marked unread
+ * stays bold while they look at it, because that flag is intent rather than
+ * arithmetic, and only opening the Bot again clears it.
+ */
+export function suppressUnreadWhileFocusedV1(
+  view: BotUnreadViewV1,
+): BotUnreadViewV1 {
+  if (view.manuallyUnread) return view;
+  return { ...view, count: 0, capped: false, unread: false };
+}

package/src/history.ts

@@ -24,6 +24,13 @@ import {
   type SessionEvent,
   type TurnTypeV1,
 } from "@frockbot/kernel-contracts";
+import {
+  compactionMessageV1,
+  compactionStateV1,
+  historyCharsV1,
+  pruneToolOutputsV1,
+  type CompactionStateV1,
+} from "./compaction.js";
 
 export { currentTurnV1 };
 
@@ -140,6 +147,68 @@ function budgetedMessagesV1(
     : [{ role: "user", content: omittedHistoryNoticeV1(dropped) }, ...narrowed];
 }
 
+/** The conversation's own messages, after any compaction already recorded. */
+export interface ChatWindowV1 {
+  /** Chat-Turn messages the newest compaction does not already cover. */
+  messages: LlmMessage[];
+  /** The Turn each of those belongs to. */
+  turns: number[];
+  /** Every chat Turn on the log, in order, covered or not. */
+  chatTurns: number[];
+  /** What the log says about compaction for this conversation. */
+  state: CompactionStateV1;
+  /** The newest completed compaction, when there is one. */
+  compaction?: CompactionStateV1["compaction"];
+}
+
+/**
+ * The window a chat Turn's request is assembled from, before pruning and
+ * before the budget.
+ *
+ * Shared by request assembly and by the Turn-end evaluation on purpose: what
+ * compaction is measured against has to be what the next request would carry,
+ * or the trigger fires against a number nobody pays.
+ */
+export function chatWindowV1(
+  events: readonly SessionEvent[],
+  messages: readonly LlmMessage[],
+): ChatWindowV1 {
+  const turns = messageTurnsV1(events);
+  const types = turnTypesByTurnV1(events);
+  const chat = (turn: number) => (types.get(turn) ?? "chat") === "chat";
+  const state = compactionStateV1(events);
+  const current = currentTurnV1(events);
+  // A compaction never covers the Turn being assembled, whatever the log says:
+  // the current Turn is carried whole, as it has been since ADR 0027.
+  const compaction =
+    state.compaction && state.compaction.throughTurn < current
+      ? state.compaction
+      : undefined;
+  const kept: LlmMessage[] = [];
+  const keptTurns: number[] = [];
+  for (const [index, message] of messages.entries()) {
+    const turn = turns[index]!;
+    if (!chat(turn)) continue;
+    if (compaction && turn <= compaction.throughTurn) continue;
+    kept.push(message);
+    keptTurns.push(turn);
+  }
+  const chatTurns = [
+    ...new Set(
+      events.flatMap((event) =>
+        event.type === "turn/start" && chat(event.turn) ? [event.turn] : [],
+      ),
+    ),
+  ];
+  return {
+    messages: kept,
+    turns: keptTurns,
+    chatTurns,
+    state,
+    ...(compaction ? { compaction } : {}),
+  };
+}
+
 /**
  * The messages one Turn's request may carry, given the whole session log and
  * the messages derived from it.
@@ -162,15 +231,24 @@ export function turnScopedMessagesV1(
   const current = currentTurnV1(input.events);
   const chatTurn = (turn: number) => (types.get(turn) ?? "chat") === "chat";
   if (chatTurn(current)) {
-    const conversation = input.messages.filter((_, index) =>
-      chatTurn(turns[index]!),
-    );
-    return budgetedMessagesV1(
-      conversation,
-      turns.filter((turn) => chatTurn(turn)),
-      current,
-      input.budget ?? CHAT_HISTORY_BUDGET_CHARS_V1,
+    const window = chatWindowV1(input.events, input.messages);
+    // Tier 1 of ADR 0030, and the only one that costs nothing: a tool result
+    // older than the newest few Turns keeps its pairing and loses its payload.
+    const pruned = pruneToolOutputsV1(window.messages, window.turns);
+    const preamble = window.compaction
+      ? [compactionMessageV1(window.compaction)]
+      : [];
+    // The summary is never a candidate for eviction — it is what stands in for
+    // the Turns eviction would otherwise have dropped — so it is spent from
+    // the budget rather than measured against it.
+    const budget = Math.max(
+      0,
+      (input.budget ?? CHAT_HISTORY_BUDGET_CHARS_V1) - historyCharsV1(preamble),
     );
+    return [
+      ...preamble,
+      ...budgetedMessagesV1(pruned, window.turns, current, budget),
+    ];
   }
   const own = input.messages.filter((_, index) => turns[index] === current);
   const chatTurns = new Set(

package/src/legacy-frock-model-id.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeModelBindingV1,
+  decodeUserSettingsViewV1,
+  resolveBotModelBindingV1,
+  type UserSettingsViewV1,
+} from "@frockbot/configuration-core";
+import { modelRuntimeLabel } from "./client/model-presentation.js";
+
+/**
+ * Bots bound before the provider was renamed carry `@flock/auto` in durable
+ * storage. Reading one must land in exactly the same place as reading
+ * `@frock/auto`: the same binding, the same resolution, the same line above
+ * the composer. Nothing writes the old spelling back.
+ */
+
+const FROCK_PACKAGE = {
+  packageId: "provider-flock-ai",
+  version: "0.0.1",
+  settings: [],
+  capabilities: [
+    {
+      id: "flock-ai-models",
+      kind: "model" as const,
+      connectionTypes: ["flock-ai-account"],
+    },
+  ],
+  connectionTypes: [
+    { id: "flock-ai-account", capabilities: ["flock-ai-models"] },
+  ],
+};
+
+function storedUserSettings(providerModelId: string): Record<string, unknown> {
+  return {
+    schemaVersion: 1,
+    revision: 7,
+    profile: { name: "FrockBot user" },
+    packages: [
+      { packageId: "provider-flock-ai", version: "0.0.1", state: "installed" },
+    ],
+    connections: [
+      {
+        connectionId: "flock-ai-ambient",
+        packageId: "provider-flock-ai",
+        connectionTypeId: "flock-ai-account",
+        displayName: "Frock AI",
+        state: "ready",
+        generation: "flock-ai-ambient-v1",
+        providerType: "flock-ai",
+        safeMetadata: {},
+        modelCatalog: {
+          schemaVersion: 1,
+          generation: "flock-ai-static-v1",
+          state: "fresh",
+          models: [
+            {
+              providerModelId: "@frock/auto",
+              displayName: "Auto (recommended)",
+              capabilities: { tools: true, vision: false, reasoning: true },
+              source: "discovered",
+            },
+          ],
+        },
+      },
+    ],
+    platformModel: { connectionId: "flock-ai-ambient", providerModelId },
+  };
+}
+
+function storedBotModelOverride(
+  providerModelId: string,
+): Record<string, unknown> {
+  return { connectionId: "flock-ai-ambient", providerModelId };
+}
+
+function composerLine(user: UserSettingsViewV1): string {
+  const model = user.platformModel!;
+  const binding = resolveBotModelBindingV1({
+    model,
+    user,
+    packages: [FROCK_PACKAGE],
+  });
+  const connection = binding.connection;
+  return modelRuntimeLabel({
+    source: "platform",
+    modelDisplayName: connection?.modelCatalog?.models.find(
+      (candidate) => candidate.providerModelId === model.providerModelId,
+    )?.displayName,
+    providerModelId: model.providerModelId,
+    packageDisplayName: "Frock AI",
+    connectionDisplayName: connection?.displayName,
+    failure: binding.failure,
+  });
+}
+
+describe("a pre-rename @flock/ model binding", () => {
+  test("decodes to the @frock/ spelling", () => {
+    expect(decodeUserSettingsViewV1(storedUserSettings("@flock/auto"))).toEqual(
+      decodeUserSettingsViewV1(storedUserSettings("@frock/auto")),
+    );
+
+    expect(
+      decodeUserSettingsViewV1(storedUserSettings("@flock/auto")).platformModel
+        ?.providerModelId,
+    ).toBe("@frock/auto");
+  });
+
+  test("decodes the same way on a Bot's own model override", () => {
+    // A Bot override is stored opaquely in `packageValues` and read back
+    // through this decoder by `storedModelBindingV1`.
+    const legacy = decodeModelBindingV1(storedBotModelOverride("@flock/auto"));
+
+    expect(legacy).toEqual(
+      decodeModelBindingV1(storedBotModelOverride("@frock/auto")),
+    );
+    expect(legacy.providerModelId).toBe("@frock/auto");
+  });
+
+  test("resolves against the catalog exactly as the new spelling does", () => {
+    const legacy = resolveBotModelBindingV1({
+      model: decodeUserSettingsViewV1(storedUserSettings("@flock/auto"))
+        .platformModel!,
+      user: decodeUserSettingsViewV1(storedUserSettings("@flock/auto")),
+      packages: [FROCK_PACKAGE],
+    });
+
+    expect(legacy.state).toBe("ready");
+    expect(legacy).toEqual(
+      resolveBotModelBindingV1({
+        model: decodeUserSettingsViewV1(storedUserSettings("@frock/auto"))
+          .platformModel!,
+        user: decodeUserSettingsViewV1(storedUserSettings("@frock/auto")),
+        packages: [FROCK_PACKAGE],
+      }),
+    );
+  });
+
+  test("shows the Frock AI settings line, not a raw legacy id", () => {
+    const line = composerLine(
+      decodeUserSettingsViewV1(storedUserSettings("@flock/auto")),
+    );
+
+    expect(line).toBe("Auto (recommended) · Frock AI");
+    expect(line).toBe(
+      composerLine(decodeUserSettingsViewV1(storedUserSettings("@frock/auto"))),
+    );
+  });
+});