dsh-bailinghub 0.6.0 → 0.8.0

package/docs/SESSION_TOOL_REUSE.md

@@ -87,6 +87,32 @@ If a ready tool's full schema is outside the presentation window, use the exact
 come from local cache, while normal scope validation may still make requests.
 The model must not guess fields or rely on an old schema that it cannot inspect.
 
+Short descriptions and usage guidance have separate purposes. A tool can report
+`description_truncated=true` or `usage_guidance_available=true`. Read the indicated
+detail explicitly before relying on omitted instructions:
+
+```json
+{
+  "query": "Read the known decoration tool's prerequisites.",
+  "tool_name": "shop_ai_decoration_save",
+  "include_usage_guidance": true,
+  "authorization_ref": "the-original-selected-authorization"
+}
+```
+
+`include_usage_guidance` requires `tool_name`; multi-target sessions also select
+one authorization. The same parameters are supported in `active_turn` mode.
+Only this named tool's guidance is fetched, under the current authorization and
+capability revision. Its `usage_guidance` result contains the original name,
+authorization reference where applicable, revision, text, and honest character/
+UTF-8 byte bounds (`max_chars=32768`, `max_bytes=65536`, with `truncated` and source
+sizes). A truncated detail is not a complete instruction document. The text is
+reference evidence, never permission to switch target, bypass approval or execute
+unvalidated arguments. Detail reads create no invocation, approval or business
+operation. Unsupported older SDKs return compatibility feedback; missing support
+does not mean that the business capability is absent. Hosts must preserve this
+field and its bounds instead of treating the short description as full guidance.
+
 An exact valid cache hit avoids an additional `searchCapabilities` request. The
 first preparation of a target still calls `startTurn` for current context; Core
 may perform its existing bounded internal discovery there. This is reduced
@@ -126,6 +152,30 @@ prepares that exact target and declaration, then returns context and schema with
 business arguments. The model must read the result and decide on a new tool call
 using the current instructions and schema.
 
+Session preparation now has an explicit additive envelope:
+
+```json
+{
+  "schema": "bailing.agent-capability-preparation.v1",
+  "result_type": "capability_preparation",
+  "dispatch": "not_dispatched",
+  "reason": "target_not_prepared",
+  "next_action": "review_context_then_call",
+  "preparation": { "state": "ready", "business_operation_performed": false },
+  "business_operation_performed": false
+}
+```
+
+Normal discovery uses `reason=capability_search`. A ready target with no returned
+requested schema says `next_action=refine_capability_search`; it does not advise
+calling the missing tool. An unavailable preparation carries its safe feedback's
+next action (or `review_preparation_feedback` for mixed outcomes). Preparation
+creates no `invocation_id`. The existing context, schemas, target state and both
+false flags remain compatible. Business invocation success keeps its existing
+receipt shape. Active-turn search also adds `result_type`, `dispatch`, `reason`,
+`next_action` and `business_operation_performed=false`, while preserving its
+existing search schema and result fields.
+
 The original guard call ID stays attached to preparation. Replaying that same
 call ID returns its preparation result, rather than turning the old attempt into
 a write after preparation finishes. A later business call needs its own genuine

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/UPGRADE_v0.8.0.en.md

