@nghyane/arcane 0.1.13 → 0.1.15

package/src/tools/grep.ts

@@ -1,37 +1,33 @@
 import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
-
 import { type GrepResult, grep } from "@nghyane/arcane-natives";
 import type { Component } from "@nghyane/arcane-tui";
 import { Text } from "@nghyane/arcane-tui";
 import { 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 { computeLineHash } from "../patch/hashline";
-import grepDescription from "../prompts/tools/grep.md" with { type: "text" };
 import { DEFAULT_MAX_COLUMN, type TruncationResult, truncateHead } from "../session/streaming-output";
-import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
+import type { Theme } from "../theme/theme";
+import { renderStatusLine } from "../tui";
+import { formatCount, formatEmptyMessage, formatErrorMessage } from "../ui/render-utils";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
-import type { OutputMeta } from "./output-meta";
+import { type OutputMeta, toolResult } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
-import { formatCount, formatEmptyMessage, formatErrorMessage, PREVIEW_LIMITS } from "./render-utils";
 import { ToolError } from "./tool-errors";
-import { toolResult } from "./tool-result";
 
 const grepSchema = Type.Object({
 	pattern: Type.String({ description: "Regex pattern to search for" }),
-	path: Type.Optional(Type.String({ description: "File or directory to search (default: cwd)" })),
-	glob: Type.Optional(Type.String({ description: "Filter files by glob pattern (e.g., '*.js')" })),
-	type: Type.Optional(Type.String({ description: "Filter by file type (e.g., js, py, rust)" })),
-	i: Type.Optional(Type.Boolean({ description: "Case-insensitive search (default: false)" })),
-	pre: Type.Optional(Type.Number({ description: "Lines of context before matches" })),
-	post: Type.Optional(Type.Number({ description: "Lines of context after matches" })),
-	multiline: Type.Optional(Type.Boolean({ description: "Enable multiline matching" })),
-	limit: Type.Optional(Type.Number({ description: "Limit output to first N matches (default: 100)" })),
-	offset: Type.Optional(Type.Number({ description: "Skip first N entries before applying limit (default: 0)" })),
+	path: Type.Optional(Type.String({ description: "Directory or file to search (default: cwd)" })),
+	glob: Type.Optional(Type.String({ description: 'Glob filter for file paths (e.g. "*.ts")' })),
+	type: Type.Optional(Type.String({ description: 'File extension filter without dot (e.g. "ts")' })),
+	i: Type.Optional(Type.Boolean({ description: "Case-insensitive search" })),
+	pre: Type.Optional(Type.Number({ description: "Context lines before match" })),
+	post: Type.Optional(Type.Number({ description: "Context lines after match" })),
+	multiline: Type.Optional(Type.Boolean({ description: "Enable multiline regex matching" })),
+	limit: Type.Optional(Type.Number({ description: "Max number of matches to return" })),
+	offset: Type.Optional(Type.Number({ description: "Skip first N matches" })),
 });
 
 export type GrepToolInput = Static<typeof grepSchema>;
@@ -55,19 +51,13 @@ export interface GrepToolDetails {
 
 type GrepParams = Static<typeof grepSchema>;
 
-export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
+export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails, Theme> {
 	readonly name = "grep";
 	readonly label = "Grep";
-	readonly description: string;
+	description = "Search file contents with regex";
 	readonly parameters = grepSchema;
 
-	constructor(private readonly session: ToolSession) {
-		const displayMode = resolveFileDisplayMode(session);
-		this.description = renderPromptTemplate(grepDescription, {
-			IS_HASHLINE_MODE: displayMode.hashLines,
-			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
-		});
-	}
+	constructor(private readonly session: ToolSession) {}
 
 	async execute(
 		_toolCallId: string,
@@ -286,29 +276,7 @@ export class GrepTool implements AgentTool<typeof grepSchema, GrepToolDetails> {
 			return resultBuilder.done();
 		});
 	}
-}
 
-// =============================================================================
-// TUI Renderer
-// =============================================================================
-
-interface GrepRenderArgs {
-	pattern: string;
-	path?: string;
-	glob?: string;
-	type?: string;
-	i?: boolean;
-	pre?: number;
-	post?: number;
-	multiline?: boolean;
-	limit?: number;
-	offset?: number;
-}
-
-const COLLAPSED_TEXT_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
-
-export const grepToolRenderer = {
-	inline: true,
 	renderCall(args: GrepRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const meta: string[] = [];
 		if (args.path) meta.push(`in ${args.path}`);
@@ -330,11 +298,11 @@ export const grepToolRenderer = {
 			uiTheme,
 		);
 		return new Text(text, 0, 0);
-	},
+	}
 
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: GrepToolDetails; isError?: boolean },
-		options: RenderResultOptions,
+		_options: RenderResultOptions,
 		uiTheme: Theme,
 		args?: GrepRenderArgs,
 	): Component {
@@ -345,145 +313,41 @@ export const grepToolRenderer = {
 			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
 		}
 
-		const hasDetailedData = details?.matchCount !== undefined || details?.fileCount !== undefined;
-
-		if (!hasDetailedData) {
-			const textContent = result.content?.find(c => c.type === "text")?.text;
-			if (!textContent || textContent === "No matches found") {
-				return new Text(formatEmptyMessage("No matches found", uiTheme), 0, 0);
-			}
-			const lines = textContent.split("\n").filter(line => line.trim() !== "");
-			const description = args?.pattern ?? undefined;
-			const header = renderStatusLine(
-				{ icon: "success", title: "Grep", description, meta: [formatCount("item", lines.length)] },
-				uiTheme,
-			);
-			let cached: RenderCache | undefined;
-			return {
-				render(width: number): string[] {
-					const { expanded } = options;
-					const key = new Hasher().bool(expanded).u32(width).digest();
-					if (cached?.key === key) return cached.lines;
-					const listLines = renderTreeList(
-						{
-							items: lines,
-							expanded,
-							maxCollapsed: COLLAPSED_TEXT_LIMIT,
-							itemType: "item",
-							renderItem: line => uiTheme.fg("toolOutput", line),
-						},
-						uiTheme,
-					);
-					const result = [header, ...listLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
-					cached = { key, lines: result };
-					return result;
-				},
-				invalidate() {
-					cached = undefined;
-				},
-			};
-		}
-
 		const matchCount = details?.matchCount ?? 0;
 		const fileCount = details?.fileCount ?? 0;
-		const truncation = details?.meta?.truncation;
-		const limits = details?.meta?.limits;
 		const truncated = Boolean(
-			details?.truncated || truncation || limits?.matchLimit || limits?.resultLimit || limits?.columnTruncated,
+			details?.truncated ||
+				details?.meta?.truncation ||
+				details?.meta?.limits?.matchLimit ||
+				details?.meta?.limits?.resultLimit ||
+				details?.meta?.limits?.columnTruncated,
 		);
 
 		if (matchCount === 0) {
-			const header = renderStatusLine(
-				{ icon: "warning", title: "Grep", description: args?.pattern, meta: ["0 matches"] },
-				uiTheme,
-			);
-			return new Text([header, formatEmptyMessage("No matches found", uiTheme)].join("\n"), 0, 0);
+			return new Text(formatEmptyMessage("No matches found", uiTheme), 0, 0);
 		}
 
-		const summaryParts = [formatCount("match", matchCount), formatCount("file", fileCount)];
-		const meta = [...summaryParts];
+		const meta = [formatCount("match", matchCount), formatCount("file", fileCount)];
 		if (details?.scopePath) meta.push(`in ${details.scopePath}`);
 		if (truncated) meta.push(uiTheme.fg("warning", "truncated"));
-		const description = args?.pattern ?? undefined;
-		const header = renderStatusLine(
-			{ icon: truncated ? "warning" : "success", title: "Grep", description, meta },
+
+		const text = renderStatusLine(
+			{ icon: truncated ? "warning" : "success", title: "Grep", description: args?.pattern, meta },
 			uiTheme,
 		);
+		return new Text(text, 0, 0);
+	}
+}
 
-		const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
-		const rawLines = textContent.split("\n");
-		const hasSeparators = rawLines.some(line => line.trim().length === 0);
-		const matchGroups: string[][] = [];
-		if (hasSeparators) {
-			let current: string[] = [];
-			for (const line of rawLines) {
-				if (line.trim().length === 0) {
-					if (current.length > 0) {
-						matchGroups.push(current);
-						current = [];
-					}
-					continue;
-				}
-				current.push(line);
-			}
-			if (current.length > 0) matchGroups.push(current);
-		} else {
-			for (const line of rawLines) {
-				if (line.trim().length === 0) continue;
-				matchGroups.push([line]);
-			}
-		}
-
-		const getCollapsedMatchLimit = (groups: string[][], maxLines: number): number => {
-			if (groups.length === 0) return 0;
-			let usedLines = 0;
-			let count = 0;
-			for (const group of groups) {
-				if (count > 0 && usedLines + group.length > maxLines) break;
-				usedLines += group.length;
-				count += 1;
-				if (usedLines >= maxLines) break;
-			}
-			return count;
-		};
-
-		const truncationReasons: string[] = [];
-		if (limits?.matchLimit) truncationReasons.push(`limit ${limits.matchLimit.reached} matches`);
-		if (limits?.resultLimit) truncationReasons.push(`limit ${limits.resultLimit.reached} results`);
-		if (truncation) truncationReasons.push(truncation.truncatedBy === "lines" ? "line limit" : "size limit");
-		if (limits?.columnTruncated) truncationReasons.push(`line length ${limits.columnTruncated.maxColumn}`);
-		if (truncation?.artifactId) truncationReasons.push(`full output: artifact://${truncation.artifactId}`);
-
-		const extraLines =
-			truncationReasons.length > 0 ? [uiTheme.fg("warning", `truncated: ${truncationReasons.join(", ")}`)] : [];
-
-		let cached: RenderCache | undefined;
-		return {
-			render(width: number): string[] {
-				const { expanded } = options;
-				const key = new Hasher().bool(expanded).u32(width).digest();
-				if (cached?.key === key) return cached.lines;
-				const maxCollapsed = expanded
-					? matchGroups.length
-					: getCollapsedMatchLimit(matchGroups, COLLAPSED_TEXT_LIMIT);
-				const matchLines = renderTreeList(
-					{
-						items: matchGroups,
-						expanded,
-						maxCollapsed,
-						itemType: "match",
-						renderItem: group => group.map(line => uiTheme.fg("toolOutput", line)),
-					},
-					uiTheme,
-				);
-				const result = [header, ...matchLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
-				cached = { key, lines: result };
-				return result;
-			},
-			invalidate() {
-				cached = undefined;
-			},
-		};
-	},
-	mergeCallAndResult: true,
-};
+interface GrepRenderArgs {
+	pattern: string;
+	path?: string;
+	glob?: string;
+	type?: string;
+	i?: boolean;
+	pre?: number;
+	post?: number;
+	multiline?: boolean;
+	limit?: number;
+	offset?: number;
+}

