@ryan_nookpi/pi-extension-subagent 0.1.0

package/tool-render.ts

@@ -0,0 +1,145 @@
+/**
+ * Rendering functions for the subagent tool's renderCall / renderResult.
+ *
+ * Extracted from commands.ts — output format is identical.
+ */
+
+import { getMarkdownTheme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { formatToolCall, formatUsageStats } from "./format.js";
+import { getDisplayItems, getFinalOutput } from "./runner.js";
+import { COLLAPSED_ITEM_COUNT } from "./store.js";
+import type { DisplayItem, SubagentDetails } from "./types.js";
+
+// ─── Helpers (internal) ──────────────────────────────────────────────────────
+
+type RenderTheme = {
+	fg: (color: ThemeColor, text: string) => string;
+	bold: (text: string) => string;
+};
+
+type ToolRenderResult = {
+	details?: unknown;
+	content: Array<{ type?: string; text?: string }>;
+};
+
+type ToolRenderArgs = { command?: unknown };
+
+function renderDisplayItems(items: DisplayItem[], expanded: boolean, theme: RenderTheme, limit?: number): string {
+	const toShow = limit ? items.slice(-limit) : items;
+	const skipped = limit && items.length > limit ? items.length - limit : 0;
+	let text = "";
+	if (skipped > 0) text += theme.fg("muted", `... ${skipped} earlier items\n`);
+	for (const item of toShow) {
+		if (item.type === "text") {
+			const preview = expanded ? item.text : item.text.split("\n").slice(0, 3).join("\n");
+			text += `${theme.fg("toolOutput", preview)}\n`;
+		} else {
+			text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
+		}
+	}
+	return text.trimEnd();
+}
+
+// ─── renderCall ──────────────────────────────────────────────────────────────
+
+export function renderSubagentToolCall(args: ToolRenderArgs, theme: RenderTheme) {
+	const raw = typeof args.command === "string" ? args.command.trim() : "";
+	const command = raw || "subagent help";
+	const MAX_CALL_LINES = 5;
+	const commandLines = command.split("\n");
+	const truncated = commandLines.length > MAX_CALL_LINES;
+	const preview = truncated ? commandLines.slice(0, MAX_CALL_LINES).join("\n") : command;
+
+	let text = theme.fg("toolTitle", theme.bold("subagent ")) + theme.fg("accent", "cli");
+	text += `\n  ${theme.fg("dim", preview)}`;
+	if (truncated) text += `\n  ${theme.fg("muted", `... +${commandLines.length - MAX_CALL_LINES} more lines`)}`;
+	return new Text(text, 0, 0);
+}
+
+// ─── renderResult ────────────────────────────────────────────────────────────
+
+export function renderSubagentToolResult(
+	result: ToolRenderResult,
+	{ expanded }: { expanded: boolean },
+	theme: RenderTheme,
+) {
+	const details = result.details as SubagentDetails | undefined;
+	if (!details || details.results.length === 0) {
+		const raw = result.content[0];
+		const fullText = (raw?.type === "text" ? raw.text : undefined) ?? "(no output)";
+		if (!expanded) {
+			const firstLine = fullText.split("\n")[0] ?? "";
+			const lineCount = fullText.split("\n").length;
+			const suffix = lineCount > 1 ? theme.fg("muted", ` (+${lineCount - 1} lines)`) : "";
+			return new Text(firstLine + suffix, 0, 0);
+		}
+		return new Text(fullText, 0, 0);
+	}
+
+	const mdTheme = getMarkdownTheme();
+	const r = details.results[0];
+	if (!r) {
+		const raw2 = result.content[0];
+		const fullText2 = (raw2?.type === "text" ? raw2.text : undefined) ?? "(no output)";
+		if (!expanded) {
+			const firstLine = fullText2.split("\n")[0] ?? "";
+			const lineCount = fullText2.split("\n").length;
+			const suffix = lineCount > 1 ? theme.fg("muted", ` (+${lineCount - 1} lines)`) : "";
+			return new Text(firstLine + suffix, 0, 0);
+		}
+		return new Text(fullText2, 0, 0);
+	}
+
+	const isError = r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
+	const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+	const displayItems = getDisplayItems(r.messages);
+	const finalOutput = getFinalOutput(r.messages);
+
+	if (expanded) {
+		const container = new Container();
+		let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+		if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+		container.addChild(new Text(header, 0, 0));
+		if (isError && r.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "task:"), 0, 0));
+		container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
+		container.addChild(new Spacer(1));
+		container.addChild(new Text(theme.fg("muted", "──────────────"), 0, 0));
+		container.addChild(new Spacer(1));
+		if (displayItems.length === 0 && !finalOutput) {
+			container.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
+		} else {
+			for (const item of displayItems) {
+				if (item.type === "toolCall") {
+					container.addChild(
+						new Text(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)), 0, 0),
+					);
+				}
+			}
+			if (finalOutput) {
+				container.addChild(new Spacer(1));
+				container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
+			}
+		}
+		const usageStr = formatUsageStats(r.usage, r.model);
+		if (usageStr) {
+			container.addChild(new Spacer(1));
+			container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+		}
+		return container;
+	}
+
+	let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+	if (isError && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
+	if (isError && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+	else if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
+	else {
+		text += `\n${renderDisplayItems(displayItems, expanded, theme, COLLAPSED_ITEM_COUNT)}`;
+		if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+	}
+	const usageStr = formatUsageStats(r.usage, r.model);
+	if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+	return new Text(text, 0, 0);
+}

package/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Type definitions, interfaces, and Typebox schemas for the Subagent tool.
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Message } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { AgentConfig, AgentRuntime } from "./agents.js";
+
+// ─── Interfaces ──────────────────────────────────────────────────────────────
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export interface SingleResult {
+	agent: string;
+	agentSource: "user" | "project" | "unknown";
+	task: string;
+	exitCode: number;
+	messages: Message[];
+	stderr: string;
+	usage: UsageStats;
+	model?: string;
+	stopReason?: string;
+	errorMessage?: string;
+	step?: number;
+	liveText?: string;
+	liveThinking?: string;
+	liveToolCalls?: number;
+	thoughtText?: string;
+	sessionFile?: string;
+	runtime?: AgentRuntime;
+	claudeSessionId?: string;
+	claudeProjectDir?: string;
+	liveActivityPreview?: string;
+}
+
+export interface BatchOrChainItem {
+	agent: string;
+	task: string;
+}
+
+export interface SubagentLaunchSummary {
+	agent: string;
+	mode: "run" | "continue" | "batch" | "chain";
+	runId?: number;
+	batchId?: string;
+	pipelineId?: string;
+	stepIndex?: number;
+}
+
+export interface SubagentDetails {
+	mode: "single" | "batch" | "chain";
+	inheritMainContext: boolean;
+	projectAgentsDir: string | null;
+	results: SingleResult[];
+	launches?: SubagentLaunchSummary[];
+}
+
+export interface CommandRunState {
+	id: number;
+	agent: string;
+	task: string;
+	displayTask?: string;
+	status: "running" | "done" | "error";
+	startedAt: number;
+	elapsedMs: number;
+	toolCalls: number;
+	lastLine: string;
+	lastOutput?: string;
+	continuedFromRunId?: number;
+	turnCount: number;
+	sessionFile?: string;
+	persistedSessionBaseOffset?: number;
+	abortController?: AbortController;
+	usage?: UsageStats;
+	model?: string;
+	removed?: boolean;
+	contextMode?: "main" | "sub";
+	thoughtText?: string;
+	/** Timestamp of last detected activity (tool call / turn / liveText change). Used for hang detection. */
+	lastActivityAt: number;
+	/** Number of auto-retries already attempted for this run. */
+	retryCount?: number;
+	/** Last transient failure reason that triggered an auto-retry. */
+	lastRetryReason?: string;
+	/** Hang detector reason preserved until the normal finalizer emits the sole completion. */
+	autoAbortReason?: string;
+	runtime?: AgentRuntime;
+	claudeSessionId?: string;
+	claudeProjectDir?: string;
+	/** Origin of this run: "tool" = LLM called subagent tool, "command" = user slash-command / >> shorthand. */
+	source?: "tool" | "command";
+	/** Optional batch group id for tool-level grouped parallel launches. */
+	batchId?: string;
+	/** Optional pipeline id for tool-level sequential launches. */
+	pipelineId?: string;
+	/** Zero-based step index inside batch/pipeline metadata. */
+	pipelineStepIndex?: number;
+	/** How completion/start events should be surfaced back to the user. */
+	deliveryMode?: "followUp" | "humanOnly";
+}
+
+export interface SessionReplayItem {
+	type: "user" | "assistant" | "tool";
+	title: string;
+	content: string;
+	timestamp: Date;
+	elapsed?: string;
+}
+
+export type DisplayItem =
+	| { type: "text"; text: string }
+	| { type: "toolCall"; name: string; args: Record<string, unknown> };
+
+export interface AgentAliasMatch {
+	matchedAgent?: AgentConfig;
+	ambiguousAgents: AgentConfig[];
+}
+
+export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
+
+/**
+ * Pending completion message stored when a run finishes while the user
+ * is in a different session from where the run originated.
+ */
+export interface PendingCompletion {
+	message: {
+		customType: string;
+		content: string;
+		display: boolean;
+		details: Record<string, unknown>;
+	};
+	options: {
+		deliverAs: "followUp";
+		triggerTurn?: boolean;
+	};
+	createdAt: number;
+}
+
+/** Live child process state owned by the current Pi extension runtime. */
+export interface GlobalRunEntry {
+	runState: CommandRunState;
+	abortController: AbortController;
+	originSessionFile: string;
+	/** Set when the run completes while the user is in a different session. */
+	pendingCompletion?: PendingCompletion;
+}
+
+export interface BatchGroupState {
+	batchId: string;
+	runIds: number[];
+	completedRunIds: Set<number>;
+	failedRunIds: Set<number>;
+	originSessionFile: string;
+	createdAt: number;
+	pendingResults: Map<number, string>;
+	pendingCompletion?: PendingCompletion;
+}
+
+export interface PipelineStepResult {
+	runId: number;
+	agent: string;
+	task: string;
+	output: string;
+	status: "done" | "error";
+}
+
+export interface PipelineState {
+	pipelineId: string;
+	currentIndex: number;
+	stepRunIds: number[];
+	stepResults: PipelineStepResult[];
+	originSessionFile: string;
+	createdAt: number;
+	pendingCompletion?: PendingCompletion;
+}
+
+export const ListAgentsParams = Type.Object({});
+
+export const SubagentParams = Type.Object({
+	command: Type.String({
+		description:
+			"Command string, e.g. 'subagent help', 'subagent run worker --main -- <task>', 'subagent batch --main --agent worker --task \"A\" --agent reviewer --task \"B\"'. Write long task context to a temp file and reference its path.",
+	}),
+});

