# Agent Loop Sequence Diagram

```
+---------+        +---------+        +------------+        +-------+        +-------+
|  User   |        |  Agent  |        | AgentLoop  |        |  LLM  |        | Tool  |
+---------+        +---------+        +------------+        +-------+        +-------+
     |                 |                   |                   |                 |
     | prompt(messages)|                   |                   |                 |
     |---------------->-->                 |                   |                 |
     |                 | normalizePrompt()|                   |                 |
     |                 |----------------->>|                   |                 |
     |                 | runPromptMessages|                   |                 |
     |                 |----------------->>|                   |                 |
     |                 |                   |                   |                 |
     |                 | createLoopConfig |                   |                 |
     |                 |----------------->>|                   |                 |
     |                 |                   |                   |                 |
     |                 | agentLoop()      |                   |                 |
     |                 |----------------->>|                   |                 |
     |                 |                   | emit(AgentStart)  |                 |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | transform_context() |               |
     |                 |                   |------------------>  |                 |
     |                 |                   | convert_to_llm()    |               |
     |                 |                   |------------------>  |                 |
     |                 |                   | stream_function()   |               |
     |                 |                   |------------------------->           |
     |                 |                   |                   | response      |
     |                 |                   |<-------------------------           |
     |                 |                   | emit(MessageStart)|                 |
     |                 |                   |------------------>  |                 |
     |                 |                   | emit(MessageEnd)  |                 |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | extract_tool_calls()|               |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | executeToolCalls()  |               |
     |                 |                   |------------------------->           |
     |                 |                   |                   | execute()     |
     |                 |                   |------------------------->           |
     |                 |                   |                   | result        |
     |                 |                   |<-------------------------           |
     |                 |                   | emit(ToolExecutionEnd)|             |
     |                 |                   |------------------>  |                 |
     |                 |                   | createToolResult()  |                 |
     |                 |                   |------------------>  |                 |
     |                 |                   | emit(MessageEnd)    |                 |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | emit(TurnEnd)       |                 |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | prepare_next_turn() |               |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | should_stop_check() |               |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | drain(steering_queue)|              |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 |                   | drain(follow_up_queue)|             |
     |                 |                   |------------------>  |                 |
     |                 |                   |                   |                 |
     |                 | emit(AgentEnd)    |                   |                 |
     |                 |------------------>|                   |                 |
     |                 |                   |                   |                 |
     |                 | appendMessage()   |                   |                 |
     |                 |------------------>  Session           |                 |
     |<----------------|                   |                   |                 |
     | messages        |                   |                   |                 |
     |                 |                   |                   |                 |
```

## Key Participants

```
User        - Initiates conversation by calling prompt()
Agent       - High-level wrapper managing state, queues, and events
AgentLoop   - Low-level execution engine (agentLoop, runLoop)
LLM         - Language model API (via stream_function)
Tool        - Tool execution (bash, read, write, edit)
Session     - Conversation history persistence
```

## Main Loop Flow

```
1. [Agent] normalizePromptInput() - Convert input to messages
2. [Agent] runPromptMessages()    - Start processing
3. [Agent] createLoopConfig()     - Build loop configuration
4. [Agent] agentLoop()            - Start low-level loop
5. [AgentLoop] emit(AgentStart)   - Signal start
6. [AgentLoop] transform_context() - Optional context transform
7. [AgentLoop] convert_to_llm()   - Convert to LLM messages
8. [AgentLoop] stream_function()  - Call LLM
9. [AgentLoop] emit(MessageStart/End) - Stream response
10. [AgentLoop] extract_tool_calls() - Check for tool calls
11. [AgentLoop] executeToolCalls() - Execute tools (seq/parallel)
12. [AgentLoop] emit(TurnEnd)     - Signal turn complete
13. [AgentLoop] prepare_next_turn() - Optional next turn setup
14. [AgentLoop] should_stop_check() - Check termination
15. [AgentLoop] drain queues()    - Check steering/follow-up
16. [AgentLoop] emit(AgentEnd)    - Signal completion
17. [Agent] appendMessage()       - Persist to session
```

## Queue Processing

```
steering_queue:  Injected after assistant turn, before next LLM call
follow_up_queue: Run only when agent would otherwise stop (after loop exit)
```

## Event Flow

```
AgentStart → [TurnStart → MessageStart → MessageEnd → ...] → TurnEnd → ...
            ↓
         AgentEnd
```

## Tool Execution Options

```
Sequential:  One tool at a time, in order
Parallel:    All tools spawned concurrently, results collected
```