@frockbot/plugin-shell 0.3.10 → 0.3.12

package/src/client/index.ts

@@ -1,7 +1,10 @@
 /// <reference path="../env.d.ts" />
 
 import {
+  clientFailureDetailV1,
   decodeExternalAuthorizationUrl,
+  presentClientFailureV1,
+  serverRefusalMessageV1,
   type AgentTransport,
   type ClientAnnouncement,
   type ClientNotificationIntent,
@@ -11,6 +14,8 @@ import {
   type ClientTurnEvent,
 } from "@frockbot/client-core";
 import { clientSurfaceRegistryKey } from "@frockbot/client-core";
+import { COMPACTED_ANNOUNCEMENT_TEXT_V1 } from "../compaction.js";
+import { readViewerFocusV1, shouldNotifyForBotV1 } from "../focus.js";
 // Connection mutations use the provider-neutral hosted command contract.
 import type {
   ConnectionCommandReceiptV1,
@@ -86,6 +91,7 @@ import {
   type WebTaskChip,
   type WebToolActivity,
 } from "../shared.js";
+import { TranscriptCache } from "./transcript-cache.js";
 import FrockBotApp from "./FrockBotApp.vue";
 import PackageEntryTrigger from "./PackageEntryTrigger.vue";
 import PackageIframeSettings from "./PackageIframeSettings.vue";
@@ -251,6 +257,11 @@ function activeRunView(run: ClientRun): WebActiveRun | undefined {
     return {
       runId: run.runId,
       status: run.status,
+      // Never the backend's own sentence. What arrived here read
+      // `Model request "1c7dd68e-…" has no durable provider outcome:` — a
+      // UUID and two internal nouns, in the one place a User is told what
+      // happened to their reply. The raw text stays on the run for the
+      // console; the banner says what it means and offers the one action.
       message: run.stopRequestedAt
         ? "Stopping…"
         : "Something went wrong mid-reply. Try again to pick it up.",
@@ -345,7 +356,15 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: "This reply stopped partway. Try again to continue it.",
+      /*
+       * A failure is not something the Bot said. The bubble holds the text
+       * the model actually produced — often none — and the notice under it
+       * says why the Turn ends there: what arrived here read `Model request
+       * "1c7dd68e-…" has no durable provider outcome`, in a bubble styled
+       * exactly like the Bot speaking.
+       */
+      text: visibleAssistantText(run),
+      notice: "This reply stopped partway. Try again to continue it.",
       status: "reconciliation-required",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -375,7 +394,11 @@ function assistantMessage(
       runId: run.runId,
       role: "assistant",
       text: run.responseText,
-      notice: run.failure ?? "Agent request failed.",
+      // The same sentence the reply-less failure gets. The durable failure
+      // text is a provider's, not the product's — `Bot turn ended with
+      // outcome model-error`, a status code, once a run UUID — and under a
+      // bubble it reads as part of what the Bot was saying.
+      notice: "This Bot couldn't finish its reply. Try again.",
       status: "error",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -388,8 +411,13 @@ function assistantMessage(
     role: "assistant",
     text:
       run.status === "failed"
-        ? "This Bot couldn't finish its reply. Try again."
+        ? visibleAssistantText(run)
         : visibleAssistantText(run, notification?.body ?? ""),
+    // Why the Turn ends there, under whatever it had already said — never as
+    // the bubble's own text, which reads as the Bot saying it.
+    ...(run.status === "failed"
+      ? { notice: "This Bot couldn't finish its reply. Try again." }
+      : {}),
     status: run.status === "failed" ? "error" : "completed",
     tools: toolsFrom(run.events),
     sends: sendsFrom(run.events),
@@ -411,7 +439,10 @@ export function projectAnnouncements(
       id: announcement.announcementId,
       runId: announcement.announcementId,
       role: "system",
-      text: `Renamed to ${announcement.to} by ${announcement.namedBy}`,
+      text:
+        announcement.type === "conversation/compacted"
+          ? COMPACTED_ANNOUNCEMENT_TEXT_V1
+          : `Renamed to ${announcement.to} by ${announcement.namedBy}`,
       at: announcement.at,
       status: "completed",
       tools: [],
@@ -420,11 +451,34 @@ export function projectAnnouncements(
     const index = messages.findIndex(
       (candidate) => candidate.id === announcement.announcementId,
     );
-    if (index >= 0) messages[index] = message;
-    else messages.push(message);
+    // Removed before it is placed, so a marker that already sits in the thread
+    // is re-seated rather than frozen wherever the first poll put it.
+    if (index >= 0) messages.splice(index, 1);
+    messages.splice(announcementIndex(messages, message.at ?? ""), 0, message);
   }
 }
 
+/**
+ * Where a system line belongs among the Turns.
+ *
+ * Only the user message of a Turn carries a timestamp; everything the Bot
+ * wrote for that Turn follows it untimed. So an untimed message inherits the
+ * last timestamp seen, and the line is placed before the first message that is
+ * genuinely later than it. A marker for a range that has scrolled out of the
+ * transcript sorts before everything, which puts it at the top of what remains.
+ */
+function announcementIndex(
+  messages: readonly WebChatMessage[],
+  at: string,
+): number {
+  let seen = "";
+  for (const [index, candidate] of messages.entries()) {
+    if (candidate.at) seen = candidate.at;
+    if (seen > at) return index;
+  }
+  return messages.length;
+}
+
 export function projectDurableRuns(
   state: DurableRunProjectionState,
   notifications: readonly ClientNotificationIntent[],
@@ -885,6 +939,26 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
    * epoch is bumped at the boundary so those answers are dropped.
    */
   let conversationGeneration = 0;
+  /*
+   * The conversations this client is still holding.
+   *
+   * Switching Bots used to be a blank thread and a read; the last few are now
+   * redrawn from memory and read back behind the paint. `transcriptEpochs`
+   * names the conversation each entry belongs to: the backend does not tell a
+   * client its Session id, but the client is the one that ends a conversation,
+   * so counting that action locally is the same boundary (ADR 0027).
+   */
+  const transcripts = new TranscriptCache();
+  const transcriptEpochs = new Map<string, number>();
+  const conversationKeyFor = (botId: string): string =>
+    `${botId}#${transcriptEpochs.get(botId) ?? 0}`;
+  /*
+   * The Bot whose first channel reset is already answered by the cache. A
+   * socket opening emits an untopiced invalidation meaning "read everything";
+   * for a transcript restored moments ago that read is the reload the User
+   * asked us to stop doing. A real `runs` notice is never suppressed.
+   */
+  let restoredWithoutRead: string | undefined;
   let userSettingsGeneration = 0;
   let pluginCatalogGeneration = 0;
   let packageCatalogGeneration = 0;
@@ -1028,11 +1102,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         if (isTerminalRun(run)) return "admitted";
       } catch (error) {
         if (signal.aborted) return "detached";
-        reconciliationError = `${
-          error instanceof Error
-            ? error.message
-            : "Couldn't check on your message."
-        } Retrying…`;
+        reconciliationError = `${presentClientFailureV1(
+          error,
+          "check on your message",
+        )} Retrying…`;
         web.value.settingsError = reconciliationError;
       }
       const delayMs = uncertainAdmissionDelayMsV1(attempt);
@@ -1084,9 +1157,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         if (isTerminalRun(run)) return;
       } catch (error) {
         if (signal.aborted) return;
-        observationError = `${
-          error instanceof Error ? error.message : "Couldn't load that reply."
-        } Retrying…`;
+        observationError = `${presentClientFailureV1(
+          error,
+          "load that reply",
+        )} Retrying…`;
         web.value.settingsError = observationError;
       }
       await waitForRunLookup(delayMs, signal);
@@ -1141,7 +1215,13 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         web.value.settingsError = "A completed Bot result is waiting to load";
         continue;
       }
-      if (document.hidden) {
+      // The open Bot is only *read* while the tab is visible and the window
+      // holds focus; `document.hidden` alone called a visible tab behind
+      // another window "open", and the reply that landed there was never
+      // heard about. One definition, shared with the sidebar's badge.
+      if (
+        shouldNotifyForBotV1(readViewerFocusV1(web.value.activeBotId), botId)
+      ) {
         // One seam: the desktop or mobile notifications Package when the shell
         // exposes it, the web API when it does not.
         const delivery = await showClientNotificationV1({
@@ -1295,6 +1375,16 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     connectionsAvailable: ctx.transport.connectionsAvailable !== false,
     activeBotId: undefined,
     composerContext: undefined,
+    transcripts: {
+      rememberViewport: (botId, viewport) =>
+        transcripts.rememberViewport(botId, viewport),
+      viewportFor: (botId) => transcripts.viewportFor(botId),
+      forget: (botId) => {
+        transcripts.forget(botId);
+        if (botId === undefined || botId === restoredWithoutRead)
+          restoredWithoutRead = undefined;
+      },
+    },
     messages: [],
     pluginCatalog: [],
     packageCatalog: [],
@@ -1326,14 +1416,33 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       admissionObserver?.abort();
       runObserver?.abort();
       selectionGeneration += 1;
+      // The conversation being left is kept, so coming back to it is a paint
+      // and not a reload. The thread writes its scroll position onto this
+      // entry once Vue has flushed, while the DOM still holds it.
+      const leaving = web.value.activeBotId;
+      if (leaving) {
+        transcripts.save(leaving, {
+          conversationKey: conversationKeyFor(leaving),
+          messages: web.value.messages.map((message) => toRaw(message)),
+          ...(web.value.activeRun ? { activeRun: web.value.activeRun } : {}),
+          ...(web.value.activeRunId
+            ? { activeRunId: web.value.activeRunId }
+            : {}),
+          ...(web.value.runningRunId
+            ? { runningRunId: web.value.runningRunId }
+            : {}),
+        });
+      }
+      const restored = transcripts.take(botId, conversationKeyFor(botId));
+      restoredWithoutRead = restored && !restored.stale ? botId : undefined;
       web.value.activeBotId = botId;
       web.value.composerContext = botId;
       web.value.botSettings = undefined;
       web.value.modelReady = false;
-      web.value.messages = [];
-      web.value.activeRun = undefined;
-      web.value.activeRunId = undefined;
-      web.value.runningRunId = undefined;
+      web.value.messages = restored?.messages ?? [];
+      web.value.activeRun = restored?.activeRun;
+      web.value.activeRunId = restored?.activeRunId;
+      web.value.runningRunId = restored?.runningRunId;
       web.value.skillCatalog = [];
       web.value.approvals = [];
       web.value.tasks = [];
@@ -1380,6 +1489,11 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       // Reads already in flight answer with the conversation that just ended;
       // the epoch drops them instead of letting them redraw it.
       conversationGeneration += 1;
+      // The conversation just ended keeps none of this Bot's cache: its key
+      // moves with it, and the transcript behind it is not this one.
+      transcriptEpochs.set(botId, (transcriptEpochs.get(botId) ?? 0) + 1);
+      transcripts.forget(botId);
+      restoredWithoutRead = undefined;
       runObserver?.abort();
       runObserver = undefined;
       web.value.messages = [];
@@ -1793,8 +1907,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           return;
         updateSettingsLoadError(
           "bot",
-          error instanceof Error ? error.message : "Could not load settings",
+          presentClientFailureV1(error, "load this Bot's settings"),
         );
+        console.debug("bot settings load failed", clientFailureDetailV1(error));
       }
     },
     async saveBotProfile(profile: BotProfile): Promise<void> {
@@ -1909,7 +2024,11 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         if (generation !== userSettingsGeneration) return;
         updateSettingsLoadError(
           "user",
-          error instanceof Error ? error.message : "Could not load settings",
+          presentClientFailureV1(error, "load your settings"),
+        );
+        console.debug(
+          "user settings load failed",
+          clientFailureDetailV1(error),
         );
       }
     },
@@ -1971,7 +2090,11 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         if (catalogGeneration !== pluginCatalogGeneration) return;
         updateSettingsLoadError(
           "catalog",
-          error instanceof Error ? error.message : "Could not load Plugins",
+          presentClientFailureV1(error, "load your plugins"),
+        );
+        console.debug(
+          "plugin catalog load failed",
+          clientFailureDetailV1(error),
         );
       }
     },
@@ -2088,18 +2211,21 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         // fault, and the raw server sentence means nothing to a person — so it
         // is translated here and the surface renders it instead of the
         // "nothing matched your search" empty state.
-        const raw =
-          error instanceof Error ? error.message : "Could not load the Catalog";
+        // The one server sentence worth reading is the one that says there is
+        // nothing to read: everything else becomes the shared failure line,
+        // because a raw fault text means nothing to the person looking at it.
+        const detail = clientFailureDetailV1(error);
         web.value.packageCatalog = [];
         web.value.packageCatalogGeneration = undefined;
         updateSettingsLoadError(
           "package-catalog",
           /catalog generation was not found|Package Catalog is not configured/.test(
-            raw,
+            detail,
           )
             ? "No plugins are published for this deployment yet."
-            : `Plugins could not be loaded: ${raw}`,
+            : presentClientFailureV1(error, "load the plugin catalog"),
         );
+        console.debug("package catalog load failed", detail);
       }
     },
     async loadCatalogEntry(
@@ -2532,10 +2658,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
             generation === selectionGeneration &&
             web.value.activeBotId === botId
           )
-            web.value.settingsError =
-              error instanceof Error
-                ? error.message
-                : "Notification delivery failed";
+            web.value.settingsError = presentClientFailureV1(
+              error,
+              "show this Bot's notification",
+            );
         }
         return { accepted: true, runId: result.runId };
       } catch (error) {
@@ -2562,10 +2688,12 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         // draft back rather than the thread pretending it was sent.
         if (isCertainSendRefusalV1(error)) {
           removeMessages(web.value.messages, pendingRunId);
+          // A refusal's own sentence is the one the person needs — the send
+          // that was over the size limit is answered with the limit. Only a
+          // refusal carries one; anything else falls back to the shared line.
           const refusal =
-            error instanceof Error && error.message
-              ? error.message
-              : "That message didn't go through. Try sending it again.";
+            serverRefusalMessageV1(error) ??
+            presentClientFailureV1(error, "send that message");
           web.value.error = refusal;
           return { accepted: false, error: refusal };
         }
@@ -2638,22 +2766,28 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           return { accepted: false, error: UNREACHABLE_BOT_MESSAGE_V1 };
         }
         if (disposition === "not-admitted") {
+          // One affordance, not two. This used to be an assistant bubble
+          // *and* a banner, both reading "Turn was not admitted." — the Bot
+          // appearing to say a word the product does not use to a User whose
+          // typing had already been thrown away. The draft comes back to the
+          // composer (`FrockBotApp.sendMessage`), so sending again is the
+          // retry, and one system line says so.
+          const notAdmitted =
+            "Your message didn't go through. Try sending it again.";
           replaceMessage(web.value.messages, pendingRunId, {
             id: `${pendingRunId}:assistant`,
             runId: pendingRunId,
-            role: "assistant",
-            text: "Your message didn't go through. Try sending it again.",
+            role: "system",
+            text: notAdmitted,
             at: placeholderAt,
             status: "error",
+            // The same affordance an unreachable send gets: the draft is back
+            // in the composer, and this sends it again.
+            retry: "resend",
             tools: [],
             sends: [],
           });
-          web.value.error =
-            "Your message didn't go through. Try sending it again.";
-          return {
-            accepted: false,
-            error: "Your message didn't go through. Try sending it again.",
-          };
+          return { accepted: false, error: notAdmitted };
         }
         return { accepted: true, runId: pendingRunId };
       } finally {
@@ -2691,16 +2825,18 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       try {
         await ctx.transport.reconcileRun(botId, runId);
       } catch (error) {
-        web.value.settingsError =
-          error instanceof Error ? error.message : "Couldn't retry that.";
+        web.value.settingsError = presentClientFailureV1(
+          error,
+          "pick that reply back up",
+        );
       }
       try {
         await deliverNotifications(botId);
       } catch (error) {
-        web.value.settingsError =
-          error instanceof Error
-            ? error.message
-            : "Couldn't refresh this reply.";
+        web.value.settingsError = presentClientFailureV1(
+          error,
+          "refresh that reply",
+        );
       }
     },
     async stopRun(): Promise<void> {
@@ -2873,6 +3009,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
             web.value.activeBotId !== botId
           )
             return;
+          // An untopiced reset on a transcript this switch restored from
+          // memory is the reload the cache exists to avoid. It is answered
+          // once and only once: the next reset reads like any other.
+          if (topic === undefined && restoredWithoutRead === botId) {
+            restoredWithoutRead = undefined;
+            return;
+          }
+          restoredWithoutRead = undefined;
           await deliverNotifications(botId, generation);
         },
         status() {

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

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

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

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

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

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

package/src/client/skill-invocation.ts

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