@kadi.build/core 0.0.1-alpha.2 → 0.0.1-alpha.4

package/dist/KadiClient.d.ts

@@ -0,0 +1,303 @@
+import { EventEmitter } from 'events';
+import { JSONSchema, BrokerConnection } from './types/core.js';
+import { LoadedAbility } from './loadAbility.js';
+export interface KadiClientConfig {
+    name?: string;
+    version?: string;
+    description?: string;
+    role?: 'agent' | 'ability' | 'service';
+    protocol?: 'native' | 'stdio' | 'broker';
+    scope?: string;
+    networks?: string[];
+    brokerUrls?: string[];
+    brokerUrl?: string;
+    maxBufferSize?: number;
+    abilityAgentJSON?: string;
+    [key: string]: any;
+}
+export interface ToolSchema {
+    name?: string;
+    description?: string;
+    inputSchema?: JSONSchema;
+    outputSchema?: JSONSchema;
+}
+type ToolHandler = (params: unknown) => Promise<unknown>;
+interface RegisteredTool {
+    name: string;
+    handler: ToolHandler;
+    schema?: ToolSchema;
+}
+/**
+ * KadiClient - Unified client for KADI protocol
+ *
+ * This class combines the functionality of KadiAgent and KadiAbility,
+ * providing a single interface for:
+ *
+ * 1. Registering tools that can be called by others
+ * 2. Calling remote tools on other services
+ * 3. Supporting multiple protocols (native, stdio, broker)
+ * 4. Connecting to broker with configurable role (agent, ability, service)
+ *
+ * @example
+ * ```typescript
+ * // Create as an ability
+ * const service = new KadiClient({
+ *   name: 'math-service',
+ *   role: 'ability',
+ *   protocol: 'broker'
+ * });
+ *
+ * // Register tools
+ * service.registerTool('add', async ({a, b}) => ({result: a + b}));
+ *
+ * // With schema
+ * service.tool('multiply', async ({a, b}) => ({result: a * b}));
+ *
+ * // Start serving
+ * await service.serve();
+ * ```
+ */
+export declare class KadiClient extends EventEmitter {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly role: 'agent' | 'ability' | 'service';
+    protocol: 'native' | 'stdio' | 'broker';
+    readonly scope: string;
+    readonly networks: string[];
+    readonly brokerUrls: string[];
+    readonly abilityAgentJSON?: string;
+    private readonly logger;
+    private protocolHandler?;
+    readonly toolHandlers: Map<string, RegisteredTool>;
+    private readonly _abilities;
+    private readonly _brokerConnections;
+    private _isConnected;
+    private _agentId;
+    private _idFactory;
+    private _pendingResponses;
+    private _pendingToolCalls;
+    private _eventSubscriptions;
+    constructor(options?: KadiClientConfig);
+    /**
+     * Register a tool for this service
+     *
+     * @param name - Tool name
+     * @param handler - Handler function
+     * @param schema - Optional schema
+     * @returns This instance for chaining
+     */
+    registerTool(name: string, handler: ToolHandler, schema?: ToolSchema): this;
+    /**
+     * Get all registered tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Get all registered tools (agent compatibility)
+     */
+    getTools(): string[];
+    /**
+     * Check if a tool is registered
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Get tool handler
+     */
+    getToolHandler(name: string): ToolHandler | undefined;
+    /**
+     * Get tool schema
+     */
+    getToolSchema(name: string): ToolSchema | undefined;
+    /**
+     * Publish an event
+     */
+    publishEvent(eventName: string, data?: any): void;
+    /**
+     * Connect to brokers (for event subscription and/or broker protocol)
+     */
+    connectToBrokers(urls?: string[]): Promise<void>;
+    /**
+     * Connect to a single broker
+     */
+    private connectToBroker;
+    /**
+     * Perform KADI protocol handshake
+     */
+    private performHandshake;
+    /**
+     * Start heartbeat to keep broker connection alive
+     * Sends ping messages at the specified interval to prevent timeout
+     */
+    private startHeartbeat;
+    /**
+     * Register capabilities with broker
+     */
+    private registerCapabilities;
+    /**
+     * Send request to broker and wait for response
+     */
+    private sendRequest;
+    /**
+     * Handle incoming broker messages
+     */
+    private handleBrokerMessage;
+    /**
+     * Handle tool invocation result from broker
+     */
+    private handleToolResult;
+    /**
+     * Handle incoming tool invocation request
+     */
+    private handleToolInvocation;
+    /**
+     * Extract tool definitions for broker registration
+     */
+    private extractToolsForBroker;
+    /**
+     * Start serving (main entry point)
+     *
+     * @param options - Optional serve options
+     */
+    serve(options?: {
+        mode?: 'native' | 'stdio' | 'broker';
+    }): Promise<void>;
+    /**
+     * Start the client (alias for serve for agent compatibility)
+     */
+    start(): Promise<void>;
+    /**
+     * Discover tools available from a remote agent
+     *
+     * This function queries the broker to find what tools
+     * a specific remote agent provides.
+     *
+     * @param targetAgent - The name of the agent to discover tools from
+     * @returns Array of tool names available from the target agent
+     */
+    discoverRemoteTools(targetAgent: string): Promise<string[]>;
+    /**
+     * Call a tool on a remote agent via the broker
+     *
+     * This function sends an RPC call through the broker to invoke
+     * a specific tool on a remote agent.
+     *
+     * @param targetAgent - The name of the agent that has the tool
+     * @param toolName - The tool name to invoke
+     * @param params - The parameters to pass to the tool
+     * @returns The result from the remote tool invocation
+     */
+    callTool<TInput = unknown, TOutput = unknown>(targetAgent: string, toolName: string, params?: TInput): Promise<TOutput>;
+    /**
+     * Load an external ability
+     */
+    loadAbility(nameOrPath: string, protocol?: 'native' | 'stdio' | 'broker', options?: {
+        brokerUrl?: string;
+        spawnAbility?: boolean;
+        networks?: string[];
+    }): Promise<LoadedAbility>;
+    /**
+     * Disconnect from brokers
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Helper to load agent.json exports
+     */
+    private _loadAgentJsonExports;
+    /**
+     * Find agent.json file
+     */
+    private _findAgentJson;
+    /**
+     * Subscribe to events with unified API across all protocols
+     *
+     * @param pattern Event pattern - exact string for native/stdio, wildcards supported for broker
+     * @param callback Function to call when event is received
+     * @returns Unsubscribe function
+     */
+    subscribeToEvent(pattern: string, callback: (data: any) => void): () => void;
+    /**
+     * Subscribe to multiple events at once
+     *
+     * @param patterns Array of event patterns
+     * @param callback Function to call when any event is received (receives eventName and data)
+     * @returns Unsubscribe function that removes all subscriptions
+     */
+    subscribeToEvents(patterns: string[], callback: (eventName: string, data: any) => void): () => void;
+    /**
+     * Unsubscribe from event pattern
+     *
+     * @param pattern Event pattern to unsubscribe from
+     * @param callback Optional specific callback to remove (if not provided, removes all)
+     */
+    unsubscribeFromEvent(pattern: string, callback?: (data: any) => void): void;
+    /**
+     * Subscribe to an event only once
+     *
+     * @param pattern Event pattern
+     * @param callback Function to call when event is received (auto-unsubscribes after first call)
+     */
+    onceEvent(pattern: string, callback: (data: any) => void): void;
+    /**
+     * Setup universal event subscription that works regardless of client protocol
+     *
+     * @private
+     * @param pattern Event pattern to subscribe to
+     */
+    /**
+     * Marker to track if we've already set up the event transport infrastructure
+     */
+    private _eventTransportSetup;
+    /**
+     * Setup the event transport infrastructure ONCE, then subscribe to specific patterns
+     * TODO: I do not understand this function very well - better step by step comments
+     * would be nice.
+     *
+     * @private
+     * @param pattern Event pattern to subscribe to (e.g., 'echo.test-event')
+     */
+    private _setupProtocolEventSubscription;
+    /**
+     * Subscribe to broker events
+     *
+     * @private
+     * @param pattern Event pattern to subscribe to
+     */
+    private _subscribeToBrokerEvent;
+    /**
+     * Setup broker event delivery handler
+     *
+     * @private
+     */
+    private _brokerEventHandlerSetup;
+    private _setupBrokerEventHandler;
+    /**
+     * Clean up protocol-specific event subscription
+     *
+     * @private
+     * @param pattern Event pattern to clean up
+     */
+    private _cleanupProtocolEventSubscription;
+    /**
+     * Check if event name matches pattern
+     *
+     * @private
+     * @param eventName Event name to check
+     * @param pattern Pattern to match against (supports wildcards for broker protocol)
+     * @returns True if matches
+     */
+    private _matchesPattern;
+    /**
+     * Dispatch event to subscribers
+     * TODO: I do not understand this function
+     *
+     * @private
+     * @param pattern Pattern that matched
+     * @param data Event data
+     */
+    private _dispatchEvent;
+    get isConnected(): boolean;
+    get agentId(): string;
+    get broker(): BrokerConnection | undefined;
+}
+export default KadiClient;
+//# sourceMappingURL=KadiClient.d.ts.map

package/dist/KadiClient.d.ts.map

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