@bd7pil/reeve 0.0.0-stage → 0.1.0

package/src/stats.js

@@ -0,0 +1,384 @@
+// 性能统计：把 Bifrost 的调用日志与本地台账**聚合成面板要看的形状**。
+//
+// 分工（两条取数路径，别混）：
+//   · Bifrost 侧 = "请求级归因"：哪一档（routing_rule_name）、真打了谁（provider/model）、
+//     是第几跳回退（fallback_index）、成没成、多久。**只有 Bifrost 知道真模型是谁** ——
+//     引擎侧的 session 记录里模型名永远是 `reeve/pro` 这类别名（见 PROGRESS §6.2 归因边界）。
+//   · 编排侧 = "任务级台账"：谁派给了谁、跑多久、超时/停止/对账、在飞与排队。
+//
+// 取数顺序（每步降级，最后如实标 unavailable）：
+//   ① `GET /api/logs`（需 setup token —— 插件自己写的 600 文件）→ 实测形状见下
+//   ② 不产出统计：面板显示"拿不到"，并给出手工核对的办法
+// 为什么不做 logs.db 直读：引擎运行时里的 node:sqlite 版本未知（Bifrost 的库用了较新的
+// 索引语法，EL7 的 python3.6 读它直接报 malformed schema）—— 直读是**最后**的手段，先不做。
+//
+// **实测形状**（2026-10-19 EL7，Bifrost 2.3.0）：
+//   GET /api/logs?limit=N&offset=0[&sort_by=timestamp&order=desc|asc]
+//   → 200 `{ has_logs, logs:[…], pagination:{limit,offset,sort_by,order,total_count}, stats:{…} }`
+//   行里的关键字段：`id, timestamp(ISO, 纳秒), provider, model, fallback_index, number_of_retries,
+//   routing_rule_id, routing_rule_name, selected_key_name, latency(ms, 浮点), upstream_latency,
+//   overhead_latency, status('success'|'error'), stream, session_id, user_agent, app`
+//   · 排序参数生效（order=asc 拿到最旧的）；未知参数**被静默忽略**（试过 content=false 等一律无效）
+//   · `content_summary` 里是**完整提示词内容**，每行约 6.7 KB —— 聚合时一律丢掉（面板不该看内容）
+//   · 无 token → 401；limit 上限在 1000（5000 → 400）
+//   · `stats` 块除 total_requests 外全是 0，不可信 → 自己按行聚合
+//
+// 因此轮询策略：先 `limit=1` 探一下（`total_count` + 最新 id 就是"有没有变"的指纹），
+// 变了才抓 `limit` 行回来聚合 —— 空闲时每分钟只有一次 6 KB 的请求。
+
+export const STATS_DEFAULTS = Object.freeze({
+  /** 轮询间隔（unref 定时器，失败只记日志） */
+  intervalMs: 60_000,
+  /** 每次抓多少行（抓的是**最新**的若干行） */
+  limit: 100,
+  /** 聚合窗口：只有落在这个窗口里的行参与统计 */
+  windowMs: 24 * 60 * 60 * 1000,
+  /** 模型目录的刷新间隔（`/v1/models` 会真去上游探测并被 Bifrost 记日志 —— 别跟统计同频） */
+  modelsIntervalMs: 30 * 60 * 1000,
+  timeoutMs: 6_000,
+})
+
+/** 面板要的形状里保留哪些字段 —— 其余（尤其 content_summary）一律丢掉。 */
+const KEEP_FIELDS = [
+  'id',
+  'timestamp',
+  'provider',
+  'model',
+  'fallback_index',
+  'number_of_retries',
+  'routing_rule_id',
+  'routing_rule_name',
+  'selected_key_name',
+  'latency',
+  'upstream_latency',
+  'status',
+  'stream',
+  'session_id',
+  'prompt_tokens',
+  'completion_tokens',
+  'total_tokens',
+]
+
+// ── 纯函数（可测） ─────────────────────────────────────────────────────────
+
+/** 最近秩百分位（不做插值 —— 面板看的是"典型有多慢"，不是数学分位）。输入会被排序副本。 */
+export function percentile(values, p) {
+  const xs = (values ?? []).filter((v) => Number.isFinite(v)).sort((a, b) => a - b)
+  if (xs.length === 0) return null
+  const idx = Math.min(xs.length - 1, Math.max(0, Math.ceil(p * xs.length) - 1))
+  return xs[idx]
+}
+
+/** 一组延迟（毫秒）→ `{n, avg, p50, p95, max}`；一个数都没有就返回 n=0 的空壳。 */
+export function summarizeLatency(values) {
+  const xs = (values ?? []).filter((v) => Number.isFinite(v))
+  if (xs.length === 0) return { n: 0, avg: null, p50: null, p95: null, max: null }
+  const round = (v) => (v == null ? null : Math.round(v))
+  return {
+    n: xs.length,
+    avg: round(xs.reduce((s, v) => s + v, 0) / xs.length),
+    p50: round(percentile(xs, 0.5)),
+    p95: round(percentile(xs, 0.95)),
+    max: round(Math.max(...xs)),
+  }
+}
+
+/** `reeve/pro` → `pro`；不是 REEVE 的档位规则就返回 null（"不属于本层"）。 */
+export function tierOfRuleName(name) {
+  const m = /^reeve\/(flash|pro|multimodal)$/.exec(String(name ?? ''))
+  return m ? m[1] : null
+}
+
+/** 丢内容、留计数：面板只该看归因与延迟，不该看提示词。 */
+export function normalizeLogRow(row) {
+  const out = {}
+  for (const k of KEEP_FIELDS) if (k in row) out[k] = row[k]
+  return out
+}
+
+/** `provider/model` 的引用串（链里就是这个写法）。 */
+export function modelRef(row) {
+  return row?.provider && row?.model ? `${row.provider}/${row.model}` : null
+}
+
+export function parseTs(value) {
+  const t = Date.parse(String(value ?? ''))
+  return Number.isFinite(t) ? t : null
+}
+
+/**
+ * 抓回来的行 → 归因统计。
+ * `source` 只表达"这批数字从哪来"，`window` 里给出实际覆盖的时间范围（别让面板假装是 24h）。
+ *
+ * ⚠️ 两条实测出来的口径（都踩到过）：
+ *   · **`model` 为空的行不是调用**：那是 Bifrost 去上游探 `/v1/models` 的痕迹（rule 为 null、
+ *     model 为空串）。实测一次探测每 7 个 provider 就写 7 行 —— 混进来会把"调用次数"灌爆。
+ *     所以按"有 model"过滤，并如实报出过滤了多少行。
+ *   · **status 有三态**：`success` / `error` / `cancelled`（客户端把流掐了）。cancelled 不算失败。
+ */
+export function aggregateBifrostRows(rows, { now = Date.now(), windowMs = STATS_DEFAULTS.windowMs } = {}) {
+  const normalized = (rows ?? []).map(normalizeLogRow)
+  const withTs = normalized.map((r) => ({ row: r, at: parseTs(r.timestamp) }))
+  const probes = withTs.filter((x) => !x.row.model)
+  const calls = withTs.filter((x) => x.row.model)
+  const since = now - windowMs
+  const inWindow = calls.filter((x) => x.at != null && x.at >= since)
+  // 窗口内一条都没有（机器闲了很久）→ 退成"就用抓到的这些行"，并如实标 relaxed
+  const relaxed = inWindow.length === 0 && calls.length > 0
+  const used = relaxed ? calls : inWindow
+
+  const tiers = new Map()
+  const providers = new Map()
+  const models = new Map()
+  let fallbackHops = 0
+  let fallbackRequests = 0
+  const byIndex = {}
+  let ok = 0
+  let error = 0
+  let cancelled = 0
+  const latencies = []
+
+  for (const { row, at } of used) {
+    const isOk = row.status === 'success'
+    const isCancelled = row.status === 'cancelled'
+    if (isOk) ok += 1
+    else if (isCancelled) cancelled += 1
+    else error += 1
+    const lat = Number(row.latency)
+    if (Number.isFinite(lat)) latencies.push(lat)
+
+    const tier = tierOfRuleName(row.routing_rule_name)
+    const bucketKey = tier ?? '(非 REEVE 档位)'
+    const bucket =
+      tiers.get(bucketKey) ??
+      { tier, rule: row.routing_rule_name ?? null, n: 0, ok: 0, error: 0, cancelled: 0, fallbackRequests: 0, fallbackHops: 0, latency: [], providers: new Map() }
+    bucket.n += 1
+    if (isOk) bucket.ok += 1
+    else if (isCancelled) bucket.cancelled += 1
+    else bucket.error += 1
+    const fb = Number(row.fallback_index) || 0
+    if (fb > 0) {
+      bucket.fallbackRequests += 1
+      bucket.fallbackHops += fb
+      fallbackRequests += 1
+      fallbackHops += fb
+    }
+    byIndex[fb] = (byIndex[fb] ?? 0) + 1
+    if (Number.isFinite(lat)) bucket.latency.push(lat)
+    const ref = modelRef(row)
+    if (ref) bucket.providers.set(ref, (bucket.providers.get(ref) ?? 0) + 1)
+    tiers.set(bucketKey, bucket)
+
+    const p = providers.get(row.provider ?? '(未知)') ?? { provider: row.provider ?? '(未知)', n: 0, ok: 0, error: 0, cancelled: 0, latency: [], lastAt: null }
+    p.n += 1
+    if (isOk) p.ok += 1
+    else if (isCancelled) p.cancelled += 1
+    else p.error += 1
+    if (Number.isFinite(lat)) p.latency.push(lat)
+    if (at != null && (p.lastAt == null || at > p.lastAt)) p.lastAt = at
+    providers.set(p.provider, p)
+
+    if (ref) {
+      const m = models.get(ref) ?? { ref, provider: row.provider, model: row.model, n: 0, ok: 0, error: 0, lastAt: null }
+      m.n += 1
+      if (isOk) m.ok += 1
+      else if (!isCancelled) m.error += 1
+      if (at != null && (m.lastAt == null || at > m.lastAt)) m.lastAt = at
+      models.set(ref, m)
+    }
+  }
+
+  const tsList = used.map((x) => x.at).filter((v) => v != null)
+  const TIER_ORDER = ['flash', 'pro', 'multimodal']
+  const tierRows = [...tiers.values()]
+    .map((b) => ({
+      tier: b.tier,
+      rule: b.rule,
+      n: b.n,
+      ok: b.ok,
+      error: b.error,
+      cancelled: b.cancelled,
+      fallbackRequests: b.fallbackRequests,
+      fallbackHops: b.fallbackHops,
+      latency: summarizeLatency(b.latency),
+      providers: [...b.providers.entries()]
+        .map(([ref, n]) => ({ ref, n }))
+        .sort((a, b) => b.n - a.n),
+    }))
+    .sort((a, b) => {
+      const ia = a.tier ? TIER_ORDER.indexOf(a.tier) : 99
+      const ib = b.tier ? TIER_ORDER.indexOf(b.tier) : 99
+      return ia - ib || b.n - a.n
+    })
+
+  return {
+    window: {
+      ms: windowMs,
+      since: relaxed ? (tsList.length ? Math.min(...tsList) : null) : since,
+      until: tsList.length ? Math.max(...tsList) : null,
+      relaxed,
+    },
+    fetched: normalized.length,
+    probes: probes.length,
+    used: used.length,
+    total: used.length,
+    ok,
+    error,
+    cancelled,
+    latency: summarizeLatency(latencies),
+    fallback: { requests: fallbackRequests, hops: fallbackHops, byIndex },
+    byTier: tierRows,
+    byProvider: [...providers.values()]
+      .map((p) => ({ provider: p.provider, n: p.n, ok: p.ok, error: p.error, cancelled: p.cancelled, lastAt: p.lastAt, latency: summarizeLatency(p.latency) }))
+      .sort((a, b) => b.n - a.n),
+    byModel: [...models.values()].sort((a, b) => b.n - a.n).slice(0, 20),
+  }
+}
+
+/**
+ * 台账（本地记录）→ 每 agent 的任务级统计。
+ * 时长 = `endedAt - startedAt`（终态的才算；在飞的只报数）。
+ */
+export function aggregateLedger(records, { now = Date.now() } = {}) {
+  const byAgent = new Map()
+  const totals = { n: 0, ok: 0, error: 0, stopped: 0, running: 0, uncertain: 0, timedOut: 0 }
+  const durations = []
+  let firstAt = null
+  let lastAt = null
+  for (const r of records ?? []) {
+    const agent = r.agent ?? '(未标注)'
+    const b = byAgent.get(agent) ?? { agent, n: 0, ok: 0, error: 0, stopped: 0, running: 0, uncertain: 0, timedOut: 0, durations: [] }
+    b.n += 1
+    totals.n += 1
+    const state = String(r.state ?? '')
+    if (state === 'completed') {
+      b.ok += 1
+      totals.ok += 1
+    } else if (state === 'error') {
+      b.error += 1
+      totals.error += 1
+    } else if (state === 'stopped') {
+      b.stopped += 1
+      totals.stopped += 1
+    } else if (state === 'running') {
+      b.running += 1
+      totals.running += 1
+    }
+    if (r.statusUncertain === true) {
+      b.uncertain += 1
+      totals.uncertain += 1
+    }
+    if (r.timedOut === true) {
+      b.timedOut += 1
+      totals.timedOut += 1
+    }
+    const start = Number(r.startedAt)
+    const end = Number(r.endedAt)
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+      b.durations.push(end - start)
+      durations.push(end - start)
+    }
+    if (Number.isFinite(start) && (firstAt == null || start < firstAt)) firstAt = start
+    if (Number.isFinite(end) && (lastAt == null || end > lastAt)) lastAt = end
+    byAgent.set(agent, b)
+  }
+  return {
+    totals: { ...totals, uncertain: totals.uncertain },
+    window: { from: firstAt, until: lastAt, now },
+    latency: summarizeLatency(durations),
+    byAgent: [...byAgent.values()]
+      .map(({ durations: d, ...rest }) => ({ ...rest, latency: summarizeLatency(d) }))
+      .sort((a, b) => b.n - a.n),
+  }
+}
+
+/**
+ * 快照里的 `stats` 一节。
+ * `source` 三态：`bifrost.api`（拿到了）/ `unavailable`（拿不到，附 error）/ `disabled`。
+ */
+export function buildStats({ bifrost = null, orchestrate = null, now = Date.now(), windowMs = STATS_DEFAULTS.windowMs, source = 'unavailable', error = null, checkedAt = null } = {}) {
+  return { generatedAt: now, checkedAt, windowMs, source, error, bifrost, orchestrate }
+}
+
+// ── IO（薄，注入 fetch 便于测试） ────────────────────────────────────────────
+
+function headers(token) {
+  return token ? { 'X-Bifrost-Setup-Token': token } : {}
+}
+
+/**
+ * 抓日志。/api/logs 的 `pagination.total_count` + 最新一行的 id 就是"有没有新东西"的指纹。
+ * @returns {{rows: any[], total: number|null, signature: string|null, error: string|null}}
+ */
+export async function fetchBifrostLogs({
+  port,
+  host = '127.0.0.1',
+  token = null,
+  limit = STATS_DEFAULTS.limit,
+  offset = 0,
+  order = 'desc',
+  fetchImpl = fetch,
+  timeoutMs = STATS_DEFAULTS.timeoutMs,
+} = {}) {
+  const url = `http://${host}:${port}/api/logs?limit=${Number(limit)}&offset=${Number(offset)}&sort_by=timestamp&order=${order}`
+  try {
+    const res = await fetchImpl(url, { headers: headers(token), signal: AbortSignal.timeout(timeoutMs) })
+    if (res.status !== 200) return { rows: [], total: null, signature: null, error: `HTTP ${res.status}` }
+    const doc = await res.json()
+    // 实测是 `logs`；`data` 只是当年的消费假设，留着兜底
+    const rows = Array.isArray(doc?.logs) ? doc.logs : Array.isArray(doc?.data) ? doc.data : []
+    const total = Number(doc?.pagination?.total_count)
+    return {
+      rows,
+      total: Number.isFinite(total) ? total : null,
+      signature: `${Number.isFinite(total) ? total : '?'}:${rows[0]?.id ?? '(空)'}`,
+      error: null,
+    }
+  } catch (err) {
+    return { rows: [], total: null, signature: null, error: String(err?.message ?? err).slice(0, 140) }
+  }
+}
+
+/** Bifrost 自己发现出来的模型目录（`provider/model`）—— 面板选择器的候选来源之一。 */
+export async function fetchBifrostModels({ port, host = '127.0.0.1', fetchImpl = fetch, timeoutMs = STATS_DEFAULTS.timeoutMs } = {}) {
+  try {
+    const res = await fetchImpl(`http://${host}:${port}/v1/models`, { signal: AbortSignal.timeout(timeoutMs) })
+    if (res.status !== 200) return { models: [], error: `HTTP ${res.status}` }
+    const doc = await res.json()
+    const models = (Array.isArray(doc?.data) ? doc.data : [])
+      .map((m) => {
+        const ref = String(m?.id ?? '')
+        const i = ref.indexOf('/')
+        if (i <= 0) return null
+        return { ref, provider: ref.slice(0, i), model: ref.slice(i + 1), context: Number(m?.context_length) || null }
+      })
+      .filter(Boolean)
+    return { models, error: null }
+  } catch (err) {
+    return { models: [], error: String(err?.message ?? err).slice(0, 140) }
+  }
+}
+
+/**
+ * 面板选择器的候选 = 发现出来的 ∪ 链上已经在用的 ∪ 引擎注册的（reeve/*）。
+ * 为什么必须含"链上在用的"与"手工可填"：实测 `/v1/models` 只覆盖 4/7 个 provider
+ * （zhipuai-coding-plan 的对话路径是自定义的，`/v1/models` 探不到；opencode zen 与
+ * alibaba-cn 同理）。发现不全就如实标出来，而不是假装列表就是全集。
+ */
+export function mergeModelCandidates({ discovered = [], chained = [], engine = [] } = {}) {
+  const out = new Map()
+  const add = (m, source) => {
+    const ref = typeof m === 'string' ? m : m?.ref
+    // 认不出的、以及 `provider/`（同模型换 provider，不是完整引用）都丢掉
+    const i = String(ref ?? '').indexOf('/')
+    if (!ref || i <= 0 || i === ref.length - 1) return
+    const cur = out.get(ref) ?? { ref, provider: ref.slice(0, i), model: ref.slice(i + 1), context: null, sources: [] }
+    if (typeof m === 'object' && Number(m?.context)) cur.context = Number(m.context)
+    if (!cur.sources.includes(source)) cur.sources.push(source)
+    out.set(ref, cur)
+  }
+  for (const m of discovered) add(m, 'bifrost')
+  for (const ref of chained) add(ref, 'chain')
+  for (const m of engine) add(m, 'engine')
+  return [...out.values()].sort((a, b) => a.ref.localeCompare(b.ref))
+}

