dsh-bailinghub 0.6.0 → 0.7.0

package/lib/session-usage-store.js

@@ -0,0 +1,280 @@
+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'
+import { isProxy } from 'node:util/types'
+
+const SCHEMAS = new Set(['bailing.usage-session.v1'])
+const RECORD_KEYS = new Set(['schema', 'sessionId', 'revision', 'entries'])
+const MAX_BYTES = 8 * 1024 * 1024
+const LOCK_TIMEOUT_MS = 1_000
+const PRIVATE_KEYS = new Set([
+  'token', 'tokens', 'accesstoken', 'refreshtoken', 'password', 'clientsecret',
+  'authorization', 'credential', 'credentials', 'secret', 'apikey',
+  'args', 'arguments', 'content', 'contents', 'body', 'prompt', 'messages',
+])
+const MAX_DEPTH = 128
+
+function storeError(code = 'USAGE_STORE_UNAVAILABLE') {
+  const error = new Error(code === 'USAGE_STORE_CONFLICT'
+    ? 'The usage binding changed or is being saved. Read it again before retrying.'
+    : 'The usage binding store is unavailable. Recovery metadata was not safely confirmed.')
+  error.code = code
+  return error
+}
+
+function safeError(error) {
+  return ['USAGE_STORE_CONFLICT', 'USAGE_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 validates each original execution binding. This boundary accepts
+// only JSON metadata and refuses credential or business payload fields. Tool names
+// are values, so a tool named "content" or "arguments" remains valid metadata.
+function snapshotJson(value, seen = new Set(), depth = 0) {
+  if (depth > MAX_DEPTH) throw storeError()
+  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) || isProxy(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') ||
+        PRIVATE_KEYS.has(key.replace(/[_-]/gu, '').toLowerCase()) || ['__proto__', 'constructor', 'prototype'].includes(key)) throw storeError()
+      copy[key] = snapshotJson(property.value, seen, depth + 1)
+    }
+    return copy
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function snapshotRecord(sessionId, record) {
+  const copy = snapshotJson(record)
+  if (!copy || Array.isArray(copy) || !SCHEMAS.has(copy.schema) || copy.sessionId !== sessionId ||
+    !Number.isSafeInteger(copy.revision) || copy.revision < 1 || !Array.isArray(copy.entries) ||
+    Object.keys(copy).some((key) => !RECORD_KEYS.has(key))) throw storeError()
+  const request = copy.entries[0]?.request
+  if (copy.entries.length !== 1 || !request || request.metadata?.schema !== 'bailing.model-request.v1'
+    || typeof request.metadata.operationId !== 'string' || !copy.sessionId.startsWith('model:')
+    || !['prepared', 'completed', 'cancelled', 'rejected', 'unknown', 'closed_unresolved'].includes(request.state)
+    || Object.keys(copy.entries[0]).some(key => key !== 'request')) 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('USAGE_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-usage')
+}
+
+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('USAGE_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 model request metadata only. No user directory is touched until load/save. */
+export function createFileSessionUsageStore({ 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 createMemorySessionUsageStore() {
+  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/usage-llm-stream.js

@@ -0,0 +1,157 @@
+import { usageNativeModelChunks } from './usage-provider-stream.js'
+
+const fail = (code = 'USAGE_STREAM_INCOMPLETE') => Object.assign(new Error(`Model gateway response is unavailable (${code}).`), {
+  code, feedback: { schema: 'bailing.usage-feedback.v1', code, dispatch: 'unknown', next_action: 'inspect_original', retryable: true },
+})
+const object = value => value && typeof value === 'object' && !Array.isArray(value)
+
+/** Convert gateway events to the native DSH model stream. No planning or tool execution lives here.
+ * Preview text is incremental. Tool blocks and finish are exposed only after an active durable receipt.
+ */
+async function* legacyChunks(events) {
+  const textBlocks = new Map(); let index = 0, ended = false
+  function block(type) {
+    let value = textBlocks.get(type)
+    if (!value) { value = { index: index++, text: '', started: false }; textBlocks.set(type, value) }
+    return value
+  }
+  for await (const event of events) {
+    if (ended) throw fail()
+    if (event.type === 'delta') {
+      for (const [key, type] of [['reasoning_content', 'reasoning'], ['content', 'text']]) {
+        const value = event.delta?.[key]
+        if (value == null || value === '') continue
+        if (typeof value !== 'string') throw fail()
+        const part = block(type)
+        if (!part.started) { part.started = true; yield { type: 'block-start', index: part.index, blockType: type } }
+        part.text += value
+        yield { type: type === 'text' ? 'text-delta' : 'reasoning-delta', index: part.index, text: value }
+      }
+      continue
+    }
+    if (event.type !== 'operation') continue
+    const receipt = event.operation
+    if (receipt?.result_state === 'failed' && receipt.delivery_state !== 'cancelled_late_result') throw Object.assign(new Error(receipt.error?.message ?? 'Model service rejected the request.'), {code: 'USAGE_PROVIDER_REJECTED', operationId: receipt.operation_id, feedback: {schema:'bailing.usage-feedback.v1',code:'USAGE_PROVIDER_REJECTED',dispatch:'rejected',next_action:'contact_operator',retryable:false}})
+    if (receipt?.delivery_state !== 'response_ready' || receipt.host_turn_active !== true) throw fail(
+      receipt?.delivery_state === 'cancelled_late_result' ? 'USAGE_CANCELLED' : receipt?.response_expired === true ? 'USAGE_ORIGINAL_RESULT_EXPIRED' : 'USAGE_ORIGINAL_PENDING')
+    const response = receipt.response, choice = response?.choices?.[0], message = choice?.message
+    if (!Array.isArray(response?.choices) || !object(message)
+      || !['stop', 'length', 'tool_calls'].includes(choice.finish_reason)) throw fail('USAGE_RESPONSE_INVALID')
+    const calls = message.tool_calls ?? [], ids = new Set()
+    if (!Array.isArray(calls)) throw fail('USAGE_RESPONSE_INVALID')
+    for (const call of calls) {
+      if (call?.type !== 'function' || typeof call.id !== 'string' || !call.id || ids.has(call.id)
+        || typeof call.function?.name !== 'string' || !call.function.name || typeof call.function.arguments !== 'string') throw fail('USAGE_RESPONSE_INVALID')
+      ids.add(call.id)
+    }
+    // Validate the whole final response against displayed previews before completing any native block.
+    for (const [key, type] of [['reasoning_content', 'reasoning'], ['content', 'text']]) {
+      const value = message[key] ?? ''
+      if (typeof value !== 'string' || !value.startsWith(textBlocks.get(type)?.text ?? '')) throw fail('USAGE_RESPONSE_INVALID')
+    }
+    for (const [key, type] of [['reasoning_content', 'reasoning'], ['content', 'text']]) {
+      const value = message[key] ?? ''
+      if (!value && !textBlocks.has(type)) continue
+      const part = block(type)
+      if (!part.started) yield { type: 'block-start', index: part.index, blockType: type }
+      if (value.length > part.text.length) yield { type: type === 'text' ? 'text-delta' : 'reasoning-delta', index: part.index, text: value.slice(part.text.length) }
+      yield { type: 'block-end', index: part.index, block: { type, text: value } }
+    }
+    for (const call of calls) {
+      const i = index++, value = { type: 'tool-call', id: call.id, name: call.function.name, arguments: call.function.arguments }
+      yield { type: 'block-start', index: i, blockType: 'tool-call' }
+      yield { type: 'tool-call-delta', index: i, id: value.id, name: value.name, argumentsDelta: value.arguments }
+      yield { type: 'block-end', index: i, block: value }
+    }
+    const usage = response.usage, count = value => Number.isSafeInteger(value) && value >= 0
+    if (count(usage?.prompt_tokens) && count(usage?.completion_tokens)) {
+      const cached = usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens ?? 0
+      if (count(cached) && cached <= usage.prompt_tokens) yield { type: 'usage', usage: {
+        inputTokens: usage.prompt_tokens - cached, outputTokens: usage.completion_tokens, ...(cached ? { cacheReadTokens: cached } : {}),
+      } }
+    }
+    ended = true
+    yield { type: 'finish', reason: { kind: choice.finish_reason === 'length' ? 'max-tokens' : choice.finish_reason === 'tool_calls' ? 'tool-calls' : 'stop' } }
+  }
+  if (!ended) throw fail()
+}
+
+
+/** OpenAI-compatible parsing is local. Provider-specific adapters can use usageNativeModelChunks. */
+async function* compatibleChunks(response) {
+  const localError = () => Object.assign(new Error('The provider response could not be parsed by the local model adapter.'), {
+    code: 'MODEL_PROVIDER_RESPONSE_INVALID', status: response.status,
+  })
+  if (!response.ok) {
+    await response.body?.cancel()
+    throw Object.assign(new Error(`Model provider returned HTTP ${response.status}.`), { code: 'MODEL_PROVIDER_HTTP_ERROR', status: response.status })
+  }
+  async function* parsed() {
+    if (!(response.headers.get('content-type') ?? '').includes('text/event-stream')) {
+      let value
+      try { value = await response.json() } catch { throw localError() }
+      yield { type: 'operation', operation: { delivery_state: 'response_ready', host_turn_active: true, response: value } }
+      return
+    }
+    let buffer = '', data = [], content = '', reasoning = '', finish, usage
+    const calls = new Map(), reader = response.body.getReader(), decoder = new TextDecoder()
+    const frame = text => {
+      if (!text || text === '[DONE]') return null
+      try { return JSON.parse(text) } catch { throw localError() }
+    }
+    try {
+      let eof = false
+      while (!eof) {
+        const next = await reader.read(); eof = next.done
+        buffer += eof ? decoder.decode() : decoder.decode(next.value, { stream: true })
+        let match
+        while ((match = /\r\n|\n|\r(?!$)/.exec(buffer))) {
+          const line = buffer.slice(0, match.index); buffer = buffer.slice(match.index + match[0].length)
+          if (line) { if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')); continue }
+          const text = data.join('\n'); data = []
+          if (text === '[DONE]') { eof = true; break }
+          const value = frame(text)
+          if (!value) continue
+          if (value.error) throw localError()
+          if (value.usage) usage = value.usage
+          const choice = value.choices?.[0], delta = choice?.delta
+          if (choice?.finish_reason != null) finish = choice.finish_reason
+          if (!delta) continue
+          if (typeof delta.content === 'string') content += delta.content
+          if (typeof delta.reasoning_content === 'string') reasoning += delta.reasoning_content
+          for (const call of delta.tool_calls ?? []) {
+            const index = call.index ?? 0
+            const target = calls.get(index) ?? { type: 'function', id: '', function: { name: '', arguments: '' } }
+            if (call.id) target.id = call.id
+            if (call.function?.name) target.function.name += call.function.name
+            if (typeof call.function?.arguments === 'string') target.function.arguments += call.function.arguments
+            calls.set(index, target)
+          }
+          yield { type: 'delta', delta: { content: delta.content, reasoning_content: delta.reasoning_content } }
+        }
+      }
+    } finally { await reader.cancel().catch(() => {}) }
+    // An incomplete provider stream is a local adapter error, not an unknown Hub operation.
+    if (finish == null) throw localError()
+    yield { type: 'operation', operation: { delivery_state: 'response_ready', host_turn_active: true, response: {
+      choices: [{ message: { role: 'assistant', content, reasoning_content: reasoning, tool_calls: [...calls.values()] }, finish_reason: finish }], usage,
+    } } }
+  }
+  try { yield* legacyChunks(parsed()) } catch (error) {
+    if (['USAGE_RESPONSE_INVALID', 'USAGE_STREAM_INCOMPLETE'].includes(error.code)) throw localError()
+    throw error
+  }
+}
+
+export async function* usageLlmChunks(events) {
+  const iterator = events[Symbol.asyncIterator]()
+  let first
+  do { first = await iterator.next() } while (!first.done && !['provider', 'delta', 'operation'].includes(first.value.type))
+  async function* remaining() {
+    try { if (!first.done) yield first.value; for (;;) { const next = await iterator.next(); if (next.done) break; yield next.value } }
+    finally { await iterator.return?.() }
+  }
+  if (first.value?.type === 'provider' || first.value?.operation?.response?.schema === 'bailing.provider-response.v1') {
+    yield* usageNativeModelChunks(remaining(), compatibleChunks)
+  } else yield* legacyChunks(remaining()) // Original saved requests from before the transport envelope.
+}

package/lib/usage-model-transport.js

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto'
+import { createFileSessionUsageStore } from './session-usage-store.js'
+import { ModelGatewayTransport } from './model-gateway-transport.js'
+
+const REQUEST_EVENT = 'bailinghub/usage-request'
+const REQUIRED = ['capabilities', 'modelModels', 'modelSummary', 'modelComplete', 'modelStream', 'inspectModelRequest', 'cancelModelRequest']
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+function exact(value, maximum = 191) {
+  if (typeof value !== 'string' || !value.length || value.length > maximum || value.trim() !== value || /[\u0000-\u001f\u007f]/u.test(value)) throw failure('USAGE_INPUT_INVALID')
+  return value
+}
+function failure(code, extra = {}) {
+  const priority = code === 'USAGE_STORAGE_ERROR' ? 'storage_error' : code === 'USAGE_RECOVERY_GAP' ? 'recovery_gap' : 'blocked'
+  return Object.assign(new Error(`The controlled usage service is unavailable (${code}).`), {
+    code, state: priority, feedback: { schema: 'bailing.usage-feedback.v1', code,
+      dispatch: 'not_dispatched', next_action: code === 'USAGE_UNSUPPORTED' ? 'upgrade' : 'resolve_error', retryable: false }, ...extra,
+  })
+}
+function bindingOf(client) {
+  const binding = client?.binding
+  if (!binding || typeof binding !== 'object') throw failure('USAGE_UNSUPPORTED')
+  return Object.fromEntries(['hubUrl', 'userId', 'accountId', 'serviceId'].map((key) => [key, exact(binding[key], key === 'hubUrl' ? 2048 : 191)]))
+}
+function signalActive(signal) { if (signal?.aborted) throw failure('USAGE_CANCELLED') }
+function validSession(session) {
+  exact(session?.id, 4096)
+  if (!Array.isArray(session.events)) throw failure('USAGE_RECOVERY_GAP')
+}
+// DSH also persists plugin context as user-role messages. Only the trusted
+// producer's explicit source marks a real user input, never the model-facing role.
+function isUserInput(event) {
+  return event?.type === 'user/message' && event.data?.source?.kind === 'user'
+}
+function eventFor(session, userMessageId) {
+  validSession(session)
+  const id = exact(userMessageId)
+  const events = session.events.filter((event) => ['user/message', REQUEST_EVENT].includes(event?.type) && event.data?.id === id)
+  if (events.length !== 1 || !Number.isSafeInteger(events[0].seq) || events[0].seq < 0) throw failure('USAGE_RECOVERY_GAP')
+  if (events[0].type === REQUEST_EVENT) {
+    if (events[0].data?.source !== 'host' || !['auxiliary', 'subagent', 'model'].includes(events[0].data?.kind)) throw failure('USAGE_RECOVERY_GAP')
+  } else if (!isUserInput(events[0]) || events[0].data.role !== 'user') throw failure('USAGE_USER_MESSAGE_REQUIRED')
+  return events[0]
+}
+function isLiveMessage(session, event) {
+  if (event.type === REQUEST_EVENT) return !session.events.some(item => item.seq > event.seq && item.type === 'bailinghub/model-request-group-ended' && item.data?.id === event.data.id)
+  return !session.events.some(item => item.seq > event.seq && (isUserInput(item) || item.type === 'turn/end'))
+}
+function primaryFailure(status) {
+  if (status?.state === 'storage_error' || status?.status === 'storage_error' || status?.storageError || status?.unsavedEvents > 0) return failure('USAGE_STORAGE_ERROR')
+  if (status?.state === 'recovery_gap' || status?.status === 'recovery_gap' || status?.recoveryGap) return failure('USAGE_RECOVERY_GAP')
+  return null
+}
+
+/** Host-owned USD model transport. Planning and tool execution remain in the native AgentLoop. */
+export class BailingHubUsageModelTransport {
+  constructor({ client, store, ensureSessionPersisted, getPrimaryStatus, mode } = {}) {
+    if (mode !== undefined && mode !== 'model_gateway') throw failure('USAGE_INPUT_INVALID')
+    this.client = client
+    this.store = store ?? createFileSessionUsageStore()
+    this.ensureSessionPersisted = ensureSessionPersisted
+    this.getPrimaryStatus = getPrimaryStatus
+    this.queues = new Map()
+    this.cancelled = new Set()
+    this.ended = new Set()
+    this.storageFailures = new Set()
+    this.capabilitiesCache = null
+    this.modelTransport = new ModelGatewayTransport(this, { failure, hash, exact, eventFor, isLiveMessage, signalActive })
+  }
+  assertSupported() {
+    if (REQUIRED.some(method => typeof this.client?.[method] !== 'function') || typeof this.ensureSessionPersisted !== 'function') throw failure('USAGE_UNSUPPORTED')
+    return bindingOf(this.client)
+  }
+  async primary(session) {
+    validSession(session)
+    let status
+    try { status = await this.getPrimaryStatus?.(session) } catch { throw failure('USAGE_STORAGE_ERROR') }
+    const existing = primaryFailure(status)
+    if (existing) throw existing
+    if (this.storageFailures.has(session.id)) throw failure('USAGE_STORAGE_ERROR')
+  }
+  async durable(session) {
+    await this.primary(session)
+    this.assertSupported()
+    try { if (await this.ensureSessionPersisted(session) !== true) throw new Error() }
+    catch { throw failure('USAGE_STORAGE_ERROR') }
+  }
+  serial(session, operation) {
+    const previous = this.queues.get(session.id) ?? Promise.resolve()
+    const current = previous.catch(() => {}).then(operation)
+    this.queues.set(session.id, current)
+    current.finally(() => { if (this.queues.get(session.id) === current) this.queues.delete(session.id) }).catch(() => {})
+    return current
+  }
+  async negotiate(options = {}) {
+    this.assertSupported()
+    if (!options.refresh && this.capabilitiesCache?.until > Date.now()) return this.capabilitiesCache.value
+    const caps = await this.client.capabilities(options), token = caps?.model_gateway
+    if (caps?.schema !== 'bailing.usage.v1' || caps.supported !== true || caps.streaming !== true || caps.orchestration !== 'host'
+      || token?.schema !== 'bailing.model-gateway.v1' || token.supported !== true || token.turn_required !== false
+      || token.provider_response !== 'bailing.provider-response.v1' || token.settlement !== 'asynchronous'
+      || token.orchestration !== 'host' || token.streaming !== true || token.billing_unit !== 'USD') throw failure('USAGE_UNSUPPORTED')
+    this.capabilitiesCache = { value: caps, until: Date.now() + 60_000 }
+    return caps
+  }
+  async model(options = {}) {
+    await this.negotiate(options)
+    return this.modelTransport.model(options)
+  }
+  /** Fetch permitted tools for the local host to register, without starting a business run. */
+  async modelTools(options = {}) {
+    await this.negotiate(options)
+    if (typeof this.client.modelTools !== 'function') throw failure('USAGE_UNSUPPORTED')
+    return this.client.modelTools(options)
+  }
+  /** One local tool call, tracked durably using the same original-request recovery protocol. */
+  async runModelTool(session, input, options = {}) {
+    validSession(session)
+    await this.durable(session)
+    eventFor(session, input?.userMessageId)
+    await this.negotiate(options)
+    if (typeof this.client.runModelTool !== 'function' || typeof this.client.modelTools !== 'function') throw failure('USAGE_UNSUPPORTED')
+    return this.modelTransport.complete(session, input, options, true)
+  }
+  async status(session, options = {}) {
+    await this.primary(session)
+    await this.negotiate(options)
+    return this.modelTransport.status(session, options)
+  }
+  async complete(session, input, options = {}) {
+    validSession(session)
+    await this.durable(session)
+    eventFor(session, input?.userMessageId)
+    await this.negotiate(options)
+    return this.modelTransport.complete(session, input, options)
+  }
+  /** A trusted host can meter a local helper/child request without inventing a user message.
+   * For requests inside a user turn, prefer complete/stream with that original owner Session and userMessageId.
+   */
+  async prepareRequest(session, input) {
+    validSession(session)
+    if (!input || Object.keys(input).some(key => !['modelRequestId', 'serviceId', 'requestGroupId', 'requestKind',
+      'messages', 'tools', 'tool_choice', 'temperature', 'provider_options'].includes(key))) throw failure('USAGE_INPUT_INVALID')
+    const requestGroupId = exact(input.requestGroupId ?? `request_${hash(exact(input.modelRequestId)).slice(0, 40)}`)
+    const kind = input.requestKind ?? 'model'
+    if (!['model', 'auxiliary', 'subagent'].includes(kind)) throw failure('USAGE_INPUT_INVALID')
+    await this.serial(session, async () => {
+      await this.primary(session)
+      const existing = session.events.find(e => [REQUEST_EVENT, 'user/message'].includes(e.type) && e.data?.id === requestGroupId)
+      if (existing && (existing.type !== REQUEST_EVENT || existing.data.kind !== kind)) throw failure('USAGE_IDEMPOTENCY_CONFLICT')
+      if (!existing) {
+        if (typeof session.append !== 'function') throw failure('USAGE_RECOVERY_GAP')
+        session.append(REQUEST_EVENT, { id: requestGroupId, kind, source: 'host' })
+      }
+      await this.durable(session)
+    })
+    return { ...input, userMessageId: requestGroupId }
+  }
+  async completeRequest(session, input, options = {}) {
+    const prepared = await this.prepareRequest(session, input)
+    return { ...await this.complete(session, prepared, options), request_group_id: prepared.userMessageId }
+  }
+  async *streamRequest(session, input, options = {}) {
+    const prepared = await this.prepareRequest(session, input)
+    for await (const event of this.stream(session, prepared, options)) yield event.type === 'operation'
+      ? { ...event, operation: { ...event.operation, request_group_id: prepared.userMessageId } } : event
+  }
+  /** Backpressured preview stream; only the terminal delivery may resume the local loop. */
+  async *stream(session, input, options = {}) {
+    const controller = new AbortController()
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal
+    const queue = []; let wake, stopped = false
+    const put = value => { queue.push(value); wake?.(); wake = null }
+    const running = this.complete(session, input, { ...options, signal,
+      onDelta: event => stopped ? undefined : new Promise(resolve => put({ event, ack: resolve })) })
+      .then(receipt => put({ event: { type: 'operation', operation: receipt }, done: true }), error => put({ error, done: true }))
+    let current
+    try {
+      for (;;) {
+        if (!queue.length) await new Promise(resolve => { wake = resolve })
+        current = queue.shift()
+        if (current.error) throw current.error
+        if (!current.done && (signal.aborted || this.cancelled.has(`${session.id}:${input.userMessageId}`) || this.ended.has(`${session.id}:${input.userMessageId}`)
+          || !isLiveMessage(session, eventFor(session, input.userMessageId)))) { current.ack?.(); current = null; continue }
+        yield current.event
+        const terminal = current.done
+        current.ack?.(); current = null
+        if (terminal) return
+      }
+    } finally {
+      stopped = true; controller.abort(); current?.ack?.()
+      for (const item of queue) item.ack?.()
+      await running
+    }
+  }
+  async recoverOperation(session, operationId, options = {}) {
+    validSession(session)
+    return this.modelTransport.recover(session, operationId, options)
+  }
+  async close(session, userMessageId, cancelled, options = {}) {
+    validSession(session)
+    return this.modelTransport.close(session, userMessageId, cancelled, options)
+  }
+  endTurn(session, userMessageId, options) { return this.close(session, userMessageId, false, options) }
+  cancelTurn(session, userMessageId, options) { return this.close(session, userMessageId, true, options) }
+}
+export function createUsageModelTransport(options) { return new BailingHubUsageModelTransport(options) }