@kadi.build/core 0.7.2 → 0.9.0

package/src/protocol.ts

@@ -0,0 +1,161 @@
+/**
+ * KADI Protocol Message Builders
+ * ==============================
+ *
+ * Pure functions that construct JSON-RPC 2.0 message objects for the KADI protocol.
+ *
+ * All functions return typed objects ready for `JSON.stringify()`.
+ *
+ * @example
+ * ```typescript
+ * import * as protocol from './protocol.js';
+ *
+ * const msg = protocol.heartbeat(1);
+ * ws.send(JSON.stringify(msg));
+ * ```
+ *
+ * Python Equivalent:
+ *   kadi-core-py/src/kadi/protocol.py
+ */
+
+import type { JsonRpcNotification, JsonRpcRequest, JsonRpcResponse } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Generic request builder
+// ---------------------------------------------------------------------------
+
+/** Build a standard JSON-RPC 2.0 request. */
+export function request(id: string | number, method: string, params: unknown): JsonRpcRequest {
+  return { jsonrpc: '2.0', id, method, params };
+}
+
+// ===========================================================================
+// Session
+// ===========================================================================
+
+/** Build a `kadi.session.hello` request. */
+export function hello(id: number): JsonRpcRequest {
+  return request(id, 'kadi.session.hello', { role: 'agent' });
+}
+
+/** Build a `kadi.session.authenticate` request. */
+export function authenticate(
+  id: number,
+  publicKey: string,
+  signature: string,
+  nonce: string,
+): JsonRpcRequest {
+  return request(id, 'kadi.session.authenticate', { publicKey, signature, nonce });
+}
+
+/** Build a `kadi.session.heartbeat` request. */
+export function heartbeat(id: number): JsonRpcRequest {
+  return request(id, 'kadi.session.heartbeat', { timestamp: Date.now() });
+}
+
+// ===========================================================================
+// Agent
+// ===========================================================================
+
+/** Build a `kadi.agent.register` request. */
+export function register(
+  id: number,
+  tools: unknown[],
+  networks: string[],
+  displayName?: string,
+): JsonRpcRequest {
+  const params: Record<string, unknown> = { tools, networks };
+  if (displayName !== undefined) {
+    params.displayName = displayName;
+  }
+  return request(id, 'kadi.agent.register', params);
+}
+
+// ===========================================================================
+// Ability
+// ===========================================================================
+
+/** Build a `kadi.ability.request` request. */
+export function abilityRequest(
+  id: number,
+  toolName: string,
+  toolInput: unknown,
+  requestId: string,
+  timeout?: number,
+): JsonRpcRequest {
+  const params: Record<string, unknown> = { toolName, toolInput, requestId };
+  if (timeout !== undefined) {
+    params.timeout = timeout;
+  }
+  return request(id, 'kadi.ability.request', params);
+}
+
+/** Build a `kadi.ability.list` request. */
+export function abilityList(
+  id: number,
+  networks: string[],
+  includeProviders = true,
+): JsonRpcRequest {
+  return request(id, 'kadi.ability.list', { networks, includeProviders });
+}
+
+// ===========================================================================
+// Event
+// ===========================================================================
+
+/** Build a `kadi.event.subscribe` request. */
+export function eventSubscribe(id: number, pattern: string): JsonRpcRequest {
+  return request(id, 'kadi.event.subscribe', { pattern });
+}
+
+/** Build a `kadi.event.unsubscribe` request. */
+export function eventUnsubscribe(id: number, pattern: string): JsonRpcRequest {
+  return request(id, 'kadi.event.unsubscribe', { pattern });
+}
+
+/** Build a `kadi.event.publish` request. */
+export function eventPublish(
+  id: number,
+  channel: string,
+  data: unknown,
+  networkId: string,
+): JsonRpcRequest {
+  return request(id, 'kadi.event.publish', { channel, data, networkId });
+}
+
+// ===========================================================================
+// Response (JSON-RPC result/error envelopes)
+// ===========================================================================
+
+/** Build a JSON-RPC 2.0 success response. */
+export function resultResponse(id: string | number, result: unknown): JsonRpcResponse {
+  return { jsonrpc: '2.0', id, result };
+}
+
+/** Build a JSON-RPC 2.0 error response. */
+export function errorResponse(
+  id: string | number,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  const error: { code: number; message: string; data?: unknown } = { code, message };
+  if (data !== undefined) {
+    error.data = data;
+  }
+  return { jsonrpc: '2.0', id, error };
+}
+
+// ===========================================================================
+// Stdio
+// ===========================================================================
+
+/** Build a `readAgentJson` request for stdio transport. */
+export function readAgentJson(id: number): JsonRpcRequest {
+  return request(id, 'readAgentJson', {});
+}
+
+/** Build an `event` notification (no `id` field). */
+export function eventNotification(name: string, data: unknown): JsonRpcNotification {
+  return { jsonrpc: '2.0', method: 'event', params: { name, data } };
+}

package/src/transports/stdio.ts

@@ -23,6 +23,7 @@ import type { Readable, Writable } from 'stream';
 import { z } from 'zod';
 import type { LoadedAbility, InvokeOptions, ToolDefinition, JsonRpcRequest, JsonRpcResponse, EventHandler } from '../types.js';
 import { KadiError } from '../errors.js';
