55 lines
5.4 KiB
Markdown
55 lines
5.4 KiB
Markdown
# Plan 5 — Complete
|
|
|
|
**Date:** 2026-06-01
|
|
**Version:** 2.0.0-alpha.5
|
|
**Tests:** full suite green (run cleanly) — companion adds tool/registry/runtime/api unit + integration tests; no network in tests (injected `callModel`).
|
|
**Branch:** `plan5-companion-chat` (16 tasks, subagent-driven TDD).
|
|
|
|
## Scope delivered (scope B — knowledge assistant + drafting via approval)
|
|
|
|
### Agent runtime + tools
|
|
- **`lib/ai/secret.js`** — `resolveSecret('env:KEY' | 'file:/path' | raw)`. The Anthropic key is configured this way; Vaultwarden swap is a pointer change later.
|
|
- **`lib/ai/anthropic.js`** — `getAnthropicClient()` (key via resolver) + `makeCallModel({client,model})` returning a stable `callModel({system,messages,tools,onTextDelta}) -> {text,toolUses,stopReason,usage}`. Wraps `client.messages.stream()` + `finalMessage()` (verified against `@anthropic-ai/sdk@0.40.1`). `DEFAULT_MODEL=claude-sonnet-4-6`.
|
|
- **`lib/ai/agent/registry.js`** — `createRegistry()` → `{registerTool,getTool,listTools,toAnthropicTools}`. Extensible; handlers stripped from the Anthropic schema.
|
|
- **Four v1 tools** (`lib/ai/agent/tools/`): `search` (wraps `repos/search.js fts`), `read` (whitelisted table by kind), `context` (resolves the active view entity), `propose_change` (capability-gated draft → `pending_changes`, **never applies**). Wired in `tools/index.js` as `companionRegistry`.
|
|
- **`lib/ai/agent/runtime.js`** — `runTurn(...)` tool-use loop. Streams `delta`s, runs tools via the registry, builds the correct Anthropic assistant/tool_result turn structure, collects draft ids, emits one `tool` event per call (`status` done/error) + `draft` events, and stops at `maxIterations` (guard).
|
|
|
|
### API + persistence
|
|
- **Migration 007** — `conversations.space_id` (FK, indexed) + seeds the default `companion` agent (`read+suggest`, no write).
|
|
- **`conversations.findOrCreateForSpace`** — one ambient open conversation per Space+agent.
|
|
- **`lib/api/routes/companion.js`** — `GET /api/spaces/:id/companion` (history) and `POST …/companion/turn` (SSE). Persists the user message, runs `runTurn` with the **agent actor** (so drafts are suggest-tier), streams events as SSE frames, persists one assistant message with `{tool_trace, draft_ids, usage}` in metadata. `callModel` from `app.locals` in tests, real client otherwise. Mounted in `lib/api/index.js`.
|
|
|
|
### Frontend
|
|
- **`public/sse.js`** — `streamTurn()` reads an authenticated POST→SSE stream (EventSource can't send the bearer token).
|
|
- **`public/markdown.js`** — `renderMarkdown` = `DOMPurify.sanitize(marked.parse(...))` (reuses existing vendor bundles).
|
|
- **`public/components/rightrail.js`** — the chat UI (approved label-led + left/right design). Loads history, streams turns, renders tool chips + inline draft cards (approve/reject → existing `/api/pending-changes/:id/{approve,reject}`, shared with the Inbox). Safe-DOM throughout; assistant markdown only via the sanitized `html:` path.
|
|
- **`public/state.js` + `public/app.js`** — `state.spaceId`/`state.view` set in `renderView`, broadcast via a `space-active` event so the rail loads the right space on initial load, navigation, and between spaces (same-space re-renders are guarded to preserve the conversation).
|
|
|
|
## Security
|
|
|
|
- **`propose_change` never applies** — verified by review + test (target table stays empty; only a `pending_changes` row is written). Capability enforced via `canAct`; the route passes the **agent** actor (`kind:'agent'`), not the owner, so even allow-tier never auto-applies in v1.
|
|
- **Prompt-injection containment is structural** — untrusted content can at most yield a draft requiring owner approval.
|
|
- **XSS** — no unsanitized path to the DOM; user text is a text node, assistant markdown is DOMPurify-sanitized (review-confirmed).
|
|
- **Cost guardrails** — per-turn `max_tokens` + `maxIterations` loop guard.
|
|
|
|
## Deviations from the plan (all reviewed)
|
|
|
|
- Plan test snippets used `../../lib/pool.js`; real path is `lib/db/pool.js` — corrected.
|
|
- `pages` uses `body_md` (+ requires `slug`); `fts` returns `title_or_snippet` — tests adjusted.
|
|
- A plan note string didn't match its own test regex (T7) — reconciled.
|
|
- Runtime emits ONE `tool` event per call (not running+done) to match the test; the UI renders a chip per event accordingly.
|
|
- Rail initial-load wired through the `space-active` state event (cleaner than a hashchange listener).
|
|
|
|
## Open items for the user
|
|
|
|
- **Live smoke + deploy (alpha-5).** Standing rule: no production deploy without explicit OK. Needs a real `ANTHROPIC_API_KEY` in `/opt/void-server/.env` on CT 311 (the `.216` box). Snapshot CT 310 + 311 first, then `TARGET=root@192.168.1.216 ./deploy/push.sh`, verify `/health` = alpha-5, and do the manual chat smoke (ask a question → tool chips + streamed answer; "create a task" → inline draft → approve → appears in `/api/tasks` and clears from Inbox).
|
|
- **Rail accent colour** — the app's `--accent` is blackflame orange `#ff4f2e`, so the rail renders orange, not the mockup's violet. Add a `--rail-accent` if you want the purple.
|
|
- **Branch** — `plan5-companion-chat` is ready to merge to `main` once you've signed off (use finishing-a-development-branch).
|
|
|
|
## What's left after Plan 5
|
|
|
|
- **Scope C** — multi-agent personas + per-persona local (Ollama) models via `agents.model`.
|
|
- **MCP server** — re-expose `companionRegistry` to external agents.
|
|
- **Plan 6** — Sacred Valley widgets ported from Void 1.x.
|
|
- **Vaultwarden** — swap the env/file key for a vault item id.
|