package/src/supervisor.js

@@ -0,0 +1,124 @@
+// 墙钟监督器：卡死的子任务要被掐掉。
+//
+// 规则（抄 omo-slim，MIT）：
+//   - **只监督 `background === true` 的任务**（前台的调用方自己在等，不需要第三方掐）
+//   - **每任务一次性定时器**；**只对新 generation 重新武装**
+//   - **忙碌 / 工具活动 / 存活信号都不续期**（卡死判定不能被"它还在动"这种信号骗过）
+//   - 到期后：先武装宽限定时器 → 再发**恰好一次** interrupt
+//   - 宽限到期仍未确认 → 标 statusUncertain 并落 error, timedOut
+//   - **已发布的硬超时不可被迟到的完成/忙碌替换**（由 Ledger.commitTerminal 的单调性保证）
+
+import {
+  DEFAULT_ABORT_GRACE_MS,
+  DEFAULT_MAX_ATTEMPTS,
+  REASON,
+  STATE,
+} from './constants.js'
+
+export class Supervisor {
+  #timers = new Map() // taskID -> { generation, timer, phase: 'wall' | 'grace' }
+
+  constructor({
+    ledger,
+    interrupt,
+    logger = console,
+    abortGraceMs = DEFAULT_ABORT_GRACE_MS,
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  }) {
+    this.ledger = ledger
+    this.interrupt = interrupt
+    this.logger = logger
+    this.abortGraceMs = abortGraceMs
+    this.maxAttempts = maxAttempts
+  }
+
+  /** 为一条记录武装墙钟。只有 background 任务、且未发布终态时才武装。 */
+  arm(taskID, wallClockMs) {
+    const record = this.ledger.get(taskID)
+    if (!record) return false
+    if (!record.background) return false
+    if (record.terminalPublished) return false
+
+    const existing = this.#timers.get(taskID)
+    if (existing && existing.generation === record.generation) {
+      // 同一个 generation 已经有定时器 —— 不重复武装，也**不续期**
+      return false
+    }
+    if (existing) clearTimeout(existing.timer)
+
+    const limit = Number(wallClockMs)
+    if (!Number.isFinite(limit) || limit <= 0) return false
+
+    const timer = setTimeout(() => this.#onExpiry(taskID, record.generation), limit)
+    timer.unref?.()
+    this.#timers.set(taskID, { generation: record.generation, timer, phase: 'wall' })
+    return true
+  }
+
+  /** 终态发布后拆除计时器。 */
+  disarm(taskID) {
+    const entry = this.#timers.get(taskID)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    this.#timers.delete(taskID)
+  }
+
+  /**
+   * 生成新 generation 时重新武装（例如重试）。
+   * **注意**：activity / busy 信号**不**走这里 —— 它们不该续期。
+   */
+  rearmIfNewGeneration(taskID, wallClockMs) {
+    const record = this.ledger.get(taskID)
+    if (!record) return false
+    const entry = this.#timers.get(taskID)
+    if (entry && entry.generation === record.generation) return false
+    return this.arm(taskID, wallClockMs)
+  }
+
+  async #onExpiry(taskID, generation) {
+    const record = this.ledger.get(taskID)
+    if (!record) return
+    // 迟到的定时器：generation 变了或已终态 —— 丢弃，不要覆盖
+    if (record.generation !== generation) return
+    if (record.terminalPublished) return
+
+    this.logger?.debug?.(`[reeve] 墙钟到期：${taskID}（子会话 ${record.childSessionID}）`)
+
+    // 先武装宽限定时器，再发中断 —— 顺序不能反
+    const graceTimer = setTimeout(() => this.#onGraceExpiry(taskID, generation), this.abortGraceMs)
+    graceTimer.unref?.()
+    this.#timers.set(taskID, { generation, timer: graceTimer, phase: 'grace' })
+
+    // 恰好一次。**发之前先打标**：宿主会因这次中断回 `execution.interrupted`，
+    // 事件处理器要靠 interruptReason 把它归因成"墙钟超时"而不是"宿主中断"。
+    if (record.interruptSent) return
+    this.ledger.update(taskID, { interruptSent: true, interruptReason: 'wall_clock' })
+    try {
+      await this.interrupt(record)
+    } catch (err) {
+      this.logger?.debug?.(`[reeve] 中断失败（${taskID}）：${String(err)}`)
+    }
+  }
+
+  async #onGraceExpiry(taskID, generation) {
+    const record = this.ledger.get(taskID)
+    if (!record) return
+    if (record.generation !== generation) return
+    if (record.terminalPublished) return
+
+    // 宽限到期仍未确认 —— 如实标"不确定"，并落超时终态。
+    this.ledger.commitTerminal(taskID, STATE.ERROR, {
+      source: 'wall-clock',
+      reason: REASON.WALL_CLOCK_TIMEOUT,
+      timedOut: true,
+      statusUncertain: true,
+      terminalUnreconciled: true,
+    })
+    this.#timers.delete(taskID)
+  }
+
+  stopAll() {
+    for (const entry of this.#timers.values()) clearTimeout(entry.timer)
+    this.#timers.clear()
+  }
+}

package/src/terminal-gate.js

@@ -0,0 +1,98 @@
+// 终态判定门 —— "静默死亡"的边界。
+//
+// 没有"子任务死了"这个事件，全靠推断。三处证据：
+//   ① 宿主事件（session.execution.*）—— 有就是有，可靠
+//   ② 子会话转录的分类（classifyTranscript）—— 判定终态 / 无终态 / 未知
+//   ③ 宿主 live-status 轮询（本实现不用轮询，靠 ①②）
+//
+// **关键设计（抄 omo-slim，MIT）**：`session.idle` 只是**候选**，不立即判定终止；
+// 只有当转录判定为 absent **且**静默已持续超过宽限期，才落 stopped。
+// 否则会把每个正常完成的子任务都误报成死亡。
+
+import { STOP_CONFIRMATION_GRACE_MS } from './constants.js'
+
+export const VERDICT = Object.freeze({
+  /** 转录里有明确的终态结果。 */
+  TERMINAL: 'terminal',
+  /** 转录里没有终态结果，且看起来已经不动了 —— 停止候选。 */
+  ABSENT: 'absent',
+  /** 看不出来（读不到、形状不认识等）—— 一律 fail-open，保持 running。 */
+  UNKNOWN: 'unknown',
+})
+
+/**
+ * 判定"静默是否已经稳定到可以下结论"。
+ *
+ * 用 max(最后一次观测到静默的时刻, 本次尝试的开始时刻) 作为基准 ——
+ * 前者防止把"刚开始跑"误判成"停了很久"，后者防止把"正常完成的最后一刻"误判成死亡。
+ */
+export function isStopStable({ quiescentSince, attemptStartedAt, graceMs, now = Date.now() }) {
+  const base = Math.max(quiescentSince ?? now, attemptStartedAt ?? 0)
+  return now - base >= graceMs
+}
+
+/**
+ * 决定是否落 stopped。
+ * @returns {{ stop: boolean, reason: string }}
+ */
+export function decideStop({
+  verdict,
+  quiescentSince = null,
+  attemptStartedAt = 0,
+  graceMs = STOP_CONFIRMATION_GRACE_MS,
+  now = Date.now(),
+}) {
+  if (verdict !== VERDICT.ABSENT) {
+    return { stop: false, reason: `verdict=${verdict}` }
+  }
+  const stable = isStopStable({ quiescentSince, attemptStartedAt, graceMs, now })
+  return stable
+    ? { stop: true, reason: 'transcript_absent_and_quiescent' }
+    : { stop: false, reason: 'still_within_grace' }
+}
+
+/**
+ * 从子会话转录里分类出终态证据。
+ *
+ * ⚠️ **输入形状未完全验证**：转录由 `ctx.session.context({ sessionID })` 取（施工图 §6），
+ * 其返回结构尚未实测。这里只做**形状容错**的保守判定：
+ *   - 认不出形状 → UNKNOWN（fail-open，保持 running，绝不下结论）
+ *   - 看到明确的失败/中断标记 → TERMINAL
+ *   - 看到 assistant 产出了内容 → TERMINAL（宿主会另行发 execution.succeeded）
+ *   - 什么都没有且消息列表为空 → ABSENT（停止候选）
+ */
+export function classifyTranscript(transcript) {
+  if (transcript == null) return VERDICT.UNKNOWN
+
+  const messages = pickMessages(transcript)
+  if (!messages) return VERDICT.UNKNOWN
+  if (messages.length === 0) return VERDICT.ABSENT
+
+  let sawAssistantContent = false
+  for (const m of messages) {
+    const role = m?.role ?? m?.info?.role
+    const text = extractText(m)
+    if (role === 'assistant' && text && text.length > 0) sawAssistantContent = true
+    const err = m?.error ?? m?.info?.error
+    if (err) return VERDICT.TERMINAL
+  }
+  return sawAssistantContent ? VERDICT.TERMINAL : VERDICT.ABSENT
+}
+
+function pickMessages(transcript) {
+  if (Array.isArray(transcript)) return transcript
+  if (Array.isArray(transcript.messages)) return transcript.messages
+  if (Array.isArray(transcript.history)) return transcript.history
+  if (Array.isArray(transcript.context?.messages)) return transcript.context.messages
+  return null
+}
+
+function extractText(m) {
+  const parts = m?.parts ?? m?.content ?? null
+  if (typeof parts === 'string') return parts
+  if (!Array.isArray(parts)) return null
+  return parts
+    .filter((p) => p && (p.type === 'text' || typeof p.text === 'string'))
+    .map((p) => p.text ?? '')
+    .join('')
+}