@nghyane/arcane 0.1.0

package/src/extensibility/extensions/wrapper.ts

@@ -0,0 +1,188 @@
+/**
+ * Tool wrappers for extensions.
+ */
+import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@nghyane/arcane-agent";
+import type { ImageContent, TextContent } from "@nghyane/arcane-ai";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Theme } from "../../modes/theme/theme";
+import { applyToolProxy } from "../tool-proxy";
+import type { ExtensionRunner } from "./runner";
+import type { RegisteredTool, ToolCallEventResult } from "./types";
+
+/**
+ * Adapts a RegisteredTool into an AgentTool.
+ */
+export class RegisteredToolAdapter implements AgentTool<any, any, any> {
+	declare name: string;
+	declare description: string;
+	declare parameters: any;
+	declare label: string;
+
+	renderCall?: (args: any, options: any, theme: any) => any;
+	renderResult?: (result: any, options: any, theme: any, args?: any) => any;
+
+	constructor(
+		private registeredTool: RegisteredTool,
+		private runner: ExtensionRunner,
+	) {
+		applyToolProxy(registeredTool.definition, this);
+
+		// Only define render methods when the underlying definition provides them.
+		// If these exist unconditionally on the prototype, ToolExecutionComponent
+		// enters the custom-renderer path, gets undefined back, and silently
+		// discards tool result text (extensions without renderers show blank).
+		if (registeredTool.definition.renderCall) {
+			this.renderCall = (args: any, options: any, theme: any) =>
+				registeredTool.definition.renderCall!(args, options, theme as Theme);
+		}
+		if (registeredTool.definition.renderResult) {
+			this.renderResult = (result: any, options: any, theme: any, args?: any) =>
+				registeredTool.definition.renderResult!(
+					result,
+					{ expanded: options.expanded, isPartial: options.isPartial, spinnerFrame: options.spinnerFrame },
+					theme as Theme,
+					args,
+				);
+		}
+	}
+
+	async execute(
+		toolCallId: string,
+		params: any,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<any>,
+		_context?: AgentToolContext,
+	) {
+		return this.registeredTool.definition.execute(toolCallId, params, signal, onUpdate, this.runner.createContext());
+	}
+}
+
+/**
+ * Backward-compatible factory function wrapper.
+ */
+export function wrapRegisteredTool(registeredTool: RegisteredTool, runner: ExtensionRunner): AgentTool {
+	return new RegisteredToolAdapter(registeredTool, runner);
+}
+
+/**
+ * Wrap all registered tools into AgentTools.
+ */
+export function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: ExtensionRunner): AgentTool[] {
+	return registeredTools.map(rt => wrapRegisteredTool(rt, runner));
+}
+
+/**
+ * Wraps a tool with extension callbacks for interception.
+ * - Emits tool_call event before execution (can block)
+ * - Emits tool_result event after execution (can modify result)
+ */
+export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetails = unknown>
+	implements AgentTool<TParameters, TDetails>
+{
+	declare name: string;
+	declare description: string;
+	declare parameters: TParameters;
+	declare label: string;
+
+	constructor(
+		private tool: AgentTool<TParameters, TDetails>,
+		private runner: ExtensionRunner,
+	) {
+		applyToolProxy(tool, this);
+	}
+
+	/**
+	 * Forward browser mode changes when available.
+	 */
+	restartForModeChange(): Promise<void> {
+		const target = this.tool as { restartForModeChange?: () => Promise<void> };
+		if (!target.restartForModeChange) return Promise.resolve();
+		return target.restartForModeChange();
+	}
+
+	async execute(
+		toolCallId: string,
+		params: Static<TParameters>,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>,
+		context?: AgentToolContext,
+	) {
+		// Emit tool_call event - extensions can block execution
+		if (this.runner.hasHandlers("tool_call")) {
+			try {
+				const callResult = (await this.runner.emitToolCall({
+					type: "tool_call",
+					toolName: this.tool.name,
+					toolCallId,
+					input: params as Record<string, unknown>,
+				})) as ToolCallEventResult | undefined;
+
+				if (callResult?.block) {
+					const reason = callResult.reason || "Tool execution was blocked by an extension";
+					throw new Error(reason);
+				}
+			} catch (err) {
+				if (err instanceof Error) {
+					throw err;
+				}
+				throw new Error(`Extension failed, blocking execution: ${String(err)}`);
+			}
+		}
+
+		// Execute the actual tool
+		let result: { content: any; details?: TDetails };
+		let executionError: Error | undefined;
+
+		try {
+			result = await this.tool.execute(toolCallId, params, signal, onUpdate, context);
+		} catch (err) {
+			executionError = err instanceof Error ? err : new Error(String(err));
+			result = {
+				content: [{ type: "text", text: executionError.message }],
+				details: undefined as TDetails,
+			};
+		}
+
+		// Emit tool_result event - extensions can modify the result and error status
+		if (this.runner.hasHandlers("tool_result")) {
+			const resultResult = await this.runner.emitToolResult({
+				type: "tool_result",
+				toolName: this.tool.name,
+				toolCallId,
+				input: params as Record<string, unknown>,
+				content: result.content,
+				details: result.details,
+				isError: !!executionError,
+			});
+
+			if (resultResult) {
+				const modifiedContent: (TextContent | ImageContent)[] = resultResult.content ?? result.content;
+				const modifiedDetails = (resultResult.details ?? result.details) as TDetails;
+
+				// Extension can override error status
+				if (resultResult.isError === true && !executionError) {
+					// Extension marks a successful result as error
+					const textBlocks = (modifiedContent ?? []).filter((c): c is TextContent => c.type === "text");
+					const errorText = textBlocks.map(t => t.text).join("\n") || "Tool result marked as error by extension";
+					throw new Error(errorText);
+				}
+				if (resultResult.isError === false && executionError) {
+					// Extension clears the error - return success
+					return { content: modifiedContent, details: modifiedDetails };
+				}
+
+				// Error status unchanged, but content/details may be modified
+				if (executionError) {
+					throw executionError;
+				}
+				return { content: modifiedContent, details: modifiedDetails };
+			}
+		}
+
+		// No extension modification
+		if (executionError) {
+			throw executionError;
+		}
+		return result;
+	}
+}

