@stigmer/react 0.0.36 → 0.0.39

package/src/execution/useCreateAgentExecution.ts

@@ -0,0 +1,137 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AttachmentInput, EnvVarInput } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+export interface CreateAgentExecutionInput {
+  readonly org: string;
+  readonly sessionId: string;
+  readonly message: string;
+  readonly modelName?: string;
+  readonly agentId?: string;
+  /**
+   * Execution-scoped secrets and configuration (Execution Flow).
+   *
+   * Values are injected into the agent sandbox for this execution only
+   * and deleted when the execution completes. They take the highest
+   * merge priority, overriding both Environment values and agent
+   * defaults.
+   *
+   * Use this for B2B integrations where per-call credentials are
+   * injected at runtime, or for one-off secrets that should not persist.
+   *
+   * For persistent credentials that are reused across executions, use
+   * the Environment Flow instead (store secrets in an Environment
+   * resource and bind them via an AgentInstance).
+   *
+   * @see {@link https://docs.stigmer.ai/product/how-to-provide-secrets | How to Provide Secrets}
+   */
+  readonly runtimeEnv?: Record<string, EnvVarInput>;
+  /**
+   * Pre-uploaded file attachments injected into the agent sandbox.
+   *
+   * Each entry must include a `storageKey` obtained from
+   * `agentExecution.uploadAttachment()`. The agent can read attached
+   * files from their mount paths (default `/inputs/{filename}`).
+   */
+  readonly attachments?: AttachmentInput[];
+}
+
+export interface CreateAgentExecutionResult {
+  readonly executionId: string;
+  readonly sessionId: string;
+}
+
+export interface UseCreateAgentExecutionReturn {
+  readonly create: (
+    input: CreateAgentExecutionInput,
+  ) => Promise<CreateAgentExecutionResult>;
+  readonly isCreating: boolean;
+  readonly error: Error | null;
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `agentExecution.create()` with loading/error
+ * state.
+ *
+ * Maps 1:1 to the AgentExecution aggregate — a single run of an agent
+ * within an existing session. Requires a `sessionId`; use
+ * {@link useCreateSession} to create the session first.
+ *
+ * Supports both secret delivery flows:
+ *
+ * - **Environment Flow** — Secrets are stored in Environment resources
+ *   and bound via AgentInstance. No `runtimeEnv` needed; the backend
+ *   resolves credentials from the session's agent instance.
+ * - **Execution Flow** — Pass `runtimeEnv` to inject per-execution
+ *   secrets. Values are merged with the highest priority and deleted
+ *   when the execution completes.
+ *
+ * @example
+ * ```tsx
+ * // Environment Flow: secrets come from the agent instance's environments
+ * const { create } = useCreateAgentExecution();
+ * await create({ org: "acme", sessionId: "ses_abc", message: "Review the PR" });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Execution Flow: inject per-call secrets
+ * const { create } = useCreateAgentExecution();
+ * await create({
+ *   org: "acme",
+ *   sessionId: "ses_abc",
+ *   message: "Deploy to production",
+ *   runtimeEnv: {
+ *     CUSTOMER_API_KEY: { value: "cust_xyz...", isSecret: true },
+ *   },
+ * });
+ * ```
+ */
+export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (
+      input: CreateAgentExecutionInput,
+    ): Promise<CreateAgentExecutionResult> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        const execution = await stigmer.agentExecution.create({
+          name: `execution-${Date.now()}`,
+          org: input.org,
+          sessionId: input.sessionId,
+          agentId: input.agentId,
+          message: input.message,
+          executionConfig: input.modelName
+            ? { modelName: input.modelName }
+            : undefined,
+          runtimeEnv: input.runtimeEnv,
+          attachments: input.attachments,
+        });
+
+        return {
+          executionId: execution.metadata!.id,
+          sessionId: input.sessionId,
+        };
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/execution/useExecutionArtifacts.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import { useMemo } 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";
+
+export interface UseExecutionArtifactsReturn {
+  /** Artifacts published by the agent during execution. Ordered by creation time (oldest first). */
+  readonly artifacts: readonly ExecutionArtifact[];
+  /** `true` when the execution has at least one artifact. */
+  readonly hasArtifacts: boolean;
+  /** Total number of artifacts. */
+  readonly artifactCount: number;
+}
+
+/**
+ * Pure derivation hook that extracts artifact metadata from an
+ * {@link AgentExecution} snapshot.
+ *
+ * Follows the same pattern as {@link useExecutionUsage}: a `useMemo`-based
+ * derivation with no side effects and no data fetching. The execution
+ * object (typically from {@link useExecutionStream}) is the single input.
+ *
+ * Returns an empty array when the execution is `null` or has no artifacts,
+ * eliminating null-checking at every consumer call site.
+ *
+ * For reading artifact *content* (e.g., for YAML detection or preview
+ * rendering), compose with {@link useArtifactContent} on a per-artifact
+ * basis. For determining whether an artifact is text-based, use
+ * {@link isTextArtifact}.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * const { artifacts, hasArtifacts } = useExecutionArtifacts(execution);
+ *
+ * if (hasArtifacts) {
+ *   artifacts.forEach((a) => console.log(a.name, a.sizeBytes));
+ * }
+ * ```
+ *
+ * @see useArtifactContent — content-fetching hook for a single artifact
+ * @see isTextArtifact — heuristic for fetchable text content
+ * @see formatArtifactSize — human-readable file size formatting
+ */
+export function useExecutionArtifacts(
+  execution: AgentExecution | null,
+): UseExecutionArtifactsReturn {
+  return useMemo(() => {
+    const artifacts = execution?.status?.artifacts ?? [];
+
+    return {
+      artifacts,
+      hasArtifacts: artifacts.length > 0,
+      artifactCount: artifacts.length,
+    };
+  }, [execution]);
+}

package/src/execution/useExecutionStream.ts

@@ -0,0 +1,149 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, 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 { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import { isTerminalPhase } from "./execution-phases";
+
+export interface UseExecutionStreamReturn {
+  /** Latest full execution snapshot from the stream, or `null` before the first update arrives. */
+  readonly execution: AgentExecution | null;
+  /**
+   * Convenience extraction of `execution.status.phase`.
+   *
+   * Derived from `execution` via `useMemo` — always consistent with the
+   * current snapshot. Returns `EXECUTION_PHASE_UNSPECIFIED` when
+   * `execution` is `null`.
+   */
+  readonly phase: ExecutionPhase;
+  /** `true` while receiving non-terminal updates from the server stream. */
+  readonly isStreaming: boolean;
+  /** `true` after subscription starts but before the first snapshot arrives. */
+  readonly isConnecting: boolean;
+  /** Error from the last failed stream attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /**
+   * Reset error state and re-establish the stream subscription.
+   *
+   * Works in any lifecycle state — error, complete, or mid-stream.
+   * Uses the `connectKey` counter pattern consistent with `refetch()`
+   * in other SDK hooks.
+   */
+  readonly reconnect: () => void;
+}
+
+/**
+ * Behavior hook that subscribes to real-time {@link AgentExecution}
+ * updates via `stigmer.agentExecution.subscribe()`.
+ *
+ * Manages the full subscription lifecycle: connection establishment,
+ * snapshot streaming, terminal-phase detection, error handling, and
+ * manual reconnection. Each server message replaces the previous
+ * snapshot atomically — no delta merging.
+ *
+ * Pass `null` to skip subscribing (stable no-op). When `executionId`
+ * changes, the previous subscription is aborted and a fresh one begins.
+ *
+ * @example
+ * ```tsx
+ * function LiveExecution({ id }: { id: string }) {
+ *   const { execution, isStreaming, error, reconnect } =
+ *     useExecutionStream(id);
+ *
+ *   if (error) return <p>{error.message} <button onClick={reconnect}>Retry</button></p>;
+ *   if (!execution) return <p>Connecting…</p>;
+ *
+ *   return (
+ *     <div>
+ *       {execution.status?.messages.map((m, i) => (
+ *         <p key={i}>{m.content}</p>
+ *       ))}
+ *       {isStreaming && <span>Streaming…</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useExecutionStream(
+  executionId: string | null,
+): UseExecutionStreamReturn {
+  const stigmer = useStigmer();
+
+  const [execution, setExecution] = useState<AgentExecution | null>(null);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [connectKey, setConnectKey] = useState(0);
+
+  const abortRef = useRef<AbortController | null>(null);
+
+  const reconnect = useCallback(() => {
+    setError(null);
+    setConnectKey((k) => k + 1);
+  }, []);
+
+  useEffect(() => {
+    if (!executionId) {
+      setExecution(null);
+      setIsConnecting(false);
+      setIsStreaming(false);
+      setError(null);
+      return;
+    }
+
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setExecution(null);
+    setIsConnecting(true);
+    setIsStreaming(false);
+    setError(null);
+
+    (async () => {
+      try {
+        for await (const snapshot of stigmer.agentExecution.subscribe(
+          executionId,
+          controller.signal,
+        )) {
+          if (controller.signal.aborted) return;
+
+          const currentPhase =
+            snapshot.status?.phase ??
+            ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+          const isTerminal = isTerminalPhase(currentPhase);
+
+          setExecution(snapshot);
+          setIsConnecting(false);
+          setIsStreaming(!isTerminal);
+
+          if (isTerminal) break;
+        }
+
+        if (!controller.signal.aborted) {
+          setIsStreaming(false);
+        }
+      } catch (err) {
+        if (controller.signal.aborted) return;
+
+        setError(toError(err));
+        setIsConnecting(false);
+        setIsStreaming(false);
+      }
+    })();
+
+    return () => {
+      controller.abort();
+    };
+  }, [executionId, stigmer, connectKey]);
+
+  const phase = useMemo(
+    () =>
+      execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
+    [execution],
+  );
+
+  return { execution, phase, isStreaming, isConnecting, error, reconnect };
+}

package/src/execution/useExecutionUsage.ts

@@ -0,0 +1,213 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type {
+  UsageMetrics,
+  ModelUsage,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import {
+  UsageMetricsSchema,
+  ModelUsageSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+
+export interface UseExecutionUsageReturn {
+  /** Aggregated usage (main agent + sub-agents). Null before usage data arrives. */
+  readonly usage: UsageMetrics | null;
+  /** Whether any sub-agent contributed usage to the aggregated total. */
+  readonly hasSubAgentUsage: boolean;
+  /** Count of sub-agents that have non-null usage data. */
+  readonly subAgentUsageCount: number;
+}
+
+/**
+ * Pure derivation hook that aggregates {@link UsageMetrics} across the
+ * main agent and all sub-agents into a single {@link UsageMetrics} total.
+ *
+ * The proto scoping rule is:
+ * > `status.usage` = main agent's direct LLM usage (excludes sub-agents)
+ * > `subAgentExecutions[].usage` = each sub-agent's LLM usage
+ * > Total cost = `status.usage` + sum(`subAgentExecutions[].usage`)
+ *
+ * This hook performs that summation, merges `modelBreakdown` entries by
+ * `model+provider` key, and concatenates `llmCalls` sorted by timestamp.
+ *
+ * Returns `null` when the execution is absent or usage data has not yet
+ * arrived from the agent runner.
+ *
+ * @example
+ * ```tsx
+ * const { execution } = useExecutionStream(executionId);
+ * const { usage, hasSubAgentUsage } = useExecutionUsage(execution);
+ *
+ * if (usage) {
+ *   console.log(`Cost: $${usage.estimatedCostUsd}`);
+ *   console.log(`Tokens: ${usage.totalTokens}`);
+ * }
+ * ```
+ */
+export function useExecutionUsage(
+  execution: AgentExecution | null,
+): UseExecutionUsageReturn {
+  return useMemo(() => {
+    const usage = aggregateUsage(execution);
+
+    if (!usage) {
+      return { usage: null, hasSubAgentUsage: false, subAgentUsageCount: 0 };
+    }
+
+    const subAgents = execution?.status?.subAgentExecutions ?? [];
+    let subAgentUsageCount = 0;
+    for (const sub of subAgents) {
+      if (sub.usage) subAgentUsageCount++;
+    }
+
+    return {
+      usage,
+      hasSubAgentUsage: subAgentUsageCount > 0,
+      subAgentUsageCount,
+    };
+  }, [execution]);
+}
+
+// ---------------------------------------------------------------------------
+// Pure aggregation function — testable without React
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregates usage metrics from the main agent and all sub-agents into
+ * a single {@link UsageMetrics} proto object.
+ *
+ * Returns `null` when the execution or its usage data is not yet available.
+ */
+export function aggregateUsage(
+  execution: AgentExecution | null,
+): UsageMetrics | null {
+  const mainUsage = execution?.status?.usage;
+  if (!mainUsage) return null;
+
+  const subAgents = execution?.status?.subAgentExecutions ?? [];
+  const subUsages: UsageMetrics[] = [];
+  for (const sub of subAgents) {
+    if (sub.usage) subUsages.push(sub.usage);
+  }
+
+  if (subUsages.length === 0) return mainUsage;
+
+  const allUsages = [mainUsage, ...subUsages];
+
+  return create(UsageMetricsSchema, {
+    promptTokens: sumField(allUsages, "promptTokens"),
+    completionTokens: sumField(allUsages, "completionTokens"),
+    totalTokens: sumField(allUsages, "totalTokens"),
+    llmCallCount: sumField(allUsages, "llmCallCount"),
+    cacheCreationTokens: sumField(allUsages, "cacheCreationTokens"),
+    cacheReadTokens: sumField(allUsages, "cacheReadTokens"),
+    estimatedCostUsd: sumField(allUsages, "estimatedCostUsd"),
+    totalDurationMs: sumField(allUsages, "totalDurationMs"),
+    llmDurationMs: sumField(allUsages, "llmDurationMs"),
+    toolDurationMs: sumField(allUsages, "toolDurationMs"),
+    approvalWaitDurationMs: sumField(allUsages, "approvalWaitDurationMs"),
+    toolResultCharsTruncated: sumBigIntField(allUsages),
+    primaryModel: mainUsage.primaryModel,
+    primaryProvider: mainUsage.primaryProvider,
+    modelBreakdown: mergeModelBreakdowns(allUsages),
+    llmCalls: mergeLlmCalls(allUsages),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+type NumericField = keyof {
+  [K in keyof UsageMetrics as UsageMetrics[K] extends number ? K : never]: true;
+};
+
+function sumField(usages: UsageMetrics[], field: NumericField): number {
+  let total = 0;
+  for (const u of usages) {
+    total += u[field] as number;
+  }
+  return total;
+}
+
+function sumBigIntField(usages: UsageMetrics[]): bigint {
+  let total = BigInt(0);
+  for (const u of usages) {
+    total += u.toolResultCharsTruncated;
+  }
+  return total;
+}
+
+/**
+ * Merges model breakdown entries across all usages by `model+provider` key.
+ * Entries for the same model and provider are combined into a single
+ * {@link ModelUsage} with summed numeric fields. Pricing rates are taken
+ * from the first entry encountered for each key (rates are stamped at
+ * execution time and are identical for the same model).
+ */
+function mergeModelBreakdowns(usages: UsageMetrics[]): ModelUsage[] {
+  const merged = new Map<
+    string,
+    {
+      model: string;
+      provider: string;
+      inputTokens: number;
+      outputTokens: number;
+      cacheCreationTokens: number;
+      cacheReadTokens: number;
+      callCount: number;
+      estimatedCostUsd: number;
+      inputPricePerMillion: number;
+      outputPricePerMillion: number;
+      cacheCreationPricePerMillion: number;
+      cacheReadPricePerMillion: number;
+    }
+  >();
+
+  for (const usage of usages) {
+    for (const entry of usage.modelBreakdown) {
+      const key = `${entry.model}\0${entry.provider}`;
+      const existing = merged.get(key);
+
+      if (existing) {
+        existing.inputTokens += entry.inputTokens;
+        existing.outputTokens += entry.outputTokens;
+        existing.cacheCreationTokens += entry.cacheCreationTokens;
+        existing.cacheReadTokens += entry.cacheReadTokens;
+        existing.callCount += entry.callCount;
+        existing.estimatedCostUsd += entry.estimatedCostUsd;
+      } else {
+        merged.set(key, {
+          model: entry.model,
+          provider: entry.provider,
+          inputTokens: entry.inputTokens,
+          outputTokens: entry.outputTokens,
+          cacheCreationTokens: entry.cacheCreationTokens,
+          cacheReadTokens: entry.cacheReadTokens,
+          callCount: entry.callCount,
+          estimatedCostUsd: entry.estimatedCostUsd,
+          inputPricePerMillion: entry.inputPricePerMillion,
+          outputPricePerMillion: entry.outputPricePerMillion,
+          cacheCreationPricePerMillion: entry.cacheCreationPricePerMillion,
+          cacheReadPricePerMillion: entry.cacheReadPricePerMillion,
+        });
+      }
+    }
+  }
+
+  return Array.from(merged.values()).map((m) => create(ModelUsageSchema, m));
+}
+
+/**
+ * Concatenates `llmCalls` from all usages, sorted by ISO 8601 timestamp.
+ * This gives a globally chronological view across main agent and sub-agents,
+ * since per-agent `sequence` numbers overlap.
+ */
+function mergeLlmCalls(usages: UsageMetrics[]): UsageMetrics["llmCalls"] {
+  const all = usages.flatMap((u) => u.llmCalls);
+  if (all.length <= 1) return all;
+  return all.slice().sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}