amalgm 0.1.72 → 0.1.73

package/runtime/scripts/amalgm-mcp/server/mcp.js

@@ -2,12 +2,8 @@
  * MCP server — built on @modelcontextprotocol/sdk.
  *
  * The SDK handles JSON-RPC framing, protocol-version negotiation, batching,
- * and streamable-HTTP transport. We just register the two tool handlers.
- *
- * Each domain module exports a flat array of
- * { name, description, inputSchema, handler }. We concatenate the built-in
- * Amalgm tools with toolbox management tools. Custom CLI/API actions registered
- * in the ToolboxDB are exposed dynamically through this same MCP transport.
+ * and streamable-HTTP transport. The Toolbox MCP surface owns tool listing and
+ * call resolution.
  */
 
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
@@ -19,47 +15,18 @@ const {
   CallToolRequestSchema,
 } = require('@modelcontextprotocol/sdk/types.js');
 
-const { AMALGM_USER_ID } = require('../config');
-const { hasSupabase, supabaseSelect } = require('../lib/supabase');
 const { attachActionDescriptor } = require('../lib/tool-result');
-const { CORE_TOOLS } = require('./core-tools');
 const {
-  callToolboxMcpTool,
-  listToolboxMcpTools,
-} = require('../toolbox/runner');
-
-const TOOLS = [
-  ...CORE_TOOLS,
-  ...require('../toolbox/tools'),
-];
-
-/**
- * Look up the caller's session to tag DB rows with origin metadata. Reads
- * x-amalgm-session-id from the transport's passed-through HTTP headers.
- */
-async function buildRequestContext(extra) {
-  const headers = extra?.requestInfo?.headers || {};
-  const h = headers['x-amalgm-session-id'];
-  const callerSessionId = Array.isArray(h) ? h[0] : h || null;
-  const ctx = { callerSessionId };
+  DEFAULT_STATIC_MCP_TOOLS,
+  createToolboxMcpSurface,
+} = require('../toolbox/mcp-surface');
+const { buildMcpRequestContext } = require('./mcp-request-context');
 
-  if (callerSessionId && hasSupabase()) {
-    const rows = await supabaseSelect(
-      'sessions',
-      `id=eq.${callerSessionId}&user_id=eq.${AMALGM_USER_ID}&select=id,title,harness,metadata`,
-    );
-    const parent = Array.isArray(rows) ? rows[0] : null;
-    if (parent) {
-      ctx.sessionMetadata = parent.metadata || {};
-      ctx.originName = parent.title || undefined;
-      ctx.originHarnessId = parent.harness || undefined;
-      ctx.originBaseHarnessId = parent.metadata?.baseHarnessId || undefined;
-    }
-  }
-  return ctx;
-}
+const TOOLS = DEFAULT_STATIC_MCP_TOOLS;
 
