@nghyane/arcane 0.1.13 → 0.1.15

package/src/tools/subagent-tool.ts

@@ -1,25 +1,33 @@
 /**
- * Generic subagent tool factory.
+ * Subagent tool system.
  *
  * All standalone subagent tools (explore, oracle, librarian, code_review)
- * share identical execution logic. This factory eliminates the boilerplate.
+ * share identical execution logic. Each tool is a config object;
+ * SubagentTool is the single class that runs them.
+ *
+ * Rendering is assigned to the tool instance via createUnifiedSubagentRenderer.
  */
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { Component } from "@nghyane/arcane-tui";
 import { Snowflake } from "@nghyane/arcane-utils";
 import type { TObject, TProperties } from "@sinclair/typebox";
 import type { ToolSession } from "..";
 import { isDefaultModelAlias } from "../config/model-resolver";
-import { renderPromptTemplate } from "../config/prompt-templates";
-import type { Theme } from "../modes/theme/theme";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { getBundledAgent } from "../task/agents";
 import { runAgent } from "../task/executor";
 import { AgentOutputManager } from "../task/output-manager";
-import type { AgentProgress, TaskToolDetails } from "../task/types";
-
-export interface SubagentToolConfig<T extends TProperties> {
+import { extractAgentOutput, ProgressTracker } from "../task/progress-tracker";
+import { createUnifiedSubagentRenderer } from "../task/render";
+import type { TaskToolDetails } from "../task/types";
+import { TASK_SUBAGENT_EVENT_CHANNEL } from "../task/types";
+import type { Theme } from "../theme/theme";
+import { EventBus } from "../utils/event-bus";
+
+export interface SubagentConfig<T extends TProperties = TProperties> {
 	/** Tool name exposed to the model */
 	name: string;
 	/** Display label in TUI */
@@ -28,142 +36,208 @@ export interface SubagentToolConfig<T extends TProperties> {
 	agent: string;
 	/** TypeBox schema for parameters */
 	schema: TObject<T>;
-	/** Raw .md template for tool description */
-	descriptionTemplate: string;
 	/** Progress message shown during execution */
 	progressText: string;
 	/** Temp directory prefix */
 	tmpPrefix: string;
 	/** Build the task string from parsed params */
 	buildTask: (params: Record<string, unknown>) => string;
-	/** Build the description for runAgent (shown in TUI) */
+	/** Build the short description shown in TUI header */
 	buildDescription: (params: Record<string, unknown>) => string;
 	/** Whether to pass compact conversation context to subagent (default: true) */
 	passContext?: boolean;
+	/** One-line tool description for model context */
+	toolDescription?: string;
+	/** Build optional context line for TUI display (shown below header). Return null to hide. */
+	buildContextLine?: (params: Record<string, unknown>) => string | null;
 }
 
-export function createSubagentTool<T extends TProperties>(
-	config: SubagentToolConfig<T>,
-): new (
-	session: ToolSession,
-) => AgentTool<TObject<T>, TaskToolDetails, Theme> {
-	const {
-		name,
-		label,
-		agent: agentName,
-		schema,
-		descriptionTemplate,
-		progressText,
-		tmpPrefix,
-		buildTask,
-		buildDescription,
-		passContext = true,
-	} = config;
-
-	const description = renderPromptTemplate(descriptionTemplate);
-
-	return class SubagentTool implements AgentTool<TObject<T>, TaskToolDetails, Theme> {
-		readonly name = name;
-		readonly label = label;
-		readonly parameters = schema;
-		readonly description = description;
-
-		constructor(private readonly session: ToolSession) {}
-
-		async execute(
-			_toolCallId: string,
-			params: Record<string, unknown>,
-			signal?: AbortSignal,
-			onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
-		): Promise<AgentToolResult<TaskToolDetails>> {
-			const startTime = Date.now();
-			const agent = getBundledAgent(agentName);
-			if (!agent) {
-				return {
-					content: [{ type: "text", text: `${label} agent not found.` }],
-					details: { results: [], totalDurationMs: 0 },
-				};
-			}
-
-			const effectiveAgentModel = isDefaultModelAlias(agent.model) ? undefined : agent.model;
-			const modelOverride =
-				effectiveAgentModel ?? this.session.getActiveModelString?.() ?? this.session.getModelString?.();
-
-			const task = buildTask(params);
-			const sessionFile = this.session.getSessionFile();
-			const artifactsDir = sessionFile ? sessionFile.slice(0, -6) : null;
-			const tempArtifactsDir = artifactsDir ? null : path.join(os.tmpdir(), `${tmpPrefix}${Snowflake.next()}`);
-			const effectiveArtifactsDir = artifactsDir || tempArtifactsDir!;
-
-			try {
-				await fs.mkdir(effectiveArtifactsDir, { recursive: true });
-
-				const outputManager =
-					this.session.agentOutputManager ?? new AgentOutputManager(this.session.getArtifactsDir ?? (() => null));
-				const [id] = await outputManager.allocateBatch([label]);
+export class SubagentTool<T extends TProperties = TProperties>
+	implements AgentTool<TObject<T>, TaskToolDetails, Theme>
+{
+	readonly name: string;
+	readonly label: string;
+	readonly parameters: TObject<T>;
+	description: string;
+	declare renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
+	declare renderResult: (
+		result: { content: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean },
+		options: RenderResultOptions,
+		theme: Theme,
+		args?: unknown,
+	) => Component;
+
+	#config: SubagentConfig<T>;
+	#session: ToolSession;
+
+	constructor(session: ToolSession, config: SubagentConfig<T>) {
+		this.#config = config;
+		this.#session = session;
+		this.name = config.name;
+		this.label = config.label;
+		this.parameters = config.schema;
+		this.description = config.toolDescription ?? "";
+		const renderer = createUnifiedSubagentRenderer({
+			label: config.label,
+			getDescription: args => config.buildDescription(args),
+			getContextLine: config.buildContextLine ? args => config.buildContextLine!(args) : undefined,
+		});
+		this.renderCall = renderer.renderCall;
+		this.renderResult = renderer.renderResult;
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: Record<string, unknown>,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
+	): Promise<AgentToolResult<TaskToolDetails>> {
+		const {
+			label,
+			agent: agentName,
+			progressText,
+			tmpPrefix,
+			buildTask,
+			buildDescription,
+			passContext = true,
+		} = this.#config;
+		const session = this.#session;
+		const startTime = Date.now();
+
+		const agent = getBundledAgent(agentName);
+		if (!agent) {
+			return {
+				content: [{ type: "text", text: `${label} agent not found.` }],
+				details: { results: [], totalDurationMs: 0 },
+			};
+		}
 
-				const emitProgress = (progress: AgentProgress) => {
+		const effectiveAgentModel = isDefaultModelAlias(agent.model) ? undefined : agent.model;
+		const modelOverride = effectiveAgentModel ?? session.getActiveModelString?.() ?? session.getModelString?.();
+
+		const task = buildTask(params);
+		const sessionFile = session.getSessionFile();
+		const artifactsDir = sessionFile ? sessionFile.slice(0, -6) : null;
+		const tempArtifactsDir = artifactsDir ? null : path.join(os.tmpdir(), `${tmpPrefix}${Snowflake.next()}`);
+		const effectiveArtifactsDir = artifactsDir || tempArtifactsDir!;
+
+		try {
+			await fs.mkdir(effectiveArtifactsDir, { recursive: true });
+
+			const outputManager =
+				session.agentOutputManager ?? new AgentOutputManager(session.getArtifactsDir ?? (() => null));
+			const [id] = await outputManager.allocateBatch([label]);
+
+			// Set up EventBus — all observation flows through here
+			const eventBus = new EventBus();
+
+			// Progress tracker subscribes to events
+			const tracker = new ProgressTracker({
+				index: 0,
+				id,
+				agent: agentName,
+				task,
+				description: buildDescription(params),
+				startTime,
+				onProgress: progress => {
 					onUpdate?.({
 						content: [{ type: "text", text: progressText }],
 						details: { results: [], totalDurationMs: Date.now() - startTime, progress: [progress] },
 					});
-				};
-
-				let contextFilePath: string | undefined;
-				if (passContext) {
-					const compactContext = this.session.subagentContext?.getCompactContext?.();
-					if (compactContext) {
-						contextFilePath = path.join(effectiveArtifactsDir, "context.md");
-						await Bun.write(contextFilePath, compactContext);
-					}
+				},
+				onTerminateRequest: () => eventBus.emit("executor:terminate", {}),
+			});
+			tracker.subscribe(eventBus);
+
+			// Capture output from agent_end event
+			let agentOutput = "";
+			const outputListener = eventBus.on(TASK_SUBAGENT_EVENT_CHANNEL, (data: unknown) => {
+				const payload = data as { event?: { type: string; messages?: unknown[] } };
+				if (payload.event?.type === "agent_end") {
+					agentOutput = extractAgentOutput(payload.event as Parameters<typeof extractAgentOutput>[0]);
+				}
+			});
+
+			let contextFilePath: string | undefined;
+			if (passContext) {
+				const compactContext = session.subagentContext?.getCompactContext?.();
+				if (compactContext) {
+					contextFilePath = path.join(effectiveArtifactsDir, "context.md");
+					await Bun.write(contextFilePath, compactContext);
 				}
+			}
 
-				const result = await runAgent({
-					cwd: this.session.cwd,
-					agent,
-					task,
-					description: buildDescription(params),
-					index: 0,
-					id,
-					isSubagent: true,
-					modelOverride,
-					sessionFile,
-					persistArtifacts: !!artifactsDir,
-					artifactsDir: effectiveArtifactsDir,
-					contextFile: contextFilePath,
-					enableLsp: false,
-					signal,
-					onProgress: emitProgress,
-					authStorage: this.session.subagentContext?.authStorage,
-					modelRegistry: this.session.subagentContext?.modelRegistry,
-					settings: this.session.settings,
-					contextFiles: this.session.contextFiles,
-					skills: this.session.skills,
-					promptTemplates: this.session.promptTemplates,
-					mcpManager: this.session.subagentContext?.mcpManager,
-				});
-
-				if (tempArtifactsDir) {
-					await fs.rm(tempArtifactsDir, { recursive: true, force: true });
+			const result = await runAgent({
+				cwd: session.cwd,
+				agent,
+				task,
+				description: buildDescription(params),
+				index: 0,
+				id,
+				isSubagent: true,
+				modelOverride,
+				sessionFile,
+				persistArtifacts: !!artifactsDir,
+				artifactsDir: effectiveArtifactsDir,
+				contextFile: contextFilePath,
+				enableLsp: false,
+				signal,
+				eventBus,
+				authStorage: session.subagentContext?.authStorage,
+				modelRegistry: session.subagentContext?.modelRegistry,
+				settings: session.settings,
+				contextFiles: session.contextFiles,
+				skills: session.skills,
+				promptTemplates: session.promptTemplates,
+				mcpManager: session.subagentContext?.mcpManager,
+			});
+
+			// Finalize tracker
+			const wasAborted = result.aborted ?? false;
+			tracker.finalize(wasAborted ? "aborted" : result.exitCode === 0 ? "completed" : "failed");
+			tracker.dispose();
+			outputListener();
+
+			// Enrich result with tracker data
+			result.tokens = tracker.progress.tokens;
+			result.lastIntent = tracker.progress.lastIntent;
+			result.usage = tracker.usage;
+			result.toolHistory = tracker.progress.toolHistory.map(t => ({
+				tool: t.tool,
+				args: t.args,
+				status: t.status === "running" ? ("error" as const) : t.status,
+			}));
+
+			// Write output artifact for agent:// URL integration
+			if (artifactsDir && agentOutput) {
+				const outputFile = path.join(effectiveArtifactsDir, `${id}.md`);
+				try {
+					await Bun.write(outputFile, agentOutput);
+				} catch {
+					// Non-fatal
 				}
+			}
 
-				const totalDuration = Date.now() - startTime;
-				const output = result.output.trim() || result.stderr.trim() || "(no output)";
-
-				return {
-					content: [{ type: "text", text: output }],
-					details: {
-						results: [result],
-						totalDurationMs: totalDuration,
-						usage: result.usage,
-					},
-				};
-			} catch (err) {
-				return {
-					content: [{ type: "text", text: `${label} failed: ${err}` }],
-					details: { results: [], totalDurationMs: Date.now() - startTime },
-				};
+			if (tempArtifactsDir) {
+				await fs.rm(tempArtifactsDir, { recursive: true, force: true });
 			}
+
+			const totalDuration = Date.now() - startTime;
+			const output = agentOutput.trim() || result.stderr.trim() || `${label} produced no output`;
+
+			return {
+				content: [{ type: "text", text: output }],
+				details: {
+					results: [result],
+					totalDurationMs: totalDuration,
+					usage: result.usage,
+				},
+			};
+		} catch (err) {
+			return {
+				content: [{ type: "text", text: `${label} failed: ${err}` }],
+				details: { results: [], totalDurationMs: Date.now() - startTime },
+			};
 		}
-	};
+	}
 }

package/src/tools/todo-write.ts

@@ -6,22 +6,19 @@ import { Text } from "@nghyane/arcane-tui";
 import { logger, Snowflake } from "@nghyane/arcane-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import chalk from "chalk";
-import { renderPromptTemplate } from "../config/prompt-templates";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
-import type { Theme } from "../modes/theme/theme";
-import todoWriteDescription from "../prompts/tools/todo-write.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
+import type { Theme } from "../theme/theme";
 import { renderStatusLine, renderTreeList } from "../tui";
-import { PREVIEW_LIMITS } from "./render-utils";
+import { PREVIEW_LIMITS } from "../ui/render-utils";
 
 const todoWriteSchema = Type.Object({
 	todos: Type.Array(
 		Type.Object({
-			id: Type.Optional(Type.String({ description: "Stable todo id" })),
-			content: Type.String({ description: "Task description (e.g., 'Run tests')" }),
-			status: StringEnum(["pending", "in_progress", "completed"]),
+			id: Type.Optional(Type.String({ description: "Existing todo ID to update (omit for new)" })),
+			content: Type.String({ description: "Todo description" }),
+			status: StringEnum(["pending", "in_progress", "completed"], { description: "Todo status" }),
 		}),
-		{ description: "The updated todo list" },
 	),
 });
 
@@ -79,10 +76,8 @@ function normalizeTodos(items: Array<{ id?: string; content?: string; status?: s
 }
 
 async function loadTodoFile(filePath: string): Promise<TodoFile | null> {
-	const file = Bun.file(filePath);
-	if (!(await file.exists())) return null;
 	try {
-		const text = await file.text();
+		const text = await Bun.file(filePath).text();
 		const data = JSON.parse(text) as TodoFile;
 		if (!data || !Array.isArray(data.todos)) return null;
 		return data;
@@ -114,18 +109,18 @@ function formatTodoLine(item: TodoItem, uiTheme: Theme, prefix: string): string
 
 // =============================================================================
 // Tool Class
-// =============================================================================
+interface TodoWriteRenderArgs {
+	todos?: Array<{ id?: string; content?: string; status?: string }>;
+}
 
-export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWriteToolDetails> {
+export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWriteToolDetails, Theme> {
 	readonly name = "todo_write";
 	readonly label = "Todo Write";
-	readonly description: string;
+	description = "Update the task/todo list";
 	readonly parameters = todoWriteSchema;
 	readonly concurrency = "exclusive";
 
-	constructor(private readonly session: ToolSession) {
-		this.description = renderPromptTemplate(todoWriteDescription);
-	}
+	constructor(private readonly session: ToolSession) {}
 
 	async execute(
 		_toolCallId: string,
@@ -166,23 +161,13 @@ export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWrit
 			details: { todos: merged, updatedAt, storage: "session" },
 		};
 	}
-}
-
-// =============================================================================
-// TUI Renderer
-// =============================================================================
-
-interface TodoWriteRenderArgs {
-	todos?: Array<{ id?: string; content?: string; status?: string }>;
-}
 
-export const todoWriteToolRenderer = {
 	renderCall(args: TodoWriteRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const count = args.todos?.length ?? 0;
 		const meta = count > 0 ? [`${count} items`] : ["empty"];
 		const text = renderStatusLine({ icon: "pending", title: "Todo Write", meta }, uiTheme);
 		return new Text(text, 0, 0);
-	},
+	}
 
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: TodoWriteToolDetails },
@@ -213,6 +198,5 @@ export const todoWriteToolRenderer = {
 		);
 		const text = [header, ...treeLines].join("\n");
 		return new Text(text, 0, 0);
-	},
-	mergeCallAndResult: true,
-};
+	}
+}

package/src/tools/tool-errors.ts

@@ -24,36 +24,6 @@ export class ToolError extends Error {
 	}
 }
 
-/**
- * Error entry for MultiError.
- */
-export interface ErrorEntry {
-	message: string;
-	context?: string;
-}
-
-/**
- * Error with multiple entries (e.g., multiple validation failures, batch errors).
- */
-export class MultiError extends ToolError {
-	constructor(readonly errors: ErrorEntry[]) {
-		super(errors.map(e => e.message).join("; "));
-		this.name = "MultiError";
-	}
-
-	render(): string {
-		if (this.errors.length === 1) {
-			const e = this.errors[0];
-			return e.context ? `${e.context}: ${e.message}` : e.message;
-		}
-		return this.errors.map(e => (e.context ? `${e.context}: ${e.message}` : e.message)).join("\n");
-	}
-
-	static from(errors: Array<string | ErrorEntry>): MultiError {
-		return new MultiError(errors.map(e => (typeof e === "string" ? { message: e } : e)));
-	}
-}
-
 /**
  * Error thrown when a tool operation is aborted (e.g., via AbortSignal).
  */

package/src/tools/undo-edit.ts

@@ -6,39 +6,39 @@ import type { Component } from "@nghyane/arcane-tui";
 import { Text } from "@nghyane/arcane-tui";
 import { isEnoent, untilAborted } from "@nghyane/arcane-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { renderPromptTemplate } from "../config/prompt-templates";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
-import type { Theme } from "../modes/theme/theme";
 import { generateUnifiedDiffString } from "../patch/diff";
 import { normalizeToLF, stripBom } from "../patch/normalize";
-import undoEditDescription from "../prompts/tools/undo-edit.md" with { type: "text" };
-import { Ellipsis, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
+import type { Theme } from "../theme/theme";
+import { renderStatusLine } from "../tui";
+import { formatErrorMessage, getDiffStats, shortenPath } from "../ui/render-utils";
 import type { ToolSession } from ".";
 import { invalidateFsScanAfterWrite } from "./fs-cache-invalidation";
 import { resolveToCwd } from "./path-utils";
-import { getDiffStats, replaceTabs, shortenPath, ToolUIKit } from "./render-utils";
 import { ToolError } from "./tool-errors";
 import { popUndo } from "./undo-history";
 
 const undoEditSchema = Type.Object({
-	path: Type.String({ description: "Path to the file whose last edit should be undone (relative or absolute)" }),
+	path: Type.String({ description: "File path to revert" }),
 });
 
 export interface UndoEditToolDetails {
 	diff: string;
 }
 
-export class UndoEditTool implements AgentTool<typeof undoEditSchema, UndoEditToolDetails> {
+interface UndoEditRenderArgs {
+	path?: string;
+}
+
+export class UndoEditTool implements AgentTool<typeof undoEditSchema, UndoEditToolDetails, Theme> {
 	readonly name = "undo_edit";
 	readonly label = "Undo";
-	readonly description: string;
+	description = "Undo the last edit to a file";
 	readonly parameters = undoEditSchema;
 	readonly nonAbortable = true;
 	readonly concurrency = "exclusive";
 
-	constructor(private readonly session: ToolSession) {
-		this.description = renderPromptTemplate(undoEditDescription);
-	}
+	constructor(private readonly session: ToolSession) {}
 
 	async execute(
 		_toolCallId: string,
@@ -74,72 +74,35 @@ export class UndoEditTool implements AgentTool<typeof undoEditSchema, UndoEditTo
 			};
 		});
 	}
-}
-
-// =============================================================================
-// TUI Renderer
-// =============================================================================
-
-interface UndoEditRenderArgs {
-	path?: string;
-}
-
-export const undoEditToolRenderer = {
-	mergeCallAndResult: true,
 
 	renderCall(args: UndoEditRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const filePath = shortenPath(args.path ?? "");
 		const pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
 		const text = renderStatusLine({ icon: "pending", title: "Undo", description: pathDisplay }, uiTheme);
 		return new Text(text, 0, 0);
-	},
+	}
 
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: UndoEditToolDetails; isError?: boolean },
-		options: RenderResultOptions,
+		_options: RenderResultOptions,
 		uiTheme: Theme,
 		args?: UndoEditRenderArgs,
 	): Component {
-		const ui = new ToolUIKit(uiTheme);
 		const filePath = shortenPath(args?.path ?? "");
-		const pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
-		const errorText = result.isError ? (result.content?.find(c => c.type === "text")?.text ?? "") : "";
-
-		let cached: RenderCache | undefined;
-
-		return {
-			render(width) {
-				const { expanded } = options;
-				const key = new Hasher().bool(expanded).u32(width).digest();
-				if (cached?.key === key) return cached.lines;
-
-				const header = renderStatusLine(
-					{ icon: result.isError ? "error" : "success", title: "Undo", description: pathDisplay },
-					uiTheme,
-				);
-				let text = header;
-
-				if (result.isError) {
-					if (errorText) {
-						text += `\n\n${uiTheme.fg("error", replaceTabs(errorText))}`;
-					}
-				} else if (result.details?.diff) {
-					const diffStats = getDiffStats(result.details.diff);
-					text += `\n${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${ui.formatDiffStats(
-						diffStats.added,
-						diffStats.removed,
-						diffStats.hunks,
-					)}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
-				}
-
-				const lines =
-					width > 0 ? text.split("\n").map(line => truncateToWidth(line, width, Ellipsis.Omit)) : text.split("\n");
-				cached = { key, lines };
-				return lines;
-			},
-			invalidate() {
-				cached = undefined;
-			},
-		};
-	},
-};
+		if (result.isError) {
+			const errorText = result.content?.find(c => c.type === "text")?.text || "Unknown error";
+			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+		}
+		const meta: string[] = ["reverted"];
+		if (result.details?.diff) {
+			const diffStats = getDiffStats(result.details.diff);
+			if (diffStats.added > 0) meta.push(`+${diffStats.added}`);
+			if (diffStats.removed > 0) meta.push(`-${diffStats.removed}`);
+		}
+		return new Text(
+			renderStatusLine({ icon: "success", title: "Undo", description: filePath || "file", meta }, uiTheme),
+			0,
+			0,
+		);
+	}
+}