@frockbot/plugin-shell 0.3.9 → 0.3.11

package/src/client/FrockBotApp.vue

@@ -2,6 +2,7 @@
 import { clientSurfaceRegistryKey } from "@frockbot/client-core";
 import {
   announceUiAnchor,
+  UiActivityRing,
   UiIcon,
   UiIconButton,
   UiMarkdown,
@@ -26,6 +27,7 @@ import {
   type WebToolActivity,
 } from "../shared.js";
 import { ComposerDraftStore } from "./composer-draft.js";
+import { activityRingV1 } from "./activity-ring.js";
 import {
   TURN_TEXT_MAX_CHARACTERS_V1,
   turnTextCounterVisibleV1,
@@ -431,66 +433,22 @@ function taskChipsOf(message: WebChatMessage): Array<{
 }
 
 /**
- * The tools this Turn ran, as the thread draws them.
+ * The activity ring for one assistant line.
  *
- * A tool whose Package draws its own surface is shown by that surface; every
- * other one is a chip, because a Turn that spends a minute making tool calls
- * used to show the User nothing at all but a spinning avatar.
+ * A Turn that spends a minute making tool calls used to show the User nothing
+ * but a breathing avatar, and then — briefly — a list of tool names, which put
+ * the model's plumbing into a conversation. The ring is neither: it pulses
+ * while the Turn runs and ticks forward for every step that settles, so the
+ * account of an ordinary tool call is a segment of a stroke and no words at
+ * all. The rule lives in `activity-ring.ts`; this only reads the message.
  */
-function toolChipsOf(message: WebChatMessage): WebToolActivity[] {
-  return message.tools.filter((tool) => iframeEntriesFor(tool).length === 0);
-}
-
-/**
- * What a chip calls a tool, in the User's words rather than the model's.
- *
- * A tool name is an identifier — `send_to_user`, `user-Github--acme/search_issues`
- * — and the transcript is a conversation, so the chip drops the namespace,
- * un-snakes the rest and capitalises it.
- */
-function toolChipLabel(tool: WebToolActivity): string {
-  const bare = tool.name.split("/").pop() ?? tool.name;
-  const words = bare.replace(/[_.-]+/g, " ").trim();
-  if (words.length === 0) return tool.name;
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
-
-/**
- * Whether a chip is drawn as a failure.
- *
- * A tool call the model recovered from is not a failure the User has anything
- * to do with: a refused call followed by a Turn that went on to finish is the
- * Bot correcting itself, and colouring it red reports a broken Turn that
- * worked. Only a Turn that itself ended badly keeps the failed state.
- */
-function toolChipState(
-  tool: WebToolActivity,
+function activityRingOf(
   message: WebChatMessage,
-): "running" | "completed" | "failed" | "retried" {
-  if (tool.status !== "failed") return tool.status;
-  return message.status === "completed" || message.status === "streaming"
-    ? "retried"
-    : "failed";
-}
-
-/** What a chip says a tool is doing. Its status, in the User's words. */
-function toolChipStatus(
-  tool: WebToolActivity,
-  message: WebChatMessage,
-): string {
-  const state = toolChipState(tool, message);
-  if (state === "running") return "running";
-  if (state === "retried") return "retried";
-  return state === "failed" ? "failed" : "done";
-}
-
-/** Which tool chips the User has opened. Local, and per chip. */
-const expandedTools = ref(new Set<string>());
-
-function toggleTool(toolId: string): void {
-  const next = new Set(expandedTools.value);
-  if (!next.delete(toolId)) next.add(toolId);
-  expandedTools.value = next;
+): ReturnType<typeof activityRingV1> {
+  return activityRingV1({
+    toolStatuses: message.tools.map((tool) => tool.status),
+    status: message.status,
+  });
 }
 
 /** Which chips the User has opened. Local, and per chip. */
@@ -928,28 +886,45 @@ function handleComposerKeydown(event: KeyboardEvent): void {
             </p>
             <template v-else-if="message.role === 'assistant'">
               <!--
-                The Bot's own avatar comes from whichever Package owns Bot
-                identity. When no Package fills the slot the sparkle tile is
-                the only child and shows through.
+                The Bot's own avatar, which appears only while it is working.
+                Every line in this transcript is from the same Bot — there are
+                no group conversations yet (issue 152) — so a sheep beside a
+                settled reply named nobody the reader did not already know. The
+                one beside a running Turn carries the ring, which is the whole
+                point of drawing it.
+
+                The art comes from whichever Package owns Bot identity; when no
+                Package fills the slot the sparkle tile is the only child and
+                shows through.
               -->
-              <div
-                class="bot-avatar"
-                :class="{
-                  'bot-avatar-live': message.status === 'streaming',
-                  'bot-avatar-waiting':
-                    message.status === 'streaming' && !message.text,
-                }"
-              >
-                <span class="bot-avatar-fallback" aria-hidden="true"
-                  ><UiIcon name="sparkle" size="sm"
-                /></span>
-                <k-slot name="frockbot.bot-avatar" />
-              </div>
+              <Transition name="activity-ring">
+                <div
+                  v-if="activityRingOf(message).active"
+                  class="bot-avatar bot-avatar-live"
+                  :class="{ 'bot-avatar-waiting': !message.text }"
+                >
+                  <span class="bot-avatar-fallback" aria-hidden="true"
+                    ><UiIcon name="sparkle" size="sm"
+                  /></span>
+                  <k-slot name="frockbot.bot-avatar" />
+                  <!--
+                    What the Bot is doing, while it is doing it — a stroke round
+                    the sheep that pulses and ticks a segment for every step the
+                    Turn settles. It completes and fades with the avatar when
+                    the Turn settles, and it never names a tool: the transcript
+                    stays a conversation.
+                  -->
+                  <UiActivityRing
+                    :progress="activityRingOf(message).progress"
+                    :running="activityRingOf(message).running"
+                    :laps="activityRingOf(message).laps"
+                  />
+                </div>
+              </Transition>
               <!--
-                Everything the Turn produced stacks in one column beside the
-                avatar. The row holds exactly two children — avatar, column —
-                so a bubble, a notice and a chip are stacked lines rather than
-                side-by-side columns squeezing the reply to a few pixels.
+                Everything the Turn produced stacks in one column. While the Bot
+                is working the avatar is beside it; once the Turn settles the
+                column is the whole row and starts at the transcript's edge.
               -->
               <div class="message-column">
                 <div v-if="message.text" class="message-bubble">
@@ -1024,40 +999,6 @@ function handleComposerKeydown(event: KeyboardEvent): void {
                   />
                 </div>
                 <!--
-                What the Bot did, while it is doing it. The chip is the
-                conversation's whole account of an ordinary tool call: its
-                name, whether it is running, and — when the User opens it —
-                what it returned.
-              -->
-                <div
-                  v-if="toolChipsOf(message).length > 0"
-                  class="message-tools"
-                >
-                  <button
-                    v-for="tool in toolChipsOf(message)"
-                    :key="tool.id"
-                    type="button"
-                    class="tool-chip"
-                    :class="`tool-chip-${toolChipState(tool, message)}`"
-                    :aria-expanded="expandedTools.has(tool.id)"
-                    @click="toggleTool(tool.id)"
-                  >
-                    <span class="tool-chip-name">{{
-                      toolChipLabel(tool)
-                    }}</span>
-                    <span class="tool-chip-status">{{
-                      toolChipStatus(tool, message)
-                    }}</span>
-                    <span
-                      v-if="
-                        expandedTools.has(tool.id) && tool.text !== undefined
-                      "
-                      class="tool-chip-result"
-                      >{{ tool.text }}</span
-                    >
-                  </button>
-                </div>
-                <!--
                 The subagents this Turn dispatched. The child's own Session is
                 never in this transcript, so the chip is the whole of what the
                 conversation says about it; opening one shows the summary the

package/src/client/activity-ring.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ACTIVITY_RING_MAX_LAPS_V1,
+  ACTIVITY_RING_SEGMENTS_V1,
+  activityRingV1,
+  type ActivityStepStatusV1,
+} from "./activity-ring.js";
+
+/** `count` settled steps, plus whatever is still in flight. */
+function steps(settled: number, inFlight = 0): ActivityStepStatusV1[] {
+  return [
+    ...Array.from<ActivityStepStatusV1>({ length: settled }).fill("completed"),
+    ...Array.from<ActivityStepStatusV1>({ length: inFlight }).fill("running"),
+  ];
+}
+
+describe("the avatar's activity ring", () => {
+  test("a Turn with nothing done yet still shows a ring", () => {
+    // Liveness before progress: the ring is the answer to "is it paused?", so
+    // it is drawn from the first moment of the Turn, empty and pulsing.
+    const ring = activityRingV1({ toolStatuses: [], status: "streaming" });
+    expect(ring.active).toBe(true);
+    expect(ring.running).toBe(true);
+    expect(ring.filled).toBe(0);
+    expect(ring.progress).toBe(0);
+  });
+
+  test("a step that is still running has not ticked the ring", () => {
+    const ring = activityRingV1({
+      toolStatuses: steps(2, 1),
+      status: "streaming",
+    });
+    expect(ring.steps).toBe(2);
+    expect(ring.filled).toBe(2);
+  });
+
+  test("a failed step ticks like any other — it is a step that happened", () => {
+    const ring = activityRingV1({
+      toolStatuses: ["completed", "failed"],
+      status: "streaming",
+    });
+    expect(ring.filled).toBe(2);
+  });
+
+  test("each settled step fills one more segment of the lap", () => {
+    for (let settled = 0; settled < ACTIVITY_RING_SEGMENTS_V1; settled += 1) {
+      const ring = activityRingV1({
+        toolStatuses: steps(settled),
+        status: "streaming",
+      });
+      expect(ring.filled).toBe(settled);
+      expect(ring.progress).toBeCloseTo(settled / ACTIVITY_RING_SEGMENTS_V1);
+      expect(ring.laps).toBe(0);
+    }
+  });
+
+  test("a full lap leaves a faint ring behind and starts again", () => {
+    const ring = activityRingV1({
+      toolStatuses: steps(ACTIVITY_RING_SEGMENTS_V1 + 1),
+      status: "streaming",
+    });
+    expect(ring.laps).toBe(1);
+    expect(ring.filled).toBe(1);
+  });
+
+  test("a Turn of forty tool calls never grows a fortieth ring", () => {
+    // The bound is the point: the ring reports that work is happening, not how
+    // much, so past the last lap it loops inside the strokes it already has.
+    const ring = activityRingV1({
+      toolStatuses: steps(40),
+      status: "streaming",
+    });
+    expect(ring.laps).toBe(ACTIVITY_RING_MAX_LAPS_V1);
+    expect(ring.filled).toBeLessThan(ACTIVITY_RING_SEGMENTS_V1);
+  });
+
+  test("a settled Turn keeps no ring, however it ended", () => {
+    for (const status of [
+      "completed",
+      "failed",
+      "interrupted",
+      "reconciliation-required",
+    ] as const) {
+      const ring = activityRingV1({ toolStatuses: steps(3), status });
+      expect(ring.active).toBe(false);
+      expect(ring.running).toBe(false);
+    }
+  });
+});

package/src/client/activity-ring.ts

@@ -0,0 +1,94 @@
+/**
+ * The activity ring: how much a running Turn has done, without saying so.
+ *
+ * A Turn can spend a minute making tool calls, and the thread used to answer
+ * that with either nothing or a list of tool names. Neither is right — the
+ * first reads as a paused app, the second puts the model's plumbing into a
+ * conversation. The ring is the third answer: a stroke around the Bot's avatar
+ * that pulses while the Turn runs and advances one segment for every step that
+ * settles, so a person sees liveness and rough progress and reads no words at
+ * all.
+ *
+ * This module is the whole rule, kept out of the component so it is testable
+ * without mounting Vue.
+ */
+
+/** Segments in one lap of the ring. A step fills one. */
+export const ACTIVITY_RING_SEGMENTS_V1 = 8;
+
+/**
+ * How many laps the ring will draw at once. A Turn making forty tool calls
+ * must not grow a fortieth ring, so the lap beyond the first is the last one:
+ * past it the ring keeps looping inside those two strokes.
+ */
+export const ACTIVITY_RING_MAX_LAPS_V1 = 1;
+
+/** A step's state, as the Turn's tool activity reports it. */
+export type ActivityStepStatusV1 = "running" | "completed" | "failed";
+
+/**
+ * A Turn's state, as the thread's message carries it.
+ *
+ * Deliberately the whole string rather than the union: only `streaming` means
+ * the Turn is still going, and every other value — including one a newer Bot
+ * invents — is an ending. The ring is drawn off that one positive test, so it
+ * cannot be left spinning by a status this file has never heard of.
+ */
+export type ActivityTurnStatusV1 = string;
+
+export interface ActivityRingViewV1 {
+  /** Whether the ring is drawn at all. A settled Turn keeps none. */
+  active: boolean;
+  /** Whether the ring pulses. False once the Turn has settled. */
+  running: boolean;
+  /** Steps that have settled in this Turn. Unbounded, and never rendered. */
+  steps: number;
+  /** Filled segments of the current lap, `0 … ACTIVITY_RING_SEGMENTS_V1`. */
+  filled: number;
+  /** Faint laps completed behind the live stroke, capped. */
+  laps: number;
+  /** The fraction of the circumference the live stroke draws, `0 … 1`. */
+  progress: number;
+}
+
+/**
+ * The ring for one assistant line.
+ *
+ * A running Turn ticks: every settled tool call advances the stroke one
+ * segment, and the lap that fills leaves a faint ring behind it — up to
+ * {@link ACTIVITY_RING_MAX_LAPS_V1}, after which the ring simply loops. A Turn
+ * that has settled draws no ring; the reply is the answer by then, and the
+ * component fades the ring out on its way off screen.
+ */
+export function activityRingV1(input: {
+  toolStatuses: readonly ActivityStepStatusV1[];
+  status: ActivityTurnStatusV1;
+}): ActivityRingViewV1 {
+  const running = input.status === "streaming";
+  const steps = input.toolStatuses.filter(
+    (status) => status !== "running",
+  ).length;
+  if (!running) {
+    return {
+      active: false,
+      running: false,
+      steps,
+      filled: 0,
+      laps: 0,
+      progress: 0,
+    };
+  }
+  const filled = steps % ACTIVITY_RING_SEGMENTS_V1;
+  const laps = Math.min(
+    Math.floor(steps / ACTIVITY_RING_SEGMENTS_V1),
+    ACTIVITY_RING_MAX_LAPS_V1,
+  );
+  return {
+    active: true,
+    running: true,
+    steps,
+    filled,
+    laps,
+    progress: filled / ACTIVITY_RING_SEGMENTS_V1,
+  };
+}

package/src/client/index.ts

@@ -1228,6 +1228,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       packageDisplayName: catalogPackage?.displayName,
       connectionDisplayName: connection?.displayName,
       failure: effective.binding?.failure,
+      fallback: Boolean(effective.fallback),
     });
   }
 

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

@@ -35,6 +35,20 @@ describe("model runtime presentation", () => {
     );
   });
 
