Skip to content
Back to search

dsh-loop-dock

A loop dock for DeepSeek Harness: one harness, multiple agent loops.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/euuuuuuzer--dsh-loop-dock/badge.svg)](/listings/euuuuuuzer--dsh-loop-dock)

HTML

<a href="/listings/euuuuuuzer--dsh-loop-dock"><img src="/api/listings/euuuuuuzer--dsh-loop-dock/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install DeepSeek Harness `0.1.0-rc.6` and `pnpm`. 2. Download `dsh-loop-dock-0.1.0.tgz` from the latest GitHub Release. 3. Install it into a clean web profile:

   dsh plugin --profile web add ./dsh-loop-dock-0.1.0.tgz
   dsh web

4. Open Settings → General → Default driver and choose `fake-driver`. 5. Create a new session and send any message. The reply is local:

   [FAKE-DRIVER] fake driver reply — generated locally, no model call.

No API key or network is needed for this first check.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 537 lines
  1. # dsh-loop-dock
  2. > One harness. Multiple agent loops.
  3. [![CI](https://github.com/euuuuuuzer/dsh-loop-dock/actions/workflows/ci.yml/badge.svg)](https://github.com/euuuuuuzer/dsh-loop-dock/actions)
  4. [![GitHub release](https://img.shields.io/github/v/release/euuuuuuzer/dsh-loop-dock?include_prereleases&label=release)](https://github.com/euuuuuuzer/dsh-loop-dock/releases)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
  6. [![Node >=22.19](https://img.shields.io/badge/node-%3E%3D22.19-green.svg)](./package.json)
  7. `dsh-loop-dock` is a community infrastructure plugin for
  8. [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). It
  9. does **not** design a new agent loop. It provides the dock that lets many loop
  10. providers exist in one harness and lets each agent choose which one runs it.
  11. [中文说明](./README.zh-CN.md)
  12. ## Quick Start
  13. 1. Install DeepSeek Harness `0.1.0-rc.6` and `pnpm`.
  14. 2. Download `dsh-loop-dock-0.1.0.tgz` from the latest GitHub Release.
  15. 3. Install it into a clean web profile:
  16. ```sh
  17. dsh plugin --profile web add ./dsh-loop-dock-0.1.0.tgz
  18. dsh web
  19. ```
  20. 4. Open Settings → General → Default driver and choose `fake-driver`.
  21. 5. Create a new session and send any message. The reply is local:
  22. ```text
  23. [FAKE-DRIVER] fake driver reply — generated locally, no model call.
  24. ```
  25. No API key or network is needed for this first check.
  26. ## Why dsh-loop-dock?
  27. A model's ceiling is not the model alone. The same model can behave very
  28. differently depending on turn structure, tool discipline, context management,
  29. planning strategy, and execution workflow.
  30. Community plugins have already shown this: small changes around one loop —
  31. a minimal-first preset, a prompt section, a bootstrap hook — can give the same
  32. model meaningfully different behavior.
  33. DSH already made the Agent Loop a plugin, but the slot is still effectively
  34. single:
  35. ```
  36. Agent A ─┐
  37. Agent B ─┼──> Loop X
  38. Agent C ─┘
  39. ```
  40. `dsh-loop-dock` opens the next step:
  41. ```
  42. Agent A ──> Loop X
  43. Agent B ──> Loop Y
  44. Agent C ──> Loop Z
  45. ```
  46. One harness. Multiple specialized loops.
  47. ## What does the dock do?
  48. The dock is intentionally simple. It does not decide how a loop reasons.
  49. It provides:
  50. - loop registration
  51. - loop selection
  52. - agent-loop binding
  53. - driver delegation
  54. The community builds the loops. The dock makes them composable.
  55. ## Example
  56. A future DSH setup could look like:
  57. ```yaml
  58. agent-loop-dock:
  59. agents:
  60. - id: coder
  61. provider: deepseek-official
  62. model: deepseek-v4-pro
  63. loop: coding-loop
  64. - id: researcher
  65. provider: deepseek-official
  66. model: deepseek-v4-flash
  67. loop: research-loop
  68. - id: planner
  69. provider: provider-c
  70. model: model-c
  71. loop: planning-loop
  72. ```
  73. `coding-loop`, `research-loop`, and `planning-loop` are community-registered
  74. loops. Each agent gets:
  75. ```
  76. one agent
  77. + one suitable model
  78. + one suitable loop
  79. ```
  80. instead of forcing every model and task through the same execution pattern.
  81. ## Try it without a model key
  82. The bundled patch registers `fake-driver` next to the real `default` driver.
  83. Switch the Settings row to `fake-driver`, create a new session, and send any
  84. message. It replies locally:
  85. ```text
  86. [FAKE-DRIVER] fake driver reply — generated locally, no model call.
  87. ```
  88. No API key and no network are involved. This makes loop and driver routing
  89. visible in the first minute.
  90. ## Architecture
  91. ```text
  92. ctx.agents.create / resume
  93. |
  94. v
  95. dsh-loop-dock
  96. (AgentFactory layer)
  97. |
  98. +-- LoopRegistry
  99. | | |
  100. v v v
  101. Loop A Loop B Loop C
  102. |
  103. v
  104. Agent Driver
  105. |
  106. v
  107. Model
  108. ```
  109. The dock separates two concepts:
  110. - **Strategy loop** — reuses an existing driver and only installs agent-scoped
  111. setup such as prompts, presets, hooks, tools, and policies. This is the
  112. common case.
  113. - **Driver loop** — a complete custom loop implementation owning
  114. `createAgent`, `resume`, and turn control flow. This is for fundamentally
  115. different execution architectures.
  116. ## Current Status
  117. Pre-alpha, but runnable.
  118. - ✅ Loop registry
  119. - ✅ Agent → loop routing
  120. - ✅ Durable loop + driver binding
  121. - ✅ Driver selection
  122. - ✅ Strategy loop protocol
  123. - ✅ Driver loop protocol
  124. - ✅ Default headless driver
  125. - ✅ Official `standard` strategy slot
  126. - ✅ Multi-agent integration tests
  127. The dock is working. The ecosystem is the next step.
  128. See [docs/architecture.md](./docs/architecture.md) for the roadmap.
  129. ## FAQ
  130. - **preset, loop, and driver** — preset defines tools/prompt sections; driver is the engine; loop is the complete loop an agent runs.
  131. - **Official `dsh-agent-loop`** — the dock disables the official row and owns the single `AgentFactory` slot; a vendored headless derivative is the default driver.
  132. - **fake-driver** — a local debug driver that never calls a model or the network; it always replies with `[FAKE-DRIVER]`.
  133. - **Do loop authors need a full driver?** — no, strategy loops only implement `setup(agentCtx)`; a driver loop is only for changing turn control flow itself.
  134. Full answers: [docs/faq.md](./docs/faq.md).
  135. ## Terminology
  136. Names follow DeepSeek Harness's own vocabulary (the official package
  137. `@deepseek-ai/dsh-agent-loop` never uses "engine"; it speaks of the
  138. "agent factory and driver service"):
  139. | Our term | What it means | Common / official phrasing |
  140. | --- | --- | --- |
  141. | **driver** | The core agent-loop implementation that owns the `createAgent`/`resume` contract and drives turns (`HeadlessAgentLoop` is the vendored official driver). | Official DSH: *agent loop* / *driver* ("agent factory and driver service"). Other harnesses often say *engine* (e.g. Codex engine) — DSH does not use that word. |
  142. | **loop** | The COMPLETE loop an agent runs, as registered in the `LoopRegistry`: a **strategy loop** (reuses a driver + installs agent-scoped setup) or a **driver loop** (`kind: 'driver'`, a full custom driver). `loop` is the whole loop; `driver` is only its engine part. | Community: *agent loop* / *loop*. Do not use "loop" for the engine layer. |
  143. | **strategy loop** | A loop that reuses a driver and only installs per-agent setup (mount a preset, add hooks). This is the common case. | Roughly: a preset/profile plus an adapter on top of one engine. |
  144. | **driver loop** | A loop that IS a complete driver (`createAgent`/`resume`), for control flow that differs from the default driver. | Roughly: a full engine implementation. |
  145. | **preset** | DSH's per-session composition (tools + prompt sections), selected via the native picker. | Official DSH: *preset*. Note: in everyday conversation "preset" sometimes means the loop — we always mean the tool/prompt composition. |
  146. | **model route** | The provider/model (+ reasoningEffort) a session's requests use. | Community: model config / model selection. |
  147. | **AgentFactory** | The `createAgent`/`resume` contract the factory registry delegates to (`ctx.agents.setFactory`). | Official DSH: *AgentFactory*. |
  148. | **harness** | The whole agent runtime platform (DSH itself, or Codex, etc.). | Common term across the ecosystem. |
  149. | **binding** | The durable `{ loop, driver? }` selection the dock records on a session at creation (`agent-preset/selected` `data.agentLoopDock`). | Recorded selection / route binding. |
  150. These concepts relate as follows: **preset** defines the tools and prompt sections, **driver** executes turns, **loop** is the complete loop an agent runs (strategy loop = driver + setup; driver loop = a full custom driver), and **model route** decides which LLM answers. Sessions pick a preset; the dock derives the loop; the loop (or settings) picks the driver; the request uses the model route.
  151. ## Implementation status
  152. **Pre-alpha but runnable: the routing core, the vendored headless official
  153. driver, and the shipped official `standard` strategy slot are implemented and tested together.**
  154. | Piece | Status |
  155. | --- | --- |
  156. | Named loop registry | ✅ implemented |
  157. | Agent → loop routing | ✅ implemented |
  158. | Durable loop + driver selection (known event binding, preset fallback) | ✅ implemented |
  159. | Local no-model ping adapter (`loop-ping`) | ✅ implemented |
  160. | Effective-preset model-route following (hero-chip switching) | ✅ implemented |
  161. | Fake driver for dual-driver testing (`fakeDriver: true`) | ✅ implemented |
  162. | Web Settings "Default driver" row (`agentLoops` Remote + `client.js`) | ✅ implemented |
  163. | Strategy-loop + driver-loop provider protocol | ✅ implemented |
  164. | `standard` strategy slot | ✅ registered |
  165. | Headless default driver (official loop derivative) | ✅ vendored, see [docs/default-driver.md](./docs/default-driver.md) |
  166. | Two-agent real-driver integration test | ✅ passing |
  167. | Core `SessionHeader.agentFactory` field | ❌ upstream follow-up only |
  168. Track the roadmap in [docs/architecture.md](./docs/architecture.md); the
  169. original motivation and design notes live in [DESIGN.md](./DESIGN.md).
  170. ## Model
  171. ```text
  172. ctx.agents.create / resume
  173. |
  174. dsh-loop-dock (the only AgentFactory)
  175. |
  176. +-- LoopRegistry (the slots)
  177. | +-- standard (strategy: standard preset)
  178. | +-- community-loop (user-registered community loop)
  179. | +-- ... (your loop)
  180. |
  181. +-- selection
  182. | explicit option > session route > preset route > default
  183. |
  184. +-- default driver
  185. +-- HeadlessDriver (vendored derivative of @deepseek-ai/dsh-agent-loop)
  186. ```
  187. A **strategy loop** reuses a driver and installs an agent-scoped setup. It
  188. may declare a preferred driver (`driver: 'loop2'`) or leave the choice to the
  189. caller. At creation time `loop` and `driver` are independent dimensions:
  190. ```js
  191. ctx.agents.create({ sessionId: 'a1', loop: 'strategy1', driver: 'loop1' })
  192. ctx.agents.create({ sessionId: 'a3', loop: 'strategy3', driver: 'loop2' })
  193. ```
  194. so one dock supports arbitrary driver × strategy combinations. A
  195. **model-specific loop** is usually a strategy loop: its author does not need
  196. to implement turn/step control flow.
  197. An **driver loop** owns the complete `createAgent` / `resume` contract. It is
  198. for loops whose control flow differs from the default driver.
  199. ## Install
  200. Install as a normal DSH profile plugin (local checkout before publication):
  201. ```sh
  202. cd /path/to/workspace
  203. dsh plugin --profile web add ./dsh-loop-dock
  204. ```
  205. Full usage instructions are in [docs/usage.md](./docs/usage.md) and the DSH
  206. multi-agent compatibility matrix is in [docs/compatibility.md](./docs/compatibility.md).
  207. The package declares `dsh.bundle.patch = cordis.patch.yml`. Its bundle patch
  208. disables the official `agent-loop` row and inserts `agent-loop-dock`, so the
  209. dock owns the single factory slot:
  210. ```yaml
  211. - id: agent-loop
  212. disabled: true
  213. - insert:
  214. - id: agent-loop-dock
  215. name: 'dsh-loop-dock'
  216. config:
  217. defaultLoop: standard
  218. defaultDriver: default
  219. presetLoops:
  220. standard: standard
  221. minimal: standard
  222. code: standard
  223. cordis: standard
  224. sessionLoops: {}
  225. agents: []
  226. - id: agent-loop-dock-default-driver
  227. name: 'dsh-loop-dock/headless-driver'
  228. config:
  229. maxParallelToolCalls: 10
  230. fakeDriver: true
  231. ```
  232. > Do not install a strategy-loop pack and the official loop adapter into the
  233. > same profile until the adapter is designed to leave `setFactory` to the
  234. > dock.
  235. ## Declarative agents
  236. The dock accepts the agent list the official loop used, plus `loop` and
  237. optional `driver` fields:
  238. ```yaml
  239. agent-loop-dock:
  240. defaultLoop: standard
  241. agents:
  242. - id: planner
  243. provider: provider-a
  244. model: model-a
  245. loop: loop-a
  246. sessionId: planner-session
  247. - id: coder
  248. provider: provider-b
  249. model: model-b
  250. loop: loop-b
  251. ```
  252. `loop` is optional. Without it, selection falls back through session routes,
  253. preset routes, and `defaultLoop`. `driver` is optional and falls back through
  254. route values, the strategy's declared driver, and `defaultDriver`.
  255. `provider`, `model`, `maxTokens`, `reasoningEffort`, and `cwd` are passed
  256. through to the driver and the strategy setup; consult your driver adapter for
  257. which fields it applies. A complete YAML shape lives in
  258. [examples/agents.example.yml](./examples/agents.example.yml).
  259. ### Driver picker in the web UI
  260. The plugin ships a client bundle (`client.js`) that renders a
  261. "默认驱动 / Default driver" row in Settings → General, listing the drivers
  262. registered with the dock and persisting the choice to the
  263. `agent-loops.defaultDriver` setting. It talks to the `agentLoops` Remote
  264. service (`listDrivers` / `setDefaultDriver`). Full wiring details, the
  265. packaging requirements (junctions, exports, inject semantics), and
  266. behavioral notes (new sessions only, blank-session reuse) are in
  267. [docs/usage.md](./docs/usage.md).
  268. ### Model routing is separate from loop routing
  269. The dock owns two coordinates:
  270. ```text
  271. loop routing: loop + driver
  272. model routing: provider + model (+ maxTokens + reasoningEffort)
  273. ```
  274. `provider` and `model` are consumed by DSH's LLM adapters; the dock passes
  275. them through, except loops that pin their own route (a loop registered
  276. programmatically with `provider`/`model`, e.g. the `loop-ping` debug
  277. adapter), which override the caller's choice — re-evaluated on every request
  278. against the session's effective preset, so preset switches follow live. So a
  279. four-agent team can be declared in one place:
  280. ```yaml
  281. agent-loop-dock:
  282. agents:
  283. - id: agent1
  284. provider: provider-a
  285. model: model-a
  286. loop: strategy1
  287. driver: loop1
  288. - id: agent2
  289. provider: provider-a
  290. model: model-a
  291. loop: strategy2
  292. driver: loop1
  293. - id: agent3
  294. provider: provider-b
  295. model: model-b
  296. loop: strategy3
  297. driver: loop2
  298. - id: agent4
  299. provider: provider-b
  300. model: model-b
  301. loop: strategy4
  302. driver: loop2
  303. ```
  304. ### Can I create that team by typing in the DSH Web chat?
  305. Not yet. The dock currently has no model-facing "create agent team" tool. The
  306. supported creation paths are:
  307. 1. declarative `agents` config (above);
  308. 2. programmatic `ctx.agents.create({ agentOptions, loop, driver })`;
  309. 3. DSH Web sessions created manually through the UI, where the model picker
  310. chooses the model and the preset picker chooses the mapped loop.
  311. Built-in subagents inherit their parent preset, and DSH's subagent tool schema
  312. does not expose `loop`/`driver` fields. A natural-language team-creation tool
  313. is a natural next plugin on top of this dock, but it is not implemented yet.
  314. ## Loop-provider protocol
  315. See [docs/loop-provider-spec.md](./docs/loop-provider-spec.md). Start from
  316. [examples/loop-author-template](./examples/loop-author-template).
  317. Strategy loop (the common case):
  318. ```js
  319. dock.register({
  320. id: 'community-loop',
  321. kind: 'strategy',
  322. description: 'community-owned setup for one model family',
  323. async setup(agentCtx) {
  324. // install presets, prompt sections, tool restrictions, event hooks
  325. },
  326. })
  327. ```
  328. Driver loop (custom control flow):
  329. ```js
  330. dock.register({
  331. id: 'planner-executor',
  332. kind: 'driver',
  333. async createAgent(ownerCtx, options) { /* ... */ },
  334. async resume(ownerCtx, options) { /* ... */ },
  335. })
  336. ```
  337. A default driver is installed once:
  338. ```js
  339. dock.registerDriver(headlessOfficialDriver)
  340. ```
  341. ## Selection precedence
  342. Create:
  343. ```text
  344. loop: options.loop > sessionLoops route > presetLoops route > defaultLoop
  345. driver: options.driver > route driver > preset driver
  346. > strategy.driver > settings defaultDriver > config defaultDriver
  347. ```
  348. Resume:
  349. - the durable binding recorded at creation as `agent-preset/selected`
  350. `data.agentLoopDock` (both `loop` and `driver`, when the creation-time
  351. driver resolution produced one);
  352. - for sessions without that record, the durable
  353. `SessionHeader.agentPreset` mapped through `presetLoops`;
  354. - exact `sessionLoops` routes;
  355. - an explicit or routed choice that differs from the recorded/mapped binding
  356. is rejected with `LOOP_SWITCH`, mirroring DSH's blank-session-only preset
  357. switch rule.
  358. > The dock persists the binding through the KNOWN `agent-preset/selected`
  359. > event, not through a custom event type. DSH's persistence read path
  360. > refuses unknown event types unless they are marked `ignorable`, and
  361. > `Session.append` has no public way to mark one. `agent-preset/selected`
  362. > is already in DSH's known-event vocabulary; the dock stores its payload
  363. > under `data.agentLoopDock` and preserves the session's effective preset
  364. > in the same event, so DSH reads the session exactly as before.
  365. ## Development
  366. ```sh
  367. npm test
  368. node examples/fake-two-loop.mjs
  369. node examples/fake-two-driver-loops.mjs
  370. npm pack --pack-destination /tmp
  371. bash scripts/smoke-portable.sh /tmp/dsh-loop-dock-0.1.0.tgz
  372. ```
  373. The regular suite skips the live API test. Opt in with a DeepSeek API key:
  374. ```sh
  375. DSH_LOOP_DOCK_LIVE_API=1 \
  376. DEEPSEEK_API_KEY=... \
  377. DSH_LOOP_DOCK_LIVE_MODEL=deepseek-chat \
  378. node --test test/live-api-2x2.test.mjs
  379. ```
  380. The live test runs four real model turns across a 2×2 matrix: two headless
  381. drivers × two strategies.
  382. `fake-two-loop.mjs` proves two strategy loops on one fake driver.
  383. `fake-two-driver-loops.mjs` proves two completely independent fake driver
  384. loops in one dock — the project's core claim without any real loop work.
  385. The routing core (`src/hub.mjs`, `src/selection.mjs`, `src/registry.mjs`,
  386. `src/config.mjs`, `src/errors.mjs`, `src/provider.mjs`) has no runtime
  387. dependencies. The plugin entry targets DSH `0.1.0-rc.6` peers and uses the
  388. host-plane services through `ctx.inject`, `ctx.effect`, `ctx.provide`,
  389. `ctx.agents.setFactory`, `ctx.llm.registerAdapter`, and
  390. `ctx.systemPrompt.variable`; agent creation/resume delegates only through the
  391. documented AgentFactory contract.
  392. ## License and attribution
  393. MIT. The vendored official-loop derivative retains the upstream MIT license
  394. and lists all modifications; see [NOTICE](./NOTICE) and
  395. `vendor/dsh-agent-loop-headless/`.
  396. This is a community project, not an official DeepSeek project.
  397. ## A brick, not the building
  398. Routing is the easy part. The dock is deliberately small and boring —
  399. register, select, bind, delegate — any competent plugin author could write
  400. it in a weekend.
  401. The hard part, and the reason this project exists, is that **nobody has
  402. written a second agent loop yet**. DSH made the Agent Loop a plugin — in my
  403. view, the only harness with that ambition — but the slot has stayed empty.
  404. This project is a dock: a working routing hub that proves the seam is real.
  405. I believe DSH is the harness that can most easily push **model × harness
  406. capability** to its limit: a model's ceiling is not the model alone, but the
  407. model driven by the right turn structure, budget, and tool discipline. An
  408. extreme example: GPT-5.6 Sol and GPT-5.6 Luna sharing the same Codex loop
  409. would not both run at full strength; whether it is GLM-5.3, Kimi K3, or
  410. GPT-5.6, each deserves a dedicated DSH loop, just as a
  411. deepseek-v4-pro-class model benefits from a loop shaped for it. The future
  412. this project points to is multi-agent by default, where every agent picks
  413. the model best suited to it and the agent loop best suited to that model —
  414. one agent, one model, one model-specific loop — with DSH as the platform
  415. where the model × harness matrix is freely recombined.
  416. I personally believe DSH is clearly moving in this direction, but it will
  417. take an extremely long time and an enormous amount of work — work that, in
  418. my view, only the open-source community can carry.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.