dsh-plugin-weapp-gateway 0.8.23 → 0.8.34

package/lib/relay-state.mjs

@@ -1,76 +1,83 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import crypto from 'node:crypto'
-
-// Pairing payload shapes. `direct` keeps the historical QR that advertises the
-// gateway's own ws/wss endpoints; `relay` emits the outbound-relay payload the
-// WeChat mini-program consumes. Both stay supported and the operator picks one.
-export const PAIRING_MODES = ['direct', 'relay']
-
-const NODE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
-const BASE64 = /^[A-Za-z0-9+/]{20,}={0,2}$/
-
-const isRelay = (value) => value && typeof value === 'object' && !Array.isArray(value)
-  && typeof value.relay === 'string' && /^wss?:\/\//.test(value.relay)
-  && typeof value.nodeId === 'string' && NODE_ID.test(value.nodeId)
-  && typeof value.agentPubKey === 'string' && BASE64.test(value.agentPubKey)
-  && typeof value.gatewayName === 'string' && value.gatewayName.length > 0
-  && value.gatewayName.length <= 80
-  && Number.isSafeInteger(value.updatedAt)
-
-// A dedicated file keeps the relay registration independent of device
-// revocation and of the gateway identity. A malformed file must fail startup
-// rather than silently drop a registration the operator relies on.
-export function createRelayState(file) {
-  const validate = (value) => {
-    if (!value || value.version !== 1) throw new Error('invalid relay state')
-    if (!PAIRING_MODES.includes(value.pairingMode)) throw new Error('invalid pairing mode')
-    if (value.relay !== null && !isRelay(value.relay)) throw new Error('invalid relay registration')
-    return value
-  }
-  const read = () => validate(JSON.parse(fs.readFileSync(file, 'utf8')))
-  const write = (value, initial = false) => {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
-    const tmp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`
-    try {
-      fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' })
-      if (initial) fs.linkSync(tmp, file) // Never overwrite a concurrently created file.
-      else fs.renameSync(tmp, file)
-    } finally {
-      fs.rmSync(tmp, { force: true })
-    }
-  }
-  let state
-  try {
-    try {
-      state = read()
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error
-      // `direct` is the historical behaviour, so an existing installation that
-      // has never seen a relay keeps producing exactly the QR it always did.
-      state = { version: 1, pairingMode: 'direct', relay: null }
-      try { write(state, true) } catch (cause) {
-        if (cause.code !== 'EEXIST') throw cause
-        state = read()
-      }
-    }
-    fs.chmodSync(file, 0o600)
-  } catch (error) {
-    throw new Error(`failed to load relay state ${file}: ${error.message}`, { cause: error })
-  }
-  return {
-    get pairingMode() { return state.pairingMode },
-    get relay() { return state.relay },
-    setPairingMode(mode) {
-      if (!PAIRING_MODES.includes(mode)) throw new TypeError('invalid pairing mode')
-      const next = { ...state, pairingMode: mode }
-      write(next)
-      state = next
-    },
-    setRelay(relay) {
-      const next = { ...state, relay: relay === null ? null : { ...relay, updatedAt: Date.now() } }
-      write(next)
-      state = next
-    },
-  }
-}
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+// Pairing payload shapes. `direct` keeps the historical QR that advertises the
+// gateway's own ws/wss endpoints; `relay` emits the outbound-relay payload the
+// WeChat mini-program consumes. Both stay supported; selecting one only changes
+// the payload emitted for newly generated pairing codes.
+export const PAIRING_MODES = ['direct', 'relay']
+
+// Pairing mode chooses the payload for the next QR; a registered relay is an
+// independent live route and must stay up while direct clients are paired.
+export function shouldRunRelayConnector(state) {
+  return state?.pairingMode === 'relay' || state?.relay != null
+}
+
+const NODE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+const BASE64 = /^[A-Za-z0-9+/]{20,}={0,2}$/
+
+const isRelay = (value) => value && typeof value === 'object' && !Array.isArray(value)
+  && typeof value.relay === 'string' && /^wss?:\/\//.test(value.relay)
+  && typeof value.nodeId === 'string' && NODE_ID.test(value.nodeId)
+  && typeof value.agentPubKey === 'string' && BASE64.test(value.agentPubKey)
+  && typeof value.gatewayName === 'string' && value.gatewayName.length > 0
+  && value.gatewayName.length <= 80
+  && Number.isSafeInteger(value.updatedAt)
+
+// A dedicated file keeps the relay registration independent of device
+// revocation and of the gateway identity. A malformed file must fail startup
+// rather than silently drop a registration the operator relies on.
+export function createRelayState(file) {
+  const validate = (value) => {
+    if (!value || value.version !== 1) throw new Error('invalid relay state')
+    if (!PAIRING_MODES.includes(value.pairingMode)) throw new Error('invalid pairing mode')
+    if (value.relay !== null && !isRelay(value.relay)) throw new Error('invalid relay registration')
+    return value
+  }
+  const read = () => validate(JSON.parse(fs.readFileSync(file, 'utf8')))
+  const write = (value, initial = false) => {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+    const tmp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`
+    try {
+      fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' })
+      if (initial) fs.linkSync(tmp, file) // Never overwrite a concurrently created file.
+      else fs.renameSync(tmp, file)
+    } finally {
+      fs.rmSync(tmp, { force: true })
+    }
+  }
+  let state
+  try {
+    try {
+      state = read()
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+      // `direct` is the historical behaviour, so an existing installation that
+      // has never seen a relay keeps producing exactly the QR it always did.
+      state = { version: 1, pairingMode: 'direct', relay: null }
+      try { write(state, true) } catch (cause) {
+        if (cause.code !== 'EEXIST') throw cause
+        state = read()
+      }
+    }
+    fs.chmodSync(file, 0o600)
+  } catch (error) {
+    throw new Error(`failed to load relay state ${file}: ${error.message}`, { cause: error })
+  }
+  return {
+    get pairingMode() { return state.pairingMode },
+    get relay() { return state.relay },
+    setPairingMode(mode) {
+      if (!PAIRING_MODES.includes(mode)) throw new TypeError('invalid pairing mode')
+      const next = { ...state, pairingMode: mode }
+      write(next)
+      state = next
+    },
+    setRelay(relay) {
+      const next = { ...state, relay: relay === null ? null : { ...relay, updatedAt: Date.now() } }
+      write(next)
+      state = next
+    },
+  }
+}

