@armadra/agent 0.4.0 → 0.5.0

package/dist/agent/session-compaction.js

@@ -1,10 +1,17 @@
 /**
  * 会话侧的压缩调度（设计 §9）。[B2]
  *
- * - 阈值检查（新提示前、`prepareNextTurn` 里）：估算 > 0.7 ×（窗口 − 预留）→ 档一裁剪；仍 > 窗口 − 预留
- *   且熔断允许 → 档二摘要（trigger `threshold`）。
+ * - 阈值检查（新提示前、`prepareNextTurn` 里）：估算 > 0.7 ×（窗口 − 预留）→ 档一裁剪（[W5-H1] 按工具
+ *   结果新旧计边界，可省 ≥ clearAtLeast 才动，一次清到 0.5 ×）；仍 > 窗口 − 预留且熔断允许 → 档二摘要
+ *   （trigger `threshold`）。缓存已冷（上次请求距今超过 TTL，只认 reported 端点）时未到 0.7 也裁，
+ *   且一次换掉全部候选。
+ * - 自检（[W5-H1] C8）：摘要缺 `## Goal` 重试一次再回落；自动压缩后估算不比压缩前小判失败，不写条目。
+ * - 回注（[W5-H1] C6 / C13）：摘要末尾接 `<post-compact-state>` 块（todo、计划、已加载 Skill、最近
+ *   文件、转录与 outputs 路径，不含文件正文；理由见 compaction/post-compact.ts），再跑 PostCompact
+ *   Hook，其 additionalContext 以 `ama.hook_context` 追加在末尾。
+ * - 熔断（[W5-H1] C5）：连续 3 次失败或连续 3 次快速回填跳闸；固定前缀超预算不再尝试；都只告警一次。
  * - 溢出恢复（会话 run 结束后，失败尝试已用 context_edit 剔除）：PreCompact Hook → 档二摘要（trigger
- *   `overflow`，不受「每 run 一次」限制但受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
+ *   `overflow`，受跳闸限制）→ 压缩后估算 ≤ 0.8 × 窗口才重试。
  * - 手动 `/compact`：PreCompact（trigger `manual`）→ 摘要；成功清零熔断。
  * PreCompact 的 `decision: "block"` 取消本次压缩；`customInstructions` 追加到摘要提示。
  * [W3-C1b] 阈值 / 手动压缩与分支摘要优先走会话前缀续写（缓存控制器给前缀），溢出恢复不走
@@ -12,9 +19,11 @@
  */
 import { AmaError } from "../errors.js";
 import { CompactionBreaker } from "../compaction/breaker.js";
