@theaiinc/yggdrasil-ratatoskr 0.1.2 → 0.2.3

package/README.md

@@ -1,15 +1,10 @@
 # @theaiinc/yggdrasil-ratatoskr
 
-Lightweight discovery and heartbeat daemon for Yggdrasil runner registration.
+Lightweight runner daemon for Yggdrasil — registers, heartbeats, and executes tasks with configurable capability presets.
 
-Ratatoskr runs alongside an agent runner (any machine, anywhere) and continuously informs Yggdrasil about:
+Ratatoskr runs alongside any agent (Docker container, laptop, server) and continuously informs [Yggdrasil](https://www.npmjs.com/package/@theaiinc/yggdrasil) about runner availability, capabilities, health, and task execution. It can execute tasks itself using its built-in LLM, shell, web, code, and file handlers.
 
-- Runner availability
-- Network endpoints
-- Capabilities
-- Health status
-- IP changes
-- Shutdown events
+> **Version note**: `@theaiinc/yggdrasil-ratatoskr` and `@theaiinc/yggdrasil` are always released at the same version number.
 
 ## Installation
 
@@ -24,59 +19,89 @@ import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
 
 const ratatoskr = new Ratatoskr({
   yggdrasilUrl: 'http://localhost:3000',
-  apiKey: 'my-api-key',  // required if Yggdrasil has API_KEYS set
+  apiKey: 'my-api-key',
 });
 
 await ratatoskr.start();
 ```
 
-Within seconds, Yggdrasil automatically knows that the runner exists, where it lives, what it can do, and whether it is healthy.
+Within seconds, Yggdrasil knows the runner exists, its capabilities, endpoint, and health status.
 
-### Running via CLI (no TypeScript needed)
+### Capabilities are Presets
+
+Capabilities define what a runner can do. Each name is a **preset** that declares its dependencies (apt, npm), environment variables, config files, task handlers, and Docker build-time preparation steps. Presets compose transitively via `dependsOn`.
+
+Built-in presets (available by name):
+
+| Preset | Description | Handlers | Depends On |
+|--------|-------------|----------|------------|
+| `llm` | LLM inference via OpenAI-compatible API | `llm` | — |
+| `web_search` | Web search and fetch | `web_search`, `web_fetch` | — |
+| `shell` | Shell command execution | `shell` | — |
+| `agent` | Full sub-agent loop (think-act-execute) | `agent` | `llm`, `shell`, `web_search` |
+| `code` | Code generation and verification | `code` | `llm`, `shell`, `python`, `node_runtime` |
+| `python` | Python script execution | `python` | — |
+| `node_runtime` | Node.js script execution | `node` | — |
+| `github_cli` | GitHub CLI operations | `github` | `shell` |
+
+```typescript
+import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
+
+const ratatoskr = new Ratatoskr({
+  yggdrasilUrl: 'http://localhost:3000',
+  // 'agent' resolves transitively to agent + llm + shell + web_search
+  capabilities: ['agent', 'code'],
+});
+
+await ratatoskr.start();
+```
+
+## Running via CLI
 
 ```bash
 YGGDRASIL_URL=http://localhost:3000 \
-API_KEY=my-api-key \
-RUNNER_NAME=my-laptop \
-CAPABILITIES=http,health,browser \
+CAPABILITIES=agent \
 npx @theaiinc/yggdrasil-ratatoskr
 ```
 
-The `YGGDRASIL_URL` can point to a remote Yggdrasil over the internet — Ratatoskr connects outbound.
+The `YGGDRASIL_URL` can point to a remote Yggdrasil instance — Ratatoskr connects outbound.
 
-## Advanced Usage
+## Full Configuration
 
 ```typescript
-import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
-
 const ratatoskr = new Ratatoskr({
   runnerId: 'runner-a',
   name: 'MacBook Pro',
   yggdrasilUrl: 'https://yggdrasil.mycompany.com',
   apiKey: process.env['YGGDRASIL_API_KEY'],
-  capabilities: ['browser', 'computer-use', 'llm'],
+  capabilities: ['agent', 'code'],
   heartbeatInterval: 15,
   leaseTtl: 45,
+  taskPollInterval: 10,
   detectLocalIp: true,
   detectPublicIp: false,
   endpointProvider: async () => 'http://192.168.1.5:8080',
   healthProvider: async () => ({ status: 'healthy' }),
+  labels: { region: 'us-east' },
+  metadata: { team: 'infra' },
 });
 
 await ratatoskr.start();
 ```
 
-## Configuration
+### Configuration Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `runnerId` | `string` | Auto-generated | Unique runner identifier |
-| `name` | `string` | `'unknown'` | Human-readable runner name |
-| `yggdrasilUrl` | `string` | (required) | Yggdrasil server URL (local or remote) |
+| `name` | `string` | hostname | Human-readable runner name |
+| `yggdrasilUrl` | `string` | (required) | Yggdrasil server URL |
 | `apiKey` | `string` | `''` | API key for Yggdrasil auth |
-| `capabilities` | `string[]` | `[]` | List of runner capabilities |
+| `capabilities` | `string[]` | `[]` | Capability presets (resolved transitively) |
 | `heartbeatInterval` | `number` | `30` | Heartbeat interval in seconds |
 | `leaseTtl` | `number` | `60` | Lease TTL in seconds |
+| `taskPollInterval` | `number` | `10` | Task poll interval in seconds (0 = disable) |
+| `taskHandlers` | `Record<string, TaskHandler>` | `{}` | Custom task handlers (overrides presets) |
 | `detectLocalIp` | `boolean` | `true` | Auto-detect local IP |
 | `detectPublicIp` | `boolean` | `false` | Auto-detect public IP |
 | `endpointProvider` | `() => Promise<string>` | `undefined` | Custom endpoint resolver |
@@ -84,65 +109,221 @@ await ratatoskr.start();
 | `labels` | `Record<string, string>` | `{}` | Additional labels |
 | `metadata` | `Record<string, unknown>` | `{}` | Additional metadata |
 
-## Environment Variables (for CLI runner)
+## Capability Presets System
+
+Presets are the core of Ratatoskr's flexibility. Each preset is a JSON-like descriptor:
+
+```typescript
+import type { CapabilityPreset, CombinedPreset } from '@theaiinc/yggdrasil-ratatoskr';
+```
+
+### Preset Structure
+
+```typescript
+interface CapabilityPreset {
+  name: string;
+  description?: string;
+  dependsOn?: string[];           // Transitive dependencies
+  apt?: string[];                 // apt packages (Docker build)
+  npm?: string[];                 // npm packages (Docker build)
+  environment?: Record<string, {  // Env vars with defaults
+    description: string;
+    default?: string;
+    required?: boolean;
+  }>;
+  files?: PresetFile[];           // Config files (Docker build)
+  handlers?: Record<string, PresetHandler>;  // Task handlers
+  prepare?: string[];             // Docker RUN commands
+}
+```
+
+### Resolving Capabilities
+
+```typescript
+import { resolveCapabilities, applyPresetDefaults } from '@theaiinc/yggdrasil-ratatoskr';
+
+const { capabilities, combined } = resolveCapabilities(['agent', 'code']);
+// capabilities => ['agent', 'llm', 'shell', 'web_search', 'code', 'python', 'node_runtime']
+
+// Apply environment defaults to process.env
+applyPresetDefaults(combined);
+```
+
+### Combining Presets
+
+```typescript
+import { combinePresets, generateDockerfile, getPreset } from '@theaiinc/yggdrasil-ratatoskr';
+
+const combined = combinePresets(getPreset('llm'), getPreset('shell'));
+
+// Generate a Dockerfile with all dependencies baked in
+const dockerfile = generateDockerfile(combined, {
+  baseImage: 'node:20-alpine',
+  port: 3100,
+});
+```
+
+### Registering Custom Presets
+
+```typescript
+import { registerPreset, getPreset } from '@theaiinc/yggdrasil-ratatoskr';
+import type { CapabilityPreset } from '@theaiinc/yggdrasil-ratatoskr';
+
+registerPreset({
+  name: 'my-tool',
+  description: 'Custom tool with binary',
+  apt: ['ffmpeg'],
+  environment: {
+    MY_TOOL_PATH: { description: 'Path to config', default: '/etc/my-tool' },
+  },
+  handlers: {
+    my_tool: { module: './handlers/my-tool.js', export: 'myToolHandler' },
+  },
+});
+
+const preset = getPreset('my-tool');
+```
+
+## Task Execution
+
+Ratatoskr polls Yggdrasil for assigned tasks and executes them using registered handlers. Each capability preset maps to one or more task handlers.
+
+### Built-in Task Output Format
+
+All built-in handlers return structured metadata:
+
+| Handler | Metadata Fields |
+|---------|----------------|
+| `llm` | `{ model, usage: { input, output }, response }` |
+| `agent` | `{ final_message, model, tokens: { input, output } }` |
+| `shell` | `{ stdout, stderr, code }` |
+| `web_search` | `{ results }` |
+| `web_fetch` | `{ content }` |
+| `python` | `{ stdout, stderr, code }` |
+| `node` | `{ stdout, stderr, code }` |
+| `github` | `{ stdout, stderr, code }` |
+
+> **Cost tracking**: Cost is computed server-side by the orchestration layer (e.g. Oasis api-gateway's `PricingService`). Ratatoskr reports the actual model used and token counts — the server applies per-model pricing.
+
+### Custom Task Handlers
+
+```typescript
+import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
+import type { TaskHandler } from '@theaiinc/yggdrasil-ratatoskr';
+
+const echoHandler: TaskHandler = async (task) => {
+  return {
+    status: 'completed',
+    metadata: {
+      message: task.metadata?.message || 'hello',
+    },
+  };
+};
+
+const ratatoskr = new Ratatoskr({
+  yggdrasilUrl: 'http://localhost:3000',
+  capabilities: ['agent'],
+  taskHandlers: { echo: echoHandler },
+});
+```
+
+## Agent Sub-Agent Loop
+
+When the `agent` capability is active, Ratatoskr runs a full think-act-execute loop:
+
+1. **Think**: LLM receives the goal + available tools
+2. **Act**: LLM emits a `tool` block → handler executes
+3. **Observe**: Result is fed back to the LLM
+4. **Repeat**: Until the LLM emits a `final` block or max iterations reached
+
+The agent has access to: `shell`, `read_file`, `write_file`, `web_search`, `web_fetch`, `python`, `node`, `github` tools.
+
+## Environment Variables (CLI Runner)
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `YGGDRASIL_URL` | `http://orchestration-controller:3000` | Yggdrasil server URL |
+| `YGGDRASIL_URL` | `http://localhost:3000` | Yggdrasil server URL |
 | `API_KEY` | `''` | API key for authentication |
 | `RUNNER_NAME` | `ratatoskr-<hostname>` | Human-readable runner name |
-| `CAPABILITIES` | `http,health` | Comma-separated capabilities |
-
-## Architecture
+| `CAPABILITIES` | `agent` | Comma-separated capability presets |
+| `LLM_MODEL` | `google/gemma-4-26b-a4b-qat` | Model for LLM inference |
+| `LLM_BASE_URL` | `http://host.docker.internal:1234/v1` | OpenAI-compatible base URL |
+| `LLM_API_KEY` | `''` | API key (optional for local LM Studio) |
+| `AGENT_MAX_TOOL_ITERATIONS` | `25` | Max tool call cycles per agent task |
+
+## Services
+
+| Service | Description |
+|---------|-------------|
+| `Registrar` | Runner registration lifecycle |
+| `HeartbeatSender` | Periodic heartbeat sender |
+| `TaskExecutor` | Task polling and execution |
+| `EndpointDetector` | IP/hostname change detection |
+| `HealthMonitor` | Health check orchestration |
+| `LeaseManager` | Lease expiry tracking |
+| `RetryManager` | Exponential backoff retry |
+| `ResourceCollector` | CPU/memory/uptime collection |
+| `UpdateManager` | Self-update on Yggdrasil signal |
+| `HttpTransport` | HTTP transport with API key support |
+
+## Self-Update
+
+Ratatoskr can update itself when Yggdrasil signals a pending update via heartbeat response. The update is deferred until all current tasks complete.
 
+```typescript
+// Yggdrasil admin API:
+POST /runners/:id/request-update
+{ "version": "0.3.0", "command": "npm update -g @theaiinc/yggdrasil-ratatoskr" }
 ```
-yggdrasil-ratatoskr
-│
-├── runner.ts              # CLI entrypoint (reads env vars)
-├── ratatoskr.ts           # Main daemon class
-├── types/                 # TypeScript interfaces and enums
-├── transports/            # Transport abstraction (HTTP)
-│   └── http-transport.ts  # HTTP transport with API key support
-└── services/
-    ├── registrar.ts           # Runner registration lifecycle
-    ├── heartbeat-sender.ts    # Periodic heartbeat sender
-    ├── endpoint-detector.ts   # IP/hostname change detection
-    ├── health-monitor.ts      # Health check orchestration
-    ├── lease-manager.ts       # Lease expiry tracking
-    └── retry-manager.ts       # Exponential backoff retry
-```
+
+On the next heartbeat, the runner receives the `pendingUpdate` field, finishes its tasks, runs the update command, and restarts.
 
 ## How It Works
 
-1. **`ratatoskr.start()`** — Registers the runner with Yggdrasil, begins heartbeats, starts monitoring IP and lease expiry, and registers shutdown handlers.
-2. **Heartbeats** — Sent every N seconds (configurable) to confirm the runner is alive.
-3. **Lease** — Each registration has a TTL. If Yggdrasil misses enough heartbeats, the runner is marked `offline`.
-4. **IP Changes** — Detected every 10 seconds; if the local IP changes, Yggdrasil is notified via `POST /runners/update`.
-5. **Graceful Shutdown** — On SIGTERM/SIGINT, Ratatoskr deregisters the runner with `POST /runners/offline`.
+1. **`ratatoskr.start()`** — Resolves capability presets, registers with Yggdrasil, begins heartbeats, starts task polling
+2. **Heartbeats** — Sent every N seconds with health, resources, and current tasks
+3. **Lease** — Each registration has a TTL; Yggdrasil marks runner `offline` on timeout
+4. **Task polling** — Polls `GET /runners/:id/tasks` for tasks in `running` status every N seconds
+5. **Task execution** — Dispatches to registered handler by task type, reports completion via `PATCH`
+6. **IP Changes** — Detected every 10 seconds; Yggdrasil notified via `POST /runners/update`
+7. **Graceful Shutdown** — On SIGTERM/SIGINT, deregisters with `POST /runners/offline`
 
 ## Reliability
 
 Ratatoskr is designed to survive:
-
-- Temporary network outages
-- Yggdrasil restarts
-- IP changes
+- Temporary network outages (exponential backoff)
+- Yggdrasil restarts (automatic re-registration)
+- IP changes (dynamic endpoint updates)
 - Laptop sleep/wake cycles
 - Docker container restarts
 
-It uses exponential backoff for retries, persistent runner IDs, and automatic re-registration.
-
-## API Endpoints (Yggdrasil)
+## Public API (Export Summary)
 
-Ratatoskr expects these endpoints on the Yggdrasil server:
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| `POST` | `/runners/register` | Register a new runner |
-| `POST` | `/runners/heartbeat` | Send a heartbeat |
-| `POST` | `/runners/update` | Update runner endpoint |
-| `POST` | `/runners/offline` | Deregister a runner |
+```typescript
+// Classes
+import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
+import { HttpTransport, EndpointDetector, HealthMonitor, HeartbeatSender,
+         LeaseManager, Registrar, RetryManager, ResourceCollector,
+         TaskExecutor, UpdateManager } from '@theaiinc/yggdrasil-ratatoskr';
+
+// Preset system
+import { registerPreset, getPreset, listPresets, combinePresets,
+         generateDockerfile, applyPresetDefaults, resolveCapabilities } from '@theaiinc/yggdrasil-ratatoskr';
+import type { CapabilityPreset, CombinedPreset, DockerfileOptions,
+              PresetEnvVar, PresetHandler, PresetFile } from '@theaiinc/yggdrasil-ratatoskr';
+
+// Built-in presets
+import { llm, webSearch, shell, agent, codeRunner, python,
+         nodeRuntime, githubCli } from '@theaiinc/yggdrasil-ratatoskr';
+
+// Types
+import type { Transport, RatatoskrConfig, RatatoskrState, RunnerRegistration,
+              HeartbeatPayload, HeartbeatResponse, PendingUpdate,
+              HealthResult, SystemResources, RunnerTask,
+              TaskHandler, TaskExecutorConfig } from '@theaiinc/yggdrasil-ratatoskr';
+import { RunnerHealth } from '@theaiinc/yggdrasil-ratatoskr';
+```
 
 ## License
 
-MIT
+MIT — © 2026 The AI Inc

package/dist/src/handlers/agent-handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent handler — full sub-agent loop (think-act-execute) with LLM + tools.
+ *
+ * Implements the 'agent' task type. Uses the LLM to plan and execute,
+ * calling shell, file, and web tools as needed.
+ */
+import type { TaskHandler } from '../types/index.js';
+export declare const agentHandler: TaskHandler;
+//# sourceMappingURL=agent-handler.d.ts.map

package/dist/src/handlers/agent-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-handler.d.ts","sourceRoot":"","sources":["../../../src/handlers/agent-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6GrD,eAAO,MAAM,YAAY,EAAE,WA4D1B,CAAC"}

package/dist/src/handlers/agent-handler.js

@@ -0,0 +1,184 @@
+/**
+ * Agent handler — full sub-agent loop (think-act-execute) with LLM + tools.
+ *
+ * Implements the 'agent' task type. Uses the LLM to plan and execute,
+ * calling shell, file, and web tools as needed.
+ */
+import { execSync } from 'child_process';
+import axios from 'axios';
+const LLM_MODEL = process.env.LLM_MODEL || 'google/gemma-4-26b-a4b-qat';
+const LLM_BASE_URL = (process.env.LLM_BASE_URL || 'http://host.docker.internal:1234/v1').replace(/\/$/, '');
+const LLM_API_KEY = process.env.LLM_API_KEY || process.env.OASIS_OPENAI_API_KEY || '';
+const MAX_TOOL_ITERATIONS = parseInt(process.env.AGENT_MAX_TOOL_ITERATIONS || '25', 10);
+const tools = {
+    shell: async (command) => {
+        try {
+            const output = execSync(command, { encoding: 'utf-8', timeout: 30_000, maxBuffer: 10 * 1024 * 1024 });
+            return { success: true, output: output.slice(0, 100_000) };
+        }
+        catch (err) {
+            return { success: false, output: err.stdout || '', error: err.stderr || err.message };
+        }
+    },
+    read_file: async (path) => {
+        try {
+            const fs = await import('fs');
+            const content = fs.readFileSync(path, 'utf-8');
+            return { success: true, output: content.slice(0, 100_000) };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+    write_file: async (path, content) => {
+        try {
+            const fs = await import('fs');
+            const pathModule = await import('path');
+            fs.mkdirSync(pathModule.dirname(path), { recursive: true });
+            fs.writeFileSync(path, content, 'utf-8');
+            return { success: true, output: `Written ${content.length} bytes to ${path}` };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+    web_search: async (query) => {
+        try {
+            const { data } = await axios.get(process.env.WEB_SEARCH_API || 'https://api.duckduckgo.com', {
+                params: { q: query, format: 'json' }, timeout: 15_000,
+            });
+            const results = data.AbstractText || (data.RelatedTopics || []).slice(0, 5).map((r) => r.Text || r.FirstURL).join('\n');
+            return { success: true, output: results || 'No results.' };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+    web_fetch: async (url) => {
+        try {
+            const { data } = await axios.get(url, { timeout: 15_000 });
+            const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+            return { success: true, output: text.slice(0, 100_000) };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+    python: async (script) => {
+        try {
+            const { pythonHandler } = await import('./python-handler.js');
+            const result = await pythonHandler({ script });
+            return { success: result.code === 0, output: result.stdout.slice(0, 100_000), error: result.stderr || '' };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+    node: async (script) => {
+        try {
+            const { nodeHandler } = await import('./node-handler.js');
+            const result = await nodeHandler({ script });
+            return { success: result.code === 0, output: result.stdout.slice(0, 100_000), error: result.stderr || '' };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+    github: async (command, ...args) => {
+        try {
+            const { githubHandler } = await import('./github-handler.js');
+            const result = await githubHandler({ command, args });
+            return { success: result.code === 0, output: result.stdout.slice(0, 100_000), error: result.stderr || '' };
+        }
+        catch (err) {
+            return { success: false, output: '', error: err.message };
+        }
+    },
+};
+const toolNames = Object.keys(tools);
+async function callLlm(messages) {
+    const { data } = await axios.post(`${LLM_BASE_URL}/chat/completions`, { model: LLM_MODEL, messages, max_tokens: 4096, temperature: 0.3 }, { headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${LLM_API_KEY}` }, timeout: 120_000 });
+    return {
+        content: data.choices?.[0]?.message?.content || '',
+        model: data.model || LLM_MODEL,
+        inputTokens: data.usage?.prompt_tokens || 0,
+        outputTokens: data.usage?.completion_tokens || 0,
+    };
+}
+export const agentHandler = async (task) => {
+    const goal = task.metadata?.goal || task.type || 'agent task';
+    if (!LLM_API_KEY) {
+        return { status: 'completed', metadata: { final_message: `No LLM configured. Goal: "${goal.slice(0, 120)}"`, tokens: { input: 0, output: 0 } } };
+    }
+    const messages = [
+        {
+            role: 'system',
+            content: [
+                'You are a capable sub-agent. Your job is to accomplish the given goal.',
+                'Available tools:', ...toolNames.map((n) => `  - ${n}`),
+                '',
+                'To use a tool:',
+                '```tool',
+                '{"name": "<tool_name>", "arguments": {"arg1": "value", ...}}',
+                '```',
+                '',
+                'When done:',
+                '```final',
+                '{"result": "your answer", "summary": "brief summary"}',
+                '```',
+            ].join('\n'),
+        },
+        { role: 'user', content: `Goal: ${goal}` },
+    ];
+    let totalInput = 0, totalOutput = 0, finalAnswer = '', lastModel = LLM_MODEL;
+    for (let iter = 0; iter < MAX_TOOL_ITERATIONS; iter++) {
+        const llm = await callLlm(messages);
+        totalInput += llm.inputTokens;
+        totalOutput += llm.outputTokens;
+        lastModel = llm.model;
+        const content = llm.content.trim();
+        const finalMatch = content.match(/```final\n([\s\S]*?)```/);
+        if (finalMatch) {
+            const json = finalMatch[1];
+            try {
+                finalAnswer = json ? (JSON.parse(json).result || JSON.parse(json).summary || content) : content;
+            }
+            catch {
+                finalAnswer = content;
+            }
+            break;
+        }
+        const toolMatch = content.match(/```tool\n([\s\S]*?)```/);
+        if (toolMatch) {
+            const match = toolMatch[1];
+            let call;
+            if (!match) {
+                messages.push({ role: 'assistant', content }, { role: 'user', content: 'Empty tool block.' });
+                continue;
+            }
+            try {
+                call = JSON.parse(match);
+            }
+            catch {
+                messages.push({ role: 'assistant', content }, { role: 'user', content: 'Invalid JSON. Use valid JSON.' });
+                continue;
+            }
+            const fn = tools[call.name];
+            if (!fn) {
+                messages.push({ role: 'assistant', content }, { role: 'user', content: `Unknown tool: ${call.name}. Available: ${toolNames.join(', ')}` });
+                continue;
+            }
+            const result = await fn(...Object.values(call.arguments));
+            messages.push({ role: 'assistant', content }, { role: 'user', content: result.success ? `Output:\n${result.output}` : `Error: ${result.error || result.output}` });
+            continue;
+        }
+        messages.push({ role: 'assistant', content }, { role: 'user', content: 'Respond with a `tool` or `final` block.' });
+    }
+    if (!finalAnswer)
+        finalAnswer = 'Max iterations reached without final answer.';
+    return {
+        status: 'completed',
+        metadata: { final_message: finalAnswer, model: lastModel, tokens: { input: totalInput, output: totalOutput } },
+    };
+};
+//# sourceMappingURL=agent-handler.js.map

package/dist/src/handlers/agent-handler.js.map

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

package/dist/src/handlers/code-handler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Code handler — generates code via LLM with a coding-optimised profile.
+ *
+ * Uses an LLM (default: gemma4:12b via Ollama) to write code for a given
+ * task description. Returns the generated source code as the result.
+ *
+ * This is NOT a sandbox executor — code runs in the user's dev environment.
+ */
+import type { TaskHandler } from '../types/index.js';
+export declare const codeHandler: TaskHandler;
+//# sourceMappingURL=code-handler.d.ts.map

package/dist/src/handlers/code-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-handler.d.ts","sourceRoot":"","sources":["../../../src/handlers/code-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkBrD,eAAO,MAAM,WAAW,EAAE,WAgDzB,CAAC"}