@frockbot/plugin-shell 0.3.4 → 0.3.6

package/src/client/index.ts

@@ -53,7 +53,11 @@ import {
 import { MCP_OAUTH_CONNECTION_TYPE_ID } from "@frockbot/plugin-mcp/agent";
 import { decodeStartConnectionResultV1 } from "@frockbot/connection-core";
 import { decodeClientSkillCatalogV1 } from "../skill-protocol.js";
-import { decodeClientTurnV1 } from "../run-protocol.js";
+import {
+  ClientTurnRefusedErrorV1,
+  type ClientTurnRefusalReasonV1,
+  decodeClientTurnV1,
+} from "../run-protocol.js";
 import {
   decodeApprovalDecisionReceiptV1,
   decodeApprovalListViewV1,
@@ -240,16 +244,43 @@ function activeRunView(run: ClientRun): WebActiveRun | undefined {
       runId: run.runId,
       status: run.status,
       message: run.stopRequestedAt
-        ? "Stop accepted; reconciling the provider outcome before cancelling."
-        : (run.recovery?.message ??
-          run.failure ??
-          "This Turn requires provider reconciliation before it can continue."),
-      canResume: !run.stopRequestedAt && run.recovery?.action === "resume",
+        ? "Stopping…"
+        : "Something went wrong mid-reply. Try again to pick it up.",
+      // Offered whenever the run is parked, Stop included. Hiding it there
+      // hid it in exactly the case Stop creates: a Turn that was stopped
+      // while the model was mid-answer parks, and the person was left with a
+      // banner and no way to act on it.
+      canResume: run.recovery?.action === "resume",
     };
   }
   return undefined;
 }
 
+/**
+ * What a refused send tells the person. The refusal's own `error` names the
+ * durable invariant that declined it, which the debug surface needs and the
+ * composer does not, so the typed reason picks the sentence instead.
+ */
+function turnRefusalCopyV1(reason: ClientTurnRefusalReasonV1): string {
+  if (reason === "busy")
+    return "This Bot is still working on your last message.";
+  if (reason === "reconciliation-required")
+    return "This Bot's last reply stopped partway. Try again to continue it.";
+  if (reason === "duplicate") return "That message was already sent.";
+  return "That message didn't go through. Try sending it again.";
+}
+
+/**
+ * The Bot's voice is its sends. When a Turn delivered anything to the User the
+ * model's own assistant text is scratch space and the thread does not draw it
+ * (issue 153): drawing both is how a one-word reply arrived twice, once as the
+ * model's text and once as the bubble that was actually delivered.
+ */
+function visibleAssistantText(run: ClientRun, fallback = ""): string {
+  if (sendsFrom(run.events).length > 0) return "";
+  return run.responseText ?? fallback;
+}
+
 function isTerminalRun(run: ClientRun): boolean {
   return (
     run.status === "completed" ||
@@ -270,7 +301,7 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.responseText ?? "",
+      text: visibleAssistantText(run),
       status: "streaming",
       // A Turn that has not started shows nothing of its own: the greyed user
       // message is the whole of what the thread says about it.
@@ -287,7 +318,8 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.failure ?? "Interrupted by your next message.",
+      text: visibleAssistantText(run),
+      notice: "Interrupted by your next message.",
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -299,10 +331,7 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text:
-        run.recovery?.message ??
-        run.failure ??
-        "Provider reconciliation is required before this Turn can continue.",
+      text: "This reply stopped partway. Try again to continue it.",
       status: "reconciliation-required",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -314,21 +343,39 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.failure ?? "Stopped by an authenticated Stop command.",
+      text: visibleAssistantText(run),
+      notice: "You stopped this.",
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
       tasks: tasksFrom(run.events),
     };
   }
