@stigmer/react 0.0.36 → 0.0.40

package/src/execution/ArtifactsWidget.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { useState } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+import { useExecutionArtifacts } from "./useExecutionArtifacts";
+import { isTerminalPhase } from "./execution-phases";
+import { ArtifactCard } from "./ArtifactCard";
+import { ArtifactPreviewModal } from "./ArtifactPreviewModal";
+import type { ApplyResourceResult } from "../library/useApplyResource";
+
+export interface ArtifactsWidgetProps {
+  /**
+   * The execution to display artifacts for. Renders nothing when `null`
+   * or when the execution has no artifacts.
+   */
+  readonly execution: AgentExecution | null;
+  /** Organization slug for the "Apply to [org]" CTA in the preview modal. */
+  readonly org: string;
+  /**
+   * Called after a resource is successfully applied or a skill package
+   * is pushed from the preview modal. The consumer can use this for
+   * post-apply behavior such as showing a toast or navigating to the
+   * Library.
+   */
+  readonly onApplied?: (result: ApplyResourceResult) => void;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+/**
+ * Right-sidebar widget that surfaces execution artifacts as a compact
+ * card list with automatic Stigmer resource detection.
+ *
+ * Composes {@link ArtifactCard} (summary + detection badges) with
+ * {@link ArtifactPreviewModal} (full content review + Apply/Push CTA).
+ * The card's "Preview" action opens the modal; the modal is the sole
+ * location for Apply/Push actions (review-before-apply pattern).
+ *
+ * Derives all data from the `execution` prop:
+ *
+ * - **Artifacts**: extracted via {@link useExecutionArtifacts}
+ * - **Terminal phase**: derived via {@link isTerminalPhase} — controls
+ *   whether the Apply CTA in the modal is enabled
+ * - **Execution ID**: read from `execution.metadata.id`
+ *
+ * Returns `null` when the execution is `null` or has no artifacts,
+ * matching the conditional-render pattern of {@link ExecutionProgress}
+ * and {@link ExecutionCostSummary}.
+ *
+ * Renders without card chrome — each {@link ArtifactCard} provides its
+ * own border and padding. The consumer controls the container styling
+ * (or places the widget directly in a flex/grid layout).
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * const stream = useExecutionStream(executionId);
+ *
+ * <ArtifactsWidget
+ *   execution={stream.execution}
+ *   org={activeOrg}
+ *   onApplied={(result) => toast(`${result.kind} applied`)}
+ * />
+ * ```
+ *
+ * @see {@link ArtifactCard} — compact summary card per artifact
+ * @see {@link ArtifactPreviewModal} — full preview with Apply/Push CTA
+ * @see {@link useExecutionArtifacts} — headless artifact extraction hook
+ */
+export function ArtifactsWidget({
+  execution,
+  org,
+  onApplied,
+  className,
+}: ArtifactsWidgetProps) {
+  const { artifacts, hasArtifacts, artifactCount } =
+    useExecutionArtifacts(execution);
+
+  const [previewArtifact, setPreviewArtifact] =
+    useState<ExecutionArtifact | null>(null);
+
+  if (!hasArtifacts) return null;
+
+  const phase =
+    execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+  const isTerminal = isTerminalPhase(phase);
+  const executionId = execution?.metadata?.id ?? "";
+
+  return (
+    <section aria-label="Execution artifacts" className={cn(className)}>
+      <div className="mb-2 flex items-center gap-2">
+        <h3 className="text-sm font-medium text-foreground">Artifacts</h3>
+        <span className="inline-flex min-w-[1.25rem] items-center justify-center rounded-full bg-muted px-1.5 text-xs tabular-nums text-muted-foreground">
+          {artifactCount}
+        </span>
+      </div>
+
+      <div role="list" className="space-y-2">
+        {artifacts.map((artifact) => (
+          <div key={artifact.storageKey} role="listitem">
+            <ArtifactCard
+              artifact={artifact}
+              executionId={executionId}
+              org={org}
+              onPreview={setPreviewArtifact}
+            />
+          </div>
+        ))}
+      </div>
+
+      {previewArtifact && (
+        <ArtifactPreviewModal
+          artifact={previewArtifact}
+          executionId={executionId}
+          org={org}
+          isTerminal={isTerminal}
+          open
+          onClose={() => setPreviewArtifact(null)}
+          onApplied={onApplied}
+        />
+      )}
+    </section>
+  );
+}

package/src/execution/ExecutionCostSummary.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ModelUsage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import { cn } from "@stigmer/theme";
+import { useExecutionUsage } from "./useExecutionUsage";
+
+export interface ExecutionCostSummaryProps {
+  /** The execution to display cost data for. Renders nothing when null or when usage data has not yet arrived. */
+  readonly execution: AgentExecution | null;
+  readonly className?: string;
+}
+
+/**
+ * Displays real-time execution cost and token usage metrics aggregated
+ * across the main agent and any sub-agents.
+ *
+ * The headline shows estimated USD cost. Below it: model identification,
+ * total token and LLM call counts, a prompt/completion breakdown, and
+ * conditional annotations for cache usage and sub-agent contributions.
+ *
+ * During active streaming, cost and token numbers update on every
+ * progressive status snapshot. Uses `tabular-nums` for stable digit
+ * widths so the layout does not shift as numbers grow.
+ *
+ * When multiple models are used (common in sub-agent executions), the
+ * single model line is replaced with a per-model cost breakdown.
+ *
+ * Renders without card chrome — the consumer provides the container.
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * const stream = useExecutionStream(executionId);
+ *
+ * <div className="rounded-lg border border-border bg-card p-3">
+ *   <ExecutionCostSummary execution={stream.execution} />
+ * </div>
+ * ```
+ */
+export function ExecutionCostSummary({
+  execution,
+  className,
+}: ExecutionCostSummaryProps) {
+  const { usage, hasSubAgentUsage, subAgentUsageCount } =
+    useExecutionUsage(execution);
+
+  if (!usage) return null;
+
+  const multiModel = usage.modelBreakdown.length > 1;
+
+  return (
+    <div
+      className={cn("flex flex-col gap-1.5", className)}
+      role="region"
+      aria-label="Execution cost summary"
+    >
+      <div className="text-sm font-medium tabular-nums text-foreground">
+        {formatCost(usage.estimatedCostUsd)}
+      </div>
+
+      {multiModel ? (
+        <ModelBreakdown models={usage.modelBreakdown} />
+      ) : (
+        <div className="truncate text-xs text-muted-foreground">
+          {usage.primaryModel}
+          {usage.primaryProvider && ` · ${usage.primaryProvider}`}
+        </div>
+      )}
+
+      <div className="text-xs tabular-nums text-muted-foreground">
+        {formatTokenCount(usage.totalTokens)} tokens ·{" "}
+        {usage.llmCallCount} {usage.llmCallCount === 1 ? "call" : "calls"}
+      </div>
+
+      <div className="pl-2 text-xs tabular-nums text-muted-foreground">
+        prompt {formatTokenCount(usage.promptTokens)} · completion{" "}
+        {formatTokenCount(usage.completionTokens)}
+      </div>
+
+      {(usage.cacheReadTokens > 0 || usage.cacheCreationTokens > 0) && (
+        <CacheLine
+          readTokens={usage.cacheReadTokens}
+          creationTokens={usage.cacheCreationTokens}
+        />
+      )}
+
+      {hasSubAgentUsage && (
+        <div className="text-xs text-muted-foreground">
+          Includes {subAgentUsageCount} sub-agent
+          {subAgentUsageCount > 1 ? "s" : ""}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal sub-components
+// ---------------------------------------------------------------------------
+
+function ModelBreakdown({
+  models,
+}: {
+  readonly models: readonly ModelUsage[];
+}) {
+  return (
+    <div
+      className="flex flex-col gap-0.5"
+      role="list"
+      aria-label="Model cost breakdown"
+    >
+      {models.map((entry) => (
+        <div
+          key={`${entry.model}\0${entry.provider}`}
+          className="flex items-baseline justify-between text-xs text-muted-foreground"
+          role="listitem"
+        >
+          <span className="truncate">{entry.model}</span>
+          <span className="ml-2 shrink-0 tabular-nums">
+            {formatCost(entry.estimatedCostUsd)}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function CacheLine({
+  readTokens,
+  creationTokens,
+}: {
+  readonly readTokens: number;
+  readonly creationTokens: number;
+}) {
+  const parts: string[] = [];
+  if (readTokens > 0) parts.push(`${formatTokenCount(readTokens)} read`);
+  if (creationTokens > 0)
+    parts.push(`${formatTokenCount(creationTokens)} write`);
+
+  return (
+    <div className="pl-2 text-xs tabular-nums text-muted-foreground">
+      cache {parts.join(" · ")}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Formatting utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Formats a USD cost value for display.
+ * - Zero: "$0.00"
+ * - Under $1: 4 decimal places ("$0.0042")
+ * - $1 and above: 2 decimal places ("$1.23")
+ */
+export function formatCost(usd: number): string {
+  if (usd === 0) return "$0.00";
+  if (usd < 1) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+const tokenFormatter = new Intl.NumberFormat("en-US");
+
+/**
+ * Formats an integer token count with comma-separated digit grouping
+ * (en-US locale) for deterministic display across environments.
+ */
+export function formatTokenCount(count: number): string {
+  return tokenFormatter.format(count);
+}

package/src/execution/ExecutionPhaseBadge.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+
+export interface ExecutionPhaseBadgeProps {
+  readonly phase: ExecutionPhase;
+  readonly className?: string;
+}
+
+interface PhaseConfig {
+  readonly label: string;
+  readonly icon: () => React.JSX.Element;
+  readonly colorClass: string;
+}
+
+const PHASE_CONFIG: ReadonlyMap<ExecutionPhase, PhaseConfig> = new Map([
+  [
+    ExecutionPhase.EXECUTION_PENDING,
+    {
+      label: "Pending",
+      icon: DotIcon,
+      colorClass: "text-muted-foreground",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_IN_PROGRESS,
+    {
+      label: "Running",
+      icon: PulseDotIcon,
+      colorClass: "text-foreground",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_COMPLETED,
+    {
+      label: "Completed",
+      icon: CheckIcon,
+      colorClass: "text-success",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_FAILED,
+    {
+      label: "Failed",
+      icon: XIcon,
+      colorClass: "text-destructive",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_CANCELLED,
+    {
+      label: "Cancelled",
+      icon: XIcon,
+      colorClass: "text-muted-foreground",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_TERMINATED,
+    {
+      label: "Terminated",
+      icon: StopIcon,
+      colorClass: "text-destructive",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+    {
+      label: "Waiting for approval",
+      icon: ClockIcon,
+      colorClass: "text-warning",
+    },
+  ],
+  [
+    ExecutionPhase.EXECUTION_PAUSED,
+    {
+      label: "Paused",
+      icon: PauseIcon,
+      colorClass: "text-muted-foreground",
+    },
+  ],
+]);
+
+/**
+ * Displays the lifecycle phase of an {@link AgentExecution} as an
+ * inline badge with a status icon and label.
+ *
+ * Renders nothing for `EXECUTION_PHASE_UNSPECIFIED`.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * <ExecutionPhaseBadge phase={ExecutionPhase.EXECUTION_COMPLETED} />
+ * ```
+ */
+export function ExecutionPhaseBadge({
+  phase,
+  className,
+}: ExecutionPhaseBadgeProps) {
+  const config = PHASE_CONFIG.get(phase);
+  if (!config) return null;
+
+  const Icon = config.icon;
+
+  return (
+    <span
+      role="status"
+      aria-label={config.label}
+      className={cn(
+        "inline-flex items-center gap-1.5 text-xs font-medium",
+        config.colorClass,
+        className,
+      )}
+    >
+      <span aria-hidden="true">
+        <Icon />
+      </span>
+      {config.label}
+    </span>
+  );
+}
+
+function DotIcon() {
+  return (
+    <svg
+      width="8"
+      height="8"
+      viewBox="0 0 8 8"
+      fill="currentColor"
+    >
+      <circle cx="4" cy="4" r="3" />
+    </svg>
+  );
+}
+
+function PulseDotIcon() {
+  return (
+    <span className="relative flex h-2 w-2">
+      <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-current opacity-75" />
+      <span className="relative inline-flex h-2 w-2 rounded-full bg-current" />
+    </span>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M2.5 6L5 8.5L9.5 3.5" />
+    </svg>
+  );
+}
+
+function XIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 3L9 9M9 3L3 9" />
+    </svg>
+  );
+}
+
+function StopIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="currentColor"
+    >
+      <rect x="2" y="2" width="8" height="8" rx="1" />
+    </svg>
+  );
+}
+
+function ClockIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx="6" cy="6" r="4.5" />
+      <path d="M6 3.5V6L7.5 7.5" />
+    </svg>
+  );
+}
+
+function PauseIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="currentColor"
+    >
+      <rect x="2.5" y="2" width="2.5" height="8" rx="0.5" />
+      <rect x="7" y="2" width="2.5" height="8" rx="0.5" />
+    </svg>
+  );
+}

package/src/execution/ExecutionProgress.tsx

@@ -0,0 +1,191 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { TodoItem } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { TodoStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+import { ExecutionPhaseBadge } from "./ExecutionPhaseBadge";
+
+export interface ExecutionProgressProps {
+  /** The execution to display progress for. Renders nothing when null. */
+  readonly execution: AgentExecution | null;
+  readonly className?: string;
+}
+
+const STATUS_SORT_ORDER: ReadonlyMap<TodoStatus, number> = new Map([
+  [TodoStatus.TODO_IN_PROGRESS, 0],
+  [TodoStatus.TODO_PENDING, 1],
+  [TodoStatus.TODO_COMPLETED, 2],
+  [TodoStatus.TODO_CANCELLED, 3],
+]);
+
+function todoSortKey(item: TodoItem): number {
+  return STATUS_SORT_ORDER.get(item.status) ?? 4;
+}
+
+/**
+ * Displays execution lifecycle phase and, when present, the agent's
+ * todo checklist showing multi-step task progress.
+ *
+ * The phase badge is always visible so the user knows the execution
+ * state at a glance. When the agent creates todo items (via the
+ * `write_todos` tool), they appear as a compact checklist sorted by
+ * activity: in-progress items first, then pending, completed, and
+ * cancelled.
+ *
+ * Renders its content without card chrome (no border, background, or
+ * elevation). The consumer controls the container styling.
+ *
+ * All visual properties flow through `--stgm-*` tokens.
+ *
+ * @example
+ * ```tsx
+ * const stream = useExecutionStream(executionId);
+ *
+ * <div className="rounded-lg border border-border bg-card p-3">
+ *   <ExecutionProgress execution={stream.execution} />
+ * </div>
+ * ```
+ */
+export function ExecutionProgress({
+  execution,
+  className,
+}: ExecutionProgressProps) {
+  if (!execution) return null;
+
+  const phase = execution.status?.phase;
+  if (phase === undefined) return null;
+
+  const todos = execution.status?.todos;
+
+  const sortedTodos = useMemo(() => {
+    if (!todos) return [];
+    const items = Object.values(todos);
+    if (items.length === 0) return [];
+    return items.slice().sort((a, b) => todoSortKey(a) - todoSortKey(b));
+  }, [todos]);
+
+  return (
+    <div
+      className={cn("flex flex-col gap-2", className)}
+      role="region"
+      aria-label="Execution progress"
+    >
+      <ExecutionPhaseBadge phase={phase} />
+      {sortedTodos.length > 0 && (
+        <ul role="list" className="flex flex-col gap-1" aria-label="Tasks">
+          {sortedTodos.map((item) => (
+            <TodoRow key={item.id} item={item} />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Internal sub-components
+// ---------------------------------------------------------------------------
+
+function TodoRow({ item }: { item: TodoItem }) {
+  const Icon = TODO_ICONS[item.status] ?? TodoPendingIcon;
+  const colorClass = TODO_COLORS[item.status] ?? "text-muted-foreground";
+  const cancelled = item.status === TodoStatus.TODO_CANCELLED;
+
+  return (
+    <li className="flex items-start gap-1.5 text-xs">
+      <span className={cn("mt-0.5 shrink-0", colorClass)} aria-hidden="true">
+        <Icon />
+      </span>
+      <span
+        className={cn(
+          "min-w-0 break-words",
+          cancelled ? "text-muted-foreground line-through" : "text-foreground",
+        )}
+      >
+        {item.content}
+      </span>
+    </li>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Status icon mapping
+// ---------------------------------------------------------------------------
+
+const TODO_ICONS: Partial<Record<TodoStatus, () => React.JSX.Element>> = {
+  [TodoStatus.TODO_PENDING]: TodoPendingIcon,
+  [TodoStatus.TODO_IN_PROGRESS]: TodoInProgressIcon,
+  [TodoStatus.TODO_COMPLETED]: TodoCompletedIcon,
+  [TodoStatus.TODO_CANCELLED]: TodoCancelledIcon,
+};
+
+const TODO_COLORS: Partial<Record<TodoStatus, string>> = {
+  [TodoStatus.TODO_PENDING]: "text-muted-foreground",
+  [TodoStatus.TODO_IN_PROGRESS]: "text-foreground",
+  [TodoStatus.TODO_COMPLETED]: "text-success",
+  [TodoStatus.TODO_CANCELLED]: "text-muted-foreground",
+};
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons — no external icon dependency in SDK
+// ---------------------------------------------------------------------------
+
+function TodoPendingIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <circle cx="6" cy="6" r="4.5" />
+    </svg>
+  );
+}
+
+function TodoInProgressIcon() {
+  return (
+    <span className="relative flex h-3 w-3 items-center justify-center">
+      <span className="absolute inline-flex h-2 w-2 animate-ping rounded-full bg-current opacity-75" />
+      <span className="relative inline-flex h-2 w-2 rounded-full bg-current" />
+    </span>
+  );
+}
+
+function TodoCompletedIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M2.5 6L5 8.5L9.5 3.5" />
+    </svg>
+  );
+}
+
+function TodoCancelledIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3 3L9 9M9 3L3 9" />
+    </svg>
+  );
+}