dsh-bailinghub 0.5.0 → 0.7.0

package/docs/USAGE_SERVICE.md

@@ -0,0 +1,96 @@
+# USD model gateway for local agents
+
+A plan has a USD allowance, one multiplier, and a live selection of conversation models and model tools. The Hub relays individual requests and meters their cost. The host keeps its original planning, tool selection and AgentLoop. Business authorization, approval, session scope, task controls and conversation archives remain separate.
+
+This optional module pairs Core 0.9.0, SDK 0.7.0 and DSH 0.7.0. It is new relative to public SDK/DSH 0.6.0 and has no legacy Token-allowance aliases, silent billing fallback, balance conversion or automatic BYOK substitution. Public Core 0.8.0 upgrades add outstanding 063/064 migrations and retain existing data. Do not erase business authorizations, history or unrelated sessions; abandoned test configuration is separate maintenance, not a customer upgrade requirement.
+
+## Identity and catalog
+
+The trusted product backend issues a Usage credential for the original Hub/user/account. `model_access:'token_gateway'` remains the credential scope spelling for the whole permitted plan; it does not select a Token billing algorithm. A deliberately single-service credential stays restricted to its original service. Supplier URLs and API keys stay server-side.
+
+```js
+import { createUsageClient } from 'bailinghub-mcp-server/usage'
+const client = createUsageClient({
+  hubUrl: trustedLogin.hubUrl,
+  userId: trustedLogin.userId,
+  accountId: trustedLogin.accountId,
+  serviceId: trustedLogin.serviceId,
+  accessTokenProvider: () => secureCredentials.readUsageToken(),
+})
+await client.capabilities()
+const models = await client.modelModels()
+const tools = await client.modelTools()
+const summary = await client.modelSummary()
+```
+
+Capabilities must advertise `model_gateway` with schema `bailing.model-gateway.v1`, `billing_unit:'USD'`, `orchestration:'host'`, `turn_required:false`, streaming, native provider response envelopes and asynchronous settlement. Old Core/SDK returns explicit unsupported, not an alternative billing path.
+
+`modelModels()` reads `/usage/v1/model/models`, schema `bailing.model-models.v1`. Its `items` are only conversation models. Render the operator's `label`, store the immutable `service_id`, never route by label or provider model name. Every read refreshes current plan membership. An empty directory is valid and does not authorize choosing an unrelated model.
+
+`modelTools()` reads `/usage/v1/model/tools`, schema `bailing.model-tools.v1`. Each item has a stable `service_id`, `service_revision`, display label, capability/output kinds and a `tool:{name,description,input_schema}`. Register only `callable:true` items in the host's local tool registry. Keep unavailable items as configuration diagnostics with their explicit `reason`. Catalog reads neither generate media nor start business runs. Namespace registrations by service identity to avoid duplicate operator-defined names or collisions with business tools; tool names alone are never authorization identities.
+
+## Shared allowance and display
+
+`modelSummary()` returns `bailing.billing-summary.v1`, with USD fields `availableUsd`, `consumedUsd`, `currentPeriodConsumedUsd`, `overageUsd`, the original grant and current plan. The plan supplies `serviceIds` and one `multiplier`; per-model input/output multipliers and Token balances no longer exist.
+
+Use `presentation` (`bailing.usage-presentation.v1`) for customer balances: allowance packs show credits; periodic plans show remaining percentage and reset time. Never recalculate balances locally from raw tokens, prices or a previous model response. Missing/malformed presentation is `USAGE_RESPONSE_INVALID`, not a guessed balance. Account details may show reported provider Token counts as usage information, separate from allowance and percentage. If unavailable, show not provided, never fabricate zero Tokens.
+
+Reference provider pricing is not an actual supplier invoice or guaranteed margin. Each request snapshots its plan multiplier and reference price; server-side USD accounting is exact to twelve decimal places. Receipt fields `reference_cost_usd`, `billed_usd`, `overage_usd` are amounts; `usage` contains integer Token counts when reported, and `raw_usage` can contain non-Token measurements. Unknown usage keeps billing pending. No client-side multiplication, second debit or extra model request is allowed.
+
+## Request and recovery API
+
+| SDK method | Behavior |
+| --- | --- |
+| `modelComplete(input)` | One JSON model request, no server agent loop |
+| `modelStream(input)` | Provider packets followed by the original durable operation receipt |
+| `runModelTool(input)` | One model-tool generation request |
+| `inspectModelRequest(operationId, originalCoordinates)` | Read original operation only |
+| `cancelModelRequest(operationId, originalCoordinates)` | Cancel original operation, never replay it |
+
+Conversation requests use `/usage/v1/model/requests` and `/usage/v1/model/requests/stream`. Tool requests use `POST /usage/v1/model/tools/requests` with `{operation_id,service_id,arguments,conversation_id?,turn_id?}`. A tool POST can return HTTP 202 with a durably admitted pending operation. Poll the original request until complete or cancelled; do not submit another generation. All use the same original request inspection/cancellation path and `bailing.model-operation.v1` receipt. Streaming frames use `bailing.model-stream.v1`.
+
+A completed model result can have `billing_state:'pending'`; billing settlement must not stop the local loop. Native provider response bytes are preserved in `bailing.provider-response.v1`. The local provider adapter interprets content, finish reason and tool calls. A tool result uses `bailing.model-tool-result.v1` with typed outputs. Downloading or using a result in a business attachment space is an explicit subsequent host action, never an automatic business write by the Hub.
+
+Persist the original operation ID, selected service and local event coordinates before any dispatch. If a POST loses its ACK, inspect that original ID; do not create a new ID, regenerate an image, change service, retry through BYOK or label the operation not dispatched. Read/cancel failures preserve uncertainty. Storage failure and recovery gaps remain primary errors.
+
+## Host integration
+
+The host must actually register executable model tools; putting their description in a prompt alone is insufficient. Present concise guidance alongside current registered tools: “These are the model tools available under this plan. Use the supplied schemas. When an operation is pending or its result is uncertain, recover the original operation ID rather than repeating generation.”
+
+The server still rechecks the live plan and selected service on each new request. A cached descriptor is not a permission grant. Business tool scope and approvals are not bypassed by generating a media file.
+
+## Durable DSH host adapter
+
+```js
+import { createUsageModelTransport, usageNativeModelChunks } from 'dsh-bailinghub'
+const usage = createUsageModelTransport({
+  client,
+  ensureSessionPersisted: session => persistRealSessionAndConfirm(session),
+  getPrimaryStatus: session => currentPersistenceStatus(session),
+})
+const tools = await usage.modelTools()
+const receipt = await usage.runModelTool(realSession, {
+  userMessageId: originalUserMessageId,
+  modelRequestId: stableLocalToolCallId,
+  serviceId: selectedTool.service_id,
+  arguments: validatedToolArguments,
+})
+```
+
+Register each callable descriptor using the native host tool registry and route its stable service ID to `usage.runModelTool`. Reuse the same local tool call ID when inspecting an unresolved call. `recoverOperation(session, operationId)` reads the saved original result; it never dispatches a second generation. For a new intentional generation, use a new local call ID.
+
+`model({serviceId,refresh?})`, `complete(session,input)`, `stream(session,input)`, `status(session)`, `endTurn`, `cancelTurn`, `completeRequest` and `streamRequest` remain the host transport interfaces. Omit `mode` or use `model_gateway`. The descriptor cache lasts 60 seconds; cache hits do not extend freshness. Use `refresh:true` after settings change. No message-count, paid-turn count or task wall-clock quota is added.
+
+The real durable DSH Session indexes `bailinghub/model-request` markers. Each request has a bounded CAS sidecar containing identity/hash/state only, not messages, tool arguments, provider credentials or generated content. Save both before dispatch. Retain them for same-operation recovery; missing metadata produces `USAGE_RECOVERY_GAP`, never an invented request. Old unpublished Token billing markers are not imported into the new ledger; ordinary business session history remains intact.
+
+Native streaming uses `usageNativeModelChunks` with the host's actual provider parser. Text/reasoning may display incrementally, but executable tool blocks and finish wait for the original durable receipt. Ending/cancelling the user input immediately fences late results; they remain inspectable history and do not restart tools. Final local save failures remain `storage_error` even when the provider result is known. Unknown billing settlement alone does not make a complete model result unusable.
+
+Synthetic acceptance covers current account catalog isolation, empty/unavailable tools, generation ACK loss across full store reopen, cancellation before late generation, raw Token usage alongside USD amounts, native provider streaming, original request recovery and long local tasks.
+
+### Image provider outcome receipts
+
+`result_state=failed`, `state=failed`, `dispatch=rejected` is a confirmed provider rejection. Stop waiting; show the bounded `error` and `next_action=contact_operator`. Never automatically create a replacement operation. `unknown` is not a running task or proof of zero cost: preserve the original ID for inspection. Only `pending` means keep waiting. A complete result is usable independently of pending billing.
+
+The diagnostic whitelist is `code`, fixed safe `message`, optional `http_status`, `provider_code`, `provider_request_id`, `retryable=false`, and `next_action`. Provider bodies and credentials are excluded. Cancelled/ended turns never regain active tools through late receipts. Existing durable request identities and prior unknown records remain unchanged.
+
+DSH stores failed requests using the existing local `rejected` state and returns `delivery_state=request_failed`. Unknown receipts return `unresolved_original`; pending receipts retain `pending_original`. No Session event or sidecar migration is required, and primary storage/recovery errors retain priority.

