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

package/dist/transports/StdioTransport.js

@@ -1,36 +1,42 @@
 /**
  * Stdio Transport
  *
- * Communicates with abilities running as child processes via stdin/stdout.
- * Enables using abilities written in any language that supports JSON over stdio.
+ * 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 { spawn } from 'child_process';
-import { StdioMessageType } from '../types/index.js';
 import { KadiError, ErrorCode } from '../types/index.js';
-/**
- * Message ID counter
- */
-let messageIdCounter = 0;
+import { StdioMessageReader } from '../utils/StdioMessageReader.js';
+import { StdioMessageWriter } from '../utils/StdioMessageWriter.js';
 /**
  * Stdio Transport
  *
- * Spawns a child process and communicates via JSON messages over stdin/stdout.
- * Uses length-prefixed framing for reliable message boundaries.
+ * 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: 'python-calculator',
- *   abilityPath: '/path/to/calculator',
- *   command: 'python3',
- *   args: ['main.py']
+ *   abilityName: 'calculator',
+ *   command: 'node',
+ *   args: ['./abilities/calculator/index.js']
  * });
  *
  * await transport.connect();
- * const result = await transport.invoke('calculate', { expr: '2 + 2' });
+ * const result = await transport.invoke('add', { a: 5, b: 3 });
+ * console.log(result); // { result: 8 }
+ * await transport.disconnect();
  * ```
  */
 export class StdioTransport extends EventEmitter {
@@ -41,7 +47,27 @@ export class StdioTransport extends EventEmitter {
     /**
      * Child process instance
      */
-    process = null;
+    process;
+    /**
+     * Message reader for stdout
+     */
+    reader;
+    /**
+     * Message writer for stdin
+     */
+    writer;
+    /**
+     * Stderr buffer
+     */
+    stderrBuffer = Buffer.alloc(0);
+    /**
+     * Whether transport is connected
+     */
+    connected = false;
+    /**
+     * Whether we're intentionally disconnecting
+     */
+    disconnecting = false;
     /**
      * Discovered methods
      */
@@ -51,46 +77,45 @@ export class StdioTransport extends EventEmitter {
      */
     schemas = new Map();
     /**
-     * Whether transport is connected
+     * Agent.json representation (from readAgentJson)
      */
-    connected = false;
+    agentJson;
     /**
-     * Pending requests waiting for responses
+     * Request ID counter
      */
-    pendingRequests = new Map();
+    requestIdCounter = 0;
     /**
-     * Buffer for incomplete messages
+     * Pending requests (waiting for responses)
      */
-    buffer = Buffer.alloc(0);
+    pendingRequests = new Map();
     /**
      * Create a new StdioTransport
      *
-     * @param options - Stdio transport options
+     * @param options - Transport options
      */
     constructor(options) {
         super();
         this.options = {
-            command: options.command ?? 'node',
-            args: options.args ?? ['index.js'],
-            env: options.env ?? {},
-            cwd: options.cwd ?? options.abilityPath,
-            timeout: options.timeout ?? 30000,
-            abilityPath: options.abilityPath,
             abilityName: options.abilityName,
+            command: options.command,
+            args: options.args,
+            cwd: options.cwd,
+            env: options.env,
+            timeout: options.timeout ?? 30000,
             abilityVersion: options.abilityVersion ?? '1.0.0'
         };
     }
     /**
      * Connect to the ability
      *
-     * Spawns the child process and performs method discovery.
+     * Spawns the child process, sets up stdio communication,
+     * and performs discovery via readAgentJson.
      *
-     * @throws {KadiError} If process fails to start or discovery fails
+     * @throws {KadiError} If spawn fails or discovery fails
      *
      * @example
      * ```typescript
      * await transport.connect();
-     * console.log('Process started');
      * ```
      */
     async connect() {
@@ -98,44 +123,105 @@ export class StdioTransport extends EventEmitter {
             return;
         }
         try {
-            // Spawn the child process
-            this.process = spawn(this.options.command, this.options.args, {
+            // Spawn child process
+            this.process = spawn(this.options.command, this.options.args ?? [], {
+                stdio: ['pipe', 'pipe', 'pipe'], // stdin, stdout, stderr
                 cwd: this.options.cwd,
                 env: {
                     ...process.env,
                     ...this.options.env
-                },
-                stdio: ['pipe', 'pipe', 'pipe']
+                }
             });
-            // Set up error handling
-            this.process.on('error', (error) => {
-                this.handleProcessError(error);
+            // Setup message reader for stdout
+            this.reader = new StdioMessageReader();
+            this.reader.on('message', (message) => {
+                this.handleMessage(message);
             });
-            this.process.on('exit', (code, signal) => {
-                this.handleProcessExit(code, signal);
+            this.reader.on('error', (error) => {
+                this.emit('error', new KadiError(`Failed to parse message from ability: ${error.message}`, ErrorCode.STDIO_FRAMING_ERROR, 500, {
+                    abilityName: this.options.abilityName,
+                    error: error.message
+                }));
             });
-            // Set up stdout handling (receives messages)
+            // Setup message writer for stdin
+            if (!this.process.stdin) {
+                throw new KadiError('Child process stdin is not available', ErrorCode.STDIO_PROCESS_FAILED, 500, { abilityName: this.options.abilityName });
+            }
+            this.writer = new StdioMessageWriter(this.process.stdin);
+            // Capture stdout data
             if (this.process.stdout) {
-                this.process.stdout.on('data', (data) => {
-                    this.handleData(data);
+                this.process.stdout.on('data', (chunk) => {
+                    this.reader?.onData(chunk);
                 });
             }
-            // Set up stderr handling (for debugging)
+            // Capture stderr
             if (this.process.stderr) {
-                this.process.stderr.on('data', (data) => {
-                    console.error(`[${this.options.abilityName}] stderr:`, data.toString());
+                this.process.stderr.on('data', (chunk) => {
+                    this.stderrBuffer = Buffer.concat([this.stderrBuffer, chunk]);
                 });
             }
-            // Perform discovery
-            await this.discoverMethods();
+            // Handle process exit
+            this.process.on('exit', (code, signal) => {
+                // Only treat as error if:
+                // 1. We're not intentionally disconnecting AND
+                // 2. Exit code is non-zero (error exit)
+                //
+                // Note: We don't treat code=0 as error even if connected, because
+                // the process may exit cleanly during cleanup
+                const isUnexpectedExit = !this.disconnecting && code !== 0;
+                if (isUnexpectedExit) {
+                    const error = new KadiError(`Ability process exited unexpectedly (code: ${code}, signal: ${signal})`, ErrorCode.STDIO_PROCESS_EXITED, 500, {
+                        abilityName: this.options.abilityName,
+                        exitCode: code,
+                        signal,
+                        stderr: this.getStderr()
+                    });
+                    // Reject all pending requests
+                    for (const pending of this.pendingRequests.values()) {
+                        clearTimeout(pending.timeout);
+                        pending.reject(error);
+                    }
+                    this.pendingRequests.clear();
+                    this.emit('error', error);
+                }
+                this.connected = false;
+            });
+            // Handle process errors
+            this.process.on('error', (error) => {
+                const kadiError = new KadiError(`Failed to spawn ability process: ${error.message}`, ErrorCode.STDIO_PROCESS_FAILED, 500, {
+                    abilityName: this.options.abilityName,
+                    command: this.options.command,
+                    args: this.options.args,
+                    error: error.message
+                });
+                this.emit('error', kadiError);
+                throw kadiError;
+            });
+            // Perform discovery via readAgentJson
+            this.agentJson = await this.sendRequest('readAgentJson', {});
+            // Extract methods from agent.json
+            this.methods = this.agentJson.tools.map(tool => tool.name);
+            // Store schemas
+            for (const tool of this.agentJson.tools) {
+                if (tool.inputSchema || tool.outputSchema) {
+                    this.schemas.set(tool.name, {
+                        inputSchema: tool.inputSchema,
+                        outputSchema: tool.outputSchema,
+                        description: tool.description
+                    });
+                }
+            }
             this.connected = true;
             this.emit('connected');
         }
         catch (error) {
-            this.cleanup();
+            // Cleanup on connection failure
+            if (this.process) {
+                this.process.kill('SIGTERM');
+            }
             const kadiError = error instanceof KadiError
                 ? error
-                : new KadiError(`Failed to start process: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.STDIO_PROCESS_FAILED, 500, {
+                : new KadiError(`Failed to connect to ability: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.ABILITY_LOAD_FAILED, 500, {
                     abilityName: this.options.abilityName,
                     command: this.options.command,
                     args: this.options.args,
@@ -159,41 +245,112 @@ export class StdioTransport extends EventEmitter {
      *
      * @example
      * ```typescript
-     * const result = await transport.invoke('add', { a: 5, b: 3 });
+     * const result = await transport.invoke<{ a: number; b: number }, { result: number }>(
+     *   'add',
+     *   { a: 5, b: 3 }
+     * );
      * ```
      */
     async invoke(method, params) {
-        if (!this.connected || !this.process) {
+        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 });
         }
-        const messageId = ++messageIdCounter;
-        return new Promise((resolve, reject) => {
+        // Send invoke request via JSON-RPC
+        const result = await this.sendRequest('invoke', {
+            toolName: method,
+            toolInput: params
+        });
+        return result;
+    }
+    /**
+     * 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
+     */
+    async sendRequest(method, params) {
+        if (!this.writer) {
+            throw new KadiError('Writer not initialized', ErrorCode.TRANSPORT_SEND_FAILED, 500, { abilityName: this.options.abilityName });
+        }
+        // Generate unique request ID
+        const id = ++this.requestIdCounter;
+        // Create promise for response
+        const responsePromise = new Promise((resolve, reject) => {
+            // Setup timeout
             const timeout = setTimeout(() => {
-                this.pendingRequests.delete(messageId);
-                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.pendingRequests.delete(id);
+                reject(new KadiError(`Request timeout after ${this.options.timeout}ms`, ErrorCode.TOOL_TIMEOUT, 408, {
+                    abilityName: this.options.abilityName,
+                    method,
+                    timeout: this.options.timeout
+                }));
             }, this.options.timeout);
-            this.pendingRequests.set(messageId, {
+            // Store pending request (cast resolve to match unknown type)
+            this.pendingRequests.set(id, {
                 resolve: resolve,
                 reject,
                 timeout
             });
-            // Send invoke message
-            this.sendMessage({
-                type: StdioMessageType.INVOKE,
-                id: messageId,
-                method,
-                params
-            });
         });
+        // Send JSON-RPC request
+        await this.writer.write({
+            jsonrpc: '2.0',
+            id,
+            method,
+            params
+        });
+        return responsePromise;
+    }
+    /**
+     * Handle incoming JSON-RPC message
+     *
+     * Matches responses to pending requests via id.
+     *
+     * @param message - Incoming message
+     */
+    handleMessage(message) {
+        const { id, result, error } = message;
+        if (typeof id !== 'number') {
+            // Not a response (or malformed)
+            return;
+        }
+        const pending = this.pendingRequests.get(id);
+        if (!pending) {
+            // Response for unknown request (may have timed out)
+            return;
+        }
+        // Clear timeout
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(id);
+        // Resolve or reject based on response
+        if (error) {
+            const errorObj = error;
+            pending.reject(new KadiError(errorObj.message || 'Request failed', ErrorCode.TOOL_INVOCATION_FAILED, errorObj.code || 500, {
+                abilityName: this.options.abilityName,
+                ...(errorObj.data && typeof errorObj.data === 'object' ? errorObj.data : {})
+            }));
+        }
+        else {
+            pending.resolve(result);
+        }
     }
     /**
      * 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];
@@ -203,208 +360,128 @@ export class StdioTransport extends EventEmitter {
      *
      * @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);
     }
     /**
-     * Disconnect from the ability
+     * Read agent.json representation
+     *
+     * Returns the agent.json representation retrieved during connection.
      *
-     * Terminates the child process and cleans up resources.
+     * @returns agent.json representation or undefined
      *
      * @example
      * ```typescript
-     * await transport.disconnect();
+     * const agentJson = transport.readAgentJson();
+     * if (agentJson) {
+     *   console.log('Ability:', agentJson.name, agentJson.version);
+     *   console.log('Tools:', agentJson.tools.map(t => t.name));
+     * }
      * ```
      */
-    async disconnect() {
-        if (!this.connected) {
-            return;
-        }
-        this.cleanup();
-        this.emit('disconnected');
+    readAgentJson() {
+        return this.agentJson;
     }
     /**
-     * Publish an event from the ability
+     * Get captured stderr output
      *
-     * @param eventName - Event name
-     * @param data - Event data
-     */
-    publishEvent(eventName, data) {
-        this.emit('event', {
-            eventName,
-            data,
-            timestamp: Date.now(),
-            source: this.options.abilityName
-        });
-    }
-    /**
-     * Discover methods by sending discovery request
-     */
-    async discoverMethods() {
-        if (!this.process) {
-            throw new KadiError('Process not started', ErrorCode.STDIO_PROCESS_FAILED, 500, { abilityName: this.options.abilityName });
-        }
-        const messageId = ++messageIdCounter;
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                this.pendingRequests.delete(messageId);
-                reject(new KadiError('Discovery timeout', ErrorCode.CONNECTION_TIMEOUT, 408, { abilityName: this.options.abilityName }));
-            }, this.options.timeout);
-            this.pendingRequests.set(messageId, {
-                resolve: (result) => {
-                    const discovery = result;
-                    this.methods = discovery.methods;
-                    if (discovery.schemas) {
-                        for (const [method, schema] of Object.entries(discovery.schemas)) {
-                            this.schemas.set(method, schema);
-                        }
-                    }
-                    resolve();
-                },
-                reject,
-                timeout
-            });
-            // Send discovery message
-            this.sendMessage({
-                type: StdioMessageType.DISCOVER,
-                id: messageId
-            });
-        });
-    }
-    /**
-     * Send a message to the child process
+     * Returns all stderr output captured from the child process.
+     * Useful for debugging or viewing ability logs.
      *
-     * Uses length-prefixed framing: [length:4 bytes][json message]
+     * @returns Stderr content as string
      *
-     * @param message - Message to send
+     * @example
+     * ```typescript
+     * const stderr = transport.getStderr();
+     * console.log('Ability logs:', stderr);
+     * ```
      */
-    sendMessage(message) {
-        if (!this.process || !this.process.stdin) {
-            throw new KadiError('Process stdin not available', ErrorCode.TRANSPORT_SEND_FAILED, 500, { abilityName: this.options.abilityName });
-        }
-        try {
-            const json = JSON.stringify(message);
-            const messageBuffer = Buffer.from(json, 'utf-8');
-            const lengthBuffer = Buffer.allocUnsafe(4);
-            lengthBuffer.writeUInt32BE(messageBuffer.length, 0);
-            // Write length prefix + message
-            this.process.stdin.write(lengthBuffer);
-            this.process.stdin.write(messageBuffer);
-        }
-        catch (error) {
-            throw new KadiError(`Failed to send message: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.TRANSPORT_SEND_FAILED, 500, { abilityName: this.options.abilityName });
-        }
+    getStderr() {
+        return this.stderrBuffer.toString('utf8');
     }
     /**
-     * Handle incoming data from stdout
+     * Disconnect from the ability
      *
-     * Implements length-prefixed framing to extract complete messages.
+     * Kills the child process with SIGTERM and cleans up resources.
      *
-     * @param data - Raw data from stdout
-     */
-    handleData(data) {
-        // Append to buffer
-        this.buffer = Buffer.concat([this.buffer, data]);
-        // Process complete messages
-        while (this.buffer.length >= 4) {
-            // Read message length (4 bytes, big-endian)
-            const messageLength = this.buffer.readUInt32BE(0);
-            // Check if we have the complete message
-            if (this.buffer.length < 4 + messageLength) {
-                break; // Wait for more data
-            }
-            // Extract message
-            const messageBuffer = this.buffer.subarray(4, 4 + messageLength);
-            this.buffer = this.buffer.subarray(4 + messageLength);
-            // Parse and handle message
-            try {
-                const message = JSON.parse(messageBuffer.toString('utf-8'));
-                this.handleMessage(message);
-            }
-            catch (error) {
-                this.emit('error', new KadiError(`Failed to parse message: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.STDIO_FRAMING_ERROR, 400, { abilityName: this.options.abilityName }));
-            }
-        }
-    }
-    /**
-     * Handle a parsed message
-     *
-     * @param message - Parsed message object
+     * @example
+     * ```typescript
+     * await transport.disconnect();
+     * ```
      */
-    handleMessage(message) {
-        // Handle result messages
-        if (message.type === StdioMessageType.RESULT && message.id !== undefined) {
-            const pending = this.pendingRequests.get(message.id);
-            if (pending) {
-                clearTimeout(pending.timeout);
-                this.pendingRequests.delete(message.id);
-                pending.resolve(message.result);
-            }
-            return;
-        }
-        // Handle error messages
-        if (message.type === StdioMessageType.ERROR && message.id !== undefined) {
-            const pending = this.pendingRequests.get(message.id);
-            if (pending) {
-                clearTimeout(pending.timeout);
-                this.pendingRequests.delete(message.id);
-                pending.reject(new KadiError(String(message.error ?? 'Unknown error'), ErrorCode.TOOL_INVOCATION_FAILED, 500, { abilityName: this.options.abilityName }));
-            }
-            return;
-        }
-        // Handle event messages
-        if (message.type === StdioMessageType.EVENT) {
-            this.emit('event', message.data);
+    async disconnect() {
+        if (!this.connected) {
             return;
         }
-        // Unknown message type
-        console.warn(`Unknown message type: ${message.type}`, message);
-    }
-    /**
-     * Handle process error
-     *
-     * @param error - Error from child process
-     */
-    handleProcessError(error) {
-        this.emit('error', new KadiError(`Process error: ${error.message}`, ErrorCode.STDIO_PROCESS_FAILED, 500, { abilityName: this.options.abilityName, originalError: error.message }));
-        this.cleanup();
-    }
-    /**
-     * Handle process exit
-     *
-     * @param code - Exit code
-     * @param signal - Exit signal
-     */
-    handleProcessExit(code, signal) {
-        if (this.connected) {
-            this.emit('error', new KadiError(`Process exited unexpectedly`, ErrorCode.STDIO_PROCESS_EXITED, 500, { abilityName: this.options.abilityName, exitCode: code, signal }));
-        }
-        this.cleanup();
-    }
-    /**
-     * Cleanup resources
-     */
-    cleanup() {
+        // Mark as intentionally disconnecting
+        this.disconnecting = true;
         // Reject all pending requests
-        for (const [_id, pending] of this.pendingRequests) {
+        for (const pending of this.pendingRequests.values()) {
             clearTimeout(pending.timeout);
-            pending.reject(new KadiError('Process terminated', ErrorCode.STDIO_PROCESS_EXITED, 503, { abilityName: this.options.abilityName }));
+            pending.reject(new KadiError('Transport disconnected', ErrorCode.TRANSPORT_NOT_CONNECTED, 503, { abilityName: this.options.abilityName }));
         }
         this.pendingRequests.clear();
-        // Kill process if running
+        // Cleanup reader/writer
+        this.reader?.destroy();
+        this.writer?.destroy();
+        // Kill child process
         if (this.process) {
-            if (!this.process.killed) {
-                this.process.kill();
-            }
-            this.process.removeAllListeners();
-            this.process = null;
+            this.process.kill('SIGTERM');
+            // Wait briefly for graceful exit
+            await new Promise((resolve) => {
+                if (!this.process) {
+                    resolve();
+                    return;
+                }
+                const timeout = setTimeout(() => {
+                    // Force kill if not exited
+                    this.process?.kill('SIGKILL');
+                    resolve();
+                }, 5000);
+                this.process.once('exit', () => {
+                    clearTimeout(timeout);
+                    resolve();
+                });
+            });
         }
         // Clear state
-        this.buffer = Buffer.alloc(0);
+        this.process = undefined;
+        this.reader = undefined;
+        this.writer = undefined;
         this.methods = [];
         this.schemas.clear();
+        this.agentJson = undefined;
         this.connected = false;
+        this.disconnecting = 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
+        });
     }
 }
 //# sourceMappingURL=StdioTransport.js.map