@kadi.build/core 0.12.0 → 0.13.0

package/README.md

@@ -206,6 +206,27 @@ const client = new KadiClient({
 });
 ```
 
+**Tool snapshot on reconnection:** When an agent first registers with a broker, kadi-core captures a snapshot of the tools sent during that initial registration. On every subsequent reconnection, the same snapshot is replayed — tools that were registered locally after the initial connection (e.g. via `loadNative`) are **not** leaked to the broker.
+
+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.
+
+If you dynamically register new tools after the initial connection and want the broker to know about them, call `refreshBrokerTools()`:
+
+```typescript
+// Register a new tool after the initial connection
+client.registerTool({
+  name: 'new-dynamic-tool',
+  description: 'Added at runtime',
+  input: z.object({ data: z.string() }),
+}, async ({ data }) => ({ result: data }));
+
+// Recapture the tool snapshot and re-announce to the broker
+await client.refreshBrokerTools();
+
+// Or target a specific broker
+await client.refreshBrokerTools('production');
+```
+
 ---
 
 ## Loading Abilities
@@ -745,6 +766,7 @@ new KadiClient(config: ClientConfig)
 | `publish(channel, data, options?)` | Publish event to broker |
 | `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) |
 | `getConnectedBrokers()` | List connected broker names |
 
 **Properties:**

package/dist/config.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Configuration loader for KADI agents and abilities.
+ *
+ * Provides standardized config.yml discovery with a 2-tier fallback:
+ *   1. **Project-level** — walk up from startDir looking for config.yml
+ *   2. **Global-level** — ~/.kadi/config.yml (shared KADI infrastructure settings)
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (PREFIX_KEY)
+ *   2. Project config.yml section
+ *   3. Global  config.yml section (~/.kadi/config.yml)
+ *   4. Built-in defaults
+ *
+ * Secrets (API keys, tokens) should NEVER appear in config.yml.
+ * Use secret-ability / kadi-secret for credentials.
+ *
+ * @example
+ * ```typescript
+ * import { loadConfig } from '@kadi.build/core';
+ *
+ * const { config, configPath, source } = loadConfig({
+ *   section: 'memory',
+ *   envPrefix: 'MEMORY',
+ *   defaults: { database: 'kadi_memory', embedding_model: 'text-embedding-3-small' },
+ * });
+ * ```
+ *
+ * TypeScript equivalent of: kadi-core-py/src/kadi/config.py
+ */
+/** How the config file was discovered. */
+export type ConfigSource = 'project' | 'global' | 'default';
+/** Options for {@link loadConfig}. */
+export interface LoadConfigOptions {
+    /**
+     * YAML section key to extract (e.g. `'tunnel'`, `'memory'`, `'kadi_agent'`).
+     * The top-level key in config.yml whose value becomes the config object.
+     */
+    section: string;
+    /**
+     * Directory to start the upward walk from.
+     * @default process.cwd()
+     */
+    startDir?: string;
+    /**
+     * Config filename to search for.
+     * @default 'config.yml'
+     */
+    filename?: string;
+    /**
+     * Environment variable prefix for automatic overrides.
+     *
+     * When set, loadConfig will scan `process.env` for keys starting with
+     * `PREFIX_` and merge them into the config (highest priority).
+     *
+     * Mapping: `PREFIX_KEY_NAME` → config field `key_name` (lowercased).
+     *
+     * @example envPrefix: 'MEMORY' → MEMORY_DATABASE overrides config.database
+     */
+    envPrefix?: string;
+    /**
+     * Built-in defaults (lowest priority).
+     * These are used when neither env vars nor config.yml provide a value.
+     */
+    defaults?: Record<string, unknown>;
+}
+/** Result of {@link loadConfig}. */
+export interface ConfigResult<T = Record<string, unknown>> {
+    /** Merged config object: env > project config.yml > global config.yml > defaults. */
+    config: T;
+    /** Absolute path to the config.yml that was loaded, or null if none found. */
+    configPath: string | null;
+    /** Where the primary config was found. */
+    source: ConfigSource;
+}
+/**
+ * Walk up the directory tree looking for a file.
+ *
+ * @param filename - File to search for (default: `'config.yml'`)
+ * @param startDir - Directory to start from (default: `process.cwd()`)
+ * @returns Absolute path if found, `null` otherwise.
+ */
+export declare function findConfigFile(filename?: string, startDir?: string): string | null;
+/**
+ * Find the global KADI config file.
+ *
+ * @param filename - Config filename (default: `'config.yml'`)
+ * @returns Absolute path to `~/.kadi/<filename>` if it exists, `null` otherwise.
+ */
+export declare function findGlobalConfigFile(filename?: string): string | null;
+/**
+ * Load configuration for a KADI agent or ability.
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (`envPrefix` + `_KEY`)
+ *   2. Project `config.yml` section (walk-up from startDir)
+ *   3. Global `~/.kadi/config.yml` section
+ *   4. Built-in `defaults`
+ *
+ * @typeParam T - The shape of the merged config object.
+ * @param options - Configuration loading options.
+ * @returns Merged config with metadata about where it was found.
+ *
+ * @example
+ * ```typescript
+ * const { config } = loadConfig<TunnelConfig>({
+ *   section: 'tunnel',
+ *   envPrefix: 'KADI_TUNNEL',
+ *   defaults: { default_service: 'kadi', server_port: 7000 },
+ * });
+ * ```
+ */
+export declare function loadConfig<T = Record<string, unknown>>(options: LoadConfigOptions): ConfigResult<T>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAuDH,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvD,qFAAqF;IACrF,MAAM,EAAE,CAAC,CAAC;IACV,8EAA8E;IAC9E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0CAA0C;IAC1C,MAAM,EAAE,YAAY,CAAC;CACtB;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAyB,EACnC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAmBf;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,GAAE,MAAyB,GAClC,MAAM,GAAG,IAAI,CAUf;AAgFD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,OAAO,EAAE,iBAAiB,GACzB,YAAY,CAAC,CAAC,CAAC,CAsDjB"}

