dsh-bailinghub 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.2.0 - 2026-08-26
+
+- Add the native Cordis Agent Client adapter that keeps reasoning and orchestration in local DSH
+  while BailingHub retains identity, context, capability governance, approval, recovery, and audit.
+- Add browser authorization, isolated connection aliases, dynamic per-turn business tools,
+  capability search, exact-invocation resume, and visible-only run completion through the generic
+  `bailinghub-mcp-server/sdk` facade.
+- Restrict host configuration to `hubUrl`, `clientAppId`, `workspace`, and `connectionName`; no
+  business endpoint, Client Token, model key, or other secret is accepted by the plugin config.
+- Preserve public `0.1.1` as the explicit static MCP/Client Token compatibility path rather than
+  silently migrating its credentials or orchestration semantics.
+- Pin `bailinghub-mcp-server@0.2.0` as an ordinary dependency so installing only this plugin also
+  installs the exact compatible Agent Client SDK.
+- Document the Core to MCP/SDK to DSH release order and the clean-profile browser-auth acceptance
+  gate.
+
+## 0.1.1 - 2026-08-18
+
+- Make the project contract accept future SemVer releases while keeping package and lock versions aligned.
+- Keep the npm landing page English-first and retain the Chinese guide under `docs/`.
+- Document the exact release-update surface, focused compatibility smoke, and patch-release recovery path.
+
 ## 0.1.0 - 2026-08-18
 
 - Add an installable DeepSeek Harness bundle for BailingHub.

package/PRIVACY.md

@@ -9,3 +9,15 @@ using personal, confidential, or regulated data.
 
 Do not include tokens, private URLs, personal information, or production payloads in public
 issues, screenshots, or compatibility reports.
+
+## Native Agent Client 0.2.0
+
+The native 0.2.0 plugin sends each direct human user turn to BailingHub Core and receives
+model-visible instructions, memory, reference-only knowledge, governance, and active tool schemas.
+Business tool arguments and governed results cross the same boundary. At completion it sends only
+the hash-aliased assistant message id, visible final text, legal status, optional model/runtime
+labels, and numeric public usage. It ignores `assistant/chunk` and never uploads hidden reasoning.
+
+Browser authorization, refresh, and credential storage remain SDK-owned; this adapter stores no
+BailingHub credential. Review DSH, model-provider, BailingHub, and business-system retention
+boundaries before enabling the plugin.

package/README.md

@@ -1,104 +1,190 @@
 # BailingHub for DeepSeek Harness
 
-[简体中文](README.zh-CN.md) | English
+[简体中文](docs/README.zh-CN.md) | English
 
-Run governed tasks from DeepSeek Harness against a business route already connected to
-BailingHub, then track the same job and read its available result. You can do this from the
-Harness Web UI on your own computer without opening the embedded chat page in each business
-backend.
+Use a local DeepSeek Harness Agent to discover and invoke business capabilities governed by a
+self-hosted BailingHub. Reasoning and tool orchestration stay in DSH; BailingHub retains trusted
+identity, runtime context, capability trimming, approval, invocation recovery, and audit.
 
 This is an independent community integration. It is not developed, certified, endorsed, or
 recommended by DeepSeek.
 
-## What You Get
+> **Current stable line:** `dsh-bailinghub@0.2.0` uses the native Agent Client flow documented
+> below. Public `0.1.1` remains available only as the explicit static MCP compatibility path.
 
-After installation, DeepSeek Harness discovers three native tools:
+## How the 0.2 Agent Client fits together
 
-| Harness tool | What it does |
-| --- | --- |
-| `mcp__bailinghub__submit_governed_job` | Submit task text with a stable request ID |
-| `mcp__bailinghub__get_governed_job` | Read the current state and public result of one job |
-| `mcp__bailinghub__wait_for_governed_job` | Wait briefly for the same job without resubmitting it |
+```text
+DeepSeek Harness local Agent
+  -> dsh-bailinghub native Cordis adapter
+  -> bailinghub-mcp-server/sdk
+  -> BailingHub Agent Auth + Agent API
+  -> operator-selected business integration and final authorization
+```
+
+The packages have separate responsibilities:
+
+- **BailingHub Core** owns Agent Auth, trusted business identity, runtime context, knowledge and
+  memory projection, capability governance, approvals, invocation state, and audit records.
+- **`bailinghub-mcp-server/sdk`** owns browser login, PKCE, credential storage, refresh,
+  Hub/client/workspace connection isolation, and HTTP DTO mapping.
+- **`dsh-bailinghub`** owns only DSH session, prompt, command, and dynamic-tool lifecycle
+  integration. It does not store credentials or call a business API directly.
+
+This Agent Client is not the BailingHub executor. The executor receives jobs from the Hub for
+work that must run near a machine; the Agent Client keeps the interactive reasoning loop on the
+user's local DSH Agent.
+
+## Before installing
+
+The deployer and business integrator must prepare these public identifiers in BailingHub:
 