-function createMcpServer() {
+function createMcpServer(options = {}) {
+  const surface = options.surface || createToolboxMcpSurface();
+  const buildRequestContext = options.buildRequestContext || buildMcpRequestContext;
   const server = new Server(
     { name: 'amalgm', version: '1.0.0' },
     { capabilities: { tools: {} } },
@@ -67,41 +34,15 @@ function createMcpServer() {
 
   server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
     const ctx = await buildRequestContext(extra);
-    return {
-      tools: [
-        ...TOOLS.map(({ name, description, inputSchema }) => ({
-          name,
-          description,
-          inputSchema,
-        })),
-        ...listToolboxMcpTools(ctx),
-      ],
-    };
+    return { tools: await surface.listTools(ctx) };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const toolName = request.params?.name;
     const toolArgs = request.params?.arguments || {};
-    const tool = TOOLS.find((t) => t.name === toolName);
-    if (!tool) {
-      const ctx = await buildRequestContext(extra);
-      const toolboxResult = await callToolboxMcpTool(toolName, toolArgs, ctx);
-      if (toolboxResult) return attachActionDescriptor(toolboxResult, toolName, toolArgs);
-      return attachActionDescriptor({
-        content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],
-        isError: true,
-      }, toolName || 'unknown', toolArgs);
-    }
     const ctx = await buildRequestContext(extra);
-    try {
-      const result = await tool.handler(toolArgs, ctx);
-      return attachActionDescriptor(result, toolName, toolArgs);
-    } catch (err) {
-      return attachActionDescriptor({
-        content: [{ type: 'text', text: `Error: ${err.message}` }],
-        isError: true,
-      }, toolName, toolArgs);
-    }
+    const result = await surface.callTool(toolName, toolArgs, ctx);
+    return attachActionDescriptor(result, toolName || 'unknown', toolArgs);
   });
 
   return server;
@@ -124,4 +65,4 @@ async function createTransport() {
   return transport;
 }
 
-module.exports = { createTransport, TOOLS };
+module.exports = { createMcpServer, createTransport, TOOLS };

package/runtime/scripts/amalgm-mcp/server/routes/agents.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const agentsRest = require('../../agents/rest');
+
+async function handleAgentRoutes(ctx) {
+  if (ctx.pathname === '/agents/list' && ctx.method === 'GET') {
+    agentsRest.handleList(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/agents/get' && ctx.method === 'POST') {
+    agentsRest.handleGet(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/agents/create' && ctx.method === 'POST') {
+    agentsRest.handleCreate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/agents/update' && ctx.method === 'POST') {
+    agentsRest.handleUpdate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/agents/delete' && ctx.method === 'POST') {
+    agentsRest.handleDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleAgentRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/apps.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const appsRest = require('../../apps/rest');
+
+function appRoute(pathname) {
+  if (pathname.startsWith('/apps/')) {
+    return { path: pathname.slice('/apps'.length), legacy: false };
+  }
+  if (pathname.startsWith('/artifacts/')) {
+    return { path: pathname.slice('/artifacts'.length), legacy: true };
+  }
+  return null;
+}
+
+async function handleAppRoutes(ctx) {
+  const route = appRoute(ctx.pathname);
+  if (!route) return false;
+  const options = route.legacy ? { legacy: true } : undefined;
+
+  if (route.path === '/list' && ctx.method === 'GET') {
+    appsRest.handleList(ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/routes' && ctx.method === 'GET') {
+    await appsRest.handleRoutes(ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/register' && ctx.method === 'POST') {
+    await appsRest.handleRegister(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/redeploy' && ctx.method === 'POST') {
+    await appsRest.handleRedeploy(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/start' && ctx.method === 'POST') {
+    await appsRest.handleStart(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/stop' && ctx.method === 'POST') {
+    await appsRest.handleStop(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/delete' && ctx.method === 'POST') {
+    await appsRest.handleDelete(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/connect-dns' && ctx.method === 'POST') {
+    await appsRest.handleConnectDns(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  if (route.path === '/disconnect-dns' && ctx.method === 'POST') {
+    await appsRest.handleDisconnectDns(await ctx.readJsonBody(), ctx.sendJson, options);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { appRoute, handleAppRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/automations.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const automationsRest = require('../../automations/rest');
+
+async function handleAutomationRoutes(ctx) {
+  if (ctx.pathname === '/automations/list' && ctx.method === 'GET') {
+    automationsRest.handleList(ctx.req, ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/get' && ctx.method === 'POST') {
+    automationsRest.handleGet(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/create' && ctx.method === 'POST') {
+    await automationsRest.handleCreate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/update' && ctx.method === 'POST') {
+    automationsRest.handleUpdate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/delete' && ctx.method === 'POST') {
+    automationsRest.handleDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/run-now' && ctx.method === 'POST') {
+    await automationsRest.handleRunNow(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/validate' && ctx.method === 'POST') {
+    await automationsRest.handleValidate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/triggers/update' && ctx.method === 'POST') {
+    automationsRest.handleTriggerUpdate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/automations/triggers/delete' && ctx.method === 'POST') {
+    automationsRest.handleTriggerDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleAutomationRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/browser.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const browserRest = require('../../browser/rest');
+
+async function handleBrowserRoutes(ctx) {
+  if (ctx.pathname === '/browser/profiles' && ctx.method === 'GET') {
+    browserRest.handleProfilesList(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/profiles' && ctx.method === 'POST') {
+    await browserRest.handleProfilesUpsert(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/auth-bundles' && ctx.method === 'GET') {
+    browserRest.handleAuthBundlesList(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/auth-bundles/export' && ctx.method === 'POST') {
+    await browserRest.handleAuthBundleExport(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/auth-bundles/import' && ctx.method === 'POST') {
+    await browserRest.handleAuthBundleImport(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/auth-bundles' && ctx.method === 'DELETE') {
+    await browserRest.handleAuthBundleDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname.startsWith('/browser/login-sessions') && ctx.method === 'GET') {
+    browserRest.handleLoginSessionsList(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/login-sessions' && ctx.method === 'POST') {
+    browserRest.handleLoginSessionCreate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/login-sessions/complete' && ctx.method === 'POST') {
+    await browserRest.handleLoginSessionComplete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/browser/login-sessions/cancel' && ctx.method === 'POST') {
+    browserRest.handleLoginSessionCancel(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleBrowserRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/credentials.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const credentialsRest = require('../../credentials/rest');
+const userApiKeysRest = require('../../user-api-keys/rest');
+
+async function handleCredentialRoutes(ctx) {
+  if (ctx.pathname === '/credentials' && ctx.method === 'GET') {
+    credentialsRest.handleList(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/credentials' && ctx.method === 'POST') {
+    credentialsRest.handleSave(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/credentials' && ctx.method === 'DELETE') {
+    credentialsRest.handleDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/user-api-keys' && ctx.method === 'POST') {
+    userApiKeysRest.handleSave(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/user-api-keys' && ctx.method === 'DELETE') {
+    userApiKeysRest.handleDelete(ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleCredentialRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/events.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const { handleEventsPost } = require('../../events/ingress');
+const eventsRing = require('../../events/ring-buffer');
+
+async function handleEventRoutes(ctx) {
+  if (ctx.pathname === '/events' && ctx.method === 'POST') {
+    await handleEventsPost(ctx.req, ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/events' && ctx.method === 'GET') {
+    ctx.sendJson(200, { events: eventsRing.recent(50) });
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleEventRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/files.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const fsRest = require('../../fs/rest');
+
+async function handleFileRoutes(ctx) {
+  if (ctx.pathname === '/fs/list' && ctx.method === 'GET') {
+    fsRest.handleList(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/fs/read' && ctx.method === 'GET') {
+    fsRest.handleRead(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/fs/write' && ctx.method === 'POST') {
+    fsRest.handleWrite(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/fs/delete' && ctx.method === 'POST') {
+    fsRest.handleDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/fs/mkdir' && ctx.method === 'POST') {
+    fsRest.handleMkdir(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/fs/rename' && ctx.method === 'POST') {
+    fsRest.handleRename(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleFileRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/health.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { loadAgents } = require('../../agents/store');
+const { loadApps } = require('../../apps/store');
+const { activeAgentConversations } = require('../../agents/talk');
+const { listAutomations } = require('../../automations/store');
+
+async function handleHealthRoutes(ctx) {
+  if (ctx.pathname !== '/healthz') return false;
+
+  const agents = loadAgents();
+  const automations = listAutomations();
+  ctx.sendJson(200, {
+    status: 'ok',
+    automations: automations.length,
+    enabledAutomations: automations.filter((automation) => automation.enabled !== false).length,
+    apps: loadApps().apps.length,
+    customAgents: agents.agents.length,
+    activeAgentConversations: activeAgentConversations.size,
+  });
+  return true;
+}
+
+module.exports = { handleHealthRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/inbound.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const emailInbound = require('../../email/inbound');
+const slackInbound = require('../../slack/inbound');
+
+async function handleInboundRoutes(ctx) {
+  if (ctx.pathname === '/email/inbound' && ctx.method === 'POST') {
+    await emailInbound.handleEmailInbound(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/slack/inbound' && ctx.method === 'POST') {
+    await slackInbound.handleSlackInbound(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleInboundRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/local.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const localRest = require('../../local/rest');
+
+async function handleLocalRoutes(ctx) {
+  if (ctx.pathname === '/local/init' && ctx.method === 'POST') {
+    localRest.handleInit(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/local/credentials' && ctx.method === 'GET') {
+    localRest.handleCredentials(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/local/credentials/resolve' && ctx.method === 'POST') {
+    localRest.handleResolve(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleLocalRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/preferences.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const prefsStore = require('../../lib/prefs');
+
+async function handlePreferenceRoutes(ctx) {
+  if (ctx.pathname === '/user-preferences' && ctx.method === 'GET') {
+    ctx.sendJson(200, prefsStore.readUserPreferences());
+    return true;
+  }
+  if (ctx.pathname === '/user-preferences' && ctx.method === 'PUT') {
+    const preferences = prefsStore.updateUserPreferences(await ctx.readJsonBody());
+    ctx.sendJson(200, { success: true, preferences });
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handlePreferenceRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/state.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const stateRest = require('../../state/rest');
+
+async function handleStateRoutes(ctx) {
+  if (ctx.method !== 'GET') return false;
+
+  if (ctx.pathname === '/state/snapshot') {
+    stateRest.handleSnapshot(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/state/events') {
+    stateRest.handleEvents(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/state/stream') {
+    stateRest.handleStream(ctx.req, ctx.res, ctx.getQuery());
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleStateRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/toolbox.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const mcpConnectionsRest = require('../../mcp-connections/rest');
+const toolboxRest = require('../../toolbox/rest');
+
+async function handleToolboxRoutes(ctx) {
+  if (ctx.pathname === '/mcp-connections' && ctx.method === 'GET') {
+    mcpConnectionsRest.handleList(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/mcp-connections' && ctx.method === 'POST') {
+    mcpConnectionsRest.handleUpsert(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/mcp-connections' && ctx.method === 'DELETE') {
+    mcpConnectionsRest.handleDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+
+  if (ctx.pathname === '/toolbox' && ctx.method === 'GET') {
+    toolboxRest.handleList(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/tools' && ctx.method === 'GET') {
+    toolboxRest.handleGetTool(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/tools' && ctx.method === 'POST') {
+    toolboxRest.handleUpsertTool(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/tools' && ctx.method === 'PATCH') {
+    toolboxRest.handleUpdateTool(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/tools' && ctx.method === 'DELETE') {
+    toolboxRest.handleDeleteTool(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/actions' && ctx.method === 'GET') {
+    toolboxRest.handleGetAction(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/actions' && ctx.method === 'POST') {
+    toolboxRest.handleUpsertAction(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/actions' && ctx.method === 'PATCH') {
+    toolboxRest.handleUpdateAction(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/toolbox/actions' && ctx.method === 'DELETE') {
+    toolboxRest.handleDeleteAction(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleToolboxRoutes };

package/runtime/scripts/amalgm-mcp/server/routes/workspace.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const workspaceRest = require('../../workspace/rest');
+
+async function handleWorkspaceRoutes(ctx) {
+  if (ctx.pathname === '/workspace/projects' && ctx.method === 'GET') {
+    workspaceRest.handleProjects(ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/projects' && ctx.method === 'POST') {
+    workspaceRest.handleProjectRegister(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/projects' && ctx.method === 'PATCH') {
+    workspaceRest.handleProjectUpdate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/projects' && ctx.method === 'DELETE') {
+    workspaceRest.handleProjectDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/import' && ctx.method === 'POST') {
+    workspaceRest.handleImport(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/github/clone' && ctx.method === 'POST') {
+    await workspaceRest.handleClone(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/branches' && ctx.method === 'GET') {
+    workspaceRest.handleBranches(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/checkout' && ctx.method === 'POST') {
+    workspaceRest.handleCheckout(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/diff' && ctx.method === 'GET') {
+    workspaceRest.handleDiff(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/worktree' && ctx.method === 'GET') {
+    workspaceRest.handleWorktreeList(ctx.getQuery(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/worktree' && ctx.method === 'POST') {
+    workspaceRest.handleWorktreeCreate(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  if (ctx.pathname === '/workspace/worktree' && ctx.method === 'DELETE') {
+    workspaceRest.handleWorktreeDelete(await ctx.readJsonBody(), ctx.sendJson);
+    return true;
+  }
+  return false;
+}
+
+module.exports = { handleWorkspaceRoutes };

package/runtime/scripts/amalgm-mcp/server/service-lifecycle.js

@@ -0,0 +1,54 @@
+'use strict';
+
+function startHttpServer(server, options = {}) {
+  const serviceName = options.serviceName || 'AmalgmService';
+  const host = options.host || '127.0.0.1';
+  const port = Number(options.port);
+  if (!Number.isFinite(port) || port < 0) {
+    throw new Error(`${serviceName} requires a valid port`);
+  }
+
+  server.listen(port, host, async () => {
+    const address = server.address();
+    const boundHost = address && typeof address === 'object' ? address.address : host;
+    const boundPort = address && typeof address === 'object' ? address.port : port;
+    console.log(`[${serviceName}] Listening on ${boundHost}:${boundPort}`);
+    await options.onListening?.();
+  });
+
+  if (options.installShutdown !== false) {
+    installGracefulShutdown(server, {
+      serviceName,
+      onShutdown: options.onShutdown,
+      exit: options.exit !== false,
+    });
+  }
+
+  return server;
+}
+
+function installGracefulShutdown(server, options = {}) {
+  const serviceName = options.serviceName || 'AmalgmService';
+  const exit = options.exit !== false;
+  let shuttingDown = false;
+
+  function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(`[${serviceName}] Shutting down...`);
+    options.onShutdown?.();
+    server.close(() => {
+      if (exit) process.exit(0);
+    });
+    if (exit) setTimeout(() => process.exit(0), 5000);
+  }
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  return shutdown;
+}
+
+module.exports = {
+  installGracefulShutdown,
+  startHttpServer,
+};