package/dist/config.js

@@ -0,0 +1,271 @@
+/**
+ * Configuration loader for KADI agents and abilities.
+ *
+ * Provides standardized config.yml discovery with a 2-tier fallback:
+ *   1. **Project-level** — walk up from startDir looking for config.yml
+ *   2. **Global-level** — ~/.kadi/config.yml (shared KADI infrastructure settings)
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (PREFIX_KEY)
+ *   2. Project config.yml section
+ *   3. Global  config.yml section (~/.kadi/config.yml)
+ *   4. Built-in defaults
+ *
+ * Secrets (API keys, tokens) should NEVER appear in config.yml.
+ * Use secret-ability / kadi-secret for credentials.
+ *
+ * @example
+ * ```typescript
+ * import { loadConfig } from '@kadi.build/core';
+ *
+ * const { config, configPath, source } = loadConfig({
+ *   section: 'memory',
+ *   envPrefix: 'MEMORY',
+ *   defaults: { database: 'kadi_memory', embedding_model: 'text-embedding-3-small' },
+ * });
+ * ```
+ *
+ * TypeScript equivalent of: kadi-core-py/src/kadi/config.py
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+// ═══════════════════════════════════════════════════════════════════════
+// YAML import — optional runtime dependency
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * We lazy-import js-yaml so that kadi-core does NOT require it as a hard
+ * dependency.  Consumers that use loadConfig() need js-yaml installed;
+ * everything else in kadi-core works without it.
+ *
+ * In practice every KADI agent/ability already has js-yaml, so this is
+ * a formality rather than a real constraint.
+ */
+let yaml = null;
+let yamlResolved = false;
+function requireYaml() {
+    if (!yamlResolved) {
+        yamlResolved = true;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            yaml = require('js-yaml');
+        }
+        catch {
+            try {
+                // ESM fallback — createRequire for pure-ESM environments
+                const { createRequire } = require('node:module');
+                const localRequire = createRequire(process.cwd() + '/');
+                yaml = localRequire('js-yaml');
+            }
+            catch {
+                yaml = null;
+            }
+        }
+    }
+    return yaml;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════
+/** Default config filename. */
+const DEFAULT_FILENAME = 'config.yml';
+/** Global KADI config directory. */
+const GLOBAL_KADI_DIR = path.join(os.homedir(), '.kadi');
+// ═══════════════════════════════════════════════════════════════════════
+// File discovery
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Walk up the directory tree looking for a file.
+ *
+ * @param filename - File to search for (default: `'config.yml'`)
+ * @param startDir - Directory to start from (default: `process.cwd()`)
+ * @returns Absolute path if found, `null` otherwise.
+ */
+export function findConfigFile(filename = DEFAULT_FILENAME, startDir) {
+    let dir = path.resolve(startDir ?? process.cwd());
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const candidate = path.join(dir, filename);
+        try {
+            if (fs.statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        catch {
+            // Not found, keep walking
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // Filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Find the global KADI config file.
+ *
+ * @param filename - Config filename (default: `'config.yml'`)
+ * @returns Absolute path to `~/.kadi/<filename>` if it exists, `null` otherwise.
+ */
+export function findGlobalConfigFile(filename = DEFAULT_FILENAME) {
+    const globalPath = path.join(GLOBAL_KADI_DIR, filename);
+    try {
+        if (fs.statSync(globalPath).isFile()) {
+            return globalPath;
+        }
+    }
+    catch {
+        // Not found
+    }
+    return null;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Section extraction
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Parse a YAML file and extract a top-level section.
+ */
+function readSection(filePath, section) {
+    const lib = requireYaml();
+    if (!lib)
+        return {};
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const parsed = lib.load(content);
+        if (!parsed || typeof parsed !== 'object')
+            return {};
+        const sectionData = parsed[section];
+        if (!sectionData || typeof sectionData !== 'object')
+            return {};
+        return sectionData;
+    }
+    catch {
+        return {};
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Environment variable overlay
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Build an overrides object from environment variables matching a prefix.
+ *
+ * `PREFIX_KEY_NAME=value` → `{ key_name: value }`
+ *
+ * Numeric strings are auto-coerced to numbers.
+ * `'true'` / `'false'` are coerced to booleans.
+ */
+function envOverrides(prefix, knownKeys) {
+    const result = {};
+    const prefixUpper = prefix.toUpperCase() + '_';
+    for (const [envKey, envVal] of Object.entries(process.env)) {
+        if (!envKey.startsWith(prefixUpper) || envVal === undefined)
+            continue;
+        const configKey = envKey.slice(prefixUpper.length).toLowerCase();
+        // Skip if we have a known-keys set and this key isn't in it
+        if (knownKeys && !knownKeys.has(configKey))
+            continue;
+        result[configKey] = coerce(envVal);
+    }
+    return result;
+}
+/**
+ * Coerce a string environment value to its natural JS type.
+ */
+function coerce(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === '')
+        return value;
+    // Attempt numeric coercion only for things that look numeric
+    const num = Number(value);
+    if (!Number.isNaN(num) && value.trim() !== '')
+        return num;
+    return value;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Main API
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Load configuration for a KADI agent or ability.
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (`envPrefix` + `_KEY`)
+ *   2. Project `config.yml` section (walk-up from startDir)
+ *   3. Global `~/.kadi/config.yml` section
+ *   4. Built-in `defaults`
+ *
+ * @typeParam T - The shape of the merged config object.
+ * @param options - Configuration loading options.
+ * @returns Merged config with metadata about where it was found.
+ *
+ * @example
+ * ```typescript
+ * const { config } = loadConfig<TunnelConfig>({
+ *   section: 'tunnel',
+ *   envPrefix: 'KADI_TUNNEL',
+ *   defaults: { default_service: 'kadi', server_port: 7000 },
+ * });
+ * ```
+ */
+export function loadConfig(options) {
+    const { section, startDir, filename = DEFAULT_FILENAME, envPrefix, defaults = {}, } = options;
+    // ── Layer 4: Defaults ──────────────────────────────────────────────
+    let merged = { ...defaults };
+    // ── Layer 3: Global config.yml (~/.kadi/config.yml) ────────────────
+    let configPath = null;
+    let source = 'default';
+    const globalPath = findGlobalConfigFile(filename);
+    if (globalPath) {
+        const globalSection = readSection(globalPath, section);
+        if (Object.keys(globalSection).length > 0) {
+            merged = shallowMerge(merged, globalSection);
+            configPath = globalPath;
+            source = 'global';
+        }
+    }
+    // ── Layer 2: Project config.yml (walk-up) ──────────────────────────
+    const projectPath = findConfigFile(filename, startDir);
+    if (projectPath) {
+        // Only use project config if it's not the same file as global
+        const isDistinct = !globalPath || path.resolve(projectPath) !== path.resolve(globalPath);
+        if (isDistinct) {
+            const projectSection = readSection(projectPath, section);
+            if (Object.keys(projectSection).length > 0) {
+                merged = shallowMerge(merged, projectSection);
+                configPath = projectPath;
+                source = 'project';
+            }
+        }
+    }
+    // ── Layer 1: Environment variables (highest priority) ──────────────
+    if (envPrefix) {
+        const env = envOverrides(envPrefix);
+        if (Object.keys(env).length > 0) {
+            merged = shallowMerge(merged, env);
+        }
+    }
+    return {
+        config: merged,
+        configPath,
+        source,
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * Shallow merge — source keys overwrite target keys.
+ * Only copies defined (non-undefined) values.
+ */
+function shallowMerge(target, source) {
+    const result = { ...target };
+    for (const [key, val] of Object.entries(source)) {
+        if (val !== undefined) {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export type { ClientConfig, BrokerEntry, ResolvedConfig, ToolDefinition, BrokerT
 export { AgentJsonManager } from './agent-json.js';
 export { ProcessManager, ManagedProcess } from './process-manager.js';
 export { getByPath, setByPath, deleteByPath, deepMerge } from './utils.js';
+export { loadConfig, findConfigFile, findGlobalConfigFile } from './config.js';
+export type { LoadConfigOptions, ConfigResult, ConfigSource } from './config.js';
 export { StdioMessageReader, StdioMessageWriter } from './stdio-framing.js';
 export { zodToJsonSchema, isZodSchema } from './zod.js';
 export { findProjectRoot, readLockFile, findAbilityEntry, resolveAbilityPath, resolveAbilityEntry, getInstalledAbilityNames, } from './lockfile.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3D,YAAY,EAEV,YAAY,EACZ,WAAW,EACX,cAAc,EAGd,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,UAAU,EACV,cAAc,EAGd,aAAa,EACb,aAAa,EACb,aAAa,EACb,YAAY,EAGZ,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAGnB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,iBAAiB,EAGjB,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EAGX,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,cAAc,EAGd,aAAa,EACb,gBAAgB,EAGhB,cAAc,EAGd,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,cAAc,EAGd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG3E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG5E,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGxD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGrE,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAG1C,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3D,YAAY,EAEV,YAAY,EACZ,WAAW,EACX,cAAc,EAGd,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,UAAU,EACV,cAAc,EAGd,aAAa,EACb,aAAa,EACb,aAAa,EACb,YAAY,EAGZ,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAGnB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,iBAAiB,EAGjB,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EAGX,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,cAAc,EAGd,aAAa,EACb,gBAAgB,EAGhB,cAAc,EAGd,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,cAAc,EAGd,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG3E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGjF,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG5E,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAGxD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGrE,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAG1C,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -36,6 +36,8 @@ export { AgentJsonManager } from './agent-json.js';
 export { ProcessManager, ManagedProcess } from './process-manager.js';
 // Dot-path utilities
 export { getByPath, setByPath, deleteByPath, deepMerge } from './utils.js';
+// Config loader (walk-up config.yml + ~/.kadi/ global fallback)
+export { loadConfig, findConfigFile, findGlobalConfigFile } from './config.js';
 // Stdio framing (for advanced use cases — building custom bridge protocols)
 export { StdioMessageReader, StdioMessageWriter } from './stdio-framing.js';
 // Zod utilities

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uCAAuC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc;AACd,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAiFxC,qBAAqB;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtE,qBAAqB;AACrB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3E,4EAA4E;AAC5E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,gBAAgB;AAChB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD,sBAAsB;AACtB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,sCAAsC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,4BAA4B;AAC5B,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,kDAAkD;AAClD,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,uCAAuC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc;AACd,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS;AACT,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAiFxC,qBAAqB;AACrB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtE,qBAAqB;AACrB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE3E,gEAAgE;AAChE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAG/E,4EAA4E;AAC5E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,gBAAgB;AAChB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD,sBAAsB;AACtB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,sCAAsC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7D,4BAA4B;AAC5B,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,kDAAkD;AAClD,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kadi.build/core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "A lean, readable SDK for building KADI agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/config.ts

@@ -0,0 +1,368 @@
+/**
+ * Configuration loader for KADI agents and abilities.
+ *
+ * Provides standardized config.yml discovery with a 2-tier fallback:
+ *   1. **Project-level** — walk up from startDir looking for config.yml
+ *   2. **Global-level** — ~/.kadi/config.yml (shared KADI infrastructure settings)
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (PREFIX_KEY)
+ *   2. Project config.yml section
+ *   3. Global  config.yml section (~/.kadi/config.yml)
+ *   4. Built-in defaults
+ *
+ * Secrets (API keys, tokens) should NEVER appear in config.yml.
+ * Use secret-ability / kadi-secret for credentials.
+ *
+ * @example
+ * ```typescript
+ * import { loadConfig } from '@kadi.build/core';
+ *
+ * const { config, configPath, source } = loadConfig({
+ *   section: 'memory',
+ *   envPrefix: 'MEMORY',
+ *   defaults: { database: 'kadi_memory', embedding_model: 'text-embedding-3-small' },
+ * });
+ * ```
+ *
+ * TypeScript equivalent of: kadi-core-py/src/kadi/config.py
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+// ═══════════════════════════════════════════════════════════════════════
+// YAML import — optional runtime dependency
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * We lazy-import js-yaml so that kadi-core does NOT require it as a hard
+ * dependency.  Consumers that use loadConfig() need js-yaml installed;
+ * everything else in kadi-core works without it.
+ *
+ * In practice every KADI agent/ability already has js-yaml, so this is
+ * a formality rather than a real constraint.
+ */
+let yaml: { load(content: string): unknown } | null = null;
+let yamlResolved = false;
+
+function requireYaml(): typeof yaml {
+  if (!yamlResolved) {
+    yamlResolved = true;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      yaml = require('js-yaml') as typeof yaml;
+    } catch {
+      try {
+        // ESM fallback — createRequire for pure-ESM environments
+        const { createRequire } = require('node:module');
+        const localRequire = createRequire(process.cwd() + '/');
+        yaml = localRequire('js-yaml') as typeof yaml;
+      } catch {
+        yaml = null;
+      }
+    }
+  }
+  return yaml;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════════
+
+/** Default config filename. */
+const DEFAULT_FILENAME = 'config.yml';
+
+/** Global KADI config directory. */
+const GLOBAL_KADI_DIR = path.join(os.homedir(), '.kadi');
+
+// ═══════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════
+
+/** How the config file was discovered. */
+export type ConfigSource = 'project' | 'global' | 'default';
+
+/** Options for {@link loadConfig}. */
+export interface LoadConfigOptions {
+  /**
+   * YAML section key to extract (e.g. `'tunnel'`, `'memory'`, `'kadi_agent'`).
+   * The top-level key in config.yml whose value becomes the config object.
+   */
+  section: string;
+
+  /**
+   * Directory to start the upward walk from.
+   * @default process.cwd()
+   */
+  startDir?: string;
+
+  /**
+   * Config filename to search for.
+   * @default 'config.yml'
+   */
+  filename?: string;
+
+  /**
+   * Environment variable prefix for automatic overrides.
+   *
+   * When set, loadConfig will scan `process.env` for keys starting with
+   * `PREFIX_` and merge them into the config (highest priority).
+   *
+   * Mapping: `PREFIX_KEY_NAME` → config field `key_name` (lowercased).
+   *
+   * @example envPrefix: 'MEMORY' → MEMORY_DATABASE overrides config.database
+   */
+  envPrefix?: string;
+
+  /**
+   * Built-in defaults (lowest priority).
+   * These are used when neither env vars nor config.yml provide a value.
+   */
+  defaults?: Record<string, unknown>;
+}
+
+/** Result of {@link loadConfig}. */
+export interface ConfigResult<T = Record<string, unknown>> {
+  /** Merged config object: env > project config.yml > global config.yml > defaults. */
+  config: T;
+  /** Absolute path to the config.yml that was loaded, or null if none found. */
+  configPath: string | null;
+  /** Where the primary config was found. */
+  source: ConfigSource;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// File discovery
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Walk up the directory tree looking for a file.
+ *
+ * @param filename - File to search for (default: `'config.yml'`)
+ * @param startDir - Directory to start from (default: `process.cwd()`)
+ * @returns Absolute path if found, `null` otherwise.
+ */
+export function findConfigFile(
+  filename: string = DEFAULT_FILENAME,
+  startDir?: string,
+): string | null {
+  let dir = path.resolve(startDir ?? process.cwd());
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = path.join(dir, filename);
+    try {
+      if (fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      // Not found, keep walking
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // Filesystem root
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Find the global KADI config file.
+ *
+ * @param filename - Config filename (default: `'config.yml'`)
+ * @returns Absolute path to `~/.kadi/<filename>` if it exists, `null` otherwise.
+ */
+export function findGlobalConfigFile(
+  filename: string = DEFAULT_FILENAME,
+): string | null {
+  const globalPath = path.join(GLOBAL_KADI_DIR, filename);
+  try {
+    if (fs.statSync(globalPath).isFile()) {
+      return globalPath;
+    }
+  } catch {
+    // Not found
+  }
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Section extraction
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse a YAML file and extract a top-level section.
+ */
+function readSection(
+  filePath: string,
+  section: string,
+): Record<string, unknown> {
+  const lib = requireYaml();
+  if (!lib) return {};
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const parsed = lib.load(content) as Record<string, unknown> | null;
+    if (!parsed || typeof parsed !== 'object') return {};
+    const sectionData = parsed[section];
+    if (!sectionData || typeof sectionData !== 'object') return {};
+    return sectionData as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Environment variable overlay
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Build an overrides object from environment variables matching a prefix.
+ *
+ * `PREFIX_KEY_NAME=value` → `{ key_name: value }`
+ *
+ * Numeric strings are auto-coerced to numbers.
+ * `'true'` / `'false'` are coerced to booleans.
+ */
+function envOverrides(
+  prefix: string,
+  knownKeys?: Set<string>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const prefixUpper = prefix.toUpperCase() + '_';
+
+  for (const [envKey, envVal] of Object.entries(process.env)) {
+    if (!envKey.startsWith(prefixUpper) || envVal === undefined) continue;
+
+    const configKey = envKey.slice(prefixUpper.length).toLowerCase();
+
+    // Skip if we have a known-keys set and this key isn't in it
+    if (knownKeys && !knownKeys.has(configKey)) continue;
+
+    result[configKey] = coerce(envVal);
+  }
+
+  return result;
+}
+
+/**
+ * Coerce a string environment value to its natural JS type.
+ */
+function coerce(value: string): unknown {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === '') return value;
+
+  // Attempt numeric coercion only for things that look numeric
+  const num = Number(value);
+  if (!Number.isNaN(num) && value.trim() !== '') return num;
+
+  return value;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Main API
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Load configuration for a KADI agent or ability.
+ *
+ * Resolution order per-field (highest-priority first):
+ *   1. Environment variables  (`envPrefix` + `_KEY`)
+ *   2. Project `config.yml` section (walk-up from startDir)
+ *   3. Global `~/.kadi/config.yml` section
+ *   4. Built-in `defaults`
+ *
+ * @typeParam T - The shape of the merged config object.
+ * @param options - Configuration loading options.
+ * @returns Merged config with metadata about where it was found.
+ *
+ * @example
+ * ```typescript
+ * const { config } = loadConfig<TunnelConfig>({
+ *   section: 'tunnel',
+ *   envPrefix: 'KADI_TUNNEL',
+ *   defaults: { default_service: 'kadi', server_port: 7000 },
+ * });
+ * ```
+ */
+export function loadConfig<T = Record<string, unknown>>(
+  options: LoadConfigOptions,
+): ConfigResult<T> {
+  const {
+    section,
+    startDir,
+    filename = DEFAULT_FILENAME,
+    envPrefix,
+    defaults = {},
+  } = options;
+
+  // ── Layer 4: Defaults ──────────────────────────────────────────────
+  let merged: Record<string, unknown> = { ...defaults };
+
+  // ── Layer 3: Global config.yml (~/.kadi/config.yml) ────────────────
+  let configPath: string | null = null;
+  let source: ConfigSource = 'default';
+
+  const globalPath = findGlobalConfigFile(filename);
+  if (globalPath) {
+    const globalSection = readSection(globalPath, section);
+    if (Object.keys(globalSection).length > 0) {
+      merged = shallowMerge(merged, globalSection);
+      configPath = globalPath;
+      source = 'global';
+    }
+  }
+
+  // ── Layer 2: Project config.yml (walk-up) ──────────────────────────
+  const projectPath = findConfigFile(filename, startDir);
+  if (projectPath) {
+    // Only use project config if it's not the same file as global
+    const isDistinct = !globalPath || path.resolve(projectPath) !== path.resolve(globalPath);
+    if (isDistinct) {
+      const projectSection = readSection(projectPath, section);
+      if (Object.keys(projectSection).length > 0) {
+        merged = shallowMerge(merged, projectSection);
+        configPath = projectPath;
+        source = 'project';
+      }
+    }
+  }
+
+  // ── Layer 1: Environment variables (highest priority) ──────────────
+  if (envPrefix) {
+    const env = envOverrides(envPrefix);
+    if (Object.keys(env).length > 0) {
+      merged = shallowMerge(merged, env);
+    }
+  }
+
+  return {
+    config: merged as T,
+    configPath,
+    source,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Shallow merge — source keys overwrite target keys.
+ * Only copies defined (non-undefined) values.
+ */
+function shallowMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...target };
+  for (const [key, val] of Object.entries(source)) {
+    if (val !== undefined) {
+      result[key] = val;
+    }
+  }
+  return result;
+}

package/src/index.ts

@@ -122,6 +122,10 @@ export { ProcessManager, ManagedProcess } from './process-manager.js';
 // Dot-path utilities
 export { getByPath, setByPath, deleteByPath, deepMerge } from './utils.js';
 
+// Config loader (walk-up config.yml + ~/.kadi/ global fallback)
+export { loadConfig, findConfigFile, findGlobalConfigFile } from './config.js';
+export type { LoadConfigOptions, ConfigResult, ConfigSource } from './config.js';
+
 // Stdio framing (for advanced use cases — building custom bridge protocols)
 export { StdioMessageReader, StdioMessageWriter } from './stdio-framing.js';