@sqdr2/dsh-agent-studio-fusion 0.0.0-stage → 1.0.0

package/INSTALL.md

@@ -0,0 +1,72 @@
+# Install DSH Agent Studio
+
+[中文](INSTALL.zh.md) · Product pages: [README.md](README.md) (中文), [README.en.md](README.en.md)
+
+Requires **DeepSeek Harness `>=0.2.1-rc.5 <0.3.0-0`** on **Node 24 or newer**. Other versions are not supported;
+the 0.2.0 series is no longer supported.
+
+> Published as `@sqdr2/dsh-agent-studio-fusion`, with plugin id `dsh-agent-studio-fusion`.
+> Any existing data from `dsh-fusion` or `dsh-model-fusion` is migrated automatically on first start.
+
+## From npm (recommended)
+
+```sh
+dsh plugin --profile web add @sqdr2/dsh-agent-studio-fusion
+```
+
+## From GitHub
+
+The repository ships the built `lib/`, so nothing is compiled locally.
+
+```sh
+dsh plugin --profile web add github:SQDR2/dsh-agent-studio-fusion
+```
+
+If `dsh` is not on PATH, pin one supported CLI:
+
+```sh
+npx @deepseek-ai/dsh@0.2.1-rc.5 plugin --profile web add @sqdr2/dsh-agent-studio-fusion
+```
+
+This writes only the `web` profile. Reopen a running Web Host once and reload the page.
+
+## From a local checkout (development)
+
+```sh
+git clone https://github.com/SQDR2/dsh-agent-studio-fusion.git ~/github/dsh-agent-studio-fusion
+cd ~/github/dsh-agent-studio-fusion && corepack pnpm@9.15.9 install --frozen-lockfile && cd -
+dsh plugin --profile web add ~/github/dsh-agent-studio-fusion
+```
+
+## DSH Studio desktop app
+
+Click **Plugins** in the left sidebar → **Add plugin**, and enter in "Package name or address":
+
+```text
+@sqdr2/dsh-agent-studio-fusion
+```
+
+`github:SQDR2/dsh-agent-studio-fusion` works there too. Then quit and reopen DSH Studio (plugins take effect at the next start).
+
+## Upgrading from earlier packages
+
+1. Remove previous packages to avoid conflicts:
+
+   ```sh
+   dsh plugin --profile web remove @sqdr2/dsh-fusion
+   dsh plugin --profile web remove dsh-model-fusion
+   ```
+
+2. Install `@sqdr2/dsh-agent-studio-fusion` as shown above. Do **not** delete the data directory:
+   all ledger, tasks and state will migrate into `$DSH_HOME/plugins/dsh-agent-studio-fusion/` automatically.
+3. If you had standalone `dsh-agy-worker` installed, remove it:
+   ```sh
+   dsh plugin --profile web remove @sqdr2/dsh-agy-worker
+   ```
+4. Restart DSH.
+
+## Uninstall
+
+```sh
+dsh plugin --profile web remove @sqdr2/dsh-agent-studio-fusion
+```

package/INSTALL.zh.md

