@frockbot/plugin-shell 0.3.12 → 0.3.14

package/src/run-failure-copy.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "bun:test";
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import { MODEL_FIRST_BYTE_DEADLINE_REASON_V1 } from "@frockbot/kernel-contracts";
+import {
+  knownFailureCopyV1,
+  RUN_FAILURE_COPY_V1,
+  RUN_FAILURE_FALLBACK_COPY_V1,
+  runFailureCopyV1,
+  USER_FACING_FAILURE_REASONS_V1,
+} from "./run-failure-copy.js";
+import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
+import type { StoredRun } from "./backend-contracts.js";
+import { projectClientRunV1 } from "./run-protocol.js";
+
+/**
+ * Words that describe the machine. Every one of them reached a chat bubble
+ * before this: the verification run read "Reconciliation was explicitly
+ * abandoned: Bot turn ended with outcome model-error: Flock AI keeps no durable
+ * copy of an interrupted response, so it cannot be recovered".
+ */
+const FORBIDDEN_V1 = [
+  "reconcil",
+  "outcome",
+  "durable",
+  "supersede",
+  "admission",
+  "provider",
+  "model-error",
+  "tool-error",
+  "turn/end",
+  "session event",
+  "run id",
+  "runid",
+];
+
+function assertPlainV1(copy: string): void {
+  const lowered = copy.toLowerCase();
+  for (const word of FORBIDDEN_V1) {
+    expect(lowered.includes(word)).toBe(false);
+  }
+  // A bare " run " is jargon; "running" and the like are not, so the check is
+  // on the word rather than the substring.
+  expect(/\brun(s|id)?\b/.test(lowered)).toBe(false);
+}
+
+const TIMESTAMP = "2026-09-04T00:00:00.000Z";
+let seq = 0;
+const turnEnd = (outcome: string) =>
+  ({
+    type: "turn/end",
+    turn: 1,
+    outcome,
+    seq: (seq += 1),
+    timestamp: TIMESTAMP,
+  }) as unknown as SessionEvent;
+
+function failedRun(failure: string, events: SessionEvent[]): StoredRun {
+  return {
+    runId: "run-1",
+    commandFingerprint: "fingerprint",
+    sessionId: "user:primary",
+    acceptedAt: TIMESTAMP,
+    input: "make me an applet",
+    events,
+    effectAdmissions: [],
+    status: "failed",
+    phase: "executing",
+    compositionGenerationId: "test-composition-generation",
+    configurationSnapshot: initializeBotSettingsV1("primary"),
+    previousEventCount: 0,
+    failure,
+  };
+}
+
+describe("runFailureCopyV1", () => {
+  test("every mapped sentence is written for a person", () => {
+    for (const copy of Object.values(RUN_FAILURE_COPY_V1)) assertPlainV1(copy);
+    assertPlainV1(RUN_FAILURE_FALLBACK_COPY_V1);
+    for (const reason of USER_FACING_FAILURE_REASONS_V1) assertPlainV1(reason);
+  });
+
+  test("the stored diagnostic never reaches the copy", () => {
+    const failure =
+      "Reconciliation was explicitly abandoned: Bot turn ended with outcome model-error: Flock AI keeps no durable copy of an interrupted response, so it cannot be recovered";
+    const copy = runFailureCopyV1({
+      failure,
+      events: [turnEnd("interrupted")],
+    });
+    expect(copy).toBe(RUN_FAILURE_COPY_V1.interrupted);
+    assertPlainV1(copy);
+  });
+
+  test("a kernel sentence written for a person survives its wrapper", () => {
+    const copy = runFailureCopyV1({
+      failure: `Model request "abc" has no durable provider outcome: Model response outcome is uncertain: ${MODEL_FIRST_BYTE_DEADLINE_REASON_V1}`,
+      events: [turnEnd("interrupted")],
+    });
+    expect(copy).toBe(MODEL_FIRST_BYTE_DEADLINE_REASON_V1);
+  });
+
+  test("a Turn with no terminal event still says something plain", () => {
+    expect(runFailureCopyV1({ failure: "boom" })).toBe(
+      RUN_FAILURE_FALLBACK_COPY_V1,
+    );
+  });
+
+  // The client's own guard, because a `ClientRun` can arrive from an older
+  // backend that forwarded the raw diagnostic, and the thread must not render
+  // a provider's words as though the Bot said them.
+  test("the thread accepts only sentences the product wrote", () => {
+    for (const written of [
+      ...Object.values(RUN_FAILURE_COPY_V1),
+      ...USER_FACING_FAILURE_REASONS_V1,
+    ]) {
+      expect(knownFailureCopyV1(written)).toBe(written);
+    }
+    for (const diagnostic of [
+      undefined,
+      "",
+      "Provider reconciliation is required",
+      "Bot turn ended with outcome model-error: Model request failed (401)",
+      'Skill "bot/no-such-skill" is unknown',
+    ]) {
+      const copy = knownFailureCopyV1(diagnostic);
+      expect(copy).toBe(RUN_FAILURE_FALLBACK_COPY_V1);
+      assertPlainV1(copy);
+    }
+  });
+
+  test("the projection sends the copy, not the diagnostic", () => {
+    const projected = projectClientRunV1(
+      failedRun(
+        "Reconciliation was explicitly abandoned: Bot turn ended with outcome model-error",
+        [
+          {
+            type: "turn/start",
+            turn: 1,
+            seq: (seq += 1),
+            timestamp: TIMESTAMP,
+          } as unknown as SessionEvent,
+          turnEnd("interrupted"),
+        ],
+      ),
+    );
+    expect(projected.outcome?.type).toBe("failed");
+    if (projected.outcome?.type !== "failed") throw new Error("unreachable");
+    assertPlainV1(projected.outcome.message);
+    expect(projected.outcome.message).toBe(RUN_FAILURE_COPY_V1.interrupted);
+  });
+});

