@xingjisoft/neutrino 0.6.0 → 0.7.0

package/dist/web/hub.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The live-session hub.
+ *
+ * The terminal UI is the source of truth for a conversation: while a
+ * {@link ../screens/chat.js ChatScreen} is open it owns the message list, the
+ * streaming buffer and the busy/paused flags. The web server, however, must be
+ * able to (a) show *every* conversation live and (b) drive the running one
+ * (pause, resume, send). This hub is the bridge between the two.
+ *
+ * A screen registers itself once it is activated and unregisters when it is
+ * popped. Every time the screen changes something meaningful it calls
+ * {@link LiveHub.notify}, which coalesces rapid-fire updates (one per streamed
+ * token) and pushes a snapshot to any connected browser.
+ */
+import type { ConversationContext } from "../compact.js";
+import { type ApprovalMode, type Mode, type AgentMode, type ResolvedModelSelection } from "../config.js";
+import type { RiskAssessment } from "../llm/risk.js";
+import type { PlanState } from "../llm/plan.js";
+import type { ProFallback } from "../pro/config.js";
+import type { FastSnapshot } from "../fast/types.js";
+export type ModelChangeResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Complete proposal shown before a human or automated approval decision. */
+export interface LiveApprovalRequest {
+    id?: string;
+    tool: string;
+    level: "high" | "extreme";
+    arguments: Record<string, unknown>;
+    cwd: string;
+    summary: string;
+    reasons: string[];
+}
+export interface LiveReviewProgress {
+    total: number;
+    round: number;
+    rounds: number;
+    request?: LiveApprovalRequest;
+}
+export declare function liveApprovalDetails(tool: string, args: Record<string, unknown>, risk: RiskAssessment, cwd: string): LiveApprovalRequest;
+/** A message as understood by the web UI. */
+export type LiveWireMessage = {
+    role: "user" | "assistant";
+    content: string;
+} | {
+    role: "tool";
+    name: string;
+    arguments: Record<string, unknown>;
+    result: string;
+} | {
+    role: "summary";
+    content: string;
+    count: number;
+};
+/** A model request that failed and is being retried. */
+export interface LiveRetryNotice {
+    /** The attempt about to be made (2 = the first retry). */
+    attempt: number;
+    /** Total attempts allowed. */
+    attempts: number;
+    /** How long this attempt waits before going out. */
+    delayMs: number;
+}
+/** The small, frequently-changing part of a live session. */
+export interface LiveMeta {
+    task?: import("../llm/runtime.js").TaskSnapshot;
+    /** On-disk session id, or null until the conversation is first saved. */
+    sessionId: string | null;
+    title: string;
+    /**
+     * Nothing has been said in this conversation yet. The sidebar leaves such a
+     * session out of the list until it has content, so an abandoned new chat
+     * never turns into a history entry.
+     */
+    empty?: boolean;
+    provider: string;
+    model: string;
+    intensity: string;
+    busy: boolean;
+    paused: boolean;
+    queued: string | null;
+    compressing: boolean;
+    /** A failed history write, cleared after the next successful checkpoint. */
+    saveError?: string | null;
+    /** A retried model request, so the browser can explain the silence. */
+    retrying?: LiveRetryNotice | null;
+    tokens: {
+        prompt: number;
+        completion: number;
+    };
+    /** Tool call waiting for a human decision, or null. */
+    approval?: LiveApprovalRequest | null;
+    /** Reviewer count while an automated approval review is running. */
+    reviewing?: LiveReviewProgress | null;
+    /** What a running sub-agent is doing right now, or null when none is running. */
+    subagent?: string | null;
+    approvalMode?: ApprovalMode;
+    agentMode?: AgentMode;
+    /** Strategy frozen for the running turn; agentMode selects the next turn. */
+    activeAgentMode?: AgentMode;
+    fast?: FastSnapshot;
+    pro?: {
+        preset: string;
+        checking: boolean;
+        checkId: string;
+        models: Array<{
+            role: string;
+            provider: string;
+            model: string;
+            intensity: string;
+            tier: string;
+        }>;
+        fallbacks: ProFallback[];
+        error?: string;
+    };
+}
+/** Everything a browser needs to render a live conversation. */
+export interface LiveSnapshot extends LiveMeta {
+    key: string;
+    cwd: string;
+    messages: LiveWireMessage[];
+    context?: ConversationContext | null;
+    streamingContent: string | null;
+    /**
+     * The plan of the current turn. The terminal draws it in the info card; a
+     * browser client can render the same steps from here without parsing text.
+     */
+    plan?: PlanState | null;
+}
+/** A screen that can be observed and driven through the web UI. */
+export interface LiveAgent {
+    /**
+     * Workspace this conversation belongs to. Optional so existing embedders and
+     * terminal screens keep working; a missing mode means the standard workspace.
+     */
+    readonly mode?: Mode;
+    /** Working directory the conversation belongs to (used to group it by path). */
+    liveCwd(): string;
+    liveMeta(): LiveMeta;
+    liveSnapshot(key: string): LiveSnapshot;
+    /** Pause the in-flight turn (no-op when idle). */
+    livePause(): void;
+    /** Resume a paused conversation. */
+    liveResume(): void;
+    /** Append a user message and start (or queue) a turn. */
+    liveSend(text: string): void;
+    /** Answer a pending approval. Returns false when nothing was pending. */
+    liveApprove?(approved: boolean, approvalId?: string): boolean;
+    liveSetApprovalMode?(mode: ApprovalMode): void;
+    liveSetAgentMode?(mode: AgentMode): ModelChangeResult;
+    /** Empty the conversation in place (a new chat in the same folder). */
+    liveClear?(): void;
+    /** Apply a server-resolved choice to future turns, while idle or paused. */
+    liveConfigure?(selection: ResolvedModelSelection): ModelChangeResult;
+    liveSetProPreset?(preset: string): ModelChangeResult;
+    /** A terminal in another process handles these actions through its bridge. */
+    remoteAction?(action: string, body: unknown): Promise<{
+        status: number;
+        data: unknown;
+    }>;
+}
+/** Summary of a live session, as shown in the sidebar. */
+export interface LiveEntrySummary extends LiveMeta {
+    key: string;
+    cwd: string;
+}
+type Listener = (snapshot: LiveSnapshot) => void;
+declare class LiveHub {
+    private entries;
+    private seq;
+    /** Register a screen. Returns the stable key used to address it over HTTP. */
+    register(agent: LiveAgent): string;
+    unregister(key: string | null): void;
+    /**
+     * Whether a key is live. With a mode, keys from the other workspace are
+     * treated as unknown: the Pro page must never reach a terminal session.
+     */
+    has(key: string, mode?: Mode): boolean;
+    remoteAction(key: string): LiveAgent["remoteAction"] | null;
+    /** All live sessions, newest registration last. Optionally one workspace only. */
+    list(mode?: Mode): LiveEntrySummary[];
+    /** One-off snapshot, or null when the key is unknown. */
+    snapshot(key: string): LiveSnapshot | null;
+    /**
+     * Subscribe to a live session. The current snapshot is delivered immediately
+     * so a freshly-connected browser never has to wait for the next change.
+     */
+    subscribe(key: string, fn: Listener): (() => void) | null;
+    /**
+     * Mark a session as changed. Snapshots are only produced when somebody is
+     * listening, and duplicate snapshots (e.g. a cursor blink) are dropped.
+     */
+    notify(key: string | null): void;
+    private flush;
+    pause(key: string): boolean;
+    resume(key: string): boolean;
+    send(key: string, text: string): boolean;
+    /** Mode and message are committed synchronously; a running turn keeps its frozen strategy. */
+    sendConfigured(key: string, text: string, mode?: AgentMode): ModelChangeResult;
+    approve(key: string, approved: boolean, approvalId?: string): boolean;
+    configure(key: string, selection: ResolvedModelSelection): ModelChangeResult;
+    setProPreset(key: string, preset: string): ModelChangeResult;
+    setAgentMode(key: string, mode: AgentMode): ModelChangeResult;
+    setApprovalMode(key: string, mode: ApprovalMode): boolean;
+    /** Empty a live conversation in place, keeping its key and working folder. */
+    clear(key: string): boolean;
+}
+/** Process-wide singleton shared by the TUI and the web server. */
+export declare const hub: LiveHub;
+export {};

