dsh-bailinghub 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # 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).
+
+- Bind administrator-created tasks through persistent taskStore and public host APIs. Preserve original members, cumulative budgets, cancellation and read-only receipt inspection; models cannot create or switch tasks.
+
+- Let a conversation panel inspect a pending shop listing or inventory change
+  after reopening, without starting a model turn or business run. Explicit continuation
+  first inspects the original receipt, preserves approval and task controls, and never
+  replaces an uncertain write. Panel and model actions serialize the same invocation.
+  Preserve local storage errors, cancellation and original retry deadlines. See the
+  [host integration contract](docs/TASK_CONTROL.md).
+
+- Let a host read original conversation and selected shop/inventory authorization
+  coordinates through `getSessionTaskCoordinates(session)` when preparing a governed
+  task. Revalidate the complete original group without locking a draft, creating a
+  run or exposing unselected targets. Keep persistence failures distinct from
+  retryable network failures and unsupported versions. Existing task binding and
+  execution rules remain in force; see [the host contract](docs/TASK_CONTROL.md).
+
+- Let an opted-in host retain complete shop, inventory or other business tool
+  declarations across user messages in the same living Session. Prepare current
+  target context once per user turn; valid exact-name lookups need no additional
+  capability-search request. Ordinary chat starts no business run.
+- Bound the session cache to 64 target-tool pairs and 2 MiB, with a 12-schema
+  presentation window. Separate cached declarations from currently prepared tools;
+  return full schemas and current context through the existing search entry point.
+- A direct unprepared cached call returns preparation only. It creates no business
+  invocation, and replaying its call ID cannot turn it into a write. Current identity,
+  declaration changes, cancellation and original-invocation recovery remain enforced.
+- Keep legacy `active_turn` behavior by default. Hosts explicitly enable
+  `toolLifecycle: 'session'` after handling preparation results. Core and SDK need
+  no additional API for this candidate. See [the integration contract](docs/SESSION_TOOL_REUSE.md).
+
+- Preserve an authoritative `invocation_not_found` response during polling and
+  direct recovery. Stop automatic retries and ask for inspection of the original
+  execution evidence, without declaring the business action unexecuted or creating
+  a replacement write. Generic network/HTTP failures retain conservative recovery.
+
+- Reopen a conversation after pending approval or a lost business response and recover
+  the original invocation through a durable, metadata-only local journal. Persist the
+  original authorization, run, invocation and parameter digest before dispatch; never
+  rebuild a business write from transcript text or substitute another account.
+- Custom hosts can supply an invocation store and inspect or restore its local status.
+  Storage failures remain explicit. Restoring metadata sends no business recovery
+  request; an explicit resume may continue the original approved operation.
+  See [reopening and original invocation recovery](docs/INVOCATION_RECOVERY.md).
+
+- Keep long tasks moving between product creation, queries and inventory checks:
+  searches merge valid tools during the active turn instead of unloading the previous
+  batch. Retain up to 64 callable tools behind a 12-schema model window; unchanged
+  registrations survive concurrent discovery and calls.
+- Invalidate only the changed authorization catalog, quarantine contradictory
+  declarations, and preserve original invocation recovery and cancellation boundaries.
+  See [long-task lifecycle and host upgrade guidance](docs/CAPABILITY_FEEDBACK.md).
+
+- Honor Hub retry delays after pre-dispatch rate limiting. Long waits retain the original invocation for later recovery; early manual resumes avoid extra requests. Shared quota details stay visible to the model.
+
+- Add an image-first Local Agent attachment space for adapted hosts: list approved conversation
+  outputs, upload 1–8 PNG/JPEG/WebP images to an explicitly selected authorization, and reuse
+  ready URLs with existing business tools. Persist original upload records for recovery.
+- See [attachment integration](docs/GENERATED_ARTIFACTS.md) for campaign artwork, charts
+  and shop examples. Host file access is explicit; upload success and business action results
+  are independent. Business limits and original-call recovery remain independent from attachment delivery.
+
+- Explain each search target’s returned candidates separately from the conversation’s
+  currently loaded tools. Keep unknown totals explicit and describe the shared loading limit.
+- Return actionable, safe failure feedback through native DSH dispatch, including retired
+  tool names rejected before the business SDK. Valid loaded tools remain directly callable.
+- Keep an unconfirmed write bound to its original invocation; discovery cannot create
+  a replacement operation. Add read-only feedback seams for custom hosts.
+- See [capability discovery and recovery](docs/CAPABILITY_FEEDBACK.md) for shop/inventory
+  examples, compatibility and exact candidate installation requirements.
+
 ## 0.5.0 - 2026-09-10
 
 ### Shop and inventory in one conversation

package/PRIVACY.md

