dsh-super-agent — the zero-code composition¶
Status: reference page, written against
main; not executed on a live dsh-superagent host. What is verified here is the plugin's rows, the CLI commands they name, the command dsh itself prints for a missing profile, and the offline pilot the verification script runs. What needs a live host is marked unverified on this page;scripts/verify-dsh-superagent.shsettles it on your machine, and skips rather than guesses when it cannot compose (no dsh, no profile, or a read-only DSH home — this page's authoring box is the last one).
AgentDescent does not need a new plugin for dsh-super-agent.
The rows it already ships are ordinary Cordis rows, so the same install that
works for the web profile composes in the superagent profile. This page is
the shortest path from a fresh checkout to one offline pilot run from a
dsh-superagent-worker, and the four traps that make it fail silently.
1. What composes¶
integrations/dsh-agentdescent/cordis.patch.yml contributes two rows:
dsh-agentdescent— the skill, registered at runtime, so it cannot drift from the package;mcp-agentdescent— a@deepseek-ai/dsh-mcp-clientrow withcommand: agentdescent,args: ["mcp"],transport: stdio, a 120000 ms tool-call timeout, and an explicit env allowlist because dsh scrubsKEY|PASSWORD|SECRET|TOKENfrom the ambient environment (integrations/dsh-agentdescent/cordis.patch.yml:8-26).
Rows are inserted, not overridden: a bare row would be read as an override of
an id that does not exist and dsh composes without it — the same trap the file's
own header names.
agentdescent install dsh is the file-based alternative: it writes
$DSH_HOME/skills/agentdescent/SKILL.md, $DSH_HOME/skills/agentdescent/hooks.json,
and a marked block in $DSH_HOME/cordis.patch.yml
(agentdescent/integrations/__init__.py:345-355). Use the plugin or the files,
never both: two mcp-agentdescent rows expose the same tools twice.
2. Install into the superagent profile¶
The profile is chosen by the same flag the plugin README documents for web
(integrations/dsh-agentdescent/README.md):
Unverified on this page: that the superagent profile behaves exactly as
web does. What dsh itself does say: dsh --profile superagent --dump-config
fails with profile "superagent" does not exist; create it with 'dsh plugin
--profile superagent add <package>', so the profile is created by the install
rather than before it. If dsh plugin --profile superagent reports no plugin
surface, use the file-based install instead — it needs no profile support beyond
the skill directory dsh already reads:
3. Verify the rows, not the intent¶
The first command must print both rows: dsh-agentdescent and
mcp-agentdescent. One row means the other was dropped as a dangling override.
doctor reports which agents, keys and optional pieces this machine actually
has; it does not prove the worker preset exposes the tools, which is step 4.
4. The worker loop, and the one rule¶
A worker asks for a Ticket, plans, starts, and then hands the run back — it does not apply:
plan -> validate the spec and estimate the cost (writes nothing)
start -> create the run (writes under the store)
status -> progress; a long run survives a turn boundary
show -> the pilot report and the learned artifact
Then attach the pilot report to the Ticket and stop. --dry-run or an offline
text kind first is the cheap rehearsal; a real model run costs tokens and
should be its own Ticket.
The no-auto-apply rule is not stylistic: a run's artifact is a candidate, and
applying it is a separate, reviewed step (apply is the tool that writes into
your tree, under the operator's write allowlist).
5. Write dirs and budget for a worker¶
- Set
AGENTDESCENT_SURFACE_WRITE_DIRSto the worker's own workspace. The default is the server's cwd plus$AGENTDESCENT_HOME(agentdescent/surface_common.py:178-190); an empty value refuses every MCP write path, which is the safest setting for a worker that should only plan. The CLIapplyreads the same variable, and inside a worker the server default applies there as well even when the variable is unset (#1082).algorithm_specobeys this allowlist from the release that carries#1018(fix in#1022). On an older version it can drop a spec outside its Ticket by naming anout: set the allowlist empty for a plan-only worker, or do not exposealgorithm_specat all. - Keep
--storeinside the run directory, so a Ticket's runs are removable with the Ticket. planis the budget line: it estimates cost without executing. Read it beforestart, and put the number in the Ticket.- A detached run no longer inherits the worker session:
launchdrops every host-session marker (SESSION_MARKERS:DSH_*,CLAUDE*,CODEX*,MCP_*, the OpenCode config carriers,XDG_CONFIG_HOME) before it starts the grandchild, so the worker's session identity and MCP config stay with the host while the API keys the run needs are passed through (#1082). The list is the one the candidate worker drops, not a second copy of it. The host's config/home directories (DETACHED_KEEP_VARS:CLAUDE_CONFIG_DIR,CODEX_HOME,DSH_HOME,XDG_CONFIG_HOME) are kept: they name configuration, not session, and this run resolves a host's real home from them forisolate: falseworkers and foragentdescent startfrom a terminal.
6. Long runs, Reports and Attention¶
A run outlives a worker turn: status is cheap and safe to poll, and the store
is on disk, so a worker that dies mid-run loses its turn, not the run. Report the
run id and the store path in the Ticket rather than pasting a transcript; the
Report is the attachment, the run is the evidence.
Do not start a nested run from inside a run's turn. A worker that evolves a harness which itself starts runs multiplies cost with no ceiling — keep one run per Ticket, and make the second one a follow-up Ticket.
Handing a run off instead of holding the slot¶
A worker's background shell job is killed at 30 minutes; an evolution run is often longer. Start it outside the worker's process group and give the slot back:
bash scripts/dsh-superagent-run.sh --store "$RUN_STORE" -- \
agentdescent --store "$RUN_STORE" evolve spec.json --detach \
--budget 5 --usd-per-call 0.01
# waiting 3f9c1a… round 2 /runs/3f9c1a…
# report /runs/3f9c1a…/waiting.json
--budget needs --usd-per-call: the engine counts calls, and a per-call price
is the only way a dollar figure becomes a stop rule. With one and not the other
the CLI exits 2 before creating anything (budget_usd needs usd_per_call), so
the pair is what makes the run stop itself and write why.
Two stores, one variable: the wrapper's --store is where the report goes, and
the run's store is the CLI's own --store, so pass the same value on both. The
wrapper only sees the store it was given: give it only to the wrapper and
evolve writes to the default store, so the wrapper waits out its deadline,
finds no status of its own where it can look, and reports status: failed with
exit 2 — the child did start, but its status sits in a store this handoff cannot
read, and the read-back below cannot find the run.
It starts the command in a detached tmux session (setsid when tmux is
absent), waits for the run's own status.json, writes waiting.json beside it
with run_id, round, state, run_dir, driver, session and log, and
exits 0 within seconds. Post the run id, the round and the run directory on the
Ticket and end the turn; nothing holds the slot.
The wrapper hands the log path and the run's command to the driver as
arguments rather than splicing them into a shell string, so a --store
containing a quote, a space, $ or ; is used literally instead of being read
as shell syntax (#1109).
A child that exits without leaving a status.json where the wrapper can see it
handed nothing off, and the wrapper says so: when the window closes with the
run's session gone and no new status file, waiting.json carries
status: failed and state: exited, the wrapper exits nonzero, and log names
the worker.log where the child's own reason sits (#1096). That includes a
run that wrote its status into a different store — the child started, this
handoff did not receive it. The window itself is unchanged for the case it
exists for — a run that is alive and has not written its status yet is still
waiting, with exit 0.
A store is reused for every Ticket, so it already holds earlier runs. The
wrapper only reports a status.json that appears after it launches, or one that
changes with a started no older than the launch, so a handoff into a used store
reports found: false until its own run writes one. A file whose started
predates the launch is never reported: that is a run this handoff did not start
— possibly still going and rewriting its own file every round — and naming it
would send the read-back to the wrong run. A caller-owned store, where the store
itself is the run directory, must be the run this handoff starts: the wrapper
takes its changed top-level status.json as this launch's own, so a second live
writer in that directory can be reported as this handoff. The tmux session carries a
per-launch suffix for the same reason: two handoffs into stores both called
runs get two sessions, not one shared, refused name. One live handoff per
store: two launched into one store inside the same wait window both read that
store's waiting.json and the second can report the first's run, so give each
handoff its own store or wait for the first to finish.
Read it back from a follow-up Trigger, a person, or a scheduled check — the
wrapper adds no daemon and no scheduler. --store is a global flag, so it
goes before the verb: after the verb the CLI exits 2 with unrecognized
arguments, and without it the run is looked up in the default store
(~/.agentdescent/runs, or $AGENTDESCENT_HOME/runs), not in the handoff's.
agentdescent --store "$RUN_STORE" status "$RUN_ID" --brief # one line; safe to poll
agentdescent --store "$RUN_STORE" show "$RUN_ID" # the artifact, once there is one
Measured against a handoff of a fake run, a second in — status keeps it to
one line, and show reports the gap instead of inventing a result:
$ agentdescent --store "$RUN_STORE" status fake-run-1 --brief
fake-run-1 running round 2 calls=0 skill_dir:./skill
$ agentdescent --store "$RUN_STORE" show fake-run-1
run_id: fake-run-1
state: running
note: no result yet
What the wrapper changes, and what it cannot:
| failure | what happens |
|---|---|
| the worker's turn ends, or its background job is killed | with the --detach above, the run is in its own session — not the worker's process group, and not the wrapper's tmux session either, which holds only the launcher — so it keeps going when either ends |
no tmux on the host (setsid fallback) |
survives the group kill, not a reboot; the run directory is still the handoff |
| the host restarts | the run directory reads failed; agentdescent resume <run_id> continues it |
| an orphan outlives the Ticket | agentdescent --store "$RUN_STORE" cancel <run_id> sends SIGTERM to the run's process group; tmux kill-session -t <session> only stops the wrapper's own launcher, because a --detach run is not in that session |
| the budget runs out | the run stops itself and writes why into its status; the follow-up reads it, nobody is waiting |
7. The check¶
It exits 0 when both rows compose, doctor answers, and an offline text
pilot writes nothing outside its temp run directory. Without dsh it prints a
skip line and exits 0; set DSH_SUPERAGENT_REQUIRED=1 to make a missing host
an error (useful in CI on a machine that is supposed to have it).
Related¶
#903— hosts could not reach the offline demo; the--kind textpath above is the workaround this page relies on.#918—doctorreportedokfor a launcher that could not start; step 3 checks the rows, not just the exit code.- Use it from your agent — the same composition for the other
hosts, including the
webprofile this page is derived from.