@stigmer/react 0.4.7 → 0.5.0

package/src/dependency-graph/useDependencyGraph.ts

@@ -0,0 +1,158 @@
+"use client";
+
+import { useMemo } from "react";
+import type {
+  DependencyNode,
+  DependencyTree,
+  UseDependencyGraphOptions,
+  UseDependencyGraphReturn,
+} from "./types";
+
+/**
+ * Pure transformation hook that converts an `AgentSpec` into a
+ * {@link DependencyTree} for rendering.
+ *
+ * No data fetching, no side effects — the tree is computed entirely
+ * from the spec fields already available via {@link useAgent}. The
+ * result is memoized and only recomputes when the spec reference
+ * changes.
+ *
+ * Returns `null` for `tree` when `spec` is `undefined` (loading state).
+ *
+ * @example
+ * ```tsx
+ * const { tree, isEmpty } = useDependencyGraph({
+ *   agentName: agent.metadata.name,
+ *   agentOrg: agent.metadata.org,
+ *   spec: agent.spec,
+ * });
+ *
+ * if (!isEmpty && tree) {
+ *   return <DependencyGraph tree={tree} onNodeClick={handleClick} />;
+ * }
+ * ```
+ */
+export function useDependencyGraph({
+  agentName,
+  agentOrg,
+  spec,
+}: UseDependencyGraphOptions): UseDependencyGraphReturn {
+  return useMemo(() => {
+    if (!spec) return { tree: null, isEmpty: true };
+
+    const { mcpServerUsages, skillRefs, subAgents } = spec;
+
+    const hasDeps =
+      mcpServerUsages.length > 0 ||
+      skillRefs.length > 0 ||
+      subAgents.length > 0;
+
+    if (!hasDeps) return { tree: null, isEmpty: true };
+
+    let nodeCount = 1; // root
+
+    const mcpNodes: DependencyNode[] = mcpServerUsages
+      .filter((u) => u.mcpServerRef)
+      .map((usage) => {
+        nodeCount++;
+        const ref = usage.mcpServerRef!;
+        const toolCount = usage.enabledTools.length;
+
+        return {
+          id: `mcp-server:${ref.slug}`,
+          kind: "mcp-server" as const,
+          label: ref.slug,
+          qualifiedLabel:
+            ref.org && ref.org !== agentOrg
+              ? `${ref.org}/${ref.slug}`
+              : undefined,
+          metadata: {
+            tools:
+              toolCount > 0
+                ? `${toolCount} ${toolCount === 1 ? "tool" : "tools"}`
+                : "all tools",
+          },
+          children: [],
+          ref: { org: ref.org || agentOrg, slug: ref.slug },
+        };
+      });
+
+    const skillNodes: DependencyNode[] = skillRefs.map((ref) => {
+      nodeCount++;
+      return {
+        id: `skill:${ref.slug}`,
+        kind: "skill" as const,
+        label: ref.slug,
+        qualifiedLabel:
+          ref.org && ref.org !== agentOrg
+            ? `${ref.org}/${ref.slug}`
+            : undefined,
+        children: [],
+        ref: { org: ref.org || agentOrg, slug: ref.slug },
+      };
+    });
+
+    const subAgentNodes: DependencyNode[] = subAgents.map((sa) => {
+      nodeCount++;
+
+      const saMcpNodes: DependencyNode[] = sa.mcpAccess.map((access) => {
+        nodeCount++;
+        const toolCount = access.enabledTools.length;
+        return {
+          id: `sub-agent:${sa.name}:mcp-server:${access.mcpServer}`,
+          kind: "mcp-server" as const,
+          label: access.mcpServer,
+          metadata: {
+            tools:
+              toolCount > 0
+                ? `${toolCount} ${toolCount === 1 ? "tool" : "tools"}`
+                : "all tools",
+          },
+          children: [],
+          ref: { org: agentOrg, slug: access.mcpServer },
+        };
+      });
+
+      const saSkillNodes: DependencyNode[] = sa.skillRefs.map((ref) => {
+        nodeCount++;
+        return {
+          id: `sub-agent:${sa.name}:skill:${ref.slug}`,
+          kind: "skill" as const,
+          label: ref.slug,
+          qualifiedLabel:
+            ref.org && ref.org !== agentOrg
+              ? `${ref.org}/${ref.slug}`
+              : undefined,
+          children: [],
+          ref: { org: ref.org || agentOrg, slug: ref.slug },
+        };
+      });
+
+      const metadata: Record<string, string> = {};
+      if (sa.modelOverride) {
+        metadata.model = sa.modelOverride;
+      }
+
+      return {
+        id: `sub-agent:${sa.name}`,
+        kind: "sub-agent" as const,
+        label: sa.name,
+        description: sa.description || undefined,
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+        children: [...saMcpNodes, ...saSkillNodes],
+      };
+    });
+
+    const root: DependencyNode = {
+      id: `agent:${agentName}`,
+      kind: "agent",
+      label: agentName,
+      children: [...mcpNodes, ...skillNodes, ...subAgentNodes],
+    };
+
+    return {
+      tree: { root, nodeCount },
+      isEmpty: false,
+    };
+  }, [agentName, agentOrg, spec]);
+}

