Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
[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.pyindex 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.pyindex 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 dataclassfrom datetime import datetime, timezoneimport structlog-from sqlalchemy import and_, select+from sqlalchemy import and_, select, text+from sqlalchemy.dialects import postgresql, sqlitefrom sqlalchemy.ext.asyncio import AsyncSessionfrom 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.valuereturn 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 rowdiff --git a/skyvern/forge/sdk/db/repositories/workflows.py b/skyvern/forge/sdk/db/repositories/workflows.pyindex 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.pyindex 1ccc8f17c..6fbaa803d 100644--- a/skyvern/forge/sdk/routes/agent_protocol.py+++ b/skyvern/forge/sdk/routes/agent_protocol.py@@ -1,7 +1,9 @@import asyncioimport json+import randomimport timeimport unicodedata+from datetime import datetimefrom enum import Enumfrom typing import Annotated, Anyfrom urllib.parse import quote@@ -24,6 +26,7 @@ from fastapi import status as http_statusfrom fastapi.responses import ORJSONResponsefrom opentelemetry import tracefrom pydantic import TypeAdapter, ValidationError+from sqlalchemy.exc import IntegrityErrorfrom skyvern import analyticsfrom 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, TagWriteContextfrom 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, RunWebhookReplayResponsefrom 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.pyindex 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 = 500SKYVERN_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.pynew file mode 100644index 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.pynew file mode 100644index 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"] == 2diff --git a/tests/unit/test_tag_schemas.py b/tests/unit/test_tag_schemas.pynew file mode 100644index 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 Nonediff --git a/tests/unit/test_tags_repository.py b/tests/unit/test_tags_repository.pyindex 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.fixtureasync 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 engawait 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"]