omp-dsh-workers

Run DeepSeek Harness (DSH) workers from your oh-my-pi session. oh-my-pi (OMP) is a terminal coding agent; DeepSeek Harness (dsh) is DeepSeek's agent runtime. The session becomes the director: it hands out briefs with dsh_spawn, each worker runs as a persistent dsh --profile headless session, and worker questions and results return as native messages relayed by a script.

Experimental v0.1: the interfaces are frozen in docs/contracts/, but nothing here has been through a public release cycle yet.

Why

The OMP harness is expensive per task, and a native sub-agent pays that cost on every job. Here it is paid once at the director level; the work runs in DSH, fast and token-frugal, with only a script between them: zero model tokens per task. DSH makes runs persistent (--resume on a real session id). When you do not need DSH, native sub-agents are still the right choice.

Related MCP server: dsh-crew

How it works

Two model levels, deliberately separate:

So @dsh names the executor's inherited model when dsh_spawn has no model — the watcher is code, not a model.

flowchart TD
    D["Director<br/>main OMP session, /dvibe on"]
    B["dsh-bridge<br/>argv spawn · run registry · steer channel"]
    X["DSH headless run<br/>+ resume plugin"]
    L["relay.ts<br/>script representative, in-process"]
    D -->|"dsh_spawn — brief, label, model"| B
    B -->|"dsh --profile headless [--resume]"| X
    X -->|"Envelope v1 (last stdout line)"| B
    B -->|"pollRun, 1s"| L
    L -->|"⟨label⟩ question / result / failure (followUp)"| D
    D -->|"dsh_answer — resumes the session"| B
    D -.->|"steering: dsh_list → dsh_send / dsh_wait by runId"| B
    D -.->|"dsh_kill by runId"| B

The director spawns with dsh_spawn, answers with dsh_answer, steers with dsh_send, waits with dsh_wait and cancels with dsh_kill; dsh_list resolves a label to a runId.

Components

Requirements

