@frockbot/plugin-shell 0.3.7 → 0.3.9

package/src/debug-protocol.test.ts

@@ -3,6 +3,7 @@ import {
   BOT_DEBUG_RUN_LIMIT_V1,
   boundDebugEventsV1,
   decodeBotDebugQueryV1,
+  isBotDebugQueryRefusalV1,
 } from "./debug-protocol.js";
 
 describe("debug query", () => {
@@ -36,13 +37,48 @@ describe("debug query", () => {
     ).toThrow("debug query has invalid fields");
   });
 
-  test("rejects a limit past the page bound", () => {
+  test("rejects a limit past the page bound, in words that name the range", () => {
     expect(() =>
       decodeBotDebugQueryV1({
         schemaVersion: 1,
         limit: BOT_DEBUG_RUN_LIMIT_V1 + 1,
       }),
-    ).toThrow("debug query limit is invalid");
+    ).toThrow(
+      `debug query limit must be a whole number from 1 to ${BOT_DEBUG_RUN_LIMIT_V1}`,
+    );
+  });
+
+  // The refusal rides on the error's name, which is all a Durable Object RPC
+  // preserves: a bad query has to arrive at the gateway as a 400 and not as
+  // an uncaught failure in the Bot's isolate.
+  test("refuses a bad query as a refusal, not as an ordinary failure", () => {
+    for (const input of [
+      { schemaVersion: 1, limit: 0 },
+      { schemaVersion: 1, limit: BOT_DEBUG_RUN_LIMIT_V1 + 1 },
+      { schemaVersion: 1, limit: 1.5 },
+      { schemaVersion: 1, limit: Number.NaN },
+      { schemaVersion: 1, sql: "select 1" },
+      { schemaVersion: 2 },
+      "not a query",
+    ]) {
+      let refusal: unknown;
+      try {
+        decodeBotDebugQueryV1(input);
+      } catch (error) {
+        refusal = error;
+      }
+      expect(isBotDebugQueryRefusalV1(refusal)).toBe(true);
+    }
+  });
+
+  test("accepts both ends of the allowed range", () => {
+    expect(decodeBotDebugQueryV1({ schemaVersion: 1, limit: 1 }).limit).toBe(1);
+    expect(
+      decodeBotDebugQueryV1({
+        schemaVersion: 1,
+        limit: BOT_DEBUG_RUN_LIMIT_V1,
+      }).limit,
+    ).toBe(BOT_DEBUG_RUN_LIMIT_V1);
   });
 
   test("rejects a wrong schema version", () => {

package/src/debug-protocol.ts

@@ -90,21 +90,50 @@ export interface BotDebugSnapshotV1 {
   nextCursor?: string;
 }
 
+/**
+ * A debug query the caller got wrong: an unknown field, a `limit` past the cap.
+ * The request is what is bad, not the Bot, so the surface owes a 400 rather
+ * than an uncaught failure in the isolate. The name is what carries that
+ * across the Durable Object RPC boundary — which keeps an error's `name` and
+ * `message` and drops everything else — exactly as `BotTurnRefusedError` does
+ * for a refused admission.
+ */
+export class BotDebugQueryRefusedErrorV1 extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BotDebugQueryRefusedErrorV1";
+  }
+}
+
+/** Whether an error — including one that has crossed RPC — is that refusal. */
+export function isBotDebugQueryRefusalV1(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    String((error as { name: unknown }).name) === "BotDebugQueryRefusedErrorV1"
+  );
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function boundedString(value: unknown, maximum: number, field: string): string {
   if (typeof value !== "string" || value.length < 1 || value.length > maximum) {
-    throw new Error(`debug query ${field} is invalid`);
+    throw new BotDebugQueryRefusedErrorV1(`debug query ${field} is invalid`);
   }
   return value;
 }
 
 export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
-  if (!isRecord(input)) throw new Error("debug query is invalid");
+  if (!isRecord(input)) {
+    throw new BotDebugQueryRefusedErrorV1("debug query is invalid");
+  }
   if (input.schemaVersion !== 1) {
-    throw new Error("debug query schemaVersion is invalid");
+    throw new BotDebugQueryRefusedErrorV1(
+      "debug query schemaVersion is invalid",
+    );
   }
   const allowed = new Set([
     "schemaVersion",
@@ -114,7 +143,7 @@ export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
     "events",
   ]);
   if (!Object.keys(input).every((key) => allowed.has(key))) {
-    throw new Error("debug query has invalid fields");
+    throw new BotDebugQueryRefusedErrorV1("debug query has invalid fields");
   }
   const query: BotDebugQueryV1 = { schemaVersion: 1 };
   if (input.runId !== undefined) {
@@ -129,13 +158,17 @@ export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
       (input.limit as number) < 1 ||
       (input.limit as number) > BOT_DEBUG_RUN_LIMIT_V1
     ) {
-      throw new Error("debug query limit is invalid");
+      throw new BotDebugQueryRefusedErrorV1(
+        `debug query limit must be a whole number from 1 to ${BOT_DEBUG_RUN_LIMIT_V1}`,
+      );
     }
     query.limit = input.limit as number;
   }
   if (input.events !== undefined) {
     if (typeof input.events !== "boolean") {
-      throw new Error("debug query events is invalid");
+      throw new BotDebugQueryRefusedErrorV1(
+        "debug query events must be true or false",
+      );
     }
     query.events = input.events;
   }

package/src/run-protocol.test.ts

@@ -24,6 +24,7 @@ import {
   projectClientRunV1,
   projectClientRunOrDegradedV1,
   projectClientTurnV1,
+  UNRECORDED_TOOL_RESULT_TEXT_V1,
 } from "./run-protocol.js";
 
 const timestamp = "2026-08-29T00:00:00.000Z";
@@ -1061,14 +1062,59 @@ describe("client run protocol v1", () => {
     expect(() => projectClientRunListV1([storedRun([result])])).toThrow(
       'tool result has no matching occurrence "tool:1:1:0"',
     );
-    expect(() => projectClientRunListV1([storedRun([call])])).toThrow(
-      'terminal run has no result for tool call "tool-1"',
-    );
     expect(() =>
       projectClientRunListV1([storedRun([call, call, result])]),
     ).toThrow('tool occurrence "tool:1:1:0" has duplicate intent');
   });
 
+  // A READ never throws on a record that is already durable. A settled Turn
+  // whose tool call was never settled used to fail the whole transcript
+  // endpoint — a 500 on every later request — so one malformed row bricked the
+  // conversation for ever. It degrades to a row saying nothing was recorded.
+  test("degrades a settled Turn's unsettled tool call instead of throwing", () => {
+    const call = toolEvents(1)[0]!;
+
+    const projected = projectClientRunListV1([storedRun([call])]).runs[0];
+
+    expect(projected?.events).toEqual([
+      { type: "tool/call", call: { id: "tool-1", name: "lookup" } },
+      {
+        type: "tool/result",
+        callId: "tool-1",
+        content: UNRECORDED_TOOL_RESULT_TEXT_V1,
+        isError: true,
+      },
+    ]);
+    // And the degraded row survives the wire decode, which used to refuse it
+    // for the same reason the projection did.
+    expect(
+      decodeClientRunListV1({
+        schemaVersion: 1,
+        runs: [projected],
+        page: { truncated: false },
+      })[0]?.events,
+    ).toHaveLength(2);
+  });
+
+  test("accepts a settled Turn on the wire whose call carries no result", () => {
+    const projected = projectClientRunListV1([storedRun([])]).runs[0]!;
+
+    expect(
+      decodeClientRunListV1({
+        schemaVersion: 1,
+        runs: [
+          {
+            ...projected,
+            events: [
+              { type: "tool/call", call: { id: "tool-1", name: "lookup" } },
+            ],
+          },
+        ],
+        page: { truncated: false },
+      })[0]?.events,
+    ).toEqual([{ type: "tool/call", call: { id: "tool-1", name: "lookup" } }]);
+  });
+
   test("retains pending calls only for nonterminal runs", () => {
     const call = toolEvents(1)[0]!;
     const projected = projectClientRunListV1([storedRun([call], "running")])
@@ -1430,6 +1476,87 @@ describe("dispatched subagents in the run projection", () => {
     }
   });
 
+  test("a running Turn projects the words it has written so far", () => {
+    const streamed: SessionEvent[] = [
+      event({
+        type: "assistant/chunk",
+        seq: 0,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: "Half a",
+      }),
+      event({
+        type: "assistant/chunk",
+        seq: 1,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: " thought",
+      }),
+    ];
+
+    const projected = projectClientRunV1(storedRun(streamed, "running"));
+    expect(projected.partialText).toBe("Half a thought");
+    expect(projected.outcome).toBeUndefined();
+
+    // And it survives the wire, so the thread draws it while the Turn runs.
+    const decoded = decodeClientRunPageV1(
+      createClientRunListV1([projected], { truncated: false }),
+    ).runs[0];
+    expect(decoded?.partialText).toBe("Half a thought");
+    expect(decoded?.responseText).toBeUndefined();
+  });
+
+  test("a running Turn that has said nothing carries no partial text", () => {
+    expect(projectClientRunV1(storedRun([], "running")).partialText).toBe(
+      undefined,
+    );
+  });
+
+  test("a later request restarts the partial answer", () => {
+    const streamed: SessionEvent[] = [
+      event({
+        type: "assistant/chunk",
+        seq: 0,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: "scratch",
+      }),
+      event({
+        type: "assistant/chunk",
+        seq: 1,
+        timestamp,
+        turn: 1,
+        step: 2,
+        requestId: "request-2",
+        text: "the answer",
+      }),
+    ];
+    expect(projectClientRunV1(storedRun(streamed, "running")).partialText).toBe(
+      "the answer",
+    );
+  });
+
+  test("a settled Turn carries its answer once, as an outcome", () => {
+    const projected = projectClientRunV1(storedRun([], "completed"));
+    expect(projected.partialText).toBeUndefined();
+    expect(projected.outcome).toMatchObject({ type: "completed" });
+
+    const page = createClientRunListV1([projected], { truncated: false });
+    const tampered = structuredClone(page) as unknown as {
+      runs: Array<Record<string, unknown>>;
+    };
+    tampered.runs[0]!.partialText = "words";
+    expect(() => decodeClientRunPageV1(tampered)).toThrow(
+      "only a running run may carry partial text",
+    );
+  });
+
   test("refuses a chip whose background flag is not a boolean", () => {
     const page = createClientRunListV1(
       [projectClientRunV1(storedRun([dispatched]))],

package/src/run-protocol.ts

@@ -220,6 +220,14 @@ export interface ClientRunV1 {
    * the flag is durable state, so a reload draws the same thing.
    */
   queued?: true;
+  /**
+   * The answer the Bot has written so far, present only while the run is still
+   * running and has produced text. The thread draws it in the bubble it is
+   * already drawing for the Turn, so a reply appears as it is written instead
+   * of arriving whole at settlement. A settled run carries its answer in
+   * `outcome` instead, and never both.
+   */
+  partialText?: string;
   outcome?: ClientRunOutcomeV1;
   recovery?: ClientRunRecoveryV1;
 }
@@ -500,6 +508,14 @@ interface ProjectionUnitV1 {
   droppable: boolean;
 }
 
+/**
+ * What a settled Turn's tool call shows when the durable record holds no
+ * result for it. Same register as the rest of the transcript copy: it tells
+ * the person what is missing rather than naming an occurrence id.
+ */
+export const UNRECORDED_TOOL_RESULT_TEXT_V1 =
+  "No result was recorded for this tool call.";
+
 function dynamicToolCallInput(
   value: unknown,
 ): ClientDynamicToolCallInputV1 | undefined {
@@ -658,12 +674,23 @@ function projectionUnits(
     }
   }
   if (isTerminalRunStatus(status)) {
-    const orphaned = units.find((unit) => !unit.droppable);
-    if (orphaned) {
-      const call = orphaned.events[0] as ClientToolCallV1;
-      throw new Error(
-        `terminal run has no result for tool call "${call.call.id}"`,
-      );
+    for (const unit of units) {
+      if (unit.droppable) continue;
+      // A settled Turn owes every tool call a result, and `Session`'s
+      // interruption repairs now write one. Records already durable from
+      // before that do not have it, and a READ must never throw on them: one
+      // malformed row used to brick the whole transcript endpoint for ever.
+      // The row degrades instead, and says exactly what is missing — not
+      // through `projectClientRunOrDegradedV1`, which throws the whole Turn
+      // away for an unreadable record. Everything else here is readable.
+      const call = unit.events[0] as ClientToolCallV1;
+      unit.events.push({
+        type: "tool/result",
+        callId: call.call.id,
+        content: UNRECORDED_TOOL_RESULT_TEXT_V1,
+        isError: true,
+      });
+      unit.droppable = true;
     }
   }
   return units;
@@ -719,10 +746,13 @@ function visibleEvents(
  * fact about what the person watched arrive, not a claim that the Turn
  * succeeded, and the thread keeps it instead of replacing it with a notice.
  */
-function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
+export function assistantTextSoFarV1(
+  events: readonly SessionEvent[],
+  responseText = "",
+): string {
   let requestId: string | undefined;
-  let text = run.responseText ?? "";
-  for (const event of run.events) {
+  let text = responseText;
+  for (const event of events) {
     if (event.type === "assistant/chunk") {
       if (event.requestId !== requestId) {
         requestId = event.requestId;
@@ -734,9 +764,31 @@ function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
       text = event.text;
     }
   }
+  return text;
+}
+
+function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
+  const text = assistantTextSoFarV1(run.events, run.responseText ?? "");
   return text ? { text: truncateWireString(text, MAX_OUTCOME_BYTES) } : {};
 }
 
+/**
+ * What a still-running Turn has said so far, read out of the same journal an
+ * interrupted one is read from.
+ *
+ * The kernel appends an `assistant/chunk` per provider text delta and each
+ * append lands on the run record, so the words are already durable while the
+ * Turn runs; nothing here is a second copy and nothing crosses the channel.
+ * Bounded exactly as an outcome is, because a long answer must not be able to
+ * grow the run list past its wire budget.
+ */
+function partialTextV1(run: StoredRun): { partialText?: string } {
+  const text = assistantTextSoFarV1(run.events);
+  return text
+    ? { partialText: truncateWireString(text, MAX_OUTCOME_BYTES) }
+    : {};
+}
+
 function runStatus(run: StoredRun): ClientRunStatusV1 {
   return requireStoredRunV1(run).status;
 }
@@ -791,6 +843,7 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
     input: truncateWireString(run.input, MAX_INPUT_BYTES),
     status,
     events: visibleEvents(run.events, status),
+    ...(status === "running" ? partialTextV1(run) : {}),
     ...(run.stopRequestedAt
       ? {
           stopRequestedAt: truncate(run.stopRequestedAt, MAX_TIMESTAMP_LENGTH),
@@ -1137,10 +1190,12 @@ function decodeEvent(value: unknown): ClientRunEventV1 {
   throw new Error("run event.type is invalid");
 }
 
-function decodeEvents(
-  values: unknown[],
-  runStatus: ClientRunStatusV1,
-): ClientTurnEvent[] {
+/**
+ * The event walk a wire run is decoded through. It no longer takes the run's
+ * status: a settled Turn's tool call with no result is a row the projection
+ * has already degraded, not a message to refuse.
+ */
+function decodeEvents(values: unknown[]): ClientTurnEvent[] {
   const events = values.map(decodeEvent);
   let index = 0;
   if (events[0]?.type === "run/events-truncated") index = 1;
@@ -1178,9 +1233,10 @@ function decodeEvents(
       index += 2;
       continue;
     }
-    if (isTerminalRunStatus(runStatus)) {
-      throw new Error(`terminal run has no result for tool call "${id}"`);
-    }
+    // A settled Turn whose call has no result is a degraded row, not a bad
+    // wire message: the projection above already renders it as "no result
+    // recorded", and refusing it here would put the whole transcript behind
+    // one durable record nobody can now repair.
     index += 1;
   }
   return events;
@@ -1278,6 +1334,7 @@ function decodeRun(value: unknown): ClientRun {
       "events",
       "stopRequestedAt",
       "queued",
+      "partialText",
       "outcome",
       "recovery",
     ],
@@ -1325,14 +1382,25 @@ function decodeRun(value: unknown): ClientRun {
   if (run.queued === true && runStatus !== "running") {
     throw new Error("only a running run may be queued");
   }
+  let partialText: string | undefined;
+  if (run.partialText !== undefined) {
+    // A settled run's answer is its outcome. Carrying both would give the
+    // thread two sources for one bubble, which is the duplication the
+    // one-bubble contract exists to prevent.
+    if (runStatus !== "running") {
+      throw new Error("only a running run may carry partial text");
+    }
+    partialText = wireString(run, "partialText", MAX_OUTCOME_BYTES, "run");
+  }
   return {
     runId,
     admittedAt,
     input: wireString(run, "input", MAX_INPUT_BYTES, "run"),
     status: runStatus,
-    events: decodeEvents(run.events, runStatus),
+    events: decodeEvents(run.events),
     ...(stopRequestedAt ? { stopRequestedAt } : {}),
     ...(run.queued === true ? { queued: true as const } : {}),
+    ...(partialText ? { partialText } : {}),
     ...(outcome?.type === "completed" ? { responseText: outcome.text } : {}),
     ...(outcome?.type === "failed"
       ? {
@@ -1454,7 +1522,7 @@ export function decodeClientTurnV1(input: unknown): ClientTurnResponse {
   return {
     runId,
     text: wireString(turn, "text", MAX_OUTCOME_BYTES, "turn"),
-    events: decodeEvents(turn.events, "completed"),
+    events: decodeEvents(turn.events),
     ...(notification ? { notification } : {}),
   };
 }

package/src/shared.ts

@@ -107,6 +107,13 @@ export interface WebChatMessage {
    * Bot had already said, which it keeps (ADR 0024).
    */
   notice?: string;
+  /**
+   * The line offers to send the draft again. Set only where the client gave
+   * up on its own — it could not reach the backend — because that is the one
+   * ending the person cannot act on from the thread otherwise: their text is
+   * back in the composer, and this is the button that sends it.
+   */
+  retry?: "resend";
   tools: WebToolActivity[];
   /** The typed payloads this Turn sent to the user, oldest first. */
   sends: WebSendPayload[];

package/src/unread.test.ts

@@ -13,6 +13,7 @@ import {
   optionalUnreadStateV1,
   projectBotUnreadViewV1,
   sidebarMessagePreviewForTurnV1,
+  sidebarMessagePreviewFromRunsV1,
   UNREAD_COUNT_CAP,
   type UnreadStateV1,
 } from "./unread.js";
@@ -235,6 +236,33 @@ describe("the unread projection", () => {
     expect(view).toMatchObject({ count: 0, capped: false, unread: false });
   });
 
+  // A Routine failing every minute left the badge at zero, because an
+  // automation Turn never advances the activity cursor.
+  test("badges a Bot whose Routine is failing, with nothing else unread", () => {
+    const view = projectBotUnreadViewV1(
+      "alpha",
+      emptyUnreadStateV1(),
+      index(3),
+      undefined,
+      2,
+    );
+    expect(view).toMatchObject({ count: 2, unread: true, capped: false });
+  });
+
+  test("adds Routine failures to the unread chat Turns", () => {
+    const state: UnreadStateV1 = {
+      schemaVersion: 1,
+      lastActivityCursor: cursor(3),
+      lastActivityAt: "2026-08-31T00:03:00.000Z",
+      lastSeenCursor: cursor(1),
+      lastViewedAt: "2026-08-31T00:01:00.000Z",
+      manuallyUnread: false,
+    };
+    expect(
+      projectBotUnreadViewV1("alpha", state, index(4), undefined, 1),
+    ).toMatchObject({ count: 3, unread: true });
+  });
+
   test("carries the already-bounded latest message without deriving it", () => {
     const preview = decodeSidebarMessagePreviewV1({
       schemaVersion: 1,
@@ -263,6 +291,73 @@ describe("the unread projection", () => {
   });
 });
 
+// The record is written at settlement, so a Bot whose Turns settled before
+// that projection existed has a full transcript and no preview — and its
+// sidebar row said "No messages yet" over six messages. A read derives it.
+describe("the sidebar preview derived from stored runs", () => {
+  const run = (over: Record<string, unknown> = {}) => ({
+    acceptedAt: "2026-08-31T00:02:00.000Z",
+    input: "What is the plan?",
+    responseText: "Here is the plan.",
+    status: "completed",
+    events: [{ timestamp: "2026-08-31T00:02:05.000Z" }],
+    ...over,
+  });
+
+  test("takes the newest settled chat Turn's reply, stamped when it settled", () => {
+    expect(sidebarMessagePreviewFromRunsV1([run()])).toEqual({
+      schemaVersion: 1,
+      text: "Here is the plan.",
+      at: "2026-08-31T00:02:05.000Z",
+      role: "assistant",
+    });
+  });
+
+  test("walks past a running Turn and an automation to the newest chat reply", () => {
+    expect(
+      sidebarMessagePreviewFromRunsV1([
+        run({ status: "running", responseText: undefined }),
+        run({
+          admission: { turnType: "automation" },
+          responseText: "Routine ran.",
+        }),
+        run({ responseText: "The older answer." }),
+      ]),
+    ).toMatchObject({ text: "The older answer.", role: "assistant" });
+  });
+
+  test("falls back to the User's own words when the reply was empty", () => {
+    expect(
+      sidebarMessagePreviewFromRunsV1([run({ responseText: "" })]),
+    ).toEqual({
+      schemaVersion: 1,
+      text: "What is the plan?",
+      at: "2026-08-31T00:02:00.000Z",
+      role: "user",
+    });
+  });
+
+  test("a Bot with no settled chat Turn still has no preview", () => {
+    expect(sidebarMessagePreviewFromRunsV1([])).toBeUndefined();
+    expect(
+      sidebarMessagePreviewFromRunsV1([
+        run({ status: "running", responseText: undefined, input: "" }),
+      ]),
+    ).toBeUndefined();
+  });
+
+  // A read of durable data never throws: a run whose stamps are unreadable
+  // costs the row, not the whole sidebar.
+  test("skips a run whose stored timestamps cannot be read", () => {
+    expect(
+      sidebarMessagePreviewFromRunsV1([
+        run({ acceptedAt: "not a time", events: [] }),
+        run({ responseText: "The readable one." }),
+      ]),
+    ).toMatchObject({ text: "The readable one." });
+  });
+});
+
 describe("the unread command", () => {
   test("decodes each type and refuses a mismatched cursor", () => {
     expect(