dsh-bailinghub 0.3.0 → 0.5.0

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -1,8 +1,403 @@
 # Agent Client Host Adapter Contract
 
-Status: public native Agent Client contract for `dsh-bailinghub@0.3.0`. This contract is not part
-of the legacy public `0.1.x` line. The multi-connection lifecycle described below is stable with
-BailingHub Core `0.5.1` and `bailinghub-mcp-server@0.3.0`.
+## 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 existing twelve-tool budget;
+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.
+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
+
+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 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.
+
+The host explicitly selects fixed SDK connection keys before sending the first user message.
+Exactly one selected authorization keeps the original typed arguments and result shape; two or
+more selected authorizations use the shared envelope below. All selected keys must be authorized
+under the same Hub/client/workspace binding. Unselected connections are never added to the scope.
+The model receives a projected directory containing
+session-local `authorization_ref` values, local display names, and availability, not raw connection
+keys, credentials, Agent Session metadata,
+or permission to supply arbitrary route or identity values. A local name is untrusted display
+data, not proof of a tenant or store. The model must resolve ambiguous user intent before acting;
+available authorization is not a request to act on every listed identity.
+Labels use existing local `connectionName` metadata, not token-derived business names or a new
+Core identity-display field. Generic aliases such as `default` and `default-2` do not establish
+an A/B business mapping; the user must supply clear labels while the business authorization page
+continues to determine the trusted identity.
+
+The directory's references resolve to the explicitly selected SDK connection bindings. The first
+`user/message` event freezes the selection, with `agent/inbox/claimed` as a fallback for drivers
+that do not emit that event, before `startTurn`. Changing the selected keys after
+that point requires a new conversation, including switching between ordinary chat and business
+mode. Adding a registry authorization or changing its alias never expands an existing scope.
+Capturing a binding does not freeze credentials or bypass refresh, expiry, revocation, or
+downstream authorization checks.
+Before transport operations, `status({ connectionKey })` must report the captured connection key,
+workspace, and the original authorized Agent Session id captured during selection. If any selected
+authorization is missing, invalid, replaced, or cannot be checked, business access for the entire
+conversation pauses. It neither falls back to a default nor silently shrinks to the remaining
+authorizations. A new conversation can explicitly select the still-valid subset. These inspection
+fields stay host-side. The
+adapter passes `connectionKey` and `workspace` as explicit SDK host metadata instead of
+resolving a mutable alias or default.
+
+The full selection is validated before any selected system receives the turn. For each direct
+user turn, the adapter starts one Core run per selected authorization before
+assembling the model request. Instructions, governance, knowledge, memory, and tool results carry
+authorization labels. The user input is sent to each of those runs. Separate run state preserves
+attribution; all injected context still shares the local Agent/model boundary described in
+[Privacy](../PRIVACY.md#same-system-authorization-selection).
+
+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
+multi-authorization session, each shared definition wraps its unchanged business schema:
+
+```json
+{
+  "authorization_ref": "<host-issued reference from this session>",
+  "arguments": { "<business parameter>": "<value>" }
+}
+```
+
+The selector is host metadata; it is not forwarded as a business argument or new Core HTTP
+field. A single-authorization session keeps the original unwrapped business schema.
+`search_business_capabilities` accepts an optional `authorization_ref` using the same reference
+boundary; omission searches all captured authorizations. Its responses update the selected
+authorizations' capability revisions and definitions before rebuilding
+the shared tool view. It cannot import a different binding into the conversation.
+
+Invocation state captures the selected authorization, Core run, capability revision, tool, and
+arguments. A replay with a different selector or payload fails closed. Recovery accepts only an
+invocation known to this conversation and uses the original binding; it accepts no replacement
+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.
+
+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
+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.
+
+### Host-owned session scope API
+
+The runtime service exposes asynchronous `getSessionScope(sessionId)`,
+`setSessionScope(sessionId, { connectionKeys, expectedRevision? })`, and
+`restoreSessionScope(sessionId)`. They are host APIs, never model tools. Use keys returned by the
+SDK registry, not aliases or model-provided identity values.
+
+Native DSH users can inspect `/bailinghub scope`, choose ordinary chat with
+`/bailinghub scope none`, or select fixed keys with `/bailinghub scope set <connection-key>...`
+before the first user message. Obtain keys from `/bailinghub connections list`; the scope command
+does not accept aliases, adopt a registry default, or start a business run. These are user-only
+commands over the same scope API.
+
+```js
+const runtime = ctx.get('bailingHubAgentClient')
+const previous = await runtime.getSessionScope(sessionId)
+const selected = await runtime.setSessionScope(sessionId, {
+  connectionKeys: selectedConnectionKeys, // [] explicitly chooses ordinary chat
+  expectedRevision: previous.revision,
+})
+// Render selected.mode and selected.authorizations, then enable sending.
+// Do not dispatch the first user message while this operation is pending or failed.
+```
+
+The returned view includes `schema`, `sessionId`, integer-or-null `revision`, `state`
+(`unselected`, `ready`, or `needs_selection`), `locked`, `mode` (`chat`, `business`, or `blocked`),
+and public authorization entries. `get` reads the scope; it does not grant access. A host must await
+a successful `set`, show its returned selection, and only then send the first message. Never
+optimistically send using an earlier scope. Before the first message, a failed replacement
+selection leaves business access blocked; it cannot restore the previous broader selection.
+After the scope is frozen, a change request returns `SESSION_SCOPE_LOCKED` and leaves the original
+frozen scope unchanged. The host must open a new conversation, not treat that rejection as a
+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 `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.
+The store and its access policy belong to the host. The model sees only the projected reference,
+label, and availability directory; raw connection keys and scope storage are not model APIs.
+
+Reopening an existing conversation must call `restoreSessionScope` before sending. A valid
+`locked: true` snapshot restores its original scope after the saved binding and Agent Sessions
+are checked; it remains locked. A stored `locked: false` snapshot is only a draft, even if its
+stored state says `ready`. Loading it into a new runtime returns `needs_selection` / `blocked`
+without probing its previously selected SDK connections. A never-started draft remains
+`locked: false`: the host must explicitly call `setSessionScope` again and show success before
+sending. It must not silently reactivate the saved draft selection.
+
+If a locked conversation is reopened offline, its business gate stays closed. A timeout,
+connection failure, or incomplete authorization response is not proof of revocation: retry
+`restoreSessionScope`, `getSessionScope`, or `syncSessionArchive` on the **same runtime and Session**
+after connectivity returns. All original members must pass validation before business access or
+archive upload resumes. Concurrent callers wait for the same in-flight whole-scope validation.
+Retries preserve the original keys, Agent Sessions, binding, member set, and persisted scope revision.
+Confirmed revocation, identity/binding replacement, corrupt storage, or a CAS conflict remains
+blocked; retries never select a default, remaining subset, or replacement Session.
+
+An old conversation without a valid snapshot stays blocked; missing or corrupt state must not
+adopt today's registry default or discovered authorizations. Trusted history containing only
+configuration or metadata still permits draft selection. Actual user-message or turn history
+requires the original locked scope; changing that scope requires a new conversation. Embedded
+hosts without the native commands or a scope-selection UI must integrate these APIs;
+`connections use` is not a substitute.
+
+### Scope persistence seam
+
+`createAgentClientPlugin({ scopeStore })` accepts an explicit store with `load(sessionId)` and
+`save(sessionId, record, expectedRevision)`. `load` returns a validated record or `null` for absence;
+errors and corrupt records are not absence. `save` compares the stored revision atomically:
+`null` means the record must not exist, the first revision is `1`, and each update increments it.
+Before validating a replacement selection, the coordinator attempts to save a `needs_selection`
+record. If that first write fails, the previous draft can remain on disk; the write is not
+reported as successful. Restart safety also depends on the draft rule above: every loaded
+unlocked snapshot requires explicit confirmation, so a stale saved selection never becomes
+`ready` automatically, even when its replacement marker could not be written.
+
+The default `createFileSessionScopeStore()` saves non-secret JSON under
+`$DSH_HOME/plugins/dsh-bailinghub/session-scopes`, using `~/.dsh` when `DSH_HOME` is unset. Session
+ids are hashed into filenames. On POSIX, files use mode `0600` and directories `0700`; writes use a
+cross-process lock, compare-and-swap, and atomic replacement. Lock conflicts and storage failures
+fail closed; the adapter never switches to an in-memory fallback. Hosts may inject another
+durable implementation. `createMemorySessionScopeStore()` is an explicit, non-persistent option
+for tests or hosts that deliberately accept losing scope state on restart.
+
+The snapshot contains only the scope schema, DSH session id, revision, state/lock, public binding,
+and selected connection keys, sanitized labels, workspace, and original Agent Session ids. It
+contains no credentials, tokens, prompts, business arguments/results, or invocation state.
+Restoring a scope does **not** restore an invocation, approval, pending completion, or task.
+
+### 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
+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
+are unchanged. It is not written into each member's memory.
+
+The optional SDK seam is `syncConversationArchive(envelope, { members })`. `envelope` contains a
+durable random UUID `clientArchiveId`, the same `clientConversationId` used by `startTurn`, and
+ordered `events`. Each event has a stable UUID `event_id`, contiguous `sequence` starting at one,
+the original `client_turn_id`, and `kind`: `turn_start`, `user_message`, `assistant_message`,
+`run_link`, or `turn_end`. Messages contain `content`; a run link contains the original `run_id`
+and `member_session_id`; turn end contains `completed`, `failed`, or `cancelled` status. A late
+original run response may attach its link to an already ended turn. It never reactivates its
+business tools, dispatches that cancelled turn's remaining members, or replaces a newer active turn.
+The SDK receives host-only member records `{ connectionKey, workspace, expectedSessionId, label }`,
+checks every original authorization, and owns HTTP batching and credential use. The first frozen
+member is the writer. Neither the old hash alias nor a random archive UUID confers read/write access.
+
+`createAgentClientPlugin({ archiveStore })` accepts an independent CAS store with `load`/`save`,
+using the same revision semantics as the scope store but a distinct schema and directory.
+`createFileConversationArchiveStore({ directory? })` defaults to
+`$DSH_HOME/plugins/dsh-bailinghub/conversation-outbox`, with private file permissions, atomic writes,
+and a 32 MiB local record bound. `createMemoryConversationArchiveStore()` is explicitly volatile.
+Outboxes retain the frozen membership, random identity, visible events, event hashes/ids, and
+acknowledged cursor. They contain task text; they are not credential stores. The SDK rejects a
+message above 64,000 characters; the adapter does not silently truncate it or discard pending text.
+Core's conversation/event quotas and the local bound can leave synchronization pending.
+
+Host APIs `getSessionArchiveStatus(sessionId)` and `syncSessionArchive(sessionId)` and the user-only
+`/bailinghub archive status|sync` commands expose synchronization separately from business state.
+Persisted pending events can be retried after reopening under the original valid frozen scope,
+without replaying `startTurn`, `invoke`, `resume`, or `completeRun`. An older SDK reports
+`unsupported` without accessing the outbox directory; an unavailable/older Core leaves saved events
+pending or unsupported for retry. Empty scope does not load a transport or create an archive.
+
+Capture begins with business turns enabled under this archive contract. Previously unarchived history is not silently
+claimed as complete. Status compares saved visible events against the available DSH `session.events`:
+missing user/assistant text or turn boundaries report `recovery_gap` / `coverage: incomplete`, even
+if the saved prefix is synchronized. Hosts without durable history report `coverage: unverified`.
+This check does not reconstruct missing business run ids. Network failure leaves durable events
+retryable; a local write failure can leave only an in-memory pending event until storage recovers.
+While scope validation or transport availability prevents upload, a known `storage_error` or
+`recovery_gap` remains visible with the existing unsaved-event count and coverage. An optional
+`availability` field describes the additional upload restriction; it does not clear the local error.
+Capability-discovery network failures report `pending`, not a fabricated local storage failure.
+If the process ends before that write succeeds, the host-history check reports the detectable gap;
+there is no atomic transaction between DSH's event log, this outbox, and Core. It does not promise
+recovery of absent host history, hidden content, or durable business task execution.
 
 ## Host Configuration
 
@@ -16,7 +411,8 @@ connectionName
 ```
 
 `hubUrl`, `clientAppId`, and `workspace` identify a public Hub-side application/workspace binding.
-`connectionName` selects one local SDK connection instance, but it is not an account, tenant, or
+`connectionName` selects a local SDK connection for connection-management commands; it does not
+select the conversation scope. It is not an account, tenant, or
 identity claim. The Hub Client App resolves to one stable business authorization endpoint; no
 business endpoint, authorization endpoint, token, secret, or business credential belongs in this
 config. The business authorization page owns sign-in, account switching, tenant selection, and
@@ -34,7 +430,7 @@ connectionsUse(connectionNameOrKey)
 connectionsRemove(connectionNameOrKey)
 
 login({ hubUrl, clientAppId, workspace, route, connectionName })
-status({ connectionName })
+status({ connectionKey }) // conversation checks; management may use connectionName
 logout({ connectionName })
 workspaces({ connectionName })
 use({ workspace, route, connectionName })
@@ -50,7 +446,7 @@ startTurn({
 
 searchCapabilities({ query, limit?, runId? })
 invoke({ invocationId, capabilityRevision, agentRunId, tool, arguments })
-resume(invocationId, {}, { workspace, connectionName, signal? })
+resume(invocationId, {}, { workspace, connectionKey, signal? })
 completeRun(runId, {
   assistantMessageId,
   content,
@@ -61,9 +457,11 @@ completeRun(runId, {
 })
 ```
 
-The adapter may pass a second host metadata argument (`workspace`, `connectionName`, and an
-`AbortSignal`) to turn/tool methods. The framework-neutral SDK DTO is always the first argument;
-an SDK implementation that does not consume host metadata may ignore it.
+The adapter passes host metadata (`workspace`, fixed `connectionKey`, and optional `signal`)
+separately from the business DTO to turn/tool methods, and as the third argument to completion
+and resume. The transport must honor that exact selection; it must never ignore it or substitute
+a mutable alias/default. Connection-management commands may use `connectionName`. The optional
+archive seam and its complete frozen member selection are specified above.
 
 ## Browser Identity and Local Reconciliation
 
@@ -142,7 +540,15 @@ agent/inbox/claimed
   -> model request
 ```
 
-The adapter captures only a claimed message whose `source.kind` is `user`. On the authoritative
+The adapter captures only a claimed message whose `source.kind` is `user`. The
+first `user/message` event freezes scope; the inbox claim is a fallback if that event is absent.
+The assembly gate permits business work only for the saved selection.
+When inspecting attached or restored history, only `user/message` with `source.kind: 'user'` or
+`turn/start` proves that a conversation has started. Configuration events, metadata, and
+`session/end-seed` alone do not freeze a draft. `firstLiveSeq` is a seed-history boundary, never
+proof of a started conversation by itself. The adapter separates the previously observed or
+seeded prefix from new events so the current first message is not mistaken for an older turn.
+On the authoritative
 `system-prompt/assemble` waterfall, it calls `startTurn`, registers the returned definitions
 through `agent.ctx.tools.register()`, and also adds their schemas to the already-sampled current
 assembly. Later steps receive the same agent-scoped definitions from the ordinary ToolRuntime
@@ -163,10 +569,11 @@ The adapter listens to durable `session/event` values:
 
 ## Tool Invocation and Recovery
 
-Every active Core tool becomes an agent-scoped DSH definition. Its invocation id is a stable
-64-character lowercase SHA-256 digest of the session, run, DSH call id, and Core tool name. It
-calls the SDK `invoke` DTO without letting the model choose the run, capability revision, route,
-or identity.
+Every active Core tool becomes an agent-scoped DSH definition. Its
+invocation id is a stable 64-character lowercase SHA-256 digest of the session, run, DSH call id,
+and Core tool name. It
+calls the SDK `invoke` DTO without letting the model supply the run, capability revision, route,
+or arbitrary identity. The constrained authorization selector is described above.
 
 An SDK error with `disposition === 'accepted_unknown'` starts recovery with the exact invocation
 id; it never repeats the business-tool `invoke`. Likewise, `awaiting_approval`, `in_progress`, and
@@ -197,41 +604,44 @@ Connection selector, workspace, conversation alias, Core run, active definitions
 state are isolated per DSH Agent/session. Named connections for different trusted identities own
 separate SDK credentials and Agent Sessions. Same-binding connections that resolve to the same
 trusted identity are reconciled to one local survivor after authorization. A workspace switch
-preserves the selected connection instance and affects future sessions; it is rejected while any
+preserves the selected connection instance and changes connection-management defaults; it is rejected while any
 Core run is active/completing or has an unsynchronized completion payload.
 
 After a same-alias login resolves to a different trusted identity, the SDK-returned replacement
-alias becomes the adapter default for new sessions. The retained old alias and the new alias both
+alias becomes the adapter's registry default. The retained old alias and the new alias both
 remain visible through `connections list` and user-selectable through `connections use`; existing
 DSH sessions remain pinned as described below.
 
 Multi-connection add/use/remove is exposed only through the `/bailinghub connections` user
-command. It is never registered as a model tool. Selecting a connection changes defaults for new
-Agent sessions only; existing states keep their captured connection and workspace. Removing a
-connection is rejected while any run is active or has an unsynchronized completion. The SDK then
+command. It is never registered as a model tool. Selecting a connection changes registry defaults;
+existing states keep their captured bindings. Defaults affect connection management only;
+the host-owned scope API alone selects the conversation's authorization directory.
+Removing a connection is rejected while any run is active or has an unsynchronized completion. The SDK then
 revokes only that instance's remote Agent Session before removing its local credentials and
 registry metadata; a revoke failure preserves both. Repeating add with the same name and public
 binding selects the existing instance; reusing a name for different public metadata fails.
 `connectionName` remains a local user selector and never becomes a trusted identity claim.
 
 After a successful remove, the adapter reads the registry again. A valid remaining
-`currentConnectionKey` replaces all four public defaults for future sessions, using the key itself
+`currentConnectionKey` replaces all four public connection-management defaults, using the key itself
 when the profile has no alias; no remaining connection sets the adapter to unconfigured. A refresh
 failure does not change the successful remove result. It makes a removed default unavailable, but
 does not invalidate an unchanged non-current default. Existing session state is never rewritten.
 
-The four static adapter fields bootstrap SDK construction only. Before the first new Agent session
-or user command after process start, the adapter reads `connectionsList()` and adopts the public
+The four static adapter fields bootstrap SDK construction only. For connection management, the
+adapter reads `connectionsList()` and adopts the public
 metadata matching `currentConnectionKey`. Invalid, missing, or unavailable registry data leaves the
 bootstrap defaults in place and must not remove or block unrelated host tools. The lookup is not a
 model tool, and restoring or later selecting a default never mutates an already-created session.
+These registry bootstrap rules do not grant business scope, even to a new
+conversation. A failed scope load or selection never uses the bootstrap fields as a fallback.
 
 The completion request is restricted to:
 
 ```json
 {
   "assistant_message_id": "stable alias",
-  "content": "visible final text",
+  "content": "visible final text for one authorization, or that run's deterministic call summary for a multi-authorization scope",
   "status": "completed | failed | cancelled",
   "model": "optional",
   "runtime": "optional",