@opengeni/react 1.0.1 → 1.0.2-canary.37202341988001

package/src/timeline/types.ts

@@ -1,4 +1,7 @@
 import type {
+  AllowanceExhaustedRefusal,
+  HumanInputQuestion,
+  HumanInputResponse,
   MediaGenerationResult,
   ResourceRef,
   SessionStatus,
@@ -6,6 +9,7 @@ import type {
   TimelineAnnotationSource,
   ToolAuthNeededPayload,
   ToolRef,
+  ToolDisplayMetadata,
 } from "@opengeni/sdk";
 
 /* ----------------------------------------------------------------------------
@@ -27,6 +31,13 @@ export type TimelineAnnotationSourceDescriptor = Omit<
 export type UserMessageItem = {
   kind: "user-message";
   id: string;
+  /**
+   * Renderer-only identity shared by a locally acknowledged message and the
+   * durable event that replaces it. The canonical event id remains `id`; this
+   * key only prevents the optimistic-to-durable handoff from remounting and
+   * replaying the row entrance animation.
+   */
+  reconciliationKey?: string | undefined;
   text: string;
   annotations?: TimelineAnnotation[] | undefined;
   annotationSource?: TimelineAnnotationSourceDescriptor | undefined;
@@ -46,19 +57,55 @@ export type UserMessageItem = {
         state: "sending" | "queued" | "failed";
         error?: string | undefined;
         onRetry?: (() => void) | undefined;
+        onEdit?: (() => void) | undefined;
         onRemove?: (() => void) | undefined;
       }
     | undefined;
 };
 
+export type HumanInputAnswerSummary = {
+  questionId: string;
+  label: string;
+  prompt: string;
+  values: string[];
+};
+
+/**
+ * One resolved structured question in the conversation. The live pending form
+ * is rendered at the timeline tip by the host; after settlement this item keeps
+ * both the agent's question and the human's answer visible as chat history.
+ */
+export type HumanInputItem = {
+  kind: "human-input";
+  id: string;
+  turnId: string | null;
+  requestId: string;
+  questions: HumanInputQuestion[];
+  response: HumanInputResponse;
+  answers: HumanInputAnswerSummary[];
+  occurredAt: string;
+};
+
 export type AgentMessageItem = {
   kind: "agent-message";
   id: string;
   turnId: string | null;
   text: string;
+  /**
+   * Assistant channel: provider-declared, or `commentary` when the model asked
+   * for tool work in the same response. Absent on legacy events and on
+   * undeclared final messages. Known from the first delta for Responses models.
+   */
+  phase?: "commentary" | "final_answer" | undefined;
   /** Still receiving deltas (no completed/turn-end seen yet). */
   streaming: boolean;
   occurredAt: string;
+  /**
+   * When the first streamed text arrived, kept once completion moves
+   * `occurredAt` to the completion time. Absent for a message that never
+   * streamed.
+   */
+  startedAt?: string | undefined;
   /** Available only after the canonical completed event lands. */
   annotationSource?: TimelineAnnotationSourceDescriptor | undefined;
 };
