@stigmer/react 3.1.17 → 3.2.1

package/src/workflow/execution/derive-waterfall-entries.ts

@@ -1,377 +0,0 @@
-/**
- * Pure derivation functions for the execution waterfall timeline.
- *
- * Converts an append-only event list into positioned waterfall entries
- * (horizontal bars on a time axis) and a scale specification for the
- * time axis labels/ticks.
- *
- * No React dependency — independently importable and testable (DD-003).
- *
- * @since T07 (Execution Waterfall Timeline)
- */
-
-import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
-import type { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
-import { WorkflowTaskKind as WTK } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
-import type { DerivedTaskState } from "../../internal/store/workflow-execution-event-store.js";
-
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-/** A single task row in the waterfall timeline. */
-export interface WaterfallEntry {
-  readonly taskName: string;
-  readonly taskKind: WorkflowTaskKind;
-  readonly status: DerivedTaskState["status"] | "not_reached";
-  /** Milliseconds offset from execution start. */
-  readonly startMs: number;
-  /** Milliseconds offset from execution start. `null` when task is still running. */
-  readonly endMs: number | null;
-  /** Duration from event payload, or computed from start/end. */
-  readonly durationMs: number;
-  readonly costMicros: bigint;
-  readonly tokensUsed: bigint;
-  /** Individual retry attempt segments (first attempt is always present). */
-  readonly attempts: readonly WaterfallAttempt[];
-  /** Nested spans (agent calls, tool calls). Populated when events exist. */
-  readonly children: readonly WaterfallSpan[];
-  /** Approval wait duration in ms, for compound bar segment. `null` if no approval. */
-  readonly approvalWaitMs: number | null;
-}
-
-/** One attempt within a retried task. */
-export interface WaterfallAttempt {
-  readonly attemptNumber: number;
-  /** Milliseconds offset from execution start. */
-  readonly startMs: number;
-  /** `null` when the attempt is still running. */
-  readonly endMs: number | null;
-  readonly status: "completed" | "failed" | "running";
-  /** Backoff delay in ms before this attempt (0 for the first attempt). */
-  readonly backoffMs: number;
-}
-
-/** A nested span within a task bar (e.g., agent call). */
-export interface WaterfallSpan {
-  readonly label: string;
-  /** Milliseconds offset from execution start. */
-  readonly startMs: number;
-  /** `null` when span is still active. */
-  readonly endMs: number | null;
-  readonly spanType: "agent_call" | "tool_call";
-}
-
-/** Time axis specification for the waterfall. */
-export interface WaterfallScale {
-  /** Total visible range in milliseconds. */
-  readonly totalMs: number;
-  /** Tick positions as ms offsets from execution start. */
-  readonly ticks: readonly number[];
-  /** Label interval — every Nth tick gets a label. */
-  readonly labelEveryN: number;
-}
-
-// ---------------------------------------------------------------------------
-// Internal accumulator
-// ---------------------------------------------------------------------------
-
-interface TaskAccumulator {
-  taskName: string;
-  taskKind: WorkflowTaskKind;
-  status: DerivedTaskState["status"] | "not_reached";
-  startMs: number;
-  endMs: number | null;
-  durationMs: number;
-  costMicros: bigint;
-  tokensUsed: bigint;
-  attempts: WaterfallAttempt[];
-  children: WaterfallSpan[];
-  approvalWaitMs: number | null;
-  currentAttemptStart: number;
-  currentAttemptNumber: number;
-}
-
-const BIGINT_ZERO = BigInt(0);
-
-// ---------------------------------------------------------------------------
-// deriveWaterfallEntries
-// ---------------------------------------------------------------------------
-
-/**
- * Derives positioned waterfall entries from an ordered event list.
- *
- * Walks the event list once (O(n)) to build entries with absolute
- * time positions relative to execution start. Handles retries as
- * stacked attempt segments and agent calls as nested child spans.
- *
- * @param events - Events ordered by sequence_number ascending.
- * @param executionStartIso - ISO 8601 timestamp of execution start
- *   (from `execution_started.occurred_at`). When empty/absent, falls
- *   back to the first event's `occurred_at`.
- */
-export function deriveWaterfallEntries(
-  events: readonly WorkflowExecutionEvent[],
-  executionStartIso: string,
-): readonly WaterfallEntry[] {
-  if (events.length === 0) return [];
-
-  const execStartEpoch = parseIsoMs(executionStartIso || events[0].occurredAt);
-  const tasks = new Map<string, TaskAccumulator>();
-
-  for (const evt of events) {
-    const taskName = evt.taskName;
-    const evtMs = parseIsoMs(evt.occurredAt) - execStartEpoch;
-    const p = evt.payload;
-
-    switch (p.case) {
-      case "taskStarted": {
-        const existing = tasks.get(taskName);
-        if (existing) {
-          // Retry: a new attempt on an existing task
-          existing.status = "running";
-          existing.currentAttemptStart = evtMs;
-          existing.currentAttemptNumber = p.value.attemptNumber;
-          existing.endMs = null;
-          existing.taskKind = p.value.taskKind;
-        } else {
-          tasks.set(taskName, {
-            taskName,
-            taskKind: p.value.taskKind,
-            status: "running",
-            startMs: evtMs,
-            endMs: null,
-            durationMs: 0,
-            costMicros: BIGINT_ZERO,
-            tokensUsed: BIGINT_ZERO,
-            attempts: [],
-            children: [],
-            approvalWaitMs: null,
-            currentAttemptStart: evtMs,
-            currentAttemptNumber: p.value.attemptNumber,
-          });
-        }
-        break;
-      }
-
-      case "taskCompleted": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          acc.status = "completed";
-          acc.endMs = evtMs;
-          acc.durationMs = Number(p.value.durationMs);
-          acc.costMicros = p.value.costMicros;
-          acc.tokensUsed = p.value.tokensUsed;
-          acc.attempts.push({
-            attemptNumber: acc.currentAttemptNumber,
-            startMs: acc.currentAttemptStart,
-            endMs: evtMs,
-            status: "completed",
-            backoffMs: acc.currentAttemptStart > acc.startMs && acc.attempts.length > 0
-              ? acc.currentAttemptStart - (acc.attempts[acc.attempts.length - 1].endMs ?? acc.currentAttemptStart)
-              : 0,
-          });
-        }
-        break;
-      }
-
-      case "taskFailed": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          const failStatus = p.value.willRetry ? "retrying" : "failed";
-          acc.status = failStatus;
-          acc.endMs = p.value.willRetry ? null : evtMs;
-          acc.durationMs = Number(p.value.durationMs);
-          acc.attempts.push({
-            attemptNumber: p.value.attemptNumber,
-            startMs: acc.currentAttemptStart,
-            endMs: evtMs,
-            status: "failed",
-            backoffMs: acc.currentAttemptStart > acc.startMs && acc.attempts.length > 0
-              ? acc.currentAttemptStart - (acc.attempts[acc.attempts.length - 1].endMs ?? acc.currentAttemptStart)
-              : 0,
-          });
-          if (!p.value.willRetry) {
-            acc.costMicros = BIGINT_ZERO;
-            acc.tokensUsed = BIGINT_ZERO;
-          }
-        }
-        break;
-      }
-
-      case "taskSkipped": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          acc.status = "skipped";
-          acc.endMs = evtMs;
-        } else {
-          tasks.set(taskName, {
-            taskName,
-            taskKind: p.value.taskKind,
-            status: "skipped",
-            startMs: evtMs,
-            endMs: evtMs,
-            durationMs: 0,
-            costMicros: BIGINT_ZERO,
-            tokensUsed: BIGINT_ZERO,
-            attempts: [],
-            children: [],
-            approvalWaitMs: null,
-            currentAttemptStart: evtMs,
-            currentAttemptNumber: 0,
-          });
-        }
-        break;
-      }
-
-      case "taskRetrying": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          acc.status = "retrying";
-        }
-        break;
-      }
-
-      case "approvalRequested": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          acc.status = "waiting_approval";
-        }
-        break;
-      }
-
-      case "approvalResolved": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          acc.status = "running";
-          acc.approvalWaitMs = Number(p.value.waitDurationMs);
-        }
-        break;
-      }
-
-      case "agentCallStarted": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          acc.children.push({
-            label: p.value.agentSlug || "agent",
-            startMs: evtMs,
-            endMs: null,
-            spanType: "agent_call",
-          });
-        }
-        break;
-      }
-
-      case "agentCallCompleted": {
-        const acc = tasks.get(taskName);
-        if (acc) {
-          const lastChild = acc.children[acc.children.length - 1];
-          if (lastChild && lastChild.spanType === "agent_call" && lastChild.endMs === null) {
-            // Mutate the last child span to close it
-            (acc.children as WaterfallSpan[])[acc.children.length - 1] = {
-              ...lastChild,
-              endMs: evtMs,
-            };
-          }
-          acc.costMicros = p.value.costMicros;
-          acc.tokensUsed = p.value.tokensConsumed;
-        }
-        break;
-      }
-    }
-  }
-
-  // Convert accumulators to immutable entries, ordered by startMs
-  const entries: WaterfallEntry[] = [];
-  for (const acc of tasks.values()) {
-    entries.push({
-      taskName: acc.taskName,
-      taskKind: acc.taskKind,
-      status: acc.status,
-      startMs: acc.startMs,
-      endMs: acc.endMs,
-      durationMs: acc.durationMs,
-      costMicros: acc.costMicros,
-      tokensUsed: acc.tokensUsed,
-      attempts: acc.attempts,
-      children: acc.children,
-      approvalWaitMs: acc.approvalWaitMs,
-    });
-  }
-
-  entries.sort((a, b) => a.startMs - b.startMs);
-  return entries;
-}
-
-// ---------------------------------------------------------------------------
-// deriveWaterfallScale
-// ---------------------------------------------------------------------------
-
-/**
- * Nice tick intervals for the time axis. Each value is a duration in ms.
- * The algorithm picks the smallest interval that produces <= MAX_TICKS ticks.
- */
-const NICE_INTERVALS = [
-  10, 20, 50, 100, 200, 500,
-  1_000, 2_000, 5_000, 10_000, 15_000, 30_000,
-  60_000, 120_000, 300_000, 600_000, 900_000, 1_800_000,
-  3_600_000, 7_200_000, 14_400_000, 28_800_000, 86_400_000,
-];
-
-const MAX_TICKS = 12;
-
-/**
- * Computes a time axis scale for the waterfall.
- *
- * @param entries - Waterfall entries (used to find the max extent).
- * @param executionDurationMs - Total execution duration. When the execution
- *   is still running, pass `Date.now() - executionStartEpoch`.
- */
-export function deriveWaterfallScale(
-  entries: readonly WaterfallEntry[],
-  executionDurationMs: number,
-): WaterfallScale {
-  // Find the maximum time extent across all entries
-  let maxMs = executionDurationMs;
-  for (const entry of entries) {
-    const entryEnd = entry.endMs ?? executionDurationMs;
-    if (entryEnd > maxMs) maxMs = entryEnd;
-  }
-
-  if (maxMs <= 0) maxMs = 1000; // minimum 1 second range
-
-  // Pick the smallest nice interval that yields <= MAX_TICKS ticks
-  let interval = NICE_INTERVALS[NICE_INTERVALS.length - 1];
-  for (const candidate of NICE_INTERVALS) {
-    if (Math.ceil(maxMs / candidate) <= MAX_TICKS) {
-      interval = candidate;
-      break;
-    }
-  }
-
-  const ticks: number[] = [];
-  for (let t = 0; t <= maxMs; t += interval) {
-    ticks.push(t);
-  }
-  // Ensure we don't exceed the total range by more than one tick
-  if (ticks.length > 0 && ticks[ticks.length - 1] < maxMs) {
-    ticks.push(ticks[ticks.length - 1] + interval);
-  }
-
-  // For very dense ticks, label every other one
-  const labelEveryN = ticks.length > 8 ? 2 : 1;
-
-  const totalMs = ticks.length > 0 ? ticks[ticks.length - 1] : maxMs;
-
-  return { totalMs, ticks, labelEveryN };
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function parseIsoMs(iso: string): number {
-  if (!iso) return 0;
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime()) ? 0 : d.getTime();
-}

