@bd7pil/reeve 0.0.0-stage → 0.1.0

package/src/reconcile.js

@@ -0,0 +1,141 @@
+// 跨重启对账 —— **本仓库唯一没有参照实现可抄的一块**。
+//
+// 语义（使用者裁决 = (b) 档）：**从父转录重建**。
+// 宿主不给会话列表 → **父会话的持久化转录是唯一事实源**。
+//
+// **惰性触发**：父会话**下一次活动时**才扫（挂 ctx.session.hook("prompt")），不是启动时扫。
+// 实测：`prompt` 钩子在回合一开始就触发，早于 `session.execution.started`（施工图 §14.7）。
+//
+// **明确不做**：不主动重新派发（会重复副作用）。
+// **如实标注**：恢复是 best-effort，别名与终态结果**不恢复**。
+
+import { REASON, STATE } from './constants.js'
+import { VERDICT, classifyTranscript as classify } from './terminal-gate.js'
+
+const RECONCILED_ONCE = new Set()
+
+/**
+ * 对账一个父会话。同一次进程生命周期内，每个父会话只跑一次。
+ * @returns {Promise<{ scanned: number, reconciled: number, notes: string[] }>}
+ */
+export async function reconcileParent({ ctx, ledger, logger, parentSessionID }) {
+  if (!parentSessionID) return { scanned: 0, reconciled: 0, notes: [] }
+  if (RECONCILED_ONCE.has(parentSessionID)) return { scanned: 0, reconciled: 0, notes: [] }
+  RECONCILED_ONCE.add(parentSessionID)
+
+  const notes = []
+  let scanned = 0
+  let reconciled = 0
+
+  // 只处理"重启前在飞"的记录：进程内本次新建的不需要探活。
+  const candidates = ledger
+    .all()
+    .filter((r) => r.parentSessionID === parentSessionID && r.state === STATE.RUNNING && r.statusUncertain)
+
+  if (candidates.length === 0) return { scanned: 0, reconciled: 0, notes: [] }
+
+  for (const record of candidates) {
+    if (ledger.isTombstoned(record.taskID)) continue
+    scanned += 1
+
+    if (!record.childSessionID) {
+      // 连子会话 id 都没留下 —— 无法探活，如实标未知，保持登记（fail-open）。
+      notes.push(`${record.taskID}: 无子会话 id，无法探活`)
+      continue
+    }
+
+    let probe
+    try {
+      probe = await ctx.session.get({ sessionID: record.childSessionID })
+    } catch (err) {
+      const msg = String(err)
+      if (isNotFound(msg)) {
+        // 子会话不存在 → 墓碑 + 拆除。**不要复活成永远在跑的幽灵。**
+        ledger.tombstone(record.taskID, REASON.CHILD_SESSION_MISSING)
+        notes.push(`${record.taskID}: 子会话已不存在 → 墓碑 + 拆除`)
+        reconciled += 1
+        continue
+      }
+      // 其他错误 → fail-open，保持登记。
+      notes.push(`${record.taskID}: 探活失败，保持登记（${msg.slice(0, 80)}）`)
+      continue
+    }
+
+    const outcome = extractOutcome(probe)
+    if (outcome) {
+      // 有终态 outcome → 落真实终态。
+      const mapped =
+        outcome === 'interrupted' ? STATE.STOPPED : outcome === 'failed' ? STATE.ERROR : STATE.COMPLETED
+      ledger.commitTerminal(record.taskID, mapped, {
+        source: 'reconcile',
+        reason: REASON.UNRECONCILED,
+        terminalUnreconciled: true,
+      })
+      notes.push(`${record.taskID}: 探到终态 ${outcome} → ${mapped}`)
+      reconciled += 1
+      continue
+    }
+
+    // 存在但空闲/无输出 → 停止候选（这里不宽限等待：对账发生在重启之后，
+    // 已经过了远超宽限的时间）。
+    let verdict = VERDICT.UNKNOWN
+    try {
+      const transcript = await ctx.session.context({ sessionID: record.childSessionID })
+      verdict = classify(transcript)
+    } catch (err) {
+      notes.push(`${record.taskID}: 读转录失败（${String(err).slice(0, 80)}）`)
+    }
+
+    if (verdict === VERDICT.TERMINAL) {
+      ledger.commitTerminal(record.taskID, STATE.COMPLETED, {
+        source: 'reconcile',
+        reason: REASON.UNRECONCILED,
+        terminalUnreconciled: true,
+      })
+      notes.push(`${record.taskID}: 转录显示有终态结果 → completed（unreconciled）`)
+      reconciled += 1
+    } else if (verdict === VERDICT.ABSENT) {
+      ledger.commitTerminal(record.taskID, STATE.STOPPED, {
+        source: 'reconcile',
+        reason: REASON.UNRECONCILED,
+        terminalUnreconciled: true,
+        statusUncertain: true,
+      })
+      notes.push(`${record.taskID}: 存在但无终态结果 → stopped（unreconciled）`)
+      reconciled += 1
+    } else {
+      notes.push(`${record.taskID}: 证据不足，保持登记（fail-open）`)
+    }
+  }
+
+  logger?.debug?.(`[reeve] 对账 ${parentSessionID}：扫 ${scanned}，落定 ${reconciled}`)
+  return { scanned, reconciled, notes }
+}
+
+/** 仅供测试：重置"每个父会话只对账一次"的门。 */
+export function _resetReconcileGate() {
+  RECONCILED_ONCE.clear()
+}
+
+function isNotFound(message) {
+  return /not\s*found|NotFound|no such session|unknown session/i.test(message)
+}
+
+/**
+ * 从 `ctx.session.get()` 的返回里提取终态 outcome。
+ * ⚠️ 返回结构未完全实测，做形状容错；认不出就返回 null（fail-open）。
+ */
+function extractOutcome(probe) {
+  if (!probe || typeof probe !== 'object') return null
+  const candidates = [
+    probe.outcome,
+    probe.session?.outcome,
+    probe.info?.outcome,
+    probe.session?.info?.outcome,
+    probe.execution?.outcome,
+  ]
+  for (const c of candidates) {
+    if (typeof c === 'string' && ['succeeded', 'failed', 'interrupted'].includes(c)) return c
+  }
+  return null
+}

