dsh-bailinghub 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.8.0 - 2026-10-22
+
+Return explicit preparation receipts, read selected tool guidance, negotiate knowledge search/read and allow cooperating hosts to confirm named context delivery before omitting repeated bodies. Pin SDK 0.8.0 for bounded complete tool inputs and explicit model-budget helpers. Keep business authorization, approval and original-operation recovery unchanged; task continuation remains the host's responsibility.
+See [changes](docs/RELEASE_NOTES_v0.8.0.en.md) and [upgrade](docs/UPGRADE_v0.8.0.en.md).
+
 ## 0.7.0 - 2026-09-23
 
 Optional host-orchestrated model gateway, USD plan presentation and asynchronous image tools.

package/README.md

@@ -1,11 +1,10 @@
 # BailingHub for DeepSeek Harness
 
-## 0.7.0: optional model services and plan billing
+## 0.8.0: prepare tools once and read knowledge when needed
 
-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.7.0.en.md) · [Upgrade](docs/UPGRADE_v0.7.0.en.md)
+A local Agent can retain complete tool declarations, read one tool's guidance and retrieve only relevant reference knowledge. A cooperating host can confirm named context delivery before omitting repeated preparation bodies. Pair Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0; existing authorization, approval and original-operation recovery remain in force.
 
+[Changes](docs/RELEASE_NOTES_v0.8.0.en.md) · [Upgrade](docs/UPGRADE_v0.8.0.en.md)
 
 [简体中文](docs/README.zh-CN.md) | English
 
@@ -40,14 +39,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.9.0 → BailingHub MCP/SDK 0.7.0 → this plugin 0.7.0**.
+**BailingHub Core 0.10.0 → BailingHub MCP/SDK 0.8.0 → this plugin 0.8.0**.
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.7.0
+dsh plugin --profile web add dsh-bailinghub@0.8.0
 ```
 
-The plugin installs its exact `bailinghub-mcp-server@0.7.0` dependency automatically.
+The plugin installs its exact `bailinghub-mcp-server@0.8.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
@@ -95,7 +94,7 @@ A confirmed revocation or identity change requires a new conversation with a val
 
 ## Follow the conversation and its actions
 
-With Core 0.7.0 and SDK 0.5.0, BailingHub can show the visible user and assistant messages, turn
+With Core 0.8.0 and SDK 0.5.0, BailingHub can show the visible user and assistant messages, turn
 boundaries, and links to the original business runs as one conversation record. Each authorization
 also keeps its own business-call record; the combined reply is not copied into every account's
 memory.

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -167,8 +167,9 @@ cross-system transaction, automatic rollback or field-level data-transfer policy
 continue owning their capabilities, permission checks, approvals and data semantics. See the
 [user and host guide](CROSS_SYSTEM_CONVERSATIONS.md).
 
-Status: native Agent Client contract for `dsh-bailinghub@0.5.0`, paired with
-`bailinghub-mcp-server@0.5.0` and BailingHub Core `0.7.0`. The same-system scope and archive
+Status: retained native Agent Client contract for `dsh-bailinghub@0.8.0`, paired with
+`bailinghub-mcp-server@0.8.0` and BailingHub Core `0.10.0`. The cross-system extension
+first shipped with plugin/SDK 0.5.0 and Core 0.7.0. The same-system scope and archive
 baseline was introduced in plugin/SDK 0.4.0 and Core 0.6.0 (recommended historical Core 0.6.1).
 This contract is separate from the legacy static `0.1.x` path. Version 0.3.0 supported user-managed
 connections but did not include
@@ -256,7 +257,18 @@ across process restarts, never into another conversation. Unknown IDs fail close
 original-invocation recovery, not durable automatic continuation of a whole task.
 
 On multi-authorization completion, the adapter freezes one deterministic summary of each run's
