@opengeni/react 3.3.2 → 3.4.0

package/src/timeline-model.ts

@@ -0,0 +1,143 @@
+// @opengeni/react/timeline-model: the pure presentation model behind the web timeline,
+// shared with non-DOM renderers (React Native). No DOM, no CSS, no styled components:
+// renderers that consume it make the same decisions the web MessageTimeline makes.
+export {
+  BUILT_IN_TURN_SUMMARY_FACET_IDS,
+  BUILT_IN_TURN_SUMMARY_FACETS,
+  createTurnSummaryContext,
+  formatDurationFacet,
+  formatElapsed,
+  resolveTurnSummaryFacets,
+} from "./timeline/turn-summary-model";
+export type {
+  BuiltInTurnSummaryFacetId,
+  TurnSummaryContext,
+  TurnSummaryFacet,
+  TurnSummaryFacetConfiguration,
+  TurnSummaryFacetResult,
+  TurnSummaryOptions,
+  TurnSummaryStatus,
+} from "./timeline/turn-summary-model";
+export {
+  clusterIsSettled,
+  compactedLandmarkCount,
+  durationBetween,
+  flattenActivityItems,
+  isPreparingWork,
+  readableWorkDefaultOpen,
+  readableWorkShowsPreview,
+  readableWorkStatus,
+  rollingActivityItem,
+} from "./timeline/work-presentation";
+export type { ActivityGroup, ReadableWorkOptions, TurnGroup } from "./timeline/work-presentation";
+export { timelineGroupContainsPresentedImage } from "./timeline/presented-image";
+export { mcpToolLeaf, toolDisplayName } from "./timeline/tool-display-name";
+export { rawTypeOf } from "./timeline/registry";
+export {
+  applyPatchOpsFromToolItem,
+  isApplyPatch,
+  parseToolArgs,
+  sandboxCommandExitCode,
+  stripExecBanner,
+  tailPeek,
+  unwrapMcpOutput,
+} from "./timeline/parsers";
+export { formatClockTime } from "./lib/format";
+export {
+  applyPatchPresentation,
+  askPresentation,
+  execPresentation,
+  genericToolIconKind,
+  genericToolPresentation,
+  pathBasename,
+  pathDirname,
+  presentedToolKind,
+  runOnPresentation,
+  toolRowPresentation,
+  truncatePreview,
+  webSearchPresentation,
+  withComputePreview,
+  writeStdinPresentation,
+} from "./timeline/tool-presentation";
+export type {
+  PresentedToolKind,
+  ToolBody,
+  ToolChip,
+  ToolIconKind,
+  ToolIconTone,
+  ToolPatchFile,
+  ToolPresentationContext,
+  ToolPreview,
+  ToolRowPresentation,
+  WebSearchResult,
+} from "./timeline/tool-presentation";
+
+export {
+  namedAgentTitle,
+  sandboxRowTitle,
+  startupDuration,
+  startupPhaseTitle,
+  STARTUP_WAIT_TITLES,
+  workerRowTitle,
+  workerRowTitleParts,
+  type AgentTitleParts,
+} from "./timeline/platform-activity-presentation";
+export { formatBytes, stringifyPayload, tryParseJson } from "./lib/format";
+export { selectTurnSummaryFacets } from "./timeline/turn-summary-model";
+export { GENIE_PREPARING_PHRASES, GENIE_WAITING_PHRASES } from "./timeline/genie-copy";
+export {
+  answersFromDrafts,
+  defaultHumanInputFormMessages,
+  emptyDraft,
+  formatDeadline,
+  humanInputHeading,
+  initialDrafts,
+  resolveSecretSaveTo,
+  SECRET_SAVE_TO_ORDER,
+  secretAnswerFromReading,
+  secretAnswerLabel,
+  secretAutocomplete,
+  secretCanGenerate,
+  secretConcealed,
+  secretFieldLabel,
+  secretInputMode,
+  secretPatternMismatch,
+  secretVaultForTarget,
+} from "./human-input-model";
+export type {
+  HumanInputAnswerDraft,
+  HumanInputFormMessages,
+  SecretAutocomplete,
+  SecretFieldReading,
+  SecretSaveToChoice,
+} from "./human-input-model";
+export { secretReferenceLabel, secretReferenceLabelText } from "./secret-reference-label";
+export type { SecretReferenceLabel } from "./secret-reference-label";
+export { isActionableHumanInputRequest } from "./human-input";
+export {
+  SESSION_STATUS_BADGE,
+  SESSION_STATUS_PRESENTATION,
+  sessionAdmissionBlocked,
+  sessionDisplayStatus,
+} from "./session-status-model";
+export type { SessionDisplayStatus, SessionStatusTone } from "./session-status-model";
+export { formatRelativeTime } from "./lib/format";
+export {
+  noticeDisplayText,
+  noticeIsResolvedApproval,
+  noticeTone,
+  recordedWaitSummaryText,
+} from "./timeline/notice-presentation";
+export {
+  QUESTION_NAV_HIDDEN_PX,
+  QUESTION_NAV_MARGIN_PX,
+  questionNavTarget,
+} from "./timeline/question-nav-model";
+export type { QuestionNavPrompt } from "./timeline/question-nav-model";
+export { timelineGroupIndexAtSequence, timelineGroupSequences } from "./timeline/focus-sequence";
+export {
+  notificationPlainText,
+  parseNotificationInline,
+  parseNotificationText,
+} from "./notification-text";
+export type { NotificationBlock, NotificationSpan } from "./notification-text";