package/src/workflow/execution/useWaterfallEntries.ts

@@ -1,125 +0,0 @@
-"use client";
-
-/**
- * React behavior hook for the execution waterfall timeline.
- *
- * Derives waterfall entries from the event stream, manages live-growing
- * bars via `requestAnimationFrame` during streaming, and provides a
- * stable `scrollToTask` callback for graph-timeline synchronization.
- *
- * Follows DD-003 (headless-first) and DD-010 (referential stability).
- *
- * @since T07 (Execution Waterfall Timeline)
- */
-
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
-import type { WorkflowEventStreamState } from "../../internal/store/workflow-execution-event-store.js";
-import {
-  deriveWaterfallEntries,
-  deriveWaterfallScale,
-  type WaterfallEntry,
-  type WaterfallScale,
-} from "./derive-waterfall-entries.js";
-
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-export interface UseWaterfallEntriesOptions {
-  /** Events ordered by sequence_number ascending. */
-  readonly events: readonly WorkflowExecutionEvent[];
-  /** Current stream lifecycle state. */
-  readonly streamState: WorkflowEventStreamState;
-  /** ISO 8601 timestamp of execution start. */
-  readonly executionStartIso: string;
-  /** Total execution duration in ms (for completed executions). */
-  readonly executionDurationMs?: number;
-}
-
-export interface UseWaterfallEntriesReturn {
-  /** Waterfall entries (one per task, ordered by start time). */
-  readonly entries: readonly WaterfallEntry[];
-  /** Time axis scale specification. */
-  readonly scale: WaterfallScale;
-  /** True when the execution is live (bars may be growing). */
-  readonly isLive: boolean;
-  /** Current elapsed ms from execution start (updates via rAF when live). */
-  readonly nowMs: number;
-}
-
-// ---------------------------------------------------------------------------
-// Hook
-// ---------------------------------------------------------------------------
-
-const EMPTY_ENTRIES: readonly WaterfallEntry[] = [];
-const EMPTY_SCALE: WaterfallScale = { totalMs: 1000, ticks: [0, 1000], labelEveryN: 1 };
-
-export function useWaterfallEntries({
-  events,
-  streamState,
-  executionStartIso,
-  executionDurationMs,
-}: UseWaterfallEntriesOptions): UseWaterfallEntriesReturn {
-  const isLive =
-    streamState.stage === "streaming" || streamState.stage === "reconnecting";
-  const execStartEpoch = useMemo(
-    () => (executionStartIso ? new Date(executionStartIso).getTime() : 0),
-    [executionStartIso],
-  );
-
-  // --- Live clock (rAF-driven nowMs for growing bars) ---
-
-  const [nowMs, setNowMs] = useState(() =>
-    execStartEpoch > 0 ? Date.now() - execStartEpoch : 0,
-  );
-  const rafRef = useRef<number>(0);
-
-  useEffect(() => {
-    if (!isLive || execStartEpoch === 0) {
-      if (rafRef.current) cancelAnimationFrame(rafRef.current);
-      return;
-    }
-
-    let mounted = true;
-    const tick = () => {
-      if (!mounted) return;
-      setNowMs(Date.now() - execStartEpoch);
-      rafRef.current = requestAnimationFrame(tick);
-    };
-    rafRef.current = requestAnimationFrame(tick);
-
-    return () => {
-      mounted = false;
-      if (rafRef.current) cancelAnimationFrame(rafRef.current);
-    };
-  }, [isLive, execStartEpoch]);
-
-  // When execution completes, snap to final duration
-  useEffect(() => {
-    if (!isLive && executionDurationMs != null && executionDurationMs > 0) {
-      setNowMs(executionDurationMs);
-    }
-  }, [isLive, executionDurationMs]);
-
-  // --- Derive entries (memoized on event list length) ---
-
-  const entries = useMemo(() => {
-    if (events.length === 0) return EMPTY_ENTRIES;
-    return deriveWaterfallEntries(events, executionStartIso);
-  }, [events, executionStartIso]);
-
-  // --- Derive scale ---
-
-  const effectiveDuration = isLive ? nowMs : (executionDurationMs ?? nowMs);
-
-  const scale = useMemo(() => {
-    if (entries.length === 0) return EMPTY_SCALE;
-    return deriveWaterfallScale(entries, effectiveDuration);
-  }, [entries, effectiveDuration]);
-
-  return useMemo(
-    () => ({ entries, scale, isLive, nowMs }),
-    [entries, scale, isLive, nowMs],
-  );
-}

