@workflow/web-shared 4.1.0-beta.62 → 4.1.0-beta.63

package/src/components/workflow-traces/trace-span-construction.ts

@@ -3,7 +3,7 @@
  */
 
 import { parseStepName, parseWorkflowName } from '@workflow/utils/parse-name';
-import type { Event, Step, WorkflowRun } from '@workflow/world';
+import type { Event, WorkflowRun } from '@workflow/world';
 import type { Span, SpanEvent } from '../trace-viewer/types';
 import { shouldShowVerticalLine } from './event-colors';
 import { calculateDuration, dateToOtelTime } from './trace-time-utils';
@@ -81,18 +81,13 @@ export const waitEventsToWaitEntity = (
 /**
  * Converts a workflow Wait to an OpenTelemetry Span
  */
-export function waitToSpan(
-  events: Event[],
-  run: WorkflowRun,
-  nowTime: Date
-): Span | null {
+export function waitToSpan(events: Event[], maxEndTime: Date): Span | null {
   const wait = waitEventsToWaitEntity(events);
   if (!wait) {
     return null;
   }
-  const viewerEndTime = new Date(run.completedAt || nowTime) ?? nowTime;
-  const startTime = wait?.createdAt ?? nowTime;
-  const endTime = wait?.completedAt ?? viewerEndTime;
+  const startTime = wait.createdAt;
+  const endTime = wait.completedAt ?? maxEndTime;
   const start = dateToOtelTime(startTime);
   const end = dateToOtelTime(endTime);
   const duration = calculateDuration(startTime, endTime);
@@ -117,29 +112,92 @@ export function waitToSpan(
   };
 }
 
+export const stepEventsToStepEntity = (
+  events: Event[]
+): {
+  stepId: string;
+  runId: string;
+  stepName: string;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+  attempt: number;
+  createdAt: Date;
+  updatedAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  specVersion?: number;
+} | null => {
+  const createdEvent = events.find(
+    (event) => event.eventType === 'step_created'
+  );
+  if (!createdEvent) {
+    return null;
+  }
+  // Walk events in order to derive status, attempt count, and timestamps.
+  // Handles both step_retrying and consecutive step_started as retry signals.
+  let status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' =
+    'pending';
+  let attempt = 0;
+  let startedAt: Date | undefined;
+  let completedAt: Date | undefined;
+
+  for (const e of events) {
+    switch (e.eventType) {
+      case 'step_started':
+        status = 'running';
+        attempt += 1;
+        if (!startedAt) startedAt = e.createdAt;
+        completedAt = undefined;
+        break;
+      case 'step_completed':
+        status = 'completed';
+        completedAt = e.createdAt;
+        break;
+      case 'step_failed':
+        status = 'failed';
+        completedAt = e.createdAt;
+        break;
+      case 'step_retrying':
+        status = 'pending';
+        completedAt = undefined;
+        break;
+    }
+  }
+
+  // Ensure at least attempt 1 if we never saw step_started
+  if (attempt === 0) attempt = 1;
+
+  const lastEvent = events[events.length - 1];
+  return {
+    stepId: createdEvent.correlationId,
+    runId: createdEvent.runId,
+    stepName: createdEvent.eventData?.stepName ?? '',
+    status,
+    attempt,
+    createdAt: createdEvent.createdAt,
+    updatedAt: lastEvent?.createdAt ?? createdEvent.createdAt,
+    startedAt,
+    completedAt,
+    specVersion: createdEvent.specVersion,
+  };
+};
+
 /**
- * Converts a workflow Step to an OpenTelemetry Span
+ * Converts step events to an OpenTelemetry Span
  */
-export function stepToSpan(
-  step: Step,
-  stepEvents: Event[],
-  nowTime?: Date,
-  maxEndTime?: Date
-): Span {
-  const now = nowTime ?? new Date();
+export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
+  const step = stepEventsToStepEntity(stepEvents);
+  if (!step) {
+    return null;
+  }
   const parsedName = parseStepName(String(step.stepName));
 
-  // Only embed identification fields — not the full object with
-  // input/output/error which may contain non-cloneable types.
-  // The detail panel fetches full data separately via spanDetailData.
-  const { input: _i, output: _o, error: _e, ...stepIdentity } = step;
   const attributes = {
     resource: 'step' as const,
-    data: stepIdentity,
+    data: step,
   };
 
   const resource = 'step';
-  const endTime = new Date(step.completedAt ?? maxEndTime ?? now);
+  const endTime = new Date(step.completedAt ?? maxEndTime);
 
   // Include ALL correlated events on the span so the sidebar detail view
   // can display them. The timeline uses the `showVerticalLine` flag to
@@ -187,6 +245,7 @@ export const hookEventsToHookEntity = (
 ): {
   hookId: string;
   runId: string;
+  token?: string;
   createdAt: Date;
   receivedCount: number;
   lastReceivedAt?: Date;
@@ -208,6 +267,7 @@ export const hookEventsToHookEntity = (
   return {
     hookId: createdEvent.correlationId,
     runId: createdEvent.runId,
+    token: createdEvent.eventData?.token,
     createdAt: createdEvent.createdAt,
     receivedCount: receivedEvents.length,
     lastReceivedAt: lastReceivedEvent?.createdAt || undefined,
@@ -218,11 +278,7 @@ export const hookEventsToHookEntity = (
 /**
  * Converts a workflow Hook to an OpenTelemetry Span
  */
-export function hookToSpan(
-  hookEvents: Event[],
-  run: WorkflowRun,
-  nowTime: Date
-): Span | null {
+export function hookToSpan(hookEvents: Event[], maxEndTime: Date): Span | null {
   const hook = hookEventsToHookEntity(hookEvents);
   if (!hook) {
     return null;
@@ -231,10 +287,7 @@ export function hookToSpan(
   // Convert hook-related events to span events
   const events = convertEventsToSpanEvents(hookEvents, false);
 
-  // We display hooks as a minimum span size of 10 seconds, just to ensure
-  // it's clickable even if there is no
-  const viewerEndTime = new Date(run.completedAt || nowTime) ?? nowTime;
-  const endTime = hook.disposedAt || viewerEndTime;
+  const endTime = hook.disposedAt || maxEndTime;
 
   return {
     spanId: String(hook.hookId),

package/src/index.ts

@@ -10,6 +10,7 @@ export type { Event, Hook, Step, WorkflowRun } from '@workflow/world';
 export * from './components';
 export {
   hookEventsToHookEntity,
+  stepEventsToStepEntity,
   waitEventsToWaitEntity,
 } from './components/workflow-traces/trace-span-construction';
 export type { EventAnalysis } from './lib/event-analysis';
@@ -20,6 +21,18 @@ export {
   isTerminalStatus,
   shouldShowReenqueueButton,
 } from './lib/event-analysis';
+export type {
+  MaterializedEntities,
+  MaterializedHook,
+  MaterializedStep,
+  MaterializedWait,
+} from './lib/event-materialization';
+export {
+  materializeAll,
+  materializeHooks,
+  materializeSteps,
+  materializeWaits,
+} from './lib/event-materialization';
 export type { Revivers, StreamRef } from './lib/hydration';
 export {
   CLASS_INSTANCE_REF_TYPE,

package/src/lib/event-materialization.ts

@@ -0,0 +1,243 @@
+/**
+ * Event materialization helpers.
+ *
+ * These functions convert a flat list of workflow events into entity-like
+ * objects (steps, hooks, waits) by grouping events by correlationId and
+ * stitching together lifecycle events.
+ *
+ * This enables a "top-down" data fetching pattern where the client fetches
+ * all events for a run once, then materializes entities client-side instead
+ * of making separate API calls for each entity type.
+ */
+
+import type { Event, StepStatus } from '@workflow/world';
+
+// ---------------------------------------------------------------------------
+// Materialized entity types
+// ---------------------------------------------------------------------------
+
+export interface MaterializedStep {
+  stepId: string;
+  runId: string;
+  stepName: string;
+  status: StepStatus;
+  attempt: number;
+  createdAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  updatedAt: Date;
+  /** All events for this step, in insertion order */
+  events: Event[];
+}
+
+export interface MaterializedHook {
+  hookId: string;
+  runId: string;
+  token?: string;
+  createdAt: Date;
+  receivedCount: number;
+  lastReceivedAt?: Date;
+  disposedAt?: Date;
+  /** All events for this hook, in insertion order */
+  events: Event[];
+}
+
+export interface MaterializedWait {
+  waitId: string;
+  runId: string;
+  status: 'waiting' | 'completed';
+  createdAt: Date;
+  resumeAt?: Date;
+  completedAt?: Date;
+  /** All events for this wait, in insertion order */
+  events: Event[];
+}
+
+export interface MaterializedEntities {
+  steps: MaterializedStep[];
+  hooks: MaterializedHook[];
+  waits: MaterializedWait[];
+}
+
+// ---------------------------------------------------------------------------
+// Helper: group events by correlationId prefix
+// ---------------------------------------------------------------------------
+
+function groupByCorrelationId(
+  events: Event[],
+  prefixes: string[]
+): Map<string, Event[]> {
+  const groups = new Map<string, Event[]>();
+  for (const event of events) {
+    const cid = event.correlationId;
+    if (!cid) continue;
+    if (!prefixes.some((p) => cid.startsWith(p))) continue;
+    const existing = groups.get(cid);
+    if (existing) {
+      existing.push(event);
+    } else {
+      groups.set(cid, [event]);
+    }
+  }
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// materializeSteps
+// ---------------------------------------------------------------------------
+
+/**
+ * Group step_* events by correlationId and build Step-like entities.
+ *
+ * Handles partial event lists gracefully: a step may only have a
+ * step_created event with no completion yet.
+ */
+export function materializeSteps(events: Event[]): MaterializedStep[] {
+  const groups = groupByCorrelationId(events, ['step_']);
+  const steps: MaterializedStep[] = [];
+
+  for (const [correlationId, stepEvents] of groups) {
+    const created = stepEvents.find((e) => e.eventType === 'step_created');
+    if (!created) continue;
+
+    let status: StepStatus = 'pending';
+    let attempt = 0;
+    let startedAt: Date | undefined;
+    let completedAt: Date | undefined;
+    let updatedAt = created.createdAt;
+
+    for (const e of stepEvents) {
+      switch (e.eventType) {
+        case 'step_started':
+          status = 'running';
+          attempt += 1;
+          if (!startedAt) startedAt = e.createdAt;
+          completedAt = undefined;
+          updatedAt = e.createdAt;
+          break;
+        case 'step_completed':
+          status = 'completed';
+          completedAt = e.createdAt;
+          updatedAt = e.createdAt;
+          break;
+        case 'step_failed':
+          status = 'failed';
+          completedAt = e.createdAt;
+          updatedAt = e.createdAt;
+          break;
+        case 'step_retrying':
+          status = 'pending';
+          completedAt = undefined;
+          updatedAt = e.createdAt;
+          break;
+      }
+    }
+
+    steps.push({
+      stepId: correlationId,
+      runId: created.runId,
+      stepName:
+        created.eventType === 'step_created'
+          ? (created.eventData?.stepName ?? correlationId)
+          : correlationId,
+      status,
+      attempt,
+      createdAt: created.createdAt,
+      startedAt,
+      completedAt,
+      updatedAt,
+      events: stepEvents,
+    });
+  }
+
+  return steps;
+}
+
+// ---------------------------------------------------------------------------
+// materializeHooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Group hook_* events by correlationId and build Hook-like entities.
+ */
+export function materializeHooks(events: Event[]): MaterializedHook[] {
+  const groups = groupByCorrelationId(events, ['hook_']);
+  const hooks: MaterializedHook[] = [];
+
+  for (const [correlationId, hookEvents] of groups) {
+    const created = hookEvents.find((e) => e.eventType === 'hook_created');
+    if (!created) continue;
+
+    const receivedEvents = hookEvents.filter(
+      (e) => e.eventType === 'hook_received'
+    );
+    const disposed = hookEvents.find((e) => e.eventType === 'hook_disposed');
+    const lastReceived = receivedEvents.at(-1);
+
+    hooks.push({
+      hookId: correlationId,
+      runId: created.runId,
+      token:
+        created.eventType === 'hook_created'
+          ? created.eventData?.token
+          : undefined,
+      createdAt: created.createdAt,
+      receivedCount: receivedEvents.length,
+      lastReceivedAt: lastReceived?.createdAt,
+      disposedAt: disposed?.createdAt,
+      events: hookEvents,
+    });
+  }
+
+  return hooks;
+}
+
+// ---------------------------------------------------------------------------
+// materializeWaits
+// ---------------------------------------------------------------------------
+
+/**
+ * Group wait_* events by correlationId and build Wait-like entities.
+ */
+export function materializeWaits(events: Event[]): MaterializedWait[] {
+  const groups = groupByCorrelationId(events, ['wait_']);
+  const waits: MaterializedWait[] = [];
+
+  for (const [correlationId, waitEvents] of groups) {
+    const created = waitEvents.find((e) => e.eventType === 'wait_created');
+    if (!created) continue;
+
+    const completed = waitEvents.find((e) => e.eventType === 'wait_completed');
+
+    waits.push({
+      waitId: correlationId,
+      runId: created.runId,
+      status: completed ? 'completed' : 'waiting',
+      createdAt: created.createdAt,
+      resumeAt:
+        created.eventType === 'wait_created'
+          ? created.eventData?.resumeAt
+          : undefined,
+      completedAt: completed?.createdAt,
+      events: waitEvents,
+    });
+  }
+
+  return waits;
+}
+
+// ---------------------------------------------------------------------------
+// materializeAll
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience function that materializes all entity types from a flat
+ * event list.
+ */
+export function materializeAll(events: Event[]): MaterializedEntities {
+  return {
+    steps: materializeSteps(events),
+    hooks: materializeHooks(events),
+    waits: materializeWaits(events),
+  };
+}

package/src/lib/trace-builder.ts

@@ -0,0 +1,201 @@
+/**
+ * Builds a complete trace from a WorkflowRun and its Events.
+ *
+ * This module groups raw events by correlation ID and entity type,
+ * converts each group into an OpenTelemetry-style Span, and returns
+ * a fully-formed Trace ready for the trace viewer.
+ */
+
+import type { Event, WorkflowRun } from '@workflow/world';
+import type { Span } from '../components/trace-viewer/types';
+import {
+  hookToSpan,
+  runToSpan,
+  stepToSpan,
+  waitToSpan,
+  WORKFLOW_LIBRARY,
+} from '../components/workflow-traces/trace-span-construction';
+import { otelTimeToMs } from '../components/workflow-traces/trace-time-utils';
+
+// ---------------------------------------------------------------------------
+// Event type classifiers
+// ---------------------------------------------------------------------------
+
+export const isStepEvent = (eventType: string) => eventType.startsWith('step_');
+
+export const isTimerEvent = (eventType: string) =>
+  eventType === 'wait_created' || eventType === 'wait_completed';
+
+export const isHookLifecycleEvent = (eventType: string) =>
+  eventType === 'hook_received' ||
+  eventType === 'hook_created' ||
+  eventType === 'hook_disposed';
+
+// ---------------------------------------------------------------------------
+// Event grouping
+// ---------------------------------------------------------------------------
+
+export type GroupedEvents = {
+  eventsByStepId: Map<string, Event[]>;
+  runLevelEvents: Event[];
+  timerEvents: Map<string, Event[]>;
+  hookEvents: Map<string, Event[]>;
+};
+
+function pushEvent(
+  map: Map<string, Event[]>,
+  correlationId: string,
+  event: Event
+) {
+  const existing = map.get(correlationId);
+  if (existing) {
+    existing.push(event);
+    return;
+  }
+  map.set(correlationId, [event]);
+}
+
+export function groupEventsByCorrelation(events: Event[]): GroupedEvents {
+  const eventsByStepId = new Map<string, Event[]>();
+  const runLevelEvents: Event[] = [];
+  const timerEvents = new Map<string, Event[]>();
+  const hookEvents = new Map<string, Event[]>();
+
+  for (const event of events) {
+    const correlationId = event.correlationId;
+    if (!correlationId) {
+      runLevelEvents.push(event);
+      continue;
+    }
+
+    if (isTimerEvent(event.eventType)) {
+      pushEvent(timerEvents, correlationId, event);
+      continue;
+    }
+
+    if (isHookLifecycleEvent(event.eventType)) {
+      pushEvent(hookEvents, correlationId, event);
+      continue;
+    }
+
+    if (isStepEvent(event.eventType)) {
+      pushEvent(eventsByStepId, correlationId, event);
+      continue;
+    }
+
+    runLevelEvents.push(event);
+  }
+
+  return { eventsByStepId, runLevelEvents, timerEvents, hookEvents };
+}
+
+// ---------------------------------------------------------------------------
+// Trace construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes the latest known event time from the events list.
+ * Active (in-progress) child spans are capped at this time instead of `now`,
+ * so they only extend as far as our data goes.
+ */
+function computeLatestKnownTime(events: Event[], run: WorkflowRun): Date {
+  let latest = new Date(run.createdAt).getTime();
+  for (const event of events) {
+    const t = new Date(event.createdAt).getTime();
+    if (t > latest) latest = t;
+  }
+  return new Date(latest);
+}
+
+function buildSpans(
+  run: WorkflowRun,
+  groupedEvents: GroupedEvents,
+  now: Date,
+  latestKnownTime: Date
+) {
+  // Active child spans cap at latestKnownTime so they don't extend into
+  // unknown territory. Even when the run is completed, we may not have loaded
+  // all events yet, so always use the latest event we've actually seen.
+  const childMaxEnd = latestKnownTime;
+
+  const stepSpans = Array.from(groupedEvents.eventsByStepId.values())
+    .map((events) => stepToSpan(events, childMaxEnd))
+    .filter((span): span is Span => span !== null);
+
+  const hookSpans = Array.from(groupedEvents.hookEvents.values())
+    .map((events) => hookToSpan(events, childMaxEnd))
+    .filter((span): span is Span => span !== null);
+
+  const waitSpans = Array.from(groupedEvents.timerEvents.values())
+    .map((events) => waitToSpan(events, childMaxEnd))
+    .filter((span): span is Span => span !== null);
+
+  return {
+    runSpan: runToSpan(run, groupedEvents.runLevelEvents, now),
+    spans: [...stepSpans, ...hookSpans, ...waitSpans],
+  };
+}
+
+function cascadeSpans(runSpan: Span, spans: Span[]) {
+  const sortedSpans = [
+    runSpan,
+    ...spans.slice().sort((a, b) => {
+      const aStart = otelTimeToMs(a.startTime);
+      const bStart = otelTimeToMs(b.startTime);
+      return aStart - bStart;
+    }),
+  ];
+
+  return sortedSpans.map((span, index) => {
+    const parentSpanId =
+      index === 0 ? undefined : String(sortedSpans[index - 1].spanId);
+    return {
+      ...span,
+      parentSpanId,
+    };
+  });
+}
+
+export interface TraceWithMeta {
+  traceId: string;
+  rootSpanId: string;
+  spans: Span[];
+  resources: { name: string; attributes: Record<string, string> }[];
+  /** Duration in ms from trace start to the latest known event. */
+  knownDurationMs: number;
+}
+
+export function buildTrace(
+  run: WorkflowRun,
+  events: Event[],
+  now: Date
+): TraceWithMeta {
+  const groupedEvents = groupEventsByCorrelation(events);
+  const latestKnownTime = computeLatestKnownTime(events, run);
+  const { runSpan, spans } = buildSpans(
+    run,
+    groupedEvents,
+    now,
+    latestKnownTime
+  );
+  const sortedCascadingSpans = cascadeSpans(runSpan, spans);
+
+  // Compute known duration relative to trace start
+  const traceStartMs = otelTimeToMs(runSpan.startTime);
+  const knownDurationMs = latestKnownTime.getTime() - traceStartMs;
+
+  return {
+    traceId: run.runId,
+    rootSpanId: run.runId,
+    spans: sortedCascadingSpans,
+    resources: [
+      {
+        name: 'workflow',
+        attributes: {
+          'service.name': WORKFLOW_LIBRARY.name,
+        },
+      },
+    ],
+    knownDurationMs: Math.max(0, knownDurationMs),
+  };
+}