@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/context/context-budget-tracker.js

@@ -0,0 +1,400 @@
+import { generateText } from 'ai';
+import { silentLogger } from '../ports/logger.js';
+import { COMPACTION_CHECKPOINT_KIND } from '../schema/index.js';
+import { COMPACTION_INSTRUCTION, judgeSummary } from '../turn/compaction.js';
+import { measureModelMessageChars, } from '../turn/context-pressure.js';
+import { partsToModelMessages, } from '../turn/parts-to-model-messages.js';
+import { charsToTokens, computeContextThreshold, computePruneCut, measureRowChars, } from './context-budget.js';
+/**
+ * 一个 tick 最多压缩几次（含失败的尝试）。
+ *
+ * **2 = 一次 + 一次重试**。再多没有意义：一个不肯好好写摘要的模型第三次多半还是
+ * 那样，而每次尝试都是一整个上下文的全量请求 —— 空转与真压缩一样贵，还各断一次
+ * 前缀缓存。压不动就让这一轮照常发出去，撞爆了自有溢出补救接手。
+ */
+const MAX_COMPACTION_ATTEMPTS = 2;
+/**
+ * 还活着的那条 checkpoint 行的 seq（`seq > compactedUpto` 的最后一条）。
+ *
+ * 取**最后一条**而不是第一条：正常情况下只有一条，多出来的只可能是历史遗留，
+ * 而新的切点要覆盖的是最靠后那条 —— 覆盖它就顺带覆盖了它前面所有的。
+ */
+function lastCheckpointSeq(rows, compactedUpto) {
+    let found = null;
+    for (const r of rows) {
+        if (compactedUpto !== null && r.seq <= compactedUpto)
+            continue;
+        if (r.kind === COMPACTION_CHECKPOINT_KIND)
+            found = r.seq;
+    }
+    return found;
+}
+/**
+ * 一个 tick 的上下文预算管家。
+ *
+ * **持有轮初那批行的快照，全程不再查库拿历史**。两条理由，都不是性能：
+ *
+ * 1. 「本轮已开的行不许进阴影区」——快照里根本没有本轮的行（`loadContext` 跑在
+ *    第一次 `drainInbox` 之前，本轮的用户消息那时还在 inbox 里），这条因此是
+ *    结构上成立的，不靠谁记得去判断。
+ * 2. 重新查库投影会把 drain 消息的**围栏**抹掉（内存里那些用的是 `modelParts`，
+ *    与落库的 `parts` 不同）。这也是 `ContextRelief` 只替换头部的原因。
+ */
+export class ContextBudgetTracker {
+    deps;
+    rows = [];
+    storedRows = [];
+    prunedUpto = null;
+    compactedUpto = null;
+    /**
+     * 上一条还活着的 checkpoint 行的 seq（没有则 null）。
+     *
+     * 新的压缩切点**必须覆盖它**：留着它就会同时存在两份摘要，而投影层只提头一条，
+     * 另一条会按 seq 落在保留段中间——同一段历史被讲两遍，且其中一遍是过期的。
+     */
+    checkpointSeq = null;
+    baseline = null;
+    /** 已经报过一次「模型没填容量」的 warn，别每步刷一条。 */
+    warnedNoCapacity = false;
+    /**
+     * 本 tick 已经尝试过几次压缩。
+     *
+     * **失败的也算**：一个不肯好好写摘要的模型，重试第三次多半还是那样，而每次
+     * 都是一整个上下文的全量请求 —— 空转的代价与真压缩一样贵。
+     */
+    compactionAttempts = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** `TurnHost.loadContext`：投影出带裁剪与压缩的历史，同时留下本轮要用的快照。 */
+    async load() {
+        const { rows, prunedUptoSeq, compactedUptoSeq, baselineContextTokens } = await this.deps.store.loadContextInputs(this.deps.sessionId);
+        this.storedRows = rows;
+        this.rows = rows.map(r => ({
+            seq: r.seq,
+            chars: measureRowChars(r.parts),
+        }));
+        this.prunedUpto = prunedUptoSeq;
+        this.compactedUpto = compactedUptoSeq;
+        this.checkpointSeq = lastCheckpointSeq(rows, compactedUptoSeq);
+        this.baseline = baselineContextTokens;
+        return this.project({ upto: null });
+    }
+    /**
+     * 快照的投影，可选只取 `seq ≤ upto` 的那一段（算 `replaces` 用）。
+     *
+     * 收成一个方法而不是各处各写一次 `partsToModelMessages(...)`：**两个指针必须
+     * 一起传**，漏掉压缩指针那一处会把已经压掉的行重新投出来，而症状只是「压缩
+     * 好像没生效」。
+     *
+     * **checkpoint 行不受 `upto` 约束**：它的 seq 是全场最大的，而投影层把它提到了
+     * 历史最前面 —— `messages` 的头部因此是「checkpoint + 前 upto 条」。按 seq 卡掉
+     * 它，算出来的 `replaces` 就比真实头部少一条，splice 会把尾部整体错位一格。
+     */
+    project(opts) {
+        const upto = opts.upto;
+        const rows = upto === null
+            ? this.storedRows
+            : this.storedRows.filter(r => r.seq <= upto || r.seq === this.checkpointSeq);
+        return partsToModelMessages(rows, {
+            prunedUptoSeq: this.prunedUpto,
+            compactedUptoSeq: this.compactedUpto,
+            ...this.deps.projection,
+        });
+    }
+    /**
+     * 本轮的触发线。**也给前端**（经 `TurnResult.contextThreshold` 落进
+     * metadata）——界面上那个「快满了」的变色判据必须与这里同源，各写一个 0.8
+     * 的结果是界面说「还早」而日志里已经在裁了。
+     */
+    thresholdOf(maxContextTokens) {
+        return computeContextThreshold({
+            maxContextTokens,
+            maxOutputTokens: this.deps.maxOutputTokens,
+            reserveFactor: this.deps.reserveFactor,
+        });
+    }
+    /** 本轮的触发线；容量未知时为 null（那时压根不做主动裁剪）。 */
+    get threshold() {
+        const max = this.deps.maxContextTokens;
+        return max === null ? null : this.thresholdOf(max);
+    }
+    /**
+     * `beforeModelCall` 的正体：超阈值就腾空间，返回新的头部。
+     *
+     * **两级，顺序固定**：先裁剪（免模型、零成本、单次就能吃掉长会话的大头），
+     * 裁到头仍不够才压缩（要花一次全量请求）。免模型的路径永远该先跑，模型摘要
+     * 是兜底 —— 裁剪把压缩的触发频率压得很低正是期望的结果。
+     */
+    async relieve(pressure) {
+        // **provider 已经拒了**：跳过一切阈值判断。阈值是我们对「快满了」的猜测，
+        // 这一刻已经不是猜测。这条路同时覆盖了「模型没填 max_context_tokens、平时
+        // 压根不主动腾」的那一类会话——它们唯一的保护就是这里。
+        if (pressure.overflowed) {
+            const retainTokens = this.deps.retainRatio * this.estimatedHistoryTokens();
+            const why = 'provider reported context overflow';
+            return ((await this.prune(retainTokens, why)) ??
+                this.compact(pressure, why, retainTokens));
+        }
+        const max = this.deps.maxContextTokens;
+        if (max === null) {
+            // **不猜容量、也不改用纯估算去判断**：没有真实数字时任何阈值都是编的。
+            // 这类会话不做主动腾空间，只靠上面那条溢出补救兜底——provider 真报了超限
+            // 的话，它已经替我们判定了必要性。
+            if (!this.warnedNoCapacity) {
+                this.warnedNoCapacity = true;
+                this.deps.logger.warn(`session ${this.deps.sessionId}: model has no max_context_tokens, context pruning is off for this turn`);
+            }
+            return null;
+        }
+        const base = pressure.lastStepInputTokens ?? this.baseline;
+        // 会话头一轮：既没调过模型、也没有上一轮留下的基线。此时历史必然很短。
+        if (base === null)
+            return null;
+        const estimate = base + charsToTokens(pressure.charsSinceLastStep);
+        const threshold = this.thresholdOf(max);
+        if (estimate < threshold)
+            return null;
+        // 保留量相对**可用空间**而不是整个窗口：窗口里给输出预留的那块，历史本来
+        // 就不该占。
+        const retainTokens = threshold * this.deps.retainRatio;
+        const why = `~${Math.round(estimate)} ≥ ${Math.round(threshold)} of ${max}`;
+        return ((await this.prune(retainTokens, why)) ??
+            this.compact(pressure, why, retainTokens));
+    }
+    /**
+     * 还在上下文里的那段历史有多大（按 `字符数 / 4` 估）。
+     *
+     * **只在溢出补救那条路上用**：那时可能连模型窗口都不知道（`max_context_tokens`
+     * 没填），拿不到触发线，也就没有「触发线 × 保留比例」这个口径。用历史自己的
+     * 规模当分母是这种情况下唯一站得住的做法——刚刚撞爆过，所以它约等于窗口。
+     *
+     * 注意这是**原始行**的规模：裁剪已经把一部分正文换成存根了，故这是个高估，
+     * 方向是「多腾一点」。撞爆之后宁可多腾。
+     */
+    estimatedHistoryTokens() {
+        const chars = this.survivingRows().reduce((sum, r) => sum + r.chars, 0);
+        return charsToTokens(chars);
+    }
+    /**
+     * 尚未被压缩掉的那部分快照。**切点只能在这里面算** —— 已经压掉的行在模型眼里
+     * 不存在了，把它们算进保留预算会让预算凭空少一块，切点随之偏晚。
+     */
+    survivingRows() {
+        const upto = this.compactedUpto;
+        return upto === null ? this.rows : this.rows.filter(r => r.seq > upto);
+    }
+    /** 第一级：把裁剪指针往前推。腾不动返回 null（交给压缩）。 */
+    async prune(retainTokens, why) {
+        const cut = computePruneCut(this.survivingRows(), retainTokens);
+        if (cut === null || (this.prunedUpto !== null && cut <= this.prunedUpto)) {
+            return null;
+        }
+        const before = this.project({ upto: cut });
+        const prevPruned = this.prunedUpto;
+        this.prunedUpto = cut;
+        const head = this.project({ upto: cut });
+        if (head.length !== before.length) {
+            // 裁剪只换 tool-result 的正文，**条数必须一模一样**——这是「只替换头部」
+            // 那条对齐的前提。真变了就是有人把裁剪改成了会增删消息的东西，此时按
+            // `before.length` 去 splice 会把尾部错位（历史与围栏消息一起被吃掉），
+            // 而那是静默的。宁可这一轮不腾空间。
+            this.prunedUpto = prevPruned;
+            this.deps.logger.error(`session ${this.deps.sessionId}: pruning changed message count (${before.length} → ${head.length}), skipping relief`);
+            return null;
+        }
+        await this.deps.store.advancePrunedUpto(this.deps.sessionId, cut);
+        this.deps.logger.log(`session ${this.deps.sessionId}: pruned tool results up to seq ${cut} (${why} tokens)`);
+        return { head, replaces: before.length };
+    }
+    /**
+     * 第二级：让模型把前面那段历史写成一份交接说明，整段换成一条 checkpoint。
+     *
+     * **失败一律返回 null、不抛。** 主动的阈值检查里超线不等于撞爆，这一轮多半
+     * 照样发得出去；为了「上下文快满了」把一轮本来能成的对话打死，比什么都不做更
+     * 糟。真撞爆的那条路（溢出补救）自己会判定必要性——它拿到 null 就把 provider
+     * 的原始错误原样抛出，抛错的判断权在内核那一侧，不在这里。
+     */
+    async compact(pressure, why, retainTokens) {
+        const cutBySize = computePruneCut(this.survivingRows(), retainTokens);
+        // **切点必须覆盖上一条 checkpoint**：留着它就是两份摘要同时在历史里，而
+        // 投影层只把最早那条提到头，另一条会按 seq 落在保留段中间——同一段历史讲两遍，
+        // 其中一遍还是过期的。
+        //
+        // 这个 clamp **只抬高一个真实存在的切点**，不能拿它去制造切点：`cutBySize`
+        // 为 null 时保留段本来就在预算之内，此时若只因为「有一条 checkpoint」就压，
+        // 那是拿一次全量请求去把上一份摘要重写一遍，压力一点没降。
+        if (cutBySize === null) {
+            // 已经压到头了。**debug 级、且不写库**：腾不出空间时压力不会下降，下一步
+            // 还会再问一次，warn 会变成每步一条。
+            this.deps.logger.debug(`session ${this.deps.sessionId}: over threshold (${why}) but nothing left to compact`);
+            return null;
+        }
+        const cut = Math.max(cutBySize, this.checkpointSeq ?? 0);
+        if (this.compactedUpto !== null && cut <= this.compactedUpto)
+            return null;
+        if (this.compactionAttempts >= MAX_COMPACTION_ATTEMPTS) {
+            this.deps.logger.debug(`session ${this.deps.sessionId}: compaction already attempted ${this.compactionAttempts}× this tick, standing down`);
+            return null;
+        }
+        this.compactionAttempts++;
+        // 顶掉的是**当前投影下**的那一段头部，不是原始行的大小：裁剪可能已经把它们
+        // 换成存根了，拿原文去比会高估源、让一份其实没压缩多少的摘要蒙混过关。
+        const before = this.project({ upto: cut });
+        if (before.length === 0)
+            return null;
+        const sourceChars = measureModelMessageChars(before);
+        let summary;
+        try {
+            const result = await generateText({
+                model: this.deps.llm.model,
+                // 逐字重放：同一份 instructions、同一份工具定义、同样的历史，**只在末尾
+                // 追加一条压缩指令**。这样这次调用能命中 provider 的 warm prefix。
+                instructions: pressure.request.system,
+                messages: [
+                    ...pressure.request.messages,
+                    { role: 'user', content: COMPACTION_INSTRUCTION },
+                ],
+                tools: pressure.request.tools,
+                providerOptions: this.deps.llm.providerOptions,
+                abortSignal: pressure.request.abortSignal,
+            });
+            // **只取 text**。reasoning 丢掉（那是模型的私有推理，落进历史等于把它
+            // 泄给后续每一轮）；tool call 也丢掉（收下就会造出一个没有 result 的
+            // 孤儿 tool_use，各家协议一律 400）。模型如果只调了工具没写字，下面
+            // `judgeSummary` 会以「没有产出任何文本」拒掉。
+            summary = result.text;
+        }
+        catch (err) {
+            this.deps.logger.error(`session ${this.deps.sessionId}: compaction request failed: ${String(err)}`);
+            return null;
+        }
+        const verdict = judgeSummary(summary, sourceChars);
+        if (!verdict.ok) {
+            // 静默丢掉一次全量请求是最贵的那种沉默：钱花了、前缀缓存也断了，日志里
+            // 却什么都没有。
+            this.deps.logger.error(`session ${this.deps.sessionId}: rejected compaction summary (${verdict.reason})`);
+            return null;
+        }
+        const row = await this.deps.store.appendCheckpoint({
+            sessionId: this.deps.sessionId,
+            seq: cut,
+            summary: summary.trim(),
+        });
+        this.compactedUpto = cut;
+        this.checkpointSeq = row.seq;
+        // 快照跟着补上这条新行。
+        //
+        // **本 tick 里其实不会再触发第二次腾空间**：切点取的正是「尾部累计刚超过保留
+        // 预算」的那一行，压完之后保留段必然恰好在预算之内，下一步 `computePruneCut`
+        // 两级都返回 null。留着这几行是为了让对象**始终自洽** —— 只更新指针不更新快照
+        // 的话，谁哪天动了触发条件（比如按剩余空间动态收紧保留比例），错位会以「顶掉的
+        // 条数差一格」的形态静默出现，而那正是最难查的一类。
+        this.storedRows = [...this.storedRows, row];
+        this.rows = [
+            ...this.rows,
+            { seq: row.seq, chars: measureRowChars(row.parts) },
+        ];
+        const head = partsToModelMessages([row], this.deps.projection);
+        this.deps.logger.log(`session ${this.deps.sessionId}: compacted history up to seq ${cut} into checkpoint ${row.id} (${why} tokens, ${sourceChars} → ${summary.trim().length} chars)`);
+        return { head, replaces: before.length };
+    }
+}
+/**
+ * tracker 在 `TurnContext.turnState` 里的键。**导出**：宿主按它预置
+ * （`createContextBudgetTracker` 的用法示例），插件按它取用，两边分叉的症状是上下文预算
+ * 静默关闭——没有报错，只有会话在某一天撞爆 context window。
+ */
+export const CONTEXT_BUDGET_TURN_STATE_KEY = 'context-budget';
+/**
+ * 取本轮的 tracker。**用 `instanceof` 而不是类型断言**：`turnState` 是一张各插件
+ * 混住的异构表，断言在这里等于「相信键上放对了东西」，而放错的那一天不会报错。
+ */
+function trackerOf(ctx) {
+    const found = ctx.turnState.get(CONTEXT_BUDGET_TURN_STATE_KEY);
+    return found instanceof ContextBudgetTracker ? found : null;
+}
+/** 宿主不给时的缺省参数（照抄 dsh 跑过真实负载的那一组）。 */
+export const CONTEXT_BUDGET_DEFAULTS = {
+    /** 预留几倍的最大输出（见 `ThresholdInput.reserveFactor`）。 */
+    reserveFactor: 1,
+    /** 腾空间时保留触发线的多大比例给最近的历史。 */
+    retainRatio: 0.16,
+};
+/**
+ * 建本轮的 tracker。宿主在 `TurnHost` 里这样接：
+ *
+ * ```ts
+ * const budget = createContextBudgetTracker({ store, sessionId, llm, maxContextTokens, … });
+ * const host: TurnHost = {
+ *   loadContext: () => budget.load(),
+ *   turnState: new Map([[CONTEXT_BUDGET_TURN_STATE_KEY, budget]]),
+ *   …
+ * };
+ * // 终态：budget.threshold 落进 metadata，界面的「快满了」与这里同源。
+ * ```
+ *
+ * **tracker 由宿主建、经 `turnState` 交给钩子**，钩子自己不建：它同时是
+ * `loadContext` 的投影源与终态 `contextThreshold` 的来源，三方必须是同一个实例；
+ * 且切点跑在第一次 drain 之后，那时懒建出来的快照会把本轮的用户消息算进可裁剪的
+ * 阴影区。
+ *
+ * 阈值参数在 agent-base 里走系统参数（只有真实负载上才知道合不合适，调它们不该
+ * 要一次发版）；这里由宿主传入，宿主自己决定从哪读。
+ */
+export function createContextBudgetTracker(opts) {
+    return new ContextBudgetTracker({
+        store: opts.store,
+        logger: opts.logger ?? silentLogger(''),
+        sessionId: opts.sessionId,
+        llm: opts.llm,
+        maxContextTokens: opts.maxContextTokens,
+        maxOutputTokens: opts.maxOutputTokens,
+        reserveFactor: opts.reserveFactor ?? CONTEXT_BUDGET_DEFAULTS.reserveFactor,
+        retainRatio: opts.retainRatio ?? CONTEXT_BUDGET_DEFAULTS.retainRatio,
+        ...(opts.projection ? { projection: opts.projection } : {}),
+    });
+}
+export const CONTEXT_BUDGET_HOOK_META = {
+    name: 'context-budget',
+    point: 'beforeModelCall',
+    order: 100,
+    // **压缩是一次完整的 LLM 调用**（逐字重放整个会话前缀），分钟级。缺省的 5s
+    // 会把它一律掐成超时；而把默认值抬上去等于让其余每个点的保护一起松掉。
+    // 这道超时是第二重保护——摘要请求本身带着本轮的 abortSignal，停止按钮先生效。
+    timeoutMs: 300_000,
+    // **腾不出空间不该把一轮本来能成的对话打死**：主动路径上超线只是我们对
+    // 「快满了」的猜测，这一轮多半照样发得出去。tracker 内部已经把压缩失败吞成
+    // null，会漏到这里的只剩裁剪指针那次存储写——它失败时下一轮重新读，
+    // 状态仍然自洽。真撞爆的那条路（`overflowed`）拿到 null 会把 provider 的
+    // 原始错误原样抛出，判断权在内核那一侧。
+    onError: 'open',
+};
+/**
+ * 上下文预算的 `beforeModelCall` 钩子：取宿主预置的 tracker，把压力转给它。
+ *
+ * **单例点**——两个插件先后替换 `messages` 的头部，第二个看到的已经不是原始
+ * 历史，它算出的 `replaces` 对不上任何一段真实前缀。
+ */
+export class ContextBudgetHook {
+    logger;
+    constructor(logger = silentLogger('')) {
+        this.logger = logger;
+    }
+    beforeModelCall(ctx, pressure) {
+        const tracker = trackerOf(ctx);
+        if (!tracker) {
+            // 接线坏了（宿主没预置），**不是**「这一轮不需要腾」。不抛：抛了就是拿
+            // 每一轮对话给一个接线错误陪葬；但必须响亮到日志里，否则症状要等到会话
+            // 撞爆 context window 才出现，那时离成因已经很远了。
+            this.logger.error(`run ${ctx.runId}: no context-budget tracker on this turn, context pruning is off`);
+            return Promise.resolve(null);
+        }
+        return tracker.relieve(pressure);
+    }
+}
+/** 把上下文预算钩子挂到注册表上。 */
+export function registerContextBudgetHook(hooks, logger) {
+    hooks.register(CONTEXT_BUDGET_HOOK_META, new ContextBudgetHook(logger));
+}
+//# sourceMappingURL=context-budget-tracker.js.map

