feat: implement background process logging and cleanup

[galz10]

Summary

This PR implements persistent logging and automatic cleanup for backgrounded shell processes. It ensures that when a process is moved to the background, its output (both historical and real-time) is captured in ~/.gemini/tmp/background-processes/*.log files. It also adds a background cleanup task that runs on CLI startup to remove logs older than 7 days.

Details

• ShellExecutionService Enhancements:
  • Added backgroundLogStreams to track active writable streams for background processes.
  • Implemented writeBufferToLogStream for node-pty to sync terminal buffer content to disk without ANSI codes.
  • Added real-time syncing for child_process output chunks.
  • Ensured streams are gracefully closed when a process exits or is killed.
• Log Cleanup:
  • Created cleanupBackgroundLogs utility in packages/cli/src/utils/logCleanup.ts.
  • Integrated cleanup into the main CLI entry point (gemini.tsx) to run once per session.
• UI Improvements:
  • Updated BackgroundShellDisplay to show a "Log file" indicator when a process is running in the background.
  • Adjusted UIActionsContext and hooks to handle async kill and dismiss operations.

Related Issues

Related to the background execution stability and observability efforts.

How to Validate

1. Run the CLI: npm run start
2. Run a long-running command: ping google.com
3. Background the command: Use the background tool or the UI button.
4. Verify the log file: Check ~/.gemini/tmp/background-processes/background-<PID>.log.
5. Run tests:
   • npm test -w @google/gemini-cli -- packages/cli/src/utils/logCleanup.test.ts
   • npm test -w @google/gemini-cli-core -- src/services/shellExecutionService.test.ts
   • npm run test:e2e -- integration-tests/background_shell_output.test.ts

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
  • Linux

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the observability and maintainability of backgrounded shell processes within the CLI. By introducing persistent logging, users can now review the full output of long-running tasks even after they've been backgrounded or the CLI has been restarted. The accompanying cleanup mechanism ensures that these logs do not accumulate indefinitely, providing a balanced approach to data retention. These changes enhance the overall stability and user experience when interacting with background tasks.

Highlights

• Persistent Background Process Logging: Implemented a system to capture and store the output of backgrounded shell processes in dedicated log files (~/.gemini/tmp/background-processes/*.log), ensuring historical and real-time output is preserved without ANSI escape codes.
• Automatic Log Cleanup: Added a utility that runs on CLI startup to automatically remove background process log files older than 7 days, preventing indefinite storage and managing disk space.
• Enhanced UI for Background Processes: Updated the BackgroundShellDisplay component to show the log file path for active background processes and adjusted UI actions (kill, dismiss) to handle asynchronous operations.
• Robust Shell Execution Service: Refactored ShellExecutionService to manage log streams, incrementally sync node-pty terminal buffers, and continuously log child_process output, with graceful cleanup on process exit or termination.

Changelog

• integration-tests/background_shell_output.test.ts
  • Added a new integration test to verify that background process output is correctly logged to a file and that ANSI escape codes are stripped.
• packages/cli/src/gemini.tsx
  • Integrated the cleanupBackgroundLogs utility to run during CLI startup, ensuring old logs are removed.
• packages/cli/src/ui/AppContainer.tsx
  • Updated the shutdown logic to await Promise.all when killing background shells, ensuring all processes are handled asynchronously.
• packages/cli/src/ui/components/BackgroundShellDisplay.test.tsx
  • Updated ShellExecutionService mocks to include getLogFilePath and getLogDir for testing log display.
  • Adjusted expected resizePty dimensions in tests due to UI layout changes.
• packages/cli/src/ui/components/BackgroundShellDisplay.tsx
  • Imported shortenPath and tildeifyPath utilities for displaying log file paths.
  • Adjusted UI height calculations to accommodate a new footer displaying the log file path.
  • Modified calls to dismissBackgroundShell to use void as the function is now asynchronous.
  • Implemented a renderFooter function to display the log file path for the currently active or highlighted background process.
• packages/cli/src/ui/components/Footer.test.tsx
  • Refactored environment variable stubbing to use beforeEach and afterEach for better test isolation.
• packages/cli/src/ui/components/ModelStatsDisplay.test.tsx
  • Added a snapshot test for the component's output.
• packages/cli/src/ui/components/snapshots/BackgroundShellDisplay.test.tsx.snap
  • Updated snapshots to reflect the new log file path display in the background shell UI.
• packages/cli/src/ui/contexts/UIActionsContext.tsx
  • Updated the dismissBackgroundShell interface to return a Promise<void>, reflecting its asynchronous nature.
• packages/cli/src/ui/hooks/shellCommandProcessor.test.tsx
  • Updated test calls to dismissBackgroundShell to await its asynchronous completion.
• packages/cli/src/ui/hooks/shellCommandProcessor.ts
  • Modified dismissBackgroundShell to be an asynchronous function and await the ShellExecutionService.kill call.
• packages/cli/src/utils/logCleanup.test.ts
  • Added new unit tests for the cleanupBackgroundLogs utility, covering scenarios like directory existence, empty directories, and file age-based deletion.
• packages/cli/src/utils/logCleanup.ts
  • Added a new utility function cleanupBackgroundLogs to remove background process log files older than a specified retention period (7 days).
• packages/core/src/services/shellExecutionService.test.ts
  • Added mocks for node:fs, node:os, debugLogger, and Storage to support background logging tests.
  • Expanded mockHeadlessTerminal interface to include length and getLine for buffer synchronization tests.
  • Introduced new test suite for 'Backgrounding' functionality, covering node-pty and child_process logging, and error handling during log setup.
• packages/core/src/services/shellExecutionService.ts
  • Imported fs, mkdirSync, and path for file system operations, and debugLogger and Storage for logging and path management.
  • Updated ActivePty interface to include lastSyncedLine for tracking node-pty buffer synchronization.
  • Updated ActiveChildProcess interface to include lastSyncedOffset for tracking child_process output synchronization.
  • Introduced findLastContentLine and writeBufferToLogStream utilities to efficiently write terminal buffer content to log files, stripping ANSI codes.
  • Added static properties backgroundLogPids and backgroundLogStreams to manage active background logging.
  • Implemented getLogDir and getLogFilePath methods for consistent log file location.
  • Created syncBackgroundLog to write child_process output chunks to log files in real-time.
  • Developed cleanupLogStream to asynchronously close and remove log file write streams.
  • Modified execute method to initialize lastSyncedOffset for child_process and lastSyncedLine for node-pty.
  • Integrated real-time logging for child_process output by syncing deltas to the background log stream.
  • Ensured cleanupLogStream is called when a child_process exits.
  • Added logic within node-pty's onData handler to incrementally write terminal buffer changes to the background log stream.
  • Updated kill method to be asynchronous and include cleanupLogStream call.
  • Refactored background method to initialize background logging, create log directories and streams, write initial output, and handle potential setup errors gracefully.

Activity

• The pull request author, galz10, provided a comprehensive summary of the changes, detailing the motivation, implementation specifics, related issues, and thorough validation steps.
• The author included a pre-merge checklist, indicating completed documentation updates, test additions, and validation on MacOS.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively implements persistent logging for background processes and adds a cleanup mechanism for old logs. The changes are well-structured, with new utilities for log cleanup, updates to the ShellExecutionService to handle log streams, and UI enhancements to display log file information. The inclusion of comprehensive integration and unit tests is also a great addition.

I've found one potential issue related to how wrapped lines are written to the log file, which could lead to corrupted logs in some streaming scenarios. My detailed comment provides a suggested fix.

_{Note: Security Review did not run due to the size of the PR.}

[adamfweidman]

LGTM with a few comments

[github-actions]

Size Change: +6.46 kB (+0.02%)

Total Size: 26.5 MB

Filename	Size	Change
./bundle/gemini.js	26 MB	+6.46 kB (+0.02%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}