@kadi.build/core 0.7.2 → 0.9.0

package/README.md

@@ -107,6 +107,59 @@ client.registerTool({
 client.registerTool(definition, handler, { brokers: ['internal'] });
 ```
 
+### Targeting Specific Networks
+
+By default, a tool is visible on **all networks** the agent has joined. You can restrict a tool to specific networks using the `networks` option — the tool will only be discoverable and invocable by agents on those networks.
+
+```typescript
+const client = new KadiClient({
+  name: 'multi-network-agent',
+  brokers: { default: 'ws://localhost:8080/kadi' },
+  networks: ['global', 'internal', 'gpu-cluster'],
+});
+
+// Visible on ALL agent networks (global, internal, gpu-cluster)
+client.registerTool({
+  name: 'echo',
+  description: 'Echo back the input',
+  input: z.object({ message: z.string() }),
+}, async ({ message }) => ({ echo: message }));
+
+// Visible ONLY on gpu-cluster
+client.registerTool({
+  name: 'gpu-inference',
+  description: 'Run ML inference on GPU',
+  input: z.object({ model: z.string(), prompt: z.string() }),
+}, async ({ model, prompt }) => {
+  return { result: await runInference(model, prompt) };
+}, { networks: ['gpu-cluster'] });
+
+// Visible on internal AND global only (not gpu-cluster)
+client.registerTool({
+  name: 'audit-log',
+  description: 'Retrieve audit logs',
+  input: z.object({ limit: z.number() }),
+}, async ({ limit }) => {
+  return { logs: await getAuditLogs(limit) };
+}, { networks: ['internal', 'global'] });
+```
+
+Per-tool networks must be a **subset** of the client's `networks`. Attempting to scope a tool to a network the agent hasn't joined throws an `INVALID_CONFIG` error:
+
+```typescript
+// Throws KadiError — 'finance' is not in client networks
+client.registerTool(definition, handler, { networks: ['finance'] });
+```
+
+You can combine `brokers` and `networks` to control both which brokers a tool registers with and which networks it's visible on:
+
+```typescript
+client.registerTool(definition, handler, {
+  brokers: ['production'],
+  networks: ['internal'],
+});
+```
+
 ---
 
 ## Connecting to Brokers

package/dist/client.d.ts

@@ -15,7 +15,7 @@
  * - Readable, traceable code flow
  */
 import { type EncryptionKeyPair } from './crypto.js';
-import type { ClientConfig, ClientIdentity, BrokerState, ToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, ToolExecutionBridge, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
+import type { ClientConfig, ClientIdentity, BrokerState, BrokerToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, ToolExecutionBridge, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
 /**
  * The main client for building KADI agents.
  *
@@ -25,8 +25,8 @@ import type { ClientConfig, ClientIdentity, BrokerState, ToolDefinition, ZodTool
  * const client = new KadiClient({
  *   name: 'my-agent',
  *   brokers: {
- *     production: 'ws://broker-prod:8080',
- *     internal: 'ws://broker-internal:8080',
+ *     production: { url: 'ws://broker-prod:8080/kadi' },
+ *     internal: { url: 'ws://broker-internal:8080/kadi', networks: ['private'] },
  *   },
  *   defaultBroker: 'production',
  * });
@@ -404,6 +404,11 @@ export declare class KadiClient {
      * Handle response to a pending request.
      */
     private handleBrokerResponse;
+    /**
+     * Finalize a broker connection: start heartbeat and mark as connected.
+     * Shared by initial connect and reconnect paths.
+     */
+    private finalizeConnection;
     /**
      * Send heartbeat to keep connection alive.
      */
@@ -521,8 +526,12 @@ export declare class KadiClient {
      *   output: z.object({ result: z.number() }),
      * }, async ({ a, b }) => ({ result: a + b }));
      *
-     * // Register only on specific broker
-     * client.registerTool(def, handler, { brokers: ['internal'] });
+     * // Register on specific brokers with per-broker networks
+     * client.registerTool(def, handler, {
+     *   brokers: {
+     *     internal: { networks: ['private'] },
+     *   },
+     * });
      * ```
      */
     registerTool<TInput, TOutput>(definition: ZodToolDefinition<TInput, TOutput>, handler: ToolHandler<TInput, TOutput>, options?: RegisterToolOptions): void;
@@ -530,7 +539,7 @@ export declare class KadiClient {
      * Get tool definitions, optionally filtered for a specific broker.
      *
      * @param forBroker - If provided, only return tools targeted for this broker.
-     *                    Tools with empty targetBrokers are included for all brokers.
+     *                    Tools with empty brokerNetworks are included for all brokers.
      */
     private getToolDefinitions;
     /**
@@ -697,7 +706,7 @@ export declare class KadiClient {
     readAgentJson(): {
         name: string;
         version: string;
-        tools: ToolDefinition[];
+        tools: BrokerToolDefinition[];
     };
     /**
      * Get broker connection state (for broker transport).

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

@@ -20,6 +20,7 @@ import { convertToEncryptionKey, convertToEncryptionKeyPair, } from './crypto.js
 // @ts-expect-error - tweetnacl-sealedbox-js doesn't have type definitions
 import sealedbox from 'tweetnacl-sealedbox-js';
 import { KadiError } from './errors.js';
+import * as protocol from './protocol.js';
 import { zodToJsonSchema, isZodSchema } from './zod.js';
 import { resolveAbilityEntry, resolveAbilityScript } from './lockfile.js';
 import { loadNativeTransport } from './transports/native.js';
@@ -112,8 +113,8 @@ function isMcpCallToolResult(result) {
  * const client = new KadiClient({
  *   name: 'my-agent',
  *   brokers: {
- *     production: 'ws://broker-prod:8080',
- *     internal: 'ws://broker-internal:8080',
+ *     production: { url: 'ws://broker-prod:8080/kadi' },
+ *     internal: { url: 'ws://broker-internal:8080/kadi', networks: ['private'] },
  *   },
  *   defaultBroker: 'production',
  * });
@@ -182,16 +183,21 @@ export class KadiClient {
         // 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 ?? {};
-        const firstBrokerName = Object.keys(brokers)[0];
+        const rawBrokers = config.brokers ?? {};
+        const normalizedBrokers = {};
+        for (const [name, entry] of Object.entries(rawBrokers)) {
+            normalizedBrokers[name] = {
+                url: entry.url,
+                networks: entry.networks ?? ['global'],
+            };
+        }
+        const firstBrokerName = Object.keys(normalizedBrokers)[0];
         this.config = {
             name: config.name,
             version: config.version ?? '1.0.0',
             description: config.description ?? '',
-            brokers,
+            brokers: normalizedBrokers,
             defaultBroker: config.defaultBroker ?? firstBrokerName,
-            networks: config.networks ?? ['global'],
             heartbeatInterval: config.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL,
             requestTimeout: config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT,
             autoReconnect: config.autoReconnect ?? DEFAULT_AUTO_RECONNECT,
@@ -364,8 +370,6 @@ export class KadiClient {
         for (const [i, result] of results.entries()) {
             if (result.status === 'rejected') {
                 const failedBroker = brokerNames[i];
-                if (failedBroker === undefined)
-                    continue;
                 const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
                 console.error(`[KADI] Failed to connect to broker "${failedBroker}": ${reason}`);
                 failures.push(failedBroker);
@@ -397,14 +401,15 @@ export class KadiClient {
      * across all broker connections, ensuring consistent identity.
      */
     async connectToBroker(brokerName) {
-        const url = this.config.brokers[brokerName];
-        if (!url) {
+        const brokerConfig = this.config.brokers[brokerName];
+        if (!brokerConfig) {
             throw new KadiError(`Broker "${brokerName}" not found in configuration`, 'UNKNOWN_BROKER', {
                 broker: brokerName,
                 available: Object.keys(this.config.brokers),
                 hint: 'Check your brokers configuration',
             });
         }
+        const url = brokerConfig.url;
         // Check if already connected
         if (this.brokers.has(brokerName)) {
             const existing = this.brokers.get(brokerName);
@@ -416,6 +421,7 @@ export class KadiClient {
         const state = {
             name: brokerName,
             url,
+            networks: brokerConfig.networks,
             ws: null,
             heartbeatTimer: null,
             pendingRequests: new Map(),
@@ -436,22 +442,14 @@ export class KadiClient {
         await this.performHandshake(state);
         // Register with broker (transitions to "ready" state)
         await this.registerWithBroker(state);
-        // Start heartbeat
-        state.heartbeatTimer = setInterval(() => {
-            this.sendHeartbeat(state);
-        }, this.config.heartbeatInterval);
-        state.status = 'connected';
+        // Finalize connection (heartbeat + status)
+        this.finalizeConnection(state);
     }
     // ─────────────────────────────────────────────────────────────
     // MESSAGE BUILDERS
     // ─────────────────────────────────────────────────────────────
     buildHelloMessage() {
-        return {
-            jsonrpc: '2.0',
-            id: this.nextRequestId++,
-            method: 'kadi.session.hello',
-            params: { role: 'agent' },
-        };
+        return protocol.hello(this.nextRequestId++);
     }
     buildAuthMessage(nonce) {
         // Sign the nonce using the client's private key
@@ -461,36 +459,13 @@ export class KadiClient {
             type: 'pkcs8',
         });
         const signature = crypto.sign(null, Buffer.from(nonce, 'utf8'), privateKey);
-        return {
-            jsonrpc: '2.0',
-            id: this.nextRequestId++,
-            method: 'kadi.session.authenticate',
-            params: {
-                publicKey: this._publicKeyBase64,
-                signature: signature.toString('base64'),
-                nonce,
-            },
-        };
+        return protocol.authenticate(this.nextRequestId++, this._publicKeyBase64, signature.toString('base64'), nonce);
     }
     buildRegisterMessage(tools, networks) {
-        return {
-            jsonrpc: '2.0',
-            id: this.nextRequestId++,
-            method: 'kadi.agent.register',
-            params: {
-                tools,
-                networks,
-                displayName: this.config.name,
-            },
-        };
+        return protocol.register(this.nextRequestId++, tools, networks, this.config.name);
     }
     buildHeartbeatMessage() {
-        return {
-            jsonrpc: '2.0',
-            id: this.nextRequestId++,
-            method: 'kadi.session.heartbeat',
-            params: { timestamp: Date.now() },
-        };
+        return protocol.heartbeat(this.nextRequestId++);
     }
     // ─────────────────────────────────────────────────────────────
     // CONNECTION HELPERS
@@ -593,7 +568,11 @@ export class KadiClient {
         // Note: If registration fails, sendRequest will reject with the error.
         // We don't need to check response.error here - errors are already
         // handled via Promise rejection in handleBrokerResponse.
-        await this.sendRequest(state, this.buildRegisterMessage(tools, this.config.networks));
+        const { droppedNetworks } = await this.sendRequest(state, this.buildRegisterMessage(tools, state.networks));
+        if (droppedNetworks && droppedNetworks.length > 0) {
+            console.warn(`[KADI] Broker "${state.name}" dropped networks ${JSON.stringify(droppedNetworks)} ` +
+                `during registration. Tools scoped to those networks will not be discoverable.`);
+        }
     }
     /**
      * Send a JSON-RPC request and wait for the response.
@@ -862,12 +841,7 @@ export class KadiClient {
         handlers.add(handler);
         // If this is the first handler for this pattern, subscribe on broker
         if (!state.subscribedPatterns.has(pattern)) {
-            await this.sendRequest(state, {
-                jsonrpc: '2.0',
-                id: this.nextRequestId++,
-                method: 'kadi.event.subscribe',
-                params: { pattern },
-            });
+            await this.sendRequest(state, protocol.eventSubscribe(this.nextRequestId++, pattern));
             state.subscribedPatterns.add(pattern);
         }
     }
@@ -913,12 +887,7 @@ export class KadiClient {
                 // Unsubscribe from broker if we were subscribed
                 if (state.subscribedPatterns.has(pattern) && state.status === 'connected') {
                     try {
-                        await this.sendRequest(state, {
-                            jsonrpc: '2.0',
-                            id: this.nextRequestId++,
-                            method: 'kadi.event.unsubscribe',
-                            params: { pattern },
-                        });
+                        await this.sendRequest(state, protocol.eventUnsubscribe(this.nextRequestId++, pattern));
                     }
                     catch {
                         // Ignore errors during unsubscribe (broker might be disconnecting)
@@ -949,19 +918,10 @@ export class KadiClient {
      */
     async publish(channel, data, options = {}) {
         const { state } = this.getConnectedBrokerState(options.broker);
-        // Resolve which network to publish to
-        const networkId = options.network ?? this.config.networks[0] ?? 'global';
+        // Resolve which network to publish to (prefer broker-specific, fallback to global)
+        const networkId = options.network ?? state.networks[0] ?? '';
         // Send publish request to broker
-        await this.sendRequest(state, {
-            jsonrpc: '2.0',
-            id: this.nextRequestId++,
-            method: 'kadi.event.publish',
-            params: {
-                channel,
-                data,
-                networkId,
-            },
-        });
+        await this.sendRequest(state, protocol.eventPublish(this.nextRequestId++, channel, data, networkId));
     }
     // ─────────────────────────────────────────────────────────────
     // DEPLOYMENT SECRETS (Trusted Introducer Pattern)
@@ -1191,35 +1151,18 @@ export class KadiClient {
                 // KADI clients receive raw structured data
                 responseResult = result;
             }
-            const response = {
-                jsonrpc: '2.0',
-                id: requestId,
-                result: responseResult,
-            };
-            state.ws?.send(JSON.stringify(response));
+            state.ws?.send(JSON.stringify(protocol.resultResponse(requestId, responseResult)));
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             // For MCP clients, wrap errors in CallToolResult format too
             if (context.callerProtocol === 'mcp') {
-                const response = {
-                    jsonrpc: '2.0',
-                    id: requestId,
-                    result: { content: [{ type: 'text', text: errorMessage }], isError: true },
-                };
-                state.ws?.send(JSON.stringify(response));
+                const mcpResult = { content: [{ type: 'text', text: errorMessage }], isError: true };
+                state.ws?.send(JSON.stringify(protocol.resultResponse(requestId, mcpResult)));
             }
             else {
                 // KADI clients receive JSON-RPC error
-                const response = {
-                    jsonrpc: '2.0',
-                    id: requestId,
-                    error: {
-                        code: -32000,
-                        message: errorMessage,
-                    },
-                };
-                state.ws?.send(JSON.stringify(response));
+                state.ws?.send(JSON.stringify(protocol.errorResponse(requestId, -32000, errorMessage)));
             }
         }
     }
@@ -1244,6 +1187,16 @@ export class KadiClient {
             pending.resolve(response.result);
         }
     }
+    /**
+     * Finalize a broker connection: start heartbeat and mark as connected.
+     * Shared by initial connect and reconnect paths.
+     */
+    finalizeConnection(state) {
+        state.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat(state);
+        }, this.config.heartbeatInterval);
+        state.status = 'connected';
+    }
     /**
      * Send heartbeat to keep connection alive.
      */
@@ -1283,6 +1236,9 @@ export class KadiClient {
             }));
         }
         state.pendingInvocations.clear();
