@stigmer/react 0.5.1 → 1.0.0

package/src/internal/store/index.ts

@@ -6,6 +6,12 @@ import { ConversationStore, type StreamState } from "./conversation-store";
 
 export { ConversationStore, type StreamState } from "./conversation-store";
 export { structuralShare } from "./structural-share";
+export {
+  WorkflowExecutionEventStore,
+  type WorkflowEventStreamState,
+  type DerivedTaskState,
+  type DerivedCostSummary,
+} from "./workflow-execution-event-store";
 
 // ---------------------------------------------------------------------------
 // Context

package/src/internal/store/workflow-execution-event-store.ts

@@ -0,0 +1,391 @@
+import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { WorkflowEventType } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import type { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+
+// ---------------------------------------------------------------------------
+// Stream state (mirrors ConversationStore's StreamState shape)
+// ---------------------------------------------------------------------------
+
+export type WorkflowEventStreamState =
+  | { readonly stage: "idle" }
+  | { readonly stage: "connecting"; readonly executionId: string }
+  | { readonly stage: "streaming"; readonly executionId: string }
+  | { readonly stage: "complete"; readonly executionId: string }
+  | {
+      readonly stage: "error";
+      readonly executionId: string;
+      readonly error: Error;
+    }
+  | { readonly stage: "unsupported"; readonly executionId: string };
+
+const IDLE_STATE: WorkflowEventStreamState = { stage: "idle" };
+
+// ---------------------------------------------------------------------------
+// Derived state types
+// ---------------------------------------------------------------------------
+
+export interface DerivedTaskState {
+  readonly taskName: string;
+  readonly taskKind: WorkflowTaskKind;
+  readonly status: "pending" | "running" | "completed" | "failed" | "skipped" | "retrying" | "waiting_approval";
+  readonly durationMs: number;
+  readonly costMicros: bigint;
+  readonly tokensUsed: bigint;
+  readonly attemptNumber: number;
+  readonly error: string;
+  readonly childExecutionId: string;
+}
+
+export interface DerivedCostSummary {
+  readonly costConsumedMicros: bigint;
+  readonly costRemainingMicros: bigint;
+  readonly tokensConsumed: bigint;
+  readonly tokensRemaining: bigint;
+  readonly thresholdBreached: boolean;
+}
+
+const BIGINT_ZERO = BigInt(0);
+const BIGINT_NEG_ONE = BigInt(-1);
+
+const EMPTY_COST_SUMMARY: DerivedCostSummary = {
+  costConsumedMicros: BIGINT_ZERO,
+  costRemainingMicros: BIGINT_NEG_ONE,
+  tokensConsumed: BIGINT_ZERO,
+  tokensRemaining: BIGINT_NEG_ONE,
+  thresholdBreached: false,
+};
+
+// ---------------------------------------------------------------------------
+// WorkflowExecutionEventStore
+// ---------------------------------------------------------------------------
+
+type Listener = () => void;
+
+/**
+ * Framework-agnostic store that accumulates workflow execution events
+ * in an append-only list and derives task states and cost summaries.
+ *
+ * Implements the contract required by React's `useSyncExternalStore`.
+ *
+ * Unlike `ConversationStore` (which stores mutable execution snapshots
+ * and applies structural sharing), this store is append-only: events
+ * are immutable once received. Derived state (task map, cost summary)
+ * is lazily recomputed and cached.
+ */
+export class WorkflowExecutionEventStore {
+  private _events: readonly WorkflowExecutionEvent[] = [];
+  private _streamState: WorkflowEventStreamState = IDLE_STATE;
+  private _listeners = new Set<Listener>();
+
+  private _taskStatesCache: ReadonlyMap<string, DerivedTaskState> | null = null;
+  private _costSummaryCache: DerivedCostSummary | null = null;
+  private _totalTasks = 0;
+
+  // -- Ingestion -----------------------------------------------------------
+
+  /**
+   * Append new events to the store. Deduplicates by sequence_number
+   * and maintains ascending order. Notifies listeners only when new
+   * events are actually added.
+   */
+  appendEvents(events: readonly WorkflowExecutionEvent[]): void {
+    if (events.length === 0) return;
+
+    const currentMax = this._events.length > 0
+      ? this._events[this._events.length - 1].sequenceNumber
+      : BIGINT_ZERO;
+
+    const newEvents = events.filter((e) => e.sequenceNumber > currentMax);
+    if (newEvents.length === 0) return;
+
+    newEvents.sort((a, b) => {
+      if (a.sequenceNumber < b.sequenceNumber) return -1;
+      if (a.sequenceNumber > b.sequenceNumber) return 1;
+      return 0;
+    });
+
+    this._events = [...this._events, ...newEvents];
+    this._taskStatesCache = null;
+    this._costSummaryCache = null;
+
+    for (const evt of newEvents) {
+      if (
+        evt.eventType === WorkflowEventType.execution_started &&
+        evt.payload.case === "executionStarted"
+      ) {
+        this._totalTasks = evt.payload.value.totalTasks;
+      }
+    }
+
+    this._notify();
+  }
+
+  /**
+   * Transition the stream lifecycle state.
+   */
+  setStreamState(state: WorkflowEventStreamState): void {
+    if (streamStateEqual(this._streamState, state)) return;
+    this._streamState = state;
+    this._notify();
+  }
+
+  /**
+   * Reset to initial state.
+   */
+  reset(): void {
+    const wasEmpty =
+      this._events.length === 0 && this._streamState.stage === "idle";
+    this._events = [];
+    this._streamState = IDLE_STATE;
+    this._taskStatesCache = null;
+    this._costSummaryCache = null;
+    this._totalTasks = 0;
+    if (!wasEmpty) this._notify();
+  }
+
+  // -- useSyncExternalStore selectors -------------------------------------
+
+  subscribe = (listener: Listener): (() => void) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+
+  getEvents = (): readonly WorkflowExecutionEvent[] => {
+    return this._events;
+  };
+
+  getStreamState = (): WorkflowEventStreamState => {
+    return this._streamState;
+  };
+
+  getLatestSequence = (): bigint => {
+    if (this._events.length === 0) return BIGINT_ZERO;
+    return this._events[this._events.length - 1].sequenceNumber;
+  };
+
+  getTotalTasks = (): number => {
+    return this._totalTasks;
+  };
+
+  /**
+   * Derived task state map, lazily computed and cached until new
+   * events are appended. Walks the event list once per invalidation
+   * to build a `Map<taskName, DerivedTaskState>`.
+   */
+  getTaskStates = (): ReadonlyMap<string, DerivedTaskState> => {
+    if (this._taskStatesCache) return this._taskStatesCache;
+    this._taskStatesCache = deriveTaskStates(this._events);
+    return this._taskStatesCache;
+  };
+
+  /**
+   * Derived cost summary from the latest budget_checkpoint event.
+   * Falls back to aggregating task_completed events when no checkpoint exists.
+   */
+  getCostSummary = (): DerivedCostSummary => {
+    if (this._costSummaryCache) return this._costSummaryCache;
+    this._costSummaryCache = deriveCostSummary(this._events);
+    return this._costSummaryCache;
+  };
+
+  // -- Internal ------------------------------------------------------------
+
+  private _notify(): void {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Derivation helpers
+// ---------------------------------------------------------------------------
+
+function deriveTaskStates(
+  events: readonly WorkflowExecutionEvent[],
+): ReadonlyMap<string, DerivedTaskState> {
+  const map = new Map<string, DerivedTaskState>();
+
+  for (const evt of events) {
+    const taskName = evt.taskName;
+    if (!taskName) continue;
+
+    const prev = map.get(taskName);
+    const p = evt.payload;
+
+    switch (p.case) {
+      case "taskStarted":
+        map.set(taskName, {
+          taskName,
+          taskKind: p.value.taskKind,
+          status: "running",
+          durationMs: 0,
+          costMicros: prev?.costMicros ?? BIGINT_ZERO,
+          tokensUsed: prev?.tokensUsed ?? BIGINT_ZERO,
+          attemptNumber: p.value.attemptNumber,
+          error: "",
+          childExecutionId: prev?.childExecutionId ?? "",
+        });
+        break;
+
+      case "taskCompleted":
+        map.set(taskName, {
+          taskName,
+          taskKind: p.value.taskKind,
+          status: "completed",
+          durationMs: Number(p.value.durationMs),
+          costMicros: p.value.costMicros,
+          tokensUsed: p.value.tokensUsed,
+          attemptNumber: prev?.attemptNumber ?? 1,
+          error: "",
+          childExecutionId: prev?.childExecutionId ?? "",
+        });
+        break;
+
+      case "taskFailed":
+        map.set(taskName, {
+          taskName,
+          taskKind: p.value.taskKind,
+          status: p.value.willRetry ? "retrying" : "failed",
+          durationMs: Number(p.value.durationMs),
+          costMicros: prev?.costMicros ?? BIGINT_ZERO,
+          tokensUsed: prev?.tokensUsed ?? BIGINT_ZERO,
+          attemptNumber: p.value.attemptNumber,
+          error: p.value.error,
+          childExecutionId: prev?.childExecutionId ?? "",
+        });
+        break;
+
+      case "taskSkipped":
+        map.set(taskName, {
+          taskName,
+          taskKind: p.value.taskKind,
+          status: "skipped",
+          durationMs: 0,
+          costMicros: BIGINT_ZERO,
+          tokensUsed: BIGINT_ZERO,
+          attemptNumber: 0,
+          error: "",
+          childExecutionId: prev?.childExecutionId ?? "",
+        });
+        break;
+
+      case "taskRetrying":
+        if (prev) {
+          map.set(taskName, { ...prev, status: "retrying" });
+        }
+        break;
+
+      case "agentCallStarted":
+        if (prev) {
+          map.set(taskName, {
+            ...prev,
+            childExecutionId: p.value.childExecutionId,
+          });
+        }
+        break;
+
+      case "agentCallCompleted":
+        if (prev) {
+          map.set(taskName, {
+            ...prev,
+            costMicros: p.value.costMicros,
+            tokensUsed: p.value.tokensConsumed,
+          });
+        }
+        break;
+
+      case "approvalRequested":
+        if (prev) {
+          map.set(taskName, { ...prev, status: "waiting_approval" });
+        }
+        break;
+
+      case "approvalResolved":
+        if (prev && prev.status === "waiting_approval") {
+          map.set(taskName, { ...prev, status: "running" });
+        }
+        break;
+    }
+  }
+
+  return map;
+}
+
+function deriveCostSummary(
+  events: readonly WorkflowExecutionEvent[],
+): DerivedCostSummary {
+  // Prefer the latest budget_checkpoint event
+  for (let i = events.length - 1; i >= 0; i--) {
+    const p = events[i].payload;
+    if (p.case === "budgetCheckpoint") {
+      return {
+        costConsumedMicros: p.value.costConsumedMicros,
+        costRemainingMicros: p.value.costRemainingMicros,
+        tokensConsumed: p.value.tokensConsumed,
+        tokensRemaining: p.value.tokensRemaining,
+        thresholdBreached: p.value.thresholdBreached,
+      };
+    }
+  }
+
+  // Fall back to execution_completed summary
+  for (let i = events.length - 1; i >= 0; i--) {
+    const p = events[i].payload;
+    if (p.case === "executionCompleted") {
+      return {
+        costConsumedMicros: p.value.totalCostMicros,
+        costRemainingMicros: BIGINT_NEG_ONE,
+        tokensConsumed: p.value.totalTokens,
+        tokensRemaining: BIGINT_NEG_ONE,
+        thresholdBreached: false,
+      };
+    }
+  }
+
+  // Fall back to aggregating task_completed events
+  let totalCost = BIGINT_ZERO;
+  let totalTokens = BIGINT_ZERO;
+  for (const evt of events) {
+    if (evt.payload.case === "taskCompleted") {
+      totalCost += evt.payload.value.costMicros;
+      totalTokens += evt.payload.value.tokensUsed;
+    }
+  }
+
+  if (totalCost > BIGINT_ZERO || totalTokens > BIGINT_ZERO) {
+    return {
+      costConsumedMicros: totalCost,
+      costRemainingMicros: BIGINT_NEG_ONE,
+      tokensConsumed: totalTokens,
+      tokensRemaining: BIGINT_NEG_ONE,
+      thresholdBreached: false,
+    };
+  }
+
+  return EMPTY_COST_SUMMARY;
+}
+
+// ---------------------------------------------------------------------------
+// Stream state equality
+// ---------------------------------------------------------------------------
+
+function streamStateEqual(
+  a: WorkflowEventStreamState,
+  b: WorkflowEventStreamState,
+): boolean {
+  if (a.stage !== b.stage) return false;
+  if (a.stage === "idle") return true;
+  if (
+    a.stage === "error" &&
+    b.stage === "error" &&
+    a.executionId === b.executionId &&
+    a.error === b.error
+  )
+    return true;
+  if ("executionId" in a && "executionId" in b)
+    return a.executionId === b.executionId;
+  return false;
+}

package/src/library/ScopeToggle.tsx

@@ -14,29 +14,45 @@ export interface ScopeToggleProps {
   readonly disabled?: boolean;
   /** Additional CSS classes applied to the root element. */
   readonly className?: string;
+  /**
+   * When true, renders icon-only buttons without text labels.
+   * Useful inside space-constrained contexts like picker popovers.
+   * Each button retains an accessible `aria-label`.
+   */
+  readonly compact?: boolean;
 }
 
-const SCOPE_OPTIONS: readonly {
+const OPTIONS: readonly {
   readonly value: ResourceListScope;
   readonly label: string;
+  readonly ariaLabel: string;
+  readonly icon: (props: { className?: string }) => React.JSX.Element;
 }[] = [
-  { value: "org", label: "Org" },
-  { value: "all", label: "All" },
+  {
+    value: "org",
+    label: "Org",
+    ariaLabel: "Organization only",
+    icon: OrgIcon,
+  },
+  {
+    value: "all",
+    label: "All",
+    ariaLabel: "All including public",
+    icon: GlobeIcon,
+  },
 ];
 
 /**
- * Segmented control for toggling resource scope between "Org"
- * (only the current organization's resources) and "All"
- * (including public and platform resources).
+ * Segmented control for switching resource list scope between
+ * organization-only and all (including public community resources).
+ *
+ * Renders as a WAI-ARIA Radio Group with roving tabindex and
+ * arrow-key navigation. Follows the same visual pattern as
+ * {@link VisibilityToggle}.
  *
- * Designed for use in Library list headers alongside a search input.
  * The component is controlled — the consumer owns the `value` state
  * and handles persistence (e.g., localStorage).
  *
- * Implements the WAI-ARIA Radio Group pattern with roving tabindex
- * for keyboard navigation: Arrow Left/Right moves focus and selects,
- * Tab enters/exits the group.
- *
  * All visual properties flow through `--stgm-*` tokens.
  *
  * @example
@@ -54,28 +70,35 @@ export function ScopeToggle({
   onChange,
   disabled = false,
   className,
+  compact = false,
 }: ScopeToggleProps) {
   const optionRefs = useRef<(HTMLButtonElement | null)[]>([]);
 
+  const handleSelect = useCallback(
+    (next: ResourceListScope) => {
+      if (next !== value) onChange(next);
+    },
+    [value, onChange],
+  );
+
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLButtonElement>, index: number) => {
       let nextIndex: number | null = null;
 
       if (e.key === "ArrowRight" || e.key === "ArrowDown") {
         e.preventDefault();
-        nextIndex = (index + 1) % SCOPE_OPTIONS.length;
+        nextIndex = (index + 1) % OPTIONS.length;
       } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
         e.preventDefault();
-        nextIndex =
-          (index - 1 + SCOPE_OPTIONS.length) % SCOPE_OPTIONS.length;
+        nextIndex = (index - 1 + OPTIONS.length) % OPTIONS.length;
       }
 
       if (nextIndex !== null) {
         optionRefs.current[nextIndex]?.focus();
-        onChange(SCOPE_OPTIONS[nextIndex].value);
+        handleSelect(OPTIONS[nextIndex].value);
       }
     },
-    [onChange],
+    [handleSelect],
   );
 
   return (
@@ -89,8 +112,9 @@ export function ScopeToggle({
         className,
       )}
     >
-      {SCOPE_OPTIONS.map((option, index) => {
+      {OPTIONS.map((option, index) => {
         const isSelected = value === option.value;
+        const Icon = option.icon;
 
         return (
           <button
@@ -101,22 +125,66 @@ export function ScopeToggle({
             type="button"
             role="radio"
             aria-checked={isSelected}
+            aria-label={option.ariaLabel}
+            title={compact ? option.ariaLabel : undefined}
             tabIndex={isSelected ? 0 : -1}
             disabled={disabled}
-            onClick={() => onChange(option.value)}
+            onClick={() => handleSelect(option.value)}
             onKeyDown={(e) => handleKeyDown(e, index)}
             className={cn(
-              "cursor-pointer rounded-sm px-3 py-1 text-xs font-medium transition-colors",
+              "inline-flex cursor-pointer items-center gap-1 rounded-sm px-2 py-1 text-xs font-medium transition-colors",
               "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
               isSelected
                 ? "bg-background text-foreground shadow-sm"
                 : "text-muted-foreground hover:text-foreground",
             )}
           >
-            {option.label}
+            <Icon className="size-3" />
+            {!compact && option.label}
           </button>
         );
       })}
     </div>
   );
 }
+
+// ---------------------------------------------------------------------------
+// Icons — inline SVGs following the SDK pattern (no icon library dependency)
+// ---------------------------------------------------------------------------
+
+function OrgIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="4" y="2" width="8" height="12" rx="1" />
+      <path d="M6.5 5h3M6.5 8h3M6.5 11h3" />
+    </svg>
+  );
+}
+
+function GlobeIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="8" r="6" />
+      <path d="M2 8h12" />
+      <path d="M8 2c1.66 1.46 2.6 3.63 2.6 6s-.94 4.54-2.6 6c-1.66-1.46-2.6-3.63-2.6-6s.94-4.54 2.6-6Z" />
+    </svg>
+  );
+}

package/src/library/VisibilityToggle.tsx

@@ -109,8 +109,6 @@ export function VisibilityToggle({
     [handleSelect],
   );
 
-  const currentIndex = OPTIONS.findIndex((o) => o.value === visibility);
-
   return (
     <div className={cn("inline-flex flex-col gap-1.5", className)}>
       <div
@@ -124,6 +122,8 @@ export function VisibilityToggle({
       >
         {OPTIONS.map((option, index) => {
           const isSelected = visibility === option.value;
+          const isPublicOption =
+            option.value === ApiResourceVisibility.visibility_public;
 
           return (
             <button
@@ -139,26 +139,26 @@ export function VisibilityToggle({
               onClick={() => handleSelect(option.value)}
               onKeyDown={(e) => handleKeyDown(e, index)}
               className={cn(
-                "cursor-pointer rounded-sm px-3 py-1 text-xs font-medium transition-colors",
+                "inline-flex cursor-pointer items-center gap-1 rounded-sm px-2.5 py-1 text-xs font-medium transition-colors",
                 "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
-                isSelected && option.value === ApiResourceVisibility.visibility_public
+                isSelected && isPublicOption
                   ? "bg-emerald-100 text-emerald-800 shadow-sm dark:bg-emerald-900/40 dark:text-emerald-300"
                   : isSelected
-                    ? "bg-background text-foreground shadow-sm"
+                    ? "bg-amber-50 text-amber-800 shadow-sm dark:bg-amber-900/30 dark:text-amber-300"
                     : "text-muted-foreground hover:text-foreground",
               )}
             >
               {isPending && isSelected ? (
-                <span className="inline-flex items-center gap-1">
-                  <span
-                    className="inline-block h-3 w-3 animate-spin rounded-full border-2 border-current border-t-transparent"
-                    aria-hidden="true"
-                  />
-                  {option.label}
-                </span>
+                <span
+                  className="inline-block size-3 animate-spin rounded-full border-2 border-current border-t-transparent"
+                  aria-hidden="true"
+                />
+              ) : isPublicOption ? (
+                <GlobeIcon className="size-3" />
               ) : (
-                option.label
+                <LockIcon className="size-3" />
               )}
+              {option.label}
             </button>
           );
         })}
@@ -204,3 +204,44 @@ export function VisibilityToggle({
     </div>
   );
 }
+
+// ---------------------------------------------------------------------------
+// Icons — inline SVGs following the SDK pattern (no icon library dependency)
+// ---------------------------------------------------------------------------
+
+function LockIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="3.5" y="7" width="9" height="7" rx="1.5" />
+      <path d="M5.5 7V5a2.5 2.5 0 0 1 5 0v2" />
+    </svg>
+  );
+}
+
+function GlobeIcon({ className }: { readonly className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="8" r="6" />
+      <path d="M2 8h12" />
+      <path d="M8 2c1.66 1.46 2.6 3.63 2.6 6s-.94 4.54-2.6 6c-1.66-1.46-2.6-3.63-2.6-6s.94-4.54 2.6-6Z" />
+    </svg>
+  );
+}

package/src/library/index.ts

@@ -37,6 +37,8 @@ export {
   serializeMcpServerInputYaml,
 } from "./serialize-resource-yaml";
 
+export { serializeWorkflowYaml, parseWorkflowYaml } from "../workflow/serialize-workflow-yaml";
+
 export { useApplyResource } from "./useApplyResource";
 export type {
   UseApplyResourceReturn,