• oh-my-pi v18 — verified against 18.0.3 / 18.0.4; @oh-my-pi/* pinned at ^18.0.4.

• DSH ≥ 0.1.1-rc.2 on PATH, with the headless profile present.

• bun for the test scripts; Node ≥ 22 for bridge-core.

• A model provider configured in your DSH settings; the extension is provider-neutral: it passes a <provider>/<model>[:<effort>] string to DSH.

DSH is at release-candidate stage. The resume plugin attaches by entry id, so a release renaming those ids makes the patch silently stop applying. After every DSH upgrade re-run dsh --profile headless --help: if --resume is gone, the plugin is not mounted; docs/dsh-update-checklist.md has the full checklist.

Install

The repository is the source of truth; live directories only ever receive symlinks back into it.

1. Link the extension into OMP.

scripts/install-omp-links.sh [--dry-run] [--uninstall] [--omp-dir DIR]

Creates a symlink extensions/dsh-task under $OMP_DIR (default $HOME/.omp/agent). Idempotent — a same-source link is left alone, one pointing elsewhere is re-pointed, and a real file at the destination aborts the script. --uninstall removes only links that point here.

2. Mount the resume plugin into the DSH headless profile.

scripts/install-resume-plugin.sh              # install
scripts/install-resume-plugin.sh --uninstall  # remove

Backs up before every change; requires dsh on PATH and ${DSH_HOME:-$HOME/.dsh}/profiles/headless. Then:

• Symlinks @deepseek-ai and commander from $DSH_MODULES into the plugin's node_modules.

• Adds the plugin: dsh plugin --profile headless add link:<plugin dir>, after backing up package.json.

• Appends a cordis.patch.yml block that disables headless-startup / headless-runner and inserts headless-resume-startup / headless-resume-runner.

• Verifies: success only when dsh --profile headless --help mentions --resume.

3. (tests only) scripts/link-plugin-deps.sh links dependencies on its own; bun run test:resume calls it.

Usage

Director mode

• /dvibe toggles director mode; /dvibe on / /dvibe off are explicit. The model can also switch it via the dvibe tool (action: "on" | "off"), which stays in the narrowed toolset.

• While on, the toolset narrows to read, todo, dsh_spawn, dsh_answer, dsh_send, dsh_wait, dsh_list, dsh_kill, dvibe, plus a director directive appended to the system prompt. The dvibe tool returns that directive in its result: the model calls it after before_agent_start has run, so the turn prompt cannot carry the rules.

• Briefs go into dsh_spawn verbatim. Worker questions arrive as ⟨label⟩ messages from relay.ts, answered with dsh_answer; results arrive the same way.

• Delivery is at-least-once: an event is re-announced every 120 s until a matching message_start proves the followUp entered the turn context; max 3 attempts per event. A delivered need_input stays watched until dsh_answer.

• Finished handing out work? End the turn: events arrive as messages on their own.

• dsh_wait is the synchronous alternative, only when the next step blocks on that specific run and nothing is left to hand out; an envelope read this way never arrives twice.

• On /dvibe off, shutdown, or an in-process session switch the previous toolset is restored.

Briefs, models, resume

• Give each task a short label and, optionally, a model, both as dsh_spawn parameters; the label finds the run later in dsh_list, dsh_answer, dsh_send.

• Model notation is <provider>/<model>[:<effort>]; effort levels: off, minimal, low, medium, high, xhigh, max. The suffix after the last : counts as effort only if it is one of them, else the colon belongs to the model name. No whitespace or control characters; provider/model ≤ 200 chars each, spec ≤ 512; malformed spec fails before spawning: error [invalid_model].

• Without model, the run inherits the @dsh role from OMP (modelRoles.dsh), falls back to your session's model, then to DSH's own default.

• Resume: pass resumeFromRunId; the bridge looks up its sessionId. Do not put a runId into resumeSessionId: different identifiers, you get resume_not_found.

• Resume works once the run has left an envelope on disk; without one dsh_spawn throws has no session to resume — for a run still running as well as one gone (killed early, crashed at startup, swept). Check which before reacting: a new brief for a still-working run duplicates work.

• The model override is not sticky: a resume without model recomputes the model. dsh_answer has no model parameter at all; to continue on another model use dsh_spawn with resumeFromRunId and an explicit model.

What the director sees

Tool cards render for humans, separately from the text the model receives: ▶ dsh spawn → <label>, ✓ started <label> (<runId8>) · pid …, then ⏳ still running with last output lines or ✓ completed · model: … · session: … plus first result lines. While runs are tracked, a dsh runs board sits above the editor and the footer shows dsh: N running · M done. The tools' text output is unchanged: it remains the contract.

Tools

dsh_wait timing out is normal: the run stays alive and can be waited on again; aborting a wait never stops the run. pending from dsh_send means the write reached the channel and the run was alive on re-check — not confirmed delivery; wait instead of resending. dsh_task leaves no envelope, so its run cannot be continued; chains go through dsh_spawn.

Lines the director can rely on

These lines go into the tool's text output, not only details, so a director reading plain text can verify executor, continuity and error codes:

model: <provider>/<model>[:<effort>]
session: <sessionId>
error [<code>]: <message>

# and one line per run from dsh_list:
<runId> state=<state> label=<label|-> model=<spec|default> started=<ISO-8601>

Error codes

Every failure returns as an explicit error turn with an envelope code, never a partial success.

デフォルト: 実行期限30分、オーナーリース5分。各dsh_waitウィンドウで更新されます。

テスト

bun run test          # unit + integration + bridge = 370 tests, no installed DSH needed
bun run test:resume   # resume plugin — needs an installed DSH

このツリーで検証された数: 単体195 + 統合11 + ブリッジ164 = 370テスト。DSHがインストールされていなくても合格します。単体テストはbridge-coreをモックし、統合テストとブリッジテストはDSH_BINARYを通じて注入されたフェイクのdshバイナリに対して実行されます。CIはtypecheck、lint、format:check（strict tsc、Biome）の後に、クリーンなHOMEで同じ3つのスイートを実行します。test:resumeは実行時に@deepseek-ai/*をインポートするため、DSHがインストールされている必要があります。

制限事項

• 孤立した実行は防止されるのではなく、掃除されます。 DSHの実行はOMPセッションより長く存続します。掃除はロード時と30秒ごとに行われます。クリーンなsession_shutdownでは、拡張機能はレジストリをクリアせずに自身の実行を終了します（SIGTERMは同期、SIGKILLはベストエフォート）。

• 実行中のクラッシュからの復旧はありません: ターン途中の死亡は復元されません。再開できるのはDSHセッションのみです。

• 再開時のコンパクションは、最初の新しいリクエストヘッダーが書き込まれるまで、前回の実行のヘッダーを読み取ります。

• エンベロープ内のmodelはベストエフォートです: 最後に準備されたリクエスト設定であり、ディスパッチの証明ではありません。

• モデルオーバーライドは実行ごとであり、resumeFromRunIdをまたいで継承されません。

• ハブのメトリクスはDSHトークンを認識しません。

ステータス、履歴、ライセンス

実験的なv0.1（0.1.0）です。インターフェース契約はdocs/contracts/にあります。docs/dsh-update-checklist.mdはDSHのアップグレードを扱います。ユーザーまたはモデルが読むものはすべて英語です。コード内のコメントとテスト名はロシア語です。MITライセンス。