package/dist/context/context-budget-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-tracker.js","sourceRoot":"","sources":["../../src/context/context-budget-tracker.ts"],"names":[],"mappings":"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"}

package/dist/context/context-budget.d.ts

@@ -0,0 +1,48 @@
+import type { MessagePart } from '../schema/index.js';
+export interface ThresholdInput {
+    maxContextTokens: number;
+    /** 模型的单次最大输出；null = 运营没填。 */
+    maxOutputTokens: number | null;
+    /**
+     * 预留几倍的最大输出。**默认 1**（完整预留）。
+     *
+     * 代价是不对称的：早裁一次的代价是断一次前缀缓存、丢几段老工具结果正文；
+     * 撞爆的代价是整轮挂掉，而且此后这个会话**每一次**发言都失败。不对称到这个
+     * 程度时不该为省几个 token 去赌模型这次不会吐满。调小它等于押注「实际输出
+     * 只会用到上限的一部分」——那个押注多数时候赢，输一次就是上面那个后果。
+     */
+    reserveFactor: number;
+}
+/**
+ * 什么时候该腾空间：**当剩余空间装不下一次完整的模型输出**。
+ *
+ * 真正的硬约束从来是 `上下文 + 本次输出 ≤ 窗口`，固定比例（原来的 0.8）只是在
+ * 猜这条线，而且在两端都猜错：1M 窗口按 0.8 要留 20 万 token 的余量，荒谬；8k
+ * 窗口配 4k 输出的模型按 0.8 只留 1.6k，一次满输出就撞。按输出算是**尺度自适应**
+ * 的，小窗口自动更保守、大窗口自动更激进。
+ */
+export declare function computeContextThreshold(i: ThresholdInput): number;
+/**
+ * 一行落库消息的字符规模。
+ *
+ * 逐 part 序列化，与 `measureModelMessageChars` 同口径（都只求相对大小，不求准）。
+ */
+export declare function measureRowChars(parts: MessagePart[]): number;
+export interface PrunableRow {
+    seq: number;
+    chars: number;
+}
+/**
+ * 新的裁剪切点：从**尾部**往前留够 `retainTokens` 的预算，剩下的全进阴影区。
+ * 返回 `null` = 整段历史都在保留预算之内，没什么可切的。
+ *
+ * `rows` 必须按 seq 升序（`listMessages` 的既有口径）。
+ *
+ * **成块推进，不是每轮挪一点。** 保留预算取的是模型容量的一个固定比例，所以
+ * 同一段历史反复检查会算出同一个切点、第二次直接无事发生；而「每轮往前挪几行」
+ * 那种写法每挪一次就断一次 provider 的前缀缓存，挪得越碎命中率越低。
+ */
+export declare function computePruneCut(rows: PrunableRow[], retainTokens: number): number | null;
+/** 字符数折成 token 的估算值。 */
+export declare function charsToTokens(chars: number): number;
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/context/context-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../../src/context/context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6CtD,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAQjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAM5D;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EAAE,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CASf;AAED,wBAAwB;AACxB,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/context/context-budget.js

