c0de-agent 1.12.0 → 1.13.0

package/dist/session/session.js

@@ -1,7 +1,8 @@
-import { and, eq, gt, ilike, inArray, isNull, lt, ne, notExists, or, sql } from 'drizzle-orm';
+import { and, eq, gt, ilike, inArray, isNull, lt, ne, notExists, notInArray, or, sql, } from 'drizzle-orm';
 import { alias } from 'drizzle-orm/pg-core';
 import { sessionEntries, sessions } from '../db/schema.js';
 import { generateId } from '../shared/index.js';
+import { getEntries } from './message.js';
 /** Convert a DB row (with Date timestamps) to the shared Session type (with number timestamps). */
 export function rowToSession(row) {
     const created = row.createdAt instanceof Date ? row.createdAt.getTime() : new Date(row.createdAt).getTime();
@@ -29,7 +30,11 @@ export function rowToSession(row) {
 /** Create a new root session. */
 async function createSession(handle, title, projectId, agentType, source, 
 /** P1 会话树治理：子 agent 会话挂到父会话（树内嵌套 + 删除级联）。 */
-parentId) {
+parentId, 
+/** 会话工作目录（CLI 会话必填：Web 打开时 agent 工具在该目录执行，而非 serve cwd）。 */
+worktreePath, 
+/** 初始 metadata（如工作流运行会话记录 workflowName，供中断恢复指引展示）。 */
+metadata) {
     const [row] = await handle.db
         .insert(sessions)
         .values({
@@ -38,23 +43,36 @@ parentId) {
         agentType: agentType ?? null,
         source: source ?? null,
         parentId: parentId ?? null,
+        worktreePath: worktreePath ?? null,
+        ...(metadata ? { metadata } : {}),
     })
         .returning();
     if (!row)
         throw new Error('Failed to insert session');
     return rowToSession(row);
 }
+/**
+ * Web 会话树可见性条件：web 会话（source 为 null/web）或「持久的 CLI 会话」。
+ * 一次性 CLI print 会话与 CLI 来源的 workflow 会话是临时数据，隐藏；
+ * Web 来源的 workflow 会话（source=null）在树中可见（标题带时间戳）。
+ * 两类临时会话到期后统一**移入回收站**（purgeTemporarySessions），不再物理清除——
+ * 可见节点（含其子 agent 会话）享有 60 天可恢复承诺。
+ * --continue 续接后 agentType 已清除（upgradeTemporarySession），即对 Web 可见。
+ */
+export function webVisibleSessionCondition() {
+    return or(isNull(sessions.source), ne(sessions.source, 'cli'), and(eq(sessions.source, 'cli'), or(isNull(sessions.agentType), notInArray(sessions.agentType, ['print', 'workflow']))));
+}
 /** Get a session by id, or null if not found. */
 async function getSession(handle, id) {
     const [row] = await handle.db.select().from(sessions).where(eq(sessions.id, id));
     return row ? rowToSession(row) : null;
 }
-/** List all active sessions (未软删除、非 CLI 来源；source 为 NULL 的旧数据视为 web). */
+/** List all active sessions（未软删除、Web 树可见：web 会话 + 持久化 CLI 会话）。 */
 async function listSessions(handle) {
     const rows = await handle.db
         .select()
         .from(sessions)
-        .where(and(isNull(sessions.deletedAt), or(isNull(sessions.source), ne(sessions.source, 'cli'))));
+        .where(and(isNull(sessions.deletedAt), webVisibleSessionCondition()));
     return rows.map(rowToSession);
 }
 /** 列出所有未软删除会话（含 CLI 来源；供 ACP/CLI 等非 Web 消费者使用）。 */
@@ -84,8 +102,11 @@ async function listOrphanDeletedSessions(handle) {
 }
 /**
  * 标记回收站条目「已被用户看到」，记录 metadata.trashSeenAt = now（仅首次，不重置）。
- * 回收站保留期自首次看到起算（见 purgeDeletedSessions）。软删除时会清除旧标记，
- * 恢复后再次删除须重新看到回收站才重新起算——避免「未重新看到就被过早清空」。
+ * 回收站保留期自首次看到起算（见 purgeDeletedSessions）。语义为分组粒度（M1）：
+ * 一次调用标记 scope 内全部条目——「首次看到」指用户打开该回收站分组，而非逐条
+ * 浏览到某个条目；分组内条目同时起算，列表按到期先后置顶展示以补偿该粒度。
+ * 软删除时会清除旧标记，恢复后再次删除须重新看到回收站才重新起算——
+ * 避免「未重新看到就被过早清空」。
  * scope.orphan=true 时仅标记未归属项目的孤儿会话（与 listOrphanDeletedSessions 对齐）；
  * 孤儿标记仅在用户展开「未归属项目」分组时由前端显式调用（POST /deleted/orphans/seen），
  * 避免打开任意项目回收站连带启动无关孤儿条目的倒计时。
@@ -276,6 +297,12 @@ async function restoreSession(handle, id, opts = {}) {
  * 仍为 30 天，见 purgeTemporarySessions。
  */
 export const TRASH_RETENTION_MS = 60 * 24 * 60 * 60 * 1000;
+/**
+ * 绝对上限（365 天）：自删除起超过此时长的条目，无论是否被看到都进入宽限期清理。
+ * 兜底「用户从不开回收站 → trashSeenAt 永不写入 → 条目永不清理」的无界增长死角。
+ * 到期仍走先标记（宽限 7 天、UI 显示「即将清除」可恢复）再物理清除的两阶段流程。
+ */
+export const TRASH_ABSOLUTE_MAX_MS = 365 * 24 * 60 * 60 * 1000;
 /**
  * A3：到期标记 → 物理清除的宽限期（默认 7 天）。
  * 条目到期后先写 metadata.purgePendingAt，UI 显示「即将清除」并可恢复；
@@ -284,13 +311,15 @@ export const TRASH_RETENTION_MS = 60 * 24 * 60 * 60 * 1000;
 export const TRASH_PURGE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
 /**
  * 回收站两阶段清理（启动时与每日定时调用）：
- * 阶段一：trashSeenAt 超过保留期且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
+ * 阶段一：进入保留期截止（首次看到 + 60 天）或绝对上限（删除 + 365 天，无论是否
+ *   被看到）且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
  * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求）。
- * 未被看到过（trashSeenAt 缺失）或恢复后重删、尚未重新看到的会话永不进入任一阶段。
+ * 恢复后重删、尚未重新看到的会话按「首次看到 + 60 天」计（绝对上限兜底仍生效）。
  */
 async function purgeDeletedSessions(handle, retentionMs = TRASH_RETENTION_MS, graceMs = TRASH_PURGE_GRACE_MS) {
     const retentionCutoff = Date.now() - retentionMs;
     const graceCutoff = Date.now() - graceMs;
+    const absoluteCutoff = Date.now() - TRASH_ABSOLUTE_MAX_MS;
     const rows = await handle.db
         .select({
         id: sessions.id,
@@ -308,8 +337,11 @@ async function purgeDeletedSessions(handle, retentionMs = TRASH_RETENTION_MS, gr
         const meta = (r.metadata ?? {});
         const seen = meta.trashSeenAt;
         const deletedMs = r.deletedAt.getTime();
-        // 保留期自「首次看到」起算：seen 缺失或早于最近一次删除 → 未重新看到，不标记。
-        if (typeof seen !== 'number' || seen <= deletedMs || seen >= retentionCutoff)
+        // 保留期自「首次看到」起算：seen 缺失或早于最近一次删除 → 未重新看到，不计。
+        const seenExpired = typeof seen === 'number' && seen > deletedMs && seen < retentionCutoff;
+        // 绝对上限兜底：删除后长期未被看到也进入宽限期，防条目永不清理的无界增长。
+        const absoluteExpired = deletedMs < absoluteCutoff;
+        if (!seenExpired && !absoluteExpired)
             continue;
         if (typeof meta.purgePendingAt === 'number')
             continue;
@@ -380,6 +412,36 @@ async function purgeEmptySessions(handle, retentionMs = EMPTY_SESSION_RETENTION_
 async function updateSessionTitle(handle, id, title) {
     await handle.db.update(sessions).set({ title, updatedAt: new Date() }).where(eq(sessions.id, id));
 }
+/**
+ * P3-9：物理删除一个「真空会话」——无任何条目且无子会话（首条消息发送失败后
+ * 的前端清理路径使用）。非空会话绝不触碰（返回 false），防误删走错回收站语义。
+ * 软删除会话（回收站条目）不在本路径处理。
+ */
+async function purgeEmptySession(handle, id) {
+    const [row] = await handle.db
+        .select({ id: sessions.id, deletedAt: sessions.deletedAt })
+        .from(sessions)
+        .where(eq(sessions.id, id));
+    if (!row || row.deletedAt)
+        return false;
+    const children = alias(sessions, 'purge_children');
+    const [entry] = await handle.db
+        .select({ one: sql `1` })
+        .from(sessionEntries)
+        .where(eq(sessionEntries.sessionId, id))
+        .limit(1);
+    if (entry)
+        return false;
+    const [child] = await handle.db
+        .select({ one: sql `1` })
+        .from(children)
+        .where(eq(children.parentId, id))
+        .limit(1);
+    if (child)
+        return false;
+    await handle.db.delete(sessions).where(eq(sessions.id, id));
+    return true;
+}
 /**
  * 彻底删除某个回收站会话及其全部后代（含未软删除的 fork 后代，防御数据异常）。
  * 子会话先于父会话删除（自引用 FK RESTRICT 要求）；entries/archives 经 FK cascade 清理。
@@ -466,70 +528,36 @@ async function emptyTrash(handle, projectId) {
     return deleted;
 }
 /**
- * 清理过期临时会话（P2 → P1 收紧：仅清理显式标记的临时会话）。
+ * 清理过期临时会话（P2 → P1 收紧：仅处理显式标记的临时会话）。
  * - agentType='print'：CLI 一次性问答（c0de chat，非 --continue）创建的会话。
  * - agentType='workflow'：工作流运行产生的会话。
  * 普通 CLI 会话（ACP）与 --continue 续接的会话（续接时已升级）永不清理——
  * 此前按 source='cli' 全删会把用户显式续接的历史静默物理删除。
- * 保留期默认 30 天；子条目经 FK cascade 一并删除。
- * 返回清除数量。启动时与每日定时调用。
+ * 保留期默认 30 天。
+ *
+ * P1（本轮）：清理方式从物理删除改为**移入回收站**（softDeleteSession）——
+ * 工作流/print 会话的子 agent 会话在 Web 树中可见，此前「30 天到点即物理清除」
+ * 让可见节点无回收站保护地凭空消失，与「60 天可恢复」的产品承诺冲突。
+ * 软删除级联同批次后代；随后由 purgeDeletedSessions 的两阶段回收站机制
+ * （trashSeenAt 60 天 / 绝对上限 365 天 + 7 天宽限）统一兜底。
+ * 返回本次移入回收站的会话数。
  */
 async function purgeTemporarySessions(handle, retentionMs = 30 * 24 * 60 * 60 * 1000) {
     const cutoff = new Date(Date.now() - retentionMs);
-    const all = await handle.db
-        .select({
-        id: sessions.id,
-        parentId: sessions.parentId,
-        agentType: sessions.agentType,
-        updatedAt: sessions.updatedAt,
-    })
-        .from(sessions);
-    const roots = all.filter((r) => (r.agentType === 'print' || r.agentType === 'workflow') &&
+    const rows = await handle.db
+        .select({ id: sessions.id, agentType: sessions.agentType, updatedAt: sessions.updatedAt })
+        .from(sessions)
+        .where(isNull(sessions.deletedAt));
+    const roots = rows.filter((r) => (r.agentType === 'print' || r.agentType === 'workflow') &&
         r.updatedAt != null &&
         r.updatedAt.getTime() < cutoff.getTime());
-    if (roots.length === 0)
-        return 0;
-    // 临时会话可能派发过子 agent（其子会话挂 parentId）。父会话直接删除会撞自引用
-    // FK（RESTRICT），且子会话失去父后成为游离节点——故连同全部后代一起物理清除，
-    // 并按拓扑序「子先于父」删除（与 emptyTrash / purgeDeletedSessions 同一策略）。
-    const childrenOf = new Map();
-    for (const r of all) {
-        if (r.parentId) {
-            const list = childrenOf.get(r.parentId) ?? [];
-            list.push(r.id);
-            childrenOf.set(r.parentId, list);
-        }
-    }
-    const ids = new Set();
-    const collect = (sid) => {
-        if (ids.has(sid))
-            return;
-        ids.add(sid);
-        for (const c of childrenOf.get(sid) ?? [])
-            collect(c);
-    };
-    for (const r of roots)
-        collect(r.id);
-    const remaining = new Set(ids);
-    let deleted = 0;
-    while (remaining.size > 0) {
-        const leaves = Array.from(remaining).filter((sid) => !(childrenOf.get(sid) ?? []).some((c) => remaining.has(c)));
-        if (leaves.length === 0) {
-            // 循环引用兜底：强制逐个删除（数据异常场景）
-            for (const sid of Array.from(remaining)) {
-                await handle.db.delete(sessions).where(eq(sessions.id, sid));
-                remaining.delete(sid);
-                deleted += 1;
-            }
-            break;
-        }
-        for (const sid of leaves) {
-            await handle.db.delete(sessions).where(eq(sessions.id, sid));
-            remaining.delete(sid);
-            deleted += 1;
-        }
+    let trashed = 0;
+    for (const r of roots) {
+        // softDeleteSession 级联标记其后代（同 deletedBatchId），恢复父即恢复子树。
+        if (await softDeleteSession(handle, r.id))
+            trashed += 1;
     }
-    return deleted;
+    return trashed;
 }
 /**
  * 把临时会话升级为持久会话（--continue 续接时调用）：
@@ -640,11 +668,48 @@ async function updateSessionLastRun(handle, id, lastRun) {
         .set({ metadata: { ...meta, lastRun }, updatedAt: new Date() })
         .where(eq(sessions.id, id));
 }
+/**
+ * P2-3：预算超支暂停时把原因写入 metadata.budgetPauseReason。
+ * 热更新/重启后 run 重建时由 consumeBudgetPauseMarker 消费——恢复内存
+ * budgetPauseTriggered 标记，避免同一超支原因二次暂停。
+ */
+async function markBudgetPause(handle, id, reason) {
+    const [row] = await handle.db.select().from(sessions).where(eq(sessions.id, id));
+    if (!row)
+        return;
+    const meta = (row.metadata ?? {});
+    await handle.db
+        .update(sessions)
+        .set({ metadata: { ...meta, budgetPauseReason: reason }, updatedAt: new Date() })
+        .where(eq(sessions.id, id));
+}
+/**
+ * P2-3：消费预算暂停标记（新 run 启动时调用一次）。返回上次暂停原因并删除字段；
+ * 无标记返回 null。消费即删除——单次语义，之后 run 恢复常规预算检查。
+ */
+async function consumeBudgetPauseMarker(handle, id) {
+    const [row] = await handle.db
+        .select({ metadata: sessions.metadata })
+        .from(sessions)
+        .where(eq(sessions.id, id));
+    if (!row)
+        return null;
+    const meta = (row.metadata ?? {});
+    const reason = typeof meta.budgetPauseReason === 'string' ? meta.budgetPauseReason : null;
+    if (reason === null)
+        return null;
+    const { budgetPauseReason: _omit, ...rest } = meta;
+    await handle.db
+        .update(sessions)
+        .set({ metadata: rest, updatedAt: new Date() })
+        .where(eq(sessions.id, id));
+    return reason;
+}
 async function listSessionsByProject(handle, projectId) {
     const rows = await handle.db
         .select()
         .from(sessions)
-        .where(and(eq(sessions.projectId, projectId), isNull(sessions.deletedAt), or(isNull(sessions.source), ne(sessions.source, 'cli'))));
+        .where(and(eq(sessions.projectId, projectId), isNull(sessions.deletedAt), webVisibleSessionCondition()));
     return rows.map(rowToSession);
 }
 /**
@@ -660,7 +725,7 @@ async function searchSessions(handle, query, projectId, opts = {}) {
     const pattern = `%${needle.replace(/[%_\\]/g, '\\$&')}%`;
     const baseWhere = and(opts.includeDeleted ? gt(sessions.deletedAt, new Date(0)) : isNull(sessions.deletedAt), 
     // 回收站搜索与回收站列表（listDeletedSessions）一致：不过滤 source。
-    ...(opts.includeDeleted ? [] : [or(isNull(sessions.source), ne(sessions.source, 'cli'))]), ...(projectId ? [eq(sessions.projectId, projectId)] : []));
+    ...(opts.includeDeleted ? [] : [webVisibleSessionCondition()]), ...(projectId ? [eq(sessions.projectId, projectId)] : []));
     // 标题命中（ILIKE 转义后按字面子串）
     const byTitle = await handle.db
         .select()
@@ -702,4 +767,52 @@ async function searchSessions(handle, query, projectId, opts = {}) {
     }
     return result;
 }
-export { clearTrashMarks, createSession, emptyTrash, getSession, listAllSessions, listDeletedSessions, listOrphanDeletedSessions, listSessions, listSessionsByProject, permanentlyDeleteSession, purgeDeletedSessions, purgeEmptySessions, purgeTemporarySessions, rebindSession, restoreSession, restoreSessionCore, searchSessions, softDeleteSession, touchLastOpened, touchSession, touchTrashSeen, updateSessionLastRun, updateSessionTitle, upgradeTemporarySession, };
+/**
+ * M3：把中断 run 的半截轮次标记为「未完成」——写入 metadata 的
+ * (unfinishedSinceEntryId, unfinishedUntilEntryId] 区间。
+ * 检测条件：lastRun.status 仍为 running/paused（进程崩溃/重启或热更新交接
+ * 未能写入 completed；deliberate abort 由 SSE finally 正常写 completed，不误标）。
+ * 边界 = 最后一条含文本的 user 消息；其后的条目全部属中断轮次——
+ * 上下文构建剔除（context.ts），前端时间线置灰。
+ * 边界已是最后一条 → 无半截内容，跳过标记。
+ * 重复中断：区间起点不变（重发不追加 user 消息），终点推进到最新末尾，天然合并。
+ */
+async function markUnfinishedTurn(handle, sessionId) {
+    const [row] = await handle.db
+        .select({ metadata: sessions.metadata })
+        .from(sessions)
+        .where(eq(sessions.id, sessionId));
+    if (!row)
+        return;
+    const meta = (row.metadata ?? {});
+    const status = meta.lastRun?.status;
+    if (status !== 'running' && status !== 'paused')
+        return;
+    const entries = await getEntries(handle, sessionId);
+    let lastUserIdx = -1;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        // P1-2：边界取「含任意内容（text 或 image）的 user 消息」——此前仅认 text，
+        // 纯图片消息不在边界判定内，中断轮次起点会错误回退到更早的文本消息。
+        if (e &&
+            !('_tag' in e) &&
+            e.role === 'user' &&
+            e.content.some((p) => p._tag === 'text' || p._tag === 'image')) {
+            lastUserIdx = i;
+            break;
+        }
+    }
+    if (lastUserIdx < 0 || lastUserIdx === entries.length - 1)
+        return;
+    const sinceId = entries[lastUserIdx]?.id;
+    const untilId = entries[entries.length - 1]?.id;
+    if (!sinceId || !untilId)
+        return;
+    await handle.db
+        .update(sessions)
+        .set({
+        metadata: { ...meta, unfinishedSinceEntryId: sinceId, unfinishedUntilEntryId: untilId },
+    })
+        .where(eq(sessions.id, sessionId));
+}
+export { clearTrashMarks, consumeBudgetPauseMarker, createSession, emptyTrash, getSession, listAllSessions, listDeletedSessions, listOrphanDeletedSessions, listSessions, listSessionsByProject, markBudgetPause, markUnfinishedTurn, permanentlyDeleteSession, purgeDeletedSessions, purgeEmptySession, purgeEmptySessions, purgeTemporarySessions, rebindSession, restoreSession, restoreSessionCore, searchSessions, softDeleteSession, touchLastOpened, touchSession, touchTrashSeen, updateSessionLastRun, updateSessionTitle, upgradeTemporarySession, };

package/dist/session/types.d.ts

@@ -98,6 +98,8 @@ type SessionUsage = {
     outputTokens: number;
     cacheRead: number;
     cost: number;
+    /** 价格未知（cost=null）的调用数：成本按 $0 计入，UI 需提示低估。 */
+    unknownCostCalls: number;
     calls: number;
 };
 /** A node in the session tree. */

package/dist/session/usage.d.ts

@@ -0,0 +1,62 @@
+import type { DB } from '../db/client.js';
+import type { UsageConfig } from '../shared/types/config.js';
+/**
+ * 把 sessions.metadata.segments 中全部调用补齐进 usage_events（幂等）。
+ * 覆盖：升级前历史数据、fork 复制的 segments（display 用途）、导入会话携带的
+ * segments。callId 冲突（已入账）静默跳过。
+ * 返回本次新增行数。
+ */
+export declare function backfillUsageEvents(handle: DB): Promise<number>;
+/** 当月用量汇总（金额 + token），预算护栏判定用。
+ *  cost：已发生成本——价格未知（cost=null）的调用按 $0 计入，故金额口径对自建
+ *  网关/未登记模型会系统性低估；tokens：input+output+cacheRead tokens 之和，
+ *  与价格无关，作为价格独立的兜底口径（缓存读取也按用量计费，须计入）。
+ *  unknownCostCalls：当月价格未知的调用数——金额预算轴据此识别「口径低估」，
+ *  无 token 预算兜底时并入护栏告警文案（P2-2：预算静默失效不再无提示）。
+ */
+export declare function monthUsage(handle: DB, opts: {
+    projectId?: string | null;
+    sinceMs: number;
+}): Promise<{
+    cost: number;
+    tokens: number;
+    unknownCostCalls: number;
+}>;
+/** 当月累计用量（本月 1 日 00:00 本地时区起算）。
+ *  已知限制：跨时区/换机时「本月」边界随本地时区漂移，成本护栏阈值随之平移——
+ *  本地单机（服务端与用户同机）场景无影响。 */
+export declare function currentMonthUsage(handle: DB, projectId?: string | null, now?: Date): Promise<{
+    cost: number;
+    tokens: number;
+    unknownCostCalls: number;
+}>;
+/** 预算护栏判定结果：parts 为超支描述片段，action 为实际超支轴中最严格的动作
+ *  （'abort' > 'pause'；'warn' 不阻断、不会进入本判定）。
+ *  warnings：非阻断的告警片段（P2-2）——金额轴启用但当月存在价格未知调用且
+ *  无 token 预算兜底时，「金额口径低估」不再静默；消费方并入暂停/中止文案。 */
+export type BudgetOverage = {
+    parts: string[];
+    action: 'pause' | 'abort';
+    warnings: string[];
+};
+/** 预算护栏判定：金额（USD）+ token 双口径，返回超支描述 + 阻断动作（空 parts =
+ *  无需阻断——可能超支但动作仅 warn）。
+ *  金额口径受 budgetAction 控制；token 口径受 tokenBudgetAction 控制（缺省回退
+ *  budgetAction，向后兼容）。warn 动作只走前端徽标/面板告警，不进本判定。
+ *  供 Web loop 暂停/中止、CLI 拒绝、子 agent 提前中止共用。
+ *  项目口径仅在 projectId 可归属时检查（未归属会话只受全局口径兜底）。
+ *  token 口径独立于价格，兜底自建网关/未登记模型（cost 恒 $0）的场景。
+ *  P1：金额/token 两轴动作各自求值，多轴同时超支取更严格者（abort > pause），
+ *  不再被单一布尔预算标志坍缩降级。 */
+export declare function budgetOverageParts(handle: DB, usage: UsageConfig, projectId: string | null | undefined, now?: Date): Promise<BudgetOverage>;
+/** 本地时区的 YYYY-MM 月份键（与 usage 聚合、前端徽标同口径）。 */
+export declare function localMonthKey(ts: number): string;
+/** 一次性 backfill 标记键（app_meta）。 */
+export declare const USAGE_BACKFILL_MARKER = "usage_backfill_v1";
+/**
+ * P3-8：backfill 只在「升级后的首次启动」执行一次，之后跳过——
+ * backfill 的真实消费者只有升级前遗留 segments（fork 复制的 segments 经 callId
+ * 唯一约束去重本就是 no-op；导入会话的 segments 已剥离 call id 不产生账本行），
+ * 每次启动全表扫描是纯浪费。标记写入与 backfill 同事务，失败不落标记可重试。
+ */
+export declare function backfillUsageEventsOnce(handle: DB): Promise<number>;

package/dist/session/usage.js

@@ -0,0 +1,194 @@
+// src/session/usage.ts
+// 成本账本工具：usage_events 的 backfill 与月度成本查询。
+//
+// usage_events（append-only，与 session 生命周期解耦）是成本聚合的权威数据源。
+// 会话物理清除（回收站到期/彻底删除/临时会话清理）不触及它——成本是账本。
+// 写路径在 loop manageSegment（每个 LLM 调用落一行）；本模块负责两条辅助路径：
+//  1. backfillUsageEvents：把 sessions.metadata.segments 中已有调用补齐进账本
+//     （升级前产生的历史数据 + fork 复制的 segments + 导入的会话）。
+//     幂等：callId 唯一约束 + onConflictDoNothing，可安全重复执行。
+//  2. budgetOverageParts：预算暂停/拒绝（usage.budgetAction='pause'）用的当月
+//     金额 + token 双口径超支判定（token 兜底价格未知的自建网关/未登记模型）。
+import { and, eq, gte } from 'drizzle-orm';
+import { appMeta, sessions, usageEvents } from '../db/schema.js';
+/**
+ * 把 sessions.metadata.segments 中全部调用补齐进 usage_events（幂等）。
+ * 覆盖：升级前历史数据、fork 复制的 segments（display 用途）、导入会话携带的
+ * segments。callId 冲突（已入账）静默跳过。
+ * 返回本次新增行数。
+ */
+export async function backfillUsageEvents(handle) {
+    const rows = await handle.db
+        .select({ id: sessions.id, projectId: sessions.projectId, metadata: sessions.metadata })
+        .from(sessions);
+    let added = 0;
+    for (const row of rows) {
+        const meta = (row.metadata ?? {});
+        for (const seg of meta.segments ?? []) {
+            if (typeof seg.provider !== 'string' || typeof seg.model !== 'string')
+                continue;
+            for (const call of seg.calls ?? []) {
+                if (typeof call.id !== 'string' || call.id.length === 0)
+                    continue;
+                const ts = typeof call.timestamp === 'number' && call.timestamp > 0 ? call.timestamp : 0;
+                if (ts === 0)
+                    continue;
+                const input = typeof call.usage?.input === 'number' ? call.usage.input : 0;
+                const output = typeof call.usage?.output === 'number' ? call.usage.output : 0;
+                const cacheRead = typeof call.usage?.cacheRead === 'number' ? call.usage.cacheRead : 0;
+                const cost = typeof call.cost === 'number' ? call.cost : null;
+                const result = await handle.db
+                    .insert(usageEvents)
+                    .values({
+                    callId: call.id,
+                    sessionId: row.id,
+                    projectId: row.projectId,
+                    provider: seg.provider,
+                    model: seg.model,
+                    inputTokens: input,
+                    outputTokens: output,
+                    cacheRead,
+                    cost,
+                    timestamp: ts,
+                })
+                    .onConflictDoNothing();
+                if (result.rowCount && result.rowCount > 0)
+                    added += result.rowCount;
+            }
+        }
+    }
+    return added;
+}
+/** 当月用量汇总（金额 + token），预算护栏判定用。
+ *  cost：已发生成本——价格未知（cost=null）的调用按 $0 计入，故金额口径对自建
+ *  网关/未登记模型会系统性低估；tokens：input+output+cacheRead tokens 之和，
+ *  与价格无关，作为价格独立的兜底口径（缓存读取也按用量计费，须计入）。
+ *  unknownCostCalls：当月价格未知的调用数——金额预算轴据此识别「口径低估」，
+ *  无 token 预算兜底时并入护栏告警文案（P2-2：预算静默失效不再无提示）。
+ */
+export async function monthUsage(handle, opts) {
+    const conds = [gte(usageEvents.timestamp, opts.sinceMs)];
+    if (opts.projectId)
+        conds.push(eq(usageEvents.projectId, opts.projectId));
+    const rows = await handle.db
+        .select({
+        cost: usageEvents.cost,
+        inputTokens: usageEvents.inputTokens,
+        outputTokens: usageEvents.outputTokens,
+        cacheRead: usageEvents.cacheRead,
+    })
+        .from(usageEvents)
+        .where(and(...conds));
+    let cost = 0;
+    let tokens = 0;
+    let unknownCostCalls = 0;
+    for (const r of rows) {
+        if (typeof r.cost === 'number')
+            cost += r.cost;
+        else
+            unknownCostCalls += 1;
+        tokens += r.inputTokens + r.outputTokens + (r.cacheRead ?? 0);
+    }
+    return { cost, tokens, unknownCostCalls };
+}
+/** 当月累计用量（本月 1 日 00:00 本地时区起算）。
+ *  已知限制：跨时区/换机时「本月」边界随本地时区漂移，成本护栏阈值随之平移——
+ *  本地单机（服务端与用户同机）场景无影响。 */
+export async function currentMonthUsage(handle, projectId, now = new Date()) {
+    const monthStart = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+    return monthUsage(handle, { projectId, sinceMs: monthStart });
+}
+/** 预算护栏判定：金额（USD）+ token 双口径，返回超支描述 + 阻断动作（空 parts =
+ *  无需阻断——可能超支但动作仅 warn）。
+ *  金额口径受 budgetAction 控制；token 口径受 tokenBudgetAction 控制（缺省回退
+ *  budgetAction，向后兼容）。warn 动作只走前端徽标/面板告警，不进本判定。
+ *  供 Web loop 暂停/中止、CLI 拒绝、子 agent 提前中止共用。
+ *  项目口径仅在 projectId 可归属时检查（未归属会话只受全局口径兜底）。
+ *  token 口径独立于价格，兜底自建网关/未登记模型（cost 恒 $0）的场景。
+ *  P1：金额/token 两轴动作各自求值，多轴同时超支取更严格者（abort > pause），
+ *  不再被单一布尔预算标志坍缩降级。 */
+export async function budgetOverageParts(handle, usage, projectId, now = new Date()) {
+    const projectBudgetUsd = usage.monthlyBudgetUsd ?? 0;
+    const globalBudgetUsd = usage.globalMonthlyBudgetUsd ?? 0;
+    const projectTokenBudget = usage.monthlyTokenBudget ?? 0;
+    const globalTokenBudget = usage.globalMonthlyTokenBudget ?? 0;
+    const amountAction = usage.budgetAction ?? 'warn';
+    const tokenAction = usage.tokenBudgetAction ?? amountAction;
+    // P0-3：'pause' 与 'abort' 都是阻断动作（均需 loop 放行前检查）；'warn' 不阻断。
+    const amountBlocks = amountAction === 'pause' || amountAction === 'abort';
+    const tokenBlocks = tokenAction === 'pause' || tokenAction === 'abort';
+    const projectScoped = projectId != null && (projectBudgetUsd > 0 || projectTokenBudget > 0);
+    const globalScoped = globalBudgetUsd > 0 || globalTokenBudget > 0;
+    if (!projectScoped && !globalScoped)
+        return { parts: [], action: 'pause', warnings: [] };
+    const [project, global] = await Promise.all([
+        projectScoped ? currentMonthUsage(handle, projectId, now) : Promise.resolve(null),
+        globalScoped ? currentMonthUsage(handle, undefined, now) : Promise.resolve(null),
+    ]);
+    // P2-2：金额轴阻断启用但价格未知调用无 token 兜底 → 「金额口径低估」告警。
+    // 仅当对应范围未设置 token 预算（token 兜底缺失）且当月确有 cost=null 调用时
+    // 追加——warnings 不触发阻断，只并入暂停/中止文案让用户知道护栏口径不可靠。
+    const warnings = [];
+    const amountAxisActive = amountBlocks && (globalBudgetUsd > 0 || (projectBudgetUsd > 0 && projectId != null));
+    if (amountAxisActive) {
+        const globalUnknown = global?.unknownCostCalls ?? 0;
+        if (globalBudgetUsd > 0 && globalTokenBudget <= 0 && globalUnknown > 0) {
+            warnings.push(`金额口径低估：本月有 ${globalUnknown} 次调用价格未知（按 $0 计入），且未设置全局 token 预算兜底`);
+        }
+        const projectUnknown = project?.unknownCostCalls ?? 0;
+        if (projectBudgetUsd > 0 &&
+            projectTokenBudget <= 0 &&
+            projectId != null &&
+            projectUnknown > 0) {
+            warnings.push(`金额口径低估：本项目有 ${projectUnknown} 次调用价格未知（按 $0 计入），且未设置项目 token 预算兜底`);
+        }
+    }
+    const parts = [];
+    // 实际超支轴中的最严格阻断动作：任一超支轴动作 === 'abort' 即整体 abort，否则 pause。
+    let action = 'pause';
+    if (amountBlocks && globalBudgetUsd > 0 && global && global.cost > globalBudgetUsd) {
+        parts.push(`全局预算 $${globalBudgetUsd.toFixed(2)}：本月全部项目已 $${global.cost.toFixed(2)}`);
+        if (amountAction === 'abort')
+            action = 'abort';
+    }
+    if (amountBlocks && projectBudgetUsd > 0 && project && project.cost > projectBudgetUsd) {
+        parts.push(`项目预算 $${projectBudgetUsd.toFixed(2)}：本项目已 $${project.cost.toFixed(2)}`);
+        if (amountAction === 'abort')
+            action = 'abort';
+    }
+    if (tokenBlocks && globalTokenBudget > 0 && global && global.tokens > globalTokenBudget) {
+        parts.push(`全局 token 预算 ${globalTokenBudget.toLocaleString()}：本月已 ${global.tokens.toLocaleString()} tokens`);
+        if (tokenAction === 'abort')
+            action = 'abort';
+    }
+    if (tokenBlocks && projectTokenBudget > 0 && project && project.tokens > projectTokenBudget) {
+        parts.push(`项目 token 预算 ${projectTokenBudget.toLocaleString()}：本项目已 ${project.tokens.toLocaleString()} tokens`);
+        if (tokenAction === 'abort')
+            action = 'abort';
+    }
+    return { parts, action, warnings };
+}
+/** 本地时区的 YYYY-MM 月份键（与 usage 聚合、前端徽标同口径）。 */
+export function localMonthKey(ts) {
+    const d = new Date(ts);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+/** 一次性 backfill 标记键（app_meta）。 */
+export const USAGE_BACKFILL_MARKER = 'usage_backfill_v1';
+/**
+ * P3-8：backfill 只在「升级后的首次启动」执行一次，之后跳过——
+ * backfill 的真实消费者只有升级前遗留 segments（fork 复制的 segments 经 callId
+ * 唯一约束去重本就是 no-op；导入会话的 segments 已剥离 call id 不产生账本行），
+ * 每次启动全表扫描是纯浪费。标记写入与 backfill 同事务，失败不落标记可重试。
+ */
+export async function backfillUsageEventsOnce(handle) {
+    const [marker] = await handle.db
+        .select()
+        .from(appMeta)
+        .where(eq(appMeta.key, USAGE_BACKFILL_MARKER));
+    if (marker)
+        return 0;
+    const added = await backfillUsageEvents(handle);
+    await handle.db.insert(appMeta).values({ key: USAGE_BACKFILL_MARKER, value: String(Date.now()) });
+    return added;
+}