chore: import upstream snapshot with attribution

apps/sim/lib/logs/execution/trace-spans/iteration-grouping.ts

@@ -0,0 +1,324 @@
+import { createLogger } from '@sim/logger'
+import type { TraceSpan } from '@/lib/logs/types'
+import { stripCloneSuffixes } from '@/executor/utils/subflow-utils'
+
+const logger = createLogger('IterationGrouping')
+
+/** Counter state for generating sequential container names. */
+interface ContainerNameCounters {
+  loopNumbers: Map<string, number>
+  parallelNumbers: Map<string, number>
+  loopCounter: number
+  parallelCounter: number
+}
+
+/**
+ * Builds a container-level TraceSpan (iteration wrapper or top-level container)
+ * from its source spans and resolved children.
+ */
+function buildContainerSpan(opts: {
+  id: string
+  name: string
+  type: string
+  sourceSpans: TraceSpan[]
+  children: TraceSpan[]
+}): TraceSpan {
+  const startTimes = opts.sourceSpans.map((s) => new Date(s.startTime).getTime())
+  const endTimes = opts.sourceSpans.map((s) => new Date(s.endTime).getTime())
+
+  // Guard against empty sourceSpans — Math.min/max of empty array returns ±Infinity
+  // which produces NaN durations and invalid Dates downstream.
+  const nowMs = Date.now()
+  const earliestStart = startTimes.length > 0 ? Math.min(...startTimes) : nowMs
+  const latestEnd = endTimes.length > 0 ? Math.max(...endTimes) : nowMs
+
+  const hasErrors = opts.sourceSpans.some((s) => s.status === 'error')
+  const allErrorsHandled =
+    hasErrors && opts.children.every((s) => s.status !== 'error' || s.errorHandled)
+
+  return {
+    id: opts.id,
+    name: opts.name,
+    type: opts.type,
+    duration: Math.max(0, latestEnd - earliestStart),
+    startTime: new Date(earliestStart).toISOString(),
+    endTime: new Date(latestEnd).toISOString(),
+    status: hasErrors ? 'error' : 'success',
+    ...(allErrorsHandled && { errorHandled: true }),
+    children: opts.children,
+  }
+}
+
+/**
+ * Resolves a container name from normal (non-iteration) spans or assigns a sequential number.
+ * Strips clone suffixes so all clones of the same container share one name/number.
+ */
+function resolveContainerName(
+  containerId: string,
+  containerType: 'parallel' | 'loop',
+  normalSpans: TraceSpan[],
+  counters: ContainerNameCounters
+): string {
+  const originalId = stripCloneSuffixes(containerId)
+
+  const matchingBlock = normalSpans.find(
+    (s) => s.blockId === originalId && s.type === containerType
+  )
+  if (matchingBlock?.name) return matchingBlock.name
+
+  if (containerType === 'parallel') {
+    if (!counters.parallelNumbers.has(originalId)) {
+      counters.parallelNumbers.set(originalId, counters.parallelCounter++)
+    }
+    return `Parallel ${counters.parallelNumbers.get(originalId)}`
+  }
+  if (!counters.loopNumbers.has(originalId)) {
+    counters.loopNumbers.set(originalId, counters.loopCounter++)
+  }
+  return `Loop ${counters.loopNumbers.get(originalId)}`
+}
+
+/**
+ * Classifies a span's immediate container ID and type from its metadata.
+ * Returns undefined for non-iteration spans.
+ */
+function classifySpanContainer(
+  span: TraceSpan
+): { containerId: string; containerType: 'parallel' | 'loop' } | undefined {
+  if (span.parallelId) {
+    return { containerId: span.parallelId, containerType: 'parallel' }
+  }
+  if (span.loopId) {
+    return { containerId: span.loopId, containerType: 'loop' }
+  }
+  if (span.blockId?.includes('_parallel_')) {
+    const match = span.blockId.match(/_parallel_([^_]+)_iteration_/)
+    if (match) {
+      return { containerId: match[1], containerType: 'parallel' }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Finds the outermost container for a span. For nested spans, this is parentIterations[0].
+ * For flat spans, this is the span's own immediate container.
+ */
+function getOutermostContainer(
+  span: TraceSpan
+): { containerId: string; containerType: 'parallel' | 'loop' } | undefined {
+  if (span.parentIterations && span.parentIterations.length > 0) {
+    const outermost = span.parentIterations[0]
+    return {
+      containerId: outermost.iterationContainerId,
+      containerType: outermost.iterationType as 'parallel' | 'loop',
+    }
+  }
+  return classifySpanContainer(span)
+}
+
+/**
+ * Builds the iteration-level hierarchy for a container, recursively nesting
+ * any deeper subflows. Works with both:
+ * - Direct spans (spans whose immediate container matches)
+ * - Nested spans (spans with parentIterations pointing through this container)
+ */
+function buildContainerChildren(
+  containerType: 'parallel' | 'loop',
+  containerId: string,
+  spans: TraceSpan[],
+  normalSpans: TraceSpan[],
+  counters: ContainerNameCounters
+): TraceSpan[] {
+  const iterationType = containerType === 'parallel' ? 'parallel-iteration' : 'loop-iteration'
+
+  const iterationGroups = new Map<number, TraceSpan[]>()
+
+  for (const span of spans) {
+    let iterIdx: number | undefined
+
+    if (
+      span.parentIterations &&
+      span.parentIterations.length > 0 &&
+      span.parentIterations[0].iterationContainerId === containerId
+    ) {
+      iterIdx = span.parentIterations[0].iterationCurrent
+    } else {
+      iterIdx = span.iterationIndex
+    }
+
+    if (iterIdx === undefined) {
+      logger.warn('Skipping iteration span without iterationIndex', {
+        spanId: span.id,
+        blockId: span.blockId,
+        containerId,
+      })
+      continue
+    }
+
+    if (!iterationGroups.has(iterIdx)) iterationGroups.set(iterIdx, [])
+    iterationGroups.get(iterIdx)!.push(span)
+  }
+
+  const iterationChildren: TraceSpan[] = []
+  const sortedIterations = Array.from(iterationGroups.entries()).sort(([a], [b]) => a - b)
+
+  for (const [iterationIndex, iterSpans] of sortedIterations) {
+    const directLeaves: TraceSpan[] = []
+    const deeperSpans: TraceSpan[] = []
+
+    for (const span of iterSpans) {
+      if (
+        span.parentIterations &&
+        span.parentIterations.length > 0 &&
+        span.parentIterations[0].iterationContainerId === containerId
+      ) {
+        deeperSpans.push({
+          ...span,
+          parentIterations: span.parentIterations.slice(1),
+        })
+      } else {
+        directLeaves.push({
+          ...span,
+          name: span.name.replace(/ \(iteration \d+\)$/, ''),
+        })
+      }
+    }
+
+    const nestedResult = groupIterationBlocksRecursive(
+      [...directLeaves, ...deeperSpans],
+      normalSpans,
+      counters
+    )
+
+    iterationChildren.push(
+      buildContainerSpan({
+        id: `${containerId}-iteration-${iterationIndex}`,
+        name: `Iteration ${iterationIndex}`,
+        type: iterationType,
+        sourceSpans: iterSpans,
+        children: nestedResult,
+      })
+    )
+  }
+
+  return iterationChildren
+}
+
+/**
+ * Core recursive algorithm for grouping iteration blocks.
+ *
+ * Handles two cases:
+ * 1. **Flat** (backward compat): spans have loopId/parallelId + iterationIndex but no
+ *    parentIterations. Grouped by immediate container -> iteration -> leaf.
+ * 2. **Nested** (new): spans have parentIterations chains. The outermost ancestor in the
+ *    chain determines the top-level container. Iteration spans are peeled one level at a
+ *    time and recursed.
+ */
+function groupIterationBlocksRecursive(
+  spans: TraceSpan[],
+  normalSpans: TraceSpan[],
+  counters: ContainerNameCounters
+): TraceSpan[] {
+  const result: TraceSpan[] = []
+  const iterationSpans: TraceSpan[] = []
+  const nonIterationSpans: TraceSpan[] = []
+
+  for (const span of spans) {
+    if (
+      (span.name.match(/^(.+) \(iteration (\d+)\)$/) &&
+        (span.loopId || span.parallelId || span.blockId?.includes('_parallel_'))) ||
+      (span.parentIterations && span.parentIterations.length > 0)
+    ) {
+      iterationSpans.push(span)
+    } else {
+      nonIterationSpans.push(span)
+    }
+  }
+
+  const containerIdsWithIterations = new Set<string>()
+  for (const span of iterationSpans) {
+    const outermost = getOutermostContainer(span)
+    if (outermost) containerIdsWithIterations.add(outermost.containerId)
+  }
+
+  const nonContainerSpans = nonIterationSpans.filter(
+    (span) =>
+      (span.type !== 'parallel' && span.type !== 'loop') ||
+      span.status === 'error' ||
+      (span.blockId && !containerIdsWithIterations.has(span.blockId))
+  )
+
+  if (iterationSpans.length === 0) {
+    result.push(...nonContainerSpans)
+    result.sort((a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime())
+    return result
+  }
+
+  const containerGroups = new Map<
+    string,
+    { type: 'parallel' | 'loop'; containerId: string; containerName: string; spans: TraceSpan[] }
+  >()
+
+  for (const span of iterationSpans) {
+    const outermost = getOutermostContainer(span)
+    if (!outermost) continue
+
+    const { containerId, containerType } = outermost
+    const groupKey = `${containerType}_${containerId}`
+
+    if (!containerGroups.has(groupKey)) {
+      const containerName = resolveContainerName(containerId, containerType, normalSpans, counters)
+      containerGroups.set(groupKey, {
+        type: containerType,
+        containerId,
+        containerName,
+        spans: [],
+      })
+    }
+    containerGroups.get(groupKey)!.spans.push(span)
+  }
+
+  for (const [, group] of containerGroups) {
+    const { type, containerId, containerName, spans: containerSpans } = group
+
+    const iterationChildren = buildContainerChildren(
+      type,
+      containerId,
+      containerSpans,
+      normalSpans,
+      counters
+    )
+
+    result.push(
+      buildContainerSpan({
+        id: `${type === 'parallel' ? 'parallel' : 'loop'}-execution-${containerId}`,
+        name: containerName,
+        type,
+        sourceSpans: containerSpans,
+        children: iterationChildren,
+      })
+    )
+  }
+
+  result.push(...nonContainerSpans)
+  result.sort((a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime())
+
+  return result
+}
+
+/**
+ * Groups iteration-based blocks (parallel and loop) by organizing their iteration spans
+ * into a hierarchical structure with proper parent-child relationships.
+ * Supports recursive nesting via parentIterations (e.g., parallel-in-parallel, loop-in-loop).
+ */
+export function groupIterationBlocks(spans: TraceSpan[]): TraceSpan[] {
+  const normalSpans = spans.filter((s) => !s.name.match(/^(.+) \(iteration (\d+)\)$/))
+  const counters: ContainerNameCounters = {
+    loopNumbers: new Map<string, number>(),
+    parallelNumbers: new Map<string, number>(),
+    loopCounter: 1,
+    parallelCounter: 1,
+  }
+  return groupIterationBlocksRecursive(spans, normalSpans, counters)
+}

apps/sim/lib/logs/execution/trace-spans/span-factory.ts

@@ -0,0 +1,390 @@
+import { createLogger } from '@sim/logger'
+import type { ProviderTiming, TraceSpan } from '@/lib/logs/types'
+import {
+  isConditionBlockType,
+  isWorkflowBlockType,
+  stripCustomToolPrefix,
+} from '@/executor/constants'
+import type {
+  BlockLog,
+  BlockToolCall,
+  NormalizedBlockOutput,
+  ProviderTimingSegment,
+} from '@/executor/types'
+
+const logger = createLogger('SpanFactory')
+
+/** A BlockLog that has already passed the id/type validity check. */
+type ValidBlockLog = BlockLog & { blockType: string }
+
+/**
+ * Creates a TraceSpan from a BlockLog. Returns null for invalid logs.
+ *
+ * Children are unified under `span.children` regardless of source:
+ *   - Provider `timeSegments` become model/tool child spans with tool I/O merged in
+ *   - `output.toolCalls` (no segments) become tool child spans
+ *   - Child workflow spans are flattened into children
+ */
+export function createSpanFromLog(log: BlockLog): TraceSpan | null {
+  if (!log.blockId || !log.blockType) return null
+  const validLog = log as ValidBlockLog
+
+  const span = createBaseSpan(validLog)
+
+  if (!isConditionBlockType(validLog.blockType)) {
+    enrichWithProviderMetadata(span, validLog)
+
+    if (!isWorkflowBlockType(validLog.blockType)) {
+      const segments = validLog.output?.providerTiming?.timeSegments
+      span.children = segments
+        ? buildChildrenFromTimeSegments(span, validLog, segments)
+        : buildChildrenFromToolCalls(span, validLog)
+    }
+  }
+
+  if (isWorkflowBlockType(validLog.blockType)) {
+    attachChildWorkflowSpans(span, validLog)
+  }
+
+  return span
+}
+
+/** Creates the base span with id, name, type, timing, status, and metadata. */
+function createBaseSpan(log: ValidBlockLog): TraceSpan {
+  const spanId = `${log.blockId}-${new Date(log.startedAt).getTime()}`
+  const output = extractDisplayOutput(log)
+  const childIds = extractChildWorkflowIds(log.output)
+
+  return {
+    id: spanId,
+    name: log.blockName ?? log.blockId,
+    type: log.blockType,
+    duration: log.durationMs,
+    startTime: log.startedAt,
+    endTime: log.endedAt,
+    status: log.error ? 'error' : 'success',
+    children: [],
+    blockId: log.blockId,
+    executionOrder: log.executionOrder,
+    input: log.input,
+    output,
+    ...(childIds ?? {}),
+    ...(log.errorHandled && { errorHandled: true }),
+    ...(log.loopId && { loopId: log.loopId }),
+    ...(log.parallelId && { parallelId: log.parallelId }),
+    ...(log.iterationIndex !== undefined && { iterationIndex: log.iterationIndex }),
+    ...(log.parentIterations?.length && { parentIterations: log.parentIterations }),
+  }
+}
+
+/**
+ * Strips internal fields from the block output for display and merges
+ * the block-level error into output so the UI renders it alongside data.
+ */
+function extractDisplayOutput(log: ValidBlockLog): Record<string, unknown> {
+  const { childWorkflowSnapshotId, childWorkflowId, ...rest } = log.output ?? {}
+  return log.error ? { ...rest, error: log.error } : rest
+}
+
+/** Pulls child-workflow identifiers off the output so they can live on the span. */
+function extractChildWorkflowIds(
+  output: NormalizedBlockOutput | undefined
+): { childWorkflowSnapshotId?: string; childWorkflowId?: string } | undefined {
+  if (!output) return undefined
+  const ids: { childWorkflowSnapshotId?: string; childWorkflowId?: string } = {}
+  if (typeof output.childWorkflowSnapshotId === 'string') {
+    ids.childWorkflowSnapshotId = output.childWorkflowSnapshotId
+  }
+  if (typeof output.childWorkflowId === 'string') {
+    ids.childWorkflowId = output.childWorkflowId
+  }
+  return ids.childWorkflowSnapshotId || ids.childWorkflowId ? ids : undefined
+}
+
+/** Enriches a span with provider timing, cost, tokens, and model from block output. */
+function enrichWithProviderMetadata(span: TraceSpan, log: ValidBlockLog): void {
+  const output = log.output
+  if (!output) return
+
+  if (output.providerTiming) {
+    const pt = output.providerTiming
+    const timing: ProviderTiming = {
+      duration: pt.duration,
+      startTime: pt.startTime,
+      endTime: pt.endTime,
+      segments: pt.timeSegments ?? [],
+    }
+    span.providerTiming = timing
+  }
+
+  if (output.cost) {
+    const { input, output: out, total, toolCost } = output.cost
+    span.cost = {
+      input,
+      output: out,
+      total,
+      ...(typeof toolCost === 'number' && toolCost > 0 ? { toolCost } : {}),
+    }
+  }
+
+  if (output.tokens) {
+    const t = output.tokens
+    const input =
+      typeof t.input === 'number' ? t.input : typeof t.prompt === 'number' ? t.prompt : undefined
+    const outputTokens =
+      typeof t.output === 'number'
+        ? t.output
+        : typeof t.completion === 'number'
+          ? t.completion
+          : undefined
+    const totalExplicit = typeof t.total === 'number' ? t.total : undefined
+    const total =
+      totalExplicit ??
+      (input !== undefined || outputTokens !== undefined
+        ? (input ?? 0) + (outputTokens ?? 0)
+        : undefined)
+    span.tokens = {
+      ...(input !== undefined && { input }),
+      ...(outputTokens !== undefined && { output: outputTokens }),
+      ...(total !== undefined && { total }),
+    }
+  }
+
+  if (typeof output.model === 'string') {
+    span.model = output.model
+  }
+}
+
+/**
+ * Builds child spans from provider `timeSegments`, matching tool segments to
+ * their corresponding tool call I/O by name in sequential order.
+ */
+function buildChildrenFromTimeSegments(
+  span: TraceSpan,
+  log: ValidBlockLog,
+  segments: ProviderTimingSegment[]
+): TraceSpan[] {
+  const toolCallsByName = groupToolCallsByName(resolveToolCallsList(log.output))
+  const toolCallIndices = new Map<string, number>()
+
+  return segments.map((segment, index) => {
+    const segmentStartTime = new Date(segment.startTime).toISOString()
+    let segmentEndTime = new Date(segment.endTime).toISOString()
+    let segmentDuration = segment.duration
+
+    // The final model segment sometimes closes before the block ends (e.g. when
+    // post-processing runs after the stream). Extend it to the block endTime so
+    // the Gantt bar fills to the edge rather than leaving a trailing gap.
+    if (index === segments.length - 1 && segment.type === 'model' && log.endedAt) {
+      const blockEndMs = new Date(log.endedAt).getTime()
+      const segmentEndMs = new Date(segment.endTime).getTime()
+      if (blockEndMs > segmentEndMs) {
+        segmentEndTime = log.endedAt
+        segmentDuration = blockEndMs - new Date(segment.startTime).getTime()
+      }
+    }
+
+    if (segment.type === 'tool') {
+      const normalizedName = stripCustomToolPrefix(segment.name ?? '')
+      const callsForName = toolCallsByName.get(normalizedName) ?? []
+      const currentIndex = toolCallIndices.get(normalizedName) ?? 0
+      const match = callsForName[currentIndex]
+      toolCallIndices.set(normalizedName, currentIndex + 1)
+
+      const toolChild: TraceSpan = {
+        id: `${span.id}-segment-${index}`,
+        name: normalizedName,
+        type: 'tool',
+        duration: segment.duration,
+        startTime: segmentStartTime,
+        endTime: segmentEndTime,
+        status: match?.error || segment.errorMessage ? 'error' : 'success',
+        input: match?.arguments ?? match?.input,
+        output: match?.error
+          ? { error: match.error, ...(match.result ?? match.output ?? {}) }
+          : (match?.result ?? match?.output),
+      }
+      if (segment.toolCallId) toolChild.toolCallId = segment.toolCallId
+      if (segment.errorType) toolChild.errorType = segment.errorType
+      if (segment.errorMessage) toolChild.errorMessage = segment.errorMessage
+      return toolChild
+    }
+
+    const modelChild: TraceSpan = {
+      id: `${span.id}-segment-${index}`,
+      name: segment.name ?? 'Model',
+      type: 'model',
+      duration: segmentDuration,
+      startTime: segmentStartTime,
+      endTime: segmentEndTime,
+      status: segment.errorMessage ? 'error' : 'success',
+    }
+
+    if (segment.assistantContent) {
+      modelChild.output = { content: segment.assistantContent }
+    }
+    if (segment.thinkingContent) {
+      modelChild.thinking = segment.thinkingContent
+    }
+    if (segment.toolCalls && segment.toolCalls.length > 0) {
+      modelChild.modelToolCalls = segment.toolCalls
+    }
+    if (segment.finishReason) {
+      modelChild.finishReason = segment.finishReason
+    }
+    if (segment.tokens) {
+      modelChild.tokens = segment.tokens
+    }
+    if (segment.cost) {
+      modelChild.cost = segment.cost
+    }
+    if (typeof segment.ttft === 'number' && segment.ttft >= 0) {
+      modelChild.ttft = segment.ttft
+    }
+    if (span.model) {
+      modelChild.model = span.model
+    }
+    if (segment.provider) {
+      modelChild.provider = segment.provider
+    }
+    if (segment.errorType) {
+      modelChild.errorType = segment.errorType
+    }
+    if (segment.errorMessage) {
+      modelChild.errorMessage = segment.errorMessage
+    }
+
+    return modelChild
+  })
+}
+
+/**
+ * Builds tool-call child spans when the provider did not emit `timeSegments`.
+ * Each tool call becomes a full TraceSpan of `type: 'tool'`.
+ */
+function buildChildrenFromToolCalls(span: TraceSpan, log: ValidBlockLog): TraceSpan[] {
+  const toolCalls = resolveToolCallsList(log.output)
+  if (toolCalls.length === 0) return []
+
+  return toolCalls.map((tc, index) => {
+    const startTime = tc.startTime ?? log.startedAt
+    const endTime = tc.endTime ?? log.endedAt
+    return {
+      id: `${span.id}-tool-${index}`,
+      name: stripCustomToolPrefix(tc.name ?? 'unnamed-tool'),
+      type: 'tool',
+      duration: tc.duration ?? 0,
+      startTime,
+      endTime,
+      status: tc.error ? 'error' : 'success',
+      input: tc.arguments ?? tc.input,
+      output: tc.error
+        ? { error: tc.error, ...(tc.result ?? tc.output ?? {}) }
+        : (tc.result ?? tc.output),
+    }
+  })
+}
+
+/** Groups tool calls by their stripped name for sequential matching against segments. */
+function groupToolCallsByName(toolCalls: BlockToolCall[]): Map<string, BlockToolCall[]> {
+  const byName = new Map<string, BlockToolCall[]>()
+  for (const tc of toolCalls) {
+    const name = stripCustomToolPrefix(tc.name ?? '')
+    const list = byName.get(name)
+    if (list) list.push(tc)
+    else byName.set(name, [tc])
+  }
+  return byName
+}
+
+/**
+ * Resolves the tool calls list from block output. Providers write a normalized
+ * `{list, count}` container; a legacy streaming path embeds calls under
+ * `executionData.output.toolCalls`. The `Array.isArray` branches guard against
+ * persisted logs from before the container shape was normalized, where
+ * `toolCalls` was stored as a plain array — still observed in older DB rows.
+ */
+function resolveToolCallsList(output: NormalizedBlockOutput | undefined): BlockToolCall[] {
+  if (!output) return []
+
+  const direct = output.toolCalls
+  if (direct) {
+    if (Array.isArray(direct)) return direct
+    if (direct.list) return direct.list
+    logger.warn('Unexpected toolCalls shape on block output — no list extracted', {
+      shape: typeof direct,
+    })
+    return []
+  }
+
+  const legacy = (output.executionData as { output?: { toolCalls?: unknown } } | undefined)?.output
+    ?.toolCalls
+  if (!legacy) return []
+  if (Array.isArray(legacy)) return legacy as BlockToolCall[]
+  if (typeof legacy === 'object' && legacy !== null && 'list' in legacy) {
+    return ((legacy as { list?: BlockToolCall[] }).list ?? []) as BlockToolCall[]
+  }
+  logger.warn('Unexpected legacy executionData.output.toolCalls shape — no list extracted', {
+    shape: typeof legacy,
+  })
+  return []
+}
+
+/** Extracts and flattens child workflow trace spans into the parent span's children. */
+function attachChildWorkflowSpans(span: TraceSpan, log: ValidBlockLog): void {
+  const childTraceSpans = log.childTraceSpans ?? log.output?.childTraceSpans
+  if (!childTraceSpans?.length) return
+
+  span.children = flattenWorkflowChildren(childTraceSpans)
+  span.output = stripChildTraceSpansFromOutput(span.output)
+}
+
+/** True when a span is a synthetic workflow wrapper (no blockId). */
+function isSyntheticWorkflowWrapper(span: TraceSpan): boolean {
+  return span.type === 'workflow' && !span.blockId
+}
+
+/** Reads nested `childTraceSpans` off a span's output, or `[]` if absent. */
+function extractOutputChildren(output: TraceSpan['output']): TraceSpan[] {
+  const nested = (output as { childTraceSpans?: TraceSpan[] } | undefined)?.childTraceSpans
+  return Array.isArray(nested) ? nested : []
+}
+
+/** Returns a copy of `output` with `childTraceSpans` removed, or undefined unchanged. */
+function stripChildTraceSpansFromOutput(
+  output: TraceSpan['output']
+): TraceSpan['output'] | undefined {
+  if (!output || !('childTraceSpans' in output)) return output
+  const { childTraceSpans: _, ...rest } = output as Record<string, unknown>
+  return rest
+}
+
+/** Recursively flattens synthetic workflow wrappers, preserving real block spans. */
+function flattenWorkflowChildren(spans: TraceSpan[]): TraceSpan[] {
+  const flattened: TraceSpan[] = []
+
+  for (const span of spans) {
+    if (isSyntheticWorkflowWrapper(span)) {
+      if (span.children?.length) {
+        flattened.push(...flattenWorkflowChildren(span.children))
+      }
+      continue
+    }
+
+    const directChildren = span.children ?? []
+    const outputChildren = extractOutputChildren(span.output)
+    const allChildren = [...directChildren, ...outputChildren]
+
+    const nextSpan: TraceSpan = { ...span }
+    if (allChildren.length > 0) {
+      nextSpan.children = flattenWorkflowChildren(allChildren)
+    }
+    if (outputChildren.length > 0) {
+      nextSpan.output = stripChildTraceSpansFromOutput(nextSpan.output)
+    }
+
+    flattened.push(nextSpan)
+  }
+
+  return flattened
+}

apps/sim/lib/logs/execution/trace-spans/trace-spans.ts

@@ -0,0 +1,143 @@
+import { groupIterationBlocks } from '@/lib/logs/execution/trace-spans/iteration-grouping'
+import { createSpanFromLog } from '@/lib/logs/execution/trace-spans/span-factory'
+import type { TraceSpan } from '@/lib/logs/types'
+import type { BlockLog, ExecutionResult } from '@/executor/types'
+
+/**
+ * Keys that should be recursively filtered from output display.
+ * These are internal fields used for execution tracking that shouldn't be shown to users.
+ */
+const HIDDEN_OUTPUT_KEYS = new Set(['childTraceSpans'])
+const SUCCESSFUL_CHILD_ERROR_BOUNDARY_BLOCK_TYPES = new Set(['mothership'])
+
+function setFilteredValue(output: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(output, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  })
+}
+
+/**
+ * Recursively filters hidden keys from nested objects for cleaner display.
+ * Used by both executor (for log output) and UI (for display).
+ */
+export function filterHiddenOutputKeys(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => filterHiddenOutputKeys(item))
+  }
+
+  if (typeof value === 'object') {
+    const filtered: Record<string, unknown> = {}
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (HIDDEN_OUTPUT_KEYS.has(key)) {
+        continue
+      }
+      setFilteredValue(filtered, key, filterHiddenOutputKeys(val))
+    }
+    return filtered
+  }
+
+  return value
+}
+
+/**
+ * Builds a hierarchical trace span tree from execution logs.
+ *
+ * Pipeline:
+ *   1. Each BlockLog becomes a TraceSpan via `createSpanFromLog`.
+ *   2. Spans are sorted by start time to form a flat list of root spans.
+ *   3. Loop/parallel iterations are grouped into container spans via `groupIterationBlocks`.
+ *   4. A synthetic "Workflow Execution" root wraps the grouped spans and provides
+ *      relative timestamps + total duration derived from the earliest start / latest end.
+ */
+export function buildTraceSpans(result: ExecutionResult): {
+  traceSpans: TraceSpan[]
+  totalDuration: number
+} {
+  if (!result.logs?.length) {
+    return { traceSpans: [], totalDuration: 0 }
+  }
+
+  const spans = buildRootSpansFromLogs(result.logs)
+  const grouped = groupIterationBlocks(spans)
+
+  if (grouped.length === 0 || !result.metadata) {
+    const totalDuration = grouped.reduce((sum, span) => sum + span.duration, 0)
+    return { traceSpans: grouped, totalDuration }
+  }
+
+  return wrapInWorkflowRoot(grouped, spans)
+}
+
+/** Converts each BlockLog into a TraceSpan, sorted chronologically by start time. */
+function buildRootSpansFromLogs(logs: BlockLog[]): TraceSpan[] {
+  const spans: TraceSpan[] = []
+  for (const log of logs) {
+    const span = createSpanFromLog(log)
+    if (span) spans.push(span)
+  }
+  spans.sort((a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime())
+  return spans
+}
+
+/**
+ * Wraps grouped spans in a synthetic workflow-execution root span using the
+ * true workflow bounds (earliest start / latest end across all leaf spans).
+ */
+function wrapInWorkflowRoot(
+  grouped: TraceSpan[],
+  leafSpans: TraceSpan[]
+): { traceSpans: TraceSpan[]; totalDuration: number } {
+  let earliestStart = Number.POSITIVE_INFINITY
+  let latestEnd = 0
+  for (const span of leafSpans) {
+    const startTime = new Date(span.startTime).getTime()
+    const endTime = new Date(span.endTime).getTime()
+    if (startTime < earliestStart) earliestStart = startTime
+    if (endTime > latestEnd) latestEnd = endTime
+  }
+
+  const actualWorkflowDuration = latestEnd - earliestStart
+  addRelativeTimestamps(grouped, earliestStart)
+
+  const totalCost = leafSpans.reduce((sum, s) => sum + (s.cost?.total ?? 0), 0)
+
+  const workflowSpan: TraceSpan = {
+    id: 'workflow-execution',
+    name: 'Workflow Execution',
+    type: 'workflow',
+    duration: actualWorkflowDuration,
+    startTime: new Date(earliestStart).toISOString(),
+    endTime: new Date(latestEnd).toISOString(),
+    status: grouped.some(hasUnhandledError) ? 'error' : 'success',
+    children: grouped,
+    ...(totalCost > 0 && { cost: { total: totalCost } }),
+  }
+
+  return { traceSpans: [workflowSpan], totalDuration: actualWorkflowDuration }
+}
+
+/** Recursively annotates spans with `relativeStartMs` (ms since workflow start). */
+function addRelativeTimestamps(spans: TraceSpan[], workflowStartMs: number): void {
+  for (const span of spans) {
+    span.relativeStartMs = new Date(span.startTime).getTime() - workflowStartMs
+    if (span.children?.length) {
+      addRelativeTimestamps(span.children, workflowStartMs)
+    }
+  }
+}
+
+/** True if this span (or any descendant) has an unhandled error. */
+function hasUnhandledError(span: TraceSpan): boolean {
+  if (span.status === 'error' && !span.errorHandled) return true
+  if (span.status === 'success' && SUCCESSFUL_CHILD_ERROR_BOUNDARY_BLOCK_TYPES.has(span.type)) {
+    return false
+  }
+  return span.children?.some(hasUnhandledError) ?? false
+}