Skip to content

Automate browser based workflows with AI

refactor(SKY-11707): extract script-attempt and agent-execution phases from _execute_single_block (#7354)

Aaron Perezcd3e0d4f665f
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 068e2b575..03dccf774 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -452,6 +452,17 @@ class CachedScriptBlocks:
blocks_to_clear: list[ScriptBlock]
+@dataclass(frozen=True)
+class ScriptBlockAttempt:
+ block_result: BlockResult | None
+ executed_with_code: bool
+ valid_to_run_code: bool
+ block_requires_agent: bool
+ fallback_episode_id: str | None
+ form_fields_for_episode: list | None
+ script_exception: Exception | None
+
+
@dataclass
class WorkflowBrowserCleanupResult:
browser_state: BrowserState | None
@@ -3598,356 +3609,40 @@ class WorkflowService:
browser_session_id=browser_session_id,
)
- valid_to_run_code = (
- is_script_run and block.label and block.label in script_blocks_by_label and not block.disable_cache
+ attempt = await self._try_execute_block_with_script(
+ workflow=workflow,
+ workflow_run=workflow_run,
+ block=block,
+ workflow_run_id=workflow_run_id,
+ organization_id=organization_id,
+ script_blocks_by_label=script_blocks_by_label,
+ loaded_script_module=loaded_script_module,
+ is_script_run=is_script_run,
)
- # requires_agent blocks must execute via agent, not code — skip code path
- block_requires_agent = False
- if valid_to_run_code and script_blocks_by_label[block.label].requires_agent:
- valid_to_run_code = False
- block_requires_agent = True
-
- # Log the execution mode decision for every block in a script run
- if is_script_run and block.label:
- LOG.info(
- "Block execution mode resolved",
- block_label=block.label,
- execution_mode="script" if valid_to_run_code else "ai",
- has_label=True,
- in_cache=block.label in script_blocks_by_label,
- disable_cache=block.disable_cache,
- requires_agent=block_requires_agent,
- )
-
- fallback_episode_id: str | None = None
- form_fields_for_episode: list | None = None
- script_exception: Exception | None = None
- if valid_to_run_code:
- script_block = script_blocks_by_label[block.label]
- LOG.info(
- "Attempting to execute block with script code",
- block_label=block.label,
- run_signature=script_block.run_signature,
- )
- # Script path skips the block's own execute() (which is where
- # format_potential_template_parameters runs in the agent path),
- # so we apply the workflow_system_prompt here to thread the
- # block-resolved value into the ``WorkflowRunContext`` cache.
- # ``ai_extract`` reads from that cache so the script-generated
- # extraction honors ``ignore_workflow_system_prompt`` the same
- # way the agent path does — same string, same cache key.
- try:
- workflow_run_context = app.WORKFLOW_CONTEXT_MANAGER.get_workflow_run_context(workflow_run_id)
- block._apply_workflow_system_prompt(workflow_run_context)
- except Exception:
- LOG.warning(
- "Failed to apply workflow_system_prompt for script-path block; continuing",
- block_label=block.label,
- exc_info=True,
- )
-
- block_exec_start = time.monotonic()
- try:
- vars_dict = vars(loaded_script_module) if loaded_script_module else {}
- exec_globals = {
- **vars_dict,
- "skyvern": skyvern,
- "__builtins__": __builtins__,
- }
-
- assert script_block.run_signature is not None
- normalized_signature = textwrap.dedent(script_block.run_signature).strip()
-
- # Compound statements (async for, for, if, while) can't be
- # wrapped in `return (...)` — they must be inlined directly
- # into the async wrapper function body.
- _COMPOUND_PREFIXES = ("async for ", "for ", "if ", "while ", "with ", "async with ")
- is_compound = normalized_signature.startswith(_COMPOUND_PREFIXES)
-
- if is_compound:
- indented_signature = textwrap.indent(normalized_signature, " ")
- wrapper_code = f"async def __run_signature_wrapper():\n{indented_signature}\n"
- else:
- indented_signature = textwrap.indent(normalized_signature, " ")
- wrapper_code = (
- f"async def __run_signature_wrapper():\n return (\n{indented_signature}\n )\n"
- )
-
- LOG.debug("Executing run_signature wrapper", wrapper_code=wrapper_code)
-
- # Pre-init so the success log can reference output_value
- # when ScriptTerminationException was caught (terminated
- # is now in script_success_statuses).
- output_value: Any = None
- try:
- exec_code = compile(wrapper_code, "<run_signature>", "exec")
- exec(exec_code, exec_globals)
- output_value = await exec_globals["__run_signature_wrapper"]()
- except ScriptTerminationException as e:
- LOG.warning(
- "Script termination",
- block_label=block.label,
- error=str(e),
- exc_info=True,
- )
-
- workflow_run_blocks = await app.DATABASE.observer.get_workflow_run_blocks(
- workflow_run_id=workflow_run_id,
- organization_id=organization_id,
- )
- matching_blocks = [b for b in workflow_run_blocks if b.label == block.label]
- if matching_blocks:
- latest_block = max(matching_blocks, key=lambda b: b.created_at)
- workflow_run_block_result = BlockResult(
- success=latest_block.status == BlockStatus.completed,
- failure_reason=latest_block.failure_reason,
- output_parameter=block.output_parameter,
- output_parameter_value=latest_block.output,
- status=BlockStatus(latest_block.status) if latest_block.status else BlockStatus.failed,
- workflow_run_block_id=latest_block.workflow_run_block_id,
- )
- # Terminate() is an explicit signal to stop, not a
- # failure to retry. `generate_script_on_terminal` is
- # orthogonal — it gates script generation, not fallback.
- script_success_statuses = {BlockStatus.completed, BlockStatus.terminated}
-
- block_exec_duration_ms = round((time.monotonic() - block_exec_start) * 1000, 1)
- if workflow_run_block_result.status in script_success_statuses:
- block_executed_with_code = True
- LOG.info(
- "Successfully executed block with script code",
- block_label=block.label,
- block_status=workflow_run_block_result.status,
- has_output=output_value is not None,
- duration_ms=block_exec_duration_ms,
- )
- else:
- # Script ran but the task/block failed (e.g., wrong xpaths for a
- # different page layout). Treat this as a script failure: record a
- # fallback episode and let AI retry the block.
- block_executed_with_code = False
- LOG.warning(
- "Script executed but block failed, falling back to AI",
- block_label=block.label,
- block_status=workflow_run_block_result.status,
- failure_reason=workflow_run_block_result.failure_reason,
- duration_ms=block_exec_duration_ms,
- )
- # Reset the block result so AI fallback produces a fresh one
- workflow_run_block_result = None
-
- # Record fallback episode for adaptive caching
- if is_adaptive_caching(workflow, workflow_run) and block.label:
- context = skyvern_context.current()
- fallback_episode_id, form_fields_for_episode = await self._record_fallback_episode(
- workflow_run=workflow_run,
- workflow=workflow,
- block=block,
- organization_id=organization_id,
- workflow_run_id=workflow_run_id,
- error_message=f"Script completed but block failed: {latest_block.failure_reason}",
- script_revision_id=context.script_revision_id if context else None,
- classify_result=context.last_classify_result if context else None,
- )
- else:
- block_exec_duration_ms = round((time.monotonic() - block_exec_start) * 1000, 1)
- LOG.warning(
- "Block executed with code but no workflow run block found",
- block_label=block.label,
- duration_ms=block_exec_duration_ms,
- )
- block_executed_with_code = False
- except Exception as e:
- block_exec_duration_ms = round((time.monotonic() - block_exec_start) * 1000, 1)
- script_exception = e
- LOG.warning(
- "Failed to execute block with script code, falling back to AI",
- block_label=block.label,
- error_type=type(e).__name__,
- error=str(e),
- duration_ms=block_exec_duration_ms,
- exc_info=True,
- )
- block_executed_with_code = False
-
- # Record fallback episode for the script reviewer (adaptive caching)
- if is_adaptive_caching(workflow, workflow_run) and block.label:
- context = skyvern_context.current()
- fallback_episode_id, form_fields_for_episode = await self._record_fallback_episode(
- workflow_run=workflow_run,
- workflow=workflow,
- block=block,
- organization_id=organization_id,
- workflow_run_id=workflow_run_id,
- error_message=str(e),
- script_revision_id=context.script_revision_id if context else None,
- )
+ workflow_run_block_result = attempt.block_result
+ block_executed_with_code = attempt.executed_with_code
+ block_requires_agent = attempt.block_requires_agent
if not block_executed_with_code:
- # Check if this block is designated as requires_agent by the script reviewer.
- # These blocks must execute via agent even when ai_fallback=False.
- block_requires_agent = bool(
- is_script_run
- and block.label
- and block.label in script_blocks_by_label
- and script_blocks_by_label[block.label].requires_agent
- )
- # Check if this block has never been cached (e.g. from an unexecuted
- # conditional branch) or is a non-cacheable block type (goto_url,
- # for_loop, conditional, code, wait, etc.). These blocks must run
- # via agent even when ai_fallback=False.
- block_is_uncached = bool(
- is_script_run
- and block.label
- and block.label not in script_blocks_by_label
- and block.block_type in BLOCK_TYPES_THAT_SHOULD_BE_CACHED
- )
- block_is_non_cacheable = bool(
- is_script_run and block.block_type not in BLOCK_TYPES_THAT_SHOULD_BE_CACHED
- )
- # If ai_fallback is explicitly disabled, skip the agent fallback entirely —
- # UNLESS this block requires_agent, has never been cached, or is a
- # non-cacheable block type that must always run via agent.
- if (
- is_script_run
- and workflow_run.ai_fallback is False
- and not block_requires_agent
- and not block_is_uncached
- and not block_is_non_cacheable
- ):
- LOG.info(
- "ai_fallback disabled: skipping agent fallback, keeping script failure",
- block_label=block.label,
- failure_reason=str(workflow_run_block_result.failure_reason)[:200]
- if workflow_run_block_result
- else "script exception",
- )
- else:
- agent_reason = (
- "requires_agent"
- if block_requires_agent
- else "uncached_block"
- if block_is_uncached
- else "non_cacheable_block_type"
- if block_is_non_cacheable
- else "normal"
- )
- LOG.info(
- "Executing block via agent",
- sampling=True,
- block_label=block.label,
- block_type=block.block_type,
- agent_reason=agent_reason,
- )
- workflow_run_block_result = await block.execute_safe(
- workflow_run_id=workflow_run_id,
- parent_workflow_run_block_id=parent_workflow_run_block_id,
+ workflow_run_block_result, block_requires_agent = await self._execute_block_via_agent_if_allowed(
+ block=block,
+ workflow_run=workflow_run,
+ workflow_run_id=workflow_run_id,
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ parent_workflow_run_block_id=parent_workflow_run_block_id,
+ is_script_run=is_script_run,
+ script_blocks_by_label=script_blocks_by_label,
+ attempt=attempt,
+ )
+ if attempt.fallback_episode_id and workflow_run_block_result:
+ await self._enrich_fallback_episode_with_agent_actions(
+ block=block,
+ workflow_run_block_result=workflow_run_block_result,
+ fallback_episode_id=attempt.fallback_episode_id,
+ form_fields_for_episode=attempt.form_fields_for_episode,
organization_id=organization_id,
- browser_session_id=browser_session_id,
)
- # Record that this run experienced a script → AI fallback if
- # the agent execution we just ran was a consequence of a failed
- # script attempt. The gate correctly excludes:
- # - ai_fallback=False kept-the-failure (execute_safe not reached)
- # - requires_agent / uncached / disable_cache / non-cacheable
- # routes (valid_to_run_code is False for these)
- # - agent-only workflows (is_script_run=False → valid_to_run_code=False)
- # and correctly covers all three script-failure modes: script-
- # block failed, script threw, and script-ran-but-no-block-found.
- # Complements the task-block AI-fallback writers in `services/script_service.py`
- # writers which handle a separate task-block AI-fallback surface.
- # Perf: a fallback-heavy run issues N writes for N fallbacks.
- # Typical runs have 0-3. `_merge_script_run` is idempotent at the
- # DB layer. If observed latency regresses, add a context-scoped
- # already-flipped cache (tracked separately).
- await self._mark_script_fallback_triggered(
- workflow_run_id=workflow_run_id,
- # `valid_to_run_code` is computed as a chain of `and`s that
- # includes `block.label` (str | None), so its static type is
- # `Literal[''] | bool` when block.label is an empty string.
- # The helper treats it as a pure truthiness gate; `bool(...)`
- # narrows the type cleanly for mypy without changing runtime
- # semantics.
- valid_to_run_code=bool(valid_to_run_code),
- block_executed_with_code=block_executed_with_code,
- block_label=block.label,
- )
-
- # Update fallback episode with agent actions for both success and failure.
- # Failed fallbacks are kept for triage — the reviewer will determine
- # if the failure is code-fixable.
- if fallback_episode_id and workflow_run_block_result:
- try:
- # None = unknown count (taskless wrb / fetch error);
- # only a confirmed zero downgrades fallback_succeeded.
- fallback_wrb_id = workflow_run_block_result.workflow_run_block_id
- agent_action_count: int | None = None
- action_summaries: list[dict] | None = None
- if fallback_wrb_id:
- try:
- wrb = await app.DATABASE.observer.get_workflow_run_block(
- workflow_run_block_id=fallback_wrb_id,
- organization_id=organization_id,
- )
- if wrb and wrb.task_id:
- actions = await app.DATABASE.tasks.get_task_actions(
- task_id=wrb.task_id,
- organization_id=organization_id,
- )
- agent_action_count = len(actions)
- action_summaries = build_action_summaries_with_timing(actions)
- except Exception:
- LOG.debug(
- "Could not fetch rich actions for fallback episode",
- fallback_wrb_id=fallback_wrb_id,
- exc_info=True,
- )
-
- # `completed` with confirmed 0 actions = the agent's
- # complete-verify accepting what the script's rejected.
- fallback_succeeded = workflow_run_block_result.status == BlockStatus.completed
- if fallback_succeeded and agent_action_count == 0:
- fallback_succeeded = False
-
- # Build agent actions summary for both success and failure
- agent_actions_summary: dict = {
- "block_status": str(workflow_run_block_result.status),
- "output_value": str(workflow_run_block_result.output_parameter_value)[:500]
- if workflow_run_block_result.output_parameter_value
- else None,
- }
- if form_fields_for_episode:
- agent_actions_summary["form_fields"] = form_fields_for_episode
- if action_summaries is not None:
- agent_actions_summary["actions"] = action_summaries
-
- if not fallback_succeeded:
- if workflow_run_block_result.failure_reason:
- agent_actions_summary["failure_reason"] = str(workflow_run_block_result.failure_reason)[
- :2000
- ]
- elif workflow_run_block_result.status == BlockStatus.completed and agent_action_count == 0:
- agent_actions_summary["failure_reason"] = script_service.VERIFIER_SWAP_FAILURE_REASON
- LOG.info(
- "AI fallback failed, keeping episode for triage",
- episode_id=fallback_episode_id,
- block_status=workflow_run_block_result.status,
- block_label=block.label,
- agent_action_count=agent_action_count,
- )
-
- await app.DATABASE.scripts.update_fallback_episode(
- episode_id=fallback_episode_id,
- organization_id=organization_id,
- agent_actions=agent_actions_summary,
- fallback_succeeded=fallback_succeeded,
- )
- except Exception:
- LOG.warning(
- "Failed to update fallback episode with agent actions",
- episode_id=fallback_episode_id,
- exc_info=True,
- )
# Extract branch metadata for conditional blocks
if isinstance(block, ConditionalBlock) and workflow_run_block_result:
@@ -3960,7 +3655,7 @@ class WorkflowService:
# (fallback_episode_id is set when the script path failed).
if (
is_script_run
- and (block_requires_agent or fallback_episode_id)
+ and (block_requires_agent or attempt.fallback_episode_id)
and workflow_run_block_result.status == BlockStatus.completed
and branch_metadata
and is_adaptive_caching(workflow, workflow_run)
@@ -4038,9 +3733,9 @@ class WorkflowService:
)
if not workflow_run_block_result:
- if script_exception is not None:
- exc_message = str(script_exception) or "<no message>"
- no_block_result_reason = f"Script error ({type(script_exception).__name__}): {exc_message}"
+ if attempt.script_exception is not None:
+ exc_message = str(attempt.script_exception) or "<no message>"
+ no_block_result_reason = f"Script error ({type(attempt.script_exception).__name__}): {exc_message}"
else:
no_block_result_reason = "Block result is None"
workflow_run = await self.mark_workflow_run_as_failed(
@@ -4128,6 +3823,387 @@ class WorkflowService:
)
return workflow_run, blocks_to_update, workflow_run_block_result, True, branch_metadata
+ async def _try_execute_block_with_script(
+ self,
+ *,
+ workflow: Workflow,
+ workflow_run: WorkflowRun,
+ block: BlockTypeVar,
+ workflow_run_id: str,
+ organization_id: str,
+ script_blocks_by_label: dict[str, Any],
+ loaded_script_module: Any,
+ is_script_run: bool,
+ ) -> ScriptBlockAttempt:
+ workflow_run_block_result: BlockResult | None = None
+ block_executed_with_code = False
+ valid_to_run_code = (
+ is_script_run and block.label and block.label in script_blocks_by_label and not block.disable_cache
+ )
+ # requires_agent blocks must execute via agent, not code — skip code path
+ block_requires_agent = False
+ if valid_to_run_code and script_blocks_by_label[block.label].requires_agent:
+ valid_to_run_code = False
+ block_requires_agent = True
+
+ # Log the execution mode decision for every block in a script run
+ if is_script_run and block.label:
+ LOG.info(
+ "Block execution mode resolved",
+ block_label=block.label,
+ execution_mode="script" if valid_to_run_code else "ai",
+ has_label=True,
+ in_cache=block.label in script_blocks_by_label,
+ disable_cache=block.disable_cache,
+ requires_agent=block_requires_agent,
+ )
+
+ fallback_episode_id: str | None = None
+ form_fields_for_episode: list | None = None
+ script_exception: Exception | None = None
+ if valid_to_run_code:
+ script_block = script_blocks_by_label[block.label]
+ LOG.info(
+ "Attempting to execute block with script code",
+ block_label=block.label,
+ run_signature=script_block.run_signature,
+ )
+ # Script path skips the block's own execute() (which is where
+ # format_potential_template_parameters runs in the agent path),
+ # so we apply the workflow_system_prompt here to thread the
+ # block-resolved value into the ``WorkflowRunContext`` cache.
+ # ``ai_extract`` reads from that cache so the script-generated
+ # extraction honors ``ignore_workflow_system_prompt`` the same
+ # way the agent path does — same string, same cache key.
+ try:
+ workflow_run_context = app.WORKFLOW_CONTEXT_MANAGER.get_workflow_run_context(workflow_run_id)
+ block._apply_workflow_system_prompt(workflow_run_context)
+ except Exception:
+ LOG.warning(
+ "Failed to apply workflow_system_prompt for script-path block; continuing",
+ block_label=block.label,
+ exc_info=True,
+ )
+
+ block_exec_start = time.monotonic()
+ try:
+ vars_dict = vars(loaded_script_module) if loaded_script_module else {}
+ exec_globals = {
+ **vars_dict,
+ "skyvern": skyvern,
+ "__builtins__": __builtins__,
+ }
+
+ assert script_block.run_signature is not None
+ normalized_signature = textwrap.dedent(script_block.run_signature).strip()
+
+ # Compound statements (async for, for, if, while) can't be
+ # wrapped in `return (...)` — they must be inlined directly
+ # into the async wrapper function body.
+ _COMPOUND_PREFIXES = ("async for ", "for ", "if ", "while ", "with ", "async with ")
+ is_compound = normalized_signature.startswith(_COMPOUND_PREFIXES)
+
+ if is_compound:
+ indented_signature = textwrap.indent(normalized_signature, " ")
+ wrapper_code = f"async def __run_signature_wrapper():\n{indented_signature}\n"
+ else:
+ indented_signature = textwrap.indent(normalized_signature, " ")
+ wrapper_code = f"async def __run_signature_wrapper():\n return (\n{indented_signature}\n )\n"
+
+ LOG.debug("Executing run_signature wrapper", wrapper_code=wrapper_code)
+
+ # Pre-init so the success log can reference output_value
+ # when ScriptTerminationException was caught (terminated
+ # is now in script_success_statuses).
+ output_value: Any = None
+ try:
+ exec_code = compile(wrapper_code, "<run_signature>", "exec")
+ exec(exec_code, exec_globals)
+ output_value = await exec_globals["__run_signature_wrapper"]()
+ except ScriptTerminationException as e:
+ LOG.warning(
+ "Script termination",
+ block_label=block.label,
+ error=str(e),
+ exc_info=True,
+ )
+
+ workflow_run_blocks = await app.DATABASE.observer.get_workflow_run_blocks(
+ workflow_run_id=workflow_run_id,
+ organization_id=organization_id,
+ )
+ matching_blocks = [b for b in workflow_run_blocks if b.label == block.label]
+ if matching_blocks:
+ latest_block = max(matching_blocks, key=lambda b: b.created_at)
+ workflow_run_block_result = BlockResult(
+ success=latest_block.status == BlockStatus.completed,
+ failure_reason=latest_block.failure_reason,
+ output_parameter=block.output_parameter,
+ output_parameter_value=latest_block.output,
+ status=BlockStatus(latest_block.status) if latest_block.status else BlockStatus.failed,
+ workflow_run_block_id=latest_block.workflow_run_block_id,
+ )
+ # Terminate() is an explicit signal to stop, not a
+ # failure to retry. `generate_script_on_terminal` is
+ # orthogonal — it gates script generation, not fallback.
+ script_success_statuses = {BlockStatus.completed, BlockStatus.terminated}
+
+ block_exec_duration_ms = round((time.monotonic() - block_exec_start) * 1000, 1)
+ if workflow_run_block_result.status in script_success_statuses:
+ block_executed_with_code = True
+ LOG.info(
+ "Successfully executed block with script code",
+ block_label=block.label,
+ block_status=workflow_run_block_result.status,
+ has_output=output_value is not None,
+ duration_ms=block_exec_duration_ms,
+ )
+ else:
+ # Script ran but the task/block failed (e.g., wrong xpaths for a
+ # different page layout). Treat this as a script failure: record a
+ # fallback episode and let AI retry the block.
+ block_executed_with_code = False
+ LOG.warning(
+ "Script executed but block failed, falling back to AI",
+ block_label=block.label,
+ block_status=workflow_run_block_result.status,
+ failure_reason=workflow_run_block_result.failure_reason,
+ duration_ms=block_exec_duration_ms,
+ )
+ # Reset the block result so AI fallback produces a fresh one
+ workflow_run_block_result = None
+
+ # Record fallback episode for adaptive caching
+ if is_adaptive_caching(workflow, workflow_run) and block.label:
+ context = skyvern_context.current()
+ fallback_episode_id, form_fields_for_episode = await self._record_fallback_episode(
+ workflow_run=workflow_run,
+ workflow=workflow,
+ block=block,
+ organization_id=organization_id,
+ workflow_run_id=workflow_run_id,
+ error_message=f"Script completed but block failed: {latest_block.failure_reason}",
+ script_revision_id=context.script_revision_id if context else None,
+ classify_result=context.last_classify_result if context else None,
+ )
+ else:
+ block_exec_duration_ms = round((time.monotonic() - block_exec_start) * 1000, 1)
+ LOG.warning(
+ "Block executed with code but no workflow run block found",
+ block_label=block.label,
+ duration_ms=block_exec_duration_ms,
+ )
+ block_executed_with_code = False
+ except Exception as e:
+ block_exec_duration_ms = round((time.monotonic() - block_exec_start) * 1000, 1)
+ script_exception = e
+ LOG.warning(
+ "Failed to execute block with script code, falling back to AI",
+ block_label=block.label,
+ error_type=type(e).__name__,
+ error=str(e),
+ duration_ms=block_exec_duration_ms,
+ exc_info=True,
+ )
+ block_executed_with_code = False
+
+ # Record fallback episode for the script reviewer (adaptive caching)
+ if is_adaptive_caching(workflow, workflow_run) and block.label:
+ context = skyvern_context.current()
+ fallback_episode_id, form_fields_for_episode = await self._record_fallback_episode(
+ workflow_run=workflow_run,
+ workflow=workflow,
+ block=block,
+ organization_id=organization_id,
+ workflow_run_id=workflow_run_id,
+ error_message=str(e),
+ script_revision_id=context.script_revision_id if context else None,
+ )
+ return ScriptBlockAttempt(
+ block_result=workflow_run_block_result,
+ executed_with_code=block_executed_with_code,
+ valid_to_run_code=bool(valid_to_run_code),
+ block_requires_agent=block_requires_agent,
+ fallback_episode_id=fallback_episode_id,
+ form_fields_for_episode=form_fields_for_episode,
+ script_exception=script_exception,
+ )
+
+ async def _execute_block_via_agent_if_allowed(
+ self,
+ *,
+ block: BlockTypeVar,
+ workflow_run: WorkflowRun,
+ workflow_run_id: str,
+ organization_id: str,
+ browser_session_id: str | None,
+ parent_workflow_run_block_id: str | None,
+ is_script_run: bool,
+ script_blocks_by_label: dict[str, Any],
+ attempt: ScriptBlockAttempt,
+ ) -> tuple[BlockResult | None, bool]:
+ workflow_run_block_result = attempt.block_result
+ # Check if this block is designated as requires_agent by the script reviewer.
+ # These blocks must execute via agent even when ai_fallback=False.
+ block_requires_agent = bool(
+ is_script_run
+ and block.label
+ and block.label in script_blocks_by_label
+ and script_blocks_by_label[block.label].requires_agent
+ )
+ # Check if this block has never been cached (e.g. from an unexecuted
+ # conditional branch) or is a non-cacheable block type (goto_url,
+ # for_loop, conditional, code, wait, etc.). These blocks must run
+ # via agent even when ai_fallback=False.
+ block_is_uncached = bool(
+ is_script_run
+ and block.label
+ and block.label not in script_blocks_by_label
+ and block.block_type in BLOCK_TYPES_THAT_SHOULD_BE_CACHED
+ )
+ block_is_non_cacheable = bool(is_script_run and block.block_type not in BLOCK_TYPES_THAT_SHOULD_BE_CACHED)
+ # If ai_fallback is explicitly disabled, skip the agent fallback entirely —
+ # UNLESS this block requires_agent, has never been cached, or is a
+ # non-cacheable block type that must always run via agent.
+ if (
+ is_script_run
+ and workflow_run.ai_fallback is False
+ and not block_requires_agent
+ and not block_is_uncached
+ and not block_is_non_cacheable
+ ):
+ LOG.info(
+ "ai_fallback disabled: skipping agent fallback, keeping script failure",
+ block_label=block.label,
+ failure_reason=str(workflow_run_block_result.failure_reason)[:200]
+ if workflow_run_block_result
+ else "script exception",
+ )
+ else:
+ agent_reason = (
+ "requires_agent"
+ if block_requires_agent
+ else "uncached_block"
+ if block_is_uncached
+ else "non_cacheable_block_type"
+ if block_is_non_cacheable
+ else "normal"
+ )
+ LOG.info(
+ "Executing block via agent",
+ sampling=True,
+ block_label=block.label,
+ block_type=block.block_type,
+ agent_reason=agent_reason,
+ )
+ workflow_run_block_result = await block.execute_safe(
+ workflow_run_id=workflow_run_id,
+ parent_workflow_run_block_id=parent_workflow_run_block_id,
+ organization_id=organization_id,
+ browser_session_id=browser_session_id,
+ )
+ # Record that this run experienced a script → AI fallback if
+ # the agent execution we just ran was a consequence of a failed
+ # script attempt. The gate correctly excludes:
+ # - ai_fallback=False kept-the-failure (execute_safe not reached)
+ # - requires_agent / uncached / disable_cache / non-cacheable
+ # routes (valid_to_run_code is False for these)
+ # - agent-only workflows (is_script_run=False → valid_to_run_code=False)
+ # and correctly covers all three script-failure modes: script-
+ # block failed, script threw, and script-ran-but-no-block-found.
+ # Complements the task-block AI-fallback writers in `services/script_service.py`
+ # writers which handle a separate task-block AI-fallback surface.
+ # Perf: a fallback-heavy run issues N writes for N fallbacks.
+ # Typical runs have 0-3. `_merge_script_run` is idempotent at the
+ # DB layer. If observed latency regresses, add a context-scoped
+ # already-flipped cache (tracked separately).
+ await self._mark_script_fallback_triggered(
+ workflow_run_id=workflow_run_id,
+ valid_to_run_code=attempt.valid_to_run_code,
+ block_executed_with_code=attempt.executed_with_code,
+ block_label=block.label,
+ )
+ return workflow_run_block_result, block_requires_agent
+
+ async def _enrich_fallback_episode_with_agent_actions(
+ self,
+ *,
+ block: BlockTypeVar,
+ workflow_run_block_result: BlockResult,
+ fallback_episode_id: str,
+ form_fields_for_episode: list | None,
+ organization_id: str,
+ ) -> None:
+ try:
+ # None = unknown count (taskless wrb / fetch error);
+ # only a confirmed zero downgrades fallback_succeeded.
+ fallback_wrb_id = workflow_run_block_result.workflow_run_block_id
+ agent_action_count: int | None = None
+ action_summaries: list[dict] | None = None
+ if fallback_wrb_id:
+ try:
+ wrb = await app.DATABASE.observer.get_workflow_run_block(
+ workflow_run_block_id=fallback_wrb_id,
+ organization_id=organization_id,
+ )
+ if wrb and wrb.task_id:
+ actions = await app.DATABASE.tasks.get_task_actions(
+ task_id=wrb.task_id,
+ organization_id=organization_id,
+ )
+ agent_action_count = len(actions)
+ action_summaries = build_action_summaries_with_timing(actions)
+ except Exception:
+ LOG.debug(
+ "Could not fetch rich actions for fallback episode",
+ fallback_wrb_id=fallback_wrb_id,
+ exc_info=True,
+ )
+
+ # `completed` with confirmed 0 actions = the agent's
+ # complete-verify accepting what the script's rejected.
+ fallback_succeeded = workflow_run_block_result.status == BlockStatus.completed
+ if fallback_succeeded and agent_action_count == 0:
+ fallback_succeeded = False
+
+ # Build agent actions summary for both success and failure
+ agent_actions_summary: dict = {
+ "block_status": str(workflow_run_block_result.status),
+ "output_value": str(workflow_run_block_result.output_parameter_value)[:500]
+ if workflow_run_block_result.output_parameter_value
+ else None,
+ }
+ if form_fields_for_episode:
+ agent_actions_summary["form_fields"] = form_fields_for_episode
+ if action_summaries is not None:
+ agent_actions_summary["actions"] = action_summaries
+
+ if not fallback_succeeded:
+ if workflow_run_block_result.failure_reason:
+ agent_actions_summary["failure_reason"] = str(workflow_run_block_result.failure_reason)[:2000]
+ elif workflow_run_block_result.status == BlockStatus.completed and agent_action_count == 0:
+ agent_actions_summary["failure_reason"] = script_service.VERIFIER_SWAP_FAILURE_REASON
+ LOG.info(
+ "AI fallback failed, keeping episode for triage",
+ episode_id=fallback_episode_id,
+ block_status=workflow_run_block_result.status,
+ block_label=block.label,
+ agent_action_count=agent_action_count,
+ )
+
+ await app.DATABASE.scripts.update_fallback_episode(
+ episode_id=fallback_episode_id,
+ organization_id=organization_id,
+ agent_actions=agent_actions_summary,
+ fallback_succeeded=fallback_succeeded,
+ )
+ except Exception:
+ LOG.warning(
+ "Failed to update fallback episode with agent actions",
+ episode_id=fallback_episode_id,
+ exc_info=True,
+ )
+
async def _prepare_login_block_browser_profile(
self,
*,