dsh-session-guard 0.3.1 → 3.0.0

package/src/pause-gate.js

@@ -46,6 +46,36 @@ export function createPluginUserMessage({ content, source }) {
   return { id, role: 'user', content, source }
 }
 
+/**
+ * 恢复消息入队（0.1.5 compat 双路径）。
+ *
+ * 0.1.5 把 Inbox 从独立服务改为 agent-loop 只读投影（消息入队走 session 事件），
+ * `agent.followup` 是否保留无法静态确认，因此运行时检测：
+ * 1. `agent.followup(msg)` —— ≤0.1.4 与（若保留的）0.1.5 首选路径；
+ * 2. `agent.send(msg)` —— followup 被移除时的回退；
+ * 3. 两者皆无 —— 记 warn 并返回 false，绝不让 resume 因入队失败而抛错。
+ * @param {object} agent 目标 agent（live agent）
+ * @param {{id: string, role: 'user', content: unknown, source: object}} message 本地构造的 user 消息
+ * @param {object} [ctx] host context（仅用于 logger）
+ * @returns {boolean} 是否成功入队
+ */
+export function enqueueFollowup(agent, message, ctx) {
+  if (typeof agent.followup === 'function') {
+    agent.followup(message)
+    return true
+  }
+  if (typeof agent.send === 'function') {
+    agent.send(message)
+    return true
+  }
+  try {
+    ctx?.logger?.warn?.('[session-guard] agent has no followup/send; resume message dropped')
+  } catch {
+    /* logger 不可用时静默 */
+  }
+  return false
+}
+
 /**
  * @param {object} deps
  * @param {object} deps.ctx host context（含 agents.get / get / logger，可选 goals）
@@ -132,11 +162,31 @@ export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', m
    * 两种形态在 DSH 0.1.1-rc.2 与 0.1.2-rc.1 的回放日志里都保留，勿改成单读。
    */
 
