NI0317
a7bfade7eb
Rename the six model-facing tools pty_* -> terminal_* and align every description, guidance section, ACP card title, and rendered result to terminal terminology. Package and service internals keep their technical PTY names (PtyService, "unknown PTY session", node-pty). Harden the local backend teardown: - a failed close is retryable: drop the memoized rejection so a later terminal_close re-runs against the live process table - service disposal clears the backend, reservation, and owner-cleanup registries even when a close fails - stop readiness polling before teardown so an in-flight send settles as session_exit instead of a mis-inferred wait reason - bound the sanitizer's pending buffer against unterminated escape runs Update the tool catalog, package READMEs, the bilingual Agent Note, and the acp/headless pty-tools snapshots to match.
61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
# @deepseek-ai/dsh-tool-pty
|
|
|
|
Six model-facing tools over `ctx.pty`: `terminal_open`, `terminal_send`, `terminal_read`, `terminal_signal`, `terminal_close`, and `terminal_list`. Every operation requires the exact initiating `Agent`, so a model cannot address another agent's terminal even if it learns the id.
|
|
|
|
`terminal_send(run_in_background: true)` reuses `ctx.tasks`; task preflight occurs before any terminal write, completion is collected with `task_output`, and `task_kill` requests `Ctrl-C`. Foreground sends use terminal ACP cards; lifecycle, history, signal, and list calls use generic cards.
|
|
|
|
## Model Experience
|
|
|
|
### System prompt
|
|
|
|
#### What the model sees
|
|
|
|
The plugin contributes this fixed guidance section:
|
|
|
|
##### Terminal guidance
|
|
|
|
```markdown
|
|
Use a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.
|
|
```
|
|
|
|
#### Token effect
|
|
|
|
Small fixed input cost on every request while the plugin is active.
|
|
|
|
#### KV Cache effect
|
|
|
|
Prefix-stable while the registration scope and guidance text are unchanged.
|
|
|
|
### Tool schemas
|
|
|
|
#### What the model sees
|
|
|
|
The six generated schemas are listed in the [`dsh-tool-pty` catalog section](../../../docs/tool-catalog.md#deepseek-aidsh-tool-pty). Their fixed schema tokens are present whenever this plugin is active; agent-scoped tool filtering may hide them.
|
|
|
|
#### Token effect
|
|
|
|
Fixed schema cost on requests where the tools are visible.
|
|
|
|
#### KV Cache effect
|
|
|
|
Prefix-stable while tool visibility and definitions are unchanged.
|
|
|
|
### Tool results and task context
|
|
|
|
#### What the model sees
|
|
|
|
Spawn returns the id and bounded MOTD. Send/read return bounded terminal text plus readiness/history markers. Background mode returns a generic task id. Results remain in session history until compaction; incremental task reads do not repeat consumed output.
|
|
|
|
#### Token effect
|
|
|
|
Data-dependent and bounded by the backend; each returned result remains in history until compaction.
|
|
|
|
#### KV Cache effect
|
|
|
|
Append-only; new results follow the reusable request prefix.
|
|
|
|
## Known Limitations and Deferred Work
|
|
|
|
- No named key sequence, TUI, BEL, resize, auto-start, or cross-agent sharing schema is exposed.
|
|
- Background mode requires both `@deepseek-ai/dsh-tasks` and its model-facing control surface.
|