package/lib/artifact-store.js

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, link, unlink } from 'node:fs/promises'
+import { resolve, join } from 'node:path'
+
+const error = () => Object.assign(new Error('Artifact recovery metadata could not be saved or restored.'), { code: 'storage_error' })
+const fileName = id => { if (!/^[a-f0-9]{64}$/.test(id)) throw error(); return `${id}.json` }
+function checked(value, id) {
+  const json = JSON.stringify(value)
+  if (json.length > 16384 || value?.uploadId !== id || !value.metadata || !value.binding || !value.artifactRef || !value.sessionId) throw error()
+  return JSON.parse(json)
+}
+/** Test/ephemeral hosts only. Production hosts must persist the immutable recovery record. */
+export function createMemoryArtifactStore() {
+  const records = new Map()
+  return { async get(id) { return structuredClone(records.get(id) ?? null) }, async reserve(value) {
+    if (!records.has(value.uploadId)) records.set(value.uploadId, checked(value, value.uploadId))
+    return structuredClone(records.get(value.uploadId))
+  } }
+}
+/** Atomic write-once receipts; no credentials or file bytes. Keep this directory across restarts. */
+export function createFileArtifactStore({ directory } = {}) {
+  if (typeof directory !== 'string' || !directory) throw error()
+  const root = resolve(directory)
+  async function prepare() {
+    await mkdir(root, { recursive: true, mode: 0o700 })
+    const stat = await lstat(root)
+    if (!stat.isDirectory() || (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o700)) throw error()
+  }
+  async function get(id) {
+    try {
+      await prepare()
+      let handle
+      try { handle = await open(join(root, fileName(id)), constants.O_RDONLY | constants.O_NOFOLLOW) }
+      catch (e) { if (e.code === 'ENOENT') return null; throw e }
+      try {
+        const stat = await handle.stat()
+        if (!stat.isFile() || stat.size > 16384 || (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o600)) throw error()
+        return checked(JSON.parse(await handle.readFile('utf8')), id)
+      } finally { await handle.close() }
+    } catch { throw error() }
+  }
+  return { get, async reserve(value) {
+    const data = checked(value, value.uploadId)
+    let temporary
+    try {
+      await prepare()
+      temporary = join(root, `${randomUUID()}.tmp`)
+      const handle = await open(temporary, 'wx', 0o600)
+      try { await handle.writeFile(JSON.stringify(data)); await handle.sync() } finally { await handle.close() }
+      try { await link(temporary, join(root, fileName(value.uploadId))) } catch (e) { if (e.code !== 'EEXIST') throw e }
+      if (process.platform !== 'win32') { const dir = await open(root, 'r'); try { await dir.sync() } finally { await dir.close() } }
+      return await get(value.uploadId)
+    } catch { throw error() } finally { if (temporary) await unlink(temporary).catch(() => {}) }
+  } }
+}

