Void-Homelab/lib/api/routes/companion.js

import { Router } from 'express';
import { z } from 'zod';
import { fileURLToPath } from 'url';
import { writeFile, unlink } from 'fs/promises';
import { join } from 'path';
import { tmpdir } from 'os';
import { randomUUID } from 'crypto';
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 { runClaudeTurn } from '../../ai/claude_cli.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.`;

/** Absolute path to the companion MCP stdio server. */
const COMPANION_STDIO_PATH = fileURLToPath(
  new URL('../../mcp/companion-stdio.js', import.meta.url)
);

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`);

    // Write a per-turn MCP config temp file declaring the companion stdio server.
    // The stdio child is spawned by `claude`; pass the DB/Ollama connection env
    // explicitly so the tools work regardless of how claude propagates env to
    // MCP children (don't rely on inheritance or cwd-based dotenv).
    const mcpConfigPath = join(tmpdir(), `void-mcp-${randomUUID()}.json`);
    const agentActor = {
      kind: 'agent',
      id: agent.id,
      capabilities: agent.capabilities,
      scopes: agent.scopes
    };
    const mcpConfig = {
      mcpServers: {
        void: {
          // Absolute node path: claude resolves `command` against the MCP child's
          // env (which has no PATH), so a bare 'node' fails to spawn ("status:failed").
          command: process.execPath,
          args: [COMPANION_STDIO_PATH],
          env: {
            VOID_SPACE_ID: req.params.space_id,
            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));

    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 {
      result = await runClaudeTurn({
        sessionId: convo.id,
        resume,
        systemPrompt: SYSTEM,
        userText: text,
        mcpConfigPath,
        // `tools` restricts the session to ONLY our tools (no built-in Bash/Read/…);
        // `allowedTools` auto-approves them in non-interactive (--print) mode.
        tools: companionTools,
        allowedTools: companionTools,
        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();
      // Clean up temp file even on error
      unlink(mcpConfigPath).catch(() => {});
      return;
    }

    // Clean up the temp MCP config file
    unlink(mcpConfigPath).catch(() => {});

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