dsh-bailinghub 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.7.0 - 2026-09-23
+
+Optional host-orchestrated model gateway, USD plan presentation and asynchronous image tools.
+See [changes](docs/RELEASE_NOTES_v0.7.0.en.md) and [upgrade](docs/UPGRADE_v0.7.0.en.md).
+
 ## 0.6.0 - 2026-09-16
 
 See [scenarios and upgrade](docs/RELEASE_NOTES_v0.6.0.md) · [English](docs/RELEASE_NOTES_v0.6.0.en.md).

package/README.md

@@ -1,10 +1,10 @@
 # BailingHub for DeepSeek Harness
 
-## 0.6.0: longer tasks, attachments and original-call recovery
+## 0.7.0: optional model services and plan billing
 
-Retain the correct target while moving between edits and queries, reuse uploaded image URLs and inspect original calls after reopening. Task budgets survive turn changes. Pair Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0; host integration is required for task binding and opt-in cross-turn reuse.
+Keep orchestration local while Core relays model requests and meters shared allowance asynchronously. Discover chat models and image tools separately; preserve business authorization, approvals and audit. Pair Core 0.9.0 / SDK 0.7.0 / DSH 0.7.0.
 
-[Changes](docs/RELEASE_NOTES_v0.6.0.en.md) · [Upgrade](docs/UPGRADE_v0.6.0.en.md)
+[Changes](docs/RELEASE_NOTES_v0.7.0.en.md) · [Upgrade](docs/UPGRADE_v0.7.0.en.md)
 
 
 [简体中文](docs/README.zh-CN.md) | English
@@ -40,14 +40,14 @@ recommended by DeepSeek.
 
 You need Node.js `22.19.0+` or `24+`, pnpm, and a compatible DeepSeek Harness release. Your
 administrator must first connect the business system to BailingHub. The matched release set is
