# dsh-agent-graph
Graph orchestration for DeepSeek Harness: scoped agent nodes, structured handoffs, bounded rework, and a layered global ledger.
English · 简体中文
A task such as “deliver this feature” can be split into nodes that each own one scope: research, spec, implementation, test plan, tests. `dsh-agent-graph` runs that graph. Every node is a fresh DSH subagent; an upstream node hands its delivery downstream as a structured contract; a node that finds an upstream delivery insufficient returns the problem to its direct upstream; and every node records progress, todos, key decisions and pitfalls into one layered ledger that any human or agent can read.
```bash
dsh plugin --profile web add dsh-agent-graph
```
## Table of contents
- [What it is](#what-it-is)
- [Why it exists](#why-it-exists)
- [How it compares](#how-it-compares)
- [Example workflow](#example-workflow)
- [Visual DAG editor (V2)](#visual-dag-editor-v2)
- [Install](#install)
- [The graph document](#the-graph-document)
- [Commands](#commands)
- [How a run works](#how-a-run-works)
- [Rework protocol](#rework-protocol)
- [The ledger](#the-ledger)
- [Node output contract](#node-output-contract)
- [CLI](#cli)
- [Data handling and limits](#data-handling-and-limits)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
## What it is
| Concern | How `dsh-agent-graph` handles it |
| --- | --- |
| Task decomposition | A YAML graph of nodes with `needs` edges; the engine validates it (cycles, unknown references, duplicate ids) before a run starts |
| Node execution | One-shot `ctx.subagents.start('spawn', …)` per activation, with a scope prompt, upstream handoffs, ledger pointers, and a structured output schema |
| Attention focus | Nodes share no conversation. An activation sees its own prompt, its upstream deliveries, and the ledger; nothing else |
| Visual authoring | In DSH Web, the **编排** conversation tab provides a drag-and-drop DAG canvas, node inspector, dependency editor and graph validation |
| Delivery between nodes | A structured handoff version (`summary` / `artifacts` / `openIssues`) is injected into every direct downstream activation |
| Insufficient upstream work | A bounded rework request returns to a **direct upstream** with evidence and an acceptance criterion; the request can be provided, declined, or forwarded one hop at a time |
| Shared memory | A per-run ledger (`README` → `index` → node sections → details) that nodes read and write and the engine regenerates deterministically |
| Failure behavior | Fail-fast: the first node failure stops the run; `/graph resume` retries failed and interrupted nodes |
| Observability | `/graph status` plus the ledger; every activation, handoff, rework trail and index is on disk |
The graph executes inside a DSH session as a human command (`/graph`), not as a model-facing tool. Nodes, however, are ordinary subagents and can use the tools their host grants them.
## Why it exists
DSH already delegates work well one call at a time. Long multi-step tasks then run into three recurring problems:
- **Context bleed.** A single conversation accumulates every concern; a node asked to write tests starts reasoning about architecture. Scope boundaries decay as history grows.
- **Silent compensation.** When an upstream result is not good enough, downstream agents tend to guess, work around it, or quietly expand their own scope instead of returning a precise request.
- **Disappearing reasoning.** When a node is re-created (retry, resume, follow-up), its conversation is gone. Decisions and pitfalls vanish with it.
`dsh-agent-graph` addresses each with a mechanism rather than a prompt: a declared graph for boundaries, a rework protocol with evidence and limits for escalation, and a durable ledger for memory. Agents stay disposable; the graph and the ledger persist.
## How it compares
These features solve adjacent, rather than identical, problems, and they compose. Pick the surface that fits the task.
| Need | `dsh-agent-graph` | Built-in `subagent` | Built-in `workflow` | Built-in `ralph` |
| --- | --- | --- | --- | --- |
| Unit of work | A declared node in a dependency graph | One delegated call | A model-written JS orchestration script | One immutable goal, iterated |
| Dependencies | Explicit `needs` edges, topologically scheduled | Caller decides order in chat | Written imperatively in the script | Not applicable |
| Data between agents | Structured handoff contract + artifacts | Final answer text | Script variables | Bounded structured report |
| When an upstream result is insufficient | Bounded rework request to the direct upstream, with evidence and an acceptance criterion | Caller retries or prompts again | Script decides (no protocol) | Workspace + next round |
| What survives a restart | Graph, handoff versions, ledger, run state (`/graph resume`) | Nothing | Run snapshot / effect cache (plugin-dependent) | Workspace |
| Human review surface | `/graph status` + layered ledger | Chat | Run UI | Chat |
Use `dsh-agent-graph` when a task has real dependency structure, more than two or three participants, and a long enough horizon that “who decided what” must survive re-creation. For one or two delegations, the built-in `subagent` tool is the shorter path.
## Example workflow
The repository ships a five-node example (`examples/feature-delivery.yaml`) and a scripted dry run (`examples/fake-script.json`) that needs no model:
```bash
npm install
npm run demo
```
A real run starts the same graph with live subagents:
```text
/graph run examples/feature-delivery.yaml
Started run feature-delivery-20260918-024342 (graph "feature-delivery", 5 nodes, concurrency 2).
Ledger: /path/to/workspace/.agent-graph/runs/feature-delivery-20260918-024342
Track with /graph status; nodes are DSH subagents, so this may take a while.
```
Tracking and inspection stay in the session:
```text
/graph status
Run feature-delivery-20260918-024342 — feature-delivery · status completed
activations 7/24 · started 2026-09-17T18:43:42.782Z · finished 2026-09-17T18:43:42.807Z
node state try handoff
implement ok 2 nodes/implement/handoff/v1.md
research ok 1 nodes/research/handoff/v1.md
spec ok 1 nodes/spec/handoff/v2.md
test-plan self_handled 2 nodes/test-plan/handoff/v1.md
tests ok 1 nodes/tests/handoff/v1.md
/graph show test-plan # prints that node's ledger section
```
The dry run demonstrates both rework outcomes: `implement` returns a missing detail to `spec`, which provides an addendum (`provided`); `test-plan` requests interface boundaries from `implement`, which declines because that is not its scope — `test-plan` then resolves the gap itself (`declined` → `self_handled`). Both exchanges are recorded under `requests/`.
## Visual DAG editor (V2)
When installed in DSH's Web profile, a new **编排** tab appears in the conversation header alongside the built-in views. It is a visual authoring surface for the same graph document: drag node cards to arrange the canvas, edit a node's id, scope, prompt and outputs in the inspector, and tick direct upstreams to draw dependency edges. The draft and its layout are kept per browser session, while a saved graph is written as canonical YAML under `.agent-graph/graphs/.yaml` — resolved against the DSH host process's working directory (the directory `dsh web` was started from), which the plugin config's `workspace` option can override. Both the graphs and the run ledger therefore live in that one workspace, not in each session's `cwd`.
The activation boundary is intentional and strict:
1. **Edit or save graph** — validates and writes YAML only. It does not call `ctx.subagents.start()`, so it creates **no** agent session.
2. **Save and run** — saves the same YAML, then starts a graph run.
3. **Scheduler activates a ready node** — only root nodes start immediately; each downstream node waits until every direct upstream has settled. At that point the scheduler calls DSH's `ctx.subagents.start()` for that one activation.
4. **DSH shows the child** — those activations are normal DSH subagent sessions (labelled `agent-graph::`), so they appear in the sidebar under their parent session. Nodes that are pending or blocked never have a child session to show.
This gives the canvas an inexpensive planning mode: build, move and validate a complex DAG before any model work begins, then inspect the real child sessions and durable ledger once execution starts.
## Install
### In DSH
From npm — recommended:
```bash
dsh plugin --profile web add dsh-agent-graph
```
From GitHub (pin a commit with `#` for reproducible installs):
```bash
dsh plugin --profile web add github:wrc093/dsh-agent-graph
```
From a local checkout (development):
```bash
cd /path/to/dsh-agent-graph
npm install && npm run build
dsh plugin --profile web add "$(pwd)"
```
Restart `dsh web` after installing or changing the plugin. Verify the plugin row is present:
```bash
dsh --profile web --dump-config | grep -i agent-graph
```
Requirements: Node.js `>=22`, a DSH profile with the `commands` and `subagents` services, and a subagent provider that supports structured output (`spawn` does; `acp`, `claude-code` and `codex` do not).
### Update or remove
```bash
dsh plugin --profile web add dsh-agent-graph # update from npm
dsh plugin --profile web add github:wrc093/dsh-agent-graph# # or pin a commit
dsh plugin --profile web remove dsh-agent-graph # remove
```
## The graph document
```yaml
name: feature-delivery
description: research → spec → implement → test plan → tests
concurrency: 2
budget:
maxNodeRuns: 24 # total activations, including rework retries
reworkPerEdge: 2 # rework requests allowed per dependency edge
nodes:
- id: research
scope: Investigate facts, constraints and risks; no solution design, no code
prompt: |
Investigate this requirement: relevant modules, constraints, risks …
outputs: [facts, constraints, risks]
- id: spec
needs: [research] # direct upstreams; also the only rework targets
scope: Turn the research into an executable spec; no code
prompt: |
Produce the spec from the upstream handoff …
```
| Field | Meaning |
| --- | --- |
| `name`, `description` | Identity of the graph, recorded in the ledger |
| `concurrency` | Maximum simultaneous activations; default `2` |
| `budget.maxNodeRuns` | Hard cap on activations for the whole run; default `40` |
| `budget.reworkPerEdge` | Hard cap on rework requests per dependency edge; default `2` |
| `nodes[].id` | `^[a-z][a-z0-9_-]*$`, unique within the graph |
| `nodes[].scope` | The ownership boundary. It is the criterion a node — and its peers — use to decide whether a rework request is legitimate |
| `nodes[].prompt` | Task description injected on every activation of this node |
| `nodes[].needs` | Direct upstream node ids. Upstreams drive scheduling and are the only nodes a rework request may target |
| `nodes[].outputs` | Optional, documentation only (shown in the node ledger section) |
The compiler rejects cycles, unknown or duplicate references, self-loops, non-positive budgets and malformed ids. The topological order is computed with an id-sorted frontier, so the same document always yields the same order.
## Commands
| Command | Behavior |
| --- | --- |
| `/graph run ` | Validates the graph, creates the run ledger, starts the run in the background and returns immediately |
| `/graph status [runId]` | Shows a run: state table, open rework requests, failures, recent activity (latest run by default) |
| `/graph resume [runId]` | Rebuilds the engine from `run.json` and continues; failed and interrupted nodes are retried |
| `/graph show [runId] ` | Prints one node's ledger section (`nodes//index.md`) |
| `/graph runs` | Lists runs in the workspace, newest first |
| `/graph editor save ` | Internal bridge used by **编排** to validate and save canonical YAML; it never starts a run or a subagent |
Runs execute in the background because nodes are full subagents. The ledger is the authoritative progress surface; `/graph status` reads the in-memory engine when the run is active and `run.json` otherwise.
## How a run works
1. **Validate and compile.** Parse the YAML, check the graph, compute upstream/downstream maps and a canonical topological order.
2. **Schedule.** Nodes whose `needs` have all settled (`ok` or `self_handled`) become runnable, up to `concurrency`. Holder activations for open rework requests are scheduled through the same limit.
3. **Activate.** The node starts as a one-shot subagent. Its prompt is assembled deterministically from: `scope` + `prompt`, the latest upstream handoffs, ledger paths (run `README`, its own node section, decisions/pitfalls indexes), recording duties, and — when applicable — the rework request or the retry resolution.
4. **Hand off.** A successful activation writes `nodes//handoff/vN.md`. Its `summary`, `artifacts` and `openIssues` are injected into every direct downstream activation on read.
5. **Record.** Each activation is written to `nodes//attempts/NNN.md`; the ledger's README, indexes, progress timeline and node sections are regenerated deterministically after every state change.
6. **Settle or fail.** When all nodes are `ok`/`self_handled` the run completes. The first node failure stops the run (in-flight activations are aborted); `resume` puts failed and interrupted nodes back to `pending`.
Every durable write is serialized through a single persist chain, so concurrent node completions cannot race on the same files.
## Rework protocol
A node that cannot fulfil its scope returns `status: "needs_rework"` with:
| Field | Meaning |
| --- | --- |
| `target` | A **direct upstream** node id (anything else degrades to self-handling) |
| `problem` | What is missing or wrong |
| `evidence` | Ledger/handoff references, e.g. `nodes/spec/handoff/v1.md#interface` |
| `acceptance` | What the upstream must deliver for the node to proceed |
The target is re-activated as a **holder** and must answer with exactly one outcome:
| Outcome | Effect |
| --- | --- |
| `provided` | The addendum is written as a new handoff version of the holder and handed back to the origin node, which is re-activated with the new material and the provenance (`providedBy`) |
| `declined` | The origin node is re-activated and told to complete the missing part itself; its final state becomes `self_handled` |
| forward | The holder returns `needs_rework` with its own direct upstream as the target; the request travels one hop and keeps its trail |
Bounds keep the loop finite:
- A request may be forwarded **once per node**; an invalid or missing forward target degrades to `declined`.
- The same problem (`problem` normalized and hashed per origin) may be requested only once. A repeat gives the origin **one** self-handle retry; a second repeat fails the node loudly (`unbounded rework`).
- `budget.reworkPerEdge` caps requests per edge; the next request on that edge degrades to self-handling.
- A holder activation that fails fails the run like any other node.
Every request is written to `requests/R-XXXX.md` with its full trail, so the escalation path is reviewable after the fact.
## The ledger
```text
.agent-graph/runs//
├── README.md # run overview, node table, recent activity
├── index.md # section index
├── progress.md # full activity timeline
├── run.json # durable machine-readable run state
├── nodes//
│ ├── index.md # scope, state, upstreams, handoffs, attempts
│ ├── handoff/vN.md # delivery versions (and rework addenda)
│ └── attempts/NNN.md # per-activation record written by the engine
├── decisions/index.md # aggregated `D-*.md` written by nodes
├── pitfalls/index.md # aggregated `P-*.md` written by nodes
└── requests/R-XXXX.md # rework requests with their full trail
```
Node agents are instructed to persist their working record with their normal file tools (`attempts/`, `decisions/D--.md`, `pitfalls/P--.md`, `todo.md`). The engine owns the layout and regenerates every index; nodes never edit shared files. Reading is layered: `README` → `index` → node section → drill-down.
`.agent-graph/` is ignored by this repository's `.gitignore`; decide per workspace whether a ledger should be committed or exported as a deliverable.
## Node output contract
Every activation must end with structured output, enforced through the DSH `outputSchema` (the child calls the structured-output tool):
```json
{
"status": "ok | needs_rework | failed",
"summary": "the handoff message downstream nodes will read",
"artifacts": ["path/to/deliverable"],
"openIssues": ["what downstream must know"],
"rework": {
"target": "direct-upstream-id",
"problem": "what is missing",
"evidence": ["nodes/spec/handoff/v1.md#section"],
"acceptance": "what must be delivered"
},
"reworkOutcome": "provided | declined",
"addendum": "material handed back to the origin node",
"declineReason": "why the request was declined"
}
```
`rework` is required when `status` is `needs_rework`. `reworkOutcome` + `addendum`/`declineReason` are required when a node answers as a rework holder. Results that violate the contract fail the node with an explicit reason; the engine validates every result, real or scripted.
## CLI
The CLI covers validation, dry runs and inspection. Real execution happens inside DSH, because nodes are host subagents.
```bash
dsh-agent-graph validate # parse + validate, print the topological order
dsh-agent-graph run --fake # dry run against scripted responses (no model, no network)
dsh-agent-graph status [--run ] [--workspace ] # inspect a run (state table, requests, failures)
dsh-agent-graph resume [--run ] --fake # continue a stopped/failed run
```
`--fake` uses the format `{ "nodes": { "": [ {result}, … ] } }`; see `examples/fake-script.json`. Exit codes: `0` success, `1` usage/validation error, `2` run ended failed.
## Data handling and limits
- The ledger is local plain text under `/.agent-graph/`. It contains node summaries, artifacts paths, decisions and pitfalls — **not** model credentials, prompts from other sessions, or tool arguments. Review a ledger before sharing it, since node-authored summaries can quote project content.
- Nodes run as DSH subagents with the permissions their host grants them. This plugin does not widen sandbox or approval settings.
- Every activation is a real subagent run and costs tokens. Budgets bound the spend: `budget.maxNodeRuns` caps total activations, `budget.reworkPerEdge` caps rework, and `nodeTimeoutMs` (plugin config, default 30 minutes) bounds one activation.
| Limit | Default | Meaning |
| --- | ---: | --- |
| `concurrency` | `2` | Maximum simultaneous activations |
| `budget.maxNodeRuns` | `40` | Total activations per run, including retries and rework |
| `budget.reworkPerEdge` | `2` | Rework requests per dependency edge |
| `nodeTimeoutMs` | `1800000` | Hard per-activation timeout; `0` disables it |
Exceeding `maxNodeRuns` fails the run with `budget exhausted`. Exceeding the timeout fails that node (fail-fast), and the message is recorded in the ledger.
## Troubleshooting
| Symptom | Check |
| --- | --- |
| `/graph` is ordinary chat | Plugin installed in the active profile, `commands` service present, host restarted after install |
| `subagent provider … does not support … capability` | Use a provider that supports `outputSchema` (`spawn`/`fork`); `acp`, `claude-code` and `codex` do not |
| `finished without structured output` | The child did not call the structured-output tool; check the provider's structured-output support, retry the node |
| Run immediately `failed` with `budget exhausted` | Raise `budget.maxNodeRuns` or reduce rework; a rework loop is visible in `requests/` |
| `unbounded rework` failure | The node re-requested a problem that was already self-handled; tighten the node prompt or the upstream delivery |
| `no runnable nodes: the graph is stuck` | A dependency never settled; inspect node states and open requests in `/graph status` |
| `invalid rework target` in the timeline | A node targeted a non-upstream node; it self-handled instead — fix the node prompt or the `needs` edges |
| Status shows `pending` nodes after a crash | Run `/graph resume `; finished nodes are not re-run |
| Graph validation error on start | Unknown/duplicate ids, a cycle, a self-loop, or a non-positive budget; the error lists every issue |
## Development
```bash
npm install
npm run typecheck
npm test
npm run demo # end-to-end dry run of the shipped example (no model required)
npm run build # dist/ (plugin entry + CLI)
```
| File | Responsibility |
| --- | --- |
| `src/core/graph.ts` | YAML parsing, validation, canonical topological compilation |
| `src/core/engine.ts` | Scheduling, handoffs, the rework state machine, persistence |
| `src/core/store.ts` | Ledger layout and deterministic index/progress regeneration |
| `src/core/runner.ts` | Node result contract, JSON schema, and the scripted test double |
| `src/core/prompt.ts` | Deterministic activation prompt assembly (scope, handoffs, ledger, rules) |
| `src/core/types.ts` | Shared vocabulary (graph, run state, requests, results) |
| `src/dsh/contracts.ts` | Structural contracts for `ctx.commands` and `ctx.subagents` |
| `src/dsh/subagent-runner.ts` | One-shot `spawn` runner with structured output |
| `src/plugin.ts`, `src/cli.ts` | Slash command surface and CLI |
| `test/`, `examples/` | Unit/integration tests and the shipped example |
Tests are deterministic: the scripted runner replaces subagents, so scheduling, rework and ledger semantics are covered without a model or network. The plugin command surface is verified against a fake host. See `mydocs/specs/` for the V1 design record.
For local DSH development, build the checkout, install its path into a development profile, and restart DSH after changes. Keep `.agent-graph/` and credentials out of source control.
## Contributing
Open an [issue](https://github.com/wrc093/dsh-agent-graph/issues) with a minimal graph, a scripted trace (or ledger excerpt), and the expected scheduling or rework behavior. Add a focused regression test under `test/` for semantic changes, and run the checks above. Documentation distinguishes what the protocol guarantees from what depends on node prompts and model behavior.
## License
This project is licensed under the [MIT License](LICENSE).