package/utils/agent-utils.ts

@@ -0,0 +1,315 @@
+// Vendored from shared personal-extension utilities as a self-contained copy.
+// Maintained independently within this package.
+/**
+ * Pure utility functions extracted from subagent/agents.ts and subagent/runner.ts.
+ * These handle agent discovery helpers, normalization, matching, and alias computation.
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface AgentConfigLike {
+	name: string;
+	description: string;
+	source: string;
+	tools?: string[];
+	model?: string;
+}
+
+export interface AgentAliasMatch<T extends AgentConfigLike = AgentConfigLike> {
+	matchedAgent?: T;
+	ambiguousAgents: T[];
+}
+
+export const AGENT_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export type AgentThinkingLevel = (typeof AGENT_THINKING_LEVELS)[number];
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+export const CLAUDE_TOOL_MAP: Record<string, string | undefined> = {
+	bash: "bash",
+	read: "read",
+	edit: "edit",
+	write: "write",
+	grep: "grep",
+	glob: "find",
+	ls: "ls",
+	todowrite: "todo",
+	todoread: "todo",
+	skill: undefined,
+};
+
+export const PI_TO_CLAUDE_TOOL_MAP: Record<string, string> = {
+	read: "Read",
+	find: "Glob",
+	grep: "Grep",
+	bash: "Bash",
+	edit: "Edit",
+	write: "Write",
+	ls: "LS",
+};
+
+export function mapPiToolsToClaude(piTools: string[]): string[] {
+	const mapped: string[] = [];
+	for (const tool of piTools) {
+		const claudeTool = PI_TO_CLAUDE_TOOL_MAP[tool];
+		if (!claudeTool) {
+			throw new Error(
+				`Unsupported tool "${tool}" for Claude runtime. Supported tools: ${Object.keys(PI_TO_CLAUDE_TOOL_MAP).join(", ")}`,
+			);
+		}
+		mapped.push(claudeTool);
+	}
+	return Array.from(new Set(mapped));
+}
+
+export function isClaudeModel(model: string | undefined): boolean {
+	if (!model) return false;
+	const lower = model.toLowerCase();
+	return lower.startsWith("anthropic/claude-") || lower.startsWith("claude-");
+}
+
+export function validateClaudeRuntimeModel(model: string | undefined): void {
+	if (!model) return;
+	if (isClaudeModel(model)) return;
+	throw new Error(
+		`Model "${model}" is not supported with Claude runtime. Only Anthropic models (anthropic/claude-* or claude-*) are allowed.`,
+	);
+}
+
+export const CLAUDE_MODEL_ALIAS_MAP: Record<string, string> = {
+	opus: "claude-opus-4-7",
+	sonnet: "claude-sonnet-5",
+	haiku: "claude-haiku-4-5",
+};
+
+// ── Tool / Model / Thinking Normalization ───────────────────────────────────
+
+/**
+ * Normalize a comma-separated tool list according to the given format.
+ * For "claude" format, maps Claude tool names to pi equivalents.
+ */
+export function normalizeTools(rawTools: string | undefined, format: "pi" | "claude"): string[] | undefined {
+	if (!rawTools) return undefined;
+
+	const parsed = rawTools
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+
+	if (parsed.length === 0) return undefined;
+	if (format === "pi") return parsed;
+
+	const mapped = parsed
+		.map((tool) => CLAUDE_TOOL_MAP[tool.toLowerCase()] ?? undefined)
+		.filter((tool): tool is string => Boolean(tool));
+
+	if (mapped.length === 0) return undefined;
+	return Array.from(new Set(mapped));
+}
+
+/**
+ * Normalize a model reference according to the given format.
+ * For "claude" format, maps short aliases (opus, sonnet, haiku) to full model names.
+ */
+export function normalizeModel(rawModel: string | undefined, format: "pi" | "claude"): string | undefined {
+	if (!rawModel) return undefined;
+	const model = rawModel.trim();
+	if (!model) return undefined;
+
+	if (format === "claude") {
+		if (model.includes("/")) return model;
+		return CLAUDE_MODEL_ALIAS_MAP[model.toLowerCase()] ?? model;
+	}
+
+	return model;
+}
+
+/**
+ * Normalize and validate thinking level.
+ */
+export function normalizeThinkingLevel(rawThinking: string | undefined): AgentThinkingLevel | undefined {
+	if (!rawThinking) return undefined;
+	const thinking = rawThinking.trim().toLowerCase();
+	if (!thinking) return undefined;
+	if ((AGENT_THINKING_LEVELS as readonly string[]).includes(thinking)) return thinking as AgentThinkingLevel;
+	return undefined;
+}
+
+// ── Agent Alias / Initials ───────────────────────────────────────────────────
+
+/**
+ * Normalize an agent alias by lowercasing and removing non-alphanumeric chars.
+ */
+export function normalizeAgentAlias(value: string): string {
+	return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * Extract initials from agent name parts.
+ * "worker" → "w", "code-reviewer" → "cr"
+ */
+export function getAgentInitials(name: string): string {
+	return name
+		.toLowerCase()
+		.split(/[^a-z0-9]+/)
+		.filter(Boolean)
+		.map((part) => part[0])
+		.join("");
+}
+
+/**
+ * Deduplicate agents by name, keeping the first occurrence.
+ */
+export function uniqueAgentsByName<T extends { name: string }>(candidates: T[]): T[] {
+	const map = new Map<string, T>();
+	for (const agent of candidates) {
+		if (!map.has(agent.name)) map.set(agent.name, agent);
+	}
+	return Array.from(map.values());
+}
+
+// ── Agent Matching ───────────────────────────────────────────────────────────
+
+/**
+ * Match a user-supplied token against a list of agents using fuzzy matching.
+ * Priority: exact match → prefix match → initials match → contains match.
+ */
+export function matchSubCommandAgent<T extends AgentConfigLike>(agents: T[], token: string): AgentAliasMatch<T> {
+	const raw = token.trim().toLowerCase();
+	if (!raw) return { ambiguousAgents: [] };
+
+	const normalized = normalizeAgentAlias(raw);
+
+	// Exact match
+	const exact = uniqueAgentsByName(
+		agents.filter((agent) => {
+			const name = agent.name.toLowerCase();
+			if (name === raw) return true;
+			if (normalized && normalizeAgentAlias(name) === normalized) return true;
+			return false;
+		}),
+	);
+	if (exact.length === 1) return { matchedAgent: exact[0], ambiguousAgents: [] };
+	if (exact.length > 1) return { ambiguousAgents: exact };
+
+	// Prefix match
+	const prefix = uniqueAgentsByName(
+		agents.filter((agent) => {
+			const name = agent.name.toLowerCase();
+			const nameNormalized = normalizeAgentAlias(name);
+			const parts = name.split(/[^a-z0-9]+/).filter(Boolean);
+			if (name.startsWith(raw)) return true;
+			if (normalized && nameNormalized.startsWith(normalized)) return true;
+			if (parts.some((part) => part.startsWith(raw))) return true;
+			if (normalized && parts.some((part) => normalizeAgentAlias(part).startsWith(normalized))) return true;
+			return false;
+		}),
+	);
+	if (prefix.length === 1) return { matchedAgent: prefix[0], ambiguousAgents: [] };
+	if (prefix.length > 1) return { ambiguousAgents: prefix };
+
+	// Initials match
+	const initialsMatch = uniqueAgentsByName(
+		agents.filter((agent) => {
+			const agentInitials = getAgentInitials(agent.name);
+			return normalized === agentInitials;
+		}),
+	);
+	if (initialsMatch.length === 1) return { matchedAgent: initialsMatch[0], ambiguousAgents: [] };
+	if (initialsMatch.length > 1) return { ambiguousAgents: initialsMatch };
+
+	// Contains match
+	const contains = uniqueAgentsByName(
+		agents.filter((agent) => {
+			const name = agent.name.toLowerCase();
+			const nameNormalized = normalizeAgentAlias(name);
+			if (name.includes(raw)) return true;
+			if (normalized && nameNormalized.includes(normalized)) return true;
+			return false;
+		}),
+	);
+	if (contains.length === 1) return { matchedAgent: contains[0], ambiguousAgents: [] };
+	if (contains.length > 1) return { ambiguousAgents: contains };
+
+	return { ambiguousAgents: [] };
+}
+
+/**
+ * Get tab-completion candidates for an agent name prefix.
+ */
+export function getSubCommandAgentCompletions<T extends AgentConfigLike>(
+	agents: T[],
+	argumentPrefix: string,
+): { value: string; label: string; description?: string }[] | null {
+	const trimmedStart = argumentPrefix.trimStart();
+	if (trimmedStart.includes(" ")) return null;
+
+	const raw = trimmedStart.toLowerCase();
+	const normalized = normalizeAgentAlias(raw);
+
+	const scored = agents
+		.map((agent) => {
+			const name = agent.name.toLowerCase();
+			const nameNormalized = normalizeAgentAlias(name);
+			const parts = name.split(/[^a-z0-9]+/).filter(Boolean);
+			const agentInitials = getAgentInitials(name);
+
+			let score = Number.POSITIVE_INFINITY;
+			if (!raw) score = 100;
+			else if (name === raw || (normalized && nameNormalized === normalized)) score = 0;
+			else if (name.startsWith(raw) || (normalized && nameNormalized.startsWith(normalized))) score = 1;
+			else if (
+				parts.some((part) => part.startsWith(raw)) ||
+				(normalized && parts.some((part) => normalizeAgentAlias(part).startsWith(normalized)))
+			)
+				score = 2;
+			else if (normalized && agentInitials === normalized) score = 3;
+			else if (name.includes(raw) || (normalized && nameNormalized.includes(normalized))) score = 4;
+
+			return { agent, score };
+		})
+		.filter((row) => Number.isFinite(row.score))
+		.sort((a, b) => a.score - b.score || a.agent.name.localeCompare(b.agent.name))
+		.slice(0, 20)
+		.map(({ agent }) => ({
+			value: `${agent.name} `,
+			label: agent.name,
+			description: agent.description || `[${agent.source}]`,
+		}));
+
+	return scored.length > 0 ? scored : null;
+}
+
+/**
+ * Compute shortest usable alias for each agent and return a formatted hint string.
+ * e.g. "w→worker  s→searcher  r→reviewer  v→verifier"
+ */
+export function computeAgentAliasHints<T extends AgentConfigLike>(agents: T[]): string {
+	const hints: string[] = [];
+
+	for (const agent of agents) {
+		const name = agent.name.toLowerCase();
+		const initials = getAgentInitials(name);
+
+		let shortestAlias = name;
+		for (let i = 1; i <= name.length; i++) {
+			const candidate = name.slice(0, i);
+			const result = matchSubCommandAgent(agents, candidate);
+			if (result.matchedAgent?.name === agent.name) {
+				shortestAlias = candidate;
+				break;
+			}
+		}
+
+		if (initials.length >= 2 && initials.length <= shortestAlias.length) {
+			const result = matchSubCommandAgent(agents, initials);
+			if (result.matchedAgent?.name === agent.name) {
+				shortestAlias = initials;
+			}
+		}
+
+		hints.push(shortestAlias === name ? name : `${shortestAlias}→${name}`);
+	}
+
+	return hints.join("  ");
+}