package/src/tools/index.ts

@@ -1,44 +1,19 @@
 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 { 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 {
+	ExaRenderDetails,
+	ExaSearchResponse,
+	ExaSearchResult,
+} from "../exa/types";
 export {
 	type FileDiagnosticsResult,
 	type FileFormatResult,
@@ -79,21 +54,42 @@ export {
 	webSearchLinkedinTool,
 } from "../web/search";
 export { AskTool, type AskToolDetails } from "./ask";
-export { BashTool, type BashToolDetails, type BashToolInput, type BashToolOptions } from "./bash";
+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 { exploreConfig } from "./explore";
 export { FetchTool, type FetchToolDetails } from "./fetch";
-export { type FindOperations, FindTool, type FindToolDetails, type FindToolInput, type FindToolOptions } from "./find";
+export {
+	type FindOperations,
+	FindTool,
+	type FindToolDetails,
+	type FindToolInput,
+	type FindToolOptions,
+} from "./find";
 export { setPreferredImageProvider } from "./gemini-image";
+export { GitHubTool, type GitHubToolDetails } from "./github";
 export { GrepTool, type GrepToolDetails, type GrepToolInput } from "./grep";
-export { LibrarianTool } from "./librarian";
+export { librarianConfig } from "./librarian";
 export { NotebookTool, type NotebookToolDetails } from "./notebook";
-export { OracleTool } from "./oracle";
-export { PythonTool, type PythonToolDetails, type PythonToolOptions } from "./python";
+export { oracleConfig } from "./oracle";
+export {
+	PythonTool,
+	type PythonToolDetails,
+	type PythonToolOptions,
+} from "./python";
 export { ReadTool, type ReadToolDetails, type ReadToolInput } from "./read";
+export { reviewerConfig } from "./reviewer-tool";
 export { loadSshTool, type SSHToolDetails, SshTool } from "./ssh";
-export { type TodoItem, TodoWriteTool, type TodoWriteToolDetails } from "./todo-write";
+export { type SubagentConfig, SubagentTool } from "./subagent-tool";
+export {
+	type TodoItem,
+	TodoWriteTool,
+	type TodoWriteToolDetails,
+} from "./todo-write";
 export { UndoEditTool, type UndoEditToolDetails } from "./undo-edit";
 export { WriteTool, type WriteToolDetails, type WriteToolInput } from "./write";
 
@@ -144,8 +140,6 @@ export interface 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 */
@@ -160,161 +154,4 @@ export interface ToolSession {
 	settings: Settings;
 }
 
-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 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 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 === "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") {
-			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 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;
-}
+export { BUILTIN_TOOLS, createTools, type ToolName } from "./create-tools";

package/src/tools/json-tree.ts

@@ -1,8 +1,8 @@
 /**
  * JSON tree rendering utilities shared across tool renderers.
  */
-import type { Theme } from "../modes/theme/theme";
-import { truncateToWidth } from "./render-utils";
+import type { Theme } from "../theme/theme";
+import { truncateToWidth } from "../ui/render-utils";
 
 /** Max depth for JSON tree rendering */
 export const JSON_TREE_MAX_DEPTH_COLLAPSED = 2;
@@ -15,7 +15,7 @@ export const JSON_TREE_SCALAR_LEN_EXPANDED = 2000;
 /**
  * Format a scalar value for inline display.
  */
-export function formatScalar(value: unknown, maxLen: number): string {
+function formatScalar(value: unknown, maxLen: number): string {
 	if (value === null) return "null";
 	if (value === undefined) return "undefined";
 	if (typeof value === "boolean") return String(value);

package/src/tools/librarian.ts

@@ -1,33 +1,33 @@
 import { Type } from "@sinclair/typebox";
-import librarianDescription from "../prompts/tools/librarian.md" with { type: "text" };
-import { createSubagentTool } from "./subagent-tool";
+import type { SubagentConfig } from "./subagent-tool";
 
 const schema = Type.Object({
-	query: Type.String({
-		description:
-			"Your question about the codebase or repository. Be specific about what you want to understand or explore.",
-	}),
-	context: Type.Optional(
-		Type.String({
-			description: "Background about what you're trying to achieve.",
-		}),
-	),
+	query: Type.String({ description: "What to look up across repositories" }),
+	context: Type.Optional(Type.String({ description: "Additional context for the search" })),
 });
 
 function buildTask(p: Record<string, unknown>): string {
-	let task = p.query as string;
-	if (p.context) task += `\n\nContext: ${p.context}`;
-	return task;
+	const parts: string[] = [p.query as string];
+	if (p.context) parts.push(`\nContext: ${p.context}`);
+	return parts.join("\n");
 }
 
-export const LibrarianTool = createSubagentTool({
+export const librarianConfig: SubagentConfig<typeof schema.properties> = {
 	name: "librarian",
 	label: "Librarian",
 	agent: "librarian",
 	schema,
-	descriptionTemplate: librarianDescription,
 	progressText: "Exploring repositories...",
 	tmpPrefix: "arc-librarian-",
 	buildTask,
-	buildDescription: p => `Librarian: ${(p.query as string).slice(0, 60)}`,
-});
+	buildDescription: p => String(p.query ?? "").slice(0, 80),
+	buildContextLine: p => {
+		if (!p.context) return null;
+		return `Context: ${String(p.context).split("\n")[0].slice(0, 60)}`;
+	},
+	toolDescription: [
+		"Explore remote GitHub repositories — cross-repo code search, reading files/PRs/issues, tracing commit history, finding implementation examples across public repos.",
+		"WHEN TO USE: Cross-repo code search; reading remote files; tracing PRs/issues/commits; finding how other projects solve similar problems.",
+		"WHEN NOT TO USE: Local codebase search (use explore/grep); quick single-file/issue lookups (use github directly).",
+	].join(" "),
+};

package/src/tools/list-limit.ts

@@ -1,12 +1,12 @@
 import type { LimitsMeta } from "./output-meta";
 
-export interface ListLimitResult<T> {
+interface ListLimitResult<T> {
 	items: T[];
 	limitReached?: number;
 	meta: Partial<LimitsMeta>;
 }
 
-export interface ListLimitOptions {
+interface ListLimitOptions {
 	limit?: number;
 	headLimit?: number;
 	limitType?: "match" | "result";