@frockbot/plugin-shell 0.3.10 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -48,41 +48,42 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.10",
-    "@frockbot/application-foundation": "0.3.10",
-    "@frockbot/catalog-core": "0.3.10",
-    "@frockbot/client-core": "0.3.10",
-    "@frockbot/client-ui": "0.3.10",
-    "@frockbot/computer-core": "0.3.10",
-    "@frockbot/computer-host-protocol": "0.3.10",
-    "@frockbot/configuration-core": "0.3.10",
-    "@frockbot/connection-core": "0.3.10",
-    "@frockbot/kernel-agent-loop": "0.3.10",
-    "@frockbot/kernel-composition": "0.3.10",
-    "@frockbot/kernel-contracts": "0.3.10",
-    "@frockbot/kernel-do": "0.3.10",
-    "@frockbot/machine-protocol": "0.3.10",
-    "@frockbot/plugin-applets": "0.3.10",
-    "@frockbot/plugin-authoring": "0.3.10",
-    "@frockbot/plugin-bot-template": "0.3.10",
-    "@frockbot/plugin-computer": "0.3.10",
-    "@frockbot/plugin-flock": "0.3.10",
-    "@frockbot/plugin-image": "0.3.10",
-    "@frockbot/plugin-machine-messages": "0.3.10",
-    "@frockbot/plugin-mcp": "0.3.10",
-    "@frockbot/plugin-memory": "0.3.10",
-    "@frockbot/plugin-package-catalog": "0.3.10",
-    "@frockbot/plugin-routines": "0.3.10",
-    "@frockbot/plugin-skills": "0.3.10",
-    "@frockbot/plugin-subagents": "0.3.10",
-    "@frockbot/plugin-user-machine": "0.3.10",
-    "@frockbot/protocol": "0.3.10",
+    "@frockbot/agent-runtime": "0.3.11",
+    "@frockbot/application-foundation": "0.3.11",
+    "@frockbot/catalog-core": "0.3.11",
+    "@frockbot/client-core": "0.3.11",
+    "@frockbot/client-ui": "0.3.11",
+    "@frockbot/computer-core": "0.3.11",
+    "@frockbot/computer-host-protocol": "0.3.11",
+    "@frockbot/configuration-core": "0.3.11",
+    "@frockbot/connection-core": "0.3.11",
+    "@frockbot/kernel-agent-loop": "0.3.11",
+    "@frockbot/kernel-composition": "0.3.11",
+    "@frockbot/kernel-contracts": "0.3.11",
+    "@frockbot/kernel-do": "0.3.11",
+    "@frockbot/machine-protocol": "0.3.11",
+    "@frockbot/plugin-applets": "0.3.11",
+    "@frockbot/plugin-authoring": "0.3.11",
+    "@frockbot/plugin-bot-template": "0.3.11",
+    "@frockbot/plugin-computer": "0.3.11",
+    "@frockbot/plugin-flock": "0.3.11",
+    "@frockbot/plugin-image": "0.3.11",
+    "@frockbot/plugin-machine-messages": "0.3.11",
+    "@frockbot/plugin-mcp": "0.3.11",
+    "@frockbot/plugin-memory": "0.3.11",
+    "@frockbot/plugin-package-catalog": "0.3.11",
+    "@frockbot/plugin-routines": "0.3.11",
+    "@frockbot/plugin-skills": "0.3.11",
+    "@frockbot/plugin-subagents": "0.3.11",
+    "@frockbot/plugin-user-machine": "0.3.11",
+    "@frockbot/protocol": "0.3.11",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-tools": "0.3.10",
+    "@frockbot/plugin-prompt": "0.3.11",
+    "@frockbot/plugin-tools": "0.3.11",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.test.ts

@@ -8,9 +8,12 @@ import {
   type ToolExecutionContext,
   type TurnTypeV1,
 } from "@frockbot/kernel-contracts";
