Skip to content

feat(terminal): persist user terminal history for agents#1540

Merged
wsp1911 merged 1 commit into
GCWing:mainfrom
wsp1911:dev
Jul 14, 2026
Merged

feat(terminal): persist user terminal history for agents#1540
wsp1911 merged 1 commit into
GCWing:mainfrom
wsp1911:dev

Conversation

@wsp1911

@wsp1911 wsp1911 commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Persist plain-text transcripts for user-created terminal sessions under the application data terminals directory.
  • Use shell integration to record executed commands and their attributed output while avoiding typed-and-deleted command-line input. Sessions without shell integration continue to capture raw PTY output.
  • Add bounded segment rotation, inactive-session retention, startup recovery, compact transcript IDs, and a generated AGENTS.md that explains how agents can search and inspect the transcript files.
  • Configure transcript storage for both desktop and CLI terminal services while excluding agent-created terminal sessions.
  • Add the {READ_TERMINAL} prompt placeholder so local agents can progressively discover terminal history when relevant execution evidence is missing from the conversation.

Fixes #

Type and Areas

Type: Feature

Areas: Rust core, terminal service, desktop/Tauri, CLI, agent prompt assembly

Motivation / Impact

Users often refer to commands they previously ran or report command-line, build, test, script, or process failures without including the exact command or complete output. Previously, agents could not recover that execution evidence after it had scrolled out of the visible terminal.

This change provides durable, bounded terminal transcripts that agents can inspect when the missing terminal context materially affects the task. Transcript discovery follows a progressive-loading model: the normal prompt only identifies when terminal history may be useful and points to the generated AGENTS.md; the transcript files are read only when needed.

Shell-integrated terminals record actual executed commands and attributed output rather than intermediate command-line editing. The PowerShell/ConPTY handling also preserves late or reordered command output after command completion.

Transcript storage defaults to:

  • 4 MiB per log segment;
  • 4 retained segments per terminal session;
  • 10 recent inactive sessions;
  • no inactive-session limit applied to currently active sessions.

The on-disk layout is:

<app-data>/terminals/
├── AGENTS.md
├── index.json
└── <transcript_id>/
    ├── 000001.log
    ├── 000002.log
    └── ...

Verification

  • pnpm run fmt:rs
  • cargo check -p terminal-core
  • cargo test -p terminal-core
    • 80 passed, 0 failed.
  • cargo test -p terminal-core transcript::tests -j 1
    • 9 passed, 0 failed.
  • cargo test -p bitfun-core --lib local_terminal_transcript_placeholder_includes_the_agents_path -j 1
  • cargo test -p bitfun-core --lib remote_terminal_transcript_placeholder_is_omitted -j 1
  • node scripts/check-core-boundaries.mjs
  • Manually reproduced PowerShell/ConPTY command execution and confirmed that late or reordered command output is persisted completely.

Reviewer Notes

  • Transcript recording is enabled only when the product host supplies a storage root. Desktop and CLI configure it as <user-data>/terminals.
  • Agent-created terminal sessions do not produce transcripts.
  • Local agent prompts receive terminal-history guidance. Remote workspace prompts omit it because this storage currently represents local user terminal sessions.
  • index.json stores session metadata and the short transcript_id; segment lists remain internal and are discovered by listing the transcript directory.
  • Missing or unreadable indexes are recovered from transcript segment headers, and sessions left active by an interrupted process are recovered as inactive.
  • Transcript write failures are handled as best-effort warnings and do not interrupt the terminal session.
  • No migration from the previous development-only terminal-transcripts directory name is included because the feature has not been released.
  • ANSI cleanup is intentionally out of scope.
  • A trailing PowerShell prompt can still occasionally be captured after command output. Late output and prompt rendering do not provide a reliable semantic boundary, so this PR avoids adding a potentially destructive heuristic.

Checklist

  • This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
  • Relevant verification is recorded above, or skipped checks are explained.
  • User-facing strings, docs, and locales are updated where applicable.

Persist rotating plain-text transcripts for user-created terminal
sessions, including command metadata, exit codes, cwd changes, and
shell-attributed output.

Configure transcript storage for desktop and CLI, recover transcript
indexes across restarts, and retain active sessions plus the most
recent completed sessions.

Add progressive READ_TERMINAL prompt guidance so agents can inspect
local terminal evidence when command or output context is missing.
@wsp1911 wsp1911 marked this pull request as ready for review July 14, 2026 02:34
@wsp1911 wsp1911 merged commit dbd6e7e into GCWing:main Jul 14, 2026
4 checks passed
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.

1 participant