cortico 0.1.0

package/src/config-file.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { readTextFile } from './core/util.ts';
+
+export type JsonObject = Record<string, unknown>;
+
+export function readJsonObject(file: string): JsonObject {
+  if (!existsSync(file)) return {};
+  try {
+    const value = JSON.parse(readTextFile(file)) as unknown;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new Error('root must be an object');
+    }
+    return value as JsonObject;
+  } catch {
+    throw new Error('config.json解析失败,拒绝写回(请手工检查文件)');
+  }
+}
+
+export function updateJsonObject(file: string, update: (root: JsonObject) => void): void {
+  const root = readJsonObject(file);
+  update(root);
+
+  const suffix = `${process.pid}-${randomUUID()}`;
+  const tmp = `${file}.tmp-${suffix}`;
+  const backup = `${file}.bak-${suffix}`;
+  writeFileSync(tmp, `${JSON.stringify(root, null, 2)}\n`, 'utf8');
+  if (!existsSync(file)) {
+    renameSync(tmp, file);
+    return;
+  }
+
+  renameSync(file, backup);
+  try {
+    renameSync(tmp, file);
+  } catch (error) {
+    renameSync(backup, file);
+    throw error;
+  }
+  rmSync(backup);
+}

package/src/core/README.md

@@ -0,0 +1,92 @@
+Owner: `src/core/core.ts`, `src/core/types.ts`, `src/core/loop.ts`, `src/core/bus.ts`
+
+# src/core
+
+Core 管理 session、事件流与模型调用的生命周期，包括事件投递、调度、上下文交接、工具执行、
+容量限制、错误隔离和 Provider。Persona 定义上下文语义；Core 使用的事件封装、错误和截断记号
+在 `markers.ts` 中定义。
+
+## 文件
+
+| 文件 | 职责 |
+|---|---|
+| `types.ts` | 全部契约:`Persona`、`World`、`WorldHost`、`CoreApi`、事件、工具、日志、配置类型 |
+| `core.ts` | Core 装配，`Persona` / `CoreApi` 的边界 |
+| `loop.ts` | 主 session 的模型调用循环、事件投递、上下文交接执行 |
+| `bus.ts` | `WakeBus`：合批事件总线、四种触发模式、FIFO 顺序、暂停与投递闸门 |
+| `fork.ts` | 临时 session 的工具循环 |
+| `session.ts`、`sessions.ts` | 常驻 session 的追加式上下文；各 session 的状态与用量记录 |
+| `event-store.ts` | 按 run 分片的 JSONL 事件库,cursor 跨 run 全局单调 |
+| `state.ts`、`run.ts`、`timers.ts` | `core-state.json`;run 目录;通用持久定时器 |
+| `transcript.ts`、`tool-log.ts`、`usage-log.ts` | 主 session 副本、工具调用记录、用量记录 |
+| `cost.ts`、`billing.ts`、`generation.ts` | 消耗汇总、计费余额、`ResponseClient` 与计量口径 |
+| `prefix.ts`、`template.ts` | system 前缀装配、环境提示词三层覆盖、模板渲染 |
+| `truncate.ts`、`markers.ts`、`blobs.ts` | 上下文压缩、结构记号、附件句柄(`log:` / `mem:`) |
+| `config.ts`、`config-schema.ts` | `CORE_DEFAULTS`、深合并、配置项声明 |
+| `instance-lock.ts`、`language.ts`、`secrets.ts` | 单实例锁、控制台语言、按名取密钥 |
+| `log-context.ts`、`ipc-logger.ts`、`util.ts` | 日志关联字段、子进程日志回传、Logger 与 token 估算 |
+
+## Core 类
+
+构造时创建事件库、session、状态、定时器和日志，先调用 `persona.attach(core)`，再调用
+`persona.declareSessions()`。声明中必须恰有一个同时设置 `receivesEvents` 和 `persistent`，否则抛错。
+公开成员：`store`、`bus`、`session`、`state`、`timers`、`loop`、`llm`、`sessions`、`providers`、
+`sessionDecls`;`spawnFork`、`resolveBlob` / `internBlobs`、`setWorldVisible`、`activeSpec` /
+`activeProviderEntry`、`mountWorld` / `unmountWorld`、`start` / `stop`。
+
+Persona 通过 `CoreApi` 访问：`injectInternal` / `injectDeferred` / `injectExternal`、
+`requestContextHandoff`、`spawnFork`、`sessionInfo`、`llm`、`timers`、`deliveryGate`、
+`personaState` / `savePersonaState`、`toolsTagged`、`blob`、`log`。
+
+## 总线与唤醒
+
+`WakeBus` 提供 `preempt`、`flush`、`debounce`、`piggyback` 四种触发模式。
+debounce 的计划投递时刻为 `min(首件时刻 + maxBatchAgeMs, max(首件时刻 + minBatchAgeMs,
+末件时刻 + quietGapMs))`；计数达到 `maxBatchSize` 时立即投递。
+计数包含外部即时事件与候选，不包含内部事件、延迟渲染项或 piggyback 项。
+piggyback 只入队，随后续唤醒一起投递。
+
+操作者的 `paused` 和 Persona 的 `DeliveryGate` 控制投递；操作者暂停的优先级更高。
+`nextBatch()` 仅支持一个消费者，每次按 FIFO 顺序取走整批。`batching` 使用共享配置引用，
+更新后的值在下一次入队时参与计算。
+
+投递水位 `lastDeliveredCursor` 持久化，队列不持久化。重启时补投水位之后的外部事件；
+已被候选处理结果引用的原始归档不重复投递。内部事件仅在当次运行投递。
+
+## 主循环
+
+每次唤醒处理一批事件，可进行多轮模型调用。`SessionDecl.rounds()` 提供
+`{ soft, hard, softHint? }`：到 soft 轮时将 `softHint` 追加到最后一条工具回执；到 hard 轮时
+记录 warn 并结束本批。`endsTurn` 工具和自然结束共用结束处理；本批结束时尚未处理的事件
+退回总线，进入下一批。
+
+状态 0、429 或 5xx 的模型调用失败，可保留已记录的输出和工具回执，按 `ResubmitPolicy` 重试。
+默认允许连续重试 2 次、每批最多 4 次，退避为 2 秒、10 秒；上下文超限、抢占、关机或轮数
+达到硬上限时不重试。
+
+参数不是合法 JSON 时返回 `TOOL_FAILED_BAD_ARGS`，不执行工具；未知工具返回 `UNKNOWN_TOOL`；
+handler 异常转为失败回执。流式生成时 `EagerDispatch` 可提前执行完整的工具调用，遵守
+`barrierAfter` 顺序，并按 call id 配对结果。回执超过 8000 字符时记录 warn。
+
+## 上下文
+
+`hardTokens = max(0, contextWindowOf(spec) − (spec.maxTokens ?? 0))`。
+`contextWindowOf` 取 provider 探测值与手动 `contextWindow` 的较小者；两者均未知时不按窗口裁剪。
+超过上限时，主循环在轮次边界结束本批，并在批末强制交接；上游报告输入超限时也请求交接。
+
+`Persona.onHandoff(snapshot, { hardTokens })` 返回 `{ tail, trim? }`。Core 重建 system 前缀，
+按 `hardTokens − estimate(prefix)` 限制保留上下文，其中 prefix 包括 system 前缀和 Persona 的合成
+开头(`sessionHead()`)。Core 校验工具调用配对，并重置 session。
+合成开头每次请求现取，不写入持久 session；Core 不据此判定远端缓存是否命中。
+阶段预算与保留比例由 Persona 决定，模型配置来自当前 provider。
+
+存储清单使用 `StorageOwner` 标识 Core、Persona、Memory 与 World 的归属。
+页面组织和 Memory 展示名称由装配层处理。
+
+## 错误隔离
+
+装配层将 World 构造失败限制在该 World。`start()` 抛错时不挂载；`stop()` 失败或超时会记录
+结果并继续卸载。`onOpening`、`onDelivery`、`onBatchEnd`、`onTurnEnded`、`onIdle` 异常记录
+warn；`onHandoff` 异常记录 error 并使用默认交接策略。其他钩子的异常由调用方处理。
+读取 `console()` 失败时省略该 World 的环境段，继续构建前缀。主循环异常退出时记录 error
+并停止定时器。启动器处理未捕获的进程异常并执行关机流程。

