feat(agent): mid-turn message injection for responsive follow-ups

[chengyongru]

Summary

• Allow user messages sent during an active agent turn to be injected into the running LLM context instead of waiting behind the per-session lock
• between iterations, queued messages are drained as attachments and sent to the model in the current turn

Motivation

Currently, nanobot uses a per-session asyncio.Lock that serializes message processing. When a task takes a long time (e.g. web_search, long exec), new messages from the user must wait until the entire turn completes. This makes the agent feel unresponsive. See #1609 for the full discussion.

Previous attempt (#1233, closed) tried to interrupt tool execution mid-way, which introduced significant complexity (~500 lines) with cancellation edge cases. This PR takes a simpler approach: don't cancel tools, just inject messages between iterations.

How It Works

User sends "hello" → agent starts processing (holds session lock)
User sends "what time is it?" → routed to pending queue (not a new task)
  ↓
Agent iteration: LLM call → tool execution → [DRAIN] → next LLM call
                                              ↑ injected as user message
  ↓
LLM sees both messages naturally and responds to both

Two drain checkpoints in the agent loop:

1. After tool execution (before next LLM call) — tools run to completion, then new messages are appended
2. After final response ("last-mile") — if the user sent a follow-up while the LLM was generating its final answer, continue the loop instead of breaking

Key Design Decisions

Decision	Rationale
Inject as natural user messages	No special system prompt or [Follow-up] markers needed — LLM handles multi-turn naturally
No tool cancellation	Avoids the complexity that caused #1233 to be closed (partial writes, inconsistent state)
_MAX_INJECTIONS_PER_TURN = 3	Prevents context window pressure from rapid message accumulation
_MAX_INJECTION_CYCLES = 5	Prevents injection loops from consuming the iteration budget
had_injections bypasses _sent_in_turn	When follow-ups are injected, the final response is new content the user hasn't seen — always deliver it
Pending queue lifecycle via try/finally	Prevents memory leaks; queue is registered before lock acquisition and cleaned up after

Edge Cases Handled

• Last-mile: Messages arriving after the LLM's final response but before turn end are caught by Checkpoint 2
• _sent_in_turn conflict: Follow-up responses bypass the MessageTool suppression check
• Queue cleanup: finally block in _dispatch() ensures no dangling queues
• Bounded accumulation: Both per-drain (3 messages) and per-turn (5 cycles) limits
• Graceful degradation: If injection_callback throws, the error is logged and injection is skipped

Changes

• nanobot/agent/runner.py: injection_callback on AgentRunSpec, _drain_injections() helper, two drain checkpoints in run(), had_injections on AgentRunResult
• nanobot/agent/loop.py: _pending_queues dict, message routing in run(), queue lifecycle in _dispatch(), _drain_pending callback, _sent_in_turn bypass
• Test files: updated _run_agent_loop return value unpacking (3-tuple → 5-tuple)

Related

• Closes How to Make nanobot More Responsive? #1609
• Supersedes feat: add async event injection mechanism for user interruption #1233 (simpler approach, no tool cancellation)