@stigmer/react 0.0.36

package/src/agent-execution/components/ToolCallCard.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import { Badge } from "../../internal/badge";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "../../internal/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;
+  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(
+          "bg-card text-card-foreground rounded-lg border text-sm",
+          isWaitingApproval && "border-primary/40 ring-primary/20 ring-1",
+          className,
+        )}
+      >
+        <CollapsibleTrigger className="hover:bg-muted/50 flex w-full items-center gap-2 rounded-t-lg px-3 py-2 text-left transition-colors">
+          <ChevronRight
+            className={cn(
+              "text-muted-foreground size-3.5 shrink-0 transition-transform",
+              (open || isWaitingApproval) && "rotate-90",
+            )}
+          />
+          {isRunning ? (
+            <Loader2 className="text-muted-foreground size-3.5 shrink-0 animate-spin" />
+          ) : (
+            <Wrench className="text-muted-foreground size-3.5 shrink-0" />
+          )}
+          <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="text-muted-foreground shrink-0 text-[10px]">
+              {duration}
+            </span>
+          )}
+        </CollapsibleTrigger>
+
+        <CollapsibleContent>
+          <div className="space-y-2 border-t px-3 py-2">
+            {toolCall.args && Object.keys(toolCall.args).length > 0 && (
+              <ToolCallSection label="Arguments">
+                <pre className="bg-muted overflow-x-auto rounded p-2 text-[11px] leading-relaxed">
+                  {JSON.stringify(toolCall.args, null, 2)}
+                </pre>
+              </ToolCallSection>
+            )}
+
+            {toolCall.result && (
+              <ToolCallSection label="Result">
+                <pre className="bg-muted overflow-x-auto rounded p-2 text-[11px] leading-relaxed whitespace-pre-wrap">
+                  {toolCall.result}
+                </pre>
+              </ToolCallSection>
+            )}
+
+            {toolCall.error && (
+              <ToolCallSection label="Error">
+                <p className="text-destructive text-xs">{toolCall.error}</p>
+              </ToolCallSection>
+            )}
+
+            {toolCall.isStreaming && !toolCall.result && (
+              <div className="text-muted-foreground flex items-center gap-1.5 text-xs">
+                <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="text-muted-foreground mb-1 text-[10px] font-medium tracking-wider uppercase">
+        {label}
+      </p>
+      {children}
+    </div>
+  );
+}

package/src/agent-execution/helpers.ts

@@ -0,0 +1,193 @@
+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/agent-execution/hooks/useAgentExecution.ts

@@ -0,0 +1,147 @@
+"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 { create } from "@bufbuild/protobuf";
+import { CancelAgentExecutionInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../../hooks";
+import { isTerminalPhase } from "../helpers";
+
+export interface CreateExecutionInput {
+  agentId?: string;
+  sessionId?: string;
+  message: string;
+  org: string;
+}
+
+export interface UseAgentExecutionOptions {
+  executionId?: string;
+}
+
+export interface UseAgentExecutionReturn {
+  execution: AgentExecution | null;
+  phase: ExecutionPhase;
+  isConnected: boolean;
+  error: string | null;
+  start: (input: CreateExecutionInput) => Promise<void>;
+  cancel: (reason?: string) => Promise<void>;
+}
+
+export function useAgentExecution(
+  options?: UseAgentExecutionOptions,
+): UseAgentExecutionReturn {
+  const stigmer = useStigmer();
+  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 = stigmer.agentExecution.subscribe(
+            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);
+          }
+        }
+      })();
+    },
+    [stigmer],
+  );
+
+  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 stigmer.agentExecution.create({
+          name: "",
+          org: input.org,
+          agentId: input.agentId,
+          sessionId: input.sessionId,
+          message: input.message,
+        });
+        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);
+      }
+    },
+    [stigmer, subscribe],
+  );
+
+  const cancel = useCallback(
+    async (reason?: string) => {
+      const id = activeExecutionIdRef.current;
+      if (!id) return;
+      try {
+        await stigmer.agentExecution.cancel(
+          create(CancelAgentExecutionInputSchema, {
+            id,
+            reason: reason ?? "",
+          }),
+        );
+      } catch (err: unknown) {
+        const message =
+          err instanceof Error ? err.message : "Failed to cancel execution";
+        setError(message);
+      }
+    },
+    [stigmer],
+  );
+
+  const phase =
+    execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+
+  return { execution, phase, isConnected, error, start, cancel };
+}

package/src/agent-execution/hooks/useApproval.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { create } from "@bufbuild/protobuf";
+import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../../hooks";
+
+export interface UseApprovalOptions {
+  executionId: string;
+}
+
+export interface UseApprovalReturn {
+  submit: (
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => Promise<void>;
+  isSubmitting: boolean;
+  error: string | null;
+  clearError: () => void;
+}
+
+export function useApproval(options: UseApprovalOptions): UseApprovalReturn {
+  const stigmer = useStigmer();
+  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 stigmer.agentExecution.submitApproval(
+          create(SubmitApprovalInputSchema, {
+            agentExecutionId: options.executionId,
+            toolCallId,
+            action,
+            comment: comment ?? "",
+          }),
+        );
+      } catch (err: unknown) {
+        const message =
+          err instanceof Error ? err.message : "Failed to submit approval";
+        setError(message);
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer, options.executionId],
+  );
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { submit, isSubmitting, error, clearError };
+}

package/src/agent-execution/index.ts

@@ -0,0 +1,46 @@
+// 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,
+  CreateExecutionInput,
+} from "./hooks/useAgentExecution";
+
+export { useApproval } from "./hooks/useApproval";
+export type {
+  UseApprovalOptions,
+  UseApprovalReturn,
+} from "./hooks/useApproval";
+
+// Helpers
+export {
+  isTerminalPhase,
+  phaseLabel,
+  phaseVariant,
+  toolCallStatusLabel,
+  toolCallStatusVariant,
+  isToolCallTerminal,
+  subAgentStatusLabel,
+  subAgentStatusVariant,
+  isHumanMessage,
+  isAiMessage,
+  isToolMessage,
+  isSystemMessage,
+  buildSubAgentIndex,
+  qualifiedToolName,
+  formatDuration,
+} from "./helpers";