-own governed calls and synchronizes that run separately. It does not send the combined visible
+own governed calls and synchronizes that run separately. The content is a JSON string with
+`schema_version: "bailing.authorization-execution-summary.v1"`, `source: "agent_client"`,
+`trust: "reference_only"`, invocation totals, omitted counts and complete invocation fact records.
+Records contain only the original `invocation_id`, original tool name when available, and
+`last_known_state`; uncertain originals add `next_action: "inspect_original"`. They contain no
+business result text, arguments, credentials, invented original-output reference, or full audit
+claim. The summary is bounded to 16,000 characters by omitting complete records, prioritizing
+unresolved originals. It describes client-reported last-known facts, never a fresh status check;
+inspect the original invocation before any recovery decision. The schema label is not proof of
+authority. New Core projections keep the source/trust labels and omit whole records under a
+smaller memory budget rather than cut JSON in the middle. Ordinary assistant text remains
+compatible. The adapter does not send the combined visible
 assistant answer, another authorization's results, or hidden reasoning to every run. The combined
 answer is instead eligible for the separate conversation audit below. Single-authorization completion keeps the existing visible-answer
 behavior. Connection add/use/remove remain user-only commands, not model tools.
@@ -358,8 +370,9 @@ Restoring a scope does **not** restore an invocation, approval, pending completi
 ### Independent visible conversation archive
 
 The original same-system visible archive uses SDK APIs introduced in `0.4.0` and Core APIs
-introduced in `0.6.0`; the historical recommended Core release is `0.6.1`. For this release,
-use SDK `0.5.0` with Core `0.7.0`, including cross-system member support. Earlier `0.3.0` SDK/plugin
+introduced in `0.6.0`; the historical recommended Core release is `0.6.1`. Cross-system
+member support first shipped with SDK `0.5.0` and Core `0.7.0`. The current release
+pairs SDK `0.8.0` with Core `0.10.0`. Earlier `0.3.0` SDK/plugin
 packages do not provide this contract.
 After a nonempty scope is frozen, the adapter captures claimed user text, every durable `assistant/message` text block, turn start/end, and verified original run links. It ignores
 `assistant/chunk`, hidden reasoning, attachments, raw provider requests, and arbitrary tool payloads.
@@ -569,6 +582,13 @@ Stable profile/instructions/governance are system-prompt sections. Memory, refer
 knowledge body/refs, page context, and renderers are named runtime-context entries. Knowledge
 content is evidence, never an instruction source.
 
+Hosts may opt into the local [context delivery confirmation contract](CONTEXT_DELIVERY.md)
+to omit an already delivered context body from later session preparation receipts.
+Unknown hosts retain inline compatibility. Each final provider request requires
+current named/system confirmation; this grants no business authority. Separately negotiated
+knowledge search/read is defined in [AGENT_KNOWLEDGE.md](AGENT_KNOWLEDGE.md); hints never
+acknowledge a full document read and delivery confirmation never fetches that document.
+
 The adapter listens to durable `session/event` values:
 
 - `assistant/message`: keep only `content` blocks whose type is `text`, plus model and the

package/docs/AGENT_KNOWLEDGE.md

