cortico 0.1.0

package/src/core/cost.ts

@@ -0,0 +1,244 @@
+/** Aggregate observed consumption and immutable Provider charges. */
+import type { UsageRecord } from './types.ts';
+import { billingBalances, recordCharges, type BillingBalance } from './billing.ts';
+
+/** 已解析的具体时间粒度(桶宽) */
+export type UsageBucketUnit = 'minute' | 'hour' | 'day' | 'week' | 'month';
+/** 请求粒度:具体粒度或 'auto'(按范围跨度自适应) */
+export type UsageBucketOption = UsageBucketUnit | 'auto';
+export type UsageGroupBy = 'role' | 'model' | 'none';
+
+/**
+ * 用量与费用合计，供时间序列及角色、模型分组使用。
+ * cost = costCacheHit + costCacheMiss + costOutput + costOther。
+ * reasoningTokens 是 completionTokens 的子集；费用采用记录内的 charges。
+ */
+export interface UsageAccum {
+  calls: number;
+  promptTokens: number;
+  completionTokens: number;
+  cacheHitTokens: number;
+  cacheMissTokens: number;
+  reasoningTokens: number;
+  cost: number;
+  costCacheHit: number;
+  costCacheMiss: number;
+  costOutput: number;
+  costOther: number;
+  unclassifiedInputTokens: number;
+  pricedCalls: number;
+  unpricedCalls: number;
+  unknownUsageCalls: number;
+}
+
+export interface UsageSeriesPoint extends UsageAccum {
+  /** 本地时区前缀,如 2026-07-19T14:30、2026-07-19 或 2026-07。 */
+  bucket: string;
+  /** 本桶内按角色的子拆分(键=角色);用于堆叠"按角色"视图 */
+  byRole: Record<string, UsageAccum>;
+  /** 本桶内按模型的子拆分(键=模型);用于堆叠"按模型"视图 */
+  byModel: Record<string, UsageAccum>;
+  /** 按角色与模型交叉分组，键为 byRoleModel[role][model]。 */
+  byRoleModel: Record<string, Record<string, UsageAccum>>;
+}
+
+/** 按 role / model 分组的合计 */
+export interface UsageGroupStat extends UsageAccum {
+  key: string;
+  /** 声明方提供的 UsageRecord.label；与 key 相同时省略。缺失时显示 key，不推断角色名称。 */
+  label?: string;
+  cacheHitRate: number | null;
+}
+
+export interface UsageAggregate {
+  currency: string;
+  basis: 'marginal' | 'equivalent';
+  balances: BillingBalance[];
+  successful: UsageAccum;
+  byInstance: UsageGroupStat[];
+  /** 实际使用的粒度(auto 会被解析成具体值) */
+  bucket: UsageBucketUnit;
+  from: string | null;
+  to: string | null;
+  /** 时间序列(按 bucket 升序) */
+  series: UsageSeriesPoint[];
+  /** 全量合计 */
+  totals: UsageGroupStat;
+  /** 按角色分组(cost 降序) */
+  byRole: UsageGroupStat[];
+  /** 按模型分组(cost 降序) */
+  byModel: UsageGroupStat[];
+  /** Failed, aborted and discarded attempts are also included in totals. */
+  failed: UsageAccum;
+}
+
+function zero(): UsageAccum {
+  return {
+    calls: 0, promptTokens: 0, completionTokens: 0,
+    cacheHitTokens: 0, cacheMissTokens: 0, reasoningTokens: 0,
+    cost: 0, costCacheHit: 0, costCacheMiss: 0, costOutput: 0, costOther: 0, unclassifiedInputTokens: 0,
+    pricedCalls: 0, unpricedCalls: 0, unknownUsageCalls: 0,
+  };
+}
+
+type MeasuredCost = { cacheHit: number; cacheMiss: number; output: number; total: number; priced: boolean };
+
+function add(a: UsageAccum, r: UsageRecord, c: MeasuredCost): void {
+  a.calls += 1;
+  if (c.priced) a.pricedCalls++; else a.unpricedCalls++;
+  if (r.attempt && (r.attempt.meters.input === null || r.attempt.meters.output === null || r.attempt.meters.cachedInput === null)) a.unknownUsageCalls++;
+  a.promptTokens += r.promptTokens;
+  a.completionTokens += r.completionTokens;
+  a.cacheHitTokens += r.cacheHitTokens;
+  a.cacheMissTokens += r.cacheMissTokens;
+  a.reasoningTokens += r.reasoningTokens;
+  a.cost += c.total;
+  a.costCacheHit += c.cacheHit;
+  a.costCacheMiss += c.cacheMiss;
+  a.costOutput += c.output;
+  a.costOther += c.total - c.cacheHit - c.cacheMiss - c.output;
+  a.unclassifiedInputTokens += Math.max(0, r.promptTokens - r.cacheHitTokens - r.cacheMissTokens);
+}
+
+function upsert(m: Map<string, UsageAccum>, key: string, r: UsageRecord, c: MeasuredCost): void {
+  let a = m.get(key);
+  if (!a) { a = zero(); m.set(key, a); }
+  add(a, r, c);
+}
+
+function mapToObj(m: Map<string, UsageAccum>): Record<string, UsageAccum> {
+  const o: Record<string, UsageAccum> = {};
+  for (const [k, v] of m) o[k] = v;
+  return o;
+}
+
+function nestedMapToObj(m: Map<string, Map<string, UsageAccum>>): Record<string, Record<string, UsageAccum>> {
+  const o: Record<string, Record<string, UsageAccum>> = {};
+  for (const [k, inner] of m) o[k] = mapToObj(inner);
+  return o;
+}
+
+function statOf(key: string, a: UsageAccum, label?: string): UsageGroupStat {
+  const out: UsageGroupStat = { key, ...a, cacheHitRate: cacheHitRate(a) };
+  if (label && label !== key) out.label = label;
+  return out;
+}
+
+/** 一天 = 该日期(YYYY-MM-DD)所在 ISO 周的周一(用 UTC 计算,避免时区漂移) */
+function weekStart(day: string): string {
+  const [y, m, d] = day.split('-').map(Number);
+  const dt = new Date(Date.UTC(y || 1970, (m || 1) - 1, d || 1));
+  const dow = (dt.getUTCDay() + 6) % 7; // 周一=0 … 周日=6
+  dt.setUTCDate(dt.getUTCDate() - dow);
+  return dt.toISOString().slice(0, 10);
+}
+
+/** 取某条记录在给定粒度下的桶键(本地时区 ISO 前缀直接切,周单独算) */
+function bucketKeyOf(ts: string, unit: UsageBucketUnit): string {
+  switch (unit) {
+    case 'minute': return ts.slice(0, 16); // YYYY-MM-DDTHH:MM
+    case 'hour': return ts.slice(0, 13);   // YYYY-MM-DDTHH
+    case 'day': return ts.slice(0, 10);    // YYYY-MM-DD
+    case 'week': return weekStart(ts.slice(0, 10));
+    case 'month': return ts.slice(0, 7);   // YYYY-MM
+  }
+}
+
+/** from/to(YYYY-MM-DD,含端)之间的整天跨度(含首尾);任一为空→NaN */
+function daySpan(from?: string | null, to?: string | null): number {
+  if (!from || !to) return NaN;
+  const a = Date.parse(from + 'T00:00:00Z');
+  const b = Date.parse(to + 'T00:00:00Z');
+  if (Number.isNaN(a) || Number.isNaN(b)) return NaN;
+  return Math.abs(b - a) / 86400000 + 1;
+}
+
+/**
+ * 自动粒度：跨度 ≤2 天用小时，≤62 天用天，≤366 天用周，其余用月。
+ * 缺少 from/to 时用天；分钟需显式选择。
+ */
+export function resolveBucket(from?: string | null, to?: string | null): UsageBucketUnit {
+  const span = daySpan(from, to);
+  if (Number.isNaN(span)) return 'day';
+  if (span <= 2) return 'hour';
+  if (span <= 62) return 'day';
+  if (span <= 366) return 'week';
+  return 'month';
+}
+
+/**
+ * 按包含端点的日期范围筛选，按时间、角色和模型聚合用量。
+ * 费用从记录内的 charges 按币种和计价基础选择，再按 meter 归入四类成本。
+ */
+export function aggregateUsage(
+  records: UsageRecord[],
+  opts: { from?: string | null; to?: string | null; bucket: UsageBucketOption; currency?: string; basis?: 'marginal' | 'equivalent' },
+): UsageAggregate {
+  const { from = null, to = null } = opts;
+  const unit: UsageBucketUnit = opts.bucket === 'auto' ? resolveBucket(from, to) : opts.bucket;
+  const series = new Map<string, { total: UsageAccum; roles: Map<string, UsageAccum>; models: Map<string, UsageAccum>; roleModels: Map<string, Map<string, UsageAccum>> }>();
+  const roles = new Map<string, UsageAccum>();
+  /** 同一 role 的 label 使用最后一条记录提供的值。 */
+  const roleLabels = new Map<string, string>();
+  const models = new Map<string, UsageAccum>();
+  const totals = zero();
+  const failed = zero();
+  const successful = zero();
+  const instances = new Map<string, UsageAccum>();
+  const selected = records.filter(r => r && typeof r.ts === 'string' && (!from || r.ts.slice(0,10) >= from) && (!to || r.ts.slice(0,10) <= to));
+  const balances = billingBalances(selected);
+  const basis = opts.basis ?? 'marginal';
+  const currency = opts.currency ?? balances.find(balance => balance.basis === basis)?.currency ?? 'USD';
+
+  for (const r of selected) {
+    const charge = recordCharges(r).find(charge => charge.quote.currency === currency && charge.quote.basis === basis);
+    const cost: MeasuredCost = { cacheHit: 0, cacheMiss: 0, output: 0, total: charge?.knownAmount ?? 0, priced: charge?.amount != null };
+    for (const line of charge?.lines ?? []) {
+      if (line.meter === 'cachedInput') cost.cacheHit += line.amount ?? 0;
+      if (line.meter === 'uncachedInput' || line.meter === 'input') cost.cacheMiss += line.amount ?? 0;
+      if (line.meter === 'output') cost.output += line.amount ?? 0;
+    }
+    const outcome = r.attempt?.outcome;
+    if (r.outcome !== undefined || (outcome !== undefined && outcome !== 'completed' && outcome !== 'incomplete')) add(failed, r, cost);
+    else if (r.attempt?.purpose !== 'diagnostic') add(successful, r, cost);
+    upsert(instances, r.attempt?.origin.instance ?? 'unknown', r, cost);
+    const role = r.role ?? 'unknown';
+    const model = r.model || 'unknown';
+    const bk = bucketKeyOf(r.ts, unit);
+    let bucketAcc = series.get(bk);
+    if (!bucketAcc) { bucketAcc = { total: zero(), roles: new Map(), models: new Map(), roleModels: new Map() }; series.set(bk, bucketAcc); }
+    add(bucketAcc.total, r, cost);
+    upsert(bucketAcc.roles, role, r, cost);
+    upsert(bucketAcc.models, model, r, cost);
+    let rm = bucketAcc.roleModels.get(role);
+    if (!rm) { rm = new Map(); bucketAcc.roleModels.set(role, rm); }
+    upsert(rm, model, r, cost);
+    upsert(roles, role, r, cost);
+    if (r.label) roleLabels.set(role, r.label);
+    upsert(models, model, r, cost);
+    add(totals, r, cost);
+  }
+
+  const seriesOut: UsageSeriesPoint[] = [...series.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([b, acc]) => ({ bucket: b, ...acc.total, byRole: mapToObj(acc.roles), byModel: mapToObj(acc.models), byRoleModel: nestedMapToObj(acc.roleModels) }));
+  const groupOut = (m: Map<string, UsageAccum>, labels?: Map<string, string>): UsageGroupStat[] =>
+    [...m.entries()].map(([k, a]) => statOf(k, a, labels?.get(k))).sort((x, y) => y.cost - x.cost);
+
+  return {
+    currency, basis, balances, successful, byInstance: groupOut(instances),
+    bucket: unit,
+    from,
+    to,
+    series: seriesOut,
+    totals: statOf('total', totals),
+    byRole: groupOut(roles, roleLabels),
+    byModel: groupOut(models),
+    failed,
+  };
+}
+
+export function cacheHitRate(u: { cacheHitTokens: number; cacheMissTokens: number }): number | null {
+  const total = u.cacheHitTokens + u.cacheMissTokens;
+  return total > 0 ? u.cacheHitTokens / total : null;
+}

