@kadi.build/core 0.3.4 → 0.5.0

package/src/transports/native.ts

@@ -0,0 +1,307 @@
+/**
+ * Native transport for kadi-core v0.1.0
+ *
+ * Loads abilities that run in the SAME Node.js process.
+ * This is the fastest transport - direct function calls with zero serialization.
+ *
+ * How it works:
+ * 1. Dynamic import the module at the given path
+ * 2. Verify it exports a KadiClient as default
+ * 3. Return a LoadedAbility that delegates to the client
+ *
+ * Use case: Abilities written in TypeScript/JavaScript that you want
+ * to load without spawning a child process.
+ */
+
+import type { LoadedAbility, InvokeOptions, ToolDefinition, EventHandler, ToolExecutionBridge } from '../types.js';
+import { KadiError } from '../errors.js';
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TYPE GUARD
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Interface for what we expect from a KadiClient.
+ * We don't import KadiClient directly to avoid circular dependencies.
+ */
+interface KadiClientLike {
+  /** Get agent information (name, tools, etc.) */
+  readAgentJson(): AgentJsonLike;
+
+  /** Create a bridge for tool execution (internal API) */
+  createToolBridge(): ToolExecutionBridge;
+
+  /** Set event handler callback (for events) */
+  setEventHandler(handler: (event: string, data: unknown) => void): void;
+}
+
+/**
+ * Minimal agent.json structure we need.
+ */
+interface AgentJsonLike {
+  name: string;
+  tools?: ToolDefinition[];
+}
+
+/**
+ * Check if an object looks like a KadiClient.
+ * We check for the methods we need rather than using instanceof,
+ * because the loaded module might have a different version of KadiClient.
+ */
+function isKadiClient(obj: unknown): obj is KadiClientLike {
+  if (obj === null || typeof obj !== 'object') {
+    return false;
+  }
+
+  // obj is confirmed to be a non-null object, safe to access properties
+  const candidate = obj as Record<string, unknown>;
+
+  // Must have readAgentJson method
+  if (typeof candidate.readAgentJson !== 'function') {
+    return false;
+  }
+
+  // Must have createToolBridge method
+  if (typeof candidate.createToolBridge !== 'function') {
+    return false;
+  }
+
+  // Must have setEventHandler method (for events)
+  if (typeof candidate.setEventHandler !== 'function') {
+    return false;
+  }
+
+  return true;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// NATIVE TRANSPORT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Load an in-process ability via dynamic import.
+ *
+ * The module at the given path must export a KadiClient instance as default.
+ * This is the standard pattern for KADI abilities.
+ *
+ * @param path - Absolute path to the ability module directory
+ * @param entrypoint - Optional entry point file (e.g., "index.js"). If not provided,
+ *   uses Node.js module resolution (package.json main/exports or index.js).
+ * @returns LoadedAbility that can invoke tools
+ * @throws KadiError if the module can't be loaded or doesn't export a KadiClient
+ *
+ * @example
+ * ```typescript
+ * // The ability module (calculator/index.ts):
+ * const client = new KadiClient({ name: 'calculator' });
+ * client.registerTool(...);
+ * export default client;
+ *
+ * // Loading it:
+ * const calc = await loadNativeTransport('/path/to/calculator');
+ * const result = await calc.invoke('add', { a: 5, b: 3 });
+ *
+ * // With explicit entrypoint:
+ * const calc = await loadNativeTransport('/path/to/calc', 'main.js');
+ *
+ * // With default timeout:
+ * const calc = await loadNativeTransport('/path/to/calc', undefined, { timeout: 300000 });
+ * ```
+ */
+export async function loadNativeTransport(
+  path: string,
+  entrypoint?: string,
+  options: { timeout?: number } = {}
+): Promise<LoadedAbility> {
+  const defaultTimeout = options.timeout;
+  // Build the import path - append entrypoint if provided
+  const importPath = entrypoint ? `${path}/${entrypoint}` : path;
+
+  // Step 1: Dynamic import the module
+  let module: Record<string, unknown>;
+  try {
+    module = await import(importPath);
+  } catch (error) {
+    throw new KadiError(
+      `Failed to import ability at "${importPath}"`,
+      'NATIVE_IMPORT_ERROR',
+      {
+        path: importPath,
+        reason: error instanceof Error ? error.message : String(error),
+        hint: 'Check that the path is correct and the module has no syntax errors',
+      }
+    );
+  }
+
+  // Step 2: Get the default export
+  const client = module.default;
+
+  if (client === undefined) {
+    throw new KadiError(
+      `Module at "${importPath}" has no default export`,
+      'ABILITY_LOAD_FAILED',
+      {
+        path: importPath,
+        hint: 'The ability must export a KadiClient instance as default export',
+        alternative: 'Example: export default client;',
+      }
+    );
+  }
+
+  // Step 3: Verify it's a KadiClient
+  if (!isKadiClient(client)) {
+    throw new KadiError(
+      `Module at "${importPath}" does not export a KadiClient`,
+      'ABILITY_LOAD_FAILED',
+      {
+        path: importPath,
+        hint: 'The default export must be a KadiClient instance',
+        alternative: 'Make sure you\'re exporting the client, not the class',
+      }
+    );
+  }
+
+  // Step 4: Get agent information
+  let agentJson: AgentJsonLike;
+  try {
+    agentJson = client.readAgentJson();
+  } catch (error) {
+    throw new KadiError(
+      `Failed to read agent information from "${importPath}"`,
+      'ABILITY_LOAD_FAILED',
+      {
+        path: importPath,
+        reason: error instanceof Error ? error.message : String(error),
+        hint: 'The ability\'s readAgentJson() method threw an error',
+      }
+    );
+  }
+
+  // Step 5: Get the tool execution bridge
+  const bridge = client.createToolBridge();
+
+  // Step 6: Set up event handling
+  // Map of event name → array of handlers
+  const eventHandlers = new Map<string, Set<EventHandler>>();
+
+  // When ability calls emit(), this callback fires
+  client.setEventHandler((event: string, data: unknown) => {
+    const handlers = eventHandlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        // Fire handlers asynchronously, don't block
+        Promise.resolve(handler(data)).catch((err) => {
+          // Using console.error directly: event handlers run async and we don't
+          // want to require logger injection into the transport layer
+          console.error(`[KADI] Event handler error for "${event}":`, err);
+        });
+      }
+    }
+  });
+
+  // Step 7: Return LoadedAbility interface
+  return {
+    name: agentJson.name,
+    transport: 'native',
+
+    /**
+     * Invoke a tool on this ability.
+     * For native transport, this is a direct function call - no serialization.
+     *
+     * @param toolName - Name of the tool to invoke
+     * @param params - Input parameters for the tool
+     * @param invokeOptions - Optional settings (timeout override)
+     */
+    async invoke<T>(toolName: string, params: unknown, invokeOptions?: InvokeOptions): Promise<T> {
+      try {
+        const invocation = bridge.executeToolHandler(toolName, params);
+
+        // Per-call timeout overrides default timeout
+        const effectiveTimeout = invokeOptions?.timeout ?? defaultTimeout;
+
+        // If timeout is specified, race against it
+        if (effectiveTimeout !== undefined) {
+          let timeoutId: ReturnType<typeof setTimeout>;
+          const timeoutPromise = new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(() => {
+              reject(new KadiError(
+                `Timeout after ${effectiveTimeout}ms waiting for "${toolName}"`,
+                'TIMEOUT',
+                { toolName, timeoutMs: effectiveTimeout }
+              ));
+            }, effectiveTimeout);
+          });
+
+          try {
+            const result = await Promise.race([invocation, timeoutPromise]);
+            return result as T;
+          } finally {
+            clearTimeout(timeoutId!);
+          }
+        }
+
+        // No timeout - just await directly
+        const result = await invocation;
+        return result as T;
+      } catch (error) {
+        // Re-throw KadiErrors as-is
+        if (error instanceof KadiError) {
+          throw error;
+        }
+        // Wrap other errors
+        throw new KadiError(
+          `Tool "${toolName}" invocation failed`,
+          'TOOL_INVOCATION_FAILED',
+          {
+            toolName,
+            ability: agentJson.name,
+            reason: error instanceof Error ? error.message : String(error),
+          }
+        );
+      }
+    },
+
+    /**
+     * Get the list of tools this ability provides.
+     */
+    getTools(): ToolDefinition[] {
+      return agentJson.tools ?? [];
+    },
+
+    /**
+     * Subscribe to events from this ability.
+     */
+    on(event: string, handler: EventHandler): void {
+      let handlers = eventHandlers.get(event);
+      if (!handlers) {
+        handlers = new Set();
+        eventHandlers.set(event, handlers);
+      }
+      handlers.add(handler);
+    },
+
+    /**
+     * Unsubscribe from events.
+     */
+    off(event: string, handler: EventHandler): void {
+      const handlers = eventHandlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          eventHandlers.delete(event);
+        }
+      }
+    },
+
+    /**
+     * Disconnect and cleanup.
+     * For native transport, there's nothing to cleanup - we share the process.
+     */
+    async disconnect(): Promise<void> {
+      // Clear all event handlers
+      eventHandlers.clear();
+      // Native abilities share the process with us.
+      // No other cleanup needed.
+    },
+  };
+}