@jopqior/pi-subagents 1.0.0

package/src/observation/notification.ts

@@ -0,0 +1,430 @@
+import { debugLog } from "#src/debug";
+import type { SubagentStatus } from "#src/lifecycle/subagent-state";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
+import {
+  renderQuestionAffordance,
+  renderRunUpdates,
+  renderStatusLabel,
+  renderWorkspaceNotice,
+} from "#src/observation/outcome-delivery";
+import type { Subagent } from "#src/types";
+
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+  id: string;
+  description: string;
+  status: SubagentStatus;
+  toolUses: number;
+  turnCount: number;
+  maxTurns?: number;
+  totalTokens: number;
+  durationMs: number;
+  outputFile?: string;
+  error?: string;
+  resultPreview: string;
+}
+
+// ---- Pure helpers (exported for unit testing) ----
+
+/**
+ * Escape XML special characters to prevent injection in structured
+ * notifications. Quotes are escaped too, so values stay safe if they are ever
+ * placed in attribute position, not only element content.
+ */
+export function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/** Format a structured <task-notification> XML block for the parent agent to parse. */
+export function formatTaskNotification(record: Subagent, resultMaxLen: number): string {
+  if (record.stoppedWhileQueued) return formatNeverStartedNotification(record);
+
+  const status = renderStatusLabel(record.status, record.error);
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+  const contextPercent = record.getContextPercent();
+  const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
+  const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
+
+  const resultPreview = record.result
+    ? record.result.length > resultMaxLen
+      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      : record.result
+    : "No output.";
+
+  const toolCallId = record.toolCallId;
+  const outputFile = record.outputFile;
+  return joinNotificationLines([
+    "<task-notification>",
+    `<task-id>${record.id}</task-id>`,
+    toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
+    outputFile ? `<output-file>${escapeXml(outputFile)}</output-file>` : null,
+    `<status>${escapeXml(status)}</status>`,
+    `<summary>Subagent "${escapeXml(record.description)}" ${record.status}</summary>`,
+    `<result>${escapeXml(resultPreview)}</result>`,
+    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
+    "</task-notification>",
+  ]);
+}
+
+/**
+ * Format a `<workspace-notice>` block for what a teardown reported after the
+ * child's result had already been delivered.
+ *
+ * A distinct element from `<task-notification>`: the outcome was reported long
+ * ago and has not changed. This says only where the child's work ended up, so
+ * the parent's next action is to act on that artifact, never to collect a
+ * result it already has.
+ */
+export function formatWorkspaceNotice(record: Subagent, notice: string): string {
+  return joinNotificationLines([
+    "<workspace-notice>",
+    `<task-id>${record.id}</task-id>`,
+    `<summary>Subagent "${escapeXml(record.description)}" left work behind when its workspace was torn down</summary>`,
+    `<notice>${escapeXml(notice)}</notice>`,
+    "</workspace-notice>",
+  ]);
+}
+
+/**
+ * Format a `<subagent-update>` block for a message a still-running child sent.
+ *
+ * A distinct element from `<task-notification>`: the child has not finished, so
+ * the parent's next action is to steer it or leave it alone, never to collect a
+ * result that does not exist yet.
+ */
+export function formatUpdateNotification(record: Subagent, message: string): string {
+  return joinNotificationLines([
+    "<subagent-update>",
+    `<task-id>${record.id}</task-id>`,
+    `<summary>Subagent "${escapeXml(record.description)}" sent an update</summary>`,
+    `<message>${escapeXml(message)}</message>`,
+    "</subagent-update>",
+    `The agent is still running. Steer it with steer_subagent("${record.id}", "...") to redirect it, or let it continue.`,
+  ]);
+}
+
+/**
+ * Format the block for an agent stopped before the limiter admitted it. Such an
+ * agent never ran, so it has no result and no usage — reporting either (even as
+ * zeroes) would point the parent at work that does not exist.
+ */
+function formatNeverStartedNotification(record: Subagent): string {
+  const toolCallId = record.toolCallId;
+  return joinNotificationLines([
+    "<task-notification>",
+    `<task-id>${record.id}</task-id>`,
+    toolCallId ? `<tool-use-id>${escapeXml(toolCallId)}</tool-use-id>` : null,
+    "<status>Stopped before starting</status>",
+    `<summary>Subagent "${escapeXml(record.description)}" was stopped while queued and never started</summary>`,
+    "</task-notification>",
+  ]);
+}
+
+/** Join notification lines, dropping the ones a conditional element omitted. */
+function joinNotificationLines(lines: (string | null)[]): string {
+  return lines.filter(Boolean).join("\n");
+}
+
+/** Build notification details for the custom message renderer. */
+export function buildNotificationDetails(
+  record: Subagent,
+  resultMaxLen: number,
+): NotificationDetails {
+  const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+
+  return {
+    id: record.id,
+    description: record.description,
+    status: record.status,
+    toolUses: record.toolUses,
+    turnCount: record.turnCount,
+    maxTurns: record.maxTurns,
+    totalTokens,
+    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    outputFile: record.outputFile,
+    error: record.error,
+    resultPreview: buildResultPreview(record, resultMaxLen),
+  };
+}
+
+/** The renderer's preview text: the (truncated) result, or why there is none. */
+function buildResultPreview(record: Subagent, resultMaxLen: number): string {
+  if (record.stoppedWhileQueued) return "Never started — stopped while queued.";
+  if (!record.result) return "No output.";
+  return record.result.length > resultMaxLen
+    ? record.result.slice(0, resultMaxLen) + "…"
+    : record.result;
+}
+
+/** Build event data for lifecycle events from a Subagent. */
+export function buildEventData(record: Subagent) {
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+  const u = record.lifetimeUsage;
+  const total = getLifetimeTotal(u);
+  const tokens =
+    total > 0
+      ? { input: u.input, output: u.output, total }
+      : undefined;
+  return {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    result: record.result,
+    error: record.error,
+    status: record.status,
+    toolUses: record.toolUses,
+    durationMs,
+    tokens,
+  };
+}
+
+// ---- Notification system factory ----
+
+export interface NotificationSystem {
+  sendCompletion: (record: Subagent) => void;
+  sendUpdate: (record: Subagent, message: string) => void;
+  sendWorkspaceNotice: (record: Subagent, notice: string) => void;
+  dispose: () => void;
+}
+
+/** Details the update renderer reads. */
+export interface UpdateDetails {
+  id: string;
+  description: string;
+  message: string;
+}
+
+/** Details the workspace-notice renderer reads. */
+export interface WorkspaceNoticeDetails {
+  id: string;
+  description: string;
+  notice: string;
+}
+
+/**
+ * One announcement withheld for the parent's current run.
+ *
+ * A completion for an agent supersedes an earlier one for that agent; two
+ * updates are two distinct facts and both survive.
+ */
+type PendingAnnouncement =
+  | { kind: "completion"; record: Subagent }
+  | { kind: "update"; record: Subagent; message: string };
+
+export class NotificationManager implements NotificationSystem {
+  // pi.sendMessage is fire-and-forget: while the parent's agent run is active,
+  // a followUp is handed to a queue the extension cannot recall, yet it is only
+  // delivered when the run drains that queue at turn end. A parent that pulls
+  // the result in between would receive it twice. So nudges that arrive mid-run
+  // are withheld here — where record.consumed is still consultable — and
+  // flushed once the run settles.
+  // Ordered rather than record-keyed: a completion for an agent supersedes an
+  // earlier one for that agent, but announcements from different agents are
+  // distinct facts, and arrival order is the only order the parent can make
+  // sense of.
+  private pending: PendingAnnouncement[] = [];
+  private parentRunActive = false;
+  private disposed = false;
+
+  constructor(
+    private sendMessage: (
+      msg: { customType: string; content: string; display: boolean; details?: unknown },
+      opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+    ) => void,
+  ) {}
+
+  sendCompletion(record: Subagent): void {
+    // The session is gone. It is the aborts fired during shutdown that reach
+    // here, and with no parent run active a nudge would go straight out as an
+    // unrecallable followUp.
+    if (this.disposed) return;
+    // A carrier has committed to delivering this outcome, so announcing it would
+    // duplicate a delivery the parent is already getting. Structural and decided
+    // at the parent's request, so unlike the consumption check below it cannot
+    // race the turn.
+    if (record.claimed) return;
+    // Consumption is domain state on the record; the nudge is a pure
+    // announcement. Skip if the parent already pulled the result (enqueue-time
+    // guard); emitIndividualNudge re-reads record.consumed when the nudge is
+    // actually emitted, which is what makes the flush a fresh re-check.
+    if (record.consumed) return;
+    if (this.parentRunActive) {
+      this.withholdCompletion(record);
+      return;
+    }
+    this.emitIndividualNudge(record);
+  }
+
+  /**
+   * Queue a completion for the flush, superseding an earlier one for the same
+   * agent in the position that one already holds — a re-completion is the same
+   * fact told again, not a later one.
+   */
+  private withholdCompletion(record: Subagent): void {
+    const entry: PendingAnnouncement = { kind: "completion", record };
+    const existing = this.pending.findIndex(
+      (queued) => queued.kind === "completion" && queued.record.id === record.id,
+    );
+    if (existing === -1) this.pending.push(entry);
+    else this.pending[existing] = entry;
+  }
+
+  /**
+   * Announce a message a still-running child sent its parent.
+   *
+   * Consumption is not consulted: it records that the child's *outcome* was
+   * collected, and an update is a new fact rather than that outcome told again.
+   * What is consulted is whether an announcement is still the right channel at
+   * all — see `canAnnounceUpdate`. The disposal latch and the parent-run
+   * withhold apply as they do to any announcement.
+   */
+  sendUpdate(record: Subagent, message: string): void {
+    if (this.disposed) return;
+    if (!this.canAnnounceUpdate(record)) return;
+    if (this.parentRunActive) {
+      this.pending.push({ kind: "update", record, message });
+      return;
+    }
+    this.emitUpdate(record, message);
+  }
+
+  /**
+   * Whether an announcement is still the right channel for this run's updates.
+   *
+   * A claimed outcome is one a blocked carrier is already delivering, so an
+   * announcement could only arrive after its return. A terminated run has an
+   * outcome, and every carrier of an outcome renders what the run still owes —
+   * including the completion nudge — so the message arrives with it rather than
+   * as a live update the child can no longer act on.
+   *
+   * Consulted at enqueue and again at emit, because a run withheld for the
+   * parent's turn can terminate or be claimed in between. That re-read is what
+   * keeps a `<subagent-update>` block's steering affordance true.
+   */
+  private canAnnounceUpdate(record: Subagent): boolean {
+    return !record.claimed && record.isActive();
+  }
+
+  /**
+   * Announce where a teardown left a child's work, after its result was already
+   * delivered.
+   *
+   * Consults neither the carrier claim nor consumption: both record that the
+   * child's *outcome* has an owner, and this is a fact about the workspace
+   * rather than that outcome told again. It is not withheld for the parent's
+   * run either — the withheld queue exists for the unrecallable `followUp` a
+   * mid-run send becomes, and this delivery mode never reaches it. Pi appends
+   * it once the current turn ends, or immediately when there is none.
+   */
+  sendWorkspaceNotice(record: Subagent, notice: string): void {
+    if (this.disposed) return;
+    const details: WorkspaceNoticeDetails = {
+      id: record.id,
+      description: record.description,
+      notice,
+    };
+    this.sendMessage(
+      {
+        customType: "subagent-workspace-notice",
+        content: formatWorkspaceNotice(record, notice),
+        display: true,
+        details,
+      },
+      { triggerTurn: false },
+    );
+  }
+
+  /** The parent's agent run became active; nudges are withheld until it settles. */
+  onParentAgentStart(): void {
+    this.parentRunActive = true;
+  }
+
+  /**
+   * The parent's agent run settled. Flush the nudges withheld during it, each
+   * re-checking consumption, so a result the parent pulled mid-run is dropped
+   * rather than announced a second time.
+   */
+  onParentAgentSettled(): void {
+    this.parentRunActive = false;
+    const withheld = this.pending.splice(0);
+    for (const entry of withheld) {
+      try {
+        if (entry.kind === "update") this.emitUpdate(entry.record, entry.message);
+        else this.emitIndividualNudge(entry.record);
+      } catch (err) {
+        debugLog("notification render", err);
+      }
+    }
+  }
+
+  /** Terminal: the manager stops announcing anything, now and afterwards. */
+  dispose(): void {
+    this.disposed = true;
+    this.pending.length = 0;
+  }
+
+  private emitUpdate(record: Subagent, message: string): void {
+    if (!this.canAnnounceUpdate(record)) return;
+    // This channel is delivering the message, so no outcome carrier may repeat
+    // it — the record renders only what is still owed.
+    record.markUpdateAnnounced(message);
+    const details: UpdateDetails = {
+      id: record.id,
+      description: record.description,
+      message,
+    };
+    this.sendMessage(
+      {
+        customType: "subagent-update",
+        content: formatUpdateNotification(record, message),
+        display: true,
+        details,
+      },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  }
+
+  private emitIndividualNudge(record: Subagent): void {
+    if (record.claimed) return;
+    if (record.consumed) return;
+
+    const notification = formatTaskNotification(record, 500);
+    // A never-started agent has no transcript and nothing to collect.
+    const pointerLines = record.stoppedWhileQueued ? "" : this.buildPointerLines(record);
+
+    this.sendMessage(
+      {
+        customType: "subagent-notification",
+        content: notification + pointerLines,
+        display: true,
+        details: buildNotificationDetails(record, 500),
+      },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  }
+
+  /**
+   * The trailing pointer lines: where the transcript lives, and how to collect
+   * the result. The nudge only announces; the parent must pull to collect (and
+   * consume).
+   */
+  private buildPointerLines(record: Subagent): string {
+    const outputFile = record.outputFile;
+    const transcriptLine = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
+    return (
+      // What the child flagged along the way leads — for a run nothing else
+      // collected, this nudge is the carrier those updates ride. Then where the
+      // work went, so the parent reads it before the pointers.
+      renderRunUpdates(record.runUpdates) +
+      renderWorkspaceNotice(record.workspaceNotice) +
+      `${transcriptLine}\nCall get_subagent_result("${record.id}") to collect the full result.` +
+      renderQuestionAffordance(record.id, record.pendingQuestion, record.resumeRefusal)
+    );
+  }
+}

package/src/observation/outcome-delivery.ts

@@ -0,0 +1,239 @@
+/**
+ * outcome-delivery.ts — Shared rendering for a subagent outcome.
+ *
+ * A terminated child's outcome reaches the parent model through exactly one
+ * carrier: the foreground tool return, the resume tool return, the
+ * `get_subagent_result` report, or the completion nudge. Each carrier owns its
+ * own framing (spawn notes, XML envelope, report header) and its own
+ * truncation — a nudge is a preview, a pull is the full text — but the body
+ * they wrap is the same fact, so it is rendered here rather than four times.
+ *
+ * A workspace notice rides the same four carriers without being part of the
+ * outcome: it reports where a teardown put the child's work, which the parent
+ * needs whether the run succeeded or failed. A notice produced after the
+ * result was already delivered reaches none of them and is announced on its
+ * own instead.
+ *
+ * The updates a child sent mid-run ride the carriers too, for the runs whose
+ * outcome a blocked carrier holds: the announcement channel would deliver them
+ * after that carrier's own return, so it renders them itself instead.
+ *
+ * The updates, the notice, and the ask-back affordance are appended in one
+ * fixed order by `renderOutcomeAddenda`, so the three carriers that compose
+ * them cannot disagree about what follows the body. The affordance is the one
+ * addendum that asks the parent to call back, so it is also the one that has
+ * to know whether that call would be accepted.
+ *
+ * Pure functions only: no SDK types, no record types, no side effects.
+ */
+
+import type { ResumeRefusal } from "#src/lifecycle/subagent";
+import type { SubagentStatus } from "#src/lifecycle/subagent-state";
+
+/**
+ * What a terminal status means, independent of how a carrier renders it.
+ *
+ * One source of truth for the facts, because the carriers disagreed on them:
+ * the nudge reported an abort as "max turns exceeded" while the foreground
+ * result added "output may be incomplete", and the pull and resume carriers
+ * reported nothing at all. Presentation still differs — see the two renderers
+ * below — because a standalone label and a mid-sentence parenthetical are
+ * different grammar, not different facts.
+ */
+interface StatusMeaning {
+	/** Sentence-initial label, e.g. "Wrapped up". */
+	label: string;
+	/** Why, without terminal punctuation, e.g. "reached turn limit". */
+	detail: string;
+}
+
+const STATUS_MEANINGS: Partial<Record<SubagentStatus, StatusMeaning>> = {
+	aborted: { label: "Aborted", detail: "max turns exceeded, output may be incomplete" },
+	steered: { label: "Wrapped up", detail: "reached turn limit" },
+	// "user request" rather than "stopped by user": the detail must stand on its
+	// own after the label, which both presentations already supply.
+	stopped: { label: "Stopped", detail: "user request" },
+};
+
+/**
+ * Why a resume is unavailable *for good*, worded as a subordinate clause.
+ *
+ * The resume door words the same three facts as standalone refusals; a clause
+ * that continues someone else's sentence is different grammar, not a different
+ * fact — the split `STATUS_MEANINGS` makes between `label` and `detail`.
+ *
+ * `still-running` is excluded by type rather than by omission: a refusal that
+ * lifts when the run settles asks the parent to wait, where these three ask it
+ * to give up, so it gets its own sentence in the renderer below.
+ */
+const RESUME_REFUSAL_CLAUSES: Record<Exclude<ResumeRefusal, "still-running">, string> = {
+	// Deliberately not "...no session to resume": the clause is followed by a
+	// colon, and "resume:" is the exact token the parent must not see here.
+	"no-session": "it has no active session",
+	"session-released": "its session was released after its retention window",
+	"workspace-disposed": "it ran in an isolated workspace that has since been removed",
+};
+
+/**
+ * Standalone label form, e.g. "Wrapped up (reached turn limit)".
+ *
+ * An error reports its message instead: the status alone does not say what
+ * went wrong.
+ */
+export function renderStatusLabel(status: SubagentStatus, error?: string): string {
+	if (status === "error") return `Error: ${error ?? "unknown"}`;
+	const meaning = STATUS_MEANINGS[status];
+	return meaning ? `${meaning.label} (${meaning.detail})` : "Done";
+}
+
+/**
+ * Parenthetical suffix form, e.g. " (wrapped up — reached turn limit)", for a
+ * carrier appending to its own sentence. Empty when the status is unremarkable
+ * or when the body already carries the explanation, as an error's does.
+ */
+export function renderStatusNote(status: SubagentStatus): string {
+	const meaning = STATUS_MEANINGS[status];
+	if (!meaning) return "";
+	return ` (${meaning.label.toLowerCase()} \u2014 ${meaning.detail})`;
+}
+
+/**
+ * Only what the body formatter reads. Narrower than any record type so a
+ * caller cannot come to depend on fields this module does not use.
+ */
+export interface OutcomeBody {
+	status: SubagentStatus;
+	result: string | undefined;
+	error: string | undefined;
+	/** Whether the agent was stopped before the limiter ever admitted it. */
+	stoppedWhileQueued: boolean;
+}
+
+/**
+ * The trailing affordance for a child that ended its turn with a question.
+ * Empty when the child asked nothing.
+ *
+ * Names the exact call that answers it when a resume would be accepted, why it
+ * cannot be answered when one would be refused for good, and what to wait for
+ * when the child is simply not finished — the parent is never told to make a
+ * call this extension declines.
+ *
+ * Takes the id, question, and refusal rather than a record: the three facts it
+ * needs, so a carrier holding any shape can call it.
+ */
+export function renderQuestionAffordance(
+	agentId: string,
+	question: string | undefined,
+	refusal: ResumeRefusal | undefined,
+): string {
+	if (!question) return "";
+	const quoted = question
+		.split("\n")
+		.map((line) => `  ${line}`)
+		.join("\n");
+	if (refusal === "still-running") {
+		return (
+			"\n\nThis agent asked a question before it finished running, so it cannot be " +
+			`resumed yet:\n\n${quoted}\n\n` +
+			"Wait for it to settle \u2014 get_subagent_result with wait: true returns when it " +
+			"does \u2014 then answer it."
+		);
+	}
+	if (refusal) {
+		return (
+			"\n\nThis agent ended its run with a question that can no longer be answered \u2014 " +
+			`${RESUME_REFUSAL_CLAUSES[refusal]}:\n\n${quoted}\n\n` +
+			"Spawn a new agent with the context it needs; this one cannot be resumed."
+		);
+	}
+	return (
+		`\n\nThis agent is waiting on an answer:\n\n${quoted}\n\n` +
+		`Answer by calling subagent with resume: "${agentId}" and your answer as the prompt.`
+	);
+}
+
+/**
+ * The provider's own wording for where a teardown left the child's work, for a
+ * carrier appending it after the outcome body. Empty when no teardown reported
+ * anything — including every run whose addendum rode the result text instead.
+ *
+ * Takes the notice rather than a record, so a carrier holding any shape can
+ * call it, and so the framing has one home if a carrier ever needs its own.
+ */
+export function renderWorkspaceNotice(notice: string | undefined): string {
+	return notice ?? "";
+}
+
+/**
+ * What a carrier appends after the outcome body: where the work went, then the
+ * call to action that follows it.
+ *
+ * The fields rather than a record, so a carrier holding any shape can call it
+ * — both `Subagent` and `AgentReport` satisfy this structurally.
+ */
+export interface OutcomeAddenda {
+	id: string;
+	runUpdates?: readonly string[];
+	workspaceNotice?: string;
+	pendingQuestion?: string;
+	/**
+	 * Why a resume would be refused; undefined when one would be accepted.
+	 *
+	 * Required rather than optional so a carrier that forgets it fails to
+	 * compile. An omitted optional would silently mean "resumable", which is the
+	 * fail-open this field exists to close.
+	 */
+	resumeRefusal: ResumeRefusal | undefined;
+}
+
+/** The addenda tail every outcome carrier appends, in one order. */
+export function renderOutcomeAddenda(outcome: OutcomeAddenda): string {
+	return (
+		// What the agent flagged along the way, then where the work went, then the
+		// call to action that follows both.
+		renderRunUpdates(outcome.runUpdates) +
+		renderWorkspaceNotice(outcome.workspaceNotice) +
+		renderQuestionAffordance(outcome.id, outcome.pendingQuestion, outcome.resumeRefusal)
+	);
+}
+
+/**
+ * The updates a child sent while a carrier held this run's outcome, quoted the
+ * way the ask-back affordance quotes the child's question. Empty for a run the
+ * child said nothing during — which is every run whose updates the parent was
+ * free to receive as they happened.
+ */
+export function renderRunUpdates(updates: readonly string[] | undefined): string {
+	if (!updates?.length) return "";
+	const quoted = updates
+		.map((update) =>
+			update
+				.split("\n")
+				.map((line) => `  ${line}`)
+				.join("\n"),
+		)
+		.join("\n\n");
+	return `\n\nUpdates this agent sent while it worked:\n\n${quoted}`;
+}
+
+/**
+ * The outcome body every carrier reports: a running note, an error line, a
+ * never-started note, or the trimmed result.
+ *
+ * The empty-result fallback tests truthiness rather than nullishness. A `??`
+ * here passed an empty string through, which is exactly what a run whose
+ * provider errored carries — so the parent received a completion header
+ * followed by nothing and confabulated the child's work. The two renderers in
+ * `notification.ts` always guarded this by truthiness; this is the third
+ * agreeing with them (#889).
+ */
+export function renderOutcomeBody(outcome: OutcomeBody): string {
+	if (outcome.status === "running")
+		return "Agent is still running. Use wait: true or check back later.";
+	if (outcome.status === "error") return `Error: ${outcome.error}`;
+	if (outcome.stoppedWhileQueued)
+		return "Agent was stopped while queued and never started. No work was performed.";
+	const trimmed = outcome.result?.trim();
+	// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: converts falsy values to fallback
+	return trimmed || "No output.";
+}