oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/util/pricing-index.js

@@ -0,0 +1,121 @@
+/**
+ * 分时价格的**运行时索引**（`provider/model` → 时段表 + 全天价）。
+ *
+ * 为什么要有这一层：算钱的时候手里只有「模型名 + token 数 + 时刻」，
+ * 而那可能是每一轮里的每一次模型调用 —— 不能每次都去读 JSON。
+ * 所以在两处刷新一次、之后只查内存：
+ *   - 服务启动时（`server/index.ts`）；
+ *   - 模型表热重载时（`engine/model-registry-reload.ts` 本来就要读这两份配置）。
+ *
+ * 查不到 = 这个模型没配时段 → 调用方继续用引擎给的 cost（既有行为完全不变）。
+ * 配置写坏了（手改 JSON 写坏）→ 那一项当作没配，不抛、不把整张表带崩。
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { costOfUsage, normalizePrice, priceAt, validateSchedule, } from "./pricing.js";
+export const MODELS_FILE = "models.json";
+export const MODELS_STORE_FILE = "models-store.json";
+let byRef = new Map();
+let byModel = new Map();
+function toEntry(model) {
+    const parsed = validateSchedule(model.costSchedule, "分时价格");
+    const schedule = parsed.ok ? parsed.value : null;
+    const base = normalizePrice(model.cost);
+    if (!schedule && !base)
+        return null;
+    return { base, schedule };
+}
+/** 纯函数：把若干 provider 的模型摊成索引（同 provider/model 后者覆盖前者，与「自定义优先」一致） */
+export function buildPriceIndex(sources) {
+    const refs = new Map();
+    for (const source of sources) {
+        for (const model of source.models) {
+            if (typeof model?.id !== "string" || model.id === "")
+                continue;
+            const entry = toEntry(model);
+            const ref = `${source.provider}/${model.id}`;
+            if (entry)
+                refs.set(ref, entry);
+            else
+                refs.delete(ref);
+        }
+    }
+    // 裸模型名（只有一份时才认）：有的引擎只报 `modelId` 不带 provider
+    const bare = new Map();
+    for (const [ref, entry] of refs) {
+        const id = ref.slice(ref.indexOf("/") + 1);
+        if (!bare.has(id))
+            bare.set(id, entry);
+        else if (bare.get(id) !== entry)
+            bare.set(id, null); // 重名 → 有歧义，不猜
+    }
+    return { byRef: refs, byModel: bare };
+}
+/** 用一批配置替换索引（热重载 / 启动都用它） */
+export function setPriceIndex(sources) {
+    const built = buildPriceIndex(sources);
+    byRef = built.byRef;
+    byModel = built.byModel;
+}
+async function readJson(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {}; // 不存在 / 坏文件都按空表处理（可重建，见 ADR-0005）
+    }
+}
+/** 从 pi 的两份配置重建索引（自定义那份额外优先，和 provider 列表的顺序一致） */
+export async function refreshPriceIndex(agentDir) {
+    const [catalog, store] = await Promise.all([
+        readJson(join(agentDir, MODELS_FILE)),
+        readJson(join(agentDir, MODELS_STORE_FILE)),
+    ]);
+    const sources = [];
+    const collect = (raw) => {
+        if (typeof raw !== "object" || raw === null)
+            return;
+        for (const [provider, entry] of Object.entries(raw)) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const models = entry.models;
+            if (!Array.isArray(models))
+                continue;
+            sources.push({ provider, models: models });
+        }
+    };
+    collect(catalog.providers);
+    collect(store);
+    setPriceIndex(sources);
+}
+/** `provider/model` → 价格项；裸模型名也能查（无歧义时） */
+export function priceEntryFor(modelRef) {
+    if (typeof modelRef !== "string" || modelRef === "")
+        return null;
+    const exact = byRef.get(modelRef);
+    if (exact)
+        return exact;
+    // 引擎报的 provider 前缀和我们配置的不一致时，退回裸模型名（有重名就查不到，宁可不改账）
+    const slash = modelRef.lastIndexOf("/");
+    return byModel.get(slash >= 0 ? modelRef.slice(slash + 1) : modelRef) ?? null;
+}
+/**
+ * 这一刻这次调用该记多少钱（美元）。
+ *
+ * 返回 `undefined` = 这个模型没配分时价格 → 调用方保留引擎算出来的 cost。
+ * 配了时段之后**不再用**引擎的 cost：厂商的分时价引擎根本不知道，混着算只会更错。
+ */
+export function scheduledCost(modelRef, usage, atMs) {
+    const entry = priceEntryFor(modelRef);
+    if (!entry || !entry.schedule)
+        return undefined;
+    const price = priceAt(entry.schedule, entry.base, atMs);
+    if (!price)
+        return undefined;
+    return costOfUsage(usage, price);
+}
+/** 给测试/界面用：当前索引里配了分时价格的模型（`provider/model`） */
+export function scheduledModelRefs() {
+    return [...byRef.entries()].filter(([, entry]) => Boolean(entry.schedule)).map(([ref]) => ref);
+}

