@duckmind/dm-darwin-x64 0.43.4 → 0.48.5

package/extensions/dm-subagents/src/runs/background/fleet-view.ts

@@ -1,515 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { AgentToolResult } from "@duckmind/dm-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");
-}