Void-Homelab/docs/superpowers/plans/2026-06-01-void-v2-plan5-companion-chat.md

# Companion Chat Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the Void 2.0 right-rail companion chat — an always-visible, per-Space AI assistant that answers questions over the Void's knowledge and proposes changes through the existing `pending_changes` approval chain.

**Architecture:** A lean agent runtime built directly on the Anthropic SDK (no Mastra) drives a tool-use loop over a small, shared, extensible tool registry (`search`, `read`, `context`, `propose_change`). An SSE endpoint streams tokens + tool-activity events to a rewritten `rightrail.js`. One ambient `conversation` per Space; drafts are `pending_changes` rows rendered inline in chat and in the Inbox.

**Tech Stack:** Node 22 / Express 5 (ESM), `@anthropic-ai/sdk`, Postgres 16 + pgvector, vitest + supertest, vanilla-JS SPA with the safe-DOM helpers in `public/dom.js`.

**Spec:** `docs/superpowers/specs/2026-06-01-void-v2-plan5-companion-chat-design.md`

---

## Conventions (read before starting)

- **ESM only.** All `import`/`export`, `"type":"module"` is set.
- **Repos** live in `lib/db/repos/*.js`, use `import { pool } from '../pool.js'`, return rows. Mutations emit audit via `recordAudit(actor, action, type, id, before, after)` from `./audit_stub.js`.
- **Routes** use `Router()`, `validate({ body|query|params: zodSchema })` (parsed body lands on `req.body`, query on `req.validatedQuery`), and `asyncWrap` from `../errors.js`. `req.actor` is set by `agentOrOwner`: owner = `{ kind:'user', id:null }`, agent = `{ kind:'agent', id, capabilities, scopes }`.
- **Capability:** `canAct(actor, action, entity_type)` → `'allow' | 'suggest' | 'deny'` (`lib/auth/capability.js`).
- **Tests** live under `tests/` mirroring `lib/` paths. Run with `npm test` (vitest, `fileParallelism:false`). DB tests use `resetDb()` from `tests/helpers/db.js` + `migrateUp()` from `lib/db/migrate.js`. The owner token in tests is `process.env.OWNER_TOKEN = 'test-token'`.
- **Commit after every task** (the repo commits directly to `main`, no remote). End commit messages with the Co-Authored-By trailer used elsewhere in this repo.

---

## File structure

**Create:**
- `lib/db/migrations/007_companion.sql` — `conversations.space_id` + index + seed default companion agent
- `lib/ai/secret.js` — `resolveSecret('env:KEY' | 'file:/path' | raw)`
- `lib/ai/anthropic.js` — Anthropic client factory + `makeCallModel({ client, model })`
- `lib/ai/agent/registry.js` — tool registry (`registerTool`, `getTool`, `listTools`, `toAnthropicTools`)
- `lib/ai/agent/tools/search.js`, `read.js`, `context.js`, `propose_change.js`
- `lib/ai/agent/tools/index.js` — registers all four tools, exports the registry
- `lib/ai/agent/runtime.js` — `runTurn(...)` tool-use loop
- `lib/api/routes/companion.js` — `GET /api/spaces/:space_id/companion`, `POST …/companion/turn` (SSE)
- `public/sse.js` — authenticated POST→SSE reader for the browser
- Tests mirroring each of the above under `tests/`

**Modify:**
- `lib/db/repos/conversations.js` — add `findOrCreateForSpace(...)`
- `lib/api/index.js` — mount the companion router
- `public/components/rightrail.js` — replace the stub with the chat UI
- `public/style.css` — rail/turn/chip/draft-card styles
- `package.json` / `CHANGELOG.md` — dependency + version bump (final task)

---

## Task 1: Add the Anthropic SDK dependency

**Files:**
- Modify: `package.json`

- [ ] **Step 1: Install the SDK**

Run:
```bash
cd /project/src/void-v2 && npm install @anthropic-ai/sdk@^0.40.0
```
Expected: `@anthropic-ai/sdk` appears in `dependencies`, `npm install` exits 0.

- [ ] **Step 2: Verify it imports**

Run:
```bash
node -e "import('@anthropic-ai/sdk').then(m => console.log(typeof m.default))"
```
Expected: prints `function` (the `Anthropic` class constructor).

- [ ] **Step 3: Commit**

