@nghyane/arcane 0.1.0

package/src/tools/renderers.ts

@@ -0,0 +1,60 @@
+/**
+ * TUI renderers for built-in tools.
+ *
+ * These provide rich visualization for tool calls and results in the TUI.
+ */
+import type { Component } from "@nghyane/arcane-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import { lspToolRenderer } from "../lsp/render";
+import type { Theme } from "../modes/theme/theme";
+import { editToolRenderer } from "../patch";
+import { taskToolRenderer } from "../task/render";
+import { webSearchToolRenderer } from "../web/search/render";
+import { askToolRenderer } from "./ask";
+import { bashToolRenderer } from "./bash";
+import { calculatorToolRenderer } from "./calculator";
+import { fetchToolRenderer } from "./fetch";
+import { findToolRenderer } from "./find";
+import { grepToolRenderer } from "./grep";
+import { notebookToolRenderer } from "./notebook";
+import { pythonToolRenderer } from "./python";
+import { readToolRenderer } from "./read";
+import { sshToolRenderer } from "./ssh";
+import { todoWriteToolRenderer } from "./todo-write";
+import { undoEditToolRenderer } from "./undo-edit";
+import { writeToolRenderer } from "./write";
+
+type ToolRenderer = {
+	renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
+	renderResult: (
+		result: { content: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean },
+		options: RenderResultOptions & { renderContext?: Record<string, unknown> },
+		theme: Theme,
+		args?: unknown,
+	) => Component;
+	mergeCallAndResult?: boolean;
+	/** Render without background box, inline in the response flow */
+	inline?: boolean;
+};
+
+export const toolRenderers: Record<string, ToolRenderer> = {
+	ask: askToolRenderer as ToolRenderer,
+	bash: bashToolRenderer as ToolRenderer,
+	python: pythonToolRenderer as ToolRenderer,
+	calc: calculatorToolRenderer as ToolRenderer,
+	edit: editToolRenderer as ToolRenderer,
+	find: findToolRenderer as ToolRenderer,
+	grep: grepToolRenderer as ToolRenderer,
+	lsp: lspToolRenderer as ToolRenderer,
+	notebook: notebookToolRenderer as ToolRenderer,
+	read: readToolRenderer as ToolRenderer,
+	ssh: sshToolRenderer as ToolRenderer,
+	task: taskToolRenderer as ToolRenderer,
+	explore: taskToolRenderer as ToolRenderer,
+	review: taskToolRenderer as ToolRenderer,
+	todo_write: todoWriteToolRenderer as ToolRenderer,
+	undo_edit: undoEditToolRenderer as ToolRenderer,
+	fetch: fetchToolRenderer as ToolRenderer,
+	web_search: webSearchToolRenderer as ToolRenderer,
+	write: writeToolRenderer as ToolRenderer,
+};

package/src/tools/reviewer-tool.ts

@@ -0,0 +1,41 @@
+import { Type } from "@sinclair/typebox";
+import reviewerDescription from "../prompts/tools/reviewer.md" with { type: "text" };
+import { createSubagentTool } from "./subagent-tool";
+
+const schema = Type.Object({
+	diff_description: Type.String({
+		description:
+			'A description or command identifying the diff to review. Examples: "uncommitted changes", "last commit", "PR #42", "changes against main branch".',
+	}),
+	files: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Specific file paths to focus the review on. If omitted, all changed files are reviewed.",
+		}),
+	),
+	instructions: Type.Optional(
+		Type.String({
+			description:
+				'Additional guidance for the reviewer. Examples: "Focus on error handling", "Check for race conditions".',
+		}),
+	),
+});
+
+function buildTask(p: Record<string, unknown>): string {
+	const parts: string[] = [`Review: ${p.diff_description}`];
+	const files = p.files as string[] | undefined;
+	if (files?.length) parts.push(`\nFocus on files:\n${files.map(f => `- ${f}`).join("\n")}`);
+	if (p.instructions) parts.push(`\nAdditional instructions: ${p.instructions}`);
+	return parts.join("\n");
+}
+
+export const ReviewerTool = createSubagentTool({
+	name: "code_review",
+	label: "Code Review",
+	agent: "reviewer",
+	schema,
+	descriptionTemplate: reviewerDescription,
+	progressText: "Reviewing code...",
+	tmpPrefix: "arc-review-",
+	buildTask,
+	buildDescription: p => `Review: ${(p.diff_description as string).slice(0, 60)}`,
+});

package/src/tools/ssh.ts

