@nghyane/arcane 0.1.0

package/src/extensibility/custom-commands/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Custom command types.
+ *
+ * Custom commands are TypeScript modules that define executable slash commands.
+ * Unlike markdown commands which expand to prompts, custom commands can execute
+ * arbitrary logic with full access to the hook context.
+ */
+import type { ExecOptions, ExecResult, HookCommandContext } from "../../extensibility/hooks/types";
+
+// Re-export for custom commands to use
+export type { ExecOptions, ExecResult, HookCommandContext };
+
+/**
+ * API passed to custom command factory.
+ * Similar to HookAPI but focused on command needs.
+ */
+export interface CustomCommandAPI {
+	/** Current working directory */
+	cwd: string;
+	/** Execute a shell command */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+	/** Injected @sinclair/typebox module */
+	typebox: typeof import("@sinclair/typebox");
+	/** Injected pi-coding-agent exports */
+	pi: typeof import("../..");
+}
+
+/**
+ * Custom command definition.
+ *
+ * Commands can either:
+ * - Return a string to be sent to the LLM as a prompt
+ * - Return void/undefined to do nothing (fire-and-forget)
+ *
+ * @example
+ * ```typescript
+ * const factory: CustomCommandFactory = (pi) => ({
+ *	  name: "deploy",
+ *	  description: "Deploy current branch to staging",
+ *	  async execute(args, ctx) {
+ *		 const env = args[0] || "staging";
+ *		 const confirmed = await ctx.ui.confirm("Deploy", `Deploy to ${env}?`);
+ *		 if (!confirmed) return;
+ *
+ *		 const result = await pi.exec("./deploy.sh", [env]);
+ *		 if (result.exitCode !== 0) {
+ *			ctx.ui.notify(`Deploy failed: ${result.stderr}`, "error");
+ *			return;
+ *		 }
+ *
+ *		 ctx.ui.notify("Deploy successful!", "info");
+ *		 // No return = no prompt sent to LLM
+ *	  }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Return a prompt to send to the LLM
+ * const factory: CustomCommandFactory = (pi) => ({
+ *	  name: "git:status",
+ *	  description: "Show git status and suggest actions",
+ *	  async execute(args, ctx) {
+ *		 const result = await pi.exec("git", ["status", "--porcelain"]);
+ *		 return `Here's the git status:\n\`\`\`\n${result.stdout}\`\`\`\nSuggest what to do next.`;
+ *	  }
+ * });
+ * ```
+ */
+export interface CustomCommand {
+	/** Command name (can include namespace like "git:commit") */
+	name: string;
+	/** Description shown in command autocomplete */
+	description: string;
+	/**
+	 * Execute the command.
+	 * @param args - Parsed command arguments
+	 * @param ctx - Command context with UI and session control
+	 * @returns String to send as prompt, or void for fire-and-forget
+	 */
+	execute(args: string[], ctx: HookCommandContext): Promise<string | undefined> | string | undefined;
+}
+
+/**
+ * Factory function that creates custom command(s).
+ * Can return a single command or an array of commands.
+ */
+export type CustomCommandFactory = (
+	api: CustomCommandAPI,
+) => CustomCommand | CustomCommand[] | Promise<CustomCommand | CustomCommand[]>;
+
+/** Source of a loaded custom command */
+export type CustomCommandSource = "bundled" | "user" | "project";
+
+/** Loaded custom command with metadata */
+export interface LoadedCustomCommand {
+	/** Original path to the command module */
+	path: string;
+	/** Resolved absolute path */
+	resolvedPath: string;
+	/** The command definition */
+	command: CustomCommand;
+	/** Where the command was loaded from */
+	source: CustomCommandSource;
+}
+
+/** Result from loading custom commands */
+export interface CustomCommandsLoadResult {
+	commands: LoadedCustomCommand[];
+	errors: Array<{ path: string; error: string }>;
+}

package/src/extensibility/custom-tools/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Custom tools module.
+ */
+
+export { CustomToolLoader, discoverAndLoadCustomTools, loadCustomTools } from "./loader";
+export type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	CustomTool,
+	CustomToolAPI,
+	CustomToolContext,
+	CustomToolFactory,
+	CustomToolResult,
+	CustomToolSessionEvent,
+	CustomToolsLoadResult,
+	CustomToolUIContext,
+	ExecResult,
+	LoadedCustomTool,
+	RenderResultOptions,
+	ToolLoadError,
+} from "./types";
+export { CustomToolAdapter } from "./wrapper";

package/src/extensibility/custom-tools/loader.ts