package/lib/session-follower.mjs

@@ -1,136 +1,140 @@
-import crypto from 'node:crypto'
-import { readSessionSnapshot } from './dsh-host-adapter.mjs'
-
-function integer(value, minimum = 0) {
-  return Number.isSafeInteger(value) && value >= minimum
-}
-
-function requireAttempt(attempt) {
-  if (!attempt || typeof attempt.attemptId !== 'string' || !attempt.attemptId
-    || !integer(attempt.turn) || !integer(attempt.step)
-    || !integer(attempt.startedAfterSeq, -1)) throw new Error('invalid assistant attempt')
-  return attempt
-}
-
-// Validate the two independent clocks. No transient frame owns a Session seq.
-export function createFollowDecoder(sessionId) {
-  let cursor
-  let revision
-  let active
-  return frame => {
-    if (cursor === undefined) {
-      const history = readSessionSnapshot(frame, sessionId)
-      const baseline = frame.assistantStream
-      if (!baseline || !integer(baseline.revision)) throw new Error('missing assistant stream baseline')
-      if (baseline.activeAttempt !== undefined) {
-        const attempt = requireAttempt(baseline.activeAttempt)
-        if (!integer(attempt.nextIndex) || !Array.isArray(attempt.stream)
-          || attempt.startedAfterSeq > history.cursor) throw new Error('invalid assistant baseline')
-        active = { ...attempt }
-      }
-      cursor = history.cursor
-      revision = baseline.revision
-      return { type: 'snapshot', history, assistantStream: baseline }
-    }
-    if (frame?.type === 'event') {
-      if (!frame.event || frame.event.seq !== cursor + 1) throw new Error('session event sequence gap')
-      cursor = frame.event.seq
-      return frame
-    }
-    if (frame?.type !== 'assistant-stream') throw new Error('unexpected session follow frame')
-    const next = frame.frame
-    if (!next || next.revision !== revision + 1) throw new Error('assistant stream revision gap')
-    if (next.type === 'start') {
-      requireAttempt(next)
-      if (active || next.startedAfterSeq > cursor) throw new Error('unexpected assistant start')
-      active = { ...next, nextIndex: 0 }
-    } else {
-      if (!active || next.attemptId !== active.attemptId || next.index !== active.nextIndex) {
-        throw new Error('assistant stream attempt/index gap')
-      }
-      if (next.type === 'chunk') {
-        if (!integer(next.time) || !next.chunk || typeof next.chunk.type !== 'string') {
-          throw new Error('invalid assistant chunk')
-        }
-        active.nextIndex += 1
-      } else if (next.type === 'end') {
-        const outcome = next.outcome
-        if (!outcome || (outcome.kind !== 'abandoned' && (outcome.kind !== 'committed'
-          || !['assistant/message', 'assistant/attempt'].includes(outcome.eventType)
-          || !integer(outcome.seq) || outcome.seq > cursor || outcome.seq <= active.startedAfterSeq))) {
-          throw new Error('invalid assistant settlement')
-        }
-      } else throw new Error('unexpected assistant frame')
-    }
-    revision = next.revision
-    const normalized = { ...next, turn: active.turn, step: active.step }
-    if (next.type === 'end') active = undefined
-    return { type: 'assistant-stream', frame: normalized }
-  }
-}
-
-function delay(ms, signal) {
-  return new Promise(resolve => {
-    if (signal.aborted) return resolve()
-    const finish = () => {
-      clearTimeout(timer)
-      signal.removeEventListener('abort', finish)
-      resolve()
-    }
-    const timer = setTimeout(finish, ms)
-    signal.addEventListener('abort', finish, { once: true })
-  })
-}
-
-// One follow per opted-in connection. Each opening owns a new stream identity
-// and atomic snapshot, including a reconnecting Agent's active attempt.
-export function createSessionFollower(api, { onFrame, onError, retryMs = 1000 }) {
-  let current
-  const stop = () => {
-    const previous = current
-    current = undefined
-    previous?.abort.abort()
-  }
-  const start = (sessionId, subscriptionId) => {
-    stop()
-    const state = { abort: new AbortController() }
-    current = state
-    const task = (async () => {
-      let failures = 0
-      while (current === state && !state.abort.signal.aborted) {
-        const attemptAbort = new AbortController()
-        const signal = AbortSignal.any([state.abort.signal, attemptAbort.signal])
-        const streamId = crypto.randomUUID()
-        const context = { sessionId, subscriptionId, streamId }
-        const decode = createFollowDecoder(sessionId)
-        let iterator
-        let permanent = false
-        try {
-          const stream = await api.openSessionStream(sessionId, signal)
-          iterator = stream[Symbol.asyncIterator]()
-          while (current === state && !signal.aborted) {
-            const item = await iterator.next()
-            if (current !== state || signal.aborted) break
-            if (item.done) throw new Error('session follow ended')
-            const decoded = decode(item.value)
-            onFrame(decoded, context)
-          }
-        } catch (error) {
-          if (current !== state || signal.aborted) break
-          permanent = ['unsupported-session-format', 'session/not-found', 'gateway/bad-request'].includes(error.code)
-            || (error.code === 'SESSION_QUERY_PERSISTENCE_FAILED'
-              && /refuses this format .*Session/.test(error.message || ''))
-          onError(error, { ...context, retrying: !permanent })
-        } finally {
-          // Abort before return: the producer may be waiting for another event.
-          attemptAbort.abort()
-          try { await iterator?.return?.() } catch { /* The opening failure was already reported. */ }
-        }
-        if (permanent) break
-        await delay(Math.min(retryMs * 2 ** Math.min(failures++, 5), 30_000), state.abort.signal)
-      }
-    })()
-    return task
-  }
-  return { start, stop }
-}
+import crypto from 'node:crypto'
+import { readSessionSnapshot } from './dsh-host-adapter.mjs'
+
+function integer(value, minimum = 0) {
+  return Number.isSafeInteger(value) && value >= minimum
+}
+
+function requireAttempt(attempt) {
+  if (!attempt || typeof attempt.attemptId !== 'string' || !attempt.attemptId
+    || !integer(attempt.turn) || !integer(attempt.step)
+    || !integer(attempt.startedAfterSeq, -1)) throw new Error('invalid assistant attempt')
+  return attempt
+}
+
+// Validate the two independent clocks. No transient frame owns a Session seq.
+export function createFollowDecoder(sessionId) {
+  let cursor
+  let revision
+  let active
+  return frame => {
+    if (cursor === undefined) {
+      const history = readSessionSnapshot(frame, sessionId)
+      const baseline = frame.assistantStream
+      if (!baseline || !integer(baseline.revision)) throw new Error('missing assistant stream baseline')
+      if (baseline.activeAttempt !== undefined) {
+        const attempt = requireAttempt(baseline.activeAttempt)
+        if (!integer(attempt.nextIndex) || !Array.isArray(attempt.stream)
+          || attempt.startedAfterSeq > history.cursor) throw new Error('invalid assistant baseline')
+        active = { ...attempt }
+      }
+      cursor = history.cursor
+      revision = baseline.revision
+      return { type: 'snapshot', history, assistantStream: baseline }
+    }
+    if (frame?.type === 'event') {
+      if (!frame.event || frame.event.seq !== cursor + 1) throw new Error('session event sequence gap')
+      cursor = frame.event.seq
+      return frame
+    }
+    if (frame?.type !== 'assistant-stream') throw new Error('unexpected session follow frame')
+    const next = frame.frame
+    if (!next || next.revision !== revision + 1) throw new Error('assistant stream revision gap')
+    if (next.type === 'start') {
+      requireAttempt(next)
+      if (active || next.startedAfterSeq > cursor) throw new Error('unexpected assistant start')
+      active = { ...next, nextIndex: 0 }
+    } else {
+      if (!active || next.attemptId !== active.attemptId || next.index !== active.nextIndex) {
+        throw new Error('assistant stream attempt/index gap')
+      }
+      if (next.type === 'chunk') {
+        if (!integer(next.time) || !next.chunk || typeof next.chunk.type !== 'string') {
+          throw new Error('invalid assistant chunk')
+        }
+        active.nextIndex += 1
+      } else if (next.type === 'end') {
+        const outcome = next.outcome
+        if (!outcome || (outcome.kind !== 'abandoned' && (outcome.kind !== 'committed'
+          || !['assistant/message', 'assistant/attempt'].includes(outcome.eventType)
+          || !integer(outcome.seq) || outcome.seq > cursor || outcome.seq <= active.startedAfterSeq))) {
+          throw new Error('invalid assistant settlement')
+        }
+      } else throw new Error('unexpected assistant frame')
+    }
+    revision = next.revision
+    const normalized = { ...next, turn: active.turn, step: active.step }
+    if (next.type === 'end') active = undefined
+    return { type: 'assistant-stream', frame: normalized }
+  }
+}
+
+function delay(ms, signal) {
+  return new Promise(resolve => {
+    if (signal.aborted) return resolve()
+    const finish = () => {
+      clearTimeout(timer)
+      signal.removeEventListener('abort', finish)
+      resolve()
+    }
+    const timer = setTimeout(finish, ms)
+    signal.addEventListener('abort', finish, { once: true })
+  })
+}
+
+// One follow per opted-in connection. Each opening owns a new stream identity
+// and atomic snapshot, including a reconnecting Agent's active attempt.
+export function createSessionFollower(api, { onFrame, onError, retryMs = 1000 }) {
+  let current
+  const stop = () => {
+    const previous = current
+    current = undefined
+    previous?.abort.abort()
+  }
+  const start = (targetValue, subscriptionId, afterSeq) => {
+    stop()
+    const target = typeof targetValue === 'string' ? { sessionId: targetValue } : targetValue
+    const sessionId = target?.sessionId
+    if (typeof sessionId !== 'string' || !sessionId) throw new Error('session follower requires a sessionId')
+    const state = { abort: new AbortController() }
+    current = state
+    const task = (async () => {
+      let failures = 0
+      while (current === state && !state.abort.signal.aborted) {
+        const attemptAbort = new AbortController()
+        const signal = AbortSignal.any([state.abort.signal, attemptAbort.signal])
+        const streamId = crypto.randomUUID()
+        const context = { ...target, sessionId, subscriptionId, streamId,
+          ...(Number.isSafeInteger(afterSeq) && afterSeq >= 0 ? { afterSeq } : {}) }
+        const decode = createFollowDecoder(sessionId)
+        let iterator
+        let permanent = false
+        try {
+          const stream = await api.openSessionStream(target.parentSessionId ? target : sessionId, signal)
+          iterator = stream[Symbol.asyncIterator]()
+          while (current === state && !signal.aborted) {
+            const item = await iterator.next()
+            if (current !== state || signal.aborted) break
+            if (item.done) throw new Error('session follow ended')
+            const decoded = decode(item.value)
+            onFrame(decoded, context)
+          }
+        } catch (error) {
+          if (current !== state || signal.aborted) break
+          permanent = ['unsupported-session-format', 'session/not-found', 'gateway/bad-request'].includes(error.code)
+            || (error.code === 'SESSION_QUERY_PERSISTENCE_FAILED'
+              && /refuses this format .*Session/.test(error.message || ''))
+          onError(error, { ...context, retrying: !permanent })
+        } finally {
+          // Abort before return: the producer may be waiting for another event.
+          attemptAbort.abort()
+          try { await iterator?.return?.() } catch { /* The opening failure was already reported. */ }
+        }
+        if (permanent) break
+        await delay(Math.min(retryMs * 2 ** Math.min(failures++, 5), 30_000), state.abort.signal)
+      }
+    })()
+    return task
+  }
+  return { start, stop }
+}

