mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-08 22:21:23 +00:00
456 lines
18 KiB
Markdown
456 lines
18 KiB
Markdown
# Agent Loop State Detection in the Roo Code Webview Client
|
|
|
|
This document explains how the webview client detects when the agent loop has stopped and is waiting on the client to resume. This is essential knowledge for implementing an alternative client.
|
|
|
|
## Overview
|
|
|
|
The Roo Code extension uses a message-based architecture where the extension host (server) communicates with the webview client through typed messages. The agent loop state is determined by analyzing the `clineMessages` array in the extension state, specifically looking at the **last message's type and properties**.
|
|
|
|
## Architecture Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ Extension Host (Server) │
|
|
│ │
|
|
│ ┌─────────────┐ ┌──────────────────────────────────────────────┐ │
|
|
│ │ Task.ts │────────▶│ RooCodeEventName events │ │
|
|
│ └─────────────┘ │ • TaskActive • TaskInteractive │ │
|
|
│ │ • TaskIdle • TaskResumable │ │
|
|
│ └──────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ postMessage("state")
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ Webview Client │
|
|
│ │
|
|
│ ┌──────────────────────┐ ┌─────────────────────┐ │
|
|
│ │ ExtensionStateContext│─────▶│ ChatView.tsx │ │
|
|
│ │ clineMessages[] │ │ │ │
|
|
│ └──────────────────────┘ │ ┌───────────────┐ │ │
|
|
│ │ │lastMessage │ │ │
|
|
│ │ │ .type │ │ │
|
|
│ │ │ .ask / .say │ │ │
|
|
│ │ │ .partial │ │ │
|
|
│ │ └───────┬───────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌───────────────┐ │ │
|
|
│ │ │ State Detection│ │ │
|
|
│ │ │ Logic │ │ │
|
|
│ │ └───────┬───────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌───────────────┐ │ │
|
|
│ │ │ UI State │ │ │
|
|
│ │ │ • clineAsk │ │ │
|
|
│ │ │ • buttons │ │ │
|
|
│ │ └───────────────┘ │ │
|
|
│ └─────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Key Message Types
|
|
|
|
### ClineMessage Structure
|
|
|
|
Defined in [`packages/types/src/message.ts`](../packages/types/src/message.ts):
|
|
|
|
```typescript
|
|
interface ClineMessage {
|
|
ts: number // Timestamp identifier
|
|
type: "ask" | "say" // Message category
|
|
ask?: ClineAsk // Ask type (when type="ask")
|
|
say?: ClineSay // Say type (when type="say")
|
|
text?: string // Message content
|
|
partial?: boolean // Is streaming incomplete?
|
|
// ... other fields
|
|
}
|
|
```
|
|
|
|
## Ask Type Categories
|
|
|
|
The `ClineAsk` types are categorized into four groups that determine when the agent is waiting. These are defined in [`packages/types/src/message.ts`](../packages/types/src/message.ts):
|
|
|
|
### 1. Idle Asks - Task effectively finished
|
|
|
|
These indicate the agent loop has stopped and the task is in a terminal or error state.
|
|
|
|
```typescript
|
|
const idleAsks = [
|
|
"completion_result", // Task completed successfully
|
|
"api_req_failed", // API request failed
|
|
"resume_completed_task", // Resume a completed task
|
|
"mistake_limit_reached", // Too many errors encountered
|
|
"auto_approval_max_req_reached", // Auto-approval limit hit
|
|
] as const
|
|
```
|
|
|
|
**Helper function:** `isIdleAsk(ask: ClineAsk): boolean`
|
|
|
|
### 2. Interactive Asks - Approval needed
|
|
|
|
These indicate the agent is waiting for user approval or input to proceed.
|
|
|
|
```typescript
|
|
const interactiveAsks = [
|
|
"followup", // Follow-up question asked
|
|
"command", // Permission to execute command
|
|
"tool", // Permission for file operations
|
|
"browser_action_launch", // Permission to use browser
|
|
"use_mcp_server", // Permission for MCP server
|
|
] as const
|
|
```
|
|
|
|
**Helper function:** `isInteractiveAsk(ask: ClineAsk): boolean`
|
|
|
|
### 3. Resumable Asks - Task paused
|
|
|
|
These indicate the task is paused and can be resumed.
|
|
|
|
```typescript
|
|
const resumableAsks = ["resume_task"] as const
|
|
```
|
|
|
|
**Helper function:** `isResumableAsk(ask: ClineAsk): boolean`
|
|
|
|
### 4. Non-Blocking Asks - No actual approval needed
|
|
|
|
These are informational and don't block the agent loop.
|
|
|
|
```typescript
|
|
const nonBlockingAsks = ["command_output"] as const
|
|
```
|
|
|
|
**Helper function:** `isNonBlockingAsk(ask: ClineAsk): boolean`
|
|
|
|
## Client-Side State Detection
|
|
|
|
### ChatView State Management
|
|
|
|
The [`ChatView`](../webview-ui/src/components/chat/ChatView.tsx) component maintains several state variables:
|
|
|
|
```typescript
|
|
const [clineAsk, setClineAsk] = useState<ClineAsk | undefined>(undefined)
|
|
const [enableButtons, setEnableButtons] = useState<boolean>(false)
|
|
const [primaryButtonText, setPrimaryButtonText] = useState<string | undefined>(undefined)
|
|
const [secondaryButtonText, setSecondaryButtonText] = useState<string | undefined>(undefined)
|
|
const [sendingDisabled, setSendingDisabled] = useState(false)
|
|
```
|
|
|
|
### Detection Logic
|
|
|
|
The state is determined by a `useDeepCompareEffect` that watches `lastMessage` and `secondLastMessage`:
|
|
|
|
```typescript
|
|
useDeepCompareEffect(() => {
|
|
if (lastMessage) {
|
|
switch (lastMessage.type) {
|
|
case "ask":
|
|
const isPartial = lastMessage.partial === true
|
|
switch (lastMessage.ask) {
|
|
case "api_req_failed":
|
|
// Agent loop stopped - API failed, needs retry or new task
|
|
setSendingDisabled(true)
|
|
setClineAsk("api_req_failed")
|
|
setEnableButtons(true)
|
|
break
|
|
|
|
case "mistake_limit_reached":
|
|
// Agent loop stopped - too many errors
|
|
setSendingDisabled(false)
|
|
setClineAsk("mistake_limit_reached")
|
|
setEnableButtons(true)
|
|
break
|
|
|
|
case "followup":
|
|
// Agent loop stopped - waiting for user answer
|
|
setSendingDisabled(isPartial)
|
|
setClineAsk("followup")
|
|
setEnableButtons(true)
|
|
break
|
|
|
|
case "tool":
|
|
case "command":
|
|
case "browser_action_launch":
|
|
case "use_mcp_server":
|
|
// Agent loop stopped - waiting for approval
|
|
setSendingDisabled(isPartial)
|
|
setClineAsk(lastMessage.ask)
|
|
setEnableButtons(!isPartial)
|
|
break
|
|
|
|
case "completion_result":
|
|
// Agent loop stopped - task complete
|
|
setSendingDisabled(isPartial)
|
|
setClineAsk("completion_result")
|
|
setEnableButtons(!isPartial)
|
|
break
|
|
|
|
case "resume_task":
|
|
case "resume_completed_task":
|
|
// Agent loop stopped - task paused/completed
|
|
setSendingDisabled(false)
|
|
setClineAsk(lastMessage.ask)
|
|
setEnableButtons(true)
|
|
break
|
|
}
|
|
break
|
|
}
|
|
}
|
|
}, [lastMessage, secondLastMessage])
|
|
```
|
|
|
|
### Streaming Detection
|
|
|
|
To determine if the agent is still streaming a response:
|
|
|
|
```typescript
|
|
const isStreaming = useMemo(() => {
|
|
// Check if current ask has buttons visible
|
|
const isLastAsk = !!modifiedMessages.at(-1)?.ask
|
|
const isToolCurrentlyAsking =
|
|
isLastAsk && clineAsk !== undefined && enableButtons && primaryButtonText !== undefined
|
|
|
|
if (isToolCurrentlyAsking) return false
|
|
|
|
// Check if message is partial (still streaming)
|
|
const isLastMessagePartial = modifiedMessages.at(-1)?.partial === true
|
|
if (isLastMessagePartial) return true
|
|
|
|
// Check if last API request finished (has cost)
|
|
const lastApiReqStarted = findLast(modifiedMessages, (m) => m.say === "api_req_started")
|
|
if (lastApiReqStarted?.text) {
|
|
const cost = JSON.parse(lastApiReqStarted.text).cost
|
|
if (cost === undefined) return true // Still streaming
|
|
}
|
|
|
|
return false
|
|
}, [modifiedMessages, clineAsk, enableButtons, primaryButtonText])
|
|
```
|
|
|
|
## Implementing State Detection in an Alternative Client
|
|
|
|
### Step 1: Subscribe to State Updates
|
|
|
|
```typescript
|
|
// Listen for state messages from extension
|
|
window.addEventListener("message", (event) => {
|
|
const message = event.data
|
|
if (message.type === "state") {
|
|
const clineMessages = message.state.clineMessages
|
|
detectAgentState(clineMessages)
|
|
}
|
|
})
|
|
```
|
|
|
|
### Step 2: Detect Agent State
|
|
|
|
```typescript
|
|
type AgentLoopState =
|
|
| "running" // Agent is actively processing
|
|
| "streaming" // Agent is streaming a response
|
|
| "interactive" // Waiting for tool/command approval
|
|
| "followup" // Waiting for user to answer a question
|
|
| "idle" // Task completed or errored out
|
|
| "resumable" // Task paused, can be resumed
|
|
|
|
function detectAgentState(messages: ClineMessage[]): AgentLoopState {
|
|
const lastMessage = messages.at(-1)
|
|
if (!lastMessage) return "running"
|
|
|
|
// Check if still streaming
|
|
if (lastMessage.partial === true) {
|
|
return "streaming"
|
|
}
|
|
|
|
// Check if it's an ask message
|
|
if (lastMessage.type === "ask" && lastMessage.ask) {
|
|
const ask = lastMessage.ask
|
|
|
|
// Idle states - task effectively stopped
|
|
if (
|
|
[
|
|
"completion_result",
|
|
"api_req_failed",
|
|
"resume_completed_task",
|
|
"mistake_limit_reached",
|
|
"auto_approval_max_req_reached",
|
|
].includes(ask)
|
|
) {
|
|
return "idle"
|
|
}
|
|
|
|
// Resumable state
|
|
if (ask === "resume_task") {
|
|
return "resumable"
|
|
}
|
|
|
|
// Follow-up question
|
|
if (ask === "followup") {
|
|
return "followup"
|
|
}
|
|
|
|
// Interactive approval needed
|
|
if (["command", "tool", "browser_action_launch", "use_mcp_server"].includes(ask)) {
|
|
return "interactive"
|
|
}
|
|
|
|
// Non-blocking (command_output)
|
|
if (ask === "command_output") {
|
|
return "running" // Can proceed or interrupt
|
|
}
|
|
}
|
|
|
|
// Check for API request in progress
|
|
const lastApiReq = messages.findLast((m) => m.say === "api_req_started")
|
|
if (lastApiReq?.text) {
|
|
try {
|
|
const data = JSON.parse(lastApiReq.text)
|
|
if (data.cost === undefined) {
|
|
return "streaming"
|
|
}
|
|
} catch {}
|
|
}
|
|
|
|
return "running"
|
|
}
|
|
```
|
|
|
|
### Step 3: Respond to Agent State
|
|
|
|
```typescript
|
|
// Send response back to extension
|
|
function respondToAsk(response: ClineAskResponse, text?: string, images?: string[]) {
|
|
vscode.postMessage({
|
|
type: "askResponse",
|
|
askResponse: response, // "yesButtonClicked" | "noButtonClicked" | "messageResponse"
|
|
text,
|
|
images,
|
|
})
|
|
}
|
|
|
|
// Start a new task
|
|
function startNewTask(text: string, images?: string[]) {
|
|
vscode.postMessage({
|
|
type: "newTask",
|
|
text,
|
|
images,
|
|
})
|
|
}
|
|
|
|
// Clear current task
|
|
function clearTask() {
|
|
vscode.postMessage({ type: "clearTask" })
|
|
}
|
|
|
|
// Cancel streaming task
|
|
function cancelTask() {
|
|
vscode.postMessage({ type: "cancelTask" })
|
|
}
|
|
|
|
// Terminal operations for command_output
|
|
function terminalOperation(operation: "continue" | "abort") {
|
|
vscode.postMessage({ type: "terminalOperation", terminalOperation: operation })
|
|
}
|
|
```
|
|
|
|
## Response Actions by State
|
|
|
|
| State | Primary Action | Secondary Action |
|
|
| ----------------------- | ---------------------------- | -------------------------- |
|
|
| `api_req_failed` | Retry (`yesButtonClicked`) | New Task (`clearTask`) |
|
|
| `mistake_limit_reached` | Proceed (`yesButtonClicked`) | New Task (`clearTask`) |
|
|
| `followup` | Answer (`messageResponse`) | - |
|
|
| `tool` | Approve (`yesButtonClicked`) | Reject (`noButtonClicked`) |
|
|
| `command` | Run (`yesButtonClicked`) | Reject (`noButtonClicked`) |
|
|
| `browser_action_launch` | Approve (`yesButtonClicked`) | Reject (`noButtonClicked`) |
|
|
| `use_mcp_server` | Approve (`yesButtonClicked`) | Reject (`noButtonClicked`) |
|
|
| `completion_result` | New Task (`clearTask`) | - |
|
|
| `resume_task` | Resume (`yesButtonClicked`) | Terminate (`clearTask`) |
|
|
| `resume_completed_task` | New Task (`clearTask`) | - |
|
|
| `command_output` | Proceed (`continue`) | Kill (`abort`) |
|
|
|
|
## Extension-Side Event Emission
|
|
|
|
The extension emits task state events from [`src/core/task/Task.ts`](../src/core/task/Task.ts):
|
|
|
|
```
|
|
┌─────────────────┐
|
|
│ Task Started │
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
┌────▶│ TaskActive │◀────┐
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ ┌─────────┼─────────┐ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌───┐ ┌───────┐ ┌─────┐ │
|
|
│ │Idle│ │Interact│ │Resume│ │
|
|
│ │Ask │ │iveAsk │ │ableAsk│ │
|
|
│ └─┬──┘ └───┬───┘ └──┬──┘ │
|
|
│ │ │ │ │
|
|
│ ▼ │ │ │
|
|
│ ┌──────┐ │ │ │
|
|
│ │TaskIdle│ │ │ │
|
|
│ └──────┘ │ │ │
|
|
│ ▼ │ │
|
|
│ ┌───────────────┐ │ │
|
|
│ │TaskInteractive│ │ │
|
|
│ └───────┬───────┘ │ │
|
|
│ │ │ │
|
|
│ │ User │ │
|
|
│ │ approves│ │
|
|
│ │ ▼ │
|
|
│ │ ┌───────────┐
|
|
│ │ │TaskResumable│
|
|
│ │ └─────┬─────┘
|
|
│ │ │
|
|
│ │ User │
|
|
│ │ resumes│
|
|
│ │ │
|
|
└──────────────┴────────┘
|
|
```
|
|
|
|
The extension uses helper functions to categorize asks and emit the appropriate events:
|
|
|
|
- `isInteractiveAsk()` → emits `TaskInteractive`
|
|
- `isIdleAsk()` → emits `TaskIdle`
|
|
- `isResumableAsk()` → emits `TaskResumable`
|
|
|
|
## WebviewMessage Types for Responses
|
|
|
|
When responding to asks, use the appropriate `WebviewMessage` type (defined in [`packages/types/src/vscode-extension-host.ts`](../packages/types/src/vscode-extension-host.ts)):
|
|
|
|
```typescript
|
|
interface WebviewMessage {
|
|
type:
|
|
| "askResponse" // Respond to an ask
|
|
| "newTask" // Start a new task
|
|
| "clearTask" // Clear/end current task
|
|
| "cancelTask" // Cancel running task
|
|
| "terminalOperation" // Control terminal output
|
|
// ... many other types
|
|
|
|
askResponse?: ClineAskResponse // "yesButtonClicked" | "noButtonClicked" | "messageResponse" | "objectResponse"
|
|
text?: string
|
|
images?: string[]
|
|
terminalOperation?: "continue" | "abort"
|
|
}
|
|
```
|
|
|
|
## Summary
|
|
|
|
To correctly detect when the agent loop has stopped in an alternative client:
|
|
|
|
1. **Monitor `clineMessages`** from state updates
|
|
2. **Check the last message's `type` and `ask`/`say` properties**
|
|
3. **Check `partial` flag** to detect streaming
|
|
4. **For API request status**, parse the `api_req_started` message's `text` field and check if `cost` is defined
|
|
5. **Use the ask category functions** (`isIdleAsk`, `isInteractiveAsk`, etc.) to determine the appropriate UI state
|
|
6. **Respond with the correct `askResponse` type** based on user action
|
|
|
|
The key insight is that the agent loop stops whenever a message with `type: "ask"` arrives, and the specific `ask` value determines what kind of response the agent is waiting for.
|