@@ -0,0 +1,235 @@
+/**
+ * Custom tool loader - loads TypeScript tool modules using native Bun import.
+ *
+ * Dependencies (@sinclair/typebox and pi-coding-agent) are injected via the CustomToolAPI
+ * to avoid import resolution issues with custom tools loaded from user directories.
+ */
+import * as path from "node:path";
+import * as piCodingAgent from "@nghyane/arcane";
+import { logger } from "@nghyane/arcane-utils";
+import * as typebox from "@sinclair/typebox";
+import { toolCapability } from "../../capability/tool";
+import { type CustomTool, loadCapability } from "../../discovery";
+import { expandPath } from "../../discovery/helpers";
+import type { ExecOptions } from "../../exec/exec";
+import { execCommand } from "../../exec/exec";
+import type { HookUIContext } from "../../extensibility/hooks/types";
+import { getAllPluginToolPaths } from "../../extensibility/plugins/loader";
+import { theme } from "../../modes/theme/theme";
+import type { CustomToolAPI, CustomToolFactory, LoadedCustomTool, ToolLoadError } from "./types";
+
+/**
+ * Resolve tool path.
+ * - Absolute paths used as-is
+ * - Paths starting with ~ expanded to home directory
+ * - Relative paths resolved from cwd
+ */
+function resolveToolPath(toolPath: string, cwd: string): string {
+	const expanded = expandPath(toolPath);
+
+	if (path.isAbsolute(expanded)) {
+		return expanded;
+	}
+
+	// Relative paths resolved from cwd
+	return path.resolve(cwd, expanded);
+}
+
+/**
+ * Create a no-op UI context for headless modes.
+ */
+function createNoOpUIContext(): HookUIContext {
+	return {
+		select: async () => undefined,
+		confirm: async () => false,
+		input: async () => undefined,
+		notify: () => {},
+		setStatus: () => {},
+		custom: async () => undefined as never,
+		setEditorText: () => {},
+		getEditorText: () => "",
+		editor: async () => undefined,
+		get theme() {
+			return theme;
+		},
+	};
+}
+
+/**
+ * Load a single tool module using native Bun import.
+ */
+async function loadTool(
+	toolPath: string,
+	cwd: string,
+	sharedApi: CustomToolAPI,
+	source?: { provider: string; providerName: string; level: "user" | "project" },
+): Promise<{ tools: LoadedCustomTool[] | null; error: ToolLoadError | null }> {
+	const resolvedPath = resolveToolPath(toolPath, cwd);
+
+	// Skip declarative tool files (.md, .json) - these are metadata only, not executable modules
+	if (resolvedPath.endsWith(".md") || resolvedPath.endsWith(".json")) {
+		return {
+			tools: null,
+			error: {
+				path: toolPath,
+				error: "Declarative tool files (.md, .json) cannot be loaded as executable modules",
+				source,
+			},
+		};
+	}
+
+	try {
+		const module = await import(resolvedPath);
+		const factory = (module.default ?? module) as CustomToolFactory;
+
+		if (typeof factory !== "function") {
+			return { tools: null, error: { path: toolPath, error: "Tool must export a default function", source } };
+		}
+
+		const toolResult = await factory(sharedApi);
+		const toolsArray = Array.isArray(toolResult) ? toolResult : [toolResult];
+
+		const loadedTools: LoadedCustomTool[] = toolsArray.map(tool => ({
+			path: toolPath,
+			resolvedPath,
+			tool,
+			source,
+		}));
+
+		return { tools: loadedTools, error: null };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { tools: null, error: { path: toolPath, error: `Failed to load tool: ${message}`, source } };
+	}
+}
+
+/** Tool path with optional source metadata */
+interface ToolPathWithSource {
+	path: string;
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/**
+ * Loads custom tools from paths with conflict detection and error handling.
+ *
+ * Manages a shared API instance passed to all tool factories, providing access to
+ * execution context, UI, logger, and injected dependencies. The UI context can be
+ * updated after loading via setUIContext().
+ */
+export class CustomToolLoader {
+	tools: LoadedCustomTool[] = [];
+	errors: ToolLoadError[] = [];
+	#sharedApi: CustomToolAPI;
+	#seenNames: Set<string>;
+
+	constructor(cwd: string, builtInToolNames: string[]) {
+		this.#sharedApi = {
+			cwd,
+			exec: (command: string, args: string[], options?: ExecOptions) =>
+				execCommand(command, args, options?.cwd ?? cwd, options),
+			ui: createNoOpUIContext(),
+			hasUI: false,
+			logger,
+			typebox,
+			pi: piCodingAgent,
+		};
+		this.#seenNames = new Set<string>(builtInToolNames);
+	}
+
+	async load(pathsWithSources: ToolPathWithSource[]): Promise<void> {
+		for (const { path: toolPath, source } of pathsWithSources) {
+			const { tools: loadedTools, error } = await loadTool(toolPath, this.#sharedApi.cwd, this.#sharedApi, source);
+
+			if (error) {
+				this.errors.push(error);
+				continue;
+			}
+
+			if (loadedTools) {
+				for (const loadedTool of loadedTools) {
+					// Check for name conflicts
+					if (this.#seenNames.has(loadedTool.tool.name)) {
+						this.errors.push({
+							path: toolPath,
+							error: `Tool name "${loadedTool.tool.name}" conflicts with existing tool`,
+							source,
+						});
+						continue;
+					}
+
+					this.#seenNames.add(loadedTool.tool.name);
+					this.tools.push(loadedTool);
+				}
+			}
+		}
+	}
+
+	setUIContext(uiContext: HookUIContext, hasUI: boolean): void {
+		this.#sharedApi.ui = uiContext;
+		this.#sharedApi.hasUI = hasUI;
+	}
+}
+
+/**
+ * Load all tools from configuration.
+ * @param pathsWithSources - Array of tool paths with optional source metadata
+ * @param cwd - Current working directory for resolving relative paths
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function loadCustomTools(pathsWithSources: ToolPathWithSource[], cwd: string, builtInToolNames: string[]) {
+	const loader = new CustomToolLoader(cwd, builtInToolNames);
+	await loader.load(pathsWithSources);
+	return {
+		tools: loader.tools,
+		errors: loader.errors,
+		setUIContext: (uiContext: HookUIContext, hasUI: boolean) => {
+			loader.setUIContext(uiContext, hasUI);
+		},
+	};
+}
+
+/**
+ * Discover and load tools from standard locations via capability system:
+ * 1. User and project tools discovered by capability providers
+ * 2. Installed plugins (~/.arcane/plugins/node_modules/*)
+ * 3. Explicitly configured paths from settings or CLI
+ *
+ * @param configuredPaths - Explicit paths from settings.json and CLI --tool flags
+ * @param cwd - Current working directory
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function discoverAndLoadCustomTools(configuredPaths: string[], cwd: string, builtInToolNames: string[]) {
+	const allPathsWithSources: ToolPathWithSource[] = [];
+	const seen = new Set<string>();
+
+	// Helper to add paths without duplicates
+	const addPath = (p: string, source?: { provider: string; providerName: string; level: "user" | "project" }) => {
+		const resolved = path.resolve(p);
+		if (!seen.has(resolved)) {
+			seen.add(resolved);
+			allPathsWithSources.push({ path: p, source });
+		}
+	};
+
+	// 1. Discover tools via capability system (user + project from all providers)
+	const discoveredTools = await loadCapability<CustomTool>(toolCapability.id, { cwd });
+	for (const tool of discoveredTools.items) {
+		addPath(tool.path, {
+			provider: tool._source.provider,
+			providerName: tool._source.providerName,
+			level: tool.level,
+		});
+	}
+
+	// 2. Plugin tools: ~/.arcane/plugins/node_modules/*/
+	for (const pluginPath of await getAllPluginToolPaths(cwd)) {
+		addPath(pluginPath, { provider: "plugin", providerName: "Plugin", level: "user" });
+	}
+
+	// 3. Explicitly configured paths (can override/add)
+	for (const configPath of configuredPaths) {
+		addPath(resolveToolPath(configPath, cwd), { provider: "config", providerName: "Config", level: "project" });
+	}
+
+	return loadCustomTools(allPathsWithSources, cwd, builtInToolNames);
+}

