Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
feat(SKY-11334): accept all 3 tag-filter shapes on analytics summary (BE) (#6786)
Aaron Perez4be2ca4ba459
diff --git a/alembic/versions/2026_06_24_1630-2c76348b4e7a_add_tag_values_table.py b/alembic/versions/2026_06_24_1630-2c76348b4e7a_add_tag_values_table.pynew file mode 100644index 000000000..27c19e1d3--- /dev/null+++ b/alembic/versions/2026_06_24_1630-2c76348b4e7a_add_tag_values_table.py@@ -0,0 +1,54 @@+"""add tag values table++Revision ID: 2c76348b4e7a+Revises: 61c9acf9f3ba+Create Date: 2026-06-24T16:30:09.366617+00:00++"""++from typing import Sequence, Union++import sqlalchemy as sa++from alembic import op++# revision identifiers, used by Alembic.+revision: str = "2c76348b4e7a"+down_revision: Union[str, None] = "61c9acf9f3ba"+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ op.create_table(+ "tag_values",+ sa.Column("tag_value_id", sa.String(), nullable=False),+ sa.Column("organization_id", sa.String(), nullable=False),+ sa.Column("key", sa.String(), nullable=False),+ sa.Column("value", sa.String(), nullable=False),+ sa.Column("color", sa.String(), nullable=False),+ sa.Column("created_at", sa.DateTime(), nullable=False),+ sa.Column("modified_at", sa.DateTime(), nullable=False),+ sa.Column("deleted_at", sa.DateTime(), nullable=True),+ sa.ForeignKeyConstraint(+ ["organization_id"],+ ["organizations.organization_id"],+ ),+ sa.PrimaryKeyConstraint("tag_value_id"),+ )+ op.create_index(+ "ix_tag_values_org_key_value_active",+ "tag_values",+ ["organization_id", "key", "value"],+ unique=True,+ postgresql_where=sa.text("deleted_at IS NULL"),+ )+++def downgrade() -> None:+ op.drop_index(+ "ix_tag_values_org_key_value_active",+ table_name="tag_values",+ postgresql_where=sa.text("deleted_at IS NULL"),+ )+ op.drop_table("tag_values")diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.jsonindex 940372c6e..018ce3d57 100644--- a/docs/api-reference/openapi.json+++ b/docs/api-reference/openapi.json@@ -1567,6 +1567,136 @@"x-fern-sdk-method-name": "delete_tag_key"}},+ "/v1/tag-values": {+ "get": {+ "tags": [+ "Tags"+ ],+ "summary": "List tag values",+ "description": "List the palette color assigned to each grouped tag (key, value) for the organization. The frontend joins these onto tags by (key, value).",+ "operationId": "list_tag_values_v1_tag_values_get",+ "parameters": [+ {+ "name": "x-api-key",+ "in": "header",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",+ "title": "X-Api-Key"+ },+ "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved tag values",+ "content": {+ "application/json": {+ "schema": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/TagValue"+ },+ "title": "Response List Tag Values V1 Tag Values Get"+ }+ }+ }+ },+ "422": {+ "description": "Validation Error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HTTPValidationError"+ }+ }+ }+ }+ },+ "x-fern-sdk-method-name": "list_tag_values"+ }+ },+ "/v1/tag-values/{key}": {+ "patch": {+ "tags": [+ "Tags"+ ],+ "summary": "Update tag value color",+ "description": "Recolor a grouped tag (key, value). The value is supplied in the body so values containing '/' stay addressable. The new color must be a palette name.",+ "operationId": "update_tag_value_v1_tag_values__key__patch",+ "parameters": [+ {+ "name": "key",+ "in": "path",+ "required": true,+ "schema": {+ "type": "string",+ "description": "Tag key (group)",+ "examples": [+ "env"+ ],+ "title": "Key"+ },+ "description": "Tag key (group)"+ },+ {+ "name": "x-api-key",+ "in": "header",+ "required": false,+ "schema": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "null"+ }+ ],+ "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.",+ "title": "X-Api-Key"+ },+ "description": "Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings."+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/TagValueUpdate"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully recolored tag value",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/TagValue"+ }+ }+ }+ },+ "404": {+ "description": "Tag value not found"+ },+ "422": {+ "description": "Invalid palette color"+ }+ },+ "x-fern-sdk-method-name": "update_tag_value"+ }+ },"/v1/workflow-tags": {"get": {"tags": [@@ -18355,6 +18485,21 @@"type": "array","title": "Tags To Delete","description": "Tags to soft-delete. List of {key?, value?} targets."+ },+ "colors": {+ "anyOf": [+ {+ "additionalProperties": {+ "type": "string"+ },+ "type": "object"+ },+ {+ "type": "null"+ }+ ],+ "title": "Colors",+ "description": "Optional map of grouped tag key to palette color name for the value being set. Keys absent from this map keep their existing color or receive a random palette color."}},"type": "object",@@ -18645,6 +18790,51 @@"title": "TagResponse","description": "Current state of one tag (``GET /v1/workflows/{wpid}/tags`` row).\n``key`` is null for a standalone label."},+ "TagValue": {+ "properties": {+ "key": {+ "type": "string",+ "title": "Key"+ },+ "value": {+ "type": "string",+ "title": "Value"+ },+ "color": {+ "type": "string",+ "title": "Color"+ }+ },+ "type": "object",+ "required": [+ "key",+ "value",+ "color"+ ],+ "title": "TagValue",+ "description": "Tag-value color registry entry: the palette color assigned to a grouped\n(key, value) pair."+ },+ "TagValueUpdate": {+ "properties": {+ "value": {+ "type": "string",+ "title": "Value",+ "description": "Tag value (label) under the key to recolor."+ },+ "color": {+ "type": "string",+ "title": "Color",+ "description": "Palette color name to assign to this (key, value)."+ }+ },+ "type": "object",+ "required": [+ "value",+ "color"+ ],+ "title": "TagValueUpdate",+ "description": "Body for ``PATCH /v1/tag-values/{key}``. The value rides in the body, not the\npath, so values containing ``/`` stay addressable."+ },"TagsResponse": {"properties": {"workflow_permanent_id": {diff --git a/skyvern/forge/sdk/db/id.py b/skyvern/forge/sdk/db/id.pyindex b1156cce2..2e7a33b31 100644--- a/skyvern/forge/sdk/db/id.py+++ b/skyvern/forge/sdk/db/id.py@@ -79,6 +79,7 @@ SCRIPT_FALLBACK_EPISODE_PREFIX = "sfe"WORKFLOW_SCHEDULE_PREFIX = "wfs"TAG_EVENT_PREFIX = "tge"TAG_KEY_PREFIX = "tkey"+TAG_VALUE_PREFIX = "tval"def generate_workflow_id() -> str:@@ -266,6 +267,11 @@ def generate_tag_key_id() -> str:return f"{TAG_KEY_PREFIX}_{int_id}"+def generate_tag_value_id() -> str:+ int_id = generate_id()+ return f"{TAG_VALUE_PREFIX}_{int_id}"++def generate_google_oauth_credential_id() -> str:int_id = generate_id()return f"{GOOGLE_OAUTH_CREDENTIAL_PREFIX}_{int_id}"diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.pyindex 0e8a44317..447beb47f 100644--- a/skyvern/forge/sdk/db/models.py+++ b/skyvern/forge/sdk/db/models.py@@ -54,6 +54,7 @@ from skyvern.forge.sdk.db.id import (generate_step_id,generate_tag_event_id,generate_tag_key_id,+ generate_tag_value_id,generate_task_generation_id,generate_task_id,generate_task_run_id,@@ -447,6 +448,40 @@ class TagKeyModel(Base):deleted_at = Column(DateTime, nullable=True)+class TagValueModel(Base):+ """Org-scoped registry of the color for each grouped tag ``(key, value)``, auto-registered+ on first SET (random palette unless supplied). Partial-UNIQUE on (org, key, value)+ WHERE deleted_at IS NULL mirrors TagKeyModel; standalone labels (no key) are not colored."""++ __tablename__ = "tag_values"+ __table_args__ = (+ Index(+ "ix_tag_values_org_key_value_active",+ "organization_id",+ "key",+ "value",+ unique=True,+ postgresql_where=text("deleted_at IS NULL"),+ sqlite_where=text("deleted_at IS NULL"),+ ),+ )++ tag_value_id = Column(String, primary_key=True, default=generate_tag_value_id)+ organization_id = Column(String, ForeignKey("organizations.organization_id"), nullable=False)+ key = Column(String, nullable=False)+ value = Column(String, nullable=False)+ color = Column(String, nullable=False)++ created_at = Column(DateTime, default=datetime.datetime.utcnow, nullable=False)+ modified_at = Column(+ DateTime,+ default=datetime.datetime.utcnow,+ onupdate=datetime.datetime.utcnow,+ nullable=False,+ )+ deleted_at = Column(DateTime, nullable=True)++# TODO: ~22 other models with manual deleted_at columns could inherit SoftDeleteMixin.# WorkflowModel is the proof of concept; remaining models will be migrated in a follow-up PR.class WorkflowModel(SoftDeleteMixin, Base):diff --git a/skyvern/forge/sdk/db/repositories/tags.py b/skyvern/forge/sdk/db/repositories/tags.pyindex a0077227e..71cd49f8d 100644--- a/skyvern/forge/sdk/db/repositories/tags.py+++ b/skyvern/forge/sdk/db/repositories/tags.py@@ -6,15 +6,15 @@ from dataclasses import dataclassfrom datetime import datetime, timezoneimport structlog-from sqlalchemy import and_, func, select, text+from sqlalchemy import and_, func, select, text, updatefrom sqlalchemy.dialects import postgresql, sqlitefrom sqlalchemy.ext.asyncio import AsyncSessionfrom skyvern.forge.sdk.db._error_handling import db_operation, register_passthrough_exceptionfrom skyvern.forge.sdk.db.base_repository import BaseRepository-from skyvern.forge.sdk.db.models import TagKeyModel, WorkflowTagEventModel+from skyvern.forge.sdk.db.models import TagKeyModel, TagValueModel, WorkflowTagEventModelfrom skyvern.forge.sdk.workflow.models.tags import TagEventType, TagWriteContext-from skyvern.forge.sdk.workflow.models.validators import RUN_METADATA_MAX_KEYS+from skyvern.forge.sdk.workflow.models.validators import RUN_METADATA_MAX_KEYS, random_tag_colorLOG = structlog.get_logger()@@ -54,11 +54,15 @@ class TagsRepository(BaseRepository):context: TagWriteContext,label_sets: list[str] | None = None,label_deletes: list[str] | None = None,+ colors: dict[str, str] | None = None,) -> list[TagChange]:"""Atomically apply SET/DELETE tag events. Grouped tags via ``sets``/``deletes``- (keys), standalone labels via ``label_sets``/``label_deletes``; set wins over delete."""+ (keys), standalone labels via ``label_sets``/``label_deletes``; set wins over delete.+ ``colors`` maps a grouped tag's key to a palette color for the value being set;+ a SET key absent from ``colors`` keeps its existing color or gets a random one."""label_sets = label_sets or []label_deletes = label_deletes or []+ colors = colors or {}label_set_values = set(label_sets)effective_deletes = {k for k in deletes if k not in sets}effective_label_deletes = {v for v in label_deletes if v not in label_set_values}@@ -186,9 +190,68 @@ class TagsRepository(BaseRepository):)await session.execute(insert_stmt)+ await self._register_tag_value_colors(+ session,+ organization_id=organization_id,+ sets=sets,+ colors=colors,+ now=now,+ )+await session.commit()return changes+ async def _register_tag_value_colors(+ self,+ session: AsyncSession,+ *,+ organization_id: str,+ sets: dict[str, str],+ colors: dict[str, str],+ now: datetime,+ ) -> None:+ """Upsert a color for every grouped (key, value) in this SET request, even when the+ tag event is idempotent: an explicit color overrides (DO UPDATE), an unspecified one+ registers only on first use (DO NOTHING keeps the existing). Standalone labels are skipped."""+ if not sets:+ return++ dialect_name = session.bind.dialect.name if session.bind is not None else "postgresql"+ insert = sqlite.insert if dialect_name == "sqlite" else postgresql.insert++ explicit_rows: list[dict[str, str]] = []+ random_rows: list[dict[str, str]] = []+ for key, value in sets.items():+ provided = colors.get(key)+ if provided is not None:+ explicit_rows.append(+ {"organization_id": organization_id, "key": key, "value": value, "color": provided}+ )+ else:+ random_rows.append(+ {"organization_id": organization_id, "key": key, "value": value, "color": random_tag_color()}+ )++ if explicit_rows:+ stmt = insert(TagValueModel.__table__).values(explicit_rows)+ stmt = stmt.on_conflict_do_update(+ index_elements=["organization_id", "key", "value"],+ index_where=text("deleted_at IS NULL"),+ set_={"color": stmt.excluded.color, "modified_at": now},+ )+ await session.execute(stmt)++ if random_rows:+ stmt = (+ insert(TagValueModel.__table__)+ .values(random_rows)+ .on_conflict_do_nothing(+ index_elements=["organization_id", "key", "value"],+ index_where=text("deleted_at IS NULL"),+ )+ )+ await session.execute(stmt)+async def _get_active_set_rows(self,session: AsyncSession,@@ -335,6 +398,47 @@ class TagsRepository(BaseRepository):result = await session.execute(stmt)return list(result.scalars().all())+ @db_operation("list_tag_values")+ async def list_tag_values(self, organization_id: str) -> list[TagValueModel]:+ """Active (key, value, color) registry entries for the org, ordered by key+ then value. The frontend joins these onto tags by (key, value) the same way+ it joins descriptions onto keys."""+ async with self.Session() as session:+ stmt = (+ select(TagValueModel)+ .where(TagValueModel.organization_id == organization_id)+ .where(TagValueModel.deleted_at.is_(None))+ .order_by(TagValueModel.key.asc(), TagValueModel.value.asc())+ )+ result = await session.execute(stmt)+ return list(result.scalars().all())++ @db_operation("recolor_tag_value")+ async def recolor_tag_value(+ self,+ organization_id: str,+ key: str,+ value: str,+ color: str,+ ) -> TagValueModel | None:+ """Recolor an existing (key, value) registry row. Returns None when the pair+ is not registered for the org (caller should 404)."""+ async with self.Session() as session:+ stmt = (+ select(TagValueModel)+ .where(TagValueModel.organization_id == organization_id)+ .where(TagValueModel.key == key)+ .where(TagValueModel.value == value)+ .where(TagValueModel.deleted_at.is_(None))+ )+ row = (await session.execute(stmt)).scalar_one_or_none()+ if row is None:+ return None+ row.color = color+ await session.commit()+ await session.refresh(row)+ return row+@db_operation("get_tag_key")async def get_tag_key(self, organization_id: str, key: str) -> TagKeyModel | None:async with self.Session() as session:@@ -399,7 +503,8 @@ class TagsRepository(BaseRepository):context: TagWriteContext,) -> int | None:"""Cascade-delete a tag key: write a DELETE event for every workflow that- currently has it, then soft-delete the registry row. Returns the number+ currently has it, then soft-delete the key registry row and its value color+ rows (so GET /tag-values stops returning colors for the removed key). Returns the numberof workflows the tag was removed from, or None when the key is notregistered (caller should 404). Idempotent: a second call returns None.@@ -472,5 +577,14 @@ class TagsRepository(BaseRepository):)key_row.deleted_at = now+ await session.execute(+ update(TagValueModel)+ .where(+ TagValueModel.organization_id == organization_id,+ TagValueModel.key == key,+ TagValueModel.deleted_at.is_(None),+ )+ .values(deleted_at=now)+ )await session.commit()return len(active_sets)diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.pyindex 6fa3fe899..e061290ca 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, timezonefrom typing import Any, castimport structlog-from sqlalchemy import Select, exists, func, or_, select, update+from sqlalchemy import exists, func, or_, select, updatefrom skyvern.constants import DEFAULT_SCRIPT_RUN_IDfrom skyvern.forge.sdk.db._error_handling import db_operation@@ -27,14 +27,13 @@ from skyvern.forge.sdk.db.models import (WorkflowParameterModel,WorkflowRunModel,WorkflowScheduleModel,- WorkflowTagEventModel,WorkflowTemplateModel,)from skyvern.forge.sdk.db.repositories.workflow_parameters import WorkflowParametersRepository+from skyvern.forge.sdk.db.tag_filters import workflow_tag_wpid_subqueriesfrom skyvern.forge.sdk.db.utils import convert_to_workflow, nullable_column_equals, serialize_proxy_locationfrom skyvern.forge.sdk.workflow.models.block import Block, ForLoopBlock, WhileLoopBlockfrom skyvern.forge.sdk.workflow.models.parameter import OutputParameter-from skyvern.forge.sdk.workflow.models.tags import TagEventTypefrom skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinitionfrom skyvern.schemas.runs import ProxyLocationInputfrom skyvern.schemas.workflows import WorkflowStatus@@ -486,47 +485,8 @@ class WorkflowsRepository(BaseRepository):if folder_id:main_query = main_query.where(WorkflowModel.folder_id == folder_id)if workflow_tags:- exact_values_by_key: dict[str, list[str]] = {}- key_only_terms: list[str] = []- value_only_terms: list[str] = []- for key, value in workflow_tags:- 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_(- _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)- )- )+ for subquery in workflow_tag_wpid_subqueries(workflow_tags, organization_id):+ main_query = main_query.where(WorkflowModel.workflow_permanent_id.in_(subquery))if search_key:search_like = f"%{search_key}%"title_like = WorkflowModel.title.ilike(search_like)diff --git a/skyvern/forge/sdk/db/tag_filters.py b/skyvern/forge/sdk/db/tag_filters.pynew file mode 100644index 000000000..c313d221d--- /dev/null+++ b/skyvern/forge/sdk/db/tag_filters.py@@ -0,0 +1,58 @@+from typing import Any++from sqlalchemy import and_, select+from sqlalchemy.sql.elements import ColumnElement++from skyvern.forge.sdk.db.models import WorkflowTagEventModel+from skyvern.forge.sdk.workflow.models.tags import TagEventType+++def workflow_tag_wpid_subqueries(+ workflow_tag_filter: list[tuple[str | None, str | None]] | None,+ organization_id: str | None = None,+) -> list[Any]:+ """One scalar ``workflow_permanent_id`` subquery per term from ``WorkflowTagEventModel``.++ Shared by the analytics summary filter and the workflows-list filter: exact ``(key, value)``+ (OR within a key), group-only ``(key, None)``, and label-only ``(None, value)``, AND-ed across+ distinct terms. Shape semantics are exercised in ``tests/unit/test_workflows_list_tag_filter.py``+ and ``tests/cloud/test_analytics_workflow_tag_filter.py``."""+ if not workflow_tag_filter:+ return []++ exact_values_by_key: dict[str, list[str]] = {}+ key_only_terms: list[str] = []+ value_only_terms: list[str] = []+ for key, value in workflow_tag_filter:+ 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 _base_filters() -> list[ColumnElement[bool]]:+ filters: list[ColumnElement[bool]] = [+ WorkflowTagEventModel.deleted_at.is_(None),+ WorkflowTagEventModel.superseded_at.is_(None),+ WorkflowTagEventModel.event_type == TagEventType.SET.value,+ ]+ if organization_id is not None:+ filters.append(WorkflowTagEventModel.organization_id == organization_id)+ return filters++ def _subquery(*term_filters: ColumnElement[bool]) -> Any:+ return (+ select(WorkflowTagEventModel.workflow_permanent_id)+ .where(and_(*_base_filters(), *term_filters))+ .scalar_subquery()+ )++ subqueries: list[Any] = []+ for key, values in exact_values_by_key.items():+ subqueries.append(_subquery(WorkflowTagEventModel.key == key, WorkflowTagEventModel.value.in_(values)))+ for key in key_only_terms:+ subqueries.append(_subquery(WorkflowTagEventModel.key == key))+ for value in value_only_terms:+ subqueries.append(_subquery(WorkflowTagEventModel.value == value))+ return subqueriesdiff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.pyindex be29a4cc1..b21e02d42 100644--- a/skyvern/forge/sdk/routes/agent_protocol.py+++ b/skyvern/forge/sdk/routes/agent_protocol.py@@ -154,6 +154,8 @@ from skyvern.schemas.tags import (TagKeyUpdate,TagResponse,TagsResponse,+ TagValue,+ TagValueUpdate,WorkflowTagsBatchRequest,WorkflowTagsBatchResponse,_assert_user_key_writable,@@ -1566,6 +1568,7 @@ async def _apply_tag_changes_with_retry(context: TagWriteContext,label_sets: list[str] | None = None,label_deletes: list[str] | None = None,+ colors: dict[str, str] | None = None,) -> None:"""Wrap ``apply_tag_changes`` with one IntegrityError retry: concurrentsame-identity SETs race the partial UNIQUE; last-write-wins, else 409."""@@ -1579,6 +1582,7 @@ async def _apply_tag_changes_with_retry(context=context,label_sets=label_sets,label_deletes=label_deletes,+ colors=colors,)returnexcept IntegrityError:@@ -1655,6 +1659,7 @@ async def apply_workflow_tags(context=write_ctx,label_sets=label_sets,label_deletes=label_deletes,+ colors=data.colors,)except ValueError as e:# Cap-breach is the only ValueError surfaced; treat as 422 (user input).@@ -1903,6 +1908,67 @@ async def delete_tag_key(return TagKeyDeleteResponse(key=key, removed_from_workflow_count=removed_count)+@legacy_base_router.get("/tag-values", response_model=list[TagValue], tags=["agent"], include_in_schema=False)+@legacy_base_router.get("/tag-values/", response_model=list[TagValue], include_in_schema=False)+@base_router.get(+ "/tag-values",+ response_model=list[TagValue],+ tags=["Tags"],+ openapi_extra={"x-fern-sdk-method-name": "list_tag_values"},+ description="List the palette color assigned to each grouped tag (key, value) for the organization. "+ "The frontend joins these onto tags by (key, value).",+ summary="List tag values",+ responses={200: {"description": "Successfully retrieved tag values"}},+)+@base_router.get("/tag-values/", response_model=list[TagValue], include_in_schema=False)+async def list_tag_values(+ current_org: Organization = Depends(org_auth_service.get_current_org),+ _tagging_gate: None = Depends(require_workflow_tagging),+) -> list[TagValue]:+ organization_id = current_org.organization_id+ rows = await app.DATABASE.tags.list_tag_values(organization_id=organization_id)+ return [TagValue(key=row.key, value=row.value, color=row.color) for row in rows]+++@legacy_base_router.patch("/tag-values/{key}", response_model=TagValue, tags=["agent"], include_in_schema=False)+@legacy_base_router.patch("/tag-values/{key}/", response_model=TagValue, include_in_schema=False)+@base_router.patch(+ "/tag-values/{key}",+ response_model=TagValue,+ tags=["Tags"],+ openapi_extra={"x-fern-sdk-method-name": "update_tag_value"},+ description="Recolor a grouped tag (key, value). The value is supplied in the body so values "+ "containing '/' stay addressable. The new color must be a palette name.",+ summary="Update tag value color",+ responses={+ 200: {"description": "Successfully recolored tag value"},+ 404: {"description": "Tag value not found"},+ 422: {"description": "Invalid palette color"},+ },+)+@base_router.patch("/tag-values/{key}/", response_model=TagValue, include_in_schema=False)+async def update_tag_value(+ key: str = Path(..., description="Tag key (group)", examples=["env"]),+ data: TagValueUpdate = Body(...),+ current_org: Organization = Depends(org_auth_service.get_current_org),+ _tagging_gate: None = Depends(require_workflow_tagging),+) -> TagValue:+ _validate_path_key(key)+ organization_id = current_org.organization_id+ row = await app.DATABASE.tags.recolor_tag_value(+ organization_id=organization_id,+ key=key,+ value=data.value,+ color=data.color,+ )+ if row is None:+ raise HTTPException(+ status_code=http_status.HTTP_404_NOT_FOUND,+ detail=f"Tag value '{key}:{data.value}' not found",+ )+ return TagValue(key=row.key, value=row.value, color=row.color)++# Keep in sync with BATCH_TAGS_MAX_WPIDS in the frontend# useWorkflowTagsBatchQuery hook, which chunks requests to this size._BATCH_TAGS_MAX_WPIDS = 200diff --git a/skyvern/forge/sdk/workflow/models/validators.py b/skyvern/forge/sdk/workflow/models/validators.pyindex 74c987ecc..c75967d4c 100644--- a/skyvern/forge/sdk/workflow/models/validators.py+++ b/skyvern/forge/sdk/workflow/models/validators.py@@ -1,3 +1,4 @@+import randomimport reimport structlog@@ -143,6 +144,44 @@ def normalize_optional_tag_value(value: object) -> str | None:return normalize_tag_value(value)+# Curated, semantic color names (not freeform hex) so the frontend can guarantee+# legible light/dark renderings by mapping each name to a vetted pair. This list is+# the server-side source of truth; the frontend mirrors it. Order is the random-pick+# pool — keep it stable so colors don't churn across deploys.+TAG_COLOR_PALETTE: tuple[str, ...] = (+ "gray",+ "red",+ "orange",+ "amber",+ "yellow",+ "green",+ "teal",+ "blue",+ "cyan",+ "indigo",+ "purple",+ "pink",+)+_TAG_COLOR_PALETTE_SET = frozenset(TAG_COLOR_PALETTE)+++def normalize_tag_color(color: object) -> str:+ """Validate a palette color name against the curated palette. Trims and+ lowercases; raises ValueError for anything outside the palette so freeform+ hex / arbitrary names can't bypass the legible light/dark guarantee."""+ if not isinstance(color, str):+ raise ValueError("tag color must be a string")+ normalized = color.strip().lower()+ if normalized not in _TAG_COLOR_PALETTE_SET:+ raise ValueError(f"tag color must be one of: {', '.join(TAG_COLOR_PALETTE)}")+ return normalized+++def random_tag_color() -> str:+ """Pick a palette color for a newly registered (key, value) with no explicit color."""+ return random.choice(TAG_COLOR_PALETTE)++def normalize_tag_description(v: str | None) -> str | None:"""Trim and length-bound a tag-key description; return None when empty."""if v is None:diff --git a/skyvern/schemas/tags.py b/skyvern/schemas/tags.pyindex 7ef54dbd1..853143c5b 100644--- a/skyvern/schemas/tags.py+++ b/skyvern/schemas/tags.py@@ -13,6 +13,7 @@ from skyvern.forge.sdk.workflow.models.validators import (TAG_KEY_REGEX,normalize_optional_tag_key,normalize_optional_tag_value,+ normalize_tag_color,normalize_tag_description,normalize_tag_value,)@@ -101,6 +102,28 @@ class TagApplyRequest(BaseModel):default_factory=list,description="Tags to soft-delete. List of {key?, value?} targets.",)+ colors: dict[str, str] | None = Field(+ default=None,+ description="Optional map of grouped tag key to palette color name for the value being set. "+ "Keys absent from this map keep their existing color or receive a random palette color.",+ )++ @field_validator("colors", mode="before")+ @classmethod+ def _normalize_colors(cls, v: object) -> dict[str, str] | None:+ if v is None:+ return None+ if not isinstance(v, dict):+ raise ValueError("colors must be a JSON object mapping a tag key to a palette color")+ if len(v) > RUN_METADATA_MAX_KEYS:+ raise ValueError(f"colors can include at most {RUN_METADATA_MAX_KEYS} entries")+ normalized: dict[str, str] = {}+ for key, color in v.items():+ normalized_key = normalize_optional_tag_key(key)+ if normalized_key is None:+ raise ValueError("colors keys must be non-empty tag keys")+ normalized[normalized_key] = normalize_tag_color(color)+ return normalized@field_validator("tags", mode="before")@classmethod@@ -205,6 +228,35 @@ class TagKeyUpdate(BaseModel):return normalize_tag_description(v)+class TagValue(BaseModel):+ """Tag-value color registry entry: the palette color assigned to a grouped+ (key, value) pair."""++ model_config = ConfigDict(from_attributes=True)++ key: str+ value: str+ color: str+++class TagValueUpdate(BaseModel):+ """Body for ``PATCH /v1/tag-values/{key}``. The value rides in the body, not the+ path, so values containing ``/`` stay addressable."""++ value: str = Field(description="Tag value (label) under the key to recolor.")+ color: str = Field(description="Palette color name to assign to this (key, value).")++ @field_validator("value", mode="before")+ @classmethod+ def _normalize_value(cls, v: object) -> str:+ return normalize_tag_value(v)++ @field_validator("color", mode="before")+ @classmethod+ def _normalize_color(cls, v: object) -> str:+ return normalize_tag_color(v)++class WorkflowTagsBatchRequest(BaseModel):"""Body for ``POST /v1/workflow-tags`` (used when the wpid list wouldexceed the URL length cap)."""diff --git a/tests/unit/test_tag_endpoints.py b/tests/unit/test_tag_endpoints.pyindex a6b1eea06..102bbad1c 100644--- a/tests/unit/test_tag_endpoints.py+++ b/tests/unit/test_tag_endpoints.py@@ -665,3 +665,106 @@ def test_post_succeeds_when_first_integrity_error_then_succeeds(app_with_routes:resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})assert resp.status_code == 200assert attempts["n"] == 2+++# ----------------------------- GET /tag-values -------------------------------------+++def test_get_tag_values_reflects_applied_colors(client: TestClient) -> None:+ resp = client.post(+ f"/v1/workflows/{WPID}/tags",+ json={+ "tags": [{"key": "env", "value": "prod"}, {"key": "team", "value": "growth"}],+ "colors": {"env": "blue", "team": "purple"},+ },+ )+ assert resp.status_code == 200, resp.text++ values = client.get("/v1/tag-values").json()+ by_pair = {(row["key"], row["value"]): row["color"] for row in values}+ assert by_pair == {("env", "prod"): "blue", ("team", "growth"): "purple"}+++def test_get_tag_values_assigns_random_palette_color_when_unset(client: TestClient) -> None:+ from skyvern.forge.sdk.workflow.models.validators import TAG_COLOR_PALETTE++ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"key": "env", "value": "prod"}]})++ values = client.get("/v1/tag-values").json()+ assert len(values) == 1+ assert values[0]["color"] in TAG_COLOR_PALETTE+++def test_get_tag_values_excludes_standalone_labels(client: TestClient) -> None:+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": [{"value": "urgent"}]})+ assert client.get("/v1/tag-values").json() == []+++def test_get_tag_values_legacy_route_works(client: TestClient) -> None:+ client.post(+ f"/v1/workflows/{WPID}/tags",+ json={"tags": [{"key": "env", "value": "prod"}], "colors": {"env": "green"}},+ )+ resp = client.get("/api/v1/tag-values")+ assert resp.status_code == 200+ assert resp.json()[0]["color"] == "green"+++def test_post_tags_invalid_color_returns_422(client: TestClient) -> None:+ resp = client.post(+ f"/v1/workflows/{WPID}/tags",+ json={"tags": [{"key": "env", "value": "prod"}], "colors": {"env": "#ff0000"}},+ )+ assert resp.status_code == 422+++def test_post_tags_color_is_case_insensitive(client: TestClient) -> None:+ resp = client.post(+ f"/v1/workflows/{WPID}/tags",+ json={"tags": [{"key": "env", "value": "prod"}], "colors": {"env": "BLUE"}},+ )+ assert resp.status_code == 200, resp.text+ assert client.get("/v1/tag-values").json()[0]["color"] == "blue"+++# ----------------------------- PATCH /tag-values/{key} -----------------------------+++def test_patch_tag_value_recolors(client: TestClient) -> None:+ client.post(+ f"/v1/workflows/{WPID}/tags",+ json={"tags": [{"key": "env", "value": "prod"}], "colors": {"env": "blue"}},+ )+ resp = client.patch("/v1/tag-values/env", json={"value": "prod", "color": "pink"})+ assert resp.status_code == 200, resp.text+ assert resp.json() == {"key": "env", "value": "prod", "color": "pink"}+ assert client.get("/v1/tag-values").json()[0]["color"] == "pink"+++def test_patch_tag_value_recolors_value_containing_slash(client: TestClient) -> None:+ client.post(+ f"/v1/workflows/{WPID}/tags",+ json={"tags": [{"key": "region", "value": "us/west"}], "colors": {"region": "blue"}},+ )+ resp = client.patch("/v1/tag-values/region", json={"value": "us/west", "color": "pink"})+ assert resp.status_code == 200, resp.text+ assert resp.json() == {"key": "region", "value": "us/west", "color": "pink"}+++def test_patch_tag_value_404_when_absent(client: TestClient) -> None:+ resp = client.patch("/v1/tag-values/env", json={"value": "prod", "color": "pink"})+ assert resp.status_code == 404+++def test_patch_tag_value_invalid_color_returns_422(client: TestClient) -> None:+ client.post(+ f"/v1/workflows/{WPID}/tags",+ json={"tags": [{"key": "env", "value": "prod"}], "colors": {"env": "blue"}},+ )+ resp = client.patch("/v1/tag-values/env", json={"value": "prod", "color": "chartreuse"})+ assert resp.status_code == 422+++def test_patch_tag_value_reserved_prefix_returns_400(client: TestClient) -> None:+ resp = client.patch("/v1/tag-values/skyvern.system", json={"value": "prod", "color": "blue"})+ assert resp.status_code == 400diff --git a/tests/unit/test_tag_filters.py b/tests/unit/test_tag_filters.pynew file mode 100644index 000000000..abd317573--- /dev/null+++ b/tests/unit/test_tag_filters.py@@ -0,0 +1,16 @@+from skyvern.forge.sdk.db.tag_filters import workflow_tag_wpid_subqueries+++def test_workflow_tag_wpid_subqueries_empty() -> None:+ assert workflow_tag_wpid_subqueries(None) == []+ assert workflow_tag_wpid_subqueries([]) == []+++def test_workflow_tag_wpid_subqueries_one_per_term_group() -> None:+ # Two exact terms under "env" collapse (OR within key) -> 1; group-only and+ # label-only each add 1 -> 3 subqueries AND-ed by the caller.+ subqueries = workflow_tag_wpid_subqueries(+ [("env", "prod"), ("env", "staging"), ("team", None), (None, "urgent")],+ organization_id="o_123",+ )+ assert len(subqueries) == 3diff --git a/tests/unit/test_tags_repository.py b/tests/unit/test_tags_repository.pyindex 452e3053f..c41f78284 100644--- a/tests/unit/test_tags_repository.py+++ b/tests/unit/test_tags_repository.py@@ -13,6 +13,7 @@ from skyvern.forge.sdk.db.base_alchemy_db import BaseAlchemyDBfrom skyvern.forge.sdk.db.models import (Base,TagKeyModel,+ TagValueModel,WorkflowTagEventModel,)from skyvern.forge.sdk.db.repositories.tags import (@@ -26,6 +27,7 @@ from skyvern.forge.sdk.workflow.models.tags import (TagSource,TagWriteContext,)+from skyvern.forge.sdk.workflow.models.validators import TAG_COLOR_PALETTEORG_ID = "o_test"WPID = "wpid_alpha"@@ -662,3 +664,149 @@ async def test_batch_includes_standalone_labels(repo: TagsRepository) -> None:)result = await repo.get_active_tags_for_workflows([WPID], ORG_ID)assert set(result[WPID]) == {("env", "prod"), (None, "urgent")}+++async def _tag_value_rows(repo: TagsRepository) -> list[TagValueModel]:+ async with repo.Session() as session:+ result = await session.execute(+ select(TagValueModel)+ .where(TagValueModel.deleted_at.is_(None))+ .order_by(TagValueModel.key, TagValueModel.value)+ )+ return list(result.scalars().all())+++async def test_set_without_color_registers_random_palette_color(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())++ rows = await _tag_value_rows(repo)+ assert len(rows) == 1+ assert (rows[0].key, rows[0].value) == ("env", "prod")+ assert rows[0].color in TAG_COLOR_PALETTE+++async def test_set_with_color_persists_provided_color(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )++ rows = await _tag_value_rows(repo)+ assert len(rows) == 1+ assert rows[0].color == "blue"+++async def test_tag_value_color_is_idempotent_without_color(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "teal"}+ )+ # Re-SET the same (key, value) with no color: the existing color must be kept,+ # and no duplicate registry row may appear under the partial unique.+ await repo.apply_tag_changes("wpid_other", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())++ rows = await _tag_value_rows(repo)+ assert len(rows) == 1+ assert rows[0].color == "teal"+++async def test_tag_value_color_override_updates_existing(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )+ await repo.apply_tag_changes(+ "wpid_other", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "green"}+ )++ rows = await _tag_value_rows(repo)+ assert len(rows) == 1+ assert rows[0].color == "green"+++async def test_color_override_applies_on_idempotent_set(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )+ # Re-SET the same (key, value) on the same workflow: an idempotent tag op that emits no+ # tag event must still apply the new color override to the registry row.+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "green"}+ )++ rows = await _tag_value_rows(repo)+ assert len(rows) == 1+ assert rows[0].color == "green"+++async def test_distinct_values_under_same_key_get_distinct_color_rows(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "stg"}, deletes=set(), context=_ctx(), colors={"env": "red"}+ )++ rows = await _tag_value_rows(repo)+ assert {(r.value, r.color) for r in rows} == {("prod", "blue"), ("stg", "red")}+++async def test_standalone_labels_are_not_colored(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(WPID, ORG_ID, sets={}, deletes=set(), context=_ctx(), label_sets=["urgent"])+ assert await _tag_value_rows(repo) == []+++async def test_list_tag_values_returns_active_rows_ordered(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID,+ ORG_ID,+ sets={"team": "core", "env": "prod"},+ deletes=set(),+ context=_ctx(),+ colors={"team": "purple", "env": "blue"},+ )++ values = await repo.list_tag_values(ORG_ID)+ assert [(v.key, v.value, v.color) for v in values] == [("env", "prod", "blue"), ("team", "core", "purple")]+++async def test_list_tag_values_is_org_scoped(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )+ assert await repo.list_tag_values("o_someone_else") == []+++async def test_recolor_tag_value_updates_color(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )++ updated = await repo.recolor_tag_value(ORG_ID, "env", "prod", "pink")+ assert updated is not None+ assert updated.color == "pink"+ assert [v.color for v in await repo.list_tag_values(ORG_ID)] == ["pink"]+++async def test_recolor_tag_value_returns_none_when_absent(repo: TagsRepository) -> None:+ assert await repo.recolor_tag_value(ORG_ID, "env", "prod", "pink") is None+++async def test_delete_tag_key_soft_deletes_value_colors(repo: TagsRepository) -> None:+ await repo.apply_tag_changes(+ WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx(), colors={"env": "blue"}+ )+ assert len(await repo.list_tag_values(ORG_ID)) == 1++ await repo.delete_tag_key(ORG_ID, "env", _ctx())+ # The key's color rows must not survive the key delete and keep showing in GET /tag-values.+ assert await repo.list_tag_values(ORG_ID) == []