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

package/dist/transports/StdioTransport.d.ts

@@ -1,30 +1,59 @@
 /**
  * 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 type { AbilityTransport, StdioTransportOptions, MethodSchema } from '../types/index.js';
+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 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 declare class StdioTransport extends EventEmitter implements AbilityTransport {
@@ -35,7 +64,27 @@ export declare class StdioTransport extends EventEmitter implements AbilityTrans
     /**
      * Child process instance
      */
-    private process;
+    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
      */
@@ -45,34 +94,34 @@ export declare class StdioTransport extends EventEmitter implements AbilityTrans
      */
     private schemas;
     /**
-     * Whether transport is connected
+     * Agent.json representation (from readAgentJson)
      */
-    private connected;
+    private agentJson?;
     /**
-     * Pending requests waiting for responses
+     * Request ID counter
      */
-    private pendingRequests;
+    private requestIdCounter;
     /**
-     * Buffer for incomplete messages
+     * Pending requests (waiting for responses)
      */
-    private buffer;
+    private pendingRequests;
     /**
      * Create a new StdioTransport
      *
-     * @param options - Stdio transport options
+     * @param options - Transport options
      */
     constructor(options: StdioTransportOptions);
     /**
      * 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');
      * ```
      */
     connect(): Promise<void>;
@@ -90,14 +139,41 @@ export declare class StdioTransport extends EventEmitter implements AbilityTrans
      *
      * @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 }
+     * );
      * ```
      */
     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[];
     /**
@@ -105,68 +181,70 @@ export declare class StdioTransport extends EventEmitter implements AbilityTrans
      *
      * @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;
     /**
-     * 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));
+     * }
      * ```
      */
-    disconnect(): Promise<void>;
+    readAgentJson(): AgentJson | undefined;
     /**
-     * Publish an event from the ability
+     * Get captured stderr output
      *
-     * @param eventName - Event name
-     * @param data - Event data
-     */
-    publishEvent(eventName: string, data: unknown): void;
-    /**
-     * Discover methods by sending discovery request
-     */
-    private discoverMethods;
-    /**
-     * 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);
+     * ```
      */
-    private sendMessage;
+    getStderr(): string;
     /**
-     * Handle incoming data from stdout
-     *
-     * Implements length-prefixed framing to extract complete messages.
+     * Disconnect from the ability
      *
-     * @param data - Raw data from stdout
-     */
-    private handleData;
-    /**
-     * Handle a parsed message
+     * Kills the child process with SIGTERM and cleans up resources.
      *
-     * @param message - Parsed message object
+     * @example
+     * ```typescript
+     * await transport.disconnect();
+     * ```
      */
-    private handleMessage;
+    disconnect(): Promise<void>;
     /**
-     * Handle process error
+     * Publish an event from the ability
      *
-     * @param error - Error from child process
-     */
-    private handleProcessError;
-    /**
-     * Handle process exit
+     * @param eventName - Event name
+     * @param data - Event data
      *
-     * @param code - Exit code
-     * @param signal - Exit signal
-     */
-    private handleProcessExit;
-    /**
-     * Cleanup resources
+     * @example
+     * ```typescript
+     * transport.publishEvent('calculation.completed', { result: 42 });
+     * ```
      */
-    private cleanup;
+    publishEvent(eventName: string, data: unknown): void;
 }
 //# sourceMappingURL=StdioTransport.d.ts.map

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

@@ -1 +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,qBAAqB,EACrB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAkB3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAe,SAAQ,YAAa,YAAW,gBAAgB;IAC1E;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D;;OAEG;IACH,OAAO,CAAC,OAAO,CAA6B;IAE5C;;OAEG;IACH,OAAO,CAAC,OAAO,CAAgB;IAE/B;;OAEG;IACH,OAAO,CAAC,OAAO,CAAmC;IAElD;;OAEG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;OAEG;IACH,OAAO,CAAC,eAAe,CAAmD;IAE1E;;OAEG;IACH,OAAO,CAAC,MAAM,CAAmB;IAEjC;;;;OAIG;gBACS,OAAO,EAAE,qBAAqB;IAc1C;;;;;;;;;;;;OAYG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE9B;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC9C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAiDnB;;;;OAIG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIzD;;;;;;;;;OASG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IASpD;;OAEG;YACW,eAAe;IAgD7B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IA8BnB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAiClB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAsCrB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,OAAO;CA4BhB"}
+{"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"}