@kadi.build/core 0.0.1-alpha.12 → 0.0.1-alpha.14

package/dist/abilities/AbilityLoader.js

@@ -17,7 +17,8 @@ import { AbilityProxy } from './AbilityProxy.js';
 import { AbilityCache } from './AbilityCache.js';
 import { AbilityValidator } from './AbilityValidator.js';
 import { resolveAbilityConfig } from '../utils/LockfileResolver.js';
-import path from 'path';
+import { join } from 'path';
+import { readFileSync } from 'fs';
 /**
  * Ability Loader
  *
@@ -59,6 +60,45 @@ export class AbilityLoader {
      * - Same name, different brokers
      */
     cache = new AbilityCache();
+    /**
+     * Explicit project root (provided by KadiClient)
+     *
+     * This is the directory where KADI will look for abilities.
+     * - If provided: use this directory
+     * - If not provided: default to process.cwd()
+     *
+     * This makes context explicit instead of inferred.
+     */
+    explicitProjectRoot;
+    /**
+     * Create an AbilityLoader
+     *
+     * **AbilityLoader** is responsible for finding, loading, and caching abilities.
+     *
+     * @param options - Loader options
+     * @param options.projectRoot - Explicit project root (overrides detection)
+     *
+     * @example
+     * ```typescript
+     * // With explicit project root (CLI plugin)
+     * const loader = new AbilityLoader({
+     *   projectRoot: '/opt/homebrew/lib/node_modules/@kadi.build/cli'
+     * });
+     *
+     * // Without explicit project root (user project)
+     * const loader = new AbilityLoader({});
+     * ```
+     */
+    constructor(options) {
+        // Store the explicit project root for later use
+        // This will be used in detectProjectRoot() method
+        this.explicitProjectRoot = options?.projectRoot;
+        if (process.env.KADI_DEBUG) {
+            console.log('[DEBUG] AbilityLoader created:', {
+                explicitProjectRoot: this.explicitProjectRoot || 'none (will use default)'
+            });
+        }
+    }
     /**
      * Load an ability with explicit transport
      *
@@ -95,7 +135,19 @@ export class AbilityLoader {
      * ```
      */
     async load(name, transport, options = {}, brokerClient) {
-        // Step 1: Check cache first (avoid duplicate loading)
+        // Step 1: Detect project root
+        // This tells us where to look for abilities
+        // - CLI plugins: Uses explicitProjectRoot from constructor
+        // - User projects: Uses process.cwd()
+        const projectRoot = this.detectProjectRoot();
+        if (process.env.KADI_DEBUG) {
+            console.log('[DEBUG] Loading ability with project root:', {
+                abilityName: name,
+                transport,
+                projectRoot
+            });
+        }
+        // Step 2: Check cache first (avoid duplicate loading)
         const cacheKey = {
             name,
             transport,
@@ -107,17 +159,19 @@ export class AbilityLoader {
             // Cache hit! Return existing ability
             return cached;
         }
-        // Step 2: Create appropriate transport
-        const transportInstance = this.createTransport(name, transport, options, brokerClient);
-        // Step 3: Connect to ability
+        // Step 3: Create appropriate transport with project root context
+        // The transport will use projectRoot to find the ability
+        const transportInstance = this.createTransport(name, transport, options, projectRoot, // ← Pass projectRoot (was callerFilePath before)
+        brokerClient);
+        // Step 4: Connect to ability
         await transportInstance.connect();
-        // Step 4: Create proxy for natural method calling
+        // Step 5: Create proxy for natural method calling
         const ability = AbilityProxy.create(name, transportInstance, transport);
-        // Step 5: Validate if requested
+        // Step 6: Validate if requested
         if (options.validate) {
             AbilityValidator.validate(ability);
         }
-        // Step 6: Cache for future use
+        // Step 7: Cache for future use
         this.cache.set(cacheKey, ability);
         return ability;
     }
@@ -188,29 +242,122 @@ export class AbilityLoader {
     cleanup() {
         return this.cache.cleanup();
     }
+    /**
+     * Detect project root directory
+     *
+     * **Strategy** (simple and explicit):
+     * 1. Use explicit override (constructor option or env var)
+     * 2. Fall back to process.cwd() (default behavior, like professor's approach)
+     *
+     * **Why This Approach?**
+     * - **Explicit over implicit**: Plugins tell us where to load from
+     * - **Simple**: No stack parsing, no complex inference
+     * - **Reliable**: Works in all environments (dev, prod, bundlers, etc.)
+     * - **Escape hatch**: Env var for edge cases
+     *
+     * **How It's Used**:
+     * - CLI plugins: Pass `ctx.core.getKadiInstallPath()` via constructor
+     * - User projects: Don't pass anything, uses process.cwd()
+     * - Edge cases: Set KADI_PROJECT_ROOT env var
+     *
+     * @returns Detected project root directory
+     *
+     * @example
+     * ```typescript
+     * // Example 1: CLI plugin (explicit)
+     * const loader = new AbilityLoader({
+     *   projectRoot: '/opt/homebrew/lib/node_modules/@kadi.build/cli'
+     * });
+     * const root = loader.detectProjectRoot();
+     * // Returns: '/opt/homebrew/lib/node_modules/@kadi.build/cli'
+     *
+     * // Example 2: User project (default)
+     * const loader = new AbilityLoader({});
+     * const root = loader.detectProjectRoot();
+     * // Returns: process.cwd() (e.g., '/Users/kassi/Repositories/KADI/gateway-agent')
+     *
+     * // Example 3: Env var override (escape hatch)
+     * process.env.KADI_PROJECT_ROOT = '/app';
+     * const loader = new AbilityLoader({});
+     * const root = loader.detectProjectRoot();
+     * // Returns: '/app'
+     * ```
+     */
+    detectProjectRoot() {
+        // ====================================================================
+        // Layer 1: Explicit Override
+        // ====================================================================
+        // Priority: Constructor option > Environment variable
+        //
+        // This gives us full control over where abilities are loaded from.
+        // - CLI plugins use constructor option (explicit)
+        // - Edge cases use env var (escape hatch)
+        if (this.explicitProjectRoot) {
+            // Constructor option provided
+            // This happens when CLI plugins pass ctx.core.getKadiInstallPath()
+            if (process.env.KADI_DEBUG) {
+                console.log('[DEBUG] Using explicit project root from constructor:', this.explicitProjectRoot);
+            }
+            return this.explicitProjectRoot;
+        }
+        const envRoot = process.env.KADI_PROJECT_ROOT;
+        if (envRoot) {
+            // Environment variable set
+            // This is the escape hatch for edge cases
+            if (process.env.KADI_DEBUG) {
+                console.log('[DEBUG] Using explicit project root from env:', envRoot);
+            }
+            return envRoot;
+        }
+        // ====================================================================
+        // Layer 2: Default Behavior
+        // ====================================================================
+        // Use process.cwd() (current working directory)
+        //
+        // This is the default behavior for user projects.
+        // It works the same way as professor's original approach.
+        //
+        // When you run: node src/server.js
+        // - process.cwd() returns the directory you ran the command from
+        // - Usually this is the project root
+        // - Abilities are in {cwd}/abilities/
+        const cwd = process.cwd();
+        if (process.env.KADI_DEBUG) {
+            console.log('[DEBUG] Using default project root (process.cwd):', cwd);
+        }
+        return cwd;
+    }
     /**
      * Create appropriate transport instance
      *
-     * Clean factory pattern - delegates to specialized creation methods.
-     * Each transport type has its own dedicated method with proper validation.
+     * Factory pattern that creates the right transport based on type.
+     * Each transport type (native, stdio, broker) has its own creation method.
      *
      * @param name - Ability name
-     * @param transport - Transport type (from inference)
-     * @param options - Load options
+     * @param transport - Transport type (native, stdio, or broker)
+     * @param options - Load options (transport-specific)
      * @param brokerClient - Broker client (for broker transport)
+     * @param projectRoot - Project root directory (where to find abilities)
      * @returns Transport instance ready to connect
      *
      * @throws {KadiError} If transport creation fails
      */
-    createTransport(name, transport, options, brokerClient) {
+    createTransport(name, transport, options, projectRoot, // ← Changed from callerFilePath?: string (moved before optional params)
+    brokerClient) {
         // Delegate to appropriate transport creation method
+        // Pass projectRoot to enable resolution from correct project location
         switch (transport) {
             case 'broker':
+                // Broker transport doesn't need projectRoot (abilities are remote)
                 return this.createBrokerTransport(name, options, brokerClient);
             case 'native':
-                return this.createNativeTransport(name, options);
+                // Native transport loads abilities from local filesystem
+                // Needs projectRoot to find abilities/ folder
+                return this.createNativeTransport(name, options, projectRoot);
             case 'stdio':
-                return this.createStdioTransport(name, options);
+                // Stdio transport runs abilities as child processes
+                // Needs projectRoot to find ability executables
+                return this.createStdioTransport(name, options, projectRoot);
             default:
                 // TypeScript exhaustiveness check ensures this is unreachable
                 const never = transport;
@@ -262,35 +409,52 @@ export class AbilityLoader {
         }, brokerClient);
     }
     /**
-     * Create native transport with path auto-resolution
+     * Create native transport with project root context
      *
-     * If path is provided, uses it directly (backwards compatible).
-     * If path is NOT provided, auto-resolves from agent-lock.json.
+     * Native transport loads abilities directly from the filesystem.
+     *
+     * Resolution strategy:
+     * 1. If explicit path provided → use it directly
+     * 2. Otherwise → auto-resolve from projectRoot using lockfile
      *
      * @param name - Ability name
      * @param options - Load options (native-specific)
+     * @param projectRoot - Project root directory (from detectProjectRoot)
      * @returns Native transport instance
      *
-     * @throws {KadiError} If path is missing and auto-resolution fails
+     * @throws {KadiError} If path cannot be resolved
      */
-    createNativeTransport(name, options) {
+    createNativeTransport(name, options, projectRoot // ← Changed from callerFilePath?: string
+    ) {
         // Step 1: Extract native-specific options (type-safe!)
         const nativeOptions = options;
-        // Step 2: Determine ability path
+        // Step 2: Determine ability path and version
         let abilityPath;
         let abilityVersion = options.version;
         if (nativeOptions.path) {
-            // Explicit path provided - use it (backwards compatible)
+            // Explicit path provided - use it directly
+            // This allows users to override auto-resolution if needed
             abilityPath = nativeOptions.path;
+            if (process.env.KADI_DEBUG) {
+                console.log('[DEBUG] Using explicit ability path:', abilityPath);
+            }
         }
         else {
-            // No path provided - auto-resolve from lockfile
+            // No path provided - auto-resolve using project root
             try {
-                const config = resolveAbilityConfig(name);
+                // Pass projectRoot directly to resolver
+                // Resolver will look in {projectRoot}/agent-lock.json
+                const config = resolveAbilityConfig(name, projectRoot);
                 abilityPath = config.path;
                 abilityVersion = config.version;
-                // Log for debugging (if needed)
-                // console.debug(`Auto-resolved ${name} to ${abilityPath}`);
+                if (process.env.KADI_DEBUG) {
+                    console.log('[DEBUG] Auto-resolved ability path:', {
+                        name,
+                        projectRoot,
+                        resolvedPath: abilityPath,
+                        version: abilityVersion
+                    });
+                }
             }
             catch (error) {
                 // Re-throw lockfile resolution errors with context
@@ -300,100 +464,304 @@ export class AbilityLoader {
                 throw new KadiError(`Failed to auto-resolve ability '${name}'`, ErrorCode.ABILITY_NOT_FOUND, 404, {
                     abilityName: name,
                     transport: 'native',
-                    reason: 'Could not auto-resolve path from lockfile',
+                    projectRoot,
+                    reason: 'Could not auto-resolve path from project root',
                     originalError: error instanceof Error ? error.message : String(error),
                     suggestion: 'Provide explicit path or run `kadi install`',
                     example: 'await client.load("calculator", "native", { path: "./abilities/calculator" })',
                     alternatives: [
                         'Install ability: kadi install ' + name,
                         'Provide explicit path in options',
-                        'Check that agent-lock.json exists'
+                        'Check that agent-lock.json exists in project root'
                     ]
                 });
             }
         }
-        // Step 3: Create NativeTransport with resolved/provided path
+        // Step 3: Read agent.json to get entrypoint
+        // Abilities can specify their entry file in agent.json (e.g., dist/kadi-ability.js)
+        let entryPoint = 'index.js'; // Default fallback
+        try {
+            const agentJsonPath = join(abilityPath, 'agent.json');
+            const agentJson = JSON.parse(readFileSync(agentJsonPath, 'utf8'));
+            if (agentJson.entrypoint) {
+                entryPoint = agentJson.entrypoint;
+            }
+        }
+        catch (error) {
+            // If agent.json doesn't exist or can't be read, use default
+            // This maintains backwards compatibility with abilities that don't have agent.json
+        }
+        // Step 4: Create NativeTransport with resolved path and entrypoint
         return new NativeTransport({
             abilityName: name,
             abilityPath,
             abilityVersion,
+            entryPoint,
             timeout: options.timeout
-            // entryPoint defaults to 'index.js' in NativeTransport constructor
         });
     }
     /**
-     * Create stdio transport with command auto-resolution
+     * Create stdio transport with context-aware command resolution
+     *
+     * Resolution strategy:
+     * 1. If explicit command provided → use it directly
+     * 2. Otherwise → auto-resolve from caller's project context
+     *
+     * **Context-Aware Resolution:**
+     * - Uses callerFilePath to find the correct project root
+     * - CLI plugins resolve from CLI's abilities/
+     * - User projects resolve from project's abilities/
+     *
+     * @param name - Ability name
+     * @param options - Load options (stdio-specific)
+     * @param callerFilePath - File path where load() was called from
+     * @returns Stdio transport instance
+     *
+     * @throws {KadiError} If command cannot be resolved
+     */
+    /**
+     * Create stdio transport with auto-resolution support
+     *
+     * **Two modes of operation**:
      *
-     * If command is provided, uses it directly (backwards compatible).
-     * If command is NOT provided, auto-resolves from agent-lock.json.
+     * 1. **Auto-resolution** (no command provided):
+     *    - Resolves ability path using resolveAbilityConfig()
+     *    - Reads ability's agent.json
+     *    - Extracts scripts.start command
+     *    - Spawns child process with shell: true
+     *    - Sets cwd to ability directory
+     *    - Injects KADI_* environment variables
+     *
+     * 2. **Explicit command** (command provided):
+     *    - Uses provided command/args directly
+     *    - Developer has full control
+     *    - Still injects KADI_* environment variables
      *
      * @param name - Ability name
      * @param options - Load options (stdio-specific)
+     * @param projectRoot - Project root directory (from detectProjectRoot)
      * @returns Stdio transport instance
      *
-     * @throws {KadiError} If command is missing and auto-resolution fails
+     * @throws {KadiError} If command cannot be resolved or scripts.start missing
+     *
+     * @example
+     * ```typescript
+     * // Auto-resolution mode
+     * const transport = this.createStdioTransport('calculator', {}, '/project/root');
+     * // Resolves path, reads agent.json, uses scripts.start
+     *
+     * // Explicit mode
+     * const transport = this.createStdioTransport('calculator', {
+     *   command: 'node',
+     *   args: ['dist/index.js']
+     * }, '/project/root');
+     * ```
      */
-    createStdioTransport(name, options) {
-        // Step 1: Extract stdio-specific options (type-safe!)
+    createStdioTransport(name, options, projectRoot) {
+        // ====================================================================
+        // STEP 1: Extract stdio-specific options (type-safe!)
+        // ====================================================================
         const stdioOptions = options;
-        // Step 2: Determine command and args
+        // ====================================================================
+        // STEP 2: Declare variables for transport configuration
+        // ====================================================================
+        // Variables that may be reassigned based on resolution mode
         let command;
         let args = stdioOptions.args;
         let cwd = stdioOptions.cwd;
         let abilityVersion = options.version;
+        let shellMode = false; // Whether to use shell: true
+        // Variables that are only read (never reassigned)
+        const env = stdioOptions.env;
+        // ====================================================================
+        // STEP 3: Determine if we're using explicit command or auto-resolution
+        // ====================================================================
         if (stdioOptions.command) {
-            // Explicit command provided - use it (backwards compatible)
+            // ==================================================================
+            // EXPLICIT COMMAND MODE
+            // ==================================================================
+            // Developer provided command explicitly - use it directly
+            // This gives developers full control when they need it
             command = stdioOptions.command;
+            if (process.env.KADI_DEBUG) {
+                console.log('[DEBUG] Using explicit stdio command:', {
+                    abilityName: name,
+                    command,
+                    args,
+                    cwd: cwd || 'default (process.cwd())'
+                });
+            }
         }
         else {
-            // No command provided - auto-resolve from lockfile
+            // ==================================================================
+            // AUTO-RESOLUTION MODE
+            // ==================================================================
+            // No command provided - auto-resolve from ability's agent.json
+            if (process.env.KADI_DEBUG) {
+                console.log('[DEBUG] Auto-resolving stdio command for ability:', name);
+            }
             try {
-                const config = resolveAbilityConfig(name);
-                // TODO: Runtime detection - currently assumes Node.js
-                // In the future, detect runtime from ability manifest:
-                // - runtime: "node" | "python" | "go" | "binary"
-                // - Or auto-detect from entry file extension (.js, .py, .go)
-                // For now, we assume Node.js for all abilities
-                command = 'node';
-                // Construct entry point path
-                const entryPath = path.join(config.path, config.entry);
-                args = [entryPath];
-                // Set working directory to ability directory
+                // ================================================================
+                // STEP 3a: Resolve ability path and metadata
+                // ================================================================
+                // This function already handles:
+                // - Checking agent-lock.json (if exists)
+                // - Scanning abilities/ folder
+                // - Picking highest version
+                // - Reading agent.json manifest
+                const config = resolveAbilityConfig(name, projectRoot);
+                if (process.env.KADI_DEBUG) {
+                    console.log('[DEBUG] Resolved ability config:', {
+                        name,
+                        path: config.path,
+                        version: config.version,
+                        entry: config.entry
+                    });
+                }
+                // ================================================================
+                // STEP 3b: Extract scripts.start from manifest
+                // ================================================================
+                const startScript = config.manifest.scripts?.start;
+                // ================================================================
+                // STEP 3c: Validate that scripts.start exists
+                // ================================================================
+                if (!startScript || startScript.trim() === '') {
+                    // scripts.start is missing or empty - cannot auto-resolve
+                    // Throw helpful error with actionable suggestions
+                    throw new KadiError(`Cannot auto-load ability '${name}' via stdio - missing scripts.start in agent.json`, ErrorCode.INVALID_CONFIG, 400, {
+                        abilityName: name,
+                        version: config.version,
+                        abilityPath: config.path,
+                        agentJsonPath: join(config.path, 'agent.json'),
+                        reason: 'agent.json does not have a "scripts.start" field',
+                        suggestion: 'Add scripts.start to agent.json OR provide explicit command options',
+                        // Detailed fix instructions
+                        fix: {
+                            option1: {
+                                title: 'Add scripts.start to agent.json',
+                                description: `Edit: ${join(config.path, 'agent.json')}`,
+                                example: {
+                                    name: name,
+                                    version: config.version,
+                                    scripts: {
+                                        start: 'node dist/index.js'
+                                    }
+                                },
+                                instructions: 'Add a "scripts" section with a "start" command that runs your ability'
+                            },
+                            option2: {
+                                title: 'Use explicit command options',
+                                description: 'Provide command and args when loading',
+                                example: `await client.load('${name}', 'stdio', {\n  command: 'node',\n  args: ['${config.entry}']\n})`
+                            }
+                        },
+                        // Examples of valid scripts.start values
+                        examples: [
+                            '"node dist/index.js"           - Run Node.js file',
+                            '"npm start"                     - Run npm script',
+                            '"python3 main.py"               - Run Python script',
+                            '"npm run build && npm start"   - Complex shell command'
+                        ],
+                        // Alternative approaches
+                        alternatives: [
+                            `Add "scripts": { "start": "node ${config.entry}" } to agent.json`,
+                            `Use explicit options: client.load('${name}', 'stdio', { command: 'node', args: ['${config.entry}'] })`
+                        ],
+                        hint: 'scripts.start is the command used to run your ability when loaded via stdio transport'
+                    });
+                }
+                // ================================================================
+                // STEP 3d: Use scripts.start as the command
+                // ================================================================
+                // We'll run this with shell: true so it supports:
+                // - Complex commands: "npm run build && npm start"
+                // - Pipes: "cat input.txt | process"
+                // - Environment variables: "PORT=3000 node server.js"
+                command = startScript;
+                shellMode = true; // Enable shell mode for complex commands
+                // ================================================================
+                // STEP 3e: Set working directory to ability's directory
+                // ================================================================
+                // This ensures relative paths in scripts.start work correctly
+                // Example: If scripts.start is "node dist/index.js"
+                //          and cwd is "/abilities/calculator/1.0.0/"
+                //          then it will find "/abilities/calculator/1.0.0/dist/index.js"
                 cwd = config.path;
-                // Use version from lockfile
+                // ================================================================
+                // STEP 3f: Store version from resolved config
+                // ================================================================
                 abilityVersion = config.version;
-                // Log for debugging (if needed)
-                // console.debug(`Auto-resolved ${name} stdio command: node ${entryPath}`);
+                // ================================================================
+                // STEP 3g: Clear args (not used in shell mode - command contains everything)
+                // ================================================================
+                args = undefined;
+                if (process.env.KADI_DEBUG) {
+                    console.log('[DEBUG] Auto-resolved stdio command:', {
+                        abilityName: name,
+                        command: startScript,
+                        cwd,
+                        version: abilityVersion,
+                        shellMode: true
+                    });
+                }
             }
             catch (error) {
-                // Re-throw lockfile resolution errors with context
+                // Re-throw KadiError as-is (already has helpful context)
                 if (error instanceof KadiError) {
                     throw error;
                 }
-                throw new KadiError(`Failed to auto-resolve ability '${name}' for stdio`, ErrorCode.ABILITY_NOT_FOUND, 404, {
+                // Wrap unexpected errors with context
+                throw new KadiError(`Failed to auto-resolve stdio command for ability '${name}'`, ErrorCode.ABILITY_NOT_FOUND, 404, {
                     abilityName: name,
                     transport: 'stdio',
-                    reason: 'Could not auto-resolve command from lockfile',
+                    projectRoot,
+                    reason: 'Could not auto-resolve command from ability manifest',
                     originalError: error instanceof Error ? error.message : String(error),
-                    suggestion: 'Provide explicit command or run `kadi install`',
-                    example: 'await client.load("calculator", "stdio", { command: "node", args: ["./service.js"] })',
+                    suggestion: 'Provide explicit command or check ability installation',
                     alternatives: [
-                        'Install ability: kadi install ' + name,
-                        'Provide explicit command in options',
-                        'Check that agent-lock.json exists'
+                        `Install ability: kadi install ${name}`,
+                        `Use explicit command: client.load('${name}', 'stdio', { command: '...', args: [...] })`,
+                        'Check that agent.json exists in ability directory'
                     ]
                 });
             }
         }
-        // Step 3: Create StdioTransport with resolved/provided config
+        // ====================================================================
+        // STEP 4: Prepare environment variables
+        // ====================================================================
+        // Merge developer's env vars with auto-injected KADI_* variables
+        const mergedEnv = {
+            // Inherit parent process environment (important for PATH, etc.)
+            ...process.env,
+            // Auto-inject KADI-specific variables
+            // These help the child process understand its context
+            KADI_MODE: 'stdio',
+            KADI_ABILITY_NAME: name,
+            KADI_ABILITY_VERSION: abilityVersion || 'unknown',
+            // Developer's custom environment variables (if provided)
+            // These override defaults if there are conflicts
+            ...(env || {})
+        };
+        if (process.env.KADI_DEBUG) {
+            console.log('[DEBUG] Stdio transport environment variables:', {
+                KADI_MODE: mergedEnv.KADI_MODE,
+                KADI_ABILITY_NAME: mergedEnv.KADI_ABILITY_NAME,
+                KADI_ABILITY_VERSION: mergedEnv.KADI_ABILITY_VERSION,
+                customEnvVars: Object.keys(env || {})
+            });
+        }
+        // ====================================================================
+        // STEP 5: Create StdioTransport with resolved/provided configuration
+        // ====================================================================
         return new StdioTransport({
             abilityName: name,
             command,
             args,
             cwd,
-            env: stdioOptions.env,
+            env: mergedEnv,
             timeout: options.timeout,
-            abilityVersion
+            abilityVersion,
+            shellMode // Pass shell mode flag to transport
         });
     }
 }