@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/extensions/repeat-call.hook.ts

@@ -0,0 +1,77 @@
+/**
+ * 重复工具调用提醒，**作为扩展接在 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,
+  turnStateOf,
+} from '../hooks/turn-hook.types.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import {
+  createRepeatCallChain,
+  type RepeatCallChain,
+} from '../turn/loop-reminder.js';
+
+/**
+ * 记账链。**order 取最小**：链要看到最接近模型原始输出的那份入参，别的
+ * `preToolUse` 插件改写过之后再记，会把「同一次调用」判成换了参数。
+ */
+export const REPEAT_CALL_HOOK_META: TurnHookMeta = {
+  name: 'repeat-call-reminder',
+  point: 'preToolUse',
+  order: 10,
+  onError: 'open',
+};
+
+export class RepeatCallHook implements TurnHookImpl {
+  constructor(private readonly tools: ToolRegistry) {}
+
+  preToolUse(
+    ctx: TurnContext,
+    toolName: string,
+    input: unknown
+  ): Promise<PreToolUseResult> {
+    // 链住在本轮的状态槽里：**一个 tick 一条**（见 `createRepeatCallChain`），
+    // 生命周期跟着 `TurnRun` 走，插件自己不持有任何跨轮状态。
+    const chain = turnStateOf<RepeatCallChain>(
+      ctx,
+      'repeat-call-reminder',
+      () =>
+        // 「哪些工具对链透明」由工具自己声明（`ToolMeta.accounting`）——插件同样
+        // 不持有任何具体工具名，加一个新的记账工具零改动。
+        createRepeatCallChain({ untracked: this.tools.accountingToolNames() })
+    );
+    const advice = chain.note(toolName, input);
+    // **只提醒，不阻止**：模型有时重复调用是对的（轮询一个还没就绪的东西），
+    // 拦错了它没有申辩余地；提醒错了它可以无视。
+    return Promise.resolve({
+      action: 'continue',
+      ...(advice ? { systemNote: advice } : {}),
+    });
+  }
+}
+
+/** 把重复调用提醒挂到注册表上（runtime 的缺省扩展，宿主可以不挂）。 */
+export function registerRepeatCallHook(
+  hooks: TurnHookRegistry,
+  tools: ToolRegistry
+): void {
+  hooks.register(REPEAT_CALL_HOOK_META, new RepeatCallHook(tools));
+}

package/src/hooks/index.ts

@@ -0,0 +1,19 @@
+export { TurnHookRegistry } from './turn-hook.registry.js';
+export {
+  type BeforeTurnResult,
+  HOOK_TIMEOUT_MS,
+  type ObservePhase,
+  ONERROR_HONORED_POINTS,
+  type PreToolUseDecision,
+  type PreToolUseResult,
+  type ReviewOutputResult,
+  SINGLETON_POINTS,
+  type ToolOutcome,
+  TURN_HOOK_POINTS,
+  type TurnContext,
+  type TurnHookAt,
+  type TurnHookImpl,
+  type TurnHookMeta,
+  type TurnHookPoint,
+  turnStateOf,
+} from './turn-hook.types.js';

package/src/hooks/turn-hook.registry.ts