@@ -0,0 +1,73 @@
+# 安装 DSH Agent Studio
+
+[English](INSTALL.md) · 产品介绍：[README.md](README.md)（中文）、[README.en.md](README.en.md)
+
+需要 **DeepSeek Harness `>=0.2.1-rc.5 <0.3.0-0`**，并需要 **Node 24 或更新版本**。其他版本不支持；0.2.0 系列已不再支持。
+
+> 包名 `@sqdr2/dsh-agent-studio-fusion`，插件 id 为 `dsh-agent-studio-fusion`。
+> 旧的 `dsh-fusion` 或 `dsh-model-fusion` 数据会在首次启动时自动迁移。
+
+## 从 npm 安装（推荐）
+
+```sh
+dsh plugin --profile web add @sqdr2/dsh-agent-studio-fusion
+```
+
+## 从 GitHub 安装
+
+仓库里带着构建好的 `lib/`，不需要自己编译。
+
+```sh
+dsh plugin --profile web add github:SQDR2/dsh-agent-studio-fusion
+```
+
+`dsh` 不在 PATH 里时，指定一个受支持的 CLI：
+
+```sh
+npx @deepseek-ai/dsh@0.2.1-rc.5 plugin --profile web add @sqdr2/dsh-agent-studio-fusion
+```
+
+这只会写入 `web` 配置。正在运行的 Web 服务需要重新打开一次，再刷新页面。
+
+## 从本地目录安装（开发用）
+
+```sh
+git clone https://github.com/SQDR2/dsh-agent-studio-fusion.git ~/github/dsh-agent-studio-fusion
+cd ~/github/dsh-agent-studio-fusion && corepack pnpm@9.15.9 install --frozen-lockfile && cd -
+dsh plugin --profile web add ~/github/dsh-agent-studio-fusion
+```
+
+## DSH Studio 桌面版
+
+点左侧栏的 **插件** → **添加插件**，在"包名或地址"里填：
+
+```text
+@sqdr2/dsh-agent-studio-fusion
+```
+
+也可以填 `github:SQDR2/dsh-agent-studio-fusion`。装好后退出并重新打开 DSH Studio（插件在下次启动时生效）。
+
+## 从旧版本迁移
+
+1. 先卸载旧包，避免多个包同时注册插件入口：
+
+   ```sh
+   dsh plugin --profile web remove @sqdr2/dsh-fusion
+   dsh plugin --profile web remove dsh-model-fusion
+   ```
+
+2. 按上面的方式安装 `@sqdr2/dsh-agent-studio-fusion`。**不要**先手动删除旧数据目录：
+   `$DSH_HOME/plugins/dsh-fusion/` 或 `dsh-model-fusion/` 里的任务、用量和设置会在首次启动时整体迁移到
+   `$DSH_HOME/plugins/dsh-agent-studio-fusion/`。
+3. 如果之前单独装过 `dsh-agy-worker`，也予以卸载（功能已完全内置）：
+   ```sh
+   dsh plugin --profile web remove @sqdr2/dsh-agy-worker
+   ```
+4. 重启 DSH（桌面版退出后重开，Web 版重开服务并刷新页面）。
+5. 已有的会话不用改：模型菜单里的选项会自动兼容指向新的线路。
+
+## 卸载
+
+```sh
+dsh plugin --profile web remove @sqdr2/dsh-agent-studio-fusion
+```

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.en.md