@@ -0,0 +1,89 @@
+/**
+ * 上下文预算的纯函数层：一行有多大、切点切在哪。
+ *
+ * 与 `parts-to-model-messages.ts` 的分工——那边管「阴影区里的行投影成什么样」，
+ * 这边管「阴影区的边界在哪」。两者都不碰库。
+ */
+/** 估算 token 时用的字符折算率。见 `ContextPressure.charsSinceLastStep` 的判据。 */
+const CHARS_PER_TOKEN = 4;
+/**
+ * 触发线的下限，占窗口的比例。
+ *
+ * 有些模型的 `max_output_tokens` 就等于半个窗口甚至更多（8k/4k 那一代很常见）。
+ * 不夹的话触发线会掉到 50% 以下、极端情形直接为 0 —— 变成「永远在触发、永远
+ * 裁不动」，每步刷一行日志。夹在这里等于承认「这种模型你就是只能用一半上下文」，
+ * 那是事实，不是妥协。
+ */
+const THRESHOLD_FLOOR_RATIO = 0.5;
+/**
+ * 触发线的上限，占窗口的比例。
+ *
+ * `max_output_tokens` 很小的模型（1M 窗口配 1k 输出）会把触发线推到 99.9%，而
+ * 我们补在基线上的增量是 `chars / 4` 估的、对中文严重低估。这 8% 就是留给估算
+ * 误差的。
+ *
+ * **实际上这条在主流大窗口模型上是常态而非例外**：它们的
+ * `max_output / max_context` 普遍在 8% 以下（1M/64k = 6.4%），所以触发线基本
+ * 恒等于 92%。公式真正起作用的是小窗口那一端（32k/8k = 25%）—— 而那正是固定
+ * 比例最容易出事的地方。
+ */
+const THRESHOLD_CEIL_RATIO = 0.92;
+/**
+ * `max_output_tokens` 没填时，按窗口的这个比例假设。
+ *
+ * 取 0.2 使得 `reserveFactor = 1` 时公式恰好退化成「窗口 × 0.8」—— 也就是这套
+ * 东西最初那个固定阈值。旧行为成了新公式的一个特例，不必为「模型没填输出上限」
+ * 另开一条代码路径。
+ */
+const DEFAULT_OUTPUT_RATIO = 0.2;
+/**
+ * 什么时候该腾空间：**当剩余空间装不下一次完整的模型输出**。
+ *
+ * 真正的硬约束从来是 `上下文 + 本次输出 ≤ 窗口`，固定比例（原来的 0.8）只是在
+ * 猜这条线，而且在两端都猜错：1M 窗口按 0.8 要留 20 万 token 的余量，荒谬；8k
+ * 窗口配 4k 输出的模型按 0.8 只留 1.6k，一次满输出就撞。按输出算是**尺度自适应**
+ * 的，小窗口自动更保守、大窗口自动更激进。
+ */
+export function computeContextThreshold(i) {
+    const assumedOutput = i.maxOutputTokens ?? i.maxContextTokens * DEFAULT_OUTPUT_RATIO;
+    const raw = i.maxContextTokens - assumedOutput * i.reserveFactor;
+    return Math.min(Math.max(raw, i.maxContextTokens * THRESHOLD_FLOOR_RATIO), i.maxContextTokens * THRESHOLD_CEIL_RATIO);
+}
+/**
+ * 一行落库消息的字符规模。
+ *
+ * 逐 part 序列化，与 `measureModelMessageChars` 同口径（都只求相对大小，不求准）。
+ */
+export function measureRowChars(parts) {
+    let total = 0;
+    for (const part of parts) {
+        total += JSON.stringify(part)?.length ?? 0;
+    }
+    return total;
+}
+/**
+ * 新的裁剪切点：从**尾部**往前留够 `retainTokens` 的预算，剩下的全进阴影区。
+ * 返回 `null` = 整段历史都在保留预算之内，没什么可切的。
+ *
+ * `rows` 必须按 seq 升序（`listMessages` 的既有口径）。
+ *
+ * **成块推进，不是每轮挪一点。** 保留预算取的是模型容量的一个固定比例，所以
+ * 同一段历史反复检查会算出同一个切点、第二次直接无事发生；而「每轮往前挪几行」
+ * 那种写法每挪一次就断一次 provider 的前缀缓存，挪得越碎命中率越低。
+ */
+export function computePruneCut(rows, retainTokens) {
+    let retained = 0;
+    for (let i = rows.length - 1; i >= 0; i--) {
+        retained += rows[i].chars / CHARS_PER_TOKEN;
+        // 这一行**自己**就是压垮保留预算的那一行，故它也进阴影区（切点是闭区间的
+        // 上界）。把它留在外面会让「保留预算」变成一个只增不减的软上限。
+        if (retained > retainTokens)
+            return rows[i].seq;
+    }
+    return null;
+}
+/** 字符数折成 token 的估算值。 */
+export function charsToTokens(chars) {
+    return chars / CHARS_PER_TOKEN;
+}
+//# sourceMappingURL=context-budget.js.map

