Skip to content

Automate browser based workflows with AI

feat(tagging): Phase 6.1 backend — key-optional labels + flexible tag filter (SKY-10683) (#6458)

Trevor Cheung4e686191ffe1
diff --git a/alembic/versions/2026_06_09_1634-4dbd183edee0_tagging_key_optional_labels_nullable_key_dual_partial_unique.py b/alembic/versions/2026_06_09_1634-4dbd183edee0_tagging_key_optional_labels_nullable_key_dual_partial_unique.py
new file mode 100644
index 000000000..81d60c928
--- /dev/null
+++ b/alembic/versions/2026_06_09_1634-4dbd183edee0_tagging_key_optional_labels_nullable_key_dual_partial_unique.py
@@ -0,0 +1,98 @@
+"""tagging: key-optional labels (nullable key, dual partial-unique)
+
+Revision ID: 4dbd183edee0
+Revises: 8266bacba614
+Create Date: 2026-06-09T16:34:35.143445+00:00
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "4dbd183edee0"
+down_revision: Union[str, None] = "8266bacba614"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ op.alter_column("workflow_tag_events", "key", existing_type=sa.String(), nullable=True)
+
+ # The old per-(org, wpid, key) uniqueness can't express a group-less label.
+ # Split it: grouped unique per key, standalone unique per value.
+ op.drop_index(
+ "workflow_tag_events_active_set_unique",
+ table_name="workflow_tag_events",
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set'"),
+ )
+ op.create_index(
+ "workflow_tag_events_active_grouped_unique",
+ "workflow_tag_events",
+ ["organization_id", "workflow_permanent_id", "key"],
+ unique=True,
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set' AND key IS NOT NULL"),
+ )
+ op.create_index(
+ "workflow_tag_events_active_label_unique",
+ "workflow_tag_events",
+ ["organization_id", "workflow_permanent_id", "value"],
+ unique=True,
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set' AND key IS NULL"),
+ )
+ # Supports the value-only ("filter by label") term, which matches a value
+ # across any/no group.
+ op.create_index(
+ "workflow_tag_events_org_value_active_idx",
+ "workflow_tag_events",
+ ["organization_id", "value"],
+ unique=False,
+ postgresql_include=["workflow_permanent_id"],
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set'"),
+ )
+
+ # DELETE rows may now carry a value (standalone-label deletes); only SET rows
+ # must have a value. Replaces the old "delete rows have null value" constraint.
+ op.drop_constraint("ck_workflow_tag_events_delete_null_value", "workflow_tag_events", type_="check")
+ op.create_check_constraint(
+ "ck_workflow_tag_events_set_has_value",
+ "workflow_tag_events",
+ "event_type != 'set' OR value IS NOT NULL",
+ )
+
+
+def downgrade() -> None:
+ op.execute("DELETE FROM workflow_tag_events WHERE key IS NULL")
+ op.drop_constraint("ck_workflow_tag_events_set_has_value", "workflow_tag_events", type_="check")
+ op.create_check_constraint(
+ "ck_workflow_tag_events_delete_null_value",
+ "workflow_tag_events",
+ "event_type != 'delete' OR value IS NULL",
+ )
+ op.drop_index(
+ "workflow_tag_events_org_value_active_idx",
+ table_name="workflow_tag_events",
+ postgresql_include=["workflow_permanent_id"],
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set'"),
+ )
+ op.drop_index(
+ "workflow_tag_events_active_label_unique",
+ table_name="workflow_tag_events",
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set' AND key IS NULL"),
+ )
+ op.drop_index(
+ "workflow_tag_events_active_grouped_unique",
+ table_name="workflow_tag_events",
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set' AND key IS NOT NULL"),
+ )
+ op.create_index(
+ "workflow_tag_events_active_set_unique",
+ "workflow_tag_events",
+ ["organization_id", "workflow_permanent_id", "key"],
+ unique=True,
+ postgresql_where=sa.text("superseded_at IS NULL AND event_type = 'set'"),
+ )
+ op.alter_column("workflow_tag_events", "key", existing_type=sa.String(), nullable=False)
diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json
index 809f5e3c5..aea2cf7cd 100644
--- a/docs/api-reference/openapi.json
+++ b/docs/api-reference/openapi.json
@@ -106,7 +106,7 @@
"/v1/run/agents": {
"post": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Run an agent",
"description": "Run an agent",
@@ -228,7 +228,7 @@
"/v1/runs/{run_id}": {
"get": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Get run info by id",
"description": "Get run information (task run, workflow run)",
@@ -334,7 +334,7 @@
"/v1/runs/{run_id}/cancel": {
"post": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Cancel a run by id",
"description": "Cancel a run (task or workflow)",
@@ -410,7 +410,7 @@
"/v1/runs/cancel": {
"post": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Bulk cancel runs",
"description": "Cancel multiple runs (tasks or workflows) in a single request",
@@ -726,14 +726,16 @@
"type": "null"
}
],
- "description": "Filter by tags as `key:value` pairs. Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct keys, OR within a key (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). Matches current tag values only. Not supported with `template=true`.",
+ "description": "Filter by tags. Each term is a label (`production`), a group (`env:*`), or a group:label (`env:prod`). Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's labels (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. Not supported with `template=true`.",
"examples": [
"env:prod",
+ "production",
+ "env:*",
"customer:acme,env:prod"
],
"title": "Tags"
},
- "description": "Filter by tags as `key:value` pairs. Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct keys, OR within a key (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). Matches current tag values only. Not supported with `template=true`."
+ "description": "Filter by tags. Each term is a label (`production`), a group (`env:*`), or a group:label (`env:prod`). Repeat the param or comma-separate (`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's labels (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only. Not supported with `template=true`."
},
{
"name": "template",
@@ -1495,6 +1497,56 @@
}
},
"x-fern-sdk-method-name": "update_tag_key"
+ },
+ "delete": {
+ "tags": [
+ "Tags"
+ ],
+ "summary": "Delete tag key",
+ "description": "Delete a tag key from the organization registry and remove that tag from every workflow that currently has it (cascade). Returns how many workflows the tag was removed from.",
+ "operationId": "delete_tag_key_v1_tag_keys__key__delete",
+ "parameters": [
+ {
+ "name": "key",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "Tag key to delete",
+ "examples": [
+ "env"
+ ],
+ "title": "Key"
+ },
+ "description": "Tag key to delete"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successfully deleted tag key",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TagKeyDeleteResponse"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Tag key not found"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ }
+ }
+ },
+ "x-fern-sdk-method-name": "delete_tag_key"
}
},
"/v1/workflow-tags": {
@@ -1783,7 +1835,7 @@
"/v1/runs/{run_id}/retry_webhook": {
"post": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Replay a run webhook",
"description": "Retry sending the webhook for a run",
@@ -1882,7 +1934,7 @@
"/v1/runs/{run_id}/timeline": {
"get": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Get run timeline",
"description": "Get timeline for a run (workflow run or task_v2 run)",
@@ -4717,7 +4769,7 @@
"/v1/agents/runs/{workflow_run_id}/retry": {
"post": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Retry a run",
"description": "Retry a workflow run using the original run parameters.",
@@ -4822,7 +4874,7 @@
"/v1/agents/runs": {
"get": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Get all runs",
"description": "List workflow runs across all workflows for the current organization.\n\nResults are paginated and can be filtered by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic — a run must match every supplied filter to be returned.\n\n### search_key\n\nA case-insensitive substring search that matches against **any** of the following fields:\n\n| Searched field | Description |\n|---|---|\n| `workflow_run_id` | The unique run identifier (e.g. `wr_123…`) |\n| Parameter **key** | The `key` of any workflow parameter definition associated with the run |\n| Parameter **description** | The `description` of any workflow parameter definition |\n| Run parameter **value** | The actual value supplied for any parameter when the run was created |\n| `extra_http_headers` | Extra HTTP headers attached to the run (searched as raw JSON text) |\n\nSoft-deleted parameter definitions are excluded from key/description matching. A run is returned if **any** of the fields above contain the search term.\n\n### error_code\n\nAn **exact-match** filter against the `error_code` field inside each task's `errors` JSON array. A run matches if **any** of its tasks contains an error object with a matching `error_code` value. Error codes are user-defined strings set during workflow execution (e.g. `INVALID_CREDENTIALS`, `LOGIN_FAILED`, `CAPTCHA_DETECTED`).\n\n### Combining filters\n\nAll query parameters use AND logic:\n- `?status=failed` — only failed runs\n- `?status=failed&error_code=LOGIN_FAILED` — failed runs **and** have a LOGIN_FAILED error\n- `?status=failed&error_code=LOGIN_FAILED&search_key=prod_credential` — all three conditions must match",
@@ -4974,7 +5026,7 @@
"/v1/agents/{workflow_id}/runs": {
"get": {
"tags": [
- "Agents"
+ "Runs"
],
"summary": "Get all runs by agent",
"description": "List runs for a specific workflow.\n\nSupports filtering by **status**, **search_key**, and **error_code**. All filters are combined with **AND** logic.\n\n### search_key\n\nCase-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, and extra HTTP headers. Soft-deleted parameter definitions are excluded.\n\n### error_code\n\nExact-match filter on the `error_code` field inside each task's `errors` JSON array. A run matches if any of its tasks contains an error with a matching `error_code`.",
@@ -14337,6 +14389,11 @@
"type": "boolean",
"title": "Include Extracted Text",
"default": true
+ },
+ "skip_saved_profile": {
+ "type": "boolean",
+ "title": "Skip Saved Profile",
+ "default": false
}
},
"type": "object",
@@ -14526,6 +14583,11 @@
"type": "boolean",
"title": "Complete Verification",
"default": true
+ },
+ "skip_saved_profile": {
+ "type": "boolean",
+ "title": "Skip Saved Profile",
+ "default": false
}
},
"type": "object",
@@ -17495,25 +17557,56 @@
"TagApplyRequest": {
"properties": {
"tags": {
- "additionalProperties": {
- "type": "string"
+ "items": {
+ "$ref": "#/components/schemas/TagInput"
},
- "type": "object",
+ "type": "array",
"title": "Tags",
- "description": "Tags to set (overwrite). Map of key to value."
+ "description": "Tags to set (overwrite). List of {key?, value} objects."
},
"tags_to_delete": {
"items": {
- "type": "string"
+ "$ref": "#/components/schemas/TagDeleteInput"
},
"type": "array",
"title": "Tags To Delete",
- "description": "Tag keys to soft-delete."
+ "description": "Tags to soft-delete. List of {key?, value?} targets."
}
},
"type": "object",
"title": "TagApplyRequest",
- "description": "Body for ``POST /v1/workflows/{wpid}/tags``. Either field may be empty;\nboth empty is a valid no-op. Same-key collisions: set wins over delete."
+ "description": "Body for ``POST /v1/workflows/{wpid}/tags``. Either field may be empty (both\nempty is a no-op). On a same-identity collision, set wins over delete."
+ },
+ "TagDeleteInput": {
+ "properties": {
+ "key": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Key",
+ "description": "Group (key) to delete. Use for grouped tags."
+ },
+ "value": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Value",
+ "description": "Label (value) to delete. Use for standalone labels."
+ }
+ },
+ "type": "object",
+ "title": "TagDeleteInput",
+ "description": "One tag to soft-delete: a grouped tag by its ``key``, or a standalone label\nby its ``value`` (omit the key)."
},
"TagHistoryItem": {
"properties": {
@@ -17522,7 +17615,14 @@
"title": "Tag Event Id"
},
"key": {
- "type": "string",
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
"title": "Key"
},
"value": {
@@ -17600,6 +17700,58 @@
],
"title": "TagHistoryResponse"
},
+ "TagInput": {
+ "properties": {
+ "key": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Key",
+ "description": "Optional group (key). Omit for a standalone label."
+ },
+ "value": {
+ "type": "string",
+ "title": "Value",
+ "description": "Label (value). Always required."
+ }
+ },
+ "type": "object",
+ "required": [
+ "value"
+ ],
+ "title": "TagInput",
+ "description": "One tag to set. ``value`` is the required label; ``key`` is the optional\ngroup — null for a standalone label, set for a grouped label (e.g. env:prod)."
+ },
+ "TagItem": {
+ "properties": {
+ "key": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Key"
+ },
+ "value": {
+ "type": "string",
+ "title": "Value"
+ }
+ },
+ "type": "object",
+ "required": [
+ "value"
+ ],
+ "title": "TagItem",
+ "description": "A single tag (key + label) without per-tag attribution. ``key`` is null\nfor a standalone label."
+ },
"TagKey": {
"properties": {
"key": {
@@ -17616,6 +17768,11 @@
}
],
"title": "Description"
+ },
+ "workflow_count": {
+ "type": "integer",
+ "title": "Workflow Count",
+ "default": 0
}
},
"type": "object",
@@ -17625,6 +17782,25 @@
"title": "TagKey",
"description": "Tag-key registry entry."
},
+ "TagKeyDeleteResponse": {
+ "properties": {
+ "key": {
+ "type": "string",
+ "title": "Key"
+ },
+ "removed_from_workflow_count": {
+ "type": "integer",
+ "title": "Removed From Workflow Count"
+ }
+ },
+ "type": "object",
+ "required": [
+ "key",
+ "removed_from_workflow_count"
+ ],
+ "title": "TagKeyDeleteResponse",
+ "description": "Response for ``DELETE /v1/tag-keys/{key}``."
+ },
"TagKeyUpdate": {
"properties": {
"description": {
@@ -17646,6 +17822,17 @@
},
"TagResponse": {
"properties": {
+ "key": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Key"
+ },
"value": {
"type": "string",
"title": "Value"
@@ -17672,7 +17859,7 @@
"set_by"
],
"title": "TagResponse",
- "description": "Current state of one tag (``GET /v1/workflows/{wpid}/tags`` row)."
+ "description": "Current state of one tag (``GET /v1/workflows/{wpid}/tags`` row).\n``key`` is null for a standalone label."
},
"TagsResponse": {
"properties": {
@@ -17681,10 +17868,10 @@
"title": "Workflow Permanent Id"
},
"tags": {
- "additionalProperties": {
+ "items": {
"$ref": "#/components/schemas/TagResponse"
},
- "type": "object",
+ "type": "array",
"title": "Tags"
}
},
@@ -17694,7 +17881,7 @@
"tags"
],
"title": "TagsResponse",
- "description": "Current tag map for a workflow."
+ "description": "Current tags for a workflow. A list (not a key-map) so standalone labels,\nwhich have no key, are representable."
},
"TaskBlock": {
"properties": {
@@ -24932,10 +25119,10 @@
"properties": {
"workflow_tags": {
"additionalProperties": {
- "additionalProperties": {
- "type": "string"
+ "items": {
+ "$ref": "#/components/schemas/TagItem"
},
- "type": "object"
+ "type": "array"
},
"type": "object",
"title": "Workflow Tags"
@@ -24946,7 +25133,7 @@
"workflow_tags"
],
"title": "WorkflowTagsBatchResponse",
- "description": "Response for the batch endpoint.\n\nWorkflows with no tags are present with an empty dict so the frontend can\ndistinguish \"fetched, none set\" from \"not fetched\" without a second call.\nWorkflows outside the caller's org are silently absent (no leakage)."
+ "description": "Response for the batch endpoint.\n\nWorkflows with no tags are present with an empty list so the frontend can\ndistinguish \"fetched, none set\" from \"not fetched\" without a second call.\nWorkflows outside the caller's org are silently absent (no leakage)."
},
"WorkflowTriggerBlock": {
"properties": {
diff --git a/docs/changelog-emails/2026-05-may.md b/docs/changelog-emails/2026-05-may.md
new file mode 100644
index 000000000..5072f3409
--- /dev/null
+++ b/docs/changelog-emails/2026-05-may.md
@@ -0,0 +1,201 @@
+![Skyvern Changelog — May 2026](images/2026-05-00-header.png)
+
+# Skyvern Changelog — April & May 2026
+
+*Two months of shipping in one email — a draggable editor, cleaner MCP OAuth, stronger run controls, and plenty more. Headliners first, the full list at the end.*
+
+---
+
+## April 2026
+
+### Workflow Copilot v2
+
+The workflow copilot got a lot more hands-on. **Hard-cancel** a run mid-flight instead of waiting it out, and **follow it live** as it **streams status narration** and surfaces **block-level events** (starts, completions, errors) while your workflow runs. When a test trips, it hands back the **work-in-progress workflow** so you can grab the draft and keep building. Self-healed retries are now visually separated from real failures, and a quick `/discover` in chat passes the whole build straight to the copilot.
+
+![Workflow Copilot v2 — live status narration with a streaming sub-event timeline, a self-healed retry shown apart from errors, and a hard-cancel button](images/2026-04-01-copilot-v2.png)
+
+---
+
+### MCP OAuth, Across Clients
+
+Connecting Skyvern over MCP is now a clean **OAuth** flow. **Multi-org users** get an organization picker right in the authorize step. Skyvern runs as a native **OpenAI Apps SDK** app, ships **safety hints** for the ChatGPT connector, documents **Codex** remote OAuth end-to-end, and adds **OpenClaw** as a new target (`skyvern setup openclaw`). Under the hood: production OAuth callbacks, plus per-tool latency and error telemetry.
+
+![MCP OAuth — an authorize dialog with an organization picker for multi-org users, alongside supported clients: Claude, ChatGPT/Apps SDK, Codex, and OpenClaw](images/2026-04-02-mcp-oauth.png)
+
+---
+
+### `skyvern schedule` + `skyvern config` CLI
+
+Your terminal is now a control panel. **`skyvern schedule`** creates, lists, toggles, and deletes workflow schedules without leaving the command line. **`skyvern config`** reads and writes org-level settings — timeouts, concurrency, default proxy — the same way. Both run over the MCP protocol, so Claude Code, Codex, and other MCP clients can use them through the same interface.
+
+![Terminal showing the new skyvern schedule and skyvern config CLI commands — listing schedules in a table, creating a cron schedule, and reading an org-level config value](images/2026-04-03-cli-schedule-config.png)
+
+---
+
+### AI Summarize for Workflow Outputs
+
+Stop squinting at nested JSON. A new **Summarize with AI** button sits next to every block and workflow output — one click turns raw data into a plain-language summary of what your workflow extracted.
+
+![AI Summarize for workflow outputs — raw JSON on the left and a generated plain-language summary on the right, produced by a "Summarize with AI" button](images/2026-04-04-ai-summarize.png)
+
+---
+
+### Workflow-Level Error Code Mapping
+
+Set your error handling once — not on every block. Workflows now take an `error_code_mapping` field that **every block inherits automatically**. Define the defaults at the top, and override per-block only where you actually need to.
+
+![Workflow-level error code mapping — error codes mapped to messages once at the workflow level, with each block inheriting them and one block adding an override](images/2026-04-05-error-code-mapping.png)
+
+---
+
+### Debugger Remembers Last-Used Values
+
+Less busywork between test runs. The debugger now **pre-fills the Run dialog with the values from your last run**, so you're not re-typing the same inputs every time.
+
+![Debugger Run dialog pre-filled with parameter values from the last run, marked by a "Pre-filled from last run" badge](images/2026-04-06-debugger-run-dialog.png)
+
+---
+
+## May 2026
+
+### Draggable Workflow Editor
+
+The editor is now **drag-and-drop** — reorder your whole workflow, not just tweak blocks in place. Grab any block by its handle and **drop it where it belongs**: top level, inside a branch, deep in a loop. **Collapse** blocks and entire nested containers to focus, and your layout is **remembered per workflow** across sessions. It's fully **keyboard-driven** with screen-reader announcements, and every block's config **autosaves as you type**. (Recording mode still freezes drag, so a mid-record reorder can't shift block identities under the recorder.)
+
+![Draggable workflow editor — a workflow canvas with a grip handle on a block mid-drag, a drop indicator between blocks, several blocks collapsed to compact headers, and a global expand/collapse control](images/2026-05-01-draggable-editor.png)
+
+---
+
+### Redesigned Run Page
+
+We redesigned the run page around a compact **timeline sidebar** and a dedicated **detail panel** — scan every block at a glance, then open any one for its inputs, output, and diagnostics. A live **N-of-M completion counter** tracks progress and visibly flags blocks that never ran. The **app sidebar** got a refresh in the same pass, for cleaner navigation everywhere.
+
+![Redesigned workflow run page — a compact timeline sidebar listing blocks with a live "7/12 blocks" completion counter, next to a detail panel showing the selected block's inputs, output, and diagnostics](images/2026-05-02-run-page-redesign.png)
+
+---
+
+### While Loop Block
+
+Loop until you're done — not a fixed number of times. The new **While Loop block** repeats a sub-workflow **until your condition is met**: paginate until there's no Next button, retry until a status flips, drain a queue until it's empty.
+
+![While Loop block — a workflow containing a While Loop block with a condition expression, wrapping a sub-workflow that repeats until the condition turns false](images/2026-05-03-while-loop.png)
+
+---
+
+### Analytics Dashboard
+
+Your automations, by the numbers. The new **`/analytics` page** breaks down **run volume, outcomes, and trends over time** in one view — no exports, no spreadsheets. (Gated per-org, so it lights up only where it's enabled.)
+
+![Analytics dashboard — an /analytics page with charts of workflow run volume and success rate over time, plus per-workflow performance breakdowns](images/2026-05-04-analytics-dashboard.png)
+
+---
+
+### Workflow Copilot, Steadier
+
+The copilot is steadier when sessions get long or messy. A persistent **turn-narrative bubble** tracks what the agent is doing — and **survives page reloads**, so you never lose your place. Hit an unexpected error? It's **recoverable now**: instead of a frozen chat, you get a clear explanation and a **specific follow-up question** drawn from what it actually found missing. The **diff view** finally catches changes **nested inside conditionals and loops**, and we cleared a batch of edge cases — credential scope leaking after an edit, session context lost across turns, accepted proposals getting dropped.
+
+![Workflow Copilot — a chat thread showing a persistent turn-narrative bubble summarizing the agent's current action, a recovered error with a clear explanation, and a diff panel highlighting a change nested inside a loop block](images/2026-05-05-copilot.png)
+
+---
+
+### More Control Over Your Runs
+
+Manage runs in bulk — cancel, retry, cap. The new **Retry API** re-runs a workflow **from the start or from any block** — no rebuilding inputs. **`POST /runs/cancel`** cancels **many runs in a single request** and tells you exactly which succeeded and which didn't. And two new guardrails — a **runtime limit** and a **per-workflow step cap** — stop runaway executions before they burn resources.
+
+![Run control APIs — an API panel showing POST /runs/cancel with a list of run IDs returning cancelled and failed arrays, a retry-from-block call, and workflow settings for a max runtime and a total step cap](images/2026-05-06-run-control.png)
+
+---
+
+### Self-Hosting: Custom Proxies & CDP Auth Headers
+
+Route any run through **your own proxy** — just pass `{"proxy_location": {"url": "http://user:pass@host:port"}}` on any task, workflow, or browser-session request; no managed proxy infrastructure required. And **CDP connect headers** are now a first-class workflow setting — your provider's auth headers are masked, stored, and applied to the **CDP connection only**, never forwarded to target sites. (Plus: msedge is the new default browser for self-hosted templates, and the Docker Compose quickstart bootstraps your `.env` files on first run.)
+
+![Self-hosting upgrades — a workflow settings panel with a custom proxy URL field and a masked CDP Connect Headers field, beside a terminal running the Docker Compose quickstart that auto-creates .env files](images/2026-05-07-self-hosting.png)
+
+---
+
+### Browser Profiles, End to End
+
+Saved browser profiles — the logged-in sessions your workflows reuse — are easier to set up and manage. A **guided, step-by-step setup** walks you through creating one, a dedicated **management page** lets you **search, rename, and organize**, and saving now gives you **instant feedback** with an in-progress row the moment you hit save.
+
+![Browser profiles — a dedicated browser profiles management page with search and rename controls, next to a guided step-by-step "create a profile" flow and an in-progress placeholder row appearing on save](images/2026-05-08-browser-profiles.png)
+
+---
+
+## Quick List — April & May
+
+**New features**
+- **Credits per run & run-level cost breakdown** — a Credits badge on run pages, and task records now track LLM, proxy, and captcha costs as separate fields via the API
+- **Credential Folders** — organize credentials into named folders, with a "Move to folder" control and a folder filter that persists across credential tabs
+- **Multiple schedules per workflow** — independent schedules on one workflow (e.g. weekdays at 9am *and* weekends at noon)
+- **Google Sheets connector** (open source) — the Sheets auth flow is now part of the OSS package
+- **Tagging API** — tag CRUD, tag history, tag-key management, and batch tag endpoints
+- **Blank-canvas workflow entry point** — a "Blank Workflow" option plus an "Or start from a description" handoff to Discover
+- **MCP setup in cloud settings** — a dedicated MCP configuration section in account settings
+- **Action Block selector + AI fallback fields** — direct control over element targeting and fallback behavior
+- **Block-scoped parameter prompts in the debugger** — prompts scoped to the specific block under test
+- **Runs tab on the browser session page** — every run tied to a given session, in one place
+- **Smarter element targeting** — deterministic HTML element-tree compression for more reliable selectors
+- **Saudi Arabia proxy** — `RESIDENTIAL_SA` added as a geolocation option
+- **Password manager migration notice** — UI banner when password manager settings need updating
+- **Loop block failure-handling UI** — clearer display of how failures are handled within loop blocks
+- **OpenAI CUA model** now configurable via feature flag
+
+**Improvements**
+- **Cross-run extraction cache** — recurring scheduled workflows reuse extraction results across runs when page content hasn't changed, cutting redundant LLM calls
+- MCP runs are now classified as `manual`, matching UI-triggered model routing and queueing
+- MCP tool call performance telemetry tracks latency and errors across all MCP tool invocations
+- Generic remote browser vendor support — evaluate third-party CDP providers via a JSON config, including HTTP/HTTPS DevTools endpoints
+- Scheduled-trigger badge on the global Runs page
+- Faster GET workflow run API
+- Faster script-mode runs (skip speculative extract-action steps) and faster proxy selection in script mode
+- Reduced scroll-into-view settle time for snappier agent actions
+- LLM router retries with a fallback model when a response is cut off by a length limit
+- Prompt token cap prevents context-window overflows on high-complexity workflows
+- Extraction prompts capped in size before LLM calls, reducing `429 RESOURCE_EXHAUSTED` errors on high-volume workflows
+- Hardened prompt input sanitization — untrusted page content is sanitized consistently at the template layer
+- Automatic webhook retry on transient infrastructure failures
+- Signed artifact content URLs with configurable expiry, plus presigned-URL fallback for self-hosted downloads
+- Archived-artifact status indicator on runs
+- Output-parameter size cap to avoid oversized payloads
+- Double-click action support and PDF embed detection inside multi-frame pages
+- Content blocking disabled for authenticated browser launches, improving login success rates
+- Browser dialogs (alert/confirm/prompt) surfaced to the agent so it can adapt
+- TOTP scoped to the active credential, and shown as placeholder text instead of pre-filled
+- Clearer Browsers vs. Browser Profiles descriptions, and a toast action-button polish pass
+- msedge is the default browser for self-hosted templates; quickstart bootstraps `.env` files
+- Fewer screenshots captured for API-triggered runs, lowering storage overhead
+- Auto-route browser type from browser profile source
+- Reduced scrape-phase mouse movement on recaptcha-protected sites
+- Renamed browser profile reset endpoint to `/browser_session/reset_profile` for clarity
+- Removed deprecated Anthropic and Bedrock Claude model configs
+
+**Bug fixes**
+- Fixed workflow run download links showing a storage path instead of the real filename
+- Fixed the Schedules panel not being dismissable from the workflow canvas
+- Fixed scheduled runs not appearing on the global Runs page
+- Fixed webhook delivery silently failing on transient 403, 5xx, or network errors
+- Fixed webhook delivery failing on URLs with leading/trailing spaces
+- Fixed popup pages and XHR-triggered downloads not being captured in runs and recordings
+- Fixed child tasks not terminating and runs getting resurrected after a cleanup-cron timeout
+- Fixed reCAPTCHA v2 invisible variant being misidentified as v3
+- Fixed inline Press & Hold captchas not solving when the challenge renders without a modal wrapper
+- Fixed the large `+` button in the editor closing the block menu instead of pinning it open
+- Fixed the browser profile dropdown in Start-node settings clipping its last item
+- Fixed credential tests started from the UI running on a lower-priority tier
+- Fixed several Copilot edge cases — credential scope after edits, session context across turns, dropped proposals, and feasibility stalls
+- Fixed copilot proposing a workflow it had just failed to build
+- Fixed embedded multi-placeholder secrets not resolving in workflow credentials
+- Fixed self-serve billing for accounts on top-up credit plans
+- Fixed 2FA entry on pages with custom overlay input components
+- Fixed CSV parsing failing on wide-format files with large header rows
+- Fixed browser crash on sites with cross-origin stylesheets (MUI-based apps)
+- Fixed context-window overflow failures being misdiagnosed as generic errors
+- Fixed workflow file-download blocks losing `download_suffix`
+- Fixed cached scripts generating incorrect `fill_form()` calls
+- Fixed run recordings missing end timestamps and broken scrubbing
+- Fixed tag input fields not selecting dropdown values on job application forms
+- Fixed per-step video sync spawning redundant ffmpeg processes
+- Fixed workflow parameter buttons hidden behind long parameter names
+- Fixed quickstart failing on Windows due to missing `DATABASE_STRING`
+- Fixed 1Password upstream failures showing unclear failure reasons
diff --git a/docs/changelog-emails/images/2026-04-01-copilot-v2.png b/docs/changelog-emails/images/2026-04-01-copilot-v2.png
new file mode 100644
index 000000000..074d3f03f
Binary files /dev/null and b/docs/changelog-emails/images/2026-04-01-copilot-v2.png differ
diff --git a/docs/changelog-emails/images/2026-04-02-mcp-oauth.png b/docs/changelog-emails/images/2026-04-02-mcp-oauth.png
new file mode 100644
index 000000000..1c4973d6e
Binary files /dev/null and b/docs/changelog-emails/images/2026-04-02-mcp-oauth.png differ
diff --git a/docs/changelog-emails/images/2026-04-03-cli-schedule-config.png b/docs/changelog-emails/images/2026-04-03-cli-schedule-config.png
new file mode 100644
index 000000000..b54762995
Binary files /dev/null and b/docs/changelog-emails/images/2026-04-03-cli-schedule-config.png differ
diff --git a/docs/changelog-emails/images/2026-04-04-ai-summarize.png b/docs/changelog-emails/images/2026-04-04-ai-summarize.png
new file mode 100644
index 000000000..bdb09c104
Binary files /dev/null and b/docs/changelog-emails/images/2026-04-04-ai-summarize.png differ
diff --git a/docs/changelog-emails/images/2026-04-05-error-code-mapping.png b/docs/changelog-emails/images/2026-04-05-error-code-mapping.png
new file mode 100644
index 000000000..18e8f16d4
Binary files /dev/null and b/docs/changelog-emails/images/2026-04-05-error-code-mapping.png differ
diff --git a/docs/changelog-emails/images/2026-04-06-debugger-run-dialog.png b/docs/changelog-emails/images/2026-04-06-debugger-run-dialog.png
new file mode 100644
index 000000000..292ba3174
Binary files /dev/null and b/docs/changelog-emails/images/2026-04-06-debugger-run-dialog.png differ
diff --git a/docs/changelog-emails/images/2026-05-00-header.png b/docs/changelog-emails/images/2026-05-00-header.png
new file mode 100644
index 000000000..ad4b50be4
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-00-header.png differ
diff --git a/docs/changelog-emails/images/2026-05-01-draggable-editor.png b/docs/changelog-emails/images/2026-05-01-draggable-editor.png
new file mode 100644
index 000000000..1312fcd12
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-01-draggable-editor.png differ
diff --git a/docs/changelog-emails/images/2026-05-02-run-page-redesign.png b/docs/changelog-emails/images/2026-05-02-run-page-redesign.png
new file mode 100644
index 000000000..ad2c8a746
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-02-run-page-redesign.png differ
diff --git a/docs/changelog-emails/images/2026-05-03-while-loop.png b/docs/changelog-emails/images/2026-05-03-while-loop.png
new file mode 100644
index 000000000..b0193660d
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-03-while-loop.png differ
diff --git a/docs/changelog-emails/images/2026-05-04-analytics-dashboard.png b/docs/changelog-emails/images/2026-05-04-analytics-dashboard.png
new file mode 100644
index 000000000..2684c2c24
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-04-analytics-dashboard.png differ
diff --git a/docs/changelog-emails/images/2026-05-05-copilot.png b/docs/changelog-emails/images/2026-05-05-copilot.png
new file mode 100644
index 000000000..185c4a654
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-05-copilot.png differ
diff --git a/docs/changelog-emails/images/2026-05-06-run-control.png b/docs/changelog-emails/images/2026-05-06-run-control.png
new file mode 100644
index 000000000..c4f6ec5a1
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-06-run-control.png differ
diff --git a/docs/changelog-emails/images/2026-05-07-self-hosting.png b/docs/changelog-emails/images/2026-05-07-self-hosting.png
new file mode 100644
index 000000000..124c79c24
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-07-self-hosting.png differ
diff --git a/docs/changelog-emails/images/2026-05-08-browser-profiles.png b/docs/changelog-emails/images/2026-05-08-browser-profiles.png
new file mode 100644
index 000000000..a95f2ec8c
Binary files /dev/null and b/docs/changelog-emails/images/2026-05-08-browser-profiles.png differ
diff --git a/docs/changelog-emails/templates/changelog-header-template.png b/docs/changelog-emails/templates/changelog-header-template.png
new file mode 100644
index 000000000..60018e2e7
Binary files /dev/null and b/docs/changelog-emails/templates/changelog-header-template.png differ
diff --git a/skyvern-frontend/src/routes/workflows/editor/Workspace.tsx b/skyvern-frontend/src/routes/workflows/editor/Workspace.tsx
index 2ba8a675d..5f5da207c 100644
--- a/skyvern-frontend/src/routes/workflows/editor/Workspace.tsx
+++ b/skyvern-frontend/src/routes/workflows/editor/Workspace.tsx
@@ -52,7 +52,6 @@ import { useBlockScriptStore } from "@/store/BlockScriptStore";
import { useBlockSidebarWidthStore } from "@/store/BlockSidebarWidthStore";
import { useCacheKeyValueStore } from "@/store/CacheKeyValueStore";
import { useRecordingStore } from "@/store/useRecordingStore";
-import { useSidebarStore } from "@/store/SidebarStore";
import { useShowAllCodeStore } from "@/store/ShowAllCodeStore";
import { useSidebarSaveStateStore } from "@/store/SidebarSaveStateStore";
import { useWorkflowHistoryAccessStore } from "@/store/WorkflowHistoryAccessStore";
@@ -101,6 +100,7 @@ import { cn } from "@/util/utils";
import { FlowRenderer, type FlowRendererProps } from "./FlowRenderer";
import { useCacheKeyValueUrlSync } from "./hooks/useCacheKeyValueUrlSync";
import { useSaveWorkflow } from "./hooks/useSaveWorkflow";
+import { useWorkspaceMountInitialization } from "./hooks/useWorkspaceMountInitialization";
import { useWorkflowHistory } from "./hooks/useWorkflowHistory";
import { AppNode, isWorkflowBlockNode, WorkflowBlockNode } from "./nodes";
import { blockTypeFromNode } from "./nodes/blockTypeFromNode";
@@ -622,10 +622,6 @@ function Workspace({
const activeDebugSession = debugSession ?? null;
- const setCollapsed = useSidebarStore((state) => {
- return state.setCollapsed;
- });
-
const workflowChangesStore = useWorkflowHasChangesStore();
const showBreakoutButton =
@@ -793,15 +789,12 @@ function Workspace({
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [workflowPermanentId]);
- useMountEffect(() => {
- setCollapsed(true);
- workflowChangesStore.setHasChanges(false);
- if (workflowPermanentId) {
- queryClient.invalidateQueries({
- queryKey: ["cache-key-values", workflowPermanentId, cacheKey],
- });
- }
- closeWorkflowPanel();
+ useWorkspaceMountInitialization({
+ cacheKey,
+ closeWorkflowPanel,
+ queryClient,
+ workflowChangesStore,
+ workflowPermanentId,
});
useCacheKeyValueUrlSync(cacheKeyInitWpidRef.current === workflowPermanentId);
diff --git a/skyvern-frontend/src/routes/workflows/editor/hooks/useWorkspaceMountInitialization.test.tsx b/skyvern-frontend/src/routes/workflows/editor/hooks/useWorkspaceMountInitialization.test.tsx
new file mode 100644
index 000000000..7619ecaa8
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/editor/hooks/useWorkspaceMountInitialization.test.tsx
@@ -0,0 +1,40 @@
+import { QueryClient } from "@tanstack/react-query";
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { useSidebarStore } from "@/store/SidebarStore";
+
+import { useWorkspaceMountInitialization } from "./useWorkspaceMountInitialization";
+
+afterEach(() => {
+ useSidebarStore.setState({ collapsed: false });
+ window.localStorage.clear();
+ vi.restoreAllMocks();
+});
+
+describe("useWorkspaceMountInitialization", () => {
+ test("keeps the global sidebar expanded when the workflow builder opens", () => {
+ const queryClient = new QueryClient();
+ const invalidateQueries = vi.spyOn(queryClient, "invalidateQueries");
+ const workflowChangesStore = { setHasChanges: vi.fn() };
+ const closeWorkflowPanel = vi.fn();
+ useSidebarStore.setState({ collapsed: false });
+
+ renderHook(() =>
+ useWorkspaceMountInitialization({
+ cacheKey: "default",
+ closeWorkflowPanel,
+ queryClient,
+ workflowChangesStore,
+ workflowPermanentId: "wpid_abc",
+ }),
+ );
+
+ expect(useSidebarStore.getState().collapsed).toBe(false);
+ expect(workflowChangesStore.setHasChanges).toHaveBeenCalledWith(false);
+ expect(invalidateQueries).toHaveBeenCalledWith({
+ queryKey: ["cache-key-values", "wpid_abc", "default"],
+ });
+ expect(closeWorkflowPanel).toHaveBeenCalledOnce();
+ });
+});
diff --git a/skyvern-frontend/src/routes/workflows/editor/hooks/useWorkspaceMountInitialization.ts b/skyvern-frontend/src/routes/workflows/editor/hooks/useWorkspaceMountInitialization.ts
new file mode 100644
index 000000000..37eced90d
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/editor/hooks/useWorkspaceMountInitialization.ts
@@ -0,0 +1,35 @@
+import type { QueryClient } from "@tanstack/react-query";
+
+import { useMountEffect } from "@/hooks/useMountEffect";
+
+type WorkflowChangesStore = {
+ setHasChanges: (hasChanges: boolean) => void;
+};
+
+type WorkspaceMountInitializationOptions = {
+ cacheKey: string;
+ closeWorkflowPanel: () => void;
+ queryClient: Pick<QueryClient, "invalidateQueries">;
+ workflowChangesStore: WorkflowChangesStore;
+ workflowPermanentId?: string;
+};
+
+function useWorkspaceMountInitialization({
+ cacheKey,
+ closeWorkflowPanel,
+ queryClient,
+ workflowChangesStore,
+ workflowPermanentId,
+}: WorkspaceMountInitializationOptions) {
+ useMountEffect(() => {
+ workflowChangesStore.setHasChanges(false);
+ if (workflowPermanentId) {
+ queryClient.invalidateQueries({
+ queryKey: ["cache-key-values", workflowPermanentId, cacheKey],
+ });
+ }
+ closeWorkflowPanel();
+ });
+}
+
+export { useWorkspaceMountInitialization };
diff --git a/skyvern/forge/agent_functions.py b/skyvern/forge/agent_functions.py
index cdd79d753..8407d98ee 100644
--- a/skyvern/forge/agent_functions.py
+++ b/skyvern/forge/agent_functions.py
@@ -44,7 +44,7 @@ from skyvern.webeye.utils.page import SkyvernFrame
if TYPE_CHECKING:
from skyvern.forge.sdk.db.enums import WorkflowRunTriggerType
- from skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowRun
+ from skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowRun, WorkflowRunStatus
LOG = structlog.get_logger()
@@ -1333,6 +1333,7 @@ class AgentFunction:
self,
organization_id: str,
workflow_id: str,
+ status: "WorkflowRunStatus | None" = None,
) -> None:
"""Fired after a workflow run reaches a final status. Overrides must be best-effort and never raise."""
return None
diff --git a/skyvern/forge/sdk/copilot/composition_browser_expressions.py b/skyvern/forge/sdk/copilot/composition_browser_expressions.py
index 7f1b875e9..b1f90a4d7 100644
--- a/skyvern/forge/sdk/copilot/composition_browser_expressions.py
+++ b/skyvern/forge/sdk/copilot/composition_browser_expressions.py
@@ -2,6 +2,28 @@
from __future__ import annotations
+import json
+
+from skyvern.forge.sdk.copilot.composition_evidence import (
+ _ANTI_BOT_PATTERNS,
+ _ANTI_BOT_SCAN_BYTES,
+ _MAX_CHALLENGE_CONTROLS,
+ _MAX_FIELDS_PER_FORM,
+ _MAX_FORMS,
+ _MAX_MODAL_DISMISS_CONTROLS,
+ _MAX_MODAL_OVERLAYS,
+ _MAX_NAVIGATION_TARGETS,
+ _MAX_PAGE_OBSTRUCTIONS,
+ _MAX_RESULT_CONTAINERS,
+ _MAX_SELECT_OPTIONS,
+ _MAX_VISIBLE_TEXT_EXCERPT_CHARS,
+ _MODAL_DISMISS_HINTS,
+ _MODAL_DISMISS_SYMBOLS,
+ _MODAL_IDENTITY_PATTERNS,
+ _MODAL_ROLE_VALUES,
+ _RESULT_CONTAINER_HINTS,
+)
+
# Keep stripped-body evaluate results under the shared MCP response cap while
# preserving as much below-fold page structure as possible.
COMPOSITION_STRIPPED_HTML_MAX_CHARS = 135000
@@ -64,3 +86,285 @@ COMPOSITION_VISUAL_OBSTRUCTION_CANDIDATES_EXPRESSION = (
" return candidates;"
"})()"
)
+
+# Safety bound; an over-cap payload is treated as a failed extraction and falls back to get_html.
+COMPOSITION_STRUCTURED_EVIDENCE_MAX_CHARS = 120_000
+
+# Injected from composition_evidence so the JS matches the parser's caps/vocabulary (single source of truth).
+_STRUCTURED_CONST_HEADER = (
+ f"const ANTI_BOT_PATTERNS={json.dumps(list(_ANTI_BOT_PATTERNS))};"
+ f"const MODAL_IDENTITY_PATTERNS={json.dumps(sorted(_MODAL_IDENTITY_PATTERNS))};"
+ f"const MODAL_ROLE_VALUES={json.dumps(sorted(_MODAL_ROLE_VALUES))};"
+ f"const MODAL_DISMISS_HINTS={json.dumps(sorted(_MODAL_DISMISS_HINTS))};"
+ f"const MODAL_DISMISS_SYMBOLS={json.dumps(sorted(_MODAL_DISMISS_SYMBOLS))};"
+ f"const RESULT_CONTAINER_HINTS={json.dumps(sorted(_RESULT_CONTAINER_HINTS))};"
+ f"const MAX_FORMS={int(_MAX_FORMS)};"
+ f"const MAX_FIELDS_PER_FORM={int(_MAX_FIELDS_PER_FORM)};"
+ f"const MAX_NAVIGATION_TARGETS={int(_MAX_NAVIGATION_TARGETS)};"
+ f"const MAX_RESULT_CONTAINERS={int(_MAX_RESULT_CONTAINERS)};"
+ f"const MAX_SELECT_OPTIONS={int(_MAX_SELECT_OPTIONS)};"
+ f"const MAX_CHALLENGE_CONTROLS={int(_MAX_CHALLENGE_CONTROLS)};"
+ f"const MAX_MODAL_OVERLAYS={int(_MAX_MODAL_OVERLAYS)};"
+ f"const MAX_MODAL_DISMISS_CONTROLS={int(_MAX_MODAL_DISMISS_CONTROLS)};"
+ f"const MAX_PAGE_OBSTRUCTIONS={int(_MAX_PAGE_OBSTRUCTIONS)};"
+ f"const MAX_VISIBLE_TEXT_EXCERPT_CHARS={int(_MAX_VISIBLE_TEXT_EXCERPT_CHARS)};"
+ f"const ANTI_BOT_SCAN_BYTES={int(_ANTI_BOT_SCAN_BYTES)};"
+)
+
+# Mirrors parse_composition_html's structural extraction; Python re-bounds the values to the exact caps.
+_STRUCTURED_EVIDENCE_BODY = r"""
+const lower = (v) => String(v == null ? '' : v).toLowerCase();
+// Cap fields in-page so a giant element can't bloat the JSON past the size bound; Python re-bounds.
+const FIELD_CAP = 2048;
+const cap = (s) => (s.length > FIELD_CAP ? s.slice(0, FIELD_CAP) : s);
+const attr = (el, k) => { const v = el && el.getAttribute ? el.getAttribute(k) : null; return typeof v === 'string' ? cap(v.trim()) : ''; };
+const nodeText = (el) => { if (!el) return ''; return cap(String(el.textContent || '').replace(/\s+/g, ' ').trim()); };
+const classesFor = (el) => Array.from((el && el.classList) || []).map((c) => String(c).trim()).filter(Boolean);
+const cssAttr = (v) => String(v).split('\\').join('\\\\').split('"').join('\\"');
+const simpleIdent = (v) => { if (!v) return false; if (!/[A-Za-z_-]/.test(v[0])) return false; for (let i = 1; i < v.length; i++) { if (!/[A-Za-z0-9_-]/.test(v[i])) return false; } return true; };
+const classSelector = (classes) => { const parts = []; for (const c of classes.slice(0, 3)) { parts.push(simpleIdent(c) ? '.' + c : '[class~="' + cssAttr(c) + '"]'); } return parts.join(''); };
+const selectorFor = (el) => {
+ const tag = (el.tagName || '*').toLowerCase();
+ const id = attr(el, 'id'); if (id) return '#' + id;
+ const name = attr(el, 'name'); const value = attr(el, 'value');
+ if (name && value) return tag + '[name="' + cssAttr(name) + '"][value="' + cssAttr(value) + '"]';
+ const classes = classesFor(el); const cs = classSelector(classes);
+ if (cs && value) return tag + cs + '[value="' + cssAttr(value) + '"]';
+ if (name) return tag + '[name="' + cssAttr(name) + '"]';
+ const href = attr(el, 'href');
+ if (tag === 'a' && href) return 'a[href="' + cssAttr(href) + '"]';
+ if (cs) return tag + cs;
+ return tag;
+};
+const FIELD_TAGS = new Set(['input', 'select', 'textarea', 'button']);
+const adjacentText = (field) => {
+ for (const dir of ['next', 'prev']) {
+ let sib = dir === 'next' ? field.nextSibling : field.previousSibling;
+ let count = 0;
+ while (sib && count < 4) {
+ const isEl = sib.nodeType === 1;
+ const tag = isEl ? sib.tagName.toLowerCase() : '';
+ if (isEl && FIELD_TAGS.has(tag)) break;
+ const text = isEl ? nodeText(sib) : String(sib.textContent || '').trim();
+ if (text) return text;
+ sib = dir === 'next' ? sib.nextSibling : sib.previousSibling;
+ count++;
+ }
+ }
+ return '';
+};
+const parentTextLabel = (field) => {
+ for (const tag of ['td', 'th', 'li', 'div', 'span']) {
+ const p = field.closest ? field.closest(tag) : null;
+ if (!p) continue;
+ const text = nodeText(p);
+ if (text.length > 0 && text.length <= 240) return text;
+ }
+ return '';
+};
+const fieldLabel = (field) => {
+ const id = attr(field, 'id');
+ if (id) {
+ let lab = null;
+ try { lab = document.querySelector('label[for="' + cssAttr(id) + '"]'); } catch (e) { lab = null; }
+ if (lab) { const t = nodeText(lab); if (t) return t; }
+ }
+ const parentLabel = field.closest ? field.closest('label') : null;
+ if (parentLabel) {
+ const ft = nodeText(field);
+ let t = nodeText(parentLabel);
+ if (ft) t = t.split(ft).join('');
+ t = t.trim();
+ if (t) return t;
+ }
+ for (const v of [attr(field, 'aria-label'), adjacentText(field), parentTextLabel(field), attr(field, 'title'), attr(field, 'value')]) {
+ if (v) return v;
+ }
+ return '';
+};
+const selectOptions = (el) => {
+ const out = [];
+ const opts = el.querySelectorAll('option');
+ for (let i = 0; i < opts.length && out.length < MAX_SELECT_OPTIONS; i++) {
+ out.push({ text: nodeText(opts[i]), value: attr(opts[i], 'value'), selected: opts[i].hasAttribute('selected') });
+ }
+ return out;
+};
+const controlDisabled = (el) => !!(el.hasAttribute('disabled') || lower(attr(el, 'aria-disabled')) === 'true' || lower(attr(el, 'data-disabled')) === 'true');
+const modalIdentity = (el) => [
+ (el.tagName || '').toLowerCase(), attr(el, 'id'), classesFor(el).join(' '), attr(el, 'role'),
+ attr(el, 'aria-label'), attr(el, 'title'), attr(el, 'data-testid'), attr(el, 'data-test'), attr(el, 'data-dismiss'),
+].join(' ').toLowerCase();
+const isModalCandidate = (el) => {
+ if (MODAL_ROLE_VALUES.includes(lower(attr(el, 'role')).trim())) return true;
+ if (lower(attr(el, 'aria-modal')).trim() === 'true') return true;
+ const ident = modalIdentity(el);
+ return MODAL_IDENTITY_PATTERNS.some((p) => ident.includes(p));
+};
+const isHiddenModal = (el) => {
+ let cur = el;
+ while (cur && cur.nodeType === 1) {
+ if (lower(attr(cur, 'aria-hidden')).trim() === 'true') return true;
+ if (cur.hasAttribute && cur.hasAttribute('hidden')) return true;
+ const style = lower(attr(cur, 'style')).split(' ').join('');
+ if (style.includes('display:none') || style.includes('visibility:hidden')) return true;
+ cur = cur.parentElement;
+ }
+ return false;
+};
+const modalDismissControls = (node) => {
+ const out = [];
+ const seen = new Set();
+ for (const c of node.querySelectorAll('button,a,input')) {
+ if (out.length >= MAX_MODAL_DISMISS_CONTROLS) break;
+ const selector = selectorFor(c);
+ if (seen.has(selector)) continue;
+ const text = nodeText(c) || attr(c, 'value');
+ const ariaLabel = attr(c, 'aria-label');
+ const title = attr(c, 'title');
+ const explicit = [text.trim().toLowerCase(), ariaLabel.trim().toLowerCase(), title.trim().toLowerCase()];
+ const identity = (text + ' ' + ariaLabel + ' ' + title + ' ' + modalIdentity(c)).toLowerCase();
+ const hasDataDismiss = c.hasAttribute && c.hasAttribute('data-dismiss');
+ const hasSymbol = MODAL_DISMISS_SYMBOLS.some((s) => explicit.includes(s));
+ const hasText = MODAL_DISMISS_HINTS.some((h) => identity.includes(h));
+ if (!(hasDataDismiss || hasSymbol || hasText)) continue;
+ seen.add(selector);
+ out.push({ tag: (c.tagName || '').toLowerCase(), text: text, aria_label: ariaLabel, title: title, selector: selector, type: attr(c, 'type') });
+ }
+ return out;
+};
+
+const all = document.querySelectorAll('*');
+const SKIP_TAGS = new Set(['script', 'style', 'noscript']);
+
+const forms = [];
+for (const form of document.querySelectorAll('form')) {
+ if (forms.length >= MAX_FORMS) break;
+ const fields = [];
+ const submitControls = [];
+ for (const node of form.querySelectorAll('input,select,textarea,button')) {
+ const tag = (node.tagName || '').toLowerCase();
+ const fieldType = lower(attr(node, 'type') || tag || 'text');
+ if (tag === 'input' && (fieldType === 'hidden' || fieldType === 'reset')) continue;
+ if (tag === 'button' || fieldType === 'submit' || fieldType === 'button') {
+ submitControls.push({ text: nodeText(node) || attr(node, 'value'), name: attr(node, 'name'), id: attr(node, 'id'), value: attr(node, 'value'), class: classesFor(node), type: fieldType, disabled: controlDisabled(node), selector: selectorFor(node) });
+ continue;
+ }
+ if (fields.length >= MAX_FIELDS_PER_FORM) continue;
+ fields.push({ name: attr(node, 'name'), id: attr(node, 'id'), label: fieldLabel(node), type: fieldType, value: attr(node, 'value'), class: classesFor(node), placeholder: attr(node, 'placeholder'), required: !!(node.hasAttribute('required') || lower(attr(node, 'aria-required')) === 'true'), disabled: controlDisabled(node), checked: node.hasAttribute('checked'), options: tag === 'select' ? selectOptions(node) : [], selector: selectorFor(node) });
+ }
+ forms.push({ id: attr(form, 'id'), name: attr(form, 'name'), action: attr(form, 'action'), method: attr(form, 'method'), fields: fields, submit_controls: submitControls });
+}
+
+const navTargets = [];
+const baseHost = location.host.toLowerCase();
+for (const link of document.querySelectorAll('a[href]')) {
+ if (navTargets.length >= MAX_NAVIGATION_TARGETS) break;
+ const rawHref = attr(link, 'href');
+ if (!rawHref || rawHref.startsWith('#') || lower(rawHref).startsWith('javascript:')) continue;
+ let resolved; try { resolved = new URL(rawHref, location.href).href; } catch (e) { continue; }
+ let host; try { host = new URL(resolved).host.toLowerCase(); } catch (e) { continue; }
+ if (!host || host !== baseHost) continue;
+ navTargets.push({ text: nodeText(link), href: resolved, selector: selectorFor(link) });
+}
+
+const resultContainers = [];
+for (const node of all) {
+ if (resultContainers.length >= MAX_RESULT_CONTAINERS) break;
+ const tag = (node.tagName || '').toLowerCase();
+ if (SKIP_TAGS.has(tag)) continue;
+ const identity = (attr(node, 'id') + ' ' + classesFor(node).join(' ')).toLowerCase();
+ if (tag === 'table' || RESULT_CONTAINER_HINTS.some((h) => identity.includes(h))) {
+ resultContainers.push({ tag: tag, id: attr(node, 'id'), selector: selectorFor(node), is_table: tag === 'table' });
+ }
+}
+
+const challengeControls = [];
+const seenChallenge = new Set();
+for (const node of all) {
+ if (challengeControls.length >= MAX_CHALLENGE_CONTROLS) break;
+ const tag = (node.tagName || '').toLowerCase();
+ const identity = [tag, attr(node, 'id'), attr(node, 'name'), '', attr(node, 'src'), attr(node, 'type'), attr(node, 'data-sitekey'), attr(node, 'data-callback'), attr(node, 'data-expired-callback'), attr(node, 'data-error-callback'), attr(node, 'aria-label'), attr(node, 'title')].join(' ').toLowerCase();
+ if (!ANTI_BOT_PATTERNS.some((p) => identity.includes(p))) continue;
+ const selector = selectorFor(node);
+ if (seenChallenge.has(selector)) continue;
+ seenChallenge.add(selector);
+ const entry = { tag: tag, id: attr(node, 'id'), name: attr(node, 'name'), class: classesFor(node), type: attr(node, 'type'), selector: selector, text: nodeText(node) || attr(node, 'aria-label') };
+ for (const k of ['src', 'title', 'data-sitekey', 'data-callback', 'data-expired-callback', 'data-error-callback']) {
+ const v = attr(node, k);
+ if (v) entry[k.split('-').join('_')] = v;
+ }
+ challengeControls.push(entry);
+}
+
+const modalOverlays = [];
+const seenModal = new Set();
+for (const node of all) {
+ if (modalOverlays.length >= MAX_MODAL_OVERLAYS) break;
+ const tag = (node.tagName || '').toLowerCase();
+ if (SKIP_TAGS.has(tag)) continue;
+ if (!isModalCandidate(node)) continue;
+ if (isHiddenModal(node)) continue;
+ const selector = selectorFor(node);
+ if (seenModal.has(selector)) continue;
+ const role = attr(node, 'role');
+ const ariaModal = lower(attr(node, 'aria-modal')).trim() === 'true';
+ const dismiss = modalDismissControls(node);
+ if (!(role || ariaModal || dismiss.length > 0)) continue;
+ seenModal.add(selector);
+ modalOverlays.push({ role: role, aria_modal: ariaModal, id: attr(node, 'id'), class: classesFor(node), selector: selector, text: nodeText(node), dismiss_controls: dismiss });
+}
+
+const visualObstructionCandidates = [];
+const vw = window.innerWidth || document.documentElement.clientWidth || 0;
+const vh = window.innerHeight || document.documentElement.clientHeight || 0;
+const highZ = (v) => { const n = Number.parseFloat(v); return Number.isFinite(n) && n >= 10; };
+const obstructionVisible = (style, rect) => style.display !== 'none' && style.visibility !== 'hidden' && Number.parseFloat(style.opacity || '1') > 0.05 && rect.width > 0 && rect.height > 0;
+const coversViewport = (rect) => vw > 0 && vh > 0 && rect.left <= vw * 0.05 && rect.top <= vh * 0.05 && rect.right >= vw * 0.95 && rect.bottom >= vh * 0.95;
+const obstructionHasControl = (el) => Array.from(el.querySelectorAll('button,a,input,[role="button"]')).some((c) => {
+ const text = ((c.innerText || '') + ' ' + (c.value || '') + ' ' + (c.getAttribute('aria-label') || '')).trim();
+ if (!text) return false;
+ const t = c.tagName.toLowerCase();
+ const ty = (c.getAttribute('type') || '').toLowerCase();
+ return t !== 'input' || ['button', 'submit', 'reset'].includes(ty);
+});
+for (const el of all) {
+ if (visualObstructionCandidates.length >= MAX_PAGE_OBSTRUCTIONS) break;
+ const tag = (el.tagName || '').toLowerCase();
+ if (SKIP_TAGS.has(tag)) continue;
+ let style; try { style = window.getComputedStyle(el); } catch (e) { continue; }
+ if (!['fixed', 'sticky'].includes(style.position)) continue;
+ if (!highZ(style.zIndex)) continue;
+ const rect = el.getBoundingClientRect();
+ if (!obstructionVisible(style, rect) || !coversViewport(rect)) continue;
+ visualObstructionCandidates.push({ source: 'computed_style', position: style.position, coverage: 'viewport', has_visible_controls: obstructionHasControl(el) });
+}
+
+const titleParts = [];
+for (const t of ['title', 'h1']) {
+ const el = document.querySelector(t);
+ const txt = el ? nodeText(el) : '';
+ if (txt && !titleParts.includes(txt)) titleParts.push(txt);
+}
+const pageTitle = titleParts.join(' ');
+// Same scan window as the get_html path (body innerHTML); head-injected challenges are caught by challengeControls.
+const scanHtml = document.body ? document.body.innerHTML : (document.documentElement ? document.documentElement.outerHTML : '');
+const haystack = (pageTitle + '\n' + scanHtml.slice(0, ANTI_BOT_SCAN_BYTES)).toLowerCase();
+const antiBotIndicators = ANTI_BOT_PATTERNS.filter((p) => haystack.includes(p));
+const visibleText = document.body ? (document.body.innerText || '') : '';
+
+return JSON.stringify({
+ page_title: pageTitle,
+ forms: forms,
+ navigation_targets: navTargets,
+ result_containers: resultContainers,
+ challenge_controls: challengeControls,
+ modal_overlays: modalOverlays,
+ visual_obstruction_candidates: visualObstructionCandidates,
+ visible_text_excerpt: visibleText.length > MAX_VISIBLE_TEXT_EXCERPT_CHARS * 2 ? visibleText.slice(0, MAX_VISIBLE_TEXT_EXCERPT_CHARS * 2) : visibleText,
+ body_has_markup: !!(document.body && (document.body.children.length > 0 || (document.body.textContent || '').trim().length > 0)),
+ anti_bot_indicators: antiBotIndicators,
+});
+"""
+
+COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION = "(() => {" + _STRUCTURED_CONST_HEADER + _STRUCTURED_EVIDENCE_BODY + "})()"
diff --git a/skyvern/forge/sdk/copilot/composition_evidence.py b/skyvern/forge/sdk/copilot/composition_evidence.py
index a03f841d5..b1a89a93a 100644
--- a/skyvern/forge/sdk/copilot/composition_evidence.py
+++ b/skyvern/forge/sdk/copilot/composition_evidence.py
@@ -36,6 +36,7 @@ _GOTO_URL_BLOCK_TYPE = "goto_url"
_SCHEMA_EVIDENCE_TOOL = "inspect_page_for_composition"
_STRUCTURED_BROWSER_EVIDENCE_TOOLS: frozenset[str] = frozenset({"evaluate"})
_POST_RUN_CONTINUATION_EVIDENCE_TOOLS: frozenset[str] = frozenset({"inspect_page_for_composition", "evaluate"})
+SCOUT_INTERACTION_EVIDENCE_TOOL = "scout_interaction"
_RESULT_CONTAINER_HINTS: frozenset[str] = frozenset({"result", "results", "record", "records", "row", "rows"})
_MAX_FORMS = 5
_MAX_FIELDS_PER_FORM = 20
@@ -579,6 +580,16 @@ def has_bounded_page_schema(evidence: dict[str, Any]) -> bool:
return evidence.get("observed_empty_page") is True
+def _is_scout_interaction_evidence(evidence: dict[str, Any]) -> bool:
+ # A scout interaction that resolved a concrete selector proves the page rendered
+ # and the element was actionable, so it is non-hollow evidence of the reached
+ # page even without a captured page schema.
+ if evidence.get("source_tool") != SCOUT_INTERACTION_EVIDENCE_TOOL:
+ return False
+ selector = evidence.get("interaction_selector")
+ return isinstance(selector, str) and bool(selector.strip())
+
+
def _evidence_matches_target(
evidence: dict[str, Any] | None,
target_url: str | None,
@@ -592,6 +603,13 @@ def _evidence_matches_target(
inspected_url = evidence.get("inspected_url")
current_url = current_url if isinstance(current_url, str) else None
inspected_url = inspected_url if isinstance(inspected_url, str) else None
+ if _is_scout_interaction_evidence(evidence):
+ if _same_page(current_url, target_url) or _same_page(inspected_url, target_url):
+ return True
+ if allow_post_run_browser_observation and (
+ _same_origin(current_url, target_url) or _same_origin(inspected_url, target_url)
+ ):
+ return True
# A hollow inspection (empty forms/links/result containers, no detected
# challenge) is not observation — `inspect_page_for_composition` can return an
# empty schema when the page had not rendered at capture time, so URL match
@@ -788,6 +806,32 @@ def _current_page_evidence_has_reached_page_credit(
return False
+def _auto_credit_interaction_observation(
+ flow_evidence_by_step: dict[int, tuple[dict[str, Any], str]],
+ consumed_steps: set[int],
+) -> bool:
+ # Bind by trajectory recency, never by source_url: a SPA holds one URL across
+ # interactions, so URL identity would mis-bind. Consume-once keeps each block on a
+ # distinct interaction.
+ for step in sorted(flow_evidence_by_step, reverse=True):
+ if step in consumed_steps:
+ continue
+ evidence, reached_via = flow_evidence_by_step[step]
+ if reached_via != "interaction":
+ continue
+ if not (_is_scout_interaction_evidence(evidence) or has_bounded_page_schema(evidence)):
+ continue
+ consumed_steps.add(step)
+ LOG.info(
+ "copilot_gate_auto_credited_interaction",
+ observation_step=step,
+ source_tool=evidence.get("source_tool"),
+ interaction_selector=evidence.get("interaction_selector"),
+ )
+ return True
+ return False
+
+
def _block_has_observed_page(
ctx: Any,
block: dict[str, Any],
@@ -795,33 +839,37 @@ def _block_has_observed_page(
allow_post_run: bool,
flow_evidence_by_step: dict[int, tuple[dict[str, Any], str]],
block_observation_refs: dict[str, int],
+ consumed_steps: set[int],
) -> bool:
label = str(block.get("label") or "")
if label and label in block_observation_refs:
- evidence_entry = flow_evidence_by_step.get(block_observation_refs[label])
- if evidence_entry is None:
- return False
- evidence, reached_via = evidence_entry
- effective_reached_via = (
- "interaction"
- if _current_page_evidence_has_reached_page_credit(
- evidence,
- reached_via,
- flow_evidence_by_step=flow_evidence_by_step,
+ step = block_observation_refs[label]
+ evidence_entry = flow_evidence_by_step.get(step)
+ if evidence_entry is not None:
+ evidence, reached_via = evidence_entry
+ effective_reached_via = (
+ "interaction"
+ if _current_page_evidence_has_reached_page_credit(
+ evidence,
+ reached_via,
+ flow_evidence_by_step=flow_evidence_by_step,
+ )
+ else reached_via
)
- else reached_via
- )
- return _associated_observation_satisfies_block(
- evidence,
- block.get("target_url"),
- acts_via=str(block.get("acts_via") or ""),
- reached_via=effective_reached_via,
- requires_observation_ref=block.get("requires_observation_ref") is True,
- allow_post_run=allow_post_run,
- )
+ if _associated_observation_satisfies_block(
+ evidence,
+ block.get("target_url"),
+ acts_via=str(block.get("acts_via") or ""),
+ reached_via=effective_reached_via,
+ requires_observation_ref=block.get("requires_observation_ref") is True,
+ allow_post_run=allow_post_run,
+ ):
+ if effective_reached_via == "interaction":
+ consumed_steps.add(step)
+ return True
if block.get("requires_observation_ref") is True:
- return False
+ return _auto_credit_interaction_observation(flow_evidence_by_step, consumed_steps)
return _page_observed(ctx, block.get("target_url"), allow_post_run=allow_post_run)
@@ -928,6 +976,7 @@ def composition_page_evidence_error(
)
if block_observation_refs is None:
block_observation_refs = _block_observation_refs(ctx)
+ consumed_steps: set[int] = set()
for block in gated_blocks:
target_url = block["target_url"]
if not _block_has_observed_page(
@@ -936,6 +985,7 @@ def composition_page_evidence_error(
allow_post_run=allow_post_run,
flow_evidence_by_step=flow_evidence_by_step,
block_observation_refs=block_observation_refs,
+ consumed_steps=consumed_steps,
):
missing_step = _missing_observation_ref_step(
block,
@@ -1616,3 +1666,279 @@ def parse_composition_html(html: str, *, inspected_url: str, current_url: str) -
"source_tool": "inspect_page_for_composition",
**_evidence_metadata(anti_bot_indicators, forms=forms),
}
+
+
+def _structured_str(value: Any) -> str:
+ return value if isinstance(value, str) else ""
+
+
+def _structured_classes(value: Any) -> str:
+ if not isinstance(value, list):
+ return ""
+ classes = [str(item).strip() for item in value if isinstance(item, str) and str(item).strip()]
+ return " ".join(classes[:5])[:160]
+
+
+def _structured_select_options(value: Any) -> list[dict[str, Any]]:
+ options: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return options
+ for option in value[:_MAX_SELECT_OPTIONS]:
+ if not isinstance(option, dict):
+ continue
+ options.append(
+ {
+ "text": _structured_str(option.get("text"))[:120],
+ "value": _structured_str(option.get("value")).strip()[:160],
+ "selected": option.get("selected") is True,
+ }
+ )
+ return options
+
+
+def _structured_form(form: Any) -> dict[str, Any] | None:
+ if not isinstance(form, dict):
+ return None
+ fields: list[dict[str, Any]] = []
+ for node in form.get("fields") or []:
+ if not isinstance(node, dict) or len(fields) >= _MAX_FIELDS_PER_FORM:
+ continue
+ field_type = (_structured_str(node.get("type")) or "text").lower()
+ fields.append(
+ {
+ "name": _structured_str(node.get("name"))[:120],
+ "id": _structured_str(node.get("id"))[:120],
+ "label": _schema_text(_structured_str(node.get("label")), 240),
+ "type": field_type[:40],
+ "value": _structured_str(node.get("value")).strip()[:160],
+ "class": _structured_classes(node.get("class")),
+ "placeholder": _schema_text(_structured_str(node.get("placeholder")), 240),
+ "required": node.get("required") is True,
+ "disabled": node.get("disabled") is True,
+ "checked": node.get("checked") is True,
+ "options": _structured_select_options(node.get("options")),
+ "selector": _structured_str(node.get("selector"))[:160],
+ }
+ )
+ submit_controls: list[dict[str, Any]] = []
+ for control in form.get("submit_controls") or []:
+ if not isinstance(control, dict):
+ continue
+ submit_controls.append(
+ {
+ "text": _schema_text(_structured_str(control.get("text")), 120),
+ "name": _structured_str(control.get("name"))[:120],
+ "id": _structured_str(control.get("id"))[:120],
+ "value": _structured_str(control.get("value")).strip()[:160],
+ "class": _structured_classes(control.get("class")),
+ "type": (_structured_str(control.get("type")) or "").lower()[:40],
+ "disabled": control.get("disabled") is True,
+ "selector": _structured_str(control.get("selector"))[:160],
+ }
+ )
+ return {
+ "id": _structured_str(form.get("id"))[:120],
+ "name": _structured_str(form.get("name"))[:120],
+ "action": _structured_str(form.get("action"))[:240],
+ "method": _structured_str(form.get("method"))[:20],
+ "fields": fields,
+ "submit_controls": submit_controls[:10],
+ }
+
+
+def _structured_navigation_targets(value: Any, *, base_url: str) -> list[dict[str, Any]]:
+ targets: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return targets
+ for link in value:
+ if len(targets) >= _MAX_NAVIGATION_TARGETS:
+ break
+ if not isinstance(link, dict):
+ continue
+ href = _structured_str(link.get("href")).strip()
+ if not href or href.startswith("#") or href.lower().startswith("javascript:"):
+ continue
+ if not _same_origin(href, base_url):
+ continue
+ targets.append(
+ {
+ "text": _schema_text(_structured_str(link.get("text")), 160),
+ "href": href[:300],
+ "selector": _structured_str(link.get("selector"))[:160],
+ }
+ )
+ return targets
+
+
+def _structured_result_containers(value: Any) -> list[dict[str, Any]]:
+ containers: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return containers
+ for node in value:
+ if len(containers) >= _MAX_RESULT_CONTAINERS:
+ break
+ if not isinstance(node, dict):
+ continue
+ tag_name = (_structured_str(node.get("tag")) or "").lower()
+ selector = _structured_str(node.get("selector"))[:160]
+ entry: dict[str, Any] = {
+ "tag": tag_name,
+ "id": _structured_str(node.get("id"))[:120],
+ "selector": selector,
+ }
+ if tag_name == "table" or node.get("is_table") is True:
+ entry["row_selector"] = f"{selector} tbody tr"
+ entry["expand_toggle_candidates"] = [
+ f"{selector} tbody tr [aria-expanded]",
+ f'{selector} tbody tr [role="button"]',
+ f"{selector} tbody tr button",
+ f"{selector} tbody tr a",
+ f"{selector} tbody tr td:first-child",
+ ]
+ containers.append(entry)
+ return containers
+
+
+def _structured_challenge_controls(value: Any) -> list[dict[str, Any]]:
+ controls: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return controls
+ for node in value[:_MAX_CHALLENGE_CONTROLS]:
+ if not isinstance(node, dict):
+ continue
+ entry: dict[str, Any] = {
+ "tag": (_structured_str(node.get("tag")) or "").lower(),
+ "id": _structured_str(node.get("id"))[:120],
+ "name": _structured_str(node.get("name"))[:120],
+ "class": _structured_classes(node.get("class")),
+ "type": _structured_str(node.get("type"))[:40],
+ "selector": _structured_str(node.get("selector"))[:160],
+ "text": _schema_text(_structured_str(node.get("text")), 200),
+ }
+ for key in ("src", "title", "data_sitekey", "data_callback", "data_expired_callback", "data_error_callback"):
+ field_value = _structured_str(node.get(key)).strip()
+ if field_value:
+ entry[key] = field_value[:300]
+ controls.append({k: v for k, v in entry.items() if v})
+ return controls
+
+
+def _structured_modal_dismiss_controls(value: Any) -> list[dict[str, Any]]:
+ controls: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return controls
+ for control in value[:_MAX_MODAL_DISMISS_CONTROLS]:
+ if not isinstance(control, dict):
+ continue
+ entry = {
+ "tag": (_structured_str(control.get("tag")) or "").lower()[:40],
+ "text": _schema_text(_structured_str(control.get("text")), 120),
+ "aria_label": _schema_text(_structured_str(control.get("aria_label")), 120),
+ "title": _schema_text(_structured_str(control.get("title")), 120),
+ "selector": _structured_str(control.get("selector"))[:160],
+ "type": _structured_str(control.get("type"))[:40],
+ }
+ controls.append({k: v for k, v in entry.items() if v})
+ return controls
+
+
+def _structured_modal_overlays(value: Any) -> list[dict[str, Any]]:
+ overlays: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return overlays
+ for node in value[:_MAX_MODAL_OVERLAYS]:
+ if not isinstance(node, dict):
+ continue
+ entry = {
+ "role": _structured_str(node.get("role"))[:80],
+ "aria_modal": node.get("aria_modal") is True,
+ "id": _structured_str(node.get("id"))[:120],
+ "class": _structured_classes(node.get("class")),
+ "selector": _structured_str(node.get("selector"))[:160],
+ "text": _schema_text(_structured_str(node.get("text")), 240),
+ "dismiss_controls": _structured_modal_dismiss_controls(node.get("dismiss_controls")),
+ }
+ overlays.append(
+ {key: field_value for key, field_value in entry.items() if field_value or key == "dismiss_controls"}
+ )
+ return overlays
+
+
+def _structured_visual_obstruction_candidates(value: Any) -> list[dict[str, Any]]:
+ candidates: list[dict[str, Any]] = []
+ if not isinstance(value, list):
+ return candidates
+ for item in value:
+ if len(candidates) >= _MAX_PAGE_OBSTRUCTIONS:
+ break
+ if not isinstance(item, dict):
+ continue
+ position = item.get("position")
+ if position not in {"fixed", "sticky"} or item.get("coverage") != "viewport":
+ continue
+ candidates.append(
+ {
+ # computed_style: from getComputedStyle, matching the obstruction-augmentation path.
+ "source": "computed_style",
+ "position": position,
+ "coverage": "viewport",
+ "has_visible_controls": item.get("has_visible_controls") is True,
+ }
+ )
+ return candidates
+
+
+def parse_composition_structured(data: Any, *, inspected_url: str, current_url: str) -> dict[str, Any] | None:
+ """Map the structured-evidence JSON to the same PageEvidence dict; None falls back to the get_html path."""
+ if not isinstance(data, dict):
+ return None
+ base_url = current_url or inspected_url
+ page_title = _schema_text(_structured_str(data.get("page_title")), 240)
+ forms = [form for form in (_structured_form(item) for item in data.get("forms") or []) if form is not None]
+ forms = forms[:_MAX_FORMS]
+ navigation_targets = _structured_navigation_targets(data.get("navigation_targets"), base_url=base_url)
+ result_containers = _structured_result_containers(data.get("result_containers"))
+ challenge_controls = _structured_challenge_controls(data.get("challenge_controls"))
+ modal_overlays = _structured_modal_overlays(data.get("modal_overlays"))
+ page_obstructions = _page_obstructions_from_modal_overlays(modal_overlays)
+ visual_obstruction_candidates = _structured_visual_obstruction_candidates(data.get("visual_obstruction_candidates"))
+ visible_text = _schema_text(_structured_str(data.get("visible_text_excerpt")), _MAX_VISIBLE_TEXT_EXCERPT_CHARS)
+
+ # Re-validate JS-reported indicators against _ANTI_BOT_PATTERNS and union a title scan.
+ reported = {indicator for indicator in (data.get("anti_bot_indicators") or []) if isinstance(indicator, str)}
+ matched = reported | set(_anti_bot_indicators("", page_title))
+ anti_bot_indicators = [pattern for pattern in _ANTI_BOT_PATTERNS if pattern in matched]
+
+ field_count = sum(len(form.get("fields") or []) for form in forms)
+ control_count = sum(len(form.get("submit_controls") or []) for form in forms)
+ # body_has_markup mirrors the HTML path's html.strip() for schema-empty parity.
+ body_has_markup = data.get("body_has_markup") is True
+ schema_empty_page = bool(body_has_markup or visible_text or page_title) and not (
+ forms
+ or navigation_targets
+ or result_containers
+ or challenge_controls
+ or page_obstructions
+ or anti_bot_indicators
+ )
+ confidence = 0.85 if field_count and control_count else 0.6 if field_count else 0.3 if forms else 0.1
+ return {
+ "inspected_url": inspected_url,
+ "current_url": current_url,
+ "page_title": page_title,
+ "forms": forms,
+ "navigation_targets": navigation_targets,
+ "result_containers": result_containers,
+ "visible_text_excerpt": visible_text,
+ "anti_bot_indicators": anti_bot_indicators,
+ "challenge_controls": challenge_controls,
+ "modal_overlays": modal_overlays,
+ "page_obstructions": page_obstructions,
+ "visual_obstruction_candidates": visual_obstruction_candidates,
+ "schema_empty_page": schema_empty_page,
+ "observed_empty_page": False,
+ "empty_page_visual_state": None,
+ "evidence_confidence": confidence,
+ "source_tool": "inspect_page_for_composition",
+ **_evidence_metadata(anti_bot_indicators, forms=forms),
+ }
diff --git a/skyvern/forge/sdk/copilot/runtime.py b/skyvern/forge/sdk/copilot/runtime.py
index 624a9d135..517904895 100644
--- a/skyvern/forge/sdk/copilot/runtime.py
+++ b/skyvern/forge/sdk/copilot/runtime.py
@@ -6,7 +6,7 @@ import asyncio
import inspect
from contextlib import asynccontextmanager
from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, AsyncIterator, Awaitable, TypeAlias, cast
+from typing import TYPE_CHECKING, Any, AsyncIterator, Awaitable, NotRequired, TypeAlias, TypedDict, cast
import structlog
@@ -106,6 +106,15 @@ class PendingBrowserInteractionObservation:
url: str = ""
+class ScoutedInteraction(TypedDict):
+ tool_name: str
+ selector: NotRequired[str]
+ source_url: NotRequired[str]
+ value: NotRequired[str]
+ key: NotRequired[str]
+ typed_length: NotRequired[int]
+
+
@dataclass
class AgentContext:
organization_id: str
@@ -216,6 +225,11 @@ class AgentContext:
post_run_page_observation_workflow_run_id: str | None = None
post_run_page_observation_after_failed_test: bool = False
post_run_current_page_inspection_workflow_run_id: str | None = None
+ observed_browser_urls: list[str] = field(default_factory=list)
+ # Ephemeral within-turn scout captures; not persisted across turns.
+ scouted_interactions: list[ScoutedInteraction] = field(default_factory=list)
+ # Source page of an in-flight scout action, captured before it may navigate away.
+ pending_scout_source_url: str | None = None
# Set by tool gates / loop guards / tool-side error branches when a tool
# dispatch is blocked. The finalization shim in agent.py reads this at
diff --git a/skyvern/forge/sdk/copilot/tools.py b/skyvern/forge/sdk/copilot/tools.py
index 357c447b0..e3a05b605 100644
--- a/skyvern/forge/sdk/copilot/tools.py
+++ b/skyvern/forge/sdk/copilot/tools.py
@@ -61,16 +61,24 @@ from skyvern.forge.sdk.copilot.composition_browser_expressions import (
from skyvern.forge.sdk.copilot.composition_browser_expressions import (
COMPOSITION_STRIPPED_HTML_MAX_CHARS as _COMPOSITION_STRIPPED_HTML_MAX_CHARS,
)
+from skyvern.forge.sdk.copilot.composition_browser_expressions import (
+ COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION as _COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION,
+)
+from skyvern.forge.sdk.copilot.composition_browser_expressions import (
+ COMPOSITION_STRUCTURED_EVIDENCE_MAX_CHARS as _COMPOSITION_STRUCTURED_EVIDENCE_MAX_CHARS,
+)
from skyvern.forge.sdk.copilot.composition_browser_expressions import (
COMPOSITION_VISUAL_OBSTRUCTION_CANDIDATES_EXPRESSION as _COMPOSITION_VISUAL_OBSTRUCTION_CANDIDATES_EXPRESSION,
)
from skyvern.forge.sdk.copilot.composition_evidence import (
+ SCOUT_INTERACTION_EVIDENCE_TOOL,
composition_page_evidence_error,
has_bounded_page_schema,
merge_visual_composition_evidence,
normalize_block_observation_refs,
page_evidence_needs_visual_fallback,
parse_composition_html,
+ parse_composition_structured,
workflow_target_url,
)
from skyvern.forge.sdk.copilot.config import BlockAuthoringPolicy, normalize_block_authoring_policy
@@ -121,6 +129,7 @@ from skyvern.forge.sdk.copilot.request_policy import CREDENTIAL_DEFERRED_DRAFT_R
from skyvern.forge.sdk.copilot.runtime import (
AgentContext,
PendingBrowserInteractionObservation,
+ ScoutedInteraction,
ensure_browser_session,
)
from skyvern.forge.sdk.copilot.screenshot_utils import enqueue_screenshot_from_result
@@ -1490,6 +1499,103 @@ def _consume_pending_browser_interaction_observation(
return True
+_MAX_SCOUTED_INTERACTIONS = 20
+
+
+async def _live_working_page_url(ctx: AgentContext) -> str | None:
+ if not ctx.browser_session_id:
+ return None
+ try:
+ browser_state = await app.PERSISTENT_SESSIONS_MANAGER.get_browser_state(
+ session_id=ctx.browser_session_id,
+ organization_id=ctx.organization_id,
+ )
+ if not browser_state:
+ return None
+ page = await browser_state.get_or_create_page()
+ return page.url if page else None
+ except Exception:
+ return None
+
+
+async def _capture_scout_source_url(ctx: AgentContext) -> None:
+ # Pre-action: a navigating click/Enter would leave only the destination URL, not the page the selector acted on.
+ ctx.pending_scout_source_url = await _live_working_page_url(ctx)
+
+
+def _consume_scout_source_url(ctx: AgentContext) -> str | None:
+ source_url = ctx.pending_scout_source_url
+ # Cleared unconditionally so a non-recording action can't bleed its source page into a later interaction.
+ ctx.pending_scout_source_url = None
+ return source_url
+
+
+def _record_scouted_interaction(
+ ctx: AgentContext,
+ *,
+ tool_name: str,
+ selector: str = "",
+ source_url: str | None = None,
+ value: str = "",
+ key: str = "",
+ typed_length: int = 0,
+) -> None:
+ selector = selector.strip()
+ # press_key may be page-level, so it is recorded by key even with no selector; other tools require one.
+ if tool_name != "press_key" and not selector:
+ return
+ artifact: ScoutedInteraction = {"tool_name": tool_name}
+ if selector:
+ artifact["selector"] = selector
+ if source_url and source_url.strip():
+ artifact["source_url"] = source_url.strip()
+ if value:
+ artifact["value"] = value
+ if key:
+ artifact["key"] = key
+ if typed_length:
+ artifact["typed_length"] = typed_length
+ interactions = [
+ item
+ for item in ctx.scouted_interactions
+ if not (
+ item.get("tool_name") == artifact["tool_name"]
+ and item.get("selector") == artifact.get("selector")
+ and item.get("source_url") == artifact.get("source_url")
+ )
+ ]
+ interactions.append(artifact)
+ ctx.scouted_interactions = interactions[-_MAX_SCOUTED_INTERACTIONS:]
+ LOG.info(
+ "copilot_scout_interaction_captured",
+ tool_name=tool_name,
+ selector=selector or None,
+ source_url=artifact.get("source_url"),
+ total_scouted_interactions=len(ctx.scouted_interactions),
+ )
+
+
+def _register_scout_interaction_observation(
+ ctx: AgentContext, *, tool_name: str, selector: str, source_url: str | None, url: str
+) -> int | None:
+ # A successful scout interaction reaches the post-action page; record it as an
+ # interaction-reached observation so a click-reached block can be authored
+ # against it without a separate inspect_page_for_composition.
+ selector = selector.strip()
+ if not selector or not url:
+ return None
+ evidence: dict[str, Any] = {
+ "inspected_url": url,
+ "current_url": url,
+ "source_tool": SCOUT_INTERACTION_EVIDENCE_TOOL,
+ "interaction_tool": tool_name,
+ "interaction_selector": selector,
+ }
+ if source_url and source_url.strip():
+ evidence["interaction_source_url"] = source_url.strip()
+ return _append_flow_evidence(ctx, evidence, reached_via="interaction")
+
+
def _mark_post_run_page_observed(ctx: AgentContext, *, source_tool: str, url: str) -> None:
run_id = getattr(ctx, "last_run_blocks_workflow_run_id", None)
if not isinstance(run_id, str) or not run_id:
@@ -5719,6 +5825,7 @@ async def _click_pre_hook(
params: dict[str, Any],
ctx: AgentContext,
) -> dict[str, Any] | None:
+ await _capture_scout_source_url(ctx)
deterministic_result = _strip_intent_for_code_only_selector_action(params, ctx, tool_name="click")
if deterministic_result is not None:
return deterministic_result
@@ -5746,6 +5853,7 @@ async def _type_text_pre_hook(
params: dict[str, Any],
ctx: AgentContext,
) -> dict[str, Any] | None:
+ await _capture_scout_source_url(ctx)
return _strip_intent_for_code_only_selector_action(params, ctx, tool_name="type_text")
@@ -5753,6 +5861,7 @@ async def _select_option_pre_hook(
params: dict[str, Any],
ctx: AgentContext,
) -> dict[str, Any] | None:
+ await _capture_scout_source_url(ctx)
return _strip_intent_for_code_only_selector_action(params, ctx, tool_name="select_option")
@@ -5760,6 +5869,7 @@ async def _press_key_pre_hook(
params: dict[str, Any],
ctx: AgentContext,
) -> dict[str, Any] | None:
+ await _capture_scout_source_url(ctx)
return _strip_intent_for_code_only_selector_action(params, ctx, tool_name="press_key")
@@ -5810,6 +5920,7 @@ async def _click_post_hook(
ctx: AgentContext,
) -> dict[str, Any]:
_clear_pending_browser_interaction_observation(ctx)
+ source_url = _consume_scout_source_url(ctx)
if result.get("ok") and result.get("data"):
data = result["data"]
url, title = await _resolve_url_title(raw, ctx)
@@ -5819,6 +5930,13 @@ async def _click_post_hook(
"url": url,
"title": title,
}
+ _record_scouted_interaction(ctx, tool_name="click", selector=data.get("selector", ""), source_url=source_url)
+ observation_step = _register_scout_interaction_observation(
+ ctx, tool_name="click", selector=data.get("selector", ""), source_url=source_url, url=url
+ )
+ if observation_step is not None:
+ result["observation_step"] = observation_step
+ result["data"]["observation_step"] = observation_step
return result
@@ -5887,6 +6005,7 @@ async def _type_text_post_hook(
ctx: AgentContext,
) -> dict[str, Any]:
_clear_pending_browser_interaction_observation(ctx)
+ source_url = _consume_scout_source_url(ctx)
if result.get("ok") and result.get("data"):
data = result["data"]
selector = data.get("selector", "")
@@ -5901,6 +6020,15 @@ async def _type_text_post_hook(
if landing_failure is not None:
return landing_failure
_mark_pending_browser_interaction_observation(ctx, tool_name="type_text", url=url)
+ _record_scouted_interaction(
+ ctx, tool_name="type_text", selector=selector, source_url=source_url, typed_length=typed_length
+ )
+ observation_step = _register_scout_interaction_observation(
+ ctx, tool_name="type_text", selector=selector, source_url=source_url, url=url
+ )
+ if observation_step is not None:
+ result["observation_step"] = observation_step
+ result["data"]["observation_step"] = observation_step
return result
@@ -5967,6 +6095,7 @@ async def _select_option_post_hook(
ctx: AgentContext,
) -> dict[str, Any]:
_clear_pending_browser_interaction_observation(ctx)
+ source_url = _consume_scout_source_url(ctx)
if result.get("ok") and result.get("data"):
data = result["data"]
url, _ = await _resolve_url_title(raw, ctx)
@@ -5976,6 +6105,19 @@ async def _select_option_post_hook(
"value": data.get("value", ""),
"url": url,
}
+ _record_scouted_interaction(
+ ctx,
+ tool_name="select_option",
+ selector=data.get("selector", ""),
+ source_url=source_url,
+ value=data.get("value", ""),
+ )
+ observation_step = _register_scout_interaction_observation(
+ ctx, tool_name="select_option", selector=data.get("selector", ""), source_url=source_url, url=url
+ )
+ if observation_step is not None:
+ result["observation_step"] = observation_step
+ result["data"]["observation_step"] = observation_step
return result
@@ -5985,6 +6127,7 @@ async def _press_key_post_hook(
ctx: AgentContext,
) -> dict[str, Any]:
_clear_pending_browser_interaction_observation(ctx)
+ source_url = _consume_scout_source_url(ctx)
if result.get("ok") and result.get("data"):
data = result["data"]
url, _ = await _resolve_url_title(raw, ctx)
@@ -5994,6 +6137,13 @@ async def _press_key_post_hook(
"selector": data.get("selector", ""),
"url": url,
}
+ _record_scouted_interaction(
+ ctx,
+ tool_name="press_key",
+ selector=data.get("selector", ""),
+ source_url=source_url,
+ key=data.get("key", ""),
+ )
return result
@@ -8154,6 +8304,15 @@ async def _composition_evidence_after_navigation_failure(
) -> dict[str, Any] | None:
current_url, _ = await _fallback_page_info(ctx)
current_url = current_url or inspected_url
+ structured = await _composition_get_structured_evidence(ctx, inspected_url=inspected_url, current_url=current_url)
+ if structured is not None and has_bounded_page_schema(structured):
+ evidence = _composition_add_inspection_warning(
+ structured,
+ f"navigation_error_before_html_capture: {navigation_error}",
+ )
+ if page_evidence_needs_visual_fallback(evidence):
+ evidence = await _augment_composition_evidence_with_visual_fallback(ctx, evidence)
+ return evidence
# Same size-cap survival as the success path: a heavy page that rendered before the nav
# error still parses via the stripped-body evaluate instead of yielding hollow evidence.
html, html_error, html_truncated, _ = await _composition_get_html(ctx)
@@ -8425,6 +8584,43 @@ async def _composition_get_html(copilot_ctx: Any, *, skip_raw: bool = False) ->
return "", str(error) if error else None, False, True
+async def _composition_get_structured_evidence(
+ copilot_ctx: Any,
+ *,
+ inspected_url: str,
+ current_url: str,
+) -> dict[str, Any] | None:
+ """Capture composition evidence via the page-side extractor; None when it can't yield a usable payload."""
+ server = getattr(copilot_ctx, "discovery_mcp_server", None)
+ if server is None:
+ return None
+ with copilot_span("composition_structured_extract"):
+ try:
+ result = await asyncio.wait_for(
+ server.call_internal_tool(
+ "skyvern_evaluate", {"expression": _COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION}
+ ),
+ timeout=_DISCOVERY_PER_CALL_TIMEOUT_SECONDS,
+ )
+ except Exception:
+ return None
+ if not isinstance(result, dict) or not result.get("ok"):
+ return None
+ raw = (result.get("data") or {}).get("result")
+ if isinstance(raw, str):
+ if len(raw) > _COMPOSITION_STRUCTURED_EVIDENCE_MAX_CHARS:
+ return None
+ try:
+ payload = json.loads(raw)
+ except (ValueError, TypeError):
+ return None
+ elif isinstance(raw, dict):
+ payload = raw
+ else:
+ return None
+ return parse_composition_structured(payload, inspected_url=inspected_url, current_url=current_url)
+
+
async def _capture_composition_evidence(
copilot_ctx: Any,
*,
@@ -8432,22 +8628,27 @@ async def _capture_composition_evidence(
current_url: str,
active_run_terminal_sample: bool = False,
) -> tuple[dict[str, Any] | None, str | None]:
- """Read page HTML and parse composition evidence, recapturing on a hollow read.
-
- The capture (`_composition_get_html`) survives the MCP size cap; this loop adds a
- short settle and re-read for the separate case where the page had not finished
- rendering at capture time (a cold cloud session's first navigate to a heavy page
- can hand back a shell). Returns (evidence, html_error); html_error is set only
- when the HTML read itself failed. Stops early once the parse yields a bounded
- schema (forms/links/result containers/challenge), so a genuine challenge page is
- not retried.
- """
+ """Parse composition evidence (cheap extractor first, get_html fallback); html_error is set only on a failed HTML read."""
evidence: dict[str, Any] | None = None
html_truncated = False
+ used_structured = False
skip_raw = False
for attempt in range(_COMPOSITION_HOLLOW_RECAPTURE_RETRIES + 1):
+ structured = await _composition_get_structured_evidence(
+ copilot_ctx, inspected_url=inspected_url, current_url=current_url
+ )
+ if structured is not None:
+ evidence = structured
+ used_structured = True
+ if has_bounded_page_schema(evidence):
+ break
+ if attempt < _COMPOSITION_HOLLOW_RECAPTURE_RETRIES:
+ await asyncio.sleep(_COMPOSITION_HOLLOW_RECAPTURE_DELAY_SECONDS)
+ continue
html, html_error, html_truncated, used_stripped = await _composition_get_html(copilot_ctx, skip_raw=skip_raw)
if html_error is not None:
+ if evidence is not None:
+ break
return None, html_error
# On a heavy page the raw get_html serialization is dropped over the MCP size cap and
# falls back to the stripped read; once that happens, settle-and-recapture via the
@@ -8455,13 +8656,15 @@ async def _capture_composition_evidence(
if used_stripped:
skip_raw = True
evidence = parse_composition_html(html, inspected_url=inspected_url, current_url=current_url)
+ used_structured = False
if has_bounded_page_schema(evidence):
break
if attempt < _COMPOSITION_HOLLOW_RECAPTURE_RETRIES:
await asyncio.sleep(_COMPOSITION_HOLLOW_RECAPTURE_DELAY_SECONDS)
- if evidence is not None and html_truncated:
+ if evidence is not None and html_truncated and not used_structured:
evidence = _composition_add_inspection_warning(evidence, "html_sliced_at_cap")
- if evidence is not None:
+ # Structured evidence already carries computed obstruction candidates; only the get_html path augments.
+ if evidence is not None and not used_structured:
evidence = await _augment_composition_evidence_with_computed_obstruction_candidates(copilot_ctx, evidence)
if evidence is not None and (
page_evidence_needs_visual_fallback(evidence)
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index 6e8a227c7..e6b6270c2 100644
--- a/skyvern/forge/sdk/db/models.py
+++ b/skyvern/forge/sdk/db/models.py
@@ -309,10 +309,13 @@ class WorkflowTagEventModel(Base):
"""Append-only event log for workflow tags.
Every state change writes a new row. SET events carry value; DELETE
- events have value=NULL and carry their own attribution. Supersession
- sets superseded_at on the previously-current row so the partial unique
- index keeps exactly one active SET per (org, wpid, key). superseded_at
- means "no longer current but still historical fact"; deleted_at follows
+ events carry their own attribution (and a value only for standalone-label
+ deletes, which are identified by value). A tag is a label (value, always
+ present) with an optional group (key): grouped labels are identified by
+ key, standalone labels by value. Two partial unique indexes keep exactly
+ one active SET per (org, wpid, key) for grouped labels and per
+ (org, wpid, value) for standalone labels. superseded_at means "no longer
+ current but still historical fact"; deleted_at follows
the same soft-delete convention as SoftDeleteMixin (via a manual column)
and is separate.
@@ -343,15 +346,36 @@ class WorkflowTagEventModel(Base):
postgresql_include=["workflow_permanent_id"],
postgresql_where=text("superseded_at IS NULL AND event_type = 'set'"),
),
+ # Powers the value-only ("filter by label") term, which matches a value
+ # across any/no group.
+ Index(
+ "workflow_tag_events_org_value_active_idx",
+ "organization_id",
+ "value",
+ postgresql_include=["workflow_permanent_id"],
+ postgresql_where=text("superseded_at IS NULL AND event_type = 'set'"),
+ ),
Index("workflow_tag_events_org_set_at_idx", "organization_id", "set_at"),
+ # One active SET per group (key) on a workflow = one-label-per-group.
Index(
- "workflow_tag_events_active_set_unique",
+ "workflow_tag_events_active_grouped_unique",
"organization_id",
"workflow_permanent_id",
"key",
unique=True,
- postgresql_where=text("superseded_at IS NULL AND event_type = 'set'"),
- sqlite_where=text("superseded_at IS NULL AND event_type = 'set'"),
+ postgresql_where=text("superseded_at IS NULL AND event_type = 'set' AND key IS NOT NULL"),
+ sqlite_where=text("superseded_at IS NULL AND event_type = 'set' AND key IS NOT NULL"),
+ ),
+ # A standalone label (no group) is identified by its value, so it gets
+ # its own one-active-SET-per-value uniqueness.
+ Index(
+ "workflow_tag_events_active_label_unique",
+ "organization_id",
+ "workflow_permanent_id",
+ "value",
+ unique=True,
+ postgresql_where=text("superseded_at IS NULL AND event_type = 'set' AND key IS NULL"),
+ sqlite_where=text("superseded_at IS NULL AND event_type = 'set' AND key IS NULL"),
),
CheckConstraint("event_type IN ('set', 'delete')", name="ck_workflow_tag_events_event_type"),
CheckConstraint(
@@ -362,13 +386,16 @@ class WorkflowTagEventModel(Base):
"caller_type IS NULL OR caller_type IN ('user', 'api_key', 'system')",
name="ck_workflow_tag_events_caller_type",
),
- CheckConstraint("event_type != 'delete' OR value IS NULL", name="ck_workflow_tag_events_delete_null_value"),
+ # SET rows require a value; DELETE rows carry a value (standalone-label
+ # delete) or null (grouped delete, identified by key).
+ CheckConstraint("event_type != 'set' OR value IS NOT NULL", name="ck_workflow_tag_events_set_has_value"),
)
tag_event_id = Column(String, primary_key=True, default=generate_tag_event_id)
workflow_permanent_id = Column(String, nullable=False)
organization_id = Column(String, ForeignKey("organizations.organization_id"), nullable=False)
- key = Column(String, nullable=False)
+ # Nullable: null = standalone label (group-less); non-null = grouped label.
+ key = Column(String, nullable=True)
value = Column(String, nullable=True)
event_type = Column(String, nullable=False)
set_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)
diff --git a/skyvern/forge/sdk/db/repositories/otp.py b/skyvern/forge/sdk/db/repositories/otp.py
index 1586babb6..96e8ed808 100644
--- a/skyvern/forge/sdk/db/repositories/otp.py
+++ b/skyvern/forge/sdk/db/repositories/otp.py
@@ -22,6 +22,7 @@ class OTPRepository(BaseRepository):
valid_lifespan_minutes: int = settings.TOTP_LIFESPAN_MINUTES,
otp_type: OTPType | None = None,
workflow_run_id: str | None = None,
+ created_after: datetime | None = None,
limit: int | None = None,
) -> list[TOTPCode]:
"""
@@ -29,6 +30,7 @@ class OTPRepository(BaseRepository):
- organization_id
- totp_identifier
- workflow_run_id (optional)
+ - created_after (optional): only codes created at/after this instant
2. make sure created_at is within the valid lifespan
3. sort by task_id/workflow_id/workflow_run_id nullslast and created_at desc
4. apply an optional limit at the DB layer
@@ -51,6 +53,8 @@ class OTPRepository(BaseRepository):
query = query.filter(TOTPCodeModel.otp_type == otp_type)
if workflow_run_id is not None:
query = query.filter(TOTPCodeModel.workflow_run_id == workflow_run_id)
+ if created_after is not None:
+ query = query.filter(TOTPCodeModel.created_at >= created_after)
query = query.order_by(asc(all_null), TOTPCodeModel.created_at.desc())
if limit is not None:
query = query.limit(limit)
diff --git a/skyvern/forge/sdk/db/repositories/tags.py b/skyvern/forge/sdk/db/repositories/tags.py
index df008c16e..a0077227e 100644
--- a/skyvern/forge/sdk/db/repositories/tags.py
+++ b/skyvern/forge/sdk/db/repositories/tags.py
@@ -32,9 +32,10 @@ register_passthrough_exception(TagCountLimitExceeded)
@dataclass(frozen=True)
class TagChange:
- """One concrete state change derived from a caller's set/delete request."""
+ """One concrete state change derived from a caller's set/delete request.
+ ``key`` is None for a standalone label (identified by its value)."""
- key: str
+ key: str | None
new_value: str | None
event_type: TagEventType
superseded_event_id: str | None
@@ -51,53 +52,66 @@ class TagsRepository(BaseRepository):
sets: dict[str, str],
deletes: set[str],
context: TagWriteContext,
+ label_sets: list[str] | None = None,
+ label_deletes: list[str] | None = None,
) -> list[TagChange]:
- """Atomically apply SET/DELETE events for a workflow's tags. Sets win
- over deletes on same-key collision; same-value SETs are no-ops. Same-key
- concurrent writers race the partial UNIQUE — the loser's IntegrityError
- is not caught here, so it surfaces to the caller as a 5xx."""
+ """Atomically apply SET/DELETE tag events. Grouped tags via ``sets``/``deletes``
+ (keys), standalone labels via ``label_sets``/``label_deletes``; set wins over delete."""
+ label_sets = label_sets or []
+ label_deletes = label_deletes or []
+ label_set_values = set(label_sets)
effective_deletes = {k for k in deletes if k not in sets}
- if not sets and not effective_deletes:
+ effective_label_deletes = {v for v in label_deletes if v not in label_set_values}
+ if not sets and not effective_deletes and not label_set_values and not effective_label_deletes:
return []
now = datetime.now(timezone.utc)
async with self.Session() as session:
- current = await self._get_current_active_set_events(
+ active_rows = await self._get_active_set_rows(
session,
workflow_permanent_id=workflow_permanent_id,
organization_id=organization_id,
)
-
- # Soft cap: concurrent distinct-key writers can each pass; partial
- # UNIQUE catches only same-key races. Cap is a UX rule, acceptable.
- projected_keys = (set(current.keys()) | set(sets.keys())) - effective_deletes
- if len(projected_keys) > MAX_TAGS_PER_WORKFLOW:
+ # Grouped tags keyed by their group; standalone labels keyed by value.
+ grouped_current = {row.key: row for row in active_rows if row.key is not None}
+ label_current = {row.value: row for row in active_rows if row.key is None}
+
+ # Soft cap: concurrent distinct-identity writers can each pass; the
+ # partial UNIQUEs catch only same-identity races. Cap is a UX rule.
+ projected_grouped = (set(grouped_current.keys()) | set(sets.keys())) - effective_deletes
+ projected_labels = (set(label_current.keys()) | label_set_values) - effective_label_deletes
+ projected_total = len(projected_grouped) + len(projected_labels)
+ if projected_total > MAX_TAGS_PER_WORKFLOW:
raise TagCountLimitExceeded(
- f"workflow {workflow_permanent_id} would have {len(projected_keys)} tags; "
+ f"workflow {workflow_permanent_id} would have {projected_total} tags; "
f"max is {MAX_TAGS_PER_WORKFLOW}"
)
changes: list[TagChange] = []
+ def _add_event(*, key: str | None, value: str | None, event_type: TagEventType) -> None:
+ session.add(
+ WorkflowTagEventModel(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ key=key,
+ value=value,
+ event_type=event_type.value,
+ set_at=now,
+ set_by=context.caller_id,
+ source=context.source.value,
+ caller_type=context.caller_type.value if context.caller_type else None,
+ )
+ )
+
for key, new_value in sets.items():
- existing = current.get(key)
+ existing = grouped_current.get(key)
if existing is not None and existing.value == new_value:
continue
if existing is not None:
existing.superseded_at = now
- event = WorkflowTagEventModel(
- workflow_permanent_id=workflow_permanent_id,
- organization_id=organization_id,
- key=key,
- value=new_value,
- event_type=TagEventType.SET.value,
- set_at=now,
- set_by=context.caller_id,
- source=context.source.value,
- caller_type=context.caller_type.value if context.caller_type else None,
- )
- session.add(event)
+ _add_event(key=key, value=new_value, event_type=TagEventType.SET)
changes.append(
TagChange(
key=key,
@@ -107,23 +121,22 @@ class TagsRepository(BaseRepository):
)
)
+ # A standalone label's value IS its identity, so an already-present
+ # label is a no-op; otherwise it's a fresh insert (never an overwrite).
+ for value in label_set_values:
+ if value in label_current:
+ continue
+ _add_event(key=None, value=value, event_type=TagEventType.SET)
+ changes.append(
+ TagChange(key=None, new_value=value, event_type=TagEventType.SET, superseded_event_id=None)
+ )
+
for key in effective_deletes:
- existing = current.get(key)
+ existing = grouped_current.get(key)
if existing is None:
continue
existing.superseded_at = now
- event = WorkflowTagEventModel(
- workflow_permanent_id=workflow_permanent_id,
- organization_id=organization_id,
- key=key,
- value=None,
- event_type=TagEventType.DELETE.value,
- set_at=now,
- set_by=context.caller_id,
- source=context.source.value,
- caller_type=context.caller_type.value if context.caller_type else None,
- )
- session.add(event)
+ _add_event(key=key, value=None, event_type=TagEventType.DELETE)
changes.append(
TagChange(
key=key,
@@ -133,22 +146,35 @@ class TagsRepository(BaseRepository):
)
)
+ # Standalone-label DELETE rows carry the value so history records
+ # which label was removed (a group-less delete has no key to identify it).
+ for value in effective_label_deletes:
+ existing = label_current.get(value)
+ if existing is None:
+ continue
+ existing.superseded_at = now
+ _add_event(key=None, value=value, event_type=TagEventType.DELETE)
+ changes.append(
+ TagChange(
+ key=None,
+ new_value=None,
+ event_type=TagEventType.DELETE,
+ superseded_event_id=existing.tag_event_id,
+ )
+ )
+
# Flush UPDATEs-before-INSERTs so the partial UNIQUE sees a
# consistent state when the new SET row hits it.
await session.flush()
- # Auto-register TagKeyModel rows only for keys whose SET actually
- # wrote a new event. The partial UNIQUE on (org, key) WHERE
- # deleted_at IS NULL races concurrent first-use writers, so we use
- # an INSERT ... ON CONFLICT DO NOTHING to swallow the race instead
- # of letting it surface as a 5xx. postgresql and sqlite need their
- # own insert() construct to compile ON CONFLICT, but share the
- # on_conflict_do_nothing signature. Both require index_where to
- # match the partial unique index or ON CONFLICT inference fails.
- changed_set_keys = {c.key for c in changes if c.event_type == TagEventType.SET}
+ # Register a TagKeyModel only for grouped keys with a new SET (standalone
+ # labels have no key). ON CONFLICT DO NOTHING swallows the first-use race.
+ changed_set_keys = {c.key for c in changes if c.event_type == TagEventType.SET and c.key is not None}
if changed_set_keys:
rows = [{"organization_id": organization_id, "key": key} for key in changed_set_keys]
dialect_name = session.bind.dialect.name if session.bind is not None else "postgresql"
+ # postgres/sqlite each need their own insert() for ON CONFLICT; index_where
+ # must match the partial unique index or ON CONFLICT inference fails.
insert = sqlite.insert if dialect_name == "sqlite" else postgresql.insert
insert_stmt = (
insert(TagKeyModel.__table__)
@@ -163,13 +189,15 @@ class TagsRepository(BaseRepository):
await session.commit()
return changes
- async def _get_current_active_set_events(
+ async def _get_active_set_rows(
self,
session: AsyncSession,
*,
workflow_permanent_id: str,
organization_id: str,
- ) -> dict[str, WorkflowTagEventModel]:
+ ) -> list[WorkflowTagEventModel]:
+ """Active (non-superseded, non-deleted) SET event rows for a workflow —
+ both grouped tags and standalone labels."""
stmt = select(WorkflowTagEventModel).where(
and_(
WorkflowTagEventModel.organization_id == organization_id,
@@ -180,17 +208,18 @@ class TagsRepository(BaseRepository):
)
)
result = await session.execute(stmt)
- return {row.key: row for row in result.scalars().all()}
+ return list(result.scalars().all())
- @db_operation("get_active_tags_for_workflow")
- async def get_active_tags_for_workflow(
+ @db_operation("get_active_grouped_tags_for_workflow")
+ async def get_active_grouped_tags_for_workflow(
self,
workflow_permanent_id: str,
organization_id: str,
) -> dict[str, str]:
- """Return the current {key: value} map for a workflow."""
+ """Current {key: value} map of a workflow's grouped tags. Standalone labels
+ (no key) are excluded; use ``get_active_tag_events_for_workflow`` for all tags."""
async with self.Session() as session:
- rows = await self._get_current_active_set_events(
+ rows = await self._get_active_set_rows(
session,
workflow_permanent_id=workflow_permanent_id,
organization_id=organization_id,
@@ -198,17 +227,19 @@ class TagsRepository(BaseRepository):
# SET events always carry a non-null value, but defend against
# data drift: skip-and-log instead of crashing the request.
result: dict[str, str] = {}
- for key, row in rows.items():
+ for row in rows:
+ if row.key is None:
+ continue
if row.value is None:
LOG.warning(
"active SET tag row has null value; skipping",
tag_event_id=row.tag_event_id,
organization_id=organization_id,
workflow_permanent_id=workflow_permanent_id,
- key=key,
+ key=row.key,
)
continue
- result[key] = row.value
+ result[row.key] = row.value
return result
@db_operation("get_active_tag_events_for_workflow")
@@ -217,16 +248,14 @@ class TagsRepository(BaseRepository):
workflow_permanent_id: str,
organization_id: str,
) -> list[WorkflowTagEventModel]:
- """Active SET event rows for a workflow. Carries full attribution
- (source/set_at/set_by) so callers can surface per-tag provenance —
- ``get_active_tags_for_workflow`` returns just key→value."""
+ """Active SET rows (grouped + standalone) with full attribution
+ (source/set_at/set_by) for per-tag provenance."""
async with self.Session() as session:
- rows = await self._get_current_active_set_events(
+ return await self._get_active_set_rows(
session,
workflow_permanent_id=workflow_permanent_id,
organization_id=organization_id,
)
- return list(rows.values())
@db_operation("get_tag_event_history")
async def get_tag_event_history(
@@ -260,10 +289,9 @@ class TagsRepository(BaseRepository):
self,
workflow_permanent_ids: list[str],
organization_id: str,
- ) -> dict[str, dict[str, str]]:
- """Batch read of current SET tags for many workflows. Cross-org isolation
- is enforced by the organization_id filter — wpids that don't belong to
- the org are silently absent from the result (no rows match)."""
+ ) -> dict[str, list[tuple[str | None, str]]]:
+ """Batch read of current SET tags (grouped + standalone) as a list of
+ (key, value) per workflow. The org filter silently drops foreign wpids."""
if not workflow_permanent_ids:
return {}
@@ -279,7 +307,7 @@ class TagsRepository(BaseRepository):
)
rows = (await session.execute(stmt)).scalars().all()
- result: dict[str, dict[str, str]] = {}
+ result: dict[str, list[tuple[str | None, str]]] = {}
for row in rows:
if row.value is None:
LOG.warning(
@@ -290,7 +318,7 @@ class TagsRepository(BaseRepository):
key=row.key,
)
continue
- result.setdefault(row.workflow_permanent_id, {})[row.key] = row.value
+ result.setdefault(row.workflow_permanent_id, []).append((row.key, row.value))
return result
@db_operation("list_tag_keys")
@@ -344,9 +372,8 @@ class TagsRepository(BaseRepository):
@db_operation("count_active_workflows_per_key")
async def count_active_workflows_per_key(self, organization_id: str) -> dict[str, int]:
- """Map of tag key -> number of workflows currently carrying it. The
- partial UNIQUE guarantees one active SET per (workflow, key), so a plain
- row count per key already equals the distinct-workflow count."""
+ """Map of tag key -> number of workflows carrying it (one active SET per
+ (workflow, key), so a row count suffices). Standalone labels are excluded."""
async with self.Session() as session:
stmt = (
select(WorkflowTagEventModel.key, func.count(WorkflowTagEventModel.tag_event_id))
@@ -356,6 +383,7 @@ class TagsRepository(BaseRepository):
WorkflowTagEventModel.superseded_at.is_(None),
WorkflowTagEventModel.event_type == TagEventType.SET.value,
WorkflowTagEventModel.deleted_at.is_(None),
+ WorkflowTagEventModel.key.isnot(None),
)
)
.group_by(WorkflowTagEventModel.key)
diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.py
index 11cf653a3..6fa3fe899 100644
--- a/skyvern/forge/sdk/db/repositories/workflows.py
+++ b/skyvern/forge/sdk/db/repositories/workflows.py
@@ -5,7 +5,7 @@ from datetime import datetime, timezone
from typing import Any, cast
import structlog
-from sqlalchemy import exists, func, or_, select, update
+from sqlalchemy import Select, exists, func, or_, select, update
from skyvern.constants import DEFAULT_SCRIPT_RUN_ID
from skyvern.forge.sdk.db._error_handling import db_operation
@@ -413,7 +413,7 @@ class WorkflowsRepository(BaseRepository):
search_key: str | None = None,
folder_id: str | None = None,
statuses: list[WorkflowStatus] | None = None,
- workflow_tags: list[tuple[str, str]] | None = None,
+ workflow_tags: list[tuple[str | None, str | None]] | None = None,
) -> list[Workflow]:
"""
Get all workflows with the latest version for the organization.
@@ -426,10 +426,15 @@ class WorkflowsRepository(BaseRepository):
- Parameter metadata search excludes soft-deleted parameter rows across parameter tables.
Tag filtering (`workflow_tags`):
- - A list of (key, value) pairs. Pairs are grouped by key; the filter is AND
- across distinct keys and OR within a key's values. One semi-join subquery is
- emitted per distinct key — normalized event rows can't satisfy two `key=`
- predicates at once, so a single conjunctive subquery would match nothing.
+ - A list of (key, value) terms in three shapes: exact ``(key, value)``,
+ group/key-only ``(key, None)``, and label/value-only ``(None, value)``.
+ - The filter is AND across distinct terms, with OR within a key for exact
+ terms sharing that key (so ``env:prod`` + ``env:staging`` is ``env IN
+ (prod, staging)``). One semi-join subquery is emitted per term group —
+ a normalized event row can't satisfy two different ``key=`` predicates
+ at once, so a single conjunctive subquery would match nothing.
+ - A value-only term matches that label across any/no group; a key-only
+ term matches any value within the group.
- Matches only the current value of each tag: superseded and soft-deleted
event rows are excluded, mirroring the active-tag read path.
"""
@@ -481,21 +486,47 @@ class WorkflowsRepository(BaseRepository):
if folder_id:
main_query = main_query.where(WorkflowModel.folder_id == folder_id)
if workflow_tags:
- values_by_key: dict[str, list[str]] = {}
+ exact_values_by_key: dict[str, list[str]] = {}
+ key_only_terms: list[str] = []
+ value_only_terms: list[str] = []
for key, value in workflow_tags:
- values_by_key.setdefault(key, []).append(value)
- for key, values in values_by_key.items():
+ if key is not None and value is not None:
+ exact_values_by_key.setdefault(key, []).append(value)
+ elif key is not None:
+ key_only_terms.append(key)
+ elif value is not None:
+ value_only_terms.append(value)
+
+ def _active_set_subquery() -> Select:
+ return (
+ select(WorkflowTagEventModel.workflow_permanent_id)
+ .where(WorkflowTagEventModel.organization_id == organization_id)
+ .where(WorkflowTagEventModel.deleted_at.is_(None))
+ .where(WorkflowTagEventModel.superseded_at.is_(None))
+ .where(WorkflowTagEventModel.event_type == TagEventType.SET.value)
+ )
+
+ # AND across distinct terms; OR within a key for exact terms.
+ for key, values in exact_values_by_key.items():
main_query = main_query.where(
WorkflowModel.workflow_permanent_id.in_(
- select(WorkflowTagEventModel.workflow_permanent_id)
- .where(WorkflowTagEventModel.organization_id == organization_id)
- .where(WorkflowTagEventModel.deleted_at.is_(None))
- .where(WorkflowTagEventModel.superseded_at.is_(None))
- .where(WorkflowTagEventModel.event_type == TagEventType.SET.value)
+ _active_set_subquery()
.where(WorkflowTagEventModel.key == key)
.where(WorkflowTagEventModel.value.in_(values))
)
)
+ for key in key_only_terms:
+ main_query = main_query.where(
+ WorkflowModel.workflow_permanent_id.in_(
+ _active_set_subquery().where(WorkflowTagEventModel.key == key)
+ )
+ )
+ for value in value_only_terms:
+ main_query = main_query.where(
+ WorkflowModel.workflow_permanent_id.in_(
+ _active_set_subquery().where(WorkflowTagEventModel.value == value)
+ )
+ )
if search_key:
search_like = f"%{search_key}%"
title_like = WorkflowModel.title.ilike(search_like)
diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.py
index b7b0c2cf2..b93c551be 100644
--- a/skyvern/forge/sdk/routes/agent_protocol.py
+++ b/skyvern/forge/sdk/routes/agent_protocol.py
@@ -148,6 +148,7 @@ from skyvern.schemas.tags import (
TagApplyRequest,
TagHistoryItem,
TagHistoryResponse,
+ TagItem,
TagKey,
TagKeyDeleteResponse,
TagKeyUpdate,
@@ -469,7 +470,7 @@ def _workflow_run_request_to_legacy_request(workflow_run_request: WorkflowRunReq
@base_router.post(
"/run/agents",
- tags=["Agents"],
+ tags=["Runs"],
openapi_extra={
"x-fern-sdk-method-name": "run_workflow",
"x-fern-examples": [
@@ -569,7 +570,7 @@ async def run_workflow(
@base_router.get(
"/runs/{run_id}",
- tags=["Agents"],
+ tags=["Runs"],
response_model=RunResponse,
description="Get run information (task run, workflow run)",
summary="Get run info by id",
@@ -611,7 +612,7 @@ async def get_run(
@base_router.post(
"/runs/{run_id}/cancel",
- tags=["Agents"],
+ tags=["Runs"],
openapi_extra={
"x-fern-sdk-method-name": "cancel_run",
"x-fern-examples": [
@@ -639,7 +640,7 @@ async def cancel_run(
@base_router.post(
"/runs/cancel",
- tags=["Agents"],
+ tags=["Runs"],
openapi_extra={
"x-fern-sdk-method-name": "bulk_cancel_runs",
"x-fern-examples": [
@@ -1529,7 +1530,7 @@ async def _assert_workflow_in_org(workflow_permanent_id: str, organization_id: s
def _tag_event_to_response(row: Any) -> TagResponse:
- return TagResponse(value=row.value, source=row.source, set_at=row.set_at, set_by=row.set_by)
+ return TagResponse(key=row.key, value=row.value, source=row.source, set_at=row.set_at, set_by=row.set_by)
def _validate_path_key(key: str) -> None:
@@ -1550,14 +1551,11 @@ async def _apply_tag_changes_with_retry(
sets: dict[str, str],
deletes: set[str],
context: TagWriteContext,
+ label_sets: list[str] | None = None,
+ label_deletes: list[str] | None = None,
) -> None:
- """Wrap ``apply_tag_changes`` with a single IntegrityError retry. The
- Phase 2 repo documents that same-workflow/same-key concurrent SET writers
- race the partial UNIQUE on ``workflow_tag_events_active_set_unique`` and
- the loser surfaces an IntegrityError. Last-write-wins is the right
- semantics here — the retry re-reads current state and either no-ops (same
- value) or supersedes the winner. If the second attempt also conflicts,
- surface as 409 Conflict instead of an unstructured 5xx."""
+ """Wrap ``apply_tag_changes`` with one IntegrityError retry: concurrent
+ same-identity SETs race the partial UNIQUE; last-write-wins, else 409."""
for attempt in range(2):
try:
await app.DATABASE.tags.apply_tag_changes(
@@ -1566,6 +1564,8 @@ async def _apply_tag_changes_with_retry(
sets=sets,
deletes=deletes,
context=context,
+ label_sets=label_sets,
+ label_deletes=label_deletes,
)
return
except IntegrityError:
@@ -1616,13 +1616,21 @@ async def apply_workflow_tags(
source=TagSource.MANUAL,
caller_type=caller.caller_type,
)
+ # A tag's key is its group; grouped tags are keyed (last-wins per group),
+ # standalone labels (no key) are addressed by value.
+ grouped_sets: dict[str, str] = {tag.key: tag.value for tag in data.tags if tag.key is not None}
+ label_sets: list[str] = [tag.value for tag in data.tags if tag.key is None]
+ grouped_deletes: set[str] = {d.key for d in data.tags_to_delete if d.key is not None}
+ label_deletes: list[str] = [d.value for d in data.tags_to_delete if d.key is None and d.value is not None]
try:
await _apply_tag_changes_with_retry(
workflow_permanent_id=workflow_permanent_id,
organization_id=organization_id,
- sets=data.tags,
- deletes=set(data.tags_to_delete),
+ sets=grouped_sets,
+ deletes=grouped_deletes,
context=write_ctx,
+ label_sets=label_sets,
+ label_deletes=label_deletes,
)
except ValueError as e:
# Cap-breach is the only ValueError surfaced; treat as 422 (user input).
@@ -1709,16 +1717,15 @@ async def get_workflow_tags(
async def _build_tags_response(workflow_permanent_id: str, organization_id: str) -> TagsResponse:
- """Read active SET event rows and project them into the response shape."""
+ """Read active SET event rows and project them into the response shape.
+ Sorted by (key, value) — standalone labels (null key) first — for stable output."""
rows = await app.DATABASE.tags.get_active_tag_events_for_workflow(
workflow_permanent_id=workflow_permanent_id,
organization_id=organization_id,
)
- tags: dict[str, TagResponse] = {}
- for row in rows:
- if row.value is None:
- continue
- tags[row.key] = _tag_event_to_response(row)
+ tags = [_tag_event_to_response(row) for row in rows if row.value is not None]
+ # Sort standalone labels (null key) first, then grouped by key, then value.
+ tags.sort(key=lambda t: (t.key is not None, t.key or "", t.value))
return TagsResponse(workflow_permanent_id=workflow_permanent_id, tags=tags)
@@ -1834,7 +1841,7 @@ async def update_tag_key(
@base_router.delete(
"/tag-keys/{key}",
response_model=TagKeyDeleteResponse,
- tags=["Workflow Tags"],
+ tags=["Tags"],
openapi_extra={"x-fern-sdk-method-name": "delete_tag_key"},
description="Delete a tag key from the organization registry and remove that tag from every workflow that "
"currently has it (cascade). Returns how many workflows the tag was removed from.",
@@ -1878,15 +1885,23 @@ def _parse_batch_wpids(raw: str | None) -> list[str]:
return [token.strip() for token in raw.split(",") if token.strip()]
-def _build_batch_response(requested_wpids: list[str], tag_map: dict[str, dict[str, str]]) -> WorkflowTagsBatchResponse:
- """Echo every requested wpid in the response (empty dict if no tags). Tag
- values themselves are already org-filtered by the repo query, so this only
- surfaces wpids the caller already supplied."""
- workflow_tags: dict[str, dict[str, str]] = {wpid: tag_map.get(wpid, {}) for wpid in requested_wpids}
+def _build_batch_response(
+ requested_wpids: list[str], tag_map: dict[str, list[tuple[str | None, str]]]
+) -> WorkflowTagsBatchResponse:
+ """Echo every requested wpid (empty list if no tags). Each list is sorted
+ standalone-first, then by key, then value — the repo SELECT has no ORDER BY."""
+
+ def _sorted(pairs: list[tuple[str | None, str]]) -> list[TagItem]:
+ ordered = sorted(pairs, key=lambda kv: (kv[0] is not None, kv[0] or "", kv[1]))
+ return [TagItem(key=key, value=value) for key, value in ordered]
+
+ workflow_tags: dict[str, list[TagItem]] = {wpid: _sorted(tag_map.get(wpid, [])) for wpid in requested_wpids}
return WorkflowTagsBatchResponse(workflow_tags=workflow_tags)
-async def _resolve_active_batch_wpids(requested_wpids: list[str], organization_id: str) -> dict[str, dict[str, str]]:
+async def _resolve_active_batch_wpids(
+ requested_wpids: list[str], organization_id: str
+) -> dict[str, list[tuple[str | None, str]]]:
"""Return the org-filtered, soft-delete-filtered tag map for the requested
wpids. Two existence checks bracket the tag read so a workflow soft-deleted
*between* the lookup and the tag query doesn't leak stale tag values: the
@@ -2400,7 +2415,7 @@ async def get_run_artifacts(
@base_router.post(
"/runs/{run_id}/retry_webhook",
- tags=["Agents"],
+ tags=["Runs"],
openapi_extra={
"x-fern-sdk-method-name": "retry_run_webhook",
"x-fern-examples": [
@@ -2434,7 +2449,7 @@ async def retry_run_webhook(
@base_router.get(
"/runs/{run_id}/timeline",
- tags=["Agents"],
+ tags=["Runs"],
response_model=list[WorkflowRunTimeline],
openapi_extra={
"x-fern-sdk-method-name": "get_run_timeline",
@@ -2876,7 +2891,7 @@ def _workflow_run_request_from_workflow_request(
@base_router.post(
"/workflows/runs/{workflow_run_id}/retry",
- tags=["Agents"],
+ tags=["Runs"],
response_model=WorkflowRunResponse,
openapi_extra={
"x-fern-sdk-method-name": "retry_workflow_run",
@@ -3450,7 +3465,7 @@ async def run_workflow_legacy(
@base_router.get(
"/workflows/runs",
response_model=list[WorkflowRun],
- tags=["Agents"],
+ tags=["Runs"],
description=(
"List workflow runs across all workflows for the current organization.\n\n"
"Results are paginated and can be filtered by **status**, **search_key**, and **error_code**. "
@@ -3600,7 +3615,7 @@ async def _get_workflow_runs_by_id(
@base_router.get(
"/workflows/{workflow_id}/runs",
response_model=list[WorkflowRun],
- tags=["Agents"],
+ tags=["Runs"],
description=_WORKFLOW_RUNS_BY_ID_DESCRIPTION,
summary="Get all runs by agent",
openapi_extra={
@@ -3903,12 +3918,14 @@ async def get_workflows(
Query(
max_length=20,
description=(
- "Filter by tags as `key:value` pairs. Repeat the param or comma-separate "
- "(`?tags=env:prod,env:staging`). AND across distinct keys, OR within a key "
- "(`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in (prod, staging)). "
+ "Filter by tags. Each term is a label (`production`), a group (`env:*`), "
+ "or a group:label (`env:prod`). Repeat the param or comma-separate "
+ "(`?tags=env:prod,env:staging`). AND across distinct terms, OR within a group's "
+ "labels (`?tags=customer:acme,env:prod,env:staging` -> customer=acme AND env in "
+ "(prod, staging)). A label term matches the value across any/no group. "
"Matches current tag values only. Not supported with `template=true`."
),
- examples=["env:prod", "customer:acme,env:prod"],
+ examples=["env:prod", "production", "env:*", "customer:acme,env:prod"],
),
] = None,
current_org: Organization = Depends(org_auth_service.get_current_org),
@@ -3938,18 +3955,37 @@ async def get_workflows(
tag_groups = tags or []
if tag_groups == [""]:
tag_groups = []
- workflow_tags: list[tuple[str, str]] = []
+ # Split on the FIRST colon: no colon -> value-only (None, value); value `*` ->
+ # group-only (key, None); else exact (key, value), whose value may contain colons.
+ invalid_term_detail = "expected 'label', 'key:*', or 'key:value'"
+ workflow_tags: list[tuple[str | None, str | None]] = []
for raw_group in tag_groups:
- for raw_pair in raw_group.split(","):
- pair = raw_pair.strip()
- tag_key, sep, tag_value = pair.partition(":")
+ for raw_term in raw_group.split(","):
+ term = raw_term.strip()
+ if not term:
+ raise HTTPException(
+ status_code=http_status.HTTP_400_BAD_REQUEST,
+ detail="Invalid tag filter; empty term.",
+ )
+ tag_key, sep, tag_value = term.partition(":")
+ if not sep:
+ workflow_tags.append((None, term))
+ continue
tag_key, tag_value = tag_key.strip(), tag_value.strip()
- if not sep or not tag_key or not tag_value:
+ if not tag_key:
+ raise HTTPException(
+ status_code=http_status.HTTP_400_BAD_REQUEST,
+ detail=f"Invalid tag filter '{term}'; {invalid_term_detail}.",
+ )
+ if tag_value == "*":
+ workflow_tags.append((tag_key, None))
+ elif not tag_value:
raise HTTPException(
status_code=http_status.HTTP_400_BAD_REQUEST,
- detail=f"Invalid tag filter '{pair}'; expected 'key:value'.",
+ detail=f"Invalid tag filter '{term}'; {invalid_term_detail}.",
)
- workflow_tags.append((tag_key, tag_value))
+ else:
+ workflow_tags.append((tag_key, tag_value))
if template and workflow_tags:
# Templates are global; tags are org-scoped, so the two can't combine.
diff --git a/skyvern/forge/sdk/routes/credentials.py b/skyvern/forge/sdk/routes/credentials.py
index 16b168357..2aa3a37c5 100644
--- a/skyvern/forge/sdk/routes/credentials.py
+++ b/skyvern/forge/sdk/routes/credentials.py
@@ -1013,22 +1013,17 @@ async def get_test_credential_status(
workflow = await app.DATABASE.workflows.get_workflow(workflow_run.workflow_id, organization_id)
# Only a save-enabled test has a saver; a plain login test must not report a save failure.
if workflow and workflow.persist_browser_session:
- # finished_at may come back tz-aware from the ORM; normalize once so every comparison /
- # subtraction below stays naive-vs-naive and never raises TypeError.
- run_finished_at = to_naive_utc(workflow_run.finished_at)
save_persisted = False
if browser_profile_id:
profile = await app.DATABASE.browser_sessions.get_browser_profile(
profile_id=browser_profile_id, organization_id=organization_id
)
saved_at = to_naive_utc(profile.modified_at) if profile else None
+ run_finished_at = to_naive_utc(workflow_run.finished_at)
save_persisted = bool(saved_at and run_finished_at and saved_at >= run_finished_at)
if not save_persisted:
browser_profile_id = None
- if (
- run_finished_at
- and (naive_utc_now() - run_finished_at).total_seconds() > _PROFILE_GRACE_PERIOD_SECONDS
- ):
+ if (naive_utc_now() - workflow_run.finished_at).total_seconds() > _PROFILE_GRACE_PERIOD_SECONDS:
browser_profile_failure_reason = (
"Login succeeded but the browser profile could not be saved. Please try testing again."
)
diff --git a/skyvern/forge/sdk/workflow/models/validators.py b/skyvern/forge/sdk/workflow/models/validators.py
index 76678bb8a..74c987ecc 100644
--- a/skyvern/forge/sdk/workflow/models/validators.py
+++ b/skyvern/forge/sdk/workflow/models/validators.py
@@ -13,14 +13,18 @@ RUN_METADATA_MAX_KEY_LENGTH = 64
RUN_METADATA_MAX_VALUE_LENGTH = 256
TAG_DESCRIPTION_MAX_LENGTH = 500
+# A tag is a label (value, always present) with an optional group (key). Keys
+# and values inherit the run_metadata length caps.
+TAG_KEY_MAX_LENGTH = RUN_METADATA_MAX_KEY_LENGTH
+TAG_VALUE_MAX_LENGTH = RUN_METADATA_MAX_VALUE_LENGTH
# Reserved for system-written tags. Uses a regex-valid separator so the
# reservation actually excludes keys a user could otherwise create.
SKYVERN_TAG_NAMESPACE = "skyvern."
# Anchored regex: keys must be URL-safe so they round-trip through path
# (`DELETE .../tags/{key}`) and query (`?tags=k:v`) without escaping.
TAG_KEY_REGEX = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
-# `,` separates pairs in the `?tags=k:v,k2:v2` filter encoding, so it may not
-# appear inside a value. `:` is allowed: the parser splits on the first `:` only.
+# `,` separates terms in the `?tags=` filter encoding, so it may not appear
+# inside a value. `:` is allowed: the parser splits on the first `:` only.
_TAG_VALUE_FORBIDDEN_CHARS = (",",)
@@ -86,36 +90,57 @@ def normalize_run_metadata(v: dict[str, str] | None) -> dict[str, str] | None:
)
-def normalize_tags(v: dict[str, str] | None) -> dict[str, str] | None:
- """Normalize and bound user-supplied workflow tags.
+def _assert_valid_tag_key(key: str) -> None:
+ """Shape rules for a (trimmed, non-empty) tag key / group. Raises ValueError."""
+ if len(key) > TAG_KEY_MAX_LENGTH:
+ raise ValueError(f"tag keys must be at most {TAG_KEY_MAX_LENGTH} characters")
+ if key.startswith(SKYVERN_TAG_NAMESPACE):
+ raise ValueError(f"tag keys must not start with the reserved '{SKYVERN_TAG_NAMESPACE}' prefix")
+ if not TAG_KEY_REGEX.match(key):
+ raise ValueError(
+ "tag keys must match '^[A-Za-z0-9][A-Za-z0-9_.-]*$' "
+ "(alphanumeric, underscore, dot, hyphen; must start with alphanumeric)"
+ )
- Stricter than normalize_run_metadata: keys must match a URL-safe regex
- and may not start with the reserved ``skyvern.`` prefix, and values may
- not contain ``,`` (which would break ``?tags=`` pair parsing).
- """
- normalized = _normalize_kv_dict(
- v,
- max_keys=RUN_METADATA_MAX_KEYS,
- max_key_length=RUN_METADATA_MAX_KEY_LENGTH,
- max_value_length=RUN_METADATA_MAX_VALUE_LENGTH,
- field_name="tags",
- )
- if normalized is None:
+
+def normalize_optional_tag_key(key: object) -> str | None:
+ """Normalize an optional tag key (group). None or blank -> None (standalone
+ label); otherwise trim and enforce the key shape rules."""
+ if key is None:
+ return None
+ if not isinstance(key, str):
+ raise ValueError("tag key must be a string")
+ trimmed = key.strip()
+ if not trimmed:
return None
+ _assert_valid_tag_key(trimmed)
+ return trimmed
+
+
+def normalize_tag_value(value: object) -> str:
+ """Normalize a required tag value (label). Trims, enforces the length cap,
+ and rejects ``,`` (which would break ``?tags=`` term parsing)."""
+ if not isinstance(value, str):
+ raise ValueError("tag value must be a string")
+ trimmed = value.strip()
+ if not trimmed:
+ raise ValueError("tag value is required")
+ if len(trimmed) > TAG_VALUE_MAX_LENGTH:
+ raise ValueError(f"tag values must be at most {TAG_VALUE_MAX_LENGTH} characters")
+ for forbidden in _TAG_VALUE_FORBIDDEN_CHARS:
+ if forbidden in trimmed:
+ raise ValueError(f"tag values must not contain '{forbidden}'")
+ return trimmed
+
- for key, value in normalized.items():
- if key.startswith(SKYVERN_TAG_NAMESPACE):
- raise ValueError(f"tags keys must not start with the reserved '{SKYVERN_TAG_NAMESPACE}' prefix")
- if not TAG_KEY_REGEX.match(key):
- raise ValueError(
- "tags keys must match '^[A-Za-z0-9][A-Za-z0-9_.-]*$' "
- "(alphanumeric, underscore, dot, hyphen; must start with alphanumeric)"
- )
- for forbidden in _TAG_VALUE_FORBIDDEN_CHARS:
- if forbidden in value:
- raise ValueError(f"tags values must not contain '{forbidden}'")
-
- return normalized
+def normalize_optional_tag_value(value: object) -> str | None:
+ """Normalize an optional tag value (the delete path's standalone-label id).
+ None or blank -> None; otherwise apply the required-value rules."""
+ if value is None:
+ return None
+ if isinstance(value, str) and not value.strip():
+ return None
+ return normalize_tag_value(value)
def normalize_tag_description(v: str | None) -> str | None:
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 63df3dcfa..d9c8a70c1 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -228,15 +228,20 @@ def _collect_enterprise_gated_workflow_features(
def _select_recording_urls_in_window(
recordings: Sequence[FileInfo],
lower_bound: datetime,
- upper_bound: datetime,
+ upper_bound: datetime | None = None,
) -> list[str]:
- """Filter recordings to [lower_bound, upper_bound] by modified_at (UTC), sort oldest-first."""
+ """Filter recordings to [lower_bound, upper_bound] by modified_at (UTC), sort oldest-first.
+
+ ``upper_bound=None`` keeps every recording from ``lower_bound`` on. A persistent browser
+ session finalizes its single continuous recording at session close — possibly hours after
+ a run ends — so the bounded window misses it; the unbounded form is the fallback.
+ """
in_window: list[tuple[datetime, str]] = []
for r in recordings:
if r.modified_at is None:
continue
modified_utc = _as_utc(r.modified_at)
- if lower_bound <= modified_utc <= upper_bound:
+ if modified_utc >= lower_bound and (upper_bound is None or modified_utc <= upper_bound):
in_window.append((modified_utc, r.url))
in_window.sort(key=lambda pair: pair[0])
return [url for _, url in in_window]
@@ -4183,7 +4188,7 @@ class WorkflowService:
search_key: str | None = None,
folder_id: str | None = None,
statuses: list[WorkflowStatus] | None = None,
- workflow_tags: list[tuple[str, str]] | None = None,
+ workflow_tags: list[tuple[str | None, str | None]] | None = None,
) -> list[Workflow]:
"""
Get all workflows with the latest version for the organization.
@@ -4191,7 +4196,8 @@ class WorkflowService:
Args:
search_key: Unified search term for title, folder name, and parameter metadata.
folder_id: Filter workflows by folder ID.
- workflow_tags: (key, value) tag filters; AND across keys, OR within a key.
+ workflow_tags: tag filter terms — exact (key, value), group-only (key, None),
+ or label-only (None, value). AND across distinct terms; OR within a key.
"""
return await app.DATABASE.workflows.get_workflows_by_organization_id(
organization_id=organization_id,
@@ -4748,6 +4754,7 @@ class WorkflowService:
app.AGENT_FUNCTION.on_workflow_run_completed(
organization_id=workflow_run.organization_id,
workflow_id=workflow_run.workflow_id,
+ status=status,
),
)
self._background_tasks.add(run_completed_task)
@@ -5439,6 +5446,11 @@ class WorkflowService:
run_end = _as_utc(workflow_run.finished_at) if workflow_run.finished_at else datetime.now(UTC)
upper_bound = run_end + RECORDING_WINDOW_END_BUFFER
recording_urls = _select_recording_urls_in_window(recordings, lower_bound, upper_bound)
+ if not recording_urls and recordings:
+ # Persistent sessions upload one continuous recording at session
+ # close, often long after run_end, so it never lands in the bounded
+ # window. Drop the upper bound rather than show "no recording".
+ recording_urls = _select_recording_urls_in_window(recordings, lower_bound)
except asyncio.TimeoutError:
LOG.warning("Timeout getting recordings", browser_session_id=workflow_run.browser_session_id)
diff --git a/skyvern/schemas/tags.py b/skyvern/schemas/tags.py
index 8aabc1b6a..7ef54dbd1 100644
--- a/skyvern/schemas/tags.py
+++ b/skyvern/schemas/tags.py
@@ -4,15 +4,17 @@ from __future__ import annotations
from datetime import datetime
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
from skyvern.forge.sdk.workflow.models.validators import (
RUN_METADATA_MAX_KEYS,
SKYVERN_TAG_NAMESPACE,
TAG_DESCRIPTION_MAX_LENGTH,
TAG_KEY_REGEX,
+ normalize_optional_tag_key,
+ normalize_optional_tag_value,
normalize_tag_description,
- normalize_tags,
+ normalize_tag_value,
)
@@ -33,70 +35,105 @@ def _assert_user_key_writable(key: str) -> None:
)
+class TagInput(BaseModel):
+ """One tag to set. ``value`` is the required label; ``key`` is the optional
+ group — null for a standalone label, set for a grouped label (e.g. env:prod)."""
+
+ key: str | None = Field(default=None, description="Optional group (key). Omit for a standalone label.")
+ value: str = Field(description="Label (value). Always required.")
+
+ @field_validator("key", mode="before")
+ @classmethod
+ def _normalize_key(cls, v: object) -> str | None:
+ return normalize_optional_tag_key(v)
+
+ @field_validator("value", mode="before")
+ @classmethod
+ def _normalize_value(cls, v: object) -> str:
+ return normalize_tag_value(v)
+
+ @model_validator(mode="after")
+ def _value_avoids_filter_grammar_sigils(self) -> TagInput:
+ if self.key is None and ":" in self.value:
+ raise ValueError("standalone label values must not contain ':' (use a group, e.g. key:value)")
+ if self.key is not None and self.value == "*":
+ raise ValueError("grouped tag values must not be exactly '*' (reserved as the group filter wildcard)")
+ return self
+
+
+class TagDeleteInput(BaseModel):
+ """One tag to soft-delete: a grouped tag by its ``key``, or a standalone label
+ by its ``value`` (omit the key)."""
+
+ key: str | None = Field(default=None, description="Group (key) to delete. Use for grouped tags.")
+ value: str | None = Field(default=None, description="Label (value) to delete. Use for standalone labels.")
+
+ @field_validator("key", mode="before")
+ @classmethod
+ def _normalize_key(cls, v: object) -> str | None:
+ return normalize_optional_tag_key(v)
+
+ @field_validator("value", mode="before")
+ @classmethod
+ def _normalize_value(cls, v: object) -> str | None:
+ return normalize_optional_tag_value(v)
+
+ @model_validator(mode="after")
+ def _exactly_one_identity(self) -> TagDeleteInput:
+ # Delete a grouped tag by key or a standalone label by value, never both —
+ # the both-set case is ambiguous (would silently ignore `value`).
+ if self.key is None and self.value is None:
+ raise ValueError("each delete target must specify a key (group) or a value (label)")
+ if self.key is not None and self.value is not None:
+ raise ValueError("a delete target must specify either a key (group) or a value (label), not both")
+ return self
+
+
class TagApplyRequest(BaseModel):
- """Body for ``POST /v1/workflows/{wpid}/tags``. Either field may be empty;
- both empty is a valid no-op. Same-key collisions: set wins over delete."""
+ """Body for ``POST /v1/workflows/{wpid}/tags``. Either field may be empty (both
+ empty is a no-op). On a same-identity collision, set wins over delete."""
- tags: dict[str, str] = Field(
- default_factory=dict,
- description="Tags to set (overwrite). Map of key to value.",
+ tags: list[TagInput] = Field(
+ default_factory=list,
+ description="Tags to set (overwrite). List of {key?, value} objects.",
)
- tags_to_delete: list[str] = Field(
+ tags_to_delete: list[TagDeleteInput] = Field(
default_factory=list,
- description="Tag keys to soft-delete.",
+ description="Tags to soft-delete. List of {key?, value?} targets.",
)
@field_validator("tags", mode="before")
@classmethod
- def _normalize(cls, v: object) -> dict[str, str]:
- # Outer-shape guard: dict-or-None only. Without this a list body would
- # crash inside _normalize_kv_dict's .items() call.
+ def _coerce_tags(cls, v: object) -> object:
if v is None:
- return {}
- if not isinstance(v, dict):
- raise ValueError("tags must be a JSON object mapping string keys to string values")
- # Inner-element guard: every key AND value must be a string. JSON can
- # carry non-string VALUES (numbers, bools, null) which would otherwise
- # blow up inside `value.strip()`. Non-string KEYS can't survive JSON
- # serialization but can be constructed via direct model_validate() —
- # covered for defense in depth.
- for k, val in v.items():
- if not isinstance(k, str):
- raise ValueError("tags keys must be strings")
- if not isinstance(val, str):
- raise ValueError("tags values must be strings")
- return normalize_tags(v) or {}
+ return []
+ # Outer-shape guard: a JSON object/string body must fail cleanly (422),
+ # not coerce into a single-element list or iterate char-by-char.
+ if not isinstance(v, list):
+ raise ValueError("tags must be a JSON array of {key, value} objects")
+ if len(v) > RUN_METADATA_MAX_KEYS:
+ raise ValueError(f"tags can include at most {RUN_METADATA_MAX_KEYS} entries")
+ return v
@field_validator("tags_to_delete", mode="before")
@classmethod
- def _normalize_deletes(cls, v: object) -> list[str]:
+ def _coerce_deletes(cls, v: object) -> object:
if v is None:
return []
- # Strings are iterable, so `[k for k in v]` on a string body
- # silently chars-into-list. Explicit list/tuple guard prevents this.
- if isinstance(v, str) or not isinstance(v, (list, tuple)):
- raise ValueError("tags_to_delete must be a JSON array of strings")
- cleaned: list[str] = []
- for k in v:
- if not isinstance(k, str):
- raise ValueError("tags_to_delete entries must be strings")
- trimmed = k.strip()
- if not trimmed:
- continue
- # Same namespace/regex rules as SET, so the reserved skyvern.* prefix
- # and malformed URL-unsafe keys can't be deleted via the body API.
- _assert_user_key_writable(trimmed)
- cleaned.append(trimmed)
- if len(cleaned) > RUN_METADATA_MAX_KEYS:
+ if not isinstance(v, list):
+ raise ValueError("tags_to_delete must be a JSON array of {key, value} objects")
+ if len(v) > RUN_METADATA_MAX_KEYS:
raise ValueError(f"tags_to_delete can include at most {RUN_METADATA_MAX_KEYS} entries")
- return cleaned
+ return v
class TagResponse(BaseModel):
- """Current state of one tag (``GET /v1/workflows/{wpid}/tags`` row)."""
+ """Current state of one tag (``GET /v1/workflows/{wpid}/tags`` row).
+ ``key`` is null for a standalone label."""
model_config = ConfigDict(from_attributes=True)
+ key: str | None = None
value: str
source: str
set_at: datetime
@@ -104,10 +141,11 @@ class TagResponse(BaseModel):
class TagsResponse(BaseModel):
- """Current tag map for a workflow."""
+ """Current tags for a workflow. A list (not a key-map) so standalone labels,
+ which have no key, are representable."""
workflow_permanent_id: str
- tags: dict[str, TagResponse]
+ tags: list[TagResponse]
class TagHistoryItem(BaseModel):
@@ -116,7 +154,7 @@ class TagHistoryItem(BaseModel):
model_config = ConfigDict(from_attributes=True)
tag_event_id: str
- key: str
+ key: str | None
value: str | None
event_type: str
source: str
@@ -177,11 +215,19 @@ class WorkflowTagsBatchRequest(BaseModel):
)
+class TagItem(BaseModel):
+ """A single tag (key + label) without per-tag attribution. ``key`` is null
+ for a standalone label."""
+
+ key: str | None = None
+ value: str
+
+
class WorkflowTagsBatchResponse(BaseModel):
"""Response for the batch endpoint.
- Workflows with no tags are present with an empty dict so the frontend can
+ Workflows with no tags are present with an empty list so the frontend can
distinguish "fetched, none set" from "not fetched" without a second call.
Workflows outside the caller's org are silently absent (no leakage)."""
- workflow_tags: dict[str, dict[str, str]]
+ workflow_tags: dict[str, list[TagItem]]
diff --git a/skyvern/services/otp_service.py b/skyvern/services/otp_service.py
index d45331575..0d243403e 100644
--- a/skyvern/services/otp_service.py
+++ b/skyvern/services/otp_service.py
@@ -359,11 +359,16 @@ async def resolve_otp_value(task: "Task") -> OTPValue | None:
if (task.totp_verification_url or task.totp_identifier) and task.organization_id:
workflow_id: str | None = None
workflow_permanent_id: str | None = None
+ # Codes forwarded into the DB share a single totp_identifier across runs with no
+ # run_id, so a stale code from a prior run can be handed to this one. Anchoring to
+ # the run's start time disqualifies any code that predates this run.
+ run_started_at: datetime | None = None
if task.workflow_run_id:
workflow_run = await app.DATABASE.workflow_runs.get_workflow_run(task.workflow_run_id)
if workflow_run:
workflow_id = workflow_run.workflow_id
workflow_permanent_id = workflow_run.workflow_permanent_id
+ run_started_at = workflow_run.started_at
return await poll_otp_value(
organization_id=task.organization_id,
task_id=task.task_id,
@@ -372,6 +377,7 @@ async def resolve_otp_value(task: "Task") -> OTPValue | None:
workflow_permanent_id=workflow_permanent_id,
totp_verification_url=task.totp_verification_url,
totp_identifier=task.totp_identifier,
+ created_after=run_started_at,
)
return None
@@ -385,6 +391,7 @@ async def poll_otp_value(
workflow_permanent_id: str | None = None,
totp_verification_url: str | None = None,
totp_identifier: str | None = None,
+ created_after: datetime | None = None,
) -> OTPValue | None:
timeout = timedelta(minutes=settings.VERIFICATION_CODE_POLLING_TIMEOUT_MINS)
start_datetime = datetime.utcnow()
@@ -448,6 +455,7 @@ async def poll_otp_value(
task_id=task_id,
workflow_id=workflow_permanent_id,
workflow_run_id=workflow_run_id,
+ created_after=created_after,
)
except FailedToGetTOTPVerificationCode as e:
consecutive_failures += 1
@@ -584,8 +592,11 @@ async def _get_otp_value_from_db(
task_id: str | None = None,
workflow_id: str | None = None,
workflow_run_id: str | None = None,
+ created_after: datetime | None = None,
) -> OTPValue | None:
- totp_codes = await app.DATABASE.otp.get_otp_codes(organization_id=organization_id, totp_identifier=totp_identifier)
+ totp_codes = await app.DATABASE.otp.get_otp_codes(
+ organization_id=organization_id, totp_identifier=totp_identifier, created_after=created_after
+ )
for totp_code in totp_codes:
if totp_code.workflow_run_id and workflow_run_id and totp_code.workflow_run_id != workflow_run_id:
continue
diff --git a/tests/unit/test_api_docs_taxonomy.py b/tests/unit/test_api_docs_taxonomy.py
index fe5bbb7b7..02d628964 100644
--- a/tests/unit/test_api_docs_taxonomy.py
+++ b/tests/unit/test_api_docs_taxonomy.py
@@ -31,6 +31,7 @@ APPROVED_TAGS = {
"Scripts",
"Server",
"SDK",
+ "Runs",
}
# Pre-rebrand / internal tags that must never render a public section again.
RETIRED_TAGS = {
@@ -51,6 +52,11 @@ RETAGGED_PATH_TAGS = {
"/v1/tag-keys": "Tags",
"/v1/tag-keys/{key}": "Tags",
"/v1/version": "Server",
+ "/v1/run/agents": "Runs",
+ "/v1/runs/{run_id}": "Runs",
+ "/v1/runs/cancel": "Runs",
+ "/v1/agents/runs": "Runs",
+ "/v1/agents/{workflow_id}/runs": "Runs",
}
diff --git a/tests/unit/test_copilot_composition_evidence.py b/tests/unit/test_copilot_composition_evidence.py
index aabd26512..e98d68a6c 100644
--- a/tests/unit/test_copilot_composition_evidence.py
+++ b/tests/unit/test_copilot_composition_evidence.py
@@ -2,12 +2,22 @@
from __future__ import annotations
+import json
from dataclasses import dataclass, field
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
from unittest.mock import patch
+import pytest
import yaml
+from skyvern.forge.sdk.copilot import tools as tools_module
from skyvern.forge.sdk.copilot.build_phase import BuildPhase
+from skyvern.forge.sdk.copilot.composition_browser_expressions import (
+ COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION,
+ COMPOSITION_VISUAL_OBSTRUCTION_CANDIDATES_EXPRESSION,
+)
from skyvern.forge.sdk.copilot.composition_evidence import (
composition_page_evidence_error,
has_bounded_page_schema,
@@ -15,6 +25,7 @@ from skyvern.forge.sdk.copilot.composition_evidence import (
normalize_block_observation_refs,
page_evidence_needs_visual_fallback,
parse_composition_html,
+ parse_composition_structured,
)
from skyvern.forge.sdk.copilot.turn_intent import TurnIntent, TurnIntentMode
from skyvern.forge.sdk.copilot.verification_evidence import WorkflowVerificationEvidence
@@ -63,6 +74,22 @@ def _flow_entry(
}
+def _scout_interaction_entry(url: str, *, step: int, selector: str = "#x") -> dict:
+ # A scout-interaction observation carries the proven selector but no page schema.
+ return {
+ "evidence": {
+ "inspected_url": url,
+ "current_url": url,
+ "source_tool": "scout_interaction",
+ "interaction_tool": "click",
+ "interaction_selector": selector,
+ },
+ "reached_via": "interaction",
+ "had_bounded_schema": False,
+ "step": step,
+ }
+
+
def _yaml(*blocks: dict) -> str:
return yaml.safe_dump({"title": "wf", "workflow_definition": {"parameters": [], "blocks": list(blocks)}})
@@ -1512,6 +1539,110 @@ def test_composition_gate_allows_current_page_read_after_matching_interaction_re
assert composition_page_evidence_error(ctx, workflow_yaml) is None
+def test_composition_gate_accepts_scout_interaction_observation_for_click_reached_block() -> None:
+ # SKY-10712: a successful scout interaction reaches the page, so a click-reached
+ # block authors against it without a separate inspect_page_for_composition.
+ workflow_yaml = _yaml(
+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},
+ {"block_type": "action", "label": "search_product", "navigation_goal": "Search for the product."},
+ {"block_type": "action", "label": "add_to_cart", "navigation_goal": "Add the first result to the cart."},
+ )
+ ctx = _Ctx(
+ flow_evidence=[
+ _flow_entry("https://example.com/", reached_via="navigate", step=0),
+ _scout_interaction_entry("https://example.com/results", step=1),
+ _scout_interaction_entry("https://example.com/cart", step=2),
+ ],
+ block_observation_refs={"search_product": 1, "add_to_cart": 2},
+ )
+
+ assert composition_page_evidence_error(ctx, workflow_yaml) is None
+
+
+def test_composition_gate_rejects_hollow_interaction_observation_without_schema() -> None:
+ # Guard: a hollow inspect (interaction-reached but no schema and not a scout
+ # interaction) must still be rejected — the relaxation is scoped to scout proof.
+ workflow_yaml = _yaml(
+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},
+ {"block_type": "action", "label": "search_product", "navigation_goal": "Search for the product."},
+ {"block_type": "action", "label": "add_to_cart", "navigation_goal": "Add the first result to the cart."},
+ )
+ hollow = _flow_entry("https://example.com/cart", reached_via="interaction", with_form=False, step=2)
+ ctx = _Ctx(
+ flow_evidence=[
+ _flow_entry("https://example.com/", reached_via="navigate", step=0),
+ _scout_interaction_entry("https://example.com/results", step=1),
+ hollow,
+ ],
+ block_observation_refs={"search_product": 1, "add_to_cart": 2},
+ )
+
+ assert composition_page_evidence_error(ctx, workflow_yaml) is not None
+
+
+def test_composition_gate_auto_credits_interaction_observation_without_a_ref() -> None:
+ # SKY-10712 option 1: a click-reached action block with NO block_observation_refs entry is
+ # auto-credited from the most-recent interaction-reached observation; the agent need not thread it.
+ workflow_yaml = _yaml(
+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},
+ {"block_type": "action", "label": "search_product", "navigation_goal": "Search for the product."},
+ {"block_type": "action", "label": "add_to_cart", "navigation_goal": "Click the Add to Cart button."},
+ )
+ ctx = _Ctx(
+ flow_evidence=[
+ _flow_entry("https://example.com/", reached_via="navigate", step=0),
+ _scout_interaction_entry("https://example.com/", step=1),
+ ],
+ block_observation_refs={},
+ )
+
+ assert composition_page_evidence_error(ctx, workflow_yaml) is None
+
+
+def test_composition_gate_rejects_click_reached_block_with_no_interaction_observation() -> None:
+ workflow_yaml = _yaml(
+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},
+ {"block_type": "action", "label": "search_product", "navigation_goal": "Search for the product."},
+ {"block_type": "action", "label": "add_to_cart", "navigation_goal": "Click the Add to Cart button."},
+ )
+ ctx = _Ctx(
+ flow_evidence=[_flow_entry("https://example.com/", reached_via="navigate", step=0)],
+ block_observation_refs={},
+ )
+
+ error = composition_page_evidence_error(ctx, workflow_yaml)
+
+ assert error is not None
+ assert "add_to_cart (action)" in error
+
+
+def test_composition_gate_auto_credit_consumes_each_interaction_once() -> None:
+ # Two click-reached blocks need two distinct interaction observations (consume-once); the
+ # SPA URL is identical across both, so binding is by trajectory order, never by url.
+ workflow_yaml = _yaml(
+ {"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},
+ {"block_type": "action", "label": "search_product", "navigation_goal": "Search for the product."},
+ {"block_type": "action", "label": "add_to_cart", "navigation_goal": "Click the Add to Cart button."},
+ {"block_type": "action", "label": "open_cart", "navigation_goal": "Click the cart icon."},
+ )
+ base = [_flow_entry("https://example.com/", reached_via="navigate", step=0)]
+
+ one = _Ctx(
+ flow_evidence=base + [_scout_interaction_entry("https://example.com/", step=1)], block_observation_refs={}
+ )
+ assert composition_page_evidence_error(one, workflow_yaml) is not None
+
+ two = _Ctx(
+ flow_evidence=base
+ + [
+ _scout_interaction_entry("https://example.com/", step=1),
+ _scout_interaction_entry("https://example.com/", step=2),
+ ],
+ block_observation_refs={},
+ )
+ assert composition_page_evidence_error(two, workflow_yaml) is None
+
+
def test_composition_gate_reports_missing_referenced_observation_step() -> None:
workflow_yaml = _yaml(
{"block_type": "goto_url", "label": "open_home", "url": "https://example.com/"},
@@ -1581,9 +1712,10 @@ def test_composition_gate_reports_string_typed_observation_step_from_raw_refs()
{"block_type": "action", "label": "add_first_result", "navigation_goal": "Add the first result to the cart."},
)
ctx = _Ctx(
+ # No interaction-reached observation exists, so auto-credit cannot ground the block and the
+ # string-typed-ref diagnostic fires instead.
flow_evidence=[
_flow_entry("https://example.com/", reached_via="navigate", step=0),
- _flow_entry("https://example.com/results", reached_via="interaction", step=1),
],
block_observation_refs={
"search_product": 0,
@@ -1762,3 +1894,552 @@ def test_composition_gate_matches_url_blocks_against_target_when_observation_ref
assert error is not None
assert "open_cart (goto_url)" in error
+
+
+# Bounded structured-evidence extractor
+
+
+def _structured_form_payload() -> dict[str, Any]:
+ return {
+ "page_title": "Lookup",
+ "forms": [
+ {
+ "id": "searchForm",
+ "name": "",
+ "action": "/results",
+ "method": "get",
+ "fields": [
+ {
+ "name": "q",
+ "id": "q",
+ "label": "Full name",
+ "type": "text",
+ "value": "",
+ "class": [],
+ "placeholder": "name",
+ "required": True,
+ "disabled": False,
+ "checked": False,
+ "options": [],
+ "selector": "#q",
+ },
+ {
+ "name": "state",
+ "id": "state",
+ "label": "State",
+ "type": "select",
+ "value": "",
+ "class": [],
+ "placeholder": "",
+ "required": False,
+ "disabled": False,
+ "checked": False,
+ "options": [
+ {"text": "CA", "value": "ca", "selected": True},
+ {"text": "NY", "value": "ny", "selected": False},
+ ],
+ "selector": "#state",
+ },
+ ],
+ "submit_controls": [
+ {
+ "text": "Search",
+ "name": "",
+ "id": "",
+ "value": "",
+ "class": [],
+ "type": "submit",
+ "disabled": False,
+ "selector": "button",
+ }
+ ],
+ }
+ ],
+ "navigation_targets": [],
+ "result_containers": [],
+ "challenge_controls": [],
+ "modal_overlays": [],
+ "visual_obstruction_candidates": [],
+ "visible_text_excerpt": "Full name State Search",
+ "anti_bot_indicators": [],
+ }
+
+
+def test_structured_parses_forms_labels_options_and_submit() -> None:
+ parsed = parse_composition_structured(
+ _structured_form_payload(),
+ inspected_url="https://example.com/lookup",
+ current_url="https://example.com/lookup",
+ )
+
+ assert parsed is not None
+ assert parsed["source_tool"] == "inspect_page_for_composition"
+ form = parsed["forms"][0]
+ assert [field["label"] for field in form["fields"]] == ["Full name", "State"]
+ assert form["fields"][0]["required"] is True
+ assert form["fields"][1]["options"][0] == {"text": "CA", "value": "ca", "selected": True}
+ assert form["submit_controls"][0]["text"] == "Search"
+ assert parsed["evidence_confidence"] == 0.85
+ assert has_bounded_page_schema(parsed) is True
+
+
+def test_structured_detects_modal_overlay_with_dismiss_controls() -> None:
+ payload = {
+ "page_title": "",
+ "forms": [],
+ "navigation_targets": [],
+ "result_containers": [],
+ "challenge_controls": [],
+ "modal_overlays": [
+ {
+ "role": "dialog",
+ "aria_modal": True,
+ "id": "",
+ "class": ["modal"],
+ "selector": "div.modal",
+ "text": "Subscribe",
+ "dismiss_controls": [
+ {
+ "tag": "button",
+ "text": "Close",
+ "aria_label": "",
+ "title": "",
+ "selector": "button.x",
+ "type": "",
+ }
+ ],
+ }
+ ],
+ "visual_obstruction_candidates": [],
+ "visible_text_excerpt": "Subscribe Close",
+ "anti_bot_indicators": [],
+ }
+
+ parsed = parse_composition_structured(
+ payload, inspected_url="https://example.com/r", current_url="https://example.com/r"
+ )
+
+ assert parsed is not None
+ overlay = parsed["modal_overlays"][0]
+ assert overlay["selector"] == "div.modal"
+ assert overlay["dismiss_controls"][0]["text"] == "Close"
+ assert "aria_modal" in overlay and overlay["aria_modal"] is True
+ assert parsed["page_obstructions"]
+ assert has_bounded_page_schema(parsed) is True
+
+
+def test_structured_detects_anti_bot_and_challenge_controls() -> None:
+ payload = {
+ "page_title": "",
+ "forms": [],
+ "navigation_targets": [],
+ "result_containers": [],
+ "challenge_controls": [
+ {
+ "tag": "iframe",
+ "id": "",
+ "name": "",
+ "class": [],
+ "type": "",
+ "selector": "iframe",
+ "text": "",
+ "src": "https://challenges.cloudflare.com/turnstile/v0/api.js",
+ "title": "Cloudflare security challenge",
+ }
+ ],
+ "modal_overlays": [],
+ "visual_obstruction_candidates": [],
+ "visible_text_excerpt": "",
+ "anti_bot_indicators": ["captcha", "turnstile"],
+ }
+
+ parsed = parse_composition_structured(
+ payload, inspected_url="https://example.com/x", current_url="https://example.com/x"
+ )
+
+ assert parsed is not None
+ assert parsed["anti_bot_indicators"] == ["captcha", "turnstile"]
+ assert parsed["challenge_state"]["detected"] is True
+ assert parsed["challenge_state"]["kind"] == "captcha"
+ assert "data_sitekey" not in parsed["challenge_controls"][0]
+ assert parsed["challenge_controls"][0]["src"] == "https://challenges.cloudflare.com/turnstile/v0/api.js"
+ assert has_bounded_page_schema(parsed) is True
+ assert page_evidence_needs_visual_fallback(parsed) is True
+
+
+def test_structured_rejects_unusable_payloads() -> None:
+ for bad in (None, "not a dict", ["a"], 123, 4.5, True):
+ assert parse_composition_structured(bad, inspected_url="u", current_url="u") is None
+
+
+def test_structured_intersects_reported_anti_bot_indicators_with_known_patterns() -> None:
+ payload = _structured_form_payload()
+ payload["anti_bot_indicators"] = ["captcha", "totally-made-up", "challenge"]
+
+ parsed = parse_composition_structured(payload, inspected_url="u", current_url="u")
+
+ assert parsed is not None
+ # Bogus indicators are dropped; survivors are returned in canonical pattern order.
+ assert parsed["anti_bot_indicators"] == ["captcha", "challenge"]
+
+
+def test_structured_navigation_drops_cross_origin_links() -> None:
+ payload = _structured_form_payload()
+ payload["navigation_targets"] = [
+ {"text": "Same", "href": "https://example.com/page2", "selector": 'a[href="/page2"]'},
+ {"text": "Cross", "href": "https://other.example.org/x", "selector": 'a[href="x"]'},
+ {"text": "Scheme", "href": "http://example.com/page3", "selector": 'a[href="/page3"]'},
+ ]
+
+ parsed = parse_composition_structured(
+ payload, inspected_url="https://example.com/lookup", current_url="https://example.com/lookup"
+ )
+
+ assert parsed is not None
+ hrefs = [target["href"] for target in parsed["navigation_targets"]]
+ # netloc match keeps the http<->https same-host link and drops the cross-host one.
+ assert "https://example.com/page2" in hrefs
+ assert "http://example.com/page3" in hrefs
+ assert "https://other.example.org/x" not in hrefs
+
+
+def test_structured_body_with_markup_but_no_structure_is_schema_empty() -> None:
+ # body markup but no bounded structure and no visible text -> schema-empty.
+ payload = {
+ "page_title": "",
+ "forms": [],
+ "navigation_targets": [],
+ "result_containers": [],
+ "challenge_controls": [],
+ "modal_overlays": [],
+ "visual_obstruction_candidates": [],
+ "visible_text_excerpt": "",
+ "body_has_markup": True,
+ "anti_bot_indicators": [],
+ }
+
+ parsed = parse_composition_structured(payload, inspected_url="u", current_url="u")
+
+ assert parsed is not None
+ assert parsed["schema_empty_page"] is True
+ assert has_bounded_page_schema(parsed) is False
+
+
+def test_structured_blank_payload_is_not_schema_empty() -> None:
+ payload = {
+ "page_title": "",
+ "forms": [],
+ "navigation_targets": [],
+ "result_containers": [],
+ "challenge_controls": [],
+ "modal_overlays": [],
+ "visual_obstruction_candidates": [],
+ "visible_text_excerpt": "",
+ "body_has_markup": False,
+ "anti_bot_indicators": [],
+ }
+
+ parsed = parse_composition_structured(payload, inspected_url="u", current_url="u")
+
+ assert parsed is not None
+ assert parsed["schema_empty_page"] is False
+
+
+# JS-DOM fidelity: run the real extractor against a live DOM and compare to the HTML parser
+
+
+def _has_playwright_browser() -> bool:
+ try:
+ from playwright.sync_api import sync_playwright # noqa: PLC0415
+
+ with sync_playwright() as p:
+ return Path(p.chromium.executable_path).exists()
+ except Exception:
+ return False
+
+
+_skip_no_browser = pytest.mark.skipif(
+ not _has_playwright_browser(),
+ reason="Requires Playwright browsers installed (run: playwright install chromium)",
+)
+
+_FIDELITY_URL = "https://test.example.com/lookup"
+_FIDELITY_HTML = """<!DOCTYPE html>
+<html>
+<head><title>Lookup</title></head>
+<body>
+ <form id="searchForm" action="/results" method="get">
+ <label for="q">Full name</label>
+ <input id="q" name="q" required placeholder="name" />
+ <label>Email <input name="email" type="email" /></label>
+ <span>Phone</span><input name="phone" />
+ <select id="state" name="state"><option value="ca" selected>CA</option><option value="ny">NY</option></select>
+ <input type="hidden" name="csrf" value="xyz" />
+ <button type="submit">Search</button>
+ </form>
+ <a href="/results">Results</a>
+ <a href="https://test.example.com/page2">Page2</a>
+ <a href="https://other.example.org/x">External</a>
+ <a href="#frag">Frag</a>
+ <table id="results"><tbody><tr><td>row</td></tr></tbody></table>
+ <div role="dialog" aria-modal="true" class="modal" id="signup">Sign up<button aria-label="Close">x</button></div>
+ <iframe src="https://challenges.cloudflare.com/turnstile/v0/api.js" title="Widget containing a Cloudflare security challenge"></iframe>
+ <div class="cf-turnstile" data-sitekey="abc123">Verify</div>
+ <script>var marker = "captcha widget loaded";</script>
+ <noscript>access denied</noscript>
+</body>
+</html>
+"""
+
+
+def _ac_projection(evidence: dict[str, Any]) -> dict[str, Any]:
+ """Project the acceptance-criteria fields (forms/labels/modal/anti-bot/nav/challenge) for parity."""
+ forms = [
+ {
+ "fields": [(field["name"], field["label"], field["type"], field["required"]) for field in form["fields"]],
+ "submit": [control["text"] for control in form["submit_controls"]],
+ }
+ for form in evidence["forms"]
+ ]
+ challenge_state = evidence["challenge_state"]
+ return {
+ "page_title": evidence["page_title"],
+ "forms": forms,
+ "navigation_targets": sorted(target["href"] for target in evidence["navigation_targets"]),
+ "result_containers": sorted((rc["tag"], rc["selector"]) for rc in evidence["result_containers"]),
+ "modal_selectors": sorted(
+ (overlay["selector"], bool(overlay.get("dismiss_controls"))) for overlay in evidence["modal_overlays"]
+ ),
+ "challenge_selectors": sorted(control["selector"] for control in evidence["challenge_controls"]),
+ "anti_bot_indicators": evidence["anti_bot_indicators"],
+ "challenge_detected": challenge_state["detected"],
+ "challenge_kind": challenge_state["kind"],
+ "bounded": has_bounded_page_schema(evidence),
+ }
+
+
+@_skip_no_browser
+async def test_structured_extractor_matches_html_parser_on_live_dom() -> None:
+ from playwright.async_api import async_playwright
+
+ async with async_playwright() as p:
+ browser = await p.chromium.launch(headless=True)
+ context = await browser.new_context()
+
+ async def _handle(route: Any) -> None:
+ if route.request.url == _FIDELITY_URL:
+ await route.fulfill(status=200, content_type="text/html", body=_FIDELITY_HTML)
+ else:
+ await route.abort()
+
+ await context.route("**/*", _handle)
+ page = await context.new_page()
+ await page.goto(_FIDELITY_URL, wait_until="domcontentloaded")
+ await page.wait_for_selector("#searchForm")
+ raw = await page.evaluate(COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION)
+ content = await page.content()
+ await context.close()
+ await browser.close()
+
+ structured = parse_composition_structured(json.loads(raw), inspected_url=_FIDELITY_URL, current_url=_FIDELITY_URL)
+ html_parsed = parse_composition_html(content, inspected_url=_FIDELITY_URL, current_url=_FIDELITY_URL)
+
+ assert structured is not None
+ assert _ac_projection(structured) == _ac_projection(html_parsed)
+ # Sanity: the fixture really exercised the detectors.
+ assert structured["forms"] and structured["challenge_controls"]
+ assert structured["anti_bot_indicators"] and structured["challenge_state"]["detected"] is True
+ assert any(overlay["selector"] == "#signup" for overlay in structured["modal_overlays"])
+
+
+_HEAVY_URL = "https://test.example.com/cart"
+
+
+def _heavy_results_cart_html() -> str:
+ """A heavy results+cart page: many rows, multiple forms/containers, lots of nav.
+
+ Exercises extractor/parser parity at the scale where their `_MAX_*` caps must
+ agree — the case SKY-10714 ships for, where get_html cap-overflows in prod.
+ """
+ product_rows = "".join(
+ f"<tr><td>Item {i}</td><td>${i}.99</td>"
+ f'<td><button name="add" value="{i}" type="button">Add to cart</button></td></tr>'
+ for i in range(1, 41)
+ )
+ cart_rows = "".join(
+ f"<tr><td>Line {i}</td>"
+ f'<td><label for="qty{i}">Qty {i}</label><input id="qty{i}" name="qty{i}" value="1" /></td></tr>'
+ for i in range(1, 16)
+ )
+ filter_fields = "".join(
+ f'<label for="f{i}">Filter {i}</label><input id="f{i}" name="f{i}" />' for i in range(1, 13)
+ )
+ nav_links = "".join(f'<a href="/category/{i}">Category {i}</a>' for i in range(1, 26))
+ return f"""<!DOCTYPE html>
+<html><head><title>Cart</title></head>
+<body>
+ <form id="filterForm" action="/results" method="get">
+ {filter_fields}
+ <button type="submit">Apply filters</button>
+ </form>
+ <table id="products"><tbody>{product_rows}</tbody></table>
+ <form id="cartForm" action="/cart" method="post">
+ <table id="cart"><tbody>{cart_rows}</tbody></table>
+ <button type="submit">Checkout</button>
+ </form>
+ <nav>{nav_links}<a href="https://other.example.org/x">External</a><a href="#top">Top</a></nav>
+ <div role="dialog" aria-modal="true" class="modal" id="promo">Promo<button aria-label="Close">x</button></div>
+</body></html>"""
+
+
+@_skip_no_browser
+async def test_structured_extractor_matches_html_parser_on_heavy_results_cart_dom() -> None:
+ from playwright.async_api import async_playwright
+
+ html = _heavy_results_cart_html()
+ async with async_playwright() as p:
+ browser = await p.chromium.launch(headless=True)
+ context = await browser.new_context()
+
+ async def _handle(route: Any) -> None:
+ if route.request.url == _HEAVY_URL:
+ await route.fulfill(status=200, content_type="text/html", body=html)
+ else:
+ await route.abort()
+
+ await context.route("**/*", _handle)
+ page = await context.new_page()
+ await page.goto(_HEAVY_URL, wait_until="domcontentloaded")
+ await page.wait_for_selector("#products")
+ raw = await page.evaluate(COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION)
+ content = await page.content()
+ await context.close()
+ await browser.close()
+
+ structured = parse_composition_structured(json.loads(raw), inspected_url=_HEAVY_URL, current_url=_HEAVY_URL)
+ html_parsed = parse_composition_html(content, inspected_url=_HEAVY_URL, current_url=_HEAVY_URL)
+
+ assert structured is not None
+ assert _ac_projection(structured) == _ac_projection(html_parsed)
+ # Sanity: the heavy fixture really exercised results + multi-form at scale.
+ assert structured["result_containers"]
+ assert structured["forms"]
+
+
+# Tools-layer invariant: cheap path skips get_html; failure falls back
+
+
+class _RecordingCompositionServer:
+ """Records call_internal_tool tool names and evaluate expressions for invariant assertions."""
+
+ def __init__(self, *, structured_json: str | None, html: str = "") -> None:
+ self.calls: list[str] = []
+ self.evaluate_expressions: list[str] = []
+ self._structured_json = structured_json
+ self._html = html
+
+ async def call_internal_tool(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+ self.calls.append(tool_name)
+ if tool_name == "skyvern_evaluate":
+ expression = arguments.get("expression", "")
+ self.evaluate_expressions.append(expression)
+ if expression == COMPOSITION_STRUCTURED_EVIDENCE_EXPRESSION:
+ if self._structured_json is None:
+ return {"ok": False, "error": "structured extract failed"}
+ return {"ok": True, "data": {"result": self._structured_json}}
+ if expression == COMPOSITION_VISUAL_OBSTRUCTION_CANDIDATES_EXPRESSION:
+ return {"ok": True, "data": {"result": []}}
+ return {"ok": False, "error": "unexpected expression"}
+ if tool_name == "skyvern_get_html":
+ return {"ok": True, "data": {"html": self._html}}
+ return {"ok": False, "error": f"unexpected tool {tool_name}"}
+
+
+_HTML_FORM_PAGE = (
+ "<html><head><title>T</title></head><body>"
+ "<form id='f'><input name='x'><button type='submit'>Go</button></form>"
+ "</body></html>"
+)
+
+
+async def test_capture_uses_structured_extractor_and_skips_get_html() -> None:
+ server = _RecordingCompositionServer(structured_json=json.dumps(_structured_form_payload()))
+ ctx = SimpleNamespace(discovery_mcp_server=server)
+
+ evidence, error = await tools_module._capture_composition_evidence(
+ ctx, inspected_url="https://example.com/lookup", current_url="https://example.com/lookup"
+ )
+
+ assert error is None
+ assert evidence is not None
+ assert evidence["forms"][0]["fields"][0]["label"] == "Full name"
+ assert evidence["source_tool"] == "inspect_page_for_composition"
+ # AC1: the cheap path never serializes the full DOM, and a bounded page needs only one evaluate.
+ assert server.calls.count("skyvern_get_html") == 0
+ assert server.calls.count("skyvern_evaluate") == 1
+
+
+async def test_capture_falls_back_to_get_html_when_structured_unusable() -> None:
+ server = _RecordingCompositionServer(structured_json=None, html=_HTML_FORM_PAGE)
+ ctx = SimpleNamespace(discovery_mcp_server=server)
+
+ evidence, error = await tools_module._capture_composition_evidence(
+ ctx, inspected_url="https://example.com/lookup", current_url="https://example.com/lookup"
+ )
+
+ assert error is None
+ assert evidence is not None
+ assert evidence["forms"]
+ assert server.calls.count("skyvern_get_html") >= 1
+
+
+async def test_navigation_failure_uses_structured_evidence_when_bounded() -> None:
+ server = _RecordingCompositionServer(structured_json=json.dumps(_structured_form_payload()))
+ ctx = SimpleNamespace(discovery_mcp_server=server, browser_session_id=None, organization_id="o_test")
+
+ evidence = await tools_module._composition_evidence_after_navigation_failure(
+ ctx, inspected_url="https://example.com/lookup", navigation_error="boom"
+ )
+
+ assert evidence is not None
+ assert evidence["forms"]
+ assert server.calls.count("skyvern_get_html") == 0
+ assert any("navigation_error_before_html_capture" in warning for warning in evidence["inspection_warnings"])
+
+
+async def test_capture_prefers_html_parse_over_hollow_structured_on_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
+ # When both extractor and get_html are unbounded, the get_html parse wins (carries the fallback signals).
+ monkeypatch.setattr(tools_module, "_COMPOSITION_HOLLOW_RECAPTURE_RETRIES", 0)
+ hollow = json.dumps(
+ {
+ "page_title": "",
+ "forms": [],
+ "navigation_targets": [],
+ "result_containers": [],
+ "challenge_controls": [],
+ "modal_overlays": [],
+ "visual_obstruction_candidates": [],
+ "visible_text_excerpt": "",
+ "body_has_markup": False,
+ "anti_bot_indicators": [],
+ }
+ )
+ html = "<html><head><title>Notice</title></head><body><p>Welcome notice text</p></body></html>"
+ server = _RecordingCompositionServer(structured_json=hollow, html=html)
+ ctx = SimpleNamespace(discovery_mcp_server=server)
+
+ evidence, error = await tools_module._capture_composition_evidence(
+ ctx, inspected_url="https://example.com/p", current_url="https://example.com/p"
+ )
+
+ assert error is None
+ assert evidence is not None
+ assert "Welcome notice text" in evidence["visible_text_excerpt"]
+ assert evidence["schema_empty_page"] is True
+ assert server.calls.count("skyvern_get_html") == 1
diff --git a/tests/unit/test_copilot_discovery.py b/tests/unit/test_copilot_discovery.py
index 74c0bd255..485aed846 100644
--- a/tests/unit/test_copilot_discovery.py
+++ b/tests/unit/test_copilot_discovery.py
@@ -375,7 +375,8 @@ async def test_inspect_current_page_uses_existing_browser_page(monkeypatch: pyte
result = await _inspect_page_for_composition_impl(ctx, "current_page")
assert result["ok"] is True
- assert server.calls == ["skyvern_get_html", "skyvern_evaluate"]
+ # structured extractor probe (None on the [] mock) -> get_html fallback -> obstruction-candidates probe
+ assert server.calls == ["skyvern_evaluate", "skyvern_get_html", "skyvern_evaluate"]
assert result["data"]["current_url"] == "https://www.example.com/results"
assert result["data"]["workflow_run_id"] == "wr_123"
assert result["data"]["observed_after_workflow_run"] is True
diff --git a/tests/unit/test_copilot_hooks.py b/tests/unit/test_copilot_hooks.py
index 930907a5d..a3fff1add 100644
--- a/tests/unit/test_copilot_hooks.py
+++ b/tests/unit/test_copilot_hooks.py
@@ -721,7 +721,12 @@ class TestBrowserInteractionObservationHooks:
async def test_click_hook_marks_pending_interaction_observation(self) -> None:
from skyvern.forge.sdk.copilot.tools import _click_post_hook
- ctx = SimpleNamespace(pending_browser_interaction_observation=None, discovery_mcp_server=None)
+ ctx = SimpleNamespace(
+ pending_browser_interaction_observation=None,
+ discovery_mcp_server=None,
+ scouted_interactions=[],
+ pending_scout_source_url=None,
+ )
result = await _click_post_hook(
{"ok": True, "data": {"selector": "#add-to-cart"}},
{"browser_context": {"url": "https://example.com/results", "title": "Results"}},
@@ -748,6 +753,8 @@ class TestBrowserInteractionObservationHooks:
url="https://example.com/results",
),
discovery_mcp_server=None,
+ scouted_interactions=[],
+ pending_scout_source_url=None,
)
result = await _click_post_hook(
@@ -770,7 +777,12 @@ class TestBrowserInteractionObservationHooks:
return {"ok": False, "error": "field is still empty"}
monkeypatch.setattr(tools_module, "_verify_scout_type_landed", fake_verify)
- ctx = SimpleNamespace(pending_browser_interaction_observation=None, discovery_mcp_server=None)
+ ctx = SimpleNamespace(
+ pending_browser_interaction_observation=None,
+ discovery_mcp_server=None,
+ scouted_interactions=[],
+ pending_scout_source_url=None,
+ )
result = await tools_module._type_text_post_hook(
{"ok": True, "data": {"selector": "#q", "text_length": 12}},
@@ -780,3 +792,258 @@ class TestBrowserInteractionObservationHooks:
assert result == {"ok": False, "error": "field is still empty"}
assert ctx.pending_browser_interaction_observation is None
+
+
+class TestScoutedInteractionCapture:
+ """A scouted interaction with a concrete selector is captured and surfaced to
+ code-only authoring; intent-only and failed-readback actions are not."""
+
+ def _ctx(self, *, policy: object = None, source_url: str | None = None) -> SimpleNamespace:
+ ns = SimpleNamespace(
+ pending_browser_interaction_observation=None,
+ discovery_mcp_server=None,
+ scouted_interactions=[],
+ observed_browser_urls=[],
+ pending_scout_source_url=source_url,
+ )
+ if policy is not None:
+ ns.block_authoring_policy = policy
+ return ns
+
+ def test_record_requires_concrete_selector(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _record_scouted_interaction
+
+ ctx = self._ctx()
+ _record_scouted_interaction(ctx, tool_name="click", selector="")
+ _record_scouted_interaction(ctx, tool_name="type_text", selector=" ")
+ assert ctx.scouted_interactions == []
+
+ def test_record_press_key_without_selector_is_kept(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _record_scouted_interaction
+
+ ctx = self._ctx()
+ _record_scouted_interaction(ctx, tool_name="press_key", selector="", key="Enter")
+ assert ctx.scouted_interactions == [{"tool_name": "press_key", "key": "Enter"}]
+
+ def test_record_takes_source_url_param(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _record_scouted_interaction
+
+ ctx = self._ctx()
+ _record_scouted_interaction(
+ ctx, tool_name="click", selector="#add-to-cart", source_url="https://example.com/product"
+ )
+ assert ctx.scouted_interactions == [
+ {"tool_name": "click", "selector": "#add-to-cart", "source_url": "https://example.com/product"}
+ ]
+
+ def test_consume_scout_source_url_reads_and_clears(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _consume_scout_source_url
+
+ ctx = self._ctx(source_url="https://example.com/product")
+ assert _consume_scout_source_url(ctx) == "https://example.com/product"
+ # cleared so a failed/non-recording action cannot bleed into a later interaction
+ assert ctx.pending_scout_source_url is None
+ assert _consume_scout_source_url(ctx) is None
+
+ def test_record_dedups_identical_interaction(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _record_scouted_interaction
+
+ ctx = self._ctx()
+ _record_scouted_interaction(ctx, tool_name="click", selector="#x", source_url="https://e.com/a")
+ _record_scouted_interaction(ctx, tool_name="click", selector="#x", source_url="https://e.com/a")
+ _record_scouted_interaction(ctx, tool_name="click", selector="#y", source_url="https://e.com/a")
+ assert ctx.scouted_interactions == [
+ {"tool_name": "click", "selector": "#x", "source_url": "https://e.com/a"},
+ {"tool_name": "click", "selector": "#y", "source_url": "https://e.com/a"},
+ ]
+
+ def test_record_drops_zero_typed_length(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _record_scouted_interaction
+
+ ctx = self._ctx()
+ _record_scouted_interaction(ctx, tool_name="type_text", selector="#q", typed_length=0)
+ assert ctx.scouted_interactions == [{"tool_name": "type_text", "selector": "#q"}]
+
+ def test_record_omits_empty_extras_and_caps_history(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _MAX_SCOUTED_INTERACTIONS, _record_scouted_interaction
+
+ ctx = self._ctx()
+ for index in range(_MAX_SCOUTED_INTERACTIONS + 5):
+ _record_scouted_interaction(ctx, tool_name="click", selector=f"#item-{index}")
+ assert len(ctx.scouted_interactions) == _MAX_SCOUTED_INTERACTIONS
+ # oldest dropped, newest kept
+ assert ctx.scouted_interactions[-1]["selector"] == f"#item-{_MAX_SCOUTED_INTERACTIONS + 4}"
+ assert "source_url" not in ctx.scouted_interactions[-1]
+
+ @pytest.mark.asyncio
+ async def test_click_post_hook_registers_interaction_reached_observation(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _click_post_hook
+
+ ctx = self._ctx(source_url="https://example.com/product")
+ ctx.flow_evidence = []
+ result = await _click_post_hook(
+ {"ok": True, "data": {"selector": "#add-to-cart"}},
+ {"browser_context": {"url": "https://example.com/cart", "title": "Cart"}},
+ ctx,
+ )
+ assert len(ctx.flow_evidence) == 1
+ entry = ctx.flow_evidence[0]
+ assert entry["reached_via"] == "interaction"
+ assert entry["evidence"]["source_tool"] == "scout_interaction"
+ assert entry["evidence"]["current_url"] == "https://example.com/cart"
+ assert entry["evidence"]["interaction_selector"] == "#add-to-cart"
+ assert entry["evidence"]["interaction_source_url"] == "https://example.com/product"
+ assert result["observation_step"] == entry["step"]
+ assert result["data"]["observation_step"] == entry["step"]
+
+ @pytest.mark.asyncio
+ async def test_post_hook_skips_observation_without_flow_evidence(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _click_post_hook
+
+ ctx = self._ctx() # no flow_evidence on this context
+ result = await _click_post_hook(
+ {"ok": True, "data": {"selector": "#add-to-cart"}},
+ {"browser_context": {"url": "https://example.com/cart", "title": "Cart"}},
+ ctx,
+ )
+ assert "observation_step" not in result
+
+ @pytest.mark.asyncio
+ async def test_click_post_hook_records_source_page_not_destination(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _click_post_hook
+
+ # pre-hook stashed the product page; the click navigates to the cart
+ ctx = self._ctx(source_url="https://example.com/product")
+ await _click_post_hook(
+ {"ok": True, "data": {"selector": "#add-to-cart"}},
+ {"browser_context": {"url": "https://example.com/cart", "title": "Cart"}},
+ ctx,
+ )
+ assert ctx.scouted_interactions == [
+ {"tool_name": "click", "selector": "#add-to-cart", "source_url": "https://example.com/product"}
+ ]
+
+ @pytest.mark.asyncio
+ async def test_click_post_hook_omits_source_url_when_unavailable(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _click_post_hook
+
+ ctx = self._ctx() # no pre-hook source url
+ await _click_post_hook(
+ {"ok": True, "data": {"selector": "#add-to-cart"}},
+ {"browser_context": {"url": "https://example.com/cart", "title": "Cart"}},
+ ctx,
+ )
+ assert ctx.scouted_interactions == [{"tool_name": "click", "selector": "#add-to-cart"}]
+
+ @pytest.mark.asyncio
+ async def test_type_post_hook_records_selector_and_length_not_text(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.forge.sdk.copilot import tools as tools_module
+
+ async def passes(*_a: object, **_k: object) -> None:
+ return None
+
+ monkeypatch.setattr(tools_module, "_verify_scout_type_landed", passes)
+ ctx = self._ctx()
+ await tools_module._type_text_post_hook(
+ {"ok": True, "data": {"selector": "#q", "text_length": 8}},
+ {"browser_context": {"url": "https://example.com/search", "title": "Search"}},
+ ctx,
+ )
+ assert ctx.scouted_interactions == [{"tool_name": "type_text", "selector": "#q", "typed_length": 8}]
+ # the raw typed text is never captured (PII)
+ assert all("text" not in item for item in ctx.scouted_interactions)
+
+ @pytest.mark.asyncio
+ async def test_type_post_hook_records_nothing_when_readback_fails(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.forge.sdk.copilot import tools as tools_module
+
+ async def fails(*_a: object, **_k: object) -> dict[str, object]:
+ return {"ok": False, "error": "field is still empty"}
+
+ monkeypatch.setattr(tools_module, "_verify_scout_type_landed", fails)
+ ctx = self._ctx()
+ await tools_module._type_text_post_hook(
+ {"ok": True, "data": {"selector": "#q", "text_length": 8}},
+ {"browser_context": {"url": "https://example.com/search", "title": "Search"}},
+ ctx,
+ )
+ assert ctx.scouted_interactions == []
+
+ @pytest.mark.asyncio
+ async def test_select_and_press_key_capture_value_and_key(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _press_key_post_hook, _select_option_post_hook
+
+ ctx = self._ctx()
+ await _select_option_post_hook(
+ {"ok": True, "data": {"selector": "#sort", "value": "price_asc"}},
+ {"browser_context": {"url": "https://example.com/results", "title": "Results"}},
+ ctx,
+ )
+ await _press_key_post_hook(
+ {"ok": True, "data": {"selector": "#q", "key": "Enter"}},
+ {"browser_context": {"url": "https://example.com/results", "title": "Results"}},
+ ctx,
+ )
+ assert ctx.scouted_interactions == [
+ {"tool_name": "select_option", "selector": "#sort", "value": "price_asc"},
+ {"tool_name": "press_key", "selector": "#q", "key": "Enter"},
+ ]
+
+ @pytest.mark.asyncio
+ async def test_multi_action_sequence_preserves_order(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.forge.sdk.copilot import tools as tools_module
+
+ async def passes(*_a: object, **_k: object) -> None:
+ return None
+
+ monkeypatch.setattr(tools_module, "_verify_scout_type_landed", passes)
+ ctx = self._ctx()
+ await tools_module._type_text_post_hook(
+ {"ok": True, "data": {"selector": "#q", "text_length": 8}},
+ {"browser_context": {"url": "https://example.com/search", "title": "Search"}},
+ ctx,
+ )
+ await tools_module._press_key_post_hook(
+ {"ok": True, "data": {"selector": "#q", "key": "Enter"}},
+ {"browser_context": {"url": "https://example.com/results", "title": "Results"}},
+ ctx,
+ )
+ assert [item["tool_name"] for item in ctx.scouted_interactions] == ["type_text", "press_key"]
+
+ @pytest.mark.asyncio
+ async def test_post_hook_clears_source_url_even_when_action_fails(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _click_post_hook
+
+ # a failed click must not leave its source page to bleed into a later interaction
+ ctx = self._ctx(source_url="https://example.com/product")
+ await _click_post_hook({"ok": False, "error": "not found"}, {}, ctx)
+ assert ctx.pending_scout_source_url is None
+ assert ctx.scouted_interactions == []
+
+ @pytest.mark.asyncio
+ async def test_capture_scout_source_url_reads_live_url(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from skyvern.forge.sdk.copilot import tools as tools_module
+
+ async def fake_url(_ctx: object) -> str:
+ return "https://example.com/product"
+
+ monkeypatch.setattr(tools_module, "_live_working_page_url", fake_url)
+ ctx = self._ctx()
+ await tools_module._capture_scout_source_url(ctx)
+ assert ctx.pending_scout_source_url == "https://example.com/product"
+
+ @pytest.mark.asyncio
+ async def test_select_option_post_hook_surfaces_observation_step(self) -> None:
+ from skyvern.forge.sdk.copilot.tools import _select_option_post_hook
+
+ ctx = self._ctx()
+ ctx.flow_evidence = []
+ result = await _select_option_post_hook(
+ {"ok": True, "data": {"selector": "#sort", "value": "price_asc"}},
+ {"browser_context": {"url": "https://example.com/results", "title": "Results"}},
+ ctx,
+ )
+ entry = ctx.flow_evidence[0]
+ assert entry["reached_via"] == "interaction"
+ assert entry["evidence"]["interaction_selector"] == "#sort"
+ assert result["data"]["observation_step"] == entry["step"]
diff --git a/tests/unit/test_onboarding_milestone_hooks.py b/tests/unit/test_onboarding_milestone_hooks.py
index da6d2f542..958f187ff 100644
--- a/tests/unit/test_onboarding_milestone_hooks.py
+++ b/tests/unit/test_onboarding_milestone_hooks.py
@@ -155,6 +155,7 @@ class TestWorkflowRunCompleteHookFires:
mock_agent_fn.on_workflow_run_completed.assert_awaited_once_with(
organization_id="o_789",
workflow_id="wf_1",
+ status=mock_status,
)
@pytest.mark.asyncio
diff --git a/tests/unit/test_otp_service.py b/tests/unit/test_otp_service.py
index 55616999d..b722094e9 100644
--- a/tests/unit/test_otp_service.py
+++ b/tests/unit/test_otp_service.py
@@ -14,6 +14,7 @@ from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.core.skyvern_context import SkyvernContext
from skyvern.services.otp_service import (
OTPValue,
+ _get_otp_value_from_db,
_get_otp_value_from_url,
_is_mfa_like_parameter_key,
extract_totp_from_navigation_inputs,
@@ -928,3 +929,22 @@ class TestPostTotpVerificationUrlSeam:
assert parsed["task_id"] == "t_123123123"
assert parsed["verification_code"] == email
assert "123456" in parsed["verification_code"]
+
+
+async def test_get_otp_value_from_db_forwards_created_after(monkeypatch: pytest.MonkeyPatch) -> None:
+ """_get_otp_value_from_db forwards created_after so the DB query can disqualify pre-run codes."""
+ started_at = datetime(2026, 6, 8, 20, 3, 0)
+ get_otp_codes = AsyncMock(return_value=[])
+ with patch("skyvern.services.otp_service.app") as mock_app:
+ mock_app.DATABASE.otp.get_otp_codes = get_otp_codes
+ result = await _get_otp_value_from_db(
+ "o_test",
+ workflow_run_id="wr_test",
+ created_after=started_at,
+ )
+
+ assert result is None
+ get_otp_codes.assert_awaited_once()
+ assert get_otp_codes.await_args.kwargs["created_after"] == started_at
diff --git a/tests/unit/test_recording_window_filter.py b/tests/unit/test_recording_window_filter.py
index 0d4844e6d..723879ec6 100644
--- a/tests/unit/test_recording_window_filter.py
+++ b/tests/unit/test_recording_window_filter.py
@@ -87,3 +87,25 @@ def test_select_handles_non_utc_aware_modified_at() -> None:
# 2026-01-01 05:30 EST == 10:30 UTC
recs = [_rec("est", datetime(2026, 1, 1, 5, 30, tzinfo=est))]
assert _select_recording_urls_in_window(recs, lower, upper) == ["est"]
+
+
+def test_select_unbounded_recovers_session_close_recording() -> None:
+ # Reproduces the persistent-session bug: the run window ends at 11:00 but the
+ # session's continuous recording is finalized/uploaded ~2h later at close, so the
+ # bounded window drops it while the unbounded fallback recovers it.
+ lower = datetime(2026, 1, 1, 10, 0, tzinfo=UTC)
+ upper = datetime(2026, 1, 1, 11, 0, tzinfo=UTC)
+ recs = [_rec("session-close", datetime(2026, 1, 1, 13, 1, tzinfo=UTC))]
+ assert _select_recording_urls_in_window(recs, lower, upper) == []
+ assert _select_recording_urls_in_window(recs, lower) == ["session-close"]
+
+
+def test_select_unbounded_still_excludes_pre_run_recording() -> None:
+ # A recording finalized before the run started belongs to an earlier session-run and
+ # must stay excluded even without an upper bound.
+ lower = datetime(2026, 1, 1, 10, 0, tzinfo=UTC)
+ recs = [
+ _rec("earlier", datetime(2026, 1, 1, 9, 30, tzinfo=UTC)),
+ _rec("this-run", datetime(2026, 1, 1, 13, 1, tzinfo=UTC)),
+ ]
+ assert _select_recording_urls_in_window(recs, lower) == ["this-run"]
diff --git a/tests/unit/test_resolve_otp_value.py b/tests/unit/test_resolve_otp_value.py
index e61541522..4bb001dc1 100644
--- a/tests/unit/test_resolve_otp_value.py
+++ b/tests/unit/test_resolve_otp_value.py
@@ -7,6 +7,7 @@ polling. Polling exceptions surface unchanged so callers can react.
from __future__ import annotations
+from datetime import datetime
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock, patch
@@ -86,10 +87,16 @@ async def test_credential_returns_value_skipping_poll_even_when_url_configured()
def _stub_workflow_run_lookup(
- monkeypatch_target, *, workflow_id: str | None, workflow_permanent_id: str | None
+ monkeypatch_target,
+ *,
+ workflow_id: str | None,
+ workflow_permanent_id: str | None,
+ started_at: datetime | None = None,
) -> MagicMock:
"""Patch app.DATABASE.workflow_runs.get_workflow_run with a recording mock."""
- workflow_run = SimpleNamespace(workflow_id=workflow_id, workflow_permanent_id=workflow_permanent_id)
+ workflow_run = SimpleNamespace(
+ workflow_id=workflow_id, workflow_permanent_id=workflow_permanent_id, started_at=started_at
+ )
get = AsyncMock(return_value=workflow_run)
monkeypatch_target.setattr(
"skyvern.services.otp_service.app.DATABASE.workflow_runs.get_workflow_run",
@@ -126,6 +133,43 @@ async def test_falls_through_to_poll_when_no_payload_or_credential(monkeypatch:
assert kwargs["totp_identifier"] == "[email protected]"
+async def test_forwards_run_started_at_as_created_after(monkeypatch: pytest.MonkeyPatch) -> None:
+ """The run's started_at is forwarded as created_after so prior-run codes are disqualified."""
+ poll_value = _otp_value("303030")
+ started_at = datetime(2026, 6, 8, 20, 3, 0)
+ task = _make_task(totp_identifier="[email protected]")
+ _stub_workflow_run_lookup(
+ monkeypatch, workflow_id="w_test", workflow_permanent_id="wpid_test", started_at=started_at
+ )
+ with (
+ patch("skyvern.services.otp_service.extract_totp_from_navigation_inputs", return_value=None),
+ patch("skyvern.services.otp_service.try_generate_totp_from_credential", return_value=None),
+ patch("skyvern.services.otp_service.poll_otp_value", new=AsyncMock(return_value=poll_value)) as poll,
+ ):
+ result = await resolve_otp_value(task)
+
+ assert result is poll_value
+ assert poll.await_args.kwargs["created_after"] == started_at
+
+
+async def test_created_after_is_none_when_run_started_at_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Null-fallback: a run with no started_at must not gain a watermark filter."""
+ poll_value = _otp_value("404040")
+ task = _make_task(totp_identifier="[email protected]")
+ _stub_workflow_run_lookup(monkeypatch, workflow_id="w_test", workflow_permanent_id="wpid_test", started_at=None)
+ with (
+ patch("skyvern.services.otp_service.extract_totp_from_navigation_inputs", return_value=None),
+ patch("skyvern.services.otp_service.try_generate_totp_from_credential", return_value=None),
+ patch("skyvern.services.otp_service.poll_otp_value", new=AsyncMock(return_value=poll_value)) as poll,
+ ):
+ result = await resolve_otp_value(task)
+
+ assert result is poll_value
+ assert poll.await_args.kwargs["created_after"] is None
+
+
@pytest.mark.asyncio
async def test_workflow_run_lookup_skipped_when_payload_resolves(monkeypatch: pytest.MonkeyPatch) -> None:
"""Codex must-fix: payload-resolved OTP must not pay a DB roundtrip."""
diff --git a/tests/unit/test_tag_endpoints.py b/tests/unit/test_tag_endpoints.py
index bd28d05c9..769cf7efe 100644
--- a/tests/unit/test_tag_endpoints.py
+++ b/tests/unit/test_tag_endpoints.py
@@ -1,15 +1,19 @@
-"""End-to-end tests for the workflow tag HTTP endpoints (Phase 3).
+"""End-to-end tests for the workflow tag HTTP endpoints.
Uses a real ``TagsRepository`` against in-memory SQLite, plus dependency
overrides for auth and a mocked ``workflows.get_workflow_by_permanent_id``
for the existence-check helper. The FastAPI ``base_router`` is mounted on
``/v1`` and ``legacy_base_router`` on ``/api/v1`` to mirror api_app.py.
+
+The public tag API is list-shaped (key-optional): a tag is ``{key?, value}``,
+so standalone labels (no key) and grouped labels coexist; responses are lists
+of tag objects rather than key-maps.
"""
from __future__ import annotations
import datetime as dt
-from typing import AsyncGenerator
+from typing import Any, AsyncGenerator
from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -32,6 +36,16 @@ OTHER_WPID = "wpid_beta"
CALLER_ID = "user_test"
+def _keys(tags: list[dict[str, Any]]) -> set[str | None]:
+ return {tag["key"] for tag in tags}
+
+
+def _by_key(tags: list[dict[str, Any]], key: str | None) -> dict[str, Any]:
+ match = next((tag for tag in tags if tag["key"] == key), None)
+ assert match is not None, f"no tag with key={key!r} in {tags}"
+ return match
+
+
@pytest_asyncio.fixture
async def engine() -> AsyncGenerator[AsyncEngine]:
eng = create_async_engine("sqlite+aiosqlite:///:memory:")
@@ -135,52 +149,79 @@ def test_post_tags_atomic_set_and_delete(client: TestClient) -> None:
"""Set + delete in one call: set wins on collision, delete removes other keys."""
resp = client.post(
f"/v1/workflows/{WPID}/tags",
- json={"tags": {"env": "prod", "team": "growth"}, "tags_to_delete": []},
+ json={
+ "tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}],
+ "tags_to_delete": [],
+ },
)
assert resp.status_code == 200, resp.text
- assert set(resp.json()["tags"].keys()) == {"env", "team"}
+ assert _keys(resp.json()["tags"]) == {"env", "team"}
# Same call: set "env=stage", delete "env" → set wins (same key collision)
resp = client.post(
f"/v1/workflows/{WPID}/tags",
- json={"tags": {"env": "stage"}, "tags_to_delete": ["env", "team"]},
+ json={"tags": [{"key": "env", "value": "stage"}], "tags_to_delete": [{"key": "env"}, {"key": "team"}]},
)
assert resp.status_code == 200
- body = resp.json()
+ tags = resp.json()["tags"]
# team was deleted; env was kept with new value (set-wins)
- assert set(body["tags"].keys()) == {"env"}
- assert body["tags"]["env"]["value"] == "stage"
- assert body["tags"]["env"]["set_by"] == CALLER_ID
+ assert _keys(tags) == {"env"}
+ assert _by_key(tags, "env")["value"] == "stage"
+ assert _by_key(tags, "env")["set_by"] == CALLER_ID
def test_post_tags_empty_noop(client: TestClient) -> None:
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {}, "tags_to_delete": []})
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [], "tags_to_delete": []})
assert resp.status_code == 200
- assert resp.json()["tags"] == {}
+ assert resp.json()["tags"] == []
+
+
+def test_post_standalone_label(client: TestClient) -> None:
+ """A single-string label (no key) is valid and round-trips with a null key."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"value": "production"}]})
+ assert resp.status_code == 200, resp.text
+ tags = resp.json()["tags"]
+ assert len(tags) == 1
+ assert tags[0]["key"] is None
+ assert tags[0]["value"] == "production"
+
+
+def test_post_grouped_and_standalone_coexist(client: TestClient) -> None:
+ resp = client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"value": "urgent"}]},
+ )
+ assert resp.status_code == 200, resp.text
+ tags = resp.json()["tags"]
+ assert _keys(tags) == {"env", None}
+ assert _by_key(tags, None)["value"] == "urgent"
def test_post_tags_invalid_key_returns_422(client: TestClient) -> None:
"""Keys starting with the reserved ``skyvern.`` prefix fail validation."""
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"skyvern.foo": "bar"}})
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "skyvern.foo", "value": "bar"}]})
assert resp.status_code == 422
def test_post_tags_bad_value_char_returns_422(client: TestClient) -> None:
- """Comma in value would break the ``?tags=k:v,k2:v2`` filter encoding."""
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"team": "a,b"}})
+ """Comma in value would break the ``?tags=`` filter encoding."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "team", "value": "a,b"}]})
assert resp.status_code == 422
def test_post_tags_404_when_workflow_not_in_org(client: TestClient) -> None:
resp = client.post(
"/v1/workflows/wpid_does_not_exist/tags",
- json={"tags": {"env": "prod"}},
+ json={"tags": [{"key": "env", "value": "prod"}]},
)
assert resp.status_code == 404
def test_post_tags_legacy_route_works(client: TestClient) -> None:
- resp = client.post(f"/api/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}, "tags_to_delete": []})
+ resp = client.post(
+ f"/api/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}], "tags_to_delete": []},
+ )
assert resp.status_code == 200
@@ -188,16 +229,28 @@ def test_post_tags_legacy_route_works(client: TestClient) -> None:
def test_delete_tag_supersedes_prior_set(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.delete(f"/v1/workflows/{WPID}/tags/env")
assert resp.status_code == 200
- assert "env" not in resp.json()["tags"]
+ assert "env" not in _keys(resp.json()["tags"])
def test_delete_tag_noop_when_absent(client: TestClient) -> None:
resp = client.delete(f"/v1/workflows/{WPID}/tags/nonexistent")
assert resp.status_code == 200
- assert resp.json()["tags"] == {}
+ assert resp.json()["tags"] == []
+
+
+def test_delete_standalone_label_via_body(client: TestClient) -> None:
+ """Standalone labels have no key, so they're removed by value through the
+ apply endpoint's tags_to_delete."""
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"value": "production"}]})
+ resp = client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [], "tags_to_delete": [{"value": "production"}]},
+ )
+ assert resp.status_code == 200
+ assert resp.json()["tags"] == []
def test_delete_tag_404_when_workflow_not_in_org(client: TestClient) -> None:
@@ -209,19 +262,33 @@ def test_delete_tag_404_when_workflow_not_in_org(client: TestClient) -> None:
def test_get_tags_returns_current_state(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}]},
+ )
resp = client.get(f"/v1/workflows/{WPID}/tags")
assert resp.status_code == 200
body = resp.json()
assert body["workflow_permanent_id"] == WPID
- assert set(body["tags"].keys()) == {"env", "team"}
- for entry in body["tags"].values():
+ assert _keys(body["tags"]) == {"env", "team"}
+ for entry in body["tags"]:
# Per-tag attribution surfaced (source/set_at/set_by).
assert entry["source"] == "manual"
assert entry["set_by"] == CALLER_ID
assert "set_at" in entry
+def test_get_tags_includes_standalone_and_grouped(client: TestClient) -> None:
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"value": "urgent"}]},
+ )
+ resp = client.get(f"/v1/workflows/{WPID}/tags")
+ assert resp.status_code == 200
+ tags = resp.json()["tags"]
+ assert _keys(tags) == {"env", None}
+
+
def test_get_tags_404_when_workflow_not_in_org(client: TestClient) -> None:
resp = client.get("/v1/workflows/wpid_missing/tags")
assert resp.status_code == 404
@@ -231,7 +298,7 @@ def test_get_tags_404_when_workflow_not_in_org(client: TestClient) -> None:
def test_get_history_includes_set_and_delete_events(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
client.delete(f"/v1/workflows/{WPID}/tags/env")
resp = client.get(f"/v1/workflows/{WPID}/tags/history")
assert resp.status_code == 200
@@ -241,7 +308,7 @@ def test_get_history_includes_set_and_delete_events(client: TestClient) -> None:
assert types == {"set", "delete"}
# Newest first.
assert events[0]["event_type"] == "delete"
- # DELETE row has null value; SET row carries the value.
+ # Grouped DELETE row has null value (identified by key); SET row carries the value.
delete_evt = next(e for e in events if e["event_type"] == "delete")
set_evt = next(e for e in events if e["event_type"] == "set")
assert delete_evt["value"] is None
@@ -249,7 +316,10 @@ def test_get_history_includes_set_and_delete_events(client: TestClient) -> None:
def test_get_history_filter_by_key(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}]},
+ )
resp = client.get(f"/v1/workflows/{WPID}/tags/history?key=team")
assert resp.status_code == 200
events = resp.json()["events"]
@@ -261,33 +331,50 @@ def test_get_history_filter_by_key(client: TestClient) -> None:
def test_list_tag_keys_returns_registered_keys(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}]},
+ )
resp = client.get("/v1/tag-keys")
assert resp.status_code == 200
keys = [row["key"] for row in resp.json()]
assert keys == ["env", "team"]
+def test_list_tag_keys_excludes_standalone_labels(client: TestClient) -> None:
+ """Standalone labels have no group, so they don't appear in the key registry."""
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"value": "urgent"}]},
+ )
+ resp = client.get("/v1/tag-keys")
+ assert resp.status_code == 200
+ assert [row["key"] for row in resp.json()] == ["env"]
+
+
def test_patch_tag_key_404_when_unknown(client: TestClient) -> None:
resp = client.patch("/v1/tag-keys/never_registered", json={"description": "hi"})
assert resp.status_code == 404
def test_patch_tag_key_updates_description(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.patch("/v1/tag-keys/env", json={"description": "deployment environment"})
assert resp.status_code == 200
assert resp.json()["description"] == "deployment environment"
def test_patch_tag_key_description_too_long_returns_422(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.patch("/v1/tag-keys/env", json={"description": "x" * 501})
assert resp.status_code == 422
def test_list_tag_keys_includes_workflow_count(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}]},
+ )
resp = client.get("/v1/tag-keys")
assert resp.status_code == 200
by_key = {row["key"]: row for row in resp.json()}
@@ -299,13 +386,16 @@ def test_list_tag_keys_includes_workflow_count(client: TestClient) -> None:
def test_delete_tag_key_removes_from_registry_and_workflow(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}]},
+ )
resp = client.delete("/v1/tag-keys/env")
assert resp.status_code == 200
assert resp.json() == {"key": "env", "removed_from_workflow_count": 1}
assert [row["key"] for row in client.get("/v1/tag-keys").json()] == ["team"]
- assert set(client.get(f"/v1/workflows/{WPID}/tags").json()["tags"].keys()) == {"team"}
+ assert _keys(client.get(f"/v1/workflows/{WPID}/tags").json()["tags"]) == {"team"}
def test_delete_tag_key_404_when_unknown(client: TestClient) -> None:
@@ -319,7 +409,7 @@ def test_delete_tag_key_reserved_prefix_returns_400(client: TestClient) -> None:
def test_delete_tag_key_legacy_route_works(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.delete("/api/v1/tag-keys/env")
assert resp.status_code == 200
assert resp.json()["removed_from_workflow_count"] == 1
@@ -329,16 +419,32 @@ def test_delete_tag_key_legacy_route_works(client: TestClient) -> None:
def test_batch_get_returns_map_keyed_by_wpid(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.get(f"/v1/workflow-tags?workflow_permanent_ids={WPID}")
assert resp.status_code == 200
- assert resp.json()["workflow_tags"] == {WPID: {"env": "prod"}}
+ assert resp.json()["workflow_tags"] == {WPID: [{"key": "env", "value": "prod"}]}
-def test_batch_get_returns_empty_dict_for_workflow_with_no_tags(client: TestClient) -> None:
+def test_batch_get_includes_standalone_labels_in_stable_order(client: TestClient) -> None:
+ client.post(
+ f"/v1/workflows/{WPID}/tags",
+ json={"tags": [{"key": "team", "value": "growth"}, {"key": "env", "value": "prod"}, {"value": "urgent"}]},
+ )
+ resp = client.get(f"/v1/workflow-tags?workflow_permanent_ids={WPID}")
+ assert resp.status_code == 200
+ tags = resp.json()["workflow_tags"][WPID]
+ # Deterministic: standalone labels first, then grouped by key, then value.
+ assert tags == [
+ {"key": None, "value": "urgent"},
+ {"key": "env", "value": "prod"},
+ {"key": "team", "value": "growth"},
+ ]
+
+
+def test_batch_get_returns_empty_list_for_workflow_with_no_tags(client: TestClient) -> None:
resp = client.get(f"/v1/workflow-tags?workflow_permanent_ids={WPID}")
assert resp.status_code == 200
- assert resp.json()["workflow_tags"] == {WPID: {}}
+ assert resp.json()["workflow_tags"] == {WPID: []}
def test_batch_get_cross_org_isolation(client: TestClient, repo: TagsRepository) -> None:
@@ -366,51 +472,60 @@ def test_batch_get_cross_org_isolation(client: TestClient, repo: TagsRepository)
body = resp.json()["workflow_tags"]
# OTHER_WPID is echoed (since the caller asked for it) but carries no
# values — cross-org filter in the repo zeroes it out.
- assert body[OTHER_WPID] == {}
- assert body[WPID] == {}
+ assert body[OTHER_WPID] == []
+ assert body[WPID] == []
def test_batch_post_accepts_body(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.post("/v1/workflow-tags", json={"workflow_permanent_ids": [WPID]})
assert resp.status_code == 200
- assert resp.json()["workflow_tags"] == {WPID: {"env": "prod"}}
+ assert resp.json()["workflow_tags"] == {WPID: [{"key": "env", "value": "prod"}]}
def test_batch_get_legacy_route_works(client: TestClient) -> None:
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.get(f"/api/v1/workflow-tags?workflow_permanent_ids={WPID}")
assert resp.status_code == 200
-# --------------------- Debated-plan fixes (CORR-1, CORR-3, CORR-4, RISK-1, RISK-3, RISK-4) ---------------------
+# --------------------- Shape/namespace guards (CORR-1, CORR-3, CORR-4, RISK-1, RISK-3, RISK-4) ---------------------
-def test_post_tags_list_body_returns_422(client: TestClient) -> None:
- """CORR-1: outer-shape guard. A list body where the schema expects a dict
- must return 422, not 500 (leaking AttributeError) and not 200."""
+def test_post_tags_dict_body_returns_422(client: TestClient) -> None:
+ """CORR-1: the old dict shape must fail cleanly (422), not coerce."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ assert resp.status_code == 422
+
+
+def test_post_tags_bare_string_items_return_422(client: TestClient) -> None:
+ """CORR-1: list items must be {key?, value} objects, not bare strings."""
resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": ["env"]})
assert resp.status_code == 422
def test_post_tags_non_string_value_returns_422(client: TestClient) -> None:
- """CORR-1: inner-element guard. JSON int values must surface as 422 with
- a clean message instead of crashing inside `value.strip()`."""
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": 1}})
+ """CORR-1: JSON int values must surface as 422, not crash inside value handling."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": 1}]})
assert resp.status_code == 422
def test_post_tags_to_delete_as_string_returns_422(client: TestClient) -> None:
- """CORR-1: critical silent-bug fix. Without the explicit list/tuple guard,
- `tags_to_delete: "env"` would silently iterate to ['e', 'n', 'v']."""
+ """CORR-1: a string tags_to_delete must 422, not iterate char-by-char."""
resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags_to_delete": "env"})
assert resp.status_code == 422
+def test_post_tags_to_delete_empty_target_returns_422(client: TestClient) -> None:
+ """A delete target with neither key nor value identifies nothing."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags_to_delete": [{}]})
+ assert resp.status_code == 422
+
+
def test_post_tags_to_delete_reserved_namespace_returns_422(client: TestClient) -> None:
- """CORR-3: skyvern.* keys are blocked on SET via normalize_tags. The same
- boundary must apply to the body-DELETE path."""
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags_to_delete": ["skyvern.managed"]})
+ """CORR-3: skyvern.* keys are blocked on SET; the same boundary applies to
+ the body-DELETE path."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags_to_delete": [{"key": "skyvern.managed"}]})
assert resp.status_code == 422
@@ -418,7 +533,7 @@ def test_post_tags_to_delete_over_cap_returns_422(client: TestClient) -> None:
"""RISK-1: tags_to_delete must be capped at the same scale as `tags`."""
resp = client.post(
f"/v1/workflows/{WPID}/tags",
- json={"tags_to_delete": [f"k{i}" for i in range(21)]},
+ json={"tags_to_delete": [{"value": f"v{i}"} for i in range(21)]},
)
assert resp.status_code == 422
@@ -437,9 +552,7 @@ def test_delete_path_bad_shape_returns_400(client: TestClient) -> None:
def test_patch_tag_key_reserved_namespace_returns_400(client: TestClient) -> None:
- """CORR-4: same namespace boundary on the registry PATCH surface — once
- Phase 4/5 system writers populate skyvern.* keys, the public PATCH API
- must not let callers rewrite their descriptions."""
+ """CORR-4: same namespace boundary on the registry PATCH surface."""
resp = client.patch("/v1/tag-keys/skyvern.managed", json={"description": "hi"})
assert resp.status_code == 400
@@ -451,7 +564,7 @@ def test_patch_tag_key_bad_shape_returns_400(client: TestClient) -> None:
def test_patch_tag_key_description_non_string_returns_422(client: TestClient) -> None:
"""CORR-1: TagKeyUpdate.description type guard for non-str payloads."""
- client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
resp = client.patch("/v1/tag-keys/env", json={"description": 123})
assert resp.status_code == 422
@@ -460,9 +573,7 @@ def test_batch_get_drops_workflow_deleted_between_checks(
monkeypatch: pytest.MonkeyPatch, app_with_routes: FastAPI, repo: TagsRepository
) -> None:
"""RISK-4: the double-check pattern must drop a wpid that was soft-deleted
- *between* the pre-read existence query and the post-read existence query.
- Simulated by overriding get_existing_permanent_ids to return the wpid on
- the first call and an empty set on the second."""
+ *between* the pre-read existence query and the post-read existence query."""
import asyncio
from skyvern.forge.sdk.workflow.models.tags import TagSource, TagWriteContext
@@ -487,7 +598,6 @@ def test_batch_get_drops_workflow_deleted_between_checks(
return set() # second check: workflow was soft-deleted in between
app_with_routes.dependency_overrides # ensure fixture build
- # Override the get_existing_permanent_ids on the patched workflows mock.
from skyvern.forge.sdk.routes import agent_protocol as ap
ap.app.DATABASE.workflows.get_existing_permanent_ids = AsyncMock(side_effect=_existence_check_then_disappear)
@@ -496,13 +606,12 @@ def test_batch_get_drops_workflow_deleted_between_checks(
resp = client.get(f"/v1/workflow-tags?workflow_permanent_ids={WPID}")
assert resp.status_code == 200
# Final response must NOT carry the now-deleted workflow's tags.
- assert resp.json()["workflow_tags"] == {WPID: {}}
+ assert resp.json()["workflow_tags"] == {WPID: []}
def test_post_returns_409_when_integrity_error_persists(app_with_routes: FastAPI) -> None:
"""RISK-3: two consecutive IntegrityErrors from apply_tag_changes surface
- as 409 Conflict, not 500. Documented same-workflow/same-key race from
- Phase 2 should never produce an unstructured server error."""
+ as 409 Conflict, not 500."""
from sqlalchemy.exc import IntegrityError
from skyvern.forge.sdk.routes import agent_protocol as ap
@@ -512,7 +621,7 @@ def test_post_returns_409_when_integrity_error_persists(app_with_routes: FastAPI
)
client = TestClient(app_with_routes)
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
assert resp.status_code == 409
@@ -537,6 +646,6 @@ def test_post_succeeds_when_first_integrity_error_then_succeeds(app_with_routes:
ap.app.DATABASE.tags.get_active_tag_events_for_workflow = AsyncMock(return_value=[])
client = TestClient(app_with_routes)
- resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})
assert resp.status_code == 200
assert attempts["n"] == 2
diff --git a/tests/unit/test_tag_schemas.py b/tests/unit/test_tag_schemas.py
index 6b3f39db7..e6950cc54 100644
--- a/tests/unit/test_tag_schemas.py
+++ b/tests/unit/test_tag_schemas.py
@@ -1,9 +1,8 @@
"""Schema-level validation tests for ``skyvern/schemas/tags.py``.
-Covers Python-construction paths that JSON-over-HTTP can't exercise. For
-example, JSON object keys are always strings on the wire (json.dumps coerces
-int keys to ``"1"``), so the non-string-KEY test has to call
-``model_validate`` directly.
+Covers the list-shaped (key-optional) tag apply request — standalone labels,
+grouped labels, and the delete-target identity rules — plus construction paths
+that JSON-over-HTTP can't easily exercise.
"""
from __future__ import annotations
@@ -14,37 +13,119 @@ from pydantic import ValidationError
from skyvern.schemas.tags import TagApplyRequest, TagKeyUpdate
-def test_tag_apply_request_rejects_non_string_dict_key() -> None:
- """COMP-1: this path can only be constructed in Python — JSON coerces
- int keys to strings before serialization."""
+def test_standalone_label_parses_with_null_key() -> None:
+ parsed = TagApplyRequest.model_validate({"tags": [{"value": "production"}]})
+ assert len(parsed.tags) == 1
+ assert parsed.tags[0].key is None
+ assert parsed.tags[0].value == "production"
+
+
+def test_grouped_label_parses() -> None:
+ parsed = TagApplyRequest.model_validate({"tags": [{"key": "env", "value": "prod"}]})
+ assert parsed.tags[0].key == "env"
+ assert parsed.tags[0].value == "prod"
+
+
+def test_blank_key_normalizes_to_standalone() -> None:
+ parsed = TagApplyRequest.model_validate({"tags": [{"key": " ", "value": "prod"}]})
+ assert parsed.tags[0].key is None
+
+
+def test_tags_must_be_a_list_not_dict() -> None:
+ # The old dict shape must fail cleanly, not coerce.
with pytest.raises(ValidationError):
- TagApplyRequest.model_validate({"tags": {1: "prod"}})
+ TagApplyRequest.model_validate({"tags": {"env": "prod"}})
-def test_tag_apply_request_rejects_non_string_dict_value() -> None:
- """Same guard at the value side, also exercised by the endpoint test
- (this assertion is the unit-level equivalent)."""
+def test_tag_missing_value_rejected() -> None:
with pytest.raises(ValidationError):
- TagApplyRequest.model_validate({"tags": {"env": 1}})
+ TagApplyRequest.model_validate({"tags": [{"key": "env"}]})
-def test_tag_apply_request_rejects_string_tags_to_delete() -> None:
- """Without the explicit list/tuple check, a string body would silently
- iterate char-by-char."""
+def test_tag_non_string_value_rejected() -> None:
with pytest.raises(ValidationError):
- TagApplyRequest.model_validate({"tags_to_delete": "env"})
+ TagApplyRequest.model_validate({"tags": [{"key": "env", "value": 1}]})
+
+
+def test_tag_reserved_namespace_key_rejected() -> None:
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": [{"key": "skyvern.managed", "value": "v"}]})
+
+
+def test_tag_comma_value_rejected() -> None:
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": [{"value": "a,b"}]})
+
+
+def test_standalone_label_colon_value_rejected() -> None:
+ # A group-less label can't contain ':' (it would be unfilterable as a
+ # value-only term, which parses ':' as group:label).
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": [{"value": "release:2026"}]})
+
+
+def test_grouped_value_may_contain_colon() -> None:
+ # With a group, ':' in the value is fine — the key disambiguates.
+ parsed = TagApplyRequest.model_validate({"tags": [{"key": "url", "value": "http://x:8000"}]})
+ assert parsed.tags[0].value == "http://x:8000"
+
+
+def test_grouped_star_value_rejected() -> None:
+ # `key:*` is the group filter wildcard, so a literal '*' value would be
+ # unfilterable exactly.
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": [{"key": "env", "value": "*"}]})
+
+
+def test_standalone_star_value_allowed() -> None:
+ # A bare `*` term (no colon) is a value-only filter, so a standalone '*'
+ # label is still filterable and therefore allowed.
+ parsed = TagApplyRequest.model_validate({"tags": [{"value": "*"}]})
+ assert parsed.tags[0].key is None
+ assert parsed.tags[0].value == "*"
+
+
+def test_tags_over_cap_rejected() -> None:
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": [{"value": f"v{i}"} for i in range(21)]})
+
+
+def test_delete_target_by_key() -> None:
+ parsed = TagApplyRequest.model_validate({"tags_to_delete": [{"key": "env"}]})
+ assert parsed.tags_to_delete[0].key == "env"
+ assert parsed.tags_to_delete[0].value is None
+
+
+def test_delete_target_by_value() -> None:
+ parsed = TagApplyRequest.model_validate({"tags_to_delete": [{"value": "production"}]})
+ assert parsed.tags_to_delete[0].key is None
+ assert parsed.tags_to_delete[0].value == "production"
-def test_tag_apply_request_rejects_reserved_namespace_in_deletes() -> None:
- """``skyvern.*`` is reserved on SET; the same boundary must hold on the
- body DELETE path."""
+def test_delete_target_requires_key_or_value() -> None:
with pytest.raises(ValidationError):
- TagApplyRequest.model_validate({"tags_to_delete": ["skyvern.managed"]})
+ TagApplyRequest.model_validate({"tags_to_delete": [{}]})
+
+
+def test_delete_target_rejects_both_key_and_value() -> None:
+ # Ambiguous: a grouped delete uses key, a standalone delete uses value.
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags_to_delete": [{"key": "env", "value": "prod"}]})
+
+
+def test_delete_target_reserved_namespace_rejected() -> None:
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags_to_delete": [{"key": "skyvern.managed"}]})
+
+
+def test_tags_to_delete_must_be_a_list() -> None:
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags_to_delete": "env"})
-def test_tag_apply_request_caps_tags_to_delete() -> None:
+def test_tags_to_delete_over_cap_rejected() -> None:
with pytest.raises(ValidationError):
- TagApplyRequest.model_validate({"tags_to_delete": [f"k{i}" for i in range(21)]})
+ TagApplyRequest.model_validate({"tags_to_delete": [{"value": f"v{i}"} for i in range(21)]})
def test_tag_key_update_rejects_non_string_description() -> None:
diff --git a/tests/unit/test_tag_validators.py b/tests/unit/test_tag_validators.py
index d7e030323..aa62d45b7 100644
--- a/tests/unit/test_tag_validators.py
+++ b/tests/unit/test_tag_validators.py
@@ -5,14 +5,18 @@ from skyvern.forge.sdk.workflow.models.validators import (
RUN_METADATA_MAX_KEYS,
RUN_METADATA_MAX_VALUE_LENGTH,
TAG_DESCRIPTION_MAX_LENGTH,
+ TAG_KEY_MAX_LENGTH,
+ TAG_VALUE_MAX_LENGTH,
+ normalize_optional_tag_key,
+ normalize_optional_tag_value,
normalize_run_metadata,
normalize_tag_description,
- normalize_tags,
+ normalize_tag_value,
)
class TestNormalizeRunMetadataUnchanged:
- """Lock the existing normalize_run_metadata contract through the shared-core refactor."""
+ """Lock the existing normalize_run_metadata contract through the tag refactor."""
def test_none_passes_through(self) -> None:
assert normalize_run_metadata(None) is None
@@ -41,51 +45,35 @@ class TestNormalizeRunMetadataUnchanged:
def test_run_metadata_permits_punctuation_in_keys(self) -> None:
# Existing shipped behavior: run_metadata does NOT restrict key characters.
- # Only normalize_tags applies the stricter regex.
+ # Only the tag validators apply the stricter regex.
assert normalize_run_metadata({"weird:key": "v"}) == {"weird:key": "v"}
assert normalize_run_metadata({"k": "value,with,commas"}) == {"k": "value,with,commas"}
-class TestNormalizeTagsCaps:
- def test_none_passes_through(self) -> None:
- assert normalize_tags(None) is None
+class TestNormalizeOptionalTagKey:
+ def test_none_is_standalone(self) -> None:
+ # Null/blank key == standalone label (no group).
+ assert normalize_optional_tag_key(None) is None
+ assert normalize_optional_tag_key("") is None
+ assert normalize_optional_tag_key(" ") is None
def test_strips_whitespace(self) -> None:
- assert normalize_tags({" env ": " prod "}) == {"env": "prod"}
-
- def test_skips_empty_pairs(self) -> None:
- assert normalize_tags({"a": "v", "b": "", "c": " "}) == {"a": "v"}
+ assert normalize_optional_tag_key(" env ") == "env"
- def test_over_max_keys_raises(self) -> None:
- too_many = {f"k{i}": "v" for i in range(RUN_METADATA_MAX_KEYS + 1)}
- with pytest.raises(ValueError, match="at most"):
- normalize_tags(too_many)
+ def test_non_string_raises(self) -> None:
+ with pytest.raises(ValueError, match="must be a string"):
+ normalize_optional_tag_key(1)
def test_key_too_long_raises(self) -> None:
with pytest.raises(ValueError, match="keys must be at most"):
- normalize_tags({"k" * (RUN_METADATA_MAX_KEY_LENGTH + 1): "v"})
-
- def test_value_too_long_raises(self) -> None:
- with pytest.raises(ValueError, match="values must be at most"):
- normalize_tags({"k": "v" * (RUN_METADATA_MAX_VALUE_LENGTH + 1)})
-
+ normalize_optional_tag_key("k" * (TAG_KEY_MAX_LENGTH + 1))
-class TestNormalizeTagsKeyRegex:
@pytest.mark.parametrize(
"key",
- [
- "env",
- "customer.id",
- "team_name",
- "use-case",
- "Env",
- "k1",
- "a",
- "A1.b-c_d",
- ],
+ ["env", "customer.id", "team_name", "use-case", "Env", "k1", "a", "A1.b-c_d"],
)
def test_valid_keys_accepted(self, key: str) -> None:
- assert normalize_tags({key: "v"}) == {key: "v"}
+ assert normalize_optional_tag_key(key) == key
@pytest.mark.parametrize(
"key",
@@ -93,10 +81,6 @@ class TestNormalizeTagsKeyRegex:
"key:with:colons",
"key,with,commas",
"key/with/slashes",
- "key?with?question",
- "key#hash",
- "key=equals",
- "key&amp",
"key with space",
"_leading_underscore",
".leading.dot",
@@ -105,40 +89,64 @@ class TestNormalizeTagsKeyRegex:
)
def test_invalid_keys_rejected(self, key: str) -> None:
with pytest.raises(ValueError, match="must match"):
- normalize_tags({key: "v"})
+ normalize_optional_tag_key(key)
+
+ @pytest.mark.parametrize("key", ["skyvern.trigger_type", "skyvern.managed", "skyvern.foo"])
+ def test_skyvern_prefix_rejected(self, key: str) -> None:
+ with pytest.raises(ValueError, match="reserved"):
+ normalize_optional_tag_key(key)
+ def test_skyvern_inside_key_allowed(self) -> None:
+ assert normalize_optional_tag_key("my-skyvern") == "my-skyvern"
+
+ def test_bare_skyvern_key_allowed(self) -> None:
+ # 'skyvern' without the dot separator is not the reserved prefix.
+ assert normalize_optional_tag_key("skyvern") == "skyvern"
-class TestNormalizeTagsValueRestrictions:
- def test_comma_in_value_rejected(self) -> None:
+
+class TestNormalizeTagValue:
+ def test_strips_whitespace(self) -> None:
+ assert normalize_tag_value(" prod ") == "prod"
+
+ def test_empty_raises(self) -> None:
+ # The label (value) is always required.
+ with pytest.raises(ValueError, match="required"):
+ normalize_tag_value(" ")
+
+ def test_non_string_raises(self) -> None:
+ with pytest.raises(ValueError, match="must be a string"):
+ normalize_tag_value(1)
+
+ def test_value_too_long_raises(self) -> None:
+ with pytest.raises(ValueError, match="values must be at most"):
+ normalize_tag_value("v" * (TAG_VALUE_MAX_LENGTH + 1))
+
+ def test_comma_rejected(self) -> None:
with pytest.raises(ValueError, match="must not contain ','"):
- normalize_tags({"k": "value,with,comma"})
+ normalize_tag_value("value,with,comma")
- def test_colon_in_value_allowed(self) -> None:
+ def test_colon_allowed(self) -> None:
# `:` is fine in values: the ?tags= parser splits on the first ':' only.
- assert normalize_tags({"env": "staging:us-east-1"}) == {"env": "staging:us-east-1"}
+ assert normalize_tag_value("staging:us-east-1") == "staging:us-east-1"
def test_value_allows_other_punctuation(self) -> None:
- assert normalize_tags({"k": "value with spaces.and-dashes_and!special"}) == {
- "k": "value with spaces.and-dashes_and!special"
- }
+ assert normalize_tag_value("value with spaces.and-dashes_and!special") == (
+ "value with spaces.and-dashes_and!special"
+ )
-class TestNormalizeTagsReservedNamespace:
- @pytest.mark.parametrize(
- "key",
- ["skyvern.trigger_type", "skyvern.managed", "skyvern.foo"],
- )
- def test_skyvern_prefix_rejected(self, key: str) -> None:
- with pytest.raises(ValueError, match="reserved"):
- normalize_tags({key: "v"})
+class TestNormalizeOptionalTagValue:
+ def test_none_and_blank_pass_through(self) -> None:
+ assert normalize_optional_tag_value(None) is None
+ assert normalize_optional_tag_value("") is None
+ assert normalize_optional_tag_value(" ") is None
- def test_skyvern_inside_key_allowed(self) -> None:
- # Only the `skyvern.` prefix is reserved; substring is fine.
- assert normalize_tags({"my-skyvern": "v"}) == {"my-skyvern": "v"}
+ def test_valid_value_trimmed(self) -> None:
+ assert normalize_optional_tag_value(" prod ") == "prod"
- def test_bare_skyvern_key_allowed(self) -> None:
- # 'skyvern' without the dot separator is not the reserved prefix.
- assert normalize_tags({"skyvern": "v"}) == {"skyvern": "v"}
+ def test_comma_rejected(self) -> None:
+ with pytest.raises(ValueError, match="must not contain ','"):
+ normalize_optional_tag_value("a,b")
class TestNormalizeTagDescription:
diff --git a/tests/unit/test_tags_repository.py b/tests/unit/test_tags_repository.py
index ffa440005..452e3053f 100644
--- a/tests/unit/test_tags_repository.py
+++ b/tests/unit/test_tags_repository.py
@@ -83,7 +83,7 @@ async def test_no_op_when_sets_and_deletes_empty(repo: TagsRepository) -> None:
async def test_initial_set_creates_event_and_registers_key(repo: TagsRepository) -> None:
await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
assert await _registered_keys(repo) == ["env"]
@@ -92,7 +92,7 @@ async def test_set_existing_key_supersedes_prior_row(repo: TagsRepository) -> No
await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "stg"}, deletes=set(), context=_ctx())
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {"env": "stg"}
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {"env": "stg"}
rows = await _all_events(repo)
assert len(rows) == 2
@@ -116,7 +116,7 @@ async def test_delete_writes_delete_event_with_null_value(repo: TagsRepository)
await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes={"env"}, context=_ctx())
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {}
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {}
rows = await _all_events(repo)
assert len(rows) == 2
@@ -137,7 +137,7 @@ async def test_sets_win_on_same_key_collision(repo: TagsRepository) -> None:
await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "stg"}, deletes={"env"}, context=_ctx())
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {"env": "stg"}
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {"env": "stg"}
rows = await _all_events(repo)
# No DELETE event got emitted for the colliding key.
assert [r.event_type for r in rows] == [TagEventType.SET.value, TagEventType.SET.value]
@@ -159,7 +159,7 @@ async def test_cap_allows_replace_at_limit(repo: TagsRepository) -> None:
await repo.apply_tag_changes(WPID, ORG_ID, sets={"k0": "new"}, deletes=set(), context=_ctx())
- current = await repo.get_active_tags_for_workflow(WPID, ORG_ID)
+ current = await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID)
assert current["k0"] == "new"
assert len(current) == MAX_TAGS_PER_WORKFLOW
@@ -230,8 +230,8 @@ async def test_isolation_between_workflows_in_same_org(repo: TagsRepository) ->
await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
await repo.apply_tag_changes("wpid_b", ORG_ID, sets={"env": "stg"}, deletes=set(), context=_ctx())
- assert await repo.get_active_tags_for_workflow("wpid_a", ORG_ID) == {"env": "prod"}
- assert await repo.get_active_tags_for_workflow("wpid_b", ORG_ID) == {"env": "stg"}
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_a", ORG_ID) == {"env": "prod"}
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_b", ORG_ID) == {"env": "stg"}
def test_tag_count_limit_is_registered_as_passthrough_exception() -> None:
@@ -301,7 +301,7 @@ async def test_realistic_tag_examples(repo: TagsRepository, tags: dict[str, str]
what shapes the system supports.
"""
await repo.apply_tag_changes(WPID, ORG_ID, sets=tags, deletes=set(), context=_ctx())
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == tags
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == tags
@pytest.mark.asyncio
@@ -324,7 +324,7 @@ async def test_dotted_key_hierarchy_works_without_schema_change(repo: TagsReposi
deletes=set(),
context=_ctx(),
)
- active = await repo.get_active_tags_for_workflow(WPID, ORG_ID)
+ active = await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID)
assert active == {
"team": "payments",
"team.subteam": "billing",
@@ -352,15 +352,15 @@ async def test_same_key_value_across_many_workflows_n_to_m(repo: TagsRepository)
context=_ctx(),
)
- assert await repo.get_active_tags_for_workflow("wpid_invoice_processor", ORG_ID) == {
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_invoice_processor", ORG_ID) == {
"team": "payments",
"environment": "prod",
"priority": "p0",
}
- assert await repo.get_active_tags_for_workflow("wpid_refund_handler", ORG_ID) == {
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_refund_handler", ORG_ID) == {
"team": "payments",
}
- assert await repo.get_active_tags_for_workflow("wpid_billing_sync", ORG_ID) == {
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_billing_sync", ORG_ID) == {
"team": "payments",
}
@@ -383,7 +383,7 @@ async def test_value_can_contain_colons(repo: TagsRepository) -> None:
deletes=set(),
context=_ctx(),
)
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {
"jira_ticket": "PROJ-1234:bugfix",
"captured_at": "2026-05-25T18:30:00Z",
}
@@ -401,7 +401,7 @@ async def test_get_active_tags_for_workflows_batch(repo: TagsRepository) -> None
await repo.apply_tag_changes(WPID, "o_other", sets={"secret": "leak"}, deletes=set(), context=_ctx("other"))
result = await repo.get_active_tags_for_workflows([WPID, "wpid_beta", "wpid_missing"], ORG_ID)
- assert result == {WPID: {"env": "prod"}, "wpid_beta": {"team": "growth"}}
+ assert result == {WPID: [("env", "prod")], "wpid_beta": [("team", "growth")]}
@pytest.mark.asyncio
@@ -497,7 +497,7 @@ async def test_apply_tag_changes_idempotent_when_tag_key_already_exists(repo: Ta
.all()
)
assert len(keys) == 1
- assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
@pytest.mark.asyncio
@@ -534,8 +534,8 @@ async def test_delete_tag_key_cascades_across_workflows(repo: TagsRepository) ->
assert removed == 2
# Tag gone from both workflows...
- assert await repo.get_active_tags_for_workflow("wpid_a", ORG_ID) == {}
- assert await repo.get_active_tags_for_workflow("wpid_b", ORG_ID) == {"team": "core"}
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_a", ORG_ID) == {}
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_b", ORG_ID) == {"team": "core"}
# ...and the key no longer appears in the active registry.
assert [row.key for row in await repo.list_tag_keys(ORG_ID)] == ["team"]
@@ -561,5 +561,104 @@ async def test_delete_tag_key_then_reapply_reregisters(repo: TagsRepository) ->
await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "dev"}, deletes=set(), context=_ctx())
- assert await repo.get_active_tags_for_workflow("wpid_a", ORG_ID) == {"env": "dev"}
+ assert await repo.get_active_grouped_tags_for_workflow("wpid_a", ORG_ID) == {"env": "dev"}
assert [row.key for row in await repo.list_tag_keys(ORG_ID)] == ["env"]
+
+
+# ---------------------- Phase 6.1: key-optional (standalone) labels ----------------------
+
+
+async def _active_labels(repo: TagsRepository, wpid: str = WPID, org_id: str = ORG_ID) -> set[str]:
+ """Standalone labels (no group) currently active on a workflow."""
+ rows = await repo.get_active_tag_events_for_workflow(wpid, org_id)
+ return {row.value for row in rows if row.key is None}
+
+
+async def test_standalone_label_set_and_read(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["production"])
+
+ # Standalone labels carry no key, so they don't show in the grouped map...
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {}
+ # ...and they don't register a tag key.
+ assert await _registered_keys(repo) == []
+ # But the label is active.
+ assert await _active_labels(repo) == {"production"}
+
+
+async def test_standalone_label_re_add_is_no_op(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["urgent"])
+ changes = await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["urgent"])
+ assert changes == []
+ assert await _event_count(repo) == 1
+
+
+async def test_standalone_and_grouped_coexist(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(
+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), label_sets=["urgent"]
+ )
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
+ assert await _active_labels(repo) == {"urgent"}
+
+
+async def test_same_value_grouped_and_standalone_are_independent(repo: TagsRepository) -> None:
+ """A grouped tag `env:prod` and a standalone label `prod` are different
+ identities (key vs value) and coexist on one workflow."""
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), label_sets=["prod"])
+ assert await repo.get_active_grouped_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
+ assert await _active_labels(repo) == {"prod"}
+
+
+async def test_standalone_label_delete_records_value(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["production"])
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_deletes=["production"])
+
+ assert await _active_labels(repo) == set()
+ rows = await _all_events(repo)
+ assert len(rows) == 2
+ assert rows[1].event_type == TagEventType.DELETE.value
+ # The standalone-label delete records which label was removed (no key to identify it).
+ assert rows[1].key is None
+ assert rows[1].value == "production"
+
+
+async def test_standalone_label_set_wins_over_delete(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["keep"])
+ await repo.apply_tag_changes(
+ WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["keep"], label_deletes=["keep"]
+ )
+ # Set wins: the label survives and no DELETE event was written.
+ assert await _active_labels(repo) == {"keep"}
+ assert [r.event_type for r in await _all_events(repo)] == [TagEventType.SET.value]
+
+
+async def test_cap_counts_grouped_and_labels_together(repo: TagsRepository) -> None:
+ grouped = {f"k{i}": "v" for i in range(MAX_TAGS_PER_WORKFLOW - 1)}
+ await repo.apply_tag_changes(WPID, ORG_ID, sets=grouped, deletes=set(), context=_ctx(), label_sets=["one_label"])
+ # At the cap (19 grouped + 1 label = 20); one more label trips it.
+ with pytest.raises(TagCountLimitExceeded):
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["over"])
+
+
+async def test_count_active_workflows_per_key_ignores_standalone(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(
+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), label_sets=["urgent"]
+ )
+ # Standalone labels have no key and must not appear in the per-key counts.
+ assert await repo.count_active_workflows_per_key(ORG_ID) == {"env": 1}
+
+
+async def test_batch_includes_standalone_labels(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(
+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), label_sets=["urgent"]
+ )
+ result = await repo.get_active_tags_for_workflows([WPID], ORG_ID)
+ assert set(result[WPID]) == {("env", "prod"), (None, "urgent")}
diff --git a/tests/unit/test_workflows_list_tag_filter.py b/tests/unit/test_workflows_list_tag_filter.py
index dac303e47..287820283 100644
--- a/tests/unit/test_workflows_list_tag_filter.py
+++ b/tests/unit/test_workflows_list_tag_filter.py
@@ -202,6 +202,82 @@ async def test_tag_filter_composes_with_search_key(repo: WorkflowsRepository) ->
assert result == {"wpid_a"}
+# ---------------------- Phase 6.1: value-only / group-only / standalone ----------------------
+
+
+async def _set_label(
+ repo: WorkflowsRepository,
+ *,
+ wpid: str,
+ value: str,
+ organization_id: str = ORG_ID,
+) -> None:
+ """Insert an active standalone-label SET event (no group / key)."""
+ async with repo.Session() as session:
+ session.add(
+ WorkflowTagEventModel(
+ workflow_permanent_id=wpid,
+ organization_id=organization_id,
+ key=None,
+ value=value,
+ event_type=TagEventType.SET.value,
+ set_at=datetime.now(timezone.utc),
+ set_by="user_test",
+ source=TagSource.MANUAL.value,
+ )
+ )
+ await session.commit()
+
+
+async def test_value_only_matches_grouped_and_standalone(repo: WorkflowsRepository) -> None:
+ """A value-only (label) term matches the value across any group and on
+ standalone labels."""
+ await _create_workflow(repo, wpid="wpid_grouped", title="G")
+ await _create_workflow(repo, wpid="wpid_standalone", title="S")
+ await _create_workflow(repo, wpid="wpid_other", title="O")
+ await _set_tag(repo, wpid="wpid_grouped", key="env", value="prod")
+ await _set_label(repo, wpid="wpid_standalone", value="prod")
+ await _set_tag(repo, wpid="wpid_other", key="env", value="dev")
+
+ assert await _wpids(repo, workflow_tags=[(None, "prod")]) == {"wpid_grouped", "wpid_standalone"}
+
+
+async def test_group_only_matches_any_value_in_group(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _create_workflow(repo, wpid="wpid_b", title="B")
+ await _create_workflow(repo, wpid="wpid_c", title="C")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod")
+ await _set_tag(repo, wpid="wpid_b", key="env", value="staging")
+ await _set_tag(repo, wpid="wpid_c", key="team", value="growth")
+
+ assert await _wpids(repo, workflow_tags=[("env", None)]) == {"wpid_a", "wpid_b"}
+
+
+async def test_group_only_excludes_deleted(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_a", title="A")
+ await _set_tag(repo, wpid="wpid_a", key="env", value="prod", deleted_at=datetime.now(timezone.utc))
+
+ assert await _wpids(repo, workflow_tags=[("env", None)]) == set()
+
+
+async def test_and_across_mixed_term_shapes(repo: WorkflowsRepository) -> None:
+ await _create_workflow(repo, wpid="wpid_both", title="Both")
+ await _create_workflow(repo, wpid="wpid_env_only", title="EnvOnly")
+ await _create_workflow(repo, wpid="wpid_label_only", title="LabelOnly")
+ await _set_tag(repo, wpid="wpid_both", key="env", value="prod")
+ await _set_label(repo, wpid="wpid_both", value="urgent")
+ await _set_tag(repo, wpid="wpid_env_only", key="env", value="prod")
+ await _set_label(repo, wpid="wpid_label_only", value="urgent")
+
+ # exact env:prod AND label urgent -> only the workflow carrying both.
+ result = await _wpids(repo, workflow_tags=[("env", "prod"), (None, "urgent")])
+ assert result == {"wpid_both"}
+
+
def _make_org(org_id: str = ORG_ID) -> Organization:
now = datetime.now(timezone.utc)
return Organization(
@@ -282,9 +358,9 @@ def test_route_value_keeps_later_colons(route_client: TestClient) -> None:
@pytest.mark.parametrize(
"tags_params",
[
- [("tags", "envprod")], # no colon
[("tags", ":prod")], # empty key
- [("tags", "env:")], # empty value
+ [("tags", "env:")], # empty value (not the `key:*` group form)
+ [("tags", ":*")], # group wildcard with empty key
[("tags", "env:prod,")], # trailing blank segment (comma form)
[("tags", "env:prod,,customer:acme")], # interior blank segment
[("tags", "env:prod"), ("tags", "")], # blank repeated param (must match comma form -> CORR-3)
@@ -295,6 +371,38 @@ def test_route_malformed_tags_400(route_client: TestClient, tags_params: list[tu
assert resp.status_code == 400, resp.text
+def test_route_value_only_term_parses_as_label(route_client: TestClient) -> None:
+ # A bare token (no colon) is a label / value-only term -> (None, value).
+ resp = route_client.get("/v1/workflows", params=[("tags", "production")])
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] == [(None, "production")] # type: ignore[attr-defined]
+
+
+def test_route_group_wildcard_parses_as_key_only(route_client: TestClient) -> None:
+ # `key:*` is the group-only (any value) term -> (key, None).
+ resp = route_client.get("/v1/workflows", params=[("tags", "env:*")])
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] == [("env", None)] # type: ignore[attr-defined]
+
+
+def test_route_exact_value_ending_in_wildcard_stays_exact(route_client: TestClient) -> None:
+ # Splitting on the first colon keeps an exact value that itself ends in `:*`
+ # (or contains colons) as an exact term, not a group-only wildcard.
+ resp = route_client.get("/v1/workflows", params=[("tags", "url:http://x:*")])
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] == [("url", "http://x:*")] # type: ignore[attr-defined]
+
+
+def test_route_mixed_term_shapes_parse(route_client: TestClient) -> None:
+ resp = route_client.get("/v1/workflows", params=[("tags", "urgent,env:*,team:growth")])
+ assert resp.status_code == 200, resp.text
+ assert route_client.captured["workflow_tags"] == [ # type: ignore[attr-defined]
+ (None, "urgent"),
+ ("env", None),
+ ("team", "growth"),
+ ]
+
+
def test_route_tags_with_template_rejected(route_client: TestClient) -> None:
# Templates are global; tags are org-scoped, so combining them is a 400.
resp = route_client.get("/v1/workflows", params=[("tags", "env:prod"), ("template", "true")])