@whaletalk/dsh-codex-collab 0.1.6 → 0.1.9

package/harness/fs-lock.mjs

@@ -0,0 +1,208 @@
+/**
+ * fs-lock.mjs —— 本机跨进程写锁（零依赖），供收件箱与任务关联存储复用。
+ *
+ * 互斥只靠一条：**一个共享路径**上的一次**原子独占创建**（先把完整元数据写进唯一命名的
+ * `pending-<token>.json`，再 `linkSync` 到锁路径；平台不支持硬链接时退化为 `wx` 独占创建 + 立即写入）。
+ * 共享路径只能被创建成功一次，所以同一时刻至多一个持有者。
+ *
+ * **在线竞争期间绝不自动回收**：在共享路径上"检查持有者 → 再删除/改名"无法原子化，回收者可能
+ * 删掉别人刚创建的新锁（ABA/TOCTOU，已被真实复现过）。因此只有三种结果：
+ *   - 持有者活着   → 有限等待，超时抛 lock-timeout；
+ *   - 持有者已死   → 二次确认（锁仍在、仍是同一把、pid 仍不可达）后抛 lock-stale-holder（可恢复，人工清理）；
+ *   - 元数据不可确认 → 抛 lock-unverified-holder（可恢复，人工清理）。
+ * 宁可阻塞等待人工处理，也不冒"两个写者"的风险。
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const LOCK_REASONS = {
+  /** 持有者活着，等不到锁（可重试）。 */
+  TIMEOUT: 'lock-timeout',
+  /** 持有者已死：不自动回收，需人工清理（可恢复错误）。 */
+  STALE_HOLDER: 'lock-stale-holder',
+  /** 锁存在但无法确认持有者：不按时间偷（可恢复错误）。 */
+  UNVERIFIED_HOLDER: 'lock-unverified-holder',
+}
+
+/** 观察到"无法确认持有者"的元数据后，最多再观察这么久（容忍原子创建的极小空窗），然后 fail closed。 */
+const UNREADABLE_GRACE_MS = 200
+/** 残留 pending 文件的清理年龄下限：先证明其记录里的 pid 已死，再删（名字唯一，不涉及共享路径）。 */
+const PENDING_STALE_MS = 1000
+const DEFAULT_TIMEOUT_MS = 10000
+
+const uid = (prefix) => prefix + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10)
+
+/** 同步睡眠（不占 CPU）；Node 主线程允许 Atomics.wait。 */
+const sleep = (ms) => {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+  } catch (e) {
+    const end = Date.now() + ms
+    while (Date.now() < end) { /* spin */ }
+  }
+}
+
+export const isProcessAlive = (pid) => {
+  if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    if (e !== null && typeof e === 'object' && e.code === 'ESRCH') return false
+    // EPERM 等：进程存在但不是我们能发信号的 → 视为活着（宁可等，也不抢）
+    return true
+  }
+}
+
+const lockError = (reason, message, extra) => Object.assign(new Error(message), { reason, ...(extra === undefined ? {} : extra) })
+
+/**
+ * 在 `lockFile` 上创建一把跨进程写锁。
+ * @param {{lockFile: string, timeoutMs?: number}} options
+ */
+export const createFileLock = (options) => {
+  const lockFile = path.resolve(options.lockFile)
+  const lockDir = path.dirname(lockFile)
+  const timeoutMs = typeof options.timeoutMs === 'number' && options.timeoutMs > 0 ? options.timeoutMs : DEFAULT_TIMEOUT_MS
+
+  const ensureDir = () => { fs.mkdirSync(lockDir, { recursive: true }) }
+
+  /** 读锁的持有者元数据。读不动/解析失败/没有 pid → 无法确认持有者（调用方必须 fail closed）。 */
+  const readLockMeta = () => {
+    let text
+    try {
+      text = fs.readFileSync(lockFile, 'utf8')
+    } catch (e) {
+      if (e !== null && typeof e === 'object' && e.code === 'ENOENT') return { ok: false, missing: true, why: 'lock file is gone' }
+      return { ok: false, missing: false, why: 'unreadable (' + e.message + ')' }
+    }
+    let value
+    try {
+      value = JSON.parse(text)
+    } catch (e) {
+      return { ok: false, missing: false, why: 'content is not valid JSON' }
+    }
+    if (value === null || typeof value !== 'object' || typeof value.pid !== 'number' || !Number.isInteger(value.pid)) {
+      return { ok: false, missing: false, why: 'content has no owner pid' }
+    }
+    return { ok: true, meta: value }
+  }
+
+  /**
+   * 原子独占创建：先写完整元数据到唯一命名的 pending 文件，再硬链接到锁路径。
+   * link 原子且独占，且"内容完整才可能可见"；不支持硬链接时退化为 `wx` + 立即写入
+   * （极小空窗内竞争者会读到不可确认的元数据 → fail closed，只会短暂报错，绝不误删）。
+   */
+  const publishLock = (meta) => {
+    ensureDir()
+    const intentPath = path.join(lockDir, 'pending-' + meta.token + '.json')
+    fs.writeFileSync(intentPath, JSON.stringify(meta), 'utf8')
+    try {
+      fs.linkSync(intentPath, lockFile)
+      return true
+    } catch (e) {
+      if (e !== null && typeof e === 'object' && e.code === 'EEXIST') return false
+      try {
+        fs.writeFileSync(lockFile, JSON.stringify(meta), { encoding: 'utf8', flag: 'wx' })
+        return true
+      } catch (e2) {
+        if (e2 !== null && typeof e2 === 'object' && e2.code === 'EEXIST') return false
+        throw e2
+      }
+    } finally {
+      try { fs.unlinkSync(intentPath) } catch (e) { /* 已被清理 */ }
+    }
+  }
+
+  /** 清理残留 pending：只在能证明其记录里的 pid 已死、且已过短宽限时删（名字唯一，不碰共享路径）。 */
+  const sweepPending = () => {
+    let names
+    try { names = fs.readdirSync(lockDir) } catch (e) { return }
+    for (const name of names) {
+      if (!name.startsWith('pending-')) continue
+      const file = path.join(lockDir, name)
+      try {
+        const age = Date.now() - fs.statSync(file).mtimeMs
+        if (age < PENDING_STALE_MS) continue
+        const owner = JSON.parse(fs.readFileSync(file, 'utf8'))
+        if (owner !== null && typeof owner === 'object' && isProcessAlive(owner.pid)) continue
+        fs.unlinkSync(file)
+      } catch (e) { /* 读不到/已被清理：下一轮再说 */ }
+    }
+  }
+
+  const acquire = () => {
+    ensureDir()
+    const token = uid('lock')
+    const meta = { token, pid: process.pid, host: os.hostname(), at: Date.now() }
+    const deadline = Date.now() + timeoutMs
+    let unreadableSince
+
+    for (;;) {
+      sweepPending()
+
+      // 1) 唯一的进入方式：原子独占创建。
+      if (publishLock(meta)) return { token }
+
+      // 2) 已存在：读元数据判定，只决定"等待 / 报错"，绝不删除或改名。
+      const info = readLockMeta()
+      if (info.missing === true) continue                    // 刚好被持有者释放：重试
+      if (info.ok === true) {
+        if (isProcessAlive(info.meta.pid)) {
+          if (Date.now() > deadline) {
+            const holder = 'pid ' + info.meta.pid
+            throw lockError(LOCK_REASONS.TIMEOUT, 'could not acquire the write lock within ' + timeoutMs + 'ms; it is held by ' + holder + ' (a live holder is never stolen). Retry later.', { holder, file: lockFile })
+          }
+          sleep(15)
+          continue
+        }
+        // 持有者看起来已死——但它可能刚刚**正常释放并退出**（读到内容之后、检查存活之前）。
+        // 报 stale 之前必须二次确认：锁文件仍在、还是同一把（token 相同）、pid 仍不可达。
+        const confirm = readLockMeta()
+        if (confirm.missing === true) continue
+        if (confirm.ok === true && confirm.meta.token === info.meta.token && !isProcessAlive(confirm.meta.pid)) {
+          throw lockError(
+            LOCK_REASONS.STALE_HOLDER,
+            'the write lock is held by pid ' + info.meta.pid + ', which is no longer running. Refusing to auto-reclaim it online: removing a shared lock path is racy (a reclaimer can delete a lock someone else just created). '
+            + 'Stop all writers, then delete ' + lockFile + ' manually and retry.',
+            { file: lockFile, stalePid: info.meta.pid },
+          )
+        }
+        continue
+      }
+
+      // 3) 元数据空/损坏：给原子创建留一点观察窗（只延迟报错，绝不删除），随后 fail closed。
+      if (unreadableSince === undefined) unreadableSince = Date.now()
+      if (Date.now() - unreadableSince >= UNREADABLE_GRACE_MS) {
+        throw lockError(
+          LOCK_REASONS.UNVERIFIED_HOLDER,
+          'the write lock at ' + lockFile + ' has no verifiable owner (' + info.why + '); refusing to reclaim it on a timer. '
+          + 'Stop the writers and inspect that file; remove it yourself only if you are sure no writer is running.',
+          { file: lockFile },
+        )
+      }
+      sleep(15)
+    }
+  }
+
+  const release = (handle) => {
+    // 只删自己创建的那把锁：核对 token 后删除。注意——这只是"尽力而为"的一致性检查，
+    // **不是互斥的基础**；互斥来自独占创建 + 从不自动回收（没有任何自动路径会删活锁）。
+    const info = readLockMeta()
+    if (info.ok === true && info.meta.token === handle.token) {
+      try { fs.unlinkSync(lockFile) } catch (e) { /* 已被外部清理 */ }
+    }
+  }
+
+  const withLock = (fn) => {
+    const handle = acquire()
+    try {
+      return fn()
+    } finally {
+      release(handle)
+    }
+  }
+
+  return { lockFile, timeoutMs, acquire, release, withLock, readLockMeta }
+}