@@ -104,8 +104,12 @@ Hidden reasoning is never uploaded by the adapter.
 
 The host checks the captured connection key, workspace, and original Agent Session id before
 transport operations without projecting those inspection fields into the model's directory.
-Invocation bindings are local to the running conversation; a new conversation or process restart
-does not recover unknown invocation ids from that map.
+Invocation bindings stay host-side. The [durable recovery journal](docs/INVOCATION_RECOVERY.md)
+adds a separate `invocation-records` store in the plugin data directory for original binding
+metadata, parameter/receipt digests, last-known state and retry deadline. It stores no raw
+arguments, receipt bodies, credentials or conversation text. Records remain until the host/operator
+removes them; there is no automatic cleanup or upload of this journal. The same original Session
+can recover known calls after reopening; new conversations and unknown IDs cannot use that binding.
 
 The default file adapter saves scope schema/version, DSH session id, revision, lock/state, public
 Hub/client/workspace binding, and the selected connection keys, sanitized labels, workspace, and
@@ -123,8 +127,9 @@ loading it does not query its old authorizations or send them user input. A fail
 write can leave that draft on disk, but it still cannot reactivate automatically in a new runtime.
 Configuration or metadata history alone does not lock a never-started draft. Missing or invalid
 scope snapshots on started conversations do not adopt current registry connections.
-Restoring that scope does not recover pending business invocations, approvals, completions, or
-tasks across a process restart.
+Restoring the scope alone does not recover pending business invocations, approvals, completions,
+or tasks across a process restart. Original invocation recovery requires the separate durable
+journal and an explicit recovery request; it does not automatically resume the whole task.
 
 ## Visible conversation archive
 
@@ -151,7 +156,8 @@ Network failures preserve successfully written events for later upload. Local wr
 not prove durable capture. Reopened DSH history is checked for detectable missing visible events,
 reported as `recovery_gap`; unavailable host history is marked unverified. Previously unarchived
 messages, attachments, and hidden content are not claimed as a complete transcript. The archive
-does not restore business invocation or approval execution after restart. An older SDK reports
+does not itself restore business invocation or approval execution after restart; the separate
+invocation journal does not make an incomplete visible archive complete. An older SDK reports
 unsupported without creating an outbox, and business calls remain available.
 
 An offline reopen keeps the original frozen scope closed until every member can be revalidated.
@@ -159,3 +165,8 @@ A later retry on the same runtime may recover a temporary network failure, but c
 confirmed revocation, replacement identity, or a storage conflict. Archive status retains known
 unsaved events and history gaps while upload is blocked. Revocation confirmed during asynchronous
 archive capability discovery or opening is rechecked before reporting availability or uploading.
+
+
+## Task records in 0.6.0
+
+A private persistent task store binds the original Session, fixed members and administrator-created task. It does not store administrative credentials or grant model task-management authority. Retain original scope, task, invocation and archive records; storage errors never downgrade to an unrestricted flow. Task enrollment persists on the original Agent Session even after cancellation. Do not downgrade an enrolled authorization to a host/Core that ignores that requirement. See [task control](docs/TASK_CONTROL.md) and [upgrade](docs/UPGRADE_v0.6.0.en.md).

package/README.md

@@ -1,5 +1,12 @@
 # BailingHub for DeepSeek Harness
 
+## 0.7.0: optional model services and plan billing
+
+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)
+
+
 [简体中文](docs/README.zh-CN.md) | English
 
 Ask your local DeepSeek Harness Agent to work with a business system connected to BailingHub:
@@ -28,18 +35,19 @@ that record fails, it can retry after reconnecting or restarting without repeati
 This is an independent community integration, not a plugin developed, certified, endorsed, or
 recommended by DeepSeek.
 
+
 ## Install and start
 
 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.7.0 → BailingHub MCP/SDK 0.5.0 → this plugin 0.5.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.5.0