@@ -0,0 +1,326 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
+import { type Static, Type } from "@sinclair/typebox";
+import type { SSHHost } from "../capability/ssh";
+import { sshCapability } from "../capability/ssh";
+import { renderPromptTemplate } from "../config/prompt-templates";
+import { loadCapability } from "../discovery";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import sshDescriptionBase from "../prompts/tools/ssh.md" with { type: "text" };
+import { DEFAULT_MAX_BYTES } from "../session/streaming-output";
+import type { SSHHostInfo } from "../ssh/connection-manager";
+import { ensureHostInfo, getHostInfoForHost } from "../ssh/connection-manager";
+import { executeSSH } from "../ssh/ssh-executor";
+import { renderStatusLine } from "../tui";
+import { CachedOutputBlock } from "../tui/output-block";
+import type { ToolSession } from ".";
+import type { OutputMeta } from "./output-meta";
+import { allocateOutputArtifact, createTailBuffer } from "./output-utils";
+import { formatBytes, wrapBrackets } from "./render-utils";
+import { ToolError } from "./tool-errors";
+import { toolResult } from "./tool-result";
+
+const sshSchema = Type.Object({
+	host: Type.String({ description: "Host name from managed SSH config or discovered ssh.json files" }),
+	command: Type.String({ description: "Command to execute on the remote host" }),
+	cwd: Type.Optional(Type.String({ description: "Remote working directory (optional)" })),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 60)" })),
+});
+
+export interface SSHToolDetails {
+	meta?: OutputMeta;
+}
+
+async function formatHostEntry(host: SSHHost): Promise<string> {
+	const info = await getHostInfoForHost(host);
+
+	let shell: string;
+	if (!info) {
+		shell = "detecting...";
+	} else if (info.os === "windows") {
+		if (info.compatEnabled) {
+			const compatShell = info.compatShell || "bash";
+			shell = `windows/${compatShell}`;
+		} else if (info.shell === "powershell") {
+			shell = "windows/powershell";
+		} else {
+			shell = "windows/cmd";
+		}
+	} else if (info.os === "linux") {
+		shell = `linux/${info.shell}`;
+	} else if (info.os === "macos") {
+		shell = `macos/${info.shell}`;
+	} else {
+		shell = `unknown/${info.shell}`;
+	}
+
+	return `- ${host.name} (${host.host}) | ${shell}`;
+}
+
+async function formatDescription(hosts: SSHHost[]): Promise<string> {
+	const baseDescription = renderPromptTemplate(sshDescriptionBase);
+	if (hosts.length === 0) {
+		return baseDescription;
+	}
+	const hostList = (await Promise.all(hosts.map(formatHostEntry))).join("\n");
+	return `${baseDescription}\n\nAvailable hosts:\n${hostList}`;
+}
+
+function quoteRemotePath(value: string): string {
+	if (value.length === 0) {
+		return "''";
+	}
+	const escaped = value.replace(/'/g, "'\\''");
+	return `'${escaped}'`;
+}
+
+function quotePowerShellPath(value: string): string {
+	if (value.length === 0) {
+		return "''";
+	}
+	const escaped = value.replace(/'/g, "''");
+	return `'${escaped}'`;
+}
+
+function quoteCmdPath(value: string): string {
+	const escaped = value.replace(/"/g, '""');
+	return `"${escaped}"`;
+}
+
+function buildRemoteCommand(command: string, cwd: string | undefined, info: SSHHostInfo): string {
+	if (!cwd) return command;
+
+	if (info.os === "windows" && !info.compatEnabled) {
+		if (info.shell === "powershell") {
+			return `Set-Location -Path ${quotePowerShellPath(cwd)}; ${command}`;
+		}
+		return `cd /d ${quoteCmdPath(cwd)} && ${command}`;
+	}
+
+	return `cd -- ${quoteRemotePath(cwd)} && ${command}`;
+}
+
+async function loadHosts(session: ToolSession): Promise<{
+	hostNames: string[];
+	hostsByName: Map<string, SSHHost>;
+}> {
+	const result = await loadCapability<SSHHost>(sshCapability.id, { cwd: session.cwd });
+	const hostsByName = new Map<string, SSHHost>();
+	for (const host of result.items) {
+		if (!hostsByName.has(host.name)) {
+			hostsByName.set(host.name, host);
+		}
+	}
+	const hostNames = Array.from(hostsByName.keys()).sort();
+	return { hostNames, hostsByName };
+}
+
+type SshToolParams = Static<typeof sshSchema>;
+
+export class SshTool implements AgentTool<typeof sshSchema, SSHToolDetails> {
+	readonly name = "ssh";
+	readonly label = "SSH";
+	readonly parameters = sshSchema;
+	readonly concurrency = "exclusive";
+
+	readonly #allowedHosts: Set<string>;
+
+	constructor(
+		private readonly session: ToolSession,
+		private readonly hostNames: string[],
+		private readonly hostsByName: Map<string, SSHHost>,
+		readonly description: string,
+	) {
+		this.#allowedHosts = new Set(this.hostNames);
+	}
+
+	async execute(
+		_toolCallId: string,
+		{ host, command, cwd, timeout: rawTimeout = 60 }: SshToolParams,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<SSHToolDetails>,
+		_ctx?: AgentToolContext,
+	): Promise<AgentToolResult<SSHToolDetails>> {
+		if (!this.#allowedHosts.has(host)) {
+			throw new ToolError(`Unknown SSH host: ${host}. Available hosts: ${this.hostNames.join(", ")}`);
+		}
+
+		const hostConfig = this.hostsByName.get(host);
+		if (!hostConfig) {
+			throw new ToolError(`SSH host not loaded: ${host}`);
+		}
+
+		const hostInfo = await ensureHostInfo(hostConfig);
+		const remoteCommand = buildRemoteCommand(command, cwd, hostInfo);
+
+		// Clamp to reasonable range: 1s - 3600s (1 hour)
+		const timeoutSec = Math.max(1, Math.min(3600, rawTimeout));
+		const timeoutMs = timeoutSec * 1000;
+
+		const tailBuffer = createTailBuffer(DEFAULT_MAX_BYTES);
+		const { artifactPath, artifactId } = await allocateOutputArtifact(this.session, "ssh");
+
+		const result = await executeSSH(hostConfig, remoteCommand, {
+			timeout: timeoutMs,
+			signal,
+			compatEnabled: hostInfo.compatEnabled,
+			artifactPath,
+			artifactId,
+			onChunk: chunk => {
+				tailBuffer.append(chunk);
+				if (onUpdate) {
+					onUpdate({
+						content: [{ type: "text", text: tailBuffer.text() }],
+						details: {},
+					});
+				}
+			},
+		});
+
+		if (result.cancelled) {
+			throw new ToolError(result.output || "Command aborted");
+		}
+
+		const outputText = result.output || "(no output)";
+		const details: SSHToolDetails = {};
+		const resultBuilder = toolResult(details).text(outputText).truncationFromSummary(result, { direction: "tail" });
+
+		if (result.exitCode !== 0 && result.exitCode !== undefined) {
+			throw new ToolError(`${outputText}\n\nCommand exited with code ${result.exitCode}`);
+		}
+
+		return resultBuilder.done();
+	}
+}
+
+export async function loadSshTool(session: ToolSession): Promise<SshTool | null> {
+	const { hostNames, hostsByName } = await loadHosts(session);
+	if (hostNames.length === 0) {
+		return null;
+	}
+
+	const descriptionHosts = hostNames
+		.map(name => hostsByName.get(name))
+		.filter((host): host is SSHHost => host !== undefined);
+	const description = await formatDescription(descriptionHosts);
+
+	return new SshTool(session, hostNames, hostsByName, description);
+}
+
+// =============================================================================
+// TUI Renderer
+// =============================================================================
+
+interface SshRenderArgs {
+	host?: string;
+	command?: string;
+	timeout?: number;
+}
+
+interface SshRenderContext {
+	/** Visual lines for truncated output (pre-computed by tool-execution) */
+	visualLines?: string[];
+	/** Number of lines skipped */
+	skippedCount?: number;
+	/** Total visual lines */
+	totalVisualLines?: number;
+}
+
+export const sshToolRenderer = {
+	renderCall(args: SshRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+		const host = args.host || "…";
+		const command = args.command || "…";
+		const text = renderStatusLine({ icon: "pending", title: "SSH", description: `[${host}] $ ${command}` }, uiTheme);
+		return new Text(text, 0, 0);
+	},
+
+	renderResult(
+		result: {
+			content: Array<{ type: string; text?: string }>;
+			details?: SSHToolDetails;
+		},
+		options: RenderResultOptions & { renderContext?: SshRenderContext },
+		uiTheme: Theme,
+		args?: SshRenderArgs,
+	): Component {
+		const details = result.details;
+		const host = args?.host || "…";
+		const command = args?.command || "…";
+		const header = renderStatusLine(
+			{ icon: "success", title: "SSH", description: `[${host}] $ ${command}` },
+			uiTheme,
+		);
+		const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
+		const truncation = details?.meta?.truncation;
+		const outputBlock = new CachedOutputBlock();
+
+		return {
+			render: (width: number): string[] => {
+				// REACTIVE: read mutable options at render time
+				const { expanded, renderContext } = options;
+				const output = textContent.trimEnd();
+				const outputLines: string[] = [];
+
+				if (output) {
+					if (expanded) {
+						outputLines.push(...output.split("\n").map(line => uiTheme.fg("toolOutput", line)));
+					} else if (renderContext?.visualLines) {
+						const { visualLines, skippedCount = 0, totalVisualLines = visualLines.length } = renderContext;
+						if (skippedCount > 0) {
+							outputLines.push(
+								uiTheme.fg(
+									"dim",
+									`… (${skippedCount} earlier lines, showing ${visualLines.length} of ${totalVisualLines}) (ctrl+o to expand)`,
+								),
+							);
+						}
+						const styledVisual = visualLines.map(line =>
+							line.includes("\x1b[") ? line : uiTheme.fg("toolOutput", line),
+						);
+						outputLines.push(...styledVisual);
+					} else {
+						const outputLinesRaw = output.split("\n");
+						const maxLines = 5;
+						const displayLines = outputLinesRaw.slice(0, maxLines);
+						const remaining = outputLinesRaw.length - maxLines;
+						outputLines.push(...displayLines.map(line => uiTheme.fg("toolOutput", line)));
+						if (remaining > 0) {
+							outputLines.push(uiTheme.fg("dim", `… (${remaining} more lines) (ctrl+o to expand)`));
+						}
+					}
+				}
+
+				if (truncation) {
+					const warnings: string[] = [];
+					if (truncation.artifactId) {
+						warnings.push(`Full output: artifact://${truncation.artifactId}`);
+					}
+					if (truncation.truncatedBy === "lines") {
+						warnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);
+					} else {
+						warnings.push(
+							`Truncated: ${truncation.outputLines} lines shown (${formatBytes(truncation.outputBytes)} limit)`,
+						);
+					}
+					outputLines.push(uiTheme.fg("warning", wrapBrackets(warnings.join(". "), uiTheme)));
+				}
+
+				return outputBlock.render(
+					{
+						header,
+						state: "success",
+						sections: [{ label: uiTheme.fg("toolTitle", "Output"), lines: outputLines }],
+						width,
+					},
+					uiTheme,
+				);
+			},
+			invalidate: () => {
+				outputBlock.invalidate();
+			},
+		};
+	},
+	mergeCallAndResult: true,
+};

package/src/tools/subagent-tool.ts

@@ -0,0 +1,169 @@
+/**
+ * Generic subagent tool factory.
+ *
+ * All standalone subagent tools (explore, oracle, librarian, code_review)
+ * share identical execution logic. This factory eliminates the boilerplate.
+ */
+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 { 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 { 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> {
+	/** Tool name exposed to the model */
+	name: string;
+	/** Display label in TUI */
+	label: string;
+	/** Bundled agent name to invoke */
+	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) */
+	buildDescription: (params: Record<string, unknown>) => string;
+	/** Whether to pass compact conversation context to subagent (default: true) */
+	passContext?: boolean;
+}
+
+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]);
+
+				const emitProgress = (progress: AgentProgress) => {
+					onUpdate?.({
+						content: [{ type: "text", text: progressText }],
+						details: { results: [], totalDurationMs: Date.now() - startTime, progress: [progress] },
+					});
+				};
+
+				let contextFilePath: string | undefined;
+				if (passContext) {
+					const compactContext = this.session.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,
+					taskDepth: this.session.taskDepth ?? 0,
+					modelOverride,
+					sessionFile,
+					persistArtifacts: !!artifactsDir,
+					artifactsDir: effectiveArtifactsDir,
+					contextFile: contextFilePath,
+					enableLsp: false,
+					signal,
+					onProgress: emitProgress,
+					authStorage: this.session.authStorage,
+					modelRegistry: this.session.modelRegistry,
+					settings: this.session.settings,
+					contextFiles: this.session.contextFiles,
+					skills: this.session.skills,
+					promptTemplates: this.session.promptTemplates,
+					mcpManager: this.session.mcpManager,
+				});
+
+				if (tempArtifactsDir) {
+					await fs.rm(tempArtifactsDir, { recursive: true, force: true });
+				}
+
+				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 },
+				};
+			}
+		}
+	};
+}