package/src/run-failure-copy.ts

@@ -0,0 +1,110 @@
+import type { SessionEvent, TurnOutcome } from "@frockbot/kernel-contracts";
+import {
+  MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
+  MODEL_IDLE_DEADLINE_REASON_V1,
+} from "@frockbot/kernel-contracts";
+import { TURN_DEADLINE_REASON_V1 } from "@frockbot/kernel-agent-loop";
+import { UNRECONCILABLE_RUN_FAILURE_V1 } from "@frockbot/kernel-do";
+
+/**
+ * The one place a Turn that did not finish is turned into a sentence for the
+ * person who was waiting on it.
+ *
+ * A run's stored `failure` is a diagnostic. It is composed by whoever settled
+ * the run, out of whatever the layer below handed up, and it reads like it:
+ * "Reconciliation was explicitly abandoned: Bot turn ended with outcome
+ * model-error: Flock AI keeps no durable copy of an interrupted response, so it
+ * cannot be recovered". Every word of that is useful — on the debug surface,
+ * where it stays, unchanged. None of it belongs in a chat bubble. A person
+ * asked for a countdown applet; they should not have to learn what
+ * reconciliation is to find out that the model gave up.
+ *
+ * So the projection stops forwarding the diagnostic and picks the sentence
+ * instead. Two inputs, in order:
+ *
+ *  1. The kernel's own user-facing reasons. A handful of failures already have
+ *     a sentence written for a person — the model deadlines, the Turn deadline,
+ *     the unretrievable settlement — and those say something the outcome alone
+ *     cannot, so a stored failure that carries one hands it straight through.
+ *  2. Otherwise the Turn's terminal outcome, which is a closed set, mapped
+ *     below. It says less, and it can never leak.
+ *
+ * The diagnostic is never the answer, not even as a fallback: an unmapped
+ * outcome gets the generic line rather than whatever prose happened to be
+ * stored.
+ */
+
+/**
+ * Sentences the kernel writes for the person rather than for the log. They are
+ * matched as substrings because the layer that settles a run wraps the reason
+ * it was handed — the sentence survives the wrapping, the wrapper does not.
+ */
+export const USER_FACING_FAILURE_REASONS_V1: readonly string[] = [
+  MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
+  MODEL_IDLE_DEADLINE_REASON_V1,
+  TURN_DEADLINE_REASON_V1,
+  UNRECONCILABLE_RUN_FAILURE_V1,
+];
+
+/**
+ * What each terminal outcome says. Total over `TurnOutcome` so adding one to
+ * the kernel's union is a type error here rather than a silent generic line.
+ */
+export const RUN_FAILURE_COPY_V1: Record<TurnOutcome, string> = {
+  completed: "This Bot couldn't finish its reply. Try again.",
+  blocked: "This Bot wouldn't do that. Try asking a different way.",
+  cancelled: "You stopped this.",
+  interrupted: "This reply stopped before it finished. Try again.",
+  "model-error": "The model couldn't finish its reply. Try again.",
+  "tool-error": "Something the Bot was using didn't work. Try again.",
+};
+
+/** What a Turn says when nothing more specific is known about how it ended. */
+export const RUN_FAILURE_FALLBACK_COPY_V1 =
+  "This Bot couldn't finish its reply. Try again.";
+
+/** The outcome the run's own log records, or `undefined` on an unclosed Turn. */
+function terminalTurnOutcomeV1(
+  events: readonly SessionEvent[],
+): TurnOutcome | undefined {
+  const terminal = events.findLast((event) => event.type === "turn/end");
+  return terminal?.type === "turn/end" ? terminal.outcome : undefined;
+}
+
+export function runFailureCopyV1(input: {
+  failure?: string;
+  events?: readonly SessionEvent[];
+}): string {
+  const failure = input.failure ?? "";
+  const written = USER_FACING_FAILURE_REASONS_V1.find((reason) =>
+    failure.includes(reason),
+  );
+  if (written) return written;
+  const outcome = terminalTurnOutcomeV1(input.events ?? []);
+  return outcome ? RUN_FAILURE_COPY_V1[outcome] : RUN_FAILURE_FALLBACK_COPY_V1;
+}
+
+/**
+ * The product's own sentences, as a set a client can check a string against.
+ *
+ * The projection maps every failure through {@link runFailureCopyV1} on the way
+ * to the wire, so what reaches a client is already copy. The client still must
+ * not *trust* that: a `ClientRun` can arrive from an older backend that
+ * forwarded the raw diagnostic, and a provider's words under a bubble read as
+ * part of what the Bot was saying. So the thread accepts a failure only when it
+ * recognises it as something the product wrote, and otherwise says the generic
+ * line — which keeps the specific sentences (the model deadlines say something
+ * the outcome alone cannot) without ever letting an unknown string through.
+ */
+const KNOWN_FAILURE_COPY_V1 = new Set<string>([
+  ...Object.values(RUN_FAILURE_COPY_V1),
+  ...USER_FACING_FAILURE_REASONS_V1,
+  RUN_FAILURE_FALLBACK_COPY_V1,
+]);
+
+/** The failure if the product wrote it, else the line every failure can use. */
+export function knownFailureCopyV1(failure: string | undefined): string {
+  return failure && KNOWN_FAILURE_COPY_V1.has(failure)
+    ? failure
+    : RUN_FAILURE_FALLBACK_COPY_V1;
+}