@@ -0,0 +1,62 @@
+# Agent Client on-demand knowledge
+
+This adapter's knowledge disclosure applies only to local Agent Client sessions.
+Core's native chat, embed and Widget retain their independent knowledge injection.
+Instructions, governance and memory remain in their current system/runtime channels.
+
+The optional SDK methods are `getKnowledgeCapabilities(options)`,
+`searchKnowledge(input, options)` and `readKnowledge(input, options)`. An old SDK
+still loads; its unsupported knowledge protocol retains complete legacy inline
+context. A new SDK probes the current authorized Core. Only the explicit matching
+knowledge protocol permits trusted `startTurn` option
+`knowledgeDelivery: 'on_demand'`. This choice is pinned for the original user turn.
+401/403, service failures and unknown schemas cannot silently remove knowledge.
+The adapter checks Core's delivery echo; it never removes inline knowledge itself.
+
+## Model tools
+
+`search_business_knowledge` accepts a minimal `query` (up to 500 characters),
+optional `limit` (1–3), and the intended `authorization_ref` when multiple targets
+are selected. A lazy target can be prepared for a knowledge-only question without
+searching business capabilities or dispatching a business tool. Queries are never
+broadcast across authorizations or sent to an unselected global default.
+
+Search returns at most three short title/summary/ref hints, `status` and an explicit
+`trust: reference_only`. Use `read_business_knowledge` with a relevant `ref`, the
+same authorization, optional `cursor` and optional `max_bytes` (4096–32768) to read
+one page. The runtime supplies the original run; the model cannot redirect it.
+Search JSON is bounded to 4 KiB, read JSON defaults to 16 KiB and is at most 32 KiB.
+
+Read only relevant documents and follow `next_cursor` as necessary. Hints are not
+full documents. `truncated: true` remains incomplete even when
+`budget_exhausted: true` ends a 128 KiB content chain with no next cursor. Safe
+`total_content_bytes`/`read_chain_max_bytes` scalars can explain that limit.
+
+References are opaque, expire after 300 seconds, and remain bound to the original
+Agent Session, route, run and current knowledge revision. Never reuse them across
+accounts. Invalid/changed/expired references return `next_action: search_knowledge`.
+Search again under the same authorization; never replay a business operation.
+Unavailable retrieval is not an empty corpus. Empty business-tool hits do not mean
+that knowledge is absent.
+
+## Context and host cooperation
+
+The prompt always explains that reference knowledge may exist and exposes these
+two tools independently of business tool discovery. A prepared on-demand target's
+named knowledge context contains the delivery status and light discovery hints;
+document bodies arrive only through explicit reads. Reference text never overrides
+system instructions, governance, identity or approval.
+
+The first-batch `getContextDeliveryManifest` / `confirmContextDelivery` contract
+continues unchanged. Confirm the exact named current contributions present in each
+final provider request. Hints are not a full-body acknowledgement. Retain actual
+read results in their current authorized conversation, with bounded pages and
+source attribution. Do not inject a separate full knowledge corpus into new
+on-demand sessions, and do not trim legacy inline knowledge on unknown Core/SDK.
+
+The client should verify real final-provider request contents, not only a
+preparation receipt. Required acceptance cases: knowledge-only question, relevant
+hint followed by one read, empty result, unavailable retrieval, paginated/truncated
+document, expired/changed ref, multi-account isolation, cancellation or revocation
+during a read, old SDK/Core fallback and first-batch delivery confirmation.
+Neither this adapter nor knowledge receipts acknowledge a business write.

package/docs/CAPABILITY_FEEDBACK.md

@@ -24,12 +24,20 @@ This change adds no stock synchronization, cross-system transaction or rollback.
 
 ## Search result meanings
 
-The default `search_business_capabilities` keeps its existing parameters. Opt-in
-session mode adds `tool_name` for exact cached declaration preparation and retrieval;
-a broad `query` without `tool_name` still discovers capabilities. Cross-system search
+`search_business_capabilities` retains `query`, `limit` and authorization selection.
+The optional `tool_name` supports exact known declarations in active-turn mode and
+cached declaration preparation in opt-in session mode. A broad `query` without
+`tool_name` still discovers capabilities. Cross-system search
 requires the original `authorization_ref` and a minimal target-specific query.
 Single-account and same-system selection continue to work.
 
+An exact known `tool_name` can also be supplied in `active_turn` mode. Add
+`include_usage_guidance=true` to explicitly fetch its bounded detail for one
+selected authorization. `description_truncated` and `usage_guidance_available`
+indicate when short descriptions are insufficient; full guidance is not appended
+to every schema or fetched by broad searches. The detail remains revision-bound
+reference evidence. See [usage guidance and preparation](SESSION_TOOL_REUSE.md).
+
 | Field | Meaning |
 | --- | --- |
 | `discovery.returned_count` | Candidates actually returned for this search target |
@@ -118,6 +126,16 @@ Failures carry `bailing.agent-feedback.v1` with `category`, `code`, `origin`,
 original `invocation_id` when one exists. SDK-defined feedback is projected through
 a safe allowlist; raw transport messages and arbitrary extra fields are omitted.
 
+For `code=arguments_too_large` only, the projection also retains known
+`actual_bytes`, `max_bytes`, `observed_bytes` (nonnegative safe integers), and
+`limit_scope=arguments|request_body` when provided by Core/SDK. Actual bytes refer
+to the serialized UTF-8 JSON or body specified by that scope; observed bytes may
+only be the stream prefix seen before stopping. These are diagnostic scalars,
+not a second business payload. Arbitrary `details`, field paths, raw arguments,
+credentials and transport messages never pass through this projection. Origin
+and dispatch remain explicit; accepted-unknown recovery takes precedence over
+any size diagnostic and still recovers only the original invocation.
+
 `retryable` refers only to `next_action`. It never grants permission to issue a new
 business invocation. `dispatch=not_dispatched` is used only for a known stage; a
 transport failure after invoking cannot establish that the request was not sent.
