Skip to content

Automate browser based workflows with AI

Let a page larger than one read be gathered across reads (#8568)

pedrohsdb0e42bf0cc764
diff --git a/skyvern/forge/taskv3/engine.py b/skyvern/forge/taskv3/engine.py
index 896ce2d4f..27813a51a 100644
--- a/skyvern/forge/taskv3/engine.py
+++ b/skyvern/forge/taskv3/engine.py
@@ -102,7 +102,7 @@ How to work:
- Be efficient — this is the whole point of the engine. After observing a form once, fill every field you can before doing anything that reloads the page. Minimize tool calls and turns.
- Batch aggressively: in ONE turn you can `type` into many fields AND `click` many radio/checkbox options AND `select_option` on several dropdowns. Answer a whole form section in a single turn — never spend a separate turn on each click.
- Autocomplete / typeahead / combobox fields (location, school, employer lookups) render suggestions only AFTER you type, and the raw text you type is NOT accepted until you pick a suggestion. Use the `select_combobox` tool (selector + value) for these — it types, waits for the suggestions to render, selects the best-matching one, and verifies the field committed. Do NOT `type` into them or press keys on your own initiative. If `select_combobox` returns an error, the field is genuinely unfilled — never treat it as done. Act on what that error tells you rather than substituting a value of your own: this field commits only the suggestions the page itself offers, and those are often coarser than the value you hold.
-- `observe` already gives you everything you need to fill a field (ref, label, type, current value, options, and the surrounding question text) — act on it directly. `get_html` markup is a rare last resort for ONE specific element `observe` failed to describe: NEVER read a whole page/form/section's markup, NEVER call it twice for the same element, and NEVER inspect more than once before acting. Its text format (the page's visible text) is the one whole-page read that is cheap and honest — use it when the goal is about what the page shows, not where a control is.
+- `observe` already gives you everything you need to fill a field (ref, label, type, current value, options, and the surrounding question text) — act on it directly. `get_html` markup is a rare last resort for ONE specific element `observe` failed to describe: NEVER read a whole page/form/section's markup, NEVER re-read the same element, and NEVER inspect more than once before acting. Its text format (the page's visible text) is the one whole-page read that is cheap and honest — use it when the goal is about what the page shows, not where a control is. A read that reports being cut is the one case where calling `get_html` again is right: it names the total size and the `offset` that continues it, so read on until you have the part you need — that is finishing ONE read, not inspecting twice. Only your last couple of reads stay in this conversation, so as you go, write down in your own words what each part told you — that is what you will still have when the earlier part is gone.
- `look` is a separate last resort for when the TEXT tools are not enough: you can't tell what the page looks like, a control you expect isn't in `observe` (custom or shadow-DOM widgets), or an action isn't taking and you can't tell why. It returns ONE screenshot with every visible control boxed and numbered; then act on a number with `click(mark=N)` or `type(mark=N, text=...)`. Do NOT call `look` to double-check what `observe` already told you, and do not call it every turn — it is for when you are genuinely stuck on something visual.
- Inspecting the page does NOT progress the task — only `type`/`select_option`/`click` do. If your recent turns were mostly `observe`/`get_html` with little typing or clicking, you are stuck inspecting: stop, and fill every field you can from the latest `observe` snapshot using its refs before doing anything else.
- Before calling finish with status=completed, re-check with `observe` that the goal's effect is present in the page's SETTLED, loaded content (no loading indicators or empty panels standing in for it), that every required field holds its intended value, and that the only remaining step is the final submit; fix anything missing first. Call `finish(status, reason, extracted_output)` when the goal is achieved (completed) or impossible/blocked (failed/terminated).
diff --git a/skyvern/forge/taskv3/loop.py b/skyvern/forge/taskv3/loop.py
index 010c4ba98..72f321b01 100644
--- a/skyvern/forge/taskv3/loop.py
+++ b/skyvern/forge/taskv3/loop.py
@@ -69,6 +69,11 @@ ToolErrorClass = Literal[
"identical_rows",
"no_matching_row",
"rows_unread",
+ # A read asked to resume past the end of what it was reading. Not an address failure and not a
+ # page refusal: the call was well-formed and the page cooperated, the offset simply named nothing.
+ "offset_past_end",
+ # The offset itself was unusable — negative, or not a whole number of characters.
+ "invalid_offset",
# The handler raised instead of returning; classified by `_raised_error_class`.
"driver_timeout",
"timeout_other",
@@ -446,6 +451,21 @@ NO_TOOL_CALL_NUDGE = (
PERCEPTION_STALL_NUDGE_AFTER = 6
PERCEPTION_STALL_TERMINATE_AFTER = 15
+# SKY-16330. How many DISTINCT reads of one compactable tool survive compaction. Supersession means a
+# snapshot went stale, and a read of region B does not make a read of region A stale — they answer
+# different questions — so eliding A on B's arrival leaves a document larger than one result
+# impossible to assemble: broad reads are cut at HTML_MAX_CHARS and narrow ones are erased.
+#
+# 2, and the ceiling is what sets it. `st.total_tokens` accumulates the re-sent transcript EVERY turn
+# against DEFAULT_MAX_TOKENS, which exists for exactly this spiral, and the measured failing runs are
+# dying on it — so every retained snapshot costs its size times the turns that follow it. At 2 this
+# holds ~2x HTML_MAX_CHARS of get_html; each further unit is another HTML_MAX_CHARS re-sent ~100
+# times. RAISE ONLY ON MEASURED EVIDENCE that two windows are not enough, not on the intuition that
+# more context helps. It cannot widen a tool whose reads do not differ: observe and look declare no
+# arguments, and the key is built from DECLARED arguments only, so all of their calls share one key
+# and exactly one of each survives, as before — whatever a non-strict provider adds to the call.
+PERCEPTION_SNAPSHOT_RETAIN = 2
+
# Stable, facetable prefix for the stall verdict's reason — telemetry queries key on it to measure
# how often the policy fires; change it only with the dashboards that read it.
PERCEPTION_STALL_REASON_PREFIX = "perception_stall:"
@@ -577,6 +597,12 @@ _TV3_MARKER_VALUE_RE = re.compile(r'data-tv3="t\d+(?:-\d+)?"')
# quote-bearing placeholder — either broken silently brings the leak back.
_TV3_MARKER_CUT_RE = re.compile(r'data-tv3="t\d*(?:-\d*)?(?=[^"]*\Z)')
+# A read can now start at an offset, so a marker can be cut open at the HEAD of a window too. Same
+# leak, same canonicalization, opposite end — but the boundary can land at ANY of the sixteen
+# characters of `data-tv3="tN"`, not only inside the digits, so the pattern is every suffix of the
+# attribute's fixed prefix (longest first) plus the empty one for a cut inside the value. Anchored at
+# the very start of the content, so the only thing it can take is the fragment a window made.
+
# observe prints its own address as `ref=N` at the head of each element line. The number is
# engine-minted identity, not page semantics: a framework that remounts a control between readings
@@ -590,21 +616,52 @@ _TV3_REF_ADDRESS_RE = re.compile(r"^ref=\d+", re.MULTILINE)
_PERCEPTION_URL_LINE_RE = re.compile(r"^url=\S+", flags=re.MULTILINE)
-def _canonical_perception_content(content: str, *, is_observe: bool = False) -> str:
+def _canonical_perception_content(
+ content: str, *, is_observe: bool = False, head_fragment_len: int = 0, notice_at: int | None = None
+) -> str:
# The ref pass is scoped to observe's own payload, not to every compactable result: get_html
# returns page-authored bytes, and a page can write a line that opens `ref=<digits>` there. The
# marker passes below are attribute-shaped and page-authored values in that shape stay significant.
addressed = _TV3_REF_ADDRESS_RE.sub("ref=*", content) if is_observe else content
- closed = _TV3_MARKER_VALUE_RE.sub(lambda m: m.group(0).partition("=")[0] + '="*"', addressed)
+ # Before the marker passes: the notice is what the tail lookahead below scans through, and a
+ # window's head fragment is what the value pattern cannot close.
+ # Only for a read the TOOL said it cut, and only the LAST match — which is then provably the
+ # notice it appended, since our notice comes after all of the window's page content. Folded
+ # unconditionally this reaches page-authored text that merely LOOKS like a notice, in `observe`
+ # and `look` as well, and a page whose notice-shaped numbers change then digests identically on
+ # every read: the stall guard sees frozen and ends a run that was still moving.
+ # Both folds are applied at boundaries the TOOL reported, never by recognizing a shape. Every
+ # prefix of the marker attribute is legal page text, and both the page (a forged unterminated
+ # prefix) and the server (a download filename) can author text wearing the cut notice's shape —
+ # so no pattern and no match-selection rule can tell ours from theirs. Folding something that is
+ # not ours makes content that genuinely differs read as frozen, which the perception-stall guard
+ # TERMINATES on: it ends a run that was still making progress.
+ #
+ # The notice first, because its index is into the string as the tool returned it and the head
+ # fold would shift everything after itself.
+ noticed = addressed
+ if notice_at is not None and 0 <= notice_at < len(addressed):
+ closing = addressed.find("]", notice_at)
+ if closing != -1:
+ noticed = addressed[:notice_at] + "…[*]" + addressed[closing + 1 :]
+ head_folded = '*"' + noticed[head_fragment_len:] if head_fragment_len else noticed
+ closed = _TV3_MARKER_VALUE_RE.sub(lambda m: m.group(0).partition("=")[0] + '="*"', head_folded)
return _TV3_MARKER_CUT_RE.sub(lambda m: m.group(0).partition("=")[0] + '="*', closed)
-def _content_only_perception(content: str, *, is_observe: bool = False) -> str:
+def _content_only_perception(
+ content: str, *, is_observe: bool = False, head_fragment_len: int = 0, notice_at: int | None = None
+) -> 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, is_observe=is_observe))
+ return _PERCEPTION_URL_LINE_RE.sub(
+ "url=*",
+ _canonical_perception_content(
+ content, is_observe=is_observe, head_fragment_len=head_fragment_len, notice_at=notice_at
+ ),
+ )
# How many recent states a probe remembers. This length IS the longest oscillation period that can
@@ -1347,7 +1404,7 @@ def _refresh_nudge_text() -> str:
def _budget_extended_observation(cap: str, recency: ActivityRecency | None) -> str:
"""The retraction of a `_budget_exhausted_observation` whose cap has since been raised.
- APPENDED, never popped: `snapshot_indices` stores absolute message indices, so deleting the
+ APPENDED, never popped: `snapshot_keys` is keyed by absolute message index, so deleting the
stale message would silently re-anchor compaction onto the wrong ones. Without this the model
keeps reading "this is the final turn" for the rest of the run and wraps up early — which spends
the extension the release exists to preserve, through the prompt instead of through a counter."""
@@ -1878,32 +1935,84 @@ def make_finish_tool(
)
+# Caps the arguments an elision placeholder echoes: a selector is model-authored and unbounded.
+_READ_LABEL_MAX_CHARS = 120
+
+
+def _declared_args_key(spec: ToolSpec, args: dict[str, Any]) -> str:
+ """The supersession identity of one read: only the arguments the tool DECLARES.
+
+ A tool's result can depend on an argument it declares and on nothing else, so an undeclared one
+ cannot make two calls different reads. The specs are not emitted strict, so a provider is free to
+ add one — and for an argumentless tool that would split the key and retain two snapshots where the
+ tool only ever describes the page as it is NOW.
+
+ For `look` that is not merely wasted context. Every call disposes the previous handles, clears
+ `_look_manifest` and renumbers the marks (`tools.py`), so a retained older legend describes numbers
+ that now address different controls, and `click(mark=N)` following it acts on the wrong one. It
+ fails open: the stale legend looks perfectly valid. Keyed on declared arguments, `look` and
+ `observe` declare none, so all their calls collapse to one key and exactly one survives.
+ """
+ declared = (spec.parameters or {}).get("properties") or {}
+ return json.dumps({k: v for k, v in args.items() if k in declared}, sort_keys=True, default=str)
+
+
+def _read_label(tool_name: str, args_key: str) -> str:
+ """How an elided snapshot names the read it dropped, e.g. `get_html(selector=#rows, offset=20000)`.
+
+ A tool whose reads cannot differ is named bare, exactly as before: observe and look take no
+ arguments, so decorating them would add a token to every elision and distinguish nothing. The
+ arguments are the model's own, echoed from the assistant message that already carries them, so
+ this discloses nothing the transcript did not already hold — but it is capped anyway, because a
+ selector has no length the model cannot choose.
+ """
+ try:
+ args = json.loads(args_key)
+ except (TypeError, ValueError):
+ return tool_name
+ if not isinstance(args, dict) or not args:
+ return tool_name
+ rendered = ", ".join(f"{k}={args[k]}" for k in sorted(args))
+ if len(rendered) > _READ_LABEL_MAX_CHARS:
+ rendered = rendered[:_READ_LABEL_MAX_CHARS] + "…"
+ return f"{tool_name}({rendered})"
+
+
_COMPACTED_PREFIX = "[superseded "
def _compact_transcript(
messages: list[dict[str, Any]],
- snapshot_indices: set[int],
+ snapshot_keys: dict[int, str],
) -> None:
"""Bound the persistent conversation by eliding stale perception snapshots.
The full transcript is re-sent every turn, so large perception outputs (an `observe` snapshot the
agent has already acted past, or a 20k-char `get_html` dump) otherwise pile up until the token
- backstop trips on perception-heavy pages. `snapshot_indices` holds the message indices of the
- *successful* perception results (recorded as they are appended); keep the newest of each such tool
- and replace older ones' content with a short placeholder. Two things are deliberately protected:
+ backstop trips on perception-heavy pages. `snapshot_keys` maps the message index of each
+ *successful* perception result (recorded as it is appended) to its supersession key; keep the
+ newest snapshot of each of the `PERCEPTION_SNAPSHOT_RETAIN` most recent distinct keys per tool,
+ and replace the rest with a short placeholder.
+
+ The key is the READ, not the tool. A second `observe` is a fresh view of the same thing and
+ genuinely supersedes the first; a `get_html` of one region does not supersede a read of another,
+ and eliding it there is what makes a document larger than one result impossible to assemble.
+ Re-reading the SAME region still supersedes, which is what keeps a run that hammers one read
+ bounded. Three things are deliberately protected:
- The most-recent round (results after the last assistant message) is never touched — a single turn
can batch several perception calls, and compaction runs *before* the model has seen that round's
results, so eliding any of them would drop data the model requested but never read.
- Only a successful snapshot is ever a candidate: a skip/error result is never recorded in
- `snapshot_indices`, so it can neither be elided nor shadow the real snapshot and leave the agent
+ `snapshot_keys`, so it can neither be elided nor shadow the real snapshot and leave the agent
with no usable page view — regardless of content length (a verbose provider error included).
+ - The placeholder NAMES the read it dropped. An erasure the model cannot see is one it cannot
+ plan around: it re-reads by accident instead of by decision, which is the loop this bounds.
Only a `tool` message's content is shrunk, never removed, so every tool_call keeps a matching result
and the transcript stays valid. Eliding also drops the index, so re-running is a no-op and an elided
placeholder can never re-anchor as the live snapshot."""
- if not snapshot_indices:
+ if not snapshot_keys:
return
last_assistant_idx = -1
for i in range(len(messages) - 1, -1, -1):
@@ -1911,14 +2020,30 @@ def _compact_transcript(
last_assistant_idx = i
break
- seen: set[str] = set()
- for i in sorted(snapshot_indices, reverse=True):
+ # Per tool: the reads of the still-unread round, and the distinct keys the retention window has
+ # kept, newest first. A key seen newer — in the unread round or already in the window — is
+ # superseded, because a re-read of one region is a fresher view of the same bytes.
+ #
+ # The unread round is protected but does NOT spend retention slots. It cannot: one turn may batch
+ # several reads (the prompt asks for batching), and counting them against the window would let a
+ # single batched turn evict every earlier read and make accumulation a no-op on exactly the
+ # behaviour the prompt trains. Its size is bounded by the per-turn tool-call budget, and the old
+ # rule protected the whole round the same way, so nothing here widens that.
+ unread: dict[str, set[str]] = {}
+ kept: dict[str, list[str]] = {}
+ for i in sorted(snapshot_keys, reverse=True):
cls = messages[i]["name"]
- if i > last_assistant_idx or cls not in seen:
- seen.add(cls) # the still-unread latest round, or the newest snapshot of this class — keep
+ key = snapshot_keys[i]
+ if i > last_assistant_idx:
+ unread.setdefault(cls, set()).add(key)
+ continue
+ window = kept.setdefault(cls, [])
+ seen_newer = key in unread.get(cls, frozenset()) or key in window
+ if not seen_newer and len(window) < PERCEPTION_SNAPSHOT_RETAIN:
+ window.append(key)
continue
- messages[i]["content"] = f"{_COMPACTED_PREFIX}{cls} output elided to bound context]"
- snapshot_indices.discard(i)
+ messages[i]["content"] = f"{_COMPACTED_PREFIX}{_read_label(cls, key)} output elided to bound context]"
+ del snapshot_keys[i]
@dataclass(kw_only=True, slots=True)
@@ -1998,8 +2123,11 @@ class LoopState:
# assistant reply or tool results itself, so multi-turn tool use must be threaded here.
messages: list[dict[str, Any]] = field(default_factory=list)
# Indices into `messages` of successful perception results, recorded as they are appended so
- # compaction can keep only the newest of each without inferring "real snapshot" from content size.
- snapshot_indices: set[int] = field(default_factory=set)
+ # compaction can keep the newest without inferring "real snapshot" from content size. The value is
+ # the read's supersession key — the loop's own `action_key`, the (tool, args) identity the
+ # perception-stall policy already calls "the same probe". Keying on the tool name alone would make
+ # a read of one region supersede a read of another.
+ snapshot_keys: dict[int, str] = field(default_factory=dict)
perception: _PerceptionLedger = field(default_factory=_PerceptionLedger)
# Net-progress ledger (additive shadow); None disables it, mirroring the guard's *_after knobs.
progress: _ProgressLedger | None = None
@@ -2483,7 +2611,7 @@ async def run_agent_tool_loop(
# Elide superseded perception results before re-sending the transcript, so a perception-heavy
# run can't balloon the context to the token backstop (the pre-compaction runaway mode).
- _compact_transcript(st.messages, st.snapshot_indices)
+ _compact_transcript(st.messages, st.snapshot_keys)
llm_caller.message_history = list(st.messages)
# Consume any pending look image into THIS call only, then clear: the image rides one request
# and is never appended to `messages`, so the turn after carries zero image blocks.
@@ -3031,9 +3159,24 @@ async def run_agent_tool_loop(
action_key = (tool_name, json.dumps(args, sort_keys=True, default=str))
attribution: dict[str, Any] = {"action_key_hash": telemetry_hash(telemetry_salt, *action_key)}
content_digest: str | None = None
+ # Whether this result is markup a window cut open — the only thing that can carry a
+ # marker fragment at its head. `rendered_text` is the tool's own statement that its
+ # content holds no start tags of the page's own; asking the ARGUMENTS instead would make
+ # the loop re-derive from a tool's argument conventions something the tool already said.
+ # Exact spans the TOOL reported: where it cut a marker open at the window's head, and
+ # where it appended its own notice. Neither is re-derived here, because page- and
+ # server-authored text can both wear those shapes and only the tool knows what it wrote.
+ reported = result.data or {}
+ head_fragment_len = int(reported.get("head_fragment_len") or 0)
+ notice_at = reported.get("notice_at")
if spec is not None and spec.compactable and result.status == "ok":
content_digest = hashlib.sha256(
- _canonical_perception_content(result.content, is_observe=tool_name == "observe").encode()
+ _canonical_perception_content(
+ result.content,
+ is_observe=tool_name == "observe",
+ head_fragment_len=head_fragment_len,
+ notice_at=notice_at,
+ ).encode()
).hexdigest()
attribution["snapshot_digest"] = telemetry_hash(telemetry_salt, content_digest)
attribution["probe_first_time"] = st.perception.first_time(action_key)
@@ -3101,7 +3244,9 @@ async def run_agent_tool_loop(
)
if spec is not None and spec.compactable and result.status == "ok":
- st.snapshot_indices.add(len(st.messages)) # index this successful snapshot will occupy, pre-append
+ # The index this successful snapshot will occupy, pre-append, against the read's
+ # identity — the tool half is `messages[i]["name"]`, which compaction reads there.
+ st.snapshot_keys[len(st.messages)] = _declared_args_key(spec, args)
model_facing_content = result.content
skyvern_ctx = skyvern_context.current()
if skyvern_ctx is not None:
@@ -3156,7 +3301,12 @@ async def run_agent_tool_loop(
tool_name,
attribution,
content_only_digest=hashlib.sha256(
- _content_only_perception(result.content, is_observe=tool_name == "observe").encode()
+ _content_only_perception(
+ result.content,
+ is_observe=tool_name == "observe",
+ head_fragment_len=head_fragment_len,
+ notice_at=notice_at,
+ ).encode()
).hexdigest(),
refresh_pending=refresh_pending,
)
diff --git a/skyvern/forge/taskv3/tools.py b/skyvern/forge/taskv3/tools.py
index c38f18cd1..de48ca17e 100644
--- a/skyvern/forge/taskv3/tools.py
+++ b/skyvern/forge/taskv3/tools.py
@@ -118,20 +118,200 @@ HTML_MAX_CHARS = 20000
# Nothing in these may vary between two reads of an unchanged page: get_html's content is hashed
# into the loop's perception digests, which decide whether the run has returned to known ground.
-# No quote character may appear in either notice: loop._TV3_MARKER_CUT_RE recognizes a marker the cut
+# `total` is a property of the page and `next_offset` of the call, so both are stable under a re-read
+# of unchanged bytes at the same offset — which is the whole of what the digest requires.
+# No quote character may appear in any notice: loop._TV3_MARKER_CUT_RE recognizes a marker the cut
# left open only while no quote follows it, and the notice is what follows. Only the whole-page read
# is steered toward text — a cut element read already has the element it asked about.
-_MARKUP_CUT = f"…[truncated at {HTML_MAX_CHARS} chars]"
-_PAGE_MARKUP_CUT = (
- f"…[truncated at {HTML_MAX_CHARS} chars - for the visible text instead of markup, call get_html with format=text]"
-)
-# ponytail: text past the cap stays unreachable; add an offset argument if a real page needs it.
-# Component text is appended after the light DOM (_PAGE_TEXT_JS walks document first), so it is what
-# a cut drops first — hence naming the component read here rather than only a generic selector.
-_RENDERED_TEXT_CUT = (
- f"…[rendered text truncated at {HTML_MAX_CHARS} chars - text inside components is appended last "
- "and is cut first; read one region with get_html and a selector, or call observe]"
-)
+
+
+def _continuation_args(next_offset: int, *, scoped: bool, text: bool) -> str:
+ """How to spell the call that continues this read.
+
+ Every argument that identifies WHICH read this is has to be named, because tool arguments do not
+ carry over between calls: an omitted `format` defaults to markup and an omitted `selector` widens
+ to the whole page, so either one missing sends a model that follows the notice literally to the
+ same integer offset of a DIFFERENT string.
+
+ The selector is described, never echoed. It is model-authored and may contain a quote character,
+ and no notice may carry one — `loop._TV3_MARKER_CUT_RE` recognizes a marker the cut left open
+ only while no quote follows it, and the notice is what follows.
+ """
+ parts = ["the same selector"] if scoped else []
+ if text:
+ parts.append("format=text")
+ parts.append(f"offset={next_offset}")
+ return ", ".join(parts[:-1]) + (" and " if len(parts) > 1 else "") + parts[-1]
+
+
+def _markup_cut(next_offset: int, total: int, *, scoped: bool) -> str:
+ """The notice a cut markup read ends with: where it stopped, how much there is, how to continue.
+
+ The offsets of the two formats are NOT interchangeable — they index different strings — so the
+ steer toward text says restart, never `or`, which reads as one call carrying both.
+ """
+ steer = "" if scoped else " Markup not what you want? format=text is a separate read, from its own offset 0."
+ args = _continuation_args(next_offset, scoped=scoped, text=False)
+ return f"…[truncated at {next_offset} of {total} chars - call get_html again with {args} for the next part.{steer}]"
+
+
+def _rendered_text_cut(next_offset: int, total: int, *, scoped: bool) -> str:
+ # Component text is appended after the light DOM (_PAGE_TEXT_JS walks document first), so it is what
+ # a cut drops first — hence naming the component read here rather than only a generic selector.
+ # A read that already carries a selector is not told to use one.
+ steer = (
+ ""
+ if scoped
+ else " Text inside components is appended last and is cut first, so a selector read or observe reaches one region directly."
+ )
+ args = _continuation_args(next_offset, scoped=scoped, text=True)
+ return (
+ f"…[rendered text truncated at {next_offset} of {total} chars - call get_html again with "
+ f"{args} for the next part.{steer}]"
+ )
+
+
+def _past_end_error(total: int) -> ToolResult:
+ """A read that starts past the content. An ERROR, not an empty ok result, for two reasons: the
+ empty string is what an empty page legitimately returns, and an ok result carrying a constant
+ string would let a run page past the end forever — identical content under a fresh (tool, args)
+ key every call, which is the one shape the perception-stall guard cannot witness."""
+ return ToolResult.error(
+ f"offset is past the end of this read, which is {total} chars - pass an offset below that",
+ error_class="offset_past_end",
+ )
+
+
+_MARKER_ATTR_OPEN = 'data-tv3="'
+# The value shape this engine mints, and the same test `MINTED_MARKER_RE` applies in the observe JS
+# before it will trust a `data-tv3` as a selector. A page can author the attribute too, so the value
+# is what separates ours from theirs.
+_MINTED_MARKER_VALUE_RE = re.compile(r"\At\d+(?:-\d+)?\Z")
+
+
+def _marker_head_fragment_len(content: str, offset: int) -> int:
+ """How many characters at `offset` are the tail of a marker attribute the cut opened, or 0.
+
+ Computed from the boundary itself rather than by recognizing the fragment's SHAPE. Every prefix
+ of the attribute is also legal page text — `123"`, `t123"`, `="t123"` — so a pattern cannot tell
+ a split marker from a page that merely starts that way, and folding page text that differs makes
+ it read as frozen, which the perception-stall guard terminates on.
+ """
+ if offset <= 0:
+ return 0
+ # The opener may STRADDLE the boundary — a window can begin `a-tv3="t123"` — so the search admits
+ # any occurrence starting before `offset`, not only ones ending before it. Bounded at `0, offset`
+ # it misses every cut that lands inside the attribute's own name, and the marker value then goes
+ # unfolded: an unchanged window gets a fresh digest whenever a remount re-mints it, which is how
+ # a frozen page evades the stall guard instead of tripping it.
+ opened = content.rfind(_MARKER_ATTR_OPEN, 0, offset + len(_MARKER_ATTR_OPEN) - 1)
+ if opened < 0 or opened >= offset:
+ return 0
+ closed = content.find('"', opened + len(_MARKER_ATTR_OPEN))
+ if closed < offset:
+ # A boundary at or past the closing quote left nothing open.
+ return 0
+ # The VALUE decides, and by here the whole of it is in hand — which is why this is not the
+ # shape-matching the fragment forbids. A prefix is ambiguous (`123"`, `t123"` are also legal page
+ # text); a complete value is not. A page may author `data-tv3` itself, and folding a
+ # page-authored value that is changing makes the window read as frozen, which the
+ # perception-stall guard terminates on. Same test the observe JS applies before it will trust one
+ # of these as a selector.
+ if not _MINTED_MARKER_VALUE_RE.match(content[opened + len(_MARKER_ATTR_OPEN) : closed]):
+ return 0
+ return closed - offset + 1
+
+
+def _window(content: str, offset: int, cut: Callable[[int, int], str]) -> tuple[str, int, int | None] | ToolResult:
+ """`content` from `offset`, capped, ending in `cut` when bytes remain after it.
+
+ Redacts BEFORE it cuts. The loop hides `model_hidden_values` from tool output by whole-substring
+ replacement, and it runs on what this returns — so a secret straddling a window boundary matches
+ neither half and both halves reach the model in the clear. Before offsets existed the tail was
+ simply unreachable; making it reachable is what turns a truncated prefix into the whole value,
+ delivered in two pieces. Redacting the whole string first means a boundary can only ever split
+ the placeholder. The loop's own pass still runs and is then a no-op on this content.
+ """
+ ctx = skyvern_context.current()
+ if ctx is not None:
+ content = ctx.hide_from_model(content)
+ total = len(content)
+ if offset >= total:
+ # An unasked-for offset on an empty read is not a read that ran off the end: an empty page is
+ # an ordinary answer and must stay the empty string, or every blank page reads as a paging
+ # mistake. Only a read the model deliberately advanced can overshoot.
+ return ("", 0, None) if offset == 0 else _past_end_error(total)
+ head = _marker_head_fragment_len(content, offset)
+ end = offset + HTML_MAX_CHARS
+ if end >= total:
+ return content[offset:], head, None
+ # The exact BOUNDARIES, not a flag. The loop canonicalizes our notice out of the perception
+ # digest because it carries the document's TOTAL, which moves when bytes outside the window
+ # change — and it must fold OUR notice and never text that merely looks like one. Both the page
+ # (a forged unterminated prefix) and the server (a download filename) control text that can wear
+ # that shape, so no pattern and no match-selection rule can tell them apart. This function put
+ # the notice there and knows where; carrying the index is the only answer that stays correct.
+ windowed = content[offset:end]
+ return windowed + cut(end, total), head, len(windowed)
+
+
+def _normalize_read_args(args: dict[str, Any]) -> None:
+ """Rewrite the arguments that name WHICH read this is to the single form the handler will act on,
+ dropping any that mean "not supplied". Mutates `args`, which is what the loop hashes into this
+ call's identity.
+
+ A non-strict provider spells an absent optional argument in several ways — omitted, `null`, or
+ the empty string — and the handler treats all of them as the whole-page HTML read. Left as sent
+ they are several identities for one read, and with a two-snapshot window duplicates of the head
+ can fill it and evict the different region the window exists to hold.
+ """
+ # Absent or empty only — never whitespace. `if selector:` treats " " as a real address, so the
+ # handler reports a stale_selector naming what the model typed; dropping it here would turn that
+ # into a silent WHOLE-PAGE read, which is the context blow-up this change exists to stop. A
+ # whitespace `format` likewise reaches the handler's unknown-format error rather than defaulting.
+ for name in ("selector", "format"):
+ if args.get(name) is None or args.get(name) == "":
+ args.pop(name, None)
+ fmt = args.get("format")
+ if isinstance(fmt, str):
+ # An unrecognized spelling is left as typed, so the handler's error names what the model wrote.
+ normalized = fmt.strip().lower()
+ if normalized == "html":
+ del args["format"]
+ elif normalized == "text":
+ args["format"] = normalized
+
+
+def _read_offset(args: dict[str, Any]) -> int | str:
+ """The requested offset, or an error message. A model that sends a bad offset must be told, not
+ silently re-served the head — it would read the same window as a fresh document.
+
+ The accepted value is written back over `args`, and an offset of 0 is removed outright. `args` is
+ what the loop hashes into this call's identity, which decides both what supersedes what in the
+ transcript and what counts as the same probe to the stall guard. Without this, `{}`,
+ `{offset: 0}` and `{offset: "0"}` are three identities for one read of the same bytes.
+
+ MUST run outside `_with_selector_guard`, which hands the handler a COPY of `args` whenever a
+ selector is present — a write-back inside it reaches nothing the loop will hash.
+ """
+ raw = args.pop("offset", None)
+ if raw is None:
+ return 0
+ if isinstance(raw, bool) or not isinstance(raw, (int, str, float)):
+ return f"offset must be a whole number of characters, not {raw!r}"
+ # Integrality is checked, never coerced: int(20000.9) is 20000, which would execute and record a
+ # DIFFERENT read from the one asked for, under a handler that promises to reject a non-whole count.
+ if isinstance(raw, float) and not raw.is_integer():
+ return f"offset must be a whole number of characters, not {raw!r}"
+ try:
+ value = int(raw)
+ except (TypeError, ValueError, OverflowError):
+ return f"offset must be a whole number of characters, not {raw!r}"
+ if value < 0:
+ return f"offset must not be negative, got {value}"
+ if value:
+ args["offset"] = value
+ return value
def _escape_tags_in_text(text: str) -> str:
@@ -8306,7 +8486,7 @@ def build_browser_tools(
# is untouched. url= is already masked before truncation above; re-masking a token is a no-op.
return ToolResult.ok(_mask_refs("\n".join(lines)), data={"count": len(elements), "summary": summary})
- async def _rendered_text_result(page: Any, selector: str | None) -> ToolResult:
+ async def _rendered_text_result(page: Any, selector: str | None, offset: int) -> ToolResult:
# rendered_text marks this result as prose rather than markup, which is what tells a reader
# of `data` that its content carries no start tags of the page's own.
target = page
@@ -8322,9 +8502,20 @@ def build_browser_tools(
# another document's text to it would answer a different question than the one asked.
text += await _child_frame_text(page)
body = _escape_tags_in_text(_mask_refs(text))
- if len(body) > HTML_MAX_CHARS:
- body = body[:HTML_MAX_CHARS] + _RENDERED_TEXT_CUT
- return ToolResult.ok(body, data={"rendered_text": True})
+ # Windowed AFTER masking and escaping, never before: both rewrite lengths, so an offset taken
+ # against the raw text would address a different character in the text the model is handed.
+ scoped = bool(selector)
+ windowed = _window(body, offset, lambda end, total: _rendered_text_cut(end, total, scoped=scoped))
+ if isinstance(windowed, ToolResult):
+ return windowed
+ text, head, notice_at = windowed
+ # Present only when non-zero. Adding a key to every result would widen a `data` shape other
+ # tests pin exactly, for no reader that needs it: the loop uses `.get`, so absent and the
+ # inert value are the same answer. A rendered-text read has no markup and so no head fragment.
+ data: dict[str, Any] = {"rendered_text": True}
+ if notice_at is not None:
+ data["notice_at"] = notice_at
+ return ToolResult.ok(text, data=data)
async def _child_frame_text(page: Any) -> str:
"""Each readable child frame's rendered text, labelled, appended to the page's own.
@@ -8376,9 +8567,11 @@ def build_browser_tools(
if error is not None:
return error
selector = args.get("selector")
+ # Already parsed, normalized and validated by `_with_read_offset`, outside the selector guard.
+ offset = int(args.get("offset") or 0)
fmt = str(args.get("format") or "html").strip().lower()
if fmt == "text":
- return await _rendered_text_result(page, selector)
+ return await _rendered_text_result(page, selector, offset)
if fmt != "html":
# Falling through to markup would hand back the whole-page dump the prompt forbids, on a
# typo the model cannot see. The enum is advisory: the spec is not emitted strict.
@@ -8405,10 +8598,18 @@ def build_browser_tools(
# costs truncation budget the model needs for real markup.
html = _ACT_ATTR_RE.sub("", html)
html = _mask_refs(html)
- if len(html) > HTML_MAX_CHARS:
- cut = _MARKUP_CUT if selector else _PAGE_MARKUP_CUT
- return ToolResult.ok(html[:HTML_MAX_CHARS] + cut)
- return ToolResult.ok(html)
+ scoped = bool(selector)
+ windowed = _window(html, offset, lambda end, total: _markup_cut(end, total, scoped=scoped))
+ if isinstance(windowed, ToolResult):
+ return windowed
+ markup, head, notice_at = windowed
+ # Same rule as the text read: a markup read with nothing to report carries no `data` at all.
+ report: dict[str, Any] = {}
+ if head:
+ report["head_fragment_len"] = head
+ if notice_at is not None:
+ report["notice_at"] = notice_at
+ return ToolResult.ok(markup, data=report or None)
async def _unreachable_error(selector: str) -> ToolResult:
# A native checkbox or <select> inside a hidden template is refused HERE, by a visibility
@@ -12135,6 +12336,30 @@ def build_browser_tools(
# guards then see less than they could, which is the pre-existing behaviour.
LOG.info("taskv3 could not record frame work", exc_info=True)
+ def _with_read_identity(handler: ToolHandler) -> ToolHandler:
+ """Normalize the arguments that name WHICH read this is, on the ORIGINAL args dict.
+
+ Outermost of get_html's wrappers by necessity: `_with_selector_guard` rebuilds `args` as a
+ copy whenever a selector is present, and the loop hashes the caller's dict, not the copy. A
+ normalization applied any further in is invisible to the call identity it exists to unify.
+
+ Spellings the handler treats as identical must not survive as different keys. The handler
+ strips and lowercases `format` and defaults it to html, so `{}`, `{format: html}` and
+ `{format: " HTML "}` are one read — left raw they are three keys, and with a retention window
+ of two, duplicates of one region can fill it and evict the different region the window exists
+ to hold. An unrecognized spelling is left untouched for the handler to reject, so its error
+ still names what the model actually typed.
+ """
+
+ async def wrapped(args: dict[str, Any]) -> ToolResult:
+ offset = _read_offset(args)
+ if isinstance(offset, str):
+ return ToolResult.error(offset, error_class="invalid_offset")
+ _normalize_read_args(args)
+ return await handler(args)
+
+ return wrapped
+
def _with_ref_resolution(tool_name: str, handler: ToolHandler) -> ToolHandler:
async def wrapped(args: dict[str, Any]) -> ToolResult:
# Read ONCE, so the value stamped on the row is provably the one that chose the branch
@@ -12256,7 +12481,8 @@ def build_browser_tools(
"get_html",
"Get raw outer/inner HTML of the page or a specific element (for detail beyond observe), or "
'with format "text" its rendered visible text instead - what a user sees, no markup. Both '
- f"are capped at {HTML_MAX_CHARS} chars and say when they were cut.",
+ f"are capped at {HTML_MAX_CHARS} chars per call; a cut result reports the total size and the "
+ "offset that continues the read, so a page larger than one call is read in parts.",
_obj(
{
"selector": {
@@ -12268,6 +12494,13 @@ def build_browser_tools(
"enum": ["html", "text"],
"description": 'Default "html". "text" returns the visible text instead of markup.',
},
+ "offset": {
+ "type": "integer",
+ "description": (
+ "Character to start this read at; default 0. Pass the offset a previous cut "
+ "result named to read the next part of the same page."
+ ),
+ },
}
),
get_html,
@@ -12415,6 +12648,9 @@ def build_browser_tools(
_tool_spec.handler = _with_ref_resolution(
_tool_spec.name, _with_selector_guard(_tool_spec.handler, diagnose)
)
+ if _tool_spec.name == "get_html":
+ # After the selector-guard block above, so this sits OUTSIDE it and sees the caller's dict.
+ _tool_spec.handler = _with_read_identity(_tool_spec.handler)
if _tool_spec.name in ("click", "type"):
# OUTERMOST wrapper: resolve mark=N to a selector before preflight builds its action from
# args["selector"], so the whole verified click/type path (uniqueness gate, commit-verify)
diff --git a/tests/unit/test_taskv3_loop.py b/tests/unit/test_taskv3_loop.py
index c43a7023e..40f6e832f 100644
--- a/tests/unit/test_taskv3_loop.py
+++ b/tests/unit/test_taskv3_loop.py
@@ -3122,9 +3122,10 @@ def _assistant_turn(*ids: str) -> dict[str, Any]:
def test_compact_transcript_elides_superseded_perception() -> None:
- # Keep the newest snapshot of each tracked tool; elide older ones' content (never remove the message),
- # and leave untracked results untouched. Round 2 (after the last assistant) supersedes round 1's
- # observe/get_html. `snapshot_indices` names the successful-perception message indices the loop records.
+ # Keep the newest snapshot of each tracked READ; elide older ones' content (never remove the message),
+ # and leave untracked results untouched. Round 2 (after the last assistant) re-takes round 1's two
+ # reads with the same arguments, so it supersedes them. `snapshot_keys` maps the successful-perception
+ # message indices the loop records to each read's (args) identity.
from skyvern.forge.taskv3.loop import _compact_transcript
messages = [
@@ -3138,7 +3139,8 @@ def test_compact_transcript_elides_superseded_perception() -> None:
_tool_msg("d", "observe", "OBSERVE_2 latest " + "z" * 300), # idx 7
_tool_msg("e", "get_html", "HTML_2 latest " + "w" * 300), # idx 8
]
- snapshots = {3, 4, 7, 8} # the observe/get_html successes; the click (5) is not a snapshot
+ # The observe/get_html successes keyed by their args; the click (5) is not a snapshot at all.
+ snapshots = {3: "{}", 4: '{"selector": "#rows"}', 7: "{}", 8: '{"selector": "#rows"}'}
_compact_transcript(messages, snapshots)
by_id = {m["tool_call_id"]: m["content"] for m in messages if m.get("role") == "tool"}
assert by_id["a"].startswith("[superseded observe") # older observe elided
@@ -3146,7 +3148,9 @@ def test_compact_transcript_elides_superseded_perception() -> None:
assert by_id["c"] == "clicked #x" # untracked result untouched
assert by_id["d"].startswith("OBSERVE_2 latest") # newest observe kept intact
assert by_id["e"].startswith("HTML_2 latest") # newest get_html kept intact
- assert snapshots == {7, 8} # elided indices are dropped so a re-run can't re-anchor them
+ assert set(snapshots) == {7, 8} # elided indices are dropped so a re-run can't re-anchor them
+ # The placeholder names the read it dropped, so the model can re-take it deliberately.
+ assert by_id["b"] == "[superseded get_html(selector=#rows) output elided to bound context]"
# Idempotent: a second pass over the (now-reduced) index set changes nothing.
snapshot = [m.get("content") for m in messages]
@@ -3166,7 +3170,7 @@ def test_compact_transcript_keeps_unread_latest_round() -> None:
_tool_msg("a", "get_html", "HTML_A " + "a" * 300), # idx 2
_tool_msg("b", "get_html", "HTML_B " + "b" * 300), # idx 3
]
- _compact_transcript(messages, {2, 3})
+ _compact_transcript(messages, {2: '{"selector": "#a"}', 3: '{"selector": "#a"}'})
assert messages[2]["content"].startswith("HTML_A") # both unread → neither elided
assert messages[3]["content"].startswith("HTML_B")
@@ -3184,7 +3188,7 @@ def test_compact_transcript_skip_stub_does_not_shadow_real_snapshot() -> None:
_tool_msg("c1", "click", "tool_error: TimeoutError: click failed"), # idx 3
_tool_msg("o2", "observe", "skipped: earlier tool call in this batch failed"), # idx 4 (not tracked)
]
- _compact_transcript(messages, {1})
+ _compact_transcript(messages, {1: "{}"})
assert messages[1]["content"].startswith("REAL_OBSERVE") # real snapshot preserved as the live view
assert messages[4]["content"].startswith("skipped:") # skip stub left as-is, never elided or promoted
@@ -3193,7 +3197,7 @@ def test_compact_transcript_noop_without_tracked_snapshots() -> None:
from skyvern.forge.taskv3.loop import _compact_transcript
messages = [_assistant_turn("a"), _tool_msg("a", "observe", "big " + "x" * 500)]
- _compact_transcript(messages, set())
+ _compact_transcript(messages, {})
assert messages[1]["content"].startswith("big ") # nothing elided when nothing is tracked
@@ -9762,3 +9766,310 @@ async def test_every_click_row_carries_a_hit_class_and_no_other_tool_does() -> N
unregistered = [e for e in logs if e["event"] == "taskv3 tool call finished"]
assert any(e["tool"] == "unknown_tool" for e in unregistered)
assert all("hit_class" not in e for e in unregistered)
+
+
+def _get_html_tool() -> ToolSpec:
+ """A get_html whose answer is a function of its arguments — disjoint reads return disjoint bytes."""
+
+ async def handler(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok(f"HTML[{args.get('selector') or 'page'}@{args.get('offset', 0)}] " + "y" * 300)
+
+ spec = ToolSpec(
+ name="get_html",
+ description="get_html",
+ # Declared, like the real spec: the supersession key is built from a tool's DECLARED arguments,
+ # so a fixture that declares none would collapse every read onto one key.
+ parameters={"type": "object", "properties": {"selector": {"type": "string"}, "offset": {"type": "integer"}}},
+ handler=handler,
+ )
+ spec.compactable = True
+ return spec
+
+
+async def test_loop_keeps_reads_of_disjoint_regions_readable_together() -> None:
+ # SKY-16330. A document too large for one read is gathered in parts, and the parts have to be
+ # readable AT THE SAME TIME or the model never holds the whole thing. Supersession is about a read
+ # going stale, and a read of region B does not make a read of region A stale — they answer
+ # different questions. Eliding A on B's arrival leaves the model with half the evidence it asked
+ # for and no way to get the other half back except by re-reading, forever.
+ script = [
+ [("get_html", {"selector": "#part-1"})],
+ [("get_html", {"selector": "#part-2"})],
+ [("finish", {"status": "completed", "reason": "ok"})],
+ ]
+ outcome, _ = await _run(script, [_get_html_tool(), make_finish_tool()])
+ assert outcome.status == "completed"
+ reads = [m["content"] for m in outcome.messages if m.get("role") == "tool" and m.get("name") == "get_html"]
+ assert len(reads) == 2
+ assert reads[0].startswith("HTML[#part-1"), reads[0] # the first region survives the second read
+ assert reads[1].startswith("HTML[#part-2"), reads[1]
+
+
+async def test_loop_still_elides_a_re_read_of_the_same_region() -> None:
+ # The other half of the same rule, and the reason the rule exists: re-reading the SAME region IS
+ # a supersession — the older copy is a stale view of the same bytes — so context stays bounded on
+ # a run that hammers one read.
+ script = [
+ [("get_html", {"selector": "#part-1"})],
+ [("get_html", {"selector": "#part-1"})],
+ [("finish", {"status": "completed", "reason": "ok"})],
+ ]
+ outcome, _ = await _run(script, [_get_html_tool(), make_finish_tool()])
+ reads = [m["content"] for m in outcome.messages if m.get("role") == "tool" and m.get("name") == "get_html"]
+ assert len(reads) == 2
+ assert reads[0].startswith("[superseded get_html"), reads[0]
+ assert reads[1].startswith("HTML[#part-1")
+
+
+async def test_loop_bounds_how_many_distinct_reads_it_retains() -> None:
+ # Accumulation is bounded, not unbounded: retaining every distinct read would let a run that
+ # walks 300 selectors carry 300 snapshots. The oldest distinct reads elide once the retention
+ # window is full, so the ceiling stays a constant times the per-read cap.
+ from skyvern.forge.taskv3.loop import PERCEPTION_SNAPSHOT_RETAIN
+
+ n = PERCEPTION_SNAPSHOT_RETAIN + 2
+ script: list[list[tuple[str, dict[str, Any]]]] = [[("get_html", {"selector": f"#p{i}"})] for i in range(n)]
+ script.append([("finish", {"status": "completed", "reason": "ok"})])
+ outcome, _ = await _run(script, [_get_html_tool(), make_finish_tool()], max_turns=n + 5, max_tool_calls=n + 5)
+ reads = [m["content"] for m in outcome.messages if m.get("role") == "tool" and m.get("name") == "get_html"]
+ assert len(reads) == n
+ intact = [r for r in reads if r.startswith("HTML[")]
+ # The retention window, plus the latest round — which is protected as unread and does not spend a
+ # window slot, so one read per turn leaves RETAIN + 1 standing.
+ expected = PERCEPTION_SNAPSHOT_RETAIN + 1
+ assert len(intact) == expected, [r[:30] for r in reads]
+ # The window keeps the NEWEST reads, which are the ones the model is working from.
+ assert [r.split("@")[0] for r in intact] == [f"HTML[#p{i}" for i in range(n - expected, n)]
+
+
+async def test_loop_retention_window_does_not_widen_observe() -> None:
+ # observe takes no arguments, so every observe is a read of the same thing: the whole page as it
+ # is now. Exactly one survives, as before — the window can only widen a tool whose reads differ.
+ script = [
+ [("observe", {})],
+ [("observe", {})],
+ [("observe", {})],
+ [("finish", {"status": "completed", "reason": "ok"})],
+ ]
+ outcome, _ = await _run(script, [_big_observe_tool(), make_finish_tool()])
+ obs = [m["content"] for m in outcome.messages if m.get("role") == "tool" and m.get("name") == "observe"]
+ assert len([o for o in obs if o.startswith("OBSERVE ")]) == 1
+ assert len([o for o in obs if o.startswith("[superseded ")]) == 2
+
+
+def test_compact_transcript_batched_turn_does_not_evict_every_earlier_read() -> None:
+ # SKY-16330. The prompt asks the model to batch aggressively, so a single turn routinely lands
+ # several reads. Counting the still-unread round against the retention window would let one
+ # batched turn evict every earlier read and make accumulation a no-op on exactly that behaviour.
+ from skyvern.forge.taskv3.loop import PERCEPTION_SNAPSHOT_RETAIN, _compact_transcript
+
+ messages: list[dict[str, Any]] = [
+ _assistant_turn("a"),
+ _tool_msg("a", "get_html", "WINDOW@0 " + "a" * 300), # idx 1
+ _assistant_turn("b", "c", "d"), # latest round, batched
+ _tool_msg("b", "get_html", "WINDOW@20000 " + "b" * 300), # idx 3
+ _tool_msg("c", "get_html", "WINDOW@40000 " + "c" * 300), # idx 4
+ _tool_msg("d", "get_html", "WINDOW@60000 " + "d" * 300), # idx 5
+ ]
+ keys = {
+ 1: "{}",
+ 3: '{"offset": 20000}',
+ 4: '{"offset": 40000}',
+ 5: '{"offset": 60000}',
+ }
+ _compact_transcript(messages, keys)
+ assert PERCEPTION_SNAPSHOT_RETAIN >= 1
+ assert messages[1]["content"].startswith("WINDOW@0") # the earlier read survives the batch
+ for idx in (3, 4, 5):
+ assert messages[idx]["content"].startswith("WINDOW@") # the unread round is untouched
+
+
+def test_compact_transcript_unread_round_still_supersedes_its_own_earlier_read() -> None:
+ # The other half: not spending a retention slot must not turn into not superseding. A read the
+ # latest round has just re-taken is a stale view of the same bytes and still elides.
+ from skyvern.forge.taskv3.loop import _compact_transcript
+
+ messages: list[dict[str, Any]] = [
+ _assistant_turn("a"),
+ _tool_msg("a", "get_html", "OLD@0 " + "a" * 300), # idx 1
+ _assistant_turn("b"),
+ _tool_msg("b", "get_html", "NEW@0 " + "b" * 300), # idx 3, same read, re-taken
+ ]
+ keys = {1: "{}", 3: "{}"}
+ _compact_transcript(messages, keys)
+ assert messages[1]["content"] == "[superseded get_html output elided to bound context]"
+ assert messages[3]["content"].startswith("NEW@0")
+ assert set(keys) == {3}
+
+
+def test_canonicalization_drops_a_windowed_reads_own_cut_notice_and_head_fragment() -> None:
+ # SKY-16330. A windowed read's digest must depend on the WINDOW, not on the rest of the document.
+ # The cut notice carries the document's total size, which moves when bytes outside the window
+ # change; an offset window can also open on a marker fragment the tail patterns cannot see.
+ # Either one left in would make a frozen window read as fresh ground on every look, which is how
+ # a page that has stopped responding hides from the perception-stall guard.
+ from skyvern.forge.taskv3.loop import _canonical_perception_content
+
+ frozen = "<div>frozen body</div>"
+ # `read_cut` is the tool's own report that it appended this notice; without it the fold does not
+ # run at all, because page text can imitate a notice.
+ grew = _canonical_perception_content(
+ frozen + "…[truncated at 20000 of 60000 chars - call get_html again]", notice_at=len(frozen)
+ )
+ grew_more = _canonical_perception_content(
+ frozen + "…[truncated at 20000 of 60123 chars - call get_html again]", notice_at=len(frozen)
+ )
+ assert grew == grew_more # a tail that changed outside the window does not move the digest
+
+ # A marker re-minted across a window boundary does not move it either — but only where the
+ # fragment still carries marker characters. A boundary landing inside the bare digits is
+ # indistinguishable from page text that opens with a number, and is deliberately left alone;
+ # see test_head_fragment_normalization_leaves_ordinary_leading_numbers_alone.
+ head_a = _canonical_perception_content('t100" class=x>' + frozen, head_fragment_len=len('t100"'))
+ head_b = _canonical_perception_content('t4567" class=x>' + frozen, head_fragment_len=len('t4567"'))
+ assert head_a == head_b
+
+ # It still discriminates a change INSIDE the window, which is the whole point of the digest.
+ moved = "<div>moved body</div>"
+ assert _canonical_perception_content(moved + "…[truncated at 1 of 2 chars]", notice_at=len(moved)) != grew
+
+
+async def test_loop_undeclared_argument_cannot_split_an_argumentless_tools_key() -> None:
+ # A tool's result can depend on an argument it DECLARES and on nothing else, and the specs are not
+ # emitted strict — so a provider adding one to `look` must not make two calls look like distinct
+ # reads. For `look` that is not merely wasted context: each call disposes the old handles, clears
+ # the mark manifest and renumbers, so a retained older legend addresses controls that have moved,
+ # and a click following it acts on the wrong one. It fails open, because the stale legend looks
+ # valid. Exactly one look snapshot survives, whatever arrives on the call.
+ async def handler(args: dict[str, Any]) -> ToolResult:
+ return ToolResult.ok("LEGEND " + "x" * 300)
+
+ spec = ToolSpec(name="look", description="look", parameters={"type": "object", "properties": {}}, handler=handler)
+ spec.compactable = True
+ script = [
+ [("look", {})],
+ [("look", {"reason": "checking the form"})],
+ [("look", {"reason": "checking again"})],
+ [("finish", {"status": "completed", "reason": "ok"})],
+ ]
+ outcome, _ = await _run(script, [spec, make_finish_tool()])
+ assert outcome.status == "completed"
+ looks = [m["content"] for m in outcome.messages if m.get("role") == "tool" and m.get("name") == "look"]
+ assert len(looks) == 3
+ assert len([lk for lk in looks if lk.startswith("LEGEND ")]) == 1, [lk[:30] for lk in looks]
+
+
+def test_declared_args_key_ignores_what_the_spec_does_not_declare() -> None:
+ from skyvern.forge.taskv3.loop import _declared_args_key
+
+ argumentless = ToolSpec(
+ name="observe", description="o", parameters={"type": "object", "properties": {}}, handler=make_finish_tool
+ )
+ assert _declared_args_key(argumentless, {}) == _declared_args_key(argumentless, {"reason": "why"})
+
+ reading = ToolSpec(
+ name="get_html",
+ description="g",
+ parameters={"type": "object", "properties": {"selector": {}, "offset": {}}},
+ handler=make_finish_tool,
+ )
+ # Declared arguments still separate genuinely different reads — the whole point of the key.
+ assert _declared_args_key(reading, {"offset": 0}) != _declared_args_key(reading, {"offset": 20000})
+ # ...and an undeclared one rides along without changing the read's identity.
+ assert _declared_args_key(reading, {"selector": "#a"}) == _declared_args_key(reading, {"selector": "#a", "z": 1})
+
+
+async def test_rendered_text_never_folds_a_head_however_far_into_the_page_it_starts() -> None:
+ # Rendered text carries no start tags of the page's own, so nothing in it is ever a marker of
+ # ours — at ANY offset. Folding its head can only fold REAL visible text, and this is what that
+ # costs: a page whose leading identifier is genuinely changing digests identically every read,
+ # the perception-stall guard sees a frozen page, and it TERMINATES a run still making progress.
+ #
+ # Asserted through the guard rather than by calling the canonicalizer, because the canonicalizer
+ # defaults to not folding — a direct call would pass whatever the loop decides and prove nothing.
+ from skyvern.forge.taskv3.loop import PERCEPTION_STALL_REASON_PREFIX, PERCEPTION_STALL_TERMINATE_AFTER
+
+ reads = PERCEPTION_STALL_TERMINATE_AFTER + 3
+
+ async def handler(args: dict[str, Any]) -> ToolResult:
+ handler.n += 1 # type: ignore[attr-defined]
+ # Only the leading identifier moves; everything after it is frozen, which is exactly the
+ # shape the fold would collapse.
+ return ToolResult.ok(f't{handler.n * 100}" balance ' + "x" * 300, data={"rendered_text": True}) # type: ignore[attr-defined]
+
+ handler.n = 0 # type: ignore[attr-defined]
+ spec = ToolSpec(
+ name="get_html",
+ description="get_html",
+ parameters={"type": "object", "properties": {"offset": {"type": "integer"}, "format": {"type": "string"}}},
+ handler=handler,
+ )
+ spec.compactable = True
+ script: list[list[tuple[str, dict[str, Any]]]] = [
+ [("get_html", {"format": "text", "offset": 20000})] for _ in range(reads)
+ ]
+ script.append([("finish", {"status": "completed", "reason": "ok"})])
+ outcome, _ = await _run(script, [spec, make_finish_tool()], max_turns=reads + 5, max_tool_calls=reads + 5)
+
+ assert not (outcome.reason or "").startswith(PERCEPTION_STALL_REASON_PREFIX), outcome.reason
+ assert outcome.status == "completed", (outcome.status, outcome.reason)
+
+
+def test_a_marker_head_is_folded_by_its_reported_length_not_by_its_shape() -> None:
+ # Every prefix of the marker attribute is also legal page text — `123"`, `t123"`, `="t123"` — so
+ # nothing about a fragment's SHAPE distinguishes a marker the cut opened from a page that merely
+ # starts that way. Folding page text that genuinely differs makes it read as frozen, and the
+ # perception-stall guard TERMINATES on that, ending a run that was progressing.
+ #
+ # The tool reports the exact length it cut open, so the fold needs no recognition at all.
+ from skyvern.forge.taskv3.loop import _canonical_perception_content as canon
+
+ for a, b in (('123" items', '456" items'), ('t123" items', 't456" items'), ('="t1" x', '="t9" x')):
+ assert canon(a) != canon(b), (a, b) # unreported: page text, folded by nothing
+
+ # A marker the tool says it cut open folds, however much of the attribute survived — the length
+ # is the fragment through its closing quote, which only the tool can know.
+ rest = " rest"
+ for frag_a, frag_b in (('t100"', 't9000"'), ('="t100"', '="t9000"'), ('a-tv3="t100"', 'a-tv3="t9000"')):
+ folded_a = canon(frag_a + rest, head_fragment_len=len(frag_a))
+ folded_b = canon(frag_b + rest, head_fragment_len=len(frag_b))
+ assert folded_a == folded_b, (frag_a, frag_b, folded_a, folded_b)
+
+
+async def test_page_authored_notice_shaped_text_never_folds_into_a_frozen_verdict() -> None:
+ # The cut notice is folded out of the digest because it carries the document's TOTAL, which moves
+ # when bytes OUTSIDE the window change. Folded unconditionally that also reaches page-authored
+ # text that merely LOOKS like a notice — in `observe` and `look` as well as inside a `get_html`
+ # window — and a page whose notice-shaped numbers are genuinely changing then digests identically
+ # on every read. The stall guard reads that as frozen and TERMINATES a run still making progress.
+ #
+ # Asserted through the guard, not against the canonicalizer: a direct call passes whatever the
+ # loop decides to hand it and would go green under the broken version.
+ from skyvern.forge.taskv3.loop import PERCEPTION_STALL_REASON_PREFIX, PERCEPTION_STALL_TERMINATE_AFTER
+
+ reads = PERCEPTION_STALL_TERMINATE_AFTER + 3
+
+ async def handler(_args: dict[str, Any]) -> ToolResult:
+ handler.n += 1 # type: ignore[attr-defined]
+ # The page's OWN text, shaped like our notice, with only its numbers moving. The observe
+ # appends no notice and reports no boundary, so there is nothing for the fold to act on.
+ return ToolResult.ok(f"rows …[truncated at 10 of {handler.n * 100} chars] more " + "x" * 300) # type: ignore[attr-defined]
+
+ handler.n = 0 # type: ignore[attr-defined]
+ spec = ToolSpec(
+ name="observe", description="observe", parameters={"type": "object", "properties": {}}, handler=handler
+ )
+ spec.compactable = True
+ script: list[list[tuple[str, dict[str, Any]]]] = [[("observe", {})] for _ in range(reads)]
+ script.append([("finish", {"status": "completed", "reason": "ok"})])
+ outcome, _ = await _run(script, [spec, make_finish_tool()], max_turns=reads + 5, max_tool_calls=reads + 5)
+
+ assert not (outcome.reason or "").startswith(PERCEPTION_STALL_REASON_PREFIX), outcome.reason
+ assert outcome.status == "completed", (outcome.status, outcome.reason)
diff --git a/tests/unit/test_taskv3_tools.py b/tests/unit/test_taskv3_tools.py
index a87912226..5d17ac0fc 100644
--- a/tests/unit/test_taskv3_tools.py
+++ b/tests/unit/test_taskv3_tools.py
@@ -2810,7 +2810,7 @@ async def test_get_html_marks_truncation_explicitly() -> None:
r = await _tool(tools, "get_html").handler({"selector": "#big"})
assert r.status == "ok"
assert len(r.content) < 30000
- assert r.content.endswith(taskv3_tools._MARKUP_CUT)
+ assert r.content.endswith(taskv3_tools._markup_cut(taskv3_tools.HTML_MAX_CHARS, 30000, scoped=True))
# A branch-local witness, not captured production DOM: a stylesheet larger than get_html's whole
@@ -2848,8 +2848,9 @@ async def test_get_html_text_format_returns_the_record_a_style_prefix_hides_from
markup = await _tool(tools, "get_html").handler({})
assert markup.status == "ok" and _STYLE_PREFIX_RECORD not in markup.content
- assert markup.content.endswith(taskv3_tools._PAGE_MARKUP_CUT), markup.content[-200:]
- assert "format=text" in taskv3_tools._PAGE_MARKUP_CUT and '"' not in taskv3_tools._PAGE_MARKUP_CUT
+ page_cut = taskv3_tools._markup_cut(taskv3_tools.HTML_MAX_CHARS, len(_STYLE_PREFIX_DOC), scoped=False)
+ assert markup.content.endswith(page_cut), markup.content[-200:]
+ assert "format=text" in page_cut and '"' not in page_cut
text = await _tool(tools, "get_html").handler({"format": "text"})
assert text.status == "ok", text.content
@@ -2862,7 +2863,10 @@ async def test_get_html_text_format_names_a_real_continuation_when_over_bound()
tools = build_browser_tools(_fixed_page_provider(_FakeTextPage(_STYLE_PREFIX_DOC, "Statement line\n" * 3000)))
r = await _tool(tools, "get_html").handler({"format": "text"})
assert r.status == "ok"
- assert r.content.endswith(taskv3_tools._RENDERED_TEXT_CUT), r.content[-300:]
+ text_total = len("Statement line\n" * 3000)
+ assert r.content.endswith(taskv3_tools._rendered_text_cut(taskv3_tools.HTML_MAX_CHARS, text_total, scoped=False)), (
+ r.content[-300:]
+ )
assert {"get_html", "observe"} <= {spec.name for spec in tools}
@@ -24601,3 +24605,385 @@ async def test_the_fallback_does_not_arm_on_everything_when_the_counter_goes_awa
# Nothing new has landed since the handover, so nothing may arm -- and the tab the model opened
# must survive.
assert not later_tab.is_closed()
+
+
+# SKY-16330. A document whose ONE record sits past the markup cap, in markup and in rendered text
+# alike, so no single read of either format can contain it. Branch-local witness, not captured DOM.
+_PAST_CAP_RECORD = "Statement STMT-9182 issued 2026-03-02"
+_PAST_CAP_TEXT = "filler row\n" * 5000 + _PAST_CAP_RECORD
+_PAST_CAP_DOC = "<html><body><main>" + _PAST_CAP_TEXT + "</main></body></html>"
+
+
+def _past_cap_tools() -> list[Any]:
+ assert len(_PAST_CAP_TEXT) > 2 * taskv3_tools.HTML_MAX_CHARS
+ assert _PAST_CAP_RECORD not in _PAST_CAP_TEXT[: taskv3_tools.HTML_MAX_CHARS]
+ return build_browser_tools(_fixed_page_provider(_FakeTextPage(_PAST_CAP_DOC, _PAST_CAP_TEXT)))
+
+
+async def test_get_html_can_resume_a_read_past_the_cap() -> None:
+ # The cap bounds ONE result; it must not bound what the page can ever say. Without a way to
+ # advance the read, everything past the first 20000 chars is unreachable by any argument the
+ # model can pass, and the only remaining move is to guess at selectors for a region it cannot see.
+ tools = _past_cap_tools()
+ first = await _tool(tools, "get_html").handler({"format": "text"})
+ assert first.status == "ok" and _PAST_CAP_RECORD not in first.content
+
+ seen = first.content
+ offset = taskv3_tools.HTML_MAX_CHARS
+ for _ in range(5):
+ nxt = await _tool(tools, "get_html").handler({"format": "text", "offset": offset})
+ assert nxt.status == "ok", nxt.content
+ assert nxt.content != seen, "offset returned the same window — the read never advanced"
+ seen = nxt.content
+ if _PAST_CAP_RECORD in nxt.content:
+ break
+ offset += taskv3_tools.HTML_MAX_CHARS
+ assert _PAST_CAP_RECORD in seen, "the record past the cap was never reachable"
+
+
+async def test_get_html_cut_reports_how_much_it_did_not_return() -> None:
+ # A cut that says only THAT it happened leaves the model unable to tell a page it has nearly read
+ # from one it has barely started. The size it did not return, and the offset that continues the
+ # read, are effects of the read the tool knows and the model cannot infer.
+ tools = _past_cap_tools()
+ markup = await _tool(tools, "get_html").handler({})
+ assert markup.status == "ok"
+ assert str(len(_PAST_CAP_DOC)) in markup.content, markup.content[-300:]
+ assert f"offset={taskv3_tools.HTML_MAX_CHARS}" in markup.content, markup.content[-300:]
+
+ text = await _tool(tools, "get_html").handler({"format": "text"})
+ assert str(len(_PAST_CAP_TEXT)) in text.content, text.content[-300:]
+ assert f"offset={taskv3_tools.HTML_MAX_CHARS}" in text.content, text.content[-300:]
+
+
+async def test_get_html_offset_is_declared_so_the_model_can_use_it() -> None:
+ # An argument the handler honours but the spec never advertises is an argument no model passes.
+ tools = _past_cap_tools()
+ props = _tool(tools, "get_html").parameters["properties"]
+ assert "offset" in props and props["offset"]["type"] == "integer"
+
+
+async def test_get_html_offset_past_the_end_errors_rather_than_reading_as_empty() -> None:
+ # An empty string is what an empty page returns, so a read that ran off the end must not be one.
+ # It is an ERROR and not an ok result for a second reason: an ok result carrying a constant
+ # string would let a run page past the end forever under a fresh (tool, args) key every call —
+ # identical content the perception-stall guard cannot witness, because `live` takes the MINIMUM
+ # of the per-tool and per-probe counters and the per-probe one never leaves zero.
+ tools = _past_cap_tools()
+ r = await _tool(tools, "get_html").handler({"format": "text", "offset": 10 * len(_PAST_CAP_TEXT)})
+ assert r.status == "error"
+ assert r.error_class == "offset_past_end"
+ assert str(len(_PAST_CAP_TEXT)) in r.content, r.content
+
+
+async def test_get_html_normalizes_offset_so_one_read_has_one_identity() -> None:
+ # `args` is what the loop hashes into the call's identity, which decides what supersedes what in
+ # the transcript AND what counts as the same probe to the stall guard. Three spellings of a read
+ # of the same bytes must not be three identities.
+ tools = _past_cap_tools()
+ handler = _tool(tools, "get_html").handler
+ bare: dict[str, Any] = {"format": "text"}
+ zero: dict[str, Any] = {"format": "text", "offset": 0}
+ stringy: dict[str, Any] = {"format": "text", "offset": "20000"}
+ assert (await handler(bare)).content == (await handler(zero)).content
+ await handler(stringy)
+ assert bare == zero == {"format": "text"} # a zero offset is removed, not carried as a variant
+ assert stringy == {"format": "text", "offset": 20000} # and a parsed one is written back as int
+
+
+async def test_get_html_rejects_an_unusable_offset_instead_of_re_serving_the_head() -> None:
+ # Silently falling back to offset 0 would hand the model the window it already has, labelled as
+ # the one it asked for. Infinity is reachable: json.loads accepts the literal by default.
+ tools = _past_cap_tools()
+ for bad in (-1, "abc", float("inf"), True, {"a": 1}):
+ r = await _tool(tools, "get_html").handler({"format": "text", "offset": bad})
+ assert r.status == "error", (bad, r.content[:80])
+
+
+async def test_get_html_cut_notice_does_not_read_as_one_call_carrying_both_formats() -> None:
+ # The two formats index DIFFERENT strings, so an offset is not portable between them. A steer
+ # joined by `or` reads as a conjunction, and a model that sends {offset: N, format: text} lands
+ # at character N of a different, usually much shorter, document.
+ markup_cut = taskv3_tools._markup_cut(20000, 60000, scoped=False)
+ assert "format=text" in markup_cut and " or format=text" not in markup_cut
+ # A read that already carries a selector is not told to go FIND one — but it is told to repeat
+ # the one it has, which is a continuation instruction rather than advice.
+ scoped_text = taskv3_tools._rendered_text_cut(20000, 60000, scoped=True)
+ assert "a selector read or observe reaches one region directly" not in scoped_text
+ assert "the same selector" in scoped_text
+
+
+async def test_get_html_cut_notices_stay_stable_across_two_reads_of_one_page() -> None:
+ # get_html's content is hashed into the loop's perception digests, which decide whether a run has
+ # returned to known ground. A notice carrying anything call-scoped and varying would make an
+ # unchanged page read as fresh ground on every look.
+ tools = _past_cap_tools()
+ a = await _tool(tools, "get_html").handler({"format": "text", "offset": 20000})
+ b = await _tool(tools, "get_html").handler({"format": "text", "offset": 20000})
+ assert a.content == b.content
+ # No quote character in any notice: loop._TV3_MARKER_CUT_RE reads a marker the cut left open only
+ # while no quote follows it, and the notice is what follows.
+ assert '"' not in taskv3_tools._markup_cut(0, 1, scoped=False)
+ assert '"' not in taskv3_tools._markup_cut(0, 1, scoped=True)
+ assert '"' not in taskv3_tools._rendered_text_cut(0, 1, scoped=False)
+ assert '"' not in taskv3_tools._rendered_text_cut(0, 1, scoped=True)
+
+
+async def test_get_html_redacts_a_hidden_secret_before_a_window_boundary_can_split_it() -> None:
+ # SKY-16330. The loop hides model_hidden_values by whole-substring replacement, on what the tool
+ # returns. A secret straddling a window boundary matches neither half, so both halves would reach
+ # the model in the clear — and offsets are what make the second half reachable at all.
+ from skyvern.forge.sdk.core import skyvern_context
+ from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
+
+ secret = "MAGICLINKTOKEN-" + "S" * 60
+ boundary = taskv3_tools.HTML_MAX_CHARS - 20 # the secret starts 20 chars before the cut
+ text = "f" * boundary + secret + "t" * taskv3_tools.HTML_MAX_CHARS
+ ctx = SkyvernContext(organization_id="o_1")
+ ctx.register_secret_value(secret, hide_from_model=True)
+ skyvern_context.set(ctx)
+ try:
+ tools = build_browser_tools(_fixed_page_provider(_FakeTextPage("<html></html>", text)))
+ first = await _tool(tools, "get_html").handler({"format": "text"})
+ second = await _tool(tools, "get_html").handler({"format": "text", "offset": taskv3_tools.HTML_MAX_CHARS})
+ assert first.status == "ok" and second.status == "ok", (first.content[:80], second.content[:80])
+ joined = first.content + second.content
+ assert secret not in joined
+ # Neither HALF survives either: a split placeholder is harmless, a split secret is the bug.
+ assert secret[:20] not in joined, first.content[-120:]
+ assert secret[-20:] not in joined, second.content[:120]
+ finally:
+ skyvern_context.reset()
+
+
+async def test_get_html_offset_normalization_survives_the_selector_guards_arg_copy() -> None:
+ # `_with_selector_guard` hands the handler a COPY of args whenever a selector is present, and the
+ # loop hashes the CALLER's dict into the call identity. A normalization applied inside that copy
+ # would unify nothing for exactly the reads most likely to be repeated.
+ tools = _past_cap_tools()
+ handler = _tool(tools, "get_html").handler
+ zero: dict[str, Any] = {"selector": "body", "offset": 0}
+ stringy: dict[str, Any] = {"selector": "body", "offset": "20000"}
+ await handler(zero)
+ await handler(stringy)
+ assert zero == {"selector": "body"}
+ assert stringy == {"selector": "body", "offset": 20000}
+
+
+async def test_a_cut_read_reports_where_it_put_its_notice() -> None:
+ # The loop folds the notice out of the perception digest at the index reported here — there is no
+ # pattern and no wording coupling left, which is what makes the fold immune to page- and
+ # server-authored text wearing the same shape. The contract is that the index is exact.
+ tools = _past_cap_tools()
+ r = await _tool(tools, "get_html").handler({})
+ assert r.status == "ok"
+ at = (r.data or {}).get("notice_at")
+ assert isinstance(at, int), r.data
+ assert r.content[at:].startswith("…["), r.content[at : at + 40]
+ assert r.content[at:].endswith("]")
+ # And the part before it is exactly one window of the document, notice excluded.
+ assert len(r.content[:at]) == taskv3_tools.HTML_MAX_CHARS
+
+ # A read that was NOT cut reports no boundary, so nothing is folded for it.
+ tail = await _tool(tools, "get_html").handler({"offset": len(_PAST_CAP_DOC) - 10})
+ assert tail.status == "ok"
+ assert (tail.data or {}).get("notice_at") is None, tail.data
+
+
+async def test_get_html_rejects_a_fractional_offset_rather_than_reading_a_different_window() -> None:
+ # int(20000.9) is 20000, so truncating would execute and record a DIFFERENT read from the one
+ # asked for, under a handler that promises to reject a non-whole character count.
+ tools = _past_cap_tools()
+ r = await _tool(tools, "get_html").handler({"format": "text", "offset": 20000.9})
+ assert r.status == "error" and r.error_class == "invalid_offset", r.content
+ # A whole-valued float is still a whole number of characters and is accepted.
+ ok = await _tool(tools, "get_html").handler({"format": "text", "offset": 20000.0})
+ assert ok.status == "ok", ok.content
+
+
+async def test_get_html_equivalent_format_spellings_are_one_read_identity() -> None:
+ # The handler strips, lowercases and defaults `format`, so these are all one read. `args` is what
+ # the loop hashes into the call identity, and with a retention window of two, duplicates of one
+ # region would fill it and evict the different region the window exists to hold.
+ tools = _past_cap_tools()
+ handler = _tool(tools, "get_html").handler
+ # Including the spellings a non-strict provider reaches for when an optional argument is absent:
+ # omitted, null, and empty. The handler reads all of these as the whole-page HTML read.
+ spellings: list[dict[str, Any]] = [
+ {},
+ {"format": "html"},
+ {"format": " HTML "},
+ {"format": ""},
+ {"format": None},
+ {"selector": None},
+ {"selector": ""},
+ ]
+ for args in spellings:
+ await handler(args)
+ assert spellings == [{}] * 7
+
+ # Whitespace is NOT one of them. It is not "absent" — the handler acts on it and reports what the
+ # model typed, and collapsing it here would turn a named error into a silent whole-page read.
+ kept: list[dict[str, Any]] = [{"selector": " "}, {"format": " "}]
+ for args in kept:
+ await handler(args)
+ assert kept == [{"selector": " "}, {"format": " "}]
+
+ texts: list[dict[str, Any]] = [{"format": "text"}, {"format": " Text "}]
+ for args in texts:
+ await handler(args)
+ assert texts == [{"format": "text"}, {"format": "text"}]
+
+ # An unrecognized spelling is left as typed so the handler's error names what the model wrote.
+ bad: dict[str, Any] = {"format": "txt"}
+ r = await handler(bad)
+ assert r.status == "error" and "txt" in r.content
+ assert bad == {"format": "txt"}
+
+
+async def test_following_a_text_cut_literally_continues_the_text_not_the_markup() -> None:
+ # `get_html` defaults format to html, so a cut TEXT read whose notice names only an offset sends
+ # the model to that character of the MARKUP — a different string, the same integer, and a
+ # continuation from a meaningless position it cannot detect.
+ #
+ # Asserted as an EQUIVALENCE, not as "the notice mentions format": the arguments the notice
+ # prescribes must produce the same read as spelling the format out. A containment check on the
+ # string passes for the wrong reason.
+ tools = _past_cap_tools()
+ handler = _tool(tools, "get_html").handler
+
+ first = await handler({"format": "text"})
+ assert first.status == "ok" and first.content.endswith("]"), first.content[-120:]
+
+ prescribed: dict[str, Any] = {}
+ for token in first.content.rsplit("…[", 1)[-1].replace("]", " ").split():
+ if "=" in token:
+ key, _, value = token.partition("=")
+ if key in ("offset", "format"):
+ prescribed[key] = int(value) if key == "offset" else value
+ assert prescribed.get("offset"), first.content[-200:]
+
+ followed = await handler(dict(prescribed))
+ spelled_out = await handler({"format": "text", "offset": prescribed["offset"]})
+ assert followed.status == "ok", followed.content
+ assert followed.content == spelled_out.content, "following the notice read a different string"
+ # And it is genuinely the text continuation, not markup starting at the same integer.
+ assert "<" not in followed.content[:200], followed.content[:200]
+
+
+def test_a_cut_notice_names_every_argument_that_identifies_the_read() -> None:
+ # Tool arguments do not carry between calls, so a notice that omits one sends a model following
+ # it literally to the same integer offset of a DIFFERENT string: an omitted `format` defaults to
+ # markup, an omitted `selector` widens to the whole page. Both are silent.
+ for scoped in (False, True):
+ for cut in (taskv3_tools._markup_cut, taskv3_tools._rendered_text_cut):
+ notice = cut(20000, 60000, scoped=scoped)
+ assert "offset=20000" in notice, notice
+ assert ("the same selector" in notice) is scoped, notice
+ assert ("format=text and offset" in notice) is (cut is taskv3_tools._rendered_text_cut), notice
+ # The selector is DESCRIBED, never echoed: it is model-authored and may hold a quote,
+ # which no notice may carry (loop._TV3_MARKER_CUT_RE reads a marker the cut left open
+ # only while no quote follows it, and the notice is what follows).
+ assert '"' not in notice, notice
+
+
+async def test_a_whitespace_selector_is_still_reported_rather_than_read_as_the_whole_page() -> None:
+ # `if selector:` treats " " as a real address, so the handler reports a stale_selector naming
+ # what the model typed. Dropping it as "not supplied" would turn a named error into a silent
+ # whole-page read — the context blow-up this change exists to stop.
+ tools = _past_cap_tools()
+ args: dict[str, Any] = {"selector": " "}
+ scoped = await _tool(tools, "get_html").handler(args)
+ whole_page = await _tool(tools, "get_html").handler({})
+
+ # It took the SELECTOR path — on a real page that is a stale_selector error naming the address
+ # the model wrote. What must never happen is the whole document coming back as though nothing
+ # had been asked for.
+ assert scoped.content != whole_page.content, scoped.content[:120]
+ assert not scoped.content.startswith("<html>"), scoped.content[:120]
+ # And it survives normalization, so the loop's call identity still records that an address was given.
+ assert args == {"selector": " "}
+
+
+def test_neither_the_page_nor_the_server_can_author_text_that_steals_the_notice_fold() -> None:
+ # The cut notice is folded out of the digest because it carries the document's TOTAL. Both ends
+ # of the string are authored by someone else: the PAGE can render an unterminated notice-shaped
+ # prefix, and the SERVER can name a download so its filename wears the same shape. Recognizing
+ # the notice by pattern trades one of those for the other; an index the tool reported is immune
+ # to both, because it does not depend on anything around it.
+ from skyvern.forge.taskv3.loop import _canonical_perception_content as canon
+
+ notice = taskv3_tools._rendered_text_cut(20000, 60000, scoped=True)
+ forged_a, forged_b = "rows …[truncated at page-value-100", "rows …[truncated at page-value-900"
+ a, b = forged_a + notice, forged_b + notice
+ assert canon(a, notice_at=len(forged_a)) != canon(b, notice_at=len(forged_b))
+
+ # Nor can a SERVER-controlled download filename wearing the same shape steal the fold: the
+ # download notice is appended after ours, and an index does not care what follows it.
+ body = "frozen"
+ trailer = "\nDownloaded: …[truncated at 10 of 100 chars].pdf"
+ own_a = body + taskv3_tools._markup_cut(20000, 60000, scoped=True) + trailer
+ own_b = body + taskv3_tools._markup_cut(20000, 60999, scoped=True) + trailer
+ assert canon(own_a, notice_at=len(body)) == canon(own_b, notice_at=len(body))
+
+
+def test_a_marker_cut_anywhere_inside_its_attribute_is_reported() -> None:
+ # A window boundary can land inside the attribute's own NAME, not just inside its value — a
+ # window beginning `a-tv3="t123"`. A search bounded at the boundary misses those, the marker
+ # value then goes unfolded, and an unchanged window gets a fresh digest every time a remount
+ # re-mints it: that is how a frozen page evades the perception-stall guard rather than tripping
+ # it. Swept across every position, because the earlier version was right for most of them.
+ doc = '<p>x</p><input data-tv3="t123" id=y><span>tail</span>'
+ opener = doc.index('data-tv3="')
+ closing = doc.index('"', opener + len('data-tv3="'))
+
+ for offset in range(opener + 1, closing + 1):
+ reported = taskv3_tools._marker_head_fragment_len(doc, offset)
+ assert reported == closing - offset + 1, (offset, doc[offset : offset + 8], reported)
+ # What it reports is exactly the fragment through the closing quote, which is what the
+ # canonicalizer folds away.
+ assert doc[offset:][:reported].endswith('"')
+
+ # A boundary with nothing open at it reports nothing.
+ assert taskv3_tools._marker_head_fragment_len(doc, opener) == 0
+ assert taskv3_tools._marker_head_fragment_len(doc, closing + 1) == 0
+ assert taskv3_tools._marker_head_fragment_len(doc, 0) == 0
+
+
+def test_only_an_engine_minted_marker_value_is_folded_at_a_window_head() -> None:
+ # A page can author `data-tv3` itself — it is an ordinary attribute — so matching the opener and
+ # the closing quote is not enough. Folding a page-authored value that is genuinely changing makes
+ # the window read as frozen, and the perception-stall guard TERMINATES on that.
+ #
+ # This is not the shape-matching a FRAGMENT forbids: by the time the closing quote is found the
+ # whole value is in hand, and a complete value is unambiguous where a prefix is not. It is the
+ # same test `MINTED_MARKER_RE` applies in the observe JS before trusting one as a selector.
+ minted = ("t123", "t0", "t123-4")
+ foreign = ("balance-100", "", "t1a", "T123", "t", "123", "t123 ", "t-1", "t 1")
+
+ for value in minted + foreign:
+ doc = f'<i data-tv3="{value}" x><b>tail</b>'
+ opener = doc.index('data-tv3="')
+ closing = doc.index('"', opener + len('data-tv3="'))
+ # Sweep every boundary inside the attribute, name and value alike.
+ for offset in range(opener + 1, closing + 1):
+ reported = taskv3_tools._marker_head_fragment_len(doc, offset)
+ if value in minted:
+ assert reported == closing - offset + 1, (value, offset, reported)
+ else:
+ assert reported == 0, (value, offset, reported)