package/src/extensibility/custom-tools/types.ts

@@ -0,0 +1,226 @@
+/**
+ * Custom tool types.
+ *
+ * Custom tools are TypeScript modules that define additional tools for the agent.
+ * They can provide custom rendering for tool calls and results in the TUI.
+ */
+import type { AgentToolResult, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { Model } from "@nghyane/arcane-ai";
+import type { Component } from "@nghyane/arcane-tui";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Rule } from "../../capability/rule";
+import type { ModelRegistry } from "../../config/model-registry";
+import type { ExecOptions, ExecResult } from "../../exec/exec";
+import type { HookUIContext } from "../../extensibility/hooks/types";
+import type { Theme } from "../../modes/theme/theme";
+import type { CompactionResult } from "../../session/compaction";
+import type { ReadonlySessionManager } from "../../session/session-manager";
+import type { TodoItem } from "../../tools/todo-write";
+
+/** Alias for clarity */
+export type CustomToolUIContext = HookUIContext;
+
+/** Re-export for custom tools to use in execute signature */
+export type { AgentToolResult, AgentToolUpdateCallback };
+
+// Re-export for backward compatibility
+export type { ExecOptions, ExecResult } from "../../exec/exec";
+
+/** API passed to custom tool factory (stable across session changes) */
+export interface CustomToolAPI {
+	/** Current working directory */
+	cwd: string;
+	/** Execute a command */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+	/** UI methods for user interaction (select, confirm, input, notify, custom) */
+	ui: CustomToolUIContext;
+	/** Whether UI is available (false in print/RPC mode) */
+	hasUI: boolean;
+	/** File logger for error/warning/debug messages */
+	logger: typeof import("@nghyane/arcane-utils").logger;
+	/** Injected @sinclair/typebox module */
+	typebox: typeof import("@sinclair/typebox");
+	/** Injected pi-coding-agent exports */
+	pi: typeof import("../..");
+}
+
+/**
+ * Context passed to tool execute and onSession callbacks.
+ * Provides access to session state and model information.
+ */
+export interface CustomToolContext {
+	/** Session manager (read-only) */
+	sessionManager: ReadonlySessionManager;
+	/** Model registry - use for API key resolution and model retrieval */
+	modelRegistry: ModelRegistry;
+	/** Current model (may be undefined if no model is selected yet) */
+	model: Model | undefined;
+	/** Whether the agent is idle (not streaming) */
+	isIdle(): boolean;
+	/** Whether there are queued messages waiting to be processed */
+	hasQueuedMessages(): boolean;
+	/** Abort the current agent operation (fire-and-forget, does not wait) */
+	abort(): void;
+}
+
+/** Session event passed to onSession callback */
+export type CustomToolSessionEvent =
+	| {
+			/** Reason for the session event */
+			reason: "start" | "switch" | "branch" | "tree" | "shutdown";
+			/** Previous session file path, or undefined for "start" and "shutdown" */
+			previousSessionFile: string | undefined;
+	  }
+	| {
+			reason: "auto_compaction_start";
+			trigger: "threshold" | "overflow";
+	  }
+	| {
+			reason: "auto_compaction_end";
+			result: CompactionResult | undefined;
+			aborted: boolean;
+			willRetry: boolean;
+			errorMessage?: string;
+	  }
+	| {
+			reason: "auto_retry_start";
+			attempt: number;
+			maxAttempts: number;
+			delayMs: number;
+			errorMessage: string;
+	  }
+	| {
+			reason: "auto_retry_end";
+			success: boolean;
+			attempt: number;
+			finalError?: string;
+	  }
+	| {
+			reason: "ttsr_triggered";
+			rules: Rule[];
+	  }
+	| {
+			reason: "todo_reminder";
+			todos: TodoItem[];
+			attempt: number;
+			maxAttempts: number;
+	  };
+
+/** Rendering options passed to renderResult */
+export interface RenderResultOptions {
+	/** Whether the result view is expanded */
+	expanded: boolean;
+	/** Whether this is a partial/streaming result */
+	isPartial: boolean;
+	/** Current spinner frame index for animated elements (0-9, only provided during partial results) */
+	spinnerFrame?: number;
+}
+
+export type CustomToolResult<TDetails = any> = AgentToolResult<TDetails>;
+
+/**
+ * Custom tool definition.
+ *
+ * Custom tools are standalone - they don't extend AgentTool directly.
+ * When loaded, they are wrapped in an AgentTool for the agent to use.
+ *
+ * The execute callback receives a ToolContext with access to session state,
+ * model registry, and current model.
+ *
+ * @example
+ * ```typescript
+ * const factory: CustomToolFactory = (pi) => ({
+ *   name: "my_tool",
+ *   label: "My Tool",
+ *   description: "Does something useful",
+ *   parameters: Type.Object({ input: Type.String() }),
+ *
+ *   async execute(toolCallId, params, onUpdate, ctx, signal) {
+ *     // Access session state via ctx.sessionManager
+ *     // Access model registry via ctx.modelRegistry
+ *     // Current model via ctx.model
+ *     return { content: [{ type: "text", text: "Done" }] };
+ *   },
+ *
+ *   onSession(event, ctx) {
+ *     if (event.reason === "shutdown") {
+ *       // Cleanup
+ *     }
+ *     // Reconstruct state from ctx.sessionManager.getEntries()
+ *   }
+ * });
+ * ```
+ */
+export interface CustomTool<TParams extends TSchema = TSchema, TDetails = any> {
+	/** Tool name (used in LLM tool calls) */
+	name: string;
+	/** Human-readable label for UI */
+	label: string;
+	/** Description for LLM */
+	description: string;
+	/** Parameter schema (TypeBox) */
+	parameters: TParams;
+	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
+	hidden?: boolean;
+
+	/**
+	 * Execute the tool.
+	 * @param toolCallId - Unique ID for this tool call
+	 * @param params - Parsed parameters matching the schema
+	 * @param onUpdate - Callback for streaming partial results (for UI, not LLM)
+	 * @param ctx - Context with session manager, model registry, and current model
+	 * @param signal - Optional abort signal for cancellation
+	 */
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		onUpdate: AgentToolUpdateCallback<TDetails, TParams> | undefined,
+		ctx: CustomToolContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<TDetails, TParams>>;
+
+	/** Called on session lifecycle events - use to reconstruct state or cleanup resources */
+	onSession?: (event: CustomToolSessionEvent, ctx: CustomToolContext) => void | Promise<void>;
+	/** Custom rendering for tool call display - return a Component */
+	renderCall?: (args: Static<TParams>, options: RenderResultOptions, theme: Theme) => Component;
+
+	/** Custom rendering for tool result display - return a Component */
+	renderResult?: (
+		result: CustomToolResult<TDetails>,
+		options: RenderResultOptions,
+		theme: Theme,
+		args?: Static<TParams>,
+	) => Component;
+}
+
+/** Factory function that creates a custom tool or array of tools */
+export type CustomToolFactory = (
+	pi: CustomToolAPI,
+) => CustomTool<any, any> | CustomTool<any, any>[] | Promise<CustomTool<any, any> | CustomTool<any, any>[]>;
+
+/** Loaded custom tool with metadata and wrapped AgentTool */
+export interface LoadedCustomTool<TParams extends TSchema = TSchema, TDetails = any> {
+	/** Original path (as specified) */
+	path: string;
+	/** Resolved absolute path */
+	resolvedPath: string;
+	/** The original custom tool instance */
+	tool: CustomTool<TParams, TDetails>;
+	/** Source metadata (provider and level) */
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/** Error with source metadata */
+export interface ToolLoadError {
+	path: string;
+	error: string;
+	source?: { provider: string; providerName: string; level: "user" | "project" };
+}
+
+/** Result from loading custom tools */
+export interface CustomToolsLoadResult {
+	tools: LoadedCustomTool[];
+	errors: ToolLoadError[];
+	/** Update the UI context for all loaded tools. Call when mode initializes. */
+	setUIContext(uiContext: CustomToolUIContext, hasUI: boolean): void;
+}

package/src/extensibility/custom-tools/wrapper.ts

@@ -0,0 +1,45 @@
+/**
+ * CustomToolAdapter wraps CustomTool instances into AgentTool for use with the agent.
+ */
+import type { AgentTool, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Theme } from "../../modes/theme/theme";
+import { applyToolProxy } from "../tool-proxy";
+import type { CustomTool, CustomToolContext } from "./types";
+
+export class CustomToolAdapter<TParams extends TSchema = TSchema, TDetails = any, TTheme extends Theme = Theme>
+	implements AgentTool<TParams, TDetails, TTheme>
+{
+	declare name: string;
+	declare label: string;
+	declare description: string;
+	declare parameters: TParams;
+
+	constructor(
+		private tool: CustomTool<TParams, TDetails>,
+		private getContext: () => CustomToolContext,
+	) {
+		applyToolProxy(tool, this);
+	}
+
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<TDetails, TParams>,
+		context?: CustomToolContext,
+	) {
+		return this.tool.execute(toolCallId, params, onUpdate, context ?? this.getContext(), signal);
+	}
+
+	/**
+	 * Backward-compatible export of factory function for existing callers.
+	 * Prefer CustomToolAdapter constructor directly.
+	 */
+	static wrap<TParams extends TSchema = TSchema, TDetails = any, TTheme extends Theme = Theme>(
+		tool: CustomTool<TParams, TDetails>,
+		getContext: () => CustomToolContext,
+	): AgentTool<TParams, TDetails, TTheme> {
+		return new CustomToolAdapter(tool, getContext);
+	}
+}