Skip to content

feat(agent): let a turn run without a tool-iteration cap - #1370

Open
LivXue wants to merge 2 commits into
mainfrom
feat/unbounded_tool_iterations
Open

LivXue wants to merge 2 commits into
mainfrom
feat/unbounded_tool_iterations

Conversation

@LivXue

@LivXue LivXue commented Nov 20, 2026

Copy link
Copy Markdown
Member

Summary

A turn that runs against a task deadline should be bounded by that clock, not by a count of model calls. Today agents.defaults.maxToolIterations is the only bound, and an explicit "no cap" cannot be expressed: a null or a zero in the config reads as "no answer" and falls back to the built-in default. On a long task that cap is what stops the work, not the deadline.

This change:

  • maxToolIterations accepts null or 0 for "no cap". An absent key still keeps the loop's built-in default, which stays at 40 for every product that does not ask otherwise. A negative value or a non-integer is still "no answer".
  • AgentLoop.max_iterations returns int | None; the loop's iteration check, the exhaustion check, the iteration log line and the wrap-up fallback text all handle "no cap".
  • Raven-Code asks for no cap, and is bounded by a wall clock instead. The code flow gains wallClockSeconds and a code_turn_budget hook that hands it to the loop under the shared turn-budget key. The hook declines when the slice names no clock, so an unset deadline casts nothing.
  • run.py renders --timeout minus a 120 second wrap-up margin into that key, with a 10 second floor. The existing kill at the timeout stays as the backstop: the loop checks a wall clock between iterations, never mid-call, so the last call and the wrap-up have to fit inside the margin.

The global default of 40 is deliberately unchanged; only the products that opt in are unbounded.

Type

  • Feature
  • Fix
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

  • uv run pytest tests/test_config_loader.py tests/test_config_live.py tests/test_agent_loop_iteration_hooks.py -q -> 313 passed, 1 skipped (the skip is the pre-existing POSIX-permission case under root)

  • uv run pytest tests/test_agents_code_flow_plugin.py tests/test_agents_code_flow_exec.py tests/test_agents_code_launcher.py tests/test_acp_modes.py tests/test_agent_loop_dead_end_retry.py -q -> 214 passed

  • uv run pytest tests/test_agent_loop_empty_recovery.py tests/test_agent_loop_session_effort.py tests/test_acp_methods.py tests/test_agent_loop_iteration_hooks.py -q -> 705 passed

  • New tests were written first and failed against the old code: an explicit null or zero now reads as unbounded while absent still keeps the built-in default; an unbounded turn runs past the loop's own cap; the turn-budget hook carries the configured clock and declines without one; --timeout renders the clock with the margin, --timeout 0 renders none, and a very short timeout never yields a negative clock.

  • uv run ruff check and uv run ruff format --check pass on every touched file.

  • scripts/check_source_language.py: the commit's added lines carry no non-ASCII characters.

  • Relevant tests pass locally

  • Relevant lint / type checks pass locally

  • User-facing docs or screenshots are updated when needed

Risk

  • Behaviour change: a config that sets maxToolIterations to null or 0 now runs without a cap. A turn with neither a cap nor a deadline could run indefinitely; that is the caller's choice, and the products that opt in supply a clock.

  • Raven-Code's default config changed from 150 to null. Its launcher always passes a deadline when it has one; a manual run.py without --timeout now has no bound at all.

  • Backward compatible for every config that does not set the key: the built-in 40 is unchanged, and the ACP mode declaration still inherits.

  • Rollback: revert the commit. No persisted state or schema migration is involved.

  • Security impact considered

  • Backward compatibility considered

  • Rollback path is clear for risky changes

Related Issues

N/A

A product with a task deadline should be bounded by its clock, not by a count
of model calls. maxToolIterations now accepts null or zero for "no cap"; an
absent key still keeps the loop's built-in default, which stays at 40 for every
product that does not ask otherwise.

Raven-Code asks for no cap: it runs one turn per task against a wall clock. The
code flow gains wallClockSeconds and a turn-budget hook that hands it to the
loop under the shared turn-budget key. run.py renders --timeout minus a wrap-up
margin into that key, so the turn stops on its own terms instead of being
killed mid-call with nothing committed.

The turn-budget hook is a separate seat that declines when the slice names no
clock, so an unset deadline casts nothing and the product behaves as before.

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Blocking: update the remaining plugin-manifest test to expect the new turn-budget hook.

I reviewed the refreshed github/main...HEAD diff and the relevant loop, live-config, plugin-hook, launcher, ACP mode, and downstream hook/participant paths. I also checked the commit history and repository rules, backward compatibility for absent/positive caps, architecture boundaries, and whether tests were weakened; I found no other blocker and no weakened coverage.

