@workflow/web-shared 4.1.0-beta.47 → 4.1.0-beta.49

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

@@ -0,0 +1,299 @@
+/**
+ * Functions for constructing OpenTelemetry spans from workflow entities
+ */
+
+import { parseStepName, parseWorkflowName } from '@workflow/utils/parse-name';
+import type { Event, Step, WorkflowRun } from '@workflow/world';
+import type { Span, SpanEvent } from '../trace-viewer/types';
+import { shouldShowVerticalLine } from './event-colors';
+import { calculateDuration, dateToOtelTime } from './trace-time-utils';
+
+export const WORKFLOW_LIBRARY = {
+  name: 'workflow-development-kit',
+  version: '4.0.0',
+};
+
+/**
+ * Event types that should be displayed as visual markers in the trace viewer
+ */
+const MARKER_EVENT_TYPES: Set<Event['eventType']> = new Set([
+  'hook_created',
+  'hook_received',
+  'hook_disposed',
+  'step_started',
+  'step_retrying',
+  'step_failed',
+  'run_failed',
+  'wait_created',
+  'wait_completed',
+]);
+
+/**
+ * Convert workflow events to span events
+ * Only includes events that should be displayed as markers
+ */
+export function convertEventsToSpanEvents(
+  events: Event[],
+  filterTypes = true
+): SpanEvent[] {
+  return events
+    .filter((event) =>
+      filterTypes ? MARKER_EVENT_TYPES.has(event.eventType) : true
+    )
+    .map((event) => ({
+      name: event.eventType,
+      timestamp: dateToOtelTime(event.createdAt),
+      attributes: {
+        eventId: event.eventId,
+        correlationId: event.correlationId,
+        eventData: 'eventData' in event ? event.eventData : undefined,
+      },
+      // Control whether to show vertical line in timeline
+      showVerticalLine: shouldShowVerticalLine(event.eventType),
+    }));
+}
+
+export const waitEventsToWaitEntity = (
+  events: Event[]
+): {
+  waitId: string;
+  runId: string;
+  createdAt: Date;
+  resumeAt: Date;
+  completedAt?: Date;
+} | null => {
+  const startEvent = events.find((event) => event.eventType === 'wait_created');
+  if (!startEvent) {
+    return null;
+  }
+  const completedEvent = events.find(
+    (event) => event.eventType === 'wait_completed'
+  );
+  return {
+    waitId: startEvent.correlationId,
+    runId: startEvent.runId,
+    createdAt: startEvent.createdAt,
+    resumeAt: startEvent.eventData?.resumeAt,
+    completedAt: completedEvent?.createdAt,
+  };
+};
+
+/**
+ * Converts a workflow Wait to an OpenTelemetry Span
+ */
+export function waitToSpan(
+  events: Event[],
+  run: WorkflowRun,
+  nowTime: 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 start = dateToOtelTime(startTime);
+  const end = dateToOtelTime(endTime);
+  const duration = calculateDuration(startTime, endTime);
+  const spanEvents = convertEventsToSpanEvents(events);
+  return {
+    spanId: wait.waitId,
+    name: 'sleep',
+    kind: 1, // INTERNAL span kind
+    resource: 'sleep',
+    library: WORKFLOW_LIBRARY,
+    status: { code: 0 },
+    traceFlags: 1,
+    attributes: {
+      resource: 'sleep' as const,
+      data: wait,
+    },
+    links: [],
+    events: spanEvents,
+    duration,
+    startTime: start,
+    endTime: end,
+  };
+}
+
+/**
+ * Converts a workflow Step to an OpenTelemetry Span
+ */
+export function stepToSpan(
+  step: Step,
+  stepEvents: Event[],
+  nowTime?: Date
+): Span {
+  const now = nowTime ?? new Date();
+  const parsedName = parseStepName(String(step.stepName));
+
+  // Simplified attributes: only store resource type and full data
+  const attributes = {
+    resource: 'step' as const,
+    data: step,
+  };
+
+  const resource = 'step';
+  const endTime = new Date(step.completedAt ?? now);
+
+  // Convert step-related events to span events (for markers like hook_created, step_retrying, etc.)
+  // This determines which events are displayed as markers. In the detail view,
+  // we'll show all events that correlate with the selected resource.
+  const events = convertEventsToSpanEvents(stepEvents);
+
+  // Use createdAt as span start time, with activeStartTime for when execution began
+  // This allows visualization of the "queued" period before execution
+  const spanStartTime = new Date(step.createdAt);
+  let activeStartTime = step.startedAt ? new Date(step.startedAt) : undefined;
+  const firstStartEvent = stepEvents.find(
+    (event) => event.eventType === 'step_started'
+  );
+  if (firstStartEvent) {
+    // `step.startedAt` is the server-side creation timestamp, and `event.createdAt` is
+    // the client-side creation timestamp. For now, to align the event marker with the
+    // line we show for step.startedAt, we overwrite here to always use client-side time.
+    activeStartTime = new Date(firstStartEvent.createdAt);
+  }
+
+  return {
+    spanId: String(step.stepId),
+    name: parsedName?.shortName ?? '',
+    kind: 1, // INTERNAL span kind
+    resource,
+    library: WORKFLOW_LIBRARY,
+    status: { code: 0 },
+    traceFlags: 1,
+    attributes,
+    links: [],
+    events,
+    startTime: dateToOtelTime(spanStartTime),
+    endTime: dateToOtelTime(endTime),
+    duration: calculateDuration(spanStartTime, endTime),
+    // Only set activeStartTime if it differs from startTime (i.e., there was a queued period)
+    activeStartTime:
+      activeStartTime && activeStartTime.getTime() > spanStartTime.getTime()
+        ? dateToOtelTime(activeStartTime)
+        : undefined,
+  };
+}
+
+export const hookEventsToHookEntity = (
+  events: Event[]
+): {
+  hookId: string;
+  runId: string;
+  createdAt: Date;
+  receivedCount: number;
+  lastReceivedAt?: Date;
+  disposedAt?: Date;
+} | null => {
+  const createdEvent = events.find(
+    (event) => event.eventType === 'hook_created'
+  );
+  if (!createdEvent) {
+    return null;
+  }
+  const receivedEvents = events.filter(
+    (event) => event.eventType === 'hook_received'
+  );
+  const disposedEvents = events.filter(
+    (event) => event.eventType === 'hook_disposed'
+  );
+  const lastReceivedEvent = receivedEvents.at(-1);
+  return {
+    hookId: createdEvent.correlationId,
+    runId: createdEvent.runId,
+    createdAt: createdEvent.createdAt,
+    receivedCount: receivedEvents.length,
+    lastReceivedAt: lastReceivedEvent?.createdAt || undefined,
+    disposedAt: disposedEvents.at(-1)?.createdAt || undefined,
+  };
+};
+
+/**
+ * Converts a workflow Hook to an OpenTelemetry Span
+ */
+export function hookToSpan(
+  hookEvents: Event[],
+  run: WorkflowRun,
+  nowTime: Date
+): Span | null {
+  const hook = hookEventsToHookEntity(hookEvents);
+  if (!hook) {
+    return null;
+  }
+
+  // Convert hook-related events to span events
+  const events = convertEventsToSpanEvents(hookEvents);
+
+  // 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;
+
+  return {
+    spanId: String(hook.hookId),
+    name: String(hook.hookId),
+    kind: 1, // INTERNAL span kind
+    resource: 'hook',
+    library: WORKFLOW_LIBRARY,
+    status: { code: 1 },
+    traceFlags: 1,
+    attributes: {
+      resource: 'hook' as const,
+      data: hook,
+    },
+    links: [],
+    events,
+    startTime: dateToOtelTime(hook.createdAt),
+    endTime: dateToOtelTime(endTime),
+    duration: calculateDuration(hook.createdAt, endTime),
+  };
+}
+
+/**
+ * Creates a root span for the workflow run
+ */
+export function runToSpan(
+  run: WorkflowRun,
+  runEvents: Event[],
+  nowTime?: Date
+): Span {
+  const now = nowTime ?? new Date();
+
+  // Simplified attributes: only store resource type and full data
+  const attributes = {
+    resource: 'run' as const,
+    data: run,
+  };
+
+  // Use createdAt as span start time, with activeStartTime for when execution began
+  const spanStartTime = new Date(run.createdAt);
+  const activeStartTime = run.startedAt ? new Date(run.startedAt) : undefined;
+  const endTime = run.completedAt ?? now;
+
+  // Convert run-level events to span events
+  const events = convertEventsToSpanEvents(runEvents);
+
+  return {
+    spanId: String(run.runId),
+    name: String(parseWorkflowName(run.workflowName)?.shortName ?? '?'),
+    kind: 1, // INTERNAL span kind
+    resource: 'run',
+    library: WORKFLOW_LIBRARY,
+    status: { code: 0 },
+    traceFlags: 1,
+    attributes,
+    links: [],
+    events,
+    startTime: dateToOtelTime(spanStartTime),
+    endTime: dateToOtelTime(endTime),
+    duration: calculateDuration(spanStartTime, endTime),
+    // Only set activeStartTime if it differs from startTime (i.e., there was a queued period)
+    activeStartTime:
+      activeStartTime && activeStartTime.getTime() > spanStartTime.getTime()
+        ? dateToOtelTime(activeStartTime)
+        : undefined,
+  };
+}

