pi-dev-team 0.2.0

package/extensions/dev-team/lib/subagent-render.ts

@@ -0,0 +1,245 @@
+/**
+ * TUI renderers for `dev_team_subagent`, after pi's examples/extensions/subagent.
+ *
+ * Rendering only: the tool's `content` stays the model-facing result, so print/json/rpc modes are
+ * unaffected. Everything shown comes from `details` (SubagentDetails), which the tool streams through
+ * onUpdate while children run and returns final in the result. Child-derived text is sanitized first,
+ * as pi's own tool renderer does, so child output cannot drive the terminal.
+ */
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { getMarkdownTheme, type Theme, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { formatAiCredits, runsAiCredits } from "./ai-credits.ts";
+import {
+	creditedRuns,
+	type DispatchArgs,
+	describeWorktree,
+	dispatchAgent,
+	dispatchTask,
+	type SubagentDetails,
+	type SubagentTaskView,
+	type ToolCallSummary,
+	type UsageTotals,
+} from "./subagent-types.ts";
+import { sanitizeTerminalText } from "./terminal-text.ts";
+
+const COLLAPSED_TOOLS = 3;
+const COLLAPSED_OUTPUT_LINES = 3;
+const CALL_PREVIEW_TASKS = 4;
+const SINGLE_CALL_PREVIEW_CHARS = 80;
+const PARALLEL_CALL_PREVIEW_CHARS = 50;
+const COLLAPSED_ERROR_CHARS = 300;
+
+function preview(text: string | undefined, maxChars: number): string {
+	const flat = sanitizeTerminalText(text ?? "").replace(/\s+/g, " ").trim();
+	return flat.length > maxChars ? `${flat.slice(0, maxChars)}…` : flat || "…";
+}
+
+function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	return `${(n / 1000).toFixed(n >= 10_000 ? 0 : 1)}k`;
+}
+
+export interface UsageLineOptions {
+	model?: string;
+	durationMs?: number;
+	/** The GitHub Copilot AI credits within `u.cost`, shown after it when not 0. */
+	aiCredits?: number;
+}
+
+/** One usage line: turns, tokens, cost (with its AI credits), duration and model. */
+export function formatUsage(u: UsageTotals | undefined, { model, durationMs, aiCredits = 0 }: UsageLineOptions = {}): string {
+	if (!u) return "";
+	const parts = [`${u.turns} turn${u.turns === 1 ? "" : "s"}`, `↑${formatTokens(u.input)}`, `↓${formatTokens(u.output)}`];
+	if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
+	if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
+	if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
+	if (aiCredits) parts.push(`(${formatAiCredits(aiCredits)})`);
+	if (durationMs !== undefined) parts.push(`${(durationMs / 1000).toFixed(1)}s`);
+	if (model) parts.push(sanitizeTerminalText(model));
+	return parts.join(" ");
+}
+
+/** One agent's own usage line (what it dispatched itself is in the parallel total). */
+function agentUsageLine(v: SubagentTaskView): string {
+	const aiCredits = v.usage ? runsAiCredits([{ model: v.model, usage: v.usage }]) : 0;
+	return formatUsage(v.usage, { model: v.model, durationMs: v.durationMs, aiCredits });
+}
+
+function addTotals(t: UsageTotals, u: UsageTotals): UsageTotals {
+	return {
+		input: t.input + u.input,
+		output: t.output + u.output,
+		cacheRead: t.cacheRead + u.cacheRead,
+		cacheWrite: t.cacheWrite + u.cacheWrite,
+		cost: t.cost + u.cost,
+		turns: t.turns + u.turns,
+	};
+}
+
+/** Everything the agents cost, including what they dispatched themselves (what pi books for the call). */
+function sumUsageTotals(views: SubagentTaskView[]): UsageTotals {
+	const usages = views.flatMap((v) => creditedRuns(v).map((run) => run.usage));
+	return usages.reduce(addTotals, { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 });
+}
+
+function statusIcon(v: SubagentTaskView, theme: Theme): string {
+	if (v.status === "running") return theme.fg("warning", "⏳");
+	return v.status === "ok" ? theme.fg("success", "✓") : theme.fg("error", "✗");
+}
+
+function headerLine(v: SubagentTaskView, theme: Theme): string {
+	let line = `${statusIcon(v, theme)} ${theme.fg("toolTitle", theme.bold(sanitizeTerminalText(v.agent)))}`;
+	if (v.source === "project") line += theme.fg("muted", " (project)");
+	if (v.tier && v.tier !== "inherit") line += theme.fg("muted", ` [${sanitizeTerminalText(v.tier)}]`);
+	if (v.status === "failed" && v.stopReason && v.stopReason !== "stop") line += ` ${theme.fg("error", `[${sanitizeTerminalText(v.stopReason)}]`)}`;
+	return line;
+}
+
+function worktreeLine(v: SubagentTaskView, theme: Theme): string {
+	return v.worktree ? theme.fg("muted", `worktree ${sanitizeTerminalText(describeWorktree(v.worktree))}`) : "";
+}
+
+const TOOL_CALL_CHARS = 80;
+
+/**
+ * A tool call as the progress view shows it, after pi's subagent example: `$ cmd`, `read path`,
+ * `grep /pattern/ in path`, otherwise the tool name and its path, file_path, url or name argument.
+ */
+export function formatToolCall(call: ToolCallSummary): string {
+	const a = call.args ?? {};
+	let text: string;
+	if (call.name === "bash" && a.command) text = `$ ${a.command}`;
+	else if (call.name === "grep" && a.pattern) text = `grep /${a.pattern}/ in ${a.path ?? "."}`;
+	else if (call.name === "find" && a.pattern) text = `find ${a.pattern} in ${a.path ?? "."}`;
+	else if (call.name === "dev_team_subagent") {
+		const who = a.agent ?? a.subagent_type ?? (a.tasks ? `${a.tasks} agents` : undefined);
+		text = who ? `dev-team ${who}` : "dev-team";
+	} else {
+		const target = a.path ?? a.file_path ?? a.url ?? a.name;
+		text = target ? `${call.name} ${target}` : call.name;
+	}
+	return text.length > TOOL_CALL_CHARS ? `${text.slice(0, TOOL_CALL_CHARS - 1)}…` : text;
+}
+
+/** A view's recent calls as display lines; stored sessions may still carry plain tool names. */
+export function recentCallLines(v: Pick<SubagentTaskView, "recentCalls" | "tools">): string[] {
+	return v.recentCalls ? v.recentCalls.map(formatToolCall) : (v.tools ?? []);
+}
+
+function toolLines(tools: string[], theme: Theme): string {
+	return tools.map((t) => `${theme.fg("muted", "→ ")}${theme.fg("accent", sanitizeTerminalText(t))}`).join("\n");
+}
+
+/** Collapsed block for one agent: header, latest tool calls or the start of its output, usage. */
+function renderCollapsed(v: SubagentTaskView, theme: Theme): string {
+	const lines = [headerLine(v, theme)];
+	if (v.status === "failed" && v.error) lines.push(theme.fg("error", `Error: ${preview(v.error, COLLAPSED_ERROR_CHARS)}`));
+	else if (v.status === "running") {
+		const calls = recentCallLines(v);
+		lines.push(calls.length ? toolLines(calls.slice(-COLLAPSED_TOOLS), theme) : theme.fg("muted", "(starting…)"));
+	}
+	else if (v.output) {
+		lines.push(theme.fg("toolOutput", sanitizeTerminalText(v.output).trim().split("\n").slice(0, COLLAPSED_OUTPUT_LINES).join("\n")));
+	} else lines.push(theme.fg("muted", "(no output)"));
+	const wt = worktreeLine(v, theme);
+	if (wt) lines.push(wt);
+	const usage = agentUsageLine(v);
+	if (usage) lines.push(theme.fg("dim", usage));
+	return lines.join("\n");
+}
+
+/** Expanded block for one agent: header, task, recent tool calls, full output as markdown, usage. */
+function renderExpandedInto(container: Container, v: SubagentTaskView, theme: Theme): void {
+	container.addChild(new Text(headerLine(v, theme), 0, 0));
+	container.addChild(new Text(`${theme.fg("muted", "Task: ")}${theme.fg("dim", sanitizeTerminalText(v.task))}`, 0, 0));
+	const calls = recentCallLines(v);
+	if (calls.length) container.addChild(new Text(toolLines(calls, theme), 0, 0));
+	if (v.status === "failed" && v.error) container.addChild(new Text(theme.fg("error", `Error: ${sanitizeTerminalText(v.error)}`), 0, 0));
+	if (v.output) {
+		container.addChild(new Spacer(1));
+		container.addChild(new Markdown(sanitizeTerminalText(v.output).trim(), 0, 0, getMarkdownTheme()));
+	}
+	const wt = worktreeLine(v, theme);
+	if (wt) container.addChild(new Text(wt, 0, 0));
+	const usage = agentUsageLine(v);
+	if (usage) container.addChild(new Text(theme.fg("dim", usage), 0, 0));
+}
+
+export function renderSubagentCall(args: DispatchArgs & { tasks?: DispatchArgs[] }, theme: Theme): Component {
+	const title = theme.fg("toolTitle", theme.bold("dev-team "));
+	if (args.tasks?.length) {
+		let text = `${title}${theme.fg("accent", `parallel (${args.tasks.length} agents)`)}`;
+		for (const t of args.tasks.slice(0, CALL_PREVIEW_TASKS)) {
+			text += `\n  ${theme.fg("accent", preview(dispatchAgent(t), PARALLEL_CALL_PREVIEW_CHARS))}${theme.fg("dim", ` ${preview(dispatchTask(t), PARALLEL_CALL_PREVIEW_CHARS)}`)}`;
+		}
+		const hiddenTaskCount = args.tasks.length - CALL_PREVIEW_TASKS;
+		if (hiddenTaskCount > 0) text += `\n  ${theme.fg("muted", `… +${hiddenTaskCount} more`)}`;
+		return new Text(text, 0, 0);
+	}
+	let text = `${title}${theme.fg("accent", preview(dispatchAgent(args), SINGLE_CALL_PREVIEW_CHARS))}`;
+	if (args.isolation === "worktree") text += theme.fg("muted", " [worktree]");
+	text += `\n  ${theme.fg("dim", preview(dispatchTask(args), SINGLE_CALL_PREVIEW_CHARS))}`;
+	return new Text(text, 0, 0);
+}
+
+export function renderSubagentResult(
+	result: AgentToolResult<unknown>,
+	{ expanded, isPartial }: ToolRenderResultOptions,
+	theme: Theme,
+): Component {
+	const details = result.details as SubagentDetails | undefined;
+	if (!details?.results?.length) {
+		const first = result.content[0];
+		return new Text(sanitizeTerminalText(first?.type === "text" ? first.text : "(no output)"), 0, 0);
+	}
+	const views = details.results;
+	const skipped = details.skippedProjectAgents ?? details.untrustedProjectAgents ?? [];
+	const skippedNote = skipped.length
+		? theme.fg("warning", `project agents skipped (project not trusted): ${sanitizeTerminalText(skipped.join(", "))}`)
+		: "";
+
+	if (views.length === 1) {
+		const v = views[0];
+		if (expanded && !isPartial) {
+			const c = new Container();
+			renderExpandedInto(c, v, theme);
+			if (skippedNote) c.addChild(new Text(skippedNote, 0, 0));
+			return c;
+		}
+		let text = renderCollapsed(v, theme);
+		if (skippedNote) text += `\n${skippedNote}`;
+		if (!isPartial && v.output && v.output.trim().split("\n").length > COLLAPSED_OUTPUT_LINES) {
+			text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+		}
+		return new Text(text, 0, 0);
+	}
+
+	const runningCount = views.filter((v) => v.status === "running").length;
+	const failedCount = views.filter((v) => v.status === "failed").length;
+	const summaryLine = runningCount
+		? `${theme.fg("warning", "⏳")} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", `${views.length - runningCount}/${views.length} done, ${runningCount} running`)}`
+		: `${failedCount ? theme.fg("warning", "◐") : theme.fg("success", "✓")} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", `${views.length - failedCount}/${views.length} succeeded`)}`;
+	const totalUsageText = runningCount ? "" : formatUsage(sumUsageTotals(views), { aiCredits: runsAiCredits(views.flatMap((v) => creditedRuns(v))) });
+
+	if (expanded && !runningCount) {
+		const c = new Container();
+		c.addChild(new Text(summaryLine, 0, 0));
+		for (const v of views) {
+			c.addChild(new Spacer(1));
+			renderExpandedInto(c, v, theme);
+		}
+		if (skippedNote) c.addChild(new Text(skippedNote, 0, 0));
+		if (totalUsageText) {
+			c.addChild(new Spacer(1));
+			c.addChild(new Text(theme.fg("dim", `Total: ${totalUsageText}`), 0, 0));
+		}
+		return c;
+	}
+	let text = summaryLine;
+	for (const v of views) text += `\n\n${renderCollapsed(v, theme)}`;
+	if (skippedNote) text += `\n\n${skippedNote}`;
+	if (totalUsageText) text += `\n\n${theme.fg("dim", `Total: ${totalUsageText}`)}`;
+	if (!runningCount) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
+	return new Text(text, 0, 0);
+}

