Skip to content

feat(tool): add interactive terminal tool with persistent PTY sessions#23760

Closed
herjarsa wants to merge 1 commit intoanomalyco:devfrom
herjarsa:feat/interactive-terminal-tool
Closed

feat(tool): add interactive terminal tool with persistent PTY sessions#23760
herjarsa wants to merge 1 commit intoanomalyco:devfrom
herjarsa:feat/interactive-terminal-tool

Conversation

@herjarsa
Copy link
Copy Markdown

Summary

Closes #23759

Adds a fully interactive terminal tool that lets the agent manage persistent PTY sessions - create, send input, read output (with cursor-based incremental reads), and close sessions. This makes the terminal a true extension of the agent rather than a one-shot command runner.

What's included

  • 5 action handlers: run, create, send, read, close
  • SessionState: tracks exitCode (via sentinel command on Windows), discriminated union Zod schema
  • FIFO eviction: max 20 sessions, oldest evicted first
  • InstanceState: per-directory session isolation via Pty.Service
  • Incremental reads: cursor-based read action returns only new output since last read
  • Windows support: sentinel command pattern for exit code detection on PowerShell

Files changed

File Lines Purpose
src/tool/terminal.ts 640 Tool implementation with 5 actions, session state, eviction
src/tool/terminal.txt 112 Tool description for agent context
src/tool/txt.d.ts 4 Type declaration for .txt imports
src/tool/registry.ts +7 Registration: import, service deps, init, builtin list
test/tool/terminal.test.ts 273 20 unit + 3 integration tests (23 pass, 2 skip)
package.json +1 @babel/types devDep (Windows Bun workaround)

Testing

  • 23 tests pass (20 unit + 3 integration)
  • 2 skipped (backward-compat run action tests - bus event propagation limitation in test context)

Design decisions

  • Sentinel command over Pty.onExit: Windows PowerShell does not reliably emit exit events, so we inject a sentinel command that writes EXIT_CODE:<N> to stdout and parse it
  • FIFO eviction: simple and predictable - when max sessions reached, the oldest is closed and evicted
  • InstanceState: sessions are scoped per working directory, preventing cross-project contamination
  • Incremental reads: cursor-based approach avoids re-reading entire buffer, keeps context lean

Introduces a new terminal tool with action-based session management:
- run (default): backward-compatible one-shot execution
- create: start persistent PTY session, returns sessionId
- send: write input to existing session (commands, control sequences)
- read: cursor-based incremental output reading
- close: terminate session and cleanup resources

Sessions stored via InstanceState for per-directory isolation with
FIFO eviction at max 20 sessions. Fixes PowerShell exit code by using
\ instead of \True on Windows.

Closes anomalyco#23759
@github-actions github-actions Bot added the needs:compliance This means the issue will auto-close after 2 hours. label Apr 21, 2026
@github-actions
Copy link
Copy Markdown
Contributor

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

  • PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

@github-actions
Copy link
Copy Markdown
Contributor

This pull request has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new pull request that follows our guidelines.

@github-actions github-actions Bot removed the needs:compliance This means the issue will auto-close after 2 hours. label Apr 22, 2026
@github-actions github-actions Bot closed this Apr 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(tool): add interactive terminal tool with persistent PTY sessions

1 participant