608 lines
27 KiB
Markdown
608 lines
27 KiB
Markdown
# Yerin Online 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:** Bring Yerin (read-only security agent) online with a global chat surface, extracting the shared agent-chat foundation (backend `run_turn` + frontend `agent_chat`) that Dross also rides on.
|
||
|
||
**Architecture:** Extract the turn-runner from `companion.js` into `lib/ai/agent/run_turn.js` and personas into `lib/ai/personas/`. Add a global (`space_id NULL`) Yerin endpoint reusing them with `VOID_TOOL_REGISTRY=security`. On the frontend, extract `components/agent_chat.js` from `rightrail.js`; add a `#/sentinel` view that uses it (no draft cards).
|
||
|
||
**Tech Stack:** Node 22 ESM, Express 5, `@modelcontextprotocol/sdk`, vanilla-JS no-build SPA, vitest + supertest (serial).
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-06-04-yerin-online-design.md`
|
||
|
||
---
|
||
|
||
### Task 1: `conversations.findOrCreateGlobal`
|
||
|
||
**Files:**
|
||
- Modify: `lib/db/repos/conversations.js`
|
||
- Test: `tests/db/conversations_global.test.js`
|
||
|
||
- [ ] **Step 1: Failing test**
|
||
|
||
```js
|
||
// tests/db/conversations_global.test.js
|
||
import { describe, it, expect, beforeAll } from 'vitest';
|
||
import { resetDb } from '../helpers/db.js';
|
||
import { migrateUp } from '../../lib/db/migrate.js';
|
||
import * as agents from '../../lib/db/repos/agents.js';
|
||
import * as conversations from '../../lib/db/repos/conversations.js';
|
||
|
||
const owner = { kind: 'user', id: null };
|
||
beforeAll(async () => { await resetDb(); await migrateUp(); });
|
||
|
||
describe('findOrCreateGlobal', () => {
|
||
it('creates one space-less open conversation and reuses it', async () => {
|
||
const y = await agents.getBySlug('yerin'); // seeded by 011_yerin.sql
|
||
const c1 = await conversations.findOrCreateGlobal(y.id, owner);
|
||
expect(c1.space_id).toBeNull();
|
||
expect(c1.agent_id).toBe(y.id);
|
||
const c2 = await conversations.findOrCreateGlobal(y.id, owner);
|
||
expect(c2.id).toBe(c1.id);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run → FAIL** (`npx vitest run tests/db/conversations_global.test.js`) — `findOrCreateGlobal is not a function`.
|
||
|
||
- [ ] **Step 3: Implement** — append to `lib/db/repos/conversations.js`:
|
||
|
||
```js
|
||
export async function findOrCreateGlobal(agent_id, actor) {
|
||
const { rows: [existing] } = await pool.query(
|
||
`SELECT * FROM conversations
|
||
WHERE agent_id=$1 AND space_id IS NULL AND status='open'
|
||
ORDER BY started_at DESC LIMIT 1`,
|
||
[agent_id]
|
||
);
|
||
if (existing) return existing;
|
||
const { rows: [r] } = await pool.query(
|
||
`INSERT INTO conversations(title, agent_id, metadata) VALUES($1,$2,$3) RETURNING *`,
|
||
[null, agent_id, {}]
|
||
);
|
||
await recordAudit(actor, 'create', 'conversation', r.id, null, r);
|
||
return r;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run → PASS.**
|
||
- [ ] **Step 5: Commit** — `git add -A && git commit -m "feat(agents): conversations.findOrCreateGlobal for space-less agents"`
|
||
|
||
---
|
||
|
||
### Task 2: Personas module
|
||
|
||
**Files:**
|
||
- Create: `lib/ai/personas/index.js`
|
||
- Test: `tests/ai/personas.test.js`
|
||
|
||
- [ ] **Step 1: Failing test**
|
||
|
||
```js
|
||
// tests/ai/personas.test.js
|
||
import { describe, it, expect } from 'vitest';
|
||
import { PERSONAS, personaFor } from '../../lib/ai/personas/index.js';
|
||
|
||
describe('personas', () => {
|
||
it('has companion (Dross) and yerin personas keyed by agent slug', () => {
|
||
expect(PERSONAS.companion).toMatch(/Dross/);
|
||
expect(PERSONAS.yerin).toMatch(/Yerin/);
|
||
});
|
||
it('personaFor falls back to companion for unknown slugs', () => {
|
||
expect(personaFor('yerin')).toBe(PERSONAS.yerin);
|
||
expect(personaFor('nope')).toBe(PERSONAS.companion);
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run → FAIL** (module missing).
|
||
|
||
- [ ] **Step 3: Implement** — create `lib/ai/personas/index.js`. Move the existing `SYSTEM` constant's value **verbatim** out of `lib/api/routes/companion.js` into `PERSONAS.companion`, and add Yerin's:
|
||
|
||
```js
|
||
// Agent personas keyed by agent slug. Dross's text moved verbatim from
|
||
// companion.js. persona_path file loading is a later (migration) concern.
|
||
export const PERSONAS = {
|
||
companion: `<<PASTE the exact current SYSTEM string from companion.js here>>`,
|
||
yerin: `You are Yerin — once the Sage of the Endless Sword, blade of the Akura clan; now the sentinel of this homelab, The Void. You notice the threat first and you call it. Disciplined, direct, economical with words — a blade wastes no motion. You investigate with your tools and report plainly: what you found, how serious it is, and what the owner should do about it. You never speculate without evidence, and you NEVER pretend to have fixed anything — you have eyes to see and a voice to warn, not hands to act; remediation is the owner's to perform. Before answering, call the relevant tools — audit_log, agent_inventory, pending_review, resource_exposure, token_audit — and read the evidence; do not guess. Reference the Cradle world naturally but never at the cost of being useful. Be concise.`
|
||
};
|
||
|
||
export function personaFor(slug) {
|
||
return PERSONAS[slug] || PERSONAS.companion;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run → PASS.**
|
||
- [ ] **Step 5: Commit** — `git add -A && git commit -m "feat(agents): personas module (Dross + Yerin), keyed by slug"`
|
||
|
||
---
|
||
|
||
### Task 3: `run_turn.js` shared turn-runner
|
||
|
||
**Files:**
|
||
- Create: `lib/ai/agent/run_turn.js`
|
||
- Test: `tests/ai/agent/run_turn.test.js`
|
||
|
||
- [ ] **Step 1: Failing test**
|
||
|
||
```js
|
||
// tests/ai/agent/run_turn.test.js
|
||
import { describe, it, expect, vi, beforeEach } from 'vitest';
|
||
import { readFile } from 'fs/promises';
|
||
vi.mock('../../../lib/ai/claude_cli.js', () => ({ runClaudeTurn: vi.fn() }));
|
||
import { runClaudeTurn } from '../../../lib/ai/claude_cli.js';
|
||
import { runAgentTurn } from '../../../lib/ai/agent/run_turn.js';
|
||
|
||
beforeEach(() => runClaudeTurn.mockReset());
|
||
|
||
describe('runAgentTurn', () => {
|
||
it('builds the MCP config (registry + tools + agent + space) and forwards to runClaudeTurn', async () => {
|
||
let captured;
|
||
runClaudeTurn.mockImplementation(async (opts) => {
|
||
captured = { ...opts, cfg: JSON.parse(await readFile(opts.mcpConfigPath, 'utf8')) };
|
||
return { text: 'ok', toolTrace: [], usage: null };
|
||
});
|
||
const out = await runAgentTurn({
|
||
agent: { id: 'a1', slug: 'yerin', capabilities: { read: true }, scopes: {} },
|
||
persona: 'YERIN', registryName: 'security',
|
||
toolNames: ['mcp__void__audit_log'], spaceId: null,
|
||
sessionId: 'c1', userText: 'check', claudeExe: 'claude'
|
||
});
|
||
expect(out.text).toBe('ok');
|
||
expect(captured.systemPrompt).toBe('YERIN');
|
||
expect(captured.tools).toEqual(['mcp__void__audit_log']);
|
||
expect(captured.allowedTools).toEqual(['mcp__void__audit_log']);
|
||
const env = captured.cfg.mcpServers.void.env;
|
||
expect(env.VOID_TOOL_REGISTRY).toBe('security');
|
||
expect(env.VOID_SPACE_ID).toBe('');
|
||
expect(JSON.parse(env.VOID_AGENT_JSON).id).toBe('a1');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: Run → FAIL** (module missing).
|
||
|
||
- [ ] **Step 3: Implement** — create `lib/ai/agent/run_turn.js`:
|
||
|
||
```js
|
||
import { writeFile, unlink } from 'fs/promises';
|
||
import { join } from 'path';
|
||
import { tmpdir } from 'os';
|
||
import { randomUUID } from 'crypto';
|
||
import { fileURLToPath } from 'url';
|
||
import { runClaudeTurn } from '../claude_cli.js';
|
||
|
||
// Absolute path to the MCP stdio server the claude child spawns.
|
||
const STDIO_PATH = fileURLToPath(new URL('../../mcp/companion-stdio.js', import.meta.url));
|
||
|
||
/**
|
||
* Shared agent turn-runner: builds the per-turn MCP config (selecting the tool
|
||
* registry + injecting agent/space/view), runs one claude turn, cleans up.
|
||
* SSE/persistence stay in the route. Returns runClaudeTurn's result.
|
||
*/
|
||
export async function runAgentTurn({
|
||
agent, persona, registryName, toolNames, spaceId = null, view = null,
|
||
sessionId, resume = false, userText, claudeExe = 'claude', home, onEvent
|
||
}) {
|
||
const agentActor = { kind: 'agent', id: agent.id, capabilities: agent.capabilities, scopes: agent.scopes };
|
||
const mcpConfigPath = join(tmpdir(), `void-mcp-${randomUUID()}.json`);
|
||
const mcpConfig = {
|
||
mcpServers: {
|
||
void: {
|
||
command: process.execPath,
|
||
args: [STDIO_PATH],
|
||
env: {
|
||
VOID_TOOL_REGISTRY: registryName || '',
|
||
VOID_SPACE_ID: spaceId || '',
|
||
VOID_AGENT_JSON: JSON.stringify(agentActor),
|
||
VOID_VIEW_JSON: view ? JSON.stringify(view) : '',
|
||
DATABASE_URL: process.env.DATABASE_URL || '',
|
||
OLLAMA_URL: process.env.OLLAMA_URL || ''
|
||
}
|
||
}
|
||
}
|
||
};
|
||
await writeFile(mcpConfigPath, JSON.stringify(mcpConfig));
|
||
try {
|
||
return await runClaudeTurn({
|
||
sessionId, resume, systemPrompt: persona, userText,
|
||
mcpConfigPath, tools: toolNames, allowedTools: toolNames,
|
||
claudeExe, home, onEvent
|
||
});
|
||
} finally {
|
||
unlink(mcpConfigPath).catch(() => {});
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run → PASS.**
|
||
- [ ] **Step 5: Commit** — `git add -A && git commit -m "feat(agents): shared runAgentTurn turn-runner"`
|
||
|
||
---
|
||
|
||
### Task 4: Refactor `companion.js` onto the shared foundation
|
||
|
||
**Files:**
|
||
- Modify: `lib/api/routes/companion.js`
|
||
|
||
- [ ] **Step 1: Refactor.** In `lib/api/routes/companion.js`:
|
||
- Delete the local `SYSTEM` constant; `import { personaFor } from '../../ai/personas/index.js';`.
|
||
- Delete now-unused imports `writeFile, unlink` (fs/promises), `join` (path), `tmpdir` (os), `randomUUID` (crypto), and the `COMPANION_STDIO_PATH` constant — all now inside `run_turn.js`. Keep `fileURLToPath` only if still used elsewhere (it isn't after removing `COMPANION_STDIO_PATH` → remove it too).
|
||
- `import { runAgentTurn } from '../../ai/agent/run_turn.js';`
|
||
- In the `/turn` handler, **remove** the `mcpConfigPath`/`mcpConfig`/`writeFile` block and the trailing `unlink(mcpConfigPath)` calls. Replace the `runClaudeTurn({...})` call with:
|
||
|
||
```js
|
||
result = await runAgentTurn({
|
||
agent,
|
||
persona: personaFor(agent.slug),
|
||
registryName: undefined, // default → companionRegistry
|
||
toolNames: companionTools,
|
||
spaceId: req.params.space_id,
|
||
view,
|
||
sessionId: convo.id,
|
||
resume,
|
||
userText: text,
|
||
claudeExe,
|
||
home: process.env.VOID_CLAUDE_HOME || undefined,
|
||
onEvent: (e) => { /* keep the EXISTING onEvent body unchanged: delta/tool/tool_result(draft parse)/error */ }
|
||
});
|
||
```
|
||
Keep the existing `onEvent` body (delta/tool/tool_result draft-parsing/error → `send(...)`) exactly as-is. Keep `companionTools`, the post-stream `messages.append(assistant…)` with `draft_ids`, and the `done` event. The `catch` block keeps `send('error',…)` + `res.end()` but drop its `unlink(mcpConfigPath)` line.
|
||
|
||
- [ ] **Step 2: Run companion + related tests → PASS (regression)**
|
||
|
||
Run: `npx vitest run tests/api/companion.test.js`
|
||
Expected: PASS unchanged (SSE delta/tool/draft/done + user/assistant persistence).
|
||
|
||
- [ ] **Step 3: Commit** — `git add -A && git commit -m "refactor(companion): ride on shared runAgentTurn + personas"`
|
||
|
||
---
|
||
|
||
### Task 5: Yerin route + mount + fixture
|
||
|
||
**Files:**
|
||
- Create: `lib/api/routes/security.js`
|
||
- Create: `tests/fixtures/fake-claude-security.js`
|
||
- Modify: `lib/api/index.js`
|
||
- Test: `tests/api/security_yerin.test.js`
|
||
|
||
- [ ] **Step 1: Fake claude fixture** — `tests/fixtures/fake-claude-security.js` (shebang; emits text deltas + one security tool call + result, NO draft):
|
||
|
||
```js
|
||
#!/usr/bin/env node
|
||
const TOOL_USE_ID = 'toolu_yerin_01';
|
||
const lines = [
|
||
{ type: 'system', subtype: 'init', session_id: 'fake-yerin', tools: [], cwd: '/tmp' },
|
||
{ type: 'stream_event', event: { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } } },
|
||
{ type: 'stream_event', event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'No new threats.' } } },
|
||
{ type: 'stream_event', event: { type: 'content_block_stop', index: 0 } },
|
||
{ type: 'stream_event', event: { type: 'content_block_start', index: 1, content_block: { type: 'tool_use', id: TOOL_USE_ID, name: 'mcp__void__audit_log', input: {} } } },
|
||
{ type: 'stream_event', event: { type: 'content_block_stop', index: 1 } },
|
||
{ type: 'tool_result', tool_use_id: TOOL_USE_ID, content: [{ type: 'text', text: JSON.stringify({ entries: [] }) }] },
|
||
{ type: 'result', subtype: 'success', is_error: false, result: 'No new threats.', stop_reason: 'end_turn', session_id: 'fake-yerin', total_cost_usd: 0.0001, usage: { input_tokens: 40, output_tokens: 4 } }
|
||
];
|
||
for (const l of lines) process.stdout.write(JSON.stringify(l) + '\n');
|
||
process.exit(0);
|
||
```
|
||
Then `chmod +x tests/fixtures/fake-claude-security.js`.
|
||
|
||
- [ ] **Step 2: Failing test** — `tests/api/security_yerin.test.js`:
|
||
|
||
```js
|
||
import { describe, it, expect, beforeAll } from 'vitest';
|
||
import { fileURLToPath } from 'url';
|
||
import request from 'supertest';
|
||
import { pool } from '../../lib/db/pool.js';
|
||
import { createApp } from '../../server.js';
|
||
import { resetDb } from '../helpers/db.js';
|
||
import { migrateUp } from '../../lib/db/migrate.js';
|
||
|
||
const FAKE = fileURLToPath(new URL('../fixtures/fake-claude-security.js', import.meta.url));
|
||
let app;
|
||
beforeAll(async () => {
|
||
await resetDb(); await migrateUp();
|
||
process.env.OWNER_TOKEN = 'test-token';
|
||
app = createApp();
|
||
app.locals.claudeExe = FAKE;
|
||
});
|
||
const auth = (r) => r.set('Authorization', 'Bearer test-token');
|
||
|
||
describe('Yerin security API', () => {
|
||
it('GET creates the global conversation and returns Yerin + empty history', async () => {
|
||
const res = await auth(request(app).get('/api/security/yerin'));
|
||
expect(res.status).toBe(200);
|
||
expect(res.body.agent.slug).toBe('yerin');
|
||
expect(res.body.conversation_id).toBeTruthy();
|
||
expect(res.body.messages).toEqual([]);
|
||
});
|
||
it('POST /turn streams SSE and persists user+assistant; no draft event', async () => {
|
||
const res = await auth(request(app).post('/api/security/yerin/turn')).send({ text: 'any new threats?' });
|
||
expect(res.status).toBe(200);
|
||
expect(res.headers['content-type']).toMatch(/text\/event-stream/);
|
||
expect(res.text).toMatch(/event: delta/);
|
||
expect(res.text).toMatch(/event: tool/);
|
||
expect(res.text).toMatch(/event: done/);
|
||
expect(res.text).not.toMatch(/event: draft/);
|
||
const { rows: msgs } = await pool.query(`SELECT role, body FROM messages ORDER BY created_at`);
|
||
expect(msgs.map(m => m.role)).toEqual(['user', 'assistant']);
|
||
expect(msgs[1].body).toBe('No new threats.');
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Run → FAIL** (route 404).
|
||
|
||
- [ ] **Step 4: Implement the route** — `lib/api/routes/security.js`:
|
||
|
||
```js
|
||
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 { runAgentTurn } from '../../ai/agent/run_turn.js';
|
||
import { personaFor } from '../../ai/personas/index.js';
|
||
|
||
const YERIN_SLUG = 'yerin';
|
||
const SECURITY_TOOLS = [
|
||
'mcp__void__audit_log', 'mcp__void__agent_inventory', 'mcp__void__pending_review',
|
||
'mcp__void__resource_exposure', 'mcp__void__token_audit'
|
||
];
|
||
|
||
async function resolveYerin() {
|
||
const agent = await agents.getBySlug(YERIN_SLUG);
|
||
const convo = await conversations.findOrCreateGlobal(agent.id, { kind: 'user', id: null });
|
||
return { agent, convo };
|
||
}
|
||
|
||
export const router = Router();
|
||
|
||
router.get('/yerin', asyncWrap(async (_req, res) => {
|
||
const { agent, convo } = await resolveYerin();
|
||
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) });
|
||
|
||
router.post('/yerin/turn', validate({ body: turnSchema }), asyncWrap(async (req, res) => {
|
||
const { agent, convo } = await resolveYerin();
|
||
const { text } = req.body;
|
||
const resume = (await messages.listByConversation(convo.id)).length > 0;
|
||
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 claudeExe = req.app.locals.claudeExe || process.env.CLAUDE_EXE || 'claude';
|
||
|
||
let result;
|
||
try {
|
||
result = await runAgentTurn({
|
||
agent, persona: personaFor(agent.slug), registryName: 'security',
|
||
toolNames: SECURITY_TOOLS, spaceId: null, view: null,
|
||
sessionId: convo.id, resume, userText: text, claudeExe,
|
||
home: process.env.VOID_CLAUDE_HOME || undefined,
|
||
onEvent: (e) => {
|
||
if (e.type === 'delta') send('delta', { type: 'delta', text: e.text });
|
||
else if (e.type === 'tool') send('tool', { type: 'tool', tool: e.tool, status: e.status });
|
||
else if (e.type === 'error') send('error', { type: 'error', message: e.message });
|
||
}
|
||
});
|
||
} 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, usage: result.usage }
|
||
});
|
||
send('done', { assistant_message_id: assistant.id, usage: result.usage });
|
||
res.end();
|
||
}));
|
||
```
|
||
|
||
- [ ] **Step 5: Mount it** — in `lib/api/index.js`: `import { router as securityRouter } from './routes/security.js';` and, alongside the other `api.use(...)` lines, `api.use('/security', securityRouter);`.
|
||
|
||
- [ ] **Step 6: Run → PASS.** (`npx vitest run tests/api/security_yerin.test.js`)
|
||
- [ ] **Step 7: Commit** — `git add -A && git commit -m "feat(yerin): global security chat endpoint /api/security/yerin"`
|
||
|
||
---
|
||
|
||
### Task 6: Frontend — extract `agent_chat` component
|
||
|
||
**Files:**
|
||
- Create: `public/components/agent_chat.js`
|
||
|
||
No automated test (no-build vanilla-JS convention; verified manually in Task 8).
|
||
|
||
- [ ] **Step 1: Create `public/components/agent_chat.js`** — generalize the chat mechanics currently in `rightrail.js`. It owns the log + input + send loop; the host supplies URLs/labels:
|
||
|
||
```js
|
||
// Reusable agent chat panel. 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';
|
||
|
||
function turnEl(role, agentName, bodyNode) {
|
||
return el('div', { class: 'turn ' + (role === 'user' ? 'you' : 'ai') },
|
||
el('span', { class: 'lbl' }, role === 'user' ? 'YOU' : (agentName || 'AGENT').toUpperCase()),
|
||
el('span', { class: 'msg' }, bodyNode));
|
||
}
|
||
function chipEl(tool, status, toolLabels) {
|
||
const name = String(tool || '').replace(/^mcp__void__/, '');
|
||
return el('div', { class: 'tools' },
|
||
el('span', { class: 'chip' + (status === 'error' ? ' err' : '') }, (toolLabels[name] || name)));
|
||
}
|
||
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;
|
||
}
|
||
|
||
/**
|
||
* Mounts log + input into `logEl`/`inputEl` and wires send.
|
||
* opts: { historyUrl, turnUrl, agentName, showDrafts, toolLabels, turnBody }
|
||
* turnBody(text) → POST body object (lets callers add view, etc.)
|
||
*/
|
||
export function wireAgentChat({ logEl, inputEl, historyUrl, turnUrl, agentName, showDrafts = false, toolLabels = {}, turnBody = (text) => ({ text }) }) {
|
||
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)); }
|
||
}
|
||
|
||
async function load() {
|
||
clear(logEl);
|
||
let data;
|
||
try { data = await api.get(historyUrl); }
|
||
catch (e) { mount(logEl, el('p', { class: 'muted' }, 'Could not load history.')); return; }
|
||
for (const m of (data.messages || [])) {
|
||
const body = el('div', { class: 'md' }); body.innerHTML = renderMarkdown(m.body || '');
|
||
logEl.appendChild(turnEl(m.role, agentName, body));
|
||
}
|
||
logEl.scrollTop = logEl.scrollHeight;
|
||
}
|
||
|
||
async function send() {
|
||
const text = inputEl.value.trim();
|
||
if (!text) return;
|
||
inputEl.value = '';
|
||
logEl.appendChild(turnEl('user', agentName, document.createTextNode(text)));
|
||
const aiBody = el('div', { class: 'md' });
|
||
const aiTurn = turnEl('assistant', agentName, aiBody);
|
||
logEl.appendChild(aiTurn);
|
||
let acc = '';
|
||
try {
|
||
await streamTurn(turnUrl, turnBody(text), (e) => {
|
||
if (e.type === 'delta') { acc += e.text || ''; aiBody.innerHTML = renderMarkdown(acc); }
|
||
else if (e.type === 'tool') aiTurn.appendChild(chipEl(e.tool, e.status, toolLabels));
|
||
else if (e.type === 'draft' && showDrafts) aiTurn.appendChild(draftCardEl(e, resolveDraft));
|
||
else if (e.type === 'error') aiTurn.appendChild(el('div', { class: 'err' }, e.message || 'error'));
|
||
logEl.scrollTop = logEl.scrollHeight;
|
||
});
|
||
} catch (e) { aiTurn.appendChild(el('div', { class: 'err' }, 'stream failed: ' + e.message)); }
|
||
}
|
||
|
||
inputEl.addEventListener('keydown', (ev) => {
|
||
if (ev.key === 'Enter' && !ev.shiftKey) { ev.preventDefault(); send(); }
|
||
});
|
||
return { load, send };
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Commit** — `git add -A && git commit -m "feat(ui): extract reusable agent_chat panel"`
|
||
|
||
---
|
||
|
||
### Task 7: Frontend — point Dross's rail at `agent_chat`
|
||
|
||
**Files:**
|
||
- Modify: `public/components/rightrail.js`
|
||
|
||
- [ ] **Step 1: Refactor `rightrail.js`** to keep its rail chrome (toggle/collapse/header) but delegate chat to `wireAgentChat`. Replace the internal history/`streamTurn`/turn/chip/draft logic with a call to `wireAgentChat` using the Dross URLs:
|
||
|
||
```js
|
||
import { wireAgentChat } from './agent_chat.js';
|
||
// …inside initChat(spaceId), after building `log` + `input`:
|
||
const COMPANION_LABELS = { search: '🔍 searching', read: '📄 reading', context: '🧭 looking at this view', propose_change: '📝 drafting a change' };
|
||
const chat = wireAgentChat({
|
||
logEl: log, inputEl: input,
|
||
historyUrl: `/api/spaces/${spaceId}/companion`,
|
||
turnUrl: `/api/spaces/${spaceId}/companion/turn`,
|
||
agentName: 'Companion', showDrafts: true, toolLabels: COMPANION_LABELS,
|
||
turnBody: (text) => ({ text, view: state.view || null })
|
||
});
|
||
await chat.load();
|
||
```
|
||
Keep the `!spaceId` guard ("Open a Space to chat…") and the Space-change re-init. Remove the now-duplicated helper functions from `rightrail.js`.
|
||
|
||
- [ ] **Step 2: Manual verify** (after Task 9 deploy, or `node server.js` locally): open a Space → Dross rail loads history, a turn streams deltas + tool chips, a `propose_change` still shows an Approve/Reject card that resolves. (No automated test — vanilla no-build UI.)
|
||
|
||
- [ ] **Step 3: Commit** — `git add -A && git commit -m "refactor(ui): Dross rail uses agent_chat"`
|
||
|
||
---
|
||
|
||
### Task 8: Frontend — `#/sentinel` Yerin view + nav
|
||
|
||
**Files:**
|
||
- Create: `public/views/sentinel.js`
|
||
- Modify: `public/router.js`, `public/app.js`, `public/components/sidebar.js`
|
||
|
||
- [ ] **Step 1: Create `public/views/sentinel.js`**:
|
||
|
||
```js
|
||
import { el, mount } from '../dom.js';
|
||
import { wireAgentChat } from '../components/agent_chat.js';
|
||
|
||
const YERIN_LABELS = {
|
||
audit_log: '🗒️ reading the audit trail', agent_inventory: '👁️ reviewing agents',
|
||
pending_review: '⏳ checking the approval queue', resource_exposure: '🛡️ checking exposure',
|
||
token_audit: '🔑 auditing tokens'
|
||
};
|
||
|
||
export async function render(main) {
|
||
const log = el('div', { class: 'rail-log sentinel-log' });
|
||
const input = el('textarea', { class: 'rail-input', rows: 1, placeholder: 'Ask Yerin about the Void’s security…' });
|
||
mount(main,
|
||
el('h1', { class: 'view-h1' }, '◆ Sentinel — Yerin'),
|
||
el('p', { class: 'view-sub' }, 'Read-only security & observability. She watches, reports, and warns — she never acts.'),
|
||
el('div', { class: 'sentinel-chat' }, log, el('div', { class: 'rail-inputwrap' }, input)));
|
||
const chat = wireAgentChat({
|
||
logEl: log, inputEl: input,
|
||
historyUrl: '/api/security/yerin', turnUrl: '/api/security/yerin/turn',
|
||
agentName: 'Yerin', showDrafts: false, toolLabels: YERIN_LABELS
|
||
});
|
||
await chat.load();
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Register the route** — in `public/router.js` add to `ROUTES` (before `home`): `{ name: 'sentinel', re: /^\/sentinel$/, keys: [] },` and add `// #/sentinel Yerin security view` to the header comment.
|
||
|
||
- [ ] **Step 3: Register the view loader** — in `public/app.js` `VIEWS`: `sentinel: () => import('./views/sentinel.js'),`.
|
||
|
||
- [ ] **Step 4: Sidebar nav** — in `public/components/sidebar.js`, alongside the global links (near `navItem('Sacred Valley', '/sacred-valley')`), add `navItem('Sentinel', '/sentinel'),`.
|
||
|
||
- [ ] **Step 5: Manual verify** — nav to `#/sentinel`: Yerin view renders, a question streams deltas + security tool chips, NO approve/reject cards appear, history persists across reload. Dross rail still works on Space views.
|
||
|
||
- [ ] **Step 6: Commit** — `git add -A && git commit -m "feat(ui): Sentinel view — Yerin global security chat"`
|
||
|
||
---
|
||
|
||
### Task 9: Release alpha.15 + deploy
|
||
|
||
**Files:** `package.json`, `server.js`, `CHANGELOG.md`
|
||
|
||
- [ ] **Step 1: Bump** `package.json` + `server.js` `VERSION` → `2.0.0-alpha.15`.
|
||
- [ ] **Step 2: CHANGELOG** — prepend:
|
||
|
||
```markdown
|
||
## 2.0.0-alpha.15 — Yerin online (Agent Layer brick 1)
|
||
- **Yerin**, the read-only security agent, is now a usable agent: a global `#/sentinel` chat surface backed by her 5 security tools (audit/agents/pending/exposure/tokens). She investigates + reports; she never acts.
|
||
- Extracted the **shared agent-chat foundation** — `runAgentTurn` (backend) + `agent_chat` (frontend) — now used by both Dross and Yerin. Personas live in `lib/ai/personas/`.
|
||
```
|
||
|
||
- [ ] **Step 3: Full suite** — `npx vitest run` → all green (serial).
|
||
- [ ] **Step 4: Commit** — `git add -A && git commit -m "chore: release 2.0.0-alpha.15 (Yerin online)"`
|
||
- [ ] **Step 5: Deploy** — `bash deploy/push.sh` → `/health` reports `2.0.0-alpha.15`, `db_ok`. (No new migration; code-only.)
|
||
- [ ] **Step 6: Prod smoke** — `https://void2-app.hynesy.com` → `#/sentinel`, send Yerin a question, confirm streamed reply + tool chips; confirm Dross still works on a Space.
|
||
|
||
---
|
||
|
||
## Self-Review
|
||
|
||
**Spec coverage:** Shared backend service → Task 3; personas module → Task 2; Yerin global endpoint + `findOrCreateGlobal` → Tasks 1, 5; Dross refactor (regression) → Task 4; `agent_chat` extraction → Task 6; rail refactor → Task 7; `#/sentinel` view + nav → Task 8; read-only/no-drafts → Tasks 5 (`not /draft/`) + 8 (`showDrafts:false`); release/deploy → Task 9. All covered.
|
||
|
||
**Placeholder scan:** One intentional move-marker — `<<PASTE the exact current SYSTEM string from companion.js>>` in Task 2 (verbatim relocation of an existing constant, not new content).
|
||
|
||
**Type consistency:** `runAgentTurn({agent, persona, registryName, toolNames, spaceId, view, sessionId, resume, userText, claudeExe, home, onEvent})` — same shape in Task 3 def + Tasks 4/5 calls. `personaFor(slug)` keyed by agent slug (`companion`/`yerin`) — consistent Tasks 2/4/5. `wireAgentChat({logEl,inputEl,historyUrl,turnUrl,agentName,showDrafts,toolLabels,turnBody})` — same in Task 6 def + Tasks 7/8 calls. `findOrCreateGlobal(agent_id, actor)` — Tasks 1/5 consistent.
|