package/src/usage/allowance-copy.ts

@@ -0,0 +1,64 @@
+// Shared, replaceable words for usage allowances. The timeline refusal row
+// (session graph) and the opt-in `@opengeni/react/usage` surfaces both read
+// these, so a host that renames "workspace" or "admin" does it once.
+//
+// Product rule: never show raw credit amounts here. Hosts that want money or
+// plan multiples opt in with `formatAmount` on the meter components.
+
+/** Which ceiling ran out: the shared workspace pool, or one member's share of it. */
+export type AllowanceScope = "workspace" | "member";
+
+export type AllowanceLabels = {
+  /** "Usage limit reached" for a member ceiling. */
+  memberLimitReachedTitle: string;
+  /** "Workspace usage limit reached" for the shared pool. */
+  workspaceLimitReachedTitle: string;
+  /** Who can fix a member ceiling. */
+  memberRemedy: string;
+  /** Who can fix the workspace pool. */
+  workspaceRemedy: string;
+  /** "Resets Nov 1". `date` is already formatted by `formatDate`. */
+  resets: (date: string) => string;
+  /** Shown when a ceiling has no automatic reset. */
+  noReset: string;
+  /** Formats a reset instant for `resets`. Defaults to a short local date. */
+  formatDate: (iso: string) => string;
+};
+
+export function formatAllowanceDate(iso: string, now: Date = new Date()): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return new Intl.DateTimeFormat(undefined, {
+    month: "short",
+    day: "numeric",
+    ...(date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }),
+  }).format(date);
+}
+
+/** Full local date and time, for a title/tooltip next to the short date. */
+export function formatAllowanceInstant(iso: string): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "short" }).format(
+    date,
+  );
+}
+
+export const DEFAULT_ALLOWANCE_LABELS: AllowanceLabels = {
+  memberLimitReachedTitle: "Usage limit reached",
+  workspaceLimitReachedTitle: "Workspace usage limit reached",
+  memberRemedy: "A workspace admin can raise this limit.",
+  workspaceRemedy: "An organization admin can raise the workspace budget.",
+  resets: (date) => `Resets ${date}.`,
+  noReset: "It doesn't reset automatically.",
+  formatDate: (iso) => formatAllowanceDate(iso),
+};
+
+export function allowanceLabels(overrides?: Partial<AllowanceLabels>): AllowanceLabels {
+  return overrides ? { ...DEFAULT_ALLOWANCE_LABELS, ...overrides } : DEFAULT_ALLOWANCE_LABELS;
+}
+
+/** "Resets Nov 1." or the no-reset sentence. */
+export function allowanceResetSentence(labels: AllowanceLabels, resetsAt: string | null): string {
+  return resetsAt === null ? labels.noReset : labels.resets(labels.formatDate(resetsAt));
+}

