feat(api): conversations + messages routes

Add conversations CRUD-lite (list, create, get, PATCH status, PATCH
summary which flips status to summarized) and conversation-scoped
messages (append, list ordered by created_at).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

lib/api/index.js

@@ -13,6 +13,8 @@ import { router as refsRouter } from './routes/refs.js';
 import { router as resourcesRouter, spacesScopedRouter as resourcesBySpaceRouter } from './routes/resources.js';
 import { router as sourceDocsRouter, resourcesScopedRouter as sourceDocsByResourceRouter } from './routes/source_docs.js';
 import { router as agentsRouter, tokensRouter as agentTokensRouter } from './routes/agents.js';
+import { router as conversationsRouter } from './routes/conversations.js';
+import { conversationsScopedRouter as messagesByConvRouter } from './routes/messages.js';
 
 export function mountApi(app) {
   const api = Router();
@@ -33,6 +35,8 @@ export function mountApi(app) {
   api.use('/source-docs', sourceDocsRouter);
   api.use('/agents', agentsRouter);
   api.use('/agent-tokens', agentTokensRouter);
+  api.use('/conversations', conversationsRouter);
+  api.use('/conversations/:conversation_id/messages', messagesByConvRouter);
 
   api.use((_req, _res, next) => next(new NotFoundError('route not found')));
 

lib/api/routes/conversations.js

@@ -0,0 +1,65 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import * as repo from '../../db/repos/conversations.js';
+import { validate } from '../validate.js';
+import { parsePagination } from '../pagination.js';
+import { NotFoundError, asyncWrap } from '../errors.js';
+
+const STATUSES = ['open', 'summarized', 'archived'];
+
+const createSchema = z.object({
+  title: z.string().nullable().optional(),
+  agent_id: z.string().uuid().nullable().optional(),
+  participants: z.array(z.string()).optional(),
+  metadata: z.record(z.string(), z.any()).optional()
+});
+
+const statusSchema = z.object({ status: z.enum(STATUSES) });
+const summarySchema = z.object({ summary: z.string().min(1) });
+
+const idParams = z.object({ id: z.string().uuid() });
+
+export const router = Router();
+
+router.get('/',
+  validate({ query: z.object({ limit: z.string().optional(), offset: z.string().optional() }) }),
+  asyncWrap(async (req, res) => {
+    const { limit, offset } = parsePagination(req);
+    res.json(await repo.list({ limit, offset }));
+  })
+);
+
+router.post('/',
+  validate({ body: createSchema }),
+  asyncWrap(async (req, res) => {
+    const row = await repo.create(req.body, req.actor);
+    res.status(201).json(row);
+  })
+);
+
+router.get('/:id',
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    const row = await repo.getById(req.params.id);
+    if (!row) throw new NotFoundError('conversation not found');
+    res.json(row);
+  })
+);
+
+router.patch('/:id/status',
+  validate({ params: idParams, body: statusSchema }),
+  asyncWrap(async (req, res) => {
+    const existing = await repo.getById(req.params.id);
+    if (!existing) throw new NotFoundError('conversation not found');
+    res.json(await repo.setStatus(req.params.id, req.body.status, req.actor));
+  })
+);
+
+router.patch('/:id/summary',
+  validate({ params: idParams, body: summarySchema }),
+  asyncWrap(async (req, res) => {
+    const existing = await repo.getById(req.params.id);
+    if (!existing) throw new NotFoundError('conversation not found');
+    res.json(await repo.setSummary(req.params.id, req.body.summary));
+  })
+);

lib/api/routes/messages.js

@@ -0,0 +1,41 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import * as repo from '../../db/repos/messages.js';
+import * as conversations from '../../db/repos/conversations.js';
+import { validate } from '../validate.js';
+import { NotFoundError, ValidationError, asyncWrap } from '../errors.js';
+
+const appendSchema = z.object({
+  role: z.string().min(1).max(64),
+  body: z.string().min(1),
+  agent_id: z.string().uuid().nullable().optional(),
+  metadata: z.record(z.string(), z.any()).optional()
+});
+
+const convParams = z.object({ conversation_id: z.string().uuid() });
+
+export const conversationsScopedRouter = Router({ mergeParams: true });
+
+conversationsScopedRouter.get('/',
+  validate({ params: convParams,
+    query: z.object({ limit: z.string().optional() }) }),
+  asyncWrap(async (req, res) => {
+    const existing = await conversations.getById(req.params.conversation_id);
+    if (!existing) throw new NotFoundError('conversation not found');
+    const limit = req.validatedQuery.limit ? Number(req.validatedQuery.limit) : 1000;
+    if (!Number.isFinite(limit) || limit < 1 || limit > 5000) {
+      throw new ValidationError('limit must be 1..5000');
+    }
+    res.json(await repo.listByConversation(req.params.conversation_id, { limit }));
+  })
+);
+
+conversationsScopedRouter.post('/',
+  validate({ params: convParams, body: appendSchema }),
+  asyncWrap(async (req, res) => {
+    const existing = await conversations.getById(req.params.conversation_id);
+    if (!existing) throw new NotFoundError('conversation not found');
+    const row = await repo.append(req.params.conversation_id, req.body);
+    res.status(201).json(row);
+  })
+);

tests/api/conversations.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import request from 'supertest';
+import { setup } from './helpers.js';
+
+let app, ownerHeaders;
+beforeAll(async () => { ({ app, ownerHeaders } = await setup()); });
+
+describe('conversations + messages routes', () => {
+  it('POST creates and GET returns', async () => {
+    const c = await request(app).post('/api/conversations').set(ownerHeaders)
+      .send({ title: 'chat' });
+    expect(c.status).toBe(201);
+    const get = await request(app).get(`/api/conversations/${c.body.id}`).set(ownerHeaders);
+    expect(get.body.id).toBe(c.body.id);
+  });
+
+  it('append + list messages in order', async () => {
+    const c = await request(app).post('/api/conversations').set(ownerHeaders).send({});
+    await request(app).post(`/api/conversations/${c.body.id}/messages`).set(ownerHeaders)
+      .send({ role: 'user', body: 'one' });
+    await request(app).post(`/api/conversations/${c.body.id}/messages`).set(ownerHeaders)
+      .send({ role: 'assistant', body: 'two' });
+    const list = await request(app).get(`/api/conversations/${c.body.id}/messages`).set(ownerHeaders);
+    expect(list.body.map(m => m.body)).toEqual(['one', 'two']);
+  });
+
+  it('PATCH /:id/summary flips status to summarized', async () => {
+    const c = await request(app).post('/api/conversations').set(ownerHeaders).send({});
+    const res = await request(app).patch(`/api/conversations/${c.body.id}/summary`).set(ownerHeaders)
+      .send({ summary: 'tldr' });
+    expect(res.body.status).toBe('summarized');
+    expect(res.body.summary).toBe('tldr');
+  });
+
+  it('append on missing conv → 404', async () => {
+    const res = await request(app)
+      .post('/api/conversations/00000000-0000-0000-0000-000000000000/messages').set(ownerHeaders)
+      .send({ role: 'user', body: 'x' });
+    expect(res.status).toBe(404);
+  });
+});