-BailingHub remains the control plane between the model and the business system. The URL,
-Client Token, and route are operator configuration, not model arguments. The model cannot
-switch to another route or supply administrator, executor, approval, or business-system
-credentials through these tools.
+1. A reachable HTTPS BailingHub deployment with the matching Agent Auth and Agent API contracts.
+2. A public Agent Client application id (`clientAppId`).
+3. At least one authorized workspace. In Agent Client v1, the workspace id is the BailingHub
+   route id.
+4. A business authorization page and governed ACC/Tool Provider integration behind that route.
 
-## Install
+The end user does **not** enter a business API URL, business login credential, Tool Provider
+signing secret, BailingHub Client Token, or model-provider key into this plugin.
+
+## Install the 0.2 line
 
 Prerequisites:
 
 - Node.js `22.19.0+` or `24+`;
-- `pnpm` and `@deepseek-ai/dsh@0.1.0-rc.7`;
-- a reachable [BailingHub deployment](https://github.com/bailinghub/bailinghub#quick-start);
-- one BailingHub Client Token restricted to the route you want this Harness profile to use.
+- `pnpm` and DeepSeek Harness `0.1.0-rc.7`;
+- the BailingHub preparation above.
+
+Install the exact stable version into the DSH Web profile:
 
 ```bash
 npm install --global pnpm @deepseek-ai/dsh@0.1.0-rc.7
-dsh plugin --profile web add dsh-bailinghub@0.1.0
+dsh plugin --profile web add dsh-bailinghub@0.2.0
 ```
 
-Configure the process that starts Harness:
+`dsh-bailinghub@0.2.0` installs its exact compatible `bailinghub-mcp-server@0.2.0` dependency
+automatically. DSH users should not separately guess or install an SDK version.
+
+## Configure one Hub connection
+
+The native plugin has exactly four host configuration fields:
+
+| Plugin field | Environment value | Meaning | Secret |
+| --- | --- | --- | --- |
+| `hubUrl` | `BAILINGHUB_HUB_URL` | Public HTTPS URL of the developer's own BailingHub | No |
+| `clientAppId` | `BAILINGHUB_CLIENT_APP_ID` | Public Agent Client application id registered in that Hub | No |
+| `workspace` | `BAILINGHUB_WORKSPACE` | Initial authorized workspace/route id | No |
+| `connectionName` | `BAILINGHUB_CONNECTION_NAME` | Local alias for this isolated SDK connection | No |
+
+Example placeholders:
 
 ```bash
-export BAILINGHUB_BASE_URL='https://hub.example.com'
-export BAILINGHUB_CLIENT_TOKEN='replace-with-a-route-scoped-client-token'
-export BAILINGHUB_ROUTE='order_assistant'
+export BAILINGHUB_HUB_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_APP_ID='example-agent-client'
+export BAILINGHUB_WORKSPACE='order_assistant'
+export BAILINGHUB_CONNECTION_NAME='default'
 ```
 
-Then verify the composed profile and start the local Web UI:
+The same four fields may be supplied through the DSH plugin settings surface. Do not add tokens,
+authorization URLs, business domains, or credentials to the Cordis patch.
+
+Inspect the composed profile before starting it:
 
 ```bash
 dsh --profile web --dump-config
 dsh web
 ```
 
-The default Web UI is local to your computer. Ask Harness to submit a task through
-BailingHub, preserve the returned `job_id`, and wait for or query that same job.
+## Authorize and use the local Agent
 
-For a first try, use a task supported by your configured route and say explicitly: submit it
-once with a stable `request_id`, preserve the returned `job_id`, and query that same job if a
-bounded wait times out.
+In DSH, run:
 
-## Correct Task Flow
+```text
+/bailinghub login
+/bailinghub status
+/bailinghub workspaces
+```
 
-1. Generate one stable `request_id` for one business request.
-2. Call `mcp__bailinghub__submit_governed_job` once.
-3. Preserve its `job_id`.
-4. Call `wait_for_governed_job`, or call `get_governed_job` later.
-5. A wait timeout is not a failed task. Do not submit a replacement request.
+`login` opens the system browser. The business-side authorization page confirms the signed-in
+business identity and requested workspace, then returns to a random loopback callback protected
+by `state` and PKCE S256. Access and refresh tokens remain in SDK-owned secure storage and are
+never written to the plugin configuration or printed by the command.
 
-## Identity and Permission Boundary
+Useful commands:
 
-Using the local Harness UI removes the need to open a business backend's embedded chat UI;
-it does **not** turn the Harness login or local user into a trusted business identity.
-Version `0.1.0` deliberately does not accept an acting subject as tool input. A route or
-downstream business system must still resolve trusted identity and perform final
-authorization. If the selected action requires identity that the configured path cannot
-establish, it should remain unavailable or be rejected.
+| Command | Purpose |
+| --- | --- |
+| `/bailinghub login` | Authorize the configured Hub/client/workspace in the browser |
+| `/bailinghub status` | Inspect the selected connection without printing credentials |
+| `/bailinghub workspaces` | List workspaces allowed by the current business authorization |
+| `/bailinghub use <workspace>` | Select another already-authorized workspace for new sessions |
+| `/bailinghub sync` | Retry a pending visible completion record without repeating a tool call |
+| `/bailinghub logout` | Revoke and remove the selected Agent Session |
+
+The standard v1 login requests only the configured workspace. `use` succeeds only when the
+current Agent Session explicitly contains the target workspace; it is not permission to switch to
+an arbitrary Hub route. The current command set always operates on this plugin instance's four
+configured fields; it does not accept a connection selector. For another Hub or route, use a
+second DSH profile/plugin instance, or edit those fields and reload the profile, set a different
+`connectionName`, and complete browser authorization again.
+
+For the first acceptance check, start a new DSH conversation and perform one read-only request,
+then one permitted mutation. Confirm the same conversation, run, visible final answer, and tool
+invocation trajectory appear in BailingHub. An approval-required capability must resume the
+original invocation after approval; it must never create a replacement business call.
+
+DSH Code Mode is deliberately degraded in this release because it cannot safely present the
+current-turn dynamic schemas. Use native tool mode for governed business actions.
+
+## Security and privacy boundary
+
+- The model cannot choose a Hub URL, workspace, identity, credential, approval result, or
+  capability revision through tool arguments.
+- The SDK stores credentials in macOS Keychain. Linux and other POSIX systems require an explicit
+  secure file-store opt-in; Windows Agent Session storage is not supported in 0.2.0.
+- BailingHub revalidates identity, scope, approval, idempotency, and invocation state on every
+  governed call. The downstream business system still performs final authorization.
+- The adapter sends visible user input, governed tool arguments/results, and the visible final
+  answer required by the Agent Client contracts. It never uploads hidden reasoning chunks.
+- This plugin governs only the BailingHub tools it registers. It does not intercept unrelated DSH
+  tools or model-provider traffic.
+
+Review [Security](SECURITY.md), [Privacy](PRIVACY.md), the
+[Agent Client contract](docs/AGENT_CLIENT_CONTRACT.md), and
+[compatibility](docs/COMPATIBILITY.md) before production use.
+
+## Legacy public 0.1.x static mode
+
+Public `dsh-bailinghub@0.1.1` remains an immutable configuration-only bundle. It uses the in-box
+DSH MCP Client to start `bailinghub-mcp-server@0.1.1`, binds one operator-provisioned Client Token
+to one fixed route, and leaves orchestration in BailingHub.
 
-This bundle governs only tasks submitted through its three BailingHub tools. It does not
-intercept or govern every other tool installed in DeepSeek Harness.
+```bash
+dsh plugin --profile web add dsh-bailinghub@0.1.1
 
-## Supply-Chain Note
+export BAILINGHUB_BASE_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_TOKEN='replace-with-a-route-scoped-client-token'
+export BAILINGHUB_ROUTE='order_assistant'
+```
+
+It exposes exactly these three tools:
 
-This bundle contains no custom runtime JavaScript, no production dependencies, and no
-install scripts. When Harness starts the bundle, its built-in MCP Client runs the pinned
-command `npx -y --package=bailinghub-mcp-server@0.1.1 bailinghub-mcp-server` outside the
-agent sandbox. The first start may
-need npm network access. Review and pin the package before using it in a sensitive
-environment; production images may pre-cache the exact version.
+```text
+mcp__bailinghub__submit_governed_job
+mcp__bailinghub__get_governed_job
+mcp__bailinghub__wait_for_governed_job
+```
 
-Non-loopback HTTP is rejected by the MCP server by default. Only set
-`BAILINGHUB_ALLOW_INSECURE_HTTP=true` on a controlled private network where TLS terminates at
-another trusted boundary.
+The 0.2 Agent Client does not automatically consume or migrate the 0.1 Client Token. Keep versions
+explicit and follow the [0.1-to-0.2 migration boundary](docs/MIGRATION_VNEXT.md) when testing or
+rolling back.
 
-## Compatibility and Feedback
+## Compatibility and feedback
 
-The first release is verified against DeepSeek Harness `0.1.0-rc.7`,
-`bailinghub-mcp-server@0.1.1`, and BailingHub Client API v1. Harness is still a developer
-preview, so each Harness release requires a compatibility smoke test.
+Version 0.2.0 is verified only against the versions listed in
+[docs/COMPATIBILITY.md](docs/COMPATIBILITY.md). DeepSeek Harness remains a developer preview, so
+every Harness release requires a new native lifecycle smoke test.
 
 Report problems through [GitHub Issues](https://github.com/bailinghub/bailinghub-dsh-plugin/issues).
 Never include tokens, private deployment URLs, personal information, or production business

package/SECURITY.md

@@ -4,7 +4,7 @@ Report vulnerabilities through a private GitHub Security Advisory in this reposi
 Do not put tokens, private deployment URLs, personal information, or raw business payloads
 in a public issue.
 
-## Boundary
+## Public legacy 0.1.x boundary
 
 This bundle contributes configuration only. It has no custom runtime JavaScript, production
 dependencies, or install-time scripts. On Harness startup, the built-in DSH MCP Client runs
@@ -18,3 +18,16 @@ or acting-subject credential. Route, URL, and token stay in operator-controlled
 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.2.0 boundary
+
+The native 0.2.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.
+
+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.2.0 installs `bailinghub-mcp-server@0.2.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.

package/cordis.agent-client.patch.yml

@@ -0,0 +1,8 @@
+- insert:
+    - id: bailinghub-agent-client-vnext
+      name: dsh-bailinghub
+      config:
+        hubUrl: !!js process.env.BAILINGHUB_HUB_URL ?? ''
+        clientAppId: !!js process.env.BAILINGHUB_CLIENT_APP_ID ?? ''
+        workspace: !!js process.env.BAILINGHUB_WORKSPACE ?? ''
+        connectionName: !!js process.env.BAILINGHUB_CONNECTION_NAME ?? 'default'

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -0,0 +1,198 @@
+# Agent Client Host Adapter Contract
+
+Status: public native Agent Client contract for `dsh-bailinghub@0.2.0`. This contract is not part
+of the legacy public `0.1.x` line.
+
+## Host Configuration
+
+The Cordis Config schema contains only:
+
+```text
+hubUrl
+clientAppId
+workspace
+connectionName
+```
+
+`hubUrl`, `clientAppId`, and `workspace` identify a public Hub-side application/workspace.
+`connectionName` is a local SDK alias. No business endpoint, authorization endpoint, token, secret,
+or business credential belongs in this config.
+
+## 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
+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.
+
+## 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 rc.7 Lifecycle
+
+DSH `0.1.0-rc.7` claims 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 name, workspace, conversation alias, Core run, active definitions, and completion
+state are isolated per DSH Agent/session. A workspace switch affects future sessions and is
+rejected while any Core run is active/completing or has an unsynchronized completion payload.
+
+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.
+
+DSH `0.1.0-rc.7` reports 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,81 @@
 # Compatibility
 
+## Native Agent Client 0.2.0
+
 | Component | Verified version |
 | --- | --- |
+| DeepSeek Harness / Cordis lifecycle | `0.1.0-rc.7` |
+| Node.js | `22.19.0+` or `24+` |
+| DSH tool presentation | Native Tool Mode |
+| Generic Agent Client SDK | `bailinghub-mcp-server@0.2.0` via `./sdk` |
+| BailingHub Core | `bailinghub@0.5.0`; 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.2.0 declares `bailinghub-mcp-server@0.2.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.0 includes migrations 055/056 and 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.
+
+### 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.2.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 credential storage is not supported by 0.2.0. Do not describe
+  Client Token compatibility as native Agent Session support.
+- 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.
+
+## 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.2 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.2: clean install of only the exact plugin package, browser authorization, workspace
+   discovery, 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.