@nghyane/arcane 0.1.12 → 0.1.14

package/src/tools/browser.ts

@@ -16,12 +16,10 @@ import type {
 	default as Puppeteer,
 	SerializedAXNode,
 } from "puppeteer";
-import { renderPromptTemplate } from "../config/prompt-templates";
-import browserDescription from "../prompts/tools/browser.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
 import { htmlToBasicMarkdown } from "../web/scrapers/types";
-import type { OutputMeta } from "./output-meta";
+import { type OutputMeta, toolResult } from "./output-meta";
 import stealthTamperingScript from "./puppeteer/00_stealth_tampering.txt" with { type: "text" };
 import stealthActivityScript from "./puppeteer/01_stealth_activity.txt" with { type: "text" };
 import stealthHairlineScript from "./puppeteer/02_stealth_hairline.txt" with { type: "text" };
@@ -37,7 +35,6 @@ import stealthHardwareScript from "./puppeteer/11_stealth_hardware.txt" with { t
 import stealthCodecsScript from "./puppeteer/12_stealth_codecs.txt" with { type: "text" };
 import stealthWorkerScript from "./puppeteer/13_stealth_worker.txt" with { type: "text" };
 import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
-import { toolResult } from "./tool-result";
 
 /**
  * Lazy-import puppeteer from a safe CWD so cosmiconfig doesn't choke
@@ -312,95 +309,70 @@ function resolvePageClient(page: Page): PuppeteerCdpClient | null {
 
 const puppeteerGetArgsSchema = Type.Array(
 	Type.Object({
-		selector: Type.String({
-			description:
-				"Selector for the target element (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
-		}),
-		attribute: Type.Optional(Type.String({ description: "Attribute name (get_attribute)" })),
+		selector: Type.String({ description: "CSS selector" }),
+		attribute: Type.Optional(Type.String({ description: "Attribute to retrieve" })),
 	}),
-	{ description: "Batch arguments for get_* actions", minItems: 1 },
+	{ minItems: 1 },
 );
 
 const browserSchema = Type.Object({
-	action: StringEnum(
-		[
-			"open",
-			"goto",
-			"observe",
-			"click",
-			"click_id",
-			"type",
-			"type_id",
-			"fill",
-			"fill_id",
-			"press",
-			"scroll",
-			"drag",
-			"wait_for_selector",
-			"evaluate",
-			"get_text",
-			"get_html",
-			"get_attribute",
-			"extract_readable",
-			"screenshot",
-			"close",
-		],
-		{ description: "Action to perform" },
-	),
-	url: Type.Optional(Type.String({ description: "URL to navigate to (goto)" })),
-	selector: Type.Optional(
-		Type.String({
-			description:
-				"Selector for the target element (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
-		}),
-	),
-	element_id: Type.Optional(Type.Number({ description: "Element ID from observe" })),
-	include_all: Type.Optional(Type.Boolean({ description: "Include non-interactive nodes in observe" })),
-	viewport_only: Type.Optional(Type.Boolean({ description: "Limit observe output to elements in the viewport" })),
+	action: StringEnum([
+		"open",
+		"goto",
+		"observe",
+		"click",
+		"click_id",
+		"type",
+		"type_id",
+		"fill",
+		"fill_id",
+		"press",
+		"scroll",
+		"drag",
+		"wait_for_selector",
+		"evaluate",
+		"get_text",
+		"get_html",
+		"get_attribute",
+		"extract_readable",
+		"screenshot",
+		"close",
+	]),
+	url: Type.Optional(Type.String({ description: "URL to navigate to" })),
+	selector: Type.Optional(Type.String({ description: "CSS selector for target element" })),
+	element_id: Type.Optional(Type.Number({ description: "Observed element ID from observe action" })),
+	include_all: Type.Optional(Type.Boolean({ description: "Include all elements, not just interactive ones" })),
+	viewport_only: Type.Optional(Type.Boolean({ description: "Only observe elements in the visible viewport" })),
 	args: Type.Optional(puppeteerGetArgsSchema),
-	script: Type.Optional(Type.String({ description: "JavaScript to evaluate (evaluate)" })),
-	text: Type.Optional(Type.String({ description: "Text to type (type)" })),
-	value: Type.Optional(Type.String({ description: "Value to set (fill)" })),
-	attribute: Type.Optional(Type.String({ description: "Attribute name to read (get_attribute)" })),
-	key: Type.Optional(Type.String({ description: "Keyboard key to press (press)" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 30)" })),
+	script: Type.Optional(Type.String({ description: "JavaScript to evaluate in page context" })),
+	text: Type.Optional(Type.String({ description: "Text to type" })),
+	value: Type.Optional(Type.String({ description: "Value to fill into input" })),
+	attribute: Type.Optional(Type.String({ description: "Attribute name to retrieve" })),
+	key: Type.Optional(Type.String({ description: "Key to press (e.g. Enter, Escape)" })),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds" })),
 	wait_until: Type.Optional(
 		StringEnum(["load", "domcontentloaded", "networkidle0", "networkidle2"], {
-			description: "Navigation wait condition (goto)",
-		}),
-	),
-	full_page: Type.Optional(Type.Boolean({ description: "Capture full page screenshot (screenshot)" })),
-	format: Type.Optional(
-		StringEnum(["text", "markdown"], {
-			description: "Output format for extract_readable (text/markdown)",
+			description: "Navigation wait condition",
 		}),
 	),
-	path: Type.Optional(Type.String({ description: "Optional path to save screenshot (relative to cwd)" })),
+	full_page: Type.Optional(Type.Boolean({ description: "Capture full page screenshot" })),
+	format: Type.Optional(StringEnum(["text", "markdown"], { description: "Output format for content extraction" })),
+	path: Type.Optional(Type.String({ description: "File path for screenshot output" })),
 	viewport: Type.Optional(
 		Type.Object({
-			width: Type.Number({ description: "Viewport width in pixels" }),
-			height: Type.Number({ description: "Viewport height in pixels" }),
-			deviceScaleFactor: Type.Optional(Type.Number({ description: "Device scale factor" })),
-		}),
-	),
-	delta_x: Type.Optional(Type.Number({ description: "Scroll delta X (scroll)" })),
-	delta_y: Type.Optional(Type.Number({ description: "Scroll delta Y (scroll)" })),
-	from_selector: Type.Optional(
-		Type.String({
-			description:
-				"Drag start selector (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
-		}),
-	),
-	to_selector: Type.Optional(
-		Type.String({
-			description:
-				"Drag end selector (CSS, or puppeteer query handler like aria/, text/, xpath/, pierce/; also accepts legacy p- prefixes)",
+			width: Type.Number(),
+			height: Type.Number(),
+			deviceScaleFactor: Type.Optional(Type.Number()),
 		}),
 	),
+	delta_x: Type.Optional(Type.Number({ description: "Horizontal scroll or drag distance" })),
+	delta_y: Type.Optional(Type.Number({ description: "Vertical scroll or drag distance" })),
+	from_selector: Type.Optional(Type.String({ description: "Drag source selector" })),
+	to_selector: Type.Optional(Type.String({ description: "Drag target selector" })),
 });
 
 /** Input schema for the Puppeteer tool. */
-export type BrowserParams = Static<typeof browserSchema>;
+type BrowserParams = Static<typeof browserSchema>;
 
 /** Details describing a Puppeteer tool execution result. */
 export interface BrowserToolDetails {
@@ -418,7 +390,7 @@ export interface BrowserToolDetails {
 	meta?: OutputMeta;
 }
 
-export interface ObservationEntry {
+interface ObservationEntry {
 	id: number;
 	role: string;
 	name?: string;
@@ -428,7 +400,7 @@ export interface ObservationEntry {
 	states: string[];
 }
 
-export interface Observation {
+interface Observation {
 	url: string;
 	title?: string;
 	viewport: { width: number; height: number; deviceScaleFactor?: number };
@@ -443,7 +415,7 @@ export interface Observation {
 	elements: ObservationEntry[];
 }
 
-export interface ReadableResult {
+interface ReadableResult {
 	url: string;
 	title?: string;
 	byline?: string;
@@ -482,7 +454,7 @@ function formatEvaluateResult(value: unknown): string {
 export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolDetails> {
 	readonly name = "puppeteer";
 	readonly label = "Puppeteer";
-	readonly description: string;
+	description = "Control a headless browser for web interaction";
 	readonly parameters = browserSchema;
 	#browser: Browser | null = null;
 	#page: Page | null = null;
@@ -493,9 +465,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 	readonly #elementCache = new Map<number, ElementHandle>();
 	readonly #patchedClients = new WeakSet<object>();
 
-	constructor(private readonly session: ToolSession) {
-		this.description = renderPromptTemplate(browserDescription, {});
-	}
+	constructor(private readonly session: ToolSession) {}
 
 	async #closeBrowser(): Promise<void> {
 		await this.#clearElementCache();

package/src/tools/create-tools.ts

@@ -0,0 +1,186 @@
+import type { AgentTool } from "@nghyane/arcane-agent";
+import { $env, logger } from "@nghyane/arcane-utils";
+import { getPreludeDocs, warmPythonEnvironment } from "../ipy/executor";
+import { checkPythonKernelAvailability } from "../ipy/kernel";
+import { LspTool } from "../lsp";
+import { EditTool } from "../patch";
+import { TaskTool } from "../task";
+import { time } from "../utils/timings";
+import { SearchTool } from "../web/search";
+import { AskTool } from "./ask";
+import { BashTool } from "./bash";
+import { BrowserTool } from "./browser";
+import { exploreConfig } from "./explore";
+import { FetchTool } from "./fetch";
+import { FindTool } from "./find";
+import { GitHubTool } from "./github";
+import { GrepTool } from "./grep";
+import type { ToolSession } from "./index";
+import { librarianConfig } from "./librarian";
+import { NotebookTool } from "./notebook";
+import { oracleConfig } from "./oracle";
+import { wrapToolWithMetaNotice } from "./output-meta";
+import { PythonTool } from "./python";
+import { ReadTool } from "./read";
+import { reviewerConfig } from "./reviewer-tool";
+import { SearchCodeTool } from "./search-code";
+import { loadSshTool } from "./ssh";
+import { SubagentTool } from "./subagent-tool";
+import { TodoWriteTool } from "./todo-write";
+import { UndoEditTool } from "./undo-edit";
+import { WriteTool } from "./write";
+
+type ToolFactory = (session: ToolSession) => AgentTool<any, any, any> | null | Promise<AgentTool<any, any, any> | null>;
+
+export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
+	ask: AskTool.createIf,
+	bash: s => new BashTool(s),
+	python: s => new PythonTool(s),
+	ssh: loadSshTool,
+	edit: s => new EditTool(s),
+	find: s => new FindTool(s),
+	explore: s => new SubagentTool(s, exploreConfig),
+	github: s => new GitHubTool(s),
+	grep: s => new GrepTool(s),
+	librarian: s => new SubagentTool(s, librarianConfig),
+	lsp: LspTool.createIf,
+	notebook: s => new NotebookTool(s),
+	oracle: s => new SubagentTool(s, oracleConfig),
+	read: s => new ReadTool(s),
+	browser: s => new BrowserTool(s),
+	task: TaskTool.create,
+	code_review: s => new SubagentTool(s, reviewerConfig),
+	todo_write: s => new TodoWriteTool(s),
+	undo_edit: s => new UndoEditTool(s),
+	fetch: s => new FetchTool(s),
+	web_search: () => new SearchTool(),
+	search_code: () => new SearchCodeTool(),
+	write: s => new WriteTool(s),
+};
+
+export type ToolName = keyof typeof BUILTIN_TOOLS;
+
+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" \u2192 bash-only
+ * - "1" or "py" \u2192 ipy-only
+ * - "mix" or "both" \u2192 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<AgentTool[]> {
+	time("createTools:start");
+	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 };
+	const isToolAllowed = (name: string) => {
+		if (name === "lsp") return enableLsp;
+		if (name === "bash") return allowBash;
+		if (name === "python") return allowPython;
+		if (name === "todo_write") return 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 === "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 === "github") return session.settings.get("github.enabled");
+		if (name === "search_code") return session.isSubagent;
+		if (name === "task") {
+			return !session.isSubagent;
+		}
+		return true;
+	};
+
+	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))];
+
+	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 AgentTool => r !== null);
+
+	return tools;
+}

package/src/tools/default-renderer.ts

@@ -0,0 +1,104 @@
+import type { Component } from "@nghyane/arcane-tui";
+import { Text } from "@nghyane/arcane-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../theme/theme";
+import { renderStatusLine } from "../tui";
+import { formatMoreItems, PREVIEW_LIMITS, TRUNCATE_LENGTHS, truncateToWidth } from "../ui/render-utils";
+import {
+	formatArgsInline,
+	JSON_TREE_MAX_DEPTH_COLLAPSED,
+	JSON_TREE_MAX_DEPTH_EXPANDED,
+	JSON_TREE_MAX_LINES_COLLAPSED,
+	JSON_TREE_MAX_LINES_EXPANDED,
+	JSON_TREE_SCALAR_LEN_COLLAPSED,
+	JSON_TREE_SCALAR_LEN_EXPANDED,
+	renderJsonTreeLines,
+} from "./json-tree";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	if (value !== null && value !== undefined && typeof value === "object") {
+		return value as Record<string, unknown>;
+	}
+	return null;
+}
+
+export interface DefaultRenderer {
+	renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
+	renderResult: (
+		result: { content: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean },
+		options: RenderResultOptions,
+		theme: Theme,
+		args?: unknown,
+	) => Component;
+}
+
+export const defaultRenderer: DefaultRenderer = {
+	renderCall(args: unknown, options: RenderResultOptions, theme: Theme): Component {
+		const label = options.label ?? "Tool";
+		const lines: string[] = [];
+		lines.push(renderStatusLine({ icon: "pending", title: label }, theme));
+
+		const argsObject = asRecord(args);
+		if (argsObject && Object.keys(argsObject).length > 0) {
+			const preview = formatArgsInline(argsObject, TRUNCATE_LENGTHS.SUBAGENT_ERROR);
+			if (preview) {
+				lines.push(theme.fg("dim", preview));
+			}
+		}
+		return new Text(lines.join("\n"), 0, 0);
+	},
+
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean },
+		options: RenderResultOptions & { renderContext?: Record<string, unknown> },
+		theme: Theme,
+		_args?: unknown,
+	): Component {
+		const { expanded = false, isPartial = false } = options;
+		const label = options.label ?? "Tool";
+		const lines: string[] = [];
+		const icon = isPartial ? "pending" : result.isError ? "error" : "success";
+		lines.push(renderStatusLine({ icon, title: label }, theme));
+
+		// Output
+		const textContent = (result.content?.find(c => c.type === "text")?.text ?? "").trimEnd();
+		if (!textContent) {
+			lines.push(theme.fg("dim", "(no output)"));
+			return new Text(lines.join("\n"), 0, 0);
+		}
+
+		// Try JSON tree
+		if (textContent.startsWith("{") || textContent.startsWith("[")) {
+			try {
+				const parsed = JSON.parse(textContent);
+				const maxDepth = expanded ? JSON_TREE_MAX_DEPTH_EXPANDED : JSON_TREE_MAX_DEPTH_COLLAPSED;
+				const maxLines = expanded ? JSON_TREE_MAX_LINES_EXPANDED : JSON_TREE_MAX_LINES_COLLAPSED;
+				const maxScalarLen = expanded ? JSON_TREE_SCALAR_LEN_EXPANDED : JSON_TREE_SCALAR_LEN_COLLAPSED;
+				const tree = renderJsonTreeLines(parsed, theme, maxDepth, maxLines, maxScalarLen);
+				if (tree.lines.length > 0) {
+					lines.push(...tree.lines);
+					if (tree.truncated) {
+						lines.push(theme.fg("dim", "…"));
+					}
+					return new Text(lines.join("\n"), 0, 0);
+				}
+			} catch {
+				// Fall through to raw output
+			}
+		}
+
+		// Raw output
+		const outputLines = textContent.split("\n");
+		const maxOutputLines = expanded ? PREVIEW_LIMITS.OUTPUT_EXPANDED : PREVIEW_LIMITS.OUTPUT_COLLAPSED;
+		const displayLines = outputLines.slice(0, maxOutputLines);
+		for (const line of displayLines) {
+			lines.push(theme.fg("toolOutput", truncateToWidth(line, TRUNCATE_LENGTHS.CONTENT)));
+		}
+		if (outputLines.length > maxOutputLines) {
+			const remaining = outputLines.length - maxOutputLines;
+			lines.push(theme.fg("dim", formatMoreItems(remaining, "line")));
+		}
+
+		return new Text(lines.join("\n"), 0, 0);
+	},
+};

package/src/tools/explore.ts

@@ -1,23 +1,24 @@
 import { Type } from "@sinclair/typebox";
-import exploreDescription from "../prompts/tools/explore.md" with { type: "text" };
-import { createSubagentTool } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent-tool";
 
 const schema = Type.Object({
-	query: Type.String({
-		description:
-			"The search query describing what to find. Be specific — include technical terms, file types, or expected code patterns.",
-	}),
+	query: Type.String({ description: "What to search for in the codebase" }),
 });
 
-export const ExploreTool = createSubagentTool({
+export const exploreConfig: SubagentConfig<typeof schema.properties> = {
 	name: "explore",
 	label: "Explore",
 	agent: "explore",
 	schema,
-	descriptionTemplate: exploreDescription,
 	progressText: "Searching codebase...",
 	tmpPrefix: "arc-explore-",
 	buildTask: p => p.query as string,
-	buildDescription: p => `Explore: ${(p.query as string).slice(0, 60)}`,
+	buildDescription: p => String(p.query ?? "").slice(0, 80),
+	toolDescription: [
+		"Intelligently search the codebase. Use for complex, multi-step search tasks where you need to find code based on functionality or concepts rather than exact matches. Chains multiple grep/find/read calls internally.",
+		'WHEN TO USE: Locate code by behavior or concept; chain multiple searches; correlate several areas of the codebase; filter broad terms ("config", "cache", "auth") by context; answer questions like "Where do we validate JWT headers?".',
+		"WHEN NOT TO USE: Exact file path known (use read tool); specific symbol lookup (use lsp tool); single exact text match (use grep tool); remote repos (use librarian tool).",
+		'PROMPTING: Be specific and goal-oriented. Name concrete artifacts, patterns, or APIs to narrow scope. State explicit success criteria so the agent knows when to stop. Good: "Find all JWT verification calls, return file paths and line numbers." Bad: "auth search".',
+	].join(" "),
 	passContext: false,
-});
+};