dsh-bailinghub 0.2.0 → 0.4.0

package/lib/session-scope-store.js

@@ -0,0 +1,265 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+
+const SCHEMA = 'bailing.agent-session-scope.v1'
+const MAX_BYTES = 256 * 1024
+const LOCK_TIMEOUT_MS = 1_000
+const SECRET_KEYS = new Set(['token', 'accesstoken', 'refreshtoken', 'password', 'clientsecret', 'authorization', 'credential', 'credentials'])
+
+function storeError(code = 'SCOPE_STORE_UNAVAILABLE') {
+  const error = new Error(code === 'SCOPE_STORE_CONFLICT'
+    ? 'The session scope changed or is being saved. Read it again before retrying.'
+    : 'The session scope store is unavailable. The scope was not safely confirmed.')
+  error.code = code
+  return error
+}
+
+function safeError(error) {
+  return ['SCOPE_STORE_CONFLICT', 'SCOPE_STORE_UNAVAILABLE'].includes(error?.code)
+    ? error : storeError()
+}
+
+function sessionKey(sessionId) {
+  if (typeof sessionId !== 'string' || !sessionId.length || sessionId.length > 4_096) throw storeError()
+  return createHash('sha256').update(sessionId).digest('hex')
+}
+
+// The coordinator owns the scope schema. This boundary additionally refuses
+// non-JSON values and credential fields so stores cannot become credential caches.
+function snapshotJson(value, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)) return value
+  if (!value || typeof value !== 'object' || seen.has(value)) throw storeError()
+  const array = Array.isArray(value)
+  if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw storeError()
+  seen.add(value)
+  try {
+    const entries = Reflect.ownKeys(value).filter((key) => !array || key !== 'length')
+    if (array && (entries.length !== value.length || entries.some((key, index) => key !== String(index)))) throw storeError()
+    const copy = array ? [] : {}
+    for (const key of entries) {
+      const property = Object.getOwnPropertyDescriptor(value, key)
+      if (typeof key !== 'string' || !property.enumerable || !Object.hasOwn(property, 'value') ||
+        SECRET_KEYS.has(key.replace(/[_-]/gu, '').toLowerCase()) || ['__proto__', 'constructor', 'prototype'].includes(key)) throw storeError()
+      copy[key] = snapshotJson(property.value, seen)
+    }
+    return copy
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function snapshotRecord(sessionId, record) {
+  const copy = snapshotJson(record)
+  if (!copy || Array.isArray(copy) || copy.schema !== SCHEMA || copy.sessionId !== sessionId ||
+    !Number.isSafeInteger(copy.revision) || copy.revision < 1) throw storeError()
+  if (Buffer.byteLength(JSON.stringify(copy)) > MAX_BYTES) throw storeError()
+  return copy
+}
+
+function nextRecord(sessionId, record, expectedRevision) {
+  sessionKey(sessionId)
+  if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)) throw storeError()
+  const copy = snapshotRecord(sessionId, record)
+  if (copy.revision !== (expectedRevision ?? 0) + 1) throw storeError()
+  return copy
+}
+
+function assertRevision(current, expectedRevision) {
+  if ((current?.revision ?? null) !== expectedRevision) throw storeError('SCOPE_STORE_CONFLICT')
+}
+
+function assertOwned(stat, kind) {
+  if (!(kind === 'directory' ? stat.isDirectory() : stat.isFile()) ||
+    (kind === 'file' && stat.nlink !== 1) ||
+    (typeof process.getuid === 'function' && stat.uid !== process.getuid()) ||
+    (process.platform !== 'win32' && (stat.mode & 0o777) !== (kind === 'directory' ? 0o700 : 0o600))) throw storeError()
+}
+
+function sameFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino
+}
+
+function defaultDirectory() {
+  const configured = process.env.DSH_HOME
+  const base = typeof configured === 'string' && configured.trim() ? configured : join(homedir(), '.dsh')
+  const expanded = base === '~' ? homedir() : /^~[/\\]/u.test(base) ? join(homedir(), base.slice(2)) : base
+  return join(resolve(expanded), 'plugins', 'dsh-bailinghub', 'session-scopes')
+}
+
+async function ensureDirectory(directory, create) {
+  if (create) await mkdir(directory, { recursive: true, mode: 0o700 })
+  let stat
+  try {
+    stat = await lstat(directory)
+  } catch (error) {
+    if (!create && error.code === 'ENOENT') return false
+    throw error
+  }
+  assertOwned(stat, 'directory')
+  return true
+}
+
+async function readRecord(path, sessionId) {
+  let before
+  try {
+    before = await lstat(path)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  assertOwned(before, 'file')
+  if (before.size > MAX_BYTES) throw storeError()
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const opened = await file.stat()
+    assertOwned(opened, 'file')
+    if (!sameFile(before, opened) || opened.size > MAX_BYTES) throw storeError()
+    // Bound the read even if an abnormal writer grows the file after fstat.
+    const bytes = Buffer.alloc(MAX_BYTES + 1)
+    let length = 0
+    while (length < bytes.length) {
+      const result = await file.read(bytes, length, bytes.length - length, length)
+      if (!result.bytesRead) break
+      length += result.bytesRead
+    }
+    if (length > MAX_BYTES) throw storeError()
+    return snapshotRecord(sessionId, JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length))))
+  } finally {
+    await file.close()
+  }
+}
+
+async function acquireLock(path) {
+  const deadline = performance.now() + LOCK_TIMEOUT_MS
+  while (true) {
+    let file
+    let stat
+    try {
+      file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+      stat = await file.stat()
+      await file.chmod(0o600)
+      assertOwned(await file.stat(), 'file')
+      return { file, stat }
+    } catch (error) {
+      if (file) {
+        if (stat) await releaseLock(path, { file, stat })
+        else await file.close().catch(() => {})
+      }
+      if (error.code !== 'EEXIST') throw error
+      try {
+        assertOwned(await lstat(path), 'file')
+      } catch (inspectionError) {
+        if (inspectionError.code === 'ENOENT') continue
+        throw inspectionError
+      }
+      if (performance.now() >= deadline) throw storeError('SCOPE_STORE_CONFLICT')
+      // Never infer staleness or remove another process's lock.
+      await delay(20)
+    }
+  }
+}
+
+async function releaseLock(path, lock) {
+  try {
+    const current = await lstat(path)
+    if (!sameFile(current, lock.stat) || !current.isFile()) throw storeError()
+    await unlink(path)
+  } finally {
+    await lock.file.close()
+  }
+}
+
+async function syncDirectory(directory) {
+  // Windows does not expose fsync on directory handles through Node.
+  if (process.platform === 'win32') return
+  const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
+  try {
+    assertOwned(await handle.stat(), 'directory')
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Durable non-secret scope sidecars. No user directory is touched until load/save. */
+export function createFileSessionScopeStore({ directory } = {}) {
+  if (directory !== undefined && (typeof directory !== 'string' || !directory.trim())) throw storeError()
+  const root = directory === undefined ? defaultDirectory() : resolve(directory)
+  return {
+    async load(sessionId) {
+      try {
+        const key = sessionKey(sessionId)
+        if (!await ensureDirectory(root, false)) return null
+        return await readRecord(join(root, `${key}.json`), sessionId)
+      } catch (error) {
+        throw safeError(error)
+      }
+    },
+    async save(sessionId, record, expectedRevision) {
+      let lock
+      let temporaryPath
+      const key = sessionKey(sessionId)
+      const path = join(root, `${key}.json`)
+      const lockPath = join(root, `${key}.lock`)
+      try {
+        const copy = nextRecord(sessionId, record, expectedRevision)
+        await ensureDirectory(root, true)
+        lock = await acquireLock(lockPath)
+        assertRevision(await readRecord(path, sessionId), expectedRevision)
+        temporaryPath = join(root, `.${key}.${randomUUID()}.tmp`)
+        const temporary = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+        try {
+          await temporary.chmod(0o600)
+          assertOwned(await temporary.stat(), 'file')
+          await temporary.writeFile(JSON.stringify(copy), 'utf8')
+          await temporary.sync()
+        } finally {
+          await temporary.close()
+        }
+        await rename(temporaryPath, path)
+        temporaryPath = undefined
+        await syncDirectory(root)
+        return snapshotRecord(sessionId, copy)
+      } catch (error) {
+        throw safeError(error)
+      } finally {
+        try {
+          if (temporaryPath) await unlink(temporaryPath).catch((error) => {
+            if (error.code !== 'ENOENT') throw storeError()
+          })
+        } finally {
+          if (lock) {
+            try {
+              await releaseLock(lockPath, lock)
+            } catch {
+              throw storeError()
+            }
+          }
+        }
+      }
+    },
+  }
+}
+
+/** Explicit in-memory adapter: CAS-compatible, but never survives process restart. */
+export function createMemorySessionScopeStore() {
+  const records = new Map()
+  return {
+    async load(sessionId) {
+      sessionKey(sessionId)
+      const record = records.get(sessionId)
+      return record ? snapshotRecord(sessionId, record) : null
+    },
+    async save(sessionId, record, expectedRevision) {
+      const copy = nextRecord(sessionId, record, expectedRevision)
+      assertRevision(records.get(sessionId), expectedRevision)
+      records.set(sessionId, copy)
+      return snapshotRecord(sessionId, copy)
+    },
+  }
+}

package/lib/session-scope.js

@@ -0,0 +1,319 @@
+import { createHash } from 'node:crypto'
+import { createFileSessionScopeStore } from './session-scope-store.js'
+
+const SCHEMA = 'bailing.agent-session-scope.v1'
+const KEY = /^conn_[0-9a-f]{32}$/
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const LOST_AUTHORIZATION_STATES = new Set(['logged_out', 'revoked', 'expired'])
+
+function definitiveAuthorizationFailure(error) {
+  return ['AUTHORIZATION_CHANGED', 'CROSS_SYSTEM_SCOPE_UNSUPPORTED'].includes(error?.code) ||
+    (error?.name === 'AgentAuthHttpError' && [401, 403].includes(error.statusCode))
+}
+
+export function scopeError(code = 'SESSION_SCOPE_UNAVAILABLE') {
+  const error = new Error(`BailingHub session scope is unavailable (${code}); retry original-scope validation when connectivity returns, or confirm scope before the first message`)
+  error.code = code
+  return error
+}
+
+/** Host-owned selection. Neither model arguments nor global defaults can grant scope. */
+export class SessionScopeCoordinator {
+  constructor({ store = createFileSessionScopeStore(), getTransport, normalizeConfig, sanitize }) {
+    if (typeof store?.load !== 'function' || typeof store?.save !== 'function') throw new TypeError('A session scope store with load/save is required')
+    this.store = store
+    this.getTransport = getTransport
+    this.normalizeConfig = normalizeConfig
+    this.sanitize = sanitize
+    this.entries = new Map()
+  }
+
+  entry(sessionId) {
+    if (typeof sessionId !== 'string' || !sessionId.trim() || sessionId.length > 512 || /[\u0000-\u001f\u007f]/.test(sessionId)) {
+      throw scopeError('INVALID_SESSION_ID')
+    }
+    if (!this.entries.has(sessionId)) this.entries.set(sessionId, { sessionId, record: null, loaded: false, claimed: false, blocked: false, retryRequired: false, pending: false, generation: 0 })
+    return this.entries.get(sessionId)
+  }
+
+  validate(record, sessionId) {
+    if (!record || record.schema !== SCHEMA || record.sessionId !== sessionId ||
+      !Number.isSafeInteger(record.revision) || record.revision < 1 ||
+      !['ready', 'needs_selection'].includes(record.state) || typeof record.locked !== 'boolean' ||
+      !Array.isArray(record.authorizations) || record.authorizations.length > 64 ||
+      Object.keys(record).some((key) => !['schema', 'sessionId', 'revision', 'state', 'locked', 'binding', 'authorizations'].includes(key))) throw scopeError('INVALID_SCOPE_SNAPSHOT')
+    const keys = new Set()
+    for (const item of record.authorizations) {
+      if (!KEY.test(item?.connectionKey ?? '') || keys.has(item.connectionKey) || !UUID.test(item.sessionId ?? '') ||
+        typeof item.label !== 'string' || item.label.length > 128 || item.workspace !== record.binding?.workspace ||
+        Object.keys(item).some((key) => !['connectionKey', 'sessionId', 'label', 'workspace'].includes(key))) throw scopeError('INVALID_SCOPE_SNAPSHOT')
+      keys.add(item.connectionKey)
+    }
+    if (record.authorizations.length) {
+      if (!record.binding || typeof record.binding !== 'object' || Array.isArray(record.binding) ||
+        Object.keys(record.binding).some((key) => !['hubUrl', 'clientAppId', 'workspace'].includes(key))) throw scopeError('INVALID_SCOPE_SNAPSHOT')
+      const binding = this.normalizeConfig(record.binding)
+      if (!binding.valid || binding.hubUrl !== record.binding.hubUrl || binding.clientAppId !== record.binding.clientAppId || binding.workspace !== record.binding.workspace || record.state !== 'ready') throw scopeError('INVALID_SCOPE_SNAPSHOT')
+    } else if (record.binding !== null) throw scopeError('INVALID_SCOPE_SNAPSHOT')
+    return structuredClone(record)
+  }
+
+  async load(entry) {
+    if (!entry.loaded) {
+      entry.loading ??= (async () => {
+        try {
+          const value = await this.store.load(entry.sessionId)
+          entry.record = value === null ? null : this.validate(value, entry.sessionId)
+          // An unlocked selection is only a draft. A failed replacement may
+          // have left its very first tombstone unwritten, so no stored draft
+          // can prove the user's latest intent after this runtime is rebuilt.
+          if (entry.record && !entry.record.locked) entry.blocked = true
+          // A restored business snapshot is not a current authorization proof.
+          // This in-memory fence never rewrites its identities or CAS revision.
+          entry.retryRequired = Boolean(entry.record?.authorizations.length)
+        } catch {
+          entry.blocked = true
+          entry.loadFailed = true
+        }
+        entry.loaded = true
+      })()
+      await entry.loading
+    }
+    return entry
+  }
+
+  view(entry) {
+    const record = entry.record
+    const blocked = entry.blocked || entry.retryRequired || this.isValidating(entry) || entry.pending || record?.state === 'needs_selection'
+    const state = blocked ? 'needs_selection' : record ? 'ready' : 'unselected'
+    return {
+      schema: SCHEMA, sessionId: entry.sessionId, revision: record?.revision ?? null,
+      state, locked: entry.claimed || record?.locked === true,
+      mode: blocked ? 'blocked' : record?.authorizations.length ? 'business' : 'chat',
+      authorizations: blocked ? [] : (record?.authorizations ?? []).map((item) => ({
+        authorizationRef: `auth_${createHash('sha256').update(`${entry.sessionId}\0${item.connectionKey}`).digest('hex').slice(0, 24)}`,
+        connectionKey: item.connectionKey, label: item.label, workspace: item.workspace,
+      })),
+    }
+  }
+
+  async get(sessionId) {
+    const entry = await this.load(this.entry(sessionId))
+    if (entry.record && !entry.pending && !entry.blocked) {
+      await this.checkStored(entry)
+      if (!entry.blocked && entry.record.state === 'ready') {
+        await this.revalidate(entry)
+      }
+    }
+    return this.view(entry)
+  }
+
+  async write(entry, values) {
+    const expected = entry.record?.revision ?? null
+    const record = this.validate({ schema: SCHEMA, sessionId: entry.sessionId, revision: (expected ?? 0) + 1, ...values }, entry.sessionId)
+    await this.store.save(entry.sessionId, structuredClone(record), expected)
+    entry.record = record
+  }
+
+  async checkStored(entry) {
+    const original = entry.record
+    const generation = entry.generation
+    try {
+      const record = this.validate(await this.store.load(entry.sessionId), entry.sessionId)
+      if (JSON.stringify(record) !== JSON.stringify(original)) throw scopeError('SESSION_SCOPE_CONFLICT')
+    } catch {
+      if (entry.record === original && entry.generation === generation) entry.blocked = true
+    }
+  }
+
+  async revalidate(entry) {
+    const original = entry.record
+    const generation = entry.generation
+    if (!original || entry.blocked || entry.pending) return
+    if (this.isValidating(entry)) return entry.validation.promise
+    const validation = { record: original, generation }
+    entry.validation = validation
+    entry.retryRequired = Boolean(original.authorizations.length)
+    const current = () => entry.record === original && entry.generation === generation && !entry.blocked && !entry.pending
+    validation.promise = (async () => {
+      try {
+        await this.resolve(original.authorizations.map((item) => item.connectionKey), original)
+        if (!current()) return
+        // A network wait must not hide a concurrent durable scope change.
+        await this.checkStored(entry)
+        if (current()) entry.retryRequired = false
+      } catch (error) {
+        if (current()) this.invalidate(entry.sessionId, error)
+      } finally {
+        if (entry.validation === validation) entry.validation = undefined
+      }
+    })()
+    return validation.promise
+  }
+
+  isValidating(entry) {
+    return Boolean(entry.validation && entry.validation.record === entry.record && entry.validation.generation === entry.generation)
+  }
+
+  validateStatus(status, { connectionKey, workspace, sessionId }) {
+    // An incomplete response proves neither identity nor revocation. A retry
+    // may proceed only after the exact original identity is actually verified.
+    if (!status || !KEY.test(status.connectionKey ?? '') || typeof status.workspace !== 'string' || !status.workspace) throw scopeError('AUTHORIZATION_UNVERIFIED')
+    if (!LOST_AUTHORIZATION_STATES.has(status.state) &&
+      (status.state !== 'authorized' || !UUID.test(status.sessionId ?? ''))) throw scopeError('AUTHORIZATION_UNVERIFIED')
+    if (status.connectionKey !== connectionKey || status.workspace !== workspace || LOST_AUTHORIZATION_STATES.has(status.state)) throw scopeError('AUTHORIZATION_CHANGED')
+    if (sessionId && sessionId !== status.sessionId) throw scopeError('AUTHORIZATION_CHANGED')
+  }
+
+  async resolve(connectionKeys, original) {
+    if (!connectionKeys.length) return { binding: null, authorizations: [] }
+    const transport = await this.getTransport()
+    const registry = await transport.connectionsList()
+    if (!Array.isArray(registry?.connections) || registry.connections.some((item) => !KEY.test(item?.connectionKey ?? ''))) throw scopeError('AUTHORIZATION_UNVERIFIED')
+    let binding
+    const authorizations = []
+    for (const connectionKey of connectionKeys) {
+      const matches = registry.connections.filter((item) => item?.connectionKey === connectionKey)
+      if (!matches.length) throw scopeError('AUTHORIZATION_CHANGED')
+      if (matches.length !== 1) throw scopeError('AUTHORIZATION_UNVERIFIED')
+      if (LOST_AUTHORIZATION_STATES.has(matches[0].state)) throw scopeError('AUTHORIZATION_CHANGED')
+      if (matches[0].state !== 'authorized') throw scopeError('AUTHORIZATION_UNVERIFIED')
+      const selected = this.normalizeConfig(matches[0])
+      if (!selected.valid) throw scopeError('AUTHORIZATION_UNVERIFIED')
+      const candidate = { hubUrl: selected.hubUrl, clientAppId: selected.clientAppId, workspace: selected.workspace }
+      binding ??= candidate
+      if (JSON.stringify(binding) !== JSON.stringify(candidate)) throw scopeError('CROSS_SYSTEM_SCOPE_UNSUPPORTED')
+      if (original && JSON.stringify(original.binding) !== JSON.stringify(candidate)) throw scopeError('AUTHORIZATION_CHANGED')
+      // Only selected keys are probed. Never resolve the SDK's current connection.
+      const status = await transport.status({ connectionKey })
+      const saved = original?.authorizations.find((item) => item.connectionKey === connectionKey)
+      this.validateStatus(status, { connectionKey, workspace: binding.workspace, sessionId: saved?.sessionId })
+      const label = String(this.sanitize(matches[0].connectionName ?? 'Authorized account'))
+        .replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 128).trim() || 'Authorized account'
+      authorizations.push({ connectionKey, sessionId: status.sessionId, label: saved?.label ?? label, workspace: binding.workspace })
+    }
+    return { binding, authorizations }
+  }
+
+  async set(sessionId, request) {
+    const entry = this.entry(sessionId)
+    if (entry.claimed || entry.record?.locked) throw scopeError('SESSION_SCOPE_LOCKED')
+    // Host UI state may be mutated immediately after calling this API. Capture
+    // the requested selection before the first storage/network await.
+    try { request = structuredClone(request) } catch { request = null }
+    if (entry.pending) {
+      entry.blocked = true
+      entry.generation += 1
+      throw scopeError('SESSION_SCOPE_CONFLICT')
+    }
+    // Close the gate synchronously, before storage or authorization validation.
+    entry.pending = true
+    const generation = ++entry.generation
+    try {
+      await this.load(entry)
+      if (entry.claimed || entry.record?.locked) throw scopeError('SESSION_SCOPE_LOCKED')
+      const previousRevision = entry.record?.revision ?? null
+      const failedLoad = entry.loadFailed
+      entry.blocked = true
+      // Invalidate the previous selection durably when storage permits it.
+      // load() also requires confirmation of every unlocked stored draft,
+      // covering failures before this first write can reach storage.
+      await this.write(entry, { state: 'needs_selection', locked: false, binding: null, authorizations: [] })
+      if (failedLoad) throw scopeError('SESSION_SCOPE_UNAVAILABLE')
+      if (!request || typeof request !== 'object' || Array.isArray(request) ||
+        Object.keys(request).some((key) => !['connectionKeys', 'expectedRevision'].includes(key)) ||
+        !Array.isArray(request.connectionKeys) || request.connectionKeys.length > 64 ||
+        request.connectionKeys.some((key) => typeof key !== 'string' || !KEY.test(key)) ||
+        new Set(request.connectionKeys).size !== request.connectionKeys.length) throw scopeError('INVALID_SCOPE_SELECTION')
+      if (Object.hasOwn(request, 'expectedRevision') && request.expectedRevision !== previousRevision) throw scopeError('SESSION_SCOPE_CONFLICT')
+      const selected = await this.resolve([...request.connectionKeys].sort())
+      if (entry.claimed || generation !== entry.generation) throw scopeError('SESSION_SCOPE_CONFLICT')
+      await this.write(entry, { state: 'ready', locked: false, ...selected })
+      if (entry.claimed || generation !== entry.generation) {
+        await this.write(entry, { state: 'needs_selection', locked: entry.claimed, binding: null, authorizations: [] })
+        throw scopeError('SESSION_SCOPE_CONFLICT')
+      }
+      entry.blocked = false
+      entry.retryRequired = false
+    } catch (error) {
+      if (error?.code !== 'SESSION_SCOPE_LOCKED') entry.blocked = true
+      throw scopeError(error?.code === 'SESSION_SCOPE_LOCKED' ? error.code : 'SESSION_SCOPE_SELECTION_FAILED')
+    } finally {
+      entry.pending = false
+    }
+    return this.view(entry)
+  }
+
+  markStarted(sessionId) {
+    const entry = this.entry(sessionId)
+    entry.claimed = true
+    if (entry.pending) { entry.blocked = true; entry.generation += 1 }
+  }
+
+  async restore(sessionId, { knownDraft = false } = {}) {
+    const entry = await this.load(this.entry(sessionId))
+    if (entry.pending) { entry.blocked = true; entry.generation += 1 }
+    if (!entry.record) {
+      entry.blocked = true
+      // Missing scope is not evidence of a user message. Only the trusted host
+      // history can distinguish a never-started draft from unknown old history.
+      if (!knownDraft) entry.claimed = true
+    } else if (!entry.blocked && entry.record.state === 'ready') {
+      await this.checkStored(entry)
+      if (!entry.blocked) await this.revalidate(entry)
+    }
+    return this.view(entry)
+  }
+
+  async begin(sessionId, restored = false) {
+    const entry = this.entry(sessionId)
+    entry.beginPromise ??= this.beginOnce(sessionId, restored).finally(() => { entry.beginPromise = undefined })
+    return entry.beginPromise
+  }
+
+  async beginOnce(sessionId, restored = false) {
+    const entry = await this.load(this.entry(sessionId))
+    // Old history must never acquire a fresh selection before it is reopened.
+    if (restored && !entry.record?.locked) entry.blocked = true
+    if (entry.pending || entry.blocked || entry.record?.state === 'needs_selection') return this.view(entry)
+    if (entry.record) await this.checkStored(entry)
+    if (entry.blocked) return this.view(entry)
+    try {
+      if (!entry.record || !entry.record.locked) {
+        await this.write(entry, { state: 'ready', locked: true, binding: entry.record?.binding ?? null, authorizations: entry.record?.authorizations ?? [] })
+      }
+    } catch { entry.blocked = true }
+    // Storage failures remain terminal. Unverified authorizations instead keep
+    // a closed, retryable gate before any selected system receives user input.
+    if (!entry.blocked) await this.revalidate(entry)
+    return this.view(entry)
+  }
+
+  snapshot(sessionId) { return structuredClone(this.entry(sessionId).record) }
+
+  async assertUsable(sessionId) {
+    const entry = await this.load(this.entry(sessionId))
+    while (this.isValidating(entry)) await entry.validation.promise
+    this.assertCurrent(sessionId)
+    await this.checkStored(entry)
+    while (this.isValidating(entry)) await entry.validation.promise
+    this.assertCurrent(sessionId)
+  }
+
+  // Last synchronous dispatch gate: a scope invalidated while an SDK/status
+  // promise was pending cannot send input or a write after that promise resolves.
+  assertCurrent(sessionId) {
+    const entry = this.entry(sessionId)
+    if (entry.pending || entry.blocked || entry.retryRequired || this.isValidating(entry) || entry.record?.state !== 'ready' || !entry.record.locked || !entry.record.authorizations.length) throw scopeError()
+  }
+
+  // Only authorization probes pass an error here. Unknown transport failures
+  // are not revocations; they close dispatch until a fresh whole-scope proof.
+  // A newer invalidation always supersedes any in-flight validation success.
+  invalidate(sessionId, error) {
+    const entry = this.entry(sessionId)
+    entry.generation += 1
+    if (!error || definitiveAuthorizationFailure(error)) entry.blocked = true
+    else entry.retryRequired = true
+  }
+}

package/lib/transport.js

@@ -1,6 +1,10 @@
 const DEFAULT_SDK_MODULE = 'bailinghub-mcp-server/sdk'
 
 const REQUIRED_METHODS = [
+  'connectionsList',
+  'connectionsAdd',
+  'connectionsUse',
+  'connectionsRemove',
   'login',
   'status',
   'logout',
@@ -45,7 +49,7 @@ function resolveSdkFactory(module) {
  * Lazily resolves the generic BailingHub Agent Client SDK. The SDK, rather than
  * this DSH adapter, owns browser authorization, token storage, refresh, and the
  * HTTP endpoint mapping. A missing SDK therefore degrades only the first use;
- * it never prevents Cordis from loading the plugin candidate.
+ * it never prevents Cordis from loading the plugin.
  */
 export function createLazySdkTransport(config, options = {}) {
   const importModule = options.importModule ?? ((specifier) => import(specifier))
@@ -68,12 +72,22 @@ export function createLazySdkTransport(config, options = {}) {
     return clientPromise
   }
 
-  return Object.fromEntries(
+  const transport = Object.fromEntries(
     REQUIRED_METHODS.map((method) => [
       method,
       async (...args) => (await client())[method](...args),
     ]),
   )
+  // Archive support is optional: an older SDK must retain all business methods.
+  transport.supportsConversationArchive = async () => typeof (await client()).syncConversationArchive === 'function'
+  transport.syncConversationArchive = async (...args) => {
+    const sdk = await client()
+    if (typeof sdk.syncConversationArchive !== 'function') {
+      throw Object.assign(new Error('The installed SDK does not support conversation archives'), { code: 'ARCHIVE_UNSUPPORTED' })
+    }
+    return sdk.syncConversationArchive(...args)
+  }
+  return transport
 }
 
 export function createTransportProvider(config, options = {}) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-bailinghub",
-  "version": "0.2.0",
-  "description": "Native DeepSeek Harness adapter for the BailingHub Agent Client Core.",
+  "version": "0.4.0",
+  "description": "Let a local DeepSeek Harness Agent use BailingHub to query data, update records, and run permitted actions in your online store, SaaS, or other admin system.",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",
@@ -39,6 +39,8 @@
     "cordis.agent-client.patch.yml",
     "cordis.patch.yml",
     "docs/AGENT_CLIENT_CONTRACT.md",
+    "docs/GETTING_STARTED.md",
+    "docs/GETTING_STARTED.zh-CN.md",
     "docs/MIGRATION_VNEXT.md",
     "docs/README.zh-CN.md",
     "SECURITY.md",
@@ -52,14 +54,22 @@
   },
   "scripts": {
     "check:project": "node scripts/check-project.mjs",
+    "check:marketplace": "node scripts/check-marketplace.mjs",
     "check:release-tag": "node scripts/check-release-tag.mjs",
     "test": "node --test tests/*.test.mjs",
-    "verify": "npm run check:project && npm test",
+    "verify": "npm run check:project && npm run check:marketplace && npm test",
     "prepack": "npm run verify"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "bailinghub-mcp-server": "0.2.0"
+    "bailinghub-mcp-server": "0.4.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-commands": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2"
   },
   "dsh": {
     "bundle": {