@clanker-code/pi-subagents 0.10.5

package/src/ui/conversation-viewer.ts

@@ -0,0 +1,297 @@
+/**
+ * conversation-viewer.ts — Live conversation overlay for viewing agent sessions.
+ *
+ * Displays a scrollable, live-updating view of an agent's conversation.
+ * Subscribes to session events for real-time streaming updates.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { extractText } from "../context.js";
+import type { AgentRecord } from "../types.js";
+import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
+import type { Theme } from "./agent-widget.js";
+import { type AgentActivity, buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
+
+/** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES_BASE = 6;
+const MIN_VIEWPORT = 3;
+/** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
+export const VIEWPORT_HEIGHT_PCT = 70;
+
+export class ConversationViewer implements Component {
+  private scrollOffset = 0;
+  private autoScroll = true;
+  private unsubscribe: (() => void) | undefined;
+  private lastInnerW = 0;
+  private closed = false;
+  /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+  private stopArmed = false;
+  private keys: ViewerKeys;
+
+  constructor(
+    private tui: TUI,
+    private session: AgentSession,
+    private record: AgentRecord,
+    private activity: AgentActivity | undefined,
+    private theme: Theme,
+    private done: (result: undefined) => void,
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    private onStop?: () => void,
+    /** User keybindings from `ctx.ui.custom()`. Omitted → hardcoded defaults. */
+    keybindings?: ViewerKeybindings,
+  ) {
+    this.keys = createViewerKeys(keybindings);
+    this.unsubscribe = session.subscribe(() => {
+      if (this.closed) return;
+      this.tui.requestRender();
+    });
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "q")) {
+      this.closed = true;
+      this.done(undefined);
+      return;
+    }
+
+    // Stop/abort the agent (only while it can still be stopped). Two-press:
+    // first "x" arms, second confirms — any other key disarms.
+    if (matchesKey(data, "x")) {
+      if (this.isStoppable()) {
+        if (this.stopArmed) {
+          this.stopArmed = false;
+          this.onStop?.();
+        } else {
+          this.stopArmed = true;
+        }
+        this.tui.requestRender();
+      }
+      return;
+    }
+    if (this.stopArmed) this.stopArmed = false;
+
+    const totalLines = this.buildContentLines(this.lastInnerW).length;
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, totalLines - viewportHeight);
+
+    if (this.keys.scrollUp(data)) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (this.keys.scrollDown(data)) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (this.keys.pageUp(data)) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
+      this.autoScroll = false;
+    } else if (this.keys.pageDown(data)) {
+      this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
+      this.autoScroll = this.scrollOffset >= maxScroll;
+    } else if (matchesKey(data, "home")) {
+      this.scrollOffset = 0;
+      this.autoScroll = false;
+    } else if (matchesKey(data, "end")) {
+      this.scrollOffset = maxScroll;
+      this.autoScroll = true;
+    }
+  }
+
+  render(width: number): string[] {
+    if (width < 6) return []; // too narrow for any meaningful rendering
+    const th = this.theme;
+    const innerW = width - 4; // border + padding
+    this.lastInnerW = innerW;
+    const lines: string[] = [];
+
+    const pad = (s: string, len: number) => {
+      const vis = visibleWidth(s);
+      return s + " ".repeat(Math.max(0, len - vis));
+    };
+    const row = (content: string) =>
+      th.fg("border", "│") + " " + truncateToWidth(pad(content, innerW), innerW) + " " + th.fg("border", "│");
+    const hrTop = th.fg("border", `╭${"─".repeat(width - 2)}╮`);
+    const hrBot = th.fg("border", `╰${"─".repeat(width - 2)}╯`);
+    const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+    // Header
+    lines.push(hrTop);
+    const name = getDisplayName(this.record.type);
+    const modeLabel = getPromptModeLabel(this.record.type);
+    const modeTag = modeLabel ? ` ${th.fg("dim", `(${modeLabel})`)}` : "";
+    const statusIcon = this.record.status === "running"
+      ? th.fg("accent", "●")
+      : this.record.status === "completed"
+        ? th.fg("success", "✓")
+        : this.record.status === "error"
+          ? th.fg("error", "✗")
+          : th.fg("dim", "○");
+    const duration = formatDuration(this.record.startedAt, this.record.completedAt);
+
+    const headerParts: string[] = [duration];
+    const toolUses = this.activity?.toolUses ?? this.record.toolUses;
+    if (toolUses > 0) headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`);
+    const tokens = getLifetimeTotal(this.activity?.lifetimeUsage);
+    if (tokens > 0) {
+      const percent = getSessionContextPercent(this.activity?.session);
+      headerParts.push(formatSessionTokens(tokens, percent, th, this.record.compactionCount));
+    }
+
+    lines.push(row(
+      `${statusIcon} ${th.bold(name)}${modeTag}  ${th.fg("muted", this.record.description)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`,
+    ));
+    const invocationLine = this.invocationLine();
+    if (invocationLine) lines.push(row(invocationLine));
+    lines.push(hrMid);
+
+    // Content area — rebuild every render (live data, no cache needed)
+    const contentLines = this.buildContentLines(innerW);
+    const viewportHeight = this.viewportHeight();
+    const maxScroll = Math.max(0, contentLines.length - viewportHeight);
+
+    if (this.autoScroll) {
+      this.scrollOffset = maxScroll;
+    }
+
+    const visibleStart = Math.min(this.scrollOffset, maxScroll);
+    const visible = contentLines.slice(visibleStart, visibleStart + viewportHeight);
+
+    for (let i = 0; i < viewportHeight; i++) {
+      lines.push(row(visible[i] ?? ""));
+    }
+
+    // Footer
+    lines.push(hrMid);
+    const scrollPct = contentLines.length <= viewportHeight
+      ? "100%"
+      : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
+    const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
+    const scrollHint = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+    // Stop hint goes first in the right group so it survives right-edge
+    // truncation on narrow terminals (the scroll hint is the expendable part).
+    const footerRight = this.isStoppable()
+      ? (this.stopArmed ? th.fg("error", "x again to STOP") : th.fg("dim", "x stop")) +
+        th.fg("dim", " · ") + scrollHint
+      : scrollHint;
+    const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
+    lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
+    lines.push(hrBot);
+
+    return lines;
+  }
+
+  /** Stoppable only when a stop handler exists and the agent is still active. */
+  private isStoppable(): boolean {
+    return !!this.onStop && (this.record.status === "running" || this.record.status === "queued");
+  }
+
+  invalidate(): void { /* no cached state to clear */ }
+
+  dispose(): void {
+    this.closed = true;
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = undefined;
+    }
+  }
+
+  // ---- Private ----
+
+  private viewportHeight(): number {
+    // Cap mirrors the overlay's maxHeight — otherwise the viewer would render
+    // more lines than the overlay shows and clip the footer.
+    const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+    return Math.max(MIN_VIEWPORT, maxRows - this.chromeLines());
+  }
+
+  private chromeLines(): number {
+    return CHROME_LINES_BASE + (this.invocationLine() ? 1 : 0);
+  }
+
+  private invocationLine(): string | undefined {
+    const { modelName, tags } = buildInvocationTags(this.record.invocation);
+    const parts = modelName ? [modelName, ...tags] : tags;
+    if (parts.length === 0) return undefined;
+    return this.theme.fg("dim", `  ↳ ${parts.join(" · ")}`);
+  }
+
+  private buildContentLines(width: number): string[] {
+    if (width <= 0) return [];
+
+    const th = this.theme;
+    const messages = this.session.messages;
+    const lines: string[] = [];
+
+    if (messages.length === 0) {
+      lines.push(th.fg("dim", "(waiting for first message...)"));
+      return lines;
+    }
+
+    let needsSeparator = false;
+    for (const msg of messages) {
+      if (msg.role === "user") {
+        const text = typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+        if (!text.trim()) continue;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.fg("accent", "[User]"));
+        for (const line of wrapTextWithAnsi(text.trim(), width)) {
+          lines.push(line);
+        }
+      } else if (msg.role === "assistant") {
+        const textParts: string[] = [];
+        const toolCalls: string[] = [];
+        for (const c of msg.content) {
+          if (c.type === "text" && c.text) textParts.push(c.text);
+          else if (c.type === "toolCall") {
+            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
+          }
+        }
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.bold("[Assistant]"));
+        if (textParts.length > 0) {
+          for (const line of wrapTextWithAnsi(textParts.join("\n").trim(), width)) {
+            lines.push(line);
+          }
+        }
+        for (const name of toolCalls) {
+          lines.push(truncateToWidth(th.fg("muted", `  [Tool: ${name}]`), width));
+        }
+      } else if (msg.role === "toolResult") {
+        const text = extractText(msg.content);
+        const truncated = text.length > 500 ? text.slice(0, 500) + "... (truncated)" : text;
+        if (!truncated.trim()) continue;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(th.fg("dim", "[Result]"));
+        for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
+          lines.push(th.fg("dim", line));
+        }
+      } else if ((msg as any).role === "bashExecution") {
+        const bash = msg as any;
+        if (needsSeparator) lines.push(th.fg("dim", "───"));
+        lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
+        if (bash.output?.trim()) {
+          const out = bash.output.length > 500
+            ? bash.output.slice(0, 500) + "... (truncated)"
+            : bash.output;
+          for (const line of wrapTextWithAnsi(out.trim(), width)) {
+            lines.push(th.fg("dim", line));
+          }
+        }
+      } else {
+        continue;
+      }
+      needsSeparator = true;
+    }
+
+    // Streaming indicator for running agents
+    if (this.record.status === "running" && this.activity) {
+      const act = describeActivity(this.activity.activeTools, this.activity.responseText);
+      lines.push("");
+      lines.push(truncateToWidth(th.fg("accent", "▍ ") + th.fg("dim", act), width));
+    }
+
+    return lines.map(l => truncateToWidth(l, width));
+  }
+}

package/src/ui/menu-select.ts

@@ -0,0 +1,68 @@
+/**
+ * menu-select.ts — Custom select dialog with left/right arrow navigation.
+ *
+ * Mirrors `ctx.ui.select()` but adds horizontal arrow semantics for nested
+ * menus: left arrow goes back (like Esc), right arrow selects (like Enter).
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getSelectListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, matchesKey, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+
+export interface MenuSelectOptions {
+  title: string;
+  options: string[];
+  /** Optional descriptions keyed by option string. */
+  descriptions?: Record<string, string>;
+  /** Maximum number of items visible at once. Defaults to all items. */
+  maxVisible?: number;
+}
+
+/**
+ * Show a selectable menu and return the chosen option, or `undefined` if the
+ * user backed out with Esc or the left arrow.
+ */
+export async function menuSelect(
+  ctx: ExtensionCommandContext,
+  opts: MenuSelectOptions,
+): Promise<string | undefined> {
+  const items = opts.options.map((value) => ({
+    value,
+    label: value,
+    description: opts.descriptions?.[value],
+  }));
+
+  return ctx.ui.custom<string | undefined>((_tui, theme, _kb, done) => {
+    const list = new SelectList(
+      items,
+      opts.maxVisible ?? items.length,
+      getSelectListTheme(),
+    );
+    list.onSelect = (item) => done(item.value);
+    list.onCancel = () => done(undefined);
+
+    const container = new Container();
+    container.addChild(new Text(theme.bold(opts.title), 0, 0));
+    container.addChild(new Spacer(1));
+    container.addChild(list);
+
+    return {
+      render: (w: number) => container.render(w),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (matchesKey(data, "left") || matchesKey(data, "escape")) {
+          done(undefined);
+          return;
+        }
+        if (matchesKey(data, "right") || matchesKey(data, "enter")) {
+          const selected = list.getSelectedItem();
+          if (selected) {
+            done(selected.value);
+          }
+          return;
+        }
+        list.handleInput(data);
+      },
+    };
+  });
+}

package/src/ui/schedule-menu.ts

@@ -0,0 +1,105 @@
+/**
+ * schedule-menu.ts — `/agents → Scheduled jobs` submenu.
+ *
+ * Minimal v1 surface: list scheduled jobs, select one to inspect details +
+ * confirm cancellation. No create wizard (the `Agent` tool's `schedule` param
+ * is the canonical creation path), no toggle/cleanup (cancel is enough for
+ * "I scheduled something dumb, get rid of it"). Add management surfaces here
+ * if real demand emerges.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SubagentScheduler } from "../schedule.js";
+import type { ScheduledSubagent } from "../types.js";
+import { menuSelect } from "./menu-select.js";
+
+/** Format an ISO timestamp as relative time ("in 4h", "2d ago", "—"). */
+function relTime(iso: string | undefined, now = Date.now()): string {
+  if (!iso) return "—";
+  const t = new Date(iso).getTime();
+  if (Number.isNaN(t)) return "—";
+  const diff = t - now;
+  const abs = Math.abs(diff);
+  const future = diff > 0;
+  if (abs < 60_000) return future ? "in <1m" : "<1m ago";
+  const m = Math.round(abs / 60_000);
+  if (m < 60) return future ? `in ${m}m` : `${m}m ago`;
+  const h = Math.round(abs / 3_600_000);
+  if (h < 24) return future ? `in ${h}h` : `${h}h ago`;
+  const d = Math.round(abs / 86_400_000);
+  return future ? `in ${d}d` : `${d}d ago`;
+}
+
+/** One-line status icon. */
+function statusIcon(j: ScheduledSubagent): string {
+  if (!j.enabled) return "✗";
+  if (j.lastStatus === "error") return "!";
+  if (j.lastStatus === "running") return "⋯";
+  return "✓";
+}
+
+/** Compact selectable row — name, schedule, agent type, next/last run, count. */
+function formatJob(j: ScheduledSubagent, scheduler: SubagentScheduler): string {
+  const next = scheduler.getNextRun(j.id);
+  return [
+    statusIcon(j),
+    j.name.padEnd(18).slice(0, 18),
+    j.schedule.padEnd(14).slice(0, 14),
+    `[${j.subagent_type}]`,
+    `next ${relTime(next)}`,
+    `last ${relTime(j.lastRun)}`,
+    `runs ${j.runCount}`,
+  ].join("  ");
+}
+
+/** Multi-line details block for the cancel confirm. */
+function formatDetails(j: ScheduledSubagent, scheduler: SubagentScheduler): string {
+  const next = scheduler.getNextRun(j.id) ?? "—";
+  return [
+    `name:      ${j.name}`,
+    `schedule:  ${j.schedule} (${j.scheduleType})`,
+    `agent:     ${j.subagent_type}`,
+    `prompt:    ${j.prompt.slice(0, 200)}${j.prompt.length > 200 ? "…" : ""}`,
+    `created:   ${j.createdAt}`,
+    `last run:  ${j.lastRun ?? "—"} (${j.lastStatus ?? "—"})`,
+    `next run:  ${next}`,
+    `runs:      ${j.runCount}`,
+  ].join("\n");
+}
+
+/**
+ * List scheduled jobs; selecting one opens a cancel-confirm with details.
+ * Returns when the user backs out or after a cancellation.
+ */
+export async function showSchedulesMenu(
+  ctx: ExtensionCommandContext,
+  scheduler: SubagentScheduler,
+): Promise<void> {
+  if (!scheduler.isActive()) {
+    ctx.ui.notify("Scheduler is not active in this session.", "warning");
+    return;
+  }
+
+  const jobs = scheduler.list();
+  if (jobs.length === 0) {
+    ctx.ui.notify("No scheduled jobs.", "info");
+    return;
+  }
+
+  const labels = jobs.map(j => formatJob(j, scheduler));
+  const choice = await menuSelect(ctx, {
+    title: `Scheduled jobs (${jobs.length}) — select to cancel`,
+    options: labels,
+  });
+  if (!choice) return;
+
+  const idx = labels.indexOf(choice);
+  if (idx < 0) return;
+  const job = jobs[idx];
+
+  const ok = await ctx.ui.confirm(`Cancel "${job.name}"?`, formatDetails(job, scheduler));
+  if (!ok) return;
+
+  scheduler.removeJob(job.id);
+  ctx.ui.notify(`Cancelled "${job.name}".`, "info");
+}

package/src/ui/viewer-keys.ts

@@ -0,0 +1,39 @@
+/**
+ * viewer-keys.ts — Scroll key matchers for the conversation viewer.
+ *
+ * Resolves `tui.select.*` through the user's keybindings when pi provides a
+ * manager, falling back to the previous hardcoded keys otherwise. The viewer's
+ * k/j and shift+arrow aliases always work alongside whatever is bound.
+ */
+
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+/** The `tui.select.*` keybinding ids the viewer resolves. */
+export type ViewerScrollKeybinding =
+  | "tui.select.up"
+  | "tui.select.down"
+  | "tui.select.pageUp"
+  | "tui.select.pageDown";
+
+/** Structural subset of pi-tui's `KeybindingsManager` (which satisfies it). */
+export interface ViewerKeybindings {
+  matches(data: string, keybinding: ViewerScrollKeybinding): boolean;
+}
+
+export interface ViewerKeys {
+  scrollUp(data: string): boolean;
+  scrollDown(data: string): boolean;
+  pageUp(data: string): boolean;
+  pageDown(data: string): boolean;
+}
+
+export function createViewerKeys(keybindings?: ViewerKeybindings): ViewerKeys {
+  const matches = (data: string, id: ViewerScrollKeybinding, fallback: KeyId): boolean =>
+    keybindings ? keybindings.matches(data, id) : matchesKey(data, fallback);
+  return {
+    scrollUp: (data) => matches(data, "tui.select.up", "up") || matchesKey(data, "k"),
+    scrollDown: (data) => matches(data, "tui.select.down", "down") || matchesKey(data, "j"),
+    pageUp: (data) => matches(data, "tui.select.pageUp", "pageUp") || matchesKey(data, "shift+up"),
+    pageDown: (data) => matches(data, "tui.select.pageDown", "pageDown") || matchesKey(data, "shift+down"),
+  };
+}

package/src/usage.ts

@@ -0,0 +1,60 @@
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+export type LifetimeUsage = { input: number; output: number; cacheWrite: number };
+
+/** Sum of lifetime usage components, or 0 if undefined. */
+export function getLifetimeTotal(u?: LifetimeUsage): number {
+  return u ? u.input + u.output + u.cacheWrite : 0;
+}
+
+/** Add a usage delta into a target accumulator (mutates target). */
+export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
+  into.input += delta.input;
+  into.output += delta.output;
+  into.cacheWrite += delta.cacheWrite;
+}
+
+/** Minimal shape we read from upstream `getSessionStats()`. */
+export type SessionStatsLike = {
+  tokens: { input: number; output: number; cacheWrite: number };
+  contextUsage?: { percent: number | null };
+};
+export type SessionLike = { getSessionStats(): SessionStatsLike };
+
+/**
+ * Session-scoped token count: input + output + cacheWrite as reported by
+ * upstream `getSessionStats().tokens` for the *current* session window.
+ *
+ * RESETS at compaction — upstream replaces `session.state.messages` and the
+ * stats are derived from that array. For a lifetime total that survives
+ * compaction, use `getLifetimeTotal(lifetimeUsage)` instead, which reads
+ * from an independent accumulator fed by `message_end` events.
+ *
+ * Avoids upstream's `tokens.total` field, which sums per-turn `cacheRead`
+ * and so counts the cumulative cached prefix N times across N turns
+ * (issue #38).
+ */
+export function getSessionTokens(session: SessionLike | undefined): number {
+  if (!session) return 0;
+  try {
+    const t = session.getSessionStats().tokens;
+    return t.input + t.output + t.cacheWrite;
+  } catch { return 0; }
+}
+
+/**
+ * Context-window utilization (0–100), or null when unavailable
+ * (no model contextWindow, or post-compaction before the next response).
+ */
+export function getSessionContextPercent(session: SessionLike | undefined): number | null {
+  if (!session) return null;
+  try { return session.getSessionStats().contextUsage?.percent ?? null; }
+  catch { return null; }
+}

package/src/wait.ts

@@ -0,0 +1,44 @@
+export type WaitOutcome = "completed" | "timeout" | "aborted";
+
+/** Human-readable "Xm Ys" for a duration in seconds. */
+export function formatWaitTimeout(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return m > 0 ? `${m}m${s > 0 ? ` ${s}s` : ""}` : `${s}s`;
+}
+
+/**
+ * Race an agent completion promise against the configured wait timeout and the
+ * parent abort signal. The subagent is never aborted here.
+ */
+export function raceWait(
+  promise: Promise<string>,
+  signal: AbortSignal | undefined,
+  timeoutSeconds: number,
+): Promise<WaitOutcome> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (outcome: WaitOutcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      resolve(outcome);
+    };
+    const timer = setTimeout(() => finish("timeout"), timeoutSeconds * 1000);
+    const onAbort = () => finish("aborted");
+    signal?.addEventListener("abort", onAbort, { once: true });
+    promise.then(() => finish("completed"));
+  });
+}
+
+/** Message returned when a wait ends with the agent still running. */
+export function waitTimeoutMessage(outcome: WaitOutcome, timeoutSeconds: number): string {
+  if (outcome === "timeout") {
+    return `Agent is still running. The wait timed out after ${formatWaitTimeout(timeoutSeconds)} to avoid blocking the parent session longer than the configured limit.\nCall get_subagent_result with wait: true again to keep waiting, or omit wait to check status.`;
+  }
+  if (outcome === "aborted") {
+    return `Agent is still running. The wait was cancelled by the user (parent turn aborted). The subagent was NOT stopped — it continues in the background.\nCall get_subagent_result with wait: true again to keep waiting, use peek to check progress, or omit wait to check status.`;
+  }
+  return "Agent is still running. Use peek to check recent progress, wait: true to block until it finishes, or check back later.";
+}