* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| Six model-facing persistent terminal tools with owner isolation, bounded results, and optional background sends for agents that need cross-call terminal state. | package-reference |
@deepseek-ai/dsh-tool-terminal
English | 中文
Summary
Use dsh-tool-terminal when an agent needs persistent terminal state or interactive input across calls. It can open, send to, read, signal, close, and list terminal sessions while preventing one agent from operating another agent's sessions. Sends may wait for bounded foreground output or return a background job id for later collection or interruption. maxResultBytes caps each result, which remains in session history until compaction. The model is guided to prefer one-shot tools for bounded work.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
terminal_open defaults to the Session's current working directory and resolves relative cwd overrides from it. Open terminals keep their own directory after the Session changes directory.
Enable these tools when the composition mounts a terminal backend and the model should be able to use terminal state across calls — stepping a debugger, exploring in a REPL, or returning to a shell after interrupting a foreground command. The guidance section steers the model toward the one-shot bash, read, write, and edit tools for bounded operations.
The six tools
| Tool | What it does | Result |
|---|---|---|
terminal_open |
Creates an owner-scoped session from a backend type | Session id, name, type, pid, status, and bounded startup output |
terminal_send |
Writes text, optionally submitting Enter, and waits for readiness — or starts a background job | Bounded output plus wait and session status, or a job id |
terminal_read |
Reads a bounded page of retained output without sending input | Text with line pagination metadata |
terminal_signal |
Delivers one allowed signal to the foreground process group | delivered plus the target process group id |
terminal_close |
Closes a session and waits for its process tree to end | Closed or already-closing outcome |
terminal_list |
Lists the caller's live sessions | Owner-scoped session summaries |
Composition
- name: '@deepseek-ai/dsh-terminal'
- name: '@deepseek-ai/dsh-terminal-bash'
- name: '@deepseek-ai/dsh-tool-terminal'
The tools need ctx.terminals — a backend must be mounted — and the system-prompt service for the guidance section. Background sends additionally require the jobs service and its model-facing controller (@deepseek-ai/dsh-tool-jobs).
Configuration
| Field | Default | Meaning |
|---|---|---|
enableRunInBackground |
true |
Expose and accept run_in_background; false removes the schema field and rejects the argument |
maxResultBytes |
262144 |
UTF-8 cap (minimum 64) for each complete terminal result after wait, session, pagination, truncation, and job-status metadata |
The generated configuration catalog and tool catalog are the exhaustive sources for config fields and schemas.
Background sends
terminal_send(run_in_background: true) returns a job id immediately instead of waiting. The job is collected with job_output, which waits and reads incremental output, and stopped with job_kill, which delivers a real SIGINT to the foreground process group. Background mode fails before writing input when the jobs surface is absent.
Observable outcomes and failures
A foreground send returns the terminal's new output plus wait: <reason> and the session status; session_exit means the top-level shell exited, while inferred_idle or timeout never proves the foreground command exited. Opening a session with an unregistered backend type fails. Results larger than maxResultBytes are truncated at a UTF-8 boundary with a marker.
Understand the implementation
Implementation internals — click to expand
This section explains the design behind the tools and points at the code that realizes it; the observable behavior is covered in Use this package.
Design concept
The package is a thin adapter: the six tools forward to ctx.terminals with the executing agent as the owner, and the presentation layer renders bounded results. Background sends register the in-flight operation on ctx.jobs so the generic job surface owns waiting, incremental reads, and SIGINT delivery.
Source map
| File | Role |
|---|---|
src/index.ts |
Six tool definitions, schemas, guidance section, background-job integration |
src/render.ts |
Result rendering and the complete-result UTF-8 cap |
Result bounding
Every terminal-owned single-text result is capped by maxResultBytes after normalized tool or pipeline errors, policy denials and short-circuits, replacements and blocks, and generic job-status text; cuts preserve UTF-8 boundaries and reserve room for a truncation marker. Structured multi-block policy results retain their shape. The minimum cap of 64 bytes keeps every registry-issued session or job id visible in its creation acknowledgement.
UI render intents
Foreground sends use terminal call and result cards; background sends and the other five tools use generic execute, read, or delete cards. None of the tools emits source locations.
Further Exploration
Read these pages when the package-level contract is not enough. They move from the generated schemas to the service contract, the backend, and the background-job surface.
- Tool catalog — the six generated schemas and result shapes.
- Terminal subsystem reference — the service contract and shared types behind the tools.
- terminal service — session operations, owner fencing, and cleanup semantics.
- terminal-bash backend — the shipped shell backend that provides sessions.
- jobs package map — the background-job surface that collects and kills background sends.
- Persistent PTY Agent Note — the capability design and deferred boundaries.
Model Experience
System prompt
What the model sees
The plugin contributes this fixed guidance section:
Terminal guidance
Use a terminal session only when work needs persistent terminal state or interactive stdin; prefer shell/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-terminal catalog section. 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 startup output. Send and read return bounded terminal text plus readiness and history markers. Background mode returns a generic job id. Every terminal-owned single-text result is capped by maxResultBytes; results remain in session history until compaction, and incremental task reads do not repeat consumed output.
Token effect
Terminal-owned results are data-dependent and bounded by maxResultBytes; each returned result stays in history until compaction.
KV Cache effect
Append-only; new results follow the reusable request prefix.
Known Limitations and Deferred Work
These limits define the model-facing surface that is absent. They are current package constraints, not a task backlog.
- No TUI or key-sequence surface — named key sequences, full-screen TUI interaction, BEL, resize, and auto-start are not exposed in any schema.
- Background mode requires the jobs surface —
run_in_backgroundneeds both@deepseek-ai/dsh-jobsand its model-facing controller (@deepseek-ai/dsh-tool-jobs); without them the argument is rejected.
Dev Note
Working context for maintainers — click to expand
None.