dsh-session-guard 0.1.0

package/src/retry.js

@@ -0,0 +1,202 @@
+/**
+ * dsh-session-guard — 后端自动重试（host side，D9）。
+ *
+ * 监听 session/event：turn/end 以 error / interrupted / max-tokens 结束时，
+ * 分类瞬时/永久失败，自适应退避后自动 `agent.followup(retryText)` 续跑。
+ *
+ * 关键纪律：
+ * - **冻结让路**：会话被本插件门控（高峰暂停 / 队列锁）时不触发重试——
+ *   与 input-traffic「freeze 是一等公民」一致，自动重试不得绕过会话门。
+ * - 用户手动介入（user/message）与成功回合重置连续计数。
+ * - 子代理会话不重试（由父代理处理）。
+ * - 永久失败（鉴权/余额/模型不存在/上下文超限等）重试无益 → 停止并告警。
+ *
+ * 纯决策逻辑（classifyTurnEnd / isTransientFailure / effectiveCooldown /
+ * shouldRetry）零依赖可单测；事件接线在 createRetry。
+ */
+
+/** 默认重试配置。 */
+export const DEFAULT_RETRY = Object.freeze({
+  retryEnabled: false, // ← 自动重试开关（默认关，保守）
+  retryText: '继续（自动重试）',
+  retryGraceMs: 3000, // 失败后等待多久再发
+  retryCooldownMs: 20000, // 同一会话两次重试最小间隔
+  retryBackoffFactor: 2,
+  retryBackoffMaxMs: 300000,
+  retryMaxConsecutive: 3, // 连续重试上限，超过停止
+})
+
+/** 瞬时 vs 永久失败分类：瞬时值得重试，永久重试无益。 */
+export function isTransientFailure({ code, message, status } = {}) {
+  const haystack = `${code ?? ''} ${message ?? ''}`.toLowerCase()
+  if (status !== undefined && (status === 401 || status === 403)) return false
+  const permanent =
+    /auth|unauthor|forbidden|credential|api\s*[_-]?\s*key|permission/i.test(haystack) ||
+    /insufficient.*(balance|quota)|billing|payment/i.test(haystack) ||
+    /model[^a-z]*not[^a-z]*found|unknown[_-]?model|not.*support.*model/i.test(haystack) ||
+    /context.*(length|limit|overflow|exceed)|token.*limit|max.*context/i.test(haystack) ||
+    /invalid[_-]?request|bad[_-]?request/i.test(haystack)
+  return !permanent
+}
+
+/**
+ * turn/end reason → 是否可自动重试。
+ * - completed / aborted（用户停）/ blocked（策略拒）→ 否
+ * - error → 按 isTransientFailure 分类
+ * - interrupted（崩溃修复）→ 可重试
+ * - max-tokens → 可重试
+ */
+export function classifyTurnEnd(reason, failure) {
+  const kind = reason && reason.kind
+  if (kind === 'completed' || kind === 'aborted' || kind === 'blocked') return false
+  if (kind === 'error') return isTransientFailure(failure)
+  if (kind === 'interrupted' || kind === 'max-tokens') return true
+  return false
+}
+
+/** 自适应退避：consecutive 次连续后 cooldown * factor^n，封顶 max。 */
+export function effectiveCooldown(consecutive, base, factor, max) {
+  const mult = Math.pow(factor, Math.max(0, consecutive))
+  return Math.min(Math.max(base, base * mult), Math.max(base, max))
+}
+
+/**
+ * 纯决策：此刻是否应触发重试。
+ * @param {object} s 会话状态 { consecutive, lastAttemptAt, pending }
+ * @param {object} cfg 重试配置
+ * @param {boolean} frozen 会话是否被门控（高峰暂停/队列锁）
+ * @param {number} now
+ */
+export function shouldRetry(s, cfg, frozen, now = Date.now()) {
+  if (!cfg.retryEnabled) return false
+  if (frozen) return false // 冻结让路（D9）
+  if (s.pending) return false // 已有排队重试
+  if (s.consecutive >= cfg.retryMaxConsecutive) return false
+  if (now - s.lastAttemptAt < effectiveCooldown(s.consecutive, cfg.retryCooldownMs, cfg.retryBackoffFactor, cfg.retryBackoffMaxMs)) return false
+  return true
+}
+
+/** 会话状态工厂。 */
+export function freshRetryState() {
+  return { consecutive: 0, lastAttemptAt: 0, pending: false }
+}
+
+/**
+ * 事件接线（host）：
+ * @param {object} deps
+ * @param {object} deps.ctx host context
+ * @param {()=>object} deps.getSettings 读实时配置
+ * @param {(sessionId:string)=>boolean} deps.isFrozen 会话是否被门控
+ * @param {(sessionId:string, text:string)=>void} [deps.send] 发送函数（默认 agent.followup）
+ */
+export function createRetry({ ctx, getSettings, isFrozen, send }) {
+  const states = new Map()
+
+  function state(sessionId) {
+    let s = states.get(sessionId)
+    if (!s) {
+      s = freshRetryState()
+      states.set(sessionId, s)
+    }
+    return s
+  }
+
+  /** 从 turn/end reason 提取失败事实。 */
+  function failureFacts(reason) {
+    const error = reason && reason.error
+    return {
+      code: error && typeof error.code === 'string' ? error.code : 'UNKNOWN',
+      message: error && typeof error.message === 'string' ? error.message : '',
+      status: error && typeof error.status === 'number' ? error.status : undefined,
+    }
+  }
+
+  function schedule(sessionId, reason) {
+    const s = state(sessionId)
+    const cfg = getSettings()
+    if (s.pending) return
+    const frozen = isFrozen(sessionId)
+    if (!shouldRetry({ ...s, pending: true }, cfg, frozen)) return
+    s.pending = true
+    const grace = cfg.retryGraceMs ?? DEFAULT_RETRY.retryGraceMs
+    const timer = setTimeout(() => {
+      s.pending = false
+      // 到点再复核：门控/上限变化后放弃。
+      if (!shouldRetry(s, cfg, isFrozen(sessionId))) return
+      const agent = ctx.agents.get(sessionId)
+      if (!agent || agent.status !== 'idle') return
+      const text = cfg.retryText ?? DEFAULT_RETRY.retryText
+      try {
+        if (send) {
+          send(sessionId, text)
+        } else {
+          // 与 autoresume 同构：直接构造 plugin-source 消息，避免运行时依赖。
+          agent.followup({
+            id: `session-guard-retry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            role: 'user',
+            content: [{ type: 'text', text }],
+            source: { kind: 'plugin', plugin: 'session-guard', form: 'notice' },
+          })
+        }
+        s.lastAttemptAt = Date.now()
+        s.consecutive += 1
+        ctx.logger?.info?.(`[session-guard] auto-retry ${sessionId} (${String(reason && reason.kind)}), #${s.consecutive}`)
+      } catch (e) {
+        ctx.logger?.warn?.(`[session-guard] auto-retry send failed: ${String(e && e.message || e)}`)
+      }
+    }, grace)
+    // 会话对象上的清理钩子（若宿主提供）。
+    const dispose = () => clearTimeout(timer)
+    return dispose
+  }
+
+  function onEvent(session, event) {
+    const sessionId = session && session.id
+    if (typeof sessionId !== 'string') return
+    const s = state(sessionId)
+    switch (event.type) {
+      case 'turn/end': {
+        const reason = event.data && event.data.reason
+        if (reason && reason.kind === 'completed') {
+          s.consecutive = 0 // 成功回合重置
+          s.pending = false
+          return
+        }
+        if (reason && reason.kind === 'aborted') {
+          // 用户主动停止：不重试，重置。
+          s.consecutive = 0
+          s.pending = false
+          return
+        }
+        if (reason && classifyTurnEnd(reason, failureFacts(reason))) {
+          schedule(sessionId, reason)
+        }
+        return
+      }
+      case 'user/message': {
+        // 用户手动介入：重置（无论是否我们的回显都保守重置）。
+        if (event.data && event.data.source && event.data.source.kind === 'user') {
+          s.consecutive = 0
+          s.pending = false
+        }
+        return
+      }
+      default:
+        return
+    }
+  }
+
+  ctx.on('session/event', (session, event) => {
+    try {
+      onEvent(session, event)
+    } catch (e) {
+      ctx.logger?.warn?.(`[session-guard] retry event failed: ${String(e && e.message || e)}`)
+    }
+  })
+
+  return {
+    onEvent,
+    state,
+    states,
+  }
+}

package/src/scheduler.js

@@ -0,0 +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,
+  }
+}

package/src/settings.js

@@ -0,0 +1,97 @@
+/**
+ * dsh-session-guard — 设置子板块（设置 → 插件 → session-guard，简单开关）。
+ *
+ * 注册方式对齐 dsh-thinking-levels 的官方做法：
+ * - `@deepseek-ai/schemastery` 为**常规 dependency**（随插件安装，可解析）。
+ * - **不 value-import `@deepseek-ai/dsh-settings`**：该服务由 dsh runtime 经
+ *   cordis `settings` 注入面提供，不属于 profile 的可解析树；这里只用本地最小
+ *   接口（SettingsScopeLike / SettingsServiceLike / SettingsAwareCtx）在
+ *   `ctx.inject(['settings'], ...)` 里注册命名空间，`base` 层叠组合配置。
+ * - 仍 fail-open：任何解析 / 注入失败都静默降级用 DEFAULT_SETTINGS，绝不因
+ *   设置依赖而崩。
+ */
+import z from '@deepseek-ai/schemastery'
+import { DEFAULT_RETRY } from './retry.js'
+
+/** 设置命名空间（设置 → 插件 → session-guard）。 */
+export const NS = 'session-guard'
+
+/** 默认配置（核心逻辑依赖；设置服务不可用时即用此值）。 */
+export const DEFAULT_SETTINGS = Object.freeze({
+  enabled: true, // 高峰自动处理开关（简单开关）
+  offPeakAutoResume: true, // 低谷自动恢复开关：低峰时段自动恢复被高峰暂停的会话
+  weekendMode: true, // 周末模式开关：识别周末，无视峰谷（简单开关）
+  timezone: 'Asia/Shanghai',
+  peakWindows: [
+    { start: '09:00', end: '12:00' },
+    { start: '14:00', end: '18:00' },
+  ],
+  pauseMode: 'safe', // 透传 taskControl.pause mode
+  pauseReason: 'wait', // 透传 taskControl.pause reason
+  queueFallback: true, // 无会话门时回退锁等待队列（简单开关）
+  retryEnabled: false, // 自动重试开关（后端，D9；默认关，保守）
+  retryText: DEFAULT_RETRY.retryText,
+  retryGraceMs: DEFAULT_RETRY.retryGraceMs,
+  retryCooldownMs: DEFAULT_RETRY.retryCooldownMs,
+  retryBackoffFactor: DEFAULT_RETRY.retryBackoffFactor,
+  retryBackoffMaxMs: DEFAULT_RETRY.retryBackoffMaxMs,
+  retryMaxConsecutive: DEFAULT_RETRY.retryMaxConsecutive,
+})
+
+/**
+ * 设置 schema（schemastery 原生命令，zod 变体）：
+ * - 枚举用 z.union([z.const(...)])；默认值用字段级 .default()。
+ */
+export const SettingsSchema = z.object({
+  enabled: z.boolean().default(DEFAULT_SETTINGS.enabled),
+  offPeakAutoResume: z.boolean().default(DEFAULT_SETTINGS.offPeakAutoResume),
+  weekendMode: z.boolean().default(DEFAULT_SETTINGS.weekendMode),
+  timezone: z.string().default(DEFAULT_SETTINGS.timezone),
+  peakWindows: z
+    .array(z.object({ start: z.string(), end: z.string() }))
+    .default(DEFAULT_SETTINGS.peakWindows),
+  pauseMode: z.union([z.const('safe'), z.const('force')]).default(DEFAULT_SETTINGS.pauseMode),
+  pauseReason: z.union([z.const('wait'), z.const('stop')]).default(DEFAULT_SETTINGS.pauseReason),
+  queueFallback: z.boolean().default(DEFAULT_SETTINGS.queueFallback),
+  retryEnabled: z.boolean().default(DEFAULT_SETTINGS.retryEnabled),
+  retryText: z.string().default(DEFAULT_SETTINGS.retryText),
+  retryGraceMs: z.number().min(0).default(DEFAULT_SETTINGS.retryGraceMs),
+  retryCooldownMs: z.number().min(0).default(DEFAULT_SETTINGS.retryCooldownMs),
+  retryBackoffFactor: z.number().min(1).default(DEFAULT_SETTINGS.retryBackoffFactor),
+  retryBackoffMaxMs: z.number().min(0).default(DEFAULT_SETTINGS.retryBackoffMaxMs),
+  retryMaxConsecutive: z.number().min(0).default(DEFAULT_SETTINGS.retryMaxConsecutive),
+})
+
+/**
+ * dsh settings 服务的最小本地接口（仿 dsh-thinking-levels 的 local face）：
+ * 插件不 value-import `@deepseek-ai/dsh-settings`，只通过这些形状在注入面调用。
+ */
+
+/** @typedef {{ get(): unknown; watch(cb: () => void): () => void }} SettingsScopeLike */
+/** @typedef {{ register(ns: string, schema: unknown, options?: { base?: unknown }): SettingsScopeLike }} SettingsServiceLike */
+/** @typedef {{ inject(deps: readonly string[], fn: (s: { settings: SettingsServiceLike; effect(cb: () => (() => void) | void, label?: string): void }) => void): void }} SettingsAwareCtx */
+
+/**
+ * 注册 设置 → 插件 → session-guard 子板块（简单开关）。
+ * - 走 `settings` 注入面，`base` 层叠组合配置；对 runtime 调用方经 `ctx.settings.get(NS)` 读取。
+ * - 任何失败（settings 服务缺失 / 注入异常）→ 返回 false，静默降级用默认配置。
+ * @param {object} ctx - host context（应含 cordis `settings` 注入面）。
+ * @returns {boolean} 注册成功 true；设置服务不可用时 false（fail-open）。
+ */
+export function registerSettings(ctx) {
+  try {
+    // 本插件顶层 `inject` 已声明 `settings`（见 src/index.js 的
+    // `export const inject`），所以 apply 时 `ctx.settings` 已是完整
+    // SettingsProvider（带 .register），直接注册即可 —— 无需再 `ctx.inject`
+    // 二次动态注入（对已在 fiber 上解析的服务做二次注入，回调作为异步插件
+    // apply 排队，`registerSettings` 同步返回 true 会掩盖实际操作未生效）。
+    // 与 dsh-thinking-levels / dsh-context 的区别仅在于它们顶层未声明
+    // settings，才必须动态注入；这里已声明，直接用最可靠。
+    const svc = /** @type {{ register(ns: string, schema: unknown, options?: { base?: unknown }): unknown }} */ (ctx.settings)
+    // base 用副本：DEFAULT_SETTINGS 被 Object.freeze，直接当 base 可能被写。
+    svc.register(NS, SettingsSchema, { base: { ...DEFAULT_SETTINGS } })
+    return true
+  } catch {
+    return false
+  }
+}

package/src/store.js

@@ -0,0 +1,77 @@
+/**
+ * dsh-session-guard — 每会话持久化状态存储（学 dsh-task-control 的独立存储模式，D4）。
+ *
+ * 暂停/锁定状态不写 session log（harness 持久化 reader 只认已知事件类型），
+ * 改为插件自有 JSON 文件：`$DSH_HOME/.dsh/session-guard/<sessionId>.json`
+ * （可用 DSH_SESSION_GUARD_STATE_DIR 覆盖根目录）。原子写：tmp + rename。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** 状态根目录。 */
+export function storeRoot() {
+  return (
+    process.env.DSH_SESSION_GUARD_STATE_DIR ||
+    join(process.env.DSH_HOME || process.env.HOME || process.cwd(), '.dsh', 'session-guard')
+  )
+}
+
+/** 会话 id → 安全文件名。 */
+function encodeSessionId(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+/** 每会话状态文件路径。 */
+export function stateFilePath(id) {
+  return join(storeRoot(), `${encodeSessionId(id)}.json`)
+}
+
+/** 未锁定基线。 */
+export function idleState(id) {
+  return { sessionId: String(id), queueLocked: false, lockReason: null, updatedAt: null }
+}
+
+/**
+ * 创建存储（内存缓存 + 磁盘持久化）。
+ */
+export function createStore() {
+  const cache = new Map()
+  return {
+    /** 读一会话状态；无记录返回 null（调用方自行 fallback idleState）。 */
+    get(id) {
+      if (cache.has(id)) return cache.get(id)
+      try {
+        const f = stateFilePath(id)
+        if (!existsSync(f)) return null
+        const v = JSON.parse(readFileSync(f, 'utf8'))
+        cache.set(id, v)
+        return v
+      } catch {
+        return null
+      }
+    },
+    /** 原子写。 */
+    set(id, value) {
+      cache.set(id, value)
+      try {
+        const f = stateFilePath(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] store write failed: ${String(e && e.message || e)}`)
+      }
+    },
+    /** 清除（解锁时）。 */
+    clear(id) {
+      cache.delete(id)
+      try {
+        rmSync(stateFilePath(id), { force: true })
+      } catch {
+        /* ignore */
+      }
+    },
+  }
+}

package/src/time.js

@@ -0,0 +1,88 @@
+/**
+ * dsh-session-guard — 时间判定（纯函数，零依赖，可单测）。
+ *
+ * 高峰/周末识别必须基于「配置时区」的墙钟，而不是裸 UTC（D1）：
+ * 周末判断用 `Intl.DateTimeFormat(timeZone)` 投影，避免 off-peak 那种
+ * 用 `getUTCDay()` 导致北京周末边界错 8 小时的 bug。
+ *
+ * 高峰时段为左闭右开 [start, end)；跨午夜窗口（start > end）安全。
+ */
+
+/** 解析 "HH:mm" → 当日分钟数，非法返回 null。 */
+export function parseHHMM(s) {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(s).trim())
+  if (!m) return null
+  const h = Number(m[1])
+  const mi = Number(m[2])
+  if (h > 23 || mi > 59) return null
+  return h * 60 + mi
+}
+
+/** 闭开区间 [s, e)，跨午夜安全（s > e 时视为跨天环绕）。 */
+export function inWindow(t, s, e) {
+  if (s === e) return false
+  return s < e ? t >= s && t < e : t >= s || t < e
+}
+
+/**
+ * 把某时刻投影为配置时区（IANA，DST 感知）的墙钟分量。
+ * @param {string} tz IANA 时区名，如 "Asia/Shanghai"
+ * @param {Date} date
+ * @returns {{year:number,month:number,day:number,weekday:number,minutes:number}}
+ *          weekday: 0=周日 ... 6=周六（与 getUTCDay 同约定，但基于配置时区的日期）
+ */
+export function wallClock(tz, date) {
+  const f = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    hour12: false,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+  const parts = {}
+  for (const p of f.formatToParts(date)) parts[p.type] = p.value
+  const year = Number(parts.year)
+  const month = Number(parts.month)
+  const day = Number(parts.day)
+  // 由该时区的「今天」日期反推 weekday，避免 UTC 边界错位（D1）。
+  const weekday = new Date(Date.UTC(year, month - 1, day)).getUTCDay()
+  const minutes = Number(parts.hour) * 60 + Number(parts.minute)
+  return { year, month, day, weekday, minutes }
+}
+
+/** 周末（0=周日, 6=周六）。 */
+export function isWeekend(weekday) {
+  return weekday === 0 || weekday === 6
+}
+
+/** 某墙钟分钟是否处于任一高峰窗口内。 */
+export function isInPeak(wc, windows) {
+  return windows.some((w) => {
+    const s = parseHHMM(w && w.start)
+    const e = parseHHMM(w && w.end)
+    if (s === null || e === null) return false
+    return inWindow(wc.minutes, s, e)
+  })
+}
+
+/**
+ * 主判定：此刻是否应触发高峰暂停。
+ * @param {object} settings { enabled, weekendMode, timezone, peakWindows }
+ * @param {Date} date
+ * @returns {{pause:boolean, reason:string}}
+ *          reason: 'disabled' | 'weekend' | 'peak' | 'off-peak'
+ */
+export function shouldPause(settings, date) {
+  if (!settings || settings.enabled !== true) return { pause: false, reason: 'disabled' }
+  const wc = wallClock(settings.timezone, date)
+  // 周末模式：识别周末 → 无视峰谷，畅快跑（D6）。
+  if (settings.weekendMode === true && isWeekend(wc.weekday)) {
+    return { pause: false, reason: 'weekend' }
+  }
+  if (isInPeak(wc, settings.peakWindows || [])) {
+    return { pause: true, reason: 'peak' }
+  }
+  return { pause: false, reason: 'off-peak' }
+}