-**BailingHub Core 0.8.0 → BailingHub MCP/SDK 0.6.0 → this plugin 0.6.0**.
+**BailingHub Core 0.9.0 → BailingHub MCP/SDK 0.7.0 → this plugin 0.7.0**.
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.6.0
+dsh plugin --profile web add dsh-bailinghub@0.7.0
 ```
 
-The plugin installs its exact `bailinghub-mcp-server@0.6.0` dependency automatically.
+The plugin installs its exact `bailinghub-mcp-server@0.7.0` dependency automatically.
 For an existing installation, read the [migration steps from 0.4.0 and earlier](docs/MIGRATION_VNEXT.md).
 
 Follow the [getting started guide](docs/GETTING_STARTED.md) to enter your administrator's four

package/docs/COMPATIBILITY.md

@@ -1,6 +1,6 @@
-# Current 0.6.0 pairing
+# Current 0.7.0 pairing
 
-Use Core 0.8.0, SDK 0.6.0 and DSH 0.6.0 for attachments, original receipts and task controls. Existing unenrolled flows retain their earlier protocol minima. Task enrollment persists: older hosts cannot omit task binding. See [upgrade](UPGRADE_v0.6.0.en.md).
+Use Core 0.9.0, SDK 0.7.0 and DSH 0.7.0 for optional model plans and image tools. Existing business-governance APIs retain their documented minima. Host orchestration, scope, approval and audit rules remain in effect. See [upgrade](UPGRADE_v0.7.0.en.md).
 
 # Compatibility
 
@@ -10,23 +10,23 @@ The additive [capability feedback contract](CAPABILITY_FEEDBACK.md) requires the
 Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0 release set for complete counts and error detail. Older unenrolled combinations keep their existing business behavior with unknown optional metadata.
 
 
-## Native Agent Client 0.6.0
+## Native Agent Client 0.7.0
 
 | Component | Release pairing / requirement |
 | --- | --- |
 | DeepSeek Harness | `0.1.1-rc.2`; real Session and native Cordis lifecycle |
 | Node.js | `^22.19.0` or `>=24.0.0` |
 | DSH tool presentation | Native Tool Mode; Code Mode deliberately degraded |
-| Generic Agent Client SDK | Exact `bailinghub-mcp-server@0.6.0` via `./sdk` |
-| BailingHub Core | `bailinghub@0.8.0`, with outstanding migrations through 062 applied |
+| Generic Agent Client SDK | Exact `bailinghub-mcp-server@0.7.0` via `./sdk` |
+| BailingHub Core | `bailinghub@0.9.0`, with outstanding migrations through 064 applied |
 | Selected scope | Single account, same-system multiple accounts, or different Client Apps/workspaces on one Hub and audit domain |
 | Original authorization | A distinct original Agent Session for every selected target |
 | Persistence | Existing same-system v1 scope/outbox and cross-system v2 records |
 
-Install `dsh-bailinghub@0.6.0`; its ordinary dependency installs the exact SDK automatically.
+Install `dsh-bailinghub@0.7.0`; its ordinary dependency installs the exact SDK automatically.
 Core 0.6.1 and SDK/plugin 0.4.0 remain the historical same-system baseline, not an alternative
 pairing for new cross-system features. See the [upgrade steps](MIGRATION_VNEXT.md) and
-[release scenario](RELEASE_NOTES_v0.5.0.md).
+[release scenarios](RELEASE_NOTES_v0.7.0.en.md).
 
 ### Authorization subject display
 

package/docs/README.zh-CN.md

@@ -1,10 +1,10 @@
 # BailingHub for DeepSeek Harness
 
-## 0.6.0：长任务、附件与原调用恢复
+## 0.7.0：可选模型服务与套餐计费
 
-连续查询、编辑和核对时保留正确目标；上传获准图片后复用URL，重开后核对原调用，任务额度不因换轮重置。配套 Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0；任务启用和跨轮复用需宿主按契约接入。
+本地宿主继续编排，中枢提供模型转发、共享额度与异步计量。对话模型和图片工具分开下发；原业务权限、审批与审计保持。配套 Core 0.9.0 / SDK 0.7.0 / DSH 0.7.0。
 
-[本次变化](RELEASE_NOTES_v0.6.0.md) · [升级指南](UPGRADE_v0.6.0.md)
+[本次变化](RELEASE_NOTES_v0.7.0.md) · [升级指南](UPGRADE_v0.7.0.md)
 
 
 [English](../README.md) | 简体中文
@@ -35,14 +35,14 @@
 ## 安装与开始使用
 
 需要 Node.js `22.19.0+` 或 `24+`、pnpm，以及兼容的 DeepSeek Harness。管理员应先完成业务系统
-接入。配套版本为 **BailingHub Core 0.8.0 → BailingHub MCP/SDK 0.6.0 → 本插件 0.6.0**。
+接入。配套版本为 **BailingHub Core 0.9.0 → BailingHub MCP/SDK 0.7.0 → 本插件 0.7.0**。
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.6.0
+dsh plugin --profile web add dsh-bailinghub@0.7.0
 ```
 
-插件会自动安装精确依赖 `bailinghub-mcp-server@0.6.0`，无需另装 SDK。
+插件会自动安装精确依赖 `bailinghub-mcp-server@0.7.0`，无需另装 SDK。
 已经使用旧版的用户请先看[从 0.4.0 及更早版本升级的步骤](MIGRATION_VNEXT.md)。
 
 按照[开始使用指南](GETTING_STARTED.zh-CN.md)填写管理员提供的四项公开连接信息，再到浏览器授权。

package/docs/RELEASE_NOTES_v0.7.0.en.md

@@ -0,0 +1,15 @@
+# DSH 0.7.0: optional model services and shared plan billing
+
+Release pairing: Core 0.9.0, SDK 0.7.0 and DSH 0.7.0. The changes and integration impact below are relative to public 0.6.0.
+
+Local agents can use administrator-configured model plans and discover image generation as a model tool. Context, tool loops, subtasks and business orchestration stay in the host. Core relays model requests, checks allowance and meters usage asynchronously.
+
+- Separate `modelModels` and `modelTools` catalogs; bind requests to exact service IDs.
+- Preserve provider streaming and complete tool declarations through `stream`. Settlement does not hold usable results or impose user-turn/tool-loop limits.
+- Validate explicit `periodAllowanceUsd`; display server `presentation` as credits or percentage. Provider Token counts remain usage details, not a quota denominator.
+- Submit asynchronous `runModelTool` once and use `recoverOperation` with its original operation ID after ACK loss or restart. Distinguish pending, failed, uncertain and pending billing outcomes.
+- Preserve original identity, business authorization, approval, task, artifact and audit boundaries. Generating an image does not upload it to a business system.
+
+Executable image support follows the Core catalog. Video/audio declarations do not promise execution. Reference prices are not supplier invoices. Payments, orders and currency conversion belong to the product backend.
+
+See the [integration contract](USAGE_SERVICE.md) and [upgrade guide](UPGRADE_v0.7.0.en.md).

