@kadi.build/core 0.13.0 → 0.15.0

package/README.md

@@ -6,6 +6,7 @@ kadi-core lets you:
 - **Expose functions** as callable tools over the network
 - **Discover and invoke** remote services without hardcoding URLs
 - **Communicate via events** across your service mesh
+- **Load configuration** from `config.yml` with project → global fallback and env var overrides
 - **Manage agent.json** configuration across projects, abilities, and global scope
 - **Run background processes** with headless, piped, and JSON-RPC bridge modes
 - **Install as an ability** — use kadi-core itself as a dependency in any agent
@@ -59,7 +60,9 @@ Now another agent can load and use it:
 - [Serving as an Ability](#serving-as-an-ability)
 - [Agent.json Management](#agentjson-management)
 - [Process Manager](#process-manager)
+- [Encryption (Crypto)](#encryption-crypto)
 - [Installing as an Ability](#installing-as-an-ability)
+- [Configuration (loadConfig)](#configuration-loadconfig)
 - [Error Handling](#error-handling)
 - [API Reference](#api-reference)
 - [Troubleshooting](#troubleshooting)
@@ -210,6 +213,8 @@ const client = new KadiClient({
 
 This means abilities that use the native-mode pattern (connect first, then register tools locally) will correctly announce zero tools to the broker on reconnection, just as they did on the initial connect.
 
+**Event subscriptions on reconnection:** All broker event subscriptions (registered via `subscribe()`) are automatically re-established on reconnect. Your event handlers continue working transparently — no manual resubscription needed.
+
 If you dynamically register new tools after the initial connection and want the broker to know about them, call `refreshBrokerTools()`:
 
 ```typescript
@@ -227,6 +232,25 @@ await client.refreshBrokerTools();
 await client.refreshBrokerTools('production');
 ```
 
+### Lifecycle Hooks
+
+Register callbacks for broker connection lifecycle events:
+
+```typescript
+// Run cleanup logic when a broker disconnects
+client.onDisconnect((brokerName) => {
+  console.log(`Lost connection to ${brokerName}`);
+});
+
+// Run logic after a broker successfully reconnects
+client.onReconnect((brokerName) => {
+  console.log(`Reconnected to ${brokerName}`);
+  // Good place to refresh state, re-sync data, etc.
+});
+```
+
+Both hooks fire with the broker name and support async callbacks. Multiple hooks can be registered and will run in order. Errors in hooks are caught and logged — they won't break the reconnection flow.
+
 ---
 
 ## Loading Abilities
@@ -664,6 +688,55 @@ await pm.shutdown();
 
 ---
 
+## Encryption (Crypto)
+
+`client.crypto` provides NaCl sealed-box encryption for secure inter-agent communication. Sealed boxes let anyone encrypt a message using the recipient's public key — only the recipient can decrypt it. The sender remains anonymous (use API tokens or signatures for authentication).
+
+Keys are derived automatically from the agent's Ed25519 identity — no extra key management required.
+
+### Encrypting for Another Agent
+
+```typescript
+// Agent A encrypts secrets for Agent B
+const encrypted = agentA.crypto.encryptFor(
+  JSON.stringify({ API_KEY: 'sk-123', DB_PASS: 'hunter2' }),
+  agentB.publicKey  // Ed25519 identity key (auto-converted to X25519)
+);
+```
+
+### Decrypting
+
+```typescript
+// Agent B decrypts
+const plaintext = agentB.crypto.decrypt(encrypted);
+const secrets = JSON.parse(plaintext);
+```
+
+### Getting Your Encryption Public Key
+
+```typescript
+// X25519 encryption key (base64) — share this with senders
+const encryptionKey = client.crypto.publicKey;
+
+// Ed25519 identity key — the standard client.publicKey
+const identityKey = client.crypto.identityPublicKey;
+```
+
+### Key Format Auto-Detection
+
+`encryptFor()` accepts both key formats:
+
+- **Ed25519 SPKI DER base64** (44 bytes decoded) — the standard `client.publicKey` format, auto-converted to X25519
+- **Raw X25519 base64** (32 bytes decoded) — used directly, no conversion needed
+
+```typescript
+// Both work:
+client.crypto.encryptFor('secret', otherAgent.publicKey);        // Ed25519 → auto-converted
+client.crypto.encryptFor('secret', otherAgent.crypto.publicKey); // X25519 → used directly
+```
+
+---
+
 ## Installing as an Ability
 
 kadi-core v0.10.0 ships its own `agent.json` with `type: "ability"`, so it can be installed into any agent project using the standard `kadi install` workflow:
@@ -685,6 +758,102 @@ This is particularly useful for:
 
 ---
 
+## Configuration (loadConfig)
+
+Load settings from `config.yml` with a standardized 3-tier resolution:
+
+1. **Environment variables** — `PREFIX_KEY` (highest priority)
+2. **Project config.yml** — walk up from CWD to find the nearest `config.yml`
+3. **Global `~/.kadi/config.yml`** — shared KADI infrastructure settings
+4. **Built-in defaults** — hardcoded fallbacks (lowest priority)
+
+Secrets (API keys, tokens) should **never** go in `config.yml`. Use `kadi secret` for credentials.
+
+### Basic Usage
+
+```typescript
+import { loadConfig } from '@kadi.build/core';
+
+const { config, configPath, source } = loadConfig({
+  section: 'tunnel',
+  envPrefix: 'KADI_TUNNEL',
+  defaults: {
+    server_addr: 'kadi.build:7835',
+    tunnel_domain: 'tunnels.kadi.build',
+  },
+});
+
+console.log(config.server_addr);  // from config.yml or default
+console.log(configPath);           // '/path/to/config.yml' or null
+console.log(source);               // 'project' | 'global' | 'default'
+```
+
+With a `config.yml` like:
+
+```yaml
+tunnel:
+  server_addr: kadi.build:7835
+  tunnel_domain: tunnels.kadi.build
+
+memory:
+  database: kadi_memory
+  embedding_model: text-embedding-3-small
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `section` | `string` | *(required)* | Top-level YAML key to extract |
+| `startDir` | `string` | `process.cwd()` | Directory to start the upward walk |
+| `filename` | `string` | `'config.yml'` | Config filename to search for |
+| `envPrefix` | `string` | — | Env var prefix for automatic overrides |
+| `defaults` | `Record<string, unknown>` | `{}` | Built-in defaults (lowest priority) |
+
+### Environment Variable Overrides
+
+When `envPrefix` is set, loadConfig scans `process.env` for matching keys:
+
+```
+envPrefix: 'MEMORY'
+
+MEMORY_DATABASE=my_db        →  config.database = 'my_db'
+MEMORY_EMBEDDING_MODEL=ada   →  config.embedding_model = 'ada'
+```
+
+Values are coerced automatically: `"true"` → `true`, `"42"` → `42`, `"3.14"` → `3.14`.
+
+### File Discovery Helpers
+
+```typescript
+import { findConfigFile, findGlobalConfigFile } from '@kadi.build/core';
+
+// Walk up from CWD to find config.yml
+const projectConfig = findConfigFile();
+
+// Walk up from a specific directory
+const agentConfig = findConfigFile('config.yml', '/path/to/agent');
+
+// Check ~/.kadi/config.yml
+const globalConfig = findGlobalConfigFile();
+```
+
+### Result Type
+
+```typescript
+import type { ConfigResult, ConfigSource, LoadConfigOptions } from '@kadi.build/core';
+
+interface ConfigResult<T = Record<string, unknown>> {
+  config: T;              // Merged config object
+  configPath: string | null;  // Path to config.yml used, or null
+  source: ConfigSource;   // 'project' | 'global' | 'default'
+}
+```
+
+> **Note:** `loadConfig` requires `js-yaml` at runtime. It is lazy-imported — if your project doesn't use `loadConfig`, you don't need `js-yaml` installed.
+
+---
+
 ## Error Handling
 
 All errors are `KadiError` with structured codes and context:
@@ -767,6 +936,8 @@ new KadiClient(config: ClientConfig)
 | `emit(event, data)` | Emit event to consumer (when serving as ability) |
 | `serve(mode)` | Serve as ability (`'stdio'` or `'broker'`) |
 | `refreshBrokerTools(broker?)` | Recapture tool snapshot and re-announce to broker. See [Reconnection](#reconnection) |
+| `onDisconnect(hook)` | Register callback for broker disconnect. See [Lifecycle Hooks](#lifecycle-hooks) |
+| `onReconnect(hook)` | Register callback for broker reconnect. See [Lifecycle Hooks](#lifecycle-hooks) |
 | `getConnectedBrokers()` | List connected broker names |
 
 **Properties:**
@@ -775,6 +946,7 @@ new KadiClient(config: ClientConfig)
 |----------|------|-------------|
 | `agentJson` | `AgentJsonManager` | Lazy-initialized agent.json manager. See [Agent.json Management](#agentjson-management) |
 | `processes` | `ProcessManager` | Lazy-initialized process manager. See [Process Manager](#process-manager) |
+| `crypto` | `CryptoService` | Lazy-initialized encryption service. See [Encryption (Crypto)](#encryption-crypto) |
 
 ### LoadedAbility
 
@@ -895,6 +1067,24 @@ Returned by `ProcessManager.spawn()`. Extends `EventEmitter`.
 | `error` | `Error` | all |
 | `notification` | `{ method, params }` | bridge |
 
+### CryptoService
+
+Accessed via `client.crypto`. Lazy-initialized from the agent's Ed25519 identity keys.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `publicKey` | `string` | X25519 encryption public key (base64). Share with senders. Cached after first access |
+| `identityPublicKey` | `string` | Ed25519 identity public key (SPKI DER base64). Same as `client.publicKey` |
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `encryptFor(plaintext, recipientPublicKey)` | `string` | Encrypt string for recipient. Returns base64 sealed box. Accepts Ed25519 or X25519 keys |
+| `decrypt(ciphertext)` | `string` | Decrypt base64 sealed box. Throws on failure |
+
 ---
 
 ## Troubleshooting

package/agent.json

@@ -1,16 +1,16 @@
 {
   "name": "kadi-core",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "type": "ability",
   "license": "MIT",
   "description": "Core SDK for building KADI agents - provides client, transports, agent.json management, and process management",
   "entrypoint": "dist/index.js",
   "repo": "https://gitlab.com/humin-game-lab/agent-abilities/kadi-core.git",
-  "lib": "https://gitlab.com/humin-game-lab/agent-abilities/kadi-core/-/archive/v0.11.0/kadi-core-v0.11.0.zip",
+  "lib": "https://gitlab.com/humin-game-lab/agent-abilities/kadi-core/-/archive/v0.15.0/kadi-core-v0.15.0.zip",
   "abilities": {},
 
   "scripts": {
-    "preflight": "echo 'kadi-core v0.11.0 checking environment...'",
+    "preflight": "echo 'kadi-core v0.15.0 checking environment...'",
     "setup": "npm install && npm run build",
     "postinstall": "node scripts/symlink.mjs",
     "start": "echo 'kadi-core is a library - import it in your code'",

package/dist/client.d.ts

@@ -18,6 +18,7 @@ import { type EncryptionKeyPair } from './crypto.js';
 import type { ClientConfig, ClientIdentity, BrokerState, BrokerToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, ToolExecutionBridge, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
 import { AgentJsonManager } from './agent-json.js';
 import { ProcessManager } from './process-manager.js';
+import { CryptoService } from './crypto-service.js';
 /**
  * The main client for building KADI agents.
  *
@@ -65,10 +66,14 @@ export declare class KadiClient {
     private readonly loadedAbilities;
     /** Registered disconnect hooks */
     private readonly disconnectHooks;
+    /** Registered reconnect hooks */
+    private readonly reconnectHooks;
     /** Lazy-initialized AgentJsonManager */
     private _agentJson;
     /** Lazy-initialized ProcessManager */
     private _processes;
+    /** Lazy-initialized CryptoService */
+    private _crypto;
     /** Ed25519 private key (DER format) - used for signing */
     private readonly _privateKey;
     /** Base64-encoded Ed25519 public key (SPKI DER format) */
@@ -482,6 +487,23 @@ export declare class KadiClient {
      * Register a cleanup function to run on disconnect.
      */
     onDisconnect(hook: () => Promise<void>): void;
+    /**
+     * Register a hook to run after a successful broker reconnection.
+     *
+     * Event subscriptions are automatically re-established on reconnect,
+     * so most agents won't need this. Use it for additional recovery logic:
+     * re-fetching state, logging, sending a "I'm back" message, etc.
+     *
+     * @param hook - Called with the broker name after each successful reconnect.
+     *
+     * @example
+     * ```typescript
+     * client.onReconnect(async (brokerName) => {
+     *   console.log(`Reconnected to ${brokerName} — re-initializing state`);
+     * });
+     * ```
+     */
+    onReconnect(hook: (brokerName: string) => void | Promise<void>): void;
     /**
      * Disconnect from broker(s) and run registered cleanup hooks.
      *
@@ -743,6 +765,25 @@ export declare class KadiClient {
      * ```
      */
     get processes(): ProcessManager;
+    /**
+     * Access the CryptoService for encrypting/decrypting messages.
+     *
+     * Lazily created on first access. Uses NaCl sealed boxes (X25519 +
+     * XSalsa20-Poly1305) derived from this agent's Ed25519 identity keys.
+     *
+     * @example
+     * ```typescript
+     * // Encrypt a message for another agent
+     * const encrypted = client.crypto.encryptFor('secret', otherAgent.publicKey);
+     *
+     * // Decrypt a message sent to this agent
+     * const plaintext = client.crypto.decrypt(encrypted);
+     *
+     * // Get this agent's encryption public key (to share with others)
+     * const pubKey = client.crypto.publicKey;
+     * ```
+     */
+    get crypto(): CryptoService;
     /**
      * Get agent information (for readAgentJson protocol).
      */

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -28,6 +28,7 @@ import { loadStdioTransport } from './transports/stdio.js';
 import { loadBrokerTransport } from './transports/broker.js';
 import { AgentJsonManager } from './agent-json.js';
 import { ProcessManager } from './process-manager.js';
+import { CryptoService } from './crypto-service.js';
 // ═══════════════════════════════════════════════════════════════
 // CONSTANTS
 // ═══════════════════════════════════════════════════════════════
@@ -153,10 +154,14 @@ export class KadiClient {
     loadedAbilities = new Map();
     /** Registered disconnect hooks */
     disconnectHooks = [];
+    /** Registered reconnect hooks */
+    reconnectHooks = [];
     /** Lazy-initialized AgentJsonManager */
     _agentJson = null;
     /** Lazy-initialized ProcessManager */
     _processes = null;
+    /** Lazy-initialized CryptoService */
+    _crypto = null;
     // ─────────────────────────────────────────────────────────────
     // IDENTITY (single keypair shared across all broker connections)
     // ─────────────────────────────────────────────────────────────
@@ -1374,9 +1379,36 @@ export class KadiClient {
             await this.registerWithBroker(state);
             // Finalize connection (heartbeat + status)
             this.finalizeConnection(state);
+            // Re-subscribe event patterns that were active before disconnect.
+            // cleanupBroker() cleared subscribedPatterns but preserved eventHandlers,
+            // so we replay broker-side subscriptions for every pattern that still has handlers.
+            if (state.eventHandlers.size > 0) {
+                const patterns = [...state.eventHandlers.keys()];
+                console.error(`[KADI] Re-subscribing ${patterns.length} event pattern(s) on broker "${state.name}"`);
+                for (const pattern of patterns) {
+                    try {
+                        await this.sendRequest(state, protocol.eventSubscribe(this.nextRequestId++, pattern));
+                        state.subscribedPatterns.add(pattern);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        console.error(`[KADI] Failed to re-subscribe "${pattern}" on broker "${state.name}": ${msg}`);
+                    }
+                }
+            }
             // Success!
             console.error(`[KADI] Reconnected to broker "${state.name}" after ${state.reconnectAttempts} attempts`);
             state.reconnectAttempts = 0;
+            // Fire reconnect hooks (best-effort, don't let a failing hook break reconnect)
+            for (const hook of this.reconnectHooks) {
+                try {
+                    await hook(state.name);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.error(`[KADI] Reconnect hook error for broker "${state.name}": ${msg}`);
+                }
+            }
         }
         catch (error) {
             // Log the error and try again
@@ -1396,6 +1428,25 @@ export class KadiClient {
     onDisconnect(hook) {
         this.disconnectHooks.push(hook);
     }
+    /**
+     * Register a hook to run after a successful broker reconnection.
+     *
+     * Event subscriptions are automatically re-established on reconnect,
+     * so most agents won't need this. Use it for additional recovery logic:
+     * re-fetching state, logging, sending a "I'm back" message, etc.
+     *
+     * @param hook - Called with the broker name after each successful reconnect.
+     *
+     * @example
+     * ```typescript
+     * client.onReconnect(async (brokerName) => {
+     *   console.log(`Reconnected to ${brokerName} — re-initializing state`);
+     * });
+     * ```
+     */
+    onReconnect(hook) {
+        this.reconnectHooks.push(hook);
+    }
     /**
      * Disconnect from broker(s) and run registered cleanup hooks.
      *
@@ -2067,6 +2118,33 @@ export class KadiClient {
         return this._processes;
     }
     // ─────────────────────────────────────────────────────────────
+    // CRYPTO SERVICE
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Access the CryptoService for encrypting/decrypting messages.
+     *
+     * Lazily created on first access. Uses NaCl sealed boxes (X25519 +
+     * XSalsa20-Poly1305) derived from this agent's Ed25519 identity keys.
+     *
+     * @example
+     * ```typescript
+     * // Encrypt a message for another agent
+     * const encrypted = client.crypto.encryptFor('secret', otherAgent.publicKey);
+     *
+     * // Decrypt a message sent to this agent
+     * const plaintext = client.crypto.decrypt(encrypted);
+     *
+     * // Get this agent's encryption public key (to share with others)
+     * const pubKey = client.crypto.publicKey;
+     * ```
+     */
+    get crypto() {
+        if (!this._crypto) {
+            this._crypto = new CryptoService(this._privateKey, this._publicKeyBase64);
+        }
+        return this._crypto;
+    }
+    // ─────────────────────────────────────────────────────────────
     // UTILITY
     // ─────────────────────────────────────────────────────────────
     /**