@wrongstack/webui-server 0.284.1 → 0.286.0

package/dist/index.d.ts

@@ -1,2304 +1,15 @@
-import { WebSocket } from 'ws';
-import * as _wrongstack_core from '@wrongstack/core';
-import { Agent, Context, Logger, EventBus, Provider, Tool, SessionStore, ToolRegistry, ModelsRegistry, ConfigStore, SecretVault, JournalEntry, SessionEventBridge, WstackPaths, MemoryStore, PromptLoader, PromptUsageStore, ProviderConfig, ProviderApiKey, AgentFactory, BrainArbiter, SkillLoader, Config, DefaultSecretVault, DefaultLogger, IndexingConfig, CollaborationBus, ResolvedProvider, ResolvedModel } from '@wrongstack/core';
-import * as http from 'node:http';
-import { MCPRegistry } from '@wrongstack/mcp';
-import { SddInterviewDriver } from '@wrongstack/sdd';
-import { SkillInstaller } from '@wrongstack/core/skills';
-import { SessionReader, AnnotationsStore } from '@wrongstack/core/storage';
-export { WorklistContext, handleWorklistMessage } from './server/handlers.js';
-import { OAuthKind } from '@wrongstack/providers/oauth';
-
-interface AutoPhaseWSMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
 /**
- * AutoPhaseWebSocketHandler — WebSocket-based AutoPhase control.
+ * @wrongstack/webui-server — public API entry.
  *
- * Message types:
- *   autophase.start   → { title, phases?, autonomous? }
- *   autophase.pause   → {}
- *   autophase.resume  → {}
- *   autophase.stop    → {}
- *   autophase.status  → {}
- *   autophase.selectPhase → { phaseId }
- *   autophase.taskStatus  → { taskId, status }
- */
-declare class AutoPhaseWebSocketHandler {
-    private agent;
-    private context;
-    private logger;
-    private events?;
-    private projectRoot?;
-    private orchestrator;
-    private graph;
-    private store;
-    private clients;
-    private broadcastInterval;
-    /** Aborts in-flight task agents AND the planning turn when the run is stopped. */
-    private abort;
-    /** Set the instant a stop/clear/revert is requested, so a planning turn that
-     *  resolves afterwards never launches the orchestrator (the abort alone can't
-     *  cover the window between the LLM call resolving and the orchestrator start). */
-    private stopping;
-    /** Optional per-phase git-worktree isolation (lazily created at start). */
-    private worktrees;
-    /** Base branch + tip SHA captured at run start so a revert can git-revert the
-     *  run's squash commits (history-preserving) instead of a destructive reset. */
-    private runBase;
-    /** Per-run worker identities so the board can show "who is on what". */
-    private usedNicknames;
-    constructor(agent: Agent, context: Context, logger: Logger, storeDir: string, events?: EventBus | undefined, projectRoot?: string | undefined);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: AutoPhaseWSMessage): Promise<void>;
-    private handleStart;
-    /**
-     * Halt the run NOW — at any phase. Sets `stopping` (so a planning turn that
-     * resolves afterwards bails), aborts in-flight agents, stops the orchestrator
-     * tick, and ends the live broadcast. The board is kept for review; use
-     * `autophase.clear` to reset or `autophase.revert` to undo the changes.
-     */
-    private handleStop;
-    /**
-     * Stop + wipe: tear down phase worktrees and reset to an empty board so the UI
-     * returns to the start screen ("new one"). Does NOT touch already-merged commits
-     * on the base branch — that is `autophase.revert`.
-     */
-    private handleClear;
-    /**
-     * Stop + undo: remove phase worktrees, then history-preservingly `git revert`
-     * every commit this run landed on the base branch (captured `runBase`..HEAD),
-     * then reset to an empty board. Refuses (reports a reason) on a dirty tree or a
-     * conflicting revert rather than leaving the tree half-reverted.
-     */
-    private handleRevert;
-    /** Generic fallback phases when the LLM planner produces nothing usable. */
-    private defaultPhases;
-    /** Plan phases+todos for the goal via the LLM; fall back to defaults on failure.
-     *  The caller passes the run's abort signal so a stop during planning cancels
-     *  the LLM turn (the previous fresh, never-aborted controller made planning
-     *  uninterruptible). */
-    private planPhases;
-    private executeTaskWithAgent;
-    /** Persist + broadcast after an interactive board mutation. */
-    private afterBoardMutation;
-    private handleTaskStatusChange;
-    private startBroadcast;
-    private stopBroadcast;
-    private broadcastState;
-    private buildState;
-    private sendState;
-    private broadcast;
-    private send;
-}
-
-/**
- * Context-aware editor completion for the WebUI Monaco surface.
- *
- * The handler combines fast symbol-index hits with a short, JSON-only LLM call.
- * It is intentionally side-effect free: it never writes files and only reads the
- * existing codebase index when available.
- */
-
-type CompletionItemKind = 'text' | 'method' | 'function' | 'constructor' | 'field' | 'variable' | 'class' | 'interface' | 'module' | 'property' | 'unit' | 'value' | 'enum' | 'keyword' | 'snippet' | 'file' | 'reference';
-interface CompletionSuggestion {
-    label: string;
-    insertText: string;
-    kind?: CompletionItemKind | undefined;
-    detail?: string | undefined;
-    documentation?: string | undefined;
-    sortText?: string | undefined;
-    source?: 'llm' | 'index' | 'lsp' | undefined;
-}
-interface CompletionHandlerOptions {
-    projectRoot: string;
-    provider?: Provider | undefined;
-    model?: string | undefined;
-    indexDir?: string | undefined;
-    lspCompletion?: LspCompletionSource | undefined;
-    timeoutMs?: number | undefined;
-}
-interface LspCompletionSourceRequest {
-    filePath: string;
-    lineNumber: number;
-    column: number;
-    content?: string | undefined;
-    triggerCharacter?: string | undefined;
-    signal: AbortSignal;
-}
-type LspCompletionSource = (request: LspCompletionSourceRequest) => Promise<CompletionSuggestion[]>;
-declare function handleCompletionRequest(ws: WebSocket, msg: unknown, opts: CompletionHandlerOptions): Promise<void>;
-declare function createToolLspCompletionSource(tool: Tool | undefined, ctx: Context): LspCompletionSource | undefined;
-
-/**
- * Custom context modes — user-defined presets that are loaded from disk,
- * merged with the built-in modes, and managed via WebSocket CRUD handlers.
- *
- * Stored in: ~/.wrongstack/custom-context-modes.json
- * Format: { "modes": ContextWindowMode[] }
- */
-interface CustomContextMode {
-    id: string;
-    name: string;
-    description: string;
-    thresholds: {
-        warn: number;
-        soft: number;
-        hard: number;
-    };
-    aggressiveOn: string;
-    preserveK: number;
-    eliseThreshold: number;
-    targetLoad: number;
-    /** Whether this is a user-defined (custom) or built-in mode. */
-    custom: boolean;
-}
-interface CustomModeStore {
-    modes: Map<string, CustomContextMode>;
-    load: () => Promise<void>;
-    save: () => Promise<void>;
-    create: (mode: CustomContextMode) => {
-        ok: boolean;
-        error?: string | undefined;
-    };
-    update: (id: string, patch: Partial<CustomContextMode>) => {
-        ok: boolean;
-        error?: string | undefined;
-    };
-    remove: (id: string) => {
-        ok: boolean;
-        error?: string | undefined;
-    };
-    list: () => CustomContextMode[];
-}
-declare function createCustomModeStore(wrongstackDir: string): CustomModeStore;
-
-/**
- * Shared Design Studio WebSocket handlers for both the standalone WebUI server
- * (`packages/webui/src/server/index.ts`) and the CLI's `--webui` embedded
- * server (`packages/cli/src/webui-server.ts`). One source of truth keeps the two
- * servers at parity (enforced by ws-handler-parity.test.ts).
- *
- *   case 'design.list':        return handleDesignList(ws, designCtx);
- *   case 'design.use':         return handleDesignUse(ws, designCtx, msg);
- *   case 'design.state':       return handleDesignState(ws, designCtx);
- *   case 'design.set':         return handleDesignSet(ws, designCtx, msg);
- *   case 'design.materialize': return handleDesignMaterialize(ws, designCtx, msg);
- *
- * Browsing + customization of curated UI design kits; `design.use` pins the
- * active kit, `design.set` records color/token overrides, `design.materialize`
- * writes the (override-applied) tokens to a real theme file on disk.
- */
-
-interface DesignContext {
-    projectRoot: string;
-    /** Live agent context whose `meta.designStudio` we read/pin. Optional. */
-    agentMeta?: {
-        meta: Record<string, unknown>;
-    } | undefined;
-}
-declare function handleDesignList(ws: WebSocket, ctx: DesignContext): Promise<void>;
-declare function handleDesignState(ws: WebSocket, ctx: DesignContext): Promise<void>;
-declare function handleDesignUse(ws: WebSocket, ctx: DesignContext, msg: {
-    payload?: unknown;
-}): Promise<void>;
-/** Record structured color/token overrides without changing the pinned kit. */
-declare function handleDesignSet(ws: WebSocket, ctx: DesignContext, msg: {
-    payload?: unknown;
-}): Promise<void>;
-/** Write the active kit's (override-applied) tokens to a real theme file. */
-declare function handleDesignMaterialize(ws: WebSocket, ctx: DesignContext, msg: {
-    payload?: unknown;
-}): Promise<void>;
-/** Scan project UI files for off-palette colors against the active kit. */
-declare function handleDesignVerify(ws: WebSocket, ctx: DesignContext): Promise<void>;
-
-interface WSServerMessage {
-    type: string;
-    payload: unknown;
-}
-interface WSClientMessage {
-    type: string;
-    payload?: unknown | undefined;
-}
-interface WebUIOptions {
-    /** HTTP frontend port. Prefer `httpPort`; `port` is kept for compatibility. */
-    port?: number | undefined;
-    /** HTTP frontend port. */
-    httpPort?: number | undefined;
-    webuiPort?: number | undefined;
-    /** WebSocket backend port. */
-    wsPort?: number | undefined;
-    /** Host/interface to bind. */
-    wsHost?: string | undefined;
-    /** Fixed access token/password. Defaults to WEBUI_TOKEN or random per process. */
-    accessToken?: string | undefined;
-    /** Browser-facing HTTP URL, used in startup output and instance registry. */
-    publicUrl?: string | undefined;
-    /** Browser-facing WebSocket URL, injected into the frontend for tunnels/proxies. */
-    publicWsUrl?: string | undefined;
-    /** Force token/password protection even on loopback binds. */
-    requireToken?: boolean | undefined;
-    /**
-     * Path to the directory containing the built WebUI frontend assets
-     * (the `dist` directory of `@wrongstack/webui`). When omitted, the
-     * server tries to resolve the frontend package from its own module
-     * location; callers that embed the server (e.g. the desktop app) should
-     * pass an explicit path for deterministic resolution.
-     */
-    distDir?: string | undefined;
-    /**
-     * Pre-built backend services. When provided, `startWebUI` skips its
-     * default agent/event-bus/session/store construction and wires the
-     * supplied instances into the WS message router and HTTP API
-     * handlers instead.
-     *
-     * Intended for callers (most notably `cli/webui-server.ts`) that
-     * already own the agent lifecycle — the CLI's `runWebUI` constructs
-     * the Agent, EventBus, SessionStore, and friends so it can run an
-     * eternal iteration against them, then hands the lot to the webui
-     * for the human-facing surface.
-     *
-     * `session` is typed as `SessionStore` (read + write) rather than
-     * the narrower `SessionWriter` because `startWebUI` needs to
-     * `load()` existing session history to project the chat view, and
-     * `list()` past sessions to populate the sessions dashboard. A
-     * `SessionWriter`-only field would force `startWebUI` to take a
-     * separate `sessionStore` for reads, which is a worse API for the
-     * CLI caller (`runWebUI` already has one store, not two).
-     *
-     * When `services` is omitted, `startWebUI` retains its existing
-     * behavior (builds the defaults in-place). This keeps the standalone
-     * `node dist/index.js webui` flow fully back-compatible.
-     */
-    services?: BackendServices | undefined;
-    /**
-     * Subscribe to live per-iteration events from the eternal-autonomy
-     * engine. When provided, `startWebUI` wires a WS broadcast that
-     * pushes each `JournalEntry` to every connected client. Observability
-     * only — starting the loop still goes through REPL/TUI or `--eternal`,
-     * since the webui has no slash-command dispatch surface yet.
-     *
-     * The argument is a *function* the caller supplies that performs the
-     * actual subscription; the returned disposer is invoked on
-     * `shutdown()`. This indirection lets the caller (most commonly
-     * `cli/webui-server.ts`) own the engine lifecycle and merely hand the
-     * webui an observer slot.
-     */
-    subscribeEternalIteration?: ((fn: (entry: JournalEntry) => void) => () => void) | undefined;
-}
-interface BackendServices {
-    agent: Agent;
-    events: EventBus;
-    session: SessionStore;
-    toolRegistry: ToolRegistry;
-    modelsRegistry: ModelsRegistry;
-    configStore: ConfigStore;
-    vault: SecretVault;
-    globalConfigPath: string;
-    projectRoot: string;
-}
-interface ConnectedClient {
-    ws: WebSocket;
-    sessionId: string | null;
-    connectedAt: number;
-    /** Unique per-connection id — used to key per-connection state (e.g. the
-     *  rate-limit bucket) so distinct browser tabs that share the same
-     *  `sessionId` do not collide, and so the entry is reliably removable on
-     *  close (`String(ws)` is `"[object Object]"` for every socket). */
-    connId: string;
-}
-
-type EternalSubscribe = (fn: (entry: JournalEntry) => void) => () => void;
-type EternalBroadcast<C> = (clients: Map<WebSocket, C>, msg: WSServerMessage) => void;
-interface EternalSubscription {
-    /** Tear down the underlying engine subscription. Idempotent. */
-    dispose: () => void;
-}
-declare function createEternalSubscription<C>(subscribe: EternalSubscribe, broadcast: EternalBroadcast<C>, clientsRef: () => Map<WebSocket, C>): EternalSubscription;
-
-/**
- * Shared file-operation WebSocket handlers for both the standalone WebUI
- * server and the CLI's `--webui` embedded server. Extracted from the
- * duplicated switch cases in `index.ts` and `cli/src/webui-server.ts`.
- *
- * Each function handles the full request→response cycle for one message
- * type. Callers drop them into their switch statement:
- *
- *   case 'files.tree': return handleFilesTree(ws, msg, projectRoot);
- */
-
-interface FilesWriteOptions {
-    onWritten?: ((filePath: string) => void | Promise<void>) | undefined;
-}
-/**
- * Build and send a nested directory tree for the File Explorer.
- *
- * Walks `projectRoot` to depth 10 max, skipping heavyweight dirs
- * (node_modules, .git, dist, …) and dot-entries. Responds with
- * `{ type: 'files.tree', payload: { root, tree } }`.
- */
-declare function handleFilesTree(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
-/**
- * Read a file's content for the Monaco editor.
- *
- * Guards against path traversal (`../` escapes). Responds with
- * `{ type: 'files.read', payload: { filePath, content } }`.
- */
-declare function handleFilesRead(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
-/**
- * Write file content back to disk (atomic write via tmp + rename).
- *
- * Guards against path traversal. Responds with
- * `{ type: 'files.written', payload: { filePath, success } }`.
- */
-declare function handleFilesWrite(ws: WebSocket, msg: unknown, projectRoot: string, opts?: FilesWriteOptions): Promise<void>;
-/**
- * Lightweight project file picker for the chat `@` mention popup.
- *
- * Walks `projectRoot` (max depth 8), skipping hidden and heavyweight
- * dirs, then fuzzy-ranks results against `query`. Responds with
- * `{ type: 'files.list', payload: { files } }`.
- */
-declare function handleFilesList(ws: WebSocket, msg: unknown, projectRoot: string): Promise<void>;
-
-/**
- * Shared `git.info` WebSocket handler for both the standalone WebUI server and
- * the CLI's `--webui` embedded server. Extracted from the duplicated switch
- * cases in `index.ts` and `cli/src/webui-server.ts`, which had drifted (the
- * standalone copy transposed ahead/behind and never matched deletions). One
- * implementation here keeps both surfaces in lockstep.
- *
- *   case 'git.info': return handleGitInfo(ws, projectRoot);
- */
-
-/**
- * Read git branch, change stats, and upstream sync status from `projectRoot`
- * and broadcast a `git.info` message. Never throws — a non-repo / missing-git
- * directory yields an empty-but-valid payload.
- */
-declare function handleGitInfo(ws: WebSocket, projectRoot: string): Promise<void>;
-/**
- * Read the working-tree change set (everything that differs from HEAD:
- * staged, unstaged, and untracked) and broadcast a `git.changes` message.
- *
- * The file list comes from `git status --porcelain -z` (NUL-delimited so
- * paths with spaces/unicode survive intact, and renames are unambiguous).
- * Per-file line counts come from `--numstat` of both the unstaged and the
- * staged diff, summed. Untracked files intentionally report 0/0 here so the
- * list view does not read every untracked file; `git.diff` loads a selected
- * file lazily on demand.
- * Never throws — a non-repo yields an empty list.
- */
-declare function handleGitChanges(ws: WebSocket, projectRoot: string): Promise<void>;
-/**
- * Resolve the before/after text for a single file and broadcast a `git.diff`
- * message. `oldText` is the file at HEAD (`git show HEAD:<path>`), `newText`
- * is the current working-tree content. New/untracked files have empty
- * `oldText`; deleted files have empty `newText`. Binary or oversized files
- * are reported with a flag instead of content so the client can show a notice.
- */
-declare function handleGitDiff(ws: WebSocket, projectRoot: string, path: string): Promise<void>;
-
-type ConfirmDecision = 'yes' | 'no' | 'always' | 'deny';
-interface PendingConfirm {
-    resolve: (decision: ConfirmDecision) => void;
-    decisionSource?: string | undefined;
-    riskTier?: 'safe' | 'standard' | 'destructive' | undefined;
-    /** The exact `tool.confirm_needed` broadcast payload, kept so the prompt
-     *  can be replayed to clients that connect while the confirm is pending
-     *  (e.g. a browser refresh mid-prompt). */
-    payload?: Record<string, unknown> | undefined;
-}
-declare function resolveYoloEligiblePendingConfirms(pendingConfirms: Map<string, PendingConfirm>): void;
-declare function resolveAllPendingConfirms(pendingConfirms: Map<string, PendingConfirm>, decision: ConfirmDecision): void;
-
-/** Metrics for the file watcher that watches status.json files. */
-interface FileWatcherMetrics {
-    /** Number of status.json filesystem events detected after filename filtering. */
-    fileChangesDetected: number;
-    filesProcessed: number;
-    broadcastsSent: number;
-    debounceResets: number;
-    totalDebounceDelayMs: number;
-    activeProjects: number;
-    /** Average debounce delay in ms across all broadcasts. */
-    averageDebounceDelayMs: number;
-    /** Whether the file watcher is currently active. */
-    watcherActive: boolean;
-}
-interface SetupEventsDeps {
-    events: EventBus;
-    broadcast: (clients: Map<WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
-    clients: Map<WebSocket, ConnectedClient>;
-    config: {
-        tools?: {
-            maxIterations?: number | undefined;
-        };
-    };
-    context: Context;
-    pendingConfirms: Map<string, PendingConfirm>;
-    /** Optional global config dir (~/.wrongstack) — enables SessionRegistry poll for fleet view. */
-    globalConfigPath?: string | undefined;
-    /**
-     * Audit-level-aware session log bridge. When provided, tool/error/provider
-     * events are persisted to the session JSONL (same contract as the CLI) —
-     * without it, standalone-WebUI sessions carry no audit events and resume
-     * with no tool history.
-     */
-    sessionBridge?: SessionEventBridge | undefined;
-    /** Optional wpaths for writing status.json file. */
-    wpaths?: WstackPaths | undefined;
-    /**
-     * Optional object to populate with file watcher metrics.
-     * When provided, the setupEvents function will populate this object
-     * with real-time metrics from the file watcher.
-     */
-    watcherMetrics?: FileWatcherMetrics | undefined;
-    /**
-     * Receives the internal `broadcastSessions` fn so the HTTP layer can trigger
-     * an immediate fleet re-broadcast on `POST /api/fleet/ping` (push-on-write
-     * from a TUI/REPL), instead of waiting on the registry file-watch/poll.
-     */
-    onFleetBroadcaster?: ((fn: () => Promise<void>) => void) | undefined;
-}
-declare function statusProjectHashFromWatchFilename(projectsDir: string, filename: string | Buffer): string | null;
-/**
- * Wire kernel events to WS broadcasts and (when wpaths/globalConfigPath are
- * given) start the status-file watcher and session-poll interval.
- *
- * Returns a disposer that stops the watcher, clears the metrics/poll
- * intervals, and flushes pending debounce timers. Callers MUST invoke it on
- * shutdown — the watcher is `persistent: true` and the metrics interval is not
- * `unref`'d, so without disposal they keep the process alive and leak across
- * server restarts. (Previously this was hung off a non-existent
- * `process.on('cleanup')` event that never fired.)
- */
-declare function setupEvents(deps: SetupEventsDeps): () => void;
-
-interface CreateHttpServerOptions {
-    /** Port to listen on. Defaults to 3456 (or the `PORT` env var). */
-    port?: number | undefined;
-    /** Host/interface to bind. Typically the loopback for the WebUI. */
-    host: string;
-    /** Resolved path to the directory containing the built React assets. */
-    distDir: string;
-    /**
-     * WS port — appears in the CSP `connect-src` directive so the browser
-     * is allowed to open a WebSocket back to the local server.
-     */
-    wsPort: number;
-    /**
-     * Public WebSocket URL injected into the frontend. Use this behind tunnels or
-     * reverse proxies where the browser-facing WS URL differs from host:wsPort.
-     */
-    publicWsUrl?: string | undefined;
-    /**
-     * Path to the global WrongStack root (~/.wrongstack). Used by the
-     * /api/sessions and /api/sessions/:id/agents endpoints to read the
-     * cross-process SessionRegistry.
-     */
-    globalRoot?: string | undefined;
-    /**
-     * Shared auth token for HTTP and WS access. Required for non-loopback
-     * binds (LAN exposure). Loopback binds accept local browser access without
-     * a token (the WS path's loopback-bootstrap policy — see ws-auth.ts).
-     */
-    apiToken?: string | undefined;
-    /** Force HTTP token auth even on loopback binds, useful behind public tunnels. */
-    requireToken?: boolean | undefined;
-    /**
-     * If true, the `/ws-auth` endpoint exchanges a `?token=` query param (or
-     * `X-WS-Token` header) for an `HttpOnly` auth cookie. The cookie is then
-     * sent automatically on the WS upgrade, closing the C-598 query-string
-     * token exposure class. Default: true. Set to false to keep the legacy
-     * URL-token-only flow (e.g. in tests that don't want cookie state).
-     */
-    enableWsCookie?: boolean | undefined;
-    /**
-     * Optional file watcher metrics object. When provided, the
-     * /debug/watcher-metrics endpoint will be enabled to expose these metrics.
-     */
-    watcherMetrics?: FileWatcherMetrics | undefined;
-    /**
-     * Push-on-write hook. `POST /api/fleet/ping` (loopback only) invokes this to
-     * trigger an immediate fleet re-broadcast, so a TUI/REPL's registry write
-     * reaches the map without waiting on the file-watch/poll. Best-effort.
-     */
-    onFleetPing?: (() => void) | undefined;
-}
-/**
- * Inject the live WS port into the served HTML so the frontend connects to
- * THIS instance's backend instead of a hardcoded default. Enables running
- * several WebUI instances simultaneously on different PORT/WS_PORT pairs
- * (e.g. one per project) — each instance serves HTML stamped with its own
- * WS port.
- *
- * A `<meta>` tag is used deliberately rather than an inline `<script>`: the
- * CSP sets `script-src 'self'`, which would block an inline script, but meta
- * tags are not subject to script-src. The frontend reads
- * `meta[name="wrongstack-ws-port"]` (see ws-client.ts `defaultWsUrl`).
- */
-declare function injectWsPort(html: string, wsPort: number): string;
-declare function injectWsConfig(html: string, opts: {
-    wsPort: number;
-    publicWsUrl?: string | undefined;
-}): string;
-/** Build the Content-Security-Policy value for the given WS port. */
-declare function buildCspHeader(wsPort: number, requestHost?: string | undefined, publicWsUrl?: string | undefined): string;
-/**
- * Returns true when `candidate` (a fully-resolved absolute path) lies
- * strictly inside `distDir` (or equals it). Used to reject path-traversal
- * attempts after `path.resolve` has normalised any `..` segments.
- *
- * Exported so tests can assert the guard's contract without having to
- * also defeat the WHATWG URL normaliser (which strips `..` from the
- * path string *before* the request even reaches the server, making a
- * black-box test via fetch impossible).
- */
-declare function isInsideDist(candidate: string, distDir: string): boolean;
-/**
- * Decode a `:id` path segment captured by the `/api/sessions/:id/*` routes.
- *
- * Session ids are `YYYY-MM-DD/sess_<ULID>` — they contain a literal
- * `/`. The frontend builds the URL with `encodeURIComponent(sessionId)`, so
- * that slash arrives as `%2F`. The route regex `([^/]+)` correctly captures
- * the whole percent-encoded segment (there is no real `/` in `%2F`), but the
- * SessionRegistry is keyed by the *decoded* id — so the capture must be
- * `decodeURIComponent`d before lookup. Without this, every
- * `/api/sessions/:id/{events,message,agents}` request 404s (the registry has
- * `2026-…/…` but we looked up `2026-…%2F…`), which broke the Fleet HQ
- * watch-stream and the steer-message composer.
- *
- * Malformed percent-encoding (a lone `%`) makes `decodeURIComponent` throw;
- * fall back to the raw segment so the caller still gets a clean 404 rather
- * than a 500.
- */
-declare function decodeSessionId(segment: string): string;
-/**
- * Create the static-file HTTP server. Returns the `http.Server` (not
- * listening yet) so the caller can attach to a `shutdown()` hook and
- * coordinate the listen() with the WebSocket bootstrap.
- */
-declare function createHttpServer(opts: CreateHttpServerOptions): http.Server;
-
-/**
- * Running-instance registry for the standalone WebUI server.
- *
- * Every live `wstackui` process records itself in a single JSON file under the
- * wstack home dir (`~/.wrongstack/webui-instances.json`) so a user running
- * several instances (one per project, or several per project on different
- * ports) can see at a glance which ports are open for which path.
- *
- * Design notes:
- * - **Self-healing**: every register/unregister/list prunes entries whose PID
- *   is no longer alive (`process.kill(pid, 0)`), so a crashed instance that
- *   never got to unregister doesn't leave a ghost behind.
- * - **Atomic writes**: the file is rewritten via `atomicWrite` (tmp + rename),
- *   so a concurrent reader never sees a half-written file. Two instances
- *   starting at the *exact* same millisecond could still race the
- *   read-modify-write — acceptable for a best-effort tracking file, and the
- *   next register() heals any dropped entry.
- * - **Best-effort**: a failure to read/write the registry must NEVER take the
- *   server down. Callers wrap these in `.catch()`.
- */
-/** One running WebUI process. */
-interface WebUIInstanceRecord {
-    /** OS process id — also the liveness key. */
-    pid: number;
-    /** HTTP port serving the React frontend. */
-    httpPort: number;
-    /** WebSocket port for the agent backend. */
-    wsPort: number;
-    /** Bind host (e.g. 127.0.0.1 or 0.0.0.0). */
-    host: string;
-    /** Absolute project root the instance booted against. */
-    projectRoot: string;
-    /** Display name (basename of projectRoot). */
-    projectName: string;
-    /** ISO timestamp when the instance registered. */
-    startedAt: string;
-    /** Convenience open-in-browser URL. */
-    url: string;
-}
-/** Default wstack home dir (`~/.wrongstack`). Callers may override the base. */
-declare function defaultBaseDir(): string;
-/** Resolve the registry file path for a given base dir. */
-declare function registryPath(baseDir?: string): string;
-/**
- * Liveness probe. `process.kill(pid, 0)` sends no signal — it only checks the
- * process exists. ESRCH ⇒ dead; EPERM ⇒ alive but owned by another user (still
- * counts as alive). Any other error is treated conservatively as "alive" so we
- * never prune an instance we simply failed to probe.
- */
-declare function isPidAlive(pid: number): boolean;
-/**
- * Register (or refresh) this instance. Prunes dead entries and any stale entry
- * for our own PID before adding the current record. Best-effort — rejects only
- * on a hard fs error, which callers swallow.
- */
-declare function registerInstance(record: WebUIInstanceRecord, baseDir?: string): Promise<void>;
-/** Remove this instance (called on graceful shutdown). Also prunes dead pids. */
-declare function unregisterInstance(pid: number, baseDir?: string): Promise<void>;
-/** List live instances, pruning any dead entries encountered. */
-declare function listInstances(baseDir?: string): Promise<WebUIInstanceRecord[]>;
-/** Human-readable table of running instances for `wstackui --list`. */
-declare function formatInstances(instances: WebUIInstanceRecord[]): string;
-
-/**
- * MCP management handlers for the WebUI server (both the standalone
- * `wstackui` server and the CLI's embedded `--webui` server).
- *
- * These are thin WebSocket translators over the shared, surface-agnostic
- * management core in `@wrongstack/mcp` (`manage.ts`) — the SAME core the REPL
- * `/mcp` command writes against (same config.json, same MCPRegistry). All the
- * config IO, url/header persistence, and live registry start/stop logic lives
- * there; here we only map structured results to WS events the browser expects.
- */
-
-/** mcp.list — configured servers merged with live registry status + tools. */
-declare function handleMcpList(ws: WebSocket, _msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.add — persist a new server (incl. url/headers) and start it if enabled. */
-declare function handleMcpAdd(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.update — re-persist config (incl. url/headers) and re-apply to registry. */
-declare function handleMcpUpdate(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.remove — stop the server and delete it from config. */
-declare function handleMcpRemove(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.enable — flip enabled:true in config and start the server. */
-declare function handleMcpEnable(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.disable — stop the server and flip enabled:false in config. */
-declare function handleMcpDisable(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.sleep — stop a running server (config stays enabled). */
-declare function handleMcpSleep(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.wake — restart a sleeping/stopped server from config. */
-declare function handleMcpWake(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.restart — stop + start a server. */
-declare function handleMcpRestart(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-/** mcp.discover — ensure the server is running and report its live tools. */
-declare function handleMcpDiscover(ws: WebSocket, msg: WSClientMessage, globalConfigPath: string, mcpRegistry?: MCPRegistry): Promise<void>;
-
-/**
- * Shared memory-operation WebSocket handlers for both the standalone WebUI
- * server and the CLI's `--webui` embedded server. Extracted from the
- * duplicated switch cases in `index.ts` and `cli/src/webui-server.ts`.
- *
- * Each function handles the full request→response cycle for one message
- * type. Callers drop them into their switch statement:
- *
- *   case 'memory.list': return handleMemoryList(ws, memoryStore);
- */
-
-/**
- * List all memory entries across all scopes.
- * Responds with `{ type: 'memory.list', payload: { text } }`.
- */
-declare function handleMemoryList(ws: WebSocket, memoryStore: MemoryStore): Promise<void>;
-/**
- * Persist a new memory entry.
- * Responds with `{ type: 'key.operation_result', payload: { success, message } }`.
- */
-declare function handleMemoryRemember(ws: WebSocket, msg: unknown, memoryStore: MemoryStore): Promise<void>;
-/**
- * Remove memory entries matching the given text.
- * Responds with `{ type: 'key.operation_result', payload: { success, message } }`.
- */
-declare function handleMemoryForget(ws: WebSocket, msg: unknown, memoryStore: MemoryStore): Promise<void>;
-
-/**
- * Best-effort "open this URL in the default browser" for `--webui --open`.
- *
- * Cross-platform via the OS opener (`start` / `open` / `xdg-open`). Fully
- * fire-and-forget: a missing opener, a headless box, or a spawn failure must
- * NEVER take the server down — the URL is always also printed to the console.
- */
-/** Resolve the platform's URL-opener command + args. */
-declare function browserOpenCommand(url: string, platform?: NodeJS.Platform): {
-    command: string;
-    args: string[];
-};
-/** Spawn the OS browser-opener for `url` and register it as a protected
- *  process so it survives kill/killAll. Never throws. */
-declare function openBrowser(url: string, platform?: NodeJS.Platform): void;
-
-/**
- * Free-port discovery for the standalone WebUI server.
- *
- * When a user runs several instances, the default ports (HTTP 3456 / WS 3457)
- * are taken by the first one. Rather than make the user hand-pick `PORT` /
- * `WS_PORT` for every extra instance, the server probes upward from the
- * requested port and binds the first free one — then stamps that real port into
- * the served HTML and the instance registry so everything stays consistent.
- *
- * The probe binds a throwaway `net.Server`, then closes it, so there is a tiny
- * TOCTOU window between "found free" and "the real server binds it". For local
- * single-user multi-instance use that race is negligible; if it ever loses, the
- * real bind fails loudly with EADDRINUSE exactly as before.
- */
-/** Resolve true when `port` can be bound on `host`, false on EADDRINUSE/EACCES. */
-declare function isPortFree(host: string, port: number): Promise<boolean>;
-interface FindFreePortOptions {
-    /** Ports to skip even if free (e.g. one already chosen for the sibling server). */
-    exclude?: Set<number> | undefined;
-    /** How many consecutive ports to try before giving up. Default 200. */
-    maxTries?: number | undefined;
-}
-/**
- * Find the first free port at or above `startPort` on `host`, skipping any in
- * `exclude`. Throws if nothing is free within `maxTries` steps.
- */
-declare function findFreePort(host: string, startPort: number, opts?: FindFreePortOptions): Promise<number>;
-
-/**
- * Send a JSON message to a single WebSocket client.
- * No-op when the socket is not in OPEN state (disconnected / closing).
- */
-declare function send(ws: WebSocket, msg: object): void;
-/**
- * Broadcast a JSON message to every connected client.
- * Swallows per-socket send errors — a client that disconnected between the
- * readyState check and `ws.send()` is cleaned up by its own `close` handler.
- */
-declare function broadcast(clients: Map<WebSocket, ConnectedClient>, msg: object): void;
-/**
- * Send a success/failure result message (used by key.* and provider.* handlers).
- * The frontend expects `key.operation_result` with `{ success, message }`.
- */
-declare function sendResult(ws: WebSocket, success: boolean, message: string): void;
-/**
- * Extract a human-readable message from an unknown thrown value.
- */
-declare function errMessage(err: unknown): string;
-/**
- * Generate a cryptographically random WebSocket auth token (hex string).
- * Shared between standalone and CLI-embedded WebUI servers.
- */
-declare function generateAuthToken(): string;
-declare function resolveAuthToken(explicit?: string | undefined): string;
-declare function hostForBrowserUrl(bindHost: string): string;
-declare function buildWebUIAccessUrl(opts: {
-    host: string;
-    port: number;
-    token?: string | undefined;
-    protocol?: 'http' | 'https' | undefined;
-    publicUrl?: string | undefined;
-}): string;
-declare function envFlag(name: string): boolean;
-
-/**
- * Shared prompt-library WebSocket handlers for BOTH the standalone WebUI server
- * (`packages/webui/src/server/index.ts`) and the CLI's `--webui` embedded server
- * (`packages/cli/src/webui-server.ts`). One source of truth so the two servers
- * never drift (the lesson from skills-handlers).
- *
- * Each function handles one request→response cycle; callers drop them into their
- * switch:
- *
- *   case 'prompts.search': return handlePromptsSearch(ws, promptsCtx, msg);
- *
- * The prompt library is read across three layers (builtin + user + project) by
- * the injected `PromptLoader`; writes (create/favorite) go to the user layer
- * with copy-on-write for builtins. Treat synced/builtin content as DATA — these
- * handlers never execute it; the client inserts a chosen prompt into the chat
- * input as an ordinary user turn.
- */
-
-interface PromptsContext {
-    /** Backs all prompt ops. Absent ⇒ feature unavailable. */
-    promptLoader: PromptLoader | undefined;
-    /** Records per-slug insert counts (shared with CLI `/prompt recent`). */
-    promptUsage?: PromptUsageStore | undefined;
-}
-declare function handlePromptsList(ws: WSLike, ctx: PromptsContext): Promise<void>;
-declare function handlePromptsSearch(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-declare function handlePromptsContent(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-declare function handlePromptsFavorite(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-declare function handlePromptsCreate(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-/** Record that a prompt was inserted (best-effort; feeds CLI `/prompt recent`). */
-declare function handlePromptsUsed(ws: WSLike, ctx: PromptsContext, msg: unknown): Promise<void>;
-/** Return recently-inserted prompt slugs (most-recent first) for the modal's Recent view. */
-declare function handlePromptsRecent(ws: WSLike, ctx: PromptsContext): Promise<void>;
-/** Minimal structural type for the ws.send sink (matches `ws` WebSocket). */
-type WSLike = Parameters<typeof send>[0];
-
-/**
- * Read the `providers` section from the global config, decrypting
- * secret-bearing fields. Returns an empty record when the config file
- * doesn't exist or has no `providers` key.
- */
-declare function loadSavedProviders(configPath: string, vault: SecretVault): Promise<Record<string, ProviderConfig>>;
-/**
- * Write `providers` back into the global config, encrypting secrets first.
- * Refuses to overwrite a corrupt-but-existing config file (the operator
- * should fix it manually). When the config file is missing (ENOENT), starts
- * from an empty object.
- */
-declare function saveProviders(configPath: string, vault: SecretVault, providers: Record<string, ProviderConfig>): Promise<void>;
-/**
- * Small helper for the standalone WebUI entry point: create a
- * `{ load, save }` pair from a config path alone (uses the
- * config-directory-relative `.key` file for the vault). The `--webui`
- * CLI mode and the standalone server both need to read/write the
- * `providers` map identically.
- */
-declare function createProviderConfigIO(configPath: string): {
-    load: () => Promise<Record<string, ProviderConfig>>;
-    save: (providers: Record<string, ProviderConfig>) => Promise<void>;
-};
-
-/**
- * Pure provider/API-key record transforms for the WebUI server's `key.*` and
- * `provider.*` WebSocket handlers.
- *
- * These operate on an in-memory `providers` record (the decrypted
- * `config.providers` map) and return a `{ ok, message }` result mirroring the
- * status string the handler sends back to the client. All persistence
- * (load/decrypt, encrypt/atomic-write) and WS messaging stays in `index.ts` —
- * keeping this layer pure means the security-sensitive key bookkeeping (which
- * key is active, when a provider is dropped, how legacy single-key configs are
- * normalized) is unit-testable without a vault or a socket.
- *
- * Extracted from `index.ts`; transforms mutate the passed record in place, the
- * same way the original handlers did before calling `saveProviders`.
- */
-
-type ProvidersRecord = Record<string, ProviderConfig>;
-interface KeyOpResult {
-    ok: boolean;
-    message: string;
-}
-/**
- * Normalize a provider's keys to the array form, upgrading a legacy single
- * `apiKey` string to a one-element `[{ label: 'default', ... }]` list. Returns
- * fresh copies so callers can mutate without aliasing the stored config.
- */
-declare function normalizeKeys(cfg: ProviderConfig): ProviderApiKey[];
-/**
- * Write a normalized key list back onto a provider config: drop all key fields
- * when empty, otherwise sync `apiKeys` and re-point `activeKey` if it no longer
- * names a present key. Does NOT mirror the plaintext key to the legacy `apiKey`
- * field — that would leak the secret on accidental serialization. Consumers
- * that need the real key should read from `apiKeys[]` directly.
- */
-declare function writeKeysBack(cfg: ProviderConfig, keys: ProviderApiKey[]): void;
-/** Mask a secret for display: `••••` for short keys, `abcd…wxyz` otherwise. */
-declare function maskedKey(key: string | undefined): string;
-/** Add or replace a labeled key for a provider, creating the provider if new. */
-declare function upsertKey(providers: ProvidersRecord, providerId: string, label: string, apiKey: string, nowIso: string): KeyOpResult;
-/** Remove a labeled key; drops the provider entirely when its last key goes. */
-declare function deleteKey(providers: ProvidersRecord, providerId: string, label: string): KeyOpResult;
-/** Point a provider's active key at the given label. */
-declare function setActiveKey(providers: ProvidersRecord, providerId: string, label: string): KeyOpResult;
-/** Register a brand-new provider (optionally with an initial `default` key). */
-declare function addProvider(providers: ProvidersRecord, payload: {
-    id: string;
-    family: string;
-    baseUrl?: string | undefined;
-    apiKey?: string | undefined;
-}, nowIso: string): KeyOpResult;
-/** Remove an entire provider and all its keys. */
-declare function removeProvider(providers: ProvidersRecord, providerId: string): KeyOpResult;
-
-interface SddBoardWSMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/** Project paths the handler needs to apply lifecycle ops directly. */
-interface SddBoardLifecycleDeps {
-    projectRoot: string;
-    paths: {
-        projectSpecs: string;
-        projectTaskGraphs: string;
-        projectSddSession: string;
-        projectSddBoards: string;
-    };
-}
-/**
- * SddBoardWebSocketHandler — streams the live SDD multi-agent board to clients
- * and relays control commands back to the CLI-owned run.
- *
- * Two observe modes (one class, shared by both webui servers):
- *  • in-process (CLI-hosted): subscribe the shared EventBus `sdd.board.snapshot`
- *    for instant updates;
- *  • standalone (separate process): poll the on-disk snapshot store (the CLI
- *    run persists JSON every change).
- *
- * Control is uniform + cross-process: every command is appended to the run's
- * `<runId>.control.jsonl`, which the CLI run drains and applies — so the run
- * stays the single driver and nothing races on shared state.
- */
-declare class SddBoardWebSocketHandler {
-    private readonly store;
-    private readonly clients;
-    private readonly lifecycle?;
-    private latest;
-    private poll;
-    private unsub;
-    constructor(boardsDir: string, events?: EventBus, lifecycle?: SddBoardLifecycleDeps);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: SddBoardWSMessage): Promise<void>;
-    /**
-     * Apply a cleanup/rollback/destroy from disk and broadcast a structured
-     * `sdd.board.lifecycle_result`. Refuses (no-op) while a run is still active —
-     * the user must stop it first; the UI gates the buttons on `!active` and the
-     * Destroy flow auto-stops then waits before sending `destroy`.
-     */
-    private applyLifecycle;
-    dispose(): void;
-    private pollLatest;
-    private sendCurrent;
-    private broadcastCurrent;
-    private loadLatestFromDisk;
-    private broadcast;
-    private send;
-}
-
-interface WizardMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/**
- * Dependencies each webui server supplies. The handler is deliberately
- * agent-agnostic: every surface decides how to build a driver, how to run an
- * interview turn (on an isolated agent, off the main chat bus), and how to
- * start the real multi-agent run (CLI's director-backed factory vs the runtime
- * light factory). This keeps the wizard protocol identical across both servers.
- */
-interface SddWizardDeps {
-    /** Build a fresh interview driver (disk spec/graph stores + session path). */
-    makeDriver: () => SddInterviewDriver;
-    /**
-     * Run one interview turn: feed the AI prompt to an isolated agent and return
-     * its final text. MUST NOT run on the main chat agent's bus — the wizard owns
-     * this conversation, separate from the user's chat.
-     */
-    runInterviewTurn: (prompt: string) => Promise<string>;
-    /**
-     * Start the real multi-agent SDD run for the driver's task graph. Returns the
-     * runId; the live board flows through the existing board handler.
-     */
-    startRun: (driver: SddInterviewDriver, opts: {
-        parallelSlots?: number | undefined;
-        defaultModel?: string | undefined;
-        defaultProvider?: string | undefined;
-        fallbackModels?: string[] | undefined;
-        /** Per-run worktree-isolation override; undefined → env default. */
-        worktrees?: boolean | undefined;
-    }) => Promise<{
-        runId: string;
-    }>;
-}
-/**
- * SddWizardWebSocketHandler — drives the interactive "New SDD Project" wizard
- * (goal → Q&A → spec → task graph → start run) over WebSocket. Shared by both
- * webui servers; server-specific construction (agent, factory) is injected via
- * {@link SddWizardDeps}.
- */
-declare class SddWizardWebSocketHandler {
-    private readonly deps;
-    private readonly clients;
-    private driver;
-    /** The agent's most recent question — paired with the next user answer. */
-    private lastAgentText;
-    /** Guards against overlapping interview turns (one in flight at a time). */
-    private busy;
-    constructor(deps: SddWizardDeps);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: WizardMessage): Promise<void>;
-    private onStart;
-    private onMessage;
-    private onApprove;
-    private onRunStart;
-    /** Run one interview turn against the isolated agent, then ingest + broadcast. */
-    private runTurn;
-    private snapshotMsg;
-    private broadcast;
-    private send;
-}
-
-interface SddWizardWiringOptions {
-    /** Leader agent — seeds the run's default factory + project context. */
-    agent: Agent;
-    /** Shared EventBus — the board projector emits sdd.board.snapshot on it. */
-    events: EventBus;
-    projectRoot: string;
-    /** Per-task agent factory: CLI's director-backed one, or the runtime light one. */
-    subagentFactory: AgentFactory;
-    /**
-     * Decision authority for the failure supervisor (the server's bound
-     * TOKENS.BrainArbiter). Omit to run without a supervisor (plain terminal-fail,
-     * matching a bare run) — but parity with the CLI wants it wired.
-     */
-    brain?: BrainArbiter | undefined;
-    /** Persisted-store directories (from resolveWstackPaths). */
-    paths: {
-        projectSpecs: string;
-        projectTaskGraphs: string;
-        projectSddBoards: string;
-        projectDir: string;
-    };
-}
-declare function buildSddWizardDeps(opts: SddWizardWiringOptions): SddWizardDeps;
-
-type ShellOpenTarget = 'terminal' | 'file-manager';
-interface ShellOpenRequest {
-    path: string;
-    target: ShellOpenTarget;
-}
-interface ShellOpenResult {
-    success: boolean;
-    message: string;
-}
-declare function handleShellOpen(req: ShellOpenRequest, logger: Logger): Promise<ShellOpenResult>;
-
-/**
- * Shared skills WebSocket handlers for both the standalone WebUI server
- * (`packages/webui/src/server/index.ts`) and the CLI's `--webui` embedded
- * server (`packages/cli/src/webui-server.ts`).
- *
- * These were previously inlined in BOTH servers, and the CLI copy had
- * drifted — it only wired `skills.list`, so `skills.content` /
- * `skills.export` / `skills.update` (and install/uninstall/create/edit)
- * fell through to the "Unhandled message type" warning even though the
- * SkillsPanel sends them. Extracting the full set here gives both servers
- * one source of truth. Each function handles the full request→response
- * cycle for one message type; callers drop them into their switch:
- *
- *   case 'skills.content': return handleSkillsContent(ws, skillsCtx, msg);
- *
- * The logic is a verbatim lift of the standalone's inline cases — only the
- * dependency references changed (`skillLoader`/`skillInstaller`/
- * `projectRoot` → `ctx.*`, local `send`/`errMessage` → imported helpers).
- */
-
-interface SkillsContext {
-    /** Backs skills.list/content/edit/export. Absent ⇒ feature disabled. */
-    skillLoader: SkillLoader | undefined;
-    /** Backs skills.install/uninstall/update. Absent ⇒ those ops disabled. */
-    skillInstaller: SkillInstaller | undefined;
-    /** Project root — used by skills.create to write `.wrongstack/skills/…`. */
-    projectRoot: string;
-    /** Project skills directory, normally `<project>/.wrongstack/skills`. */
-    projectSkillsDir?: string | undefined;
-    /** User-global skills directory, normally `~/.wrongstack/skills`. */
-    globalSkillsDir?: string | undefined;
-}
-/**
- * List installed skills. Enriches each manifest with the source URL + git
- * ref recorded by the installer (when present), so the panel can show
- * provenance and offer update/uninstall.
- */
-declare function handleSkillsList(ws: WebSocket, ctx: SkillsContext): Promise<void>;
-/**
- * Read a single skill's body + its directory's related files + which other
- * skills reference it by name. Powers the skill detail/preview view.
- */
-declare function handleSkillsContent(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Install a skill from a git ref (`owner/repo` or URL). Optional `global`
- * installs into the user-wide skills dir instead of the project's.
- */
-declare function handleSkillsInstall(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Uninstall a skill by name. Optional `global` restricts/Targets the
- * user-wide install.
- */
-declare function handleSkillsUninstall(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Update one skill (`name`) or all installed skills (when `name` is
- * omitted). Reports per-skill updated/unchanged/error tallies.
- */
-declare function handleSkillsUpdate(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Scaffold a new project- or global-scoped skill from a name + description.
- * Writes a templated `SKILL.md` under `.wrongstack/skills/<name>/` (project)
- * or the user-wide skills dir (global).
- */
-declare function handleSkillsCreate(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Overwrite a skill's body. Refuses bundled skills (read-only) and unknown
- * names.
- */
-declare function handleSkillsEdit(ws: WebSocket, ctx: SkillsContext, msg: unknown): Promise<void>;
-/**
- * Export every readable skill as a base64-encoded zip (one folder per skill,
- * each with its `SKILL.md`). Powers the panel's "Export all" button.
- */
-declare function handleSkillsExport(ws: WebSocket, ctx: SkillsContext): Promise<void>;
-
-interface SpecsWSMessage {
-    type: string;
-    payload?: Record<string, unknown>;
-}
-/**
- * SpecsWebSocketHandler — read-only-ish browser of persisted SDD specs and their
- * task graphs, rendered as a FORGE-style dependency board (topological phase
- * columns + dependency refs). Shared by both webui servers via specs-routes.
- *
- * Message types:
- *   specs.list                       → all specs + progress
- *   specs.get { specId }             → one spec's dependency board
- *   specs.taskStatus { graphId, taskId, status } → update + rebroadcast
- */
-declare class SpecsWebSocketHandler {
-    private specStore;
-    private graphStore;
-    private clients;
-    constructor(specsDir: string, taskGraphsDir: string);
-    addClient(ws: WebSocket): void;
-    handleMessage(msg: SpecsWSMessage): Promise<void>;
-    private buildList;
-    private broadcastList;
-    private sendList;
-    private broadcastDetail;
-    private findGraphForSpec;
-    private buildDetail;
-    private updateTaskStatus;
-    private broadcast;
-    private send;
-}
-
-/**
- * Per-section context-window token estimate for the `context.debug` command.
- *
- * Uses the simple 4-chars-per-token heuristic — not exact, but close enough to
- * spot which section (system prompt, tool schemas, or message history) is
- * eating the context window. Tool schemas in particular are easy to overlook:
- * each tool ships its full JSON schema to the model every turn, so 20+ builtins
- * can cost 10-20k tokens on their own.
- *
- * Extracted from `index.ts` as a pure function so the breakdown maths can be
- * unit tested without standing up a Context/ToolRegistry.
- */
-/** 4-chars-per-token heuristic estimate for a string. */
-declare function estimateTokens(s: string): number;
-/** Stringify arbitrary content for length estimation (JSON, with fallbacks). */
-declare function stringifyContent(c: unknown): string;
-interface PromptBlock {
-    text?: string | undefined;
-}
-interface ToolLike {
-    name: string;
-    inputSchema?: unknown | undefined;
-    description?: string | undefined;
-}
-interface MessageLike {
-    role: string;
-    content: unknown;
-}
-interface ToolTokenEntry {
-    name: string;
-    tokens: number;
-}
-interface MessageTokenEntry {
-    index: number;
-    role: string;
-    tokens: number;
-    preview: string;
-}
-interface ContextBreakdown {
-    total: number;
-    systemPrompt: number;
-    tools: {
-        total: number;
-        count: number;
-        breakdown: ToolTokenEntry[];
-    };
-    messages: {
-        total: number;
-        count: number;
-        breakdown: MessageTokenEntry[];
-    };
-}
-declare function messageTokens(content: unknown): number;
-declare function messagePreview(content: unknown): string;
-/**
- * Compute the per-section token breakdown for the active context. Mirrors the
- * shape the `context.debug` WS reply expects (minus the `mode`/`policy` fields,
- * which the caller layers on from `context.meta`).
- */
-declare function estimateContextBreakdown(input: {
-    systemPrompt: ReadonlyArray<PromptBlock>;
-    tools: ReadonlyArray<ToolLike>;
-    messages: ReadonlyArray<MessageLike>;
-}): ContextBreakdown;
-
-interface WorktreeManagementDeps {
-    projectRoot: string;
-    /** Board snapshot dir — powers the cross-process liveness guard on cleanup. */
-    boardsDir: string;
-}
-/**
- * WorktreeWebSocketHandler — mirrors AutoPhaseWebSocketHandler. Subscribes to
- * the shared EventBus `worktree.*` lifecycle events, keeps a live snapshot of
- * every worktree, and broadcasts:
- *   - `worktree.event` incrementally (drives the flowing activity strip)
- *   - `worktree.state`  on connect + on a 2s timer (drives swim-lanes/DAG)
- */
-declare class WorktreeWebSocketHandler {
-    private readonly events;
-    private readonly logger;
-    private readonly management?;
-    private readonly clients;
-    private readonly handles;
-    private baseBranch;
-    private broadcastInterval;
-    private readonly offs;
-    constructor(events: EventBus, logger: Logger, management?: WorktreeManagementDeps | undefined);
-    addClient(ws: WebSocket): void;
-    /** Handle worktree-panel control messages (scan / clean / per-row ops). */
-    handleMessage(msg: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }): Promise<boolean>;
-    dispose(): void;
-    /** Absolute managed-worktrees root for this project. */
-    private worktreesRoot;
-    /** True iff `dir` resolves strictly inside the managed worktrees root. */
-    private underRoot;
-    /** Branches of worktrees a live in-session run currently owns. */
-    private liveActiveBranches;
-    /**
-     * Scan the disk for managed worktrees/branches NOT owned by a live in-session
-     * run and broadcast them as orphans, with whether it is safe to clean now.
-     * No-op (empty inventory) when management deps were not wired.
-     */
-    private scanAndBroadcast;
-    /**
-     * Force-remove every orphaned worktree + branch. Refused while a run is live —
-     * in this session (active handles) OR another process (the SDD board liveness
-     * guard inside cleanupStaleSddWorktrees). Best-effort; reports the outcome.
-     */
-    private cleanupOrphans;
-    /** Remove/discard ONE worktree + branch. Refused while a live run owns it. */
-    private removeOne;
-    /** Squash-merge ONE branch into base. Refused while a live run owns it. */
-    private mergeBranch;
-    /** Compact change summary for one worktree checkout. */
-    private diffOne;
-    private subscribe;
-    private upsert;
-    private patch;
-    private activity;
-    private stateMessage;
-    private broadcastState;
-    private ensureBroadcast;
-    private stopBroadcast;
-    private broadcast;
-    private send;
-}
-
-/** A hostname that refers to the local machine. */
-declare function isLoopbackHostname(hostname: string): boolean;
-/** True when the server is bound to a loopback interface (vs. LAN/0.0.0.0). */
-declare function isLoopbackBind(wsHost: string): boolean;
-/**
- * True when the server is bound to a wildcard address that exposes it on every
- * interface — IPv4 `0.0.0.0` OR IPv6 `::` (and its bracketed form). The
- * "LAN exposure = deny" guards below must treat both families identically; a
- * `::` bind is exactly as exposed as `0.0.0.0` and previously slipped past the
- * `wsHost === '0.0.0.0'` string check.
- */
-declare function isWildcardBind(wsHost: string): boolean;
-/**
- * Constant-time comparison of a provided token against the expected one.
- * A length mismatch short-circuits (lengths aren't secret); equal-length
- * inputs are compared with `timingSafeEqual` so the token can't be recovered
- * byte-by-byte via response timing.
- */
-declare function tokenMatches(provided: string | undefined, expected: string): boolean;
-/** Pull the `token` query param out of a request URL (`/?token=…`). */
-declare function extractToken(url: string): string | undefined;
-/**
- * Pull the `ws_token` value out of a Cookie header (`Cookie: ws_token=…`).
- * The WebUI's auth-token cookie is set via `Set-Cookie: ws_token=<token>;
- * HttpOnly; SameSite=Strict; Path=/` from the `/ws-auth` HTTP endpoint. The
- * browser then sends it back automatically on the WS upgrade request —
- * closing the C-598 (Information Exposure Through Query String) class
- * because the token never appears in the URL, browser history, or
- * reverse-proxy access logs.
- *
- * Returns `undefined` if the cookie header is absent or malformed.
- */
-declare function extractTokenFromCookie(cookieHeader: string | string[] | undefined): string | undefined;
-/**
- * DNS-rebinding defense. On a loopback bind, the `Host` header must resolve to
- * a loopback name. When the operator deliberately exposes the socket (wsHost is
- * a LAN/0.0.0.0 address) the Host is legitimately non-loopback, so the guard is
- * skipped and connection auth falls to the token check.
- */
-declare function hostHeaderOk(input: {
-    hostHeader: string | undefined;
-    wsHost: string;
-    allowedHostnames?: readonly string[] | undefined;
-}): boolean;
-interface VerifyClientInput {
-    /** Browser `Origin` header, or undefined for non-browser clients. */
-    origin?: string | undefined;
-    /** Request URL (`req.url`) — carries the `?token=…` query param. */
-    url: string;
-    /** `Host` header (`req.headers.host`). */
-    hostHeader?: string | undefined;
-    /** Peer address (`req.socket.remoteAddress`). */
-    remoteAddress?: string | undefined;
-    /** `Cookie` header (`req.headers.cookie`). Carries `ws_token=…` when the
-     *  browser went through `/ws-auth` to set the HttpOnly auth cookie. */
-    cookieHeader?: string | string[] | undefined;
-    /** Host/interface the WS server is bound to. */
-    wsHost: string;
-    /** The server's generated auth token. */
-    expectedToken: string;
-    /** Force token auth even for loopback binds, useful behind public tunnels. */
-    requireToken?: boolean | undefined;
-    /** Extra Host header names allowed on loopback binds, e.g. a tunnel hostname. */
-    allowedHostnames?: readonly string[] | undefined;
-    /** Allow browser WS URL tokens for explicit public WS URLs where cookies cannot cross hostnames. */
-    allowBrowserUrlToken?: boolean | undefined;
-}
-/**
- * Decide whether to accept an incoming WebSocket handshake. Pure mirror of the
- * closure previously inlined in `index.ts`; see the module doc for the layered
- * policy. Returns `true` to accept, `false` to reject.
- *
- * Token sources, in priority order:
- *  1. `Cookie: ws_token=…` (browser clients that went through `/ws-auth`)
- *  2. `?token=…` URL query param (non-browser clients: curl, scripts)
- *
- * Browser clients (with an `Origin` header) are restricted to the cookie path —
- * URL token is rejected for them, closing the C-598 query-string token
- * exposure class. Non-browser clients keep the URL-token fallback so curl
- * and tests continue to work.
- */
-declare function verifyClient(input: VerifyClientInput): boolean;
-
-declare function startWebUI(opts?: WebUIOptions & {
-    wsPort?: number | undefined;
-    wsHost?: string | undefined;
-    httpPort?: number | undefined;
-    accessToken?: string | undefined;
-    publicUrl?: string | undefined;
-    publicWsUrl?: string | undefined;
-    requireToken?: boolean | undefined;
-    open?: boolean | undefined;
-}): Promise<void>;
-
-interface AutoPhaseRouteHandlers {
-    handleMessage: (msg: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }) => Promise<void>;
-}
-declare function handleAutoPhaseRoute(_ws: WebSocket, msg: WSClientMessage, handlers: AutoPhaseRouteHandlers): Promise<boolean>;
-
-interface BootResult {
-    config: Config;
-    vault: DefaultSecretVault;
-    globalConfigPath: string;
-    projectRoot: string;
-    wpaths: WstackPaths;
-    logger: InstanceType<typeof DefaultLogger>;
-}
-/**
- * Thin WebUI wrapper over the canonical `bootConfig` in `@wrongstack/core`
- * (mirrors packages/cli/src/boot-config.ts). All real boot behavior — wstack
- * path resolution, the AES-GCM `DefaultSecretVault`, plaintext-secret
- * migration, and config load/merge — lives in core so the WebUI server and the
- * CLI can't drift. Only the secret-migration notice label (`WebUI`) differs.
- */
-declare function bootConfig(): Promise<BootResult>;
-declare function patchConfig(config: Config, updates: Partial<Config>): Config;
-
-interface WebUICodebaseIndexingDeps {
-    config: {
-        indexing?: IndexingConfig | undefined;
-    };
-    context: Context;
-    projectRoot: string;
-    logger: Logger;
-}
-interface WebUICodebaseIndexing {
-    onFileWritten(filePath: string): void;
-    dispose(): void;
-}
-declare function setupWebUICodebaseIndexing(deps: WebUICodebaseIndexingDeps): WebUICodebaseIndexing;
-
-/**
- * Goal-state WebSocket handler for the WebUI server, extracted from the
- * `handleMessage` switch in `index.ts` as part of splitting that file (#31).
- *
- *   case 'goal.get': return handleGoalGet(projectRoot, (m) => broadcast(clients, m));
- *
- * Reads the canonical goal.json and broadcasts it to every connected client so
- * all browser tabs share one goal snapshot. Never throws — a missing or
- * unparseable file broadcasts `null` so clients clear stale goal state.
- */
-/**
- * Read `goal.json` for `projectRoot` and broadcast a `goal.updated` message.
- * The path must match /goal, the autonomy engines, and TUI F9, which all
- * resolve via `resolveWstackPaths().projectGoal`
- * (`~/.wrongstack/projects/<slug>/goal.json`) — NOT the repo-local
- * `.wrongstack/goal.json`.
- */
-declare function handleGoalGet(projectRoot: string, broadcast: (msg: object) => void): Promise<void>;
-
-/**
- * Process-registry WebSocket handlers for the WebUI server, extracted from the
- * `handleMessage` switch in `index.ts` as part of splitting that file (#31).
- *
- *   case 'process.list':    return handleProcessList(ws);
- *   case 'process.kill':    return handleProcessKill(ws, msg.payload);
- *   case 'process.killAll': return handleProcessKillAll(ws);
- *
- * All three reach the registry via a dynamic `@wrongstack/tools` import so the
- * server starts even when that package is unavailable, and never throw — a
- * failure is reported back over the socket instead.
- */
-
-/** Broadcast the tracked-process list; an empty list on any registry failure. */
-declare function handleProcessList(ws: WebSocket): Promise<void>;
-/** Kill one tracked PID. Rejects invalid payloads and protected processes. */
-declare function handleProcessKill(ws: WebSocket, payload: unknown): Promise<void>;
-/** Kill every tracked process. */
-declare function handleProcessKillAll(ws: WebSocket): Promise<void>;
-
-interface BrainRouteHandlers {
-    status: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-    risk: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-    ask: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-}
-declare function handleBrainRoute(ws: WebSocket, msg: WSClientMessage, handlers: BrainRouteHandlers): Promise<boolean>;
-
-/**
- * CollaborationWebSocketHandler — passive read-only session observer (Phase 1
- * of idea #13 from IDEAS.md). Mirrors `WorktreeWebSocketHandler` and
- * `AutoPhaseWebSocketHandler`.
- *
- * Capabilities in this phase:
- *   - A second human (or any client) joins an active agent run as an
- *     `observer` and receives a live mirror of the kernel's iteration /
- *     tool / subagent events.
- *   - The observer declares a `sessionId` on join (used for state scoping
- *     and future replay-on-join). Live event routing is session-agnostic
- *     for now — see the limitation note below.
- *   - The observer can leave at any time; cleanup runs on WS close/error.
- *   - The observer CANNOT modify the agent's state, pause it, or inject
- *     tool calls. Those capabilities land in Phase 2/3.
- *
- * Limitation (documented, acceptable for Phase 1):
- *   The webui server multiplexes every active session onto a single
- *   EventBus, and most event payloads (`tool.started`, `iteration.*`,
- *   `subagent.*`) do NOT carry a `sessionId` field. The webui's primary
- *   WS path works because it is the only consumer and assumes one
- *   active session at a time. We mirror that assumption here. When a
- *   future multi-session "session router" lands, this handler will be
- *   upgraded to filter by sessionId.
+ * The WebUI HTTP/WebSocket server module, extracted from @wrongstack/webui in
+ * PR #018b (see docs/backlog/2026-07-architecture-review/018-modularity-audit-and-plan.md
+ * §3.1.1). This re-export surface exists so consumers can `import { ... }
+ * from '@wrongstack/webui-server'` without reaching into ./server/...
+ * internals.
  *
- * Protocol additions (see `packages/webui/src/types.ts`):
- *   client → server:  collab.join { sessionId, role: 'observer' }
- *                     collab.leave { sessionId }
- *   server → client:  collab.state          (initial + 2s periodic)
- *                     collab.participant.joined
- *                     collab.participant.left
- *                     collab.event          (live kernel event mirror)
- */
-declare class CollaborationWebSocketHandler {
-    private readonly events;
-    private readonly logger;
-    /**
-     * Optional reader over the on-disk session log. When provided, late
-     * joiners receive the last `REPLAY_LIMIT` events of the joined
-     * session before live mirroring begins. Without a reader, joining
-     * is still allowed — the observer simply starts from "now" with no
-     * historical context.
-     */
-    private readonly reader?;
-    /**
-     * Optional sidecar store for collaboration annotations. Required
-     * for the `annotator` role — without it, `collab.annotate` messages
-     * are rejected with an error.
-     */
-    private readonly annotations?;
-    /**
-     * Optional kernel-level pause/resume bus. Required for the
-     * `controller` role — without it, `collab.request_pause` is rejected
-     * with an error. Wired to the agent's `toolCall` pipeline via
-     * `collabPauseMiddleware` in the webui server boot.
-     */
-    private readonly bus?;
-    private readonly clients;
-    /** sessionId → participants currently watching it. */
-    private readonly bySession;
-    private broadcastInterval;
-    private readonly offs;
-    constructor(events: EventBus, logger: Logger, 
-    /**
-     * Optional reader over the on-disk session log. When provided, late
-     * joiners receive the last `REPLAY_LIMIT` events of the joined
-     * session before live mirroring begins. Without a reader, joining
-     * is still allowed — the observer simply starts from "now" with no
-     * historical context.
-     */
-    reader?: SessionReader | undefined, 
-    /**
-     * Optional sidecar store for collaboration annotations. Required
-     * for the `annotator` role — without it, `collab.annotate` messages
-     * are rejected with an error.
-     */
-    annotations?: AnnotationsStore | undefined, 
-    /**
-     * Optional kernel-level pause/resume bus. Required for the
-     * `controller` role — without it, `collab.request_pause` is rejected
-     * with an error. Wired to the agent's `toolCall` pipeline via
-     * `collabPauseMiddleware` in the webui server boot.
-     */
-    bus?: CollaborationBus | undefined);
-    addClient(ws: WebSocket): void;
-    dispose(): void;
-    /**
-     * Dispatch a parsed client message. Returns true when the message was
-     * recognized and handled; false when the caller should ignore / log.
-     * Phase 1 only knows `collab.join` and `collab.leave`; unknown types
-     * return false so the upstream router can decide.
-     */
-    handleMessage(ws: WebSocket, msg: {
-        type: string;
-        payload?: unknown | undefined;
-    }): boolean;
-    private join;
-    private leave;
-    private handleDisconnect;
-    /**
-     * Look up the participant record for a given WS across all sessions.
-     * Returns null when the WS hasn't joined (e.g. the client sent a
-     * `collab.annotate` before `collab.join`).
-     */
-    private findParticipant;
-    private findParticipantById;
-    private handleAnnotate;
-    private handleResolve;
-    private subscribe;
-    private broadcastEvent;
-    /**
-     * Replay the last `REPLAY_LIMIT` events from the on-disk session log
-     * to a single observer (the late joiner). Each event is forwarded as
-     * a `collab.event` with `replay: true` so the client can distinguish
-     * history from the live stream.
-     *
-     * The session log stores typed `SessionEvent`s (`user_input`,
-     * `llm_response`, `tool_result`, etc.) — different from the kernel's
-     * bus events. We translate the most useful subset (`tool.*` and
-     * `iteration.*`-shaped ones) into the same `kind` namespace the live
-     * mirror uses, so the client can render a single activity strip.
-     */
-    private replayHistory;
-    /**
-     * Map a stored `SessionEvent` to a `collab.event.kind` so the live
-     * strip and the history strip can share a single rendering path.
-     * Returns null for events that don't have a meaningful live analog
-     * (e.g. `session_start`, file-snapshot bookkeeping, rewind markers).
-     */
-    private historyEventToKind;
-    private stateMessage;
-    private ensureBroadcast;
-    private stopBroadcast;
-    private broadcast;
-    private send;
-    private errorMessage;
-    private handleRequestPause;
-    private handleResume;
-    private handleGrantControl;
-    /**
-     * Phase 4 — handle a controller's manual tool-call injection.
-     * Validates the payload, queues it on the bus, and broadcasts
-     * the grant so observers see what just happened. The actual
-     * splice into the agent's pipeline is performed by the
-     * `collabInjectMiddleware` on the next tool call.
-     */
-    private handleInjectTool;
-    /**
-     * Bus callback: a queued injection was spliced into a real tool call. Re-emit
-     * `collab.injection.granted` with phase `'consumed'` and the now-known tool
-     * name. The injection carries no sessionId, so resolve it from the author's
-     * current session; if they've already left, fall back to every live session.
-     */
-    private broadcastInjectionConsumed;
-}
-
-/**
- * Pure filtering + ranking for the `files.list` project file picker (the chat
- * `@`-mention popup). The directory *walk* stays in index.ts (it's I/O), but
- * the two decisions that shape the result — which entries to hide and how to
- * rank matches — are pure and live here so the scoring weights, depth penalty,
- * and tie-break order can be unit tested. A silently-flipped weight would make
- * the picker feel subtly wrong with nothing to catch it.
- */
-/** Heavyweight build/vcs/dependency dirs the picker never descends into. */
-declare const SKIP_DIRS: ReadonlySet<string>;
-/**
- * Whether a directory entry should be hidden from the picker by its name.
- * Dotfiles are hidden by default, except a few commonly-wanted ones.
- */
-declare function isHiddenEntry(name: string): boolean;
-/**
- * Rank `paths` against `query` and return up to `limit` paths, best first.
- *
- * Scoring (cheap heuristic, good enough for a picker): exact basename match
- * (100) > basename prefix (60) > path substring (20); non-matches are dropped.
- * Each match is penalized by its path depth so root files sort first. Ties
- * break by lexicographic path. An empty query keeps every path (score 0), so
- * the result is the paths sorted lexicographically, capped to `limit`.
- */
-declare function rankFiles(paths: readonly string[], query: string, limit: number): string[];
-
-/**
- * HTTP /api/analytics handler for the WebUI server.
- *
- * Accepts a batch of analytics events from the frontend, validates them,
- * and stores them for later aggregation. Events are kept in a small
- * in-memory ring buffer (last 1000) and can be retrieved via GET for
- * debugging or exported to an external system.
- *
- * The endpoint is intentionally simple: no persistent storage, no external
- * dependencies. If you need durable analytics, poll the GET endpoint
- * and ship the events to your own aggregation pipeline (PostHog,
- * Segment, etc.).
- */
-
-interface AnalyticsEvent {
-    event: string;
-    category: string;
-    label?: string | undefined;
-    value?: number | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    timestamp: string;
-    sessionId?: string | undefined;
-    userAgent?: string | undefined;
-}
-/** POST /api/analytics — ingest a batch of events from the frontend. */
-declare function handleApiAnalyticsPost(res: http.ServerResponse, req: http.IncomingMessage): Promise<void>;
-/** GET /api/analytics — retrieve the last N events (debug/export). */
-declare function handleApiAnalyticsGet(res: http.ServerResponse, url: URL): Promise<void>;
-/** GET /api/analytics/summary — aggregated stats for quick inspection. */
-declare function handleApiAnalyticsSummary(res: http.ServerResponse): Promise<void>;
-/** Clear the in-memory buffer (useful for testing). */
-declare function clearAnalyticsBuffer(): void;
-/** Get a snapshot of the buffer (useful for testing). */
-declare function getAnalyticsBuffer(): readonly AnalyticsEvent[];
-
-/**
- * Process lifecycle for the WebUI server: graceful shutdown and the
- * SIGINT/SIGTERM wiring that triggers it.
- *
- * On a termination signal we (best-effort) flush + close the active session,
- * close every connected WebSocket, stop the HTTP and WS servers, then exit.
- * A re-entrancy guard makes a second signal during shutdown a no-op (rapid
- * double Ctrl+C no longer runs the teardown twice).
- *
- * Extracted from `index.ts` as a parameterized factory so the teardown
- * sequence can be unit tested without a real process signal, server, or
- * `process.exit` — `log` and `exit` are injectable seams.
- */
-interface LifecycleResources {
-    /** Persist + close the active session (best-effort; errors are logged). */
-    flushSession: () => Promise<void>;
-    /**
-     * Returns the currently-connected client sockets to close. A thunk (not a
-     * snapshot) so shutdown closes whoever is connected *at signal time*, not
-     * whoever was connected when the handler was registered.
-     */
-    clients: () => Iterable<{
-        close: () => void;
-    }>;
-    /** Servers to stop (HTTP + WS). `null`/`undefined` entries are skipped. */
-    servers: Array<{
-        close: () => void;
-    } | null | undefined>;
-    /**
-     * Optional best-effort cleanup run after the session flush and before exit
-     * (e.g. removing this process from the running-instance registry). Errors are
-     * logged, never thrown — cleanup must not block a clean shutdown.
-     */
-    onShutdown?: (() => Promise<void> | void) | undefined;
-    /** Output sink. Defaults to `console.log`. */
-    log?: ((msg: string) => void) | undefined;
-    /** Process exit. Defaults to `process.exit`. Injectable for tests. */
-    exit?: ((code: number) => void) | undefined;
-}
-/**
- * Build the graceful-shutdown handler. Returns an idempotent async function:
- * the first call runs the teardown, subsequent calls (e.g. a second SIGINT)
- * return immediately.
- */
-declare function createShutdown(res: LifecycleResources): () => Promise<void>;
-/**
- * Register the shutdown handler on SIGINT and SIGTERM. Returns an unregister
- * function that detaches both listeners (useful for tests and clean restarts).
- */
-declare function registerShutdownHandlers(res: LifecycleResources): () => void;
-
-/**
- * Mailbox WebSocket handlers for the WebUI.
- *
- * Handles `mailbox.messages` and `mailbox.agents` message types.
- * The frontend sends these to populate the mailbox panel; the server
- * reads from the project-level GlobalMailbox and responds.
- */
-
-interface MailboxHandlerDeps {
-    /** Absolute project root. */
-    projectRoot: string;
-    /** Global WrongStack root (~/.wrongstack). */
-    globalRoot: string;
-}
-/**
- * List recent mailbox messages. Frontend sends:
- *   { type: 'mailbox.messages', limit?: number, incompleteOnly?: boolean }
- *
- * Uses `incompleteOnly` so the server filters to active/unread messages,
- * making readByCount === 0 a reliable "unread to all agents" signal for
- * the ActivityBar badge count.
- */
-declare function handleMailboxMessages(ws: WebSocket, deps: MailboxHandlerDeps, payload: {
-    limit?: number;
-    agentId?: string;
-    unreadOnly?: boolean;
-    incompleteOnly?: boolean;
-} | undefined): Promise<void>;
-
-interface MailboxRouteHandlers {
-    messages: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-    agents: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-    clear: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-    purge: (ws: WebSocket, msg: WSClientMessage) => Promise<void> | void;
-}
-declare function handleMailboxRoute(ws: WebSocket, msg: WSClientMessage, handlers: MailboxRouteHandlers): Promise<boolean>;
-
-interface McpRouteHandlers {
-    list: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    add: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    update: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    remove: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    enable: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    disable: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    sleep: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    wake: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    restart: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    discover: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-}
-/**
- * Chain-of-responsibility dispatcher for the `mcp.*` WS message family.
- * Returns `true` if the message was handled by this layer (so the caller's
- * chain short-circuits), `false` if it should fall through to the next layer
- * or the residual switch.
- *
- * Owned prefixes (10 message types — full coverage of the MCP management
- * surface; the WebUI MCP panel only ever talks to the server through these):
- *   - mcp.list
- *   - mcp.add
- *   - mcp.update
- *   - mcp.remove
- *   - mcp.enable
- *   - mcp.disable
- *   - mcp.sleep
- *   - mcp.wake
- *   - mcp.restart
- *   - mcp.discover
- *
- * Regression-tested by packages/webui/tests/server/dispatcher-routing.test.ts.
- */
-declare function handleMcpRoute(ws: WebSocket, msg: WSClientMessage, handlers: McpRouteHandlers): Promise<boolean>;
-
-interface ModeRouteHandlers {
-    listModes: (ws: WebSocket) => Promise<void>;
-    switchMode: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-}
-declare function handleModeRoute(ws: WebSocket, msg: WSClientMessage, handlers: ModeRouteHandlers): Promise<boolean>;
-
-/**
- * Resolve the catalog entry to use for a saved provider's WebUI model list.
- * Runtime discovery injects provider-specific catalogs under the saved provider
- * id (for example `omniroute`), while older aliases may still need to fall
- * back to their generic wire/catalog `type`.
- */
-declare function resolveProviderCatalogForModels(modelsRegistry: Pick<ModelsRegistry, 'getProvider'>, providerId: string, cfg: Pick<ProviderConfig, 'type'> | undefined): Promise<ResolvedProvider | undefined>;
-/**
- * Resolve model metadata for a selected config provider. Prefer the saved
- * provider id so provider-specific runtime discovery (for example Omniroute)
- * supplies context/cost/capability metadata; fall back to cfg.type for aliases.
- */
-declare function resolveProviderModelMetadata(modelsRegistry: Pick<ModelsRegistry, 'getModel' | 'getProvider'> & Partial<Pick<ModelsRegistry, 'listProviders'>>, providerId: string, modelId: string, cfg: Pick<ProviderConfig, 'type' | 'family' | 'models' | 'customModels' | 'capabilities'> | undefined): Promise<ResolvedModel | undefined>;
-
-declare function isPathInside(root: string, target: string): boolean;
-declare function resolveWorkingDirInsideProject(projectRoot: string, inputPath: string): Promise<string>;
-
-interface PrefHelperDeps {
-    globalConfigPath: string;
-    vault: SecretVault;
-    logger: {
-        warn(msg: string): void;
-    };
-}
-/** Mutable holder for the serialized-config-write lock. The helpers update
- *  `lock` in place so callers keep a stable reference across writes (the
- *  lock is non-poisoning: a failed write resolves the chain but logs).
- *
- *  We use a holder object rather than returning the new lock because
- *  TypeScript flattens `Promise<Promise<void>>` into `Promise<void>`,
- *  which would make `await helper(...)` yield `void` instead of the new
- *  lock value. */
-interface ConfigWriteLockHolder {
-    lock: Promise<void>;
-}
-/**
- * Persist pref changes into the global config.json — the SAME keys the TUI
- * settings picker writes — so a toggle made in the browser survives restarts
- * and is visible to the CLI/TUI (and vice versa on next boot). Best-effort
- * and serialized behind the holder's `lock`; failures log but never break
- * the WS reply.
- */
-declare function persistPrefsToConfig(deps: PrefHelperDeps, holder: ConfigWriteLockHolder, payload: Record<string, unknown>): Promise<void>;
-
-interface PrefsRouteHandlers {
-    /** Respond to the WS client with the current pref snapshot. */
-    getPrefs: (ws: WebSocket) => Promise<void>;
-    /**
-     * Merge the supplied pref payload into context.meta, persist the durable
-     * keys to config.json, apply any runtime effects (YOLO toggle, feature-flag
-     * mutation, fallback chain update, AutoCompaction pipeline add/remove,
-     * logger.level), then broadcast the full current snapshot to all clients.
-     */
-    updatePrefs: (ws: WebSocket, payload: Record<string, unknown>) => Promise<void>;
-}
-/**
- * Chain-of-responsibility dispatcher for the `prefs.*` WS message family.
- * Returns `true` if the message was handled by this layer (so the caller's
- * chain short-circuits), `false` if it should fall through to the next layer
- * or the residual switch.
- *
- * Owned prefixes:
- *   - `prefs.get`
- *   - `prefs.update`
- *
- * Regression-tested by packages/webui/tests/server/dispatcher-routing.test.ts.
- */
-declare function handlePrefsRoute(ws: WebSocket, msg: WSClientMessage, handlers: PrefsRouteHandlers): Promise<boolean>;
-
-interface ProjectRouteHandlers {
-    listProjects: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    addProject: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    selectProject: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    setWorkingDir: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-}
-declare function handleProjectRoute(ws: WebSocket, msg: WSClientMessage, handlers: ProjectRouteHandlers): Promise<boolean>;
-
-interface ProjectEntry {
-    name: string;
-    root: string;
-    slug: string;
-    lastSeen?: string | undefined;
-    createdAt?: string | undefined;
-    /** Working directory of the most recent session (may differ from root). */
-    lastWorkingDir?: string | undefined;
-}
-interface ProjectsManifest {
-    projects: ProjectEntry[];
-}
-declare function projectsJsonPath(globalConfigPath: string): string;
-declare function loadManifest(globalConfigPath: string): Promise<ProjectsManifest>;
-declare function saveManifest(manifest: ProjectsManifest, globalConfigPath: string): Promise<void>;
-declare function ensureProjectDataDir(slug: string, globalConfigPath: string): Promise<string>;
-
-/**
- * Wire shape of one saved provider as broadcast over `providers.saved`.
- * The WebUI's `<ProviderModelsPanel>` consumes this — when
- * `pickedModelId` / `models` is missing, the panel renders the empty
- * state.
- */
-interface SavedProviderView {
-    id: string;
-    family?: string | undefined;
-    baseUrl?: string | undefined;
-    /** Saved model allowlist, verbatim (undefined / [] both possible). */
-    models?: string[] | undefined;
-    /** First entry of `models`, or undefined when the list is empty/unset. */
-    pickedModelId?: string | undefined;
-    apiKeys: Array<{
-        label: string;
-        maskedKey: string;
-        isActive: boolean;
-        createdAt: string;
-    }>;
-}
-/**
- * Canonical projection from in-memory `ProviderConfig` to the
- * `providers.saved` wire shape. Pure (no I/O) so it's unit-tested in
- * isolation — see `tests/server/provider-handlers-projection.test.ts`.
- *
- * Secrets never leave: every key is run through `maskedKey` before it
- * reaches the wire.
- */
-declare function projectSavedProviders(providers: Record<string, ProviderConfig>): SavedProviderView[];
-interface ProviderHandlerDeps {
-    globalConfigPath: string;
-    vault: _wrongstack_core.SecretVault;
-    /** Shared config write lock — serialized via chained promises */
-    setConfigWriteLock: (lock: Promise<void>) => void;
-    getConfigWriteLock: () => Promise<void>;
-    /** Broadcast a message to all connected WebUI clients */
-    broadcast: (clients: Map<WebSocket, ConnectedClient>, msg: WSServerMessage) => void;
-    /** Connected WebUI clients map */
-    clients: Map<WebSocket, ConnectedClient>;
-    /** Used by the ChatGPT OAuth flow's tier-2 model lookup (best-effort). */
-    modelsRegistry?: ModelsRegistry | undefined;
-}
-declare function createProviderHandlers(deps: ProviderHandlerDeps): {
-    handleKeyUpsert: (ws: WebSocket, providerId: string, label: string, apiKey: string) => Promise<void>;
-    handleKeyDelete: (ws: WebSocket, providerId: string, label: string) => Promise<void>;
-    handleKeySetActive: (ws: WebSocket, providerId: string, label: string) => Promise<void>;
-    handleProviderAdd: (ws: WebSocket, payload: {
-        id: string;
-        family: string;
-        baseUrl?: string | undefined;
-        apiKey?: string | undefined;
-    }) => Promise<void>;
-    handleProviderRemove: (ws: WebSocket, providerId: string) => Promise<void>;
-    handleProviderClearModels: (ws: WebSocket, providerId: string) => Promise<void>;
-    handleProviderUndoClear: (ws: WebSocket, providerId: string, previousModels: string[]) => Promise<void>;
-    handleProviderUpdate: (ws: WebSocket, payload: {
-        id: string;
-        family?: string | undefined;
-        baseUrl?: string | undefined;
-        envVars?: string[] | undefined;
-        models?: string[] | undefined;
-    }) => Promise<void>;
-    handleProviderProbe: (ws: WebSocket, providerId: string, timeoutMs?: number) => Promise<void>;
-    handleOAuthStart: (ws: WebSocket, kind: OAuthKind) => Promise<void>;
-    handleOAuthCode: (ws: WebSocket, kind: OAuthKind, input: string) => Promise<void>;
-    handleOAuthCancel: (ws: WebSocket, kind: OAuthKind) => void;
-    loadConfigProviders: () => Promise<Record<string, ProviderConfig>>;
-};
-
-interface ProviderRouteHandlers {
-    listProviders: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    listSavedProviders: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    listProviderModels: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    switchModel: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    refineModel: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    providerHandlers: ReturnType<typeof createProviderHandlers>;
-}
-declare function handleProviderRoute(ws: WebSocket, msg: WSClientMessage, routes: ProviderRouteHandlers): Promise<boolean>;
-
-interface ProviderStoreDeps {
-    globalConfigPath: string;
-    vault: DefaultSecretVault;
-}
-/**
- * Serializes concurrent config writes to prevent races between model.switch
- * and key.add/key.update handlers that both read-modify-write globalConfigPath.
- */
-declare function createConfigWriteLock(): {
-    readonly current: Promise<void>;
-    acquire(): {
-        prev: Promise<void>;
-        release: () => void;
-    };
-};
-interface ProviderStore {
-    load(): Promise<Record<string, ProviderConfig>>;
-    save(providers: Record<string, ProviderConfig>): Promise<void>;
-    normalizeKeys(cfg: ProviderConfig): ProviderApiKey[];
-    writeKeysBack(cfg: ProviderConfig, keys: ProviderApiKey[]): void;
-    maskedKey(key: string | undefined): string;
-}
-declare function createProviderStore(deps: ProviderStoreDeps): ProviderStore;
-
-interface SddBoardRouteHandlers {
-    handleMessage: (msg: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }) => Promise<void>;
-}
-/** Forward any `sdd.board.*` message to the SddBoardWebSocketHandler. */
-declare function handleSddBoardRoute(_ws: WebSocket, msg: WSClientMessage, handlers: SddBoardRouteHandlers): Promise<boolean>;
-
-interface SddWizardRouteHandlers {
-    handleMessage: (msg: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }) => Promise<void>;
-}
-/**
- * Forward the SDD wizard messages (`sdd.spec.*` and `sdd.run.start`) to the
- * SddWizardWebSocketHandler. Note `sdd.board.*` is handled separately by the
- * board route — the wizard owns spec-building + run kickoff, the board owns
- * live observation/control.
- */
-declare function handleSddWizardRoute(_ws: WebSocket, msg: WSClientMessage, handlers: SddWizardRouteHandlers): Promise<boolean>;
-
-interface SessionRouteHandlers {
-    newSession: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    clearContext: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    debugContext: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    compactContext: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    repairContext: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    listContextModes: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    switchContextMode: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    createContextMode: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    updateContextMode: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    deleteContextMode: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    listSessions: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    renameSession: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    deleteSession: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    resumeSession: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    saveSession: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    listCheckpoints: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    rewindSession: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-}
-declare function handleSessionRoute(ws: WebSocket, msg: WSClientMessage, handlers: SessionRouteHandlers): Promise<boolean>;
-
-interface ShellGitRouteHandlers {
-    gitInfo: (ws: WebSocket) => Promise<void>;
-    gitChanges: (ws: WebSocket) => Promise<void>;
-    gitDiff: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-    shellOpen: (ws: WebSocket, msg: WSClientMessage) => Promise<void>;
-}
-declare function handleShellGitRoute(ws: WebSocket, msg: WSClientMessage, handlers: ShellGitRouteHandlers): Promise<boolean>;
-
-interface SpecsRouteHandlers {
-    handleMessage: (msg: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }) => Promise<void>;
-}
-/** Forward any `specs.*` message to the SpecsWebSocketHandler. */
-declare function handleSpecsRoute(_ws: WebSocket, msg: WSClientMessage, handlers: SpecsRouteHandlers): Promise<boolean>;
-
-/** Loose inbound shape — matches the server's internal WSClientMessage. */
-type IncomingMessage = {
-    type: string;
-    payload?: unknown;
-};
-type PtyExit = {
-    exitCode: number;
-    signal?: number | undefined;
-};
-interface PtyProcess {
-    readonly pid?: number | undefined;
-    write(data: string): void;
-    resize(cols: number, rows: number): void;
-    kill(): void;
-    onData(cb: (data: string) => void): unknown;
-    onExit(cb: (event: PtyExit) => void): unknown;
-}
-interface NodePtyApi {
-    spawn(file: string, args: string[], opts: {
-        name: string;
-        cols: number;
-        rows: number;
-        cwd: string;
-        env: Record<string, string | undefined>;
-        useConptyDll?: boolean | undefined;
-    }): PtyProcess;
-}
-type LoadNodePty = () => NodePtyApi | null;
-type KillProcessTree = (pid: number) => void;
-/**
- * TerminalWebSocketHandler — backs the WebUI's integrated terminal panel.
- *
- * Mirrors the lifecycle shape of WorktreeWebSocketHandler but is *per-client*
- * and *interactive*: each connected WebSocket owns a map of real node-pty
- * sessions keyed by a client-chosen id. Browser xterm.js ⇄ pty wiring:
- *   - `terminal.create` → spawn a shell pty, stream its output back
- *   - `terminal.input`  → write keystrokes to the pty
- *   - `terminal.resize` → propagate xterm's fit dimensions
- *   - `terminal.close`  → kill the pty
- * When a client disconnects, every pty it owns is killed (no orphan shells).
- */
-declare class TerminalWebSocketHandler {
-    /** Resolves the cwd new terminals open in — tracks the live working dir. */
-    private readonly getCwd;
-    private readonly logger;
-    private readonly loadNodePty;
-    private readonly killProcessTree;
-    /** ws → (terminalId → pty). */
-    private readonly sessions;
-    constructor(
-    /** Resolves the cwd new terminals open in — tracks the live working dir. */
-    getCwd: () => string, logger: Logger, loadNodePty?: LoadNodePty, killProcessTree?: KillProcessTree);
-    addClient(ws: WebSocket): void;
-    /** Kill every pty owned by every client (server shutdown). */
-    dispose(): void;
-    /** True if this message was a terminal.* message (handled here). */
-    handleMessage(ws: WebSocket, msg: IncomingMessage): boolean;
-    private create;
-    private input;
-    private resize;
-    private close;
-    private disposeClient;
-    private killPty;
-    private killWindowsProcessTree;
-    private send;
-}
-
-/**
- * Token-usage cost math for the WebUI server.
- *
- * models.dev pricing is expressed in **dollars per 1,000,000 tokens**, and
- * providers omit the field entirely for free/unmetered plans. Both the
- * `session.start` payload (which ships the per-token rates to the client) and
- * `stats.get` (which reports an actual dollar figure) repeated the same
- * "read `model.cost.*` with a `?? 0` fallback, then divide by 1e6" logic
- * inline. Pulling it here keeps the rate normalization and the cost formula in
- * one tested place — a wrong field name or a missing `/ 1e6` silently produces
- * a plausible-but-wrong number, which is exactly what a unit test should pin.
- */
-/** Per-1,000,000-token pricing, normalized to numbers (0 when unpriced). */
-interface CostRates {
-    /** $ per 1M input tokens. */
-    input: number;
-    /** $ per 1M output tokens. */
-    output: number;
-    /** $ per 1M cache-read tokens. */
-    cacheRead: number;
-}
-/** Token counts for a turn/session. `cacheRead` is optional (older counters). */
-interface TokenUsage {
-    input: number;
-    output: number;
-    cacheRead?: number | undefined;
-}
-/**
- * Normalize a models.dev model object's pricing into {@link CostRates}.
- * Missing model, missing `cost`, or missing individual fields all yield 0 —
- * free/unmetered plans report `$0` rather than crashing.
- */
-declare function getCostRates(model: unknown): CostRates;
-/**
- * Dollar cost of `usage` at the given per-1M-token `rates`. Returns 0 when all
- * rates are 0 (unpriced plan).
+ * The implementation lives in `./server/` — `./server/index.ts` is the
+ * canonical barrel. Consumers (CLI, future cross-package code) should
+ * import from this file (the package root) for forward-compat.
  */
-declare function computeUsageCost(usage: TokenUsage, rates: CostRates): number;
-
-type PayloadValidationResult<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    message: string;
-};
-interface ModelSwitchPayload {
-    provider: string;
-    model: string;
-}
-declare function validateModelSwitchPayload(payload: unknown): PayloadValidationResult<ModelSwitchPayload>;
-interface PrefsUpdatePayload {
-    prefs: Record<string, unknown>;
-}
-interface MailboxMessagesPayload {
-    limit?: number;
-    agentId?: string;
-    unreadOnly?: boolean;
-    incompleteOnly?: boolean;
-}
-declare function validateMailboxMessagesPayload(payload: unknown): PayloadValidationResult<MailboxMessagesPayload | undefined>;
-interface MailboxAgentsPayload {
-    onlineOnly?: boolean;
-}
-declare function validateMailboxAgentsPayload(payload: unknown): PayloadValidationResult<MailboxAgentsPayload | undefined>;
-interface MailboxPurgePayload {
-    completedMaxAgeMs?: number;
-    incompleteMaxAgeMs?: number;
-}
-declare function validateMailboxPurgePayload(payload: unknown): PayloadValidationResult<MailboxPurgePayload | undefined>;
-interface BrainRiskPayload {
-    level: string;
-}
-declare function validateBrainRiskPayload(payload: unknown): PayloadValidationResult<BrainRiskPayload>;
-interface BrainAskPayload {
-    question: string;
-}
-declare function validateBrainAskPayload(payload: unknown): PayloadValidationResult<BrainAskPayload>;
-interface AutonomySwitchPayload {
-    mode: string;
-}
-declare function validateAutonomySwitchPayload(payload: unknown): PayloadValidationResult<AutonomySwitchPayload>;
-interface PlanTemplateUsePayload {
-    template: string;
-}
-declare function validatePlanTemplateUsePayload(payload: unknown): PayloadValidationResult<PlanTemplateUsePayload>;
-declare function validatePrefsUpdatePayload(payload: unknown): PayloadValidationResult<PrefsUpdatePayload>;
-interface SkillsCreatePayload {
-    name: string;
-    description: string;
-    scope: 'project' | 'global';
-}
-declare function validateSkillsCreatePayload(payload: unknown): PayloadValidationResult<SkillsCreatePayload>;
-interface SkillsEditPayload {
-    name: string;
-    body: string;
-}
-declare function validateSkillsEditPayload(payload: unknown): PayloadValidationResult<SkillsEditPayload>;
-interface ProcessKillPayload {
-    pid: number;
-}
-declare function validateProcessKillPayload(payload: unknown): PayloadValidationResult<ProcessKillPayload>;
-interface WorkingDirSetPayload {
-    path: string;
-}
-declare function validateWorkingDirSetPayload(payload: unknown): PayloadValidationResult<WorkingDirSetPayload>;
-interface ModeSwitchPayload {
-    id: string;
-}
-declare function validateModeSwitchPayload(payload: unknown): PayloadValidationResult<ModeSwitchPayload>;
-interface ContextModeIdPayload {
-    id: string;
-}
-declare function validateContextModeSwitchPayload(payload: unknown): PayloadValidationResult<ContextModeIdPayload>;
-declare function validateContextModeDeletePayload(payload: unknown): PayloadValidationResult<ContextModeIdPayload>;
-interface ContextModeCreatePayload {
-    id: string;
-    name: string;
-    description: string;
-    thresholds: {
-        warn: number;
-        soft: number;
-        hard: number;
-    };
-    preserveK: number;
-    eliseThreshold: number;
-}
-declare function validateContextModeCreatePayload(payload: unknown): PayloadValidationResult<ContextModeCreatePayload>;
-interface ContextModeUpdatePayload {
-    id: string;
-    name?: string;
-    description?: string;
-    thresholds?: {
-        warn?: number;
-        soft?: number;
-        hard?: number;
-    };
-    preserveK?: number;
-    eliseThreshold?: number;
-}
-declare function validateContextModeUpdatePayload(payload: unknown): PayloadValidationResult<ContextModeUpdatePayload>;
-interface ShellOpenPayload {
-    path: string;
-    target?: 'file' | 'terminal';
-}
-declare function validateShellOpenPayload(payload: unknown): PayloadValidationResult<ShellOpenPayload>;
-interface GitDiffPayload {
-    path: string;
-}
-declare function validateGitDiffPayload(payload: unknown): PayloadValidationResult<GitDiffPayload>;
-interface ProjectsAddPayload {
-    root: string;
-    name?: string;
-}
-declare function validateProjectsAddPayload(payload: unknown): PayloadValidationResult<ProjectsAddPayload>;
-interface ProjectsSelectPayload {
-    root: string;
-    name?: string;
-}
-declare function validateProjectsSelectPayload(payload: unknown): PayloadValidationResult<ProjectsSelectPayload>;
-
-export { type AutoPhaseRouteHandlers, AutoPhaseWebSocketHandler, type BackendServices, type BrainRouteHandlers, CollaborationWebSocketHandler, type CompletionHandlerOptions, type CompletionItemKind, type CompletionSuggestion, type ConnectedClient, type ContextBreakdown, type CreateHttpServerOptions, type CustomContextMode, type CustomModeStore, type DesignContext, type EternalBroadcast, type EternalSubscribe, type EternalSubscription, type KeyOpResult, type LspCompletionSource, type LspCompletionSourceRequest, type MailboxRouteHandlers, type MessageTokenEntry, type ModeRouteHandlers, type PendingConfirm, type ProjectRouteHandlers, type PromptsContext, type ProviderRouteHandlers, type ProviderStore, type ProvidersRecord, SKIP_DIRS, type SavedProviderView, SddBoardWebSocketHandler, type SddWizardDeps, SddWizardWebSocketHandler, type SddWizardWiringOptions, type SessionRouteHandlers, type ShellGitRouteHandlers, type ShellOpenRequest, type ShellOpenResult, type ShellOpenTarget, type SkillsContext, SpecsWebSocketHandler, TerminalWebSocketHandler, type ToolTokenEntry, type VerifyClientInput, type WSClientMessage, type WSServerMessage, type WebUIInstanceRecord, type WebUIOptions, WorktreeWebSocketHandler, addProvider, bootConfig, broadcast, browserOpenCommand, buildCspHeader, buildSddWizardDeps, buildWebUIAccessUrl, clearAnalyticsBuffer, computeUsageCost, createConfigWriteLock, createCustomModeStore, createEternalSubscription, createHttpServer, createProviderConfigIO, createProviderHandlers, createProviderStore, createShutdown, createToolLspCompletionSource, decodeSessionId, defaultBaseDir, deleteKey, ensureProjectDataDir, envFlag, errMessage, estimateContextBreakdown, estimateTokens, extractToken, extractTokenFromCookie, findFreePort, formatInstances, generateAuthToken, getAnalyticsBuffer, getCostRates, handleApiAnalyticsGet, handleApiAnalyticsPost, handleApiAnalyticsSummary, handleAutoPhaseRoute, handleBrainRoute, handleCompletionRequest, handleDesignList, handleDesignMaterialize, handleDesignSet, handleDesignState, handleDesignUse, handleDesignVerify, handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, handleGitChanges, handleGitDiff, handleGitInfo, handleGoalGet, handleMailboxMessages, handleMailboxRoute, handleMcpAdd, handleMcpDisable, handleMcpDiscover, handleMcpEnable, handleMcpList, handleMcpRemove, handleMcpRestart, handleMcpRoute, handleMcpSleep, handleMcpUpdate, handleMcpWake, handleMemoryForget, handleMemoryList, handleMemoryRemember, handleModeRoute, handlePrefsRoute, handleProcessKill, handleProcessKillAll, handleProcessList, handleProjectRoute, handlePromptsContent, handlePromptsCreate, handlePromptsFavorite, handlePromptsList, handlePromptsRecent, handlePromptsSearch, handlePromptsUsed, handleProviderRoute, handleSddBoardRoute, handleSddWizardRoute, handleSessionRoute, handleShellGitRoute, handleShellOpen, handleSkillsContent, handleSkillsCreate, handleSkillsEdit, handleSkillsExport, handleSkillsInstall, handleSkillsList, handleSkillsUninstall, handleSkillsUpdate, handleSpecsRoute, hostForBrowserUrl, hostHeaderOk, injectWsConfig, injectWsPort, isHiddenEntry, isInsideDist, isLoopbackBind, isLoopbackHostname, isPathInside, isPidAlive, isPortFree, isWildcardBind, listInstances, loadManifest, loadSavedProviders, maskedKey, messagePreview, messageTokens, normalizeKeys, openBrowser, patchConfig, persistPrefsToConfig, projectSavedProviders, projectsJsonPath, rankFiles, registerInstance, registerShutdownHandlers, registryPath, removeProvider, resolveAllPendingConfirms, resolveAuthToken, resolveProviderCatalogForModels, resolveProviderModelMetadata, resolveWorkingDirInsideProject, resolveYoloEligiblePendingConfirms, saveManifest, saveProviders, send, sendResult, setActiveKey, setupEvents, setupWebUICodebaseIndexing, startWebUI, statusProjectHashFromWatchFilename, stringifyContent, tokenMatches, unregisterInstance, upsertKey, validateAutonomySwitchPayload, validateBrainAskPayload, validateBrainRiskPayload, validateContextModeCreatePayload, validateContextModeDeletePayload, validateContextModeSwitchPayload, validateContextModeUpdatePayload, validateGitDiffPayload, validateMailboxAgentsPayload, validateMailboxMessagesPayload, validateMailboxPurgePayload, validateModeSwitchPayload, validateModelSwitchPayload, validatePlanTemplateUsePayload, validatePrefsUpdatePayload, validateProcessKillPayload, validateProjectsAddPayload, validateProjectsSelectPayload, validateShellOpenPayload, validateSkillsCreatePayload, validateSkillsEditPayload, validateWorkingDirSetPayload, verifyClient, writeKeysBack };
+export * from './server/index.js';
+//# sourceMappingURL=index.d.ts.map