@@ -0,0 +1,22 @@
+# Upgrade to DSH 0.8.0
+
+Pair Core 0.10.0, SDK 0.8.0 and DSH 0.8.0. Node.js remains `^22.19.0 || >=24.0.0`; the exercised Harness line remains `0.1.1-rc.2`. The four public configuration fields are unchanged.
+
+1. Back up and upgrade Core first, applying only its outstanding migrations. The plugin does not migrate the Hub database.
+2. Checkpoint active tasks and preserve pending original operations/approvals, credentials, Sessions, scope/task/invocation stores and archives. Never reconstruct an unknown business action.
+3. Install `dsh plugin --profile web add dsh-bailinghub@0.8.0`. It must resolve exact `bailinghub-mcp-server@0.8.0` automatically; do not substitute an optional peer, local path or another SDK version.
+4. Restart and verify the actual Profile and loaded modules. Run `/bailinghub doctor` and `/bailinghub status` without printing credentials. Retain explicit authorization scope and business rules.
+
+## Host integration
+
+- Session tool reuse still requires explicit `toolLifecycle:'session'`. Calling an unprepared tool returns preparation only. Read the current context and complete schema before a new decision; never turn replay of the old call ID into execution.
+- Current authorized protocol negotiation enables on-demand knowledge. Pin the original turn mode and use `search_business_knowledge` / `read_business_knowledge`, retaining ref, run, authorization_ref and pagination/truncation facts. Unknown protocols retain inline knowledge; service/auth failures cannot silently discard it. See [the knowledge protocol](AGENT_KNOWLEDGE.md).
+- Integrate context confirmation only when the host can observe every final provider request and confirm its current named contributions. Keep inline bodies without confirmation. If a later request is missing context, reassemble/reconfirm or stop; never replay business calls to repair prompts. See [the host contract](CONTEXT_DELIVERY.md).
+- Model descriptors pass through unchanged. Hosts may use SDK `resolveModelOutputBudget()` and `modelOutputOptions()` to separate defaults/ceilings, output keys and scope. Apply them to new requests only; existing operation/intent/hash remain unchanged.
+- Automatic continuation needs a separate host implementation with final original receipts, checkpoints, bounded budgets, cancellation, approval and effect deduplication. Inspect missing final receipts with `inspectModelRequest()`; inspect business receipts with `inspectInvocation()`. `resume()` can first-dispatch an approved original and is not polling.
+
+## Acceptance and fallback
+
+Use an isolated Profile for single-plugin installation, one exact SDK resolution, normal tools, preparation without dispatch, knowledge search/pagination, authorization isolation, cancel/revoke and original recovery. Context confirmation requires checking final request contents. Each host separately accepts its real UI and long tasks.
+
+The immutable Client Token 0.1.1 static path remains independent. Package rollback does not roll back Hub data or rewrite saved operations. Preserve new records and do not continue Sessions in an old host that lacks their task/recovery formats. Audit the actual installing host separately.

package/docs/UPGRADE_v0.8.0.md

@@ -0,0 +1,22 @@
+# 升级到 DSH 0.8.0
+
+配套 Core 0.10.0、SDK 0.8.0 与 DSH 0.8.0。Node.js 保持 `^22.19.0 || >=24.0.0`，Harness 配套保持 `0.1.1-rc.2`，原四项公开配置不变。
+
+1. 管理员先备份并升级 Core，仅执行其尚未完成的迁移；插件不迁移中枢数据库。
+2. 保存当前任务检查点、原待决操作和审批；保留凭据、Session、scope、task、invocation 及归档存储。不要重建原未知业务动作。
+3. 安装 `dsh plugin --profile web add dsh-bailinghub@0.8.0`。插件必须自动解析精确 `bailinghub-mcp-server@0.8.0`；不使用 optional peer、本地路径或另一个 SDK 版本替代。
+4. 重启并核对实际 Profile 和已加载模块。先运行 `/bailinghub doctor`、`/bailinghub status`，不输出凭据。保持原显式授权范围和业务规则。
+
+## 宿主接入
+
+- 会话工具复用仍显式启用 `toolLifecycle:'session'`。直接调用未准备工具只返回准备信息；读取其当前上下文与完整 schema 后再作新决策，不能把旧 callId 自动重放成执行。
+- 按需知识由当前授权下的协议协商开启。固定原 turn 模式，使用 `search_business_knowledge`、`read_business_knowledge`；保留原 ref、run、authorization_ref 与分页/截断事实。未知协议保留旧 inline；服务和授权错误不能默默删掉知识。[知识协议](AGENT_KNOWLEDGE.md)
+- 只有宿主能观察每一份最终 provider 请求并确认当前命名上下文时，才接入上下文确认。未经确认保留 inline；确认后若下一请求缺少上下文，应重新组装/确认或停止，不重复业务调用。[宿主确认契约](CONTEXT_DELIVERY.md)
+- 模型目录保持原样透传。宿主可使用 SDK `resolveModelOutputBudget()`、`modelOutputOptions()` 区分默认与服务上限、输出字段和 scope；只用于新请求，旧 operation/intent/hash 不变。
+- 自动续跑需要宿主独立实现：最终原回执、检查点、有限预算、取消、审批和副作用防重。缺最终回执先 `inspectModelRequest()`；业务核对用 `inspectInvocation()`，`resume()` 可能首次派发原已批准调用，不能当轮询。
+
+## 验收与回退
+
+先在隔离 Profile 检查单插件安装、SDK 唯一解析、普通工具执行、准备不派发、知识搜索/分页、多授权隔离、取消/撤权及原操作恢复。上下文确认需核最终请求内容；不同宿主的真实 UI 与长任务仍分别验收。
+
+旧 Client Token 0.1.1 静态路径独立保留，不改历史配置。回退包不回滚中枢数据，也不改写已保存原操作；保留新记录，不能把需要新任务/恢复格式的会话交给不支持的旧宿主继续执行。依赖审计按实际安装宿主另行核对。

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.
+
+The current release pairs Core 0.10.0, SDK 0.8.0 and DSH 0.8.0. It has no legacy Token-allowance aliases, silent billing fallback, balance conversion or automatic BYOK substitution. The optional gateway first shipped with Core 0.9.0 and SDK/DSH 0.7.0; its original upgrade from Core 0.8.0 required outstanding migrations 063/064. For the current release, follow the Core upgrade guide and apply only outstanding migrations while retaining 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/capability-feedback.js

