@stigmer/react 0.3.3 → 0.4.0

package/src/usage/HarnessSplitCard.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+import type { HarnessCostSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { formatCost } from "../execution/UsageWidget";
+
+/** Props for {@link HarnessSplitCard}. */
+export interface HarnessSplitCardProps {
+  /** Harness breakdown entries from the org usage report. */
+  readonly breakdown: readonly HarnessCostSummary[];
+  /** Additional CSS class names. */
+  readonly className?: string;
+}
+
+const HARNESS_LABELS: Record<string, string> = {
+  native: "Native",
+  cursor: "Cursor",
+};
+
+const HARNESS_COLORS: Record<string, string> = {
+  native: "bg-chart-1",
+  cursor: "bg-chart-3",
+};
+
+/**
+ * Displays the cost split between execution harnesses as a segmented bar.
+ *
+ * Renders a two-tone horizontal bar with labels showing cost and percentage
+ * per harness. Designed for at-a-glance understanding of native vs cursor
+ * cost distribution.
+ */
+export function HarnessSplitCard({
+  breakdown,
+  className,
+}: HarnessSplitCardProps) {
+  if (breakdown.length === 0) return null;
+
+  const totalCost = breakdown.reduce(
+    (sum, h) => sum + Number(h.billableCostMicros),
+    0,
+  );
+
+  if (totalCost <= 0) return null;
+
+  return (
+    <div className={className}>
+      <h3 className="mb-2 text-xs font-semibold text-foreground">
+        Harness Split
+      </h3>
+      <div className="rounded-lg border border-border bg-card px-3.5 py-3">
+        {/* Segmented bar */}
+        <div
+          className="flex h-3 w-full overflow-hidden rounded-full"
+          role="img"
+          aria-label="Cost distribution by harness"
+        >
+          {breakdown.map((entry) => {
+            const cost = Number(entry.billableCostMicros);
+            const pct = (cost / totalCost) * 100;
+            if (pct <= 0) return null;
+            return (
+              <div
+                key={entry.harness}
+                className={cn(
+                  "transition-all",
+                  HARNESS_COLORS[entry.harness] ?? "bg-chart-4",
+                )}
+                style={{ width: `${pct}%` }}
+              />
+            );
+          })}
+        </div>
+
+        {/* Labels */}
+        <div className="mt-2.5 flex flex-wrap gap-x-5 gap-y-1">
+          {breakdown.map((entry) => {
+            const cost = Number(entry.billableCostMicros);
+            const pct = totalCost > 0 ? (cost / totalCost) * 100 : 0;
+            return (
+              <div key={entry.harness} className="flex items-center gap-1.5">
+                <div
+                  className={cn(
+                    "size-2 rounded-full",
+                    HARNESS_COLORS[entry.harness] ?? "bg-chart-4",
+                  )}
+                />
+                <span className="text-xs text-muted-foreground">
+                  {HARNESS_LABELS[entry.harness] ?? entry.harness}
+                </span>
+                <span className="text-xs tabular-nums font-medium text-foreground">
+                  {formatCost(cost / 1_000_000)}
+                </span>
+                <span className="text-[0.6rem] tabular-nums text-muted-foreground">
+                  ({pct.toFixed(0)}%)
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/usage/OrgUsagePanel.tsx

@@ -17,6 +17,11 @@ import {
   presetLabel,
   type DateRangePreset,
 } from "./date-range";
+import { CreditRunwayIndicator } from "./CreditRunwayIndicator";
+import { AgentBreakdownList } from "./AgentBreakdownList";
+import { HarnessSplitCard } from "./HarnessSplitCard";
+import { ExportButton } from "./ExportButton";
+import { useExportCSV } from "./useExportCSV";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -49,6 +54,8 @@ export function OrgUsagePanel({ orgId, className }: OrgUsagePanelProps) {
   const [preset, setPreset] = useState<DateRangePreset>("30d");
   const dateRange = dateRangeFromPreset(preset);
   const { report, isLoading, error } = useOrgUsageReport(orgId, dateRange);
+  const { exportCSV, isExporting } = useExportCSV(report, orgId);
+  const daysInRange = Number.parseInt(preset, 10);
 
   if (isLoading) {
     return (
@@ -90,18 +97,36 @@ export function OrgUsagePanel({ orgId, className }: OrgUsagePanelProps) {
 
   return (
     <div className={cn("space-y-6", className)}>
-      <DateRangeSelector
-        activePreset={preset}
-        onPresetChange={setPreset}
-        dateRange={dateRange}
-      />
+      <div className="flex items-center justify-between gap-3">
+        <DateRangeSelector
+          activePreset={preset}
+          onPresetChange={setPreset}
+          dateRange={dateRange}
+        />
+        <ExportButton
+          onExport={exportCSV}
+          isExporting={isExporting}
+          disabled={!report || report.modelBreakdown.length === 0}
+        />
+      </div>
 
-      <SummaryCards report={report} />
+      <SummaryCards report={report} daysInRange={daysInRange} />
 
       {report.dailyCosts.length > 0 && (
         <DailyCostChart entries={report.dailyCosts} />
       )}
 
+      {report.harnessBreakdown.length > 0 && (
+        <HarnessSplitCard breakdown={report.harnessBreakdown} />
+      )}
+
+      {report.topAgentsByCost.length > 0 && (
+        <AgentBreakdownList
+          agents={report.topAgentsByCost}
+          totalBillableCostMicros={report.totalBillableCostMicros}
+        />
+      )}
+
       {report.modelBreakdown.length > 0 && (
         <ModelBreakdownList models={report.modelBreakdown} />
       )}
@@ -126,7 +151,7 @@ function DateRangeSelector({
 }) {
   return (
     <div
-      className="flex items-center justify-between gap-3"
+      className="flex items-center gap-3"
       role="group"
       aria-label="Date range"
     >
@@ -159,43 +184,80 @@ function DateRangeSelector({
 // SummaryCards (internal)
 // ---------------------------------------------------------------------------
 
-function SummaryCards({ report }: { report: GetOrgUsageReportOutput }) {
+function microsToUsd(micros: bigint): number {
+  return Number(micros) / 1_000_000;
+}
+
+function SummaryCards({
+  report,
+  daysInRange,
+}: {
+  report: GetOrgUsageReportOutput;
+  daysInRange: number;
+}) {
   const { totalLlmCalls, totalTokens } = report.modelBreakdown.reduce(
     (acc, m) => ({
       totalLlmCalls: acc.totalLlmCalls + m.callCount,
       totalTokens:
         acc.totalTokens +
-        m.inputTokens +
-        m.outputTokens +
-        m.cacheCreationTokens +
-        m.cacheReadTokens,
+        Number(m.inputTokens) +
+        Number(m.outputTokens) +
+        Number(m.cacheCreationInputTokens) +
+        Number(m.cacheReadInputTokens),
     }),
     { totalLlmCalls: 0, totalTokens: 0 },
   );
 
-  const cards: { label: string; value: string }[] = [
-    { label: "Total Cost", value: formatCost(report.totalCostUsd) },
-    { label: "LLM Calls", value: formatCompactNumber(totalLlmCalls) },
-    { label: "Tokens", value: formatCompactNumber(totalTokens) },
-  ];
-
   return (
-    <div
-      className="grid grid-cols-3 gap-3"
-      role="group"
-      aria-label="Usage summary"
-    >
-      {cards.map((card) => (
-        <div
-          key={card.label}
-          className="rounded-lg border border-border bg-card px-3.5 py-3"
-        >
+    <div role="group" aria-label="Usage summary" className="space-y-2">
+      {/* Primary row */}
+      <div className="grid grid-cols-3 gap-3">
+        <div className="rounded-lg border border-border bg-card px-3.5 py-3">
           <div className="text-lg font-semibold tabular-nums text-foreground">
-            {card.value}
+            {formatCost(microsToUsd(report.totalBillableCostMicros))}
           </div>
-          <div className="text-xs text-muted-foreground">{card.label}</div>
+          <div className="text-xs text-muted-foreground">Total Cost</div>
+          <CreditRunwayIndicator
+            totalBillableCostMicros={report.totalBillableCostMicros}
+            daysInRange={daysInRange}
+            className="mt-0.5 block"
+          />
         </div>
-      ))}
+        <div className="rounded-lg border border-border bg-card px-3.5 py-3">
+          <div className="text-lg font-semibold tabular-nums text-foreground">
+            {formatCompactNumber(totalLlmCalls)}
+          </div>
+          <div className="text-xs text-muted-foreground">LLM Calls</div>
+        </div>
+        <div className="rounded-lg border border-border bg-card px-3.5 py-3">
+          <div className="text-lg font-semibold tabular-nums text-foreground">
+            {formatCompactNumber(totalTokens)}
+          </div>
+          <div className="text-xs text-muted-foreground">Tokens</div>
+        </div>
+      </div>
+
+      {/* Secondary row */}
+      <div className="grid grid-cols-3 gap-3">
+        <div className="rounded-lg border border-border-muted bg-card/50 px-3.5 py-2.5">
+          <div className="text-sm font-semibold tabular-nums text-foreground">
+            {formatCompactNumber(report.totalExecutions)}
+          </div>
+          <div className="text-[0.65rem] text-muted-foreground">Executions</div>
+        </div>
+        <div className="rounded-lg border border-border-muted bg-card/50 px-3.5 py-2.5">
+          <div className="text-sm font-semibold tabular-nums text-foreground">
+            {formatCompactNumber(report.totalAgents)}
+          </div>
+          <div className="text-[0.65rem] text-muted-foreground">Agents</div>
+        </div>
+        <div className="rounded-lg border border-border-muted bg-card/50 px-3.5 py-2.5">
+          <div className="text-sm font-semibold tabular-nums text-foreground">
+            {formatCompactNumber(report.totalSessions)}
+          </div>
+          <div className="text-[0.65rem] text-muted-foreground">Sessions</div>
+        </div>
+      </div>
     </div>
   );
 }
@@ -207,7 +269,7 @@ function SummaryCards({ report }: { report: GetOrgUsageReportOutput }) {
 const CHART_HEIGHT_PX = 128;
 
 function DailyCostChart({ entries }: { entries: readonly DailyCostEntry[] }) {
-  const maxCost = Math.max(...entries.map((e) => e.estimatedCostUsd), 0);
+  const maxCost = Math.max(...entries.map((e) => microsToUsd(e.billableCostMicros)), 0);
   const [hoveredIdx, setHoveredIdx] = useState<number | null>(null);
 
   return (
@@ -222,9 +284,9 @@ function DailyCostChart({ entries }: { entries: readonly DailyCostEntry[] }) {
             <span className="text-xs tabular-nums text-muted-foreground">
               {formatChartDate(entries[hoveredIdx].date)}
               {" \u00B7 "}
-              {formatCost(entries[hoveredIdx].estimatedCostUsd)}
+              {formatCost(microsToUsd(entries[hoveredIdx].billableCostMicros))}
               {" \u00B7 "}
-              {formatTokenCount(entries[hoveredIdx].totalTokens)} tokens
+              {formatTokenCount(Number(entries[hoveredIdx].totalTokens))} tokens
             </span>
           )}
         </div>
@@ -238,7 +300,7 @@ function DailyCostChart({ entries }: { entries: readonly DailyCostEntry[] }) {
         >
           {entries.map((entry, i) => {
             const ratio =
-              maxCost > 0 ? entry.estimatedCostUsd / maxCost : 0;
+              maxCost > 0 ? microsToUsd(entry.billableCostMicros) / maxCost : 0;
             const heightPx = Math.max(ratio * CHART_HEIGHT_PX, 2);
 
             return (
@@ -326,9 +388,11 @@ function ModelBreakdownList({
           </span>
         </div>
         {models.map((m) => {
-          const totalInput =
-            m.inputTokens + m.cacheCreationTokens + m.cacheReadTokens;
-          const hasCache = m.cacheReadTokens > 0 || m.cacheCreationTokens > 0;
+          const inputTok = Number(m.inputTokens);
+          const cacheCreation = Number(m.cacheCreationInputTokens);
+          const cacheRead = Number(m.cacheReadInputTokens);
+          const totalInput = inputTok + cacheCreation + cacheRead;
+          const hasCache = cacheRead > 0 || cacheCreation > 0;
 
           return (
             <div
@@ -363,24 +427,24 @@ function ModelBreakdownList({
                   role="cell"
                   className="self-center text-right text-xs tabular-nums text-muted-foreground"
                 >
-                  {formatCompactNumber(m.outputTokens)}
+                  {formatCompactNumber(Number(m.outputTokens))}
                 </span>
                 <span
                   role="cell"
                   className="self-center text-right text-xs tabular-nums text-foreground"
                 >
-                  {formatCost(m.estimatedCostUsd)}
+                  {formatCost(microsToUsd(m.billableCostMicros))}
                 </span>
               </div>
               {hasCache && (
                 <div className="mt-0.5 text-[0.6rem] tabular-nums text-muted-foreground">
                   cache{" "}
-                  {m.cacheReadTokens > 0 &&
-                    `${formatCompactNumber(m.cacheReadTokens)} read`}
-                  {m.cacheReadTokens > 0 && m.cacheCreationTokens > 0 &&
+                  {cacheRead > 0 &&
+                    `${formatCompactNumber(cacheRead)} read`}
+                  {cacheRead > 0 && cacheCreation > 0 &&
                     " · "}
-                  {m.cacheCreationTokens > 0 &&
-                    `${formatCompactNumber(m.cacheCreationTokens)} write`}
+                  {cacheCreation > 0 &&
+                    `${formatCompactNumber(cacheCreation)} write`}
                 </div>
               )}
             </div>

package/src/usage/index.ts

@@ -4,6 +4,21 @@ export type { UseOrgUsageReportReturn } from "./useOrgUsageReport";
 export { OrgUsagePanel } from "./OrgUsagePanel";
 export type { OrgUsagePanelProps } from "./OrgUsagePanel";
 
+export { CreditRunwayIndicator } from "./CreditRunwayIndicator";
+export type { CreditRunwayIndicatorProps } from "./CreditRunwayIndicator";
+
+export { AgentBreakdownList } from "./AgentBreakdownList";
+export type { AgentBreakdownListProps } from "./AgentBreakdownList";
+
+export { HarnessSplitCard } from "./HarnessSplitCard";
+export type { HarnessSplitCardProps } from "./HarnessSplitCard";
+
+export { useExportCSV } from "./useExportCSV";
+export type { UseExportCSVReturn, ExportFormat } from "./useExportCSV";
+
+export { ExportButton } from "./ExportButton";
+export type { ExportButtonProps } from "./ExportButton";
+
 export {
   DATE_RANGE_PRESETS,
   dateRangeFromPreset,

package/src/usage/useExportCSV.ts

@@ -0,0 +1,115 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { GetOrgUsageReportOutput } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+
+/** Export format for the CSV download. */
+export type ExportFormat = "daily_summary" | "model_breakdown";
+
+/** Return value of {@link useExportCSV}. */
+export interface UseExportCSVReturn {
+  /** Trigger a CSV download for the given format. */
+  readonly exportCSV: (format: ExportFormat) => void;
+  /** Whether an export is being generated. */
+  readonly isExporting: boolean;
+}
+
+/**
+ * Behavior hook that generates and downloads usage data as CSV.
+ *
+ * Operates entirely client-side from data already in memory — no
+ * additional RPC calls. Supports two formats:
+ * - `daily_summary` — one row per day with date, executions, tokens, cost
+ * - `model_breakdown` — one row per model with calls, tokens, cost
+ *
+ * @param report - The org usage report data (from `useOrgUsageReport`).
+ * @param orgId - Organization ID for the filename.
+ */
+export function useExportCSV(
+  report: GetOrgUsageReportOutput | null,
+  orgId: string,
+): UseExportCSVReturn {
+  const [isExporting, setIsExporting] = useState(false);
+
+  const exportCSV = useCallback(
+    (format: ExportFormat) => {
+      if (!report) return;
+      setIsExporting(true);
+
+      try {
+        const { csv, filename } = format === "daily_summary"
+          ? buildDailySummaryCSV(report, orgId)
+          : buildModelBreakdownCSV(report, orgId);
+
+        downloadCSV(csv, filename);
+      } finally {
+        setIsExporting(false);
+      }
+    },
+    [report, orgId],
+  );
+
+  return { exportCSV, isExporting };
+}
+
+function buildDailySummaryCSV(
+  report: GetOrgUsageReportOutput,
+  orgId: string,
+): { csv: string; filename: string } {
+  const header = "Date,Executions,Tokens,Cost (USD)";
+  const rows = report.dailyCosts.map((entry) => {
+    const cost = (Number(entry.billableCostMicros) / 1_000_000).toFixed(6);
+    return `${entry.date},${entry.executionCount},${entry.totalTokens},${cost}`;
+  });
+
+  return {
+    csv: [header, ...rows].join("\n"),
+    filename: `${orgId}-daily-usage.csv`,
+  };
+}
+
+function buildModelBreakdownCSV(
+  report: GetOrgUsageReportOutput,
+  orgId: string,
+): { csv: string; filename: string } {
+  const header =
+    "Model,Provider,Calls,Input Tokens,Output Tokens,Cache Read Tokens,Cache Write Tokens,Cost (USD)";
+  const rows = report.modelBreakdown.map((m) => {
+    const cost = (Number(m.billableCostMicros) / 1_000_000).toFixed(6);
+    return [
+      escapeCsvField(m.model),
+      escapeCsvField(m.provider),
+      m.callCount,
+      m.inputTokens,
+      m.outputTokens,
+      m.cacheReadInputTokens,
+      m.cacheCreationInputTokens,
+      cost,
+    ].join(",");
+  });
+
+  return {
+    csv: [header, ...rows].join("\n"),
+    filename: `${orgId}-model-usage.csv`,
+  };
+}
+
+function escapeCsvField(value: string): string {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+function downloadCSV(csv: string, filename: string): void {
+  const blob = new Blob([csv], { type: "text/csv;charset=utf-8;" });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename;
+  link.style.display = "none";
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}

package/src/usage/useOrgUsageReport.ts

@@ -54,7 +54,8 @@ export interface UseOrgUsageReportReturn {
  * if (error) return <ErrorMessage error={error} />;
  * if (!report) return null;
  *
- * return <div>Total cost: {formatCost(report.totalCostUsd)}</div>;
+ * const costUsd = Number(report.totalBillableCostMicros) / 1_000_000;
+ * return <div>Total cost: {formatCost(costUsd)}</div>;
  * ```
  */
 export function useOrgUsageReport(

package/src/workspace/__tests__/useWorkspaceEntries-stability.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useWorkspaceEntries } from "../useWorkspaceEntries";
+
+describe("useWorkspaceEntries — return reference stability", () => {
+  it("returns the same object reference across re-renders when state is unchanged", () => {
+    const { result, rerender } = renderHook(() => useWorkspaceEntries());
+
+    const first = result.current;
+    rerender();
+    const second = result.current;
+
+    expect(second).toBe(first);
+  });
+
+  it("returns a new reference after adding an entry", () => {
+    const { result } = renderHook(() => useWorkspaceEntries());
+
+    const before = result.current;
+
+    act(() => {
+      result.current.addGitRepo("https://github.com/acme/repo.git", "main");
+    });
+
+    expect(result.current).not.toBe(before);
+    expect(result.current.entries).toHaveLength(1);
+    expect(result.current.hasEntries).toBe(true);
+  });
+
+  it("stabilizes after add — re-renders without state change preserve reference", () => {
+    const { result, rerender } = renderHook(() => useWorkspaceEntries());
+
+    act(() => {
+      result.current.addGitRepo("https://github.com/acme/repo.git");
+    });
+
+    const after = result.current;
+    rerender();
+
+    expect(result.current).toBe(after);
+  });
+
+  it("callback references are stable across re-renders", () => {
+    const { result, rerender } = renderHook(() => useWorkspaceEntries());
+
+    const { addGitRepo, addLocalPath, remove, clear, clearLocal, toInput } = result.current;
+
+    rerender();
+
+    expect(result.current.addGitRepo).toBe(addGitRepo);
+    expect(result.current.addLocalPath).toBe(addLocalPath);
+    expect(result.current.remove).toBe(remove);
+    expect(result.current.clear).toBe(clear);
+    expect(result.current.clearLocal).toBe(clearLocal);
+    expect(result.current.toInput).toBe(toInput);
+  });
+
+  it("returns a new reference after removing an entry", () => {
+    const { result } = renderHook(() => useWorkspaceEntries());
+
+    act(() => {
+      result.current.addLocalPath("/home/dev/project");
+    });
+
+    const withEntry = result.current;
+    const entryId = withEntry.entries[0].id;
+
+    act(() => {
+      result.current.remove(entryId);
+    });
+
+    expect(result.current).not.toBe(withEntry);
+    expect(result.current.entries).toHaveLength(0);
+    expect(result.current.hasEntries).toBe(false);
+  });
+});

package/src/workspace/useWorkspaceEntries.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import type { WorkspaceEntryInput, WorkspaceSourceInput } from "@stigmer/sdk";
 
 /**
@@ -156,14 +156,19 @@ export function useWorkspaceEntries(): UseWorkspaceEntriesReturn {
     });
   }, [entries]);
 
-  return {
-    entries,
-    addGitRepo,
-    addLocalPath,
-    remove,
-    clear,
-    clearLocal,
-    toInput,
-    hasEntries: entries.length > 0,
-  };
+  const hasEntries = entries.length > 0;
+
+  return useMemo(
+    () => ({
+      entries,
+      addGitRepo,
+      addLocalPath,
+      remove,
+      clear,
+      clearLocal,
+      toInput,
+      hasEntries,
+    }),
+    [entries, addGitRepo, addLocalPath, remove, clear, clearLocal, toInput, hasEntries],
+  );
 }