dsh-bailinghub 0.1.1 → 0.3.0

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -0,0 +1,260 @@
+# 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`.
+
+## Host Configuration
+
+The Cordis Config schema contains only:
+
+```text
+hubUrl
+clientAppId
+workspace
+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
+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
+the trusted identity ultimately represented by `on_behalf_of`.
+
+## Injectable Transport Seam
+
+The default transport is lazily created from `bailinghub-mcp-server/sdk`. Tests and future host
+adapters may inject an object with all methods below:
+
+```js
+connectionsList({})
+connectionsAdd({ connectionName, hubUrl, clientAppId, workspace })
+connectionsUse(connectionNameOrKey)
+connectionsRemove(connectionNameOrKey)
+
+login({ hubUrl, clientAppId, workspace, route, connectionName })
+status({ connectionName })
+logout({ connectionName })
+workspaces({ connectionName })
+use({ workspace, route, connectionName })
+
+startTurn({
+  clientConversationId,
+  clientTurnId,
+  userMessageId,
+  userInput,
+  pageContext?,
+  renderers?,
+})
+
+searchCapabilities({ query, limit?, runId? })
+invoke({ invocationId, capabilityRevision, agentRunId, tool, arguments })
+resume(invocationId, {}, { workspace, connectionName, signal? })
+completeRun(runId, {
+  assistantMessageId,
+  content,
+  status,
+  model?,
+  runtime?,
+  usage?,
+})
+```
+
+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.
+
+## Browser Identity and Local Reconciliation
+
+`/bailinghub login` always starts from the selected Hub/client/workspace binding. The plugin does
+not accept or derive a business URL, account id, tenant id, or identity selector. Core redirects
+to the single authorization endpoint configured for that Client App, and the business page
+performs any login, account switching, or tenant selection required before it approves the
+authorization.
+
+The SDK may stage more than one named local instance for the same public binding while browser
+authorization is in progress. After authorization it compares the trusted Session
+`on_behalf_of`, never the local `connectionName`:
+
+- the same identity replaces the older local connection and revokes its old Agent Session;
+- a different identity remains a separate named connection; when login was launched from an alias
+  already owned by the old identity, the SDK preserves that alias and Session, allocates an
+  available alias such as `default-2` to the new identity, and makes the new connection current;
+- an uncertain identity inspection or failed old-Session revoke keeps the new Session authorized
+  and returns `cleanupRequired: true` with cleanup metadata.
+
+The adapter reports that last result as successful authorization plus a visible warning. It tells
+the user not to authorize again and to retry explicit cleanup with the user-only connection
+lifecycle commands. It does not turn the result into a failed login or let the model perform
+cleanup.
+
+## Core HTTP Mapping
+
+The SDK, not this adapter, maps those DTOs to:
+
+```text
+POST /agent-api/v1/workspaces/:route/turns
+POST /agent-api/v1/workspaces/:route/capabilities/search
+POST /agent-api/v1/tool-invocations
+POST /agent-api/v1/tool-invocations/:invocation_id/resume
+POST /agent-api/v1/runs/:run_id/complete
+```
+
+`startTurn` accepts the Core `schema` or `schema_version` alias, but the resolved value must be
+exactly `bailing.agent-turn-context.v1`. Its runtime result is:
+
+```json
+{
+  "schema_version": "bailing.agent-turn-context.v1",
+  "run_id": "UUID",
+  "profile_revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "capability_revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "context": {
+    "instructions": "...",
+    "page_context": {},
+    "renderers": [],
+    "memory": null,
+    "memory_refs": [],
+    "knowledge": [],
+    "knowledge_refs": [],
+    "governance": {}
+  },
+  "active_tools": []
+}
+```
+
+At most 12 active tools are accepted. 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
+uppercase digests fail closed.
+
+## Verified DSH Lifecycles
+
+DSH `0.1.0-rc.7` and `0.1.1-rc.2` claim inbox messages before assembling the current step:
+
+```text
+agent/inbox/claimed
+  -> systemPrompt.assemble()
+  -> system-prompt/assemble async waterfall
+  -> agent/pre-step
+  -> model request
+```
+
+The adapter captures only a claimed message whose `source.kind` is `user`. 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
+registry.
+
+Stable profile/instructions/governance are system-prompt sections. Memory, reference-only
+knowledge body/refs, page context, and renderers are named runtime-context entries. Knowledge
+content is evidence, never an instruction source.
+
+The adapter listens to durable `session/event` values:
+
+- `assistant/message`: keep only `content` blocks whose type is `text`, plus model and the
+  public numeric usage buckets;
+- `tool/call`: count distinct durable call ids for the public `tool_calls` metric; never copy
+  tool arguments or results into completion usage;
+- `turn/end`: freeze the completion DTO and synchronize it;
+- `assistant/chunk`: deliberately ignored, including hidden reasoning chunks.
+
+## 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.
+
+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
+retryable `rejected_before_dispatch` results keep the original DSH tool call open while the
+adapter performs bounded `resume` polling. Approval therefore continues the same invocation and
+the same Core run before the local Agent writes its final answer.
+
+The default recovery window is at most 120 seconds and 60 resume attempts. `executed`,
+`business_rejected`, `denied`, non-retryable `rejected_before_dispatch`, and
+`reconciliation_required` are terminal and are never polled. If the bounded wait expires while a
+known result is still pending, the tool returns that result plus an `agent_client_wait` marker
+containing the same invocation id and the only legal recovery tool. If no trustworthy invocation
+result was ever received, the safe error still retains only that exact id. Raw transport errors
+are never exposed.
+
+Concurrent or replayed executions of the same DSH call share one in-flight operation. A terminal
+result is returned from the per-run cache, while an unfinished replay resumes the same invocation;
+neither path submits another `invoke`. A replay that changes the original tool or arguments fails
+closed.
+
+`search_business_capabilities` applies the returned revision/tool set only to the current
+session/run. `resume_governed_tool_invocation` accepts only the exact 64-character id, shares the
+same bounded recovery state when known locally, and never creates a replacement invocation.
+
+## Session and Completion State
+
+Connection selector, workspace, conversation alias, Core run, active definitions, and completion
+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
+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
+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
+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
+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
+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.
+
+The completion request is restricted to:
+
+```json
+{
+  "assistant_message_id": "stable alias",
+  "content": "visible final text",
+  "status": "completed | failed | cancelled",
+  "model": "optional",
+  "runtime": "optional",
+  "usage": {}
+}
+```
+
+The adapter supplies the camelCase SDK equivalent. It never passes an event, message object,
+reasoning block, DSH end-reason object, or arbitrary host metadata. The payload is frozen before
+the first attempt and reused unchanged for up to three automatic attempts. A failed completion
+remains pending in its original run; `/bailinghub sync` starts another bounded attempt batch with
+that same id and payload.
+
+The verified DSH releases report disjoint camelCase buckets (`inputTokens`, `cacheReadTokens`,
+optional `cacheWriteTokens`, and `outputTokens`) on each durable `assistant/message`. The adapter sums them
+across model steps, exposes total input as Core `input_tokens`, cache reads as the
+`cached_input_tokens` subset, and derives `total_tokens` without adding `reasoningTokens` a second
+time. Unknown, non-finite, and negative metrics are discarded; only the Core public usage
+allowlist can leave the host.
+
+## Graceful Degradation
+
+Missing/invalid configuration, missing SDK, failed authorization, failed Core context, a tool-name
+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.

package/docs/COMPATIBILITY.md

@@ -1,15 +1,97 @@
 # Compatibility
 
+## Native Agent Client 0.3.0
+
 | Component | Verified version |
 | --- | --- |
+| DeepSeek Harness / Cordis lifecycle | `0.1.0-rc.7`; `0.1.1-rc.2` |
+| Node.js | `22.19.0+` or `24+` |
+| DSH tool presentation | Native Tool Mode |
+| Generic Agent Client SDK | `bailinghub-mcp-server@0.3.0` via `./sdk` |
+| BailingHub Core | `bailinghub@0.5.1`; Agent Auth v1 + Agent Client Runtime v1 |
+| BailingHub turn context | `bailing.agent-turn-context.v1` |
+| BailingHub capability search | `bailing.agent-capability-search.v1` |
+| BailingHub governed invocation | `bailing.agent-tool-invocation.v1` |
+| BailingHub run completion | `bailing.agent-run-completion.v1` |
+
+Version 0.3.0 declares `bailinghub-mcp-server@0.3.0` as an exact ordinary dependency. A clean DSH
+profile must work after installing only the plugin; ambient `node_modules`, peer/optional
+dependencies, dist-tags, ranges, and local `file:` paths are outside the supported contract.
+Compatibility with Core 0.5.1 includes the live Agent Auth/Runtime
+contracts from that release.
+
+DeepSeek Harness remains a developer preview. Every Harness version change requires a new smoke
+against its real Cordis lifecycle, prompt waterfall, ToolRuntime, commands, durable session events,
+and Web profile installation before this table can change.
+
+`/bailinghub doctor` validates the required host API shape at runtime and reports the releases for
+which that shape has been exercised. This is a diagnostic check, not a substitute for the live
+browser authorization, read/write, approval/recovery, trajectory, and revocation gates below.
+
+### Tool-mode and operating-system boundaries
+
+- Native Tool Mode is required. DSH Code Mode is deliberately degraded because it cannot safely
+  present the current-turn dynamic business schemas in 0.3.0.
+- macOS Agent Session credentials use Keychain.
+- Linux and other POSIX systems require the SDK's explicit secure file-store opt-in; the file must
+  remain owned by the current user with mode `0600`.
+- Windows Agent Session credentials use CurrentUser DPAPI. Native package installation, SDK
+  resolution, and host lifecycle are Windows CI gates; each deployment must still accept its own
+  live browser and business authorization flow.
+- Non-loopback Hub connections require HTTPS. Loopback HTTP is for local development only.
+
+### Host configuration contract
+
+The plugin accepts only these four public routing fields:
+
+```text
+hubUrl
+clientAppId
+workspace
+connectionName
+```
+
+In Agent Client v1, `workspace` is the BailingHub route id. Business endpoints, authorization page
+URLs, Client Tokens, Tool Provider signing secrets, business credentials, and model-provider keys
+are not DSH plugin configuration.
+
+The public binding is the normalized Hub URL, client app id, and workspace tuple.
+`connectionName` is a user-controlled local selector, not an identity claim. The Hub Client App
+supplies one stable business authorization entry, and the business page
+handles login, account switching, and tenant selection. After authorization, the SDK compares the
+trusted `on_behalf_of` within the same public binding: the same identity replaces the older local
+connection, while different identities remain independent. When a same-alias login returns a
+different identity, the old alias and Session remain intact and the new identity receives a
+non-conflicting alias that becomes current. A cleanup-required result keeps the new connection
+authorized and must be resolved explicitly without another authorization attempt.
+
+## Public legacy 0.1.x
+
+| Component | Published version |
+| --- | --- |
 | DeepSeek Harness | `0.1.0-rc.7` |
 | DSH MCP Client | in-box version shipped by `0.1.0-rc.7` |
-| BailingHub MCP Server | `0.1.1` |
+| BailingHub MCP Server | exactly `0.1.1` |
 | BailingHub Client API | `bailing.client-api.v1` |
 | Node.js | `22.19.0+` |
 
-DeepSeek Harness is currently a developer preview. Compatibility with another Harness release
-must be rechecked before changing this table or the package's supported range.
+Public `dsh-bailinghub@0.1.1` remains a configuration-only bundle. It starts the exact
+`bailinghub-mcp-server@0.1.1` stdio command, exposes three fixed governed-job tools, and uses one
+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
+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.
+
+## Release compatibility rule
+
+Compatibility requires independent evidence for both paths:
+
+1. Native 0.3: 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.
+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.
 
-The bundle uses DSH's in-box `@deepseek-ai/dsh-mcp-client`; it intentionally does not install a
-second copy into the profile. The stdio child is pinned to `bailinghub-mcp-server@0.1.1`.
+Passing one path does not establish compatibility for the other.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,92 @@
+# Get started in three minutes
+
+This guide is for someone whose organization has already connected a business system to
+BailingHub. If that integration does not exist yet, the BailingHub administrator and business
+developer must prepare it before an end user installs this plugin.
+
+## What to ask your administrator for
+
+Ask for these four public connection values:
+
+```text
+Hub URL
+Client App ID
+Workspace
+Connection Name
+```
+
+They identify the BailingHub application and starting workspace. They are not credentials. Do not
+ask the administrator to send you a Client Token, Tool Provider secret, business password, model
+API key, authorization code, browser session cookie, business URL, or tenant-specific login URL.
+
+## 1. Install the plugin
+
+Install the exact public version into the DSH Web profile:
+
+```bash
+dsh plugin --profile web add dsh-bailinghub@0.3.0
+```
+
+The plugin installs the matching BailingHub SDK automatically.
+
+## 2. Enter the four connection values
+
+Use the DSH plugin settings page or these environment names:
+
+```bash
+export BAILINGHUB_HUB_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
+export BAILINGHUB_WORKSPACE='employee_assistant'
+export BAILINGHUB_CONNECTION_NAME='default'
+```
+
+The values above are placeholders. Use the public values from your own BailingHub administrator.
+Never paste credentials into the Cordis patch or a chat message.
+
+## 3. Authorize in the browser
+
+Start DSH and run:
+
+```text
+/bailinghub login
+/bailinghub status
+/bailinghub workspaces
+```
+
+`login` opens the one business-side authorization entry configured for the Client App. Sign in or
+switch account there, select a tenant there when the business system asks, and check the resulting
+business identity and requested workspace before approving. Authorization uses the business
+system's own login; it does not send the business password or business URL to the plugin.
+
+`Connection Name` is only a local selector. If the same trusted business identity authorizes the
+same Hub/client/workspace binding again, the SDK replaces the older local connection. A different
+trusted identity remains separate. When the selected name already belongs to the old identity,
+the SDK preserves it and assigns the new identity an available alias such as `default-2`; the new
+alias becomes current. Run `/bailinghub connections list` to see both and
+`/bailinghub connections use <name-or-key>` to switch. If login says cleanup is required, the new
+connection is already authorized, but an existing connection may still need inspection or
+removal: do not authorize again; list connections and remove the reported old entry.
+
+## 4. Try one safe business request
+
+Start a new conversation and ask for one read-only action that the connected system exposes, for
+example:
+
+```text
+Find the demonstration employee EMP-001 and summarize the visible fields.
+```
+
+Then try one reversible permitted update in a dedicated development workspace. The exact requests
+depend on the capabilities your business system has exposed. An operation that requires approval
+must continue through the existing approval flow; an operation outside the current identity's
+permissions must remain unavailable.
+
+## 5. Confirm the result in BailingHub
+
+The BailingHub console should show the same visible conversation, Agent Run, governed tool calls,
+approval state, and final result. Do not treat a successful installation alone as proof that a
+business action ran.
+
+If setup fails, include the DSH version, plugin version, operating system, the command that failed,
+and redacted error text in a GitHub Issue. Never attach tokens, private URLs, personal information,
+authorization codes, or production payloads.

package/docs/GETTING_STARTED.zh-CN.md

@@ -0,0 +1,83 @@
+# 三分钟开始使用
+
+这份指南面向业务系统已经接入 BailingHub 的最终用户。如果还没有完成业务接入，需要先由
+BailingHub 管理员和业务开发者准备中枢应用、授权页面与业务能力，再安装本插件。
+
+## 先向管理员获取什么
+
+只需要向管理员获取四项公开连接信息：
+
+```text
+Hub URL
+Client App ID
+Workspace
+Connection Name
+```
+
+它们用于定位 BailingHub 应用和初始业务空间，不是凭据。不要让管理员把 Client Token、Tool
+Provider 密钥、业务密码、模型 API Key、授权码、浏览器 Cookie、业务地址或租户专属登录地址
+发给你。
+
+## 第一步：安装插件
+
+把精确公开版本安装到 DSH Web Profile：
+
+```bash
+dsh plugin --profile web add dsh-bailinghub@0.3.0
+```
+
+插件会自动安装匹配版本的 BailingHub SDK，不需要再手工拼装依赖。
+
+## 第二步：填写四项连接信息
+
+可以在 DSH 插件设置页面填写，也可以使用对应环境变量：
+
+```bash
+export BAILINGHUB_HUB_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
+export BAILINGHUB_WORKSPACE='employee_assistant'
+export BAILINGHUB_CONNECTION_NAME='default'
+```
+
+上面都是占位值，请替换成自己中枢管理员提供的公开信息。不要把凭据写进 Cordis Patch，也不要
+把凭据粘贴到聊天消息里。
+
+## 第三步：在浏览器完成授权
+
+启动 DSH 后依次执行：
+
+```text
+/bailinghub login
+/bailinghub status
+/bailinghub workspaces
+```
+
+`login` 会打开 Client App 配置的唯一业务授权入口。在该页面登录或切换账号，并在业务系统要求
+时选择租户；点击同意前，确认页面显示的最终业务身份和准备使用的 workspace。整个过程沿用业务
+系统自己的登录流程，不会把业务密码或业务地址交给插件。
+
+`Connection Name` 只是本机选择器。同一可信业务身份再次授权同一 Hub/client/workspace 绑定时，
+SDK 会覆盖旧的本机连接；不同可信身份继续相互独立。如果当前名称已经属于旧身份，SDK 会保留
+它，并给新身份分配一个可用名称（例如 `default-2`），同时把新名称设为当前连接。使用
+`/bailinghub connections list` 可以查看两者，再用
+`/bailinghub connections use <名称或连接键>` 显式切换。如果登录提示需要清理，新连接其实已经
+授权成功，但某个旧连接可能仍需检查或删除：不要再次授权，应先列出连接，再删除提示的旧连接。
+
+## 第四步：尝试一条安全的业务请求
+
+新建一个会话，先尝试业务系统已经开放的一条只读请求，例如：
+
+```text
+查询演示员工 EMP-001，并汇总我能看到的资料。
+```
+
+随后可以在专用开发空间尝试一次可回滚、当前账号允许的修改。实际能问什么，取决于业务系统
+开放了哪些能力。需要审批的操作必须继续走原有审批，没有权限的操作仍然不可用。
+
+## 第五步：在 BailingHub 查看结果
+
+BailingHub 控制台应当能看到同一条可见会话、Agent Run、业务工具调用、审批状态与最终结果。
+只有插件安装成功，还不能证明业务操作已经真正完成。
+
+如果初始化失败，请在 GitHub Issue 中提供 DSH 版本、插件版本、操作系统、失败命令和脱敏错误。
+不要附带 Token、私有地址、个人信息、授权码或生产业务载荷。

package/docs/MIGRATION_VNEXT.md

@@ -0,0 +1,128 @@
+# Migration Boundary: Public 0.1.x to the Native Agent Client
+
+There is no automatic credential, configuration, tool, or orchestration migration from public
+`dsh-bailinghub@0.1.x` to the native 0.3 Agent Client.
+
+## What remains unchanged
+
+Public `dsh-bailinghub@0.1.1` is immutable. It remains a configuration-only DSH Bundle that starts
+`bailinghub-mcp-server@0.1.1` through the in-box MCP client and exposes exactly:
+
+```text
+mcp__bailinghub__submit_governed_job
+mcp__bailinghub__get_governed_job
+mcp__bailinghub__wait_for_governed_job
+```
+
+The operator supplies one Hub URL, route-scoped Client Token, and fixed route. BailingHub performs
+the orchestration. Local DSH does not obtain a trusted Agent Session or dynamic capability catalog.
+
+The retained [legacy patch](../cordis.patch.yml) documents that historical meaning. It is not
+selected by the current native package metadata, and its presence is not a dual-mode switch.
+
+## What changed in 0.2
+
+| Concern | Public 0.1.1 | Native 0.2 and later |
+| --- | --- | --- |
+| DSH integration | in-box MCP client | native Cordis host adapter |
+| Core unit | governed job | conversation, run, and governed invocation |
+| Authentication | operator Client Token | end-user browser authorization with PKCE |
+| Tool surface | three fixed job tools | current-turn typed tools plus search/resume |
+| Reasoning/orchestration | BailingHub route | local DSH Agent |
+| Business identity | not established by DSH | Agent Session approved through the business boundary |
+| Hub audit | job records | conversation, run, completion, and invocation trajectory |
+
+## What 0.3 adds
+
+Version 0.3 keeps the same native boundary and adds stable named multi-connection lifecycle,
+same-binding trusted-identity reconciliation, and Windows CurrentUser DPAPI credential storage.
+It does not reinterpret or migrate the public 0.1.x Client Token path.
+
+The new plugin config is limited to `hubUrl`, `clientAppId`, `workspace`, and `connectionName`.
+The old `BAILINGHUB_CLIENT_TOKEN` is not read, copied, exchanged, or converted into an Agent
+Session. Browser authorization creates a new independently revocable credential in SDK-owned
+secure storage. The plugin does not accept a business URL: the Hub Client App resolves to one
+stable, account- and tenant-neutral business authorization entry, where the user can log in,
+switch account, and select a tenant.
+
+## Safe evaluation before migration
+
+Do not replace a working production profile merely to evaluate 0.3.0. Use a separate DSH home or
+another isolated Web profile and verify that the CLI really honors that location. Stable public
+`0.3.0` creates a separate credential for each name registered through
+`connections add` while authorization is pending. After authorization, the SDK replaces an older
+same-binding connection when its trusted `on_behalf_of` is the same; different trusted identities
+remain independent. A different identity returned from a same-alias login keeps the original
+alias and Session and receives a non-conflicting alias that becomes current. Use the exact matching
+SDK installed by the DSH package when evaluating that behavior.
+
+1. Keep the existing `0.1.1` profile and its legacy environment unchanged.
+2. Install the exact released 0.3 package into an isolated profile.
+3. Configure only the four public native fields using neutral values for dry composition.
+4. Run `/bailinghub login` and approve a dedicated non-production client app/workspace whose
+   credential can be revoked without affecting a maintainer's existing profile.
+5. Verify status, workspace discovery, one read, one permitted mutation, approval/resume, and Hub
+   trajectory.
+6. Separately re-run the `0.1.1` submit and same-job follow-up against the newly released Core.
+
+Passing the native path does not prove legacy compatibility, and passing the legacy path does not
+prove the native Agent Client.
+
+## Moving a profile to 0.3
+
+Only after the isolated acceptance passes:
+
+1. Record the exact old plugin, DSH, MCP, and Core versions without copying credentials into the
+   migration record.
+2. Finish or cancel outstanding legacy jobs. A wait timeout is not a terminal failure.
+3. Install the exact accepted 0.3 plugin version. Do not use an unpinned dist-tag.
+4. Replace the legacy plugin configuration with the four native fields. Remove the old Client
+   Token from that process environment after confirming no remaining 0.1 integration uses it.
+5. Start DSH, run `/bailinghub login`, use the business page to log in or switch account and select
+   a tenant if required, then authorize the intended workspace.
+6. Run `/bailinghub status`, open a new conversation, and repeat the accepted read/mutation checks.
+7. Confirm BailingHub receives visible conversation and invocation audit without hidden reasoning.
+
+The developer or deployer supplies the Hub URL, public client app id, and initial workspace/route.
+The end user completes browser authorization. Neither role supplies a business API secret or model
+key to this plugin.
+
+## Rollback
+
+Rollback is explicit; it does not convert the Agent Session back into a Client Token.
+
+Before downgrading a 0.3 profile to 0.2, first use the installed 0.3 plugin to finish active runs
+and remove every named instance through `/bailinghub connections remove <name>`. The SDK returns
+the registry to schema v1 after the last such instance is removed. Stable `0.2.0` fails closed on
+schema v2; do not manually delete the registry, Keychain entry, DPAPI ciphertext, or secure file
+credentials as a downgrade shortcut.
+
+1. Finish active native runs and use `/bailinghub sync` for any known pending completion.
+2. Run `/bailinghub logout` if the new Agent Session should be revoked.
+3. Reinstall exact `dsh-bailinghub@0.1.1` in the target profile.
+4. Restore the separately retained legacy Hub URL, route-scoped Client Token, and route through the
+   original `BAILINGHUB_BASE_URL`, `BAILINGHUB_CLIENT_TOKEN`, and `BAILINGHUB_ROUTE` environment
+   names.
+5. Verify the three fixed MCP tools and follow one stable `request_id`/`job_id` flow to terminal
+   state without resubmission.
+
+Do not delete SDK credential files or Keychain entries manually as a substitute for logout. Do not
+reuse, move, or republish an npm version or Git tag as a rollback mechanism.
+
+## Release gates
+
+Before any public 0.3 release:
+
+1. The matching BailingHub Core Agent Auth/Agent API contracts are released.
+2. The exact `bailinghub-mcp-server/sdk` version is publicly installable and has passed DTO,
+   credential, invoke/resume, and completion tests.
+3. Installing only `dsh-bailinghub` into a clean DSH `0.1.1-rc.2` profile installs and resolves that
+   exact SDK dependency automatically.
+4. Browser login, session isolation, dynamic tool replacement, approval recovery, visible
+   completion, same-identity replacement, different-identity isolation, and Hub trajectory pass
+   from the packaged artifact.
+5. Public `0.1.1` still works against the new Core through the unchanged Client API.
+6. The maintainer explicitly selects the public version and migration story.
+
+Do not tag or publish a future 0.3.x version until all gates pass, and do not describe release
+validation as public adoption.