@@ -190,6 +208,17 @@ before a new business operation; replaying the preparation's call ID does not
 convert it into an operation. Do not gate these native preparation guards against
 `active_tools` alone. Read-only tool-state methods do not prepare targets.
 
+Preparation results additionally expose `result_type=capability_preparation`,
+`dispatch=not_dispatched`, a preparation reason and a controlled `next_action`.
+Do not display them as completed business operations. No invocation is fabricated
+for a preparation-only result. Common lifecycle and recovery guidance is assembled
+once in the public profile; each business definition still retains its own scope,
+risk, approval/read-only/idempotency facts, target binding and a minimal original-ID
+recovery warning. A custom host must deliver the public profile, tool declarations
+and named contexts together. Both the returned preparation context and named
+context paths remain available until there is an explicit host-consumption contract;
+this change does not silently remove either path.
+
 Tested with the public native registry `@deepseek-ai/dsh-tools@0.1.1-rc.2` and real
 Cordis/DSH Sessions. A custom host must verify the hook and preserve the feedback
 carrier through its own model loop. Simply adding properties to a thrown Error is

package/docs/COMPATIBILITY.md

@@ -1,6 +1,6 @@
-# Current 0.7.0 pairing
+# Current 0.8.0 pairing
 
-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).
+Use Core 0.10.0, SDK 0.8.0 and DSH 0.8.0 for larger Agent tool inputs, negotiated on-demand knowledge and cooperating-host context delivery confirmation. Existing business-governance APIs retain their documented minima. The host still owns model parameter selection and bounded task continuation. See [upgrade](UPGRADE_v0.8.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.7.0
+## Native Agent Client 0.8.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.7.0` via `./sdk` |
-| BailingHub Core | `bailinghub@0.9.0`, with outstanding migrations through 064 applied |
+| Generic Agent Client SDK | Exact `bailinghub-mcp-server@0.8.0` via `./sdk` |
+| BailingHub Core | `bailinghub@0.10.0`, with only its outstanding migrations 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.7.0`; its ordinary dependency installs the exact SDK automatically.
+Install `dsh-bailinghub@0.8.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 scenarios](RELEASE_NOTES_v0.7.0.en.md).
+[release scenarios](RELEASE_NOTES_v0.8.0.en.md).
 
 ### Authorization subject display
 
@@ -189,7 +189,7 @@ BailingHub Core release is compatible only after a separate clean legacy profile
 
 Compatibility requires independent evidence for both paths:
 
-1. Native 0.5: clean install of only the exact plugin package, browser authorization, workspace
+1. Native 0.8: clean install of only the exact plugin package, browser authorization, workspace
    discovery, same-identity replacement, different-identity isolation, read, permitted mutation,
    approval/resume, visible completion, and Hub trajectory. Additionally verify explicit single/multiple
    scope selection, full-set archive authorization, offline reopen/retry, revocation, and no business

package/docs/CONTEXT_DELIVERY.md

