@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/lib/adapter-client.mjs

@@ -0,0 +1,383 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang v2.6.1 — 母体侧 Adapter v3 客户端（契约：docs/PROTOCOL-V3.md §5）。
+//
+// 把「协议协商 + 状态快照 + SSE 事件流 + 断线重连 + cursor 续传 + 幂等命令」封成一个
+// ForkClient。母体（Orchestrator / 未来 Forker 监督器）只接触方法，不碰 HTTP/SSE 细节。
+//
+// 失败语义（刻意与 remote.mjs 一致）：**永不抛出**，全部降级为 `{ok:false, ...}`；
+// 网络/超时类失败按指数退避无限重连，401（token 错误）是致命失败、不重试。
+import { RECONNECT_DEFAULTS, createSseParser, negotiateProtocol, newCommandId } from './adapter-protocol.mjs'
+import { classifyRemoteFailure, createRemote } from './remote.mjs'
+
+const msgOf = (e) => String(e && e.message !== undefined ? e.message : e)
+
+const positiveMs = (value, fallback) => {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.url]          分身 web URL（可自带 `?token=`）
+ * @param {string} [options.token]        DSH web token（也用于 SSE 的 ?token=）
+ * @param {string} [options.adapterToken] v3 Bearer token（不落 URL）
+ * @param {Function} [options.fetchImpl]  可注入 fetch（测试用）
+ * @param {number} [options.timeoutMs]
+ * @param {string} [options.prefix]
+ * @param {number} [options.minProtocol]
+ * @param {number} [options.maxProtocol]
+ * @param {{baseMs?:number,maxMs?:number}} [options.reconnect]
+ * @param {boolean} [options.autoReconnect=true] 事件流断开后是否自动重连
+ */
+export function createAdapterClient(options = {}) {
+  const {
+    url,
+    token,
+    adapterToken,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = 8000,
+    prefix = '/fang',
+    minProtocol,
+    maxProtocol,
+    reconnect = {},
+    autoReconnect = true,
+  } = options
+
+  const remote = createRemote({ url, token, adapterToken, fetchImpl, timeoutMs, prefix })
+  const impl = typeof fetchImpl === 'function' ? fetchImpl : null
+  const limits = {
+    ...(Number.isInteger(minProtocol) ? { min: minProtocol } : {}),
+    ...(Number.isInteger(maxProtocol) ? { max: maxProtocol } : {}),
+  }
+  const backoff = {
+    baseMs: positiveMs(reconnect?.baseMs, RECONNECT_DEFAULTS.baseMs),
+    maxMs: positiveMs(reconnect?.maxMs, RECONNECT_DEFAULTS.maxMs),
+  }
+
+  const listeners = {
+    event: new Set(),
+    state: new Set(),
+    reconnect: new Set(),
+    disconnect: new Set(),
+  }
+
+  let mode = 'idle'
+  let protocol = 0
+  let sessionId = ''
+  let lastCursor = '0'
+  let lastState = null
+  let lastVersionInfo = null
+  let sessionMismatch = null
+  let protocolRange = { min: undefined, max: undefined }
+  let lastError = ''
+  let stopped = true
+  let controller = null
+  let pumpPromise = null
+
+  const emit = (kind, payload) => {
+    for (const fn of listeners[kind]) {
+      try {
+        fn(payload)
+      } catch {
+        /* 订阅者异常不得打断连接 */
+      }
+    }
+  }
+
+  const on = (kind) => (fn) => {
+    if (typeof fn !== 'function') return () => {}
+    listeners[kind].add(fn)
+    return () => listeners[kind].delete(fn)
+  }
+
+  const pendingWaits = new Map()
+
+  const wait = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingWaits.delete(timer)
+      resolve()
+    }, ms)
+    pendingWaits.set(timer, resolve)
+  })
+
+  const backoffFor = (attempt) => Math.min(backoff.maxMs, backoff.baseMs * 2 ** Math.min(attempt, 5))
+
+  const headers = () => remote.authHeaders()
+
+  /** 用快照把 cursor/session 对齐（410 cursor-expired / 409 session-changed 后调用）。 */
+  async function resyncFromState(reason) {
+    lastCursor = '0'
+    const snapshot = await remote.state()
+    if (snapshot.ok && snapshot.data) {
+      lastState = snapshot.data
+      if (snapshot.data.sessionId) sessionId = String(snapshot.data.sessionId)
+      lastCursor = String(snapshot.data.lastCursor ?? '0')
+      emit('state', lastState)
+    }
+    emit('reconnect', { resetCursor: true, reason, sessionId, lastCursor })
+    return snapshot
+  }
+
+  /** 打开一次 SSE 连接：返回可判定结果，不抛。 */
+  async function openOnce() {
+    if (!impl) return { ok: false, code: 'no-fetch', fatal: true }
+    controller = new AbortController()
+    const target = remote.eventsUrl({ since: lastCursor, session: sessionId })
+    let res = null
+    try {
+      res = await impl(target, { method: 'GET', headers: headers(), signal: controller.signal })
+    } catch (e) {
+      return { ok: false, code: classifyRemoteFailure(e).kind, error: msgOf(e), retryable: true }
+    }
+    const status = Number(res?.status)
+    if (status === 401) return { ok: false, code: 'unauthorized', status, fatal: true }
+    if (status === 409) {
+      await resyncFromState('session-changed')
+      return { ok: false, code: 'session-changed', status, resync: true, retryable: true }
+    }
+    if (status === 410) {
+      await resyncFromState('cursor-expired')
+      return { ok: false, code: 'cursor-expired', status, resync: true, retryable: true }
+    }
+    if (!(status >= 200 && status < 300)) return { ok: false, code: `http-${status}`, status, retryable: true }
+    return { ok: true, res }
+  }
+
+  /** 读 SSE 流直到结束；解析出的每条事件更新 cursor 并回调 onEvent。 */
+  async function pump(res) {
+    const parser = createSseParser()
+    const body = res?.body
+    const onFrame = (frame) => {
+      if (!frame || !frame.data) return
+      let envelope = null
+      try {
+        envelope = JSON.parse(frame.data)
+      } catch {
+        return
+      }
+      const cursor = frame.id || (envelope && envelope.cursor) || ''
+      if (cursor) lastCursor = String(cursor)
+      if (envelope && envelope.event) emit('event', envelope)
+    }
+    try {
+      if (body && typeof body.getReader === 'function') {
+        const reader = body.getReader()
+        const decoder = new TextDecoder()
+        for (;;) {
+          const chunk = await reader.read()
+          if (chunk.done) return { ok: true }
+          if (chunk.value !== undefined) {
+            for (const frame of parser.push(decoder.decode(chunk.value, { stream: true }))) onFrame(frame)
+          }
+        }
+      }
+      if (body && typeof body[Symbol.asyncIterator] === 'function') {
+        const decoder = new TextDecoder()
+        for await (const value of body) {
+          for (const frame of parser.push(decoder.decode(value, { stream: true }))) onFrame(frame)
+        }
+        return { ok: true }
+      }
+      return { ok: false, code: 'no-stream-body' }
+    } catch (e) {
+      return { ok: false, code: classifyRemoteFailure(e).kind, error: msgOf(e) }
+    }
+  }
+
+  /** 断线后的重连循环：指数退避；401 致命；409/410 先快照对齐再立即重试。 */
+  async function reconnectLoop() {
+    let attempt = 0
+    while (!stopped) {
+      const opened = await openOnce()
+      if (stopped) return
+      if (opened.fatal) {
+        mode = 'failed'
+        lastError = opened.code
+        emit('disconnect', { reason: opened.code, fatal: true })
+        return
+      }
+      if (opened.ok) {
+        attempt = 0
+        mode = 'streaming'
+        emit('reconnect', { resetCursor: false, reason: 'resumed', sessionId, lastCursor })
+        const result = await pump(opened.res)
+        if (stopped) return
+        mode = 'reconnecting'
+        emit('disconnect', { reason: result.code ?? 'stream-closed' })
+        if (!autoReconnect) {
+          mode = 'idle'
+          return
+        }
+        await wait(backoffFor(attempt++))
+        continue
+      }
+      mode = 'reconnecting'
+      lastError = opened.code
+      emit('disconnect', { reason: opened.code, retryable: true })
+      if (opened.resync) {
+        attempt = 0
+        await wait(backoffFor(0))
+        continue
+      }
+      await wait(backoffFor(attempt++))
+    }
+  }
+
+  /**
+   * 建立会话：版本协商 → 首帧快照 → 打开事件流。
+   * 结果可判定：`{ok:true, protocol, sessionId, lastCursor}` 或 `{ok:false, code, fatal|retryable}`。
+   * 首连失败但可重试时仍会启动后台重连（设计上母体不放弃分身，只等在 onDisconnect 里上报）。
+   */
+  async function connect() {
+    stopped = false
+    mode = 'negotiating'
+    const versionRes = await remote.version()
+    if (!versionRes.ok) {
+      const fatal = Number(versionRes.status) === 401
+      mode = fatal ? 'failed' : 'reconnecting'
+      lastError = versionRes.error ?? versionRes.kind ?? 'version-failed'
+      emit('disconnect', { reason: lastError, fatal })
+      return { ok: false, code: lastError, status: versionRes.status ?? 0, fatal }
+    }
+
+    const negotiated = negotiateProtocol(versionRes.data?.protocol, limits)
+    if (!negotiated.ok) {
+      mode = 'failed'
+      lastError = negotiated.reason
+      emit('disconnect', { reason: negotiated.reason, fatal: true })
+      return { ok: false, code: negotiated.reason, protocol: versionRes.data?.protocol }
+    }
+    protocol = negotiated.protocol
+    protocolRange = { min: negotiated.min, max: negotiated.max }
+    lastVersionInfo = versionRes.data && typeof versionRes.data === 'object' ? versionRes.data : { protocol: versionRes.data ?? null }
+    sessionId = String(versionRes.data?.sessionId ?? '')
+
+    const snapshot = await remote.state()
+    if (!snapshot.ok) {
+      const fatal = Number(snapshot.status) === 401
+      mode = fatal ? 'failed' : 'reconnecting'
+      lastError = snapshot.error ?? snapshot.kind ?? 'state-failed'
+      emit('disconnect', { reason: lastError, fatal })
+      return { ok: false, code: lastError, status: snapshot.status ?? 0, fatal }
+    }
+    lastState = snapshot.data ?? null
+    if (lastState?.sessionId) sessionId = String(lastState.sessionId)
+    if (lastState?.lastCursor !== undefined) lastCursor = String(lastState.lastCursor)
+    // 一致性诊断：version 与 state 之间 Adapter 若重启，sessionId 会变化。
+    // 此时 state 是最新真相，继续用 state.sessionId 连接；只记录差异供排障（不重试三步）。
+    const versionSession = String(lastVersionInfo?.sessionId ?? '')
+    const stateSession = String(lastState?.sessionId ?? '')
+    sessionMismatch = versionSession && stateSession && versionSession !== stateSession
+      ? { versionSession, stateSession, at: Date.now() }
+      : null
+    emit('state', lastState)
+
+    const opened = await openOnce()
+    if (stopped) return { ok: false, code: 'stopped' }
+    if (!opened.ok) {
+      if (opened.fatal) {
+        mode = 'failed'
+        lastError = opened.code
+        emit('disconnect', { reason: opened.code, fatal: true })
+        return { ok: false, code: opened.code, fatal: true }
+      }
+      mode = 'reconnecting'
+      if (autoReconnect) void reconnectLoop()
+      return { ok: false, code: opened.code, retryable: true, sessionId, lastCursor }
+    }
+
+    mode = 'streaming'
+    pumpPromise = pump(opened.res).then((result) => {
+      if (stopped) return result
+      mode = autoReconnect ? 'reconnecting' : 'idle'
+      emit('disconnect', { reason: result.code ?? 'stream-closed' })
+      if (autoReconnect) void reconnectLoop()
+      return result
+    })
+    return { ok: true, protocol, sessionId, state: lastState, lastCursor, version: lastVersionInfo, sessionMismatch }
+  }
+
+  /** 停止事件流（幂等）。未到期的退避计时器会被立即唤醒，让重连循环看到 stopped 退出。 */
+  function stop() {
+    stopped = true
+    try {
+      controller?.abort()
+    } catch {
+      /* 老运行时没有 abort 也不影响逻辑 */
+    }
+    controller = null
+    for (const [timer, resolve] of pendingWaits) {
+      clearTimeout(timer)
+      resolve()
+    }
+    pendingWaits.clear()
+    mode = 'idle'
+  }
+
+  /**
+   * 幂等命令：生成 commandId，网络/超时失败时用**同一个** commandId 重试一次。
+   * 服务端命中 CommandCache 会返回 `deduplicated:true`，不会重复执行副作用。
+   */
+  async function command(op, payload = {}, { commandId = newCommandId(), async: isAsync = false, retries = 1 } = {}) {
+    const envelope = { commandId, op: String(op ?? ''), payload: payload ?? {} }
+    if (isAsync) envelope.async = true
+    let result = await remote.commands(envelope)
+    let attempt = 0
+    while (!result.ok && attempt < retries && (result.kind === 'network' || result.kind === 'timeout')) {
+      await wait(backoffFor(attempt++))
+      result = await remote.commands(envelope)
+    }
+    return result
+  }
+
+  return {
+    ...remote,
+    connect,
+    stop,
+    command,
+    onEvent: on('event'),
+    onState: on('state'),
+    onReconnect: on('reconnect'),
+    onDisconnect: on('disconnect'),
+    get mode() {
+      return mode
+    },
+    get protocol() {
+      return protocol
+    },
+    get sessionId() {
+      return sessionId
+    },
+    get lastCursor() {
+      return lastCursor
+    },
+    get lastState() {
+      return lastState
+    },
+    /** 最近一次 /adapter/version 的原始响应（protocol / version / sessionId…），供诊断。 */
+    get lastVersionInfo() {
+      return lastVersionInfo
+    },
+    /** version 与 state 的 sessionId 不一致时记录（Adapter 在两次请求之间重启过）。 */
+    get sessionMismatch() {
+      return sessionMismatch
+    },
+    /** 本客户端实际用于协商的协议区间（min/max），供诊断与上层审计。 */
+    get protocolRange() {
+      return { ...protocolRange }
+    },
+    get lastError() {
+      return lastError
+    },
+    get streaming() {
+      return mode === 'streaming'
+    },
+    /** 等待首帧事件流结束（测试/编排器优雅停止时用）。 */
+    get pumpDone() {
+      return pumpPromise ?? Promise.resolve(null)
+    },
+  }
+}
+
+export const _internals = { positiveMs }