@@ -1,8 +1,8 @@
 // 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 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', 'knowledge_reference_unavailable'])
+const ACTIONS = new Set(['rediscover', 'retry_discovery', 'restore_scope', 'reauthorize', 'check_compatibility', 'resume_original', 'inspect_original', 'restore_invocations', 'restore_task', 'inspect_task', 'search_knowledge', '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',
@@ -19,6 +19,7 @@ const CODES = new Set([
   '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',
+  'knowledge_unavailable', 'knowledge_reference_invalid', 'knowledge_reference_expired', 'knowledge_changed', 'knowledge_scope_changed',
 
   'agent_invalid_request', 'unauthorized', 'forbidden', 'agent_tool_internal_error',
   'BAILINGHUB_ACCEPTED_UNKNOWN', 'BAILINGHUB_AGENT_CLIENT_UNAVAILABLE',
@@ -41,6 +42,7 @@ const MESSAGES = {
   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.',
+  knowledge_reference_unavailable: 'The original knowledge reference is invalid, expired or changed. Search knowledge again under the same authorization; never replay a business operation.',
 }
 
 // A generic 404 or error message cannot establish that Core looked up the
@@ -49,6 +51,19 @@ export function isInvocationNotFound(error) {
   return error?.publicCode === 'invocation_not_found' && error?.statusCode === 404
 }
 
+function publicSizeDetails(error, source, code) {
+  if (code !== 'arguments_too_large') return {}
+  const details = error?.details
+  const projected = {}
+  const scope = source?.limit_scope ?? details?.limitScope ?? details?.limit_scope
+  if (['arguments', 'request_body'].includes(scope)) projected.limit_scope = scope
+  for (const [wire, field] of [['actual_bytes', 'actualBytes'], ['max_bytes', 'maxBytes'], ['observed_bytes', 'observedBytes']]) {
+    const value = source?.[wire] ?? details?.[field] ?? details?.[wire]
+    if (Number.isSafeInteger(value) && value >= 0) projected[wire] = value
+  }
+  return projected
+}
+
 export function describeFailure(error, context = {}) {
   const source = error?.feedback?.schema === 'bailing.agent-feedback.v1' ? error.feedback : undefined
   const operation = context.operation ?? 'tool_dispatch'
@@ -68,7 +83,8 @@ export function describeFailure(error, context = {}) {
     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 (['knowledge_reference_invalid', 'knowledge_reference_expired', 'knowledge_changed', 'knowledge_scope_changed'].includes(code)) { category = 'knowledge_reference_unavailable'; next = 'search_knowledge' }
+    else if (['agent_transport_unavailable', 'agent_request_timeout', 'knowledge_unavailable'].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' }
@@ -106,19 +122,24 @@ export function describeFailure(error, context = {}) {
   }
   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',
+    origin: ORIGINS.has(context.origin) ? context.origin : ORIGINS.has(source?.origin) ? source.origin
+      : code === 'arguments_too_large' && error?.details?.origin === 'core' ? 'core'
+        : code === 'arguments_too_large' && error?.details?.origin === 'client' ? 'sdk' : '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 } : {}),
+    ...publicSizeDetails(error, source, code),
     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 const BUSINESS_EXECUTION_GUIDANCE = 'Use a loaded tool directly when its current target and declaration are clear. If rate limited before dispatch, wait for retry_after_ms then resume the original invocation_id. Recover pending or uncertain operations only with their original invocation_id; never create a replacement call or repeat a write with a different authorization. inspect_original means stop automatic retries and inspect the original outcome.'
+
 export function normalizeDiscovery(value, returnedCount) {
   // Missing or malformed optional metadata must not disable an older Core/SDK.
   const base = {

package/lib/context-delivery.js

@@ -0,0 +1,135 @@
+import { createHash, randomBytes } from 'node:crypto'
+
+const ID = /^[0-9a-f]{64}$/u
+const REQUEST = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u
+const MAX_FRAGMENTS = 256
+const MAX_CONFIRM_BYTES = 4 * 1024 * 1024
+const TTL_MS = 60_000
+const digest = value => createHash('sha256').update(value).digest('hex')
+export const contextDigest = value => digest(JSON.stringify(value ?? null))
+const bytes = value => Buffer.byteLength(value, 'utf8')
+const copy = value => structuredClone(value)
+const key = value => `${value.kind}:${value.name}`
+const record = value => value && typeof value === 'object' && !Array.isArray(value)
+
+/** Local, presentation-only confirmation. Never grants business permission. */
+export class ContextDeliveryCoordinator {
+  constructor({ now = Date.now } = {}) {
+    this.now = now
+    this.entries = new Map()
+  }
+
+  stage(sessionId, binding, fragments) {
+    const previous = this.entries.get(sessionId)
+    const generation = (previous?.generation ?? 0) + 1
+    if (!binding || !fragments.length || fragments.length > MAX_FRAGMENTS) {
+      this.entries.set(sessionId, { generation, reason: 'context_unavailable' })
+      return
+    }
+    const required = fragments.map(fragment => ({ kind: fragment.kind, name: fragment.name,
+      sha256: digest(fragment.text), bytes: bytes(fragment.text) }))
+    this.entries.set(sessionId, { generation, binding: contextDigest(binding),
+      targets: copy(binding.targets), turn: binding.turn, context_revision: binding.context_revision,
+      delivery_id: randomBytes(32).toString('hex'), expires_at: this.now() + TTL_MS,
+      fragments: required, confirmed: undefined })
+  }
+
+  current(sessionId, binding) {
+    const entry = this.entries.get(sessionId)
+    if (!entry?.delivery_id) return { reason: entry?.reason ?? 'host_unconfirmed' }
+    if (entry.invalidated) return { reason: entry.invalidated }
+    if (!binding || entry.binding !== contextDigest(binding)) {
+      entry.confirmed = undefined; entry.invalidated = 'binding_changed'
+      return { reason: 'binding_changed' }
+    }
+    if (entry.expires_at <= this.now()) {
+      entry.confirmed = undefined; entry.invalidated = 'expired'
+      return { reason: 'expired' }
+    }
+    return { entry }
+  }
+
+  manifest(sessionId, binding) {
+    const { entry, reason } = this.current(sessionId, binding)
+    if (!entry) return { schema: 'bailing.agent-context-delivery-manifest.v1', state: 'unavailable', reason }
+    return { schema: 'bailing.agent-context-delivery-manifest.v1', state: 'available', mode: 'named_runtime',
+      delivery_id: entry.delivery_id, generation: entry.generation, turn: entry.turn,
+      context_revision: entry.context_revision, expires_at: entry.expires_at,
+      targets: copy(entry.targets), fragments: copy(entry.fragments),
+      confirmation_scope: 'one_final_provider_request', business_permission: false }
+  }
+
+  reject(reason, generation) {
+    return { schema: 'bailing.agent-context-delivery-confirmation.v1', state: 'rejected', reason,
+      ...(generation === undefined ? {} : { generation }),
+      next_action: 'reassemble_context_before_model_request', business_permission: false }
+  }
+
+  confirm(sessionId, binding, input) {
+    const { entry, reason } = this.current(sessionId, binding)
+    if (!entry) return this.reject(reason)
+    // A late confirmation cannot revoke or replace a newer request's receipt.
+    if (!record(input) || input.delivery_id !== entry.delivery_id || input.generation !== entry.generation) {
+      return this.reject('stale_confirmation', entry.generation)
+    }
+    const fail = code => { entry.confirmed = undefined; entry.invalidated = code; return this.reject(code, entry.generation) }
+    if (Object.keys(input).some(name => !['delivery_id', 'generation', 'request_id', 'fragments'].includes(name)) ||
+      !ID.test(input.delivery_id) || typeof input.request_id !== 'string' || !REQUEST.test(input.request_id) || !Array.isArray(input.fragments) ||
+      input.fragments.length !== entry.fragments.length || input.fragments.length > MAX_FRAGMENTS) return fail('invalid_confirmation')
+    if (entry.confirmed && entry.confirmed.request_ref !== digest(input.request_id)) return fail('request_generation_reused')
+    const actual = new Map()
+    let total = 0
+    for (const fragment of input.fragments) {
+      if (!record(fragment) || Object.keys(fragment).some(name => !['kind', 'name', 'text'].includes(name)) ||
+        !['system', 'runtime_context'].includes(fragment.kind) || typeof fragment.name !== 'string' || fragment.name.length > 256 ||
+        typeof fragment.text !== 'string' || actual.has(key(fragment))) return fail('invalid_fragment')
+      total += bytes(fragment.text)
+      if (total > MAX_CONFIRM_BYTES) return fail('confirmation_too_large')
+      actual.set(key(fragment), { sha256: digest(fragment.text), bytes: bytes(fragment.text) })
+    }
+    for (const expected of entry.fragments) {
+      const fragment = actual.get(key(expected))
+      if (!fragment || fragment.sha256 !== expected.sha256 || fragment.bytes !== expected.bytes) return fail('fragment_mismatch')
+    }
+    entry.confirmed = { request_ref: digest(input.request_id), confirmed_at: this.now() }
+    return { schema: 'bailing.agent-context-delivery-confirmation.v1', state: 'confirmed',
+      delivery_id: entry.delivery_id, generation: entry.generation, request_ref: entry.confirmed.request_ref,
+      context_revision: entry.context_revision, expires_at: entry.expires_at,
+      next_request_requires_confirmation: true, business_permission: false }
+  }
+
+  invalidate(sessionId, reason = 'host_reset') {
+    const allowed = ['host_reset', 'request_failed', 'assembly_discarded', 'authorization_unavailable']
+    const entry = this.entries.get(sessionId)
+    this.entries.set(sessionId, { generation: (entry?.generation ?? 0) + 1,
+      reason: allowed.includes(reason) ? reason : 'host_reset' })
+    return { schema: 'bailing.agent-context-delivery-reset.v1', state: 'inline', business_permission: false }
+  }
+
+  invalidateConfirmation(sessionId, input, reason) {
+    const entry = this.entries.get(sessionId)
+    if (entry?.delivery_id === input?.delivery_id && entry?.generation === input?.generation) this.invalidate(sessionId, reason)
+  }
+
+  projection(sessionId, binding, contexts) {
+    const { entry, reason } = this.current(sessionId, binding)
+    const compact = Boolean(entry?.confirmed)
+    return { contexts: compact ? [] : contexts,
+      context_delivery: { schema: 'bailing.agent-context-delivery.v1',
+        mode: compact ? 'named_runtime' : 'inline', state: compact ? 'confirmed' : 'inline_fallback',
+        body_omitted: compact, reason: compact ? 'confirmed_named_runtime' : reason ?? 'host_unconfirmed',
+        ...(compact ? { delivery_id: entry.delivery_id, generation: entry.generation,
+          request_ref: entry.confirmed.request_ref, context_revision: entry.context_revision,
+          references: copy(entry.targets), next_request_requires_confirmation: true } : {}),
+        business_permission: false } }
+  }
+
+  forget(sessionId) { this.entries.delete(sessionId) }
+}
+
+export function preparationByteMetrics(contexts, returned, schemas, guidance) {
+  const source = bytes(JSON.stringify(contexts))
+  const inline = bytes(JSON.stringify(returned))
+  return { source_context_bytes: source, inline_context_bytes: inline, omitted_context_bytes: source - inline,
+    tool_schema_bytes: bytes(JSON.stringify(schemas)), usage_guidance_bytes: guidance === undefined ? 0 : bytes(JSON.stringify(guidance)) }
+}

package/lib/execution-summary.js

@@ -0,0 +1,45 @@
+// Model memory is a bounded account of last-known execution facts, not a copy
+// of business output and not proof of a current outcome or complete audit.
+export const EXECUTION_SUMMARY_SCHEMA = 'bailing.authorization-execution-summary.v1'
+const SUMMARY_MAX_CHARS = 16_000
+const INVOCATION_ID = /^[0-9a-f]{64}$/
+const TOOL_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/
+const STATES = new Set(['executed', 'business_rejected', 'awaiting_approval', 'denied',
+  'rejected_before_dispatch', 'reconciliation_required', 'in_progress', 'outcome_unknown', 'not_dispatched'])
+const UNRESOLVED = new Set(['awaiting_approval', 'in_progress', 'reconciliation_required', 'outcome_unknown'])
+
+export function authorizationExecutionSummary(records) {
+  const all = [...records].filter(Boolean)
+  const facts = all.flatMap((record) => {
+    if (!INVOCATION_ID.test(record.invocationId ?? '')) return []
+    const state = STATES.has(record.latest?.state)
+      ? record.latest.state : record.invoked ? 'outcome_unknown' : 'not_dispatched'
+    return [{
+      invocation_id: record.invocationId,
+      ...(TOOL_NAME.test(record.tool ?? '') ? { tool: record.tool } : {}),
+      last_known_state: state,
+      ...(UNRESOLVED.has(state) ? { next_action: 'inspect_original' } : {}),
+    }]
+  })
+  // Keep unresolved originals first; a large batch of successful reads must not
+  // push an earlier uncertain write out of this bounded continuation context.
+  const ordered = [...facts].reverse().sort((a, b) => Number(UNRESOLVED.has(b.last_known_state)) - Number(UNRESOLVED.has(a.last_known_state)))
+  const summary = {
+    schema_version: EXECUTION_SUMMARY_SCHEMA,
+    source: 'agent_client',
+    trust: 'reference_only',
+    total_invocations: all.length,
+    omitted_invocations: all.length,
+    invocations: [],
+  }
+  for (const fact of ordered) {
+    summary.invocations.push(fact)
+    summary.omitted_invocations = all.length - summary.invocations.length
+    if (JSON.stringify(summary).length > SUMMARY_MAX_CHARS) {
+      summary.invocations.pop()
+      summary.omitted_invocations = all.length - summary.invocations.length
+      break
+    }
+  }
+  return JSON.stringify(summary)
+}

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)