Skip to content

Automate browser based workflows with AI

Copilot: grounded parameterized-selection so persisted code reads a click-embedded input (SKY-12316, partial) (#7397)

Andrew Neilson1ea96ebca281
diff --git a/skyvern/forge/sdk/copilot/code_block_synthesis.py b/skyvern/forge/sdk/copilot/code_block_synthesis.py
index a75268419..282b0cadb 100644
--- a/skyvern/forge/sdk/copilot/code_block_synthesis.py
+++ b/skyvern/forge/sdk/copilot/code_block_synthesis.py
@@ -33,6 +33,7 @@ from skyvern.forge.sdk.copilot.output_extraction_plan import (
output_path_segments,
)
from skyvern.forge.sdk.copilot.reached_download_target import ReachedDownloadTarget
+from skyvern.forge.sdk.copilot.runtime import ScoutedInputCorrespondence
from skyvern.utils.strings import escape_code_fences
LOG = structlog.get_logger()
@@ -47,6 +48,7 @@ _ENTRY_RESUME_TARGET_VAR = "_scout_entry_resume_target"
_ENTRY_OPENER_VAR = "_scout_entry_opener"
_OPTIONAL_DISMISSAL_VAR = "_scout_optional_dismissal"
_READONLY_DEFERRED_VAR = "_scout_readonly_actual"
+_MONTH_HELPER_VAR = "_scout_month_to_iso"
_ENTRY_LOCATOR_VARS = (_ENTRY_TARGET_VAR, _ENTRY_RESUME_TARGET_VAR, _ENTRY_OPENER_VAR)
_INTERNAL_SCOUT_VARS = (
_ENTRY_TARGET_VAR,
@@ -56,6 +58,7 @@ _INTERNAL_SCOUT_VARS = (
_ENTRY_OPENER_VAR,
_OPTIONAL_DISMISSAL_VAR,
_READONLY_DEFERRED_VAR,
+ _MONTH_HELPER_VAR,
)
# Base name for the download var bound by `async with page.expect_download() as <name>:`.
@@ -217,6 +220,7 @@ _RESERVED_PARAM_NAMES = frozenset(
"password",
"totp",
"totp_identifier",
+ "otp",
"print",
"len",
"range",
@@ -247,6 +251,7 @@ _RESERVED_PARAM_NAMES = frozenset(
_ENTRY_RESUME_AFTER_AUTH_VAR,
_ENTRY_RESUME_TARGET_VAR,
_ENTRY_OPENER_VAR,
+ _MONTH_HELPER_VAR,
_DOWNLOAD_VAR_BASE,
f"{_DOWNLOAD_VAR_BASE}_file",
_DOWNLOAD_FILENAME_VAR_BASE,
@@ -434,6 +439,367 @@ def _get_by_role_expr_strict(role: str, name: str) -> str:
return f"page.get_by_role({_py_str(role)}, name={_py_str(name)}, exact=True)"
+LOCATOR_WITNESS_PARAM_SOURCE = "locator_witness"
+INPUT_TEMPLATED_PROVENANCE_SOURCE = "input_templated"
+_SCOUT_MONTH_HELPER_NAME = _MONTH_HELPER_VAR
+_WITNESS_MIN_VALUE_LEN = 3
+_WITNESS_SAFE_CHARSET_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 ._-]*$")
+_WITNESS_KEY_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_WITNESS_MONTH_TO_ISO = {
+ "january": "01",
+ "february": "02",
+ "march": "03",
+ "april": "04",
+ "may": "05",
+ "june": "06",
+ "july": "07",
+ "august": "08",
+ "september": "09",
+ "october": "10",
+ "november": "11",
+ "december": "12",
+}
+
+
+class _InputTemplatingPlan(NamedTuple):
+ surface: str
+ selector: str
+ role: str
+ name: str
+ holes: list[Mapping[str, Any]]
+
+
+def _witness_key_is_safe(key: str) -> bool:
+ if not _WITNESS_KEY_IDENT_RE.fullmatch(key):
+ return False
+ if keyword.iskeyword(key):
+ return False
+ if key.startswith("_scout"):
+ return False
+ return key not in _RESERVED_PARAM_NAMES
+
+
+def _month_name_to_iso(value: str) -> str | None:
+ parts = value.split()
+ if len(parts) != 2:
+ return None
+ month = _WITNESS_MONTH_TO_ISO.get(parts[0].lower())
+ year = parts[1]
+ if month is None or len(year) != 4 or not year.isdigit():
+ return None
+ return f"{year}-{month}"
+
+
+def _witness_observed_forms(value: str) -> list[tuple[str, str]]:
+ forms: list[tuple[str, str]] = [("identity", value)]
+ iso = _month_name_to_iso(value)
+ if iso is not None and iso != value:
+ forms.append(("month_name_to_iso", iso))
+ return forms
+
+
+def _quoted_content_spans(selector: str) -> list[tuple[int, int]]:
+ spans: list[tuple[int, int]] = []
+ quote = ""
+ start = -1
+ i = 0
+ length = len(selector)
+ while i < length:
+ ch = selector[i]
+ if quote:
+ if ch == "\\":
+ i += 2
+ continue
+ if ch == quote:
+ spans.append((start, i))
+ quote = ""
+ elif ch in ("'", '"'):
+ quote = ch
+ start = i + 1
+ i += 1
+ return spans
+
+
+def _boundary_delimited_positions(haystack: str, needle: str, allowed_spans: Sequence[tuple[int, int]]) -> list[int]:
+ positions: list[int] = []
+ if not needle:
+ return positions
+ start = 0
+ while True:
+ idx = haystack.find(needle, start)
+ if idx < 0:
+ break
+ end = idx + len(needle)
+ left_ok = idx == 0 or not haystack[idx - 1].isalnum()
+ right_ok = end == len(haystack) or not haystack[end].isalnum()
+ inside = any(span_start <= idx and end <= span_end for span_start, span_end in allowed_spans)
+ if left_ok and right_ok and inside:
+ positions.append(idx)
+ start = idx + 1
+ return positions
+
+
+def _resolve_non_competing_correspondences(raw: list[dict[str, Any]]) -> list[ScoutedInputCorrespondence]:
+ result: list[ScoutedInputCorrespondence] = []
+ for surface in ("selector", "accessible_name"):
+ entries = sorted((entry for entry in raw if entry["surface"] == surface), key=lambda entry: entry["_position"])
+ key_counts: dict[str, int] = {}
+ for entry in entries:
+ key_counts[entry["input_key"]] = key_counts.get(entry["input_key"], 0) + 1
+ bad: set[int] = set()
+ for a_index, a_entry in enumerate(entries):
+ if key_counts[a_entry["input_key"]] > 1:
+ bad.add(a_index)
+ a_start = a_entry["_position"]
+ a_end = a_start + len(a_entry["matched_literal"])
+ for b_index in range(a_index + 1, len(entries)):
+ b_start = entries[b_index]["_position"]
+ b_end = b_start + len(entries[b_index]["matched_literal"])
+ if a_start < b_end and b_start < a_end:
+ bad.add(a_index)
+ bad.add(b_index)
+ for index, entry in enumerate(entries):
+ if index in bad:
+ continue
+ result.append(
+ {
+ "input_key": entry["input_key"],
+ "matched_literal": entry["matched_literal"],
+ "parameter_value": entry["parameter_value"],
+ "surface": entry["surface"],
+ "transform": entry["transform"],
+ "position": entry["_position"],
+ }
+ )
+ return result
+
+
+def input_correspondences_for_interaction(
+ interaction: Mapping[str, Any], declared_params: Mapping[str, str]
+) -> list[ScoutedInputCorrespondence]:
+ """Witness a declared parameter value observed verbatim (identity, or month-name -> ISO) inside a
+ quoted selector segment or the accessible name at click time — value containment, never label==header
+ matching. Empty unless the match is unique across both surfaces, boundary-delimited, safe-charset on
+ value and literal, whitespace-normalized, and name-safe."""
+ if str(interaction.get("tool_name") or "") != "click":
+ return []
+ selector = str(interaction.get("selector") or "").strip()
+ name = str(interaction.get("accessible_name") or "").strip()
+ selector_spans = _quoted_content_spans(selector)
+ name_spans = [(0, len(name))] if name else []
+ raw: list[dict[str, Any]] = []
+ for key in sorted(declared_params):
+ value = declared_params[key]
+ if not value or value != value.strip() or len(value) < _WITNESS_MIN_VALUE_LEN:
+ continue
+ if not _WITNESS_SAFE_CHARSET_RE.fullmatch(value):
+ continue
+ if not _witness_key_is_safe(key):
+ continue
+ for transform, observed in _witness_observed_forms(value):
+ if len(observed) < _WITNESS_MIN_VALUE_LEN or not _WITNESS_SAFE_CHARSET_RE.fullmatch(observed):
+ continue
+ selector_positions = _boundary_delimited_positions(selector, observed, selector_spans)
+ name_positions = _boundary_delimited_positions(name, observed, name_spans)
+ if len(selector_positions) + len(name_positions) != 1:
+ continue
+ if selector_positions:
+ surface, position = "selector", selector_positions[0]
+ else:
+ surface, position = "accessible_name", name_positions[0]
+ raw.append(
+ {
+ "surface": surface,
+ "input_key": key,
+ "matched_literal": observed,
+ "parameter_value": value,
+ "transform": transform,
+ "_position": position,
+ }
+ )
+ return _resolve_non_competing_correspondences(raw)
+
+
+def _escape_fstring_literal_segment(value: str) -> str:
+ escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "\\r")
+ escaped = "".join(f"\\x{ord(ch):02x}" if ch in _CONTROL_CODEPOINTS else ch for ch in escaped)
+ for separator in _EXTRA_LINE_SEPARATORS:
+ escaped = escaped.replace(separator, f"\\u{ord(separator):04x}")
+ return escaped.replace("{", "{{").replace("}", "}}")
+
+
+def _interpolate_holes(raw: str, holes: Sequence[Mapping[str, Any]]) -> str | None:
+ segments: list[str] = []
+ cursor = 0
+ for hole in holes:
+ matched_literal = str(hole.get("matched_literal") or "")
+ idx = hole.get("position")
+ # Interpolate at the boundary-validated span carried from the witness, not a naive substring
+ # scan: a value that also occurs earlier as a non-boundary substring would template the wrong span.
+ if not isinstance(idx, int) or idx < cursor or raw[idx : idx + len(matched_literal)] != matched_literal:
+ return None
+ segments.append(_escape_fstring_literal_segment(raw[cursor:idx]))
+ key = str(hole.get("input_key") or "")
+ if str(hole.get("transform") or "identity") == "month_name_to_iso":
+ segments.append("{" + _SCOUT_MONTH_HELPER_NAME + "(" + key + ")}")
+ else:
+ segments.append("{" + key + "}")
+ cursor = idx + len(matched_literal)
+ segments.append(_escape_fstring_literal_segment(raw[cursor:]))
+ return "".join(segments)
+
+
+def build_input_templated_locator(
+ *, surface: str, selector: str, role: str, name: str, holes: Sequence[Mapping[str, Any]]
+) -> str | None:
+ """Single source for the templated locator literal, used at emission AND re-derived byte-for-byte at
+ the admissibility seam so a tampered or reordered provenance record fails the recompute equality check."""
+ if not holes:
+ return None
+ if surface == "selector":
+ body = _interpolate_holes(selector, holes)
+ if body is None:
+ return None
+ return f'page.locator(f"{body}")'
+ if surface == "accessible_name":
+ if not role or not name:
+ return None
+ body = _interpolate_holes(name, holes)
+ if body is None:
+ return None
+ return f'page.get_by_role({_py_str(role)}, name=f"{body}", exact=True)'
+ return None
+
+
+def _ordered_holes(raw: str, holes: Sequence[Mapping[str, Any]]) -> list[Mapping[str, Any]] | None:
+ positioned: list[tuple[int, Mapping[str, Any]]] = []
+ for hole in holes:
+ matched_literal = str(hole.get("matched_literal") or "")
+ idx = hole.get("position")
+ if not isinstance(idx, int) or raw[idx : idx + len(matched_literal)] != matched_literal:
+ return None
+ positioned.append((idx, hole))
+ positioned.sort(key=lambda item: item[0])
+ return [hole for _, hole in positioned]
+
+
+def _input_templating_plan(interaction: Mapping[str, Any]) -> _InputTemplatingPlan | None:
+ correspondences = interaction.get("input_correspondences")
+ if not isinstance(correspondences, list) or not correspondences:
+ return None
+ selector = str(interaction.get("selector") or "").strip()
+ role = str(interaction.get("role") or "").strip()
+ name = str(interaction.get("accessible_name") or "").strip()
+ selector_holes = [c for c in correspondences if isinstance(c, Mapping) and c.get("surface") == "selector"]
+ name_holes = [c for c in correspondences if isinstance(c, Mapping) and c.get("surface") == "accessible_name"]
+ parsed = _parse_role_name(selector) if selector else None
+ if (
+ selector_holes
+ and selector
+ and parsed is None
+ and not _is_positional_selector(selector)
+ and not _is_bare_ambiguous_selector(selector)
+ ):
+ ordered = _ordered_holes(selector, selector_holes)
+ if ordered is not None:
+ return _InputTemplatingPlan(surface="selector", selector=selector, role="", name="", holes=ordered)
+ if name_holes and role and name:
+ ambiguous_role = parsed is not None and not parsed[1]
+ if not selector or _is_bare_ambiguous_selector(selector) or ambiguous_role:
+ ordered = _ordered_holes(name, name_holes)
+ if ordered is not None:
+ return _InputTemplatingPlan(surface="accessible_name", selector="", role=role, name=name, holes=ordered)
+ return None
+
+
+def _maybe_input_templated_locator(
+ interaction: Mapping[str, Any],
+ *,
+ diagnostics: SynthesisDiagnostics | None,
+ trajectory_index: int | None,
+) -> str | None:
+ plan = _input_templating_plan(interaction)
+ if plan is None:
+ return None
+ expr = build_input_templated_locator(
+ surface=plan.surface, selector=plan.selector, role=plan.role, name=plan.name, holes=plan.holes
+ )
+ if expr is None:
+ return None
+ if diagnostics is not None:
+ record: dict[str, Any] = {
+ "trajectory_index": trajectory_index if trajectory_index is not None else -1,
+ "source": INPUT_TEMPLATED_PROVENANCE_SOURCE,
+ "surface": plan.surface,
+ "emitted_literal": expr,
+ "holes": [
+ {
+ "input_key": str(hole.get("input_key") or ""),
+ "matched_literal": str(hole.get("matched_literal") or ""),
+ "parameter_value": str(hole.get("parameter_value") or ""),
+ "transform": str(hole.get("transform") or "identity"),
+ "position": hole.get("position"),
+ }
+ for hole in plan.holes
+ ],
+ }
+ if plan.surface == "selector":
+ record["selector"] = plan.selector
+ else:
+ record["role"] = plan.role
+ record["name"] = plan.name
+ diagnostics.locator_provenance.append(record)
+ return expr
+
+
+def _prescan_input_templating(trajectory: Sequence[Mapping[str, Any]]) -> tuple[list[str], bool]:
+ keys: list[str] = []
+ needs_month = False
+ for interaction in trajectory:
+ plan = _input_templating_plan(interaction)
+ if plan is None:
+ continue
+ for hole in plan.holes:
+ key = str(hole.get("input_key") or "")
+ if key and key not in keys:
+ keys.append(key)
+ if str(hole.get("transform") or "identity") == "month_name_to_iso":
+ needs_month = True
+ return keys, needs_month
+
+
+def _scout_month_helper_lines() -> list[str]:
+ month_map_literal = "{" + ", ".join(f'"{name}": "{code}"' for name, code in _WITNESS_MONTH_TO_ISO.items()) + "}"
+ return [
+ f"{_INDENT}def {_SCOUT_MONTH_HELPER_NAME}(_value):",
+ f"{_INDENT * 2}_months = {month_map_literal}",
+ f"{_INDENT * 2}_parts = str(_value).split()",
+ f"{_INDENT * 2}if len(_parts) != 2 or _parts[0].lower() not in _months or not (len(_parts[1]) == 4 "
+ f"and _parts[1].isdigit()):",
+ f'{_INDENT * 3}raise Exception("unrecognized month value for grounded parameter")',
+ f'{_INDENT * 2}return _parts[1] + "-" + _months[_parts[0].lower()]',
+ ]
+
+
+def _witness_charset_guard_lines(key: str) -> list[str]:
+ return [
+ f"{_INDENT}if not (isinstance({key}, str) and {key} == {key}.strip() and {key}[:1].isalnum() "
+ f'and all(_c.isalnum() or _c in " ._-" for _c in {key})):',
+ f"{_INDENT * 2}raise Exception({_py_str(f'invalid value for grounded parameter {key}')})",
+ ]
+
+
+def witness_prelude_lines(keys: Sequence[str], *, include_month_helper: bool) -> list[str]:
+ """Top-of-body guards (fail closed before any interpolation) plus the reserved month helper def.
+ Reinjected into every separated browser stage because each stage is an independent CodeBlock."""
+ lines: list[str] = []
+ if include_month_helper:
+ lines.extend(_scout_month_helper_lines())
+ for key in keys:
+ lines.extend(_witness_charset_guard_lines(key))
+ return lines
+
+
def _locator_expr(
interaction: Mapping[str, Any],
notes: list[str],
@@ -454,6 +820,10 @@ def _locator_expr(
role = str(interaction.get("role") or "").strip()
name = str(interaction.get("accessible_name") or "").strip()
+ templated = _maybe_input_templated_locator(interaction, diagnostics=diagnostics, trajectory_index=trajectory_index)
+ if templated is not None:
+ return templated
+
if strict_selectors:
if not selector:
notes.append("dropped an interaction with no selector")
@@ -842,6 +1212,34 @@ def synthesize_code_block(
)
diagnostics.retained_trajectory_indices = list(range(len(trajectory)))
+ input_templated_keys, input_templated_needs_month = _prescan_input_templating(trajectory)
+ minted_input_witness_keys: set[str] = set()
+ for interaction in trajectory:
+ plan = _input_templating_plan(interaction)
+ if plan is None:
+ continue
+ for hole in plan.holes:
+ key = str(hole.get("input_key") or "")
+ if not key or key in minted_input_witness_keys:
+ continue
+ minted_input_witness_keys.add(key)
+ parameters.append(
+ {
+ "key": key,
+ "default_value": str(hole.get("parameter_value") or ""),
+ "source": LOCATOR_WITNESS_PARAM_SOURCE,
+ }
+ )
+ for key in input_templated_keys:
+ used_param_keys.add(key)
+ if input_templated_keys:
+ lines.extend(witness_prelude_lines(input_templated_keys, include_month_helper=input_templated_needs_month))
+ LOG.info(
+ "copilot_spine_input_templated_prelude",
+ witness_keys=input_templated_keys,
+ month_helper=input_templated_needs_month,
+ )
+
def append_step(description: str, action_type: str, line_start: int) -> None:
steps.append(
{
diff --git a/skyvern/forge/sdk/copilot/runtime.py b/skyvern/forge/sdk/copilot/runtime.py
index 1f2a53973..b2f0bfbb9 100644
--- a/skyvern/forge/sdk/copilot/runtime.py
+++ b/skyvern/forge/sdk/copilot/runtime.py
@@ -176,11 +176,23 @@ class AuthorTimeGateAblationEvent:
payload: AuthorTimeGateAblationPayload = field(default_factory=dict)
+class ScoutedInputCorrespondence(TypedDict):
+ input_key: str
+ matched_literal: str
+ parameter_value: str
+ surface: str
+ transform: str
+ position: int
+
+
class ScoutedInteraction(TypedDict):
tool_name: str
selector: NotRequired[str]
source_url: NotRequired[str]
value: NotRequired[str]
+ # Grounded value-containment witnesses computed at the update_workflow confluence; drive
+ # generator-owned templated locators. Empty/absent => literal replay.
+ input_correspondences: NotRequired[list[ScoutedInputCorrespondence]]
typed_value: NotRequired[str]
key: NotRequired[str]
typed_length: NotRequired[int]
diff --git a/skyvern/forge/sdk/copilot/tools/workflow_update.py b/skyvern/forge/sdk/copilot/tools/workflow_update.py
index 5a406a16d..867637ed7 100644
--- a/skyvern/forge/sdk/copilot/tools/workflow_update.py
+++ b/skyvern/forge/sdk/copilot/tools/workflow_update.py
@@ -57,6 +57,8 @@ from skyvern.forge.sdk.copilot.code_block_synthesis import (
_INTERNAL_SCOUT_VARS,
_SYNTHESIZED_BLOCK_LABEL,
CREDENTIAL_FILL_TOOL_NAME,
+ INPUT_TEMPLATED_PROVENANCE_SOURCE,
+ LOCATOR_WITNESS_PARAM_SOURCE,
SCOUTED_SPINE_DROPPED_UNFORGIVEN_REASON_CODE,
SCOUTED_SPINE_TRUNCATED_REASON_CODE,
SCOUTED_SPINE_UNDER_BUILD_REASON_CODE,
@@ -73,8 +75,10 @@ from skyvern.forge.sdk.copilot.code_block_synthesis import (
_selector_refines,
artifact_dependency_id,
artifact_observation_ref_id,
+ build_input_templated_locator,
credential_scout_gap,
freeze_requested_output_extraction_candidate,
+ input_correspondences_for_interaction,
locator_selector_literals,
missing_rung_text,
normalized_locator_expr,
@@ -5967,6 +5971,19 @@ def _locator_provenance_is_self_validating(provenance: Mapping[str, Any]) -> boo
role = str(provenance.get("role") or "")
name = str(provenance.get("name") or "")
return bool(role) and bool(name) and _get_by_role_expr_strict(role, name) == provenance.get("emitted_literal")
+ if source == INPUT_TEMPLATED_PROVENANCE_SOURCE:
+ surface = str(provenance.get("surface") or "")
+ holes = provenance.get("holes")
+ if not isinstance(holes, list) or not holes:
+ return False
+ recomputed = build_input_templated_locator(
+ surface=surface,
+ selector=str(provenance.get("selector") or ""),
+ role=str(provenance.get("role") or ""),
+ name=str(provenance.get("name") or ""),
+ holes=holes,
+ )
+ return recomputed is not None and recomputed == provenance.get("emitted_literal")
return False
@@ -7466,7 +7483,7 @@ def _apply_scouted_typed_default_promotions(workflow_yaml: str, ctx: AgentContex
defaults_by_value: dict[str, list[str]] = {}
for parameter in synthesized.parameters:
- if parameter.get("credential_id"):
+ if parameter.get("credential_id") or parameter.get("source") == LOCATOR_WITNESS_PARAM_SOURCE:
continue
key = str(parameter.get("key") or "").strip()
default_value = str(parameter.get("default_value") or "").strip()
@@ -7744,7 +7761,9 @@ def _scout_interaction_for_synthesized_parameter(
non_credential_keys = [
str(parameter.get("key") or "").strip()
for parameter in synthesized_parameters
- if str(parameter.get("key") or "").strip() and not parameter.get("credential_id")
+ if str(parameter.get("key") or "").strip()
+ and not parameter.get("credential_id")
+ and parameter.get("source") != LOCATOR_WITNESS_PARAM_SOURCE
]
typed_interactions = [
interaction for interaction in scout_trajectory if str(interaction.get("tool_name") or "") == "type_text"
@@ -7788,7 +7807,11 @@ def _reconcile_synthesized_parameters(
aliases: dict[str, str] = {}
used_selector_join_aliases: set[str] = set()
repair_context: CodeAuthoringRepairContext | None = None
- non_credential_synthesized = [param for param in synthesized_parameters if not param.get("credential_id")]
+ non_credential_synthesized = [
+ param
+ for param in synthesized_parameters
+ if not param.get("credential_id") and param.get("source") != LOCATOR_WITNESS_PARAM_SOURCE
+ ]
typed_lengths = [
int(interaction.get("typed_length") or 0)
for interaction in scout_trajectory
@@ -7972,8 +7995,16 @@ def _synthesized_durable_stage_codes(synthesized: SynthesizedCodeBlock, *, sourc
ranges.append((start, end))
if ranges != sorted(ranges):
return []
- stage_codes = ["\n".join(lines[start - 1 : end]).strip() for start, end in ranges]
- return [code for code in stage_codes if code]
+ # The witness prelude (runtime charset guards + month helper) sits above the first step range, so the
+ # slice would drop it; each separated stage is an independent CodeBlock that must carry its own guards.
+ prelude = "\n".join(lines[: ranges[0][0] - 1]).strip()
+ stage_codes: list[str] = []
+ for start, end in ranges:
+ body = "\n".join(lines[start - 1 : end]).strip()
+ if not body:
+ continue
+ stage_codes.append(f"{prelude}\n{body}" if prelude else body)
+ return stage_codes
def _top_level_block_list_for_selected_code_block(
@@ -9517,6 +9548,49 @@ def _reject_schema_incompatibility(
)
+def _declared_string_parameter_values(workflow_yaml: str) -> dict[str, str]:
+ parsed = parse_workflow_yaml(workflow_yaml)
+ if not isinstance(parsed, dict):
+ return {}
+ workflow_definition = parsed.get("workflow_definition")
+ if not isinstance(workflow_definition, dict):
+ return {}
+ parameters = workflow_definition.get("parameters")
+ if not isinstance(parameters, list):
+ return {}
+ values: dict[str, str] = {}
+ for parameter in parameters:
+ if not isinstance(parameter, Mapping):
+ continue
+ key = str(parameter.get("key") or "").strip()
+ if not key:
+ continue
+ default_value = _string_parameter_default_value(parameter)
+ if isinstance(default_value, str) and default_value:
+ values[key] = default_value
+ return values
+
+
+def _enrich_scout_trajectory_input_correspondences(workflow_yaml: str, ctx: AgentContext) -> None:
+ """Match the submitted workflow's declared string-parameter values against each scout click's captured
+ literals and stamp the correspondence onto the trajectory once, so every synthesize_code_block call reads
+ it. Idempotent; empty declared params clears prior stamps."""
+ scout_trajectory = ctx.scout_trajectory
+ if not scout_trajectory:
+ return
+ if _copilot_block_authoring_policy(ctx) != BlockAuthoringPolicy.CODE_ONLY_BROWSER:
+ return
+ declared_params = _declared_string_parameter_values(workflow_yaml)
+ for interaction in scout_trajectory:
+ if not isinstance(interaction, dict):
+ continue
+ correspondences = input_correspondences_for_interaction(interaction, declared_params) if declared_params else []
+ if correspondences:
+ interaction["input_correspondences"] = correspondences
+ else:
+ interaction.pop("input_correspondences", None)
+
+
async def _update_workflow(
params: dict[str, Any],
ctx: AgentContext,
@@ -9564,6 +9638,7 @@ async def _update_workflow(
ctx.block_observation_refs = normalize_block_observation_refs(params.get("block_observation_refs"))
ctx.raw_code_artifact_metadata = params.get("raw_code_artifact_metadata", params.get("code_artifact_metadata"))
# Imposition reconciles synthesized aliases/parameters before the persisted YAML contract is checked.
+ _enrich_scout_trajectory_input_correspondences(workflow_yaml, ctx)
imposition = _maybe_impose_synthesized_code_block(workflow_yaml, ctx)
# Consume the one-shot credential-scout reopen before the gate below so a fresh reject can re-arm it.
ctx.synthesized_block_reopened_for_credential_scout = False
diff --git a/tests/unit/test_copilot_code_block_persist_seam.py b/tests/unit/test_copilot_code_block_persist_seam.py
index 153dfcd3a..368b8050a 100644
--- a/tests/unit/test_copilot_code_block_persist_seam.py
+++ b/tests/unit/test_copilot_code_block_persist_seam.py
@@ -15981,3 +15981,119 @@ def test_producer_preserves_the_models_download_descriptor_key() -> None:
artifact = {"claimed_outcomes": [{"id": "claim", "goal_value_paths": ["output.downloaded_invoice_pdf"]}]}
assert workflow_update_module._download_return_shape_error("block", artifact, envelope.code) is None
assert {"output.statement_amount"} <= workflow_update_module._code_block_produced_output_paths(envelope.code)
+
+
+_WITNESS_SELECTOR = "a[href='/statements/100245_2026-05.pdf']"
+
+
+def _input_templated_provenance() -> dict[str, object]:
+ holes = workflow_update_module.input_correspondences_for_interaction(
+ {"tool_name": "click", "selector": _WITNESS_SELECTOR},
+ {"account_number": "100245", "billing_period": "May 2026"},
+ )
+ emitted = workflow_update_module.build_input_templated_locator(
+ surface="selector", selector=_WITNESS_SELECTOR, role="", name="", holes=holes
+ )
+ return {
+ "source": workflow_update_module.INPUT_TEMPLATED_PROVENANCE_SOURCE,
+ "surface": "selector",
+ "selector": _WITNESS_SELECTOR,
+ "emitted_literal": emitted,
+ "holes": [dict(hole) for hole in holes],
+ }
+
+
+def test_input_templated_provenance_admitted() -> None:
+ assert workflow_update_module._locator_provenance_is_self_validating(_input_templated_provenance())
+
+
+def test_input_templated_accessible_name_shape_admitted() -> None:
+ holes = workflow_update_module.input_correspondences_for_interaction(
+ {"tool_name": "click", "selector": "button", "accessible_name": "Download 100245", "role": "button"},
+ {"account_number": "100245"},
+ )
+ emitted = workflow_update_module.build_input_templated_locator(
+ surface="accessible_name", selector="", role="button", name="Download 100245", holes=holes
+ )
+ record = {
+ "source": workflow_update_module.INPUT_TEMPLATED_PROVENANCE_SOURCE,
+ "surface": "accessible_name",
+ "role": "button",
+ "name": "Download 100245",
+ "emitted_literal": emitted,
+ "holes": [dict(hole) for hole in holes],
+ }
+ assert workflow_update_module._locator_provenance_is_self_validating(record)
+
+
+def test_input_templated_provenance_rejects_tamper() -> None:
+ tampered_literal = _input_templated_provenance()
+ tampered_literal["emitted_literal"] = str(tampered_literal["emitted_literal"]).replace("account_number", "attacker")
+ assert not workflow_update_module._locator_provenance_is_self_validating(tampered_literal)
+
+ reordered = _input_templated_provenance()
+ reordered["holes"] = list(reversed(reordered["holes"])) # type: ignore[arg-type]
+ assert not workflow_update_module._locator_provenance_is_self_validating(reordered)
+
+ missing_holes = _input_templated_provenance()
+ missing_holes["holes"] = []
+ assert not workflow_update_module._locator_provenance_is_self_validating(missing_holes)
+
+
+def test_confluence_stamps_and_clears_input_correspondences() -> None:
+ ctx = _code_only_ctx()
+ ctx.scout_trajectory = [
+ {
+ "tool_name": "click",
+ "selector": _WITNESS_SELECTOR,
+ "source_url": "https://example.com/s",
+ "trajectory_index": 0,
+ }
+ ]
+ yaml_with_params = textwrap.dedent(
+ """
+ workflow_definition:
+ parameters:
+ - parameter_type: workflow
+ workflow_parameter_type: string
+ key: account_number
+ default_value: "100245"
+ - parameter_type: workflow
+ workflow_parameter_type: string
+ key: billing_period
+ default_value: "May 2026"
+ blocks: []
+ """
+ )
+ workflow_update_module._enrich_scout_trajectory_input_correspondences(yaml_with_params, ctx)
+ stamped = ctx.scout_trajectory[0].get("input_correspondences")
+ assert stamped is not None
+ assert {c["input_key"] for c in stamped} == {"account_number", "billing_period"}
+
+ yaml_without_params = "workflow_definition:\n parameters: []\n blocks: []\n"
+ workflow_update_module._enrich_scout_trajectory_input_correspondences(yaml_without_params, ctx)
+ assert "input_correspondences" not in ctx.scout_trajectory[0]
+
+
+def test_reconcile_scout_interaction_positional_map_skips_witness_rows() -> None:
+ scout_trajectory = [
+ {"tool_name": "type_text", "selector": "#account", "typed_length": 6},
+ {"tool_name": "type_text", "selector": "#period", "typed_length": 8},
+ ]
+ synthesized_parameters = [
+ {"key": "account_number", "default_value": "100245", "source": "locator_witness"},
+ {"key": "account_field"},
+ {"key": "period_field"},
+ ]
+ account = workflow_update_module._scout_interaction_for_synthesized_parameter(
+ synthesized_key="account_field",
+ scout_trajectory=scout_trajectory,
+ synthesized_parameters=synthesized_parameters,
+ )
+ period = workflow_update_module._scout_interaction_for_synthesized_parameter(
+ synthesized_key="period_field",
+ scout_trajectory=scout_trajectory,
+ synthesized_parameters=synthesized_parameters,
+ )
+ assert account is not None and account["selector"] == "#account"
+ assert period is not None and period["selector"] == "#period"
diff --git a/tests/unit/test_copilot_code_block_synthesis.py b/tests/unit/test_copilot_code_block_synthesis.py
index 8a3c2d156..71f0912a9 100644
--- a/tests/unit/test_copilot_code_block_synthesis.py
+++ b/tests/unit/test_copilot_code_block_synthesis.py
@@ -26,6 +26,8 @@ from skyvern.forge.sdk.copilot.code_block_synthesis import (
_READONLY_DEFERRED_VAR,
_SYNTHESIZED_BLOCK_LABEL,
CREDENTIAL_FILL_TOOL_NAME,
+ INPUT_TEMPLATED_PROVENANCE_SOURCE,
+ LOCATOR_WITNESS_PARAM_SOURCE,
SCOUTED_SPINE_DROPPED_UNFORGIVEN_REASON_CODE,
SCOUTED_SPINE_TRUNCATED_REASON_CODE,
TRUNCATED_FINDING,
@@ -35,8 +37,10 @@ from skyvern.forge.sdk.copilot.code_block_synthesis import (
SynthesisDiagnostics,
_get_by_role_expr,
_get_by_role_expr_strict,
+ build_input_templated_locator,
build_synthesized_artifact_metadata,
code_contains_credential_fill,
+ input_correspondences_for_interaction,
is_optional_dismissal_only_trajectory,
obligation_finding_reason_code,
produce_covered_static_return_envelope,
@@ -46,6 +50,7 @@ from skyvern.forge.sdk.copilot.code_block_synthesis import (
synthesize_code_block_with_extraction,
synthesize_extraction_suffix,
uncovered_required_emitted_interactions,
+ witness_prelude_lines,
)
from skyvern.forge.sdk.copilot.context import (
FillCarry,
@@ -3398,3 +3403,192 @@ class TestDownloadTerminalSequencing:
assert (
_with_trajectory_anchor(SimpleNamespace(scout_trajectory=[]), _download_target()).trajectory_anchor is None
) # type: ignore[arg-type]
+
+
+_STATEMENT_SELECTOR = "a[href='/statements/100245_2026-05.pdf']"
+_DECLARED = {"account_number": "100245", "billing_period": "May 2026"}
+
+
+def _witnessed_click(*, selector: str = _STATEMENT_SELECTOR, accessible_name: str = "Download May") -> dict[str, Any]:
+ interaction: dict[str, Any] = {
+ "tool_name": "click",
+ "selector": selector,
+ "accessible_name": accessible_name,
+ "role": "link",
+ "source_url": "https://example.com/statements",
+ }
+ correspondences = input_correspondences_for_interaction(interaction, _DECLARED)
+ if correspondences:
+ interaction["input_correspondences"] = correspondences
+ return interaction
+
+
+def test_input_correspondence_selector_identity_and_month() -> None:
+ correspondences = input_correspondences_for_interaction(
+ {"tool_name": "click", "selector": _STATEMENT_SELECTOR}, _DECLARED
+ )
+ by_key = {c["input_key"]: c for c in correspondences}
+ assert by_key["account_number"] == {
+ "input_key": "account_number",
+ "matched_literal": "100245",
+ "parameter_value": "100245",
+ "surface": "selector",
+ "transform": "identity",
+ "position": 20,
+ }
+ assert by_key["billing_period"]["matched_literal"] == "2026-05"
+ assert by_key["billing_period"]["parameter_value"] == "May 2026"
+ assert by_key["billing_period"]["transform"] == "month_name_to_iso"
+
+
+def test_templated_hole_uses_validated_span_not_earlier_substring() -> None:
+ # "Widget" also occurs as a non-boundary substring inside "Widgetry"; the hole must template the
+ # boundary-validated standalone span, not the first find() hit.
+ selector = 'a[aria-label="Widgetry Widget"]'
+ holes = input_correspondences_for_interaction({"tool_name": "click", "selector": selector}, {"gadget": "Widget"})
+ assert [h["position"] for h in holes] == [23]
+ expr = build_input_templated_locator(surface="selector", selector=selector, role="", name="", holes=holes)
+ assert expr is not None
+ assert "Widgetry {gadget}" in expr
+ assert "{gadget}ry" not in expr
+
+
+ "declared",
+ [
+ {"account_number": "24"},
+ {"account_number": "10 0245"},
+ {"account_number": "100245 "},
+ {"class": "100245"},
+ {"page": "100245"},
+ {"re": "100245"},
+ {"_scout_month_to_iso": "100245"},
+ {"account_number": "100245'] , [href"},
+ ],
+)
+def test_input_correspondence_rejects_unsafe_or_unnamed(declared: dict[str, str]) -> None:
+ assert (
+ input_correspondences_for_interaction({"tool_name": "click", "selector": _STATEMENT_SELECTOR}, declared) == []
+ )
+
+
+def test_input_correspondence_ignores_non_click() -> None:
+ assert (
+ input_correspondences_for_interaction({"tool_name": "type_text", "selector": _STATEMENT_SELECTOR}, _DECLARED)
+ == []
+ )
+
+
+def test_input_correspondence_requires_quoted_segment() -> None:
+ # `100245` appears only in an unquoted structural position, never inside a quoted attribute value.
+ assert (
+ input_correspondences_for_interaction(
+ {"tool_name": "click", "selector": "div.row-100245 > a"}, {"account_number": "100245"}
+ )
+ == []
+ )
+
+
+def test_input_correspondence_rejects_second_occurrence() -> None:
+ selector = "a[href='/x/100245'][data-id='100245']"
+ assert (
+ input_correspondences_for_interaction(
+ {"tool_name": "click", "selector": selector}, {"account_number": "100245"}
+ )
+ == []
+ )
+
+
+def test_synthesize_templated_selector_identical_across_modes() -> None:
+ trajectory = [_witnessed_click()]
+ non_strict = synthesize_code_block(list(trajectory), strict_selectors=False)
+ strict = synthesize_code_block(list(trajectory), strict_selectors=True)
+ assert non_strict is not None and strict is not None
+ templated = "page.locator(f\"a[href='/statements/{account_number}_{_scout_month_to_iso(billing_period)}.pdf']\")"
+ assert f"await {templated}.click()" in non_strict.code
+ assert f"await {templated}.click()" in strict.code
+
+
+def test_synthesize_mints_one_witness_row_per_key() -> None:
+ trajectory = [_witnessed_click(), _witnessed_click(selector=_STATEMENT_SELECTOR, accessible_name="View May")]
+ synthesized = synthesize_code_block(trajectory)
+ assert synthesized is not None
+ witness_rows = [p for p in synthesized.parameters if p.get("source") == LOCATOR_WITNESS_PARAM_SOURCE]
+ assert sorted((row["key"], row["default_value"]) for row in witness_rows) == [
+ ("account_number", "100245"),
+ ("billing_period", "May 2026"),
+ ]
+
+
+def test_synthesize_prelude_before_entry_and_preflight_clean() -> None:
+ synthesized = synthesize_code_block([_witnessed_click()])
+ assert synthesized is not None
+ code_lines = synthesized.code.splitlines()
+ guard_line = next(i for i, line in enumerate(code_lines) if "invalid value for grounded parameter" in line)
+ entry_line = next(i for i, line in enumerate(code_lines) if "_scout_entry_target =" in line)
+ assert guard_line < entry_line
+ diagnostics = preflight_code_block(synthesized.code, parameter_keys=["account_number", "billing_period"])
+ assert not any(diagnostic.code == "SANDBOX_UNRESOLVED_NAME" for diagnostic in diagnostics)
+
+
+def test_templated_locator_reads_declared_input_at_runtime() -> None:
+ plan_holes = input_correspondences_for_interaction(
+ {"tool_name": "click", "selector": _STATEMENT_SELECTOR}, _DECLARED
+ )
+ expr = build_input_templated_locator(
+ surface="selector", selector=_STATEMENT_SELECTOR, role="", name="", holes=plan_holes
+ )
+ assert expr is not None
+
+ class _Page:
+ def locator(self, value: str) -> str:
+ return value
+
+ source_lines = ["def _block(page, account_number, billing_period):"]
+ source_lines.extend(witness_prelude_lines(["account_number", "billing_period"], include_month_helper=True))
+ source_lines.append(f" return {expr}")
+ namespace: dict[str, Any] = {"Exception": Exception}
+ exec("\n".join(source_lines), namespace)
+ block = namespace["_block"]
+ assert block(_Page(), "100248", "June 2026") == "a[href='/statements/100248_2026-06.pdf']"
+ with pytest.raises(Exception):
+ block(_Page(), "100245'] , x[href='", "May 2026")
+ with pytest.raises(Exception):
+ block(_Page(), "100245", "Notamonth 2026")
+
+
+def test_build_input_templated_locator_recompute_and_tamper() -> None:
+ holes = input_correspondences_for_interaction({"tool_name": "click", "selector": _STATEMENT_SELECTOR}, _DECLARED)
+ expr = build_input_templated_locator(
+ surface="selector", selector=_STATEMENT_SELECTOR, role="", name="", holes=holes
+ )
+ recomputed = build_input_templated_locator(
+ surface="selector", selector=_STATEMENT_SELECTOR, role="", name="", holes=holes
+ )
+ assert expr == recomputed
+ reordered = build_input_templated_locator(
+ surface="selector", selector=_STATEMENT_SELECTOR, role="", name="", holes=list(reversed(holes))
+ )
+ assert reordered != expr
+
+
+def test_synthesize_unwitnessed_selector_byte_identical() -> None:
+ plain = {
+ "tool_name": "click",
+ "selector": _STATEMENT_SELECTOR,
+ "accessible_name": "Download",
+ "source_url": "https://example.com/s",
+ }
+ baseline = synthesize_code_block([dict(plain)])
+ assert baseline is not None
+ assert INPUT_TEMPLATED_PROVENANCE_SOURCE not in baseline.code
+ assert all(p.get("source") != LOCATOR_WITNESS_PARAM_SOURCE for p in baseline.parameters)
+ assert "_scout_month_to_iso" not in baseline.code
+
+
+def test_synthesize_input_purity() -> None:
+ trajectory = [_witnessed_click()]
+ snapshot = json.loads(json.dumps(trajectory))
+ synthesize_code_block(list(trajectory), strict_selectors=False)
+ synthesize_code_block(list(trajectory), strict_selectors=True)
+ assert trajectory == snapshot
diff --git a/tests/unit/test_copilot_tools_credential_id_misbinding.py b/tests/unit/test_copilot_tools_credential_id_misbinding.py
index be0a062c2..dddc3e1a5 100644
--- a/tests/unit/test_copilot_tools_credential_id_misbinding.py
+++ b/tests/unit/test_copilot_tools_credential_id_misbinding.py
@@ -393,6 +393,7 @@ def test_error_message_steers_delete_not_relocate() -> None:
def _ctx() -> MagicMock:
ctx = MagicMock(spec=AgentContext)
ctx.workflow_yaml = ""
+ ctx.scout_trajectory = []
ctx.last_workflow_yaml = None
ctx.workflow_id = "w_test"
ctx.workflow_permanent_id = "wpid_test"