package/src/core/event-store.ts

@@ -0,0 +1,304 @@
+/**
+ * 事件库:按 run 分片的 JSONL,`data/runs/<run>/events.jsonl` 一行一个 EventEnvelope。
+ * cursor 跨 run 全局单调:开机时从已有分片的末行续号。当前 run 常驻内存,更早的
+ * 分片按 cursor / ts 区间按需装载;range / around / grep 跨分片作答。
+ */
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type {
+  EventEnvelope,
+  EventGrepHit,
+  EventGrepQuery,
+  EventRangeQuery,
+  EventStore,
+  Logger,
+} from './types.ts';
+import { listRuns, runsDirOf } from './run.ts';
+import { nullLogger } from './util.ts';
+
+export interface JsonlEventStoreOptions {
+  dataDir: string;
+  /** 当前 run id;新事件写进它的分片 */
+  run: string;
+  log?: Logger;
+}
+
+interface Segment {
+  run: string;
+  file: string;
+  first: number;
+  last: number;
+  firstTs: string;
+  lastTs: string;
+  /** 装载后的记录,按 cursor 升序 */
+  events: EventEnvelope[] | null;
+}
+
+const EDGE_BYTES = 64 * 1024;
+const EVENTS_FILE = 'events.jsonl';
+
+function parseLine(line: string): EventEnvelope | null {
+  try {
+    const e = JSON.parse(line) as EventEnvelope;
+    return Number.isInteger(e.cursor) && typeof e.ts === 'string' ? e : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 不整读文件:头尾各取一段,拿首末两条的 cursor 与 ts。 */
+function readEdges(file: string): { first: EventEnvelope; last: EventEnvelope } | null {
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    if (size === 0) return null;
+    const headLen = Math.min(size, EDGE_BYTES);
+    const head = Buffer.alloc(headLen);
+    readSync(fd, head, 0, headLen, 0);
+    const headLines = head.toString('utf8').split('\n');
+    const first = headLines.map((l) => l.trim()).filter(Boolean).map(parseLine).find((e) => e !== null);
+    if (!first) return null;
+    const tailStart = Math.max(0, size - EDGE_BYTES);
+    const tail = Buffer.alloc(size - tailStart);
+    readSync(fd, tail, 0, size - tailStart, tailStart);
+    const tailLines = tail.toString('utf8').split('\n');
+    if (tailStart > 0) tailLines.shift();
+    const last = tailLines.map((l) => l.trim()).filter(Boolean).map(parseLine).reverse().find((e) => e !== null);
+    return { first, last: last ?? first };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function lowerBound(events: EventEnvelope[], cursor: number): number {
+  let lo = 0;
+  let hi = events.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (events[mid].cursor < cursor) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+export class JsonlEventStore implements EventStore {
+  private readonly log: Logger;
+  private readonly run: string;
+  private readonly segments: Segment[] = [];
+  private readonly current: Segment;
+  /** 下一条事件拿到的 cursor */
+  private next = 1;
+  /**
+   * 本实例记录的分片字节数；写入前的大小变化可能来自其他写入方。
+   * 用 stat 比较大小，避免每次追加都读取全部文件。
+   */
+  private expectedSize = 0;
+  /** 文件大小不符的错误只报告一次。 */
+  private concurrencyReported = false;
+  private appendListeners: Array<(e: EventEnvelope) => void> = [];
+
+  constructor(opts: JsonlEventStoreOptions) {
+    this.log = opts.log ?? nullLogger();
+    this.run = opts.run;
+    const runsDir = runsDirOf(opts.dataDir);
+    for (const id of listRuns(opts.dataDir)) {
+      if (id === this.run) continue;
+      const file = join(runsDir, id, EVENTS_FILE);
+      if (!existsSync(file)) continue;
+      let edges: { first: EventEnvelope; last: EventEnvelope } | null;
+      try {
+        edges = readEdges(file);
+      } catch (error) {
+        this.log.warn('事件分片读不出头尾,跳过', { run: id, err: error });
+        continue;
+      }
+      if (!edges) continue;
+      this.segments.push({
+        run: id, file, first: edges.first.cursor, last: edges.last.cursor,
+        firstTs: edges.first.ts, lastTs: edges.last.ts, events: null,
+      });
+      this.next = Math.max(this.next, edges.last.cursor + 1);
+    }
+    const currentFile = join(runsDir, this.run, EVENTS_FILE);
+    mkdirSync(join(runsDir, this.run), { recursive: true });
+    this.current = { run: this.run, file: currentFile, first: 0, last: 0, firstTs: '', lastTs: '', events: [] };
+    if (existsSync(currentFile)) {
+      const raw = readFileSync(currentFile, 'utf8');
+      this.expectedSize = Buffer.byteLength(raw, 'utf8');
+      this.current.events = this.parseAll(raw, this.run);
+      const events = this.current.events;
+      if (events.length) {
+        this.current.first = events[0].cursor;
+        this.current.last = events[events.length - 1].cursor;
+        this.current.firstTs = events[0].ts;
+        this.current.lastTs = events[events.length - 1].ts;
+        this.next = Math.max(this.next, this.current.last + 1);
+      }
+    }
+    this.segments.push(this.current);
+  }
+
+  private parseAll(raw: string, run: string): EventEnvelope[] {
+    const out: EventEnvelope[] = [];
+    let skipped = 0;
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      const e = parseLine(t);
+      if (!e) { skipped++; continue; }
+      if (out.length && e.cursor <= out[out.length - 1].cursor) { skipped++; continue; }
+      out.push(e);
+    }
+    if (skipped) this.log.warn('事件分片有损坏或乱序行,已跳过', { run, skipped });
+    return out;
+  }
+
+  private load(segment: Segment): EventEnvelope[] {
+    if (segment.events) return segment.events;
+    let raw = '';
+    try {
+      raw = readFileSync(segment.file, 'utf8');
+    } catch (error) {
+      this.log.warn('事件分片读取失败', { run: segment.run, err: error });
+    }
+    segment.events = this.parseAll(raw, segment.run);
+    return segment.events;
+  }
+
+  append(e: Omit<EventEnvelope, 'cursor'>): EventEnvelope {
+    this.checkExclusiveWrite();
+    const envelope: EventEnvelope = { ...e, cursor: this.next++, run: this.run };
+    const events = this.current.events!;
+    events.push(envelope);
+    if (events.length === 1) { this.current.first = envelope.cursor; this.current.firstTs = envelope.ts; }
+    this.current.last = envelope.cursor;
+    this.current.lastTs = envelope.ts;
+    const line = JSON.stringify(envelope) + '\n';
+    appendFileSync(this.current.file, line, 'utf8');
+    this.expectedSize += Buffer.byteLength(line, 'utf8');
+    for (const cb of this.appendListeners) {
+      try { cb(envelope); } catch { /* 观察者异常不影响主流程 */ }
+    }
+    return envelope;
+  }
+
+  /** 大小与本实例记录不符时报告文件变化，仍继续写入；独占检查由 instanceLock 负责。 */
+  private checkExclusiveWrite(): void {
+    if (this.concurrencyReported) return;
+    let onDisk = 0;
+    try {
+      onDisk = existsSync(this.current.file) ? statSync(this.current.file).size : 0;
+    } catch {
+      return; // 读不到文件状态不影响写入
+    }
+    if (onDisk === this.expectedSize) return;
+    this.concurrencyReported = true;
+    this.log.error('事件库被本进程之外的写入改动过,疑似另一个实例在写同一个事件库', {
+      expectedSize: this.expectedSize,
+      onDiskSize: onDisk,
+      file: this.current.file,
+    });
+    this.expectedSize = onDisk;
+  }
+
+  /** 事件追加订阅，供控制台实时观察。 */
+  onAppend(cb: (e: EventEnvelope) => void): void {
+    this.appendListeners.push(cb);
+  }
+
+  /** 当前 run 分片里的条数 */
+  currentCount(): number {
+    return this.current.events!.length;
+  }
+
+  get(cursor: number): EventEnvelope | undefined {
+    if (!Number.isInteger(cursor) || cursor < 1) return undefined;
+    const segment = this.segments.find((s) => s.first <= cursor && cursor <= s.last);
+    if (!segment) return undefined;
+    const events = this.load(segment);
+    const i = lowerBound(events, cursor);
+    return events[i]?.cursor === cursor ? events[i] : undefined;
+  }
+
+  latestCursor(): number {
+    return this.next - 1;
+  }
+
+  private segmentsIn(q: { fromCursor?: number; toCursor?: number; fromTs?: string; toTs?: string }): Segment[] {
+    return this.segments.filter((s) => {
+      if (s.last === 0) return s === this.current;
+      if (q.fromCursor !== undefined && s.last < q.fromCursor) return false;
+      if (q.toCursor !== undefined && s.first > q.toCursor) return false;
+      if (q.fromTs !== undefined && s.lastTs < q.fromTs) return false;
+      if (q.toTs !== undefined && s.firstTs > q.toTs) return false;
+      return true;
+    });
+  }
+
+  range(q: EventRangeQuery): EventEnvelope[] {
+    const matched: EventEnvelope[] = [];
+    for (const segment of this.segmentsIn(q)) {
+      const events = this.load(segment);
+      const start = q.fromCursor !== undefined ? lowerBound(events, q.fromCursor) : 0;
+      for (let i = start; i < events.length; i++) {
+        const e = events[i];
+        if (q.toCursor !== undefined && e.cursor > q.toCursor) break;
+        if (q.fromTs !== undefined && e.ts < q.fromTs) continue;
+        if (q.toTs !== undefined && e.ts > q.toTs) continue;
+        if (q.senderKey !== undefined && e.senderKey !== q.senderKey) continue;
+        if (q.source !== undefined && e.source !== q.source) continue;
+        if (q.origin !== undefined && e.origin !== q.origin) continue;
+        matched.push(e);
+      }
+    }
+    // limit从区间尾部取(最近优先),返回仍按游标升序
+    if (q.limit !== undefined && q.limit >= 0 && matched.length > q.limit) {
+      return matched.slice(matched.length - q.limit);
+    }
+    return matched;
+  }
+
+  around(cursor: number, before: number, after: number): EventEnvelope[] {
+    const latest = this.latestCursor();
+    if (latest === 0) return [];
+    const center = Math.min(Math.max(cursor, 1), latest);
+    return this.range({ fromCursor: center - Math.max(0, before), toCursor: center + Math.max(0, after) });
+  }
+
+  grep(q: EventGrepQuery): EventGrepHit[] {
+    const kw = q.keyword.toLowerCase();
+    const ctx = Math.max(0, q.context);
+    const hits: EventGrepHit[] = [];
+    for (const segment of this.segmentsIn(q)) {
+      for (const e of this.load(segment)) {
+        if (q.senderKey !== undefined && e.senderKey !== q.senderKey) continue;
+        if (q.source !== undefined && e.source !== q.source) continue;
+        if (q.origin !== undefined && e.origin !== q.origin) continue;
+        if (q.fromTs !== undefined && e.ts < q.fromTs) continue;
+        if (q.toTs !== undefined && e.ts > q.toTs) continue;
+        if (!e.text.toLowerCase().includes(kw)) continue;
+        // 邻近记录不经过筛选；重叠窗口保持分开。
+        hits.push({ hitCursor: e.cursor, events: this.around(e.cursor, ctx, ctx) });
+        if (q.limit !== undefined && hits.length >= q.limit) return hits;
+      }
+    }
+    return hits;
+  }
+
+  /**
+   * 清空当前 run 的分片(web 运维动作):删文件与内存里这一段,游标不回退,
+   * 更早的 run 不受影响。返回清掉的条数。
+   */
+  clear(): number {
+    const n = this.current.events!.length;
+    this.current.events = [];
+    this.current.first = 0;
+    this.current.last = 0;
+    this.current.firstTs = '';
+    this.current.lastTs = '';
+    if (existsSync(this.current.file)) rmSync(this.current.file);
+    this.expectedSize = 0;
+    this.log.warn('当前 run 的事件分片已清空', { cleared: n, run: this.run });
+    return n;
+  }
+}

package/src/core/fork.ts

@@ -0,0 +1,113 @@
+import type { Logger, ModelSpec, ToolCallContext, ToolDef } from './types.ts';
+import type { SessionHandle } from './sessions.ts';
+import { message, functionResult, responseRecords, type ContextRecord } from '../protocol/open-responses/context.ts';
+import { responseRequest, textOf } from '../protocol/open-responses/context-helpers.ts';
+import { ResponseAccumulator } from '../protocol/open-responses/stream.ts';
+import { GenerationError, type ResponseClient } from './generation.ts';
+import {
+  NOT_EXECUTED_BARRIER,
+  NOT_EXECUTED_INCOMPLETE,
+  NOT_EXECUTED_THREAD_ENDED,
+  forkUnknownTool,
+  toolFailed,
+} from './markers.ts';
+
+export interface ForkLoopOptions {
+  id: string;
+  llm: ResponseClient;
+  spec: ModelSpec;
+  messages: ContextRecord[];
+  tools: ToolDef[];
+  maxRounds: number;
+  softRounds?: number;
+  log: Logger;
+  stopWhen?: () => boolean;
+  wrapUpHint?: string;
+  capNote?: string;
+  nudge?: { when: (lastContent: string) => boolean; message: string };
+  track?: SessionHandle;
+  observeMessages?: (messages: ContextRecord[]) => void;
+}
+
+/** The caller hands the fork a client already bound to one provider instance; the Item sequence is retained across tool rounds. */
+export async function runForkLoop(opts: ForkLoopOptions): Promise<string> {
+  const { id, llm, spec, tools, maxRounds, log } = opts;
+  const messages = [...opts.messages];
+  const observed = [...messages];
+  opts.observeMessages?.(observed);
+  const ctx: ToolCallContext = { role: id, log };
+  const schemas = tools.map(({ name, description, parameters }) => ({ name, description, parameters }));
+  const wrapUpAt = Math.min(Math.max(1, opts.softRounds ?? maxRounds - 1), Math.max(1, maxRounds - 1));
+  const wrapUpHint = opts.wrapUpHint ?? 'Wrap up: give your conclusion next round, no more tool calls.';
+  let lastContent = '';
+  const runRound = async (round: number): Promise<'done' | 'continue'> => {
+    let draft = new ResponseAccumulator();
+    const settledLength = observed.length;
+    let generated;
+    try {
+      generated = await llm.respond(responseRequest(spec, messages, schemas), {
+        role: id, sessionId: opts.track?.id, context: messages, nativeSpec: spec,
+        onEvent: event => {
+          if (event.type === 'response.created') draft = new ResponseAccumulator();
+          draft.accept(event);
+          const snapshot = draft.snapshot();
+          if (snapshot) {
+            observed.splice(settledLength, observed.length - settledLength, ...snapshot.output.map(item => ({ version: 2 as const, item, context: { responseId: snapshot.id } })));
+          }
+        },
+      });
+    } catch (error) {
+      if (error instanceof GenerationError) opts.track?.recordAttempts(error.attempts, observed);
+      throw error;
+    }
+    const output = responseRecords(generated.response, generated.origin);
+    messages.push(...output);
+    observed.splice(settledLength, observed.length - settledLength, ...output);
+    opts.track?.recordAttempts(generated.attempts, observed);
+    const text = output.filter(entry => entry.item.type === 'message').map(textOf).join('');
+    if (text) lastContent = text;
+    const calls = generated.response.output.filter(item => item.type === 'function_call');
+    if (!calls.length) return 'done';
+    let barrier = false;
+    for (const [index, call] of calls.entries()) {
+      const def = tools.find(tool => tool.name === call.name);
+      let out: string;
+      let ended = false;
+      if (barrier) out = NOT_EXECUTED_BARRIER;
+      else if (call.status !== 'completed') { out = NOT_EXECUTED_INCOMPLETE; barrier = true; }
+      else if (!def) out = forkUnknownTool(call.name);
+      else {
+        try {
+          const args = JSON.parse(call.arguments || '{}') as Record<string, unknown>;
+          const result = await def.handler(args, { ...ctx, callId: call.call_id });
+          out = typeof result === 'string' ? result : result.text;
+          ended = def.endsTurn === true;
+        } catch (error) { out = toolFailed(error instanceof Error ? error.message : String(error)); }
+        if (def.barrierAfter) barrier = true;
+      }
+      if (round === wrapUpAt) out += `\n[system] ${wrapUpHint}`;
+      const receipt = functionResult(call.call_id, out);
+      messages.push(receipt); observed.push(receipt);
+      if (ended || opts.stopWhen?.()) {
+        for (const skipped of calls.slice(index + 1)) {
+          const receipt = functionResult(skipped.call_id, NOT_EXECUTED_THREAD_ENDED);
+          messages.push(receipt); observed.push(receipt);
+        }
+        return 'done';
+      }
+    }
+    return 'continue';
+  };
+  let finished = false;
+  for (let round = 1; round <= maxRounds; round++) {
+    if (await runRound(round) === 'done') { finished = true; break; }
+  }
+  if (!finished) log.warn('工具循环达到硬上限,取最后内容为结果', { maxRounds });
+  if (opts.nudge && !opts.stopWhen?.() && opts.nudge.when(lastContent)) {
+    const reminder = message('user', opts.nudge.message);
+    messages.push(reminder); observed.push(reminder);
+    await runRound(maxRounds);
+  }
+  if (!finished && opts.capNote) lastContent = lastContent ? `${lastContent}\n\n${opts.capNote}` : opts.capNote;
+  return lastContent;
+}