Add StateMachine tracking to Agent control flow
This commit integrates the existing StateMachine type with the Agent
to provide state tracking and validation throughout the conversation
control flow. This allows for better monitoring and debugging of the
Agent's behavior during execution.
This commit adds tests to verify the correct behavior of the state
machine integration with the Agent type:
1. A test for basic state transitions
2. A test for a complete processTurn flow with a simple response
3. A test for a processTurn flow with tool use
Co-Authored-By: sketch <hello@sketch.dev>
diff --git a/loop/statemachine_diagram.md b/loop/statemachine_diagram.md
new file mode 100644
index 0000000..82a160c
--- /dev/null
+++ b/loop/statemachine_diagram.md
@@ -0,0 +1,80 @@
+# Agent State Machine Diagram
+
+```mermaid
+stateDiagram-v2
+ [*] --> StateReady
+
+ StateReady --> StateWaitingForUserInput
+
+ StateWaitingForUserInput --> StateSendingToLLM
+ StateWaitingForUserInput --> StateError
+
+ StateSendingToLLM --> StateProcessingLLMResponse
+ StateSendingToLLM --> StateError
+
+ StateProcessingLLMResponse --> StateEndOfTurn
+ StateProcessingLLMResponse --> StateToolUseRequested
+ StateProcessingLLMResponse --> StateError
+
+ StateEndOfTurn --> StateWaitingForUserInput
+
+ StateToolUseRequested --> StateCheckingForCancellation
+
+ StateCheckingForCancellation --> StateRunningTool
+ StateCheckingForCancellation --> StateCancelled
+
+ StateRunningTool --> StateCheckingGitCommits
+ StateRunningTool --> StateError
+
+ StateCheckingGitCommits --> StateRunningAutoformatters
+ StateCheckingGitCommits --> StateCheckingBudget
+
+ StateRunningAutoformatters --> StateCheckingBudget
+
+ StateCheckingBudget --> StateGatheringAdditionalMessages
+ StateCheckingBudget --> StateBudgetExceeded
+
+ StateGatheringAdditionalMessages --> StateSendingToolResults
+ StateGatheringAdditionalMessages --> StateError
+
+ StateSendingToolResults --> StateProcessingLLMResponse
+ StateSendingToolResults --> StateError
+
+ StateError --> StateWaitingForUserInput
+ StateCancelled --> StateWaitingForUserInput
+ StateBudgetExceeded --> StateWaitingForUserInput
+```
+
+## State Descriptions
+
+| State | Description |
+|-------|-------------|
+| StateReady | Initial state when the agent is initialized and ready to operate |
+| StateWaitingForUserInput | Agent is waiting for a user message to start a turn |
+| StateSendingToLLM | Agent is sending message(s) to the LLM |
+| StateProcessingLLMResponse | Agent is processing a response from the LLM |
+| StateEndOfTurn | Processing completed without tool use, turn ends |
+| StateToolUseRequested | LLM has requested to use a tool |
+| StateCheckingForCancellation | Agent checks if user requested cancellation |
+| StateRunningTool | Agent is executing the requested tool |
+| StateCheckingGitCommits | Agent checks for new git commits after tool execution |
+| StateRunningAutoformatters | Agent runs code formatters on new commits |
+| StateCheckingBudget | Agent verifies if budget limits are exceeded |
+| StateGatheringAdditionalMessages | Agent collects user messages that arrived during tool execution |
+| StateSendingToolResults | Agent sends tool results back to the LLM |
+| StateCancelled | Operation was cancelled by the user |
+| StateBudgetExceeded | Budget limit was reached |
+| StateError | An error occurred during processing |
+
+## Implementation Details
+
+This state machine is implemented in `statemachine.go` and follows the State pattern design. Key features include:
+
+1. Explicit state enumeration for all possible states
+2. Validation of state transitions
+3. History tracking for debugging
+4. Event recording for each transition
+5. Timing information for performance analysis
+6. Error state detection
+
+The `AgentWithStateMachine` in `statemachine_example.go` demonstrates how this state machine could be integrated with the existing Agent implementation.