From caf4dcae00a3b5b6ab9c00634293ee67a1953fa0 Mon Sep 17 00:00:00 2001 From: awork Date: Sat, 24 Oct 2026 01:52:04 +0800 Subject: [PATCH 1/2] docs(#4319): document the host-plugin integration contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extracted from PR #4327 per owner decision: the tab-naming/hiding side of the dsh-context coexistence work already shipped via merged PR #4238 (dsh.contextTab / dsh.contextTabLabel knobs), so only the stable-contract documentation remains from #4319. - README: new 'Host plugin integration' section — GET /bili/origin shapes (incl. the #4237 face flags, marked internal), GET /__bili/plugin/status stable field set, error shapes, loopback admin gate + trusted-Origin/CORS caveats, additive-evolution promise. - CLIENTS.md: pointer from the dsh Context-tab paragraph to that section. - PLUGIN.md: cross-ref in the status-route subsection for non-cooperative third-party readers. --- CLIENTS.md | 4 +++- PLUGIN.md | 2 +- README.md | 23 +++++++++++++++++++++++ 3 files changed, 27 insertions(+), 2 deletions(-) diff --git a/CLIENTS.md b/CLIENTS.md index 21fe8ae71f..09ffdc2bc8 100644 --- a/CLIENTS.md +++ b/CLIENTS.md @@ -203,7 +203,9 @@ anchor on its own labeled scale, and recent fold/switch events with reclaimed tokens. It refreshes every 10 s; when the running proxy predates this build the tab degrades to a restart notice plus an open-Web-UI button instead of guessing. Plain React from dsh's own runtime — no iframe, no added -dependencies. +dependencies. Third-party UI plugins can read the same status route +cross-origin — the stable contract (fields, errors, access gate, evolution +promise) is documented in README → **Host plugin integration** (#4319). ## Kimi Code (Moonshot) diff --git a/PLUGIN.md b/PLUGIN.md index d12ef260a1..2b14d3e960 100644 --- a/PLUGIN.md +++ b/PLUGIN.md @@ -104,7 +104,7 @@ Notes: ### 4. `GET /__bili/plugin/status?conversationId=` -Context-level visibility for plugin UIs (status bars / slash commands): +Context-level visibility for plugin UIs (status bars / slash commands). Third-party UI readers that are not cooperative plugins get the same route — its access gate and evolution contract live in README → **Host plugin integration** (#4319): ```json { diff --git a/README.md b/README.md index e89b209045..62adcd6c84 100644 --- a/README.md +++ b/README.md @@ -319,6 +319,29 @@ should see a `processTurn` line per request, and once the conversation grows, Everything that doesn't fit in one Quickstart line — how each client's lanes attach, what gets written where, and known limitations — lives in **[CLIENTS.md](CLIENTS.md)**: dsh · Kimi Code · Hermes · ZCode · Gemini family (Gemini CLI / iFlow CLI / Qwen Code / Antigravity) · cert-MITM clients that never compress (CONNECT blind tunnels, #897) · unrecognized endpoints going direct (#1290) · OpenCode (launcher / native / pure proxy, `/acp` status & rules, legacy opencode-acp sessions #920). +### Host plugin integration + +Stable read-only surface for third-party host-side UI plugins that want to show bili's wire-caliber numbers next to their own local views (e.g. [dsh-context](https://github.com/bowenliang123/dsh-context): where the tokens come from vs. what actually reaches the model). Two routes: + +**`GET /bili/origin`** — served by the host web server (registered by the dsh lane's native entry), answers where the bound bili proxy listens: + +- `{"origin":"http://127.0.0.1:"}` — use this as the base for all `/__bili/*` calls below; +- `{"origin":null,"relay":true}` — admin relay mode (#3373): derive your base from the probe response URL itself instead; +- `{"origin":null}` — no proxy bound yet (attach/spawn still booting); keep polling; +- route absent (404) — older host build without the route. + +Newer builds additionally carry bili's own UI face flags (`contextTab`, optional `contextTabLabel`, #4237) in the same body — internal to bili's DSH client bundle; ignore them. + +Poll while unresolved: the origin can land late (spawn mode binds after bootstrap) or move (runtime re-bind). + +**`GET /__bili/plugin/status?conversationId=`** — wire-caliber session stats. Full field semantics (observation lifecycle, fork behavior, revision guards): [PLUGIN.md](PLUGIN.md) §4. The stable contract surface is the documented field set there — `ok`, `conversationId`, `sessionId`, `sessionRevision`, `pluginAgent`, `model`, `contextLimit`, `contextTokens`, `contextTokensSource`, `contextTokensAt`, `contextGeneration`, `inputTokens`, `outputTokens`, `cachedTokens`, `requests`, `blocks`, `compressibleRanges`, `lastSeen`; fields not listed are internal and carry no guarantee. + +Errors: `400 {"ok":false,"error":"conversationId query parameter is required"}`; `404 {"ok":false,"error":"unknown plugin conversation"}` (with `fallback=latest`: `"no session with activity since boot …"`). Before any request lands, responses report `"phase":"pre-first-request"` or `"phase":"chain-advisory"` with null context fields instead of 404. + +Access: loopback-only management gate — the connection must come from loopback, the `Host` header must be a loopback name (`localhost` / `127.0.0.1` / `::1`, port ignored so SSH forwards work), and a browser `Origin` must be a loopback http(s) origin or the dsh desktop scheme (`dsh-app://app`). Non-browser clients without an `Origin` are admitted on a trusted Host. An admitted browser `Origin` is echoed back via `access-control-allow-origin`, so cross-origin `fetch` from the host web app works. + +Evolution: additive. Documented fields are never removed or re-semantized silently; new fields may appear at any time. Do not depend on undocumented fields. + ## From source (development) > **Risk:** `master` is the development branch and can be broken at any moment — unreleased changes, failing builds, unverified fixes. Unless you are patching the code or testing an unreleased fix, install a release with npm as above. From ed3e8dace754b0129b6c28d7c6a34a4ea4430296 Mon Sep 17 00:00:00 2001 From: awork Date: Sat, 24 Oct 2026 02:11:08 +0800 Subject: [PATCH 2/2] docs(#4319): clarify /bili/origin absence also covers web-server-less profiles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review fix on #4447: the route registers only when a dsh web server exists (src/agent/dsh-native.ts — TUI/headless profiles never fire the callback), so 'older host build' was an incomplete account of the 404 case. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 62adcd6c84..15e78c2016 100644 --- a/README.md +++ b/README.md @@ -328,7 +328,7 @@ Stable read-only surface for third-party host-side UI plugins that want to show - `{"origin":"http://127.0.0.1:"}` — use this as the base for all `/__bili/*` calls below; - `{"origin":null,"relay":true}` — admin relay mode (#3373): derive your base from the probe response URL itself instead; - `{"origin":null}` — no proxy bound yet (attach/spawn still booting); keep polling; -- route absent (404) — older host build without the route. +- route absent (404) — host build predates the route, or the dsh profile has no web server (TUI/headless); no amount of polling resolves that case. Newer builds additionally carry bili's own UI face flags (`contextTab`, optional `contextTabLabel`, #4237) in the same body — internal to bili's DSH client bundle; ignore them.