package/docs/RELEASE_NOTES_v0.7.0.md

@@ -0,0 +1,15 @@
+# DSH 0.7.0：可选模型服务与统一套餐计费
+
+版本配套：Core 0.9.0、SDK 0.7.0、DSH 0.7.0。以下为相对公开 0.6.0 的新增能力与接入影响。
+
+本地智能体可使用管理员配置的模型套餐，并将图片生成作为按需工具调用。上下文、工具循环、子任务和业务编排仍由本地宿主执行；中枢负责模型转发、额度检查及异步计量。
+
+- `modelModels` 与 `modelTools` 分离对话模型和可调用模型工具；使用服务标识绑定所选模型，不按名称猜测。
+- `stream` 保留供应商流式内容与工具声明，结算不阻塞可用结果；不增加用户轮次或工具循环上限。
+- `modelSummary` 严格读取周期额度 `periodAllowanceUsd`，用户展示继续消费服务端 `presentation`（积分或百分比），原始 Token 仅供用量明细。
+- `runModelTool` 异步受理生成；`recoverOperation` 按原 operation ID 查询，回包丢失不新建生成请求。明确失败、处理中、结果不确定和待计量分开处理。
+- 原业务授权、审批、任务控制、附件上传与审计约束保持；套餐不扩大业务权限。图片结果与上传到业务系统是两个独立动作。
+
+图片可执行适配以 Core 工具目录为准；视频与语音声明不等于已支持执行。参考价格不等于供应商实际账单。支付、订单、汇率由业务侧负责。
+
+参见[接入契约](USAGE_SERVICE.md)及[升级指南](UPGRADE_v0.7.0.md)。

package/docs/UPGRADE_v0.7.0.en.md

@@ -0,0 +1,15 @@
+# Upgrade to DSH 0.7.0
+
+Upgrade with the matched Core 0.9.0 / SDK 0.7.0 / DSH 0.7.0 release set. Existing public 0.6.0 business-governance integrations remain supported; managed model plans require explicit host integration.
+
+1. Back up and apply the Core 0.9.0 upgrade migrations. Enabling this optional module does not recreate business authorizations.
+2. Install exact paired packages. DSH 0.7.0 depends on SDK 0.7.0. Restart the host and verify its actual Profile resolution.
+3. Exchange a Usage credential through the trusted backend, preserving plan-wide or single-service scope. Provider keys stay in Core. Read capabilities, modelModels, modelTools and modelSummary; never substitute a default model or authorization for an empty catalog.
+4. Keep orchestration local, provide complete tool schemas, use transport.stream for plan models and runModelTool for generation. Persist the original operation ID before dispatch. Late responses cannot reactivate cancelled/ended turns or override storage failures.
+5. Verify streaming, image results, shared allowance and original-request recovery. A complete result is usable while billing is pending; do not reissue it or block unrelated new user messages for settlement.
+
+Display server presentation. Periodic allowance is grant.periodAllowanceUsd, not sale price, token totals or model count. Refresh summary after an administrator resets allowance; do not recreate accounts or credentials.
+
+Model billing is new relative to public 0.6.0 and provides no legacy Token-quota aliases. No history or account purge is required. Upgrading public Core 0.8.0 only adds outstanding 063/064 migrations; maintaining test configuration is not a real-customer upgrade step. Existing business Sessions and original invocation recovery remain unchanged.
+
+Respect callable=false for unsupported video/audio adapters. Inspect uncertain requests by original ID only. See the [contract](USAGE_SERVICE.md).

package/docs/UPGRADE_v0.7.0.md

