Tianyi Cui
a2d0f7f411
Apply the accepted pre-release package, service, type, directory, and role renames as one repository-wide change.
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# @deepseek-ai/dsh-tool-bash-persistent
|
|
|
|
English | [中文](README.zh.md)
|
|
|
|
Model-facing `bash(command)` backed by one owner-scoped `ctx.terminals` shell. The package owns the tool contract and shell reuse; deployments select the PTY backend and sandbox policy.
|
|
|
|
## Config
|
|
|
|
| Key | Default | Meaning |
|
|
|---|---:|---|
|
|
| `backendType` | `shell` | Registered PTY backend used for each Agent shell. |
|
|
| `timeoutMs` | `300000` | Wall-clock limit for one command; timeout closes the shell. |
|
|
| `maxOutputChars` | `16000` | Maximum retained command-output characters; fixed diagnostics are added afterward. |
|
|
| `description` | Persistent-shell description | Model-facing environment contract. |
|
|
|
|
## Model Experience
|
|
|
|
### Tool schema
|
|
|
|
#### What the model sees
|
|
|
|
The generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash-persistent), including the configured `description`. The plugin contributes no standalone system-prompt section; the deployment owns persona and environment guidance.
|
|
|
|
#### Token effect
|
|
|
|
Fixed schema cost while `bash` is visible.
|
|
|
|
#### KV Cache effect
|
|
|
|
Prefix-stable while the configured description and schema remain unchanged.
|
|
|
|
### Tool results
|
|
|
|
#### What the model sees
|
|
|
|
Commands share one shell per Agent, so cwd, exported variables, activated environments, functions, and background jobs persist across calls. Results exclude private completion markers and the shell prompt. A nonzero wrapped command appends `[exit code: N]`; a shell that exits before reporting that status instead appends `[shell exited: code N]`, `[shell killed by signal: SIG]`, or `[shell exited]` when the backend supplies neither, then resets and tells the model that the next call starts fresh. Long output keeps the earliest retained prefix plus a clipping notice. If the PTY has already dropped that prefix, the result says so explicitly instead of presenting a tail as complete output. Timeout returns bounded partial output, closes the uncertain shell, and reports the reset.
|
|
|
|
#### Token effect
|
|
|
|
Data-dependent. `maxOutputChars` bounds retained command output; fixed clipping, lost-prefix, status, timeout, and reset diagnostics can extend the result.
|
|
|
|
#### KV Cache effect
|
|
|
|
Append-only tool results follow the reusable request prefix.
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- The tool requires an owning Agent and a real PTY backend.
|
|
- Explicit `exit` and timeout discard shell state. Cancellation also resets and discards the result, even when a complete status marker is already observable; the next call starts a fresh shell.
|
|
- Environment facts such as network access and package mirrors belong in the configured `description`, not this package's default.
|