package/src/usage/session-usage-limit.ts

@@ -0,0 +1,266 @@
+// Per-task usage limits as a person reads them. Pure and React-free, so the
+// timeline projection, the web console and native clients share one wording.
+//
+// Amounts are API-equivalent model usage (provider list-price estimate) in USD
+// micros, not a bill. Unknown usage is never shown as $0: a task whose usage
+// is still being prepared or can't be read says so in words instead.
+import {
+  formatSessionUsageMicros,
+  type ParsedSessionUsageLimitReachedRefusal,
+  type SessionUsageLimit,
+} from "@opengeni/sdk/session-usage-limits";
+
+/** Share of the limit at which a quiet, dismissible near-limit notice appears. */
+export const SESSION_USAGE_LIMIT_NEAR_FRACTION = 0.8;
+
+export type SessionUsageLimitLabels = {
+  /** The setting's name: "Usage limit". */
+  title: string;
+  /** The one explanation, shown once next to the setting. */
+  explanation: string;
+  /** Short help: what the amount is not. */
+  notYourBill: string;
+  noLimit: string;
+  /** "Pause at $50.00". */
+  pauseAt: (limit: string) => string;
+  /** "$12.34 of $50.00". */
+  usedOfLimit: (used: string, limit: string) => string;
+  /** "At least $12.34 of $50.00" when some usage has no known price. */
+  atLeastOfLimit: (used: string, limit: string) => string;
+  /** "$12.34 used" without a limit. */
+  used: (used: string) => string;
+  /** "At least $12.34 used". */
+  atLeastUsed: (used: string) => string;
+  preparing: string;
+  unavailable: string;
+  /** Notes under the amount when the total is incomplete. */
+  unpricedNote: string;
+  legacyNote: string;
+  preparingNote: string;
+  unavailableNote: string;
+  /** A refresh failed after a good read: the last known amount is shown. */
+  staleNote: string;
+  reachedTitle: string;
+  /** "$52.10 of $50.00 API-equivalent model usage." */
+  reachedAmount: (amount: string) => string;
+  reachedRemedy: string;
+  /** Added when the goal paused at the limit: raising it never resumes by itself. */
+  reachedGoalRemedy: string;
+  /** Added to a read-only (child or no permission) reached notice. */
+  reachedReadOnlyRemedy: string;
+  /** "This task has used 84% of its usage limit ($42.00 of $50.00)." */
+  near: (percent: string, amount: string) => string;
+  changeLimit: string;
+  openMainTask: string;
+  dismiss: string;
+};
+
+export const DEFAULT_SESSION_USAGE_LIMIT_LABELS: SessionUsageLimitLabels = {
+  title: "Usage limit",
+  explanation:
+    "API-equivalent model usage for this chat and its agents. In-progress requests may take usage above the limit.",
+  notYourBill:
+    "Estimated from model list prices, whoever pays for the model. It's not your bill and doesn't change your credits.",
+  noLimit: "No limit",
+  pauseAt: (limit) => `Pause at ${limit}`,
+  usedOfLimit: (used, limit) => `${used} of ${limit}`,
+  atLeastOfLimit: (used, limit) => `At least ${used} of ${limit}`,
+  used: (used) => `${used} used`,
+  atLeastUsed: (used) => `At least ${used} used`,
+  preparing: "Preparing usage",
+  unavailable: "Usage unavailable",
+  unpricedNote: "Some model usage has no known price, so it isn't counted.",
+  legacyNote: "This chat started before usage limits, so some earlier usage may be missing.",
+  preparingNote: "Earlier usage is still being counted. You can set a limit when it's ready.",
+  unavailableNote: "Couldn't read this chat's usage right now. A set limit still applies.",
+  staleNote: "Couldn't refresh, so this may be out of date. The limit still applies.",
+  reachedTitle: "Usage limit reached",
+  reachedAmount: (amount) => `${amount} API-equivalent model usage.`,
+  reachedRemedy: "Raise or remove the limit to continue.",
+  reachedGoalRemedy: "Raise or remove the limit, then resume the goal.",
+  reachedReadOnlyRemedy: "Someone who can run the main task can raise or remove its limit.",
+  near: (percent, amount) => `This task has used ${percent}% of its usage limit (${amount}).`,
+  changeLimit: "Change limit",
+  openMainTask: "Open main task",
+  dismiss: "Dismiss",
+};
+
+export function sessionUsageLimitLabels(
+  overrides?: Partial<SessionUsageLimitLabels>,
+): SessionUsageLimitLabels {
+  return { ...DEFAULT_SESSION_USAGE_LIMIT_LABELS, ...overrides };
+}
+
+export type SessionUsageLimitState =
+  | "unknown"
+  | "unlimited"
+  | "within"
+  | "near"
+  | "reached"
+  | "preparing"
+  | "unavailable";
+
+export type SessionUsageLimitSummary = {
+  state: SessionUsageLimitState;
+  /** Configured limit, null for none or while unreadable. */
+  limitMicros: number | null;
+  /** Recorded known usage; null whenever it is not known (never $0 then). */
+  usedMicros: number | null;
+  /** Some usage is missing from the total: show "at least". */
+  partial: boolean;
+  /** Used share of the limit, clamped to 0..1 for a bar; null without both amounts. */
+  barFraction: number | null;
+  /** Unclamped share; may exceed 1 when in-progress requests overshot. */
+  fraction: number | null;
+  /** "$12.34 of $50.00", "At least $12.34 used", "Preparing usage", ... */
+  amountText: string | null;
+  /** Plain sentences explaining an incomplete or unreadable total. */
+  notes: string[];
+  inherited: boolean;
+  rootSessionId: string | null;
+  version: number | null;
+  /** The last refresh failed: amounts are the last known ones, maybe out of date. */
+  stale: boolean;
+};
+
+const UNKNOWN: SessionUsageLimitSummary = {
+  state: "unknown",
+  limitMicros: null,
+  usedMicros: null,
+  partial: false,
+  barFraction: null,
+  fraction: null,
+  amountText: null,
+  notes: [],
+  inherited: false,
+  rootSessionId: null,
+  version: null,
+  stale: false,
+};
+
+/**
+ * Fold the server's usage-limit projection into what to show. `null` or
+ * `undefined` (an older server, or not loaded yet) is `unknown`: render
+ * nothing rather than "No limit" or "$0".
+ */
+export function summarizeSessionUsageLimit(
+  usage: SessionUsageLimit | null | undefined,
+  overrides?: Partial<SessionUsageLimitLabels>,
+  options?: {
+    /**
+     * The last refresh failed after this projection was read. The amounts and
+     * any reached state stay (never $0); a note says they may be out of date.
+     */
+    stale?: boolean;
+  },
+): SessionUsageLimitSummary {
+  if (!usage) return UNKNOWN;
+  const summary = summarizeFresh(usage, overrides);
+  if (!options?.stale) return summary;
+  const labels = sessionUsageLimitLabels(overrides);
+  return { ...summary, stale: true, notes: [...summary.notes, labels.staleNote] };
+}
+
+function summarizeFresh(
+  usage: SessionUsageLimit,
+  overrides?: Partial<SessionUsageLimitLabels>,
+): SessionUsageLimitSummary {
+  const labels = sessionUsageLimitLabels(overrides);
+  const base = {
+    inherited: usage.inherited,
+    rootSessionId: usage.rootSessionId,
+    version: usage.version,
+    stale: false,
+  };
+  if (usage.status === "unavailable") {
+    return {
+      ...UNKNOWN,
+      ...base,
+      state: "unavailable",
+      amountText: labels.unavailable,
+      notes: [labels.unavailableNote],
+    };
+  }
+  if (usage.status === "preparing" || usage.usedMicros === null) {
+    return {
+      ...UNKNOWN,
+      ...base,
+      state: usage.status === "preparing" ? "preparing" : "unavailable",
+      limitMicros: usage.limitMicros,
+      amountText: usage.status === "preparing" ? labels.preparing : labels.unavailable,
+      notes: [usage.status === "preparing" ? labels.preparingNote : labels.unavailableNote],
+    };
+  }
+  const used = usage.usedMicros;
+  const limit = usage.limitMicros;
+  const legacy = usage.history === "legacy_partial";
+  const unpriced = usage.unpricedCalls > 0;
+  const partial = usage.coverage === "partial" || legacy || unpriced;
+  const notes = [
+    ...(unpriced ? [labels.unpricedNote] : []),
+    ...(legacy ? [labels.legacyNote] : []),
+  ];
+  const usedText = formatSessionUsageMicros(used);
+  if (limit === null) {
+    return {
+      ...base,
+      state: "unlimited",
+      limitMicros: null,
+      usedMicros: used,
+      partial,
+      barFraction: null,
+      fraction: null,
+      amountText: partial ? labels.atLeastUsed(usedText) : labels.used(usedText),
+      notes,
+    };
+  }
+  const fraction = limit === 0 ? (used > 0 ? Infinity : 1) : used / limit;
+  const reached = usage.status === "reached" || used >= limit;
+  const limitText = formatSessionUsageMicros(limit);
+  return {
+    ...base,
+    state: reached ? "reached" : fraction >= SESSION_USAGE_LIMIT_NEAR_FRACTION ? "near" : "within",
+    limitMicros: limit,
+    usedMicros: used,
+    partial,
+    barFraction: Math.min(1, Math.max(0, Number.isFinite(fraction) ? fraction : 1)),
+    fraction: Number.isFinite(fraction) ? fraction : null,
+    // Text keeps the real overshoot; only the bar is clamped.
+    amountText: partial
+      ? labels.atLeastOfLimit(usedText, limitText)
+      : labels.usedOfLimit(usedText, limitText),
+    notes,
+  };
+}
+
+/**
+ * A summary for a refused Send before the projection was re-read: the refusal
+ * carries the amounts that applied when the server refused.
+ */
+export function summarizeSessionUsageLimitRefusal(
+  refusal: Pick<
+    ParsedSessionUsageLimitReachedRefusal,
+    "limitMicros" | "usedMicros" | "rootSessionId"
+  >,
+  overrides?: Partial<SessionUsageLimitLabels>,
+): SessionUsageLimitSummary {
+  const labels = sessionUsageLimitLabels(overrides);
+  return {
+    ...UNKNOWN,
+    state: "reached",
+    limitMicros: refusal.limitMicros,
+    usedMicros: refusal.usedMicros,
+    barFraction: 1,
+    fraction: refusal.limitMicros === 0 ? null : refusal.usedMicros / refusal.limitMicros,
+    amountText: labels.usedOfLimit(
+      formatSessionUsageMicros(refusal.usedMicros),
+      formatSessionUsageMicros(refusal.limitMicros),
+    ),
+    rootSessionId: refusal.rootSessionId,
+  };
+}
+
+/** "84" for 0.84; never rounds a near-limit share up to a misleading 100. */
+export function sessionUsageLimitPercent(fraction: number): string {
+  return String(Math.min(99, Math.floor(fraction * 100)));
+}

