@opengeni/react 0.29.0 → 0.33.1

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

@@ -0,0 +1,62 @@
+import type { SessionEvent } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type TerminalChunk = {
+    /** Stable key (the source event id) so the xterm writer tracks a written-cursor. */
+    id: string;
+    /** Raw output bytes (utf-8 lossy) — written verbatim into xterm. */
+    text: string;
+    /** stdout vs stderr (drives optional tinting). */
+    stream: "stdout" | "stderr";
+    /** Global ordering: the source event sequence. */
+    seq: number;
+};
+export type UseSandboxTerminalOptions = ClientOverride & {
+    /** The live session event log (usually `useSessionEvents().events`). */
+    events: SessionEvent[];
+    /** Restrict to one PTY (by ptyId). Omit to interleave the agent firehose +
+     *  every PTY. */
+    ptyId?: string | undefined;
+    /** Include the agent's command-output firehose (sandbox.command.output.delta).
+     *  Default true — the read-only "terminal-as-events" the data path settled on. */
+    includeAgentFirehose?: boolean | undefined;
+    /**
+     * OPEN an interactive PTY against the box so the user can type, not just watch.
+     * When true (and the session is live) the hook calls `terminalPtyOpen` once,
+     * tracks the returned ptyId, exposes `write` immediately (bound to that ptyId),
+     * and closes the PTY on unmount. The PTY's banner + every output delta ride the
+     * SSE spine (`terminal.pty.*`) back into `events`, so xterm fills in. Default
+     * false — a caller that only wants the read-only firehose stays projection-only.
+     */
+    interactive?: boolean | undefined;
+    /** Lease liveness ("cold" | "warm" | "draining"). The interactive PTY is only
+     *  opened once the box is warm — opening on a cold box (ptyCapable is advertised
+     *  cold too) races the box and leaves a dead read-only terminal. */
+    liveness?: string | undefined;
+};
+export type UseSandboxTerminalResult = {
+    /** Ordered, deduped output chunks to write() into xterm.js. */
+    chunks: TerminalChunk[];
+    /** Whether a PTY is currently open (drives the prompt/cursor affordance). */
+    running: boolean;
+    /**
+     * Interactive write fn when a PTY is open and the backend supports stdin
+     * (`terminal.transport === "pty-ws"` / `PtyOpenResponse.supportsInput`). Null
+     * in the read-only event-projection case (v1 default).
+     */
+    write: ((data: string) => void) | null;
+    /** The active PTY id, if one is open. */
+    activePtyId: string | null;
+    /** Close the active PTY (no-op when none is open). */
+    close: () => void;
+    /** A PTY-open failure (interactive mode), if any. */
+    error: Error | null;
+};
+/**
+ * Project the Channel-A event log into an xterm-writable byte stream. The
+ * terminal is "terminal-as-events": there is NO new socket in v1 — the agent's
+ * command output (`sandbox.command.output.delta`) and any interactive PTY
+ * (`terminal.pty.output.delta`) ride the existing SSE spine. When a PTY is open
+ * and the backend accepts stdin, `write` pipes keystrokes via the SDK
+ * `terminalPtyWrite` (the synchronous Channel-A control path).
+ */
+export declare function useSandboxTerminal(sessionId: string | null | undefined, options: UseSandboxTerminalOptions): UseSandboxTerminalResult;

package/dist/hooks/use-scheduled-tasks.d.ts