package/dist/server/util/pricing.js

@@ -0,0 +1,214 @@
+/**
+ * 分时价格（模型计费的扩展，ADR-0026 D 期）。
+ *
+ * 为什么需要：有的厂商按时段定价（高峰期 / 低峰期），一天里切成好几段，
+ * 同一百万 tokens 的钱在不同时段不一样。pi 的模型表只认「一个模型一套价」，
+ * 它算出来的 cost 在这些厂商身上必然是错的 —— 所以这里多存一张「时段 → 价格」表，
+ * 由**我们自己**按调用发生的时刻挑价格（引擎给的 cost 只在没配时段时兜底）。
+ *
+ * 约定（都写进界面提示里，别让用户猜）：
+ *   - `start` 必填，`end` 可空：空 = 一直用到**下一段**开始（最后一段跨零点回到最早那段）；
+ *   - `start > end` 表示跨零点（22:00–02:00）；
+ *   - 段内的价格字段可以留空：留空 = 沿用模型的「全天价格」（配置里那份 cost）；
+ *   - 时间按**本机时区**解释（界面显示什么就是什么，不做 UTC 换算）；
+ *   - 没配时段 = 全天一个价（既有行为完全不变）。
+ *
+ * 这一层是纯函数：不读文件、不看时钟（时间一律由调用方传 `atMs`），方便单测。
+ */
+export const PRICE_FIELDS = ["input", "output", "cacheRead", "cacheWrite"];
+export const MAX_PRICE_SEGMENTS = 32;
+export const MINUTES_PER_DAY = 1440;
+/** 纯函数：`HH:MM`（也认 `H:MM` / `HH:MM:SS`，秒直接丢掉）→ 当天第几分钟；不合法返回 null */
+export function parseClock(raw) {
+    if (typeof raw !== "string")
+        return null;
+    // 秒可有可无：浏览器 / 系统给的 time 值不统一（有的会带秒），
+    // 在这儿报「必须是 HH:MM」只会让用户莫名其妙
+    const match = /^(\d{1,2}):(\d{2})(?::\d{2}(?:\.\d+)?)?$/.exec(raw.trim());
+    if (!match)
+        return null;
+    const hours = Number(match[1]);
+    const minutes = Number(match[2]);
+    if (!Number.isFinite(hours) || !Number.isFinite(minutes))
+        return null;
+    if (hours > 23 || minutes > 59)
+        return null;
+    return hours * 60 + minutes;
+}
+/** 纯函数：分钟 → `HH:MM`（界面/日志用） */
+export function formatClock(minutes) {
+    const normalized = ((Math.round(minutes) % MINUTES_PER_DAY) + MINUTES_PER_DAY) % MINUTES_PER_DAY;
+    const hours = Math.floor(normalized / 60);
+    return `${String(hours).padStart(2, "0")}:${String(normalized % 60).padStart(2, "0")}`;
+}
+/** 纯函数：某一时刻是当天第几分钟（本机时区） */
+export function minutesOfDay(atMs) {
+    const date = new Date(atMs);
+    return date.getHours() * 60 + date.getMinutes();
+}
+/**
+ * 纯函数：把时段表展开成 `[start, end)` 窗口。
+ *
+ * 没填 end 的段落到下一段开始；**最后一段**落到最早那段的开始（跨零点回去），
+ * 这样「只填几个低峰窗口的起点」也能表达完整的 24 小时。
+ */
+export function windowsOf(schedule) {
+    const parsed = [];
+    for (const segment of schedule) {
+        const start = parseClock(segment.start);
+        if (start === null)
+            continue;
+        parsed.push({ segment, start });
+    }
+    parsed.sort((left, right) => left.start - right.start);
+    return parsed.map((item, index) => {
+        const explicit = parseClock(item.segment.end);
+        if (item.segment.end !== undefined && item.segment.end !== "" && explicit !== null) {
+            // 结束早于/等于开始 = 跨零点（22:00–02:00）
+            return { ...item, end: explicit > item.start ? explicit : explicit + MINUTES_PER_DAY };
+        }
+        const next = index + 1 < parsed.length
+            ? parsed[index + 1].start
+            : parsed[0].start + MINUTES_PER_DAY;
+        return { ...item, end: next > item.start ? next : next + MINUTES_PER_DAY };
+    });
+}
+/**
+ * 纯函数：`atMs` 这一刻生效的那一段。
+ *
+ * 没配时段 / 这一刻没有任何段覆盖 → null（调用方用全天价）。
+ * 段与段重叠时**起点更晚的那段优先**（更具体的配置赢）。
+ */
+export function activeSegment(schedule, atMs) {
+    if (!schedule || schedule.length === 0)
+        return null;
+    const minutes = minutesOfDay(atMs);
+    let best = null;
+    let bestOrder = Number.NEGATIVE_INFINITY;
+    for (const window of windowsOf(schedule)) {
+        // 跨零点的窗口（end > 1440）要把「明天的这份分钟数」也算一遍
+        const covered = (minutes >= window.start && minutes < window.end) ||
+            (minutes + MINUTES_PER_DAY >= window.start && minutes + MINUTES_PER_DAY < window.end);
+        if (!covered)
+            continue;
+        const order = window.start <= minutes ? window.start : window.start - MINUTES_PER_DAY;
+        if (order > bestOrder) {
+            bestOrder = order;
+            best = window;
+        }
+    }
+    return best ? best.segment : null;
+}
+/** 纯函数：把 cost 字段收敛成价格（驼峰 / 下划线都认；一个数都没有 → null） */
+export function normalizePrice(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const record = raw;
+    const number = (field) => {
+        const snake = field.replace(/[A-Z]/g, (char) => `_${char.toLowerCase()}`);
+        const value = record[field] ?? record[snake];
+        return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+    };
+    const input = number("input");
+    const output = number("output");
+    const cacheRead = number("cacheRead");
+    const cacheWrite = number("cacheWrite");
+    if (input === null && output === null && cacheRead === null && cacheWrite === null)
+        return null;
+    return { input: input ?? 0, output: output ?? 0, cacheRead: cacheRead ?? 0, cacheWrite: cacheWrite ?? 0 };
+}
+/**
+ * 纯函数：`atMs` 这一刻该用的价格。
+ *
+ * 段内没填的字段 → 全天价（`base`）；全天价也没有 → 0（这一项不收费，和 pi 的口径一致）。
+ * 段表和全天价都拿不到 → null（调用方保留引擎给的 cost）。
+ */
+export function priceAt(schedule, base, atMs) {
+    const segment = activeSegment(schedule, atMs);
+    if (!segment && !base)
+        return null;
+    const pick = (field) => {
+        const value = segment?.[field];
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+            return value;
+        return base?.[field] ?? 0;
+    };
+    return { input: pick("input"), output: pick("output"), cacheRead: pick("cacheRead"), cacheWrite: pick("cacheWrite") };
+}
+/** 纯函数：一次调用（或一轮合计）花多少钱（美元）。价格是「每百万 tokens」 */
+export function costOfUsage(usage, price) {
+    const tokens = (value) => (Number.isFinite(value) && value > 0 ? value : 0);
+    const total = tokens(usage.input) * price.input +
+        tokens(usage.output) * price.output +
+        tokens(usage.cacheRead) * price.cacheRead +
+        tokens(usage.cacheWrite) * price.cacheWrite;
+    return total / 1_000_000;
+}
+/**
+ * 纯函数：把配置里的原始值校验 + 收敛成时段表。
+ *
+ * 一次收集**全部**问题（前端的表单是手填的，挤牙膏式试错太烦）。
+ * 空数组 / 没填 = null（= 全天一个价）。
+ */
+export function validateSchedule(raw, label = "分时价格") {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: null };
+    if (!Array.isArray(raw))
+        return { ok: false, errors: [`${label}必须是数组`] };
+    if (raw.length === 0)
+        return { ok: true, value: null };
+    if (raw.length > MAX_PRICE_SEGMENTS)
+        return { ok: false, errors: [`${label}最多 ${MAX_PRICE_SEGMENTS} 段`] };
+    const errors = [];
+    const seen = new Set();
+    const segments = [];
+    raw.forEach((item, index) => {
+        const position = index + 1;
+        if (typeof item !== "object" || item === null) {
+            errors.push(`第 ${position} 段不是对象`);
+            return;
+        }
+        const record = item;
+        const start = parseClock(record.start);
+        if (start === null) {
+            errors.push(`第 ${position} 段起始时间必须是 HH:MM`);
+            return;
+        }
+        if (seen.has(start))
+            errors.push(`${formatClock(start)} 这个起始时间填了两次`);
+        seen.add(start);
+        const segment = { start: formatClock(start) };
+        const rawEnd = record.end;
+        if (rawEnd !== undefined && rawEnd !== null && rawEnd !== "") {
+            const end = parseClock(rawEnd);
+            if (end === null)
+                errors.push(`第 ${position} 段结束时间必须是 HH:MM（留空 = 到下一段开始）`);
+            else if (end === start)
+                errors.push(`第 ${position} 段结束时间和起始时间相同`);
+            else
+                segment.end = formatClock(end);
+        }
+        for (const field of PRICE_FIELDS) {
+            const value = record[field];
+            if (value === undefined || value === null || value === "")
+                continue;
+            const number = typeof value === "number" ? value : Number(String(value).trim());
+            if (!Number.isFinite(number) || number < 0) {
+                errors.push(`第 ${position} 段${PRICE_LABELS[field]}必须是非负数（留空 = 沿用全天价）`);
+                continue;
+            }
+            segment[field] = number;
+        }
+        segments.push(segment);
+    });
+    if (errors.length > 0)
+        return { ok: false, errors };
+    segments.sort((left, right) => (parseClock(left.start) ?? 0) - (parseClock(right.start) ?? 0));
+    return { ok: true, value: segments.length > 0 ? segments : null };
+}
+export const PRICE_LABELS = {
+    input: "输入价格",
+    output: "输出价格",
+    cacheRead: "缓存读价格",
+    cacheWrite: "缓存写价格",
+};

