pi-subagents 0.32.0 → 0.33.0

package/src/runs/background/control-channel.ts

@@ -14,6 +14,7 @@
  * authoritative.
  */
 
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
@@ -26,7 +27,7 @@ import { POLL_INTERVAL_MS } from "../../shared/types.ts";
  */
 export const INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
 
-export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch">;
+export type ControlChannelFs = Pick<typeof fs, "mkdirSync" | "existsSync" | "rmSync" | "watch" | "readdirSync" | "readFileSync">;
 export type ControlChannelTimers = { setInterval: typeof setInterval; clearInterval: typeof clearInterval };
 type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => unknown;
 
@@ -44,6 +45,18 @@ export interface TimeoutRequest {
 	reason?: string;
 }
 
+export interface SteerRequest {
+	type: "steer";
+	id: string;
+	ts: number;
+	message: string;
+	targetIndex?: number;
+	source?: string;
+}
+
+const STEER_REQUESTS_DIR = "steer-requests";
+const STEER_TARGETS_DIR = "steer-targets";
+
 /** Control inbox directory inside an async run dir. */
 export function controlInboxDir(asyncDir: string): string {
 	return path.join(asyncDir, "control");
@@ -59,6 +72,26 @@ export function timeoutRequestPath(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), "timeout.json");
 }
 