package/dist/web/hub.js

@@ -163,11 +163,23 @@ class LiveHub {
         this.notify(key);
         return true;
     }
-    approve(key, approved) {
+    /** Mode and message are committed synchronously; a running turn keeps its frozen strategy. */
+    sendConfigured(key, text, mode) {
+        if (!this.entries.has(key))
+            return { ok: false, error: "unknown live session" };
+        if (mode !== undefined) {
+            const changed = this.setAgentMode(key, mode);
+            if (!changed.ok)
+                return changed;
+        }
+        this.send(key, text);
+        return { ok: true };
+    }
+    approve(key, approved, approvalId) {
         const entry = this.entries.get(key);
         if (!entry || !entry.agent.liveApprove)
             return false;
-        const handled = entry.agent.liveApprove(approved);
+        const handled = entry.agent.liveApprove(approved, approvalId);
         this.notify(key);
         return handled;
     }

package/dist/web/localApi.d.ts

@@ -0,0 +1,11 @@
+import http from "node:http";
+import { type Mode } from "../config.js";
+export interface LocalApiHandle {
+    url: string;
+    token: string;
+    close(): Promise<void>;
+}
+type Route = (req: http.IncomingMessage, res: http.ServerResponse, url: URL, mode: Mode, pathname: string) => Promise<void>;
+/** A separate, authenticated listener: Web can bind to LAN without exposing this API. */
+export declare function startLocalApi(port: number, route: Route, publish: boolean): Promise<LocalApiHandle>;
+export {};

package/dist/web/localApi.js

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { AGENT_MODES, NEUTRINO_DIR } from "../config.js";
+import { getWebSettings } from "./settings.js";
+import { hub } from "./hub.js";
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+async function body(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const bytes = Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 1024 * 1024)
+            throw new Error("request too large");
+        chunks.push(bytes);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid JSON body");
+    return value;
+}
+/** A separate, authenticated listener: Web can bind to LAN without exposing this API. */
+export async function startLocalApi(port, route, publish) {
+    const token = randomBytes(32).toString("hex");
+    const epoch = randomUUID();
+    let seq = 0;
+    const watches = new Map();
+    const sockets = new Set();
+    const auth = (req) => {
+        const supplied = Buffer.from(String(req.headers.authorization ?? ""));
+        const expected = Buffer.from(`Bearer ${token}`);
+        return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+    };
+    const frame = (event) => `id: ${event.id}\nevent: ${event.name}\ndata: ${JSON.stringify(event.data)}\n\n`;
+    const send = (res, event) => {
+        if (res.destroyed || res.writableEnded)
+            return;
+        // A stalled client must not accumulate an unbounded queue in memory.
+        if (res.writableLength > 4 * 1024 * 1024) {
+            res.destroy();
+            return;
+        }
+        res.write(frame(event));
+    };
+    const watch = (key) => {
+        const existing = watches.get(key);
+        if (existing)
+            return existing;
+        if (!hub.snapshot(key))
+            return null;
+        if (watches.size >= 64) {
+            const idle = [...watches.entries()].filter(([, value]) => value.clients.size === 0).sort((a, b) => a[1].touched - b[1].touched)[0];
+            if (!idle)
+                return null;
+            idle[1].unsubscribe();
+            watches.delete(idle[0]);
+        }
+        const item = { events: [], bytes: 0, clients: new Set(), unsubscribe: () => { }, last: null, touched: Date.now() };
+        const emit = (name, data) => {
+            const event = { id: `${epoch}:${++seq}`, name, data, bytes: Buffer.byteLength(JSON.stringify(data)) };
+            item.events.push(event);
+            item.bytes += event.bytes;
+            while (item.events.length > 1 && (item.events.length > 256 || item.bytes > 4 * 1024 * 1024))
+                item.bytes -= item.events.shift().bytes;
+            for (const client of item.clients)
+                send(client, event);
+        };
+        watches.set(key, item);
+        const unsub = hub.subscribe(key, snapshot => {
+            const previous = item.last;
+            item.last = snapshot;
+            emit("snapshot", snapshot);
+            if (snapshot.approval?.id && snapshot.approval.id !== previous?.approval?.id)
+                emit("approval.requested", snapshot.approval);
+            if (previous?.approval?.id && previous.approval.id !== snapshot.approval?.id)
+                emit("approval.resolved", { id: previous.approval.id });
+        });
+        if (!unsub) {
+            watches.delete(key);
+            return null;
+        }
+        item.unsubscribe = unsub;
+        return item;
+    };
+    const sweeper = setInterval(() => {
+        for (const [key, item] of watches) {
+            if (!item.clients.size && (!hub.has(key) || Date.now() - item.touched > 10 * 60_000)) {
+                item.unsubscribe();
+                watches.delete(key);
+            }
+        }
+    }, 60_000);
+    sweeper.unref();
+    const statusFile = path.join(NEUTRINO_DIR, "api.json");
+    let actualPort = port;
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            // A browser-originated request must never be able to drive the agent, even
+            // if it can reach loopback. Do not trust forwarded addresses or Host.
+            if (req.headers.origin || req.headers.host !== `127.0.0.1:${actualPort}`) {
+                json(res, 403, { error: "local API requires a loopback Host and no Origin" });
+                return;
+            }
+            if (!auth(req)) {
+                json(res, 401, { error: "Bearer token required" });
+                return;
+            }
+            const url = new URL(req.url ?? "/", `http://127.0.0.1:${actualPort}`);
+            const match = /^\/api\/v1\/(.*)$/.exec(url.pathname);
+            if (!match) {
+                json(res, 404, { error: "not found" });
+                return;
+            }
+            let name = match[1];
+            let mode = "standard";
+            if (name.startsWith("pro/")) {
+                mode = "pro";
+                name = name.slice(4);
+            }
+            if (req.method === "GET" && name === "health") {
+                json(res, 200, { ok: true, version: 1 });
+                return;
+            }
+            if (req.method === "GET" && name === "capabilities") {
+                json(res, 200, { version: 1, workspaces: ["standard", "pro"], agent_modes: AGENT_MODES, streaming: "sse-snapshots", approval_ids: true });
+                return;
+            }
+            if (req.method === "GET" && name === "models") {
+                const settings = getWebSettings(mode);
+                json(res, 200, { providers: settings.providers, intensities: settings.intensities, ...(mode === "pro" ? { pro: settings.pro } : {}) });
+                return;
+            }
+            const approval = /^live\/([^/]+)\/approvals\/([^/]+)$/.exec(name);
+            if (approval && req.method === "POST") {
+                const key = decodeURIComponent(approval[1]), id = decodeURIComponent(approval[2]);
+                if (!hub.has(key, mode)) {
+                    json(res, 404, { error: "unknown live session" });
+                    return;
+                }
+                const input = await body(req);
+                if (typeof input.approved !== "boolean") {
+                    json(res, 400, { error: "approved must be a boolean" });
+                    return;
+                }
+                const remote = hub.remoteAction(key);
+                if (remote) {
+                    const result = await remote("approve", { approved: input.approved, approval_id: id });
+                    json(res, result.status, result.data);
+                    return;
+                }
+                if (!hub.approve(key, input.approved, id)) {
+                    json(res, 409, { error: "approval is no longer pending" });
+                    return;
+                }
+                json(res, 200, { ok: true, approved: input.approved });
+                return;
+            }
+            const stream = /^live\/([^/]+)\/events$/.exec(name);
+            if (stream && req.method === "GET") {
+                const key = decodeURIComponent(stream[1]);
+                if (!hub.has(key, mode)) {
+                    json(res, 404, { error: "unknown live session" });
+                    return;
+                }
+                const item = watch(key);
+                if (!item) {
+                    json(res, 503, { error: "too many watched sessions" });
+                    return;
+                }
+                res.writeHead(200, { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache, no-transform", Connection: "keep-alive", "X-Accel-Buffering": "no" });
+                res.write("retry: 2000\n\n");
+                const cursor = String(req.headers["last-event-id"] ?? "");
+                const index = cursor ? item.events.findIndex(event => event.id === cursor) : -1;
+                if (cursor && index < 0)
+                    res.write(`event: reset\ndata: ${JSON.stringify({ reason: "event history unavailable" })}\n\n`);
+                if (cursor && index >= 0)
+                    for (const event of item.events.slice(index + 1))
+                        send(res, event);
+                // Always provide a current snapshot, including when no event changed while disconnected.
+                const current = hub.snapshot(key);
+                if (current)
+                    res.write(`event: snapshot\ndata: ${JSON.stringify(current)}\n\n`);
+                item.clients.add(res);
+                item.touched = Date.now();
+                sockets.add(res);
+                const timer = setInterval(() => {
+                    if (!hub.has(key, mode)) {
+                        res.write("event: gone\ndata: {}\n\n");
+                        res.end();
+                        return;
+                    }
+                    res.write(": ping\n\n");
+                }, 15000);
+                timer.unref();
+                const cleanup = () => { clearInterval(timer); item.clients.delete(res); item.touched = Date.now(); sockets.delete(res); };
+                req.on("close", cleanup);
+                res.on("error", cleanup);
+                return;
+            }
+            // The shared Web handlers are the source of truth. Explicitly exclude
+            // application settings, login and service lifecycle controls.
+            if (/^(settings|auth|background)(\/|$)/.test(name) || /^live\/[^/]+\/approve$/.test(name)) {
+                json(res, 404, { error: "not found" });
+                return;
+            }
+            await route(req, res, url, mode, `/api/${name}`);
+        })().catch(error => { if (!res.headersSent)
+            json(res, 400, { error: error instanceof Error ? error.message : "invalid request" });
+        else
+            res.end(); });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => { server.removeListener("error", reject); resolve(); });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("local API failed to bind");
+    }
+    actualPort = address.port;
+    const url = `http://127.0.0.1:${actualPort}/api/v1`;
+    if (publish) {
+        try {
+            fs.mkdirSync(NEUTRINO_DIR, { recursive: true, mode: 0o700 });
+            const temporary = `${statusFile}.${process.pid}.${randomBytes(6).toString("hex")}`;
+            fs.writeFileSync(temporary, JSON.stringify({ pid: process.pid, url, token }), { mode: 0o600, flag: "wx" });
+            fs.renameSync(temporary, statusFile);
+        }
+        catch (error) {
+            clearInterval(sweeper);
+            server.close();
+            throw error;
+        }
+    }
+    server.on("error", () => { });
+    return { url, token, close: async () => {
+            clearInterval(sweeper);
+            for (const item of watches.values())
+                item.unsubscribe();
+            watches.clear();
+            for (const response of sockets)
+                response.destroy();
+            sockets.clear();
+            if (publish) {
+                try {
+                    const saved = JSON.parse(fs.readFileSync(statusFile, "utf8"));
+                    if (saved.token === token)
+                        fs.unlinkSync(statusFile);
+                }
+                catch { /* already gone */ }
+            }
+            await new Promise(resolve => { server.close(() => resolve()); server.closeAllConnections(); });
+        } };
+}