```bash
git add package.json package-lock.json
git commit -m "chore(deps): add @anthropic-ai/sdk for companion runtime

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 2: Secret resolver (`lib/ai/secret.js`)

The companion's API key is configured as a `vault_path`-style string. v1 supports `env:` and `file:` (the Vaultwarden swap is deferred — see the spec).

**Files:**
- Create: `lib/ai/secret.js`
- Test: `tests/ai/secret.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/secret.test.js
import { describe, it, expect, beforeEach } from 'vitest';
import { writeFileSync, mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { resolveSecret } from '../../lib/ai/secret.js';

describe('resolveSecret', () => {
  beforeEach(() => { delete process.env.__SECRET_TEST; });

  it('resolves env: specs', () => {
    process.env.__SECRET_TEST = 'sk-from-env';
    expect(resolveSecret('env:__SECRET_TEST')).toBe('sk-from-env');
  });

  it('resolves file: specs (trimmed)', () => {
    const dir = mkdtempSync(join(tmpdir(), 'sec-'));
    const f = join(dir, 'key');
    writeFileSync(f, 'sk-from-file\n');
    expect(resolveSecret('file:' + f)).toBe('sk-from-file');
  });

  it('returns a raw value unchanged', () => {
    expect(resolveSecret('sk-raw')).toBe('sk-raw');
  });

  it('returns null for empty/missing', () => {
    expect(resolveSecret('')).toBeNull();
    expect(resolveSecret('env:__SECRET_TEST')).toBeNull();
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/secret.test.js`
Expected: FAIL — `resolveSecret is not a function` / module not found.

- [ ] **Step 3: Implement `lib/ai/secret.js`**

```javascript
import { readFileSync } from 'node:fs';

// Resolve a vault_path-style secret reference. v1 supports:
//   env:NAME   -> process.env.NAME
//   file:/path -> file contents (trimmed)
//   <raw>      -> returned as-is
// Vaultwarden item-id resolution is a future swap (see spec).
export function resolveSecret(spec) {
  if (!spec) return null;
  if (spec.startsWith('env:')) {
    return process.env[spec.slice(4)] ?? null;
  }
  if (spec.startsWith('file:')) {
    try { return readFileSync(spec.slice(5), 'utf8').trim(); }
    catch { return null; }
  }
  return spec;
}
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/secret.test.js`
Expected: PASS (4 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/ai/secret.js tests/ai/secret.test.js
git commit -m "feat(ai): vault_path secret resolver (env:/file:)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 3: Migration 007 — `conversations.space_id` + seed companion agent

`conversations` has no Space linkage and no agent is seeded. Add a nullable `space_id` FK + lookup index, and seed one default companion agent (`slug='companion'`, `kind='claude'`, default capabilities `read+suggest`, no write).

**Files:**
- Create: `lib/db/migrations/007_companion.sql`
- Test: `tests/db/migration_007.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/db/migration_007.test.js
import { describe, it, expect, beforeAll } from 'vitest';
import { pool } from '../../lib/pool.js';
import { resetDb } from '../helpers/db.js';
import { migrateUp } from '../../lib/db/migrate.js';

beforeAll(async () => { await resetDb(); await migrateUp(); });

describe('migration 007', () => {
  it('adds conversations.space_id column', async () => {
    const { rows } = await pool.query(
      `SELECT column_name FROM information_schema.columns
       WHERE table_name='conversations' AND column_name='space_id'`
    );
    expect(rows).toHaveLength(1);
  });

  it('seeds a default companion agent', async () => {
    const { rows } = await pool.query(`SELECT slug, kind, capabilities FROM agents WHERE slug='companion'`);
    expect(rows).toHaveLength(1);
    expect(rows[0].kind).toBe('claude');
    expect(rows[0].capabilities).toMatchObject({ read: true, suggest: true, write: false });
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/db/migration_007.test.js`
Expected: FAIL — column missing / no `companion` agent row.

- [ ] **Step 3: Write the migration**

```sql
-- lib/db/migrations/007_companion.sql
-- Plan 5: per-Space ambient companion conversation + default companion agent.

ALTER TABLE conversations
  ADD COLUMN space_id uuid REFERENCES spaces(id) ON DELETE CASCADE;

CREATE INDEX idx_conversations_space ON conversations(space_id, started_at DESC);

INSERT INTO agents (slug, name, kind, model, capabilities)
VALUES (
  'companion', 'Companion', 'claude', NULL,
  '{"read":true,"suggest":true,"write":false}'::jsonb
)
ON CONFLICT (slug) DO NOTHING;
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/db/migration_007.test.js`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/db/migrations/007_companion.sql tests/db/migration_007.test.js
git commit -m "feat(db): migration 007 — conversations.space_id + seed companion agent

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 4: `conversations.findOrCreateForSpace`

One ambient conversation per Space, owned by a given agent. Reuse on subsequent turns.

**Files:**
- Modify: `lib/db/repos/conversations.js`
- Test: `tests/db/conversations_companion.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/db/conversations_companion.test.js
import { describe, it, expect, beforeAll } from 'vitest';
import { pool } from '../../lib/pool.js';
import { resetDb } from '../helpers/db.js';
import { migrateUp } from '../../lib/db/migrate.js';
import * as conversations from '../../lib/db/repos/conversations.js';

const ACTOR = { kind: 'user', id: null };
let spaceId, agentId;

beforeAll(async () => {
  await resetDb(); await migrateUp();
  ({ rows: [{ id: spaceId }] } = await pool.query(
    `INSERT INTO spaces(slug,name) VALUES('s','S') RETURNING id`));
  ({ rows: [{ id: agentId }] } = await pool.query(
    `SELECT id FROM agents WHERE slug='companion'`));
});

describe('findOrCreateForSpace', () => {
  it('creates once then returns the same row', async () => {
    const a = await conversations.findOrCreateForSpace(spaceId, agentId, ACTOR);
    const b = await conversations.findOrCreateForSpace(spaceId, agentId, ACTOR);
    expect(a.id).toBe(b.id);
    expect(a.space_id).toBe(spaceId);
    expect(a.agent_id).toBe(agentId);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/db/conversations_companion.test.js`
Expected: FAIL — `findOrCreateForSpace is not a function`.

- [ ] **Step 3: Implement (append to `lib/db/repos/conversations.js`)**

```javascript
export async function findOrCreateForSpace(space_id, agent_id, actor) {
  const { rows: [existing] } = await pool.query(
    `SELECT * FROM conversations
     WHERE space_id=$1 AND agent_id=$2 AND status='open'
     ORDER BY started_at DESC LIMIT 1`,
    [space_id, agent_id]
  );
  if (existing) return existing;
  const { rows: [r] } = await pool.query(
    `INSERT INTO conversations(title, space_id, agent_id, metadata)
     VALUES($1,$2,$3,$4) RETURNING *`,
    ['Companion', space_id, agent_id, {}]
  );
  await recordAudit(actor, 'create', 'conversation', r.id, null, r);
  return r;
}
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/db/conversations_companion.test.js`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add lib/db/repos/conversations.js tests/db/conversations_companion.test.js
git commit -m "feat(db): conversations.findOrCreateForSpace for the ambient companion

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 5: Tool registry (`lib/ai/agent/registry.js`)

A registry of `{ name, description, input_schema, handler }`. The runtime reads it now; a future MCP server re-exposes the same defs. **Extensible by design** (registering a new tool needs no runtime change — see spec §7).

**Files:**
- Create: `lib/ai/agent/registry.js`
- Test: `tests/ai/agent/registry.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/agent/registry.test.js
import { describe, it, expect } from 'vitest';
import { createRegistry } from '../../../lib/ai/agent/registry.js';

describe('tool registry', () => {
  const def = {
    name: 'echo',
    description: 'echo back',
    input_schema: { type: 'object', properties: { x: { type: 'string' } }, required: ['x'] },
    handler: async ({ x }) => ({ ok: true, x })
  };

  it('registers and retrieves a tool', () => {
    const r = createRegistry();
    r.registerTool(def);
    expect(r.getTool('echo')).toBe(def);
    expect(r.listTools().map(t => t.name)).toEqual(['echo']);
  });

  it('rejects duplicate names', () => {
    const r = createRegistry();
    r.registerTool(def);
    expect(() => r.registerTool(def)).toThrow(/already registered/);
  });

  it('serialises to the Anthropic tools shape (no handler leak)', () => {
    const r = createRegistry();
    r.registerTool(def);
    expect(r.toAnthropicTools()).toEqual([
      { name: 'echo', description: 'echo back', input_schema: def.input_schema }
    ]);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/agent/registry.test.js`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement `lib/ai/agent/registry.js`**

```javascript
export function createRegistry() {
  const tools = new Map();
  return {
    registerTool(def) {
      if (!def?.name) throw new Error('tool def needs a name');
      if (tools.has(def.name)) throw new Error(`tool "${def.name}" already registered`);
      tools.set(def.name, def);
    },
    getTool(name) { return tools.get(name); },
    listTools() { return [...tools.values()]; },
    // Anthropic tool-use schema — handlers are intentionally stripped.
    toAnthropicTools() {
      return [...tools.values()].map(({ name, description, input_schema }) =>
        ({ name, description, input_schema }));
    }
  };
}
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/agent/registry.test.js`
Expected: PASS (3 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/ai/agent/registry.js tests/ai/agent/registry.test.js
git commit -m "feat(ai): extensible agent tool registry

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 6: `search` and `read` tools

Read-only grounding tools. `search` wraps the existing FTS repo (Space-scoped); `read` fetches an entity by type+id. Tool `ctx` = `{ agent, space_id, view, actor }`.

**Files:**
- Create: `lib/ai/agent/tools/search.js`, `lib/ai/agent/tools/read.js`
- Test: `tests/ai/agent/tools/read_search.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/agent/tools/read_search.test.js
import { describe, it, expect, beforeAll } from 'vitest';
import { pool } from '../../../../lib/pool.js';
import { resetDb } from '../../../helpers/db.js';
import { migrateUp } from '../../../../lib/db/migrate.js';
import { searchTool } from '../../../../lib/ai/agent/tools/search.js';
import { readTool } from '../../../../lib/ai/agent/tools/read.js';

let spaceId, pageId;
beforeAll(async () => {
  await resetDb(); await migrateUp();
  ({ rows: [{ id: spaceId }] } = await pool.query(
    `INSERT INTO spaces(slug,name) VALUES('s','S') RETURNING id`));
  ({ rows: [{ id: pageId }] } = await pool.query(
    `INSERT INTO pages(space_id,title,body) VALUES($1,'Telemetry export','export CSV via phone') RETURNING id`,
    [spaceId]));
});

describe('search tool', () => {
  it('returns FTS hits scoped to the space', async () => {
    const ctx = { space_id: spaceId, actor: { kind: 'user', id: null } };
    const out = await searchTool.handler({ q: 'telemetry' }, ctx);
    expect(Array.isArray(out.results)).toBe(true);
    expect(out.results.some(r => r.title?.includes('Telemetry'))).toBe(true);
  });
});

describe('read tool', () => {
  it('fetches a page by id', async () => {
    const out = await readTool.handler({ kind: 'page', id: pageId }, { space_id: spaceId });
    expect(out.title).toBe('Telemetry export');
  });
  it('reports not-found cleanly', async () => {
    const out = await readTool.handler(
      { kind: 'page', id: '00000000-0000-0000-0000-000000000000' }, { space_id: spaceId });
    expect(out.error).toMatch(/not found/i);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/agent/tools/read_search.test.js`
Expected: FAIL — modules not found.

- [ ] **Step 3: Implement `lib/ai/agent/tools/search.js`**

```javascript
import * as searchRepo from '../../../db/repos/search.js';

export const searchTool = {
  name: 'search',
  description: 'Full-text search across pages, refs, source docs and messages in the current Space. Use to find information before answering.',
  input_schema: {
    type: 'object',
    properties: {
      q: { type: 'string', description: 'search query' },
      kinds: {
        type: 'array',
        items: { type: 'string', enum: ['page', 'ref', 'source_doc', 'message'] },
        description: 'optional filter of result kinds'
      }
    },
    required: ['q']
  },
  async handler({ q, kinds }, ctx) {
    const results = await searchRepo.fts({
      q,
      space_id: ctx.space_id ?? null,
      kinds: kinds?.length ? kinds : null,
      limit: 8,
      offset: 0
    });
    return { results };
  }
};
```

- [ ] **Step 4: Implement `lib/ai/agent/tools/read.js`**

```javascript
import { pool } from '../../../pool.js';

const TABLE = { page: 'pages', ref: 'refs', task: 'tasks', conversation: 'conversations' };

export const readTool = {
  name: 'read',
  description: 'Read a single entity (page, ref, task, conversation) by id for grounding.',
  input_schema: {
    type: 'object',
    properties: {
      kind: { type: 'string', enum: ['page', 'ref', 'task', 'conversation'] },
      id: { type: 'string', description: 'uuid of the entity' }
    },
    required: ['kind', 'id']
  },
  async handler({ kind, id }, _ctx) {
    const table = TABLE[kind];
    if (!table) return { error: `unknown kind "${kind}"` };
    const { rows: [row] } = await pool.query(`SELECT * FROM ${table} WHERE id=$1`, [id]);
    if (!row) return { error: `${kind} ${id} not found` };
    return row;
  }
};
```

- [ ] **Step 5: Run it to confirm it passes**

Run: `npx vitest run tests/ai/agent/tools/read_search.test.js`
Expected: PASS (3 tests).

- [ ] **Step 6: Commit**

```bash
git add lib/ai/agent/tools/search.js lib/ai/agent/tools/read.js tests/ai/agent/tools/read_search.test.js
git commit -m "feat(ai): search + read grounding tools

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 7: `context` tool

Resolves the current view's entity so the agent knows what the owner is looking at.

**Files:**
- Create: `lib/ai/agent/tools/context.js`
- Test: `tests/ai/agent/tools/context.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/agent/tools/context.test.js
import { describe, it, expect, beforeAll } from 'vitest';
import { pool } from '../../../../lib/pool.js';
import { resetDb } from '../../../helpers/db.js';
import { migrateUp } from '../../../../lib/db/migrate.js';
import { contextTool } from '../../../../lib/ai/agent/tools/context.js';

let spaceId, taskId;
beforeAll(async () => {
  await resetDb(); await migrateUp();
  ({ rows: [{ id: spaceId }] } = await pool.query(
    `INSERT INTO spaces(slug,name) VALUES('s','S') RETURNING id`));
  ({ rows: [{ id: taskId }] } = await pool.query(
    `INSERT INTO tasks(space_id,title) VALUES($1,'Wire telemetry') RETURNING id`, [spaceId]));
});

describe('context tool', () => {
  it('summarises the current view entity', async () => {
    const out = await contextTool.handler({}, { space_id: spaceId, view: { entityType: 'task', entityId: taskId } });
    expect(out.entityType).toBe('task');
    expect(out.title).toBe('Wire telemetry');
  });
  it('handles no active view', async () => {
    const out = await contextTool.handler({}, { space_id: spaceId, view: null });
    expect(out.note).toMatch(/no specific entity/i);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/agent/tools/context.test.js`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement `lib/ai/agent/tools/context.js`**

```javascript
import { pool } from '../../../pool.js';

const TABLE = { page: 'pages', ref: 'refs', task: 'tasks', project: 'projects', space: 'spaces' };

export const contextTool = {
  name: 'context',
  description: "Resolve what the owner is currently looking at (the active view). Call this first to ground your answer in the right entity.",
  input_schema: { type: 'object', properties: {} },
  async handler(_args, ctx) {
    const view = ctx.view;
    if (!view?.entityType || !view?.entityId) {
      return { note: 'The owner is not on a specific entity; only the Space context is available.', space_id: ctx.space_id };
    }
    const table = TABLE[view.entityType];
    if (!table) return { entityType: view.entityType, entityId: view.entityId, note: 'unrecognised entity type' };
    const { rows: [row] } = await pool.query(`SELECT * FROM ${table} WHERE id=$1`, [view.entityId]);
    if (!row) return { entityType: view.entityType, entityId: view.entityId, error: 'not found' };
    return { entityType: view.entityType, ...row };
  }
};
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/agent/tools/context.test.js`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/ai/agent/tools/context.js tests/ai/agent/tools/context.test.js
git commit -m "feat(ai): context tool — resolve the active view entity

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 8: `propose_change` tool (the action seam)

Writes one `pending_changes` row — **never** applies. Enforces the agent's capability tier via `canAct`; a denied agent gets a clean refusal.

**Files:**
- Create: `lib/ai/agent/tools/propose_change.js`
- Test: `tests/ai/agent/tools/propose_change.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/agent/tools/propose_change.test.js
import { describe, it, expect, beforeAll } from 'vitest';
import { pool } from '../../../../lib/pool.js';
import { resetDb } from '../../../helpers/db.js';
import { migrateUp } from '../../../../lib/db/migrate.js';
import { proposeChangeTool } from '../../../../lib/ai/agent/tools/propose_change.js';

let spaceId, agentId;
beforeAll(async () => {
  await resetDb(); await migrateUp();
  ({ rows: [{ id: spaceId }] } = await pool.query(
    `INSERT INTO spaces(slug,name) VALUES('s','S') RETURNING id`));
  ({ rows: [{ id: agentId }] } = await pool.query(`SELECT id FROM agents WHERE slug='companion'`));
});

const suggestAgent = (id) => ({ kind: 'agent', id, capabilities: { read: true, suggest: true, write: false }, scopes: {} });

describe('propose_change tool', () => {
  it('writes a pending_changes row and never applies', async () => {
    const ctx = { agent: suggestAgent(agentId), space_id: spaceId };
    const out = await proposeChangeTool.handler(
      { entity_type: 'task', action: 'create', payload: { space_id: spaceId, title: 'Validate CSV' }, reason: 'tracking' },
      ctx
    );
    expect(out.pending_change_id).toBeTruthy();
    expect(out.applied).toBe(false);

    const { rows } = await pool.query(`SELECT * FROM pending_changes WHERE id=$1`, [out.pending_change_id]);
    expect(rows[0].status).toBe('pending');
    expect(rows[0].agent_id).toBe(agentId);

    const { rows: tasks } = await pool.query(`SELECT * FROM tasks WHERE title='Validate CSV'`);
    expect(tasks).toHaveLength(0); // not applied
  });

  it('refuses when the agent cannot even suggest', async () => {
    const denied = { kind: 'agent', id: agentId, capabilities: { read: true, suggest: false, write: false }, scopes: {} };
    const out = await proposeChangeTool.handler(
      { entity_type: 'task', action: 'create', payload: { title: 'x' } },
      { agent: denied, space_id: spaceId }
    );
    expect(out.error).toMatch(/not permitted/i);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/agent/tools/propose_change.test.js`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement `lib/ai/agent/tools/propose_change.js`**

```javascript
import { canAct } from '../../../auth/capability.js';
import * as pendingChanges from '../../../db/repos/pending_changes.js';

const ENTITY_TYPES = ['task', 'page', 'project', 'ref', 'resource', 'source_doc'];
const ACTIONS = ['create', 'update', 'delete'];

export const proposeChangeTool = {
  name: 'propose_change',
  description: 'Propose a change to the Void. This NEVER applies directly — it creates a draft the owner must approve. Use for creating/updating/deleting tasks, pages, projects, refs, resources.',
  input_schema: {
    type: 'object',
    properties: {
      entity_type: { type: 'string', enum: ENTITY_TYPES },
      action: { type: 'string', enum: ACTIONS },
      entity_id: { type: 'string', description: 'uuid; required for update/delete' },
      payload: { type: 'object', description: 'fields for the change' },
      reason: { type: 'string', description: 'one-line rationale shown to the owner' }
    },
    required: ['entity_type', 'action', 'payload']
  },
  async handler({ entity_type, action, entity_id, payload, reason }, ctx) {
    const tier = canAct(ctx.agent, action, entity_type);
    if (tier === 'deny') {
      return { error: `not permitted to ${action} ${entity_type}` };
    }
    // v1: drafting always routes through approval, even for allow-tier agents.
    const change = await pendingChanges.create({
      agent_id: ctx.agent.id,
      entity_type,
      entity_id: entity_id ?? null,
      action,
      payload: payload ?? {},
      reason: reason ?? null
    });
    return {
      pending_change_id: change.id,
      applied: false,
      summary: `${action} ${entity_type}${payload?.title ? ` "${payload.title}"` : ''}`
    };
  }
};
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/agent/tools/propose_change.test.js`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/ai/agent/tools/propose_change.js tests/ai/agent/tools/propose_change.test.js
git commit -m "feat(ai): propose_change tool — drafts to pending_changes, never applies

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 9: Tool index (wire the four tools into a registry)

**Files:**
- Create: `lib/ai/agent/tools/index.js`
- Test: `tests/ai/agent/tools/index.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/agent/tools/index.test.js
import { describe, it, expect } from 'vitest';
import { companionRegistry } from '../../../../lib/ai/agent/tools/index.js';

describe('companion registry', () => {
  it('registers exactly the four v1 tools', () => {
    expect(companionRegistry.listTools().map(t => t.name).sort())
      .toEqual(['context', 'propose_change', 'read', 'search']);
  });
  it('exposes them in Anthropic shape', () => {
    const tools = companionRegistry.toAnthropicTools();
    expect(tools.every(t => t.name && t.input_schema && !('handler' in t))).toBe(true);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/agent/tools/index.test.js`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement `lib/ai/agent/tools/index.js`**

```javascript
import { createRegistry } from '../registry.js';
import { searchTool } from './search.js';
import { readTool } from './read.js';
import { contextTool } from './context.js';
import { proposeChangeTool } from './propose_change.js';

// The shared registry. Adding a tool later is a one-line registerTool() call
// here (see spec §7 — extensible tool registry). A future MCP server can
// import this same registry and re-expose toAnthropicTools().
export const companionRegistry = createRegistry();
companionRegistry.registerTool(searchTool);
companionRegistry.registerTool(readTool);
companionRegistry.registerTool(contextTool);
companionRegistry.registerTool(proposeChangeTool);
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/agent/tools/index.test.js`
Expected: PASS (2 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/ai/agent/tools/index.js tests/ai/agent/tools/index.test.js
git commit -m "feat(ai): wire the four v1 companion tools into a shared registry

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 10: Anthropic client + `makeCallModel`

Decouple the SDK from the runtime behind a `callModel({ system, messages, tools, onTextDelta })` function. Production wraps `client.messages.stream(...)`; tests inject a fake. Default model `claude-sonnet-4-6` (good tool-use, cheaper than Opus for a chat companion); overridable per-agent via `agent.model` and globally via `ANTHROPIC_MODEL`.

**Files:**
- Create: `lib/ai/anthropic.js`
- Test: `tests/ai/anthropic.test.js`

- [ ] **Step 1: Write the failing test** (tests the pure shaping logic, not the network)

```javascript
// tests/ai/anthropic.test.js
import { describe, it, expect } from 'vitest';
import { makeCallModel } from '../../lib/ai/anthropic.js';

// Fake SDK client whose stream() yields text deltas then a tool_use block.
function fakeClient(events) {
  return {
    messages: {
      stream() {
        return {
          async *[Symbol.asyncIterator]() { for (const e of events) yield e; }
        };
      }
    }
  };
}

describe('makeCallModel', () => {
  it('accumulates text, forwards deltas, and collects tool_use', async () => {
    const events = [
      { type: 'content_block_delta', delta: { type: 'text_delta', text: 'Hel' } },
      { type: 'content_block_delta', delta: { type: 'text_delta', text: 'lo' } },
      { type: 'content_block_start', content_block: { type: 'tool_use', id: 'tu_1', name: 'search', input: {} } },
      { type: 'input_json_delta_done', toolInput: { q: 'x' } }, // see impl note
      { type: 'message_delta', usage: { output_tokens: 5 } },
      { type: 'message_stop', message: { stop_reason: 'tool_use', usage: { input_tokens: 10, output_tokens: 5 } } }
    ];
    const callModel = makeCallModel({ client: fakeClient(events), model: 'm' });
    const deltas = [];
    const out = await callModel({ system: 's', messages: [], tools: [], onTextDelta: t => deltas.push(t) });
    expect(deltas.join('')).toBe('Hello');
    expect(out.text).toBe('Hello');
    expect(out.toolUses[0]).toMatchObject({ id: 'tu_1', name: 'search' });
    expect(out.stopReason).toBe('tool_use');
  });
});
```

> **Impl note:** the real Anthropic stream emits `input_json_delta` events whose partial JSON must be accumulated and parsed at `content_block_stop`. To keep this testable and robust, the implementation listens to the SDK's higher-level `inputJson`/`finalMessage()` helpers. Use the SDK's `stream.finalMessage()` to collect the assembled `tool_use` blocks rather than hand-assembling JSON. The fake above simulates the assembled result; adjust event names to match `@anthropic-ai/sdk` if the SDK helper API differs, keeping the **return shape** `{ text, toolUses, stopReason, usage }` stable.

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/anthropic.test.js`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement `lib/ai/anthropic.js`**

```javascript
import Anthropic from '@anthropic-ai/sdk';
import { resolveSecret } from './secret.js';

export const DEFAULT_MODEL = process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-6';

export function getAnthropicClient() {
  const key = resolveSecret(process.env.ANTHROPIC_API_KEY_REF || 'env:ANTHROPIC_API_KEY');
  if (!key) throw new Error('Anthropic API key not configured (set ANTHROPIC_API_KEY or ANTHROPIC_API_KEY_REF)');
  return new Anthropic({ apiKey: key });
}

// Returns callModel({ system, messages, tools, onTextDelta }) -> { text, toolUses, stopReason, usage }.
// Streams text deltas through onTextDelta; collects tool_use blocks from the
// final assembled message so partial-JSON handling is the SDK's problem.
export function makeCallModel({ client, model = DEFAULT_MODEL, maxTokens = 1024 }) {
  return async function callModel({ system, messages, tools, onTextDelta }) {
    const stream = client.messages.stream({
      model, max_tokens: maxTokens, system, messages, tools
    });
    for await (const event of stream) {
      if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
        onTextDelta?.(event.delta.text);
      }
    }
    const final = await stream.finalMessage();
    const text = final.content.filter(b => b.type === 'text').map(b => b.text).join('');
    const toolUses = final.content
      .filter(b => b.type === 'tool_use')
      .map(b => ({ id: b.id, name: b.name, input: b.input }));
    return { text, toolUses, stopReason: final.stop_reason, usage: final.usage };
  };
}
```

> **If the SDK's streaming iterator/`finalMessage()` API differs** from the above in the installed version, adjust the event handling but keep the return shape identical so Task 11's runtime is unaffected. Verify against context7 docs for `@anthropic-ai/sdk` message streaming.

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/anthropic.test.js`
Expected: PASS. (If the fake event shape needs tweaking to match the SDK helper, update the test fake — the assertion on the return shape is what matters.)

- [ ] **Step 5: Commit**

```bash
git add lib/ai/anthropic.js tests/ai/anthropic.test.js
git commit -m "feat(ai): Anthropic client + streaming callModel adapter

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 11: Agent runtime (`runTurn`)

The tool-use loop. Pure orchestration — `callModel` and the registry are injected, so it unit-tests with no network. Emits events via `onEvent`; returns the final assistant text + trace.

**Files:**
- Create: `lib/ai/agent/runtime.js`
- Test: `tests/ai/agent/runtime.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/ai/agent/runtime.test.js
import { describe, it, expect } from 'vitest';
import { createRegistry } from '../../../lib/ai/agent/registry.js';
import { runTurn } from '../../../lib/ai/agent/runtime.js';

function scriptedCallModel(steps) {
  let i = 0;
  return async ({ onTextDelta }) => {
    const step = steps[i++];
    if (step.text) for (const ch of step.text) onTextDelta?.(ch);
    return { text: step.text || '', toolUses: step.toolUses || [], stopReason: step.toolUses ? 'tool_use' : 'end_turn', usage: { output_tokens: 1 } };
  };
}

describe('runTurn', () => {
  it('runs a tool then produces a final answer', async () => {
    const reg = createRegistry();
    reg.registerTool({ name: 'search', description: 's', input_schema: { type: 'object', properties: {} },
      handler: async () => ({ results: [{ title: 'Hit' }] }) });

    const callModel = scriptedCallModel([
      { toolUses: [{ id: 'tu1', name: 'search', input: { q: 'x' } }] },
      { text: 'Found it.' }
    ]);

    const events = [];
    const out = await runTurn({
      callModel, registry: reg, system: 'sys',
      messages: [{ role: 'user', content: 'find x' }],
      ctx: { agent: { id: 'a' }, space_id: 's' },
      onEvent: e => events.push(e)
    });

    expect(out.text).toBe('Found it.');
    expect(events.filter(e => e.type === 'tool').map(e => e.tool)).toEqual(['search']);
    expect(events.some(e => e.type === 'delta' && e.text)).toBe(true);
    expect(out.toolTrace[0]).toMatchObject({ tool: 'search' });
  });

  it('emits a draft event when propose_change runs', async () => {
    const reg = createRegistry();
    reg.registerTool({ name: 'propose_change', description: 'p', input_schema: { type: 'object', properties: {} },
      handler: async () => ({ pending_change_id: 'pc1', applied: false, summary: 'create task "X"' }) });

    const callModel = scriptedCallModel([
      { toolUses: [{ id: 'tu1', name: 'propose_change', input: {} }] },
      { text: 'Drafted.' }
    ]);

    const events = [];
    const out = await runTurn({ callModel, registry: reg, system: 's',
      messages: [{ role: 'user', content: 'make a task' }],
      ctx: { agent: { id: 'a' } }, onEvent: e => events.push(e) });

    expect(out.draftIds).toEqual(['pc1']);
    expect(events.find(e => e.type === 'draft')).toMatchObject({ pending_change_id: 'pc1' });
  });

  it('stops at the iteration guard', async () => {
    const reg = createRegistry();
    reg.registerTool({ name: 'search', description: 's', input_schema: { type: 'object', properties: {} },
      handler: async () => ({ results: [] }) });
    const always = async () => ({ text: '', toolUses: [{ id: 't', name: 'search', input: {} }], stopReason: 'tool_use', usage: {} });
    const out = await runTurn({ callModel: always, registry: reg, system: 's',
      messages: [{ role: 'user', content: 'loop' }], ctx: { agent: { id: 'a' } }, onEvent: () => {}, maxIterations: 3 });
    expect(out.toolTrace.length).toBe(3);
    expect(out.stoppedOnGuard).toBe(true);
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/ai/agent/runtime.test.js`
Expected: FAIL — module not found.

- [ ] **Step 3: Implement `lib/ai/agent/runtime.js`**

```javascript
// Tool-use loop. callModel + registry injected (no network here).
// Emits: { type:'tool', tool, args, status } | { type:'delta', text }
//        | { type:'draft', pending_change_id, summary }
// Returns: { text, toolTrace, draftIds, usage, stoppedOnGuard }
export async function runTurn({ callModel, registry, system, messages, ctx, onEvent, maxIterations = 6 }) {
  const convo = [...messages];
  const toolTrace = [];
  const draftIds = [];
  let usage = {};
  let stoppedOnGuard = false;

  for (let i = 0; i < maxIterations; i++) {
    const res = await callModel({
      system,
      messages: convo,
      tools: registry.toAnthropicTools(),
      onTextDelta: (t) => onEvent?.({ type: 'delta', text: t })
    });
    usage = res.usage || usage;

    if (!res.toolUses?.length) {
      return { text: res.text, toolTrace, draftIds, usage, stoppedOnGuard };
    }

    // Record the assistant turn (text + tool_use blocks) for the next round.
    convo.push({
      role: 'assistant',
      content: [
        ...(res.text ? [{ type: 'text', text: res.text }] : []),
        ...res.toolUses.map(t => ({ type: 'tool_use', id: t.id, name: t.name, input: t.input }))
      ]
    });

    const toolResults = [];
    for (const call of res.toolUses) {
      onEvent?.({ type: 'tool', tool: call.name, args: call.input, status: 'running' });
      const tool = registry.getTool(call.name);
      let result;
      try {
        result = tool ? await tool.handler(call.input, ctx) : { error: `unknown tool ${call.name}` };
      } catch (e) {
        result = { error: String(e?.message || e) };
      }
      toolTrace.push({ tool: call.name, args: call.input, ok: !result?.error });
      if (result?.pending_change_id) {
        draftIds.push(result.pending_change_id);
        onEvent?.({ type: 'draft', pending_change_id: result.pending_change_id, summary: result.summary });
      }
      onEvent?.({ type: 'tool', tool: call.name, status: result?.error ? 'error' : 'done' });
      toolResults.push({ type: 'tool_result', tool_use_id: call.id, content: JSON.stringify(result) });
    }
    convo.push({ role: 'user', content: toolResults });

    if (i === maxIterations - 1) stoppedOnGuard = true;
  }

  return { text: '', toolTrace, draftIds, usage, stoppedOnGuard };
}
```

- [ ] **Step 4: Run it to confirm it passes**

Run: `npx vitest run tests/ai/agent/runtime.test.js`
Expected: PASS (3 tests).

- [ ] **Step 5: Commit**

```bash
git add lib/ai/agent/runtime.js tests/ai/agent/runtime.test.js
git commit -m "feat(ai): agent runtime tool-use loop with event streaming

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 12: Companion API — history + SSE turn endpoint

`GET /api/spaces/:space_id/companion` → `{ conversation_id, agent, messages }`.
`POST /api/spaces/:space_id/companion/turn` (SSE) → persists the user message, runs `runTurn`, streams events, persists one assistant message with the trace in `metadata`.

The runtime's `callModel` is taken from `req.app.locals.callModel` when present (tests inject a fake) and otherwise built from the real client — so the integration test never hits the network.

**Files:**
- Create: `lib/api/routes/companion.js`
- Modify: `lib/api/index.js`
- Test: `tests/api/companion.test.js`

- [ ] **Step 1: Write the failing test**

```javascript
// tests/api/companion.test.js
import { describe, it, expect, beforeAll } from 'vitest';
import request from 'supertest';
import { pool } from '../../lib/pool.js';
import { createApp } from '../../server.js';
import { resetDb } from '../helpers/db.js';
import { migrateUp } from '../../lib/db/migrate.js';

let app, spaceId;
beforeAll(async () => {
  await resetDb(); await migrateUp();
  process.env.OWNER_TOKEN = 'test-token';
  ({ rows: [{ id: spaceId }] } = await pool.query(
    `INSERT INTO spaces(slug,name) VALUES('s','S') RETURNING id`));
  app = createApp();
  // Inject a scripted callModel: one propose_change call, then a final answer.
  let step = 0;
  app.locals.callModel = async ({ onTextDelta }) => {
    if (step++ === 0) return { text: '', toolUses: [{ id: 't1', name: 'propose_change',
      input: { entity_type: 'task', action: 'create', payload: { space_id: spaceId, title: 'Validate CSV' } } }], stopReason: 'tool_use', usage: {} };
    for (const ch of 'Drafted a task.') onTextDelta?.(ch);
    return { text: 'Drafted a task.', toolUses: [], stopReason: 'end_turn', usage: { output_tokens: 3 } };
  };
});

const auth = (r) => r.set('Authorization', 'Bearer test-token');

describe('companion API', () => {
  it('GET creates the conversation and returns empty history', async () => {
    const res = await auth(request(app).get(`/api/spaces/${spaceId}/companion`));
    expect(res.status).toBe(200);
    expect(res.body.conversation_id).toBeTruthy();
    expect(res.body.messages).toEqual([]);
  });

  it('POST /turn streams SSE events and persists messages + draft', async () => {
    const res = await auth(request(app).post(`/api/spaces/${spaceId}/companion/turn`))
      .send({ text: 'make a task to validate the CSV' });
    expect(res.status).toBe(200);
    expect(res.headers['content-type']).toMatch(/text\/event-stream/);
    expect(res.text).toMatch(/event: tool/);
    expect(res.text).toMatch(/event: draft/);
    expect(res.text).toMatch(/event: delta/);
    expect(res.text).toMatch(/event: done/);

    const { rows: msgs } = await pool.query(
      `SELECT role, body, metadata FROM messages ORDER BY created_at`);
    expect(msgs.map(m => m.role)).toEqual(['user', 'assistant']);
    expect(msgs[1].body).toBe('Drafted a task.');
    expect(msgs[1].metadata.draft_ids).toHaveLength(1);

    const { rows: pc } = await pool.query(`SELECT * FROM pending_changes`);
    expect(pc).toHaveLength(1);
    expect(pc[0].status).toBe('pending');

    const { rows: tasks } = await pool.query(`SELECT * FROM tasks WHERE title='Validate CSV'`);
    expect(tasks).toHaveLength(0); // draft only, not applied
  });
});
```

- [ ] **Step 2: Run it to confirm it fails**

Run: `npx vitest run tests/api/companion.test.js`
Expected: FAIL — route not mounted (404) / module not found.

- [ ] **Step 3: Implement `lib/api/routes/companion.js`**

```javascript
import { Router } from 'express';
import { z } from 'zod';
import { validate } from '../validate.js';
import { asyncWrap } from '../errors.js';
import * as conversations from '../../db/repos/conversations.js';
import * as messages from '../../db/repos/messages.js';
import * as agents from '../../db/repos/agents.js';
import { companionRegistry } from '../../ai/agent/tools/index.js';
import { runTurn } from '../../ai/agent/runtime.js';
import { makeCallModel, getAnthropicClient, DEFAULT_MODEL } from '../../ai/anthropic.js';

const COMPANION_SLUG = 'companion';

const SYSTEM = `You are the Void companion — a concise, helpful assistant embedded in a personal knowledge system.
Ground answers in the Void's content: call the context tool to see what the owner is looking at, and search/read before answering factual questions.
When the owner asks you to change something, use propose_change — it creates a draft they approve; you cannot apply changes directly. Be brief.`;

async function resolveConversation(space_id) {
  const agent = await agents.getBySlug(COMPANION_SLUG);
  const convo = await conversations.findOrCreateForSpace(space_id, agent.id, { kind: 'user', id: null });
  return { agent, convo };
}

// Build Anthropic-format history from stored messages (text-only turns).
function toAnthropicHistory(rows) {
  return rows
    .filter(m => m.role === 'user' || m.role === 'assistant')
    .map(m => ({ role: m.role, content: m.body }));
}

export const spacesScopedRouter = Router({ mergeParams: true });

spacesScopedRouter.get('/', asyncWrap(async (req, res) => {
  const { agent, convo } = await resolveConversation(req.params.space_id);
  const rows = await messages.listByConversation(convo.id);
  res.json({
    conversation_id: convo.id,
    agent: { id: agent.id, slug: agent.slug, name: agent.name },
    messages: rows
  });
}));

const turnSchema = z.object({
  text: z.string().min(1),
  view: z.object({ entityType: z.string(), entityId: z.string() }).partial().optional()
});

spacesScopedRouter.post('/turn',
  validate({ body: turnSchema }),
  asyncWrap(async (req, res) => {
    const { agent, convo } = await resolveConversation(req.params.space_id);
    const { text, view } = req.body;

    await messages.append(convo.id, { role: 'user', body: text });

    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive'
    });
    const send = (event, data) => res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);

    const callModel = req.app.locals.callModel
      || makeCallModel({ client: getAnthropicClient(), model: agent.model || DEFAULT_MODEL });

    const history = toAnthropicHistory(await messages.listByConversation(convo.id));

    let result;
    try {
      result = await runTurn({
        callModel,
        registry: companionRegistry,
        system: SYSTEM,
        messages: history,
        ctx: {
          agent: { kind: 'agent', id: agent.id, capabilities: agent.capabilities, scopes: agent.scopes },
          space_id: req.params.space_id,
          view: view ?? null,
          actor: req.actor
        },
        onEvent: (e) => send(e.type, e)
      });
    } catch (e) {
      send('error', { message: String(e?.message || e) });
      return res.end();
    }

    const assistant = await messages.append(convo.id, {
      role: 'assistant', body: result.text, agent_id: agent.id,
      metadata: { tool_trace: result.toolTrace, draft_ids: result.draftIds, usage: result.usage }
    });

    send('done', { assistant_message_id: assistant.id, draft_ids: result.draftIds, usage: result.usage });
    res.end();
  })
);
```

- [ ] **Step 4: Add `getBySlug` to the agents repo if absent**

Check `lib/db/repos/agents.js`. If there is no `getBySlug`, add:

```javascript
export async function getBySlug(slug) {
  const { rows: [r] } = await pool.query(`SELECT * FROM agents WHERE slug=$1`, [slug]);
  return r;
}
```

- [ ] **Step 5: Mount the router in `lib/api/index.js`**

Add the import near the other route imports:
```javascript
import { spacesScopedRouter as companionRouter } from './routes/companion.js';
```
Add the mount line alongside the other `/spaces/:space_id/...` mounts (e.g. after the resources line):
```javascript
api.use('/spaces/:space_id/companion', companionRouter);
```

- [ ] **Step 6: Run it to confirm it passes**

Run: `npx vitest run tests/api/companion.test.js`
Expected: PASS (2 tests).

- [ ] **Step 7: Run the full suite (no regressions)**

Run: `npm test`
Expected: all green (existing 247 Node tests + the new ones).

- [ ] **Step 8: Commit**

```bash
git add lib/api/routes/companion.js lib/api/index.js lib/db/repos/agents.js tests/api/companion.test.js
git commit -m "feat(api): companion SSE turn endpoint + per-Space history

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 13: Browser SSE reader (`public/sse.js`)

`EventSource` can't send the `Authorization` header, so read the SSE stream from a `fetch` POST body. Parses `event:`/`data:` frames and invokes a handler per event.

**Files:**
- Create: `public/sse.js`

> No automated test (browser-only); verified in the UI smoke (Task 15).

- [ ] **Step 1: Implement `public/sse.js`**

```javascript
// Authenticated POST -> SSE reader. Calls onEvent({ type, ...data }) per frame.
const TOKEN_KEY = 'void_token';

export async function streamTurn(path, body, onEvent) {
  const res = await fetch(path, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + (localStorage.getItem(TOKEN_KEY) || ''),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });
  if (!res.ok || !res.body) throw new Error('stream failed: ' + res.status);

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buf = '';
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buf += decoder.decode(value, { stream: true });
    const frames = buf.split('\n\n');
    buf = frames.pop();                       // keep the trailing partial
    for (const frame of frames) {
      let event = 'message', data = '';
      for (const line of frame.split('\n')) {
        if (line.startsWith('event:')) event = line.slice(6).trim();
        else if (line.startsWith('data:')) data += line.slice(5).trim();
      }
      if (data) onEvent({ type: event, ...JSON.parse(data) });
    }
  }
}
```

- [ ] **Step 2: Commit**

```bash
git add public/sse.js
git commit -m "feat(ui): authenticated POST->SSE reader

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 14: Right-rail chat UI (`public/components/rightrail.js`)

Replace the stub with the approved design: label-led turns (YOU / agent), left/right alignment with accent edges, live tool-activity chips, streamed answer, inline draft card. Uses safe-DOM (`el`/`mount`/`safeHref`); assistant markdown only via the sanitized `html:` path.

**Files:**
- Modify: `public/components/rightrail.js`
- Modify: `public/style.css`
- Depends on: `public/api.js` (existing `api.get`), `public/sse.js` (Task 13), `marked` + `DOMPurify` (already vendored — confirm `public/vendor/`)

- [ ] **Step 1: Confirm marked + DOMPurify are available to the browser**

Run: `ls public/vendor/`
Expected: marked + dompurify bundles present (used by `markdown_editor.js`). If a shared `renderMarkdown(src)` helper exists (grep `public` for `DOMPurify.sanitize`), reuse it; otherwise add `public/markdown.js`:

```javascript
import { marked } from './vendor/marked.esm.js';
import DOMPurify from './vendor/purify.es.js';
export function renderMarkdown(src) {
  return DOMPurify.sanitize(marked.parse(src || ''));
}
```
(Match the exact vendor filenames from `ls public/vendor/`.)

- [ ] **Step 2: Implement `public/components/rightrail.js`**

```javascript
// Plan 5: per-Space companion chat. Safe-DOM only; markdown via sanitized html:.
import { el, mount, clear } from '../dom.js';
import { api } from '../api.js';
import { streamTurn } from '../sse.js';
import { renderMarkdown } from '../markdown.js';
import { state } from '../state.js';

const COLLAPSE_KEY = 'void_rail_collapsed';

function turnEl(role, agentName, bodyNode) {
  return el('div', { class: 'turn ' + (role === 'user' ? 'you' : 'ai') },
    el('span', { class: 'lbl' }, role === 'user' ? 'YOU' : (agentName || 'COMPANION').toUpperCase()),
    el('span', { class: 'msg' }, bodyNode));
}

function chipEl(tool, status) {
  const icon = tool === 'search' ? '🔍' : tool === 'read' ? '📄' : tool === 'context' ? '🧭' : '📝';
  return el('div', { class: 'tools' }, el('span', { class: 'chip' + (status === 'error' ? ' err' : '') }, `${icon} ${tool}`));
}

function draftCardEl(d, onResolve) {
  const card = el('div', { class: 'draftx', dataset: { pc: d.pending_change_id } },
    el('div', { class: 'dh' }, 'Proposed change'),
    el('div', { class: 'dt' }, d.summary || 'a change'),
    el('div', { class: 'row' },
      el('button', { class: 'ok', onclick: () => onResolve(d.pending_change_id, 'approved', card) }, 'Approve'),
      el('button', { class: 'no', onclick: () => onResolve(d.pending_change_id, 'rejected', card) }, 'Reject')));
  return card;
}

export async function renderRightrail(root) {
  const shell = document.getElementById('shell');
  let collapsed = localStorage.getItem(COLLAPSE_KEY) === 'true';
  if (collapsed) shell.classList.add('rail-collapsed');
  const toggle = () => {
    collapsed = !collapsed;
    localStorage.setItem(COLLAPSE_KEY, String(collapsed));
    shell.classList.toggle('rail-collapsed', collapsed);
  };

  const log = el('div', { class: 'rail-log' });
  const input = el('textarea', { class: 'rail-input', rows: 1, placeholder: 'Ask the companion…' });
  const header = el('div', { class: 'rail-hd' },
    el('span', { class: 'who' }, '◆ Companion'),
    el('span', { class: 'chev', onclick: toggle, title: 'Collapse' }, '⟩'));

  mount(root, el('div', { class: 'rail-toggle', onclick: toggle, title: 'Companion' }, 'CRADLE'),
    el('div', { class: 'rail-chat' }, header, log, el('div', { class: 'rail-inputwrap' }, input)));

  const spaceId = state.spaceId;
  if (!spaceId) {
    mount(log, el('p', { class: 'muted' }, 'Open a Space to chat with its companion.'));
    return;
  }

  async function resolveDraft(id, status, cardNode) {
    try {
      await api.post(`/api/pending-changes/${id}/${status === 'approved' ? 'approve' : 'reject'}`);
      cardNode.classList.add('resolved');
      cardNode.appendChild(el('div', { class: 'resolved-tag' }, status));
    } catch (e) { cardNode.appendChild(el('div', { class: 'err' }, 'failed: ' + e.message)); }
  }

  function addTurn(role, text) {
    const body = role === 'assistant'
      ? el('span', { html: renderMarkdown(text) })
      : el('span', {}, text);
    const t = turnEl(role, 'Companion', body);
    log.appendChild(t);
    log.scrollTop = log.scrollHeight;
    return body;
  }

  // Load history.
  const { messages } = await api.get(`/api/spaces/${spaceId}/companion`);
  clear(log);
  for (const m of messages) {
    addTurn(m.role, m.body);
    for (const d of (m.metadata?.draft_ids || []))
      log.appendChild(draftCardEl({ pending_change_id: d, summary: 'a change' }, resolveDraft));
  }

  async function send() {
    const text = input.value.trim();
    if (!text) return;
    input.value = '';
    addTurn('user', text);
    let assistantBody = null, acc = '';
    await streamTurn(`/api/spaces/${spaceId}/companion/turn`, { text, view: state.view || null }, (ev) => {
      if (ev.type === 'tool' && ev.status !== 'done') log.appendChild(chipEl(ev.tool, ev.status));
      else if (ev.type === 'delta') {
        if (!assistantBody) assistantBody = addTurn('assistant', '');
        acc += ev.text; assistantBody.innerHTML = renderMarkdown(acc);
      } else if (ev.type === 'draft') log.appendChild(draftCardEl(ev, resolveDraft));
      else if (ev.type === 'error') log.appendChild(el('div', { class: 'err' }, ev.message));
      log.scrollTop = log.scrollHeight;
    });
  }

  input.addEventListener('keydown', (e) => {
    if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); send(); }
  });
}
```

> **Note:** confirm `public/state.js` exposes `spaceId` and `view`. If it currently only tracks one of these, extend it (small change) so the rail and router agree on the active Space + view. Check `router.js` for how the current Space is set and mirror it into `state`.

- [ ] **Step 3: Add styles to `public/style.css`**

Append rail/turn/chip/draft styles consistent with the approved mockup (label-led, left/right accent edges, dim monospace chips, violet draft card). Use the existing CSS variables in `style.css` for colours where present:

```css
.rail-chat { display:flex; flex-direction:column; height:100%; }
.rail-hd { display:flex; justify-content:space-between; align-items:center; padding:9px 12px; border-bottom:1px solid var(--border,#262b38); }
.rail-hd .who { font-weight:600; color:var(--accent,#b69cff); }
.rail-hd .chev { cursor:pointer; color:#5b6478; }
.rail-log { flex:1; overflow-y:auto; padding:12px; display:flex; flex-direction:column; gap:10px; }
.turn { display:flex; flex-direction:column; max-width:84%; }
.turn .lbl { font-size:9.5px; letter-spacing:.12em; margin-bottom:3px; }
.turn .msg { line-height:1.4; padding:6px 10px; border-radius:8px; background:#141826; }
.turn.you { align-self:flex-end; align-items:flex-end; }
.turn.you .lbl { color:#6f7ce0; } .turn.you .msg { border-right:2px solid #6f7ce0; }
.turn.ai { align-self:flex-start; } .turn.ai .lbl { color:var(--accent,#b69cff); }
.turn.ai .msg { border-left:2px solid var(--accent,#b69cff); }
.tools { align-self:flex-start; }
.tools .chip { font-family:ui-monospace,Menlo,monospace; font-size:10.5px; color:#7d869b; }
.tools .chip.err { color:#e08a8a; }
.draftx { align-self:flex-start; max-width:90%; border:1px solid #3a2f5e; background:#1a1530; border-radius:9px; padding:9px 11px; }
.draftx .dh { font-size:9.5px; text-transform:uppercase; letter-spacing:.1em; color:#9b7dff; }
.draftx .dt { color:#e3e0f5; margin:4px 0 9px; }
.draftx .row { display:flex; gap:6px; }
.draftx .ok { background:#2a6f4f; color:#d9ffe9; border:none; border-radius:6px; padding:4px 12px; }
.draftx .no { background:#2a2f3d; color:#aeb6c7; border:none; border-radius:6px; padding:4px 12px; }
.draftx.resolved { opacity:.55; } .resolved-tag { font-size:10px; text-transform:uppercase; color:#7d869b; margin-top:6px; }
.rail-inputwrap { border-top:1px solid var(--border,#262b38); padding:9px 12px; }
.rail-input { width:100%; resize:none; background:#0c0e14; color:#c9d1e0; border:1px solid #262b38; border-radius:8px; padding:7px 9px; }
.err { color:#e08a8a; font-size:12px; }
```

- [ ] **Step 4: Commit**

```bash
git add public/components/rightrail.js public/markdown.js public/style.css public/state.js
git commit -m "feat(ui): right-rail companion chat — streaming, tool chips, inline drafts

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 15: Verify the pending-changes approve/reject endpoints exist for the rail

The draft card POSTs to `/api/pending-changes/:id/approve` and `/reject`. Confirm those routes exist (Plan 2 built the inbox) and return the resolved row; if the paths differ, align the rail's `resolveDraft` calls to the real endpoints.

**Files:**
- Inspect: `lib/api/routes/pending_changes.js`
- Modify (only if needed): `public/components/rightrail.js`

- [ ] **Step 1: Inspect the routes**

Run: `grep -nE "approve|reject|router\.(post|patch)" lib/api/routes/pending_changes.js`
Expected: approve/reject endpoints exist. Note the exact method + path.

- [ ] **Step 2: Align the rail if the paths/methods differ**

If e.g. the API uses `PATCH /api/pending-changes/:id` with `{ status }`, change `resolveDraft` accordingly:
```javascript
await api.patch(`/api/pending-changes/${id}`, { status });
```

- [ ] **Step 3: Confirm the Inbox view reads the same rows**

Run: `grep -n "pending-changes" public/views/inbox.js`
Expected: the Inbox lists `/api/pending-changes` — confirming a draft approved in chat disappears from the Inbox (same row, shared state).

- [ ] **Step 4: Commit (only if the rail changed)**

```bash
git add public/components/rightrail.js
git commit -m "fix(ui): align draft card with the pending-changes resolve endpoint

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Task 16: Manual UI smoke + deploy alpha-5

**Files:**
- Modify: `package.json` (version), `CHANGELOG.md`
- Create: `docs/plan-5-complete.md`

- [ ] **Step 1: Full test suite green**

Run: `npm test`
Expected: all green.

- [ ] **Step 2: Local smoke against the dev DB**

Set `ANTHROPIC_API_KEY` in the dev `.env`, start the server (`npm start`), open the SPA, pick a Space, and:
- ask a question → confirm tool chips appear, the answer streams in, markdown renders.
- ask it to "create a task to X" → confirm an inline draft card appears, **and** the same row shows in the Inbox.
- approve from chat → confirm the task now exists (`/api/tasks`) and the Inbox row clears.
- reject another draft → confirm it does not apply.

- [ ] **Step 3: Bump version + changelog**

Set `package.json` version to `2.0.0-alpha.5`. Add a `CHANGELOG.md` entry summarising the companion chat (scope B). Write `docs/plan-5-complete.md` (mirror the structure of `docs/plan-4-complete.md`: what shipped, files, security notes, deferred items → C personas/MCP/Vaultwarden).

- [ ] **Step 4: Commit**

```bash
git add package.json CHANGELOG.md docs/plan-5-complete.md
git commit -m "chore: version 2.0.0-alpha.5 + plan-5 completion doc

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

- [ ] **Step 5: Deploy (standing rule: snapshot first)**

On Z: `pct snapshot 310 pre_alpha5_deploy_<ts>` and `pct snapshot 311 pre_alpha5_deploy_<ts>`.
Ensure `ANTHROPIC_API_KEY` is set in `/opt/void-server/.env` on CT 311 (mode 600, owned by `void`).
Then from the repo: `TARGET=root@192.168.1.216 ./deploy/push.sh`.
Verify: `curl http://192.168.1.216:3000/health` → `version: 2.0.0-alpha.5`, then run the Step-2 smoke against the deployed instance.

- [ ] **Step 6: Update memory**

Update `project_void_v2_execution.md`: Plan 5 complete + alpha-5 deployed; companion chat live; note deferred C personas / MCP / Vaultwarden.

---

## Self-review notes (for the planner)

- **Spec coverage:** runtime (T10–11), shared/extensible registry (T5, T9), four tools (T6–8), SSE turn lifecycle + one-assistant-message-with-trace (T12), per-Space ambient conversation (T3–4, T12), inline draft card synced with Inbox (T14–15), env/file key handling (T2, T10), prompt-injection containment via approval-only `propose_change` (T8 test asserts no apply), cost guardrail via `maxTokens` + `maxIterations` (T10–11), tests incl. security (T8, T12). All spec §s map to a task.
- **Type/name consistency:** `callModel({system,messages,tools,onTextDelta}) -> {text,toolUses,stopReason,usage}` is used identically in T10, T11, T12. `ctx = {agent,space_id,view,actor}` consistent across T6–8 and T12. Event types `tool|delta|draft|done|error` consistent across T11–14. `companionRegistry` name consistent T9/T12.
- **Known external-API risk:** the exact `@anthropic-ai/sdk` streaming/`finalMessage()` surface (T10) may differ by version — flagged inline with a context7 check and a stable return-shape contract so the rest of the plan is insulated.
- **Assumptions to verify during execution (flagged in-task):** `agents.getBySlug` may need adding (T12 S4); `pending-changes` resolve path/method (T15); `state.js` exposing `spaceId`/`view` (T14); exact vendor filenames for marked/DOMPurify (T14 S1).