@@ -95,6 +142,7 @@ export type ToolCallItem = {
   turnId: string | null;
   callId: string | null;
   name: string;
+  display?: ToolDisplayMetadata;
   arguments: unknown;
   output: unknown;
   truncation?: ToolCallTruncation | null;
@@ -159,6 +207,36 @@ export type SandboxItem = {
   occurredAt: string;
 };
 
+export type StartupPhase =
+  | "queue"
+  | "sandbox"
+  | "rig"
+  | "repository"
+  | "files"
+  | "tools"
+  | "model_preparation"
+  | "provider_first_byte";
+
+/** A compact user-visible critical-path span reconstructed from durable events. */
+export type StartupPhaseItem = {
+  kind: "startup-phase";
+  id: string;
+  turnId: string | null;
+  phase: StartupPhase;
+  status: "running" | "complete" | "failed" | "cancelled";
+  startedAt: string;
+  completedAt: string | null;
+  durationMs: number | null;
+  /** Sandbox origin and rig marker outcomes refine the settled label only. */
+  outcome: "created" | "restored" | "resumed" | "skipped" | null;
+  blockedReason?:
+    | "capture_in_progress"
+    | "rotation_in_progress"
+    | "provider_recovery_in_progress"
+    | undefined;
+  occurredAt: string;
+};
+
 /**
  * A first-party workspace-memory write the agent made mid-turn — a `memory.saved`
  * (it committed a new preference / fact / procedure / decision / history) or a
@@ -168,6 +246,18 @@ export type SandboxItem = {
  * `onMemoryClick` handler the row also deep-links to the record in its memory
  * pane; without one it is non-interactive rich content.
  */
+export type KnowledgeItem = {
+  kind: "knowledge";
+  id: string;
+  turnId: string | null;
+  status: "complete" | "failed";
+  outcome: "published" | "pending" | "rejected" | "archived" | "failed";
+  fileId?: string | undefined;
+  filename?: string | undefined;
+  entryId?: string | undefined;
+  occurredAt: string;
+};
+
 export type MemoryItem = {
   kind: "memory";
   id: string;
@@ -220,7 +310,14 @@ export type FleetDecisionItem = {
   policyVersion: "adaptive-shadow-v1";
   actualOutcome: "selected" | "waiting" | "none";
   actualCandidateKey: string | null;
-  actualReason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "none";
+  actualReason:
+    | "lease_reused"
+    | "pin"
+    | "rotation"
+    | "active"
+    | "all_capped"
+    | "allocator_disabled"
+    | "none";
   shadowOutcome: "selected" | "paced" | "none";
   shadowCandidateKey: string | null;
   shadowReason:
@@ -259,13 +356,23 @@ export type SessionStatusItem = {
   kind: "session-status";
   id: string;
   status: SessionStatus;
+  /** Presentation-only evidence that this historical attention state resumed. */
+  resolvedAt?: string;
   occurredAt: string;
 };
 
 export type GoalItem = {
   kind: "goal";
   id: string;
-  action: "set" | "updated" | "completed" | "paused" | "resumed" | "cleared" | "continuation";
+  action:
+    | "set"
+    | "updated"
+    | "completed"
+    | "paused"
+    | "resumed"
+    | "cleared"
+    | "held"
+    | "continuation";
   text: string | null;
   occurredAt: string;
 };
@@ -275,9 +382,27 @@ export type NoticeItem = {
   id: string;
   tone: "waiting" | "cancelled" | "failed" | "input";
   text: string;
+  /** Presentation-only evidence that a historical approval wait resumed. */
+  resolvedAt?: string;
+  /** A preserved turn-end outcome, not a claim about current session state. */
+  recordedOutcome?: true;
+  /**
+   * Recorded agent wait only: delegated worker sessions that had not reported
+   * back when the wait began. Best effort from the loaded history; absent when
+   * none are known.
+   */
+  waitingAgents?: number;
+  /** Recorded agent wait only: when later input ended the wait. */
+  waitEndedAt?: string;
   /** 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;
 };
 
@@ -294,20 +419,40 @@ export type ContextCompactionItem = {
   estimatedTokensBefore: number | null;
   estimatedTokensAfter: number | null;
   skipReason: string | null;
+  /**
+   * Present only for a `summarization_failed` skip where the provider
+   * definitively rejected the compaction request. Content-free identifiers.
+   */
+  providerRejection: ContextCompactionProviderRejection | null;
   /** Provider implementation id for debug disclosure only. */
   implementation: string | null;
   occurredAt: string;
 };
 
+export type ContextCompactionProviderRejection = {
+  httpStatus: number;
+  type: string | null;
+  code: string | null;
+  param: string | null;
+  requestId: string | null;
+};
+
 export type MachineInputMember = {
   id: string;
   kind:
     | "scheduled_occurrence"
     | "goal_continuation"
+    | "background_command_result"
+    | "session_wait_timeout"
     | "agent_message"
     | "agent_steer_instruction"
     | "child_terminal_result"
-    | "media_generation_result";
+    | "media_generation_result"
+    | "child_requires_action"
+    | "child_requires_action_resolved"
+    | "child_paused"
+    | "child_waiting_capacity"
+    | "child_progress";
   classification: "success" | "failure" | "action_required" | "info";
   sourceId: string;
   summary: string;
@@ -323,6 +468,8 @@ export type MachineInputBatchItem = {
   id: string;
   turnId: string | null;
   members: MachineInputMember[];
+  /** Readable-turn presentation keeps machine payload prose inside the disclosure. */
+  compact?: boolean;
   occurredAt: string;
 };
 
@@ -342,12 +489,17 @@ export type AuthNeededItem = {
   turnId: string | null;
   /** The runtime surface that requested recovery, when the event is an MCP auth signal. */
   serverId: string | null;
+  /** Explicit recovery identity; never inferred from an opaque execution alias. */
+  canonicalServerId?: string | null;
+  connectionSubjectScope?: "workspace" | "subject" | null;
   /** Durable event family that produced this notice. */
   source?: "tool" | "credential" | "capability" | undefined;
   /** The connection's registrable domain, e.g. "linear.app". */
   providerDomain: string;
   /** The lapsed connection to reconnect, when the row survived. */
   connectionId: string | null;
+  /** Host-owned bindings must never be routed into OpenGeni's native reconnect flow. */
+  authoritySource?: ToolAuthNeededPayload["authoritySource"] | null | undefined;
   reason: ToolAuthNeededPayload["reason"] | null;
   /** Scopes the provider now needs; may inform the copy, never shown as a raw label. */
   scopes: string[];
@@ -359,6 +511,8 @@ export type AuthNeededItem = {
   authorizationUrl: string | null;
   /** Agent-selected catalog recommendation. The host still owns authorization. */
   capability?: NonNullable<ToolAuthNeededPayload["capability"]> | null | undefined;
+  /** Human-reviewed custom integration proposal. Never treated as catalog authority. */
+  setupRequest?: ToolAuthNeededPayload["setupRequest"] | null | undefined;
   occurredAt: string;
 };
 
@@ -366,6 +520,10 @@ export type TurnOutcome = "complete" | "failed" | "cancelled";
 
 export type TurnEndItem = {
   kind: "turn-end";
+  /** A durable Retry reopened this failed logical turn; its failure is history. */
+  resumedAt?: string;
+  /** Keep an existing answer visible when a recorded input wait ends without final output. */
+  preserveWaitResponse?: true;
   id: string;
   turnId: string | null;
   outcome: TurnOutcome;
@@ -373,14 +531,16 @@ export type TurnEndItem = {
   occurredAt: string;
 };
 
-export type TimelineItem =
+export type TimelineItem = (
   | UserMessageItem
+  | HumanInputItem
   | AgentMessageItem
   | ReasoningItem
   | ToolCallItem
   | WorkerItem
   | WorkerCompletionItem
   | SandboxItem
+  | StartupPhaseItem
   | SessionStatusItem
   | GoalItem
   | NoticeItem
@@ -388,17 +548,28 @@ export type TimelineItem =
   | MachineInputBatchItem
   | AuthNeededItem
   | MemoryItem
+  | KnowledgeItem
   | FleetDecisionItem
-  | TurnEndItem;
+  | TurnEndItem
+) & {
+  /** Durable identities, independent of renderer/reconciliation keys. */
+  sourceEvents?: readonly { eventId: string; sequence: number }[] | undefined;
+};
 
-/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
+/**
+ * Activity items cluster between chat messages (reasoning, tools, workers,
+ * sandbox, memory). Assistant prose is rendered separately.
+ */
 export type ActivityItem =
   | ReasoningItem
   | ToolCallItem
   | WorkerItem
   | SandboxItem
+  | StartupPhaseItem
   | MemoryItem
-  | FleetDecisionItem;
+  | KnowledgeItem
+  | FleetDecisionItem
+  | AgentMessageItem;
 
 export type TimelineGroup =
   | { kind: "item"; item: TimelineItem }
@@ -408,6 +579,20 @@ export type TimelineGroup =
       items: ActivityItem[];
       outcome?: TurnOutcome;
       failureText?: string;
+      /** One turn's chronological work history, including progress prose after settlement. */
+      work?: {
+        startedAt: string;
+        endedAt?: string;
+        responseStartedAt?: string;
+        waiting?: { label: string; since: string };
+        details: TimelineGroup[];
+        /**
+         * While the turn is live, its progress notes stay readable above the
+         * work row and are also listed in `details`. These are their item ids,
+         * so an expanded work disclosure can fold the outside copies away.
+         */
+        liveNoteIds?: string[];
+      };
     }
   | {
       kind: "turn";

package/src/types/machines.ts

@@ -23,6 +23,11 @@ import type {
   MachinesResponse,
   MachineState,
   MachineView,
+  MachineRuntime,
+  MachineRuntimeCapabilities,
+  MachineOperationPolicy,
+  MachineUpdateState,
+  MachineUpdateStatus,
   MetricSample,
 } from "@opengeni/sdk";
 
@@ -32,6 +37,11 @@ export type {
   MachinesResponse,
   MachineState,
   MachineView,
+  MachineRuntime,
+  MachineRuntimeCapabilities,
+  MachineOperationPolicy,
+  MachineUpdateState,
+  MachineUpdateStatus,
   MetricSample,
 };
 

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";