package/lib/artifacts.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto'
+
+const digest = (...parts) => createHash('sha256').update(JSON.stringify(parts)).digest('hex')
+const fail = code => Object.assign(new Error(code), { code })
+const repairSchema = 'bailing.artifact-run-link-repair.v1'
+const withoutRun = metadata => { const { runId, ...rest } = metadata; return rest }
+const receiptMatches = (receipt, metadata) => ['name', 'mime', 'bytes', 'sha256'].every(k => receipt[k] === metadata[k]) &&
+  receipt.client_conversation_id === metadata.clientConversationId && receipt.client_turn_id === metadata.clientTurnId && receipt.run_id === metadata.runId
+const descriptor = v => {
+  if (!v || typeof v.artifactRef !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(v.artifactRef) || typeof v.name !== 'string' || !v.name || v.name.length > 128 || /[\\/\u0000-\u001f\u007f]/.test(v.name) ||
+    !['image/png', 'image/jpeg', 'image/webp'].includes(v.mime) || !Number.isInteger(v.bytes) || v.bytes < 1 || v.bytes > 6291456 || !/^[a-f0-9]{64}$/.test(v.sha256)) throw fail('artifact_invalid_source')
+  return { artifactRef: v.artifactRef, name: v.name, mime: v.mime, bytes: v.bytes, sha256: v.sha256 }
+}
+export async function listArtifacts(source, sessionId) {
+  if (typeof source?.list !== 'function') throw fail('artifact_source_unsupported')
+  const values = await source.list({ sessionId })
+  if (!Array.isArray(values) || values.length > 100) throw fail('artifact_invalid_source')
+  const result = values.map(descriptor)
+  if (new Set(result.map(x => x.artifactRef)).size !== result.length) throw fail('artifact_invalid_source')
+  return result
+}
+/** One immutable original target per receipt. This never invokes a business operation. */
+export async function deliverArtifact({ source, store, transport, sessionId, artifactRef, binding, options, metadata, assertActive }) {
+  if (!store?.get || !store?.reserve) throw fail('storage_error')
+  if (!transport?.uploadArtifact || !transport?.getArtifact) throw fail('artifact_unsupported')
+  const uploadId = digest('bailing.artifact.v1', sessionId, options.connectionKey, artifactRef)
+  const repairId = digest(repairSchema, uploadId)
+  const validateStored = record => {
+    if (!record || record.sessionId !== sessionId || record.artifactRef !== artifactRef || record.uploadId !== uploadId || JSON.stringify(record.binding) !== JSON.stringify(binding)) throw fail('artifact_conflict')
+    return record
+  }
+  let record
+  try { record = await store.get(uploadId) } catch { throw fail('storage_error') }
+  let repair
+  const loadRepair = async () => {
+    let saved
+    try { saved = await store.get(repairId) } catch { throw fail('storage_error') }
+    if (saved) {
+      if (!record?.metadata.runId || digest(saved) !== digest(repairRecord())) throw fail('storage_error')
+      repair = saved
+    } else if (repair) throw fail('storage_error')
+    return repair
+  }
+  const repairRecord = () => ({ uploadId: repairId, sessionId, artifactRef, binding,
+    metadata: withoutRun(record.metadata),
+    runLinkRepair: { schema: repairSchema, originalUploadId: uploadId, originalMetadataHash: digest(record.metadata), reason: 'artifact_run_turn_mismatch' },
+  })
+  const checkReceipt = async result => {
+    await loadRepair()
+    const expected = repair?.metadata ?? record.metadata
+    if (!['ready', 'pending'].includes(result?.state)) throw fail('artifact_invalid_receipt')
+    if (!receiptMatches(result, expected)) {
+      // A corrected remote receipt without its local correction is a history
+      // gap, not permission to reconstruct the missing recovery record.
+      if (!repair && record.metadata.runId && receiptMatches(result, withoutRun(record.metadata))) throw fail('storage_error')
+      throw fail('artifact_conflict')
+    }
+    return result
+  }
+  await loadRepair()
+  if (record) {
+    validateStored(record)
+    await assertActive()
+    try {
+      const result = await checkReceipt(await transport.getArtifact(uploadId, options))
+      if (result.state === 'ready') {
+        await assertActive()
+        return { artifact_ref: artifactRef, ...result }
+      }
+    } catch (e) { if (e.publicCode !== 'artifact_not_found') throw e }
+  }
+  await assertActive()
+  if (typeof source?.read !== 'function') throw fail('artifact_source_unsupported')
+  const item = (await listArtifacts(source, sessionId)).find(x => x.artifactRef === artifactRef)
+  if (!item) throw fail('artifact_not_found_local')
+  if (record && (record.metadata.sha256 !== item.sha256 || record.metadata.name !== item.name || record.metadata.mime !== item.mime || record.metadata.bytes !== item.bytes)) throw fail('artifact_content_changed')
+  const raw = await source.read({ sessionId, artifactRef })
+  if (!(raw instanceof Uint8Array)) throw fail('artifact_invalid_source')
+  if (raw.byteLength !== item.bytes) throw fail('artifact_content_changed')
+  const body = Buffer.from(raw)
+  if (body.length !== item.bytes || createHash('sha256').update(body).digest('hex') !== item.sha256) throw fail('artifact_content_changed')
+  if (!record) {
+    try { record = await store.reserve({ uploadId, sessionId, artifactRef, binding, metadata: { ...metadata, name: item.name, mime: item.mime, bytes: item.bytes, sha256: item.sha256 } }) }
+    catch { throw fail('storage_error') }
+    validateStored(record)
+    if (['sha256', 'name', 'mime', 'bytes'].some(key => record.metadata[key] !== item[key])) throw fail('artifact_content_changed')
+  }
+  await assertActive()
+  await loadRepair()
+  let result
+  try {
+    result = await transport.uploadArtifact({ uploadId, body, ...(repair?.metadata ?? record.metadata) }, options)
+  } catch (error) {
+    // Only Core's explicit same-identity, same-route, same-conversation proof
+    // permits detaching a run from another turn. Generic mismatch stays blocked.
+    if (error.publicCode !== 'artifact_run_turn_mismatch' || repair || !record.metadata.runId ||
+      record.metadata.clientConversationId !== metadata.clientConversationId) throw error
+    await assertActive()
+    try {
+      const existing = await checkReceipt(await transport.getArtifact(uploadId, options))
+      if (existing.state === 'ready') {
+        await assertActive()
+        return { artifact_ref: artifactRef, ...existing }
+      }
+      throw error
+    } catch (readError) { if (readError.publicCode !== 'artifact_not_found') throw readError }
+    await assertActive()
+    try { await store.reserve(repairRecord()) } catch { throw fail('storage_error') }
+    await loadRepair()
+    if (!repair) throw fail('storage_error')
+    await assertActive()
+    // The original upload ID, file, target and upload turn remain unchanged.
+    // The immutable original record retains the rejected run for diagnostics.
+    result = await transport.uploadArtifact({ uploadId, body, ...repair.metadata }, options)
+  }
+  await checkReceipt(result)
+  await assertActive()
+  return { artifact_ref: artifactRef, ...result }
+}
+
+export function artifactFailure(error, artifactRef) {
+  const candidate = error?.publicCode ?? error?.code
+  const known = new Set(['storage_error', 'artifact_unsupported', 'artifact_source_unsupported', 'artifact_invalid_source', 'artifact_not_found_local', 'artifact_content_changed',
+    'artifact_conflict', 'artifact_invalid_request', 'artifact_content_mismatch', 'artifact_type_not_allowed', 'artifact_too_large', 'artifact_run_mismatch', 'artifact_run_turn_mismatch',
+    'artifact_storage_changed', 'artifact_upload_disabled', 'artifact_storage_unavailable', 'artifact_upload_pending', 'artifact_invalid_receipt',
+    'agent_request_timeout', 'agent_transport_unavailable', 'unauthorized', 'route_not_allowed', 'agent_request_cancelled'])
+  const code = known.has(candidate) ? candidate : 'artifact_delivery_blocked'
+  const pending = ['artifact_upload_pending', 'agent_request_timeout', 'agent_transport_unavailable'].includes(code)
+  return { artifact_ref: artifactRef, state: pending ? 'pending' : 'blocked', error: code,
+    next_action: pending ? 'retry_same_artifact_and_authorization' : code === 'storage_error' ? 'repair_local_storage' : 'resolve_error',
+    business_operation_performed: false }
+}

