@frockbot/plugin-shell 0.3.10 → 0.3.12

package/src/client/styles.css

@@ -1,4 +1,10 @@
 .frockbot-root {
+  /*
+   * The clear margin a bubble leaves on the side it is not anchored to — about
+   * a centimetre and a half. It is what says which side of the conversation a
+   * line is on, so it is the same on a phone as on a desktop.
+   */
+  --frock-bubble-gutter: 56px;
   position: fixed;
   z-index: 1000;
   inset: 0;
@@ -195,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 {
@@ -209,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 {
@@ -324,26 +356,45 @@
 }
 
 /*
- * An assistant Turn is its avatar and, beside it, one column holding
- * everything the Turn produced. The row has exactly two children: bubbles,
- * notices, sends and chips stack inside the column, so a one-word reply is a
- * bubble the width of its word rather than a sliver of a shared row.
+ * An assistant Turn is one column holding everything it produced: bubbles,
+ * 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 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;
@@ -351,7 +402,6 @@
   height: var(--frock-avatar-sm);
   flex: 0 0 auto;
   place-items: center;
-  margin-top: 2px;
 }
 
 .bot-avatar-fallback {
@@ -381,20 +431,23 @@
   animation: frock-breathe 2600ms ease-in-out infinite;
 }
 
-.bot-avatar-live::after {
-  position: absolute;
-  border-radius: 12px;
-  animation: frock-halo 2600ms ease-in-out infinite;
-  box-shadow: 0 0 0 2px var(--frock-surface-accent);
-  content: "";
-  inset: -4px;
-  opacity: 0;
-  pointer-events: none;
+.bot-avatar-waiting {
+  animation-duration: 1600ms;
 }
 
-.bot-avatar-waiting,
-.bot-avatar-waiting::after {
-  animation-duration: 1600ms;
+/*
+ * 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.
+ */
+.bot-working-enter-active,
+.bot-working-leave-active {
+  transition: opacity 420ms ease-out;
+}
+
+.bot-working-enter-from,
+.bot-working-leave-to {
+  opacity: 0;
 }
 
 @keyframes frock-breathe {
@@ -421,9 +474,59 @@
   }
 }
 
+/*
+ * 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
+ * start. That margin is the only thing distinguishing the two columns now that
+ * neither carries an avatar, so it is a fixed gap rather than a percentage —
+ * it has to stay legible at every width.
+ */
 .message-bubble {
   width: max-content;
-  max-width: min(640px, 84%);
+  max-width: calc(100% - var(--frock-bubble-gutter));
   padding: 10px 14px;
   border: 1px solid var(--frock-border);
   border-radius: 18px 18px 18px 6px;
@@ -438,7 +541,7 @@
 }
 
 .message-user .message-bubble {
-  max-width: min(640px, 84%);
+  max-width: calc(100% - var(--frock-bubble-gutter));
   border-color: var(--frock-action-primary);
   border-radius: 18px 18px 6px 18px;
   color: var(--frock-on-accent);
@@ -453,59 +556,9 @@
 
 .message-sends {
   display: flex;
+  width: calc(100% - var(--frock-bubble-gutter));
   flex-direction: column;
   gap: 8px;
-  width: min(640px, 84%);
-}
-
-/*
- * Tool calls. Quieter than anything the Bot said: the User is watching work
- * happen, not reading a message, so a chip carries the name and its state and
- * opens in place to what the tool returned.
- */
-
-.message-tools {
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-  width: min(640px, 84%);
-}
-
-.tool-chip {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  align-items: baseline;
-  padding: 6px 10px;
-  font: inherit;
-  color: var(--frock-text-muted);
-  text-align: left;
-  cursor: pointer;
-  background: var(--frock-surface);
-  border: 1px solid var(--frock-border);
-  border-radius: 10px;
-}
-
-.tool-chip-name {
-  color: var(--frock-text);
-  font-weight: 600;
-}
-
-.tool-chip-status {
-  flex: 1 1 auto;
-  font-size: var(--frock-text-xs);
-}
-
-.tool-chip-failed .tool-chip-status {
-  color: var(--frock-danger-text);
-}
-
-.tool-chip-result {
-  flex: 1 0 100%;
-  max-height: 12em;
-  overflow: auto;
-  white-space: pre-wrap;
-  word-break: break-word;
 }
 
 /*
@@ -516,9 +569,9 @@
 
 .message-tasks {
   display: flex;
+  width: calc(100% - var(--frock-bubble-gutter));
   flex-direction: column;
   gap: 6px;
-  width: min(640px, 84%);
 }
 
 .task-chip {
@@ -1138,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;
   }
@@ -1169,16 +1224,6 @@
     padding: 20px;
   }
 
-  .message-bubble,
-  .message-user .message-bubble {
-    max-width: 92%;
-  }
-
-  .message-sends,
-  .message-tasks {
-    width: 92%;
-  }
-
   .message-attachments img {
     max-width: 100%;
   }

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);
+  }
+}