@jopqior/pi-subagents 1.0.0

package/src/tools/get-result-report.ts

@@ -0,0 +1,84 @@
+/**
+ * get-result-report.ts — Pure report assembly for get_subagent_result.
+ *
+ * All functions are stateless: they receive an AgentReport, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by GetResultTool.execute in get-result-tool.ts. Mirrors the
+ * result-renderer.ts pattern used by the subagent tool's TUI renderer.
+ */
+
+import type { ResumeRefusal, SubagentStatus } from "#src/lifecycle/subagent";
+import {
+	renderOutcomeAddenda,
+	renderOutcomeBody,
+	renderStatusNote,
+} from "#src/observation/outcome-delivery";
+
+/** The data a get_subagent_result report renders from — only what the formatter reads. */
+export interface AgentReport {
+	id: string;
+	displayName: string;
+	status: SubagentStatus;
+	toolUses: number;
+	/** Pre-formatted lifetime token total; "" when zero. */
+	tokens: string;
+	contextPercent: number | null;
+	compactionCount: number;
+	/** Pre-formatted duration string. */
+	duration: string;
+	description: string;
+	result: string | undefined;
+	error: string | undefined;
+	/** Whether the agent was stopped before the limiter ever admitted it. */
+	stoppedWhileQueued: boolean;
+	/** Present only when verbose was requested and a conversation is available. */
+	conversation?: string;
+	/** Persisted transcript path; rendered as a pointer so the parent can read it directly. */
+	transcriptPath?: string;
+	/** The updates the agent sent while this call's carrier held the outcome. */
+	runUpdates?: readonly string[];
+	/** The question the agent ended its turn with, when it declared one. */
+	pendingQuestion?: string;
+	/**
+	 * Why a resume would be refused; undefined when one would be accepted.
+	 * Required, for the reason `OutcomeAddenda` gives.
+	 */
+	resumeRefusal: ResumeRefusal | undefined;
+	/** Where a teardown with no result text to carry it saved the agent's work. */
+	workspaceNotice?: string;
+}
+
+/** Assemble the stats parts: Tool uses / tokens? / Context? / Compactions? / Duration. */
+export function renderStatsParts(report: AgentReport): string[] {
+	const parts = [`Tool uses: ${report.toolUses}`];
+	if (report.tokens) parts.push(report.tokens);
+	if (report.contextPercent !== null) parts.push(`Context: ${Math.round(report.contextPercent)}%`);
+	if (report.compactionCount) parts.push(`Compactions: ${report.compactionCount}`);
+	parts.push(`Duration: ${report.duration}`);
+	return parts;
+}
+
+/**
+ * Select the per-status body. `AgentReport` structurally satisfies
+ * `OutcomeBody`, so this is the shared renderer under this carrier's name.
+ */
+export function renderReportBody(report: AgentReport): string {
+	return renderOutcomeBody(report);
+}
+
+/** Assemble the full get_subagent_result report text. */
+export function formatAgentReport(report: AgentReport): string {
+	let output =
+		`Agent: ${report.id}\n` +
+		`Type: ${report.displayName} | Status: ${report.status}${renderStatusNote(report.status)} | ${renderStatsParts(report).join(" | ")}\n` +
+		`Description: ${report.description}\n\n`;
+	output += renderReportBody(report);
+	output += renderOutcomeAddenda(report);
+	if (report.conversation) {
+		output += `\n\n--- Agent Conversation ---\n${report.conversation}`;
+	}
+	if (report.transcriptPath) {
+		output += `\n\nFull transcript available at: ${report.transcriptPath}`;
+	}
+	return output;
+}

package/src/tools/get-result-tool.ts

