Problem
Today, detecting when an agent is stuck (e.g., looping on a login wall, blocked on a captcha, waiting for a 2FA code, retrying the same failing action) is implicit and unreliable. We rely on heuristics over the trajectory rather than the agent telling us directly. This produces:
- Late detection — the agent burns steps/tokens before we surface the issue
- Ambiguous UX — the user sees activity but no clear signal that progress has stopped
- Hard-to-diagnose failures — no first-class reason string explaining why the agent thinks it's stuck
Proposal
Add a new tool to the Browser Harness (and expose it through the agent loop) that lets the agent explicitly emit a stuck state with a free-form message.
stuck(reason: string, details?: string)
Example calls the agent could make:
stuck("Hit a login page and I don't have credentials")
stuck("Blocked on captcha — needs human")
stuck("Site keeps redirecting back to home, can't reach checkout")
stuck("Same selector failed 3 times in a row")
When invoked, the harness should:
- Mark the session as
stuck (new state, distinct from running / done / error)
- Forward the reason string to the AgentPane so the user sees a clear overlay/banner: "Agent is stuck: {reason}"
- Surface a Resume / Provide Input / Stop action so the user can unblock the agent
- Emit a telemetry event so we can analyze stuck patterns over time
Open questions
- Should
stuck halt the run, or just signal and let the agent keep trying? (Lean: halt and wait for user input, similar to a cancel-with-resume.)
- Do we want a structured
category enum (auth, captcha, navigation, selector, unknown) alongside the free-form reason for analytics?
- How does this interact with the existing AgentPane end-state overlay? Likely reuse the unified centered overlay with a sub-line for the stuck reason.
Out of scope
- Auto-detection heuristics — this issue is about giving the agent a way to tell us it's stuck. Heuristic detection is a separate follow-up.
Acceptance criteria
Problem
Today, detecting when an agent is stuck (e.g., looping on a login wall, blocked on a captcha, waiting for a 2FA code, retrying the same failing action) is implicit and unreliable. We rely on heuristics over the trajectory rather than the agent telling us directly. This produces:
Proposal
Add a new tool to the Browser Harness (and expose it through the agent loop) that lets the agent explicitly emit a stuck state with a free-form message.
Example calls the agent could make:
stuck("Hit a login page and I don't have credentials")stuck("Blocked on captcha — needs human")stuck("Site keeps redirecting back to home, can't reach checkout")stuck("Same selector failed 3 times in a row")When invoked, the harness should:
stuck(new state, distinct fromrunning/done/error)Open questions
stuckhalt the run, or just signal and let the agent keep trying? (Lean: halt and wait for user input, similar to a cancel-with-resume.)categoryenum (auth, captcha, navigation, selector, unknown) alongside the free-form reason for analytics?Out of scope
Acceptance criteria
stucktool registered in the harness tool setstuckstate with reason payload