EKOS Web Console

EKOS is a compiler for enterprise knowledge. It observes source systems without interpreting them, compiles those observations through deterministic passes into a Canonical Knowledge Model, and stores the result in an append-only ledger where every conclusion carries the evidence it was derived from. Until now the only way to look at a compiled workspace was a terminal or an AI agent over MCP — the product's central claim, a traceable evidence chain, had no visual form.

The console closes that. It is a FastAPI application (web/api/) plus a Vite + React app (web/ui/). It never touches raw source systems: reads go through the read-only EKOS Runtime over the Model Context Protocol, and the few write actions run the ekos CLI as a subprocess against a hardcoded allowlist.

One FastAPI process holds five concerns. The workspace registry (SQLite) is the source of truth for what exists. The MCP supervisor spawns and restarts one ekos mcp serve --tcp per registered workspace and owns a pooled client to each. The job runner executes allowlisted ekos commands through a bounded per-workspace queue. The scheduler fires those same commands on a cron or interval trigger. Auth resolves a read/write principal per request.

Phase 0 is pure plumbing — the pieces the browser needs before any pixel. RFC 0127's earlier increment had already landed ekos graph export (the first bulk graph-extraction path in EKOS — every other read is per-object or LIMIT 50), ekos status --json, and the ekos_graph_export MCP tool. This phase added the rest:

• R4 — bearer-token auth on ekos mcp serve --tcp. The first line on an authenticated connection must be an initialize carrying params._meta.token; anything else gets a single -32001 unauthorized and the socket closes before a tool is reachable. Hand-rolled constant-time compare, no new dependency. Token-less --tcp is unchanged.
• The Python MCP client — app/mcp_client.py, ~150 lines, asyncio, no SDK. Framing is one JSON object per line; call_tool unwraps the server's JSON-inside-JSON result; one automatic reconnect on a mid-call EOF.
• The web/ skeleton — the FastAPI app factory, a handful of real endpoints proving the wiring end to end, a Vite + React shell, and a docker-compose.yml.

Phase 1 makes the console own its inputs. A registered workspace is a directory containing ekos.toml and .ekos/; the console does the rest. The McpSupervisor spawns one ekos mcp serve --tcp per workspace on a loopback port with a fresh 32-byte token, probes it with tools/list before marking it ready, and restarts it with exponential backoff (cap 30 s, five strikes then failed). Two small Rust additions feed the dashboard: R5 ekos doctor --json and R6 ekos ledger timeline --json — cumulative object and relationship counts bucketed by mint time, backend-agnostic, no new KnowledgeStore method.

Getting [observe] wrong is expensive in a way that isn't obvious: the ledger is append-only, so narrowing a path or an ignore-pattern never retroactively removes already-compiled data — the only remedy is a full wipe and rebuild. Phase 2 makes that concrete. R7 ekos config validate reports TOML syntax and deny_unknown_fields errors plus [observe] warnings; R8 ekos config preview-scan counts what ekos build would observe — files by extension, and how many directories each ignore-pattern actually pruned. The editor writes an ekos.toml.bak, and a narrowing save returns the wipe-and-rebuild warning.

Phase 3 lets you run EKOS pipeline commands from the browser and watch them stream — the first mutation, so it also brings the read/write role split. A hardcoded COMMAND_ALLOWLIST of 15 entries is the only way to run anything; argv is built from a fixed template plus validated parameters, never interpolated into a shell.

The pipeline command chains the five verbs as one run entry with per-stage status, stopping on the first non-zero exit:

The JobRunner keeps one bounded queue and one worker task per workspace — the single worker serialises everything, which is what the ledger's write lock demands. Output is streamed ANSI-stripped to .ekos-web/runs/<id>.log; the browser follows it over an SSE endpoint that replays existing lines then polls to a terminal status. Cancellation is SIGTERM then SIGKILL. On startup any run left running is swept to interrupted.

Auth — two modes, one cookie

Both modes end in a signed session cookie — EventSource can't set an Authorization header, so the SSE log stream needs cookie auth to work at all.

A Schedule row — workspace, command, params, a cron or interval trigger, a required notify_url — fires the same job runner. The row is the source of truth: ConsoleScheduler runs APScheduler in memory and rebuilds it from the enabled rows on every console start, so there is no pickle-based job store to corrupt. Triggers are validated at create time (CronTrigger.from_crontab, UTC) — a bad expression is a 422, never a background crash. misfire_grace_time=1 means a schedule that should have fired during a restart is skipped, not caught up.

On any non-succeeded terminal run — including a QueueFull — the console POSTs {schedule_id, workspace_id, command, run_id, status, detail} to the notify_url. Best-effort, logged, no retry. The one change to Phase 3's runner is a single optional on_done callback on submit.

ekos graph export shipped in Phase 0 with nothing that drew it. Phase 5 draws it, in 2D (react-force-graph-2d, canvas — a third the bundle of the three.js build, and the labels stay readable). The renderer is behind a React.lazy boundary: a separate 178 KB chunk that the rest of the console never loads.

Clicking a super-node drills in. The first cut filtered to that one kind and lost every cross-kind edge — RustModule and File connect almost entirely to other kinds, so they showed zero edges. The rework fetches the whole object graph at a min degree threshold (default 2, ~800 nodes); the focused kind stays bright and every other kind dims to 20% alpha.

1. The browser sends a cookie-authed GET /api/workspaces/self/graph?level=aggregate&group_by=kind.
2. FastAPI resolves the read principal, looks the workspace up in SQLite, and asks the supervisor for that workspace's pooled MCP client.
3. The client sends one tools/call line for ekos_graph_export over the NDJSON/TCP socket, holding an asyncio.Lock so one request is on the wire at a time.
4. ekos mcp serve answers from its cached read-only handle — one whole-store walk over all_objects + all_relationships, collapsed to super-nodes, truncated by degree if over the caps, with the truncation reported in the payload.
5. The response line (which can exceed 64 KiB — hence the reader-limit fix) is parsed and returned. React maps {s, t} edge indices to node ids and hands the result to the canvas.

The Rust workspace gate (fmt, clippy --workspace, test --workspace, integration) and the web/api pytest suite (72 passing, the EKOS_BIN-gated ones included) both run clean; web/ui typechecks and builds with the graph renderer as a separate lazy chunk. Every phase merged to main after local verification.

HTTP surface