@@ -0,0 +1,133 @@
+# Agent Client context delivery confirmation
+
+This optional local host contract reduces repeated context bodies in session-tool
+preparation results. It does not change Core chat/embed context assembly, grant
+authorization, or acknowledge business execution. The separate
+[on-demand knowledge contract](AGENT_KNOWLEDGE.md) adds explicit search/read tools;
+delivery confirmation itself never searches or reads a document.
+
+## Default and timing
+
+Existing or unknown hosts keep the complete `contexts` array in preparation
+receipts. Named system/runtime contributions also remain in ordinary DSH prompt
+assembly. Existing runtime-snapshot deduplication is unchanged.
+
+The first lazy preparation creates context after the preceding model request was
+sent, so it remains inline. After a cooperating host has assembled and confirmed
+the current named contributions in a final provider request, later same-binding
+preparations may omit that repeated body. This does not eliminate the first inline
+copy already retained in tool history.
+
+## Public local service
+
+Use the `bailingHubAgentClient` service (`BailingHubAgentClientRuntime`), outside
+model tools:
+
+```js
+const manifest = runtime.getContextDeliveryManifest(session.id)
+const confirmation = await runtime.confirmContextDelivery(session.id, {
+  delivery_id: manifest.delivery_id,
+  generation: manifest.generation,
+  request_id: 'opaque-provider-request-17',
+  fragments: [
+    { kind: 'system', name: 'bailinghub:agent-client-profile', text: actualSystemSection },
+    // One entry per manifest runtime_context fragment, retaining its exact name.
+    { kind: 'runtime_context', name: actualNamedContextName, text: actualNamedContextText },
+  ],
+})
+```
+
+The manifest is available only after a current active context was assembled. It
+contains kind/name, SHA-256 and UTF-8 bytes, never document text. Target references
+bind current run/profile/capability/context revisions. The opaque ticket also binds
+the local Session, real user turn and complete original authorization scope and
+revision, including connection, Hub, client, route and authorized Session identities.
+
+Each assembly creates a new generation and clears preceding confirmation, even
+if its text is unchanged. Tickets expire after 60 seconds. There is one opaque
+`request_id` per generation: 1–128 ASCII letters/digits and `_.:-`, beginning with a
+letter/digit. Identical confirmations for that request are idempotent; a different
+request id needs a fresh assembly.
+
+## Final provider request responsibility
+
+The host must confirm **every final provider request**, after its own serialization,
+clipping, compaction and policy transforms. Extract only the exact current
+BailingHub system section and named runtime contributions actually present in
+that request. DSH runtime snapshots may use a provider `user` role with trusted
+plugin source; preserve `snapshot.source.sections` attribution through serialization.
+Do not infer authority from role alone. Ordinary user/tool history is not a named
+runtime contribution. Do not scan arbitrary messages for substrings or manufacture
+fragments by parsing old inline preparation JSON.
+
+All manifest entries require correct kind/name and exact text hash/size.
+Unrelated kinds/names, duplicates, missing/truncated text and invalid inputs reject.
+Text is compared only in memory: not retained, logged, or returned. Confirmation
+is bounded to 256 fragments and 4 MiB total text; an unsupported host stays inline.
+
+Request N's confirmation does not prove N+1 still contains context. Even if a light
+preparation was produced between requests, the host **must not send N+1** without
+reassembling and confirming current fragments. Missing/truncated context or rejected
+confirmation requires restoring named contributions and assembling/confirming
+again, or aborting that model request. Do not replay a business tool to repair a
+prompt. Core authorization, approval and unknown-invocation recovery are unchanged.
+
+The library cannot independently observe downstream network payloads. Confirmation
+is a cooperating host's presentation protocol, not proof that a model received,
+read or understood text and not a security/authorization assertion.
+
+## Invalidation and fallback
+
+```js
+runtime.invalidateContextDelivery(session.id, { reason: 'request_failed' })
+// host_reset, request_failed, assembly_discarded, authorization_unavailable
+```
+
+Reset when a prepared request is discarded, serialization fails, or delivery
+strategy changes; unknown reason strings become `host_reset`. Reassemble before
+confirmation. New assembly/turn/run/scope/account/route/Session/profile/capability/
+context revision invalidates prior acknowledgement. Ended/disposed sessions cannot
+confirm. Expired or changed-back bindings cannot revive an old ticket. Late old
+tickets cannot replace a newer receipt. Malformed current confirmation invalidates
+its generation; a fresh assembly is required.
+
+Rejections return a bounded reason and
+`next_action: reassemble_context_before_model_request`, never the submitted body.
+They do not establish that any business operation ran or that an unknown one did not.
+
+## Preparation and metrics
+
+The existing preparation schema retains `result_type`, `dispatch: not_dispatched`,
+`business_operation_performed: false`, preparation state, full tool schemas,
+governance and explicit usage-guidance result. Confirmed optional delivery uses
+`contexts: []` plus `context_delivery` with schema
+`bailing.agent-context-delivery.v1`, mode `named_runtime`, state `confirmed`,
+`body_omitted: true`, bounded delivery/generation/request/context references,
+target revisions, `next_request_requires_confirmation: true`, and
+`business_permission: false`. Empty contexts means already delivered by the named
+path, not knowledge absence. Otherwise complete contexts remain with mode `inline`,
+state `inline_fallback`, `body_omitted: false` and a bounded reason.
+
+`context_metrics` contains fixed numeric fields only:
+
+- `source_context_bytes`: UTF-8 bytes of JSON.stringify(full contexts array).
+- `inline_context_bytes`: bytes of the returned array (`[]` is two bytes).
+- `omitted_context_bytes`: the difference.
+- `tool_schema_bytes`: bytes of returned tool_schemas.
+- `usage_guidance_bytes`: bytes of explicit usage-guidance, otherwise zero.
+
+These preparation-component bytes are not final model token counts, provider wire
+sizes, relevance scores or evidence-retention guarantees. Measure the final provider
+request separately without logging bodies or credentials. Do not globally dedupe
+identical text across accounts.
+
+## Dependency candidates
+
+Source root overrides repair the registry SDK's old exact MCP dependency and retain
+the SDK safety override, so this workspace lock can be audited cleanly. Library
+overrides do not propagate downstream. Consumers must install the matching new SDK
+and DSH candidates as direct local tarballs, select that SDK for DSH via their root
+override, regenerate their actual lock and verify ESM resolution, installed bytes,
+fresh audits and final runtime build. Version alone does not identify an internal
+same-version candidate. Knowledge search/read follows the separate negotiated
+contract; it does not introduce a free-form knowledge_get or off/hint/full switch.