package/harness/session-target.mjs

@@ -27,8 +27,18 @@ export const REASONS = {
   BAD_REQUEST: 'session-bad-request',
   GATEWAY_INTERNAL: 'session-gateway-internal',
   DISPATCH_FAILED: 'session-dispatch-failed',
+  /** 带来源的会话任务不能精确关联到单个请求回合：在执行前拒绝 steer。 */
+  ORIGIN_STEER_UNSUPPORTED: 'origin-steer-unsupported',
+  /** 关联到了请求回合，但该回合以非 completed 结束（aborted/blocked/error/…）。 */
+  TURN_FAILED: 'session-turn-failed',
+  /** 没有任何证据能确认这个请求回合的结局（不猜、不重发）。 */
+  UNCONFIRMED: 'execution-state-unconfirmed',
 }
 
+/** `turn/end` 的 reason.kind 枚举（来自 driver/typert）：**只有 completed 算成功**。 */
+export const TURN_END_KINDS = ['completed', 'aborted', 'blocked', 'error', 'max-tokens', 'interrupted', 'forked']
+export const SUCCESS_TURN_END = 'completed'
+
 /** 候选列表回传给调用方时的上限，避免把整个会话库倒出去。 */
 export const MAX_CANDIDATES = 10
 
@@ -91,6 +101,128 @@ export const pickSessionResult = (streamed, extracted) => {
   return fromStream !== '' ? fromStream : '(无输出)'
 }
 