package/src/components/workflow-traces/trace-time-utils.ts

@@ -0,0 +1,50 @@
+/**
+ * Time conversion utilities for workflow trace construction
+ */
+
+/**
+ * Converts a Date to OpenTelemetry time format [seconds, nanoseconds]
+ */
+export function dateToOtelTime(
+  date: Date | string | unknown
+): [number, number] {
+  if (typeof date === 'string') {
+    date = new Date(date);
+  }
+  if (!date || !(date instanceof Date)) {
+    return [0, 0];
+  }
+  const ms = date.getTime();
+  const seconds = Math.floor(ms / 1000);
+  const nanoseconds = (ms % 1000) * 1_000_000;
+  return [seconds, nanoseconds];
+}
+
+export function otelTimeToMs(time: [number, number]): number {
+  const secondsToMs = time[0] * 1_000;
+  const nanosecondsToMs = time[1] / 1_000_000;
+  return secondsToMs + nanosecondsToMs;
+}
+
+/**
+ * Calculates duration in [seconds, nanoseconds] format
+ */
+export function calculateDuration(
+  start: Date | string | unknown,
+  end: Date | string | unknown
+): [number, number] {
+  if (typeof start === 'string') {
+    start = new Date(start);
+  }
+  if (typeof end === 'string') {
+    end = new Date(end);
+  }
+  if (!start || !(start instanceof Date)) {
+    return [0, 0];
+  }
+  const endTime = end && end instanceof Date ? end : new Date();
+  const durationMs = endTime.getTime() - start.getTime();
+  const seconds = Math.floor(durationMs / 1000);
+  const nanoseconds = (durationMs % 1000) * 1_000_000;
+  return [seconds, nanoseconds];
+}

