@stigmer/react 0.0.56 → 0.0.58

package/src/execution/{ExecutionCostSummary.tsx → UsageWidget.tsx}

@@ -1,51 +1,59 @@
 "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;
+import {
+  useSessionUsage,
+  type ModelCostEntry,
+} from "../session/useSessionUsage";
+
+export interface UsageWidgetProps {
+  /**
+   * All executions for the current session — both completed and
+   * actively streaming.  The widget aggregates cost data across
+   * every execution's per-message `llm_metrics`, presenting a
+   * session-level total that never resets.
+   *
+   * Renders nothing when the list is empty or no execution has
+   * usage data.
+   */
+  readonly executions: readonly AgentExecution[];
+  /** Additional CSS classes for the root element. */
   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.
+ * Right-sidebar widget that displays session-level cost and token
+ * usage aggregated from per-message {@link LlmCallMetrics}.
  *
- * 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.
+ * Usage data is computed purely from messages the frontend already
+ * has — no server RPC is required for the real-time widget.
  *
- * When multiple models are used (common in sub-agent executions), the
- * single model line is replaced with a per-model cost breakdown.
+ * Returns `null` when no execution has usage data, matching the
+ * conditional-render pattern of {@link ArtifactsWidget} and
+ * {@link WriteBacksWidget}.
  *
- * Renders without card chrome — the consumer provides the container.
- * All visual properties flow through `--stgm-*` tokens.
+ * All visual properties flow through `--stgm-*` tokens. Zero
+ * Console dependencies.
  *
  * @example
  * ```tsx
- * const stream = useExecutionStream(executionId);
+ * const conv = useSessionConversation(sessionId, org);
  *
- * <div className="rounded-lg border border-border bg-card p-3">
- *   <ExecutionCostSummary execution={stream.execution} />
- * </div>
+ * <UsageWidget
+ *   executions={[
+ *     ...conv.completedExecutions,
+ *     ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ *   ]}
+ * />
  * ```
+ *
+ * @see {@link useSessionUsage} — headless session-level usage aggregation hook
  */
-export function ExecutionCostSummary({
-  execution,
-  className,
-}: ExecutionCostSummaryProps) {
-  const { usage, hasSubAgentUsage, subAgentUsageCount } =
-    useExecutionUsage(execution);
+export function UsageWidget({ executions, className }: UsageWidgetProps) {
+  const usage = useSessionUsage(executions);
 
-  if (!usage) return null;
+  if (!usage.hasUsage) return null;
 
   const multiModel = usage.modelBreakdown.length > 1;
 
@@ -53,10 +61,10 @@ export function ExecutionCostSummary({
     <div
       className={cn("flex flex-col gap-1.5", className)}
       role="region"
-      aria-label="Execution cost summary"
+      aria-label="Session cost summary"
     >
       <div className="text-sm font-medium tabular-nums text-foreground">
-        {formatCost(usage.estimatedCostUsd)}
+        {formatCost(usage.totalCostUsd)}
       </div>
 
       {multiModel ? (
@@ -74,8 +82,8 @@ export function ExecutionCostSummary({
       </div>
 
       <div className="pl-2 text-xs tabular-nums text-muted-foreground">
-        prompt {formatTokenCount(usage.promptTokens)} · completion{" "}
-        {formatTokenCount(usage.completionTokens)}
+        prompt {formatTokenCount(usage.inputTokens)} · completion{" "}
+        {formatTokenCount(usage.outputTokens)}
       </div>
 
       {(usage.cacheReadTokens > 0 || usage.cacheCreationTokens > 0) && (
@@ -84,25 +92,14 @@ export function ExecutionCostSummary({
           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[];
+  readonly models: readonly ModelCostEntry[];
 }) {
   return (
     <div
@@ -145,10 +142,6 @@ function CacheLine({
   );
 }
 
-// ---------------------------------------------------------------------------
-// Formatting utilities
-// ---------------------------------------------------------------------------
-
 /**
  * Formats a USD cost value for display.
  * - Zero: "$0.00"

package/src/execution/index.ts

@@ -10,8 +10,8 @@ export { isTerminalPhase } from "./execution-phases";
 export { useExecutionStream } from "./useExecutionStream";
 export type { UseExecutionStreamReturn } from "./useExecutionStream";
 
-export { useExecutionUsage, aggregateUsage } from "./useExecutionUsage";
-export type { UseExecutionUsageReturn } from "./useExecutionUsage";
+export { UsageWidget, formatCost, formatTokenCount } from "./UsageWidget";
+export type { UsageWidgetProps } from "./UsageWidget";
 
 export { useExecutionArtifacts } from "./useExecutionArtifacts";
 export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts";
@@ -89,8 +89,14 @@ export type { FollowUpInputProps } from "./FollowUpInput";
 export { ExecutionProgress } from "./ExecutionProgress";
 export type { ExecutionProgressProps } from "./ExecutionProgress";
 
-export { ExecutionCostSummary, formatCost, formatTokenCount } from "./ExecutionCostSummary";
-export type { ExecutionCostSummaryProps } from "./ExecutionCostSummary";
+export {
+  TodoList,
+  TodoInProgressIcon,
+  findActiveTodo,
+  todoCompletionSummary,
+} from "./TodoList";
+export type { TodoListProps } from "./TodoList";
+
 
 export { useSubmitApproval } from "./useSubmitApproval";
 export type { UseSubmitApprovalReturn } from "./useSubmitApproval";

package/src/execution/useExecutionArtifacts.ts

@@ -17,7 +17,7 @@ export interface UseExecutionArtifactsReturn {
  * Pure derivation hook that extracts artifact metadata from an
  * {@link AgentExecution} snapshot.
  *
- * Follows the same pattern as {@link useExecutionUsage}: a `useMemo`-based
+ * Follows the same pattern as {@link useSessionUsage}: a `useMemo`-based
  * derivation with no side effects and no data fetching. The execution
  * object (typically from {@link useExecutionStream}) is the single input.
  *

package/src/index.ts

@@ -54,6 +54,7 @@ export {
   useSessionConversation,
   useSessionArtifacts,
   useSessionWriteBacks,
+  useSessionUsage,
   useAgentRefFromSession,
   groupSessionsByTime,
   PENDING_SUBJECT,
@@ -74,6 +75,8 @@ export type {
   UseSessionArtifactsReturn,
   SessionWriteBackEntry,
   UseSessionWriteBacksReturn,
+  ModelCostEntry,
+  UseSessionUsageReturn,
   UseAgentRefFromSessionReturn,
   SessionGroup,
 } from "./session";
@@ -83,13 +86,17 @@ export {
   isTerminalPhase,
   useCreateAgentExecution,
   useExecutionStream,
-  useExecutionUsage,
-  aggregateUsage,
   useSubmitApproval,
   ExecutionPhaseBadge,
   SetupProgress,
   ExecutionProgress,
-  ExecutionCostSummary,
+  TodoList,
+  TodoInProgressIcon,
+  findActiveTodo,
+  todoCompletionSummary,
+  UsageWidget,
+  formatCost,
+  formatTokenCount,
   ToolCallGroup,
   ToolCallDetail,
   McpToolDetail,
@@ -133,12 +140,12 @@ export type {
   CreateAgentExecutionResult,
   UseCreateAgentExecutionReturn,
   UseExecutionStreamReturn,
-  UseExecutionUsageReturn,
   UseSubmitApprovalReturn,
   ExecutionPhaseBadgeProps,
   SetupProgressProps,
   ExecutionProgressProps,
-  ExecutionCostSummaryProps,
+  TodoListProps,
+  UsageWidgetProps,
   ToolCallGroupProps,
   ToolCallDetailProps,
   McpToolDetailProps,

package/src/session/index.ts

@@ -38,6 +38,12 @@ export type {
   UseSessionWriteBacksReturn,
 } from "./useSessionWriteBacks";
 
+export { useSessionUsage } from "./useSessionUsage";
+export type {
+  ModelCostEntry,
+  UseSessionUsageReturn,
+} from "./useSessionUsage";
+
 export { useAgentRefFromSession } from "./useAgentRefFromSession";
 export type { UseAgentRefFromSessionReturn } from "./useAgentRefFromSession";
 

package/src/session/useSessionUsage.ts

@@ -0,0 +1,159 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { LlmCallMetrics } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+
+/**
+ * Per-model cost breakdown computed from per-message {@link LlmCallMetrics}.
+ */
+export interface ModelCostEntry {
+  readonly model: string;
+  readonly provider: string;
+  readonly estimatedCostUsd: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheCreationTokens: number;
+  readonly cacheReadTokens: number;
+  readonly callCount: number;
+}
+
+export interface UseSessionUsageReturn {
+  /** Total estimated cost across all executions in the session. */
+  readonly totalCostUsd: number;
+  /** Total tokens (all types) across all executions. */
+  readonly totalTokens: number;
+  /** Total input tokens (non-cached) across all executions. */
+  readonly inputTokens: number;
+  /** Total output tokens across all executions. */
+  readonly outputTokens: number;
+  /** Total cache read tokens across all executions. */
+  readonly cacheReadTokens: number;
+  /** Total cache creation tokens across all executions. */
+  readonly cacheCreationTokens: number;
+  /** Total number of LLM calls across all executions. */
+  readonly llmCallCount: number;
+  /** Per-model breakdown, sorted by cost descending. */
+  readonly modelBreakdown: readonly ModelCostEntry[];
+  /** Primary model (first model encountered). */
+  readonly primaryModel: string;
+  /** Primary provider (first provider encountered). */
+  readonly primaryProvider: string;
+  /** `true` when at least one execution has cost data. */
+  readonly hasUsage: boolean;
+}
+
+/**
+ * Pure derivation hook that aggregates usage data across all executions
+ * in a session from per-message {@link LlmCallMetrics}.
+ *
+ * Follows the same pattern as {@link useSessionArtifacts} and
+ * {@link useSessionWriteBacks}: `useMemo`-based derivation, no side
+ * effects, no data fetching. Takes the same `executions` array input.
+ *
+ * Per-message `llm_metrics` on `AgentMessage` (type == MESSAGE_AI) is
+ * the single source of truth for cost data. This hook walks all messages
+ * (main agent + sub-agents) across all executions and sums the fields.
+ *
+ * @param executions - All executions for a session, in chronological
+ *   order. Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId, org);
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { totalCostUsd, totalTokens, hasUsage } = useSessionUsage(allExecutions);
+ * ```
+ */
+export function useSessionUsage(
+  executions: readonly AgentExecution[],
+): UseSessionUsageReturn {
+  return useMemo(() => {
+    let totalCostUsd = 0;
+    let totalTokens = 0;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheCreationTokens = 0;
+    let llmCallCount = 0;
+    let primaryModel = "";
+    let primaryProvider = "";
+    const modelMap = new Map<string, ModelCostEntry>();
+
+    const processMessage = (msg: { type: MessageType; llmMetrics?: LlmCallMetrics }) => {
+      const m = msg.llmMetrics;
+      if (!m) return;
+
+      totalCostUsd += m.estimatedCostUsd;
+      totalTokens += m.totalTokens;
+      inputTokens += m.inputTokens;
+      outputTokens += m.outputTokens;
+      cacheReadTokens += m.cacheReadTokens;
+      cacheCreationTokens += m.cacheCreationTokens;
+      llmCallCount++;
+
+      if (!primaryModel && m.model) {
+        primaryModel = m.model;
+        primaryProvider = m.provider;
+      }
+
+      const key = `${m.model}\0${m.provider}`;
+      const existing = modelMap.get(key);
+      if (existing) {
+        modelMap.set(key, {
+          ...existing,
+          estimatedCostUsd: existing.estimatedCostUsd + m.estimatedCostUsd,
+          inputTokens: existing.inputTokens + m.inputTokens,
+          outputTokens: existing.outputTokens + m.outputTokens,
+          cacheCreationTokens: existing.cacheCreationTokens + m.cacheCreationTokens,
+          cacheReadTokens: existing.cacheReadTokens + m.cacheReadTokens,
+          callCount: existing.callCount + 1,
+        });
+      } else {
+        modelMap.set(key, {
+          model: m.model,
+          provider: m.provider,
+          estimatedCostUsd: m.estimatedCostUsd,
+          inputTokens: m.inputTokens,
+          outputTokens: m.outputTokens,
+          cacheCreationTokens: m.cacheCreationTokens,
+          cacheReadTokens: m.cacheReadTokens,
+          callCount: 1,
+        });
+      }
+    };
+
+    for (const execution of executions) {
+      for (const msg of execution.status?.messages ?? []) {
+        processMessage(msg);
+      }
+      for (const sub of execution.status?.subAgentExecutions ?? []) {
+        for (const msg of sub.messages) {
+          processMessage(msg);
+        }
+      }
+    }
+
+    const modelBreakdown = Array.from(modelMap.values()).sort(
+      (a, b) => b.estimatedCostUsd - a.estimatedCostUsd,
+    );
+
+    return {
+      totalCostUsd,
+      totalTokens,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheCreationTokens,
+      llmCallCount,
+      modelBreakdown,
+      primaryModel,
+      primaryProvider,
+      hasUsage: llmCallCount > 0,
+    };
+  }, [executions]);
+}