package/src/core/billing.ts

@@ -0,0 +1,26 @@
+import type { Charge } from './generation.ts';
+import type { UsageRecord } from './types.ts';
+
+export interface BillingBalance {
+  currency: string;
+  basis: 'marginal' | 'equivalent';
+  knownAmount: number;
+  pricedCalls: number;
+  partialCalls: number;
+}
+
+export function recordCharges(record: UsageRecord): readonly Charge[] { return record.attempt?.charges ?? record.charges ?? []; }
+
+/** Currency and cost basis are separate ledgers. Unquoted rows remain visible in coverage. */
+export function billingBalances(records: readonly UsageRecord[]): BillingBalance[] {
+  const balances = new Map<string, BillingBalance>();
+  for (const record of records) for (const charge of recordCharges(record)) {
+    const { currency, basis } = charge.quote;
+    const key = JSON.stringify([currency, basis]);
+    const balance = balances.get(key) ?? { currency, basis, knownAmount: 0, pricedCalls: 0, partialCalls: 0 };
+    balance.knownAmount += charge.knownAmount;
+    if (charge.amount === null) balance.partialCalls++; else balance.pricedCalls++;
+    balances.set(key, balance);
+  }
+  return [...balances.values()].sort((a,b) => a.basis.localeCompare(b.basis) || a.currency.localeCompare(b.currency));
+}

