refactor(copilot): tighten subblock serialization helpers

Derive KbTagDefinitionSummary from the canonical TagDefinition instead of
restating its fields, make parseJsonArrayValue generic so callers drop their
`as T[]` casts, and unexport the three builders helpers that no longer have
consumers outside the module now that normalizeSubblockValue fronts them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: j15z

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/document-tag-entry/document-tag-entry.tsx

@@ -100,13 +100,13 @@ export function DocumentTagEntry({
   const currentValue = isPreview ? previewValue : storeValue
 
   const parseTags = (tagValue: unknown): DocumentTag[] =>
-    (parseJsonArrayValue(tagValue) as DocumentTag[]).map((t) => ({
+    parseJsonArrayValue<DocumentTag>(tagValue).map((t) => ({
       ...t,
       fieldType: t.fieldType || 'text',
       collapsed: t.collapsed ?? false,
     }))
 
-  const parsedTags = parseTags(currentValue || null)
+  const parsedTags = parseTags(currentValue)
   const tags: DocumentTag[] = parsedTags.length > 0 ? parsedTags : [createDefaultTag()]
   const isReadOnly = isPreview || disabled
 

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/knowledge-tag-filters/knowledge-tag-filters.tsx

@@ -102,15 +102,15 @@ export function KnowledgeTagFilters({
   })
 
   const parseFilters = (filterValue: unknown): TagFilter[] =>
-    (parseJsonArrayValue(filterValue) as TagFilter[]).map((f) => ({
+    parseJsonArrayValue<TagFilter>(filterValue).map((f) => ({
       ...f,
       fieldType: f.fieldType || 'text',
       operator: f.operator || 'eq',
       collapsed: f.collapsed ?? false,
     }))
 
   const currentValue = isPreview ? previewValue : storeValue
-  const parsedFilters = parseFilters(currentValue || null)
+  const parsedFilters = parseFilters(currentValue)
   const filters: TagFilter[] = parsedFilters.length > 0 ? parsedFilters : [createDefaultFilter()]
   const isReadOnly = isPreview || disabled
 

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/utils.ts

@@ -25,10 +25,13 @@ export function resolvePreviewContextValue(raw: unknown): unknown {
  * `edit_workflow` persisted them as raw arrays until it was fixed to re-serialize, so rows
  * written by older builds still hold an array. Both shapes are accepted on read.
  *
+ * The element type is asserted, not validated -- callers are responsible for defaulting any
+ * fields a malformed entry may be missing.
+ *
  * @param value - The stored sub-block value, of unknown shape
  * @returns The parsed array, or `[]` when the value is absent, unparseable, or not an array
  */
-export function parseJsonArrayValue(value: unknown): unknown[] {
+export function parseJsonArrayValue<T>(value: unknown): T[] {
   if (!value) return []
   let parsed: unknown = value
   if (typeof value === 'string') {
@@ -38,5 +41,5 @@ export function parseJsonArrayValue(value: unknown): unknown[] {
       return []
     }
   }
-  return Array.isArray(parsed) ? parsed : []
+  return Array.isArray(parsed) ? (parsed as T[]) : []
 }

apps/sim/lib/copilot/tools/server/workflow/edit-workflow/builders.ts

@@ -266,19 +266,14 @@ const ARRAY_WITH_ID_SUBBLOCK_TYPES = new Set([
  * Subblock keys whose UI components expect a JSON string, not a raw array.
  * After normalizeArrayWithIds returns an array, these must be re-stringified.
  */
-export const JSON_STRING_SUBBLOCK_KEYS = new Set([
-  'conditions',
-  'routes',
-  'tagFilters',
-  'documentTags',
-])
+const JSON_STRING_SUBBLOCK_KEYS = new Set(['conditions', 'routes', 'tagFilters', 'documentTags'])
 
 /**
  * Normalizes array subblock values by ensuring each item has a valid UUID.
  * The LLM may generate arbitrary IDs like "input-desc-001" or "row-1" which need
  * to be converted to proper UUIDs for consistency with UI-created items.
  */
-export function normalizeArrayWithIds(value: unknown): any[] {
+function normalizeArrayWithIds(value: unknown): any[] {
   let arr: any[]
 
   if (Array.isArray(value)) {
@@ -312,7 +307,7 @@ export function normalizeArrayWithIds(value: unknown): any[] {
 /**
  * Checks if a subblock key should have its array items normalized with UUIDs.
  */
-export function shouldNormalizeArrayIds(key: string): boolean {
+function shouldNormalizeArrayIds(key: string): boolean {
   return ARRAY_WITH_ID_SUBBLOCK_TYPES.has(key)
 }
 

apps/sim/lib/copilot/vfs/serializers.ts

@@ -1,5 +1,6 @@
 import { getCopilotToolDescription } from '@/lib/copilot/tools/descriptions'
 import { isHosted } from '@/lib/core/config/env-flags'
+import type { TagDefinition } from '@/lib/knowledge/types'
 import { isSubBlockHidden } from '@/lib/workflows/subblocks/visibility'
 import { isCustomBlockType } from '@/blocks/custom/build-config'
 import type { BlockConfig, SubBlockConfig } from '@/blocks/types'
@@ -84,11 +85,7 @@ export function serializeRecentExecutions(
 }
 
 /** A knowledge base tag definition, reduced to the fields the agent needs to bind a tag filter. */
-export interface KbTagDefinitionSummary {
-  displayName: string
-  tagSlot: string
-  fieldType: string
-}
+export type KbTagDefinitionSummary = Pick<TagDefinition, 'displayName' | 'tagSlot' | 'fieldType'>
 
 /**
  * Serialize knowledge base metadata for VFS meta.json.