@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/transports/NativeTransport.js

@@ -0,0 +1,397 @@
+/**
+ * Native Transport
+ *
+ * Loads abilities in-process for zero-overhead communication.
+ * Best for abilities written in JavaScript/TypeScript that can run in the same process.
+ *
+ * @module transports/NativeTransport
+ */
+import { EventEmitter } from 'events';
+import { resolve } from 'path';
+import { KadiError, ErrorCode } from '../types/index.js';
+/**
+ * Type guard to check if loaded module is a KadiClient instance
+ *
+ * Detection strategy:
+ * - Has readAgentJson() method (returns agent.json representation with tools)
+ * - Has invoke() method (executes tools by name)
+ *
+ * This identifies abilities written using the Registration Pattern (Option A),
+ * where the ability has an agent.json file and uses KadiClient.registerTool().
+ *
+ * @param obj - Object to check
+ * @returns True if object is a KadiClient instance
+ *
+ * @example
+ * ```typescript
+ * const module = await import('./ability.js');
+ * if (isKadiClient(module.default)) {
+ *   const agentJson = module.default.readAgentJson();
+ *   // { name: 'calculator', tools: [...] }
+ * }
+ * ```
+ */
+function isKadiClient(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        'readAgentJson' in obj &&
+        typeof obj.readAgentJson === 'function' &&
+        'invoke' in obj &&
+        typeof obj.invoke === 'function');
+}
+/**
+ * Native Transport
+ *
+ * Loads Node.js modules directly into the current process.
+ * Provides zero-overhead method invocation since everything runs in-process.
+ *
+ * @example
+ * ```typescript
+ * const transport = new NativeTransport({
+ *   abilityName: 'calculator',
+ *   abilityPath: '/path/to/calculator',
+ *   entryPoint: 'index.js'
+ * });
+ *
+ * await transport.connect();
+ * const result = await transport.invoke('add', { a: 5, b: 3 });
+ * console.log(result); // { result: 8 }
+ * ```
+ */
+export class NativeTransport extends EventEmitter {
+    /**
+     * Transport configuration
+     */
+    options;
+    /**
+     * Loaded ability module
+     */
+    ability = null;
+    /**
+     * Whether loaded module is a KadiClient instance
+     */
+    isKadiClientInstance = false;
+    /**
+     * Discovered methods
+     */
+    methods = [];
+    /**
+     * Method schemas
+     */
+    schemas = new Map();
+    /**
+     * Whether transport is connected
+     */
+    connected = false;
+    /**
+     * Create a new NativeTransport
+     *
+     * @param options - Native transport options
+     */
+    constructor(options) {
+        super();
+        this.options = {
+            entryPoint: options.entryPoint ?? 'index.js',
+            timeout: options.timeout ?? 30000,
+            abilityPath: options.abilityPath,
+            abilityName: options.abilityName,
+            abilityVersion: options.abilityVersion ?? '1.0.0'
+        };
+    }
+    /**
+     * Connect to the ability
+     *
+     * Loads the module from disk and performs discovery.
+     *
+     * @throws {KadiError} If module cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * await transport.connect();
+     * ```
+     */
+    async connect() {
+        if (this.connected) {
+            return;
+        }
+        try {
+            // Resolve module path
+            const modulePath = resolve(this.options.abilityPath, this.options.entryPoint);
+            // Load the module
+            const module = await import(modulePath);
+            // Get the ability (default export or named export)
+            this.ability = module.default ?? module;
+            if (!this.ability || typeof this.ability !== 'object') {
+                throw new KadiError(`Ability module must export an object or class instance`, ErrorCode.ABILITY_LOAD_FAILED, 500, { abilityName: this.options.abilityName, modulePath });
+            }
+            // Check if it's a KadiClient instance (Registration Pattern - Option A)
+            this.isKadiClientInstance = isKadiClient(this.ability);
+            if (this.isKadiClientInstance) {
+                // KadiClient instance - read agent.json representation
+                const agentJson = this.ability.readAgentJson();
+                this.methods = agentJson.tools.map(tool => tool.name);
+                // Store schemas from tool definitions (agent.json's 'exports' → runtime 'tools')
+                for (const tool of agentJson.tools) {
+                    if (tool.inputSchema || tool.outputSchema) {
+                        this.schemas.set(tool.name, {
+                            inputSchema: tool.inputSchema,
+                            outputSchema: tool.outputSchema,
+                            description: tool.description
+                        });
+                    }
+                }
+            }
+            else {
+                // Legacy module - use introspection
+                await this.discoverMethods();
+            }
+            this.connected = true;
+            this.emit('connected');
+        }
+        catch (error) {
+            const kadiError = error instanceof KadiError
+                ? error
+                : new KadiError(`Failed to load ability: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.ABILITY_LOAD_FAILED, 500, {
+                    abilityName: this.options.abilityName,
+                    abilityPath: this.options.abilityPath,
+                    originalError: error instanceof Error ? error.message : String(error)
+                });
+            this.emit('error', kadiError);
+            throw kadiError;
+        }
+    }
+    /**
+     * Invoke a method on the ability
+     *
+     * @template TInput - Input parameter type
+     * @template TOutput - Return type
+     *
+     * @param method - Method name
+     * @param params - Method parameters
+     * @returns Promise resolving to method result
+     *
+     * @throws {KadiError} If method doesn't exist or invocation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await transport.invoke<{ a: number; b: number }, { result: number }>(
+     *   'add',
+     *   { a: 5, b: 3 }
+     * );
+     * ```
+     */
+    async invoke(method, params) {
+        if (!this.connected) {
+            throw new KadiError('Transport not connected', ErrorCode.TRANSPORT_NOT_CONNECTED, 503, { abilityName: this.options.abilityName });
+        }
+        // Check if method exists
+        if (!this.methods.includes(method)) {
+            throw new KadiError(`Method '${method}' not found on ability '${this.options.abilityName}'`, ErrorCode.ABILITY_METHOD_NOT_FOUND, 404, { abilityName: this.options.abilityName, method, availableMethods: this.methods });
+        }
+        try {
+            // KadiClient instance - use agent.json protocol (invoke by name)
+            if (this.isKadiClientInstance) {
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new KadiError(`Method invocation timeout after ${this.options.timeout}ms`, ErrorCode.TOOL_TIMEOUT, 408, { abilityName: this.options.abilityName, method, timeout: this.options.timeout }));
+                    }, this.options.timeout);
+                });
+                const result = await Promise.race([
+                    this.ability.invoke(method, params),
+                    timeoutPromise
+                ]);
+                return result;
+            }
+            // Legacy module - use direct method access
+            const handler = this.ability[method];
+            if (typeof handler !== 'function') {
+                throw new KadiError(`Method '${method}' is not a function`, ErrorCode.ABILITY_METHOD_NOT_FOUND, 500, { abilityName: this.options.abilityName, method, type: typeof handler });
+            }
+            // Invoke with timeout
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new KadiError(`Method invocation timeout after ${this.options.timeout}ms`, ErrorCode.TOOL_TIMEOUT, 408, { abilityName: this.options.abilityName, method, timeout: this.options.timeout }));
+                }, this.options.timeout);
+            });
+            const result = await Promise.race([
+                handler.call(this.ability, params),
+                timeoutPromise
+            ]);
+            return result;
+        }
+        catch (error) {
+            // Don't wrap KadiError
+            if (error instanceof KadiError) {
+                throw error;
+            }
+            // Enhance the original error with context
+            if (error instanceof Error) {
+                const enhancedError = error;
+                enhancedError.message = `${error.message} (in ${this.options.abilityName}.${method})`;
+                throw enhancedError;
+            }
+            throw new KadiError(`Method invocation failed: ${String(error)}`, ErrorCode.TOOL_INVOCATION_FAILED, 500, { abilityName: this.options.abilityName, method });
+        }
+    }
+    /**
+     * Get list of available methods
+     *
+     * @returns Array of method names
+     *
+     * @example
+     * ```typescript
+     * const methods = transport.getMethods();
+     * console.log('Available methods:', methods);
+     * ```
+     */
+    getMethods() {
+        return [...this.methods];
+    }
+    /**
+     * Get schema for a specific method
+     *
+     * @param method - Method name
+     * @returns Method schema or undefined
+     *
+     * @example
+     * ```typescript
+     * const schema = transport.getMethodSchema('add');
+     * if (schema) {
+     *   console.log('Input schema:', schema.inputSchema);
+     * }
+     * ```
+     */
+    getMethodSchema(method) {
+        return this.schemas.get(method);
+    }
+    /**
+     * Read agent.json representation (only for KadiClient instances)
+     *
+     * Returns the agent.json representation from KadiClient.readAgentJson() if
+     * the loaded module is a KadiClient instance. Returns undefined for legacy modules.
+     *
+     * **What this returns:**
+     * - Runtime representation of the ability's agent.json file
+     * - Contains name, version, description, and tools (mapped from agent.json's 'exports')
+     * - Used for type generation during `kadi install`
+     *
+     * @returns agent.json representation or undefined
+     *
+     * @example
+     * ```typescript
+     * const agentJson = transport.readAgentJson();
+     * if (agentJson) {
+     *   console.log('Ability:', agentJson.name, agentJson.version);
+     *   console.log('Tools:', agentJson.tools.map(t => t.name));
+     *   // This represents what's in the ability's agent.json file
+     * }
+     * ```
+     */
+    readAgentJson() {
+        if (!this.isKadiClientInstance || !this.ability) {
+            return undefined;
+        }
+        return this.ability.readAgentJson();
+    }
+    /**
+     * Disconnect from the ability
+     *
+     * Cleans up resources and removes references.
+     *
+     * @example
+     * ```typescript
+     * await transport.disconnect();
+     * ```
+     */
+    async disconnect() {
+        if (!this.connected) {
+            return;
+        }
+        // Clean up
+        this.ability = null;
+        this.methods = [];
+        this.schemas.clear();
+        this.connected = false;
+        this.emit('disconnected');
+    }
+    /**
+     * Publish an event from the ability
+     *
+     * @param eventName - Event name
+     * @param data - Event data
+     *
+     * @example
+     * ```typescript
+     * transport.publishEvent('calculation.completed', { result: 42 });
+     * ```
+     */
+    publishEvent(eventName, data) {
+        this.emit('event', {
+            eventName,
+            data,
+            timestamp: Date.now(),
+            source: this.options.abilityName
+        });
+    }
+    /**
+     * Discover methods on the loaded ability
+     *
+     * Introspects the ability object to find callable methods.
+     * Excludes internal methods (starting with _) and special methods.
+     */
+    async discoverMethods() {
+        if (!this.ability || typeof this.ability !== 'object') {
+            return;
+        }
+        const excludedMethods = new Set([
+            'constructor',
+            'toString',
+            'toJSON',
+            'valueOf',
+            'hasOwnProperty',
+            'isPrototypeOf',
+            'propertyIsEnumerable'
+        ]);
+        // Get all property names (own and inherited)
+        const allProps = new Set();
+        // Own properties
+        for (const prop of Object.getOwnPropertyNames(this.ability)) {
+            allProps.add(prop);
+        }
+        // Prototype properties
+        let proto = Object.getPrototypeOf(this.ability);
+        while (proto && proto !== Object.prototype) {
+            for (const prop of Object.getOwnPropertyNames(proto)) {
+                allProps.add(prop);
+            }
+            proto = Object.getPrototypeOf(proto);
+        }
+        // Filter to functions, exclude internal methods
+        for (const prop of allProps) {
+            if (excludedMethods.has(prop)) {
+                continue;
+            }
+            if (prop.startsWith('_')) {
+                continue; // Internal method
+            }
+            try {
+                const value = this.ability[prop];
+                if (typeof value === 'function') {
+                    this.methods.push(prop);
+                    // Try to get schema if available
+                    const schemaGetter = this.ability[`${prop}Schema`];
+                    if (typeof schemaGetter === 'function') {
+                        const schema = schemaGetter.call(this.ability);
+                        if (schema) {
+                            this.schemas.set(prop, schema);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Skip properties that throw on access
+            }
+        }
+    }
+}
+//# sourceMappingURL=NativeTransport.js.map

package/dist/transports/NativeTransport.js.map

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

package/dist/transports/StdioTransport.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Stdio Transport
+ *
+ * Spawns abilities as child processes and communicates via stdin/stdout
+ * using Content-Length framed JSON-RPC messages (LSP-style).
+ *
+ * @module transports/StdioTransport
+ */
+import { EventEmitter } from 'events';
+import type { AbilityTransport, MethodSchema } from '../types/index.js';
+import type { AgentJson } from '../abilities/types.js';
+/**
+ * Stdio Transport Options
+ */
+export interface StdioTransportOptions {
+    /** Ability name (for error messages) */
+    abilityName: string;
+    /** Command to execute (e.g., 'node', 'python') */
+    command: string;
+    /** Command arguments (e.g., ['./ability.js']) */
+    args?: string[];
+    /** Working directory for child process */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Ability version */
+    abilityVersion?: string;
+}
+/**
+ * Stdio Transport
+ *
+ * Spawns an ability as a child process and communicates via JSON-RPC
+ * over stdin/stdout using Content-Length framing (LSP-style).
+ *
+ * **Features**:
+ * - Spawns child process with configurable command/args
+ * - Content-Length framed messages (reliable even with logs)
+ * - Captures stderr separately (ability logs)
+ * - Request/response matching via JSON-RPC ids
+ * - Timeout handling per request
+ * - Graceful shutdown with SIGTERM
+ *
+ * @example
+ * ```typescript
+ * const transport = new StdioTransport({
+ *   abilityName: 'calculator',
+ *   command: 'node',
+ *   args: ['./abilities/calculator/index.js']
+ * });
+ *
+ * await transport.connect();
+ * const result = await transport.invoke('add', { a: 5, b: 3 });
+ * console.log(result); // { result: 8 }
+ * await transport.disconnect();
+ * ```
+ */
+export declare class StdioTransport extends EventEmitter implements AbilityTransport {
+    /**
+     * Transport configuration
+     */
+    private readonly options;
+    /**
+     * Child process instance
+     */
+    private process?;
+    /**
+     * Message reader for stdout
+     */
+    private reader?;
+    /**
+     * Message writer for stdin
+     */
+    private writer?;
+    /**
+     * Stderr buffer
+     */
+    private stderrBuffer;
+    /**
+     * Whether transport is connected
+     */
+    private connected;
+    /**
+     * Whether we're intentionally disconnecting
+     */
+    private disconnecting;
+    /**
+     * Discovered methods
+     */
+    private methods;
+    /**
+     * Method schemas
+     */
+    private schemas;
+    /**
+     * Agent.json representation (from readAgentJson)
+     */
+    private agentJson?;
+    /**
+     * Request ID counter
+     */
+    private requestIdCounter;
+    /**
+     * Pending requests (waiting for responses)
+     */
+    private pendingRequests;
+    /**
+     * Create a new StdioTransport
+     *
+     * @param options - Transport options
+     */
+    constructor(options: StdioTransportOptions);
+    /**
+     * Connect to the ability
+     *
+     * Spawns the child process, sets up stdio communication,
+     * and performs discovery via readAgentJson.
+     *
+     * @throws {KadiError} If spawn fails or discovery fails
+     *
+     * @example
+     * ```typescript
+     * await transport.connect();
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Invoke a method on the ability
+     *
+     * @template TInput - Input parameter type
+     * @template TOutput - Return type
+     *
+     * @param method - Method name
+     * @param params - Method parameters
+     * @returns Promise resolving to method result
+     *
+     * @throws {KadiError} If method doesn't exist or invocation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await transport.invoke<{ a: number; b: number }, { result: number }>(
+     *   'add',
+     *   { a: 5, b: 3 }
+     * );
+     * ```
+     */
+    invoke<TInput = unknown, TOutput = unknown>(method: string, params: TInput): Promise<TOutput>;
+    /**
+     * Send a JSON-RPC request and wait for response
+     *
+     * @param method - JSON-RPC method name
+     * @param params - Request parameters
+     * @returns Promise resolving to response result
+     *
+     * @throws {KadiError} If request fails or times out
+     */
+    private sendRequest;
+    /**
+     * Handle incoming JSON-RPC message
+     *
+     * Matches responses to pending requests via id.
+     *
+     * @param message - Incoming message
+     */
+    private handleMessage;
+    /**
+     * Get list of available methods
+     *
+     * @returns Array of method names
+     *
+     * @example
+     * ```typescript
+     * const methods = transport.getMethods();
+     * console.log('Available methods:', methods);
+     * ```
+     */
+    getMethods(): string[];
+    /**
+     * Get schema for a specific method
+     *
+     * @param method - Method name
+     * @returns Method schema or undefined
+     *
+     * @example
+     * ```typescript
+     * const schema = transport.getMethodSchema('add');
+     * if (schema) {
+     *   console.log('Input schema:', schema.inputSchema);
+     * }
+     * ```
+     */
+    getMethodSchema(method: string): MethodSchema | undefined;
+    /**
+     * Read agent.json representation
+     *
+     * Returns the agent.json representation retrieved during connection.
+     *
+     * @returns agent.json representation or undefined
+     *
+     * @example
+     * ```typescript
+     * const agentJson = transport.readAgentJson();
+     * if (agentJson) {
+     *   console.log('Ability:', agentJson.name, agentJson.version);
+     *   console.log('Tools:', agentJson.tools.map(t => t.name));
+     * }
+     * ```
+     */
+    readAgentJson(): AgentJson | undefined;
+    /**
+     * Get captured stderr output
+     *
+     * Returns all stderr output captured from the child process.
+     * Useful for debugging or viewing ability logs.
+     *
+     * @returns Stderr content as string
+     *
+     * @example
+     * ```typescript
+     * const stderr = transport.getStderr();
+     * console.log('Ability logs:', stderr);
+     * ```
+     */
+    getStderr(): string;
+    /**
+     * Disconnect from the ability
+     *
+     * Kills the child process with SIGTERM and cleans up resources.
+     *
+     * @example
+     * ```typescript
+     * await transport.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Publish an event from the ability
+     *
+     * @param eventName - Event name
+     * @param data - Event data
+     *
+     * @example
+     * ```typescript
+     * transport.publishEvent('calculation.completed', { result: 42 });
+     * ```
+     */
+    publishEvent(eventName: string, data: unknown): void;
+}
+//# sourceMappingURL=StdioTransport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StdioTransport.d.ts","sourceRoot":"","sources":["../../src/transports/StdioTransport.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAI3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IAEpB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAEhB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,sBAAsB;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,cAAe,SAAQ,YAAa,YAAW,gBAAgB;IAC1E;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAItB;IAEF;;OAEG;IACH,OAAO,CAAC,OAAO,CAAC,CAAe;IAE/B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,CAAqB;IAEpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,CAAqB;IAEpC;;OAEG;IACH,OAAO,CAAC,YAAY,CAAmB;IAEvC;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO,CAAC,aAAa,CAAS;IAE9B;;OAEG;IACH,OAAO,CAAC,OAAO,CAAgB;IAE/B;;OAEG;IACH,OAAO,CAAC,OAAO,CAAmC;IAElD;;OAEG;IACH,OAAO,CAAC,SAAS,CAAC,CAAY;IAE9B;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAAK;IAE7B;;OAEG;IACH,OAAO,CAAC,eAAe,CAAqC;IAE5D;;;;OAIG;gBACS,OAAO,EAAE,qBAAqB;IAc1C;;;;;;;;;;;;OAYG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmK9B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC9C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IA6BnB;;;;;;;;OAQG;YACW,WAAW;IAoDzB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAmCrB;;;;;;;;;;OAUG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIzD;;;;;;;;;;;;;;;OAeG;IACH,aAAa,IAAI,SAAS,GAAG,SAAS;IAItC;;;;;;;;;;;;;OAaG;IACH,SAAS,IAAI,MAAM;IAInB;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6DjC;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;CAQrD"}