package/src/run-protocol.test.ts

@@ -3,6 +3,7 @@ import { type SessionEvent } from "@frockbot/kernel-contracts";
 import { initializeBotSettingsV1 } from "@frockbot/configuration-core";
 import type { StoredRun } from "./backend-contracts.js";
 import { planBotRunRecovery } from "./backend-recovery.js";
+import { RUN_FAILURE_COPY_V1 } from "./run-failure-copy.js";
 import {
   createClientRunStopReceiptV1,
   decodeClientNotificationAcknowledgementCommandV1,
@@ -10,6 +11,7 @@ import {
   decodeClientRunLookupQueryV1,
   decodeClientRunReconciliationCommandV1,
   decodeClientRunStopCommandV1,
+  RESUMABLE_RUN_MESSAGE_V1,
   decodeClientRunStopReceiptV1,
   decodeClientTurnCommandV1,
   decodeClientRunLookupV1,
@@ -285,7 +287,7 @@ describe("client run protocol v1", () => {
       stopRequestedAt: "2026-08-28T00:00:05.000Z",
       outcome: {
         type: "cancelled",
-        message: "Stopped by an authenticated Stop command.",
+        message: "You stopped this.",
       },
     });
     expect(projectClientRunLookupV1(storedRun([], "cancelled"))).toMatchObject({
@@ -297,7 +299,7 @@ describe("client run protocol v1", () => {
       ).run,
     ).toMatchObject({
       status: "cancelled",
-      failure: "Stopped by an authenticated Stop command.",
+      failure: "You stopped this.",
     });
 
     expect(() =>
@@ -745,7 +747,7 @@ describe("client run protocol v1", () => {
           ],
           recovery: {
             action: "resume",
-            message: "Provider confirmation required",
+            message: RESUMABLE_RUN_MESSAGE_V1,
           },
         },
       ],
@@ -758,10 +760,10 @@ describe("client run protocol v1", () => {
         input: "continue",
         status: "reconciliation-required",
         events: projected.runs[0]?.events,
-        failure: "Provider confirmation required",
+        failure: RESUMABLE_RUN_MESSAGE_V1,
         recovery: {
           action: "resume",
-          message: "Provider confirmation required",
+          message: RESUMABLE_RUN_MESSAGE_V1,
         },
       },
     ]);
@@ -1278,14 +1280,18 @@ describe("client run protocol v1", () => {
       events,
       failure: plan.failure,
     });
+    // The provider's own words — its name, its status code — stay on the
+    // stored record, which is what the debug surface reads. What crosses to a
+    // chat bubble is the sentence for the outcome, and nothing else.
     expect(decodeClientRunLookupV1(structuredClone(lookup))).toMatchObject({
       state: "terminal",
       run: {
         status: "failed",
-        failure:
-          "Bot turn ended with outcome model-error: Ollama Cloud responded 401: invalid api key",
+        failure: RUN_FAILURE_COPY_V1["model-error"],
       },
     });
+    expect(JSON.stringify(lookup)).not.toContain("Ollama Cloud");
+    expect(JSON.stringify(lookup)).not.toContain("model-error");
   });
 
   test("carries rename announcements beside the Turns, and refuses a bad one", () => {

package/src/run-protocol.ts

@@ -24,6 +24,7 @@ import {
   type BotTurnCompletion,
   type StoredRun,
 } from "./backend-contracts.js";
+import { runFailureCopyV1 } from "./run-failure-copy.js";
 
 const MAX_RUN_ID_LENGTH = 128;
 const MAX_TIMESTAMP_LENGTH = 64;
@@ -54,8 +55,15 @@ export type ClientRunStatusV1 =
   | "superseded"
   | "reconciliation-required";
 
-const CANCELLED_RUN_MESSAGE = "Stopped by an authenticated Stop command.";
+// Both are sentences for the person, not descriptions of the mechanism: the
+// wire outcome is what a client with no copy of its own renders verbatim, and
+// "Stopped by an authenticated Stop command" told somebody who pressed Stop
+// about the authentication of their own button press.
+const CANCELLED_RUN_MESSAGE = "You stopped this.";
 const SUPERSEDED_RUN_MESSAGE = "Interrupted by your next message.";
+/** What a Turn waiting on a person's "Try again" says while it waits. */
+export const RESUMABLE_RUN_MESSAGE_V1 =
+  "This reply stopped partway. Try again to continue it.";
 
 /**
  * Why the Bot declined to admit a Turn. A refusal is an ordinary answer — the
@@ -836,8 +844,11 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
       : status === "failed"
         ? ({
             type: "failed",
+            // The stored `failure` is a diagnostic and stays one: it is what
+            // the debug surface reads. What crosses to a chat bubble is the
+            // sentence written for the person — see `runFailureCopyV1`.
             message: truncateWireString(
-              run.failure ?? "Agent request failed.",
+              runFailureCopyV1({ failure: run.failure, events: run.events }),
               MAX_FAILURE_BYTES,
             ),
             ...interruptedOutcomeTextV1(run),
@@ -859,11 +870,10 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
     status === "reconciliation-required"
       ? ({
           action: "resume",
-          message: truncateWireString(
-            run.failure ??
-              "Provider reconciliation is required before this Turn can continue.",
-            MAX_FAILURE_BYTES,
-          ),
+          // The stored failure is the diagnostic the debug surface reads; a
+          // person offered a "Try again" needs the sentence, not the reason
+          // the Bot cannot answer it on its own.
+          message: RESUMABLE_RUN_MESSAGE_V1,
         } satisfies ClientRunRecoveryV1)
       : undefined;
   return {

package/src/shared.ts

@@ -22,6 +22,10 @@ import type {
   SendToUserPayloadV1,
   SkillRefV1,
 } from "@frockbot/kernel-contracts";
+import type {
+  VoiceDictationObserverV1,
+  VoiceDictationSessionV1,
+} from "@frockbot/client-core";
 import type { McpServerStatusViewV1 } from "@frockbot/plugin-mcp/records";
 import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
 import type { ClientSkillCatalogEntryV1 } from "./skill-protocol.js";
@@ -256,6 +260,12 @@ export interface FrockBotWebData {
   modelSource: "bot" | "default" | "none";
   settingsAvailable: boolean;
   connectionsAvailable: boolean;
+  /**
+   * False when this platform cannot dictate — no transport socket, or a
+   * browser with no microphone API. The composer's send button then never
+   * changes shape and nothing about it moves.
+   */
+  voiceAvailable: boolean;
   activeBotId?: string;
   composerContext?: unknown;
   messages: WebChatMessage[];
@@ -511,6 +521,13 @@ export interface FrockBotWebData {
     skills?: readonly SkillRefV1[],
   ): Promise<SendPromptResult>;
   resumeRun(runId: string): Promise<void>;
+  /**
+   * Opens one dictation session (voice plan D2). `undefined` on a platform
+   * whose transport cannot, which is what `voiceAvailable` reports up front.
+   */
+  openVoiceDictation(
+    observer: VoiceDictationObserverV1,
+  ): VoiceDictationSessionV1 | undefined;
   /** Sends the durable Stop command for the observed active run. */
   stopRun(): Promise<void>;
   /** Detaches the local observer only; admitted work stays durable. */