package/src/core/blobs.ts

@@ -0,0 +1,106 @@
+/**
+ * 附件以句柄存入事件库与 session。
+ * `log:<内容哈希>.<ext>` 引用 data/media/ 中按内容寻址、只增的日志附件。
+ * `mem:<后端标识>` 由 Persona 的 BlobStore 解析，后端决定标识格式。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BlobRef } from './types.ts';
+
+export const LOG_SCHEME = 'log:';
+export const MEM_SCHEME = 'mem:';
+
+const EXT_BY_MIME: Record<string, string> = {
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/gif': '.gif',
+  'image/bmp': '.bmp',
+  'image/webp': '.webp',
+  'application/pdf': '.pdf',
+  'audio/wav': '.wav',
+  'audio/mpeg': '.mp3',
+  'text/plain': '.txt',
+  'application/json': '.json',
+  'application/zip': '.zip',
+};
+
+/** 日志附件的文件名形状(不含 scheme);路径分隔符一律拒绝(防穿越)。 */
+const LOG_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** 短句柄:至少 8 位十六进制,可带扩展名 */
+const LOG_PREFIX_RE = /^([0-9a-f]{8,40})(\.[A-Za-z0-9]+)?$/;
+const LOG_HASH_CHARS = 20;
+
+export function blobScheme(handle: string): 'log' | 'mem' | null {
+  if (handle.startsWith(MEM_SCHEME)) return 'mem';
+  if (handle.startsWith(LOG_SCHEME)) return 'log';
+  return null;
+}
+
+/** 按扩展名反推 mime;认不出的扩展名 → octet-stream。 */
+export function mimeOfHandle(handle: string): string {
+  const dot = handle.lastIndexOf('.');
+  const ext = dot >= 0 ? handle.slice(dot).toLowerCase() : '';
+  for (const [mime, e] of Object.entries(EXT_BY_MIME)) if (e === ext) return mime;
+  return 'application/octet-stream';
+}
+
+/** 一份附件进入 session 的那一行:句柄、mime、名字,后接它的文本形态。 */
+export function blobLine(ref: BlobRef): string {
+  return `[blob ${ref.handle} ${ref.mime}${ref.name ? ` ${ref.name}` : ''}] ${ref.fallbackText}`;
+}
+
+/** 正文后接每份附件一行;没有附件时原样交回。 */
+export function withBlobLines(text: string, refs: readonly BlobRef[] | undefined): string {
+  if (!refs || refs.length === 0) return text;
+  const lines = refs.map(blobLine).join('\n');
+  return text ? `${text}\n${lines}` : lines;
+}
+
+/**
+ * 字节按内容哈希存入 data/media/，重复写入不增加副本；删除由运维处理。
+ * 读取接受完整句柄或唯一的十六进制前缀（至少 8 位）。
+ */
+export class LogBlobStore {
+  private readonly dir: string;
+
+  constructor(dataDir: string) {
+    this.dir = join(dataDir, 'media');
+  }
+
+  /** 落盘并返回 `log:` 句柄。 */
+  put(bytes: Uint8Array, mime: string): string {
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, LOG_HASH_CHARS);
+    const ext = EXT_BY_MIME[mime] ?? '.bin';
+    const name = `${hash}${ext}`;
+    const path = join(this.dir, name);
+    if (!existsSync(path)) {
+      if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });
+      writeFileSync(path, bytes);
+    }
+    return `${LOG_SCHEME}${name}`;
+  }
+
+  /** 按句柄取回;句柄不合形状、前缀不唯一或文件不在了返回 null。 */
+  read(handle: string): { bytes: Buffer; mime: string } | null {
+    const name = this.resolveName(handle);
+    if (!name) return null;
+    try {
+      return { bytes: readFileSync(join(this.dir, name)), mime: mimeOfHandle(name) };
+    } catch {
+      return null;
+    }
+  }
+
+  private resolveName(handle: string): string | null {
+    if (!handle.startsWith(LOG_SCHEME)) return null;
+    const raw = handle.slice(LOG_SCHEME.length);
+    if (!LOG_NAME_RE.test(raw)) return null;
+    if (existsSync(join(this.dir, raw))) return raw;
+    const m = LOG_PREFIX_RE.exec(raw);
+    if (!m || !existsSync(this.dir)) return null;
+    const [, prefix, ext] = m;
+    const hits = readdirSync(this.dir).filter((f) => f.startsWith(prefix) && (!ext || f.endsWith(ext)));
+    return hits.length === 1 ? hits[0] : null;
+  }
+}

