@kadi.build/core 0.0.1-alpha.9 → 0.1.0

package/dist/lockfile.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Lock file resolution for kadi-core v0.1.0
+ *
+ * This module handles reading agent-lock.json and resolving ability paths.
+ * The lock file is generated by kadi-install and contains:
+ * - Exact versions of installed abilities
+ * - Paths where abilities are installed
+ * - Integrity hashes for verification
+ *
+ * Flow:
+ * 1. Find project root (where agent.json lives)
+ * 2. Read agent-lock.json from project root
+ * 3. Look up ability by name to get its installed path
+ */
+import type { AgentLockFile, AbilityLockEntry, ResolvedScript } from './types.js';
+/**
+ * Find the project root by walking up the directory tree.
+ * Looks for agent.json, which marks the root of a KADI project.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Absolute path to the project root
+ * @throws KadiError if no agent.json is found
+ *
+ * @example
+ * ```typescript
+ * const root = await findProjectRoot();
+ * // '/Users/kassi/my-project'
+ *
+ * const root = await findProjectRoot('/Users/kassi/my-project/src/deep/folder');
+ * // '/Users/kassi/my-project'
+ * ```
+ */
+export declare function findProjectRoot(startDir?: string): Promise<string>;
+/**
+ * Read and parse agent-lock.json from a project root.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Parsed lock file contents
+ * @throws KadiError if lock file doesn't exist or is invalid
+ *
+ * @example
+ * ```typescript
+ * const lockFile = await readLockFile('/Users/kassi/my-project');
+ * console.log(lockFile.abilities);
+ * // { 'calculator@1.0.0': { resolved: 'abilities/calculator@1.0.0', ... } }
+ * ```
+ */
+export declare function readLockFile(projectRoot: string): Promise<AgentLockFile>;
+/**
+ * Find an ability entry in the lock file by name.
+ * Keys in the lock file are "name@version", this function matches by name only.
+ *
+ * @param lockFile - The parsed lock file
+ * @param name - Ability name to find (without version)
+ * @returns The ability entry, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const entry = findAbilityEntry(lockFile, 'calculator');
+ * // Returns entry for 'calculator@1.0.0' (or whatever version is installed)
+ * ```
+ */
+export declare function findAbilityEntry(lockFile: AgentLockFile, name: string): AbilityLockEntry | null;
+/**
+ * Get all installed ability names from the lock file.
+ * Useful for error messages listing available abilities.
+ *
+ * @param lockFile - The parsed lock file
+ * @returns Array of ability names (without versions)
+ */
+export declare function getInstalledAbilityNames(lockFile: AgentLockFile): string[];
+/**
+ * Resolve the absolute path to an installed ability.
+ * This is the main function used by loadNative() and loadStdio().
+ *
+ * Flow:
+ * 1. Find project root (if not provided)
+ * 2. Read agent-lock.json
+ * 3. Look up ability by name
+ * 4. Return absolute path to the ability
+ *
+ * @param name - Ability name to resolve
+ * @param projectRoot - Project root (will be auto-detected if not provided)
+ * @returns Absolute path to the ability directory
+ * @throws KadiError if ability not found
+ *
+ * @example
+ * ```typescript
+ * const path = await resolveAbilityPath('calculator');
+ * // '/Users/kassi/my-project/abilities/calculator@1.0.0'
+ * ```
+ */
+export declare function resolveAbilityPath(name: string, projectRoot?: string): Promise<string>;
+/**
+ * Get full ability entry with resolved path.
+ * Returns more information than resolveAbilityPath() for cases where
+ * you need the version, type, or other metadata.
+ *
+ * @param name - Ability name to resolve
+ * @param projectRoot - Project root (will be auto-detected if not provided)
+ * @returns Ability entry with absolute path added
+ */
+export declare function resolveAbilityEntry(name: string, projectRoot?: string): Promise<AbilityLockEntry & {
+    absolutePath: string;
+}>;
+/**
+ * Parsed script command ready for spawning a child process.
+ */
+interface ParsedScript {
+    /** The command to execute (e.g., 'python3', 'node') */
+    command: string;
+    /** Arguments to pass to the command */
+    args: string[];
+}
+/**
+ * Parse a script string into command and arguments.
+ *
+ * This is a simple parser that splits on whitespace.
+ * For most use cases (e.g., "python3 main.py --debug"), this works fine.
+ *
+ * Note: Does not handle quoted arguments with spaces (e.g., "node 'my file.js'").
+ * For complex cases, users should use explicit command/args.
+ *
+ * @param script - Script string from agent.json (e.g., "python3 main.py --verbose")
+ * @returns Parsed command and arguments
+ *
+ * @example
+ * ```typescript
+ * parseScriptCommand('python3 main.py --debug')
+ * // → { command: 'python3', args: ['main.py', '--debug'] }
+ *
+ * parseScriptCommand('node dist/server.js')
+ * // → { command: 'node', args: ['dist/server.js'] }
+ * ```
+ */
+export declare function parseScriptCommand(script: string): ParsedScript;
+/**
+ * Minimal agent.json structure for script resolution.
+ * We only need the scripts section.
+ */
+interface AbilityAgentJson {
+    name?: string;
+    scripts?: Record<string, string>;
+}
+/**
+ * Read an ability's agent.json file.
+ *
+ * @param abilityPath - Absolute path to the ability directory
+ * @returns Parsed agent.json contents
+ * @throws KadiError if agent.json doesn't exist or is invalid
+ *
+ * @example
+ * ```typescript
+ * const agentJson = await readAbilityAgentJson('/path/to/ability');
+ * console.log(agentJson.scripts?.start);
+ * // → "python3 main.py"
+ * ```
+ */
+export declare function readAbilityAgentJson(abilityPath: string): Promise<AbilityAgentJson>;
+/**
+ * Resolve a script command for an ability.
+ *
+ * This is the main function used by loadStdio() when in script resolution mode.
+ *
+ * Flow:
+ * 1. Resolve ability path from agent-lock.json
+ * 2. Read ability's agent.json
+ * 3. Get the requested script (default: 'start')
+ * 4. Parse the script into command and args
+ * 5. Resolve paths relative to ability directory
+ *
+ * @param name - Ability name to resolve
+ * @param scriptName - Which script to use (default: 'start')
+ * @param projectRoot - Project root (auto-detected if not provided)
+ * @returns Command, args, and working directory for spawning the process
+ *
+ * @example
+ * ```typescript
+ * // Uses scripts.start by default
+ * const { command, args, cwd } = await resolveAbilityScript('image-processor');
+ * // → { command: 'python3', args: ['main.py'], cwd: '/path/to/ability' }
+ *
+ * // Use a specific script
+ * const { command, args, cwd } = await resolveAbilityScript('image-processor', 'dev');
+ * // → { command: 'python3', args: ['main.py', '--debug'], cwd: '/path/to/ability' }
+ * ```
+ */
+export declare function resolveAbilityScript(name: string, scriptName?: string, projectRoot?: string): Promise<ResolvedScript>;
+export {};
+//# sourceMappingURL=lockfile.d.ts.map

