@opengeni/react 3.1.0 → 3.1.3-canary.38890816741001

package/dist/hooks/use-composer.d.ts

@@ -7,10 +7,17 @@ export type ComposerPolicy = {
     latencyMode: LatencyMode;
 };
 export type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId" | "annotations" | "model" | "reasoningEffort" | "latencyMode">;
+/** Unsent local content handed off from a new-conversation composer. */
+export type InitialComposerDraft = {
+    text: string;
+    resources?: ResourceRef[] | undefined;
+    annotations?: DraftTimelineAnnotation[] | undefined;
+    policy?: ComposerPolicy | undefined;
+};
 export type UseComposerOptions = EmbeddedSessionClientOverride & SessionEventFeedOptions & {
-    /** Called synchronously after an ordinary Send is accepted by the local UI. */
+    /** Called synchronously after local submission. Observer errors never change delivery. */
     onSubmitted?: ((text: string, input: SendMessageInput) => void) | undefined;
-    /** Called with the exact accepted wire input after a successful send. */
+    /** Called with the accepted wire input. Observer errors never turn acceptance into failure. */
     onSent?: ((text: string, input: SendMessageInput) => void) | undefined;
     /** Called with the exact wire input after a delivery failure. */
     onDeliveryError?: ((error: Error, input: SendMessageInput, delivery: "send" | "steer") => void) | undefined;
@@ -33,6 +40,13 @@ export type UseComposerOptions = EmbeddedSessionClientOverride & SessionEventFee
     draftPersistence?: "durable" | "disabled" | undefined;
     /** Required explicit authority when durable draft persistence is disabled. */
     initialPolicy?: ComposerPolicy | undefined;
+    /**
+     * Seed local unsent content once when this session is mounted/selected.
+     * The real server draft still supplies the revision used for persistence.
+     * A retained uncertain submission takes precedence over this handoff.
+     * An empty seed does not erase an existing server draft.
+     */
+    initialDraft?: InitialComposerDraft | undefined;
 };
 export type ComposerOptimisticMessage = {
     clientEventId: string;
@@ -47,6 +61,10 @@ export type ComposerOptimisticMessage = {
     triggerEventId?: string | null | undefined;
     appliedQueueVersion?: number | null | undefined;
     error?: string | undefined;
+    /** Bounded support reference retained independently of display copy across remounts. */
+    correlationId?: string | undefined;
+    /** False for a definitive refusal that requires changing payment or allowance settings. */
+    retryable?: boolean | undefined;
     outcomeUnknown?: boolean | undefined;
 };
 export type ComposerState = {
@@ -59,6 +77,8 @@ export type ComposerState = {
     /** Newly captured annotation the review surface should focus. */
     annotationReviewTargetId?: string | null | undefined;
     clearAnnotationReviewTarget?: (() => void) | undefined;
+    /** Focus an annotation, or the first incomplete note when omitted. */
+    requestAnnotationReview?: ((id?: string) => void) | undefined;
     /** Read the current draft synchronously before a destructive replacement. */
     hasDraftContent: () => boolean;
     /** Append the draft behind prompts already visible in the queue. */
@@ -66,6 +86,8 @@ export type ComposerState = {
     /** Locally acknowledged ordinary sends awaiting durable timeline reconciliation. */
     optimisticMessages?: ComposerOptimisticMessage[] | undefined;
     retryOptimisticMessage?: ((clientEventId: string) => void) | undefined;
+    /** Move a definitively refused message into an empty composer without resending it. */
+    restoreOptimisticMessage?: ((clientEventId: string) => void) | undefined;
     removeOptimisticMessage?: ((clientEventId: string) => void) | undefined;
     /** Supersede current direction with the draft. */
     steer: (text?: string) => Promise<boolean>;

package/dist/hooks/use-computer-frame-stream.d.ts

@@ -15,7 +15,7 @@ export type UseComputerFrameStreamOptions = EmbeddedComputerInteractionClientOve
 export type UseComputerFrameStreamResult = {
     state: ComputerFrameConnectionState;
     frame: ComputerFrame | null;
-    attachment: Pick<ComputerSessionAttachment, "computerSessionId" | "controllerGeneration" | "targetId" | "stream" | "expiresAt"> | null;
+    attachment: Pick<ComputerSessionAttachment, "computerSessionId" | "controllerGeneration" | "targetId" | "inputAllowed" | "stream" | "expiresAt"> | null;
     error: Error | null;
     reconnect: () => void;
 };

package/dist/hooks/use-computer-input-posture.d.ts

@@ -0,0 +1,13 @@
+import { type EmbeddedComputerInteractionClientOverride } from "../session-context.js";
+/** Semantic-only targets need caller authority without opening a pixel stream.
+ * A source change synchronously discards the previous posture. */
+export declare function useComputerInputPosture(options: EmbeddedComputerInteractionClientOverride & {
+    computerSessionId: string | null;
+    controllerGeneration: string | null;
+    enabled: boolean;
+}): {
+    inputAllowed: boolean | null;
+    pending: boolean;
+    error: Error | null;
+    refresh: () => void;
+};

package/dist/hooks/use-computer-session.d.ts

@@ -1,5 +1,7 @@
 import type { ComputerAction, ComputerActionReceipt, ComputerClipboard, ComputerFrame, ComputerObservation, ComputerSession, ComputerTarget } from "@opengeni/sdk/interaction";
 import { type EmbeddedComputerInteractionClientOverride } from "../session-context.js";
+export declare function isStaleComputerActionResult(value: unknown): boolean;
+export declare function computerActionReceiptError(receipt: ComputerActionReceipt): Error;
 export type UseComputerSessionOptions = EmbeddedComputerInteractionClientOverride & {
     computerSessionId: string | null;
     enabled?: boolean | undefined;
@@ -13,6 +15,8 @@ export type UseComputerSessionResult = {
     loading: boolean;
     mutating: boolean;
     error: Error | null;
+    /** Control service loss, independent of target accessibility inspection and media. */
+    controlError: Error | null;
     refresh: () => Promise<void>;
     readClipboard: () => Promise<ComputerClipboard>;
     /** Changes only this viewer's target cursor; it never takes ownership or

package/dist/hooks/use-connect.d.ts

@@ -0,0 +1,23 @@
+import type { ConnectController } from "@opengeni/connect";
+/** Internal consumers import the hook directly so setup surfaces stay lazy. */
+export declare function useConnect(controller: ConnectController): {
+    attempt: import("@opengeni/connect").ConnectAttempt | null;
+    busy: boolean;
+    error: Error | null;
+    begin: (input: {
+        providerId: string;
+        ownership: import("@opengeni/connect").ConnectOwnership;
+        returnUrl: string;
+        idempotencyKey: string;
+        reconnectAccountId?: string;
+        installationTarget?: import("@opengeni/connect").ConnectInstallationTarget;
+        mcpSetup?: import("@opengeni/connect").PreparedMcpSetup;
+    }) => Promise<import("@opengeni/connect").ConnectAttempt>;
+    recover: (attemptId: string) => Promise<import("@opengeni/connect").ConnectAttempt>;
+    refresh: () => Promise<import("@opengeni/connect").ConnectAttempt>;
+    waitForAction: (options?: {
+        timeoutMs?: number;
+    }) => Promise<import("@opengeni/connect").ConnectAttempt>;
+    advance: (action: import("@opengeni/connect").ConnectAdvance, idempotencyKey: string) => Promise<import("@opengeni/connect").ConnectAttempt>;
+    cancel: (idempotencyKey: string) => Promise<import("@opengeni/connect").ConnectAttempt>;
+};

package/dist/hooks/use-desktop-stream.d.ts

@@ -9,7 +9,7 @@ export type UseDesktopStreamOptions = {
     /** Read-only by default (v1 ruling H). interactive only when cap.mode allows. */
     interactive?: boolean | undefined;
     scaleViewport?: boolean | undefined;
-    /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
+    /** Custom RFB factory. Otherwise call enableDesktopViewer() on the desktop subpath. */
     rfbFactory?: DesktopRfbFactory | undefined;
     /** Additional WebSocket protocols for an authenticated placement proxy. */
     webSocketProtocols?: string[] | undefined;

package/dist/hooks/use-file-attachments.d.ts

@@ -8,6 +8,8 @@ export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
      * UseFileAttachmentsResult.addFiles} (the explicit picker / drop path)
      * bypasses it.
      */
+    /** Retain original uploads in the chat owner’s personal scope when private. */
+    scope?: "workspace" | "personal";
     pasteFilter?: ((file: File) => boolean) | undefined;
 };
 export type FileAttachment = {
@@ -20,7 +22,11 @@ export type FileAttachment = {
     file?: FileAsset | undefined;
     /** Object-URL for an inline preview; minted for `image/*` files only. */
     previewUrl?: string | undefined;
+    /** Stable SDK failure code for UI behavior that must not parse error copy. */
+    errorCode?: "secure_context_required" | undefined;
     error?: string | undefined;
+    /** Original diagnostic failure; presentation copy is kept separately in `error`. */
+    errorCause?: unknown;
 };
 export type UseFileAttachmentsResult = {
     attachments: FileAttachment[];
@@ -45,6 +51,12 @@ export type UseFileAttachmentsResult = {
     }) => void;
     /** Restore already-ready server assets without recreating browser-local bytes. */
     restoreReadyFiles: (files: Iterable<FileAsset>) => void;
+    /**
+     * Resolve a ready image's short-lived server preview URL on demand. Optional
+     * for upload-only embedded clients; local object-URL previews remain usable
+     * without it.
+     */
+    loadPreview?: ((id: string, signal?: AbortSignal) => Promise<string | undefined>) | undefined;
     /**
      * Re-run the upload for a `failed` attachment, in place (same id, same
      * source file). No-op for an id that isn't a known failed upload.

package/dist/hooks/use-goal.d.ts

@@ -39,7 +39,8 @@ export type UseGoalResult = {
 /**
  * The session's goal: state, the autonomy counters (`autoContinuations`,
  * `noProgressStreak`), and pause/resume control. A goal-less session yields
- * `goal: null` (the 404 is absorbed). Live-updates on goal, turn, session,
+ * `goal: null`: read through `findGoal` as a successful null when the client
+ * has it, otherwise from an absorbed 404. Live-updates on goal, turn, session,
  * control, and system-update events — pass `options.events` from
  * `useSessionEvents` to reuse its stream.
  */

package/dist/hooks/use-last-started-turn-policy.d.ts

@@ -1,4 +1,4 @@
-import type { LatencyMode, ReasoningEffort, SessionEvent } from "@opengeni/sdk";
+import type { LatencyMode, ReasoningEffort, SessionEvent, SessionModelAccountChoiceResponse } from "@opengeni/sdk";
 import { type ClientOverride } from "../session-context.js";
 import { type SessionEventFeedOptions } from "./internal.js";
 /** Refresh when a turn actually admits — not on composer picker / queue-only changes. */
@@ -11,6 +11,8 @@ export type LastStartedTurnPolicy = {
 };
 export type UseLastStartedTurnPolicyOptions = ClientOverride & SessionEventFeedOptions & {
     pollIntervalMs?: number | undefined;
+    /** Project the last lease-backed serving model without changing the accepted policy. */
+    includeServingModel?: boolean | undefined;
 };
 export type UseLastStartedTurnPolicyResult = {
     /** Null until some turn has durably emitted `turn.started`. */
@@ -19,6 +21,8 @@ export type UseLastStartedTurnPolicyResult = {
     error: Error | null;
     refresh: () => Promise<void>;
 };
+/** Never project an earlier turn's selection onto newly admitted work. */
+export declare function withServingModel(policy: LastStartedTurnPolicy | null, serving: SessionModelAccountChoiceResponse["serving"]): LastStartedTurnPolicy | null;
 /**
  * Model·effort·latency of the newest admitted turn (`turn.started`). This is
  * historical runtime truth for the session header — not the composer next-turn

package/dist/hooks/use-new-conversation.d.ts

@@ -0,0 +1,56 @@
+import { type FileResourceRef, type LatencyMode, type ReasoningEffort } from "@opengeni/sdk";
+import type { SessionRealtimeModel } from "@opengeni/sdk/realtime";
+import { type ClientOverride } from "../session-context.js";
+import { type ComposerState, type InitialComposerDraft } from "./use-composer.js";
+/** Browser choices, not server-owned agent configuration or authority. */
+export type NewConversationCreateOptions = {
+    resources?: FileResourceRef[] | undefined;
+    model?: string | undefined;
+    reasoningEffort?: ReasoningEffort | undefined;
+    latencyMode?: LatencyMode | undefined;
+    /** Creates an empty session; no synthetic first user message. */
+    startMode?: "realtime" | undefined;
+};
+export type CreatedConversation = {
+    sessionId: string;
+    /** The accepted first message; empty for voice-first creation. */
+    initialMessage: string;
+    /** Newer unsent content, or the whole untouched draft for voice-first creation. */
+    draft: InitialComposerDraft;
+    realtimeModel?: SessionRealtimeModel | undefined;
+};
+export type UseNewConversationOptions = ClientOverride & {
+    createSession?: ((initialMessage: string, idempotencyKey: string, options: NewConversationCreateOptions) => Promise<string>) | undefined;
+    onCreated?: ((created: CreatedConversation) => void) | undefined;
+    /** A host may disable creation while its own required state is loading. */
+    enabled?: boolean | undefined;
+    attachments?: boolean | undefined;
+    modelPicker?: boolean | undefined;
+    realtimeVoice?: boolean | undefined;
+    /** Changes reset this new-chat draft; use for host record/project scope. */
+    scopeKey?: string | undefined;
+};
+export type NewConversationController = ReturnType<typeof useNewConversation>;
+/** Stock new-chat state shared by OpenGeniChat and custom host layouts. */
+export declare function useNewConversation(options?: UseNewConversationOptions): {
+    client: import("../index.js").SessionClientLike;
+    workspaceId: string;
+    config: import("./use-client-config-flags.js").ClientConfigFlags;
+    files: import("./use-file-attachments.js").UseFileAttachmentsResult;
+    uploadsEnabled: boolean;
+    available: boolean;
+    showModelPicker: boolean;
+    catalog: import("./use-available-models.js").UseWorkspaceModelCatalogResult;
+    composer: ComposerState;
+    realtimeVoiceEnabled: boolean;
+    error: {
+        cause: unknown;
+    } | null;
+    finishingUploads: boolean;
+    pending: {
+        idempotencyKey: string;
+        realtimeModel: SessionRealtimeModel | undefined;
+    } | null;
+    retry: () => Promise<boolean>;
+    startRealtime: (model: SessionRealtimeModel) => Promise<boolean>;
+};

package/dist/hooks/use-new-session-draft.d.ts

@@ -0,0 +1,74 @@
+import type { FileAsset, NewSessionDraft, NewSessionSelectionHistory, OpenGeniClient, ResourceRef, SaveNewSessionDraftRequest } from "@opengeni/sdk";
+export type NewSessionDraftEditable = Omit<SaveNewSessionDraftRequest, "expectedRevision">;
+export type UseNewSessionDraftOptions = {
+    workspaceId: string;
+    client: Pick<OpenGeniClient, "getNewSessionDraft" | "saveNewSessionDraft" | "getFile">;
+    /** The complete browser-visible value. It must contain ready file refs only. */
+    value: NewSessionDraftEditable;
+    /** Apply a remote value to the controlled text/model/tool/options state. */
+    onApplyRemote: (value: NewSessionDraftEditable, selectionHistory: NewSessionSelectionHistory) => void;
+    /** Replace finalized attachments with freshly revalidated server assets. */
+    restoreReadyFiles: (files: Iterable<FileAsset>) => void;
+    /** Revalidate non-file resource identities against the current UI catalog. */
+    hydrateResources?: (resources: ResourceRef[]) => ResourceRef[] | Promise<ResourceRef[]>;
+    /** Keep the first read pending until catalogs needed for hydration are ready. */
+    resourceHydrationReady?: boolean;
+    /** A create in flight owns the exact clicked snapshot; resume autosave on settlement. */
+    suspendAutosave?: boolean;
+    /** Test seam for the quiet retry backoff and the background reconnect pace. */
+    transientRetry?: {
+        delaysMs?: readonly number[];
+        reconnectIntervalMs?: number;
+    };
+};
+export type FlushedNewSessionDraft = {
+    revision: number;
+    /** Signature of the exact local snapshot acknowledged by this revision. */
+    signature: string;
+};
+export type AcknowledgeConsumedNewSessionDraftResult = {
+    kind: "consumed";
+} | {
+    kind: "preserved";
+    flushed: FlushedNewSessionDraft;
+};
+export type UseNewSessionDraftResult = {
+    draft: NewSessionDraft | null;
+    revision: number;
+    loading: boolean;
+    saving: boolean;
+    conflict: Error | null;
+    error: Error | null;
+    /**
+     * `error` only says Opengeni was briefly unreachable (a deploy or database
+     * restart). Show the calm updating notice instead of the error; the hook
+     * keeps reconnecting in the background and clears this on success.
+     */
+    unavailable: boolean;
+    /** The latest failure, readable right after an awaited call (state lags a render). */
+    currentError: () => Error | null;
+    /** Mark Opengeni unreachable after a transient failure elsewhere in the send path. */
+    reportUnavailable: (cause: unknown) => boolean;
+    flush: () => Promise<FlushedNewSessionDraft | null>;
+    /** Send the visible snapshot, rebasing a stale draft revision without replacing the composer. */
+    flushForSend: (snapshot?: NewSessionDraftEditable) => Promise<FlushedNewSessionDraft | null>;
+    isCurrentSignature: (signature: string) => boolean;
+    /**
+     * Fence the exact acknowledged snapshot after session creation consumes it,
+     * preserving a genuinely newer local value against the safe-seed row.
+     */
+    acknowledgeConsumed: (flushed: FlushedNewSessionDraft, visibleSignature?: string) => Promise<AcknowledgeConsumedNewSessionDraftResult | null>;
+    reload: () => Promise<void>;
+    /** Surface a create-time OCC rejection through the ordinary draft recovery UI. */
+    captureConflict: (cause: unknown) => boolean;
+    resolveConflict: (choice: "keep_mine" | "use_remote") => Promise<void>;
+    clearError: () => void;
+};
+/**
+ * Actor-private, server-authoritative state for the composer shown before a
+ * session exists. Reads and writes are fenced to one client/workspace target;
+ * writes serialize and acquire the latest acknowledged revision at execution
+ * time, so a stale closure can never invent its own OCC base.
+ */
+export declare function useNewSessionDraft(options: UseNewSessionDraftOptions): UseNewSessionDraftResult;
+export declare function isNewSessionDraftConflict(cause: unknown): boolean;

package/dist/hooks/use-realtime-voice-models.d.ts

@@ -0,0 +1,7 @@
+import type { RealtimeModelOption } from "../realtime/session-realtime.js";
+/**
+ * Voice models this user can start in the workspace, or an empty list while
+ * disabled, unsupported or unknown. Shares the stock voice control's catalog
+ * cache, without eagerly loading voice code for a text-only embed.
+ */
+export declare function useRealtimeVoiceModels(client: unknown, workspaceId: string, enabled: boolean): RealtimeModelOption[];

package/dist/hooks/use-sandbox-files.d.ts

@@ -1,4 +1,4 @@
-import type { FsReadResponse, FsWriteResponse, OpenGeniRequestOptions, SessionCapabilities, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
+import type { FileSystemRouteIdentity, FsReadResponse, FsWriteResponse, OpenGeniRequestOptions, SessionCapabilities, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
 import { type ClientOverride } from "../provider.js";
 /** The git-status overlay a file row may carry (tints modified files in the tree). */
 export type FileTreeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
@@ -47,6 +47,9 @@ export type UseSandboxFilesOptions = ClientOverride & {
     events?: SessionEvent[] | undefined;
     /** Initial path to list (workspace root by default). */
     rootPath?: string | undefined;
+    /** Exact capability identity for the selected filesystem route. A route/root
+     * change resets this hook and makes stale provider requests fail retryably. */
+    route?: FileSystemRouteIdentity | undefined;
     /** Hold off the initial list (e.g. panel collapsed). Default true. */
     enabled?: boolean | undefined;
     /** Pause live reads/invalidation while preserving the last rendered result. */

package/dist/hooks/use-session-conversation.d.ts

@@ -0,0 +1,49 @@
+import { type ClientOverride } from "../session-context.js";
+import { type UseComposerOptions } from "./use-composer.js";
+export type UseSessionConversationOptions = ClientOverride & {
+    /** Uploads remain subject to the client's capabilities. Defaults to true. */
+    attachments?: boolean | undefined;
+    /** Defaults to the client's model-selection offer. */
+    modelPicker?: boolean | undefined;
+    /**
+     * Optional host context and notifications. The stock composer still owns
+     * draft validation, annotations, retry identity, queueing and delivery.
+     * File cleanup and upload blocking are composed with, not replaced by, these hooks.
+     */
+    composerOptions?: Pick<UseComposerOptions, "sendExtras" | "sendBlocked" | "onSubmitted" | "onSent" | "onDeliveryError" | "initialDraft"> | undefined;
+};
+export type SessionConversationController = ReturnType<typeof useSessionConversation>;
+/**
+ * The complete conversation's state, independent of its layout. Mount once in
+ * a stable host and pass the result to SessionConversationView, or compose the
+ * stock timeline/chrome/composer around the same controller. Unmounting a view
+ * does not dispose the stream, draft or uploads while this hook stays mounted.
+ * The ordinary SessionConversation component uses this exact implementation.
+ */
+export declare function useSessionConversation(sessionId: string, options?: UseSessionConversationOptions): {
+    client: import("../index.js").SessionClientLike;
+    workspaceId: string;
+    sessionId: string;
+    config: import("./use-client-config-flags.js").ClientConfigFlags;
+    catalog: import("./use-available-models.js").UseWorkspaceModelCatalogResult;
+    showModelPicker: boolean;
+    feed: import("./use-session-events.js").UseSessionEventsResult;
+    detail: import("./use-session.js").UseSessionResult;
+    queue: import("./use-turn-queue.js").UseTurnQueueResult;
+    human: import("./use-human-input.js").UseHumanInputRequestsResult;
+    control: import("./use-session-control.js").UseSessionControlResult;
+    approvals: import("../index.js").PendingApproval[];
+    files: import("./use-file-attachments.js").UseFileAttachmentsResult;
+    uploadsEnabled: boolean;
+    composer: import("./use-composer.js").ComposerControllerState;
+    /** The same live application context for text and durable voice messages. */
+    getModelContext: () => string | undefined;
+    timeline: import("../index.js").TimelineItem[];
+    status: import("@opengeni/sdk").SessionStatus | undefined;
+    terminal: boolean;
+    importedArchive: boolean;
+    running: boolean;
+    error: Error | null;
+    loadFailed: boolean;
+    retry: () => Promise<void>;
+};

package/dist/hooks/use-session-events.d.ts

@@ -1,7 +1,8 @@
-import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
+import { type SessionEvent, type SessionStatus, type StreamConnectionState } from "@opengeni/sdk";
 import { type EmbeddedSessionClientOverride } from "../session-context.js";
 import { type OlderHistoryLoadReceipt } from "../older-history.js";
 import type { TimelineItem } from "../timeline/types.js";
+import type { LatestQuestionOptions } from "./latest-question.js";
 export type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
 export type UseSessionEventsOptions = EmbeddedSessionClientOverride & {
     /** Resume after this sequence (exclusive). Nonzero keeps full replay/resume semantics. */
@@ -14,10 +15,12 @@ export type UseSessionEventsOptions = EmbeddedSessionClientOverride & {
 export type UseSessionEventsResult = {
     /** Replayed + live events, ordered by sequence, no gaps, no duplicates. */
     events: SessionEvent[];
-    /** Projected, renderable timeline (memoized over `events`). */
+    /** Renderable timeline, including the bounded navigation witness for a distant queued prompt. */
     timeline: TimelineItem[];
     /** Latest session status observed in the event log, if any. */
     sessionStatus: SessionStatus | null;
+    /** Sequence of the retained status projection, including events evicted from the window. */
+    sessionStatusSequence?: number;
     connectionState: SessionEventsConnectionState;
     /** Highest sequence seen so far (0 before the first event). */
     lastSequence: number;
@@ -27,6 +30,10 @@ export type UseSessionEventsResult = {
     windowTruncated: boolean;
     /** True until the initial tail window has been applied (windowed mode). */
     initialLoading: boolean;
+    /** A history window (including an empty tail) succeeded for this session/replay
+     * identity. Stays true through later stream errors and navigation/reloads.
+     * Full replay has no snapshot-completion watermark and does not set this by itself. */
+    initialHistoryReady: boolean;
     /** Whether older durable events are available before the current window. */
     hasOlder: boolean;
     /** True while an older window is being fetched. */
@@ -59,11 +66,19 @@ export type UseSessionEventsResult = {
      * "Jump to latest" when the tip is not in memory (history view).
      */
     jumpToLatest: () => Promise<void>;
+    /** Resolve the newest eligible durable human question. Pending prompts use the
+     * optional queue destination and return null; started prompts load their actual
+     * turn context (pass `timeline` to MessageTimeline as `items`). */
+    jumpToLatestQuestion: (options?: LatestQuestionOptions) => Promise<number | null>;
+    /** Replace history with a bounded window containing this exact durable event. */
+    jumpToSequence: (sequence: number, options?: {
+        signal?: AbortSignal;
+    }) => Promise<boolean>;
+    loadingTarget: boolean;
     error: Error | null;
 };
 export declare const SESSION_EVENT_BROWSER_MAX_BYTES: number;
-export declare const SESSION_EVENT_BROWSER_MAX_COUNT = 10000;
-export declare const SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES: number;
+export declare const SESSION_EVENT_BROWSER_MAX_COUNT = 20000;
 export declare const SESSION_EVENT_BROWSER_PENDING_MAX_BYTES: number;
 export declare const SESSION_EVENT_BROWSER_PENDING_MAX_COUNT = 256;
 export type BrowserSessionEventWindow = {
@@ -82,12 +97,18 @@ export declare function useSessionEvents(sessionId: string | null | undefined, o
  * accumulation retains the newest suffix; backward paging retains the oldest
  * prefix so newly fetched history cannot be immediately evicted. This is
  * deliberately separate from durable history and transport paging: when a
- * backward page evicts the live tail, the hook reconnects from the retained
- * high-water mark while preserving the highest-ever-observed sequence
- * separately. The source event remains durable in PostgreSQL throughout.
+ * backward page evicts the live tail, the hook enters bounded history mode and
+ * preserves the highest-ever-observed sequence separately for forward paging.
+ * The source event remains durable in PostgreSQL throughout. An event larger
+ * than the byte target is retained alone, never replaced by a lossy preview.
  */
 export declare function boundBrowserSessionEventWindow(events: readonly SessionEvent[], options?: {
     maxBytes?: number;
     maxCount?: number;
     direction?: "newest" | "oldest";
 }): BrowserSessionEventWindow;
+/** @internal Append immutable events without serializing the retained history again. */
+export declare function appendBrowserSessionEventWindow(current: BrowserSessionEventWindow, batch: readonly SessionEvent[], options?: {
+    maxBytes?: number;
+    maxCount?: number;
+}): BrowserSessionEventWindow;

package/dist/hooks/use-session-mcp-approval-policy.d.ts

@@ -1,4 +1,4 @@
-import type { SessionEvent, SessionMcpApprovalPolicy, SessionMcpServerMetadata, UpdateSessionMcpApprovalPolicyResponse } from "@opengeni/sdk";
+import type { SessionEvent, SessionMcpApprovalPolicy, SessionMcpApprovalPolicyTarget, UpdateSessionMcpApprovalPolicyResponse } from "@opengeni/sdk";
 import { type EmbeddedSessionMcpApprovalPolicyClientOverride } from "../session-context.js";
 import { type SessionEventFeedOptions } from "./internal.js";
 export declare function isSessionMcpApprovalPolicyEvent(event: Pick<SessionEvent, "type" | "payload">, serverId?: string): boolean;
@@ -7,7 +7,7 @@ export type UseSessionMcpApprovalPolicyOptions = EmbeddedSessionMcpApprovalPolic
     pollIntervalMs?: number | undefined;
 };
 export type UseSessionMcpApprovalPolicyResult = {
-    server: SessionMcpServerMetadata | null;
+    server: SessionMcpApprovalPolicyTarget | null;
     policy: SessionMcpApprovalPolicy | null;
     loading: boolean;
     error: Error | null;

package/dist/hooks/use-session-model-account.d.ts

@@ -0,0 +1,48 @@
+import type { ModelAccountPreferences, SessionEvent, SessionModelAccountChoiceResponse, SetSessionModelAccountChoiceRequest, SetSessionModelAccountChoiceResponse, UpdateModelAccountPreferencesRequest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider.js";
+import { type SessionEventFeedOptions } from "./internal.js";
+/** Events after which the session's model account may have changed. */
+export declare function isModelAccountEvent(event: Pick<SessionEvent, "type">): boolean;
+/**
+ * The structural slice of the SDK client the model-account picker needs.
+ * Method names and signatures match `OpenGeniClient`, so the real client
+ * satisfies it directly and a test client can stand in.
+ */
+export type ModelAccountClientLike = {
+    getSessionModelAccount: (workspaceId: string, sessionId: string) => Promise<SessionModelAccountChoiceResponse>;
+    setSessionModelAccount?: (workspaceId: string, sessionId: string, request: SetSessionModelAccountChoiceRequest) => Promise<SetSessionModelAccountChoiceResponse>;
+    updateModelAccountPreferences?: (organizationId: string, request: UpdateModelAccountPreferencesRequest) => Promise<ModelAccountPreferences>;
+};
+export type UseSessionModelAccountOptions = ClientOverride & SessionEventFeedOptions & {
+    sessionId: string;
+    /** Scope choices, including Automatic, to this provider. Omit for a whole-session reset. */
+    provider?: string | null | undefined;
+    /** The session's organization; needed to change the personal-fallback opt-in. */
+    organizationId?: string | null | undefined;
+    pollIntervalMs?: number | undefined;
+    modelAccountClient?: ModelAccountClientLike | undefined;
+};
+export type UseSessionModelAccountResult = {
+    choice: SessionModelAccountChoiceResponse | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** Choose an account, or `null` for automatic selection; true on success. */
+    choose: (connectionId: string | null) => Promise<boolean>;
+    choosing: boolean;
+    /** The in-flight target (`null` is automatic; `undefined` when idle). */
+    choosingTarget: string | null | undefined;
+    appliedTo: "waiting_turn" | "next_turn" | null;
+    /** Turn the caller's own personal-fallback opt-in on or off; true on success. */
+    setFallbackOptIn: (optIn: boolean) => Promise<boolean>;
+    canChangeFallback: boolean;
+    mutationError: Error | null;
+};
+/**
+ * The session's model account across every provider on the shared
+ * subscription core: the accounts it may use (the workspace's shared accounts
+ * and the caller's own personal accounts), the explicit choice, and the
+ * caller's personal-fallback opt-in. The server decides what may be chosen;
+ * this hook only reflects and requests.
+ */
+export declare function useSessionModelAccount(options: UseSessionModelAccountOptions): UseSessionModelAccountResult;

package/dist/hooks/use-supergrok-accounts.d.ts

@@ -1,5 +1,8 @@
 import type { SuperGrokAccount, SuperGrokAccountsResponse } from "@opengeni/sdk";
 import { type ClientOverride } from "../provider.js";
+import { type SharedQueryKey } from "./shared-query.js";
+/** Shared-cache key for a workspace's SuperGrok accounts (internal; see `useSharedQuery`). */
+export declare const superGrokAccountsQueryKey: (workspaceId: string) => SharedQueryKey;
 export type SuperGrokAccountsClientLike = {
     listSuperGrokAccounts: (workspaceId: string) => Promise<SuperGrokAccountsResponse>;
     activateSuperGrokAccount?: (workspaceId: string, accountId: string) => Promise<{
@@ -22,5 +25,8 @@ export type UseSuperGrokAccountsResult = {
     activating: boolean;
     mutationError: Error | null;
 };
-/** Workspace-visible xAI accounts. Workspace scope is the connection default. */
+/**
+ * Workspace-visible xAI accounts. Workspace scope is the connection default.
+ * Reads share the client-scoped cache, so a remount renders retained rows at once.
+ */
 export declare function useSuperGrokAccounts(options?: UseSuperGrokAccountsOptions): UseSuperGrokAccountsResult;

package/dist/hooks/use-terminal-stream.d.ts

@@ -5,8 +5,9 @@ export type UseTerminalStreamOptions = {
     /** The Terminal cell of the negotiated capabilities (`capabilities.Terminal`).
      *  The stream connects ONLY when `transport === "pty-ws"` and `url` is set; on a
      *  cold box (`transport === "sse-events"` / no url) it stays idle and the caller
-     *  falls back to the Channel-A read-only firehose. */
-    capability: Pick<TerminalCapability, "transport" | "url" | "token" | "expiresAt"> | null;
+     *  falls back to the Channel-A firehose. Explicit PTY-capable cold cells may
+     *  buffer input, but cannot connect or flush until the grant arrives. */
+    capability: (Pick<TerminalCapability, "transport" | "url" | "token" | "expiresAt"> & Partial<Pick<TerminalCapability, "ptyCapable" | "reason">>) | null;
     /** Called for each OUTPUT payload from ttyd (write verbatim into xterm). */
     onOutput?: ((data: string) => void) | undefined;
     /** Called when ttyd sends a SET_WINDOW_TITLE frame. */
@@ -19,11 +20,16 @@ export type UseTerminalStreamOptions = {
     initialRows?: number | undefined;
 };
 export type UseTerminalStreamResult = {
-    /** True once the ttyd socket is open (and the auth frame has been sent). */
+    /** True when input can be sent. Legacy ttyd does not guarantee shell readiness. */
     connected: boolean;
     status: TerminalStreamStatus;
+    /** `waiting` requires explicit shell readiness; `legacy` has no such guarantee. */
+    inputReadiness: "pending" | "waiting" | "ready" | "legacy";
+    /** Deliberate escape for startup prompts/no-Readline shells. Clears queued
+     * typing without executing it, then enables unguaranteed manual input. */
+    useLegacyInput: () => void;
     /** Pipe a keystroke/paste to PTY stdin. Input during CONNECTING is bounded and
-     *  replayed only after ttyd authentication succeeds. */
+     *  replayed after negotiated readiness (or legacy ttyd preferences). */
     write: (data: string) => void;
     /** Tell ttyd the PTY window changed size (on xterm fit/resize). */
     resize: (cols: number, rows: number) => void;
@@ -45,7 +51,7 @@ export declare function terminalStreamCredentialUsable(capability: Pick<Terminal
  *   - first frame: `JSON.stringify({ AuthToken: "" })` (+ optional columns/rows).
  *   - client→server: INPUT = "0"+data ; RESIZE = "1"+JSON({columns,rows}).
  *   - server→client: "0" = OUTPUT (→ xterm) ; "1" = SET_WINDOW_TITLE ;
- *     "2" = SET_PREFERENCES (ignored). Binary frames are decoded the same way.
+ *     "2" = SET_PREFERENCES (readiness negotiation). Binary frames decode identically.
  *
  * On a `url`/`token` rotation (a box rollover folds a fresh address into the cell)
  * the effect re-runs: the old socket closes and a fresh one connects — a brief