package/lib/capability-feedback.js

@@ -0,0 +1,138 @@
+// The SDK owns HTTP error classification. This projection also supports older
+// SDKs and custom transports without importing an optional SDK entry point.
+const ID = /^[0-9a-f]{64}$/
+const CATEGORIES = new Set(['tool_not_loaded', 'capability_changed', 'transport_unavailable', 'authorization_unavailable', 'unsupported', 'invocation_outcome_unknown', 'unknown_failure', 'cancelled', 'invalid_request', 'storage_error', 'invocation_recovery_unavailable', 'task_control'])
+const ACTIONS = new Set(['rediscover', 'retry_discovery', 'restore_scope', 'reauthorize', 'check_compatibility', 'resume_original', 'inspect_original', 'restore_invocations', 'restore_task', 'inspect_task', 'none'])
+const ORIGINS = new Set(['core', 'sdk', 'mcp', 'dsh', 'host'])
+const CODES = new Set([
+  'TASK_DISPATCH_UNCERTAIN', 'TASK_NOT_FOUND', 'TASK_RUN_INACTIVE', 'TASK_INVALID_INPUT',
+  'TASK_REQUIRED', 'TASK_UNSUPPORTED', 'TASK_SCOPE_BLOCKED', 'TASK_MEMBER_MISMATCH', 'TASK_BINDING_CONFLICT', 'TASK_PAUSED', 'TASK_CANCELLED', 'TASK_EXPIRED', 'TASK_WRITE_BUDGET_EXHAUSTED', 'TASK_CONCURRENCY_EXHAUSTED', 'TASK_TOOL_NOT_ALLOWED', 'TASK_REVISION_CONFLICT', 'TASK_RECORD_INVALID', 'TASK_UNAVAILABLE', 'TASK_STORE_CONFLICT', 'TASK_STORE_UNAVAILABLE',
+  'invocation_binding_unavailable', 'invocation_binding_conflict', 'invocation_store_unavailable', 'invocation_store_conflict', 'invocation_store_unsupported',
+  'agent_client_disabled', 'agent_direct_disabled', 'agent_runtime_unavailable', 'agent_tools_unavailable',
+  'arguments_too_large', 'assistant_message_conflict', 'audience_not_allowed', 'capability_changed',
+  'hub_paused', 'invalid_request', 'invalid_route', 'invocation_conflict', 'invocation_not_found',
+  'page_context_too_large', 'route_not_allowed', 'route_unavailable', 'run_completion_conflict',
+  'run_not_found', 'tool_not_found', 'turn_conflict', 'conversation_audit_conflict',
+  'conversation_audit_not_found', 'conversation_audit_not_ready', 'conversation_audit_authorization_invalid',
+  'conversation_audit_limit', 'conversation_audit_unavailable', 'conversation_audit_internal_error',
+  'conversation_audit_cross_binding_unavailable', 'system_info_unsupported', 'agent_binding_changed',
+  'agent_request_cancelled', 'agent_transport_unavailable', 'agent_request_timeout',
+  'agent_authorization_unavailable', 'agent_schema_unsupported', 'agent_invalid_response',
+  'tool_not_loaded', 'reconciliation_required', 'unknown_failure',
+
+  'agent_invalid_request', 'unauthorized', 'forbidden', 'agent_tool_internal_error',
+  'BAILINGHUB_ACCEPTED_UNKNOWN', 'BAILINGHUB_AGENT_CLIENT_UNAVAILABLE',
+  'AUTHORIZATION_CHANGED', 'AUTHORIZATION_UNVERIFIED', 'SESSION_SCOPE_UNAVAILABLE',
+  'CROSS_SYSTEM_SCOPE_UNSUPPORTED', 'CROSS_HUB_SCOPE_UNSUPPORTED',
+  'SCOPE_STORE_UNAVAILABLE', 'SCOPE_STORE_CONFLICT', 'SESSION_SCOPE_CONFLICT',
+  'INVALID_SCOPE_SNAPSHOT', 'INVALID_SESSION_ID', 'SESSION_LOCAL_STORAGE_ERROR', 'SESSION_RECOVERY_GAP',
+])
+
+const MESSAGES = {
+  task_control: 'The original task does not currently permit this operation. Inspect its task state; do not rediscover tools, change authorization, replace the invocation or create a new task to bypass the limit.',
+  storage_error: 'The local invocation recovery record could not be saved or verified. Restore invocation storage before continuing; do not create a replacement write. This does not confirm the original business outcome.',
+  invocation_recovery_unavailable: 'The original invocation binding is missing or conflicts with this fixed session scope. Inspect the original record; never switch target, guess arguments or create a replacement write.',
+  tool_not_loaded: 'This business tool is no longer loaded. Discover capabilities for the same selected target; an existing invocation must be recovered using its original ID.',
+  capability_changed: 'The capability declaration or its authorization changed. Keep any original invocation and its target; never create a replacement write to recover an uncertain result.',
+  transport_unavailable: 'The connection is temporarily unavailable. Retry only the indicated discovery, identity check or original invocation recovery.',
+  authorization_unavailable: 'The original authorization cannot currently be used. Do not switch to a default, different authorization or a surviving subset.',
+  unsupported: 'The current component does not support this capability. Check compatibility; this does not mean the business system has no capabilities.',
+  invocation_outcome_unknown: 'The original operation outcome is unconfirmed. Recover only the original invocation_id; never create a replacement business call.',
+  unknown_failure: 'The failure could not be classified. Do not infer that the business capability is absent or repeat an uncertain write.',
+  cancelled: 'This operation or turn has ended. Do not reactivate its tools or create a replacement business call.',
+  invalid_request: 'The request is invalid for this tool. Check the current tool declaration and selected target.',
+}
+
+// A generic 404 or error message cannot establish that Core looked up the
+// original invocation. Require the SDK's structured public code and HTTP status.
+export function isInvocationNotFound(error) {
+  return error?.publicCode === 'invocation_not_found' && error?.statusCode === 404
+}
+
+export function describeFailure(error, context = {}) {
+  const source = error?.feedback?.schema === 'bailing.agent-feedback.v1' ? error.feedback : undefined
+  const operation = context.operation ?? 'tool_dispatch'
+  const id = context.invocationId ?? source?.invocation_id ?? error?.invocationId
+  const invocationId = typeof id === 'string' && ID.test(id) ? id : undefined
+  const rawCode = source?.code ?? error?.publicCode ?? error?.code
+  const code = CODES.has(rawCode) ? rawCode : 'unknown_failure'
+  const missingOriginal = (['resume', 'inspect'].includes(operation) && isInvocationNotFound(error)) ||
+    (source?.code === 'invocation_not_found' && source?.next_action === 'inspect_original' && source?.original_outcome === 'unverified')
+  let category = CATEGORIES.has(source?.category) ? source.category : 'unknown_failure'
+  let next = ACTIONS.has(source?.next_action) ? source.next_action : 'none'
+  let dispatch = ['not_dispatched', 'attempted', 'unknown'].includes(source?.dispatch)
+    ? source.dispatch : context.dispatch ?? (['invoke', 'resume'].includes(operation) ? 'unknown' : 'not_dispatched')
+  if (!source) {
+    if (['TASK_DISPATCH_UNCERTAIN', 'TASK_UNAVAILABLE'].includes(code) && ['invoke', 'resume'].includes(operation)) { category = 'invocation_outcome_unknown'; next = 'inspect_original'; dispatch = 'unknown' }
+    else if (code.startsWith('TASK_')) { category = code.startsWith('TASK_STORE_') ? 'storage_error' : code === 'TASK_UNSUPPORTED' ? 'unsupported' : 'task_control'; next = category === 'storage_error' ? 'restore_task' : category === 'unsupported' ? 'check_compatibility' : 'inspect_task'; dispatch = 'not_dispatched' }
+    else if (error?.name === 'AbortError' || code === 'agent_request_cancelled') category = 'cancelled'
+    else if (code === 'tool_not_loaded' || code === 'tool_not_found') { category = 'tool_not_loaded'; next = 'rediscover' }
+    else if (code === 'capability_changed') { category = 'capability_changed'; next = operation === 'resume' ? 'inspect_original' : 'rediscover' }
+    else if (['agent_transport_unavailable', 'agent_request_timeout'].includes(code)) { category = 'transport_unavailable'; next = operation === 'search' ? 'retry_discovery' : 'restore_scope' }
+    else if (['unauthorized', 'forbidden', 'agent_authorization_unavailable', 'agent_binding_changed', 'AUTHORIZATION_CHANGED', 'route_not_allowed', 'audience_not_allowed', 'conversation_audit_authorization_invalid'].includes(code) || [401, 403].includes(error?.statusCode)) { category = 'authorization_unavailable'; next = 'reauthorize' }
+    else if (['AUTHORIZATION_UNVERIFIED', 'SESSION_SCOPE_UNAVAILABLE'].includes(code)) { category = 'authorization_unavailable'; next = 'restore_scope' }
+    else if (['agent_schema_unsupported', 'CROSS_SYSTEM_SCOPE_UNSUPPORTED', 'CROSS_HUB_SCOPE_UNSUPPORTED'].includes(code)) { category = 'unsupported'; next = 'check_compatibility' }
+    else if (['agent_invalid_request', 'invalid_request', 'invalid_route', 'arguments_too_large', 'page_context_too_large'].includes(code) || error instanceof TypeError && !['invoke', 'resume'].includes(operation)) { category = 'invalid_request'; dispatch = 'not_dispatched' }
+  }
+  if (!source && operation === 'invoke' && ['definitive_rejection', 'refresh_required'].includes(error?.disposition) &&
+    ([401, 403].includes(error?.statusCode) || ['capability_changed', 'tool_not_found', 'invalid_request', 'route_not_allowed', 'audience_not_allowed'].includes(code))) {
+    dispatch = 'not_dispatched'
+  }
+  // A previously dispatched call takes precedence over tool discovery advice.
+  if (error?.disposition === 'accepted_unknown' || source?.disposition === 'accepted_unknown' || category === 'invocation_outcome_unknown') {
+    category = 'invocation_outcome_unknown'; dispatch = dispatch === 'not_dispatched' ? 'unknown' : dispatch; next = source?.next_action === 'inspect_original' || ['reconciliation_required', 'TASK_DISPATCH_UNCERTAIN', 'TASK_UNAVAILABLE'].includes(code) || !invocationId ? 'inspect_original' : 'resume_original'
+  } else if (!source && operation === 'resume' && invocationId && !['cancelled', 'authorization_unavailable', 'unsupported', 'task_control', 'storage_error'].includes(category)) {
+    next = ['transport_unavailable', 'unknown_failure'].includes(category) ? 'resume_original' : 'inspect_original'
+  } else if (!source && operation === 'invoke' && invocationId && dispatch !== 'not_dispatched' && !['cancelled', 'authorization_unavailable', 'unsupported', 'capability_changed', 'task_control', 'storage_error'].includes(category)) {
+    category = 'invocation_outcome_unknown'; next = 'resume_original'
+  }
+  if (missingOriginal) {
+    // This is evidence about recovery availability, not proof that the original
+    // business action never ran. Preserve it through the host's second projection.
+    category = 'invocation_outcome_unknown'
+    dispatch = dispatch === 'attempted' ? 'attempted' : 'unknown'
+    next = 'inspect_original'
+  }
+  if (operation === 'task_coordinates') {
+    // Coordinates never dispatch. Preserve the shared feedback envelope while
+    // distinguishing local persistence from retryable read-only network probes.
+    dispatch = 'not_dispatched'
+    if (['SCOPE_STORE_UNAVAILABLE', 'SCOPE_STORE_CONFLICT'].includes(code)) { category = 'storage_error'; next = 'restore_scope' }
+    else if (['SESSION_LOCAL_STORAGE_ERROR', 'SESSION_RECOVERY_GAP'].includes(code)) { category = 'storage_error'; next = 'none' }
+    else if (['SESSION_SCOPE_CONFLICT', 'INVALID_SCOPE_SNAPSHOT'].includes(code)) { category = 'authorization_unavailable'; next = 'restore_scope' }
+    else if (code === 'INVALID_SESSION_ID') { category = 'invalid_request'; next = 'none' }
+    else if (['TASK_UNAVAILABLE', 'agent_runtime_unavailable', 'agent_invalid_response'].includes(code)) { category = 'transport_unavailable'; next = 'restore_scope' }
+    else if (error?.statusCode === 429 || error?.statusCode >= 500) { category = 'transport_unavailable'; next = 'restore_scope' }
+  }
+  return {
+    schema: 'bailing.agent-feedback.v1', category, code: missingOriginal ? 'invocation_not_found' : code,
+    origin: ORIGINS.has(context.origin) ? context.origin : ORIGINS.has(source?.origin) ? source.origin : 'dsh',
+    operation, dispatch,
+    retryable: ['rediscover', 'retry_discovery', 'restore_scope', 'resume_original', 'restore_invocations'].includes(next),
+    next_action: next,
+    ...(invocationId ? { invocation_id: invocationId } : {}),
+    ...(missingOriginal || source?.original_outcome === 'unverified' ? { original_outcome: 'unverified' } : {}),
+    ...(['accepted_unknown', 'definitive_rejection', 'refresh_required'].includes(source?.disposition ?? error?.disposition) ? { disposition: source?.disposition ?? error.disposition } : {}),
+    message: code.startsWith('TASK_STORE_') ? 'The local task association could not be saved or verified. Restore the original task binding before continuing; do not switch or create a replacement task.' : missingOriginal
+      ? 'The original invocation record was not found. Inspect its original execution evidence; this does not prove that the business action never ran. Do not recreate the call, switch authorization or submit a replacement write.'
+      : MESSAGES[category],
+  }
+}
+
+export function normalizeDiscovery(value, returnedCount) {
+  // Missing or malformed optional metadata must not disable an older Core/SDK.
+  const base = {
+    mode: 'unknown', scope: 'current_authorization', returned_count: returnedCount,
+    authorized_total: null, matched_total: null, matched_total_exact: false,
+    limit: null, truncated: null, has_more: null, truncation_scope: 'unknown', pagination: 'unsupported',
+  }
+  if (!value || value.mode !== 'ranked_candidates' || value.scope !== 'current_authorization' ||
+    value.returned_count !== returnedCount || !Number.isSafeInteger(value.authorized_total) || value.authorized_total < returnedCount ||
+    !Number.isSafeInteger(value.limit) || value.limit < 1 || value.limit > 12 || returnedCount > value.limit ||
+    value.matched_total !== null || value.matched_total_exact !== false || value.truncation_scope !== 'authorized_catalog' || value.pagination !== 'unsupported' ||
+    value.truncated !== (value.authorized_total > returnedCount) || value.has_more !== value.truncated) return base
+  return { ...base, mode: 'ranked_candidates', authorized_total: value.authorized_total, limit: value.limit,
+    truncated: value.truncated, has_more: value.has_more, truncation_scope: 'authorized_catalog' }
+}
+
+export const DISCOVERY_GUIDANCE = 'Capability search returns bounded ranked candidates, not an exhaustive matching list or pageable catalog. Search adds candidates to the current turn while the authorization catalog revision is unchanged; a changed revision resets that target’s cache. active_tools lists retained, directly callable tools (up to 64 shared); visible_tools is the smaller full-schema window (up to 12). Tools outside that window remain callable using their known exact schema and target. Only eviction, changed declarations or an ended turn require rediscovery. Use currently loaded, valid tools directly when the selected target is clear; search again only when needed. not_loaded means not yet loaded, not no capability. Never use discovery to replace an uncertain invocation.'