package/dist/web/plugins.d.ts

@@ -0,0 +1,8 @@
+import type http from "node:http";
+import type { Profile } from "../plugins/types.js";
+/** Called only after the server's existing authentication check. */
+export declare function handlePlugins(req: http.IncomingMessage, res: http.ServerResponse, url: URL, pathname: string, profile: Profile, helpers: {
+    sameOrigin: boolean;
+    read(): Promise<unknown>;
+    json(status: number, value: unknown): void;
+}): Promise<boolean>;

package/dist/web/plugins.js

@@ -0,0 +1,64 @@
+import { configurePlugin, installPlugin, listPlugins, pluginAsset, removePlugin, rollbackPlugin, selectProvider } from "../plugins/manager.js";
+import { pluginCatalog } from "../plugins/catalog.js";
+import { assert, object } from "../plugins/validation.js";
+/** Called only after the server's existing authentication check. */
+export async function handlePlugins(req, res, url, pathname, profile, helpers) {
+    if (pathname !== "/api/plugins" && !pathname.startsWith("/api/plugins/"))
+        return false;
+    try {
+        const cwd = url.searchParams.get("cwd") || undefined;
+        if (req.method === "GET") {
+            if (pathname === "/api/plugins")
+                helpers.json(200, listPlugins(profile, cwd));
+            else if (pathname === "/api/plugins/catalog")
+                helpers.json(200, pluginCatalog(profile, cwd));
+            else if (pathname === "/api/plugins/asset")
+                helpers.json(200, { body: pluginAsset(url.searchParams.get("id") ?? "", url.searchParams.get("file") ?? "", profile, cwd) });
+            else
+                helpers.json(404, { error: "Unknown plugin endpoint" });
+            return true;
+        }
+        if (req.method !== "POST" || pathname !== "/api/plugins") {
+            helpers.json(405, { error: "Method not allowed" });
+            return true;
+        }
+        if (!helpers.sameOrigin) {
+            helpers.json(403, { error: "cross-origin request rejected" });
+            return true;
+        }
+        const body = await helpers.read();
+        assert(object(body), "Invalid plugin request");
+        assert(body.revision === undefined || Number.isSafeInteger(body.revision), "Invalid plugin revision");
+        const revision = body.revision;
+        const id = String(body.id ?? "");
+        if (body.action === "install") {
+            assert(typeof body.source === "string", "Source directory is required");
+            installPlugin(body.source, revision);
+        }
+        else if (body.action === "configure") {
+            assert(object(body.patch), "Plugin patch is required");
+            assert(Object.keys(body.patch).every(k => ["enabled", "config", "trustNative"].includes(k)), "Unknown plugin patch field");
+            configurePlugin(id, body.patch, profile, cwd, revision);
+        }
+        else if (body.action === "remove")
+            removePlugin(id, revision);
+        else if (body.action === "update") {
+            const plugin = listPlugins(profile, cwd).plugins.find(p => p.manifest.id === id);
+            assert(plugin, "Unknown plugin");
+            installPlugin(plugin.source, revision);
+        }
+        else if (body.action === "rollback")
+            rollbackPlugin(id, revision);
+        else if (body.action === "provider") {
+            assert(typeof body.slot === "string" && typeof body.provider === "string", "Slot and provider are required");
+            selectProvider(body.slot, body.provider, profile, revision);
+        }
+        else
+            throw new Error("Unknown plugin action");
+        helpers.json(200, listPlugins(profile, cwd));
+    }
+    catch (e) {
+        helpers.json(e.message.includes("state changed") ? 409 : 400, { error: e.message });
+    }
+    return true;
+}

