c0de-agent 1.13.1 → 1.14.0

package/dist/session/session.js

@@ -34,7 +34,9 @@ parentId,
 /** 会话工作目录（CLI 会话必填：Web 打开时 agent 工具在该目录执行，而非 serve cwd）。 */
 worktreePath, 
 /** 初始 metadata（如工作流运行会话记录 workflowName，供中断恢复指引展示）。 */
-metadata) {
+metadata, 
+/** 插件 hook runner：创建成功后广播 session:create（可选，纯广播不阻断）。 */
+hooks) {
     const [row] = await handle.db
         .insert(sessions)
         .values({
@@ -49,7 +51,16 @@ metadata) {
         .returning();
     if (!row)
         throw new Error('Failed to insert session');
-    return rowToSession(row);
+    const created = rowToSession(row);
+    if (hooks) {
+        try {
+            await hooks.fireHooks('session:create', { session: created });
+        }
+        catch {
+            // 广播失败绝不阻断会话创建（fireHooks 内部已吞 handler 异常，双保险）
+        }
+    }
+    return created;
 }
 /**
  * Web 会话树可见性条件：web 会话（source 为 null/web）或「持久的 CLI 会话」。
@@ -259,10 +270,18 @@ async function restoreSessionCore(handle, id, opts = {}) {
     // 祖先链（仅还原其中已软删除的节点）：为保证恢复节点在会话树可达，
     // 已删除的祖先无论批次均需一并还原。记录还原的祖先数量与是否跨越删除批次，
     // 供前端提示「为保持会话树完整，同时还原了 N 个父会话」。
+    // 环守卫：parentId 成环数据（a↔b 互指/自引用，快照恢复或手改 DB 均可产生）
+    // 会让 while 循环在环上无限打转（每圈一条 DB 查询，恢复请求永不返回）——
+    // 已访问节点再次出现即终止，与 orderSessionsByParent/purgeDeletedSessions
+    // 的同型守卫一致。
     let restoredAncestorCount = 0;
     let crossedBatchAncestor = false;
     let parentId = row.parentId;
+    const visitedAncestors = new Set([id]);
     while (parentId) {
+        if (visitedAncestors.has(parentId))
+            break;
+        visitedAncestors.add(parentId);
         const [parent] = await handle.db.select().from(sessions).where(eq(sessions.id, parentId));
         if (!parent)
             break;
@@ -313,7 +332,8 @@ export const TRASH_PURGE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
  * 回收站两阶段清理（启动时与每日定时调用）：
  * 阶段一：进入保留期截止（首次看到 + 60 天）或绝对上限（删除 + 365 天，无论是否
  *   被看到）且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
- * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求）。
+ * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求；
+ *   删除闭包含全部后代，未到期的子行随父行一并清除）。
  * 恢复后重删、尚未重新看到的会话按「首次看到 + 60 天」计（绝对上限兜底仍生效）。
  */
 async function purgeDeletedSessions(handle, retentionMs = TRASH_RETENTION_MS, graceMs = TRASH_PURGE_GRACE_MS) {
@@ -323,7 +343,6 @@ async function purgeDeletedSessions(handle, retentionMs = TRASH_RETENTION_MS, gr
     const rows = await handle.db
         .select({
         id: sessions.id,
-        parentId: sessions.parentId,
         deletedAt: sessions.deletedAt,
         metadata: sessions.metadata,
     })
@@ -359,31 +378,11 @@ async function purgeDeletedSessions(handle, retentionMs = TRASH_RETENTION_MS, gr
         const p = meta.purgePendingAt;
         return typeof p === 'number' && p < graceCutoff;
     });
-    let deleted = 0;
-    if (pending.length > 0) {
-        // 拓扑序：无子会话的先删
-        const remaining = new Set(pending.map((r) => r.id));
-        while (remaining.size > 0) {
-            const hasChildParent = new Set(pending.filter((r) => r.parentId && remaining.has(r.parentId)).map((r) => r.parentId));
-            const leaves = pending
-                .filter((r) => remaining.has(r.id) && !hasChildParent.has(r.id))
-                .map((r) => r.id);
-            if (leaves.length === 0) {
-                // 循环引用兜底：强制按 id 逐个删除（自引用环数据异常场景）
-                for (const id of Array.from(remaining)) {
-                    await handle.db.delete(sessions).where(eq(sessions.id, id));
-                    remaining.delete(id);
-                    deleted += 1;
-                }
-                break;
-            }
-            for (const id of leaves) {
-                await handle.db.delete(sessions).where(eq(sessions.id, id));
-                remaining.delete(id);
-                deleted += 1;
-            }
-        }
-    }
+    if (pending.length === 0)
+        return { marked, deleted: 0 };
+    // 删除闭包含全部后代（子先父后）——pending 集合外的子行（未到期条目、跨项目
+    // 归属、未软删的 fork 后代）同样引用被删父行，漏掉即撞 FK 23503 让清理整体失败。
+    const deleted = await deleteSessionSubtrees(handle, pending.map((r) => r.id));
     return { marked, deleted };
 }
 /** C4：空会话 GC 保留期（7 天）。仅覆盖「从未写入任何消息/工具条目」的会话。 */
@@ -443,89 +442,101 @@ async function purgeEmptySession(handle, id) {
     return true;
 }
 /**
- * 彻底删除某个回收站会话及其全部后代（含未软删除的 fork 后代，防御数据异常）。
- * 子会话先于父会话删除（自引用 FK RESTRICT 要求）；entries/archives 经 FK cascade 清理。
- * 返回删除数量。会话不存在或不在回收站 → 返回 0。
+ * 物理删除会话子树：rootIds + 其**全部后代**（不论删除状态与项目归属），子先父后。
+ * 返回实际删除行数。
+ *
+ * 自引用 FK（sessions.parentId，无 onDelete 级联）要求任何引用待删行的子行先删，
+ * 且子行可能不在调用方给定的清除集合内：跨项目归属（子会话经 rebind 留在另一
+ * 项目）、未到期/未进入宽限期的回收站条目、乃至未软删除的 fork 后代（数据异常，
+ * 与 permanentlyDeleteSession 既有防御同口径）。只按「待清除集合」排序会在这些
+ * 子行上撞 FK 23503——emptyTrash(projectId) 直接 500（该项目回收站永远清不掉）、
+ * purgeDeletedSessions 整体抛错（启动/每日清理静默失败，回收站永不清理）。
+ * 故删除闭包必须扩展到全部后代，集合外无人引用集合内行时断开父指针亦安全。
+ *
+ * 环数据（parentId 互指/自引用）无拓扑序可解：无叶可删时先断开集合内父指针
+ * （仅集合内引用，集合外不可能引用集合内行），再整体删除。
  */
-async function permanentlyDeleteSession(handle, id) {
-    const [row] = await handle.db
-        .select({ id: sessions.id, deletedAt: sessions.deletedAt })
-        .from(sessions)
-        .where(eq(sessions.id, id));
-    if (!row?.deletedAt)
+async function deleteSessionSubtrees(handle, rootIds) {
+    if (rootIds.length === 0)
         return 0;
     const all = await handle.db
         .select({ id: sessions.id, parentId: sessions.parentId })
         .from(sessions);
-    const ids = new Set([id]);
-    let frontier = [id];
+    const ids = new Set();
+    let frontier = [];
+    for (const id of rootIds) {
+        if (ids.has(id) || !all.some((r) => r.id === id))
+            continue;
+        ids.add(id);
+        frontier.push(id);
+    }
     while (frontier.length > 0) {
-        const children = all
-            .filter((r) => r.parentId && frontier.includes(r.parentId))
-            .map((r) => r.id)
-            .filter((cid) => !ids.has(cid));
-        for (const cid of children)
-            ids.add(cid);
-        frontier = children;
+        const next = [];
+        for (const r of all) {
+            if (!r.parentId || ids.has(r.id) || !frontier.includes(r.parentId))
+                continue;
+            ids.add(r.id);
+            next.push(r.id);
+        }
+        frontier = next;
     }
-    // 拓扑序：无子会话的先删（与 purgeDeletedSessions 同策略）
     const remaining = new Set(ids);
     let deleted = 0;
     while (remaining.size > 0) {
-        const hasChildParent = new Set(Array.from(remaining).filter((rid) => {
-            const r = all.find((x) => x.id === rid);
-            return r?.parentId && remaining.has(r.parentId);
-        }));
+        // 仍有子会话存活的父 id 集合（其子会话先删，避免自引用 FK 违反）。
+        const hasChildParent = new Set();
+        for (const r of all) {
+            if (r.parentId && remaining.has(r.parentId) && remaining.has(r.id)) {
+                hasChildParent.add(r.parentId);
+            }
+        }
         const leaves = Array.from(remaining).filter((rid) => !hasChildParent.has(rid));
         if (leaves.length === 0) {
-            for (const rid of Array.from(remaining)) {
-                await handle.db.delete(sessions).where(eq(sessions.id, rid));
-                remaining.delete(rid);
-                deleted += 1;
-            }
+            // 环兜底：集合内成环（a↔b / 自引用），无叶可删——断开父指针后整体删除。
+            const cycleIds = Array.from(remaining);
+            await handle.db.update(sessions).set({ parentId: null }).where(inArray(sessions.id, cycleIds));
+            const rows = await handle.db
+                .delete(sessions)
+                .where(inArray(sessions.id, cycleIds))
+                .returning({ id: sessions.id });
+            deleted += rows.length;
             break;
         }
-        for (const rid of leaves) {
-            await handle.db.delete(sessions).where(eq(sessions.id, rid));
+        const rows = await handle.db
+            .delete(sessions)
+            .where(inArray(sessions.id, leaves))
+            .returning({ id: sessions.id });
+        deleted += rows.length;
+        for (const rid of leaves)
             remaining.delete(rid);
-            deleted += 1;
-        }
     }
     return deleted;
 }
-/** 清空回收站：物理删除所有已软删除会话（子先于父）。返回删除数量。
- *  projectId 提供时仅清空该项目（P1-7）。 */
+/**
+ * 彻底删除某个回收站会话及其全部后代（含未软删除的 fork 后代，防御数据异常）。
+ * 子会话先于父会话删除（自引用 FK RESTRICT 要求）；entries/archives 经 FK cascade 清理。
+ * 返回删除数量。会话不存在或不在回收站 → 返回 0。
+ */
+async function permanentlyDeleteSession(handle, id) {
+    const [row] = await handle.db
+        .select({ id: sessions.id, deletedAt: sessions.deletedAt })
+        .from(sessions)
+        .where(eq(sessions.id, id));
+    if (!row?.deletedAt)
+        return 0;
+    return deleteSessionSubtrees(handle, [id]);
+}
+/** 清空回收站：物理删除所有已软删除会话（子先于父，连同其全部后代）。
+ *  projectId 提供时仅以该项目条目为根（P1-7）——后代闭包仍含其他项目的子行
+ *  （它们引用被删父行，必须同批删除）。返回删除数量。 */
 async function emptyTrash(handle, projectId) {
     const rows = await handle.db
-        .select({ id: sessions.id, parentId: sessions.parentId })
+        .select({ id: sessions.id })
         .from(sessions)
         .where(projectId
         ? and(gt(sessions.deletedAt, new Date(0)), eq(sessions.projectId, projectId))
         : gt(sessions.deletedAt, new Date(0)));
-    if (rows.length === 0)
-        return 0;
-    const remaining = new Set(rows.map((r) => r.id));
-    let deleted = 0;
-    while (remaining.size > 0) {
-        const hasChildParent = new Set(rows.filter((r) => r.parentId && remaining.has(r.parentId)).map((r) => r.parentId));
-        const leaves = rows
-            .filter((r) => remaining.has(r.id) && !hasChildParent.has(r.id))
-            .map((r) => r.id);
-        if (leaves.length === 0) {
-            for (const id of Array.from(remaining)) {
-                await handle.db.delete(sessions).where(eq(sessions.id, id));
-                remaining.delete(id);
-                deleted += 1;
-            }
-            break;
-        }
-        for (const id of leaves) {
-            await handle.db.delete(sessions).where(eq(sessions.id, id));
-            remaining.delete(id);
-            deleted += 1;
-        }
-    }
-    return deleted;
+    return deleteSessionSubtrees(handle, rows.map((r) => r.id));
 }
 /**
  * 清理过期临时会话（P2 → P1 收紧：仅处理显式标记的临时会话）。

package/dist/session/shake.js

@@ -1,4 +1,5 @@
-import { estimateTokens } from './token.js';
+import { headChars } from '../shared/utils/string.js';
+import { estimateMessageTokens, estimateTokens } from './token.js';
 /** Rough token cost of a placeholder line; used only for the savings gate. */
 const PLACEHOLDER_TOKEN_ESTIMATE = 16;
 /** 识别顶层 XML 元素（小写 tag，保守策略）。 */
@@ -20,26 +21,49 @@ export function scanTextForBlockRanges(text) {
     const ranges = [];
     let inFence = false;
     let fenceStart = -1;
+    // 开启围栏的 marker（字符 + 长度）。闭合必须同字符且长度 ≥ 开启长度
+    //（markdown 语义）；异种/更短围栏行是块内内容——此前任意围栏行都切换
+    // inFence：``` 块内的 ~~~ 行把 range 拦腰截断、真实闭合行被当成新围栏
+    // 开端、后续顶层 XML 块被误吞。
+    let fenceChar = '';
+    let fenceLen = 0;
     const tagStack = [];
     let xmlStart = -1;
+    // CRLF 归一化：\r\n 文件的每行末尾携带 \r——XML 正则的 $ 锚定在 \r 上恒失败
+    // （顶层 XML 块永远不被识别），且 range 若含 \r，applyShakeRegions 替换后
+    // 该行变裸 \n，与其余 \r\n 行混排产出混合行尾。扫描行剥离 \r、range end
+    // 内收到 \r 之前，替换即无损。
+    const isCRLF = text.includes('\r\n');
     let lineStart = 0;
     for (let i = 0; i <= text.length; i++) {
         if (i !== text.length && text[i] !== '\n')
             continue;
-        const line = text.slice(lineStart, i);
-        const lineEnd = i;
+        let line = text.slice(lineStart, i);
+        let lineEnd = i;
+        if (isCRLF && line.endsWith('\r')) {
+            line = line.slice(0, -1);
+            lineEnd = i - 1;
+        }
         const trimmedStart = line.trimStart();
-        const isFenceLine = trimmedStart.startsWith('```') || trimmedStart.startsWith('~~~');
-        if (isFenceLine) {
+        const fenceMatch = /^(`{3,}|~{3,})/.exec(trimmedStart);
+        if (fenceMatch) {
+            const marker = fenceMatch[1] ?? '';
+            const markerChar = marker[0] ?? '';
+            const markerLen = marker.length;
             if (!inFence) {
                 inFence = true;
                 fenceStart = lineStart;
+                fenceChar = markerChar;
+                fenceLen = markerLen;
             }
-            else {
+            else if (markerChar === fenceChar && markerLen >= fenceLen) {
                 inFence = false;
                 ranges.push({ start: fenceStart, end: lineEnd });
                 fenceStart = -1;
+                fenceChar = '';
+                fenceLen = 0;
             }
+            // 围栏行（含块内异种/更短的围栏行）不参与 XML 检测
             lineStart = i + 1;
             continue;
         }
@@ -88,27 +112,13 @@ function mergeRanges(ranges) {
     }
     return kept;
 }
-/** 单条消息的 token 估算（优先用缓存的 tokenCount）。 */
+/** 单条消息的 token 估算（优先用缓存的 tokenCount）。
+ *  委托 token.ts 的 estimateMessageTokens：此前本模块持有一份同型私有实现，
+ *  与权威实现同步漂移（image 部分两处同缺、恒计 0），收敛后口径单源。 */
 function messageTokens(m) {
     if (m.tokenCount > 0)
         return m.tokenCount;
-    let total = 0;
-    for (const part of m.content) {
-        switch (part._tag) {
-            case 'text':
-            case 'thinking':
-            case 'steering':
-                total += estimateTokens(part.text);
-                break;
-            case 'tool_call':
-                total += estimateTokens(JSON.stringify(part.input));
-                break;
-            case 'tool_result':
-                total += estimateTokens(JSON.stringify(part.output));
-                break;
-        }
-    }
-    return total;
+    return estimateMessageTokens(m.content);
 }
 /** tool_result part 的输出文本。 */
 function toolResultText(output) {
@@ -294,7 +304,7 @@ export function toRegionViews(regions, config, messages) {
         partIndex: region.partIndex,
         tokens: region.tokens,
         label: region.label,
-        preview: region.originalText.slice(0, 200),
+        preview: headChars(region.originalText, 200),
         placeholder: region.kind === 'toolResult'
             ? `[shaken: ${region.label}, ${region.tokens} tokens]`
             : '[shaken]',

package/dist/session/squash.js

@@ -1,7 +1,7 @@
 import { generateId } from '../shared/index.js';
 import { archiveOriginalEntries } from './archive.js';
 import { extractHotFiles } from './compaction.js';
-import { deleteEntriesByIds, getMessages, insertEntry } from './message.js';
+import { deleteEntriesByIds, getMessages, insertEntry, summaryEntryTimestamp } from './message.js';
 import { upsertFileSnapshot } from './snapshot.js';
 import { estimateTokens } from './token.js';
 const DEFAULT_SQUASH_CONFIG = {
@@ -78,9 +78,8 @@ ${history}`;
                 archiveId,
             },
             tokenCount: estimateTokens(summary),
-            // Position at the first squashed message's timestamp so it sorts between
-            // the prefix and the kept tail under createdAt-ascending order.
-            createdAt: toSquash[0] ? new Date(toSquash[0].createdAt) : new Date(),
+            // 定位在首个被压缩消息处（并列时间戳时再早 1ms），保证摘要排在保留尾部之前。
+            createdAt: summaryEntryTimestamp(toSquash[0], keepTail[0]),
         });
         return { archiveId, fileSnapshotIds };
     });

package/dist/session/token.d.ts

@@ -1,10 +1,9 @@
+import { estimateTokens } from '../llm/token.js';
 import type { MessageContent } from '../shared/types/message.js';
-/**
- * CJK-aware token estimate.
- * Chinese/CJK characters ≈ 2 tokens each (denser encoding).
- * Other characters ≈ 4 chars/token (standard heuristic).
- */
-declare const estimateTokens: (text: string) => number;
-/** Sum token estimates across all parts of a message's content array. */
+export { estimateTokens };
+/** Sum token estimates across all parts of a message's content array.
+ *  缺字段分片（import sanitizeContent 只校验 _tag，input/output 可能缺省）保守按
+ *  0 token 计：JSON.stringify(undefined) 返回 undefined（非字符串），直接传入
+ *  estimateTokens 会抛 TypeError，把 agent run 整个击穿在预算拟合处。 */
 declare const estimateMessageTokens: (content: MessageContent[]) => number;
-export { estimateMessageTokens, estimateTokens };
+export { estimateMessageTokens };

package/dist/session/token.js

@@ -1,16 +1,14 @@
-/**
- * CJK-aware token estimate.
- * Chinese/CJK characters ≈ 2 tokens each (denser encoding).
- * Other characters ≈ 4 chars/token (standard heuristic).
- */
-const estimateTokens = (text) => {
-    if (text.length === 0)
-        return 0;
-    const cjkCount = text.match(/[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g)?.length ?? 0;
-    const otherCount = text.length - cjkCount;
-    return Math.ceil(cjkCount * 2 + otherCount / 4);
-};
-/** Sum token estimates across all parts of a message's content array. */
+import { estimateTokens } from '../llm/token.js';
+export { estimateTokens };
+/** 单张图片的固定 token 估算。
+ *  provider 图片计费按像素维度而非字节（OpenAI high-detail 1024×1024 ≈ 1105），
+ *  message 内容只携带 base64 数据、无尺寸信息——按字节长度估算会系统性偏差
+ *  数百倍（1MB 截图 ≈ 34 万「token」）。固定典型值保数量级正确。 */
+const IMAGE_PART_TOKEN_ESTIMATE = 1100;
+/** Sum token estimates across all parts of a message's content array.
+ *  缺字段分片（import sanitizeContent 只校验 _tag，input/output 可能缺省）保守按
+ *  0 token 计：JSON.stringify(undefined) 返回 undefined（非字符串），直接传入
+ *  estimateTokens 会抛 TypeError，把 agent run 整个击穿在预算拟合处。 */
 const estimateMessageTokens = (content) => {
     let total = 0;
     for (const part of content) {
@@ -21,13 +19,18 @@ const estimateMessageTokens = (content) => {
                 total += estimateTokens(part.text);
                 break;
             case 'tool_call':
-                total += estimateTokens(JSON.stringify(part.input));
+                total += part.input === undefined ? 0 : estimateTokens(JSON.stringify(part.input));
                 break;
             case 'tool_result':
-                total += estimateTokens(JSON.stringify(part.output));
+                total += part.output === undefined ? 0 : estimateTokens(JSON.stringify(part.output));
+                break;
+            case 'image':
+                // 图片轮次真实开销约千级 token——此前无 case 恒计 0，
+                // 预算护栏/压缩窗口把图片消息当免费。
+                total += IMAGE_PART_TOKEN_ESTIMATE;
                 break;
         }
     }
     return total;
 };
-export { estimateMessageTokens, estimateTokens };
+export { estimateMessageTokens };

package/dist/session/usage.js

@@ -11,6 +11,7 @@
 //     金额 + token 双口径超支判定（token 兜底价格未知的自建网关/未登记模型）。
 import { and, eq, gte } from 'drizzle-orm';
 import { appMeta, sessions, usageEvents } from '../db/schema.js';
+import { roundTo } from '../shared/round.js';
 /**
  * 把 sessions.metadata.segments 中全部调用补齐进 usage_events（幂等）。
  * 覆盖：升级前历史数据、fork 复制的 segments（display 用途）、导入会话携带的
@@ -145,14 +146,15 @@ export async function budgetOverageParts(handle, usage, projectId, now = new Dat
     }
     const parts = [];
     // 实际超支轴中的最严格阻断动作：任一超支轴动作 === 'abort' 即整体 abort，否则 pause。
+    // 金额展示经 roundTo 十进制舍入（toFixed 二进制近似会把 1.005 显示成 1.00）。
     let action = 'pause';
     if (amountBlocks && globalBudgetUsd > 0 && global && global.cost > globalBudgetUsd) {
-        parts.push(`全局预算 $${globalBudgetUsd.toFixed(2)}：本月全部项目已 $${global.cost.toFixed(2)}`);
+        parts.push(`全局预算 $${roundTo(globalBudgetUsd, 2).toFixed(2)}：本月全部项目已 $${roundTo(global.cost, 2).toFixed(2)}`);
         if (amountAction === 'abort')
             action = 'abort';
     }
     if (amountBlocks && projectBudgetUsd > 0 && project && project.cost > projectBudgetUsd) {
-        parts.push(`项目预算 $${projectBudgetUsd.toFixed(2)}：本项目已 $${project.cost.toFixed(2)}`);
+        parts.push(`项目预算 $${roundTo(projectBudgetUsd, 2).toFixed(2)}：本项目已 $${roundTo(project.cost, 2).toFixed(2)}`);
         if (amountAction === 'abort')
             action = 'abort';
     }

package/dist/shared/index.d.ts

@@ -1,2 +1,3 @@
+export { MAX_TIMER_MS } from './timer.js';
 export type * from './types/index.js';
 export { generateId, now } from './utils.js';

package/dist/shared/index.js

@@ -1 +1,2 @@
+export { MAX_TIMER_MS } from './timer.js';
 export { generateId, now } from './utils.js';

package/dist/shared/round.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 按十进制语义舍入到指定小数位（half-up）。
+ *
+ * `x.toFixed(n)` 直接作用于二进制浮点近似值：1.005 在内存中是 1.004999…，
+ * toFixed 舍入为 "1.00"——少一分钱（0.015→"0.01"、2.675→"2.67" 同类）。
+ * Intl.NumberFormat 按最短十进制表示舍入，消除该系统性偏差；返回值仍为
+ * number（无分组符），调用方再以 toFixed 输出显示字符串。
+ *
+ * 无 node 依赖：web（vite tsconfig 无 node types）与服务端均可引用。
+ */
+declare function roundTo(value: number, digits: number): number;
+export { roundTo };

package/dist/shared/round.js

@@ -0,0 +1,18 @@
+/**
+ * 按十进制语义舍入到指定小数位（half-up）。
+ *
+ * `x.toFixed(n)` 直接作用于二进制浮点近似值：1.005 在内存中是 1.004999…，
+ * toFixed 舍入为 "1.00"——少一分钱（0.015→"0.01"、2.675→"2.67" 同类）。
+ * Intl.NumberFormat 按最短十进制表示舍入，消除该系统性偏差；返回值仍为
+ * number（无分组符），调用方再以 toFixed 输出显示字符串。
+ *
+ * 无 node 依赖：web（vite tsconfig 无 node types）与服务端均可引用。
+ */
+function roundTo(value, digits) {
+    return Number(new Intl.NumberFormat('en-US', {
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+        useGrouping: false,
+    }).format(value));
+}
+export { roundTo };

package/dist/shared/timer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Node timer 的 32 位安全上限：setTimeout/setInterval 的延迟超过
+ * 2^31-1（2147483647ms ≈ 24.8 天）会被引擎钳到 1ms（TimeoutOverflowWarning）。
+ *
+ * 任何把用户输入/配置/插件声明直接作为 timer 延迟的调用点都必须先经本常量
+ * 钳制或校验——否则「超长超时/超长间隔」会变成「立即触发」：命令刚 spawn 即
+ * 被杀、间隔变成每毫秒狂刷。同类值此前散落定义（llm/retry.ts 的
+ * RETRY_MAX_DELAY），现已收敛为单一来源。
+ */
+export declare const MAX_TIMER_MS = 2147483647;
+/**
+ * 归一化「用户输入/配置/插件声明」提供的 timer 时长（毫秒）。
+ *
+ * 引擎行为：非有限（NaN/±Infinity）或超 32 位上限的延迟都被钳到 1ms。
+ * 两种退化都必须拦截，否则语义反转——
+ *  - 上界：写「超长超时/间隔」本意是「等很久/少检查」，实际立即触发/每毫秒狂刷；
+ *  - 下界：0/负数（如「不检查」的配置写法）同样落到 1ms 轮询，比上界情形更糟。
+ *
+ * @param ms           外部提供的时长；undefined 视为未设置
+ * @param fallback     非法值（非有限或 < minInclusive）的回落值
+ * @param minInclusive 合法下界（一次性延迟可为 0=立即；间隔类传 1）
+ */
+export declare function clampTimerDelay(ms: number | undefined, fallback: number, minInclusive?: number): number;

package/dist/shared/timer.js

@@ -0,0 +1,27 @@
+/**
+ * Node timer 的 32 位安全上限：setTimeout/setInterval 的延迟超过
+ * 2^31-1（2147483647ms ≈ 24.8 天）会被引擎钳到 1ms（TimeoutOverflowWarning）。
+ *
+ * 任何把用户输入/配置/插件声明直接作为 timer 延迟的调用点都必须先经本常量
+ * 钳制或校验——否则「超长超时/超长间隔」会变成「立即触发」：命令刚 spawn 即
+ * 被杀、间隔变成每毫秒狂刷。同类值此前散落定义（llm/retry.ts 的
+ * RETRY_MAX_DELAY），现已收敛为单一来源。
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * 归一化「用户输入/配置/插件声明」提供的 timer 时长（毫秒）。
+ *
+ * 引擎行为：非有限（NaN/±Infinity）或超 32 位上限的延迟都被钳到 1ms。
+ * 两种退化都必须拦截，否则语义反转——
+ *  - 上界：写「超长超时/间隔」本意是「等很久/少检查」，实际立即触发/每毫秒狂刷；
+ *  - 下界：0/负数（如「不检查」的配置写法）同样落到 1ms 轮询，比上界情形更糟。
+ *
+ * @param ms           外部提供的时长；undefined 视为未设置
+ * @param fallback     非法值（非有限或 < minInclusive）的回落值
+ * @param minInclusive 合法下界（一次性延迟可为 0=立即；间隔类传 1）
+ */
+export function clampTimerDelay(ms, fallback, minInclusive = 0) {
+    if (ms === undefined || !Number.isFinite(ms) || ms < minInclusive)
+        return fallback;
+    return Math.min(ms, MAX_TIMER_MS);
+}

package/dist/shared/types/tool.d.ts

@@ -69,6 +69,10 @@ type ToolContext = {
     /** Spawn a sub-agent and return its final text output (dependency-reversal hook
      *  for the `task` tool; avoids tools→core circular import). */
     runSubAgent?: (input: SubAgentRequest) => Promise<SubAgentResult>;
+    /** 批量派发子 agent（task 工具的批量模式）。宿主负责并发池（按
+     *  config.agents.subagentConcurrency）与逐任务错误隔离，结果与入参顺序一一对应；
+     *  未注入时 task 工具回退逐个调用 runSubAgent（串行）。 */
+    runSubAgents?: (input: SubAgentRequest[]) => Promise<SubAgentResult[]>;
     /** Spawn a debug adapter and return its stdio transport (dependency-reversal
      *  hook for the `debug_*` tools; host wires real child_process spawn). */
     debugSpawn?: (config: unknown) => DebugTransport;

package/dist/shared/utils/markdown-code.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Markdown 代码剥离：围栏代码块与行内代码一律移除，供「只该命中人类文字」的
+ * prose 感知检测共用（workflowz 关键词、<todo:*> 标签、composer 的 @agent
+ * 提及提取等）。
+ *
+ * 此前各检测点自带 ad-hoc 剥离（```...``` 非贪婪配对 + `[^`]*` 单反引号）——
+ * 未闭合围栏、~~~ 围栏、长反引号围栏、多反引号行内代码全部漏网：代码内容上的
+ * 关键词/标签/提及被误触发（工作流通告注入 / todo 状态幽灵变更 / 误派发子 agent）。
+ *
+ * 语义（保守方向——宁可多剥，不可在代码上误判）：
+ * - 围栏开启 = 行首（≤3 空格缩进）+ ≥3 个同字符反引号/波浪线；
+ *   闭合 = 同字符、长度 ≥ 开启、行内仅剩空白；未闭合围栏吞掉余文。
+ * - 行内代码 = 等长反引号对（``x`` 内可含单反引号，CommonMark 口径）。
+ */
+export declare function stripMarkdownCode(text: string): string;