Skip to content

feat(browser): stop a browser step repeated in a row with browser.run.max_repeats - #39296

Merged
javenciu merged 1 commit into
mainfrom
feat/browser-repeat-detector
Nov 19, 2026
Merged

javenciu merged 1 commit into
mainfrom
feat/browser-repeat-detector

Conversation

@javenciu

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a browser task that repeats one step ends with a clear stop report the agent reads, instead of running until the context or the budget is gone.

The browser tool has per-op timeouts (browser_harness/budgets.py) and, inside fast mode, a step and time bar. The ordinary path has no limit on a repeat, and every looped call succeeds, so nothing flags it: a click on the same control, or the same scroll, can repeat dozens of times. #36027 records one such session, where nine documentation pages took 60 to 100 screenshots and the host flagged the repeated scroll calls as a loop that Kiro Crew itself did not stop.

Why it matters

Each wasted step costs a page read or an image, and a loop of 60 identical calls teaches the agent nothing the first three did not. A person away from the screen finds out only from the bill. A stop with a readable answer lets the agent report where it got to, and lets the person decide whether to raise the limit.

Not a goal

  • A cap on the total steps in a chat. That is a separate setting in a follow-up slice.
  • A wall-clock limit. Fast mode keeps its own step and time bar, which this does not touch.
  • Reading page text without screenshots. feat(browser): read a page's text and HTML without screenshots #36027 asks for that and this does not change it.
  • Detecting a loop that alternates between two different steps.
  • Turning the limit on by default.

What changed (motivation → approach → change)

One setting, browser.run.max_repeats, default 0 (off). The gateway's op route, which sees every op of every chat, asks before the op reaches the browser. A stopped op is not run; the answer is a normal tool result (Error (run_budget): ...) that names the setting and how to go on (raise it, take over the browser, or start a new chat).

  • src/kiro_crew/browser_harness/run_budget.py (new): RunCount and check(). The repeat key is a CRC32 checksum plus the length of the op and its arguments as JSON, so a typed value is never kept and typing different text into one field is not a repeat. A refused op is not counted, so the same op stays refused until a different one runs.
  • src/kiro_crew/browser_harness/live_hub.py: the chat's RunCount lives on its hub session, with the chat's other per-session state. It starts again on a takeover (claim) and at the end of the chat's session (reset_run, called where the chat's tabs are closed). No new process-wide state.
  • src/kiro_crew/dashboard/handlers/browser_ops.py: _run_limits() reads the setting for each op (0 when unreadable). _bound_op calls check after the ask branch and before the op runs, so an op held for the person is not counted. With the setting at 0 it never touches the hub.
  • src/kiro_crew/config/sections_browser.py, sections.py: browser.run.max_repeats (BrowserRunConfig), clamped to 0..10,000. config-baseline.json regenerated with scripts/generate_config_baseline.py.
  • Docs: docs/browser-control.md (what the limit does), docs/configuration.md (the key).

Backwards compatibility

With the setting at 0 the route adds no field to any result and answers as on main; test_with_the_setting_off_the_route_answers_as_it_always_did passes on main as well. The new refusal code run_budget can appear only after a person sets the limit. The shim already renders any code as Error (<code>): <text>. Removes nothing.

