@stigmer/react-ui 0.0.34

package/src/execution/components/ToolCallCard.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import { Badge } from "../../internal/ui/badge";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "../../internal/ui/collapsible";
+import { ApprovalControls } from "./ApprovalControls";
+import {
+  toolCallStatusLabel,
+  toolCallStatusVariant,
+  qualifiedToolName,
+  formatDuration,
+} from "../helpers";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { cn } from "@stigmer/theme";
+import { ChevronRight, Wrench, Loader2 } from "lucide-react";
+
+interface ToolCallCardProps {
+  toolCall: ToolCall;
+  /** Callback for approval submission. Only required when tool is awaiting approval. */
+  onApproval?: (
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => Promise<void>;
+  isApprovalSubmitting?: boolean;
+  className?: string;
+}
+
+export function ToolCallCard({
+  toolCall,
+  onApproval,
+  isApprovalSubmitting = false,
+  className,
+}: ToolCallCardProps) {
+  const [open, setOpen] = useState(false);
+  const isWaitingApproval =
+    toolCall.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL;
+  const isRunning = toolCall.status === ToolCallStatus.TOOL_CALL_RUNNING;
+  const duration = formatDuration(toolCall.startedAt, toolCall.completedAt);
+  const displayName = qualifiedToolName(toolCall.name, toolCall.mcpServerSlug);
+
+  const handleApproval = useCallback(
+    async (action: ApprovalAction, comment?: string) => {
+      await onApproval?.(toolCall.id, action, comment);
+    },
+    [onApproval, toolCall.id],
+  );
+
+  return (
+    <Collapsible open={open || isWaitingApproval} onOpenChange={setOpen}>
+      <div
+        className={cn(
+          "rounded-lg border bg-card text-card-foreground text-sm",
+          isWaitingApproval && "border-primary/40 ring-1 ring-primary/20",
+          className,
+        )}
+      >
+        <CollapsibleTrigger className="flex w-full items-center gap-2 px-3 py-2 text-left hover:bg-muted/50 transition-colors rounded-t-lg">
+          <ChevronRight
+            className={cn(
+              "size-3.5 shrink-0 text-muted-foreground transition-transform",
+              (open || isWaitingApproval) && "rotate-90",
+            )}
+          />
+          {isRunning ? (
+            <Loader2 className="size-3.5 shrink-0 animate-spin text-muted-foreground" />
+          ) : (
+            <Wrench className="size-3.5 shrink-0 text-muted-foreground" />
+          )}
+          <span className="truncate font-mono text-xs">{displayName}</span>
+          <Badge
+            variant={toolCallStatusVariant(toolCall.status)}
+            className="ml-auto shrink-0 text-[10px]"
+          >
+            {toolCallStatusLabel(toolCall.status)}
+          </Badge>
+          {duration && (
+            <span className="shrink-0 text-[10px] text-muted-foreground">
+              {duration}
+            </span>
+          )}
+        </CollapsibleTrigger>
+
+        <CollapsibleContent>
+          <div className="border-t px-3 py-2 space-y-2">
+            {toolCall.args && Object.keys(toolCall.args).length > 0 && (
+              <ToolCallSection label="Arguments">
+                <pre className="overflow-x-auto rounded bg-muted p-2 text-[11px] leading-relaxed">
+                  {JSON.stringify(toolCall.args, null, 2)}
+                </pre>
+              </ToolCallSection>
+            )}
+
+            {toolCall.result && (
+              <ToolCallSection label="Result">
+                <pre className="overflow-x-auto rounded bg-muted p-2 text-[11px] leading-relaxed whitespace-pre-wrap">
+                  {toolCall.result}
+                </pre>
+              </ToolCallSection>
+            )}
+
+            {toolCall.error && (
+              <ToolCallSection label="Error">
+                <p className="text-xs text-destructive">{toolCall.error}</p>
+              </ToolCallSection>
+            )}
+
+            {toolCall.isStreaming && !toolCall.result && (
+              <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                <Loader2 className="size-3 animate-spin" />
+                Executing...
+              </div>
+            )}
+          </div>
+
+          {isWaitingApproval && onApproval && (
+            <div className="border-t px-3 py-2">
+              <ApprovalControls
+                approvalMessage={
+                  toolCall.approvalMessage ||
+                  `Execute tool: ${displayName}`
+                }
+                onSubmit={handleApproval}
+                isSubmitting={isApprovalSubmitting}
+              />
+            </div>
+          )}
+        </CollapsibleContent>
+      </div>
+    </Collapsible>
+  );
+}
+
+function ToolCallSection({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div>
+      <p className="mb-1 text-[10px] font-medium uppercase tracking-wider text-muted-foreground">
+        {label}
+      </p>
+      {children}
+    </div>
+  );
+}

package/src/execution/helpers.ts

@@ -0,0 +1,199 @@
+import {
+  ExecutionPhase,
+  ToolCallStatus,
+  SubAgentStatus,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+
+// ---------------------------------------------------------------------------
+// Execution phase utilities
+// ---------------------------------------------------------------------------
+
+const TERMINAL_PHASES = new Set<ExecutionPhase>([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+export function isTerminalPhase(phase: ExecutionPhase): boolean {
+  return TERMINAL_PHASES.has(phase);
+}
+
+const PHASE_LABELS: Record<ExecutionPhase, string> = {
+  [ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED]: "Unknown",
+  [ExecutionPhase.EXECUTION_PENDING]: "Pending",
+  [ExecutionPhase.EXECUTION_IN_PROGRESS]: "Running",
+  [ExecutionPhase.EXECUTION_COMPLETED]: "Completed",
+  [ExecutionPhase.EXECUTION_FAILED]: "Failed",
+  [ExecutionPhase.EXECUTION_CANCELLED]: "Cancelled",
+  [ExecutionPhase.EXECUTION_TERMINATED]: "Terminated",
+  [ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL]: "Waiting for Approval",
+  [ExecutionPhase.EXECUTION_PAUSED]: "Paused",
+};
+
+export function phaseLabel(phase: ExecutionPhase): string {
+  return PHASE_LABELS[phase] ?? "Unknown";
+}
+
+type BadgeVariant =
+  | "default"
+  | "secondary"
+  | "destructive"
+  | "outline";
+
+const PHASE_VARIANTS: Record<ExecutionPhase, BadgeVariant> = {
+  [ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED]: "outline",
+  [ExecutionPhase.EXECUTION_PENDING]: "outline",
+  [ExecutionPhase.EXECUTION_IN_PROGRESS]: "default",
+  [ExecutionPhase.EXECUTION_COMPLETED]: "secondary",
+  [ExecutionPhase.EXECUTION_FAILED]: "destructive",
+  [ExecutionPhase.EXECUTION_CANCELLED]: "outline",
+  [ExecutionPhase.EXECUTION_TERMINATED]: "destructive",
+  [ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL]: "default",
+  [ExecutionPhase.EXECUTION_PAUSED]: "outline",
+};
+
+export function phaseVariant(phase: ExecutionPhase): BadgeVariant {
+  return PHASE_VARIANTS[phase] ?? "outline";
+}
+
+// ---------------------------------------------------------------------------
+// Tool call status utilities
+// ---------------------------------------------------------------------------
+
+const TOOL_CALL_STATUS_LABELS: Record<ToolCallStatus, string> = {
+  [ToolCallStatus.TOOL_CALL_STATUS_UNSPECIFIED]: "Unknown",
+  [ToolCallStatus.TOOL_CALL_PENDING]: "Pending",
+  [ToolCallStatus.TOOL_CALL_RUNNING]: "Running",
+  [ToolCallStatus.TOOL_CALL_COMPLETED]: "Completed",
+  [ToolCallStatus.TOOL_CALL_FAILED]: "Failed",
+  [ToolCallStatus.TOOL_CALL_WAITING_APPROVAL]: "Awaiting Approval",
+  [ToolCallStatus.TOOL_CALL_SKIPPED]: "Skipped",
+};
+
+export function toolCallStatusLabel(status: ToolCallStatus): string {
+  return TOOL_CALL_STATUS_LABELS[status] ?? "Unknown";
+}
+
+const TOOL_CALL_STATUS_VARIANTS: Record<ToolCallStatus, BadgeVariant> = {
+  [ToolCallStatus.TOOL_CALL_STATUS_UNSPECIFIED]: "outline",
+  [ToolCallStatus.TOOL_CALL_PENDING]: "outline",
+  [ToolCallStatus.TOOL_CALL_RUNNING]: "default",
+  [ToolCallStatus.TOOL_CALL_COMPLETED]: "secondary",
+  [ToolCallStatus.TOOL_CALL_FAILED]: "destructive",
+  [ToolCallStatus.TOOL_CALL_WAITING_APPROVAL]: "default",
+  [ToolCallStatus.TOOL_CALL_SKIPPED]: "outline",
+};
+
+export function toolCallStatusVariant(status: ToolCallStatus): BadgeVariant {
+  return TOOL_CALL_STATUS_VARIANTS[status] ?? "outline";
+}
+
+export function isToolCallTerminal(status: ToolCallStatus): boolean {
+  return (
+    status === ToolCallStatus.TOOL_CALL_COMPLETED ||
+    status === ToolCallStatus.TOOL_CALL_FAILED ||
+    status === ToolCallStatus.TOOL_CALL_SKIPPED
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Sub-agent status utilities
+// ---------------------------------------------------------------------------
+
+const SUB_AGENT_STATUS_LABELS: Record<SubAgentStatus, string> = {
+  [SubAgentStatus.SUB_AGENT_STATUS_UNSPECIFIED]: "Unknown",
+  [SubAgentStatus.SUB_AGENT_PENDING]: "Pending",
+  [SubAgentStatus.SUB_AGENT_IN_PROGRESS]: "Running",
+  [SubAgentStatus.SUB_AGENT_COMPLETED]: "Completed",
+  [SubAgentStatus.SUB_AGENT_FAILED]: "Failed",
+  [SubAgentStatus.SUB_AGENT_CANCELLED]: "Cancelled",
+};
+
+export function subAgentStatusLabel(status: SubAgentStatus): string {
+  return SUB_AGENT_STATUS_LABELS[status] ?? "Unknown";
+}
+
+const SUB_AGENT_STATUS_VARIANTS: Record<SubAgentStatus, BadgeVariant> = {
+  [SubAgentStatus.SUB_AGENT_STATUS_UNSPECIFIED]: "outline",
+  [SubAgentStatus.SUB_AGENT_PENDING]: "outline",
+  [SubAgentStatus.SUB_AGENT_IN_PROGRESS]: "default",
+  [SubAgentStatus.SUB_AGENT_COMPLETED]: "secondary",
+  [SubAgentStatus.SUB_AGENT_FAILED]: "destructive",
+  [SubAgentStatus.SUB_AGENT_CANCELLED]: "outline",
+};
+
+export function subAgentStatusVariant(status: SubAgentStatus): BadgeVariant {
+  return SUB_AGENT_STATUS_VARIANTS[status] ?? "outline";
+}
+
+// ---------------------------------------------------------------------------
+// Message type utilities
+// ---------------------------------------------------------------------------
+
+export function isHumanMessage(type: MessageType): boolean {
+  return type === MessageType.MESSAGE_HUMAN;
+}
+
+export function isAiMessage(type: MessageType): boolean {
+  return type === MessageType.MESSAGE_AI;
+}
+
+export function isToolMessage(type: MessageType): boolean {
+  return type === MessageType.MESSAGE_TOOL;
+}
+
+export function isSystemMessage(type: MessageType): boolean {
+  return type === MessageType.MESSAGE_SYSTEM;
+}
+
+// ---------------------------------------------------------------------------
+// Execution-level helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an index of sub-agent executions keyed by their ID.
+ * The sub-agent ID matches the tool call ID from the parent's "task" tool invocation,
+ * enabling O(1) lookup when rendering tool calls that represent sub-agent delegations.
+ */
+export function buildSubAgentIndex(
+  execution: AgentExecution,
+): Map<string, SubAgentExecution> {
+  const subAgents = execution.status?.subAgentExecutions;
+  if (!subAgents || subAgents.length === 0) return new Map();
+  return new Map(subAgents.map((sa) => [sa.id, sa]));
+}
+
+/**
+ * Format a qualified tool name: "mcp-server/tool-name" when an MCP server
+ * slug is present, or just "tool-name" for built-in sandbox tools.
+ */
+export function qualifiedToolName(
+  name: string,
+  mcpServerSlug: string,
+): string {
+  if (mcpServerSlug) return `${mcpServerSlug}/${name}`;
+  return name;
+}
+
+/**
+ * Format elapsed time between two ISO timestamps as a human-readable duration.
+ * Returns null if either timestamp is missing.
+ */
+export function formatDuration(
+  startedAt: string,
+  completedAt: string,
+): string | null {
+  if (!startedAt || !completedAt) return null;
+  const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
+  if (ms < 0) return null;
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = Math.round(seconds % 60);
+  return `${minutes}m ${remainingSeconds}s`;
+}

package/src/execution/hooks/useAgentExecution.ts

@@ -0,0 +1,126 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { useExecutionService } from "./useExecutionService";
+import { isTerminalPhase } from "../helpers";
+import type { CreateExecutionInput } from "../services/execution-service";
+
+export type { CreateExecutionInput };
+
+export interface UseAgentExecutionOptions {
+  /** Subscribe to an existing execution on mount. */
+  executionId?: string;
+}
+
+export interface UseAgentExecutionReturn {
+  /** The latest execution state from the stream. Null before subscription starts. */
+  execution: AgentExecution | null;
+  /** Convenience accessor — the current phase (defaults to UNSPECIFIED when no execution). */
+  phase: ExecutionPhase;
+  /** True while the subscription stream is open and receiving updates. */
+  isConnected: boolean;
+  /** Error message from creation, subscription, or cancellation. Null when healthy. */
+  error: string | null;
+  /** Create a new execution and auto-subscribe to its stream. */
+  start: (input: CreateExecutionInput) => Promise<void>;
+  /** Gracefully cancel the current execution. */
+  cancel: (reason?: string) => Promise<void>;
+}
+
+export function useAgentExecution(
+  options?: UseAgentExecutionOptions,
+): UseAgentExecutionReturn {
+  const service = useExecutionService();
+  const [execution, setExecution] = useState<AgentExecution | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const activeExecutionIdRef = useRef<string | null>(
+    options?.executionId ?? null,
+  );
+  const abortRef = useRef<AbortController | null>(null);
+
+  const subscribe = useCallback((executionId: string) => {
+    abortRef.current?.abort();
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+    activeExecutionIdRef.current = executionId;
+    setIsConnected(true);
+    setError(null);
+
+    (async () => {
+      try {
+        const stream = service.subscribeToExecution(executionId, controller.signal);
+        for await (const update of stream) {
+          if (controller.signal.aborted) break;
+          setExecution(update);
+
+          const phase = update.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+          if (isTerminalPhase(phase)) {
+            setIsConnected(false);
+            break;
+          }
+        }
+      } catch (err: unknown) {
+        if (controller.signal.aborted) return;
+        const message =
+          err instanceof Error ? err.message : "Stream disconnected";
+        setError(message);
+      } finally {
+        if (!controller.signal.aborted) {
+          setIsConnected(false);
+        }
+      }
+    })();
+  }, [service]);
+
+  useEffect(() => {
+    if (options?.executionId) {
+      subscribe(options.executionId);
+    }
+    return () => {
+      abortRef.current?.abort();
+    };
+  }, [options?.executionId, subscribe]);
+
+  const start = useCallback(
+    async (input: CreateExecutionInput) => {
+      setError(null);
+      setExecution(null);
+      try {
+        const created = await service.createExecution(input);
+        const executionId = created.metadata?.id;
+        if (!executionId) {
+          throw new Error("Created execution missing metadata.id");
+        }
+        setExecution(created);
+        subscribe(executionId);
+      } catch (err: unknown) {
+        const message =
+          err instanceof Error ? err.message : "Failed to create execution";
+        setError(message);
+      }
+    },
+    [service, subscribe],
+  );
+
+  const cancel = useCallback(async (reason?: string) => {
+    const id = activeExecutionIdRef.current;
+    if (!id) return;
+    try {
+      await service.cancelExecution(id, reason);
+    } catch (err: unknown) {
+      const message =
+        err instanceof Error ? err.message : "Failed to cancel execution";
+      setError(message);
+    }
+  }, [service]);
+
+  const phase =
+    execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+
+  return { execution, phase, isConnected, error, start, cancel };
+}

package/src/execution/hooks/useApproval.ts

@@ -0,0 +1,55 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { useExecutionService } from "./useExecutionService";
+
+export interface UseApprovalOptions {
+  executionId: string;
+}
+
+export interface UseApprovalReturn {
+  /** Submit an approval decision for a specific tool call. */
+  submit: (
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => Promise<void>;
+  /** True while an approval request is in flight. */
+  isSubmitting: boolean;
+  /** Error message from the last failed submission. Null when healthy. */
+  error: string | null;
+  /** Clear the current error state. */
+  clearError: () => void;
+}
+
+export function useApproval(options: UseApprovalOptions): UseApprovalReturn {
+  const service = useExecutionService();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const submit = useCallback(
+    async (
+      toolCallId: string,
+      action: ApprovalAction,
+      comment?: string,
+    ) => {
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        await service.submitApproval(options.executionId, toolCallId, action, comment);
+      } catch (err: unknown) {
+        const message =
+          err instanceof Error ? err.message : "Failed to submit approval";
+        setError(message);
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [service, options.executionId],
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { submit, isSubmitting, error, clearError };
+}

package/src/execution/hooks/useExecutionService.ts

@@ -0,0 +1,15 @@
+"use client";
+
+import { useMemo } from "react";
+import { useStigmerTransport } from "@stigmer/rpc-client";
+import { createExecutionService, type ExecutionService } from "../services/execution-service";
+
+/**
+ * Returns an {@link ExecutionService} bound to the transport from
+ * {@link StigmerTransportProvider}. The service instance is memoized
+ * for the lifetime of the transport.
+ */
+export function useExecutionService(): ExecutionService {
+  const transport = useStigmerTransport();
+  return useMemo(() => createExecutionService(transport), [transport]);
+}

package/src/execution/index.ts

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+
+export { ExecutionStream } from "./components/ExecutionStream";
+export { ExecutionStatus } from "./components/ExecutionStatus";
+export { OutputBlock } from "./components/OutputBlock";
+export { ToolCallCard } from "./components/ToolCallCard";
+export { ApprovalControls } from "./components/ApprovalControls";
+export { SubAgentCard } from "./components/SubAgentCard";
+export { MessageInput } from "./components/MessageInput";
+export { MessageEntry, HumanMessageBubble, SystemMessageBlock } from "./components/MessageEntry";
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+export { useAgentExecution } from "./hooks/useAgentExecution";
+export type { UseAgentExecutionOptions, UseAgentExecutionReturn } from "./hooks/useAgentExecution";
+
+export { useApproval } from "./hooks/useApproval";
+export type { UseApprovalOptions, UseApprovalReturn } from "./hooks/useApproval";
+
+export { useExecutionService } from "./hooks/useExecutionService";
+
+// ---------------------------------------------------------------------------
+// Services (for non-React usage or custom wiring)
+// ---------------------------------------------------------------------------
+
+export { createExecutionService } from "./services/execution-service";
+export type { ExecutionService, CreateExecutionInput, ListExecutionsBySessionOptions } from "./services/execution-service";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export {
+  isTerminalPhase,
+  phaseLabel,
+  phaseVariant,
+  toolCallStatusLabel,
+  toolCallStatusVariant,
+  isToolCallTerminal,
+  subAgentStatusLabel,
+  subAgentStatusVariant,
+  isHumanMessage,
+  isAiMessage,
+  isToolMessage,
+  isSystemMessage,
+  buildSubAgentIndex,
+  qualifiedToolName,
+  formatDuration,
+} from "./helpers";