Skip to content

fix(agent-task): honor caller max_turns over package defaults and report turn-cap stops - #2589

Merged
chubes4 merged 1 commit into
mainfrom
fix/agent-task-max-turns
Nov 15, 2026
Merged

chubes4 merged 1 commit into
mainfrom
fix/agent-task-max-turns

Conversation

@chubes4

@chubes4 chubes4 commented Nov 15, 2026

Copy link
Copy Markdown
Collaborator

Refs #2567

Problem

  1. run-agent-task.yml accepts max_turns (default 12), but runtime-package tasks never forwarded it to the agent loop. In Extra-Chill/extrachill run 43726379745 the workflow received MAX_TURNS: 40, yet the docs agent still stopped at turn 12.
  2. When the agent hit the turn cap without giving a final answer, the run was reported as a green no-op. Run 43726382831 finished succeeded with no_changes.

Root cause

  • .github/scripts/run-agent-task/execute-native-agent-task.mjs:746 puts max_turns only on the workload's top level. The wp-codebox/run-runtime-package task input built at :748-770 (workflow: agents/chat, input: {prompt, provider, model}) has no max_turns.
  • packages/cli/src/agent-code.ts:587 (normalizeRuntimeTask) passes the caller's limit only inside task_input. It never puts it in the nested input.input that the package runs from.
  • WP_Codebox_Runtime_Package_Executor::execute_workflow() (class-wp-codebox-runtime-package-executor.php) calls agents/chat using that nested input. Because the input has no max_turns, agents-api resolve_max_turns() (register-default-agents-chat-handler.php:457) falls back to DEFAULT_MAX_TURNS = 12 (:72). That matches the package's meta.default_max_turns: 12, so the caller's 40 never took effect.
  • Turn-cap reporting: agents-api WP_Agent_Conversation_Loop (~:470-510) ends a synthesized max_turns budget silently with completed: true and a natural stop. Nothing downstream could tell a capped run from a finished one.

Fix

Caller max_turns wins

  • The executor script and the CLI's normalizeRuntimeTask now copy the caller's positive max_turns into the run-runtime-package chat input. An explicit input.input.max_turns is kept as is.
  • The PHP runtime-package executor sets the effective limit before calling agents/chat, in this order:
    1. the caller's max_turns
    2. the package's meta.default_max_turns
    3. the handler default
  • It records the result as metadata.turn_limit (wp-codebox/agent-turn-limit/v1, with source: caller|package_default|runtime_default).

Turn-cap stops are reported

  • A run counts as stopped by the turn cap if either:
    • turn_count >= max_turns and the final turn still issued tool calls (so the model never got a turn to answer), or
    • upstream reports stop_reason: max_turns.
  • In that case the executor returns success: false, a max_turns_exceeded error diagnostic, and a canonical wp-codebox/agent-terminal-result/v1 with status: max_turns. WP_Codebox_Runtime_Package_Service passes that terminal result through to the host.
  • WP_Codebox_Agent_Outcome_Classifier also reads the turn-limit record, so remediation outcomes report max_turns_exceeded.

Workflow result

  • New side-effect-free agent-turn-limit-outcome.mjs, written in the same style as fix(agent-task): record runner-workspace apply outcome and upload write evidence #2588's runner-workspace-apply-outcome.mjs. It projects agent_turn_limit from, strongest signal first:
    1. the terminal result
    2. the turn-limit record
    3. a tool call observed on the capped turn
  • When the cap is reached, the workflow result is:
    • status: failed, terminal_status: max_turns, exit code 1
    • failure: {stage: "agent", code: "max_turns_exceeded", classification: "max_turns", max_turns, turn_count, message}
  • In that case the partial work is not applied (workspace_apply.status: skipped), and verification and publication are skipped.
  • The upload projection also carries terminal_status and agent_turn_limit.

Tests

  • tests/agent-task-max-turns.test.ts:
    • the CLI forwards --max-turns into the runtime-package chat input and keeps an explicit nested value;
    • other abilities are left untouched;
    • covers every turn-limit outcome source.
  • scripts/php-runtime-package-max-turns-smoke.php covers:
    • the caller's 40 reaches agents/chat over the package default of 12;
    • the package default applies when the caller sets none;
    • no value is invented when nothing declares one;
    • a capped run with tool calls on the final turn becomes a max_turns terminal result;
    • answering on the final turn is not a cap;
    • an explicit stop reason is honored;
    • the service passes the terminal result through.
  • tests/execute-native-agent-task-lifecycle.test.mjs:
    • asserts that the caller's max_turns reaches the runtime-package chat input;
    • new max-turns mode (terminal result) and max-turns-maintenance mode (the run 43726382831 shape) both fail at stage: agent with max_turns_exceeded;
    • in both modes nothing is applied or published, and the uploaded result shows terminal_status: max_turns.
  • npm run check: passed (332 commands).

AI assistance: Extra Chill Bot (Claude), via a Roadie subagent.

@chubes4
chubes4 merged commit e3508a6 into main Nov 15, 2026
4 of 5 checks passed
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.

1 participant