@@ -0,0 +1,15 @@
+# DSH 0.7.0 升级
+
+使用 Core 0.9.0 / SDK 0.7.0 / DSH 0.7.0 配套升级。公开 0.6.0 的业务治理接入继续保持，可选模型套餐需宿主显式接入。
+
+1. 按 Core 0.9.0 升级指南完成备份和新增迁移。未启用套餐时不需要重建原业务授权。
+2. 安装精确配套包；DSH 0.7.0 固定依赖 SDK 0.7.0。重启宿主并核对实际 Profile 加载的版本，不能只检查开发目录。
+3. 可信业务后端签发使用凭据，明确套餐范围或单模型范围；供应商密钥保留在 Core。读取 capabilities、modelModels、modelTools、modelSummary。无可用项时显示配置原因，不回退到其他模型或授权。
+4. 宿主继续本地编排，将完整工具 schema 提供给模型；套餐使用 `stream`，生成工具使用 `runModelTool`。持久保存原 operation ID，取消/存储失败/已结束轮次不能被迟到结果重新启用。
+5. 核对文本流式、图片结果、同一套餐额度及原请求恢复。`result_state=complete` 即可使用结果，`billing_state=pending` 不要求重复请求或阻止下一条独立用户消息。
+
+额度显示直接读取 presentation；周期剩余按原 grant 的 periodAllowanceUsd，而非售价、Token 数或模型数量计算。后台手动重置后刷新摘要即可，无需重建账户或凭据。
+
+模型计费是相对公开 0.6.0 的新增模块，不提供旧 Token 额度接口别名，也不要求清退历史或账户。从公开 Core 0.8.0 升级仅应用新增 063/064 迁移；测试配置的维护不属于真实客户升级步骤。已有业务 Session 和原 invocation 恢复规则不变。
+
+视频/语音不含可执行适配时必须尊重 callable=false。断网或不确定请求只按原 ID 核对，不重新派发生成。详见[契约](USAGE_SERVICE.md)。

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/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'
@@ -36,6 +37,8 @@ export function createAgentClientPlugin(options = {}) {
         { 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))
     },
   }
 }
@@ -60,3 +63,9 @@ export { createFileArtifactStore, createMemoryArtifactStore } from './artifact-s
 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'

package/lib/invocation-journal.js

@@ -92,6 +92,11 @@ export class InvocationJournal {
     return result
   }
 
