c0de-agent 1.11.0 → 1.13.0

package/dist/kanban/store.js

@@ -1,10 +1,53 @@
-import { and, asc, eq, max } from 'drizzle-orm';
+import { and, asc, eq, inArray, isNotNull, isNull, max, sql } from 'drizzle-orm';
 import { kanbanBoards, kanbanCards } from '../db/schema.js';
 import { DEFAULT_KANBAN_COLUMNS } from '../shared/types/kanban.js';
 /** Default column when none is specified. */
 const DEFAULT_COLUMN_ID = 'todo';
 /** Position increment — large gap avoids frequent re-indexing on reorder. */
 const POSITION_GAP = 1000;
+/** 合法优先级枚举（运行时校验用——REST/tool 层输入未经 TS 约束）。 */
+const VALID_PRIORITIES = new Set(['high', 'medium', 'low']);
+/** 列内仍有卡片时禁止删除该列（否则卡片静默不可见）。 */
+class KanbanColumnInUseError extends Error {
+    constructor(columnNames, cardCount, cardIds = []) {
+        const idHint = cardIds.length > 0
+            ? `（示例卡片 id：${cardIds.slice(0, 5).join('、')}${cardIds.length > 5 ? ' 等' : ''}，可直接按 id 删除这些卡片）`
+            : '';
+        super(`列 [${columnNames.join(', ')}] 中仍有 ${cardCount} 张卡片，无法删除。` +
+            `请先移动或删除这些卡片。${idHint}`);
+    }
+}
+/**
+ * 目标列不存在（add/move 引用未配置的列）——与 import/删列的悬空列防护同口径：
+ * 此前运行时 add/move 不校验，LLM 幻觉列名写入后卡片静默不可见，且幽灵卡片
+ * 会反过来冻结列配置删除（KanbanColumnInUseError 死锁）。
+ * 错误信息回传可用列清单，供 LLM 自纠而非再猜。
+ */
+class KanbanColumnNotFoundError extends Error {
+    columnId;
+    constructor(columnId, availableColumns, op) {
+        const avail = availableColumns.length > 0 ? availableColumns.join('、') : '（看板无列）';
+        super(`列 "${columnId}" 不存在，无法${op === 'add' ? '创建' : '移动'}卡片。` +
+            `可用列：${avail}。请改用其中一个列 id。`);
+        this.columnId = columnId;
+    }
+}
+/** 非法优先级（REST PATCH / kanbanTool 透传未校验值）。 */
+class KanbanInvalidPriorityError extends Error {
+    value;
+    constructor(value) {
+        super(`无效优先级 "${value}"，允许值：high、medium、low`);
+        this.value = value;
+    }
+}
+/** 卡片不存在（update/move 目标 id 无效）。 */
+class KanbanCardNotFoundError extends Error {
+    cardId;
+    constructor(cardId) {
+        super(`Kanban card not found: ${cardId}`);
+        this.cardId = cardId;
+    }
+}
 // ── Row → API mappers ──────────────────────────────────────
 function rowToBoard(row) {
     return {
@@ -50,9 +93,14 @@ function createKanbanStore(handle, projectId) {
         const [row] = await db
             .select({ id: kanbanBoards.id })
             .from(kanbanBoards)
-            .where(eq(kanbanBoards.projectId, projectId))
+            .where(and(eq(kanbanBoards.projectId, projectId), isNull(kanbanBoards.deletedAt)))
             .limit(1);
-        // 行一定存在：上面 insert + onConflictDoNothing 保证了 projectId 对应的行已创建
+        // 正常路径行一定存在（insert + onConflictDoNothing 已保证）。防御性兜底：
+        // 唯一 projectId 槽位被软删行占用等异常态下不再返回 undefined id
+        //（后续查询会静默查空、上层误判「板不存在」），显式抛错暴露问题。
+        if (!row) {
+            throw new Error(`Kanban board for project ${projectId} missing after ensure-insert (unique slot likely held by a soft-deleted row)`);
+        }
         return row.id;
     }
     /** Max position in a column (0 if empty). */
@@ -63,7 +111,45 @@ function createKanbanStore(handle, projectId) {
             .where(and(eq(kanbanCards.boardId, boardId), eq(kanbanCards.columnId, columnId)));
         return row?.m ?? 0;
     }
+    /** 当前板的列配置（add/move 的悬空列校验用）。 */
+    async function boardColumns(boardId) {
+        const [row] = await db
+            .select({ columns: kanbanBoards.columns })
+            .from(kanbanBoards)
+            .where(eq(kanbanBoards.id, boardId))
+            .limit(1);
+        return (row?.columns ?? []);
+    }
+    /** 校验列存在；不存在抛 KanbanColumnNotFoundError（消息含可用列清单）。 */
+    function assertColumn(columns, columnId, op) {
+        if (!columns.some((c) => c.id === columnId)) {
+            throw new KanbanColumnNotFoundError(columnId, columns.map((c) => c.id), op);
+        }
+    }
+    /** 校验优先级合法；非法抛 KanbanInvalidPriorityError。 */
+    function assertPriority(priority) {
+        if (priority !== undefined && !VALID_PRIORITIES.has(priority)) {
+            throw new KanbanInvalidPriorityError(String(priority));
+        }
+    }
     return {
+        /** 只读获取板（不创建）：导出等纯读路径用——此前导出经 getBoard 懒建板，
+         *  「导出」一个从未打开过看板的项目会凭空产生空板行。无板返回 null。 */
+        async peekBoard() {
+            const [boardRow] = await db
+                .select()
+                .from(kanbanBoards)
+                .where(and(eq(kanbanBoards.projectId, projectId), isNull(kanbanBoards.deletedAt)))
+                .limit(1);
+            if (!boardRow)
+                return null;
+            const cards = await db
+                .select()
+                .from(kanbanCards)
+                .where(eq(kanbanCards.boardId, boardRow.id))
+                .orderBy(asc(kanbanCards.columnId), asc(kanbanCards.position));
+            return { ...rowToBoard(boardRow), cards: cards.map(rowToCard) };
+        },
         async getBoard() {
             const boardId = await getOrCreateBoardId();
             const [boardRow] = await db
@@ -81,7 +167,12 @@ function createKanbanStore(handle, projectId) {
         },
         async addCard(input) {
             const boardId = await getOrCreateBoardId();
-            const columnId = input.columnId ?? DEFAULT_COLUMN_ID;
+            const columns = await boardColumns(boardId);
+            // 默认列 = 板上第一列（而非硬编码 'todo'）：todo 列被删除/重排后
+            // 硬编码默认会让无参 addCard 静默落入不存在的列（卡片不可见）。
+            const columnId = input.columnId ?? columns[0]?.id ?? DEFAULT_COLUMN_ID;
+            assertColumn(columns, columnId, 'add');
+            assertPriority(input.priority);
             const position = (await maxPos(boardId, columnId)) + POSITION_GAP;
             const [cardRow] = await db
                 .insert(kanbanCards)
@@ -99,6 +190,7 @@ function createKanbanStore(handle, projectId) {
             return rowToCard(row);
         },
         async updateCard(id, patch) {
+            assertPriority(patch.priority);
             const [row] = await db
                 .update(kanbanCards)
                 .set({
@@ -111,36 +203,69 @@ function createKanbanStore(handle, projectId) {
                 .where(eq(kanbanCards.id, id))
                 .returning();
             if (!row)
-                throw new Error(`Kanban card not found: ${id}`);
+                throw new KanbanCardNotFoundError(id);
             return rowToCard(row);
         },
         async moveCard(id, columnId, position) {
+            const [card] = await db
+                .select({ boardId: kanbanCards.boardId })
+                .from(kanbanCards)
+                .where(eq(kanbanCards.id, id))
+                .limit(1);
+            if (!card)
+                throw new KanbanCardNotFoundError(id);
+            // 悬空列校验：目标列必须存在于当前列配置，否则卡片静默不可见。
+            const columns = await boardColumns(card.boardId);
+            assertColumn(columns, columnId, 'move');
             // If no explicit position, append to end of target column.
-            let newPos = position;
-            if (newPos === undefined) {
-                const [card] = await db
-                    .select({ boardId: kanbanCards.boardId })
-                    .from(kanbanCards)
-                    .where(eq(kanbanCards.id, id))
-                    .limit(1);
-                if (!card)
-                    throw new Error(`Kanban card not found: ${id}`);
-                newPos = (await maxPos(card.boardId, columnId)) + POSITION_GAP;
-            }
+            const newPos = position ?? (await maxPos(card.boardId, columnId)) + POSITION_GAP;
             const [row] = await db
                 .update(kanbanCards)
                 .set({ columnId, position: newPos, updatedAt: new Date() })
                 .where(eq(kanbanCards.id, id))
                 .returning();
-            if (!row)
-                throw new Error(`Kanban card not found: ${id}`);
-            return rowToCard(row);
+            const moved = row;
+            return rowToCard(moved);
         },
         async deleteCard(id) {
             await db.delete(kanbanCards).where(eq(kanbanCards.id, id));
         },
         async updateBoard(patch) {
-            await getOrCreateBoardId();
+            const boardId = await getOrCreateBoardId();
+            // P1-4：删除列前校验该列内是否有卡片；删除标签前把悬空 labelId 从卡片上清掉。
+            if (patch.columns !== undefined) {
+                const cards = await db
+                    .select({ id: kanbanCards.id, columnId: kanbanCards.columnId })
+                    .from(kanbanCards)
+                    .where(eq(kanbanCards.boardId, boardId));
+                const newColumnIds = new Set(patch.columns.map((c) => c.id));
+                const removedWithCards = new Map();
+                const orphanCardIds = [];
+                for (const card of cards) {
+                    if (!newColumnIds.has(card.columnId)) {
+                        removedWithCards.set(card.columnId, (removedWithCards.get(card.columnId) ?? 0) + 1);
+                        orphanCardIds.push(card.id);
+                    }
+                }
+                if (removedWithCards.size > 0) {
+                    const total = Array.from(removedWithCards.values()).reduce((a, b) => a + b, 0);
+                    throw new KanbanColumnInUseError(Array.from(removedWithCards.keys()), total, orphanCardIds);
+                }
+            }
+            if (patch.labels !== undefined) {
+                const labelIds = new Set(patch.labels.map((l) => l.id));
+                const cards = await db
+                    .select({ id: kanbanCards.id, labels: kanbanCards.labels })
+                    .from(kanbanCards)
+                    .where(eq(kanbanCards.boardId, boardId));
+                for (const card of cards) {
+                    const current = (card.labels ?? []);
+                    const kept = current.filter((lid) => labelIds.has(lid));
+                    if (kept.length !== current.length) {
+                        await db.update(kanbanCards).set({ labels: kept }).where(eq(kanbanCards.id, card.id));
+                    }
+                }
+            }
             const [boardRow] = await db
                 .update(kanbanBoards)
                 .set({
@@ -148,11 +273,293 @@ function createKanbanStore(handle, projectId) {
                 ...(patch.labels !== undefined && { labels: patch.labels }),
                 updatedAt: new Date(),
             })
-                .where(eq(kanbanBoards.projectId, projectId))
+                .where(and(eq(kanbanBoards.projectId, projectId), isNull(kanbanBoards.deletedAt)))
                 .returning();
             const row = boardRow;
             return rowToBoard(row);
         },
+        /** 整板替换（导入）：board 配置 + 卡片在单事务内重建；中途失败整体回滚，
+         *  不残留「配置已换、卡片半新半旧」的混合状态。 */
+        async replaceBoard(input) {
+            const boardId = await getOrCreateBoardId();
+            await db.transaction(async (tx) => {
+                await tx.delete(kanbanCards).where(eq(kanbanCards.boardId, boardId));
+                await tx
+                    .update(kanbanBoards)
+                    .set({ columns: input.columns, labels: input.labels, updatedAt: new Date() })
+                    .where(eq(kanbanBoards.id, boardId));
+                if (input.cards.length > 0) {
+                    await tx.insert(kanbanCards).values(input.cards.map((c) => ({
+                        boardId,
+                        title: c.title,
+                        description: c.description ?? null,
+                        columnId: c.columnId,
+                        priority: c.priority,
+                        position: c.position,
+                        labels: c.labels,
+                    })));
+                }
+            });
+            const boardRow = await db
+                .select()
+                .from(kanbanBoards)
+                .where(eq(kanbanBoards.id, boardId))
+                .limit(1);
+            const board = boardRow[0];
+            const cards = await db
+                .select()
+                .from(kanbanCards)
+                .where(eq(kanbanCards.boardId, boardId))
+                .orderBy(asc(kanbanCards.columnId), asc(kanbanCards.position));
+            return { ...rowToBoard(board), cards: cards.map(rowToCard) };
+        },
+    };
+}
+export { createKanbanStore, KanbanCardNotFoundError, KanbanColumnInUseError, KanbanColumnNotFoundError, KanbanInvalidPriorityError, };
+/** 把活动看板软删除进回收站（记录原项目名与工作目录）。项目行删除后 FK 将 projectId 置 null。 */
+export async function softDeleteKanbanBoard(handle, projectId, projectName, worktree) {
+    const rows = await handle.db
+        .update(kanbanBoards)
+        .set({
+        deletedAt: new Date(),
+        deletedProjectName: projectName ?? undefined,
+        deletedProjectWorktree: worktree ?? undefined,
+        // 恢复后重删的看板须重新经历「到期 → 宽限」周期，宽限标记不跨删除周期生效。
+        purgePendingAt: null,
+        updatedAt: new Date(),
+    })
+        .where(and(eq(kanbanBoards.projectId, projectId), isNull(kanbanBoards.deletedAt)))
+        .returning({ id: kanbanBoards.id });
+    return rows.length > 0;
+}
+/** 行 + 卡片数 → 回收站条目（时间戳统一转 ms，兼容 Date/null/字符串）。 */
+function toDeletedBoard(b, cardCount) {
+    const toMs = (d) => {
+        if (d == null)
+            return null;
+        const t = d instanceof Date ? d.getTime() : new Date(d).getTime();
+        return Number.isFinite(t) ? t : null;
+    };
+    return {
+        id: b.id,
+        projectName: b.deletedProjectName ?? '未知项目',
+        cardCount,
+        deletedAt: toMs(b.deletedAt) ?? 0,
+        purgePendingAt: toMs(b.purgePendingAt),
+        deletedProjectWorktree: b.deletedProjectWorktree ?? null,
     };
 }
-export { createKanbanStore };
+/** 回收站看板列表（含卡片数）。 */
+export async function listDeletedKanbanBoards(handle) {
+    const boards = await handle.db
+        .select()
+        .from(kanbanBoards)
+        .where(isNotNull(kanbanBoards.deletedAt))
+        .orderBy(asc(kanbanBoards.deletedAt));
+    if (boards.length === 0)
+        return [];
+    const counts = await handle.db
+        .select({ boardId: kanbanCards.boardId, n: sql `count(*)::int` })
+        .from(kanbanCards)
+        .where(inArray(kanbanCards.boardId, boards.map((b) => b.id)))
+        .groupBy(kanbanCards.boardId);
+    const countMap = new Map(counts.map((c) => [c.boardId, c.n]));
+    return boards.map((b) => toDeletedBoard(b, countMap.get(b.id) ?? 0));
+}
+/** 按 id 取单个回收站看板（供「重建原项目」恢复读取原工作目录）。 */
+export async function getDeletedKanbanBoard(handle, boardId) {
+    const [b] = await handle.db
+        .select()
+        .from(kanbanBoards)
+        .where(and(eq(kanbanBoards.id, boardId), isNotNull(kanbanBoards.deletedAt)))
+        .limit(1);
+    if (!b)
+        return null;
+    const counts = await handle.db
+        .select({ n: sql `count(*)::int` })
+        .from(kanbanCards)
+        .where(eq(kanbanCards.boardId, boardId));
+    return toDeletedBoard(b, counts[0]?.n ?? 0);
+}
+/** 恢复看板到指定项目：目标项目已有活动看板 → 409 语义（不覆盖用户现有看板）。
+ *  P2 修复：检查与更新放进单事务，并发下撞 uq_kanban_boards_project 唯一索引时
+ *  降级为 TARGET_HAS_BOARD（此前抛 PG 错误 500）。 */
+export async function restoreKanbanBoard(handle, boardId, projectId) {
+    try {
+        return await handle.db.transaction(async (tx) => {
+            const [active] = await tx
+                .select({ id: kanbanBoards.id })
+                .from(kanbanBoards)
+                .where(and(eq(kanbanBoards.projectId, projectId), isNull(kanbanBoards.deletedAt)))
+                .limit(1);
+            if (active)
+                return { ok: false, reason: 'TARGET_HAS_BOARD' };
+            const rows = await tx
+                .update(kanbanBoards)
+                .set({
+                projectId,
+                deletedAt: null,
+                deletedProjectName: null,
+                deletedProjectWorktree: null,
+                purgePendingAt: null,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(kanbanBoards.id, boardId), isNotNull(kanbanBoards.deletedAt)))
+                .returning({ id: kanbanBoards.id });
+            if (rows.length === 0)
+                return { ok: false, reason: 'BOARD_NOT_FOUND' };
+            return { ok: true };
+        });
+    }
+    catch (err) {
+        // PG 23505 = unique_violation：并发窗口内目标板被创建。
+        if (err.code === '23505') {
+            return { ok: false, reason: 'TARGET_HAS_BOARD' };
+        }
+        throw err;
+    }
+}
+/**
+ * P1 修复：把回收站看板合并进目标项目的活动看板（TARGET_HAS_BOARD 死胡同的出口）。
+ * 此前「目标项目已有看板」时恢复 409，而产品没有删除活动看板的能力，用户无法
+ * 把旧项目卡片拿回现有项目——现在 merge 模式下：
+ *  - 目标无活动看板 → 等价普通恢复（重新归属）；
+ *  - 目标有活动看板 → 追加缺失列，卡片并入对应列末尾（position 重新计算避免
+ *    与目标卡片重叠）；源卡片引用源板已不存在列时落到目标第一列（保证可见）；
+ *  - 合并成功后源看板物理删除（卡片已迁移，FK cascade 清源卡）。
+ * 全程单事务：失败整体回滚，不残留半合并状态。
+ */
+export async function mergeKanbanBoard(handle, boardId, projectId) {
+    return await handle.db.transaction(async (tx) => {
+        const [src] = await tx
+            .select({ id: kanbanBoards.id, columns: kanbanBoards.columns })
+            .from(kanbanBoards)
+            .where(and(eq(kanbanBoards.id, boardId), isNotNull(kanbanBoards.deletedAt)))
+            .limit(1);
+        if (!src)
+            return { ok: false, reason: 'BOARD_NOT_FOUND' };
+        const [target] = await tx
+            .select({ id: kanbanBoards.id, columns: kanbanBoards.columns })
+            .from(kanbanBoards)
+            .where(and(eq(kanbanBoards.projectId, projectId), isNull(kanbanBoards.deletedAt)))
+            .limit(1);
+        // 目标无活动看板 → 重新归属（等价普通恢复，但保持 merge 调用幂等语义）。
+        if (!target) {
+            const rows = await tx
+                .update(kanbanBoards)
+                .set({
+                projectId,
+                deletedAt: null,
+                deletedProjectName: null,
+                deletedProjectWorktree: null,
+                purgePendingAt: null,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(kanbanBoards.id, boardId), isNotNull(kanbanBoards.deletedAt)))
+                .returning({ id: kanbanBoards.id });
+            if (rows.length === 0)
+                return { ok: false, reason: 'BOARD_NOT_FOUND' };
+            return { ok: true, mergedColumns: 0, mergedCards: 0 };
+        }
+        // —— 合并路径 ——
+        const srcCols = (src.columns ?? []);
+        const targetCols = (target.columns ?? []);
+        const targetIds = new Set(targetCols.map((c) => c.id));
+        const newCols = srcCols.filter((c) => !targetIds.has(c.id));
+        if (newCols.length > 0) {
+            await tx
+                .update(kanbanBoards)
+                .set({ columns: [...targetCols, ...newCols], updatedAt: new Date() })
+                .where(eq(kanbanBoards.id, target.id));
+        }
+        const mergedCols = [...targetCols, ...newCols];
+        const fallbackCol = mergedCols[0]?.id ?? DEFAULT_COLUMN_ID;
+        const srcCards = await tx
+            .select()
+            .from(kanbanCards)
+            .where(eq(kanbanCards.boardId, boardId))
+            .orderBy(asc(kanbanCards.position));
+        // 目标各列现有 max(position)：合并卡片追加到末尾，避免 position 重叠。
+        const targetMax = await tx
+            .select({ columnId: kanbanCards.columnId, m: max(kanbanCards.position) })
+            .from(kanbanCards)
+            .where(eq(kanbanCards.boardId, target.id))
+            .groupBy(kanbanCards.columnId);
+        const maxMap = new Map(targetMax.map((r) => [r.columnId, r.m ?? 0]));
+        const counters = new Map();
+        let mergedCards = 0;
+        for (const card of srcCards) {
+            const colId = mergedCols.some((c) => c.id === card.columnId) ? card.columnId : fallbackCol;
+            const idx = counters.get(colId) ?? 0;
+            counters.set(colId, idx + 1);
+            await tx.insert(kanbanCards).values({
+                boardId: target.id,
+                title: card.title,
+                description: card.description,
+                columnId: colId,
+                priority: card.priority,
+                position: (maxMap.get(colId) ?? 0) + POSITION_GAP * (idx + 1),
+                labels: card.labels ?? [],
+            });
+            mergedCards += 1;
+        }
+        // 源看板物理删除（卡片已迁移；卡片行经 FK cascade 连带清除）。
+        await tx.delete(kanbanBoards).where(eq(kanbanBoards.id, boardId));
+        return { ok: true, mergedColumns: newCols.length, mergedCards };
+    });
+}
+/** 回收站内彻底删除看板（不可恢复）。 */
+export async function permanentlyDeleteKanbanBoard(handle, boardId) {
+    const rows = await handle.db
+        .delete(kanbanBoards)
+        .where(and(eq(kanbanBoards.id, boardId), isNotNull(kanbanBoards.deletedAt)))
+        .returning({ id: kanbanBoards.id });
+    return rows.length;
+}
+/**
+ * 看板回收站两阶段清理（与会话 purgeDeletedSessions 同策略，杜绝「到期即静默清空」）：
+ *  - 阶段一：软删除超过 retentionMs 且尚未标记 → 写 purgePendingAt（进入宽限期，
+ *    UI 显示「即将清除」仍可恢复）；
+ *  - 阶段二：purgePendingAt 早于 graceMs 截止 → 物理清除（卡片经 FK cascade 连带删除）。
+ * 看板回收站全局单一分组、无「首次查看才起算」语义，保留期自删除时刻起算，稳定可预期。
+ */
+export async function purgeDeletedKanbanBoards(handle, retentionMs, graceMs) {
+    const retentionCutoff = new Date(Date.now() - retentionMs);
+    const graceCutoff = new Date(Date.now() - graceMs);
+    const rows = await handle.db
+        .select({
+        id: kanbanBoards.id,
+        deletedAt: kanbanBoards.deletedAt,
+        purgePendingAt: kanbanBoards.purgePendingAt,
+    })
+        .from(kanbanBoards)
+        .where(isNotNull(kanbanBoards.deletedAt));
+    // —— 阶段一：到期标记（先宽限，不直接清除）——
+    let marked = 0;
+    for (const r of rows) {
+        if (!r.deletedAt)
+            continue;
+        if (r.purgePendingAt)
+            continue;
+        if (r.deletedAt.getTime() >= retentionCutoff.getTime())
+            continue;
+        await handle.db
+            .update(kanbanBoards)
+            .set({ purgePendingAt: new Date(), updatedAt: new Date() })
+            .where(eq(kanbanBoards.id, r.id));
+        marked += 1;
+    }
+    // —— 阶段二：宽限期满物理清除 ——
+    const pendingIds = rows
+        .filter((r) => r.purgePendingAt && r.purgePendingAt.getTime() < graceCutoff.getTime())
+        .map((r) => r.id);
+    let deleted = 0;
+    if (pendingIds.length > 0) {
+        const removed = await handle.db
+            .delete(kanbanBoards)
+            .where(inArray(kanbanBoards.id, pendingIds))
+            .returning({ id: kanbanBoards.id });
+        deleted = removed.length;
+    }
+    return { marked, deleted };
+}

package/dist/llm/index.d.ts

@@ -8,6 +8,6 @@ export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overri
 export type { Retryable, RetryOptions } from './retry.js';
 export { delay, retryable, withRetry } from './retry.js';
 export type { FallbackChain } from './routing.js';
-export { runWithFallback, shouldFallOver } from './routing.js';
+export { buildFallbackChain, runWithFallback, shouldFallOver } from './routing.js';
 export * from './schema/index.js';
 export { estimateTokens } from './token.js';

package/dist/llm/index.js

@@ -3,6 +3,6 @@ export { buildInternalRequest, chat, chatStream, toInternalMessage, toStreamChun
 export { isContextOverflow, isContextOverflowFailure } from './provider-error.js';
 export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overrideToCapabilities, registerProvider, resolveModelByRole, resolveRoute, setRole, } from './registry.js';
 export { delay, retryable, withRetry } from './retry.js';
-export { runWithFallback, shouldFallOver } from './routing.js';
+export { buildFallbackChain, runWithFallback, shouldFallOver } from './routing.js';
 export * from './schema/index.js';
 export { estimateTokens } from './token.js';

package/dist/llm/provider.js

@@ -135,7 +135,7 @@ const streamTarget = async function* (ctx, request, target, chain) {
         headers: { authorization: `Bearer ${authHeader}`, ...resolved.route.headers() },
         signal: ctx.signal,
         fetchImpl: ctx.fetchImpl,
-    }), { maxRetries: chain.maxRetries, sleep: chain.sleep });
+    }), { maxRetries: chain.maxRetries, sleep: chain.sleep, initialDelayMs: chain.retryDelay });
     let state = initialStepState();
     for await (const frame of sseFraming(stream)) {
         const chunk = parseChunk(resolved.route.id, frame);

package/dist/llm/registry.d.ts

@@ -81,7 +81,13 @@ declare const setRole: (registry: Registry, role: ModelRole, provider: string, m
  * live request handlers (e.g. config hot-reload).
  */
 declare const rebuildRegistry: (registry: Registry, builder: (next: Registry) => void) => void;
+/**
+ * 内置价目表版本（H3）：记录 builtinCapabilities 最近一次人工核价的日期。
+ * LLM 价格频繁变动，前端在用量/成本面板展示此版本提醒「估算可能过期」；
+ * 发布新版本时同步核对 builtinCapabilities 并更新此常量（release checklist）。
+ */
+declare const PRICE_CATALOG_VERSION = "2026-09-09";
 /** Default role + a starter catalog of well-known models. */
 declare const builtinCapabilities: Record<string, Record<string, ModelCapabilities>>;
 export type { ProviderInput, Registry, ResolveResult, RouteEntry, RouteTable };
-export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overrideToCapabilities, rebuildRegistry, registerProvider, resolveModelByRole, resolveRoute, setRole, };
+export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overrideToCapabilities, PRICE_CATALOG_VERSION, rebuildRegistry, registerProvider, resolveModelByRole, resolveRoute, setRole, };

package/dist/llm/registry.js

@@ -117,6 +117,12 @@ const rebuildRegistry = (registry, builder) => {
     builder(next);
     registry.table = next.table;
 };
+/**
+ * 内置价目表版本（H3）：记录 builtinCapabilities 最近一次人工核价的日期。
+ * LLM 价格频繁变动，前端在用量/成本面板展示此版本提醒「估算可能过期」；
+ * 发布新版本时同步核对 builtinCapabilities 并更新此常量（release checklist）。
+ */
+const PRICE_CATALOG_VERSION = '2026-09-09';
 /** Default role + a starter catalog of well-known models. */
 const builtinCapabilities = {
     openai: {
@@ -151,4 +157,4 @@ const builtinCapabilities = {
         },
     },
 };
-export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overrideToCapabilities, rebuildRegistry, registerProvider, resolveModelByRole, resolveRoute, setRole, };
+export { builtinCapabilities, createRegistry, DEFAULT_MODEL_CAPABILITIES, overrideToCapabilities, PRICE_CATALOG_VERSION, rebuildRegistry, registerProvider, resolveModelByRole, resolveRoute, setRole, };

package/dist/llm/retry.d.ts

@@ -4,9 +4,10 @@ declare const RETRY_MAX_DELAY_NO_HEADERS = 30000;
 declare const RETRY_MAX_DELAY = 2147483647;
 /**
  * Compute the delay before the next retry attempt (ms).
- * Honors retry-after / retry-after-ms headers when present, else exponential backoff.
+ * Honors retry-after / retry-after-ms headers when present, else exponential backoff
+ * from the given base delay (defaults to RETRY_INITIAL_DELAY).
  */
-declare const delay: (attempt: number, error?: unknown) => number;
+declare const delay: (attempt: number, error?: unknown, initialDelayMs?: number) => number;
 /** A normalized, retryable error descriptor for the session layer. */
 type Retryable = {
     message: string;
@@ -29,6 +30,8 @@ type RetryOptions = {
         delayMs: number;
         error: unknown;
     }) => void;
+    /** Base delay for exponential backoff (default RETRY_INITIAL_DELAY). */
+    initialDelayMs?: number;
 };
 /**
  * Run an async operation with retry. Retries only on retryable LLM errors.

package/dist/llm/retry.js

@@ -17,9 +17,10 @@ const errorHeaders = (error) => {
 const capDelay = (ms) => Math.min(ms, RETRY_MAX_DELAY);
 /**
  * Compute the delay before the next retry attempt (ms).
- * Honors retry-after / retry-after-ms headers when present, else exponential backoff.
+ * Honors retry-after / retry-after-ms headers when present, else exponential backoff
+ * from the given base delay (defaults to RETRY_INITIAL_DELAY).
  */