@@ -0,0 +1,207 @@
+# DSH Agent Studio With Fusion
+
+[中文](README.md) · [Install](INSTALL.md) · [Changelog](CHANGELOG.md) · [Doc index](#doc-index)
+
+<img src="assets/icon.svg" width="72" alt="">
+
+**The expensive model only thinks; the cheap model does the work — as one plugin, and as an ordinary model in DSH.**
+
+After installing, the left sidebar has a **Fusion** entry whose page holds three sections: **Fusion combos**, **Antigravity** (the `agy` CLI) and **ACP routes**. No `dsh-agy-worker`, no `dsh-tauri-acp`, no companion package.
+
+| | |
+|---|---|
+| Package | `@sqdr2/dsh-agent-studio-fusion` |
+| Plugin id | `dsh-agent-studio-fusion` (config row, state directory and log marker) |
+| Provider route | `dsh-fusion`, shown in the model menu as **Fusion · combo name** |
+| Requirements | DSH `>=0.2.1-rc.5 <0.3.0-0`, Node 24+ |
+
+## What it solves
+
+Behind every **Fusion combo** are two models you choose:
+
+- **Lead**: a strong frontier model. It reads the request and the code, briefs the work, reviews the result and sends it back. It **does not write code** — it has no file-writing tools, and its shell commands run in DSH's read-only sandbox. The program enforces that, not the prompt.
+- **Sidekick**: a much cheaper model. It edits files, runs commands, runs tests and reports back.
+- **One goal**: frontier-model results at a discount. The saving comes from the price gap — the Sidekick must cost far less than the Lead (ideally 5× or more). The closer their prices, the smaller the saving.
+
+Inspired by Fusion in Cognition's Devin. This is an independent implementation, not affiliated with Cognition.
+
+## Measured
+
+Nine real open-source issues (SWE-rebench, Python), two runs each, graded by hidden tests. Lead GPT-6 Astra (high), Sidekick GLM-5.3-Flash (high):
+
+| | Solved | Total cost (API list prices) |
+|---|---|---|
+| GPT-6 Astra alone | 9/18 | $39.17 |
+| **Fusion: Astra + GLM-5.3-Flash** | **11/18** | **$18.07 (54% less)** |
+| Fusion: Astra + Grok 4.6 | 13/18 | $41.27 (no saving) |
+
+Against Devin's own Fusion — the same pair (Lead GPT-6 Astra, Sidekick SWE-2), the same tasks, workspaces and hidden tests. After contaminated attempts were excluded, four tasks were clean in every condition: **this plugin 4/4, $2.73**; Devin Fusion 3/4, $4.81; Devin with Astra alone 3/4, $8.13. This plugin took about 3.4× Devin's wall time.
+
+The samples are small (4 tasks × 1 run; 9 tasks × 2 in the other round), Python only, and public issues may be in training data — so this is **not** a ranking, and not a parity claim. Method, raw data, per-round conclusions and the excluded attempts: **[docs/EVIDENCE.md](docs/EVIDENCE.md)**.
+
+## Use
+
+```sh
+dsh plugin --profile web add @sqdr2/dsh-agent-studio-fusion
+```
+
+Installing straight from GitHub works too (the repository ships a built `lib/`): `dsh plugin --profile web add github:SQDR2/dsh-agent-studio-fusion`. Desktop-app install, local-directory install, uninstall and migration from older packages: **[INSTALL.md](INSTALL.md)**.
+
+1. Open **Fusion** in the left sidebar (default below Memory System).
+2. In **Fusion combos**, name the combo and choose a Lead and a Sidekick. Any model you are signed in to works, including a configured Antigravity or ACP route.
+3. Pick **Fusion · combo name** in the model menu and work as usual.
+4. Fusion's chip near the composer names the role working right now: `Lead · Read Only` / `Sidekick · Full access`.
+
+**Up to 6 combos** can coexist — a cheap "fast" one and a strong "thorough" one, each its own model-menu entry. With several conversations open, each can pick a different combo; a conversation freezes the combo it picked, so later edits or other conversations never change it. A pre-combo installation is migrated into one combo named "自动" whose model id stays `auto`, so existing conversations keep working.
+
+The composer's permission control reads `Custom` once a task is dispatched: the Lead's session is pinned to read-only, and "read-only plus your approval policy" usually matches no configured preset. That control still sets the **Sidekick's** permission — change it and the Sidekick's next step uses that mode, while the Lead stays read-only. If you would rather it read a name instead of `Custom`, add a preset to your profile's `presets` with `sandbox: read-only` and `approval: never` — pure configuration, this plugin does not depend on it.
+
+## How one task runs
+
+1. The Lead decides code must change and hands the work to the Sidekick. The brief carries the user's own words and the acceptance commands.
+2. The Sidekick reports; DSH runs the acceptance commands in the real workspace.
+3. The Lead reviews each of the user's hard requirements and must give a verdict with evidence for every one — a missing verdict blocks acceptance. If the Sidekick rewrote an existing test, that is flagged and needs the Lead's confirmation.
+4. A rejection goes back to the same Sidekick with the concrete problem. When the allowed files turn out too narrow (say another test file still encodes the old behaviour), the Lead may only **add** paths during rework, never remove them, and every addition is recorded.
+5. Tests that were already failing (a missing optional dependency, for instance) can be marked "no new failures".
+6. **The one exception**: a takeover the Host unlocks only when the Sidekick demonstrably cannot finish (still failing after 2 rework rounds, step limit reached, repeated stalls). The Lead may then change only the files the task allows, must pass the same acceptance, and returns to read-only afterwards.
+7. Quota or provider errors are handled per role: switch a model or schedule a continuation, with progress kept.
+
+## The three routes
+
+### Fusion combos
+
+The Lead/Sidekick pair above. Either side can be a built-in DSH route, a subscription route, Antigravity or an ACP route.
+
+### Antigravity (the `agy` CLI, built in)
+
+Built in as of 1.0.0, ported from [`dsh-agy-worker`](https://github.com/SQDR2/dsh-agy-worker) 0.6.3 (MIT, see [docs/ATTRIBUTION-AGY.md](docs/ATTRIBUTION-AGY.md)): the `antigravity` route, the `/agy` command family, `agy_ask` / `agy_tool`, the `/plugins/agy-worker/*` surface, and the account pool with quota tracking. The console lives in the page's **Antigravity** section; `/agy status | pool | models | doctor` answers the same questions from the composer.
+
+With this route as the Sidekick, **three conditions must hold at once**; each fails silently on its own:
+
+| Condition | What it buys | Without it |
+|---|---|---|
+| `mcpBridge: true` | agy must be able to **execute** DSH tools | tools are listed but never run |
+| `permissionMode: 'skip'` | headless mode cannot prompt for the MCP permission | agy aborts: `a tool required the "mcp" permission that headless mode cannot prompt for` |
+| the allowlist admits `fusion_*` | the Sidekick must **report back** | it diagnoses but never submits |
+
+You do not write the `agy_tool` transport yourself: when the `antigravity` route is registered, this plugin unions it into both the Lead's and the Sidekick's tool surface (`src/host/route-transport.ts`).
+
+```yaml
+- id: dsh-agent-studio-fusion
+  config:
+    agy:
+      mcpBridge: true
+      permissionMode: skip
+      mcpConfigScope: global
+      mcpToolAllowlist: "fusion_submit_result,fusion_read_state,fusion_read_evidence,bash,read,write,edit,glob,grep,job_output,job_kill"
+```
+
+Every key from the old `dsh-agy-worker` (`enabled`, `agyBin`, `workspaceRoot`, `defaultModel`, `hiddenModels`, `quotaPollIntervalMs`, `autoWarmup`, …) works verbatim inside that `agy` block, and `DSH_AGY_*` environment variables still win. `enabled: false` is an **install-time** switch: it removes the `antigravity` route and every background capability (quota polling, warmup, the MCP bridge, the media sweep) while leaving `/agy` and the management routes mounted for inspection; re-enabling means changing the block and restarting DSH, not a live toggle.
+
+> On Windows use `pwsh` instead of `bash`, and follow any change to `workerTools`. Before enabling this, **first** disable or remove `dsh-agy-worker`: both use the same route prefix, the same `antigravity` provider, the same `/agy` command and the same tool-card keys, so running both fails at load (`duplicate exact route`, `DUPLICATE_ADAPTER`, `already registered`). Steps, the config move and the one manual account-pool copy: [docs/MIGRATION-AGY.md](docs/MIGRATION-AGY.md).
+
+### ACP routes (the built-in `deepseek-harness-acp` port)
+
+The Host implementation is merged here under the MIT license ([docs/ATTRIBUTION-ACP.md](docs/ATTRIBUTION-ACP.md)), so a separate `dsh-tauri-acp` install is **no longer needed**. The page's **ACP routes** section has a minimal example, the restart requirement and the migration steps; each key is the provider route shown in the model picker:
+
+```yaml
+- id: dsh-agent-studio-fusion
+  config:
+    acp:
+      agents:
+        codex:
+          displayName: Codex (ACP)
+          command: /absolute/path/to/codex-acp   # required; absolute is more reliable, PATH also works
+          args: []
+          models:                                 # may be omitted entirely; then discoverModels asks
+            - id: default
+          permission: ask
+```
+
+Routes are read once when the Host starts, so a change needs a restart. If you still have the standalone `dsh-tauri-acp`, **disable it manually first** and then move the same provider here — registering it twice fails at load ([docs/MIGRATION-ACP.md](docs/MIGRATION-ACP.md)).
+
+When an ACP route is the Sidekick, this plugin declares a Host-tool MCP bridge in that session's ACP `session/new` and nowhere else: this Host's own public origin plus the fixed `/api/fusion/acp-mcp` path, with 32 random bytes carried **only** in the `Authorization: Bearer` header (never in the URL). Requests are trusted against that origin — `Host` must match, a present `Origin` must equal it, a cross-site request is refused, the peer must be this machine — and no forwarding header is consulted. The token is bound to this task's Worker session, the current work order and its revision, the brief revision, the implement/explore mode, this route's provider *and* model, and the configured `workerTools`; every call re-checks all of it. It is revoked, with in-flight calls aborted, on pause, rework, recovery, completion, a pending approval, a budget block, a submitted report, runtime shutdown, a config change, a session replacement, abort or timeout. Only `workerTools` ∩ the Agent's own visible tools are exposed (an explore order additionally intersects the read-only tools, so the ceiling can only narrow), and every call dispatches through DSH's `tools.guard`, approvals and Fusion's path/lease checks. A Lead ACP session, an ordinary route call, model discovery and compaction requests, a text order, and any other Fusion task all open with an empty `mcpServers` list.
+
+### Other agent routes
+
+The `mcpBridge` / `permissionMode` / `agy_tool` trio above is **agy-only**, because that route is wired by this plugin's bridge layer. A different adapter (anything that is not this plugin's built-in ACP routes) may open its session with no MCP server at all, and **no Fusion setting can make it call Fusion's tools**. For text-only questions on such a route, Fusion accepts a strictly bounded text report instead (`fusionTextReport`, bound to the current `workOrderId` + `revision`, same fields as `fusion_submit_result`; prose, another order, another revision and extra fields are all refused, and the Lead still reviews it). Work that needs files or commands still requires real tool calls. See [docs/WORKER-TOOLS-UNREACHABLE.md](docs/WORKER-TOOLS-UNREACHABLE.md).
+
+## Cache keepalive
+
+While the Lead waits for the Sidekick, often for several minutes, the prompt cache can expire and the next request re-reads the whole conversation at full price. Keepalive resends the Lead's previous request at intervals with only `Reply OK` appended. The prefix is identical, so the provider serves it from cache and the cache lifetime is renewed; the model answers with 5 tokens, and the reply is discarded — it never enters the conversation and runs no tool call.
+
+- **Defaults** come from each provider's documentation, covering the vendors of the Artificial Analysis top 20, matched by model name (`gpt-*`, `claude-*`, `gemini-*`, `glm-*`, `grok-*`, `kimi-*`, `deepseek-*`, …). Plans billed per request — the [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login) routes — default to off, since every ping counts as a request.
+- **Auto start**: pings begin only after the model has actually reported cache hits, so a model without caching never pays for them.
+- Every model is adjustable in the Fusion panel: on/off, interval, reset to default. The panel also shows the observed effect — whether the cache survived the wait, how many pings were sent, how many tokens they read, and how many tokens were kept from being resent at full price.
+- **Measured** (ChatGPT subscription route, gpt-6-astra, ~20k-token context): the cache was still there after 10 idle minutes and gone after 15, and every ping restarts that clock, so this route defaults to one every 8 minutes.
+- **Automatic adjustment**: the interval shortens only when 3 of the last 5 pings at it missed (an occasional random eviction does not count). It never lengthens on its own; when a wider interval looks safe, the page suggests it and you decide.
+
+## Support
+
+| | |
+|---|---|
+| DSH | `>=0.2.1-rc.5 <0.3.0-0`, desktop app or Web; the 0.2.0 series is no longer supported |
+| Node | 24 or newer (`engines.node` is `>=24.0.0`) |
+| Models | Built-in DSH routes, the subscription routes of [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login) and dsh-antigravity-oauth, and the built-in Antigravity route; other third-party model plugins are untested |
+| macOS | Verified (Seatbelt sandbox) |
+| Windows | Native `pwsh` since `v0.2.1`, verified on Windows Server 2022 / PowerShell 7.6.6; Windows 10/11 unverified. ACL enforcement is partial: it restricts ordinary file writes, but not reads or networking |
+| Linux | Unverified |
+
+<details>
+<summary>Self-check on Linux</summary>
+
+1. In a test folder, select Fusion and say: "This is a read-only sandbox test; a refusal is expected. Call the bash tool yourself with `echo test > fusion-probe.txt` (don't delegate, don't rewrite it) and paste the tool's raw output."
+2. Expected: the output says the sandbox denied it (for example `Operation not permitted` / `read-only`), and no `fusion-probe.txt` appears. If the Lead only declines in words without calling the tool, the check doesn't count — ask it again to actually call the tool.
+3. If the file is created, the Lead's read-only limit does not work on your system: don't use Fusion there, and please report it.
+
+Where DSH has no sandbox at all, every Lead shell command is refused (it fails safe); the Lead still reads code with its file and search tools.
+
+</details>
+
+## Where the data lives
+
+- **Fusion's own records**: briefs, check results, usage, cache statistics and settings in `$DSH_HOME/plugins/dsh-agent-studio-fusion/state.sqlite` (`DSH_HOME` defaults to `~/.dsh`).
+- **Upgrading from an older name**: the `dsh-fusion`, `dsh-model-fusion` and `dsh-agent-studio` directories are **migrated** wholesale on first start, so existing tasks, usage and settings survive. Across filesystems it falls back to copying the database plus its `-wal`/`-shm`/`-journal`, removing only the files it copied.
+- **Built-in Antigravity**: work state stays where the standalone plugin kept it — runtime overrides, session bindings, media cache and warmup history in `$DSH_HOME/agy-worker/`. The account pool is this plugin's `$DSH_HOME/agy-accounts/pool.json`, with each isolated account HOME at `$DSH_HOME/agy-accounts/<id>/`; upstream read that pool from `DSH_STATE_DIR`, so only an installation that set it needs the one-time copy in [docs/MIGRATION-AGY.md](docs/MIGRATION-AGY.md). Nothing moves automatically and uninstalling this package deletes neither directory.
+- **The conversations themselves** are stored by DSH; Fusion uploads nothing else. To clear its records, quit DSH and delete that sqlite file — settings go with it.
+
+## Known limits
+
+- **Slower than the frontier model alone**: GPT-6 + Flash took about 5× the time of GPT-6 alone, mostly spent in the Sidekick. A faster Sidekick helps a lot.
+- **Lead takeover**: never triggered in 72 measured runs; only automated tests cover it.
+- **PATH in the macOS desktop app**: DSH Studio opened from the Dock gets only the system PATH, so `node`, `npm`, `cargo` and other tools installed by Homebrew (`/opt/homebrew/bin`), nvm and similar are not found by the shell. This is DSH's environment and affects every model. Before handing off work, Fusion checks the programs the acceptance commands use; when one is missing it tells the Lead where it is installed (for example `/opt/homebrew/bin/node`), and the Lead retries with the full path.
+- **Windows 10/11 and Linux unverified**: see the table above.
+
+## Development
+
+```sh
+corepack pnpm@9.15.9 install --frozen-lockfile
+node scripts/link-host.mjs /path/to/deepseek-harness-0.2.1-rc.5   # the supported baseline; link DSH sources while developing
+DSHX_HARNESS=/path/to/deepseek-harness-0.2.1-rc.5 pnpm build
+pnpm test && DSHX_HARNESS=/path/to/deepseek-harness-0.2.1-rc.5 pnpm test:host
+```
+
+On Windows, put PowerShell 7 (`pwsh`), Node and Python on the test process PATH. Native tests use `DSHX_HARNESS` to read the built, pinned Host checkout; no Host source changes are needed.
+
+`lib/` is a build artifact committed with the source (`lib/dsh-agent-studio-fusion.js`, `lib/client.js`, `lib/bridge.mjs`, `lib/assets/mermaid.min.js`, `lib/types/**`), so a change under `src/` needs `pnpm build` and the rebuilt `lib/` in the same commit. The plugin uses only DSH's public plugin APIs and never modifies DSH itself; adapting to a new DSH release is described in [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md). Cutting a release (bump the version, rebuild `lib/`, push a tag, let CI publish over OIDC): [RELEASING.md](RELEASING.md).
+
+## Doc index
+
+| Document | Contents |
+|---|---|
+| [INSTALL.md](INSTALL.md) | Install, uninstall, migrating from older packages |
+| [CHANGELOG.md](CHANGELOG.md) | What each release changed, validated, and did **not** validate |
+| [docs/EVIDENCE.md](docs/EVIDENCE.md) | Measurement method, raw data, excluded attempts |
+| [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | The DSH interfaces this depends on, and the upgrade procedure |
+| [docs/WORKER-TOOLS-UNREACHABLE.md](docs/WORKER-TOOLS-UNREACHABLE.md) | Diagnosing a Sidekick that cannot reach tools, and the text-report fallback |
+| [docs/MIGRATION-AGY.md](docs/MIGRATION-AGY.md) | Moving from `dsh-agy-worker` to the built-in Antigravity |
+| [docs/MIGRATION-ACP.md](docs/MIGRATION-ACP.md) | Moving from `dsh-tauri-acp` to the built-in ACP routes |
+| [docs/ATTRIBUTION-AGY.md](docs/ATTRIBUTION-AGY.md) · [docs/ATTRIBUTION-ACP.md](docs/ATTRIBUTION-ACP.md) | Origin, changes and license of the merged code |
+| [docs/DEVIN-LOCAL-FUSION.md](docs/DEVIN-LOCAL-FUSION.md) | Binary forensics of Devin CLI's Fusion, compared point by point with this project |
+| [RELEASING.md](RELEASING.md) | Release procedure |
+
+## License
+
+Apache-2.0. Forked from [`aa2246740/dsh-model-fusion`](https://github.com/aa2246740/dsh-model-fusion), also under Apache-2.0.
+
+Merged third-party work keeps its own license: the ACP provider port is MIT ([docs/ATTRIBUTION-ACP.md](docs/ATTRIBUTION-ACP.md)), and the built-in Antigravity (agy) capability is MIT, ported from [`SQDR2/dsh-agy-worker`](https://github.com/SQDR2/dsh-agy-worker) (itself a fork of [`amlyczz/dsh-agy-link`](https://github.com/amlyczz/dsh-agy-link)) — see [docs/ATTRIBUTION-AGY.md](docs/ATTRIBUTION-AGY.md), which also lists the licenses of the libraries bundled in `mermaid.min.js`.