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

package/dist/api/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Simplified KADI API
+ *
+ * User-friendly API wrapper that makes KADI incredibly simple to use.
+ * This is what developers actually interact with.
+ *
+ * @module api
+ */
+import { KadiClient } from '../client/KadiClient.js';
+import type { KadiConfig, ServiceConfig } from '../types/index.js';
+/**
+ * Connect to a KADI broker and create a client
+ *
+ * Simplified connection API that handles common cases beautifully.
+ *
+ * @param config - Broker URL string or full configuration object
+ * @returns Connected KADI client
+ *
+ * @example
+ * ```typescript
+ * // Simple broker URL
+ * const client = await Kadi.connect('ws://localhost:8080');
+ *
+ * // Full configuration
+ * const client = await Kadi.connect({
+ *   name: 'my-app',
+ *   brokers: { local: 'ws://localhost:8080' },
+ *   networks: ['global']
+ * });
+ * ```
+ */
+export declare function connect(config: string | KadiConfig): Promise<KadiClient>;
+/**
+ * Create a service that provides tools
+ *
+ * Simplified service creation for agents that expose capabilities.
+ *
+ * @param config - Service configuration
+ * @returns Service client ready for tool registration
+ *
+ * @example
+ * ```typescript
+ * const service = await Kadi.service({
+ *   name: 'calculator',
+ *   broker: 'ws://localhost:8080'
+ * });
+ *
+ * // Register tools using MCP schema format
+ * service.registerTool({
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       a: { type: 'number' },
+ *       b: { type: 'number' }
+ *     },
+ *     required: ['a', 'b']
+ *   },
+ *   outputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       result: { type: 'number' }
+ *     }
+ *   }
+ * }, async ({ a, b }) => {
+ *   return { result: a + b };
+ * });
+ * ```
+ */
+export declare function service(config: ServiceConfig): Promise<KadiClient>;
+/**
+ * Create a client without connecting to brokers
+ *
+ * Useful for local-only operations (native/stdio transports).
+ *
+ * @param name - Client name
+ * @returns Local client (not connected to brokers)
+ *
+ * @example
+ * ```typescript
+ * const client = Kadi.local('my-app');
+ *
+ * // Load abilities locally
+ * const calc = await client.loadAbility('calculator', {
+ *   transport: 'native',
+ *   path: './calculator'
+ * });
+ * ```
+ */
+export declare function local(name: string): KadiClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAoB,MAAM,mBAAmB,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAa9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAqBxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAK9C"}

package/dist/api/index.js

