@xzzpig/pi-tidy 0.0.0-stage → 0.1.0

package/src/messages/bash-mode-frame.ts

@@ -0,0 +1,112 @@
+/**
+ * `!` / `!!` bash runs — the commands the user types, not the agent's — in a
+ * rounded frame of their own.
+ *
+ * pi draws them between two full-width rules in `bashMode`, which reads like
+ * the agent's bash box with its frame missing. The frame here is tidy's, but
+ * marked as the user's: the user icon instead of the terminal one, the command
+ * behind the `!` or `!!` that was typed instead of `$`, and the user
+ * messages' color for the border. The agent's bash boxes change color with their
+ * state; this one keeps its color, and pi's own rows say how the run went
+ * (the spinner, `(exit 1)`, `(cancelled)`). `!!` — output kept out of the
+ * model's context — stays dim, as pi draws it.
+ *
+ * Everything under the command row is pi's own: the 20-row preview, `ctrl+o`,
+ * the truncation notice.
+ */
+
+import { BashExecutionComponent } from "@earendil-works/pi-coding-agent";
+import { highlightBashCommand } from "../tools/bash-highlight.ts";
+import { drawFrame, sameLines, stripBackgroundFills, trimBlankEdges } from "../draw/frame-draw.ts";
+import { MESSAGE_ICONS } from "../draw/icons.ts";
+import { liveSlot, tidyEnabled } from "../live.ts";
+import { paint } from "../draw/paint.ts";
+import { getTheme, type ThemeLike } from "../theme-access.ts";
+
+export interface BashModeOptions {
+  enabled: boolean;
+  icons: boolean;
+  /** The user messages' color (frame border or rail): a theme color name or `#rrggbb`. */
+  color: string;
+}
+
+interface BashExecutionInternals {
+  command: string;
+  /** `"dim"` for `!!`, `"bashMode"` for `!`. */
+  colorKey?: string;
+  contentContainer?: { children: Array<{ render(width: number): string[] }> };
+  render(width: number): string[];
+  __tidyBashModeCache?: { width: number; sample: string; raw: string[]; out: string[] };
+}
+
+const bashModeOptions = liveSlot<BashModeOptions | undefined>("bash-mode-options", undefined);
+
+/**
+ * `theme` with `fg` taking `#rrggbb` too, for `drawFrame`. Forwarded, not
+ * spread: pi's theme keeps its methods on the class prototype.
+ */
+function withHexColors(theme: ThemeLike): ThemeLike {
+  return { fg: (color, text) => paint(theme, color, text), bold: (text) => theme.bold(text) };
+}
+
+function commandRow(component: BashExecutionInternals, theme: ThemeLike, color: string, icons: boolean): string {
+  const excluded = component.colorKey === "dim";
+  const prompt = paint(theme, color, theme.bold(excluded ? "!! " : "! "));
+  let command: string;
+  try {
+    command = highlightBashCommand(component.command, (token, text) => theme.fg(token, text));
+  } catch {
+    command = component.command;
+  }
+  const icon = icons ? `${paint(theme, color, MESSAGE_ICONS.user)} ` : "";
+  return ` ${icon}${prompt}${command}`;
+}
+
+function renderBashMode(
+  component: BashExecutionInternals,
+  width: number,
+  theme: ThemeLike,
+  options: BashModeOptions,
+): string[] | undefined {
+  const container = component.contentContainer;
+  if (!container || typeof component.command !== "string") return undefined;
+  const color = component.colorKey === "dim" ? "dim" : options.color;
+
+  // Child 0 is pi's `$ command` header; the rows under it are kept as drawn.
+  const raw: string[] = [];
+  for (const child of container.children.slice(1)) raw.push(...child.render(width - 2));
+
+  const sample = paint(theme, color, "·");
+  const cache = component.__tidyBashModeCache;
+  if (cache && cache.width === width && cache.sample === sample && sameLines(cache.raw, raw)) return cache.out;
+
+  const body = trimBlankEdges(raw.map(stripBackgroundFills));
+  const content = [commandRow(component, theme, color, options.icons), ...(body.length > 0 ? ["", ...body] : [])];
+  const out = ["", ...drawFrame(content, width, withHexColors(theme), color)];
+  component.__tidyBashModeCache = { width, sample, raw, out };
+  return out;
+}
+
+/**
+ * Install the patch once; later calls (a `/reload`) only update the options it
+ * reads. `enabled: false`, `tidy.enabled: false`, a missing theme or a render
+ * error leaves pi's own drawing.
+ */
+export function patchBashExecutions(options: BashModeOptions): void {
+  bashModeOptions.set(options);
+  const proto = BashExecutionComponent.prototype as unknown as BashExecutionInternals & { __tidyBashMode?: boolean };
+  if (proto.__tidyBashMode) return;
+  proto.__tidyBashMode = true;
+
+  const originalRender = proto.render;
+  proto.render = function (this: BashExecutionInternals, width: number): string[] {
+    const live = bashModeOptions.get();
+    const theme = getTheme();
+    if (!theme || !live?.enabled || !tidyEnabled.get() || width < 6) return originalRender.call(this, width);
+    try {
+      return renderBashMode(this, width, theme, live) ?? originalRender.call(this, width);
+    } catch {
+      return originalRender.call(this, width);
+    }
+  };
+}