+        // Clear broker-side subscription tracking — subscriptions are lost when
+        // the connection drops and must be re-established after reconnection.
+        state.subscribedPatterns.clear();
     }
     // ─────────────────────────────────────────────────────────────
     // RECONNECTION LOGIC
@@ -1395,14 +1351,11 @@ export class KadiClient {
             await this.performHandshake(state);
             // Re-register tools
             await this.registerWithBroker(state);
-            // Restart heartbeat
-            state.heartbeatTimer = setInterval(() => {
-                this.sendHeartbeat(state);
-            }, this.config.heartbeatInterval);
+            // Finalize connection (heartbeat + status)
+            this.finalizeConnection(state);
             // Success!
             console.error(`[KADI] Reconnected to broker "${state.name}" after ${state.reconnectAttempts} attempts`);
             state.reconnectAttempts = 0;
-            state.status = 'connected';
         }
         catch (error) {
             // Log the error and try again
@@ -1509,12 +1462,7 @@ export class KadiClient {
         }
         else if (this.isServingStdio) {
             // Stdio transport: write notification to stdout
-            const notification = {
-                jsonrpc: '2.0',
-                method: 'event',
-                params: { name: event, data },
-            };
-            const json = JSON.stringify(notification);
+            const json = JSON.stringify(protocol.eventNotification(event, data));
             process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
         }
         // Broadcast: also publish to broker (if specified and connected)
@@ -1548,8 +1496,12 @@ export class KadiClient {
      *   output: z.object({ result: z.number() }),
      * }, async ({ a, b }) => ({ result: a + b }));
      *
