Skip to content

Automate browser based workflows with AI

Task V3: let an action block land its click after a hover, a precursor or a failed click (#8843)

pedrohsdb990abdb08f47
diff --git a/skyvern/forge/agent.py b/skyvern/forge/agent.py
index ff6251465..7ff1f3442 100644
--- a/skyvern/forge/agent.py
+++ b/skyvern/forge/agent.py
@@ -194,7 +194,7 @@ from skyvern.forge.taskv3.goal_check import (
GoalJudge,
)
from skyvern.forge.taskv3.goal_composition import CodeProgressRecord
-from skyvern.forge.taskv3.loop import LoopOutcome, RoundAction
+from skyvern.forge.taskv3.loop import ACTION_BLOCK_TARGET_ACTION_RESERVE, LoopOutcome, RoundAction
from skyvern.forge.taskv3.pre_submit_capture import PreSubmitCaptureRing, is_run_sampled, pre_submit_screenshot
from skyvern.forge.taskv3.run_arms import (
DATE_SEGMENT_AIM_FLAG,
@@ -2627,6 +2627,7 @@ class ForgeAgent:
return step, task
step_cap = min(step_cap, remaining_workflow_steps)
workflow_step_ceiling = remaining_workflow_steps
+ workflow_pool_ceiling = workflow_step_ceiling
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.
@@ -2948,6 +2949,12 @@ class ForgeAgent:
)
# A block that completes on a download is not done by its one action.
single_action_block = isinstance(task_block, ActionBlock) and not task_block.complete_on_download
+ target_action_reserve = 0
+ if single_action_block:
+ # The pinned ceiling above refuses the extension; the reserve answers to the org's run-wide pool.
+ target_action_reserve = ACTION_BLOCK_TARGET_ACTION_RESERVE
+ if workflow_pool_ceiling is not None:
+ target_action_reserve = max(0, min(target_action_reserve, workflow_pool_ceiling - step_cap))
block_completion_judge: GoalJudge | None = None
if single_action_block:
# The run's own model, on its non-flex twin as flex queueing outlasts the judge's timeout.
@@ -3055,6 +3062,7 @@ class ForgeAgent:
label_secret_values=_label_secret_values,
login_identifier_tokens=_login_identifier_tokens,
single_action_block=single_action_block,
+ target_action_reserve=target_action_reserve,
block_completion_judge=block_completion_judge,
code_typed_values=recovery_code_progress.typed_values if recovery_code_progress else (),
)
diff --git a/skyvern/forge/taskv3/engine.py b/skyvern/forge/taskv3/engine.py
index ec0675093..6058f68fa 100644
--- a/skyvern/forge/taskv3/engine.py
+++ b/skyvern/forge/taskv3/engine.py
@@ -305,6 +305,8 @@ async def run_task_v3_agent_loop(
# The workflow system prompt reads a page-derived value, so the re-ask shows it as untrusted data.
unlisted_reask_instructions_untrusted: bool = False,
single_action_block: bool = False,
+ # Extra action rounds a single-action block may spend before its own action lands; see the loop.
+ target_action_reserve: int = 0,
# Asked before a single-action block completes on its step cap.
block_completion_judge: GoalJudge | None = None,
# Appended to the goal, whose Code outline section is last, only as far as the request has room for them.
@@ -636,6 +638,7 @@ async def run_task_v3_agent_loop(
refuse_input_entry=refuse_input_entry,
tool_trail=tool_trail,
single_action_block=single_action_block,
+ target_action_reserve=target_action_reserve,
block_completion_check=_block_completion_check if block_check_on else None,
)
finally:
diff --git a/skyvern/forge/taskv3/loop.py b/skyvern/forge/taskv3/loop.py
index c50696263..edbf3760e 100644
--- a/skyvern/forge/taskv3/loop.py
+++ b/skyvern/forge/taskv3/loop.py
@@ -333,6 +333,8 @@ _HIT_CLASS: ContextVar[dict[str, Any] | None] = ContextVar("taskv3_hit_class", d
_COVERED_LAYER: ContextVar[dict[str, Any] | None] = ContextVar("taskv3_covered_layer", default=None)
# Where a typing call's reach probe ran and whether it scrolled first; set only by that probe.
_TYPE_REACH: ContextVar[dict[str, bool] | None] = ContextVar("taskv3_type_reach", default=None)
+# A click that raised after the page received it (a slow submit whose navigation had not committed).
+_CLICK_DISPATCHED: ContextVar[bool] = ContextVar("taskv3_click_dispatched", default=False)
# The text-delta read's cost and yield for the one tool call this context covers.
_TEXT_DELTA: ContextVar[tuple[float, int | None, int, bool, str | None, int] | None] = ContextVar(
"taskv3_text_delta", default=None
@@ -431,6 +433,10 @@ def record_type_reach(*, acted_in_frame: bool, probe_scrolled: bool, hit_on_docu
_TYPE_REACH.set({key: value or seen.get(key, False) for key, value in new.items()})
+def record_click_dispatched() -> None:
+ _CLICK_DISPATCHED.set(True)
+
+
# What observe() prints and the model hands back, BYTE-IDENTICAL in both directions: the digest
# prints `ref=12` and that exact string is the selector argument, so "copy it as printed" has one
# reading. Deliberately not an attribute-selector shape and deliberately not bracketed -- the ref
@@ -770,6 +776,13 @@ ACTION_BUDGET_EXTENSION_MAX_FACTOR = 3
# Refusals left uncharged in a row before a refusal is charged like any failed call. The repeat guard cannot
# bound them (a stale address resets it), so this does.
UNCHARGED_REFUSAL_GRACE = ACTION_LOOP_NUDGE_AFTER
+# Rounds a single-action block may spend past its cap before its own action has landed. The step engine
+# completes such a block on one SUCCESSFUL step after retrying failed ones, and lets that step batch a
+# precursor; a v3 cap of 1 is spent by a hover, a precursor, or a click that failed without moving the page.
+ACTION_BLOCK_TARGET_ACTION_RESERVE = 2
+# Set on a click result once the driver's click returned, so a later verification error still reads as dispatched.
+CLICK_DISPATCHED_DATA_KEY = "click_dispatched"
+TARGET_ACTION_ROUND_EVENT = "taskv3 loop target action round"
# 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"
@@ -3173,6 +3186,11 @@ class LoopState:
block_completion_offered: bool = False
# A billable action that succeeded moved the tab's URL: evidence the block's action took effect.
block_action_transitioned: bool = False
+ # A billable call that succeeded and did more than reveal state, as a hover or a menu-opening click does. One that
+ # may have submitted, or a failed call that may have moved the page, also sets the second flag: no round follows it.
+ block_action_committed: bool = False
+ block_action_may_have_landed: bool = False
+ target_action_rounds_granted: int = 0
async def run_agent_tool_loop(
@@ -3251,6 +3269,8 @@ async def run_agent_tool_loop(
# A block whose contract is one action: once one succeeded, a follow-up the step cap refuses offers
# finish(completed) instead of failing the block, as the step engine completes it after that step.
single_action_block: bool = False,
+ # Rounds such a block may add, one per cap trip, while its own action has not landed.
+ target_action_reserve: int = 0,
# The goal judge's verdict on that completion; the completion is offered only on its grounded "achieved".
block_completion_check: Callable[[], Awaitable[GoalVerdict]] | None = None,
) -> LoopOutcome:
@@ -3622,6 +3642,47 @@ async def run_agent_tool_loop(
started_at = time.monotonic()
deadline_at = started_at + deadline_seconds if deadline_seconds is not None else None
+ async def _reserve_target_action_round(tool_name: str) -> bool:
+ if (
+ not single_action_block
+ or st.target_action_rounds_granted >= target_action_reserve
+ or st.block_action_transitioned
+ or st.final_turn_granted
+ ):
+ return False
+ verdict: str | None = None
+ if st.block_action_may_have_landed:
+ # A click or Enter may have submitted without moving the URL, and a failed call that moved the page left
+ # it; another round could submit twice or act on the next page.
+ reason = "may_have_landed"
+ elif not st.block_action_committed:
+ reason = "nothing_committed"
+ elif block_completion_check is None:
+ reason = "no_judge"
+ else:
+ try:
+ judged = await block_completion_check()
+ verdict = judged.verdict if judged.skipped_reason is None else None
+ reason = f"judge_{judged.skipped_reason or judged.verdict}"
+ except Exception:
+ LOG.warning("taskv3 target action judge raised", exc_info=True)
+ reason = "judge_error"
+ granted = reason == "nothing_committed" or verdict == "not_achieved"
+ if granted:
+ st.target_action_rounds_granted += 1
+ st.max_action_steps = (st.max_action_steps or 0) + 1
+ LOG.info(
+ TARGET_ACTION_ROUND_EVENT,
+ granted=granted,
+ reason=reason,
+ rounds_granted=st.target_action_rounds_granted,
+ max_action_steps=st.max_action_steps,
+ action_steps=st.action_steps,
+ tool=tool_name,
+ turn=st.turns,
+ )
+ return granted
+
def _extension_gate(extension: int, headroom_gain: tuple[int, int, int]) -> tuple[bool, str]:
refresh_ctx = skyvern_context.current()
if refresh_ctx is not None and refresh_ctx.refresh_working_page:
@@ -4131,6 +4192,7 @@ async def run_agent_tool_loop(
and spec.billable
and st.max_action_steps is not None
and st.action_steps >= st.max_action_steps
+ and not await _reserve_target_action_round(tool_name)
):
base_cap = st.original_action_steps if st.original_action_steps else st.max_action_steps
raw_extension = base_cap // 2
@@ -4173,7 +4235,7 @@ async def run_agent_tool_loop(
and next_tokens <= backstops_for_cap(st.max_action_steps)[2]
and grant_max_turns > st.max_turns
)
- if st.max_action_steps >= extension_limit:
+ if st.max_action_steps - st.target_action_rounds_granted >= extension_limit:
allowed, gate_reason = False, "extension_limit_reached"
elif raw_extension <= 0:
allowed, gate_reason = False, "cap_too_small"
@@ -4313,7 +4375,7 @@ async def run_agent_tool_loop(
)
if judged is not None and judged.verdict == "achieved":
block_reason = (
- f"performed the block's action ({st.billable_actions[0]}); "
+ f"performed the block's action ({st.billable_actions[-1]}); "
"a further action was past the block's step limit"
)
# Through the real handler, so every guard on a completed verdict still applies.
@@ -4415,6 +4477,7 @@ async def run_agent_tool_loop(
_HIT_CLASS.set(None)
_COVERED_LAYER.set(None)
_TYPE_REACH.set(None)
+ _CLICK_DISPATCHED.set(False)
_TEXT_DELTA.set(None)
_TOOL_CALL_SEQ.set(st.total_tool_calls)
dispatch_ctx = skyvern_context.current()
@@ -4696,6 +4759,16 @@ async def run_agent_tool_loop(
st.messages.append(
{"role": "tool", "tool_call_id": tool_call_id, "name": tool_name, "content": transcript_content}
)
+ # The two ways a secret reaches the page: a credential placeholder typed by an entry tool, and a value a
+ # tool registered as secret (a delivered verification code) for the model to type next. `navigate`
+ # resolves placeholders in a URL too.
+ call_entered_secret = (
+ (tool_name in CREDENTIAL_ENTRY_TOOLS or tool_name == "navigate")
+ and bool(_credential_placeholders(args))
+ ) or (dispatch_ctx is not None and len(dispatch_ctx.runtime_secret_values) > runtime_secrets_before)
+ if call_entered_secret and (result.touched_page or not result.refused):
+ # A second round after a secret, ok or failed, could submit it again and spend a lockout attempt.
+ st.block_action_may_have_landed = True
if tool_trail is not None and spec is not None and not spec.terminal:
tool_trail.record(
TrailEntry(
@@ -4704,18 +4777,7 @@ async def run_agent_tool_loop(
content=model_facing_content,
perception=spec.compactable,
page_changing=spec.touches_page and (result.touched_page or not result.refused),
- # The two ways a secret reaches the page: a credential placeholder typed by an
- # entry tool, and a value a tool registered as secret (a delivered verification
- # code) for the model to type next.
- # `navigate` resolves placeholders in a URL too.
- secret_entered=(
- (tool_name in CREDENTIAL_ENTRY_TOOLS or tool_name == "navigate")
- and bool(_credential_placeholders(args))
- )
- or (
- dispatch_ctx is not None
- and len(dispatch_ctx.runtime_secret_values) > runtime_secrets_before
- ),
+ secret_entered=call_entered_secret,
entered=entered_values(tool_name, args),
# Masked like the content, so an unchanged URL compares equal to the one observe prints.
url_before=_trail_url_before(result, skyvern_ctx),
@@ -4871,6 +4933,9 @@ async def run_agent_tool_loop(
)
if spec.billable and result.status == "ok":
st.billable_actions.append(tool_name)
+ if not (tool_name == "hover" or (tool_name == "click" and result_data.get("menu_note"))):
+ st.block_action_committed = True
+ st.block_action_may_have_landed |= _may_submit(tool_name, args)
# click reports it at the top level, navigate inside its action outcome. A navigation that
# landed on an error page moved the URL without doing the block's action.
if not _outcome_reports_failure(round_outcome) and (
@@ -4987,6 +5052,18 @@ async def run_agent_tool_loop(
# document, and the fingerprint may render identically on the new one (a
# same-template step) — absorb it here or the rung survives that blindness.
st.canonical.progress(_ProgressEvidence.PROBE_MISMATCH)
+ # Only a click reports whether the page received it; a failed Enter or code call may have submitted.
+ may_have_submitted = (
+ _CLICK_DISPATCHED.get()
+ or bool(result_data.get(CLICK_DISPATCHED_DATA_KEY))
+ or (tool_name != "click" and _may_submit(tool_name, args))
+ )
+ if spec is not None and spec.billable and (poisoned or may_have_submitted) and not list_left_open:
+ st.block_action_may_have_landed = True
+ elif tool_name in FILL_TOOLS and (result.touched_page or not result.refused):
+ # A failed entry may still have written the field (a partial or other value); only the judge,
+ # which also skips after a typed secret, can say another round is safe.
+ st.block_action_committed = True
if poisoned:
if tool_calls[idx + 1 :]:
if list_left_open:
diff --git a/skyvern/forge/taskv3/tools.py b/skyvern/forge/taskv3/tools.py
index 0946319b1..a80f51a01 100644
--- a/skyvern/forge/taskv3/tools.py
+++ b/skyvern/forge/taskv3/tools.py
@@ -64,6 +64,7 @@ from skyvern.forge.sdk.workflow.models.credential_release import (
from skyvern.forge.taskv3 import input_dispatch
from skyvern.forge.taskv3.loop import (
ACTION_OUTCOME_DATA_KEY,
+ CLICK_DISPATCHED_DATA_KEY,
FILL_TOOLS,
NAVIGATION_DEAD_END_STATUSES,
PAGE_UNAVAILABLE_ERROR,
@@ -79,6 +80,7 @@ from skyvern.forge.taskv3.loop import (
ToolSpec,
current_tool_call_seq,
mark_is_filler,
+ record_click_dispatched,
record_covered_layer,
record_hit_class,
record_resolve_seconds,
@@ -7214,8 +7216,32 @@ _CLICK_PRECHECK_JS = (
)
# Same-document token for the click retry: a navigation destroys window, a pushState does not.
-_CLICK_SAME_DOC_PLANT_JS = "() => { window.__tv3_click_same = 1; }"
+# Also arms a capture listener that records whether the document received a trusted press, so a click that
+# raised afterwards (its navigation not yet committed) is known to have been dispatched.
+_CLICK_SAME_DOC_PLANT_JS = """() => {
+ window.__tv3_click_same = 1;
+ window.__tv3_click_seen = 0;
+ if (!window.__tv3_click_hook) {
+ window.__tv3_click_hook = 1;
+ for (const type of ["pointerdown", "mousedown", "click"]) {
+ window.addEventListener(type, (event) => { if (event.isTrusted) window.__tv3_click_seen = 1; }, true);
+ }
+ }
+}"""
_CLICK_SAME_DOC_CHECK_JS = "() => window.__tv3_click_same === 1"
+_CLICK_SEEN_CHECK_JS = "() => window.__tv3_click_seen === 1"
+
+
+async def _note_click_dispatch(page: Any, *, marker_armed: bool) -> None:
+ try:
+ # An unarmed marker cannot say the press never landed, so it reads as dispatched, the safe side.
+ seen = not marker_armed or await page.evaluate(_CLICK_SEEN_CHECK_JS)
+ except Exception:
+ # The document cannot be read (it may be navigating away): treated as dispatched, the safe side.
+ seen = True
+ if seen:
+ record_click_dispatched()
+
# Planted on window before an option click; a navigation clears window, so its absence afterwards is
# the page saying "different document" even when the post-click probe's own JS is what failed.
@@ -14818,10 +14844,11 @@ def build_browser_tools(
)
base = f"clicked {selector} (hidden native control, toggled directly) — now at {await _url(page)}"
else:
+ marker_armed = True
try:
await page.evaluate(_CLICK_SAME_DOC_PLANT_JS)
except Exception:
- pass
+ marker_armed = False
try:
if label_over_control:
# The probe already answered: the only thing "over" this control is its own label
@@ -14831,6 +14858,7 @@ def build_browser_tools(
else:
await input_dispatch.click(page, selector, timeout=_ACTION_TIMEOUT_MS)
except Exception as e:
+ await _note_click_dispatch(page, marker_armed=marker_armed)
gone = False
try:
gone = not await page.evaluate(_SELECTOR_EXISTS_JS, await _probe_arg(page, selector))
@@ -14904,6 +14932,7 @@ def build_browser_tools(
await page.locator(selector).first.wait_for(state="visible", timeout=3000)
await input_dispatch.click(page, selector, timeout=5000, force=True)
except Exception:
+ await _note_click_dispatch(page, marker_armed=marker_armed)
raise e from None
else:
raise
@@ -14925,6 +14954,7 @@ def build_browser_tools(
"page_transitioned": bool(page_url_before and page_url_after and page_url_after != page_url_before),
# The re-ask's URL rule reads where this click started: its result reports only where it landed.
"url_before": page_url_before,
+ CLICK_DISPATCHED_DATA_KEY: True,
}
if page_url_before and page_url_after and page_url_after != page_url_before:
# Click-driven transitions feed the same visited-URL ring navigate reads, so a later
diff --git a/tests/unit/test_agent_task_v3.py b/tests/unit/test_agent_task_v3.py
index 34b19ed90..8c02b9814 100644
--- a/tests/unit/test_agent_task_v3.py
+++ b/tests/unit/test_agent_task_v3.py
@@ -72,6 +72,7 @@ from skyvern.forge.taskv3.goal_check import BLOCK_COMPLETION_CHECK_PROMPT_NAME
from skyvern.forge.taskv3.goal_composition import CodeProgressRecord, CodeTypedValue
from skyvern.forge.taskv3.handoff_redaction import pin_caller_authored_block_urls
from skyvern.forge.taskv3.loop import (
+ ACTION_BLOCK_TARGET_ACTION_RESERVE,
ACTION_LOOP_GUARD,
NAV_DEAD_END_GUARD,
TOKEN_BUDGET_EXTENDED_EVENT,
@@ -2903,6 +2904,37 @@ async def test_execute_task_v3_atomic_block_ceiling_pinned_to_its_own_cap(monkey
assert loop_mock.await_args.kwargs["max_action_steps_ceiling"] == 5
+ ("pool", "reserve"),
+ [
+ (None, ACTION_BLOCK_TARGET_ACTION_RESERVE),
+ ((40, 50), ACTION_BLOCK_TARGET_ACTION_RESERVE),
+ ((49, 50), 1),
+ ((50, 50), 0),
+ ],
+ ids=["no_pool", "pool_funds_it", "pool_cuts_it", "pool_spent"],
+)
+async def test_execute_task_v3_action_block_target_reserve_answers_to_the_run_pool_not_the_pinned_ceiling(
+ monkeypatch: pytest.MonkeyPatch, pool: tuple[int, int] | None, reserve: int
+) -> None:
+ outcome = LoopOutcome(status="completed", reason="done", billable_actions=["click"])
+ monkeypatch.setattr(ForgeAgent, "_check_workflow_run_step_budget", AsyncMock(return_value=pool))
+ _step, _task, loop_mock, _post = await _run_execute_task_v3(
+ monkeypatch,
+ outcome,
+ task_block=_make_block(ActionBlock, navigation_goal="Click Next"),
+ workflow_run_id="wr_action_reserve",
+ max_steps_per_run=1,
+ data_extraction_goal=None,
+ extracted_information_schema=None,
+ )
+ kwargs = loop_mock.await_args.kwargs
+ assert kwargs["max_action_steps"] == 1
+ assert kwargs["max_action_steps_ceiling"] == 1
+ assert kwargs["target_action_reserve"] == reserve
+
+
class _AdvancingFormPage(_FakePage):
"""Every action advances the form, so the next observe is fresh page-change evidence."""
diff --git a/tests/unit/test_taskv3_loop.py b/tests/unit/test_taskv3_loop.py
index 965be0162..956821473 100644
--- a/tests/unit/test_taskv3_loop.py
+++ b/tests/unit/test_taskv3_loop.py
@@ -36,6 +36,7 @@ from skyvern.forge.taskv3.engine import MAX_TOKENS_CEILING, MAX_TOKENS_PER_ACTIO
from skyvern.forge.taskv3.goal_check import GoalVerdict, ToolTrail, run_goal_check
from skyvern.forge.taskv3.handoff_redaction import ELIDED_URL_PATH, caller_known_published_urls
from skyvern.forge.taskv3.loop import (
+ ACTION_BLOCK_TARGET_ACTION_RESERVE,
ACTION_BUDGET_EXTENDED_EVENT,
ACTION_BUDGET_EXTENSION_MAX_FACTOR,
ACTION_BUDGET_EXTENSION_REFUSED_EVENT,
@@ -43,6 +44,7 @@ from skyvern.forge.taskv3.loop import (
ACTION_LOOP_NUDGE_AFTER,
ACTION_LOOP_TERMINATE_AFTER,
ACTION_OUTCOME_DATA_KEY,
+ CLICK_DISPATCHED_DATA_KEY,
CODE_TOOL_NAME,
FAILURE_EVIDENCE_MIN_TOOL_CALLS,
FAILURE_EVIDENCE_MIN_TURNS,
@@ -65,6 +67,7 @@ from skyvern.forge.taskv3.loop import (
PERCEPTION_STALL_TERMINATE_AFTER,
PROGRESS_LEDGER_SHADOW_EVENT,
PROGRESS_LEDGER_WINDOW,
+ TARGET_ACTION_ROUND_EVENT,
TOKEN_BUDGET_EXTENDED_EVENT,
TOKEN_BUDGET_EXTENSION_REFUSED_EVENT,
UNCHARGED_REFUSAL_GRACE,
@@ -90,6 +93,7 @@ from skyvern.forge.taskv3.loop import (
_RevisitMemory,
current_tool_call_seq,
make_finish_tool,
+ record_click_dispatched,
record_covered_layer,
record_hit_class,
record_resolve_seconds,
@@ -1254,6 +1258,287 @@ async def test_step_cap_block_completion_evidence_log_carries_the_verdict_not_th
assert "482913" not in repr(evidence)
+def _flaky_click(sink: list[dict[str, Any]], fail_first: int, landed: dict[str, Any] | None = None) -> ToolSpec:
+ async def handler(args: dict[str, Any]) -> ToolResult:
+ sink.append(args)
+ if len(sink) <= fail_first:
+ return ToolResult.error("click timed out: element is not stable")
+ return ToolResult.ok("clicked button 'Next'", data=landed if landed is not None else _REACHED_TARGET)
+
+ return ToolSpec(name="click", description="click", parameters={"type": "object"}, handler=handler, billable=True)
+
+
+def _scripted_block_check(*verdicts: GoalVerdict) -> tuple[Callable[[], Awaitable[GoalVerdict]], list[GoalVerdict]]:
+ asked: list[GoalVerdict] = []
+
+ async def check() -> GoalVerdict:
+ verdict = verdicts[min(len(asked), len(verdicts) - 1)]
+ asked.append(verdict)
+ return verdict
+
+ return check, asked
+
+
+_NOT_ACHIEVED = GoalVerdict("not_achieved", "Next", "the next page", None, 0.1)
+_ACHIEVED = GoalVerdict("achieved", "", "", None, 0.1)
+
+
[email protected]("reserve", [0, ACTION_BLOCK_TARGET_ACTION_RESERVE], ids=["no_reserve", "reserve"])
+async def test_a_one_click_block_lands_its_click_after_a_hover_and_a_failed_click(reserve: int) -> None:
+ # Cap 1 is the action block's default. The hover and the click that failed without moving the page did not
+ # do the block's action, so they must not leave the click it asked for unspent (the step engine retries a
+ # failed step and completes on the one that succeeds).
+ hovers: list[tuple[str, dict[str, Any]]] = []
+ clicks: list[dict[str, Any]] = []
+ script = [[("hover", {})], [("click", {})], [("click", {})], [("click", {})]]
+ outcome, _ = await _run(
+ script,
+ [_recording_tool("hover", hovers, billable=True), _flaky_click(clicks, fail_first=1), make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=_achieved_block_check,
+ max_action_steps=1,
+ target_action_reserve=reserve,
+ )
+
+ if reserve:
+ assert outcome.status == "completed"
+ assert "(click)" in outcome.reason
+ assert len(clicks) == 2 # the failed click and the one that landed; the follow-up got the completion
+ else:
+ assert outcome.status == "budget_exhausted"
+ assert clicks == []
+
+
+async def test_a_menu_opening_click_is_a_precursor_like_a_hover() -> None:
+ clicks: list[dict[str, Any]] = []
+ opener = {"menu_note": "listed"}
+
+ async def handler(args: dict[str, Any]) -> ToolResult:
+ clicks.append(args)
+ return ToolResult.ok("clicked", data=opener if len(clicks) == 1 else _REACHED_TARGET)
+
+ click = ToolSpec(name="click", description="click", parameters={"type": "object"}, handler=handler, billable=True)
+ check, asked = _scripted_block_check(_ACHIEVED)
+ script = [[("click", {})], [("click", {})], [("click", {})]]
+ outcome, _ = await _run(
+ script,
+ [click, make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "completed"
+ assert len(clicks) == 2
+ assert len(asked) == 1 # only the completion offer after the landed click; the menu open needed no judge
+
+
+ ("verdict", "granted"),
+ [
+ (_NOT_ACHIEVED, True),
+ (_ACHIEVED, False),
+ (GoalVerdict("impossible", "", "", None, 0.1), False),
+ (GoalVerdict("achieved", "", "", "secret_entered", 0.0), False),
+ (None, False),
+ ],
+ ids=["not_achieved", "achieved", "impossible", "judge_skipped", "judge_raises"],
+)
[email protected]("entry", ["typed", "type_failed"])
+async def test_a_precursor_that_committed_needs_the_judges_not_achieved_for_another_round(
+ verdict: GoalVerdict | None, granted: bool, entry: str
+) -> None:
+ # A typed value can be the block's whole action, and a type that errored may still have written part of it (a
+ # partial credential); only the block judge saying it is not done yet earns a round.
+ types: list[tuple[str, dict[str, Any]]] = []
+ clicks: list[dict[str, Any]] = []
+
+ async def check() -> GoalVerdict:
+ if verdict is None:
+ raise RuntimeError("judge down")
+ return verdict
+
+ script = [[("type", {})], [("click", {})], [("click", {})]]
+ outcome, _ = await _run(
+ script,
+ [
+ _recording_tool("type", types, billable=True)
+ if entry == "typed"
+ else _erroring_tool("type", types, billable=True),
+ _flaky_click(clicks, fail_first=0),
+ make_finish_tool(),
+ ],
+ single_action_block=True,
+ block_completion_check=check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert len(clicks) == (1 if granted else 0)
+ if not granted:
+ assert outcome.status == "budget_exhausted"
+ assert outcome.cap_trip == "Reached the maximum steps (1)"
+
+
+ "landed", ["ok_url_unchanged", "failed_page_moved", "failed_select_moved_url", "failed_enter", "click_unverified"]
+)
+async def test_no_round_is_reserved_after_a_call_that_may_have_submitted_or_left_the_page(landed: str) -> None:
+ # A click that did not move the URL may have submitted, and a failed call that moved the page left it; another
+ # round could submit twice or act on the next page, so the judge is not even asked.
+ clicks: list[tuple[str, dict[str, Any]]] = []
+ tool_name = {"failed_select_moved_url": "select_option", "failed_enter": "press_key"}.get(landed, "click")
+ call_args = {"key": "Enter"} if landed == "failed_enter" else {}
+ if landed == "ok_url_unchanged":
+ click = _recording_tool("click", clicks, billable=True, ok_data={"page_transitioned": False})
+ elif landed == "failed_page_moved":
+ click = _erroring_tool("click", clicks, billable=True, error_data={"page_state_changed": True})
+ elif landed == "click_unverified":
+ click = _erroring_tool("click", clicks, billable=True, error_data={CLICK_DISPATCHED_DATA_KEY: True})
+ elif landed == "failed_select_moved_url":
+ click = _erroring_tool("select_option", clicks, billable=True, error_data={"page_transitioned": True})
+ else:
+ click = _erroring_tool("press_key", clicks, billable=True)
+ check, asked = _scripted_block_check(_NOT_ACHIEVED)
+ script = [[(tool_name, call_args)], [(tool_name, call_args)], [(tool_name, call_args)]]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script,
+ [click, make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "budget_exhausted"
+ assert len(clicks) == 1
+ assert asked == []
+ [decision] = [entry for entry in logs if entry["event"] == TARGET_ACTION_ROUND_EVENT]
+ assert decision["granted"] is False and decision["reason"] == "may_have_landed"
+
+
[email protected]("entry", ["typed", "type_failed"])
+async def test_no_reserve_round_follows_a_typed_secret_even_on_a_not_done_verdict(entry: str) -> None:
+ # A partial or full credential is on the page; a second round could submit it and spend a lockout attempt.
+ types: list[tuple[str, dict[str, Any]]] = []
+ clicks: list[dict[str, Any]] = []
+ secret = {"selector": "#password", "text": "placeholder_TlK9_password"}
+ typer = (
+ _recording_tool("type", types, billable=True)
+ if entry == "typed"
+ else _erroring_tool("type", types, billable=True)
+ )
+ check, asked = _scripted_block_check(_NOT_ACHIEVED)
+ script = [[("type", secret)], [("click", {})], [("click", {})]]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script,
+ [typer, _flaky_click(clicks, fail_first=0), make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "budget_exhausted"
+ assert clicks == [] and asked == []
+ [decision] = [log for log in logs if log["event"] == TARGET_ACTION_ROUND_EVENT]
+ assert decision["reason"] == "may_have_landed"
+
+
+async def test_an_action_that_moved_the_page_goes_to_the_completion_offer_not_the_reserve() -> None:
+ # A select that navigated landed the block's action; a not-done verdict fails the block as before rather than
+ # granting a round on the page it moved to.
+ selects: list[tuple[str, dict[str, Any]]] = []
+ select = _recording_tool("select_option", selects, billable=True, ok_data=_REACHED_TARGET)
+ check, asked = _scripted_block_check(_NOT_ACHIEVED)
+ script = [[("select_option", {})], [("select_option", {})], [("select_option", {})]]
+ outcome, _ = await _run(
+ script,
+ [select, make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "budget_exhausted"
+ assert len(selects) == 1
+ assert len(asked) == 1 # the completion offer's judge only
+
+
[email protected]("dispatched", [True, False], ids=["page_received_it", "never_dispatched"])
+async def test_a_click_that_raised_after_the_page_received_it_gets_no_reserve_round(dispatched: bool) -> None:
+ # A slow submit: the click raised while its navigation had not committed, so the probe reads the same page. A
+ # second click could post the form twice; a click that never reached the page is the retry v1 also makes.
+ clicks: list[dict[str, Any]] = []
+
+ async def handler(args: dict[str, Any]) -> ToolResult:
+ clicks.append(args)
+ if dispatched:
+ record_click_dispatched()
+ raise TimeoutError("click timed out")
+
+ click = ToolSpec(name="click", description="click", parameters={"type": "object"}, handler=handler, billable=True)
+ script = [[("click", {})], [("click", {})], [("click", {})]]
+ with capture_logs() as logs:
+ outcome, _ = await _run(
+ script,
+ [click, make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=_achieved_block_check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "budget_exhausted"
+ [first] = [entry for entry in logs if entry["event"] == TARGET_ACTION_ROUND_EVENT][:1]
+ assert first["granted"] is (not dispatched)
+ assert len(clicks) == (1 if dispatched else 3)
+
+
+async def test_the_target_action_reserve_is_bounded() -> None:
+ clicks: list[dict[str, Any]] = []
+ script = [[("click", {})] for _ in range(8)]
+ outcome, _ = await _run(
+ script,
+ [_flaky_click(clicks, fail_first=99), make_finish_tool()],
+ single_action_block=True,
+ block_completion_check=_achieved_block_check,
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "budget_exhausted"
+ assert len(clicks) == 1 + ACTION_BLOCK_TARGET_ACTION_RESERVE
+
+
+async def test_a_multi_action_block_gets_no_target_action_reserve() -> None:
+ hovers: list[tuple[str, dict[str, Any]]] = []
+ clicks: list[dict[str, Any]] = []
+ script = [[("hover", {})], [("click", {})], [("click", {})]]
+ outcome, _ = await _run(
+ script,
+ [_recording_tool("hover", hovers, billable=True), _flaky_click(clicks, fail_first=0), make_finish_tool()],
+ max_action_steps=1,
+ target_action_reserve=ACTION_BLOCK_TARGET_ACTION_RESERVE,
+ )
+
+ assert outcome.status == "budget_exhausted"
+ assert clicks == []
+
+
@pytest.mark.asyncio
async def test_step_gate_on_the_granted_turn_salvages_a_staged_finish_output() -> None:
# The granted turn batches an over-cap action AND a finish: the refused action voids the
diff --git a/tests/unit/test_taskv3_tools.py b/tests/unit/test_taskv3_tools.py
index 92b304858..ba73dbb6a 100644
--- a/tests/unit/test_taskv3_tools.py
+++ b/tests/unit/test_taskv3_tools.py
@@ -8834,8 +8834,13 @@ class _ClickFakePage:
click_raises: Exception | None = None,
match_counts: list[int] | None = None,
doc_same: bool | None = True,
+ click_seen: bool | None = False,
+ plant_raises: bool = False,
) -> None:
self.url = "https://example.test/results"
+ # whether the document received the press; None => the page cannot be asked
+ self._click_seen = click_seen
+ self._plant_raises = plant_raises
# the post-click "is this still the same document" answer; None => the page cannot be asked
self._doc_same = doc_same
self.calls: list[tuple[str, Any]] = []
@@ -8868,6 +8873,12 @@ class _ClickFakePage:
return self._doc_same
if "__tv3_click_doc = 1" in js:
return None
+ if "__tv3_click_hook" in js and self._plant_raises:
+ raise RuntimeError("plant refused")
+ if "__tv3_click_seen === 1" in js:
+ if self._click_seen is None:
+ raise RuntimeError("Execution context was destroyed, most likely because of a navigation")
+ return self._click_seen
if self._probe_raises:
raise RuntimeError("probe boom")
if "menuOpen" in js:
@@ -9011,6 +9022,8 @@ async def test_click_option_no_commit_errors_loud(monkeypatch: pytest.MonkeyPatc
assert "did not commit" in r.content
assert "Most popular" in r.content
assert "Do not repeat" in r.content
+ # The click fired before the verification failed: an action block must not be granted a second one.
+ assert (r.data or {}).get(taskv3_loop.CLICK_DISPATCHED_DATA_KEY) is True
@pytest.mark.asyncio
@@ -11232,6 +11245,42 @@ async def test_click_timeout_on_live_element_reraises_original() -> None:
await _tool(tools, "click").handler({"selector": "#covered"})
+ ("seen", "plant_raises", "dispatched"),
+ [(True, False, True), (False, False, False), (None, False, True), (False, True, True)],
+ ids=["received", "never", "unreadable", "marker_never_armed"],
+)
[email protected]("covered", [False, True], ids=["reraised", "covered_after_raise"])
+async def test_a_raised_click_reports_whether_the_page_received_it(
+ seen: bool | None, plant_raises: bool, dispatched: bool, covered: bool, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # A slow submit raises after the page took the press; the loop must not grant a single-action block a second
+ # click then. An overlay the submit raised is the covered branch, which returns instead of re-raising.
+ if covered:
+ monkeypatch.setattr(
+ taskv3_tools,
+ "_probe_evaluate",
+ AsyncMock(return_value={"exists": True, "occluded": True, "occluder": {"tag": "div"}}),
+ )
+ page = _ClickFakePage(
+ exists=True,
+ click_raises=TimeoutError("Page.click: Timeout 15000ms exceeded"),
+ click_seen=seen,
+ plant_raises=plant_raises,
+ )
+ tools = build_browser_tools(_fixed_page_provider(page))
+ token = taskv3_loop._CLICK_DISPATCHED.set(False)
+ try:
+ try:
+ await _tool(tools, "click").handler({"selector": "#submit"})
+ except TimeoutError:
+ assert not covered
+ assert taskv3_loop._CLICK_DISPATCHED.get() is dispatched
+ finally:
+ taskv3_loop._CLICK_DISPATCHED.reset(token)
+
+
# --- DOM-level tests: the REAL precheck/finder/after JS against live Chromium, on a faithful mimic
# of the staging widget (conditional-render popover, option nodes REMOUNTED on every toggle). ---