-import { estimateProjectedTokens } from "../compaction/estimate.js";
-import { planPrune, shouldPrune } from "../compaction/prune-tier.js";
-import { prepareCompaction, runCompaction, } from "../compaction/summarize-tier.js";
+import { estimateMessageTokens, estimateProjectedTokens, } from "../compaction/estimate.js";
+import { planPrune, prunePolicy } from "../compaction/prune-tier.js";
+import { createProtection, skillLocations } from "../compaction/protect.js";
+import { buildPostCompactBlock } from "../compaction/post-compact.js";
+import { prepareCompaction, prepareCompactionAt, runCompaction, } from "../compaction/summarize-tier.js";
 import { prepareBranchSummary, runBranchSummary } from "../compaction/branch-summary.js";
 import { buildProjection } from "../session/projection.js";
 export const DEFAULT_COMPACTION_SETTINGS = {
@@ -24,14 +33,25 @@ export const DEFAULT_COMPACTION_SETTINGS = {
 };
 /** 保留区不超过 (窗口 − 预留) 的 40%，否则小窗口模型上摘要后仍然溢出。 */
 export const KEEP_RECENT_MAX_RATIO = 0.4;
+/** Hook additionalContext 的 custom 类型（与 UserPromptSubmit 的相同）。 */
+const HOOK_CONTEXT_CUSTOM_TYPE = "ama.hook_context";
 export class CompactionController {
     breaker;
     settings;
     core;
     compacting = false;
+    warnedReason;
+    /** [W5-H1] config `compaction.prune / pruneExclude`（组装根把整段 config.compaction 展开传入）。 */
+    pruneConfig;
     constructor(core, settings = {}) {
         this.core = core;
         this.settings = { ...DEFAULT_COMPACTION_SETTINGS, ...settings };
+        const extra = settings;
+        this.pruneConfig = {};
+        if (extra.prune !== undefined)
+            this.pruneConfig.prune = extra.prune;
+        if (extra.pruneExclude !== undefined)
+            this.pruneConfig.pruneExclude = extra.pruneExclude;
         this.breaker = new CompactionBreaker(this.settings.enabled, core.model().contextWindow);
     }
     get isCompacting() {
@@ -69,16 +89,31 @@ export class CompactionController {
             signal,
             customInstructions: instructions,
             onFallback: (reason) => core.log("warn", `summary by prefix continuation failed (${reason}); used a separate request`),
+            onInvalid: (reason) => core.log("warn", `${reason}; kept it after one retry`),
         };
         if (continuation)
             options.continuation = core.cache?.summaryContinuation();
         return options;
     }
-    /** 档一；返回是否裁剪了内容。 */
-    prune() {
-        const branch = this.core.manager.branch();
-        const plan = planPrune(buildProjection(branch).items, { outputDir: this.core.outputDir() });
-        for (const item of plan) {
+    /** 档一参数；无窗口时 undefined。 */
+    prunePolicy() {
+        const budget = this.budget();
+        return budget === undefined ? undefined : prunePolicy(budget, this.pruneConfig.prune);
+    }
+    /**
+     * 档一；`need` = 清到目标还要省多少（undefined = 全部候选）。返回省下的 token 估算（0 = 未裁）。
+     */
+    prune(policy, need) {
+        const core = this.core;
+        const items = buildProjection(core.manager.branch()).items;
+        const isProtected = createProtection({
+            cwd: core.cwd,
+            skillPaths: skillLocations(items),
+            exclude: this.pruneConfig.pruneExclude ?? [],
+            keepInContext: (name) => core.tool(name)?.annotations?.keepInContext === true,
+        });
+        const plan = planPrune(items, { policy, need, outputDir: core.outputDir(), isProtected });
+        for (const item of plan.items) {
             this.core.appendEntry({
                 type: "context_edit",
                 targetId: item.targetId,
@@ -86,23 +121,101 @@ export class CompactionController {
                 reason: "prune",
             });
         }
-        if (plan.length > 0)
+        if (plan.items.length > 0)
             this.core.reloadMessages();
-        return plan.length > 0;
+        return plan.savedTokens;
     }
     /** 阈值检查（档一 → 档二）。失败只记录，不打断 run。 */
     async checkThreshold(signal) {
         if (!this.breaker.autoEnabled || this.compacting || signal.aborted)
             return;
-        const window = this.core.model().contextWindow;
-        const reserve = this.settings.reserveTokens;
+        this.breaker.tick();
+        const policy = this.prunePolicy();
+        const budget = this.budget();
+        if (policy === undefined || budget === undefined)
+            return;
         let tokens = this.estimate().tokens;
-        if (shouldPrune(tokens, window, reserve) && this.prune())
-            tokens = this.estimate().tokens;
-        if (tokens <= window - reserve || !this.breaker.canSummarize())
+        // 缓存已冷（C3）：前缀反正要重写，未到阈值也把候选一次换掉（仍要可省 ≥ clearAtLeast）
+        const cold = this.core.cache?.isCold() ?? false;
+        if (tokens > policy.triggerTokens || cold) {
+            const need = cold ? undefined : tokens - policy.targetTokens;
+            if (this.prune(policy, need) > 0)
+                tokens = this.estimate().tokens;
+        }
+        if (tokens <= budget)
             return;
+        this.breaker.setPrefixOverflow(this.fixedPrefixTokens() > budget);
+        if (!this.breaker.canSummarize())
+            return this.warnBlocked();
         await this.summarize("threshold", signal);
     }
+    /** 回注块（todo、计划、已加载 Skill、最近文件、转录与 outputs 路径；不含文件正文）。 */
+    postCompactBlock() {
+        const core = this.core;
+        const branch = core.manager.branch();
+        return buildPostCompactBlock({
+            branch,
+            cwd: core.cwd,
+            skillPaths: skillLocations(buildProjection(branch).items),
+            transcriptPath: core.manager.file(),
+            outputDir: core.outputDir(),
+        });
+    }
+    /**
+     * PostCompact Hook（C13，不可阻止）：`additionalContext` 作为 `ama.hook_context` 追加在末尾。
+     * 返回最终的压缩后估算。
+     */
+    async runPostCompactHook(trigger, tokensBefore, signal) {
+        const core = this.core;
+        const tokensAfter = this.estimate().tokens;
+        const hook = await core.runHook("PostCompact", { tokensBefore, tokensAfter, trigger: trigger === "manual" ? "manual" : "auto" }, signal);
+        const context = hook?.additionalContext;
+        if (context === undefined || context === "")
+            return tokensAfter;
+        core.appendEntry({
+            type: "custom_message",
+            customType: HOOK_CONTEXT_CUSTOM_TYPE,
+            content: context,
+            display: false,
+        });
+        core.reloadMessages();
+        return this.estimate().tokens;
+    }
+    /** 假设追加了这条 compaction 之后的估算（按投影全量重估）。 */
+    projectedTokens(input) {
+        const branch = this.core.manager.branch();
+        const pending = {
+            ...input,
+            id: "\u0000pending-compaction",
+            parentId: branch.at(-1)?.id ?? null,
+            timestamp: new Date().toISOString(),
+        };
+        const next = [...branch, pending];
+        return estimateProjectedTokens(buildProjection(next).items, next).tokens;
+    }
+    /** 固定前缀（system 节 + 工具表）的估算：摘要压不掉这部分。 */
+    fixedPrefixTokens() {
+        let tokens = 0;
+        for (const { message } of buildProjection(this.core.manager.branch()).items)
+            if (message.role === "system")
+                tokens += estimateMessageTokens(message);
+        return tokens;
+    }
+    /** 熔断挡住自动摘要时告警（同一原因只报一次）。 */
+    warnBlocked() {
+        const reason = this.breaker.blockReason();
+        if (reason === undefined || reason === this.warnedReason)
+            return;
+        this.warnedReason = reason;
+        const text = {
+            tripped: "auto-compaction disabled after repeated summary failures",
+            rapid_refill: "auto-compaction disabled: the context refilled within 3 turns after each of the last 3 compactions",
+            prefix_overflow: "auto-compaction skipped: the system prompt and tool definitions alone exceed the context budget",
+        };
+        const message = text[reason];
+        if (message !== undefined)
+            this.core.log("warn", message);
+    }
     /** 溢出恢复：返回是否应以新 run 重试。 */
     async recoverOverflow(signal) {
         if (!this.settings.enabled)
@@ -136,14 +249,16 @@ export class CompactionController {
         }
         return { retry: true };
     }
-    async compactManual(instructions, signal) {
-        const outcome = await this.summarize("manual", signal, instructions);
+    /** `cutAt`：[RW-B] 以该条目为切点（「摘要到这里」），不按保留预算找切点。 */
+    async compactManual(instructions, signal, cutAt) {
+        const outcome = await this.summarize("manual", signal, instructions, cutAt);
         if (outcome.result === undefined) {
             if (outcome.aborted)
                 throw new AmaError("aborted", "compaction aborted");
             throw new AmaError("compaction_failed", outcome.error ?? "compaction failed");
         }
         this.breaker.reset();
+        this.warnedReason = undefined;
         return outcome.result;
     }
     /** `/tree` 离开分支：换叶子，并为离开的那段写 branch_summary（挂在新叶子下）。 */
@@ -163,7 +278,7 @@ export class CompactionController {
             details: draft.details,
         });
     }
-    async summarize(trigger, signal, instructions) {
+    async summarize(trigger, signal, instructions, cutAt) {
         const core = this.core;
         this.compacting = true;
         core.emit({ type: "compaction_start", trigger });
@@ -202,34 +317,43 @@ export class CompactionController {
         const projection = buildProjection(core.manager.branch());
         const keep = this.keepRecent();
         let plan;
-        for (const budget of [keep, Math.floor(keep / 4), 1]) {
-            plan = prepareCompaction(projection, Math.max(1, budget));
-            if (plan !== undefined)
-                break;
+        if (cutAt !== undefined)
+            plan = prepareCompactionAt(projection, cutAt);
+        else {
+            for (const budget of [keep, Math.floor(keep / 4), 1]) {
+                plan = prepareCompaction(projection, Math.max(1, budget));
+                if (plan !== undefined)
+                    break;
+            }
         }
-        if (plan === undefined) {
-            if (trigger !== "manual")
-                this.breaker.recordSummary(false);
+        // 「nothing to compact」不计失败（C5）
+        if (plan === undefined)
             return fail("nothing to compact");
-        }
         try {
             const options = await this.summarizer(signal, customInstructions, trigger !== "overflow");
             const draft = await runCompaction(plan, options);
             if (signal.aborted)
                 return fail("aborted", true);
+            // 回注（C6）：清单与指针接在摘要末尾，模型看到「摘要 → 回注 → 保留区」
             const entry = {
                 type: "compaction",
-                summary: draft.summary,
+                summary: `${draft.summary}\n\n${this.postCompactBlock()}`,
                 firstKeptEntryId: draft.firstKeptEntryId,
                 tokensBefore,
                 details: draft.details,
             };
             if (draft.usage !== undefined)
                 entry.usage = draft.usage;
+            // 自检（C8）：自动压缩后不比压缩前小 = 失败（不写条目，计入熔断）；手动 /compact 照用户意思写
+            const projected = trigger === "manual" ? 0 : this.projectedTokens(entry);
+            if (projected >= tokensBefore)
+                throw new AmaError("compaction_failed", `compaction did not shrink the context (${tokensBefore} → ${projected} tokens)`);
             core.appendEntry(entry);
             core.reloadMessages();
             this.breaker.recordSummary(true);
-            const tokensAfter = this.estimate().tokens;
+            if (this.breaker.tripped)
+                this.warnBlocked();
+            const tokensAfter = await this.runPostCompactHook(trigger, tokensBefore, signal);
             const result = {
                 summary: draft.summary,
                 firstKeptEntryId: draft.firstKeptEntryId,
@@ -245,6 +369,8 @@ export class CompactionController {
             const aborted = signal.aborted || (error instanceof AmaError && error.code === "aborted");
             if (!aborted)
                 this.breaker.recordSummary(false);
+            if (this.breaker.tripped)
+                this.warnBlocked();
             return fail(error instanceof Error ? error.message : String(error), aborted);
         }
     }

package/dist/agent/session-core.d.ts

@@ -5,6 +5,7 @@
  * `SessionCore` 是 session.ts 交给 session-tools.ts / session-compaction.ts 的内部视图（避免循环 import）。
  */
 import type { WarmingDecisionHandler } from "../ai/cache/types.js";
+import type { CheckpointHooks } from "../checkpoints/types.js";
 import type { Model, ModelThinkingLevel, ProviderRegistryApi } from "../ai/types.js";
 import type { HookDispatcherApi, HookEvent, HookEventPayload, HookOutcome } from "../hooks/types.js";
 import type { PermissionClassifier } from "../permissions/classifier.js";
@@ -15,8 +16,10 @@ import type { SubagentRequest, SubagentResult, ToolDefinition } from "../tools/t
 import type { Agent } from "./agent.js";
 import type { StreamFn } from "./loop.js";
 import type { SessionCacheController } from "./session-cache.js";
+import type { CheckpointBackendFactory } from "../checkpoints/index.js";
+import type { SessionExtensionFactory } from "./session-extensions.js";
 import type { SystemPromptInput } from "./system-prompt.js";
-import type { CacheSettings, CompactionSettings, QueueMode, RetrySettings, SessionEvent } from "./types.js";
+import type { CacheSettings, CompactionSettings, QueueMode, RetrySettings, SessionEvent, SessionLimits } from "./types.js";
 export type PromptExpansion = {
     text: string;
 } | {
@@ -72,6 +75,18 @@ export interface AgentSessionOptions {
     idleTimeoutMs?: number;
     /** 子 Agent 的回合上限（maxTurns）。 */
     maxTurns?: number;
+    /**
+     * [W5-C0] 会话预算（`--max-turns` / `--max-cost` / config `limits.*`）；到限发 `limit_reached`
+     * 并结束 run（实现归 W5-H2 的 limits 扩展，C0 只透传）。
+     */
+    limits?: SessionLimits;
+    /**
+     * [W5-C0] 会话扩展的工厂（session-extensions.ts）：每个会话实例（含 fork 与 task 子会话）各调一次；
+     * 组装根从 `cli/compose-extensions.ts` 的表取得。缺省无扩展。
+     */
+    extensions?: readonly SessionExtensionFactory[];
+    /** [W5-C0] 回退模型 `provider/model[@channel]`（config `fallbackModel`，实现归 W5-H2）。 */
+    fallbackModel?: string;
     /** 子 Agent 并发上限，缺省 4；`false` 关闭 spawnSubagent。 */
     subagents?: {
         maxConcurrent?: number;
@@ -82,6 +97,15 @@ export interface AgentSessionOptions {
     cache?: Partial<CacheSettings>;
     /** [W3-C1b] 宿主 `cache.onWarmingDecision` 的处理器（每次保温前现取）。 */
     warmingDecider?(): WarmingDecisionHandler | undefined;
+    /**
+     * [RW-B] 检查点后端工厂（rewind-plan §2）：只在主会话（depth 0）且会话有目录时调用；返回
+     * undefined = 不建检查点（`checkpoints.mode: "off"`）。
+     */
+    checkpoints?: CheckpointBackendFactory;
+    /** [RW-B] task 子会话：父会话的检查点钩子（编辑记到父会话当前回合）。 */
+    checkpointHooks?: CheckpointHooks;
+    /** [RW-B] 中断即撤回（config `ui.restoreOnCancel`，缺省 true）。 */
+    restoreOnCancel?: boolean;
     log?(level: "debug" | "info" | "warn" | "error", message: string): void;
 }
 export interface SessionCore {
@@ -110,6 +134,8 @@ export interface SessionCore {
     /** Hook 返回 continue:false 时记下，finishTurn 据此结束 run。 */
     requestStop(reason: string | undefined): void;
     spawnSubagent(request: SubagentRequest): Promise<SubagentResult>;
+    /** [RW-B] ToolContext.checkpoint：本会话的检查点钩子（无则 undefined）。 */
+    checkpointHooks?(): CheckpointHooks | undefined;
     /** auto 权限模式的分类器（懒建，会话内缓存判定）。 */
     autoClassifier(): PermissionClassifier;
     log(level: "debug" | "info" | "warn" | "error", message: string): void;

package/dist/agent/session-extensions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 会话扩展点（docs/wave5-plan.md §10.1，D30）。[W5-C0]
+ *
+ * 第五波的遥测、计划、提醒、图片预算、预算上限等都以扩展实现在各自文件，`session.ts` 只留调用点：
+ *
+ * | 钩子             | 调用点                                                                                  |
+ * | ---------------- | --------------------------------------------------------------------------------------- |
+ * | `beforePrompts`  | `runPrompt` 组装好 prompts（用户消息 + Hook additionalContext）、阈值压缩与检查点之后， |
+ * |                  | 按表顺序调用；返回的消息**追加在 prompts 之后**（只能是 custom_message，不得改已有消息） |
+ * | `wrapStream`     | 会话构造时按表顺序包流：表中靠前的离协议层近；缓存控制器始终在最外层（看到最终请求）   |
+ * | `onEvent`        | 每个 `SessionEvent` 广播给订阅者之后                                                    |
+ * | `onAgentSettled` | `agent_settled` 发出之后、本周期结束（`waitForIdle` resolve）之前 await                  |
+ * | `contributeStats`| `getStats()` 末尾，就地补 `SessionStats` 的字段                                         |
+ * | `dispose`        | 会话 dispose 时                                                                         |
+ *
+ * 约束：
+ * - **缓存前缀**（design §9.1）：扩展不得改 system 节与工具表、不得改已有消息；只能在尾部追加。
+ * - 选项里放的是**工厂**（`SessionExtensionFactory`），每个会话实例（主会话、fork、task 子会话）
+ *   各调一次得到自己的扩展实例；工厂按 `ctx.core.depth` 决定子会话要不要装（返回 undefined 即不装）。
+ *   工厂在会话构造中途调用：只可读 `core.options / depth / cwd / manager`，不要 emit 或请求模型。
+ * - 钩子抛错不影响会话：同步钩子的异常记 warn 日志后忽略；`beforePrompts` / `onAgentSettled`
+ *   的异常同样记日志、按「无追加」处理。
+ * - `onAgentSettled` 不要等待人工输入（计划审批等）：需要等待的流程自行异步进行，之后用
+ *   `prompt / followUp` 开新回合。
+ */
+import type { AgentMessage } from "../session/types.js";
+import type { StreamFn } from "./loop.js";
+import type { SessionCore } from "./session-core.js";
+import type { SessionEvent, SessionStats } from "./types.js";
+export interface SessionExtensionContext {
+    /** appendEntry / reloadMessages / emit / manager / model() / cache / options / depth。 */
+    readonly core: SessionCore;
+}
+export interface SessionExtension {
+    readonly id: string;
+    /** 新回合 prompts 投递前；返回要追加在 prompts 之后的消息（只能 custom_message）。 */
+    beforePrompts?(ctx: SessionExtensionContext, prompts: readonly AgentMessage[]): Promise<AgentMessage[]> | AgentMessage[];
+    wrapStream?(stream: StreamFn): StreamFn;
+    onEvent?(event: SessionEvent): void;
+    onAgentSettled?(ctx: SessionExtensionContext): Promise<void> | void;
+    contributeStats?(stats: SessionStats): void;
+    dispose?(): void;
+}
+/** 每个会话实例调一次；返回 undefined = 本会话不装（例如子会话）。 */
+export type SessionExtensionFactory = (ctx: SessionExtensionContext) => SessionExtension | undefined;
+/** 会话持有的扩展集合：把各钩子的遍历、顺序与异常隔离集中在这里，session.ts 只调一行。 */
+export declare class SessionExtensions {
+    private readonly list;
+    private readonly ctx;
+    constructor(core: SessionCore, factories: readonly SessionExtensionFactory[] | undefined);
+    get size(): number;
+    ids(): string[];
+    /** 表中靠前的离协议层近；调用方再把结果交给缓存控制器包在最外层。 */
+    wrapStream(stream: StreamFn): StreamFn;
+    beforePrompts(prompts: readonly AgentMessage[]): Promise<AgentMessage[]>;
+    onEvent(event: SessionEvent): void;
+    onAgentSettled(): Promise<void>;
+    contributeStats(stats: SessionStats): SessionStats;
+    dispose(): void;
+    private warn;
+}

package/dist/agent/session-extensions.js

@@ -0,0 +1,129 @@
+/**
+ * 会话扩展点（docs/wave5-plan.md §10.1，D30）。[W5-C0]
+ *
+ * 第五波的遥测、计划、提醒、图片预算、预算上限等都以扩展实现在各自文件，`session.ts` 只留调用点：
+ *
+ * | 钩子             | 调用点                                                                                  |
+ * | ---------------- | --------------------------------------------------------------------------------------- |
+ * | `beforePrompts`  | `runPrompt` 组装好 prompts（用户消息 + Hook additionalContext）、阈值压缩与检查点之后， |
+ * |                  | 按表顺序调用；返回的消息**追加在 prompts 之后**（只能是 custom_message，不得改已有消息） |
+ * | `wrapStream`     | 会话构造时按表顺序包流：表中靠前的离协议层近；缓存控制器始终在最外层（看到最终请求）   |
+ * | `onEvent`        | 每个 `SessionEvent` 广播给订阅者之后                                                    |
+ * | `onAgentSettled` | `agent_settled` 发出之后、本周期结束（`waitForIdle` resolve）之前 await                  |
+ * | `contributeStats`| `getStats()` 末尾，就地补 `SessionStats` 的字段                                         |
+ * | `dispose`        | 会话 dispose 时                                                                         |
+ *
+ * 约束：
+ * - **缓存前缀**（design §9.1）：扩展不得改 system 节与工具表、不得改已有消息；只能在尾部追加。
+ * - 选项里放的是**工厂**（`SessionExtensionFactory`），每个会话实例（主会话、fork、task 子会话）
+ *   各调一次得到自己的扩展实例；工厂按 `ctx.core.depth` 决定子会话要不要装（返回 undefined 即不装）。
+ *   工厂在会话构造中途调用：只可读 `core.options / depth / cwd / manager`，不要 emit 或请求模型。
+ * - 钩子抛错不影响会话：同步钩子的异常记 warn 日志后忽略；`beforePrompts` / `onAgentSettled`
+ *   的异常同样记日志、按「无追加」处理。
+ * - `onAgentSettled` 不要等待人工输入（计划审批等）：需要等待的流程自行异步进行，之后用
+ *   `prompt / followUp` 开新回合。
+ */
+/** 会话持有的扩展集合：把各钩子的遍历、顺序与异常隔离集中在这里，session.ts 只调一行。 */
+export class SessionExtensions {
+    list;
+    ctx;
+    constructor(core, factories) {
+        this.ctx = { core };
+        const list = [];
+        for (const factory of factories ?? []) {
+            const extension = guard(core.log.bind(core), "factory", () => factory(this.ctx));
+            if (extension !== undefined)
+                list.push(extension);
+        }
+        this.list = list;
+    }
+    get size() {
+        return this.list.length;
+    }
+    ids() {
+        return this.list.map((extension) => extension.id);
+    }
+    /** 表中靠前的离协议层近；调用方再把结果交给缓存控制器包在最外层。 */
+    wrapStream(stream) {
+        let wrapped = stream;
+        for (const extension of this.list) {
+            const next = extension.wrapStream?.(wrapped);
+            if (next !== undefined)
+                wrapped = next;
+        }
+        return wrapped;
+    }
+    async beforePrompts(prompts) {
+        const added = [];
+        for (const extension of this.list) {
+            if (extension.beforePrompts === undefined)
+                continue;
+            try {
+                added.push(...(await extension.beforePrompts(this.ctx, [...prompts, ...added])));
+            }
+            catch (error) {
+                this.warn(extension, "beforePrompts", error);
+            }
+        }
+        return added;
+    }
+    onEvent(event) {
+        for (const extension of this.list) {
+            if (extension.onEvent === undefined)
+                continue;
+            try {
+                extension.onEvent(event);
+            }
+            catch (error) {
+                this.warn(extension, "onEvent", error);
+            }
+        }
+    }
+    async onAgentSettled() {
+        for (const extension of this.list) {
+            if (extension.onAgentSettled === undefined)
+                continue;
+            try {
+                await extension.onAgentSettled(this.ctx);
+            }
+            catch (error) {
+                this.warn(extension, "onAgentSettled", error);
+            }
+        }
+    }
+    contributeStats(stats) {
+        for (const extension of this.list) {
+            if (extension.contributeStats === undefined)
+                continue;
+            try {
+                extension.contributeStats(stats);
+            }
+            catch (error) {
+                this.warn(extension, "contributeStats", error);
+            }
+        }
+        return stats;
+    }
+    dispose() {
+        for (const extension of this.list) {
+            try {
+                extension.dispose?.();
+            }
+            catch (error) {
+                this.warn(extension, "dispose", error);
+            }
+        }
+    }
+    warn(extension, hook, error) {
+        this.ctx.core.log("warn", `extension ${extension.id} failed in ${hook}: ${String(error)}`);
+    }
+}
+function guard(log, hook, run) {
+    try {
+        return run();
+    }
+    catch (error) {
+        log("warn", `extension ${hook} failed: ${String(error)}`);
+        return undefined;
+    }
+}

package/dist/agent/session-images.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 图片预算扩展（docs/wave5-plan.md §4、D11、D30）。[W5-I]
+ *
+ * 每次请求前检查图片总量：超预算（或有超单图上限的旧图、> 20 张时的大图）就按
+ * `planImageBudget` 把旧图换成占位文本，写成 `context_edit{reason:"image_budget"}` 持久化、
+ * 重建上下文，并通知缓存控制器「下一条是重置点」（前缀只在这里变一次，之后稳定）。
+ *
+ * 两个检查点：
+ * - `beforePrompts`：新回合投递前；本回合提示里的附件计入总量但不降级；
+ * - `wrapStream`：回合内（工具结果里新读的图）每次 `turn` 请求前；已发出的消息都已落盘时才降级，
+ *   并把本次请求的转录换成降级后的（就地改 context，缓存控制器看到的也是降级后的请求）。
+ *
+ * 模型不收图片时不处理：`normalizeContext` 已把图片换成占位（ai/context.ts）。
+ */
+import { type ImageLimits } from "../ai/image-limits.js";
+import type { Model } from "../ai/types.js";
+import type { SessionCore } from "./session-core.js";
+import type { SessionExtension } from "./session-extensions.js";
+export interface ImageBudgetExtensionDeps {
+    /** 测试注入：按模型的上限。缺省 `imageLimits(model)`。 */
+    limits?(model: Model): ImageLimits;
+}
+export declare function createImageBudgetExtension(core: SessionCore, deps?: ImageBudgetExtensionDeps): SessionExtension;