+import { SystemPromptRegistry } from "@frockbot/plugin-prompt";
 import { ToolRegistry } from "@frockbot/plugin-tools";
 import { Context } from "cordis";
 import {
+  CONVERSATION_PROMPT_SECTION_V1,
+  CONVERSATION_PROMPT_TEXT_V1,
   shellAdmissionCeilingV1,
   shellAgentPlugin,
   PARENT_HANDOFF_CAPABILITY_V1,
@@ -31,6 +34,7 @@ interface Mounted {
 async function mount(): Promise<Mounted> {
   const root = new Context();
   await root.plugin(SessionStore);
+  await root.plugin(SystemPromptRegistry);
   await root.plugin(ToolRegistry);
   const session = root.sessions.create(SESSION_ID);
   session.appendBatch([
@@ -382,3 +386,65 @@ describe("wake_parent", () => {
     }
   });
 });
+
+// The conversational contract is a prompt section and a tool description, and
+// the two have to say the same thing: a model that read one and not the other
+// would have half the rule.
+describe("the conversation prompt section", () => {
+  test("is assembled into the system prompt the model reads", async () => {
+    const mounted = await mount();
+    try {
+      const assembled = await mounted.root.systemPrompt.assemble({
+        sessionId: SESSION_ID,
+        provider: "test",
+        model: "test-model",
+        turnType: "chat",
+      });
+
+      const section = assembled.sections.find(
+        (candidate) => candidate.id === CONVERSATION_PROMPT_SECTION_V1,
+      );
+      expect(section?.text).toBe(CONVERSATION_PROMPT_TEXT_V1);
+      expect(assembled.text).toContain(CONVERSATION_PROMPT_TEXT_V1);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+
+  test("says acknowledge first, then beats, and never the steps between", () => {
+    expect(CONVERSATION_PROMPT_TEXT_V1).toContain("On it.");
+    expect(CONVERSATION_PROMPT_TEXT_V1).toContain(
+      "send only on a real beat: the result, a decision only the user can make, or a blocker",
+    );
+    expect(CONVERSATION_PROMPT_TEXT_V1).toContain(
+      "Never narrate what you are doing",
+    );
+    expect(CONVERSATION_PROMPT_TEXT_V1).toContain(
+      "Never leave a question or a request hanging",
+    );
+    // Short enough to be read as guidance rather than skimmed as a document.
+    expect(CONVERSATION_PROMPT_TEXT_V1.split("\n").length).toBeLessThanOrEqual(
+      12,
+    );
+  });
+
+  test("matches what the send tool's own description tells the model", async () => {
+    const mounted = await mount();
+    try {
+      const schema = mounted.root.tools
+        .schemas({ turnType: "chat" })
+        .find((tool) => tool.name === SEND_TO_USER_TOOL_V1);
+      const description = schema?.description ?? "";
+
+      expect(description).toContain("only way to say anything the user sees");
+      // When to call it, not only what it does.
+      expect(description).toContain("Call it once, immediately");
+      expect(description).toContain("Call it again only on a real");
+      expect(description).toContain("narrate a step or a tool");
+      expect(description).toContain("never end your Turn leaving the");
+      expect(description).toContain("keep it short");
+    } finally {
+      await mounted.dispose();
+    }
+  });
+});

package/src/agent.ts

@@ -3,6 +3,10 @@
 //
 // Two tools, and no authority of its own:
 //
+//  0. One prompt section, `conversation`: when to speak and when not to. It
+//     is contributed beside the tool so the section and the tool description
+//     cannot drift into telling the model two different things.
+//
 //  1. `send_to_user` (legacy alias `send_message`) — parity register row 57b.
 //     One tool carrying the typed payload union, admitted on chat turns only,
 //     recording each send as `send/to-user` on the durable log. Row 57c: a
@@ -127,8 +131,38 @@ function sendAcknowledgement(payload: SendToUserPayloadV1): string {
   }
 }
 
+/**
+ * The Bot's conversational contract, in the words the model reads.
+ *
+ * It lives here rather than in a prompt Package because it is the same rule
+ * the send tool's own description states: one place to write it, so the
+ * section and the tool cannot drift into telling the model two things. The
+ * Shell already owns the voice; it owns how the voice is used.
+ */
+export const CONVERSATION_PROMPT_SECTION_V1 = "conversation";
+/** Ordered after identity (0), before anything a Package contributes. */
+export const CONVERSATION_PROMPT_ORDER_V1 = 1;
+
+export const CONVERSATION_PROMPT_TEXT_V1 = [
+  "## Talking to the user",
+  "",
+  "Everything the user sees is a `send_to_user` call; nothing else reaches them.",
+  'When a request will take more than a moment, send one short line first — "On it." or "Looking into that." — then go quiet and work.',
+  "After that, send only on a real beat: the result, a decision only the user can make, or a blocker you cannot get past.",
+  "Never narrate what you are doing, what you are about to do, or which tool you are using.",
+  "Never leave a question or a request hanging: before you stop, the user must have the answer, the result, or the reason there isn't one.",
+  "When the work is finished, send the result itself, not an account of how you got it.",
+  "Keep every message short — a line or two, no preamble and no sign-off.",
+  "Don't say the same thing twice.",
+].join("\n");
+
 const SEND_TO_USER_DESCRIPTION = [
   "Speak to the user. This is the only way to say anything the user sees.",
+  "Call it once, immediately, with one short line when the request will take",
+  "more than a moment, then work in silence. Call it again only on a real",
+  "beat: the result, a decision only the user can make, or a blocker. Do not",
+  "call it to narrate a step or a tool, and never end your Turn leaving the",
+  "user's question unanswered. Each call is one message; keep it short.",
   "The payload is one of:",
   '{"type":"text","text":"…"}',
   '{"type":"attachment","url":"https://…","name":"…","mediaType":"…"}',
@@ -295,6 +329,13 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
   const userVoice = shellAdmissionCeilingV1(USER_VOICE_CAPABILITY_V1);
   const parentHandoff = shellAdmissionCeilingV1(PARENT_HANDOFF_CAPABILITY_V1);
   const disposers = [
+    // The voice and the rules for using it are contributed together, so a
+    // Composition that admits the send tool always carries the contract.
+    ctx.systemPrompt.register({
+      id: CONVERSATION_PROMPT_SECTION_V1,
+      order: CONVERSATION_PROMPT_ORDER_V1,
+      render: () => CONVERSATION_PROMPT_TEXT_V1,
+    }),
     ctx.tools.register(
       createSendToUserTool(SEND_TO_USER_TOOL_V1, ctx.sessions),
       userVoice ? { admissionCeiling: userVoice } : undefined,
@@ -327,6 +368,6 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
     for (const dispose of disposers.toReversed()) dispose();
   };
 };
-shellAgentPlugin.inject = ["tools", "sessions"];
+shellAgentPlugin.inject = ["tools", "sessions", "systemPrompt"];
 
 export default shellAgentPlugin;

package/src/backend-configuration.test.ts

@@ -8,6 +8,7 @@ import type {
 import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
 import { createShellBotBackendContribution } from "./backend.js";
 import { createIsolateCapabilityHost } from "./backend-isolate.js";
+import { notificationIdV1 } from "./notification-id.js";
 
 class MemoryStorage {
   readonly values = new Map<string, unknown>();
@@ -601,9 +602,14 @@ describe("generic per-Turn model resolution", () => {
     await expect(contribution.listNotifications()).resolves.toEqual([
       expect.objectContaining({
         // Colons would fail the acknowledge decoder, so the mint replaces
-        // them; a notification nobody can acknowledge 400s forever.
-        notificationId:
-          "package-connection-unavailable-run-1-bot-authored-flock-ai-ambient",
+        // them and folds in a digest of the raw parts; a notification nobody
+        // can acknowledge 400s forever.
+        notificationId: notificationIdV1(
+          "package-connection-unavailable",
+          "run-1",
+          "bot-authored",
+          "flock-ai-ambient",
+        ),
         title: "Connection unavailable",
       }),
     ]);

package/src/backend-package-catalog.ts

@@ -520,12 +520,9 @@ export function createPackageCatalogHost(
           index,
           catalogId: provenance.catalogId,
         });
-        // A first-party member pins no bundle, so "the entry still offers
-        // what the target generation recorded" is the two hashes agreeing,
-        // both present or both absent.
         if (
-          !targetEntry ||
-          targetEntry.bundle?.contentHash !== provenance.contentHash
+          !targetEntry?.bundle ||
+          targetEntry.bundle.contentHash !== provenance.contentHash
         ) {
           return undoRefused(
             request,
@@ -541,9 +538,7 @@ export function createPackageCatalogHost(
           version: targetCatalogMember.version,
           catalogId: provenance.catalogId,
           catalogGeneration: provenance.catalogGeneration,
-          ...(provenance.contentHash === undefined
-            ? {}
-            : { contentHash: provenance.contentHash }),
+          contentHash: provenance.contentHash,
         };
       }
       const receipt = await options.user.execute(command);
@@ -596,6 +591,13 @@ export function createPackageCatalogHost(
       let user: UserSettingsViewV1;
       let base: CompositionGenerationV1;
       let intent: PackageCatalogChangeIntentV1;
+      /**
+       * The entry names a compiled-in Package that is already required core in
+       * this Bot's Composition, so installing it is a User settings change and
+       * nothing else. Set on the install path and re-derived on a resumed
+       * intent, which carries no bundle hash precisely when this is true.
+       */
+      let firstParty = false;
       try {
         user = await options.user.read();
         base = await options.composition.lastKnownGood();
@@ -616,6 +618,12 @@ export function createPackageCatalogHost(
             );
           entry = resumed;
           intent = existingIntent;
+          firstParty =
+            existingIntent.action !== "remove" &&
+            !resumed.bundle &&
+            base.members.find(
+              (candidate) => candidate.packageId === resumed.packageId,
+            )?.provenance.kind === "first-party";
         } else if (action === "remove") {
           const packageId = request.change.input.packageId;
           const member = base.members.find(
@@ -697,7 +705,27 @@ export function createPackageCatalogHost(
           const member = base.members.find(
             (candidate) => candidate.packageId === entry.packageId,
           );
-          if (action === "install" && member) {
+          // Installing a first-party entry changes the *User's* settings, not
+          // the Composition: the compiled-in Package is already required core
+          // in the bootstrap generation (every one of them is), and
+          // `assertRequiredCoreSet` refuses any proposal that restates a
+          // first-party member with catalog provenance. So "already a member"
+          // is the normal state here, not a conflict — the guard below is
+          // about a *bundle-backed* entry, whose code really would be added
+          // twice.
+          firstParty =
+            !entry.bundle && member?.provenance.kind === "first-party";
+          if (firstParty) {
+            // The one integrity check left for a member nothing re-hashes at
+            // mount: the entry must name the manifest the application actually
+            // compiled in, or the Catalog has drifted from this deployment.
+            if (member!.manifestHash !== entry.manifestHash) {
+              throw new Error(
+                `Catalog entry "${entry.catalogId}" names manifest "${entry.manifestHash}", but this deployment ships "${member!.manifestHash}"`,
+              );
+            }
+          }
+          if (action === "install" && member && !firstParty) {
             throw new Error(
               `Package "${entry.packageId}" is already in this Bot's Composition`,
             );
@@ -757,9 +785,12 @@ export function createPackageCatalogHost(
         const bundle = entry.bundle;
         await options.storage.put({
           [packageCatalogChangeIntentKey(request.effectId)]: intent,
-          // A bundle-less entry has no manifest document to store; the mount
-          // resolves it from the compiled-in application instead, still
-          // against the `manifestHash` the generation records.
+          // A bundle-less entry stores no manifest document, because it adds
+          // no Composition member to mount one for: the compiled-in Package is
+          // already required core, running the manifest this deployment
+          // shipped. The entry's `manifestHash` was checked against that
+          // member's above, so a Catalog that has drifted from this deployment
+          // is refused rather than silently recorded.
           ...(bundle
             ? {
                 [authorshipManifestKey(intent.manifestHash)]: {
@@ -805,11 +836,35 @@ export function createPackageCatalogHost(
 
       const parent =
         (await options.composition.read(intent.baseGenerationId)) ?? base;
+      // A first-party entry contributes no member: it is already required core
+      // in the bootstrap generation, and restating it with catalog provenance
+      // is exactly what `assertRequiredCoreSet` refuses. The install is the
+      // User settings command above, which is all the Plugins page does too,
+      // so the Composition is left on the generation it was already running.
+      if (firstParty) {
+        const outcome: PackageCatalogChangeOutcomeRecordV1 = {
+          schemaVersion: 1,
+          status: "recorded",
+          effectId: request.effectId,
+          action,
+          packageId: intent.packageId,
+          displayName: intent.displayName,
+          version: intent.version,
+          generationId: parent.generationId,
+          missingConnectionTypes: intent.missingConnectionTypes,
+          recordedAt: intent.recordedAt,
+        };
+        await options.storage.put({
+          [packageCatalogChangeOutcomeKey(request.effectId)]: outcome,
+        });
+        return recordedOutcome(outcome);
+      }
+
       const members = parent.members.filter(
         (member) => member.packageId !== intent.packageId,
       );
       if (action !== "remove") {
-        const bundle = entry.bundle;
+        const bundle = entry.bundle!;
         const member: CompositionMemberV1 = {
           packageId: entry.packageId,
           specifier: `catalog:${entry.catalogId}`,
@@ -821,20 +876,14 @@ export function createPackageCatalogHost(
             version: entry.version,
             catalogId: entry.catalogId,
             catalogGeneration: intent.catalogGeneration,
-            ...(bundle ? { contentHash: bundle.contentHash } : {}),
+            contentHash: bundle.contentHash,
+          },
+          artifact: {
+            contentHash: bundle.contentHash,
+            size: bundle.size,
+            mediaType: bundle.mediaType,
+            bundlerVersion: bundle.bundlerVersion,
           },
-          // No artifact ⇒ the member mounts in the kernel isolate from the
-          // compiled-in Package, exactly as the UI install records it.
-          ...(bundle
-            ? {
-                artifact: {
-                  contentHash: bundle.contentHash,
-                  size: bundle.size,
-                  mediaType: bundle.mediaType,
-                  bundlerVersion: bundle.bundlerVersion,
-                },
-              }
-            : {}),
         };
         members.push(member);
       }

package/src/backend.ts

@@ -1239,18 +1239,7 @@ export class ShellBotBackendContribution {
     return { schemaVersion: 1, skills: entries };
   }
 
-  /**
-   * The one durable manifest lookup used by mounts, commands, and UI views —
-   * as the **stored document**, byte-for-byte what `manifestHash` was taken
-   * over at authoring time.
-   *
-   * Decoding rebuilds the object (`decodeV5` always writes a `configuration`
-   * key, for one), so a decoded manifest does not canonicalize back to the
-   * recorded hash. Every mount re-verifies that hash
-   * (`botIsolatePackageDescriptorV1`), so the raw document is the only thing
-   * that can be handed to it; callers that want the typed shape decode it
-   * themselves through `readCompositionMemberManifest`.
-   */
+  /** The two places this Bot's manifests live; see `composition-manifest.ts`. */
   private compositionManifestSources(): CompositionManifestSourcesV1 {
     return {
       stored: (manifestHash) =>
@@ -1261,6 +1250,16 @@ export class ShellBotBackendContribution {
     };
   }
 
+  /**
+   * The manifest a **mount** is handed: the stored document, byte-for-byte
+   * what `manifestHash` was taken over at authoring time.
+   *
+   * Decoding rebuilds the object (`decodeV5` always writes a `configuration`
+   * key, for one), so a decoded manifest does not canonicalize back to the
+   * recorded hash. Every mount re-verifies that hash
+   * (`botIsolatePackageDescriptorV1`), so the raw document is the only thing
+   * that can be handed to it.
+   */
   private readCompositionMemberManifestDocument(
     member: CompositionMemberV1,
   ): Promise<unknown | undefined> {
@@ -1270,6 +1269,10 @@ export class ShellBotBackendContribution {
     );
   }
 
+  /**
+   * The same manifest as the typed shape, for the callers that are not mounts:
+   * commands and UI views, which read fields rather than re-hash the document.
+   */
   private readCompositionMemberManifest(
     member: CompositionMemberV1,
   ): Promise<FrockBotManifest | undefined> {
@@ -5386,9 +5389,30 @@ export class ShellBotBackendContribution {
       index.map((entry) => entry.cursor),
       await this.sidebarPreview(storedPreview, index),
       failures,
+      await this.isWorking(index[0]?.runId),
     );
   }
 
+  /**
+   * Whether the Bot's newest admitted run is still going.
+   *
+   * The sidebar draws this as an activity ring, so somebody in another
+   * conversation can see a Bot working rather than reading a quiet row as a
+   * stalled one. It is the newest run only: a Bot admits one Turn at a time,
+   * so an older run that is somehow still marked running is a reconciliation
+   * problem and not something a ring should report. A read that fails is no
+   * ring — liveness is never worth failing a sidebar poll for.
+   */
+  private async isWorking(runId: string | undefined): Promise<boolean> {
+    if (runId === undefined) return false;
+    try {
+      const run = await this.authority.readRun(runId);
+      return run?.status === "running";
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * How many stored runs a read will open to recover a missing preview. The
    * newest settled chat Turn is almost always the first entry; the bound is

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/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%;
   }

package/src/notification-id.test.ts

@@ -50,6 +50,16 @@ describe("notificationIdV1", () => {
     expect(notificationIdV1(...parts)).toBe(notificationIdV1(...parts));
   });
 
+  test("parts the sanitiser would flatten together stay distinct", () => {
+    // Well under the length ceiling, so nothing else separates them: `a:b` and
+    // `a-b` both sanitise to `a-b`, and one notification silently overwrote
+    // the other.
+    expect(notificationIdV1("package", "a:b")).not.toBe(
+      notificationIdV1("package", "a-b"),
+    );
+    expect(notificationIdV1("a", "b")).not.toBe(notificationIdV1("a-b"));
+  });
+
   test("distinct parts stay distinct, even past the length ceiling", () => {
     const long = "x".repeat(400);
     const a = notificationIdV1("package", long, "one");
@@ -60,6 +70,22 @@ describe("notificationIdV1", () => {
     expect(acknowledge(b)).toBe(b);
   });
 
+  test("a legacy colon id already in the field can still be acknowledged", () => {
+    // Bots that failed a generation before this fix are holding notifications
+    // whose ids were interpolated by hand. If those stay unacknowledgeable the
+    // client retries them forever, so the decoder admits the older shape even
+    // though nothing mints it any more.
+    const legacy =
+      "composition-failure:2026-09-03T23:49:00.416Z:dc03a32d9b717619:1";
+    expect(acknowledge(legacy)).toBe(legacy);
+  });
+
+  test("an id is still bounded, whatever shape it arrives in", () => {
+    expect(() => acknowledge("a".repeat(200))).toThrow();
+    expect(() => acknowledge("../../escape")).toThrow();
+    expect(() => acknowledge("")).toThrow();
+  });
+
   test("parts that sanitize to nothing still mint an acknowledgeable id", () => {
     const id = notificationIdV1(":::", "::");
     expect(acknowledge(id)).toBe(id);

package/src/run-protocol.ts

@@ -5,7 +5,10 @@ import {
   type SessionEvent,
   type SkillRefV1,
 } from "@frockbot/kernel-contracts";
-import { isPublicIdentifier } from "@frockbot/configuration-core";
+import {
+  isPublicIdentifier,
+  isRpcIdentifier,
+} from "@frockbot/configuration-core";
 import { decodeRunCursorV1, RUN_CURSOR_PATTERN } from "./run-cursor.js";
 export { decodeRunCursorV1, RUN_CURSOR_PATTERN };
 import type {
@@ -1648,7 +1651,15 @@ export function decodeClientNotificationAcknowledgementCommandV1(
     MAX_RUN_ID_LENGTH,
     "notification acknowledgement command",
   );
-  if (!isPublicIdentifier(notificationId)) {
+  // `isRpcIdentifier`, not `isPublicIdentifier`: the same bounded alphabet
+  // plus `:` and `@`. New ids are minted through `notificationIdV1` and carry
+  // neither, but Bots in the field are already holding notifications whose ids
+  // were interpolated by hand — `composition-failure:<generationId>:<attempt>`
+  // and three more like it. Under the stricter pattern those could never be
+  // acknowledged, so the client retried them forever and the Bot answered 400
+  // on every poll for the rest of its life. Accepting them here is what lets
+  // an already-wedged Bot recover without a storage sweep.
+  if (!isRpcIdentifier(notificationId)) {
     throw new Error(
       "notification acknowledgement command.notificationId is invalid",
     );

package/src/settings-links.ts

@@ -81,6 +81,12 @@ export const SETTINGS_ANCHORS_V1: readonly SettingsAnchorV1[] = [
     label: "Label",
     scope: "bot",
   },
+  {
+    anchor: "bot-pinned",
+    surface: "bot-settings",
+    label: "Pinned",
+    scope: "bot",
+  },
   {
     anchor: "bot-description",
     surface: "bot-settings",

package/src/unread.ts

@@ -389,6 +389,15 @@ export interface BotUnreadViewV1 {
   lastViewedAt?: string;
   /** Latest settled assistant/user line, projected for the sidebar only. */
   lastMessage?: SidebarMessagePreviewV1;
+  /**
+   * Whether this Bot has a Turn running right now.
+   *
+   * The sidebar draws it as an activity ring on the row's avatar, so somebody
+   * reading one conversation can see another Bot still working rather than
+   * assuming it stalled. Optional: a view a client older than the Bot decodes,
+   * or one stored before this existed, simply draws no ring.
+   */
+  working?: boolean;
 }
 
 export interface BotUnreadDirectoryViewV1 {
@@ -414,6 +423,8 @@ export function projectBotUnreadViewV1(
    * so it counts here even though the firing that produced it does not.
    */
   automationFailures = 0,
+  /** True while a Turn of this Bot's is running. Drawn as the row's ring. */
+  working = false,
 ): BotUnreadViewV1 {
   const ceiling = state.lastActivityCursor;
   let counted = Math.max(0, automationFailures);
@@ -449,6 +460,7 @@ export function projectBotUnreadViewV1(
       ? {}
       : { lastViewedAt: state.lastViewedAt }),
     ...(lastMessage === undefined ? {} : { lastMessage }),
+    ...(working ? { working: true } : {}),
   };
 }
 
@@ -528,7 +540,13 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
   exactKeys(
     value,
     ["schemaVersion", "botId", "count", "capped", "unread", "manuallyUnread"],
-    ["lastActivityCursor", "lastActivityAt", "lastViewedAt", "lastMessage"],
+    [
+      "lastActivityCursor",
+      "lastActivityAt",
+      "lastViewedAt",
+      "lastMessage",
+      "working",
+    ],
     "unread view",
   );
   if (value.schemaVersion !== 1) {
@@ -563,6 +581,9 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
   );
   const lastViewedAt = optionalTimestamp(value, "lastViewedAt", "unread view");
   const lastMessage = optionalSidebarMessagePreviewV1(value.lastMessage);
+  if (value.working !== undefined && typeof value.working !== "boolean") {
+    throw new UnreadDecodeError("unread view working is invalid");
+  }
   return {
     schemaVersion: 1,
     botId: value.botId,
@@ -574,6 +595,7 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
     ...(lastActivityAt === undefined ? {} : { lastActivityAt }),
     ...(lastViewedAt === undefined ? {} : { lastViewedAt }),
     ...(lastMessage === undefined ? {} : { lastMessage }),
+    ...(value.working === true ? { working: true } : {}),
   };
 }