Skip to content

Add agent 'stuck' tool for explicit stuck-state reporting #418

@Cheggin

Description

@Cheggin

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:

  1. Mark the session as stuck (new state, distinct from running / done / error)
  2. Forward the reason string to the AgentPane so the user sees a clear overlay/banner: "Agent is stuck: {reason}"
  3. Surface a Resume / Provide Input / Stop action so the user can unblock the agent
  4. 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

  • New stuck tool registered in the harness tool set
  • Session state machine has a stuck state with reason payload
  • AgentPane renders the stuck reason in the unified overlay with Resume/Stop actions
  • Telemetry event emitted on stuck
  • Docs updated for the new tool

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions