# Architecture OpenMono is a .NET 10 CLI that runs a local agentic loop against a llama.cpp inference server (or any OpenAI-compatible endpoint). The agent normally runs in a Docker sandbox — your project folder bind-mounts in as `/workspace`. macOS inference and the Strata backend run natively on the host, and host mode is a deliberate, permission-gated escape hatch.

OpenMono architecture diagram

--- ## High-level topology ``` ┌──────────────────────────────────┐ ┌──────────────────────────────────┐ │ openmono (CLI / TUI) │ │ VS Code / Cursor extension │ │ src/OpenMono.Cli/ │ │ StartupHakk.openmono-agent │ │ │ │ (sidebar chat panel) │ │ ConversationLoop │ │ · streams responses │ │ └── ILlmClient (streaming SSE)│ │ · executes workspace tools │ │ └── ToolDispatcher │ │ (file edits, bash, grep, │ │ └── 21 built-in tools │ │ patches, permission prompts) │ │ └── MCP tools (dynamic) │ └──────────────┬───────────────────┘ │ └── LSP tools │ │ HTTP/SSE (ACP) :7475 │ └── RoslynTool │ ▼ │ └── PermissionEngine │ ┌──────────────────────────────────┐ │ └── SessionManager (JSONL) │ │ ACP server (--acp-only mode) │ │ └── Compactor / Checkpointer │ │ same ConversationLoop + tools │ │ └── HookRunner │ │ as the CLI — extension is UI │ │ └── IRenderer (TUI | Classic)│ └──────────────┬───────────────────┘ └────────────────┬─────────────────┘ │ │ HTTP :7474 (OpenAI-compat) │ HTTP :7474 └──────────────────┬─────────────────┘ ▼ ┌────────────────────┐ │ llama-server │ │ (llama.cpp) │ │ Qwen3.6 GGUF │ └────────────────────┘ ``` The CLI and the VS Code/Cursor extension share the same agent core. The extension connects over ACP (Agent Client Protocol) on `:7475` — start the agent with `--acp-only --acp-port 7475` to expose this interface instead of the TUI. Host mode adds a second ACP client: the **HostBridge** daemon (`src/OpenMono.HostBridge`, loopback :7476) executes whole-machine commands on behalf of a sandbox session. The sandbox `HostGateway` pairs with it (shared secret, per-session token, idle-token expiry via `--idle-timeout` with a background `/keepalive` heartbeat + silent auto re-pair so a live agent's session never expires mid-task, `GET /status` for liveness); consent for each host command is forwarded up the ACP `user_input_request` pause with structured `host_exec` fields, so a remote client can approve or deny. The session-level toggle is `POST /api/v1/sessions/{id}/host` (`{"action":"on"|"off"}`). See [Deployment modes → Host mode](DEPLOYMENT-MODES.md). --- ## Inference-side web services (Caddy gateway) One tunnel, three services. `WebSearch` & `WebFetch`, self-hosted. The agent's `WebSearch` and `WebFetch` tools route through a single Caddy gateway that sits beside the inference server. `frpc` tunnels only that one port — Caddy fans requests apart by path to SearXNG, Scrapling, and llama-server. Services are opt-in, auto-detected, and every tool degrades to a built-in default when its service is absent. | | | |---|---| | **Gateway** | Caddy 2 · `:47480` | | **Search** | SearXNG — backs `WebSearch` | | **Scrape** | Scrapling + Camoufox — backs `WebFetch` | | **Auth** | shared `LLAMA_API_KEY` bearer on `/search*` and `/scrape*` | ``` ┌──────────── inference box ────────────┐ agent ──frpc/relay──▶ │ Caddy gateway :8080 → :47480 │ llm.endpoint ┐ │ /v1,/props,/metrics → llama-server │ (pass-through, SSE flush -1) web.gateway ──┴───▶ │ /search* [Bearer] → SearXNG:8080 │ │ /scrape* [Bearer] → Scrapling:5000 │ │ /services → capability JSON│ │ /health → 200 (no auth) │ └────────────────────────────────────────┘ ``` `llm.endpoint` and `web.gateway` resolve to the **same** relay URL in dual-box mode — Caddy fans them apart by path, so `web.gateway` is optional. The only thing to configure on the agent box is `llm.endpoint` + `llm.api_key`. ### How a tool picks its path Every `WebSearch` / `WebFetch` call walks this decision before doing any network work. `GatewayCapabilities` owns the logic and caches the answer per gateway URL for the whole process — the registry is probed at most once per session. 1. **Explicit config override wins** — `web.search` / `web.scrape` in config or `OPENMONO_WEB_SEARCH` / `OPENMONO_WEB_SCRAPE` env var. Truthy = `1/true/yes/on`. 2. **Resolve the gateway URL** — `web.gateway` if set, else `llm.endpoint`. No gateway → fall back immediately. 3. **Probe `GET /services` (cached, 5 s timeout)** — returns `{"search": true, "scrape": false}`. Memoised in a `ConcurrentDictionary` keyed by gateway URL. 4. **Route through the gateway** — `POST/GET` to `/scrape` or `/search` with the shared `LLAMA_API_KEY` bearer. 5. **Fall back on any failure** — service absent, probe fails, non-JSON body, or request throws → tool silently uses DuckDuckGo / direct `HttpClient` fetch. Cancellation token is the one exception that always propagates. ### The two tools **`WebSearch`** — read-only, concurrency-safe Primary: `GET /search?q=…&format=json` against the gateway; parses `results[]` into title / url / snippet. Fallback: scrapes `html.duckduckgo.com` exactly as before. **`WebFetch`** — 90 s ceiling, browser-capable Primary: `POST /scrape` with `{url, render, headless, max_length, format:"markdown"}`. Returns clean markdown. `render` forces a real browser; `headless` toggles headed mode — both only apply on the gateway path. Fallback: original direct `HttpClient` fetch + HTML strip. ### Scrapling engine selection The FastAPI wrapper (`docker/scrapling/app.py`) runs auth-free on the internal network — Caddy enforces the bearer in front. | | Engine | Condition | |---|---|---| | A | `AsyncFetcher` (fast path) | Plain async HTTP. Default unless `render:true`. | | B | Auto-escalate | 403 / 429 / 503 or thrown fetch → retries with stealthy. | | C | `StealthyFetcher` (stealth) | Camoufox real browser, `solve_cloudflare=True`, network-idle wait. | ### Install ```bash openmono setup gateway # Caddy only openmono setup search # SearXNG + gateway (profile: search) openmono setup scraper # Scrapling + gateway (profile: scraper) ``` ### Component reference | Component | Layer | Responsibility | |-----------|-------|----------------| | `WebSearchTool.cs` | agent | Routes to SearXNG, parses JSON; DuckDuckGo fallback | | `WebFetchTool.cs` | agent | POSTs to Scrapling with `render`/`headless`; direct-fetch fallback | | `GatewayCapabilities.cs` | agent | Resolves gateway URL, probes `/services`, caches per-URL | | `WebConfig` (`AppConfig.cs`) | agent | Gateway / Search / Scrape config + truthy parsing + env merge | | `docker/Caddyfile` | gateway | Path-routing, bearer enforcement, `/services` registry, SSE pass-through | | `docker/scrapling/app.py` | service | FastAPI wrapper: fast→stealth engine selection, markdown extraction | | `docker/searxng/settings.yml` | service | Enables JSON format, disables rate limiter (internal traffic) | | `docker-compose.yml` | infra | `caddy` / `searxng` / `scrapling` under `search` / `scraper` profiles | | `openmono setup *` | infra | Installs services, flips `WEB_*_ENABLED`, retargets frpc tunnel | Files: [docker/Caddyfile](../docker/Caddyfile), [docker/searxng/settings.yml](../docker/searxng/settings.yml), [docker/scrapling/](../docker/scrapling/), [docker/docker-compose.yml](../docker/docker-compose.yml). --- ## Startup sequence (`Program.cs`) 1. Parse CLI flags (`--tui`, `--classic`, `--endpoint`, `--model`, `--verbose`, …) 2. Probe the LLM server — tries `/props` (llama.cpp), falls back to `/v1/models` — to detect the live model name and context size 3. Create `SessionState` (12-char UUID, timestamp, empty message list) 4. Wire DI: config → renderer → permissions → memory → hooks → LSP/MCP managers → playbook registry → tool registry → LLM client 5. Choose renderer: `UseTui ?? (!Console.IsInputRedirected && !Console.IsOutputRedirected)` — TUI by default for interactive terminals 6. Launch `ConversationLoop.RunAsync()` --- ## Conversation loop (`ConversationLoop.cs`) ### Initialisation (once) - Build system prompt: base instructions + project `OPENMONO.md` + cross-session memory + git branch/status - Start LSP servers, MCP servers, load playbooks, register commands and hooks ### Per-turn flow ``` User input │ ├─ /command → CommandRegistry.Execute() │ └─ message │ ├─ Checkpoint if >65% context used (LLM-generated summary, preferred) ├─ Compact if >80% context used (fallback — summarise + keep last 4 turns) │ └─ Stream LLM (up to 1,000 iterations) │ ├─ ThinkingDelta → thinking panel (collapsed on first text) ├─ TextDelta → streamed to output ├─ ToolCallDelta → accumulated, dispatched after stream ends └─ Usage → token counter │ └─ Tool execution (see below) │ └─ Results added to session → next LLM iteration ``` Turn ends when the LLM produces text with no tool calls. Session saved to JSONL. **Doom loop detection**: repeated tool-call batches (period 1–4) are detected and handled in tiers. The first detection adds a nudge, the third consecutive detection escalates to a strong nudge, and the fifth ends the turn. The streak clears after a full clean detection window. --- ## Tool execution pipeline Every tool call goes through this pipeline before touching anything: ``` 1. Parse JSON arguments 2. Schema validation (required fields, types, enums) 3. Sanity check (e.g. path outside workspace → reject) 4. Plan mode gate (read-only tools only when in plan mode) 5. Host mode gate (HostExec only when host mode is enabled) 6. Capability check → PermissionEngine ├─ Auto-allowed (FileRead, Glob, Grep, …) ├─ Config rules (allow/deny patterns per tool) └─ Interactive (prompt user → once / session / deny) 7. Result cache lookup (read-only tools) 8. Pre-tool hook 9. Execute 10. Post-tool hook 11. Artifact store (>10 KB results → stored, reference returned to model) 12. Cache write 13. File cache invalidation (FileWrite/FileEdit/ApplyPatch) ``` **Concurrency**: read-only + concurrency-safe tools run in parallel (`Task.WhenAll`). Writable tools run serially. Read-only tasks can start while the LLM is still streaming. ## Session & context management ### Persistence (`SessionManager`) - Format: JSONL — line 1 is a header record, subsequent lines are messages - Path: `~/.openmono/sessions/{date}_{sessionId}.jsonl` - Checkpoints stored alongside: `{date}_{sessionId}.checkpoints.json` ### Context window management | Threshold | Action | |-----------|--------| | 65% | **Checkpoint** — LLM summarises messages up to N recent turns; summary stored with cutoff index; future context window starts from cutoff | | 80% | **Compact** (fallback) — summarise all messages except last 4 turns; replace with summary message + recents | The CLI reads the actual context size from `/props` at startup, so both thresholds track the real window. --- ## Sub-agents (`AgentTool`) Spawns an isolated session with a restricted tool set and a dedicated system prompt. Parent session's permission engine is reused. | Agent | Max turns | Allowed tools | Purpose | |-------|-----------|---------------|---------| | `general-purpose` | 200 | all | generic tasks | | `Explore` | 100 | FileRead, Glob, Grep, ListDirectory, WebSearch, WebFetch, ToolSearch, MCP | read-only discovery | | `Plan` | 100 | FileRead, Glob, Grep, ListDirectory, WebSearch, WebFetch, ToolSearch, TodoWrite, MCP (no writes) | architecture planning | | `Coder` | 300 | FileRead/Write/Edit, ApplyPatch, Glob, Grep, ListDirectory, Bash, AskUser, TodoWrite, WebSearch, WebFetch, ToolSearch, MCP | implementation | | `Verify` | 150 | FileRead, Glob, Grep, ListDirectory, Bash, Roslyn, LSP, MCP | adversarial testing | Tool allow-lists support wildcards (`*`, `mcp__*`). --- ## MCP client (`McpServerManager` + `McpClient`) On startup, for each enabled MCP server in config: 1. Spawn subprocess (command + args + env) 2. JSON-RPC 2.0 handshake over stdin/stdout (`initialize` → `notifications/initialized`) 3. `tools/list` → get tool definitions 4. Register each tool as `mcp__{serverName}__{toolName}` in `ToolRegistry` `McpClient` serialises requests, reads responses, and exposes `CallToolAsync`, `ListResourcesAsync`, `ReadResourceAsync`. **Auto-detected servers**: `code-review-graph` is registered automatically when it is in `PATH` and a graph DB exists. `graphify` is not an MCP server; when `graphify-out/graph.json` exists, OpenMono detects it and tells the agent to use the `graphify` CLI through `Bash`. --- ## LSP client (`LspServerManager` + `LspClient`) Language servers start lazily on first call. File extension → language mapping: | Extension | Server | |-----------|--------| | `.cs` | OmniSharp | | `.ts` / `.tsx` | typescript-language-server | | `.py` | pylsp | | `.go` | gopls | | `.rs` | rust-analyzer | `LspTool` exposes: `hover`, `definition`, `references`. --- ## Roslyn tool (`RoslynTool`) Loads all `.cs` files from the working directory into an in-memory `AdhocWorkspace` with .NET runtime metadata references. Compilation is cached for 5 minutes. Actions: | Action | What it returns | |--------|-----------------| | `overview` | Types and members in a file | | `find-references` | Every usage of a symbol | | `callers` | Methods that call a given method | | `diagnostics` | Compiler errors and warnings | | `capture-baseline` | Snapshot diagnostics as a baseline for later comparison | | `search` | Symbols matching a name pattern | | `type-hierarchy` | Base types, interfaces, derived types | | `blast-radius` | Direct + transitive dependents | | `get-symbol` | Kind, type, parameters, modifiers, location | --- ## Permissions (`PermissionEngine`) **Capability system (primary)** — tools declare what they need: | Capability | Example | |------------|---------| | `FileReadCap(path)` | read a file | | `FileWriteCap(path, op)` | write / create / delete | | `ProcessExecCap(binary, args)` | shell execution | | `NetworkEgressCap(host, port)` | HTTP/HTTPS call | | `VcsMutationCap(repo, op)` | git write | | `AgentSpawnCap(type, task)` | spawn sub-agent | Decision order: session deny-all → config deny patterns → session allow-all → config allow patterns → **interactive prompt** (allow once / session / deny once / session). **Legacy system (fallback)** — tools declare `PermissionLevel`: `AutoAllow`, `Ask`, or `Deny`. --- ## Hooks (`HookRunner`) Bash scripts triggered at three points. Conditions can filter by tool name or input substring. ```jsonc // settings.json { "hooks": { "preToolUse": [ { "if": { "tool": "Bash", "inputContains": "rm" }, "run": "echo '{{tool_name}}: {{tool_input}}' >> audit.log" } ] } } ``` Hook types: `SessionStart`, `PreToolUse`, `PostToolUse`. Timeout: 30 s each. --- ## Rendering `IRenderer` is a composite interface: `IOutputSink` (write markdown, tool events) + `IInputReader` (read input, show pickers) + `ILiveFeedback` (stream text, thinking panel, tok/s indicator). | Implementation | Mode | When used | |----------------|------|-----------| | `AnsiTuiRenderer` | Full-screen (Spectre.Console) | Interactive terminal | | `TerminalRenderer` | Scrolling REPL | Redirected I/O or `--classic` | The TUI is powered by [Spectre.Console](https://spectreconsole.net) — a cross-platform .NET library for building rich terminal UIs with colors, tables, progress bars, and interactive components. --- ## Key types (reference) ```csharp interface ITool { string Name { get; } string Description { get; } JsonElement InputSchema { get; } bool IsConcurrencySafe { get; } bool IsReadOnly { get; } Task ExecuteAsync(JsonElement input, ToolContext ctx, CancellationToken ct); PermissionLevel RequiredPermission(JsonElement input); IReadOnlyList RequiredCapabilities(JsonElement input); } interface ILlmClient { IAsyncEnumerable StreamChatAsync( IReadOnlyList messages, JsonElement? tools, LlmOptions options, CancellationToken ct); } // Messages record Message(MessageRole Role, string? Content, List? ToolCalls, string? ToolCallId, string? ToolName); record ToolCall(string Id, string Name, string Arguments); // Arguments = JSON string // Streaming record StreamChunk { ThinkingDelta? Thinking; TextDelta? Text; ToolCallDelta? ToolCall; Usage? Usage; bool IsComplete; } ``` --- ## Project layout ``` src/OpenMono.Cli/ ├── Program.cs entry point, DI wiring, startup sequence ├── Session/ ConversationLoop, SessionManager, Compactor, Checkpointer, TokenTracker ├── Tools/ 21 built-in tools + ToolRegistry, ToolDispatcher, SchemaValidator, AgentTool, LspTool, RoslynTool ├── Llm/ ProviderRegistry, AnthropicClient, OpenAiCompatClient ├── Permissions/ PermissionEngine, Capability, PermissionLevel ├── Agents/ AgentDefinition (built-in sub-agent presets) ├── Mcp/ McpClient, McpServerManager, McpToolAdapter ├── Lsp/ LspClient, LspServerManager ├── Playbooks/ PlaybookExecutor, PlaybookLoader, TemplateEngine, ParameterValidator ├── Commands/ 20 slash commands (/help, /status, /model, /compact, /undo, /btw, …) ├── Memory/ Cross-session memory (YAML frontmatter files) ├── Hooks/ HookRunner ├── Rendering/ AnsiTuiRenderer, TerminalRenderer, IRenderer └── Utils/ Git, process, path helpers src/OpenMono.Core/ ├── Config/ AppConfig, ConfigLoader, HookDefinition ├── Session/ SessionState ├── History/ File snapshots for /undo ├── HostExec/ Host daemon client and consent ├── Permissions/ PermissionStore, PathGuard └── Playbooks/ PlaybookDefinition ```