@zoraxylia/dsh-codex-adapter 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +15 -0
- package/.claude-plugin/plugin.json +8 -0
- package/.mcp.json +8 -0
- package/LICENSE +21 -0
- package/README.de.md +480 -0
- package/README.es.md +480 -0
- package/README.fr.md +480 -0
- package/README.hi.md +480 -0
- package/README.id.md +480 -0
- package/README.ja.md +478 -0
- package/README.ko.md +480 -0
- package/README.md +483 -2
- package/README.pt.md +480 -0
- package/README.ru.md +480 -0
- package/README.th.md +480 -0
- package/README.tr.md +480 -0
- package/README.vi.md +480 -0
- package/README.zh-TW.md +478 -0
- package/README.zh.md +482 -0
- package/agents/ds-flash.md +17 -0
- package/agents/ds-pro.md +17 -0
- package/agy/agents/ds-flash.md +18 -0
- package/agy/agents/ds-pro.md +18 -0
- package/agy/skills/dsh-config/SKILL.md +6 -0
- package/agy/skills/dsh-playbook/SKILL.md +65 -0
- package/agy/skills/dsh-status/SKILL.md +6 -0
- package/codex/agents/ds-flash.toml +23 -0
- package/codex/agents/ds-pro.toml +23 -0
- package/codex/prompts/dsh-config.md +3 -0
- package/codex/prompts/dsh-playbook.md +60 -0
- package/codex/prompts/dsh-status.md +1 -0
- package/commands/config.md +9 -0
- package/commands/off.md +5 -0
- package/commands/on.md +5 -0
- package/commands/playbook.md +64 -0
- package/commands/status.md +5 -0
- package/cordis.patch.yml +4 -0
- package/docs/images/dsh-adapter-host.png +0 -0
- package/docs/images/dsh-adapter-jobs.png +0 -0
- package/docs/images/dsh-adapter-logo.png +0 -0
- package/docs/images/dsh-adapter-overview.png +0 -0
- package/grok/agents/ds-flash.md +19 -0
- package/grok/agents/ds-pro.md +19 -0
- package/grok/commands/dsh-config.md +9 -0
- package/grok/commands/dsh-playbook.md +66 -0
- package/grok/commands/dsh-status.md +5 -0
- package/lib/client.js +2694 -0
- package/lib/server.mjs +15417 -0
- package/package.json +138 -4
- package/scripts/build-client.mjs +23 -0
- package/scripts/build-mcp.mjs +43 -0
- package/scripts/bump-version.mjs +79 -0
- package/scripts/fake-agy.sh +23 -0
- package/scripts/release-local.mjs +87 -0
- package/scripts/smoke-bundle.mjs +166 -0
- package/scripts/smoke-cwd.mjs +41 -0
- package/scripts/smoke-pack.mjs +285 -0
- package/scripts/smoke.mjs +79 -0
- package/scripts/verify-cli-workers.mjs +133 -0
- package/scripts/verify-wpc10-client.mjs +237 -0
- package/scripts/verify-wpc14-proc-endpoints.mjs +356 -0
- package/scripts/verify-wpc9-guardrails.mjs +432 -0
- package/src/cli-workers.mjs +396 -0
- package/src/client/index.tsx +1135 -0
- package/src/client/jobs-view.ts +374 -0
- package/src/cwd-lock.mjs +91 -0
- package/src/hub/index.mjs +643 -0
- package/src/hub-client.mjs +72 -0
- package/src/i18n.mjs +19 -0
- package/src/install/cli.mjs +34 -0
- package/src/install/install.mjs +580 -0
- package/src/jobs.mjs +289 -0
- package/src/multimodal.mjs +744 -0
- package/src/origin-guard.mjs +133 -0
- package/src/paths.mjs +43 -0
- package/src/plugin-env.mjs +65 -0
- package/src/proc-kill.mjs +208 -0
- package/src/process-info.mjs +60 -0
- package/src/provider-probe.mjs +35 -0
- package/src/server.mjs +438 -0
- package/src/status-shard.mjs +95 -0
- package/src/tier-binding.mjs +63 -0
- package/src/vision-route.mjs +139 -0
- package/src/worker-profiles.mjs +95 -0
- package/src/worker-question.mjs +22 -0
- package/statusline/statusline.sh +14 -0
- package/statusline/worker-segment.sh +35 -0
- package/worker.cordis.yml +77 -0
package/README.md
CHANGED
|
@@ -1,3 +1,484 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="./docs/images/dsh-adapter-logo.png" alt="DSH Adapter" width="120" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">DSH Adapter</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<sub>Independent fork of <a href="https://github.com/ZSeven-W/dsh-crew">dsh-adapter</a> (MIT) — see <a href="./NOTICE">NOTICE</a>.</sub>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<strong>A <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> plugin: dispatch work to DSH agents from Claude Code / Codex / Antigravity / Grok, without giving up the host's native subagent UI.</strong><br />
|
|
13
|
+
<sub>Native Progress UI • Tier Policy & Escalation • Dispatch Guardrails • Jobs Board • In-Host DSH Sessions • Vision & Image Gen (Native-First) • One-Click Install</sub>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<sub>npm: <code>@zoraxylia/dsh-codex-adapter</code> · Current plugin release: <code>0.1.0-rc.11</code> · Tested with DSH <code>0.1.1-rc.1</code></sub>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="./README.md"><b>English</b></a> · <a href="./README.zh.md">简体中文</a> · <a href="./README.zh-TW.md">繁體中文</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.fr.md">Français</a> · <a href="./README.es.md">Español</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.pt.md">Português</a> · <a href="./README.ru.md">Русский</a> · <a href="./README.hi.md">हिन्दी</a> · <a href="./README.tr.md">Türkçe</a> · <a href="./README.th.md">ไทย</a> · <a href="./README.vi.md">Tiếng Việt</a> · <a href="./README.id.md">Bahasa Indonesia</a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<a href="https://github.com/ZSeven-W/dsh-crew/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ZSeven-W/dsh-crew?color=64748b" alt="License" /></a>
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
<br />
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
<img src="./docs/images/dsh-adapter-overview.png" alt="DSH Adapter — settings page" width="100%" />
|
|
32
|
+
</p>
|
|
33
|
+
<p align="center"><sub>The DSH Adapter settings page — host integrations, dispatch policy, execution and the multimodal bridge</sub></p>
|
|
34
|
+
|
|
35
|
+
## Why DSH Adapter
|
|
36
|
+
|
|
37
|
+
DSH Adapter is a plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) — an open-source agent harness. It makes DSH agents dispatchable from Claude Code, Codex, Antigravity and Grok: the orchestrator keeps its own model, the work runs on a real DSH agent with that harness's tools, sandbox, presets and session history, and the host still shows it as a native subagent with live progress.
|
|
38
|
+
|
|
39
|
+
What runs the work is a DSH agent, not a bare model call. Tiers (`flash` / `pro`) select how much capability that agent gets from the harness's configured roster — DeepSeek V4 Flash and V4 Pro today — so a change of model in DSH needs no change here.
|
|
40
|
+
|
|
41
|
+
<table>
|
|
42
|
+
<tr>
|
|
43
|
+
<td width="50%">
|
|
44
|
+
|
|
45
|
+
### 🧵 Native Progress UI
|
|
46
|
+
|
|
47
|
+
Workers appear as regular subagents in Claude Code / Codex / Antigravity / Grok — dispatch count, running step, tool calls and token usage all show up in the host's own task panel, plus a claude-hud statusline segment: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3`.
|
|
48
|
+
|
|
49
|
+
</td>
|
|
50
|
+
<td width="50%">
|
|
51
|
+
|
|
52
|
+
### 🎚️ Tier Policy and Escalation
|
|
53
|
+
|
|
54
|
+
`flash` for mechanical work, `pro` for reasoning, `effort` from `off` to `max`. `tier_policy` can clamp every dispatch to one tier at the tool layer, and `escalate_on_failure` retries a failed flash run once on pro — based on evidence, not on guessing difficulty up front.
|
|
55
|
+
|
|
56
|
+
</td>
|
|
57
|
+
</tr>
|
|
58
|
+
<tr>
|
|
59
|
+
<td width="50%">
|
|
60
|
+
|
|
61
|
+
### 🏛️ In-Host DSH Sessions
|
|
62
|
+
|
|
63
|
+
With the bundle installed in a DSH profile, each worker is a first-class DSH session: visible in the Web UI, grouped by working directory, mounted with the Agent preset you choose per tier. Without DSH running, dispatch falls back to a standalone DSH runtime, so CI and headless environments still work.
|
|
64
|
+
|
|
65
|
+
</td>
|
|
66
|
+
<td width="50%">
|
|
67
|
+
|
|
68
|
+
### 👁️ Vision and Image Generation
|
|
69
|
+
|
|
70
|
+
DSH's models are text-only. `describe_image` now prefers DeepSeek's own VL model (`deepseek-v4-flash-vision-exp`) whenever a key is available, then falls back to the CLIs you already have — Claude, Codex, Grok, Antigravity — or any OpenAI-compatible API you configure. `generate_image` borrows the same CLIs' brush. Pasted images stay visible in the conversation and reach the model as text.
|
|
71
|
+
|
|
72
|
+
</td>
|
|
73
|
+
</tr>
|
|
74
|
+
<tr>
|
|
75
|
+
<td width="50%">
|
|
76
|
+
|
|
77
|
+
### 🛡️ Dispatch Guardrails
|
|
78
|
+
|
|
79
|
+
Every dispatch is checked before anything spawns. Worker→worker nesting is capped at origin-chain depth 3 and cycles are refused; a second worker on a workspace another job already holds is refused with the holder's info — never silently queued. Refusals are readable errors: wait or re-scope, don't bypass.
|
|
80
|
+
|
|
81
|
+
</td>
|
|
82
|
+
<td width="50%">
|
|
83
|
+
|
|
84
|
+
### 📋 Jobs Board
|
|
85
|
+
|
|
86
|
+
The DSH Adapter panel doubles as a jobs board: every worker job — running or finished — is listed with tier, effort, live progress and tokens, held workspaces show their holders, and a job that vanishes mid-flight (e.g. a hub restart) is surfaced as an orphan ghost instead of disappearing silently.
|
|
87
|
+
|
|
88
|
+
</td>
|
|
89
|
+
</tr>
|
|
90
|
+
<tr>
|
|
91
|
+
<td width="50%">
|
|
92
|
+
|
|
93
|
+
### 🔌 Custom Providers
|
|
94
|
+
|
|
95
|
+
Bring your own endpoint (Base URL + API key + models) or a local command template. Each provider has a connectivity test that checks reachability and auth, then makes one real vision call so you find out now, not mid-task.
|
|
96
|
+
|
|
97
|
+
</td>
|
|
98
|
+
<td width="50%">
|
|
99
|
+
|
|
100
|
+
### 📦 One-Click Install
|
|
101
|
+
|
|
102
|
+
The settings page installs and updates the Claude Code plugin, the Codex role files and the Antigravity / Grok agents, skills and commands for you — marketplace registration, permission allowlist, HUD wiring, absolute paths rendered for this machine — and restores them just as easily. Every settings file is backed up first.
|
|
103
|
+
|
|
104
|
+
</td>
|
|
105
|
+
</tr>
|
|
106
|
+
</table>
|
|
107
|
+
|
|
108
|
+
## How it works
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
Claude Code / Codex / Antigravity / Grok (orchestrator, keeps its own model)
|
|
112
|
+
└─ ds-flash / ds-pro ← native subagent shell (progress shows in the host's task UI)
|
|
113
|
+
└─ MCP: dsh_run_worker(tier, effort, cwd, worker=)
|
|
114
|
+
├─ worker="agy"/"grok" → that external CLI runs the task (explicit opt-in)
|
|
115
|
+
├─ hub reachable → session inside DSH (visible in the Web UI, grouped by cwd)
|
|
116
|
+
└─ otherwise → dsh-jsonrpc-agent runtime (worker.cordis.yml)
|
|
117
|
+
└─ DeepSeek V4 Flash / Pro (DSH SDK, event stream → progress and token stats)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## One run, two views
|
|
121
|
+
|
|
122
|
+
Dispatch fans out. Below, eighteen workers translate this README in parallel: the host counts them as its own subagents, while the harness runs them as real sessions.
|
|
123
|
+
|
|
124
|
+
<p align="center">
|
|
125
|
+
<img src="./docs/images/dsh-adapter-host.png" alt="Claude Code" width="100%" />
|
|
126
|
+
</p>
|
|
127
|
+
<p align="center"><sub>Claude Code sees dsh-adapter workers as native subagents, with a statusline segment tracking running tiers, elapsed time and tokens.</sub></p>
|
|
128
|
+
|
|
129
|
+
<p align="center">
|
|
130
|
+
<img src="./docs/images/dsh-adapter-jobs.png" alt="DSH Adapter" width="100%" />
|
|
131
|
+
</p>
|
|
132
|
+
<p align="center"><sub>The DSH Adapter panel sees the same run from the harness side: which host dispatched each job, its tier and effort, live progress and token usage.</sub></p>
|
|
133
|
+
|
|
134
|
+
<p align="center"><sub>The panel is also the jobs board: running and finished jobs stay listed with tier, progress and tokens, held workspaces name their holders, and a job that vanishes mid-flight (a hub restart) surfaces as an orphan ghost instead of disappearing silently.</sub></p>
|
|
135
|
+
|
|
136
|
+
## Install
|
|
137
|
+
|
|
138
|
+
Install into a DSH profile from npm:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
dsh plugin --profile web add @zoraxylia/dsh-codex-adapter@latest
|
|
142
|
+
dsh web
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Or, for local development straight from the source tree:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
dsh plugin --profile web add link:/path/to/dsh-adapter
|
|
149
|
+
dsh web
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The `link:` protocol symlinks the profile dependency to this repository, so rebuilds are visible immediately.
|
|
153
|
+
|
|
154
|
+
### Configure DeepSeek credentials (standalone only)
|
|
155
|
+
|
|
156
|
+
In hub mode — the installation above — workers run inside the DSH instance and use the DeepSeek credentials it is already configured with. Nothing else to set up.
|
|
157
|
+
|
|
158
|
+
Only the standalone fallback needs a key of its own: dispatching from a host with no DSH instance running launches a worker runtime as a separate process. Obtain an API key from [platform.deepseek.com](https://platform.deepseek.com) and write it to `~/.config/dsh-adapter/.env`:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
DEEPSEEK_API_KEY=sk-...
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Verify
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
node scripts/smoke.mjs
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The smoke test dispatches one cheap job through whichever path is available — the hub when a DSH instance is running, standalone otherwise — and prints which one it used. Within about ten seconds you should see `smoke test passed — configuration OK`. On failure the reason is printed, scoped to the path that was tested.
|
|
171
|
+
|
|
172
|
+
Then open Settings → DSH Adapter and install the host integrations — Claude Code, Codex, Antigravity, Grok — with one click, or drive the same installer from the command line:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
node src/install/cli.mjs claude # Claude Code plugin: marketplace + permissions + HUD segment
|
|
176
|
+
node src/install/cli.mjs codex # Codex agents + prompts
|
|
177
|
+
node src/install/cli.mjs agy # Antigravity MCP config + agents + skills
|
|
178
|
+
node src/install/cli.mjs grok # Grok MCP config + agents + commands
|
|
179
|
+
node src/install/cli.mjs all # all four hosts at once
|
|
180
|
+
# uninstall symmetrically (uninstall-claude | uninstall-codex | uninstall-agy | uninstall-grok):
|
|
181
|
+
node src/install/cli.mjs uninstall-claude
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Background and terminology
|
|
185
|
+
|
|
186
|
+
- **DSH** (DeepSeek Harness): DeepSeek's open-source agent harness, a code agent in Web UI form, similar to Claude Code but driving DeepSeek models.
|
|
187
|
+
- **MCP** (Model Context Protocol): Anthropic's AI tool integration protocol, enables LLMs to safely call external tools and data sources.
|
|
188
|
+
- **Cordis bundle**: DSH's plugin format; this project can run standalone as an MCP service or install into DSH Web as hub mode.
|
|
189
|
+
- **tier**: capability tier — which slot of DSH's configured model roster a worker gets. `flash` is fast and cheap (simple tasks), `pro` reasons harder (complex problems). Today they map to DeepSeek V4 Flash and V4 Pro; swap models in DSH and nothing changes here.
|
|
190
|
+
- **worker**: the DSH agent doing the work — a full session with its own tools, sandbox and preset, not a bare model call.
|
|
191
|
+
- **effort**: reasoning strength, `off` = no reasoning, `high` = high reasoning investment, `max` = maximum reasoning investment.
|
|
192
|
+
|
|
193
|
+
## Claude Code
|
|
194
|
+
|
|
195
|
+
### Installation
|
|
196
|
+
|
|
197
|
+
One-click installation (choose one):
|
|
198
|
+
|
|
199
|
+
- **DSH settings page** (when hub mode is installed): Settings → DSH Adapter → "Install to Claude Code"
|
|
200
|
+
- **Command line**: `node src/install/cli.mjs all`
|
|
201
|
+
|
|
202
|
+
Both do the same thing: register local marketplace (the repo itself, via `.claude-plugin/marketplace.json`) + `claude plugin install` + MCP tool permission allowlist + claude-hud worker status segment config (auto-backup settings.json before changes, idempotent). **Restart the session after installation for changes to take effect.**
|
|
203
|
+
|
|
204
|
+
### Usage
|
|
205
|
+
|
|
206
|
+
- Directly in conversation, say "dispatch X to ds-flash" or "dispatch X to ds-pro", and subagent executes the task
|
|
207
|
+
- Dispatch count and real-time progress shown in Claude Code task UI
|
|
208
|
+
- **HUD status line segment**: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3` (current tier / elapsed time / token usage / completion count)
|
|
209
|
+
- For local development, `statusline/statusline.sh` or `statusline/worker-segment.sh` can be independently integrated
|
|
210
|
+
- **Long-running tasks**: CC has timeout limits on MCP calls (`MCP_TOOL_TIMEOUT` adjustable), long tasks can have orchestrator use `dsh_spawn_worker` + `dsh_worker_result(wait_seconds)` polling
|
|
211
|
+
- **Local development and debugging**: `claude --plugin-dir /path/to/dsh-adapter` to temporarily load
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
### Session commands
|
|
215
|
+
|
|
216
|
+
These override the global defaults for the current session only, and are enforced at the tool layer rather than by prompting:
|
|
217
|
+
|
|
218
|
+
| Command | What it does |
|
|
219
|
+
|---|---|
|
|
220
|
+
| `/dsh-adapter:config` | Show or set this session's defaults: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<seconds>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `origin_depth_limit=<1-32>`, `preset_flash/preset_pro=<preset id|default>`, `reset` |
|
|
221
|
+
|
|
222
|
+
| `/dsh-adapter:on` · `/dsh-adapter:off` | Turn dispatch for this session on or off (off is a hard switch: the tool refuses) |
|
|
223
|
+
| `/dsh-adapter:status` | Live status of worker jobs: tier, progress, tokens, current tool |
|
|
224
|
+
| `/dsh-adapter:playbook` | Dispatch best practices: choosing flash vs pro, self-contained briefs, parallelism, verifying results, guardrails |
|
|
225
|
+
|
|
226
|
+
## Codex
|
|
227
|
+
|
|
228
|
+
### Installation
|
|
229
|
+
|
|
230
|
+
Recommended to use the installer (auto-renders paths for this machine, copies the `/dsh-config`, `/dsh-status` and `/dsh-playbook` prompts):
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
node src/install/cli.mjs codex
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Or manually copy (requires manual path modification after copying):
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
cp codex/agents/*.toml ~/.codex/agents/ # global or project-level .codex/agents/
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Role files come pre-configured with:
|
|
243
|
+
|
|
244
|
+
- MCP server mounting configuration
|
|
245
|
+
- `default_tools_approval_mode = "approve"` (**required**, otherwise tool calls are auto-cancelled in exec mode)
|
|
246
|
+
- `tool_timeout_sec = 3600`
|
|
247
|
+
|
|
248
|
+
**Note**: When manually copying, absolute paths in the `args` field must be updated to match actual installation location; the installer handles this automatically.
|
|
249
|
+
|
|
250
|
+
### Usage
|
|
251
|
+
|
|
252
|
+
- In interactive TUI, select "spawn ds-pro to ..." to dispatch tasks; Active/Done panels show progress
|
|
253
|
+
- `codex exec` mode can also directly call `dsh_run_worker`
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
### Session commands
|
|
257
|
+
|
|
258
|
+
Three prompts are installed for Codex:
|
|
259
|
+
|
|
260
|
+
| Command | What it does |
|
|
261
|
+
|---|---|
|
|
262
|
+
| `/dsh-config` | Show or set this session's defaults: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<seconds>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `origin_depth_limit=<1-32>`, `preset_flash/preset_pro=<preset id|default>`, `reset` |
|
|
263
|
+
|
|
264
|
+
| `/dsh-status` | Live status of worker jobs: tier, progress, tokens, current tool |
|
|
265
|
+
| `/dsh-playbook` | Dispatch best practices: choosing flash vs pro, self-contained briefs, parallelism, verifying results, guardrails |
|
|
266
|
+
|
|
267
|
+
## Antigravity (agy)
|
|
268
|
+
|
|
269
|
+
### Installation
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
node src/install/cli.mjs agy
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Registers the dsh-adapter MCP server in `~/.gemini/config/mcp_config.json` and installs the `ds-flash` / `ds-pro` agents plus the `dsh-config`, `dsh-status` and `dsh-playbook` skills into `~/.gemini/config/` (all files backed up first). Restart the session after installation.
|
|
276
|
+
|
|
277
|
+
### Usage
|
|
278
|
+
|
|
279
|
+
- Pick `ds-flash` or `ds-pro` as the agent to dispatch tasks
|
|
280
|
+
- `dsh_worker_config` reads or overrides the session defaults
|
|
281
|
+
|
|
282
|
+
### Session skills
|
|
283
|
+
|
|
284
|
+
| Skill | What it does |
|
|
285
|
+
|---|---|
|
|
286
|
+
| `/dsh-config` | Show or set this session's defaults (tier / effort / mode / timeout / policy / escalation / reset) |
|
|
287
|
+
| `/dsh-status` | Live status of worker jobs: tier, progress, tokens, current tool |
|
|
288
|
+
| `/dsh-playbook` | Dispatch best practices: choosing flash vs pro, self-contained briefs, parallelism, verifying results, guardrails |
|
|
289
|
+
|
|
290
|
+
### Caveats
|
|
291
|
+
|
|
292
|
+
- agy runs workers with **full approval** (`--dangerously-skip-permissions` + accept-edits): agy 1.1.16 has no workspace-scoped permission mode, so a headless worker must auto-approve tool requests.
|
|
293
|
+
|
|
294
|
+
Uninstall: `node src/install/cli.mjs uninstall-agy`
|
|
295
|
+
|
|
296
|
+
## Grok
|
|
297
|
+
|
|
298
|
+
### Installation
|
|
299
|
+
|
|
300
|
+
```bash
|
|
301
|
+
node src/install/cli.mjs grok
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
Writes the `[mcp_servers.dsh-adapter]` section into `~/.grok/config.toml` and installs the `ds-flash` / `ds-pro` agents plus the `/dsh-config`, `/dsh-status` and `/dsh-playbook` commands into `~/.grok/` (all files backed up first).
|
|
305
|
+
|
|
306
|
+
### Usage
|
|
307
|
+
|
|
308
|
+
- Pick `ds-flash` or `ds-pro` as the agent to dispatch tasks
|
|
309
|
+
|
|
310
|
+
### Session commands
|
|
311
|
+
|
|
312
|
+
| Command | What it does |
|
|
313
|
+
|---|---|
|
|
314
|
+
| `/dsh-config` | Show or set this session's defaults (tier / effort / mode / timeout / policy / escalation / reset) |
|
|
315
|
+
| `/dsh-status` | Live status of worker jobs: tier, progress, tokens, current tool |
|
|
316
|
+
| `/dsh-playbook` | Dispatch best practices: choosing flash vs pro, self-contained briefs, parallelism, verifying results, guardrails |
|
|
317
|
+
|
|
318
|
+
### Caveats
|
|
319
|
+
|
|
320
|
+
- By security design, grok does not start repo-level MCP servers in untrusted project directories (`grok mcp doctor` reports "folder untrusted"); a global install is unaffected — change directory or pass `--trust`.
|
|
321
|
+
- grok workers run with `bypassPermissions` (always-approve, as the grok docs recommend for headless automation); deny rules and hooks still apply.
|
|
322
|
+
|
|
323
|
+
Uninstall: `node src/install/cli.mjs uninstall-grok`
|
|
324
|
+
|
|
325
|
+
## MCP tools
|
|
326
|
+
|
|
327
|
+
| Tool | Description |
|
|
328
|
+
|---|---|
|
|
329
|
+
| `dsh_run_worker` | Blocking task dispatch (`tier`: flash/pro, `effort`: off/high/max, `cwd`, `worker`), waits for result |
|
|
330
|
+
| `dsh_spawn_worker` | Async dispatch, returns job id (for parallel fan-out); collect results with `dsh_worker_result` |
|
|
331
|
+
| `dsh_worker_status` | Real-time progress of all jobs (turn/step/current tool/token) + cwd advisory locks |
|
|
332
|
+
| `dsh_worker_result` | Fetch result, can specify `wait_seconds` to wait |
|
|
333
|
+
| `dsh_worker_cancel` | Cancel specified job, terminate its runtime process |
|
|
334
|
+
| `dsh_worker_config` | Read/set session defaults (tier, effort, mode, timeout, policy, escalation) and list `worker_profiles` |
|
|
335
|
+
|
|
336
|
+
Progress is simultaneously mirrored to `~/.config/dsh-adapter/status.d/` (one shard file per writer, can be read by statusline / external monitoring).
|
|
337
|
+
|
|
338
|
+
## Dispatch guardrails
|
|
339
|
+
|
|
340
|
+
Every dispatch is checked before anything spawns — refusals are readable errors, never silent queues:
|
|
341
|
+
|
|
342
|
+
- **Origin chain**: each dispatch appends a hop to the worker→worker origin chain. Nesting deeper than the cap (`origin_depth_limit`, default 3) is refused, and so is any cycle (the same backend + cwd appearing twice) — the guard that stops recursive worker self-amplification.
|
|
343
|
+
- **cwd advisory lock**: one running worker per workspace. A second dispatch into a held workspace is refused with the holder's job id, backend and start time — wait for it to settle, cancel it with `dsh_worker_cancel`, or pass `allow_concurrent_cwd: true` (read-only tasks only).
|
|
344
|
+
|
|
345
|
+
## Dispatch playbook
|
|
346
|
+
|
|
347
|
+
How to dispatch *well* — flash vs pro, self-contained briefs, safe parallelism, verifying results, and the guardrails above — is bundled as a per-host playbook: `/dsh-adapter:playbook` (Claude Code skill), `/dsh-playbook` (Codex prompt, Antigravity skill, Grok command).
|
|
348
|
+
|
|
349
|
+
## Explicit CLI backends
|
|
350
|
+
|
|
351
|
+
`worker="agy"` / `worker="grok"` pins a dispatch to that external CLI (backend × model × effort) instead of the DSH tier logic. It is explicit opt-in — there is no default, so set it only when the user asks for that CLI. Caveats: grok refuses to start repo-local MCP servers in untrusted folders, and agy runs workers with full approval (no workspace-scoped permission mode).
|
|
352
|
+
|
|
353
|
+
## Multimodal: vision and image generation
|
|
354
|
+
|
|
355
|
+
**DeepSeek is a text-only model** and does not support image input or generation. This plugin sources these capabilities externally through MCP tools:
|
|
356
|
+
|
|
357
|
+
**Native vision first**: when the vision provider is a built-in CLI (or explicitly `native`), `describe_image` first tries DeepSeek's own VL model `deepseek-v4-flash-vision-exp` (direct API call; key from `DEEPSEEK_API_KEY` or `~/.config/dsh-adapter/.env`). Any failure degrades gracefully to the CLI provider chain below, which is kept as the fallback. Image generation is untouched — the native model only ever looks at pictures.
|
|
358
|
+
|
|
359
|
+
| Tool | Description |
|
|
360
|
+
|---|---|
|
|
361
|
+
| `describe_image` | Answer questions by viewing images (screenshots, designs, charts, etc.), results cached by provider + model + image + question |
|
|
362
|
+
| `generate_image` | Generate image from text description, save to specified absolute path; output is flat bitmap (requires OpenPencil for layer editing) |
|
|
363
|
+
|
|
364
|
+
**Session image pasting**: In DSH, switch model to `DeepSeek (vision) ◉` to directly paste images. Images remain in session and display normally; the plugin appends transcribed text after them and strips images before sending—you see the image, the model reads the text. The transcription follows the same native-first ladder: DeepSeek's VL model when a key is available, then your configured CLI provider.
|
|
365
|
+
|
|
366
|
+
### Configuration
|
|
367
|
+
|
|
368
|
+
In **DSH settings page → DSH Adapter → Multimodal** (or directly edit `~/.config/dsh-adapter/config.json`):
|
|
369
|
+
|
|
370
|
+
**Vision provider** (image viewing):
|
|
371
|
+
|
|
372
|
+
- `native` / `deepseek-native` (DeepSeek's own VL model — tried first automatically for every built-in provider whenever a key is available)
|
|
373
|
+
- `claude-code` (default, uses haiku, inexpensive)
|
|
374
|
+
- `codex` (uses GPT, can specify specific model)
|
|
375
|
+
- `grok` (uses Grok)
|
|
376
|
+
- `agy` (Antigravity)
|
|
377
|
+
- `custom` (OpenAI-compatible API or local command)
|
|
378
|
+
- `off` (disabled)
|
|
379
|
+
|
|
380
|
+
**Image generation provider** (image generation):
|
|
381
|
+
|
|
382
|
+
- `codex` (`$imagegen`, gpt-image-2)
|
|
383
|
+
- `agy` (Nano Banana)
|
|
384
|
+
- `grok` (Imagine)
|
|
385
|
+
- `custom` (OpenAI-compatible API or local command)
|
|
386
|
+
- `off` (disabled)
|
|
387
|
+
|
|
388
|
+
### Custom provider
|
|
389
|
+
|
|
390
|
+
Two integration methods:
|
|
391
|
+
|
|
392
|
+
**API**: Any OpenAI-compatible endpoint
|
|
393
|
+
- Fill Base URL, API Key, model list
|
|
394
|
+
- Vision uses `/chat/completions` with inline base64 images
|
|
395
|
+
- Image generation uses `/images/generations`
|
|
396
|
+
- **Must specify "image generation model" to have generation capability**, otherwise provider only appears in vision selection
|
|
397
|
+
|
|
398
|
+
**CLI**: Local command template, placeholders substituted with safe references
|
|
399
|
+
- Vision: `{image} {question} {model}` → stdout as answer
|
|
400
|
+
- Image generation: `{prompt} {output} {size}` → command must write file to `{output}`
|
|
401
|
+
- Fill at least one command; whichever is filled determines capability
|
|
402
|
+
|
|
403
|
+
**Connectivity test**: Each custom provider has a test button
|
|
404
|
+
- API: Check endpoint reachability, auth, send real vision request to verify
|
|
405
|
+
- CLI: Check executable file, run real command to verify
|
|
406
|
+
- Image generation: Validate config only, no actual image output
|
|
407
|
+
|
|
408
|
+
**Borrowed subscription CLIs** (claude / codex / grok / agy) require you to be logged in locally; the plugin won't bypass their permissions for you.
|
|
409
|
+
|
|
410
|
+
## Hub mode
|
|
411
|
+
|
|
412
|
+
This package is also a valid DSH bundle (`dsh.bundle` + `cordis.patch.yml`). After installing into DSH Web profile with `dsh plugin add dsh-adapter`:
|
|
413
|
+
|
|
414
|
+
- **Worker sessions become first-class citizens**: run as first-class sessions in DSH host (`agents.create` + per-session model/effort waterfall + default preset), appear in Web UI session list, can be opened anytime to view complete execution
|
|
415
|
+
- **Organize by working directory**: manage worker sessions by cwd in Web UI
|
|
416
|
+
- **Loopback API**:
|
|
417
|
+
- `POST/GET /_dsh/dsh-adapter/jobs`: spawn tasks, list, long-poll results, cancel
|
|
418
|
+
- `GET /_dsh/dsh-adapter/ping`: health check (MCP shim uses this to detect if hub is running)
|
|
419
|
+
- `POST /_dsh/dsh-adapter/install`: one-click install of the host integrations — Claude Code / Codex / Antigravity / Grok (backend of `src/install/`)
|
|
420
|
+
- **Auto-detection**: the hosts' MCP shim auto-detects hub (`DSHPLUGIN_ADAPTER_HUB` env var, default `http://127.0.0.1:3080`)
|
|
421
|
+
- DSH Web running → jobs enter hub mode (`mode: "hub"`)
|
|
422
|
+
- Not running → fall back to standalone runtime
|
|
423
|
+
|
|
424
|
+
**Windows process inspection:** dispatch-source detection and verified single-process termination use PowerShell/CIM. The ghost-process endpoint refuses process-group termination with `unsupported-platform`; it sends no signal.
|
|
425
|
+
|
|
426
|
+
## Solution selection and limitations
|
|
427
|
+
|
|
428
|
+
### Regular subscribers → shell subagent approach (recommended)
|
|
429
|
+
|
|
430
|
+
- **Current state**: Claude Code subagent shell uses haiku as intermediary; each dispatch adds hundreds to thousands of tokens
|
|
431
|
+
- **Trade-off**: Use small amount of Anthropic token in exchange for native task UI, real-time progress display, no extra configuration
|
|
432
|
+
- **Recommendation**: If you already subscribe to Claude Pro or use Claude Code, use this approach—convenient and transparent
|
|
433
|
+
|
|
434
|
+
### Pay-as-you-go / CI environments → direct router approach
|
|
435
|
+
|
|
436
|
+
- **Current state**: Claude Code subagent frontmatter doesn't support direct third-party model connection; this repo's router experiment in scratchpad requires API-key credentials for Claude Code, but subscription OAuth is blocked upstream by Anthropic with 403
|
|
437
|
+
- **Recommendation**:
|
|
438
|
+
- If using API-key credentials (not OAuth) and want to save Anthropic tokens, can run local router for direct DeepSeek connection
|
|
439
|
+
- CI environments typically also use API keys; this approach is more economical (all DeepSeek tokens)
|
|
440
|
+
- Requires self-testing of router integration (not officially supported)
|
|
441
|
+
|
|
442
|
+
### Running DSH Web → hub mode auto-enabled
|
|
443
|
+
|
|
444
|
+
- **Current state**: If `dsh plugin add dsh-adapter` installed into DSH Web profile, jobs run as first-class sessions in host, appear in Web UI session list
|
|
445
|
+
- **Recommendation**: During local development iteration, recommend enabling hub mode; worker progress can be fully observed in Web UI; for cross-machine collaboration or environments without Web UI, use the dispatching-host shell approach
|
|
446
|
+
|
|
447
|
+
### Known items
|
|
448
|
+
|
|
449
|
+
- Codex role can theoretically try `model_provider` pointing directly to DeepSeek (unverified); this bridge doesn't depend on it
|
|
450
|
+
- Image generation output is flat bitmap; layer editing requires OpenPencil
|
|
451
|
+
- **Runtime dependencies**: Only `@modelcontextprotocol/sdk` and `zod`; `@deepseek-ai/*` are host runtime, provided by the DSH host (a plain npm install never pulls them)
|
|
452
|
+
- **Codex must configure**: `default_tools_approval_mode = "approve"`, otherwise tool calls are auto-cancelled
|
|
453
|
+
|
|
454
|
+
## Develop
|
|
455
|
+
|
|
456
|
+
```bash
|
|
457
|
+
pnpm install
|
|
458
|
+
node_modules/.bin/tsdown src/client/index.tsx --format cjs --platform browser \
|
|
459
|
+
--target es2022 --tsconfig tsconfig.client.json --out-dir .client-build --clean
|
|
460
|
+
node scripts/build-client.mjs # wraps the bundle for the DSH module loader
|
|
461
|
+
node scripts/smoke.mjs # dispatches one real flash task end to end
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
Runtime dependencies are only `@modelcontextprotocol/sdk` and `zod`; every `@deepseek-ai/*` package is host runtime provided by the DSH host (documented in the package's dshHostRuntime field, not in peerDependencies, so a plain npm install never pulls them), which keeps the plugin inside the host's single module realm.
|
|
465
|
+
|
|
466
|
+
## Ecosystem
|
|
467
|
+
|
|
468
|
+
- [DSH Android](https://github.com/ZSeven-W/dsh-android) — a live Android emulator or USB device inside the conversation, driven entirely through adb
|
|
469
|
+
- [DSH iOS](https://github.com/ZSeven-W/dsh-ios) — a live iOS Simulator and a USB-connected iPhone, inside the conversation
|
|
470
|
+
- [DSH Noema](https://github.com/ZSeven-W/dsh-noema) — long-term memory for DSH
|
|
471
|
+
- [DSH OpenPencil](https://github.com/ZSeven-W/dsh-openpencil) — inspect and edit `.op` design documents inside a conversation
|
|
472
|
+
|
|
473
|
+
## License
|
|
474
|
+
|
|
475
|
+
MIT
|
|
476
|
+
|
|
477
|
+
|
|
478
|
+
### `dsh_worker_probe` / `needs_input`
|
|
479
|
+
|
|
480
|
+
`dsh_worker_probe` sends one bounded no-op tool-call request to a DSH-configured route, without starting a worker or changing bindings. It may use model tokens. An unanswered worker question stops the runtime with `needs_input`; obtain the required user answer and redispatch. Host permissions are inherited; no additional OS sandbox is claimed.
|
|
481
|
+
|
|
482
|
+
```js
|
|
483
|
+
dsh_worker_probe({ tier: "flash" })
|
|
484
|
+
```
|