@@ -0,0 +1,15 @@
+import type { ScheduledTask } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseScheduledTasksOptions = ClientOverride & {
+    limit?: number | undefined;
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseScheduledTasksResult = {
+    tasks: ScheduledTask[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** List the workspace's scheduled tasks (drift checks, sentinels, reapers, ...). */
+export declare function useScheduledTasks(options?: UseScheduledTasksOptions): UseScheduledTasksResult;

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

@@ -0,0 +1,83 @@
+import { type SessionCapabilities, type SessionEvent } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "on-demand" | "error";
+export type UseSessionCapabilitiesOptions = ClientOverride & {
+    /**
+     * Live event log to fold `stream.url.rotated` from (usually
+     * `useSessionEvents().events`). When present the desktop socket stays fresh on
+     * a box rollover without a round-trip; stale-epoch rotations are dropped.
+     */
+    events?: SessionEvent[] | undefined;
+    /**
+     * Whether to acquire a viewer holder for the desktop pixel plane. Requires the
+     * un-redacted acknowledgment to have been recorded (else the attach 409s and
+     * the hook surfaces the consent requirement). Default false: read-only
+     * negotiation (no holder, no warm) — terminal/files/git work without it.
+     */
+    attachDesktop?: boolean | undefined;
+    /**
+     * Whether to acquire a viewer holder to warm the box for the REAL interactive
+     * terminal (the ttyd pty-ws plane). Symmetric with `attachDesktop` and shares
+     * the SAME viewer attach (one warm box serves both planes), but needs NO
+     * un-redacted acknowledgment — a shell is interactive by nature, and the gate
+     * is the scoped tunnel URL + stream token. Default false: the terminal stays on
+     * the read-only Channel-A firehose until the user opens/focuses it. The attach
+     * folds the minted `pty-ws` url+token into the `Terminal` cell.
+     */
+    attachTerminal?: boolean | undefined;
+    /**
+     * Whether to acquire a viewer holder to warm the box for a FILE WRITE — the
+     * wake-on-edit INTENT (a first keystroke in the editor), NOT passive browsing.
+     * Shares the SAME viewer attach as the desktop/terminal (one warm box, one
+     * holder) and — like the terminal — needs NO un-redacted acknowledgment:
+     * reading/writing files is the ordinary Channel-A control plane, not the pixel
+     * plane. It folds NO live URL (files ride the stateless HTTP plane) — it only
+     * refcounts liveness. Unlike desktop/terminal it warms even a COLD box: an edit
+     * legitimately cold-creates (that IS the wake), so the write lands ~100ms warm
+     * instead of paying the ~5s cold resume. Default false. IMPORTANT: merely
+     * opening/reading the Files tab must NOT set this — browsing capture-served
+     * trees/diffs needs no box, and warming one on a cold glance burns box-hours to
+     * serve reads the capture already answers for free.
+     */
+    attachFiles?: boolean | undefined;
+    /** Hold off negotiating (e.g. the workbench panel is collapsed). Default true. */
+    enabled?: boolean | undefined;
+    /** Poll cadence (ms) while the lease is cold/warming. Default 1500. */
+    warmingPollMs?: number | undefined;
+    /**
+     * Give up waiting for `warm` after this long while polling (ms) and surface a
+     * stalled error with a manual `renegotiate`. Default 30000. This is a UI
+     * patience deadline, independent from the worker's sandbox warming timeout.
+     * 0 disables the deadline.
+     */
+    warmingDeadlineMs?: number | undefined;
+};
+export type UseSessionCapabilitiesResult = {
+    /** The negotiated capability doc — the single source of UI truth. */
+    capabilities: SessionCapabilities | null;
+    state: SessionCapabilitiesState;
+    error: Error | null;
+    /**
+     * 409 from the desktop attach: the un-redacted (or shared) plane needs explicit
+     * acknowledgment before a viewer holder is granted. Drives the consent prompt.
+     */
+    acknowledgmentRequired: "unredacted" | "shared" | null;
+    /** 429 from the desktop attach: the per-session viewer cap is reached. */
+    viewerCapReached: boolean;
+    /** The viewer holder id minted on a desktop attach (for detach/heartbeat). */
+    viewerId: string | null;
+    /** Force a re-negotiation (after acknowledging, a resolution change, etc.). */
+    renegotiate: () => void;
+};
+/**
+ * The capability-negotiation hook. Discovers what THIS session+backend+OS
+ * supports (FileSystem/Terminal/Git always-ish; DesktopStream/Recording
+ * sometimes), drives capability-gated rendering, and — when `attachDesktop` —
+ * holds a viewer lease + heartbeats it so the box stays warm while watched.
+ *
+ * Degradation is a value, never a crash: an unsupported surface comes back
+ * `available:false`/`transport:null` + a `reason`; the components render the
+ * reason-aware empty state. 409 (consent) and 429 (viewer cap) are surfaced as
+ * typed signals, not thrown.
+ */
+export declare function useSessionCapabilities(sessionId: string | null | undefined, options?: UseSessionCapabilitiesOptions): UseSessionCapabilitiesResult;

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

@@ -0,0 +1,22 @@
+import type { SessionControlResponse, SessionEvent } from "@opengeni/sdk";
+import { type EmbeddedSessionClientOverride } from "../session-context";
+export type UseSessionControlOptions = EmbeddedSessionClientOverride;
+export type UseSessionControlResult = {
+    pause: (reason?: string) => Promise<SessionControlResponse | null>;
+    resume: (reason?: string) => Promise<SessionControlResponse | null>;
+    controlling: boolean;
+    /** Approve a pending `requires_action` approval. */
+    approve: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
+    /** Reject a pending `requires_action` approval. */
+    reject: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
+    /** True while an approval decision is in flight. */
+    responding: boolean;
+    error: Error | null;
+    clearError: () => void;
+};
+/**
+ * Session pause/resume and approval decisions. Pair with
+ * `useSessionEvents` (for `session.requiresAction` payloads carrying the
+ * `approvalId`) to render an approval bar.
+ */
+export declare function useSessionControl(sessionId: string | null | undefined, options?: UseSessionControlOptions): UseSessionControlResult;

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

@@ -0,0 +1,92 @@
+import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
+import { type EmbeddedSessionClientOverride } from "../session-context";
+import type { TimelineItem } from "../timeline/types";
+export type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
+export type UseSessionEventsOptions = EmbeddedSessionClientOverride & {
+    /** Resume after this sequence (exclusive). Nonzero keeps full replay/resume semantics. */
+    after?: number | undefined;
+    /** Load a bounded tail by default, or opt back into full replay from `after`. */
+    replay?: "windowed" | "full" | undefined;
+    /** Pause the stream without unmounting (e.g. hidden tab). Defaults to true. */
+    enabled?: boolean | undefined;
+};
+export type UseSessionEventsResult = {
+    /** Replayed + live events, ordered by sequence, no gaps, no duplicates. */
+    events: SessionEvent[];
+    /** Projected, renderable timeline (memoized over `events`). */
+    timeline: TimelineItem[];
+    /** Latest session status observed in the event log, if any. */
+    sessionStatus: SessionStatus | null;
+    connectionState: SessionEventsConnectionState;
+    /** Highest sequence seen so far (0 before the first event). */
+    lastSequence: number;
+    /** Exact serialized bytes retained in the current browser event window. */
+    windowBytes: number;
+    /** Whether older delivered events were evicted from the browser window. */
+    windowTruncated: boolean;
+    /** True until the initial tail window has been applied (windowed mode). */
+    initialLoading: boolean;
+    /** Whether older durable events are available before the current window. */
+    hasOlder: boolean;
+    /** True while an older window is being fetched. */
+    loadingOlder: boolean;
+    /** Prepend an older density-bounded window; resolves true when more remain. */
+    loadOlder: () => Promise<boolean>;
+    /**
+     * Durable events exist after the current window (history view jumped away
+     * from the live tip, or a forward page is incomplete).
+     */
+    hasNewer: boolean;
+    /** True while a newer history page is being fetched. */
+    loadingNewer: boolean;
+    /**
+     * Append one density-bounded newer page without pulling the whole gap.
+     * Resolves true when more newer history remains.
+     */
+    loadNewer: () => Promise<boolean>;
+    /** True while replacing the window with the session start. */
+    loadingOldest: boolean;
+    /**
+     * Jump to the durable session start: one bounded oldest window, no middle.
+     * Leaves live streaming until {@link jumpToLatest} (or loadNewer catches up).
+     */
+    loadOldest: () => Promise<boolean>;
+    /** True while reloading the live tip window. */
+    loadingLatest: boolean;
+    /**
+     * Reload the newest bounded tip and resume live streaming. Use for
+     * "Jump to latest" when the tip is not in memory (history view).
+     */
+    jumpToLatest: () => Promise<void>;
+    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_PENDING_MAX_BYTES: number;
+export declare const SESSION_EVENT_BROWSER_PENDING_MAX_COUNT = 256;
+export type BrowserSessionEventWindow = {
+    events: SessionEvent[];
+    bytes: number;
+    truncated: boolean;
+};
+/**
+ * Live-stream a session's event log with replay-by-sequence, reconnect, and
+ * batched React updates. Fresh loads default to a bounded tail window; pass
+ * `replay: "full"` or a nonzero `after` for the previous full replay path.
+ */
+export declare function useSessionEvents(sessionId: string | null | undefined, options?: UseSessionEventsOptions): UseSessionEventsResult;
+/**
+ * Keep one direction-aware count+byte-bounded browser window. Live/default
+ * 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.
+ */
+export declare function boundBrowserSessionEventWindow(events: readonly SessionEvent[], options?: {
+    maxBytes?: number;
+    maxCount?: number;
+    direction?: "newest" | "oldest";
+}): BrowserSessionEventWindow;

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

@@ -0,0 +1,17 @@
+import type { SessionEvent, SessionLineageResponse } from "@opengeni/sdk";
+import { type EmbeddedSessionLineageClientOverride } from "../session-context";
+export type UseSessionLineageOptions = EmbeddedSessionLineageClientOverride & {
+    events?: SessionEvent[] | undefined;
+    /** Refresh interval (ms). Off by default. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseSessionLineageResult = {
+    lineage: SessionLineageResponse | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+export declare function isLineageRefreshEvent(event: SessionEvent): boolean;
+/** Read the ancestors + descendant tree for one session. Data-only; no UI state. */
+export declare function useSessionLineage(sessionId: string | null | undefined, options?: UseSessionLineageOptions): UseSessionLineageResult;

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

@@ -0,0 +1,23 @@
+import type { SessionEvent, SessionMcpApprovalPolicy, SessionMcpServerMetadata, UpdateSessionMcpApprovalPolicyResponse } from "@opengeni/sdk";
+import { type EmbeddedSessionMcpApprovalPolicyClientOverride } from "../session-context";
+import { type SessionEventFeedOptions } from "./internal";
+export declare function isSessionMcpApprovalPolicyEvent(event: Pick<SessionEvent, "type" | "payload">, serverId?: string): boolean;
+export type UseSessionMcpApprovalPolicyOptions = EmbeddedSessionMcpApprovalPolicyClientOverride & SessionEventFeedOptions & {
+    /** Optional safety-net polling (ms). Off by default; policy events drive refreshes. */
+    pollIntervalMs?: number | undefined;
+};
+export type UseSessionMcpApprovalPolicyResult = {
+    server: SessionMcpServerMetadata | null;
+    policy: SessionMcpApprovalPolicy | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    update: (policy: SessionMcpApprovalPolicy) => Promise<UpdateSessionMcpApprovalPolicyResponse | null>;
+    updating: boolean;
+    clearError: () => void;
+};
+/**
+ * Read and update one existing session MCP server's approval policy. Updates
+ * become effective for the next claimed attempt; current work is unchanged.
+ */
+export declare function useSessionMcpApprovalPolicy(sessionId: string | null | undefined, serverId: string | null | undefined, options?: UseSessionMcpApprovalPolicyOptions): UseSessionMcpApprovalPolicyResult;

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

@@ -0,0 +1,23 @@
+import type { Session, SessionEvent } from "@opengeni/sdk";
+import { type EmbeddedSessionReadClientOverride } from "../session-context";
+import { type SessionEventFeedOptions } from "./internal";
+export type UseSessionOptions = EmbeddedSessionReadClientOverride & SessionEventFeedOptions & {
+    /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
+    pollIntervalMs?: number | undefined;
+};
+export type UseSessionResult = {
+    session: Session | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** Manually rename the session (PATCH, source='user'). Returns the updated session, or null on failure. */
+    updateTitle: (title: string) => Promise<Session | null>;
+    /** True while a rename is in flight. */
+    updating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/** Event types that change the session title (auto + cross-client renames). */
+export declare function isTitleEvent(event: Pick<SessionEvent, "type">): boolean;
+/** Fetch one session (with optional polling), live-patching its title on `session.title_set`. */
+export declare function useSession(sessionId: string | null | undefined, options?: UseSessionOptions): UseSessionResult;

package/dist/hooks/use-slash-commands.d.ts

@@ -0,0 +1,66 @@
+import type { KeyboardEvent } from "react";
+import type { CommandContext, SlashCommand } from "../commands/types";
+/**
+ * Context the composer supplies for command execution and visibility. The
+ * composer owns the UI affordances (notice/openHelp/clearView/confirm), so they
+ * are NOT part of this slice — the hook closes over them via `handlers`.
+ */
+export type SlashCommandContext = Pick<CommandContext, "client" | "workspaceId" | "sessionId" | "status" | "permissions">;
+/**
+ * UI affordances the composer supplies. `confirm` differs from the registry-
+ * facing {@link CommandContext.confirm} (which takes no args): the composer's
+ * confirm receives the command being run so the confirm bar renders from that
+ * exact command's identity. The hook bridges the two in {@link buildContext}.
+ */
+export type SlashCommandHandlers = Pick<CommandContext, "notice" | "openHelp" | "clearView"> & {
+    confirm: (command: SlashCommand) => Promise<boolean>;
+};
+export type ConfirmState = {
+    command: SlashCommand;
+    /** Resolve the pending confirm() promise. */
+    resolve: (confirmed: boolean) => void;
+} | null;
+export type UseSlashCommandsOptions = {
+    commands: readonly SlashCommand[];
+    context: SlashCommandContext | undefined;
+    handlers: SlashCommandHandlers;
+    /** The current composer draft. */
+    value: string;
+    /** Replace the composer draft (autocomplete writes through this). */
+    setValue: (value: string) => void;
+};
+export type UseSlashCommandsResult = {
+    /** Whether the palette is open (a command token is being typed). */
+    open: boolean;
+    /**
+     * Whether the draft is a slash-command attempt (matches a registered command)
+     * — true even after Escape dismisses the popover. The composer blocks its send
+     * path while this holds so a command can't be delivered to the agent as chat.
+     */
+    isCommandDraft: boolean;
+    /** Commands shown for the current token + context, in display order. */
+    items: SlashCommand[];
+    /** Index into `items` of the highlighted row. */
+    highlight: number;
+    setHighlight: (index: number) => void;
+    /** The matched command once the name is closed by a space (arg-hint mode). */
+    activeCommand: SlashCommand | null;
+    /** The arg hint string for the active command (footer), or "". */
+    activeArgHint: string;
+    /**
+     * Key handler for the textarea. Returns true when it consumed the event
+     * (the composer must then NOT run its send path). Only consumes while open.
+     */
+    onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => boolean;
+    /** Run the highlighted command (or the active command in arg-hint mode). */
+    runHighlighted: () => Promise<void>;
+    /**
+     * Run the command at an explicitly chosen index (a pointer click on a row).
+     * Bypasses the exact-match token heuristic that runHighlighted uses for
+     * keyboard Enter, so an explicit click always runs the clicked command.
+     */
+    runAt: (index: number) => Promise<void>;
+    /** Autocomplete the highlighted command name + a trailing space. */
+    autocompleteHighlighted: () => void;
+};
+export declare function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult;

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

@@ -0,0 +1,46 @@
+import { TerminalCapability } from "@opengeni/sdk";
+/** The ttyd connection lifecycle as surfaced to the component. */
+export type TerminalStreamStatus = "connecting" | "open" | "closed" | "error";
+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"> | 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. */
+    onTitle?: ((title: string) => void) | undefined;
+    /** Initial PTY size to seed the ttyd auth frame + first resize. */
+    initialCols?: number | undefined;
+    initialRows?: number | undefined;
+};
+export type UseTerminalStreamResult = {
+    /** True once the ttyd socket is open (and the auth frame has been sent). */
+    connected: boolean;
+    status: TerminalStreamStatus;
+    /** Pipe a keystroke/paste to the PTY stdin. No-op until the socket is open. */
+    write: (data: string) => void;
+    /** Tell ttyd the PTY window changed size (on xterm fit/resize). */
+    resize: (cols: number, rows: number) => void;
+    /** Tear the socket down (the effect also tears down on unmount / url change). */
+    disconnect: () => void;
+};
+/**
+ * Drive a ttyd PTY-over-websocket connection from a `pty-ws` Terminal capability,
+ * symmetric with `use-desktop-stream` (the noVNC-over-tunnel hook). The scoped
+ * stream token is already embedded in the minted tunnel `url`; the WebSocket is
+ * opened with the REQUIRED ttyd subprotocol "tty".
+ *
+ * ttyd wire protocol (see `@opengeni/sdk/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.
+ *
+ * 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
+ * terminal blink, acceptable on rollover (mirrors the desktop's RFB hot-swap).
+ * SSR-safe: the socket open lives in `useEffect`, so a server render is a no-op.
+ */
+export declare function useTerminalStream(options: UseTerminalStreamOptions): UseTerminalStreamResult;

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

@@ -0,0 +1,73 @@
+import { type TranscriptionAdapter, type TranscriptionDiagnostic, type TranscriptionErrorCode, type TranscriptionEvent, type TranscriptionLifecycleStatus, type TranscriptionPolicyBlockReason, type TranscriptionTargetSelection, type WorkspaceTranscriptionPolicy } from "@opengeni/sdk";
+export type TranscriptionControlState = {
+    status: TranscriptionLifecycleStatus;
+    generation: number;
+    localSessionId: string | null;
+    providerSessionId: string | null;
+    lastSequence: number;
+    partial: string;
+    error: {
+        code: TranscriptionErrorCode;
+        recoverable: boolean;
+    } | null;
+    acceptedFinalIds: string[];
+    audioMilliseconds: number;
+    costUsd: number | null;
+};
+export declare const INITIAL_TRANSCRIPTION_CONTROL_STATE: TranscriptionControlState;
+export type TranscriptionControlAction = {
+    type: "start";
+    generation: number;
+    localSessionId: string;
+} | {
+    type: "event";
+    generation: number;
+    event: TranscriptionEvent;
+} | {
+    type: "start.failed";
+    generation: number;
+    code: TranscriptionErrorCode;
+} | {
+    type: "cancel";
+    generation: number;
+} | {
+    type: "cancel.settled";
+    generation: number;
+} | {
+    type: "reset";
+};
+export type TranscriptionControlTransition = {
+    state: TranscriptionControlState;
+    /** A newly accepted final to append to the current editable draft once. */
+    commit: string | null;
+};
+export declare function transitionTranscriptionControl(state: TranscriptionControlState, action: TranscriptionControlAction): TranscriptionControlTransition;
+export declare function appendFinalTranscript(draft: string, transcript: string): string;
+export type UseTranscriptionOptions = {
+    adapter: TranscriptionAdapter | null;
+    policy: WorkspaceTranscriptionPolicy;
+    selection?: TranscriptionTargetSelection | undefined;
+    value: string;
+    setValue: (value: string) => void;
+    focusInput: () => void;
+    disabled?: boolean | undefined;
+    createLocalSessionId?: (() => string) | undefined;
+    lifecycleTimeouts?: Partial<TranscriptionLifecycleTimeouts> | undefined;
+    /** Receives bounded, redacted diagnostics; this detail is never rendered by the hook. */
+    onDiagnostic?: ((diagnostic: TranscriptionDiagnostic) => void) | undefined;
+};
+export type TranscriptionLifecycleTimeouts = {
+    startMs: number;
+    cleanupMs: number;
+};
+export type UseTranscriptionResult = {
+    state: TranscriptionControlState;
+    available: boolean;
+    unavailableReason: TranscriptionPolicyBlockReason | "adapter_missing" | "composer_disabled" | null;
+    start: () => Promise<boolean>;
+    cancel: () => Promise<boolean>;
+    reset: () => void;
+};
+export declare function useTranscription({ adapter, policy, selection, value, setValue, focusInput, disabled, createLocalSessionId, lifecycleTimeouts, onDiagnostic, }: UseTranscriptionOptions): UseTranscriptionResult;
+export declare function normalizeTranscriptionErrorCode(code: unknown): TranscriptionErrorCode;
+export declare function sanitizeTranscriptionDiagnostic(diagnostic: unknown): TranscriptionDiagnostic;

package/dist/hooks/use-turn-queue.d.ts

@@ -0,0 +1,44 @@
+import type { ComposerDraft, EffectiveSessionControl, SessionEvent, SessionQueueSnapshot, SessionPendingInputPreview, SessionTurn } from "@opengeni/sdk";
+import { type EmbeddedSessionClientOverride } from "../session-context";
+import { type SessionEventFeedOptions } from "./internal";
+/** Events that can change the authoritative prompt queue or effective control. */
+export declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
+export type QueueMutationKind = "move" | "edit" | "steer" | "delete";
+export type UseTurnQueueOptions = EmbeddedSessionClientOverride & SessionEventFeedOptions & {
+    pollIntervalMs?: number | undefined;
+};
+export type UseTurnQueueResult = {
+    snapshot: SessionQueueSnapshot | null;
+    /** Human/API prompts exactly in server execution order. Never client-sorted. */
+    queue: SessionTurn[];
+    /** Canonical pending machine inputs. Events only trigger an authoritative refresh. */
+    pendingInputs: SessionPendingInputPreview[];
+    /** Exact pending members projected to join an already-waiting prompt. */
+    pendingInputAttachment: SessionQueueSnapshot["pendingInputAttachment"];
+    effectiveControl: EffectiveSessionControl | null;
+    /** The latest interrupted attempt has not yet durably proved physical quiescence. */
+    stoppingPreviousAttempt: boolean;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    moveTurn: (turnId: string, beforeTurnId: string | null) => Promise<boolean>;
+    /** Atomically withdraw a waiting prompt into the private durable composer draft. */
+    editTurn: (turnId: string, options: {
+        expectedDraftRevision: number;
+        replaceDraft: boolean;
+    }) => Promise<ComposerDraft | null>;
+    /** Advance the same durable waiting prompt; no duplicate prompt is created. */
+    steerTurn: (turnId: string) => Promise<boolean>;
+    removeTurn: (turnId: string) => Promise<boolean>;
+    pendingByTurn: Readonly<Record<string, QueueMutationKind>>;
+    mutationFor: (turnId: string) => QueueMutationKind | null;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * The one authoritative human prompt queue. Every mutation carries the exact
+ * server versions the operator saw and accepts only monotonic snapshots. A
+ * conflict immediately reloads server truth; the client never invents order.
+ */
+export declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;

package/dist/hooks/use-voice-input.d.ts

@@ -0,0 +1,25 @@
+import type { ClientVoiceInputConfig, OpenGeniClient } from "@opengeni/sdk";
+export type VoiceInputStatus = "idle" | "requesting-permission" | "recording" | "transcribing" | "error";
+export type UseVoiceInputOptions = {
+    client: Pick<OpenGeniClient, "transcribeAudio"> | null;
+    workspaceId: string;
+    capability: ClientVoiceInputConfig | null;
+    enabled: boolean;
+    value: string;
+    setValue: (value: string) => void;
+    focusInput: () => void;
+    disabled?: boolean | undefined;
+};
+export type UseVoiceInputResult = {
+    status: VoiceInputStatus;
+    error: string | null;
+    available: boolean;
+    /** Live mic stream while recording; null once stopped/cancelled. */
+    stream: MediaStream | null;
+    start: () => Promise<boolean>;
+    /** Stop capture and immediately upload/transcribe into the draft (no Send). */
+    stop: () => void;
+    /** Discard the in-flight recording or transcription; Escape also cancels. */
+    cancel: () => void;
+};
+export declare function useVoiceInput({ client, workspaceId, capability, enabled, value, setValue, focusInput, disabled, }: UseVoiceInputOptions): UseVoiceInputResult;

package/dist/hooks/use-windowed-sections.d.ts

@@ -0,0 +1,42 @@
+export type WindowRange = {
+    /** First mounted index (inclusive). */
+    start: number;
+    /** One past the last mounted index (exclusive). */
+    end: number;
+};
+/**
+ * Pure windowing math: given each section's height (px), the scroll offset, the
+ * viewport height, and an overscan count, return the `[start, end)` index window
+ * to mount. Robust to a zero viewport (a headless/pre-layout pass) — it then
+ * mounts a small overscan window anchored at the item under `scrollTop` rather
+ * than the whole list.
+ */
+export declare function computeWindowRange(heights: readonly number[], scrollTop: number, viewport: number, overscan: number): WindowRange;
+export type WindowedSections = {
+    /** Attach to the scroll container. */
+    scrollRef: React.RefObject<HTMLDivElement | null>;
+    /** The mounted window `[start, end)`. */
+    range: WindowRange;
+    /** Prefix offsets: `offsets[i]` is the top px of section `i`; `offsets[count]`
+     *  is the total content height. */
+    offsets: number[];
+    /** Total content height (px) — set on the spacer so scroll length is stable. */
+    totalHeight: number;
+    /** Report a MOUNTED section's real height (px) so the layout refines as async
+     *  content — e.g. Pierre's Shiki render — grows. Drive it from a ResizeObserver;
+     *  a zero/idle value is ignored so a headless pass keeps the estimate. */
+    measure: (index: number, height: number) => void;
+    /** Scroll section `index` to the top of the pane (the rail-jump). */
+    scrollToIndex: (index: number) => void;
+};
+/**
+ * Variable-height section windowing over a scroll container. Seeds every section
+ * to `estimateHeight(i)`, mounts only `range`, and refines heights from real
+ * measurements (a no-op in a zero-layout headless pass, which keeps the estimate
+ * — deterministic for tests). Pass a STABLE `estimateHeight` (wrap in useCallback).
+ */
+export declare function useWindowedSections(opts: {
+    count: number;
+    estimateHeight: (index: number) => number;
+    overscan?: number | undefined;
+}): WindowedSections;