@aexol/spectral 0.9.230 → 0.9.231

package/dist/relay/routing.js

@@ -0,0 +1,669 @@
+/**
+ * Relay route table (CLI side).
+ *
+ * `matchRoute` is the pure path matcher translating `method + path` into a
+ * `RouteMatch`; `dispatchRoute` is the inner switch that calls the pure REST
+ * handlers (`handlers/projects.ts`, `handlers/sessions.ts`, ...). Extracted
+ * from `relay/dispatcher.ts` — `handleRestRequest` (`relay/rest.ts`) owns the
+ * single try/catch boundary around `dispatchRoute`, and the dispatcher
+ * re-exports `matchRoute` + the request-deps types so existing imports keep
+ * working.
+ */
+import { homedir } from "node:os";
+import { BadRequestError } 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 { handleKillDevProcess, handleKillDetectedDevServer, handleListDevProcesses, handleRestartDevProcess, handleScanDevServers, handleStartDevProcess, } from "../server/handlers/dev-processes.js";
+import { startWizardLogin } from "./wizard-login.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;
+}
+/**
+ * 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.
+ */
+export 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 {};
+}

package/dist/relay/wizard-login.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wizard login flow (CLI side).
+ *
+ * Starts the `@aexol/wizard-spectral` login subprocess on behalf of
+ * `POST /api/wizard/login` (routed by `relay/routing.ts`). Extracted from
+ * `relay/dispatcher.ts` — the dispatcher re-exports `startWizardLogin` and
+ * `WizardLoginResult` so existing imports keep working.
+ */
+export interface WizardLoginResult {
+    status: "configured" | "login_url_observed" | "started" | "completed" | "already_running" | "package_unavailable" | "spawn_failed" | "exited";
+    packageName: string;
+    message: string;
+    loginUrl?: string;
+    startedAt?: number;
+}
+export declare function startWizardLogin(directory?: string): Promise<WizardLoginResult>;
+//# sourceMappingURL=wizard-login.d.ts.map