package/src/extensibility/hooks/index.ts

@@ -0,0 +1,16 @@
+// biome-ignore assist/source/organizeImports: biome is not smart
+export type { ReadonlySessionManager, UsageStatistics } from "../../session/session-manager";
+export {
+	discoverAndLoadHooks,
+	loadHooks,
+	type AppendEntryHandler,
+	type BranchHandler,
+	type LoadedHook,
+	type LoadHooksResult,
+	type NavigateTreeHandler,
+	type NewSessionHandler,
+	type SendMessageHandler,
+} from "./loader";
+export { execCommand, HookRunner, type HookErrorListener } from "./runner";
+export { HookToolWrapper } from "./tool-wrapper";
+export * from "./types";

package/src/extensibility/hooks/loader.ts

@@ -0,0 +1,273 @@
+/**
+ * Hook loader - loads TypeScript hook modules using native Bun import.
+ */
+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 { hookCapability } from "../../capability/hook";
+import type { Hook } from "../../discovery";
+import { loadCapability } from "../../discovery";
+import { expandPath } from "../../discovery/helpers";
+import type { HookMessage } from "../../session/messages";
+import type { SessionManager } from "../../session/session-manager";
+import { execCommand } from "./runner";
+import type { ExecOptions, HookAPI, HookFactory, HookMessageRenderer, RegisteredCommand } from "./types";
+
+/**
+ * Generic handler function type.
+ */
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+
+/**
+ * Send message handler type for pi.sendMessage().
+ */
+export type SendMessageHandler = <T = unknown>(
+	message: Pick<HookMessage<T>, "customType" | "content" | "display" | "details">,
+	options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" },
+) => void;
+
+/**
+ * Append entry handler type for pi.appendEntry().
+ */
+export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
+
+/**
+ * New session handler type for ctx.newSession() in HookCommandContext.
+ */
+export type NewSessionHandler = (options?: {
+	parentSession?: string;
+	setup?: (sessionManager: SessionManager) => Promise<void>;
+}) => Promise<{ cancelled: boolean }>;
+
+/**
+ * Branch handler type for ctx.branch() in HookCommandContext.
+ */
+export type BranchHandler = (entryId: string) => Promise<{ cancelled: boolean }>;
+
+/**
+ * Navigate tree handler type for ctx.navigateTree() in HookCommandContext.
+ */
+export type NavigateTreeHandler = (
+	targetId: string,
+	options?: { summarize?: boolean },
+) => Promise<{ cancelled: boolean }>;
+
+/**
+ * Registered handlers for a loaded hook.
+ */
+export interface LoadedHook {
+	/** Original path from config */
+	path: string;
+	/** Resolved absolute path */
+	resolvedPath: string;
+	/** Map of event type to handler functions */
+	handlers: Map<string, HandlerFn[]>;
+	/** Map of customType to hook message renderer */
+	messageRenderers: Map<string, HookMessageRenderer>;
+	/** Map of command name to registered command */
+	commands: Map<string, RegisteredCommand>;
+	/** Set the send message handler for this hook's pi.sendMessage() */
+	setSendMessageHandler: (handler: SendMessageHandler) => void;
+	/** Set the append entry handler for this hook's pi.appendEntry() */
+	setAppendEntryHandler: (handler: AppendEntryHandler) => void;
+}
+
+/**
+ * Result of loading hooks.
+ */
+export interface LoadHooksResult {
+	/** Successfully loaded hooks */
+	hooks: LoadedHook[];
+	/** Errors encountered during loading */
+	errors: Array<{ path: string; error: string }>;
+}
+
+/**
+ * Resolve hook path.
+ * - Absolute paths used as-is
+ * - Paths starting with ~ expanded to home directory
+ * - Relative paths resolved from cwd
+ */
+function resolveHookPath(hookPath: string, cwd: string): string {
+	const expanded = expandPath(hookPath);
+
+	if (path.isAbsolute(expanded)) {
+		return expanded;
+	}
+
+	// Relative paths resolved from cwd
+	return path.resolve(cwd, expanded);
+}
+
+/**
+ * Create a HookAPI instance that collects handlers, renderers, and commands.
+ * Returns the API, maps, and functions to set handlers later.
+ */
+function createHookAPI(
+	handlers: Map<string, HandlerFn[]>,
+	cwd: string,
+): {
+	api: HookAPI;
+	messageRenderers: Map<string, HookMessageRenderer>;
+	commands: Map<string, RegisteredCommand>;
+	setSendMessageHandler: (handler: SendMessageHandler) => void;
+	setAppendEntryHandler: (handler: AppendEntryHandler) => void;
+} {
+	let sendMessageHandler: SendMessageHandler | null = null;
+	let appendEntryHandler: AppendEntryHandler | null = null;
+	const messageRenderers = new Map<string, HookMessageRenderer>();
+	const commands = new Map<string, RegisteredCommand>();
+
+	// Cast to HookAPI - the implementation is more general (string event names)
+	// but the interface has specific overloads for type safety in hooks
+	const api = {
+		on(event: string, handler: HandlerFn): void {
+			if (!handlers.has(event)) {
+				handlers.set(event, []);
+			}
+			handlers.get(event)!.push(handler);
+		},
+		sendMessage<T = unknown>(
+			message: HookMessage<T>,
+			options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" },
+		): void {
+			if (!sendMessageHandler) {
+				throw new Error("sendMessage handler not initialized");
+			}
+			sendMessageHandler(message, options);
+		},
+		appendEntry<T = unknown>(customType: string, data?: T): void {
+			if (!appendEntryHandler) {
+				throw new Error("appendEntry handler not initialized");
+			}
+			appendEntryHandler(customType, data);
+		},
+		registerMessageRenderer<T = unknown>(customType: string, renderer: HookMessageRenderer<T>): void {
+			messageRenderers.set(customType, renderer as HookMessageRenderer);
+		},
+		registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void {
+			commands.set(name, { name, ...options });
+		},
+		exec(command: string, args: string[], options?: ExecOptions) {
+			return execCommand(command, args, options?.cwd ?? cwd, options);
+		},
+		logger,
+		typebox,
+		pi: piCodingAgent,
+	} as HookAPI;
+
+	return {
+		api,
+		messageRenderers,
+		commands,
+		setSendMessageHandler: (handler: SendMessageHandler) => {
+			sendMessageHandler = handler;
+		},
+		setAppendEntryHandler: (handler: AppendEntryHandler) => {
+			appendEntryHandler = handler;
+		},
+	};
+}
+
+/**
+ * Load a single hook module using native Bun import.
+ */
+async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHook | null; error: string | null }> {
+	const resolvedPath = resolveHookPath(hookPath, cwd);
+
+	try {
+		// Import the module using native Bun import
+		const module = await import(resolvedPath);
+		const factory = module.default as HookFactory;
+
+		if (typeof factory !== "function") {
+			return { hook: null, error: "Hook must export a default function" };
+		}
+
+		// Create handlers map and API
+		const handlers = new Map<string, HandlerFn[]>();
+		const { api, messageRenderers, commands, setSendMessageHandler, setAppendEntryHandler } = createHookAPI(
+			handlers,
+			cwd,
+		);
+
+		// Call factory to register handlers
+		factory(api);
+
+		return {
+			hook: {
+				path: hookPath,
+				resolvedPath,
+				handlers,
+				messageRenderers,
+				commands,
+				setSendMessageHandler,
+				setAppendEntryHandler,
+			},
+			error: null,
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { hook: null, error: `Failed to load hook: ${message}` };
+	}
+}
+
+/**
+ * Load all hooks from configuration.
+ * @param paths - Array of hook file paths
+ * @param cwd - Current working directory for resolving relative paths
+ */
+export async function loadHooks(paths: string[], cwd: string): Promise<LoadHooksResult> {
+	const hooks: LoadedHook[] = [];
+	const errors: Array<{ path: string; error: string }> = [];
+
+	for (const hookPath of paths) {
+		const { hook, error } = await loadHook(hookPath, cwd);
+
+		if (error) {
+			errors.push({ path: hookPath, error });
+			continue;
+		}
+
+		if (hook) {
+			hooks.push(hook);
+		}
+	}
+
+	return { hooks, errors };
+}
+
+/**
+ * Discover and load hooks from all registered providers.
+ * Uses the capability API to discover hook paths from:
+ * 1. OMP native configs (.arcane/.pi hooks/)
+ * 2. Installed plugins
+ * 3. Other editor/IDE configurations
+ *
+ * Plus any explicitly configured paths from settings.
+ */
+export async function discoverAndLoadHooks(configuredPaths: string[], cwd: string): Promise<LoadHooksResult> {
+	const allPaths: string[] = [];
+	const seen = new Set<string>();
+
+	// Helper to add paths without duplicates
+	const addPaths = (paths: string[]) => {
+		for (const p of paths) {
+			const resolved = path.resolve(p);
+			if (!seen.has(resolved)) {
+				seen.add(resolved);
+				allPaths.push(p);
+			}
+		}
+	};
+
+	// 1. Discover hooks via capability API
+	const discovered = await loadCapability<Hook>(hookCapability.id, { cwd });
+	addPaths(discovered.items.map(hook => hook.path));
+
+	// 2. Explicitly configured paths (can override/add)
+	addPaths(configuredPaths.map(p => resolveHookPath(p, cwd)));
+
+	return loadHooks(allPaths, cwd);
+}