claude-simple 0.2.9 → 0.2.11

package/src/app.js

@@ -14,6 +14,8 @@ import { fileURLToPath } from 'url';
 import { runClaude } from './agents/claude.js';
 import { runCodex } from './agents/codex.js';
 import { runGrok } from './agents/grok.js';
+import { runGemini } from './agents/gemini.js';
+import { runCursor } from './agents/cursor.js';
 import {
   scanAllSessions,
   loadSessionMessages,
@@ -32,6 +34,7 @@ import { createTextBatcher } from './agents/stream-batch.js';
 import { normalizeCommand, mapAgentEmit } from './runtime/protocol.js';
 import { createOutbox } from './runtime/outbox.js';
 import { resolveApproval, cancelApprovalsForSession } from './runtime/approvals.js';
+import { createMcpHttpHandler, createMcpService } from './mcp.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.join(__dirname, '..');
 
@@ -44,12 +47,16 @@ const SESSION_META_FILE  = process.env.SESSION_META_FILE  || path.join(rootDir,
 const CLAUDE_CLI_PATH = process.env.CLAUDE_CLI_PATH || 'claude';
 const CODEX_CLI_PATH  = process.env.CODEX_CLI_PATH  || 'codex';
 const GROK_CLI_PATH   = process.env.GROK_CLI_PATH   || 'grok';
+const GEMINI_CLI_PATH = process.env.GEMINI_CLI_PATH || process.env.AGY_PATH || 'agy';
+const CURSOR_AGENT_PATH = process.env.CURSOR_AGENT_PATH || 'cursor-agent';
 const CODEX_HOME = (process.env.CODEX_HOME || path.join(os.homedir(), '.codex')).replace(/^~/, os.homedir());
 const GROK_HOME  = (process.env.GROK_HOME  || path.join(os.homedir(), '.grok')).replace(/^~/, os.homedir());
+const GEMINI_HOME = (process.env.GEMINI_HOME || path.join(os.homedir(), '.gemini')).replace(/^~/, os.homedir());
+const CURSOR_HOME = (process.env.CURSOR_HOME || path.join(os.homedir(), '.cursor')).replace(/^~/, os.homedir());
 const ENABLED_AGENTS = (() => {
-  const raw = (process.env.AGENTS || 'claude,codex,grok')
+  const raw = (process.env.AGENTS || 'claude,codex,grok,gemini,cursor')
     .split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
-  return [...new Set(raw.length ? raw : ['claude', 'codex', 'grok'])];
+  return [...new Set(raw.length ? raw : ['claude', 'codex', 'grok', 'gemini', 'cursor'])];
 })();
 const CLAUDE_CONFIG_DIRS = (() => {
   const dirs = (process.env.CLAUDE_CONFIG_DIRS || '')
@@ -186,6 +193,14 @@ function makeToken(user) {
   return jwt.sign({ userId: user.id, username: user.username }, jwtSecret(), { expiresIn: '7d' });
 }
 
+function makeMcpToken(user, expiresInSeconds) {
+  return jwt.sign(
+    { userId: user.userId ?? user.id, username: user.username, scope: 'mcp', tokenId: crypto.randomUUID() },
+    jwtSecret(),
+    { expiresIn: expiresInSeconds },
+  );
+}
+
 function verifyToken(token) {
   try { return jwt.verify(token, jwtSecret()); }
   catch { return null; }
@@ -306,11 +321,37 @@ async function listSessions(filterCwd = null, agentFilter = null) {
     claudeConfigDirs: CLAUDE_CONFIG_DIRS,
     codexHome: CODEX_HOME,
     grokHome: GROK_HOME,
+    geminiHome: GEMINI_HOME,
+    cursorHome: CURSOR_HOME,
     filterCwd,
     agents,
   });
 }
 
+// The HTTP UI endpoint and MCP both need the same agent-aware lookup rule:
+// prefer the stated agent, then fall back only when no preference was given.
+async function readSessionBundle(sessionId, preferredAgent = null) {
+  const opts = {
+    claudeConfigDirs: CLAUDE_CONFIG_DIRS,
+    codexHome: CODEX_HOME,
+    grokHome: GROK_HOME,
+    geminiHome: GEMINI_HOME,
+    cursorHome: CURSOR_HOME,
+  };
+  const order = preferredAgent
+    ? [preferredAgent]
+    : [...ENABLED_AGENTS];
+  for (const agent of order) {
+    const bundle = await loadSessionMessages(sessionId, agent, opts);
+    if (bundle) {
+      return Array.isArray(bundle)
+        ? { messages: bundle, context: null, agent }
+        : { ...bundle, agent: bundle.agent || agent, messages: bundle.messages || [] };
+    }
+  }
+  return null;
+}
+
 /**
  * Wrap agent emit → map/filter → outbox (delta coalesce + batch frames).
  * Agents may still call send() with UI-shaped events; unknown noise is dropped.
@@ -337,6 +378,10 @@ async function dispatchAgent(agent, command, options, send) {
     await runCodex(command, options, send, { ...ctx, cliPath: CODEX_CLI_PATH });
   } else if (a === 'grok') {
     await runGrok(command, options, send, { ...ctx, cliPath: GROK_CLI_PATH });
+  } else if (a === 'gemini') {
+    await runGemini(command, options, send, { ...ctx, cliPath: GEMINI_CLI_PATH, geminiHome: GEMINI_HOME });
+  } else if (a === 'cursor') {
+    await runCursor(command, options, send, { ...ctx, cliPath: CURSOR_AGENT_PATH, cursorHome: CURSOR_HOME });
   } else {
     await runClaude(command, options, send, { ...ctx, cliPath: CLAUDE_CLI_PATH });
   }
@@ -496,6 +541,55 @@ export function createApp() {
 
   app.use(express.json({ limit: '10mb' }));
 
+  // MCP uses a separate short-lived bearer token. Normal UI JWTs deliberately
+  // cannot call /mcp, so a browser token leaked through a URL cannot become an
+  // agent-control credential.
+  const mcpService = createMcpService({
+    listSessions,
+    readSession: readSessionBundle,
+    dispatchAgent,
+    abortSession,
+    isSessionBusy,
+    enabledAgents: ENABLED_AGENTS,
+    toClientSession,
+  });
+  const authenticateMcp = (req) => {
+    const header = req.headers.authorization || '';
+    const token = /^Bearer\s+(.+)$/i.exec(header)?.[1];
+    if (!token) return false;
+    const claims = verifyToken(token);
+    if (claims?.scope === 'mcp') return true;
+
+    // Optional headless deployment token. It is accepted only with an explicit
+    // expiry, keeping the same expiration guarantee as issued JWTs.
+    const configured = process.env.MCP_TOKEN;
+    const expiresRaw = process.env.MCP_TOKEN_EXPIRES_AT;
+    if (!configured || !expiresRaw || token.length !== configured.length) return false;
+    let expiresAt = Number(expiresRaw);
+    if (!Number.isFinite(expiresAt)) expiresAt = Date.parse(expiresRaw);
+    if (expiresAt > 0 && expiresAt < 10_000_000_000) expiresAt *= 1000;
+    return Number.isFinite(expiresAt) && Date.now() < expiresAt
+      && crypto.timingSafeEqual(Buffer.from(token), Buffer.from(configured));
+  };
+  app.post('/mcp', createMcpHttpHandler({ service: mcpService, authenticate: authenticateMcp }));
+
+  // Issue a scoped credential from an already-authenticated UI/API client.
+  // The raw secret is returned once and never written to the credential store.
+  app.post('/api/mcp/tokens', authMiddleware, (req, res) => {
+    try {
+      const requested = req.body?.expiresInSeconds ?? 86_400;
+      if (!Number.isInteger(requested) || requested < 60 || requested > 2_592_000) {
+        return res.status(400).json({ error: 'expiresInSeconds must be an integer between 60 and 2592000' });
+      }
+      const token = makeMcpToken(req.user, requested);
+      const decoded = jwt.decode(token);
+      res.setHeader('Cache-Control', 'no-store');
+      res.status(201).json({ token, tokenType: 'Bearer', expiresAt: Number(decoded?.exp || 0) * 1000, expiresInSeconds: requested });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+
   const distDir   = path.join(rootDir, 'dist');
   const publicDir = path.join(rootDir, 'public');
   // Only ship the built bundle in production. Local `node server.js` serves
@@ -716,6 +810,10 @@ export function createApp() {
         claudeConfigDirs: CLAUDE_CONFIG_DIRS,
         codexHome: CODEX_HOME,
         grokHome: GROK_HOME,
+        geminiHome: GEMINI_HOME,
+        geminiCliPath: GEMINI_CLI_PATH,
+        cursorHome: CURSOR_HOME,
+        cursorAgentPath: CURSOR_AGENT_PATH,
         agents: ENABLED_AGENTS,
       });
       res.json({
@@ -725,11 +823,15 @@ export function createApp() {
           claude: CLAUDE_CONFIG_DIRS,
           codex: CODEX_HOME,
           grok: GROK_HOME,
+          gemini: GEMINI_HOME,
+          cursor: CURSOR_HOME,
         },
         paths: {
           claude: CLAUDE_CLI_PATH,
           codex: CODEX_CLI_PATH,
           grok: GROK_CLI_PATH,
+          gemini: GEMINI_CLI_PATH,
+          cursor: CURSOR_AGENT_PATH,
         },
       });
     } catch (e) {
@@ -833,8 +935,10 @@ export function createApp() {
         claudeConfigDirs: CLAUDE_CONFIG_DIRS,
         codexHome: CODEX_HOME,
         grokHome: GROK_HOME,
+        geminiHome: GEMINI_HOME,
+        cursorHome: CURSOR_HOME,
       };
-      const order = [...new Set([preferred, ...ENABLED_AGENTS, 'claude', 'codex', 'grok'].filter(Boolean))];
+      const order = [...new Set([preferred, ...ENABLED_AGENTS, 'claude', 'codex', 'grok', 'gemini', 'cursor'].filter(Boolean))];
       let data = null;
       for (const a of order) {
         data = await loadSessionUsage(sessionId, a, opts);
@@ -925,6 +1029,8 @@ export function createApp() {
         claudeConfigDirs: CLAUDE_CONFIG_DIRS,
         codexHome: CODEX_HOME,
         grokHome: GROK_HOME,
+        geminiHome: GEMINI_HOME,
+        cursorHome: CURSOR_HOME,
       };
       // Prefer stated agent; only fall back if not found (avoids scanning all agents every time)
       const order = preferred
@@ -975,11 +1081,13 @@ export function createApp() {
         claudeConfigDirs: CLAUDE_CONFIG_DIRS,
         codexHome: CODEX_HOME,
         grokHome: GROK_HOME,
+        geminiHome: GEMINI_HOME,
+        cursorHome: CURSOR_HOME,
       };
 
       let detectedSourceAgent = sourceAgent;
       if (!detectedSourceAgent) {
-        const order = [...new Set([...ENABLED_AGENTS, 'claude', 'codex', 'grok'])];
+        const order = [...new Set([...ENABLED_AGENTS, 'claude', 'codex', 'grok', 'gemini', 'cursor'])];
         for (const a of order) {
           const bundle = await loadSessionMessages(sessionId, a, opts);
           if (bundle) {
@@ -1009,12 +1117,14 @@ export function createApp() {
         claudeConfigDirs: CLAUDE_CONFIG_DIRS,
         codexHome: CODEX_HOME,
         grokHome: GROK_HOME,
+        geminiHome: GEMINI_HOME,
+        cursorHome: CURSOR_HOME,
       };
       // A selected session already knows its agent. Do not fall back to another
       // agent's account-level memory (especially Codex) when that session has none.
       const order = preferred
         ? [preferred]
-        : [...new Set([...ENABLED_AGENTS, 'claude', 'codex', 'grok'])];
+        : [...new Set([...ENABLED_AGENTS, 'claude', 'codex', 'grok', 'gemini', 'cursor'])];
       let memory = null;
       for (const a of order) {
         memory = await loadSessionMemory(sessionId, a, opts);
@@ -1033,7 +1143,7 @@ export function createApp() {
       const file = typeof req.query.file === 'string' ? req.query.file : '';
       if (!/^[0-9a-f-]{36}$/i.test(sessionId)) return res.status(400).json({ error: 'Invalid session id' });
       const row = await readSessionMemoryFile(sessionId, agent, file, {
-        claudeConfigDirs: CLAUDE_CONFIG_DIRS, codexHome: CODEX_HOME, grokHome: GROK_HOME,
+        claudeConfigDirs: CLAUDE_CONFIG_DIRS, codexHome: CODEX_HOME, grokHome: GROK_HOME, geminiHome: GEMINI_HOME, cursorHome: CURSOR_HOME,
       });
       if (!row) return res.status(404).json({ error: 'Memory file not found' });
       res.setHeader('Cache-Control', 'private, max-age=30');
@@ -1076,6 +1186,8 @@ export function createApp() {
     claudeConfigDirs: () => CLAUDE_CONFIG_DIRS,
     codexHome: () => CODEX_HOME,
     grokHome: () => GROK_HOME,
+    geminiHome: () => GEMINI_HOME,
+    cursorHome: () => CURSOR_HOME,
   });
 
   /** Write SSE event */
@@ -1666,7 +1778,7 @@ export async function init() {
   await bootstrapEnvUser();
   await syncConfigDirs();
   console.log(`[agents] enabled: ${ENABLED_AGENTS.join(', ')}`);
-  console.log(`[agents] claude=${CLAUDE_CLI_PATH}  codex=${CODEX_CLI_PATH}  grok=${GROK_CLI_PATH}`);
+  console.log(`[agents] claude=${CLAUDE_CLI_PATH}  codex=${CODEX_CLI_PATH}  grok=${GROK_CLI_PATH}  gemini=${GEMINI_CLI_PATH}`);
 }
 
 // (session helpers live in ./agents/sessions.js)

package/src/mcp.js

@@ -0,0 +1,275 @@
+import crypto from 'crypto';
+
+// A deliberately small MCP implementation.  The Streamable HTTP transport is
+// JSON-RPC over POST; none of the tools need a long-lived server-side session.
+export const MCP_PROTOCOL_VERSION = '2025-03-26';
+
+const MAX_EVENTS = 100;
+const MAX_OUTPUT_CHARS = 12_000;
+const MAX_HISTORY_MESSAGES = 2_000;
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function digest(value) {
+  return crypto.createHash('sha256').update(JSON.stringify(value)).digest('base64url');
+}
+
+export function encodeSessionCursor({ sessionId, agent, count, prefix }) {
+  return Buffer.from(JSON.stringify({ v: 1, sessionId, agent, count, prefix })).toString('base64url');
+}
+
+export function decodeSessionCursor(cursor) {
+  if (typeof cursor !== 'string' || cursor.length > 2_000) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (parsed?.v !== 1 || typeof parsed.sessionId !== 'string' || typeof parsed.agent !== 'string'
+      || !Number.isInteger(parsed.count) || parsed.count < 0 || typeof parsed.prefix !== 'string') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function jsonText(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+function toolError(message) {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+function stringArg(args, key, { required = false, max = 0 } = {}) {
+  const value = args?.[key];
+  if (value == null || value === '') {
+    if (required) throw new Error(`${key} is required`);
+    return undefined;
+  }
+  if (typeof value !== 'string') throw new Error(`${key} must be a string`);
+  const result = value.trim();
+  if (required && !result) throw new Error(`${key} is required`);
+  if (max && result.length > max) throw new Error(`${key} is too long (max ${max})`);
+  return result;
+}
+
+function boundedInt(value, fallback, min, max) {
+  if (value == null) return fallback;
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+function sessionIdArg(args) {
+  const sessionId = stringArg(args, 'sessionId', { required: true, max: 200 });
+  if (!SESSION_ID_RE.test(sessionId)) throw new Error('sessionId must be a UUID');
+  return sessionId;
+}
+
+function conciseEvent(event) {
+  const out = {
+    type: event?.type || 'unknown',
+    agent: event?.agent,
+    sessionId: event?.sessionId,
+  };
+  if (typeof event?.message === 'string') out.message = event.message.slice(0, 2_000);
+  if (typeof event?.result === 'string') out.result = event.result.slice(0, 4_000);
+  if (typeof event?.data === 'string') out.data = event.data.slice(0, 4_000);
+  if (event?.exitCode != null) out.exitCode = event.exitCode;
+  if (event?.aborted) out.aborted = true;
+  return out;
+}
+
+export const MCP_TOOLS = [
+  {
+    name: 'session_list',
+    description: 'List saved Claude, Codex, Grok, Gemini, and Cursor sessions. Use updatedSince for inexpensive polling.',
+    inputSchema: {
+      type: 'object', properties: {
+        agent: { type: 'string', enum: ['claude', 'codex', 'grok', 'gemini', 'cursor'] },
+        cwd: { type: 'string' }, updatedSince: { type: 'number' }, limit: { type: 'integer', minimum: 1, maximum: 800 },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_get',
+    description: 'Read a session history. Returns a cursor that can be supplied to session_changes for append-only incremental updates.',
+    inputSchema: {
+      type: 'object', required: ['sessionId'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, tail: { type: 'integer', minimum: 0, maximum: 50000 },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_changes',
+    description: 'Get changes since a cursor from session_get/session_changes. It returns only added messages when history is append-only; mode=reset means old history changed and should be fetched again.',
+    inputSchema: {
+      type: 'object', required: ['sessionId', 'cursor'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, cursor: { type: 'string' }, limit: { type: 'integer', minimum: 1, maximum: 2000 },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_create',
+    description: 'Create a real agent session by running its first prompt. Waits for the turn to finish and returns the newly assigned sessionId.',
+    inputSchema: {
+      type: 'object', required: ['prompt'], properties: {
+        agent: { type: 'string', enum: ['claude', 'codex', 'grok', 'gemini', 'cursor'] }, prompt: { type: 'string', minLength: 1 }, cwd: { type: 'string' },
+        model: { type: 'string' }, effort: { type: 'string' }, permissionMode: { type: 'string', enum: ['default', 'acceptEdits', 'auto', 'bypassPermissions'] },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_run',
+    description: 'Run one more prompt in an existing session. This is synchronous and returns a compact event transcript.',
+    inputSchema: {
+      type: 'object', required: ['sessionId', 'prompt'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, prompt: { type: 'string', minLength: 1 }, cwd: { type: 'string' },
+        model: { type: 'string' }, effort: { type: 'string' }, permissionMode: { type: 'string', enum: ['default', 'acceptEdits', 'auto', 'bypassPermissions'] },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_resume',
+    description: 'Alias of session_run with an explicit resume intent. Use it to continue a session with a new prompt.',
+    inputSchema: {
+      type: 'object', required: ['sessionId', 'prompt'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, prompt: { type: 'string', minLength: 1 }, cwd: { type: 'string' },
+        model: { type: 'string' }, effort: { type: 'string' }, permissionMode: { type: 'string', enum: ['default', 'acceptEdits', 'auto', 'bypassPermissions'] },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_abort',
+    description: 'Interrupt the active run for a session.',
+    inputSchema: { type: 'object', required: ['sessionId'], properties: { sessionId: { type: 'string' } }, additionalProperties: false },
+  },
+];
+
+/**
+ * Create the MCP domain layer. Dependencies are injected so the protocol and
+ * cursor rules are testable without a running HTTP server or installed CLIs.
+ */
+export function createMcpService({ listSessions, readSession, dispatchAgent, abortSession, isSessionBusy, enabledAgents, toClientSession = (s) => s }) {
+  const validAgents = new Set(enabledAgents || []);
+
+  function agentArg(args, fallback = 'claude') {
+    const agent = (stringArg(args, 'agent', { max: 32 }) || fallback).toLowerCase();
+    if (!validAgents.has(agent)) throw new Error(`agent must be one of: ${[...validAgents].join(', ')}`);
+    return agent;
+  }
+
+  async function sessionSnapshot(sessionId, preferredAgent) {
+    const bundle = await readSession(sessionId, preferredAgent);
+    if (!bundle) throw new Error('Session not found');
+    const messages = Array.isArray(bundle.messages) ? bundle.messages : [];
+    const agent = bundle.agent || preferredAgent || 'claude';
+    return { ...bundle, agent, messages };
+  }
+
+  async function run(args, { creating = false, resumed = false } = {}) {
+    const prompt = stringArg(args, 'prompt', { required: true, max: 200_000 });
+    const agent = agentArg(args);
+    const sessionId = creating ? undefined : sessionIdArg(args);
+    if (sessionId && isSessionBusy(sessionId)) throw new Error('Session is already running');
+    const options = { sessionId, cwd: stringArg(args, 'cwd', { max: 4_000 }), model: stringArg(args, 'model', { max: 200 }), effort: stringArg(args, 'effort', { max: 100 }) };
+    // Codex otherwise defaults to yolo when no mode is supplied. MCP callers
+    // must explicitly opt into a broader permissionMode.
+    options.mode = agent === 'codex' ? 'suggest' : undefined;
+    options.permissionMode = stringArg(args, 'permissionMode', { max: 64 }) || 'acceptEdits';
+    const events = [];
+    let eventCount = 0;
+    let createdSessionId = sessionId || null;
+    let output = '';
+    await dispatchAgent(agent, prompt, options, (event) => {
+      if (event?.sessionId) createdSessionId = event.sessionId;
+      if (event?.type === 'assistant_delta' && typeof event.data === 'string') output += event.data;
+      if (event?.type === 'result' && typeof event.result === 'string') output += event.result;
+      eventCount++;
+      if (events.length < MAX_EVENTS) events.push(conciseEvent(event));
+    });
+    return {
+      created: creating, resumed, agent, sessionId: createdSessionId || sessionId,
+      output: output.slice(-MAX_OUTPUT_CHARS), events, eventsTruncated: eventCount > MAX_EVENTS,
+    };
+  }
+
+  async function call(name, args = {}) {
+    switch (name) {
+      case 'session_list': {
+        const agent = args.agent == null ? null : agentArg(args);
+        const cwd = stringArg(args, 'cwd', { max: 4_000 });
+        const since = args.updatedSince == null ? 0 : Number(args.updatedSince);
+        if (!Number.isFinite(since) || since < 0) throw new Error('updatedSince must be a Unix millisecond timestamp');
+        const limit = boundedInt(args.limit, 100, 1, 800);
+        let sessions = await listSessions(cwd || null, agent);
+        if (since) sessions = sessions.filter((s) => Number(s.updatedAt || 0) > since);
+        sessions.sort((a, b) => Number(b.updatedAt || 0) - Number(a.updatedAt || 0));
+        return { sessions: sessions.slice(0, limit).map(toClientSession), nextUpdatedSince: sessions[0]?.updatedAt || since || Date.now(), truncated: sessions.length > limit };
+      }
+      case 'session_get': {
+        const sessionId = sessionIdArg(args);
+        const snapshot = await sessionSnapshot(sessionId, stringArg(args, 'agent', { max: 32 }));
+        const tail = boundedInt(args.tail, 0, 0, 50_000);
+        const all = snapshot.messages;
+        const messages = tail > 0 ? all.slice(-tail) : all.slice(-MAX_HISTORY_MESSAGES);
+        const returnedFrom = all.length - messages.length;
+        return {
+          sessionId, agent: snapshot.agent, context: snapshot.context || null, total: all.length, returnedFrom, messages,
+          truncated: returnedFrom > 0,
+          cursor: encodeSessionCursor({ sessionId, agent: snapshot.agent, count: all.length, prefix: digest(all) }),
+        };
+      }
+      case 'session_changes': {
+        const sessionId = sessionIdArg(args);
+        const cursor = decodeSessionCursor(stringArg(args, 'cursor', { required: true, max: 2_000 }));
+        if (!cursor || cursor.sessionId !== sessionId) throw new Error('cursor is invalid for this session');
+        const requestedAgent = stringArg(args, 'agent', { max: 32 });
+        if (requestedAgent && requestedAgent !== cursor.agent) throw new Error('cursor agent does not match agent');
+        const snapshot = await sessionSnapshot(sessionId, cursor.agent);
+        const limit = boundedInt(args.limit, MAX_HISTORY_MESSAGES, 1, MAX_HISTORY_MESSAGES);
+        const prefixMatches = snapshot.agent === cursor.agent && cursor.count <= snapshot.messages.length
+          && digest(snapshot.messages.slice(0, cursor.count)) === cursor.prefix;
+        const nextCursor = encodeSessionCursor({ sessionId, agent: snapshot.agent, count: snapshot.messages.length, prefix: digest(snapshot.messages) });
+        if (!prefixMatches) {
+          return { mode: 'reset', sessionId, agent: snapshot.agent, total: snapshot.messages.length, cursor: nextCursor,
+            reason: 'session history was rewritten or the cursor is stale; call session_get again' };
+        }
+        const added = snapshot.messages.slice(cursor.count, cursor.count + limit);
+        return { mode: 'diff', sessionId, agent: snapshot.agent, from: cursor.count, total: snapshot.messages.length,
+          added, hasMore: cursor.count + added.length < snapshot.messages.length, cursor: nextCursor };
+      }
+      case 'session_create': return run(args, { creating: true });
+      case 'session_run': return run(args);
+      case 'session_resume': return run(args, { resumed: true });
+      case 'session_abort': {
+        const sessionId = sessionIdArg(args);
+        return { sessionId, aborted: !!abortSession(sessionId) };
+      }
+      default: throw new Error(`Unknown tool: ${name}`);
+    }
+  }
+
+  return { call };
+}
+
+export function createMcpHttpHandler({ service, authenticate }) {
+  return async (req, res) => {
+    const rpc = req.body;
+    const id = rpc?.id;
+    const reply = (result) => res.json({ jsonrpc: '2.0', id: id ?? null, result });
+    const rpcError = (code, message) => res.status(code === -32600 ? 400 : 200).json({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+    if (!rpc || rpc.jsonrpc !== '2.0' || typeof rpc.method !== 'string') return rpcError(-32600, 'Invalid JSON-RPC request');
+    if (!authenticate(req)) return res.status(401).json({ jsonrpc: '2.0', id: id ?? null, error: { code: -32001, message: 'Valid MCP bearer token required' } });
+    if (rpc.method === 'initialize') {
+      return reply({ protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'claude-simple-sessions', version: '0.2.9' } });
+    }
+    if (rpc.method === 'notifications/initialized') return res.status(202).end();
+    if (rpc.method === 'ping') return reply({});
+    if (rpc.method === 'tools/list') return reply({ tools: MCP_TOOLS });
+    if (rpc.method === 'tools/call') {
+      if (typeof rpc.params?.name !== 'string') return rpcError(-32602, 'tools/call requires params.name');
+      try { return reply(await service.call(rpc.params.name, rpc.params.arguments || {})); }
+      catch (error) { return reply(toolError(error instanceof Error ? error.message : String(error))); }
+    }
+    return rpcError(-32601, `Method not found: ${rpc.method}`);
+  };
+}