@kasenri/dsh-cx

Community plugin for DeepSeek Harness (DSH). Not affiliated with or endorsed by DeepSeek.

Deterministic engineering orchestration for DSH, implemented as a Cordis plugin:

• a CxService on ctx.cx
• a model-facing cx_controller tool
• recoverable tool guards

Goal
 │
 ▼
CxService
 └─ Deterministic Supervisor
     ├─ Commander   (plan / step & final evaluation / strategy reconsider)
     ├─ Executor    (one engineering step at a time)
     └─ Smart Watchdog (runtime diagnosis and recovery)

Every child role runs on DSH's native ctx.subagents service; durable state lives in <project>/.cx/state.json.

Requirements

Component	Tested with
@deepseek-ai/dsh	0.1.5-rc.2
@deepseek-ai/cordis	4.0.2
Node.js	>= 22.19.0

Requires the DSH base services: agents, subagents, tools, sessions (the standard/web profile provides them).

Install

dsh plugin --profile web add @kasenri/[email protected]

The package declares a dsh.bundle patch, so dsh plugin add registers it as a profile layer automatically.

Usage

The cx_controller tool drives the run:

Action	Meaning
run / start	Start a run for a goal (or continue the current one).
resume	Continue the persisted run after an interruption.
status	Inspect phase, plan, loop budget and last error.
stop	Close the run.
doctor	Read-only environment and configuration checks.

// cx_controller
{
  "action": "run",
  "goal": "…",
  "approved_loop_count": 4,
  "user_hard_constraints": ["only touch src/"]
}

State machine

PLAN → EXECUTE → EVALUATE → SUCCESS
                     │
                     ├─ correction (bounded per step)
                     ├─ append (bounded by remaining loop budget)
                     ├─ NEEDS_USER
                     └─ BUDGET_EXHAUSTED

• Only a normally completed Executor step consumes one loop from the budget.
• Corrections are limited per base step and reserve budget for the remaining planned steps.
• Commander decisions are validated in code (PASS_CURRENT_STEP / CORRECT_CURRENT_STEP / NEEDS_USER for step evaluation, SUCCESS / APPEND / NEEDS_USER for final evaluation, KEEP_APPROACH / REPLACE_CURRENT_STEP / NEEDS_USER for strategy reconsider).
• Commander runs under an adaptive timeout: a soft review at 360s, a second review at 600s and a deterministic hard ceiling at 840s; an extension always keeps the same child.
• The Smart Watchdog is only invoked on runtime anomalies, performs at most two diagnoses per step, and can resume the same child or restart the step with a fresh one after interrupting the old child.
• Blocked tools are recoverable: a guard denial stops that single call, not the turn or the run.

Safety boundaries

• Commander and Watchdog receive read-only tool allowlists.
• Executors receive the configured writer allowlist; browser tools are added only for steps that declare the browser capability.
• While CX owns a workspace, other top-level autonomous drivers (create_goal, ralph, workflow) are refused, and CX refuses to start while an active goal driver owns the same workspace.
• .cx durable state is written only by the CX service (atomic write, short lock transaction, monotonic revision).

Configuration

Key	Default	Meaning
projectDir	session cwd	Project the run operates on.
routes.commander	deepseek-official / deepseek-v4-pro / high	Commander model route.
routes.executor	deepseek-official / deepseek-v4-flash / high	Executor model route.
routes.watchdog	deepseek-official / deepseek-v4-flash / low	Watchdog model route.
executorTools	read/glob/grep/bash/edit/write/…	Executor allowlist.
browserTools	["agent_browser"]	Browser capability tool names.
commanderReadOnlyTools	read/glob/grep/web…	Commander allowlist.
watchdogTools	read/glob/grep	Watchdog allowlist.
executorTimeoutMs	480000	Deterministic executor runtime timeout.
registerTool	true	Register the cx_controller tool.
registerGuards	true	Register recoverable tool guards.

Routes are normal DSH model routes; configure them for your own provider and model identifiers. No credentials are included in this package.

Optional browser capability

CX does not depend on @kasenri/dsh-browser. A plan step that declares capabilities: ["browser"] needs the agent_browser tool to be registered by the browser plugin; otherwise CX reports BROWSER_CAPABILITY_UNAVAILABLE and lets the Commander decide what to do. Install both packages to use that path:

dsh plugin --profile web add @kasenri/[email protected]
dsh plugin --profile web add @kasenri/[email protected]

License

MIT