Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Let copilot ask for a login credential with a tool that opens the in-chat card (SKY-15409) (#8420)
Andrew Neilson827b70a2a202
diff --git a/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts b/skyvern-frontend/src/routes/workflows/copilot/narrativeState.tsindex 068a46019..8e710938e 100644--- a/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts+++ b/skyvern-frontend/src/routes/workflows/copilot/narrativeState.ts@@ -658,6 +658,7 @@ const ACTIVITY_TOOL_DISPLAY_LABELS: Record<string, string> = {edit_block: "Editing block",add_block: "Adding block",delete_block: "Deleting block",+ request_credential: "Requesting a credential",synthesize_demonstrated_block: "Building a block from the recorded steps",};diff --git a/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2 b/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2index 5be659107..4dd74e34a 100644--- a/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2+++ b/skyvern/forge/prompts/skyvern/workflow-copilot-agent.j2@@ -13,7 +13,7 @@ Blocks already in the workflow stay as-is unless the user asks you to change theEach turn carries the user's account state — saved credentials (name, ID, the site each was tested against, whether it carries an authenticator), connected integrations, and recent workflows. It is ground truth: never ask for something it already shows, and never tell a user their account lacks something without checking both the state and the relevant tool.-A saved credential is a named login stored in the user's vault. It is attached to workflows as a credential parameter and filled into pages by the platform — you never see or handle the secret values. A credential may carry a TOTP authenticator; when it does, two-factor prompts can be satisfied without the user. Credentials reach you two ways: you resolve one the user names, by exact name or credential ID; or the platform matches the live page and reports the credential it resolved. When a credential has already been resolved for the page you are on, use it — do not ask which login to use.+A saved credential is a named login stored in the user's vault. It is attached to workflows as a credential parameter and filled into pages by the platform — you never see or handle the secret values. A credential may carry a TOTP authenticator; when it does, two-factor prompts can be satisfied without the user. Credentials reach you three ways: you resolve one the user names, by exact name or credential ID; the platform matches the live page and reports the credential it resolved; or, when a sign-in is needed and no saved credential covers that site, you call request_credential with the sign-in page URL and the user adds or picks one in chat — call that tool instead of directing the user to the Credentials page. When a credential has already been resolved for the page you are on, use it — do not ask which login to use.CREDENTIAL HANDLING - CRITICAL:DO NOT PROVIDE RAW LOGIN/PASSWORD values to tools. If a message contains a raw secret written inline (a password, API key, token, or one-time code), do not echo it, do not type or submit it into a page, do not pass it as a run parameter, and do not use the browser or run anything with it. You may persist only a redacted draft that uses a saved credential parameter; then ask the user to store the secret as a saved credential and reply with its name — that is the whole turn.diff --git a/skyvern/forge/sdk/copilot/agent.py b/skyvern/forge/sdk/copilot/agent.pyindex ce7cff82a..b47098f30 100644--- a/skyvern/forge/sdk/copilot/agent.py+++ b/skyvern/forge/sdk/copilot/agent.py@@ -100,7 +100,6 @@ from skyvern.forge.sdk.copilot.context import (record_approved_credentials_in_global_llm_context,sanitize_global_llm_context_for_prompt,)-from skyvern.forge.sdk.copilot.credential_pause import credential_pause_reason, preflight_credential_pausefrom skyvern.forge.sdk.copilot.data_write_defaults import default_data_write_continue_on_failurefrom skyvern.forge.sdk.copilot.enforcement import (_elapsed_run_seconds,@@ -4838,16 +4837,12 @@ async def _run_copilot_turn_impl(prior_copilot_workflow_yaml=prior_copilot_workflow_yaml,)if request_policy is not None and request_policy_guardrail_result.output.tripwire_triggered:- preflight_resolution = None- if credential_pause_reason(ctx) is not None:- preflight_resolution = await preflight_credential_pause(ctx, stream, copilot_config)- if preflight_resolution is None:- return _build_request_policy_clarification_result(- request_policy,- prior_global_llm_context=global_llm_context,- prior_workflow_yaml=chat_request.workflow_yaml,- ctx=ctx,- )+ return _build_request_policy_clarification_result(+ request_policy,+ prior_global_llm_context=global_llm_context,+ prior_workflow_yaml=chat_request.workflow_yaml,+ ctx=ctx,+ )if request_policy is None:raise CopilotRequestPolicyMissingError()diff --git a/skyvern/forge/sdk/copilot/browser_ablation.py b/skyvern/forge/sdk/copilot/browser_ablation.pyindex fad974ea5..7587e4ac8 100644--- a/skyvern/forge/sdk/copilot/browser_ablation.py+++ b/skyvern/forge/sdk/copilot/browser_ablation.py@@ -55,6 +55,7 @@ BROWSER_ABLATION_NATIVE_TOOLS = ("inspect_page_for_composition","inspect_locator_matches","fill_credential_field",+ "request_credential",)# Browser ablation keeps the production Copilot browser aliases, then projects the missing# multi-page capabilities from the app registry. This avoids both a second handwritten browserdiff --git a/skyvern/forge/sdk/copilot/context.py b/skyvern/forge/sdk/copilot/context.pyindex 72442e7fb..cdc2ba1ad 100644--- a/skyvern/forge/sdk/copilot/context.py+++ b/skyvern/forge/sdk/copilot/context.py@@ -2,6 +2,7 @@from __future__ import annotations+import asyncioimport hashlibimport jsonimport re@@ -827,9 +828,19 @@ class CopilotContext(AgentContext):last_run_skipped_unbound_credentials: bool = Falseclient_supports_credential_pause: bool = Falsecredential_pause_used: bool = False+ # True only while a card is on screen. credential_pause_used stays true for the rest of the+ # turn once one has been raised, which cannot tell a concurrent sibling ask from a later one.+ credential_ask_in_flight: bool = False+ # A tool ask the user did not answer with a credential spends the one-card budget on a guess.+ # A run that then hits a real login wall has evidence the guess did not, so it gets the budget+ # back once.+ credential_pause_reaskable_by_run: bool = Falsecopilot_credential_pause_seconds: float = 0.0credential_pause_outcome: str | None = Nonecredential_pause_connected_credential_id: str | None = None+ # Set while a ``request_credential`` ask is open, so tool calls issued alongside it in the same+ # model response wait for the user's answer instead of racing it.+ credential_pause_settled: asyncio.Event | None = None# Preserve the immutable turn-open document because ``workflow_yaml`` is# reassigned after every accepted update in the same agent turn.google_connection_turn_start_workflow_yaml: str | None = field(init=False, default=None)diff --git a/skyvern/forge/sdk/copilot/credential_pause.py b/skyvern/forge/sdk/copilot/credential_pause.pyindex 346950399..5c1adf017 100644--- a/skyvern/forge/sdk/copilot/credential_pause.py+++ b/skyvern/forge/sdk/copilot/credential_pause.py@@ -1,8 +1,9 @@"""Mid-loop pause for copilot BUILD turns blocked on a missing credential.-Parks between ``Runner.run_streamed`` iterations at the enforcement finalize-seam (see ``run_with_enforcement``) so the SSE connection stays open while-the frontend surfaces a credential-connect card. Resume transport is a+Parks either inside the ``request_credential`` tool call the model makes, or+between ``Runner.run_streamed`` iterations at the enforcement finalize seam+(see ``run_with_enforcement``) for the run-derived asks, so the SSE connection+stays open while the frontend surfaces a credential-connect card. Resume transport is aper-turn Redis flag polled directly by the paused coroutine -- the inverse ofthe ``/workflow/copilot/cancel`` sidecar watcher, since here the paused loopitself is the poller rather than a task racing the handler.@@ -23,6 +24,8 @@ import jsonimport reimport secretsimport time+from collections.abc import Iterator+from contextlib import contextmanagerfrom dataclasses import dataclassfrom datetime import datetime, timedelta, timezonefrom http import HTTPStatus@@ -45,8 +48,6 @@ from skyvern.forge.sdk.schemas.workflow_copilot import (if TYPE_CHECKING:from agents.result import RunResultStreaming- from skyvern.forge.sdk.copilot.context import CopilotContext-# Importing the routes package at module scope pulls in workflow_copilot.py -># agent.py -> enforcement.py, which imports this module -> circular import.from skyvern.forge.sdk.core.event_source_stream import EventSourceStream@@ -244,14 +245,6 @@ def credential_pause_reason(ctx: Any) -> str | None:and policy.raw_secret_detectedand policy.raw_secret_handling == "redacted_draft")- if isinstance(policy, RequestPolicy) and (- policy.clarification_reason == "login_credentials_unresolved"- # Every ask the credential card can answer resumes through the same typed contract, so- # the reason literal no longer distinguishes them -- `card_answerable` does.- or (policy.requires_user_clarification and policy.credential_ask_card_answerable)- ):- return "login_credentials_unresolved"-if getattr(ctx, "last_run_skipped_unbound_credentials", False) and not raw_secret_redacted_draft:# This is a concrete run result, not a policy or classifier verdict. Preserve it# even when legacy context labels the request as skip_test.@@ -273,14 +266,10 @@ def credential_pause_reason(ctx: Any) -> str | None:return None-def credential_pause_would_fire(ctx: Any, copilot_config: CopilotConfig | None) -> bool:- """Synchronous subset of maybe_credential_pause's guards.+def credential_pause_transport_ready(ctx: Any, copilot_config: CopilotConfig | None) -> bool:+ """Whether a card can be shown at all this turn, independent of what is asking for one.- Called from both here and enforcement.py's enforcement_decision so the two- can't drift: enforcement pre-empts hygiene nudges based on this same- prediction, and a client/kill-switch/latch mismatch between the two would- either suppress nudges for a pause that will never fire, or let a nudge- race a pause that will. Excludes the async-only checks (stream disconnect).+ Excludes the async-only checks (stream disconnect)."""return (copilot_config is not None@@ -290,17 +279,16 @@ def credential_pause_would_fire(ctx: Any, copilot_config: CopilotConfig | None)# A same-process-only cache (LocalCache) can't coordinate the poller with a# /credential-response POST that may land on a different worker -- gate on a# cache that's explicitly known to be shared (Redis) rather than merely non-None.- and getattr(getattr(app, "CACHE", None), "is_shared", False)- and credential_pause_reason(ctx) is not None+ and bool(getattr(getattr(app, "CACHE", None), "is_shared", False)))-def _defang(text: str) -> str:+def defang_card_text(text: str) -> str:return re.sub(r"\s+", " ", text).replace('"', "").strip()[:200]def _bind_connected_credential_origin(policy: RequestPolicy, credential: Credential) -> str | None:- """Stamp the server-held origin this ask was formed against, so a card-created credential with+ """Stamp the origin this ask was formed against, so a card-created credential withno ``tested_url`` still has an intended origin at the fill seam. Written directly rather thanthrough ``_record_live_page_admission``, which skips already-resolved ids and would stampnothing here.@@ -336,7 +324,6 @@ def _apply_connected_credential_to_policy(ctx: Any, policy: RequestPolicy, credeadmitted_url = _bind_connected_credential_origin(policy, credential)LOG.info("copilot_credential_pause_connected",- card_answerable=policy.credential_ask_card_answerable,credential_id=credential.credential_id,bound_origin=loggable_origin(admitted_url) if admitted_url else None,)@@ -366,7 +353,7 @@ def _assemble_resume_messages(ctx: Any, text: str) -> list[dict[str, Any]]:def _connected_resume_text(credential: Credential) -> str:- safe_name = _defang(credential.name)+ safe_name = defang_card_text(credential.name)return (f"The user connected saved credential {safe_name} ({credential.credential_id}) via the credential card. ""Bind it as the credential parameter and continue the build; run the blocks that were skipped or failed "@@ -428,27 +415,57 @@ async def _wait_for_credential_response(return None+def _reschedule_stream_deadline(deadline: asyncio.Timeout, when: float | None) -> None:+ try:+ deadline.reschedule(when)+ except RuntimeError:+ # The owning ``asyncio.timeout`` block has already exited -- the turn was cancelled or torn+ # down while the card was open -- so there is no deadline left to move.+ LOG.info("copilot_credential_pause_deadline_reschedule_skipped")+++@contextmanager+def _stream_deadline_suspended(ctx: Any) -> Iterator[None]:+ """Hold off the turn's model-stream deadline while the user answers the card, then give it back+ the time the answer took; the wait itself is bounded by the pause timeout."""+ deadline = getattr(ctx, "model_stream_deadline", None)+ when = deadline.when() if deadline is not None else None+ if deadline is None or when is None:+ yield+ return+ loop = asyncio.get_running_loop()+ start = loop.time()+ _reschedule_stream_deadline(deadline, None)+ try:+ yield+ finally:+ _reschedule_stream_deadline(deadline, when + (loop.time() - start))++async def _run_credential_pause(ctx: Any,message: str,stream: EventSourceStream,copilot_config: CopilotConfig,+ *,+ reason: str,+ login_page_urls: list[str],) -> CredentialPauseResolution | None:"""Send the credential card and wait for the user's decision.Returns the resolution, or None to let the caller proceed without one(kill-switch off, client can't render the frame, already paused once this- turn, no cache configured or not shared across workers, client gone, no- typed signal fired, or the wait timed out).+ turn, no cache configured or not shared across workers, client gone, or+ the wait timed out)."""- if not credential_pause_would_fire(ctx, copilot_config):+ if not credential_pause_transport_ready(ctx, copilot_config):return None# Predicted true (the sync guard chain passed) but bailing below anyway --# latch it now so this iteration can't loop back into the same prediction,# and tag the outcome "declined" (distinct from "timeout") so the caller# knows no frame was ever sent and can fall back to a normal nudge instead- # of a premature finalize. credential_pause_would_fire's own docstring notes- # it excludes the async-only disconnect check, which is exactly the gap here.+ # of a premature finalize. credential_pause_transport_ready's own docstring+ # notes it excludes the async-only disconnect check, which is the gap here.ctx.credential_pause_used = Truecache = getattr(app, "CACHE", None)if cache is None:@@ -457,18 +474,10 @@ async def _run_credential_pause(if await stream.is_disconnected():ctx.credential_pause_outcome = "declined"return None- reason = credential_pause_reason(ctx)- if reason is None:- ctx.credential_pause_outcome = "declined"- return None-policy = getattr(ctx, "request_policy", None)- login_page_urls = list(policy.login_page_urls) if isinstance(policy, RequestPolicy) else []# The FE credential card fetches the full org list itself; these ride the frame as `credential_refs`# and seed the picker's "Suggested" group (pinned first), so the user still sees the full list.- credential_refs: list[str] = []- if isinstance(policy, RequestPolicy):- credential_refs = list(policy.credential_ask_candidate_ids or policy.credential_refs)+ credential_refs = list(policy.credential_refs) if isinstance(policy, RequestPolicy) else []timeout_seconds = copilot_config.credential_pause_timeout_secondsnow = datetime.now(timezone.utc)@@ -538,7 +547,8 @@ async def _run_credential_pause(start = time.monotonic()try:- resolution = await _wait_for_credential_response(response_key, ctx, stream, timeout_seconds)+ with _stream_deadline_suspended(ctx):+ resolution = await _wait_for_credential_response(response_key, ctx, stream, timeout_seconds)except BaseException:# Covers CancelledError (a direct BaseException subclass, not Exception)# alongside any unexpected failure in the wait loop itself -- the frame's@@ -575,28 +585,103 @@ async def _run_credential_pause(return resolution+def arm_credential_pause_gate(ctx: Any) -> None:+ """Close the gate as soon as a model response is known to contain a ``request_credential`` call.++ Arming inside the tool coroutine would be too late: the SDK runs one response's tool calls as+ concurrent tasks, so a run tool scheduled first would pass an unarmed gate.+ """+ settled = getattr(ctx, "credential_pause_settled", None)+ if settled is None or settled.is_set():+ ctx.credential_pause_settled = asyncio.Event()+++def release_credential_pause_gate(ctx: Any) -> None:+ settled = getattr(ctx, "credential_pause_settled", None)+ if settled is not None:+ settled.set()+++async def request_credential_pause(+ ctx: Any,+ *,+ login_page_url: str,+ message: str,+ stream: EventSourceStream,+ copilot_config: CopilotConfig,+) -> CredentialPauseResolution | None:+ """Raise the card from the model's own ``request_credential`` call and wait, inline, for the+ answer, so tool calls the model issued alongside it can await ``credential_pause_settled``."""+ arm_credential_pause_gate(ctx)+ ctx.credential_ask_in_flight = True+ try:+ resolution = await _run_credential_pause(+ ctx,+ message,+ stream,+ copilot_config,+ reason="login_credentials_unresolved",+ login_page_urls=[login_page_url],+ )+ ctx.credential_pause_reaskable_by_run = resolution is None or resolution.action != "connected"+ return resolution+ finally:+ ctx.credential_ask_in_flight = False+ release_credential_pause_gate(ctx)+++async def await_pending_credential_pause(ctx: Any) -> None:+ """Wait out a ``request_credential`` ask that is still open, so a run tool the model called in+ parallel with it cannot start a run before the user has answered. Draft edits are not gated:+ they neither run nor sign in."""+ settled = getattr(ctx, "credential_pause_settled", None)+ if settled is None:+ return+ # A call the SDK rejects on its arguments arms the gate without ever reaching the handler that+ # releases it, and the stream cannot exit to run the enforcement backstop while this wait is+ # parked inside it. Bound the wait so that strands one tool call rather than the whole turn.+ try:+ await asyncio.wait_for(settled.wait(), settings.WORKFLOW_COPILOT_CREDENTIAL_PAUSE_TIMEOUT_SECONDS + 30)+ except asyncio.TimeoutError:+ LOG.warning("copilot_credential_gate_wait_timed_out")+ settled.set()++async def maybe_credential_pause(ctx: Any,result: RunResultStreaming,stream: EventSourceStream,copilot_config: CopilotConfig,) -> list[dict[str, Any]] | None:- """Pause a finalizing turn that hit a typed mid-build credential ask.+ """Pause a finalizing turn that hit a typed run-derived credential ask.Returns the resume messages to re-enter the loop with, or None to let thecaller finalize normally."""- if not credential_pause_would_fire(ctx, copilot_config):+ reason = credential_pause_reason(ctx)+ if reason is None:+ return None+ # Exactly True, not merely truthy: ctx is Any here, and a partial stand-in returns a truthy+ # object for any attribute, which would hand the budget back on every turn.+ if getattr(ctx, "credential_pause_reaskable_by_run", False) is True:+ # The spent card was a guess the user never answered; this ask has a run behind it. Hand the+ # budget back once, so an unanswered guess cannot silently cost the turn its real card.+ ctx.credential_pause_reaskable_by_run = False+ ctx.credential_pause_used = False+ if not credential_pause_transport_ready(ctx, copilot_config):return None# Local import: same module-load-cycle reason as _assemble_resume_messages.from skyvern.forge.sdk.copilot.enforcement import _parse_normalized_final_responseparsed = _parse_normalized_final_response(result)+ policy = getattr(ctx, "request_policy", None)resolution = await _run_credential_pause(ctx,str((parsed or {}).get("user_response") or ""),stream,copilot_config,+ reason=reason,+ login_page_urls=list(policy.login_page_urls) if isinstance(policy, RequestPolicy) else [],)if resolution is None:return None@@ -606,31 +691,3 @@ async def maybe_credential_pause(if credential is None:return Nonereturn _assemble_resume_messages(ctx, _connected_resume_text(credential))---async def preflight_credential_pause(- ctx: CopilotContext,- stream: EventSourceStream,- copilot_config: CopilotConfig,-) -> CredentialPauseResolution | None:- """Ask for a credential before the agent loop starts, so no build precedes the ask.-- Both decisions clear the clarification block the request policy raised, so the- caller falls through into a normal run instead of the terminal clarify; a- declined turn must not keep a reason that would re-surface the card CTA.- """- policy = ctx.request_policy- question = (policy.clarification_question or "") if policy is not None else ""- resolution = await _run_credential_pause(ctx, question, stream, copilot_config)- if resolution is None or policy is None:- return resolution- policy.user_response_policy = "proceed"- # Record the explicit product-owned resume. These are compatibility facts for- # the credential flow, not generic update/run permissions.- policy.allow_update_workflow = True- policy.allow_run_blocks = True- if resolution.action == "skip":- policy.allow_missing_credentials_in_draft = True- policy.requires_user_clarification = False- policy.clarification_reason = "none"- return resolutiondiff --git a/skyvern/forge/sdk/copilot/enforcement.py b/skyvern/forge/sdk/copilot/enforcement.pyindex b24a7f866..d268b2866 100644--- a/skyvern/forge/sdk/copilot/enforcement.py+++ b/skyvern/forge/sdk/copilot/enforcement.py@@ -45,7 +45,7 @@ from skyvern.forge.sdk.copilot.config import (CopilotConfig,)from skyvern.forge.sdk.copilot.credential_fill_fields import LIVE_SCOUT_CREDENTIAL_FIELDS-from skyvern.forge.sdk.copilot.credential_pause import maybe_credential_pause+from skyvern.forge.sdk.copilot.credential_pause import maybe_credential_pause, release_credential_pause_gatefrom skyvern.forge.sdk.copilot.diagnosis_repair_contract import RepairNextActionfrom skyvern.forge.sdk.copilot.narration import TransitionKindfrom skyvern.forge.sdk.copilot.output_extraction_plan import (@@ -1160,13 +1160,15 @@ async def _run_streamed_with_deadline(against ``TOTAL_TIMEOUT_SECONDS``.The top-of-loop elapsed check only fires between iterations; a- long-running tool inside ``Runner.run_streamed`` needs ``wait_for``+ long-running tool inside ``Runner.run_streamed`` needs this deadlineto raise ``CopilotTotalTimeoutError`` mid-tool so the caller's``_build_exit_result`` path emits a non-empty REPLY before the- client's own transport timeout closes the stream.+ client's own transport timeout closes the stream. The live timeout is+ published on the context so a tool that parks on a user decision (the+ credential card) can suspend it for the length of that wait.- ``MIN_DEADLINE_REMAINING_SECONDS`` floors ``remaining`` so- ``wait_for(timeout=0)`` never panics on an already-spent budget.+ ``MIN_DEADLINE_REMAINING_SECONDS`` floors ``remaining`` so a zero+ timeout never panics on an already-spent budget."""elapsed = _elapsed_run_seconds(ctx, start_time)remaining = max(MIN_DEADLINE_REMAINING_SECONDS, TOTAL_TIMEOUT_SECONDS - elapsed)@@ -1174,8 +1176,17 @@ async def _run_streamed_with_deadline(result = Runner.run_streamed(agent, input=current_input, context=ctx, session=session, **runner_kwargs)try:try:- await asyncio.wait_for(streaming_adapter.stream_to_sse(result, tracked_stream, ctx), timeout=remaining)+ async with asyncio.timeout(remaining) as deadline:+ ctx.model_stream_deadline = deadline+ await streaming_adapter.stream_to_sse(result, tracked_stream, ctx)finally:+ ctx.model_stream_deadline = None+ # A request_credential call the SDK rejected before its handler ran leaves the gate+ # armed with no releaser, and arm_credential_pause_gate skips a stranded Event, so+ # every later response's run tools would park on it. A rejected call never sets the+ # in-flight flag, so this still cannot open the gate under a card that is on screen.+ if not ctx.credential_ask_in_flight:+ release_credential_pause_gate(ctx)_accumulate_usage(result, ctx)except TimeoutError:_mark_copilot_total_timeout(ctx, elapsed_seconds=_elapsed_run_seconds(ctx, start_time), iteration=iteration)diff --git a/skyvern/forge/sdk/copilot/hooks.py b/skyvern/forge/sdk/copilot/hooks.pyindex fae65540a..8d913e6c5 100644--- a/skyvern/forge/sdk/copilot/hooks.py+++ b/skyvern/forge/sdk/copilot/hooks.py@@ -8,12 +8,13 @@ from typing import TYPE_CHECKING, Anyimport structlogfrom agents.agent import Agent, AgentBase-from agents.items import TResponseInputItem+from agents.items import ModelResponse, TResponseInputItemfrom agents.lifecycle import RunHooksBasefrom agents.run_context import AgentHookContext, RunContextWrapperfrom agents.tool import Toolfrom skyvern.forge.sdk.copilot.browser_ablation import prompt_sha256+from skyvern.forge.sdk.copilot.credential_pause import arm_credential_pause_gatefrom skyvern.forge.sdk.copilot.enforcement import (gate_decision_trace_fields,outcome_fully_verified,@@ -94,6 +95,16 @@ class CopilotRunHooks(RunHooksBase):**_copilot_log_fields(self._ctx),)+ async def on_llm_end(self, context: RunContextWrapper, agent: Agent, response: ModelResponse) -> None:+ try:+ if any(getattr(item, "name", None) == "request_credential" for item in response.output):+ arm_credential_pause_gate(self._ctx)+ except Exception:+ LOG.warning(+ "CopilotRunHooks.on_llm_end credential gate arming failed",+ **_copilot_log_fields(self._ctx),+ )+async def on_agent_start(self, context: AgentHookContext, agent: AgentBase) -> None:try:self._ctx.enforcement_pass_count += 1diff --git a/skyvern/forge/sdk/copilot/narration.py b/skyvern/forge/sdk/copilot/narration.pyindex 98955718d..b02c2899b 100644--- a/skyvern/forge/sdk/copilot/narration.py+++ b/skyvern/forge/sdk/copilot/narration.py@@ -119,6 +119,7 @@ _TOOL_ACTIVITY_DISPLAY_LABELS = {"edit_block": "Editing block","add_block": "Adding block","delete_block": "Deleting block",+ "request_credential": "Requesting a credential",}# Tools whose label names the block they operate on, read from the tool's owndiff --git a/skyvern/forge/sdk/copilot/output_utils.py b/skyvern/forge/sdk/copilot/output_utils.pyindex 37e6a3e77..5e5dbf513 100644--- a/skyvern/forge/sdk/copilot/output_utils.py+++ b/skyvern/forge/sdk/copilot/output_utils.py@@ -1726,6 +1726,7 @@ _USER_FACING_EMPTY_SUCCESS_TOOLS: frozenset[str] = frozenset("evaluate","select_option","list_credentials",+ "request_credential",# The server-authored display label already names the operation and its# target block; a bare "OK" summary would render instead of it."edit_block",diff --git a/skyvern/forge/sdk/copilot/request_policy.py b/skyvern/forge/sdk/copilot/request_policy.pyindex a6f39c0f4..5987f9183 100644--- a/skyvern/forge/sdk/copilot/request_policy.py+++ b/skyvern/forge/sdk/copilot/request_policy.py@@ -454,8 +454,9 @@ async def _screen_raw_secret_safety(_VALID_CLARIFICATION_REASONS: frozenset[ClarificationReason] = frozenset(get_args(ClarificationReason))-# Only deterministic post-resolution code may mint these; a classifier emission would-# skip the concrete-target and credential-reachability checks the reason stands for.+# The server owns these in model-authored JSON. safety_screen_unavailable is minted+# deterministically; login_credentials_unresolved names a pause frame, and a model-emitted one+# would still stamp a credential CTA on the terminal reply._DETERMINISTIC_ONLY_CLARIFICATION_REASONS: frozenset[ClarificationReason] = frozenset({"login_credentials_unresolved", "safety_screen_unavailable"})@@ -481,11 +482,6 @@ _PRE_RESOLUTION_CLARIFICATION_REASONS = {"missing_conditional_condition","missing_target_context",}-# A failed credential lookup under explicit login intent is the same condition-# login_credentials_unresolved names, so it may be upgraded; other planes may not.-_LOGIN_CREDENTIAL_OVERRIDABLE_REASONS: frozenset[ClarificationReason] = frozenset(- {"none", "credential_name_unresolved"}-)_REASONS_OVERRIDDEN_BY_CREDENTIAL_REFS = {"ambiguous_loop_edit","invalid_conditional_container",@@ -510,22 +506,7 @@ SAFETY_SCREEN_UNAVAILABLE_QUESTION = ("I couldn't finish safety screening on that message, so I never read it. ""That's a problem on my side, not something wrong with what you sent — please send it again.")-_SAVED_CREDENTIAL_NAME_QUESTION_STABLE_PREFIX = "Which saved credential should I use? Please provide the exact credential name or a credential ID beginning with cred_."-_SAVED_CREDENTIAL_NAME_QUESTION = f"{_SAVED_CREDENTIAL_NAME_QUESTION_STABLE_PREFIX} {_CREDENTIALS_UI_DIRECTIONS}"-_LOGIN_CREDENTIAL_QUESTION_STABLE_PREFIX = (- "This request needs to sign in, and no saved credential for it is available yet. "- "Please connect one, or reply with its exact saved credential name or a credential ID beginning with cred_."-)-_LOGIN_CREDENTIAL_QUESTION = f"{_LOGIN_CREDENTIAL_QUESTION_STABLE_PREFIX} {_CREDENTIALS_UI_DIRECTIONS}"-_STORED_CREDENTIAL_URL_QUESTION_STABLE_PREFIX = (- "Which website or login page should I use to look up the stored credential?"-)-_STORED_CREDENTIAL_URL_QUESTION = f"{_STORED_CREDENTIAL_URL_QUESTION_STABLE_PREFIX} {_CREDENTIALS_UI_DIRECTIONS}"_AMBIGUOUS_URL_CREDENTIAL_QUESTION = "I found multiple stored credentials for that login page. Which one should I use?"-_AMBIGUOUS_URLLESS_CREDENTIAL_QUESTION = (- "I found multiple saved credentials, and none of them is bound to that login page. Which one should I use?"-)-_SIGNIN_EMAIL_QUESTION = "Which email address should I sign in with?"_CREDENTIAL_ID_RE = re.compile(r"\bcred_[A-Za-z0-9][A-Za-z0-9_-]*\b")# A credential ID typed with the wrong separator (`cred 530…`, `cred-530…`). The# digit-only body and length floor keep this off prose like `cred and the password`.@@ -932,11 +913,9 @@ class RequestPolicy:raw_secret_safety_exonerated_citation_count: int = 0raw_secret_safety_latency_ms: float = 0.0clarification_reason: ClarificationReason = "none"- # `clarification_reason` cannot say this on its own: credential_name_unresolved is also raised- # by raw-secret, invention and invalid-id asks the credential card cannot answer.- credential_ask_card_answerable: bool = False- # The server-held login page URLs this ask was formed against; the only origin source the- # connected resume may bind from.+ # The login page URLs a tool ask was formed against. A model-supplied URL reaches this list only+ # after it matched a site in ``user_provided_site_urls``; the connected resume falls back to the+ # classifier-authored ``login_page_urls`` when it is empty, which carries no such grounding.credential_ask_login_page_urls: list[str] = field(default_factory=list)# Credentials this turn resolved from an explicit user reference — an exact saved name or a# cred_ id — as distinct from approvals carried in from earlier turns. Naming a credential@@ -948,7 +927,6 @@ class RequestPolicy:user_provided_site_urls: list[str] = field(default_factory=list)# Which user message (1-based) each of those URLs came from, so a release records its provenance.user_site_url_sources: dict[str, int] = field(default_factory=dict)- credential_ask_candidate_ids: list[str] = field(default_factory=list)existing_workflow_credential_ids: list[str] = field(default_factory=list)# Read from the saved workflow row, never from the submitted YAML. The submission is the live# canvas, which carries a copilot proposal the user has not accepted, so it cannot grant a run.diff --git a/skyvern/forge/sdk/copilot/runtime.py b/skyvern/forge/sdk/copilot/runtime.pyindex cea8814a4..6632d5d75 100644--- a/skyvern/forge/sdk/copilot/runtime.py+++ b/skyvern/forge/sdk/copilot/runtime.py@@ -359,6 +359,9 @@ class AgentContext:turn_origin: TurnOrigin = TurnOrigin.interactiveinjected_browser_state: BrowserState | None = Noneheal_workflow_run_id: str | None = None+ # The deadline the current model stream runs under, published by the enforcement loop so a tool+ # that parks on a user decision can suspend it instead of being cancelled mid-question.+ model_stream_deadline: asyncio.Timeout | None = None# The streaming adapter narrates any context it is handed, so the design-phase latches live here# rather than on the copilot subclass it is annotated for.design_start_emitted: bool = Falsediff --git a/skyvern/forge/sdk/copilot/tools/__init__.py b/skyvern/forge/sdk/copilot/tools/__init__.pyindex f41627114..91e0cabdd 100644--- a/skyvern/forge/sdk/copilot/tools/__init__.py+++ b/skyvern/forge/sdk/copilot/tools/__init__.py@@ -24,6 +24,10 @@ from skyvern.forge.sdk.copilot.composition_evidence import ()from skyvern.forge.sdk.copilot.composition_evidence import workflow_target_url as workflow_target_urlfrom skyvern.forge.sdk.copilot.context import CopilotContext+from skyvern.forge.sdk.copilot.credential_pause import (+ await_pending_credential_pause,+ release_credential_pause_gate,+)from skyvern.forge.sdk.copilot.enforcement import requested_output_paths_for_derivationfrom skyvern.forge.sdk.copilot.loop_detection import record_tool_step_result_for_ctxfrom skyvern.forge.sdk.copilot.output_extraction_plan import (@@ -111,6 +115,7 @@ from .credential_fill import _credential_fill_authority_error as _credential_filfrom .credential_fill import _credential_fill_prerequisite_error as _credential_fill_prerequisite_errorfrom .credential_fill import (_fill_credential_field_impl,+ _request_credential,)from .credential_fill import _resolve_credential_fill_value as _resolve_credential_fill_valuefrom .credentials import _credential_id_misbinding_findings as _credential_id_misbinding_findings@@ -467,6 +472,7 @@ async def edit_block_and_run_tool(credential and reply with the credential name; do not build or run with the raw value."""copilot_ctx = ctx.context+ await await_pending_credential_pause(copilot_ctx)copilot_ctx.completion_verification_result = Nonehandler_start = time.monotonic()requested_labels = list(block_labels) if block_labels else [label]@@ -793,6 +799,35 @@ async def list_credentials_tool(return json.dumps(sanitized)+@function_tool(name_override="request_credential")+async def request_credential_tool(ctx: RunContextWrapper, login_page_url: str, reason: str) -> str:+ """Ask the user, in chat, to add or pick a saved credential for a sign-in page.++ Use this instead of writing a prose question when the turn needs a login and no saved+ credential covers that site. `login_page_url` must be a page on a site the user themselves+ provided in this chat; `reason` is one sentence shown to the user saying why the login is+ needed. The call waits for the user's answer and comes back `connected` with the credential+ to bind, `skipped`, `unanswered`, or `unavailable` — follow the `next` or `fallback` it+ carries. One ask per turn.+ """+ copilot_ctx = ctx.context+ arguments = {"login_page_url": login_page_url, "reason": reason}+ result: dict[str, Any] = {}+ try:+ authority_error = _authority_tool_error(copilot_ctx, "request_credential")+ if authority_error:+ result = {"ok": False, "error": authority_error}+ else:+ result = await _request_credential(login_page_url, reason, copilot_ctx)+ finally:+ # A card on screen right now owns the gate; this call must not open it for one it never+ # raised. Every other exit has to release, including a repeat ask in a later response.+ if not copilot_ctx.credential_ask_in_flight:+ release_credential_pause_gate(copilot_ctx)+ record_tool_step_result_for_ctx(copilot_ctx, "request_credential", arguments, result)+ return json.dumps(result)++@function_tool(name_override="list_integrations")async def list_integrations_tool(ctx: RunContextWrapper) -> str:"""List the organization's connected Google and Microsoft accounts (metadata only —@@ -888,6 +923,7 @@ async def run_blocks_tool(evidence instead of retrying guessed URL params or page structure."""copilot_ctx = ctx.context+ await await_pending_credential_pause(copilot_ctx)copilot_ctx.completion_verification_result = Nonehandler_start = time.monotonic()arguments = {"block_labels": block_labels, "parameters": parameters or {}}@@ -1032,6 +1068,7 @@ async def update_and_run_blocks_tool(do not compose a click against a control observed as disabled."""copilot_ctx = ctx.context+ await await_pending_credential_pause(copilot_ctx)copilot_ctx.completion_verification_result = Nonehandler_start = time.monotonic()serialized_code_artifact_metadata: object = _code_artifact_metadata_as_tool_argument(code_artifact_metadata)@@ -1499,4 +1536,5 @@ NATIVE_TOOLS = [inspect_page_for_composition_tool,inspect_locator_matches_tool,fill_credential_field_tool,+ request_credential_tool,]diff --git a/skyvern/forge/sdk/copilot/tools/credential_fill.py b/skyvern/forge/sdk/copilot/tools/credential_fill.pyindex 13fcc03d1..acd2a0321 100644--- a/skyvern/forge/sdk/copilot/tools/credential_fill.py+++ b/skyvern/forge/sdk/copilot/tools/credential_fill.py@@ -14,7 +14,13 @@ from skyvern.cli.core.session_manager import get_pagefrom skyvern.forge import appfrom skyvern.forge.sdk.browser_action_policy import canonicalize_originfrom skyvern.forge.sdk.copilot.config import BlockAuthoringPolicy+from skyvern.forge.sdk.copilot.context import CopilotContextfrom skyvern.forge.sdk.copilot.credential_fill_fields import CREDENTIAL_FILL_FIELDS+from skyvern.forge.sdk.copilot.credential_pause import (+ credential_pause_transport_ready,+ defang_card_text,+ request_credential_pause,+)from skyvern.forge.sdk.copilot.credential_resolution import load_credentials, url_partsfrom skyvern.forge.sdk.copilot.loop_detection import record_tool_step_result_for_ctxfrom skyvern.forge.sdk.copilot.page_identity import safe_page_origin@@ -358,6 +364,87 @@ def _user_provided_site_url_match(policy: RequestPolicy, page_url: str) -> tuplereturn None, False+_CREDENTIAL_CARD_FALLBACK = (+ "Ask the user in prose to add the login on the Credentials page and reply with its exact saved name."+)+++def _unprovided_login_page_error(login_page_url: str) -> str:+ origin = loggable_origin(login_page_url) if login_page_url else "that page"+ return (+ f"No credential can be requested for {origin}: that site has not been named in this chat. "+ "The sign-in page URL has to come from the user before a login can be requested for it."+ )+++async def _request_credential(login_page_url: str, reason: str, copilot_ctx: CopilotContext) -> dict[str, Any]:+ policy = copilot_ctx.request_policy+ if not isinstance(policy, RequestPolicy) or _user_provided_site_url_match(policy, login_page_url)[0] is None:+ return {"ok": False, "error": _unprovided_login_page_error(login_page_url)}++ if copilot_ctx.credential_pause_used:+ return {+ "ok": True,+ "status": "already_asked",+ "outcome": copilot_ctx.credential_pause_outcome or "unanswered",+ "next": "Continue without re-asking this turn.",+ }++ config = copilot_ctx.copilot_config+ if config is None or not credential_pause_transport_ready(copilot_ctx, config):+ LOG.info(+ "copilot_credential_card_unavailable",+ flag_enabled=config is not None and config.credential_pause_enabled,+ client_supports=copilot_ctx.client_supports_credential_pause,+ shared_cache=getattr(getattr(app, "CACHE", None), "is_shared", False),+ )+ return {+ "ok": True,+ "status": "unavailable",+ "detail": "The in-chat credential card cannot be shown on this turn.",+ "fallback": _CREDENTIAL_CARD_FALLBACK,+ }++ policy.credential_ask_login_page_urls = [login_page_url]+ resolution = await request_credential_pause(+ copilot_ctx,+ login_page_url=login_page_url,+ message=defang_card_text(reason),+ stream=copilot_ctx.stream,+ copilot_config=config,+ )+ credential = resolution.credential if resolution is not None else None+ if resolution is None or (resolution.action == "connected" and credential is None):+ return {+ "ok": True,+ "status": "unanswered",+ "outcome": copilot_ctx.credential_pause_outcome or "timeout",+ "next": (+ "The user did not answer the card. Continue without the credential: keep the credential "+ "parameter placeholder in the draft and do not ask again this turn."+ ),+ }+ if credential is None:+ return {+ "ok": True,+ "status": "skipped",+ "next": (+ "The user chose not to connect a credential now. Keep the credential parameter placeholder "+ "in the draft, do not ask again this turn, and say a test run may stop at the login step."+ ),+ }+ return {+ "ok": True,+ "status": "connected",+ "credential_id": credential.credential_id,+ "credential_name": credential.name,+ "next": (+ "Bind this credential as the workflow's credential parameter and continue the build; run the "+ "blocks that were waiting on the login."+ ),+ }++def _request_settled_credential(policy: RequestPolicy, credential_id: str) -> bool:"""A non-model signal already answered which credential: the user named it this turn, or it isthe only credential resolved for this request (e.g. the one card answer, carried)."""diff --git a/skyvern/forge/sdk/copilot/tools/credentials.py b/skyvern/forge/sdk/copilot/tools/credentials.pyindex 17bf06e36..d792f9986 100644--- a/skyvern/forge/sdk/copilot/tools/credentials.py+++ b/skyvern/forge/sdk/copilot/tools/credentials.py@@ -430,9 +430,10 @@ def _missing_credential_reference_tool_error(missing_credential_ids: list[str])was_word = "was" if len(missing_credential_ids) == 1 else "were"return (f"The credential {id_word} {formatted_ids} {was_word} not found in this organization. "- "Stop before creating, updating, or running the workflow. Ask the user to provide/select a valid "- "credential ID, create the credential in the Credentials UI and return with its ID, or explicitly "- "choose an unvalidated draft workflow that will not be run until credentials are available."+ "Stop before creating, updating, or running the workflow. Call `request_credential` with the sign-in "+ "page URL so the user can add or pick one in chat, or, failing that, ask them to create it in the "+ "Credentials UI and return with its ID, or explicitly choose an unvalidated draft workflow that will "+ "not be run until credentials are available.")diff --git a/tests/unit/test_copilot_credential_pause.py b/tests/unit/test_copilot_credential_pause.pyindex 9c469251a..0a984e9f0 100644--- a/tests/unit/test_copilot_credential_pause.py+++ b/tests/unit/test_copilot_credential_pause.py@@ -35,7 +35,7 @@ from skyvern.config import settingsfrom skyvern.forge import appfrom skyvern.forge.sdk.cache.base import NoopLockfrom skyvern.forge.sdk.copilot import credential_pause as credential_pause_module-from skyvern.forge.sdk.copilot.agent import RequestPolicyGuardrailInputs+from skyvern.forge.sdk.copilot import tools as tools_modulefrom skyvern.forge.sdk.copilot.config import CopilotConfigfrom skyvern.forge.sdk.copilot.context import (CopilotContext,@@ -46,11 +46,11 @@ from skyvern.forge.sdk.copilot.credential_pause import (CredentialPauseRejection,CredentialPauseResolution,_encode_active_pause,+ await_pending_credential_pause,credential_pause_active_key,credential_response_cache_key,encode_credential_response,maybe_credential_pause,- preflight_credential_pause,resolve_credential_pause,)from skyvern.forge.sdk.copilot.diagnosis_repair_contract import (@@ -69,22 +69,21 @@ from skyvern.forge.sdk.copilot.enforcement import (enforcement_decision,run_with_enforcement,)+from skyvern.forge.sdk.copilot.hooks import CopilotRunHooksfrom skyvern.forge.sdk.copilot.request_policy import (- CREDENTIAL_PROMPT_CLARIFICATION_REASONS,- ClarificationReason,+ _CREDENTIALS_UI_DIRECTIONS,RequestPolicy,credential_prompt_reason,)from skyvern.forge.sdk.copilot.tools._shared import TOTAL_TIMEOUT_SECONDS, _copilot_seconds_remaining+from skyvern.forge.sdk.copilot.tools.credential_fill import _request_credential+from skyvern.forge.sdk.copilot.turn_origin import TurnOriginfrom skyvern.forge.sdk.routes.workflow_copilot import (WorkflowCopilotCredentialResponseRequest,workflow_copilot_credential_response,)from skyvern.forge.sdk.schemas.credentials import Credential, CredentialType, CredentialVaultType-from skyvern.forge.sdk.schemas.workflow_copilot import (- WorkflowCopilotCredentialRequiredUpdate,- WorkflowCopilotStreamMessageType,-)+from skyvern.forge.sdk.schemas.workflow_copilot import WorkflowCopilotStreamMessageTypefrom tests.unit.conftest import make_copilot_context@@ -286,6 +285,50 @@ def test_reason_none_when_no_signals_present() -> None:# ---------------------------------------------------------------------------+async def test_a_run_that_hits_a_login_still_gets_a_card_after_an_unanswered_tool_ask(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The one-card budget is spent when the tool asks on a guess. A run that then hits a real login+ has evidence the guess did not, so the guess must not cost the turn its real card."""+ ctx = make_copilot_context()+ ctx.organization_id = "org-1"+ ctx.turn_id = "turn-1"+ ctx.client_supports_credential_pause = True+ ctx.workflow_copilot_chat_id = "chat-1"+ ctx.last_run_skipped_unbound_credentials = True+ ctx.request_policy = RequestPolicy()+ # State left by a tool ask the user skipped.+ ctx.credential_pause_used = True+ ctx.credential_pause_reaskable_by_run = True++ cache = _FakeCache()+ cache.store[credential_response_cache_key("org-1", "chat-1", "turn-1")] = encode_credential_response(+ "connected", "cred_1"+ )+ monkeypatch.setattr(credential_pause_module.app._inst, "CACHE", cache, raising=False)+ monkeypatch.setattr(+ credential_pause_module.app,+ "DATABASE",+ SimpleNamespace(+ credentials=SimpleNamespace(get_credentials_by_ids=AsyncMock(return_value=[_make_credential()]))+ ),+ )+ monkeypatch.setattr(credential_pause_module, "CREDENTIAL_RESPONSE_POLL_SECONDS", 0.01)++ resume_msgs = await maybe_credential_pause(+ ctx,+ _fake_result(),+ _make_stream(),+ CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=5),+ )++ assert resume_msgs is not None+ assert ctx.credential_pause_outcome == "connected"+ # Handed back once only, so the turn cannot loop on repeated cards.+ assert ctx.credential_pause_reaskable_by_run is False++@pytest.mark.asyncioasync def test_connected_action_mutates_policy_and_resolves(monkeypatch: pytest.MonkeyPatch) -> None:ctx = make_copilot_context()@@ -547,7 +590,7 @@ async def test_disconnect_racing_the_send_itself_declines_without_waiting(monkeyasync def test_already_disconnected_before_send_declines_without_sending_a_frame(monkeypatch: pytest.MonkeyPatch,) -> None:- """The predictor (credential_pause_would_fire) excludes the async-only+ """The predictor (credential_pause_transport_ready) excludes the async-onlydisconnect check by design -- a client gone before the frame is even sentmust latch and tag 'declined' (not 'timeout') so the caller can fall backto a normal nudge instead of treating this like a delivered-and-waited pause."""@@ -1319,23 +1362,23 @@ def test_copilot_seconds_remaining_credits_pause_time() -> None:# ----------------------------------------------------------------------------def test_would_fire_false_when_client_does_not_support_pause() -> None:+def test_transport_not_ready_when_client_does_not_support_pause() -> None:ctx = make_copilot_context()ctx.last_run_skipped_unbound_credentials = Truectx.request_policy = RequestPolicy()config = CopilotConfig(credential_pause_enabled=True)- assert credential_pause_module.credential_pause_would_fire(ctx, config) is False+ assert credential_pause_module.credential_pause_transport_ready(ctx, config) is False-def test_would_fire_true_once_client_support_is_set() -> None:+def test_transport_ready_once_client_support_is_set() -> None:ctx = make_copilot_context()ctx.client_supports_credential_pause = Truectx.last_run_skipped_unbound_credentials = Truectx.request_policy = RequestPolicy()config = CopilotConfig(credential_pause_enabled=True)- assert credential_pause_module.credential_pause_would_fire(ctx, config) is True+ assert credential_pause_module.credential_pause_transport_ready(ctx, config) is True@pytest.mark.asyncio@@ -1520,125 +1563,42 @@ def test_credential_pause_resolution_defaults_credential_to_none() -> None:assert resolution.credential is None-def _blocked_login_policy() -> RequestPolicy:- """A policy shaped the way build_request_policy leaves an unresolved login ask."""- return RequestPolicy(- clarification_reason="login_credentials_unresolved",- clarification_question="Connect a saved credential to sign in.",- requires_user_clarification=True,- user_response_policy="ask_clarification",- allow_update_workflow=False,- allow_run_blocks=False,- )+def _ask_origin_policy(*ask_login_page_urls: str) -> RequestPolicy:+ return RequestPolicy(credential_ask_login_page_urls=list(ask_login_page_urls))-def _preflight_ctx() -> CopilotContext:+def _named_site_policy(site_url: str = "https://portal.example.com/login") -> RequestPolicy:+ return RequestPolicy(user_provided_site_urls=[site_url])+++def _tool_ctx(monkeypatch: pytest.MonkeyPatch, cache: _FakeCache | None = None) -> CopilotContext:ctx = make_copilot_context()ctx.organization_id = "org-1"ctx.turn_id = "turn-1"ctx.workflow_copilot_chat_id = "chat-1"ctx.client_supports_credential_pause = True- ctx.request_policy = _blocked_login_policy()+ ctx.copilot_config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=5)+ ctx.request_policy = _named_site_policy()+ ctx.stream = _make_stream()+ monkeypatch.setattr(credential_pause_module.app._inst, "CACHE", cache or _FakeCache(), raising=False)+ monkeypatch.setattr(credential_pause_module, "CREDENTIAL_RESPONSE_POLL_SECONDS", 0.01)return ctx-def test_reason_fires_on_unresolved_login_credentials() -> None:- ctx = make_copilot_context()- ctx.request_policy = _blocked_login_policy()-- assert credential_pause_module.credential_pause_reason(ctx) == "login_credentials_unresolved"---def test_reason_does_not_fire_for_a_login_ask_that_resolved_to_a_credential() -> None:- ctx = make_copilot_context()- ctx.request_policy = RequestPolicy(clarification_reason="none")-- assert credential_pause_module.credential_pause_reason(ctx) is None---def _card_answerable_policy(- *,- clarification_reason: ClarificationReason = "credential_name_unresolved",- clarification_question: str = "Which one should I use?",- card_answerable: bool = True,- ask_login_page_urls: list[str] | None = None,-) -> RequestPolicy:- """A disambiguation ask the credential card can answer: a different reason to the login ask."""- return RequestPolicy(- clarification_reason=clarification_reason,- clarification_question=clarification_question,- requires_user_clarification=True,- user_response_policy="ask_clarification",- allow_update_workflow=False,- allow_run_blocks=False,- credential_ask_card_answerable=card_answerable,- credential_ask_candidate_ids=["cred_1", "cred_2"] if card_answerable else [],- credential_ask_login_page_urls=["https://portal.example.com/login"]- if ask_login_page_urls is None- else ask_login_page_urls,- )---def test_reason_fires_on_a_card_answerable_ask_under_a_different_reason() -> None:- ctx = make_copilot_context()- ctx.request_policy = _card_answerable_policy()-- assert credential_pause_module.credential_pause_reason(ctx) == "login_credentials_unresolved"---def test_reason_ignores_a_clarification_the_card_cannot_answer() -> None:- ctx = make_copilot_context()- ctx.request_policy = _card_answerable_policy(clarification_reason="raw_secret", card_answerable=False)-- assert credential_pause_module.credential_pause_reason(ctx) is None---def test_widened_reason_still_builds_a_valid_credential_required_frame() -> None:- ctx = make_copilot_context()- ctx.request_policy = _card_answerable_policy()- reason = credential_pause_module.credential_pause_reason(ctx)-- frame = WorkflowCopilotCredentialRequiredUpdate(- type=WorkflowCopilotStreamMessageType.CREDENTIAL_REQUIRED,- turn_id="turn-1",- workflow_copilot_chat_id="chat-1",- resume_token="rt",- reason=reason or "",- message="Which one should I use?",- login_page_urls=[],- credential_refs=[],- timeout_seconds=5,- expires_at=datetime.now(timezone.utc),- timestamp=datetime.now(timezone.utc),- )-- assert frame.reason == "login_credentials_unresolved"+async def _ask(ctx: CopilotContext, login_page_url: str = "https://portal.example.com/login") -> dict[str, Any]:+ return await _request_credential(login_page_url, "This site needs a sign-in.", ctx)def test_connected_resume_stamps_the_single_ask_origin() -> None:- policy = _card_answerable_policy()- credential = _make_credential()+ policy = _ask_origin_policy("https://portal.example.com/login")- credential_pause_module._apply_connected_credential_to_policy(make_copilot_context(), policy, credential)+ credential_pause_module._apply_connected_credential_to_policy(make_copilot_context(), policy, _make_credential())assert policy.live_page_admitted_urls == {"cred_1": "https://portal.example.com/login"}def test_connected_resume_stamps_nothing_when_the_ask_spans_several_origins() -> None:- policy = _card_answerable_policy(- ask_login_page_urls=["https://portal.example.com/login", "https://other.example.com/login"]- )-- credential_pause_module._apply_connected_credential_to_policy(make_copilot_context(), policy, _make_credential())-- assert policy.live_page_admitted_urls == {}---def test_connected_resume_never_binds_an_origin_from_prose() -> None:- policy = _card_answerable_policy(- ask_login_page_urls=[],- clarification_question="Sign in at https://prose.example.com/login first. Which one should I use?",- )+ policy = _ask_origin_policy("https://portal.example.com/login", "https://other.example.com/login")credential_pause_module._apply_connected_credential_to_policy(make_copilot_context(), policy, _make_credential())@@ -1648,7 +1608,7 @@ def test_connected_resume_never_binds_an_origin_from_prose() -> None:def test_connected_resume_names_the_picked_credential_superseding_an_earlier_mention() -> None:"""The fill seam's which-credential check is set equality, so a card answer must replace anearlier prose mention, not join it."""- policy = _card_answerable_policy()+ policy = _ask_origin_policy("https://portal.example.com/login")policy.current_turn_named_credential_ids = {"cred_earlier"}credential_pause_module._apply_connected_credential_to_policy(make_copilot_context(), policy, _make_credential())@@ -1657,7 +1617,7 @@ def test_connected_resume_names_the_picked_credential_superseding_an_earlier_mendef test_connected_resume_does_not_duplicate_an_already_resolved_credential() -> None:- policy = _card_answerable_policy()+ policy = _ask_origin_policy("https://portal.example.com/login")credential = _make_credential()policy.resolved_credentials = [credential]@@ -1668,7 +1628,7 @@ def test_connected_resume_does_not_duplicate_an_already_resolved_credential() ->def test_a_card_connected_credential_keeps_its_durable_cross_turn_approval() -> None:ctx = make_copilot_context()- policy = _card_answerable_policy()+ policy = _ask_origin_policy("https://portal.example.com/login")ctx.request_policy = policycredential_pause_module._apply_connected_credential_to_policy(ctx, policy, _make_credential())@@ -1679,123 +1639,355 @@ def test_a_card_connected_credential_keeps_its_durable_cross_turn_approval() ->]-async def test_preflight_connect_binds_the_credential_and_clears_the_clarification_block(- monkeypatch: pytest.MonkeyPatch,-) -> None:- ctx = _preflight_ctx()+def _answered_cache(action: str, credential_id: str | None = None) -> _FakeCache:cache = _FakeCache()cache.store[credential_response_cache_key("org-1", "chat-1", "turn-1")] = encode_credential_response(- "connected", "cred_1"+ action, credential_id)- monkeypatch.setattr(credential_pause_module.app._inst, "CACHE", cache, raising=False)- credential = _make_credential()+ return cache+++def _stub_credential_lookup(monkeypatch: pytest.MonkeyPatch, credential: Credential) -> None:monkeypatch.setattr(credential_pause_module.app,"DATABASE",SimpleNamespace(credentials=SimpleNamespace(get_credentials_by_ids=AsyncMock(return_value=[credential]))),)- monkeypatch.setattr(credential_pause_module, "CREDENTIAL_RESPONSE_POLL_SECONDS", 0.01)- stream = _make_stream()- config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=5)- resolution = await preflight_credential_pause(ctx, stream, config)- assert resolution is not None and resolution.action == "connected"- assert ctx.credential_pause_outcome == "connected"- policy = ctx.request_policy- assert policy.resolved_credentials == [credential]- assert policy.allow_run_blocks is True- assert policy.clarification_reason == "none"- assert policy.user_response_policy == "proceed"- assert policy.allow_update_workflow is True- assert policy.requires_user_clarification is False- sent_types = [call.args[0].type for call in stream.send.await_args_list]- assert sent_types == [WorkflowCopilotStreamMessageType.CREDENTIAL_REQUIRED]+async def test_the_tool_call_raises_the_card_and_returns_the_connected_credential_to_the_model(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Fails without the tool: nothing pre-run raises the card, so the turn finalizes with a prose+ ask and no frame. Fails again if the answer is not returned as this call's own typed result."""+ ctx = _tool_ctx(monkeypatch, _answered_cache("connected", "cred_1"))+ _stub_credential_lookup(monkeypatch, _make_credential())+ result = await _ask(ctx)-def _preflight_policy_inputs() -> RequestPolicyGuardrailInputs:- return RequestPolicyGuardrailInputs(- user_message="Log in to https://portal.example.com/login and download the invoices.",- workflow_yaml="",- chat_history_text="",- chat_history_messages=[],- global_llm_context="",- organization_id="org-1",- request_policy_handler=None,- )+ assert result["status"] == "connected"+ assert result["credential_id"] == "cred_1"+ frame = ctx.stream.send.await_args_list[0].args[0]+ assert frame.type is WorkflowCopilotStreamMessageType.CREDENTIAL_REQUIRED+ assert frame.reason == "login_credentials_unresolved"+ assert frame.login_page_urls == ["https://portal.example.com/login"]+ assert frame.message == "This site needs a sign-in."+ assert ctx.request_policy.live_page_admitted_urls == {"cred_1": "https://portal.example.com/login"}+ assert ctx.request_policy.current_turn_named_credential_ids == {"cred_1"}+ assert ctx.request_policy.allow_run_blocks is True@pytest.mark.asyncio-async def test_preflight_skip_clears_the_reason_so_the_declined_turn_shows_no_card_cta(+async def test_a_skipped_card_returns_skipped_and_spends_the_one_ask_per_turn_latch(monkeypatch: pytest.MonkeyPatch,) -> None:- """A stale login_credentials_unresolved would still route through- CREDENTIAL_PROMPT_CLARIFICATION_REASONS and stamp a credential CTA on the- reply for a turn the user explicitly declined."""- ctx = _preflight_ctx()- cache = _FakeCache()- cache.store[credential_response_cache_key("org-1", "chat-1", "turn-1")] = encode_credential_response("skip", None)- monkeypatch.setattr(credential_pause_module.app._inst, "CACHE", cache, raising=False)- monkeypatch.setattr(credential_pause_module, "CREDENTIAL_RESPONSE_POLL_SECONDS", 0.01)- stream = _make_stream()- config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=5)+ ctx = _tool_ctx(monkeypatch, _answered_cache("skip"))- resolution = await preflight_credential_pause(ctx, stream, config)+ first = await _ask(ctx)+ second = await _ask(ctx)- assert resolution is not None and resolution.action == "skip"- policy = ctx.request_policy- assert policy.clarification_reason == "none"- assert policy.clarification_reason not in CREDENTIAL_PROMPT_CLARIFICATION_REASONS- assert policy.requires_user_clarification is False- assert policy.allow_missing_credentials_in_draft is True- assert policy.user_response_policy == "proceed"- assert policy.allow_update_workflow is True+ assert first["status"] == "skipped"+ assert ctx.credential_pause_outcome == "skipped"+ assert second["status"] == "already_asked"+ assert second["outcome"] == "skipped"+ assert ctx.stream.send.await_count == 1@pytest.mark.asyncio-async def test_preflight_timeout_leaves_the_clarification_block_for_the_terminal_clarify(+async def test_an_unanswered_card_returns_a_typed_outcome_rather_than_an_error(monkeypatch: pytest.MonkeyPatch,) -> None:- ctx = _preflight_ctx()- monkeypatch.setattr(credential_pause_module.app._inst, "CACHE", _FakeCache(), raising=False)- monkeypatch.setattr(credential_pause_module, "CREDENTIAL_RESPONSE_POLL_SECONDS", 0.01)- stream = _make_stream()- config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=0)+ """The user can walk away from an open card; the model must get a typed arm it can act on+ instead of a failed call it would retry or narrate as a breakage."""+ ctx = _tool_ctx(monkeypatch)+ ctx.copilot_config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=0)- resolution = await preflight_credential_pause(ctx, stream, config)+ result = await _ask(ctx)- assert resolution is None- assert ctx.credential_pause_outcome == "timeout"- policy = ctx.request_policy- assert policy.user_response_policy == "ask_clarification"- assert policy.clarification_reason == "login_credentials_unresolved"+ assert result["ok"] is True+ assert result["status"] == "unanswered"+ assert result["outcome"] == "timeout"+ assert result["next"]+ ctx.stream.send.assert_awaited()@pytest.mark.asyncio-async def test_preflight_declines_when_the_client_cannot_render_the_card() -> None:- ctx = _preflight_ctx()+async def test_the_tool_refuses_a_sign_in_site_the_user_never_provided(monkeypatch: pytest.MonkeyPatch) -> None:+ """The connected credential's origin is bound from this argument, so a model-invented site+ would hand the card's answer fill authority the user never granted."""+ ctx = _tool_ctx(monkeypatch)++ result = await _ask(ctx, "https://elsewhere.example.net/login")++ assert result["ok"] is False+ assert ctx.request_policy.credential_ask_login_page_urls == []+ ctx.stream.send.assert_not_awaited()+++async def test_the_tool_reports_unavailable_with_a_prose_fallback_when_the_card_cannot_render(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ ctx = _tool_ctx(monkeypatch)ctx.client_supports_credential_pause = False- stream = _make_stream()- config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=5)- assert await preflight_credential_pause(ctx, stream, config) is None- stream.send.assert_not_awaited()+ result = await _ask(ctx)++ assert result["status"] == "unavailable"+ assert "Credentials page" in result["fallback"]+ assert ctx.request_policy.credential_ask_login_page_urls == []+ ctx.stream.send.assert_not_awaited()@pytest.mark.asyncio-async def test_preflight_consumes_the_one_pause_per_turn_latch(monkeypatch: pytest.MonkeyPatch) -> None:- ctx = _preflight_ctx()- cache = _FakeCache()- cache.store[credential_response_cache_key("org-1", "chat-1", "turn-1")] = encode_credential_response("skip", None)- monkeypatch.setattr(credential_pause_module.app._inst, "CACHE", cache, raising=False)- monkeypatch.setattr(credential_pause_module, "CREDENTIAL_RESPONSE_POLL_SECONDS", 0.01)+async def test_the_tool_reports_unavailable_rather_than_raising_when_no_cache_is_configured(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A deployment with no cache at all must degrade, not fault the turn on an attribute of None."""+ ctx = _tool_ctx(monkeypatch)+ monkeypatch.setattr(app._inst, "CACHE", None, raising=False)++ result = await _ask(ctx)++ assert result["status"] == "unavailable"+ ctx.stream.send.assert_not_awaited()+++class _SlowAnswerCache(_FakeCache):+ """Answers the card only after ``delay_seconds``, standing in for a user who takes a moment."""++ def __init__(self, response_key: str, delay_seconds: float, action: str = "skip") -> None:+ super().__init__()+ self._response_key = response_key+ self._action = action+ self._ready_at = time.monotonic() + delay_seconds++ async def get(self, key: str) -> Any:+ if key == self._response_key and time.monotonic() >= self._ready_at:+ return encode_credential_response(self._action, "cred_1" if self._action == "connected" else None)+ return await super().get(key)+++async def test_the_card_outlives_the_model_stream_deadline_the_tool_call_ran_under(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The ask is raised inside the model stream, which runs under the turn deadline; without+ suspending that deadline for the wait, a user who takes longer than the budget left has the+ card cancelled out from under them."""+ ctx = _tool_ctx(+ monkeypatch,+ _SlowAnswerCache(credential_response_cache_key("org-1", "chat-1", "turn-1"), 1.6),+ )+ monkeypatch.setattr("skyvern.forge.sdk.copilot.enforcement.TOTAL_TIMEOUT_SECONDS", 1.0)+stream = _make_stream()- config = CopilotConfig(credential_pause_enabled=True, credential_pause_timeout_seconds=5)+ fake_result = _fake_result()+ calls: list[dict[str, Any]] = []- await preflight_credential_pause(ctx, stream, config)- assert ctx.credential_pause_used is True+ def fake_run_streamed(*args: Any, **kwargs: Any) -> Any:+ calls.append(kwargs)+ return fake_result++ async def fake_stream_to_sse(result: Any, s: Any, c: Any) -> None:+ await _ask(ctx)++ monkeypatch.setattr("skyvern.forge.sdk.copilot.enforcement.Runner.run_streamed", fake_run_streamed)+ monkeypatch.setattr("skyvern.forge.sdk.copilot.streaming_adapter.stream_to_sse", fake_stream_to_sse)++ returned = await run_with_enforcement(+ agent=MagicMock(),+ initial_input="hello",+ ctx=ctx,+ stream=stream,+ run_config=RunConfig(),+ copilot_config=ctx.copilot_config,+ )++ assert returned is fake_result+ assert len(calls) == 1+ assert ctx.credential_pause_outcome == "skipped"+ assert ctx.model_stream_deadline is None+ sent = [str(call.args[0]) for call in ctx.stream.send.await_args_list]+ assert sum(1 for frame in sent if "credential_required" in frame) == 1+ assert not any(_CREDENTIALS_UI_DIRECTIONS in frame for frame in sent)+++async def test_cancelling_the_turn_while_the_card_is_open_stays_a_cancellation(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The suspended deadline is handed back on the way out; a failure to reschedule it must not+ replace the cancellation with a RuntimeError the enforcement loop does not handle."""+ ctx = _tool_ctx(+ monkeypatch,+ _SlowAnswerCache(credential_response_cache_key("org-1", "chat-1", "turn-1"), 30),+ )++ async def ask_under_deadline() -> None:+ async with asyncio.timeout(30) as deadline:+ ctx.model_stream_deadline = deadline+ await _ask(ctx)++ task = asyncio.create_task(ask_under_deadline())+ await asyncio.sleep(0.05)+ task.cancel()++ with pytest.raises(asyncio.CancelledError):+ await task+ assert ctx.copilot_credential_pause_seconds > 0+++_RUN_TOOLS_GATED_ON_AN_OPEN_ASK = [+ ("run_blocks_and_collect_debug", {"block_labels": ["login"], "parameters": {}}),+ (+ "edit_block_and_run",+ {+ "label": "login",+ "expected_code": "old",+ "replacement_code": "new",+ "block_labels": ["login"],+ "parameters": {},+ },+ ),+ ("update_and_run_blocks", {"workflow_yaml": "title: draft", "block_labels": ["login"], "parameters": {}}),+]++[email protected](("tool_name", "arguments"), _RUN_TOOLS_GATED_ON_AN_OPEN_ASK)+async def test_a_run_tool_called_alongside_the_ask_waits_for_the_user_to_answer(+ monkeypatch: pytest.MonkeyPatch,+ tool_name: str,+ arguments: dict[str, Any],+) -> None:+ """The provider issues sibling tool calls in one model response, so without this wait the run+ starts against the pre-card policy and the user answers a login the run already went without."""+ ctx = _tool_ctx(+ monkeypatch,+ _SlowAnswerCache(credential_response_cache_key("org-1", "chat-1", "turn-1"), 0.25, "connected"),+ )+ _stub_credential_lookup(monkeypatch, _make_credential())+ ctx.turn_origin = TurnOrigin.runtime_self_heal+ tool = {+ "run_blocks_and_collect_debug": tools_module.run_blocks_tool,+ "edit_block_and_run": tools_module.edit_block_and_run_tool,+ "update_and_run_blocks": tools_module.update_and_run_blocks_tool,+ }[tool_name]+ finished: list[str] = []++ async def ask() -> None:+ await _ask(ctx)+ finished.append("ask")++ async def run() -> None:+ await tool.on_invoke_tool(SimpleNamespace(context=ctx, tool_name=tool_name), json.dumps(arguments))+ finished.append("run")++ await asyncio.gather(ask(), run())++ assert finished == ["ask", "run"]+ assert ctx.credential_pause_outcome == "connected"+++async def _announce_ask(ctx: CopilotContext) -> None:+ response = SimpleNamespace(output=[SimpleNamespace(name="request_credential")])+ await CopilotRunHooks(ctx).on_llm_end(SimpleNamespace(context=ctx), MagicMock(), response) # type: ignore[arg-type]+++async def _invoke_ask_tool(ctx: CopilotContext, login_page_url: str) -> None:+ await tools_module.request_credential_tool.on_invoke_tool(+ SimpleNamespace(context=ctx, tool_name="request_credential"), # type: ignore[arg-type]+ json.dumps({"login_page_url": login_page_url, "reason": "This site needs a sign-in."}),+ )+++def test_the_ask_tool_is_registered_in_the_production_tool_set() -> None:+ """Every other test here invokes the tool object directly, so unregistering it would take the+ whole capability away without reddening one of them."""+ assert "request_credential" in {tool.name for tool in tools_module.NATIVE_TOOLS}++[email protected](("tool_name", "arguments"), _RUN_TOOLS_GATED_ON_AN_OPEN_ASK)+async def test_a_run_tool_scheduled_ahead_of_the_ask_in_one_response_still_waits(+ monkeypatch: pytest.MonkeyPatch,+ tool_name: str,+ arguments: dict[str, Any],+) -> None:+ """Tool calls in one model response run as concurrent tasks in an order the model picks, so a+ gate armed only inside the ask's own coroutine is passed by whichever sibling is scheduled first."""+ ctx = _tool_ctx(+ monkeypatch,+ _SlowAnswerCache(credential_response_cache_key("org-1", "chat-1", "turn-1"), 0.25, "connected"),+ )+ _stub_credential_lookup(monkeypatch, _make_credential())+ await _announce_ask(ctx)+ finished: list[str] = []++ tool = {+ "run_blocks_and_collect_debug": tools_module.run_blocks_tool,+ "edit_block_and_run": tools_module.edit_block_and_run_tool,+ "update_and_run_blocks": tools_module.update_and_run_blocks_tool,+ }[tool_name]++ async def run() -> None:+ await tool.on_invoke_tool(SimpleNamespace(context=ctx, tool_name=tool_name), json.dumps(arguments)) # type: ignore[arg-type]+ finished.append("run")++ async def ask() -> None:+ await _invoke_ask_tool(ctx, "https://portal.example.com/login")+ finished.append("ask")++ await asyncio.gather(run(), ask())++ # Without this the ask refuses instantly and the ordering is proven around a card that never+ # opened, which is the one shape the wrapper's release runs in.+ assert ctx.credential_pause_outcome == "connected"+ assert finished == ["ask", "run"]+++async def test_an_announced_ask_that_never_reaches_the_card_still_releases_the_waiting_run_tool(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Arming on the response means the gate closes before the ask can refuse, so every exit of the+ tool has to open it again or the sibling waits out the whole turn."""+ ctx = _tool_ctx(monkeypatch)+ await _announce_ask(ctx)++ async def ask() -> None:+ await _invoke_ask_tool(ctx, "https://elsewhere.example.net/login")++ await asyncio.wait_for(asyncio.gather(await_pending_credential_pause(ctx), ask()), timeout=5)++ assert ctx.request_policy.credential_ask_login_page_urls == []+++def test_the_card_message_is_capped_and_stripped_before_the_user_sees_it() -> None:+ """`reason` is model-authored and leads the card, above the hostname. An unbounded one can push+ the site the credential is actually for off the viewport."""+ shouted = 'Connect your bank login\n"now"' + "!" * 500++ safe = credential_pause_module.defang_card_text(shouted)++ assert len(safe) <= 200+ assert "\n" not in safe+ assert '"' not in safe+++async def test_a_repeat_ask_in_a_later_response_releases_the_gate_it_armed(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """already_asked means a card was raised somewhere this turn, not that one is open now. A later+ response arms a fresh gate, so refusing to release on that exit parks every sibling on an Event+ no one owns until the turn times out."""+ ctx = _tool_ctx(monkeypatch)+ ctx.credential_pause_used = True++ await _announce_ask(ctx)+ await _invoke_ask_tool(ctx, "https://portal.example.com/login")- ctx.request_policy = _blocked_login_policy()- assert await maybe_credential_pause(ctx, _fake_result(), stream, config) is None- assert len(stream.send.await_args_list) == 1+ await asyncio.wait_for(await_pending_credential_pause(ctx), timeout=1)