package/docs/GETTING_STARTED.md

@@ -1,7 +1,7 @@
-# Get started with 0.6.0
+# Get started with 0.8.0
 
 This guide is for users whose business system is already connected to BailingHub. Your
-administrator must prepare Core 0.8.0, a public Client App ID, a workspace, and the business
+administrator must prepare Core 0.10.0, a public Client App ID, a workspace, and the business
 browser-authorization entry first. For multiple systems, prepare one independently authorized
 connection per target on the same Hub and audit domain. Existing business capability declarations
 remain valid; each requested action must already be exposed by its own system.
@@ -12,10 +12,10 @@ Use Node.js `22.19.0+` or `24+` and the compatible DSH version:
 
 ```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.8.0
 ```
 
-The plugin installs SDK 0.6.0 automatically. Enter the four public values in DSH plugin settings,
+The plugin installs SDK 0.8.0 automatically. Enter the four public values in DSH plugin settings,
 or use their environment names. The example values below are placeholders:
 
 ```bash

package/docs/GETTING_STARTED.zh-CN.md

@@ -1,6 +1,6 @@
-# 开始使用 0.6.0
+# 开始使用 0.8.0
 
-这份指南面向业务系统已经接入 BailingHub 的用户。管理员需要先准备 Core 0.8.0、公开的 Client
+这份指南面向业务系统已经接入 BailingHub 的用户。管理员需要先准备 Core 0.10.0、公开的 Client
 App ID、workspace 和浏览器业务授权入口。多系统时，每个目标分别授权，且属于同一中枢、同一
 审计域；已有能力无需重新声明，但每项动作必须已由相应业务系统开放。
 
@@ -10,10 +10,10 @@ App ID、workspace 和浏览器业务授权入口。多系统时，每个目标
 
 ```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.8.0
 ```
 
-插件会自动安装 SDK 0.6.0。通过插件设置填写四项公开信息，或使用对应环境变量。下面都是
+插件会自动安装 SDK 0.8.0。通过插件设置填写四项公开信息，或使用对应环境变量。下面都是
 占位值，需要替换成管理员提供的中枢地址、Client App ID 和 workspace：
 
 ```bash

package/docs/MIGRATION_VNEXT.md

@@ -1,8 +1,6 @@
-# Migrate to 0.6.0
+# Migrate to 0.8.0
 
-Use [the 0.6.0 paired upgrade guide](UPGRADE_v0.6.0.en.md) / [中文](UPGRADE_v0.6.0.md). Preserve original scopes, events, journals and task bindings. Session tool reuse requires host opt-in. The following sections retain earlier upgrade history.
-
-# Migrate to 0.5.0
+Use [the 0.8.0 paired upgrade guide](UPGRADE_v0.8.0.en.md) / [中文](UPGRADE_v0.8.0.md). Pair Core 0.10.0, SDK 0.8.0 and DSH 0.8.0. Preserve original scopes, events, invocation journals and task bindings. On-demand knowledge is negotiated; named-context omission requires cooperating-host confirmation. The following sections retain earlier upgrade history.
 
 ## From 0.4.0: add systems without replacing existing authorizations
 