@@ -0,0 +1,192 @@
+import type { AgentToolResult, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import {
+	type GetResultDetails,
+	PREVIEW_CHARS,
+	renderGetResultLines,
+} from "#src/tools/get-result-renderer";
+import { type AgentReport, formatAgentReport } from "#src/tools/get-result-report";
+import { formatLifetimeTokens, textResult } from "#src/tools/helpers";
+import type { Subagent } from "#src/types";
+import { BoundedLines } from "#src/ui/bounded-lines";
+import { formatDuration, getDisplayName, type Theme } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+
+// ---- Deps interfaces ----
+
+export interface GetResultToolManager {
+	getRecord(id: string): Subagent | undefined;
+}
+
+// ---- Class ----
+
+export class GetResultTool {
+	constructor(
+		private readonly manager: GetResultToolManager,
+		private readonly registry: AgentConfigLookup,
+	) {}
+
+	async execute(
+		_toolCallId: string,
+		params: { agent_id: string; wait?: boolean; verbose?: boolean },
+		signal: AbortSignal,
+		_onUpdate: unknown,
+		_ctx: unknown,
+	) {
+		const record = this.manager.getRecord(params.agent_id);
+		if (!record) {
+			return textResult<GetResultDetails>(`Agent not found: "${params.agent_id}". Records are cleared at session start/switch, so it may be from a previous session.`);
+		}
+
+		// Wait for completion if requested. The record owns the decision of whether
+		// it is still awaitable — a queued agent counts, because scheduleVia()
+		// captures its limiter promise at spawn. A parent interrupt ends the wait
+		// without cancelling the agent, leaving the outcome uncollected below.
+		const waited = params.wait === true;
+		if (waited) {
+			// Waiting commits this call to delivering the outcome, so claim it before
+			// the agent can settle and be announced by the nudge instead.
+			record.claim();
+			await record.waitUntilSettled(signal);
+		}
+
+		// Pull-delivery edge: the parent is collecting the settled outcome here, so
+		// mark it consumed. An agent still active after a wait means the wait was
+		// abandoned, so release the claim this call made and let the nudge announce.
+		// Only a wait that claimed may release, so a concurrent carrier's claim is
+		// never cleared by this call.
+		if (!record.isActive()) {
+			record.markConsumed();
+		} else if (waited) {
+			record.release();
+		}
+
+		const verbose = params.verbose === true;
+		return textResult<GetResultDetails>(
+			formatAgentReport(this.buildReport(record, verbose)),
+			this.buildGetResultDetails(record, verbose),
+		);
+	}
+
+	private buildReport(record: Subagent, verbose?: boolean): AgentReport {
+		return {
+			id: record.id,
+			displayName: getDisplayName(record.type, this.registry),
+			status: record.status,
+			toolUses: record.toolUses,
+			tokens: formatLifetimeTokens(record),
+			contextPercent: record.getContextPercent(),
+			compactionCount: record.compactionCount,
+			duration: formatDuration(record.startedAt, record.completedAt),
+			description: record.description,
+			result: record.result,
+			error: record.error,
+			stoppedWhileQueued: record.stoppedWhileQueued,
+			conversation: verbose ? record.getConversation() : undefined,
+			// Transcript pointer: lets the parent read the full session from disk,
+			// and covers verbose after the live session was released (no conversation).
+			transcriptPath: record.outputFile,
+			runUpdates: record.runUpdates,
+			pendingQuestion: record.pendingQuestion,
+			resumeRefusal: record.resumeRefusal,
+			workspaceNotice: record.workspaceNotice,
+		};
+	}
+
+	/**
+	 * The compact metadata the TUI renders from.
+	 *
+	 * Named in full because `helpers.ts` exports a module-level `buildDetails`
+	 * producing the structurally different `AgentDetails`.
+	 */
+	private buildGetResultDetails(record: Subagent, verbose: boolean): GetResultDetails {
+		return {
+			agentId: record.id,
+			displayName: getDisplayName(record.type, this.registry),
+			status: record.status,
+			description: record.description,
+			toolUses: record.toolUses,
+			tokens: formatLifetimeTokens(record),
+			contextPercent: record.getContextPercent(),
+			compactionCount: record.compactionCount,
+			duration: formatDuration(record.startedAt, record.completedAt),
+			preview: buildPreview(record.result),
+			error: record.error,
+			verbose,
+			transcriptPath: record.outputFile,
+		};
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: "get_subagent_result" as const,
+			label: "Get Agent Result",
+			promptSnippet:
+				"Check status and retrieve results from a background agent.",
+			description:
+				"Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+			parameters: Type.Object({
+				agent_id: Type.String({
+					description: "The agent ID to check.",
+				}),
+				wait: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, wait for the agent to complete before returning. Default: false.",
+					}),
+				),
+				verbose: Type.Optional(
+					Type.Boolean({
+						description:
+							"If true, include the agent's full conversation (messages + tool calls). Default: false.",
+					}),
+				),
+			}),
+			// ---- Custom rendering: a bounded, Ctrl+O-expandable retrieval row ----
+
+			renderCall(args: { agent_id: string; wait?: boolean; verbose?: boolean }, theme: Theme) {
+				const notes = [args.wait === true ? "waiting" : "", args.verbose === true ? "verbose" : ""]
+					.filter(Boolean)
+					.join(", ");
+				return new Text(
+					`${GLYPHS.toolCall} ` +
+						theme.fg("toolTitle", theme.bold("Get Agent Result")) +
+						"  " +
+						theme.fg("muted", args.agent_id) +
+						(notes ? " " + theme.fg("muted", `(${notes})`) : ""),
+					0,
+					0,
+				);
+			},
+
+			renderResult(
+				result: AgentToolResult<GetResultDetails | undefined>,
+				{ expanded }: ToolRenderResultOptions,
+				theme: Theme,
+			) {
+				const reportText = result.content[0]?.type === "text" ? result.content[0].text : "";
+				const details = result.details;
+				if (!details) return new Text(reportText, 0, 0);
+				return new BoundedLines(renderGetResultLines(details, reportText, expanded, theme));
+			},
+
+			execute: (
+				toolCallId: string,
+				params: { agent_id: string; wait?: boolean; verbose?: boolean },
+				signal: AbortSignal,
+				onUpdate: unknown,
+				ctx: unknown,
+			) => this.execute(toolCallId, params, signal, onUpdate, ctx),
+		});
+	}
+}
+
+/** The first non-empty line of a result body, clipped to the preview budget. */
+function buildPreview(result: string | undefined): string | undefined {
+	const line = result?.split("\n").find((candidate) => candidate.trim())?.trim();
+	if (!line) return undefined;
+	return line.length > PREVIEW_CHARS ? line.slice(0, PREVIEW_CHARS - 1) + "\u2026" : line;
+}

