Renderers such as errorChain and the activation report expand AggregateError members but otherwise follow only cause, so a cause of just the setup failure hid the cleanup failure that may leave resources alive. The cause is now an AggregateError of both failures. An upgrade guide records that the class extends TerminalError instead of AggregateError. INIT_REJECTED is documented as the code a consumer that drives a shell uses when the shell rejects its setup input, and the persistent bash tool README records it. Refs #7869
description, kind
| description | kind |
|---|---|
| Package map for the persistent terminal service and the shell backend that starts interactive bash or pwsh. | package-group |
terminal/ — persistent PTY capability family
English | 中文
Summary
The terminal/ family lets agents keep interactive shell and REPL sessions alive across tool calls, including the working directory, environment variables, and running child processes. Use terminal/ for owner-isolated session management, terminal-bash/ for sandboxed interactive bash or pwsh sessions. Choose this family when a task needs interactive input or state that a one-shot bash command cannot retain. Sessions remain local to one harness process and do not survive a restart.
Table of Contents
Packages
This group contains one session service and one shell backend. Each child README owns the full contract; the subsystem reference owns the shared vocabulary and the generated service surface.
| Package | Role | ctx key |
|---|---|---|
terminal/ |
Session service: owner-scoped sessions with opaque ids, exact-owner fencing, and awaited cleanup | ctx.terminals |
terminal-bash/ |
Shell backend: interactive bash or pwsh under the shared sandbox policy, with readiness detection and bounded output | registers a backend on ctx.terminals |
Related documentation
Start with the subsystem reference for the shared types and the service surface, then the Agent Note for the design rationale and deferred boundaries.
- Terminal subsystem reference — ids, backend and session contracts, send readiness, bounded reads, and the generated
ctx.terminalsAPI. - Persistent PTY Agent Note — the design decision, alternatives, and deferred work.
- Capability seams — the Service Definition / Service Provider / Consumer split this family follows.
See tool-terminal for the experimental optional capability.
Dev Note
Working context for maintainers — click to expand
None.