package/dist/context/context-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.js","sourceRoot":"","sources":["../../src/context/context-budget.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,oEAAoE;AACpE,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;;;GAOG;AACH,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAiBjC;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAiB;IACvD,MAAM,aAAa,GACjB,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,gBAAgB,GAAG,oBAAoB,CAAC;IACjE,MAAM,GAAG,GAAG,CAAC,CAAC,gBAAgB,GAAG,aAAa,GAAG,CAAC,CAAC,aAAa,CAAC;IACjE,OAAO,IAAI,CAAC,GAAG,CACb,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,EACzD,CAAC,CAAC,gBAAgB,GAAG,oBAAoB,CAC1C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAOD;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAmB,EACnB,YAAoB;IAEpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,eAAe,CAAC;QAC5C,wCAAwC;QACxC,kCAAkC;QAClC,IAAI,QAAQ,GAAG,YAAY;YAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAClD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK,GAAG,eAAe,CAAC;AACjC,CAAC"}

package/dist/context/index.d.ts

@@ -0,0 +1,3 @@
+export { charsToTokens, computeContextThreshold, computePruneCut, measureRowChars, type PrunableRow, type ThresholdInput, } from './context-budget.js';
+export { CONTEXT_BUDGET_DEFAULTS, CONTEXT_BUDGET_HOOK_META, CONTEXT_BUDGET_TURN_STATE_KEY, ContextBudgetHook, ContextBudgetTracker, createContextBudgetTracker, registerContextBudgetHook, } from './context-budget-tracker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,3 @@
+export { charsToTokens, computeContextThreshold, computePruneCut, measureRowChars, } from './context-budget.js';
+export { CONTEXT_BUDGET_DEFAULTS, CONTEXT_BUDGET_HOOK_META, CONTEXT_BUDGET_TURN_STATE_KEY, ContextBudgetHook, ContextBudgetTracker, createContextBudgetTracker, registerContextBudgetHook, } from './context-budget-tracker.js';
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,eAAe,EACf,eAAe,GAGhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,6BAA6B,EAC7B,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC"}

