dsh-bailinghub 0.3.0 → 0.4.0

package/SECURITY.md

@@ -19,9 +19,9 @@ configuration and are never model tool arguments.
 
 Non-loopback HTTP is denied by default. Do not enable insecure HTTP on an untrusted network.
 
-## Native 0.3.0 boundary
+## Native 0.4.0 boundary
 
-The native 0.3.0 plugin accepts only `hubUrl`, `clientAppId`, `workspace`, and
+The native 0.4.0 plugin accepts only `hubUrl`, `clientAppId`, `workspace`, and
 `connectionName`. The generic SDK owns browser authorization, refresh, and secure credential
 storage; business endpoints and final authorization remain Core/business-system concerns. The
 Hub Client App owns one business authorization entry. That business page, not the plugin or model,
@@ -41,7 +41,7 @@ falsely report a complete logout.
 Tools are Agent/run scoped. Message ids are replaced by Core-safe hash aliases, invocation ids are
 stable 64-character digests, and an `accepted_unknown` outcome must resume that exact invocation
 instead of creating a replacement. Completion retries are bounded and reuse one frozen,
-visible-only payload. Version 0.3.0 installs `bailinghub-mcp-server@0.3.0` as an exact ordinary
+visible-only payload. Version 0.4.0 installs `bailinghub-mcp-server@0.4.0` as an exact ordinary
 dependency and resolves its `./sdk` export. It does not depend on ambient modules, an optional
 peer, a range, a dist-tag, or a local path. Public `0.1.1` does not provide that facade.
 
@@ -49,3 +49,95 @@ Agent Session credentials use macOS Keychain or Windows CurrentUser DPAPI-protec
 LocalAppData. Windows PowerShell or DPAPI unavailability fails closed without a plaintext fallback.
 Linux and other POSIX hosts must explicitly enable the SDK's isolated mode-0600 file store. The
 plugin never receives the credential value and never writes one into Cordis configuration.
