@frockbot/plugin-shell 0.3.11 → 0.3.12

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,41 @@
  * 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. While the Bot is working it sits on its
+ * own row underneath, so the trail streaming off its right has the width of
+ * the transcript to run through rather than the gutter beside a bubble. 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.
+ */
+.bot-working {
+  display: flex;
+  height: 44px;
+  align-items: center;
+  gap: 0;
+}
+
+.bot-working-indicator {
+  height: 100%;
+}
+
 .bot-avatar {
   position: relative;
   display: grid;
@@ -361,7 +402,6 @@
   height: var(--frock-avatar-sm);
   flex: 0 0 auto;
   place-items: center;
-  margin-top: 2px;
 }
 
 .bot-avatar-fallback {
@@ -396,16 +436,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;
 }
 
@@ -420,6 +461,62 @@
   }
 }
 
+@keyframes frock-halo {
+  0%,
+  100% {
+    opacity: 0;
+    transform: scale(0.94);
+  }
+
+  50% {
+    opacity: 1;
+    transform: scale(1.06);
+  }
+}
+
+/*
+ * The bubble a Turn has before it has words: three dots that say the Bot is
+ * working, where the reply itself will appear.
+ */
+.message-working {
+  display: flex;
+  align-items: center;
+  min-height: 20px;
+}
+
+.working-dots {
+  display: inline-flex;
+  gap: 4px;
+}
+
+.working-dots i {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--frock-text-muted);
+  animation: frock-working-dot 1.2s ease-in-out infinite;
+}
+
+.working-dots i:nth-child(2) {
+  animation-delay: 0.15s;
+}
+
+.working-dots i:nth-child(3) {
+  animation-delay: 0.3s;
+}
+
+@keyframes frock-working-dot {
+  0%,
+  60%,
+  100% {
+    opacity: 0.3;
+  }
+
+  30% {
+    opacity: 1;
+  }
+}
+
 /*
  * A bubble runs nearly the width of the transcript, leaving one clear margin
  * on the side it is not anchored to: the Bot's at the end, the User's at the
@@ -1094,19 +1191,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);
+  }
+}

package/src/compaction-scheduler.test.ts

@@ -0,0 +1,96 @@
+// A compaction that outlives the Turn, and yields to the next one (ADR 0030).
+import { describe, expect, test } from "bun:test";
+import {
+  compactionInFlightV1,
+  compactionWorkV1,
+  whenCompactionSettledV1,
+  yieldCompactionWorkV1,
+} from "./compaction-scheduler.js";
+
+function stall(signal: AbortSignal): Promise<never> {
+  return new Promise((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), {
+      once: true,
+    });
+  });
+}
+
+/** A promise and the function that settles it, for ordering without timers. */
+function gate(): { promise: Promise<void>; open: () => void } {
+  let open = () => {};
+  const promise = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  return { promise, open };
+}
+
+describe("detached compaction", () => {
+  test("starting it does not wait for it", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    let finished = false;
+    const running = gate();
+    const started = Date.now();
+    compactionWorkV1(session).start(async (signal) => {
+      running.open();
+      await stall(signal).catch(() => {});
+      finished = true;
+    });
+    // The claim the defect got wrong: control is back immediately.
+    expect(Date.now() - started).toBeLessThan(50);
+    expect(finished).toBe(false);
+    expect(compactionInFlightV1(session)).toBe(true);
+    await running.promise;
+    await yieldCompactionWorkV1(session);
+    expect(finished).toBe(true);
+  });
+
+  test("a newly admitted Turn aborts it rather than queueing behind it", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    let reason: unknown;
+    const running = gate();
+    compactionWorkV1(session).start(async (signal) => {
+      running.open();
+      try {
+        await stall(signal);
+      } catch (error) {
+        reason = error;
+      }
+    });
+    await running.promise;
+    await yieldCompactionWorkV1(session);
+    expect(compactionInFlightV1(session)).toBe(false);
+    expect(String((reason as Error).message)).toContain("yielded");
+  });
+
+  test("a failure is nobody's problem, and never leaves work in flight", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    compactionWorkV1(session).start(async () => {
+      throw new Error("the summariser fell over");
+    });
+    await whenCompactionSettledV1(session);
+    expect(compactionInFlightV1(session)).toBe(false);
+  });
+
+  test("two compactions on one conversation never run beside each other", async () => {
+    const session = `session-${crypto.randomUUID()}`;
+    const order: string[] = [];
+    const release = gate();
+    compactionWorkV1(session).start(async () => {
+      order.push("first:start");
+      await release.promise;
+      order.push("first:end");
+    });
+    compactionWorkV1(session).start(async () => {
+      order.push("second:start");
+    });
+    release.open();
+    await whenCompactionSettledV1(session);
+    expect(order).toEqual(["first:start", "first:end", "second:start"]);
+  });
+
+  test("yielding costs nothing when no compaction is running", async () => {
+    await expect(
+      yieldCompactionWorkV1(`session-${crypto.randomUUID()}`),
+    ).resolves.toBeUndefined();
+  });
+});