Remove unrelated plan file from stale branch
This commit is contained in:
@@ -1,378 +0,0 @@
|
|||||||
# 2026-07-13 — MCP tool apps: custom in-chat renderers
|
|
||||||
|
|
||||||
**Status:** Planned
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Today, every MCP tool call renders identically — a collapsed JSON box in
|
|
||||||
`ToolCallGroup.svelte` with raw `{args, result}` dumps. The operator has to
|
|
||||||
expand and read JSON to understand what the agent did or found. This plan
|
|
||||||
introduces **tool renderers** — per-tool Svelte components that render rich,
|
|
||||||
purpose-built UI inline in the conversation, while unmatched tools stay
|
|
||||||
collapsed.
|
|
||||||
|
|
||||||
Concrete examples: `get_entity("host:hubris")` renders as a compact entity card
|
|
||||||
with type badge, health dot, and key attributes — not as 30 lines of JSON.
|
|
||||||
`get_health_summary` renders as colored health bars. `list_lxcs` renders as a
|
|
||||||
sortable table. The operator reads the chat, not raw tool output.
|
|
||||||
|
|
||||||
## UX principle: inline by default when matched
|
|
||||||
|
|
||||||
Today:
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ 🔧 3 tools: get_entity, │ ← collapsed
|
|
||||||
│ get_health_summary, ... │
|
|
||||||
│ ┌───────────────────────┐ │
|
|
||||||
│ │ {"slug":"host:hubris",│ │ ← raw JSON when expanded
|
|
||||||
│ │ "type":"host",...} │ │
|
|
||||||
│ └───────────────────────┘ │
|
|
||||||
└─────────────────────────────┘
|
|
||||||
The fleet is healthy. 42 hosts...
|
|
||||||
```
|
|
||||||
|
|
||||||
Target:
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ ● host:hubris [host] 🟢 │ ← entity card, inline
|
|
||||||
│ healthy · 2 min ago │
|
|
||||||
│ IP: 10.13.13.1 │
|
|
||||||
└─────────────────────────────┘
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ ████████████ healthy 42 │ ← health bar, inline
|
|
||||||
│ ███ degraded 3 │
|
|
||||||
│ ██ down 1 │
|
|
||||||
└─────────────────────────────┘
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ 🔧 1 tool: list_entities │ ← unmatched → still collapsed
|
|
||||||
└─────────────────────────────┘
|
|
||||||
The fleet is healthy...
|
|
||||||
```
|
|
||||||
|
|
||||||
Tools with a custom renderer appear **inline** as their own card in the message
|
|
||||||
flow, between the user bubble and the assistant's markdown text. Tools without
|
|
||||||
a renderer stay in the collapsed `ToolCallGroup`. This naturally separates
|
|
||||||
"rich, informative" tools from "utility/plumbing" tools.
|
|
||||||
|
|
||||||
### During streaming (tool in progress)
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ ◌ host:hubris │ ← skeleton while tool_result
|
|
||||||
│ [host] ⠋ loading… │ hasn't arrived yet
|
|
||||||
└─────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
Skeleton/spinner state shown while `type === 'tool_use'`; full card on `tool_result`.
|
|
||||||
The per-tool card has the same chrome as ToolCallGroup: spinner → check/X based
|
|
||||||
on completion and error state.
|
|
||||||
|
|
||||||
### Error state
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────┐
|
|
||||||
│ ✕ get_entity │
|
|
||||||
│ Entity not found: "bad" │
|
|
||||||
└─────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
### Layer 1 — Server annotation (`internal/mcp/server.go`)
|
|
||||||
|
|
||||||
Each tool handler that warrants a custom renderer adds a `__renderer` key to
|
|
||||||
its result JSON. This is a plain string field — no protocol changes, no new
|
|
||||||
content types.
|
|
||||||
|
|
||||||
```go
|
|
||||||
// Before:
|
|
||||||
return queryEntity(ctx, pool, slug), nil
|
|
||||||
|
|
||||||
// After:
|
|
||||||
r := queryEntity(ctx, pool, slug)
|
|
||||||
r["__renderer"] = "entity_card"
|
|
||||||
return jsonResult(r), nil
|
|
||||||
```
|
|
||||||
|
|
||||||
Renderer IDs by tool:
|
|
||||||
|
|
||||||
| Tool | `__renderer` | Component |
|
|
||||||
|------|-------------|-----------|
|
|
||||||
| `get_entity` | `entity_card` | EntityCard.svelte |
|
|
||||||
| `whoami` | `entity_card` | EntityCard.svelte |
|
|
||||||
| `explain` | `entity_card` | EntityCard.svelte |
|
|
||||||
| `get_health_summary` | `health_summary` | HealthSummary.svelte |
|
|
||||||
| `list_lxcs` | `lxc_list` | LXCList.svelte |
|
|
||||||
| `list_entities` | `entity_table` | EntityTable.svelte |
|
|
||||||
| `search_knowledge` | `knowledge_results` | KnowledgeResults.svelte |
|
|
||||||
| `get_entity_knowledge` | `knowledge_results` | KnowledgeResults.svelte |
|
|
||||||
| `query_metrics` | `metric_chart` | MetricChart.svelte |
|
|
||||||
| `get_blast_radius` | `blast_radius` | BlastRadius.svelte |
|
|
||||||
| `get_change_history` | `change_log` | ChangeLog.svelte |
|
|
||||||
| `get_agent_activity` | `activity_log` | (reuses ChangeLog.svelte) |
|
|
||||||
| `get_state_snapshot` | `fleet_snapshot` | FleetSnapshot.svelte |
|
|
||||||
|
|
||||||
Non-rendered tools (stay collapsed): `get_relations`, `list_my_secrets`,
|
|
||||||
`get_service_status`, `tail_log`, `get_lxc_state`, `ping_service`,
|
|
||||||
`get_patterns`, `get_skills`, `http_get`, `preflight`, `get_signal_history`,
|
|
||||||
`get_execution_status`, `get_audit_trail`, `get_trend`,
|
|
||||||
`get_event_timeline`, `upsert_knowledge`, `update_entity_attributes`,
|
|
||||||
`create_relationship`, `run`, `request_execution`.
|
|
||||||
|
|
||||||
Gated execution tools (`run`, `request_execution`) already have
|
|
||||||
`InlineApproval.svelte` rendering in Chat.svelte — they stay in the collapsed
|
|
||||||
group so the approval card remains prominent at the message level.
|
|
||||||
|
|
||||||
### Layer 2 — Renderer registry (`web/src/lib/tool-renderers.ts`)
|
|
||||||
|
|
||||||
```ts
|
|
||||||
import type { ComponentType, SvelteComponent } from 'svelte'
|
|
||||||
import type { ToolCallResult } from '$lib/stores/chat'
|
|
||||||
|
|
||||||
export interface ToolRenderer {
|
|
||||||
match: (tool: ToolCallResult) => boolean
|
|
||||||
component: ComponentType<{ tool: ToolCallResult }>
|
|
||||||
}
|
|
||||||
|
|
||||||
const registry: ToolRenderer[] = []
|
|
||||||
|
|
||||||
export function registerToolRenderer(r: ToolRenderer) {
|
|
||||||
registry.push(r)
|
|
||||||
}
|
|
||||||
|
|
||||||
export function getToolRenderer(tool: ToolCallResult): ToolRenderer | undefined {
|
|
||||||
return registry.find(r => r.match(tool))
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Match strategy: check `tool.name` against known tool names AND check
|
|
||||||
`tool.result?.__renderer` if the result is an object. The tool-name path
|
|
||||||
handles the streaming case (tool_use arrives before tool_result); the
|
|
||||||
`__renderer` path handles cases where the same tool can return different
|
|
||||||
shapes (not applicable today but future-proof).
|
|
||||||
|
|
||||||
```ts
|
|
||||||
function hasRenderer(tool: ToolCallResult, id: string): boolean {
|
|
||||||
if (tool.name === id) return true
|
|
||||||
if (tool.result && typeof tool.result === 'object' && tool.result.__renderer === id) return true
|
|
||||||
return false
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Layer 3 — Auto-registration via Vite glob (`web/src/lib/renderers/index.ts`)
|
|
||||||
|
|
||||||
Each renderer file exports a Svelte component and an `init()` call:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
// web/src/lib/renderers/entity-card.ts
|
|
||||||
import EntityCard from './EntityCard.svelte'
|
|
||||||
import { registerToolRenderer } from '$lib/tool-renderers'
|
|
||||||
|
|
||||||
export function init() {
|
|
||||||
registerToolRenderer({
|
|
||||||
match: (t) => hasRenderer(t, 'entity_card'),
|
|
||||||
component: EntityCard
|
|
||||||
})
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`web/src/lib/renderers/index.ts` imports and calls `init()` for every renderer
|
|
||||||
module. In `web/src/main.ts`, a single `import './lib/renderers'` wires
|
|
||||||
everything. Adding a new renderer means: create `Foo.svelte` + `foo.ts` with
|
|
||||||
`init()`, add the import to `index.ts`. No changes to ToolCallGroup or Chat.
|
|
||||||
|
|
||||||
### Layer 4 — ToolCallGroup split (`web/src/lib/components/ToolCallGroup.svelte`)
|
|
||||||
|
|
||||||
`ToolCallGroup` today receives `tools: ToolCallResult[]` and renders all of them.
|
|
||||||
Change: add an exported `unmatched` derived prop, and move the per-tool
|
|
||||||
rendering to Chat.svelte so inline cards appear in the message flow.
|
|
||||||
|
|
||||||
**New ToolCallGroup props:**
|
|
||||||
|
|
||||||
```ts
|
|
||||||
let { tools, unmatched, active = false }: {
|
|
||||||
tools: ToolCallResult[]
|
|
||||||
unmatched: ToolCallResult[]
|
|
||||||
active?: boolean
|
|
||||||
} = $props()
|
|
||||||
```
|
|
||||||
|
|
||||||
`tools` is the full list (for the summary: "3 tools"); `unmatched` is the
|
|
||||||
subset without renderers (for the collapsed body). The summary bar says
|
|
||||||
"1 tool" if only one unmatched tool exists, or "1 tool + 2 cards" to
|
|
||||||
acknowledge the inline ones.
|
|
||||||
|
|
||||||
**Chat.svelte changes (lines 114-133):**
|
|
||||||
|
|
||||||
```svelte
|
|
||||||
{:else}
|
|
||||||
<div class="flex w-full flex-col gap-2">
|
|
||||||
<!-- Inline tool cards (matched renderers) -->
|
|
||||||
{#each msg.tools as tool (tool.id)}
|
|
||||||
{@const renderer = getToolRenderer(tool)}
|
|
||||||
{#if renderer}
|
|
||||||
<renderer.component {tool} />
|
|
||||||
{/if}
|
|
||||||
{/each}
|
|
||||||
|
|
||||||
<!-- Unmatched tools → collapsed group -->
|
|
||||||
<ToolCallGroup
|
|
||||||
tools={msg.tools}
|
|
||||||
unmatched={msg.tools.filter(t => !getToolRenderer(t))}
|
|
||||||
active={$streaming && i === $messages.length - 1}
|
|
||||||
/>
|
|
||||||
|
|
||||||
<!-- Text + approvals (unchanged) -->
|
|
||||||
...
|
|
||||||
</div>
|
|
||||||
{/if}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Layer 5 — Renderer component contract
|
|
||||||
|
|
||||||
Every renderer component receives a single `tool: ToolCallResult` prop.
|
|
||||||
|
|
||||||
Component responsibilities:
|
|
||||||
- **Loading state** (`tool.type === 'tool_use'`): render a skeleton/spinner with
|
|
||||||
the tool name and relevant args
|
|
||||||
- **Success state** (`tool.type === 'tool_result' && !tool.error`): render the
|
|
||||||
rich card
|
|
||||||
- **Error state** (`tool.type === 'tool_result' && tool.error`): render error
|
|
||||||
with a compact message
|
|
||||||
- **No result** (tool completed but result is null/empty): render a minimal card
|
|
||||||
with just the tool name + checkmark
|
|
||||||
|
|
||||||
Self-contained card: a border, padding, and the same size feel as the
|
|
||||||
existing approval cards. Each card is independent — no shared state between
|
|
||||||
renderers.
|
|
||||||
|
|
||||||
## New components
|
|
||||||
|
|
||||||
| Component | Matches | Visual |
|
|
||||||
|-----------|---------|--------|
|
|
||||||
| `EntityCard` | `get_entity`, `whoami`, `explain` | Slug + type badge + health dot + state + key attrs (IP, version) + "last checked" relative time |
|
|
||||||
| `HealthSummary` | `get_health_summary` | Horizontal stacked bar: green=healthy, amber=degraded, red=down, with counts |
|
|
||||||
| `LXCList` | `list_lxcs` | Compact table: name, host, IP, health dot, status |
|
|
||||||
| `EntityTable` | `list_entities` | Sortable table (reuses EntityTable.svelte from KB page) |
|
|
||||||
| `KnowledgeResults` | `search_knowledge`, `get_entity_knowledge` | Result cards: title + excerpt + tags |
|
|
||||||
| `MetricChart` | `query_metrics` | Sparkline or small bar chart of bucketed values |
|
|
||||||
| `BlastRadius` | `get_blast_radius` | Entity list grouped by distance (direct → 1 hop → 2 hops) |
|
|
||||||
| `ChangeLog` | `get_change_history`, `get_agent_activity` | Timeline of recent entries with timestamps |
|
|
||||||
| `FleetSnapshot` | `get_state_snapshot` | Summary grid: healthy/degraded/down counts + drift count |
|
|
||||||
|
|
||||||
Some already exist partially: `EntityTable.svelte` and `EntityGraph` are used
|
|
||||||
on the KB page — the renderer can wrap or reuse them.
|
|
||||||
|
|
||||||
## File changes
|
|
||||||
|
|
||||||
| File | Change |
|
|
||||||
|------|--------|
|
|
||||||
| `internal/mcp/server.go` | Add `__renderer` to result JSON for ~12 tools |
|
|
||||||
| `web/src/lib/tool-renderers.ts` | New — registry + match helpers |
|
|
||||||
| `web/src/lib/renderers/index.ts` | New — imports all renderer init modules |
|
|
||||||
| `web/src/lib/renderers/entity-card.ts` | New — register `EntityCard` |
|
|
||||||
| `web/src/lib/renderers/EntityCard.svelte` | New — entity card component |
|
|
||||||
| `web/src/lib/renderers/health-summary.ts` | New — register `HealthSummary` |
|
|
||||||
| `web/src/lib/renderers/HealthSummary.svelte` | New — health bar component |
|
|
||||||
| `web/src/lib/renderers/lxc-list.ts` | New — register `LXCList` |
|
|
||||||
| `web/src/lib/renderers/LXCList.svelte` | New — LXC table component |
|
|
||||||
| `web/src/lib/renderers/knowledge-results.ts` | New — register `KnowledgeResults` |
|
|
||||||
| `web/src/lib/renderers/KnowledgeResults.svelte` | New — search results component |
|
|
||||||
| `web/src/lib/renderers/metric-chart.ts` | New — register `MetricChart` |
|
|
||||||
| `web/src/lib/renderers/MetricChart.svelte` | New — sparkline component |
|
|
||||||
| `web/src/lib/renderers/blast-radius.ts` | New — register `BlastRadius` |
|
|
||||||
| `web/src/lib/renderers/BlastRadius.svelte` | New — blast radius component |
|
|
||||||
| `web/src/lib/renderers/change-log.ts` | New — register `ChangeLog` |
|
|
||||||
| `web/src/lib/renderers/ChangeLog.svelte` | New — timeline component |
|
|
||||||
| `web/src/lib/renderers/fleet-snapshot.ts` | New — register `FleetSnapshot` |
|
|
||||||
| `web/src/lib/renderers/FleetSnapshot.svelte` | New — snapshot grid component |
|
|
||||||
| `web/src/lib/components/ToolCallGroup.svelte` | Add `unmatched` prop; render only unmatched tools in body; adjust summary text |
|
|
||||||
| `web/src/pages/Chat.svelte` | Filter matched tools to inline cards; pass unmatched to ToolCallGroup |
|
|
||||||
| `web/src/main.ts` | Add `import './lib/renderers'` |
|
|
||||||
|
|
||||||
## Phases
|
|
||||||
|
|
||||||
### Phase 1 — Infra + first renderer
|
|
||||||
|
|
||||||
1. Create `tool-renderers.ts` registry
|
|
||||||
2. Create renderer directory + index
|
|
||||||
3. Modify `ToolCallGroup.svelte` to accept `unmatched` prop
|
|
||||||
4. Modify `Chat.svelte` to dispatch inline cards
|
|
||||||
5. Add `__renderer` to `get_entity`, `whoami`, `explain` in server.go
|
|
||||||
6. Create `EntityCard.svelte` — the flagship renderer
|
|
||||||
7. Test: ask Nomos "tell me about host:hubris"
|
|
||||||
8. Verify: entity card renders inline, unrelated tools stay collapsed
|
|
||||||
|
|
||||||
### Phase 2 — Remaining renderers
|
|
||||||
|
|
||||||
Add in priority order:
|
|
||||||
1. `HealthSummary` + `get_health_summary` annotation
|
|
||||||
2. `LXCList` + `list_lxcs` annotation
|
|
||||||
3. `KnowledgeResults` + `search_knowledge` / `get_entity_knowledge` annotation
|
|
||||||
4. `BlastRadius` + `get_blast_radius` annotation
|
|
||||||
5. `EntityTable` + `list_entities` annotation
|
|
||||||
6. `ChangeLog` + `get_change_history` / `get_agent_activity` annotation
|
|
||||||
7. `FleetSnapshot` + `get_state_snapshot` annotation
|
|
||||||
8. `MetricChart` + `query_metrics` annotation
|
|
||||||
|
|
||||||
### Phase 3 — Polish
|
|
||||||
|
|
||||||
1. Smooth streaming: renderer shows skeleton on `tool_use`, renders on `tool_result`
|
|
||||||
2. Error states: renderer shows compact error card (not raw JSON)
|
|
||||||
3. Mobile: renderers stack full-width on narrow viewports
|
|
||||||
4. Accessibility: renderer cards have proper ARIA labels
|
|
||||||
|
|
||||||
## Risks / open questions
|
|
||||||
|
|
||||||
1. **Tool name vs `__renderer` mismatch**: If the server adds `__renderer` but
|
|
||||||
the frontend hasn't deployed yet, the field is silently ignored and the
|
|
||||||
tool falls back to the collapsed group. No breakage. Vice versa (frontend
|
|
||||||
expects a renderer that the server doesn't emit): match falls through to
|
|
||||||
collapsed group. Graceful degradation in both directions.
|
|
||||||
|
|
||||||
2. **Streaming jank**: During a turn, tool_use events arrive before tool_result.
|
|
||||||
The renderer sees `type: 'tool_use'` initially (shows skeleton), then Svelte
|
|
||||||
reactivity updates when the store merges `tool_result`. The card transitions
|
|
||||||
from skeleton → rich. This is the same model as ToolCallGroup's
|
|
||||||
spinner → check transition. No new complexity.
|
|
||||||
|
|
||||||
3. **Multiple tools of same type**: A single agent turn might call `get_entity`
|
|
||||||
twice. Each gets its own inline card — natural, no dedup needed.
|
|
||||||
|
|
||||||
4. **Card explosion**: If the agent calls 15 tools in one turn and 12 of them
|
|
||||||
match renderers, the chat gets 12 inline cards before any text. This could
|
|
||||||
be noisy if the agent is chatty. Mitigations: (a) renderers are compact
|
|
||||||
(3-4 lines), (b) the collapsed group still exists for unmatched tools,
|
|
||||||
(c) we can add a per-turn limit later ("show top 3, collapse rest") but
|
|
||||||
start simple. The agent in practice calls 3-6 tools per turn; 12 is
|
|
||||||
an edge case.
|
|
||||||
|
|
||||||
5. **Security**: Renderers receive tool result data that already passed through
|
|
||||||
the SSE stream (authenticated). No new attack surface. Renderers render
|
|
||||||
data, not HTML — Svelte's auto-escaping handles XSS. No `{@html}` in any
|
|
||||||
renderer unless explicitly sanitized.
|
|
||||||
|
|
||||||
6. **Persistence**: Tool results are already persisted in the DB (via Nomos's
|
|
||||||
incremental message persistence). On session reload,
|
|
||||||
`mergeToolCalls()` → `toChatMessages()` reconstructs `ToolCallResult[]`
|
|
||||||
including `result`. The `__renderer` field survives the roundtrip because
|
|
||||||
it's part of the result JSON, which is stored as-is. No schema change.
|
|
||||||
**Verified**: `cmd/nomos/continue.go` marshals tool results to JSONB
|
|
||||||
without filtering fields — `__renderer` passes through transparently.
|
|
||||||
|
|
||||||
7. **The gated-execution tools** (`run`, `request_execution`): These already
|
|
||||||
surface as `InlineApproval` cards at the message level via
|
|
||||||
`extractApprovals()` in `chat.ts`. They deliberately stay in the collapsed
|
|
||||||
group — don't add a renderer for them. The approval card is the rich UI.
|
|
||||||
|
|
||||||
## Cost / effort
|
|
||||||
|
|
||||||
| Area | Estimate |
|
|
||||||
|------|----------|
|
|
||||||
| Server annotations | ~20 lines across ~12 tools |
|
|
||||||
| Registry + infra | ~50 lines (tool-renderers.ts + Chat.svelte + ToolCallGroup changes) |
|
|
||||||
| First renderer (EntityCard) | ~60 lines |
|
|
||||||
| Remaining 8 renderers | ~40-80 lines each |
|
|
||||||
| **Total** | ~500 lines, 1-2 sessions |
|
|
||||||
Reference in New Issue
Block a user