package/extensions/dev-team/lib/subagent-types.ts

@@ -0,0 +1,164 @@
+/**
+ * Shapes and small pure helpers shared by the `dev_team_subagent` tool, its TUI renderers and the
+ * cost meter. A leaf module: it imports nothing from the tool or the renderers, so both depend on it
+ * rather than on each other.
+ */
+import type { Usage } from "@earendil-works/pi-ai";
+
+export const SUBAGENT_USAGE_ENTRY = "dev-team-subagent-usage";
+
+/** Where an agent definition came from: the project (.pi/agents, .claude/agents) or this package. */
+export type AgentSource = "project" | "package";
+
+/** One child's usage as the cost meter and the renderers read it (cost is the total in USD). */
+export interface UsageTotals {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+
+/**
+ * A child's tool call as kept for the progress view: the tool and the few arguments the view shows
+ * (command, pattern, path, ...), each one line and bounded, so stored details stay small.
+ */
+export interface ToolCallSummary {
+	name: string;
+	args?: Record<string, string>;
+}
+
+/** Spend of an agent dispatched by a child (or deeper), credited to that agent and its model. */
+export interface NestedUsage {
+	agent: string;
+	model?: string;
+	usage: UsageTotals;
+}
+
+/** Payload of the SUBAGENT_USAGE_ENTRY session entry the cost meter reads. */
+export interface SubagentUsageEntry {
+	agent: string;
+	model?: string;
+	tier?: string;
+	ok: boolean;
+	durationMs: number;
+	/** The child's own turns only. */
+	usage: UsageTotals;
+	/** Agents the child dispatched itself, at any depth. */
+	nested?: NestedUsage[];
+}
+
+export interface WorktreeInfo {
+	path: string;
+	branch: string;
+	kept: boolean;
+	dirty: boolean;
+	commits: number;
+}
+
+/** One dispatch as the renderers see it. Streamed through onUpdate while running, final in the result. */
+export interface SubagentTaskView {
+	agent: string;
+	source?: AgentSource;
+	task: string;
+	status: "running" | "ok" | "failed";
+	/** Same as status === "ok"; kept from the earlier details shape (DispatchProgress keeps them in step). */
+	ok: boolean;
+	model?: string;
+	tier?: string;
+	turns: number;
+	/** Most recent tool calls, newest last (bounded); the renderer formats them. */
+	recentCalls: ToolCallSummary[];
+	/** Earlier details shape (tool names only), still found in stored sessions. */
+	tools?: string[];
+	/** The agent's own turns. */
+	usage?: UsageTotals;
+	/** Agents it dispatched itself, so a parent can credit them in turn. */
+	nested?: NestedUsage[];
+	durationMs?: number;
+	stopReason?: string;
+	error?: string;
+	output?: string;
+	worktree?: WorktreeInfo;
+}
+
+/** Progress fields a running child reports; status/ok are set only from the final result. */
+export type ProgressPatch = Partial<Pick<SubagentTaskView, "agent" | "source" | "turns" | "recentCalls" | "model" | "usage">>;
+
+export interface SubagentDetails {
+	results: SubagentTaskView[];
+	/** Project agents that were requested but not run because pi trust was declined for the project. */
+	skippedProjectAgents?: string[];
+	/** Earlier name of skippedProjectAgents, still found in stored sessions. */
+	untrustedProjectAgents?: string[];
+}
+
+/** Tool arguments, with the Claude Agent/Task aliases (subagent_type, prompt) still possible. */
+export interface DispatchArgs {
+	agent?: string;
+	subagent_type?: string;
+	task?: string;
+	prompt?: string;
+	description?: string;
+	model?: string;
+	thinking?: string;
+	cwd?: string;
+	isolation?: string;
+}
+
+export function dispatchAgent(args: DispatchArgs): string {
+	return (args.agent ?? args.subagent_type ?? "").trim();
+}
+
+export function dispatchTask(args: DispatchArgs): string {
+	return (args.task ?? args.prompt ?? "").trim();
+}
+
+/** "kept: <path> on branch <b>, N commit(s)[, uncommitted changes]" or "removed: no changes". */
+export function describeWorktree(wt: WorktreeInfo): string {
+	if (!wt.kept) return "removed: no changes";
+	return `kept: ${wt.path} on branch ${wt.branch}, ${wt.commits} commit(s)${wt.dirty ? ", uncommitted changes" : ""}`;
+}
+
+/**
+ * The spend one dispatched agent accounts for: its own run (when it reported usage), then every run it
+ * dispatched itself. The single rule the cost meter, the parent's crediting and the TUI total share.
+ */
+export function creditedRuns(run: { agent: string; model?: string; usage?: UsageTotals; nested?: NestedUsage[] }): NestedUsage[] {
+	return [...(run.usage ? [{ agent: run.agent, model: run.model, usage: run.usage }] : []), ...(run.nested ?? [])];
+}
+
+export function emptyPiUsage(): Usage {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+}
+
+/** Add one message's usage (pi-ai `Usage`, possibly partial) into `into`. `into` is a local accumulator. */
+export function addPiUsage(into: Usage, u: Partial<Usage> | undefined): void {
+	if (!u) return;
+	into.input += u.input ?? 0;
+	into.output += u.output ?? 0;
+	into.cacheRead += u.cacheRead ?? 0;
+	into.cacheWrite += u.cacheWrite ?? 0;
+	into.totalTokens += u.totalTokens ?? (u.input ?? 0) + (u.output ?? 0) + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+	if (u.cacheWrite1h !== undefined) into.cacheWrite1h = (into.cacheWrite1h ?? 0) + u.cacheWrite1h;
+	if (u.reasoning !== undefined) into.reasoning = (into.reasoning ?? 0) + u.reasoning;
+	into.cost.input += u.cost?.input ?? 0;
+	into.cost.output += u.cost?.output ?? 0;
+	into.cost.cacheRead += u.cost?.cacheRead ?? 0;
+	into.cost.cacheWrite += u.cost?.cacheWrite ?? 0;
+	into.cost.total += u.cost?.total ?? 0;
+}
+
+/** Combined usage of all children, for the tool result: pi adds tool-result usage to session totals. */
+export function sumPiUsage(usages: (Usage | undefined)[]): Usage | undefined {
+	const present = usages.filter((u): u is Usage => u !== undefined);
+	if (!present.length) return undefined;
+	const total = emptyPiUsage();
+	for (const u of present) addPiUsage(total, u);
+	return total;
+}
+
+export function toUsageTotals(u: Usage, turns: number): UsageTotals {
+	return { input: u.input, output: u.output, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite, cost: u.cost.total, turns };
+}