# Conflicts: # apps/web/tests/expected/agent-preset-selection/header.expected.md # docs/architecture.i18n.yaml # docs/config-catalog.i18n.yaml # docs/config-catalog.md # docs/event-producer-consumer.i18n.yaml # docs/event-producer-consumer.md # docs/event-producer-consumer.zh.md # docs/module-graph.i18n.yaml # docs/module-graph.md # docs/module-graph.zh.md # docs/persistence-catalog.i18n.yaml # docs/persistence-catalog.md # docs/persistence-catalog.zh.md # docs/persistence-schema.json # docs/subsystems/web-client.i18n.yaml # packages/api/README.i18n.yaml # packages/api/README.md # packages/api/README.zh.md # packages/api/session-controller/README.i18n.yaml # packages/api/session-controller/README.md # packages/api/session-controller/README.zh.md # packages/api/session-controller/src/client/sessions/manager.ts # packages/api/session-controller/src/client/sessions/service.ts # packages/api/session-controller/tests/manager.client.spec.ts # packages/client/locale/tests/language-row.client.spec.tsx # packages/client/ui-chat/tests/chat-view.client.spec.tsx # packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx # packages/client/ui-conversation/tests/conversation-registry.client.spec.ts # packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx # packages/client/ui-conversation/tests/input-bar.client.spec.tsx # packages/client/ui-conversation/tests/input-matrix.client.spec.tsx # packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx # packages/client/ui-conversation/tests/skeleton.client.spec.tsx # packages/client/ui-deliverables/tests/deliverables.client.spec.tsx # packages/client/ui-jobs/tests/job-list-action.client.spec.tsx # packages/client/ui-layout/tests/app-frame.client.spec.tsx # packages/client/ui-layout/tests/document-title.client.spec.tsx # packages/client/ui-open-in-app/tests/open-in-app-action.client.spec.tsx # packages/client/ui-primitives/README.i18n.yaml # packages/client/ui-session/tests/ui-session.client.spec.ts # packages/client/ui-settings-general/tests/settings-root.client.spec.tsx # packages/client/ui-settings-unarchive-sessions/tests/components.client.spec.tsx # packages/client/ui-subagent/README.i18n.yaml # packages/client/ui-subagent/README.md # packages/client/ui-subagent/README.zh.md # packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx # packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx # packages/client/ui-theme/tests/appearance-row.client.spec.tsx # packages/client/ui-theme/tests/font-size-row.client.spec.tsx # packages/client/ui-tool/tests/coverage-tails.client.spec.tsx # packages/client/ui-tool/tests/diff-card.client.spec.tsx # packages/client/ui-tool/tests/image-card.client.spec.tsx # packages/client/ui-tool/tests/read-card.client.spec.tsx # packages/client/ui-tool/tests/terminal-card.client.spec.tsx # packages/client/ui-trajectory/tests/views.client.spec.tsx # packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx # packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx # packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx # packages/client/ui-workspace/tests/apply.client.spec.ts # packages/client/ui-workspace/tests/tree.client.spec.ts # packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx # packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx # packages/client/ui-workspace/tests/workspaces-service.client.spec.ts # packages/extensions/cordis-client-runner/src/client/slot-catalog.ts # packages/jobs/tool-jobs/src/index.ts # packages/shell/tool-bash/README.i18n.yaml # packages/test-support/client-runtime/src/sessions.ts
description, kind
| description | kind |
|---|---|
| Package map for the persistent terminal capability family: the owner-scoped ctx.terminals service, the shell backend that starts interactive bash or pwsh, and the six model-facing tools. | 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, and tool-terminal/ for six model-facing terminal operations with bounded results. 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
The family is one session service, one shell backend, and one set of model-facing tools. 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 |
tool-terminal/ |
Six model-facing tools with owner isolation and optional background sends | registers on ctx.tools |
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.
Dev Note
Working context for maintainers — click to expand
None.