Skip to content

Automate browser based workflows with AI

fix: resolve 4 CodeQL alerts in extract_form_fields.js (#5212)

pedrohsdb5fa0ff679524
diff --git a/skyvern/core/script_generations/extract_form_fields.js b/skyvern/core/script_generations/extract_form_fields.js
index edff14fad..9d8e75b99 100644
--- a/skyvern/core/script_generations/extract_form_fields.js
+++ b/skyvern/core/script_generations/extract_form_fields.js
@@ -22,13 +22,55 @@
}
const parentLabel = el.closest("label");
if (parentLabel) return parentLabel.textContent.trim();
- if (el.getAttribute("aria-label")) return el.getAttribute("aria-label");
+ const ariaLabel = el.getAttribute("aria-label");
+ // fieldset/legend — prefer over generic aria-labels like "Month", "Day", "Year"
+ // which don't tell the LLM WHICH date is being asked
+ const fieldset = el.closest("fieldset");
+ if (fieldset) {
+ const legend = fieldset.querySelector("legend");
+ if (legend) {
+ const legendText = legend.textContent.trim();
+ if (legendText && legendText.length > 3 && legendText.length < 300) {
+ // If aria-label exists but is short/generic, prepend it to the legend
+ // so the LLM knows both the question and the field role
+ if (ariaLabel && ariaLabel.length < 15) {
+ return ariaLabel + " — " + legendText;
+ }
+ return legendText;
+ }
+ }
+ }
+ if (ariaLabel) return ariaLabel;
const labelledBy = el.getAttribute("aria-labelledby");
if (labelledBy) {
const ref = document.getElementById(labelledBy);
if (ref) return ref.textContent.trim();
}
if (el.placeholder) return el.placeholder;
+ // Custom aria-checked inputs have sibling labels, not parent labels
+ if (el.hasAttribute && el.hasAttribute("aria-checked")) {
+ for (const sib of [el.previousElementSibling, el.nextElementSibling]) {
+ if (sib && sib.tagName === "LABEL") return sib.textContent.trim();
+ }
+ const parent = el.parentElement;
+ if (parent) {
+ const lbl = parent.querySelector("label");
+ if (lbl) return lbl.textContent.trim();
+ }
+ }
+ // Walk up to 4 ancestors checking for a preceding sibling with
+ // question/label text (common in multi-part form layouts)
+ let prevSib = el.parentElement;
+ for (let walk = 0; walk < 4 && prevSib; walk++) {
+ const prev = prevSib.previousElementSibling;
+ if (prev) {
+ const t = prev.textContent.trim();
+ if (t && t.length > 3 && t.length < 300) return t;
+ }
+ prevSib = prevSib.parentElement;
+ }
+ // Last resort: look at the element's title attribute
+ if (el.title) return el.title;
return null;
}
@@ -38,6 +80,12 @@
const vis = elType === "file" ? "" : ":visible";
if (el.name) return tag + '[name="' + el.name + '"]' + vis;
if (el.id) return "#" + el.id + vis;
+ // File inputs with no name/id: no name/id, use data-automation-id or type selector
+ if (elType === "file") {
+ const autoId = el.getAttribute("data-automation-id");
+ if (autoId) return tag + '[data-automation-id="' + autoId + '"]';
+ return 'input[type="file"]';
+ }
if (label && label.length < 80) {
const escapedLabel = label
.replace(/\\/g, "\\\\")
@@ -65,6 +113,67 @@
if (name && value)
return tag + '[name="' + name + '"][value="' + value + '"]';
if (name) return tag + '[name="' + name + '"]';
+ // Anonymous <input aria-checked> — find the associated label and
+ // build a selector. Structure varies: label may wrap input, be a sibling, or
+ // both may be inside a <div role="group">.
+ if (el.hasAttribute("aria-checked")) {
+ // 1. Label wraps input: <label>Yes<input></label>
+ const parentLabel = el.closest("label");
+ if (parentLabel) {
+ const labelText = parentLabel.textContent.trim();
+ if (labelText && labelText.length < 50) {
+ return (
+ "label:has-text('" +
+ labelText.replace(/\\/g, "\\\\").replace(/'/g, "\\'") +
+ "') input"
+ );
+ }
+ }
+ // 2. Label is a sibling (before or after): <label>Yes</label><input>
+ // Click the LABEL (visible) instead of the hidden input — the UI
+ // responds to label clicks, not hidden input clicks
+ for (const sibling of [
+ el.previousElementSibling,
+ el.nextElementSibling,
+ ]) {
+ if (sibling && sibling.tagName === "LABEL") {
+ const labelText = sibling.textContent.trim();
+ if (labelText && labelText.length < 50) {
+ return (
+ "label:has-text('" +
+ labelText.replace(/\\/g, "\\\\").replace(/'/g, "\\'") +
+ "')"
+ );
+ }
+ }
+ }
+ // 3. Label is inside the same container: <div role="group"><label>Yes</label>...<input></div>
+ const container = el.parentElement;
+ if (container) {
+ const labels = container.querySelectorAll("label");
+ const inputIndex = Array.from(container.children).indexOf(el);
+ let bestLabel = null;
+ let bestDist = Infinity;
+ for (const lbl of labels) {
+ const lblIndex = Array.from(container.children).indexOf(lbl);
+ const dist = Math.abs(lblIndex - inputIndex);
+ if (dist < bestDist) {
+ bestDist = dist;
+ bestLabel = lbl;
+ }
+ }
+ if (bestLabel) {
+ const labelText = bestLabel.textContent.trim();
+ if (labelText && labelText.length < 50) {
+ return (
+ "label:has-text('" +
+ labelText.replace(/\\/g, "\\\\").replace(/'/g, "\\'") +
+ "')"
+ );
+ }
+ }
+ }
+ }
return null;
}
@@ -146,12 +255,30 @@
const type = (el.getAttribute("type") || "").toLowerCase();
if (["hidden", "submit", "button", "image", "reset"].includes(type))
continue;
- if (type !== "file" && !isVisible(el)) continue;
+ // Skip inputs inside multiselect containers — platform extension handles those
+ if (
+ el.closest('[data-uxi-widget-type="multiselect"]') ||
+ el.closest('[role="combobox"][aria-autocomplete="list"]')
+ )
+ continue;
+ // Allow aria-checked inputs through even if visually hidden (hides
+ // real radio/checkbox inputs behind styled overlays at opacity:0)
+ const hasAriaChecked = el.hasAttribute("aria-checked");
+ if (type !== "file" && !hasAriaChecked && !isVisible(el)) continue;
- if (type === "checkbox" || type === "radio") {
+ // Custom <input aria-checked> without type="radio" for custom radios.
+ // Detect these by the presence of aria-checked attribute.
+ const effectiveType =
+ type === "checkbox" || type === "radio"
+ ? type
+ : el.hasAttribute("aria-checked")
+ ? "radio"
+ : type;
+
+ if (effectiveType === "checkbox" || effectiveType === "radio") {
if (el.name) {
if (!checkRadioGroups[el.name]) {
- checkRadioGroups[el.name] = { type: type, elements: [] };
+ checkRadioGroups[el.name] = { type: effectiveType, elements: [] };
}
checkRadioGroups[el.name].elements.push(el);
} else {
@@ -167,29 +294,36 @@
if (!container._groupKey) {
container._groupKey =
"__nameless_" +
- type +
+ effectiveType +
"_" +
Math.random().toString(36).slice(2, 8);
}
const gk = container._groupKey;
if (!checkRadioGroups[gk]) {
- checkRadioGroups[gk] = { type: type, elements: [] };
+ checkRadioGroups[gk] = { type: effectiveType, elements: [] };
}
if (!checkRadioGroups[gk].elements.includes(el)) {
checkRadioGroups[gk].elements.push(el);
}
} else {
+ // Standalone checkbox/radio with no siblings — this is a toggle
+ // (e.g., "I have a preferred name", "SMS opt-in") that reveals or
+ // enables a section. Present as "toggle" so the LLM knows to leave
+ // it unchecked unless data explicitly requires it.
const label = getLabel(el);
const selector = buildSelector(el, label);
if (selector) {
+ const isChecked =
+ el.getAttribute("aria-checked") === "true" || el.checked;
fields.push({
label: label || null,
selector: selector,
tag: "input",
- type: type,
+ type: "toggle",
name: null,
required: el.required || false,
placeholder: null,
+ currentValue: isChecked ? "checked" : "unchecked",
});
}
}
@@ -209,6 +343,53 @@
const selector = buildSelector(el, label);
if (!selector) continue;
+ // Collect format hints for phone/date fields — validation messages,
+ // pattern attributes, and aria-describedby text that tell the LLM
+ // what format the field expects (e.g., "(xxx) xxx-xxxx").
+ let formatHint = null;
+ const autoId = el.getAttribute("data-automation-id") || "";
+ const elName = (el.name || "").toLowerCase();
+ const elLabel = (label || "").toLowerCase();
+ const isPhoneOrDate =
+ elName.includes("phone") ||
+ elLabel.includes("phone") ||
+ autoId.includes("phone") ||
+ elName.includes("date") ||
+ elLabel.includes("date") ||
+ autoId.includes("date");
+ if (isPhoneOrDate || el.pattern) {
+ const hints = [];
+ if (el.pattern) hints.push("pattern: " + el.pattern);
+ if (el.title) hints.push(el.title);
+ // aria-describedby often links to a format description element
+ const describedBy = el.getAttribute("aria-describedby");
+ if (describedBy) {
+ for (const refId of describedBy.split(/\s+/)) {
+ const ref = document.getElementById(refId);
+ if (ref) {
+ const t = ref.textContent.trim();
+ if (t && t.length < 200) hints.push(t);
+ }
+ }
+ }
+ // Check closest form-group wrapper for format/help text
+ const wrapper =
+ el.closest(".form-group") ||
+ el.closest('[role="group"]') ||
+ el.closest("fieldset");
+ if (wrapper) {
+ // Look for elements that contain format hints (e.g., "(xxx) xxx-xxxx")
+ const hintEl = wrapper.querySelector(
+ '.help-text, .hint, [class*="hint"], [class*="help"]',
+ );
+ if (hintEl) {
+ const t = hintEl.textContent.trim();
+ if (t && t.length < 200) hints.push(t);
+ }
+ }
+ if (hints.length > 0) formatHint = hints.join(" | ");
+ }
+
fields.push({
label: label || null,
selector: selector,
@@ -223,6 +404,7 @@
name: el.name || null,
required: el.required || false,
placeholder: el.placeholder || null,
+ formatHint: formatHint,
});
if (el.tagName.toLowerCase() === "select") {
@@ -255,7 +437,54 @@
const groupLabel = getGroupLabel(els);
const firstSelector =
buildOptionSelector(els[0]) || buildSelector(els[0], getLabel(els[0]));
- if (!firstSelector) continue;
+ if (!firstSelector) {
+ // Fallback for aria-checked groups: use nth-of-type selectors
+ if (
+ els[0].hasAttribute &&
+ els[0].hasAttribute("aria-checked") &&
+ els.length >= 2
+ ) {
+ const fallbackOptions = [];
+ for (let oi = 0; oi < els.length; oi++) {
+ const optEl = els[oi];
+ const optLabel =
+ getLabel(optEl) || optEl.value || "Option " + (oi + 1);
+ // Build selector by walking up to the label
+ const parentLabel = optEl.closest("label");
+ let optSelector = null;
+ if (parentLabel) {
+ const lt = parentLabel.textContent.trim();
+ if (lt && lt.length < 50) {
+ optSelector =
+ "label:has-text('" +
+ lt.replace(/\\/g, "\\\\").replace(/'/g, "\\'") +
+ "')";
+ }
+ }
+ if (!optSelector && optEl.id) optSelector = "#" + optEl.id;
+ if (optSelector) {
+ fallbackOptions.push({
+ label: optLabel,
+ value: optLabel,
+ selector: optSelector,
+ });
+ }
+ }
+ if (fallbackOptions.length >= 2) {
+ fields.push({
+ label: groupLabel || null,
+ selector: fallbackOptions[0].selector,
+ tag: "input",
+ type: "radio_group",
+ name: groupKey,
+ required: false,
+ placeholder: null,
+ options: fallbackOptions,
+ });
+ }
+ }
+ continue;
+ }
const options = [];
for (const el of els) {
@@ -281,5 +510,151 @@
options: options,
});
}
+ // Pass 3: Detect custom ARIA role-based components
+ // These are <div role="radio">, <div role="checkbox">, <div role="listbox"> etc.
+ // that standard input scanning misses.
+
+ // 3a: Custom radio groups via [role="radiogroup"] or grouped [role="radio"]
+ const ariaRadioGroups = document.querySelectorAll('[role="radiogroup"]');
+ for (const group of ariaRadioGroups) {
+ const radios = group.querySelectorAll('[role="radio"]');
+ if (radios.length === 0) continue;
+ const groupId =
+ group.getAttribute("data-automation-id") ||
+ group.id ||
+ Math.random().toString(36).slice(2, 8);
+ if (seen.has("aria_rg_" + groupId)) continue;
+ seen.add("aria_rg_" + groupId);
+
+ const groupLabel = getGroupLabel(Array.from(radios));
+ const options = [];
+ for (const r of radios) {
+ const optLabel =
+ r.getAttribute("aria-label") || r.textContent.trim() || null;
+ const optSelector = r.getAttribute("data-automation-id")
+ ? '[data-automation-id="' + r.getAttribute("data-automation-id") + '"]'
+ : r.id
+ ? "#" + r.id
+ : null;
+ if (optSelector) {
+ options.push({
+ label: optLabel,
+ value: optLabel,
+ selector: optSelector,
+ });
+ }
+ }
+ if (options.length > 0) {
+ fields.push({
+ label: groupLabel || null,
+ selector: options[0].selector,
+ tag: "div",
+ type: "radio_group",
+ name: groupId,
+ required: group.getAttribute("aria-required") === "true",
+ placeholder: null,
+ options: options,
+ });
+ }
+ }
+
+ // 3b: Ungrouped [role="radio"] elements (not inside a radiogroup)
+ const orphanRadios = document.querySelectorAll(
+ '[role="radio"]:not([role="radiogroup"] [role="radio"])',
+ );
+ if (orphanRadios.length > 0) {
+ // Group orphan radios by their nearest common ancestor
+ const orphanGroups = {};
+ for (const r of orphanRadios) {
+ if (!isVisible(r)) continue;
+ // Walk up to find a grouping container
+ let container = r.parentElement;
+ for (let i = 0; i < 5 && container; i++) {
+ const siblings = container.querySelectorAll('[role="radio"]');
+ if (siblings.length >= 2) break;
+ container = container.parentElement;
+ }
+ const key = container
+ ? container.getAttribute("data-automation-id") ||
+ container.id ||
+ "orphan_" + Math.random().toString(36).slice(2, 6)
+ : "orphan_default";
+ if (!orphanGroups[key])
+ orphanGroups[key] = { container: container, elements: [] };
+ if (!orphanGroups[key].elements.includes(r))
+ orphanGroups[key].elements.push(r);
+ }
+ for (const [key, group] of Object.entries(orphanGroups)) {
+ if (seen.has("aria_or_" + key)) continue;
+ seen.add("aria_or_" + key);
+ const groupLabel = getGroupLabel(group.elements);
+ const options = [];
+ for (const r of group.elements) {
+ const optLabel =
+ r.getAttribute("aria-label") || r.textContent.trim() || null;
+ const optSelector = r.getAttribute("data-automation-id")
+ ? '[data-automation-id="' +
+ r.getAttribute("data-automation-id") +
+ '"]'
+ : r.id
+ ? "#" + r.id
+ : null;
+ if (optSelector) {
+ options.push({
+ label: optLabel,
+ value: optLabel,
+ selector: optSelector,
+ });
+ }
+ }
+ if (options.length > 0) {
+ fields.push({
+ label: groupLabel || null,
+ selector: options[0].selector,
+ tag: "div",
+ type: "radio_group",
+ name: key,
+ required: false,
+ placeholder: null,
+ options: options,
+ });
+ }
+ }
+ }
+
+ // 3c: Custom [role="checkbox"] elements (not <input type="checkbox">)
+ const ariaCheckboxes = document.querySelectorAll(
+ '[role="checkbox"]:not(input)',
+ );
+ for (const cb of ariaCheckboxes) {
+ if (!isVisible(cb)) continue;
+ const cbId = cb.getAttribute("data-automation-id") || cb.id || null;
+ if (!cbId || seen.has("aria_cb_" + cbId)) continue;
+ seen.add("aria_cb_" + cbId);
+ const label =
+ cb.getAttribute("aria-label") ||
+ getLabel(cb) ||
+ cb.textContent.trim() ||
+ null;
+ const selector = cbId
+ ? '[data-automation-id="' + cbId + '"]'
+ : cb.id
+ ? "#" + cb.id
+ : null;
+ if (selector) {
+ fields.push({
+ label: label,
+ selector: selector,
+ tag: "div",
+ type: "checkbox",
+ name: cbId,
+ required: cb.getAttribute("aria-required") === "true",
+ placeholder: null,
+ });
+ }
+ }
+
+ // PLATFORM_EXTENSION_POINT
+
return fields;
};
diff --git a/skyvern/core/script_generations/fuzzy_matcher.py b/skyvern/core/script_generations/fuzzy_matcher.py
new file mode 100644
index 000000000..d4754ebd2
--- /dev/null
+++ b/skyvern/core/script_generations/fuzzy_matcher.py
@@ -0,0 +1,99 @@
+"""Fuzzy matching for form option labels.
+
+Consolidates the duplicated option-matching logic used throughout the
+form-filling pipeline into a single, configurable implementation.
+"""
+
+from __future__ import annotations
+
+import re
+
+import structlog
+
+LOG = structlog.get_logger()
+
+_WORD_RE = re.compile(r"\w+")
+
+
+_NORMALIZE_RE = re.compile(r"[''`]")
+
+
+def _normalize(text: str) -> str:
+ """Normalize text for matching: lowercase, strip apostrophes/quotes."""
+ return _NORMALIZE_RE.sub("", text.lower().strip())
+
+
+def match_option(candidate: str, options: list[str], *, min_substring_len: int = 3) -> int | None:
+ """Find the best matching option index for a candidate value.
+
+ Uses a 4-pass strategy:
+ 1. Exact match (case-insensitive, apostrophe-normalized)
+ 2. Substring containment (candidate in option or option in candidate)
+ 3. Stem match (e.g., "bachelors" matches "bachelor's degree")
+ 4. Word overlap scoring (Jaccard-like, threshold >= 50%)
+
+ Args:
+ candidate: The value to match (e.g., "Bachelor of Science").
+ options: List of option labels to match against.
+ min_substring_len: Minimum length for substring matches to avoid
+ false positives on very short strings.
+
+ Returns:
+ Index of the best matching option, or None if no match found.
+ """
+ if not candidate or not options:
+ return None
+
+ candidate_norm = _normalize(candidate)
+
+ # Pass 1: exact match (normalized)
+ for i, opt in enumerate(options):
+ if _normalize(opt) == candidate_norm:
+ return i
+
+ # Pass 2: substring containment (normalized, both directions)
+ best_sub_idx: int | None = None
+ best_sub_len = 0
+ for i, opt in enumerate(options):
+ opt_norm = _normalize(opt)
+ if len(candidate_norm) >= min_substring_len and candidate_norm in opt_norm:
+ if len(candidate_norm) > best_sub_len:
+ best_sub_len = len(candidate_norm)
+ best_sub_idx = i
+ elif len(opt_norm) >= min_substring_len and opt_norm in candidate_norm:
+ if len(opt_norm) > best_sub_len:
+ best_sub_len = len(opt_norm)
+ best_sub_idx = i
+ if best_sub_idx is not None:
+ return best_sub_idx
+
+ # Pass 3: stem match — strip trailing 's' and compare
+ # Catches: "bachelors" ↔ "bachelor's", "masters" ↔ "master's"
+ candidate_stem = candidate_norm.rstrip("s")
+ if len(candidate_stem) >= min_substring_len:
+ for i, opt in enumerate(options):
+ opt_stem = _normalize(opt).rstrip("s")
+ if candidate_stem in opt_stem or opt_stem in candidate_stem:
+ return i
+
+ # Pass 4: word overlap scoring
+ candidate_words = set(_WORD_RE.findall(candidate_norm))
+ if not candidate_words:
+ return None
+
+ best_overlap_idx: int | None = None
+ best_overlap_score = 0.0
+ for i, opt in enumerate(options):
+ opt_words = set(_WORD_RE.findall(_normalize(opt)))
+ if not opt_words:
+ continue
+ overlap = len(candidate_words & opt_words)
+ score = overlap / max(len(candidate_words), len(opt_words))
+ if score > best_overlap_score:
+ best_overlap_score = score
+ best_overlap_idx = i
+
+ if best_overlap_score >= 0.5 and best_overlap_idx is not None:
+ return best_overlap_idx
+
+ return None
diff --git a/skyvern/core/script_generations/generate_script.py b/skyvern/core/script_generations/generate_script.py
index f70275f49..2cfa53861 100644
--- a/skyvern/core/script_generations/generate_script.py
+++ b/skyvern/core/script_generations/generate_script.py
@@ -1065,13 +1065,32 @@ def _build_form_filling_block_fn(
return decorated
-def _detect_block_ats_platform(block: dict[str, Any]) -> str | None:
- """Check if a block's URL belongs to a known ATS platform.
+def _detect_block_ats_platform(block: dict[str, Any], all_blocks: list[dict[str, Any]] | None = None) -> str | None:
+ """Check if a block belongs to a known platform with optimized scripts.
+
+ Checks the block's own URL first. If the block has no URL (common for
+ continuation blocks that share the previous block's page), checks all
+ other blocks in the workflow for a URL match.
Delegates to app.AGENT_FUNCTION which is overridden in cloud builds.
- Returns None in OSS (no ATS detection).
+ Returns None in OSS (no detection).
"""
- return app.AGENT_FUNCTION.detect_ats_platform(block.get("url", ""))
+ # Check block URL first
+ result = app.AGENT_FUNCTION.detect_ats_platform(block.get("url") or "")
+ if result:
+ return result
+
+ # Fall back: check any sibling block's URL (all blocks in the same
+ # workflow share the same site context)
+ if all_blocks:
+ for sibling in all_blocks:
+ sibling_url = sibling.get("url") or ""
+ if sibling_url:
+ result = app.AGENT_FUNCTION.detect_ats_platform(sibling_url)
+ if result:
+ return result
+
+ return None
def _build_block_fn(
@@ -1080,10 +1099,11 @@ def _build_block_fn(
value_to_param: dict[str, str] | None = None,
use_semantic_selectors: bool = False,
is_in_for_loop: bool = False,
+ all_blocks: list[dict[str, Any]] | None = None,
) -> FunctionDef:
# Check for platform-specific pipeline (cloud-only; returns None in OSS)
if use_semantic_selectors:
- ats_platform = _detect_block_ats_platform(block)
+ ats_platform = _detect_block_ats_platform(block, all_blocks=all_blocks)
if ats_platform:
pipeline_fn = app.AGENT_FUNCTION.build_ats_pipeline_block_fn(block, ats_platform)
if pipeline_fn:
@@ -2746,6 +2766,7 @@ async def generate_workflow_script_python_code(
block_actions,
value_to_param=value_to_param,
use_semantic_selectors=use_semantic_selectors,
+ all_blocks=task_v1_blocks,
)
temp_module = cst.Module(body=[block_fn_def])
block_code = temp_module.code
diff --git a/skyvern/core/script_generations/skyvern_page.py b/skyvern/core/script_generations/skyvern_page.py
index 314ee5e7c..b58ed9cbb 100644
--- a/skyvern/core/script_generations/skyvern_page.py
+++ b/skyvern/core/script_generations/skyvern_page.py
@@ -2,8 +2,11 @@ from __future__ import annotations
import asyncio
import copy
+import datetime
import json as _json
+import os
import re
+import time
import uuid
from dataclasses import dataclass
from pathlib import Path
@@ -13,6 +16,7 @@ import structlog
from playwright.async_api import Locator, Page
from skyvern.config import settings
+from skyvern.core.script_generations.fuzzy_matcher import match_option as _match_option
from skyvern.core.script_generations.skyvern_page_ai import SkyvernPageAi
from skyvern.exceptions import ScriptTerminationException
from skyvern.forge import app
@@ -33,6 +37,7 @@ _EXTRACT_FORM_FIELDS_JS: str | None = None
def _get_extract_form_fields_js() -> str:
+ """Load the base form field extraction JS (cached after first read)."""
global _EXTRACT_FORM_FIELDS_JS
if _EXTRACT_FORM_FIELDS_JS is None:
js_path = Path(__file__).parent / "extract_form_fields.js"
@@ -512,7 +517,7 @@ class SkyvernPage(Page):
) -> str:
"""Fill an autocomplete input by typing a value and clicking the matching dropdown option.
- Handles widgets like Google Places, Lever location fields, and other
+ Handles widgets like Google Places, autocomplete location fields, and other
autocomplete inputs where typing triggers a dropdown and the user must
select an option for the value to persist.
@@ -653,7 +658,7 @@ class SkyvernPage(Page):
"[data-option-id]:visible",
"ul.autocomplete-results li:visible",
'.dropdown-menu li:visible, .dropdown-menu [role="option"]:visible',
- ".autocomplete-dropdown-container div:visible", # Lever location
+ ".autocomplete-dropdown-container div:visible", # autocomplete location
'[class*="suggestion"]:visible',
'[class*="option"]:visible:not(select option)',
]
@@ -735,9 +740,6 @@ class SkyvernPage(Page):
selector=selector,
value=value,
)
- # Small delay for the value to commit
- await asyncio.sleep(0.3)
- return value
else:
# No close text match — click the first option as best guess
first = option_locators[0]
@@ -747,8 +749,10 @@ class SkyvernPage(Page):
selector=selector,
value=value,
)
- await asyncio.sleep(0.3)
- return value
+
+ # Wait for the selection to register in the UI
+ await asyncio.sleep(0.5)
+ return value
async def _find_autocomplete_options(
self,
@@ -1302,21 +1306,24 @@ class SkyvernPage(Page):
async def extract_form_fields(self) -> list[dict[str, Any]]:
"""Scan the page for visible form fields using DOM inspection (no LLM).
- Two-pass approach:
- - Pass 1: Process non-checkbox/non-radio elements (text, email, select, textarea, etc.)
- - Pass 2: Group checkbox/radio inputs by their ``name`` attribute into
- ``checkbox_group`` / ``radio_group`` entries with an ``options`` list.
-
- Returns a list of field descriptors. Regular fields:
- [{"label": "Full name", "selector": "label:has-text('Full name') input",
- "tag": "input", "type": "text", "name": "full_name", "required": True}, ...]
+ The base scanner handles standard HTML form elements (input, select,
+ textarea) and ARIA role-based groups. Platform-specific passes
+ (e.g., custom listbox buttons, multiselect widgets) are injected
+ at runtime via ``AgentFunction.get_form_field_extraction_js()``.
- Group fields:
- [{"label": "Areas of focus", "selector": "input[name='field0']",
- "tag": "input", "type": "checkbox_group", "name": "field0", "required": False,
- "options": [{"label": "Engineering", "value": "Engineering", "selector": "..."}]}]
+ Returns a list of field descriptors.
"""
- return await self.page.evaluate(_get_extract_form_fields_js())
+ base_js = _get_extract_form_fields_js()
+
+ ext_js = app.AGENT_FUNCTION.get_form_field_extraction_js(url=self.page.url)
+ if ext_js:
+ marker = "// PLATFORM_EXTENSION_POINT"
+ if marker not in base_js:
+ LOG.warning("extract_form_fields: extension point marker missing from base JS")
+ else:
+ base_js = base_js.replace(marker, ext_js)
+
+ return await self.page.evaluate(base_js)
async def dynamic_field_map(
self,
@@ -1348,21 +1355,25 @@ class SkyvernPage(Page):
options: list[str] | None = None
if field.get("options"):
options = [o.get("label") or o.get("value", "") for o in field["options"]]
- field_descs.append(
- {
- "label": label,
- "type": field_type,
- "required": field.get("required", False),
- "placeholder": field.get("placeholder"),
- "options": options,
- }
- )
+ desc: dict[str, Any] = {
+ "label": label,
+ "type": field_type,
+ "required": field.get("required", False),
+ "placeholder": field.get("placeholder"),
+ "options": options,
+ }
+ if field.get("currentValue"):
+ desc["currentValue"] = field["currentValue"]
+ if field.get("formatHint"):
+ desc["formatHint"] = field["formatHint"]
+ field_descs.append(desc)
prompt_text = prompt_engine.load_prompt(
template="form-field-mapper",
form_fields=field_descs,
data=data,
prompt=prompt,
+ platform_hints=app.AGENT_FUNCTION.get_form_field_mapper_hints(),
)
try:
@@ -1394,7 +1405,17 @@ class SkyvernPage(Page):
result[idx] = v
except (ValueError, TypeError):
LOG.warning("dynamic_field_map: non-numeric key in LLM response", key=k)
- LOG.info("dynamic_field_map: mapped fields", mapped=len(result), total=len(form_fields))
+ mapped_labels = [(form_fields[i].get("label") or form_fields[i].get("name") or "?")[:40] for i in result]
+ unmapped_labels = [
+ (f.get("label") or f.get("name") or "?")[:40] for idx, f in enumerate(form_fields) if idx not in result
+ ]
+ LOG.info(
+ "dynamic_field_map: mapped fields",
+ mapped=len(result),
+ total=len(form_fields),
+ mapped_labels=mapped_labels,
+ unmapped_labels=unmapped_labels,
+ )
return result
except Exception:
@@ -1440,6 +1461,15 @@ class SkyvernPage(Page):
try:
if field_type in ("radio_group", "checkbox_group"):
+ LOG.info(
+ "fill_from_mapping: processing group field",
+ field_label=label[:50],
+ field_type=field_type,
+ field_index=idx,
+ value=str(value)[:50],
+ options_count=len(field.get("options", [])),
+ option_labels=[o.get("label", "?")[:30] for o in field.get("options", [])],
+ )
if isinstance(value, str):
try:
parsed = _json.loads(value)
@@ -1456,21 +1486,15 @@ class SkyvernPage(Page):
selected = [str(value).lower().strip()]
options = field.get("options", [])
- opt_labels = [(o.get("label") or o.get("value", "")).lower().strip() for o in options]
+ opt_labels = [(o.get("label") or o.get("value", "")).strip() for o in options]
matched_any = False
for sel_label in selected:
- for oi, ol in enumerate(opt_labels):
- # Exact match, or substring match with min length 3 to avoid
- # false positives (e.g., "No" matching "None of the above")
- if (
- sel_label == ol
- or (len(sel_label) >= 3 and sel_label in ol)
- or (len(ol) >= 3 and ol in sel_label)
- ):
- await self.click(selector=options[oi]["selector"], ai=None)
- matched_any = True
- break
+ match_idx = _match_option(sel_label, opt_labels)
+ if match_idx is not None:
+ await self.click(selector=options[match_idx]["selector"], ai=None)
+ matched_any = True
+ break
if not matched_any:
# No option text-matched — use AI fallback (Code 2.0 style)
@@ -1519,6 +1543,11 @@ class SkyvernPage(Page):
if value and str(value).lower() not in ("false", "no", "0", "skip"):
await self.click(selector=selector, ai=None)
+ elif field_type == "toggle":
+ # Standalone toggles — only click if LLM explicitly said true
+ if value is True or str(value).lower() in ("true", "yes", "1"):
+ await self.click(selector=selector, ai=None)
+
elif field_type == "file":
await self.upload_file(
selector=selector,
@@ -1527,6 +1556,36 @@ class SkyvernPage(Page):
prompt=f"Upload file for {label}",
)
+ elif field_type in ("multiselect", "listbox") or (field.get("placeholder") or "").lower() == "search":
+ # Custom widgets (e.g., multiselect chip-pickers, listbox
+ # dropdowns). Dispatch to platform-specific filler via
+ # AgentFunction; fall back to element_fallback if no
+ # platform handler is registered or the handler fails.
+ LOG.info(
+ "fill_from_mapping: custom widget detected",
+ field_label=label,
+ widget_type=field_type,
+ value=str(value)[:50],
+ )
+ if _budget_available():
+ filled = await app.AGENT_FUNCTION.fill_custom_widget(
+ self.page,
+ field,
+ value,
+ label,
+ )
+ # None means "not handled" — use element_fallback
+ if filled is None or filled is False:
+ if _budget_available():
+ self._track_ai_call()
+ await self.element_fallback(
+ navigation_goal=(
+ f"For the '{label}' field, select or type '{str(value)[:30]}' "
+ f"and pick the best match. Do NOT click Save and Continue."
+ ),
+ max_steps=3,
+ )
+
else:
await self.fill(selector=selector, value=str(value), ai=None)
@@ -1563,7 +1622,18 @@ class SkyvernPage(Page):
# This catches those cases by scanning for file fields that weren't in the mapping
# and trying to match them against URL-like parameter values.
if data:
+ # Collect all URL params — including nested ones in user_data JSON
url_params = {k: v for k, v in data.items() if isinstance(v, str) and v.startswith("http")}
+ # Parse user_data if it's a JSON string (resume_url is often nested inside it)
+ user_data_str = data.get("user_data", "")
+ if isinstance(user_data_str, str) and user_data_str.startswith("{"):
+ try:
+ user_data_parsed = _json.loads(user_data_str)
+ for k, v in user_data_parsed.items():
+ if isinstance(v, str) and v.startswith("http") and k not in url_params:
+ url_params[k] = v
+ except Exception:
+ pass
file_fields = [(i, f) for i, f in enumerate(form_fields) if f.get("type") == "file"]
unmapped_files = [(i, f) for i, f in file_fields if i not in mapping]
LOG.info(
@@ -1574,7 +1644,8 @@ class SkyvernPage(Page):
unmapped_file_count=len(unmapped_files),
unmapped_file_labels=[(f.get("label") or f.get("name") or "?")[:50] for _, f in unmapped_files],
)
- if url_params:
+ if url_params and unmapped_files:
+ uploaded = False
for idx, field in enumerate(form_fields):
if field.get("type") != "file" or idx in mapping:
continue
@@ -1591,6 +1662,17 @@ class SkyvernPage(Page):
or (len(pk) >= 3 and pk in field_name) # "resume" in "resume-upload"
or (len(field_name) >= 3 and field_name in pk) # "doc" in "resume_doc"
or (field_label and len(pk) >= 3 and pk in field_label)
+ # Generic file upload fallback — match resume/cv params
+ # only when the field label is also generic or matches
+ or (
+ ("resume" in pk or "cv" in pk)
+ and (
+ not field_label
+ or "resume" in field_label
+ or "cv" in field_label
+ or "upload" in field_label
+ )
+ )
):
LOG.info(
"fill_from_mapping: matched URL param to file field",
@@ -1601,8 +1683,10 @@ class SkyvernPage(Page):
await self.upload_file(
selector=selector,
files=param_url,
- ai=None,
+ ai="fallback",
+ prompt=f"Upload resume file to the '{field_label or 'file upload'}' field",
)
+ uploaded = True
except Exception:
LOG.warning(
"fill_from_mapping: file upload failed",
@@ -1611,6 +1695,8 @@ class SkyvernPage(Page):
exc_info=True,
)
break
+ if uploaded:
+ break
async def validate_mapping(
self,
@@ -1738,6 +1824,224 @@ class SkyvernPage(Page):
await self.fill_from_mapping(form_fields, mapping, data=data)
+ async def _dump_html(self, debug_dir: str | None, label: str) -> None:
+ """Dump current page HTML to a timestamped file for debugging."""
+ if not debug_dir:
+ return
+ try:
+ ts = datetime.datetime.now().strftime("%H%M%S_%f")[:-3]
+ filename = f"{ts}_{label}.html"
+ filepath = os.path.join(debug_dir, filename)
+ html = await self.page.content()
+ with open(filepath, "w", encoding="utf-8") as f:
+ f.write(html)
+ LOG.info("_dump_html: saved", path=filepath, size=len(html))
+ except Exception:
+ LOG.warning("_dump_html: failed", exc_info=True)
+
+ async def fill_multipage_form(
+ self,
+ data: dict[str, Any],
+ *,
+ prompt: str = "Fill out the form",
+ next_button: str = 'button:has-text("Save and Continue"), button:has-text("Next"), button:has-text("Continue")',
+ max_pages: int = 10,
+ timeout_seconds: float = 300,
+ debug_dir: str | None = None,
+ ) -> int:
+ """Fill a multi-page form by looping: fill current page → click next → repeat.
+
+ Returns the number of pages filled. Stops when:
+ - No fillable form fields are found on the current page (e.g., Review page)
+ - The next button is not found (last page)
+ - max_pages is reached
+ - Wall-clock timeout is exceeded
+
+ Args:
+ data: Dict of data keys/values to fill into the form.
+ prompt: User instructions for how to fill the form.
+ next_button: CSS selector(s) for the next/continue button.
+ max_pages: Safety limit on number of pages to fill.
+ timeout_seconds: Wall-clock timeout for the entire multi-page fill (default 5 min).
+ """
+ start_time = time.monotonic()
+ pages_filled = 0
+ prev_field_signature: str | None = None
+
+ for page_num in range(max_pages):
+ elapsed = time.monotonic() - start_time
+ if elapsed > timeout_seconds:
+ LOG.warning(
+ "fill_multipage_form: timeout exceeded, stopping",
+ page_num=page_num,
+ elapsed_s=round(elapsed, 1),
+ timeout_s=timeout_seconds,
+ )
+ break
+
+ # Small wait on page 1+ to let React DOM settle after transition
+ if page_num > 0:
+ await asyncio.sleep(1)
+
+ form_fields = await self.extract_form_fields()
+
+ # Filter to fillable fields — includes standard inputs AND custom widgets
+ fillable = [
+ f
+ for f in form_fields
+ if (f.get("tag") in ("input", "select", "textarea") and f.get("type") != "hidden")
+ or f.get("type") in ("listbox", "multiselect", "toggle")
+ ]
+
+ if not fillable:
+ await self._dump_html(debug_dir, f"p{page_num}_empty")
+ LOG.info(
+ "fill_multipage_form: no fillable fields on page, stopping",
+ page_num=page_num,
+ total_fields=len(form_fields),
+ )
+ break
+
+ # Detect stuck on same page: if field labels haven't changed, the
+ # next-button click didn't navigate. Stop to avoid infinite loop.
+ field_sig = "|".join((f.get("label") or f.get("name") or f.get("placeholder") or "") for f in fillable)
+ if field_sig and field_sig == prev_field_signature:
+ LOG.warning(
+ "fill_multipage_form: same fields detected, page did not advance — stopping",
+ page_num=page_num,
+ field_count=len(fillable),
+ )
+ break
+ prev_field_signature = field_sig
+
+ field_labels = [(f.get("label") or f.get("name") or f.get("placeholder") or "?")[:40] for f in fillable]
+ # Log unlabeled fields with their raw data for debugging
+ unlabeled = [
+ {k: v for k, v in f.items() if k in ("tag", "type", "selector", "placeholder", "name")}
+ for f in fillable
+ if not f.get("label") and not f.get("name") and not f.get("placeholder")
+ ]
+ LOG.info(
+ "fill_multipage_form: filling page",
+ page_num=page_num,
+ field_count=len(fillable),
+ field_labels=field_labels,
+ unlabeled_fields=unlabeled[:5] if unlabeled else None,
+ elapsed_s=round(time.monotonic() - start_time, 1),
+ )
+
+ await self._dump_html(debug_dir, f"p{page_num}_00_before_fill")
+
+ mapping = await self.dynamic_field_map(form_fields, data, prompt=prompt)
+
+ # Skip validation on intermediate pages — validate_mapping checks user
+ # instructions like "do not submit" which only apply to the final page.
+ # We'll validate after the loop if needed.
+ await self.fill_from_mapping(form_fields, mapping, data=data)
+ pages_filled += 1
+
+ await self._dump_html(debug_dir, f"p{page_num}_01_after_fill")
+
+ # Re-scan for dynamically revealed fields (e.g., State appears after
+ # Country may be auto-filled). Fill any new fields that appeared.
+ rescan_fields = await self.extract_form_fields()
+ rescan_fillable = [
+ f
+ for f in rescan_fields
+ if (f.get("tag") in ("input", "select", "textarea") and f.get("type") != "hidden")
+ or f.get("type") in ("listbox", "multiselect", "toggle")
+ ]
+ new_field_count = len(rescan_fillable) - len(fillable)
+ if new_field_count > 0:
+ LOG.info(
+ "fill_multipage_form: new fields appeared after fill, re-mapping",
+ page_num=page_num,
+ original_count=len(fillable),
+ new_count=len(rescan_fillable),
+ new_fields=new_field_count,
+ )
+ rescan_mapping = await self.dynamic_field_map(rescan_fields, data, prompt=prompt)
+ # Only fill indices that weren't in the original mapping
+ new_mapping: dict[int, str | list | bool | None] = {
+ k: v for k, v in rescan_mapping.items() if k not in mapping and v is not None
+ }
+ if new_mapping:
+ await self.fill_from_mapping(rescan_fields, new_mapping, data=data)
+ await self._dump_html(debug_dir, f"p{page_num}_02_after_rescan_fill")
+ # Update field signature to use the new fields for stuck detection
+ fillable = rescan_fillable
+ form_fields = rescan_fields
+ prev_field_signature = "|".join(
+ (f.get("label") or f.get("name") or f.get("placeholder") or "") for f in fillable
+ )
+
+ # Try to click the next/continue button
+ try:
+ await self.click(
+ selector=next_button,
+ ai="fallback",
+ prompt="Click the button to save and continue to the next page of the application",
+ )
+ except Exception:
+ LOG.info(
+ "fill_multipage_form: next button not found, stopping",
+ page_num=page_num,
+ )
+ break
+
+ await self._dump_html(debug_dir, f"p{page_num}_03_after_click_next")
+
+ # Wait for page transition using DOM readiness check
+ try:
+ from skyvern.webeye.utils.page import SkyvernFrame
+
+ skyvern_frame = await SkyvernFrame.create_instance(frame=self.page)
+ await skyvern_frame.wait_for_page_ready(
+ network_idle_timeout_ms=3000,
+ loading_indicator_timeout_ms=5000,
+ dom_stable_ms=300,
+ dom_stability_timeout_ms=3000,
+ )
+ except Exception:
+ # Fall back to a short sleep if readiness check fails
+ await asyncio.sleep(2)
+
+ # Check for validation errors AFTER clicking next (some sites show
+ # errors only after clicking Save and Continue)
+ try:
+ post_click_errors = await self.page.evaluate("""() => {
+ const errs = [];
+ // Common error patterns: inline error messages, alert banners
+ const selectors = '[data-automation-id*="error"], [data-automation-id*="Error"], [class*="errorMessage"], [class*="fieldError"], [role="alert"], [aria-invalid="true"]';
+ document.querySelectorAll(selectors).forEach(el => {
+ const t = el.textContent.trim();
+ if (t && t.length > 3 && t.length < 300 && el.offsetWidth > 0) {
+ // Skip upload success messages — not real errors
+ if (/successfully uploaded/i.test(t)) return;
+ errs.push(t.substring(0, 100));
+ }
+ });
+ return errs;
+ }""")
+ if post_click_errors:
+ LOG.warning(
+ "fill_multipage_form: validation errors after Save and Continue",
+ page_num=page_num,
+ error_count=len(post_click_errors),
+ errors=post_click_errors[:5],
+ )
+ await self._dump_html(debug_dir, f"p{page_num}_04_validation_errors")
+ except Exception:
+ pass
+
+ elapsed = time.monotonic() - start_time
+ LOG.info(
+ "fill_multipage_form: completed",
+ pages_filled=pages_filled,
+ total_elapsed_s=round(elapsed, 1),
+ )
+ return pages_filled
+
def _match_field_to_map(
self,
field: dict[str, Any],
@@ -2317,8 +2621,6 @@ class SkyvernPage(Page):
navigation_goal: str = "Fill out the form",
) -> None:
"""Fill a field with a pre-planned value (no per-field LLM call)."""
- import json as _json
-
selector = field.get("selector", "")
field_type = field.get("type", "text")
field_tag = field.get("tag", "input")
diff --git a/skyvern/forge/agent_functions.py b/skyvern/forge/agent_functions.py
index 007105e81..bebb844d6 100644
--- a/skyvern/forge/agent_functions.py
+++ b/skyvern/forge/agent_functions.py
@@ -629,7 +629,7 @@ class AgentFunction:
def detect_ats_platform(self, url_or_domain: str | None) -> str | None:
"""Detect if a URL belongs to a known ATS platform.
- Returns a platform key (e.g., "lever") or None.
+ Returns a platform key string or None.
Override in cloud to provide platform detection.
"""
return None
@@ -650,6 +650,25 @@ class AgentFunction:
"""
return None
+ async def ensure_static_script(
+ self,
+ workflow: Any,
+ workflow_run: Any,
+ organization_id: str,
+ ) -> tuple[Any, dict[str, Any], Any] | None:
+ """Ensure a static pre-built script exists in the DB for this platform.
+
+ If the workflow targets a known platform (detected from block URLs),
+ creates a pinned script in the DB from the static source file on first
+ run. On subsequent runs the cached script is returned normally.
+
+ Returns ``(script, script_blocks_by_label, loaded_module)`` if a
+ static script was created/loaded, or None if no static script applies.
+
+ Override in cloud. OSS returns None.
+ """
+ return None
+
def build_ats_pipeline_block_fn(self, block: dict, ats_platform: str) -> Any:
"""Build an ATS-optimized script block for a detected platform.
@@ -664,3 +683,50 @@ class AgentFunction:
Returns an empty list in OSS. Override in cloud.
"""
return []
+
+ def get_form_field_mapper_hints(self) -> str | None:
+ """Return platform-specific hints for the form-field-mapper LLM prompt.
+
+ These hints are injected into the prompt template under
+ ``{{ platform_hints }}``. Use them to guide the LLM on
+ field-to-data key mappings specific to a platform (e.g., ATS
+ job applications).
+
+ Returns None in OSS. Override in cloud.
+ """
+ return None
+
+ def get_form_field_extraction_js(self, url: str | None = None) -> str | None:
+ """Return platform-specific JS to extend the base form field scanner.
+
+ The returned JS is concatenated into the base extract_form_fields.js
+ IIFE. It can reference ``fields``, ``seen``, ``isVisible``,
+ ``getLabel``, ``buildSelector``, ``buildOptionSelector``, and
+ ``getGroupLabel`` defined in the base script.
+
+ Args:
+ url: Current page URL, used to select the right platform JS.
+
+ Returns None in OSS (no platform-specific extraction).
+ Override in cloud to inject platform-specific passes.
+ """
+ return None
+
+ async def fill_custom_widget(
+ self,
+ page: Any,
+ field: dict,
+ value: Any,
+ label: str,
+ ) -> bool | None:
+ """Fill a platform-specific custom widget (e.g., hierarchical multiselect).
+
+ Returns:
+ True if the widget was filled successfully.
+ False if the widget was recognized but filling failed.
+ None if this field type is not a custom widget — caller should
+ use default handling.
+
+ Override in cloud to dispatch to platform-specific widget fillers.
+ """
+ return None
diff --git a/skyvern/forge/prompts/skyvern/form-field-mapper.j2 b/skyvern/forge/prompts/skyvern/form-field-mapper.j2
index 77255f787..abf3159b8 100644
--- a/skyvern/forge/prompts/skyvern/form-field-mapper.j2
+++ b/skyvern/forge/prompts/skyvern/form-field-mapper.j2
@@ -21,22 +21,29 @@ Follow these instructions when deciding how to fill fields — they take priorit
{%- if field.required %} [REQUIRED]{% endif %}
{%- if field.placeholder %} — hint: "{{ field.placeholder }}"{% endif %}
{%- if field.options %} — options: [{{ field.options | join(", ") }}]{% endif %}
+{%- if field.currentValue %} — current: "{{ field.currentValue }}"{% endif %}
+{%- if field.formatHint %} — FORMAT: {{ field.formatHint }}{% endif %}
{% endfor %}
# Instructions
For EVERY field above, decide the correct value from the provided data.
-## CRITICAL — Common mistakes to avoid
-- **graduation_year** maps to graduation/graduation date fields. Do NOT put other data (like additional_info) into graduation fields.
-- **additional_info** is a generic note — it goes ONLY into "Additional information" or "Cover letter" textareas, NEVER into specific fields like graduation date, name, or phone.
-- **needs_sponsorship** answers sponsorship questions DIRECTLY: if needs_sponsorship = "No", then "Will you require sponsorship?" → "No". Do NOT invert it.
-- **authorized_to_work** answers authorization questions DIRECTLY: if authorized_to_work = "Yes", then "Are you authorized to work?" → "Yes".
+## CRITICAL — General rules
- Each data key should map to at most ONE field. Never reuse the same value for unrelated fields.
+- Match semantically, not literally. A data key like "phone" maps to a field labeled "Phone number" or "Mobile".
+- For boolean/Yes-No data keys, map them DIRECTLY without inverting. If the data says "Yes", select "Yes".
+{% if platform_hints %}
+
+## Platform-specific guidance
+{{ platform_hints }}
+{% endif %}
## Text fields
-- Match semantically: "email" data → "Email address" field, "phone" → "Phone number", "graduation_year" → "Expected graduation date", etc.
-- For fields with no matching data (e.g., "Twitter URL" when no twitter data exists), return null.
+- Match semantically: "email" data → "Email address" field, "phone" → "Phone number", etc.
+- For fields with no matching data, return null.
+- For **multiselect** and **search-dropdown** fields: return a SPECIFIC, SEARCHABLE value from the data. The value will be typed into a search box, so it must match real option text.
+- **Fields with FORMAT hints**: Some fields show a required format (e.g., phone: "(xxx) xxx-xxxx"). You MUST reformat the data value to match the specified format. For phone numbers, convert raw digits like "5551234567" to the format shown (e.g., "(555) 123-4567"). For dates, convert to the required format (e.g., "MM/DD/YYYY").
## Choice fields (dropdown, radio, checkbox)
- Return the EXACT option text from the options list. Do NOT rephrase, abbreviate, or summarize.
@@ -44,16 +51,29 @@ For EVERY field above, decide the correct value from the provided data.
- For EEO/demographic fields with no matching data, pick the "Decline to self-identify" or "I do not want to answer" option.
- For checkboxes, return a JSON array of the exact option labels to check.
- For Yes/No radio buttons: match the provided data value directly. If the data says "Yes", select "Yes". If "No", select "No".
+- **Match questions by INTENT, not exact wording.** "Are you a U.S. citizen or permanent resident?" and "Are you authorized to work in the US?" ask the same thing — if the data has ANY key about work authorization, citizenship, or legal status, use it to answer.
+- For Yes/No questions with NO matching data (e.g., "Have you previously worked for [company]?", "Are you a former employee?"), default to "No" unless the data says otherwise.
## File upload fields (type: file)
- Look for URL values in the provided data that match file upload fields. For example: a parameter named "resume" with a URL value like "https://example.com/resume.pdf" should be mapped to a "Resume/CV" file upload field.
- Return the URL string as the value — the system will download and upload the file.
- If no matching URL exists in the provided data, return null.
+## Toggle fields (type: toggle)
+- Toggle fields are standalone checkboxes that enable or reveal additional form sections when checked (e.g., "I have a preferred name" reveals a preferred name section, "SMS Opt-In" enables text notifications).
+- They show their current state: "current: unchecked" or "current: checked".
+- **Default behavior: return null (leave unchanged).**
+- Only return true to CHECK a toggle if the provided data EXPLICITLY requires what it enables — e.g., only check "I have a preferred name" if the data contains a preferred_name that differs from first_name.
+- When in doubt, return null — checking a toggle adds unnecessary complexity to the form.
+
## Fields with no matching data
- For REQUIRED text fields with no matching data, write a brief professional response (1-2 sentences) based on the available data context.
- For OPTIONAL fields with no matching data, return null.
+## Listbox fields (type: listbox) with current value
+- If a listbox already shows a correct value (currentValue is set), return null to keep it.
+- If it shows "Select One" or needs changing, return the value to select.
+
# Output Format
JSON object mapping field number (1-indexed string) to the value to fill.
Return null for file uploads and optional fields with no matching data.
diff --git a/skyvern/forge/sdk/db/agent_db.py b/skyvern/forge/sdk/db/agent_db.py
index 30f2a3ff6..42e9c88a7 100644
--- a/skyvern/forge/sdk/db/agent_db.py
+++ b/skyvern/forge/sdk/db/agent_db.py
@@ -7138,6 +7138,7 @@ class AgentDB(BaseAlchemyDB):
workflow_id: str | None = None,
workflow_run_id: str | None = None,
status: ScriptStatus = ScriptStatus.published,
+ is_pinned: bool = False,
) -> None:
"""Create a workflow->script cache mapping entry."""
try:
@@ -7151,6 +7152,7 @@ class AgentDB(BaseAlchemyDB):
cache_key=cache_key,
cache_key_value=cache_key_value,
status=status,
+ is_pinned=is_pinned,
)
session.add(record)
await session.commit()
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 98d2e0b46..dc6758701 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -1307,9 +1307,10 @@ class WorkflowService:
if spec and spec.loader:
loaded_script_module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(loaded_script_module)
+ param_cls = getattr(loaded_script_module, "GeneratedWorkflowParameters", None)
await skyvern.setup(
script_parameters,
- generated_parameter_cls=loaded_script_module.GeneratedWorkflowParameters,
+ generated_parameter_cls=param_cls,
)
LOG.info(
"Successfully loaded script module",
@@ -1333,6 +1334,40 @@ class WorkflowService:
script_blocks_by_label = {}
loaded_script_module = None
+ # If no cached script exists, check if a static pre-built script
+ # should be created for this platform (e.g., ATS). This persists the
+ # script to DB (pinned) on first run so it shows in the Code tab.
+ if is_script_run and not script_blocks_by_label:
+ try:
+ static_result = await app.AGENT_FUNCTION.ensure_static_script(
+ workflow=workflow,
+ workflow_run=workflow_run,
+ organization_id=organization_id,
+ )
+ if static_result:
+ script, script_blocks_by_label, loaded_script_module = static_result
+ is_script_run = True
+ # Initialize RunContext with the browser page + parameters,
+ # same as the normal script loading path at line 1310.
+ parameter_tuples = await app.DATABASE.get_workflow_run_parameters(
+ workflow_run_id=workflow_run.workflow_run_id,
+ )
+ script_parameters = {wf_param.key: run_param.value for wf_param, run_param in parameter_tuples}
+ param_cls = getattr(loaded_script_module, "GeneratedWorkflowParameters", None)
+ await skyvern.setup(
+ script_parameters,
+ generated_parameter_cls=param_cls,
+ )
+ LOG.info(
+ "Static script loaded successfully",
+ script_id=script.script_id if script else None,
+ blocks=list(script_blocks_by_label.keys()),
+ )
+ else:
+ LOG.info("No static script available for this workflow")
+ except Exception:
+ LOG.error("Failed to load static script", exc_info=True)
+
# Mark workflow as running, preserving the user's original run_with intent.
# The run_with field records what the user requested (e.g. "code_v2"),
# not whether a script was actually found. Execution mode is determined