# 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`.

### One-link MCP mesh connection

On the first Tailscale device, generate the direct link and start MCP. Infinicode creates and persists the shared token automatically:

```bash
infinicode mesh link
infinicode mcp --tailscale
```

Give the single generated `http://.../fed/join?token=...` URL to the agent on the second device. It can connect immediately with either:

```bash
infinicode mcp --connect "PASTE_LINK_HERE"
infinicode mesh join "PASTE_LINK_HERE" --host opencode
```

The first form runs an MCP instance directly. The second persists the same MCP connection in OpenCode or Claude (`--host all` configures both). The link is a credential: share it only inside the tailnet and rotate the mesh token if it leaks.

> 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.