package/lib/session-resume-bridge.mjs

@@ -0,0 +1,86 @@
+const DEFAULT_LIMITS = Object.freeze({
+  maxSessions: 32,
+  maxEventsPerSession: 2048,
+  maxBytesPerSession: 512 * 1024,
+  maxReplayEvents: 256,
+  maxReplayBytes: 256 * 1024,
+  maxAgeMs: 60 * 60 * 1000,
+})
+
+function byteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8')
+}
+
+// Keep only bounded wire-safe events. Recovery succeeds only when the entire
+// sequence interval is present; otherwise callers must trust a fresh snapshot.
+export function createSessionReplay(options = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...options }
+  const sessions = new Map()
+
+  function prune(now = Date.now()) {
+    for (const [sessionId, entry] of sessions) {
+      if (now - entry.touchedAt > limits.maxAgeMs) sessions.delete(sessionId)
+    }
+    while (sessions.size > limits.maxSessions) sessions.delete(sessions.keys().next().value)
+  }
+
+  function append(sessionId, frame) {
+    if (typeof sessionId !== 'string' || !sessionId || !Number.isSafeInteger(frame?.seq) || frame.seq < 0) return false
+    const now = Date.now()
+    prune(now)
+    let entry = sessions.get(sessionId)
+    if (!entry) entry = { events: [], bytes: 0, touchedAt: now }
+    const copy = { ...frame }
+    const bytes = byteLength(copy)
+    if (bytes > limits.maxBytesPerSession) return false
+    const last = entry.events[entry.events.length - 1]
+    if (!last || frame.seq > last.seq) {
+      entry.events.push({ seq: frame.seq, frame: copy, bytes })
+    } else {
+      const existing = entry.events.findIndex(item => item.seq === frame.seq)
+      if (existing >= 0) {
+        entry.bytes -= entry.events[existing].bytes
+        entry.events.splice(existing, 1)
+      }
+      let low = 0, high = entry.events.length
+      while (low < high) {
+        const middle = (low + high) >> 1
+        if (entry.events[middle].seq < frame.seq) low = middle + 1
+        else high = middle
+      }
+      entry.events.splice(low, 0, { seq: frame.seq, frame: copy, bytes })
+    }
+    entry.bytes += bytes
+    entry.touchedAt = now
+    while (entry.events.length > limits.maxEventsPerSession || entry.bytes > limits.maxBytesPerSession) {
+      const removed = entry.events.shift()
+      entry.bytes -= removed.bytes
+    }
+    sessions.delete(sessionId)
+    sessions.set(sessionId, entry)
+    prune(now)
+    return true
+  }
+
+  function recover(sessionId, afterSeq, throughSeq) {
+    const invalid = { status: 'snapshot', events: [] }
+    if (!Number.isSafeInteger(afterSeq) || afterSeq < 0 || !Number.isSafeInteger(throughSeq) || throughSeq < afterSeq) return invalid
+    if (afterSeq === throughSeq) return { status: 'replayed', events: [], fromSeq: afterSeq, toSeq: throughSeq }
+    if (throughSeq - afterSeq > limits.maxReplayEvents) return invalid
+    prune()
+    const entry = sessions.get(sessionId)
+    if (!entry) return invalid
+    const picked = entry.events.filter(item => item.seq > afterSeq && item.seq <= throughSeq)
+    if (picked.length !== throughSeq - afterSeq) return invalid
+    for (let i = 0; i < picked.length; i += 1) {
+      if (picked[i].seq !== afterSeq + i + 1) return invalid
+    }
+    const events = picked.map(item => item.frame)
+    if (byteLength(events) > limits.maxReplayBytes) return invalid
+    entry.touchedAt = Date.now()
+    return { status: 'replayed', events, fromSeq: afterSeq, toSeq: throughSeq }
+  }
+
+  return { append, recover }
+}
+

