@kadi.build/core 0.3.2 → 0.3.4

package/dist/client.d.ts

@@ -14,7 +14,7 @@
  * - Explicit over implicit (no proxy magic)
  * - Readable, traceable code flow
  */
-import type { ClientConfig, BrokerState, ToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, RequestContext, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
+import type { ClientConfig, BrokerState, ToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, ToolExecutionBridge, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
 /**
  * The main client for building KADI agents.
  *
@@ -112,33 +112,8 @@ export declare class KadiClient {
     private registerWithBroker;
     /**
      * Send a JSON-RPC request and wait for the response.
-     *
-     * Design: Returns the result directly (not the full JSON-RPC response).
-     *
-     * Why? The JSON-RPC envelope (jsonrpc, id) is transport metadata.
-     * Once we've matched the response to the pending request, that metadata
-     * has served its purpose. Callers care about the result, not the envelope.
-     *
-     * Errors are handled via Promise rejection in handleBrokerResponse,
-     * so by the time this resolves, we know it's a successful response.
-     *
-     * IMPORTANT: The type parameter T is NOT validated at runtime.
-     * It provides TypeScript type hints but the broker could return any shape.
-     * Callers MUST validate critical fields before using them.
-     *
-     * @template T - Expected type of the result (defaults to unknown for safety)
-     * @param state - Broker connection state
-     * @param request - JSON-RPC request to send
-     * @returns Promise resolving to the typed result
-     *
-     * @example
-     * ```typescript
-     * // Caller specifies expected result type
-     * const result = await this.sendRequest<{ nonce: string }>(state, helloMessage);
-     * // IMPORTANT: Validate before using - the type is not runtime-enforced
-     * if (!result.nonce) throw new Error('Missing nonce');
-     * console.log(result.nonce);
-     * ```
+     * Returns the result directly (not the JSON-RPC envelope).
+     * Note: Type parameter T is not validated at runtime.
      */
     private sendRequest;
     /**
@@ -152,30 +127,19 @@ export declare class KadiClient {
      * 1. Client sends kadi.ability.request → gets { status: 'pending', requestId }
      * 2. Provider executes tool and sends result back to broker
      * 3. Broker sends this notification with the actual result
-     *
-     * The notification contains:
-     * - requestId: matches what we got in step 1
-     * - result: the tool's return value (if successful)
-     * - error: error message (if failed)
      */
     private handleAbilityResponse;
+    /**
+     * Resolve or reject a pending invocation based on response content.
+     */
+    private resolveAbilityResponse;
+    /**
+     * Get a connected broker's state, throwing if not available.
+     */
+    private getConnectedBrokerState;
     /**
      * Handle kadi.event.delivery notification from broker.
-     *
-     * When an event is published to a channel that matches one of our subscribed
-     * patterns, the broker sends us this notification with the event data.
-     *
-     * Flow:
-     * 1. Some agent calls publish('user.login', data)
-     * 2. Broker routes to all subscribers matching 'user.*' or 'user.#' etc.
-     * 3. We receive this notification and dispatch to local handlers
-     *
-     * The notification params contain:
-     * - channel: The exact channel name (e.g., 'user.login')
-     * - data: The event payload
-     * - networkId: Which network the event was published to
-     * - source: Session ID of the publisher
-     * - timestamp: When the event was published
+     * Dispatches to local handlers matching the event channel.
      */
     private handleEventDelivery;
     /**
@@ -405,8 +369,6 @@ export declare class KadiClient {
      * ```
      */
     registerTool<TInput, TOutput>(definition: ZodToolDefinition<TInput, TOutput>, handler: ToolHandler<TInput, TOutput>, options?: RegisterToolOptions): void;
-    /**
-     */
     /**
      * Get tool definitions, optionally filtered for a specific broker.
      *
@@ -415,13 +377,33 @@ export declare class KadiClient {
      */
     private getToolDefinitions;
     /**
-     * Invoke a local tool by name.
+     * Execute a tool registered on this client.
+     *
+     * This is a PRIVATE method - not for external use.
+     * It handles INCOMING tool calls from:
+     * - Broker (when another agent calls your tools)
+     * - Stdio (when running as an ability)
+     * - Native transport (when loaded in-process)
      *
-     * @param toolName - Name of the tool to invoke
+     * To call tools on OTHER agents, use:
+     * - `loadBroker(name).invoke(tool, params)` - for repeated calls to the same agent
+     * - `invokeRemote(tool, params, { timeout })` - for one-off calls with custom timeout
+     *
+     * @param toolName - Name of the registered tool to execute
      * @param params - Input parameters for the tool
-     * @param context - Optional request context (provided when invoked via broker)
+     * @param context - Request context with caller info (provided by broker/stdio)
+     * @internal
+     */
+    private executeToolHandler;
+    /**
+     * Create a bridge for internal transport use.
+     *
+     * This allows native transport to call tools on this client without
+     * exposing the full client interface.
+     *
+     * @internal - Not for external use
      */
-    invoke(toolName: string, params: unknown, context?: RequestContext): Promise<unknown>;
+    createToolBridge(): ToolExecutionBridge;
     /**
      * Load an in-process ability via dynamic import.
      *

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -26,7 +26,7 @@ import { loadBrokerTransport } from './transports/broker.js';
 // CONSTANTS
 // ═══════════════════════════════════════════════════════════════
 const DEFAULT_HEARTBEAT_INTERVAL = 25000; // 25 seconds
-const DEFAULT_REQUEST_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_REQUEST_TIMEOUT = 600000; // 10 minutes
 const DEFAULT_AUTO_RECONNECT = true;
 const DEFAULT_MAX_RECONNECT_DELAY = 30000; // 30 seconds cap
 const RECONNECT_BASE_DELAY = 1000; // 1 second initial delay
@@ -424,33 +424,8 @@ export class KadiClient {
     }
     /**
      * Send a JSON-RPC request and wait for the response.
-     *
-     * Design: Returns the result directly (not the full JSON-RPC response).
-     *
-     * Why? The JSON-RPC envelope (jsonrpc, id) is transport metadata.
-     * Once we've matched the response to the pending request, that metadata
-     * has served its purpose. Callers care about the result, not the envelope.
-     *
-     * Errors are handled via Promise rejection in handleBrokerResponse,
-     * so by the time this resolves, we know it's a successful response.
-     *
-     * IMPORTANT: The type parameter T is NOT validated at runtime.
-     * It provides TypeScript type hints but the broker could return any shape.
-     * Callers MUST validate critical fields before using them.
-     *
-     * @template T - Expected type of the result (defaults to unknown for safety)
-     * @param state - Broker connection state
-     * @param request - JSON-RPC request to send
-     * @returns Promise resolving to the typed result
-     *
-     * @example
-     * ```typescript
-     * // Caller specifies expected result type
-     * const result = await this.sendRequest<{ nonce: string }>(state, helloMessage);
-     * // IMPORTANT: Validate before using - the type is not runtime-enforced
-     * if (!result.nonce) throw new Error('Missing nonce');
-     * console.log(result.nonce);
-     * ```
+     * Returns the result directly (not the JSON-RPC envelope).
+     * Note: Type parameter T is not validated at runtime.
      */
     sendRequest(state, request) {
         // Fail fast if WebSocket is not connected
@@ -528,66 +503,64 @@ export class KadiClient {
      * 1. Client sends kadi.ability.request → gets { status: 'pending', requestId }
      * 2. Provider executes tool and sends result back to broker
      * 3. Broker sends this notification with the actual result
-     *
-     * The notification contains:
-     * - requestId: matches what we got in step 1
-     * - result: the tool's return value (if successful)
-     * - error: error message (if failed)
      */
     handleAbilityResponse(state, notification) {
-        // The error field can be either a string or an object with code/message.
-        // We accept both forms and normalize for consistent error handling.
         const params = notification.params;
-        // Validate notification has requestId
         if (!params?.requestId) {
-            // Malformed notification - ignore
             return;
         }
-        // Find pending invocation
         const pending = state.pendingInvocations.get(params.requestId);
         if (!pending) {
-            // No one waiting for this - might be stale or already timed out
+            // No listener - response is orphaned (timed out or unknown requestId)
             return;
         }
-        // Clean up: remove from pending and clear timeout
         clearTimeout(pending.timeout);
         state.pendingInvocations.delete(params.requestId);
-        // Resolve or reject based on response content
-        if (params.error) {
-            // Normalize error - could be string or { code, message } object
-            const errorMessage = typeof params.error === 'string' ? params.error : params.error.message;
-            const errorCode = typeof params.error === 'object' ? params.error.code : undefined;
+        this.resolveAbilityResponse(pending, params, state.name);
+    }
+    /**
+     * Resolve or reject a pending invocation based on response content.
+     */
+    resolveAbilityResponse(pending, response, brokerName) {
+        if (response.error) {
+            const errorMessage = typeof response.error === 'string' ? response.error : response.error.message;
+            const errorCode = typeof response.error === 'object' ? response.error.code : undefined;
             pending.reject(new KadiError(`Tool "${pending.toolName}" failed: ${errorMessage}`, 'TOOL_INVOCATION_FAILED', {
                 toolName: pending.toolName,
-                requestId: params.requestId,
-                broker: state.name,
-                errorCode, // Include error code if available
+                broker: brokerName,
+                errorCode,
             }));
         }
         else {
-            pending.resolve(params.result);
+            pending.resolve(response.result);
         }
     }
+    /**
+     * Get a connected broker's state, throwing if not available.
+     */
+    getConnectedBrokerState(optionsBroker) {
+        const brokerName = optionsBroker ?? this.config.defaultBroker;
+        if (!brokerName) {
+            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
+                hint: 'Either specify a broker in options or set defaultBroker in config',
+            });
+        }
+        const state = this.brokers.get(brokerName);
+        if (!state || state.status !== 'connected') {
+            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
+                broker: brokerName,
+                status: state?.status ?? 'not found',
+                hint: 'Call client.connect() first',
+            });
+        }
+        return { state, brokerName };
+    }
     // ═══════════════════════════════════════════════════════════════
     // BROKER EVENTS (Pub/Sub)
     // ═══════════════════════════════════════════════════════════════
     /**
      * Handle kadi.event.delivery notification from broker.
-     *
-     * When an event is published to a channel that matches one of our subscribed
-     * patterns, the broker sends us this notification with the event data.
-     *
-     * Flow:
-     * 1. Some agent calls publish('user.login', data)
-     * 2. Broker routes to all subscribers matching 'user.*' or 'user.#' etc.
-     * 3. We receive this notification and dispatch to local handlers
-     *
-     * The notification params contain:
-     * - channel: The exact channel name (e.g., 'user.login')
-     * - data: The event payload
-     * - networkId: Which network the event was published to
-     * - source: Session ID of the publisher
-     * - timestamp: When the event was published
+     * Dispatches to local handlers matching the event channel.
      */
     handleEventDelivery(state, notification) {
         const params = notification.params;
@@ -706,22 +679,7 @@ export class KadiClient {
      * ```
      */
     async subscribe(pattern, handler, options = {}) {
-        // Resolve which broker to use
-        const brokerName = options.broker ?? this.config.defaultBroker;
-        if (!brokerName) {
-            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
-                hint: 'Either specify a broker in options or set defaultBroker in config',
-            });
-        }
-        // Get broker state
-        const state = this.brokers.get(brokerName);
-        if (!state || state.status !== 'connected') {
-            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
-                broker: brokerName,
-                status: state?.status ?? 'not found',
-                hint: 'Call client.connect() first',
-            });
-        }
+        const { state } = this.getConnectedBrokerState(options.broker);
         // Add handler to local tracking
         let handlers = state.eventHandlers.get(pattern);
         if (!handlers) {
@@ -817,22 +775,7 @@ export class KadiClient {
      * ```
      */
     async publish(channel, data, options = {}) {
-        // Resolve which broker to use
-        const brokerName = options.broker ?? this.config.defaultBroker;
-        if (!brokerName) {
-            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
-                hint: 'Either specify a broker in options or set defaultBroker in config',
-            });
-        }
-        // Get broker state
-        const state = this.brokers.get(brokerName);
-        if (!state || state.status !== 'connected') {
-            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
-                broker: brokerName,
-                status: state?.status ?? 'not found',
-                hint: 'Call client.connect() first',
-            });
-        }
+        const { state } = this.getConnectedBrokerState(options.broker);
         // Resolve which network to publish to
         const networkId = options.network ?? this.config.networks[0] ?? 'global';
         // Send publish request to broker
