night-orch 0.3.2 → 0.4.0

package/dist/web/server.js

@@ -1,27 +1,25 @@
 import { createServer } from 'node:http';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import { extname, resolve, dirname, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { WebSocket, WebSocketServer } from 'ws';
-import { handleToolCall } from '../mcp/tools/index.js';
-import { handleResourceRead } from '../mcp/resources/index.js';
 import { InteractiveAgentSessionManager, } from './agent-session.js';
-import { loadTuiStats } from '../state/stats.js';
-import { getBuildInfo } from '../utils/build-info.js';
+import { ShellSessionManager, } from './shell-session.js';
 import { logger } from '../utils/logger.js';
 import { sanitizeError } from '../utils/sanitize-error.js';
 import { nowUtcIso } from '../utils/time.js';
-import { listRuntimeSettings, resolveConfigWithRuntimeSettings, RuntimeSettingInputError, } from '../settings/runtime.js';
-import { getSettingDefinition, resolveSettingYamlValue } from '../settings/registry.js';
+import { buildDashboardSnapshot, } from './snapshots.js';
+import { handleRunRoutes } from './routes/api-runs.js';
+import { handleOperationRoutes } from './routes/api-operations.js';
+import { handleSettingsRoutes } from './routes/api-settings.js';
+import { handleWsMessage, publishRunSubscriptions, publishAgentSessionSubscriptions, publishShellSessionSubscriptions, } from './routes/api-events.js';
 const ONE_MEGABYTE = 1024 * 1024;
 const DEFAULT_SNAPSHOT_INTERVAL_MS = 3000;
 const MUTATION_INTENT_HEADER = 'x-night-orch-intent';
 const MUTATION_INTENT_VALUE = 'mutate';
 const WEB_AUTH_TOKEN_HEADER = 'x-night-orch-web-token';
-const BUILD_INFO = getBuildInfo();
 const CONTENT_TYPES = {
     '.css': 'text/css; charset=utf-8',
     '.html': 'text/html; charset=utf-8',
@@ -44,12 +42,6 @@ export function resolveWebFrontendDistPath(explicitPath) {
     return resolve(moduleDir, '../../web/dist');
 }
 export async function startWebServer(deps, options) {
-    // Hard gate on non-loopback binds: the web server hands out a mutation
-    // token via `/api/session` to any same-origin caller and offers
-    // destructive endpoints (retry/cleanup/sync/etc) under that token. When
-    // bound to a non-loopback address, require an operator-supplied auth
-    // token env (`NIGHT_ORCH_WEB_AUTH_TOKEN`) so any single-origin XSS or
-    // local process cannot trivially escalate to full write access.
     const bindHostName = normalizeHostname(options.host) ?? options.host;
     const isLoopbackBind = bindHostName === '127.0.0.1'
         || bindHostName === '::1'
@@ -64,6 +56,7 @@ export async function startWebServer(deps, options) {
     const agentSessionManager = new InteractiveAgentSessionManager(deps.config, {
         workspacePath: resolveAgentSessionWorkspacePath(deps),
     });
+    const shellSessionManager = new ShellSessionManager();
     const frontendDistPath = resolveWebFrontendDistPath(options.frontendDistPath);
     const hasFrontendAssets = existsSync(resolve(frontendDistPath, 'index.html'));
     if (!hasFrontendAssets) {
@@ -71,6 +64,14 @@ export async function startWebServer(deps, options) {
     }
     const wsServer = new WebSocketServer({ noServer: true });
     const clients = new Map();
+    const routeContext = {
+        deps,
+        security,
+        operationsEnabled,
+        rawConfig: options.rawConfig,
+        agentSessionManager,
+        shellSessionManager,
+    };
     const httpServer = createServer(async (req, res) => {
         try {
             const requestUrl = getRequestUrl(req);
@@ -79,7 +80,7 @@ export async function startWebServer(deps, options) {
                     writeJson(res, 403, { error: 'Forbidden host' });
                     return;
                 }
-                await handleApiRequest(req, res, requestUrl, deps, security, operationsEnabled, options.rawConfig, agentSessionManager);
+                await handleApiRequest(req, res, requestUrl, routeContext);
                 return;
             }
             if (requestUrl.pathname === '/ws') {
@@ -126,13 +127,16 @@ export async function startWebServer(deps, options) {
             return;
         }
         wsServer.handleUpgrade(req, socket, head, (ws) => {
-            wsServer.emit('connection', ws);
+            wsServer.emit('connection', ws, req);
         });
     });
-    wsServer.on('connection', (ws) => {
+    wsServer.on('connection', (ws, req) => {
+        const isAuthenticated = resolveWebSocketAuthenticationState(req, security);
         const state = {
+            isAuthenticated,
             runSubscriptions: new Map(),
             agentSessionSubscriptions: new Map(),
+            shellSessionSubscriptions: new Map(),
         };
         clients.set(ws, state);
         sendWebsocket(ws, {
@@ -145,7 +149,7 @@ export async function startWebServer(deps, options) {
                 sendWebsocket(ws, { type: 'error', error: 'Unsupported websocket payload type' });
                 return;
             }
-            void handleWsMessage(ws, state, decoded, deps, agentSessionManager);
+            void handleWsMessage(ws, state, decoded, deps, agentSessionManager, shellSessionManager);
         });
         ws.on('close', () => {
             clients.delete(ws);
@@ -170,6 +174,7 @@ export async function startWebServer(deps, options) {
                     continue;
                 await publishRunSubscriptions(ws, state, deps);
                 publishAgentSessionSubscriptions(ws, state, agentSessionManager);
+                publishShellSessionSubscriptions(ws, state, shellSessionManager);
             }
         }
         catch (err) {
@@ -192,8 +197,19 @@ export async function startWebServer(deps, options) {
             publishAgentSessionSubscriptions(ws, state, agentSessionManager);
         }
     });
+    const stopShellSessionStreaming = shellSessionManager.onSessionEvent((sessionId) => {
+        for (const [ws, state] of clients.entries()) {
+            if (ws.readyState !== WebSocket.OPEN)
+                continue;
+            if (!state.shellSessionSubscriptions.has(sessionId))
+                continue;
+            publishShellSessionSubscriptions(ws, state, shellSessionManager);
+        }
+    });
     httpServer.on('close', () => {
         stopAgentSessionStreaming();
+        stopShellSessionStreaming();
+        shellSessionManager.closeAll();
         clearInterval(interval);
         for (const ws of wsServer.clients) {
             ws.close();
@@ -211,16 +227,21 @@ export async function startWebServer(deps, options) {
     await publishTick();
     return httpServer;
 }
-async function handleApiRequest(req, res, requestUrl, deps, security, operationsEnabled, rawConfig, agentSessionManager) {
+async function handleApiRequest(req, res, requestUrl, ctx) {
     const method = req.method ?? 'GET';
     const { pathname, searchParams } = requestUrl;
-    const runtimeDeps = {
-        ...deps,
-        config: resolveConfigWithRuntimeSettings(deps.config, deps.db),
-    };
+    const { security, operationsEnabled } = ctx;
+    if (method === 'GET' && pathname.startsWith('/api/shell/')) {
+        const shellReadGuardFailure = validateShellReadRequest(req, security);
+        if (shellReadGuardFailure) {
+            writeJson(res, shellReadGuardFailure.statusCode, { error: shellReadGuardFailure.error });
+            return;
+        }
+    }
     if ((method === 'POST' || method === 'DELETE')
-        && (pathname.startsWith('/api/operations/') || pathname.startsWith('/api/agent/'))) {
-        // Update is a supervisor operation — always allowed regardless of attach/standalone mode.
+        && (pathname.startsWith('/api/operations/')
+            || pathname.startsWith('/api/agent/')
+            || pathname.startsWith('/api/shell/'))) {
         if (!operationsEnabled && pathname !== '/api/operations/update') {
             writeJson(res, 409, { error: 'Web operations are disabled by server policy.' });
             return;
@@ -231,418 +252,12 @@ async function handleApiRequest(req, res, requestUrl, deps, security, operations
             return;
         }
     }
-    if (method === 'GET' && pathname === '/api/health') {
-        writeJson(res, 200, { status: 'ok', now: nowUtcIso() });
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/dashboard') {
-        const snapshot = await buildDashboardSnapshot(runtimeDeps);
-        writeJson(res, 200, snapshot);
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/projects') {
-        const snapshot = buildProjectsSnapshot(runtimeDeps);
-        writeJson(res, 200, snapshot);
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/settings') {
-        const snapshot = buildSettingsSnapshot(deps, rawConfig);
-        writeJson(res, 200, snapshot);
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/session') {
-        // When the server is bound to a non-loopback address with an operator-
-        // supplied auth token, we must NOT hand it out via HTTP — the client
-        // must provide it out-of-band. For loopback, disclosure is low-risk.
-        writeJson(res, 200, {
-            mutationToken: security.operatorAuthMode ? null : security.webMutationToken,
-            operationsEnabled,
-            requiresExternalAuth: security.operatorAuthMode,
-        });
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/agent/sessions') {
-        writeJson(res, 200, agentSessionManager.listSessions());
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/status') {
-        const repo = searchParams.get('repo') ?? undefined;
-        const result = await handleToolCall('night-orch-status', { repo }, runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/runs') {
-        const repo = searchParams.get('repo') ?? undefined;
-        const status = searchParams.get('status') ?? undefined;
-        const limit = toBoundedInt(searchParams.get('limit'), 50, 1, 500);
-        const result = await handleToolCall('night-orch-list-runs', { repo, status, limit }, runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/cost') {
-        const days = toBoundedInt(searchParams.get('days'), 7, 1, 30);
-        const result = await handleToolCall('night-orch-cost-report', { days }, runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/stats') {
-        writeJson(res, 200, loadTuiStats(runtimeDeps.db, { costModel: runtimeDeps.config.cost.model }));
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/config') {
-        const result = await handleResourceRead('night-orch://config', runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'GET') {
-        const agentSessionEventsMatch = pathname.match(/^\/api\/agent\/sessions\/([^/]+)\/events$/);
-        if (agentSessionEventsMatch) {
-            const sessionId = decodeURIComponent(agentSessionEventsMatch[1] ?? '');
-            const since = toBoundedInt(searchParams.get('since'), 0, 0, Number.MAX_SAFE_INTEGER);
-            const limit = toBoundedInt(searchParams.get('limit'), 100, 1, 400);
-            try {
-                writeJson(res, 200, agentSessionManager.getEvents(sessionId, since, limit));
-            }
-            catch (err) {
-                const message = err.message;
-                const statusCode = message.startsWith('Session not found:') ? 404 : 400;
-                writeJson(res, statusCode, { error: message });
-            }
-            return;
-        }
-        const agentSessionDetailMatch = pathname.match(/^\/api\/agent\/sessions\/([^/]+)$/);
-        if (agentSessionDetailMatch) {
-            const sessionId = decodeURIComponent(agentSessionDetailMatch[1] ?? '');
-            const session = agentSessionManager.getSession(sessionId);
-            if (!session) {
-                writeJson(res, 404, { error: `Session not found: ${sessionId}` });
-                return;
-            }
-            writeJson(res, 200, { session });
-            return;
-        }
-        const runDetailMatch = pathname.match(/^\/api\/runs\/([^/]+)$/);
-        if (runDetailMatch) {
-            const runId = decodeURIComponent(runDetailMatch[1] ?? '');
-            const result = await handleToolCall('night-orch-run-detail', { runId }, runtimeDeps);
-            writeJson(res, 200, result);
-            return;
-        }
-        const runEventsMatch = pathname.match(/^\/api\/runs\/([^/]+)\/events$/);
-        if (runEventsMatch) {
-            const runId = decodeURIComponent(runEventsMatch[1] ?? '');
-            const since = toBoundedInt(searchParams.get('since'), 0, 0, Number.MAX_SAFE_INTEGER);
-            const limit = toBoundedInt(searchParams.get('limit'), 100, 1, 200);
-            const result = await handleToolCall('night-orch-stream-events', { runId, since, limit }, runtimeDeps);
-            writeJson(res, 200, result);
-            return;
-        }
-        const repoIssuesMatch = pathname.match(/^\/api\/repos\/([^/]+)\/issues$/);
-        if (repoIssuesMatch) {
-            const repo = decodeURIComponent(repoIssuesMatch[1] ?? '');
-            const filter = searchParams.get('filter') ?? 'all';
-            const result = await handleToolCall('night-orch-list-issues', { repo, filter }, runtimeDeps);
-            writeJson(res, 200, result);
-            return;
-        }
-    }
-    if (method === 'POST' && pathname === '/api/operations/poll') {
-        const body = await readJsonBody(req);
-        const result = await handleToolCall('night-orch-poll', withMcpMutationAuth({ dryRun: Boolean(body['dryRun']) }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/sync') {
-        const body = await readJsonBody(req);
-        const result = await handleToolCall('night-orch-sync', withMcpMutationAuth({ dryRun: Boolean(body['dryRun']) }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/cleanup') {
-        const body = await readJsonBody(req);
-        const result = await handleToolCall('night-orch-cleanup', withMcpMutationAuth({ dryRun: Boolean(body['dryRun']) }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/labels-init') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        if (!repo) {
-            writeJson(res, 400, { error: 'repo is required' });
-            return;
-        }
-        const result = await handleToolCall('night-orch-labels-init', withMcpMutationAuth({
-            repo,
-            dryRun: Boolean(body['dryRun']),
-        }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/retry') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        const issueNumber = toBoundedInt(body['issueNumber'], NaN, 1, Number.MAX_SAFE_INTEGER);
-        if (!repo || Number.isNaN(issueNumber)) {
-            writeJson(res, 400, { error: 'repo and issueNumber are required' });
-            return;
-        }
-        const result = await handleToolCall('night-orch-retry', withMcpMutationAuth({
-            repo,
-            issueNumber,
-            resetPlan: Boolean(body['resetPlan']),
-            fresh: Boolean(body['fresh']),
-        }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/rebase') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        const issueNumber = toBoundedInt(body['issueNumber'], NaN, 1, Number.MAX_SAFE_INTEGER);
-        if (!repo || Number.isNaN(issueNumber)) {
-            writeJson(res, 400, { error: 'repo and issueNumber are required' });
-            return;
-        }
-        const result = await handleToolCall('night-orch-rebase', withMcpMutationAuth({
-            repo,
-            issueNumber,
-            check: body['check'] === undefined ? true : Boolean(body['check']),
-        }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/continue') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        const issueNumber = toBoundedInt(body['issueNumber'], NaN, 1, Number.MAX_SAFE_INTEGER);
-        if (!repo || Number.isNaN(issueNumber)) {
-            writeJson(res, 400, { error: 'repo and issueNumber are required' });
-            return;
-        }
-        const result = await handleToolCall('night-orch-continue', withMcpMutationAuth({
-            repo,
-            issueNumber,
-        }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/delete-entry') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        const issueNumber = toBoundedInt(body['issueNumber'], NaN, 1, Number.MAX_SAFE_INTEGER);
-        if (!repo || Number.isNaN(issueNumber)) {
-            writeJson(res, 400, { error: 'repo and issueNumber are required' });
-            return;
-        }
-        const result = await handleToolCall('night-orch-delete-entry', withMcpMutationAuth({
-            repo,
-            issueNumber,
-            force: Boolean(body['force']),
-            dryRun: Boolean(body['dryRun']),
-        }, security), runtimeDeps);
-        writeJson(res, 200, result);
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/daily-cost-override/set') {
-        const body = await readJsonBody(req);
-        const amountUsd = toFiniteNumber(body['amountUsd']);
-        if (amountUsd === null || amountUsd <= 0) {
-            writeJson(res, 400, { error: 'amountUsd must be a positive finite number' });
-            return;
-        }
-        try {
-            const result = await handleToolCall('night-orch-daily-cost-override', withMcpMutationAuth({ amountUsd }, security), runtimeDeps);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            writeJson(res, 400, { error: err.message });
-        }
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/daily-cost-override/clear') {
-        try {
-            const result = await handleToolCall('night-orch-daily-cost-override', withMcpMutationAuth({ clear: true }, security), runtimeDeps);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            writeJson(res, 400, { error: err.message });
-        }
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/cost-override/set') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        const issueNumber = toBoundedInt(body['issueNumber'], NaN, 1, Number.MAX_SAFE_INTEGER);
-        const amountUsd = toFiniteNumber(body['amountUsd']);
-        if (!repo || Number.isNaN(issueNumber)) {
-            writeJson(res, 400, { error: 'repo and issueNumber are required' });
-            return;
-        }
-        if (amountUsd === null || amountUsd <= 0) {
-            writeJson(res, 400, { error: 'amountUsd must be a positive finite number' });
-            return;
-        }
-        try {
-            const result = await handleToolCall('night-orch-cost-override', withMcpMutationAuth({ repo, issueNumber, amountUsd }, security), runtimeDeps);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            writeJson(res, 400, { error: err.message });
-        }
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/cost-override/clear') {
-        const body = await readJsonBody(req);
-        const repo = toNonEmptyString(body['repo']);
-        const issueNumber = toBoundedInt(body['issueNumber'], NaN, 1, Number.MAX_SAFE_INTEGER);
-        if (!repo || Number.isNaN(issueNumber)) {
-            writeJson(res, 400, { error: 'repo and issueNumber are required' });
-            return;
-        }
-        try {
-            const result = await handleToolCall('night-orch-cost-override', withMcpMutationAuth({ repo, issueNumber, clear: true }, security), runtimeDeps);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            writeJson(res, 400, { error: err.message });
-        }
+    if (await handleRunRoutes(req, res, method, pathname, searchParams, ctx))
         return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/settings/set') {
-        const body = await readJsonBody(req);
-        const key = toNonEmptyString(body['key']);
-        const value = body['value'];
-        if (!key || value === undefined) {
-            writeJson(res, 400, { error: 'key and value are required' });
-            return;
-        }
-        try {
-            const result = await handleToolCall('night-orch-set-setting', withMcpMutationAuth({ key, value }, security), deps);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            if (isRuntimeSettingInputError(err)) {
-                writeJson(res, 400, { error: err.message });
-                return;
-            }
-            throw err;
-        }
+    if (await handleSettingsRoutes(req, res, method, pathname, searchParams, ctx))
         return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/settings/clear') {
-        const body = await readJsonBody(req);
-        const key = toNonEmptyString(body['key']);
-        if (!key) {
-            writeJson(res, 400, { error: 'key is required' });
-            return;
-        }
-        try {
-            const result = await handleToolCall('night-orch-clear-setting', withMcpMutationAuth({ key }, security), deps);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            if (isRuntimeSettingInputError(err)) {
-                writeJson(res, 400, { error: err.message });
-                return;
-            }
-            throw err;
-        }
-        return;
-    }
-    if (method === 'GET' && pathname === '/api/update-status') {
-        const statusPath = resolve(homedir(), '.config', 'night-orch', 'update-status.json');
-        try {
-            const parsed = JSON.parse(readFileSync(statusPath, 'utf-8'));
-            const status = {
-                state: typeof parsed['state'] === 'string' ? parsed['state'] : 'idle',
-                ...(typeof parsed['error'] === 'string' ? { error: parsed['error'] } : {}),
-            };
-            writeJson(res, 200, status);
-        }
-        catch {
-            writeJson(res, 200, { state: 'idle' });
-        }
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/operations/update') {
-        // Try IPC first (running under supervisor)
-        if (typeof process.send === 'function') {
-            process.send({ type: 'update-requested' });
-            writeJson(res, 200, { accepted: true, method: 'ipc' });
-            return;
-        }
-        // Fallback: trigger file
-        const dataDir = resolve(homedir(), '.config', 'night-orch');
-        const triggerPath = resolve(dataDir, 'update-requested');
-        mkdirSync(dataDir, { recursive: true });
-        writeFileSync(triggerPath, nowUtcIso());
-        writeJson(res, 200, { accepted: true, method: 'trigger-file' });
-        return;
-    }
-    if (method === 'POST' && pathname === '/api/agent/sessions') {
-        const body = await readJsonBody(req);
-        const agentRaw = toNonEmptyString(body['agent']);
-        const profileName = toNonEmptyString(body['profileName']);
-        const cwd = toNonEmptyString(body['cwd']);
-        if (agentRaw !== 'claude' && agentRaw !== 'codex') {
-            writeJson(res, 400, { error: 'agent must be "claude" or "codex"' });
-            return;
-        }
-        try {
-            const session = agentSessionManager.createSession({
-                agent: agentRaw,
-                profileName,
-                cwd,
-            });
-            writeJson(res, 200, { session });
-        }
-        catch (err) {
-            writeJson(res, 400, { error: err.message });
-        }
-        return;
-    }
-    const agentSessionMessageMatch = pathname.match(/^\/api\/agent\/sessions\/([^/]+)\/messages$/);
-    if (method === 'POST' && agentSessionMessageMatch) {
-        const sessionId = decodeURIComponent(agentSessionMessageMatch[1] ?? '');
-        const body = await readJsonBody(req);
-        const prompt = toNonEmptyString(body['prompt']);
-        if (!prompt) {
-            writeJson(res, 400, { error: 'prompt is required' });
-            return;
-        }
-        try {
-            const result = agentSessionManager.sendPrompt(sessionId, prompt);
-            writeJson(res, 200, result);
-        }
-        catch (err) {
-            const message = err.message;
-            const statusCode = message.startsWith('Session not found:')
-                ? 404
-                : message.includes('running') || message.includes('closed')
-                    ? 409
-                    : 400;
-            writeJson(res, statusCode, { error: message });
-        }
-        return;
-    }
-    const agentSessionCloseMatch = pathname.match(/^\/api\/agent\/sessions\/([^/]+)$/);
-    if (method === 'DELETE' && agentSessionCloseMatch) {
-        const sessionId = decodeURIComponent(agentSessionCloseMatch[1] ?? '');
-        try {
-            const session = agentSessionManager.closeSession(sessionId);
-            writeJson(res, 200, { session });
-        }
-        catch (err) {
-            const message = err.message;
-            const statusCode = message.startsWith('Session not found:')
-                ? 404
-                : message.includes('running')
-                    ? 409
-                    : 400;
-            writeJson(res, statusCode, { error: message });
-        }
+    if (await handleOperationRoutes(req, res, method, pathname, searchParams, ctx))
         return;
-    }
     writeJson(res, 404, { error: `Unknown API route: ${method} ${pathname}` });
 }
 async function serveFrontend(req, res, pathname, frontendDistPath, hasFrontendAssets) {
@@ -660,9 +275,6 @@ async function serveFrontend(req, res, pathname, frontendDistPath, hasFrontendAs
     }
     const relativePath = pathname === '/' ? '/index.html' : pathname;
     const targetPath = resolve(frontendDistPath, `.${relativePath}`);
-    // Path-traversal guard: `targetPath.startsWith(frontendDistPath)` alone
-    // is insufficient — a sibling directory such as `frontendDistPath` +
-    // "-stash" would pass. Require exact match or a true subdirectory path.
     if (targetPath !== frontendDistPath && !targetPath.startsWith(frontendDistPath + sep)) {
         writeJson(res, 403, { error: 'Forbidden path' });
         return;
@@ -705,7 +317,11 @@ async function pickExistingFile(path) {
     }
     return null;
 }
-async function readJsonBody(req) {
+export function writeJson(res, status, payload) {
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(payload));
+}
+export async function readJsonBody(req) {
     const chunks = [];
     let size = 0;
     for await (const chunk of req) {
@@ -734,10 +350,50 @@ async function readJsonBody(req) {
         throw new Error(`Invalid JSON body: ${err.message}`);
     }
 }
+export function toBoundedInt(value, fallback, min, max) {
+    const parsed = typeof value === 'number'
+        ? value
+        : typeof value === 'string'
+            ? Number.parseInt(value, 10)
+            : NaN;
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+export function toNonEmptyString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function toFiniteNumber(value) {
+    const parsed = typeof value === 'number'
+        ? value
+        : typeof value === 'string'
+            ? Number.parseFloat(value)
+            : NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+}
+export function withMcpMutationAuth(args, security) {
+    if (!security.mcpMutationAuthToken) {
+        return args;
+    }
+    return {
+        ...args,
+        authToken: security.mcpMutationAuthToken,
+    };
+}
+export function sendWebsocket(ws, payload) {
+    if (ws.readyState !== WebSocket.OPEN)
+        return;
+    ws.send(JSON.stringify(payload));
+}
 function getRequestUrl(req) {
     return new URL(req.url ?? '/', 'http://localhost');
 }
-function validateMutationRequest(req, security) {
+export function validateMutationRequest(req, security) {
     if (!isAllowedRequestHost(req, security)) {
         return { statusCode: 403, error: 'Forbidden host' };
     }
@@ -761,6 +417,16 @@ function validateMutationRequest(req, security) {
     }
     return null;
 }
+function validateShellReadRequest(req, security) {
+    const webToken = getSingleHeaderValue(req.headers[WEB_AUTH_TOKEN_HEADER]);
+    if (!webToken) {
+        return { statusCode: 401, error: `Missing required header: ${WEB_AUTH_TOKEN_HEADER}` };
+    }
+    if (!isMatchingToken(webToken, security.webMutationToken)) {
+        return { statusCode: 403, error: 'Invalid web auth token' };
+    }
+    return null;
+}
 function hasAllowedOrigin(req, security, allowMissingOrigin) {
     const originHeader = getSingleHeaderValue(req.headers.origin);
     if (!originHeader) {
@@ -792,26 +458,7 @@ function getSingleHeaderValue(value) {
     }
     return null;
 }
-function withMcpMutationAuth(args, security) {
-    if (!security.mcpMutationAuthToken) {
-        return args;
-    }
-    return {
-        ...args,
-        authToken: security.mcpMutationAuthToken,
-    };
-}
 function createWebSecurityContext(deps, options) {
-    // When bound to a non-loopback address, the operator-supplied env var
-    // IS the mutation token. The startup guard in startWebServer() ensures
-    // the env var is set before we get here. Using it directly means the
-    // /api/session endpoint can refuse to disclose it — the operator gives
-    // the token to trusted clients out-of-band (browser extension, curl
-    // header, etc).
-    //
-    // For loopback binds, keep the random-per-process token and disclose it
-    // via /api/session as before — the risk is low when only local processes
-    // can reach the server.
     const operatorToken = process.env['NIGHT_ORCH_WEB_AUTH_TOKEN'];
     const bindHostName = normalizeHostname(options.host) ?? options.host;
     const isLoopback = bindHostName === '127.0.0.1'
@@ -921,393 +568,21 @@ function rejectUpgrade(socket, statusCode, message) {
         payload);
     socket.destroy();
 }
-function writeJson(res, status, payload) {
-    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
-    res.end(JSON.stringify(payload));
-}
-function toBoundedInt(value, fallback, min, max) {
-    const parsed = typeof value === 'number'
-        ? value
-        : typeof value === 'string'
-            ? Number.parseInt(value, 10)
-            : NaN;
-    if (!Number.isFinite(parsed)) {
-        return fallback;
-    }
-    return Math.max(min, Math.min(max, Math.floor(parsed)));
-}
-function toNonEmptyString(value) {
-    if (typeof value !== 'string') {
-        return null;
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function toFiniteNumber(value) {
-    const parsed = typeof value === 'number'
-        ? value
-        : typeof value === 'string'
-            ? Number.parseFloat(value)
-            : NaN;
-    return Number.isFinite(parsed) ? parsed : null;
-}
-async function buildDashboardSnapshot(deps) {
-    const runtimeConfig = resolveConfigWithRuntimeSettings(deps.config, deps.db);
-    const runtimeDeps = {
-        ...deps,
-        config: runtimeConfig,
-    };
-    const [status, runs, cost] = await Promise.all([
-        handleToolCall('night-orch-status', {}, runtimeDeps),
-        handleToolCall('night-orch-list-runs', { limit: 100 }, runtimeDeps),
-        handleToolCall('night-orch-cost-report', { days: 7 }, runtimeDeps),
-    ]);
-    return {
-        generatedAt: nowUtcIso(),
-        status,
-        runs,
-        cost,
-        build: BUILD_INFO,
-        config: {
-            repos: runtimeConfig.repos.map((repo) => repo.repo),
-            pollIntervalSeconds: runtimeConfig.github.pollIntervalSeconds,
-        },
-        stats: loadTuiStats(runtimeDeps.db, { costModel: runtimeConfig.cost.model }),
-    };
-}
-function buildProjectsSnapshot(deps) {
-    return {
-        generatedAt: nowUtcIso(),
-        githubDefaults: {
-            tokenEnv: deps.config.github.tokenEnv,
-            apiBaseUrl: deps.config.github.apiBaseUrl,
-        },
-        workerProfiles: Object.fromEntries(Object.entries(deps.config.workerProfiles).map(([name, profile]) => [
-            name,
-            sanitizeWorkerProfile(profile),
-        ])),
-        repos: deps.config.repos.map((repo) => sanitizeProjectRepo(repo)),
-    };
-}
-function buildSettingsSnapshot(deps, rawConfig) {
-    const runtimeSettings = listRuntimeSettings(deps.config, deps.db);
-    return {
-        generatedAt: nowUtcIso(),
-        settings: runtimeSettings.map((setting) => {
-            const definition = getSettingDefinition(setting.key);
-            if (!definition) {
-                return {
-                    ...setting,
-                    hasYamlValue: false,
-                    yamlValue: null,
-                };
-            }
-            const { hasYamlValue, yamlValue } = resolveSettingYamlValue(definition, rawConfig, deps.config);
-            return {
-                ...setting,
-                hasYamlValue,
-                yamlValue,
-            };
-        }),
-    };
-}
-function sanitizeWorkerProfile(profile) {
-    return {
-        type: profile.type,
-        command: profile.command,
-        args: [...profile.args],
-        workerTimeoutSeconds: profile.workerTimeoutSeconds,
-        minimalEnv: profile.minimalEnv,
-        runtimeWrapper: profile.runtimeWrapper,
-        envKeys: Object.keys(profile.env),
-    };
-}
-function sanitizeProjectRepo(repo) {
-    return {
-        repo: repo.repo,
-        forge: repo.forge,
-        linkedProjects: [...repo.linkedProjects],
-        apiBaseUrl: repo.apiBaseUrl,
-        tokenEnv: repo.tokenEnv,
-        maxConcurrentRuns: repo.maxConcurrentRuns,
-        localPath: repo.localPath,
-        baseBranch: repo.baseBranch,
-        branchPrefix: repo.branchPrefix,
-        labels: sanitizeLabels(repo.labels),
-        ...(repo.kanban
-            ? {
-                kanban: {
-                    triggerLabel: repo.kanban.triggerLabel,
-                    labels: sanitizeLabels(repo.kanban.labels),
-                },
-            }
-            : {}),
-        labelConfig: Object.fromEntries(Object.entries(repo.labelConfig).map(([label, config]) => [
-            label,
-            {
-                ...(config.color ? { color: config.color } : {}),
-                ...(config.description ? { description: config.description } : {}),
-            },
-        ])),
-        defaults: {
-            planner: repo.defaults.planner,
-            coder: repo.defaults.coder,
-            reviewer: repo.defaults.reviewer,
-            doneMode: repo.defaults.doneMode,
-            notifyPriority: repo.defaults.notifyPriority,
-            prMentions: [...repo.defaults.prMentions],
-        },
-        ...(repo.environment ? { environment: sanitizeEnvironment(repo.environment) } : {}),
-        verify: repo.verify.map((command) => copyCommandSpec(command)),
-        prompts: {
-            plannerSystem: Boolean(repo.prompts?.plannerSystem),
-            coderSystem: Boolean(repo.prompts?.coderSystem),
-            reviewerSystem: Boolean(repo.prompts?.reviewerSystem),
-        },
-        planning: {
-            prdDirectory: repo.planning.prdDirectory,
-        },
-        selectors: {
-            includeLabelsAny: [...repo.selectors.includeLabelsAny],
-            excludeLabelsAny: [...repo.selectors.excludeLabelsAny],
-        },
-        agents: { ...repo.agents },
-        ...(repo.workflow ? { workflow: repo.workflow } : {}),
-        ...(repo.workflowByTriage ? { workflowByTriage: { ...repo.workflowByTriage } } : {}),
-        mergeQueue: {
-            enabled: repo.mergeQueue.enabled,
-            batchSize: repo.mergeQueue.batchSize,
-            mergeMethod: repo.mergeQueue.mergeMethod,
-            retryFlakyOnce: repo.mergeQueue.retryFlakyOnce,
-            requireApproval: repo.mergeQueue.requireApproval,
-            stagingBranchPrefix: repo.mergeQueue.stagingBranchPrefix,
-        },
-    };
-}
-function sanitizeEnvironment(environment) {
-    return {
-        defaultMode: environment.defaultMode,
-        ...(environment.dedicated
-            ? {
-                dedicated: {
-                    compose: {
-                        file: environment.dedicated.compose.file,
-                        services: [...environment.dedicated.compose.services],
-                        projectName: environment.dedicated.compose.projectName,
-                    },
-                    env: {
-                        copyFrom: environment.dedicated.env.copyFrom,
-                        overrideKeys: Object.keys(environment.dedicated.env.overrides),
-                        overrideFiles: [...environment.dedicated.env.overrideFiles],
-                    },
-                    ...(environment.dedicated.healthcheck
-                        ? { healthcheck: copyCommandSpec(environment.dedicated.healthcheck) }
-                        : {}),
-                    teardownOnComplete: environment.dedicated.teardownOnComplete,
-                },
-            }
-            : {}),
-        ...(environment.shared
-            ? {
-                shared: {
-                    requireRunning: environment.shared.requireRunning,
-                    ...(environment.shared.healthcheck
-                        ? { healthcheck: copyCommandSpec(environment.shared.healthcheck) }
-                        : {}),
-                },
-            }
-            : {}),
-        bootstrap: environment.bootstrap.map((step) => ({
-            when: step.when,
-            command: copyCommandSpec(step.command),
-            ...(step.failureHints && step.failureHints.length > 0
-                ? {
-                    failureHints: step.failureHints.map((hint) => ({
-                        contains: hint.contains,
-                        message: hint.message,
-                        output: hint.output,
-                    })),
-                }
-                : {}),
-        })),
-        cleanup: environment.cleanup.map((step) => ({
-            when: step.when,
-            command: copyCommandSpec(step.command),
-            ...(step.failureHints && step.failureHints.length > 0
-                ? {
-                    failureHints: step.failureHints.map((hint) => ({
-                        contains: hint.contains,
-                        message: hint.message,
-                        output: hint.output,
-                    })),
-                }
-                : {}),
-        })),
-    };
-}
-function sanitizeLabels(labels) {
-    return {
-        ready: [...labels.ready],
-        running: labels.running,
-        blocked: normalizeLabelValue(labels.blocked),
-        needsHuman: labels.needsHuman,
-        reviewReady: labels.reviewReady,
-        error: labels.error,
-        retry: labels.retry,
-        planning: labels.planning,
-        mergeQueued: labels.mergeQueued,
-        merging: labels.merging,
-        mergeFailed: labels.mergeFailed,
-    };
-}
-function normalizeLabelValue(value) {
-    if (typeof value === 'string')
-        return value;
-    if (Array.isArray(value)) {
-        return value.find((entry) => typeof entry === 'string') ?? '';
-    }
-    return '';
-}
-function copyCommandSpec(command) {
-    if (Array.isArray(command)) {
-        return [...command];
-    }
-    return command;
-}
-async function handleWsMessage(ws, state, rawMessage, deps, agentSessionManager) {
-    let command;
+function resolveWebSocketAuthenticationState(request, security) {
+    let requestUrl;
     try {
-        command = JSON.parse(rawMessage);
+        requestUrl = getRequestUrl(request);
     }
     catch {
-        sendWebsocket(ws, { type: 'error', error: 'Invalid JSON message' });
-        return;
-    }
-    if (command.type === 'subscribe-run-events') {
-        const runId = typeof command.runId === 'string' ? command.runId : '';
-        if (!runId) {
-            sendWebsocket(ws, { type: 'error', error: 'runId is required for subscribe-run-events' });
-            return;
-        }
-        const cursor = Number.isFinite(command.since) ? Math.max(0, Math.floor(command.since ?? 0)) : 0;
-        state.runSubscriptions.set(runId, cursor);
-        sendWebsocket(ws, { type: 'subscribed', payload: { runId, since: cursor } });
-        return;
-    }
-    if (command.type === 'unsubscribe-run-events') {
-        const runId = typeof command.runId === 'string' ? command.runId : '';
-        if (!runId) {
-            sendWebsocket(ws, { type: 'error', error: 'runId is required for unsubscribe-run-events' });
-            return;
-        }
-        state.runSubscriptions.delete(runId);
-        sendWebsocket(ws, { type: 'unsubscribed', payload: { runId } });
-        return;
-    }
-    if (command.type === 'subscribe-agent-session-events') {
-        const sessionId = typeof command.sessionId === 'string' ? command.sessionId : '';
-        if (!sessionId) {
-            sendWebsocket(ws, { type: 'error', error: 'sessionId is required for subscribe-agent-session-events' });
-            return;
-        }
-        const cursor = Number.isFinite(command.since) ? Math.max(0, Math.floor(command.since ?? 0)) : 0;
-        state.agentSessionSubscriptions.set(sessionId, cursor);
-        sendWebsocket(ws, { type: 'subscribed', payload: { sessionId, since: cursor } });
-        publishAgentSessionSubscriptions(ws, state, agentSessionManager);
-        return;
-    }
-    if (command.type === 'unsubscribe-agent-session-events') {
-        const sessionId = typeof command.sessionId === 'string' ? command.sessionId : '';
-        if (!sessionId) {
-            sendWebsocket(ws, { type: 'error', error: 'sessionId is required for unsubscribe-agent-session-events' });
-            return;
-        }
-        state.agentSessionSubscriptions.delete(sessionId);
-        sendWebsocket(ws, { type: 'unsubscribed', payload: { sessionId } });
-        return;
-    }
-    if (command.type === 'refresh') {
-        const snapshot = await buildDashboardSnapshot(deps);
-        sendWebsocket(ws, { type: 'snapshot', payload: snapshot });
-        return;
-    }
-    sendWebsocket(ws, { type: 'error', error: 'Unknown command type' });
-}
-async function publishRunSubscriptions(ws, state, deps) {
-    for (const [runId, since] of state.runSubscriptions.entries()) {
-        try {
-            const result = await handleToolCall('night-orch-stream-events', { runId, since, limit: 200 }, deps);
-            const eventPayload = toRunEventPayload(result);
-            if (!eventPayload) {
-                continue;
-            }
-            state.runSubscriptions.set(runId, eventPayload.lastEventId);
-            if (eventPayload.events.length === 0) {
-                continue;
-            }
-            sendWebsocket(ws, {
-                type: 'run-events',
-                payload: {
-                    runId,
-                    events: eventPayload.events,
-                    lastEventId: eventPayload.lastEventId,
-                },
-            });
-        }
-        catch (err) {
-            sendWebsocket(ws, {
-                type: 'error',
-                error: `Failed to stream events for ${runId}: ${err.message}`,
-            });
-        }
+        return false;
     }
-}
-function publishAgentSessionSubscriptions(ws, state, manager) {
-    for (const [sessionId, since] of state.agentSessionSubscriptions.entries()) {
-        let result;
-        try {
-            result = manager.getEvents(sessionId, since, 200);
-        }
-        catch (err) {
-            sendWebsocket(ws, {
-                type: 'error',
-                error: `Failed to stream agent-session events for ${sessionId}: ${err.message}`,
-            });
-            continue;
-        }
-        state.agentSessionSubscriptions.set(sessionId, result.lastEventId);
-        if (result.events.length === 0) {
-            continue;
-        }
-        sendWebsocket(ws, {
-            type: 'agent-session-events',
-            payload: {
-                sessionId,
-                status: result.status,
-                events: result.events,
-                lastEventId: result.lastEventId,
-            },
-        });
+    const queryToken = requestUrl.searchParams.get('token');
+    const headerToken = getSingleHeaderValue(request.headers[WEB_AUTH_TOKEN_HEADER]);
+    const providedToken = toNonEmptyString(queryToken) ?? headerToken;
+    if (!providedToken) {
+        return false;
     }
-}
-function toRunEventPayload(input) {
-    if (!input || typeof input !== 'object')
-        return null;
-    const maybeEvents = input.events;
-    const maybeLastEventId = input.lastEventId;
-    if (!Array.isArray(maybeEvents))
-        return null;
-    if (typeof maybeLastEventId !== 'number' || !Number.isFinite(maybeLastEventId))
-        return null;
-    return {
-        events: maybeEvents,
-        lastEventId: Math.max(0, Math.floor(maybeLastEventId)),
-    };
-}
-function sendWebsocket(ws, payload) {
-    if (ws.readyState !== WebSocket.OPEN)
-        return;
-    ws.send(JSON.stringify(payload));
+    return isMatchingToken(providedToken, security.webMutationToken);
 }
 function isClientRequestError(message) {
     return message.startsWith('Invalid JSON body') || message === 'Request body too large';
@@ -1315,12 +590,6 @@ function isClientRequestError(message) {
 function isAuthorizationError(message) {
     return message.startsWith('Unauthorized:');
 }
-function isRuntimeSettingInputError(err) {
-    if (err instanceof RuntimeSettingInputError) {
-        return true;
-    }
-    return err instanceof Error && err.name === 'RuntimeSettingInputError';
-}
 function decodeWsMessage(raw) {
     if (typeof raw === 'string') {
         return raw;