package/dist/server/util/startup.js

@@ -0,0 +1,34 @@
+/**
+ * 启动自检（ADR-0007 §启动自检）。
+ *
+ * 「能不能跑起来」必须在启动那一刻说清楚，而不是等用户往里打字时才炸。
+ * 三项检查：数据目录可写 · 工作区根合法（在 util/env.ts）· 端口可用（在 index.ts）。
+ */
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** 数据目录可写：建目录 + 写一个探针文件再删掉（比只看权限位可靠） */
+export async function checkDataDirWritable(dataDir) {
+    try {
+        await mkdir(dataDir, { recursive: true });
+        const probe = join(dataDir, ".write-probe");
+        await writeFile(probe, "ok", "utf8");
+        await rm(probe, { force: true });
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `数据目录不可写：${dataDir}（${error instanceof Error ? error.message : String(error)}）`,
+        };
+    }
+}
+/** 把 listen 的错误翻译成人话（尤其是「端口被占」这种最常见的一种） */
+export function describeListenError(error, port, holderHint) {
+    if (error.code === "EADDRINUSE") {
+        const hint = holderHint ? `；${holderHint}` : "；先确认是否已有实例在跑（看数据目录里的 server.lock）";
+        return `端口 ${port} 已被占用，本进程退出${hint}`;
+    }
+    if (error.code === "EACCES")
+        return `没有权限监听端口 ${port}（小于 1024 的端口通常需要特权）`;
+    return `监听端口 ${port} 失败：${error.code ?? "未知错误"}`;
+}

