@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.
Files changed (88) hide show
  1. package/.claude-plugin/marketplace.json +15 -0
  2. package/.claude-plugin/plugin.json +8 -0
  3. package/.mcp.json +8 -0
  4. package/LICENSE +21 -0
  5. package/README.de.md +480 -0
  6. package/README.es.md +480 -0
  7. package/README.fr.md +480 -0
  8. package/README.hi.md +480 -0
  9. package/README.id.md +480 -0
  10. package/README.ja.md +478 -0
  11. package/README.ko.md +480 -0
  12. package/README.md +483 -2
  13. package/README.pt.md +480 -0
  14. package/README.ru.md +480 -0
  15. package/README.th.md +480 -0
  16. package/README.tr.md +480 -0
  17. package/README.vi.md +480 -0
  18. package/README.zh-TW.md +478 -0
  19. package/README.zh.md +482 -0
  20. package/agents/ds-flash.md +17 -0
  21. package/agents/ds-pro.md +17 -0
  22. package/agy/agents/ds-flash.md +18 -0
  23. package/agy/agents/ds-pro.md +18 -0
  24. package/agy/skills/dsh-config/SKILL.md +6 -0
  25. package/agy/skills/dsh-playbook/SKILL.md +65 -0
  26. package/agy/skills/dsh-status/SKILL.md +6 -0
  27. package/codex/agents/ds-flash.toml +23 -0
  28. package/codex/agents/ds-pro.toml +23 -0
  29. package/codex/prompts/dsh-config.md +3 -0
  30. package/codex/prompts/dsh-playbook.md +60 -0
  31. package/codex/prompts/dsh-status.md +1 -0
  32. package/commands/config.md +9 -0
  33. package/commands/off.md +5 -0
  34. package/commands/on.md +5 -0
  35. package/commands/playbook.md +64 -0
  36. package/commands/status.md +5 -0
  37. package/cordis.patch.yml +4 -0
  38. package/docs/images/dsh-adapter-host.png +0 -0
  39. package/docs/images/dsh-adapter-jobs.png +0 -0
  40. package/docs/images/dsh-adapter-logo.png +0 -0
  41. package/docs/images/dsh-adapter-overview.png +0 -0
  42. package/grok/agents/ds-flash.md +19 -0
  43. package/grok/agents/ds-pro.md +19 -0
  44. package/grok/commands/dsh-config.md +9 -0
  45. package/grok/commands/dsh-playbook.md +66 -0
  46. package/grok/commands/dsh-status.md +5 -0
  47. package/lib/client.js +2694 -0
  48. package/lib/server.mjs +15417 -0
  49. package/package.json +138 -4
  50. package/scripts/build-client.mjs +23 -0
  51. package/scripts/build-mcp.mjs +43 -0
  52. package/scripts/bump-version.mjs +79 -0
  53. package/scripts/fake-agy.sh +23 -0
  54. package/scripts/release-local.mjs +87 -0
  55. package/scripts/smoke-bundle.mjs +166 -0
  56. package/scripts/smoke-cwd.mjs +41 -0
  57. package/scripts/smoke-pack.mjs +285 -0
  58. package/scripts/smoke.mjs +79 -0
  59. package/scripts/verify-cli-workers.mjs +133 -0
  60. package/scripts/verify-wpc10-client.mjs +237 -0
  61. package/scripts/verify-wpc14-proc-endpoints.mjs +356 -0
  62. package/scripts/verify-wpc9-guardrails.mjs +432 -0
  63. package/src/cli-workers.mjs +396 -0
  64. package/src/client/index.tsx +1135 -0
  65. package/src/client/jobs-view.ts +374 -0
  66. package/src/cwd-lock.mjs +91 -0
  67. package/src/hub/index.mjs +643 -0
  68. package/src/hub-client.mjs +72 -0
  69. package/src/i18n.mjs +19 -0
  70. package/src/install/cli.mjs +34 -0
  71. package/src/install/install.mjs +580 -0
  72. package/src/jobs.mjs +289 -0
  73. package/src/multimodal.mjs +744 -0
  74. package/src/origin-guard.mjs +133 -0
  75. package/src/paths.mjs +43 -0
  76. package/src/plugin-env.mjs +65 -0
  77. package/src/proc-kill.mjs +208 -0
  78. package/src/process-info.mjs +60 -0
  79. package/src/provider-probe.mjs +35 -0
  80. package/src/server.mjs +438 -0
  81. package/src/status-shard.mjs +95 -0
  82. package/src/tier-binding.mjs +63 -0
  83. package/src/vision-route.mjs +139 -0
  84. package/src/worker-profiles.mjs +95 -0
  85. package/src/worker-question.mjs +22 -0
  86. package/statusline/statusline.sh +14 -0
  87. package/statusline/worker-segment.sh +35 -0
  88. package/worker.cordis.yml +77 -0