package/src/register.js

@@ -0,0 +1,137 @@
+// 运行时注册：把 agent 与 skill **从插件自己的包里**注册进引擎。
+//
+// 为什么这么做（使用者："像 omo 一样"）：omo 的 agent 与 prompt 都在插件里，配置只有一行。
+// 搬进来之后，**配置目录里不再需要 agent/ 与 skill/ 两个目录**，也不用往那儿拷文件。
+//
+// 提示词仍是 markdown（`plugin/agents/*.md`、`plugin/skills/<name>/*.md`）——
+// 它们是插件包的一部分，改提示词就改这些文件；代价是**面板改不了**（那是刻意的，见 §6.1）。
+//
+// 三条纪律：
+//   1. **配置优先**：引擎里已经有的（配置目录里的 md、用户的覆盖）一律不动，只补缺的；
+//   2. 建出来的 agent 该 hidden 的就 hidden（前台只留编排者）；
+//   3. skill 的 content 里会把真实的绝对路径填进去 —— 因为配套的 rubric 文件也在插件包里，
+//      模型要靠那个路径去读它们。
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const PLUGIN_ROOT = fileURLToPath(new URL('..', import.meta.url))
+export const AGENTS_DIR = join(PLUGIN_ROOT, 'agents')
+export const SKILLS_DIR = join(PLUGIN_ROOT, 'skills')
+
+/** 极小的 frontmatter 解析：只认我们的 md 用的那几个键（够用，不引依赖）。 */
+/** 去掉一层引号（我们的 md 里 `resource: "*"` 是带引号的 YAML 写法）。 */
+function unquote(v) {
+  const t = String(v).trim()
+  if (t.length >= 2 && ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")))) {
+    return t.slice(1, -1)
+  }
+  return t
+}
+
+export function parseFrontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(String(text))
+  if (!m) return { data: {}, body: String(text).trim() }
+  const data = {}
+  const lines = m[1].split(/\r?\n/)
+  let current = null
+  for (const line of lines) {
+    if (/^\s*$/.test(line)) continue
+    const top = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line)
+    if (top) {
+      const [, key, raw] = top
+      if (raw === '') {
+        current = key
+        data[key] = key === 'permissions' ? [] : null
+      } else {
+        current = null
+        data[key] = unquote(raw)
+      }
+      continue
+    }
+    const item = /^\s*-\s+([A-Za-z_][\w-]*):\s*(.*)$/.exec(line)
+    if (item && current === 'permissions' && Array.isArray(data[current])) {
+      data[current].push({ [item[1]]: unquote(item[2]) })
+      continue
+    }
+    const cont = /^\s+([A-Za-z_][\w-]*):\s*(.*)$/.exec(line)
+    if (cont && current === 'permissions' && Array.isArray(data[current]) && data[current].length > 0) {
+      Object.assign(data[current][data[current].length - 1], { [cont[1]]: unquote(cont[2]) })
+    }
+  }
+  return { data, body: m[2].trim() }
+}
+
+/** md → 引擎要的 agent 形状（`ctx.agent.transform` 里 `editor.update(id, a => Object.assign(a, ...))`）。 */
+export function toAgentInfo(id, text) {
+  const { data, body } = parseFrontmatter(text)
+  const info = {
+    id,
+    name: id,
+    description: typeof data.description === 'string' ? data.description : undefined,
+    system: body.length > 0 ? body : undefined,
+    mode: ['primary', 'subagent', 'all'].includes(data.mode) ? data.mode : 'subagent',
+  }
+  if (data.hidden === 'true') info.hidden = true
+  if (typeof data.model === 'string' && data.model.includes('/')) {
+    const [providerID, ...rest] = data.model.split('/')
+    info.model = { providerID, id: rest.join('/') }
+  }
+  if (Array.isArray(data.permissions)) {
+    info.permissions = data.permissions
+      .filter((p) => p && p.action && p.resource && p.effect)
+      .map((p) => ({ action: p.action, resource: p.resource, effect: p.effect }))
+  }
+  return info
+}
+
+/** 读插件包里的 agents/*.md。 */
+export async function loadAgents({ dir = AGENTS_DIR, readdirImpl = readdir, readFileImpl = readFile } = {}) {
+  const out = []
+  let files = []
+  try {
+    files = (await readdirImpl(dir)).filter((f) => f.endsWith('.md')).sort()
+  } catch {
+    return out
+  }
+  for (const f of files) {
+    try {
+      const text = await readFileImpl(join(dir, f), 'utf8')
+      out.push(toAgentInfo(f.replace(/\.md$/, ''), text))
+    } catch {
+      /* 读不到就跳过 —— 宁可少注册，也不要把插件加载搞崩 */
+    }
+  }
+  return out
+}
+
+/** 读插件包里的 skills/<name>/SKILL.md；content 里把真实路径填进去（配套 rubric 靠它定位）。 */
+export async function loadSkills({ dir = SKILLS_DIR, readdirImpl = readdir, readFileImpl = readFile } = {}) {
+  const out = []
+  let entries = []
+  try {
+    entries = await readdirImpl(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (!e.isDirectory?.()) continue
+    const file = join(dir, e.name, 'SKILL.md')
+    try {
+      const text = await readFileImpl(file, 'utf8')
+      const { data, body } = parseFrontmatter(text)
+      out.push({
+        id: e.name,
+        name: typeof data.name === 'string' ? data.name : e.name,
+        description: typeof data.description === 'string' ? data.description.replace(/\s+/g, ' ').trim() : undefined,
+        path: file,
+        // 把 skill 自己的目录塞进正文 —— rubric 文件住在插件包里，模型得知道绝对路径
+        content: `（本 skill 的目录：${join(dir, e.name)}）\n\n${body}`,
+      })
+    } catch {
+      /* 同一个 skill 有问题不影响其它 */
+    }
+  }
+  return out
+}

package/src/roster.js

@@ -0,0 +1,44 @@
+// subagent 名册 —— 注入到 `subagent` 工具的描述里。
+//
+// 为什么需要它：REEVE 的 7 个 subagent 都标了 `hidden: true`（前台不可见、
+// openchamber 的 @ 提及列表也不列它们）。代价是**引擎自己的
+// "Available subagents:" 宣传段也会把它们滤掉**（v2.0.32
+// `packages/core/src/tool/plugin/subagent.ts` 的 context 钩子只列 `!agent.hidden`）。
+// → 于是由本插件把名册**补回工具描述**：人看不见，模型看得见。
+//
+// 这份名册与 `agents/*.md` 一一对应（名字必须逐字一致，否则 subagent 工具会回
+// "Unknown agent"）。`plugin/test/unit.mjs` 里有一条测试盯着"名字不漂移"。
+
+export const ROSTER_MARKER = 'REEVE 名册'
+
+/** name = agents/<name>.md 的文件名；duty 与那些文件的 description 同义。 */
+export const SUBAGENT_ROSTER = Object.freeze([
+  { name: 'scout', duty: '代码库侦察：回答"X 在哪里、怎么工作的"，带 路径:行号。只读' },
+  { name: 'librarian', duty: '外部资料检索：外部库/规范/上游怎么规定的，每条带 URL。只读' },
+  { name: 'planner', duty: '把需求写成"不携带上下文的执行者也能照着干完"的实施文档。不写代码' },
+  { name: 'critic', duty: '计划评审：多轮 × 多角度，默认立场是不通过。只读' },
+  { name: 'advisor', duty: '对抗性顾问：找出方案最可能失败的那个假设与代价。只读' },
+  { name: 'executor', duty: '执行者：照实施文档干活，唯一的实现者。不重新设计、不扩大范围' },
+  { name: 'reviewer', duty: '代码 diff 审查：五维 + 结构化输出（severity/category/path/行号/锚点）。只读' },
+])
+
+/**
+ * 生成要追加到 `subagent` 工具描述后面的段落。
+ * @param {ReadonlyArray<{name:string,duty:string}>} roster
+ */
+export function buildSubagentRoster(roster = SUBAGENT_ROSTER) {
+  return [
+    `可用 subagent（${ROSTER_MARKER} —— 它们在前台不可见，只能由你委派；\`agent\` 参数逐字取下面的名字）：`,
+    ...roster.map((a) => `- ${a.name}: ${a.duty}`),
+  ].join('\n')
+}
+
+/**
+ * 幂等地把名册接进一段工具描述：已经有标记就原样返回（钩子每回合都会触发）。
+ * @returns {string}
+ */
+export function withRoster(description, roster = SUBAGENT_ROSTER) {
+  const base = typeof description === 'string' ? description : ''
+  if (base.includes(ROSTER_MARKER)) return base
+  return base.length > 0 ? `${base}\n\n${buildSubagentRoster(roster)}` : buildSubagentRoster(roster)
+}

package/src/snapshot.js

@@ -0,0 +1,171 @@
+// 台账快照：把内存里的账**投影**成一份 JSON 文件，给只读面板（openchamber 扩展）读。
+//
+// 为什么是"投影"而不是"第二份真相"：
+//   权威仍然是 ctx.storage 里的记录；这个文件只是给人看的视图。
+//   面板**只读**它，永远不会写回 —— 也就不会出现两处互相覆盖。
+//
+// 为什么用文件而不是让面板读 ctx.storage：
+//   面板跑在 openchamber 的 iframe 里（浏览器环境、有 CSP、无网络），
+//   拿不到引擎的 SQLite；而宿主给了它一个 `readFile` 能力。
+//   → 文件是两边唯一都够得着的通道。
+//
+// 原子性：先写 `<path>.tmp` 再 rename。面板永远看不到半截 JSON。
+// 失败只记日志：**记账的正确性绝不依赖这个文件**。
+
+import { mkdir, rename, writeFile, unlink } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export class SnapshotWriter {
+  #path
+  #logger
+  #debounceMs
+  #timer = null
+  #building = null
+  #dirty = false
+
+  constructor({ path, logger = console, debounceMs = 250 } = {}) {
+    if (!path) throw new Error('SnapshotWriter 需要 path')
+    this.#path = path
+    this.#logger = logger
+    this.#debounceMs = debounceMs
+  }
+
+  get path() {
+    return this.#path
+  }
+
+  /** 记账变了：合并成一次写（250ms 内的连续变化只落一次盘）。 */
+  schedule(build) {
+    this.#building = build
+    this.#dirty = true
+    if (this.#timer) return
+    this.#timer = setTimeout(() => {
+      this.#timer = null
+      void this.flush()
+    }, this.#debounceMs)
+    // 定时器不该拖住进程退出（Node 独有；宿主里 also fine）
+    this.#timer?.unref?.()
+  }
+
+  cancel() {
+    if (this.#timer) clearTimeout(this.#timer)
+    this.#timer = null
+  }
+
+  /** 立刻写一次。返回是否真的写了（false = 没有变化）。 */
+  async flush() {
+    if (!this.#dirty || !this.#building) return false
+    this.#dirty = false
+    let doc
+    try {
+      doc = this.#building()
+    } catch (err) {
+      this.#logger?.debug?.(`[reeve] 快照构建失败（忽略）：${String(err)}`)
+      return false
+    }
+    const tmp = `${this.#path}.tmp`
+    try {
+      await mkdir(dirname(this.#path), { recursive: true })
+      await writeFile(tmp, JSON.stringify(doc, null, 2), 'utf8')
+      await rename(tmp, this.#path)
+      return true
+    } catch (err) {
+      this.#logger?.debug?.(`[reeve] 快照写入失败（忽略）：${String(err)}`)
+      try {
+        await unlink(tmp)
+      } catch {
+        /* 清不掉就算了 */
+      }
+      return false
+    }
+  }
+}
+
+/**
+ * 把台账投影成面板要的形状。
+ * **注意**：这里刻意只放面板显示需要的字段 —— 不多不少，免得这份文件变成事实上的第二套接口。
+ *
+ * `agents`：启动时从引擎读到的 agent 表（谁在前台可见 / 谁被藏）。
+ * 为什么放进快照：`opencode debug agents` 走的是 CLI 自己连的那个服务，
+ * 未必是你以为的那个引擎（实测踩过 —— 它连到另一个 HOME 的服务，报出别人的表）。
+ * 这一份是**引擎进程内部**读的，落盘可核对，也是"前台只出现编排者"这条设计的证据。
+ */
+export function buildSnapshot(
+  records,
+  { now = Date.now(), version = null, agents = null, roster = null, proxy = null, registered = null, endpoint = null, chain = null, models = null, stats = null } = {},
+) {
+  const tasks = records
+    .map((r) => ({
+      taskID: r.taskID,
+      parentSessionID: r.parentSessionID ?? null,
+      childSessionID: r.childSessionID ?? null,
+      agent: r.agent ?? null,
+      description: r.description ?? null,
+      background: r.background === true,
+      state: r.state ?? null,
+      reason: r.reason ?? null,
+      terminalSource: r.terminalSource ?? null,
+      timedOut: r.timedOut === true,
+      statusUncertain: r.statusUncertain === true,
+      startedAt: r.startedAt ?? null,
+      endedAt: r.endedAt ?? null,
+    }))
+    .sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0))
+
+  const counts = { total: tasks.length, running: 0, completed: 0, error: 0, stopped: 0, reconciled: 0 }
+  for (const t of tasks) {
+    if (Object.prototype.hasOwnProperty.call(counts, t.state)) counts[t.state] += 1
+  }
+
+  return {
+    generatedAt: now,
+    plugin: 'reeve',
+    version,
+    agentTable: agents,
+    roster,
+    proxy,
+    chain: chain == null ? null : projectChain(chain),
+    models,
+    registered,
+    endpoint,
+    stats,
+    counts,
+    tasks,
+  }
+}
+
+/**
+ * 链的状态 → 面板要的那一小块。
+ * `tiers` 就是 `~/.reeve/chain.json` 里那份形状（面板编辑的就是它，写回也是它）。
+ */
+export function projectChain(chain) {
+  if (!chain) return null
+  return {
+    tiersPath: chain.tiersPath ?? null,
+    source: chain.source ?? null,
+    from: chain.from ?? null,
+    derived: chain.derived === true,
+    tiers: chain.tiers ?? null,
+    problems: chain.problems ?? [],
+    error: chain.error ?? null,
+    changedAt: chain.changedAt ?? null,
+    appliedAt: chain.appliedAt ?? null,
+    drift: chain.drift ?? null,
+    lastError: chain.lastError ?? null,
+  }
+}
+
+/**
+ * 从 `ctx.agent.list()` 的返回里抽出"谁可见"的最小形状。
+ * 读不到就返回 null —— 快照里没有这一节，不假装知道。
+ */
+export function projectAgentTable(list) {
+  if (!Array.isArray(list)) return null
+  const one = (a) => ({ id: a?.id ?? null, mode: a?.mode ?? null, hidden: a?.hidden === true })
+  return {
+    total: list.length,
+    visible: list.filter((a) => a?.mode !== 'subagent' && a?.hidden !== true).map(one),
+    hidden: list.filter((a) => a?.hidden === true).map(one),
+    subagent: list.filter((a) => a?.mode === 'subagent' && a?.hidden !== true).map(one),
+  }
+}