oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/index.js

@@ -1,543 +1,365 @@
 /**
- * oh-my-agent-web server — express + WebSocket hub in front of the codex app-server.
- *
- *   browser  <--ws /ws-->  [this]  <--ws-->  codex app-server (ws://127.0.0.1:25258)
- *
- * 我们是「透明 JSON-RPC 代理 + 进程守护」：
- *  - 浏览器可以按名字调用任意 codex 方法；所有 codex 通知原样广播。
- *  - `omaw/*` 是本地方法（状态 / 日志 / 文件系统 / 路径），由本进程处理。
- *  - codex 反向请求（审批 / user input / 动态工具）广播给所有标签页，谁先 reply 谁赢，
- *    随后广播 `serverRequest/resolved` 让其他标签页关掉弹窗。
- *  - 同一 `dist/server/index.js` 既能被 CLI `startServer()` 调用，也能直接 `node` 运行。
+ * 入口：一个 HTTP 端口 + 实时通道（WS 或 SSE/RPC，ADR-0032）。
  */
-import { existsSync, readFileSync } from "node:fs";
+import { homedir, networkInterfaces } from "node:os";
 import { createServer } from "node:http";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import express from "express";
-import { WebSocket, WebSocketServer } from "ws";
-import { CodexClient } from "./codex-client.js";
-import { CodexSupervisor } from "./codex-supervisor.js";
-import { RequestInspector } from "./request-inspector.js";
-import { FsError, listDirectory, paths as resolvePaths, readTextFile } from "./fs-service.js";
-import { LOCAL_METHODS, PROTOCOL_VERSION, } from "../shared/protocol.js";
-/* ------------------------------------------------------------------ */
-/* config                                                              */
-/* ------------------------------------------------------------------ */
-const DEFAULT_OMAW_PORT = 25257;
-const DEFAULT_OMAW_HOST = "127.0.0.1";
-const DEFAULT_CODEX_PORT = 25258;
-const DEFAULT_CODEX_BIN = "codex";
-const HEARTBEAT_MS = 30_000;
-const SERVER_REQUEST_HISTORY = 2_000;
-/**
- * How long a proxied `codex/*` call waits for the app-server before giving up
- * with `-32001`. Long enough to cover a cold `codex app-server` boot (and a
- * reconnect after a crash), short enough that a genuinely dead server still
- * reports an error quickly.
- */
-const CODEX_READY_WAIT_MS = 20_000;
-/**
- * `OMAW_DEV_WEB=1` —— dev 时前端不经 `web/dist`，而是把 Vite **挂在同一个进程里**
- * 当中间件（middleware mode）。
- *
- * 这样对外只有一个源、一个端口：`http://127.0.0.1:25257`。页面由 Vite 现编
- * （源码 + HMR，不用 build），`/ws` 与页面同源，也没有第二个端口要记、要开、
- * 或者要配置跨源白名单。
- */
-const DEV_SOURCE = process.env.OMAW_DEV_WEB === "1";
-/**
- * Vite 的 HMR 通道挂在同一个 http server 上，得给个专属路径，
- * 否则会和下面 `/ws` 的 upgrade 拦截器撞车（非 /ws 一律 destroy）。
- */
-const DEV_HMR_PATH = "/omaw-hmr";
-/* ------------------------------------------------------------------ */
-/* package metadata                                                    */
-/* ------------------------------------------------------------------ */
-/** 从当前文件向上找 package.json —— 兼容 tsx(src) 与 dist 两种目录深度。 */
-function findPackageRoot(startDir) {
-    let dir = startDir;
-    for (let i = 0; i < 8; i += 1) {
-        if (existsSync(join(dir, "package.json")))
-            return dir;
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return startDir;
-}
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const PACKAGE_ROOT = findPackageRoot(__dirname);
-function readOwnVersion() {
-    try {
-        const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
-        return pkg.version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
-function codexVersionFromHandshake(userAgent) {
-    if (!userAgent)
-        return null;
-    // 形如 `codex-cli 0.156.1` 或 `codex/0.156.1 ...`。
-    const match = /(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/.exec(userAgent);
-    return match ? match[1] : userAgent;
-}
-/* ------------------------------------------------------------------ */
-/* origin admission                                                    */
-/* ------------------------------------------------------------------ */
-function parseAllowOrigins() {
-    return (process.env.OMAW_ALLOW_ORIGINS ?? "")
-        .split(",")
-        .map((s) => s.trim().toLowerCase())
-        .filter(Boolean);
-}
-/**
- * 浏览器 upgrade 的 Origin 校验：
- *  - 无 Origin（curl / 脚本 / ws 测试）放行；
- *  - 设置了 OMAW_ALLOW_ORIGINS 就按白名单；
- *  - 否则放行同源，以及 localhost / 127.0.0.1 / ::1 的任意端口（覆盖 Vite dev server）。
- */
-function originAllowed(req) {
-    const origin = req.headers.origin;
-    if (typeof origin !== "string" || !origin)
-        return true;
-    const lower = origin.toLowerCase();
-    const allow = parseAllowOrigins();
-    if (allow.length > 0)
-        return allow.includes(lower);
-    if (lower === "null")
-        return false;
-    let url;
-    try {
-        url = new URL(origin);
-    }
-    catch {
-        return false;
-    }
-    const hostHeader = req.headers.host;
-    if (typeof hostHeader === "string" && hostHeader) {
-        try {
-            const hostUrl = new URL(`http://${hostHeader}`);
-            if (url.hostname === hostUrl.hostname && url.port === hostUrl.port)
-                return true;
-        }
-        catch {
-            /* ignore */
-        }
+import { WebSocketServer } from "ws";
+import { createEngineWiring } from "./engine/wiring.js";
+import { createFileRuleStore } from "./approval/rules.js";
+import { existsSync } from "node:fs";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { acquireLock, describeHolder, releaseLock } from "./session/lock.js";
+import { createRuntime } from "./session/runtime.js";
+import { createFileSettingsStore } from "./session/settings.js";
+import { createSender } from "./snapshot/sender.js";
+import { createPiSessionsProvider, piAgentDir } from "./session/pi-sessions-provider.js";
+import { createUploadStore, uploadsDir } from "./uploads/upload-store.js";
+import { builtinProviderGroups, createProviderWiring } from "./providers/provider-handlers.js";
+import { probeProvider } from "./providers/probe.js";
+import { createProviderStore } from "./providers/provider-store.js";
+import { createEnabledStore } from "./providers/enabled-models.js";
+import { migrateStoreToCatalog } from "./providers/catalog-writes.js";
+import { createPushStore, notifyTurnFinished } from "./push/push.js";
+import { registerAuxRoutes } from "./http/aux-routes.js";
+import { handleMessage } from "./ws/handle-message.js";
+import { registerHealthAndStatic } from "./http/health-and-static.js";
+import { registerUploadRoutes } from "./uploads/upload-routes.js";
+import { readConfig, validateConfig } from "./util/env.js";
+import { createLogger } from "./util/log.js";
+import { createRotatingFileSink, logFileName } from "./util/log-file.js";
+import { refreshPriceIndex } from "./util/pricing-index.js";
+import { describePolicy, isAllowedHost, isAllowedOrigin } from "./util/origin.js";
+import { pickExisting, webDistCandidates } from "./util/paths.js";
+import { authMiddleware, decide, effectiveAddress } from "./http/auth.js";
+import { registerAuthRoutes } from "./http/auth-routes.js";
+import { BRAND_NAME } from "./brand.js";
+import { registerLiveRoutes } from "./http/live-routes.js";
+import { compressText, immutableAssets } from "./http/compress.js";
+import { fanOutSnapshot } from "./snapshot/fan-out.js";
+import { checkDataDirWritable, describeListenError } from "./util/startup.js";
+import { migrateLegacyDataDir } from "./util/data-dir.js";
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+/** 开发态对外端口（Vite）；dev 脚本用它告诉后端可信来源 */
+const DEV_WEB_PORT = Number(process.env.AGENT_WEB_DEV_PORT ?? 25257);
+/** 快照节流窗口（ADR-0004 §3） */
+const SNAPSHOT_WINDOW_MS = 60;
+const TICK_MS = 20;
+/** socket 积压阈值：超过就只发事件、丢快照（ADR-0004 §4） */
+const BACKPRESSURE_BYTES = 256 * 1024;
+const { config, problems: envProblems } = readConfig(process.env, { home: homedir(), cwd: process.cwd() });
+let fileSink = null;
+const logger = createLogger({
+    level: config.logLevel,
+    scope: "app",
+    sink: (line) => {
+        process.stdout.write(`${line}\n`);
+        fileSink?.write(line);
+    },
+});
+// 单用户工作台：一处 fire-and-forget 的 Promise 拒绝（推送写盘失败、模型热重载失败……）
+// 不该把整个服务带走（Node ≥15 默认会直接退出）。记日志、继续跑。
+process.on("unhandledRejection", (reason) => {
+    logger.error("未处理的 Promise 拒绝（已记录，进程继续）", {
+        message: reason instanceof Error ? (reason.stack ?? reason.message) : String(reason),
+    });
+});
+/** 局域网地址自动放行；域名仍要显式配 */
+const localAddresses = Object.values(networkInterfaces())
+    .flat()
+    .filter((item) => Boolean(item) && item?.internal === false)
+    .map((item) => item.address);
+const policy = {
+    port: config.port,
+    devPorts: [DEV_WEB_PORT],
+    extraHosts: [...new Set([...localAddresses, ...config.allowedHosts])],
+};
+const sockets = new Set();
+let shuttingDown = false;
+const sender = createSender({
+    windowMs: SNAPSHOT_WINDOW_MS,
+    send: (frame) => {
+        if (frame.kind === "snapshot")
+            fanOut(frame.snapshot);
+    },
+});
+const piSessions = createPiSessionsProvider({ agentDir: piAgentDir(), dataDir: config.dataDir, logger });
+/** 引擎接线：注册表 + codex 客户端 + 每个引擎的会话来源（engine/wiring.ts） */
+const engineWiring = createEngineWiring({
+    engineName: config.engine,
+    codexBin: config.codexBin,
+    codexHome: config.codexHome,
+    dshBin: config.dshBin,
+    dshHome: config.dshHome,
+    dshModel: config.dshModel,
+    dshPatches: config.dshPatches,
+    dshPatchDir: join(config.dataDir, "dsh-patches"),
+    piSessions,
+    onNotice: (text, level) => runtimeRef.current?.notify(text, level),
+    onLog: (text, meta) => logger.warn(text, meta),
+});
+const engineCatalog = engineWiring.catalog;
+const resolved = engineWiring.resolved;
+const engine = resolved.engine;
+/** 引擎在 runtime 建好之前就会创建，用一个 ref 把「通知」转发给界面 */
+/** provider 配置存储（ADR-0025）：复用 pi 自己的 models-store.json / auth.json */
+const providerStore = createProviderStore({ agentDir: piAgentDir(), now: Date.now });
+/** 启动时的配置补齐（main 里会 await 它：避免和价格索引抢着读同一个文件） */
+const catalogMigration = migrateStoreToCatalog(piAgentDir()).then((migrated) => {
+    if (migrated.length > 0)
+        logger.info("已把老 provider 补进 models.json", { providers: migrated });
+});
+const enabledStore = createEnabledStore({ agentDir: piAgentDir() });
+const pushStore = createPushStore({ dataDir: config.dataDir, now: Date.now });
+const runProviderRequest = createProviderWiring({
+    store: providerStore,
+    logger,
+    probe: probeProvider,
+    enabled: enabledStore,
+    getRuntime: () => runtime,
+});
+const runtimeRef = {
+    current: null,
+};
+/** 懒读：provider 列表里要带上内置 provider 分组，而那需要 runtime 里的模型表 */
+const providerList = async () => {
+    const list = await providerStore.list(builtinProviderGroups(runtime?.state().models ?? []));
+    const live = runtime?.state();
+    if (live)
+        live.enabledModels = await enabledStore.read();
+    return list;
+};
+const runtime = createRuntime({
+    engine,
+    // 自定义 provider 来自 models-store.json；不主动读一次，界面上就只剩内置的那几个
+    loadProviders: providerList,
+    onTurnFinished: (info) => notifyTurnFinished(pushStore, info),
+    rules: createFileRuleStore(config.dataDir),
+    // 启动信息只进日志，不进对话流
+    onStartupInfo: (text) => logger.info(text),
+    workspace: config.workspace,
+    engineName: resolved.descriptor.name,
+    engineCapabilities: resolved.descriptor.capabilities,
+    turnTimeoutMs: config.turnTimeoutMs,
+    settings: createFileSettingsStore(config.dataDir),
+    uploadStore: {
+        read: (id) => uploadStore.read(id),
+        pathOf: (id) => join(uploadsDir(config.dataDir), id),
+    },
+    piSessions: engineCatalog.sessionsFor(resolved.descriptor.name) ?? undefined,
+    engines: engineCatalog,
+    emit: {
+        snapshot: (snapshot) => sender.pushSnapshot(snapshot),
+        event: (event) => {
+            broadcast(JSON.stringify(event));
+        },
+    },
+});
+runtimeRef.current = runtime;
+/** SSE 连接（纯 HTTP 通道）：clientId → 写入函数（每客户端一份快照，ADR-0033） */
+const sinks = new Map();
+const fanOut = (snapshot) => fanOutSnapshot(snapshot, { sockets, sinks, snapshotFor: (id) => runtime.snapshotFor(id) });
+function broadcast(payload) {
+    for (const socket of sockets) {
+        if (socket.readyState === socket.OPEN)
+            socket.send(payload);
     }
-    const hn = url.hostname.toLowerCase();
-    return hn === "localhost" || hn === "127.0.0.1" || hn === "::1" || hn === "[::1]";
+    for (const sink of sinks.values())
+        sink(payload);
 }
-/* ------------------------------------------------------------------ */
-/* helpers                                                             */
-/* ------------------------------------------------------------------ */
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
+async function dispatchRequest(socket, raw, clientId) {
+    await handleMessage(socket, raw, {
+        runtime,
+        ...(clientId ? { clientId } : {}),
+        reply,
+        sender,
+        logger,
+        runProviderRequest: (request, respond) => runProviderRequest(request, (result) => respond(result)),
+    });
 }
-function asJsonRpcError(err) {
-    if (err instanceof FsError)
-        return { code: err.code, message: err.message };
-    if (isRecord(err)) {
-        return {
-            code: typeof err.code === "number" ? err.code : -32000,
-            message: typeof err.message === "string" ? err.message : "internal error",
-            data: err.data,
-        };
-    }
-    return { code: -32000, message: err instanceof Error ? err.message : String(err) };
+function reply(socket, id, result) {
+    const message = result.ok
+        ? { type: "reply", id, ok: true, ...(result.result === undefined ? {} : { result: result.result }) }
+        : { type: "reply", id, ok: false, error: result.error };
+    socket.send(JSON.stringify(message));
 }
-/* ------------------------------------------------------------------ */
-/* startServer                                                         */
-/* ------------------------------------------------------------------ */
-export async function startServer(options = {}) {
-    const version = readOwnVersion();
-    const cwd = resolve(options.cwd ?? process.env.OMAW_CWD ?? process.cwd());
-    const port = options.port ?? Number(process.env.OMAW_PORT ?? DEFAULT_OMAW_PORT);
-    const host = options.host ?? process.env.OMAW_HOST ?? DEFAULT_OMAW_HOST;
-    const codexPort = options.codexPort ?? Number(process.env.OMAW_CODEX_PORT ?? DEFAULT_CODEX_PORT);
-    const codexBin = options.codexBin ?? process.env.OMAW_CODEX_BIN ?? DEFAULT_CODEX_BIN;
-    const log = options.quiet
-        ? () => undefined
-        : (...args) => {
-            console.log("[oh-my-agent-web]", ...args);
-        };
-    /* -------- supervisor + client (capture/inspector off by default) -------- */
-    // 抓包（loopback Responses 代理）默认关闭：只有显式设置 OMAW_REQUEST_INSPECTOR=1
-    // 才会启动 inspector，也才会给 app-server 注入 chatgpt_base_url /
-    // model_providers.capture.base_url 这两个 -c 覆盖。默认一个都不加，codex 走自己的配置。
-    const inspector = new RequestInspector({ dataDir: join(PACKAGE_ROOT, "data") });
-    let inspectorUrl = "";
-    if (process.env.OMAW_REQUEST_INSPECTOR === "1") {
-        try {
-            inspectorUrl = await inspector.start();
-            log(`request inspector: ${inspectorUrl} -> ${process.env.OMAW_CODEX_UPSTREAM ?? "https://chatgpt.com/backend-api/codex"}`);
-        }
-        catch (error) {
-            log(`request inspector disabled: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    const supervisor = new CodexSupervisor({ port: codexPort, bin: codexBin, cwd, codexBaseUrl: inspectorUrl || undefined });
-    const client = new CodexClient(supervisor.url, version);
-    supervisor.onLog((line) => {
-        if (!options.quiet)
-            console.log("[codex]", line);
+// ------------------------------ HTTP ------------------------------
+const app = express();
+// 登录端点必须挂在鉴权**之前**：此刻还没有 cookie，不能要求先过鉴权（ADR-0031 修订）
+registerAuthRoutes(app, { password: config.password, brandName: BRAND_NAME });
+// 鉴权其次：本机放行，其它来源必须过密码；页面请求给登录页，接口请求给 401
+app.use(authMiddleware({ password: config.password, brandName: BRAND_NAME }));
+app.use(express.json()); // 终端/技能/导入要读 body
+const webDist = pickExisting(webDistCandidates(HERE), existsSync);
+// 压缩 + 缓存头必须在 **API 路由注册之前** 挂：Express 按注册顺序匹配中间件，
+// 挂在后面就只影响之后注册的路由 —— `/api/rpc`（快照帧）这类大包会一直裸奔。
+// SSE / 终端流 / Range 媒体在 compress.ts 里显式跳过（不能攒、不能压）。
+app.use(compressText());
+app.use(immutableAssets());
+const uploadStore = createUploadStore({ dataDir: config.dataDir });
+registerUploadRoutes(app, { uploadStore, logger }); // 附件（ADR-0020 §P3）
+const workspaceOf = () => runtime.state().files?.root ?? config.workspace;
+registerAuxRoutes(app, {
+    providerStore,
+    workspaceOf,
+    projects: () => runtime.state().piProjects,
+    deleteSession: (id) => runtime.deleteSession(id),
+    pushStore,
+    onChange: () => void runProviderRequest({ type: "list_providers" }, () => { }),
+});
+registerLiveRoutes(app, {
+    sinks,
+    snapshotFor: (clientId) => runtime.snapshotFor(clientId),
+    clientTracker: { setSlim: runtime.clientView.setSlim, drop: runtime.clientView.drop },
+    logger,
+    handleMessage: async (clientId, shim, raw) => {
+        await dispatchRequest(shim, raw, clientId);
+    },
+});
+registerHealthAndStatic(app, {
+    workspace: config.workspace,
+    engine: config.engine,
+    webDist,
+    devWebPort: DEV_WEB_PORT,
+    counts: () => ({
+        sessions: runtime.state().piProjects.reduce((total, project) => total + project.sessions.length, 0),
+        conversations: runtime.state().conversations.length,
+    }),
+});
+const httpServer = createServer(app);
+// ---------------------------------------------------------------------------
+// WebSocket（握手校验是 ADR-0006 的核心条目）
+// ---------------------------------------------------------------------------
+const wss = new WebSocketServer({ noServer: true });
+httpServer.on("upgrade", (request, socket, head) => {
+    // WS 不走 Express 中间件，得在这里单独判一次
+    const forwarded = request.headers["x-forwarded-for"];
+    const auth = decide({
+        password: config.password,
+        remoteAddress: effectiveAddress(request.socket.remoteAddress, typeof forwarded === "string" ? forwarded : undefined),
+        authorization: request.headers.authorization,
+        cookie: request.headers.cookie,
     });
-    await supervisor.start();
-    void client.connect();
-    /* -------- HTTP app -------- */
-    const app = express();
-    app.disable("x-powered-by");
-    // 先建 http server：Vite 的 HMR 要挂到它上面（见下面的 middleware mode）。
-    // 路由按注册顺序匹配，所以这里提前 createServer 不影响 /api 的优先级。
-    const httpServer = createServer(app);
-    app.get("/api/health", (_req, res) => {
-        const body = { ok: true, codex: supervisor.status(), version };
-        res.json(body);
-    });
-    app.get("/api/version", (_req, res) => {
-        const hs = client.handshake();
-        res.json({
-            name: "oh-my-agent-web",
-            version,
-            protocolVersion: PROTOCOL_VERSION,
-            codexVersion: codexVersionFromHandshake(hs?.userAgent),
-            codexUserAgent: hs?.userAgent ?? null,
-            codexUrl: supervisor.url,
-        });
-    });
-    // 前端：dev 把 Vite 当中间件挂进本进程（源码 + HMR）；生产发 web/dist。
-    // 两种情况下对外都只有 http://127.0.0.1:<port> 一个源，页面与 /ws 同源。
-    if (DEV_SOURCE) {
-        // devDependency，且只在源码模式下加载。
-        const { createServer: createViteServer } = await import("vite");
-        const vite = await createViteServer({
-            configFile: join(PACKAGE_ROOT, "web", "vite.config.ts"),
-            // spa：index.html 的转换 + history fallback 都交给 Vite，
-            // 替代生产分支里那段 express 的 SPA fallback。
-            appType: "spa",
-            server: { middlewareMode: true, hmr: { server: httpServer, path: DEV_HMR_PATH } },
-        });
-        app.use(vite.middlewares);
-        httpServer.once("close", () => void vite.close());
-        log(`serving web UI from source via Vite (middleware mode, hmr=${DEV_HMR_PATH}, no build needed)`);
+    if (auth !== "allow") {
+        // 不发 WWW-Authenticate：那会让浏览器弹原生登录框，与自建登录页重复
+        socket.write(auth === "forbid" ? "HTTP/1.1 403 Forbidden\r\n\r\n" : "HTTP/1.1 401 Unauthorized\r\n\r\n");
+        socket.destroy();
+        return;
     }
-    else {
-        const webDist = join(PACKAGE_ROOT, "web", "dist");
-        if (existsSync(webDist)) {
-            app.use(express.static(webDist));
-            app.get(/^\/(?!api\/|ws).*/, (_req, res) => {
-                res.sendFile(join(webDist, "index.html"));
-            });
-            log(`serving web UI from ${webDist}`);
-        }
-        else {
-            log(`web/dist not found — dev 直接跑 \`npm run dev\`（源码模式，无需 build），生产先 \`npm run build\``);
-            app.get(/^\/(?!api\/|ws).*/, (_req, res) => {
-                res.status(404).type("text/plain").send("web/dist 不存在。dev 请跑 npm run dev（源码模式，无需 build）；生产请先 npm run build。");
-            });
-        }
+    const origin = request.headers.origin;
+    const host = request.headers.host;
+    if (!isAllowedOrigin(origin, policy) || !isAllowedHost(host, policy)) {
+        logger.warn("拒绝 WS 握手：来源不在白名单", { origin, host, policy: describePolicy(policy) });
+        socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+        socket.destroy();
+        return;
     }
-    /* -------- WebSocket hub -------- */
-    const wss = new WebSocketServer({ noServer: true });
-    const browsers = new Set();
-    const send = (ws, msg) => {
-        if (ws.readyState !== WebSocket.OPEN)
-            return;
-        try {
-            ws.send(JSON.stringify(msg));
-        }
-        catch {
-            /* ignore */
-        }
-    };
-    const broadcast = (msg) => {
-        for (const ws of browsers)
-            send(ws, msg);
-    };
-    const broadcastStatus = () => {
-        broadcast({ type: "status", codex: supervisor.status() });
-    };
-    let prevPhase = supervisor.status().phase;
-    supervisor.onStatus((status) => {
-        broadcastStatus();
-        // supervisor 重新就绪后主动拉一次 codex 连接，避免等满 client 自己的退避。
-        if (status.phase === "ready" && prevPhase !== "ready" && !client.isReady())
-            client.reconnect();
-        prevPhase = status.phase;
-    });
-    client.on("state", (state) => {
-        supervisor.setConnected(state.connected, state.error);
+    wss.handleUpgrade(request, socket, head, (websocket) => wss.emit("connection", websocket));
+});
+wss.on("connection", (socket) => {
+    sockets.add(socket);
+    logger.info("客户端已连接", { clients: sockets.size });
+    // 首屏：立刻给一份快照，不等节流窗口
+    sender.pushSnapshot(runtime.snapshot());
+    sender.flush(Date.now());
+    socket.on("message", (raw) => {
+        void dispatchRequest(socket, raw.toString());
     });
-    client.on("notification", (evt) => {
-        broadcast({ type: "event", method: evt.method, params: evt.params });
+    socket.on("close", () => {
+        sockets.delete(socket);
+        logger.info("客户端已断开", { clients: sockets.size });
     });
-    // codex 反向请求：广播给所有浏览器，记录待答复集合用于去重。
-    const pendingServerRequests = new Map();
-    const answeredServerRequests = new Set();
-    client.on("serverRequest", (evt) => {
-        const key = String(evt.id);
-        const threadId = isRecord(evt.params) && typeof evt.params.threadId === "string" ? evt.params.threadId : null;
-        pendingServerRequests.set(key, { method: evt.method, threadId });
-        broadcast({ type: "serverRequest", id: evt.id, method: evt.method, params: evt.params });
+    socket.on("error", (error) => {
+        logger.warn("socket 错误", { message: error.message });
+        sockets.delete(socket);
     });
-    client.on("state", (state) => {
-        // 断线后 codex 可能复用 request id，清掉去重历史避免误吞新请求。
-        if (!state.connected) {
-            pendingServerRequests.clear();
-            answeredServerRequests.clear();
-        }
-    });
-    function rememberAnswered(key) {
-        answeredServerRequests.add(key);
-        if (answeredServerRequests.size > SERVER_REQUEST_HISTORY) {
-            const first = answeredServerRequests.values().next().value;
-            if (first !== undefined)
-                answeredServerRequests.delete(first);
-        }
+});
+// 客户端请求分发在 ws/handle-message.ts（index 只负责装配）
+// ---------------------------------------------------------------------------
+// 启动
+// ---------------------------------------------------------------------------
+async function main() {
+    // 旧数据目录（~/.agent-web）自动搬到新目录：dev 直接跑本文件时也要搬
+    migrateLegacyDataDir({ dataDir: config.dataDir, log: (line) => logger.info(line) });
+    const problems = [...envProblems, ...validateConfig(config, { home: homedir() })];
+    if (problems.length > 0) {
+        for (const problem of problems)
+            logger.error(`启动自检失败：${problem}`);
+        process.exit(1);
     }
-    /* -------- local `omaw/*` methods -------- */
-    async function handleLocal(method, params) {
-        const p = isRecord(params) ? params : {};
-        switch (method) {
-            case LOCAL_METHODS.codexStatus:
-                return { status: supervisor.status() };
-            case LOCAL_METHODS.codexRestart:
-                await supervisor.restart();
-                client.reconnect();
-                return { ok: true };
-            case LOCAL_METHODS.codexLog:
-                return { lines: supervisor.logLines() };
-            case LOCAL_METHODS.requestLogsList:
-                return inspector.list(typeof p.threadId === "string" ? p.threadId : undefined, typeof p.limit === "number" ? p.limit : undefined);
-            case LOCAL_METHODS.requestLogsDetail: {
-                if (typeof p.id !== "string" || !p.id)
-                    throw new FsError(-32602, "omaw/request-logs/detail requires { id: string }");
-                const entry = await inspector.get(p.id);
-                if (!entry)
-                    throw new FsError(-32004, "request log not found");
-                return entry;
-            }
-            case LOCAL_METHODS.fsList:
-                return listDirectory({
-                    path: typeof p.path === "string" ? p.path : undefined,
-                    cwd,
-                    maxEntries: typeof p.maxEntries === "number" ? p.maxEntries : undefined,
-                });
-            case LOCAL_METHODS.fsRead:
-                if (typeof p.path !== "string")
-                    throw new FsError(-32602, "omaw/fs/read requires { path: string }");
-                return readTextFile({
-                    path: p.path,
-                    cwd,
-                    maxBytes: typeof p.maxBytes === "number" ? p.maxBytes : undefined,
-                });
-            case LOCAL_METHODS.paths: {
-                const codexHome = client.handshake()?.codexHome || process.env.CODEX_HOME || join(homedir(), ".codex");
-                return resolvePaths(cwd, codexHome);
-            }
-            default:
-                throw { code: -32601, message: `unknown local method: ${method}` };
-        }
+    const writable = await checkDataDirWritable(config.dataDir);
+    if (!writable.ok) {
+        logger.error(`启动自检失败：${writable.reason}`);
+        process.exit(1);
     }
-    /* -------- browser message handling -------- */
-    async function handleRpc(ws, requestId, method, params) {
-        try {
-            let result;
-            if (method.startsWith("omaw/")) {
-                result = await handleLocal(method, params);
-            }
-            else {
-                // A browser opened during startup races the app-server's boot (and a
-                // reconnect after a codex crash). Wait briefly instead of failing the
-                // client's first requests; only report -32001 if it never comes up.
-                if (!client.isReady() && !(await client.waitUntilReady(CODEX_READY_WAIT_MS))) {
-                    throw { code: -32001, message: "codex app-server not connected" };
-                }
-                result = await client.request(method, params);
-            }
-            send(ws, { type: "rpcResult", requestId, ok: true, result });
-        }
-        catch (err) {
-            send(ws, { type: "rpcResult", requestId, ok: false, error: asJsonRpcError(err) });
-        }
+    // 日志自己也住在数据目录里 → 确认可写之后再挂文件 sink
+    fileSink = createRotatingFileSink({ file: logFileName(config.dataDir), onError: (message) => logger.warn(message) });
+    // 单实例锁（ADR-0007）：必须在读/写任何会话数据之前拿到
+    const acquired = await acquireLock(config.dataDir, { pid: process.pid, port: config.port, startedAt: Date.now() });
+    if (!acquired.ok) {
+        logger.error("已经有一个 agent-web 在跑，本进程退出", { holder: describeHolder(acquired.holder) });
+        console.error(`\n已经有一个 agent-web 在这个数据目录上跑着：\n  ${describeHolder(acquired.holder)}\n`);
+        console.error(`  → 打开它：http://127.0.0.1:${acquired.holder.port}`);
+        console.error("  → 或者先停掉它（前台运行时 Ctrl-C 即可）\n");
+        process.exit(1);
     }
-    function handleReply(id, result, error) {
-        const key = String(id);
-        if (answeredServerRequests.has(key))
-            return; // 其他标签页已答复，忽略后来者
-        rememberAnswered(key);
-        const pending = pendingServerRequests.get(key);
-        pendingServerRequests.delete(key);
-        if (error)
-            client.respondError(id, error);
-        else
-            client.respond(id, result);
-        // 让其他标签页关闭审批弹窗；复用 codex 自己的通知名。
-        broadcast({
-            type: "event",
-            method: "serverRequest/resolved",
-            params: { threadId: pending?.threadId ?? null, requestId: id },
-        });
+    if (acquired.stale && acquired.previous) {
+        logger.warn("接管陈旧锁（上一个进程已不在）", { previous: describeHolder(acquired.previous) });
     }
-    async function onBrowserMessage(ws, raw) {
-        let parsed;
-        try {
-            parsed = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
-        }
-        catch {
-            log("忽略非 JSON 的浏览器报文");
-            return;
-        }
-        if (!isRecord(parsed) || typeof parsed.type !== "string")
-            return;
-        const msg = parsed;
-        switch (msg.type) {
-            case "rpc": {
-                if (typeof msg.requestId !== "string" || typeof msg.method !== "string")
-                    return;
-                await handleRpc(ws, msg.requestId, msg.method, msg.params);
-                return;
-            }
-            case "reply": {
-                if (msg.id === undefined || msg.id === null)
-                    return;
-                const hasError = "error" in msg && msg.error !== undefined;
-                const error = hasError ? asJsonRpcError(msg.error) : undefined;
-                handleReply(msg.id, msg.result, error);
-                return;
-            }
-            case "ping":
-                send(ws, { type: "pong" });
-                return;
-            default:
-                return;
-        }
-    }
-    wss.on("connection", (ws) => {
-        ws.__alive = true;
-        browsers.add(ws);
-        ws.on("pong", () => {
-            ws.__alive = true;
-        });
-        ws.on("message", (raw) => {
-            void onBrowserMessage(ws, raw).catch((err) => log("browser message handler error:", err));
-        });
-        ws.on("error", (err) => log("browser socket error:", err.message));
-        ws.on("close", () => browsers.delete(ws));
-        const info = {
-            version,
-            protocolVersion: PROTOCOL_VERSION,
-            cwd,
-            codexUrl: supervisor.url,
-            codexVersion: codexVersionFromHandshake(client.handshake()?.userAgent),
-            platform: process.platform,
-        };
-        send(ws, { type: "welcome", info });
-        send(ws, { type: "status", codex: supervisor.status() });
+    const { conversations } = await runtime.init().then(() => ({ conversations: runtime.state().conversations }));
+    // 分时价格索引（ADR-0026 D 期）：要在读历史 / 算账之前就绪；读不到就是空表 = 全部走引擎给的 cost
+    await catalogMigration.catch(() => undefined);
+    await refreshPriceIndex(piAgentDir());
+    void runProviderRequest({ type: "list_providers" }, () => { }); // 启动先填一次 provider 列表
+    logger.info("会话索引已装载", { conversations: conversations.length });
+    httpServer.on("error", (error) => {
+        logger.error(describeListenError(error, config.port, `可能是另一个 agent-web 或别的程序占着这个端口`));
+        void releaseLock(config.dataDir, process.pid).finally(() => process.exit(1));
     });
-    // 升级前做 origin 校验 + 路径校验；非 /ws 直接 destroy（dev 下 Vite 的 HMR 通道除外，
-    // 它由 Vite 自己在这个 server 上注册的 upgrade 监听器处理）。
-    httpServer.on("upgrade", (req, socket, head) => {
-        let pathname = "/";
-        try {
-            pathname = new URL(req.url ?? "/", "http://localhost").pathname;
-        }
-        catch {
-            /* fall through */
-        }
-        if (DEV_SOURCE && pathname === DEV_HMR_PATH)
-            return;
-        if (pathname !== "/ws") {
-            socket.destroy();
-            return;
-        }
-        if (!originAllowed(req)) {
-            socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
-            socket.destroy();
-            return;
-        }
-        wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
+    await new Promise((resolve) => httpServer.listen(config.port, config.host, resolve));
+    logger.info("agent-web 已启动", {
+        url: `http://${config.host}:${config.port}`,
+        workspace: config.workspace,
+        dataDir: config.dataDir,
+        engine: config.engine,
+        protocolVersion: PROTOCOL_VERSION,
+        conversations: runtime.state().conversations.length,
     });
-    // 心跳：30s 一次 ping，未回 pong 的直接 terminate。
-    const heartbeat = setInterval(() => {
-        for (const ws of browsers) {
-            if (ws.__alive === false) {
-                ws.terminate();
-                browsers.delete(ws);
-                continue;
-            }
-            ws.__alive = false;
-            try {
-                ws.ping();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-    }, HEARTBEAT_MS);
-    heartbeat.unref?.();
-    /* -------- listen -------- */
-    await new Promise((resolvePromise, rejectPromise) => {
-        httpServer.once("error", rejectPromise);
-        httpServer.listen(port, host, () => resolvePromise());
-    });
-    const address = httpServer.address();
-    const actualPort = typeof address === "object" && address ? address.port : port;
-    const url = `http://${host}:${actualPort}`;
-    log(`listening on ${url} (ws://${host}:${actualPort}/ws)`);
-    log(`codex app-server: ${supervisor.url} (${supervisor.isExternal() ? "external" : "managed"})`);
-    /* -------- close -------- */
-    let closed = false;
-    async function close() {
-        if (closed)
-            return;
-        closed = true;
-        clearInterval(heartbeat);
-        for (const ws of browsers) {
-            try {
-                ws.close(1001, "server shutting down");
-            }
-            catch {
-                /* ignore */
-            }
-            ws.terminate();
-        }
-        browsers.clear();
-        client.close();
-        await supervisor.stop();
-        await inspector.close();
-        await new Promise((resolvePromise) => {
-            wss.close(() => resolvePromise());
-            // 没有活跃连接时 wss.close 回调可能不触发；兜底。
-            setTimeout(resolvePromise, 500);
-        });
-        await new Promise((resolvePromise) => {
-            httpServer.close(() => resolvePromise());
-            setTimeout(resolvePromise, 500);
-        });
+    if (!webDist) {
+        logger.info("前端未构建，开发态请访问", { vite: `http://127.0.0.1:${DEV_WEB_PORT}` });
     }
-    return { port: actualPort, host, url, cwd, version, supervisor, client, close };
+    setInterval(() => {
+        const buffered = [...sockets].reduce((max, socket) => Math.max(max, socket.bufferedAmount), 0);
+        sender.setBusy(buffered > BACKPRESSURE_BYTES);
+        sender.tick(Date.now());
+    }, TICK_MS);
+    setInterval(() => {
+        for (const socket of sockets) {
+            if (socket.readyState === socket.OPEN)
+                socket.ping();
+        }
+    }, 25_000);
 }
-/* ------------------------------------------------------------------ */
-/* direct execution (node dist/server/index.js)                        */
-/* ------------------------------------------------------------------ */
-const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
-if (invokedPath === import.meta.url) {
-    startServer()
-        .then((handle) => {
-        const shutdown = (signal) => {
-            console.log(`\n[oh-my-agent-web] received ${signal}, shutting down…`);
-            void handle.close().finally(() => process.exit(0));
-        };
-        process.on("SIGINT", () => shutdown("SIGINT"));
-        process.on("SIGTERM", () => shutdown("SIGTERM"));
-    })
-        .catch((err) => {
-        console.error("[oh-my-agent-web] failed to start:", err);
-        process.exit(1);
-    });
+async function shutdown(signal) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    logger.info("收到退出信号，正在关闭", { signal });
+    sender.flush(Date.now());
+    engineWiring.close(); // 收掉 codex app-server 子进程（不给它留孤儿）
+    for (const socket of sockets)
+        socket.close(1001, "server shutting down");
+    wss.close();
+    httpServer.close();
+    // 锁要还回去：只有还属于自己时才删（避免删掉接管者的锁）
+    await releaseLock(config.dataDir, process.pid);
+    process.exit(0);
 }
+process.on("SIGINT", () => void shutdown("SIGINT"));
+process.on("SIGTERM", () => void shutdown("SIGTERM"));
+main().catch((error) => {
+    logger.error("启动失败", { message: error instanceof Error ? error.message : String(error) });
+    process.exit(1);
+});