plans: add oikos gaps review and control-room webui plans
Documents a full-project review (confirmed bugs, security gaps, user- and agent-perspective gaps) and a realtime control-room web UI plan, per prior codebase exploration on this branch. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
184
plans/2026-07-08-control-room-webui.md
Normal file
184
plans/2026-07-08-control-room-webui.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 2026-07-08 — Control room web UI
|
||||
|
||||
**Status:** Planned
|
||||
|
||||
## Goal
|
||||
|
||||
A realtime "control room" web UI for inspecting the state of Oikos and all its
|
||||
entities — graphs, tables, and lists — that updates live as an agent (Hermes)
|
||||
interacts with the system: executions appearing, approvals firing, health
|
||||
changing, the entity graph mutating. Inspect **and act**: approve/deny pending
|
||||
approvals and ack/resolve/mute signals directly from the UI.
|
||||
|
||||
---
|
||||
|
||||
## Stack (decided)
|
||||
|
||||
**Svelte 5 + Vite + TypeScript SPA**, compiled to static assets in
|
||||
`web/dist`, embedded into the existing `oikos` binary via
|
||||
`go:embed all:web/dist` in a new `internal/httpapi/ui.go`, served at `/ui/`
|
||||
(redirect `/` → `/ui/`, SPA fallback to `index.html`).
|
||||
|
||||
Why: the hard requirements (force-directed graph, time-series charts, one SSE
|
||||
stream patching many widgets) are client-side-JS problems; Svelte's reactive
|
||||
stores map 1:1 onto "SSE event mutates shared state, every widget reacts";
|
||||
the compiled runtime keeps the embed small; and `openapi-typescript` generates
|
||||
frontend types from `api/openapi.yaml` — the frontend twin of the repo's
|
||||
oapi-codegen contract-first discipline (ADR-0004). Embedding preserves the
|
||||
single-binary story: no new container, no CORS, no Caddy changes.
|
||||
|
||||
Dependencies kept minimal:
|
||||
- `d3-force` — graph physics only; render SVG/canvas by hand
|
||||
- `uPlot` — ~45 KB canvas time-series, ideal for `/metrics` rollups
|
||||
- `openapi-typescript` — dev-only, generates `api-types.d.ts`
|
||||
- No SvelteKit (no SSR wanted — the Go binary is the server), no component
|
||||
framework; hash router; hand-rolled dark-theme CSS.
|
||||
|
||||
Build integration: commit a placeholder `web/dist/index.html` so backend-only
|
||||
`go build` never breaks; `make ui` runs the Vite build; add a node stage to
|
||||
`compose/oikos/Dockerfile` (3-stage: node → go → runtime). Local dev:
|
||||
`vite dev` proxying `/api` → `:8090`.
|
||||
|
||||
---
|
||||
|
||||
## Realtime
|
||||
|
||||
Reuse the existing pipeline: migration 008's `pg_notify('oikos_events')`
|
||||
trigger → `internal/httpapi/sse.go` broker → `GET /api/v1/events/stream`
|
||||
(Last-Event-ID replay, 15s heartbeat). One shared `EventSource` in a Svelte
|
||||
store; pages subscribe by event type and either patch state from `event.data`
|
||||
or trigger a targeted refetch. Scheduler and actuator are separate processes
|
||||
but share Postgres, so their events reach the api role's LISTEN automatically.
|
||||
|
||||
### Event emission gap-fill (required)
|
||||
|
||||
Today only 5 event types are emitted (`entity.created`, `entity.updated`,
|
||||
`client.enrolled`, `entity.provisioned`, `execution.requested`). Most of what
|
||||
the control room must show live is silent. Add `observability.Event(...)`
|
||||
calls at:
|
||||
|
||||
| Event | Site |
|
||||
|-------|------|
|
||||
| `signal.raised` / `signal.resolved` | `internal/scheduler/scheduler.go` (~115 / ~145) |
|
||||
| `health.changed` (on transition only, to avoid flooding) | scheduler `entity_status` writes (~104/135/156) |
|
||||
| `signal.acked` / `signal.muted` / `signal.resolved` (API side) | `internal/httpapi/impl.go:545/582/619` |
|
||||
| `approval.created` | `internal/mcp/server.go` `createApproval` — depends on bug A1 in [gaps plan](2026-07-08-oikos-gaps-and-improvements.md) |
|
||||
| `approval.decided` | `internal/httpapi/phase3.go:871` |
|
||||
| `execution.started/completed/failed/cancelled` | `internal/actuator/actuator.go`, `phase3.go:746` |
|
||||
| `relationship.created` / `relationship.ended` | `phase3.go:1560/1621` |
|
||||
|
||||
Agent activity: poll `GET /agent-activity` every ~5s rather than duplicating
|
||||
every tool call into `events`.
|
||||
|
||||
---
|
||||
|
||||
## API surface
|
||||
|
||||
Existing endpoints already cover nearly everything the UI needs:
|
||||
`/graph?root=&depth=&rel_type=` (impl.go:268), `/health` fleet rollup
|
||||
(impl.go:481), `/metrics?rollup=raw|1h|1d|auto&from=&to=`, `/trends/{id}`,
|
||||
`/events` (filterable) + `/events/stream` (SSE), `/signals` + ack/resolve/
|
||||
mute, `/executions`, `/approvals` + `POST /approvals/{id}/decision`,
|
||||
`/agent-activity`, `/knowledge/search`, `/audit`, entities CRUD, `/ontology`.
|
||||
|
||||
New endpoints (spec-first in `api/openapi.yaml`, regen, then implement):
|
||||
|
||||
1. `GET /api/v1/dashboard/summary` (new `internal/httpapi/dashboard.go`) —
|
||||
one round-trip for the overview: entity counts by type/state, health
|
||||
rollup from `entity_status`, open signals by severity, pending approvals,
|
||||
executions by state (24h), event-rate sparkline (count/5min from the
|
||||
`events` hypertable).
|
||||
2. `GET /graph?include=status` — join `entity_status` so graph nodes can be
|
||||
colored by health (preferred over a separate bulk-status endpoint).
|
||||
|
||||
---
|
||||
|
||||
## Auth & deployment
|
||||
|
||||
- Serve `/ui/*` assets without `combinedAuth` — Caddy/Authentik already gates
|
||||
the `oikos.hubris.network` vhost, and the assets are public JS/CSS.
|
||||
- **Trusted-proxy header auth** for API calls from the browser: extend
|
||||
`combinedAuth` (`internal/httpapi/server.go:157`) with a config flag
|
||||
(`OIKOS_TRUSTED_PROXY_AUTH`) — when no Bearer token is present but Authentik
|
||||
forward-auth headers (`X-Authentik-Username`/`-Email`) are, resolve an
|
||||
operator actor. Caddy must inject these via `forward_auth` and strip inbound
|
||||
`X-Authentik-*` from clients. Result: the UI needs no token handling, and —
|
||||
critically — `EventSource` works unmodified (it cannot set Authorization
|
||||
headers).
|
||||
- Docker: node build stage in `compose/oikos/Dockerfile`; no compose or Caddy
|
||||
routing changes.
|
||||
|
||||
---
|
||||
|
||||
## Pages
|
||||
|
||||
Persistent nav + live top status strip (health dots, open-signal badge,
|
||||
pending-approval badge):
|
||||
|
||||
1. **Overview** — summary cards from `/dashboard/summary`, event-rate
|
||||
sparkline, live event ticker, top degraded entities.
|
||||
2. **Graph explorer** — d3-force over `/graph`; node color = health; filters
|
||||
by entity type / rel_type / root+depth; click → side panel with attributes
|
||||
+ blast radius; live mutation from `entity.*` / `relationship.*` /
|
||||
`health.changed` events.
|
||||
3. **Entity detail** — attributes, relations mini-graph, blast radius, uPlot
|
||||
charts (`/metrics`, `/trends`), entity-scoped events, knowledge, open
|
||||
signals, executions.
|
||||
4. **Entities table** — filter/sort by type/state/health, live badges.
|
||||
5. **Operations ledger** — executions + approvals panes with **approve/deny
|
||||
buttons** (`POST /approvals/{id}/decision`); live via `execution.*` /
|
||||
`approval.*` events; grouped by `correlation_id`. The "watch Hermes work"
|
||||
page.
|
||||
6. **Signals** — tabs by state, severity filter, **ack/resolve/mute** actions.
|
||||
7. **Live event feed** — full stream tail with filters, pause,
|
||||
correlation-id clustering (one agent action = one cluster), scroll-back via
|
||||
`GET /events`.
|
||||
8. **Agent activity** — polled `/agent-activity` timeline joined to
|
||||
executions/approvals by correlation_id.
|
||||
9. **Knowledge** — FTS search over `/knowledge/search`. **Audit** — low
|
||||
priority.
|
||||
|
||||
---
|
||||
|
||||
## Milestones
|
||||
|
||||
- **M1 (MVP):** scaffold + embed + proxy auth; Overview, Entities table, Live
|
||||
event feed over SSE. Proves the pipeline end-to-end (agent creates an
|
||||
entity → it appears live in the browser).
|
||||
- **M2:** event gap-fill (all sites above); Operations ledger with live
|
||||
approvals + decision buttons; Signals page. The payoff milestone. *Depends
|
||||
on gaps-plan bug A1 for approvals to exist at all.*
|
||||
- **M3:** graph explorer with live mutation; entity detail with charts;
|
||||
`/dashboard/summary`; `include=status`.
|
||||
- **M4:** agent activity, knowledge, audit, correlation grouping, polish.
|
||||
|
||||
## File layout
|
||||
|
||||
```
|
||||
web/
|
||||
package.json vite.config.ts
|
||||
src/
|
||||
main.ts App.svelte router.ts
|
||||
lib/api.ts lib/api-types.d.ts
|
||||
lib/stores/{events.ts, summary.ts}
|
||||
pages/{Overview,Graph,Entity,Entities,Ops,Signals,Events,Agent,Knowledge}.svelte
|
||||
dist/index.html # committed placeholder
|
||||
internal/httpapi/ui.go # go:embed + SPA fallback at /ui
|
||||
internal/httpapi/dashboard.go # GET /dashboard/summary
|
||||
internal/httpapi/server.go # mount /ui; trusted-proxy auth
|
||||
api/openapi.yaml # new paths
|
||||
internal/{scheduler/scheduler.go, mcp/server.go, actuator/actuator.go,
|
||||
httpapi/{impl,phase3}.go} # missing event emissions
|
||||
Makefile compose/oikos/Dockerfile # ui build targets, node stage
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
- M1: run `oikos api` locally, open `/ui/`, confirm Overview + Entities render
|
||||
from live API; `POST /api/v1/entities` from curl and watch it appear in the
|
||||
event feed without refresh.
|
||||
- M2: drive `request_execution` through Hermes and watch the approval appear
|
||||
on the Operations ledger, decide it from the UI, and see the execution state
|
||||
advance live.
|
||||
- Backend-only `go build ./...` succeeds without a node toolchain (placeholder
|
||||
dist).
|
||||
Reference in New Issue
Block a user