-     * // Register only on specific broker
-     * client.registerTool(def, handler, { brokers: ['internal'] });
+     * // Register on specific brokers with per-broker networks
+     * client.registerTool(def, handler, {
+     *   brokers: {
+     *     internal: { networks: ['private'] },
+     *   },
+     * });
      * ```
      */
     registerTool(definition, handler, options = {}) {
@@ -1569,12 +1521,35 @@ export class KadiClient {
                 ? zodToJsonSchema(definition.output)
                 : undefined,
         };
+        // Validate per-broker network scoping (skip when no brokers configured)
+        const brokerScopes = options.brokers ?? {};
+        if (Object.keys(brokerScopes).length > 0 && Object.keys(this.config.brokers).length > 0) {
+            for (const [brokerName, scope] of Object.entries(brokerScopes)) {
+                const brokerConfig = this.config.brokers[brokerName];
+                if (!brokerConfig) {
+                    throw new KadiError(`Tool "${definition.name}" references broker "${brokerName}" which is not configured. Available brokers: ${JSON.stringify(Object.keys(this.config.brokers))}`, 'INVALID_CONFIG', {
+                        toolName: definition.name,
+                        broker: brokerName,
+                        availableBrokers: Object.keys(this.config.brokers),
+                    });
+                }
+                const brokerNetworks = brokerConfig.networks;
+                const invalid = scope.networks.filter((n) => !brokerNetworks.includes(n));
+                if (invalid.length > 0) {
+                    throw new KadiError(`Tool "${definition.name}" has networks ${JSON.stringify(invalid)} not present on broker "${brokerName}" networks ${JSON.stringify(brokerNetworks)}. Per-tool networks must be a subset of the broker's networks — a tool can only be visible on networks the agent has joined.`, 'INVALID_CONFIG', {
+                        toolName: definition.name,
+                        broker: brokerName,
+                        invalidNetworks: invalid,
+                        brokerNetworks,
+                    });
+                }
+            }
+        }
         // Store registration
         const registered = {
             definition: jsonDefinition,
             handler: handler,
-            registeredAt: new Date(),
-            targetBrokers: options.brokers ?? [],
+            brokerNetworks: brokerScopes,
         };
         this.tools.set(definition.name, registered);
     }
@@ -1582,21 +1557,31 @@ export class KadiClient {
      * Get tool definitions, optionally filtered for a specific broker.
      *
      * @param forBroker - If provided, only return tools targeted for this broker.
-     *                    Tools with empty targetBrokers are included for all brokers.
+     *                    Tools with empty brokerNetworks are included for all brokers.
      */
     getToolDefinitions(forBroker) {
-        return Array.from(this.tools.values())
-            .filter((t) => {
-            // If no broker specified, return all tools (e.g., for readAgentJson)
-            if (!forBroker)
-                return true;
-            // Empty targetBrokers means "register with all brokers"
-            if (t.targetBrokers.length === 0)
-                return true;
-            // Otherwise, only include if this broker is in the target list
-            return t.targetBrokers.includes(forBroker);
-        })
-            .map((t) => t.definition);
+        const results = [];
+        for (const t of this.tools.values()) {
+            const hasBrokerNetworks = Object.keys(t.brokerNetworks).length > 0;
+            if (!forBroker) {
+                // No broker filter — return all tools (e.g., for readAgentJson)
+                results.push({ ...t.definition });
+                continue;
+            }
+            if (!hasBrokerNetworks) {
+                // Empty brokerNetworks = register with all brokers, no network field
+                results.push({ ...t.definition });
+                continue;
+            }
+            const scope = t.brokerNetworks[forBroker];
+            if (!scope)
+                continue; // Tool not registered on this broker
+            results.push({
+                ...t.definition,
+                ...(scope.networks.length > 0 && { networks: scope.networks }),
+            });
+        }
+        return results;
     }
     /**
      * Execute a tool registered on this client.
@@ -1752,7 +1737,7 @@ export class KadiClient {
         const ability = await loadBrokerTransport(name, {
             broker: state,
             requestTimeout: options.timeout ?? this.config.requestTimeout,
-            networks: options.networks,
+            networks: options.networks ?? state.networks,
             // Provide subscribe/unsubscribe for ability.on()/off() support
             subscribe: (pattern, handler) => this.subscribe(pattern, handler, { broker: brokerName }),
             unsubscribe: (pattern, handler) => this.unsubscribe(pattern, handler, { broker: brokerName }),
@@ -1831,13 +1816,9 @@ export class KadiClient {
         };
         // 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',
-                // timeout sent so the broker can enforce a matching server-side deadline
-                params: { toolName, toolInput: params, requestId, timeout },
-            });
+            const pendingResult = await this.sendRequest(state, 
+            // timeout sent so the broker can enforce a matching server-side deadline
+            protocol.abilityRequest(++this.nextRequestId, toolName, params, requestId, timeout));
             // Validate the broker accepted the request
             if (pendingResult.status !== 'pending') {
                 cleanupPendingInvocation();
@@ -1990,24 +1971,14 @@ export class KadiClient {
      * Send a response via stdio.
      */
     sendStdioResponse(id, result) {
-        const response = {
-            jsonrpc: '2.0',
-            id,
-            result,
-        };
-        const json = JSON.stringify(response);
+        const json = JSON.stringify(protocol.resultResponse(id, result));
         process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
     }
     /**
      * Send an error response via stdio.
      */
     sendStdioError(id, error) {
-        const response = {
-            jsonrpc: '2.0',
-            id,
-            error,
-        };
-        const json = JSON.stringify(response);
+        const json = JSON.stringify(protocol.errorResponse(id, error.code, error.message));
         process.stdout.write(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
     }
     /**