dsh-bailinghub 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 - 2026-09-01
+
+- Add `/bailinghub doctor` for credential-safe host-contract, configuration, SDK, authorization,
+  and workspace diagnostics before a business turn starts.
+- Add real lifecycle coverage for DeepSeek Harness `0.1.1-rc.2` and enforce it in Ubuntu,
+  Windows, and tagged publication workflows.
+- Make `connectionName` a user-controlled local selector while the business authorization page
+  owns login, account switching, tenant selection, and the trusted identity result.
+- Reconcile same-binding connections by trusted `on_behalf_of`: replace an older same-identity
+  connection, keep different identities independent, and surface cleanup-required authorization
+  as a successful login with an explicit no-reauthorize warning.
+- Preserve an existing alias and Session when same-alias authorization returns a different trusted
+  identity; allocate and select a non-conflicting local alias for the new identity.
+- Add user-only `/bailinghub connections list|add|use|remove` lifecycle commands with quoted-name
+  parsing, new-session-only selection, existing-session pinning, and revoke-before-remove safety.
+- Restore the SDK registry's current connection before the first new session or user command after
+  restart, with validated public metadata and a non-blocking bootstrap-field fallback.
+- Reconcile defaults after connection removal: adopt a remaining current profile, become
+  unconfigured after the last removal, and preserve successful removal across registry refresh
+  failures without disturbing a valid non-current default.
+- Pin the stable public `bailinghub-mcp-server@0.3.0` SDK, including Windows CurrentUser DPAPI
+  credential storage for Agent Session connections.
+
+## 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.

package/PRIVACY.md

@@ -9,3 +9,20 @@ 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.3.0
+
+The native 0.3.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. The SDK uses macOS Keychain, Windows CurrentUser DPAPI, or an explicitly
+enabled isolated mode-0600 POSIX file store. Review DSH, model-provider, BailingHub, and
+business-system retention boundaries before enabling the plugin.
+
+The multi-connection registry contains public connection name, Hub URL, client app id, workspace,
+timestamps, and current-selection state. It does not contain access tokens, refresh tokens, model
+keys, business cookies, prompts, tool arguments, or business results.

package/README.md