Verification:

  • uv run pytest -q -p no:cacheprovider -n 0 tests/test_agent_loop_iteration_hooks.py tests/test_agents_code_flow_plugin.py tests/test_agents_code_launcher.py tests/test_config_live.py: 280 passed after syncing the full workspace environment.
  • uv run pytest -q -p no:cacheprovider -n 0 tests/test_agents_code_tools_plugin.py::test_the_manifest_contributes_the_seven_tools_beside_the_flows_own_seats: 1 failed, matching the Windows ACP stdio CI failure.
  • uv run ruff check on all changed Python files: passed.
  • git diff --check github/main...HEAD: passed.

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

No blockers; this can merge as far as I am concerned.

The one-line delta updates the remaining manifest contract for code_turn_budget, resolving the prior blocker without weakening the assertion. I re-read the full target diff and checked the repository rules and context vocabulary, the affected loop/config/plugin/launcher callers, commit history, backward compatibility, architecture boundaries, and test coverage. No new defect emerged.

Verification:

  • Focused loop, plugin, launcher, tools-plugin, and live-config suite: 281 passed.
  • Ruff on all changed Python files: passed.
  • git diff --check github/main...HEAD: passed.
  • GitHub CI: all checks passed, including Windows ACP stdio and coverage gates.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Blocking: Raven-Code's ACP hosting and run_task without --timeout now run a turn with no iteration cap and no wall clock; on base both stop at 150.

agents/raven-code/config.json now sets maxToolIterations: null for every hosting, but the wall clock that is meant to replace it is only written when run_task gets a truthy --timeout (run.py:551, if timeout:). Two hostings never get one:

  • ACP, which is the command the host roster launches: subagent.json:7 is run.py --acp, and subagent.json:10 has "timeout": null. render_acp_config calls render_config(source, acp_state, mode=mode) with no timeout (run.py:578).
  • run_task with its default --timeout 0 (run.py:928, "0 (default) means no limit").

In both, make_turn_budget_hook declines (code_flow/flow.py:331-332), nothing is written under TURN_BUDGETS_KEY, live.max_tool_iterations turns the null into 0, WiringMixin.max_iterations returns None, and while iteration_cap is None or ... (turn_path.py:1437) runs until the model stops calling tools. What still ends such a turn is the No-Progress ladder (an identical call with an identical answer) and cancellation; a model that keeps issuing varied calls is not stopped.

This contradicts what the change says about itself. Commit 15c1ec8: "an unset deadline casts nothing and the product behaves as before". FlowConfig.wall_clock_seconds: "zero or absent means the turn has no clock and is bounded by the tool-iteration cap". AgentDefaults.max_tool_iterations: "a cap is for a turn with no deadline".

Measured on head 6e635f2 merged onto main fc0a30f, against base fc0a30f. Real render_acp_config / render_config(unattended=True, timeout=...), load_config, build_runtime, and one USER turn through _process_message; a stub provider returns a glob call with fresh arguments until 160 calls, then answers:

hosting                 base                         head
acp                     cap 150, 150 calls + wrap-up  cap None, no clock, 161 calls (ran to the stub's ceiling)
run_task --timeout 0    cap 150, 150 calls + wrap-up  cap None, no clock, 161 calls
run_task --timeout 900  cap 150, 150 calls + wrap-up  cap None, clock 780 s reaches the loop

A shape that keeps what this change is for: leave config.json at 150 and have render_config drop the cap only in the branch that writes the clock:

    if timeout:
        slice_ = config.setdefault("plugins", {}).setdefault("config", {}).setdefault(FLOW_PLUGIN_ID, {})
        slice_["wallClockSeconds"] = max(10, int(timeout) - WRAPUP_MARGIN_SECONDS)
        config.setdefault("agents", {}).setdefault("defaults", {})["maxToolIterations"] = None

I tried that in a scratch copy: the same probe gives ACP and --timeout 0 cap 150 with 150 calls plus a wrap-up (as on base), and --timeout 900 cap None with the 780 s clock delivered. tests/test_agents_code_launcher.py and tests/test_agents_code_flow_plugin.py still pass there (107 passed together with the probe). A launcher test that renders the ACP config and asserts the cap is still 150 would have caught this.

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Blocking: preserve the 150-iteration cap for Raven-Code hostings that do not install a wall clock.

The new reviewer evidence changes my prior clean stance. I independently verified the rendered configurations: ACP-equivalent hosting produces cap=None, clock=None, default run_task --timeout 0 produces cap=None, clock=None, and only budgeted --timeout 900 produces cap=None, clock=780. Thus the global maxToolIterations: null change removes the existing bound from ordinary ACP and default CLI hosting, even though those paths receive no replacement deadline.

I am not duplicating the existing inline finding or resolving another reviewer's thread. The relevant launcher and code-flow plugin suites still pass (104 tests), confirming that current coverage does not catch these unbounded no-clock paths.

This branch has not been deployed

No deployments
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.

3 participants