+import * as protocol from '../protocol.js';
 
 /** Schema for event notification params */
 const EventNotificationParams = z.object({
@@ -393,12 +394,7 @@ export async function loadStdioTransport(
     }
 
     const id = idCounter++;
-    const request: JsonRpcRequest = {
-      jsonrpc: '2.0',
-      id,
-      method,
-      params,
-    };
+    const request = protocol.request(id, method, params);
 
     writer.write(request);
     const response = await reader.waitForResponse(id, timeoutMs);

package/src/types.ts

@@ -27,6 +27,30 @@ export type JSONSchema = JSONSchemaTypes.JSONSchema;
 // 1. CONFIGURATION
 // ═══════════════════════════════════════════════════════════════════════
 
+/**
+ * Per-broker connection configuration.
+ *
+ * Use this when different brokers should join different networks.
+ *
+ * @example
+ * ```typescript
+ * brokers: {
+ *   local: { url: 'ws://localhost:8080/kadi', networks: ['private', 'public'] },
+ *   remote: { url: 'wss://remote/kadi', networks: ['public'] },
+ * }
+ * ```
+ */
+export interface BrokerEntry {
+  /** WebSocket URL for this broker */
+  url: string;
+
+  /**
+   * Networks to join on this broker.
+   * Defaults to `['global']` if omitted.
+   */
+  networks?: string[];
+}
+
 /**
  * Configuration options for creating a KadiClient.
  *
@@ -36,8 +60,8 @@ export type JSONSchema = JSONSchemaTypes.JSONSchema;
  *   name: 'my-agent',
  *   version: '1.0.0',
  *   brokers: {
- *     prod: 'ws://broker-prod:8080',
- *     internal: 'ws://broker-internal:8080',
+ *     prod: { url: 'ws://broker-prod:8080/kadi', networks: ['public'] },
+ *     internal: { url: 'ws://broker-internal:8080/kadi', networks: ['private'] },
  *   },
  *   defaultBroker: 'prod',
  * });
@@ -55,17 +79,17 @@ export interface ClientConfig {
 
   /**
    * Named brokers to connect to.
-   * Keys are friendly names, values are WebSocket URLs.
+   * Keys are friendly names, values are BrokerEntry objects.
    *
    * @example
    * ```typescript
    * brokers: {
-   *   prod: 'ws://broker-prod:8080',
-   *   staging: 'ws://broker-staging:8080',
+   *   local: { url: 'ws://localhost:8080/kadi', networks: ['private'] },
+   *   remote: { url: 'wss://remote/kadi', networks: ['public'] },
    * }
    * ```
    */
-  brokers?: Record<string, string>;
+  brokers?: Record<string, BrokerEntry>;
 
   /**
    * Which broker to use by default for invokeRemote() and loadBroker().
@@ -73,13 +97,6 @@ export interface ClientConfig {
    */
   defaultBroker?: string;
 
-  /**
-   * Networks this agent belongs to.
-   * Used for filtering when discovering abilities.
-   * Default: ['global']
-   */
-  networks?: string[];
-
   /**
    * Heartbeat interval in milliseconds.
    * Broker expects heartbeats to stay connected.
@@ -147,9 +164,9 @@ export interface ResolvedConfig {
   name: string;
   version: string;
   description: string;
-  brokers: Record<string, string>;
+  /** Normalized broker configs. Each entry has a url and resolved networks array. */
+  brokers: Record<string, { url: string; networks: string[] }>;
   defaultBroker: string | undefined;
-  networks: string[];
   heartbeatInterval: number;
   requestTimeout: number;
   autoReconnect: boolean;
@@ -178,6 +195,15 @@ export interface ToolDefinition {
   outputSchema?: JSONSchema;
 }
 
+/**
+ * Tool definition extended with optional per-tool network scoping.
+ * Used when sending tool definitions to brokers and in readAgentJson().
+ */
+export interface BrokerToolDefinition extends ToolDefinition {
+  /** Networks this tool is visible on (omitted if visible on all client networks) */
+  networks?: string[];
+}
+
 /**
  * Tool definition using Zod schemas.
  * Recommended approach - provides type inference.
@@ -280,11 +306,8 @@ export interface RegisteredTool {
   /** The handler function */
   handler: ToolHandler;
 
-  /** When this tool was registered */
-  registeredAt: Date;
-
-  /** Which brokers this tool is registered with (empty = all) */
-  targetBrokers: string[];
+  /** Per-broker network targeting (empty = all brokers, all networks) */
+  brokerNetworks: Record<string, { networks: string[] }>;
 }
 
 /**
@@ -476,6 +499,9 @@ export interface BrokerState {
   /** WebSocket URL */
   url: string;
 
+  /** Networks this broker connection has joined */
+  networks: string[];
+
   /** WebSocket connection (null if disconnected) */
   ws: WebSocket | null;
 
@@ -721,16 +747,23 @@ export interface AbilityLockEntry {
  */
 export interface RegisterToolOptions {
   /**
-   * Which brokers to register this tool with.
-   * If not specified, registers with ALL connected brokers.
+   * Per-broker network scoping.
+   * Keys are broker names, values specify which networks to register on for that broker.
+   * Each broker name must exist in client's configured brokers.
+   * Each network list must be a subset of that specific broker's networks.
+   * If not specified, registers with ALL brokers on ALL their networks.
    *
    * @example
    * ```typescript
-   * // Register only on internal broker
-   * client.registerTool(def, handler, { brokers: ['internal'] });
+   * client.registerTool(def, handler, {
+   *   brokers: {
+   *     local: { networks: ['private'] },
+   *     remote: { networks: ['sensitive'] },
+   *   },
+   * });
    * ```
    */
-  brokers?: string[];
+  brokers?: Record<string, { networks: string[] }>;
 }
 
 /**