dsh-pi-subagent
English | 中文
A DeepSeek Harness (DSH) bundle that turns a local Pi coding agent into an out-of-process subagent with an inspectable child session. DSH's model hands a development task to Pi the same way it hands one to the official Codex or Claude Code subagents, gets Pi's answer back, and can afterwards open the run as a real, read-only DSH child session: the task text, Pi's replies with their token usage, and how the run ended.
The plugin registers its own pi tool (it no longer needs
@deepseek-ai/dsh-tool-subagent)
and runs one pi-dev child per call. The child session is created before the process
starts, and Pi's structured JSON-mode events are then projected line by line as they
arrive: reasoning, replies, tool calls and their results, one step per model call, with
real timestamps. The parent's catalog row is appended up front too, so the child appears
in DSH's subagent list while the task is still running and opens as read-only history.
The thin shell
The plugin deliberately owns almost nothing about how Pi runs. That stays inside the
pi-dev wrapper:
- a throwaway
PI_CODING_AGENT_DIRper run, so~/.piis never touched; - the credential handoff from Pi's own
auth.jsoninto the environment (never printed); - the fixed rules prepended to every brief;
- the pinned model (
deepseek-flashby default); - Pi's session storage: the plugin passes
--session-idand--session-dir, so a delegation can be continued with Pi's own memory; a wrapper called with no id still runs--no-session; --logtee'ing the full output to a file (the plugin asks for it only inlogMode: "full");- one line appended to the delegation record after every run.
The plugin itself only does two things:
- run the delegation — validate the arguments, write the brief to a scratch
directory, spawn
pi-dev(plainnode:child_process, no seam needed), parse its stdout as NDJSON incrementally, keep only the stderr tail for diagnostics, escalate SIGTERM → SIGKILL on cancellation, and take the final answer from Pi's last non-empty assistant message; - project the run live — create a real DSH child session (
sessions.prepare+sessionPersistence.create+enter/announce) and append its opening events plus the parent'ssubagent/catalogrow before spawning the child, then stream one event per Pi record:step/start…step/endper model call,assistant/messagewith reasoning/text/tool-call blocks,tool/call+tool/resultfor every tool execution, and aturn/endwith the run's real reason; finally flush both sessions (a retained child stays open so a later call can append another turn, until the plugin unloads).
It imports no @deepseek-ai/* package and has no runtime dependencies — only node:
built-ins. DSH injects the tools, sessions, and sessionPersistence services. Every
projection step is best-effort: if a service is missing or an append is rejected, the
plugin logs one warning and still returns Pi's answer.
Requirements
- Node.js
^22.19.0 || >=24.0.0and DSH>= 0.2.2-rc.1. - Pi CLI installed and usable as
pi(or viaPI_BIN). - A
pi-devwrapper — the bundledbin/pi-dev(see below), or any executable named through thecommandconfig field (default~/.dsh/bin/pi-dev).
The pi-dev contract
The plugin knows nothing about Pi's arguments; it only knows this contract:
| Part | Meaning |
|---|---|
--brief <file> |
Path to the brief. Always passed. The file holds the task text. |
--cwd <dir> |
Working directory for the child. Always passed; also the child's process cwd. |
--log <file> |
Full-output log file. Passed only in logMode: "full"; the parent directory may not exist yet. |
--model <name> |
Optional, passed only when configured. |
--thinking <level> |
Optional, passed only when configured. |
--tools <list> |
Optional, passed only when configured. |
--mode <text|json> |
Passed as --mode json while session projection is on (the default) and the wrapper's own --help advertises the flag. No --mode is passed when projection is off or the help text does not mention it, so the wrapper keeps its text behaviour (see Session projection). |
--session-id <id> |
The Pi session to continue (created when absent). Always passed together with --session-dir; --no-session is never passed alongside it. |
--session-dir <dir> |
Where Pi stores and looks up that session. |
--help |
Probed once per projected run (stdin ignored, short timeout) to decide whether --mode json is safe to pass. |
--approve |
Optional, passed only when configured. |
| anything else | config.args, appended last, verbatim. |
| stdout | The final answer. DSH returns it to the parent agent as the subagent output. |
| exit code | 0 means success (completed). Anything else means error, and stderr becomes the diagnostic (tail-kept within 4096 bytes). |
| stderr | Free-form progress and errors; never treated as the answer. |
A minimal wrapper that satisfies the contract:
#!/usr/bin/env bash
# ~/.dsh/bin/pi-dev — one Pi run per delegation.
set -euo pipefail
PI_BIN=${PI_BIN:-pi}
brief="" cwd="$PWD" log="" session_id="" session_dir=""
model="" thinking="" tools="" mode="text" approve=0
while [ $# -gt 0 ]; do
case "$1" in
--brief) brief=$2; shift 2 ;;
--cwd) cwd=$2; shift 2 ;;
--log) log=$2; shift 2 ;;
--session-id) session_id=$2; shift 2 ;;
--session-dir) session_dir=$2; shift 2 ;;
--model) model=$2; shift 2 ;;
--thinking) thinking=$2; shift 2 ;;
--tools) tools=$2; shift 2 ;;
--mode) mode=$2; shift 2 ;;
--approve) approve=1; shift ;;
*) echo "pi-dev: unknown argument: $1" >&2; exit 2 ;;
esac
done
[ -n "$brief" ] || { echo "pi-dev: --brief is required" >&2; exit 2; }
args=(--print)
if [ -n "$session_id" ]; then
args+=(--session-id "$session_id" --session-dir "${session_dir:-$HOME/.dsh/pi-sessions}")
else
args+=(--no-session)
fi
[ "$mode" = text ] || args+=(--mode "$mode")
[ -n "$tools" ] && args+=(--tools "$tools")
[ -n "$model" ] && args+=(--model "$model")
[ -n "$thinking" ] && args+=(--thinking "$thinking")
[ "$approve" = 1 ] && args+=(--approve)
prompt=$(cat "$brief")
cd "$cwd"
if [ -n "$log" ]; then
mkdir -p "$(dirname "$log")"
set +e
"$PI_BIN" "${args[@]}" "$prompt" 2>&1 | tee "$log"
exit "${PIPESTATUS[0]}"
fi
exec "$PI_BIN" "${args[@]}" "$prompt"
Add whatever your own workflow needs on top — rules, a state directory, a model pin. Keep
the contract above intact and the plugin needs no change. A wrapper that does not
advertise --mode in its --help (or ignores the flag and prints plain text) still works:
the plugin runs it in text mode, keeps the whole stdout as the answer, and degrades the
projection (see Session projection).
Bundled pi-dev wrapper
bin/pi-dev is a portable copy of the wrapper this plugin was developed against.
package.json declares it as a bin, so a package manager that installs this package links
it as pi-dev. It keeps the contract above (including --mode text|json) and adds the
author's workflow:
- a throwaway
PI_CODING_AGENT_DIRper run, so~/.piis never touched; - the DeepSeek key from
$HOME/.pi/agent/auth.jsonplaced inDEEPSEEK_API_KEY(never printed; an existingDEEPSEEK_API_KEYwins), with api auth login deepseekhint when it is missing; rules/PI-DEV-RULES.mdprepended to the brief — these are the author's own working rules, not something the plugin needs; if you use your own wrapper or do not want them, ignore that file and this wrapper;deepseek-flashpinned as the model and a default tool list;--session-id <id>/--session-dir <dir>continue (or create) that stored Pi session instead of adding--no-session; with no--session-dirthe wrapper uses$PI_DEV_SESSION_DIRor$HOME/.dsh/pi-sessions, and with no--session-idit keeps the old--no-sessionbehaviour;--mode text|jsonpassed through to Pi:textis the default and adds no--modeat all,jsonmakes Pi emit its NDJSON event stream (what the plugin asks for while projection is on);--logtee'ing the full output;- one line per run appended to the delegation record
(
${PI_DEV_RECORD_DIR:-$HOME/.dsh}/pi-delegations.log); - the child's exit code passed through unchanged.
| Variable | Default | Meaning |
|---|---|---|
PI_BIN |
pi (from PATH) |
The Pi executable to run. |
PI_DEV_RULES |
<wrapper's real dir>/../rules/PI-DEV-RULES.md |
Fixed rules file to prepend (symlinks to the wrapper are resolved first). |
PI_DEV_RECORD_DIR |
$HOME/.dsh |
Directory for pi-delegations.log. |
PI_DEV_MODEL |
deepseek-flash |
Default model pin. |
PI_DEV_SESSION_DIR |
$HOME/.dsh/pi-sessions |
Default storage for --session-id when --session-dir is omitted. |
The plugin's default command is still $HOME/.dsh/bin/pi-dev. To use the bundled
wrapper, either copy it there or symlink it (the wrapper resolves its own real path, so
the bundled rules/PI-DEV-RULES.md is still found) or point command at the bundled path, for example
<...>/node_modules/dsh-pi-subagent/bin/pi-dev. If you already have your own pi-dev,
point command at that instead; the contract above is all the plugin needs.
Install
This package is a DSH bundle: package.json declares
dsh.bundle.patch = ./cordis.patch.yml, so installing the package is enough — the patch
mounts the plugin, which registers the pi tool and projects child sessions, and it shows
up as a card under Plugins → Installed in the web app.
# from npm
dsh plugin --profile web add dsh-pi-subagent
# from GitHub
dsh plugin --profile web add git+https://github.com/A1311981684/dsh-pi-subagent.git
# from a local checkout
dsh plugin --profile web add file:/path/to/dsh-pi-subagent
Or add it to the profile manifest ~/.dsh/profiles/<name>/package.json and let the profile
resolve it from its own node_modules:
{
"dependencies": {
"dsh-pi-subagent": "git+https://github.com/A1311981684/dsh-pi-subagent.git"
},
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-pi-subagent"]
}
}
}
After installing, restart DSH (or let HMR reload). The model gains a pi tool. No extra
environment variable is needed as long as pi-dev can find Pi's credentials itself.
If you would rather compose the rows by hand — for example to set config values — add them
to the profile's own cordis.patch.yml. One row is enough; the plugin registers its own
pi tool, so nothing from @deepseek-ai/dsh-tool-subagent is needed:
- insert:
- id: subagent-pi
name: dsh-pi-subagent
config:
# command: /usr/local/bin/pi-dev
# model: deepseek-flash
# tools: read,bash,edit,write,grep,find,ls
# logDir: /home/me/.dsh/pi-logs
# logMode: summary
# sessionDir: /home/me/.dsh/pi-sessions
# graceMs: 5000
# projection: true
Configuration
All fields are optional; the bundle patch passes none of them.
| Field | Default | Description |
|---|---|---|
command |
$HOME/.dsh/bin/pi-dev |
The wrapper to execute. Set it when yours lives elsewhere. |
args |
[] |
Extra arguments appended after everything else. |
model |
— | When set, passed as --model; otherwise the wrapper decides. |
thinking |
— | When set, passed as --thinking. |
tools |
— | When set, passed as --tools. |
approve |
false |
When true, passes --approve. |
projection |
true |
Project each run into a DSH child session. false skips the projection entirely and passes no --mode to the wrapper. |
labelPrefix |
pi · |
Prefix added to every new child session's label, so Pi rows are recognizable next to rows from other backends. Set to '' to disable it. It only affects rows created after it is set; existing catalog rows, and rows written by pi_recover_legacy, keep their old labels. |
recoverLegacy |
false |
Register the maintenance tool pi_recover_legacy, which backfills legacy mode: "external" delegations into real child sessions. Off by default; see Legacy delegation backfill. |
logMode |
summary |
summary (default) writes a compact log itself: task first line, final answer, one line per tool, usage/stop reason/session. full asks the wrapper to tee the whole output (--log), which in JSON mode is the raw event stream and can be tens of MB. |
logDir |
$HOME/.dsh/pi-logs |
Where logs go, named <YYYYMMDD-HHmmss>-<id 8 chars>.log. |
sessionDir |
$HOME/.dsh/pi-sessions |
Where Pi stores the sessions a continuation reuses; passed as --session-dir. |
graceMs |
5000 |
SIGTERM → SIGKILL grace for a cancelled child. |
maxOutputBytes |
262144 |
In-memory cap per collected stream (stdout and stderr separately); the tail is kept. |
Validation happens at mount time, so a bad value is a load error rather than a surprise on
the first delegation: graceMs and maxOutputBytes must be positive finite numbers,
command, logDir, and sessionDir must be non-empty strings, logMode must be
"summary" or "full", args must be an array of strings, approve/projection/
recoverLegacy must be booleans, and labelPrefix must be a string without control
characters (an empty string is allowed).
Session projection
Every delegation also produces a real DSH child session (phase 2: live, streamed projection). The child is created in the calling agent's session first, then Pi is started, and each JSON record is projected as it arrives:
sessions.prepare(childId, { meta })with the child'scwd,parentSession,origin: 'subagent', anddelegationDepth(the parent's depth + 1), thensessionPersistence.create(session.header, { inheritedEventCount: 0 }), the pre-publication suffix,enter, andannounce— the same orderdsh-agent-loopuses;- the child's opening events, still before the process exists:
turn/start(DSH turn 1),subagent/descriptor(version 3,mode: 'one-shot',provider: 'pi', the label), and the task text asuser/message; the parent'ssubagent/catalogrow (version 0) follows immediately, so the child is listed while Pi works; - stdout is parsed line by line (a partial line is buffered; a line over 2 MiB is dropped
with a warning) and each record becomes one event:
turn_startopens a new step (step/start) — one Pi turn is one model call, so it maps to a DSH step, not a DSH turn;- an assistant
message_endappendsassistant/messageinside the current step, withthinkingmapped toreasoningblocks, text kept,toolCallmapped totool-call(its arguments serialized once to the raw JSON string DSH stores), the step'susage, and an emptystream; every advertisedtool-callis then answered by atool/callcarrying the identical argument string; tool_execution_endappendstool/resultwith the tool's text (or its serialized structured content),isErrorpassed through, on the surface;turn_endcloses the step — any call still pending gets an error result first, so a step never closes with an unresolved call;agent_end/agent_settledjust mark the run's abort flag; theturn/endwith the real reason (completed,aborted, orerror) is appended once the child exits;
- both sessions are flushed; the child is then kept live (not detached, handle open) so a later call can append the next turn, and it is released when the plugin unloads.
The order is not cosmetic: the durable log is relationship-checked when it is restored. A
step/end is rejected while an advertised tool/call has no tool/result, a turn/end is
rejected while a step is open, tool/call arguments must equal the tool-call block's
string exactly, and step numbers must run 1, 2, 3… inside the open turn. Normal end,
failure, and cancellation all funnel through the same finalizer, so the log always has
matched brackets and a turn/end.
What you can see: the child row in DSH's subagent list from the moment the task starts, and
when you open it, the task text, Pi's reasoning and replies, the tool calls with their
arguments and results, each step's token usage (inputTokens/outputTokens plus the
cache/reasoning counters Pi reported), real timestamps/durations, and how the run ended.
Because the log is durable, this survives a DSH restart.
Limitations.
- No independent Stop for a child. Cancelling the delegation in the main conversation
aborts the tool call, which SIGTERMs Pi (SIGKILL after
graceMs) and closes the child's turn asaborted; that is the only supported stop. The UI renders a child session as read-only history and offers no per-child stop control. An independent Stop needs the continuable-activation form, so it is deliberately left for a later phase. - Retained sessions stay live until unload. That is what makes reuse possible, so DSH shows the child row while it is retained. A DSH restart ends continuability: the plugin only knows the sessions it opened in this process.
Degradation. The projection is best-effort and never affects the delegation:
--modesupport is detected up front by runningpi-dev --helponce (stdin ignored, short timeout); a wrapper whose help does not mention--modeis run in text mode: the projection gets the task text, one assistant message holding the whole stdout, and the end state, still with real timestamps. A run is never attempted twice;- if
sessions/sessionPersistenceis missing, orprepare/create/the opening appends are rejected, the plugin logs onewarnand returns the result with an emptychildSessionId; - if an append is rejected mid-run, the plugin logs one
warn, stops projecting further content, and still appends the structural closers (step/end,turn/end) so the stored log is not left with an open bracket; - if JSON mode was requested but the wrapper printed plain text anyway, the whole stdout becomes the single assistant message and the projection still records the prompt and the end state;
- a tool result whose call was never advertised is skipped with a
warn; a line over the 2 MiB cap is dropped with awarn.
Session reuse
Every pi result carries session (the child session id). Passing it back on the next call
continues that delegation:
- the same DSH child session gets a new turn (number = last recorded turn + 1) with its own
task text and its own step numbering (steps restart at 1 in each turn); no second
subagent/descriptorand no second parentsubagent/catalogrow; - Pi is started with
--session-id <id> --session-dir <sessionDir>, so Pi's own conversation (files read, decisions, tool history) is still there — the task usually gets cheaper and does not re-read the project; - the child session is retained after each run (flushed, but not detached or closed) until a
later turn or plugin unload, where
ctx.effectreleases the handles; - a session is only continuable inside the host process that opened it. After a DSH restart
the plugin returns a clear error:
session <id> is not continuable in this host process; omit session to start a new one; - only one run per session at a time: a concurrent call fails with
session <id> is already running.
Pi's own session files accumulate under sessionDir; they are not the DSH logs and the
cleanup script does not delete them.
Behavior details
- One
pitool. The plugin registers it at mount time; the description tells the model it delegates to the local Pi agent and that a child session is created. Parameters areprompt(required),cwd(optional; defaults to the calling session's working directory),label(optional; defaults to the first line ofprompt, at most 60 characters includinglabelPrefix), andsession(optional; the child session id from an earlier call, to continue that delegation). - The tool value is
{ output, childSessionId, session, logPath, stopReason }(plusdiagnosticwhen the run failed). The model sees the final answer, an optional diagnostic, asubagent session: <id>line, ato continue this delegation, pass session: <id>hint, and afull output: <log path>line. - Result mapping. Exit code
0→stopReason: 'completed'. Any other exit code →'error', withdiagnosticset topi-dev exit code Nplus the tail of stderr, capped at 4096 bytes. Cancellation throughexec.signal→'aborted'after SIGTERM (and SIGKILL aftergraceMs), keeping whatever output was collected. A spawn failure is an'error'result, never a thrown tool. - The final answer is the text of the last non-empty assistant message Pi reported. If no structured record parses, it is the whole stdout (trailing whitespace trimmed).
- Each new delegation is isolated. It gets its own scratch directory, its own child-session id, and its own process state, so concurrent runs cannot observe each other; a continuation shares its own session by design, and two runs of one session never overlap.
- The scratch directory is always removed, even when the run fails. It holds the brief,
which contains the task text; the log stays in
logDirbecause it is the pointer returned to the model.
Logs and cleanup
logMode (default summary) decides what one delegation writes to
<logDir>/<YYYYMMDD-HHmmss>-<id 8 chars>.log:
summary— the plugin writes the file itself: the task's first line (at most 100 characters), the final answer, onetool <name> <durationMs>ms <ok|error>line per tool, and one line with the summed usage,stopReason, and child session id. Usually a few KB.full— the wrapper is asked to tee Pi's whole output (--log), which in JSON mode is the raw event stream and can reach tens of MB on a long task.
The tool's logPath always names the file that was actually written (empty when the summary
write failed). Old logs are never removed automatically:
node scripts/cleanup.mjs [--days 14] [--dry-run] [--sessions]
It deletes $HOME/.dsh/pi-logs files older than N days and prints the count and the freed
space; --dry-run only lists them. --sessions additionally lists (never deletes) old
session directories under $HOME/.dsh/sessions that contain session.v4.jsonl.zstd, with
the caveats that deleting sessions is an out-of-band operation, DSH should be stopped first,
and the sqlite index may keep stale rows. The candidates include parent and child sessions
(the origin is inside the compressed log, so the script does not try to tell them apart).
Legacy delegation backfill (maintenance)
Before session projection existed, a delegation was only a mode: "external" row in the
parent's subagent/catalog: there is no child session behind it, so DSH's subagent panel
cannot open it. The optional pi_recover_legacy tool backfills those rows with one new
read-only child session each:
- Candidates — every
mode: "external"catalog row, plus any child id passed inids(for example a one-shot session whose projection kept only the user message). - Content — the old log found by child-id prefix in
logDir. A plain-text log is used as-is; a JSON event stream contributes its last non-empty assistant text, plus a tool summary appendix. A missing log still creates the session, with a "log missing" notice. The content is capped at 1 MB, keeping its tail and saying it was truncated. - Idempotent — a legacy row that already has a backfill catalog row
(
(回填 <old id first 8>)…) is skipped, so the tool can be run again.dryRun: trueonly reports what would be recovered.
The tool is registered only when recoverLegacy: true, so a normal install never exposes
it. To run it once on one machine, add the flag to the profile patch
(~/.dsh/profiles/web/cordis.patch.yml), reload DSH, call the tool, then remove the flag
and reload again:
- insert: [{ id: subagent-pi, name: dsh-pi-subagent, config: { recoverLegacy: true } }]
Old catalog rows cannot be deleted, so they stay as-is next to the backfilled ones.
Development and testing
git clone <repo> && cd dsh-pi-subagent
node --check lib/index.js
bash -n bin/pi-dev
node --test test/ # 50 unit tests, all green, no network and no model call
node test/real-pi.mjs # opt-in: one real pi-dev run, costs a model call
test/tool.test.jsmounts the plugin on a fakectx(tools.register,sessions,sessionPersistence,logger) and runs real child processes:test/fake-pi-dev.mjsis copied into the scratch root as the configuredcommandand reads itsFIXTURE/RECORDdirectives from the brief, so every test controls the child's stdout, stderr, exit code, and timing while the plugin's argv, brief, and child-session events are asserted exactly. Covered: tool registration and schema, argv building, argument andcwdvalidation, the--helpcapability probe (JSON vs. text mode), the streamed projection event order and payloads (descriptor v3, catalog v0 strict keys, step brackets, reasoning/text/tool-call blocks,tool/call/tool/resultpairing and argument identity, usage mapping,stream: []), multi-turn step numbering, plain-text and empty-stdout degradation, error/abort end states (including a pending call resolved on cancel), SIGKILL escalation, missing-service and rejected-append degradation, an oversized line, concurrent runs, config validation, HOME-derived defaults, and scratch-directory cleanup; the phase-3 cases cover the compact and full log modes, session continuation (turn numbering, no duplicate descriptor/catalog, Pi session argv), unknown and concurrentsessionids, and the unload effect.test/cleanup.test.jsrunsscripts/cleanup.mjsagainst a temporary$HOME:--dry-runnever deletes,--daysfilters, deletion keeps fresh files, and--sessionsonly lists.test/recover.test.jsmounts the plugin withrecoverLegacy: trueon a fake parent whosesnapshotEvents()returns legacy catalog rows, and checks: the tool is absent by default; a new read-only child session per candidate with the v4 event order and exact catalog payload; text vs. JSONL log recovery (last assistant text plus tool appendix); the missing log notice; idempotent skips;dryRunwriting nothing; and one rejected row not stopping the rest.test/pi-dev.test.jsexecutes the bundled wrapper with a fakePI_BINand checks the Pi argv:--session-id/--session-dirreplace--no-session, the default session directory, and the unchanged--no-sessionbehaviour when no id is given.test/real-pi.mjsis the manual end-to-end check: a realpi-devrun whose brief asks for one line of text with--tools readand no file changes. It has no DSH container, so it also exercises the "projection unavailable → warn and continue" path. It exits as a no-op whenNODE_TEST_CONTEXTis set, sonode --testnever spends a model call on it.test/index.jsexists only so the documentednode --test test/command works on Node versions that resolve a positional argument as a module instead of searching the directory. The equivalent form isnode --test test/*.test.js..github/workflows/test.ymlruns the syntax check and the unit tests on Node 22 and 24.
License
MIT © 2026 Asta Zhao
No comments yet. Be the first to write one.