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

package/dist/abilities/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Ability Loading Types
+ *
+ * Clean, type-safe options for loading abilities using discriminated unions.
+ * TypeScript enforces that only relevant fields are used per transport type.
+ *
+ * @module abilities/types
+ */
+import type { KadiTool } from '../types/index.js';
+/**
+ * AgentJson - Runtime representation of agent.json file
+ *
+ * Both KADI agents and abilities have an `agent.json` file in their root directory.
+ * This interface represents the runtime structure returned by `readAgentJson()`.
+ *
+ * **Field Mapping:**
+ * - agent.json uses `exports` field (array of tool definitions)
+ * - Runtime uses `tools` field (clearer, more intuitive naming)
+ *
+ * **Purpose:**
+ * - Ability discovery: What tools does this provide?
+ * - Type generation: Generate TypeScript .d.ts files from agent.json
+ * - Validation: Check schemas before invocation
+ *
+ * **Source:** Extracted from agent.json at runtime via `KadiClient.readAgentJson()`
+ *
+ * @example
+ * ```typescript
+ * // agent.json file:
+ * {
+ *   "name": "calculator",
+ *   "version": "1.0.0",
+ *   "description": "Basic math operations",
+ *   "exports": [
+ *     { "name": "add", "description": "Add two numbers", ... }
+ *   ]
+ * }
+ *
+ * // Runtime representation:
+ * const agentJson = client.readAgentJson();
+ * // {
+ * //   name: 'calculator',
+ * //   version: '1.0.0',
+ * //   description: 'Basic math operations',
+ * //   tools: [{ name: 'add', ... }]  // ← mapped from 'exports'
+ * // }
+ * ```
+ */
+export interface AgentJson {
+    /**
+     * Agent/ability name from agent.json
+     *
+     * @example 'calculator', 'text-processor', 'my-agent'
+     */
+    name: string;
+    /**
+     * Semantic version from agent.json
+     *
+     * @example '1.0.0', '2.1.3'
+     */
+    version: string;
+    /**
+     * Human-readable description from agent.json
+     *
+     * @example 'Basic math operations'
+     */
+    description?: string;
+    /**
+     * List of tools provided by this agent/ability
+     *
+     * Mapped from agent.json's 'exports' field at runtime.
+     * We use 'tools' instead of 'exports' for clarity.
+     */
+    tools: KadiTool[];
+}
+/**
+ * Base options shared across all transports
+ *
+ * These options apply regardless of how the ability is loaded.
+ */
+interface BaseLoadOptions {
+    /**
+     * 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;
+    /**
+     * Validate loaded ability has expected methods
+     *
+     * When true, checks that ability exposes methods before returning.
+     * Catches mismatches early with helpful error messages.
+     *
+     * @default false
+     */
+    validate?: boolean;
+}
+/**
+ * Broker transport options
+ *
+ * Load ability from remote broker service.
+ * Service is already running independently with its own context.
+ *
+ * @example
+ * ```typescript
+ * const remote = await client.load('gpu-service', 'broker', {
+ *   networks: ['global', 'gpu-cluster']
+ * });
+ * ```
+ */
+export interface BrokerLoadOptions extends BaseLoadOptions {
+    /**
+     * Networks to search for the ability
+     *
+     * @default client's configured networks
+     */
+    networks?: string[];
+    /**
+     * Specific broker to use
+     *
+     * @default client's default broker
+     */
+    broker?: string;
+}
+/**
+ * Native transport options
+ *
+ * Load ability in same process (fastest, full type safety).
+ * Ability runs in same Node.js process as caller.
+ *
+ * @example
+ * ```typescript
+ * const local = await client.load('math-lib', 'native', {
+ *   path: './abilities/math'
+ * });
+ * ```
+ */
+export interface NativeLoadOptions extends BaseLoadOptions {
+    /**
+     * Path to ability module
+     *
+     * Can be:
+     * - Relative path: './abilities/math'
+     * - Absolute path: '/usr/local/lib/abilities/math'
+     * - Package name: '@kadi/math-ability'
+     */
+    path: string;
+}
+/**
+ * Stdio transport options
+ *
+ * Load ability as child process (any language).
+ * Context flows from parent to child (broker, auth, networks).
+ *
+ * @example
+ * ```typescript
+ * const analyzer = await client.load('python-analyzer', 'stdio', {
+ *   command: 'python3',
+ *   args: ['analyzer.py'],
+ *   env: { PYTHONPATH: './lib' }
+ * });
+ * ```
+ */
+export interface StdioLoadOptions extends BaseLoadOptions {
+    /**
+     * Command to execute
+     *
+     * @example 'python3', 'node', './my-script.sh'
+     */
+    command: string;
+    /**
+     * Command arguments
+     *
+     * @example ['main.py', '--verbose']
+     */
+    args?: string[];
+    /**
+     * Environment variables for child process
+     *
+     * @example { PYTHONPATH: './lib', DEBUG: 'true' }
+     */
+    env?: Record<string, string>;
+    /**
+     * Working directory for child process
+     *
+     * @default process.cwd()
+     */
+    cwd?: string;
+}
+/**
+ * Load options based on transport type
+ *
+ * Options are now transport-specific since transport is a separate parameter.
+ * TypeScript will enforce correct options based on the transport you specify.
+ *
+ * @example
+ * ```typescript
+ * // Broker transport with options
+ * await client.load('ability', 'broker', { networks: ['global'] });
+ *
+ * // Native transport with path (required)
+ * await client.load('ability', 'native', { path: './local' });
+ *
+ * // Stdio transport with command (required)
+ * await client.load('ability', 'stdio', { command: 'python3', args: ['main.py'] });
+ *
+ * // Minimal broker - just base options
+ * await client.load('calculator', 'broker', { validate: true });
+ * ```
+ */
+export type LoadOptions<T extends TransportType = TransportType> = T extends 'broker' ? BrokerLoadOptions : T extends 'native' ? NativeLoadOptions : T extends 'stdio' ? StdioLoadOptions : BaseLoadOptions;
+/**
+ * Transport type for ability loading
+ */
+export type TransportType = 'native' | 'stdio' | 'broker';
+export {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/abilities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,UAAU,eAAe;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAC7D,CAAC,SAAS,QAAQ,GAAG,iBAAiB,GACtC,CAAC,SAAS,QAAQ,GAAG,iBAAiB,GACtC,CAAC,SAAS,OAAO,GAAG,gBAAgB,GACpC,eAAe,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC"}

package/dist/abilities/types.js

@@ -0,0 +1,10 @@
+/**
+ * Ability Loading Types
+ *
+ * Clean, type-safe options for loading abilities using discriminated unions.
+ * TypeScript enforces that only relevant fields are used per transport type.
+ *
+ * @module abilities/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/abilities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/abilities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

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"}