@frockbot/plugin-shell 0.3.4 → 0.3.6

package/src/run-protocol.test.ts

@@ -22,6 +22,7 @@ import {
   projectClientRunLookupV1,
   projectClientRunListV1,
   projectClientRunV1,
+  projectClientRunOrDegradedV1,
   projectClientTurnV1,
 } from "./run-protocol.js";
 
@@ -1357,6 +1358,78 @@ describe("dispatched subagents in the run projection", () => {
     expect(() => decodeClientRunPageV1(tampered)).toThrow();
   });
 
+  test("a run whose record cannot be read degrades instead of failing the list", () => {
+    // One badly written record — a resolve that wrote a shape the record does
+    // not allow — used to answer 500 for the whole transcript, for good.
+    const broken = {
+      ...storedRun([], "running"),
+      status: "reconciliation-required",
+      phase: "executing",
+    } as unknown as StoredRun;
+    expect(() => projectClientRunV1(broken)).toThrow();
+
+    const degraded = projectClientRunOrDegradedV1(broken);
+    expect(degraded).toMatchObject({
+      runId: "run-events",
+      status: "failed",
+      outcome: { type: "failed" },
+    });
+    // And the degraded row is itself a valid projection, so the page decodes.
+    expect(
+      decodeClientRunPageV1(
+        createClientRunListV1([degraded], { truncated: false }),
+      ).runs,
+    ).toHaveLength(1);
+  });
+
+  test("an interrupted Turn keeps the text it had already streamed", () => {
+    const streamed: SessionEvent[] = [
+      event({
+        type: "assistant/chunk",
+        seq: 0,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: "The three things to know are",
+      }),
+      event({
+        type: "assistant/chunk",
+        seq: 1,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: " first, that",
+      }),
+    ];
+
+    for (const status of ["cancelled", "superseded"] as const) {
+      const projected = projectClientRunV1({
+        ...storedRun(streamed, status),
+        ...(status === "superseded"
+          ? {
+              supersededAt: "2026-08-28T00:00:05.000Z",
+              supersededBy: "run-next",
+            }
+          : {}),
+      });
+      expect(projected.outcome).toMatchObject({
+        type: status,
+        text: "The three things to know are first, that",
+      });
+      // And it survives the wire: the client reads it as the Turn's text, with
+      // the notice kept separately as the line that says why it stops there.
+      const decoded = decodeClientRunPageV1(
+        createClientRunListV1([projected], { truncated: false }),
+      ).runs[0];
+      expect(decoded?.responseText).toBe(
+        "The three things to know are first, that",
+      );
+      expect(decoded?.failure).toBeDefined();
+    }
+  });
+
   test("refuses a chip whose background flag is not a boolean", () => {
     const page = createClientRunListV1(
       [projectClientRunV1(storedRun([dispatched]))],

package/src/run-protocol.ts

@@ -52,6 +52,63 @@ export type ClientRunStatusV1 =
 const CANCELLED_RUN_MESSAGE = "Stopped by an authenticated Stop command.";
 const SUPERSEDED_RUN_MESSAGE = "Interrupted by your next message.";
 
+/**
+ * Why the Bot declined to admit a Turn. A refusal is an ordinary answer — the
+ * Bot is busy with a Turn this command did not ask to replace, is holding an
+ * effect only a User can settle, or the command was fenced or already used —
+ * so the client shows the reason and keeps the person's text rather than
+ * treating it as a failure of the send.
+ */
+export type ClientTurnRefusalReasonV1 =
+  "busy" | "reconciliation-required" | "fenced" | "duplicate";
+
+/** The versioned body a refused Turn answers with, decoded by the client. */
+export interface ClientTurnRefusalV1 {
+  schemaVersion: 1;
+  status: "refused";
+  reason: ClientTurnRefusalReasonV1;
+  error: string;
+}
+
+const TURN_REFUSAL_REASONS_V1: readonly ClientTurnRefusalReasonV1[] = [
+  "busy",
+  "reconciliation-required",
+  "fenced",
+  "duplicate",
+];
+
+/** The refusal a response body carries, or `undefined` when it carries none. */
+export function decodeClientTurnRefusalV1(
+  value: unknown,
+): ClientTurnRefusalV1 | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const body = value as Record<string, unknown>;
+  if (body.schemaVersion !== 1 || body.status !== "refused") return undefined;
+  if (typeof body.error !== "string") return undefined;
+  const reason = TURN_REFUSAL_REASONS_V1.find(
+    (candidate) => candidate === body.reason,
+  );
+  if (!reason) return undefined;
+  return {
+    schemaVersion: 1,
+    status: "refused",
+    reason,
+    error: wireString(body, "error", MAX_FAILURE_BYTES, "turn refusal"),
+  };
+}
+
+/**
+ * A refusal, as an error, because that is how a transport reports a non-2xx.
+ * The reason survives on the error so the client can tell "the Bot said no"
+ * from "the send may or may not have happened".
+ */
+export class ClientTurnRefusedErrorV1 extends Error {
+  constructor(readonly refusal: ClientTurnRefusalV1) {
+    super(refusal.error);
+    this.name = "ClientTurnRefusedErrorV1";
+  }
+}
+
 export type ClientRunEventV1 =
   | {
       type: "run/events-truncated";
@@ -122,9 +179,19 @@ export interface ClientDynamicToolCallInputV1 {
 
 export type ClientRunOutcomeV1 =
   | { type: "completed"; text: string }
-  | { type: "failed"; message: string }
-  | { type: "cancelled"; message: string }
-  | { type: "superseded"; message: string };
+  /**
+   * A Turn that broke keeps what it had already said, for the same reason a
+   * stopped one does: the words arrived, the person read them, and replacing
+   * them with a notice would rewrite what they watched happen (ADR 0028).
+   */
+  | { type: "failed"; message: string; text?: string }
+  /**
+   * A Turn a Stop or a later message ended keeps what it had already said:
+   * `text` is that partial answer, and `message` is the line saying why it
+   * ends where it does (ADR 0024).
+   */
+  | { type: "cancelled"; message: string; text?: string }
+  | { type: "superseded"; message: string; text?: string };
 
 export interface ClientRunRecoveryV1 {
   action: "resume";
@@ -565,6 +632,33 @@ function visibleEvents(
   return projection;
 }
 
+/**
+ * What an interrupted Turn had already said, read back out of its journal.
+ *
+ * The kernel records a Turn's answer as it streams, so a Turn stopped or
+ * superseded mid-sentence still holds every word it sent. It never reached a
+ * `responseText`, because it never completed — but the partial answer is a
+ * 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 } {
+  let requestId: string | undefined;
+  let text = run.responseText ?? "";
+  for (const event of run.events) {
+    if (event.type === "assistant/chunk") {
+      if (event.requestId !== requestId) {
+        requestId = event.requestId;
+        text = "";
+      }
+      text += event.text;
+    } else if (event.type === "assistant/message") {
+      requestId = event.requestId;
+      text = event.text;
+    }
+  }
+  return text ? { text: truncateWireString(text, MAX_OUTCOME_BYTES) } : {};
+}
+
 function runStatus(run: StoredRun): ClientRunStatusV1 {
   return requireStoredRunV1(run).status;
 }
@@ -584,16 +678,19 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
               run.failure ?? "Agent request failed.",
               MAX_FAILURE_BYTES,
             ),
+            ...interruptedOutcomeTextV1(run),
           } satisfies ClientRunOutcomeV1)
         : status === "cancelled"
           ? ({
               type: "cancelled",
               message: CANCELLED_RUN_MESSAGE,
+              ...interruptedOutcomeTextV1(run),
             } satisfies ClientRunOutcomeV1)
           : status === "superseded"
             ? ({
                 type: "superseded",
                 message: SUPERSEDED_RUN_MESSAGE,
+                ...interruptedOutcomeTextV1(run),
               } satisfies ClientRunOutcomeV1)
             : undefined;
   const recovery =
@@ -695,6 +792,39 @@ export function projectClientTurnV1(result: BotTurnCompletion): ClientTurnV1 {
   };
 }
 
+/**
+ * One stored run on the wire, degraded rather than thrown when the record
+ * cannot be read.
+ *
+ * A single unreadable run — an older shape, or one a bug wrote badly — used to
+ * fail the whole transcript: `GET /turns` answered 500 for every request after
+ * it, and the person's entire conversation disappeared behind one bad row. The
+ * transcript keeps its shape and says which Turn it could not read.
+ */
+export function projectClientRunOrDegradedV1(run: StoredRun): ClientRunV1 {
+  try {
+    return projectClientRunV1(run);
+  } catch {
+    const admittedAt =
+      typeof run.acceptedAt === "string" &&
+      Number.isFinite(Date.parse(run.acceptedAt))
+        ? run.acceptedAt
+        : new Date(0).toISOString();
+    return {
+      schemaVersion: 2,
+      runId: truncate(String(run.runId ?? "unknown"), MAX_RUN_ID_LENGTH),
+      admittedAt,
+      input: typeof run.input === "string" ? run.input : "",
+      status: "failed",
+      events: [],
+      outcome: {
+        type: "failed",
+        message: "This Turn's record could not be read.",
+      },
+    };
+  }
+}
+
 export function projectClientRunListV1(
   runs: readonly StoredRun[],
 ): ClientRunListV1 {
@@ -997,29 +1127,42 @@ function decodeOutcome(
     };
   }
   if (outcome.type === "failed" && runStatus === "failed") {
-    exactKeys(outcome, ["type", "message"], "run.outcome");
+    exactKeys(outcome, ["type", "message", "text"], "run.outcome");
     return {
       type: "failed",
       message: wireString(outcome, "message", MAX_FAILURE_BYTES, "run.outcome"),
+      ...decodeInterruptedTextV1(outcome),
     };
   }
   if (outcome.type === "cancelled" && runStatus === "cancelled") {
-    exactKeys(outcome, ["type", "message"], "run.outcome");
+    exactKeys(outcome, ["type", "message", "text"], "run.outcome");
     return {
       type: "cancelled",
       message: wireString(outcome, "message", MAX_FAILURE_BYTES, "run.outcome"),
+      ...decodeInterruptedTextV1(outcome),
     };
   }
   if (outcome.type === "superseded" && runStatus === "superseded") {
-    exactKeys(outcome, ["type", "message"], "run.outcome");
+    exactKeys(outcome, ["type", "message", "text"], "run.outcome");
     return {
       type: "superseded",
       message: wireString(outcome, "message", MAX_FAILURE_BYTES, "run.outcome"),
+      ...decodeInterruptedTextV1(outcome),
     };
   }
   throw new Error("run.outcome does not match run.status");
 }
 
+/** The partial answer an interrupted Turn kept, when it said anything. */
+function decodeInterruptedTextV1(outcome: Record<string, unknown>): {
+  text?: string;
+} {
+  if (outcome.text === undefined) return {};
+  return {
+    text: wireString(outcome, "text", MAX_OUTCOME_BYTES, "run.outcome"),
+  };
+}
+
 function decodeRecovery(
   value: unknown,
   runStatus: ClientRunStatusV1,
@@ -1113,9 +1256,18 @@ function decodeRun(value: unknown): ClientRun {
     ...(stopRequestedAt ? { stopRequestedAt } : {}),
     ...(run.queued === true ? { queued: true as const } : {}),
     ...(outcome?.type === "completed" ? { responseText: outcome.text } : {}),
-    ...(outcome?.type === "failed" ? { failure: outcome.message } : {}),
-    ...(outcome?.type === "cancelled" ? { failure: outcome.message } : {}),
-    ...(outcome?.type === "superseded" ? { failure: outcome.message } : {}),
+    ...(outcome?.type === "failed"
+      ? {
+          failure: outcome.message,
+          ...(outcome.text ? { responseText: outcome.text } : {}),
+        }
+      : {}),
+    ...(outcome?.type === "cancelled" || outcome?.type === "superseded"
+      ? {
+          failure: outcome.message,
+          ...(outcome.text ? { responseText: outcome.text } : {}),
+        }
+      : {}),
     ...(recovery ? { failure: recovery.message, recovery } : {}),
   };
 }

package/src/shared.ts

@@ -101,6 +101,12 @@ export interface WebChatMessage {
    * reached, not a state the User has to understand.
    */
   pending?: boolean;
+  /**
+   * A line under the bubble saying why the Turn ends where it does — it was
+   * stopped, or a later message took its place. The text above it is what the
+   * Bot had already said, which it keeps (ADR 0024).
+   */
+  notice?: string;
   tools: WebToolActivity[];
   /** The typed payloads this Turn sent to the user, oldest first. */
   sends: WebSendPayload[];