infinicode 2.8.27 → 2.8.29

package/README.md

@@ -1,624 +1,624 @@
-# OpenKernel
-
-### Provider-Agnostic AI Execution Kernel
-
-> **Mission:** Execute AI workloads reliably for hours or days using the best available inference without depending on any single provider, model, or framework.
-
-`infinicode` now ships a **kernel** — a provider-agnostic AI execution runtime — alongside the original Ollama-based coding CLI. The kernel is not an agent framework; it executes missions. Harnesses, CLIs, bots, and custom workflows all interact through the same execution API.
-
----
-
-## Quick Start
-
-### Friendly setup wizard (recommended)
-
-```bash
-infinicode kernel-setup
-```
-
-The wizard walks through:
-
-1. **Ollama master** — LAN URL + optional Tailscale fallback (preserved from v1)
-2. **Free cloud providers** — recommends setting up as many as possible for optimal rotation:
-   - **Groq** — fastest cloud inference, free tier
-   - **OpenRouter** — aggregator with many free model variants
-   - **GitHub Models** — free preview, use a GitHub token
-   - **NVIDIA NIM** — free NIM endpoints
-   - **Hugging Face** — free Inference API
-   - For each: prompt for API key, test connection, enable on success
-3. **Worker model pinning** — arrow-key list per worker type (coding, research, architecture, review, documentation, translation, terminal, verification, vision, browser). Recommends a model for each based on capability match.
-4. **Default policy** — local-first, free-first, fastest, highest-quality, privacy-first, balanced, offline
-5. **Save** — prints a summary
-
-All choices are saved to the infinicode config. Setting up more providers gives the router more options for failover and rate-limit rotation.
-
-### Quick manual setup
-
-```bash
-# Ollama only (original v1 flow)
-infinicode connect 192.168.1.100
-
-# Add a cloud provider
-infinicode providers add
-
-# Pin a model per worker type
-infinicode workers edit
-```
-
----
-
-### As a CLI (infinicode TUI)
-
-```bash
-npm install -g infinicode
-
-# Connect to your Ollama master
-infinicode connect 192.168.1.100
-
-# Set up cloud providers (Groq, OpenRouter, GitHub, NVIDIA, HF, Gemini)
-infinicode kernel-setup
-
-# Start the infinicode TUI — full provider pool injected
-infinicode
-```
-
-The `run` command (default) launches the **infinicode TUI** — the infinicode SolidJS terminal UI with the infinicode gold theme, animated logo, markdown rendering, diff view, and plugin slots. infinicode builds the provider config from your saved kernel config (Ollama + all enabled cloud providers) and injects it via `OPENCODE_CONFIG_CONTENT`, so the TUI can use **every provider** — not just a single Ollama master.
-
-The TUI is the **Harness** (prompts, workflows, personas, memory). For headless mission execution with full kernel routing (capability router, recovery, verification, checkpoints), use `infinicode mission run`.
-
-### As a kernel (new in v2)
-
-```bash
-# One-time friendly setup wizard (providers + worker models + policy)
-infinicode kernel-setup
-
-# Or set up individual pieces
-infinicode providers add     # add Groq/OpenRouter/GitHub/NVIDIA/HF
-infinicode workers edit      # pick a model per worker type
-
-# List built-in sample missions
-infinicode mission samples
-
-# Run a mission through the kernel
-infinicode mission run --goal "Reverse a string in TypeScript" --task "Write reverseString(s)" --cap coding
-
-# Run a sample
-infinicode mission run --sample hello-code
-
-# Mission status / list
-infinicode mission status <id>
-infinicode mission list
-```
-
-### As a device mesh (multi-device, new in v2)
-
-Install infinicode on every machine — laptop, workstation, Raspberry&nbsp;Pi — and they become one fleet. Spawn AI agents on any device from any device (no SSH), stream activity/hardware back, and drive it all from an MCP host like Claude Code or InfiniBot.
-
-```bash
-# install on each device
-npm install -g infinicode
-
-# same LAN — zero config: each node broadcasts a UDP beacon and auto-connects
-infinicode serve --hub --lan                         # your main machine
-infinicode serve --role satellite --lan              # a Pi / other box
-
-# across LAN + remote — auto-discover over Tailscale
-infinicode serve --hub --tailscale
-infinicode serve --role satellite --tailscale --tag tag:robopark
-
-# or point at exact peers
-infinicode serve --role satellite --seed http://192.168.1.20:47913
-
-# verify the mesh — ask any running node for its peers (self + connected)
-curl http://localhost:47913/fed/nodes
-```
-
-Set your cloud provider keys + policy **once on the hub**; every satellite auto-sources them (over `--seed`/`--lan`/`--tailscale`) and registers the providers + models live, no restart.
-
-Drive the fleet from an MCP host — register the control server (spawn / dispatch / follow / role / voice / mesh-map tools):
-
-```jsonc
-// ~/.claude.json
-{ "mcpServers": { "infinicode": { "command": "infinicode", "args": ["mcp", "--lan"] } } }
-```
-
-Link a node onto an **InfiniBot** neural-mesh map (no InfiniBot changes needed):
-
-```bash
-infinicode serve --hub --gateway ws://<infinibot-host>:18789 --gateway-token <token>
-```
-
-Discovery options: `--lan` (same subnet, zero-config UDP broadcast, port 47915), `--tailscale` (LAN+remote), `--seed <url>` (exact) — they combine. Full guide: `docs/user-manual.html`; design deep-dive: `docs/federation-architecture.html`.
-
-> The Windows TUI binaries are not shipped in the npm package (they're large and platform-specific), so `infinicode run` needs a local TUI build; the mesh commands (`serve`, `mcp`, `mission`, `console`) run everywhere as pure Node.
-
-### As a library
-
-```ts
-import { createKernel, OllamaProvider, OpenAICompatibleProvider } from 'infinicode/kernel';
-
-const kernel = createKernel();
-
-// Register providers (plugins — the application never knows which)
-kernel.registerProvider('ollama', new OllamaProvider({
-  baseURL: 'http://192.168.1.100:11434',
-  defaultModel: 'qwen2.5-coder:14b',
-}));
-
-kernel.registerProvider('openrouter', new OpenAICompatibleProvider({
-  id: 'openrouter',
-  name: 'OpenRouter',
-  baseURL: 'https://openrouter.ai/api',
-  apiKey: process.env.OPENROUTER_API_KEY!,
-}));
-
-// Subscribe to events (plugins, notifications, logging)
-kernel.subscribeAll(event => console.log(event.type));
-
-// Execute a mission — the kernel decides where/when/with which model
-const mission = await kernel.execute({
-  name: 'reverse-string',
-  description: 'Write a TypeScript string reverser',
-  goal: 'Produce a reverseString function',
-  policy: 'local-first',
-  tasks: [
-    {
-      description: 'Write the function',
-      capabilities: ['coding', 'reasoning'],
-      input: { prompt: 'Write `reverseString(s: string): string`. Include only the function.' },
-    },
-  ],
-});
-
-console.log(mission.status, mission.tasks[0].output?.content);
-```
-
----
-
-## Core Principles
-
-1. **Execution First** — the kernel is not an agent framework. It executes missions. It doesn't define prompts, workflows, or personas. Those belong to Harnesses.
-2. **Framework Agnostic** — works equally well with Harness, custom workflows, CLI, n8n, Discord bots, VSCode extensions. Everything interacts through the same execution API.
-3. **Model Agnostic** — workers never request "Gemini". They request `Need: Coding, Reasoning>90, Vision, Context>128K`. The router decides.
-4. **Provider Agnostic** — providers are plugins. The application never knows.
-
----
-
-## Architecture
-
-```
-                     Applications
-
-      Harness     CLI     n8n     VSCode
-
-                     │
-──────────────────── API ───────────────────
-                     │
-             AI Execution Kernel
-────────────────────────────────────────────
-
-Mission Engine
-Native Orchestrator
-Scheduler
-Worker Runtime
-Capability Router
-Provider Manager
-Policy Engine
-Verification
-Recovery
-Checkpoint Engine
-Event Bus
-Plugin Manager
-────────────────────────────────────────────
-
-Providers          Tools          Workers          Notifications
-```
-
-### Components
-
-| Component | Responsibility |
-|---|---|
-| **Mission Engine** | Lifecycle (NEW → PLANNING → READY → RUNNING → VERIFYING → WAITING → FAILED → COMPLETED), pause/resume, completion |
-| **Native Orchestrator** | Always running. Coordinates everything, executes nothing directly |
-| **Scheduler** | Mission → Objectives → Tasks → Execution Queue → Workers. Sequential, parallel, dependency graphs |
-| **Worker Runtime** | Disposable capability containers: Spawn → Initialize → Execute → Verify → Publish → Destroy |
-| **Capability Registry** | Workers advertise capabilities (coding, browser, vision, terminal, planning, reasoning, …) |
-| **Policy Engine** | 7 built-in policies: free-first, fastest, highest-quality, local-first, privacy-first, balanced, offline |
-| **Intelligent Router** | Scores: capability + reliability + speed + quota + context + policy − cost → best model + provider |
-| **Provider Manager** | Tracks models, quota, 429s, latency, success rate, health. Background refresh only, never blocks |
-| **Verification Engine** | Pipeline: objective → compile → tests → lint → browser tests → expected output → LLM judge (always last) |
-| **Recovery Manager** | Classifies failures (429, timeout, provider-down, hallucination, …) → retry / rotate / spawn-different-worker / replan / checkpoint |
-| **Checkpoint Engine** | Persists mission, objectives, tasks, worker state, memory, logs, artifacts. Pause/resume/crash-recovery |
-| **Event Bus** | Everything emits events. Plugins subscribe |
-| **Plugin System** | Core stays tiny. Telegram, Discord, Slack, Browser, Search, Dashboard, Metrics, … all optional |
-
----
-
-## Worker Types (built-in)
-
-Workers are **capability containers, not personalities**. No prompts, no workflows, no personas — only capabilities. Any system prompt is supplied by the Harness via `TaskInput.context`, never by the worker itself.
-
-```
-research     browser     coding       architecture
-vision       review      documentation translation
-terminal     verification
-```
-
-Register custom workers via `kernel.registerWorker({ type, capabilities, preferences })`.
-
----
-
-## Providers (built-in)
-
-| Provider | Type | File |
-|---|---|---|
-| **Ollama** | local | `ollama-provider.ts` (LAN + Tailscale fallback, migrated from v1) |
-| **OpenAI-compatible** | local/cloud | `openai-compatible-provider.ts` (powers OpenRouter, Groq, GitHub Models, NVIDIA, HF, vLLM, LM Studio, SGLang) |
-| **Gemini** | cloud | `gemini-provider.ts` (Google Generative Language API — generateContent / streamGenerateContent) |
-
-All three implement the same `ProviderInterface`. The application never knows which is in use.
-
-### Adding a cloud provider
-
-```ts
-import { OpenAICompatibleProvider } from 'infinicode/kernel';
-
-kernel.registerProvider('groq', new OpenAICompatibleProvider({
-  id: 'groq',
-  name: 'Groq',
-  baseURL: 'https://api.groq.com/openai',
-  apiKey: process.env.GROQ_API_KEY!,
-  knownModels: [
-    { id: 'llama-3.3-70b-versatile', contextLength: 128_000, supportsVision: false },
-  ],
-}));
-```
-
-### Adding Gemini
-
-```ts
-import { GeminiProvider } from 'infinicode/kernel';
-
-kernel.registerProvider('gemini', new GeminiProvider({
-  apiKey: process.env.GEMINI_API_KEY!,
-  knownModels: [
-    { id: 'gemini-2.0-flash', contextLength: 1_048_576, supportsVision: true, supportsFunctionCalling: true },
-  ],
-}));
-```
-
----
-
-## Browser Layer (Phase 4)
-
-Default: **Playwright** (optional peer dependency). When Playwright is not installed, the browser controller degrades to a fetch-based read-only mode automatically.
-
-```ts
-import { createBrowserPlugin } from 'infinicode/kernel';
-await kernel.registerPlugin(createBrowserPlugin({ headless: true }));
-
-// Drive the browser via a mission task:
-const mission = await kernel.execute({
-  goal: 'Extract the latest news headlines',
-  tasks: [{
-    description: 'Open site and extract headlines',
-    capabilities: ['browser'],
-    input: {
-      prompt: 'Navigate and extract the top 5 headlines',
-      context: {
-        actions: [
-          { type: 'navigate', url: 'https://news.ycombinator.com' },
-          { type: 'extract' },
-        ],
-      },
-    },
-  }],
-});
-```
-
-## Search Layer (Phase 4)
-
-Default stack: **SearXNG → Crawler → Markdown → LLM**. Falls back to a DuckDuckGo HTML scrape when SearXNG is not configured.
-
-```ts
-import { createSearchPlugin } from 'infinicode/kernel';
-await kernel.registerPlugin(createSearchPlugin({ searxngUrl: 'http://localhost:8080' }));
-
-// Research worker uses the search controller automatically:
-const mission = await kernel.execute({
-  goal: 'Research latest TS patterns',
-  tasks: [{
-    description: 'Research and summarize',
-    capabilities: ['search', 'citations'],
-    input: { prompt: 'TypeScript branded types', context: { query: 'TypeScript branded types' } },
-  }],
-});
-```
-
-## Plugin SDK & Harness SDK (Phase 4)
-
-```ts
-import { definePlugin, mission, taskInput, browserTaskInput, researchTaskInput } from 'infinicode/kernel';
-
-// Author a plugin fluently
-const myPlugin = definePlugin('my-plugin')
-  .version('1.0.0')
-  .description('Custom notifier')
-  .subscribe(['MISSION_COMPLETED'], (e) => console.log('done', e.missionId))
-  .command('ping', 'Ping', async (args) => console.log('pong', args.join(' ')))
-  .build();
-await kernel.registerPlugin(myPlugin);
-
-// Build a mission input fluently
-const input = mission('reverse-string', 'Produce a reverseString function')
-  .description('Write a TypeScript string reverser')
-  .policy('local-first')
-  .task('Write the function', ['coding', 'reasoning'], taskInput('Write `reverseString(s)`'))
-  .build();
-await kernel.execute(input);
-```
-
-## Dashboard & Metrics (Phase 4)
-
-```ts
-import { createDashboardPlugin, createMetricsPlugin } from 'infinicode/kernel';
-
-const metrics = createMetricsPlugin();
-await kernel.registerPlugin(metrics);
-await kernel.registerPlugin(createDashboardPlugin({ port: 7331 }));
-
-// Read counters anytime
-console.log(metrics.snapshot());
-// → { missionsStarted: 3, tasksCompleted: 11, recoveries: 1, totalTokensOut: 4521, ... }
-```
-
-The dashboard serves `http://127.0.0.1:7331/` (HTML), `/status`, `/missions`, `/events`.
-
----
-
-## Policies
-
-```yaml
-policy:
-  execution:
-    parallelism: 4
-  routing:
-    mode: free-first
-  verification:
-    strict
-  checkpoint:
-    every-task: true
-  retry:
-    maxAttempts: 5
-  notifications:
-    channels: [telegram]
-```
-
-Built-in: `free-first`, `fastest`, `highest-quality`, `local-first`, `privacy-first`, `balanced`, `offline`.
-
-```ts
-kernel.registerPolicy({
-  name: 'my-policy',
-  execution: { parallelism: 8 },
-  routing: { mode: 'balanced', preferredProviders: ['ollama', 'groq'] },
-  retry: { maxAttempts: 5 },
-});
-```
-
----
-
-## Public API
-
-```ts
-kernel.execute(mission)     // → Promise<Mission>
-kernel.pause(missionId)     // → Promise<void>
-kernel.resume(missionId)    // → Promise<Mission>
-kernel.cancel(missionId)    // → Promise<void>
-kernel.status(missionId)    // → Promise<MissionStatus>
-kernel.subscribe(types, fn) // → unsubscribe
-kernel.subscribeAll(fn)      // → unsubscribe
-kernel.registerWorker(def)
-kernel.registerProvider(id, provider)
-kernel.registerPlugin(plugin)
-kernel.registerPolicy(policy)
-kernel.getMission(id)
-kernel.listMissions()
-```
-
----
-
-## CLI Commands
-
-| Command | Alias | Description |
-|---|---|---|
-| `infinicode connect <ip>` | `ic c` | Quick connect to Ollama master |
-| `infinicode setup` | `ic s` | Interactive setup wizard (Ollama only) |
-| `infinicode run` | `ic` | Start the infinicode TUI (full provider pool: Ollama + cloud) |
-| `infinicode status` | | Show config & all provider health |
-| `infinicode models` | `ic m` | List available models across all healthy providers |
-| `infinicode config` | | View or modify configuration |
-| `infinicode kernel-setup` | `ic ks` | **Friendly setup wizard — providers + worker models + policy** |
-| `infinicode workers` | `ic w` | **View per-worker model preferences** |
-| `infinicode workers edit` | `ic w e` | **Interactively pick a model per worker type** |
-| `infinicode workers reset` | | Clear all worker pins |
-| `infinicode providers` | `ic p` | **View configured providers** |
-| `infinicode providers add` | | **Add a cloud provider (Groq/OpenRouter/GitHub/NVIDIA/HF/Gemini)** |
-| `infinicode providers remove <id>` | | Remove a cloud provider |
-| `infinicode providers test [id]` | | Test connection to one or all providers |
-| `infinicode mission run` | `ic k run` | **Execute a mission through the kernel** |
-| `infinicode mission samples` | | List built-in sample missions |
-| `infinicode mission status <id>` | | Show mission status |
-| `infinicode mission list` | | List missions in this session |
-| `infinicode mission resume <id>` | | Resume a paused mission |
-| `infinicode mission cancel <id>` | | Cancel a running mission |
-
-### Mission run options
-
-```
-infinicode mission run \
-  --goal "Mission goal" \
-  --name "mission-name" \
-  --task "Task 1 description" --task "Task 2 description" \
-  --cap coding,reasoning \
-  --policy local-first \
-  --sample hello-code
-```
-
----
-
-## Worker Model Preferences
-
-Workers request **capabilities** (coding, reasoning, vision, …). The router picks the best model. You can **pin** a specific model per worker type — the pinned pair is used when healthy, otherwise the router falls back.
-
-```bash
-# View current pins
-infinicode workers
-
-# Interactively pick a model per worker type (arrow-key lists)
-infinicode workers edit
-
-# Clear all pins (router decides for every worker type)
-infinicode workers reset
-```
-
-Each worker type has a recommended default based on capability match across your configured providers. The wizard preselects the recommendation.
-
-### Worker types
-
-| Type | Capabilities | Description |
-|---|---|---|
-| `coding` | coding, reasoning, filesystem, terminal | Writes code |
-| `research` | search, crawl, summarize, citations | Researches with citations (SearXNG → Crawl → LLM) |
-| `architecture` | architecture, planning, reasoning | Designs structure |
-| `review` | review, coding, reasoning | Critiques code/design |
-| `documentation` | documentation, summarize, reasoning | Produces docs |
-| `translation` | translation, reasoning | Translates content |
-| `terminal` | terminal, coding, filesystem | Produces shell commands |
-| `verification` | verification, reasoning, review | Verifies acceptance criteria |
-| `vision` | vision, ocr, reasoning | Analyzes images |
-| `browser` | browser, crawl, search, reasoning | Drives a browser (Playwright or fetch fallback) |
-
-### Programmatic API
-
-```ts
-kernel.workerRuntime.setWorkerPin('coding', 'groq', 'llama-3.3-70b-versatile');
-kernel.workerRuntime.setWorkerPins(new Map([
-  ['coding', { providerId: 'ollama', modelId: 'qwen2.5-coder:14b' }],
-  ['research', { providerId: 'groq', modelId: 'llama-3.3-70b-versatile' }],
-]));
-kernel.setDefaultPolicy('local-first');
-```
-
----
-
-**Harness owns:** Prompts, workflows, templates, agent design, memory strategy.
-**Kernel owns:** Execution, scheduling, workers, routing, recovery, verification, checkpoints.
-
-Perfect separation. A harness produces mission inputs; the kernel executes them.
-
----
-
-## Harness Integration
-
-**Harness owns:** Prompts, workflows, templates, agent design, memory strategy.
-**Kernel owns:** Execution, scheduling, workers, routing, recovery, verification, checkpoints.
-
-Perfect separation. A harness produces mission inputs; the kernel executes them.
-
----
-
-## Development Roadmap
-
-### Phase 1 — Core Runtime ✅
-
-- [x] Mission Engine
-- [x] Scheduler
-- [x] Worker Runtime
-- [x] Provider Interface (Ollama + OpenAI-compatible)
-- [x] Event Bus
-- [x] Checkpoints
-- [x] Capability Router (policy-weighted scoring)
-- [x] Policy Engine (7 built-in policies)
-- [x] Plugin Manager + Telegram/Discord/Slack/Browser/Search stubs
-- [x] Setup wizard + worker model pinning + free cloud provider presets
-
-**Target:** Stable execution kernel. ✅
-
-### Phase 2 — Intelligent Routing
-
-- [x] Model scoring benchmarks
-- [x] Capability-based routing with health awareness
-- [x] Free-first routing
-- [x] Automatic failover (via Recovery Manager → rotate-provider)
-- [x] Provider telemetry: 429 / quota / success-rate tracking
-
-**Target:** Provider-independent inference. ✅
-
-### Phase 3 — Reliability
-
-- [x] Verification engine (objective → compile → tests → lint → browser → expected output → LLM judge)
-- [x] Recovery manager (retry → rotate provider → spawn different worker → replan → checkpoint)
-- [x] Long-running missions (checkpoint + resume)
-- [x] Persistent checkpoints (fs-backed, capped at 20/mission)
-- [ ] Automatic replanning (planning-failure → replan action wired; full objective re-plan pending)
-
-**Target:** Autonomous execution. ✅ (core)
-
-### Phase 4 — Ecosystem
-
-- [x] Telegram notifications + slash commands (/status /workers /logs /pause /resume /retry /models /providers /checkpoints /goal)
-- [x] Browser worker (Playwright-backed; fetch fallback when Playwright not installed)
-- [x] Research worker (SearXNG → Crawl4AI-style crawler → Markdown → LLM; DuckDuckGo fallback)
-- [x] Plugin SDK (`definePlugin()` fluent builder)
-- [x] Harness SDK (`mission()` builder + `taskInput`/`browserTaskInput`/`researchTaskInput` helpers)
-- [x] Dashboard plugin (HTTP `/status` `/missions` `/events` + HTML view)
-- [x] Metrics plugin (runtime counters: missions/tasks/workers/tokens/latency)
-- [x] Gemini provider (Google Generative Language API — dedicated class, not OpenAI-compatible)
-- [ ] Natural chat with orchestrator via Telegram
-- [ ] Vision / Email / Database / Storage / Monitoring plugins
-
-**Target:** Extensible platform. ✅ (core)
-
----
-
-## Configuration
-
-Config is stored automatically (via `conf`). Override with:
-
-```bash
-infinicode config --set defaultModel=qwen2.5-coder:14b
-infinicode config --set masterUrl=http://192.168.1.100:11434
-infinicode config --list
-```
-
-Checkpoints persist to `.openkernel/checkpoints/` (capped at 20 per mission).
-
----
-
-## Recommended Models
-
-| Model | Size | Best For |
-|---|---|---|
-| `qwen2.5-coder:14b` | 9GB | Great balance |
-| `qwen2.5-coder:32b` | 20GB | Best quality |
-| `deepseek-coder-v2:16b` | 10GB | Strong reasoning |
-| `codestral:22b` | 13GB | Fast completion |
-
----
-
-## Requirements
-
-- Node.js 20+
-- infinicode installed globally (`npm install -g infinicode`) — provides the TUI binary
-- An Ollama master running somewhere on your network — for the kernel's default local provider
-- Optional: cloud provider API keys (Groq, OpenRouter, GitHub, NVIDIA, HF, Gemini) for provider rotation
-
----
-
-## License
-
-MIT
-
----
-
+# OpenKernel
+
+### Provider-Agnostic AI Execution Kernel
+
+> **Mission:** Execute AI workloads reliably for hours or days using the best available inference without depending on any single provider, model, or framework.
+
+`infinicode` now ships a **kernel** — a provider-agnostic AI execution runtime — alongside the original Ollama-based coding CLI. The kernel is not an agent framework; it executes missions. Harnesses, CLIs, bots, and custom workflows all interact through the same execution API.
+
+---
+
+## Quick Start
+
+### Friendly setup wizard (recommended)
+
+```bash
+infinicode kernel-setup
+```
+
+The wizard walks through:
+
+1. **Ollama master** — LAN URL + optional Tailscale fallback (preserved from v1)
+2. **Free cloud providers** — recommends setting up as many as possible for optimal rotation:
+   - **Groq** — fastest cloud inference, free tier
+   - **OpenRouter** — aggregator with many free model variants
+   - **GitHub Models** — free preview, use a GitHub token
+   - **NVIDIA NIM** — free NIM endpoints
+   - **Hugging Face** — free Inference API
+   - For each: prompt for API key, test connection, enable on success
+3. **Worker model pinning** — arrow-key list per worker type (coding, research, architecture, review, documentation, translation, terminal, verification, vision, browser). Recommends a model for each based on capability match.
+4. **Default policy** — local-first, free-first, fastest, highest-quality, privacy-first, balanced, offline
+5. **Save** — prints a summary
+
+All choices are saved to the infinicode config. Setting up more providers gives the router more options for failover and rate-limit rotation.
+
+### Quick manual setup
+
+```bash
+# Ollama only (original v1 flow)
+infinicode connect 192.168.1.100
+
+# Add a cloud provider
+infinicode providers add
+
+# Pin a model per worker type
+infinicode workers edit
+```
+
+---
+
+### As a CLI (infinicode TUI)
+
+```bash
+npm install -g infinicode
+
+# Connect to your Ollama master
+infinicode connect 192.168.1.100
+
+# Set up cloud providers (Groq, OpenRouter, GitHub, NVIDIA, HF, Gemini)
+infinicode kernel-setup
+
+# Start the infinicode TUI — full provider pool injected
+infinicode
+```
+
+The `run` command (default) launches the **infinicode TUI** — the infinicode SolidJS terminal UI with the infinicode gold theme, animated logo, markdown rendering, diff view, and plugin slots. infinicode builds the provider config from your saved kernel config (Ollama + all enabled cloud providers) and injects it via `OPENCODE_CONFIG_CONTENT`, so the TUI can use **every provider** — not just a single Ollama master.
+
+The TUI is the **Harness** (prompts, workflows, personas, memory). For headless mission execution with full kernel routing (capability router, recovery, verification, checkpoints), use `infinicode mission run`.
+
+### As a kernel (new in v2)
+
+```bash
+# One-time friendly setup wizard (providers + worker models + policy)
+infinicode kernel-setup
+
+# Or set up individual pieces
+infinicode providers add     # add Groq/OpenRouter/GitHub/NVIDIA/HF
+infinicode workers edit      # pick a model per worker type
+
+# List built-in sample missions
+infinicode mission samples
+
+# Run a mission through the kernel
+infinicode mission run --goal "Reverse a string in TypeScript" --task "Write reverseString(s)" --cap coding
+
+# Run a sample
+infinicode mission run --sample hello-code
+
+# Mission status / list
+infinicode mission status <id>
+infinicode mission list
+```
+
+### As a device mesh (multi-device, new in v2)
+
+Install infinicode on every machine — laptop, workstation, Raspberry&nbsp;Pi — and they become one fleet. Spawn AI agents on any device from any device (no SSH), stream activity/hardware back, and drive it all from an MCP host like Claude Code or InfiniBot.
+
+```bash
+# install on each device
+npm install -g infinicode
+
+# same LAN — zero config: each node broadcasts a UDP beacon and auto-connects
+infinicode serve --hub --lan                         # your main machine
+infinicode serve --role satellite --lan              # a Pi / other box
+
+# across LAN + remote — auto-discover over Tailscale
+infinicode serve --hub --tailscale
+infinicode serve --role satellite --tailscale --tag tag:robopark
+
+# or point at exact peers
+infinicode serve --role satellite --seed http://192.168.1.20:47913
+
+# verify the mesh — ask any running node for its peers (self + connected)
+curl http://localhost:47913/fed/nodes
+```
+
+Set your cloud provider keys + policy **once on the hub**; every satellite auto-sources them (over `--seed`/`--lan`/`--tailscale`) and registers the providers + models live, no restart.
+
+Drive the fleet from an MCP host — register the control server (spawn / dispatch / follow / role / voice / mesh-map tools):
+
+```jsonc
+// ~/.claude.json
+{ "mcpServers": { "infinicode": { "command": "infinicode", "args": ["mcp", "--lan"] } } }
+```
+
+Link a node onto an **InfiniBot** neural-mesh map (no InfiniBot changes needed):
+
+```bash
+infinicode serve --hub --gateway ws://<infinibot-host>:18789 --gateway-token <token>
+```
+
+Discovery options: `--lan` (same subnet, zero-config UDP broadcast, port 47915), `--tailscale` (LAN+remote), `--seed <url>` (exact) — they combine. Full guide: `docs/user-manual.html`; design deep-dive: `docs/federation-architecture.html`.
+
+> The Windows TUI binaries are not shipped in the npm package (they're large and platform-specific), so `infinicode run` needs a local TUI build; the mesh commands (`serve`, `mcp`, `mission`, `console`) run everywhere as pure Node.
+
+### As a library
+
+```ts
+import { createKernel, OllamaProvider, OpenAICompatibleProvider } from 'infinicode/kernel';
+
+const kernel = createKernel();
+
+// Register providers (plugins — the application never knows which)
+kernel.registerProvider('ollama', new OllamaProvider({
+  baseURL: 'http://192.168.1.100:11434',
+  defaultModel: 'qwen2.5-coder:14b',
+}));
+
+kernel.registerProvider('openrouter', new OpenAICompatibleProvider({
+  id: 'openrouter',
+  name: 'OpenRouter',
+  baseURL: 'https://openrouter.ai/api',
+  apiKey: process.env.OPENROUTER_API_KEY!,
+}));
+
+// Subscribe to events (plugins, notifications, logging)
+kernel.subscribeAll(event => console.log(event.type));
+
+// Execute a mission — the kernel decides where/when/with which model
+const mission = await kernel.execute({
+  name: 'reverse-string',
+  description: 'Write a TypeScript string reverser',
+  goal: 'Produce a reverseString function',
+  policy: 'local-first',
+  tasks: [
+    {
+      description: 'Write the function',
+      capabilities: ['coding', 'reasoning'],
+      input: { prompt: 'Write `reverseString(s: string): string`. Include only the function.' },
+    },
+  ],
+});
+
+console.log(mission.status, mission.tasks[0].output?.content);
+```
+
+---
+
+## Core Principles
+
+1. **Execution First** — the kernel is not an agent framework. It executes missions. It doesn't define prompts, workflows, or personas. Those belong to Harnesses.
+2. **Framework Agnostic** — works equally well with Harness, custom workflows, CLI, n8n, Discord bots, VSCode extensions. Everything interacts through the same execution API.
+3. **Model Agnostic** — workers never request "Gemini". They request `Need: Coding, Reasoning>90, Vision, Context>128K`. The router decides.
+4. **Provider Agnostic** — providers are plugins. The application never knows.
+
+---
+
+## Architecture
+
+```
+                     Applications
+
+      Harness     CLI     n8n     VSCode
+
+                     │
+──────────────────── API ───────────────────
+                     │
+             AI Execution Kernel
+────────────────────────────────────────────
+
+Mission Engine
+Native Orchestrator
+Scheduler
+Worker Runtime
+Capability Router
+Provider Manager
+Policy Engine
+Verification
+Recovery
+Checkpoint Engine
+Event Bus
+Plugin Manager
+────────────────────────────────────────────
+
+Providers          Tools          Workers          Notifications
+```
+
+### Components
+
+| Component | Responsibility |
+|---|---|
+| **Mission Engine** | Lifecycle (NEW → PLANNING → READY → RUNNING → VERIFYING → WAITING → FAILED → COMPLETED), pause/resume, completion |
+| **Native Orchestrator** | Always running. Coordinates everything, executes nothing directly |
+| **Scheduler** | Mission → Objectives → Tasks → Execution Queue → Workers. Sequential, parallel, dependency graphs |
+| **Worker Runtime** | Disposable capability containers: Spawn → Initialize → Execute → Verify → Publish → Destroy |
+| **Capability Registry** | Workers advertise capabilities (coding, browser, vision, terminal, planning, reasoning, …) |
+| **Policy Engine** | 7 built-in policies: free-first, fastest, highest-quality, local-first, privacy-first, balanced, offline |
+| **Intelligent Router** | Scores: capability + reliability + speed + quota + context + policy − cost → best model + provider |
+| **Provider Manager** | Tracks models, quota, 429s, latency, success rate, health. Background refresh only, never blocks |
+| **Verification Engine** | Pipeline: objective → compile → tests → lint → browser tests → expected output → LLM judge (always last) |
+| **Recovery Manager** | Classifies failures (429, timeout, provider-down, hallucination, …) → retry / rotate / spawn-different-worker / replan / checkpoint |
+| **Checkpoint Engine** | Persists mission, objectives, tasks, worker state, memory, logs, artifacts. Pause/resume/crash-recovery |
+| **Event Bus** | Everything emits events. Plugins subscribe |
+| **Plugin System** | Core stays tiny. Telegram, Discord, Slack, Browser, Search, Dashboard, Metrics, … all optional |
+
+---
+
+## Worker Types (built-in)
+
+Workers are **capability containers, not personalities**. No prompts, no workflows, no personas — only capabilities. Any system prompt is supplied by the Harness via `TaskInput.context`, never by the worker itself.
+
+```
+research     browser     coding       architecture
+vision       review      documentation translation
+terminal     verification
+```
+
+Register custom workers via `kernel.registerWorker({ type, capabilities, preferences })`.
+
+---
+
+## Providers (built-in)
+
+| Provider | Type | File |
+|---|---|---|
+| **Ollama** | local | `ollama-provider.ts` (LAN + Tailscale fallback, migrated from v1) |
+| **OpenAI-compatible** | local/cloud | `openai-compatible-provider.ts` (powers OpenRouter, Groq, GitHub Models, NVIDIA, HF, vLLM, LM Studio, SGLang) |
+| **Gemini** | cloud | `gemini-provider.ts` (Google Generative Language API — generateContent / streamGenerateContent) |
+
+All three implement the same `ProviderInterface`. The application never knows which is in use.
+
+### Adding a cloud provider
+
+```ts
+import { OpenAICompatibleProvider } from 'infinicode/kernel';
+
+kernel.registerProvider('groq', new OpenAICompatibleProvider({
+  id: 'groq',
+  name: 'Groq',
+  baseURL: 'https://api.groq.com/openai',
+  apiKey: process.env.GROQ_API_KEY!,
+  knownModels: [
+    { id: 'llama-3.3-70b-versatile', contextLength: 128_000, supportsVision: false },
+  ],
+}));
+```
+
+### Adding Gemini
+
+```ts
+import { GeminiProvider } from 'infinicode/kernel';
+
+kernel.registerProvider('gemini', new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  knownModels: [
+    { id: 'gemini-2.0-flash', contextLength: 1_048_576, supportsVision: true, supportsFunctionCalling: true },
+  ],
+}));
+```
+
+---
+
+## Browser Layer (Phase 4)
+
+Default: **Playwright** (optional peer dependency). When Playwright is not installed, the browser controller degrades to a fetch-based read-only mode automatically.
+
+```ts
+import { createBrowserPlugin } from 'infinicode/kernel';
+await kernel.registerPlugin(createBrowserPlugin({ headless: true }));
+
+// Drive the browser via a mission task:
+const mission = await kernel.execute({
+  goal: 'Extract the latest news headlines',
+  tasks: [{
+    description: 'Open site and extract headlines',
+    capabilities: ['browser'],
+    input: {
+      prompt: 'Navigate and extract the top 5 headlines',
+      context: {
+        actions: [
+          { type: 'navigate', url: 'https://news.ycombinator.com' },
+          { type: 'extract' },
+        ],
+      },
+    },
+  }],
+});
+```
+
+## Search Layer (Phase 4)
+
+Default stack: **SearXNG → Crawler → Markdown → LLM**. Falls back to a DuckDuckGo HTML scrape when SearXNG is not configured.
+
+```ts
+import { createSearchPlugin } from 'infinicode/kernel';
+await kernel.registerPlugin(createSearchPlugin({ searxngUrl: 'http://localhost:8080' }));
+
+// Research worker uses the search controller automatically:
+const mission = await kernel.execute({
+  goal: 'Research latest TS patterns',
+  tasks: [{
+    description: 'Research and summarize',
+    capabilities: ['search', 'citations'],
+    input: { prompt: 'TypeScript branded types', context: { query: 'TypeScript branded types' } },
+  }],
+});
+```
+
+## Plugin SDK & Harness SDK (Phase 4)
+
+```ts
+import { definePlugin, mission, taskInput, browserTaskInput, researchTaskInput } from 'infinicode/kernel';
+
+// Author a plugin fluently
+const myPlugin = definePlugin('my-plugin')
+  .version('1.0.0')
+  .description('Custom notifier')
+  .subscribe(['MISSION_COMPLETED'], (e) => console.log('done', e.missionId))
+  .command('ping', 'Ping', async (args) => console.log('pong', args.join(' ')))
+  .build();
+await kernel.registerPlugin(myPlugin);
+
+// Build a mission input fluently
+const input = mission('reverse-string', 'Produce a reverseString function')
+  .description('Write a TypeScript string reverser')
+  .policy('local-first')
+  .task('Write the function', ['coding', 'reasoning'], taskInput('Write `reverseString(s)`'))
+  .build();
+await kernel.execute(input);
+```
+
+## Dashboard & Metrics (Phase 4)
+
+```ts
+import { createDashboardPlugin, createMetricsPlugin } from 'infinicode/kernel';
+
+const metrics = createMetricsPlugin();
+await kernel.registerPlugin(metrics);
+await kernel.registerPlugin(createDashboardPlugin({ port: 7331 }));
+
+// Read counters anytime
+console.log(metrics.snapshot());
+// → { missionsStarted: 3, tasksCompleted: 11, recoveries: 1, totalTokensOut: 4521, ... }
+```
+
+The dashboard serves `http://127.0.0.1:7331/` (HTML), `/status`, `/missions`, `/events`.
+
+---
+
+## Policies
+
+```yaml
+policy:
+  execution:
+    parallelism: 4
+  routing:
+    mode: free-first
+  verification:
+    strict
+  checkpoint:
+    every-task: true
+  retry:
+    maxAttempts: 5
+  notifications:
+    channels: [telegram]
+```
+
+Built-in: `free-first`, `fastest`, `highest-quality`, `local-first`, `privacy-first`, `balanced`, `offline`.
+
+```ts
+kernel.registerPolicy({
+  name: 'my-policy',
+  execution: { parallelism: 8 },
+  routing: { mode: 'balanced', preferredProviders: ['ollama', 'groq'] },
+  retry: { maxAttempts: 5 },
+});
+```
+
+---
+
+## Public API
+
+```ts
+kernel.execute(mission)     // → Promise<Mission>
+kernel.pause(missionId)     // → Promise<void>
+kernel.resume(missionId)    // → Promise<Mission>
+kernel.cancel(missionId)    // → Promise<void>
+kernel.status(missionId)    // → Promise<MissionStatus>
+kernel.subscribe(types, fn) // → unsubscribe
+kernel.subscribeAll(fn)      // → unsubscribe
+kernel.registerWorker(def)
+kernel.registerProvider(id, provider)
+kernel.registerPlugin(plugin)
+kernel.registerPolicy(policy)
+kernel.getMission(id)
+kernel.listMissions()
+```
+
+---
+
+## CLI Commands
+
+| Command | Alias | Description |
+|---|---|---|
+| `infinicode connect <ip>` | `ic c` | Quick connect to Ollama master |
+| `infinicode setup` | `ic s` | Interactive setup wizard (Ollama only) |
+| `infinicode run` | `ic` | Start the infinicode TUI (full provider pool: Ollama + cloud) |
+| `infinicode status` | | Show config & all provider health |
+| `infinicode models` | `ic m` | List available models across all healthy providers |
+| `infinicode config` | | View or modify configuration |
+| `infinicode kernel-setup` | `ic ks` | **Friendly setup wizard — providers + worker models + policy** |
+| `infinicode workers` | `ic w` | **View per-worker model preferences** |
+| `infinicode workers edit` | `ic w e` | **Interactively pick a model per worker type** |
+| `infinicode workers reset` | | Clear all worker pins |
+| `infinicode providers` | `ic p` | **View configured providers** |
+| `infinicode providers add` | | **Add a cloud provider (Groq/OpenRouter/GitHub/NVIDIA/HF/Gemini)** |
+| `infinicode providers remove <id>` | | Remove a cloud provider |
+| `infinicode providers test [id]` | | Test connection to one or all providers |
+| `infinicode mission run` | `ic k run` | **Execute a mission through the kernel** |
+| `infinicode mission samples` | | List built-in sample missions |
+| `infinicode mission status <id>` | | Show mission status |
+| `infinicode mission list` | | List missions in this session |
+| `infinicode mission resume <id>` | | Resume a paused mission |
+| `infinicode mission cancel <id>` | | Cancel a running mission |
+
+### Mission run options
+
+```
+infinicode mission run \
+  --goal "Mission goal" \
+  --name "mission-name" \
+  --task "Task 1 description" --task "Task 2 description" \
+  --cap coding,reasoning \
+  --policy local-first \
+  --sample hello-code
+```
+
+---
+
+## Worker Model Preferences
+
+Workers request **capabilities** (coding, reasoning, vision, …). The router picks the best model. You can **pin** a specific model per worker type — the pinned pair is used when healthy, otherwise the router falls back.
+
+```bash
+# View current pins
+infinicode workers
+
+# Interactively pick a model per worker type (arrow-key lists)
+infinicode workers edit
+
+# Clear all pins (router decides for every worker type)
+infinicode workers reset
+```
+
+Each worker type has a recommended default based on capability match across your configured providers. The wizard preselects the recommendation.
+
+### Worker types
+
+| Type | Capabilities | Description |
+|---|---|---|
+| `coding` | coding, reasoning, filesystem, terminal | Writes code |
+| `research` | search, crawl, summarize, citations | Researches with citations (SearXNG → Crawl → LLM) |
+| `architecture` | architecture, planning, reasoning | Designs structure |
+| `review` | review, coding, reasoning | Critiques code/design |
+| `documentation` | documentation, summarize, reasoning | Produces docs |
+| `translation` | translation, reasoning | Translates content |
+| `terminal` | terminal, coding, filesystem | Produces shell commands |
+| `verification` | verification, reasoning, review | Verifies acceptance criteria |
+| `vision` | vision, ocr, reasoning | Analyzes images |
+| `browser` | browser, crawl, search, reasoning | Drives a browser (Playwright or fetch fallback) |
+
+### Programmatic API
+
+```ts
+kernel.workerRuntime.setWorkerPin('coding', 'groq', 'llama-3.3-70b-versatile');
+kernel.workerRuntime.setWorkerPins(new Map([
+  ['coding', { providerId: 'ollama', modelId: 'qwen2.5-coder:14b' }],
+  ['research', { providerId: 'groq', modelId: 'llama-3.3-70b-versatile' }],
+]));
+kernel.setDefaultPolicy('local-first');
+```
+
+---
+
+**Harness owns:** Prompts, workflows, templates, agent design, memory strategy.
+**Kernel owns:** Execution, scheduling, workers, routing, recovery, verification, checkpoints.
+
+Perfect separation. A harness produces mission inputs; the kernel executes them.
+
+---
+
+## Harness Integration
+
+**Harness owns:** Prompts, workflows, templates, agent design, memory strategy.
+**Kernel owns:** Execution, scheduling, workers, routing, recovery, verification, checkpoints.
+
+Perfect separation. A harness produces mission inputs; the kernel executes them.
+
+---
+
+## Development Roadmap
+
+### Phase 1 — Core Runtime ✅
+
+- [x] Mission Engine
+- [x] Scheduler
+- [x] Worker Runtime
+- [x] Provider Interface (Ollama + OpenAI-compatible)
+- [x] Event Bus
+- [x] Checkpoints
+- [x] Capability Router (policy-weighted scoring)
+- [x] Policy Engine (7 built-in policies)
+- [x] Plugin Manager + Telegram/Discord/Slack/Browser/Search stubs
+- [x] Setup wizard + worker model pinning + free cloud provider presets
+
+**Target:** Stable execution kernel. ✅
+
+### Phase 2 — Intelligent Routing
+
+- [x] Model scoring benchmarks
+- [x] Capability-based routing with health awareness
+- [x] Free-first routing
+- [x] Automatic failover (via Recovery Manager → rotate-provider)
+- [x] Provider telemetry: 429 / quota / success-rate tracking
+
+**Target:** Provider-independent inference. ✅
+
+### Phase 3 — Reliability
+
+- [x] Verification engine (objective → compile → tests → lint → browser → expected output → LLM judge)
+- [x] Recovery manager (retry → rotate provider → spawn different worker → replan → checkpoint)
+- [x] Long-running missions (checkpoint + resume)
+- [x] Persistent checkpoints (fs-backed, capped at 20/mission)
+- [ ] Automatic replanning (planning-failure → replan action wired; full objective re-plan pending)
+
+**Target:** Autonomous execution. ✅ (core)
+
+### Phase 4 — Ecosystem
+
+- [x] Telegram notifications + slash commands (/status /workers /logs /pause /resume /retry /models /providers /checkpoints /goal)
+- [x] Browser worker (Playwright-backed; fetch fallback when Playwright not installed)
+- [x] Research worker (SearXNG → Crawl4AI-style crawler → Markdown → LLM; DuckDuckGo fallback)
+- [x] Plugin SDK (`definePlugin()` fluent builder)
+- [x] Harness SDK (`mission()` builder + `taskInput`/`browserTaskInput`/`researchTaskInput` helpers)
+- [x] Dashboard plugin (HTTP `/status` `/missions` `/events` + HTML view)
+- [x] Metrics plugin (runtime counters: missions/tasks/workers/tokens/latency)
+- [x] Gemini provider (Google Generative Language API — dedicated class, not OpenAI-compatible)
+- [ ] Natural chat with orchestrator via Telegram
+- [ ] Vision / Email / Database / Storage / Monitoring plugins
+
+**Target:** Extensible platform. ✅ (core)
+
+---
+
+## Configuration
+
+Config is stored automatically (via `conf`). Override with:
+
+```bash
+infinicode config --set defaultModel=qwen2.5-coder:14b
+infinicode config --set masterUrl=http://192.168.1.100:11434
+infinicode config --list
+```
+
+Checkpoints persist to `.openkernel/checkpoints/` (capped at 20 per mission).
+
+---
+
+## Recommended Models
+
+| Model | Size | Best For |
+|---|---|---|
+| `qwen2.5-coder:14b` | 9GB | Great balance |
+| `qwen2.5-coder:32b` | 20GB | Best quality |
+| `deepseek-coder-v2:16b` | 10GB | Strong reasoning |
+| `codestral:22b` | 13GB | Fast completion |
+
+---
+
+## Requirements
+
+- Node.js 20+
+- infinicode installed globally (`npm install -g infinicode`) — provides the TUI binary
+- An Ollama master running somewhere on your network — for the kernel's default local provider
+- Optional: cloud provider API keys (Groq, OpenRouter, GitHub, NVIDIA, HF, Gemini) for provider rotation
+
+---
+
+## License
+
+MIT
+
+---
+
 ⚡ Built for sovereign computing. Your code, your models, your hardware.