+
+## Same-system authorization selection
+
+Version 0.4.0 lets the model select a session-local `authorization_ref` from the current
+conversation's directory. This is a constrained per-call selector, not a connection-management
+tool or authority to supply a Hub, route, raw connection key, credential, or business identity.
+The host must first explicitly select fixed connection keys for this conversation through
+`setSessionScope` or the user-only `/bailinghub scope set <connection-key>...` command. Aliases are
+not scope keys. Unset scope and `[]` (`/bailinghub scope none`) remain ordinary chat, without
+BailingHub tools or runs. Authorization and registry defaults cannot grant conversation scope.
+The selected bindings must share one Hub/client/workspace; unselected bindings are excluded.
+The adapter never implements selection by changing the SDK's global current connection.
+
+Hosts must await successful scope persistence and confirmation before sending the first user
+message. The first `user/message` event freezes scope, with the inbox claim as a fallback, before
+`startTurn`; an in-flight or
+failed selection cannot admit business work. Subsequent changes require a new conversation.
+The full selected group is checked before business input is sent. Any missing, revoked, replaced,
+or unreadable selected authorization pauses the whole conversation's business access. The adapter
+must not silently adopt a default or shrink the scope to the remaining valid authorizations.
+
+Local connection names are untrusted display data. They do not prove tenant identity, widen an
+authorization, or replace the business system's final permission checks. The directory is a
+binding snapshot, not a credential snapshot: expired, removed, or revoked access must fail
+without silently selecting another authorization. New authorizations and alias changes require
+a new conversation.
+The host checks the fixed connection key, workspace, and original Agent Session id before
+transport operations. An Agent Session replacement also requires a new conversation, even if
+the local alias or connection key remains unchanged.
+
+Matching declarations share one typed tool. Conflicting same-name descriptions, schemas, or
+governance are not merged for execution, and a shared declaration cannot confer another identity's permissions.
+Each invocation binds its chosen authorization, Core run, and capability revision. Recovery
+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.
+
+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,
+revision compare-and-swap, a cross-process lock, and atomic replacement. Lock timeout reports a
+conflict without deleting another process's lock. Corrupt data and I/O failure fail closed; they
+are never interpreted as an absent selection or a reason to use memory storage. Before validating
+a replacement scope, the coordinator attempts to persist `needs_selection`. Failure of that first
+write can leave the previous draft on disk. Every unlocked snapshot loaded into a new runtime is
+therefore blocked pending explicit selection, without checking its previous SDK authorizations;
+restart safety does not assume that the failed write replaced the old record.
+
+The host may inject a store with the same CAS semantics; the provided memory adapter is explicitly
+non-persistent. `restoreSessionScope` restores only a valid locked selection after verifying its
+keys, binding, and original Agent Session ids. Unlocked drafts require explicit selection again;
+started conversations without valid locked scope stay blocked. History containing only metadata,
+configuration, or seed markers does not prove that a conversation started. The lifecycle check
+requires an actual user-sourced `user/message` or `turn/start` and uses seed/observation boundaries
+to distinguish prior history from a new first message. It restores scope only, not invocations,
+approvals, pending completions, or task execution. A new conversation is required to change an
+already-started scope. No token, credential, prompt, or business payload belongs in the
+scope snapshot.
+The trusted host owns stable, unique conversation ids and the store namespace. Scope APIs and
+records must not be exposed as model-controlled storage or allow an untrusted caller to select
+another conversation's id. This plugin does not secure unrelated host filesystem tools; the host
+must enforce that access boundary.
+
+The adapter keeps authorization-specific instructions and context labeled, and each run receives
+only its authorization's deterministic call summary. It does not broadcast a combined final
+answer to every run. Visible user input and context do share the local conversation boundary;
+see [Privacy](PRIVACY.md#same-system-authorization-selection).
+
+The independent conversation-audit extension sends visible text for the complete frozen member
+set through an optional SDK API. A durable random archive UUID supplies correlation, not authority:
+the SDK/Core must validate every original member before confirming or appending, and Core owns the
+aggregate read permission. Never expose mixed free text to a reader authorized for only one member
+by assuming it can be safely redacted. The original run id and member Session bind run links;
+archive synchronization cannot create or resume a business action. Late links remain attached to
+their original turn.
+
+The separate private outbox contains plaintext visible task text and must be protected from
+untrusted host/model filesystem tools. It has bounded reads, no-follow regular-file checks,
+CAS/lock/atomic-write semantics, and no credential or scope-store fallback. Payloads and ids remain
+stable on ambiguous network retries. Local I/O failure can leave an unpersisted event: available
+DSH history is compared after reopening, and missing events produce `recovery_gap`, not a claim
+of a complete transcript. Hosts without history must show unverified coverage. This boundary is
+not a distributed transaction or durable business-task recovery mechanism.
+
+Transient transport failures do not prove that an original authorization was revoked. Scope
+get/restore and archive retry may revalidate all original members on the same runtime, while
+keeping business access and uploads closed until validation succeeds. Concurrent callers share
+that validation. Confirmed revocation/replacement and storage/CAS conflicts remain terminally
+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.

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -1,8 +1,238 @@
 # 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`.
+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
+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.
+
+Version 0.4.0 changes 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 returned `authorizations` entry has exactly the public host-facing fields
+`{ authorizationRef, connectionKey, label, workspace }`. 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 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.
+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 +246,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 +265,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 +281,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 +292,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 +375,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 +404,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 +439,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",

package/docs/COMPATIBILITY.md

@@ -1,6 +1,51 @@
 # Compatibility
 
-## Native Agent Client 0.3.0
+## Native Agent Client 0.4.0
+
+| Component | Release pairing / requirement |
+| --- | --- |
+| DeepSeek Harness | `0.1.1-rc.2`; real Session, Cordis lifecycle, commands, prompt assembly, and ToolRuntime regression coverage |
+| 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.4.0` via `./sdk` |
+| BailingHub Core | Recommended `bailinghub@0.6.1`; Agent Auth v1, Agent Client Runtime v1, and conversation audit v1 |
+| Visible archive acknowledgement | `bailing.agent-conversation-audit-ack.v1` |
+| Selected authorization group | One Hub + Client App + workspace; no cross-system or cross-route scope |
+
+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
+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
+0.3 includes 0.4 features.
+
+New conversations need explicit scope selection before the first message. Custom hosts must await
+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.
+
+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.
+Archived event ids and payloads remain stable on retry; known local write errors and detectable
+history gaps cannot be hidden by a connectivity failure.
+
+The archive transport seam is optional for injected older SDKs. They report `unsupported` while
+existing business methods remain usable. An older Core may leave durable events pending or
+unsupported; that degradation does not establish full compatibility with this release. Empty scope
+starts no business run or archive operation. No model can select a new credential or bypass the
+full selected group.
+
+Local scope and outbox files use private POSIX permissions and atomic/CAS persistence. The outbox
+contains plaintext visible task text, persists after acknowledgement, and has no automatic
+retention cleanup. See [Privacy](../PRIVACY.md) and the [host contract](AGENT_CLIENT_CONTRACT.md).
+
+The CI matrix checks Ubuntu and Windows with Node.js 22.19.0 and 24. Live business/browser
+acceptance still belongs to each deployment; the matrix is not a universal deployment claim.
+
+## Historical native Agent Client 0.3.0
 
 | Component | Verified version |
 | --- | --- |
@@ -80,7 +125,7 @@ Public `dsh-bailinghub@0.1.1` remains a configuration-only bundle. It starts the
 operator-configured Hub URL, route-scoped Client Token, and route. It does not establish an Agent
 Session, receive a dynamic capability catalog, or move orchestration into local DSH.
 
-The 0.3 line must not mutate the published 0.1 package or reinterpret its configuration. A new
+The native line must not mutate the published 0.1 package or reinterpret its configuration. A new
 BailingHub Core release is compatible only after a separate clean legacy profile proves that the
 0.1.1 `/run` and `/jobs/{job_id}` flow still works.
 
@@ -88,9 +133,11 @@ BailingHub Core release is compatible only after a separate clean legacy profile
 
 Compatibility requires independent evidence for both paths:
 
-1. Native 0.3: clean install of only the exact plugin package, browser authorization, workspace
+1. Native 0.4: 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.
+   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.
 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.