package/src/empty-state/EmptyState.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { useEmptyState } from "./useEmptyState";
+import type { EmptyStateProps } from "./types";
+
+/**
+ * A semantic, accessible empty state component supporting four distinct
+ * variants: first-use, zero-results, permission, and error.
+ *
+ * Each variant provides appropriate default icons, copy, and ARIA roles.
+ * All defaults can be overridden via props. The `icon` prop accepts any
+ * ReactNode for full visual customization.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   variant="first-use"
+ *   resourceLabel="agents"
+ *   action={{ label: "Create agent", onClick: handleCreate }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   variant="error"
+ *   errorMessage="Network request failed"
+ *   action={{ label: "Retry", onClick: handleRetry }}
+ * />
+ * ```
+ */
+export function EmptyState({
+  variant,
+  resourceLabel,
+  icon,
+  title,
+  description,
+  errorMessage,
+  action,
+  children,
+  className,
+}: EmptyStateProps) {
+  const resolved = useEmptyState({
+    variant,
+    resourceLabel,
+    title,
+    description,
+    errorMessage,
+  });
+
+  return (
+    <div
+      role={resolved.role}
+      className={cn(
+        "flex flex-col items-center gap-3 py-12 text-center",
+        className,
+      )}
+    >
+      <div className="text-muted-foreground-faint">
+        {icon ?? resolved.defaultIcon}
+      </div>
+      <div className="flex flex-col gap-1">
+        <p className="text-sm font-medium text-muted-foreground">
+          {resolved.title}
+        </p>
+        <p className="max-w-sm text-xs text-muted-foreground-subtle">
+          {resolved.description}
+        </p>
+      </div>
+      {children
+        ? <div className="mt-1">{children}</div>
+        : action && (
+          <button
+            type="button"
+            onClick={action.onClick}
+            className={cn(
+              "mt-1 inline-flex items-center rounded-md px-3 py-1.5 text-xs font-medium",
+              variant === "error"
+                ? "border border-input bg-background text-foreground hover:bg-accent hover:text-accent-foreground"
+                : "bg-primary text-primary-foreground hover:bg-primary-hover",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          >
+            {action.label}
+          </button>
+        )}
+    </div>
+  );
+}

package/src/empty-state/index.ts

@@ -0,0 +1,9 @@
+export { EmptyState } from "./EmptyState";
+export { useEmptyState } from "./useEmptyState";
+export type {
+  EmptyStateVariant,
+  EmptyStateAction,
+  EmptyStateProps,
+  UseEmptyStateOptions,
+  UseEmptyStateReturn,
+} from "./types";

package/src/empty-state/types.ts

@@ -0,0 +1,81 @@
+import type { ReactNode } from "react";
+
+/**
+ * Semantic variant for an empty state, each representing a distinct
+ * reason why no content is visible.
+ */
+export type EmptyStateVariant =
+  | "first-use"
+  | "zero-results"
+  | "permission"
+  | "error";
+
+/** Action rendered as a button within the empty state. */
+export interface EmptyStateAction {
+  /** Button label. */
+  readonly label: string;
+  /** Click handler. */
+  readonly onClick: () => void;
+}
+
+/** Options for the {@link useEmptyState} behavior hook. */
+export interface UseEmptyStateOptions {
+  /** The semantic reason no content is shown. */
+  readonly variant: EmptyStateVariant;
+  /**
+   * Human-readable label for the resource type (e.g. "agents", "skills").
+   * Used to generate contextual default copy.
+   */
+  readonly resourceLabel?: string;
+  /** Custom title override. When provided, replaces the generated default. */
+  readonly title?: string;
+  /** Custom description override. When provided, replaces the generated default. */
+  readonly description?: string;
+  /** Error message to display — relevant for the "error" variant. */
+  readonly errorMessage?: string;
+}
+
+/** Return value of the {@link useEmptyState} behavior hook. */
+export interface UseEmptyStateReturn {
+  /** Resolved title text. */
+  readonly title: string;
+  /** Resolved description text. */
+  readonly description: string;
+  /** Suggested default icon for the variant (as a ReactNode). */
+  readonly defaultIcon: ReactNode;
+  /** The ARIA role appropriate for this variant. */
+  readonly role: "status" | "alert";
+}
+
+/** Props for the styled {@link EmptyState} component. */
+export interface EmptyStateProps {
+  /**
+   * The semantic reason no content is shown.
+   * Determines default icon, copy, and ARIA role.
+   */
+  readonly variant: EmptyStateVariant;
+  /**
+   * Human-readable label for the resource type (e.g. "agents", "skills").
+   * Used to generate contextual default copy.
+   */
+  readonly resourceLabel?: string;
+  /** Custom icon to display. Defaults to a variant-appropriate Lucide icon. */
+  readonly icon?: ReactNode;
+  /** Custom title override. */
+  readonly title?: string;
+  /** Custom description override. */
+  readonly description?: string;
+  /** Error message — only used when variant is "error". */
+  readonly errorMessage?: string;
+  /** Primary action button. */
+  readonly action?: EmptyStateAction;
+  /**
+   * Custom action slot content. When provided, renders in the action
+   * area (centered, below the description) instead of the `action` button.
+   * Use this when you need full control over the CTA element — e.g. a
+   * `<Link>` for client-side routing or a button with an icon.
+   */
+  readonly children?: ReactNode;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}

package/src/empty-state/useEmptyState.ts

@@ -0,0 +1,85 @@
+import { useMemo, createElement } from "react";
+import { Package, SearchX, Lock, AlertCircle } from "lucide-react";
+import type { UseEmptyStateOptions, UseEmptyStateReturn } from "./types";
+
+const ICON_CLASSES = "h-10 w-10";
+
+function resolveDefaults(
+  variant: UseEmptyStateOptions["variant"],
+  resourceLabel: string,
+): { title: string; description: string } {
+  switch (variant) {
+    case "first-use":
+      return {
+        title: `No ${resourceLabel} yet`,
+        description: `Create ${resourceLabel === "agents" ? "an agent" : `a ${resourceLabel.replace(/s$/, "")}`} to get started.`,
+      };
+    case "zero-results":
+      return {
+        title: "No results found",
+        description: "Try adjusting your search or filters.",
+      };
+    case "permission":
+      return {
+        title: `No access to ${resourceLabel}`,
+        description:
+          "You don't have permission to view these resources. Contact your organization admin.",
+      };
+    case "error":
+      return {
+        title: "Something went wrong",
+        description: "We couldn't load this content. Please try again.",
+      };
+  }
+}
+
+function resolveIcon(variant: UseEmptyStateOptions["variant"]) {
+  switch (variant) {
+    case "first-use":
+      return createElement(Package, { className: ICON_CLASSES });
+    case "zero-results":
+      return createElement(SearchX, { className: ICON_CLASSES });
+    case "permission":
+      return createElement(Lock, { className: ICON_CLASSES });
+    case "error":
+      return createElement(AlertCircle, { className: ICON_CLASSES });
+  }
+}
+
+function resolveRole(
+  variant: UseEmptyStateOptions["variant"],
+): "status" | "alert" {
+  return variant === "error" ? "alert" : "status";
+}
+
+/**
+ * Behavior hook that resolves empty state copy, icon, and accessibility
+ * attributes based on the semantic variant and optional overrides.
+ *
+ * Use this hook when you want full rendering control but need the
+ * variant-aware logic (default copy, icons, ARIA roles).
+ *
+ * @example
+ * ```tsx
+ * const { title, description, defaultIcon, role } = useEmptyState({
+ *   variant: "first-use",
+ *   resourceLabel: "agents",
+ * });
+ * ```
+ */
+export function useEmptyState(options: UseEmptyStateOptions): UseEmptyStateReturn {
+  const { variant, resourceLabel = "resources", title, description, errorMessage } = options;
+
+  return useMemo(() => {
+    const defaults = resolveDefaults(variant, resourceLabel);
+    return {
+      title: title ?? defaults.title,
+      description:
+        variant === "error" && errorMessage
+          ? errorMessage
+          : (description ?? defaults.description),
+      defaultIcon: resolveIcon(variant),
+      role: resolveRole(variant),
+    };
+  }, [variant, resourceLabel, title, description, errorMessage]);
+}

package/src/execution/MessageThread.tsx

@@ -129,7 +129,7 @@ export type ThreadItem =
   | { readonly kind: "sub-agent"; readonly subAgentExecution: SubAgentExecution; readonly key: string }
   | { readonly kind: "phase-badge"; readonly phase: ExecutionPhase; readonly key: string }
   | { readonly kind: "approval-request"; readonly pendingApproval: PendingApproval; readonly key: string }
-  | { readonly kind: "setup-progress"; readonly workspaceEntries: readonly WorkspaceEntry[]; readonly serverPhase?: string; readonly key: string };
+  | { readonly kind: "setup-progress"; readonly workspaceEntries: readonly WorkspaceEntry[]; readonly serverPhase?: string; readonly isAwaitingResponse?: boolean; readonly key: string };
 
 function hasAiMessages(execution: AgentExecution): boolean {
   const messages = execution.status?.messages;
@@ -257,20 +257,30 @@ export function buildThreadItems(
   const lastPhase =
     lastExec?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
 
-  if (
-    activeStreamExecution &&
-    (lastPhase === ExecutionPhase.EXECUTION_PENDING ||
-      lastPhase === ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) &&
-    !hasAiMessages(activeStreamExecution)
-  ) {
-    const serverPhase =
-      activeStreamExecution.status?.setupProgress?.currentPhase || undefined;
-    items.push({
-      kind: "setup-progress",
-      workspaceEntries: workspaceEntries ?? [],
-      serverPhase,
-      key: "setup-progress",
-    });
+  if (activeStreamExecution && !hasAiMessages(activeStreamExecution)) {
+    const isPending =
+      lastPhase === ExecutionPhase.EXECUTION_PENDING ||
+      lastPhase === ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+    const isInProgressNoMessages =
+      lastPhase === ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+    if (isPending) {
+      const serverPhase =
+        activeStreamExecution.status?.setupProgress?.currentPhase || undefined;
+      items.push({
+        kind: "setup-progress",
+        workspaceEntries: workspaceEntries ?? [],
+        serverPhase,
+        key: "setup-progress",
+      });
+    } else if (isInProgressNoMessages) {
+      items.push({
+        kind: "setup-progress",
+        workspaceEntries: workspaceEntries ?? [],
+        isAwaitingResponse: true,
+        key: "setup-progress",
+      });
+    }
   }
 
   if (
@@ -557,6 +567,7 @@ export function ThreadItemRenderer({
         <SetupProgress
           workspaceEntries={item.workspaceEntries}
           serverPhase={item.serverPhase}
+          isAwaitingResponse={item.isAwaitingResponse}
         />
       );
   }

package/src/execution/SetupProgress.tsx

@@ -22,6 +22,13 @@ export interface SetupProgressProps {
    * step sequence derived from `workspaceEntries`.
    */
   readonly serverPhase?: string;
+  /**
+   * When `true`, the execution has moved past `PENDING` into
+   * `IN_PROGRESS` but the agent has not yet produced any AI messages.
+   * Renders a static "Thinking\u2026" label instead of the setup
+   * phase sequence or server-reported phase.
+   */
+  readonly isAwaitingResponse?: boolean;
   /** Additional CSS class names for the root container. */
   readonly className?: string;
 }
@@ -66,33 +73,41 @@ function buildSteps(
 
 /**
  * Animated inline indicator shown in the message thread while an
- * execution is in the `PENDING` phase and no AI messages have arrived.
+ * execution has not yet produced AI messages.
+ *
+ * Operates in three modes (highest-priority first):
  *
- * **Server-driven mode** — when the backend reports
- * `setup_progress.current_phase` through the execution stream, the
- * component renders the server-reported label directly.
+ * 1. **Awaiting response** — `isAwaitingResponse` is `true`. The
+ *    execution has moved past `PENDING` into `IN_PROGRESS` but no AI
+ *    messages have arrived yet. Shows a static "Thinking\u2026" label.
  *
- * **Timer-based fallback** — when `serverPhase` is absent (older
- * backends), the component cycles through contextual status messages
- * derived from the session configuration on a fixed interval.
+ * 2. **Server-driven** — `serverPhase` is non-empty. Renders the
+ *    server-reported `setup_progress.current_phase` label directly.
+ *
+ * 3. **Timer-based fallback** — neither of the above. Cycles through
+ *    contextual status messages derived from `workspaceEntries`.
  *
  * All visual properties flow through `--stgm-*` tokens.
  *
  * @example
  * ```tsx
- * // Server-driven (preferred)
+ * // Awaiting response (IN_PROGRESS, no messages yet)
+ * <SetupProgress isAwaitingResponse />
+ *
+ * // Server-driven (preferred during PENDING)
  * <SetupProgress serverPhase={execution.status?.setupProgress?.currentPhase} />
  *
- * // Fallback (no server phase available)
+ * // Timer fallback (PENDING, no server phase available)
  * <SetupProgress workspaceEntries={session.spec?.workspaceEntries} />
  * ```
  */
 export const SetupProgress = memo(function SetupProgress({
   workspaceEntries,
   serverPhase,
+  isAwaitingResponse,
   className,
 }: SetupProgressProps) {
-  const useServerPhase = !!serverPhase;
+  const useServerPhase = !isAwaitingResponse && !!serverPhase;
 
   /* ── Timer-based fallback state ─────────────────────────────────── */
   const steps = useMemo(() => buildSteps(workspaceEntries), [workspaceEntries]);
@@ -103,7 +118,7 @@ export const SetupProgress = memo(function SetupProgress({
   }, [steps]);
 
   useEffect(() => {
-    if (useServerPhase) return;
+    if (isAwaitingResponse || useServerPhase) return;
     if (stepIndex >= steps.length - 1) return;
 
     const timer = setTimeout(() => {
@@ -111,11 +126,17 @@ export const SetupProgress = memo(function SetupProgress({
     }, steps[stepIndex].durationMs);
 
     return () => clearTimeout(timer);
-  }, [useServerPhase, stepIndex, steps]);
+  }, [isAwaitingResponse, useServerPhase, stepIndex, steps]);
 
   /* ── Resolve display message ────────────────────────────────────── */
-  const currentMessage =
-    serverPhase || steps[Math.min(stepIndex, steps.length - 1)].message;
+  let currentMessage: string;
+  if (isAwaitingResponse) {
+    currentMessage = "Thinking\u2026";
+  } else if (serverPhase) {
+    currentMessage = serverPhase;
+  } else {
+    currentMessage = steps[Math.min(stepIndex, steps.length - 1)].message;
+  }
 
   return (
     <div

package/src/execution/__tests__/thread-keys.test.ts

@@ -406,4 +406,105 @@ describe("buildThreadItems key generation", () => {
 
     expect(items[0].key).toBe("_e0-m0");
   });
+
+  describe("setup-progress indicator lifecycle", () => {
+    it("shows setup-progress during PENDING with no AI messages", () => {
+      const exec = makeExecution({
+        id: "exec-pending",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_PENDING,
+      });
+
+      const items = buildThreadItems([], exec, null, false, undefined);
+      const setupItem = items.find((i) => i.kind === "setup-progress");
+
+      expect(setupItem).toBeDefined();
+      expect(setupItem!.key).toBe("setup-progress");
+      if (setupItem?.kind === "setup-progress") {
+        expect(setupItem.isAwaitingResponse).toBeFalsy();
+      }
+    });
+
+    it("shows setup-progress with isAwaitingResponse during IN_PROGRESS with no AI messages", () => {
+      const exec = makeExecution({
+        id: "exec-in-progress",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      });
+
+      const items = buildThreadItems([], exec, null, false, undefined);
+      const setupItem = items.find((i) => i.kind === "setup-progress");
+
+      expect(setupItem).toBeDefined();
+      expect(setupItem!.key).toBe("setup-progress");
+      if (setupItem?.kind === "setup-progress") {
+        expect(setupItem.isAwaitingResponse).toBe(true);
+      }
+    });
+
+    it("hides setup-progress once AI messages arrive during IN_PROGRESS", () => {
+      const exec = makeExecution({
+        id: "exec-streaming",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+        messages: [
+          makeMessage(MessageType.MESSAGE_AI, "Here's my response"),
+        ],
+      });
+
+      const items = buildThreadItems([], exec, null, false, undefined);
+      const setupItem = items.find((i) => i.kind === "setup-progress");
+
+      expect(setupItem).toBeUndefined();
+    });
+
+    it("hides setup-progress for terminal phases even without AI messages", () => {
+      const exec = makeExecution({
+        id: "exec-failed",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_FAILED,
+      });
+
+      const items = buildThreadItems([], exec, null, false, undefined);
+      const setupItem = items.find((i) => i.kind === "setup-progress");
+
+      expect(setupItem).toBeUndefined();
+    });
+
+    it("does not show setup-progress for completed executions (not active stream)", () => {
+      const exec = makeExecution({
+        id: "exec-done",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_PENDING,
+      });
+
+      const items = buildThreadItems([exec], null, null, false, undefined);
+      const setupItem = items.find((i) => i.kind === "setup-progress");
+
+      expect(setupItem).toBeUndefined();
+    });
+
+    it("preserves stable key across PENDING → IN_PROGRESS transition", () => {
+      const pendingExec = makeExecution({
+        id: "exec-transition",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_PENDING,
+      });
+      const itemsPending = buildThreadItems([], pendingExec, null, false, undefined);
+
+      const inProgressExec = makeExecution({
+        id: "exec-transition",
+        specMessage: "Hello",
+        phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      });
+      const itemsInProgress = buildThreadItems([], inProgressExec, null, false, undefined);
+
+      const pendingSetup = itemsPending.find((i) => i.kind === "setup-progress");
+      const inProgressSetup = itemsInProgress.find((i) => i.kind === "setup-progress");
+
+      expect(pendingSetup).toBeDefined();
+      expect(inProgressSetup).toBeDefined();
+      expect(pendingSetup!.key).toBe(inProgressSetup!.key);
+    });
+  });
 });