dsh-bailinghub 0.4.0 → 0.6.0

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -1,17 +1,187 @@
 # Agent Client Host Adapter Contract
 
-Status: native Agent Client contract for `dsh-bailinghub@0.4.0`, paired with
-`bailinghub-mcp-server@0.4.0` and recommended BailingHub Core `0.6.1` (minimum API version
-`0.6.0`). This contract is separate from the legacy static `0.1.x` path. Version 0.3.0 supported user-managed connections but did not include
+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
+the user. A subject can be an organization, account, project, department, workspace or another
+business entity; the upstream contract does not prescribe a store or any particular product.
+The name is display data, separate from both trusted authorization identity and `system_info`
+(the product's purpose). Only the trusted business backend supplies this name; the DSH model,
+local alias, device label and principal identifiers are not sources for it.
+
+The matched SDK exposes these additive fields on `login`, `status` and every `connectionsList`
+entry, and the plugin passes them to its host:
+
+| Field | Meaning |
+| --- | --- |
+| `subjectDisplay` | `{ name: string }`, or `null` when unavailable |
+| `subjectDisplayStatus` | `provided`, `missing`, `unsupported` or `unavailable` |
+| `subjectDisplaySource` | `verified` after the SDK reads the original Session, `cache` for display-only local data, otherwise `none` |
+| `subjectDisplayCacheStatus` | SDK auxiliary cache outcome: `saved`, `storage_error` or `not_cached` |
+| `displayLabel` | Plugin presentation label: the provided name, otherwise `Authorization name pending sync` |
+
+Names are trimmed, nonempty, at most 120 UTF-16 code units, with C0/C1 controls and Unicode line
+separators U+2028/U+2029 and unpaired surrogate code units rejected. Valid Unicode emoji are
+preserved. Only the `name` field enters model assembly. A matching name
+does not establish an identity or a business relationship. Cached display data proves no current
+authorization; a real identity-validation failure still blocks the complete original scope.
+An old SDK without these fields yields `unsupported`; a supported response without a name yields
+`missing`. Neither condition prevents the existing authorized tools from working. A display-cache
+write error stays auxiliary and cannot replace a scope/archive `storage_error` or `recovery_gap`.
+
+Custom hosts may omit a user-entered remark/name field and render the returned business name.
+Keep the internal `connectionName` selector and fixed `connectionKey` independently; do not rename,
+merge or recreate credentials because two subjects have the same name or an existing subject is
+renamed. A host may combine a separately trusted product name with this subject name for display.
+When unavailable, localize the generic pending-name message; never guess the name from a product
+description, local alias, principal identifier or list order. Older hosts can keep their current
+connection-management UI unchanged.
+
+`setSessionScope`, `getSessionScope` and `restoreSessionScope` add `subjectDisplay`,
+`subjectDisplayStatus` and `subjectDisplaySource` to each visible authorization. The legacy `label`
+is the frozen historical value: newly selected scopes capture the supplied name (or the generic
+pending-name label), while existing stored labels remain byte-for-byte unchanged. Hosts should
+render the new display fields for current names, not reinterpret an old `label` as verified metadata.
+
+After the whole scope is validated, current display fields are held separately in coordinator
+memory. They do not enter binding comparisons, persisted v1/v2 scope records or archive identity.
+Single, same-system and cross-system model directories include `subject_display`,
+`subject_display_status` and `subject_display_source`, separately from `system_description` and
+`metadata_status`. The current directory `label` and attributed tool-result label use this display
+projection; the original `authorization_ref` remains the only model target selector.
+Scope revalidation refreshes current names without changing the selected members, original Agent
+Sessions, frozen scope revision, historical labels, visible events or archive context. Normal archive
+ACK writes continue their existing CAS sequence; display refresh itself writes no archive record.
+
+## System descriptions (0.5.0)
+
+Core 0.7.0 and SDK 0.5.0 add optional `transport.getSystemInfo({ connectionKey,
+workspace, expectedBinding, signal })`. After the entire selected scope has passed identity
+validation and before first model assembly, the adapter reads one description for each original
+selected member. Requests include the original Hub/Client/workspace/Agent Session binding and
+never user text, tools, or a run identifier. They do not create business runs or load business
+context. Single, same-system multi-authorization and cross-system conversations use the same
+description projection. The existing same-system first-turn run policy remains unchanged.
+
+The response schema is `bailing.agent-system-info.v1`. Only `system.name`, `summary`, `domains`,
+and `boundaries`, their metadata status/revision, and availability enter the model directory.
+System references derive from the verified binding, including for a single authorization or
+same-system group. Product purpose describes typical use; it does not grant an action or prove
+that any tool is enabled. `not_loaded` means not yet loaded, not no capabilities. Product purpose,
+authorization limits, tool loading and availability remain separate fields.
+
+Descriptions are data, not executable model instructions. Missing configuration, an absent SDK
+method, an unsupported old Core or a temporary metadata failure degrades description fields to
+unknown without changing existing capability search. A 401/403 or changed response binding
+blocks the original whole scope. Scope storage errors retain their existing priority. No description
+is persisted in the scope, Session events or archive outbox; each turn reloads against the original
+complete binding, so mutable labels or another runtime cannot supply stale system identity.
+Cancelled or superseded requests cannot publish late metadata or reactivate business tools.
+
+An exact HTTP 404 `route_unavailable` is different from unknown metadata: the selected target
+remains in the directory with `metadata_status: "unknown"`, `availability: "unavailable"` and
+directory-only `availability_reason: "route_unavailable"`. It is not old-version unsupported or
+an authorization grant/revocation. Other ambiguous failures stay unknown. The Core wire's
+`unavailable_reason` still accepts only the documented runtime/direct-switch reasons. A later
+turn retries the same original binding and clears the directory reason after successful lookup.
+
+Hosts keep the existing scope/restore/archive interfaces. The scope view now consistently includes
+`clientAppId` and `systemRef` for all selected authorizations; this is additive and does not change
+stored v1/v2 records. No local hard-coded product dictionary or extra body-reporting channel is
+required. A host may keep a separately controlled fallback when metadata is unavailable, but must
+not infer identity from local labels or expand the selected scope.
+
+## Cross-system extension (0.5.0)
+
+This extension requires SDK 0.5.0 and Core 0.7.0 with migration 058 applied. Subject display
+additionally requires migration 059. Existing same-system behavior, signatures and v1 records
+remain supported; old selected scopes never expand to include newly available targets.
+
+The host selects fixed connection keys from one normalized Hub. Different Client Apps or
+workspaces form different capability sources. Each target must have a distinct original Agent
+Session; two selected routes sharing a Session are rejected. A scope never expands to another Hub,
+registry default, newly added connection, or surviving subset after one member is lost.
+
+Cross-system scope uses persisted `bailing.agent-session-scope.v2` with shared `binding: { hubUrl }`
+and `authorizations` containing `{ connectionKey, sessionId, label, workspace, clientAppId }`.
+The host view keeps `bailing.agent-session-scope.v1` and adds `targetMode: "multi_system"` and
+per-authorization `clientAppId`/`systemRef`. Existing `authorizationRef`, key and lifecycle fields
+retain their meaning. System references are opaque identifiers for capability sources; labels
+remain descriptive data, not business identity or object mappings. The subject-display extension
+above separates current business names from historical local labels.
+
+Selection/restoration verifies the whole original group and calls SDK
+`getConversationArchiveCapabilities({ members })`. Support requires
+`schema: "bailing.agent-conversation-audit-capabilities.v1"`, `cross_binding_members: true`
+and `member_bindings: "session-client-route.v1"`. Missing support produces
+`CROSS_SYSTEM_SCOPE_UNSUPPORTED` and no cross-system business run. Temporary discovery failures
+remain retryable under the original selection; confirmed authorization replacement remains blocked.
+
+Initial prompt assembly registers the target directory, capability search and known-invocation
+recovery tools, without starting any business run. In this mode `search_business_capabilities`
+requires `{ authorization_ref, query, limit? }`. Its bounded query (up to 500 characters) is the
+task projection passed as `userInput` to that target's first `startTurn` in the current turn.
+The original visible user text stays in the independent archive. Subsequent searches reuse that
+target's run. Omission/unknown target fails before dispatch; another selected target is not
+started merely because its authorization is available. Authorization and archive membership checks
+may still inspect the full original set.
+
+Tools are grouped only by capability-source binding and complete declaration. Host-issued
+`bh_...` aliases keep same-named tools from different sources separate, even with identical schemas.
+Each alias enumerates only its own `authorization_ref` values and wraps unchanged business
+`arguments`. The server receives the original tool name. Revisions, invocation IDs, argument
+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 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 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
+original invocation identity. Completion summaries and archive upload are separate from business
+dispatch cancellation and may still synchronize after a turn ends.
+
+Cross-system archives use `bailing.agent-conversation-outbox.v2`. Context binding is `{ hubUrl }`;
+each member retains `{ connectionKey, hubUrl, clientAppId, workspace, expectedSessionId, label }`.
+Event/ACK schemas, random archive identity, source hashes, ordering, local capture-gap reporting
+and CAS semantics remain unchanged. The SDK uses explicit cross-binding create v2 and each
+member's own credential to confirm; the Core verifies each original app/route/Session and run link.
+The full transcript remains available only through the management audit read boundary.
+
+Query minimization, object mapping and step planning are Agent responsibilities. The runtime
+enforces target/tool/invocation authority; it does not establish a deterministic dependency DAG,
+cross-system transaction, automatic rollback or field-level data-transfer policy. Business systems
+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
+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
 explicit conversation scope, multi-authorization tool selection, or the visible conversation archive.
 
 ## Same-System Authorization Selection
 
-This increment supports multiple independently authorized identities for one public
-`Hub + clientAppId + workspace` binding in one DSH conversation. It does not combine different
-systems or routes, alter business capability declarations, or change Core authorization rules.
+The retained same-system path supports multiple independently authorized identities for one
+public `Hub + clientAppId + workspace` binding in one DSH conversation. It uses the existing v1
+records and shared capability declarations. The cross-system v2 path above handles different
+sources; neither path changes Core authorization or business approval rules.
 
-Version 0.4.0 changes the default: a new conversation with no selected scope, or an explicitly
+Version 0.4.0 changed the default: a new conversation with no selected scope, or an explicitly
 empty `connectionKeys: []`, is ordinary chat. It starts no BailingHub run and exposes no BailingHub
 business tools. Browser authorization, the registry's current connection, and the four bootstrap
 fields do not select a conversation's scope. There is no automatic discovery-and-enable fallback.
@@ -57,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
@@ -80,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
@@ -125,8 +296,10 @@ frozen scope unchanged. The host must open a new conversation, not treat that re
 successful selection of the requested keys. Revision values may advance more than once
 during selection; always use the returned value for the next compare-and-swap request.
 
-Each returned `authorizations` entry has exactly the public host-facing fields
-`{ authorizationRef, connectionKey, label, workspace }`. The selection accepts at most 64 unique
+Each `authorizations` entry retains the public host-facing fields
+`{ authorizationRef, connectionKey, label, workspace }`. Version 0.5.0 consistently adds
+`clientAppId`, `systemRef` and the current display fields documented above for single, same-system
+and cross-system scopes. The selection accepts at most 64 unique
 connection keys. The trusted host owns `sessionId`: it must remain stable when reopening the same
 conversation and be unique within that store's namespace. Do not let the model or an untrusted
 client choose another conversation's id, edit scope records, or control the storage namespace.
@@ -184,8 +357,10 @@ Restoring a scope does **not** restore an invocation, approval, pending completi
 
 ### Independent visible conversation archive
 
-The visible archive requires SDK `0.4.0` and Core APIs introduced in `0.6.0`; the recommended
-Core release is `0.6.1`. Earlier `0.3.0` SDK/plugin packages do not provide this contract.
+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
+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.
 The archive is one record for the complete fixed authorization set; per-authorization run summaries
@@ -357,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
@@ -503,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,6 +1,59 @@
+# Current 0.6.0 pairing
+
+Use Core 0.8.0, SDK 0.6.0 and DSH 0.6.0 for attachments, original receipts and task controls. Existing unenrolled flows retain their earlier protocol minima. Task enrollment persists: older hosts cannot omit task binding. See [upgrade](UPGRADE_v0.6.0.en.md).
+
 # Compatibility
 
-## Native Agent Client 0.4.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.6.0
+
+| Component | Release pairing / requirement |
+| --- | --- |
+| DeepSeek Harness | `0.1.1-rc.2`; real Session and native Cordis lifecycle |
+| Node.js | `^22.19.0` or `>=24.0.0` |
+| DSH tool presentation | Native Tool Mode; Code Mode deliberately degraded |
+| Generic Agent Client SDK | Exact `bailinghub-mcp-server@0.6.0` via `./sdk` |
+| BailingHub Core | `bailinghub@0.8.0`, with outstanding migrations through 062 applied |
+| Selected scope | Single account, same-system multiple accounts, or different Client Apps/workspaces on one Hub and audit domain |
+| Original authorization | A distinct original Agent Session for every selected target |
+| Persistence | Existing same-system v1 scope/outbox and cross-system v2 records |
+
+Install `dsh-bailinghub@0.6.0`; its ordinary dependency installs the exact SDK automatically.
+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).
+
+### Authorization subject display
+
+Core 0.7.0, SDK 0.5.0 and plugin 0.5.0 support business-supplied authorization names. New
+names are optional: an old SDK reports `unsupported`, a missing business name reports `missing`,
+and neither blocks the existing tools. A list may show cached display data without claiming it
+is fresh identity evidence. Current names and cache-write status remain separate from scope,
+credential, archive and business errors. Existing v1/v2 records need no conversion or new labels;
+names never replace their original key, binding or Session. See the
+[display contract](AGENT_CLIENT_CONTRACT.md#authorization-subject-display-050).
+
+### Cross-system scope
+
+Requires Core 0.7.0, SDK 0.5.0 and plugin 0.5.0. Core must advertise
+`cross_binding_members: true` and `member_bindings: "session-client-route.v1"` through
+`bailing.agent-conversation-audit-capabilities.v1`, with its additive target-member migration ready.
+The SDK must implement `getConversationArchiveCapabilities` and the `expectedBinding` dispatch guard.
+Cross-system selection refuses missing support before creating any business run. Existing
+same-system scope and archive interfaces continue using their v1 behavior.
+
+One Hub may contain different Client Apps and workspaces; every target must have a distinct
+original Agent Session. Multiple routes sharing a single Agent Session and cross-Hub conversations
+are outside this release. Hosts using custom stores must preserve scope/outbox v2 records with
+their original bindings and CAS revisions; do not convert v2 into v1 or reconstruct missing state.
+See [the cross-system guide](CROSS_SYSTEM_CONVERSATIONS.md) for usage and limits.
+
+## Historical native Agent Client 0.4.0
 
 | Component | Release pairing / requirement |
 | --- | --- |
@@ -15,7 +68,7 @@
 Core `0.6.0` is the minimum API version for this contract. Use Core `0.6.1` for the
 recommended release pairing; the patch does not change these business APIs.
 
-Install only `dsh-bailinghub@0.4.0`; its ordinary dependency installs the exact SDK. A release
+For this historical pairing, install `dsh-bailinghub@0.4.0`; its ordinary dependency installs the exact SDK. A release
 requires a registry-generated lockfile and a clean package/profile check. Local source and
 synthetic HTTP verification are compatibility evidence, not evidence of an organization's
 production use. The older 0.3 baseline is retained below for existing users, not as a claim that
@@ -25,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.
@@ -133,11 +189,13 @@ BailingHub Core release is compatible only after a separate clean legacy profile
 
 Compatibility requires independent evidence for both paths:
 
-1. Native 0.4: clean install of only the exact plugin package, browser authorization, workspace
+1. Native 0.5: 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
-   replay after a lost archive acknowledgement.
+   replay after a lost archive acknowledgement. Verify cross-system routing and same-named tools,
+   unselected-target isolation, metadata before tool search, and duplicate/renamed subject displays.
+   Metadata reads must create no business run; subject names must not change identity or scope.
 2. Legacy 0.1.1: clean static profile, fixed Client Token route, one submit, and same-job follow-up
    through the unchanged public Client API.