+  // A Turn that broke after it had started talking keeps what it said, with
+  // the reason underneath it — the treatment a stopped Turn already gets, for
+  // the same reason: the words arrived and the person read them (ADR 0028).
+  // A Turn that broke before saying anything is still just the reason.
+  if (run.status === "failed" && run.responseText) {
+    return {
+      id: `${run.runId}:assistant`,
+      runId: run.runId,
+      role: "assistant",
+      text: run.responseText,
+      notice: run.failure ?? "Agent request failed.",
+      status: "error",
+      tools: toolsFrom(run.events),
+      sends: sendsFrom(run.events),
+      tasks: tasksFrom(run.events),
+    };
+  }
   return {
     id: `${run.runId}:assistant`,
     runId: run.runId,
     role: "assistant",
     text:
       run.status === "failed"
-        ? (run.failure ?? "Agent request failed.")
-        : (run.responseText ?? notification?.body ?? ""),
+        ? "This Bot couldn't finish its reply. Try again."
+        : visibleAssistantText(run, notification?.body ?? ""),
     status: run.status === "failed" ? "error" : "completed",
     tools: toolsFrom(run.events),
     sends: sendsFrom(run.events),
@@ -420,8 +467,12 @@ export function projectDurableRuns(
     activeRun = activeRunView(run) ?? activeRun;
     if (run.status === "running" || run.status === "reconciliation-required") {
       busyRunId = run.runId;
-      if (!run.queued) runningRunId = run.runId;
     }
+    // Stop belongs to a Turn that is executing. A Turn parked on a
+    // reconciliation is busy but not running: there is nothing to stop, and
+    // offering it left a Stop button standing for good — across reloads,
+    // because the state it was keyed off never became terminal.
+    if (run.status === "running" && !run.queued) runningRunId = run.runId;
     if (notification && isTerminalRun(run)) {
       projected.add(notification.notificationId);
     }
@@ -439,7 +490,13 @@ export function projectDurableRuns(
     state.activeRunId = undefined;
   }
   if (runningRunId) state.runningRunId = runningRunId;
-  else if (state.runningRunId && terminalRunIds.has(state.runningRunId)) {
+  else if (
+    state.runningRunId &&
+    runs.some((run) => run.runId === state.runningRunId)
+  ) {
+    // The channel is carrying this run and it is not executing, whatever it
+    // settled as. A run the list does not carry yet is the one this tab just
+    // submitted, which keeps its Stop.
     state.runningRunId = undefined;
   }
   if (activeRun) state.activeRun = activeRun;
@@ -695,7 +752,7 @@ export function decodePluginCatalog(value: unknown): PluginCatalogItem[] {
     !Array.isArray(value.packages) ||
     value.packages.length > 256
   ) {
-    throw new Error("Application manifest is invalid");
+    throw new Error("FrockBot couldn't load this deployment. Reload the page.");
   }
   return value.packages.flatMap((candidate) => {
     if (
@@ -728,7 +785,9 @@ export function decodePluginCatalog(value: unknown): PluginCatalogItem[] {
           kind === "mobile",
       )
     ) {
-      throw new Error("Application Package metadata is invalid");
+      throw new Error(
+        "FrockBot couldn't load this deployment. Reload the page.",
+      );
     }
     const decoded = decodeFrockBotManifest({
       // v4, so a Capability carrying an admission ceiling decodes here too.
@@ -910,7 +969,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     web.value.activeRun = {
       runId,
       status: "running",
-      message: "Confirming whether this Turn was admitted.",
+      message: "Checking whether your message went through…",
       canResume: false,
     };
     if (!ctx.transport.lookupRun || !ctx.transport.fenceRunAdmission) {
@@ -950,7 +1009,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         reconciliationError = `${
           error instanceof Error
             ? error.message
-            : "Turn admission lookup failed"
+            : "Couldn't check on your message."
         } Retrying…`;
         web.value.settingsError = reconciliationError;
       }
@@ -982,7 +1041,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         ) {
           return;
         }
-        if (!run) throw new Error("Stopped Turn is unavailable");
+        if (!run) throw new Error("Couldn't load that reply.");
         if (web.value.settingsError === observationError) {
           web.value.settingsError = undefined;
         }
@@ -992,7 +1051,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       } catch (error) {
         if (signal.aborted) return;
         observationError = `${
-          error instanceof Error ? error.message : "Turn lookup failed"
+          error instanceof Error ? error.message : "Couldn't load that reply."
         } Retrying…`;
         web.value.settingsError = observationError;
       }
@@ -1180,7 +1239,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
 
   const web: Ref<ShellWebData> = ref({
     connection: "ready",
-    modelLabel: "Model unavailable",
+    modelLabel: "No model available — set one up in Models",
     modelReady: false,
     modelSource: "none",
     settingsAvailable: true,
@@ -1510,12 +1569,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       const botId = web.value.activeBotId;
       const catalog = web.value.packageUi;
       if (!post || !botId || !catalog || catalog.botId !== botId) {
-        throw new Error("Package UI is unavailable");
+        throw new Error("That plugin's page isn't available.");
       }
       if (!packageIframeToolAllowedV1(contribution, name)) {
-        throw new Error(
-          `Package "${contribution.packageId}" did not declare tool "${name}"`,
-        );
+        throw new Error(`That plugin isn't allowed to use ${name}.`);
       }
       const turn = decodeClientTurnV1(
         await post(
@@ -1942,9 +1999,22 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         updateSettingsLoadError("package-catalog");
       } catch (error) {
         if (generation !== packageCatalogGeneration) return;
+        // The gateway answers 404 `catalog generation was not found` when the
+        // deployment has published no Catalog at all. That is a state, not a
+        // 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";
+        web.value.packageCatalog = [];
+        web.value.packageCatalogGeneration = undefined;
         updateSettingsLoadError(
           "package-catalog",
-          error instanceof Error ? error.message : "Could not load the Catalog",
+          /catalog generation was not found|Package Catalog is not configured/.test(
+            raw,
+          )
+            ? "No plugins are published for this deployment yet."
+            : `Plugins could not be loaded: ${raw}`,
         );
       }
     },
@@ -1974,7 +2044,8 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       if (!settings || !ctx.transport.executeConfiguration) {
         throw new Error("Plugins are unavailable");
       }
-      if (!generation) throw new Error("The Catalog generation is unknown");
+      if (!generation)
+        throw new Error("The catalog isn't loaded yet. Try again in a moment.");
       const receipt = await ctx.transport.executeConfiguration({
         schemaVersion: 1,
         type: "user/install-package",
@@ -2257,8 +2328,8 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       if (result.status !== "applied") {
         throw new Error(
           result.status === "reconciliation-required"
-            ? "Connection revocation requires reconciliation"
-            : "Connection revocation failed",
+            ? "Disconnecting didn't finish. Try again."
+            : "Couldn't disconnect that account.",
         );
       }
     },
@@ -2296,6 +2367,12 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       const observed = web.value.activeRunId;
       const supersedes = observed ? { runId: observed } : {};
       web.value.activeRunId = pendingRunId;
+      // Stop is offered for the whole of the Turn the User just started, not
+      // only from the moment a projection happens to arrive. A send that
+      // supersedes a running Turn is the exception: the Turn Stop targets is
+      // still the one executing, and this one is queued behind it. The durable
+      // projection corrects both the instant it arrives.
+      if (!observed) web.value.runningRunId = pendingRunId;
       web.value.error = undefined;
       web.value.messages.push(
         {
@@ -2355,7 +2432,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           id: `${result.runId}:assistant`,
           runId: result.runId,
           role: "assistant",
-          text: result.text,
+          // The same rule the durable projection follows: a Turn that
+          // delivered something speaks through its sends, not through the
+          // model's own text (issue 153).
+          text: sendsFrom(result.events).length > 0 ? "" : result.text,
           at: optimisticAt,
           status: "completed",
           tools: toolsFrom(result.events),
@@ -2380,15 +2460,23 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           web.value.activeBotId !== botId
         )
           return { accepted: true, runId: pendingRunId };
+        // A refusal is a normal answer, not an uncertain send: the Bot
+        // declined and said why. Show that, drop the optimistic bubbles, and
+        // let the composer give the person their text back — fencing a run
+        // that was never admitted only threw the reason away.
+        if (error instanceof ClientTurnRefusedErrorV1) {
+          removeMessages(web.value.messages, pendingRunId);
+          const refusal = turnRefusalCopyV1(error.refusal.reason);
+          web.value.error = refusal;
+          return { accepted: false, error: refusal };
+        }
         const aborted =
           error instanceof DOMException && error.name === "AbortError";
         replaceMessage(web.value.messages, pendingRunId, {
           id: `${pendingRunId}:assistant`,
           runId: pendingRunId,
           role: "assistant",
-          text: aborted
-            ? "Request stopped locally; checking whether it started."
-            : "Confirming whether this Turn was admitted.",
+          text: "Checking whether your message went through…",
           at: optimisticAt,
           status: "interrupted",
           tools: [],
@@ -2417,14 +2505,18 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
             id: `${pendingRunId}:assistant`,
             runId: pendingRunId,
             role: "assistant",
-            text: "Turn was not admitted.",
+            text: "Your message didn't go through. Try sending it again.",
             at: optimisticAt,
             status: "error",
             tools: [],
             sends: [],
           });
-          web.value.error = "Turn was not admitted";
-          return { accepted: false, error: "Turn was not admitted" };
+          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: true, runId: pendingRunId };
       } finally {
@@ -2435,18 +2527,26 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         ) {
           web.value.activeRunId = undefined;
         }
+        // The optimistic Stop target goes with it: a Turn nobody is running is
+        // not a Turn anybody can stop.
+        if (
+          web.value.runningRunId === pendingRunId &&
+          web.value.activeRunId !== pendingRunId
+        ) {
+          web.value.runningRunId = undefined;
+        }
       }
     },
     async resumeRun(runId: string): Promise<void> {
       if (!ctx.transport.reconcileRun) {
-        web.value.settingsError = "Turn reconciliation is unavailable";
+        web.value.settingsError = "Can't retry this right now.";
         return;
       }
       if (web.value.activeRun?.runId !== runId) return;
       web.value.activeRun = {
         runId,
         status: "running",
-        message: "Reconciliation requested; checking progress.",
+        message: "Retrying…",
         canResume: false,
       };
       const botId = web.value.activeBotId;
@@ -2455,7 +2555,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         await ctx.transport.reconcileRun(botId, runId);
       } catch (error) {
         web.value.settingsError =
-          error instanceof Error ? error.message : "Reconciliation failed";
+          error instanceof Error ? error.message : "Couldn't retry that.";
       }
       try {
         await deliverNotifications(botId);
@@ -2463,7 +2563,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         web.value.settingsError =
           error instanceof Error
             ? error.message
-            : "Could not refresh the reconciled Turn";
+            : "Couldn't refresh this reply.";
       }
     },
     async stopRun(): Promise<void> {
@@ -2606,6 +2706,70 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     },
   );
 
+  /*
+   * A running Turn reaches every browser that is looking, not only the one
+   * holding its POST.
+   *
+   * The reply to `POST /api/bots/:bot/turns` is one client's copy of a Turn.
+   * A reload, a second tab, or a dropped request has no such copy, so the
+   * transcript would sit on a spinner until somebody reloaded again. Two
+   * seams close that: the Bot's state channel pushes a `runs` invalidation
+   * whenever the durable run records move, and — for any client that has no
+   * socket — the run is polled to its terminal state. Both end in the same
+   * `GET /api/bots/:bot/turns` projection, so neither invents client state
+   * and the one-bubble-per-send contract is untouched.
+   */
+  let stopRunChannel: (() => void) | undefined;
+  const stopRunChannelWatch = watch(
+    () => web.value.activeBotId,
+    (botId) => {
+      stopRunChannel?.();
+      stopRunChannel = undefined;
+      if (!botId || !ctx.transport.watchBotState) return;
+      const generation = selectionGeneration;
+      stopRunChannel = ctx.transport.watchBotState(botId, {
+        async invalidate(topic) {
+          // A reset carries no topic and means "read everything again".
+          if (topic !== undefined && topic !== "runs") return;
+          if (
+            generation !== selectionGeneration ||
+            web.value.activeBotId !== botId
+          )
+            return;
+          await deliverNotifications(botId, generation);
+        },
+        status() {
+          // The channel's health is not the transcript's: an unavailable
+          // socket falls back to the observation below, which is what a
+          // client without one uses anyway.
+        },
+      });
+    },
+    { immediate: true },
+  );
+
+  const stopRunObservation = watch(
+    () => [web.value.activeBotId, web.value.activeRunId] as const,
+    ([botId, runId]) => {
+      // The send path owns the run it started: its POST is the observation,
+      // and `stopRun` starts its own. This is for every other way a client
+      // finds itself watching a Turn it is not holding open.
+      if (!botId || !runId || activeRequest || runObserver) return;
+      const generation = selectionGeneration;
+      const observer = new AbortController();
+      runObserver = observer;
+      void observeRunUntilTerminal(botId, runId, generation, observer.signal)
+        .catch(() => {
+          // `observeRunUntilTerminal` reports its own failures; a rejection
+          // here would be an unhandled one.
+        })
+        .finally(() => {
+          if (runObserver === observer) runObserver = undefined;
+        });
+    },
+    { immediate: true },
+  );
+
   return [
     ctx.provide(clientSurfaceRegistryKey, surfaces),
     // The shared client projection is updated by the contracts lane. This cast
@@ -2624,6 +2788,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     () => {
       stopEntrySync();
       stopRunFollow();
+      stopRunChannelWatch();
+      stopRunChannel?.();
+      stopRunObservation();
       stopSourceFollow();
       for (const dispose of entryDisposers.splice(0).toReversed()) dispose();
       activeRequest?.abort();
@@ -2644,6 +2811,13 @@ function replaceMessage(
   if (index >= 0) messages[index] = replacement;
 }
 
+/** Takes back both optimistic lines of a send the Bot never admitted. */
+function removeMessages(messages: WebChatMessage[], runId: string): void {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.runId === runId) messages.splice(index, 1);
+  }
+}
+
 export default shellClientPlugin;
 
 /**

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

@@ -31,12 +31,14 @@ describe("model runtime presentation", () => {
       "Llama 3 · Ollama Cloud · Account model",
     );
     expect(modelRuntimeLabel({ ...label, source: "bot" })).toBe(
-      "Llama 3 · Ollama Cloud · Bot override",
+      "Llama 3 · Ollama Cloud · this Bot only",
     );
   });
 
   test("shows unavailable and backend failure states", () => {
-    expect(modelRuntimeLabel({ source: "none" })).toBe("Model unavailable");
+    expect(modelRuntimeLabel({ source: "none" })).toBe(
+      "No model available — set one up in Models",
+    );
     expect(
       modelRuntimeLabel({
         source: "account",

package/src/client/model-presentation.ts

@@ -14,13 +14,13 @@ export function modelRuntimeLabel(input: {
 }): string {
   if (input.failure) return input.failure;
   if (input.source === "none" || !input.providerModelId) {
-    return "Model unavailable";
+    return "No model available — set one up in Models";
   }
   const model =
     input.modelDisplayName ?? input.providerModelId ?? "Connected model";
   const provider = input.packageDisplayName ?? input.connectionDisplayName;
   const runtime = provider ? `${model} · ${provider}` : model;
-  if (input.source === "bot") return `${runtime} · Bot override`;
+  if (input.source === "bot") return `${runtime} · this Bot only`;
   if (input.source === "account") return `${runtime} · Account model`;
   return runtime;
 }

package/src/client/styles.css

@@ -290,13 +290,38 @@
   text-align: center;
 }
 
-/* An assistant Turn is its avatar and, once there is text, its bubble. */
+/*
+ * Why a Turn ends where it does — stopped, or replaced by a later message.
+ * Quiet, and under the answer rather than instead of it: the words the Bot
+ * already said are the Turn's content, and this is only its last line.
+ */
+.message-notice {
+  margin: 2px 0 0;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+}
+
+/*
+ * 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.
+ */
 .message-assistant {
   flex-direction: row;
   align-items: flex-start;
   gap: 8px;
 }
 
+.message-column {
+  display: flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 6px;
+}
+
 .bot-avatar {
   position: relative;
   display: grid;
@@ -411,6 +436,56 @@
   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;
+}
+
 /*
  * Dispatched subagents. A chip is deliberately quiet — a subagent is work the
  * Bot delegated, not something it said — and opens in place to the summary the