package/dist/web/server.d.ts

@@ -0,0 +1,81 @@
+import { type FolderPick } from "./folderPicker.js";
+import { type BackgroundStatus, type BackgroundUpdate } from "../background.js";
+export interface WebServerOptions {
+    /** Port to listen on. `0` lets the OS pick a free one. */
+    port: number;
+    /** Interface to bind. Defaults to loopback. */
+    host?: string;
+    /** Require password login by default. `false` explicitly disables authentication. */
+    auth?: boolean;
+    /**
+     * Offer the background-residency prompt to the first browser that opens this
+     * console. Only a console started by the terminal UI sets this.
+     */
+    backgroundPrompt?: boolean;
+    /**
+     * Present only in the detached background service: the token that authorizes
+     * `/api/background/{ping,stop}` and the callback that shuts the process down.
+     */
+    backgroundService?: {
+        token: string;
+        onStop: () => void;
+        status?: () => BackgroundStatus;
+        configure?: (update: BackgroundUpdate) => BackgroundStatus;
+    };
+    /** Keep service discovery in sync after a live LAN switch. */
+    onAddressChange?: () => void;
+    /**
+     * Opens the operating system's folder window and reports the chosen folder.
+     * Only replaced by tests, which run where no window can be drawn.
+     */
+    folderPicker?: FolderPicker;
+    /** Local API port. Zero selects an available port. */
+    apiPort?: number;
+    /** Publish connection information in the user data directory. */
+    publishApi?: boolean;
+    /** Run only the local API, with no Web listener. */
+    apiOnly?: boolean;
+}
+/**
+ * Draws the operating system's folder window on the desktop of this machine.
+ * The console opens one window at a time (see `startWebServer`).
+ */
+export type FolderPicker = (request: {
+    start?: string;
+    title?: string;
+}) => Promise<FolderPick>;
+export interface WebServerHandle {
+    /** Loopback URL. Always usable from this machine. */
+    url: string;
+    /** Addresses to open. Credentials are never included in URLs. */
+    urls: string[];
+    port: number;
+    host: string;
+    /** Whether a browser must log in before using the API. */
+    authRequired: boolean;
+    /** Local API connection information; token must be kept private. */
+    api?: {
+        url: string;
+        token: string;
+    };
+    /**
+     * Re-bind the same port on another interface. Live connections (a streaming
+     * turn, the tab asking for the change) stay open; resolves once the new
+     * socket is listening and rejects if it could not be bound.
+     */
+    setHost(host: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** True when `host` only accepts connections from this machine. */
+export declare function isLoopbackHost(host: string): boolean;
+/** True when `host` listens on every interface, i.e. what --lan selects. */
+export declare function isWildcardHost(host: string): boolean;
+/** The IPv4 addresses other devices can reach this machine on. */
+export declare function lanAddresses(): string[];
+/** Build the list of addresses worth showing to the operator. */
+export declare function webUrls(host: string, port: number): {
+    url: string;
+    urls: string[];
+};
+/** Start the web UI. Resolves once the socket is actually listening. */
+export declare function startWebServer(options: WebServerOptions): Promise<WebServerHandle>;