@stigmer/react 0.3.4 → 0.4.1

package/src/session/useSessionConversation.ts

@@ -17,6 +17,7 @@ import type {
 } from "@stigmer/sdk";
 import { isTerminalPhase } from "../execution/execution-phases";
 import { useStigmer } from "../hooks";
+import { useConversationStoreRef } from "../internal/store";
 import { useCreateAgentExecution } from "../execution/useCreateAgentExecution";
 import { useExecutionStream } from "../execution/useExecutionStream";
 import { useSubmitApproval } from "../execution/useSubmitApproval";
@@ -248,7 +249,14 @@ export function useSessionConversation(
 
   const activeExecutionId = pendingExecutionId ?? listActiveId;
 
-  const stream = useExecutionStream(activeExecutionId);
+  // The conversation store is shared between useExecutionStream (which
+  // ingests snapshots with structural sharing + rAF coalescing) and the
+  // rendering tree. This eliminates the duplicate structuralShare that
+  // was previously done in this hook.
+  const conversationStore = useConversationStoreRef();
+  const stream = useExecutionStream(activeExecutionId, {
+    store: conversationStore,
+  });
 
   // Clear pendingExecutionId once the execution appears in the fetched list
   useEffect(() => {
@@ -291,7 +299,8 @@ export function useSessionConversation(
     );
   }, [executions, activeExecutionId]);
 
-  const activeStreamExecution = stream.execution ?? fetchedActiveExecution;
+  const activeStreamExecution =
+    stream.execution ?? fetchedActiveExecution;
 
   const activePhase = useMemo<ExecutionPhase | null>(() => {
     if (!activeExecutionId) return null;

package/src/session/useSessionExecutions.ts

@@ -73,6 +73,7 @@ export function useSessionExecutions(
       : null,
     [sessionId, stigmer],
     [] as AgentExecution[],
+    { cacheKey: sessionId ? `session-executions:${sessionId}` : undefined },
   );
 
   return { executions, isLoading, isRefetching, error, refetch };

package/src/session/useSessionPageFlow.ts

@@ -253,7 +253,7 @@ export function useSessionPageFlow(
 
       sessionVariables.clear();
     },
-    [conv, modelId, workspace, mcpServerUsages, skillRefs, sessionVariables, resolution, agentRef, sessionInstanceId, stigmer],
+    [conv.sendFollowUp, modelId, workspace, mcpServerUsages, skillRefs, sessionVariables.clear, resolution, agentRef, sessionInstanceId, stigmer],
   );
 
   // -------------------------------------------------------------------------

package/src/session/useSessionUsage.ts

@@ -1,27 +1,33 @@
 "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 { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { LlmCallMetrics } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import {
+  GetSessionUsageReportInputSchema,
+  type GetSessionUsageReportOutput,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { ModelUsage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
 
 /**
- * Per-model cost breakdown computed from per-message {@link LlmCallMetrics}.
+ * Per-model cost breakdown.
  */
 export interface ModelCostEntry {
-  /** Model identifier (e.g., `"claude-3-5-sonnet-20241022"`). */
+  /** Model identifier (e.g. "claude-sonnet-4-20250514"). */
   readonly model: string;
-  /** Provider that served the model (e.g., `"anthropic"`). */
+  /** Provider name (e.g. "anthropic", "openai"). */
   readonly provider: string;
-  /** Estimated cost in USD for all calls to this model. */
+  /** Estimated cost in USD for this model's usage. */
   readonly estimatedCostUsd: number;
-  /** Total non-cached input tokens across all calls to this model. */
+  /** Total input tokens consumed by this model. */
   readonly inputTokens: number;
-  /** Total output tokens across all calls to this model. */
+  /** Total output tokens generated by this model. */
   readonly outputTokens: number;
-  /** Total cache creation tokens across all calls to this model. */
+  /** Tokens used to create cache entries. */
   readonly cacheCreationTokens: number;
-  /** Total cache read tokens across all calls to this model. */
+  /** Tokens served from cache. */
   readonly cacheReadTokens: number;
   /** Number of LLM calls made to this model. */
   readonly callCount: number;
@@ -29,140 +35,113 @@ export interface ModelCostEntry {
 
 /** Return value of {@link useSessionUsage}. */
 export interface UseSessionUsageReturn {
-  /** Total estimated cost across all executions in the session. */
+  /** Aggregate estimated cost in USD across all models. */
   readonly totalCostUsd: number;
-  /** Total tokens (all types) across all executions. */
+  /** Total tokens (input + output) across all models. */
   readonly totalTokens: number;
-  /** Total input tokens (non-cached) across all executions. */
+  /** Total input tokens across all models. */
   readonly inputTokens: number;
-  /** Total output tokens across all executions. */
+  /** Total output tokens across all models. */
   readonly outputTokens: number;
-  /** Total cache read tokens across all executions. */
+  /** Total tokens served from cache across all models. */
   readonly cacheReadTokens: number;
-  /** Total cache creation tokens across all executions. */
+  /** Total tokens used to create cache entries across all models. */
   readonly cacheCreationTokens: number;
-  /** Total number of LLM calls across all executions. */
+  /** Total number of LLM calls in this session. */
   readonly llmCallCount: number;
-  /** Per-model breakdown, sorted by cost descending. */
+  /** Per-model cost and token breakdown. */
   readonly modelBreakdown: readonly ModelCostEntry[];
-  /** Primary model (first model encountered). */
+  /** Model with the highest usage in this session. */
   readonly primaryModel: string;
-  /** Primary provider (first provider encountered). */
+  /** Provider of the primary model. */
   readonly primaryProvider: string;
-  /** `true` when at least one execution has cost data. */
+  /** `true` when usage data is available. */
   readonly hasUsage: boolean;
 }
 
+const EMPTY: UseSessionUsageReturn = {
+  totalCostUsd: 0,
+  totalTokens: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheCreationTokens: 0,
+  llmCallCount: 0,
+  modelBreakdown: [],
+  primaryModel: "",
+  primaryProvider: "",
+  hasUsage: false,
+};
+
+function microsToUsd(micros: bigint): number {
+  return Number(micros) / 1_000_000;
+}
+
+function mapModelUsage(m: ModelUsage): ModelCostEntry {
+  return {
+    model: m.model,
+    provider: m.provider,
+    estimatedCostUsd: microsToUsd(m.billableCostMicros),
+    inputTokens: Number(m.inputTokens),
+    outputTokens: Number(m.outputTokens),
+    cacheCreationTokens: Number(m.cacheCreationInputTokens),
+    cacheReadTokens: Number(m.cacheReadInputTokens),
+    callCount: m.callCount,
+  };
+}
+
+function mapReport(report: GetSessionUsageReportOutput): UseSessionUsageReturn {
+  const agg = report.totalUsage;
+  if (!agg) return EMPTY;
+
+  return {
+    totalCostUsd: microsToUsd(agg.billableCostMicros),
+    totalTokens: Number(agg.totalTokens),
+    inputTokens: Number(agg.inputTokens),
+    outputTokens: Number(agg.outputTokens),
+    cacheReadTokens: Number(agg.cacheReadInputTokens),
+    cacheCreationTokens: Number(agg.cacheCreationInputTokens),
+    llmCallCount: agg.llmCallCount,
+    modelBreakdown: report.modelBreakdown.map(mapModelUsage),
+    primaryModel: agg.primaryModel,
+    primaryProvider: agg.primaryProvider,
+    hasUsage: true,
+  };
+}
+
 /**
- * Pure derivation hook that aggregates usage data across all executions
- * in a session from per-message {@link LlmCallMetrics}.
+ * Usage hook for session-level cost and token aggregation.
  *
- * 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.
+ * Calls `getSessionUsageReport` to fetch real usage data from the
+ * billing domain. Returns zeros while loading or when no session is
+ * available.
  *
- * 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);
- * ```
+ * @param executions - All executions for a session (used to derive session ID).
  */
 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;
+  const stigmer = useStigmer();
 
-      totalCostUsd += m.estimatedCostUsd;
-      totalTokens += m.totalTokens;
-      inputTokens += m.inputTokens;
-      outputTokens += m.outputTokens;
-      cacheReadTokens += m.cacheReadTokens;
-      cacheCreationTokens += m.cacheCreationTokens;
-      llmCallCount++;
+  const sessionId = useMemo(
+    () => executions[0]?.spec?.sessionId ?? null,
+    [executions],
+  );
 
-      if (!primaryModel && m.model) {
-        primaryModel = m.model;
-        primaryProvider = m.provider;
-      }
+  const { data: report } = useFetch(
+    sessionId
+      ? () =>
+          stigmer.agentExecution.getSessionUsageReport(
+            create(GetSessionUsageReportInputSchema, { sessionId }),
+          )
+      : null,
+    [sessionId, stigmer],
+    null as GetSessionUsageReportOutput | null,
+    { cacheKey: sessionId ? `session-usage:${sessionId}` : undefined },
+  );
 
-      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]);
+  return useMemo(() => {
+    if (!report) return EMPTY;
+    return mapReport(report);
+  }, [report]);
 }

package/src/settings/BillingSection.tsx

@@ -0,0 +1,4 @@
+"use client";
+
+export { BillingSection } from "../billing/BillingSection";
+export type { BillingSectionProps } from "../billing/BillingSection";

package/src/settings/index.ts

@@ -2,6 +2,8 @@ export { SETTINGS_NAV_GROUPS } from "./settings-nav";
 export type { SettingsNavItem, SettingsNavGroup } from "./settings-nav";
 
 export { ApiKeysSection } from "./ApiKeysSection";
+export { BillingSection } from "./BillingSection";
+export type { BillingSectionProps } from "./BillingSection";
 export { MembersSection } from "./MembersSection";
 export { OrgProfileSection } from "./OrgProfileSection";
 export { EnvironmentsSection } from "./EnvironmentsSection";

package/src/settings/settings-nav.ts

@@ -69,7 +69,7 @@ export const SETTINGS_NAV_GROUPS: readonly SettingsNavGroup[] = [
   },
   {
     label: "Billing & Usage",
-    description: "Subscription management and usage metrics.",
+    description: "Credit management and usage metrics.",
     items: [
       { href: "/settings/billing", label: "Billing", icon: CreditCard },
       { href: "/settings/usage", label: "Usage", icon: BarChart3 },

package/src/styles.css

@@ -1,4 +1,5 @@
 @source "./**/*.{ts,tsx}";
+@source "../node_modules/streamdown/dist/*.js";
 
 @layer stgm;
 
@@ -82,6 +83,8 @@
 
 @layer stgm {
   .stgm {
+    --stgm-motion-duration: 150ms;
+    --stgm-motion-easing: var(--stgm-transition-timing, ease-out);
     line-height: 1.5;
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
@@ -95,4 +98,32 @@
     border-style: solid;
     border-color: var(--stgm-border, currentColor);
   }
+
+  @keyframes stgm-fade-in-up {
+    from {
+      opacity: 0;
+      transform: translateY(6px);
+    }
+  }
+
+  .stgm-thread-item-enter {
+    animation: stgm-fade-in-up var(--stgm-motion-duration) var(--stgm-motion-easing) both;
+  }
+}
+
+@layer stgm {
+  @media (prefers-reduced-motion: reduce) {
+    .stgm {
+      --stgm-motion-duration: 0ms;
+      --stgm-transition-duration: 0ms;
+    }
+
+    .stgm *,
+    .stgm *::before,
+    .stgm *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
 }

package/src/usage/AgentBreakdownList.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { AgentUsageSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { formatCost } from "../execution/UsageWidget";
+
+/** Props for {@link AgentBreakdownList}. */
+export interface AgentBreakdownListProps {
+  /** Top agents by cost, ordered by billable cost descending. */
+  readonly agents: readonly AgentUsageSummary[];
+  /** Total billable cost for the org (used to compute percentages). */
+  readonly totalBillableCostMicros: bigint;
+  /** Optional href builder for agent links. Receives the agent ID. */
+  readonly agentHref?: (agentId: string) => string;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Renders a ranked list of agents by cost with proportional cost bars.
+ *
+ * Each row shows the agent name, execution count, token usage,
+ * billable cost, and a visual bar representing cost as a percentage
+ * of the organization total.
+ */
+export function AgentBreakdownList({
+  agents,
+  totalBillableCostMicros,
+  agentHref,
+  className,
+}: AgentBreakdownListProps) {
+  if (agents.length === 0) return null;
+
+  const totalCost = Number(totalBillableCostMicros);
+  const maxCost =
+    agents.length > 0 ? Number(agents[0].billableCostMicros) : 0;
+
+  return (
+    <div className={className}>
+      <h3 className="mb-2 text-xs font-semibold text-foreground">
+        Top Agents by Cost
+      </h3>
+      <div
+        className="rounded-lg border border-border bg-card"
+        role="table"
+        aria-label="Agent cost breakdown"
+      >
+        <div
+          role="row"
+          className="grid grid-cols-[1fr_auto_auto_auto] gap-x-4 border-b border-border px-3.5 py-2 text-[0.65rem] font-medium uppercase tracking-wider text-muted-foreground"
+        >
+          <span role="columnheader">Agent</span>
+          <span role="columnheader" className="text-right">
+            Runs
+          </span>
+          <span role="columnheader" className="text-right">
+            Tokens
+          </span>
+          <span role="columnheader" className="text-right">
+            Cost
+          </span>
+        </div>
+        {agents.map((agent) => {
+          const cost = Number(agent.billableCostMicros);
+          const pct = totalCost > 0 ? (cost / totalCost) * 100 : 0;
+          const barWidth =
+            maxCost > 0 ? (cost / maxCost) * 100 : 0;
+
+          const NameTag = agentHref ? "a" : "span";
+          const nameProps = agentHref
+            ? { href: agentHref(agent.agentId) }
+            : {};
+
+          return (
+            <div
+              key={agent.agentId}
+              className="border-b border-border-muted px-3.5 py-2 last:border-b-0"
+            >
+              <div
+                role="row"
+                className="grid grid-cols-[1fr_auto_auto_auto] gap-x-4"
+              >
+                <div role="cell" className="min-w-0">
+                  <NameTag
+                    {...nameProps}
+                    className={cn(
+                      "block truncate text-xs font-medium",
+                      agentHref
+                        ? "text-primary hover:underline"
+                        : "text-foreground",
+                    )}
+                  >
+                    {agent.agentName || agent.agentId}
+                  </NameTag>
+                </div>
+                <span
+                  role="cell"
+                  className="self-center text-right text-xs tabular-nums text-muted-foreground"
+                >
+                  {agent.executionCount}
+                </span>
+                <span
+                  role="cell"
+                  className="self-center text-right text-xs tabular-nums text-muted-foreground"
+                >
+                  {formatCompactTokens(Number(agent.totalTokens))}
+                </span>
+                <span
+                  role="cell"
+                  className="self-center text-right text-xs tabular-nums text-foreground"
+                >
+                  {formatCost(cost / 1_000_000)}
+                  <span className="ml-1.5 text-[0.6rem] text-muted-foreground">
+                    {pct.toFixed(0)}%
+                  </span>
+                </span>
+              </div>
+              {/* Proportional cost bar */}
+              <div className="mt-1.5 h-1 w-full rounded-full bg-muted">
+                <div
+                  className="h-full rounded-full bg-chart-2 transition-all"
+                  style={{ width: `${barWidth}%` }}
+                />
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function formatCompactTokens(n: number): string {
+  if (n >= 1_000_000) {
+    const v = n / 1_000_000;
+    return v >= 100 ? `${Math.round(v)}M` : `${trimZero(v.toFixed(1))}M`;
+  }
+  if (n >= 1_000) {
+    const v = n / 1_000;
+    return v >= 100 ? `${Math.round(v)}K` : `${trimZero(v.toFixed(1))}K`;
+  }
+  return String(n);
+}
+
+function trimZero(s: string): string {
+  return s.endsWith(".0") ? s.slice(0, -2) : s;
+}

package/src/usage/CreditRunwayIndicator.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import { useBillingAccount } from "../billing/useBillingAccount";
+import { useOrg } from "../organization/OrgProvider";
+import { useDeploymentMode } from "../deployment-mode";
+
+/** Props for {@link CreditRunwayIndicator}. */
+export interface CreditRunwayIndicatorProps {
+  /** Total billable cost in micro-USD for the report period. */
+  readonly totalBillableCostMicros: bigint;
+  /** Number of calendar days the report covers. */
+  readonly daysInRange: number;
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+/**
+ * Displays projected credit runway: "~N days at this rate".
+ *
+ * Computes runway by dividing available balance by the daily spend rate
+ * derived from the usage report. Color-coded by urgency:
+ * green (>14d), amber (7-14d), red (<7d).
+ *
+ * Requires `useBillingAccount` — renders nothing in local mode or if
+ * billing data is unavailable.
+ */
+export function CreditRunwayIndicator({
+  totalBillableCostMicros,
+  daysInRange,
+  className,
+}: CreditRunwayIndicatorProps) {
+  const mode = useDeploymentMode();
+  const { activeOrg } = useOrg();
+  const orgId = activeOrg?.metadata?.id ?? "";
+  const { account } = useBillingAccount(mode === "cloud" ? orgId : "");
+
+  if (!account?.balance || daysInRange <= 0) return null;
+
+  const totalCost = Number(totalBillableCostMicros);
+  if (totalCost <= 0) return null;
+
+  const dailyRate = totalCost / daysInRange;
+  const availableMicros = Number(account.balance.availableMicros);
+  const runwayDays = Math.floor(availableMicros / dailyRate);
+
+  if (runwayDays < 0) return null;
+
+  const label =
+    runwayDays === 0
+      ? "Less than 1 day remaining"
+      : `~${runwayDays} day${runwayDays === 1 ? "" : "s"} at this rate`;
+
+  const urgency: "healthy" | "warning" | "critical" =
+    runwayDays > 14 ? "healthy" : runwayDays >= 7 ? "warning" : "critical";
+
+  return (
+    <span
+      className={cn(
+        "text-xs tabular-nums",
+        urgency === "healthy" && "text-emerald-600 dark:text-emerald-400",
+        urgency === "warning" && "text-amber-600 dark:text-amber-400",
+        urgency === "critical" && "text-red-600 dark:text-red-400",
+        className,
+      )}
+      aria-label={`Credit runway: ${label}`}
+    >
+      {label}
+    </span>
+  );
+}