Skip to content

Automate browser based workflows with AI

[SKY-10102] Phase 3: Tag CRUD + history + tag-keys + batch endpoints (#6251)

Trevor Cheungc09b19178cbb
diff --git a/skyvern/forge/sdk/db/models.py b/skyvern/forge/sdk/db/models.py
index 9356dc75c..c86c318ce 100644
--- a/skyvern/forge/sdk/db/models.py
+++ b/skyvern/forge/sdk/db/models.py
@@ -350,6 +350,7 @@ class WorkflowTagEventModel(Base):
"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'"),
),
CheckConstraint("event_type IN ('set', 'delete')", name="ck_workflow_tag_events_event_type"),
CheckConstraint(
@@ -398,6 +399,7 @@ class TagKeyModel(Base):
"key",
unique=True,
postgresql_where=text("deleted_at IS NULL"),
+ sqlite_where=text("deleted_at IS NULL"),
),
)
diff --git a/skyvern/forge/sdk/db/repositories/tags.py b/skyvern/forge/sdk/db/repositories/tags.py
index 94849ef96..b5fa176c2 100644
--- a/skyvern/forge/sdk/db/repositories/tags.py
+++ b/skyvern/forge/sdk/db/repositories/tags.py
@@ -6,7 +6,8 @@ from dataclasses import dataclass
from datetime import datetime, timezone
import structlog
-from sqlalchemy import and_, select
+from sqlalchemy import and_, select, text
+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
@@ -137,20 +138,27 @@ class TagsRepository(BaseRepository):
await session.flush()
# Auto-register TagKeyModel rows only for keys whose SET actually
- # wrote a new event — idempotent no-op SETs don't need to re-touch
- # the registry. Partial UNIQUE on (org, key) WHERE deleted_at IS
- # NULL races concurrent first-use writers; the loser surfaces
- # IntegrityError to the caller.
+ # 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}
if changed_set_keys:
- existing_keys_stmt = select(TagKeyModel.key).where(
- TagKeyModel.organization_id == organization_id,
- TagKeyModel.key.in_(changed_set_keys),
- TagKeyModel.deleted_at.is_(None),
+ 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"
+ insert = sqlite.insert if dialect_name == "sqlite" else postgresql.insert
+ insert_stmt = (
+ insert(TagKeyModel.__table__)
+ .values(rows)
+ .on_conflict_do_nothing(
+ index_elements=["organization_id", "key"],
+ index_where=text("deleted_at IS NULL"),
+ )
)
- existing_keys = set((await session.execute(existing_keys_stmt)).scalars().all())
- for key in changed_set_keys - existing_keys:
- session.add(TagKeyModel(organization_id=organization_id, key=key))
+ await session.execute(insert_stmt)
await session.commit()
return changes
@@ -203,12 +211,31 @@ class TagsRepository(BaseRepository):
result[key] = row.value
return result
+ @db_operation("get_active_tag_events_for_workflow")
+ async def get_active_tag_events_for_workflow(
+ self,
+ 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."""
+ async with self.Session() as session:
+ rows = await self._get_current_active_set_events(
+ 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(
self,
workflow_permanent_id: str,
organization_id: str,
limit: int = 100,
+ since: datetime | None = None,
+ key: str | None = None,
) -> list[WorkflowTagEventModel]:
"""Return tag events newest-first for a workflow. Includes DELETE and superseded SET rows."""
async with self.Session() as session:
@@ -217,8 +244,100 @@ class TagsRepository(BaseRepository):
.where(WorkflowTagEventModel.organization_id == organization_id)
.where(WorkflowTagEventModel.workflow_permanent_id == workflow_permanent_id)
.where(WorkflowTagEventModel.deleted_at.is_(None))
- .order_by(WorkflowTagEventModel.set_at.desc(), WorkflowTagEventModel.tag_event_id.desc())
- .limit(limit)
+ )
+ if since is not None:
+ stmt = stmt.where(WorkflowTagEventModel.set_at >= since)
+ if key is not None:
+ stmt = stmt.where(WorkflowTagEventModel.key == key)
+ stmt = stmt.order_by(WorkflowTagEventModel.set_at.desc(), WorkflowTagEventModel.tag_event_id.desc()).limit(
+ limit
+ )
+ result = await session.execute(stmt)
+ return list(result.scalars().all())
+
+ @db_operation("get_active_tags_for_workflows")
+ async def get_active_tags_for_workflows(
+ 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)."""
+ if not workflow_permanent_ids:
+ return {}
+
+ async with self.Session() as session:
+ stmt = select(WorkflowTagEventModel).where(
+ and_(
+ WorkflowTagEventModel.organization_id == organization_id,
+ WorkflowTagEventModel.workflow_permanent_id.in_(workflow_permanent_ids),
+ WorkflowTagEventModel.superseded_at.is_(None),
+ WorkflowTagEventModel.event_type == TagEventType.SET.value,
+ WorkflowTagEventModel.deleted_at.is_(None),
+ )
+ )
+ rows = (await session.execute(stmt)).scalars().all()
+
+ result: dict[str, dict[str, str]] = {}
+ for row in rows:
+ 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=row.workflow_permanent_id,
+ key=row.key,
+ )
+ continue
+ result.setdefault(row.workflow_permanent_id, {})[row.key] = row.value
+ return result
+
+ @db_operation("list_tag_keys")
+ async def list_tag_keys(self, organization_id: str) -> list[TagKeyModel]:
+ """Active tag-key registry entries for the org, ordered by key for stable
+ autocomplete output."""
+ async with self.Session() as session:
+ stmt = (
+ select(TagKeyModel)
+ .where(TagKeyModel.organization_id == organization_id)
+ .where(TagKeyModel.deleted_at.is_(None))
+ .order_by(TagKeyModel.key.asc())
)
result = await session.execute(stmt)
return list(result.scalars().all())
+
+ @db_operation("get_tag_key")
+ async def get_tag_key(self, organization_id: str, key: str) -> TagKeyModel | None:
+ async with self.Session() as session:
+ stmt = (
+ select(TagKeyModel)
+ .where(TagKeyModel.organization_id == organization_id)
+ .where(TagKeyModel.key == key)
+ .where(TagKeyModel.deleted_at.is_(None))
+ )
+ return (await session.execute(stmt)).scalar_one_or_none()
+
+ @db_operation("update_tag_key_description")
+ async def update_tag_key_description(
+ self,
+ organization_id: str,
+ key: str,
+ description: str | None,
+ ) -> TagKeyModel | None:
+ """Update description on an existing tag-key row. Returns None when the
+ key is not registered for the org (caller should 404)."""
+ async with self.Session() as session:
+ stmt = (
+ select(TagKeyModel)
+ .where(TagKeyModel.organization_id == organization_id)
+ .where(TagKeyModel.key == key)
+ .where(TagKeyModel.deleted_at.is_(None))
+ )
+ row = (await session.execute(stmt)).scalar_one_or_none()
+ if row is None:
+ return None
+ row.description = description
+ await session.commit()
+ await session.refresh(row)
+ return row
diff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.py
index 03eb235d1..fe4d9ced7 100644
--- a/skyvern/forge/sdk/db/repositories/workflows.py
+++ b/skyvern/forge/sdk/db/repositories/workflows.py
@@ -379,6 +379,26 @@ class WorkflowsRepository(BaseRepository):
for workflow in workflows
]
+ @db_operation("get_existing_permanent_ids")
+ async def get_existing_permanent_ids(
+ self,
+ workflow_permanent_ids: list[str],
+ organization_id: str,
+ ) -> set[str]:
+ """Return the subset of ``workflow_permanent_ids`` that exist as
+ non-deleted workflows in the org, filtering out soft-deleted workflows."""
+ if not workflow_permanent_ids:
+ return set()
+ async with self.Session() as session:
+ stmt = (
+ select(WorkflowModel.workflow_permanent_id)
+ .where(WorkflowModel.organization_id == organization_id)
+ .where(WorkflowModel.workflow_permanent_id.in_(workflow_permanent_ids))
+ .where(WorkflowModel.deleted_at.is_(None))
+ .distinct()
+ )
+ return set((await session.execute(stmt)).scalars().all())
+
@db_operation("get_workflows_by_organization_id")
async def get_workflows_by_organization_id(
self,
diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.py
index 1ccc8f17c..6fbaa803d 100644
--- a/skyvern/forge/sdk/routes/agent_protocol.py
+++ b/skyvern/forge/sdk/routes/agent_protocol.py
@@ -1,7 +1,9 @@
import asyncio
import json
+import random
import time
import unicodedata
+from datetime import datetime
from enum import Enum
from typing import Annotated, Any
from urllib.parse import quote
@@ -24,6 +26,7 @@ from fastapi import status as http_status
from fastapi.responses import ORJSONResponse
from opentelemetry import trace
from pydantic import TypeAdapter, ValidationError
+from sqlalchemy.exc import IntegrityError
from skyvern import analytics
from skyvern._version import __version__
@@ -109,6 +112,7 @@ from skyvern.forge.sdk.workflow.exceptions import (
InvalidTemplateWorkflowPermanentId,
WorkflowDefinitionValidationException,
)
+from skyvern.forge.sdk.workflow.models.tags import TagSource, TagWriteContext
from skyvern.forge.sdk.workflow.models.workflow import (
RunWorkflowResponse,
Workflow,
@@ -137,6 +141,18 @@ from skyvern.schemas.runs import (
WorkflowRunRequest,
WorkflowRunResponse,
)
+from skyvern.schemas.tags import (
+ TagApplyRequest,
+ TagHistoryItem,
+ TagHistoryResponse,
+ TagKey,
+ TagKeyUpdate,
+ TagResponse,
+ TagsResponse,
+ WorkflowTagsBatchRequest,
+ WorkflowTagsBatchResponse,
+ _assert_user_key_writable,
+)
from skyvern.schemas.webhooks import RetryRunWebhookRequest, RunWebhookReplayResponse
from skyvern.schemas.workflows import (
BlockType,
@@ -1456,6 +1472,432 @@ async def update_workflow_folder(
raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+async def _assert_workflow_in_org(workflow_permanent_id: str, organization_id: str) -> None:
+ """404 when the wpid does not belong to the caller's org. Centralizes the
+ existence/isolation check across the tag routes."""
+ workflow = await app.DATABASE.workflows.get_workflow_by_permanent_id(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ )
+ if workflow is None:
+ raise HTTPException(
+ status_code=http_status.HTTP_404_NOT_FOUND,
+ detail=f"Workflow {workflow_permanent_id} not found",
+ )
+
+
+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)
+
+
+def _validate_path_key(key: str) -> None:
+ """Apply the same reserved-namespace + shape rules to a URL-path tag key
+ that ``normalize_tags`` applies to SET-body keys. Path violations surface
+ as 400 (vs 422 for body — the offending value comes from the URL, not the
+ request body)."""
+ try:
+ _assert_user_key_writable(key)
+ except ValueError as e:
+ raise HTTPException(status_code=http_status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+
+
+async def _apply_tag_changes_with_retry(
+ *,
+ workflow_permanent_id: str,
+ organization_id: str,
+ sets: dict[str, str],
+ deletes: set[str],
+ context: TagWriteContext,
+) -> 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."""
+ for attempt in range(2):
+ try:
+ await app.DATABASE.tags.apply_tag_changes(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ sets=sets,
+ deletes=deletes,
+ context=context,
+ )
+ return
+ except IntegrityError:
+ if attempt == 0:
+ await asyncio.sleep(random.uniform(0.01, 0.05))
+ continue
+ raise HTTPException(
+ status_code=http_status.HTTP_409_CONFLICT,
+ detail="Tag write conflicted with a concurrent update; please retry",
+ )
+
+
+@legacy_base_router.post(
+ "/workflows/{workflow_permanent_id}/tags",
+ response_model=TagsResponse,
+ tags=["agent"],
+ include_in_schema=False,
+)
+@legacy_base_router.post(
+ "/workflows/{workflow_permanent_id}/tags/", response_model=TagsResponse, include_in_schema=False
+)
+@base_router.post(
+ "/workflows/{workflow_permanent_id}/tags",
+ response_model=TagsResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "apply_workflow_tags"},
+ description="Atomically apply tag changes to a workflow. Sets and deletes happen in one transaction; "
+ "same-key collisions resolve set-wins.",
+ summary="Apply workflow tags",
+ responses={
+ 200: {"description": "Successfully applied tag changes"},
+ 404: {"description": "Workflow not found"},
+ 422: {"description": "Invalid tag key or value"},
+ },
+)
+@base_router.post("/workflows/{workflow_permanent_id}/tags/", response_model=TagsResponse, include_in_schema=False)
+async def apply_workflow_tags(
+ workflow_permanent_id: str = Path(..., description="Workflow permanent ID", examples=["wpid_123"]),
+ data: TagApplyRequest = Body(...),
+ caller: org_auth_service.CallerContext = Depends(org_auth_service.get_current_caller_context),
+) -> TagsResponse:
+ analytics.capture("skyvern-oss-workflow-tags-apply")
+ organization_id = caller.organization.organization_id
+ await _assert_workflow_in_org(workflow_permanent_id, organization_id)
+
+ write_ctx = TagWriteContext(
+ caller_id=caller.caller_id,
+ source=TagSource.MANUAL,
+ caller_type=caller.caller_type,
+ )
+ 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),
+ context=write_ctx,
+ )
+ except ValueError as e:
+ # Cap-breach is the only ValueError surfaced; treat as 422 (user input).
+ raise HTTPException(status_code=http_status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(e)) from e
+
+ return await _build_tags_response(workflow_permanent_id, organization_id)
+
+
+@legacy_base_router.delete(
+ "/workflows/{workflow_permanent_id}/tags/{key}",
+ tags=["agent"],
+ include_in_schema=False,
+)
+@legacy_base_router.delete("/workflows/{workflow_permanent_id}/tags/{key}/", include_in_schema=False)
+@base_router.delete(
+ "/workflows/{workflow_permanent_id}/tags/{key}",
+ response_model=TagsResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "delete_workflow_tag"},
+ description="Soft-delete a single tag from a workflow. Writes a DELETE event row.",
+ summary="Delete workflow tag",
+ responses={
+ 200: {"description": "Successfully deleted tag (or no-op if absent)"},
+ 404: {"description": "Workflow not found"},
+ },
+)
+@base_router.delete(
+ "/workflows/{workflow_permanent_id}/tags/{key}/", response_model=TagsResponse, include_in_schema=False
+)
+async def delete_workflow_tag(
+ workflow_permanent_id: str = Path(..., description="Workflow permanent ID", examples=["wpid_123"]),
+ key: str = Path(..., description="Tag key to delete", examples=["env"]),
+ caller: org_auth_service.CallerContext = Depends(org_auth_service.get_current_caller_context),
+) -> TagsResponse:
+ analytics.capture("skyvern-oss-workflow-tags-delete")
+ organization_id = caller.organization.organization_id
+ _validate_path_key(key)
+ await _assert_workflow_in_org(workflow_permanent_id, organization_id)
+
+ write_ctx = TagWriteContext(
+ caller_id=caller.caller_id,
+ source=TagSource.MANUAL,
+ caller_type=caller.caller_type,
+ )
+ await _apply_tag_changes_with_retry(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ sets={},
+ deletes={key},
+ context=write_ctx,
+ )
+ return await _build_tags_response(workflow_permanent_id, organization_id)
+
+
+@legacy_base_router.get(
+ "/workflows/{workflow_permanent_id}/tags",
+ response_model=TagsResponse,
+ tags=["agent"],
+ include_in_schema=False,
+)
+@legacy_base_router.get(
+ "/workflows/{workflow_permanent_id}/tags/", response_model=TagsResponse, include_in_schema=False
+)
+@base_router.get(
+ "/workflows/{workflow_permanent_id}/tags",
+ response_model=TagsResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "get_workflow_tags"},
+ description="Get the current tag state for a workflow.",
+ summary="Get workflow tags",
+ responses={
+ 200: {"description": "Successfully retrieved tags"},
+ 404: {"description": "Workflow not found"},
+ },
+)
+@base_router.get("/workflows/{workflow_permanent_id}/tags/", response_model=TagsResponse, include_in_schema=False)
+async def get_workflow_tags(
+ workflow_permanent_id: str = Path(..., description="Workflow permanent ID", examples=["wpid_123"]),
+ current_org: Organization = Depends(org_auth_service.get_current_org),
+) -> TagsResponse:
+ organization_id = current_org.organization_id
+ await _assert_workflow_in_org(workflow_permanent_id, organization_id)
+ return await _build_tags_response(workflow_permanent_id, organization_id)
+
+
+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."""
+ 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)
+ return TagsResponse(workflow_permanent_id=workflow_permanent_id, tags=tags)
+
+
+@legacy_base_router.get(
+ "/workflows/{workflow_permanent_id}/tags/history",
+ response_model=TagHistoryResponse,
+ tags=["agent"],
+ include_in_schema=False,
+)
+@legacy_base_router.get(
+ "/workflows/{workflow_permanent_id}/tags/history/",
+ response_model=TagHistoryResponse,
+ include_in_schema=False,
+)
+@base_router.get(
+ "/workflows/{workflow_permanent_id}/tags/history",
+ response_model=TagHistoryResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "get_workflow_tag_history"},
+ description="Chronological tag-event log for a workflow (newest first). Includes SET and DELETE events.",
+ summary="Get workflow tag history",
+ responses={
+ 200: {"description": "Successfully retrieved tag history"},
+ 404: {"description": "Workflow not found"},
+ },
+)
+@base_router.get(
+ "/workflows/{workflow_permanent_id}/tags/history/",
+ response_model=TagHistoryResponse,
+ include_in_schema=False,
+)
+async def get_workflow_tag_history(
+ workflow_permanent_id: str = Path(..., description="Workflow permanent ID", examples=["wpid_123"]),
+ limit: int = Query(100, ge=1, le=500, description="Max events to return"),
+ since: datetime | None = Query(None, description="Only return events at or after this timestamp"),
+ key: str | None = Query(None, description="Filter to events for a single tag key"),
+ current_org: Organization = Depends(org_auth_service.get_current_org),
+) -> TagHistoryResponse:
+ organization_id = current_org.organization_id
+ await _assert_workflow_in_org(workflow_permanent_id, organization_id)
+ rows = await app.DATABASE.tags.get_tag_event_history(
+ workflow_permanent_id=workflow_permanent_id,
+ organization_id=organization_id,
+ limit=limit,
+ since=since,
+ key=key,
+ )
+ return TagHistoryResponse(
+ workflow_permanent_id=workflow_permanent_id,
+ events=[TagHistoryItem.model_validate(r) for r in rows],
+ )
+
+
+@legacy_base_router.get("/tag-keys", response_model=list[TagKey], tags=["agent"], include_in_schema=False)
+@legacy_base_router.get("/tag-keys/", response_model=list[TagKey], include_in_schema=False)
+@base_router.get(
+ "/tag-keys",
+ response_model=list[TagKey],
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "list_tag_keys"},
+ description="List all tag keys registered for the organization with their descriptions.",
+ summary="List tag keys",
+ responses={200: {"description": "Successfully retrieved tag keys"}},
+)
+@base_router.get("/tag-keys/", response_model=list[TagKey], include_in_schema=False)
+async def list_tag_keys(
+ current_org: Organization = Depends(org_auth_service.get_current_org),
+) -> list[TagKey]:
+ rows = await app.DATABASE.tags.list_tag_keys(organization_id=current_org.organization_id)
+ return [TagKey.model_validate(r) for r in rows]
+
+
+@legacy_base_router.patch("/tag-keys/{key}", response_model=TagKey, tags=["agent"], include_in_schema=False)
+@legacy_base_router.patch("/tag-keys/{key}/", response_model=TagKey, include_in_schema=False)
+@base_router.patch(
+ "/tag-keys/{key}",
+ response_model=TagKey,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "update_tag_key"},
+ description="Update the description for a tag key.",
+ summary="Update tag key",
+ responses={
+ 200: {"description": "Successfully updated tag key"},
+ 404: {"description": "Tag key not found"},
+ 422: {"description": "Description too long"},
+ },
+)
+@base_router.patch("/tag-keys/{key}/", response_model=TagKey, include_in_schema=False)
+async def update_tag_key(
+ key: str = Path(..., description="Tag key to update"),
+ data: TagKeyUpdate = Body(...),
+ current_org: Organization = Depends(org_auth_service.get_current_org),
+) -> TagKey:
+ _validate_path_key(key)
+ row = await app.DATABASE.tags.update_tag_key_description(
+ organization_id=current_org.organization_id,
+ key=key,
+ description=data.description,
+ )
+ if row is None:
+ raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail=f"Tag key '{key}' not found")
+ return TagKey.model_validate(row)
+
+
+_BATCH_TAGS_MAX_WPIDS = 200
+
+
+def _parse_batch_wpids(raw: str | None) -> list[str]:
+ """Parse the comma-separated wpid list from the GET query string."""
+ if not raw:
+ return []
+ 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}
+ return WorkflowTagsBatchResponse(workflow_tags=workflow_tags)
+
+
+async def _resolve_active_batch_wpids(requested_wpids: list[str], organization_id: str) -> dict[str, dict[str, 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
+ second check intersects the result keys and drops any wpid that disappeared.
+ The residual race window is the gap between the two SELECTs (sub-ms).
+ Fully eliminating it would require a JOIN that couples ``TagsRepository``
+ to ``WorkflowModel``, which contradicts the Phase 2 boundary decision.
+
+ Costs up to three SELECTs (pre-existence, tag read, post-existence); the
+ bracketing existence checks are the safety mechanism — don't collapse them
+ to save a query."""
+ if not requested_wpids:
+ return {}
+ active_wpids_pre = await app.DATABASE.workflows.get_existing_permanent_ids(
+ workflow_permanent_ids=requested_wpids,
+ organization_id=organization_id,
+ )
+ if not active_wpids_pre:
+ return {}
+ tag_map = await app.DATABASE.tags.get_active_tags_for_workflows(
+ workflow_permanent_ids=list(active_wpids_pre),
+ organization_id=organization_id,
+ )
+ if not tag_map:
+ return {}
+ active_wpids_post = await app.DATABASE.workflows.get_existing_permanent_ids(
+ workflow_permanent_ids=list(tag_map.keys()),
+ organization_id=organization_id,
+ )
+ return {wpid: tags for wpid, tags in tag_map.items() if wpid in active_wpids_post}
+
+
+@legacy_base_router.get(
+ "/workflow-tags", response_model=WorkflowTagsBatchResponse, tags=["agent"], include_in_schema=False
+)
+@legacy_base_router.get("/workflow-tags/", response_model=WorkflowTagsBatchResponse, include_in_schema=False)
+@base_router.get(
+ "/workflow-tags",
+ response_model=WorkflowTagsBatchResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "batch_get_workflow_tags"},
+ description="Batch fetch current tags for many workflows. Avoids N+1 on the workflows-list page.",
+ summary="Batch get workflow tags",
+ responses={
+ 200: {"description": "Successfully retrieved tags"},
+ 400: {"description": "Too many workflow IDs requested"},
+ },
+)
+@base_router.get("/workflow-tags/", response_model=WorkflowTagsBatchResponse, include_in_schema=False)
+async def batch_get_workflow_tags(
+ workflow_permanent_ids: str | None = Query(
+ None,
+ description="Comma-separated workflow permanent IDs",
+ examples=["wpid_123,wpid_456"],
+ ),
+ current_org: Organization = Depends(org_auth_service.get_current_org),
+) -> WorkflowTagsBatchResponse:
+ wpids = _parse_batch_wpids(workflow_permanent_ids)
+ if len(wpids) > _BATCH_TAGS_MAX_WPIDS:
+ raise HTTPException(
+ status_code=http_status.HTTP_400_BAD_REQUEST,
+ detail=f"At most {_BATCH_TAGS_MAX_WPIDS} workflow IDs may be requested at once",
+ )
+ tag_map = await _resolve_active_batch_wpids(wpids, current_org.organization_id)
+ return _build_batch_response(wpids, tag_map)
+
+
+@legacy_base_router.post(
+ "/workflow-tags", response_model=WorkflowTagsBatchResponse, tags=["agent"], include_in_schema=False
+)
+@legacy_base_router.post("/workflow-tags/", response_model=WorkflowTagsBatchResponse, include_in_schema=False)
+@base_router.post(
+ "/workflow-tags",
+ response_model=WorkflowTagsBatchResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "batch_get_workflow_tags_post"},
+ description="Batch fetch current tags for many workflows (POST variant for id lists exceeding URL length).",
+ summary="Batch get workflow tags (POST)",
+ responses={
+ 200: {"description": "Successfully retrieved tags"},
+ 400: {"description": "Too many workflow IDs requested"},
+ },
+)
+@base_router.post("/workflow-tags/", response_model=WorkflowTagsBatchResponse, include_in_schema=False)
+async def batch_get_workflow_tags_post(
+ data: WorkflowTagsBatchRequest = Body(...),
+ current_org: Organization = Depends(org_auth_service.get_current_org),
+) -> WorkflowTagsBatchResponse:
+ wpids = [wpid.strip() for wpid in data.workflow_permanent_ids if wpid and wpid.strip()]
+ if len(wpids) > _BATCH_TAGS_MAX_WPIDS:
+ raise HTTPException(
+ status_code=http_status.HTTP_400_BAD_REQUEST,
+ detail=f"At most {_BATCH_TAGS_MAX_WPIDS} workflow IDs may be requested at once",
+ )
+ tag_map = await _resolve_active_batch_wpids(wpids, current_org.organization_id)
+ return _build_batch_response(wpids, tag_map)
+
+
@legacy_base_router.post(
"/utilities/curl-to-http",
tags=["Utilities"],
diff --git a/skyvern/forge/sdk/workflow/models/validators.py b/skyvern/forge/sdk/workflow/models/validators.py
index f9c66e0bf..76678bb8a 100644
--- a/skyvern/forge/sdk/workflow/models/validators.py
+++ b/skyvern/forge/sdk/workflow/models/validators.py
@@ -18,7 +18,7 @@ TAG_DESCRIPTION_MAX_LENGTH = 500
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_.-]*$")
+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.
_TAG_VALUE_FORBIDDEN_CHARS = (",",)
@@ -106,7 +106,7 @@ def normalize_tags(v: dict[str, str] | None) -> dict[str, str] | None:
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):
+ 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)"
diff --git a/skyvern/schemas/tags.py b/skyvern/schemas/tags.py
new file mode 100644
index 000000000..42df3fc74
--- /dev/null
+++ b/skyvern/schemas/tags.py
@@ -0,0 +1,177 @@
+"""Pydantic schemas for the workflow tagging public API surface."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from skyvern.forge.sdk.workflow.models.validators import (
+ RUN_METADATA_MAX_KEYS,
+ SKYVERN_TAG_NAMESPACE,
+ TAG_DESCRIPTION_MAX_LENGTH,
+ TAG_KEY_REGEX,
+ normalize_tag_description,
+ normalize_tags,
+)
+
+
+def _assert_user_key_writable(key: str) -> None:
+ """Raise ValueError when ``key`` is in the reserved ``skyvern.*`` namespace
+ or violates the URL-safe key regex. Reused on every public write surface
+ (SET, DELETE body, DELETE path, PATCH path) so the namespace boundary
+ enforced by ``normalize_tags`` on SET can't be bypassed via the other
+ write paths."""
+ if not isinstance(key, str):
+ raise ValueError("tag key must be a string")
+ 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)"
+ )
+
+
+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."""
+
+ tags: dict[str, str] = Field(
+ default_factory=dict,
+ description="Tags to set (overwrite). Map of key to value.",
+ )
+ tags_to_delete: list[str] = Field(
+ default_factory=list,
+ description="Tag keys to soft-delete.",
+ )
+
+ @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.
+ 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 {}
+
+ @field_validator("tags_to_delete", mode="before")
+ @classmethod
+ def _normalize_deletes(cls, v: object) -> list[str]:
+ 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:
+ raise ValueError(f"tags_to_delete can include at most {RUN_METADATA_MAX_KEYS} entries")
+ return cleaned
+
+
+class TagResponse(BaseModel):
+ """Current state of one tag (``GET /v1/workflows/{wpid}/tags`` row)."""
+
+ model_config = ConfigDict(from_attributes=True)
+
+ value: str
+ source: str
+ set_at: datetime
+ set_by: str
+
+
+class TagsResponse(BaseModel):
+ """Current tag map for a workflow."""
+
+ workflow_permanent_id: str
+ tags: dict[str, TagResponse]
+
+
+class TagHistoryItem(BaseModel):
+ """One row from ``GET /v1/workflows/{wpid}/tags/history``."""
+
+ model_config = ConfigDict(from_attributes=True)
+
+ tag_event_id: str
+ key: str
+ value: str | None
+ event_type: str
+ source: str
+ set_at: datetime
+ set_by: str
+ superseded_at: datetime | None = None
+
+
+class TagHistoryResponse(BaseModel):
+ workflow_permanent_id: str
+ events: list[TagHistoryItem]
+
+
+class TagKey(BaseModel):
+ """Tag-key registry entry."""
+
+ model_config = ConfigDict(from_attributes=True)
+
+ key: str
+ description: str | None = None
+
+
+class TagKeyUpdate(BaseModel):
+ """Body for ``PATCH /v1/tag-keys/{key}``."""
+
+ description: str | None = Field(
+ None,
+ description=f"Free-form description (max {TAG_DESCRIPTION_MAX_LENGTH} chars). Pass null to clear.",
+ )
+
+ @field_validator("description", mode="before")
+ @classmethod
+ def _normalize(cls, v: object) -> str | None:
+ if v is None:
+ return None
+ if not isinstance(v, str):
+ raise ValueError("description must be a string")
+ return normalize_tag_description(v)
+
+
+class WorkflowTagsBatchRequest(BaseModel):
+ """Body for ``POST /v1/workflow-tags`` (used when the wpid list would
+ exceed the URL length cap)."""
+
+ workflow_permanent_ids: list[str] = Field(
+ default_factory=list,
+ description="Workflow permanent IDs to fetch tags for.",
+ )
+
+
+class WorkflowTagsBatchResponse(BaseModel):
+ """Response for the batch endpoint.
+
+ Workflows with no tags are present with an empty dict 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]]
diff --git a/tests/unit/test_tag_endpoints.py b/tests/unit/test_tag_endpoints.py
new file mode 100644
index 000000000..5bd2db25c
--- /dev/null
+++ b/tests/unit/test_tag_endpoints.py
@@ -0,0 +1,503 @@
+"""End-to-end tests for the workflow tag HTTP endpoints (Phase 3).
+
+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.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import AsyncGenerator
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+import pytest_asyncio
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+
+from skyvern.forge.sdk.db.base_alchemy_db import BaseAlchemyDB
+from skyvern.forge.sdk.db.models import Base
+from skyvern.forge.sdk.db.repositories.tags import TagsRepository
+from skyvern.forge.sdk.schemas.organizations import Organization
+from skyvern.forge.sdk.services import org_auth_service
+from skyvern.forge.sdk.workflow.models.tags import CallerType
+
+ORG_ID = "o_test"
+OTHER_ORG_ID = "o_other"
+WPID = "wpid_alpha"
+OTHER_WPID = "wpid_beta"
+CALLER_ID = "user_test"
+
+
+@pytest_asyncio.fixture
+async def engine() -> AsyncGenerator[AsyncEngine]:
+ eng = create_async_engine("sqlite+aiosqlite:///:memory:")
+ async with eng.begin() as conn:
+ await conn.run_sync(Base.metadata.create_all)
+ yield eng
+ await eng.dispose()
+
+
+@pytest_asyncio.fixture
+async def repo(engine: AsyncEngine) -> TagsRepository:
+ db = BaseAlchemyDB(engine)
+ return TagsRepository(db.Session, debug_enabled=False)
+
+
+def _make_org(org_id: str = ORG_ID) -> Organization:
+ now = dt.datetime.now(dt.timezone.utc)
+ return Organization(
+ organization_id=org_id,
+ organization_name="Test Org",
+ created_at=now,
+ modified_at=now,
+ )
+
+
+def app_with_routes(repo: TagsRepository, monkeypatch: pytest.MonkeyPatch) -> FastAPI:
+ """Mount the real routers with patched ``app`` module + dependency overrides.
+
+ The route handlers reach the DB via ``app.DATABASE.tags`` and
+ ``app.DATABASE.workflows``; we point both at fakes that delegate to the
+ in-memory ``TagsRepository`` and a mock workflow lookup respectively.
+ """
+ from skyvern.forge.sdk.routes import agent_protocol as ap
+ from skyvern.forge.sdk.routes.routers import base_router, legacy_base_router
+
+ workflows_mock = MagicMock()
+
+ async def _get_workflow_by_permanent_id(
+ workflow_permanent_id: str,
+ organization_id: str | None = None,
+ **kwargs: object,
+ ) -> object | None:
+ # Only WPID exists under ORG_ID. Cross-org callers see None.
+ if workflow_permanent_id == WPID and organization_id == ORG_ID:
+ return MagicMock(workflow_permanent_id=WPID, organization_id=ORG_ID)
+ if workflow_permanent_id == OTHER_WPID and organization_id == OTHER_ORG_ID:
+ return MagicMock(workflow_permanent_id=OTHER_WPID, organization_id=OTHER_ORG_ID)
+ return None
+
+ workflows_mock.get_workflow_by_permanent_id = AsyncMock(side_effect=_get_workflow_by_permanent_id)
+
+ async def _get_existing_permanent_ids(workflow_permanent_ids: list[str], organization_id: str) -> set[str]:
+ # Same residency rules as the per-workflow mock, but bulk.
+ if organization_id == ORG_ID:
+ return {wpid for wpid in workflow_permanent_ids if wpid == WPID}
+ if organization_id == OTHER_ORG_ID:
+ return {wpid for wpid in workflow_permanent_ids if wpid == OTHER_WPID}
+ return set()
+
+ workflows_mock.get_existing_permanent_ids = AsyncMock(side_effect=_get_existing_permanent_ids)
+
+ database_mock = MagicMock()
+ database_mock.tags = repo
+ database_mock.workflows = workflows_mock
+
+ app_mock = MagicMock()
+ app_mock.DATABASE = database_mock
+
+ monkeypatch.setattr(ap, "app", app_mock)
+
+ test_app = FastAPI()
+ test_app.include_router(base_router, prefix="/v1")
+ test_app.include_router(legacy_base_router, prefix="/api/v1")
+
+ def _override_get_current_org() -> Organization:
+ return _make_org(ORG_ID)
+
+ def _override_get_current_caller_context() -> org_auth_service.CallerContext:
+ return org_auth_service.CallerContext(
+ organization=_make_org(ORG_ID),
+ caller_id=CALLER_ID,
+ caller_type=CallerType.USER,
+ )
+
+ test_app.dependency_overrides[org_auth_service.get_current_org] = _override_get_current_org
+ test_app.dependency_overrides[org_auth_service.get_current_caller_context] = _override_get_current_caller_context
+
+ return test_app
+
+
+def client(app_with_routes: FastAPI) -> TestClient:
+ return TestClient(app_with_routes)
+
+
+# ----------------------------- POST /workflows/{wpid}/tags ---------------------------
+
+
+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": []},
+ )
+ assert resp.status_code == 200, resp.text
+ assert set(resp.json()["tags"].keys()) == {"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"]},
+ )
+ assert resp.status_code == 200
+ body = resp.json()
+ # 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
+
+
+def test_post_tags_empty_noop(client: TestClient) -> None:
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {}, "tags_to_delete": []})
+ assert resp.status_code == 200
+ assert resp.json()["tags"] == {}
+
+
+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"}})
+ 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"}})
+ 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"}},
+ )
+ 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": []})
+ assert resp.status_code == 200
+
+
+# ----------------------------- DELETE /workflows/{wpid}/tags/{key} -------------------
+
+
+def test_delete_tag_supersedes_prior_set(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ resp = client.delete(f"/v1/workflows/{WPID}/tags/env")
+ assert resp.status_code == 200
+ assert "env" not in 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"] == {}
+
+
+def test_delete_tag_404_when_workflow_not_in_org(client: TestClient) -> None:
+ resp = client.delete("/v1/workflows/wpid_missing/tags/env")
+ assert resp.status_code == 404
+
+
+# ----------------------------- GET /workflows/{wpid}/tags ----------------------------
+
+
+def test_get_tags_returns_current_state(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "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():
+ # 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_404_when_workflow_not_in_org(client: TestClient) -> None:
+ resp = client.get("/v1/workflows/wpid_missing/tags")
+ assert resp.status_code == 404
+
+
+# ----------------------------- GET /workflows/{wpid}/tags/history --------------------
+
+
+def test_get_history_includes_set_and_delete_events(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ client.delete(f"/v1/workflows/{WPID}/tags/env")
+ resp = client.get(f"/v1/workflows/{WPID}/tags/history")
+ assert resp.status_code == 200
+ events = resp.json()["events"]
+ assert len(events) == 2
+ types = {e["event_type"] for e in events}
+ assert types == {"set", "delete"}
+ # Newest first.
+ assert events[0]["event_type"] == "delete"
+ # DELETE row has null value; 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
+ assert set_evt["value"] == "prod"
+
+
+def test_get_history_filter_by_key(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ resp = client.get(f"/v1/workflows/{WPID}/tags/history?key=team")
+ assert resp.status_code == 200
+ events = resp.json()["events"]
+ assert all(e["key"] == "team" for e in events)
+ assert len(events) == 1
+
+
+# ----------------------------- GET/PATCH /tag-keys -----------------------------------
+
+
+def test_list_tag_keys_returns_registered_keys(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "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_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"}})
+ 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"}})
+ resp = client.patch("/v1/tag-keys/env", json={"description": "x" * 501})
+ assert resp.status_code == 422
+
+
+# ----------------------------- Batch endpoints ---------------------------------------
+
+
+def test_batch_get_returns_map_keyed_by_wpid(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "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"}}
+
+
+def test_batch_get_returns_empty_dict_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: {}}
+
+
+def test_batch_get_cross_org_isolation(client: TestClient, repo: TagsRepository) -> None:
+ """Tags belonging to a different org must not appear in the response."""
+ import asyncio
+
+ from skyvern.forge.sdk.workflow.models.tags import TagSource, TagWriteContext
+
+ # Plant a tag in a different org for OTHER_WPID.
+ asyncio.run(
+ repo.apply_tag_changes(
+ workflow_permanent_id=OTHER_WPID,
+ organization_id=OTHER_ORG_ID,
+ sets={"secret": "leak_me"},
+ deletes=set(),
+ context=TagWriteContext(
+ caller_id="user_other",
+ source=TagSource.MANUAL,
+ caller_type=CallerType.USER,
+ ),
+ )
+ )
+ resp = client.get(f"/v1/workflow-tags?workflow_permanent_ids={WPID},{OTHER_WPID}")
+ assert resp.status_code == 200
+ 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] == {}
+
+
+def test_batch_post_accepts_body(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "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"}}
+
+
+def test_batch_get_legacy_route_works(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "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) ---------------------
+
+
+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."""
+ 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}})
+ 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']."""
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags_to_delete": "env"})
+ 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"]})
+ assert resp.status_code == 422
+
+
+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)]},
+ )
+ assert resp.status_code == 422
+
+
+def test_delete_path_reserved_namespace_returns_400(client: TestClient) -> None:
+ """CORR-3: URL-path-keys violating the namespace must return 400 (not 422)
+ because the offending value is in the path, not the body."""
+ resp = client.delete(f"/v1/workflows/{WPID}/tags/skyvern.managed")
+ assert resp.status_code == 400
+
+
+def test_delete_path_bad_shape_returns_400(client: TestClient) -> None:
+ """CORR-3: same path-level rule for shape (regex) violations."""
+ resp = client.delete(f"/v1/workflows/{WPID}/tags/.leading-dot")
+ assert resp.status_code == 400
+
+
+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."""
+ resp = client.patch("/v1/tag-keys/skyvern.managed", json={"description": "hi"})
+ assert resp.status_code == 400
+
+
+def test_patch_tag_key_bad_shape_returns_400(client: TestClient) -> None:
+ resp = client.patch("/v1/tag-keys/.bad-key", json={"description": "hi"})
+ assert resp.status_code == 400
+
+
+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"}})
+ resp = client.patch("/v1/tag-keys/env", json={"description": 123})
+ assert resp.status_code == 422
+
+
+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."""
+ import asyncio
+
+ from skyvern.forge.sdk.workflow.models.tags import TagSource, TagWriteContext
+
+ # Plant a tag so the read returns something to filter.
+ asyncio.run(
+ repo.apply_tag_changes(
+ workflow_permanent_id=WPID,
+ organization_id=ORG_ID,
+ sets={"env": "prod"},
+ deletes=set(),
+ context=TagWriteContext(caller_id=CALLER_ID, source=TagSource.MANUAL, caller_type=CallerType.USER),
+ )
+ )
+
+ call_count = {"n": 0}
+
+ async def _existence_check_then_disappear(workflow_permanent_ids: list[str], organization_id: str) -> set[str]:
+ call_count["n"] += 1
+ if call_count["n"] == 1:
+ return {WPID} # first check: workflow still present
+ 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)
+
+ client = TestClient(app_with_routes)
+ 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: {}}
+
+
+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."""
+ from sqlalchemy.exc import IntegrityError
+
+ from skyvern.forge.sdk.routes import agent_protocol as ap
+
+ ap.app.DATABASE.tags.apply_tag_changes = AsyncMock(
+ side_effect=IntegrityError("statement", {}, Exception("conflict"))
+ )
+
+ client = TestClient(app_with_routes)
+ resp = client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ assert resp.status_code == 409
+
+
+def test_post_succeeds_when_first_integrity_error_then_succeeds(app_with_routes: FastAPI) -> None:
+ """RISK-3: the retry is actually exercised — first attempt raises, second
+ succeeds, response is 200."""
+ from sqlalchemy.exc import IntegrityError
+
+ from skyvern.forge.sdk.routes import agent_protocol as ap
+
+ attempts = {"n": 0}
+
+ async def _flaky(*args: object, **kwargs: object) -> list:
+ attempts["n"] += 1
+ if attempts["n"] == 1:
+ raise IntegrityError("statement", {}, Exception("conflict"))
+ return []
+
+ ap.app.DATABASE.tags.apply_tag_changes = AsyncMock(side_effect=_flaky)
+ # _build_tags_response also reaches the repo — stub the read path so the
+ # 200 response can render after the retry succeeds.
+ 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"}})
+ 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
new file mode 100644
index 000000000..6b3f39db7
--- /dev/null
+++ b/tests/unit/test_tag_schemas.py
@@ -0,0 +1,57 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import pytest
+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."""
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": {1: "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)."""
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags": {"env": 1}})
+
+
+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."""
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags_to_delete": "env"})
+
+
+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."""
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags_to_delete": ["skyvern.managed"]})
+
+
+def test_tag_apply_request_caps_tags_to_delete() -> None:
+ with pytest.raises(ValidationError):
+ TagApplyRequest.model_validate({"tags_to_delete": [f"k{i}" for i in range(21)]})
+
+
+def test_tag_key_update_rejects_non_string_description() -> None:
+ with pytest.raises(ValidationError):
+ TagKeyUpdate.model_validate({"description": 123})
+
+
+def test_tag_key_update_accepts_none() -> None:
+ parsed = TagKeyUpdate.model_validate({"description": None})
+ assert parsed.description is None
diff --git a/tests/unit/test_tags_repository.py b/tests/unit/test_tags_repository.py
index 3f5f62406..25feed683 100644
--- a/tests/unit/test_tags_repository.py
+++ b/tests/unit/test_tags_repository.py
@@ -31,30 +31,11 @@ ORG_ID = "o_test"
WPID = "wpid_alpha"
-async def _enable_partial_unique_indexes(engine: AsyncEngine) -> None:
- """SQLite ignores postgresql_where, so the model's partial unique indexes
- become full unique indexes. Drop them and re-create with WHERE clauses so
- test behavior matches Postgres semantics.
- """
- async with engine.begin() as conn:
- await conn.exec_driver_sql("DROP INDEX IF EXISTS workflow_tag_events_active_set_unique")
- await conn.exec_driver_sql(
- "CREATE UNIQUE INDEX workflow_tag_events_active_set_unique "
- "ON workflow_tag_events (organization_id, workflow_permanent_id, key) "
- "WHERE superseded_at IS NULL AND event_type = 'set'"
- )
- await conn.exec_driver_sql("DROP INDEX IF EXISTS ix_tag_keys_org_key_active")
- await conn.exec_driver_sql(
- "CREATE UNIQUE INDEX ix_tag_keys_org_key_active ON tag_keys (organization_id, key) WHERE deleted_at IS NULL"
- )
-
-
@pytest_asyncio.fixture
async def engine() -> AsyncGenerator[AsyncEngine]:
eng = create_async_engine("sqlite+aiosqlite:///:memory:")
async with eng.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
- await _enable_partial_unique_indexes(eng)
yield eng
await eng.dispose()
@@ -406,3 +387,122 @@ async def test_value_can_contain_colons(repo: TagsRepository) -> None:
"jira_ticket": "PROJ-1234:bugfix",
"captured_at": "2026-05-25T18:30:00Z",
}
+
+
+# ---------------------------- Phase 3 read helpers ----------------------------
+
+
+async def test_get_active_tags_for_workflows_batch(repo: TagsRepository) -> None:
+ """Batch read groups rows by wpid and applies the org filter."""
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ await repo.apply_tag_changes("wpid_beta", ORG_ID, sets={"team": "growth"}, deletes=set(), context=_ctx())
+ # Different org for the same wpid — must not bleed across.
+ 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"}}
+
+
+async def test_get_active_tags_for_workflows_empty_input(repo: TagsRepository) -> None:
+ assert await repo.get_active_tags_for_workflows([], ORG_ID) == {}
+
+
+async def test_list_tag_keys_orders_alphabetically(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(
+ WPID, ORG_ID, sets={"zeta": "1", "alpha": "2", "mu": "3"}, deletes=set(), context=_ctx()
+ )
+ rows = await repo.list_tag_keys(ORG_ID)
+ assert [r.key for r in rows] == ["alpha", "mu", "zeta"]
+
+
+async def test_list_tag_keys_excludes_other_orgs(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"a": "1"}, deletes=set(), context=_ctx())
+ await repo.apply_tag_changes(WPID, "o_other", sets={"b": "2"}, deletes=set(), context=_ctx("other"))
+ rows = await repo.list_tag_keys(ORG_ID)
+ assert [r.key for r in rows] == ["a"]
+
+
+async def test_update_tag_key_description_sets_value(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ row = await repo.update_tag_key_description(ORG_ID, "env", "deployment environment")
+ assert row is not None
+ assert row.description == "deployment environment"
+
+
+async def test_update_tag_key_description_unknown_returns_none(repo: TagsRepository) -> None:
+ row = await repo.update_tag_key_description(ORG_ID, "never_seen", "x")
+ assert row is None
+
+
+async def test_update_tag_key_description_org_scoped(repo: TagsRepository) -> None:
+ """Updating in one org must not match a same-keyed row in another org."""
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ row = await repo.update_tag_key_description("o_other", "env", "shouldn't find")
+ assert row is None
+
+
+async def test_get_tag_event_history_filters_by_since(repo: TagsRepository) -> None:
+ """`since` is inclusive; events earlier than the cutoff are excluded."""
+ from datetime import datetime, timezone
+
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ cutoff = datetime.now(timezone.utc)
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "stage"}, deletes=set(), context=_ctx())
+
+ events = await repo.get_tag_event_history(WPID, ORG_ID, since=cutoff)
+ # Only the second SET is at-or-after cutoff.
+ assert len(events) == 1
+ assert events[0].value == "stage"
+
+
+async def test_get_tag_event_history_filters_by_key(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod", "team": "growth"}, deletes=set(), context=_ctx())
+ events = await repo.get_tag_event_history(WPID, ORG_ID, key="team")
+ assert {e.key for e in events} == {"team"}
+
+
+# ---------------------------- Race-safe TagKeyModel registration (RISK-2) ----------------------------
+
+
+async def test_apply_tag_changes_idempotent_when_tag_key_already_exists(repo: TagsRepository) -> None:
+ """A concurrent first-use writer that beat us to registering the TagKey
+ must not surface IntegrityError. Simulated by pre-inserting the row out
+ of band, then running apply_tag_changes for the same key — the
+ ON CONFLICT DO NOTHING path swallows the conflict."""
+ async with repo.Session() as session:
+ session.add(TagKeyModel(organization_id=ORG_ID, key="env"))
+ await session.commit()
+
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+
+ # Still exactly one TagKeyModel row — the duplicate insert was swallowed.
+ async with repo.Session() as session:
+ keys = (
+ (
+ await session.execute(
+ select(TagKeyModel).where(TagKeyModel.organization_id == ORG_ID).where(TagKeyModel.key == "env")
+ )
+ )
+ .scalars()
+ .all()
+ )
+ assert len(keys) == 1
+ assert await repo.get_active_tags_for_workflow(WPID, ORG_ID) == {"env": "prod"}
+
+
+async def test_apply_tag_changes_registers_new_key_when_absent(repo: TagsRepository) -> None:
+ """Same code path, normal case: no existing TagKey row, INSERT proceeds
+ and the registry gets the new entry."""
+ await repo.apply_tag_changes(WPID, ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ assert await _registered_keys(repo) == ["env"]