@@ -2,103 +2,241 @@
 
 [简体中文](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 your local DeepSeek Harness Agent to operate the admin side of an online store, SaaS product,
+or other business system through BailingHub. Ask it to look up data, update records, or run other
+actions available to the connected account. The existing business identity, permissions, and
+approval rules still apply, and BailingHub keeps the authorization and action trail.
+
+For example, depending on what the connected business system has exposed, you can ask the local
+Agent to:
+
+- find an order, customer, product, or employee record;
+- update an allowed field or business status;
+- run another permitted admin action;
+- return the result while BailingHub records the corresponding tool steps.
+
+Reasoning and tool orchestration stay in DSH. BailingHub supplies the authorized business context,
+available capabilities, approval state, invocation recovery, and audit records required for the
+local Agent to act safely.
 
 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.3.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:
+For the shortest end-user path, follow the [three-minute getting started guide](docs/GETTING_STARTED.md).
 
-| 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 |
+## How the 0.3 Agent Client fits together
+
+```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 selection, 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.
 
-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.
+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.
 
-## Install
+## Before installing
+
+The deployer and business integrator must prepare these public identifiers in BailingHub:
+
+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. One stable, account- and tenant-neutral business authorization entry configured on the Hub
+   Client App, plus a governed ACC/Tool Provider integration behind that route. The business page
+   must handle sign-in, account switching, and tenant selection before it approves the request.
+
+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.3 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 a DeepSeek Harness release listed in the compatibility matrix;
+- 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.1
+npm install --global pnpm @deepseek-ai/dsh@0.1.1-rc.2
+dsh plugin --profile web add dsh-bailinghub@0.3.0
 ```
 
-Configure the process that starts Harness:
+`dsh-bailinghub@0.3.0` installs its exact compatible `bailinghub-mcp-server@0.3.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` | User-selected local connection label | 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. The Hub resolves the
+Client App to its single business authorization entry. `connectionName` is only a user-controlled
+local selector; it is not an account, tenant, or identity claim.
+
+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:
+
+```text
+/bailinghub login
+/bailinghub doctor
+/bailinghub status
+/bailinghub workspaces
+```
 
-## Correct Task Flow
+`login` opens the system browser at the single business authorization entry configured by the Hub
+operator. That business page owns sign-in, account switching, and tenant selection, confirms the
+resulting 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.
 
-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.
+Useful commands:
 
-## Identity and Permission Boundary
+| Command | Purpose |
+| --- | --- |
+| `/bailinghub doctor` | Check host APIs, public configuration, SDK resolution, authorization, and workspace reachability without printing credentials |
+| `/bailinghub connections list` | List local public connection metadata and authorization state without tokens |
+| `/bailinghub connections add <name> <hub-url> <client-app-id> <workspace>` | Create and select another local connection instance for new sessions; the public binding may match an existing instance |
+| `/bailinghub connections use <name-or-key>` | Select a registered connection for new sessions only |
+| `/bailinghub connections remove <name-or-key>` | Remotely revoke its Agent Session, then remove its local credential and metadata |
+| `/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 four plugin fields are the bootstrap connection. Additional connections can be registered with
+`connections add`; the BailingHub console's Agent Client page can generate the same secret-free
+command. On restart, the adapter reads the SDK registry before the first new Agent session or user
+command and adopts its current connection's public metadata; a missing or unavailable registry
+safely falls back to the four bootstrap fields. Quote a connection name when it contains spaces.
+After `connections use`, run `/bailinghub login` if that binding is not authorized yet.
+
+Connection selection is a user-only slash command and is never exposed as a model tool. It affects
+only Agent sessions created afterward; existing sessions remain pinned to their original
+connection and workspace. `/bailinghub use <workspace>` remains a different operation: it succeeds
+only when the current Agent Session already authorizes that workspace.
+
+After removing the selected connection, the adapter reads the SDK registry and adopts the remaining
+current connection for new sessions, including connections without an alias. Removing the final
+connection leaves the adapter explicitly unconfigured. A failed post-remove registry read never
+turns a successful removal into an error; removing a non-current connection also preserves the
+still-valid default when that refresh is unavailable.
+
+For the same `Hub + clientAppId + workspace` public binding, browser authorization determines the
+identity from the business page and its trusted `on_behalf_of` result. If that identity is already
+authorized under another local connection name, the SDK replaces the older local connection and
+revokes its old Agent Session. A different trusted identity remains an independent connection.
+If login starts from a `connectionName` that already belongs to another identity, the SDK keeps
+that original alias and Session, gives the newly authorized identity an available local alias such
+as `default-2`, and selects the new alias for future sessions. Use `connections list` to see both
+and `connections use <name-or-key>` to switch explicitly.
+If login returns `cleanupRequired: true`, the newly selected connection is still authorized, but
+one or more existing same-binding connections need explicit cleanup. Their identity may still be
+unconfirmed when inspection was deferred. Do not authorize again; inspect
+`connections list` and retry `/bailinghub connections remove <name-or-key>` for the reported old
+entry.
+
+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, local connection, business identity, credential,
+  approval result, or capability revision through tool arguments.
+- The SDK stores credentials in macOS Keychain. On Windows it protects credential files under
+  LocalAppData with CurrentUser DPAPI; unavailable Windows PowerShell or DPAPI fails closed without
+  a plaintext fallback. Linux and other POSIX systems require an explicit secure file-store opt-in.
+- 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.
 
-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.
-The current `0.1.x` bundle 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.
+```bash
+dsh plugin --profile web add dsh-bailinghub@0.1.1
 
-This bundle governs only tasks submitted through its three BailingHub tools. It does not
-intercept or govern every other tool installed in DeepSeek Harness.
+export BAILINGHUB_BASE_URL='https://hub.example.com'
+export BAILINGHUB_CLIENT_TOKEN='replace-with-a-route-scoped-client-token'
+export BAILINGHUB_ROUTE='order_assistant'
+```
 
-## Supply-Chain Note
+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.3 Agent Client does not automatically consume or migrate the 0.1 Client Token. Keep versions
+explicit and follow the [0.1-to-0.3 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.3.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,34 @@ 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.3.0 boundary
+
+The native 0.3.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,
+handles login, account switching, tenant selection, and the trusted `on_behalf_of` identity.
+
+The multi-connection registry stores only public Hub/client/workspace metadata. `connectionName`
+is a user-only local selector, not an identity claim. After browser
+authorization, the SDK replaces an older same-binding connection only when the trusted
+`on_behalf_of` matches; different trusted identities remain isolated. A same-alias authorization
+for a different identity preserves the original alias and Session and assigns the new identity a
+non-conflicting local alias. If inspection or old-Session revocation is uncertain, the new
+connection stays authorized and explicit cleanup is required.
+Connection add/use/remove are user slash commands, not model tools. Removing an authorized
+connection is remote-revoke-first and keeps the local credential if revocation fails, so it cannot
+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
+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.
+
+Agent Session credentials use macOS Keychain or Windows CurrentUser DPAPI-protected files under
+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.

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'