dsh-pi-compatible
English | 中文
Two Full Access-only DeepSeek Harness agent presets whose core tool contract is frozen to @earendil-works/pi-coding-agent 0.84.2.
- Pi-compatible Core exposes exactly seven lower-case tools:
read, bash, edit, write, grep, find, and ls.
- Pi-compatible Plus exposes the same core plus explicit DSH-backed Web, Task, Todo, Plan, Think, Slash, and compaction capabilities.
The presets use DSH's filesystem, subprocess, attachment, session, cancellation, model-routing, and presentation seams. They are designed and tested only with the danger-full-access permission preset; they do not implement escalation workflows for narrower policies.
Product contract
Core tools
| Tool | Pi-compatible behavior |
|---|
read(path, offset?, limit?) | Head truncation at 2,000 lines or 50 KiB, offset continuation, a 64 MiB whole-file safety cap, and PNG/JPEG/GIF/WebP/BMP handling subject to DSH attachment capabilities |
bash(command, timeout?) | Fresh real Bash process per call, no persistent state, no default timeout, tail truncation with a private full-output spill file |
edit(path, edits[]) | Original-file matching, unique non-overlapping edits, Pi-style fuzzy punctuation fallback, BOM and CRLF/LF preservation, one guarded atomic write |
write(path, content) | Complete UTF-8 write through DSH; missing parent directories are created by the DSH local filesystem backend |
grep(...) | ripgrep JSON search, default 100 matches, 500-character line clipping, optional context/glob/literal/case control |
find(pattern, path?, limit?) | fd glob search, default 1,000 results, .gitignore-aware relative paths |
ls(path?, limit?) | One directory, dotfiles included, case-insensitive sort, / after directories, default 500 entries |
All seven tools are visible by default. This intentionally differs from Pi 0.84.2's default four-tool activation (read, bash, edit, write): DSH does not reproduce Pi's dynamic tool-activation mechanism.
Plus extensions
pi-compatible-plus additionally registers:
WebFetchWebSearchTaskTodoWriteExitPlanModeThinkSlashCommand/plan/compact- DSH basic compaction and tool-result pruning
These are DSH-backed extensions, not Pi 0.84.2 core tools.
Install
Install the bundle into the DSH Web profile:
dsh plugin --profile web add kingguuu8-svg/dsh-pi-compatible
Or install a local checkout:
dsh plugin --profile web add .
The bundle installs both presets into:
${DSH_HOME:-~/.dsh}/.agent-presets/pi-compatible/
${DSH_HOME:-~/.dsh}/.agent-presets/pi-compatible-plus/
Installation is idempotent and does not overwrite a complete existing preset. Set force: true on the bundle row in the profile patch to replace packaged files during an upgrade. A forced 0.1.x → 0.2.0 migration also removes the known package-owned legacy modules from the Core directory; unrelated user files are preserved.
After installation, create a new session and choose Pi-compatible Core or Pi-compatible Plus.
Runtime configuration
| Variable | Meaning |
|---|
PI_COMPAT_BASH_PATH | Absolute path to the real Bash executable |
PI_COMPAT_FD_PATH | Absolute path to fd |
PI_COMPAT_RG_PATH | Absolute path to rg |
PI_COMPAT_OFFLINE=1 | Disable fd/rg network download |
PI_OFFLINE=1 | Pi-compatible alias that also disables fd/rg download |
DSH_HOME | DSH home and the private pi-compatible/bin cache root |
Bash resolution follows Pi's platform intent: on Windows, Git Bash under Program Files is preferred before PATH Bash. PowerShell is never silently presented as bash.
fd and rg resolution is:
- explicit environment override;
- system executable on PATH;
- cached executable under
<DSH_HOME>/pi-compatible/bin;
- latest compatible GitHub release download, unless offline mode is enabled.
When GitHub publishes a SHA-256 asset digest, the downloader verifies it. Downloaded files and extraction directories are private to the current user.
Persona customization
The default persona is intentionally short and direct. To customize it, copy the preset to a new id and edit that copy's agent.cordis.yml. Tool compatibility is the stable product contract; persona text is not.
Compatibility boundaries
- Pi baseline is permanently frozen to
0.84.2 for this product line.
- Compatibility means schema and key behavior, not byte-identical error messages or Pi's TUI rendering.
- DSH owns path authorization, filesystem publication, subprocess-tree cancellation, attachments, sessions, and UI cards.
- BMP is recognized, but DSH rc.6/rc.7 attachments do not accept BMP;
read returns a conversion instruction instead of an image block.
- Pi resizes large images to 2,000×2,000. DSH's attachment seam has no resize operation, so supported images are stored at their original dimensions and the deviation is disclosed in the tool result.
- Text
read rejects files above 64 MiB before whole-file decoding. Grep context expansion skips files above 10 MiB. These safety bounds prevent one tool call from exhausting the long-lived DSH host.
- Windows is the release-blocking platform. POSIX paths remain supported on a best-effort basis.
- The preset shadows only the model-facing
sandbox:policy and approval:policy runtime-context prose because it duplicates the Full Access contract and mentions tool parameters that do not exist in Pi. DSH enforcement remains active, and all other runtime contexts remain available.
- The preset does not reject a narrower DSH permission mode at mount time. Such modes are unsupported; host denial is reported directly and the model is instructed not to request escalation.
Development
npm run check
npm test
npm run test:integration
- Unit tests use DSH seam mocks and require no LLM API key.
test:integration uses the globally installed DSH rc.6 local filesystem and subprocess packages, executes real Git Bash, and exercises downloaded/cached fd and ripgrep.- The running DSH Web host is separately validated by creating blank Core and Plus sessions through
session.create; no model request is required for mount validation.
Trust
A user preset is a Cordis composition and has the authority of the plugins it loads. This bundle is intentionally Full Access-only and can execute arbitrary Bash commands and modify arbitrary files allowed by the host process. Review the source before installation.
License
MIT. See THIRD_PARTY_NOTICES.md for the Pi 0.84.2 behavior reference.
