Void-Homelab/lib/api/routes/companion.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 COMPANION_SLUG = 'companion';

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 };
}

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),
  // nullish: the rail sends `view: null` when not on a specific entity.
  view: z.object({ entityType: z.string(), entityId: z.string() }).partial().nullish()
});

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

    // Resume the claude session if this conversation already had turns (the CLI
    // keys session history by --session-id; first turn creates it, rest --resume).
    const priorTurns = (await messages.listByConversation(convo.id)).length;
    const resume = priorTurns > 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';
    const draftIds = [];

    const companionTools = [
      'mcp__void__search',
      'mcp__void__read',
      'mcp__void__context',
      'mcp__void__propose_change'
    ];

    let result;
    try {
      // runAgentTurn builds the per-turn MCP config (default registry → companionRegistry)
      // and runs the claude turn; SSE + draft-parsing + persistence stay here.
      result = await runAgentTurn({
        agent,
        persona: personaFor(agent.slug),
        registryName: undefined,
        toolNames: companionTools,
        spaceId: req.params.space_id,
        view,
        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 === 'tool_result') {
            // Extract pending_change_id from the MCP tool result.
            //
            // companion-stdio.js returns:
            //   { content: [{ type:'text', text: JSON.stringify(result) }], structuredContent: result }
            //
            // claude_cli.js surfaces this as:
            //   { type:'tool_result', name, result: raw.content }
            //   where result = the content array: [{ type:'text', text:'...' }]
            //
            // Defensive parsing: try structuredContent first (future-proof), then
            // scan content array text blocks and JSON.parse them.
            // The CLI delivers an MCP tool_result `content` as a JSON STRING,
            // e.g. '{"pending_change_id":"...","applied":false,"summary":"..."}'.
            // Be defensive: also accept a content-block array or a structuredContent object.
            let parsed = null;
            const tryParse = (s) => { try { return JSON.parse(s); } catch { return null; } };
            try {
              if (typeof e.result === 'string') {
                parsed = tryParse(e.result);
              } else if (e.result?.structuredContent?.pending_change_id) {
                parsed = e.result.structuredContent;
              } else if (Array.isArray(e.result)) {
                for (const block of e.result) {
                  const candidate = block?.type === 'text' && block.text ? tryParse(block.text) : null;
                  if (candidate?.pending_change_id) { parsed = candidate; break; }
                }
              }
            } catch {
              // parsing failed — no draft to surface
            }

            if (parsed?.pending_change_id) {
              draftIds.push(parsed.pending_change_id);
              send('draft', {
                type: 'draft',
                pending_change_id: parsed.pending_change_id,
                summary: parsed.summary || 'a change'
              });
            }
          } else if (e.type === 'error') {
            send('error', { type: 'error', message: e.message });
          }
          // 'result' events are captured via the resolved return value; no SSE needed mid-stream.
        }
      });
    } catch (e) {
      send('error', { message: String(e?.message || e) });
      res.end();
      return;
    }

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

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