Skip to content

Automate browser based workflows with AI

Grant one progress-gated extension of the task_v3 action-step budget (SKY-15264) (#8338)

pedrohsdb248fd61a6d2f
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index e7c75fa04..e505105e9 100644
--- a/skyvern/forge/agent.py
+++ b/skyvern/forge/agent.py
@@ -1663,6 +1663,7 @@ class ForgeAgent:
floored_step_cap=floored_step_cap,
)
step_cap = floored_step_cap
+ workflow_step_ceiling: int | None = None
if task_block is not None:
# The org's workflow-run-wide step ceiling binds v3 blocks too: an action round is the
# budget unit (round-stamped action rows make prior v3 rounds count exactly).
@@ -1695,6 +1696,11 @@ class ForgeAgent:
)
return step, task
step_cap = min(step_cap, remaining_workflow_steps)
+ workflow_step_ceiling = remaining_workflow_steps
+ if atomic_block_budget:
+ # A block that owns a deliberately small budget (action/validation) keeps it: the
+ # in-loop extension is refused by pinning the hard ceiling to the cap itself.
+ workflow_step_ceiling = step_cap if workflow_step_ceiling is None else min(workflow_step_ceiling, step_cap)
max_turns, max_tool_calls, max_tokens = taskv3_runaway_backstops(step_cap)
if max_tokens == MAX_TOKENS_CEILING:
# A step cap large enough to hit the token ceiling silently re-caps the run's tokens; make
@@ -1907,6 +1913,7 @@ class ForgeAgent:
# builds Task without it); the caller sources it from the WorkflowRun row.
workflow_permanent_id=workflow_permanent_id,
max_action_steps=step_cap,
+ max_action_steps_ceiling=workflow_step_ceiling,
max_turns=max_turns,
max_tool_calls=max_tool_calls,
max_tokens=max_tokens,
diff --git a/skyvern/forge/taskv3/engine.py b/skyvern/forge/taskv3/engine.py
index 36cd2b13a..20211d0f7 100644
--- a/skyvern/forge/taskv3/engine.py
+++ b/skyvern/forge/taskv3/engine.py
@@ -199,6 +199,7 @@ async def run_task_v3_agent_loop(
max_turns: int = DEFAULT_MAX_TURNS,
max_tool_calls: int = DEFAULT_MAX_TOOL_CALLS,
max_action_steps: int | None = None,
+ max_action_steps_ceiling: int | None = None,
prompt_name: str = "taskv3-agent-loop",
step: Any = None,
should_cancel: Callable[[], Awaitable[bool]] | None = None,
@@ -348,6 +349,7 @@ async def run_task_v3_agent_loop(
max_turns=max_turns,
max_tool_calls=max_tool_calls,
max_action_steps=max_action_steps,
+ max_action_steps_ceiling=max_action_steps_ceiling,
prompt_name=prompt_name,
organization_id=organization_id,
call_kwargs=_build_call_kwargs(step, llm_caller),
diff --git a/skyvern/forge/taskv3/loop.py b/skyvern/forge/taskv3/loop.py
index 4bac653d9..d8985685a 100644
--- a/skyvern/forge/taskv3/loop.py
+++ b/skyvern/forge/taskv3/loop.py
@@ -193,6 +193,18 @@ ACTION_LOOP_TERMINATE_AFTER = 6
# Facetable sibling of PERCEPTION_STALL_REASON_PREFIX; same dashboard contract.
ACTION_LOOP_REASON_PREFIX = "action_loop:"
+# Progress-gated action-step budget extension (SKY-15264): a run that hits its action-step cap while
+# the page is still demonstrably changing (a repeated probe returned fresh content, a navigation or
+# download landed) earns ONE extension of half the original cap — the observed failure population is
+# genuinely long multi-page forms dying mid-progress, while a stalled run must be refused exactly as
+# before. Evidence must be at most this many action rounds old: staler change evidence says nothing
+# about the run's current state.
+ACTION_BUDGET_EXTENSION_EVIDENCE_WINDOW = 8
+# Facetable event names — both the grant and the refusal are queryable so the gate's decision
+# precision is measurable on the canary; change only with the dashboards that read them.
+ACTION_BUDGET_EXTENDED_EVENT = "taskv3 loop action budget extended"
+ACTION_BUDGET_EXTENSION_REFUSED_EVENT = "taskv3 loop action budget extension refused"
+
# Hard "the resource does not exist / is gone" HTTP statuses. A navigation landing on one of these is
# a genuine non-capability dead-end (a dead or removed posting), which v1 routes to `terminated`. Both
# the in-loop `navigate` tool and the pre-loop initial-URL navigation classify against this set. NARROW
@@ -260,11 +272,22 @@ _TV3_MARKER_VALUE_RE = re.compile(r'data-tv3="t\d+(?:-\d+)?"|data-tv3-ref="(?:\d
_TV3_MARKER_CUT_RE = re.compile(r'data-tv3="t\d*(?:-\d*)?(?=[^"]*\Z)|data-tv3-ref="[\d?]*(?=[^"]*\Z)')
+_PERCEPTION_URL_LINE_RE = re.compile(r"^url=\S+", flags=re.MULTILINE)
+
+
def _canonical_perception_content(content: str) -> str:
closed = _TV3_MARKER_VALUE_RE.sub(lambda m: m.group(0).partition("=")[0] + '="*"', content)
return _TV3_MARKER_CUT_RE.sub(lambda m: m.group(0).partition("=")[0] + '="*', closed)
+def _content_only_perception(content: str) -> str:
+ # The URL is a hint, not content: history.pushState moves it without changing the document. The
+ # full canonicalization (URL included) keeps clearing the repeat guards — a wizard whose pages
+ # differ only by URL must survive — but budget-extension evidence hashes THIS, so a URL flip
+ # alone can never earn budget.
+ return _PERCEPTION_URL_LINE_RE.sub("url=*", _canonical_perception_content(content))
+
+
# How many recent states a probe remembers. This length IS the longest oscillation period that can
# be recognised, so it is a detection limit and not a memory tuning knob.
PERCEPTION_RING = 8
@@ -319,6 +342,7 @@ class _PerceptionLedger:
def __init__(self) -> None:
self._probes: dict[tuple[str, str], _ProbeStreak] = {}
self._tools: dict[str, tuple[str, int]] = {}
+ self.content_only: dict[tuple[str, str], deque[str]] = {}
self.shadow_reported = False
self.suppressed_reported = False
@@ -326,6 +350,7 @@ class _PerceptionLedger:
"""Forget every streak: the document they described is gone (a reload)."""
self._probes.clear()
self._tools.clear()
+ self.content_only.clear()
def first_time(self, key: tuple[str, str]) -> bool:
return key not in self._probes
@@ -692,6 +717,69 @@ def _has_hold_headroom(activity: ActivityRecency | None, deadline_at: float | No
return True
+def _budget_extension_gate(
+ action_steps: int,
+ last_change_evidence_step: int | None,
+ action_warned: set[tuple[str, str]],
+ progress_stalled: bool,
+ activity: ActivityRecency | None,
+ deadline_at: float | None,
+ extension: int,
+ seconds_per_step: float | None = None,
+) -> tuple[bool, str]:
+ """Whether an exhausted action-step budget may be extended once, and the deciding reason.
+
+ Progress is the property, not its absence-of-stall proxy: the gate requires POSITIVE recent
+ evidence the page changed (a repeated probe returning fresh content, a navigation or download —
+ the same events that clear the action-retry ledger), then vetoes on any live stall signal, and
+ finally requires the turn/token/deadline headroom to actually fund the extension — granting
+ budget the runaway guards would immediately revoke converts an honest exhaustion into a worse
+ one. The pre-computed turn/tool-call backstops are NOT re-derived from the extended cap: these
+ headroom checks are the margin the extension runs on, so tightening the per-step guard
+ multipliers also tightens what an extension can fund. They are a funding FLOOR sized off the
+ run's own observed burn (turns per step so far, last turn's tokens), not a guarantee the
+ extension completes — the facetable grant/refusal events measure that on the canary."""
+ if (
+ last_change_evidence_step is None
+ or action_steps - last_change_evidence_step > ACTION_BUDGET_EXTENSION_EVIDENCE_WINDOW
+ ):
+ return False, "no_recent_page_change_evidence"
+ if action_warned:
+ return False, "warned_action_retry_streak"
+ if progress_stalled:
+ return False, "no_net_progress_window"
+ if activity is not None and activity.turns_remaining is not None:
+ # Fractional comparison (cross-multiplied): floor division would read 1.9 observed
+ # turns-per-step as 1 and fund an extension the remaining turns cannot run.
+ if (
+ activity.turns_remaining < extension
+ or activity.turns_remaining * max(action_steps, 1) < extension * activity.turn
+ ):
+ return False, "insufficient_turn_headroom"
+ if activity is not None and activity.tool_calls_remaining is not None:
+ # +1 reserves the terminal finish call: funding only the actions trades one budget
+ # exhaustion for another at the very last call.
+ if activity.tool_calls_remaining < extension + 1:
+ return False, "insufficient_tool_call_headroom"
+ if (
+ activity is not None
+ and activity.tokens_remaining is not None
+ and activity.tokens_remaining < extension * max(activity.last_turn_tokens, 1)
+ ):
+ return False, "insufficient_token_headroom"
+ if activity is not None and activity.perception_stall_imminent:
+ return False, "perception_stall_imminent"
+ if deadline_at is not None:
+ # Fund the extension in wall-clock at the run's own observed pace, never below the flat
+ # minimum the deferral gates use.
+ required = FAILURE_EVIDENCE_MIN_DEADLINE_HEADROOM_SECONDS
+ if seconds_per_step is not None:
+ required = max(required, extension * seconds_per_step)
+ if deadline_at - time.monotonic() < required:
+ return False, "insufficient_deadline_headroom"
+ return True, "recent_page_change_evidence"
+
+
@dataclass
class SubmitWatch:
"""The control a click last acted on, and whether a completed verdict has already been held once
@@ -1161,6 +1249,7 @@ async def run_agent_tool_loop(
max_turns: int,
max_tool_calls: int,
max_action_steps: int | None = None,
+ max_action_steps_ceiling: int | None = None,
prompt_name: str = "taskv3-agent-loop",
organization_id: str | None = None,
call_kwargs: dict[str, Any] | None = None,
@@ -1232,17 +1321,25 @@ async def run_agent_tool_loop(
# the warning (and a chance to self-correct) at least one turn before the verdict.
action_counts: dict[tuple[str, str], tuple[int, int]] = {}
action_warned: set[tuple[str, str]] = set()
+ # Progress-gated budget extension (SKY-15264): the action round of the latest positive
+ # page-change evidence, and whether the single extension has been spent.
+ last_change_evidence_step: int | None = None
+ budget_extension_granted = False
def _clear_action_state() -> None:
action_counts.clear()
action_warned.clear()
+ def _note_page_change_evidence() -> None:
+ nonlocal last_change_evidence_step
+ last_change_evidence_step = action_steps
+
async def _consume_refresh_signal(
ctx: SkyvernContext, tool_name: str, remaining: list[Any], round_actions: list[Any], *, drop: bool
) -> bool:
"""Clear the page-refresh signal and, unless dropped or past the cap, reload and void `remaining`."""
nonlocal refresh_cycles, refresh_nudge_due, reload_failed_nudge_due, pending_screenshots, outcome
- nonlocal pending_nav_dead_end, stall_nudges_due
+ nonlocal pending_nav_dead_end, stall_nudges_due, last_change_evidence_step
ctx.refresh_working_page = False
refresh_cycles += 1
if drop:
@@ -1276,8 +1373,11 @@ async def run_agent_tool_loop(
round_actions.append((*reload_record, True))
LOG.info("taskv3 loop honored page refresh signal", tool=tool_name, turn=turns)
# The reloaded document is a new baseline for every ledger that described the old one, and a
- # look taken before it would hand the model marks that no longer exist.
+ # look taken before it would hand the model marks that no longer exist. That includes the
+ # budget-extension evidence stamp: pre-reload progress says nothing about the fresh document,
+ # so the run must re-demonstrate progress before it can earn an extension.
_clear_action_state()
+ last_change_evidence_step = None
perception.reset()
auto_perception.reset()
if activity is not None:
@@ -1320,16 +1420,42 @@ async def run_agent_tool_loop(
# A download landing or a navigation is progress no matter which tool witnessed it or
# whether that call itself errored: re-clicking the button that produces a file (a
# "download next" flow), or re-trying after navigating to a fresh page, is a healthy
- # loop, not a stuck one.
+ # loop, not a stuck one. A same-URL reload is the exception: it resets the retry ledger
+ # like any reload but is a state WIPE, not progress — it clears the extension evidence
+ # exactly like the refresh-signal path.
_clear_action_state()
+ if result_data.get("same_url_reload") or result_data.get("nav_revisit"):
+ # A reload destroys the observed document and a revisit replaces it with a fresh
+ # instance of known territory: re-baseline the perception ledgers (as the refresh
+ # path does) so the first post-navigation look cannot diff against a pre-navigation
+ # digest and read as progress — and clear the evidence stamp in both cases, since
+ # navigation is non-billable and a surviving stamp would stay maximally recent
+ # through any amount of oscillation.
+ perception.reset()
+ auto_perception.reset()
+ nonlocal last_change_evidence_step
+ last_change_evidence_step = None
+ if activity is not None:
+ activity.perception_stall_imminent = False
+ elif result_data.get("download_new") or result_data.get("page_state_changed"):
+ # Only a download detected on THIS call is evidence — a compactable tool replaying
+ # a retained notice re-clears the retry ledger but earns no budget.
+ _note_page_change_evidence()
+ # The old document's perception streak cannot speak for the fresh page: clear the
+ # imminent flag exactly as the refresh path does.
+ if activity is not None:
+ activity.perception_stall_imminent = False
if progress is not None:
progress.hard_progress()
# A click that moved the URL is a real page transition (H1 hard progress) for the shadow
# ledger, but URL equality does NOT prove same-page (a URL-stable SPA form advance) — so only
# the positive direction is acted on, and kept OUT of the branch above so it never clears the
- # action-loop guard's state; this signal is shadow-only and additive.
- if result_data.get("page_transitioned") is True and progress is not None:
- progress.hard_progress()
+ # action-loop guard's state; this signal is shadow-only and additive. It is a URL-only HINT
+ # (history.pushState moves the URL without changing the document), so it never stamps
+ # budget-extension evidence either — the content-confirmed signals are that bar.
+ if result_data.get("page_transitioned") is True:
+ if progress is not None:
+ progress.hard_progress()
return tool_name == "look" and bool(result_data.get("marks_renumbered"))
async def _completion_probe_outcome(
@@ -1363,6 +1489,7 @@ async def run_agent_tool_loop(
tool_name: str,
attribution: dict[str, Any],
*,
+ content_only_digest: str | None = None,
refresh_pending: bool = False,
can_terminate: bool = True,
) -> tuple[LoopOutcome | None, list[tuple[str, int]]]:
@@ -1384,6 +1511,17 @@ async def run_agent_tool_loop(
# terminate verdict, since it fires far more often than the model calls observe on its own
# and would trip those far too eagerly for a path the model never asked to take.
_clear_action_state()
+ # Evidence requires NEW content: a URL-only flip (history.pushState) still clears the
+ # repeat guards above but earns no budget, and neither does a return to a content state
+ # in the probe's recent ring (a panel toggling open and shut).
+ ring = ledger.content_only.get(action_key) if content_only_digest is not None else None
+ if ring and content_only_digest not in ring:
+ _note_page_change_evidence()
+ if content_only_digest is not None:
+ ring = ledger.content_only.get(action_key)
+ if ring is None:
+ ring = ledger.content_only.setdefault(action_key, deque(maxlen=PERCEPTION_RING))
+ ring.append(content_only_digest)
if can_terminate and activity is not None and stall_terminate_after is not None:
# Auto-observe (can_terminate=False) is a path the model never asked to take, so its
# snapshots must not arm this flag: it feeds the failure-evidence retry gate below, and a
@@ -1719,10 +1857,69 @@ async def run_agent_tool_loop(
# Once the action-step budget is spent, refuse a further page action — terminate, mirroring
# the step engine's max-steps stop — but let perception/finish through, since the cap bounds
# new action rounds, not the separate re-observe/finish turn the system prompt asks for.
+ # A run with recent positive page-change evidence earns ONE extension of half the original
+ # cap first (SKY-15264): the observed exhaustion population splits into genuinely long
+ # multi-page forms dying mid-progress (the extension's target) and stalled runs the gate
+ # refuses so they fail exactly as before.
if spec is not None and spec.billable and max_action_steps is not None and action_steps >= max_action_steps:
- outcome = LoopOutcome("budget_exhausted", f"Reached the maximum steps ({max_action_steps})")
- _append_skipped_tool_results(messages, tool_calls[idx:], "action-step budget reached")
- break
+ raw_extension = max_action_steps // 2
+ extension = raw_extension
+ if max_action_steps_ceiling is not None:
+ # The org's workflow-run-wide step pool is a HARD ceiling the extension must
+ # never breach: truncate the grant to what the pool can fund.
+ extension = min(extension, max_action_steps_ceiling - max_action_steps)
+ refresh_ctx = skyvern_context.current()
+ if budget_extension_granted:
+ allowed, gate_reason = False, "already_extended"
+ elif raw_extension <= 0:
+ allowed, gate_reason = False, "cap_too_small"
+ elif extension <= 0:
+ allowed, gate_reason = False, "hard_step_ceiling"
+ elif refresh_ctx is not None and refresh_ctx.refresh_working_page:
+ # A pending refresh voids this very action and re-baselines the page: the grant
+ # must not race it and spend the extension on pre-reload evidence.
+ allowed, gate_reason = False, "refresh_pending"
+ else:
+ allowed, gate_reason = _budget_extension_gate(
+ action_steps,
+ last_change_evidence_step,
+ action_warned,
+ # CURRENT confirmed stalled-ness by the ledger's own rules: form_armed
+ # (the latest look showed a form) plus a window of fruitless actions. Not
+ # the one-shot telemetry latch, and never a bare counter — a form-less page
+ # increments the counter but must not be judged stuck by it.
+ progress is not None
+ and progress.form_armed
+ and progress.actions_since_progress >= progress.window,
+ activity,
+ deadline_at,
+ extension,
+ seconds_per_step=(time.monotonic() - started_at) / max(action_steps, 1),
+ )
+ if allowed:
+ original_cap = max_action_steps
+ budget_extension_granted = True
+ max_action_steps += extension
+ LOG.info(
+ ACTION_BUDGET_EXTENDED_EVENT,
+ original_cap=original_cap,
+ extension=extension,
+ action_steps=action_steps,
+ turn=turns,
+ tool=tool_name,
+ )
+ else:
+ LOG.info(
+ ACTION_BUDGET_EXTENSION_REFUSED_EVENT,
+ gate_reason=gate_reason,
+ max_action_steps=max_action_steps,
+ action_steps=action_steps,
+ turn=turns,
+ tool=tool_name,
+ )
+ outcome = LoopOutcome("budget_exhausted", f"Reached the maximum steps ({max_action_steps})")
+ _append_skipped_tool_results(messages, tool_calls[idx:], "action-step budget reached")
+ break
# Submit-shaped actions (the failure-evidence predicate, minus captcha) are reported BEFORE
# dispatch, since after it the page may be the confirmation page. A failure here never fails
# the action, and the time is not billed to the tool.
@@ -1866,7 +2063,13 @@ async def run_agent_tool_loop(
_progress_observe_shadow(observe_summary, tool_name, attribution)
if content_digest is not None:
stall_outcome, nudges_due = _perception_stall_check(
- perception, content_digest, action_key, tool_name, attribution, refresh_pending=refresh_pending
+ perception,
+ content_digest,
+ action_key,
+ tool_name,
+ attribution,
+ content_only_digest=hashlib.sha256(_content_only_perception(result.content).encode()).hexdigest(),
+ refresh_pending=refresh_pending,
)
stall_nudges_due.extend(nudges_due)
if stall_outcome is not None:
@@ -2232,6 +2435,9 @@ async def run_agent_tool_loop(
ao_action_key,
"observe",
ao_attribution,
+ content_only_digest=hashlib.sha256(
+ _content_only_perception(ao_result.content).encode()
+ ).hexdigest(),
can_terminate=False,
)
if stall_outcome is not None:
diff --git a/skyvern/forge/taskv3/tools.py b/skyvern/forge/taskv3/tools.py
index 3fd9ce303..494ae426a 100644
--- a/skyvern/forge/taskv3/tools.py
+++ b/skyvern/forge/taskv3/tools.py
@@ -21,6 +21,7 @@ import re
import time
import unicodedata
import weakref
+from collections import deque
from enum import Enum
from functools import lru_cache
from typing import TYPE_CHECKING, Any, Awaitable, Callable, NamedTuple
@@ -5930,6 +5931,10 @@ def build_browser_tools(
# refused. A repeat to that URL confirms intent and is allowed — but only if the at-risk state has
# not GROWN since (else a file attached after the refusal would be wiped by a stale confirmation).
_reload_confirm_pending: list[tuple[str, int] | None] = [None]
+ # Canonical URLs recently touched by navigate (both endpoints of each hop, so maxlen=16 spans
+ # the last ~8 hops — hops, not action rounds): a navigation landing back on one is a revisit,
+ # not fresh-page progress, for the budget-extension evidence.
+ _recent_nav_canonicals: deque[str] = deque(maxlen=16)
async def _resolve_page() -> tuple[Any, ToolResult | None]:
# Single-use handoff from the preflight wrapper so a preflighted call resolves the page
@@ -6849,6 +6854,11 @@ def build_browser_tools(
transition_data: dict[str, Any] = {
"page_transitioned": bool(url_before and url_after and url_after != url_before)
}
+ if url_before and url_after and url_after != url_before:
+ # Click-driven transitions feed the same visited-URL ring navigate reads, so a later
+ # navigate back to a click-reached page is classified as a revisit, not fresh territory.
+ _recent_nav_canonicals.append(canonical_url(url_before))
+ _recent_nav_canonicals.append(canonical_url(url_after))
# An already-checked radio legitimately doesn't change on re-click, so the readback is
# skipped for it -- same as the skinned path's short-circuit above.
@@ -8391,7 +8401,8 @@ def build_browser_tools(
# otherwise scores as progress. Refuse it once with an actionable message; a repeat to the same
# URL confirms the model means to reset and is allowed through.
target_canonical = canonical_url(url)
- same_page = canonical_url(await _url(page)) == target_canonical
+ pre_nav_canonical = canonical_url(await _url(page))
+ same_page = pre_nav_canonical == target_canonical
filled = await _count_filled_fields(page) if same_page else 0
if filled > 0:
pending = _reload_confirm_pending[0]
@@ -8432,8 +8443,22 @@ def build_browser_tools(
# dead URLs and blank shells from the model.
status = f" (HTTP {response.status})" if response is not None else ""
# page_state_changed tells the loop's action-loop guard the world moved: a re-attempt after
- # a navigation is a fresh attempt, not a repeat against unchanged state.
+ # a navigation is a fresh attempt, not a repeat against unchanged state. A same-URL reload is
+ # flagged separately: it resets state rather than progressing it, and the loop's budget
+ # extension must not read it as page-change evidence.
data: dict[str, Any] = {"page_state_changed": True}
+ # Classified from where the navigation LANDED, not what was requested: a same-URL request
+ # that redirects somewhere new is a real transition, while any request (alias, redirect,
+ # or the URL itself) landing back on the pre-navigation page is a reload in effect.
+ landed_canonical = canonical_url(landed)
+ if landed_canonical == pre_nav_canonical:
+ data["same_url_reload"] = True
+ elif landed_canonical in _recent_nav_canonicals:
+ # Landing on a page this run recently navigated through (an A->B->A hop) re-visits
+ # known territory: the retry ledger still resets, but it is not fresh-page evidence.
+ data["nav_revisit"] = True
+ _recent_nav_canonicals.append(pre_nav_canonical)
+ _recent_nav_canonicals.append(landed_canonical)
# A hard 404/410 landing is a dead/removed target: flag it so the loop ends the run as
# terminated (v1's behavior) rather than defaulting the outcome to failed.
if response is not None and response.status in NAVIGATION_DEAD_END_STATUSES:
@@ -9002,7 +9027,9 @@ def _apply_download_signal(tools: list[ToolSpec], downloads_dir: str | None) ->
return ToolResult(
result.status,
result.content + "\n" + "\n".join(capped),
- {**(result.data or {}), "download_notice": True},
+ # download_new marks a download detected on THIS call; a compactable tool
+ # replaying retained pending lines carries only download_notice.
+ {**(result.data or {}), "download_notice": True, "download_new": bool(new_lines)},
result.screenshots,
)
except Exception:
diff --git a/tests/unit/test_agent_task_v3.py b/tests/unit/test_agent_task_v3.py
index b93cab534..8521a4df9 100644
--- a/tests/unit/test_agent_task_v3.py
+++ b/tests/unit/test_agent_task_v3.py
@@ -1793,6 +1793,65 @@ async def test_execute_task_v3_workflow_run_ceiling_still_beats_the_floor(
)
assert 7 < 10 < MIN_ACTION_STEPS
assert loop_mock.await_args.kwargs["max_action_steps"] == 10
+ # The pool remainder is also handed to the loop as a HARD ceiling, so the in-loop budget
+ # extension can never grant rounds the org-wide pool cannot fund.
+ assert loop_mock.await_args.kwargs["max_action_steps_ceiling"] == 10
+
+
+async def test_execute_task_v3_workflow_ceiling_above_cap_passes_through(monkeypatch: pytest.MonkeyPatch) -> None:
+ # A pool remainder larger than the block's own cap doesn't clamp the cap, but still flows to the
+ # loop as the ceiling so an extension can only grow into what the pool actually has left.
+ outcome = LoopOutcome(status="completed", reason="done", billable_actions=["click"])
+ block = _make_block(NavigationBlock, navigation_goal="Apply to the job")
+ monkeypatch.setattr(ForgeAgent, "_check_workflow_run_step_budget", AsyncMock(return_value=(1, 30)))
+ _step, _task, loop_mock, _post = await _run_execute_task_v3(
+ monkeypatch,
+ outcome,
+ task_block=block,
+ workflow_run_id="wr_pool_above_cap",
+ max_steps_per_run=7,
+ data_extraction_goal=None,
+ extracted_information_schema=None,
+ )
+ assert loop_mock.await_args.kwargs["max_action_steps"] == MIN_ACTION_STEPS
+ assert loop_mock.await_args.kwargs["max_action_steps_ceiling"] == 30
+
+
+async def test_execute_task_v3_atomic_block_ceiling_pinned_to_its_own_cap(monkeypatch: pytest.MonkeyPatch) -> None:
+ # A block that owns a deliberately small budget (action/validation) must not have it extended:
+ # the hard ceiling is pinned to the cap itself, so the in-loop extension is refused.
+ outcome = LoopOutcome(status="completed", reason="done", billable_actions=["click"])
+ block = _make_block(ActionBlock, navigation_goal="Click the confirm button")
+ _step, _task, loop_mock, _post = await _run_execute_task_v3(
+ monkeypatch,
+ outcome,
+ task_block=block,
+ max_steps_per_run=5,
+ data_extraction_goal=None,
+ extracted_information_schema=None,
+ )
+ assert loop_mock.await_args.kwargs["max_action_steps"] == 5
+ assert loop_mock.await_args.kwargs["max_action_steps_ceiling"] == 5
+
+
+async def test_execute_task_v3_no_workflow_ceiling_without_a_pool(monkeypatch: pytest.MonkeyPatch) -> None:
+ # No org pool -> no hard ceiling: the loop's extension is bounded only by its own gate.
+ outcome = LoopOutcome(status="completed", reason="done", billable_actions=["click"])
+ block = _make_block(NavigationBlock, navigation_goal="Apply to the job")
+ monkeypatch.setattr(ForgeAgent, "_check_workflow_run_step_budget", AsyncMock(return_value=None))
+ _step, _task, loop_mock, _post = await _run_execute_task_v3(
+ monkeypatch,
+ outcome,
+ task_block=block,
+ workflow_run_id="wr_no_pool",
+ max_steps_per_run=7,
+ data_extraction_goal=None,
+ extracted_information_schema=None,
+ )
+ assert loop_mock.await_args.kwargs["max_action_steps_ceiling"] is None
@pytest.mark.asyncio
diff --git a/tests/unit/test_taskv3_loop.py b/tests/unit/test_taskv3_loop.py
index 8ade6766e..d30e0f976 100644
--- a/tests/unit/test_taskv3_loop.py
+++ b/tests/unit/test_taskv3_loop.py
@@ -26,6 +26,8 @@ from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
from skyvern.forge.taskv3 import loop as loop_module
from skyvern.forge.taskv3.loop import (
+ ACTION_BUDGET_EXTENDED_EVENT,
+ ACTION_BUDGET_EXTENSION_REFUSED_EVENT,
ACTION_LOOP_REASON_PREFIX,
FAILURE_EVIDENCE_MIN_TOOL_CALLS,
FAILURE_EVIDENCE_MIN_TURNS,
@@ -48,6 +50,7 @@ from skyvern.forge.taskv3.loop import (
ToolHandler,
ToolResult,
ToolSpec,
+ _budget_extension_gate,
_canonical_perception_content,
_PerceptionLedger,
_ProgressLedger,
@@ -1463,6 +1466,644 @@ async def test_action_step_budget_counts_failed_action_rounds() -> None:
assert len(click_calls) == 1 # 2nd round refused at the budget gate
+async def test_action_step_budget_extends_once_for_a_progressing_run() -> None:
+ # A run whose page keeps changing (a repeated probe returning fresh content) at the cap earns
+ # ONE bounded extension instead of dying mid-progress on a genuinely long form.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", ["page 1", "page 2", "page 3"])
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})], # round 1
+ [("observe", {})], # content changed -> progressed evidence
+ [("click", {"selector": "#b"})], # round 2 == cap
+ [("observe", {})], # fresh evidence again
+ [("click", {"selector": "#c"})], # beyond cap: progress-gated extension (2 -> 3)
+ [("finish", {"status": "completed", "reason": "done"})],
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [observe, click, make_finish_tool()], max_action_steps=2, max_turns=20)
+ assert outcome.status == "completed"
+ assert outcome.action_steps == 3
+ assert len(clicks) == 3
+ extended = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENDED_EVENT]
+ assert len(extended) == 1 and extended[0]["extension"] == 1 and extended[0]["original_cap"] == 2
+
+
+async def test_action_step_budget_no_extension_without_page_change_evidence() -> None:
+ # Absence of stall warnings is NOT progress: a run with no evidence the page ever changed is
+ # refused at the original cap exactly as before, and the refusal is a queryable event.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ script = [[("click", {"selector": "#a"})], [("click", {"selector": "#b"})], [("click", {"selector": "#c"})]]
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [click, make_finish_tool()], max_action_steps=2, max_turns=20)
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert len(refused) == 1 and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_is_granted_at_most_once() -> None:
+ # The grant is single: a run that exhausts cap + extension is refused for good, and the
+ # exhaustion reason names the in-effect (extended) cap.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", [f"page {i}" for i in range(1, 6)])
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})],
+ [("click", {"selector": "#b"})], # cap
+ [("observe", {})],
+ [("click", {"selector": "#c"})], # extension: cap 2 -> 3
+ [("observe", {})],
+ [("click", {"selector": "#d"})], # beyond the extended cap: refused for good
+ ]
+ outcome, _ = await _run(script, [observe, click, make_finish_tool()], max_action_steps=2, max_turns=30)
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (3)" in outcome.reason
+ assert len(clicks) == 3
+
+
+async def test_action_step_budget_extension_refused_without_turn_headroom() -> None:
+ # An extension the remaining turn budget cannot fund is refused — granting steps the runaway
+ # guards would immediately revoke converts an honest exhaustion into a worse one.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", ["page 1", "page 2", "page 3"])
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})],
+ [("click", {"selector": "#b"})],
+ [("observe", {})],
+ [("click", {"selector": "#c"})],
+ ]
+ outcome, _ = await _run(
+ script,
+ [observe, click, make_finish_tool()],
+ max_action_steps=2,
+ max_turns=6,
+ activity=ActivityRecency(),
+ )
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+
+
+async def test_action_step_budget_extension_recovers_after_an_early_stall_window() -> None:
+ # The no-net-progress veto reads CURRENT stalled-ness, not the progress ledger's one-shot
+ # telemetry latch: a run that stalled early, then made sustained hard progress right up to the
+ # cap, earns the extension.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+
+ async def plain_handler(args: dict[str, Any]) -> ToolResult:
+ clicks.append(("click", args))
+ return ToolResult.ok("click done")
+
+ async def transition_handler(args: dict[str, Any]) -> ToolResult:
+ clicks.append(("click_transition", args))
+ return ToolResult.ok("click done", data={"page_transitioned": True})
+
+ observe_n = {"n": 0}
+
+ async def observe_handler(args: dict[str, Any]) -> ToolResult:
+ # Same content while stalling; fresh content once the run recovers, so evidence comes from
+ # a content-confirmed progressed probe (URL-only transitions no longer stamp evidence).
+ observe_n["n"] += 1
+ content = "form page" if observe_n["n"] <= 2 else f"form page {observe_n['n']}"
+ return ToolResult.ok(content, data={"summary": {"invalid_fields": 3}})
+
+ click = ToolSpec(
+ name="click",
+ description="c",
+ parameters={"type": "object", "properties": {}},
+ handler=plain_handler,
+ billable=True,
+ )
+ click_transition = ToolSpec(
+ name="click_transition",
+ description="c",
+ parameters={"type": "object", "properties": {}},
+ handler=transition_handler,
+ billable=True,
+ )
+ observe = ToolSpec(
+ name="observe",
+ description="o",
+ parameters={"type": "object", "properties": {}},
+ handler=observe_handler,
+ compactable=True,
+ )
+ script: list[list[tuple[str, dict[str, Any]]]] = [
+ [("observe", {})], # arms the progress ledger (invalid_fields=3)
+ [("click", {"selector": f"#s{i}"}) for i in range(8)], # one fruitless batch spanning the window
+ [("observe", {})], # flat confirm -> the ledger's shadow latch fires
+ ]
+ for i in range(3): # sustained recovery: hard progress plus content-confirmed fresh observes
+ script.append([("click_transition", {"selector": f"#p{i}"})])
+ script.append([("observe", {})]) # changed content -> progressed probe stamps evidence
+ script.append([("click", {"selector": "#final"})]) # beyond cap: extension must be granted
+ script.append([("finish", {"status": "completed", "reason": "done"})])
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script, [click, click_transition, observe, make_finish_tool()], max_action_steps=4, max_turns=30
+ )
+ assert [entry for entry in logs if entry["event"] == PROGRESS_LEDGER_SHADOW_EVENT] # the latch DID fire
+ assert outcome.status == "completed"
+ assert [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENDED_EVENT]
+
+
+async def test_action_step_budget_extension_not_granted_on_pre_reload_evidence() -> None:
+ # A reload re-baselines every ledger describing the old document, the evidence stamp included:
+ # pre-reload progress says nothing about the fresh page, so the run must re-demonstrate
+ # progress before it can earn an extension.
+ reload_calls: list[None] = []
+
+ async def reload_page() -> None:
+ reload_calls.append(None)
+
+ clicks: list[tuple[str, dict[str, Any]]] = []
+
+ async def click_handler(args: dict[str, Any]) -> ToolResult:
+ clicks.append(("click", args))
+ if args.get("selector") == "#refresh-trigger":
+ skyvern_context.current().refresh_working_page = True
+ return ToolResult.ok("clicked")
+
+ click = ToolSpec(
+ name="click",
+ description="c",
+ parameters={"type": "object", "properties": {}},
+ handler=click_handler,
+ billable=True,
+ )
+ observe = _perception_tool("observe", ["page 1", "page 2"])
+ script: list[list[tuple[str, dict[str, Any]]]] = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})], # progressed -> evidence
+ [("click", {"selector": "#refresh-trigger"})], # round 2 == cap; triggers a reload after
+ [("click", {"selector": "#b"})], # beyond cap, right after the reload: must be refused
+ ]
+ ctx = SkyvernContext(task_id="tsk_ext_reload")
+ skyvern_context.set(ctx)
+ try:
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script, [click, observe, make_finish_tool()], max_action_steps=2, max_turns=20, reload_page=reload_page
+ )
+ finally:
+ skyvern_context.reset()
+ assert len(reload_calls) == 1
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_respects_workflow_run_ceiling() -> None:
+ # An org's workflow-run-wide step pool is a HARD ceiling the extension must never breach: when
+ # the pool remainder supplied the effective cap, a progressing run is still refused.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", ["page 1", "page 2", "page 3"])
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})],
+ [("click", {"selector": "#b"})],
+ [("observe", {})],
+ [("click", {"selector": "#c"})],
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script,
+ [observe, click, make_finish_tool()],
+ max_action_steps=2,
+ max_action_steps_ceiling=2,
+ max_turns=20,
+ )
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "hard_step_ceiling"
+
+
+async def test_action_step_budget_extension_truncated_to_workflow_run_ceiling() -> None:
+ # A pool remainder above the cap but below cap+extension truncates the grant to what the pool
+ # can fund, rather than refusing outright or breaching it.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", [f"page {i}" for i in range(1, 8)])
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})],
+ [("click", {"selector": "#b"})],
+ [("observe", {})],
+ [("click", {"selector": "#c"})],
+ [("observe", {})],
+ [("click", {"selector": "#d"})], # cap 4
+ [("observe", {})],
+ [("click", {"selector": "#e"})], # extension would be 2; ceiling 5 truncates to 1
+ [("finish", {"status": "completed", "reason": "done"})],
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script,
+ [observe, click, make_finish_tool()],
+ max_action_steps=4,
+ max_action_steps_ceiling=5,
+ max_turns=40,
+ )
+ assert outcome.status == "completed"
+ assert outcome.action_steps == 5
+ extended = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENDED_EVENT]
+ assert extended and extended[0]["extension"] == 1
+
+
+async def test_action_step_budget_extension_not_laundered_by_same_url_reload() -> None:
+ # A confirmed same-URL navigate reports page_state_changed (the retry ledger legitimately
+ # resets) but flags same_url_reload: a reset is not progress, so it must CLEAR the extension
+ # evidence exactly like the refresh-signal path, not stamp it.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+
+ async def nav_handler(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok("navigated", data={"page_state_changed": True, "same_url_reload": True})
+
+ navigate = ToolSpec(
+ name="navigate", description="n", parameters={"type": "object", "properties": {}}, handler=nav_handler
+ )
+ script = [
+ [("click", {"selector": "#a"})],
+ [("click", {"selector": "#b"})], # cap
+ [("navigate", {"url": "https://example.test/apply"})], # same-URL reload: not evidence
+ [("click", {"selector": "#c"})], # beyond cap: must be refused
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [click, navigate, make_finish_tool()], max_action_steps=2, max_turns=20)
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_deferred_while_a_refresh_is_pending() -> None:
+ # A pending page-refresh signal voids the very action that would earn the grant and re-baselines
+ # the page: the gate must not race it and spend the extension on pre-reload evidence.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", ["page 1", "page 2"])
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})], # progressed -> evidence
+ [("click", {"selector": "#b"})], # cap reached
+ [("click", {"selector": "#c"})], # over cap; the refresh arrives DURING this model turn
+ ]
+
+ class _RefreshArmingCaller(_ScriptedCaller):
+ async def call(self, **kwargs: Any) -> dict[str, Any]:
+ if self.calls == 4: # the turn whose tool call is the over-cap #c
+ skyvern_context.current().refresh_working_page = True
+ return await super().call(**kwargs)
+
+ ctx = SkyvernContext(task_id="tsk_ext_refresh_race")
+ skyvern_context.set(ctx)
+ try:
+ with capture_logs() as logs:
+ outcome = await run_agent_tool_loop(
+ llm_caller=_RefreshArmingCaller(script),
+ system_prompt="sys",
+ user_prompt="goal",
+ tools=[click, observe, make_finish_tool()],
+ max_action_steps=2,
+ max_turns=20,
+ max_tool_calls=100,
+ )
+ finally:
+ skyvern_context.reset()
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "refresh_pending"
+
+
+async def test_action_step_budget_extension_not_stamped_by_nav_revisit() -> None:
+ # A hop back onto a recently-navigated URL (A->B->A) resets the retry ledger like any
+ # navigation but is known territory — it must not stamp fresh-page extension evidence.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+
+ async def nav_handler(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok("navigated", data={"page_state_changed": True, "nav_revisit": True})
+
+ navigate = ToolSpec(
+ name="navigate", description="n", parameters={"type": "object", "properties": {}}, handler=nav_handler
+ )
+ fresh_nav_calls: list[None] = []
+
+ async def fresh_nav_handler(args: dict[str, Any]) -> ToolResult:
+ fresh_nav_calls.append(None)
+ return ToolResult.ok("navigated", data={"page_state_changed": True})
+
+ fresh_navigate = ToolSpec(
+ name="goto", description="n", parameters={"type": "object", "properties": {}}, handler=fresh_nav_handler
+ )
+ # The real two-hop shape: the A->B hop stamps genuine fresh-page evidence, then the B->A
+ # revisit must CLEAR it — navigation is non-billable, so the action-round clock never advances
+ # and a surviving stamp would stay maximally recent forever.
+ script = [
+ [("click", {"selector": "#a"})],
+ [("click", {"selector": "#b"})], # cap
+ [("goto", {"url": "https://example.test/results"})], # A->B: stamps evidence
+ [("navigate", {"url": "https://example.test/apply"})], # B->A revisit: clears it
+ [("click", {"selector": "#c"})], # beyond cap: refused
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script, [click, navigate, fresh_navigate, make_finish_tool()], max_action_steps=2, max_turns=20
+ )
+ assert len(fresh_nav_calls) == 1
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_not_laundered_by_post_reload_observe() -> None:
+ # A same-URL reload destroys the observed document: the perception ledgers must re-baseline
+ # (as the refresh path does), or the first post-reload observe diffs against the PRE-reload
+ # digest, reads as progressed, and stamps evidence without any progress on the fresh page.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", ["page 1", "page 2", "page 3 reloaded"])
+
+ async def nav_handler(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok("navigated", data={"page_state_changed": True, "same_url_reload": True})
+
+ navigate = ToolSpec(
+ name="navigate", description="n", parameters={"type": "object", "properties": {}}, handler=nav_handler
+ )
+ script = [
+ [("observe", {})],
+ [("click", {"selector": "#a"})],
+ [("observe", {})], # progressed -> evidence
+ [("click", {"selector": "#b"})], # cap
+ [("navigate", {"url": "https://example.test/apply"})], # reload: clears stamp AND ledgers
+ [("observe", {})], # post-reload first look: no baseline, must NOT read as progressed
+ [("click", {"selector": "#c"})], # beyond cap: refused
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script, [click, navigate, observe, make_finish_tool()], max_action_steps=2, max_turns=20
+ )
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_not_stamped_by_url_only_transitions() -> None:
+ # history.pushState moves the URL without changing the document: page_transitioned is a
+ # URL-only hint, and a stalled run varying such clicks (evading the retry-streak veto) must
+ # not launder evidence from it — content-confirmed signals are the evidence bar.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+
+ async def push_state_click(args: dict[str, Any]) -> ToolResult:
+ clicks.append(("click", args))
+ return ToolResult.ok("clicked", data={"page_transitioned": True})
+
+ click = ToolSpec(
+ name="click",
+ description="c",
+ parameters={"type": "object", "properties": {}},
+ handler=push_state_click,
+ billable=True,
+ )
+ script = [
+ [("click", {"selector": "#tab-1"})],
+ [("click", {"selector": "#tab-2"})], # cap; varied selectors keep the retry ledger cold
+ [("click", {"selector": "#tab-3"})], # beyond cap: URL-only hints are not evidence
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [click, make_finish_tool()], max_action_steps=2, max_turns=20)
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ assert len(clicks) == 2
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_granted_on_progressing_non_form_work() -> None:
+ # The no-net-progress veto reads the ledger's own confirmed form-stall state: on a page with no
+ # form, billable rounds still increment the raw counter, but a run demonstrating real progress
+ # (changing probe content) must not be vetoed by a counter the ledger itself refuses to judge.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ observe = _perception_tool("observe", [f"listing page {i}" for i in range(1, 12)])
+ script: list[list[tuple[str, dict[str, Any]]]] = []
+ for i in range(8): # window-many billable rounds on a form-less page, each with fresh content
+ script.append([("observe", {})])
+ script.append([("click", {"selector": f"#item-{i}"})])
+ script.append([("observe", {})])
+ script.append([("click", {"selector": "#next"})]) # beyond cap 8: extension must be granted
+ script.append([("finish", {"status": "completed", "reason": "done"})])
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [observe, click, make_finish_tool()], max_action_steps=8, max_turns=40)
+ assert outcome.status == "completed"
+ assert outcome.action_steps == 9
+ assert [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENDED_EVENT]
+
+
+async def test_action_step_budget_extension_survives_stale_perception_stall_flag() -> None:
+ # perception_stall_imminent armed on the PREVIOUS document must not veto an extension after a
+ # real page change invalidated that streak — positive page-change evidence clears the flag, as
+ # the refresh path already does.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+
+ async def nav_handler(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok("navigated", data={"page_state_changed": True})
+
+ navigate = ToolSpec(
+ name="navigate", description="n", parameters={"type": "object", "properties": {}}, handler=nav_handler
+ )
+ activity = ActivityRecency(perception_stall_imminent=True)
+ script = [
+ [("click", {"selector": "#a"})],
+ [("click", {"selector": "#b"})], # cap
+ [("navigate", {"url": "https://example.test/step-2"})], # fresh page: evidence + flag clear
+ [("click", {"selector": "#c"})], # beyond cap: granted
+ [("finish", {"status": "completed", "reason": "done"})],
+ ]
+ outcome, _ = await _run(
+ script, [click, navigate, make_finish_tool()], max_action_steps=2, max_turns=20, activity=activity
+ )
+ assert outcome.status == "completed"
+ assert outcome.action_steps == 3
+ assert activity.perception_stall_imminent is False
+
+
+async def test_action_step_budget_extension_dries_up_on_content_oscillation() -> None:
+ # A page alternating between two known states (a panel toggling open and shut) is a cycle, not
+ # progress: only genuinely NEW content stamps evidence, so the stamp from the first flip goes
+ # stale and the oscillating run is refused at the cap.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+ contents = ["panel closed", "panel open"]
+ observe = _perception_tool("observe", [contents[i % 2] for i in range(24)])
+ script: list[list[tuple[str, dict[str, Any]]]] = [[("observe", {})]]
+ for i in range(10):
+ script.append([("click", {"selector": f"#toggle-{i}"})]) # varied: retry ledger stays cold
+ script.append([("observe", {})]) # alternating known content
+ script.append([("click", {"selector": "#over-cap"})])
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [observe, click, make_finish_tool()], max_action_steps=10, max_turns=60)
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (10)" in outcome.reason
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+async def test_action_step_budget_extension_not_stamped_by_replayed_download_notice() -> None:
+ # A compactable tool replaying a retained download notice (download_notice without download_new)
+ # re-clears the retry ledger but is not fresh progress: an old download must not keep the
+ # evidence stamp maximally recent forever.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ click = _recording_tool("click", clicks, billable=True)
+
+ async def replay_observe(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok("page\nDownloaded: report.pdf (1.0 MB)", data={"download_notice": True})
+
+ observe = ToolSpec(
+ name="observe",
+ description="o",
+ parameters={"type": "object", "properties": {}},
+ handler=replay_observe,
+ compactable=True,
+ )
+ script = [
+ [("click", {"selector": "#a"})],
+ [("observe", {})], # replayed notice: not evidence
+ [("click", {"selector": "#b"})], # cap
+ [("observe", {})], # replay again
+ [("click", {"selector": "#c"})], # beyond cap: refused
+ ]
+ with capture_logs() as logs:
+ outcome, _ = await _run(script, [click, observe, make_finish_tool()], max_action_steps=2, max_turns=20)
+ assert outcome.status == "budget_exhausted"
+ assert "maximum steps (2)" in outcome.reason
+ refused = [entry for entry in logs if entry["event"] == ACTION_BUDGET_EXTENSION_REFUSED_EVENT]
+ assert refused and refused[0]["gate_reason"] == "no_recent_page_change_evidence"
+
+
+def test_content_only_perception_ignores_the_url_value() -> None:
+ # The URL is a hint, not content: the evidence lane's digest ignores a history.pushState URL
+ # flip (which under auto-observe would otherwise read as a progressed snapshot on a frozen
+ # document), while the full canonicalization keeps the URL so wizard pages that differ only by
+ # URL still clear the repeat guards.
+ from skyvern.forge.taskv3.loop import _content_only_perception
+
+ a = _content_only_perception("url=https://site.test/a title='T' (3 interactive elements)\nbutton#x")
+ b = _content_only_perception("url=https://site.test/b title='T' (3 interactive elements)\nbutton#x")
+ assert a == b
+ c = _content_only_perception("url=https://site.test/a title='T' (4 interactive elements)\nbutton#y")
+ assert a != c # real content changes still differ
+ full_a = _canonical_perception_content("url=https://site.test/a title='T' (3 interactive elements)\nbutton#x")
+ full_b = _canonical_perception_content("url=https://site.test/b title='T' (3 interactive elements)\nbutton#x")
+ assert full_a != full_b # the guard-clearing digest still sees the URL
+
+
+def test_budget_extension_gate_deadline_scales_with_observed_pace() -> None:
+ # Funding the extension in wall-clock: a run that burned ~30s per step cannot run a 5-step
+ # extension in 120s, even though the flat minimum headroom is met.
+ now = time.monotonic()
+ ok, _ = _budget_extension_gate(10, 9, set(), False, None, now + 1200, 5, seconds_per_step=30.0)
+ assert ok
+ assert _budget_extension_gate(10, 9, set(), False, None, now + 120, 5, seconds_per_step=30.0) == (
+ False,
+ "insufficient_deadline_headroom",
+ )
+
+
+def test_budget_extension_gate_vetoes_fire_independently() -> None:
+ ok, reason = _budget_extension_gate(
+ action_steps=10,
+ last_change_evidence_step=9,
+ action_warned=set(),
+ progress_stalled=False,
+ activity=None,
+ deadline_at=None,
+ extension=5,
+ )
+ assert ok and reason == "recent_page_change_evidence"
+ assert _budget_extension_gate(10, None, set(), False, None, None, 5) == (False, "no_recent_page_change_evidence")
+ assert _budget_extension_gate(10, 1, set(), False, None, None, 5) == (False, "no_recent_page_change_evidence")
+ assert _budget_extension_gate(10, 9, {("click", "{}")}, False, None, None, 5) == (
+ False,
+ "warned_action_retry_streak",
+ )
+ assert _budget_extension_gate(10, 9, set(), True, None, None, 5) == (False, "no_net_progress_window")
+ starving = ActivityRecency(turns_remaining=2)
+ assert _budget_extension_gate(10, 9, set(), False, starving, None, 5) == (False, "insufficient_turn_headroom")
+ # The turns requirement scales with the run's own observed turns-per-step burn.
+ thrashy = ActivityRecency(turn=40, turns_remaining=10)
+ assert _budget_extension_gate(10, 9, set(), False, thrashy, None, 5) == (False, "insufficient_turn_headroom")
+ lean = ActivityRecency(turn=12, turns_remaining=10)
+ assert _budget_extension_gate(10, 9, set(), False, lean, None, 5)[0]
+ # Fractional burn must not be floored away: 19 turns over 10 steps is 1.9/step, so a 5-step
+ # extension needs ~9.5 turns — 5 remaining cannot fund it.
+ fractional = ActivityRecency(turn=19, turns_remaining=5)
+ assert _budget_extension_gate(10, 9, set(), False, fractional, None, 5) == (
+ False,
+ "insufficient_turn_headroom",
+ )
+ call_starved = ActivityRecency(tool_calls_remaining=2)
+ assert _budget_extension_gate(10, 9, set(), False, call_starved, None, 5) == (
+ False,
+ "insufficient_tool_call_headroom",
+ )
+ # Exactly-extension calls left funds the actions but not the terminal finish call.
+ call_exact = ActivityRecency(tool_calls_remaining=5)
+ assert _budget_extension_gate(10, 9, set(), False, call_exact, None, 5) == (
+ False,
+ "insufficient_tool_call_headroom",
+ )
+ token_starved = ActivityRecency(tokens_remaining=100, last_turn_tokens=50)
+ assert _budget_extension_gate(10, 9, set(), False, token_starved, None, 5) == (
+ False,
+ "insufficient_token_headroom",
+ )
+ stalling = ActivityRecency(perception_stall_imminent=True)
+ assert _budget_extension_gate(10, 9, set(), False, stalling, None, 5) == (False, "perception_stall_imminent")
+
+
@pytest.mark.asyncio
async def test_on_action_round_fires_once_per_action_round() -> None:
# The callback fires once per action ROUND (a turn with >=1 successful billable action), not per
diff --git a/tests/unit/test_taskv3_tools.py b/tests/unit/test_taskv3_tools.py
index 301c1a02b..9e6b08841 100644
--- a/tests/unit/test_taskv3_tools.py
+++ b/tests/unit/test_taskv3_tools.py
@@ -594,6 +594,89 @@ async def test_navigate_same_url_reload_allowed_on_confirming_repeat(monkeypatch
assert any(c[0] == "goto" for c in page.calls)
+async def test_navigate_same_url_reload_is_flagged_in_result_data(monkeypatch: pytest.MonkeyPatch) -> None:
+ # A confirmed same-URL reload is a state RESET, not progress: the result flags it so the loop
+ # clears (rather than stamps) budget-extension evidence, while a real navigation stays unflagged.
+ page, tools = _reload_guard_tools(monkeypatch, filled=2)
+ await _tool(tools, "navigate").handler({"url": page.url}) # refused; pending set
+ r2 = await _tool(tools, "navigate").handler({"url": page.url}) # confirmed reload
+ assert r2.status == "ok"
+ assert r2.data is not None and r2.data.get("page_state_changed") is True
+ assert r2.data.get("same_url_reload") is True
+ r3 = await _tool(tools, "navigate").handler({"url": "https://example.test/apply/step-2"})
+ assert r3.status == "ok"
+ assert r3.data is not None and r3.data.get("same_url_reload") is None
+
+
+async def test_navigate_redirect_back_to_current_url_is_flagged_as_reload(monkeypatch: pytest.MonkeyPatch) -> None:
+ # A different requested URL (an alias or redirect) that LANDS back on the current canonical URL
+ # is a reload in effect — flagged so the loop treats it as a reset, not fresh-page progress.
+ page, tools = _reload_guard_tools(monkeypatch, filled=0)
+
+ async def bounce(url: str, timeout: int | None = None, wait_until: str | None = None) -> None:
+ page.calls.append(("goto", {"url": url})) # redirects back: page.url never changes
+
+ page.goto = bounce # type: ignore[method-assign]
+ r = await _tool(tools, "navigate").handler({"url": "https://example.test/alias"})
+ assert r.status == "ok", r.content
+ assert r.data is not None and r.data.get("same_url_reload") is True
+
+
+async def test_navigate_same_url_request_redirecting_away_is_not_a_reload(monkeypatch: pytest.MonkeyPatch) -> None:
+ # Requesting the current URL but LANDING somewhere new (a login page redirecting into the app)
+ # is a real transition — classification depends on the landed URL, not the requested one.
+ page, tools = _reload_guard_tools(monkeypatch, filled=0)
+ requested = page.url
+
+ async def redirect_away(url: str, timeout: int | None = None, wait_until: str | None = None) -> None:
+ page.calls.append(("goto", {"url": url}))
+ page.url = "https://example.test/dashboard"
+
+ page.goto = redirect_away # type: ignore[method-assign]
+ r = await _tool(tools, "navigate").handler({"url": requested})
+ assert r.status == "ok", r.content
+ assert r.data is not None and r.data.get("same_url_reload") is None
+
+
+async def test_navigate_hop_back_to_a_recent_url_is_flagged_as_revisit(monkeypatch: pytest.MonkeyPatch) -> None:
+ # An A->B->A hop lands on a page this run recently navigated through: flagged nav_revisit so
+ # the loop does not read known territory as fresh-page progress, while first visits stay clean.
+ page, tools = _reload_guard_tools(monkeypatch, filled=0)
+ a = page.url
+ r1 = await _tool(tools, "navigate").handler({"url": "https://example.test/results"})
+ assert r1.status == "ok" and r1.data is not None
+ assert r1.data.get("nav_revisit") is None # first visit to B
+ r2 = await _tool(tools, "navigate").handler({"url": a})
+ assert r2.status == "ok" and r2.data is not None
+ assert r2.data.get("nav_revisit") is True # back to A: revisit
+ r3 = await _tool(tools, "navigate").handler({"url": "https://example.test/item/3"})
+ assert r3.status == "ok" and r3.data is not None
+ assert r3.data.get("nav_revisit") is None # fresh C stays clean
+
+
+async def test_navigate_back_to_a_click_reached_page_is_flagged_as_revisit(monkeypatch: pytest.MonkeyPatch) -> None:
+ # The first hop away need not use navigate: a click-driven transition feeds the same visited-URL
+ # ring, so a later navigate back to the click-departed page is a revisit, not fresh territory.
+ page, tools = _reload_guard_tools(monkeypatch, filled=0)
+ a = page.url
+
+ async def click_to_results(selector: str, timeout: int | None = None) -> None:
+ page.calls.append(("click", {"selector": selector}))
+ page.url = "https://example.test/results"
+
+ page.click = click_to_results # type: ignore[method-assign]
+ r1 = await _tool(tools, "click").handler({"selector": "#go"})
+ assert r1.data is not None and r1.data.get("page_transitioned") is True
+ r2 = await _tool(tools, "navigate").handler({"url": a})
+ assert r2.status == "ok" and r2.data is not None
+ assert r2.data.get("nav_revisit") is True
+
+
@pytest.mark.asyncio
async def test_navigate_to_a_different_url_is_never_guarded(monkeypatch: pytest.MonkeyPatch) -> None:
# NEGATIVE: the guard must not touch normal multi-page navigation — a DIFFERENT url proceeds even