package/src/usage/summary.ts

@@ -0,0 +1,93 @@
+import type {
+  MemberAllowanceUsage,
+  UsageAllowanceStatus,
+  WorkspaceAllowanceUsage,
+  WorkspaceUsageResponse,
+} from "@opengeni/sdk/usage-allowances";
+
+import type { AllowanceScope } from "./allowance-copy";
+
+/** One ceiling as a person reads it: how much of it is used, and when it resets. */
+export type UsageReading = {
+  scope: AllowanceScope;
+  /** Used share of the ceiling. Can exceed 1 after post-call overshoot. */
+  fraction: number;
+  status: UsageAllowanceStatus;
+  resetsAt: string | null;
+  /** USD micros. Only shown when a host opts in with `formatAmount`. */
+  used: number;
+  limit: number;
+  remaining: number;
+};
+
+/**
+ * What a member can still do: `unlimited` when no ceiling applies, otherwise
+ * the state of whichever ceiling stops them first (`binding`).
+ */
+export type UsageSummary = {
+  state: "unlimited" | "ok" | "warning" | "exhausted";
+  /** The ceiling a person would ask to raise; null when unlimited. */
+  binding: UsageReading | null;
+  /** Their own ceiling, when one applies. */
+  member: UsageReading | null;
+  /** The shared workspace pool, when one is set. */
+  workspace: UsageReading | null;
+};
+
+function reading(
+  scope: AllowanceScope,
+  usage: Pick<
+    WorkspaceAllowanceUsage | MemberAllowanceUsage,
+    "limit" | "used" | "remaining" | "fraction" | "status" | "resetsAt"
+  >,
+): UsageReading | null {
+  if (usage.limit === null) return null;
+  return {
+    scope,
+    fraction: usage.fraction ?? (usage.limit === 0 ? 1 : usage.used / usage.limit),
+    status: usage.status,
+    resetsAt: usage.resetsAt,
+    used: usage.used,
+    limit: usage.limit,
+    remaining: Math.max(0, usage.remaining ?? usage.limit - usage.used),
+  };
+}
+
+/**
+ * Fold a usage response (normally `/usage/me`) into what to tell one member.
+ * The server's `status` decides warning/exhausted (it applies the configured
+ * thresholds); when both ceilings apply, the one with less room left binds.
+ */
+export function summarizeUsage(
+  usage: WorkspaceUsageResponse,
+  subjectId?: string | undefined,
+): UsageSummary {
+  const row =
+    subjectId === undefined
+      ? usage.members[0]
+      : usage.members.find((member) => member.subjectId === subjectId);
+  const member = row ? reading("member", row) : null;
+  const workspace = reading("workspace", usage.workspace);
+  const readings = [member, workspace].filter((value): value is UsageReading => value !== null);
+  if (readings.length === 0) return { state: "unlimited", binding: null, member, workspace };
+  // Raising a member ceiling cannot help while the shared pool is spent, so an
+  // exhausted workspace binds first.
+  const exhausted =
+    (workspace?.status === "exhausted" ? workspace : null) ??
+    (member?.status === "exhausted" ? member : null);
+  if (exhausted) return { state: "exhausted", binding: exhausted, member, workspace };
+  const warnings = readings.filter((value) => value.status === "warning");
+  const candidates = warnings.length > 0 ? warnings : readings;
+  const binding = candidates.reduce((tightest, value) =>
+    value.remaining < tightest.remaining ? value : tightest,
+  );
+  return { state: warnings.length > 0 ? "warning" : "ok", binding, member, workspace };
+}
+
+/** A whole-number percentage for display: "<1" for a sliver, never "0" for some use. */
+export function usagePercentLabel(fraction: number): string {
+  if (!Number.isFinite(fraction) || fraction <= 0) return "0";
+  if (fraction < 0.01) return "<1";
+  if (fraction < 1 && Math.round(fraction * 100) === 100) return "99";
+  return String(Math.round(fraction * 100));
+}

