@kadi.build/core 0.3.3 → 0.4.0

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, ClientIdentity, 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.
  *
@@ -58,7 +58,48 @@ export declare class KadiClient {
     private eventHandler;
     /** Whether we're serving via stdio (set by serve('stdio')) */
     private isServingStdio;
+    /** Ed25519 private key (DER format) - used for signing */
+    private readonly _privateKey;
+    /** Base64-encoded Ed25519 public key (SPKI DER format) */
+    private readonly _publicKeyBase64;
+    /** Deterministic agent ID: SHA256(publicKey).hex().substring(0, 16) */
+    private readonly _agentId;
     constructor(config: ClientConfig);
+    /**
+     * Get the client's cryptographic identity.
+     *
+     * Available immediately after construction (before connect).
+     * The same identity is used for all broker connections.
+     *
+     * @example
+     * ```typescript
+     * const client = new KadiClient({ name: 'my-agent' });
+     * console.log(client.identity);
+     * // { publicKey: 'MIIBIjAN...', agentId: 'a1b2c3d4e5f67890' }
+     * ```
+     */
+    get identity(): ClientIdentity;
+    /**
+     * Get the client's public key (base64-encoded SPKI DER format).
+     *
+     * This is the key used for Ed25519 authentication with brokers.
+     */
+    get publicKey(): string;
+    /**
+     * Get the client's agent ID.
+     *
+     * Derived deterministically from publicKey: SHA256(publicKey).hex().substring(0, 16)
+     * This is the same ID that brokers will assign during authentication.
+     */
+    get agentId(): string;
+    /**
+     * Get the agent name (from config).
+     */
+    get name(): string;
+    /**
+     * Get the agent version (from config).
+     */
+    get version(): string;
     /**
      * Connect to all configured brokers.
      * Call this after registering tools.
@@ -74,14 +115,16 @@ export declare class KadiClient {
      * Connect to a specific broker by name.
      *
      * Protocol:
-     * 1. Generate Ed25519 keypair
-     * 2. Open WebSocket connection
-     * 3. Send kadi.session.hello
-     * 4. Receive nonce from broker
-     * 5. Send kadi.session.authenticate with signed nonce
-     * 6. Receive agentId from broker
-     * 7. Register tools with broker
-     * 8. Start heartbeat
+     * 1. Open WebSocket connection
+     * 2. Send kadi.session.hello
+     * 3. Receive nonce from broker
+     * 4. Send kadi.session.authenticate with signed nonce (using client's identity)
+     * 5. Receive agentId from broker (should match client.agentId)
+     * 6. Register tools with broker
+     * 7. Start heartbeat
+     *
+     * Note: The keypair is generated once at client construction and shared
+     * across all broker connections, ensuring consistent identity.
      */
     private connectToBroker;
     private buildHelloMessage;
@@ -299,8 +342,8 @@ export declare class KadiClient {
     /**
      * Attempt to reconnect to the broker.
      *
-     * This reuses the existing keypair (agentId stays the same) and
-     * re-registers tools with the broker.
+     * Uses the client's identity (same keypair/agentId for all connections)
+     * and re-registers tools with the broker.
      *
      * On failure, schedules another attempt with increased delay.
      */
@@ -377,13 +420,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
@@ -144,6 +144,15 @@ export class KadiClient {
     /** Whether we're serving via stdio (set by serve('stdio')) */
     isServingStdio = false;
     // ─────────────────────────────────────────────────────────────
+    // IDENTITY (single keypair shared across all broker connections)
+    // ─────────────────────────────────────────────────────────────
+    /** Ed25519 private key (DER format) - used for signing */
+    _privateKey;
+    /** Base64-encoded Ed25519 public key (SPKI DER format) */
+    _publicKeyBase64;
+    /** Deterministic agent ID: SHA256(publicKey).hex().substring(0, 16) */
+    _agentId;
+    // ─────────────────────────────────────────────────────────────
     // CONSTRUCTOR
     // ─────────────────────────────────────────────────────────────
     constructor(config) {
@@ -153,6 +162,12 @@ export class KadiClient {
                 hint: 'Provide a name for your agent: new KadiClient({ name: "my-agent" })',
             });
         }
+        // Generate Ed25519 keypair once for consistent identity across all brokers
+        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+        this._privateKey = privateKey.export({ type: 'pkcs8', format: 'der' });
+        this._publicKeyBase64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+        // Derive agentId using same algorithm as broker: SHA256(publicKey).hex().substring(0, 16)
+        this._agentId = crypto.createHash('sha256').update(this._publicKeyBase64).digest('hex').substring(0, 16);
         // Resolve configuration with defaults
         // Auto-select first broker as default if not specified (matches Python behavior)
         const brokers = config.brokers ?? {};
@@ -179,6 +194,57 @@ export class KadiClient {
         }
     }
     // ─────────────────────────────────────────────────────────────
+    // IDENTITY GETTERS
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Get the client's cryptographic identity.
+     *
+     * Available immediately after construction (before connect).
+     * The same identity is used for all broker connections.
+     *
+     * @example
+     * ```typescript
+     * const client = new KadiClient({ name: 'my-agent' });
+     * console.log(client.identity);
+     * // { publicKey: 'MIIBIjAN...', agentId: 'a1b2c3d4e5f67890' }
+     * ```
+     */
+    get identity() {
+        return {
+            publicKey: this._publicKeyBase64,
+            agentId: this._agentId,
+        };
+    }
+    /**
+     * Get the client's public key (base64-encoded SPKI DER format).
+     *
+     * This is the key used for Ed25519 authentication with brokers.
+     */
+    get publicKey() {
+        return this._publicKeyBase64;
+    }
+    /**
+     * Get the client's agent ID.
+     *
+     * Derived deterministically from publicKey: SHA256(publicKey).hex().substring(0, 16)
+     * This is the same ID that brokers will assign during authentication.
+     */
+    get agentId() {
+        return this._agentId;
+    }
+    /**
+     * Get the agent name (from config).
+     */
+    get name() {
+        return this.config.name;
+    }
+    /**
+     * Get the agent version (from config).
+     */
+    get version() {
+        return this.config.version;
+    }
+    // ─────────────────────────────────────────────────────────────
     // CONNECTION MANAGEMENT
     // ─────────────────────────────────────────────────────────────
     /**
@@ -231,14 +297,16 @@ export class KadiClient {
      * Connect to a specific broker by name.
      *
      * Protocol:
-     * 1. Generate Ed25519 keypair
-     * 2. Open WebSocket connection
-     * 3. Send kadi.session.hello
-     * 4. Receive nonce from broker
-     * 5. Send kadi.session.authenticate with signed nonce
-     * 6. Receive agentId from broker
-     * 7. Register tools with broker
-     * 8. Start heartbeat
+     * 1. Open WebSocket connection
+     * 2. Send kadi.session.hello
+     * 3. Receive nonce from broker
+     * 4. Send kadi.session.authenticate with signed nonce (using client's identity)
+     * 5. Receive agentId from broker (should match client.agentId)
+     * 6. Register tools with broker
+     * 7. Start heartbeat
+     *
+     * Note: The keypair is generated once at client construction and shared
+     * across all broker connections, ensuring consistent identity.
      */
     async connectToBroker(brokerName) {
         const url = this.config.brokers[brokerName];
@@ -256,16 +324,11 @@ export class KadiClient {
                 return;
             }
         }
-        // Generate Ed25519 keypair for authentication
-        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
-        // Create broker state
+        // Create broker state (identity is at client level, not per-broker)
         const state = {
             name: brokerName,
             url,
             ws: null,
-            agentId: '',
-            publicKey: publicKey.export({ type: 'spki', format: 'der' }),
-            privateKey: privateKey.export({ type: 'pkcs8', format: 'der' }),
             heartbeatTimer: null,
             pendingRequests: new Map(),
             pendingInvocations: new Map(),
@@ -302,9 +365,10 @@ export class KadiClient {
             params: { role: 'agent' },
         };
     }
-    buildAuthMessage(state, nonce) {
+    buildAuthMessage(nonce) {
+        // Sign the nonce using the client's private key
         const privateKey = crypto.createPrivateKey({
-            key: state.privateKey,
+            key: this._privateKey,
             format: 'der',
             type: 'pkcs8',
         });
@@ -314,7 +378,7 @@ export class KadiClient {
             id: this.nextRequestId++,
             method: 'kadi.session.authenticate',
             params: {
-                publicKey: state.publicKey.toString('base64'),
+                publicKey: this._publicKeyBase64,
                 signature: signature.toString('base64'),
                 nonce,
             },
@@ -399,13 +463,18 @@ export class KadiClient {
         }
         // Step 2: Sign the nonce and authenticate
         // This proves we own the private key without revealing it
-        const authResult = await this.sendRequest(state, this.buildAuthMessage(state, helloResult.nonce));
+        const authResult = await this.sendRequest(state, this.buildAuthMessage(helloResult.nonce));
         if (!authResult.agentId) {
             throw new KadiError('Auth response missing agentId', 'AUTHENTICATION_FAILED', {
                 broker: state.name,
             });
         }
-        state.agentId = authResult.agentId;
+        // Verify broker assigned the expected agentId (sanity check)
+        if (authResult.agentId !== this._agentId) {
+            console.warn(`[KADI] Broker "${state.name}" returned different agentId: ` +
+                `expected ${this._agentId}, got ${authResult.agentId}. ` +
+                `This may indicate the broker uses a different ID derivation algorithm.`);
+        }
     }
     /**
      * Register with broker after authentication.
@@ -828,7 +897,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') {
@@ -1028,8 +1097,8 @@ export class KadiClient {
     /**
      * Attempt to reconnect to the broker.
      *
-     * This reuses the existing keypair (agentId stays the same) and
-     * re-registers tools with the broker.
+     * Uses the client's identity (same keypair/agentId for all connections)
+     * and re-registers tools with the broker.
      *
      * On failure, schedules another attempt with increased delay.
      */
@@ -1233,13 +1302,24 @@ export class KadiClient {
             .map((t) => t.definition);
     }
     /**
-     * Invoke a local tool by name.
+     * Execute a tool registered on this client.
      *
-     * @param toolName - Name of the tool to invoke
+     * 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)
+     *
+     * 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', {
@@ -1254,6 +1334,20 @@ export class KadiClient {
         // 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
     // ─────────────────────────────────────────────────────────────
@@ -1284,7 +1378,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.
@@ -1321,7 +1417,7 @@ export class KadiClient {
         // ─────────────────────────────────────────────────────────────────────────
         if (options.command) {
             return loadStdioTransport(options.command, options.args ?? [], {
-                timeoutMs: this.config.requestTimeout,
+                timeoutMs: options.timeout ?? this.config.requestTimeout,
             });
         }
         // ─────────────────────────────────────────────────────────────────────────
@@ -1329,7 +1425,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
         });
     }
@@ -1352,7 +1448,7 @@ export class KadiClient {
         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 }),
@@ -1415,6 +1511,14 @@ 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, {
@@ -1425,22 +1529,12 @@ export class KadiClient {
             });
             // Validate the broker accepted the request
             if (pendingResult.status !== 'pending') {
-                // Clean up listener since request wasn't accepted
-                const pending = state.pendingInvocations.get(requestId);
-                if (pending) {
-                    clearTimeout(pending.timeout);
-                    state.pendingInvocations.delete(requestId);
-                }
+                cleanupPendingInvocation();
                 throw new KadiError('Unexpected response from broker: expected pending acknowledgment', 'BROKER_ERROR', { broker: brokerName, toolName, response: pendingResult });
             }
         }
         catch (error) {
-            // Clean up listener if request failed
-            const pending = state.pendingInvocations.get(requestId);
-            if (pending) {
-                clearTimeout(pending.timeout);
-                state.pendingInvocations.delete(requestId);
-            }
+            cleanupPendingInvocation();
             throw error;
         }
         return resultPromise;
@@ -1559,7 +1653,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