package/src/messages/error-lines.ts

@@ -0,0 +1,331 @@
+/**
+ * pi's own error rows — the ones that are not a tool result: a failed request,
+ * an extension that threw, a provider that dropped blocks. It builds each as a
+ * plain `ThemedText` (`Error: 429: {…}`) and appends it straight to the chat
+ * container, once per retry attempt.
+ *
+ * Two things are wrong with that: the attempt count never changes the text, so
+ * a retry storm leaves three identical rows carrying the provider's raw body;
+ * and the row has no frame, unlike every other box in the transcript.
+ *
+ * So exactly one row survives: a repeat of the same text folds into it with a
+ * `×N`, and that row wears the frame the rest of tidy's boxes wear. The rows
+ * are transport state, not conversation, but they are also the only record
+ * that a turn failed — dropping them all would leave the failure invisible.
+ *
+ * `ThemedText` is not exported and never reaches a class tidy could patch, so
+ * the hook is the container: after `InteractiveMode.init`, the chat container
+ * gets its own `addChild`. Rows not painted in the error colour (warnings,
+ * notes, dim asides) pass through untouched — a billing notice is information,
+ * and repeating one is a real event, not a retry.
+ */
+
+import { AssistantMessageComponent, InteractiveMode } from "@earendil-works/pi-coding-agent";
+import { type Component, Spacer, Text } from "@earendil-works/pi-tui";
+import { drawFrame, labeledTopBorder, stripBackgroundFills, trimBlankEdges, visibleText } from "../draw/frame-draw.ts";
+import { liveSlot, tidyEnabled } from "../live.ts";
+import { getTheme } from "../theme-access.ts";
+
+export interface ErrorLineOptions {
+  /** Fold a repeated error row into the first one as `×N`, and frame it. */
+  enabled: boolean;
+}
+
+const errorLineOptions = liveSlot<ErrorLineOptions>("error-line-options", { enabled: true });
+
+/** Marks a container already watching, so a second install can't double-wrap. */
+const INSTALLED = Symbol.for("pi-tidy:error-lines");
+const INIT_PATCH = Symbol.for("pi-tidy:error-lines-init");
+
+export interface ChatContainerLike {
+  children: Component[];
+  addChild(child: Component): void;
+}
+
+/** Wide enough that a probe render says what the row holds, not how it wraps. */
+const PROBE_WIDTH = 400;
+
+/** The escape `theme.fg(color, …)` opens with, for prefix matching. */
+function opener(color: string): string {
+  const probe = getTheme()?.fg(color, "\u0000") ?? "";
+  return probe.split("\u0000")[0] ?? "";
+}
+
+function rowsOf(component: Component): string[] {
+  try {
+    return component.render(PROBE_WIDTH).map(stripBackgroundFills);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The colour a row is painted in, when it is one of pi's status rows: pi wraps
+ * the whole line in a single `fg`, so the first visible row opens with it.
+ */
+function rowColor(rows: string[]): string | undefined {
+  const row = rows.find((line) => visibleText(line).trim() !== "");
+  if (!row) return undefined;
+  const painted = row.trimStart();
+  for (const color of ["error", "warning"]) {
+    const prefix = opener(color);
+    if (prefix && painted.startsWith(prefix)) return color;
+  }
+  return undefined;
+}
+
+function blankRows(rows: string[]): boolean {
+  return rows.every((line) => visibleText(line).trim() === "");
+}
+
+/**
+ * Give one row the error frame, labelled `label()` at draw time. Only `render`
+ * changes: the row keeps its identity, and nothing is drawn ahead of the frame.
+ */
+function frameErrorRow(child: Component, label: () => string, live?: () => boolean): void {
+  const unpainted = child.render.bind(child);
+  child.render = (width: number): string[] => {
+    if (live && !live()) return unpainted(width);
+    const theme = getTheme();
+    const w = Math.max(4, width);
+    const rows = trimBlankEdges(unpainted(Math.max(2, w - 2)).map(stripBackgroundFills));
+    if (rows.length === 0) return [];
+    // No theme yet: pi's shell hasn't painted anything either, so keep the
+    // rows exactly as pi drew them rather than inventing colours.
+    if (!theme) return rows;
+    const framed = drawFrame(rows, w, theme, "error");
+    framed[0] = labeledTopBorder(w, theme, "error", theme.fg("error", label()));
+    return framed;
+  };
+}
+
+/**
+ * Watch one chat container. `addChild` is the only seam, and the rows keep
+ * their identity: pi holds references to some of them (`removeChild` on the
+ * previous status line), so a repeat is simply not added and the survivor gets
+ * its own `render`.
+ */
+export function installErrorLines(container: ChatContainerLike): void {
+  const target = container as ChatContainerLike & { [INSTALLED]?: boolean };
+  if (target[INSTALLED]) return;
+  target[INSTALLED] = true;
+
+  const addChild = container.addChild.bind(container);
+  let kept: Component | undefined;
+  let keptText = "";
+  let keptCount = 0;
+
+  const reset = () => {
+    kept = undefined;
+    keptText = "";
+    keptCount = 0;
+  };
+
+  const adopt = (child: Component, text: string) => {
+    kept = child;
+    keptText = text;
+    keptCount = 1;
+    frameErrorRow(child, () => (keptCount > 1 ? `error ×${keptCount}` : "error"));
+  };
+
+  container.addChild = (child: Component) => {
+    // Only pi's status rows (a `Text`) and the spacers between them can take
+    // part, so nothing else is probed. A probe is a render outside the frame's
+    // top-to-bottom pass, and the tool grouping reads that order: a probed tool
+    // joined its group before the step that issued it (the step's thinking row
+    // then hung above the summary line), and a probed message, not filled in
+    // yet, read as a group boundary.
+    if (!(child instanceof Text) && !(child instanceof Spacer)) {
+      reset();
+      const message = child as AssistantLike;
+      if (message.contentContainer) chatOf.set(child, container);
+      addChild(child);
+      // A resumed session builds the message before adding it: it is already
+      // filled in, and only now has a place in the chat.
+      if (message.contentContainer) noteFailure(message, message.lastMessage);
+      return;
+    }
+    const rows = rowsOf(child);
+    // Separators neither repeat nor break a repeat: pi may space two attempts
+    // apart, and that should still read as one failure.
+    if (rows.length > 0 && blankRows(rows)) {
+      addChild(child);
+      return;
+    }
+    const isErrorRow =
+      tidyEnabled.get() && errorLineOptions.get().enabled && child instanceof Text && rowColor(rows) === "error";
+    if (!isErrorRow) {
+      reset();
+      addChild(child);
+      return;
+    }
+    const text = rows.map(visibleText).join("\n").trim();
+    // pi's "Retry failed after N attempts: <error>" closes a run of failed
+    // attempts: it says the same as their box, and says it last.
+    const run = failureOf.get(previousMessage(container, container.children.length) as object);
+    if (run?.error && text.includes(run.error)) {
+      run.closed = true;
+      for (const member of run.members) member.contentContainer?.clear?.();
+    }
+    if (kept && keptText === text && container.children.includes(kept)) {
+      keptCount++;
+      return;
+    }
+    adopt(child, text);
+    addChild(child);
+  };
+}
+
+const ASSISTANT_PATCH = Symbol.for("pi-tidy:error-lines-assistant");
+
+interface AssistantLike {
+  contentContainer?: { children?: Component[]; clear?: () => void };
+  lastMessage?: FailedMessageLike;
+}
+
+interface FailedMessageLike {
+  stopReason?: unknown;
+  content?: unknown;
+  errorMessage?: unknown;
+}
+
+/**
+ * pi retries a failed request as a new assistant message per attempt, each
+ * drawing the same `Error: 429 …`. Consecutive identical failures are one run:
+ * the first message keeps the box and counts `×N`, the others draw nothing.
+ * When pi gives up it adds "Retry failed after N attempts", and the run's box
+ * gives way to that row.
+ */
+interface FailureRun {
+  key: string;
+  error: string;
+  count: number;
+  members: AssistantLike[];
+  closed: boolean;
+}
+
+const failureOf = new WeakMap<object, FailureRun>();
+/** The chat each assistant message was added to: its place in the transcript. */
+const chatOf = new WeakMap<object, ChatContainerLike>();
+
+/** The message before position `index`, past spacers. Never rendered. */
+function previousMessage(container: ChatContainerLike, index: number): Component | undefined {
+  for (let i = index - 1; i >= 0; i--) {
+    const child = container.children[i];
+    if (!(child instanceof Spacer)) return child;
+  }
+  return undefined;
+}
+
+function isEmpty(message: FailedMessageLike): boolean {
+  return Array.isArray(message.content) && message.content.length === 0;
+}
+
+function noteFailure(component: AssistantLike, message: FailedMessageLike | undefined): void {
+  if (!message || failureOf.has(component) || !failedWithNothingElse(message)) return;
+  if (!tidyEnabled.get() || !errorLineOptions.get().enabled) return;
+  const container = chatOf.get(component);
+  if (!container) return;
+  const error = typeof message.errorMessage === "string" ? message.errorMessage : "";
+  const key = `${String(message.stopReason)}\u0000${error}`;
+  const index = container.children.indexOf(component as Component);
+  const run = index > 0 ? failureOf.get(previousMessage(container, index) as object) : undefined;
+  if (run && !run.closed && run.key === key && isEmpty(message)) {
+    run.count++;
+    run.members.push(component);
+    failureOf.set(component, run);
+  } else {
+    failureOf.set(component, { key, error, count: 1, members: [component], closed: false });
+  }
+  hideIfAbsorbed(component);
+}
+
+/** A repeat, or a run pi has closed, draws nothing. */
+function hideIfAbsorbed(component: AssistantLike): void {
+  const run = failureOf.get(component);
+  if (run && (run.closed || run.members[0] !== component)) component.contentContainer?.clear?.();
+}
+
+/**
+ * A request that fails for good never reaches the chat as a row of its own:
+ * pi ends the assistant message with `stopReason: "error"` and draws
+ * `Error: …` as the last line *inside* that message. A length stop does the
+ * same with "Response was truncated". Neither passes `addChild` on the chat, so
+ * they stayed bare while a retried failure wore the frame.
+ *
+ * Only a failure with nothing else to show is framed. After streamed text the
+ * line belongs to that text, and the settled reply may wear its own frame: a
+ * box inside it would be a frame in a frame. An abort is the user's own Esc,
+ * not a failure, and stays as pi drew it.
+ *
+ * The hook is `updateContent`, which rebuilds the message's rows: the line is
+ * found by what pi put there, never by rendering it.
+ */
+function patchAssistantErrors(): void {
+  const proto = (AssistantMessageComponent as unknown as { prototype?: Record<string | symbol, unknown> }).prototype;
+  if (!proto || proto[ASSISTANT_PATCH]) return;
+  const original = proto.updateContent;
+  if (typeof original !== "function") return;
+  proto[ASSISTANT_PATCH] = true;
+  proto.updateContent = function (this: AssistantLike, message: FailedMessageLike, ...rest: unknown[]) {
+    const result = (original as (...args: unknown[]) => unknown).call(this, message, ...rest);
+    if (failedWithNothingElse(message)) {
+      const last = this.contentContainer?.children?.at(-1);
+      if (last instanceof Text) {
+        frameErrorRow(
+          last,
+          () => {
+            const run = failureOf.get(this);
+            return run && run.count > 1 ? `error ×${run.count}` : "error";
+          },
+          () => tidyEnabled.get() && errorLineOptions.get().enabled,
+        );
+      }
+      noteFailure(this, message);
+      // pi rebuilds the rows on every update (a theme change, a thinking
+      // toggle): a message the run absorbed stays absorbed.
+      hideIfAbsorbed(this);
+    }
+    return result;
+  };
+}
+
+function failedWithNothingElse(message: FailedMessageLike | undefined): boolean {
+  if (!message || !Array.isArray(message.content)) return false;
+  if (message.stopReason !== "error" && message.stopReason !== "length") return false;
+  // pi leaves a failed tool call's error to the tool row, and draws nothing here.
+  if (message.stopReason === "error" && message.content.some((block) => block?.type === "toolCall")) return false;
+  return !message.content.some((block) => block?.type === "text" && typeof block.text === "string" && block.text.trim());
+}
+
+/**
+ * pi's interactive mode owns the chat container and hands it to nobody, so the
+ * instance is reached through `init`. A pi that renames that method leaves the
+ * hook uninstalled: rows then render as pi draws them, which is the behaviour
+ * before this patch and not a crash.
+ */
+export function patchErrorLines(options: ErrorLineOptions): void {
+  errorLineOptions.set(options);
+  patchAssistantErrors();
+  const proto = (InteractiveMode as unknown as { prototype?: Record<string | symbol, unknown> }).prototype;
+  if (!proto || proto[INIT_PATCH]) return;
+  const original = proto.init;
+  if (typeof original !== "function") return;
+  const init = original as (...args: unknown[]) => unknown;
+  proto[INIT_PATCH] = true;
+  proto.init = function (this: { chatContainer?: ChatContainerLike }, ...args: unknown[]) {
+    const install = () => {
+      const chat = this?.chatContainer;
+      if (chat && typeof chat.addChild === "function") installErrorLines(chat);
+    };
+    const result = init.apply(this, args);
+    if (result && typeof (result as Promise<unknown>).then === "function") {
+      return (result as Promise<unknown>).then((value) => {
+        install();
+        return value;
+      });
+    }
+    install();
+    return result;
+  };
+}

package/src/messages/extension-notice.ts

@@ -0,0 +1,204 @@
+/**
+ * What an extension's notice says, read from the message rather than from its
+ * renderer.
+ *
+ * A custom message whose renderer paints its own chrome gives Tidy nothing to
+ * work with: its rows are the extension's, and the one thing a reader needs
+ * from them — who it is about and how it went — is buried in styled text. Every
+ * notice an extension sends also carries the text the model read (`content`),
+ * and most carry structured `details`, so the label and the body can come from
+ * there instead and the frame stays Tidy's.
+ *
+ * pi-subagents names its notices `subagent…`; `subagent-notify`'s
+ * `details.runs` is documented (its `docs/extension-api.md`, "Host session
+ * lifetime and completion wakes"), and the other types are read field by field
+ * with a fallback — a notice that names nobody is still drawn, just with the
+ * glyph alone.
+ */
+
+export type NoticeTone = "success" | "error" | "warning";
+
+/** The label a notice wears in its frame. Both halves are optional. */
+export interface NoticeLabel {
+  /** Who the notice is about: a subagent's name, when the message carries one. */
+  name?: string;
+  /** What happened, in the plugin's own words. */
+  status?: string;
+  /** A theme color for the border; Tidy's `custom` color when nothing says. */
+  tone?: NoticeTone;
+}
+
+interface NoticeMessage {
+  customType?: unknown;
+  content?: unknown;
+  details?: unknown;
+}
+
+/** pi-subagents' own `STATUS_TONES`, word for word: what a status means to a reader. */
+const STATUS_TONES: Record<string, NoticeTone> = {
+  completed: "success",
+  failed: "error",
+  partial: "error",
+  blocked: "error",
+  unhandled: "error",
+  "save failed": "error",
+  "reconciliation failed": "error",
+  blocker: "error",
+  paused: "warning",
+  stopped: "warning",
+  recovered: "warning",
+  unanswered: "warning",
+  concern: "warning",
+  interrupted: "warning",
+  "timed out": "warning",
+  "could not be reconciled": "warning",
+  "needs attention": "warning",
+  "needs a decision": "warning",
+  "needs clarification": "warning",
+  decision: "warning",
+  "interview request": "warning",
+  progress_update: "warning",
+};
+
+/** Fields a notice may carry the subject of, in the order worth trying. */
+const NAME_FIELDS = ["agent", "childKey", "workflowKey", "runId"];
+/** Fields that say how it went, in the order worth trying. */
+const STATUS_FIELDS = ["status", "outcome", "state", "severity", "reason"];
+
+const controlNotice = "subagent_control_notice";
+const completionNotice = "subagent-notify";
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+
+/**
+ * A notice Tidy draws itself: pi-subagents' whole namespace. Other extensions
+ * keep their renderer — their message body is not known to be text.
+ */
+export function isNoticeType(customType: unknown): customType is string {
+  return typeof customType === "string" && customType.startsWith("subagent");
+}
+
+/**
+ * Every run a completion notice reports, or nothing. All or nothing: a list
+ * with one unreadable entry says nothing trustworthy about the notice.
+ */
+function runs(details: unknown): Array<{ agent: string; status: string }> | undefined {
+  const list = record(details)?.runs;
+  if (!Array.isArray(list) || list.length === 0) return undefined;
+  const parsed = list.flatMap((run) => {
+    const entry = record(run);
+    return typeof entry?.agent === "string" && typeof entry?.status === "string"
+      ? [{ agent: entry.agent, status: entry.status }]
+      : [];
+  });
+  return parsed.length === list.length ? parsed : undefined;
+}
+
+/** Worst tone of a group: an error outranks a warning, a warning ranks a success. */
+function worstTone(list: Array<{ status: string }>): NoticeTone | undefined {
+  const tones = list.map((run) => STATUS_TONES[run.status]);
+  return tones.includes("error") ? "error" : tones.includes("warning") ? "warning" : tones.includes("success") ? "success" : undefined;
+}
+
+/** Words in a notice's type name that say what kind of message it is, not what it is about. */
+const KIND_NOISE = new Set(["notice", "warning", "message", "notify", "update"]);
+
+/**
+ * What kind of notice this is, from its type name: `subagent_watchdog_warning`
+ * is a watchdog. Used when the message names nobody, so the row still says
+ * something — the glyph alone cannot say whether it is a run or a watchdog.
+ */
+function kindOf(customType: string): string | undefined {
+  const words = customType
+    .replace(/^subagent[-_]?/, "")
+    .split(/[-_]/)
+    .filter((word) => word && !KIND_NOISE.has(word.toLowerCase()));
+  return words.length > 0 ? words.join(" ") : undefined;
+}
+
+/** The label for a notice, or undefined when this message is not one. */
+export function noticeLabel(message: NoticeMessage | undefined): NoticeLabel | undefined {
+  const type = message?.customType;
+  if (!isNoticeType(type)) return undefined;
+  const details = record(message?.details);
+
+  if (type === controlNotice) {
+    const event = record(details?.event);
+    const name = event?.agent;
+    const status = event?.type;
+    if (typeof name !== "string" || typeof status !== "string") return {};
+    return { name, status: status.replaceAll("_", " "), tone: "warning" };
+  }
+
+  if (type === completionNotice) {
+    const list = runs(message?.details);
+    if (!list) return {};
+    if (list.length === 1) {
+      const [run] = list as [{ agent: string; status: string }];
+      return { name: run.agent, status: run.status, tone: STATUS_TONES[run.status] };
+    }
+    return { status: `${list.length} background runs`, tone: worstTone(list) };
+  }
+
+  // The rest of pi-subagents' notices each carry part of it: `agent` and
+  // `outcome` for a wait, `childKey` and `outcome` for a workflow child,
+  // `severity` for a watchdog warning. Whatever is missing is simply not drawn.
+  const name = firstString(details, NAME_FIELDS) ?? kindOf(type);
+  const status = statusOf(details);
+  return {
+    ...(name ? { name } : {}),
+    ...(status ? { status: status.text, ...(status.tone ? { tone: status.tone } : {}) } : {}),
+  };
+}
+
+/** The first non-empty string among these fields. */
+function firstString(source: Record<string, unknown> | undefined, fields: readonly string[]): string | undefined {
+  for (const field of fields) {
+    const value = source?.[field];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return undefined;
+}
+
+/** The human words and the tone of whatever status field this notice carries. */
+function statusOf(details: Record<string, unknown> | undefined): { text: string; tone?: NoticeTone } | undefined {
+  for (const field of STATUS_FIELDS) {
+    const value = details?.[field];
+    if (typeof value !== "string" || !value.trim()) continue;
+    const text = value.replaceAll("_", " ");
+    const tone = STATUS_TONES[text] ?? STATUS_TONES[field];
+    return tone ? { text, tone } : { text };
+  }
+  return undefined;
+}
+
+/** The text the model read: a custom message's content, flattened to one string. */
+export function noticeText(message: NoticeMessage | undefined): string {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .flatMap((part) => {
+      const block = record(part);
+      return block?.type === "text" && typeof block.text === "string" ? [block.text] : [];
+    })
+    .join("\n");
+}
+
+/**
+ * The body of a notice: its text, minus the lines the frame's label already
+ * says. A completion notice opens with its own title, then with `<agent>:`, the
+ * child's answer underneath; both are the label again. Nothing is removed while
+ * the label says nothing — the first line is then the only summary there is —
+ * and nothing is removed when it would leave no text at all.
+ */
+export function noticeBodyText(message: NoticeMessage | undefined, label: NoticeLabel | undefined): string {
+  const text = noticeText(message);
+  if (!label || (!label.name && !label.status)) return text;
+  const [, ...rest] = text.split("\n");
+  const body = rest.slice(rest.findIndex((line) => line.trim() !== ""));
+  if (label.name && body[0]?.trim() === `${label.name}:`) body.shift();
+  while (body.length > 0 && body[0]!.trim() === "") body.shift();
+  return body.length > 0 ? body.join("\n") : text;
+}