+  // Wait only for local work already queued. Do not read, retry or restore records.
+  async drain(sessionId) {
+    await this.queues.get(sessionId)
+  }
+
   normalizeFailure(error, id) {
     return error?.feedback ? error : recoveryError(error?.code === 'INVOCATION_STORE_CONFLICT'
       ? 'invocation_store_conflict' : 'invocation_store_unavailable', id)

package/lib/model-gateway-transport.js

@@ -0,0 +1,246 @@
+import { randomUUID } from 'node:crypto'
+
+export const MODEL_REQUEST_EVENT = 'bailinghub/model-request'
+const CLOSED_EVENT = 'bailinghub/model-request-group-ended'
+const SCHEMA = 'bailing.usage-session.v1'
+const META_SCHEMA = 'bailing.model-request.v1'
+const REQUIRED = ['modelModels', 'modelSummary', 'modelComplete', 'modelStream', 'inspectModelRequest', 'cancelModelRequest']
+const clone = value => structuredClone(value)
+
+/** Request-sized sidecars prevent a long task from consuming a session-wide metadata budget.
+ * The real durable Session is the original request index. No transcript or credential is copied.
+ */
+export class ModelGatewayTransport {
+  constructor(host, helpers) { this.host = host; Object.assign(this, helpers) }
+  assertSupported() {
+    if (REQUIRED.some(name => typeof this.host.client?.[name] !== 'function')) throw this.failure('USAGE_UNSUPPORTED')
+  }
+  markers(session) { return session.events.filter(e => e.type === MODEL_REQUEST_EVENT) }
+  locate(session, id) {
+    const found = this.markers(session).filter(e => e.data?.operationId === id)
+    if (found.length !== 1) throw this.failure('USAGE_RECOVERY_GAP')
+    return found[0].data
+  }
+  key(session, id) { return `model:${this.hash(session.id)}:${id}` }
+  async load(session, meta) {
+    const owner = this.eventFor(session, meta.turnId)
+    if (meta.schema !== META_SCHEMA || meta.conversationId !== session.id || meta.eventSeq !== owner.seq
+      || meta.eventHash !== this.hash(owner.data) || this.hash(meta.binding) !== this.hash(this.host.assertSupported())) throw this.failure('USAGE_RECOVERY_GAP')
+    let record
+    try { record = await this.host.store.load(this.key(session, meta.operationId)) } catch { throw this.failure('USAGE_STORAGE_ERROR') }
+    if (!record || record.schema !== SCHEMA || record.entries?.length !== 1
+      || this.hash(record.entries[0].request?.metadata) !== this.hash(meta)) throw this.failure('USAGE_RECOVERY_GAP')
+    return record
+  }
+  async save(session, record) {
+    const previous = record.revision; record.revision++
+    try { await this.host.store.save(record.sessionId, clone(record), previous || null) }
+    catch { this.host.storageFailures.add(session.id); throw this.failure('USAGE_STORAGE_ERROR') }
+  }
+  closed(session, meta) {
+    return this.host.cancelled.has(`${session.id}:${meta.turnId}`) || this.host.ended.has(`${session.id}:${meta.turnId}`)
+      || session.events.some(e => e.type === CLOSED_EVENT && e.data?.id === meta.turnId)
+      || !this.isLiveMessage(session, this.eventFor(session, meta.turnId))
+  }
+  async model(options = {}) {
+    this.assertSupported()
+    const key = options.serviceId ?? this.host.client.binding.serviceId
+    const cached = this.host.modelModelsCache
+    const hit = !options.refresh && cached?.until > Date.now()
+    const models = hit ? cached.value : await this.host.client.modelModels(options)
+    // Cache hits do not extend the freshness deadline; live plan edits must become visible.
+    if (!hit) this.host.modelModelsCache = { value: clone(models), until: Date.now() + 60_000 }
+    const model = models.items.find(item => item.service_id === key)
+    if (!model) throw this.failure('SERVICE_NOT_ENTITLED', { feedback: { schema: 'bailing.usage-feedback.v1', code: 'SERVICE_NOT_ENTITLED', dispatch: 'not_dispatched', next_action: 'select_model', retryable: false } })
+    return clone(model)
+  }
+  async complete(session, input, options = {}, modelTool = false) {
+    this.assertSupported()
+    let copied
+    try { copied = clone(input) } catch { throw this.failure('USAGE_INPUT_INVALID') }
+    if (!copied || typeof copied !== 'object' || Array.isArray(copied)
+      || Object.keys(copied).some(key => !['userMessageId', 'modelRequestId', 'serviceId', 'requestGroupId', 'requestKind',
+        ...(modelTool ? ['arguments'] : ['messages', 'tools', 'tool_choice', 'temperature', 'provider_options'])].includes(key))) throw this.failure('USAGE_INPUT_INVALID')
+    const prepared = await this.host.serial(session, async () => {
+      await this.host.durable(session)
+      const binding = this.host.assertSupported()
+      if (this.markers(session).some(marker => this.hash(marker.data?.binding) !== this.hash(binding))) throw this.failure('USAGE_BINDING_MISMATCH')
+      const event = this.eventFor(session, copied.userMessageId), requestKey = this.exact(copied.modelRequestId)
+      const serviceId = this.exact(copied.serviceId ?? this.host.client.binding.serviceId)
+      const request = Object.fromEntries((modelTool ? ['arguments'] : ['messages', 'tools', 'tool_choice', 'temperature', 'provider_options'])
+        .filter(key => copied[key] !== undefined).map(key => [key, copied[key]]))
+      if (modelTool ? !request.arguments || typeof request.arguments !== 'object' || Array.isArray(request.arguments)
+        : !Array.isArray(request.messages) || !request.messages.length) throw this.failure('USAGE_INPUT_INVALID')
+      const requestHash = this.hash({ serviceId, kind: modelTool ? 'tool' : 'chat', ...request })
+      const existing = this.markers(session).filter(item => item.data?.turnId === copied.userMessageId && item.data?.requestKey === requestKey)
+      if (existing.length > 1) throw this.failure('USAGE_RECOVERY_GAP')
+      if (existing.length) {
+        const meta = existing[0].data
+        if (meta.requestHash !== requestHash || meta.serviceId !== serviceId) throw this.failure('USAGE_IDEMPOTENCY_CONFLICT')
+        return { receipt: await this.inspect(session, meta, options) }
+      }
+      if (this.host.cancelled.has(`${session.id}:${copied.userMessageId}`)) throw this.failure('USAGE_CANCELLED')
+      this.signalActive(options.signal)
+      if (this.host.ended.has(`${session.id}:${copied.userMessageId}`) || !this.isLiveMessage(session, event) || session.events.some(e => e.type === CLOSED_EVENT && e.data?.id === copied.userMessageId)) throw this.failure('USAGE_TURN_ENDED')
+      // Preserve the original user/account/service credential binding alongside the selected model.
+      // The server remains authoritative for its current plan and credential scope.
+      if (modelTool) {
+        const directory = await this.host.client.modelTools(options)
+        const tool = directory.items.find(item => item.service_id === serviceId)
+        if (!tool) throw this.failure('SERVICE_NOT_ENTITLED')
+        if (!tool.callable) throw this.failure('USAGE_MODEL_TOOL_UNAVAILABLE')
+      }
+      const meta = { schema: META_SCHEMA, kind: modelTool ? 'tool' : 'chat', operationId: randomUUID(), requestKey, requestHash,
+        binding: clone(this.host.assertSupported()), serviceId, conversationId: this.exact(session.id),
+        turnId: copied.userMessageId, eventSeq: event.seq, eventHash: this.hash(event.data) }
+      const record = { schema: SCHEMA, sessionId: this.key(session, meta.operationId), revision: 0,
+        entries: [{ request: { metadata: meta, state: 'prepared' } }] }
+      await this.save(session, record)
+      if (typeof session.append !== 'function') throw this.failure('USAGE_RECOVERY_GAP')
+      session.append(MODEL_REQUEST_EVENT, meta)
+      await this.host.durable(session)
+      if (options.signal?.aborted || this.closed(session, meta)) {
+        record.entries[0].request.state = 'rejected'
+        await this.save(session, record)
+        throw this.afterFailure(this.failure(options.signal?.aborted ? 'USAGE_CANCELLED' : 'USAGE_TURN_ENDED'), meta, 'not_dispatched')
+      }
+      return { meta, request }
+    })
+    if (prepared.receipt) return prepared.receipt
+    const { meta, request } = prepared
+    const wire = { ...request, operation_id: meta.operationId, service_id: meta.serviceId,
+      conversation_id: meta.conversationId, turn_id: meta.turnId }
+    let result, receivedFrame = false
+    try {
+      await this.host.primary(session); this.signalActive(options.signal)
+      if (this.closed(session, meta)) throw this.failure('USAGE_TURN_ENDED')
+      if (modelTool) result = await this.host.client.runModelTool(wire, options)
+      else if (options.onDelta) {
+        for await (const frame of this.host.client.modelStream(wire, options)) {
+          receivedFrame = true
+          if (frame.type === 'operation') result = frame.operation
+          else if (['delta', 'provider'].includes(frame.type) && !options.signal?.aborted && !this.closed(session, meta)) {
+            await this.host.primary(session)
+            await options.onDelta({ ...frame, preview: true, executable: false })
+          }
+        }
+        if (!result) throw this.failure('USAGE_STREAM_INCOMPLETE', { feedback: { schema: 'bailing.usage-feedback.v1', code: 'USAGE_STREAM_INCOMPLETE', dispatch: 'unknown', next_action: 'inspect_original', retryable: true } })
+      } else result = await this.host.client.modelComplete(wire, options)
+    } catch (error) {
+      if (receivedFrame && error?.feedback) error.feedback = { ...error.feedback, dispatch: 'unknown', next_action: 'inspect_original' }
+      if (['USAGE_INPUT_LIMIT', 'USAGE_UNSUPPORTED', 'SERVICE_NOT_ENTITLED'].includes(error?.code)) this.host.modelModelsCache = null
+      try {
+        await this.update(session, meta, item => { item.state = error?.feedback?.dispatch === 'not_dispatched' ? 'rejected' : 'unknown' })
+        await this.host.primary(session)
+      } catch (primary) { throw this.afterFailure(primary, meta) }
+      throw this.afterFailure(error?.feedback ? error : this.failure('USAGE_TRANSPORT_UNAVAILABLE'), meta, error?.feedback?.dispatch)
+    }
+    try {
+      this.check(result, meta)
+      await this.update(session, meta, item => { item.state = this.state(result) })
+      await this.host.primary(session)
+    } catch (error) { throw this.afterFailure(error, meta) }
+    return this.delivery(session, meta, result, Boolean(options.signal?.aborted))
+  }
+  afterFailure(error, meta, dispatch = 'unknown') {
+    return Object.assign(error, { operationId: meta.operationId, turnId: meta.turnId,
+      feedback: { ...error.feedback, dispatch, ...(dispatch === 'unknown' ? { next_action: 'inspect_original' } : {}) } })
+  }
+  check(result, meta) {
+    if (result?.schema !== 'bailing.model-operation.v1' || result.operation_id !== meta.operationId
+      || result.account_id !== meta.binding.accountId || result.user_id !== meta.binding.userId
+      || result.service_id !== meta.serviceId || result.conversation_id !== meta.conversationId || result.turn_id !== meta.turnId
+      || !['pending', 'complete', 'unknown', 'cancelled', 'failed'].includes(result.result_state)
+      || !['pending', 'settled'].includes(result.billing_state)) throw this.failure('USAGE_RECOVERY_GAP')
+  }
+  state(result) { return result.response_expired === true ? 'closed_unresolved' : result.result_state === 'complete' ? 'completed' : result.result_state === 'cancelled' ? 'cancelled' : result.result_state === 'failed' ? 'rejected' : 'unknown' }
+  delivery(session, meta, result, aborted = false) {
+    const closed = aborted || this.closed(session, meta), ready = result.result_state === 'complete' && result.response && typeof result.response === 'object'
+    return { ...result, host_turn_active: Boolean(!closed && ready),
+      delivery_state: closed ? 'cancelled_late_result' : ready ? 'response_ready' : result.result_state === 'failed' ? 'request_failed' : result.response_expired === true || result.result_state === 'unknown' ? 'unresolved_original' : 'pending_original',
+      ...(closed ? { next_action: 'inspect_original' } : result.response_expired === true ? { next_action: 'contact_operator' } : {}) }
+  }
+  async update(session, meta, update) {
+    return this.host.serial(session, async () => {
+      await this.host.primary(session)
+      const record = await this.load(session, meta)
+      update(record.entries[0].request)
+      await this.save(session, record)
+    })
+  }
+  async inspect(session, meta, options = {}) {
+    const record = await this.load(session, meta)
+    const result = await this.host.client.inspectModelRequest(meta.operationId, { ...options, serviceId: meta.serviceId, conversationId: meta.conversationId, turnId: meta.turnId })
+    this.check(result, meta)
+    record.entries[0].request.state = this.state(result)
+    await this.save(session, record)
+    await this.host.primary(session)
+    return { ...this.delivery(session, meta, result), recovered_original: true }
+  }
+  async recover(session, operationId, options = {}) {
+    this.assertSupported()
+    return this.host.serial(session, async () => {
+      await this.host.durable(session)
+      return this.inspect(session, this.locate(session, operationId), options)
+    })
+  }
+  async close(session, userMessageId, cancelled, options = {}) {
+    const id = this.exact(userMessageId)
+    ;(cancelled ? this.host.cancelled : this.host.ended).add(`${session.id}:${id}`)
+    return this.host.serial(session, async () => {
+      await this.host.primary(session)
+      this.eventFor(session, id)
+      if (!session.events.some(e => e.type === CLOSED_EVENT && e.data?.id === id)) {
+        session.append(CLOSED_EVENT, { id, cancelled: Boolean(cancelled) })
+        await this.host.durable(session)
+      }
+      const results = []
+      for (const marker of this.markers(session).filter(e => e.data?.turnId === id)) {
+        const meta = marker.data, record = await this.load(session, meta)
+        if (cancelled && !['completed', 'rejected', 'cancelled'].includes(record.entries[0].request.state)) {
+          // Original request cancellation only. No turn exists and no model operation is replayed.
+          const result = await this.host.client.cancelModelRequest(meta.operationId,
+            { ...options, serviceId: meta.serviceId, conversationId: meta.conversationId, turnId: meta.turnId })
+          this.check(result, meta); results.push(result)
+          record.entries[0].request.state = this.state(result)
+          await this.save(session, record)
+        }
+      }
+      return { state: cancelled ? 'cancelled' : 'ended', requests: results, model_operation_performed: false }
+    })
+  }
+  async status(session, options = {}) {
+    const pending = []
+    for (const marker of this.markers(session)) {
+      const record = await this.load(session, marker.data)
+      if (['prepared', 'unknown'].includes(record.entries[0].request.state)) pending.push(marker.data.operationId)
+    }
+    let summary
+    try { summary = await this.host.client.modelSummary(options) }
+    catch (error) { await this.host.primary(session); throw error }
+    await this.host.primary(session)
+    const presentation = summary?.presentation
+    // Hosts may provide a custom client. Never hand an old/raw summary to a customer UI.
+    if (presentation?.schema !== 'bailing.usage-presentation.v1'
+      || !['credits', 'percentage', 'none'].includes(presentation.kind)
+      || !['active', 'depleted', 'not_started', 'expired', 'suspended', 'unavailable'].includes(presentation.state)
+      || !['remaining', 'total'].every(key => presentation[key] === null || typeof presentation[key] === 'number' && Number.isFinite(presentation[key]) && presentation[key] >= 0)
+      || !(presentation.displayValue === null || typeof presentation.displayValue === 'string' && /^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,2})?$|^<(?:1|0\.01)$/.test(presentation.displayValue))) throw this.failure('USAGE_RESPONSE_INVALID')
+    const usable = ['active', 'depleted'].includes(presentation.state)
+    if (presentation.kind === 'none') {
+      if (presentation.state !== 'unavailable' || presentation.remaining !== null || presentation.total !== null || presentation.displayValue !== null) throw this.failure('USAGE_RESPONSE_INVALID')
+    } else if (!usable) {
+      if (!['not_started', 'expired', 'suspended'].includes(presentation.state) || presentation.remaining !== null || presentation.displayValue !== null) throw this.failure('USAGE_RESPONSE_INVALID')
+    } else {
+      if (presentation.remaining === null || presentation.total === null || presentation.displayValue === null
+        || presentation.state === 'active' && presentation.remaining <= 0
+        || presentation.state === 'depleted' && (presentation.remaining !== 0 || presentation.displayValue !== '0')) throw this.failure('USAGE_RESPONSE_INVALID')
+      if (presentation.kind === 'percentage') {
+        if (presentation.total !== 100 || presentation.remaining > 100 || !/^(?:0|[1-9][0-9]?|100|<1)$/.test(presentation.displayValue)) throw this.failure('USAGE_RESPONSE_INVALID')
+      } else if (presentation.displayValue === '<1') throw this.failure('USAGE_RESPONSE_INVALID')
+    }
+    return { schema: 'bailing.usage-host-status.v1', state: 'ready', binding: clone(this.host.assertSupported()),
+      mode: 'model_gateway', summary: clone(summary), pendingOperations: pending,
+      model_transport_required: true, byok_metered: false, turn_required: false }
+  }
+}

