Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: unwrap hard-wrapped Markdown to one line per paragraph

Browse Source 
Hard line breaks mid-paragraph make docs harder to edit and diff — a
one-word change reflows and re-diffs the whole paragraph. Reflow all
tracked non-vendor Markdown (plus vendor/AGENTS.md) so each prose
paragraph is a single line; soft-wrapping is the editor's job. Fenced
code, tables, and list structure are preserved (wrapped list items fold
to one line per bullet). Documents the convention in AGENTS.md.
This commit is contained in:
Tianyi Cui
2026-06-13 18:39:20 +08:00
parent e98c1c5d42
commit 066f94c7e0
39 changed files with 348 additions and 1206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
packages/bash-local/README.md
View File

@@ -1,9 +1,6 @@
# @deepseek-ai/dsh-bash-local
Local-subprocess implementation of the `@deepseek-ai/dsh-bash` executor seam:
`LocalBashExecutor` spawns `bash -c <command>` per call in its own process
group, collects bounded output with full-stream spill files, and escalates
kills SIGTERM→SIGKILL across the whole group.
Local-subprocess implementation of the `@deepseek-ai/dsh-bash` executor seam: `LocalBashExecutor` spawns `bash -c <command>` per call in its own process group, collects bounded output with full-stream spill files, and escalates kills SIGTERM→SIGKILL across the whole group.
## Config
@@ -19,33 +16,14 @@ kills SIGTERM→SIGKILL across the whole group.
## Behavior (and where it came from)
Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and
pi; the notable choices:
Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi; the notable choices:
- **Spawn per call, no shell state** — every call is a fresh non-login
`bash -c` (deterministic; no rc files). All four surveyed tools spawn per
call. `TODO(stateful-shell)` in `src/run.ts` records the two proven
stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec
sessions) for when real workflows demand them.
- **Process-group kills with escalation** — children are spawned `detached`
(own process group); kills send SIGTERM to the group, then SIGKILL after a
3s grace (OpenCode's escalation; pipelines and subshells die with the
parent). ESRCH is tolerated; daemons that re-parent away from the group can
still survive — same caveat as the surveyed tools.
- **Tail-keep truncation + spill files** — output beyond `maxOutputBytes`
keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode
rationale) while the FULL stream is appended to a temp file whose path is
reported. The model can `grep`/`tail` the spill file with bash itself.
- **Model-friendly env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat`
(Codex's hardcoded set) so pagers and ANSI color don't garble results.
- **Background tasks** — `start()` returns immediately, no timeout applies
(Claude Code detaches timeouts when backgrounding), `readOutput()` is
incremental with whole-stream byte offsets, and disposal kills everything.
- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `TODO(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
- **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after a 3s grace (OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
- **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported. The model can `grep`/`tail` the spill file with bash itself.
- **Model-friendly env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results.
- **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything.
## Sandboxing
`TODO(permissions/sandbox)`: execution policy does NOT belong in this
package. Wrap the `tools/execute` waterfall (veto/ask) or implement a
sandboxing `BashExecutor` — see docs/architecture.md § plugin checklist.
Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap;
Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine.
`TODO(permissions/sandbox)`: execution policy does NOT belong in this package. Wrap the `tools/execute` waterfall (veto/ask) or implement a sandboxing `BashExecutor` — see docs/architecture.md § plugin checklist. Reference points: Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies seatbelt/landlock plus an execpolicy prefix-rule engine.