+  /**
+   * 读取会话事件数组。DSH 0.1.5 移除了 `session.events` 数组访问器，改为
+   * `snapshotEvents()`（compatibility-guide §20.3 实测表）；本专线以
+   * snapshotEvents() 为主，events 数组仅作回退防御，两者皆缺时返回 null
+   * （fail-open，与既有防御语义一致）。
+   */
+  function readSessionEvents(session) {
+    if (!session) return null
+    if (typeof session.snapshotEvents === 'function') {
+      try {
+        const events = session.snapshotEvents()
+        return Array.isArray(events) ? events : null
+      } catch {
+        return null
+      }
+    }
+    return Array.isArray(session.events) ? session.events : null
+  }
+
   /** 在 session log 查一个中断工具的实际结果（kernel 会 drain 已启动工具到 tool/result）。 */
   function findToolOutcome(agent, callId) {
-    if (!agent?.session?.events) return null
+    const events = readSessionEvents(agent?.session)
+    if (!events) return null
     let outcome = null
-    for (const event of agent.session.events) {
+    for (const event of events) {
       if (event.type === 'tool/result') {
         const message = event.data?.message ?? {}
         const block = (Array.isArray(message.content) ? message.content : []).find((b) => b?.type === 'tool-result')
@@ -162,9 +212,10 @@ export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', m
   }
 
   function lastUserPrompt(agent) {
-    if (!agent?.session?.events) return null
-    for (let index = agent.session.events.length - 1; index >= 0; index -= 1) {
-      const event = agent.session.events[index]
+    const events = readSessionEvents(agent?.session)
+    if (!events) return null
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      const event = events[index]
       if (event.type !== 'user/message') continue
       if (event.data?.source?.kind !== 'user') continue
       return event.data.content ?? null
@@ -286,7 +337,8 @@ export function createPauseGate({ ctx, pauseStore, pluginId = 'session-guard', m
     state.pendingPause.delete(sessionId)
     const current = currentPause(sessionId)
     if (!current.paused) return { kind: 'success', text: 'no paused task to resume' }
-    const followup = (blocks) => agent.followup(makeFollowupMessage({ content: blocks, source: { kind: 'plugin', plugin: pluginId } }))
+    // 0.1.5 compat：source 补 form: 'instructions'（0.1.5 ContextFormed 契约；旧版本忽略未知字段）
+    const followup = (blocks) => enqueueFollowup(agent, makeFollowupMessage({ content: blocks, source: { kind: 'plugin', plugin: pluginId, form: 'instructions' } }), ctx)
 
     if (current.forced) {
       const tool = current.interruptedTool

package/src/pause-store.js

@@ -1,101 +1,101 @@
-/**
- * dsh-session-guard — 自研会话门暂停状态持久化（脱离 dsh-task-control）。
- *
- * 与 queueLock（src/store.js，队列锁）分离：这里是「真暂停」的持久化快照，
- * 仿 task-control 的状态模型，但独立子目录 /pause 避免与队列锁文件互相污染。
- *
- * 暂停/锁定状态仍**不写 session log**（harness 持久化 reader 只有已知事件集，
- * 自定义 `session-guard/*` 事件会导致重启后会话无法加载），走插件自有 JSON 文件：
- * `$DSH_HOME/.dsh/session-guard/pause/<sessionId>.json`（`DSH_SESSION_GUARD_PAUSE_DIR`
- * 可覆盖根目录）。原子写：tmp + rename。
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { storeRoot } from './store.js'
-
-/** 会话 id → 安全文件名（与队列锁同规则）。 */
-export function encodeSessionId(id) {
-  return String(id).replace(/[^a-zA-Z0-9._-]/g, '_')
-}
-
-/** 自研暂停状态根目录（独立于队列锁）。 */
-export function pauseStateRoot() {
-  return (
-    process.env.DSH_SESSION_GUARD_PAUSE_DIR ||
-    join(storeRoot(), 'pause')
-  )
-}
-
-/** 每会话暂停状态文件路径。 */
-export function pauseFilePath(id) {
-  return join(pauseStateRoot(), `${encodeSessionId(id)}.json`)
-}
-
-/** 未暂停基线快照。 */
-export function idlePauseState(id) {
-  return {
-    sessionId: String(id),
-    paused: false,
-    resumeContent: null,
-    forced: false,
-    interruptedTool: null,
-    deferredTools: null,
-    updatedAt: null,
-  }
-}
-
-/**
- * 创建暂停状态存储（内存缓存 + 磁盘持久化，原子写）。
- * 独立于队列锁 store，字段形态仿 task-control（paused/forced/interruptedTool/deferredTools）。
- */
-export function createPauseStore() {
-  const cache = new Map()
-
-  function read(id) {
-    if (cache.has(id)) return cache.get(id)
-    try {
-      const f = pauseFilePath(id)
-      if (!existsSync(f)) return null
-      const v = JSON.parse(readFileSync(f, 'utf8'))
-      cache.set(id, v)
-      return v
-    } catch {
-      return null
-    }
-  }
-
-  return {
-    /** 读一会话暂停态；无记录返回 null（调用方 fallback idlePauseState）。 */
-    get(id) {
-      return read(id)
-    },
-    /** 原子写。 */
-    set(id, value) {
-      cache.set(id, value)
-      try {
-        const f = pauseFilePath(id)
-        mkdirSync(dirname(f), { recursive: true })
-        const tmp = `${f}.tmp`
-        writeFileSync(tmp, JSON.stringify(value, null, 2))
-        renameSync(tmp, f)
-      } catch (e) {
-        // 落盘失败仅影响重启恢复，内存态仍可用。
-        console.error(`[session-guard] pause store write failed: ${String(e && e.message || e)}`)
-      }
-    },
-    /** 清除（resume/cancel 后）。 */
-    clear(id) {
-      cache.delete(id)
-      try {
-        rmSync(pauseFilePath(id), { force: true })
-      } catch {
-        /* ignore */
-      }
-    },
-    /** 当前有效快照（无记录时 idle 基线）。 */
-    current(id) {
-      const v = read(id)
-      return v !== null && typeof v === 'object' ? v : idlePauseState(id)
-    },
-  }
-}
+/**
+ * dsh-session-guard — 自研会话门暂停状态持久化（脱离 dsh-task-control）。
+ *
+ * 与 queueLock（src/store.js，队列锁）分离：这里是「真暂停」的持久化快照，
+ * 仿 task-control 的状态模型，但独立子目录 /pause 避免与队列锁文件互相污染。
+ *
+ * 暂停/锁定状态仍**不写 session log**（harness 持久化 reader 只有已知事件集，
+ * 自定义 `session-guard/*` 事件会导致重启后会话无法加载），走插件自有 JSON 文件：
+ * `$DSH_HOME/.dsh/session-guard/pause/<sessionId>.json`（`DSH_SESSION_GUARD_PAUSE_DIR`
+ * 可覆盖根目录）。原子写：tmp + rename。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { storeRoot } from './store.js'
+
+/** 会话 id → 安全文件名（与队列锁同规则）。 */
+export function encodeSessionId(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+/** 自研暂停状态根目录（独立于队列锁）。 */
+export function pauseStateRoot() {
+  return (
+    process.env.DSH_SESSION_GUARD_PAUSE_DIR ||
+    join(storeRoot(), 'pause')
+  )
+}
+
+/** 每会话暂停状态文件路径。 */
+export function pauseFilePath(id) {
+  return join(pauseStateRoot(), `${encodeSessionId(id)}.json`)
+}
+
+/** 未暂停基线快照。 */
+export function idlePauseState(id) {
+  return {
+    sessionId: String(id),
+    paused: false,
+    resumeContent: null,
+    forced: false,
+    interruptedTool: null,
+    deferredTools: null,
+    updatedAt: null,
+  }
+}
+
+/**
+ * 创建暂停状态存储（内存缓存 + 磁盘持久化，原子写）。
+ * 独立于队列锁 store，字段形态仿 task-control（paused/forced/interruptedTool/deferredTools）。
+ */
+export function createPauseStore() {
+  const cache = new Map()
+
+  function read(id) {
+    if (cache.has(id)) return cache.get(id)
+    try {
+      const f = pauseFilePath(id)
+      if (!existsSync(f)) return null
+      const v = JSON.parse(readFileSync(f, 'utf8'))
+      cache.set(id, v)
+      return v
+    } catch {
+      return null
+    }
+  }
+
+  return {
+    /** 读一会话暂停态；无记录返回 null（调用方 fallback idlePauseState）。 */
+    get(id) {
+      return read(id)
+    },
+    /** 原子写。 */
+    set(id, value) {
+      cache.set(id, value)
+      try {
+        const f = pauseFilePath(id)
+        mkdirSync(dirname(f), { recursive: true })
+        const tmp = `${f}.tmp`
+        writeFileSync(tmp, JSON.stringify(value, null, 2))
+        renameSync(tmp, f)
+      } catch (e) {
+        // 落盘失败仅影响重启恢复，内存态仍可用。
+        console.error(`[session-guard] pause store write failed: ${String(e && e.message || e)}`)
+      }
+    },
+    /** 清除（resume/cancel 后）。 */
+    clear(id) {
+      cache.delete(id)
+      try {
+        rmSync(pauseFilePath(id), { force: true })
+      } catch {
+        /* ignore */
+      }
+    },
+    /** 当前有效快照（无记录时 idle 基线）。 */
+    current(id) {
+      const v = read(id)
+      return v !== null && typeof v === 'object' ? v : idlePauseState(id)
+    },
+  }
+}

package/src/scheduler.js

@@ -1,42 +1,42 @@
-/**
- * dsh-session-guard — 纯状态机（可单测，零依赖）。
- *
- * 状态：NORMAL ↔ PAUSED_PEAK。
- * 副作用（暂停/恢复具体会话）由 host 的 tick 执行，这里只做判定与迁移检测。
- */
-import { shouldPause } from './time.js'
-
-export const STATES = {
-  NORMAL: 'NORMAL',
-  PAUSED_PEAK: 'PAUSED_PEAK',
-}
-
-/**
- * 计算当前状态。
- * @param {object} settings 同 time.shouldPause 的 settings
- * @param {Date|number} now
- * @returns {{state:string, reason:string, at:number}}
- */
-export function computeState(settings, now) {
-  const date = now instanceof Date ? now : new Date(now)
-  const d = shouldPause(settings, date)
-  return {
-    state: d.pause ? STATES.PAUSED_PEAK : STATES.NORMAL,
-    reason: d.reason,
-    at: date.getTime(),
-  }
-}
-
-/**
- * 迁移检测：从 prev 到 next 是否发生了 入峰(enter) / 退峰(leave)。
- * @param {{state:string}|null} prev
- * @param {{state:string}} next
- * @returns {{enter:boolean, leave:boolean}}
- */
-export function transition(prev, next) {
-  const was = prev && prev.state
-  return {
-    enter: next.state === STATES.PAUSED_PEAK && was !== STATES.PAUSED_PEAK,
-    leave: was === STATES.PAUSED_PEAK && next.state !== STATES.PAUSED_PEAK,
-  }
-}
+/**
+ * dsh-session-guard — 纯状态机（可单测，零依赖）。
+ *
+ * 状态：NORMAL ↔ PAUSED_PEAK。
+ * 副作用（暂停/恢复具体会话）由 host 的 tick 执行，这里只做判定与迁移检测。
+ */
+import { shouldPause } from './time.js'
+
+export const STATES = {
+  NORMAL: 'NORMAL',
+  PAUSED_PEAK: 'PAUSED_PEAK',
+}
+
+/**
+ * 计算当前状态。
+ * @param {object} settings 同 time.shouldPause 的 settings
+ * @param {Date|number} now
+ * @returns {{state:string, reason:string, at:number}}
+ */
+export function computeState(settings, now) {
+  const date = now instanceof Date ? now : new Date(now)
+  const d = shouldPause(settings, date)
+  return {
+    state: d.pause ? STATES.PAUSED_PEAK : STATES.NORMAL,
+    reason: d.reason,
+    at: date.getTime(),
+  }
+}
+
+/**
+ * 迁移检测：从 prev 到 next 是否发生了 入峰(enter) / 退峰(leave)。
+ * @param {{state:string}|null} prev
+ * @param {{state:string}} next
+ * @returns {{enter:boolean, leave:boolean}}
+ */
+export function transition(prev, next) {
+  const was = prev && prev.state
+  return {
+    enter: next.state === STATES.PAUSED_PEAK && was !== STATES.PAUSED_PEAK,
+    leave: was === STATES.PAUSED_PEAK && next.state !== STATES.PAUSED_PEAK,
+  }
+}