Tests

  • Before: on main bdc5e2ff9a, 10 of the 12 tests in test/test_browser_run_budget.py fail (no module, no setting). The two that pass pin the default answer and the tool's rendering of a stop report.
  • After: all 12 pass.
  • The route test with the setting off also fails if the check reads a hub session that _bound_op does not have (a NameError answered as browser_error on every op); that is the break the first version had after feat(browser): isolate sign-ins per chat with browser.isolation #37821 split _bound_op out.
  • The whole backend suite on this branch: 279,959 passed, 203 failed, 6 errors. All 209 failing ids also fail on plain main bdc5e2ff9a (decisions, design-tweak, terminal-probe and sandbox files, and test_browser_quick_ask_vault.py's 21 in this environment); none reaches the changed code. The browser, live hub, config, facade, schema, docs and MCP-listing test files: 7,279 passed beside those same 21.
  • flake8, isort, mypy on the changed source files, the repo's black gate, and the comment-history, flake-pattern, wait-discipline, sync-io and lane CI checks pass.
  • Reproduce: python -m pytest test/test_browser_run_budget.py -n0
  • Proof: PROVEN test/test_browser_run_budget.py::test_the_repeat_detector_stops_the_same_op_on_the_same_ref, test/test_browser_run_budget.py::test_a_repeated_scroll_is_stopped_and_a_new_distance_goes_on, test/test_browser_run_budget.py::test_a_takeover_starts_the_count_again, test/test_browser_run_budget.py::test_with_the_setting_off_the_route_answers_as_it_always_did (head 5e8293c, rebased on main)

Manual verification

Not run against a live browser. The route tests drive POST /api/browser/op through api_browser_op with a fake daemon: the third scroll of the same distance under a limit of two answers run_budget and makes no browser call, and a different distance goes on.

Sibling sweep

Sibling: browser_harness/reflex.py (fast mode) -- not affected -- it keeps its own step and time bar; one fast-mode call is one op here
Sibling: mcp_tools/browser.py -- not affected -- it renders the refusal through its existing Error (<code>) path
Sibling: browser_harness/ops.py -- not affected -- the check sits in the route, so run_op and its callers are unchanged

Pattern harvest

Rule candidate: review-prompt
Pattern: a loop guard that answers with a refusal the model reads, keyed on a checksum of the arguments and kept on the chat's own session object, needs no new global state or reset.

Related Issues

Related to #36027, which flagged a repeated-scroll loop. This does not close it.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

….max_repeats

A long browser task can scroll or click the same control dozens of times while every call succeeds, so nothing stops it. With browser.run.max_repeats above 0, the op route refuses the step that would repeat the last one too often and tells the agent to try something else. The count is per chat, restarts on a takeover or when the chat ends, and keeps only a checksum of the arguments. Default 0 leaves every op as it was.
@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners November 18, 2026 22:16
@javenciu
javenciu enabled auto-merge (squash) November 18, 2026 22:16
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 5e8293ca9f8a516d393d7b5d15886c32bf578dcc touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 5e8293ca9f8a516d393d7b5d15886c32bf578dcc — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

The design holds up: the setting is off by default, the check sits at the one route every op passes through, the count lives on the chat's own hub session, and the refusal is an answer the model can read.

Notes

  • The key is the op plus its arguments, so a repeated screenshot or wait while a page loads or animates counts as a loop. Under a small limit the agent loses its polling step. Think about leaving read-only ops out of the count, or say in the docs that they are counted.
  • The count carries over from one turn to the next. After a person says "keep going", the same op is still refused until a different op runs, so the stop report should say that.

[DESIGN-REVIEWED] 5e8293c

Description read

[DESCRIPTION-READ] eef2b548c86c5f65a038f57eb3186c7a0af51c5e91f439bdd034f146f520ad01

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 5e8293ca9f8a516d393d7b5d15886c32bf578dcc — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: the stop is opt-in, has one real consumer, and is not a copy of repeat_loop.py, which leaves browser out on purpose and only sends a notice. The notes below concern the framing.

Notes

  • Item 1 — symptom-level: the Goal says "a browser task that repeats one step ends with a clear stop report", but the diff ships max_repeats: int = field(default=0. The feat(browser): read a page's text and HTML without screenshots #36027 session would loop exactly as it does today unless someone has set the key first, and turning it on is listed under "Not a goal". So on every install that has not set the key, the stated harm stays.
  • Item 1 — inherited premise: src/kiro_crew/repeat_loop.py:39-41 already decided that for browser, "the same result text after the same input is normal, not a loop". The new key counts repeats of the same input alone, and the Sibling sweep does not mention that decision. A long page scrolled at a fixed distance is exactly the case that decision describes. Subtraction: drop the RUN_MAX_REPEATS_CAP/BrowserRunConfig re-exports from config/sections.py:211,216. A grep finds 0 consumers that import them from there.

What this change ships

Inventory (5 items) — 3 justified

Intent: let a person stop a browser agent that repeats one step in a row, and have the agent get a readable reason. ADDITION.

  1. New setting browser.run.max_repeats, off by default, configurable with config set — symptom-level (default off leaves feat(browser): read a page's text and HTML without screenshots #36027 unchanged)
  2. Past the limit, the same op is refused with Error (run_budget) and never reaches the browser — justified
  3. A takeover (claim) starts the count again — justified
  4. When the chat's tabs close, the count starts again — justified
  5. A denied run_budget entry is written to the audit log — undeclared

[FIRST-PRINCIPLES-REVIEWED] 5e8293c

Description read

[DESCRIPTION-READ] ba8a1d8d4b11de52b4898713ed9f84be470f0278fc9679fa8d2b9fc3e0026c36

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 5e8293ca9f8a516d393d7b5d15886c32bf578dcc and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5e8293c

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5e8293ca9f8a516d393d7b5d15886c32bf578dcc false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 5e8293ca9f8a516d393d7b5d15886c32bf578dcc — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • ask returns before run_budget.check, so a quick ask answered without a takeover does not reset the count. This goes against the docs' "any different step counts again from zero".
  • docs/system-specs/modules/browser.md owns the op route, but it does not yet describe the run_budget refusal or the per-session RunCount and when it resets.

[OPUS-REVIEWED] 5e8293c

Verdict parsed from the review's SHA-scoped output markers for commit 5e8293ca9f8a516d393d7b5d15886c32bf578dcc.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5e8293ca9f8a516d393d7b5d15886c32bf578dcc false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own.

This adds an opt-in browser.run.max_repeats setting, off by default (0). It refuses the same browser op when it repeats too many times in a row. The check sits in _bound_op after the hold and ask branches and before run_op, so a refused op never reaches the browser. The setting is read fresh for each op, the same way _report_changes already reads its setting. It falls back to 0 (off) when the config can't be read. With the setting at 0 the route behaves exactly as on main.

The count lives on the chat's own LiveSession. A takeover (claim) starts it again. When a chat ends, the session is cleared with forget, and reset_run also clears it. The repeat key is a CRC32 checksum plus the length of the op and its arguments, so no typed text is stored. The refusal comes back through the tool's existing Error (<code>) path. Its audit entry is written the same way as the route's other refusals.

The config is clamped to 0..10,000, and both config-baseline.json and the round-trip test were updated. The tests are real: 10 of the 12 new tests fail on main. They cover the counting, a stopped scroll at the route with no browser call, the reset on takeover and the readers of the

Tier: 2, held for a person: reviewer-finding: Design Review.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 5e8293ca9f · 381 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This review checked head 5e8293c. The new check runs in _bound_op after the in_control and ask branches and before run_op. A refused op never reaches the browser and is not counted. The count resets on takeover. With browser.run.max_repeats at 0 the route answers as it does on main. The 12 new tests pass and use no sleeps, clocks or ports. PR Readiness is green on this head.

Done well: the fingerprint is a CRC32 plus length of op and args, so no typed text is kept. The count lives on the chat's existing LiveSession, so the change adds no process-wide state.

Optional:

  • Add a short paragraph to docs/system-specs/modules/browser.md, next to the refusal codes. It should cover the run_budget code, where the check runs, and when the count resets.
  • An ask returns before run_budget.check, so it does not restart the count. But browser-control.md and the config help say any different step restarts it. Reset sess.run on an ask, or reword the docs.
  • If the limit is set to 0 and then turned back on, the old count is reused. Keep the fingerprint updated while the limit is off, or reset the count when the limit changes.

@javenciu
javenciu merged commit e89df63 into main Nov 19, 2026
96 of 99 checks passed
@javenciu
javenciu deleted the feat/browser-repeat-detector branch November 19, 2026 00:55
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants