@aexol/spectral 0.9.230 → 0.9.234

package/dist/relay/dispatcher.js

@@ -37,1145 +37,25 @@
  *  - Backend cancels pending REST requests with `code:"timeout"` (30 s)
  *    or `code:"machine_offline"` (CLI socket dropped). Both are
  *    transparent to this layer — we just respond when we can.
+ *
+ * Path matching + the REST request handler + the wizard login flow live in
+ * sibling modules (`routing.ts`, `rest.ts`, `wizard-login.ts`) and are
+ * re-exported below so existing imports from `relay/dispatcher.js` keep
+ * working.
  */
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
-import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
-import { handleListMcpStatus } from "../server/handlers/mcp-status.js";
-import { handleReloadMcpConfig } from "../server/handlers/mcp-reload.js";
-import { handlePathAutocomplete } from "../server/handlers/paths-autocomplete.js";
-import { handleGetHomeDirectory } from "../server/handlers/paths-home.js";
-import { handleListDirectory } from "../server/handlers/paths-list.js";
-import { handleSearchProjectFiles } from "../server/handlers/files-search.js";
-import { handleBindStudioProject, handleUnbindStudioProject, handleCleanupProjectSessions, handleCreateProject, handleDeleteProject, handleGetProjectObservations, handleListProjectsAsync, handleListSessionsByProjectAsync, handleUpdateProject, } from "../server/handlers/projects.js";
-import { handleCompactSession, handleCleanupAllSessions, handleCreateSession, handleDeleteSession, handleForkSession, handleRememberAndDeleteSession, handleGetSessionDetailAsync, handleGetSessionMessagesAsync, handleGetSessionMemoryDetails, handleGetSessionMemoryStatus, handleUpdateSession, handleGetSessionActiveAgentAsync, handleUpdateSessionActiveAgentAsync, } from "../server/handlers/sessions.js";
-import { handleClearPromptQueue, handleEnqueuePrompt, handleGetPromptQueue, handleRemovePrompt, } from "../server/handlers/queue.js";
-import { handleGetAgentSettingsAsync, handleListAgents, handlePutAgentSettingsAsync, } from "../server/handlers/agent-settings.js";
-import { handleGetSettingsAsync, handlePutSettingsAsync, } from "../server/handlers/settings.js";
-import { handleGetPromptMutationSettings, handlePutPromptMutationSettings, } from "../server/handlers/prompt-mutation-settings.js";
 import { shutdownState } from "../server/shutdown.js";
 import { coerceImages, hasImages, MAX_INLINE_IMAGE_BASE64_CHARS, } from "../server/image-attachments.js";
 import { humanizeProviderError } from "../server/error-humanizer.js";
-import { handleKillDevProcess, handleKillDetectedDevServer, handleListDevProcesses, handleRestartDevProcess, handleScanDevServers, handleStartDevProcess, } from "../server/handlers/dev-processes.js";
 import { handleAutoResearch } from "./auto-research.js";
 import { handleAutoOptimize } from "./auto-optimizer.js";
 import { chunkHistory } from "./history-chunker.js";
 import { gzipEncodeMessages, shouldCompressHistory } from "./history-compression.js";
 import { projectHistoryForReplay } from "./history-projection.js";
-/**
- * Inline path matcher. Returns `null` for any path/method combination we
- * don't recognise; the caller turns that into a `404 Unknown route`.
- *
- * Intentionally literal — a regex table would be marginally fancier but
- * also marginally slower and harder to read for ~11 routes.
- */
-export function matchRoute(method, path) {
-    // Strip query string for path matching but keep it for the handler.
-    const qIdx = path.indexOf("?");
-    const cleanPath = qIdx === -1 ? path : path.slice(0, qIdx);
-    const query = qIdx >= 0 ? new URLSearchParams(path.slice(qIdx + 1)) : undefined;
-    // /api/mcp-status
-    if (cleanPath === "/api/mcp-status") {
-        if (method === "GET")
-            return { route: "list_mcp_status" };
-        return null;
-    }
-    if (cleanPath === "/api/mcp-reload") {
-        if (method === "POST")
-            return { route: "reload_mcp_config" };
-        return null;
-    }
-    if (cleanPath === "/api/native-extensions/refresh") {
-        if (method === "POST")
-            return { route: "refresh_native_extensions" };
-        return null;
-    }
-    if (cleanPath === "/api/cloud-agents/refresh") {
-        if (method === "POST")
-            return { route: "refresh_cloud_agents" };
-        return null;
-    }
-    if (cleanPath === "/api/wizard/login") {
-        if (method === "POST")
-            return { route: "wizard_login" };
-        return null;
-    }
-    // /api/settings
-    if (cleanPath === "/api/settings") {
-        if (method === "GET")
-            return { route: "get_settings" };
-        if (method === "PUT")
-            return { route: "put_settings" };
-        return null;
-    }
-    // /api/agent-settings
-    if (cleanPath === "/api/agent-settings") {
-        if (method === "GET")
-            return { route: "get_agent_settings" };
-        if (method === "PUT")
-            return { route: "put_agent_settings" };
-        return null;
-    }
-    if (cleanPath === "/api/prompt-mutation-settings") {
-        if (method === "GET")
-            return { route: "get_prompt_mutation_settings" };
-        if (method === "PUT")
-            return { route: "put_prompt_mutation_settings" };
-        return null;
-    }
-    // /api/agents
-    if (cleanPath === "/api/agents") {
-        if (method === "GET")
-            return { route: "list_agents", query };
-        return null;
-    }
-    // /api/paths/autocomplete
-    if (cleanPath === "/api/paths/autocomplete") {
-        if (method === "GET")
-            return { route: "list_path_autocomplete", query };
-        return null;
-    }
-    // /api/paths/list
-    if (cleanPath === "/api/paths/list") {
-        if (method === "POST")
-            return { route: "list_directory" };
-        return null;
-    }
-    // /api/paths/home
-    if (cleanPath === "/api/paths/home") {
-        if (method === "POST")
-            return { route: "get_home_directory" };
-        return null;
-    }
-    // /api/projects
-    if (cleanPath === "/api/projects") {
-        if (method === "GET")
-            return { route: "list_projects" };
-        if (method === "POST")
-            return { route: "create_project" };
-        return null;
-    }
-    // /api/sessions
-    if (cleanPath === "/api/sessions") {
-        if (method === "POST")
-            return { route: "create_session" };
-        return null;
-    }
-    // /api/projects/:id/files/search
-    const projectFilesMatch = /^\/api\/projects\/([^/]+)\/files\/search$/.exec(cleanPath);
-    if (projectFilesMatch) {
-        const id = decodeURIComponent(projectFilesMatch[1]);
-        if (method === "GET")
-            return { route: "search_project_files", id, query };
-        return null;
-    }
-    // /api/projects/:id/bind-studio  and  /api/projects/:id/unbind-studio
-    const bindStudioMatch = /^\/api\/projects\/([^/]+)\/bind-studio$/.exec(cleanPath);
-    if (bindStudioMatch) {
-        const id = decodeURIComponent(bindStudioMatch[1]);
-        if (method === "POST")
-            return { route: "bind_studio", id };
-        return null;
-    }
-    const unbindStudioMatch = /^\/api\/projects\/([^/]+)\/unbind-studio$/.exec(cleanPath);
-    if (unbindStudioMatch) {
-        const id = decodeURIComponent(unbindStudioMatch[1]);
-        if (method === "POST")
-            return { route: "unbind_studio", id };
-        return null;
-    }
-    // /api/projects/:id/observations
-    const projectObsMatch = /^\/api\/projects\/([^/]+)\/observations$/.exec(cleanPath);
-    if (projectObsMatch) {
-        const id = decodeURIComponent(projectObsMatch[1]);
-        if (method === "GET")
-            return { route: "get_project_observations", id };
-        return null;
-    }
-    // /api/projects/:id  and  /api/projects/:id/sessions
-    const projectMatch = /^\/api\/projects\/([^/]+)(\/sessions)?$/.exec(cleanPath);
-    if (projectMatch) {
-        const id = decodeURIComponent(projectMatch[1]);
-        const isSessions = projectMatch[2] === "/sessions";
-        if (isSessions) {
-            if (method === "GET")
-                return { route: "list_project_sessions", id };
-            return null;
-        }
-        if (method === "PATCH")
-            return { route: "update_project", id };
-        if (method === "DELETE")
-            return { route: "delete_project", id };
-        return null;
-    }
-    // /api/projects/:id/cleanup-sessions
-    const projectCleanupMatch = /^\/api\/projects\/([^/]+)\/cleanup-sessions$/.exec(cleanPath);
-    if (projectCleanupMatch) {
-        const id = decodeURIComponent(projectCleanupMatch[1]);
-        if (method === "POST")
-            return { route: "cleanup_project_sessions", id };
-        return null;
-    }
-    // /api/sessions/cleanup (must precede the /api/sessions/:id matches —
-    // "cleanup" would otherwise be captured as an :id)
-    if (cleanPath === "/api/sessions/cleanup") {
-        if (method === "POST")
-            return { route: "cleanup_all_sessions" };
-        return null;
-    }
-    // /api/sessions/:id
-    const sessionMessagesMatch = /^\/api\/sessions\/([^/]+)\/messages$/.exec(cleanPath);
-    if (sessionMessagesMatch) {
-        const id = decodeURIComponent(sessionMessagesMatch[1]);
-        if (method === "GET")
-            return { route: "get_session_messages", id, query };
-        return null;
-    }
-    const sessionMatch = /^\/api\/sessions\/([^/]+)$/.exec(cleanPath);
-    if (sessionMatch) {
-        const id = decodeURIComponent(sessionMatch[1]);
-        if (method === "GET")
-            return { route: "get_session", id };
-        if (method === "PATCH")
-            return { route: "update_session", id };
-        if (method === "DELETE")
-            return { route: "delete_session", id };
-        return null;
-    }
-    const sessionAgentMatch = /^\/api\/sessions\/([^/]+)\/active-agent$/.exec(cleanPath);
-    if (sessionAgentMatch) {
-        const id = decodeURIComponent(sessionAgentMatch[1]);
-        if (method === "GET")
-            return { route: "get_session_active_agent", id };
-        if (method === "PUT")
-            return { route: "update_session_active_agent", id };
-        return null;
-    }
-    // /api/sessions/:id/memory/details and /api/sessions/:id/memory and /api/sessions/:id/compact
-    const sessionActionMatch = /^\/api\/sessions\/([^/]+)\/(memory(?:\/details)?|compact)$/.exec(cleanPath);
-    if (sessionActionMatch) {
-        const id = decodeURIComponent(sessionActionMatch[1]);
-        const action = sessionActionMatch[2];
-        if (action === "memory" && method === "GET")
-            return { route: "get_session_memory", id };
-        if (action === "memory/details" && method === "GET")
-            return { route: "get_session_memory_details", id };
-        if (action === "compact" && method === "POST")
-            return { route: "compact_session", id };
-        return null;
-    }
-    // /api/sessions/:id/remember-and-delete
-    const rememberDeleteMatch = /^\/api\/sessions\/([^/]+)\/remember-and-delete$/.exec(cleanPath);
-    if (rememberDeleteMatch) {
-        const id = decodeURIComponent(rememberDeleteMatch[1]);
-        if (method === "POST")
-            return { route: "remember_and_delete_session", id };
-        return null;
-    }
-    // /api/sessions/:id/fork
-    const forkMatch = /^\/api\/sessions\/([^/]+)\/fork$/.exec(cleanPath);
-    if (forkMatch) {
-        const id = decodeURIComponent(forkMatch[1]);
-        if (method === "POST")
-            return { route: "fork_session", id };
-        return null;
-    }
-    // /api/sessions/:id/queue  and  /api/sessions/:id/queue/:itemId
-    const queueMatch = /^\/api\/sessions\/([^/]+)\/queue(\/([^/]+))?$/.exec(cleanPath);
-    if (queueMatch) {
-        const id = decodeURIComponent(queueMatch[1]);
-        const itemId = queueMatch[3] ? decodeURIComponent(queueMatch[3]) : undefined;
-        if (!itemId) {
-            if (method === "GET")
-                return { route: "get_prompt_queue", id };
-            if (method === "POST")
-                return { route: "enqueue_prompt", id };
-            if (method === "DELETE")
-                return { route: "clear_prompt_queue", id };
-        }
-        else {
-            if (method === "DELETE")
-                return { route: "remove_prompt", id, itemId };
-        }
-        return null;
-    }
-    // /api/dev-processes and /api/dev-processes/:id
-    if (cleanPath === "/api/dev-processes") {
-        if (method === "GET")
-            return { route: "list_dev_processes" };
-        if (method === "POST")
-            return { route: "start_dev_process" };
-        return null;
-    }
-    const restartDevProcessMatch = /^\/api\/dev-processes\/([^/]+)\/restart$/.exec(cleanPath);
-    if (restartDevProcessMatch) {
-        const id = decodeURIComponent(restartDevProcessMatch[1]);
-        if (method === "POST")
-            return { route: "restart_dev_process", id };
-        return null;
-    }
-    const devProcessMatch = /^\/api\/dev-processes\/([^/]+)$/.exec(cleanPath);
-    if (devProcessMatch) {
-        const id = decodeURIComponent(devProcessMatch[1]);
-        if (method === "DELETE")
-            return { route: "kill_dev_process", id };
-        return null;
-    }
-    // /api/dev-servers and /api/dev-servers/:pid
-    if (cleanPath === "/api/dev-servers") {
-        if (method === "GET")
-            return { route: "scan_dev_servers" };
-        return null;
-    }
-    const devServerMatch = /^\/api\/dev-servers\/([^/]+)$/.exec(cleanPath);
-    if (devServerMatch) {
-        const id = decodeURIComponent(devServerMatch[1]);
-        if (method === "DELETE") {
-            const rawPort = query?.get("port");
-            const parsedPort = rawPort === null ? Number.NaN : Number(rawPort);
-            const port = Number.isFinite(parsedPort) ? parsedPort : undefined;
-            return port === undefined
-                ? { route: "kill_dev_server", id }
-                : { route: "kill_dev_server", id, port };
-        }
-        return null;
-    }
-    return null;
-}
-const WIZARD_PACKAGE_NAME = "@aexol/wizard-spectral";
-const WIZARD_CLI_BIN_NAME = "spectral-wizard";
-const WIZARD_LOGIN_STARTUP_TIMEOUT_MS = 5_000;
-const requireForWizard = createRequire(import.meta.url);
-let activeWizardLoginRun = null;
-let activeWizardLoginStartPromise = null;
-function getActiveWizardLoginRun() {
-    const run = activeWizardLoginRun;
-    if (!run)
-        return null;
-    if (run.child.exitCode !== null || run.child.killed) {
-        activeWizardLoginRun = null;
-        return null;
-    }
-    return run;
-}
-function toSafeErrorMessage(error) {
-    if (error instanceof Error)
-        return error.message;
-    if (typeof error === "string")
-        return error;
-    return "Unknown error";
-}
-function asRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return null;
-    }
-    return value;
-}
-function findWizardPackageJsonFromEntry(entryPath) {
-    let current = dirname(entryPath);
-    for (let depth = 0; depth < 8; depth += 1) {
-        const candidate = join(current, "package.json");
-        if (existsSync(candidate)) {
-            try {
-                const packageJson = JSON.parse(readFileSync(candidate, "utf8"));
-                if (asRecord(packageJson)?.name === WIZARD_PACKAGE_NAME)
-                    return candidate;
-            }
-            catch {
-                // Keep walking upward; malformed metadata is handled by the final reader.
-            }
-        }
-        const parent = dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-    return undefined;
-}
-function resolveWizardPackageJsonPath() {
-    try {
-        return { ok: true, path: requireForWizard.resolve(`${WIZARD_PACKAGE_NAME}/package.json`) };
-    }
-    catch (error) {
-        try {
-            const entryPath = requireForWizard.resolve(WIZARD_PACKAGE_NAME);
-            const packageJsonPath = findWizardPackageJsonFromEntry(entryPath);
-            if (packageJsonPath)
-                return { ok: true, path: packageJsonPath };
-        }
-        catch {
-            // Fall through to the original package-unavailable message.
-        }
-        return {
-            ok: false,
-            message: `${WIZARD_PACKAGE_NAME} is not available on this machine: ${toSafeErrorMessage(error)}`,
-        };
-    }
-}
-function readWizardPackageJson(packageJsonPath) {
-    try {
-        return { ok: true, json: JSON.parse(readFileSync(packageJsonPath, "utf8")) };
-    }
-    catch (error) {
-        return {
-            ok: false,
-            message: `Could not read ${WIZARD_PACKAGE_NAME} package metadata: ${toSafeErrorMessage(error)}`,
-        };
-    }
-}
-function getWizardBinRelativePath(packageJson) {
-    const pkg = asRecord(packageJson);
-    const bin = pkg?.bin;
-    if (typeof bin === "string" && bin.trim())
-        return bin;
-    const binRecord = asRecord(bin);
-    const namedBin = binRecord?.[WIZARD_CLI_BIN_NAME];
-    return typeof namedBin === "string" && namedBin.trim() ? namedBin : undefined;
-}
-function findWindowsBinShim(packageRoot) {
-    let current = packageRoot;
-    for (let depth = 0; depth < 8; depth += 1) {
-        const candidate = join(current, "node_modules", ".bin", `${WIZARD_CLI_BIN_NAME}.cmd`);
-        if (existsSync(candidate))
-            return candidate;
-        const parent = dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-    return undefined;
-}
-function resolveWizardBinCommand() {
-    const packageJsonPath = resolveWizardPackageJsonPath();
-    if (!packageJsonPath.ok)
-        return packageJsonPath;
-    const packageJson = readWizardPackageJson(packageJsonPath.path);
-    if (!packageJson.ok)
-        return packageJson;
-    const binRelativePath = getWizardBinRelativePath(packageJson.json);
-    if (!binRelativePath) {
-        return {
-            ok: false,
-            message: `${WIZARD_PACKAGE_NAME} is installed but does not expose a ${WIZARD_CLI_BIN_NAME} bin.`,
-        };
-    }
-    const packageRoot = dirname(packageJsonPath.path);
-    const packageBinPath = isAbsolute(binRelativePath)
-        ? binRelativePath
-        : join(packageRoot, binRelativePath);
-    if (process.platform === "win32") {
-        const cmdShim = findWindowsBinShim(packageRoot);
-        if (cmdShim) {
-            return {
-                ok: true,
-                bin: { command: cmdShim, argsPrefix: [] },
-            };
-        }
-    }
-    return {
-        ok: true,
-        bin: { command: packageBinPath, argsPrefix: [] },
-    };
-}
-function collectWizardTools(value) {
-    if (Array.isArray(value))
-        return value;
-    const record = asRecord(value);
-    const tools = record?.tools;
-    return Array.isArray(tools) ? tools : [];
-}
-function findWizardStatusTool(tools) {
-    for (const tool of tools) {
-        const record = asRecord(tool);
-        if (record?.name !== "wizard_status" || typeof record.execute !== "function") {
-            continue;
-        }
-        return {
-            execute: record.execute,
-        };
-    }
-    return null;
-}
-function normalizeWizardAuthStatus(value) {
-    const normalized = value.trim().toLowerCase().replace(/[\s-]+/g, "_");
-    if (normalized === "configured" ||
-        normalized === "authenticated" ||
-        normalized === "ready" ||
-        normalized === "ok" ||
-        normalized === "connected") {
-        return "configured";
-    }
-    if (normalized === "missing_auth" ||
-        normalized === "auth_missing" ||
-        normalized === "needs_auth" ||
-        normalized === "not_authenticated" ||
-        normalized === "unauthenticated" ||
-        normalized === "not_configured") {
-        return "missing_auth";
-    }
-    return "unknown";
-}
-function parseWizardAuthStatusFromObject(record) {
-    for (const key of ["status", "authStatus", "state"]) {
-        const raw = record[key];
-        if (typeof raw !== "string")
-            continue;
-        const status = normalizeWizardAuthStatus(raw);
-        if (status !== "unknown")
-            return status;
-    }
-    for (const key of ["configured", "authenticated", "isAuthenticated", "hasAuth"]) {
-        const raw = record[key];
-        if (typeof raw === "boolean")
-            return raw ? "configured" : "missing_auth";
-    }
-    return "unknown";
-}
-function parseWizardAuthStatus(statusOutput) {
-    const candidates = [statusOutput];
-    const outputRecord = asRecord(statusOutput);
-    if (outputRecord) {
-        candidates.push(outputRecord.details, outputRecord.data, outputRecord.result);
-    }
-    for (const candidate of candidates) {
-        const record = asRecord(candidate);
-        if (!record)
-            continue;
-        const status = parseWizardAuthStatusFromObject(record);
-        if (status !== "unknown")
-            return status;
-    }
-    return "unknown";
-}
-async function checkWizardAuthStatus(directory) {
-    let importedModule;
-    try {
-        importedModule = await import(WIZARD_PACKAGE_NAME);
-    }
-    catch (error) {
-        return {
-            status: "package_unavailable",
-            message: `${WIZARD_PACKAGE_NAME} is not available on this machine: ${toSafeErrorMessage(error)}`,
-        };
-    }
-    const buildSpectralTools = asRecord(importedModule)?.buildSpectralTools;
-    if (typeof buildSpectralTools !== "function") {
-        return {
-            status: "unknown",
-            message: "Wizard status API is unavailable; starting login.",
-        };
-    }
-    try {
-        const tools = collectWizardTools(await buildSpectralTools());
-        const statusTool = findWizardStatusTool(tools);
-        if (!statusTool) {
-            return {
-                status: "unknown",
-                message: "Wizard status tool is unavailable; starting login.",
-            };
-        }
-        const status = parseWizardAuthStatus(await statusTool.execute("wizard-ui-login-status", { directory }));
-        return {
-            status,
-            message: status === "configured"
-                ? "Wizard is already authenticated."
-                : "Wizard authentication is missing; starting login.",
-        };
-    }
-    catch (error) {
-        return {
-            status: "unknown",
-            message: `Could not check Wizard auth status; starting login: ${toSafeErrorMessage(error)}`,
-        };
-    }
-}
-function wizardLoginResult(status, message, run) {
-    return {
-        status,
-        packageName: WIZARD_PACKAGE_NAME,
-        message,
-        loginUrl: run?.loginUrl,
-        startedAt: run?.startedAt,
-    };
-}
-function extractLoginUrl(text) {
-    const matches = text.match(/https?:\/\/[^\s"'<>]+/g) ?? [];
-    for (const raw of matches) {
-        const candidate = raw.replace(/[),.;]+$/, "");
-        if (isSafeLoginUrl(candidate))
-            return candidate;
-    }
-    return undefined;
-}
-function isSafeLoginUrl(value) {
-    try {
-        const url = new URL(value);
-        if (url.protocol !== "https:" && url.protocol !== "http:")
-            return false;
-        const forbiddenQueryKeys = new Set([
-            "access_token",
-            "id_token",
-            "refresh_token",
-            "token",
-            "jwt",
-            "code",
-        ]);
-        for (const key of url.searchParams.keys()) {
-            if (forbiddenQueryKeys.has(key.toLowerCase()))
-                return false;
-        }
-        if (/(^|[#&])(access_token|id_token|refresh_token|token|jwt|code)=/i.test(url.hash)) {
-            return false;
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export async function startWizardLogin(directory = homedir()) {
-    const existing = getActiveWizardLoginRun();
-    if (existing) {
-        return wizardLoginResult("already_running", existing.loginUrl
-            ? "Wizard login is already running. Complete the browser flow."
-            : "Wizard login is already running. Complete the browser flow if it has opened.", existing);
-    }
-    if (activeWizardLoginStartPromise)
-        return await activeWizardLoginStartPromise;
-    const startPromise = startWizardLoginInternal(directory);
-    activeWizardLoginStartPromise = startPromise;
-    try {
-        return await startPromise;
-    }
-    finally {
-        if (activeWizardLoginStartPromise === startPromise) {
-            activeWizardLoginStartPromise = null;
-        }
-    }
-}
-async function startWizardLoginInternal(directory) {
-    const authStatus = await checkWizardAuthStatus(directory);
-    if (authStatus.status === "configured") {
-        return {
-            status: "configured",
-            packageName: WIZARD_PACKAGE_NAME,
-            message: "Wizard is already authenticated; no login needed.",
-        };
-    }
-    if (authStatus.status === "package_unavailable") {
-        return {
-            status: "package_unavailable",
-            packageName: WIZARD_PACKAGE_NAME,
-            message: authStatus.message,
-        };
-    }
-    const existing = getActiveWizardLoginRun();
-    if (existing) {
-        return wizardLoginResult("already_running", existing.loginUrl
-            ? "Wizard login is already running. Complete the browser flow."
-            : "Wizard login is already running. Complete the browser flow if it has opened.", existing);
-    }
-    const bin = resolveWizardBinCommand();
-    if (!bin.ok) {
-        return {
-            status: "package_unavailable",
-            packageName: WIZARD_PACKAGE_NAME,
-            message: bin.message,
-        };
-    }
-    const child = spawn(bin.bin.command, [...bin.bin.argsPrefix, "login"], {
-        stdio: ["ignore", "pipe", "pipe"],
-        env: process.env,
-        cwd: directory,
-    });
-    const run = { child, startedAt: Date.now() };
-    activeWizardLoginRun = run;
-    return await new Promise((resolve) => {
-        let settled = false;
-        let timeout;
-        const finish = (result) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeout);
-            resolve(result);
-        };
-        const onData = (chunk) => {
-            if (run.loginUrl)
-                return;
-            const loginUrl = extractLoginUrl(chunk.toString("utf8"));
-            if (!loginUrl)
-                return;
-            run.loginUrl = loginUrl;
-            finish(wizardLoginResult("login_url_observed", "Wizard login started. Complete the browser flow to finish authentication.", run));
-        };
-        const onError = (error) => {
-            if (activeWizardLoginRun === run)
-                activeWizardLoginRun = null;
-            child.stdout?.off("data", onData);
-            child.stderr?.off("data", onData);
-            finish({
-                status: "spawn_failed",
-                packageName: WIZARD_PACKAGE_NAME,
-                message: `Could not start Wizard login: ${toSafeErrorMessage(error)}`,
-            });
-        };
-        const onExit = (code, signal) => {
-            if (activeWizardLoginRun === run)
-                activeWizardLoginRun = null;
-            child.stdout?.off("data", onData);
-            child.stderr?.off("data", onData);
-            const exitLabel = signal ? `signal ${signal}` : `code ${code ?? "unknown"}`;
-            const completed = code === 0 && signal === null;
-            finish(wizardLoginResult(completed ? "completed" : "exited", completed
-                ? "Wizard login completed."
-                : `Wizard login exited before emitting a login URL (${exitLabel}).`, run));
-        };
-        timeout = setTimeout(() => {
-            finish(wizardLoginResult("started", "Wizard login started. Complete the browser flow if it has opened.", run));
-        }, WIZARD_LOGIN_STARTUP_TIMEOUT_MS);
-        child.stdout?.on("data", onData);
-        child.stderr?.on("data", onData);
-        child.once("error", onError);
-        child.once("exit", onExit);
-    });
-}
-/**
- * Dispatch a `rest_request` frame. Always resolves with a
- * `RestResponseFrame` — handler exceptions are caught and translated.
- *
- * Status mapping:
- *  - 200: handler returned successfully (body is the handler's return value
- *         or `{ ok: true }` for void returns)
- *  - 400: `BadRequestError` thrown by handler, OR malformed body for a
- *         route that requires one, OR unknown route
- *  - 404: `NotFoundError` thrown by handler
- *  - 405: route matches but method doesn't (returned as 404 since we don't
- *         distinguish — the matcher treats it as "no route", consistent
- *         with the original Hono router which also 404'd)
- *  - 500: anything else; `error` field carries a sanitized message
- */
-export async function handleRestRequest(frame, deps) {
-    const { reqId, method, path, body } = frame;
-    const logger = deps.logger ?? console;
-    const startedAt = performance.now();
-    logger.info?.(`[rest] start machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId}`);
-    const match = matchRoute(method, path);
-    if (!match) {
-        logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=404 durationMs=${Math.round(performance.now() - startedAt)}`);
-        return {
-            kind: "rest_response",
-            reqId,
-            status: 404,
-            body: { error: `Unknown route: ${method} ${path}` },
-        };
-    }
-    try {
-        const result = await dispatchRoute(match, body, deps);
-        logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=200 durationMs=${Math.round(performance.now() - startedAt)}`);
-        return {
-            kind: "rest_response",
-            reqId,
-            status: 200,
-            body: result,
-        };
-    }
-    catch (err) {
-        if (err instanceof BadRequestError) {
-            logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=400 durationMs=${Math.round(performance.now() - startedAt)}`);
-            return {
-                kind: "rest_response",
-                reqId,
-                status: 400,
-                body: { error: err.message, code: err.code },
-            };
-        }
-        if (err instanceof NotFoundError) {
-            logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=404 durationMs=${Math.round(performance.now() - startedAt)}`);
-            return {
-                kind: "rest_response",
-                reqId,
-                status: 404,
-                body: { error: err.message, code: err.code },
-            };
-        }
-        // Unexpected — log locally so operators can correlate, but only
-        // return a sanitized message to the caller.
-        logger.error?.(`[dispatcher] unexpected error in ${method} ${path}:`, err);
-        logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=500 durationMs=${Math.round(performance.now() - startedAt)}`);
-        return {
-            kind: "rest_response",
-            reqId,
-            status: 500,
-            body: { error: "Internal error" },
-        };
-    }
-}
-/**
- * Inner switch: route → handler call. Separated so `handleRestRequest`
- * owns ONE try/catch boundary for all error mapping.
- *
- * Meta publish is fired AFTER the handler returns successfully (i.e.
- * after SQLite has committed) so subscribers never see a "create" event
- * for a row the next read won't find. Publish failures are swallowed
- * inside `safePublish` — the wire response goes back regardless.
- *
- * The body is `unknown` from the wire; each handler validates its own
- * shape via the `BadRequestError`-throwing checks they already do.
- */
-async function dispatchRoute(match, body, deps) {
-    const { store, manager, publishMetaEvent, logger } = deps;
-    const id = match.id ?? "";
-    switch (match.route) {
-        case "list_projects": {
-            const busyIds = manager.getBusySessionIds();
-            const projects = await handleListProjectsAsync(store);
-            // Batch all per-project session lookups into a SINGLE query (LEFT JOIN +
-            // GROUP BY) instead of calling listSessionsByProject(p.id) in a loop,
-            // which issued O(projects) queries each with a per-session correlated
-            // COUNT(*) subquery and blocked the event loop past the 30s relay
-            // deadline on large projects.
-            const sessionsByProject = await store.listSessionsByProjectIdsAsync(projects.map((p) => p.id));
-            return projects.map((p) => {
-                const sessions = sessionsByProject.get(p.id) ?? [];
-                const hasActiveSession = sessions.some((s) => busyIds.has(s.id));
-                return { ...p, hasActiveSession, busy: hasActiveSession };
-            });
-        }
-        case "create_project": {
-            const project = handleCreateProject(store, asObject(body));
-            safePublish(publishMetaEvent, logger, {
-                type: "project_created",
-                projectId: project.id,
-            });
-            return project;
-        }
-        case "update_project": {
-            const project = handleUpdateProject(store, id, asObject(body));
-            safePublish(publishMetaEvent, logger, {
-                type: "project_renamed",
-                projectId: project.id,
-            });
-            return project;
-        }
-        case "delete_project": {
-            // Order matters: tear down live streams BEFORE the row is gone so
-            // the bridges don't try to write to a deleted FK target. Mirrors
-            // the ordering the deleted Hono route used.
-            const project = await store.getProjectAsync(id);
-            if (project) {
-                const sessions = await store.listSessionsByProjectAsync(id);
-                manager.disposeProjectStreams(sessions.map((s) => s.id));
-            }
-            const result = handleDeleteProject(store, id);
-            // Publish AFTER the cascade has committed. We use `id` (the URL
-            // param) as the projectId — `handleDeleteProject` would have
-            // thrown 404 above if it didn't exist.
-            safePublish(publishMetaEvent, logger, {
-                type: "project_deleted",
-                projectId: id,
-            });
-            return result;
-        }
-        case "bind_studio": {
-            const result = await handleBindStudioProject(store, id, asObject(body));
-            safePublish(publishMetaEvent, logger, {
-                type: "project_studio_bound",
-                projectId: id,
-                studioProjectId: result.studioProjectId,
-                studioProjectName: result.studioProjectName,
-            });
-            // Refresh the X-Project-Id header on active bridges so agent-session
-            // credits are attributed to the newly bound project immediately.
-            manager.reloadProjectBindings().catch((err) => {
-                logger?.error?.(`[dispatcher] reloadProjectBindings failed: ${err instanceof Error ? err.message : String(err)}`);
-            });
-            // Reload MCP config so the aexol-mcp extension picks up the new binding.
-            if (deps.mcpState) {
-                handleReloadMcpConfig(deps.mcpState).catch((err) => {
-                    logger?.error?.(`[dispatcher] MCP reload after bind failed: ${err instanceof Error ? err.message : String(err)}`);
-                });
-            }
-            return result;
-        }
-        case "unbind_studio": {
-            const result = await handleUnbindStudioProject(store, id);
-            if (result.studioProjectId) {
-                safePublish(publishMetaEvent, logger, {
-                    type: "project_studio_unbound",
-                    projectId: id,
-                    studioProjectId: result.studioProjectId,
-                });
-            }
-            // Clear the X-Project-Id header on active bridges.
-            manager.reloadProjectBindings().catch((err) => {
-                logger?.error?.(`[dispatcher] reloadProjectBindings failed: ${err instanceof Error ? err.message : String(err)}`);
-            });
-            // Reload MCP config so the aexol-mcp extension clears the old binding.
-            if (deps.mcpState) {
-                handleReloadMcpConfig(deps.mcpState).catch((err) => {
-                    logger?.error?.(`[dispatcher] MCP reload after unbind failed: ${err instanceof Error ? err.message : String(err)}`);
-                });
-            }
-            return result;
-        }
-        case "get_project_observations": {
-            const limitVal = Number(match.query?.get("limit") ?? 30);
-            return handleGetProjectObservations(store, id, Math.max(1, Math.min(100, limitVal || 30)));
-        }
-        case "list_project_sessions": {
-            const busyIds = manager.getBusySessionIds();
-            const sessions = await handleListSessionsByProjectAsync(store, id);
-            return sessions.map((s) => ({
-                ...s,
-                hasActiveTurn: busyIds.has(s.id),
-                busy: busyIds.has(s.id),
-            }));
-        }
-        case "cleanup_project_sessions": {
-            const result = handleCleanupProjectSessions(store, id, asObject(body));
-            // Tear down any in-flight streams for sessions that are being deleted.
-            for (const sessionId of result.ids) {
-                manager.disposeSessionStream(sessionId);
-            }
-            for (const sessionId of result.ids) {
-                safePublish(publishMetaEvent, logger, {
-                    type: "session_deleted",
-                    projectId: id,
-                    sessionId,
-                });
-            }
-            return { deleted: result.deleted };
-        }
-        case "cleanup_all_sessions": {
-            const result = handleCleanupAllSessions(store, asObject(body));
-            // Tear down any in-flight streams for sessions that are being deleted,
-            // across every project.
-            for (const sessionId of result.ids) {
-                manager.disposeSessionStream(sessionId);
-            }
-            for (const [sessionId, projectId] of Object.entries(result.projectIds)) {
-                safePublish(publishMetaEvent, logger, {
-                    type: "session_deleted",
-                    projectId,
-                    sessionId,
-                });
-            }
-            return { deleted: result.deleted };
-        }
-        case "create_session": {
-            const session = handleCreateSession(store, asObject(body));
-            safePublish(publishMetaEvent, logger, {
-                type: "session_created",
-                projectId: session.projectId,
-                sessionId: session.id,
-            });
-            return session;
-        }
-        case "get_session": {
-            const detail = await handleGetSessionDetailAsync(store, id);
-            return {
-                ...detail,
-                busy: manager.isBusy(id),
-                runState: manager.getRunState(id),
-            };
-        }
-        case "get_session_active_agent":
-            return await handleGetSessionActiveAgentAsync(store, id, deps.cwd ?? homedir(), deps.agentDir);
-        case "update_session_active_agent":
-            return await handleUpdateSessionActiveAgentAsync(store, id, asObject(body), manager, deps.cwd ?? homedir(), deps.agentDir);
-        case "get_session_messages":
-            return await handleGetSessionMessagesAsync(store, id, {
-                beforeSeq: match.query?.get("beforeSeq") ?? undefined,
-                beforeCreatedAt: match.query?.get("beforeCreatedAt") ?? undefined,
-                beforeId: match.query?.get("beforeId") ?? undefined,
-                limit: match.query?.get("limit") ?? undefined,
-            });
-        case "get_session_memory":
-            return handleGetSessionMemoryStatus(store, manager, id);
-        case "get_session_memory_details":
-            return handleGetSessionMemoryDetails(store, manager, id);
-        case "update_session": {
-            const session = handleUpdateSession(store, id, asObject(body));
-            safePublish(publishMetaEvent, logger, {
-                type: "session_renamed",
-                projectId: session.projectId,
-                sessionId: session.id,
-            });
-            return session;
-        }
-        case "delete_session": {
-            // Capture projectId BEFORE the row is gone — otherwise the
-            // post-delete publish has no project to attribute to. Treat a
-            // missing session here the same way `handleDeleteSession` does
-            // (throws NotFoundError → 404), but capture first.
-            const detail = store.getSession(id);
-            // Same ordering rationale as delete_project.
-            manager.disposeSessionStream(id);
-            handleDeleteSession(store, id);
-            if (detail) {
-                safePublish(publishMetaEvent, logger, {
-                    type: "session_deleted",
-                    projectId: detail.projectId,
-                    sessionId: id,
-                });
-            }
-            return { ok: true };
-        }
-        case "compact_session":
-            return await handleCompactSession(store, manager, id, body);
-        case "remember_and_delete_session": {
-            // Compact first — the compaction hook's persistProjectObservations
-            // runs inside compactSession, writing reflections to cross-session
-            // durable memory. On failure (e.g. no API key), we let the error
-            // propagate so the session is NOT deleted.
-            await handleRememberAndDeleteSession(store, manager, id);
-            const detail = store.getSession(id);
-            manager.disposeSessionStream(id);
-            handleDeleteSession(store, id);
-            if (detail) {
-                safePublish(publishMetaEvent, logger, {
-                    type: "session_deleted",
-                    projectId: detail.projectId,
-                    sessionId: id,
-                });
-            }
-            return { ok: true };
-        }
-        case "fork_session": {
-            const session = handleForkSession(store, id, asObject(body));
-            safePublish(publishMetaEvent, logger, {
-                type: "session_created",
-                projectId: session.projectId,
-                sessionId: session.id,
-            });
-            return session;
-        }
-        case "list_path_autocomplete": {
-            const prefix = match.query?.get("prefix") ?? "";
-            return await handlePathAutocomplete(prefix);
-        }
-        case "list_directory":
-            return await handleListDirectory(asObject(body));
-        case "get_home_directory":
-            return handleGetHomeDirectory();
-        case "search_project_files": {
-            const searchQuery = match.query?.get("query") ?? "";
-            return handleSearchProjectFiles(store, id, searchQuery);
-        }
-        case "enqueue_prompt":
-            return handleEnqueuePrompt(store, manager, id, asObject(body));
-        case "get_prompt_queue":
-            return handleGetPromptQueue(store, id);
-        case "remove_prompt":
-            handleRemovePrompt(store, manager, id, match.itemId ?? "");
-            return { ok: true };
-        case "clear_prompt_queue":
-            handleClearPromptQueue(store, manager, id);
-            return { ok: true };
-        case "list_mcp_status": {
-            if (!deps.mcpState) {
-                return [];
-            }
-            return handleListMcpStatus(deps.mcpState);
-        }
-        case "reload_mcp_config": {
-            return await handleReloadMcpConfig(deps.mcpState);
-        }
-        case "refresh_native_extensions": {
-            if (!deps.refreshNativeExtensions) {
-                return { ok: true };
-            }
-            await deps.refreshNativeExtensions();
-            return { ok: true };
-        }
-        case "refresh_cloud_agents": {
-            const teamId = asObject(body).teamId;
-            if (typeof teamId !== "string" || teamId.length === 0) {
-                throw new BadRequestError("teamId is required");
-            }
-            if (deps.refreshCloudAgents)
-                await deps.refreshCloudAgents(teamId);
-            return { ok: true };
-        }
-        case "wizard_login": {
-            return await (deps.startWizardLogin ?? (() => startWizardLogin(deps.cwd ?? homedir())))();
-        }
-        case "get_settings":
-            return await handleGetSettingsAsync(deps.cwd ?? homedir());
-        case "put_settings":
-            return await handlePutSettingsAsync(deps.cwd ?? homedir(), asObject(body));
-        case "get_agent_settings":
-            return await handleGetAgentSettingsAsync(deps.cwd ?? homedir(), deps.agentDir);
-        case "put_agent_settings":
-            return await handlePutAgentSettingsAsync(deps.cwd ?? homedir(), asObject(body), deps.agentDir);
-        case "get_prompt_mutation_settings":
-            return handleGetPromptMutationSettings(deps.cwd ?? homedir(), deps.agentDir);
-        case "put_prompt_mutation_settings":
-            return handlePutPromptMutationSettings(deps.cwd ?? homedir(), asObject(body), deps.agentDir);
-        case "list_agents": {
-            const agentCwd = match.query?.get("cwd") || deps.cwd || homedir();
-            const teamId = match.query?.get("teamId") || undefined;
-            // Kick off cloud refresh in the background without blocking the response.
-            // The previous version awaited refreshCloudAgents (network → backend GraphQL)
-            // before returning, so every page refresh stalled the entire REST queue
-            // behind this one slow call while 5-7 other rest_requests timed out.
-            // Background refresh self-dedupes via CloudAgentCacheEntry.inFlight, so
-            // bursts coalesce; stale cache renders immediately and the picker catches
-            // up on the next meta_event/live refresh.
-            if (teamId && deps.refreshCloudAgents) {
-                void deps.refreshCloudAgents(teamId).catch((err) => {
-                    logger?.error?.(`[dispatcher] cloud agent refresh failed:`, err);
-                });
-            }
-            const agents = handleListAgents(agentCwd, deps.agentDir, teamId);
-            return agents;
-        }
-        case "list_dev_processes":
-            return handleListDevProcesses(deps.devProcessRegistry);
-        case "start_dev_process":
-            return handleStartDevProcess(deps.devProcessRegistry, store, asObject(body), deps.cwd);
-        case "kill_dev_process":
-            return handleKillDevProcess(deps.devProcessRegistry, id);
-        case "restart_dev_process":
-            return handleRestartDevProcess(deps.devProcessRegistry, id);
-        case "scan_dev_servers":
-            return handleScanDevServers(store, deps.devProcessRegistry);
-        case "kill_dev_server":
-            return await handleKillDetectedDevServer(store, Number(id), match.port);
-    }
-}
-/**
- * Invoke `publishMetaEvent` if provided, swallowing any throw. The
- * caller has already returned a 200 to the browser; a publish failure
- * (e.g. relay socket just dropped) must NEVER turn a successful
- * mutation into a wire-level error.
- */
-function safePublish(publish, logger, event) {
-    if (!publish)
-        return;
-    try {
-        publish(event);
-    }
-    catch (err) {
-        (logger ?? console).error?.(`[dispatcher] publishMetaEvent failed for ${event.type}:`, err);
-    }
-}
-/**
- * Coerce an `unknown` body to a plain object for the handler. Returns an
- * empty object when the body is missing/non-object so the handler's own
- * field checks produce the canonical error message ("name (string) is
- * required") instead of a confusing "body must be object" from us.
- */
-function asObject(body) {
-    if (body !== null && typeof body === "object" && !Array.isArray(body)) {
-        return body;
-    }
-    return {};
-}
+// Extracted modules — re-exported for backwards compatibility with the
+// original single-file dispatcher.
+export { matchRoute } from "./routing.js";
+export { handleRestRequest } from "./rest.js";
+export { startWizardLogin } from "./wizard-login.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -1560,6 +440,17 @@ export async function handleSubscribe(frame, deps) {
 export function handleCancelTurn(frame, deps) {
     deps.manager.cancelTurn(frame.sessionId);
 }
+/**
+ * Dispatch a `stop_tool_call` frame. Stops ONE hung/long-running tool call
+ * for the session — that call is aborted, the agent receives a synthesized
+ * user-stop tool result, and the turn continues (unlike `cancel_turn`).
+ *
+ * Guarded: unknown toolCallId → no crash, the manager broadcasts a
+ * best-effort `tool_stop_result` info frame.
+ */
+export async function handleStopToolCall(frame, deps) {
+    await deps.manager.stopToolCall(frame.sessionId, frame.toolCallId, frame.reason);
+}
 /**
  * Detach every subscriber the dispatcher has attached. Called by
  * `serve.ts` on relay disconnect / shutdown so the underlying spectral