feat(core): implement mid-turn queue drain for agent execution

[wenshao]

Summary

Implement mid-turn queue drain for the main session, allowing the model to see user messages immediately during tool execution instead of waiting for the entire round to complete.

Before (Between-Round Drain)

User messages sent during tool execution are buffered locally in React state. They are only flushed after the entire round completes, then processed as a new round:

Round start → [API→Tool→API→Tool→...→Done] → dequeue → New Round(user msg) → ...
                                                 ↑ user must wait until here

The user cannot redirect or supplement the agent mid-execution — they must wait for all tool steps to finish.

After (Mid-Turn Queue Drain)

After each tool execution step, the queue is drained and messages are injected as text parts alongside tool results, so the model sees them in the very next API call:

Turn start → [API→Tool] → queue drain → [API(user msg + tool results)→Tool] → ...
                               ↑ user message injected here, model sees it immediately

Changes

File	Change
useGeminiStream.ts	Add midTurnDrainRef parameter; drain queue in handleCompletedTools before submitQuery
AppContainer.tsx	Create drain ref; bridge useMessageQueue to it via ref pattern (avoids stale closures)

Test plan

Automated tests

• npx vitest run packages/cli/src/ui/hooks/useGeminiStream.test.tsx — 56 tests pass (no regression)
• npx vitest run packages/cli/src/ui/AppContainer.test.tsx — 32 tests pass (no regression)
• npx tsc --noEmit passes for both core and cli packages

Manual test case

1. Send a multi-step task with a slow tool call:

   Run this command: sleep 15 && echo "step1 done", then after that create a file src/result.ts
   

2. While sleep 15 is executing (you have a 15-second window), type:

   Write "modified by user" in the file instead
   

3. After sleep finishes, check src/result.ts:
   • Mid-turn drain working: file contains "modified by user" (model saw the message before creating the file)
   • Not working: file has model-chosen content, user message processed in a separate round

🤖 Generated with Claude Code

[github-actions]

📋 Review Summary

This PR implements mid-turn queue drain functionality, allowing user messages queued during tool execution to be injected into the current reasoning turn rather than waiting for the entire round to complete. The implementation is well-structured with comprehensive test coverage and clean separation of concerns across the queue utility, agent core, interactive agent, and UI components.

🔍 General Feedback

• Clean architecture: The implementation follows a clear layered approach - AsyncMessageQueue provides the primitive, AgentInteractive orchestrates the drain logic, AgentCore injects messages into the conversation, and AgentComposer handles UI display.
• Good test coverage: New tests cover the dequeueAll() method, mid-turn drain callback passing, message draining, event emission, and edge cases (empty queue drain).
• Consistent patterns: Event-driven architecture aligns with existing patterns (QUEUE_MESSAGES_CONSUMED event follows the same structure as other agent events).
• Type safety: Proper TypeScript typing throughout, including the new AgentQueueDrainEvent interface and AgentEventMap extension.
• Positive: The midTurnDrain callback pattern in ReasoningLoopOptions is a clean, non-invasive way to inject this behavior into the core reasoning loop.

🎯 Specific Feedback

🟢 Medium

• File: packages/core/src/agents/runtime/agent-core.ts:504-509 - The injected user message format uses a plain text prefix ([User message received during tool execution]) which could potentially be confused with actual user input by the model. Consider using a more structured approach (e.g., a separate message role or metadata field) to distinguish injected messages from genuine user messages.

• File: packages/core/src/agents/runtime/agent-interactive.ts:189 - The midTurnDrain callback is created inline in the options object. While functional, this creates a new function reference on each call. Consider defining it as a class method bound in the constructor or using an arrow property to avoid potential memory churn in tight loops.

• File: packages/cli/src/ui/components/agent-view/AgentComposer.tsx:194-204 - The useEffect for clearing display on QUEUE_MESSAGES_CONSUMED and STATUS_CHANGE events doesn't include streamingState in dependencies, but accesses it in the closure. While not causing bugs here (the event handlers don't use it), adding it would make the dependency array more explicit and future-proof.

🔵 Low

• File: packages/core/src/agents/runtime/agent-events.ts:177-183 - The AgentQueueDrainEvent interface includes subagentId but other similar events (like AgentStatusChangeEvent) use agentId. Consider standardizing on one naming convention for consistency across event types.

• File: packages/core/src/utils/asyncMessageQueue.ts:41-44 - The dequeueAll() implementation uses this.items.splice(0) which mutates the internal array. While correct, adding a JSDoc comment noting that it returns a copy (or explicitly returning a copy with [...this.items]) would clarify the ownership semantics for callers.

• File: packages/cli/src/ui/components/agent-view/AgentComposer.tsx:285 - The variable rename from messageQueue to pendingMessages is clear, but the comment "Track for display when agent is busy" could benefit from explaining why we track pending messages separately (i.e., to show users their queued messages are waiting to be processed).

✅ Highlights

• Excellent test coverage: The four new test cases in agent-interactive.test.ts thoroughly cover the mid-turn drain functionality, including the callback passing, message draining with metadata, event emission, and empty queue edge case.
• Clean event-driven design: The QUEUE_MESSAGES_CONSUMED event allows the UI to stay synchronized with backend state changes without polling or tight coupling.
• Minimal invasive changes: The midTurnDrain callback pattern in ReasoningLoopOptions is an elegant way to add this feature without modifying the core reasoning loop logic significantly.
• Good metadata tracking: Messages injected mid-turn are marked with metadata: { midTurnInjected: true }, enabling potential debugging or analytics down the line.

[Copilot]

Pull request overview

Adds “mid-turn” draining of queued user messages so that messages typed during tool execution can be injected into the very next model call (instead of waiting until the entire round completes), improving interactivity for both in-process agents and the main CLI stream loop.

Changes:

• Add dequeueAll() to AsyncMessageQueue to atomically drain pending items.
• Introduce midTurnDrain callback plumbing through AgentCore.runReasoningLoop and implement queue draining + event emission in AgentInteractive.
• Wire CLI UI/streaming to enqueue immediately and drain mid-turn (via new event + a ref bridge).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/core/src/utils/asyncMessageQueue.ts	Adds dequeueAll() for draining all queued items.
packages/core/src/utils/asyncMessageQueue.test.ts	Adds tests for dequeueAll() behavior.
packages/core/src/agents/runtime/agent-interactive.ts	Implements queue draining + event emission; passes midTurnDrain into core loop.
packages/core/src/agents/runtime/agent-interactive.test.ts	Adds tests for mid-turn draining and event emission.
packages/core/src/agents/runtime/agent-events.ts	Adds QUEUE_MESSAGES_CONSUMED event and payload type.
packages/core/src/agents/runtime/agent-core.ts	Calls midTurnDrain() after tool execution to inject messages into the next API call.
packages/cli/src/ui/hooks/useGeminiStream.ts	Injects drained queued messages into the next tool-result submission.
packages/cli/src/ui/components/agent-view/AgentComposer.tsx	Always enqueues messages directly; clears pending display on drain/status events.
packages/cli/src/ui/AppContainer.tsx	Bridges useMessageQueue to useGeminiStream via a midTurnDrainRef.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tanzhenxin]

LGTM!

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.