+/**
+ * 请求 → DSH turn 的关联器（纯函数群）。
+ *
+ * 依据（本机 controller 0.2.0-rc.2 的实测字段）：
+ *  - `prompt.requestId` 会被写进 `user/message` 的 `event.data.source.rpcId`——这是"这条用户消息属于
+ *    哪次请求"的**唯一可靠凭据**（我们用 taskId 当 requestId）；
+ *  - **`user/message.data.turn` 不存在**：turn 号只能靠按 seq 有序跟踪"已 turn/start 但还没 turn/end"
+ *    的回合得到，遇到 rpcId 匹配的 user/message 时把它归到**当时仍未闭合**的那个 turn；
+ *  - `assistant/message.data = {turn, step, message:{content:[...]}}`：只收自己那个 turn 的助手文本；
+ *  - `turn/end.data = {turn, reason:{kind,…}}`：这是本次请求结束的依据；**只有 completed 算成功**；
+ *  - `api-session/status` 只表示 agent 当前是否 running（连续跑 queued turn 时可能没有新的 running=true），
+ *    因此它**绝不能**当作某个请求完成的证明。
+ *
+ * 同一套规则被 live follow 帧、follow 开场 snapshot.records、以及轮询读日志共用；`seq` 去重保证
+ * 同一条事件被多条路径投递时也只算一次、不串文本。
+ */
+export const createRequestTracker = (requestId) => ({
+  requestId: String(requestId),
+  /** 已 turn/start 但未 turn/end 的 turn 号（有序）。 */
+  openTurns: [],
+  /** 匹配到本请求的 turn 号（由 rpcId 匹配时那一刻的未闭合 turn 决定）。 */
+  turn: undefined,
+  sawRequest: false,
+  text: '',
+  /**
+   * **只记录"真正产生了效果"的事件 seq**（建立 turn 关联 / 追加自己 turn 的文字 / 收尾 / 记录 turn/start）。
+   * 当时因为"还不知道自己那个 turn"而无法使用的事件**不**标记——后续从完整日志回填时它们必须能被重新消费
+   * （否则快照缺前半段就会永久丢掉答案）。
+   */
+  usedSeqs: new Set(),
+  end: undefined,
+  lastSeq: 0,
+})
+
+const dataOf = (event) => (event.data !== undefined && event.data !== null && typeof event.data === 'object' ? event.data : {})
+
+/**
+ * 消费一条会话事件。返回 `'settled'`（本请求的 turn 已结束）/ `'progress'` / `'ignored'`。
+ */
+export const consumeSessionEvent = (tracker, event) => {
+  if (tracker === undefined || tracker === null) return 'ignored'
+  if (event === null || typeof event !== 'object') return 'ignored'
+  const seq = typeof event.seq === 'number' ? event.seq : undefined
+  if (seq !== undefined) {
+    if (tracker.usedSeqs.has(seq)) return 'ignored'          // 已经用过的效果不重复施加
+    tracker.lastSeq = Math.max(tracker.lastSeq, seq)
+  }
+  const markUsed = () => { if (seq !== undefined) tracker.usedSeqs.add(seq) }
+  const data = dataOf(event)
+  if (event.type === 'turn/start') {
+    const turn = typeof data.turn === 'number' ? data.turn : undefined
+    if (turn !== undefined && !tracker.openTurns.includes(turn)) tracker.openTurns.push(turn)
+    markUsed()
+    return 'ignored'
+  }
+  if (event.type === 'user/message') {
+    const source = data.source !== undefined && data.source !== null && typeof data.source === 'object' ? data.source : {}
+    if (typeof source.rpcId !== 'string' || source.rpcId !== tracker.requestId) return 'ignored'
+    tracker.sawRequest = true
+    if (tracker.turn === undefined) {
+      // user/message 没有 data.turn：归到此刻仍未闭合的那个 turn（有 data.turn 时以它为准）
+      const fallback = tracker.openTurns.length > 0 ? tracker.openTurns[tracker.openTurns.length - 1] : undefined
+      tracker.turn = typeof data.turn === 'number' ? data.turn : fallback
+    }
+    // 只有真的建立了 turn 关联才算"用过"；没有未闭合 turn 时留待回填。
+    if (tracker.turn !== undefined) markUsed()
+    return 'progress'
+  }
+  if (event.type === 'assistant/message') {
+    if (tracker.turn === undefined) return 'ignored'         // 还不知道自己的 turn：留待回填
+    if (typeof data.turn === 'number' && data.turn !== tracker.turn) return 'ignored'
+    const text = assistantTextOf(event)
+    if (text === '') return 'ignored'
+    tracker.text += text
+    markUsed()
+    return 'progress'
+  }
+  if (event.type === 'turn/end') {
+    const turn = typeof data.turn === 'number' ? data.turn : undefined
+    if (turn !== undefined) tracker.openTurns = tracker.openTurns.filter((t) => t !== turn)
+    if (tracker.turn === undefined || turn !== tracker.turn) {
+      // 不是我们的回合：**不标记**，等自己那个 turn 绑定后若还有对应结束仍要能收到。
+      return 'ignored'
+    }
+    const reason = data.reason !== undefined && data.reason !== null && typeof data.reason === 'object' ? data.reason : {}
+    const kind = typeof reason.kind === 'string' ? reason.kind : 'unknown'
+    tracker.end = { kind, reason, seq }
+    markUsed()
+    return 'settled'
+  }
+  return 'ignored'
+}
+
+/**
+ * follow 开场的 snapshot 帧：`{type:'snapshot', records:[{type:'event', event:{…}}], …}`。
+ * **不能把 snapshot 整个丢掉**——快任务可能在派发与订阅之间就已经跑完，答案只在这个快照里。
+ */
+export const consumeSnapshotFrame = (tracker, frame) => {
+  const records = frame !== null && frame !== undefined && Array.isArray(frame.records)
+    ? frame.records
+    : (frame !== null && frame !== undefined && Array.isArray(frame.events) ? frame.events : [])
+  let last = 'ignored'
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') continue
+    const event = record.type === 'event' && record.event !== undefined && record.event !== null
+      ? record.event
+      : (typeof record.type === 'string' && record.seq !== undefined ? record : undefined)
+    if (event === undefined) continue
+    const outcome = consumeSessionEvent(tracker, event)
+    if (outcome === 'settled') return 'settled'
+    if (outcome === 'progress') last = 'progress'
+  }
+  return last
+}
+
+/** 由 tracker 得出终态结论：只有 completed 算成功；其他 kind 明确失败；没有证据=未确认。 */
+export const turnOutcome = (end) => {
+  if (end === undefined || end === null) return { ok: false, unconfirmed: true, kind: 'unconfirmed' }
+  if (end.kind === SUCCESS_TURN_END) return { ok: true, unconfirmed: false, kind: end.kind }
+  return { ok: false, unconfirmed: false, kind: end.kind }
+}
+
 /**
  * 判定一次派发的目标。
  *
@@ -232,6 +364,54 @@ export const looksLikeDisabledSearch = (error) => {
   return /search is disabled/i.test(text)
 }
 
+/** 去空白后的字符 bigram 集合（CJK 友好：不需要分词）。 */
+const bigramsOf = (value) => {
+  const text = typeof value === 'string' ? value.replace(/\s+/g, '') : ''
+  const out = new Set()
+  if (text.length === 1) out.add(text)
+  for (let i = 0; i + 1 < text.length; i++) out.add(text.slice(i, i + 2))
+  return out
+}
+
+/** 查询里的 bigram 有多少比例出现在标题里（0..1）。 */
+export const titleSimilarity = (query, title) => {
+  const q = bigramsOf(query)
+  const t = bigramsOf(title)
+  if (q.size === 0 || t.size === 0) return 0
+  let shared = 0
+  for (const gram of q) if (t.has(gram)) shared++
+  return shared / q.size
+}
+
+/**
+ * `session-query-empty` 时给出的"近似候选"。
+ *
+ * 起因是一个真实事故：调用方搜「量化框架」没命中，又**没有别的办法确认标题**，于是
+ * 发了一条占位消息去"探测命中"——那条消息落进了用户自己的会话并跑成回合，污染了
+ * 对话。修法是不给"探测"留动机：查询落空时直接回一批候选标题（同 bigram 相似度排
+ * 序，无相似度的按最近更新补位），调用方靠只读信息就能改词重查。
+ */
+export const rankTitleCandidates = (query, summaries, limit = 5) => {
+  const list = Array.isArray(summaries) ? summaries : []
+  const scored = []
+  for (const summary of list) {
+    if (summary === null || typeof summary !== 'object') continue
+    if (typeof summary.sessionId !== 'string' || summary.sessionId === '') continue
+    const title = typeof summary.title === 'string' && summary.title !== '' ? summary.title : ''
+    const updatedAt = typeof summary.updatedAt === 'number' ? summary.updatedAt : 0
+    scored.push({ sessionId: summary.sessionId, snippet: title, score: titleSimilarity(query, title), updatedAt })
+  }
+  const byRecency = (a, b) => b.updatedAt - a.updatedAt
+  const related = scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score || byRecency(a, b))
+  const rest = scored.filter((s) => s.score === 0).sort(byRecency)
+  const bound = Math.max(1, Math.min(Number(limit) || 5, MAX_CANDIDATES))
+  return [...related, ...rest].slice(0, bound).map((s) => ({
+    sessionId: s.sessionId,
+    snippet: s.snippet,
+    score: Math.round(s.score * 1000) / 1000,
+  }))
+}
+
 /** 任务在 HTTP 行上的回显：调用方一眼能看出这次是"新建"还是"接进哪个会话"。 */
 export const taskResponse = (task) => {
   const out = { taskId: task.taskId, status: task.status, kind: task.kind }
@@ -246,5 +426,12 @@ export const taskResponse = (task) => {
     out.target = { kind: 'worker', cwd: target.cwd, lane: target.lane }
   }
   if (Array.isArray(task.notes) && task.notes.length > 0) out.notes = task.notes
+  // delivered=true：prompt 已被目标会话接受（进了它的队列）。调用方据此知道
+  // "别重发"——即便随后我们的观察超时并报错，消息也可能正在队列里等着跑。
+  if (task.target !== undefined && task.target !== null && task.target.kind === 'session' && task.delivered === true) {
+    out.delivered = true
+  }
+  // 来源关联（R1）：回显发起这次任务的 Codex 对话 id，便于跨回合按 origin+taskId 精确收取。
+  if (typeof task.originThreadId === 'string' && task.originThreadId !== '') out.originThreadId = task.originThreadId
   return out
 }

