@stigmer/react 0.5.0 → 1.0.0

package/src/inline-edit/InlineEditKeyValue.tsx

@@ -12,6 +12,10 @@ export interface InlineEditKeyValueProps extends InlineEditBaseProps {
   readonly onSave: (rows: KeyValueRow[]) => Promise<boolean>;
   /** Label for the "key" column. @default "Key" */
   readonly keyLabel?: string;
+  /** Show the value alongside the key in read mode and provide a value input in edit mode. @default false */
+  readonly showValue?: boolean;
+  /** Label for the "value" column (only relevant when showValue is true). @default "Value" */
+  readonly valueLabel?: string;
   /** Show the "secret" toggle per row. @default false */
   readonly showSecretToggle?: boolean;
   /** Show the "optional" toggle per row. @default false */
@@ -35,6 +39,8 @@ export function InlineEditKeyValue({
   value,
   onSave,
   keyLabel = "Key",
+  showValue = false,
+  valueLabel = "Value",
   showSecretToggle = false,
   showOptionalToggle = false,
   showDescription = false,
@@ -99,6 +105,11 @@ export function InlineEditKeyValue({
                 <code className="shrink-0 font-mono text-sm font-medium text-foreground">
                   {row.key}
                 </code>
+                {showValue && (
+                  <span className="min-w-0 break-all font-mono text-xs text-muted-foreground">
+                    {row.value}
+                  </span>
+                )}
                 {showSecretToggle && (
                   <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
                     {row.isSecret ? "secret" : "config"}
@@ -137,6 +148,18 @@ export function InlineEditKeyValue({
                 "focus:outline-none focus:ring-2 focus:ring-ring",
               )}
             />
+            {showValue && (
+              <input
+                type="text"
+                value={row.value}
+                onChange={(e) => updateRow(i, { value: e.target.value })}
+                placeholder={valueLabel}
+                className={cn(
+                  "rounded-md border border-border bg-input-bg px-2 py-1 font-mono text-sm text-foreground",
+                  "focus:outline-none focus:ring-2 focus:ring-ring",
+                )}
+              />
+            )}
             {showDescription && (
               <input
                 type="text"

package/src/internal/VirtualizedThread.tsx

@@ -37,6 +37,7 @@ export interface VirtualizedThreadProps {
   readonly submittingApprovalIds?: ReadonlySet<string>;
   readonly filePathCtx: FilePathContextValue;
   readonly sandboxCtx: SandboxContextValue;
+  readonly onBuildFromPlan?: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -93,6 +94,7 @@ export function VirtualizedThread({
   submittingApprovalIds,
   filePathCtx,
   sandboxCtx,
+  onBuildFromPlan,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -121,8 +123,9 @@ export function VirtualizedThread({
       formatToolCallSummary,
       onApprovalSubmit,
       submittingApprovalIds,
+      onBuildFromPlan,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, onBuildFromPlan],
   );
 
   return (

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/internal/useFetch.ts

@@ -94,8 +94,8 @@ export function useFetch<T>(
   const hasDataRef = useRef(
     cacheKey && cache ? cache.has(cacheKey) : false,
   );
-  const isFetchingRef = useRef(false);
-  const [isFetching, setIsFetching] = useState(false);
+  const isFetchingRef = useRef(fetchFn !== null);
+  const [isFetching, setIsFetching] = useState(fetchFn !== null);
 
   // Stable ref for cache — avoids adding cache to effect deps while
   // still letting the effect body access the current instance.

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>
+  );
+}