package/src/workflow/execution-inspector/AgentCallTab.tsx

@@ -1,169 +0,0 @@
-"use client";
-
-import { memo, useMemo } from "react";
-import { cn } from "@stigmer/theme";
-import type { TaskDetailAgentCall } from "./derive-task-detail.js";
-import type { DerivedTaskState } from "../../internal/store/workflow-execution-event-store.js";
-import { formatMicroUsd, formatTokenCount } from "../format-utils.js";
-import { useExecutionStream } from "../../execution/useExecutionStream.js";
-import { useConversationStoreRef } from "../../internal/store/index.js";
-import { MessageThread } from "../../execution/MessageThread.js";
-
-export interface AgentCallTabProps {
-  readonly agentCall: TaskDetailAgentCall;
-  readonly taskStatus?: DerivedTaskState["status"];
-  readonly isTabActive?: boolean;
-  readonly onNavigateToAgentExecution?: (id: string) => void;
-  readonly className?: string;
-}
-
-/**
- * Agent Call tab in the execution inspector.
- *
- * When the task is running and childExecutionId is known, subscribes to
- * the child AgentExecution stream and renders a live MessageThread.
- * When complete or ID is unavailable, shows a static summary.
- *
- * Subscription lifecycle follows DD-LIVE-006: only subscribes when the tab
- * is active and the task is running. Unsubscribes on unmount or deactivation.
- */
-export const AgentCallTab = memo(function AgentCallTab({
-  agentCall,
-  taskStatus,
-  isTabActive = true,
-  onNavigateToAgentExecution,
-  className,
-}: AgentCallTabProps) {
-  const isRunning = taskStatus === "running" || taskStatus === "waiting_approval";
-  const hasChildId = !!agentCall.childExecutionId;
-  const shouldSubscribe = isTabActive && isRunning && hasChildId;
-
-  const effectiveId = shouldSubscribe ? agentCall.childExecutionId : null;
-  const store = useConversationStoreRef();
-  const { execution: streamExecution, isStreaming, isConnecting, error: streamError } =
-    useExecutionStream(effectiveId, { store });
-
-  const emptyExecutions = useMemo(() => [] as const, []);
-
-  const BZ = BigInt(0);
-
-  if (isRunning && hasChildId) {
-    return (
-      <div className={cn("flex flex-col gap-2", className)}>
-        {/* Stream status bar */}
-        <div className="flex items-center gap-2 text-[11px]">
-          {isConnecting && (
-            <span className="text-muted-foreground">Connecting to agent stream...</span>
-          )}
-          {isStreaming && (
-            <span className="text-primary">
-              <span className="mr-1 inline-block size-1.5 animate-pulse rounded-full bg-primary" />
-              Live
-            </span>
-          )}
-          {streamError && (
-            <span className="text-destructive">Stream error</span>
-          )}
-          <span className="ml-auto text-muted-foreground">{agentCall.agentSlug}</span>
-        </div>
-
-        {/* Live message transcript */}
-        <div className="min-h-0 flex-1 overflow-y-auto rounded border border-border">
-          <MessageThread
-            executions={emptyExecutions}
-            activeStreamExecution={streamExecution ?? undefined}
-            className="max-h-[50vh]"
-          />
-        </div>
-
-        {/* Navigation link */}
-        {onNavigateToAgentExecution && (
-          <button
-            type="button"
-            onClick={() => onNavigateToAgentExecution(agentCall.childExecutionId)}
-            className="self-start rounded border border-border px-2.5 py-1.5 text-xs font-medium text-primary hover:bg-muted"
-          >
-            Open Full Session
-          </button>
-        )}
-      </div>
-    );
-  }
-
-  if (isRunning && !hasChildId) {
-    return (
-      <div className={cn("flex flex-col items-center justify-center gap-2 py-8", className)}>
-        <div className="size-5 animate-spin rounded-full border-2 border-muted border-t-primary" />
-        <p className="text-xs text-muted-foreground">Waiting for agent to start...</p>
-        <p className="text-[11px] text-muted-foreground">{agentCall.agentSlug}</p>
-      </div>
-    );
-  }
-
-  return (
-    <div className={cn("flex flex-col gap-3", className)}>
-      <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1.5 text-xs">
-        <dt className="text-muted-foreground">Agent</dt>
-        <dd className="font-medium text-foreground">{agentCall.agentSlug}</dd>
-
-        {agentCall.agentPhase && (
-          <>
-            <dt className="text-muted-foreground">Phase</dt>
-            <dd className="text-foreground">{agentCall.agentPhase}</dd>
-          </>
-        )}
-
-        {agentCall.messagesCount > 0 && (
-          <>
-            <dt className="text-muted-foreground">Messages</dt>
-            <dd className="tabular-nums text-foreground">{agentCall.messagesCount}</dd>
-          </>
-        )}
-
-        {agentCall.toolCallsCount > 0 && (
-          <>
-            <dt className="text-muted-foreground">Tool calls</dt>
-            <dd className="tabular-nums text-foreground">{agentCall.toolCallsCount}</dd>
-          </>
-        )}
-
-        {agentCall.currentToolName && (
-          <>
-            <dt className="text-muted-foreground">Current tool</dt>
-            <dd className="text-foreground">{agentCall.currentToolName}</dd>
-          </>
-        )}
-
-        {agentCall.tokensConsumed > BZ && (
-          <>
-            <dt className="text-muted-foreground">Tokens</dt>
-            <dd className="tabular-nums text-foreground">{formatTokenCount(agentCall.tokensConsumed)}</dd>
-          </>
-        )}
-
-        {agentCall.costMicros > BZ && (
-          <>
-            <dt className="text-muted-foreground">Cost</dt>
-            <dd className="tabular-nums text-foreground">{formatMicroUsd(agentCall.costMicros)}</dd>
-          </>
-        )}
-      </dl>
-
-      {agentCall.error && (
-        <div className="rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2" role="alert">
-          <p className="text-xs text-destructive">{agentCall.error}</p>
-        </div>
-      )}
-
-      {onNavigateToAgentExecution && agentCall.childExecutionId && (
-        <button
-          type="button"
-          onClick={() => onNavigateToAgentExecution(agentCall.childExecutionId)}
-          className="self-start rounded border border-border px-2.5 py-1.5 text-xs font-medium text-primary hover:bg-muted"
-        >
-          View Agent Execution
-        </button>
-      )}
-    </div>
-  );
-});