package/lib/session-target.mjs

@@ -0,0 +1,29 @@
+// 移动端保留 sessionId 为当前视图 ID，父子关系只作为显式路由地址。
+export function parseSessionTarget(msg, { optional = false } = {}) {
+  const fail = message => ({ error: { kind: 'error', code: 'bad-request', requestType: msg.type, message,
+    ...(typeof msg.requestId === 'string' ? { requestId: msg.requestId } : {}) } })
+  const sessionId = typeof msg.sessionId === 'string' ? msg.sessionId.trim() : ''
+  const hasChildAddress = msg.parentSessionId !== undefined || msg.subagentMode !== undefined
+  if (!sessionId && (!optional || hasChildAddress)) return fail('sessionId must be a non-empty string')
+  if (!hasChildAddress) return { value: sessionId ? { sessionId } : {} }
+  const parentSessionId = typeof msg.parentSessionId === 'string' ? msg.parentSessionId.trim() : ''
+  if (!parentSessionId || parentSessionId === sessionId) return fail('parentSessionId must identify a different direct parent')
+  if (!['continuable', 'one-shot', 'unknown'].includes(msg.subagentMode)) {
+    return fail('subagentMode must be continuable, one-shot, or unknown')
+  }
+  return { value: { sessionId, parentSessionId, subagentMode: msg.subagentMode } }
+}
+
+export function sessionAddress(target) {
+  return target.parentSessionId === undefined
+    ? { kind: 'session', sessionId: target.sessionId }
+    : { kind: 'subagent', parentSessionId: target.parentSessionId,
+      childSessionId: target.sessionId, mode: target.subagentMode }
+}
+
+export const TEAM_PROJECTION_KINDS = {
+  agentTeam: 'agent-team-updated',
+  subagentCatalog: 'subagents-updated',
+  subagent: 'subagent-identity-updated',
+  subagentTiming: 'subagent-timing-updated',
+}