Skip to content

Automate browser based workflows with AI

feat(tagging): Phase 6 frontend — tag chips, filter, editor, delete-key (SKY-10105) (#6402)

Trevor Cheung35d1532d0345
diff --git a/skyvern-frontend/src/routes/workflows/WorkflowPage.test.tsx b/skyvern-frontend/src/routes/workflows/WorkflowPage.test.tsx
index 55448f6fd..557b272ec 100644
--- a/skyvern-frontend/src/routes/workflows/WorkflowPage.test.tsx
+++ b/skyvern-frontend/src/routes/workflows/WorkflowPage.test.tsx
@@ -63,6 +63,14 @@ vi.mock("./hooks/useWorkflowRunsQuery", () => ({
}),
}));
+vi.mock("./hooks/useWorkflowTagsBatchQuery", () => ({
+ useWorkflowTagsBatchQuery: () => ({ data: {} }),
+}));
+
+vi.mock("./hooks/useTagKeysQuery", () => ({
+ useTagKeysQuery: () => ({ data: [] }),
+}));
+
vi.mock("./hooks/useKeywordSearch", () => ({
useKeywordSearch: () => ({
matchesParameter: () => false,
diff --git a/skyvern-frontend/src/routes/workflows/WorkflowPage.tsx b/skyvern-frontend/src/routes/workflows/WorkflowPage.tsx
index 97d22f98e..912823984 100644
--- a/skyvern-frontend/src/routes/workflows/WorkflowPage.tsx
+++ b/skyvern-frontend/src/routes/workflows/WorkflowPage.tsx
@@ -44,7 +44,7 @@ import {
} from "@/util/timeFormat";
import { cn } from "@/util/utils";
import CloudContext from "@/store/CloudContext";
-import React, { useContext, useEffect, useState } from "react";
+import React, { useContext, useEffect, useMemo, useState } from "react";
import {
Link,
useNavigate,
@@ -53,6 +53,9 @@ import {
} from "react-router-dom";
import { useWorkflowQuery } from "./hooks/useWorkflowQuery";
import { useWorkflowRunsQuery } from "./hooks/useWorkflowRunsQuery";
+import { useTagKeysQuery } from "./hooks/useTagKeysQuery";
+import { useWorkflowTagsBatchQuery } from "./hooks/useWorkflowTagsBatchQuery";
+import { TagChipList } from "./components/tagging/TagChipList";
import { WorkflowActions } from "./WorkflowActions";
import { useDebounce } from "use-debounce";
import {
@@ -120,6 +123,24 @@ function WorkflowPage() {
workflowPermanentId,
});
+ const { data: workflowTagsMap = {} } = useWorkflowTagsBatchQuery(
+ workflowPermanentId ? [workflowPermanentId] : [],
+ );
+ const workflowTags = workflowPermanentId
+ ? workflowTagsMap[workflowPermanentId]
+ : undefined;
+ const { data: tagKeys = [] } = useTagKeysQuery();
+ const tagDescriptions = useMemo(
+ () =>
+ new Map(
+ tagKeys.map((tagKey): [string, string | null] => [
+ tagKey.key,
+ tagKey.description,
+ ]),
+ ),
+ [tagKeys],
+ );
+
useEffect(() => {
if (!isSearchActive) {
setAutoExpandedRows([]);
@@ -141,18 +162,29 @@ function WorkflowPage() {
return (
<div className="space-y-8">
<header className="flex justify-between">
- <div className="flex flex-col gap-2">
- {workflowIsLoading ? (
- <>
- <Skeleton className="h-7 w-56" />
- <Skeleton className="h-7 w-56" />
- </>
- ) : (
- <>
- <h1 className="text-lg font-semibold">{workflow?.title}</h1>
- <h2 className="text-sm">{workflowPermanentId}</h2>
- </>
- )}
+ <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
+ <div className="flex flex-col gap-2">
+ {workflowIsLoading ? (
+ <>
+ <Skeleton className="h-7 w-56" />
+ <Skeleton className="h-7 w-56" />
+ </>
+ ) : (
+ <>
+ <h1 className="text-lg font-semibold">{workflow?.title}</h1>
+ <h2 className="text-sm">{workflowPermanentId}</h2>
+ </>
+ )}
+ </div>
+ {!workflowIsLoading &&
+ workflowTags &&
+ Object.keys(workflowTags).length > 0 ? (
+ <TagChipList
+ tags={workflowTags}
+ descriptions={tagDescriptions}
+ maxVisible={6}
+ />
+ ) : null}
</div>
<div className="flex gap-2">
{workflow && (
diff --git a/skyvern-frontend/src/routes/workflows/Workflows.tsx b/skyvern-frontend/src/routes/workflows/Workflows.tsx
index f22b72cc7..d1d1182c1 100644
--- a/skyvern-frontend/src/routes/workflows/Workflows.tsx
+++ b/skyvern-frontend/src/routes/workflows/Workflows.tsx
@@ -38,7 +38,7 @@ import {
} from "@radix-ui/react-icons";
import { FolderIcon } from "@/components/icons/FolderIcon";
import { useQuery } from "@tanstack/react-query";
-import React, { useEffect, useMemo, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
import { Link, useNavigate, useSearchParams } from "react-router-dom";
import { useDebounce } from "use-debounce";
import {
@@ -56,7 +56,17 @@ import { WorkflowFolderSelector } from "./components/WorkflowFolderSelector";
import { HighlightText } from "./components/HighlightText";
import { useCreateWorkflowMutation } from "./hooks/useCreateWorkflowMutation";
import { useFoldersQuery } from "./hooks/useFoldersQuery";
+import { useTagKeysQuery } from "./hooks/useTagKeysQuery";
+import { useWorkflowTagsBatchQuery } from "./hooks/useWorkflowTagsBatchQuery";
import { useActiveImportsPolling } from "./hooks/useActiveImportsPolling";
+import { TagChipList } from "./components/tagging/TagChipList";
+import { WorkflowTagFilter } from "./components/tagging/WorkflowTagFilter";
+import { WorkflowTagEditor } from "./components/tagging/WorkflowTagEditor";
+import {
+ parseTagFilter,
+ serializeTagFilter,
+ type TagFilterPair,
+} from "./types/tagTypes";
import { ImportWorkflowButton } from "./ImportWorkflowButton";
import { convert } from "./editor/workflowEditorUtils";
import { WorkflowApiResponse } from "./types/workflowTypes";
@@ -123,6 +133,33 @@ function Workflows() {
// Folder slug from query param (e.g., /workflows?folder=my-folder-name)
const folderSlug = searchParams.get("folder");
+ // Tag filter from query param (e.g., /workflows?tags=env:prod,env:staging).
+ // The backend accepts both comma-separated pairs and repeated `tags` params,
+ // so read every occurrence. The serialized form is canonical (sorted) and is
+ // used for both the request and the query key so cache hits are
+ // order-independent.
+ const tagFilterParam = searchParams.getAll("tags").join(",");
+ const tagFilters = useMemo(
+ () => parseTagFilter(tagFilterParam),
+ [tagFilterParam],
+ );
+ const serializedTagFilter = serializeTagFilter(tagFilters);
+
+ const setTagFilters = useCallback(
+ (pairs: TagFilterPair[]) => {
+ const params = new URLSearchParams(searchParams);
+ const serialized = serializeTagFilter(pairs);
+ if (serialized) {
+ params.set("tags", serialized);
+ } else {
+ params.delete("tags");
+ }
+ params.set("page", "1");
+ setSearchParams(params, { replace: true });
+ },
+ [searchParams, setSearchParams],
+ );
+
const [isCreateFolderOpen, setIsCreateFolderOpen] = useState(false);
const [isViewAllFoldersOpen, setIsViewAllFoldersOpen] = useState(false);
@@ -221,6 +258,7 @@ function Workflows() {
page,
itemsPerPage,
selectedFolderId,
+ serializedTagFilter,
],
queryFn: async () => {
const client = await getClient(credentialGetter);
@@ -234,6 +272,9 @@ function Workflows() {
if (selectedFolderId) {
params.append("folder_id", selectedFolderId);
}
+ if (serializedTagFilter) {
+ params.append("tags", serializedTagFilter);
+ }
return client
.get(`/workflows`, {
params,
@@ -250,6 +291,7 @@ function Workflows() {
page + 1,
itemsPerPage,
selectedFolderId,
+ serializedTagFilter,
],
queryFn: async () => {
const client = await getClient(credentialGetter);
@@ -263,6 +305,9 @@ function Workflows() {
if (selectedFolderId) {
params.append("folder_id", selectedFolderId);
}
+ if (serializedTagFilter) {
+ params.append("tags", serializedTagFilter);
+ }
return client
.get(`/workflows`, {
params,
@@ -275,6 +320,49 @@ function Workflows() {
const isNextDisabled =
isFetching || !nextPageWorkflows || nextPageWorkflows.length === 0;
+ // Tag-key registry: supplies chip-hover descriptions and the filter's key list.
+ // Keyed with a Map so tag keys like "constructor"/"toString" can't resolve to
+ // inherited Object prototype members when looked up.
+ const { data: tagKeys = [] } = useTagKeysQuery();
+ const tagDescriptions = useMemo(
+ () =>
+ new Map(
+ tagKeys.map((tagKey): [string, string | null] => [
+ tagKey.key,
+ tagKey.description,
+ ]),
+ ),
+ [tagKeys],
+ );
+
+ // One batch fetch of current tags for every workflow on the page (no N+1).
+ const workflowIds = useMemo(
+ () => workflows.map((workflow) => workflow.workflow_permanent_id),
+ [workflows],
+ );
+ const { data: workflowTagsMap = {} } = useWorkflowTagsBatchQuery(workflowIds);
+
+ // Distinct values per key observed on the page, used as filter suggestions.
+ // Maps avoid prototype-key collisions from user-controlled tag keys.
+ const tagValueSuggestions = useMemo(() => {
+ const collected = new Map<string, Set<string>>();
+ for (const tags of Object.values(workflowTagsMap)) {
+ for (const [key, value] of Object.entries(tags)) {
+ let values = collected.get(key);
+ if (!values) {
+ values = new Set<string>();
+ collected.set(key, values);
+ }
+ values.add(value);
+ }
+ }
+ const suggestions = new Map<string, string[]>();
+ for (const [key, values] of collected) {
+ suggestions.set(key, [...values].sort());
+ }
+ return suggestions;
+ }, [workflowTagsMap]);
+
const { matchesParameter, isSearchActive } =
useKeywordSearch(debouncedSearch);
const {
@@ -485,15 +573,23 @@ function Workflows() {
)}
</header>
<div className="flex justify-between">
- <TableSearchInput
- value={search}
- onChange={(value) => {
- setSearch(value);
- setParamPatch({ page: "1" });
- }}
- placeholder="Search by title or input..."
- className="w-48 lg:w-72"
- />
+ <div className="flex items-center gap-3">
+ <TableSearchInput
+ value={search}
+ onChange={(value) => {
+ setSearch(value);
+ setParamPatch({ page: "1" });
+ }}
+ placeholder="Search by title or input..."
+ className="w-48 lg:w-72"
+ />
+ <WorkflowTagFilter
+ tagKeys={tagKeys}
+ value={tagFilters}
+ onChange={setTagFilters}
+ valueSuggestions={tagValueSuggestions}
+ />
+ </div>
<div className="flex items-center gap-4">
<Link
to="/discover"
@@ -600,6 +696,8 @@ function Workflows() {
);
// Check if this is an importing agent
const isUploading = workflow.status === "importing";
+ const workflowTags =
+ workflowTagsMap[workflow.workflow_permanent_id];
return (
<React.Fragment key={workflow.workflow_permanent_id}>
@@ -665,23 +763,35 @@ function Workflows() {
);
}}
>
- <div className="flex min-w-0 items-center gap-2">
- <span className="truncate" title={workflow.title}>
- <HighlightText
- text={workflow.title}
- query={debouncedSearch}
+ <div className="flex min-w-0 flex-col gap-1">
+ <div className="flex min-w-0 items-center gap-2">
+ <span
+ className="truncate"
+ title={workflow.title}
+ >
+ <HighlightText
+ text={workflow.title}
+ query={debouncedSearch}
+ />
+ </span>
+ {workflow.is_template && (
+ <TooltipProvider>
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <BookmarkFilledIcon className="h-3.5 w-3.5 shrink-0 text-blue-500" />
+ </TooltipTrigger>
+ <TooltipContent>Template</TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ )}
+ </div>
+ {workflowTags &&
+ Object.keys(workflowTags).length > 0 ? (
+ <TagChipList
+ tags={workflowTags}
+ descriptions={tagDescriptions}
/>
- </span>
- {workflow.is_template && (
- <TooltipProvider>
- <Tooltip>
- <TooltipTrigger asChild>
- <BookmarkFilledIcon className="h-3.5 w-3.5 shrink-0 text-blue-500" />
- </TooltipTrigger>
- <TooltipContent>Template</TooltipContent>
- </Tooltip>
- </TooltipProvider>
- )}
+ ) : null}
</div>
</TableCell>
<TableCell
@@ -746,6 +856,14 @@ function Workflows() {
</TooltipContent>
</Tooltip>
</TooltipProvider>
+ <WorkflowTagEditor
+ workflowPermanentId={
+ workflow.workflow_permanent_id
+ }
+ tags={workflowTags ?? {}}
+ tagKeys={tagKeys}
+ valueSuggestions={tagValueSuggestions}
+ />
<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
diff --git a/skyvern-frontend/src/routes/workflows/components/tagging/TagChip.tsx b/skyvern-frontend/src/routes/workflows/components/tagging/TagChip.tsx
new file mode 100644
index 000000000..69f8c1ae4
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/components/tagging/TagChip.tsx
@@ -0,0 +1,69 @@
+import { Cross2Icon } from "@radix-ui/react-icons";
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipProvider,
+ TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { badgeVariants } from "@/components/ui/badge-variants";
+import { cn } from "@/util/utils";
+
+type Props = {
+ tagKey: string;
+ value: string;
+ description?: string | null;
+ onRemove?: () => void;
+ className?: string;
+};
+
+// Generic single-tag chip. Rendered as a styled span (not the Badge div) so it
+// can be a Radix TooltipTrigger `asChild` target without a ref/nesting warning.
+// Reusable wherever a `key: value` tag is shown (workflow cards today, run-tag
+// UI later).
+function TagChip({ tagKey, value, description, onRemove, className }: Props) {
+ const chip = (
+ <span
+ className={cn(
+ badgeVariants({ variant: "secondary" }),
+ "max-w-full gap-1 font-normal",
+ className,
+ )}
+ >
+ <span className="truncate">
+ <span className="font-medium">{tagKey}</span>
+ <span className="text-muted-foreground">: </span>
+ {value}
+ </span>
+ {onRemove ? (
+ <button
+ type="button"
+ aria-label={`Remove ${tagKey}: ${value}`}
+ className="ml-0.5 shrink-0 rounded-sm opacity-70 hover:opacity-100"
+ onClick={(event) => {
+ event.stopPropagation();
+ onRemove();
+ }}
+ >
+ <Cross2Icon className="h-3 w-3" />
+ </button>
+ ) : null}
+ </span>
+ );
+
+ if (!description) {
+ return chip;
+ }
+
+ return (
+ <TooltipProvider>
+ <Tooltip>
+ <TooltipTrigger asChild>{chip}</TooltipTrigger>
+ <TooltipContent className="max-w-xs break-words">
+ {description}
+ </TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ );
+}
+
+export { TagChip };
diff --git a/skyvern-frontend/src/routes/workflows/components/tagging/TagChipList.tsx b/skyvern-frontend/src/routes/workflows/components/tagging/TagChipList.tsx
new file mode 100644
index 000000000..8adaa077c
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/components/tagging/TagChipList.tsx
@@ -0,0 +1,70 @@
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipProvider,
+ TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { badgeVariants } from "@/components/ui/badge-variants";
+import { cn } from "@/util/utils";
+import { TagChip } from "./TagChip";
+
+type Props = {
+ tags: Record<string, string>;
+ // Map (not a plain object) so lookups by user-controlled tag keys can't hit
+ // inherited Object prototype members (e.g. a key named "constructor").
+ descriptions?: Map<string, string | null>;
+ maxVisible?: number;
+ className?: string;
+};
+
+// Generic list of tag chips with a "+N" overflow affordance. Sorts by key for
+// stable ordering across renders. Reusable for any key->value tag map.
+function TagChipList({ tags, descriptions, maxVisible = 3, className }: Props) {
+ const entries = Object.entries(tags).sort(([a], [b]) => a.localeCompare(b));
+ if (entries.length === 0) {
+ return null;
+ }
+
+ const visible = entries.slice(0, maxVisible);
+ const hidden = entries.slice(maxVisible);
+
+ return (
+ <div className={cn("flex flex-wrap items-center gap-1", className)}>
+ {visible.map(([key, value]) => (
+ <TagChip
+ key={key}
+ tagKey={key}
+ value={value}
+ description={descriptions?.get(key)}
+ />
+ ))}
+ {hidden.length > 0 ? (
+ <TooltipProvider>
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <span
+ className={cn(
+ badgeVariants({ variant: "outline" }),
+ "cursor-default font-normal text-muted-foreground",
+ )}
+ >
+ +{hidden.length}
+ </span>
+ </TooltipTrigger>
+ <TooltipContent className="max-w-xs">
+ <div className="flex flex-col gap-1">
+ {hidden.map(([key, value]) => (
+ <span key={key} className="break-words">
+ <span className="font-medium">{key}</span>: {value}
+ </span>
+ ))}
+ </div>
+ </TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ ) : null}
+ </div>
+ );
+}
+
+export { TagChipList };
diff --git a/skyvern-frontend/src/routes/workflows/components/tagging/WorkflowTagEditor.tsx b/skyvern-frontend/src/routes/workflows/components/tagging/WorkflowTagEditor.tsx
new file mode 100644
index 000000000..1db0aee36
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/components/tagging/WorkflowTagEditor.tsx
@@ -0,0 +1,331 @@
+import * as React from "react";
+import {
+ ArrowLeftIcon,
+ PlusIcon,
+ ReloadIcon,
+ TokensIcon,
+} from "@radix-ui/react-icons";
+import { Button } from "@/components/ui/button";
+import {
+ Command,
+ CommandEmpty,
+ CommandGroup,
+ CommandInput,
+ CommandItem,
+ CommandList,
+} from "@/components/ui/command";
+import {
+ Popover,
+ PopoverContent,
+ PopoverTrigger,
+} from "@/components/ui/popover";
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipProvider,
+ TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { toast } from "@/components/ui/use-toast";
+import {
+ MAX_TAGS_PER_WORKFLOW,
+ validateTagKey,
+ validateTagValue,
+ type TagKey,
+} from "../../types/tagTypes";
+import {
+ useApplyWorkflowTagsMutation,
+ useDeleteWorkflowTagMutation,
+} from "../../hooks/useWorkflowTagMutations";
+import { TagChip } from "./TagChip";
+
+type Props = {
+ workflowPermanentId: string;
+ tags: Record<string, string>;
+ tagKeys: Array<TagKey>;
+ // key -> existing values observed on the page, so the value step can suggest
+ // existing values for the chosen key (the backend has no list-values
+ // endpoint). Free-text entry still works. A Map keeps lookups safe against
+ // tag keys like "constructor".
+ valueSuggestions?: Map<string, Array<string>>;
+};
+
+// Inline tag editor for a workflow row: add / overwrite / remove tags. Uses a
+// cmdk Command (key step -> value step) rather than native <datalist>, which is
+// unreliable inside a Radix popover; this mirrors WorkflowTagFilter so key and
+// value autosuggest behave the same. Adding a key that already exists overwrites
+// its value (backend set-wins) = the edit path.
+function WorkflowTagEditor({
+ workflowPermanentId,
+ tags,
+ tagKeys,
+ valueSuggestions,
+}: Props) {
+ const [open, setOpen] = React.useState(false);
+ const [selectedKey, setSelectedKey] = React.useState<string | null>(null);
+ const [query, setQuery] = React.useState("");
+ const [error, setError] = React.useState<string | null>(null);
+
+ const applyMutation = useApplyWorkflowTagsMutation();
+ const deleteMutation = useDeleteWorkflowTagMutation();
+ const isPending = applyMutation.isPending || deleteMutation.isPending;
+
+ const entries = Object.entries(tags).sort(([a], [b]) => a.localeCompare(b));
+
+ function resetForm() {
+ setSelectedKey(null);
+ setQuery("");
+ setError(null);
+ }
+
+ React.useEffect(() => {
+ // Inline the resets (rather than calling resetForm) so the effect's only
+ // dependency is `open`; setState identities are stable.
+ if (!open) {
+ setSelectedKey(null);
+ setQuery("");
+ setError(null);
+ }
+ }, [open]);
+
+ function applyTag(key: string, value: string) {
+ // A write is in flight; ignore further selects so quick double Enter/click
+ // can't queue racing POSTs whose arrival order would decide the final tag
+ // (backend is set-wins).
+ if (isPending) {
+ return;
+ }
+ const trimmedKey = key.trim();
+ const trimmedValue = value.trim();
+
+ const keyError = validateTagKey(trimmedKey);
+ if (keyError) {
+ setError(keyError);
+ return;
+ }
+ const valueError = validateTagValue(trimmedValue);
+ if (valueError) {
+ setError(valueError);
+ return;
+ }
+ // Own-key check: `key in tags` would treat inherited names like
+ // "constructor"/"toString" (valid backend tag keys) as already present.
+ const hasKey = Object.prototype.hasOwnProperty.call(tags, trimmedKey);
+ const previousValue = hasKey ? tags[trimmedKey] : undefined;
+ if (!hasKey && Object.keys(tags).length >= MAX_TAGS_PER_WORKFLOW) {
+ setError(`A workflow can have at most ${MAX_TAGS_PER_WORKFLOW} tags.`);
+ return;
+ }
+ // Same key, different value: the backend overwrites (set-wins); proceed but
+ // tell the user it replaced the existing tag.
+ const isOverwrite =
+ previousValue !== undefined && previousValue !== trimmedValue;
+
+ applyMutation.mutate(
+ { workflowPermanentId, data: { tags: { [trimmedKey]: trimmedValue } } },
+ {
+ onSuccess: () => {
+ resetForm();
+ if (isOverwrite) {
+ toast({
+ title: "Tag overwritten",
+ description: `“${trimmedKey}” changed from “${previousValue}” to “${trimmedValue}”.`,
+ });
+ }
+ },
+ },
+ );
+ }
+
+ function handleRemove(key: string) {
+ if (isPending) {
+ return;
+ }
+ deleteMutation.mutate({ workflowPermanentId, key });
+ }
+
+ const normalizedQuery = query.trim().toLowerCase();
+ const trimmedQuery = query.trim();
+
+ // Rank an exact (case-insensitive) match first so cmdk highlights it by
+ // default — plain Enter then commits the exact typed text, while arrow+Enter
+ // still selects any other highlighted suggestion (sort is stable otherwise).
+ const exactFirst = (a: string, b: string) =>
+ (a.toLowerCase() === normalizedQuery ? 0 : 1) -
+ (b.toLowerCase() === normalizedQuery ? 0 : 1);
+
+ const filteredKeys = tagKeys
+ .filter((tagKey) => tagKey.key.toLowerCase().includes(normalizedQuery))
+ .sort((a, b) => exactFirst(a.key, b.key));
+ const showUseKey =
+ trimmedQuery.length > 0 && !tagKeys.some((tk) => tk.key === trimmedQuery);
+
+ const suggestionsForKey = selectedKey
+ ? (valueSuggestions?.get(selectedKey) ?? [])
+ : [];
+ const filteredValues = suggestionsForKey
+ .filter((value) => value.toLowerCase().includes(normalizedQuery))
+ .sort(exactFirst);
+ const showAddValue =
+ trimmedQuery.length > 0 && !suggestionsForKey.includes(trimmedQuery);
+
+ return (
+ <Popover open={open} onOpenChange={setOpen}>
+ <TooltipProvider>
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <PopoverTrigger asChild>
+ <Button
+ size="icon"
+ variant="ghost"
+ aria-label="Edit tags"
+ className="text-muted-foreground hover:text-foreground"
+ >
+ <TokensIcon className="h-4 w-4" />
+ </Button>
+ </PopoverTrigger>
+ </TooltipTrigger>
+ <TooltipContent>Edit Tags</TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ <PopoverContent className="w-80 p-0" align="end">
+ <div className="space-y-2 p-3">
+ <div className="text-sm font-medium">Tags</div>
+ {entries.length > 0 ? (
+ <div className="flex flex-wrap gap-1">
+ {entries.map(([key, value]) => (
+ <TagChip
+ key={key}
+ tagKey={key}
+ value={value}
+ onRemove={() => handleRemove(key)}
+ />
+ ))}
+ </div>
+ ) : (
+ <div className="text-xs text-muted-foreground">No tags yet.</div>
+ )}
+ {error ? (
+ <div className="text-xs text-destructive">{error}</div>
+ ) : null}
+ </div>
+ <Command shouldFilter={false}>
+ {selectedKey === null ? (
+ <>
+ <CommandInput
+ placeholder="Tag key…"
+ value={query}
+ onValueChange={(value) => {
+ setQuery(value);
+ setError(null);
+ }}
+ />
+ <CommandList>
+ <CommandEmpty>Type a key to add.</CommandEmpty>
+ {showUseKey ? (
+ <CommandGroup>
+ <CommandItem
+ value={`__use__,${trimmedQuery}`}
+ onSelect={() => {
+ setSelectedKey(trimmedQuery);
+ setQuery("");
+ }}
+ >
+ <PlusIcon className="mr-2 h-4 w-4" />
+ Use “{trimmedQuery}”
+ </CommandItem>
+ </CommandGroup>
+ ) : null}
+ {filteredKeys.length > 0 ? (
+ <CommandGroup heading="Existing keys">
+ {filteredKeys.map((tagKey) => (
+ <CommandItem
+ key={tagKey.key}
+ value={tagKey.key}
+ onSelect={() => {
+ setSelectedKey(tagKey.key);
+ setQuery("");
+ }}
+ >
+ <div className="flex min-w-0 flex-col">
+ <span className="truncate">{tagKey.key}</span>
+ {tagKey.description ? (
+ <span className="truncate text-xs text-muted-foreground">
+ {tagKey.description}
+ </span>
+ ) : null}
+ </div>
+ </CommandItem>
+ ))}
+ </CommandGroup>
+ ) : null}
+ </CommandList>
+ </>
+ ) : (
+ <>
+ <div className="flex items-center gap-1 border-b px-2 py-1.5">
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 shrink-0"
+ onClick={() => {
+ setSelectedKey(null);
+ setQuery("");
+ }}
+ >
+ <ArrowLeftIcon className="h-4 w-4" />
+ </Button>
+ <span className="truncate text-sm font-medium">
+ {selectedKey}
+ </span>
+ </div>
+ <CommandInput
+ placeholder="Value…"
+ value={query}
+ onValueChange={(value) => {
+ setQuery(value);
+ setError(null);
+ }}
+ />
+ <CommandList>
+ <CommandEmpty>Type a value to add.</CommandEmpty>
+ {showAddValue ? (
+ <CommandGroup>
+ {/* cmdk item values must be unique. The comma can't appear
+ in a valid tag value, so this sentinel can never collide
+ with a real suggestion's value. */}
+ <CommandItem
+ value={`__add__,${trimmedQuery}`}
+ onSelect={() => applyTag(selectedKey, trimmedQuery)}
+ >
+ {applyMutation.isPending ? (
+ <ReloadIcon className="mr-2 h-4 w-4 animate-spin" />
+ ) : (
+ <PlusIcon className="mr-2 h-4 w-4" />
+ )}
+ Add “{selectedKey}: {trimmedQuery}”
+ </CommandItem>
+ </CommandGroup>
+ ) : null}
+ {filteredValues.length > 0 ? (
+ <CommandGroup heading="Existing values">
+ {filteredValues.map((value) => (
+ <CommandItem
+ key={value}
+ value={value}
+ onSelect={() => applyTag(selectedKey, value)}
+ >
+ {value}
+ </CommandItem>
+ ))}
+ </CommandGroup>
+ ) : null}
+ </CommandList>
+ </>
+ )}
+ </Command>
+ </PopoverContent>
+ </Popover>
+ );
+}
+
+export { WorkflowTagEditor };
diff --git a/skyvern-frontend/src/routes/workflows/components/tagging/WorkflowTagFilter.tsx b/skyvern-frontend/src/routes/workflows/components/tagging/WorkflowTagFilter.tsx
new file mode 100644
index 000000000..9b78c15fb
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/components/tagging/WorkflowTagFilter.tsx
@@ -0,0 +1,419 @@
+import * as React from "react";
+import {
+ ArrowLeftIcon,
+ CheckIcon,
+ PlusIcon,
+ ReloadIcon,
+ TokensIcon,
+ TrashIcon,
+} from "@radix-ui/react-icons";
+import { Button } from "@/components/ui/button";
+import {
+ Command,
+ CommandEmpty,
+ CommandGroup,
+ CommandInput,
+ CommandItem,
+ CommandList,
+} from "@/components/ui/command";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import {
+ Popover,
+ PopoverContent,
+ PopoverTrigger,
+} from "@/components/ui/popover";
+import { cn } from "@/util/utils";
+import { copyText } from "@/util/copyText";
+import { toast } from "@/components/ui/use-toast";
+import type { TagFilterPair, TagKey } from "../../types/tagTypes";
+import { useDeleteTagKeyMutation } from "../../hooks/useWorkflowTagMutations";
+import { TagChip } from "./TagChip";
+
+type Props = {
+ tagKeys: Array<TagKey>;
+ value: Array<TagFilterPair>;
+ onChange: (pairs: Array<TagFilterPair>) => void;
+ // key -> distinct values observed on the current page; used to suggest values
+ // since the backend has no "list values for key" endpoint. Free-text entry
+ // always works regardless. A Map (not a plain object) so a tag key like
+ // "constructor" can't resolve to an inherited Object prototype member.
+ valueSuggestions?: Map<string, Array<string>>;
+};
+
+// Tag filter pill for the workflows-list page. Collects `key:value` pairs; the
+// backend (GET /workflows?tags=) ANDs across distinct keys and ORs within a
+// key, so adding several values for one key is the OR-within-key path.
+function WorkflowTagFilter({
+ tagKeys,
+ value,
+ onChange,
+ valueSuggestions,
+}: Props) {
+ const [open, setOpen] = React.useState(false);
+ const [selectedKey, setSelectedKey] = React.useState<string | null>(null);
+ const [query, setQuery] = React.useState("");
+ const [keyToDelete, setKeyToDelete] = React.useState<TagKey | null>(null);
+ const deleteKeyMutation = useDeleteTagKeyMutation();
+
+ React.useEffect(() => {
+ if (!open) {
+ setSelectedKey(null);
+ setQuery("");
+ }
+ }, [open]);
+
+ function addPair(key: string, rawValue: string) {
+ const trimmedKey = key.trim();
+ const trimmedValue = rawValue.trim();
+ // Comma is the pair separator in the serialized `tags` param, so a value
+ // containing one cannot round-trip (it would split into a different
+ // filter). Backend filter values can't contain commas, so reject here.
+ if (!trimmedKey || !trimmedValue || trimmedValue.includes(",")) {
+ return;
+ }
+ const exists = value.some(
+ (pair) => pair.key === trimmedKey && pair.value === trimmedValue,
+ );
+ if (exists) {
+ return;
+ }
+ onChange([...value, { key: trimmedKey, value: trimmedValue }]);
+ }
+
+ function removePair(target: TagFilterPair) {
+ onChange(
+ value.filter(
+ (pair) => !(pair.key === target.key && pair.value === target.value),
+ ),
+ );
+ }
+
+ // Registered keys, to flag active filters whose key isn't in the org's
+ // registry (e.g. a typo'd / hand-edited URL).
+ const knownKeys = React.useMemo(
+ () => new Set(tagKeys.map((tagKey) => tagKey.key)),
+ [tagKeys],
+ );
+
+ // Stable key-then-value order so same-key pairs sit together and the "AND"
+ // separators land between distinct keys.
+ const sortedValue = React.useMemo(
+ () =>
+ [...value].sort(
+ (a, b) => a.key.localeCompare(b.key) || a.value.localeCompare(b.value),
+ ),
+ [value],
+ );
+
+ function copyFilterUrl() {
+ // copyText handles the secure-context navigator.clipboard path plus an
+ // execCommand fallback, and resolves false on failure (no silent no-op).
+ copyText(window.location.href).then((ok) => {
+ toast(
+ ok
+ ? { title: "Filter link copied" }
+ : { variant: "destructive", title: "Couldn't copy link" },
+ );
+ });
+ }
+
+ const normalizedQuery = query.trim().toLowerCase();
+
+ const filteredKeys = tagKeys.filter((tagKey) =>
+ tagKey.key.toLowerCase().includes(normalizedQuery),
+ );
+
+ const suggestionsForKey = selectedKey
+ ? (valueSuggestions?.get(selectedKey) ?? [])
+ : [];
+ // Drop unselectable comma-containing values (they can't be applied as a
+ // filter) so the suggestion list never dangles a no-op item.
+ const filteredValues = suggestionsForKey.filter(
+ (suggestion) =>
+ !suggestion.includes(",") &&
+ suggestion.toLowerCase().includes(normalizedQuery),
+ );
+ const trimmedQuery = query.trim();
+ const showAddOption =
+ trimmedQuery.length > 0 &&
+ !trimmedQuery.includes(",") &&
+ !suggestionsForKey.includes(trimmedQuery);
+
+ return (
+ <>
+ <Popover open={open} onOpenChange={setOpen}>
+ <PopoverTrigger asChild>
+ <Button variant="outline" size="sm" className="gap-2">
+ <TokensIcon className="h-4 w-4" />
+ Tags
+ {value.length > 0 ? (
+ <span className="flex h-5 min-w-5 items-center justify-center rounded bg-primary px-1 text-xs text-primary-foreground">
+ {value.length}
+ </span>
+ ) : null}
+ </Button>
+ </PopoverTrigger>
+ <PopoverContent className="w-72 p-0" align="start">
+ {value.length > 0 ? (
+ <div className="flex flex-col gap-2 border-b p-3">
+ <div className="flex items-center justify-between">
+ <span className="text-xs text-muted-foreground">
+ Active filters
+ </span>
+ <div className="flex items-center gap-2">
+ <button
+ type="button"
+ className="text-xs text-blue-500 hover:underline"
+ onClick={copyFilterUrl}
+ >
+ Copy link
+ </button>
+ <button
+ type="button"
+ className="text-xs text-blue-500 hover:underline"
+ onClick={() => onChange([])}
+ >
+ Clear all
+ </button>
+ </div>
+ </div>
+ <div className="flex flex-wrap items-center gap-1">
+ {sortedValue.map((pair, index) => {
+ const previous =
+ index > 0 ? sortedValue[index - 1] : undefined;
+ // Different key from the previous chip → AND; same key →
+ // adjacent (OR within a key).
+ const startsNewKey =
+ previous !== undefined && previous.key !== pair.key;
+ const unknownKey = !knownKeys.has(pair.key);
+ return (
+ <React.Fragment key={`${pair.key}:${pair.value}`}>
+ {startsNewKey ? (
+ <span className="px-0.5 text-[10px] font-semibold uppercase text-muted-foreground">
+ and
+ </span>
+ ) : null}
+ <TagChip
+ tagKey={pair.key}
+ value={pair.value}
+ description={
+ unknownKey
+ ? `"${pair.key}" isn't a registered tag key in this org.`
+ : undefined
+ }
+ className={unknownKey ? "border-warning" : undefined}
+ onRemove={() => removePair(pair)}
+ />
+ </React.Fragment>
+ );
+ })}
+ </div>
+ </div>
+ ) : null}
+ <Command shouldFilter={false}>
+ {selectedKey === null ? (
+ <>
+ <CommandInput
+ placeholder="Filter by tag key…"
+ value={query}
+ onValueChange={setQuery}
+ />
+ <CommandList>
+ <CommandEmpty>No tag keys found.</CommandEmpty>
+ <CommandGroup>
+ {filteredKeys.map((tagKey) => (
+ <CommandItem
+ key={tagKey.key}
+ value={tagKey.key}
+ className="justify-between gap-2"
+ onSelect={() => {
+ setSelectedKey(tagKey.key);
+ setQuery("");
+ }}
+ >
+ <div className="flex min-w-0 flex-col">
+ <span className="truncate">{tagKey.key}</span>
+ {tagKey.description ? (
+ <span className="truncate text-xs text-muted-foreground">
+ {tagKey.description}
+ </span>
+ ) : null}
+ </div>
+ <div className="flex shrink-0 items-center gap-1.5">
+ {tagKey.workflow_count > 0 ? (
+ <span className="text-xs text-muted-foreground">
+ {tagKey.workflow_count}
+ </span>
+ ) : null}
+ <button
+ type="button"
+ aria-label={`Delete tag key ${tagKey.key}`}
+ className="rounded-sm p-1 text-muted-foreground hover:text-destructive"
+ onClick={(event) => {
+ // Stop cmdk from treating this as selecting the key.
+ event.preventDefault();
+ event.stopPropagation();
+ setKeyToDelete(tagKey);
+ }}
+ >
+ <TrashIcon className="h-3.5 w-3.5" />
+ </button>
+ </div>
+ </CommandItem>
+ ))}
+ </CommandGroup>
+ </CommandList>
+ </>
+ ) : (
+ <>
+ <div className="flex items-center gap-1 border-b px-2 py-1.5">
+ <Button
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 shrink-0"
+ onClick={() => {
+ setSelectedKey(null);
+ setQuery("");
+ }}
+ >
+ <ArrowLeftIcon className="h-4 w-4" />
+ </Button>
+ <span className="truncate text-sm font-medium">
+ {selectedKey}
+ </span>
+ </div>
+ <CommandInput
+ placeholder="Add a value…"
+ value={query}
+ onValueChange={setQuery}
+ onKeyDown={(event) => {
+ if (event.key === "Enter" && trimmedQuery.length > 0) {
+ event.preventDefault();
+ addPair(selectedKey, trimmedQuery);
+ setQuery("");
+ }
+ }}
+ />
+ <CommandList>
+ {filteredValues.length === 0 && !showAddOption ? (
+ <CommandEmpty>Type a value to filter.</CommandEmpty>
+ ) : null}
+ {showAddOption ? (
+ <CommandGroup>
+ <CommandItem
+ value={`__add__:${trimmedQuery}`}
+ onSelect={() => {
+ addPair(selectedKey, trimmedQuery);
+ setQuery("");
+ }}
+ >
+ <PlusIcon className="mr-2 h-4 w-4" />
+ Add “{trimmedQuery}”
+ </CommandItem>
+ </CommandGroup>
+ ) : null}
+ {filteredValues.length > 0 ? (
+ <CommandGroup heading="Suggestions">
+ {filteredValues.map((suggestion) => {
+ const checked = value.some(
+ (pair) =>
+ pair.key === selectedKey &&
+ pair.value === suggestion,
+ );
+ return (
+ <CommandItem
+ key={suggestion}
+ value={suggestion}
+ onSelect={() => {
+ if (checked) {
+ removePair({
+ key: selectedKey,
+ value: suggestion,
+ });
+ } else {
+ addPair(selectedKey, suggestion);
+ }
+ }}
+ >
+ <CheckIcon
+ className={cn(
+ "mr-2 h-4 w-4",
+ checked ? "opacity-100" : "opacity-0",
+ )}
+ />
+ {suggestion}
+ </CommandItem>
+ );
+ })}
+ </CommandGroup>
+ ) : null}
+ </CommandList>
+ </>
+ )}
+ </Command>
+ </PopoverContent>
+ </Popover>
+ <Dialog
+ open={keyToDelete !== null}
+ onOpenChange={(next) => {
+ if (!next && !deleteKeyMutation.isPending) {
+ setKeyToDelete(null);
+ }
+ }}
+ >
+ <DialogContent className="sm:max-w-md">
+ <DialogHeader>
+ <DialogTitle>Delete tag “{keyToDelete?.key}”?</DialogTitle>
+ <DialogDescription>
+ This removes it from {keyToDelete?.workflow_count ?? 0} workflow
+ {keyToDelete?.workflow_count === 1 ? "" : "s"} and from the tag
+ list. This can’t be undone.
+ </DialogDescription>
+ </DialogHeader>
+ <DialogFooter>
+ <Button
+ variant="outline"
+ onClick={() => setKeyToDelete(null)}
+ disabled={deleteKeyMutation.isPending}
+ >
+ Cancel
+ </Button>
+ <Button
+ variant="destructive"
+ className="gap-2"
+ disabled={deleteKeyMutation.isPending}
+ onClick={() => {
+ if (!keyToDelete) {
+ return;
+ }
+ const deletedKey = keyToDelete.key;
+ deleteKeyMutation.mutate(deletedKey, {
+ onSuccess: () => {
+ // Drop any active filter on the now-deleted key, else the
+ // list refetches with a stale ?tags= and shows empty.
+ onChange(value.filter((pair) => pair.key !== deletedKey));
+ setKeyToDelete(null);
+ },
+ });
+ }}
+ >
+ {deleteKeyMutation.isPending ? (
+ <ReloadIcon className="h-4 w-4 animate-spin" />
+ ) : null}
+ Delete
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ </>
+ );
+}
+
+export { WorkflowTagFilter };
diff --git a/skyvern-frontend/src/routes/workflows/hooks/useTagKeysQuery.ts b/skyvern-frontend/src/routes/workflows/hooks/useTagKeysQuery.ts
new file mode 100644
index 000000000..c68575701
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/hooks/useTagKeysQuery.ts
@@ -0,0 +1,20 @@
+import { getClient } from "@/api/AxiosClient";
+import { useCredentialGetter } from "@/hooks/useCredentialGetter";
+import { useQuery } from "@tanstack/react-query";
+import type { TagKey } from "../types/tagTypes";
+
+function useTagKeysQuery() {
+ const credentialGetter = useCredentialGetter();
+
+ return useQuery({
+ queryKey: ["tag-keys"],
+ queryFn: async () => {
+ const client = await getClient(credentialGetter);
+ return client
+ .get<Array<TagKey>>("/tag-keys")
+ .then((response) => response.data);
+ },
+ });
+}
+
+export { useTagKeysQuery };
diff --git a/skyvern-frontend/src/routes/workflows/hooks/useWorkflowTagMutations.ts b/skyvern-frontend/src/routes/workflows/hooks/useWorkflowTagMutations.ts
new file mode 100644
index 000000000..437e34a07
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/hooks/useWorkflowTagMutations.ts
@@ -0,0 +1,160 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { isAxiosError } from "axios";
+import { useCredentialGetter } from "@/hooks/useCredentialGetter";
+import { getClient } from "@/api/AxiosClient";
+import { toast } from "@/components/ui/use-toast";
+import type { TagApplyRequest, TagKey, TagsResponse } from "../types/tagTypes";
+
+// Tag writes surface validation/conflict reasons in the FastAPI `detail`
+// string (422 cap/regex, 409 concurrent write), so prefer it over the generic
+// axios message.
+function tagErrorMessage(error: unknown): string {
+ if (isAxiosError(error)) {
+ const detail = error.response?.data?.detail;
+ if (typeof detail === "string") {
+ return detail;
+ }
+ }
+ return error instanceof Error ? error.message : "Unknown error";
+}
+
+function useApplyWorkflowTagsMutation() {
+ const credentialGetter = useCredentialGetter();
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async ({
+ workflowPermanentId,
+ data,
+ }: {
+ workflowPermanentId: string;
+ data: TagApplyRequest;
+ }) => {
+ const client = await getClient(credentialGetter);
+ return client
+ .post<TagsResponse>(`/workflows/${workflowPermanentId}/tags`, data)
+ .then((response) => response.data);
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ["workflow-tags"] });
+ // A first-time key registers a new tag-key row, so refresh the registry.
+ queryClient.invalidateQueries({ queryKey: ["tag-keys"] });
+ // The workflows list is filterable by tags, so a changed tag can change
+ // which rows match the active ?tags= filter.
+ queryClient.invalidateQueries({ queryKey: ["workflows"] });
+ },
+ onError: (error: unknown) => {
+ toast({
+ variant: "destructive",
+ title: "Failed to update tags",
+ description: tagErrorMessage(error),
+ });
+ },
+ });
+}
+
+function useDeleteWorkflowTagMutation() {
+ const credentialGetter = useCredentialGetter();
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async ({
+ workflowPermanentId,
+ key,
+ }: {
+ workflowPermanentId: string;
+ key: string;
+ }) => {
+ const client = await getClient(credentialGetter);
+ return client
+ .delete<TagsResponse>(
+ `/workflows/${workflowPermanentId}/tags/${encodeURIComponent(key)}`,
+ )
+ .then((response) => response.data);
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ["workflow-tags"] });
+ // Removing a tag decrements the key's workflow_count (and a last-remove
+ // drops it to 0), so refresh the registry that feeds the filter dropdown.
+ queryClient.invalidateQueries({ queryKey: ["tag-keys"] });
+ // A removed tag can drop the row out of the active ?tags= filter.
+ queryClient.invalidateQueries({ queryKey: ["workflows"] });
+ },
+ onError: (error: unknown) => {
+ toast({
+ variant: "destructive",
+ title: "Failed to delete tag",
+ description: tagErrorMessage(error),
+ });
+ },
+ });
+}
+
+// Part of the tag-key mutation surface (SKY-10660). Not yet wired to a UI —
+// the tag-key description editor is a queued follow-up (SKY-10661 optional) —
+// but exported so that surface can consume it without re-deriving the hook.
+function useUpdateTagKeyMutation() {
+ const credentialGetter = useCredentialGetter();
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async ({
+ key,
+ description,
+ }: {
+ key: string;
+ description: string | null;
+ }) => {
+ const client = await getClient(credentialGetter);
+ return client
+ .patch<TagKey>(`/tag-keys/${encodeURIComponent(key)}`, { description })
+ .then((response) => response.data);
+ },
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: ["tag-keys"] });
+ },
+ onError: (error: unknown) => {
+ toast({
+ variant: "destructive",
+ title: "Failed to update tag key",
+ description: tagErrorMessage(error),
+ });
+ },
+ });
+}
+
+function useDeleteTagKeyMutation() {
+ const credentialGetter = useCredentialGetter();
+ const queryClient = useQueryClient();
+
+ return useMutation({
+ mutationFn: async (key: string) => {
+ const client = await getClient(credentialGetter);
+ return client
+ .delete(`/tag-keys/${encodeURIComponent(key)}`)
+ .then((response) => response.data);
+ },
+ onSuccess: () => {
+ // Cascade delete drops the key from the registry AND removes the tag from
+ // every workflow, so refresh the registry, batch tags, and the (tag-
+ // filterable) workflows list.
+ queryClient.invalidateQueries({ queryKey: ["tag-keys"] });
+ queryClient.invalidateQueries({ queryKey: ["workflow-tags"] });
+ queryClient.invalidateQueries({ queryKey: ["workflows"] });
+ },
+ onError: (error: unknown) => {
+ toast({
+ variant: "destructive",
+ title: "Failed to delete tag",
+ description: tagErrorMessage(error),
+ });
+ },
+ });
+}
+
+export {
+ useApplyWorkflowTagsMutation,
+ useDeleteWorkflowTagMutation,
+ useUpdateTagKeyMutation,
+ useDeleteTagKeyMutation,
+};
diff --git a/skyvern-frontend/src/routes/workflows/hooks/useWorkflowTagsBatchQuery.ts b/skyvern-frontend/src/routes/workflows/hooks/useWorkflowTagsBatchQuery.ts
new file mode 100644
index 000000000..f6d70993b
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/hooks/useWorkflowTagsBatchQuery.ts
@@ -0,0 +1,47 @@
+import { getClient } from "@/api/AxiosClient";
+import { useCredentialGetter } from "@/hooks/useCredentialGetter";
+import { useQuery } from "@tanstack/react-query";
+import type { WorkflowTagsBatchResponse } from "../types/tagTypes";
+
+// The backend batch endpoint rejects more than this many IDs per request
+// (_BATCH_TAGS_MAX_WPIDS). The workflows list page size is unbounded via the
+// URL, so chunk rather than slice to avoid silently dropping tags for rows
+// beyond the limit. The common case (page size <= 50) is a single request.
+const BATCH_TAGS_MAX_WPIDS = 200;
+
+// One batch fetch for all visible workflows, avoiding an N+1 of per-row tag
+// fetches on the workflows-list page. Ids are sorted so the query key is
+// order-independent and two renders with the same set share a cache entry.
+function useWorkflowTagsBatchQuery(workflowPermanentIds: Array<string>) {
+ const credentialGetter = useCredentialGetter();
+ const sortedIds = [...workflowPermanentIds].sort();
+
+ return useQuery({
+ queryKey: ["workflow-tags", "batch", sortedIds],
+ enabled: sortedIds.length > 0,
+ queryFn: async () => {
+ const client = await getClient(credentialGetter);
+ const chunks: Array<Array<string>> = [];
+ for (let i = 0; i < sortedIds.length; i += BATCH_TAGS_MAX_WPIDS) {
+ chunks.push(sortedIds.slice(i, i + BATCH_TAGS_MAX_WPIDS));
+ }
+ const responses = await Promise.all(
+ chunks.map((ids) => {
+ const params = new URLSearchParams();
+ params.append("workflow_permanent_ids", ids.join(","));
+ return client
+ .get<WorkflowTagsBatchResponse>("/workflow-tags", { params })
+ .then((response) => response.data.workflow_tags);
+ }),
+ );
+ // Chunks are disjoint slices, so wpid keys never collide on merge.
+ const merged: Record<string, Record<string, string>> = {};
+ for (const response of responses) {
+ Object.assign(merged, response);
+ }
+ return merged;
+ },
+ });
+}
+
+export { useWorkflowTagsBatchQuery };
diff --git a/skyvern-frontend/src/routes/workflows/types/tagTypes.ts b/skyvern-frontend/src/routes/workflows/types/tagTypes.ts
new file mode 100644
index 000000000..de62d2556
--- /dev/null
+++ b/skyvern-frontend/src/routes/workflows/types/tagTypes.ts
@@ -0,0 +1,121 @@
+export interface TagResponse {
+ value: string;
+ source: string;
+ set_at: string;
+ set_by: string;
+}
+
+export interface TagsResponse {
+ workflow_permanent_id: string;
+ tags: Record<string, TagResponse>;
+}
+
+export interface TagKey {
+ key: string;
+ description: string | null;
+ // Number of workflows currently carrying this key (from GET /tag-keys).
+ workflow_count: number;
+}
+
+// Batch endpoint returns a flat key->value map per workflow (no per-tag
+// metadata). Descriptions come from the tag-key registry (GET /tag-keys).
+export interface WorkflowTagsBatchResponse {
+ workflow_tags: Record<string, Record<string, string>>;
+}
+
+// Body for POST /workflows/{wpid}/tags. `tags` is set (overwrite, set-wins);
+// `tags_to_delete` soft-deletes keys. Both optional; both empty is a no-op.
+export interface TagApplyRequest {
+ tags?: Record<string, string>;
+ tags_to_delete?: Array<string>;
+}
+
+// Mirror skyvern/forge/sdk/workflow/models/validators.py so the editor rejects
+// the same inputs the backend would 422 on.
+export const TAG_KEY_REGEX = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+export const RESERVED_TAG_KEY_PREFIX = "skyvern.";
+export const MAX_TAGS_PER_WORKFLOW = 20;
+export const TAG_KEY_MAX_LENGTH = 64;
+export const TAG_VALUE_MAX_LENGTH = 256;
+
+export function validateTagKey(key: string): string | null {
+ const trimmed = key.trim();
+ if (!trimmed) {
+ return "Key is required.";
+ }
+ if (trimmed.length > TAG_KEY_MAX_LENGTH) {
+ return `Key must be at most ${TAG_KEY_MAX_LENGTH} characters.`;
+ }
+ if (trimmed.startsWith(RESERVED_TAG_KEY_PREFIX)) {
+ return `Keys can't start with the reserved "${RESERVED_TAG_KEY_PREFIX}" prefix.`;
+ }
+ if (!TAG_KEY_REGEX.test(trimmed)) {
+ return "Use letters, digits, _ . or - (must start with a letter or digit).";
+ }
+ return null;
+}
+
+export function validateTagValue(value: string): string | null {
+ const trimmed = value.trim();
+ if (!trimmed) {
+ return "Value is required.";
+ }
+ if (trimmed.length > TAG_VALUE_MAX_LENGTH) {
+ return `Value must be at most ${TAG_VALUE_MAX_LENGTH} characters.`;
+ }
+ if (trimmed.includes(",")) {
+ return "Value can't contain a comma.";
+ }
+ return null;
+}
+
+export interface TagFilterPair {
+ key: string;
+ value: string;
+}
+
+// Parse the `?tags=key:value,key:value` URL param into pairs. Forgiving on
+// read (drops malformed/blank segments) so a hand-edited URL can't crash the
+// page; the backend GET /workflows filter is strict, so we only ever serialize
+// valid pairs back. Mirrors the backend's first-colon partition so values may
+// themselves contain colons. Duplicate pairs are collapsed.
+export function parseTagFilter(
+ raw: string | null | undefined,
+): TagFilterPair[] {
+ if (!raw) {
+ return [];
+ }
+ const pairs: TagFilterPair[] = [];
+ const seen = new Set<string>();
+ for (const segment of raw.split(",")) {
+ const separatorIndex = segment.indexOf(":");
+ if (separatorIndex <= 0) {
+ continue;
+ }
+ const key = segment.slice(0, separatorIndex).trim();
+ const value = segment.slice(separatorIndex + 1).trim();
+ if (!key || !value) {
+ continue;
+ }
+ const dedupeKey = `${key}:${value}`;
+ if (seen.has(dedupeKey)) {
+ continue;
+ }
+ seen.add(dedupeKey);
+ pairs.push({ key, value });
+ }
+ return pairs;
+}
+
+// Canonical serialization: pairs are sorted by key then value so that
+// semantically identical filters (the backend ANDs keys / ORs values, order
+// is irrelevant) produce one stable string. This keeps the URL and the React
+// Query key order-independent, so reordering can't cause a needless refetch.
+export function serializeTagFilter(pairs: TagFilterPair[]): string {
+ return [...pairs]
+ .sort(
+ (a, b) => a.key.localeCompare(b.key) || a.value.localeCompare(b.value),
+ )
+ .map((pair) => `${pair.key}:${pair.value}`)
+ .join(",");
+}
diff --git a/skyvern/forge/sdk/db/repositories/tags.py b/skyvern/forge/sdk/db/repositories/tags.py
index b5fa176c2..df008c16e 100644
--- a/skyvern/forge/sdk/db/repositories/tags.py
+++ b/skyvern/forge/sdk/db/repositories/tags.py
@@ -6,7 +6,7 @@ from dataclasses import dataclass
from datetime import datetime, timezone
import structlog
-from sqlalchemy import and_, select, text
+from sqlalchemy import and_, func, select, text
from sqlalchemy.dialects import postgresql, sqlite
from sqlalchemy.ext.asyncio import AsyncSession
@@ -341,3 +341,108 @@ class TagsRepository(BaseRepository):
await session.commit()
await session.refresh(row)
return row
+
+ @db_operation("count_active_workflows_per_key")
+ async def count_active_workflows_per_key(self, organization_id: str) -> dict[str, int]:
+ """Map of tag key -> number of workflows currently carrying it. The
+ partial UNIQUE guarantees one active SET per (workflow, key), so a plain
+ row count per key already equals the distinct-workflow count."""
+ async with self.Session() as session:
+ stmt = (
+ select(WorkflowTagEventModel.key, func.count(WorkflowTagEventModel.tag_event_id))
+ .where(
+ and_(
+ WorkflowTagEventModel.organization_id == organization_id,
+ WorkflowTagEventModel.superseded_at.is_(None),
+ WorkflowTagEventModel.event_type == TagEventType.SET.value,
+ WorkflowTagEventModel.deleted_at.is_(None),
+ )
+ )
+ .group_by(WorkflowTagEventModel.key)
+ )
+ rows = await session.execute(stmt)
+ return {key: count for key, count in rows.all()}
+
+ @db_operation("delete_tag_key")
+ async def delete_tag_key(
+ self,
+ organization_id: str,
+ key: str,
+ context: TagWriteContext,
+ ) -> int | None:
+ """Cascade-delete a tag key: write a DELETE event for every workflow that
+ currently has it, then soft-delete the registry row. Returns the number
+ of workflows the tag was removed from, or None when the key is not
+ registered (caller should 404). Idempotent: a second call returns None.
+
+ DELETE events don't match the SET-only partial UNIQUE, so superseding the
+ SET and inserting the DELETE in one transaction needs no flush ordering.
+
+ Accepted race (mirrors the soft-cap tolerance in apply_tag_changes): a
+ concurrent apply of the same key can insert a fresh active SET after this
+ method reads the active set, leaving that tag active while the registry
+ row is soft-deleted — i.e. a tag present on a workflow but absent from
+ /tag-keys. It is not data loss (the tag still resolves on the workflow)
+ and self-heals on the next apply (which re-registers the key via the
+ deleted_at IS NULL partial unique). Serializing delete-vs-SET would need
+ dialect-specific row/advisory locking, which is disproportionate for a
+ rare manual admin action.
+
+ Scale note: this loads the key's active SET rows into the session and
+ iterates in Python. Fine for realistic key fan-out (a key on at most a
+ few hundred workflows) and a one-off admin action; if a key ever spans
+ thousands of workflows, switch to a bulk UPDATE (supersede) + batched
+ INSERT for the DELETE events to avoid the ORM round-trip."""
+ now = datetime.now(timezone.utc)
+ async with self.Session() as session:
+ key_row = (
+ await session.execute(
+ select(TagKeyModel).where(
+ and_(
+ TagKeyModel.organization_id == organization_id,
+ TagKeyModel.key == key,
+ TagKeyModel.deleted_at.is_(None),
+ )
+ )
+ )
+ ).scalar_one_or_none()
+ if key_row is None:
+ return None
+
+ active_sets = (
+ (
+ await session.execute(
+ select(WorkflowTagEventModel).where(
+ and_(
+ WorkflowTagEventModel.organization_id == organization_id,
+ WorkflowTagEventModel.key == key,
+ WorkflowTagEventModel.superseded_at.is_(None),
+ WorkflowTagEventModel.event_type == TagEventType.SET.value,
+ WorkflowTagEventModel.deleted_at.is_(None),
+ )
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+
+ for existing in active_sets:
+ existing.superseded_at = now
+ session.add(
+ WorkflowTagEventModel(
+ workflow_permanent_id=existing.workflow_permanent_id,
+ organization_id=organization_id,
+ key=key,
+ value=None,
+ event_type=TagEventType.DELETE.value,
+ set_at=now,
+ set_by=context.caller_id,
+ source=context.source.value,
+ caller_type=context.caller_type.value if context.caller_type else None,
+ )
+ )
+
+ key_row.deleted_at = now
+ await session.commit()
+ return len(active_sets)
diff --git a/skyvern/forge/sdk/routes/agent_protocol.py b/skyvern/forge/sdk/routes/agent_protocol.py
index 96019eed0..74a831d8a 100644
--- a/skyvern/forge/sdk/routes/agent_protocol.py
+++ b/skyvern/forge/sdk/routes/agent_protocol.py
@@ -146,6 +146,7 @@ from skyvern.schemas.tags import (
TagHistoryItem,
TagHistoryResponse,
TagKey,
+ TagKeyDeleteResponse,
TagKeyUpdate,
TagResponse,
TagsResponse,
@@ -1755,8 +1756,10 @@ async def get_workflow_tag_history(
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]
+ organization_id = current_org.organization_id
+ rows = await app.DATABASE.tags.list_tag_keys(organization_id=organization_id)
+ counts = await app.DATABASE.tags.count_active_workflows_per_key(organization_id=organization_id)
+ return [TagKey(key=row.key, description=row.description, workflow_count=counts.get(row.key, 0)) for row in rows]
@legacy_base_router.patch("/tag-keys/{key}", response_model=TagKey, tags=["agent"], include_in_schema=False)
@@ -1781,16 +1784,59 @@ async def update_tag_key(
current_org: Organization = Depends(org_auth_service.get_current_org),
) -> TagKey:
_validate_path_key(key)
+ organization_id = current_org.organization_id
row = await app.DATABASE.tags.update_tag_key_description(
- organization_id=current_org.organization_id,
+ organization_id=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)
+ # Populate the real count so PATCH and GET /tag-keys agree (the ORM row
+ # has no count attribute, so model_validate would default it to 0).
+ counts = await app.DATABASE.tags.count_active_workflows_per_key(organization_id=organization_id)
+ return TagKey(key=row.key, description=row.description, workflow_count=counts.get(row.key, 0))
+
+
+@legacy_base_router.delete("/tag-keys/{key}", tags=["agent"], include_in_schema=False)
+@legacy_base_router.delete("/tag-keys/{key}/", include_in_schema=False)
+@base_router.delete(
+ "/tag-keys/{key}",
+ response_model=TagKeyDeleteResponse,
+ tags=["Workflow Tags"],
+ openapi_extra={"x-fern-sdk-method-name": "delete_tag_key"},
+ description="Delete a tag key from the organization registry and remove that tag from every workflow that "
+ "currently has it (cascade). Returns how many workflows the tag was removed from.",
+ summary="Delete tag key",
+ responses={
+ 200: {"description": "Successfully deleted tag key"},
+ 404: {"description": "Tag key not found"},
+ },
+)
+@base_router.delete("/tag-keys/{key}/", response_model=TagKeyDeleteResponse, include_in_schema=False)
+async def delete_tag_key(
+ key: str = Path(..., description="Tag key to delete", examples=["env"]),
+ caller: org_auth_service.CallerContext = Depends(org_auth_service.get_current_caller_context),
+) -> TagKeyDeleteResponse:
+ analytics.capture("skyvern-oss-tag-key-delete")
+ _validate_path_key(key)
+ context = TagWriteContext(
+ caller_id=caller.caller_id,
+ source=TagSource.MANUAL,
+ caller_type=caller.caller_type,
+ )
+ removed_count = await app.DATABASE.tags.delete_tag_key(
+ organization_id=caller.organization.organization_id,
+ key=key,
+ context=context,
+ )
+ if removed_count is None:
+ raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail=f"Tag key '{key}' not found")
+ return TagKeyDeleteResponse(key=key, removed_from_workflow_count=removed_count)
+# Keep in sync with BATCH_TAGS_MAX_WPIDS in the frontend
+# useWorkflowTagsBatchQuery hook, which chunks requests to this size.
_BATCH_TAGS_MAX_WPIDS = 200
diff --git a/skyvern/schemas/tags.py b/skyvern/schemas/tags.py
index 42df3fc74..8aabc1b6a 100644
--- a/skyvern/schemas/tags.py
+++ b/skyvern/schemas/tags.py
@@ -137,6 +137,16 @@ class TagKey(BaseModel):
key: str
description: str | None = None
+ # Number of workflows currently carrying this tag. Powers the dropdown count
+ # and the delete-key confirmation ("removes it from N workflows").
+ workflow_count: int = 0
+
+
+class TagKeyDeleteResponse(BaseModel):
+ """Response for ``DELETE /v1/tag-keys/{key}``."""
+
+ key: str
+ removed_from_workflow_count: int
class TagKeyUpdate(BaseModel):
diff --git a/tests/unit/test_tag_endpoints.py b/tests/unit/test_tag_endpoints.py
index 5bd2db25c..bd28d05c9 100644
--- a/tests/unit/test_tag_endpoints.py
+++ b/tests/unit/test_tag_endpoints.py
@@ -286,6 +286,45 @@ def test_patch_tag_key_description_too_long_returns_422(client: TestClient) -> N
assert resp.status_code == 422
+def test_list_tag_keys_includes_workflow_count(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ resp = client.get("/v1/tag-keys")
+ assert resp.status_code == 200
+ by_key = {row["key"]: row for row in resp.json()}
+ assert by_key["env"]["workflow_count"] == 1
+ assert by_key["team"]["workflow_count"] == 1
+
+
+# ----------------------------- DELETE /tag-keys/{key} --------------------------------
+
+
+def test_delete_tag_key_removes_from_registry_and_workflow(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod", "team": "growth"}})
+ resp = client.delete("/v1/tag-keys/env")
+
+ assert resp.status_code == 200
+ assert resp.json() == {"key": "env", "removed_from_workflow_count": 1}
+ assert [row["key"] for row in client.get("/v1/tag-keys").json()] == ["team"]
+ assert set(client.get(f"/v1/workflows/{WPID}/tags").json()["tags"].keys()) == {"team"}
+
+
+def test_delete_tag_key_404_when_unknown(client: TestClient) -> None:
+ resp = client.delete("/v1/tag-keys/never_registered")
+ assert resp.status_code == 404
+
+
+def test_delete_tag_key_reserved_prefix_returns_400(client: TestClient) -> None:
+ resp = client.delete("/v1/tag-keys/skyvern.system")
+ assert resp.status_code == 400
+
+
+def test_delete_tag_key_legacy_route_works(client: TestClient) -> None:
+ client.post(f"/v1/workflows/{WPID}/tags", json={"tags": {"env": "prod"}})
+ resp = client.delete("/api/v1/tag-keys/env")
+ assert resp.status_code == 200
+ assert resp.json()["removed_from_workflow_count"] == 1
+
+
# ----------------------------- Batch endpoints ---------------------------------------
diff --git a/tests/unit/test_tags_repository.py b/tests/unit/test_tags_repository.py
index 25feed683..ffa440005 100644
--- a/tests/unit/test_tags_repository.py
+++ b/tests/unit/test_tags_repository.py
@@ -506,3 +506,60 @@ async def test_apply_tag_changes_registers_new_key_when_absent(repo: TagsReposit
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"]
+
+
+async def test_count_active_workflows_per_key(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ await repo.apply_tag_changes("wpid_b", ORG_ID, sets={"env": "stg", "team": "core"}, deletes=set(), context=_ctx())
+
+ counts = await repo.count_active_workflows_per_key(ORG_ID)
+ assert counts == {"env": 2, "team": 1}
+
+
+async def test_count_active_workflows_per_key_ignores_deleted_tags(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={}, deletes={"env"}, context=_ctx())
+
+ assert await repo.count_active_workflows_per_key(ORG_ID) == {}
+
+
+async def test_delete_tag_key_cascades_across_workflows(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ await repo.apply_tag_changes("wpid_b", ORG_ID, sets={"env": "stg", "team": "core"}, deletes=set(), context=_ctx())
+
+ removed = await repo.delete_tag_key(ORG_ID, "env", _ctx())
+
+ assert removed == 2
+ # Tag gone from both workflows...
+ assert await repo.get_active_tags_for_workflow("wpid_a", ORG_ID) == {}
+ assert await repo.get_active_tags_for_workflow("wpid_b", ORG_ID) == {"team": "core"}
+ # ...and the key no longer appears in the active registry.
+ assert [row.key for row in await repo.list_tag_keys(ORG_ID)] == ["team"]
+
+
+async def test_delete_tag_key_unknown_returns_none(repo: TagsRepository) -> None:
+ assert await repo.delete_tag_key(ORG_ID, "never_seen", _ctx()) is None
+
+
+async def test_delete_tag_key_idempotent(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+
+ assert await repo.delete_tag_key(ORG_ID, "env", _ctx()) == 1
+ # Second call: key already soft-deleted, no active SETs left.
+ assert await repo.delete_tag_key(ORG_ID, "env", _ctx()) is None
+
+
+async def test_delete_tag_key_then_reapply_reregisters(repo: TagsRepository) -> None:
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "prod"}, deletes=set(), context=_ctx())
+ await repo.delete_tag_key(ORG_ID, "env", _ctx())
+
+ await repo.apply_tag_changes("wpid_a", ORG_ID, sets={"env": "dev"}, deletes=set(), context=_ctx())
+
+ assert await repo.get_active_tags_for_workflow("wpid_a", ORG_ID) == {"env": "dev"}
+ assert [row.key for row in await repo.list_tag_keys(ORG_ID)] == ["env"]