@opengeni/react 7.4.0 → 7.5.0-canary.36927100590001

package/src/timeline/projection.ts

@@ -1,6 +1,8 @@
 import {
   parseMediaGenerationResult,
   parseToolDisplayMetadata,
+  EMPTY_FINAL_REPLY_NOTICE,
+  turnCompletedWithEmptyFinalReply,
   type HumanInputAnswer,
   type HumanInputQuestion,
   type HumanInputResponse,
@@ -9,6 +11,10 @@ import {
   type TimelineAnnotation,
 } from "@opengeni/sdk";
 import fleetDecisionItem from "./fleet-decision-projection";
+import {
+  allowanceExhaustedMessage,
+  parseAllowanceExhaustedRefusal,
+} from "@opengeni/sdk/allowance-refusal";
 import {
   CREDIT_EXHAUSTION_MESSAGE,
   presentFailure,
@@ -145,6 +151,34 @@ export function buildTimeline(
   options: { partialStart?: boolean } = {},
 ): TimelineItem[] {
   const items: TimelineItem[] = [];
+  const allowanceNotices = new Set<string>();
+  const allowanceNotice = (event: SessionEvent, turnId: string | null) => {
+    const refusal = parseAllowanceExhaustedRefusal(event.payload);
+    if (!refusal) return null;
+    const text = allowanceExhaustedMessage(refusal);
+    const key = JSON.stringify([
+      turnId,
+      event.turnAttemptId,
+      startupRecoveryRevisionByTurn.get(turnId ?? "") ?? 0,
+      refusal.scope,
+      refusal.subjectId,
+      refusal.resetsAt,
+    ]);
+    if (!allowanceNotices.has(key)) {
+      allowanceNotices.add(key);
+      items.push({
+        kind: "notice",
+        id: `${event.id}-allowance`,
+        tone: "failed",
+        text,
+        // The canonical sentence replaces upstream prose, so a host renderer
+        // reading `message` never shows a wrapper's private wording.
+        allowance: { ...refusal, message: text },
+        occurredAt: event.occurredAt,
+      });
+    }
+    return text;
+  };
   const prescan = prescanTurnAnchors(events);
   const ordered = orderTimelineEvents(events, prescan);
   // A bounded replay can begin halfway through a message (including inside an
@@ -1200,6 +1234,11 @@ export function buildTimeline(
         break;
       }
 
+      case "usage.exhausted": {
+        allowanceNotice(event, turnId);
+        break;
+      }
+
       case "turn.completed": {
         // A standalone manual compaction uses the turn ledger for fencing and
         // recovery, but it is maintenance rather than a conversational turn.
@@ -1218,6 +1257,15 @@ export function buildTimeline(
         // Rendering it as a clean "complete" turn is a lie that leaves the
         // session looking healthy while every future turn silently dies, so it
         // projects exactly like a failed turn plus an explicit notice.
+        const allowance = parseAllowanceExhaustedRefusal(payload);
+        if (allowance) {
+          finalizeOpen(turnId, "complete", event.occurredAt);
+          takeAgentResponse(turnId);
+          takePendingWaitOutcome(turnId);
+          items.push(turnEndItem(event, "failed", ALLOWANCE_TURN_END_TEXT));
+          allowanceNotice(event, turnId);
+          break;
+        }
         if (isCreditExhaustionPayload(payload)) {
           finalizeOpen(turnId, "complete", event.occurredAt);
           takeAgentResponse(turnId);
@@ -1283,6 +1331,16 @@ export function buildTimeline(
         finalizeOpen(turnId, "complete", event.occurredAt);
         const completedTurn = turnEndItem(event, "complete", null);
         items.push(completedTurn);
+        if (turnCompletedWithEmptyFinalReply(payload)) {
+          items.push({
+            kind: "notice",
+            id: `${event.id}-empty-final-reply`,
+            tone: "input",
+            text: EMPTY_FINAL_REPLY_NOTICE,
+            recordedOutcome: true,
+            occurredAt: event.occurredAt,
+          });
+        }
         const hasCompletedFinalResponse =
           latestAgentResponse?.completed === true &&
           latestAgentResponse.item.phase !== "commentary" &&
@@ -1317,16 +1375,21 @@ export function buildTimeline(
         // Credit death can hide behind fields `failureMessage` doesn't read
         // (detail/segmentLimit), so classify the whole payload before falling
         // back to the generic error/message extraction.
-        const failureText = isCreditExhaustionPayload(payload)
-          ? CREDIT_EXHAUSTION_MESSAGE
-          : failureMessage(payload);
+        const allowance = parseAllowanceExhaustedRefusal(payload);
+        const failureText = allowance
+          ? ALLOWANCE_TURN_END_TEXT
+          : isCreditExhaustionPayload(payload)
+            ? CREDIT_EXHAUSTION_MESSAGE
+            : failureMessage(payload);
         // The TURN failed — the in-flight items did not. Chip doctrine: red is
         // spent once, on the turn-level outcome. Items caught mid-flight read
         // as calm "interrupted" (same as turn.cancelled); an item that itself
         // failed keeps its own failed status from its output event.
         finalizeOpen(turnId, "cancelled", event.occurredAt);
         items.push(turnEndItem(event, "failed", failureText));
-        if (!hadActivity) {
+        if (allowance) {
+          allowanceNotice(event, turnId);
+        } else if (!hadActivity) {
           items.push({
             kind: "notice",
             id: event.id,
@@ -1688,8 +1751,16 @@ export function stripOpaqueCitationTokens(text: string): string {
   return text.replace(/\s*cite(?:[^]+)+/gu, "");
 }
 
+/**
+ * The turn summary's short outcome for a usage ceiling. The adjacent notice row
+ * carries who can raise it and when it resets (and is host-customizable), so
+ * the summary line stays a neutral fact instead of repeating remedy prose.
+ */
+const ALLOWANCE_TURN_END_TEXT = "Usage limit reached";
+
 /** The turn-end payload shape, as `isCreditExhaustion` wants it. */
 function isCreditExhaustionPayload(payload: Record<string, unknown>): boolean {
+  if (payload.code === "allowance_exhausted") return false;
   return isCreditExhaustion({
     error: typeof payload.error === "string" ? payload.error : null,
     detail: typeof payload.detail === "string" ? payload.detail : null,
@@ -2348,6 +2419,9 @@ export function isTurnExecutionEvidence(type: string): boolean {
     isAgentActivityEvent(type) ||
     type === "turn.completed" ||
     type === "turn.failed" ||
+    // An admission refusal can settle a queued turn before it ever starts:
+    // its prompt still belongs above the "usage limit reached" row.
+    type === "usage.exhausted" ||
     type === "turn.superseded" ||
     type === "turn.recovery.requested" ||
     type === "turn.capacity_waiting" ||

package/src/timeline/types.ts

@@ -1,4 +1,5 @@
 import type {
+  AllowanceExhaustedRefusal,
   HumanInputQuestion,
   HumanInputResponse,
   MediaGenerationResult,
@@ -56,6 +57,7 @@ export type UserMessageItem = {
         state: "sending" | "queued" | "failed";
         error?: string | undefined;
         onRetry?: (() => void) | undefined;
+        onEdit?: (() => void) | undefined;
         onRemove?: (() => void) | undefined;
       }
     | undefined;
@@ -391,6 +393,12 @@ export type NoticeItem = {
   /** Optional evidence kept inspectable without overwhelming the main rail. */
   details?: { label: string; value: unknown };
   action?: { label: string; url: string };
+  /**
+   * A usage ceiling refused further work. `text` keeps the canonical sentence
+   * for plain-text consumers; `MessageTimeline` renders this structured row
+   * (customizable with `renderAllowanceExhausted` / `allowanceExhaustedLabels`).
+   */
+  allowance?: AllowanceExhaustedRefusal;
   occurredAt: string;
 };
 

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/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,50 @@
+// @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";