package/dist/extensions/repeat-call.hook.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 重复工具调用提醒，**作为扩展接在 turn hook 上**——内核因此不再认识「重复调用」
+ * 这件事，它只知道「发起一次工具调用前问一句 preToolUse」。
+ *
+ * 纯文本层（链怎么记、什么时候出声、说什么）仍在 `runtime/loop-reminder.ts`，
+ * 本文件只做接线。
+ *
+ * **记账与投递在同一个点上**：记在**调用发起处**（被拒绝、报错的调用一样计数
+ * ——模型反复撞一个必失败的调用正是最该提醒的循环），劝告随决策的 `systemNote`
+ * 挂到**同一次调用的结果**上，归属天然精确。
+ *
+ * **不能改成「订阅事件流去记账」**（讨论中出现过这个说法，是错的）：note 是同步
+ * 调用、同步返回劝告，而劝告要跟着这次调用的结果走。改成订阅就是异步消费同步
+ * 生产，`tool-call` 事件还没被处理、结果已经落定——竞态，症状是「提醒偶尔不
+ * 出现」。能靠订阅的只有不影响本轮行为的事后观测。
+ */
+import type { TurnHookRegistry } from '../hooks/turn-hook.registry.js';
+import { type PreToolUseResult, type TurnContext, type TurnHookImpl, type TurnHookMeta } from '../hooks/turn-hook.types.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+/**
+ * 记账链。**order 取最小**：链要看到最接近模型原始输出的那份入参，别的
+ * `preToolUse` 插件改写过之后再记，会把「同一次调用」判成换了参数。
+ */
+export declare const REPEAT_CALL_HOOK_META: TurnHookMeta;
+export declare class RepeatCallHook implements TurnHookImpl {
+    private readonly tools;
+    constructor(tools: ToolRegistry);
+    preToolUse(ctx: TurnContext, toolName: string, input: unknown): Promise<PreToolUseResult>;
+}
+/** 把重复调用提醒挂到注册表上（runtime 的缺省扩展，宿主可以不挂）。 */
+export declare function registerRepeatCallHook(hooks: TurnHookRegistry, tools: ToolRegistry): void;
+//# sourceMappingURL=repeat-call.hook.d.ts.map

package/dist/extensions/repeat-call.hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeat-call.hook.d.ts","sourceRoot":"","sources":["../../src/extensions/repeat-call.hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EAElB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAM9D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAKnC,CAAC;AAEF,qBAAa,cAAe,YAAW,YAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAEhD,UAAU,CACR,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC;CAmB7B;AAED,2CAA2C;AAC3C,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,YAAY,GAClB,IAAI,CAEN"}