package/README.id.md ADDED
@@ -0,0 +1,480 @@
1
+ <p align="center">
2
+ <img src="./docs/images/dsh-adapter-logo.png" alt="DSH Adapter" width="120" />
3
+ </p>
4
+
5
+ <h1 align="center">DSH Adapter</h1>
6
+
7
+ <p align="center">
8
+ <strong>Plugin <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>: dispatch pekerjaan ke agen DSH dari Claude Code / Codex / Antigravity / Grok, tanpa kehilangan UI subagent bawaan host.</strong><br />
9
+ <sub>UI Progres Bawaan &bull; Kebijakan Tier &amp; Eskalasi &bull; Pagar Pembatas Dispatch &bull; Papan Job &bull; Sesi DSH di Dalam Host &bull; Vision &amp; Gen Gambar (Native-First) &bull; Instalasi Sekali Klik</sub>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <sub>npm: <code>@zoraxylia/dsh-codex-adapter</code> &middot; Rilis plugin saat ini: <code>0.1.0-rc.11</code> &middot; Diuji dengan DSH <code>0.1.1-rc.1</code></sub>
14
+ </p>
15
+
16
+ <p align="center">
17
+ <a href="./README.md">English</a> &middot; <a href="./README.zh.md">简体中文</a> &middot; <a href="./README.zh-TW.md">繁體中文</a> &middot; <a href="./README.ja.md">日本語</a> &middot; <a href="./README.ko.md">한국어</a> &middot; <a href="./README.fr.md">Français</a> &middot; <a href="./README.es.md">Español</a> &middot; <a href="./README.de.md">Deutsch</a> &middot; <a href="./README.pt.md">Português</a> &middot; <a href="./README.ru.md">Русский</a> &middot; <a href="./README.hi.md">हिन्दी</a> &middot; <a href="./README.tr.md">Türkçe</a> &middot; <a href="./README.th.md">ไทย</a> &middot; <a href="./README.vi.md">Tiếng Việt</a> &middot; <a href="./README.id.md"><b>Bahasa Indonesia</b></a>
18
+ </p>
19
+
20
+ <p align="center">
21
+ <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>
22
+ </p>
23
+
24
+ <br />
25
+
26
+ <p align="center">
27
+ <img src="./docs/images/dsh-adapter-overview.png" alt="DSH Adapter — settings page" width="100%" />
28
+ </p>
29
+ <p align="center"><sub>Halaman pengaturan DSH Adapter — integrasi host, kebijakan dispatch, eksekusi, dan jembatan multimodal</sub></p>
30
+
31
+ ## Mengapa DSH Adapter
32
+
33
+ DSH Adapter adalah plugin untuk [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) — harness agen sumber terbuka. Plugin ini membuat agen DSH dapat di-dispatch dari Claude Code, Codex, Antigravity dan Grok: orchestrator tetap memakai modelnya sendiri, pekerjaan berjalan pada agen DSH sungguhan dengan tools, sandbox, preset, dan riwayat sesi milik harness tersebut, dan host tetap menampilkannya sebagai subagent bawaan dengan progres langsung.
34
+
35
+ Yang menjalankan pekerjaan adalah agen DSH, bukan panggilan model biasa. Tier (`flash` / `pro`) menentukan seberapa besar kapabilitas yang didapat agen tersebut dari roster yang dikonfigurasi di harness — saat ini DeepSeek V4 Flash dan V4 Pro — sehingga pergantian model di DSH tidak memerlukan perubahan apa pun di sini.
36
+
37
+ <table>
38
+ <tr>
39
+ <td width="50%">
40
+
41
+ ### 🧵 UI Progres Bawaan
42
+
43
+ Worker tampil sebagai subagent biasa di Claude Code / Codex / Antigravity / Grok — jumlah dispatch, langkah yang sedang berjalan, panggilan tool, dan penggunaan token semuanya tampil di panel tugas milik host, plus segmen statusline claude-hud: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3`.
44
+
45
+ </td>
46
+ <td width="50%">
47
+
48
+ ### 🎚️ Kebijakan Tier dan Eskalasi
49
+
50
+ `flash` untuk pekerjaan mekanis, `pro` untuk penalaran, `effort` dari `off` sampai `max`. `tier_policy` dapat membatasi setiap dispatch ke satu tier di lapisan tool, dan `escalate_on_failure` mencoba ulang sekali run flash yang gagal di pro — berdasarkan bukti, bukan menebak tingkat kesulitan di awal.
51
+
52
+ </td>
53
+ </tr>
54
+ <tr>
55
+ <td width="50%">
56
+
57
+ ### 🏛️ Sesi DSH di Dalam Host
58
+
59
+ Dengan bundle terpasang di profil DSH, setiap worker adalah sesi DSH kelas satu: terlihat di Web UI, dikelompokkan menurut direktori kerja, dipasangi preset Agent yang Anda pilih per tier. Tanpa DSH berjalan, dispatch melakukan fallback ke runtime DSH standalone, sehingga lingkungan CI dan headless tetap berfungsi.
60
+
61
+ </td>
62
+ <td width="50%">
63
+
64
+ ### 👁️ Vision dan Pembuatan Gambar
65
+
66
+ Model DSH hanya mendukung teks. `describe_image` kini mengutamakan model VL milik DeepSeek sendiri (`deepseek-v4-flash-vision-exp`) kapan pun key tersedia, lalu fallback ke CLI yang sudah Anda miliki — Claude, Codex, Grok, Antigravity — atau API apa pun yang kompatibel dengan OpenAI yang Anda konfigurasi. `generate_image` meminjam kuas dari CLI yang sama. Gambar yang ditempel tetap terlihat di percakapan dan sampai ke model sebagai teks.
67
+
68
+ </td>
69
+ </tr>
70
+ <tr>
71
+ <td width="50%">
72
+
73
+ ### 🛡️ Pagar Pembatas Dispatch
74
+
75
+ Setiap dispatch diperiksa sebelum apa pun dijalankan. Nesting worker→worker dibatasi pada kedalaman rantai origin 3 dan siklus ditolak; worker kedua pada workspace yang sudah dipegang job lain ditolak dengan info pemegangnya — tidak pernah antre diam-diam. Penolakan adalah error yang terbaca: tunggu atau ubah cakupan, jangan lewati.
76
+
77
+ </td>
78
+ <td width="50%">
79
+
80
+ ### 📋 Papan Job
81
+
82
+ Panel DSH Adapter berfungsi ganda sebagai papan job: setiap job worker — berjalan maupun selesai — tercantum dengan tier, effort, progres langsung, dan token, workspace yang dipegang menampilkan pemegangnya, dan job yang hilang di tengah jalan (mis. restart hub) dimunculkan sebagai orphan ghost alih-alih menghilang diam-diam.
83
+
84
+ </td>
85
+ </tr>
86
+ <tr>
87
+ <td width="50%">
88
+
89
+ ### 🔌 Provider Kustom
90
+
91
+ Bawa endpoint Anda sendiri (Base URL + API key + model) atau template perintah lokal. Setiap provider punya uji konektivitas yang memeriksa keterjangkauan dan autentikasi, lalu melakukan satu panggilan vision sungguhan sehingga Anda langsung tahu sekarang, bukan di tengah tugas.
92
+
93
+ </td>
94
+ <td width="50%">
95
+
96
+ ### 📦 Instalasi Sekali Klik
97
+
98
+ Halaman pengaturan memasang dan memperbarui plugin Claude Code, file role Codex, dan agen, skill, serta perintah Antigravity / Grok untuk Anda — registrasi marketplace, daftar izin (allowlist), pemasangan HUD, path absolut yang dirender untuk mesin ini — dan memulihkannya semudah itu. Setiap file pengaturan dicadangkan terlebih dahulu.
99
+
100
+ </td>
101
+ </tr>
102
+ </table>
103
+
104
+ ## Cara Kerja
105
+
106
+ ```
107
+ Claude Code / Codex / Antigravity / Grok (orchestrator, keeps its own model)
108
+ └─ ds-flash / ds-pro ← native subagent shell (progress shows in the host's task UI)
109
+ └─ MCP: dsh_run_worker(tier, effort, cwd, worker=)
110
+ ├─ worker="agy"/"grok" → that external CLI runs the task (explicit opt-in)
111
+ ├─ hub reachable → session inside DSH (visible in the Web UI, grouped by cwd)
112
+ └─ otherwise → dsh-jsonrpc-agent runtime (worker.cordis.yml)
113
+ └─ DeepSeek V4 Flash / Pro (DSH SDK, event stream → progress and token stats)
114
+ ```
115
+
116
+ ## Satu eksekusi, dua sudut pandang
117
+
118
+ Dispatch bisa melebar. Di bawah ini delapan belas worker menerjemahkan README ini secara paralel: host menghitungnya sebagai subagent miliknya, sementara harness menjalankannya sebagai sesi nyata.
119
+
120
+ <p align="center">
121
+ <img src="./docs/images/dsh-adapter-host.png" alt="Claude Code" width="100%" />
122
+ </p>
123
+ <p align="center"><sub>Di Claude Code, worker dsh-adapter tampil sebagai subagent native; segmen statusline menampilkan tier yang berjalan, waktu berjalan, dan token.</sub></p>
124
+
125
+ <p align="center">
126
+ <img src="./docs/images/dsh-adapter-jobs.png" alt="DSH Adapter" width="100%" />
127
+ </p>
128
+ <p align="center"><sub>Panel DSH Adapter melihat eksekusi yang sama dari sisi harness: host mana yang mengirim setiap job, tier dan effort-nya, progres langsung, dan pemakaian token.</sub></p>
129
+
130
+ <p align="center"><sub>Panel ini juga merupakan papan job: job yang berjalan dan yang selesai tetap tercantum dengan tier, progres, dan token, workspace yang dipegang menyebut nama pemegangnya, dan job yang hilang di tengah jalan (restart hub) dimunculkan sebagai orphan ghost alih-alih menghilang diam-diam.</sub></p>
131
+
132
+ ## Instalasi
133
+
134
+ Pasang dari npm ke sebuah profil DSH:
135
+
136
+ ```bash
137
+ dsh plugin --profile web add @zoraxylia/dsh-codex-adapter@latest
138
+ dsh web
139
+ ```
140
+
141
+ Atau, untuk pengembangan lokal langsung dari kode sumber:
142
+
143
+ ```bash
144
+ dsh plugin --profile web add link:/path/to/dsh-adapter
145
+ dsh web
146
+ ```
147
+
148
+ Protokol `link:` menautkan dependensi profil ke repositori ini, sehingga hasil rebuild langsung terlihat.
149
+
150
+ ### Konfigurasikan kredensial DeepSeek (hanya standalone)
151
+
152
+ Dalam hub mode — instalasi di atas — worker berjalan di dalam instance DSH dan menggunakan kredensial DeepSeek yang sudah dikonfigurasi. Tidak perlu setup apa pun.
153
+
154
+ Hanya fallback standalone yang memerlukan key sendiri: ketika dispatch dari host tanpa instance DSH yang berjalan, worker runtime diluncurkan sebagai proses terpisah. Ambil API key di [platform.deepseek.com](https://platform.deepseek.com) lalu tulis ke `~/.config/dsh-adapter/.env`:
155
+
156
+ ```
157
+ DEEPSEEK_API_KEY=sk-...
158
+ ```
159
+
160
+ ### Verifikasi
161
+
162
+ ```bash
163
+ node scripts/smoke.mjs
164
+ ```
165
+
166
+ Smoke test mengirim satu job murah melalui path yang tersedia — hub saat instance DSH sedang berjalan, standalone sebaliknya — dan mencetak path mana yang digunakan. Dalam sekitar sepuluh detik akan muncul `smoke test passed — configuration OK`. Jika gagal, alasannya dicetak dan dibatasi pada path yang diuji.
167
+
168
+ Lalu buka Pengaturan → DSH Adapter dan pasang integrasi host — Claude Code, Codex, Antigravity, Grok — dengan sekali klik, atau jalankan installer yang sama dari baris perintah:
169
+
170
+ ```bash
171
+ node src/install/cli.mjs claude # plugin Claude Code: marketplace + izin + segmen HUD
172
+ node src/install/cli.mjs codex # agen + prompt Codex
173
+ node src/install/cli.mjs agy # konfigurasi MCP Antigravity + agen + skill
174
+ node src/install/cli.mjs grok # konfigurasi MCP Grok + agen + perintah
175
+ node src/install/cli.mjs all # keempat host sekaligus
176
+ # uninstall secara simetris (uninstall-claude | uninstall-codex | uninstall-agy | uninstall-grok):
177
+ node src/install/cli.mjs uninstall-claude
178
+ ```
179
+
180
+ ## Latar Belakang dan Terminologi
181
+
182
+ - **DSH** (DeepSeek Harness): harness agen sumber terbuka dari DeepSeek, agen kode dalam bentuk Web UI, mirip Claude Code tetapi menggerakkan model DeepSeek.
183
+ - **MCP** (Model Context Protocol): protokol integrasi tool AI dari Anthropic, memungkinkan LLM memanggil tool eksternal dan sumber data secara aman.
184
+ - **Cordis bundle**: format plugin DSH; proyek ini dapat berjalan standalone sebagai layanan MCP atau dipasang ke DSH Web sebagai mode hub.
185
+ - **tier**: tier kapabilitas — slot mana dari roster model DSH yang dikonfigurasi yang didapat seorang worker. `flash` cepat dan murah (tugas sederhana), `pro` menalar lebih dalam (masalah kompleks). Saat ini keduanya dipetakan ke DeepSeek V4 Flash dan V4 Pro; ganti model di DSH dan tidak ada yang berubah di sini.
186
+ - **worker**: agen DSH yang mengerjakan pekerjaan — sesi penuh dengan tools, sandbox, dan preset sendiri, bukan panggilan model biasa.
187
+ - **effort**: kekuatan penalaran, `off` = tanpa penalaran, `high` = investasi penalaran tinggi, `max` = investasi penalaran maksimum.
188
+
189
+ ## Claude Code
190
+
191
+ ### Instalasi
192
+
193
+ Instalasi sekali klik (pilih salah satu):
194
+
195
+ - **Halaman pengaturan DSH** (saat mode hub terpasang): Settings → DSH Adapter → "Install to Claude Code"
196
+ - **Baris perintah**: `node src/install/cli.mjs all`
197
+
198
+ Keduanya melakukan hal yang sama: mendaftarkan marketplace lokal (direktori induk `dsh-plugins/` sebagai root marketplace) + `claude plugin install` + daftar izin tool MCP + konfigurasi segmen status worker claude-hud (mencadangkan settings.json otomatis sebelum perubahan, idempotent). **Mulai ulang sesi setelah instalasi agar perubahan diterapkan.**
199
+
200
+ ### Penggunaan
201
+
202
+ - Langsung di percakapan, katakan "dispatch X to ds-flash" atau "dispatch X to ds-pro", dan subagent menjalankan tugasnya
203
+ - Jumlah dispatch dan progres waktu nyata ditampilkan di UI tugas Claude Code
204
+ - **Segmen status line HUD**: `⚙dsh 1▶pro 2m14s 21.7k/606 ✓3` (tier saat ini / waktu berjalan / penggunaan token / jumlah selesai)
205
+ - Untuk pengembangan lokal, `statusline/statusline.sh` atau `statusline/worker-segment.sh` dapat diintegrasikan secara terpisah
206
+ - **Tugas berdurasi panjang**: CC punya batas timeout pada panggilan MCP (`MCP_TOOL_TIMEOUT` dapat disesuaikan), untuk tugas panjang orchestrator dapat memakai polling `dsh_spawn_worker` + `dsh_worker_result(wait_seconds)`
207
+ - **Pengembangan dan debugging lokal**: `claude --plugin-dir /path/to/dsh-adapter` untuk memuat sementara
208
+
209
+
210
+ ### Perintah sesi
211
+
212
+ Hanya menimpa nilai default global untuk sesi saat ini, dan ditegakkan di lapisan tool, bukan lewat prompt:
213
+
214
+ | Perintah | Fungsinya |
215
+ |---|---|
216
+ | `/dsh-adapter:config` | Tampilkan atau setel default sesi: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<detik>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `origin_depth_limit=<1-32>`, `preset_flash/preset_pro=<preset id|default>`, `reset` |
217
+
218
+ | `/dsh-adapter:on` · `/dsh-adapter:off` | Nyalakan atau matikan dispatch untuk sesi ini (mati adalah saklar keras: tool menolak) |
219
+ | `/dsh-adapter:status` | Status langsung job worker: tier, progres, token, tool saat ini |
220
+ | `/dsh-adapter:playbook` | Praktik terbaik dispatch: memilih flash vs pro, brief yang mandiri, paralelisme, memverifikasi hasil, pagar pembatas |
221
+
222
+ ## Codex
223
+
224
+ ### Instalasi
225
+
226
+ Disarankan memakai installer (merender path otomatis untuk mesin ini, menyalin prompt `/dsh-config`, `/dsh-status`, dan `/dsh-playbook`):
227
+
228
+ ```bash
229
+ node src/install/cli.mjs codex
230
+ ```
231
+
232
+ Atau salin manual (memerlukan modifikasi path manual setelah menyalin):
233
+
234
+ ```bash
235
+ cp codex/agents/*.toml ~/.codex/agents/ # global or project-level .codex/agents/
236
+ ```
237
+
238
+ File role sudah dikonfigurasi sebelumnya dengan:
239
+
240
+ - Konfigurasi pemasangan server MCP
241
+ - `default_tools_approval_mode = "approve"` (**wajib**, jika tidak, panggilan tool otomatis dibatalkan dalam mode exec)
242
+ - `tool_timeout_sec = 3600`
243
+
244
+ **Catatan**: Saat menyalin manual, path absolut di kolom `args` harus diperbarui agar sesuai dengan lokasi instalasi sebenarnya; installer menanganinya secara otomatis.
245
+
246
+ ### Penggunaan
247
+
248
+ - Di TUI interaktif, pilih "spawn ds-pro to ..." untuk mengirim tugas; panel Active/Done menampilkan progres
249
+ - Mode `codex exec` juga dapat memanggil `dsh_run_worker` secara langsung
250
+
251
+
252
+ ### Perintah sesi
253
+
254
+ Untuk Codex dipasang tiga prompt:
255
+
256
+ | Perintah | Fungsinya |
257
+ |---|---|
258
+ | `/dsh-config` | Tampilkan atau setel default sesi: `tier=flash\|pro`, `effort=off\|high\|max`, `mode=auto\|hub\|standalone`, `timeout=<detik>`, `policy=auto\|flash-only\|pro-only`, `escalate=true\|false`, `origin_depth_limit=<1-32>`, `preset_flash/preset_pro=<preset id|default>`, `reset` |
259
+
260
+ | `/dsh-status` | Status langsung job worker: tier, progres, token, tool saat ini |
261
+ | `/dsh-playbook` | Praktik terbaik dispatch: memilih flash vs pro, brief yang mandiri, paralelisme, memverifikasi hasil, pagar pembatas |
262
+
263
+ ## Antigravity (agy)
264
+
265
+ ### Instalasi
266
+
267
+ ```bash
268
+ node src/install/cli.mjs agy
269
+ ```
270
+
271
+ Mendaftarkan server MCP dsh-adapter di `~/.gemini/config/mcp_config.json` dan memasang agen `ds-flash` / `ds-pro` plus skill `dsh-config`, `dsh-status`, dan `dsh-playbook` ke `~/.gemini/config/` (semua file dicadangkan terlebih dahulu). Mulai ulang sesi setelah instalasi.
272
+
273
+ ### Penggunaan
274
+
275
+ - Pilih `ds-flash` atau `ds-pro` sebagai agen untuk men-dispatch tugas
276
+ - `dsh_worker_config` membaca atau menimpa default sesi
277
+
278
+ ### Skill sesi
279
+
280
+ | Skill | Fungsinya |
281
+ |---|---|
282
+ | `/dsh-config` | Tampilkan atau setel default sesi (tier / effort / mode / timeout / policy / escalation / reset) |
283
+ | `/dsh-status` | Status langsung job worker: tier, progres, token, tool saat ini |
284
+ | `/dsh-playbook` | Praktik terbaik dispatch: memilih flash vs pro, brief yang mandiri, paralelisme, memverifikasi hasil, pagar pembatas |
285
+
286
+ ### Catatan
287
+
288
+ - agy menjalankan worker dengan **persetujuan penuh** (`--dangerously-skip-permissions` + accept-edits): agy 1.1.16 tidak punya mode izin berlingkup workspace, sehingga worker headless harus menyetujui permintaan tool secara otomatis.
289
+
290
+ Uninstall: `node src/install/cli.mjs uninstall-agy`
291
+
292
+ ## Grok
293
+
294
+ ### Instalasi
295
+
296
+ ```bash
297
+ node src/install/cli.mjs grok
298
+ ```
299
+
300
+ Menulis bagian `[mcp_servers.dsh-adapter]` ke `~/.grok/config.toml` dan memasang agen `ds-flash` / `ds-pro` plus perintah `/dsh-config`, `/dsh-status`, dan `/dsh-playbook` ke `~/.grok/` (semua file dicadangkan terlebih dahulu).
301
+
302
+ ### Penggunaan
303
+
304
+ - Pilih `ds-flash` atau `ds-pro` sebagai agen untuk men-dispatch tugas
305
+
306
+ ### Perintah sesi
307
+
308
+ | Perintah | Fungsinya |
309
+ |---|---|
310
+ | `/dsh-config` | Tampilkan atau setel default sesi (tier / effort / mode / timeout / policy / escalation / reset) |
311
+ | `/dsh-status` | Status langsung job worker: tier, progres, token, tool saat ini |
312
+ | `/dsh-playbook` | Praktik terbaik dispatch: memilih flash vs pro, brief yang mandiri, paralelisme, memverifikasi hasil, pagar pembatas |
313
+
314
+ ### Catatan
315
+
316
+ - Secara desain keamanan, grok tidak memulai server MCP tingkat repo di direktori proyek yang tidak dipercaya (`grok mcp doctor` melaporkan "folder untrusted"); instalasi global tidak terpengaruh — pindah direktori atau berikan `--trust`.
317
+ - Worker grok berjalan dengan `bypassPermissions` (selalu-menyetujui, sebagaimana direkomendasikan dokumen grok untuk otomasi headless); aturan deny dan hook tetap berlaku.
318
+
319
+ Uninstall: `node src/install/cli.mjs uninstall-grok`
320
+
321
+ ## Tool MCP
322
+
323
+ | Tool | Deskripsi |
324
+ |---|---|
325
+ | `dsh_run_worker` | Dispatch tugas blocking (`tier`: flash/pro, `effort`: off/high/max, `cwd`, `worker`), menunggu hasil |
326
+ | `dsh_spawn_worker` | Dispatch asinkron, mengembalikan job id (untuk fan-out paralel); kumpulkan hasil dengan `dsh_worker_result` |
327
+ | `dsh_worker_status` | Progres waktu nyata semua job (turn/langkah/tool saat ini/token) + advisory lock cwd |
328
+ | `dsh_worker_result` | Ambil hasil, dapat menentukan `wait_seconds` untuk menunggu |
329
+ | `dsh_worker_cancel` | Batalkan job tertentu, hentikan proses runtime-nya |
330
+ | `dsh_worker_config` | Baca/setel default sesi (tier, effort, mode, timeout, policy, escalation) dan daftarkan `worker_profiles` |
331
+
332
+ Progres secara bersamaan dicerminkan ke `~/.config/dsh-adapter/status.d/` (satu file shard per penulis, dapat dibaca oleh statusline / pemantauan eksternal).
333
+
334
+ ## Pagar Pembatas Dispatch
335
+
336
+ Setiap dispatch diperiksa sebelum apa pun dijalankan — penolakan adalah error yang terbaca, tidak pernah antre diam-diam:
337
+
338
+ - **Rantai origin**: setiap dispatch menambahkan satu hop ke rantai origin worker→worker. Nesting lebih dalam dari batas (`origin_depth_limit`, default 3) ditolak, begitu pula siklus apa pun (backend + cwd yang sama muncul dua kali) — penjaga yang menghentikan amplifikasi-diri worker secara rekursif.
339
+ - **advisory lock cwd**: satu worker berjalan per workspace. Dispatch kedua ke workspace yang dipegang ditolak dengan job id, backend, dan waktu mulai pemegangnya — tunggu sampai selesai, batalkan dengan `dsh_worker_cancel`, atau berikan `allow_concurrent_cwd: true` (khusus tugas read-only).
340
+
341
+ ## Panduan Dispatch
342
+
343
+ Cara men-dispatch dengan *baik* — flash vs pro, brief yang mandiri, paralelisme yang aman, memverifikasi hasil, dan pagar pembatas di atas — dibundel sebagai panduan per host: `/dsh-adapter:playbook` (skill Claude Code), `/dsh-playbook` (prompt Codex, skill Antigravity, perintah Grok).
344
+
345
+ ## Backend CLI Eksplisit
346
+
347
+ `worker="agy"` / `worker="grok"` mematok dispatch ke CLI eksternal tersebut (backend × model × effort) alih-alih logika tier DSH. Ini opt-in eksplisit — tidak ada default, jadi setel hanya ketika pengguna meminta CLI tersebut. Catatan: grok menolak memulai server MCP repo-lokal di folder yang tidak dipercaya, dan agy menjalankan worker dengan persetujuan penuh (tidak ada mode izin berlingkup workspace).
348
+
349
+ ## Multimodal: Vision dan Pembuatan Gambar
350
+
351
+ **DeepSeek adalah model khusus teks** dan tidak mendukung input maupun pembuatan gambar. Plugin ini memperoleh kapabilitas tersebut secara eksternal melalui tool MCP:
352
+
353
+ **Native vision terlebih dahulu**: ketika provider vision adalah CLI bawaan (atau secara eksplisit `native`), `describe_image` pertama-tama mencoba model VL milik DeepSeek `deepseek-v4-flash-vision-exp` (panggilan API langsung; key dari `DEEPSEEK_API_KEY` atau `~/.config/dsh-adapter/.env`). Kegagalan apa pun menurun secara halus ke rantai provider CLI di bawah, yang dipertahankan sebagai fallback. Pembuatan gambar tidak tersentuh — model native hanya pernah melihat gambar.
354
+
355
+ | Tool | Deskripsi |
356
+ |---|---|
357
+ | `describe_image` | Menjawab pertanyaan dengan melihat gambar (screenshot, desain, bagan, dll.), hasil di-cache berdasarkan provider + model + gambar + pertanyaan |
358
+ | `generate_image` | Membuat gambar dari deskripsi teks, menyimpan ke path absolut yang ditentukan; output berupa bitmap datar (memerlukan OpenPencil untuk pengeditan layer) |
359
+
360
+ **Menempel gambar di sesi**: Di DSH, ganti model ke `DeepSeek (vision) ◉` untuk menempel gambar secara langsung. Gambar tetap ada di sesi dan tampil normal; plugin menambahkan teks hasil transkripsi setelahnya dan menghapus gambar sebelum dikirim—Anda melihat gambarnya, model membaca teksnya. Transkripsi mengikuti tangga native-first yang sama: model VL DeepSeek bila key tersedia, lalu provider CLI yang Anda konfigurasi.
361
+
362
+ ### Konfigurasi
363
+
364
+ Di **halaman pengaturan DSH → DSH Adapter → Multimodal** (atau langsung edit `~/.config/dsh-adapter/config.json`):
365
+
366
+ **Provider vision** (melihat gambar):
367
+
368
+ - `native` / `deepseek-native` (model VL milik DeepSeek — otomatis dicoba pertama untuk setiap provider bawaan kapan pun key tersedia)
369
+ - `claude-code` (default, memakai haiku, murah)
370
+ - `codex` (memakai GPT, dapat menentukan model spesifik)
371
+ - `grok` (memakai Grok)
372
+ - `agy` (Antigravity)
373
+ - `custom` (API kompatibel OpenAI atau perintah lokal)
374
+ - `off` (nonaktif)
375
+
376
+ **Provider pembuatan gambar** (pembuatan gambar):
377
+
378
+ - `codex` (`$imagegen`, gpt-image-2)
379
+ - `agy` (Nano Banana)
380
+ - `grok` (Imagine)
381
+ - `custom` (API kompatibel OpenAI atau perintah lokal)
382
+ - `off` (nonaktif)
383
+
384
+ ### Provider Kustom
385
+
386
+ Dua metode integrasi:
387
+
388
+ **API**: Endpoint apa pun yang kompatibel dengan OpenAI
389
+ - Isi Base URL, API Key, daftar model
390
+ - Vision memakai `/chat/completions` dengan gambar base64 inline
391
+ - Pembuatan gambar memakai `/images/generations`
392
+ - **Harus menentukan "model pembuatan gambar" agar punya kapabilitas pembuatan**, jika tidak provider hanya muncul di pilihan vision
393
+
394
+ **CLI**: Template perintah lokal, placeholder diganti dengan referensi yang aman
395
+ - Vision: `{image} {question} {model}` → stdout sebagai jawaban
396
+ - Pembuatan gambar: `{prompt} {output} {size}` → perintah harus menulis file ke `{output}`
397
+ - Isi minimal satu perintah; mana pun yang diisi menentukan kapabilitas
398
+
399
+ **Uji konektivitas**: Setiap provider kustom punya tombol uji
400
+ - API: Periksa keterjangkauan endpoint dan autentikasi, kirim permintaan vision sungguhan untuk verifikasi
401
+ - CLI: Periksa file eksekutabel, jalankan perintah sungguhan untuk verifikasi
402
+ - Pembuatan gambar: Hanya validasi konfigurasi, tanpa output gambar sungguhan
403
+
404
+ **CLI langganan yang dipinjam** (claude / codex / grok / agy) mengharuskan Anda login secara lokal; plugin tidak akan menerobos izin mereka untuk Anda.
405
+
406
+ ## Mode Hub
407
+
408
+ Paket ini juga merupakan DSH bundle yang valid (`dsh.bundle` + `cordis.patch.yml`). Setelah dipasang ke profil DSH Web dengan `dsh plugin add dsh-adapter`:
409
+
410
+ - **Sesi worker menjadi warga kelas satu**: berjalan sebagai sesi kelas satu di host DSH (`agents.create` + waterfall model/effort per sesi + preset default), muncul di daftar sesi Web UI, dapat dibuka kapan saja untuk melihat eksekusi lengkap
411
+ - **Kelompokkan menurut direktori kerja**: kelola sesi worker berdasarkan cwd di Web UI
412
+ - **Loopback API**:
413
+ - `POST/GET /_dsh/dsh-adapter/jobs`: memulai tugas, daftar, long-poll hasil, membatalkan
414
+ - `GET /_dsh/dsh-adapter/ping`: pemeriksaan kesehatan (shim MCP memakai ini untuk mendeteksi apakah hub berjalan)
415
+ - `POST /_dsh/dsh-adapter/install`: instalasi sekali klik integrasi host — Claude Code / Codex / Antigravity / Grok (backend dari `src/install/`)
416
+ - **Deteksi otomatis**: shim MCP para host mendeteksi hub secara otomatis (env var `DSHPLUGIN_ADAPTER_HUB`, default `http://127.0.0.1:3080`)
417
+ - DSH Web berjalan → job masuk mode hub (`mode: "hub"`)
418
+ - Tidak berjalan → fallback ke runtime standalone
419
+
420
+ **Pemeriksaan proses Windows:** identifikasi sumber panggilan dan penghentian satu proses yang telah diverifikasi memakai PowerShell/CIM. API proses yatim menolak penghentian grup dengan `unsupported-platform` tanpa mengirim sinyal.
421
+
422
+ ## Pemilihan Solusi dan Keterbatasan
423
+
424
+ ### Pelanggan reguler → pendekatan subagent shell (disarankan)
425
+
426
+ - **Kondisi saat ini**: shell subagent Claude Code memakai haiku sebagai perantara; setiap dispatch menambah ratusan hingga ribuan token
427
+ - **Trade-off**: Memakai sedikit token Anthropic sebagai ganti UI tugas bawaan, tampilan progres waktu nyata, tanpa konfigurasi tambahan
428
+ - **Rekomendasi**: Jika Anda sudah berlangganan Claude Pro atau memakai Claude Code, gunakan pendekatan ini—praktis dan transparan
429
+
430
+ ### Lingkungan pay-as-you-go / CI → pendekatan router langsung
431
+
432
+ - **Kondisi saat ini**: frontmatter subagent Claude Code tidak mendukung koneksi model pihak ketiga secara langsung; eksperimen router di scratchpad repo ini memerlukan kredensial API-key untuk Claude Code, tetapi OAuth langganan diblokir di sisi upstream oleh Anthropic dengan 403
433
+ - **Rekomendasi**:
434
+ - Jika memakai kredensial API-key (bukan OAuth) dan ingin menghemat token Anthropic, dapat menjalankan router lokal untuk koneksi DeepSeek langsung
435
+ - Lingkungan CI biasanya juga memakai API key; pendekatan ini lebih ekonomis (semua token DeepSeek)
436
+ - Memerlukan pengujian sendiri untuk integrasi router (tidak didukung secara resmi)
437
+
438
+ ### Menjalankan DSH Web → mode hub aktif otomatis
439
+
440
+ - **Kondisi saat ini**: Jika `dsh plugin add dsh-adapter` dipasang ke profil DSH Web, job berjalan sebagai sesi kelas satu di host, muncul di daftar sesi Web UI
441
+ - **Rekomendasi**: Selama iterasi pengembangan lokal, disarankan mengaktifkan mode hub; progres worker dapat diamati sepenuhnya di Web UI; untuk kolaborasi lintas mesin atau lingkungan tanpa Web UI, gunakan pendekatan shell host yang men-dispatch
442
+
443
+ ### Hal yang Diketahui
444
+
445
+ - Role Codex secara teoretis dapat mencoba `model_provider` yang mengarah langsung ke DeepSeek (belum diverifikasi); jembatan ini tidak bergantung padanya
446
+ - Output pembuatan gambar berupa bitmap datar; pengeditan layer memerlukan OpenPencil
447
+ - **Dependensi runtime**: Hanya `@modelcontextprotocol/sdk` dan `zod`; `@deepseek-ai/*` adalah runtime host (disediakan oleh host DSH; instalasi npm biasa tidak pernah menariknya)
448
+ - **Codex wajib dikonfigurasi**: `default_tools_approval_mode = "approve"`, jika tidak panggilan tool otomatis dibatalkan
449
+
450
+ ## Pengembangan
451
+
452
+ ```bash
453
+ pnpm install
454
+ node_modules/.bin/tsdown src/client/index.tsx --format cjs --platform browser \
455
+ --target es2022 --tsconfig tsconfig.client.json --out-dir .client-build --clean
456
+ node scripts/build-client.mjs # wraps the bundle for the DSH module loader
457
+ node scripts/smoke.mjs # dispatches one real flash task end to end
458
+ ```
459
+
460
+ Dependensi runtime hanya `@modelcontextprotocol/sdk` dan `zod`; setiap paket `@deepseek-ai/*` adalah runtime host yang disediakan oleh host DSH (didokumentasikan di field dshHostRuntime pada package, bukan di peerDependencies, sehingga instalasi npm biasa tidak pernah menariknya), yang menjaga plugin tetap berada di dalam satu realm modul milik host.
461
+
462
+ ## Ekosistem
463
+
464
+ - [DSH Android](https://github.com/ZSeven-W/dsh-android) — emulator Android atau perangkat USB langsung di dalam percakapan, digerakkan sepenuhnya melalui adb
465
+ - [DSH iOS](https://github.com/ZSeven-W/dsh-ios) — iOS Simulator langsung — dan iPhone via USB — di dalam percakapan
466
+ - [DSH Noema](https://github.com/ZSeven-W/dsh-noema) — memori jangka panjang untuk DSH
467
+ - [DSH OpenPencil](https://github.com/ZSeven-W/dsh-openpencil) — memeriksa dan mengedit dokumen desain `.op` di dalam percakapan
468
+
469
+ ## Lisensi
470
+
471
+ MIT
472
+
473
+
474
+ ### `dsh_worker_probe` / `needs_input`
475
+
476
+ `dsh_worker_probe` mengirim satu permintaan alat tanpa efek dan berbatas waktu ke rute DSH, tanpa membuat worker atau mengubah binding. Token dapat terpakai. Pertanyaan tanpa jawaban menghentikan worker dengan `needs_input`; dapatkan jawaban pengguna lalu kirim ulang. Izin host diwarisi, tanpa OS sandbox baru.
477
+
478
+ ```js
479
+ dsh_worker_probe({ tier: "flash" })
480
+ ```