package/docs/README.zh-CN.md

@@ -1,11 +1,10 @@
 # BailingHub for DeepSeek Harness
 
-## 0.7.0：可选模型服务与套餐计费
+## 0.8.0：复用工具声明，按需读取知识
 
-本地宿主继续编排，中枢提供模型转发、共享额度与异步计量。对话模型和图片工具分开下发；原业务权限、审批与审计保持。配套 Core 0.9.0 / SDK 0.7.0 / DSH 0.7.0。
-
-[本次变化](RELEASE_NOTES_v0.7.0.md) · [升级指南](UPGRADE_v0.7.0.md)
+本地智能体可以保留完整工具声明、只读选定工具的指导，并按需检索相关参考知识。配合宿主逐请求确认命名上下文后，可省去准备回执中的重复正文。配套 Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0；原授权、审批和原操作恢复保持。
 
+[本次变化](RELEASE_NOTES_v0.8.0.md) · [升级指南](UPGRADE_v0.8.0.md)
 
 [English](../README.md) | 简体中文
 
@@ -35,14 +34,14 @@
 ## 安装与开始使用
 
 需要 Node.js `22.19.0+` 或 `24+`、pnpm，以及兼容的 DeepSeek Harness。管理员应先完成业务系统
-接入。配套版本为 **BailingHub Core 0.9.0 → BailingHub MCP/SDK 0.7.0 → 本插件 0.7.0**。
+接入。配套版本为 **BailingHub Core 0.10.0 → BailingHub MCP/SDK 0.8.0 → 本插件 0.8.0**。
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
-dsh plugin --profile web add dsh-bailinghub@0.7.0
+dsh plugin --profile web add dsh-bailinghub@0.8.0
 ```
 
-插件会自动安装精确依赖 `bailinghub-mcp-server@0.7.0`，无需另装 SDK。
+插件会自动安装精确依赖 `bailinghub-mcp-server@0.8.0`，无需另装 SDK。
 已经使用旧版的用户请先看[从 0.4.0 及更早版本升级的步骤](MIGRATION_VNEXT.md)。
 
 按照[开始使用指南](GETTING_STARTED.zh-CN.md)填写管理员提供的四项公开连接信息，再到浏览器授权。
@@ -80,7 +79,7 @@ dsh plugin --profile web add dsh-bailinghub@0.7.0
 
 ## 查看沟通过程与操作结果
 
-配合 Core 0.7.0 和 SDK 0.5.0，BailingHub 可以把可见的用户消息、助手回复、轮次，以及原业务
+配合 Core 0.8.0 和 SDK 0.5.0，BailingHub 可以把可见的用户消息、助手回复、轮次，以及原业务
 执行记录的关联放在同一份会话记录中。各份授权仍保留自己的业务调用记录，汇总回答不会复制到
 每个账号的记忆中。
 

package/docs/RELEASE_NOTES_v0.8.0.en.md

@@ -0,0 +1,21 @@
+# DSH 0.8.0: tool preparation and knowledge on demand
+
+A user may check stock, update a product and then ask about a page-setting rule. The Agent needs reusable declarations without treating preparation as completed business work. This release makes preparation distinct and reduces repeated guidance and knowledge bodies. It pairs **Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0**. Business capabilities and product mappings must already exist; authorization and approval remain unchanged.
+
+## Additions and fixes
+
+- Preparation receipts explicitly report `result_type: capability_preparation`, `dispatch: not_dispatched` and `business_operation_performed: false`. A host opting into session tool reuse can retrieve complete declarations by original name. Preparation is not execution; replaying its call ID must not turn it into a write.
+- When short descriptions advertise more guidance, use `search_business_capabilities` with `tool_name` and `include_usage_guidance` for bounded reference material tied to the original authorization and capability revision. Multiple targets remain distinct through `authorization_ref`.
+- Add `search_business_knowledge` and `read_business_knowledge`. Negotiated support separates knowledge retrieval from tool discovery: inspect hints, then read relevant content and pages. Old SDK/Core combinations retain inline knowledge; authorization/service failures are not empty results. Core native chat and embed stay independent.
+- Add host-only `getContextDeliveryManifest()`, `confirmContextDelivery()` and `invalidateContextDelivery()`. Later preparation receipts can omit repeated bodies only after a cooperating host confirms the current named contributions in each final model request. Unknown hosts keep inline bodies. Confirmation is neither business permission nor proof of model understanding.
+- Pin SDK 0.8.0, including 1 MiB serialized tool arguments, on-demand knowledge and separate model-budget helpers. Library dependency overrides do not replace host audits.
+
+## Hosts still own task loops
+
+The plugin preserves original model operations, business invocations, approvals and cancellation fences. Hosts integrate model parameters and reasoning/answer budgets from service descriptors. Automatic long-task continuation is not enabled by this release: hosts must checkpoint, bound counts/cost/time, detect no progress and avoid repeating completed actions. Inspect unknown originals read-only; never execute truncated tool arguments.
+
+## Upgrade and observe
+
+Upgrade Core first, then install `dsh-bailinghub@0.8.0`; it installs the exact SDK without manual version mixing. Preserve credentials, real Sessions, scope/task/invocation stores and archive records. Restart and verify the actual resolved packages.
+
+Observe preparation versus a normal tool result, independent knowledge search/pagination, multiple-authorization isolation and old-Core fallback. Hosts enabling context confirmation must additionally inspect the final provider request, not just preparation receipts. Missing confirmation requires restoring context or stopping the request, not replaying business work. See [the upgrade guide](UPGRADE_v0.8.0.en.md).

package/docs/RELEASE_NOTES_v0.8.0.md

@@ -0,0 +1,21 @@
+# DSH 0.8.0：工具准备与知识按需读取
+
+用户先查库存、再修改商品、最后确认页面规则时，智能体需要复用已发现工具，又不能把“声明已准备”当成业务已经完成。本版把准备和执行结果说清楚，并减少重复指导与知识正文。配套 **Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0**；业务能力及商品映射须由业务系统预先提供，原授权和审批不变。
+
+## 新增与修复
+
+- 准备回执明确给出 `result_type: capability_preparation`、`dispatch: not_dispatched` 与 `business_operation_performed: false`。宿主启用会话工具复用时，可按原工具名取得完整声明；准备工具不等于执行工具，不能把相同调用 ID 重放成写入。
+- 短描述提示有补充指导时，用 `search_business_capabilities` 的 `tool_name` 和 `include_usage_guidance`，只读取对应授权及能力修订下的有界参考。多目标仍由 `authorization_ref` 区分。
+- 新增 `search_business_knowledge`、`read_business_knowledge`。协议协商成功后，工具发现与知识搜索独立；先看提示，再读取相关正文和分页。旧 SDK/Core 保留 inline 知识；授权、服务异常不能当成空结果。Core 原生聊天/嵌入不受此模式影响。
+- 新增宿主级 `getContextDeliveryManifest()`、`confirmContextDelivery()` 与 `invalidateContextDelivery()`。只有协作宿主确认每份最终模型请求实际包含当前命名上下文，后续准备回执才可省略重复正文；未知宿主默认保留正文。确认不是业务权限或模型理解证明。
+- 精确依赖 SDK 0.8.0，包含 1 MiB 序列化工具参数、按需知识及独立模型预算 helper。库内依赖覆盖不替代宿主自身依赖审计。
+
+## 任务循环仍由宿主负责
+
+插件保留原模型 operation、业务 invocation、审批和取消边界。模型参数与思考/答案预算由宿主按服务目录接入。自动长任务续跑不是本版自动开启的功能：宿主须保存检查点、限制次数/费用/时长、识别无进展并避免重复已完成动作。原结果未知时只读核对；截断工具参数不执行。
+
+## 升级与观察
+
+先升级 Core，再安装 `dsh-bailinghub@0.8.0`；插件自动安装精确 SDK，无需手工混装。保留凭据、真实 Session、scope、task、invocation 与归档记录，重启后核对实际加载包。
+
+观察一次正常工具调用与准备回执的差异、知识单独搜索与分页、多授权隔离和旧 Core 回退。若宿主启用上下文确认，额外核对最终 provider 请求，不能只检查准备回执。缺失确认必须恢复上下文或停止请求，不重做业务动作。[完整升级步骤](UPGRADE_v0.8.0.md)

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