package/lib/runtime.js

@@ -1014,6 +1014,30 @@ export class BailingHubAgentClientRuntime {
     return this.sessionTasks.set(id, request)
   }
 
+  /** Synchronous snapshot; queued local writes can still be pending. */
+  getSessionLocalPrimaryStatus(session) {
+    if (!session || typeof session.id !== 'string' || !session.id.trim() || session.id.length > 512
+      || /[\u0000-\u001f\u007f]/.test(session.id) || !Array.isArray(session.events)) {
+      throw new TypeError('A real Session with its current events is required')
+    }
+    const view = this.sessionTaskView(session.id, session)
+    return { schema: 'bailing.agent-session-local-primary.v1',
+      state: ['storage_error', 'recovery_gap'].includes(view.state) ? view.state : 'ready',
+      local: { ...view.local }, snapshot_is_dispatch_permission: false }
+  }
+
+  /** Settle already queued local persistence before checking the primary error. */
+  async waitForSessionLocalPrimaryStatus(session) {
+    this.getSessionLocalPrimaryStatus(session) // Validate before touching queues.
+    await Promise.all([
+      this.conversationOutbox.drain(session.id),
+      this.invocationJournal.drain(session.id),
+    ])
+    // Task queues also contain remote validation; never wait for them here.
+    // Failed saves retain their original pending records and error status.
+    return this.getSessionLocalPrimaryStatus(session)
+  }
+
   async getSessionTaskState(session) {
     const id = typeof session === 'string' ? session : String(session.id)
     await this.sessionTasks.refresh(id)