@smartmemory/compose 0.1.0

package/server/agent-server.js

@@ -0,0 +1,290 @@
+/**
+ * Agent Server (Tier 1 — immortal, port 3003 during migration, then 3002)
+ *
+ * Replaces terminal-server.js. Uses @anthropic-ai/claude-agent-sdk instead of
+ * node-pty + tmux. Streams typed SDK messages via SSE to the browser.
+ * User input arrives via POST — SSE is the right transport for a unidirectional
+ * async iterator.
+ *
+ * Process isolation: this server only talks to api-server (3001) via SDK hooks.
+ * SessionManager and VisionServer require zero changes.
+ */
+
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import express from 'express';
+import cors from 'cors';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { requireSensitiveToken } from './security.js';
+import { HOOK_OPTIONS } from './agent-hooks.js';
+import { getTargetRoot, getDataDir } from './project-root.js';
+import { BuildStreamBridge } from './build-stream-bridge.js';
+import { CoalescingBuffer } from './coalescing-buffer.js';
+
+const _agentBuffer = new CoalescingBuffer((flushed) => {
+  if (flushed.agentMessage) {
+    for (const msg of flushed.agentMessage) {
+      _trackMessage(msg);
+      broadcast(msg);
+    }
+  }
+}, { intervalMs: 16 });
+_agentBuffer.register('agentMessage', 'append');
+
+const _recentMessages = [];
+const HYDRATE_LIMIT = 50;
+
+function _trackMessage(msg) {
+  _recentMessages.push(msg);
+  if (_recentMessages.length > HYDRATE_LIMIT) _recentMessages.shift();
+}
+
+export function getAgentSnapshot() {
+  return _recentMessages.length > 0 ? [..._recentMessages] : null;
+}
+
+const PORT = process.env.AGENT_PORT || 4002;
+const SETTINGS_FILE = path.join(getDataDir(), 'settings.json');
+
+function _readModelSetting() {
+  try {
+    const raw = readFileSync(SETTINGS_FILE, 'utf-8');
+    return JSON.parse(raw)?.models?.interactive || null;
+  } catch {
+    return null;
+  }
+}
+
+const app = express();
+app.use(cors({ origin: /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/ }));
+app.use(express.json());
+
+app.get('/api/health', (_req, res) => res.json({ ok: true }));
+
+// ---------------------------------------------------------------------------
+// Session state — one active SDK session at a time
+// ---------------------------------------------------------------------------
+
+/**
+ * Active session state:
+ *   id: string|null        — SDK session_id captured from init message
+ *   queryIter: Query|null  — SDK async iterator, has .interrupt() method
+ */
+let _session = { id: null, queryIter: null };
+
+/** SSE clients waiting for messages */
+const _sseClients = new Set();
+
+function broadcast(msg) {
+  const line = `data: ${JSON.stringify(msg)}\n\n`;
+  for (const client of _sseClients) {
+    try {
+      client.write(line);
+    } catch {
+      _sseClients.delete(client);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GET /api/agent/stream — SSE subscription
+// ---------------------------------------------------------------------------
+
+app.get('/api/agent/stream', (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('X-Accel-Buffering', 'no'); // disable nginx buffering if proxied
+  res.flushHeaders();
+
+  _sseClients.add(res);
+
+  const snapshot = getAgentSnapshot();
+  if (snapshot) {
+    res.write(`event: hydrate\ndata: ${JSON.stringify(snapshot)}\n\n`);
+  }
+
+  // Immediately tell the new client whether a session exists
+  if (_session.id) {
+    res.write(`data: ${JSON.stringify({
+      type: 'system', subtype: 'connected', sessionId: _session.id,
+    })}\n\n`);
+  }
+
+  req.on('close', () => _sseClients.delete(res));
+});
+
+// ---------------------------------------------------------------------------
+// POST /api/agent/session — create a fresh session
+// ---------------------------------------------------------------------------
+
+app.post('/api/agent/session', requireSensitiveToken, (req, res) => {
+  const { prompt = '' } = req.body || {};
+  if (!prompt.trim()) return res.status(400).json({ error: 'prompt is required' });
+
+  _killCurrentSession();
+
+  try {
+    const q = _startQuery(prompt, null);
+    _session = { id: null, queryIter: q };
+    _consumeStream(q);
+    res.json({ ok: true });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// POST /api/agent/message — send a follow-up message (resumes session)
+// ---------------------------------------------------------------------------
+
+app.post('/api/agent/message', requireSensitiveToken, (req, res) => {
+  const { prompt } = req.body || {};
+  if (!prompt?.trim()) return res.status(400).json({ error: 'prompt is required' });
+
+  const resumeId = _session.id;
+  _killCurrentSession();
+
+  try {
+    const q = _startQuery(prompt, resumeId);
+    _session = { id: resumeId, queryIter: q };
+    _consumeStream(q);
+    res.json({ ok: true, resumeSessionId: resumeId });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// POST /api/agent/interrupt — interrupt current query
+// ---------------------------------------------------------------------------
+
+app.post('/api/agent/interrupt', requireSensitiveToken, (req, res) => {
+  if (!_session.queryIter) {
+    return res.status(404).json({ error: 'No active query' });
+  }
+  try {
+    _session.queryIter.interrupt();
+
+    // COMP-AGT-1: Escalation — if not resolved within 5s, force-kill the session
+    const capturedIter = _session.queryIter;
+    setTimeout(() => {
+      if (_session.queryIter === capturedIter) {
+        console.log('[agent-server] Interrupt escalation: killing session after 5s timeout');
+        _killCurrentSession();
+      }
+    }, 5000);
+
+    res.json({ ok: true });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// GET /api/agent/session/status
+// ---------------------------------------------------------------------------
+
+app.get('/api/agent/session/status', (_req, res) => {
+  res.json({
+    active: !!_session.queryIter,
+    sessionId: _session.id || null,
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function _buildOptions(prompt, resumeId) {
+  return {
+    cwd: getTargetRoot(),
+    model: _readModelSetting() || 'claude-sonnet-4-6',
+    permissionMode: 'acceptEdits',
+    settingSources: ['project'],
+    tools: { type: 'preset', preset: 'claude_code' },
+    hooks: HOOK_OPTIONS,
+    ...(resumeId ? { resume: resumeId } : {}),
+  };
+}
+
+function _startQuery(prompt, resumeId) {
+  return query({ prompt, options: _buildOptions(prompt, resumeId) });
+}
+
+function _killCurrentSession() {
+  if (_session.queryIter) {
+    try { _session.queryIter.return(); } catch { /* ignore */ }
+  }
+  _session = { id: null, queryIter: null };
+  _recentMessages.length = 0;
+}
+
+async function _consumeStream(q) {
+  try {
+    for await (const msg of q) {
+      // Capture session_id from the init message so we can resume
+      if (msg.type === 'system' && msg.subtype === 'init') {
+        _session.id = msg.session_id;
+      }
+      _agentBuffer.put('agentMessage', msg);
+    }
+  } catch (err) {
+    if (err?.name !== 'AbortError') {
+      broadcast({ type: 'error', message: err.message || String(err) });
+    }
+  } finally {
+    // Signal completion to clients regardless of success/error
+    if (_session.queryIter === q) {
+      _session.queryIter = null;
+    }
+    // Keep _recentMessages populated after natural session end so clients
+    // reloading the tab post-turn can still hydrate recent history.
+    // Ring is cleared only on force-kill / new-session start in _killCurrentSession.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server startup
+// ---------------------------------------------------------------------------
+
+let serverListening = false;
+const server = http.createServer(app);
+
+// Build stream bridge — tails JSONL from CLI build, rebroadcasts via SSE
+const _bridge = new BuildStreamBridge(
+  path.join(getTargetRoot(), '.compose'),
+  broadcast
+);
+
+server.listen(PORT, '127.0.0.1', () => {
+  serverListening = true;
+  _bridge.start();
+  console.log(`Agent server running on http://127.0.0.1:${PORT}`);
+});
+
+function shutdown(sig) {
+  console.log(`[agent-server] ${sig}, shutting down`);
+  _agentBuffer.stop();
+  _bridge.stop();
+  _killCurrentSession();
+  server.close();
+  setTimeout(() => process.exit(0), 1000);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+process.on('uncaughtException', (err) => {
+  if (!serverListening && err.code === 'EADDRINUSE') {
+    console.error(`[agent-server] Port ${PORT} in use, exiting for supervisor retry`);
+    process.exit(1);
+  }
+  console.error('[agent-server] Uncaught exception (kept alive):', err.message);
+  console.error(err.stack);
+});
+
+process.on('unhandledRejection', (reason) => {
+  console.error('[agent-server] Unhandled rejection (kept alive):', reason);
+});

package/server/agent-spawn.js

@@ -0,0 +1,251 @@
+/**
+ * agent-spawn.js — Hidden Claude subagent spawn/poll routes.
+ *
+ * Routes: POST /api/agent/spawn, GET /api/agent/:id, GET /api/agents
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+import { getTargetRoot } from './project-root.js';
+import { gracefulKill } from './agent-health.js';
+
+const PROJECT_ROOT = getTargetRoot();
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach agent spawn/poll routes to an Express app.
+ * Each call creates an isolated agent registry — safe for multiple instances.
+ *
+ * @param {object} app — Express app
+ * @param {{ projectRoot: string, broadcastMessage: function, requireSensitiveToken: function }} deps
+ */
+function deriveAgentType(prompt) {
+  const lower = (prompt ?? '').toLowerCase();
+  if (lower.includes('explore') || lower.includes('find features') || lower.includes('map the architecture'))
+    return 'compose-explorer';
+  if (lower.includes('architect') || lower.includes('competing') || lower.includes('proposal'))
+    return 'compose-architect';
+  if (lower.includes('review') || lower.includes('codex'))
+    return 'codex';
+  return 'claude';
+}
+
+export function attachAgentSpawnRoutes(app, { projectRoot = PROJECT_ROOT, broadcastMessage, requireSensitiveToken, registry, sessionManager, healthMonitor, worktreeGC }) {
+  const _agents = new Map();
+  // POST /api/agent/spawn — spawn a hidden Claude subagent
+  app.post('/api/agent/spawn', requireSensitiveToken, (req, res) => {
+    const { prompt, id } = req.body || {};
+    if (!prompt || typeof prompt !== 'string') return res.status(400).json({ error: 'prompt is required and must be a string' });
+
+    const agentId = id || `agent-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+
+    if (_agents.has(agentId)) {
+      return res.status(409).json({ error: `Agent ${agentId} already running` });
+    }
+
+    const cleanEnv = { ...process.env, NO_COLOR: '1' };
+    delete cleanEnv.CLAUDECODE;
+
+    const proc = spawn('claude', [
+      '-p', prompt,
+      '--dangerously-skip-permissions',
+    ], {
+      cwd: projectRoot,
+      env: cleanEnv,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const agent = {
+      process: proc,
+      output: '',
+      stderr: '',
+      status: 'running',
+      prompt,
+      startedAt: new Date().toISOString(),
+    };
+    _agents.set(agentId, agent);
+
+    // Register with persistent registry + broadcast spawn event
+    const agentType = deriveAgentType(prompt);
+    const parentSessionId = sessionManager?.currentSession?.id ?? null;
+    if (registry) {
+      registry.register(agentId, { parentSessionId, agentType, prompt, pid: proc.pid });
+    }
+    broadcastMessage({
+      type: 'agentSpawned',
+      agentId,
+      parentSessionId,
+      agentType,
+      prompt: prompt.slice(0, 200),
+      startedAt: agent.startedAt,
+    });
+    broadcastMessage({
+      type: 'agentRelay',
+      fromAgentId: parentSessionId || 'session',
+      toAgentId: agentId,
+      direction: 'dispatch',
+      messagePreview: (prompt || '').slice(0, 80),
+      timestamp: new Date().toISOString(),
+    });
+
+    proc.stdout.on('data', (chunk) => {
+      agent.output += chunk.toString();
+    });
+
+    proc.stderr.on('data', (chunk) => {
+      agent.stderr += chunk.toString();
+    });
+
+    // COMP-AGT-1: Wire health monitor after stdout/stderr listeners
+    if (healthMonitor) healthMonitor.track(agentId, proc);
+
+    proc.on('close', (code) => {
+      // COMP-AGT-1: Untrack from health monitor, preserve terminal reason
+      if (healthMonitor) {
+        const terminalReason = healthMonitor.getTerminalReason(agentId);
+        healthMonitor.untrack(agentId);
+        if (terminalReason) {
+          agent.status = 'killed';
+          agent.terminalReason = terminalReason;
+          agent.exitCode = code;
+          if (registry) {
+            registry.updateStatus(agentId, 'killed', terminalReason);
+          }
+          broadcastMessage({
+            type: 'agentComplete',
+            agentId,
+            agentType,
+            status: 'killed',
+            terminalReason,
+            output: agent.output,
+          });
+          broadcastMessage({
+            type: 'agentRelay',
+            fromAgentId: agentId,
+            toAgentId: parentSessionId || 'session',
+            direction: 'result',
+            messagePreview: `Killed: ${terminalReason}`,
+            timestamp: new Date().toISOString(),
+          });
+          return; // skip normal close handling
+        }
+      }
+      agent.status = code === 0 ? 'complete' : 'failed';
+      agent.exitCode = code;
+      if (registry) {
+        registry.complete(agentId, { status: agent.status, exitCode: code });
+      }
+      broadcastMessage({
+        type: 'agentComplete',
+        agentId,
+        agentType,
+        status: agent.status,
+        output: agent.output,
+      });
+      broadcastMessage({
+        type: 'agentRelay',
+        fromAgentId: agentId,
+        toAgentId: parentSessionId || 'session',
+        direction: 'result',
+        messagePreview: (agent.output || '').slice(0, 80),
+        timestamp: new Date().toISOString(),
+      });
+    });
+
+    proc.on('error', (err) => {
+      agent.status = 'failed';
+      agent.stderr += err.message;
+      console.error(`[vision] Agent ${agentId} spawn error:`, err.message);
+    });
+
+    console.log(`[vision] Agent ${agentId} spawned (PID ${proc.pid})`);
+    res.status(201).json({ agentId, pid: proc.pid, status: 'running' });
+  });
+
+  // GET /api/agent/:id — poll agent status + output
+  app.get('/api/agent/:id', (req, res) => {
+    const agent = _agents.get(req.params.id);
+    if (!agent) return res.status(404).json({ error: 'Agent not found' });
+    res.json({
+      agentId: req.params.id,
+      status: agent.status,
+      output: agent.output,
+      stderr: agent.stderr,
+      exitCode: agent.exitCode,
+      startedAt: agent.startedAt,
+    });
+  });
+
+  // GET /api/agents — list all agents
+  app.get('/api/agents', (_req, res) => {
+    const agents = [];
+    for (const [id, agent] of _agents) {
+      agents.push({
+        agentId: id,
+        status: agent.status,
+        startedAt: agent.startedAt,
+        outputLength: agent.output.length,
+      });
+    }
+    res.json({ agents });
+  });
+
+  // GET /api/agents/tree — agent hierarchy for current session
+  app.get('/api/agents/tree', (_req, res) => {
+    if (!registry) return res.json({ agents: [] });
+    const parentId = sessionManager?.currentSession?.id ?? null;
+    const agents = parentId ? registry.getChildren(parentId) : registry.getAll();
+    res.json({ sessionId: parentId, agents });
+  });
+
+  // POST /api/agent/:id/stop — COMP-AGT-1: graceful stop (SIGTERM → 5s → SIGKILL)
+  app.post('/api/agent/:id/stop', requireSensitiveToken, (req, res) => {
+    const agentId = req.params.id;
+    const agent = _agents.get(agentId);
+
+    // For SDK sessions, proxy to agent-server's interrupt endpoint
+    const currentSessionId = sessionManager?.currentSession?.id ?? null;
+    if (agentId === currentSessionId) {
+      const agentPort = process.env.AGENT_PORT || 4002;
+      const headers = { 'Content-Type': 'application/json' };
+      if (process.env.COMPOSE_API_TOKEN) headers['x-compose-token'] = process.env.COMPOSE_API_TOKEN;
+      fetch(`http://127.0.0.1:${agentPort}/api/agent/interrupt`, {
+        method: 'POST',
+        headers,
+      }).then(r => {
+          if (!r.ok) {
+            return res.status(r.status).json({ ok: false, error: `Interrupt proxy failed: ${r.status}` });
+          }
+          return r.json().then(data => res.json({ ok: true, proxied: true, ...data }));
+        })
+        .catch(err => res.status(502).json({ error: `Interrupt proxy failed: ${err.message}` }));
+      return;
+    }
+
+    if (!agent) return res.status(404).json({ error: 'Agent not found' });
+    if (agent.status !== 'running') return res.json({ ok: true, status: agent.status, note: 'already stopped' });
+
+    // Set terminal reason before killing
+    if (healthMonitor) healthMonitor.setTerminalReason(agentId, 'manual_stop');
+
+    gracefulKill(agent.process);
+
+    res.json({ ok: true, agentId, action: 'SIGTERM sent, SIGKILL in 5s if needed' });
+  });
+
+  // POST /api/agent/gc — COMP-AGT-1: trigger worktree garbage collection
+  app.post('/api/agent/gc', requireSensitiveToken, async (_req, res) => {
+    if (!worktreeGC) return res.status(503).json({ error: 'WorktreeGC not available' });
+    try {
+      const removed = await worktreeGC.runNow();
+      broadcastMessage({ type: 'agentGC', removed, timestamp: new Date().toISOString() });
+      res.json({ ok: true, removed });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+}

package/server/agent-templates.js

@@ -0,0 +1,77 @@
+/**
+ * agent-templates.js — Agent capability profiles for COMP-AGENT-CAPS.
+ *
+ * Defines which tools each agent role is allowed or denied.
+ * Violations are informational in v1 — logged but not blocking.
+ */
+
+/**
+ * @type {Map<string, {allowedTools: string[]|null, disallowedTools: string[]|null, description: string}>}
+ */
+export const AGENT_TEMPLATES = new Map([
+  ['read-only-reviewer', {
+    allowedTools: ['Read', 'Grep', 'Glob', 'Agent'],
+    disallowedTools: ['Edit', 'Write', 'Bash'],
+    description: 'Read-only review agent',
+  }],
+  ['read-only-researcher', {
+    allowedTools: ['Read', 'Grep', 'Glob', 'Agent', 'WebSearch', 'WebFetch'],
+    disallowedTools: ['Edit', 'Write', 'Bash'],
+    description: 'Read-only research agent with web access',
+  }],
+  ['implementer', {
+    allowedTools: null,
+    disallowedTools: null,
+    description: 'Full access implementation agent',
+  }],
+  ['orchestrator', {
+    allowedTools: ['Read', 'Grep', 'Glob', 'Agent', 'Bash'],
+    disallowedTools: ['Edit', 'Write'],
+    description: 'Meta-config orchestrator',
+  }],
+  ['security-auditor', {
+    allowedTools: ['Read', 'Grep', 'Glob', 'Bash'],
+    disallowedTools: ['Edit', 'Write'],
+    description: 'Security audit agent',
+  }],
+]);
+
+/**
+ * Resolve a template by name.
+ * @param {string|null|undefined} templateName
+ * @returns {{ allowedTools: string[]|null, disallowedTools: string[]|null, description: string }|null}
+ *   Returns null if templateName is unknown — callers fall back to no restrictions.
+ */
+export function resolveTemplate(templateName) {
+  if (!templateName) return null;
+  return AGENT_TEMPLATES.get(templateName) ?? null;
+}
+
+/**
+ * Check whether a given tool is allowed under a template.
+ * @param {{ allowedTools: string[]|null, disallowedTools: string[]|null }|null} template
+ * @param {string} toolName
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+export function validateCapabilities(template, toolName) {
+  if (!template) {
+    return { allowed: true, reason: 'No template — all tools permitted' };
+  }
+
+  const { allowedTools, disallowedTools } = template;
+
+  // Explicit deny list takes priority
+  if (disallowedTools && disallowedTools.includes(toolName)) {
+    return { allowed: false, reason: `Tool "${toolName}" is in disallowedTools` };
+  }
+
+  // If allowedTools is set, tool must appear in it
+  if (allowedTools !== null) {
+    if (allowedTools.includes(toolName)) {
+      return { allowed: true, reason: `Tool "${toolName}" is in allowedTools` };
+    }
+    return { allowed: false, reason: `Tool "${toolName}" is not in allowedTools` };
+  }
+
+  return { allowed: true, reason: 'No restrictions defined' };
+}