@@ -0,0 +1,124 @@
+/**
+ * Simplified KADI API
+ *
+ * User-friendly API wrapper that makes KADI incredibly simple to use.
+ * This is what developers actually interact with.
+ *
+ * @module api
+ */
+import { KadiClient } from '../client/KadiClient.js';
+/**
+ * Connect to a KADI broker and create a client
+ *
+ * Simplified connection API that handles common cases beautifully.
+ *
+ * @param config - Broker URL string or full configuration object
+ * @returns Connected KADI client
+ *
+ * @example
+ * ```typescript
+ * // Simple broker URL
+ * const client = await Kadi.connect('ws://localhost:8080');
+ *
+ * // Full configuration
+ * const client = await Kadi.connect({
+ *   name: 'my-app',
+ *   brokers: { local: 'ws://localhost:8080' },
+ *   networks: ['global']
+ * });
+ * ```
+ */
+export async function connect(config) {
+    // Normalize config
+    const normalizedConfig = typeof config === 'string'
+        ? { name: 'kadi-client', brokers: { default: config } }
+        : config;
+    // Create client
+    const client = new KadiClient(normalizedConfig);
+    // Auto-connect
+    await client.connect();
+    return client;
+}
+/**
+ * Create a service that provides tools
+ *
+ * Simplified service creation for agents that expose capabilities.
+ *
+ * @param config - Service configuration
+ * @returns Service client ready for tool registration
+ *
+ * @example
+ * ```typescript
+ * const service = await Kadi.service({
+ *   name: 'calculator',
+ *   broker: 'ws://localhost:8080'
+ * });
+ *
+ * // Register tools using MCP schema format
+ * service.registerTool({
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       a: { type: 'number' },
+ *       b: { type: 'number' }
+ *     },
+ *     required: ['a', 'b']
+ *   },
+ *   outputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       result: { type: 'number' }
+ *     }
+ *   }
+ * }, async ({ a, b }) => {
+ *   return { result: a + b };
+ * });
+ * ```
+ */
+export async function service(config) {
+    // Convert ServiceConfig to KadiConfig
+    const clientConfig = {
+        name: config.name,
+        version: config.version,
+        description: config.description,
+        role: 'ability',
+        networks: config.networks ?? ['global']
+    };
+    // Add broker configuration
+    if (config.broker) {
+        clientConfig.brokers = { default: config.broker };
+        clientConfig.defaultBroker = 'default';
+    }
+    // Create and return client
+    const client = new KadiClient(clientConfig);
+    await client.connect();
+    return client;
+}
+/**
+ * Create a client without connecting to brokers
+ *
+ * Useful for local-only operations (native/stdio transports).
+ *
+ * @param name - Client name
+ * @returns Local client (not connected to brokers)
+ *
+ * @example
+ * ```typescript
+ * const client = Kadi.local('my-app');
+ *
+ * // Load abilities locally
+ * const calc = await client.loadAbility('calculator', {
+ *   transport: 'native',
+ *   path: './calculator'
+ * });
+ * ```
+ */
+export function local(name) {
+    return new KadiClient({
+        name,
+        networks: ['local']
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAA2B;IACvD,mBAAmB;IACnB,MAAM,gBAAgB,GAAe,OAAO,MAAM,KAAK,QAAQ;QAC7D,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;QACvD,CAAC,CAAC,MAAM,CAAC;IAEX,gBAAgB;IAChB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAEhD,eAAe;IACf,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IAEvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAqB;IACjD,sCAAsC;IACtC,MAAM,YAAY,GAAqB;QACrC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC;KACxC,CAAC;IAEF,2BAA2B;IAC3B,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,YAAY,CAAC,OAAO,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;QAClD,YAAY,CAAC,aAAa,GAAG,SAAS,CAAC;IACzC,CAAC;IAED,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IAEvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,KAAK,CAAC,IAAY;IAChC,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI;QACJ,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC,CAAC;AACL,CAAC"}

package/dist/broker/BrokerConnection.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Broker Connection
+ *
+ * Wraps a single WebSocket connection to a KADI broker.
+ * Handles connection lifecycle, message sending/receiving, and state management.
+ *
+ * @module broker/BrokerConnection
+ */
+import { EventEmitter } from 'events';
+import type { BrokerConfig, JsonRpcRequest, JsonRpcResponse, JsonRpcNotification } from '../types/index.js';
+import { ConnectionState } from '../types/index.js';
+/**
+ * Broker Connection Events
+ */
+export interface BrokerConnectionEvents {
+    /**
+     * Emitted when connection is established
+     */
+    connected: () => void;
+    /**
+     * Emitted when connection is closed
+     */
+    disconnected: (code: number, reason: string) => void;
+    /**
+     * Emitted when an error occurs
+     */
+    error: (error: Error) => void;
+    /**
+     * Emitted when a message is received
+     */
+    message: (message: JsonRpcResponse | JsonRpcNotification) => void;
+    /**
+     * Emitted when connection state changes
+     */
+    stateChange: (oldState: ConnectionState, newState: ConnectionState) => void;
+}
+/**
+ * Broker Connection
+ *
+ * Manages a single WebSocket connection to a broker.
+ * Handles low-level connection lifecycle and message framing.
+ *
+ * Does NOT handle:
+ * - Protocol logic (handshake, auth) - that's BrokerProtocol's job
+ * - Multiple connections - that's BrokerConnectionManager's job
+ *
+ * @example
+ * ```typescript
+ * const connection = new BrokerConnection({
+ *   url: 'ws://localhost:8080',
+ *   name: 'local',
+ *   connectionTimeout: 10000
+ * });
+ *
+ * connection.on('connected', () => {
+ *   console.log('Connected to broker');
+ * });
+ *
+ * connection.on('message', (message) => {
+ *   console.log('Received:', message);
+ * });
+ *
+ * await connection.connect();
+ * ```
+ */
+export declare class BrokerConnection extends EventEmitter {
+    /**
+     * Broker configuration
+     */
+    private readonly config;
+    /**
+     * WebSocket instance
+     */
+    private ws;
+    /**
+     * Current connection state
+     */
+    private _state;
+    /**
+     * Assigned agent ID (set after handshake)
+     */
+    private _agentId;
+    /**
+     * Heartbeat timer
+     */
+    private heartbeatTimer;
+    /**
+     * Connection timestamp
+     */
+    private _connectedAt;
+    /**
+     * Last heartbeat timestamp
+     */
+    private _lastHeartbeat;
+    /**
+     * Pending requests (for matching responses)
+     */
+    private pendingRequests;
+    /**
+     * Request ID counter
+     */
+    private requestIdCounter;
+    /**
+     * Create a new BrokerConnection
+     *
+     * @param config - Broker configuration
+     */
+    constructor(config: BrokerConfig);
+    /**
+     * Connect to the broker
+     *
+     * @throws {KadiError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * await connection.connect();
+     * console.log('Connected!');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the broker
+     *
+     * @example
+     * ```typescript
+     * await connection.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send a JSON-RPC request and wait for response
+     *
+     * @template T - Response result type
+     * @param request - JSON-RPC request
+     * @returns Promise resolving to the response result
+     *
+     * @throws {KadiError} If request fails or times out
+     *
+     * @example
+     * ```typescript
+     * const result = await connection.sendRequest({
+     *   jsonrpc: '2.0',
+     *   method: 'kadi.handshake',
+     *   params: { name: 'my-agent' },
+     *   id: 1
+     * });
+     * ```
+     */
+    sendRequest<T = unknown>(request: JsonRpcRequest): Promise<T>;
+    /**
+     * Send a JSON-RPC notification (no response expected)
+     *
+     * @param notification - JSON-RPC notification
+     *
+     * @example
+     * ```typescript
+     * connection.sendNotification({
+     *   jsonrpc: '2.0',
+     *   method: 'kadi.heartbeat',
+     *   params: { timestamp: Date.now() }
+     * });
+     * ```
+     */
+    sendNotification(notification: JsonRpcNotification): void;
+    /**
+     * Send a tool result back to broker as JSON-RPC response
+     *
+     * Used when this client acts as a tool provider and needs to respond to invocations.
+     * The requestId must match the incoming request's id field for proper routing.
+     *
+     * @param requestId - Request ID to respond to (CRITICAL: must match incoming request id)
+     * @param result - Result data to send back
+     */
+    sendResponse(requestId: string | number | undefined, result: unknown): void;
+    /**
+     * Send a tool error back to broker as JSON-RPC error response
+     *
+     * Used when tool execution fails and we need to report the error back.
+     * The requestId must match the incoming request's id field for proper routing.
+     *
+     * @param requestId - Request ID to respond to (CRITICAL: must match incoming request id)
+     * @param code - Error code (e.g., ErrorCode.TOOL_NOT_FOUND)
+     * @param message - Human-readable error message
+     * @param data - Optional additional error context
+     */
+    sendError(requestId: string | number | undefined, code: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Send raw data to broker
+     *
+     * @param data - Data to send (request, response, or notification)
+     */
+    private send;
+    /**
+     * Handle incoming WebSocket message
+     *
+     * @param data - Raw message data
+     */
+    private handleMessage;
+    /**
+     * Handle WebSocket close event
+     *
+     * @param code - Close code
+     * @param reason - Close reason
+     */
+    private handleClose;
+    /**
+     * Setup heartbeat timer
+     */
+    private setupHeartbeat;
+    /**
+     * Cleanup connection resources
+     */
+    private cleanup;
+    /**
+     * Set connection state and emit event
+     *
+     * @param newState - New state
+     */
+    private setState;
+    /**
+     * Get broker name
+     */
+    get name(): string;
+    /**
+     * Get broker URL
+     */
+    get url(): string;
+    /**
+     * Get current connection state
+     */
+    get state(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Get assigned agent ID
+     */
+    get agentId(): string | null;
+    /**
+     * Set agent ID (called after handshake)
+     */
+    set agentId(id: string | null);
+    /**
+     * Get connection timestamp
+     */
+    get connectedAt(): number | null;
+    /**
+     * Get last heartbeat timestamp
+     */
+    get lastHeartbeat(): number | null;
+}
+//# sourceMappingURL=BrokerConnection.d.ts.map

package/dist/broker/BrokerConnection.d.ts.map

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