khive frontend: dashboard for swarm telemetry, KG exploration, GTD board, event stream, PR review

[ohdearquant]

Motivation

khive ships a single MCP request tool over stdio. Agents drive it; humans get no
window into what the agents are doing without scraping the DB by hand. As the
plugin set grows (kg, gtd, future comm), as agent swarms drive PRs against
the graph (#69), and as self-correction (#68) needs human-overrideable surfaces,
the lack of a frontend becomes the bottleneck.

This issue tracks the khive frontend — Next.js-based dashboard product —
positioned as the primary observability + control surface for the kg/gtd/swarm
ecosystem.

Primary use cases

1. Swarm telemetry

The use case that crystallized this issue (Ocean, 2026-05-19): when running
agent swarms (gap-analyst → expander → polisher → gap-analyst), we want to see:

• Per-agent throughput — completed task count, in-flight count, queue depth
• Handoff DAG — who assigns to whom, derived from tags=["from:X"] and depends_on chains
• Cycle progression — gap survey → expand → polish → resurvey, visualized as a stack of loops
• Bottlenecks — which agent's queue is deepest, which task type takes longest, where work piles up
• Drift signals — soft-deprecation rate per agent (from Self-correction mechanism for the kg swarm — preventing noise amplification in the gap→expand→polish loop #68), agents whose creates are getting reverted

Data source: GTD task records + (eventually) khive-events event stream (ADR-038).
Without 038 the frontend is limited to current-state queries; with 038 it
becomes a real-time telemetry surface (projections over the event log).

2. KG explorer

• Entity browser by kind/domain/status/properties
• Edge inspector — pick an entity, see its neighborhood with relation labels
• Path finder — shortest path between two concepts
• Density heatmap by domain (which areas are dense vs sparse)
• Diff view — what changed in the last N events (depends on ADR-038)

3. GTD board

• Kanban: inbox / next / waiting / active / done / cancelled
• Per-assignee swimlanes (one column per agent role + a "humans" lane)
• Task detail: full content, tags, depends_on chain, originating agent, linked notes
• Bulk actions: transition multiple, reassign, cancel

4. Gap inventory + frontier ranking visualizer

• Top-N frontier table rendered from gap_inventory.md artifacts
• Drill into each gap: source concept, score breakdown, recommended expand mode
• One-click "queue this gap for expansion" → fires assign(assignee=expander)

5. Event stream (depends on #38)

• Real-time tail of events emitted by the substrate
• Filter by actor, by kind, by record_id
• Reverse from current state to any past snapshot (depends on KG versioning KG versioning: snapshots, branches, and remotes #2)

6. PR review surface (depends on #69)

• List open agent-authored PRs against main branches
• Diff view: graph-level diff (added/removed/modified entities + edges)
• Review actions: approve, request_changes, comment
• One-click merge

7. Plugin marketplace (depends on #19)

• Browse installed packs (currently kg, gtd; eventually comm, custom)
• View pack verb catalogs + skill files inline
• Install/uninstall/upgrade packs
• Per-pack health: are its verbs being called? error rate?

Architecture

┌─────────────────────────────────────────┐
│  Next.js dashboard (this issue)         │
│  Routes:                                │
│    /swarm       — telemetry             │
│    /kg          — entity + edge browser │
│    /tasks       — GTD board             │
│    /events      — event stream tail     │
│    /prs         — agent-PR review       │
│    /gaps        — inventory + frontier  │
│    /plugins     — marketplace           │
└─────────────────────────────────────────┘
                 ↓ HTTP / WebSocket
┌─────────────────────────────────────────┐
│  khive-http (sibling crate, new)        │
│  - REST: read-side queries              │
│  - WS: event stream subscription        │
│  - Auth: API key per tenant             │
│  - Wraps `request` DSL internally       │
└─────────────────────────────────────────┘
                 ↓
┌─────────────────────────────────────────┐
│  khive-mcp + packs (unchanged)          │
│  Single source of truth for verbs       │
└─────────────────────────────────────────┘

The HTTP layer is a thin wrapper — every endpoint maps to one or a few request
DSL ops. The frontend never bypasses pack semantics.

Build phases

Phase 0 — design + scaffolding

• ADR documenting routes, data contracts, auth model
• Next.js app scaffold under crates/khive-http/web/ or products/khive-dashboard/
• Minimal khive-http crate exposing /api/request (REST wrapper over the DSL)
• One read-only route working end-to-end (e.g., /kg/entities)

Phase 1 — read-only observability

• /swarm (the use case that drove this issue)
• /kg browser + edge inspector
• /tasks board
• /gaps viewer
• All read-only — no actions yet

Phase 2 — action surfaces

• Task transitions from the UI (/tasks becomes interactive)
• Trigger gap surveys + expansions from /gaps
• Pack management from /plugins

Phase 3 — agent control plane

• Configure swarm policies (concurrency caps, confidence thresholds)
• Pause / resume agents
• View agent prompt + skill content per role

Phase 4 — event-driven UX (depends on #38)

• WebSocket subscriptions to event stream
• Real-time updates without polling
• Time-travel UI (slider to view graph state at any past timestamp)

Phase 5 — PR review + kg.github (depends on #69)

• The full PR review surface
• (Long term) public-graph forking and federated reviews

Open design questions

• Auth model. Single-tenant (local) → API key (remote) → OAuth (multi-tenant).
  Mirror khive-mcp's existing approach.
• Real-time vs polling. Polling is simpler; WS is right for events. Start
  with polling, migrate to WS when feat(marketplace): kg plugin — 4 workflow skills, researcher agent, 11-verb MCP surface #38 lands.
• Mobile. Defer. Dashboard is desktop-first.
• Embed in existing IDE plugins (Claude Code, VS Code). Long-term, not v1.
  v1 is a standalone web app.
• Storage of view preferences. Per-user, server-side, in khive itself? Or
  local browser storage? Defer until phase 2.
• Theming / branding. Match khive monospace aesthetic. Defer to design pass.

Dependencies on other issues

Phase	Hard deps	Soft deps
0	none	none
1	none	none
2	none	#19 (plugin mgmt)
3	none	#68 (self-corr.)
4	#38 (events surface)	#2 (versioning)
5	#38, #69 (agent PRs)	#2

So Phase 0-1 is unblocked today — read-only views of the existing KG and
GTD state are buildable without any other issue landing.

Out of scope (for this issue)

• The implementation of any phase — design via ADR first
• Cross-tenant federation UI (kg.github) — that's Agent-driven PR workflow on top of kg-versioning: autonomous mutators commit, branch, open PRs, merge #69's wave 4
• Mobile-specific design
• Embedded IDE plugins
• Real-time collaboration UI (multi-user cursor) — defer indefinitely

Refs

• KG versioning: snapshots, branches, and remotes #2 (kg versioning), MCP exposure: shortest_path, bfs_traverse, kg_export, kg_import #6 (mcp exposure of graph verbs), feat: plugin/marketplace for khive MCP #19 (plugin marketplace),
  feat(marketplace): kg plugin — 4 workflow skills, researcher agent, 11-verb MCP surface #38 (events surface), DX: link verb rejects entity names — 5 ingestion agents hit the same UUID-as-name error in one session #65/MCP display: default to short IDs + YYYY/MM/DD dates; --verbose for full fidelity #66 (DX), Pack design: communication + schedule (events, reminders, time-triggers) #67 (comm pack), Self-correction mechanism for the kg swarm — preventing noise amplification in the gap→expand→polish loop #68 (self-correction),
  Agent-driven PR workflow on top of kg-versioning: autonomous mutators commit, branch, open PRs, merge #69 (agent PRs)
• Triggered by the unimpl-adr-sweep show's swarm test (2026-05-19) — the
  question "can we visualize what just happened" had no answer because there's
  no frontend yet

[ohdearquant]

Server choice: Rust khive-http (axum) confirmed (2026-05-19)

Decision: HTTP server is a Rust crate in the existing workspace, not a separate
Deno server.

Stack

• khive-http — new sibling crate. axum-based HTTP server, in the same
  process as khive-mcp (or a separate binary in the same workspace that
  embeds khive-runtime).
• OpenAPI generation — utoipa annotations on every handler; spec served
  at /api/openapi.json.
• TypeScript client — openapi-typescript generates deno/src/types/api.ts
  on every CI run. Frontend imports typed clients from there; no hand-written
  fetch wrappers.
• WebSocket — axum::extract::ws for event-stream subscriptions when
  ADR-038 lands (phase 4).
• Frontend — Next.js (Deno/Node runtime per developer preference) consumes
  the generated TS types. UI tier remains TS; only the server tier is Rust.

Why not Deno server

Considered. Net loss for this codebase:

Concern	khive-http (Rust)	Deno server
Deploy surface	Single binary	Two binaries (Rust MCP + Deno)
IPC overhead	None (in-process)	JSON over the boundary
Schema reuse	Direct khive-types, khive-pack-kg	Re-derived via JSON
Type safety	Compile-time end-to-end	Runtime, via codegen
Hot-reload during UI dev	n/a (server stable, UI hot-reloads)	Faster server restarts
Greenfield velocity	Slower (Rust ceremony)	Faster

Greenfield velocity is the only meaningful Deno win, and the existing
deno/src/types subdir confirms the pattern was already "TS consumes
schemas, not produces them."

What changes in #70 phasing

• Phase 0 scaffolding explicitly creates crates/khive-http (axum + utoipa)
  alongside the Next.js app under products/khive-dashboard/ (or apps/web/).
• CI adds an openapi-types step that re-generates deno/src/types/api.ts
  on every API change and fails the build if uncommitted.
• Phase 4 (WS) explicitly uses axum's WS extractor; no separate gateway.

Risks

• Frontend devs need a Rust cargo run --bin khive-http step in their dev
  loop. Mitigation: a Justfile / Makefile target that starts both servers and
  watches both. Acceptable cost.
• API changes touch two languages. Mitigation: the OpenAPI step makes this
  mechanical — change the Rust handler, run the codegen, TS types appear in
  the next diff.

Open mechanics

• Single binary embedding both stdio MCP and HTTP, or two binaries sharing a
  workspace crate? Default to two binaries (khive-mcp stays stdio-only,
  khive-http is HTTP-only). Both consume the same khive-runtime.
• Auth: API key in Authorization: Bearer header for v1 (matches existing
  remote MCP auth pattern). OAuth defers to multi-tenant phase.

[ohdearquant]

Marking as area/design. This overlaps significantly with ADR-049 (Project Workspace Frontend) and ADR-045 (Swarm Telemetry Dashboard). When implementation begins, consolidate scope between this issue and those two ADRs rather than spawning a third design document.