@@ -0,0 +1,307 @@
+import { type LoggerFactory, silentLogger } from '../ports/logger.js';
+import type {
+  ContextPressure,
+  ContextRelief,
+} from '../turn/context-pressure.js';
+import {
+  type BeforeTurnResult,
+  HOOK_TIMEOUT_MS,
+  type ObservePhase,
+  ONERROR_HONORED_POINTS,
+  type PreToolUseDecision,
+  type PreToolUseResult,
+  type ReviewOutputResult,
+  SINGLETON_POINTS,
+  type ToolOutcome,
+  type TurnContext,
+  type TurnHookAt,
+  type TurnHookImpl,
+  type TurnHookMeta,
+  type TurnHookPoint,
+} from './turn-hook.types.js';
+
+interface Entry {
+  meta: TurnHookMeta;
+  impl: TurnHookImpl;
+}
+
+const TOOL_POINTS: readonly TurnHookPoint[] = ['preToolUse', 'postToolUse'];
+
+/**
+ * 轮钩子注册表。搬自 agent-base：去掉 Nest 的扫描，宿主显式 `register`（Nest 适配包负责
+ * 把装饰器接过来）。同一 point 上按 `order` 升序串行；order 相同按注册顺序。
+ */
+export class TurnHookRegistry {
+  private readonly logger: ReturnType<LoggerFactory>;
+  private readonly entries: Entry[] = [];
+  private readonly names = new Set<string>();
+
+  constructor(options: { logger?: LoggerFactory } = {}) {
+    this.logger = (options.logger ?? silentLogger)('TurnHookRegistry');
+  }
+
+  /** 登记一个钩子。名字重复、没实现那个 point、违反单例 / onError 约束 → 抛。 */
+  register(meta: TurnHookMeta, impl: TurnHookImpl): void {
+    this.add(meta, impl);
+    // 稳定排序：order 相同的保持注册顺序。
+    this.entries.sort((a, b) => a.meta.order - b.meta.order);
+  }
+
+  private add(meta: TurnHookMeta, impl: TurnHookImpl): void {
+    if (this.names.has(meta.name)) {
+      throw new Error(`duplicate hook name '${meta.name}'`);
+    }
+    if (typeof impl?.[meta.point] !== 'function') {
+      throw new Error(`hook '${meta.name}' must implement ${meta.point}()`);
+    }
+    if (meta.tools && !TOOL_POINTS.includes(meta.point)) {
+      throw new Error(
+        `hook '${meta.name}': tools[] only valid on preToolUse/postToolUse`
+      );
+    }
+    if (
+      meta.onError === 'closed' &&
+      !ONERROR_HONORED_POINTS.includes(meta.point)
+    ) {
+      throw new Error(
+        `hook '${meta.name}': onError 'closed' is meaningless on point ${meta.point} (nothing to hold back)`
+      );
+    }
+    if (
+      SINGLETON_POINTS.includes(meta.point) &&
+      this.entries.some(e => e.meta.point === meta.point)
+    ) {
+      throw new Error(
+        `hook '${meta.name}': ${meta.point} allows at most one implementation`
+      );
+    }
+    this.names.add(meta.name);
+    this.entries.push({ meta, impl });
+  }
+
+  /**
+   * 取某个 point 上的 hook，**并把 impl 收窄成「那个方法一定在」**（见
+   * `TurnHookAt`）。
+   *
+   * 本文件唯一的类型断言就在这里：准入条件在 `register` 里验过，而 `entries`
+   * 是一张异构表（六个 point 混在一起），读出来时类型系统没办法自己重建那条
+   * 不变量。断言收在这一处，六个 run 方法就都不必写 `!`。
+   */
+  private of<P extends TurnHookPoint>(
+    point: P
+  ): Array<{ meta: TurnHookMeta; impl: TurnHookAt<P> }> {
+    return this.entries.filter(e => e.meta.point === point) as Array<{
+      meta: TurnHookMeta;
+      impl: TurnHookAt<P>;
+    }>;
+  }
+
+  /**
+   * Promise.race 在调用当下就同步给 fn() 和 timeout promise 各挂上
+   * then/catch handler，故落败的一方（超时后 fn() 才 reject，或 fn()
+   * 先行完成后 timeout 定时器仍会触发但已无人等待）都不会产生
+   * unhandled rejection —— 无需额外 `.catch()`。finally 保证
+   * clearTimeout 在成功/hook 抛错/超时三条路径下都执行，避免定时器泄漏。
+   */
+  private async withTimeout<T>(
+    meta: TurnHookMeta,
+    fn: () => Promise<T>
+  ): Promise<T> {
+    // 超时**按 hook 声明**（缺省 5s）：慢的那个自己声明一个大的，而不是把
+    // 默认值抬上去让其余每个点的保护一起松掉（见 `TurnHookMeta.timeoutMs`）。
+    const limit = meta.timeoutMs ?? HOOK_TIMEOUT_MS;
+    let timer: NodeJS.Timeout | undefined;
+    try {
+      return await Promise.race([
+        fn(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`hook timed out after ${limit}ms`)),
+            limit
+          );
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  async runBeforeTurn(ctx: TurnContext): Promise<BeforeTurnResult> {
+    for (const { meta, impl } of this.of('beforeTurn')) {
+      let res: BeforeTurnResult;
+      try {
+        res = await this.withTimeout(meta, () => impl.beforeTurn(ctx));
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+        if (meta.onError === 'closed') {
+          return { action: 'reject', reply: '系统繁忙，请稍后再试。' };
+        }
+        continue;
+      }
+      if (res.action === 'reject') {
+        // 断言：reject 不带 reply 会挂死 SSE 流。这是显式抛错（而非吞掉
+        // 继续下一个 hook）—— 配错的 hook 不该被 onError:'open' 悄悄放行，
+        // 因为放行的后果是流挂死，比让本轮直接报错更糟。
+        if (!res.reply) {
+          throw new Error(
+            `hook '${meta.name}': reject must carry reply text (empty reply hangs the SSE stream)`
+          );
+        }
+        return res;
+      }
+    }
+    return { action: 'continue' };
+  }
+
+  async runTransformContext(ctx: TurnContext): Promise<string[]> {
+    const appended: string[] = [];
+    for (const { meta, impl } of this.of('transformContext')) {
+      try {
+        const res = await this.withTimeout(meta, () =>
+          impl.transformContext(ctx)
+        );
+        if (res.appendSystem) appended.push(res.appendSystem);
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+      }
+    }
+    return appended;
+  }
+
+  async runReviewOutput(
+    ctx: TurnContext,
+    text: string
+  ): Promise<ReviewOutputResult> {
+    let current = text;
+    let changed = false;
+    for (const { meta, impl } of this.of('reviewOutput')) {
+      try {
+        const res = await this.withTimeout(meta, () =>
+          impl.reviewOutput(ctx, current)
+        );
+        if (res.action === 'block') return res;
+        if (res.action === 'rewrite') {
+          current = res.text;
+          changed = true;
+        }
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+        if (meta.onError === 'closed') {
+          return { action: 'block', reply: '系统繁忙，请稍后再试。' };
+        }
+      }
+    }
+    // 用显式 changed 标记而非 `current === text`：某个 hook 若把文本改写成
+    // 恰好与原文相等的新字符串（例如脱敏后又还原），=== 会误判成「没改过」
+    // 而把 rewrite 事实上退化成 keep（丢事件/丢审计，虽结果字节相同但语义
+    // 不对）。
+    return changed ? { action: 'rewrite', text: current } : { action: 'keep' };
+  }
+
+  async runPreToolUse(
+    ctx: TurnContext,
+    toolName: string,
+    input: unknown
+  ): Promise<PreToolUseDecision> {
+    let current = input;
+    let changed = false;
+    // 各 hook 要追加给模型的话，按 `order` 攒起来（entries 已排过序）。
+    const notes: string[] = [];
+    for (const { meta, impl } of this.of('preToolUse')) {
+      if (meta.tools && !meta.tools.includes(toolName)) continue;
+      try {
+        const res = await this.withTimeout(meta, () =>
+          impl.preToolUse(ctx, toolName, current)
+        );
+        if (res.action === 'deny') {
+          // **拒绝也要把已攒下的话带走**：拦下这次调用的是另一个 hook，而先前
+          // 那句提醒说的仍是这一次调用（被拒绝的调用一样计数，那正是判据）。
+          // 丢在这里的话，症状是「偏偏在被拦的那次不提醒」。
+          return withNotes(res, notes);
+        }
+        if (res.systemNote) notes.push(res.systemNote);
+        if (res.action === 'modifyInput') {
+          current = res.input;
+          changed = true;
+        }
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+        if (meta.onError === 'closed') {
+          return withNotes({ action: 'deny', reason: 'hook failure' }, notes);
+        }
+      }
+    }
+    // 同上：显式 changed 标记，防止「改成引用不同但内容恰好 === 的新对象」
+    // 或「原地改了同一个对象引用」两种场景被 === 误判。preToolUse 尤其容易
+    // 踩后者——hook 拿到的 current 是同一个可变对象引用，若原地 mutate 而不
+    // 返回新引用，`current === input` 恒真，会把已生效的 modifyInput 错报
+    // 成 continue（下游若按 action 分支决定要不要重新校验/审计，会被漏过）。
+    return withNotes(
+      changed
+        ? { action: 'modifyInput', input: current }
+        : { action: 'continue' },
+      notes
+    );
+  }
+
+  async runPostToolUse(
+    ctx: TurnContext,
+    toolName: string,
+    outcome: ToolOutcome,
+    toolCallId: string
+  ): Promise<void> {
+    for (const { meta, impl } of this.of('postToolUse')) {
+      if (meta.tools && !meta.tools.includes(toolName)) continue;
+      try {
+        await this.withTimeout(meta, () =>
+          impl.postToolUse(ctx, toolName, outcome, toolCallId)
+        );
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+      }
+    }
+  }
+
+  /**
+   * 调模型前腾空间。**单例点**（注册期保证至多一个实现），故这里的循环最多转
+   * 一圈；没有实现方时返回 `null` —— 与「不用腾」同一个值，内核两条路径的处理
+   * 本来就一样（阈值路径继续发请求，overflow 路径把原始错误原样抛出）。
+   *
+   * `onError: 'closed'` 在这里的含义是「腾不出来就别再发请求了」：把异常继续
+   * 往上抛，由内核的 catch 收成一轮 failed。缺省 `'open'` 则当作「没腾出来」。
+   */
+  async runBeforeModelCall(
+    ctx: TurnContext,
+    pressure: ContextPressure
+  ): Promise<ContextRelief | null> {
+    for (const { meta, impl } of this.of('beforeModelCall')) {
+      try {
+        return await this.withTimeout(meta, () =>
+          impl.beforeModelCall(ctx, pressure)
+        );
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+        if (meta.onError === 'closed') throw err;
+      }
+    }
+    return null;
+  }
+
+  async emit(ctx: TurnContext, phase: ObservePhase): Promise<void> {
+    for (const { meta, impl } of this.of('observe')) {
+      try {
+        await this.withTimeout(meta, () => impl.observe(ctx, phase));
+      } catch (err) {
+        this.logger.warn(`hook '${meta.name}' failed: ${String(err)}`);
+      }
+    }
+  }
+}
+
+/**
+ * 把攒下的 `systemNote` 合成一条挂到决策上。多个 hook 各说一句时**合成一条**：
+ * 它们描述的是同一次调用，分成两条只会在同一份工具结果后面并排出现两段话。
+ */
+function withNotes(res: PreToolUseResult, notes: string[]): PreToolUseDecision {
+  return notes.length > 0 ? { ...res, systemNote: notes.join('\n\n') } : res;
+}

package/src/hooks/turn-hook.types.ts

@@ -0,0 +1,210 @@
+import type { AgentExtensions } from '../agent-extensions.js';
+import type {
+  ContextPressure,
+  ContextRelief,
+} from '../turn/context-pressure.js';
+
+export const TURN_HOOK_POINTS = [
+  'beforeTurn',
+  'transformContext',
+  'reviewOutput',
+  'observe',
+  'preToolUse',
+  'postToolUse',
+  'beforeModelCall',
+] as const;
+export type TurnHookPoint = (typeof TURN_HOOK_POINTS)[number];
+
+/**
+ * **单例 point**：注册期校验至多一个实现，多于一个直接抛。
+ *
+ * `beforeModelCall` 要替换 `messages` 的头部，而「两个插件先后替换头部」的语义
+ * 定义不出来——第二个看到的已经不是原始历史，它算出的切点对不上任何一段真实
+ * 前缀。与其定一套顺序规则让人去猜，不如在注册期拒绝。
+ */
+export const SINGLETON_POINTS: readonly TurnHookPoint[] = ['beforeModelCall'];
+
+/**
+ * `onError` 真正被消费的 point。**其余点上声明 `'closed'` 会被注册期拒绝**。
+ *
+ * 判据是「这个点崩了之后，还有没有一个『拦下来』的分支可走」：门禁类（放行/
+ * 拒绝）有，观测类（observe/postToolUse）与注入类（transformContext）没有——
+ * 后者失败的唯一可能反应就是少注入一段文本，此时 `'closed'` 是一句**声明了却
+ * 不生效**的话，而那正是本仓最不想留的那种静默。
+ */
+export const ONERROR_HONORED_POINTS: readonly TurnHookPoint[] = [
+  'beforeTurn',
+  'reviewOutput',
+  'preToolUse',
+  'beforeModelCall',
+];
+
+export interface TurnHookMeta {
+  name: string;
+  point: TurnHookPoint;
+  /** 升序串行。 */
+  order: number;
+  /** 仅 preToolUse/postToolUse 可设：限定作用的工具名。 */
+  tools?: readonly string[];
+  /** 'open' = 崩了当 no-op（默认）；鉴权类必须 'closed'。 */
+  onError: 'open' | 'closed';
+  /**
+   * 这个 hook 的超时，缺省 `HOOK_TIMEOUT_MS`（5s）。
+   *
+   * **给它一个逃生口，而不是把默认值调大**：5s 对门禁/观测类是合适的保护，
+   * 而 `beforeModelCall` 的实现要跑一次完整的 LLM 调用（压缩摘要，分钟级）。
+   * 把默认值抬到分钟级，等于让其余每个点的超时保护一起松掉——那些点上一个
+   * 卡死的 hook 会把整轮对话拖住，正是这道保护要防的事。**慢的那个自己声明。**
+   */
+  timeoutMs?: number;
+}
+
+export interface TurnContext {
+  streamId: string;
+  runId: string;
+  /** 本轮跑在哪个会话上——往它的 inbox 回投（`todo-settle.hook.ts`）要用。 */
+  sessionId: string;
+  agentId: string;
+  /** 宿主经 `AgentExtensions` 加的 agent 字段（如跑的是哪种形式的哪一个）。 */
+  agent: AgentExtensions;
+  userId: string | null;
+  depth: number;
+  /**
+   * 本轮 drain 到的消息（只露 `metadata`）——「这一轮是被什么叫起来的」。
+   *
+   * 内核在首次 drain 之后填进来，之前是空数组；插件按 `metadata.kind` 分辨
+   * 「这一轮是在回应平台自己插的提醒」（防止一条提醒催出下一条）。**只给
+   * metadata 不给正文**：正文是用户的话，观测类插件不该顺手读到它。
+   */
+  inbound: Array<{ metadata?: Record<string, unknown> }>;
+  /**
+   * **插件的 per-turn 状态槽**，键用插件自己的 `name`（取用见 `turnStateOf`）。
+   *
+   * 这个 Map 是 `TurnRun` 的一个字段，生命周期跟着那个对象走——插件本身是单例
+   * provider，自己攒 `Map<runId, T>` 就要在终态里记得清理，而那条路要三个 phase
+   * 全覆盖、漏一个就漏一类会话（且症状是内存慢慢涨，没有人会看见）。这里**结构上
+   * 不可能泄漏**。
+   */
+  turnState: Map<string, unknown>;
+}
+
+/**
+ * 取（没有就建）本插件在这一轮的状态。
+ *
+ * 断言收在这一处：`turnState` 是一张异构表（各插件的状态混在一起），读出来时
+ * 类型系统重建不出「这个键上放的是 T」——同 `TurnHookAt` 那条理由。**键必须用
+ * 插件自己的 `name`**（registry 保证全局唯一），别用点名或类型名。
+ */
+export function turnStateOf<T>(
+  ctx: TurnContext,
+  key: string,
+  create: () => T
+): T {
+  const existing = ctx.turnState.get(key);
+  if (existing !== undefined) return existing as T;
+  const created = create();
+  ctx.turnState.set(key, created);
+  return created;
+}
+
+/**
+ * beforeTurn 返回 reject 时 **必须** 带 reply 文案 —— 否则 SSE 流会挂死
+ * （smart-property 的 human-takeover-gate 踩过，它因此只敢在微信渠道启用）。
+ * registry 层有断言强制。
+ */
+export type BeforeTurnResult =
+  { action: 'continue' } | { action: 'reject'; reply: string };
+
+export type ReviewOutputResult =
+  | { action: 'keep' }
+  | { action: 'rewrite'; text: string }
+  | { action: 'block'; reply: string };
+
+/**
+ * 一次工具调用的结果切面，交给 `postToolUse`。
+ *
+ * **`output` 是三处同源的那份文本**（SSE 事件 / 落库 part / 模型上下文），不是
+ * 工具内部的结构化返回值——需要程序判据的读 `ref`，别从这段文本里抠（它是随时
+ * 会改的文案）。`isError` 与落库用的是同一个判据（`ToolRegistry.didFail`，
+ * 两层信封都看），观测方因此不会看到一个与界面上颜色相反的成败。
+ */
+export interface ToolOutcome {
+  output: string;
+  isError: boolean;
+  ref?: Record<string, unknown>;
+}
+
+/**
+ * `preToolUse` 的产出。
+ *
+ * `systemNote` = 平台要针对**这一次调用**追加给模型的一句话（当前唯一来源：
+ * 重复调用提醒）。内核把它放进那次 tool-result part 的 `systemNote` 字段，
+ * 投影期才拼进文本——**插件只决定注入什么，不决定怎么落库**。
+ *
+ * 挂在这里而不是另开一个步末的注入点，是因为**归属**：劝告说的就是这一次调用，
+ * 挂在它的结果上，一步里多个调用各自撞线时不必合成一条，也不需要「让提醒的 seq
+ * 落在它引发的那段文字之前」那套切段规程。
+ */
+export type PreToolUseResult =
+  | { action: 'continue'; systemNote?: string }
+  | { action: 'modifyInput'; input: unknown; systemNote?: string }
+  | { action: 'deny'; reason: string };
+
+/**
+ * registry 把各 hook 的产出聚合之后交给内核的那份。
+ *
+ * 与 `PreToolUseResult` 的唯一差别是 **deny 也可能带 `systemNote`**：拦下这次
+ * 调用的是某个 hook，而先前另一个 hook 攒的那句提醒说的仍是这一次调用。单个
+ * hook 的 deny 不必自己带（拒绝理由已经进了结果正文）。
+ */
+export type PreToolUseDecision = PreToolUseResult & { systemNote?: string };
+
+export type ObservePhase = 'started' | 'rejected' | 'replied' | 'failed';
+
+export interface TurnHookImpl {
+  beforeTurn?(ctx: TurnContext): Promise<BeforeTurnResult>;
+  transformContext?(ctx: TurnContext): Promise<{ appendSystem?: string }>;
+  reviewOutput?(ctx: TurnContext, text: string): Promise<ReviewOutputResult>;
+  observe?(ctx: TurnContext, phase: ObservePhase): Promise<void>;
+  preToolUse?(
+    ctx: TurnContext,
+    toolName: string,
+    input: unknown
+  ): Promise<PreToolUseResult>;
+  /**
+   * `toolCallId` 放在最后、不进 `ToolOutcome`：outcome 会被原样铺进事件与落库
+   * part，多一个键就多落一份。
+   */
+  postToolUse?(
+    ctx: TurnContext,
+    toolName: string,
+    outcome: ToolOutcome,
+    toolCallId: string
+  ): Promise<void>;
+  /**
+   * 调模型前腾空间。返回 `null` = 不用动。**至多一个实现**（见 `SINGLETON_POINTS`）。
+   *
+   * 内核只测压与替换头部；「阈值多少、模型容量多大、腾出来的是什么」全在实现方。
+   * 两条调用路径的差别不许合并（阈值路径的 null = 不用腾；`pressure.overflowed`
+   * 路径的 null = 腾不出来，把 provider 的原始错误原样抛出）。
+   */
+  beforeModelCall?(
+    ctx: TurnContext,
+    pressure: ContextPressure
+  ): Promise<ContextRelief | null>;
+}
+
+/**
+ * 「注册在 point P 上」的 impl 视图：P 那个方法一定在。
+ *
+ * 注册期唯一的准入条件就是 `typeof impl[meta.point] === 'function'`（见
+ * `TurnHookRegistry.register`），但 `TurnHookImpl` 的成员全是可选的，类型系统
+ * 重建不出这条已经验过的不变量——六个 run 方法因此各写过一个 `impl.xxx!(…)`。
+ * `!` 的问题不在于它丑：它**不检查过滤出来的 point 与调用的方法是不是同一个**，
+ * `of('observe')` 的循环里写 `impl.beforeTurn!(ctx)` 一样编译通过，要到运行时
+ * 才炸。收窄成这个类型之后，那种错配是编译错误。
+ */
+export type TurnHookAt<P extends TurnHookPoint> = TurnHookImpl &
+  Required<Pick<TurnHookImpl, P>>;
+
+export const HOOK_TIMEOUT_MS = 5_000;

package/src/images/byte-cache.ts

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+
+import type { ImageSource } from '../ports/image-source.js';
+
+/** 递送用的字节：带上了 sha256（缓存键）。 */
+export interface LoadedImage {
+  data: Uint8Array;
+  contentType: string;
+  contentHash: string;
+}
+
+/** 进程内字节缓存的缺省上限。 */
+export const DEFAULT_BYTE_CACHE_LIMIT = 256 * 1024 * 1024;
+
+/**
+ * 按 `src` 缓存字节的 LRU：同一条会话每一步都要重发同一批图。`src` 内容不可变，所以永不
+ * 失效，只按体积淘汰（至少留一张）。同一 `src` 的并发读合流成一次。
+ */
+export class ImageByteCache {
+  private readonly entries = new Map<string, LoadedImage>();
+  private readonly inflight = new Map<string, Promise<LoadedImage>>();
+  private total = 0;
+
+  constructor(
+    private readonly source: ImageSource,
+    private readonly limitBytes = DEFAULT_BYTE_CACHE_LIMIT
+  ) {}
+
+  load(src: string): Promise<LoadedImage> {
+    const hit = this.entries.get(src);
+    if (hit) {
+      this.entries.delete(src);
+      this.entries.set(src, hit);
+      return Promise.resolve(hit);
+    }
+    const pending = this.inflight.get(src);
+    if (pending) return pending;
+    const p = this.read(src).finally(() => this.inflight.delete(src));
+    this.inflight.set(src, p);
+    return p;
+  }
+
+  private async read(src: string): Promise<LoadedImage> {
+    const raw = await this.source.read(src);
+    const entry: LoadedImage = {
+      data: raw.data,
+      contentType: raw.contentType,
+      contentHash:
+        raw.contentHash ?? createHash('sha256').update(raw.data).digest('hex'),
+    };
+    this.entries.set(src, entry);
+    this.total += entry.data.byteLength;
+    while (this.total > this.limitBytes && this.entries.size > 1) {
+      const oldest = this.entries.keys().next().value as string;
+      const evicted = this.entries.get(oldest);
+      this.entries.delete(oldest);
+      if (evicted) this.total -= evicted.data.byteLength;
+    }
+    return entry;
+  }
+}