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

package/dist/client/KadiClient.d.ts

@@ -0,0 +1,459 @@
+/**
+ * KADI Client
+ *
+ * Thin orchestrator that composes specialized modules to provide the
+ * complete KADI client functionality.
+ *
+ * This is dramatically simpler than the old implementation because each
+ * concern has been properly separated.
+ *
+ * @module client/KadiClient
+ */
+import { EventEmitter } from 'events';
+import type { KadiConfig, ResolvedConfig, ToolHandler, KadiTool, EventCallback, UnsubscribeFunction, PublishOptions } from '../types/index.js';
+import { BrokerConnectionManager } from '../broker/BrokerConnectionManager.js';
+import { BrokerProtocol } from '../broker/BrokerProtocol.js';
+import { type LoadedAbility, type LoadOptions, type AgentJson } from '../abilities/index.js';
+import type { IBrokerClient } from '../transports/BrokerTransport.js';
+/**
+ * KADI Client
+ *
+ * Main client class for KADI framework.
+ * Orchestrates tool registry, event hub, broker connections, and ability loading.
+ *
+ * @example
+ * ```typescript
+ * // Create client
+ * const client = new KadiClient({
+ *   name: 'my-service',
+ *   brokers: { local: 'ws://localhost:8080' },
+ *   networks: ['global']
+ * });
+ *
+ * // Register a tool
+ * client.registerTool('greet', async ({ name }) => {
+ *   return { message: `Hello, ${name}!` };
+ * });
+ *
+ * // Connect to brokers
+ * await client.connect();
+ *
+ * // Load an ability (explicit transport)
+ * const calc = await client.load('calculator', 'broker');
+ * const result = await calc.add({ a: 5, b: 3 });
+ *
+ * // Subscribe to events
+ * client.subscribeToEvent('user.*', (data) => {
+ *   console.log('User event:', data);
+ * });
+ *
+ * // Publish an event
+ * client.publishEvent('user.login', { userId: '123' });
+ * ```
+ */
+export declare class KadiClient extends EventEmitter implements IBrokerClient {
+    /**
+     * Resolved configuration
+     */
+    readonly config: ResolvedConfig;
+    /**
+     * Tool registry
+     */
+    private readonly tools;
+    /**
+     * Event hub
+     */
+    private readonly events;
+    /**
+     * Broker connection manager
+     */
+    private readonly brokers;
+    /**
+     * Broker protocol instances (per broker)
+     */
+    private readonly protocols;
+    /**
+     * Ability loader
+     */
+    private readonly abilityLoader;
+    /**
+     * Whether client is initialized
+     */
+    private initialized;
+    /**
+     * Create a new KADI Client
+     *
+     * @param config - Client configuration
+     */
+    constructor(config: KadiConfig);
+    /**
+     * Connect to configured brokers
+     *
+     * @throws {KadiError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * await client.connect();
+     * console.log('Connected to brokers');
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Connect to all configured brokers
+     */
+    private connectToBrokers;
+    /**
+     * Register capabilities with a broker
+     *
+     * @param protocol - Broker protocol instance
+     */
+    private registerCapabilitiesWithBroker;
+    /**
+     * Register a tool (MCP-based)
+     *
+     * @template TInput - Tool input type
+     * @template TOutput - Tool output type
+     * @param definition - MCP-compliant tool definition
+     * @param handler - Tool handler function
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * client.registerTool({
+     *   name: 'add',
+     *   description: 'Add two numbers',
+     *   version: '1.0.0',
+     *   tags: ['math'],
+     *   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 };
+     * });
+     * ```
+     */
+    registerTool<TInput = unknown, TOutput = unknown>(definition: KadiTool | (Omit<KadiTool, 'inputSchema' | 'outputSchema'> & {
+        input?: any;
+        output?: any;
+    }), handler: ToolHandler<TInput, TOutput>): this;
+    /**
+     * Get a registered tool by name
+     *
+     * Retrieves a tool that has been registered with this client.
+     * Useful for inspecting registered tools or accessing their metadata.
+     *
+     * @param name - Tool name to retrieve
+     * @returns The registered tool with its definition and handler, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const tool = client.getRegisteredTool('add');
+     * if (tool) {
+     *   console.log('Tool:', tool.definition.name);
+     *   console.log('Description:', tool.definition.description);
+     * }
+     * ```
+     */
+    getRegisteredTool(name: string): import("../schemas/kadi-extensions.js").RegisteredTool<unknown, unknown> | undefined;
+    /**
+     * Get all registered tools
+     *
+     * Returns an array of all tools that have been registered with this client.
+     * Useful for listing available tools or debugging.
+     *
+     * @returns Array of all registered tools
+     *
+     * @example
+     * ```typescript
+     * const allTools = client.getAllRegisteredTools();
+     * console.log('Available tools:', allTools.map(t => t.definition.name));
+     * ```
+     */
+    getAllRegisteredTools(): import("../schemas/kadi-extensions.js").RegisteredTool<unknown, unknown>[];
+    /**
+     * Check if a tool is registered
+     *
+     * @param name - Tool name to check
+     * @returns true if the tool is registered, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (client.hasRegisteredTool('add')) {
+     *   // Tool is available
+     * }
+     * ```
+     */
+    hasRegisteredTool(name: string): boolean;
+    /**
+     * Load an ability
+     *
+     * **Explicit Transport, Excellent Developer Experience:**
+     * - Explicit transport selection (no magic)
+     * - Transport-specific options (only relevant fields shown)
+     * - Smart caching (avoids duplicate loads)
+     * - Runtime validation (optional)
+     * - Helpful errors with suggestions
+     *
+     * @param name - Ability name
+     * @param transport - Transport type ('native', 'stdio', or 'broker')
+     * @param options - Load options (transport-specific, optional)
+     * @returns Proxied ability with dynamic method access
+     *
+     * @throws {KadiError} If loading fails
+     *
+     * @example
+     * ```typescript
+     * // Simple broker load
+     * const calc = await client.load('calculator', 'broker');
+     * await calc.add({ a: 5, b: 3 });
+     *
+     * // With options
+     * const remote = await client.load('gpu-service', 'broker', {
+     *   networks: ['global', 'gpu-cluster']
+     * });
+     *
+     * // With runtime validation
+     * const validated = await client.load('calculator', 'broker', {
+     *   validate: true  // Runtime check for expected methods
+     * });
+     *
+     * // Native transport
+     * const local = await client.load('math-lib', 'native', {
+     *   path: './abilities/math'
+     * });
+     * ```
+     */
+    load(name: string, transport: 'native' | 'stdio' | 'broker', options?: LoadOptions): Promise<LoadedAbility>;
+    /**
+     * Subscribe to events
+     *
+     * @template T - Event data type
+     * @param pattern - Event pattern (supports wildcards)
+     * @param callback - Event callback
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = client.subscribeToEvent('user.*', (data) => {
+     *   console.log('User event:', data);
+     * });
+     *
+     * // Later...
+     * unsubscribe();
+     * ```
+     */
+    subscribeToEvent<T = unknown>(pattern: string, callback: EventCallback<T>): UnsubscribeFunction;
+    /**
+     * Publish an event
+     *
+     * @template T - Event data type
+     * @param eventName - Event name
+     * @param data - Event data
+     * @param options - Publishing options
+     *
+     * @example
+     * ```typescript
+     * client.publishEvent('user.login', {
+     *   userId: '123',
+     *   timestamp: Date.now()
+     * });
+     * ```
+     */
+    publishEvent<T = unknown>(eventName: string, data: T, options?: PublishOptions): void;
+    /**
+     * Disconnect from all brokers and cleanup
+     *
+     * @example
+     * ```typescript
+     * await client.disconnect();
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Stdio server instance (when running in stdio mode)
+     */
+    private stdioServer?;
+    /**
+     * Start serving this ability in the specified mode
+     *
+     * **Universal Entry Point**:
+     * Starts the appropriate server based on the mode parameter.
+     * This enables the same ability code to work across all transports
+     *
+     * **Modes**:
+     * - **native**: No-op (ability already loaded in-process as ES module)
+     * - **stdio**: Starts JSON-RPC server over stdin/stdout (for child processes)
+     * - **broker**: Connects to WebSocket broker and serves remotely
+     *
+     * @param mode - Transport mode to serve in ('native' | 'stdio' | 'broker')
+     * @returns Promise that resolves when server is ready (never resolves for stdio/broker - they keep running)
+     *
+     * @example
+     * ```typescript
+     * // ability.ts
+     * const client = new KadiClient({
+     *   name: 'calculator',
+     *   version: '1.0.0',
+     *   brokers: { default: 'ws://localhost:8080' }  // For broker mode
+     * });
+     *
+     * client.registerTool({ name: 'add', ... }, async ({ a, b }) => {
+     *   return { result: a + b };
+     * });
+     *
+     * export default client;
+     *
+     * // If running standalone, start server
+     * if (import.meta.url === `file://${process.argv[1]}`) {
+     *   await client.serve('stdio');  // or 'broker' for distributed mode
+     * }
+     * ```
+     */
+    serve(mode: 'native' | 'stdio' | 'broker'): Promise<void>;
+    /**
+     * Serve via stdio (JSON-RPC over stdin/stdout)
+     *
+     * **Steps**:
+     * 1. Redirect console.log to stderr (keeps stdout clean for JSON-RPC)
+     * 2. Create Content-Length message reader/writer for stdin/stdout
+     * 3. Listen for incoming JSON-RPC requests (invoke, readAgentJson, shutdown)
+     * 4. Execute tool handlers for 'invoke' requests
+     * 5. Send JSON-RPC responses back via stdout
+     * 6. Handle graceful shutdown on SIGTERM/SIGINT
+     * 7. Keep process alive until shutdown
+     *
+     * @returns Promise that never resolves (server runs until killed)
+     */
+    private serveStdio;
+    /**
+     * Serve via broker (WebSocket-based distributed mode)
+     *
+     * Connects to the broker, registers this ability's tools, and handles
+     * incoming tool invocation requests.
+     *
+     * **Steps**:
+     * 1. Get broker URL from constructor config
+     * 2. Create and connect to broker via BrokerConnection
+     * 3. Perform handshake and authentication
+     * 4. Register all tools from the registry
+     * 5. Listen for incoming 'kadi.ability.request' messages
+     * 6. Execute tool handlers and send responses
+     * 7. Handle graceful shutdown on SIGTERM/SIGINT
+     * 8. Keep process alive until shutdown
+     *
+     * @returns Promise that never resolves (server runs until killed)
+     * @throws {KadiError} If broker config missing or connection fails
+     * @private
+     */
+    private serveBroker;
+    /**
+     * Read agent.json representation
+     *
+     * Returns the runtime representation of this client's agent.json configuration.
+     * This enables KadiClient to function as an ability module that can be loaded
+     * natively by other agents.
+     *
+     * **What this returns:**
+     * - Represents what would be in the ability's agent.json file
+     * - Runtime `tools` field is mapped from agent.json's `exports` field
+     * - Used for discovery, type generation, and validation
+     *
+     * **Registration Pattern (Option A):**
+     * Ability developers write their code once using KadiClient.registerTool(),
+     * and it works across all transports (native, stdio, broker).
+     *
+     * @returns agent.json representation with name, version, and tools
+     *
+     * @example
+     * ```typescript
+     * // ability.ts (alongside agent.json file)
+     * const client = new KadiClient({ name: 'calculator', version: '1.0.0' });
+     * client.registerTool({ name: 'add', ... }, handler);
+     * export default client;
+     *
+     * // When loaded natively:
+     * const agentJson = client.readAgentJson();
+     * // { name: 'calculator', version: '1.0.0', tools: [...] }
+     * //   ↑ Represents agent.json's runtime structure
+     * ```
+     */
+    readAgentJson(): AgentJson;
+    /**
+     * Invoke a tool by name
+     *
+     * Enables KadiClient to be used as an ability module. When loaded natively,
+     * this method is called by NativeTransport to execute registered tools.
+     *
+     * **Write Once, Run Anywhere:**
+     * The same tool handler works whether the ability is loaded natively,
+     * via stdio, or through a broker.
+     *
+     * @template TInput - Tool input type
+     * @template TOutput - Tool output type
+     * @param toolName - Name of the tool to invoke
+     * @param params - Tool input parameters
+     * @returns Promise resolving to tool result
+     *
+     * @throws {KadiError} If tool not found or invocation fails
+     *
+     * @example
+     * ```typescript
+     * // Registered tool:
+     * client.registerTool({ name: 'add', ... }, ({ a, b }) => ({ result: a + b }));
+     *
+     * // Invoke via agent.json protocol (native loading):
+     * const result = await client.invoke('add', { a: 5, b: 3 });
+     * // { result: 8 }
+     * ```
+     */
+    invoke<TInput = unknown, TOutput = unknown>(toolName: string, params: TInput): Promise<TOutput>;
+    /**
+     * Get broker manager (implements IBrokerClient)
+     */
+    getBrokerManager(): BrokerConnectionManager;
+    /**
+     * Get broker protocol instance (implements IBrokerClient)
+     *
+     * @param brokerName - Optional broker name (uses default if not specified)
+     */
+    getBrokerProtocol(brokerName?: string): BrokerProtocol;
+    /**
+     * Networks (implements IBrokerClient)
+     */
+    get networks(): string[];
+    /**
+     * Create minimal configuration for constructor
+     * Full resolution happens in connect()
+     */
+    private createMinimalConfig;
+    /**
+     * Setup broker event forwarding
+     */
+    private setupBrokerEventForwarding;
+    /**
+     * Handle incoming tool invocation requests from broker
+     *
+     * Flow:
+     * 1. Extract id from top-level message (JSON-RPC request id)
+     * 2. Look up tool handler by name
+     * 3. Execute handler with toolInput
+     * 4. Send JSON-RPC response back to broker with matching id
+     *
+     * @param brokerName - Name of the broker connection to use for response
+     * @param message - Full JSON-RPC request message with id, method, and params
+     * @private
+     */
+    private handleIncomingToolRequest;
+}
+//# sourceMappingURL=KadiClient.d.ts.map

package/dist/client/KadiClient.d.ts.map

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