package/harness/task-table.mjs

@@ -0,0 +1,32 @@
+/**
+ * task-table.mjs —— 网关内存任务表的淘汰策略（纯函数，可单测）。
+ *
+ * 为什么单独抽出来：原来三个入口都无条件 `tasks.splice(0, tasks.length - 200)`，会把
+ * **仍在执行**的任务挤掉，导致完成回调/会话观察器 `find(taskId)` 找不到它（结果丢失）。
+ * 现在只淘汰**终态**任务，且永不淘汰刚创建的那一条。
+ */
+
+export const DEFAULT_TASK_LIMIT = 200
+
+/**
+ * 把任务放进表里，并在超限时淘汰终态任务。
+ * @param {Array<object>} tasks 任务表（原地修改）
+ * @param {object} task 新任务
+ * @param {number} [limit]
+ * @returns {Array<object>} 同一个数组
+ */
+export const rememberTask = (tasks, task, limit = DEFAULT_TASK_LIMIT) => {
+  tasks.push(task)
+  const bound = typeof limit === 'number' && limit > 0 ? limit : DEFAULT_TASK_LIMIT
+  while (tasks.length > bound) {
+    // 只淘汰终态（非 accepted/running）且不是刚加进来的那一条。
+    const index = tasks.findIndex((t) => t !== task && t.status !== 'accepted' && t.status !== 'running')
+    if (index === -1) break                    // 全是活任务：宁可超过上限，也不丢执行中的任务
+    tasks.splice(index, 1)
+  }
+  return tasks
+}
+
+/** 是否处于"还在执行"的状态（完成回调需要能找到它）。 */
+export const isActiveTask = (task) => task !== null && typeof task === 'object'
+  && (task.status === 'accepted' || task.status === 'running')