package/src/hooks/use-dark-mode.ts

@@ -0,0 +1,34 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Hook that detects if dark mode is active and reacts to theme changes.
+ * Observes the 'dark' class on the document element, which is how
+ * next-themes and similar libraries apply the theme.
+ *
+ * @returns `true` if dark mode is active, `false` otherwise
+ */
+export const useDarkMode = (): boolean => {
+  const [isDark, setIsDark] = useState(() => {
+    if (typeof document === 'undefined') return false;
+    return document.documentElement.classList.contains('dark');
+  });
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    const observer = new MutationObserver(() => {
+      setIsDark(document.documentElement.classList.contains('dark'));
+    });
+
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class'],
+    });
+
+    return () => observer.disconnect();
+  }, []);
+
+  return isDark;
+};

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './index';

package/src/index.ts

@@ -0,0 +1,29 @@
+export type {
+  HealthCheckEndpoint,
+  HealthCheckResult,
+} from '@workflow/core/runtime';
+export {
+  parseStepName,
+  parseWorkflowName,
+} from '@workflow/utils/parse-name';
+export type { Event, Hook, Step, WorkflowRun } from '@workflow/world';
+export * from './components';
+export {
+  hookEventsToHookEntity,
+  waitEventsToWaitEntity,
+} from './components/workflow-traces/trace-span-construction';
+export type { EventAnalysis } from './lib/event-analysis';
+export {
+  analyzeEvents,
+  hasPendingHooksFromEvents,
+  hasPendingStepsFromEvents,
+  isTerminalStatus,
+  shouldShowReenqueueButton,
+} from './lib/event-analysis';
+export type { StreamStep } from './lib/utils';
+export {
+  extractConversation,
+  formatDuration,
+  identifyStreamSteps,
+  isDoStreamStep,
+} from './lib/utils';

