@talgent/workbench-ui 0.0.0-stage → 0.1.2

package/lib/token-analytics.ts

@@ -0,0 +1,168 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { useQuery } from "@tanstack/react-query";
+import { dashboardReportPeriod, previousReportPeriod, type DashboardReportPeriod } from "./dashboard-report";
+import { type DashboardWindow } from "./dashboard";
+import {
+  buildTraceMetricLeaderboards,
+  buildTraceMetricsDiagnostics,
+  type TraceMetricBucketLike,
+  type TraceDiagnostics,
+  type TraceMetricLeaderboards,
+  type TraceMetricsLike,
+  type TraceTokenTrendPoint,
+} from "./trace-view-model";
+import { addTokenMeasurement, addTokenUsage, emptyTokenUsage, tokenMetricKinds, tokenTotal, tokenUsageFromMeasurements, type TokenUsage } from "./token-usage";
+
+export type TokenAnalytics = {
+  window: DashboardWindow;
+  period: DashboardReportPeriod;
+  previous: TokenAnalytics["tokenValues"] | null;
+  comparisonUnavailable: string;
+  tokenValues: TokenUsage & {total: number};
+  metrics: TraceMetricsLike;
+  summary: TraceDiagnostics["summary"];
+  tokenTrend: TraceTokenTrendPoint[];
+  modelUsage: ModelUsageTrend;
+  leaderboards: TraceMetricLeaderboards;
+};
+
+/** Each window's usage per model: the window's five largest models by Total
+ * Tokens individually, the rest combined as Other. */
+export type ModelUsageTrend = {
+  models: string[];
+  buckets: Array<{label: string; usage: Record<string, TokenUsage>}>;
+};
+
+export const otherModels = "Other";
+const shownModelCount = 5;
+
+const refreshIntervalMs = 10000;
+
+/** Spend's analytics over whatever `read` measures, such as a Project's or a
+ * person's usage, with the previous period for comparison. `scope` names
+ * what is measured. */
+export function useTokenAnalytics(scope: readonly [string, string], read: (bounds: DashboardReportPeriod) => Promise<TraceMetricsLike>, window: DashboardWindow = "24h", period?: DashboardReportPeriod, enabled = true) {
+  return useQuery({
+    queryKey: [...scope, window, period?.end.getTime()],
+    queryFn: async (): Promise<TokenAnalytics> => {
+      const metricWindow = period ?? dashboardReportPeriod(window, new Date());
+      const [current, previous] = await Promise.allSettled([
+        read(metricWindow),
+        window === "30d" ? Promise.resolve(null) : read(previousReportPeriod(metricWindow)),
+      ]);
+      for (const result of [current, previous]) {
+        if (result.status === "rejected" && [Code.PermissionDenied, Code.Unauthenticated].includes(ConnectError.from(result.reason).code)) throw result.reason;
+      }
+      if (current.status === "rejected") throw current.reason;
+      return {
+        ...buildTokenAnalytics(current.value, window, metricWindow),
+        previous: previous.status === "fulfilled" && previous.value ? buildTokenAnalytics(previous.value, window, previousReportPeriod(metricWindow)).tokenValues : null,
+        comparisonUnavailable: window === "30d" ? "The previous 30D period is outside the 30-day metrics retention window." : previous.status === "rejected" ? `Previous metrics unavailable: ${previous.reason instanceof Error ? previous.reason.message : "query failed"}` : "",
+      };
+    },
+    enabled,
+    // A new period keeps showing the last report of the same scope and window until it answers.
+    placeholderData: (previous, previousQuery) => previousQuery?.queryKey[0] === scope[0] && previousQuery?.queryKey[1] === scope[1] && previousQuery?.queryKey[2] === window ? previous : undefined,
+    retry: false,
+    refetchInterval: refreshIntervalMs,
+    refetchIntervalInBackground: false,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function buildTokenAnalytics(traceMetrics: TraceMetricsLike, window: DashboardWindow, metricWindow = dashboardReportPeriod(window, new Date())): TokenAnalytics {
+  const diagnostics = buildTraceMetricsDiagnostics(traceMetrics);
+  const usage = tokenUsageFromMeasurements(traceMetrics.totals);
+  const trends = buildTokenTrends(traceMetrics.buckets, metricWindow);
+  return {
+    window,
+    period: metricWindow,
+    previous: null,
+    comparisonUnavailable: "Comparison not loaded",
+    tokenValues: {...usage, total: tokenTotal(usage)},
+    metrics: traceMetrics,
+    summary: diagnostics.summary,
+    tokenTrend: trends.tokenTrend,
+    modelUsage: trends.modelUsage,
+    leaderboards: buildTraceMetricLeaderboards(traceMetrics, 5),
+  };
+}
+
+function buildTokenTrends(metrics: TraceMetricBucketLike[], metricWindow: DashboardReportPeriod): Pick<TokenAnalytics, "tokenTrend" | "modelUsage"> {
+  const stepMillis = metricWindow.stepSeconds * 1000;
+  const startMillis = metricWindow.start.getTime();
+  const endMillis = metricWindow.end.getTime();
+  const buckets = Array.from({ length: metricWindow.bucketCount }, (_, index) => ({
+    label: formatTrendWindow(startMillis + index * stepMillis, startMillis + (index + 1) * stepMillis),
+    usage: emptyTokenUsage(),
+    models: new Map<string, TokenUsage>(),
+  }));
+
+  for (const metric of metrics) {
+    if (!metric.bucketStart) continue;
+    const bucketMillis = timestampDate(metric.bucketStart).getTime();
+    if (bucketMillis >= endMillis || bucketMillis + metric.bucketSeconds * 1000 <= startMillis) continue;
+    const bucket = buckets[Math.min(Math.max(Math.floor((bucketMillis - startMillis) / stepMillis), 0), buckets.length - 1)];
+    const value = Number.isFinite(metric.value) ? metric.value : 0;
+    addTokenMeasurement(bucket.usage, metric.metricKind, value);
+    // Token measurements of a model call carry the model as their dimension.
+    const model = metric.dimension.trim();
+    if (!model || !tokenMetricKinds.includes(metric.metricKind)) continue;
+    const usage = bucket.models.get(model) ?? emptyTokenUsage();
+    addTokenMeasurement(usage, metric.metricKind, value);
+    bucket.models.set(model, usage);
+  }
+
+  const windowTotals = new Map<string, number>();
+  for (const bucket of buckets) for (const [model, usage] of bucket.models) windowTotals.set(model, (windowTotals.get(model) ?? 0) + tokenTotal(usage));
+  const ranked = [...windowTotals].filter(([, total]) => total > 0).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).map(([model]) => model);
+  const shown = ranked.slice(0, shownModelCount);
+  const models = ranked.length > shown.length ? [...shown, otherModels] : shown;
+
+  return {
+    tokenTrend: buckets.map(bucket => ({ label: bucket.label, ...bucket.usage, totalTokens: tokenTotal(bucket.usage) })),
+    modelUsage: {
+      models,
+      buckets: buckets.map(bucket => {
+        const usage: Record<string, TokenUsage> = {};
+        for (const [model, value] of bucket.models) {
+          const key = shown.includes(model) ? model : otherModels;
+          usage[key] = addTokenUsage(usage[key] ?? emptyTokenUsage(), value);
+        }
+        return { label: bucket.label, usage };
+      }),
+    },
+  };
+}
+
+function formatTrendWindow(startEpochMillis: number, endEpochMillis: number): string {
+  const start = new Date(startEpochMillis);
+  const end = new Date(endEpochMillis);
+  if (sameUtcDay(start, end)) {
+    return `${formatUtcClock(start)}-${formatUtcClock(end)}`;
+  }
+  return `${formatUtcDateTime(start)}-${formatUtcDateTime(end)}`;
+}
+
+function sameUtcDay(left: Date, right: Date): boolean {
+  return left.getUTCFullYear() === right.getUTCFullYear()
+    && left.getUTCMonth() === right.getUTCMonth()
+    && left.getUTCDate() === right.getUTCDate();
+}
+
+function formatUtcClock(value: Date): string {
+  return [
+    value.getUTCHours(),
+    value.getUTCMinutes(),
+    value.getUTCSeconds(),
+  ].map(padTimePart).join(":");
+}
+
+function formatUtcDateTime(value: Date): string {
+  return `${padTimePart(value.getUTCMonth() + 1)}-${padTimePart(value.getUTCDate())} ${formatUtcClock(value)}`;
+}
+
+function padTimePart(value: number): string {
+  return String(value).padStart(2, "0");
+}

package/lib/token-usage.ts

@@ -0,0 +1,64 @@
+/** Token usage in its four categories; Total Tokens is their sum. */
+export interface TokenUsage {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  output: number;
+}
+
+export const tokenCategories = [
+  { key: "input", label: "Input", metricKind: "input_tokens" },
+  { key: "cacheRead", label: "Cache read", metricKind: "cache_read_tokens" },
+  { key: "cacheWrite", label: "Cache write", metricKind: "cache_creation_tokens" },
+  { key: "output", label: "Output", metricKind: "output_tokens" },
+] as const satisfies readonly { key: keyof TokenUsage; label: string; metricKind: string }[];
+
+export const tokenMetricKinds: readonly string[] = tokenCategories.map(category => category.metricKind);
+
+export const emptyTokenUsage = (): TokenUsage => ({ input: 0, cacheRead: 0, cacheWrite: 0, output: 0 });
+
+export function tokenTotal(usage: TokenUsage): number {
+  return usage.input + usage.cacheRead + usage.cacheWrite + usage.output;
+}
+
+/** Adds one measurement to usage; other metric kinds are ignored. */
+export function addTokenMeasurement(usage: TokenUsage, metricKind: string, value: number): void {
+  const category = tokenCategories.find(item => item.metricKind === metricKind);
+  if (category && Number.isFinite(value)) usage[category.key] += value;
+}
+
+export function addTokenUsage(target: TokenUsage, usage: TokenUsage): TokenUsage {
+  for (const { key } of tokenCategories) target[key] += usage[key];
+  return target;
+}
+
+export function tokenUsageFromMeasurements(measurements: readonly { metricKind: string; value: number }[]): TokenUsage {
+  const usage = emptyTokenUsage();
+  for (const item of measurements) addTokenMeasurement(usage, item.metricKind, item.value);
+  return usage;
+}
+
+/** A model call's usage as its span reports it. A call without usage, such as
+ * a rejected request, counts as zero. */
+export function tokenUsageFromAttributes(attributes: Record<string, string>): TokenUsage {
+  const usage = emptyTokenUsage();
+  for (const { key, metricKind } of tokenCategories) {
+    const value = Number(attributes[metricKind]);
+    if (attributes[metricKind]?.trim() && Number.isFinite(value) && value >= 0) usage[key] = value;
+  }
+  return usage;
+}
+
+/**
+ * Cache Hit Rate = Cache read ÷ (Input + Cache read + Cache write). Callers sum
+ * usage before asking, so an aggregate rate follows volume; null when there is
+ * no input usage at all.
+ */
+export function cacheHitRate(usage: TokenUsage): number | null {
+  const denominator = usage.input + usage.cacheRead + usage.cacheWrite;
+  return denominator > 0 ? usage.cacheRead / denominator : null;
+}
+
+export function formatHitRate(rate: number): string {
+  return `${(rate * 100).toFixed(1)}%`;
+}

package/lib/trace-view-model.ts

@@ -0,0 +1,292 @@
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { tokenMetricKinds, tokenTotal, tokenUsageFromMeasurements, type TokenUsage } from "./token-usage";
+
+export const traceMetricKinds = ["tool_call", "mcp_call", "skill_call", "agent_call", "skill_activation", "model_call", "input_tokens", "output_tokens", "cache_read_tokens", "cache_creation_tokens"] as const;
+
+export interface TraceDiagnostics {
+  summary: TraceSummary;
+}
+
+export interface TraceSummary {
+  tokenUsage: TokenUsage;
+  totalTokens: number;
+  observationGaps: string[];
+  incompleteMetricKinds: string[];
+  modelCallCount: number;
+  toolCallCount: number;
+  skillCallCount: number;
+  agentCallCount: number;
+  mcpCallCount: number;
+  skillActivationCount: number;
+  toolDistribution: TraceMetricBar[];
+  skillDistribution: TraceMetricBar[];
+  agentDistribution: TraceMetricBar[];
+  mcpDistribution: TraceMetricBar[];
+  modelDistribution: TraceMetricBar[];
+}
+
+export interface TraceMetricBar {
+  label: string;
+  value: number;
+  displayValue: string;
+  percent: number;
+}
+
+export interface TraceTokenTrendPoint extends TokenUsage {
+  label: string;
+  totalTokens: number;
+}
+
+export interface TraceMetricBucketLike {
+  bucketStart?: Timestamp;
+  bucketSeconds: number;
+  ownerContext?: string;
+  ownerId?: string;
+  runtimePurpose?: string;
+  userId?: string;
+  agentWorkId?: string;
+  projectId?: string;
+  metricKind: string;
+  dimension: string;
+  value: number;
+  unknownCount?: bigint;
+  gaps?: string[];
+}
+
+export interface TraceMetricTotalLike {
+  metricKind: string;
+  dimension: string;
+  value: number;
+  unknownCount?: bigint;
+  gaps?: string[];
+}
+
+export interface TraceMetricsLike {
+  buckets: TraceMetricBucketLike[];
+  totals: TraceMetricTotalLike[];
+}
+
+export interface TraceTokenLeaderboardRow {
+  key: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  percent: number;
+}
+
+export interface TraceOwnerRuntimeLeaderboardRow extends TraceTokenLeaderboardRow {
+  ownerContext: string;
+  runtimePurpose: string;
+}
+
+export interface TraceMetricLeaderboards {
+  ownerRuntimes: TraceOwnerRuntimeLeaderboardRow[];
+  users: TraceTokenLeaderboardRow[];
+}
+
+
+export function buildTraceMetricsDiagnostics(metrics: TraceMetricsLike): TraceDiagnostics {
+  const tokenUsage = tokenUsageFromMeasurements(metrics.totals);
+  const modelCallCount = metricKindTotal(metrics.totals, "model_call");
+  const toolCallCount = metricKindTotal(metrics.totals, "tool_call");
+  const skillCallCount = metricKindTotal(metrics.totals, "skill_call");
+  const agentCallCount = metricKindTotal(metrics.totals, "agent_call");
+  const mcpCallCount = metricKindTotal(metrics.totals, "mcp_call");
+  const skillActivationCount = metricKindTotal(metrics.totals, "skill_activation");
+  const observationGaps = [...new Set(metrics.buckets.flatMap((bucket) => bucket.gaps ?? []))];
+  // Token usage is always the recorded amount, so only call kinds can be incomplete.
+  const incompleteMetricKinds = new Set(metrics.totals.filter((metric) => (metric.unknownCount ?? 0n) > 0n && !tokenKinds.includes(metric.metricKind)).map((metric) => metric.metricKind));
+  if (observationGaps.includes("projection_incomplete")) traceMetricKinds.filter((kind) => !tokenKinds.includes(kind)).forEach((kind) => incompleteMetricKinds.add(kind));
+  if (observationGaps.some((gap) => gap === "missing_call_id" || gap === "unclassified_call")) {
+    ["tool_call", "mcp_call", "skill_call", "agent_call"].forEach((kind) => incompleteMetricKinds.add(kind));
+  }
+  if (observationGaps.includes("missing_event_identity")) incompleteMetricKinds.add("skill_activation");
+
+  return {
+    summary: {
+      tokenUsage,
+      totalTokens: tokenTotal(tokenUsage),
+      observationGaps,
+      incompleteMetricKinds: [...incompleteMetricKinds],
+      modelCallCount,
+      toolCallCount,
+      skillCallCount, agentCallCount, mcpCallCount, skillActivationCount,
+      toolDistribution: metricDistribution(metrics.totals, "tool_call"),
+      skillDistribution: metricDistribution(metrics.totals, "skill_call"),
+      agentDistribution: metricDistribution(metrics.totals, "agent_call"),
+      mcpDistribution: metricDistribution(metrics.totals, "mcp_call"),
+      modelDistribution: metricDistribution(metrics.totals, "model_call"),
+    },
+  };
+}
+
+export function buildTraceMetricLeaderboards(metrics: TraceMetricsLike, limit = 5): TraceMetricLeaderboards {
+  return {
+    ownerRuntimes: ownerRuntimeLeaderboard(metrics.buckets, limit),
+    users: tokenLeaderboard(metrics.buckets, "user", limit),
+  };
+}
+
+const tokenKinds = tokenMetricKinds;
+
+/**
+ * What token usage is grouped by: a person, a Work, or the owner its Works
+ * name through the caller attributes ownerContext and ownerId, as the caller
+ * that started them names it.
+ */
+export type TokenAttribution = "user" | "work" | { ownerContext: string };
+
+function attributionKey(metric: TraceMetricBucketLike, by: TokenAttribution): string {
+  if (by === "user") return metric.userId?.trim() ?? "";
+  if (by === "work") return metric.agentWorkId?.trim() ?? "";
+  return metric.ownerContext === by.ownerContext ? metric.ownerId?.trim() ?? "" : "";
+}
+
+/** Total Tokens per person, Work or owner, for every one with usage (no ranking cut-off). */
+export function tokenTotals(metrics: TraceMetricBucketLike[], by: TokenAttribution): Map<string, number> {
+  return new Map(tokenLeaderboard(metrics, by, Number.POSITIVE_INFINITY).map(row => [row.key, row.totalTokens]));
+}
+
+export function formatTraceDuration(durationNanos: bigint): string {
+  const millis = durationMillis(durationNanos);
+
+  if (millis < 1000) {
+    return `${formatCompactNumber(millis, Number.isInteger(millis) ? 0 : 1)}ms`;
+  }
+
+  const seconds = millis / 1000;
+  if (seconds < 60) {
+    return `${formatCompactNumber(seconds, 1)}s`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = Math.round(seconds % 60);
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+function durationMillis(durationNanos: bigint): number {
+  return Number(durationNanos) / 1_000_000;
+}
+
+function formatCompactNumber(value: number, fractionDigits: number): string {
+  return value.toFixed(fractionDigits).replace(/\.0$/, "");
+}
+
+export function formatCompactTokenCount(value: number): string {
+  if (value < 1000) {
+    return `${Math.round(value)}`;
+  }
+  if (value < 1_000_000) {
+    return `${formatCompactNumber(value / 1000, 1)}k`;
+  }
+  if (value < 1_000_000_000) {
+    return `${formatCompactNumber(value / 1_000_000, 1)}M`;
+  }
+  return `${formatCompactNumber(value / 1_000_000_000, 1)}B`;
+}
+
+function metricKindTotal(metrics: TraceMetricTotalLike[], kind: string): number {
+  return metrics
+    .filter((metric) => metric.metricKind === kind)
+    .reduce((sum, metric) => sum + safeMetricValue(metric.value), 0);
+}
+
+function metricDistribution(metrics: TraceMetricTotalLike[], kind: string): TraceMetricBar[] {
+  const rows = metrics
+    .filter((metric) => metric.metricKind === kind && metric.dimension.trim() !== "" && safeMetricValue(metric.value) > 0)
+    .map((metric) => ({ label: metric.dimension, value: safeMetricValue(metric.value) }));
+  const total = rows.reduce((sum, row) => sum + row.value, 0);
+
+  return rows
+    .sort((left, right) => right.value - left.value || left.label.localeCompare(right.label))
+    .map((row) => ({
+      label: row.label,
+      value: row.value,
+      displayValue: formatMetricValue(row.value),
+      percent: total > 0 ? (row.value / total) * 100 : 0,
+    }));
+}
+
+function safeMetricValue(value: number): number {
+  return Number.isFinite(value) ? value : 0;
+}
+
+function formatMetricValue(value: number): string {
+  return Number.isInteger(value) ? String(value) : formatCompactNumber(value, 1);
+}
+
+/** The limit people, Works or owners with the most Tokens, largest first. */
+export function tokenLeaderboard(metrics: TraceMetricBucketLike[], by: TokenAttribution, limit = 5): TraceTokenLeaderboardRow[] {
+  const totals = new Map<string, { inputTokens: number; outputTokens: number; cacheTokens: number }>();
+  for (const metric of metrics) {
+    const key = attributionKey(metric, by);
+    if (!key) continue;
+    const value = safeMetricValue(metric.value);
+    if (!tokenKinds.includes(metric.metricKind)) continue;
+
+    const current = totals.get(key) ?? { inputTokens: 0, outputTokens: 0, cacheTokens: 0 };
+    if (metric.metricKind === "input_tokens") current.inputTokens += value;
+    if (metric.metricKind === "output_tokens") current.outputTokens += value;
+    if (metric.metricKind === "cache_read_tokens" || metric.metricKind === "cache_creation_tokens") current.cacheTokens += value;
+    totals.set(key, current);
+  }
+
+  const rows = Array.from(totals.entries())
+    .map(([key, value]) => ({
+      key,
+      inputTokens: value.inputTokens,
+      outputTokens: value.outputTokens,
+      totalTokens: value.inputTokens + value.outputTokens + value.cacheTokens,
+      percent: 0,
+    }))
+    .filter((row) => row.totalTokens > 0)
+    .sort((left, right) => right.totalTokens - left.totalTokens || left.key.localeCompare(right.key))
+    .slice(0, Math.max(limit, 0));
+  const maxTotal = Math.max(0, ...rows.map((row) => row.totalTokens));
+  return rows.map((row) => ({
+    ...row,
+    percent: maxTotal > 0 ? Math.max((row.totalTokens / maxTotal) * 100, 4) : 0,
+  }));
+}
+
+function ownerRuntimeLeaderboard(metrics: TraceMetricBucketLike[], limit: number): TraceOwnerRuntimeLeaderboardRow[] {
+  const totals = new Map<string, { ownerContext: string; runtimePurpose: string; inputTokens: number; outputTokens: number; cacheTokens: number }>();
+  for (const metric of metrics) {
+    const ownerContext = metric.ownerContext?.trim() ?? "";
+    const runtimePurpose = metric.runtimePurpose?.trim() ?? "";
+    if (!ownerContext && !runtimePurpose) continue;
+    if (!tokenKinds.includes(metric.metricKind)) continue;
+
+    const key = `${ownerContext || "unknown"}:${runtimePurpose || "unknown"}`;
+    const current = totals.get(key) ?? {
+      ownerContext,
+      runtimePurpose,
+      inputTokens: 0,
+      outputTokens: 0, cacheTokens: 0,
+    };
+    const value = safeMetricValue(metric.value);
+    if (metric.metricKind === "input_tokens") current.inputTokens += value;
+    if (metric.metricKind === "output_tokens") current.outputTokens += value;
+    if (metric.metricKind === "cache_read_tokens" || metric.metricKind === "cache_creation_tokens") current.cacheTokens += value;
+    totals.set(key, current);
+  }
+
+  const rows = Array.from(totals.entries())
+    .map(([key, value]) => ({
+      key,
+      ownerContext: value.ownerContext,
+      runtimePurpose: value.runtimePurpose,
+      inputTokens: value.inputTokens,
+      outputTokens: value.outputTokens,
+      totalTokens: value.inputTokens + value.outputTokens + value.cacheTokens,
+      percent: 0,
+    }))
+    .filter((row) => row.totalTokens > 0)
+    .sort((left, right) => right.totalTokens - left.totalTokens || left.key.localeCompare(right.key))
+    .slice(0, Math.max(limit, 0));
+  const maxTotal = Math.max(0, ...rows.map((row) => row.totalTokens));
+  return rows.map((row) => ({
+    ...row,
+    percent: maxTotal > 0 ? Math.max((row.totalTokens / maxTotal) * 100, 4) : 0,
+  }));
+}

package/lib/transport.ts

@@ -0,0 +1,29 @@
+import { Code, ConnectError, type Interceptor } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-web";
+import { refreshSession } from "./session";
+
+// An Identity Token lives fifteen minutes. When the gateway rejects one, ask
+// Account for a fresh token once and repeat the call. If Account rejects the
+// session, the error reaches AuthGate, which sends the person to sign in; if
+// Account cannot be reached, the call fails as unavailable so the page offers
+// a retry instead. A stream cannot replay its request, so it only refreshes
+// for its reconnect.
+export const refreshOnUnauthenticated: Interceptor = (next) => async (request) => {
+  try {
+    return await next(request);
+  } catch (error) {
+    if (!(error instanceof ConnectError) || error.code !== Code.Unauthenticated) throw error;
+    const outcome = await refreshSession();
+    if (outcome === "unavailable") throw new ConnectError("session refresh unavailable", Code.Unavailable, undefined, undefined, error);
+    if (outcome === "rejected" || request.stream) throw error;
+    return next(request);
+  }
+};
+
+export const transport = createConnectTransport({
+  baseUrl: "/api",
+  interceptors: [refreshOnUnauthenticated],
+});
+
+export const streamTransport = transport;
+export const traceTransport = transport;

package/lib/use-now.ts

@@ -0,0 +1,11 @@
+import { useEffect, useState } from "react";
+
+// The current time, refreshed on an interval, so rendering stays pure.
+export function useNow(intervalMs = 60_000) {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const timer = setInterval(() => setNow(Date.now()), intervalMs);
+    return () => clearInterval(timer);
+  }, [intervalMs]);
+  return now;
+}