dsh-gatedflow

Gated, durable, human-in-the-loop workflows for DeepSeek Harness — gates as control flow: "must verify / confirm / review" rules live in the engine, not in prompts, so no agent can skip them under load.

Zero-mutation replan · gates as control flow · declarative subflows. The engine core contains no LLM and no orchestrator dependencies.

Packages

The idea in one picture

user task ──► agent composes atomics (Ref/Inline) ──► gf_start
                                                       │
              path ① single Ref ──────────────┐        │
              path ② multi/inline ── pre_start_gate (human approves the plan)
                                                       ▼
              shell (command + expect) ─ interrupt (human gate via panel)
              handoff (delegate back to the agent) ─ conditional (structured fields)
                                                       ▼
                                                   done (auto)

• Gates are control flow. interrupt steps pause the engine; the human approves or rejects through a panel card in the conversation. The model agent has no approve/reject channel — gf_advance rejects them (guard
  • schema), and decisions travel straight from the panel to the engine.
• Zero mutation. Agents cannot rewrite workflow state, params, or routing. Failures take exactly two paths: step-level failure with pause_on_failure → pause → human repairs → retry (prior outputs kept); otherwise abort → failed → human reviews → new workflow.
• Declarative subflows. Workflows are JSON/YAML data, validated at load time and snapshotted at start — what the human approves is exactly what executes.
• No LLM in the engine. Semantic judgment happens on the agent side and returns structured fields; the engine only evaluates deterministic operators (==, !=, >=, <=, >, <, contains, &&, ||, !).

Quick start

npm install
npm run check   # build + typecheck + unit tests

Run a workflow (as a DSH user)

The adapter registers seven tools. The agent composes a plan, then:

gf_start({ atomics: [
  { name: 'gf-verify-demo', params: { note: 'hello' } },
  { type: 'shell', params: { command: 'echo done', expect: 'true' } },
]})

• Single Ref runs the preset deterministically (no gate wrapper).
• Multiple / Inline atomics wrap a pre_start_gate: the engine pauses and the plan appears as a panel card above the composer. Click ✓ Approve to proceed or ✕ Reject to abort.
• Handoff gates pause for the agent; the agent returns structured results via gf_advance(handoff_complete, result).
• A failed step with pause_on_failure shows an Awaiting retry card; after the human repairs the environment, gf_advance(decision: 'retry') re-runs only that step.

Author a subflow

Drop a JSON file into a subflows directory — the session workspace's .gatedflow/subflows (scanned automatically, takes precedence on name conflicts) or the shared root (~/.gatedflow/subflows by default, GATEDFLOW_SUBFLOWS_DIR to override) — then call gf_reload_subflows (hot-loaded, no restart):

{
  "name": "release",
  "description": "build with objective verification, human review, then publish",
  "keywords": ["release", "build", "review"],
  "params": { "branch": { "required": true } },
  "steps": [
    { "id": "build", "type": "shell", "params": { "command": "npm run build", "expect": "test -f dist/index.js", "max_retries": 1, "pause_on_failure": true }, "on_success": "review", "on_failure": "abort" },
    { "id": "review", "type": "interrupt", "params": { "message": "Publish ${branch}?" }, "on_approve": "publish", "on_reject": "abort" },
    { "id": "publish", "type": "shell", "params": { "command": "npm publish" }, "on_success": "next", "on_failure": "abort" }
  ]
}

See examples/subflows/ for more.

Architecture

• docs/DESIGN.md — root constraints, step model, routing, data references, gate protocol, persistence and anti-stuck design, with the decision record.
• docs/INTEGRATION.md — mounting the adapter in a DSH composition, environment variables, tool reference, and the agent skill guidance.

Development

npm install
npm run test          # unit tests (vitest, engine + adapter)
npm run typecheck     # strict TS across both packages
npm run build         # tsc output for engine + dsh

The engine package is deliberately dependency-free and framework-agnostic; the DSH adapter is a thin, typed wiring layer over the harness services (fs, shell, tools, timer, subagents; the gateway row additionally consumes webServer), configurable through a schemastery Config schema exactly like the official DSH plugins. See the package README for the plugin contract. Contributions welcome — see CONTRIBUTING.md.

Status

v0.1 ships the engine core plus the DSH adapter with shell / interrupt / handoff / conditional / agent_delegate / agent_resume steps, the gate panel, the anti-bypass guard, gate deadlines, /stop-safe interruption semantics, hot-reloadable subflows, bounded-tail audit logs, and restore-on-reference persistence. Roadmap: YAML-native subflow authoring improvements and a solidify flow that turns recurring dynamic plans into named presets.

License

MIT — see LICENSE.

Relationship to gatedflow

This project is an independent, native implementation of the gatedflow philosophy for DeepSeek Harness. It shares the vocabulary (atomics, subflows, pre_start_gate, zero-mutation replan, decision records) but re-implements everything on harness-native primitives — the engine core is written from scratch in TypeScript with no external dependencies.