package/dist/lockfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.d.ts","sourceRoot":"","sources":["../src/lockfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOlF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,QAAQ,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BvF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA+B9E;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,GACX,gBAAgB,GAAG,IAAI,CAsBzB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,EAAE,CAW1E;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAyBtD;AAMD;;GAEG;AACH,UAAU,YAAY;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAoC/D;AAED;;;GAGG;AACH,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6BzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAgB,EAC5B,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,cAAc,CAAC,CAiDzB"}

package/dist/lockfile.js

@@ -0,0 +1,373 @@
+/**
+ * Lock file resolution for kadi-core v0.1.0
+ *
+ * This module handles reading agent-lock.json and resolving ability paths.
+ * The lock file is generated by kadi-install and contains:
+ * - Exact versions of installed abilities
+ * - Paths where abilities are installed
+ * - Integrity hashes for verification
+ *
+ * Flow:
+ * 1. Find project root (where agent.json lives)
+ * 2. Read agent-lock.json from project root
+ * 3. Look up ability by name to get its installed path
+ */
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { KadiError } from './errors.js';
+// ═══════════════════════════════════════════════════════════════════════
+// PROJECT ROOT DISCOVERY
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Find the project root by walking up the directory tree.
+ * Looks for agent.json, which marks the root of a KADI project.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Absolute path to the project root
+ * @throws KadiError if no agent.json is found
+ *
+ * @example
+ * ```typescript
+ * const root = await findProjectRoot();
+ * // '/Users/kassi/my-project'
+ *
+ * const root = await findProjectRoot('/Users/kassi/my-project/src/deep/folder');
+ * // '/Users/kassi/my-project'
+ * ```
+ */
+export async function findProjectRoot(startDir = process.cwd()) {
+    let current = startDir;
+    // Walk up the directory tree looking for agent.json
+    while (current !== dirname(current)) {
+        const agentJsonPath = join(current, 'agent.json');
+        try {
+            // Try to read agent.json - if it exists, this is the project root
+            await readFile(agentJsonPath);
+            return current;
+        }
+        catch {
+            // File doesn't exist, try parent directory
+            current = dirname(current);
+        }
+    }
+    // Reached filesystem root without finding agent.json
+    throw new KadiError('Could not find project root', 'PROJECT_ROOT_NOT_FOUND', {
+        searched: startDir,
+        hint: 'Make sure you are in a KADI project directory with an agent.json file',
+    });
+}
+// ═══════════════════════════════════════════════════════════════════════
+// LOCK FILE READING
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Read and parse agent-lock.json from a project root.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @returns Parsed lock file contents
+ * @throws KadiError if lock file doesn't exist or is invalid
+ *
+ * @example
+ * ```typescript
+ * const lockFile = await readLockFile('/Users/kassi/my-project');
+ * console.log(lockFile.abilities);
+ * // { 'calculator@1.0.0': { resolved: 'abilities/calculator@1.0.0', ... } }
+ * ```
+ */
+export async function readLockFile(projectRoot) {
+    const lockPath = join(projectRoot, 'agent-lock.json');
+    let content;
+    try {
+        content = await readFile(lockPath, 'utf-8');
+    }
+    catch (error) {
+        throw new KadiError('agent-lock.json not found', 'LOCKFILE_NOT_FOUND', {
+            searched: lockPath,
+            hint: 'Run `kadi install` to generate the lock file',
+            alternative: 'Or specify an explicit path when loading abilities',
+        });
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new KadiError('Failed to parse agent-lock.json', 'LOCKFILE_PARSE_ERROR', {
+            path: lockPath,
+            reason: error instanceof Error ? error.message : 'Invalid JSON',
+            hint: 'The lock file may be corrupted. Try running `kadi install` again',
+        });
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// ABILITY LOOKUP
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Find an ability entry in the lock file by name.
+ * Keys in the lock file are "name@version", this function matches by name only.
+ *
+ * @param lockFile - The parsed lock file
+ * @param name - Ability name to find (without version)
+ * @returns The ability entry, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const entry = findAbilityEntry(lockFile, 'calculator');
+ * // Returns entry for 'calculator@1.0.0' (or whatever version is installed)
+ * ```
+ */
+export function findAbilityEntry(lockFile, name) {
+    // Lock file keys are "name@version", we need to match by name only
+    for (const [key, entry] of Object.entries(lockFile.abilities)) {
+        // Find the last @ to split name from version
+        // (handles scoped packages like @kadi.build/ability@1.0.0)
+        const lastAtIndex = key.lastIndexOf('@');
+        if (lastAtIndex === -1) {
+            // No @ in key - shouldn't happen, but check anyway
+            if (key === name) {
+                return entry;
+            }
+            continue;
+        }
+        const abilityName = key.substring(0, lastAtIndex);
+        if (abilityName === name) {
+            return entry;
+        }
+    }
+    return null;
+}
+/**
+ * Get all installed ability names from the lock file.
+ * Useful for error messages listing available abilities.
+ *
+ * @param lockFile - The parsed lock file
+ * @returns Array of ability names (without versions)
+ */
+export function getInstalledAbilityNames(lockFile) {
+    const names = [];
+    for (const key of Object.keys(lockFile.abilities)) {
+        const lastAtIndex = key.lastIndexOf('@');
+        if (lastAtIndex !== -1) {
+            names.push(key.substring(0, lastAtIndex));
+        }
+    }
+    return names;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// PATH RESOLUTION
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Resolve the absolute path to an installed ability.
+ * This is the main function used by loadNative() and loadStdio().
+ *
+ * Flow:
+ * 1. Find project root (if not provided)
+ * 2. Read agent-lock.json
+ * 3. Look up ability by name
+ * 4. Return absolute path to the ability
+ *
+ * @param name - Ability name to resolve
+ * @param projectRoot - Project root (will be auto-detected if not provided)
+ * @returns Absolute path to the ability directory
+ * @throws KadiError if ability not found
+ *
+ * @example
+ * ```typescript
+ * const path = await resolveAbilityPath('calculator');
+ * // '/Users/kassi/my-project/abilities/calculator@1.0.0'
+ * ```
+ */
+export async function resolveAbilityPath(name, projectRoot) {
+    // Find project root if not provided
+    const root = projectRoot ?? await findProjectRoot();
+    // Read lock file
+    const lockFile = await readLockFile(root);
+    // Find ability entry
+    const entry = findAbilityEntry(lockFile, name);
+    if (!entry) {
+        // Build helpful error message with available abilities
+        const available = getInstalledAbilityNames(lockFile);
+        throw new KadiError(`Ability "${name}" not found in agent-lock.json`, 'ABILITY_NOT_FOUND', {
+            abilityName: name,
+            searched: join(root, 'agent-lock.json'),
+            available: available.length > 0 ? available : undefined,
+            hint: `Run \`kadi install ${name}\` to install it`,
+            alternative: 'Or specify an explicit path: { path: "./path/to/ability" }',
+        });
+    }
+    // Build absolute path from project root + relative path in lock file
+    return join(root, entry.resolved);
+}
+/**
+ * Get full ability entry with resolved path.
+ * Returns more information than resolveAbilityPath() for cases where
+ * you need the version, type, or other metadata.
+ *
+ * @param name - Ability name to resolve
+ * @param projectRoot - Project root (will be auto-detected if not provided)
+ * @returns Ability entry with absolute path added
+ */
+export async function resolveAbilityEntry(name, projectRoot) {
+    const root = projectRoot ?? await findProjectRoot();
+    const lockFile = await readLockFile(root);
+    const entry = findAbilityEntry(lockFile, name);
+    if (!entry) {
+        const available = getInstalledAbilityNames(lockFile);
+        throw new KadiError(`Ability "${name}" not found in agent-lock.json`, 'ABILITY_NOT_FOUND', {
+            abilityName: name,
+            searched: join(root, 'agent-lock.json'),
+            available: available.length > 0 ? available : undefined,
+            hint: `Run \`kadi install ${name}\` to install it`,
+            alternative: 'Or specify an explicit path: { path: "./path/to/ability" }',
+        });
+    }
+    return {
+        ...entry,
+        absolutePath: join(root, entry.resolved),
+    };
+}
+/**
+ * Parse a script string into command and arguments.
+ *
+ * This is a simple parser that splits on whitespace.
+ * For most use cases (e.g., "python3 main.py --debug"), this works fine.
+ *
+ * Note: Does not handle quoted arguments with spaces (e.g., "node 'my file.js'").
+ * For complex cases, users should use explicit command/args.
+ *
+ * @param script - Script string from agent.json (e.g., "python3 main.py --verbose")
+ * @returns Parsed command and arguments
+ *
+ * @example
+ * ```typescript
+ * parseScriptCommand('python3 main.py --debug')
+ * // → { command: 'python3', args: ['main.py', '--debug'] }
+ *
+ * parseScriptCommand('node dist/server.js')
+ * // → { command: 'node', args: ['dist/server.js'] }
+ * ```
+ */
+export function parseScriptCommand(script) {
+    // Check for quotes — we can't handle these properly with simple split
+    // Users with complex commands should use explicit command/args
+    if (script.includes("'") || script.includes('"')) {
+        throw new KadiError('Script contains quotes which are not supported', 'INVALID_CONFIG', {
+            script,
+            hint: 'Scripts with quoted arguments cannot be parsed. Provide command and args separately.',
+            example: '{ command: "node", args: ["my file.js"] }',
+        });
+    }
+    // Trim and split on whitespace
+    const parts = script.trim().split(/\s+/);
+    // Extract command (first element)
+    const command = parts[0];
+    if (!command) {
+        throw new KadiError('Script is empty', 'INVALID_CONFIG', {
+            script,
+            hint: 'The script should contain a command (e.g., "python3 main.py")',
+        });
+    }
+    return {
+        command,
+        args: parts.slice(1),
+    };
+}
+/**
+ * Read an ability's agent.json file.
+ *
+ * @param abilityPath - Absolute path to the ability directory
+ * @returns Parsed agent.json contents
+ * @throws KadiError if agent.json doesn't exist or is invalid
+ *
+ * @example
+ * ```typescript
+ * const agentJson = await readAbilityAgentJson('/path/to/ability');
+ * console.log(agentJson.scripts?.start);
+ * // → "python3 main.py"
+ * ```
+ */
+export async function readAbilityAgentJson(abilityPath) {
+    const agentJsonPath = join(abilityPath, 'agent.json');
+    let content;
+    try {
+        content = await readFile(agentJsonPath, 'utf-8');
+    }
+    catch (error) {
+        throw new KadiError(`Ability is missing agent.json`, 'ABILITY_LOAD_FAILED', {
+            path: agentJsonPath,
+            hint: 'The ability directory must contain an agent.json file with a scripts section',
+        });
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new KadiError(`Failed to parse ability's agent.json`, 'ABILITY_LOAD_FAILED', {
+            path: agentJsonPath,
+            reason: error instanceof Error ? error.message : 'Invalid JSON',
+        });
+    }
+}
+/**
+ * Resolve a script command for an ability.
+ *
+ * This is the main function used by loadStdio() when in script resolution mode.
+ *
+ * Flow:
+ * 1. Resolve ability path from agent-lock.json
+ * 2. Read ability's agent.json
+ * 3. Get the requested script (default: 'start')
+ * 4. Parse the script into command and args
+ * 5. Resolve paths relative to ability directory
+ *
+ * @param name - Ability name to resolve
+ * @param scriptName - Which script to use (default: 'start')
+ * @param projectRoot - Project root (auto-detected if not provided)
+ * @returns Command, args, and working directory for spawning the process
+ *
+ * @example
+ * ```typescript
+ * // Uses scripts.start by default
+ * const { command, args, cwd } = await resolveAbilityScript('image-processor');
+ * // → { command: 'python3', args: ['main.py'], cwd: '/path/to/ability' }
+ *
+ * // Use a specific script
+ * const { command, args, cwd } = await resolveAbilityScript('image-processor', 'dev');
+ * // → { command: 'python3', args: ['main.py', '--debug'], cwd: '/path/to/ability' }
+ * ```
+ */
+export async function resolveAbilityScript(name, scriptName = 'start', projectRoot) {
+    // Step 1: Resolve ability path from agent-lock.json
+    const abilityPath = await resolveAbilityPath(name, projectRoot);
+    // Step 2: Read ability's agent.json
+    const agentJson = await readAbilityAgentJson(abilityPath);
+    // Step 3: Get the requested script
+    const scripts = agentJson.scripts;
+    if (!scripts) {
+        throw new KadiError(`Ability "${name}" has no scripts section in agent.json`, 'INVALID_CONFIG', {
+            abilityName: name,
+            agentJsonPath: join(abilityPath, 'agent.json'),
+            hint: 'Add a "scripts" section with a "start" script to agent.json',
+            example: '{ "scripts": { "start": "python3 main.py" } }',
+        });
+    }
+    const script = scripts[scriptName];
+    if (!script) {
+        // Build helpful error with available scripts
+        const availableScripts = Object.keys(scripts).filter(k => scripts[k]); // Filter out empty scripts
+        throw new KadiError(`Script "${scriptName}" not found in ability "${name}"`, 'INVALID_CONFIG', {
+            abilityName: name,
+            requestedScript: scriptName,
+            availableScripts: availableScripts.length > 0 ? availableScripts : undefined,
+            hint: availableScripts.length > 0
+                ? `Available scripts: ${availableScripts.join(', ')}`
+                : 'Add scripts to the ability\'s agent.json',
+        });
+    }
+    // Step 4: Parse the script into command and args
+    const parsed = parseScriptCommand(script);
+    // Step 5: Return with ability path as working directory
+    return {
+        ...parsed,
+        cwd: abilityPath,
+    };
+}
+//# sourceMappingURL=lockfile.js.map

