@nghyane/arcane 0.1.0

package/src/tools/index.ts

@@ -0,0 +1,337 @@
+import type { AgentTool } from "@nghyane/arcane-agent";
+import { createCodeTool } from "@nghyane/arcane-codemode";
+import { $env, logger } from "@nghyane/arcane-utils";
+import type { PromptTemplate } from "../config/prompt-templates";
+import type { Settings } from "../config/settings";
+import type { Skill } from "../extensibility/skills";
+import type { InternalUrlRouter } from "../internal-urls";
+import { getPreludeDocs, warmPythonEnvironment } from "../ipy/executor";
+import { checkPythonKernelAvailability } from "../ipy/kernel";
+import { LspTool } from "../lsp";
+import { EditTool } from "../patch";
+import type { ArtifactManager } from "../session/artifacts";
+import { TaskTool } from "../task";
+import type { AgentOutputManager } from "../task/output-manager";
+import type { EventBus } from "../utils/event-bus";
+import { time } from "../utils/timings";
+import { SearchTool } from "../web/search";
+import { AskTool } from "./ask";
+import { BashTool } from "./bash";
+import { BrowserTool } from "./browser";
+import { CalculatorTool } from "./calculator";
+import { ExploreTool } from "./explore";
+import { FetchTool } from "./fetch";
+import { FindTool } from "./find";
+import { GrepTool } from "./grep";
+import { LibrarianTool } from "./librarian";
+import { NotebookTool } from "./notebook";
+import { OracleTool } from "./oracle";
+import { wrapToolWithMetaNotice } from "./output-meta";
+import { PythonTool } from "./python";
+import { ReadTool } from "./read";
+import { ReviewerTool } from "./reviewer-tool";
+import { loadSshTool } from "./ssh";
+import { SubmitResultTool } from "./submit-result";
+import { TodoWriteTool } from "./todo-write";
+import { UndoEditTool } from "./undo-edit";
+import { WriteTool } from "./write";
+
+// Exa MCP tools (22 tools)
+
+export { exaTools } from "../exa";
+export type { ExaRenderDetails, ExaSearchResponse, ExaSearchResult } from "../exa/types";
+export {
+	type FileDiagnosticsResult,
+	type FileFormatResult,
+	getLspStatus,
+	type LspServerStatus,
+	LspTool,
+	type LspToolDetails,
+	type LspWarmupOptions,
+	type LspWarmupResult,
+	warmupLspServers,
+} from "../lsp";
+export { EditTool, type EditToolDetails } from "../patch";
+export {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatBytes,
+	type TruncationOptions,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+	truncateTail,
+} from "../session/streaming-output";
+export { BUNDLED_AGENTS, TaskTool } from "../task";
+export {
+	companySearchTools,
+	exaSearchTools,
+	getSearchTools,
+	type SearchProvider,
+	type SearchResponse,
+	SearchTool,
+	type SearchToolsOptions,
+	setPreferredSearchProvider,
+	webSearchCodeContextTool,
+	webSearchCompanyTool,
+	webSearchCrawlTool,
+	webSearchCustomTool,
+	webSearchDeepTool,
+	webSearchLinkedinTool,
+} from "../web/search";
+export { AskTool, type AskToolDetails } from "./ask";
+export { BashTool, type BashToolDetails, type BashToolInput, type BashToolOptions } from "./bash";
+export { BrowserTool, type BrowserToolDetails } from "./browser";
+export { CalculatorTool, type CalculatorToolDetails } from "./calculator";
+export { ExploreTool } from "./explore";
+export { FetchTool, type FetchToolDetails } from "./fetch";
+export { type FindOperations, FindTool, type FindToolDetails, type FindToolInput, type FindToolOptions } from "./find";
+export { setPreferredImageProvider } from "./gemini-image";
+export { GrepTool, type GrepToolDetails, type GrepToolInput } from "./grep";
+export { LibrarianTool } from "./librarian";
+export { NotebookTool, type NotebookToolDetails } from "./notebook";
+export { OracleTool } from "./oracle";
+export { PythonTool, type PythonToolDetails, type PythonToolOptions } from "./python";
+export { ReadTool, type ReadToolDetails, type ReadToolInput } from "./read";
+export { loadSshTool, type SSHToolDetails, SshTool } from "./ssh";
+export { SubmitResultTool } from "./submit-result";
+export { type TodoItem, TodoWriteTool, type TodoWriteToolDetails } from "./todo-write";
+export { UndoEditTool, type UndoEditToolDetails } from "./undo-edit";
+export { WriteTool, type WriteToolDetails, type WriteToolInput } from "./write";
+
+/** Tool type (AgentTool from pi-ai) */
+export type Tool = AgentTool<any, any, any>;
+
+export type ContextFileEntry = {
+	path: string;
+	content: string;
+	depth?: number;
+};
+
+/** Session context for tool factories */
+export interface ToolSession {
+	/** Current working directory */
+	cwd: string;
+	/** Whether UI is available */
+	hasUI: boolean;
+	/** Skip Python kernel availability check and warmup */
+	skipPythonPreflight?: boolean;
+	/** Pre-loaded context files (AGENTS.md, etc) */
+	contextFiles?: ContextFileEntry[];
+	/** Pre-loaded skills */
+	skills?: Skill[];
+	/** Pre-loaded prompt templates */
+	promptTemplates?: PromptTemplate[];
+	/** Whether LSP integrations are enabled */
+	enableLsp?: boolean;
+	/** Whether the edit tool is available in this session (controls hashline output) */
+	hasEditTool?: boolean;
+	/** Event bus for tool/extension communication */
+	eventBus?: EventBus;
+	/** Output schema for structured completion (subagents) */
+	outputSchema?: unknown;
+	/** Whether to include the submit_result tool by default */
+	requireSubmitResultTool?: boolean;
+	/** Task recursion depth (0 = top-level, 1 = first child, etc.) */
+	taskDepth?: number;
+	/** Get session file */
+	getSessionFile: () => string | null;
+	/** Get session ID */
+	getSessionId?: () => string | null;
+	/** Cached artifact manager (allocated per ToolSession) */
+	artifactManager?: ArtifactManager;
+	/** Get artifacts directory for artifact:// URLs and $ARTIFACTS env var */
+	getArtifactsDir?: () => string | null;
+	/** Get session spawns */
+	getSessionSpawns: () => string | null;
+	/** Get resolved model string if explicitly set for this session */
+	getModelString?: () => string | undefined;
+	/** Get the current session model string, regardless of how it was chosen */
+	getActiveModelString?: () => string | undefined;
+	/** Auth storage for passing to subagents (avoids re-discovery) */
+	authStorage?: import("../session/auth-storage").AuthStorage;
+	/** Model registry for passing to subagents (avoids re-discovery) */
+	modelRegistry?: import("../config/model-registry").ModelRegistry;
+	/** MCP manager for proxying MCP calls through parent */
+	mcpManager?: import("../mcp/manager").MCPManager;
+	/** Internal URL router for agent:// and skill:// URLs */
+	internalRouter?: InternalUrlRouter;
+	/** Agent output manager for unique agent:// IDs across task invocations */
+	agentOutputManager?: AgentOutputManager;
+	/** Settings instance for passing to subagents */
+	settings: Settings;
+	/** Get compact conversation context for subagents (excludes tool results, system prompts) */
+	getCompactContext?: () => string;
+}
+
+type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
+
+export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
+	ask: AskTool.createIf,
+	bash: s => new BashTool(s),
+	python: s => new PythonTool(s),
+	calc: s => new CalculatorTool(s),
+	ssh: loadSshTool,
+	edit: s => new EditTool(s),
+	find: s => new FindTool(s),
+	explore: s => new ExploreTool(s),
+	grep: s => new GrepTool(s),
+	librarian: s => new LibrarianTool(s),
+	lsp: LspTool.createIf,
+	notebook: s => new NotebookTool(s),
+	oracle: s => new OracleTool(s),
+	read: s => new ReadTool(s),
+	browser: s => new BrowserTool(s),
+	task: TaskTool.create,
+	code_review: s => new ReviewerTool(s),
+	todo_write: s => new TodoWriteTool(s),
+	undo_edit: s => new UndoEditTool(s),
+	fetch: s => new FetchTool(s),
+	web_search: s => new SearchTool(s),
+	write: s => new WriteTool(s),
+};
+
+export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
+	submit_result: s => new SubmitResultTool(s),
+};
+
+export type ToolName = keyof typeof BUILTIN_TOOLS;
+
+export type PythonToolMode = "ipy-only" | "bash-only" | "both";
+
+/**
+ * Parse ARCANE_PY environment variable to determine Python tool mode.
+ * Returns null if not set or invalid.
+ *
+ * Values:
+ * - "0" or "bash" → bash-only
+ * - "1" or "py" → ipy-only
+ * - "mix" or "both" → both
+ */
+function getPythonModeFromEnv(): PythonToolMode | null {
+	const value = $env.ARCANE_PY?.toLowerCase();
+	if (!value) return null;
+
+	switch (value) {
+		case "0":
+		case "bash":
+			return "bash-only";
+		case "1":
+		case "py":
+			return "ipy-only";
+		case "mix":
+		case "both":
+			return "both";
+		default:
+			return null;
+	}
+}
+
+/**
+ * Create tools from BUILTIN_TOOLS registry.
+ */
+export async function createTools(session: ToolSession, toolNames?: string[]): Promise<Tool[]> {
+	time("createTools:start");
+	const includeSubmitResult = session.requireSubmitResultTool === true;
+	const enableLsp = session.enableLsp ?? true;
+	const requestedTools = toolNames && toolNames.length > 0 ? [...new Set(toolNames)] : undefined;
+	const pythonMode = getPythonModeFromEnv() ?? session.settings.get("python.toolMode");
+	const skipPythonPreflight = session.skipPythonPreflight === true;
+	let pythonAvailable = true;
+	const shouldCheckPython =
+		!skipPythonPreflight &&
+		pythonMode !== "bash-only" &&
+		(requestedTools === undefined || requestedTools.includes("python"));
+	const isTestEnv = Bun.env.BUN_ENV === "test" || Bun.env.NODE_ENV === "test";
+	const skipPythonWarm = isTestEnv || $env.ARCANE_PYTHON_SKIP_CHECK === "1";
+	if (shouldCheckPython) {
+		const availability = await checkPythonKernelAvailability(session.cwd);
+		time("createTools:pythonCheck");
+		pythonAvailable = availability.ok;
+		if (!availability.ok) {
+			logger.warn("Python kernel unavailable, falling back to bash", {
+				reason: availability.reason,
+			});
+		} else if (!skipPythonWarm && getPreludeDocs().length === 0) {
+			const sessionFile = session.getSessionFile?.() ?? undefined;
+			const warmSessionId = sessionFile ? `session:${sessionFile}:cwd:${session.cwd}` : `cwd:${session.cwd}`;
+			try {
+				await warmPythonEnvironment(session.cwd, warmSessionId, session.settings.get("python.sharedGateway"));
+				time("createTools:warmPython");
+			} catch (err) {
+				logger.warn("Failed to warm Python environment", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+		}
+	}
+
+	const effectiveMode = pythonAvailable ? pythonMode : "bash-only";
+	const allowBash = effectiveMode !== "ipy-only";
+	const allowPython = effectiveMode !== "bash-only";
+	if (
+		requestedTools &&
+		allowBash &&
+		!allowPython &&
+		requestedTools.includes("python") &&
+		!requestedTools.includes("bash")
+	) {
+		requestedTools.push("bash");
+	}
+	const allTools: Record<string, ToolFactory> = { ...BUILTIN_TOOLS, ...HIDDEN_TOOLS };
+	const isToolAllowed = (name: string) => {
+		if (name === "lsp") return enableLsp;
+		if (name === "bash") return allowBash;
+		if (name === "python") return allowPython;
+		if (name === "todo_write") return !includeSubmitResult && session.settings.get("todo.enabled");
+		if (name === "find") return session.settings.get("find.enabled");
+		if (name === "grep") return session.settings.get("grep.enabled");
+		if (name === "notebook") return session.settings.get("notebook.enabled");
+		if (name === "fetch") return session.settings.get("fetch.enabled");
+		if (name === "web_search") return session.settings.get("web_search.enabled");
+		if (name === "lsp") return session.settings.get("lsp.enabled");
+		if (name === "calc") return session.settings.get("calc.enabled");
+		if (name === "browser") return session.settings.get("browser.enabled");
+		if (name === "librarian") return session.settings.get("librarian.enabled");
+		if (name === "oracle") return session.settings.get("oracle.enabled");
+		if (name === "task") {
+			const maxDepth = session.settings.get("task.maxRecursionDepth") ?? 2;
+			const currentDepth = session.taskDepth ?? 0;
+			return maxDepth < 0 || currentDepth < maxDepth;
+		}
+		return true;
+	};
+	if (includeSubmitResult && requestedTools && !requestedTools.includes("submit_result")) {
+		requestedTools.push("submit_result");
+	}
+
+	const filteredRequestedTools = requestedTools?.filter(name => name in allTools && isToolAllowed(name));
+
+	const entries =
+		filteredRequestedTools !== undefined
+			? filteredRequestedTools.map(name => [name, allTools[name]] as const)
+			: [
+					...Object.entries(BUILTIN_TOOLS).filter(([name]) => isToolAllowed(name)),
+					...(includeSubmitResult ? ([["submit_result", HIDDEN_TOOLS.submit_result]] as const) : []),
+				];
+
+	const results = await Promise.all(
+		entries.map(async ([name, factory]) => {
+			if (filteredRequestedTools && !filteredRequestedTools.includes(name)) {
+				return null;
+			}
+			const tool = await factory(session);
+			time(`createTools:${name}`);
+			return tool ? wrapToolWithMetaNotice(tool) : null;
+		}),
+	);
+	const tools = results.filter((r): r is Tool => r !== null);
+
+	// Code Mode: wrap all eligible tools into a single "code" tool
+	if (session.settings.get("codemode.enabled")) {
+		const { codeTool, excludedTools } = createCodeTool(tools);
+		return [codeTool as Tool, ...(excludedTools as Tool[])];
+	}
+
+	return tools;
+}

package/src/tools/json-tree.ts

@@ -0,0 +1,231 @@
+/**
+ * JSON tree rendering utilities shared across tool renderers.
+ */
+import type { Theme } from "../modes/theme/theme";
+import { truncateToWidth } from "./render-utils";
+
+/** Max depth for JSON tree rendering */
+export const JSON_TREE_MAX_DEPTH_COLLAPSED = 2;
+export const JSON_TREE_MAX_DEPTH_EXPANDED = 6;
+export const JSON_TREE_MAX_LINES_COLLAPSED = 6;
+export const JSON_TREE_MAX_LINES_EXPANDED = 200;
+export const JSON_TREE_SCALAR_LEN_COLLAPSED = 60;
+export const JSON_TREE_SCALAR_LEN_EXPANDED = 2000;
+
+/**
+ * Format a scalar value for inline display.
+ */
+export function formatScalar(value: unknown, maxLen: number): string {
+	if (value === null) return "null";
+	if (value === undefined) return "undefined";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") return String(value);
+	if (typeof value === "string") {
+		const escaped = value.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+		const truncated = truncateToWidth(escaped, maxLen);
+		return `"${truncated}"`;
+	}
+	if (Array.isArray(value)) return `[${value.length} items]`;
+	if (typeof value === "object") {
+		const keys = Object.keys(value);
+		return `{${keys.length} keys}`;
+	}
+	return String(value);
+}
+
+/**
+ * Format args inline for collapsed view.
+ */
+export function formatArgsInline(args: Record<string, unknown>, maxWidth: number): string {
+	const entries = Object.entries(args);
+	if (entries.length === 0) return "";
+
+	// Single arg: show key=value
+	if (entries.length === 1) {
+		const [key, value] = entries[0];
+		return `${key}=${formatScalar(value, maxWidth - key.length - 1)}`;
+	}
+
+	// Multiple args: show key=value, key=value...
+	const pairs: string[] = [];
+	let totalLen = 0;
+
+	for (const [key, value] of entries) {
+		const valueStr = formatScalar(value, 24);
+		const pairStr = `${key}=${valueStr}`;
+		const addLen = pairs.length > 0 ? pairStr.length + 2 : pairStr.length;
+
+		if (totalLen + addLen > maxWidth && pairs.length > 0) {
+			pairs.push("…");
+			break;
+		}
+
+		pairs.push(pairStr);
+		totalLen += addLen;
+	}
+
+	return pairs.join(", ");
+}
+
+/**
+ * Build tree prefix for nested rendering.
+ */
+function buildTreePrefix(ancestors: boolean[], theme: Theme): string {
+	return ancestors.map(hasNext => (hasNext ? `${theme.tree.vertical}  ` : "   ")).join("");
+}
+
+/**
+ * Render a JSON value as tree lines.
+ */
+export function renderJsonTreeLines(
+	value: unknown,
+	theme: Theme,
+	maxDepth: number,
+	maxLines: number,
+	maxScalarLen: number,
+): { lines: string[]; truncated: boolean } {
+	const lines: string[] = [];
+	let truncated = false;
+
+	const iconObject = theme.styledSymbol("icon.folder", "muted");
+	const iconArray = theme.styledSymbol("icon.package", "muted");
+	const iconScalar = theme.styledSymbol("icon.file", "muted");
+
+	const pushLine = (line: string): boolean => {
+		if (lines.length >= maxLines) {
+			truncated = true;
+			return false;
+		}
+		lines.push(line);
+		return true;
+	};
+
+	const renderNode = (val: unknown, key: string | undefined, ancestors: boolean[], isLast: boolean, depth: number) => {
+		if (lines.length >= maxLines) {
+			truncated = true;
+			return;
+		}
+
+		const connector = isLast ? theme.tree.last : theme.tree.branch;
+		const prefix = `${buildTreePrefix(ancestors, theme)}${theme.fg("dim", connector)} `;
+
+		// Handle scalars
+		if (val === null || val === undefined || typeof val !== "object") {
+			const label = key ? theme.fg("muted", key) : theme.fg("muted", "value");
+
+			// Special handling for multiline strings
+			if (typeof val === "string" && val.includes("\n")) {
+				const strLines = val.split("\n");
+				const maxStrLines = Math.min(strLines.length, Math.max(1, maxLines - lines.length - 1));
+				const continuePrefix = buildTreePrefix([...ancestors, !isLast], theme);
+
+				// First line with label
+				const firstLine = truncateToWidth(strLines[0], maxScalarLen);
+				pushLine(`${prefix}${iconScalar} ${label}: ${theme.fg("dim", `"${firstLine}`)}`);
+
+				// Subsequent lines indented
+				for (let i = 1; i < maxStrLines; i++) {
+					if (lines.length >= maxLines) {
+						truncated = true;
+						break;
+					}
+					const line = truncateToWidth(strLines[i], maxScalarLen);
+					pushLine(`${continuePrefix}   ${theme.fg("dim", ` ${line}`)}`);
+				}
+
+				// Show truncation and closing quote
+				if (strLines.length > maxStrLines) {
+					truncated = true;
+					pushLine(`${continuePrefix}   ${theme.fg("dim", ` …(${strLines.length - maxStrLines} more lines)"`)}`);
+				} else {
+					// Add closing quote to last line - need to modify the last pushed line
+					const lastIdx = lines.length - 1;
+					lines[lastIdx] = `${lines[lastIdx]}${theme.fg("dim", '"')}`;
+				}
+				return;
+			}
+
+			const scalar = formatScalar(val, maxScalarLen);
+			pushLine(`${prefix}${iconScalar} ${label}: ${theme.fg("dim", scalar)}`);
+			return;
+		}
+
+		// Handle arrays
+		if (Array.isArray(val)) {
+			const header = key ? theme.fg("muted", key) : theme.fg("muted", "array");
+			pushLine(`${prefix}${iconArray} ${header}`);
+			if (val.length === 0) {
+				pushLine(
+					`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "[]")}`,
+				);
+				return;
+			}
+			if (depth >= maxDepth) {
+				pushLine(
+					`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "…")}`,
+				);
+				return;
+			}
+			const nextAncestors = [...ancestors, !isLast];
+			for (let i = 0; i < val.length; i++) {
+				renderNode(val[i], `[${i}]`, nextAncestors, i === val.length - 1, depth + 1);
+				if (lines.length >= maxLines) {
+					truncated = true;
+					return;
+				}
+			}
+			return;
+		}
+
+		// Handle objects
+		const header = key ? theme.fg("muted", key) : theme.fg("muted", "object");
+		pushLine(`${prefix}${iconObject} ${header}`);
+		const entries = Object.entries(val as Record<string, unknown>);
+		if (entries.length === 0) {
+			pushLine(
+				`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "{}")}`,
+			);
+			return;
+		}
+		if (depth >= maxDepth) {
+			pushLine(
+				`${buildTreePrefix([...ancestors, !isLast], theme)}${theme.fg("dim", theme.tree.last)} ${theme.fg("dim", "…")}`,
+			);
+			return;
+		}
+		const nextAncestors = [...ancestors, !isLast];
+		for (let i = 0; i < entries.length; i++) {
+			const [childKey, child] = entries[i];
+			renderNode(child, childKey, nextAncestors, i === entries.length - 1, depth + 1);
+			if (lines.length >= maxLines) {
+				truncated = true;
+				return;
+			}
+		}
+	};
+
+	// Render root level
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const entries = Object.entries(value as Record<string, unknown>);
+		for (let i = 0; i < entries.length; i++) {
+			const [childKey, child] = entries[i];
+			renderNode(child, childKey, [], i === entries.length - 1, 1);
+			if (lines.length >= maxLines) {
+				truncated = true;
+				break;
+			}
+		}
+	} else if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			renderNode(value[i], `[${i}]`, [], i === value.length - 1, 1);
+			if (lines.length >= maxLines) {
+				truncated = true;
+				break;
+			}
+		}
+	} else {
+		renderNode(value, undefined, [], true, 0);
+	}
+
+	return { lines, truncated };
+}