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

package/dist/abilities/AbilityContext.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Ability Context
+ * ================
+ *
+ * Context provided to abilities when running in stdio or native mode.
+ * Enables abilities to load other abilities with inherited configuration.
+ *
+ * **Context Flow:**
+ * - Native/Stdio: Context flows from parent to child
+ * - Broker: Services are independent (no context inheritance)
+ *
+ * @module abilities/AbilityContext
+ */
+import type { LoadedAbility } from './AbilityProxy.js';
+/**
+ * Load options for ability loading
+ */
+export interface LoadOptions {
+    /**
+     * Force specific transport (optional - auto-detect if omitted)
+     * - 'native': In-process module
+     * - 'stdio': Child process communication
+     * - 'broker': Remote service via broker
+     */
+    transport?: 'native' | 'stdio' | 'broker';
+    /**
+     * Version constraint (semver format)
+     * @example '^2.0.0', '>=1.5.0 <2.0.0'
+     */
+    version?: string;
+    /**
+     * Connection timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Use cached instance if available
+     * @default true
+     */
+    cached?: boolean;
+    /**
+     * Enable debug logging for this ability
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Authentication configuration
+ */
+export interface AuthConfig {
+    /**
+     * Authentication token
+     */
+    token?: string;
+    /**
+     * API key
+     */
+    apiKey?: string;
+    /**
+     * Additional authentication data
+     */
+    [key: string]: unknown;
+}
+/**
+ * Context provided to abilities running as stdio/native children.
+ *
+ * Abilities receive this context from their parent and can use it to:
+ * - Load other abilities with inherited configuration
+ * - Emit events to parent
+ * - Access parent's broker/auth/networks
+ *
+ * **Important:** Context only flows through stdio/native transport.
+ * Broker services are independent and have their own context.
+ *
+ * @example
+ * ```typescript
+ * // Inside an ability
+ * export class DataAnalyzer extends Ability {
+ *   async initialize() {
+ *     // Load child abilities using inherited context
+ *     this.mlModel = await this.context.load('ml-model');
+ *     this.database = await this.context.load('database');
+ *   }
+ *
+ *   async analyze(data: any) {
+ *     // Use loaded abilities
+ *     const predictions = await this.mlModel.predict(data);
+ *     await this.database.save(predictions);
+ *     return predictions;
+ *   }
+ * }
+ * ```
+ */
+export interface AbilityContext {
+    /**
+     * Ability name
+     */
+    readonly name: string;
+    /**
+     * Broker URL (inherited from parent)
+     *
+     * If the parent is connected to a broker, the child inherits this connection.
+     * The child can use this to load abilities via the broker.
+     *
+     * @example 'ws://broker.example.com'
+     */
+    readonly broker?: string;
+    /**
+     * Authentication configuration (inherited from parent)
+     *
+     * Child abilities inherit parent's authentication credentials.
+     * This enables seamless ability chaining without re-authentication.
+     */
+    readonly auth?: AuthConfig;
+    /**
+     * Network memberships (inherited from parent)
+     *
+     * Networks define visibility boundaries for abilities in the broker.
+     * Child abilities inherit parent's network memberships.
+     *
+     * @example ['global', 'team-alpha', 'production']
+     */
+    readonly networks?: readonly string[];
+    /**
+     * Parent ability name (for chain tracking)
+     *
+     * Identifies the immediate parent that loaded this ability.
+     * Useful for debugging and cycle detection.
+     *
+     * @example If Agent → Python Analyzer, parent is 'Agent'
+     */
+    readonly parent?: string;
+    /**
+     * Full chain from root to this ability
+     *
+     * Tracks the complete loading chain for debugging and cycle detection.
+     * Each ability in the chain adds itself to this array.
+     *
+     * @example ['js-agent', 'data-processor', 'ml-model']
+     */
+    readonly chain: readonly string[];
+    /**
+     * Load another ability with inherited context.
+     *
+     * **Context Inheritance (Stdio/Native only):**
+     * - broker, auth, networks are inherited from this context
+     * - Chain is extended with the new ability
+     * - Cycle detection prevents infinite loops
+     *
+     * **Broker Services (Independent):**
+     * - When loading via broker, service has its own context
+     * - No configuration inheritance
+     * - Services are autonomous
+     *
+     * @param name - Ability name to load
+     * @param options - Loading options (transport, version, etc.)
+     * @returns Promise resolving to loaded ability proxy
+     *
+     * @throws {AbilityNotFoundError} If ability not found
+     * @throws {CircularDependencyError} If loading would create a cycle
+     * @throws {ConnectionError} If connection fails
+     *
+     * @example
+     * ```typescript
+     * // Load with auto-detection
+     * const helper = await context.load('helper-service');
+     *
+     * // Force specific transport
+     * const localScript = await context.load('script', { transport: 'stdio' });
+     *
+     * // With version constraint
+     * const mlModel = await context.load('ml-model', { version: '^2.0.0' });
+     * ```
+     */
+    load(name: string, options?: LoadOptions): Promise<LoadedAbility>;
+    /**
+     * Emit events to parent.
+     *
+     * Allows child abilities to communicate with their parent via events.
+     * Useful for progress updates, notifications, and status changes.
+     *
+     * @param event - Event name
+     * @param data - Event data
+     *
+     * @example
+     * ```typescript
+     * // Inside an ability
+     * context.emit('progress', { percent: 50 });
+     * context.emit('warning', { message: 'Low memory' });
+     * context.emit('completed', { result: data });
+     * ```
+     */
+    emit(event: string, data: unknown): void;
+}
+/**
+ * Create an AbilityContext from parent information.
+ *
+ * Used internally when spawning stdio child processes or loading native abilities.
+ *
+ * @param config - Context configuration
+ * @returns AbilityContext instance
+ *
+ * @internal
+ */
+export declare function createAbilityContext(config: {
+    name: string;
+    broker?: string;
+    auth?: AuthConfig;
+    networks?: string[];
+    parent?: string;
+    chain?: string[];
+    loadFn: (name: string, options?: LoadOptions) => Promise<LoadedAbility>;
+    emitFn: (event: string, data: unknown) => void;
+}): AbilityContext;
+//# sourceMappingURL=AbilityContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AbilityContext.d.ts","sourceRoot":"","sources":["../../src/abilities/AbilityContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAE1C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElE;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IACxE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CAChD,GAAG,cAAc,CAWjB"}

package/dist/abilities/AbilityContext.js

@@ -0,0 +1,36 @@
+/**
+ * Ability Context
+ * ================
+ *
+ * Context provided to abilities when running in stdio or native mode.
+ * Enables abilities to load other abilities with inherited configuration.
+ *
+ * **Context Flow:**
+ * - Native/Stdio: Context flows from parent to child
+ * - Broker: Services are independent (no context inheritance)
+ *
+ * @module abilities/AbilityContext
+ */
+/**
+ * Create an AbilityContext from parent information.
+ *
+ * Used internally when spawning stdio child processes or loading native abilities.
+ *
+ * @param config - Context configuration
+ * @returns AbilityContext instance
+ *
+ * @internal
+ */
+export function createAbilityContext(config) {
+    return {
+        name: config.name,
+        broker: config.broker,
+        auth: config.auth,
+        networks: config.networks ? [...config.networks] : undefined,
+        parent: config.parent,
+        chain: config.chain ? [...config.chain, config.name] : [config.name],
+        load: config.loadFn,
+        emit: config.emitFn
+    };
+}
+//# sourceMappingURL=AbilityContext.js.map

package/dist/abilities/AbilityContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbilityContext.js","sourceRoot":"","sources":["../../src/abilities/AbilityContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwMH;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,MASpC;IACC,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;QAC5D,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;QACpE,IAAI,EAAE,MAAM,CAAC,MAAM;QACnB,IAAI,EAAE,MAAM,CAAC,MAAM;KACpB,CAAC;AACJ,CAAC"}

package/dist/abilities/AbilityLoader.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Ability Loader
+ *
+ * Orchestrates ability loading with excellent developer experience:
+ * - Smart transport inference (auto-detect or explicit)
+ * - Intelligent caching (composite keys)
+ * - Runtime validation (catch issues early)
+ * - Helpful error messages (actionable suggestions)
+ *
+ * @module abilities/AbilityLoader
+ */
+import type { LoadOptions, TransportType } from './types.js';
+import { type IBrokerClient } from '../transports/BrokerTransport.js';
+import { type LoadedAbility } from './AbilityProxy.js';
+/**
+ * Ability Loader
+ *
+ * Orchestrates the complete ability loading process:
+ * - Transport inference (smart auto-detection)
+ * - Caching (avoid duplicate loads)
+ * - Transport creation (factory pattern)
+ * - Validation (runtime checks)
+ * - Error handling (helpful messages)
+ *
+ * Single responsibility: Load abilities, nothing else.
+ *
+ * @example
+ * ```typescript
+ * const loader = new AbilityLoader();
+ *
+ * // Auto-detect (recommended)
+ * const calc = await loader.load('calculator', {}, brokerClient);
+ *
+ * // Explicit transport
+ * const remote = await loader.load('service', {
+ *   transport: 'broker',
+ *   networks: ['global']
+ * }, brokerClient);
+ *
+ * // With validation
+ * const typed = await loader.load<CalcAPI>('calc', {
+ *   validate: true
+ * }, brokerClient);
+ * ```
+ */
+export declare class AbilityLoader {
+    /**
+     * Ability cache with composite key strategy
+     *
+     * Handles complex scenarios:
+     * - Same name, different transports
+     * - Same name, different versions
+     * - Same name, different brokers
+     */
+    private cache;
+    /**
+     * Load an ability with explicit transport
+     *
+     * **Features:**
+     * - Explicit transport (no magic)
+     * - Smart caching (composite keys)
+     * - Runtime validation (optional)
+     * - Dynamic method access
+     *
+     * @param name - Ability name
+     * @param transport - Transport type (native, stdio, or broker)
+     * @param options - Load options (transport-specific)
+     * @param brokerClient - Broker client interface
+     * @returns Loaded ability with dynamic method access
+     *
+     * @throws {KadiError} If loading fails
+     *
+     * @example
+     * ```typescript
+     * // Broker transport
+     * const remote = await loader.load('service', 'broker', {
+     *   networks: ['global']
+     * }, brokerClient);
+     *
+     * // With runtime validation
+     * const calc = await loader.load('calc', 'broker', {
+     *   validate: true
+     * }, brokerClient);
+     *
+     * // Native transport
+     * const local = await loader.load('local-lib', 'native', {
+     *   path: './abilities/local-lib'
+     * });
+     * ```
+     */
+    load(name: string, transport: TransportType, options?: LoadOptions, brokerClient?: IBrokerClient): Promise<LoadedAbility>;
+    /**
+     * Unload all abilities
+     *
+     * Disconnects all transports and clears cache.
+     *
+     * @example
+     * ```typescript
+     * await loader.unloadAll();
+     * ```
+     */
+    unloadAll(): Promise<void>;
+    /**
+     * Get all loaded abilities
+     *
+     * @returns Array of loaded abilities
+     *
+     * @example
+     * ```typescript
+     * const abilities = loader.getAll();
+     * console.log(`Loaded ${abilities.length} abilities`);
+     * ```
+     */
+    getAll(): LoadedAbility[];
+    /**
+     * Get cache statistics
+     *
+     * Useful for debugging and monitoring.
+     *
+     * @returns Cache statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = loader.getStats();
+     * console.log(`Cached: ${stats.totalCached}, Connected: ${stats.connected}`);
+     * ```
+     */
+    getStats(): {
+        totalCached: number;
+        connected: number;
+        disconnected: number;
+        byTransport: Record<TransportType, number>;
+    };
+    /**
+     * Cleanup disconnected abilities
+     *
+     * Removes stale cache entries.
+     *
+     * @returns Number of stale entries removed
+     *
+     * @example
+     * ```typescript
+     * const removed = loader.cleanup();
+     * console.log(`Cleaned up ${removed} disconnected abilities`);
+     * ```
+     */
+    cleanup(): number;
+    /**
+     * Create appropriate transport instance
+     *
+     * Clean factory pattern - delegates to specialized creation methods.
+     * Each transport type has its own dedicated method with proper validation.
+     *
+     * @param name - Ability name
+     * @param transport - Transport type (from inference)
+     * @param options - Load options
+     * @param brokerClient - Broker client (for broker transport)
+     * @returns Transport instance ready to connect
+     *
+     * @throws {KadiError} If transport creation fails
+     */
+    private createTransport;
+    /**
+     * Create broker transport with excellent error handling
+     *
+     * Validates broker connection and creates transport with proper configuration.
+     *
+     * @param name - Ability name
+     * @param options - Load options (broker-specific)
+     * @param brokerClient - Broker client interface
+     * @returns Broker transport instance
+     *
+     * @throws {KadiError} If broker client missing or invalid config
+     */
+    private createBrokerTransport;
+    /**
+     * Create native transport with path validation
+     *
+     * Validates the ability path and creates a NativeTransport instance
+     * for in-process ability loading.
+     *
+     * @param name - Ability name
+     * @param options - Load options (native-specific)
+     * @returns Native transport instance
+     *
+     * @throws {KadiError} If path is missing or invalid
+     */
+    private createNativeTransport;
+    /**
+     * Create stdio transport with command validation
+     *
+     * Validates the command and creates a StdioTransport instance
+     * for spawning the ability as a child process.
+     *
+     * @param name - Ability name
+     * @param options - Load options (stdio-specific)
+     * @returns Stdio transport instance
+     *
+     * @throws {KadiError} If command is missing
+     */
+    private createStdioTransport;
+}
+//# sourceMappingURL=AbilityLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AbilityLoader.d.ts","sourceRoot":"","sources":["../../src/abilities/AbilityLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAuC,MAAM,YAAY,CAAC;AAGlG,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGvF,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAa;IACxB;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,CAAsB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,WAAgB,EACzB,YAAY,CAAC,EAAE,aAAa,GAC3B,OAAO,CAAC,aAAa,CAAC;IAwCzB;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBhC;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,EAAE;IAIzB;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;KAC5C;IAID;;;;;;;;;;;;OAYG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,eAAe;IA6BvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAiD7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAsC7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;CAuC7B"}