@@ -885,7 +828,7 @@ export class KadiClient {
      */
     async handleInvokeRequest(state, requestId, toolName, toolInput, context) {
         try {
-            const result = await this.invoke(toolName, toolInput, context);
+            const result = await this.executeToolHandler(toolName, toolInput, context);
             // Format response based on caller protocol
             let responseResult;
             if (context.callerProtocol === 'mcp') {
@@ -1269,8 +1212,6 @@ export class KadiClient {
         };
         this.tools.set(definition.name, registered);
     }
-    /**
-     */
     /**
      * Get tool definitions, optionally filtered for a specific broker.
      *
@@ -1292,13 +1233,24 @@ export class KadiClient {
             .map((t) => t.definition);
     }
     /**
-     * Invoke a local tool by name.
+     * Execute a tool registered on this client.
+     *
+     * This is a PRIVATE method - not for external use.
+     * It handles INCOMING tool calls from:
+     * - Broker (when another agent calls your tools)
+     * - Stdio (when running as an ability)
+     * - Native transport (when loaded in-process)
      *
-     * @param toolName - Name of the tool to invoke
+     * To call tools on OTHER agents, use:
+     * - `loadBroker(name).invoke(tool, params)` - for repeated calls to the same agent
+     * - `invokeRemote(tool, params, { timeout })` - for one-off calls with custom timeout
+     *
+     * @param toolName - Name of the registered tool to execute
      * @param params - Input parameters for the tool
-     * @param context - Optional request context (provided when invoked via broker)
+     * @param context - Request context with caller info (provided by broker/stdio)
+     * @internal
      */
-    async invoke(toolName, params, context) {
+    async executeToolHandler(toolName, params, context) {
         const tool = this.tools.get(toolName);
         if (!tool) {
             throw new KadiError(`Tool "${toolName}" not found`, 'TOOL_NOT_FOUND', {
@@ -1307,8 +1259,26 @@ export class KadiClient {
                 hint: 'Register the tool first with registerTool()',
             });
         }
+        // TODO: Validate params against tool.definition.input schema before invoking.
+        // Currently the schema is only used for discovery (kadi.ability.list) and TypeScript types.
+        // Tool handlers must do their own validation, which defeats the purpose of requiring a schema.
+        // Should call tool.definition.input.safeParse(params) and throw on validation errors.
         return tool.handler(params, context);
     }
+    /**
+     * Create a bridge for internal transport use.
+     *
+     * This allows native transport to call tools on this client without
+     * exposing the full client interface.
+     *
+     * @internal - Not for external use
+     */
+    createToolBridge() {
+        return {
+            executeToolHandler: (toolName, params, context) => this.executeToolHandler(toolName, params, context),
+            getRegisteredTools: () => Array.from(this.tools.values()).map((t) => t.definition),
+        };
+    }
     // ─────────────────────────────────────────────────────────────
     // ABILITY LOADING
     // ─────────────────────────────────────────────────────────────
@@ -1339,7 +1309,9 @@ export class KadiClient {
             path = entry.absolutePath;
             entrypoint = entry.entrypoint;
         }
-        return loadNativeTransport(path, entrypoint);
+        return loadNativeTransport(path, entrypoint, {
+            timeout: options.timeout ?? this.config.requestTimeout,
+        });
     }
     /**
      * Load a child process ability via stdio.
@@ -1376,7 +1348,7 @@ export class KadiClient {
         // ─────────────────────────────────────────────────────────────────────────
         if (options.command) {
             return loadStdioTransport(options.command, options.args ?? [], {
-                timeoutMs: this.config.requestTimeout,
+                timeoutMs: options.timeout ?? this.config.requestTimeout,
             });
         }
         // ─────────────────────────────────────────────────────────────────────────
@@ -1384,7 +1356,7 @@ export class KadiClient {
         // ─────────────────────────────────────────────────────────────────────────
         const { command, args, cwd } = await resolveAbilityScript(name, options.script ?? 'start', options.projectRoot);
         return loadStdioTransport(command, args, {
-            timeoutMs: this.config.requestTimeout,
+            timeoutMs: options.timeout ?? this.config.requestTimeout,
             cwd, // Run in ability's directory so relative paths work
         });
     }
@@ -1404,22 +1376,10 @@ export class KadiClient {
      * ```
      */
     async loadBroker(name, options = {}) {
-        const brokerName = options.broker ?? this.config.defaultBroker;
-        if (!brokerName) {
-            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
-                hint: 'Either specify a broker in options or set defaultBroker in config',
-            });
-        }
-        const state = this.brokers.get(brokerName);
-        if (!state || state.status !== 'connected') {
-            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
-                broker: brokerName,
-                hint: 'Call client.connect() first',
-            });
-        }
+        const { state, brokerName } = this.getConnectedBrokerState(options.broker);
         return loadBrokerTransport(name, {
             broker: state,
-            requestTimeout: this.config.requestTimeout,
+            requestTimeout: options.timeout ?? this.config.requestTimeout,
             networks: options.networks,
             // Provide subscribe/unsubscribe for ability.on()/off() support
             subscribe: (pattern, handler) => this.subscribe(pattern, handler, { broker: brokerName }),
@@ -1454,49 +1414,17 @@ export class KadiClient {
      * ```
      */
     async invokeRemote(toolName, params, options = {}) {
-        // ─────────────────────────────────────────────────────────────
-        // VALIDATION
-        // ─────────────────────────────────────────────────────────────
-        const brokerName = options.broker ?? this.config.defaultBroker;
-        if (!brokerName) {
-            throw new KadiError('No broker specified and no defaultBroker configured', 'INVALID_CONFIG', {
-                hint: 'Either specify a broker in options or set defaultBroker in config',
-            });
-        }
-        const state = this.brokers.get(brokerName);
-        if (!state || state.status !== 'connected') {
-            throw new KadiError(`Broker "${brokerName}" is not connected`, 'BROKER_NOT_CONNECTED', {
-                broker: brokerName,
-                hint: 'Call client.connect() first',
-            });
-        }
+        const { state, brokerName } = this.getConnectedBrokerState(options.broker);
         const timeout = options.timeout ?? this.config.requestTimeout;
-        // ─────────────────────────────────────────────────────────────
-        // PHASE 1: Send request, get "pending" acknowledgment
-        // ─────────────────────────────────────────────────────────────
-        // Use existing sendRequest() for the request/response part.
-        // This handles the JSON-RPC id matching for us.
-        const pendingResult = await this.sendRequest(state, {
-            jsonrpc: '2.0',
-            id: ++this.nextRequestId,
-            method: 'kadi.ability.request',
-            params: { toolName, toolInput: params },
-        });
-        // Validate the pending response
-        if (pendingResult.status !== 'pending' || !pendingResult.requestId) {
-            throw new KadiError('Unexpected response from broker: expected pending acknowledgment', 'BROKER_ERROR', {
-                broker: brokerName,
-                toolName,
-                response: pendingResult,
-            });
-        }
-        const requestId = pendingResult.requestId;
-        // ─────────────────────────────────────────────────────────────
-        // PHASE 2: Wait for kadi.ability.response notification
-        // ─────────────────────────────────────────────────────────────
-        // The actual result comes as a notification (no id) with our requestId.
-        // We store in pendingInvocations and handleAbilityResponse() will resolve.
-        return new Promise((resolve, reject) => {
+        // Generate requestId FIRST, before any async operations.
+        // This allows us to set up the response listener before sending,
+        // eliminating the race condition where fast responses arrive
+        // before the listener exists.
+        const requestId = crypto.randomUUID();
+        // Set up result listener BEFORE sending the request.
+        // When the broker sends kadi.ability.response, handleAbilityResponse()
+        // will find this listener and resolve/reject the promise.
+        const resultPromise = new Promise((resolve, reject) => {
             const timeoutHandle = setTimeout(() => {
                 state.pendingInvocations.delete(requestId);
                 reject(new KadiError(`Tool invocation "${toolName}" timed out waiting for result`, 'BROKER_TIMEOUT', {
@@ -1514,6 +1442,33 @@ export class KadiClient {
                 sentAt: new Date(),
             });
         });
+        // Helper to clean up the pending invocation on failure
+        const cleanupPendingInvocation = () => {
+            const pending = state.pendingInvocations.get(requestId);
+            if (pending) {
+                clearTimeout(pending.timeout);
+                state.pendingInvocations.delete(requestId);
+            }
+        };
+        // NOW send the request (listener already exists, no race possible)
+        try {
+            const pendingResult = await this.sendRequest(state, {
+                jsonrpc: '2.0',
+                id: ++this.nextRequestId,
+                method: 'kadi.ability.request',
+                params: { toolName, toolInput: params, requestId },
+            });
+            // Validate the broker accepted the request
+            if (pendingResult.status !== 'pending') {
+                cleanupPendingInvocation();
+                throw new KadiError('Unexpected response from broker: expected pending acknowledgment', 'BROKER_ERROR', { broker: brokerName, toolName, response: pendingResult });
+            }
+        }
+        catch (error) {
+            cleanupPendingInvocation();
+            throw error;
+        }
+        return resultPromise;
     }
     // ─────────────────────────────────────────────────────────────
     // SERVE MODE
@@ -1629,7 +1584,7 @@ export class KadiClient {
             }
             else if (message.method === 'invoke') {
                 const params = message.params;
-                result = await this.invoke(params.toolName, params.toolInput);
+                result = await this.executeToolHandler(params.toolName, params.toolInput);
             }
             else if (message.method === 'shutdown') {
                 // Graceful shutdown - send response first, then cleanup
@@ -1735,13 +1690,9 @@ export class KadiClient {
      * Get list of connected broker names.
      */
     getConnectedBrokers() {
-        const connected = [];
-        for (const [name, state] of this.brokers) {
-            if (state.status === 'connected') {
-                connected.push(name);
-            }
-        }
-        return connected;
+        return Array.from(this.brokers.entries())
+            .filter(([, state]) => state.status === 'connected')
+            .map(([name]) => name);
     }
 }
 //# sourceMappingURL=client.js.map