package/src/lib/event-analysis.ts

@@ -0,0 +1,231 @@
+/**
+ * Shared utilities for analyzing workflow events.
+ * Used by run-actions and trace viewer components.
+ */
+
+import type { Event, WorkflowRunStatus } from '@workflow/world';
+
+// Time thresholds for Re-enqueue button visibility
+const STEP_ACTIVITY_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const STEP_IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Result of analyzing events for a workflow run
+ */
+export interface EventAnalysis {
+  /** Whether there are pending sleep/wait calls */
+  hasPendingSleeps: boolean;
+  /** Whether there are pending steps (started but not completed/failed) */
+  hasPendingSteps: boolean;
+  /** Whether there are pending hooks (created but not disposed) */
+  hasPendingHooks: boolean;
+  /** Correlation IDs of pending sleeps */
+  pendingSleepIds: string[];
+  /** Correlation IDs of pending steps */
+  pendingStepIds: string[];
+  /** Correlation IDs of pending hooks */
+  pendingHookIds: string[];
+  /** Timestamp of the last step_started or step_retrying event */
+  lastStepActivityAt: Date | null;
+  /** Timestamp of the last step completion (step_completed or step_failed) */
+  lastStepCompletionAt: Date | null;
+}
+
+/**
+ * Analyze events to determine pending sleeps, steps, and hooks.
+ */
+export function analyzeEvents(events: Event[] | undefined): EventAnalysis {
+  if (!events || events.length === 0) {
+    return {
+      hasPendingSleeps: false,
+      hasPendingSteps: false,
+      hasPendingHooks: false,
+      pendingSleepIds: [],
+      pendingStepIds: [],
+      pendingHookIds: [],
+      lastStepActivityAt: null,
+      lastStepCompletionAt: null,
+    };
+  }
+
+  // Group events by correlation ID for each type
+  const waitCreated = new Map<string, Event>();
+  const waitCompleted = new Set<string>();
+  const stepStarted = new Map<string, Event>();
+  const stepCompleted = new Set<string>();
+  const hookCreated = new Map<string, Event>();
+  const hookDisposed = new Set<string>();
+
+  let lastStepActivityAt: Date | null = null;
+  let lastStepCompletionAt: Date | null = null;
+
+  for (const event of events) {
+    const correlationId = event.correlationId;
+    if (!correlationId) continue;
+
+    switch (event.eventType) {
+      // Sleeps/Waits
+      case 'wait_created':
+        waitCreated.set(correlationId, event);
+        break;
+      case 'wait_completed':
+        waitCompleted.add(correlationId);
+        break;
+
+      // Steps
+      case 'step_started':
+        stepStarted.set(correlationId, event);
+        if (
+          !lastStepActivityAt ||
+          new Date(event.createdAt) > lastStepActivityAt
+        ) {
+          lastStepActivityAt = new Date(event.createdAt);
+        }
+        break;
+      case 'step_retrying':
+        if (
+          !lastStepActivityAt ||
+          new Date(event.createdAt) > lastStepActivityAt
+        ) {
+          lastStepActivityAt = new Date(event.createdAt);
+        }
+        break;
+      case 'step_completed':
+      case 'step_failed':
+        stepCompleted.add(correlationId);
+        if (
+          !lastStepCompletionAt ||
+          new Date(event.createdAt) > lastStepCompletionAt
+        ) {
+          lastStepCompletionAt = new Date(event.createdAt);
+        }
+        break;
+
+      // Hooks
+      case 'hook_created':
+        hookCreated.set(correlationId, event);
+        break;
+      case 'hook_disposed':
+        hookDisposed.add(correlationId);
+        break;
+    }
+  }
+
+  // Find pending items (created but not completed)
+  const pendingSleepIds = Array.from(waitCreated.keys()).filter(
+    (id) => !waitCompleted.has(id)
+  );
+  const pendingStepIds = Array.from(stepStarted.keys()).filter(
+    (id) => !stepCompleted.has(id)
+  );
+  const pendingHookIds = Array.from(hookCreated.keys()).filter(
+    (id) => !hookDisposed.has(id)
+  );
+
+  return {
+    hasPendingSleeps: pendingSleepIds.length > 0,
+    hasPendingSteps: pendingStepIds.length > 0,
+    hasPendingHooks: pendingHookIds.length > 0,
+    pendingSleepIds,
+    pendingStepIds,
+    pendingHookIds,
+    lastStepActivityAt,
+    lastStepCompletionAt,
+  };
+}
+
+/**
+ * Check if a workflow run status is terminal (completed, failed, or cancelled)
+ */
+export function isTerminalStatus(
+  status: WorkflowRunStatus | undefined
+): boolean {
+  return (
+    status === 'completed' || status === 'failed' || status === 'cancelled'
+  );
+}
+
+/**
+ * Determine if the Re-enqueue button should be shown without the debug flag.
+ *
+ * The Re-enqueue button is shown when the workflow appears to be stuck:
+ * - The workflow is not in a terminal state
+ * - There are no pending sleeps (which would show the Wake up button instead)
+ * - There are no pending hooks (which are waiting for external input)
+ * - Either:
+ *   - The last step_started or step_retrying event was >30 minutes ago, OR
+ *   - There have been no pending steps for >5 minutes (all steps completed/failed)
+ */
+export function shouldShowReenqueueButton(
+  events: Event[] | undefined,
+  status: WorkflowRunStatus | undefined
+): boolean {
+  // Never show if in terminal state
+  if (isTerminalStatus(status)) {
+    return false;
+  }
+
+  const analysis = analyzeEvents(events);
+
+  // Don't show if there are pending sleeps (Wake up button handles this)
+  if (analysis.hasPendingSleeps) {
+    return false;
+  }
+
+  // Don't show if there are pending hooks (waiting for external input)
+  if (analysis.hasPendingHooks) {
+    return false;
+  }
+
+  const now = Date.now();
+
+  // Check if last step activity was >30 minutes ago
+  if (analysis.lastStepActivityAt) {
+    const timeSinceLastActivity = now - analysis.lastStepActivityAt.getTime();
+    if (timeSinceLastActivity > STEP_ACTIVITY_TIMEOUT_MS) {
+      return true;
+    }
+  }
+
+  // Check if there are no pending steps and last completion was >5 minutes ago
+  if (!analysis.hasPendingSteps && analysis.lastStepCompletionAt) {
+    const timeSinceLastCompletion =
+      now - analysis.lastStepCompletionAt.getTime();
+    if (timeSinceLastCompletion > STEP_IDLE_TIMEOUT_MS) {
+      return true;
+    }
+  }
+
+  // If there's no step activity at all but the run is not terminal,
+  // and we've been waiting for a while, show the button
+  if (
+    !analysis.lastStepActivityAt &&
+    !analysis.hasPendingSteps &&
+    !analysis.hasPendingSleeps &&
+    !analysis.hasPendingHooks
+  ) {
+    // This case handles runs that haven't started any steps yet
+    // but aren't in a terminal state - they might be stuck
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if there are pending steps from an events list.
+ */
+export function hasPendingStepsFromEvents(
+  events: Event[] | undefined
+): boolean {
+  return analyzeEvents(events).hasPendingSteps;
+}
+
+/**
+ * Check if there are pending hooks from an events list.
+ */
+export function hasPendingHooksFromEvents(
+  events: Event[] | undefined
+): boolean {
+  return analyzeEvents(events).hasPendingHooks;
+}