package/src/lib/adapter-protocol.mjs

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang v2.6.1 — Adapter 协议的可共享部分（契约：docs/PROTOCOL-V3.md）。
+//
+// 这里只放**纯函数与纯状态**：cursor 编解码、事件环形缓冲、命令幂等缓存、
+// 协议协商、Bearer 解析、SSE 帧编解码、错误码 → HTTP 状态码。
+// 不 import `node:*`，因此分身侧（adapter.mjs）与母体侧（adapter-client.mjs）
+// 可以共用同一份语义，测试也不需要真实 socket。
+import {
+  ADAPTER_ERROR_STATUS,
+  ADAPTER_PROTOCOL_MIN,
+  ADAPTER_PROTOCOL_VERSION,
+} from '../kernel/types.mjs'
+
+/** 事件环形缓冲默认容量：母体断线后能追多久（1000 条 ≈ 数十分钟的常规事件）。 */
+export const DEFAULT_EVENT_CAPACITY = 1000
+/** 命令幂等缓存默认容量（LRU）。 */
+export const DEFAULT_COMMAND_CACHE_SIZE = 500
+/** SSE 心跳间隔：注释帧，不占 cursor（应小于常见代理 60s idle 超时）。 */
+export const SSE_HEARTBEAT_MS = 15000
+/** 母体侧重连退避默认值（毫秒）。 */
+export const RECONNECT_DEFAULTS = Object.freeze({ baseMs: 500, maxMs: 8000 })
+
+const MAX_UINT64 = 18446744073709551615n
+const DECIMAL_RE = /^(0|[1-9][0-9]{0,19})$/
+const COMMAND_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/
+
+/**
+ * cursor 是单调递增 uint64，JSON 里用十进制字符串表示（bigint 不能 JSON 序列化）。
+ * @param {unknown} value
+ * @returns {bigint|null} 非法输入返回 null（调用方映射 400 cursor-invalid）
+ */
+export function parseCursor(value) {
+  if (typeof value === 'bigint') return value >= 0n && value <= MAX_UINT64 ? value : null
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value) || value < 0) return null
+    return BigInt(value)
+  }
+  if (typeof value !== 'string') return null
+  const text = value.trim()
+  if (!DECIMAL_RE.test(text)) return null
+  try {
+    const n = BigInt(text)
+    return n <= MAX_UINT64 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/** @param {bigint|number|string} value @returns {string} */
+export function formatCursor(value) {
+  try {
+    const n = typeof value === 'bigint' ? value : BigInt(value)
+    return n < 0n ? '0' : n.toString()
+  } catch {
+    return '0'
+  }
+}
+
+/**
+ * 分身侧事件环形缓冲。append 返回完整事件信封；since 支持断线续传。
+ *
+ * cursor 语义（PROTOCOL-V3 §7）：
+ *   * `since=0`  → 从头回放当前缓冲；
+ *   * `since` 落在缓冲内 → 返回之后的事件，gap=false；
+ *   * `since` 早于最旧一条 → gap=true（调用方回 410，让母体重新拉快照）；
+ *   * `since` 超前（分身重启 / 伪造）→ gap=true，reason='cursor-ahead'。
+ */
+export class EventLog {
+  constructor({ capacity = DEFAULT_EVENT_CAPACITY, sessionId = '', now = () => Date.now() } = {}) {
+    const size = Math.floor(Number(capacity))
+    this.capacity = Number.isFinite(size) && size > 0 ? size : DEFAULT_EVENT_CAPACITY
+    this.sessionId = String(sessionId ?? '')
+    this.entries = []
+    this.next = 1n
+    this.now = typeof now === 'function' ? now : () => Date.now()
+  }
+
+  get size() {
+    return this.entries.length
+  }
+
+  /** 最后一条事件的 cursor（空缓冲返回 '0'）。 */
+  get lastCursor() {
+    return this.entries.length > 0 ? this.entries[this.entries.length - 1].cursor : '0'
+  }
+
+  /** 下一条事件将拿到的 cursor（不会回退）。 */
+  get nextCursor() {
+    return formatCursor(this.next)
+  }
+
+  /**
+   * 追加一条事件。
+   * @param {object} event
+   * @returns {{cursor:string, sessionId:string, at:number, event:object}}
+   */
+  append(event) {
+    const cursor = this.next++
+    const body = event && typeof event === 'object' ? event : { kind: 'error', code: 'bad-event' }
+    const envelope = {
+      cursor: formatCursor(cursor),
+      sessionId: this.sessionId,
+      at: this.now(),
+      event: body,
+    }
+    this.entries.push(envelope)
+    if (this.entries.length > this.capacity) {
+      this.entries.splice(0, this.entries.length - this.capacity)
+    }
+    return envelope
+  }
+
+  /**
+   * 取 `cursor` 之后的事件。
+   * @param {unknown} cursor
+   * @returns {{ok:boolean, code?:string, events:object[], gap:boolean, reason?:string,
+   *   lastCursor:string, nextCursor:string, sessionId:string}}
+   */
+  since(cursor) {
+    const parsed = parseCursor(cursor)
+    if (parsed === null) {
+      return {
+        ok: false,
+        code: 'cursor-invalid',
+        events: [],
+        gap: false,
+        lastCursor: this.lastCursor,
+        nextCursor: this.nextCursor,
+        sessionId: this.sessionId,
+      }
+    }
+    const base = { ok: true, events: [], gap: false, lastCursor: this.lastCursor, nextCursor: this.nextCursor, sessionId: this.sessionId }
+    if (this.entries.length === 0) return base
+    if (parsed >= this.next) return { ...base, gap: true, reason: 'cursor-ahead' }
+    const oldest = parseCursor(this.entries[0].cursor)
+    const events = this.entries.filter((entry) => parseCursor(entry.cursor) > parsed)
+    return { ...base, events, gap: oldest !== null && parsed + 1n < oldest }
+  }
+
+  clear() {
+    this.entries = []
+  }
+}
+
+// 命令幂等缓存已独立到 `command-cache.mjs`（v2.6.3 起：in-flight 合并 + 失败契约）；
+// 这里保留 re-export，避免 Adapter 与旧测试的 import 路径断裂。
+export { CommandCache, COMMAND_CACHE_DEFAULT_CAPACITY } from './command-cache.mjs'
+
+/**
+ * 版本协商。父体拿到分身 /adapter/version 的 protocol 后调用。
+ * @param {unknown} remote
+ * @param {{min?:number, max?:number}} [options]
+ * @returns {{ok:boolean, protocol?:number, reason?:string, remote?:unknown, min:number, max:number}}
+ */
+export function negotiateProtocol(remote, { min = ADAPTER_PROTOCOL_MIN, max = ADAPTER_PROTOCOL_VERSION } = {}) {
+  const raw = Number(remote)
+  if (!Number.isInteger(raw) || raw < 1) {
+    return { ok: false, reason: 'protocol-invalid', remote, min, max }
+  }
+  if (raw < min) return { ok: false, reason: 'protocol-too-old', protocol: raw, remote: raw, min, max }
+  if (raw > max) return { ok: false, reason: 'protocol-too-new', protocol: raw, remote: raw, min, max }
+  return { ok: true, protocol: raw, min, max }
+}
+
+/** 从 Authorization 头取 Bearer token（大小写不敏感，空值返回 ''）。 */
+export function parseBearer(header) {
+  const text = String(header ?? '').trim()
+  if (!text) return ''
+  const match = /^Bearer\s+(\S+)$/i.exec(text)
+  return match ? match[1] : ''
+}
+
+/**
+ * 校验并归一化 v3 命令信封。
+ * 接受 `{commandId, op, payload, async}`，也接受嵌套 `{commandId, command:{kind, payload}}`。
+ * @returns {{ok:true, commandId:string, op:string, payload:object, async:boolean} |
+ *   {ok:false, code:'command-id-invalid'|'missing-op', error:string, commandId:string}}
+ */
+export function normalizeCommandEnvelope(input) {
+  const raw = input && typeof input === 'object' ? input : {}
+  const command = raw.command && typeof raw.command === 'object' ? raw.command : null
+  const commandId = raw.commandId === undefined || raw.commandId === null ? '' : String(raw.commandId).trim()
+  if (commandId && !COMMAND_ID_RE.test(commandId)) {
+    return { ok: false, code: 'command-id-invalid', error: 'command-id-invalid', commandId }
+  }
+  const op = String(raw.op ?? command?.op ?? command?.kind ?? '').trim()
+  if (!op) return { ok: false, code: 'missing-op', error: 'missing-op', commandId }
+  const payloadRaw = raw.payload ?? command?.payload
+  const payload = payloadRaw && typeof payloadRaw === 'object' ? payloadRaw : {}
+  const async = raw.async === true || command?.async === true || payload.async === true
+  return { ok: true, commandId, op, payload, async }
+}
+
+/** 构造失败信封（所有 Adapter 端点共用）。 */
+export function adapterError(code, message, extra = null) {
+  const envelope = { ok: false, code: String(code ?? 'internal-error'), error: String(message ?? code ?? 'internal-error') }
+  if (extra && typeof extra === 'object') Object.assign(envelope, extra)
+  return envelope
+}
+
+/** 错误码 → HTTP 状态码（未登记 = 500）。 */
+export function statusForAdapterError(code) {
+  return ADAPTER_ERROR_STATUS[String(code ?? '')] ?? 500
+}
+
+/**
+ * 一条 SSE 帧。data 是事件信封的 JSON（JSON 会转义换行，因此永远是单行）。
+ * @param {{cursor:string, sessionId:string, at:number, event:object}} envelope
+ * @param {string} [eventName]
+ */
+export function sseFrame(envelope, eventName = 'adapter') {
+  const data = JSON.stringify(envelope)
+  return `id: ${envelope.cursor}\nevent: ${eventName}\ndata: ${data}\n\n`
+}
+
+/** SSE 注释帧（心跳/连接确认），不占 cursor。 */
+export function sseComment(text = 'heartbeat') {
+  return `: ${text}\n\n`
+}
+
+/** 连接建立时建议客户端重连间隔。 */
+export const SSE_RETRY_FRAME = 'retry: 2000\n\n'
+
+/**
+ * 增量 SSE 解析器（母体侧）：把任意 chunk 切片还原成完整帧。
+ * v2.6.5 起独立成 `sse-parser.mjs` 的 `SseParser` 类（便于模糊测试）；
+ * `flush()` 按 SSE 规范丢弃未完成的残帧。
+ * @returns {{push:(chunk:unknown)=>object[], flush:()=>object[]}}
+ */
+export { SseParser, createSseParser } from './sse-parser.mjs'
+
+/** 生成一个命令幂等键（crypto.randomUUID 可用时优先）。 */
+export function newCommandId() {
+  try {
+    if (globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function') {
+      return `cmd_${globalThis.crypto.randomUUID()}`
+    }
+  } catch {
+    /* 老运行时退化到时间戳 + 随机串 */
+  }
+  return `cmd_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
+}