feat(core): pause agent timeout budget while waiting for tool confirmation

[abhipatel12]

Summary

This PR ensures that subagent timeout budgets only account for active processing time by pausing the timeout when the agent is waiting for user confirmation of a tool call.

Details

• Introduced DeadlineTimer utility in packages/core/src/utils/deadlineTimer.ts to manage pauseable/resumable timeouts.
• Added onWaitingForConfirmation hook to Scheduler to track when it enters and exits an idle state (waiting for user input).
• Integrated DeadlineTimer into LocalAgentExecutor to accurately track agent execution time, excluding human interaction time.
• Added unit tests for DeadlineTimer and the scheduler's notification logic.

Related Issues

N/A

How to Validate

1. Run unit tests for the new utility and scheduler logic:

   npm test -w @google/gemini-cli-core -- src/utils/deadlineTimer.test.ts src/scheduler/scheduler_waiting_callback.test.ts

2. Manual validation: Start a subagent with a short timeout (e.g., 1 minute), trigger a tool that requires confirmation, wait longer than the timeout before confirming, and observe that the agent continues successfully without timing out.

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
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello @abhipatel12, 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 refines how agent execution timeouts are managed by introducing a pauseable timer. This ensures that the time an agent spends waiting for human interaction, such as tool confirmation, does not count against its allocated timeout budget, leading to more robust and user-friendly agent operations.

Highlights

• New Utility: DeadlineTimer: Introduced a DeadlineTimer utility that allows timeouts to be paused, resumed, and extended, providing more flexible control over time-sensitive operations.
• Agent Timeout Budget Management: The LocalAgentExecutor now utilizes the DeadlineTimer to accurately track agent execution time, pausing the timeout budget when the agent is waiting for user confirmation of a tool call.
• Scheduler Confirmation Hook: Added an onWaitingForConfirmation hook to the Scheduler to notify when it enters or exits a state of waiting for user input, enabling external systems (like the DeadlineTimer) to react accordingly.
• Enhanced Test Coverage: New unit tests have been added for both the DeadlineTimer utility and the scheduler's onWaitingForConfirmation callback logic, ensuring the reliability of these new features.

Changelog

• packages/core/src/agents/agent-scheduler.ts
  • Added onWaitingForConfirmation optional function to AgentSchedulingOptions interface.
  • Passed onWaitingForConfirmation through to the Scheduler constructor.
• packages/core/src/agents/local-executor.ts
  • Imported DeadlineTimer utility.
  • Modified _runTurn and _attemptRecovery methods to accept onWaitingForConfirmation callback.
  • Replaced AbortController and setTimeout for agent timeout management with DeadlineTimer.
  • Integrated onWaitingForConfirmation callback to pause and resume the deadlineTimer when waiting for user input.
  • Updated timeout signal checks to use deadlineTimer.signal.
• packages/core/src/scheduler/confirmation.ts
  • Modified resolveConfirmation to accept onWaitingForConfirmation callback.
  • Invoked onWaitingForConfirmation(true) before waiting for user confirmation and onWaitingForConfirmation(false) after receiving it.
• packages/core/src/scheduler/scheduler.ts
  • Added onWaitingForConfirmation optional property to SchedulerOptions interface and Scheduler class.
  • Passed onWaitingForConfirmation to the resolveConfirmation function.
• packages/core/src/scheduler/scheduler_waiting_callback.test.ts
  • Added a new test file to verify the onWaitingForConfirmation callback functionality within the Scheduler.
• packages/core/src/utils/deadlineTimer.test.ts
  • Added a new test file to provide comprehensive unit tests for the DeadlineTimer class, covering pause, resume, extend, and abort functionalities.
• packages/core/src/utils/deadlineTimer.ts
  • Added a new utility class DeadlineTimer that provides a pauseable, resumable, and extendable timeout mechanism using AbortController.

Activity

• A new DeadlineTimer utility has been introduced to manage timeouts with pause/resume capabilities.
• The LocalAgentExecutor has been refactored to use this new DeadlineTimer for its timeout budget.
• A new onWaitingForConfirmation hook has been added to the Scheduler and AgentSchedulingOptions to signal when user input is awaited.
• The resolveConfirmation function now uses this hook to pause and resume the DeadlineTimer during user interaction.
• Comprehensive unit tests have been added for both the DeadlineTimer and the scheduler's new callback logic.
• The author has confirmed that tests have been added/updated and breaking changes (if any) have been noted.
• Validation has been performed on MacOS using npm run.

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. ↩

[github-actions]

Size Change: +3.33 kB (+0.01%)

Total Size: 23.8 MB

Filename	Size	Change
./bundle/gemini.js	23.7 MB	+3.33 kB (+0.01%)

ℹ️ View Unchanged

Filename	Size
./bundle/sandbox-macos-permissive-closed.sb	1.03 kB
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-closed.sb	3.29 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature by pausing the agent's timeout budget while it awaits user confirmation for a tool call. The implementation is solid, utilizing a new DeadlineTimer utility with comprehensive unit tests, and thoughtfully integrated into LocalAgentExecutor and Scheduler. A security audit confirmed no high or critical vulnerabilities, noting robust resource management, accurate pause/resume logic, safe integration, and no new injection vectors or LLM safety issues. This enhancement improves the user experience by preventing premature timeouts due to human interaction delays.

[sehoon38]

LGTM