claude-multi-session 1.0.0

package/src/mcp-server.js

@@ -0,0 +1,808 @@
+/**
+ * MCP Server — Model Context Protocol server for claude-multi-session.
+ *
+ * This turns the multi-session system into NATIVE Claude Code tools.
+ * Instead of Claude running CLI commands via Bash, it calls tools directly:
+ *
+ *   mcp__multi-session__spawn_session
+ *   mcp__multi-session__send_message
+ *   mcp__multi-session__delegate_task
+ *   etc.
+ *
+ * Protocol: JSON-RPC 2.0 over stdio (newline-delimited JSON).
+ * Zero dependencies — implements the MCP protocol manually.
+ *
+ * How MCP works:
+ *   1. Claude Code starts this server as a child process
+ *   2. Claude sends JSON-RPC requests on stdin
+ *   3. Server responds with JSON-RPC responses on stdout
+ *   4. All debug/log output goes to stderr (never stdout)
+ *
+ * JSON-RPC methods handled:
+ *   - initialize         → capability negotiation
+ *   - notifications/initialized → client confirms init (no response)
+ *   - tools/list         → return available tools
+ *   - tools/call         → execute a tool and return result
+ */
+
+const readline = require('readline');
+const SessionManager = require('./manager');
+const Delegate = require('./delegate');
+
+// =============================================================================
+// Server State — persists across all tool calls
+// =============================================================================
+
+// Single SessionManager instance for the entire MCP server lifetime.
+// This means spawned sessions stay alive between tool calls — much more
+// efficient than the CLI where each command creates a new manager.
+const manager = new SessionManager();
+
+// Track delegates per session (for continue/finish/abort)
+const delegates = new Map();
+
+// =============================================================================
+// Tool Definitions — these appear in Claude's tool list
+// =============================================================================
+
+const TOOLS = [
+  // ── Session Management ──────────────────────────────────────────────────
+  {
+    name: 'spawn_session',
+    description:
+      'Start a new Claude Code session. Spawns a long-lived streaming process. ' +
+      'Optionally sends an initial prompt and returns the response. ' +
+      'The session stays alive for follow-up messages via send_message.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:           { type: 'string', description: 'Unique session name (e.g. "fix-auth", "build-login")' },
+        prompt:         { type: 'string', description: 'Initial prompt to send (optional — if omitted, session starts idle)' },
+        model:          { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model to use (default: sonnet)' },
+        work_dir:       { type: 'string', description: 'Working directory for the session (default: current directory)' },
+        permission_mode:{ type: 'string', enum: ['default', 'acceptEdits', 'bypassPermissions', 'plan'], description: 'Permission mode (default: default)' },
+        allowed_tools:  { type: 'array', items: { type: 'string' }, description: 'Restrict to specific tools (e.g. ["Read", "Glob", "Grep"])' },
+        system_prompt:  { type: 'string', description: 'Text to append to system prompt' },
+        max_budget:     { type: 'number', description: 'Max budget in USD for the session' },
+        agent:          { type: 'string', description: 'Agent to use for the session' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'send_message',
+    description:
+      'Send a follow-up message to an existing session. ' +
+      'The session keeps full conversation context — no restart needed. ' +
+      'If the session was stopped, it auto-resumes using the saved session ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:    { type: 'string', description: 'Session name' },
+        message: { type: 'string', description: 'Message to send' },
+      },
+      required: ['name', 'message'],
+    },
+  },
+
+  {
+    name: 'resume_session',
+    description:
+      'Resume a stopped/paused session. Uses --resume with the saved session ID ' +
+      'to restore the full conversation. Optionally sends a message immediately.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:    { type: 'string', description: 'Session name to resume' },
+        message: { type: 'string', description: 'Optional message to send after resuming' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'pause_session',
+    description: 'Pause a session. The process stays alive but no messages are accepted until resumed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to pause' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'fork_session',
+    description:
+      'Fork a session into a new one. The new session starts with all the parent\'s ' +
+      'conversation context. Useful for trying different approaches from the same starting point.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:     { type: 'string', description: 'Source session name to fork from' },
+        new_name: { type: 'string', description: 'Name for the new forked session' },
+        message:  { type: 'string', description: 'Initial message for the fork (default: "Continue from the forked conversation.")' },
+        model:    { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model for the forked session' },
+      },
+      required: ['name', 'new_name'],
+    },
+  },
+
+  {
+    name: 'stop_session',
+    description: 'Gracefully stop a session. Saves state so it can be resumed later with resume_session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to stop' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'kill_session',
+    description: 'Force kill a session immediately. Use when stop_session is not working.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to kill' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Information ─────────────────────────────────────────────────────────
+  {
+    name: 'get_session_status',
+    description: 'Get detailed status of a session — status, model, cost, turns, interactions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'get_last_output',
+    description: 'Get the last response text from a session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'list_sessions',
+    description:
+      'List all sessions (both alive and stopped). Shows name, status, model, cost, turns. ' +
+      'Optionally filter by status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', enum: ['ready', 'paused', 'stopped', 'killed', 'busy'], description: 'Filter by status (optional)' },
+      },
+    },
+  },
+
+  {
+    name: 'get_history',
+    description: 'Get full interaction history (all prompts and responses) for a session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'delete_session',
+    description: 'Permanently delete a session and all its data. Cannot be undone.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Session name to delete' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Delegate (Control Loop + Safety) ────────────────────────────────────
+  {
+    name: 'delegate_task',
+    description:
+      'Smart task delegation with control loop and safety net. ' +
+      'Spawns a child session, sends the task, monitors for issues ' +
+      '(permission denials, cost overruns, turn limits), and returns structured output. ' +
+      'Use this for autonomous task execution with safety guardrails. ' +
+      'After delegation, use continue_task to send corrections if the result is not satisfactory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:          { type: 'string', description: 'Unique name for this delegated task' },
+        task:          { type: 'string', description: 'Task description for the child session' },
+        model:         { type: 'string', enum: ['sonnet', 'opus', 'haiku'], description: 'Model to use (default: sonnet)' },
+        preset:        { type: 'string', enum: ['read-only', 'review', 'edit', 'full', 'plan'], description: 'Permission preset (default: edit)' },
+        max_cost:      { type: 'number', description: 'Max cost in USD before auto-kill (default: 2.00)' },
+        max_turns:     { type: 'number', description: 'Max agent turns before auto-kill (default: 50)' },
+        context:       { type: 'string', description: 'Extra context to prepend to the task' },
+        work_dir:      { type: 'string', description: 'Working directory for the child session' },
+        system_prompt: { type: 'string', description: 'Text to append to system prompt' },
+        agent:         { type: 'string', description: 'Agent to use' },
+        safety:        { type: 'boolean', description: 'Enable safety net (default: true). Set false to disable cost/turn/path limits.' },
+      },
+      required: ['name', 'task'],
+    },
+  },
+
+  {
+    name: 'continue_task',
+    description:
+      'Send a follow-up correction or instruction to a delegated task. ' +
+      'The child session retains its full conversation memory — it remembers ' +
+      'what it did, what files it touched, and what the original task was. ' +
+      'Use this to correct mistakes, request changes, or add requirements.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name:    { type: 'string', description: 'Name of the delegated task to continue' },
+        message: { type: 'string', description: 'Follow-up instruction or correction' },
+      },
+      required: ['name', 'message'],
+    },
+  },
+
+  {
+    name: 'finish_task',
+    description: 'Finish a delegated task — stop the session cleanly. Call this when the task result is satisfactory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name of the delegated task to finish' },
+      },
+      required: ['name'],
+    },
+  },
+
+  {
+    name: 'abort_task',
+    description: 'Abort a delegated task immediately — force kill the session. Use when the task is going off track and corrections are not working.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name of the delegated task to abort' },
+      },
+      required: ['name'],
+    },
+  },
+
+  // ── Batch ───────────────────────────────────────────────────────────────
+  {
+    name: 'batch_spawn',
+    description:
+      'Spawn multiple sessions in parallel. Each session gets its own name, prompt, and model. ' +
+      'Returns results for all sessions. Use for parallel task execution.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessions: {
+          type: 'array',
+          description: 'Array of session specs to spawn in parallel',
+          items: {
+            type: 'object',
+            properties: {
+              name:   { type: 'string', description: 'Session name' },
+              prompt: { type: 'string', description: 'Initial prompt' },
+              model:  { type: 'string', description: 'Model to use' },
+            },
+            required: ['name', 'prompt'],
+          },
+        },
+      },
+      required: ['sessions'],
+    },
+  },
+];
+
+// =============================================================================
+// Tool Handlers — execute each tool and return result
+// =============================================================================
+
+/**
+ * Execute a tool by name with given arguments.
+ * Returns { content: [{ type: "text", text: "..." }], isError?: true }
+ */
+async function executeTool(toolName, args) {
+  try {
+    switch (toolName) {
+      // ── Session Management ────────────────────────────────────────────
+      case 'spawn_session':
+        return await handleSpawn(args);
+      case 'send_message':
+        return await handleSend(args);
+      case 'resume_session':
+        return await handleResume(args);
+      case 'pause_session':
+        return handlePause(args);
+      case 'fork_session':
+        return await handleFork(args);
+      case 'stop_session':
+        return handleStop(args);
+      case 'kill_session':
+        return handleKill(args);
+
+      // ── Information ───────────────────────────────────────────────────
+      case 'get_session_status':
+        return handleStatus(args);
+      case 'get_last_output':
+        return handleLastOutput(args);
+      case 'list_sessions':
+        return handleList(args);
+      case 'get_history':
+        return handleHistory(args);
+      case 'delete_session':
+        return handleDelete(args);
+
+      // ── Delegate ──────────────────────────────────────────────────────
+      case 'delegate_task':
+        return await handleDelegate(args);
+      case 'continue_task':
+        return await handleContinue(args);
+      case 'finish_task':
+        return handleFinish(args);
+      case 'abort_task':
+        return handleAbort(args);
+
+      // ── Batch ─────────────────────────────────────────────────────────
+      case 'batch_spawn':
+        return await handleBatch(args);
+
+      default:
+        return errorResult(`Unknown tool: ${toolName}`);
+    }
+  } catch (err) {
+    return errorResult(err.message);
+  }
+}
+
+// ── Session Handlers ──────────────────────────────────────────────────────
+
+async function handleSpawn(args) {
+  const { session, response } = await manager.spawn(args.name, {
+    prompt: args.prompt,
+    model: args.model,
+    workDir: args.work_dir,
+    permissionMode: args.permission_mode,
+    allowedTools: args.allowed_tools,
+    systemPrompt: args.system_prompt,
+    maxBudget: args.max_budget,
+    agent: args.agent,
+  });
+
+  const result = {
+    session_name: session.name,
+    status: session.status,
+    model: session.model,
+    session_id: session.id,
+  };
+
+  if (response) {
+    result.response = response.text;
+    result.cost = response.cost;
+    result.turns = response.turns;
+    result.duration_ms = response.duration;
+  } else {
+    result.message = 'Session started (idle). Send a message with send_message.';
+  }
+
+  return textResult(JSON.stringify(result, null, 2));
+}
+
+async function handleSend(args) {
+  // Auto-resume if session is not alive
+  if (!manager.sessions.has(args.name)) {
+    log(`Session "${args.name}" not alive. Auto-resuming...`);
+    const response = await manager.resume(args.name, args.message);
+    return textResult(JSON.stringify({
+      session_name: args.name,
+      auto_resumed: true,
+      response: response?.text || '',
+      cost: response?.cost || 0,
+      turns: response?.turns || 0,
+      duration_ms: response?.duration || 0,
+    }, null, 2));
+  }
+
+  const response = await manager.send(args.name, args.message);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    response: response.text,
+    cost: response.cost,
+    turns: response.turns,
+    duration_ms: response.duration,
+  }, null, 2));
+}
+
+async function handleResume(args) {
+  const response = await manager.resume(args.name, args.message);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'resumed',
+    response: response?.text || null,
+    cost: response?.cost || 0,
+    turns: response?.turns || 0,
+  }, null, 2));
+}
+
+function handlePause(args) {
+  manager.pause(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'paused',
+  }, null, 2));
+}
+
+async function handleFork(args) {
+  const { session, response } = await manager.fork(args.name, args.new_name, {
+    message: args.message,
+    model: args.model,
+  });
+
+  return textResult(JSON.stringify({
+    source: args.name,
+    forked_as: args.new_name,
+    status: session.status,
+    response: response?.text || '',
+    cost: response?.cost || 0,
+    turns: response?.turns || 0,
+  }, null, 2));
+}
+
+function handleStop(args) {
+  manager.stop(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'stopped',
+    message: 'Session stopped. Can be resumed later with resume_session.',
+  }, null, 2));
+}
+
+function handleKill(args) {
+  manager.kill(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'killed',
+  }, null, 2));
+}
+
+// ── Information Handlers ──────────────────────────────────────────────────
+
+function handleStatus(args) {
+  const info = manager.status(args.name);
+  return textResult(JSON.stringify({
+    name: info.name,
+    status: info.status,
+    model: info.model,
+    session_id: info.claudeSessionId || info.id,
+    work_dir: info.workDir,
+    total_cost: info.totalCostUsd || 0,
+    total_turns: info.totalTurns || 0,
+    interactions: info.interactionCount || (info.interactions || []).length,
+    pid: info.pid || null,
+  }, null, 2));
+}
+
+function handleLastOutput(args) {
+  const last = manager.lastOutput(args.name);
+  if (!last) {
+    return textResult(JSON.stringify({ session_name: args.name, output: null, message: 'No output yet.' }, null, 2));
+  }
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    prompt: last.prompt,
+    response: last.response,
+    cost: last.cost,
+    timestamp: last.timestamp,
+  }, null, 2));
+}
+
+function handleList(args) {
+  const sessions = manager.list(args.status);
+  const summary = sessions.map(s => ({
+    name: s.name,
+    status: s.status,
+    model: s.model,
+    total_cost: s.totalCostUsd || 0,
+    total_turns: s.totalTurns || 0,
+    interactions: s.interactionCount || (s.interactions || []).length,
+  }));
+  return textResult(JSON.stringify({ total: summary.length, sessions: summary }, null, 2));
+}
+
+function handleHistory(args) {
+  const hist = manager.history(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    interaction_count: hist.length,
+    interactions: hist.map((h, i) => ({
+      index: i,
+      prompt: h.prompt,
+      response: h.response,
+      cost: h.cost,
+      turns: h.turns,
+      duration_ms: h.duration,
+      timestamp: h.timestamp,
+    })),
+  }, null, 2));
+}
+
+function handleDelete(args) {
+  manager.delete(args.name);
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'deleted',
+    message: 'Session permanently deleted.',
+  }, null, 2));
+}
+
+// ── Delegate Handlers ─────────────────────────────────────────────────────
+
+async function handleDelegate(args) {
+  // Create or reuse a delegate instance for this session
+  let delegate = delegates.get(args.name);
+  if (!delegate) {
+    delegate = new Delegate(manager);
+    delegates.set(args.name, delegate);
+  }
+
+  const result = await delegate.run(args.name, {
+    task: args.task,
+    model: args.model,
+    preset: args.preset,
+    workDir: args.work_dir,
+    maxCost: args.max_cost,
+    maxTurns: args.max_turns,
+    context: args.context,
+    systemPrompt: args.system_prompt,
+    agent: args.agent,
+    safety: args.safety,
+  });
+
+  return textResult(JSON.stringify(result, null, 2));
+}
+
+async function handleContinue(args) {
+  // Get or create delegate for this session
+  let delegate = delegates.get(args.name);
+  if (!delegate) {
+    delegate = new Delegate(manager);
+    delegates.set(args.name, delegate);
+  }
+
+  const result = await delegate.continue(args.name, args.message);
+  return textResult(JSON.stringify(result, null, 2));
+}
+
+function handleFinish(args) {
+  const delegate = delegates.get(args.name);
+  if (delegate) {
+    delegate.finish(args.name);
+    delegates.delete(args.name);
+  } else {
+    // No delegate — just stop the session
+    try { manager.stop(args.name); } catch (e) {}
+  }
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'finished',
+    message: 'Task finished. Session stopped.',
+  }, null, 2));
+}
+
+function handleAbort(args) {
+  const delegate = delegates.get(args.name);
+  if (delegate) {
+    delegate.abort(args.name);
+    delegates.delete(args.name);
+  } else {
+    try { manager.kill(args.name); } catch (e) {}
+  }
+  return textResult(JSON.stringify({
+    session_name: args.name,
+    status: 'aborted',
+    message: 'Task aborted. Session killed.',
+  }, null, 2));
+}
+
+// ── Batch Handler ─────────────────────────────────────────────────────────
+
+async function handleBatch(args) {
+  const results = await manager.batch(args.sessions);
+  const summary = results.map(r => ({
+    name: r.session?.name || 'unknown',
+    status: r.error ? 'failed' : 'completed',
+    response: r.response?.text || null,
+    cost: r.response?.cost || 0,
+    error: r.error || null,
+  }));
+  return textResult(JSON.stringify({ total: summary.length, results: summary }, null, 2));
+}
+
+// =============================================================================
+// Result Helpers
+// =============================================================================
+
+function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function errorResult(message) {
+  return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+}
+
+// =============================================================================
+// MCP Protocol Handler — JSON-RPC 2.0 over stdio
+// =============================================================================
+
+/**
+ * Log to stderr (NEVER stdout — stdout is for MCP protocol only).
+ */
+function log(msg) {
+  process.stderr.write(`[multi-session-mcp] ${msg}\n`);
+}
+
+/**
+ * Send a JSON-RPC response on stdout.
+ */
+function sendResponse(id, result) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, result });
+  process.stdout.write(msg + '\n');
+}
+
+/**
+ * Send a JSON-RPC error on stdout.
+ */
+function sendError(id, code, message) {
+  const msg = JSON.stringify({
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  });
+  process.stdout.write(msg + '\n');
+}
+
+/**
+ * Handle an incoming JSON-RPC message.
+ */
+async function handleMessage(message) {
+  const { id, method, params } = message;
+
+  switch (method) {
+    // ── Initialize ────────────────────────────────────────────────────
+    case 'initialize':
+      sendResponse(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'claude-multi-session',
+          version: '1.0.0',
+        },
+      });
+      break;
+
+    // ── Initialized notification (no response needed) ─────────────────
+    case 'notifications/initialized':
+      log('Client initialized.');
+      break;
+
+    // ── List tools ────────────────────────────────────────────────────
+    case 'tools/list':
+      sendResponse(id, { tools: TOOLS });
+      break;
+
+    // ── Call a tool ───────────────────────────────────────────────────
+    case 'tools/call':
+      if (!params || !params.name) {
+        sendError(id, -32602, 'Missing tool name');
+        break;
+      }
+      try {
+        const result = await executeTool(params.name, params.arguments || {});
+        sendResponse(id, result);
+      } catch (err) {
+        sendResponse(id, errorResult(err.message));
+      }
+      break;
+
+    // ── Ping ──────────────────────────────────────────────────────────
+    case 'ping':
+      sendResponse(id, {});
+      break;
+
+    // ── Unknown method ────────────────────────────────────────────────
+    default:
+      if (id !== undefined) {
+        sendError(id, -32601, `Method not found: ${method}`);
+      }
+      // Notifications (no id) are silently ignored
+      break;
+  }
+}
+
+// =============================================================================
+// Start Server — read from stdin, write to stdout
+// =============================================================================
+
+function startServer() {
+  log('Starting MCP server...');
+
+  // Read newline-delimited JSON from stdin
+  const rl = readline.createInterface({
+    input: process.stdin,
+    terminal: false,
+  });
+
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (e) {
+      log(`Failed to parse message: ${e.message}`);
+      // Send parse error if we can extract an id
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: 'Parse error' },
+      }) + '\n');
+      return;
+    }
+
+    // Validate JSON-RPC 2.0 format
+    if (message.jsonrpc !== '2.0') {
+      log(`Invalid JSON-RPC version: ${message.jsonrpc}`);
+      if (message.id !== undefined) {
+        sendError(message.id, -32600, 'Invalid Request: must use jsonrpc 2.0');
+      }
+      return;
+    }
+
+    await handleMessage(message);
+  });
+
+  rl.on('close', () => {
+    log('stdin closed. Shutting down...');
+    // Clean up — stop all live sessions
+    manager.stopAll();
+    process.exit(0);
+  });
+
+  // Handle process signals gracefully
+  process.on('SIGTERM', () => {
+    log('SIGTERM received. Shutting down...');
+    manager.stopAll();
+    process.exit(0);
+  });
+
+  process.on('SIGINT', () => {
+    log('SIGINT received. Shutting down...');
+    manager.stopAll();
+    process.exit(0);
+  });
+
+  log('MCP server ready. Waiting for messages...');
+}
+
+module.exports = { startServer, TOOLS, executeTool };