Refactor agent executors, improve CLI presentation, and update prompts/docs

[lvndry]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @lvndry, 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 refactors core agent execution mechanisms, enhances the command-line interface's presentation, and updates agent prompts and skill documentation. The changes aim to improve agent capabilities through sub-agent delegation and context management, provide a more polished and informative user experience in the CLI, and guide agents towards more effective task-solving strategies.

Highlights

• Agent Executor Refactoring: Introduced spawn_subagent and summarize_context tools, enabling agents to delegate complex tasks to specialized sub-agents and manage context window size. Tools now support longRunning and timeoutMs properties for better control and UI feedback.
• Improved CLI Presentation: Enhanced the command-line interface's visual output with a new code-theme.ts for consistent code coloring, replacing chalk.cyan with a more sophisticated color function. Tool execution timeouts are now conditionally displayed based on the longRunning flag.
• Updated Prompts and Documentation: Revised system prompts to reorder task-solving preferences, emphasizing skills and existing tools over shell builtins. The deep-research skill documentation was updated with new search query examples.
• Graceful Shutdown and Tool Context: Implemented a more robust signal handling mechanism for graceful application shutdown. Tool execution contexts now include conversationMessages and parentAgent for richer tool interactions.
• AI SDK Integration Enhancements: Refined the handling of provider-native web search tools within the AI SDK service, ensuring correct routing and filtering of tool calls.

Changelog

• skills/deep-research/SKILL.md
  • Updated example search query variants for synonym expansion and specificity ladder.
• src/app-layer.ts
  • Introduced requestShutdownRef and modified signal handler to use it for more controlled interruption of the main fiber.
  • Implemented Effect.race between fiber completion and shutdown requests for graceful exit.
• src/cli/presentation/cli-renderer.test.ts
  • Updated tests to import and use the new codeColor function for code block and codespan assertions.
• src/cli/presentation/cli-renderer.ts
  • Imported codeColor from code-theme.ts.
  • Configured marked.setOptions to use codeColor for code and codespan rendering, replacing chalk.cyan.
• src/cli/presentation/code-theme.ts
  • New file: Defines getCodeColor function to return a chalk color function based on chalk.level, providing a Dracula-inspired color for code.
• src/cli/presentation/ink-presentation-service.ts
  • Modified setupToolTimeout call to only apply if event.longRunning is false, preventing premature timeout warnings for long-running tools.
• src/cli/presentation/markdown-formatter.ts
  • Replaced direct chalk.cyan calls with codeColor for inline code, code blocks, and code block content formatting.
• src/cli/services/markdown-service.ts
  • Imported codeColor.
  • Replaced direct chalk.cyan calls with codeColor for inline code, code block content, and streaming chunk formatting.
• src/core/agent/agent-runner.ts
  • Added spawn_subagent and summarize_context to the BUILT_IN_TOOLS list.
  • Adjusted streaming detection logic: internal runs (sub-agents) now use the same streaming detection as the parent, removing the forced non-streaming behavior.
• src/core/agent/execution/batch-executor.ts
  • Injected conversationMessages and parentAgent into the contextWithTokenStats object for tool execution.
• src/core/agent/execution/streaming-executor.ts
  • Injected conversationMessages and parentAgent into the contextWithTokenStats object for tool execution.
• src/core/agent/execution/tool-executor.ts
  • Implemented logic to retrieve longRunning and timeoutMs from tool metadata.
  • Used timeoutMs for Effect.timeoutFail duration, allowing per-tool custom timeouts.
  • Added isLongRunning property to tool_execution_start events for UI hints.
• src/core/agent/prompts/default/system.ts
  • Reordered task-solving preferences: Skills are now prioritized first, followed by existing tools, then web search, piping, inference, and finally shell builtins.
  • Minor wording changes from 'user’s' to 'user's'.
• src/core/agent/prompts/researcher/system.ts
  • Updated description from 'CLI and tools environment' to 'CLI environment with tools and skills'.
• src/core/agent/tools/base-tool.ts
  • Added longRunning (boolean) and timeoutMs (number) properties to the BaseToolConfig interface and defineTool function.
• src/core/agent/tools/register-tools.ts
  • Imported createSubagentTools.
  • Added SUBAGENT_CATEGORY and registered registerSubagentTools.
  • Included SUBAGENT_CATEGORY in ALL_CATEGORIES and BUILTIN_TOOL_CATEGORIES.
• src/core/agent/tools/subagent-tools.ts
  • New file: Defines spawn_subagent and summarize_context tools.
  • spawn_subagent: Allows delegating tasks to ephemeral sub-agents with specific personas and wraps the task with instructions for one-shot completion.
  • summarize_context: Enables compacting conversation history by summarizing older messages.
  • Both tools are marked as longRunning and spawn_subagent has a custom timeoutMs.
• src/core/agent/tools/user-interaction-tools.ts
  • Added longRunning: true and timeoutMs: USER_INPUT_TIMEOUT_MS to ask_user_question and ask_file_picker tools.
• src/core/interfaces/tool-registry.ts
  • Added LLMService to ToolRequirements.
  • Added longRunning and timeoutMs properties to the Tool interface.
• src/core/types/streaming.ts
  • Added optional longRunning boolean property to the tool_execution_start event type.
• src/core/types/tools.ts
  • Added optional conversationMessages (array of ChatMessage) and parentAgent (Agent type) to ToolExecutionContext.
• src/services/llm/ai-sdk-service.ts
  • Removed hasExternalWebSearchKeys function.
  • Modified prepareTools to return providerNativeToolNames alongside tools.
  • Refined logic for determining whether to use provider-native web search or Jazz's web search based on explicit user configuration and provider support.
  • Filtered out provider-native tool calls from the toolCalls array before passing them to Jazz's tool executor, as they are handled server-side.

Activity

• The pull request author, lvndry, created this pull request.
• The pull request includes multiple commits covering feature additions, refactoring, and documentation updates.

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 introduces significant enhancements to the agent's capabilities, including sub-agent execution, improved CLI presentation with theming, and more robust handling of provider-native tools. The refactoring of signal handling for graceful shutdown is a great improvement for stability. My review focuses on ensuring consistency in the new features and preventing potential bugs in the streaming execution path. I've identified a critical issue in the streaming logic for provider-native tools and a couple of medium-severity improvement opportunities in the new sub-agent tools for better robustness and consistency.

[lvndry]

/gemini review

[gemini-code-assist]

Code Review

This is a substantial pull request that introduces significant new capabilities, most notably the agent executor refactoring to support sub-agents. The addition of spawn_subagent and summarize_context tools opens up powerful new patterns for agent workflows. The improvements to CLI presentation, especially the more robust handling of provider-native tools and the new color theme for code, enhance the user experience. The extensive updates to system prompts are also a welcome change, steering the agent towards more reliable and hierarchical tool usage. The code is well-structured, and the changes are consistent across the codebase. The identified issues, one related to markdown formatting and another to improving logging for a specific configuration scenario, remain valid. Overall, this is an excellent set of changes.