@frockbot/plugin-shell 0.3.11 → 0.3.13

package/src/client/model-presentation.test.ts

@@ -42,11 +42,11 @@ describe("model runtime presentation", () => {
       modelRuntimeLabel({
         source: "platform",
         modelDisplayName: "Auto",
-        providerModelId: "@flock/auto",
-        packageDisplayName: "Flock AI",
+        providerModelId: "@frock/auto",
+        packageDisplayName: "Frock AI",
         fallback: true,
       }),
-    ).toBe("Auto · Flock AI · your chosen model is unavailable");
+    ).toBe("Auto · Frock AI · your chosen model is unavailable");
   });
 
   test("shows unavailable and backend failure states", () => {

package/src/client/no-bot-model-label.test.ts

@@ -20,7 +20,7 @@ const { shellClientPlugin } = await import("./index.js");
 
 /**
  * A first-run account: the platform model resolves against a ready ambient
- * Flock AI Connection whose Catalog is fresh, and no Bot has been created yet.
+ * Frock AI Connection whose Catalog is fresh, and no Bot has been created yet.
  * The account's model is available, so the shell must not tell the User it is
  * unavailable before they have made their first Bot.
  */
@@ -37,7 +37,7 @@ test("does not report the account model unavailable before a Bot exists", async
         connectionId: "flock-ai-ambient",
         packageId: "provider-flock-ai",
         connectionTypeId: "flock-ai-account",
-        displayName: "Flock AI",
+        displayName: "Frock AI",
         state: "ready",
         providerType: "flock-ai",
         safeMetadata: {},
@@ -47,7 +47,7 @@ test("does not report the account model unavailable before a Bot exists", async
           state: "fresh",
           models: [
             {
-              providerModelId: "@flock/auto",
+              providerModelId: "@frock/auto",
               displayName: "Auto (recommended)",
               capabilities: { tools: true, vision: false, reasoning: true },
               source: "discovered",
@@ -58,7 +58,7 @@ test("does not report the account model unavailable before a Bot exists", async
     ],
     platformModel: {
       connectionId: "flock-ai-ambient",
-      providerModelId: "@flock/auto",
+      providerModelId: "@frock/auto",
     },
   };
 
@@ -74,7 +74,7 @@ test("does not report the account model unavailable before a Bot exists", async
           packages: [
             {
               id: "provider-flock-ai",
-              displayName: "Flock AI",
+              displayName: "Frock AI",
               version: "0.0.1",
               contributions: ["backend", "runtime"],
               configuration: {
@@ -82,7 +82,7 @@ test("does not report the account model unavailable before a Bot exists", async
                 connectionTypes: [
                   {
                     id: "flock-ai-account",
-                    displayName: "Flock AI",
+                    displayName: "Frock AI",
                     allowMultiple: false,
                     authorization: { kind: "ambient-native" },
                     capabilities: ["flock-ai-models"],
@@ -117,6 +117,6 @@ test("does not report the account model unavailable before a Bot exists", async
 
   // No Bot has been created, so `activeBotId` is unset.
   expect(provided.value.activeBotId).toBeUndefined();
-  expect(provided.value.modelLabel).toBe("Auto (recommended) · Flock AI");
+  expect(provided.value.modelLabel).toBe("Auto (recommended) · Frock AI");
   expect(provided.value.modelReady).toBe(true);
 });

package/src/client/skill-invocation.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { ClientSkillCatalogEntryV1 } from "../skill-protocol.js";
 import {
+  keptSkillHighlightV1,
   nextSkillHighlightV1,
   rankSkillCandidatesV1,
   SkillAttachmentStore,
@@ -140,4 +141,37 @@ describe("keyboard navigation", () => {
     expect(nextSkillHighlightV1(0, 3, -1)).toBe(2);
     expect(nextSkillHighlightV1(0, 0, 1)).toBe(0);
   });
+
+  test("a refilter keeps the highlight on the Skill it was on", () => {
+    const ranked = rankSkillCandidatesV1(catalog, "standup");
+    // The composer refreshes the popover on every keyup, the arrow key's own
+    // keyup included. Row two has to survive that refresh, or the highlight
+    // snaps back to the first row and the arrow keys look dead.
+    const highlighted = ranked[1]!.entry.ref;
+    expect(keptSkillHighlightV1(highlighted, ranked)).toBe(1);
+  });
+
+  test("a narrower query keeps the highlight when the Skill is still offered", () => {
+    const before = rankSkillCandidatesV1(catalog, "s");
+    const highlighted = before.find(
+      (candidate) => candidate.entry.ref === "bot/standup-notes",
+    )!.entry.ref;
+    const after = rankSkillCandidatesV1(catalog, "standup-n");
+    expect(after.map((candidate) => candidate.entry.ref)).toContain(
+      highlighted,
+    );
+    expect(keptSkillHighlightV1(highlighted, after)).toBe(
+      after.findIndex((candidate) => candidate.entry.ref === highlighted),
+    );
+  });
+
+  test("falls back to the first row once the highlighted Skill is gone", () => {
+    const ranked = rankSkillCandidatesV1(catalog, "standup");
+    expect(keptSkillHighlightV1("bot/weekly-report", ranked)).toBe(0);
+    expect(keptSkillHighlightV1(undefined, ranked)).toBe(0);
+  });
+
+  test("an empty list has no highlight to keep", () => {
+    expect(keptSkillHighlightV1("bot/daily-standup", [])).toBe(0);
+  });
 });

package/src/client/skill-invocation.ts

@@ -164,6 +164,28 @@ export class SkillAttachmentStore {
   }
 }
 
+/**
+ * The highlight to keep once the candidate list has been recomputed.
+ *
+ * The popover is refreshed from the composer's own `keyup` — including the
+ * `keyup` of the arrow key that has just moved the highlight — so a refresh
+ * that reset the highlight to the first row made the arrow keys look like they
+ * did nothing at all. The highlight is carried by ref rather than by index: the
+ * Skill under it keeps its place for as long as the query still offers it, and
+ * only a Skill that has dropped out of the list hands the highlight back to the
+ * first row.
+ */
+export function keptSkillHighlightV1(
+  highlightedRef: string | undefined,
+  candidates: readonly SkillCandidateV1[],
+): number {
+  if (candidates.length === 0) return 0;
+  const index = candidates.findIndex(
+    (candidate) => candidate.entry.ref === highlightedRef,
+  );
+  return index === -1 ? 0 : index;
+}
+
 /** Moves the popover's highlight, wrapping at both ends. */
 export function nextSkillHighlightV1(
   highlighted: number,

package/src/client/styles.css

@@ -201,6 +201,18 @@
   -webkit-app-region: no-drag;
 }
 
+/*
+ * The Bot's own header controls on a phone, where the right panel that
+ * usually carries them is a closed drawer.
+ */
+.topbar-bot-actions {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 2px;
+  margin-left: auto;
+}
+
 /* Thread */
 
 .thread {
@@ -215,6 +227,20 @@
   background-image: var(--frock-thread-gradient);
   scrollbar-color: var(--frock-scrollbar) transparent;
   scrollbar-width: thin;
+  /*
+   * New content is added at the end, so the browser keeps the reader where
+   * they are rather than letting the growth push the view.
+   */
+  overflow-anchor: auto;
+}
+
+/*
+ * Laid out and measured, deliberately not painted. A conversation is put at
+ * its end while this holds, so it opens there instead of opening at the top
+ * and scrolling down where the reader can see it.
+ */
+.thread-settling {
+  visibility: hidden;
 }
 
 .empty-thread {
@@ -334,26 +360,48 @@
  * notices and sends stack inside it, so a one-word reply is a bubble the width
  * of its word rather than a sliver of a shared row.
  *
- * The avatar is beside that column only while the Bot is working. Every reply
- * in this transcript is from the same Bot — there are no group conversations —
- * so a sheep on every settled line said nothing and cost the column its left
- * edge. The one on the running Turn does say something, which is why it stays.
+ * The avatar is not in that column, and not in the article at all: while the
+ * Bot is working it sits on its own row at the very end of the thread, so the
+ * trail streaming off its right has the width of the transcript to run through
+ * rather than the gutter beside a bubble, and a message sent mid-Turn lands
+ * above it. Every reply here is from the same Bot — there are no group
+ * conversations — so a sheep on every settled line said nothing and cost the
+ * column its left edge.
  */
 .message-assistant {
-  flex-direction: row;
-  align-items: flex-start;
+  flex-direction: column;
+  align-items: stretch;
   gap: 8px;
 }
 
 .message-column {
   display: flex;
   min-width: 0;
-  flex: 1 1 auto;
   flex-direction: column;
   align-items: flex-start;
   gap: 6px;
 }
 
+/*
+ * The working row. Its height is the trail's canvas: tall enough for the
+ * wobble to be visible, short enough that it reads as one line of the thread.
+ * It is the thread's last child, so it takes the same top margin every message
+ * has and adds no width of its own — the bubbles above never move sideways
+ * when it appears or goes.
+ */
+.bot-working {
+  display: flex;
+  width: 100%;
+  height: 44px;
+  align-items: center;
+  margin-top: 6px;
+  gap: 0;
+}
+
+.bot-working-indicator {
+  height: 100%;
+}
+
 .bot-avatar {
   position: relative;
   display: grid;
@@ -361,7 +409,6 @@
   height: var(--frock-avatar-sm);
   flex: 0 0 auto;
   place-items: center;
-  margin-top: 2px;
 }
 
 .bot-avatar-fallback {
@@ -396,16 +443,17 @@
 }
 
 /*
- * The ring's way off screen. The Turn has settled, the reply is the answer
- * now, and the stroke fades rather than vanishing between two frames.
+ * The working row's way off screen. The Turn has settled, the reply is the
+ * answer now, and the row fades rather than vanishing between two frames —
+ * which is also long enough for the particles still in flight to drain.
  */
-.activity-ring-enter-active,
-.activity-ring-leave-active {
+.bot-working-enter-active,
+.bot-working-leave-active {
   transition: opacity 420ms ease-out;
 }
 
-.activity-ring-enter-from,
-.activity-ring-leave-to {
+.bot-working-enter-from,
+.bot-working-leave-to {
   opacity: 0;
 }
 
@@ -1094,19 +1142,21 @@
     padding-left: 0;
   }
 
+  /* No window chrome to clear, but the panel toggle still sits at the
+     trailing edge, so the row ends before it rather than under it. */
   .topbar {
     gap: 8px;
-    padding: 0 100px 0 4px;
-  }
-
-  .brand-mark {
-    font-size: var(--frock-text-lg);
+    padding: 0 52px 0 4px;
   }
 
   .window-actions {
     padding: 0 8px;
   }
 
+  .brand-mark {
+    font-size: var(--frock-text-lg);
+  }
+
   .nav-toggle {
     flex: 0 0 auto;
   }

package/src/client/transcript-cache.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test";
+import type { WebChatMessage } from "../shared.js";
+import {
+  TRANSCRIPT_CACHE_LIMIT,
+  TranscriptCache,
+  TRANSCRIPT_FRESH_MS,
+} from "./transcript-cache.js";
+
+function message(runId: string, text = "hello"): WebChatMessage {
+  return {
+    id: `${runId}:user`,
+    runId,
+    role: "user",
+    text,
+    status: "completed",
+    tools: [],
+    sends: [],
+  };
+}
+
+function snapshot(conversationKey = "bot:1", runId = "run-1") {
+  return { conversationKey, messages: [message(runId)] };
+}
+
+describe("TranscriptCache", () => {
+  test("gives a saved conversation back without a read", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot());
+    const restored = cache.take("alpha", "bot:1");
+    expect(restored?.messages.map((entry) => entry.runId)).toEqual(["run-1"]);
+    expect(restored?.stale).toBe(false);
+  });
+
+  test("hands back copies, so the caller's edits never reach the cache", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot());
+    const restored = cache.take("alpha", "bot:1");
+    restored?.messages.push(message("run-2"));
+    const [first] = restored?.messages ?? [];
+    if (first) first.text = "rewritten";
+    expect(cache.take("alpha", "bot:1")?.messages).toEqual([message("run-1")]);
+  });
+
+  test("a different conversation on the same Bot is a miss, not the old one", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot("bot:1"));
+    // ADR 0027: "new conversation" moves the Bot to a new Session, and the
+    // transcript that belonged to the previous one must not come back.
+    expect(cache.take("alpha", "bot:1#2")).toBeUndefined();
+    // The miss drops it: nothing will ask for that conversation again.
+    expect(cache.take("alpha", "bot:1")).toBeUndefined();
+  });
+
+  test("keeps the last N Bots and evicts the least recently used", () => {
+    const cache = new TranscriptCache();
+    for (let index = 0; index < TRANSCRIPT_CACHE_LIMIT + 2; index += 1) {
+      cache.save(`bot-${index}`, snapshot(`key-${index}`, `run-${index}`));
+    }
+    expect(cache.size).toBe(TRANSCRIPT_CACHE_LIMIT);
+    expect(cache.take("bot-0", "key-0")).toBeUndefined();
+    expect(cache.take("bot-1", "key-1")).toBeUndefined();
+    expect(cache.take("bot-2", "key-2")).toBeDefined();
+  });
+
+  test("reading a transcript makes it the last one evicted", () => {
+    const cache = new TranscriptCache({ limit: 2 });
+    cache.save("alpha", snapshot("a"));
+    cache.save("beta", snapshot("b"));
+    // Alpha is the oldest write but the newest use.
+    expect(cache.take("alpha", "a")).toBeDefined();
+    cache.save("gamma", snapshot("c"));
+    expect(cache.take("beta", "b")).toBeUndefined();
+    expect(cache.take("alpha", "a")).toBeDefined();
+  });
+
+  test("an empty transcript is not held", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot());
+    cache.save("alpha", { conversationKey: "bot:1", messages: [] });
+    expect(cache.size).toBe(0);
+  });
+
+  test("a channel notice leaves the transcript drawable but owes a read", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot());
+    cache.markStale("alpha");
+    const restored = cache.take("alpha", "bot:1");
+    expect(restored?.messages).toHaveLength(1);
+    expect(restored?.stale).toBe(true);
+  });
+
+  test("a transcript past its freshness window owes a read", () => {
+    let clock = 1_000;
+    const cache = new TranscriptCache({ now: () => clock });
+    cache.save("alpha", snapshot());
+    clock += TRANSCRIPT_FRESH_MS + 1;
+    expect(cache.take("alpha", "bot:1")?.stale).toBe(true);
+  });
+
+  test("forget drops one Bot, or every Bot", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot("a"));
+    cache.save("beta", snapshot("b"));
+    cache.forget("alpha");
+    expect(cache.take("alpha", "a")).toBeUndefined();
+    expect(cache.take("beta", "b")).toBeDefined();
+    // Signing out is not "some conversations are stale", it is "none of these
+    // are this User's".
+    cache.forget();
+    expect(cache.size).toBe(0);
+  });
+
+  test("remembers where the reader had the thread", () => {
+    const cache = new TranscriptCache();
+    cache.save("alpha", snapshot());
+    cache.rememberViewport("alpha", { scrollTop: 420, pinnedToLatest: false });
+    expect(cache.take("alpha", "bot:1")?.viewport).toEqual({
+      scrollTop: 420,
+      pinnedToLatest: false,
+    });
+    // A viewport for a Bot that is not held is dropped rather than resurrecting it.
+    cache.rememberViewport("ghost", { scrollTop: 1, pinnedToLatest: true });
+    expect(cache.take("ghost", "bot:1")).toBeUndefined();
+  });
+});

