@workflow/web-shared 5.0.0-beta.46 → 5.0.0-beta.47

package/src/components/trace-viewer.tsx

@@ -8,6 +8,7 @@ import {
 } from './sidebar/sidebar-data-context';
 import { TraceViewerSkeleton } from './trace-viewer/components/trace-viewer-skeleton';
 import { TraceViewer as TraceViewerComponent } from './trace-viewer/trace-viewer';
+import type { GetStepAttributes } from './workflow-traces/trace-span-construction';
 
 const TraceViewer = ({
   run,
@@ -17,6 +18,7 @@ const TraceViewer = ({
   hasMore,
   isLoadingMore,
   loading = false,
+  getStepAttributes,
 }: {
   run: WorkflowRun;
   events: Event[];
@@ -25,6 +27,8 @@ const TraceViewer = ({
   hasMore?: boolean;
   isLoadingMore?: boolean;
   loading?: boolean;
+  /** Adds product-specific attributes to event-derived step span data. */
+  getStepAttributes?: GetStepAttributes;
 }) => {
   const trace: TraceWithMeta | undefined = useMemo(() => {
     if (!run?.runId) {
@@ -35,9 +39,10 @@ const TraceViewer = ({
     // repeats with the whole log in hand.
     return buildTrace(run, events, new Date(), {
       isCompleteHistory: !hasMore,
+      getStepAttributes,
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps -- `new Date()` is intentionally not a dep
-  }, [run, events, hasMore]);
+  }, [run, events, hasMore, getStepAttributes]);
 
   // The sidebar shows one entity's slice of the log, so it takes the trace's
   // answer rather than recomputing one from the slice.

package/src/components/ui/data-inspector.tsx

@@ -344,7 +344,7 @@ function BytesDisplayValue({ display }: { display: BytesDisplay }) {
 // Tree renderer
 // ---------------------------------------------------------------------------
 
-type Entry = [field: string | undefined, value: unknown];
+type Entry = [field: string | undefined, value: unknown, key?: string | number];
 
 interface NodeContext {
   level: number;
@@ -357,10 +357,51 @@ function formatField(field: string): string {
   return field === '' ? '""' : field;
 }
 
+function isGenericIterable(
+  value: unknown
+): value is object & Iterable<unknown> {
+  if (
+    value === null ||
+    (typeof value !== 'object' && typeof value !== 'function') ||
+    Array.isArray(value) ||
+    value instanceof Map ||
+    value instanceof Set
+  ) {
+    return false;
+  }
+  return (
+    typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] ===
+    'function'
+  );
+}
+
+function isEntryIterable(
+  value: object & Iterable<unknown>
+): value is object & Iterable<unknown> & { entries(): Iterable<unknown> } {
+  return typeof (value as { entries?: unknown }).entries === 'function';
+}
+
+function collectEntries(
+  iterable: Iterable<unknown>,
+  asPairs: boolean
+): Entry[] {
+  return Array.from(iterable, (item, index) => {
+    if (asPairs && Array.isArray(item) && item.length >= 2) {
+      return [String(item[0]), collapseRefs(item[1]), index];
+    }
+    return [undefined, collapseRefs(item), index];
+  });
+}
+
+function isSelfIterableIterator(value: object & Iterable<unknown>): boolean {
+  return Object.is(value[Symbol.iterator](), value);
+}
+
 /**
- * Describe an object/array/map/set as an expandable container. Returns null for
- * values that should render as a primitive. `prefix` carries a class name shown
- * before the opening bracket (Map/Set and named class instances).
+ * Describe an object/array/iterable as an expandable container. Returns null
+ * for values that should render as a primitive. `prefix` carries a class name
+ * shown before the opening bracket (Map/Set, generic iterables, and named class
+ * instances).
  */
 function describeContainer(
   value: unknown
@@ -391,6 +432,25 @@ function describeContainer(
       prefix: 'Set',
     };
   }
+  if (isGenericIterable(value)) {
+    const name = (value as { constructor?: { name?: string } }).constructor
+      ?.name;
+    const prefix = name && name !== 'Object' ? name : undefined;
+    if (isEntryIterable(value)) {
+      return {
+        entries: collectEntries(value.entries(), true),
+        open: '{',
+        close: '}',
+        prefix,
+      };
+    }
+    return {
+      entries: collectEntries(value, false),
+      open: '[',
+      close: ']',
+      prefix,
+    };
+  }
   if (value !== null && typeof value === 'object') {
     const name = (value as { constructor?: { name?: string } }).constructor
       ?.name;
@@ -616,9 +676,9 @@ function ExpandableContainer({
       {expanded ? (
         // biome-ignore lint/a11y/useSemanticElements: ARIA tree group is the correct role here
         <ul id={contentsId} className={CLS.childFields} role="group">
-          {entries.map(([childField, childValue], index) => (
+          {entries.map(([childField, childValue, entryKey], index) => (
             <DataRender
-              key={childField ?? index}
+              key={entryKey ?? childField ?? index}
               field={childField}
               value={childValue}
               isLast={index === lastIndex}
@@ -820,8 +880,8 @@ function makeBytesDisplay(display: FormattedStreamChunkDisplay): unknown {
  * non-expandable versions so the renderer doesn't show their internals.
  * Only recurses into plain objects and arrays to avoid stripping class
  * instances (Date, Error, URL, Headers, etc.) that have their own rendering.
- * Map and Set containers are preserved while their contents are prepared for
- * display.
+ * Map and Set contents are prepared here; other iterable contents are prepared
+ * when the renderer traverses them.
  *
  * Exported for testing the typed-array detection path used by hydrated
  * AI agent stream chunks (e.g. `{ delta: new Uint8Array(...) }`).
@@ -962,7 +1022,28 @@ function isSameBytesDisplay(a: BytesDisplay, b: BytesDisplay): boolean {
   );
 }
 
-function isDeepEqual(a: unknown, b: unknown, seen = new WeakMap()): boolean {
+function haveSameIterableValues(
+  a: Iterable<unknown>,
+  b: Iterable<unknown>,
+  seen: WeakMap<object, object>
+): boolean {
+  const aIterator = a[Symbol.iterator]();
+  const bIterator = b[Symbol.iterator]();
+  while (true) {
+    const aResult = aIterator.next();
+    const bResult = bIterator.next();
+    if (aResult.done || bResult.done) {
+      return aResult.done === bResult.done;
+    }
+    if (!isDeepEqual(aResult.value, bResult.value, seen)) return false;
+  }
+}
+
+export function isDeepEqual(
+  a: unknown,
+  b: unknown,
+  seen = new WeakMap()
+): boolean {
   if (Object.is(a, b)) return true;
 
   if (isBytesDisplay(a) || isBytesDisplay(b)) {
@@ -977,6 +1058,21 @@ function isDeepEqual(a: unknown, b: unknown, seen = new WeakMap()): boolean {
     return a.source === b.source && a.flags === b.flags;
   }
 
+  if (isGenericIterable(a) || isGenericIterable(b)) {
+    if (!isGenericIterable(a) || !isGenericIterable(b)) return false;
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+    if (isSelfIterableIterator(a) || isSelfIterableIterator(b)) return false;
+    if (seen.get(a) === b) return true;
+    seen.set(a, b);
+    const aHasEntries = isEntryIterable(a);
+    const bHasEntries = isEntryIterable(b);
+    if (aHasEntries !== bHasEntries) return false;
+    if (aHasEntries && bHasEntries) {
+      return haveSameIterableValues(a.entries(), b.entries(), seen);
+    }
+    return haveSameIterableValues(a, b, seen);
+  }
+
   if (a instanceof Map && b instanceof Map) {
     if (a.size !== b.size) return false;
     for (const [key, value] of a.entries()) {

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

@@ -150,6 +150,10 @@ export function waitToSpan(
   };
 }
 
+export type GetStepAttributes = (
+  events: Event[]
+) => Record<string, unknown> | undefined;
+
 export const stepEventsToStepEntity = (
   events: Event[]
 ): {
@@ -231,7 +235,11 @@ export const stepEventsToStepEntity = (
 /**
  * Converts step events to an OpenTelemetry Span
  */
-export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
+export function stepToSpan(
+  stepEvents: Event[],
+  maxEndTime: Date,
+  getStepAttributes?: GetStepAttributes
+): Span | null {
   const step = stepEventsToStepEntity(stepEvents);
   if (!step) {
     return null;
@@ -242,7 +250,11 @@ export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
 
   const attributes = {
     resource: 'step' as const,
-    data: step,
+    data: {
+      ...getStepAttributes?.(stepEvents),
+      // Canonical event-derived fields cannot be overridden by extensions.
+      ...step,
+    },
   };
 
   const resource = 'step';

package/src/lib/duplicate-events.ts

@@ -1,8 +1,9 @@
 import {
+  classifyEntityEvent,
   type EntityEventClass,
   type Event,
-  entityEventClass,
   isSlotEventId,
+  TERMINAL_EVENT_CLASSES,
 } from '@workflow/world';
 
 /**
@@ -10,13 +11,13 @@ import {
  *
  * Concurrent replays of one run write to a shared log, so a replay working
  * from a stale prefix can commit a second `step_created` / `step_started` /
- * `wait_created` for an entity the log already records one of. Every replay
- * reads the first event of that class at the same position, so a later one
- * cannot change what the workflow observes.
+ * `wait_created` / `attr_set` for an entity the log already records one of.
+ * Every replay reads the first event of that class at the same position, so a
+ * later one cannot change what the workflow observes.
  *
- * The classification mirrors `entityEventClass` in `@workflow/world`, which is
- * what the runtime keys its own duplicate detection on. What it cannot mirror
- * is consumer state: the runtime passes over an event only after every
+ * The classification comes from `classifyEntityEvent` in `@workflow/world`,
+ * the same function the runtime keys its own duplicate detection on. What it
+ * cannot share is consumer state: the runtime passes over an event only after every
  * registered callback has declined it, and a callback registered for a
  * still-open entity legitimately claims a repeat (each retry of a step writes
  * another `step_started`, and a live step consumer absorbs a second
@@ -25,27 +26,11 @@ import {
  * consumer remains.
  */
 
-/**
- * Classes whose event closes its entity: no consumer is left for it after.
- *
- * The run's own terminal events are absent because `entityEventClass` gives
- * them no class. The runtime exits rather than replaying the body once the log
- * holds one, so nothing ever consumes them and nothing can repeat them.
- */
-const TERMINAL_EVENT_CLASSES: ReadonlySet<EntityEventClass> = new Set([
-  'step_terminal',
-  'wait_completed',
-  'hook_disposed',
-]);
-
 /** Classes with no entity to close first: the log records one per run. */
 const SINGLETON_EVENT_CLASSES: ReadonlySet<EntityEventClass> = new Set([
   'run_started',
 ]);
 
-/** Entity key for events that carry no correlation ID (the run itself). */
-const RUN_ENTITY_KEY = '';
-
 /**
  * Shown against an event this module reports. Deliberately says what the log
  * shows rather than what the runtime did with it: tolerating these repeats is
@@ -122,10 +107,13 @@ function foldDuplicates(ordered: readonly Event[]): Set<string> {
   const closedEntities = new Set<string>();
 
   for (const event of ordered) {
-    const eventClass = entityEventClass(event.eventType);
-    if (eventClass === undefined) continue;
+    // Shared with the runtime's own duplicate detection, deliberately: an
+    // event it tracks under no class is one it never reads past, so naming it
+    // here would grey out an event the run acted on.
+    const classification = classifyEntityEvent(event);
+    if (classification === undefined) continue;
 
-    const entity = event.correlationId ?? RUN_ENTITY_KEY;
+    const { eventClass, entity } = classification;
     const classKey = `${eventClass}:${entity}`;
     const repeatsClass = seenClasses.has(classKey);
     const entityWasClosed = closedEntities.has(entity);

package/src/lib/trace-builder.test.ts

@@ -9,7 +9,11 @@ let nextId = 0;
 
 function event(
   eventType: EventType,
-  options: { correlationId?: string; at: number }
+  options: {
+    correlationId?: string;
+    at: number;
+    externalAttemptId?: string;
+  }
 ): Event {
   nextId += 1;
   return {
@@ -20,6 +24,7 @@ function event(
     createdAt: new Date(BASE_TIME + options.at * 1000),
     occurredAt: new Date(BASE_TIME + options.at * 1000),
     eventData: eventType === 'step_created' ? { stepName: 'doWork' } : {},
+    externalAttemptId: options.externalAttemptId,
   } as unknown as Event;
 }
 
@@ -31,6 +36,42 @@ const run = {
 } as unknown as WorkflowRun;
 
 describe('buildTrace', () => {
+  it('adds caller-derived attributes to step span data', () => {
+    const events = [
+      event('run_created', { at: 0 }),
+      event('run_started', { at: 0 }),
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', {
+        correlationId: 'step_a',
+        at: 2,
+        externalAttemptId: 'attempt_first',
+      }),
+      event('step_retrying', { correlationId: 'step_a', at: 3 }),
+      event('step_started', {
+        correlationId: 'step_a',
+        at: 4,
+        externalAttemptId: 'attempt_latest',
+      }),
+    ];
+
+    const trace = buildTrace(run, events, new Date(BASE_TIME + 5000), {
+      getStepAttributes(stepEvents) {
+        const latestStart = stepEvents
+          .slice()
+          .reverse()
+          .find((candidate) => candidate.eventType === 'step_started') as
+          | (Event & { externalAttemptId?: string })
+          | undefined;
+        return { externalAttemptId: latestStart?.externalAttemptId };
+      },
+    });
+    const stepSpan = trace.spans.find((span) => span.resource === 'step');
+
+    expect(stepSpan?.attributes.data).toMatchObject({
+      externalAttemptId: 'attempt_latest',
+    });
+  });
+
   it('ends a step span on the terminal event the run acted on', () => {
     const events = [
       event('run_created', { at: 0 }),

package/src/lib/trace-builder.ts

@@ -14,6 +14,7 @@ import {
   type WorkflowRun,
 } from '@workflow/world';
 import {
+  type GetStepAttributes,
   getEventTimestamp,
   hookToSpan,
   runToSpan,
@@ -137,7 +138,8 @@ function buildSpans(
   run: WorkflowRun,
   groupedEvents: GroupedEvents,
   now: Date,
-  latestKnownTime: Date
+  latestKnownTime: Date,
+  getStepAttributes?: GetStepAttributes
 ) {
   // 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
@@ -146,7 +148,7 @@ function buildSpans(
   const runMaxEnd = run.completedAt ?? now;
 
   const stepSpans = Array.from(groupedEvents.eventsByStepId.values())
-    .map((events) => stepToSpan(events, childMaxEnd))
+    .map((events) => stepToSpan(events, childMaxEnd, getStepAttributes))
     .filter((span): span is Span => span !== null);
 
   const hookSpans = Array.from(groupedEvents.hookEvents.values())
@@ -208,7 +210,13 @@ export function buildTrace(
    * from the only copy the caller was given, and dropping the wrong one moves
    * a span. See {@link findDuplicateEventIds}.
    */
-  { isCompleteHistory = false }: { isCompleteHistory?: boolean } = {}
+  {
+    isCompleteHistory = false,
+    getStepAttributes,
+  }: {
+    isCompleteHistory?: boolean;
+    getStepAttributes?: GetStepAttributes;
+  } = {}
 ): TraceWithMeta {
   // Span geometry comes from what the run acted on. A repeat of a class the
   // log already records is read past by every replay, and letting one through
@@ -232,7 +240,8 @@ export function buildTrace(
     run,
     groupedEvents,
     now,
-    latestKnownTime
+    latestKnownTime,
+    getStepAttributes
   );
   const sortedCascadingSpans = cascadeSpans(runSpan, spans);