+/** Directory of parent-to-runner steering requests. */
+export function steerRequestsDir(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), STEER_REQUESTS_DIR);
+}
+
+/** Per-child inbox consumed by the child prompt runtime inside the Pi process. */
+export function stepSteerInboxDir(asyncDir: string, index: number): string {
+	return path.join(controlInboxDir(asyncDir), STEER_TARGETS_DIR, String(index));
+}
+
+function steerRequestFileName(request: SteerRequest): string {
+	return `${String(request.ts).padStart(13, "0")}-${Buffer.from(request.id).toString("base64url")}.json`;
+}
+
+export function writeSteerRequestToDir(dir: string, request: SteerRequest): string {
+	const requestPath = path.join(dir, steerRequestFileName(request));
+	writeAtomicJson(requestPath, request);
+	return requestPath;
+}
+
 /**
  * Parent side: drop a portable interrupt request the runner's inbox watcher will
  * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
@@ -85,6 +118,76 @@ export function requestAsyncTimeout(
 	return requestPath;
 }
 
+export function requestAsyncSteer(
+	asyncDir: string,
+	payload: { message: string; targetIndex?: number; source?: string; id?: string; ts?: number },
+	deps: { now?: () => number; randomId?: () => string } = {},
+): string {
+	const message = payload.message.trim();
+	if (!message) throw new Error("steer message must not be empty.");
+	if (payload.targetIndex !== undefined && (!Number.isInteger(payload.targetIndex) || payload.targetIndex < 0)) {
+		throw new Error("steer targetIndex must be a non-negative integer.");
+	}
+	const request: SteerRequest = {
+		type: "steer",
+		id: payload.id ?? deps.randomId?.() ?? randomUUID(),
+		ts: payload.ts ?? deps.now?.() ?? Date.now(),
+		message,
+		...(payload.targetIndex !== undefined ? { targetIndex: payload.targetIndex } : {}),
+		...(payload.source ? { source: payload.source } : {}),
+	};
+	return writeSteerRequestToDir(steerRequestsDir(asyncDir), request);
+}
+
+export function enqueueStepSteer(asyncDir: string, index: number, request: SteerRequest): string {
+	if (!Number.isInteger(index) || index < 0) throw new Error("steer child index must be a non-negative integer.");
+	return writeSteerRequestToDir(stepSteerInboxDir(asyncDir, index), { ...request, targetIndex: index, type: "steer" });
+}
+
+function parseSteerRequest(raw: unknown): SteerRequest | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const input = raw as Partial<SteerRequest>;
+	if (input.type !== "steer") return undefined;
+	if (typeof input.id !== "string" || !input.id.trim()) return undefined;
+	if (typeof input.ts !== "number" || !Number.isFinite(input.ts)) return undefined;
+	if (typeof input.message !== "string" || !input.message.trim()) return undefined;
+	if (input.targetIndex !== undefined && (!Number.isInteger(input.targetIndex) || input.targetIndex < 0)) return undefined;
+	return {
+		type: "steer",
+		id: input.id.trim(),
+		ts: input.ts,
+		message: input.message.trim(),
+		...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}),
+		...(typeof input.source === "string" && input.source.trim() ? { source: input.source } : {}),
+	};
+}
+
+export function consumeSteerRequestsFromDir(dir: string, fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs): SteerRequest[] {
+	if (!fsImpl.existsSync(dir)) return [];
+	const requests: SteerRequest[] = [];
+	for (const entry of fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort()) {
+		const requestPath = path.join(dir, entry);
+		let parsed: SteerRequest | undefined;
+		try {
+			parsed = parseSteerRequest(JSON.parse(fsImpl.readFileSync(requestPath, "utf-8")));
+		} catch {
+			parsed = undefined;
+		}
+		try {
+			fsImpl.rmSync(requestPath, { recursive: true });
+		} catch {
+			// Already removed by a concurrent check — do not execute it twice.
+			continue;
+		}
+		if (parsed) requests.push(parsed);
+	}
+	return requests.sort((left, right) => left.ts - right.ts || left.id.localeCompare(right.id));
+}
+
+export function consumeSteerRequests(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs): SteerRequest[] {
+	return consumeSteerRequestsFromDir(steerRequestsDir(asyncDir), fsImpl);
+}
+
 /**
  * Runner side: consume a pending interrupt request. Idempotent — removes the file
  * so each distinct request fires exactly once. Returns whether one was pending.
@@ -173,6 +276,7 @@ export function watchAsyncControlInbox(
 	opts: {
 		onInterrupt: () => void;
 		onTimeout?: () => void;
+		onSteer?: (request: SteerRequest) => void;
 		pollIntervalMs?: number;
 		fs?: ControlChannelFs;
 		timers?: ControlChannelTimers;
@@ -193,6 +297,7 @@ export function watchAsyncControlInbox(
 		try {
 			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
 			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
+			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
 		} catch {
 			// Never let inbox errors crash the runner.
 		}

package/src/runs/background/fleet-view.ts

@@ -0,0 +1,515 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
+import { formatActivityLabel } from "../../shared/status-format.ts";
+import {
+	ASYNC_DIR,
+	RESULTS_DIR,
+	type ActivityState,
+	type AsyncJobStep,
+	type AsyncStatus,
+	type Details,
+	type NestedRunSummary,
+	type SubagentRunMode,
+	type SubagentState,
+} from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
+import { formatAsyncRunOutputPath, formatAsyncRunProgressLabel, listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
+
+const DEFAULT_TRANSCRIPT_LINES = 80;
+const MAX_TRANSCRIPT_LINES = 500;
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+type ForegroundControl = SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
+
+interface FleetViewParams {
+	lines?: number;
+}
+
+interface FleetViewDeps {
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+	state?: SubagentState;
+	childSafe?: boolean;
+}
+
+interface TranscriptOptions {
+	index?: number;
+	lines?: number;
+	sessionRoots?: string[];
+}
+
+interface TextTailResult {
+	path: string;
+	lines: string[];
+	truncated: boolean;
+	error?: string;
+}
+
+function transcriptLineLimit(value: number | undefined): number {
+	if (value === undefined) return DEFAULT_TRANSCRIPT_LINES;
+	if (!Number.isFinite(value)) return DEFAULT_TRANSCRIPT_LINES;
+	return Math.max(1, Math.min(MAX_TRANSCRIPT_LINES, Math.trunc(value)));
+}
+
+function uniqueStrings(values: Array<string | undefined>): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const value of values) {
+		if (!value || seen.has(value)) continue;
+		seen.add(value);
+		result.push(value);
+	}
+	return result;
+}
+
+function resolveMaybeRelative(asyncDir: string, filePath: string | undefined): string | undefined {
+	if (!filePath) return undefined;
+	return path.resolve(asyncDir, filePath);
+}
+
+function pathWithin(base: string, candidate: string): boolean {
+	const resolvedBase = path.resolve(base);
+	const resolvedCandidate = path.resolve(candidate);
+	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isNotFoundError(error: unknown): boolean {
+	return typeof error === "object"
+		&& error !== null
+		&& "code" in error
+		&& (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function readTextTail(filePath: string, maxLines: number): TextTailResult {
+	let stat: fs.Stats;
+	try {
+		stat = fs.statSync(filePath);
+	} catch (error) {
+		if (isNotFoundError(error)) return { path: filePath, lines: [], truncated: false };
+		return { path: filePath, lines: [], truncated: false, error: getErrorMessage(error) };
+	}
+	if (stat.size === 0) return { path: filePath, lines: [], truncated: false };
+
+	let fd: number | undefined;
+	try {
+		const bytesToRead = Math.min(stat.size, TRANSCRIPT_TAIL_BYTES);
+		const start = stat.size - bytesToRead;
+		const buffer = Buffer.alloc(bytesToRead);
+		fd = fs.openSync(filePath, "r");
+		const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, start);
+		const content = buffer.subarray(0, bytesRead).toString("utf-8");
+		let lines = content.split(/\r?\n/);
+		if (start > 0 && lines.length > 0) lines = lines.slice(1);
+		if (lines.at(-1) === "") lines = lines.slice(0, -1);
+		return { path: filePath, lines: lines.slice(-maxLines), truncated: start > 0 || lines.length > maxLines };
+	} catch (error) {
+		return { path: filePath, lines: [], truncated: false, error: getErrorMessage(error) };
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+	}
+}
+
+function readContainedTextTail(filePath: string, maxLines: number, trustedRoots: string[], label: string): TextTailResult {
+	if (trustedRoots.length === 0) return { path: filePath, lines: [], truncated: false, error: `Refusing to read ${label} transcript path without a trusted root: ${filePath}` };
+	const resolvedPath = path.resolve(filePath);
+	if (!trustedRoots.some((root) => pathWithin(root, resolvedPath))) {
+		return { path: filePath, lines: [], truncated: false, error: `Refusing to read ${label} transcript path outside trusted roots: ${filePath}` };
+	}
+	let lstat: fs.Stats;
+	try {
+		lstat = fs.lstatSync(resolvedPath);
+	} catch (error) {
+		if (isNotFoundError(error)) return { path: filePath, lines: [], truncated: false };
+		return { path: filePath, lines: [], truncated: false, error: getErrorMessage(error) };
+	}
+	if (lstat.isSymbolicLink()) return { path: filePath, lines: [], truncated: false, error: `Refusing to read symlink ${label} transcript path: ${filePath}` };
+	if (!lstat.isFile()) return { path: filePath, lines: [], truncated: false, error: `Refusing to read non-file ${label} transcript path: ${filePath}` };
+	let realPath: string;
+	let realRoots: string[];
+	try {
+		realPath = fs.realpathSync(resolvedPath);
+		realRoots = trustedRoots.filter((root) => fs.existsSync(root)).map((root) => fs.realpathSync(root));
+	} catch (error) {
+		return { path: filePath, lines: [], truncated: false, error: getErrorMessage(error) };
+	}
+	if (!realRoots.some((root) => pathWithin(root, realPath))) {
+		return { path: filePath, lines: [], truncated: false, error: `Refusing to read ${label} transcript path outside trusted roots: ${filePath}` };
+	}
+	return readTextTail(resolvedPath, maxLines);
+}
+
+function stringifyJsonPreview(value: unknown, maxLength = 240): string {
+	let raw: string;
+	if (typeof value === "string") raw = value;
+	else raw = JSON.stringify(value);
+	return raw.length > maxLength ? `${raw.slice(0, maxLength)}…` : raw;
+}
+
+function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content.map((part) => {
+		if (!part || typeof part !== "object") return "";
+		const entry = part as { type?: unknown; text?: unknown; name?: unknown; toolName?: unknown; args?: unknown; result?: unknown; content?: unknown };
+		if (typeof entry.text === "string") return entry.text;
+		if (entry.type === "toolCall" || entry.type === "tool_call") {
+			const name = typeof entry.name === "string" ? entry.name : typeof entry.toolName === "string" ? entry.toolName : "tool";
+			return `[tool: ${name}${entry.args === undefined ? "" : ` ${stringifyJsonPreview(entry.args)}`}]`;
+		}
+		if (entry.type === "toolResult" || entry.type === "tool_result") {
+			return `[tool result${entry.result === undefined ? "" : `: ${stringifyJsonPreview(entry.result)}`}]`;
+		}
+		if (entry.content !== undefined) return stringifyJsonPreview(entry.content);
+		return "";
+	}).filter(Boolean).join("\n");
+}
+
+function sessionMessageLine(record: unknown): string | undefined {
+	if (!record || typeof record !== "object") return undefined;
+	const outer = record as { message?: unknown; role?: unknown; content?: unknown; type?: unknown };
+	const message = outer.message && typeof outer.message === "object" ? outer.message as { role?: unknown; content?: unknown } : outer;
+	const role = typeof message.role === "string" ? message.role : undefined;
+	if (!role) return undefined;
+	const text = contentText(message.content).trim();
+	if (!text) return undefined;
+	return `${role}: ${text}`;
+}
+
+function readSessionTranscriptTail(sessionFile: string, maxLines: number, trustedRoots: string[]): { lines: string[]; warnings: string[] } {
+	const tail = readContainedTextTail(sessionFile, Math.max(maxLines * 4, maxLines), trustedRoots, "session");
+	const warnings: string[] = [];
+	if (tail.error) warnings.push(`Session read failed for ${sessionFile}: ${tail.error}`);
+	const lines: string[] = [];
+	let malformed = 0;
+	for (const line of tail.lines) {
+		if (!line.trim()) continue;
+		try {
+			const parsed = JSON.parse(line) as unknown;
+			const messageLine = sessionMessageLine(parsed);
+			if (messageLine) lines.push(messageLine);
+		} catch {
+			malformed++;
+		}
+	}
+	if (malformed > 0) warnings.push(`Skipped ${malformed} malformed session tail line${malformed === 1 ? "" : "s"}.`);
+	return { lines: lines.slice(-maxLines), warnings };
+}
+
+function formatActivityFacts(input: {
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	tokens?: { total: number };
+}): string | undefined {
+	const facts: string[] = [];
+	if (input.currentTool && input.currentToolStartedAt !== undefined) facts.push(`tool ${input.currentTool} ${formatDuration(Math.max(0, Date.now() - input.currentToolStartedAt))}`);
+	else if (input.currentTool) facts.push(`tool ${input.currentTool}`);
+	if (input.currentPath) facts.push(shortenPath(input.currentPath));
+	if (input.turnCount !== undefined) facts.push(`${input.turnCount} turns`);
+	if (input.toolCount !== undefined) facts.push(`${input.toolCount} tools`);
+	if (input.tokens?.total) facts.push(`${formatTokens(input.tokens.total)} tok`);
+	const activity = formatActivityLabel(input.lastActivityAt, input.activityState);
+	return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
+}
+
+function foregroundModeName(control: ForegroundControl): string {
+	if (control.mode === "single" && control.currentAgent) return control.currentAgent;
+	return control.mode;
+}
+
+function formatForegroundFleetLines(controls: ForegroundControl[]): string[] {
+	if (controls.length === 0) return [];
+	const lines = ["Foreground runs:"];
+	const ordered = [...controls].sort((left, right) => right.updatedAt - left.updatedAt);
+	for (const control of ordered) {
+		const activity = formatActivityFacts({
+			activityState: control.currentActivityState,
+			lastActivityAt: control.lastActivityAt,
+			currentTool: control.currentTool,
+			currentToolStartedAt: control.currentToolStartedAt,
+			currentPath: control.currentPath,
+			turnCount: control.turnCount,
+			toolCount: control.toolCount,
+			...(control.tokens !== undefined ? { tokens: { total: control.tokens } } : {}),
+		});
+		const current = control.currentAgent ? ` | ${control.currentAgent}${control.currentIndex !== undefined ? ` #${control.currentIndex}` : ""}` : "";
+		lines.push(`- ${control.runId} | running | ${foregroundModeName(control)}${current}${activity ? ` | ${activity}` : ""}`);
+		lines.push(`  status: subagent({ action: "status", id: "${control.runId}" })`);
+		lines.push("  transcript: live in the expanded foreground result; persisted session transcript appears after completion when sessions are enabled.");
+		lines.push(...formatNestedRunStatusLines(control.nestedChildren, { indent: "  ", commandHints: true, maxLines: 12 }));
+	}
+	return lines;
+}
+
+function formatAsyncFleetLines(runs: AsyncRunSummary[]): string[] {
+	if (runs.length === 0) return [];
+	const lines = ["Async runs:"];
+	for (const run of runs) {
+		const progress = formatAsyncRunProgressLabel(run);
+		const activity = formatActivityFacts(run);
+		const cwd = run.cwd ? shortenPath(run.cwd) : shortenPath(run.asyncDir);
+		const pending = run.pendingAppends ? ` | ${run.pendingAppends} pending append${run.pendingAppends === 1 ? "" : "s"}` : "";
+		lines.push(`- ${run.id} | ${run.state}${activity ? ` | ${activity}` : ""} | ${run.mode} | ${progress}${pending} | ${cwd}`);
+		lines.push(`  status: subagent({ action: "status", id: "${run.id}" })`);
+		lines.push(`  transcript: subagent({ action: "status", id: "${run.id}", view: "transcript" })`);
+		for (const step of run.steps) {
+			const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+			const phase = step.phase ? `[${step.phase}] ` : "";
+			const stepActivity = formatActivityFacts(step);
+			const modelThinking = formatModelThinking(step.model, step.thinking);
+			const parts = [`${step.index}. ${phase}${display}`, step.status, stepActivity, modelThinking].filter(Boolean);
+			lines.push(`  ${parts.join(" | ")}`);
+			const output = path.join(run.asyncDir, `output-${step.index}.log`);
+			if (fs.existsSync(output)) lines.push(`    output: ${shortenPath(output)}`);
+			if (step.sessionFile) lines.push(`    session: ${shortenPath(step.sessionFile)}`);
+			if (step.status === "running" || step.recentOutput?.length || fs.existsSync(output)) {
+				lines.push(`    transcript: subagent({ action: "status", id: "${run.id}", index: ${step.index}, view: "transcript" })`);
+			}
+			lines.push(...formatNestedRunStatusLines(step.children, { indent: "    ", commandHints: true, maxLines: 12 }));
+		}
+		const attached = new Set(run.steps.flatMap((step) => step.children?.map((child) => child.id) ?? []));
+		const unattached = run.nestedChildren?.filter((child) => !attached.has(child.id)) ?? [];
+		lines.push(...formatNestedRunStatusLines(unattached, { indent: "  ", commandHints: true, maxLines: 12 }));
+		if (run.error) lines.push(`  error: ${run.error}`);
+		for (const warning of run.nestedWarnings ?? []) lines.push(`  warning: ${warning}`);
+		const outputPath = formatAsyncRunOutputPath(run);
+		if (outputPath) lines.push(`  output: ${shortenPath(outputPath)}`);
+		if (run.sessionFile) lines.push(`  session: ${shortenPath(run.sessionFile)}`);
+	}
+	return lines;
+}
+
+export function inspectSubagentFleet(_params: FleetViewParams, deps: FleetViewDeps = {}): AgentToolResult<Details> {
+	if (deps.childSafe) {
+		return {
+			content: [{ type: "text", text: "Child-safe subagent fleet view is unavailable without an explicit run id. Use subagent({ action: \"status\", id: \"...\" }) for the delegated run you can see." }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	let asyncRuns: AsyncRunSummary[];
+	try {
+		asyncRuns = listAsyncRuns(deps.asyncDirRoot ?? ASYNC_DIR, {
+			states: ["queued", "running"],
+			sessionId: deps.state?.currentSessionId ?? undefined,
+			resultsDir: deps.resultsDir ?? RESULTS_DIR,
+			kill: deps.kill,
+			now: deps.now,
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
+	}
+
+	const foregroundControls = deps.state ? [...deps.state.foregroundControls.values()] : [];
+	const total = foregroundControls.length + asyncRuns.length;
+	if (total === 0) {
+		return {
+			content: [{ type: "text", text: "No active subagent fleet. Background runs that already finished are available through completion notifications or subagent({ action: \"status\", id: \"...\" })." }],
+			details: { mode: "management", results: [] },
+		};
+	}
+
+	const lines = [`Subagent fleet: ${total} active`, ""];
+	const foregroundLines = formatForegroundFleetLines(foregroundControls);
+	if (foregroundLines.length) lines.push(...foregroundLines, "");
+	const asyncLines = formatAsyncFleetLines(asyncRuns);
+	if (asyncLines.length) lines.push(...asyncLines, "");
+	lines.push("Commands:");
+	lines.push("  Refresh fleet: subagent({ action: \"status\", view: \"fleet\" })");
+	lines.push("  Tail run transcript: subagent({ action: \"status\", id: \"<run-id>\", view: \"transcript\" })");
+	lines.push("  Tail child transcript: subagent({ action: \"status\", id: \"<run-id>\", index: 0, view: \"transcript\" })");
+
+	return { content: [{ type: "text", text: lines.join("\n").trimEnd() }], details: { mode: "management", results: [] } };
+}
+
+function validateTranscriptIndex(index: number | undefined, steps: AsyncJobStep[]): number | undefined {
+	if (index === undefined) return undefined;
+	if (!Number.isInteger(index)) throw new Error("Transcript index must be an integer.");
+	if (index < 0 || index >= steps.length) throw new Error(`Transcript index ${index} is out of range for ${steps.length} child step${steps.length === 1 ? "" : "s"}.`);
+	return index;
+}
+
+function selectTranscriptStep(status: AsyncStatus, options: TranscriptOptions): { index?: number; step?: AsyncJobStep; hint?: string } {
+	const steps = status.steps ?? [];
+	let selectedIndex = validateTranscriptIndex(options.index, steps);
+	if (selectedIndex === undefined) {
+		if (status.state === "running" && typeof status.currentStep === "number" && status.currentStep >= 0 && status.currentStep < steps.length) {
+			selectedIndex = status.currentStep;
+		} else if (steps.length === 1) {
+			selectedIndex = 0;
+		}
+	}
+	const step = selectedIndex !== undefined ? steps[selectedIndex] : undefined;
+	const hint = options.index === undefined && steps.length > 1
+		? `Tip: pass index to inspect a specific child transcript (${steps.map((candidate, index) => `${index}=${candidate.agent}`).join(", ")}).`
+		: undefined;
+	return { index: selectedIndex, step, hint };
+}
+
+function stepStateLine(mode: SubagentRunMode, index: number | undefined, step: AsyncJobStep | undefined): string | undefined {
+	if (index === undefined || !step) return undefined;
+	const modelThinking = formatModelThinking(step.model, step.thinking);
+	const parts = [
+		`${mode === "parallel" ? "Agent" : "Step"}: ${index} (${step.agent})`,
+		step.status,
+		formatActivityFacts(step),
+		modelThinking,
+		step.error ? `error: ${step.error}` : undefined,
+	].filter(Boolean);
+	return parts.join(" | ");
+}
+
+function appendKnownArtifacts(lines: string[], input: { outputPaths: string[]; sessionFile?: string; eventsPath?: string; logPath?: string; resultPath?: string }): void {
+	const artifacts: string[] = [];
+	for (const outputPath of input.outputPaths) artifacts.push(`Output: ${outputPath}`);
+	if (input.sessionFile) artifacts.push(`Session: ${input.sessionFile}`);
+	if (input.eventsPath) artifacts.push(`Events: ${input.eventsPath}`);
+	if (input.logPath) artifacts.push(`Log: ${input.logPath}`);
+	if (input.resultPath) artifacts.push(`Result: ${input.resultPath}`);
+	if (!artifacts.length) return;
+	lines.push("Artifacts:");
+	for (const artifact of artifacts) lines.push(`  ${artifact}`);
+}
+
+function appendTranscriptBody(lines: string[], sourceLabel: string, sourceLines: string[], truncated: boolean): void {
+	lines.push(`${sourceLabel}${truncated ? " (tail truncated)" : ""}:`);
+	if (sourceLines.length === 0) {
+		lines.push("  (no transcript lines available yet)");
+		return;
+	}
+	for (const line of sourceLines) lines.push(`  ${line}`);
+}
+
+export function formatAsyncRunTranscript(status: AsyncStatus, asyncDir: string, options: TranscriptOptions = {}): string {
+	const lineLimit = transcriptLineLimit(options.lines);
+	const selected = selectTranscriptStep(status, options);
+	const stepOutputPath = selected.index !== undefined ? path.join(asyncDir, `output-${selected.index}.log`) : undefined;
+	const runOutputPath = resolveMaybeRelative(asyncDir, status.outputFile);
+	const logPath = path.join(asyncDir, `subagent-log-${status.runId}.md`);
+	const outputPaths = selected.index !== undefined
+		? uniqueStrings([stepOutputPath, runOutputPath && stepOutputPath && path.resolve(runOutputPath) === path.resolve(stepOutputPath) ? runOutputPath : undefined])
+		: uniqueStrings([runOutputPath]);
+	const sessionFile = selected.index !== undefined ? selected.step?.sessionFile : status.sessionFile;
+	const eventsPath = path.join(asyncDir, "events.jsonl");
+
+	const lines = [
+		`Run: ${status.runId}`,
+		`State: ${status.state}`,
+		`Mode: ${status.mode}`,
+		stepStateLine(status.mode, selected.index, selected.step),
+		selected.hint,
+	].filter((line): line is string => Boolean(line));
+	appendKnownArtifacts(lines, { outputPaths, sessionFile, eventsPath: fs.existsSync(eventsPath) ? eventsPath : undefined, logPath: fs.existsSync(logPath) ? logPath : undefined });
+
+	const warnings: string[] = [];
+	let transcriptLines: string[] = [];
+	let transcriptSource = "Transcript tail";
+	let truncated = false;
+	for (const outputPath of outputPaths) {
+		const tail = readContainedTextTail(outputPath, lineLimit, [asyncDir], "output");
+		if (tail.error) warnings.push(`Output read failed for ${tail.path}: ${tail.error}`);
+		if (tail.lines.length === 0) continue;
+		transcriptLines = tail.lines;
+		transcriptSource = `Transcript tail from ${tail.path}`;
+		truncated = tail.truncated;
+		break;
+	}
+	if (transcriptLines.length === 0 && selected.step?.recentOutput?.length) {
+		transcriptLines = selected.step.recentOutput.slice(-lineLimit);
+		transcriptSource = "Recent output from status.json";
+	}
+	if (transcriptLines.length === 0 && sessionFile) {
+		const sessionTail = readSessionTranscriptTail(sessionFile, lineLimit, options.sessionRoots ?? []);
+		transcriptLines = sessionTail.lines;
+		warnings.push(...sessionTail.warnings);
+		if (transcriptLines.length > 0) transcriptSource = `Session transcript tail from ${sessionFile}`;
+	}
+
+	if (warnings.length) {
+		lines.push("Warnings:");
+		for (const warning of warnings) lines.push(`  ${warning}`);
+	}
+	appendTranscriptBody(lines, transcriptSource, transcriptLines, truncated);
+	return lines.join("\n");
+}
+
+export function formatNestedRunTranscript(run: NestedRunSummary, options: TranscriptOptions = {}): string {
+	if (run.asyncDir) {
+		const status = readStatus(run.asyncDir);
+		if (status) return formatAsyncRunTranscript(status, run.asyncDir, options);
+	}
+	const lineLimit = transcriptLineLimit(options.lines);
+	const lines = [
+		`Nested run: ${run.id}`,
+		`State: ${run.state}`,
+		run.mode ? `Mode: ${run.mode}` : undefined,
+		run.agent ? `Agent: ${run.agent}` : run.agents?.length ? `Agents: ${run.agents.join(", ")}` : undefined,
+	].filter((line): line is string => Boolean(line));
+	appendKnownArtifacts(lines, { outputPaths: [], sessionFile: run.sessionFile });
+	if (!run.sessionFile) {
+		appendTranscriptBody(lines, "Transcript tail", [], false);
+		return lines.join("\n");
+	}
+	const sessionTail = readSessionTranscriptTail(run.sessionFile, lineLimit, options.sessionRoots ?? []);
+	if (sessionTail.warnings.length) {
+		lines.push("Warnings:");
+		for (const warning of sessionTail.warnings) lines.push(`  ${warning}`);
+	}
+	appendTranscriptBody(lines, `Session transcript tail from ${run.sessionFile}`, sessionTail.lines, false);
+	return lines.join("\n");
+}
+
+export function formatAsyncResultTranscript(data: {
+	id?: string;
+	runId?: string;
+	state?: string;
+	success?: boolean;
+	summary?: string;
+	output?: string;
+	sessionFile?: string;
+	agent?: string;
+	exitCode?: number | null;
+	results?: Array<{ agent?: string; output?: string; summary?: string; sessionFile?: string; state?: string; success?: boolean; exitCode?: number | null }>;
+}, resultPath: string, options: TranscriptOptions = {}): string {
+	const lineLimit = transcriptLineLimit(options.lines);
+	const runId = data.runId ?? data.id ?? path.basename(resultPath, ".json");
+	const children = Array.isArray(data.results)
+		? data.results
+		: data.agent
+			? [{ agent: data.agent, output: data.output, summary: data.summary, sessionFile: data.sessionFile, state: data.state, success: data.success, exitCode: data.exitCode }]
+			: [];
+	let index = options.index;
+	if (index !== undefined && !Number.isInteger(index)) throw new Error("Transcript index must be an integer.");
+	if (index === undefined && children.length === 1) index = 0;
+	if (index !== undefined && (index < 0 || index >= children.length)) throw new Error(`Transcript index ${index} is out of range for ${children.length} result child${children.length === 1 ? "" : "ren"}.`);
+	const child = index !== undefined ? children[index] : undefined;
+	const output = index !== undefined
+		? child?.output ?? child?.summary ?? (children.length === 1 ? data.output ?? data.summary : undefined) ?? ""
+		: data.output ?? data.summary ?? "";
+	const transcriptLines = output.split(/\r?\n/).slice(-lineLimit);
+	const sessionFile = child?.sessionFile ?? data.sessionFile;
+	const lines = [
+		`Run: ${runId}`,
+		`State: ${data.state ?? (data.success ? "complete" : "failed")}`,
+		index !== undefined && child ? `Child: ${index} (${child.agent ?? "subagent"})` : undefined,
+		index === undefined && children.length > 1 ? `Tip: pass index to inspect a specific child transcript (${children.map((candidate, childIndex) => `${childIndex}=${candidate.agent ?? "subagent"}`).join(", ")}).` : undefined,
+	].filter((line): line is string => Boolean(line));
+	appendKnownArtifacts(lines, { outputPaths: [], sessionFile, resultPath });
+	appendTranscriptBody(lines, "Result transcript tail", transcriptLines.filter((line) => line.trim()), output.split(/\r?\n/).length > lineLimit);
+	return lines.join("\n");
+}