+dsh plugin --profile web add dsh-bailinghub@0.7.0
 ```
 
-The plugin installs its exact `bailinghub-mcp-server@0.5.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
@@ -168,6 +176,7 @@ identity separately. Custom DSH hosts must implement the [scope selection and re
 and display confirmation before the first message. The native slash commands already use those
 APIs. Tool envelopes, persistence, event schemas, and recovery limits are documented in the
 [Agent Client contract](docs/AGENT_CLIENT_CONTRACT.md).
+For the Local Agent attachment space (image-first), see [host artifact integration](docs/GENERATED_ARTIFACTS.md). Register approved conversation outputs, upload them once, and use ready URLs with existing business tools.
 
 Use Native Tool Mode. DSH Code Mode is deliberately degraded because it cannot safely present the
 current-turn dynamic schemas. See the [compatibility matrix](docs/COMPATIBILITY.md).
@@ -182,3 +191,12 @@ legacy version when using that path and follow the [migration guide](docs/MIGRAT
 Report issues at [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues) with
 versions and redacted errors. Do not include tokens, private URLs, personal data, or production
 payloads. Compatibility tests and package downloads are not evidence of production adoption.
+
+
+## Recover an original action after reopening
+
+Version 0.6.0 adds a local invocation journal for actions such as a product listing
+awaiting approval or an inventory update whose response was lost. Reopen the same conversation
+and explicitly recover the original call without creating a second business request. Custom
+hosts must retain the new store alongside their existing Session scope. See the
+[recovery contract, limits and host integration](docs/INVOCATION_RECOVERY.md).

package/SECURITY.md

@@ -118,8 +118,11 @@ Each invocation binds its chosen authorization, Core run, and capability revisio
 accepts only an invocation known to this conversation and resolves its original binding; the
 model cannot provide a replacement authorization. Changing a default connection cannot retarget
 an existing call.
-This invocation map lasts only for the live conversation: later turns can recover its original
-calls, while new conversations and process restarts must reject unknown invocation ids.
+The live invocation map supports later turns of the same conversation. The unreleased
+[durable recovery journal](docs/INVOCATION_RECOVERY.md) additionally persists original
+metadata before dispatch and validates it after reopening. New conversations, missing records,
+and conflicting original identities still reject recovery. Raw parameters and credentials do
+not belong in the invocation journal; model text never reconstructs its authority.
 
 Only non-secret scope metadata belongs in the scope store. Its default file store uses SHA-256 session filenames,
 mode-0600 files and mode-0700 directories on POSIX, bounded reads, rejection of symlinks/non-regular files,
@@ -174,3 +177,8 @@ that validation. Confirmed revocation/replacement and storage/CAS conflicts rema
 blocked, with no default or subset fallback. The gate is rechecked after asynchronous archive
 capability discovery and outbox opening; a late result cannot erase a confirmed revocation.
 Known local storage errors and capture gaps remain visible even while network or scope checks block upload.
+
+
+## Task records in 0.6.0
+
+A private persistent task store binds the original Session, fixed members and administrator-created task. It does not store administrative credentials or grant model task-management authority. Retain original scope, task, invocation and archive records; storage errors never downgrade to an unrestricted flow. Task enrollment persists on the original Agent Session even after cancellation. Do not downgrade an enrolled authorization to a host/Core that ignores that requirement. See [task control](docs/TASK_CONTROL.md) and [upgrade](docs/UPGRADE_v0.6.0.en.md).

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -1,5 +1,12 @@
 # Agent Client Host Adapter Contract
 
+The additive [session tool reuse contract](SESSION_TOOL_REUSE.md) is explicitly
+enabled with `createAgentClientPlugin({ toolLifecycle: 'session', ... })`. It uses
+lazy current-turn target preparation for one or many selected authorizations,
+and retains bounded declarations between messages. The lifecycle descriptions
+below remain the default `active_turn` behavior unless that option is enabled.
+Neither mode changes fixed scope, business approval or original-invocation recovery.
+
 ## Authorization subject display (0.5.0)
 
 The business backend may supply `subject_display: { name }` for the subject actually approved by
@@ -133,12 +140,14 @@ Each alias enumerates only its own `authorization_ref` values and wraps unchange
 snapshots and original target bindings remain fixed on replay. The SDK receives host-only
 `expectedBinding: { hubUrl, clientAppId, workspace, sessionId }` together with an explicit key
 on status and all business calls. Model arguments cannot replace these fields.
-Explicit search prioritizes that target's results inside the existing twelve-tool budget;
+Explicit search prioritizes that target's results inside the twelve-schema window while retaining up to 64 callable tools;
 same-named capabilities on earlier targets cannot permanently crowd it out.
 
 Recovery accepts only a known original invocation. When needed in a later live turn, it opens
 only that original target's run with a recovery-specific input and resumes the original invocation;
-it does not call the business action again. It does not restore invocation state after process restart.
+it does not create a replacement invocation. The [durable recovery journal](INVOCATION_RECOVERY.md)
+can restore original binding metadata after process restart; scope or archive restoration alone
+cannot. Explicit Core resume may continue the original approved operation.
 Cancellation and superseding turns cannot register tools or dispatch a new write from a late start.
 Each cross-system turn owns an AbortSignal combined with the host's signal. SDK dispatch checks
 that signal after local IO and before HTTP; an in-flight write with an unknown outcome keeps its
@@ -218,7 +227,7 @@ attribution; all injected context still shares the local Agent/model boundary de
 Business definitions with the same name, description, input schema, and governance are registered
 once.
 Conflicting declarations are not merged for execution. Availability remains specific to each
-authorization, and the conversation's total active business-tool limit remains 12. In a
+authorization, and the conversation's retained business-tool limit is 64, with at most 12 full schemas shown at once. In a
 multi-authorization session, each shared definition wraps its unchanged business schema:
 
 ```json
@@ -241,9 +250,10 @@ invocation known to this conversation and uses the original binding; it accepts
 authorization selector. Pending approval and unknown dispatch outcomes follow the same
 exact-invocation recovery rules as the baseline. Removing or selecting another default must not
 retarget an existing invocation.
-The local invocation map survives later turns of the same live conversation. It is not persisted
-across process restarts or copied into new conversations, and unknown invocation ids fail closed.
-This increment does not provide durable task recovery across those boundaries.
+The local invocation map survives later turns of the same live conversation. The
+[durable recovery journal](INVOCATION_RECOVERY.md) can restore trusted original binding metadata
+across process restarts, never into another conversation. Unknown IDs fail closed. This is
+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
@@ -522,7 +532,8 @@ exactly `bailing.agent-turn-context.v1`. Its runtime result is:
 }
 ```
 
-At most 12 active tools are accepted. Each tool must use the Core tool-name grammar, an
+At most 12 active tools are accepted per Core response. Further searches can accumulate
+up to 64 retained tools in this active turn; see [discovery lifecycle](CAPABILITY_FEEDBACK.md). Each tool must use the Core tool-name grammar, an
 object-rooted input schema, and complete governance metadata (`scope`, `risk`,
 `approval_required`, `readonly`, and `idempotent`).
 Both revision fields are required lowercase 64-character SHA-256 values; shorter labels or
@@ -668,3 +679,12 @@ Missing/invalid configuration, missing SDK, failed authorization, failed Core co
 collision, or unsupported DSH Code Mode removes the Core business tools and inserts a concise
 status section. The local Agent may continue using unrelated local tools, but it is explicitly
 told not to claim a BailingHub business action was executed.
+
+
+## Original invocation recovery after reopening
+
+See [the durable recovery contract](INVOCATION_RECOVERY.md) for the additive
+`invocationStore`, `getSessionInvocationStatus(sessionId)` and
+`restoreSessionInvocations(sessionId)` host interfaces. They do not replace the fixed
+scope, original visible-event archive, or attachment store. A host using its own scope
+store must explicitly provide durable invocation storage to support full reopening.

package/docs/CAPABILITY_FEEDBACK.md

@@ -0,0 +1,199 @@
+# Discover capabilities and recover the right operation
+
+DSH 0.6.0 improves the information the Agent receives. Use the paired SDK 0.6.0 and Core 0.8.0 for authoritative counts and feedback. Existing authorization, approval, fixed conversation scope and archive rules still apply.
+
+## What users should notice
+
+For example, an Agent checks warehouse stock and then updates a shop product.
+
+- A currently loaded shop tool can be called directly for its selected account.
+- The Agent can discover product creation, create a product, discover a query tool,
+  check the result, and return to product creation without another search. Searching
+  warehouse tools also retains valid shop tools within the current turn.
+- Only 12 full schemas are shown at a time; up to 64 discovered business tools remain
+  registered and directly callable with their original target and known parameters.
+  This is a tool-type budget, not a limit on operations, products or task duration.
+- Hosts can opt into [cross-turn declaration reuse](SESSION_TOOL_REUSE.md) with
+  `toolLifecycle: 'session'`. A cached tool is prepared with current target context
+  before use in a new turn. The default remains `active_turn`.
+- If the shop request was sent but its response is unconfirmed, recover only its
+  original invocation. A new search or tool name must not produce another write.
+
+Business systems still define their own product fields, validation and approvals.
+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
+requires the original `authorization_ref` and a minimal target-specific query.
+Single-account and same-system selection continue to work.
+
+| Field | Meaning |
+| --- | --- |
+| `discovery.returned_count` | Candidates actually returned for this search target |
+| `discovery.authorized_total` | Tools in the same authorization-filtered catalog; `null` when unknown |
+| `discovery.matched_total` | `null`: ranked candidates do not establish an exact match count |
+| `discovery.truncated`, `has_more` | Whether authorized catalog candidates were omitted by the search limit; `null` when unknown |
+| `discovery.truncation_scope` | `authorized_catalog` when reported, otherwise `unknown` |
+| `discovery.mode` | `ranked_candidates`, or `unknown` for older/malformed optional metadata |
+| `discovery.pagination` | `unsupported`; the result does not promise complete paging |
+| `active_tools` | Business tools ready for dispatch in the current turn, with their target references where applicable; session-mode cached preparation guards are listed separately in `cached_tools` |
+| `toolset.active_count`, `limit` | Current registered business-tool count and shared ceiling of 64; search/resume/local tools do not consume this budget |
+| `visible_tools`, `toolset.visible_count`, `visible_limit` | Current full-schema presentation window, capped at 12 across targets; absence here does not mean unloaded |
+| `toolset.retained_outside_window_count` | Registered tools outside that window, still callable using the exact schema already discovered |
+| `toolset.lifetime` | `active_turn`: one user message through its completion/cancellation, including all intermediate searches and operations |
+| `toolset.reuse`, `cache.lifetime` | `session_runtime` only when the host opted into cross-turn declaration reuse; does not change the current-run execution lifetime |
+| `toolset.generation` | Local collection generation, separate from Core's capability revision; compare only within the same runtime/session |
+| `toolset.omitted_tool_count` | Compatible cached candidates omitted by the shared budget, not all unreturned Core capabilities |
+| `toolset.conflicting_tool_count` | Excluded shared declaration conflicts plus per-target contradictory catalog entries |
+| `toolset.catalog_conflict_count` | The per-target contradictory catalog portion of that count |
+
+Multi-account results place `discovery` under each searched `authorizations[]`
+entry. The top-level `toolset` covers the whole conversation, not just that target.
+The existing top-level `omitted_tool_count` remains as a compatibility alias for
+the shared-budget count. `toolset.update=merge` describes the registration policy, consistently for one or
+many accounts. Per-target `candidate_update=merge` means the new results were added
+under the same authoritative catalog revision; `reset` with
+`invalidation_reason=capability_revision_changed` invalidates that target's old
+cache before retaining the new response. Tools from other targets keep their own
+revisions. `evicted_count` counts candidates removed by the per-target cache cap
+in this update; it is not a catalog total.
+
+If the same target, revision and tool name claim different declarations, that
+name is quarantined for the revision. `conflicting_tools` and structured
+`feedback.category=capability_changed` explain the exclusion. Other valid tools
+remain available. The runtime never silently reinterprets old arguments under the
+new declaration. An authoritative new revision can remove the quarantine.
+
+An unrelated query can still return ranked candidates. Neither an empty result
+nor a transport failure proves that the entire business system lacks a feature.
+Optional metadata from older components is unknown, never a fabricated zero.
+
+## Long-task lifecycle and safety
+
+Discovery merges only tools actually returned for selected authorizations; it does
+not preload a system's whole catalog. An empty successful search with an unchanged
+revision or a temporary search failure preserves prior valid candidates. A new
+revision clears that target's old candidates even if the new response is empty.
+Core still checks the original identity, allowed surface and revision before each
+new invocation; local retention does not extend permission or skip approval.
+
+In the default `active_turn` mode, each target retains up to 64 recently
+discovered/used declarations. The shared
+registry also caps at 64, favoring recently searched/used tools; the schema window
+favors the latest search and subsequent use. Candidates outside the registry cap
+need discovery again. Tools merely outside `visible_tools` do not. This keeps
+memory and prompt costs bounded without forcing a search for every call.
+
+With `toolLifecycle: 'session'`, the declaration cache instead shares a total
+budget of 64 target-tool pairs and 2 MiB of JSON across the living Session. Its
+12-schema presentation window remains separate. New turns prepare only targets
+actually needed, using new context and runs; exact valid cached declarations
+avoid an extra search request. Core's existing `startTurn` may still perform
+bounded internal discovery. See the [session lifecycle contract](SESSION_TOOL_REUSE.md)
+for `cached_tools`, target readiness and preparation-only call handling.
+
+The registry applies differences rather than clearing all registrations on every
+search. Unchanged definitions keep their registration; changed schemas or target
+enumerations are retired individually. Searches are serialized within the turn;
+independent calls keep their original invocation bindings while discovery runs.
+An invocation already issued keeps its original arguments, revision, authorization
+and ID regardless of cache eviction. Resume never creates a replacement write.
+
+Completion, cancellation, scope failure and a new user turn retain their existing
+boundaries: ended turns cannot accept late search results or reactivate tools.
+The default cache ends with the active turn. Opt-in session-mode declarations
+can survive between turns in the same living runtime; they are never reused as
+authorization or old run context, and are not persisted across restarts. Archive
+events, original run links, ACK/CAS and attachment upload identities are unchanged.
+Original invocation metadata can be persisted separately by the
+[durable recovery](INVOCATION_RECOVERY.md); it does not restore the old tool cache.
+
+## Structured failure feedback
+
+Failures carry `bailing.agent-feedback.v1` with `category`, `code`, `origin`,
+`operation`, `dispatch`, `retryable`, `next_action`, a controlled `message`, and the
+original `invocation_id` when one exists. SDK-defined feedback is projected through
+a safe allowlist; raw transport messages and arbitrary extra fields are omitted.
+
+`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.
+
+| Category | Intended next step |
+| --- | --- |
+| `tool_not_loaded` | Rediscover the same selected target, unless an existing invocation needs recovery |
+| `capability_changed` | Check the current declaration; an original recovery stays bound to the original invocation |
+| `transport_unavailable` | Retry discovery or original identity validation/recovery as indicated |
+| `authorization_unavailable` | Restore/confirm the original scope or reauthorize; do not use defaults or a surviving subset |
+| `unsupported` | Check the supported component combination; arbitrary 404/503 errors are not version evidence |
+| `invocation_outcome_unknown` | Resume or inspect the original invocation; never create a replacement write |
+| `cancelled`, `invalid_request`, `unknown_failure` | Follow the explicit action; do not guess a business retry |
+
+Core's `reconciliation_required` result remains a non-auto-retry result. Its
+feedback says `inspect_original`; ordinary resume may only replay the recorded
+uncertainty and can require an operator to verify the result.
+
+An authoritative original-record lookup failure also requires inspection:
+`code=invocation_not_found`, `category=invocation_outcome_unknown`,
+`next_action=inspect_original`, `retryable=false`, `original_outcome=unverified`.
+The plugin stops the current recovery poll and preserves the original invocation ID.
+For example, a host may have saved a shop listing's dispatch fence before it crashed,
+while the request never reached Core. That is only one possible cause: a missing
+record does not prove that the listing was never performed. Do not recreate it from
+the conversation or switch accounts. Generic 404/network errors cannot establish
+this condition. See [recovery failure rules](INVOCATION_RECOVERY.md#failure-and-compatibility-rules).
+
+## Client host integration
+
+Standard native DSH uses the existing `tools/execute` hook. Error results retain
+`isError=true` and the original host error information, while carrying the same
+safe feedback in `result.meta.bailinghub.feedback` and JSON text content
+`{"feedback": ...}`. Ordinary multi-target search can succeed overall while a
+target entry contains `state=unavailable` plus its own `feedback`.
+
+Only BailingHub-owned tool failures are decorated. Host `UNKNOWN_TOOL` is classified
+as retired only for a previously registered business name in that conversation
+which is no longer registered. Other plugins, unknown names, currently registered
+tools hidden by host presentation, and reserved tools are not reclassified.
+
+Two read-only runtime methods support hosts which intercept dispatch earlier:
+
+```js
+runtime.getSessionToolState(sessionId)
+// { state, toolset, active_tools, visible_tools }; no HTTP requests or new business run
+
+runtime.getToolDispatchFeedback(sessionId, {
+  toolName, callId, errorCode: 'UNKNOWN_TOOL',
+})
+// feedback or null; call only after the host registry actually rejects lookup
+```
+
+Pass the original call ID. If that call already has an invocation, feedback points
+to that original ID instead of suggesting a new operation. These methods do not
+execute or restore tools and must not be used to bypass normal scope validation.
+Do not filter dispatch against `visible_tools` or the latest search response: the
+native registry and `active_tools` determine retained availability. Do not cache a
+stale copy of the registry or demand discovery before every call. Keep all new
+fields in model-facing search results. Custom hosts which only allow names in the
+current schema window need to support retained native registry dispatch; otherwise
+their presentation layer can still produce an artificial `UNKNOWN_TOOL`.
+No new user/assistant message upload path is needed.
+
+Session-mode hosts must also preserve `targets`, `cached_tools`, `contexts`,
+`tool_schemas` and the preparation result's `business_operation_performed=false`.
+An unprepared cached tool name can return preparation and schema without performing
+the requested operation. The model must read current context and issue a new call
+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.
+
+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
+insufficient: the host may discard them. Older SDK/Core combinations retain their
+business flows, but may lack precise counts or authoritative error detail.
+
+These discovery and tool-lifecycle changes require no credential, scope or archive conversion. Follow the [release upgrade guide](UPGRADE_v0.6.0.en.md) for the complete release, including Core migrations for attachments, limits and task controls.

package/docs/COMPATIBILITY.md

@@ -1,22 +1,32 @@
+# Current 0.7.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).
+
 # Compatibility
 
-## Native Agent Client 0.5.0
+## Capability feedback
+
+The additive [capability feedback contract](CAPABILITY_FEEDBACK.md) requires the paired
+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
 
 | 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.5.0` via `./sdk` |
-| BailingHub Core | `bailinghub@0.7.0`, with outstanding migrations through 059 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.5.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
 
@@ -68,7 +78,10 @@ New conversations need explicit scope selection before the first message. Custom
 and display selection, preserve the stable conversation id, and restore the original scope before
 sending on reopen. Missing started-session snapshots stay blocked. Saved drafts require fresh
 confirmation. Scope restoration and archive synchronization do not recover business invocations,
-approvals, or task execution after a process restart.
+approvals, or task execution after a process restart. The
+[invocation recovery journal](INVOCATION_RECOVERY.md) supplies a separate durable journal
+for explicit recovery of original calls. Custom scope-store hosts must explicitly provide
+`invocationStore`; existing calls remain available if they have not enabled that feature.
 
 Temporary network failure during reopening is retryable on the same runtime under the complete
 original scope. Confirmed revocation, replaced identity, or storage/CAS conflict stays blocked.

package/docs/CROSS_SYSTEM_CONVERSATIONS.md

@@ -82,8 +82,10 @@ installing this plugin does not migrate or deploy the Hub.
   and multiple selected routes sharing one Agent Session are not supported.
 - Task planning and step ordering are performed by the Agent. This is not a deterministic
   dependency engine, a distributed transaction, automatic rollback, or cross-process task recovery.
-- Original invocation recovery is available in later turns of the same live runtime. Archive
-  restoration after restart does not reconstruct pending invocations or approvals.
+- Original invocation recovery is available in later turns of the same live runtime. The
+  unreleased [durable recovery candidate](INVOCATION_RECOVERY.md) adds explicit recovery after
+  restart when the host retains its invocation journal. Archive restoration alone does not
+  reconstruct pending invocations or approvals.
 - Different systems' object IDs are unrelated unless a verified business mapping establishes
   the relationship. The Agent must clarify an ambiguous mapping.
 - The runtime enforces target and capability boundaries. It does not provide automatic

package/docs/GENERATED_ARTIFACTS.md

@@ -0,0 +1,77 @@
+# 本地智能体附件空间：DSH 宿主接入
+
+智能体生成或用户明确指定用于业务的图片，可以用于活动海报、内容封面、经营图表，也可以用于商城商品。宿主把当前会话获准使用的图片登记到附件目录，插件提供目录查询和上传工具；模型选择目标授权与附件引用，中枢保存图片并返回 URL，供后续业务工具使用。图片不必在当前轮生成；仅用于聊天理解的附件不会因此自动登记或上传，聊天附件历史存档是另一项独立能力。
+
+首期支持 PNG、JPEG、WebP。附件空间提供会话级目录、上传与上传结果恢复，不把 PDF、Word、视频或完整网盘管理写成已经交付的能力。业务系统需要预先提供相应的图片 URL 接口。
+
+配套版本：Core 0.8.0 / SDK 0.6.0 / DSH 0.6.0。新能力需部署方升级并按宿主契约接入；业务权限、审批和原身份约束保持。
+
+## 宿主需要接哪两处
+
+```js
+import { createAgentClientPlugin, createFileArtifactStore } from 'dsh-bailinghub'
+
+const plugin = createAgentClientPlugin({
+  // 保留原 SDK、scopeStore、archiveStore 等配置。
+  artifactSource: {
+    async list({ sessionId }) {
+      // 从本会话已获准用于业务的图片中读取；只返回元数据，最多 100 项。
+      return [{ artifactRef: 'campaign-banner', name: 'campaign-banner.png',
+        mime: 'image/png', bytes: generatedSize, sha256: generatedDigest }]
+    },
+    async read({ sessionId, artifactRef }) {
+      // 宿主按已登记引用读取获准文件，返回 Uint8Array。
+      // 检查归属、允许目录、符号链接及读取期间文件变化；不要直接拼接模型给出的路径。
+      return generatedBytes
+    },
+  },
+  artifactStore: createFileArtifactStore({ directory: artifactRecoveryDirectory }),
+})
+```
+
+`artifactRef` 是宿主管理的稳定引用，允许字母、数字、下划线和短横线，最多128字符；不可把同一个引用改指另一份文件。同名图片可以用不同引用。目录属于真实 DSH Session，重新打开时保持原归属；后台持久化上传元数据目录同样需要跨重启保留。也可实现自有 `artifactStore.get(uploadId)` / `reserve(record)`：reserve 必须原子、只写一次并返回先前记录或新记录，落盘完成才成功返回。内存 store 仅用于测试或明确的临时会话。
+
+未提供 artifactSource 时不会新增模型工具，已有业务流程不变。缺少持久恢复 store 时上传返回 storage_error，并且不会发送文件。
+
+## 模型实际能用的工具
+
+- `list_generated_artifacts`：读取当前会话产物目录，不返回路径或文件正文。
+- `upload_generated_artifacts`：必须明确 `authorization_ref` 与 `artifact_refs` 数组；每批1–8张，单张不超过6MiB，支持PNG/JPEG/WebP。
+
+上传成功后模型直接使用 ready URL，不需要为每次使用重复查询地址或上传。只有不确定的上传结果或会话重开恢复才查询原上传记录。
+
+业务操作独立执行并单独判断结果。例如更新商城轮播图时，所有必需图片 ready 后再提交完整清单，保留未被要求删除的旧图片；业务结果未知时保留原 invocation，不能重发写操作。
+
+模型不选择桶或密钥。中枢管理员在“智能体客户端 → 配置接入 → 工具与审批 → 生成图片上传”选择媒体存储。第一期图片用于公开展示；普通COS/OSS或显式本地存储都由部署方管理保留，不增加文件到期判定。
+
+## 失败和重开
+
+### 跨轮上传与旧错误记录恢复
+
+新上传只关联目标授权**当前轮次的 active run**。跨系统按需启动业务 run；该目标当轮尚未启动时，上传使用原会话与当前轮次、不带可选 runId，既不沿用上轮记录，也不为上传额外创建业务 run。
+
+旧候选可能保存了“本轮上传 + 上轮 run”的记录。只有配套 Core 返回 `artifact_run_turn_mismatch`（同一原身份、路由、会话均一致，仅轮次不同），且再次读取原上传 ID 明确返回 `artifact_not_found`，DSH 才自动纠正。泛化的 `artifact_run_mismatch`、授权失效、网络错误或结果未知都不能触发纠正。Core 的身份和关联检查保持生效。
+
+纠正不覆盖原恢复记录：通过现有 get/reserve 原子保存独立的 `bailing.artifact-run-link-repair.v1` 记录，保留原记录摘要和原上传 ID。修正元数据只删除已证明属于另一轮的 runId，保留原上传会话、轮次、内容及目标；实际 HTTP 始终使用原上传 ID。宿主应完整保存记录中的 `runLinkRepair` 字段，不把这个本地记录键当成新增云端上传或新产物。无需新增 store 方法。
+
+纠正必须落盘后才补传；已 ready 的原回执直接复用，pending 不改绑，确认丢失后读取原 ID。原记录或纠正记录缺失、损坏时返回 storage_error，不根据服务端 URL 猜补本地历史。旧 Core/SDK 没有精确错误码时，旧错链记录继续明确阻断；当前正确链接的新上传仍兼容原附件 API。
+
+两个工具名中的 `generated` 为兼容保留，不限制来源必须是 AI 生成。宿主需要更新自己的目录说明，让用户明确指定业务用途的图片可以受控登记，不新增聊天附件自动同步或用户手动上传入口。
+
+每文件上传身份绑定原真实 Session、连接与产物引用，首发前原子保存原 Hub/client/workspace/Agent Session、内容摘要、名称和原会话/轮次/run关联。重试或重开先读取原中枢记录，成功项直接复用 URL；pending 或尚未写入时补传原文件。即使原文件已不可读，已确认成功的上传仍可恢复。
+
+批量结果包含 `results`、`all_ready` 和 `business_operation_performed=false`。每项为 ready、pending 或 blocked。成功项保留，失败项独立处理；不要因部分上传成功就写入残缺图库。
+
+本地持久化失败返回 storage_error；原记录损坏或丢失须由宿主标记恢复缺口，不能猜补原历史。暂时网络失败可以在同一 runtime 重试，保留原记录。任何原授权成员撤销或改绑时整组阻断，不退回默认、子集或替代 Session。取消后迟到上传不会重新注册业务工具或返回可继续执行的轮次；已经保存的对象及原记录仍可在合法恢复时查询。
+
+旧SDK/Core返回artifact_unsupported，保留原业务工具能力。Lazy SDK transport 已转发新增接口，但宿主仍必须实际提供生成文件来源。测试替身与真实对象存储连通性分开验收。
+
+## 业务后端要不要改
+
+如果原业务能力已经接收图片 URL，不必改授权或审批规则。客户端将 ready URL 作为原业务参数传入即可。需要业务自身素材ID、转存或素材库归属时，另接该系统的业务导入能力。
+
+## 分开记录的已知限制
+
+配套 Core 0.8.0 已提供可配置的中枢工具限额，小时/日额度按原窗口计数，并为新调用保留加密原参数。DSH 读取 `retry_after_ms`，等待后只恢复原 `invocation_id`；长于自动等待预算时返回 `agent_client_wait.state=rate_limited`，保留等待时间和原调用。手动过早恢复也不向中枢反复请求。原权限、审批、取消和授权目标约束继续生效；旧 Core 不返回提示时仍沿原恢复流程。
+
+当前列表工具的源错误可能经过通用分类变成 unknown_failure；宿主应保留自己检查到的 storage_error/recovery_gap，不能将其描述为空目录。上传工具仍返回逐项错误。不要用新业务调用或重新上传已经 ready 的附件掩盖这些问题。