dsh-session-guard 0.1.2 → 0.2.0-beta.1

package/src/provider-directory.js

@@ -0,0 +1,101 @@
+/**
+ * dsh-session-guard — 端点目录（host 适配层，读上游只读信息，全部 fail-open）。
+ *
+ * 端点来源（见 findings F4）：
+ *   1. `ctx.get('llm')` 懒取（**不进 inject**：llm 缺失时降级为纯 id 判定，保持 fail-open）；
+ *   2. `llm.listConfigurableProviders()` 按 `entry.provider === id` 找到目录条目
+ *      （`{ settingsNs, settingsPath }`）；
+ *   3. `ctx.settings.get(settingsNs)` 读该命名空间解析值，按 `settingsPath` 逐层取 profile 的 `baseURL`；
+ *   4. 交给纯函数 `classifyProvider`。
+ *
+ * 只读非密字段（`baseURL`），绝不触碰 `apiKeyEnv` 的值。
+ * `llm-deepseek` / `llm-pi-ai` 的内部结构属上游实现细节：任何异常 / 形状不符
+ * 一律降级为「无端点」，由 `classifyProvider` 走 id / 内置端点兜底，**绝不抛出**。
+ *
+ * 每次请求实时计算（两次内存读 + 一次目录枚举），不缓存 → 免疫 provider 配置热改。
+ */
+import { classifyProvider } from './provider.js'
+
+/** 逐层按 path 取值；任一层不是对象即返回 undefined。 */
+function pickPath(root, path) {
+  let cur = root
+  for (const key of path) {
+    if (cur === null || typeof cur !== 'object') return undefined
+    cur = cur[key]
+  }
+  return cur
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.ctx host context（需 `get` / `settings`，两者缺失均降级）
+ * @param {()=>object} deps.getSettings 读实时配置（officialProviders / officialBaseURLs）
+ * @param {(msg:string)=>void} [deps.warn] 诊断日志
+ * @returns {{classify:(providerId:string)=>{official:boolean,matchedBy:string}, describe:(providerId:string)=>object, endpointOf:(providerId:string)=>string|null, entries:()=>object[]}}
+ */
+export function createProviderDirectory({ ctx, getSettings, warn }) {
+  function readCfg() {
+    try {
+      const v = getSettings()
+      return v && typeof v === 'object' ? v : {}
+    } catch {
+      return {}
+    }
+  }
+
+  /** 目录条目（llm 服务缺失 / 抛错 → 空数组）。 */
+  function entries() {
+    try {
+      const llm = ctx && typeof ctx.get === 'function' ? ctx.get('llm') : null
+      if (!llm || typeof llm.listConfigurableProviders !== 'function') return []
+      const list = llm.listConfigurableProviders()
+      return Array.isArray(list) ? list : []
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * 读某路由的实时端点（`baseURL`）；取不到返回 null。
+   * @param {string} providerId
+   * @returns {string|null}
+   */
+  function endpointOf(providerId) {
+    if (typeof providerId !== 'string' || providerId === '') return null
+    try {
+      const entry = entries().find((e) => e && e.provider === providerId)
+      if (!entry) return null
+      const settings = ctx && ctx.settings
+      if (!settings || typeof settings.get !== 'function') return null
+      const section = settings.get(entry.settingsNs)
+      const profile = pickPath(section, Array.isArray(entry.settingsPath) ? entry.settingsPath : [])
+      const baseURL = profile && typeof profile === 'object' ? profile.baseURL : undefined
+      return typeof baseURL === 'string' && baseURL.trim() !== '' ? baseURL : null
+    } catch (e) {
+      if (warn) warn(`provider directory lookup failed for "${providerId}": ${String(e && e.message || e)}`)
+      return null
+    }
+  }
+
+  /**
+   * 判定某路由是否官方源（端点优先 + id 兜底）。
+   * @param {string} providerId
+   * @returns {{official:boolean, matchedBy:'explicit'|'endpoint'|'endpoint-default'|'route-id'|'unknown'}}
+   */
+  function classify(providerId) {
+    const cfg = readCfg()
+    return classifyProvider(providerId, {
+      endpoint: endpointOf(providerId),
+      officialProviders: cfg.officialProviders,
+      officialHosts: cfg.officialBaseURLs,
+    })
+  }
+
+  /** 带可解释信息的判定结果（日志 / 路由诊断用）。 */
+  function describe(providerId) {
+    const r = classify(providerId)
+    return { provider: providerId, official: r.official, matchedBy: r.matchedBy, endpoint: endpointOf(providerId) }
+  }
+
+  return { classify, describe, endpointOf, entries }
+}

package/src/provider.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-session-guard — 官方 provider 判定（纯函数，零依赖，可单测）。
+ *
+ * 目标：判断「这次请求真正要去的路由」是不是 DeepSeek 官方源。
+ *
+ * 判定口径（优先级从高到低）：
+ *   1. `officialProviders` 显式名单（用户最高优先，精确 id 匹配）
+ *   2. 实时端点 `baseURL`（归一化 host 后与官方 host 名单比对）
+ *   3. 内置端点兜底（catalog 默认端点，如 pi-ai 的 `deepseek`）
+ *   4. 内置 id 名单（`deepseek-official`）
+ *   5. 未知 → 非官方
+ *
+ * 端点优先的理由（见 findings F3）：
+ * - 名为 `deepseek-official` 但把 `baseURL` 改到中转的配置必须**不拦**（第 2 步先命中）；
+ * - pi-ai 内置 `deepseek` 路由的 catalog 端点就是官方 API，只按 id 会**漏拦**（第 3 步兜底）。
+ *
+ * 纯函数：不读 ctx / settings / 网络，输入即输出，便于穷举判定矩阵。
+ */
+
+/** 内置官方 provider id 名单（catalog 路由 id）。 */
+export const BUILTIN_OFFICIAL_IDS = Object.freeze(['deepseek-official'])
+
+/**
+ * 内置路由 → 默认端点映射。
+ * - `deepseek-official`：`dsh-llm-deepseek` 的 `PUBLIC_BASE_URL`（schema 无默认值，用户没配时用它兜底）。
+ * - `deepseek`：pi-ai 内置 catalog 的两个模型 `baseUrl` 均为官方端点（本机 pi-ai 0.82.1 实测）。
+ */
+export const BUILTIN_OFFICIAL_ENDPOINTS = Object.freeze({
+  'deepseek-official': 'https://api.deepseek.com',
+  deepseek: 'https://api.deepseek.com',
+})
+
+/** 默认官方端点 host 名单（`officialBaseURLs` 设置项可增删）。 */
+export const DEFAULT_OFFICIAL_HOSTS = Object.freeze(['api.deepseek.com'])
+
+/** `matchedBy` 的全部合法取值。 */
+export const MATCHED_BY = Object.freeze(['explicit', 'endpoint', 'endpoint-default', 'route-id', 'unknown'])
+
+/**
+ * 归一化端点 → host（小写、无协议、无 www.、无端口、无路径）。
+ *
+ * 接受 `https://API.DeepSeek.com/v1`、`//host/path`、`host:8200`、裸 `host`；
+ * 非法值（空串 / null / 含空格 / 非字符串）返回 `null`。
+ * @param {unknown} raw 原始端点（provider 的 `baseURL`）
+ * @returns {string|null} 归一化后的 host，或 null
+ */
+export function normalizeEndpoint(raw) {
+  if (typeof raw !== 'string') return null
+  let s = raw.trim().toLowerCase()
+  if (s === '') return null
+  // 剥协议（http:// https:// 或协议相对 //）
+  s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//, '')
+  s = s.replace(/^\/\//, '')
+  // 剥 userinfo（user:pass@host）
+  const at = s.indexOf('@')
+  if (at !== -1) s = s.slice(at + 1)
+  // 剥路径 / 查询 / 片段
+  s = s.split(/[/?#]/, 1)[0]
+  if (s === '') return null
+  // 剥端口（IPv6 形如 [::1]:8200 只取括号内）
+  if (s.startsWith('[')) {
+    const close = s.indexOf(']')
+    if (close === -1) return null
+    const host6 = s.slice(1, close)
+    return /^[0-9a-f:.]+$/.test(host6) ? host6 : null
+  }
+  s = s.replace(/:\d+$/, '')
+  if (s === '') return null
+  // 剥前导 www.
+  s = s.replace(/^www\./, '')
+  if (s === '') return null
+  // host 合法性：字母数字 + 连字符 + 点（拒绝空格、下划线、非 ASCII 等）
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/.test(s)) return null
+  return s
+}
+
+/**
+ * host 是否属于官方端点名单（精确匹配，名单项同样归一化）。
+ * @param {string|null} host 归一化 host
+ * @param {readonly string[]|undefined} hosts 官方 host 名单（可含协议/端口，会被归一化）
+ * @returns {boolean}
+ */
+export function isOfficialEndpoint(host, hosts) {
+  if (typeof host !== 'string' || host === '') return false
+  const list = Array.isArray(hosts) && hosts.length > 0 ? hosts : DEFAULT_OFFICIAL_HOSTS
+  for (const item of list) {
+    const norm = normalizeEndpoint(item)
+    if (norm !== null && norm === host) return true
+  }
+  return false
+}
+
+/**
+ * 五级判定：这次请求的目标 provider 是否官方源。
+ * @param {string} providerId 路由 id（`next()` 返回值里的 `config.provider`）
+ * @param {object} [options]
+ * @param {string|null} [options.endpoint] 实时端点（settings 里的 `baseURL`，取不到为 null）
+ * @param {readonly string[]} [options.officialProviders] 用户显式追加的官方 id
+ * @param {readonly string[]} [options.officialHosts] 官方端点 host 名单
+ * @param {readonly string[]} [options.builtinIds] 内置官方 id 名单
+ * @param {Record<string,string>} [options.builtinEndpoints] 内置路由 → 默认端点
+ * @returns {{official: boolean, matchedBy: 'explicit'|'endpoint'|'endpoint-default'|'route-id'|'unknown'}}
+ */
+export function classifyProvider(providerId, options = {}) {
+  const id = typeof providerId === 'string' ? providerId.trim() : ''
+  const explicit = Array.isArray(options.officialProviders) ? options.officialProviders : []
+  const hosts = options.officialHosts
+  const builtinIds = Array.isArray(options.builtinIds) ? options.builtinIds : BUILTIN_OFFICIAL_IDS
+  const builtinEndpoints =
+    options.builtinEndpoints && typeof options.builtinEndpoints === 'object'
+      ? options.builtinEndpoints
+      : BUILTIN_OFFICIAL_ENDPOINTS
+
+  // 1) 用户显式名单最高优先（精确 id，大小写敏感以保持可预测）
+  if (id !== '' && explicit.some((x) => typeof x === 'string' && x === id)) {
+    return { official: true, matchedBy: 'explicit' }
+  }
+
+  // 2) 实时端点优先于 id：中转改到别处 → 不拦
+  const endpointHost = normalizeEndpoint(options.endpoint)
+  if (endpointHost !== null) {
+    return { official: isOfficialEndpoint(endpointHost, hosts), matchedBy: 'endpoint' }
+  }
+
+  // 3) 内置端点兜底（catalog 默认端点，插件看不到 settings 时的官方路由）
+  const builtinRaw = id !== '' ? builtinEndpoints[id] : undefined
+  const builtinHost = normalizeEndpoint(builtinRaw)
+  if (builtinHost !== null) {
+    return { official: isOfficialEndpoint(builtinHost, hosts), matchedBy: 'endpoint-default' }
+  }
+
+  // 4) 内置 id 兜底
+  if (id !== '' && builtinIds.some((x) => typeof x === 'string' && x === id)) {
+    return { official: true, matchedBy: 'route-id' }
+  }
+
+  // 5) 未知 → 非官方（fail-open：非官方即放行，绝不在未知路径上拦）
+  return { official: false, matchedBy: 'unknown' }
+}

package/src/request-guard.js

@@ -0,0 +1,191 @@
+/**
+ * dsh-session-guard — 请求级守卫（`agent/request` waterfall，host）。
+ *
+ * 为什么需要它（findings F6）：现有 tick 只在 `NORMAL → PAUSED_PEAK` 跳变时处理
+ * `status === 'running'` 的会话，入峰后新启动的会话、以及入峰后切到官方源的会话
+ * 都漏网。请求级兜底覆盖这两个缺口。
+ *
+ * 判定顺序（**必须先 await next()**，见 findings F2：`installModelSelection` 会在
+ * waterfall 内把 provider/model 覆盖成用户在 UI 选的值）：
+ *   1. `providerGuard !== true` → 原样放行（退回现有纯时间判定）
+ *   2. 非 root agent 且 `guardSubagents === false` → 放行
+ *   3. 非高峰（含周末 / disabled）→ 放行
+ *   4. 目标 provider 非官方 → 放行（本地/第三方源照常跑）
+ *   5. 高峰 + 官方 → 拦截：hold（默认，挂起不报错）或 error（抛 PeakDeferredError）
+ *
+ * **互斥铁律**（findings F7）：hold 路径**严禁**调用 `gate.stopNextTurn` /
+ * `pauseGate.pause`——暂停要等安全边界，而请求被挂住后永远到不了安全边界，双方互等。
+ *
+ * 任何判定异常都 fail-open 放行（绝不因为本插件让正常请求失败）。
+ */
+import { shouldPause } from './time.js'
+import { PeakDeferredError } from './deferrals.js'
+
+/**
+ * 默认 root 判定：优先 `agents.roots()`，查不到再看 `agents.list()`；
+ * 两边都查不到 → 视为 root（fail-open 到「纳入守卫」）。
+ * @param {object} ctx
+ * @returns {(agent:object)=>boolean}
+ */
+export function makeIsRoot(ctx) {
+  return function isRoot(agent) {
+    try {
+      const agents = ctx && ctx.agents
+      const id = String((agent && agent.id) ?? '')
+      if (!agents || id === '') return true
+      const roots = typeof agents.roots === 'function' ? agents.roots() : []
+      if (Array.isArray(roots) && roots.some((a) => String((a && a.id) ?? '') === id)) return true
+      const all = typeof agents.list === 'function' ? agents.list() : []
+      if (Array.isArray(all) && all.some((a) => String((a && a.id) ?? '') === id)) return false
+      return true
+    } catch {
+      return true
+    }
+  }
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.ctx host context（需 `on` / 可选 `agents`）
+ * @param {()=>object} deps.getSettings 读实时配置
+ * @param {{classify:(id:string)=>{official:boolean,matchedBy:string}}} deps.directory 端点目录
+ * @param {ReturnType<import('./deferrals.js').createDeferrals>} deps.deferrals 延后登记表
+ * @param {{stopNextTurn:(id:string,opts?:object)=>unknown}} [deps.gate] 会话门（**仅 error 模式**使用）
+ * @param {object} [deps.logger]
+ * @param {()=>Date} [deps.clock]
+ * @param {(agent:object)=>boolean} [deps.isRoot]
+ * @param {(ms:number)=>void} [deps.scheduleRelease] 挂起后请求一次退峰释放检查
+ * @returns {{install:()=>()=>void, handle:(payload:object, next:Function)=>Promise<unknown>, stats:()=>object}}
+ */
+export function createRequestGuard({
+  ctx,
+  getSettings,
+  directory,
+  deferrals,
+  gate,
+  logger,
+  clock = () => new Date(),
+  isRoot,
+  scheduleRelease,
+}) {
+  const rootCheck = isRoot ?? makeIsRoot(ctx)
+  const counters = { pass: 0, hold: 0, error: 0, skippedSubagent: 0, failOpen: 0 }
+
+  function readCfg() {
+    try {
+      const v = getSettings()
+      return v && typeof v === 'object' ? v : {}
+    } catch {
+      return {}
+    }
+  }
+
+  /** 同步决策：pass / error / hold。 */
+  function decide(payload, config) {
+    const cfg = readCfg()
+    if (cfg.providerGuard !== true) return { action: 'pass', why: 'provider-guard-off' }
+
+    const agent = payload && payload.agent
+    const sessionId = String((agent && agent.id) ?? '')
+    if (sessionId === '') {
+      logger?.warn?.('[session-guard] agent/request without agent.id — provider guard skipped')
+      counters.failOpen += 1
+      return { action: 'pass', why: 'no-session-id' }
+    }
+    if (cfg.guardSubagents === false && !rootCheck(agent)) {
+      counters.skippedSubagent += 1
+      return { action: 'pass', why: 'subagent' }
+    }
+
+    const verdict = shouldPause(cfg, clock())
+    if (!verdict.pause) return { action: 'pass', why: verdict.reason }
+
+    const cls = directory.classify(config && config.provider)
+    if (!cls.official) {
+      logger?.info?.(`[session-guard] peak but target "${String(config && config.provider)}" is not official (matchedBy=${cls.matchedBy}) — pass`)
+      return { action: 'pass', why: 'not-official' }
+    }
+
+    const info = {
+      provider: (config && config.provider) ?? null,
+      model: (config && config.model) ?? null,
+      config,
+      matchedBy: cls.matchedBy,
+    }
+    const mode = cfg.deferredMode === 'error' ? 'error' : 'hold'
+    const resume = cfg.deferredResume !== false
+
+    // 退峰不自动续跑：hold 也无法自动放行 → 直接转 error（避免无限挂起）
+    if (mode === 'hold' && resume) {
+      counters.hold += 1
+      logger?.info?.(`[session-guard] peak + official "${info.provider}/${info.model}" — holding request of ${sessionId} (matchedBy=${cls.matchedBy})`)
+      const promise = deferrals.hold(sessionId, info, payload && payload.signal)
+      if (scheduleRelease) {
+        try {
+          scheduleRelease()
+        } catch (e) {
+          logger?.warn?.(`[session-guard] release scheduling failed: ${String(e && e.message || e)}`)
+        }
+      }
+      return { action: 'hold', promise }
+    }
+
+    // error 模式（或 deferredResume=false）：记延后 + 抛可识别的错误
+    counters.error += 1
+    deferrals.remember(sessionId, info)
+    // 互斥铁律只约束 hold 路径；error 路径回合立刻结束，调门控是安全的。
+    if (gate && typeof gate.stopNextTurn === 'function') {
+      try {
+        const r = gate.stopNextTurn(sessionId, { mode: cfg.pauseMode, reason: cfg.pauseReason })
+        if (r && typeof r.then === 'function') {
+          r.then(undefined, (e) => logger?.warn?.(`[session-guard] stopNextTurn failed: ${String(e && e.message || e)}`))
+        }
+      } catch (e) {
+        logger?.warn?.(`[session-guard] stopNextTurn threw: ${String(e && e.message || e)}`)
+      }
+    }
+    logger?.info?.(`[session-guard] peak + official "${info.provider}/${info.model}" — deferring ${sessionId} with error (mode=${mode}, resume=${resume})`)
+    const detail = resume
+      ? `peak hours: ${info.provider}/${info.model} deferred to off-peak`
+      : `peak hours: ${info.provider}/${info.model} deferred; auto-resume disabled`
+    return { action: 'error', error: new PeakDeferredError(detail, { sessionId, ...info, config: undefined }) }
+  }
+
+  /** 一次 waterfall 调用。 */
+  async function handle(payload, next) {
+    const config = await next()
+    let decision
+    try {
+      decision = decide(payload, config)
+    } catch (e) {
+      // 判定异常 → fail-open 放行；但自己的延后错误必须抛出
+      if (e && e.code === 'PEAK_DEFERRED') throw e
+      counters.failOpen += 1
+      logger?.warn?.(`[session-guard] request guard failed open: ${String(e && e.message || e)}`)
+      return config
+    }
+    if (decision.action === 'pass') {
+      counters.pass += 1
+      return config
+    }
+    if (decision.action === 'error') throw decision.error
+    // hold：挂起 promise 的 resolve 值就是原 config（字段未被篡改）
+    return decision.promise
+  }
+
+  /** 注册 waterfall 监听；返回 disposer（同时释放全部挂起，避免 promise 泄漏）。 */
+  function install() {
+    if (!ctx || typeof ctx.on !== 'function') return () => {}
+    const off = ctx.on('agent/request', (payload, next) => handle(payload, next))
+    return () => {
+      if (typeof off === 'function') off()
+      try {
+        deferrals.rejectAll('guard-disposed')
+      } catch {
+        /* 释放失败不阻断卸载 */
+      }
+    }
+  }
+
+  return { install, handle, decide, stats: () => ({ ...counters }) }
+}