Skip to content

Automate browser based workflows with AI

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.py
new file mode 100644
index 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.json
index 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.py
index 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.py
index 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.py
index 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 dataclass
from datetime import datetime, timezone
import structlog
-from sqlalchemy import and_, func, select, text
+from sqlalchemy import and_, func, select, text, update
from sqlalchemy.dialects import postgresql, sqlite
from sqlalchemy.ext.asyncio import AsyncSession
from skyvern.forge.sdk.db._error_handling import db_operation, register_passthrough_exception
from 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, WorkflowTagEventModel
from 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_color
LOG = 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 number
of workflows the tag was removed from, or None when the key is not
registered (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.py
index 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, timezone
from typing import Any, cast
import structlog
-from sqlalchemy import Select, exists, func, or_, select, update
+from sqlalchemy import exists, func, or_, select, update
from skyvern.constants import DEFAULT_SCRIPT_RUN_ID
from 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_subqueries
from skyvern.forge.sdk.db.utils import convert_to_workflow, nullable_column_equals, serialize_proxy_location
from skyvern.forge.sdk.workflow.models.block import Block, ForLoopBlock, WhileLoopBlock
from skyvern.forge.sdk.workflow.models.parameter import OutputParameter
-from skyvern.forge.sdk.workflow.models.tags import TagEventType
from skyvern.forge.sdk.workflow.models.workflow import Workflow, WorkflowDefinition
from skyvern.schemas.runs import ProxyLocationInput
from 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.py
new file mode 100644
index 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 subqueries
diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.py
index 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: concurrent
same-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,
)
return
except 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 = 200
diff --git a/skyvern/forge/sdk/workflow/models/validators.py b/skyvern/forge/sdk/workflow/models/validators.py
index 74c987ecc..c75967d4c 100644
--- a/skyvern/forge/sdk/workflow/models/validators.py
+++ b/skyvern/forge/sdk/workflow/models/validators.py
@@ -1,3 +1,4 @@
+import random
import re
import 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.py
index 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 would
exceed the URL length cap)."""
diff --git a/tests/unit/test_tag_endpoints.py b/tests/unit/test_tag_endpoints.py
index 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 == 200
assert 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 == 400
diff --git a/tests/unit/test_tag_filters.py b/tests/unit/test_tag_filters.py
new file mode 100644
index 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) == 3
diff --git a/tests/unit/test_tags_repository.py b/tests/unit/test_tags_repository.py
index 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 BaseAlchemyDB
from 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_PALETTE
ORG_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) == []