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

package/dist/abilities/AbilityProxy.d.ts

@@ -0,0 +1,496 @@
+/**
+ * Ability Proxy
+ *
+ * Creates a proxy object that makes calling ability methods feel natural.
+ * Enables syntax like: `ability.methodName(params)` instead of
+ * `transport.invoke('methodName', params)`.
+ *
+ * @module abilities/AbilityProxy
+ */
+import { EventEmitter } from 'events';
+import type { AbilityTransport, MethodSchema } from '../types/index.js';
+/**
+ * Transport type for ability loading
+ */
+export type TransportType = 'native' | 'stdio' | 'broker';
+/**
+ * Framework methods that ALL abilities have.
+ *
+ * These are introspection and control methods provided by the KADI framework,
+ * prefixed with __ to avoid conflicts with ability-specific methods.
+ *
+ * Every loaded ability will have these methods available regardless of what
+ * the underlying ability provides.
+ */
+export interface AbilityFramework extends EventEmitter {
+    /**
+     * Ability name (readonly)
+     *
+     * @example
+     * ```typescript
+     * console.log(ability.__name);  // "calculator"
+     * ```
+     */
+    readonly __name: string;
+    /**
+     * Transport type used to load this ability (readonly)
+     * - 'native': In-process module (loaded directly into memory)
+     * - 'stdio': Child process (communicated via stdin/stdout)
+     * - 'broker': Remote service (communicated via WebSocket broker)
+     *
+     * @example
+     * ```typescript
+     * console.log(ability.__transport);  // "broker"
+     * ```
+     */
+    readonly __transport: TransportType;
+    /**
+     * Get list of available method names
+     *
+     * Returns all methods that this ability exposes. You can call any of
+     * these methods on the ability object.
+     *
+     * @returns Array of method names
+     *
+     * @example
+     * ```typescript
+     * const methods = ability.__getMethods();
+     * console.log(methods);  // ['add', 'subtract', 'multiply']
+     * ```
+     */
+    __getMethods(): string[];
+    /**
+     * Get MCP schema for a specific method
+     *
+     * Returns the JSON Schema describing the method's input and output types.
+     * Useful for validation, documentation, and runtime type checking.
+     *
+     * @param method - Method name
+     * @returns Method schema or undefined if not available
+     *
+     * @example
+     * ```typescript
+     * const schema = ability.__getSchema('add');
+     * console.log(schema.inputSchema);   // { type: 'object', properties: { a: ..., b: ... } }
+     * console.log(schema.outputSchema);  // { type: 'object', properties: { result: ... } }
+     * ```
+     */
+    __getSchema(method: string): MethodSchema | undefined;
+    /**
+     * Get all schemas for all methods
+     *
+     * Returns a map of method name to schema for every method this ability provides.
+     *
+     * @returns Record mapping method names to their schemas
+     *
+     * @example
+     * ```typescript
+     * const schemas = ability.__getAllSchemas();
+     * for (const [method, schema] of Object.entries(schemas)) {
+     *   console.log(`${method}:`, schema.description);
+     * }
+     * ```
+     */
+    __getAllSchemas(): Record<string, MethodSchema>;
+    /**
+     * Get human-readable usage documentation for a method
+     *
+     * Returns formatted documentation showing how to use a method, including
+     * description, parameters, return type, and example usage.
+     *
+     * @param method - Method name
+     * @returns Formatted usage string or undefined if method not found
+     *
+     * @example
+     * ```typescript
+     * console.log(ability.__getUsage('add'));
+     * // Output:
+     * // add(params)
+     * //   Description: Add two numbers
+     * //   Parameters: { a: number, b: number }
+     * //   Returns: { result: number }
+     * //   Example: ability.add({ a: 5, b: 3 })
+     * ```
+     */
+    __getUsage(method: string): string | undefined;
+    /**
+     * Get complete API documentation for all methods
+     *
+     * Returns formatted documentation for the entire ability API.
+     * Includes all methods, their descriptions, parameters, and examples.
+     *
+     * @returns Complete API documentation string
+     *
+     * @example
+     * ```typescript
+     * console.log(ability.__getAPI());
+     * // Shows formatted documentation for all methods
+     * ```
+     */
+    __getAPI(): string;
+    /**
+     * Call a method directly by name (alternative to proxy syntax)
+     *
+     * This is an escape hatch for when you need to call methods dynamically
+     * or when the method name is in a variable.
+     *
+     * @template TInput - Input parameter type
+     * @template TOutput - Output return type
+     * @param method - Method name to invoke
+     * @param params - Method parameters
+     * @returns Promise resolving to method result
+     *
+     * @example
+     * ```typescript
+     * // These are equivalent:
+     * const result1 = await ability.add({ a: 5, b: 3 });
+     * const result2 = await ability.__call('add', { a: 5, b: 3 });
+     *
+     * // Dynamic method name:
+     * const methodName = 'add';
+     * const result3 = await ability.__call(methodName, { a: 5, b: 3 });
+     * ```
+     */
+    __call<TInput = unknown, TOutput = unknown>(method: string, params: TInput): Promise<TOutput>;
+    /**
+     * Disconnect from the ability
+     *
+     * Closes the connection and cleans up resources. After calling disconnect,
+     * any subsequent method calls will fail.
+     *
+     * @returns Promise that resolves when disconnection is complete
+     *
+     * @example
+     * ```typescript
+     * await ability.__disconnect();
+     * console.log(ability.__isConnected());  // false
+     * ```
+     */
+    __disconnect(): Promise<void>;
+    /**
+     * Check if currently connected to the ability
+     *
+     * @returns true if connected and ready for method calls, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (ability.__isConnected()) {
+     *   await ability.someMethod({ ... });
+     * }
+     * ```
+     */
+    __isConnected(): boolean;
+    /**
+     * Subscribe to events from the ability
+     *
+     * Abilities can emit events during long-running operations or to notify
+     * about state changes. Use this to listen for those events.
+     *
+     * @param event - Event name
+     * @param callback - Event callback function
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * ability.__on('progress', (data) => {
+     *   console.log(`Progress: ${data.percent}%`);
+     * });
+     *
+     * ability.__on('error', (error) => {
+     *   console.error('Ability error:', error);
+     * });
+     * ```
+     */
+    __on(event: string, callback: (...args: unknown[]) => void): this;
+}
+/**
+ * Default type for dynamic method calls.
+ *
+ * When you don't provide a type parameter to LoadedAbility, this is what you get:
+ * - Any string property can be called as a function
+ * - Parameters are flexible (any[])
+ * - Return type is Promise<any>
+ *
+ * This allows rapid prototyping without needing to define types upfront.
+ *
+ * @example
+ * ```typescript
+ * const ability = await client.load('my-ability', 'broker');
+ * // ability has type: LoadedAbility<DynamicMethods>
+ *
+ * // Any method name works:
+ * await ability.anyMethod({ foo: 'bar' });
+ * await ability.something();
+ * await ability.whatever({ a: 1, b: 2 });
+ * ```
+ */
+export type DynamicMethods = Record<string, (...args: any[]) => Promise<any>>;
+/**
+ * Loaded Ability type.
+ *
+ * **TYPE ARCHITECTURE:**
+ * This is an intersection type that combines:
+ * 1. DynamicMethods - allows calling any method name dynamically
+ * 2. AbilityFramework - framework methods (introspection, control)
+ *
+ * **HOW IT WORKS:**
+ * At runtime, AbilityProxy creates a JavaScript Proxy that intercepts ALL
+ * property access. When you call `ability.someMethod(params)`:
+ * 1. Proxy intercepts the 'someMethod' property access
+ * 2. Returns a function that calls `transport.invoke('someMethod', params)`
+ * 3. Framework methods (__name, etc.) are handled directly
+ *
+ * This type definition makes TypeScript understand that runtime behavior.
+ *
+ * **RUNTIME VALIDATION:**
+ * Use the `validate: true` option when loading abilities to get runtime
+ * method checking and helpful error messages.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage:
+ * const calc = await client.load('calculator', 'broker');
+ * const result = await calc.add({ a: 5, b: 3 });
+ *
+ * // With runtime validation:
+ * const validated = await client.load('calculator', 'broker', {
+ *   validate: true  // Checks ability has expected methods
+ * });
+ *
+ * // Access framework methods:
+ * console.log(calc.__name);        // "calculator"
+ * console.log(calc.__getMethods()); // ["add", "subtract", ...]
+ * console.log(calc.__getSchema('add')); // { inputSchema: {...}, outputSchema: {...} }
+ * ```
+ */
+export type LoadedAbility = DynamicMethods & AbilityFramework;
+/**
+ * Ability Proxy (internal implementation)
+ *
+ * Creates a proxy object that intercepts property access and converts it
+ * to method invocations on the underlying transport.
+ *
+ * This class implements AbilityFramework, providing all the framework methods.
+ * The runtime Proxy wrapper adds dynamic method access on top.
+ *
+ * **Internal Architecture:**
+ * - This class extends EventEmitter and implements AbilityFramework
+ * - createProxy() wraps an instance in a Proxy for dynamic method access
+ * - The Proxy intercepts property access and routes to __call()
+ * - Framework methods (__name, __getMethods, etc.) are handled directly
+ *
+ * @example
+ * ```typescript
+ * const proxy = AbilityProxy.create('calculator', transport, 'broker');
+ *
+ * // These all work:
+ * const result1 = await proxy.add({ a: 5, b: 3 });
+ * const result2 = await proxy.__call('add', { a: 5, b: 3 });
+ *
+ * // Get methods
+ * const methods = proxy.__getMethods();
+ *
+ * // Get schema
+ * const schema = proxy.__getSchema('add');
+ *
+ * // Events
+ * proxy.__on('calculation.done', (data) => {
+ *   console.log('Done:', data);
+ * });
+ * ```
+ */
+export declare class AbilityProxy extends EventEmitter implements AbilityFramework {
+    /**
+     * Ability name
+     */
+    readonly __name: string;
+    /**
+     * Transport type
+     */
+    readonly __transport: TransportType;
+    /**
+     * Underlying transport
+     */
+    private readonly transport;
+    /**
+     * Schema validator for runtime validation
+     */
+    private readonly validator;
+    /**
+     * Create a new AbilityProxy (private constructor)
+     *
+     * Use AbilityProxy.create() to get a proxied ability object.
+     *
+     * @param name - Ability name
+     * @param transport - Ability transport
+     * @param transportType - Transport type identifier
+     */
+    private constructor();
+    /**
+     * Create a new proxied ability
+     *
+     * Factory method that creates an AbilityProxy and wraps it in a Proxy
+     * to enable dynamic method access.
+     *
+     * @param name - Ability name
+     * @param transport - Ability transport
+     * @param transportType - Transport type identifier
+     * @returns Proxied ability object with dynamic method access and framework methods
+     *
+     * @example
+     * ```typescript
+     * // Create ability proxy:
+     * const calc = AbilityProxy.create('calculator', transport, 'broker');
+     *
+     * // Call methods dynamically:
+     * await calc.add({ a: 5, b: 3 });
+     * await calc.subtract({ a: 10, b: 4 });
+     *
+     * // Access framework methods:
+     * console.log(calc.__name);         // "calculator"
+     * console.log(calc.__getMethods()); // ["add", "subtract", ...]
+     * ```
+     */
+    static create(name: string, transport: AbilityTransport, transportType: TransportType): LoadedAbility;
+    /**
+     * Register schemas for all methods with the validator
+     *
+     * Iterates over all methods and registers their schemas for validation.
+     * Methods without schemas will not have validation.
+     */
+    private registerMethodSchemas;
+    /**
+     * Get available methods
+     *
+     * @returns Array of method names
+     */
+    __getMethods(): string[];
+    /**
+     * Get schema for a method
+     *
+     * @param method - Method name
+     * @returns Method schema or undefined
+     */
+    __getSchema(method: string): MethodSchema | undefined;
+    /**
+     * Get all schemas for all methods
+     *
+     * @returns Map of method names to their schemas
+     */
+    __getAllSchemas(): Record<string, MethodSchema>;
+    /**
+     * Read agent.json representation (native transport with KadiClient only)
+     *
+     * Returns the agent.json representation from the loaded ability if it's a KadiClient
+     * instance loaded via native transport. Returns undefined for other transports
+     * or legacy modules.
+     *
+     * **What this returns:**
+     * - Runtime representation of the ability's agent.json file
+     * - Contains name, version, description, and tools
+     * - Tools field is mapped from agent.json's 'exports' field
+     *
+     * **Use Case:** Type generation during `kadi install`
+     * The CLI can call this method to get the agent.json representation including schemas,
+     * then generate TypeScript .d.ts files for autocomplete.
+     *
+     * @returns agent.json representation or undefined
+     *
+     * @example
+     * ```typescript
+     * const calc = await client.load('calculator', 'native', { path: './abilities/calc' });
+     * const agentJson = calc.__readAgentJson();
+     *
+     * if (agentJson) {
+     *   console.log('Ability:', agentJson.name, agentJson.version);
+     *   console.log('Tools:', agentJson.tools.map(t => t.name));
+     *
+     *   // CLI would use this for type generation:
+     *   // await TypeGenerator.generate(agentJson, './types/calculator.d.ts');
+     * }
+     * ```
+     */
+    __readAgentJson(): import('../abilities/types.js').AgentJson | undefined;
+    /**
+     * Get usage information for a method
+     *
+     * Formats schema into human-readable usage documentation.
+     *
+     * @param method - Method name
+     * @returns Formatted usage string
+     */
+    __getUsage(method: string): string | undefined;
+    /**
+     * Get complete API documentation
+     *
+     * Returns formatted documentation for all methods.
+     *
+     * @returns API documentation string
+     */
+    __getAPI(): string;
+    /**
+     * Call a method directly
+     *
+     * @template TInput - Input type
+     * @template TOutput - Output type
+     * @param method - Method name
+     * @param params - Method parameters
+     * @returns Promise resolving to method result
+     */
+    __call<TInput = unknown, TOutput = unknown>(method: string, params: TInput): Promise<TOutput>;
+    /**
+     * Disconnect the ability
+     */
+    __disconnect(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    __isConnected(): boolean;
+    /**
+     * Subscribe to events
+     *
+     * @param event - Event name
+     * @param callback - Event callback
+     * @returns this for chaining
+     */
+    __on(event: string, callback: (...args: unknown[]) => void): this;
+    /**
+     * Generate example data from JSON Schema
+     *
+     * Creates sample values based on schema types and constraints.
+     * Useful for showing users what valid input looks like.
+     *
+     * @param schema - JSON Schema (MCP inputSchema)
+     * @returns Example data matching schema
+     *
+     * @example
+     * ```typescript
+     * const schema = {
+     *   type: 'object',
+     *   properties: {
+     *     name: { type: 'string' },
+     *     age: { type: 'number' }
+     *   },
+     *   required: ['name']
+     * };
+     * const example = generateExampleFromSchema(schema);
+     * // Returns: { name: "example", age: 0 }
+     * ```
+     */
+    private generateExampleFromSchema;
+    /**
+     * Create the proxy object
+     *
+     * Wraps this AbilityProxy instance in a JavaScript Proxy to intercept
+     * property access and convert it to method calls.
+     *
+     * **How this satisfies LoadedAbility type:**
+     * - Target (this) implements AbilityFramework (all __ methods)
+     * - Proxy handler provides dynamic method access (DynamicMethods)
+     * - Result is AbilityFramework & DynamicMethods = LoadedAbility
+     *
+     * @returns Proxied ability (satisfies LoadedAbility<DynamicMethods>)
+     */
+    private createProxy;
+}
+//# sourceMappingURL=AbilityProxy.d.ts.map

package/dist/abilities/AbilityProxy.d.ts.map

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