package/dist/server/util/upstream-version.js

@@ -0,0 +1,140 @@
+/**
+ * 上游（GitHub）最新版本号：新会话抬头的 `web v0.1.0` 靠它决定「要不要标红提醒有新版」。
+ *
+ * 为什么是查上游而不是读本地两份 package.json：抬头那行是在说「我在跑哪个版本」，
+ * 只有跟**已发布的版本**比，才知道「该不该提醒你去更新」。
+ *
+ * 三条纪律：
+ *   - **绝不抛、绝不阻塞**：离线 / 超时 / 被墙 / 上游文件写坏都只是 `null` = 不知道有没有新版，
+ *     界面照旧显示版本号、不标红、不弹提示条。启动不能因为一次网络请求慢半拍。
+ *   - **只在服务端查**：浏览器直连 raw.githubusercontent 要看 CORS 与代理脸色；
+ *     而且「上游是什么」本来就该是服务端作为唯一事实源给出的（ADR-0012）。
+ *   - **一个进程内低频查**：成功缓存 6 小时、失败缓存 10 分钟（慢网不至于被重试拖死），
+ *     再配合定时器轮询 —— 服务器开着好几天也能在下次轮询时看到新版本。
+ */
+/** 仓库地址：抬头那行版本号点它跳过去（前端也 import 这份常量，避免两处各写一遍） */
+export const REPO_URL = "https://github.com/duzhenxun/oh-my-agent-web";
+/** 拿版本号的分支：跟 `main` 上的 package.json 对齐（发版就是改那里） */
+export const REPO_BRANCH = "main";
+/** 只要一个版本号，不必走 GitHub API（匿名 API 有速率限制，raw 没有） */
+export const VERSION_URL = `https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/${REPO_BRANCH}/package.json`;
+/** 一次请求最多等这么久：等不到就当没网 */
+export const FETCH_TIMEOUT_MS = 4000;
+/** 成功结果的保鲜期：6 小时（发版是低频事件，没必要频繁打人家的 CDN） */
+export const OK_TTL_MS = 6 * 60 * 60 * 1000;
+/** 失败结果的保鲜期：10 分钟（断网时别每帧都去试） */
+export const FAIL_TTL_MS = 10 * 60 * 1000;
+/**
+ * 从 package.json 文本里抠 `"version"`。
+ *
+ * 不 `JSON.parse`：上游文件里我们只要这一个字段，别的字段写坏（注释、尾逗号）不该连版本号一起丢。
+ */
+export function parseVersion(text) {
+    const matched = /"version"\s*:\s*"([^"]+)"/.exec(text);
+    const version = matched?.[1]?.trim();
+    return version ? version : null;
+}
+/** 版本号切成数字段：`v1.2.3` → `[1,2,3]`；`1.2.3-beta.1` 的预发布后缀忽略（比大小只看前三段） */
+function versionParts(version) {
+    return version
+        .replace(/^v/i, "")
+        .split("-")[0]
+        .split(".")
+        .map((item) => {
+        const parsed = Number.parseInt(item, 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+    });
+}
+/** 比大小：`a` 新于 `b` 返回正数，相等 0，更旧负数（缺的段按 0 算，所以 `1.0` == `1.0.0`） */
+export function compareVersions(a, b) {
+    const left = versionParts(a);
+    const right = versionParts(b);
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const diff = (left[index] ?? 0) - (right[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * 上游比本机新吗（= 该提醒更新了）。
+ *
+ * 本机反而更新（本地改了版本号还没发版）**不算** —— 那时候标红会误导人跑去「更新」，
+ * 而他要的其实是「发布」。
+ */
+export function isOutdated(latest, current) {
+    if (!latest)
+        return false;
+    if (current === "" || current === "unknown")
+        return false; // 读不到本机版本时不给结论
+    return compareVersions(latest, current) > 0;
+}
+/** 真去拉一次（不带缓存）：任何异常都咽掉，返回 null */
+export async function fetchLatestVersion(options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl)
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? FETCH_TIMEOUT_MS);
+    timer.unref?.();
+    try {
+        const response = await fetchImpl(options.url ?? VERSION_URL, { signal: controller.signal });
+        if (!response.ok)
+            return null;
+        return parseVersion(await response.text());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 带缓存的上游版本查询：同一个进程里多处调用只算一次网络（在飞时合并成同一个 promise）。
+ *
+ * 缓存是模块级的：启动流程、回调、定时器都可能问它，各自持有一份缓存就会各打一次网络。
+ */
+let cache = null;
+let inflight = null;
+export async function checkUpstreamVersion(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const ttl = cache?.value ? OK_TTL_MS : FAIL_TTL_MS;
+    if (cache && now() - cache.at < ttl)
+        return cache.value;
+    if (inflight)
+        return inflight;
+    inflight = fetchLatestVersion(options)
+        .then((value) => {
+        cache = { value, at: now() };
+        return value;
+    })
+        .finally(() => {
+        inflight = null;
+    });
+    return inflight;
+}
+/**
+ * 起一个「盯着上游版本」的定时器：先立刻查一次，之后每隔 `intervalMs` 再查（缓存过期的才会真发请求）。
+ *
+ * 回调只在**拿到的值和上一次不同**（且不是 null）时触发 —— 界面照这个值刷一帧就够，
+ * 不必每 6 小时白推一帧一模一样的快照。返回停止函数（测试 / 收摊用）。
+ *
+ * 轮询间隔取**短的**那个 TTL（10 分钟）：多数情况下缓存还没过期，醒一下不花一个字节；
+ * 而启动时那次网络万一赶上断网，10 分钟后就能自愈，不用等满 6 小时。
+ */
+export function startUpstreamVersionWatch(onChange, options = {}) {
+    let last = null;
+    const tick = () => {
+        void checkUpstreamVersion(options).then((latest) => {
+            if (!latest || latest === last)
+                return;
+            last = latest;
+            onChange(latest);
+        });
+    };
+    tick();
+    const timer = setInterval(tick, options.intervalMs ?? FAIL_TTL_MS);
+    timer.unref?.(); // 别拦着进程退出
+    return () => clearInterval(timer);
+}

package/dist/server/util/usage.js

@@ -0,0 +1,19 @@
+const num = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+export function parseUsage(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const usage = raw;
+    const parsed = {
+        input: num(usage.inputTokens ?? usage.input ?? usage.input_tokens ?? usage.promptTokens),
+        output: num(usage.outputTokens ?? usage.output ?? usage.output_tokens ?? usage.completionTokens),
+        cacheRead: num(usage.cacheReadTokens ?? usage.cacheRead ?? usage.cache_read ?? usage.cachedTokens),
+        cacheWrite: num(usage.cacheWriteTokens ?? usage.cacheWrite ?? usage.cache_write),
+    };
+    if (parsed.input + parsed.output + parsed.cacheRead + parsed.cacheWrite === 0)
+        return null;
+    // 花费：provider 没配价格 / 免费模型时 pi 不给 cost，这种就不显示
+    const costTotal = num(usage.cost?.total);
+    if (costTotal > 0)
+        parsed.cost = costTotal;
+    return parsed;
+}

package/dist/server/util/version.js

@@ -0,0 +1,50 @@
+/**
+ * 版本号的**唯一来源**：本包的 `package.json`。
+ *
+ * 三处会用到它，必须读同一份、算同一个值：
+ *   - 新会话抬头 `web v0.1.0 · pi v1.3.0`（快照里的 `versions.web`）
+ *   - `/api/health` 的 `version`（`omaw status` 用它判断「跑着的进程是不是旧版」）
+ *   - `omaw version` / `omaw upgrade`
+ *
+ * 为什么是「从当前模块往上找 package.json」而不是写死相对路径：开发态在 `server/util/`、
+ * 构建后在 `dist/server/util/`，层级不同；而且不能写死包名 —— 包名已经改过一次
+ * （`agentweb` → `oh-my-agent-web`），写死就会静默退化成 `unknown`（踩过）。
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cached = null;
+/**
+ * 读本包的 package.json。
+ *
+ * 从模块所在目录一路往上找，最多 5 层：`dist/server/util` → `dist/server` → `dist` → 包根。
+ * 认「有 name + version 的第一份」即可 —— 起点就在我们自己目录里，先撞到的必然是本包。
+ */
+export function packageMeta(fromUrl = import.meta.url) {
+    if (cached)
+        return cached;
+    let dir = dirname(fromUrl.startsWith("file:") ? fileURLToPath(fromUrl) : fromUrl);
+    for (let depth = 0; depth < 5; depth += 1) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (typeof parsed.name === "string" && typeof parsed.version === "string") {
+                cached = { name: parsed.name, version: parsed.version, private: parsed.private === true };
+                return cached;
+            }
+        }
+        catch {
+            // 这一层没有 / 读不了 → 继续往上
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // 读不到也别让界面炸：显示 unknown，其余功能照常
+    cached = { name: "oh-my-agent-web", version: "unknown", private: true };
+    return cached;
+}
+/** web 版本；找不到就回 `"unknown"` */
+export function webVersion(fromUrl = import.meta.url) {
+    return packageMeta(fromUrl).version;
+}

package/dist/server/ws/handle-message.js

@@ -0,0 +1,95 @@
+import { parseClientRequest } from "../protocol.js";
+export async function handleMessage(socket, raw, deps) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        deps.logger.warn("收到非法 JSON，已忽略");
+        return;
+    }
+    const request = parseClientRequest(parsed);
+    if (!request) {
+        const id = typeof parsed?.id === "string" ? parsed.id : "unknown";
+        const type = parsed?.type;
+        const error = typeof type === "string"
+            ? { code: "protocol.bad_payload", message: `请求 ${type} 的载荷不合法` }
+            : { code: "protocol.unknown_type", message: "无法识别的请求" };
+        deps.logger.warn("拒绝非法请求", { id, type, code: error.code });
+        deps.reply(socket, id, { ok: false, error });
+        return;
+    }
+    try {
+        switch (request.type) {
+            case "send_message": {
+                deps.reply(socket, request.id, await deps.runtime.sendMessage(request.payload.text, request.payload.attachments, request.payload.mode, undefined, deps.clientId));
+                return;
+            }
+            case "interrupt":
+                deps.reply(socket, request.id, await deps.runtime.interrupt(request.payload.conversationId));
+                return;
+            case "refresh_actions":
+                deps.reply(socket, request.id, await deps.runtime.refreshActions(request.payload?.conversationId, request.payload?.count));
+                return;
+            case "set_engine":
+                // 零重启切引擎：项目 / 模型 / 能力都跟着新引擎走（engine-switch.ts）
+                deps.reply(socket, request.id, await deps.runtime.setEngine(request.payload.engine));
+                return;
+            case "approve":
+                deps.reply(socket, request.id, deps.runtime.approve(request.payload.requestId, request.payload.decision));
+                return;
+            case "new_chat":
+                deps.reply(socket, request.id, await deps.runtime.newConversation(request.payload?.workspace, deps.clientId));
+                return;
+            case "rename_session":
+                deps.reply(socket, request.id, await deps.runtime.renameSession(request.payload.conversationId, request.payload.title));
+                return;
+            case "switch_conversation":
+                deps.reply(socket, request.id, await deps.runtime.switchConversation(request.payload.conversationId, deps.clientId));
+                return;
+            case "list_providers":
+            case "upsert_provider":
+            case "delete_provider":
+            case "test_provider":
+            case "update_model":
+            case "remove_model":
+            case "set_enabled_models":
+                await deps.runProviderRequest(request, (result) => deps.reply(socket, request.id, result));
+                return;
+            case "set_approval_mode": {
+                deps.reply(socket, request.id, deps.runtime.setApprovalMode(request.payload.mode));
+                return;
+            }
+            case "cancel_queued":
+                deps.reply(socket, request.id, deps.runtime.cancelQueued(request.payload.queueId));
+                return;
+            case "set_thinking_level":
+                deps.reply(socket, request.id, await deps.runtime.setThinkingLevel(request.payload.level));
+                return;
+            case "set_model": {
+                deps.reply(socket, request.id, await deps.runtime.setModel(request.payload.modelId));
+                return;
+            }
+            case "set_settings": {
+                deps.reply(socket, request.id, await deps.runtime.applySettings(request.payload));
+                return;
+            }
+            case "get_state": {
+                // 重连/刷新后的第一件事：拉一份权威快照（ADR-0004 §3）；顺便刷一次 pi 会话列表（带 10s 下限）
+                await deps.runtime.refreshPiSessions();
+                await deps.runtime.refreshProviders();
+                // 必须按**这个客户端**生成：用全局快照会让重连的手机拿到电脑的会话
+                // （真实症状：电脑上切会话，手机跟着切 —— get_state 是每次重连都会调的）
+                deps.sender.pushSnapshot(deps.runtime.snapshotFor(deps.clientId));
+                deps.sender.flush(Date.now());
+                deps.reply(socket, request.id, { ok: true });
+                return;
+            }
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        deps.logger.error("处理请求失败", { type: request.type, message });
+        deps.reply(socket, request.id, { ok: false, error: { code: "protocol.handler_failed", message } });
+    }
+}