package/src/tools/helpers.ts

@@ -0,0 +1,118 @@
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import { getLifetimeTotal, type LifetimeUsage } from "#src/lifecycle/usage";
+import { type AgentDetails, formatTokens } from "#src/ui/display";
+
+/** Build AgentDetails from a base + record-specific fields. */
+export function buildDetails(
+  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
+  record: {
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    status: string;
+    error?: string;
+    id?: string;
+    lifetimeUsage: LifetimeUsage;
+    /** Live-activity counters — exposed as getters on Subagent (Phase 18 Step 2). */
+    turnCount?: number;
+    maxTurns?: number;
+  },
+  overrides?: Partial<AgentDetails>,
+): AgentDetails {
+  return {
+    ...base,
+    toolUses: record.toolUses,
+    tokens: formatLifetimeTokens(record),
+    turnCount: record.turnCount,
+    maxTurns: record.maxTurns,
+    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
+    status: record.status as AgentDetails["status"],
+    agentId: record.id,
+    error: record.error,
+    ...overrides,
+  };
+}
+
+/** Render a spawn's advisories as the prefix a result's leading line follows, or "" when there are none. */
+export function renderSpawnNotes(notes: readonly string[]): string {
+  return notes.length > 0 ? `${notes.join("\n")}\n\n` : "";
+}
+
+/**
+ * Tool execute return value for a text response.
+ *
+ * Generic over the details payload so a tool with its own presentation metadata
+ * can attach it; defaults to `AgentDetails`, which is what every subagent-tool
+ * call site passes.
+ */
+export function textResult<T = AgentDetails>(msg: string, details?: T) {
+  return { content: [{ type: "text" as const, text: msg }], details };
+}
+
+/** Format an agent's lifetime token total, or "" when zero. */
+export function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
+  const t = getLifetimeTotal(o.lifetimeUsage);
+  return t > 0 ? formatTokens(t) : "";
+}
+
+/**
+ * Narrow registry interface needed by buildTypeListText.
+ * Extends AgentConfigLookup with the two name-listing methods.
+ */
+export interface TypeListRegistry extends AgentConfigLookup {
+  getDefaultAgentNames(): string[];
+  getUserAgentNames(): string[];
+}
+
+/**
+ * Build the full agent-type list text for the Agent tool description.
+ * Extracted from index.ts so it can be called inside createAgentTool.
+ */
+export function buildTypeListText(registry: TypeListRegistry, agentDir: string): string {
+  const defaultNames = registry.getDefaultAgentNames().filter((name) => isEnabledAgent(registry, name));
+  const userNames = registry.getUserAgentNames().filter((name) => isEnabledAgent(registry, name));
+
+  const defaultDescs = defaultNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+    return `- ${name}: ${cfg.description}${modelSuffix}`;
+  });
+
+  const customDescs = userNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    return `- ${name}: ${cfg.description}`;
+  });
+
+  return [
+    ...(defaultDescs.length > 0 ? ["Default agents:", ...defaultDescs] : []),
+    ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
+    "",
+    `Custom agents can be defined in .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
+  ].join("\n");
+}
+
+/** True when an agent config is present and not explicitly disabled. */
+function isEnabledAgent(registry: AgentConfigLookup, name: string): boolean {
+  return registry.resolveAgentConfig(name).enabled !== false;
+}
+
+/**
+ * Collect the per-agent usage guidelines for the subagent tool's Guidelines: block.
+ * Sourced from each enabled default agent's `toolGuideline`, in registry order,
+ * so a disabled built-in drops its guideline automatically.
+ */
+export function buildAgentGuidelines(registry: TypeListRegistry): string[] {
+  return registry
+    .getDefaultAgentNames()
+    .filter((name) => isEnabledAgent(registry, name))
+    .map((name) => registry.resolveAgentConfig(name).toolGuideline)
+    .filter((line): line is string => line !== undefined);
+}
+
+/** Derive a short model label from a model string. */
+export function getModelLabelFromConfig(model: string): string {
+  // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")
+  const name = model.includes("/") ? model.split("/").pop()! : model;
+  // Strip trailing date suffix (e.g. "claude-haiku-4-5-20251001" → "claude-haiku-4-5")
+  return name.replace(/-\d{8}$/, "");
+}

package/src/tools/result-renderer.ts

@@ -0,0 +1,153 @@
+/**
+ * result-renderer.ts — Pure per-status rendering functions for Agent tool results.
+ *
+ * All functions are stateless: they receive AgentDetails and a Theme, returning
+ * formatted strings. No SDK types, no timers, no side effects.
+ * Consumed by the renderResult hook in agent-tool.ts.
+ */
+
+import type { SubagentStatus } from "#src/lifecycle/subagent-state";
+import type { AgentDetails, Theme } from "#src/ui/display";
+import { formatMs, formatTurns } from "#src/ui/display";
+import { GLYPHS, SPINNER } from "#src/ui/glyphs";
+
+// ---- Dispatcher ----
+
+/** Dispatch to the per-status renderer based on details.status and isPartial. */
+export function renderAgentResult(
+	details: AgentDetails,
+	resultText: string,
+	expanded: boolean,
+	isPartial: boolean,
+	theme: Theme,
+): string {
+	if (isPartial || details.status === "running") return renderRunning(details, theme);
+	if (details.status === "background") return renderBackground(details, theme);
+	if (details.status === "completed" || details.status === "steered")
+		return renderCompleted(details, resultText, expanded, theme);
+	if (details.status === "stopped") return renderStopped(details, theme);
+	return renderFailed(details, theme);
+}
+
+// ---- Per-status renderers ----
+
+/** Render running/partial status: spinner + stats + activity line. */
+export function renderRunning(details: AgentDetails, theme: Theme): string {
+	const frame = SPINNER[details.spinnerFrame ?? 0];
+	const s = renderStats(details, theme);
+	let line = theme.fg("accent", frame) + (s ? " " + s : "");
+	line += "\n" + theme.fg("dim", `  ${GLYPHS.subLine}  ${details.activity ?? "thinking\u2026"}`);
+	return line;
+}
+
+/** Render background launch status. */
+export function renderBackground(details: AgentDetails, theme: Theme): string {
+	return theme.fg("dim", `  ${GLYPHS.subLine}  Running in background (ID: ${details.agentId})`);
+}
+
+/** Render completed or steered status with optional expanded result text. */
+export function renderCompleted(
+	details: AgentDetails,
+	resultText: string,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const duration = formatMs(details.durationMs);
+	const isSteered = details.status === "steered";
+	const icon = renderStatusIcon(isSteered ? "steered" : "completed", theme);
+	const s = renderStats(details, theme);
+	let line = icon + (s ? " " + s : "");
+	line += " " + theme.fg("dim", "\u00B7") + " " + theme.fg("dim", duration);
+
+	if (expanded) {
+		if (resultText) {
+			const lines = resultText.split("\n").slice(0, 50);
+			for (const l of lines) {
+				line += "\n" + theme.fg("dim", `  ${l}`);
+			}
+			if (resultText.split("\n").length > 50) {
+				line +=
+					"\n" +
+					theme.fg(
+						"muted",
+						"  ... (use get_subagent_result with verbose for full output)",
+					);
+			}
+		}
+	} else {
+		const doneText = isSteered ? "Wrapped up (turn limit)" : "Done";
+		line += "\n" + theme.fg("dim", `  ${GLYPHS.subLine}  ${doneText}`);
+	}
+	return line;
+}
+
+/** Render stopped status: dim stop icon + stats + "Stopped". */
+export function renderStopped(details: AgentDetails, theme: Theme): string {
+	const s = renderStats(details, theme);
+	let line = renderStatusIcon("stopped", theme) + (s ? " " + s : "");
+	line += "\n" + theme.fg("dim", `  ${GLYPHS.subLine}  Stopped`);
+	return line;
+}
+
+/** Render error or aborted status: error icon + stats + status message. */
+export function renderFailed(details: AgentDetails, theme: Theme): string {
+	const s = renderStats(details, theme);
+	let line = renderStatusIcon(details.status === "error" ? "error" : "aborted", theme) + (s ? " " + s : "");
+
+	if (details.status === "error") {
+		line +=
+			"\n" +
+			theme.fg("error", `  ${GLYPHS.subLine}  Error: ${details.error ?? "unknown"}`);
+	} else {
+		line +=
+			"\n" +
+			theme.fg("warning", `  ${GLYPHS.subLine}  Aborted (max turns exceeded)`);
+	}
+	return line;
+}
+
+// ---- Shared helpers ----
+
+/**
+ * The themed status glyph for a settled or pending agent.
+ *
+ * Exhaustive over `SubagentStatus`, so a status added later fails to compile
+ * here rather than falling through to an unmarked icon. Shared with
+ * `get-result-renderer.ts`, which draws the same vocabulary for the same enum.
+ */
+export function renderStatusIcon(status: SubagentStatus, theme: Theme): string {
+	switch (status) {
+		case "completed":
+			return theme.fg("success", GLYPHS.success);
+		case "steered":
+			return theme.fg("warning", GLYPHS.success);
+		case "stopped":
+			return theme.fg("dim", GLYPHS.stopped);
+		case "error":
+		case "aborted":
+			return theme.fg("error", GLYPHS.failure);
+		case "queued":
+			return theme.fg("dim", GLYPHS.queued);
+		case "running":
+			return theme.fg("dim", GLYPHS.streaming);
+	}
+}
+
+/**
+ * Build the stats string: "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k token".
+ * Returns an empty string when all fields are absent or zero.
+ */
+export function renderStats(details: AgentDetails, theme: Theme): string {
+	const parts: string[] = [];
+	if (details.modelName) parts.push(details.modelName);
+	if (details.tags) parts.push(...details.tags);
+	if (details.turnCount != null && details.turnCount > 0) {
+		parts.push(formatTurns(details.turnCount, details.maxTurns));
+	}
+	if (details.toolUses > 0)
+		parts.push(`${details.toolUses} tool use${details.toolUses === 1 ? "" : "s"}`);
+	if (details.tokens) parts.push(details.tokens);
+	return parts
+		.map((p) => theme.fg("dim", p))
+		.join(" " + theme.fg("dim", "\u00B7") + " ");
+}