package/src/client/transcript-cache.ts

@@ -0,0 +1,190 @@
+/**
+ * What the client keeps of a conversation it is not currently showing.
+ *
+ * Clicking between Bots used to throw the transcript away and read it back:
+ * every switch was an empty thread, a network round trip, and a scroll jump.
+ * A Bot's conversation is small, already durable behind it, and cheap to hold,
+ * so the last few are kept in memory and redrawn immediately.
+ *
+ * Two rules keep the cache from lying:
+ *
+ * - **It is keyed by conversation, not by Bot.** ADR 0027 makes "new
+ *   conversation" change the Session a Bot's Turns record, so the transcript
+ *   that belonged to the previous one must not come back under the same key.
+ * - **A cached transcript is still revalidated.** The entry carries when it
+ *   was written; past {@link TRANSCRIPT_FRESH_MS}, or once something has told
+ *   the client the Bot's runs moved, the restore is followed by a read. Inside
+ *   that window the click costs nothing, which is the whole point.
+ *
+ * The cache is memory only and never outlives the page: nothing about one
+ * User's conversations reaches the next one through it.
+ */
+import type { WebActiveRun, WebChatMessage } from "../shared.ts";
+
+/** How many Bots' transcripts are held before the least recent is dropped. */
+export const TRANSCRIPT_CACHE_LIMIT = 8;
+
+/**
+ * How long a cached transcript is served without a read behind it. Long
+ * enough that clicking between Bots is free, short enough that a conversation
+ * changed on another device is never stale for long.
+ */
+export const TRANSCRIPT_FRESH_MS = 30_000;
+
+/** Where the reader had the thread when they switched away. */
+export interface TranscriptViewport {
+  scrollTop: number;
+  /**
+   * True when they were at the end. Restored as "the end" rather than as the
+   * pixel offset, so a transcript that grew while they were away comes back
+   * pinned to the newest Turn and not to where it used to be.
+   */
+  pinnedToLatest: boolean;
+}
+
+/** One conversation, as the thread last drew it. */
+export interface TranscriptSnapshot {
+  /** Distinguishes this conversation from the next one on the same Bot. */
+  conversationKey: string;
+  messages: WebChatMessage[];
+  activeRun?: WebActiveRun;
+  activeRunId?: string;
+  runningRunId?: string;
+  viewport?: TranscriptViewport;
+}
+
+interface CacheEntry extends TranscriptSnapshot {
+  writtenAt: number;
+  stale: boolean;
+}
+
+/** A restored transcript, and whether reading it back is still owed. */
+export interface TranscriptRestore extends TranscriptSnapshot {
+  /** True when the caller should revalidate before trusting this for long. */
+  stale: boolean;
+}
+
+export interface TranscriptCacheOptions {
+  limit?: number;
+  freshMs?: number;
+  now?: () => number;
+}
+
+/**
+ * The last few Bots' conversations, most recently used last.
+ *
+ * `Map` iteration order is insertion order, so "touch on read" is a delete
+ * followed by a set and the first key is always the eviction candidate.
+ */
+export class TranscriptCache {
+  readonly #entries = new Map<string, CacheEntry>();
+  readonly #limit: number;
+  readonly #freshMs: number;
+  readonly #now: () => number;
+
+  constructor(options: TranscriptCacheOptions = {}) {
+    this.#limit = options.limit ?? TRANSCRIPT_CACHE_LIMIT;
+    this.#freshMs = options.freshMs ?? TRANSCRIPT_FRESH_MS;
+    this.#now = options.now ?? (() => Date.now());
+  }
+
+  /** The Bots held, least recently used first. */
+  get botIds(): readonly string[] {
+    return [...this.#entries.keys()];
+  }
+
+  get size(): number {
+    return this.#entries.size;
+  }
+
+  /**
+   * The transcript for this Bot's current conversation, if it is held.
+   *
+   * A key mismatch is a miss and drops the entry: the conversation it holds
+   * is over, and nothing will ask for it again.
+   */
+  take(botId: string, conversationKey: string): TranscriptRestore | undefined {
+    const entry = this.#entries.get(botId);
+    if (!entry) return undefined;
+    if (entry.conversationKey !== conversationKey) {
+      this.#entries.delete(botId);
+      return undefined;
+    }
+    // Reading is using: this Bot is now the most recent and the last to go.
+    this.#entries.delete(botId);
+    this.#entries.set(botId, entry);
+    return {
+      conversationKey: entry.conversationKey,
+      // Copies, so the caller's edits never reach back into the cache.
+      messages: entry.messages.map((message) => ({ ...message })),
+      ...(entry.activeRun ? { activeRun: { ...entry.activeRun } } : {}),
+      ...(entry.activeRunId ? { activeRunId: entry.activeRunId } : {}),
+      ...(entry.runningRunId ? { runningRunId: entry.runningRunId } : {}),
+      ...(entry.viewport ? { viewport: { ...entry.viewport } } : {}),
+      stale: entry.stale || this.#now() - entry.writtenAt > this.#freshMs,
+    };
+  }
+
+  /** Holds this conversation, evicting the least recently used past the limit. */
+  save(botId: string, snapshot: TranscriptSnapshot): void {
+    // An empty transcript is not worth a slot: restoring it looks exactly like
+    // the read it would have saved.
+    if (snapshot.messages.length === 0) {
+      this.#entries.delete(botId);
+      return;
+    }
+    // The scroll position is written after the transcript, by the thread that
+    // still has it on screen, so a save that carries none keeps the last one.
+    const viewport =
+      snapshot.viewport ?? this.#entries.get(botId)?.viewport ?? undefined;
+    this.#entries.delete(botId);
+    this.#entries.set(botId, {
+      conversationKey: snapshot.conversationKey,
+      messages: snapshot.messages.map((message) => ({ ...message })),
+      ...(snapshot.activeRun ? { activeRun: { ...snapshot.activeRun } } : {}),
+      ...(snapshot.activeRunId ? { activeRunId: snapshot.activeRunId } : {}),
+      ...(snapshot.runningRunId ? { runningRunId: snapshot.runningRunId } : {}),
+      ...(viewport ? { viewport: { ...viewport } } : {}),
+      writtenAt: this.#now(),
+      stale: false,
+    });
+    while (this.#entries.size > this.#limit) {
+      const oldest = this.#entries.keys().next();
+      if (oldest.done) break;
+      this.#entries.delete(oldest.value);
+    }
+  }
+
+  /** Records where the reader had the thread, without touching the transcript. */
+  rememberViewport(botId: string, viewport: TranscriptViewport): void {
+    const entry = this.#entries.get(botId);
+    if (!entry) return;
+    entry.viewport = { ...viewport };
+  }
+
+  /** Where the reader had this Bot's thread, if it is still held. */
+  viewportFor(botId: string): TranscriptViewport | undefined {
+    const viewport = this.#entries.get(botId)?.viewport;
+    return viewport ? { ...viewport } : undefined;
+  }
+
+  /**
+   * Says this Bot's runs have moved. The transcript still draws immediately —
+   * a stale answer beats an empty thread — but a read follows it.
+   */
+  markStale(botId: string): void {
+    const entry = this.#entries.get(botId);
+    if (entry) entry.stale = true;
+  }
+
+  /**
+   * Drops what is held for this Bot, or for every Bot.
+   *
+   * Called where the cached transcript would be a lie rather than merely old:
+   * archive, delete, rename, and a change of signed-in User.
+   */
+  forget(botId?: string): void {
+    if (botId === undefined) this.#entries.clear();
+    else this.#entries.delete(botId);
+  }
+}