-const delay = (attempt, error) => {
+const delay = (attempt, error, initialDelayMs = RETRY_INITIAL_DELAY) => {
     const headers = errorHeaders(error);
     if (headers) {
         const retryAfterMs = headers['retry-after-ms'];
@@ -37,9 +38,9 @@ const delay = (attempt, error) => {
             if (!Number.isNaN(parsed) && parsed > 0)
                 return capDelay(Math.ceil(parsed));
         }
-        return capDelay(RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR ** (attempt - 1));
+        return capDelay(initialDelayMs * RETRY_BACKOFF_FACTOR ** (attempt - 1));
     }
-    return capDelay(Math.min(RETRY_INITIAL_DELAY * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_MAX_DELAY_NO_HEADERS));
+    return capDelay(Math.min(initialDelayMs * RETRY_BACKOFF_FACTOR ** (attempt - 1), RETRY_MAX_DELAY_NO_HEADERS));
 };
 /**
  * Decide whether a thrown error is retryable. Returns undefined when not retryable
@@ -74,7 +75,7 @@ const withRetry = async (fn, options) => {
             const fallbackReason = isLLMError(error)
                 ? error.reason
                 : { _tag: 'InvalidRequest', message: '' };
-            const delayMs = Math.min(reasonRetryAfterMs(fallbackReason) ?? delay(attempt, error), canRetry.policy.maxDelay);
+            const delayMs = Math.min(reasonRetryAfterMs(fallbackReason) ?? delay(attempt, error, options.initialDelayMs), canRetry.policy.maxDelay);
             options.onRetry?.({ attempt, delayMs, error });
             await sleep(delayMs);
         }

package/dist/llm/routing.d.ts

@@ -32,5 +32,28 @@ declare const runWithFallback: <T>(registry: Registry, chain: FallbackChain, run
  * errors propagate without trying fallbacks.
  */
 declare const shouldFallOver: (error: unknown) => boolean;
+/** 回退目标所需的最小 provider 信息。 */
+type FallbackSourceProvider = {
+    name?: string;
+    _tag?: string;
+    /** 声明了模型清单的 provider 只对清单内的模型回退；未声明视为不支持（保守）。 */
+    models?: Record<string, unknown>;
+};
+/**
+ * 从 config.fallback 构建回退链（主 chat 循环/压缩/标题等 LLM 调用的接线点）。
+ * - enabled=false → undefined（保持内置默认：3 次重试、无跨 provider 回退）。
+ * - enabled=true → 按配置 maxRetries/retryDelay 重试，并对「声明了同一模型」的
+ *   其他 provider 依次回退。无合格回退目标时 fallbacks 为空——重试参数仍然生效。
+ * 回退只接受声明了该模型的 provider：对未声明的 provider 盲目回退会在其 API 处
+ * 得到 InvalidRequest 并中断整条链（shouldFallOver 不放过非回退错误）。
+ */
+declare function buildFallbackChain(config: {
+    providers: FallbackSourceProvider[];
+    fallback: {
+        enabled: boolean;
+        maxRetries: number;
+        retryDelay: number;
+    };
+}, provider: string, model: string): FallbackChain | undefined;
 export type { FallbackChain };
-export { runWithFallback, shouldFallOver };
+export { buildFallbackChain, runWithFallback, shouldFallOver };