@kadi.build/core 0.9.0 → 0.11.0

package/README.md

@@ -1,11 +1,14 @@
 # kadi-core
 
-TypeScript SDK for building KADI agents. Register tools, connect to brokers, load abilities, publish events.
+TypeScript SDK for building KADI agents. Register tools, connect to brokers, load abilities, publish events, manage agent configuration, and run background processes.
 
 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
+- **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
 
 ## Install
 
@@ -54,6 +57,9 @@ Now another agent can load and use it:
 - [Events from Abilities](#events-from-abilities)
 - [Broker Events (Pub/Sub)](#broker-events-pubsub)
 - [Serving as an Ability](#serving-as-an-ability)
+- [Agent.json Management](#agentjson-management)
+- [Process Manager](#process-manager)
+- [Installing as an Ability](#installing-as-an-ability)
 - [Error Handling](#error-handling)
 - [API Reference](#api-reference)
 - [Troubleshooting](#troubleshooting)
@@ -400,6 +406,264 @@ await client.serve('broker');
 
 ---
 
+## Agent.json Management
+
+The `AgentJsonManager` provides unified read/write/delete access to `agent.json` files across three scopes:
+
+| Scope | Location | Use Case |
+|-------|----------|----------|
+| **Project** | `./agent.json` | Your agent's own configuration |
+| **Ability** | `./abilities/<name>@<version>/agent.json` | Installed ability configuration |
+| **Home** | `~/.kadi/agent.json` | Global CLI / user-level configuration |
+
+### Via KadiClient
+
+The client exposes a lazy `agentJson` property — no extra instantiation needed:
+
+```typescript
+const client = new KadiClient({ name: 'my-agent' });
+
+// Read the full project config
+const config = await client.agentJson.readProject();
+
+// Read a nested field with dot-path notation
+const target = await client.agentJson.readProject('deploy.local.target');
+
+// Write a nested field (deep-merges into existing data)
+await client.agentJson.writeProject('deploy.staging', {
+  target: 'akash',
+  replicas: 2,
+});
+
+// Delete a field
+await client.agentJson.deleteProject('deploy.staging');
+```
+
+### Standalone Usage
+
+You can also use `AgentJsonManager` directly without a client:
+
+```typescript
+import { AgentJsonManager } from '@kadi.build/core';
+
+const ajm = new AgentJsonManager({
+  projectRoot: '/path/to/my-agent',   // Optional, auto-detects via agent-lock.json
+  kadiHome: '~/.kadi',                // Optional, defaults to ~/.kadi
+  createOnWrite: true,                // Create file if missing on write (default: true)
+});
+
+const config = await ajm.readProject();
+```
+
+### Reading Ability Config
+
+```typescript
+// Read full config for an installed ability (resolves highest semver by default)
+const calcConfig = await client.agentJson.readAbility('calculator');
+
+// Read a specific field
+const scripts = await client.agentJson.readAbility('calculator', {
+  field: 'scripts.start',
+});
+
+// Pin to a specific version (useful when multiple versions are installed)
+const old = await client.agentJson.readAbility('calculator', {
+  version: '1.0.0',
+});
+```
+
+### Global Home Config
+
+```typescript
+// Read global KADI configuration
+const homeConfig = await client.agentJson.readHome();
+const defaultBroker = await client.agentJson.readHome('brokers.default');
+
+// Write to global config
+await client.agentJson.writeHome('brokers.staging', 'wss://staging.example.com/kadi');
+```
+
+### Discovery
+
+```typescript
+// List all installed abilities (reads agent-lock.json)
+const abilities = await client.agentJson.listAbilities();
+// [{ name: 'calculator', version: '1.0.0', path: '/abs/path/abilities/calculator@1.0.0' }, ...]
+
+// Check if an ability is installed
+const has = await client.agentJson.hasAbility('calculator');
+
+// Get all installed versions of an ability
+const versions = await client.agentJson.getAbilityVersions('calculator');
+// ['1.0.0', '2.0.0']
+
+// Get resolved paths for all three scopes
+const paths = await client.agentJson.getPaths();
+// { project: '/abs/path/agent.json', home: '/home/user/.kadi/agent.json' }
+```
+
+---
+
+## Process Manager
+
+The `ProcessManager` spawns and supervises background child processes in three modes:
+
+| Mode | Communication | Use Case |
+|------|--------------|----------|
+| **headless** | None | Fire-and-forget tasks (docker build, git clone) |
+| **piped** | stdout/stderr streaming | Tasks where you need live output (deploys, logs) |
+| **bridge** | JSON-RPC 2.0 over stdio | Interactive workers (inference engines, language servers) |
+
+### Via KadiClient
+
+```typescript
+const client = new KadiClient({ name: 'my-agent' });
+
+// Headless — fire and forget
+const build = await client.processes.spawn('build', {
+  command: 'docker',
+  args: ['build', '-t', 'myapp', '.'],
+  mode: 'headless',
+});
+
+// Check status later
+const status = client.processes.getStatus('build');
+console.log(status); // 'running' | 'exited' | 'killed' | 'errored'
+```
+
+### Piped Mode — Live Output
+
+```typescript
+const deploy = await client.processes.spawn('deploy', {
+  command: 'kadi',
+  args: ['deploy', '--target', 'akash'],
+  mode: 'piped',
+  cwd: '/path/to/project',
+  env: { KADI_ENV: 'production' },
+});
+
+// Stream stdout/stderr in real time
+deploy.on('stdout', (chunk) => process.stdout.write(chunk));
+deploy.on('stderr', (chunk) => process.stderr.write(chunk));
+deploy.on('exit', ({ exitCode }) => console.log('Deploy exited:', exitCode));
+
+// Get buffered output later
+const output = deploy.getOutput();
+console.log(output.stdout); // Full stdout string
+console.log(output.stderr); // Full stderr string
+```
+
+### Bridge Mode — JSON-RPC Workers
+
+Bridge mode wraps the child process in the same Content-Length framed JSON-RPC protocol used by stdio transports. This lets you send requests to the child and receive responses:
+
+```typescript
+const worker = await client.processes.spawn('inference', {
+  command: 'python3',
+  args: ['worker.py'],
+  mode: 'bridge',
+});
+
+// Send a JSON-RPC request and await the response
+const result = await worker.request('run-inference', {
+  model: 'llama3',
+  prompt: 'Explain kadi in one sentence',
+});
+console.log(result);
+
+// Fire-and-forget notification (no response expected)
+worker.notify('update-config', { temperature: 0.7 });
+
+// Listen for notifications from the worker
+worker.on('notification', ({ method, params }) => {
+  console.log(`Worker says: ${method}`, params);
+});
+```
+
+### Lifecycle Management
+
+```typescript
+// List all managed processes
+const all = client.processes.list();
+const running = client.processes.list({ mode: 'piped' }); // Filter by mode
+
+// Get a handle to an existing process
+const proc = client.processes.get('build');
+
+// Get detailed info
+const info = proc.getInfo();
+// { id: 'build', pid: 12345, mode: 'piped', state: 'running', startedAt: ... }
+
+// Kill a single process (SIGTERM → grace period → SIGKILL)
+await proc.kill();
+
+// Kill all managed processes
+await client.processes.killAll();
+
+// Wait for a process to exit
+const exitInfo = await proc.waitForExit();
+console.log(exitInfo.exitCode, exitInfo.signal);
+
+// Clean up exited/errored entries
+client.processes.prune();
+
+// Graceful shutdown — kills all and cleans up
+await client.processes.shutdown();
+```
+
+### Timeout Auto-Kill
+
+Processes can have an automatic timeout. When the timeout fires, the process is killed:
+
+```typescript
+const task = await client.processes.spawn('migration', {
+  command: 'node',
+  args: ['migrate.js'],
+  mode: 'piped',
+  timeout: 60000, // Kill after 60 seconds if still running
+});
+```
+
+### Standalone Usage
+
+```typescript
+import { ProcessManager } from '@kadi.build/core';
+
+const pm = new ProcessManager();
+
+const worker = await pm.spawn('worker', {
+  command: 'python3',
+  args: ['worker.py'],
+  mode: 'bridge',
+});
+
+const result = await worker.request('echo', { message: 'hello' });
+await pm.shutdown();
+```
+
+---
+
+## 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:
+
+```bash
+kadi install kadi-core
+```
+
+After installation, a `postinstall` script creates a symlink at `node_modules/@kadi.build/core` pointing to the installed ability directory. This means your code can use the standard import path regardless of where the ability lives on disk:
+
+```typescript
+import { KadiClient, z } from '@kadi.build/core';
+```
+
+This is particularly useful for:
+- **Python agents** (via `kadi-core-py`) that need a reference to kadi-core's protocol definitions
+- **Polyglot projects** that install abilities via `kadi install` rather than `npm install`
+- **Deployed agents** where abilities are resolved from `agent-lock.json`
+
+---
+
 ## Error Handling
 
 All errors are `KadiError` with structured codes and context:
@@ -430,6 +694,17 @@ try {
 | `BROKER_TIMEOUT` | Request to broker timed out |
 | `INVALID_CONFIG` | Configuration error (missing required fields, etc.) |
 | `LOCKFILE_NOT_FOUND` | `loadNative/loadStdio` when agent-lock.json doesn't exist |
+| `AGENT_JSON_NOT_FOUND` | `readProject/readAbility/readHome` when agent.json doesn't exist |
+| `AGENT_JSON_PARSE_ERROR` | agent.json exists but contains invalid JSON |
+| `AGENT_JSON_WRITE_ERROR` | Failed to write agent.json (permissions, disk, etc.) |
+| `AGENT_JSON_FIELD_NOT_FOUND` | Dot-path field doesn't exist in agent.json |
+| `AGENT_JSON_VERSION_AMBIGUOUS` | Multiple versions installed and no version specified |
+| `PROCESS_ALREADY_EXISTS` | `spawn()` with an ID that's already in use |
+| `PROCESS_NOT_FOUND` | `get()` / `getStatus()` with an unknown process ID |
+| `PROCESS_NOT_RUNNING` | `request()` / `notify()` on an exited process |
+| `PROCESS_BRIDGE_ERROR` | JSON-RPC communication error in bridge mode |
+| `PROCESS_SPAWN_FAILED` | Child process failed to start (bad command, permissions) |
+| `PROCESS_TIMEOUT` | Process exceeded its configured timeout |
 
 ---
 
@@ -472,6 +747,13 @@ new KadiClient(config: ClientConfig)
 | `serve(mode)` | Serve as ability (`'stdio'` or `'broker'`) |
 | `getConnectedBrokers()` | List connected broker names |
 
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `agentJson` | `AgentJsonManager` | Lazy-initialized agent.json manager. See [Agent.json Management](#agentjson-management) |
+| `processes` | `ProcessManager` | Lazy-initialized process manager. See [Process Manager](#process-manager) |
+
 ### LoadedAbility
 
 Returned by `loadNative()`, `loadStdio()`, `loadBroker()`:
@@ -500,6 +782,97 @@ interface BrokerEvent {
 }
 ```
 
+### AgentJsonManager
+
+```typescript
+new AgentJsonManager(options?: AgentJsonManagerOptions)
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `projectRoot` | `string` | auto-detect | Path to agent project root |
+| `kadiHome` | `string` | `~/.kadi` | Path to KADI home directory |
+| `createOnWrite` | `boolean` | `true` | Create agent.json if missing on write |
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `readProject(field?)` | `Promise<unknown>` | Read project agent.json (optional dot-path field) |
+| `readAbility(name, options?)` | `Promise<unknown>` | Read an installed ability's agent.json |
+| `readHome(field?)` | `Promise<unknown>` | Read global ~/.kadi/agent.json |
+| `writeProject(path, value)` | `Promise<void>` | Write/deep-merge a field in project agent.json |
+| `writeAbility(name, path, value, version?)` | `Promise<void>` | Write a field in an ability's agent.json |
+| `writeHome(path, value)` | `Promise<void>` | Write a field in global agent.json |
+| `deleteProject(path)` | `Promise<boolean>` | Delete a field from project agent.json |
+| `deleteAbility(name, path, version?)` | `Promise<boolean>` | Delete a field from an ability's agent.json |
+| `deleteHome(path)` | `Promise<boolean>` | Delete a field from global agent.json |
+| `listAbilities()` | `Promise<AbilityInfo[]>` | List all installed abilities |
+| `hasAbility(name)` | `Promise<boolean>` | Check if an ability is installed |
+| `getAbilityVersions(name)` | `Promise<string[]>` | Get installed versions of an ability |
+| `getPaths()` | `Promise<AgentJsonPaths>` | Get resolved file paths for all scopes |
+
+### ProcessManager
+
+```typescript
+new ProcessManager()
+```
+
+**Methods:**
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `spawn(id, options)` | `Promise<ManagedProcess>` | Spawn a new background process |
+| `get(id)` | `ManagedProcess` | Get handle to an existing process (throws if not found) |
+| `getStatus(id)` | `ProcessState` | Get process state: `'running'` \| `'exited'` \| `'killed'` \| `'errored'` |
+| `list(options?)` | `ManagedProcess[]` | List all managed processes (optional mode filter) |
+| `kill(id)` | `Promise<void>` | Kill a process by ID |
+| `killAll()` | `Promise<void>` | Kill all managed processes |
+| `shutdown()` | `Promise<void>` | Kill all and clean up |
+| `prune()` | `number` | Remove exited/errored entries, returns count pruned |
+
+**SpawnOptions:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `command` | `string` | required | Command to run |
+| `args` | `string[]` | `[]` | Command arguments |
+| `mode` | `ProcessMode` | required | `'headless'` \| `'piped'` \| `'bridge'` |
+| `cwd` | `string` | `process.cwd()` | Working directory |
+| `env` | `Record<string, string>` | inherited | Environment variables |
+| `timeout` | `number` | none | Auto-kill after N milliseconds |
+| `killGracePeriod` | `number` | `5000` | Time between SIGTERM and SIGKILL |
+
+### ManagedProcess
+
+Returned by `ProcessManager.spawn()`. Extends `EventEmitter`.
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `id` | Unique process identifier |
+| `pid` | OS process ID |
+| `mode` | `'headless'` \| `'piped'` \| `'bridge'` |
+| `state` | Current state: `'running'` \| `'exited'` \| `'killed'` \| `'errored'` |
+| `request(method, params?)` | **Bridge only.** Send JSON-RPC request, returns `Promise<unknown>` |
+| `notify(method, params?)` | **Bridge only.** Send JSON-RPC notification (no response) |
+| `write(data)` | Write raw data to stdin |
+| `kill()` | Kill the process (SIGTERM → grace → SIGKILL) |
+| `waitForExit()` | `Promise<ProcessExitInfo>` — resolves when process exits |
+| `getOutput()` | **Piped only.** Get buffered `{ stdout, stderr }` |
+| `getInfo()` | Get `ProcessInfo` snapshot |
+
+**Events:**
+
+| Event | Payload | Modes |
+|-------|---------|-------|
+| `stdout` | `string` | piped |
+| `stderr` | `string` | piped |
+| `exit` | `ProcessExitInfo` | all |
+| `error` | `Error` | all |
+| `notification` | `{ method, params }` | bridge |
+
 ---
 
 ## Troubleshooting
@@ -530,6 +903,19 @@ Increase the timeout:
 await client.invokeRemote('slow-tool', params, { timeout: 60000 });
 ```
 
+### AGENT_JSON_NOT_FOUND errors
+
+The manager can't find `agent.json` at the expected path. Either:
+- Ensure you're running from inside a project with `agent.json` and `agent-lock.json`
+- Pass an explicit `projectRoot` when constructing `AgentJsonManager`
+
+### PROCESS_BRIDGE_ERROR in bridge mode
+
+The child process isn't speaking the expected Content-Length framed JSON-RPC protocol. Ensure:
+1. The child writes `Content-Length: <n>\r\n\r\n<json>` to stdout
+2. The child reads the same framing from stdin
+3. No other output is mixed into stdout (use stderr for logging)
+
 ---
 
 ## Advanced: Building CLI Tools
@@ -575,6 +961,43 @@ const calcPath = resolveAbilityPath('calculator', root);
 // '/path/to/project/abilities/calculator@1.0.0'
 ```
 
+### Dot-Path Utilities
+
+Low-level helpers for nested object access (used internally by `AgentJsonManager`):
+
+```typescript
+import { getByPath, setByPath, deleteByPath, deepMerge } from '@kadi.build/core';
+
+const obj = { deploy: { local: { target: 'docker' } } };
+
+getByPath(obj, 'deploy.local.target');  // 'docker'
+setByPath(obj, 'deploy.staging.target', 'akash');
+deleteByPath(obj, 'deploy.local');
+
+// Deep merge (objects merged recursively, arrays replaced)
+const merged = deepMerge(
+  { deploy: { replicas: 1, target: 'docker' } },
+  { deploy: { replicas: 3 } },
+);
+// { deploy: { replicas: 3, target: 'docker' } }
+```
+
+### Stdio Framing
+
+For building custom Content-Length framed JSON-RPC protocols (used internally by stdio transport and bridge mode):
+
+```typescript
+import { StdioMessageReader, StdioMessageWriter } from '@kadi.build/core';
+
+// Wrap a readable stream (e.g., child.stdout)
+const reader = new StdioMessageReader(childProcess.stdout);
+reader.onMessage((msg) => console.log('Received:', msg));
+
+// Wrap a writable stream (e.g., child.stdin)
+const writer = new StdioMessageWriter(childProcess.stdin);
+writer.write({ jsonrpc: '2.0', method: 'ping', params: {} });
+```
+
 ---
 
 ## Related

package/agent.json

@@ -0,0 +1,19 @@
+{
+  "name": "kadi-core",
+  "version": "0.11.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",
+  "abilities": {},
+
+  "scripts": {
+    "preflight": "echo 'kadi-core v0.11.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'",
+    "stop": "echo 'kadi-core stopped'"
+  }
+}