package/src/core/bus.ts

@@ -0,0 +1,311 @@
+/**
+ * WakeBus 按到达顺序向单个消费者交付整个队列。触发模式及默认值见 types.ts 的 TriggerMode。
+ * debounce 的投递时间为 min(首件 + maxBatchAge, max(首件 + minBatchAge, 末件 + quietGap))；
+ * 可计数外部事件达到 maxBatchSize 时立即投递。
+ * 队列包含即时事件、延迟渲染项与候选项。延迟渲染项不参与关键词匹配或外部事件计数；
+ * 候选项按外部事件计数，关键词只检查 gateText。
+ * piggyback 不触发计时、关键词或溢出，也不单独获得投递许可；需要其他项触发投递。
+ * 人工暂停阻止所有投递。DeliveryGate 解除、关键词回调授权或溢出授权均放行整批。
+ */
+import type { DeliveryGate, EventOrigin, Logger, TriggerMode, WakeItem } from './types.ts';
+import { nullLogger } from './util.ts';
+
+export interface WakeBusOptions {
+  /** 末件到达之后安静这么久才投递 */
+  quietGapMs: number;
+  /** 首件到达起至少攒这么久 */
+  minBatchAgeMs: number;
+  /** 首件到达起最多攒这么久,到点强制投递 */
+  maxBatchAgeMs: number;
+  /** 积压事件达到这个条数就强制投递 */
+  maxBatchSize: number;
+}
+
+// 每次 push 读取同一个配置对象，原位修改在下一次 push 生效。
+
+/** 入队时固定 piggyback 标志，后续计数与调度沿用该值。 */
+interface Queued {
+  item: WakeItem;
+  piggyback: boolean;
+}
+
+export class WakeBus {
+  private opts: WakeBusOptions;
+  private queue: Queued[] = [];
+  private paused = false;
+  private gate: DeliveryGate | null = null;
+  /** 一次整批投递许可;人工暂停的优先级更高。 */
+  private bypassGateOnce = false;
+  /** 到期即投递的那一个定时器;每次 push 按四条判据重算 */
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  /** 本批首件与末件的到达时刻(队列空时为 null) */
+  private firstAt: number | null = null;
+  private lastAt = 0;
+  /** 挂起中的消费者(单消费者,最多一个) */
+  private waiter: ((batch: WakeItem[]) => void) | null = null;
+  /** 已到投递条件但没有消费者在等:置真,消费者一来就取走 */
+  private ready = false;
+  /** preempt 只报告机械时机；是否仍可安全取消由主循环裁决。 */
+  private preemptHandler: (() => void) | null = null;
+
+  private readonly log: Logger;
+
+  constructor(opts: WakeBusOptions, log: Logger = nullLogger()) {
+    this.opts = opts;
+    this.log = log;
+  }
+
+  setPreemptHandler(handler: () => void): void {
+    this.preemptHandler = handler;
+  }
+
+  push(item: WakeItem, opts?: { trigger?: TriggerMode }): void {
+    const origin = originOf(item);
+    const trigger: TriggerMode =
+      opts?.trigger ?? (origin === 'internal' ? 'flush' : 'debounce');
+    const piggyback = trigger === 'piggyback';
+    this.queue.push({ item, piggyback });
+    const gate = this.gate;
+    if (gate) {
+      this.clearTimers();
+      // piggyback 不参与关键词或溢出判定。
+      if (piggyback) return;
+      // 延迟渲染项没有可用于关键词匹配的正文。
+      const gateText = textForGate(item);
+      if (origin === 'external' && gate.keyword !== undefined && gateText?.includes(gate.keyword)) {
+        gate.onKeyword();
+        const permitted = this.gate !== gate || this.bypassGateOnce;
+        this.log.emit('debug', '闸门关键词命中', { event: 'gate-keyword', data: { gate: gate.id, permitted } });
+        if (permitted) this.deliver(this.bypassGateOnce);
+        this.notifyPreempt(trigger, permitted);
+        return;
+      }
+      // 已经有一批获准放行时,新到直接并入该批,不重复产生溢出通知。
+      if (this.bypassGateOnce) {
+        this.deliver(true);
+        this.notifyPreempt(trigger, true);
+        return;
+      }
+      if (origin === 'external' && this.pendingEventCount() > gate.overflowLimit) {
+        // 回调可能同步注入事件；先设置许可，使注入项仍属于当前批。
+        this.bypassGateOnce = true;
+        this.log.emit('debug', '闸门下积压越过溢出线,整批放行', { event: 'gate-overflow', data: { gate: gate.id, pending: this.pendingEventCount(), limit: gate.overflowLimit } });
+        gate.onOverflow();
+        this.deliver(true);
+        this.notifyPreempt(trigger, true);
+      }
+      return;
+    }
+
+    if (trigger === 'preempt') {
+      const permitted = !this.blocked();
+      this.deliver();
+      this.notifyPreempt(trigger, permitted);
+      return;
+    }
+    if (trigger === 'flush') {
+      this.deliver();
+      return;
+    }
+    // piggyback 不启动或延后批次计时器。
+    if (piggyback) return;
+    const now = Date.now();
+    if (this.firstAt === null) this.firstAt = now;
+    this.lastAt = now;
+    if (this.pendingEventCount() >= this.opts.maxBatchSize) {
+      this.deliver();
+      return;
+    }
+    this.arm();
+  }
+
+  /** 重新计算投递时间；配置修改在下一次 push 生效。 */
+  private arm(): void {
+    if (this.firstAt === null) return;
+    const { quietGapMs, minBatchAgeMs, maxBatchAgeMs } = this.opts;
+    const at = Math.min(
+      this.firstAt + maxBatchAgeMs,
+      Math.max(this.firstAt + minBatchAgeMs, this.lastAt + quietGapMs),
+    );
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.deliver(), Math.max(0, at - Date.now()));
+  }
+
+  /** 暂停或闸门(未获准整批放行)期间不投递。 */
+  private blocked(): boolean {
+    return this.paused || (this.gate !== null && !this.bypassGateOnce);
+  }
+
+  /** 已获准投递的 preempt 才能取消当前模型轮；暂停与闸门继续拥有更高优先级。 */
+  private notifyPreempt(trigger: TriggerMode, permitted: boolean): void {
+    if (trigger === 'preempt' && permitted && !this.paused) {
+      this.log.emit('debug', '抢占:请求取消尚未外化的在途模型轮', { event: 'preempt' });
+      this.preemptHandler?.();
+    }
+  }
+
+  /** 人工暂停/继续(控制台);继续时积压一次性投递 */
+  setPaused(v: boolean): void {
+    if (v !== this.paused) this.log.emit('info', v ? '总线已暂停:事件照常落库,不投递' : '总线继续', { event: v ? 'paused' : 'resumed', data: { queued: this.queue.length } });
+    this.paused = v;
+    if (!this.paused && (this.ready || this.queue.length > 0)) {
+      this.deliver(this.bypassGateOnce);
+    }
+  }
+
+  isPaused(): boolean {
+    return this.paused;
+  }
+
+  /**
+   * 安装或更新投递闸门。若此前没有闸门,安装前已经积压的内容获准放行一次;
+   * 闸门只约束安装之后到达的唤醒项。
+   */
+  setDeliveryGate(gate: DeliveryGate): void {
+    const hadGate = this.gate !== null;
+    this.gate = gate;
+    this.clearTimers();
+    this.log.emit('debug', hadGate ? '投递闸门已更新' : '投递闸门已安装', { event: 'gate-set', data: { gate: gate.id, queued: this.queue.length } });
+    if (!hadGate && this.queue.length > 0) {
+      this.deliver(true);
+    }
+  }
+
+  /**
+   * 只解除匹配id的闸门。deliverQueued=false用于"先解闸、再把到期通知和积压
+   * 一起投递",避免拆成两个user回合。
+   */
+  clearDeliveryGate(id: string, deliverQueued = true): boolean {
+    if (this.gate?.id !== id) return false;
+    this.gate = null;
+    this.log.emit('debug', '投递闸门已解除', { event: 'gate-cleared', data: { gate: id, queued: this.queue.length, deliverQueued } });
+    if (deliverQueued && this.queue.length > 0) {
+      this.deliver(this.bypassGateOnce);
+    }
+    return true;
+  }
+
+  isDeliveryBlocked(): boolean {
+    return this.gate !== null;
+  }
+
+  /** 当前积压条数(控制台可见性;含尚未成文的投递成文项) */
+  pending(): number {
+    return this.queue.length;
+  }
+
+  /** 供空闲判定使用：不计延迟渲染项和 piggyback 项。 */
+  pendingImmediate(): number {
+    let n = 0;
+    for (const q of this.queue) {
+      if (!q.piggyback && (q.item.event !== undefined || q.item.candidate !== undefined)) n++;
+    }
+    return n;
+  }
+
+  /** 按原序取出匹配项，消费后不再投递。同步完成，不触发消费者或改变投递许可和计时器。 */
+  drainPending(pred: (item: WakeItem) => boolean): WakeItem[] {
+    const drained: WakeItem[] = [];
+    const kept: Queued[] = [];
+    for (const q of this.queue) {
+      if (pred(q.item)) drained.push(q.item);
+      else kept.push(q);
+    }
+    this.queue = kept;
+    // 仅剩 piggyback 项时清除 ready 和计时器，避免触发空批次。
+    if (!this.hasWakingItem()) {
+      this.ready = false;
+      this.bypassGateOnce = false;
+      this.firstAt = null;
+      this.clearTimers();
+    }
+    return drained;
+  }
+
+  /**
+   * 仅在满足投递条件时同步取走整批，否则返回 null。
+   * 供工具调用链在没有 nextBatch 消费者时接收已就绪的通知。
+   */
+  takeIfReady(): WakeItem[] | null {
+    if (!this.ready || this.queue.length === 0 || this.blocked()) return null;
+    this.ready = false;
+    return this.take();
+  }
+
+  /** 取走整个队列；尚不可投递时等待。只允许一个等待中的消费者。 */
+  nextBatch(): Promise<WakeItem[]> {
+    if (this.waiter) throw new Error('WakeBus只支持单消费者');
+    if (this.ready && this.queue.length > 0 && !this.blocked()) {
+      this.ready = false;
+      return Promise.resolve(this.take());
+    }
+    return new Promise<WakeItem[]>((resolve) => {
+      this.waiter = resolve;
+    });
+  }
+
+  private deliver(bypassGate = false): void {
+    this.clearTimers();
+    // piggyback 需要其他项触发投递。
+    if (this.queue.length > 0 && !this.hasWakingItem()) return;
+    if (bypassGate) this.bypassGateOnce = true;
+    if (this.blocked()) {
+      this.ready = true;
+      return;
+    }
+    if (this.queue.length === 0) {
+      // 许可仅用于当前批，不能沿用到下一批。
+      this.bypassGateOnce = false;
+      return;
+    }
+    if (this.waiter) {
+      const w = this.waiter;
+      this.waiter = null;
+      this.ready = false;
+      w(this.take());
+    } else {
+      this.ready = true;
+    }
+  }
+
+  private take(): WakeItem[] {
+    const batch = this.queue.map((q) => q.item);
+    this.log.emit('debug', '投递一批', { event: 'deliver', data: { count: batch.length, piggyback: this.queue.filter((q) => q.piggyback).length, ageMs: this.firstAt === null ? 0 : Date.now() - this.firstAt } });
+    this.queue = [];
+    this.bypassGateOnce = false;
+    this.firstAt = null; // 下一批的延迟下限和上限从首条事件重新计时。
+    return batch;
+  }
+
+  /** 供批次大小与闸门上限使用：只计外部即时事件和候选项，不计 piggyback。 */
+  private pendingEventCount(): number {
+    let count = 0;
+    for (const q of this.queue) {
+      if (
+        !q.piggyback &&
+        (q.item.event !== undefined || q.item.candidate !== undefined) &&
+        originOf(q.item) === 'external'
+      ) count++;
+    }
+    return count;
+  }
+
+  private hasWakingItem(): boolean {
+    return this.queue.some((q) => !q.piggyback);
+  }
+
+  private clearTimers(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}
+
+function originOf(item: WakeItem): EventOrigin {
+  return item.event?.origin ?? item.deferred?.origin ?? item.candidate!.origin;
+}
+
+function textForGate(item: WakeItem): string | null {
+  return item.event?.text ?? item.candidate?.gateText ?? null;
+}