package/lib/conversation-outbox.js

@@ -117,6 +117,30 @@ export class ConversationOutbox {
     })
   }
 
+  // Host receipt actions may reopen before a model turn. Read only the original
+  // local outbox; do not create an archive, reconstruct text, flush or upload it.
+  restoreExisting(sessionId, value) {
+    const context = contextSnapshot(value)
+    let entry = this.entries.get(sessionId)
+    if (entry && digest(entry.context) !== digest(context)) throw fail('ARCHIVE_BINDING_CHANGED')
+    if (!entry) {
+      entry = { sessionId, context, pending: [], status: 'inactive' }
+      this.entries.set(sessionId, entry)
+    }
+    return this.serialize(entry, async () => {
+      try {
+        if (entry.status === 'storage_error') return this.status(sessionId)
+        if (!entry.record) {
+          const saved = await this.store.load(sessionId)
+          if (saved) entry.record = validateRecord(saved, sessionId, context)
+        }
+        entry.coverageLoaded = true
+        entry.status = entry.pending.length ? 'storage_error' : entry.record?.syncState ?? 'inactive'
+        return this.status(sessionId)
+      } catch (error) { entry.status = 'storage_error'; throw error }
+    })
+  }
+
   async save(entry, values) {
     const previous = entry.record
     const record = validateRecord({ ...previous, ...values, revision: previous.revision + 1 }, entry.sessionId, entry.context)

package/lib/index.js

@@ -1,6 +1,7 @@
 import Schema from '@deepseek-ai/schemastery'
 
 import { BailingHubAgentClientRuntime } from './runtime.js'
+import { createUsageModelTransport } from './usage-model-transport.js'
 import { createTransportProvider } from './transport.js'
 
 export const name = 'dsh-bailinghub'
@@ -33,9 +34,11 @@ export function createAgentClientPlugin(options = {}) {
         config,
         getTransport,
         options.recovery,
-        { scopeStore: options.scopeStore, archiveStore: options.archiveStore },
+        { scopeStore: options.scopeStore, archiveStore: options.archiveStore, artifactSource: options.artifactSource, artifactStore: options.artifactStore, invocationStore: options.invocationStore, taskStore: options.taskStore, toolLifecycle: options.toolLifecycle },
       ).install()
       ctx.provide('bailingHubAgentClient', runtime)
+      // Explicit host integration only; installing business tools does not intercept model traffic.
+      if (options.usage) ctx.provide('bailingHubUsage', createUsageModelTransport(options.usage))
     },
   }
 }
@@ -54,3 +57,15 @@ export {
   createLazySdkTransport,
   createTransportProvider,
 } from './transport.js'
+
+export { createFileArtifactStore, createMemoryArtifactStore } from './artifact-store.js'
+
+export { createFileInvocationStore, createMemoryInvocationStore } from './invocation-store.js'
+
+export { createFileSessionTaskStore, createMemorySessionTaskStore } from './session-task-store.js'
+
+export { BailingHubUsageModelTransport, createUsageModelTransport } from './usage-model-transport.js'
+export { usageLlmChunks } from './usage-llm-stream.js'
+export { createFileSessionUsageStore, createMemorySessionUsageStore } from './session-usage-store.js'
+
+export { usageNativeModelChunks } from './usage-provider-stream.js'