+  test("names the stand-in model when the chosen one is unavailable", () => {
+    // The Bot is answering, so the line is not a failure — it names the model
+    // actually in use and says the User's own choice is not it.
+    expect(
+      modelRuntimeLabel({
+        source: "platform",
+        modelDisplayName: "Auto",
+        providerModelId: "@flock/auto",
+        packageDisplayName: "Flock AI",
+        fallback: true,
+      }),
+    ).toBe("Auto · Flock AI · your chosen model is unavailable");
+  });
+
   test("shows unavailable and backend failure states", () => {
     expect(modelRuntimeLabel({ source: "none" })).toBe(
       "No model available — set one up in Models",

package/src/client/model-presentation.ts

@@ -11,6 +11,11 @@ export function modelRuntimeLabel(input: {
   packageDisplayName?: string;
   connectionDisplayName?: string;
   failure?: string;
+  /**
+   * The chosen model could not bind — its provider Package is off, or its
+   * Connection is gone — and the platform default is answering in its place.
+   */
+  fallback?: boolean;
 }): string {
   if (input.failure) return input.failure;
   if (input.source === "none" || !input.providerModelId) {
@@ -22,5 +27,6 @@ export function modelRuntimeLabel(input: {
   const runtime = provider ? `${model} · ${provider}` : model;
   if (input.source === "bot") return `${runtime} · this Bot only`;
   if (input.source === "account") return `${runtime} · Account model`;
+  if (input.fallback) return `${runtime} · your chosen model is unavailable`;
   return runtime;
 }

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;
@@ -324,10 +330,14 @@
 }
 
 /*
- * 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 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.
  */
 .message-assistant {
   flex-direction: row;
@@ -381,20 +391,22 @@
   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 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.
+ */
+.activity-ring-enter-active,
+.activity-ring-leave-active {
+  transition: opacity 420ms ease-out;
+}
+
+.activity-ring-enter-from,
+.activity-ring-leave-to {
+  opacity: 0;
 }
 
 @keyframes frock-breathe {
@@ -408,22 +420,16 @@
   }
 }
 
-@keyframes frock-halo {
-  0%,
-  100% {
-    opacity: 0;
-    transform: scale(0.94);
-  }
-
-  50% {
-    opacity: 1;
-    transform: scale(1.06);
-  }
-}
-
+/*
+ * 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 +444,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 +459,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 +472,9 @@
 
 .message-tasks {
   display: flex;
+  width: calc(100% - var(--frock-bubble-gutter));
   flex-direction: column;
   gap: 6px;
-  width: min(640px, 84%);
 }
 
 .task-chip {
@@ -1169,16 +1125,6 @@
     padding: 20px;
   }
 
-  .message-bubble,
-  .message-user .message-bubble {
-    max-width: 92%;
-  }
-
-  .message-sends,
-  .message-tasks {
-    width: 92%;
-  }
-
   .message-attachments img {
     max-width: 100%;
   }