@bd7pil/reeve 0.0.0-stage → 0.1.0

package/src/ledger.js

@@ -0,0 +1,253 @@
+// REEVE 台账：子任务登记表。
+//
+// 为什么必须自持：opencode v2 **不把 session.list / session.children / session.status 交给插件**
+// （施工图 §6）。所以"谁在跑、谁死了"这份账只能插件自己记。
+//
+// 两条正确性性质（本项目最贵的 bug 是"静默不一致"，不是崩溃）：
+//   1. 终态一旦发布就**不可被迟到的完成/忙碌覆盖**（commitTerminal 的单调性）
+//   2. 墓碑一旦立下就**不可复活**（跨重启对账不要造出永远在跑的幽灵）
+
+import { STORAGE_PREFIX, STATE, TERMINAL_STATES, newRecord } from './constants.js'
+
+export class Ledger {
+  /** @type {Map<string, object>} taskID -> record */
+  #records = new Map()
+  /** @type {Map<string, string>} childSessionID -> taskID */
+  #byChild = new Map()
+  /** @type {Set<string>} 已墓碑的 taskID —— 永不复活 */
+  #tombstones = new Set()
+
+  constructor({ storage = null, logger = console } = {}) {
+    this.storage = storage
+    this.logger = logger
+    // 变更通知：给只读快照用。**同步、绝不 await** —— 记账不能被视图拖慢。
+    this.onChange = null
+  }
+
+  #changed() {
+    try {
+      this.onChange?.()
+    } catch {
+      /* 视图的问题不是记账的问题 */
+    }
+  }
+
+  static storageKey(taskID) {
+    return STORAGE_PREFIX + taskID
+  }
+
+  create(rec) {
+    const record = newRecord(rec)
+    this.#records.set(record.taskID, record)
+    if (record.childSessionID) this.#byChild.set(record.childSessionID, record.taskID)
+    void this.persist(record.taskID)
+    this.#changed()
+    return record
+  }
+
+  get(taskID) {
+    return this.#records.get(taskID) ?? null
+  }
+
+  /** 子会话 id 是 `subagent` 工具的输出解析出来的，可能晚于创建。 */
+  attachChild(taskID, childSessionID) {
+    const record = this.#records.get(taskID)
+    if (!record || !childSessionID) return record ?? null
+    record.childSessionID = childSessionID
+    this.#byChild.set(childSessionID, taskID)
+    void this.persist(taskID)
+    this.#changed()
+    return record
+  }
+
+  forChildSession(childSessionID) {
+    const taskID = this.#byChild.get(childSessionID)
+    return taskID ? (this.#records.get(taskID) ?? null) : null
+  }
+
+  update(taskID, patch) {
+    const record = this.#records.get(taskID)
+    if (!record) return null
+    Object.assign(record, patch)
+    record.lastActivityAt = Date.now()
+    void this.persist(taskID)
+    this.#changed()
+    return record
+  }
+
+  /**
+   * 落终态。**单调**：已发布的终态不会被再次写入覆盖。
+   * @returns {boolean} 是否真的写入了（false = 已有终态，被拒绝）
+   */
+  commitTerminal(taskID, state, { source = null, reason = null, ...extra } = {}) {
+    const record = this.#records.get(taskID)
+    if (!record) return false
+    if (record.terminalPublished) {
+      this.logger?.debug?.(
+        `[reeve] 拒绝覆盖已发布的终态：${taskID} 已是 ${record.state}，忽略迟到的 ${state}`,
+      )
+      return false
+    }
+    if (!TERMINAL_STATES.has(state)) return false
+    Object.assign(record, extra, {
+      state,
+      reason,
+      terminalSource: source,
+      terminalPublished: true,
+      endedAt: Date.now(),
+      statusUncertain: extra.statusUncertain ?? false,
+    })
+    void this.persist(taskID)
+    this.#changed()
+    return true
+  }
+
+  /** 在飞的（父会话维度）。parentSessionID 省略则返回全部在飞的。 */
+  running(parentSessionID = null) {
+    const out = []
+    for (const r of this.#records.values()) {
+      if (r.state !== STATE.RUNNING) continue
+      if (parentSessionID && r.parentSessionID !== parentSessionID) continue
+      out.push(r)
+    }
+    return out
+  }
+
+  all() {
+    return [...this.#records.values()]
+  }
+
+  tombstone(taskID, reason) {
+    this.#tombstones.add(taskID)
+    const record = this.#records.get(taskID)
+    if (record) {
+      // 拆除：不留幽灵。终态为 reconciled，明确标"不是正常结束"。
+      this.commitTerminal(taskID, STATE.RECONCILED, {
+        source: 'reconcile',
+        reason,
+        terminalUnreconciled: true,
+      })
+      if (record.childSessionID) this.#byChild.delete(record.childSessionID)
+    }
+    void this.persist(taskID)
+    this.#changed()
+  }
+
+  isTombstoned(taskID) {
+    return this.#tombstones.has(taskID)
+  }
+
+  // ---- 持久化（best-effort，绝不因为落盘失败而打断记账）----
+
+  async persist(taskID) {
+    if (!this.storage) return
+    const record = this.#records.get(taskID)
+    if (!record) return
+    try {
+      await this.storage.set(Ledger.storageKey(taskID), toJson(record))
+      if (this.#tombstones.has(taskID)) {
+        await this.storage.set(Ledger.storageKey(taskID) + '.tombstone', true)
+      }
+    } catch (err) {
+      this.logger?.debug?.(`[reeve] 台账落盘失败（忽略）：${String(err)}`)
+    }
+  }
+
+  /**
+   * 启动时把盘上的账读回来。
+   * **注意**：恢复是 best-effort，别名与终态结果**不恢复**；
+   * 重启时仍在 running 的记录一律标 statusUncertain —— **如实标未知，不谎报**。
+   *
+   * @returns {Promise<{loaded:number, truncated:boolean, pages:number}>}
+   *   `truncated: true` = 存储没有返回游标但取满了一页，**可能还有没读到的记录**。
+   *   这是"静默不一致"的一个入口，所以**不吞掉**，交给调用方决定怎么报。
+   */
+  async hydrate() {
+    if (!this.storage?.scan) return { loaded: 0, truncated: false, pages: 0 }
+    let loaded = 0
+    let pages = 0
+    let truncated = false
+    const PAGE = 500
+    try {
+      let after
+      for (;;) {
+        const page = await this.storage.scan({ prefix: STORAGE_PREFIX, after, limit: PAGE })
+        const entries = page?.entries ?? []
+        pages += 1
+        for (const entry of entries) {
+          if (entry.key.endsWith('.tombstone')) {
+            this.#tombstones.add(entry.key.slice(0, -'.tombstone'.length).replace(STORAGE_PREFIX, ''))
+            continue
+          }
+          const record = fromJson(entry.value)
+          if (!record?.taskID) continue
+          this.#records.set(record.taskID, record)
+          if (record.childSessionID) this.#byChild.set(record.childSessionID, record.taskID)
+          loaded += 1
+        }
+        if (!page?.next) {
+          // 取满一页却没有游标 —— 存储可能不支持分页。如实标记，别假装读全了。
+          if (entries.length >= PAGE) truncated = true
+          break
+        }
+        after = page.next
+      }
+    } catch (err) {
+      this.logger?.debug?.(`[reeve] 台账恢复失败（忽略）：${String(err)}`)
+      return { loaded, truncated, pages }
+    }
+
+    if (truncated) {
+      this.logger?.debug?.(
+        `[reeve] ⚠️ 台账恢复可能不完整：scan 取满 ${PAGE} 条但没有返回游标（已恢复 ${loaded} 条）。` +
+          `未读到的记录不会出现在台账里 —— 这是静默不一致，请检查 ctx.storage.scan 的分页。`,
+      )
+    }
+
+    // 重启后仍在 running 的一律标未知 —— 不要谎报 running，也不要谎报 completed。
+    for (const record of this.#records.values()) {
+      if (record.state === STATE.RUNNING) {
+        record.statusUncertain = true
+        record.reason = 'host_restarted'
+      }
+    }
+    if (loaded > 0) this.#changed()
+    return { loaded, truncated, pages }
+  }
+
+  /**
+   * 保留期修剪：删掉**已落终态**且超过保留期的记录，以及过期的墓碑。
+   * **只动终态**——在飞记录永不修剪（哪怕很老，那也是"账还没结"）。
+   * 为什么需要：台账只增不减，跑一年会攒到几万条 → 启动扫描变慢、内存与盘都涨。
+   * @returns {Promise<number>} 删掉的条数
+   */
+  async prune({ olderThanMs = 30 * 24 * 60 * 60 * 1000, now = Date.now() } = {}) {
+    const cutoff = now - olderThanMs
+    let removed = 0
+    for (const [taskID, record] of [...this.#records.entries()]) {
+      if (record.state === STATE.RUNNING) continue // 在飞的一律不动
+      if (!record.endedAt || record.endedAt > cutoff) continue
+      this.#records.delete(taskID)
+      if (record.childSessionID) this.#byChild.delete(record.childSessionID)
+      this.#tombstones.delete(taskID)
+      try {
+        await this.storage?.remove?.(Ledger.storageKey(taskID))
+        await this.storage?.remove?.(Ledger.storageKey(taskID) + '.tombstone')
+      } catch (err) {
+        this.logger?.debug?.(`[reeve] 修剪落盘失败（忽略）：${String(err)}`)
+      }
+      removed += 1
+    }
+    if (removed > 0) this.#changed()
+    return removed
+  }
+}
+
+function toJson(record) {
+  return JSON.parse(JSON.stringify(record))
+}
+
+function fromJson(value) {
+  if (!value || typeof value !== 'object') return null
+  return { ...value }
+}

package/src/models.js

@@ -0,0 +1,114 @@
+// 三个档位的**模型注册** —— 让 opencode.jsonc 里不再需要一份 models 映射。
+//
+// 为什么能做：v2 的插件 API 有 `ctx.provider.transform(editor => editor.models.set(id, models))`
+//（`packages/plugin/src/promise/provider.ts` @v2.0.27），`Model.Info` 也能从最小形状造出来。
+//
+// 规则（顺序即优先级）：
+//   - 配置里已经写了的模型条目**不动**（配置说话时以配置为准）；
+//   - 只补上缺的那几个档位；
+//   - 端点（baseURL / key）**插件注册不了** —— `Provider.Info` 只有 {id,name,activation,package,integrationID}，
+//     `Connection.Info` 只是凭据引用，`Integration.Method` 只是"怎么拿凭据"，都没有 URL。
+//     所以配置里那两行是**irreducible** 的（见 config/opencode.sample.jsonc）。
+//
+// 另一处简化：代理端口不再让用户重复写 —— 从 `providers.reeve.settings.baseURL` 里推。
+
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** 三个档位。`images` 决定这一档声明不声明"能吃图"（只有视觉档声明）。 */
+export const REEVE_TIERS = Object.freeze([
+  { id: 'flash', modelID: 'reeve/flash', name: 'REEVE flash（廉价链）', images: false },
+  { id: 'pro', modelID: 'reeve/pro', name: 'REEVE pro（强推理链）', images: false },
+  { id: 'multimodal', modelID: 'reeve/multimodal', name: 'REEVE multimodal（视觉链）', images: true },
+])
+
+/** 造一个最小的 `Model.Info`（照 `Model.Info.default()` 的形状，能力按档位给）。 */
+export function buildTierModel(tier, providerID = 'reeve') {
+  return {
+    id: tier.id,
+    modelID: tier.modelID,
+    providerID,
+    name: tier.name,
+    capabilities: {
+      tools: true,
+      input: tier.images ? ['text', 'image'] : ['text'],
+      output: ['text'],
+    },
+    variants: [],
+    time: { released: 0 },
+    cost: [],
+    status: 'active',
+    enabled: true,
+    limit: { context: 200_000, output: 32_000 },
+  }
+}
+
+/**
+ * 合并：保留已有的，补上缺的档位。
+ * @param {Array<{id: string}>} existing 运行时已有的模型（可能为空）
+ * @param {ReadonlyArray<typeof REEVE_TIERS[number]>} tiers
+ * @param {string} providerID
+ * @returns {Array<object>} 要 set 回去的完整数组
+ */
+export function mergeTierModels(existing, tiers = REEVE_TIERS, providerID = 'reeve') {
+  const have = new Set((existing ?? []).map((m) => m?.id).filter(Boolean))
+  const added = tiers.filter((t) => !have.has(t.id)).map((t) => buildTierModel(t, providerID))
+  return [...(existing ?? []), ...added]
+}
+
+/**
+ * 从引擎配置里读 `providers.reeve.settings.baseURL` → 代理该在哪个 host:port 上服务。
+ * 读不到就返回 null（调用方退回 options.proxy.port / 默认端口）。
+ * **只读**：插件永不写引擎配置。
+ */
+export function parseEndpointFromConfig(text, providerID = 'reeve') {
+  try {
+    const stripped = String(text)
+      .split('\n')
+      .filter((l) => !l.trim().startsWith('//'))
+      .join('\n')
+    const json = JSON.parse(stripped)
+    const base = json?.providers?.[providerID]?.settings?.baseURL
+    if (typeof base !== 'string' || base.length === 0) return null
+    const url = new URL(base)
+    return { baseURL: base, host: url.hostname, port: Number(url.port || (url.protocol === 'https:' ? 443 : 80)) }
+  } catch {
+    return null
+  }
+}
+
+/** 读配置目录里的 opencode.json / opencode.jsonc（哪个先读到用哪个）。 */
+export async function readEndpoint({ configDir = null, readFileImpl = readFile, providerID = 'reeve' } = {}) {
+  const dir = configDir ?? join(homedir(), '.config', 'opencode')
+  for (const name of ['opencode.json', 'opencode.jsonc']) {
+    try {
+      const text = await readFileImpl(join(dir, name), 'utf8')
+      const found = parseEndpointFromConfig(text, providerID)
+      if (found) return { ...found, from: join(dir, name) }
+    } catch {
+      /* 换下一个 */
+    }
+  }
+  return null
+}
+/**
+ * 要藏起来的内置 agent —— 前台只留编排者（见 PROGRESS §6.1）。
+ * 由插件在启动时设置 `hidden: true`，所以配置里不再需要 `agents` 块。
+ * 希望某个内置 agent 重新可见：删掉这里的 id，或者在配置里显式写 `agents.<id>.hidden = false`
+ * （**配置后应用**，会覆盖这里的设置）。
+ */
+export const BUILTINS_TO_HIDE = Object.freeze(['build', 'plan', 'general', 'explore'])
+
+/** 把默认 agent 设为编排者（存在才设；配置里的 `default_agent` 优先级更高）。 */
+export function pickDefaultAgent(editor, id = 'foreman') {
+  try {
+    if (editor.get(id)) {
+      editor.default(id)
+      return true
+    }
+  } catch {
+    /* 读不到就当不存在 */
+  }
+  return false
+}