package/dist/lockfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lockfile.js","sourceRoot":"","sources":["../src/lockfile.ts"],"names":[],"mappings":"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"}

package/dist/transports/broker.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Broker transport for kadi-core v0.1.0
+ *
+ * Loads abilities that run on REMOTE agents connected to a broker.
+ * Communication happens via WebSocket using JSON-RPC.
+ *
+ * Protocol flow for invoking a remote tool:
+ * 1. Client sends kadi.ability.request → broker returns { status: 'pending', requestId }
+ * 2. Broker forwards request to provider agent
+ * 3. Provider executes tool and sends result back to broker
+ * 4. Broker sends kadi.ability.response notification with the actual result
+ *
+ * This transport doesn't manage the broker connection itself.
+ * It receives a BrokerState from KadiClient and uses it for communication.
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * WORKAROUND NOTE: Ability Discovery
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * The current broker is TOOL-CENTRIC (tracks tools, not abilities). There's no
+ * direct API to ask "What tools does agent X provide?"
+ *
+ * CURRENT WORKAROUND:
+ * 1. Call kadi.ability.list with includeProviders: true (fetches ALL tools)
+ * 2. Filter tools where provider.displayName matches the ability name
+ * 3. Use the provider's agentId for routing via _kadi hints
+ *
+ * FUTURE: When the broker implements kadi.agent.discover (see design doc at
+ * kadi-broker/docs/design/ABILITY_CENTRIC_DISCOVERY.md), replace the
+ * discoverAbilityWorkaround() function with a direct API call.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+import type { LoadedAbility, BrokerState } from '../types.js';
+/**
+ * Options for creating a broker transport.
+ */
+export interface BrokerTransportOptions {
+    /** The broker connection to use */
+    broker: BrokerState;
+    /** Timeout for requests in milliseconds (default: 30000) */
+    requestTimeout?: number;
+    /** Networks to filter by when discovering (default: all) */
+    networks?: string[];
+}
+/**
+ * Load a remote ability via broker.
+ *
+ * This discovers an agent providing the ability and returns a LoadedAbility
+ * interface that invokes tools via the broker, consistently routing to that
+ * specific agent.
+ *
+ * @param abilityName - Name of the ability to load (matches agent's displayName)
+ * @param options - Broker connection and options
+ * @returns LoadedAbility that can invoke tools remotely
+ *
+ * @example
+ * ```typescript
+ * // The broker state comes from KadiClient
+ * const brokerState = client.getBrokerState('production');
+ *
+ * // Load a remote ability
+ * const analyzer = await loadBrokerTransport('text-analyzer', {
+ *   broker: brokerState,
+ *   requestTimeout: 60000,
+ * });
+ *
+ * // Invoke tools on the remote agent
+ * const result = await analyzer.invoke('analyze', { text: 'hello' });
+ *
+ * // All invocations go to the same agent (consistent routing)
+ * const result2 = await analyzer.invoke('summarize', { text: 'world' });
+ * ```
+ */
+export declare function loadBrokerTransport(abilityName: string, options: BrokerTransportOptions): Promise<LoadedAbility>;
+//# sourceMappingURL=broker.d.ts.map

package/dist/transports/broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.d.ts","sourceRoot":"","sources":["../../src/transports/broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,aAAa,EAEb,WAAW,EAGZ,MAAM,aAAa,CAAC;AAoDrB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,MAAM,EAAE,WAAW,CAAC;IAEpB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAkUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAoGxB"}