package/src/usage.ts

@@ -0,0 +1,70 @@
+// @opengeni/react/usage — usage allowances for people, kept out of the package
+// root and the session entry so hosts that don't meter usage never load it.
+//
+// Member-facing: `useUsage` + `<UsageMeter>` read the signed-in member's own
+// `/usage/me` (the session proxy serves exactly that route) and
+// `<UsageLimitNotice>` is the calm near/at-limit line for a composer header.
+// Admin-facing: `<UsageMemberList>` shows every member against their limit and
+// edits it with a share-of-budget slider; your backend saves the rule.
+//
+// Shares and percentages only by default. Pass `formatAmount` / `amounts` to
+// show money, credits, or plan multiples in your own unit.
+export { useUsage } from "./hooks/use-usage";
+export type { UsageClientLike, UseUsageOptions, UseUsageResult } from "./hooks/use-usage";
+export { summarizeUsage, usagePercentLabel } from "./usage/summary";
+export type { UsageReading, UsageSummary } from "./usage/summary";
+export {
+  DEFAULT_ALLOWANCE_LABELS,
+  allowanceLabels,
+  allowanceResetSentence,
+  formatAllowanceDate,
+} from "./usage/allowance-copy";
+export type { AllowanceLabels, AllowanceScope } from "./usage/allowance-copy";
+export { DEFAULT_USAGE_METER_LABELS, UsageMeter, UsageMeterView } from "./components/usage-meter";
+export type {
+  UsageMeterBaseProps,
+  UsageMeterLabels,
+  UsageMeterProps,
+  UsageMeterViewProps,
+} from "./components/usage-meter";
+export {
+  DEFAULT_USAGE_LIMIT_NOTICE_LABELS,
+  UsageLimitNotice,
+  UsageLimitNoticeView,
+} from "./components/usage-limit-notice";
+export type {
+  UsageLimitNoticeLabels,
+  UsageLimitNoticeProps,
+} from "./components/usage-limit-notice";
+export {
+  DEFAULT_USAGE_MEMBER_LIST_LABELS,
+  UsageMemberList,
+  describeMemberLimit,
+} from "./components/usage-member-list";
+export type {
+  UsageAmountFormat,
+  UsageMemberIdentity,
+  UsageMemberListLabels,
+  UsageMemberListProps,
+} from "./components/usage-member-list";
+export type { RenderAllowanceExhausted } from "./timeline/allowance-exhausted-row";
+
+// Per-task usage limits: one optional limit on a root chat's API-equivalent
+// model usage, shared by its agents. `summarizeSessionUsageLimit` turns the
+// server projection into words ("At least $12.34 of $50.00", "Preparing
+// usage") and `<SessionUsageLimitNotice>` is the calm near/at-limit line.
+export {
+  DEFAULT_SESSION_USAGE_LIMIT_LABELS,
+  SESSION_USAGE_LIMIT_NEAR_FRACTION,
+  sessionUsageLimitLabels,
+  sessionUsageLimitPercent,
+  summarizeSessionUsageLimit,
+  summarizeSessionUsageLimitRefusal,
+} from "./usage/session-usage-limit";
+export type {
+  SessionUsageLimitLabels,
+  SessionUsageLimitState,
+  SessionUsageLimitSummary,
+} from "./usage/session-usage-limit";
+export { SessionUsageLimitNotice } from "./components/session-usage-limit-notice";
+export type { SessionUsageLimitNoticeProps } from "./components/session-usage-limit-notice";

package/src/voice-recording-owner.ts

@@ -98,6 +98,28 @@ async function createUnderlyingOwnerLease(): Promise<UnderlyingOwnerLease> {
   return { ownerId, release: () => undefined };
 }
 
+/**
+ * Owner ids whose document still holds its Web Lock, or null when this browser
+ * cannot answer. A lock is released the moment its tab closes or crashes, so a
+ * recording whose owner is absent here is recoverable immediately instead of
+ * after the heartbeat stale window.
+ */
+export async function liveVoiceRecordingOwnerIds(): Promise<ReadonlySet<string> | null> {
+  if (!hasWebLocks() || typeof navigator.locks.query !== "function") return null;
+  try {
+    const snapshot = await navigator.locks.query();
+    const live = new Set<string>();
+    for (const lock of [...(snapshot.held ?? []), ...(snapshot.pending ?? [])]) {
+      if (lock.name?.startsWith(VOICE_RECORDING_OWNER_LOCK_PREFIX)) {
+        live.add(lock.name.slice(VOICE_RECORDING_OWNER_LOCK_PREFIX.length));
+      }
+    }
+    return live;
+  } catch {
+    return null;
+  }
+}
+
 function hasWebLocks(): boolean {
   return (
     typeof navigator !== "undefined" &&