@opengeni/react 0.48.0 → 0.57.0

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

@@ -0,0 +1,28 @@
+import { type BrowserFrame, type BrowserFrameStreamOptions, type BrowserSessionAttachment } from "@opengeni/sdk/interaction";
+import { type EmbeddedBrowserInteractionClientOverride } from "../session-context.js";
+export type BrowserFrameConnectionState = "idle" | "attaching" | "connecting" | "live" | "reconnecting" | "error";
+export type BrowserFrameWebSocket = Pick<WebSocket, "binaryType" | "readyState" | "close" | "addEventListener" | "removeEventListener"> & {
+    send(data: ArrayBuffer): void;
+};
+export type BrowserFrameWebSocketFactory = (url: string, protocols: string[]) => BrowserFrameWebSocket;
+export type UseBrowserFrameStreamOptions = EmbeddedBrowserInteractionClientOverride & {
+    browserSessionId: string | null;
+    targetId: string | null;
+    enabled?: boolean | undefined;
+    stream?: BrowserFrameStreamOptions | undefined;
+    webSocketFactory?: BrowserFrameWebSocketFactory | undefined;
+};
+export type UseBrowserFrameStreamResult = {
+    state: BrowserFrameConnectionState;
+    frame: BrowserFrame | null;
+    attachment: Pick<BrowserSessionAttachment, "browserSessionId" | "controllerGeneration" | "targetId" | "expiresAt"> | null;
+    error: Error | null;
+    reconnect: () => void;
+};
+/**
+ * Reconnecting, latest-only BrowserSession media attachment. Direct placement
+ * grants travel as a WebSocket subprotocol; connected-machine grants stay in the
+ * relay's first authenticated binary message. Neither transport puts a grant in
+ * a URL, event, log, or separately exposed React state.
+ */
+export declare function useBrowserFrameStream(options: UseBrowserFrameStreamOptions): UseBrowserFrameStreamResult;

package/dist/hooks/use-browser-identities.d.ts

@@ -0,0 +1,30 @@
+import type { BrowserIdentity, BrowserIdentityMutationResponse, BrowserRevisionListResponse, CreateBrowserIdentityRequest, PublishBrowserRevisionRequest, PublishBrowserRevisionResponse, UpdateBrowserIdentityRequest } from "@opengeni/sdk/interaction";
+import type { EmbeddedBrowserInteractionClientLike } from "../client.js";
+import { type EmbeddedBrowserInteractionClientOverride } from "../session-context.js";
+export type UseBrowserIdentitiesOptions = EmbeddedBrowserInteractionClientOverride & {
+    enabled?: boolean | undefined;
+    includeArchived?: boolean | undefined;
+};
+export type UseBrowserIdentitiesResult = {
+    revision: number;
+    identities: BrowserIdentity[];
+    loading: boolean;
+    refreshing: boolean;
+    mutating: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: Omit<CreateBrowserIdentityRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<BrowserIdentityMutationResponse>;
+    update: (identityId: string, request: Omit<UpdateBrowserIdentityRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<BrowserIdentityMutationResponse>;
+    revisions: (identityId: string) => Promise<BrowserRevisionListResponse>;
+    publish: (browserSessionId: string, request: Omit<PublishBrowserRevisionRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<PublishBrowserRevisionResponse>;
+};
+/** Workspace browser-profile library and explicit immutable-version mutations. */
+export declare function useBrowserIdentities(options?: UseBrowserIdentitiesOptions): UseBrowserIdentitiesResult;
+/** Exported for narrow proxy implementations and tests. */
+export type BrowserIdentitiesClient = EmbeddedBrowserInteractionClientLike;

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

@@ -0,0 +1,29 @@
+import type { BrowserAction, BrowserActionBatch, BrowserActionReceipt, BrowserClipboard, BrowserDiagnosticBatch, BrowserDiagnosticsOptions, BrowserFrame, BrowserObservation, BrowserSession, BrowserTarget } from "@opengeni/sdk/interaction";
+import { type EmbeddedBrowserInteractionClientOverride } from "../session-context.js";
+export type UseBrowserSessionOptions = EmbeddedBrowserInteractionClientOverride & {
+    browserSessionId: string | null;
+    enabled?: boolean | undefined;
+    pollIntervalMs?: number | undefined;
+};
+export type UseBrowserSessionResult = {
+    session: BrowserSession | null;
+    targets: BrowserTarget[];
+    selectedTarget: BrowserTarget | null;
+    observation: BrowserObservation | null;
+    loading: boolean;
+    mutating: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    selectTarget: (targetId: string) => Promise<BrowserTarget>;
+    openTarget: (url?: string) => Promise<BrowserTarget>;
+    closeTarget: (targetId: string) => Promise<void>;
+    act: (action: BrowserAction | BrowserActionBatch, operationId?: string) => Promise<BrowserActionReceipt>;
+    /** Dispatch input against the exact image a human saw. Stale images fail at
+     *  the controller fence instead of targeting a newer page. */
+    actFromFrame: (action: BrowserAction | BrowserActionBatch, frame: BrowserFrame, operationId?: string) => Promise<BrowserActionReceipt>;
+    readClipboard: () => Promise<BrowserClipboard>;
+    diagnostics: (options?: BrowserDiagnosticsOptions) => Promise<BrowserDiagnosticBatch>;
+};
+/** Selected BrowserSession control state. All human actions use the same
+ *  generation-fenced controller operation stream as agent actions. */
+export declare function useBrowserSession(options: UseBrowserSessionOptions): UseBrowserSessionResult;

package/dist/hooks/use-browser-sessions.d.ts

@@ -0,0 +1,32 @@
+import type { BrowserSession, BrowserSessionMutationResponse, CreateBrowserSessionRequest } from "@opengeni/sdk/interaction";
+import type { EmbeddedBrowserInteractionClientLike } from "../client.js";
+import { type EmbeddedBrowserInteractionClientOverride } from "../session-context.js";
+export type UseBrowserSessionsOptions = EmbeddedBrowserInteractionClientOverride & {
+    /** Current agent/session relevance. Workspace peers remain in `sessions`. */
+    sessionId?: string | undefined;
+    enabled?: boolean | undefined;
+    /** Polling fallback used only while the workspace invalidation stream is unavailable. */
+    pollIntervalMs?: number | undefined;
+};
+export type UseBrowserSessionsResult = {
+    revision: number;
+    sessions: BrowserSession[];
+    relevantSessions: BrowserSession[];
+    loading: boolean;
+    refreshing: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: Omit<CreateBrowserSessionRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<BrowserSessionMutationResponse>;
+    suspend: (browserSessionId: string, operationId?: string) => Promise<BrowserSessionMutationResponse>;
+    resume: (browserSessionId: string, operationId?: string) => Promise<BrowserSessionMutationResponse>;
+    end: (browserSessionId: string, operationId?: string) => Promise<BrowserSessionMutationResponse>;
+};
+/**
+ * Workspace-wide BrowserSession registry. Associations rank relevance but never
+ * hide peer resources; no explicit share ceremony or per-view ownership exists.
+ */
+export declare function useBrowserSessions(options?: UseBrowserSessionsOptions): UseBrowserSessionsResult;
+/** Exported for narrow proxy implementations and tests. */
+export type BrowserSessionsClient = EmbeddedBrowserInteractionClientLike;

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

@@ -0,0 +1,26 @@
+import type { Channel, CreateChannelRequest, Session, UpdateChannelRequest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider.js";
+export type UseChannelsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseChannelsResult = {
+    channels: Channel[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateChannelRequest) => Promise<Channel | null>;
+    update: (channelId: string, request: UpdateChannelRequest) => Promise<Channel | null>;
+    remove: (channelId: string) => Promise<boolean>;
+    /** Re-file a session into a channel; null moves it back to the inbox. */
+    moveSession: (sessionId: string, channelId: string | null) => Promise<Session | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * Workspace-shared channels: rail organization for root sessions
+ * ("workstreams") by work type. Pure metadata — filing a session into a
+ * channel never affects execution.
+ */
+export declare function useChannels(options?: UseChannelsOptions): UseChannelsResult;

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

@@ -1,6 +1,6 @@
 import type { CodexAccount, CodexAccountsResponse, CodexRotationSettings, SessionEvent } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
-import { type SessionEventFeedOptions } from "./internal";
+import { type ClientOverride } from "../provider.js";
+import { type SessionEventFeedOptions } from "./internal.js";
 /** Events that change which Codex account a session runs on (or just ran). */
 export declare function isCodexAccountEvent(event: Pick<SessionEvent, "type">): boolean;
 /**

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

@@ -1,8 +1,10 @@
-import { type ComposerDraft, type EffectiveControlResumeOption, type EffectiveSessionControl, type ResourceRef, type SendMessageInput, type SessionEvent } from "@opengeni/sdk";
-import { type EmbeddedSessionClientOverride } from "../session-context";
-import { type SessionEventFeedOptions } from "./internal";
-export type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
+import { type ComposerDraft, type DraftTimelineAnnotation, type EffectiveControlResumeOption, type EffectiveSessionControl, type ResourceRef, type SendMessageInput, type SessionEvent } from "@opengeni/sdk";
+import { type EmbeddedSessionClientOverride } from "../session-context.js";
+import { type SessionEventFeedOptions } from "./internal.js";
+export type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId" | "annotations">;
 export type UseComposerOptions = EmbeddedSessionClientOverride & SessionEventFeedOptions & {
+    /** Called synchronously after an ordinary Send is accepted by the local UI. */
+    onSubmitted?: ((text: string, input: SendMessageInput) => void) | undefined;
     /** Called with the exact accepted wire input after a successful send. */
     onSent?: ((text: string, input: SendMessageInput) => void) | undefined;
     /**
@@ -24,17 +26,40 @@ export type UseComposerOptions = EmbeddedSessionClientOverride & SessionEventFee
     /** Disable remote composer-draft reads and writes for embedded hosts. */
     draftPersistence?: "durable" | "disabled" | undefined;
 };
+export type ComposerOptimisticMessage = {
+    clientEventId: string;
+    text: string;
+    annotations: DraftTimelineAnnotation[];
+    resources: ResourceRef[];
+    occurredAt: string;
+    state: "sending" | "queued" | "failed";
+    error?: string | undefined;
+    outcomeUnknown?: boolean | undefined;
+};
 export type ComposerState = {
     value: string;
     setValue: (value: string) => void;
+    annotations?: DraftTimelineAnnotation[] | undefined;
+    addAnnotation?: ((annotation: DraftTimelineAnnotation) => void) | undefined;
+    updateAnnotation?: ((id: string, note: string) => void) | undefined;
+    removeAnnotation?: ((id: string) => void) | undefined;
+    /** Newly captured annotation the review surface should focus. */
+    annotationReviewTargetId?: string | null | undefined;
+    clearAnnotationReviewTarget?: (() => void) | undefined;
     /** Read the current draft synchronously before a destructive replacement. */
     hasDraftContent: () => boolean;
     /** Append the draft behind prompts already visible in the queue. */
     send: (text?: string) => Promise<boolean>;
+    /** Locally acknowledged ordinary sends awaiting durable timeline reconciliation. */
+    optimisticMessages?: ComposerOptimisticMessage[] | undefined;
+    retryOptimisticMessage?: ((clientEventId: string) => void) | undefined;
+    removeOptimisticMessage?: ((clientEventId: string) => void) | undefined;
     /** Supersede current direction with the draft. */
     steer: (text?: string) => Promise<boolean>;
     /** Optimistic-to-durable projection for a Steer that has not started yet. */
     steering?: ComposerSteeringState | null | undefined;
+    /** Immediate mutation-receipt projection while physical cancellation settles. */
+    stoppingAttempt?: "current" | "previous" | null | undefined;
     sending: boolean;
     canSend: boolean;
     /** Pause the session without deleting its prompt queue. */
@@ -65,6 +90,8 @@ export type ComposerSteeringState = {
     clientEventId: string | null;
     triggerEventId: string | null;
     turnId: string | null;
+    /** True only when the accepted Steer durably interrupted a live attempt. */
+    stoppingPreviousAttempt?: boolean | undefined;
 };
 /**
  * Draft + send + Pause/Resume state for the chat composer — the only
@@ -76,12 +103,12 @@ export declare function useComposer(sessionId: string | null | undefined, option
 /** Events that can atomically replace or clear this subject's durable draft. */
 export declare function isComposerDraftEvent(event: Pick<SessionEvent, "type">): boolean;
 /**
- * Default text for a file-only message (attachment(s) present, no typed draft).
- * Kept non-empty so the wire contract (`text: z.string().min(1)`) and the
- * worker's non-whitespace guard accept it; the attached files still ride in
- * `resources`. Exported for tests.
+ * Default text for a resource-only message (attachments present, no typed
+ * draft). Kept non-empty so the wire contract (`text: z.string().min(1)`) and
+ * the worker's non-whitespace guard accept it. The export name is retained for
+ * compatibility now that repositories can ride beside files in `resources`.
  */
-export declare const FILE_ONLY_MESSAGE_TEXT = "(see attached files)";
+export declare const FILE_ONLY_MESSAGE_TEXT = "(see attached context)";
 /** Resolve possibly-deferred extras to a concrete bag (function evaluated now). */
 export declare function resolveSendExtras(extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined): ComposerSendExtras;
 /**

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

@@ -0,0 +1,24 @@
+import { type ComputerFrame, type ComputerFrameStreamOptions, type ComputerSessionAttachment } from "@opengeni/sdk/interaction";
+import { type EmbeddedComputerInteractionClientOverride } from "../session-context.js";
+export type ComputerFrameConnectionState = "idle" | "attaching" | "connecting" | "live" | "reconnecting" | "error";
+export type ComputerFrameWebSocket = Pick<WebSocket, "binaryType" | "readyState" | "close" | "addEventListener" | "removeEventListener"> & {
+    send(data: ArrayBuffer): void;
+};
+export type ComputerFrameWebSocketFactory = (url: string, protocols: string[]) => ComputerFrameWebSocket;
+export type UseComputerFrameStreamOptions = EmbeddedComputerInteractionClientOverride & {
+    computerSessionId: string | null;
+    targetId: string | null;
+    enabled?: boolean | undefined;
+    stream?: ComputerFrameStreamOptions | undefined;
+    webSocketFactory?: ComputerFrameWebSocketFactory | undefined;
+};
+export type UseComputerFrameStreamResult = {
+    state: ComputerFrameConnectionState;
+    frame: ComputerFrame | null;
+    attachment: Pick<ComputerSessionAttachment, "computerSessionId" | "controllerGeneration" | "targetId" | "stream" | "expiresAt"> | null;
+    error: Error | null;
+    reconnect: () => void;
+};
+/** Reconnecting, latest-only ComputerSession media attachment. Grants remain in
+ * WebSocket subprotocols or the relay's authenticated first binary message. */
+export declare function useComputerFrameStream(options: UseComputerFrameStreamOptions): UseComputerFrameStreamResult;

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

@@ -0,0 +1,29 @@
+import type { ComputerAction, ComputerActionReceipt, ComputerClipboard, ComputerFrame, ComputerObservation, ComputerSession, ComputerTarget } from "@opengeni/sdk/interaction";
+import { type EmbeddedComputerInteractionClientOverride } from "../session-context.js";
+export type UseComputerSessionOptions = EmbeddedComputerInteractionClientOverride & {
+    computerSessionId: string | null;
+    enabled?: boolean | undefined;
+    pollIntervalMs?: number | undefined;
+};
+export type UseComputerSessionResult = {
+    session: ComputerSession | null;
+    targets: ComputerTarget[];
+    selectedTarget: ComputerTarget | null;
+    observation: ComputerObservation | null;
+    loading: boolean;
+    mutating: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    readClipboard: () => Promise<ComputerClipboard>;
+    /** Changes only this viewer's target cursor; it never takes ownership or
+     * foregrounds an application. */
+    selectTarget: (targetId: string) => Promise<ComputerTarget>;
+    act: (action: ComputerAction, operationId?: string) => Promise<ComputerActionReceipt>;
+    /** Dispatch pointer input against the exact displayed frame. */
+    actFromFrame: (action: Extract<ComputerAction, {
+        type: "pointer";
+    }>, frame: ComputerFrame, operationId?: string) => Promise<ComputerActionReceipt>;
+};
+/** Selected ComputerSession state. Semantic and pixel input share the same
+ * generation-fenced controller operation stream used by agents. */
+export declare function useComputerSession(options: UseComputerSessionOptions): UseComputerSessionResult;

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

@@ -0,0 +1,28 @@
+import type { ComputerSession, ComputerSessionMutationResponse, CreateComputerSessionRequest } from "@opengeni/sdk/interaction";
+import type { EmbeddedComputerInteractionClientLike } from "../client.js";
+import { type EmbeddedComputerInteractionClientOverride } from "../session-context.js";
+export type UseComputerSessionsOptions = EmbeddedComputerInteractionClientOverride & {
+    /** Current agent/session relevance. Workspace peers remain in `sessions`. */
+    sessionId?: string | undefined;
+    enabled?: boolean | undefined;
+    /** Polling fallback used only while the workspace invalidation stream is unavailable. */
+    pollIntervalMs?: number | undefined;
+};
+export type UseComputerSessionsResult = {
+    revision: number;
+    sessions: ComputerSession[];
+    relevantSessions: ComputerSession[];
+    loading: boolean;
+    refreshing: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: Omit<CreateComputerSessionRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<ComputerSessionMutationResponse>;
+    end: (computerSessionId: string, operationId?: string) => Promise<ComputerSessionMutationResponse>;
+};
+/** Workspace-wide ComputerSession registry. Associations rank relevance but
+ * never hide peer resources or create an ownership boundary. */
+export declare function useComputerSessions(options?: UseComputerSessionsOptions): UseComputerSessionsResult;
+/** Exported for narrow proxy implementations and tests. */
+export type ComputerSessionsClient = EmbeddedComputerInteractionClientLike;

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

@@ -1,6 +1,6 @@
 import { type DesktopConnectionState, type DesktopRfbFactory, type DesktopStreamCapability } from "@opengeni/sdk";
 import { type RefObject } from "react";
-import { type DesktopWebSocketFactory } from "./use-relay-frame-stream";
+import { type DesktopWebSocketFactory } from "./use-relay-frame-stream.js";
 export type UseDesktopStreamOptions = {
     /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
     capability: DesktopStreamCapability | null;
@@ -11,6 +11,8 @@ export type UseDesktopStreamOptions = {
     scaleViewport?: boolean | undefined;
     /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
     rfbFactory?: DesktopRfbFactory | undefined;
+    /** Additional WebSocket protocols for an authenticated placement proxy. */
+    webSocketProtocols?: string[] | undefined;
     /** Custom socket factory for the `relay-frames` transport (tests). Defaults to
      *  `new WebSocket(url)`. Mirrors `rfbFactory` for the frame renderer. */
     webSocketFactory?: DesktopWebSocketFactory | undefined;
@@ -20,6 +22,8 @@ export type UseDesktopStreamResult = {
     error: Error | null;
     /** Manual reconnect (e.g. after a securityfailure once a fresh URL arrives). */
     reconnect: () => void;
+    /** Synchronous input on the already-open RFB authority. */
+    sendKey?: ((keysym: number, code: string, down?: boolean) => boolean) | undefined;
 };
 /**
  * Drive the noVNC RFB lifecycle from a `DesktopStreamCapability`, using the

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

@@ -1,5 +1,5 @@
 import type { CreateVariableSetRequest, UpdateVariableSetRequest, VariableSet, VariableSetSecret, VariableSetVariableMetadata } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import { type ClientOverride } from "../provider.js";
 export type UseVariableSetsOptions = ClientOverride & {
     pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;

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

@@ -1,5 +1,5 @@
 import type { FileAsset, FileResourceRef } from "@opengeni/sdk";
-import { type EmbeddedFileAttachmentClientOverride } from "../session-context";
+import { type EmbeddedFileAttachmentClientOverride } from "../session-context.js";
 export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
     /**
      * Only files matching this predicate are accepted by {@link

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

@@ -1,6 +1,6 @@
 import { type SessionEvent, type SessionGoal } from "@opengeni/sdk";
-import { type EmbeddedGoalClientOverride } from "../session-context";
-import { type SessionEventFeedOptions } from "./internal";
+import { type EmbeddedGoalClientOverride } from "../session-context.js";
+import { type SessionEventFeedOptions } from "./internal.js";
 /** Event types that change the session goal (set/updated/completed/paused/...). */
 export declare function isGoalEvent(event: Pick<SessionEvent, "type">): boolean;
 /**

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

@@ -1,6 +1,6 @@
 import type { SessionEvent, SessionHumanInputRequest, SubmitHumanInputResponseRequest } from "@opengeni/sdk";
-import { type EmbeddedHumanInputClientOverride } from "../session-context";
-import { type SessionEventFeedOptions } from "./internal";
+import { type EmbeddedHumanInputClientOverride } from "../session-context.js";
+import { type SessionEventFeedOptions } from "./internal.js";
 /** Events that can create, settle, or invalidate an actionable request. */
 export declare function isHumanInputEvent(event: Pick<SessionEvent, "type">): boolean;
 export type UseHumanInputRequestsOptions = EmbeddedHumanInputClientOverride & SessionEventFeedOptions & {

package/dist/hooks/use-interaction-interventions.d.ts

@@ -0,0 +1,27 @@
+import type { CreateInteractionInterventionRequest, InteractionIntervention, InteractionInterventionMutationResponse, ResolveInteractionInterventionRequest } from "@opengeni/sdk/interaction";
+import type { EmbeddedInterventionClientLike } from "../client.js";
+import { type EmbeddedInterventionClientOverride } from "../session-context.js";
+export type UseInteractionInterventionsOptions = EmbeddedInterventionClientOverride & {
+    enabled?: boolean | undefined;
+    resourceKind?: "browser_session" | "computer_session" | undefined;
+    resourceId?: string | null | undefined;
+    includeSettled?: boolean | undefined;
+    pollIntervalMs?: number | undefined;
+};
+export type UseInteractionInterventionsResult = {
+    interventions: InteractionIntervention[];
+    loading: boolean;
+    refreshing: boolean;
+    mutating: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: Omit<CreateInteractionInterventionRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<InteractionInterventionMutationResponse>;
+    resolve: (interventionId: string, request: Omit<ResolveInteractionInterventionRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<InteractionInterventionMutationResponse>;
+};
+/** Human-action bridge shared by Browser and Computer surfaces. */
+export declare function useInteractionInterventions(options?: UseInteractionInterventionsOptions): UseInteractionInterventionsResult;
+export type InteractionInterventionsClient = EmbeddedInterventionClientLike;

package/dist/hooks/use-interaction-invalidation.d.ts

@@ -0,0 +1,19 @@
+import type { StreamConnectionState, WorkspaceInteractionRevisionEvent } from "@opengeni/sdk";
+export type InteractionInvalidationOptions = {
+    workspaceId: string;
+    /** Distinguishes filtered projections of the same workspace catalog. */
+    key: string;
+    enabled: boolean;
+    event: WorkspaceInteractionRevisionEvent | null;
+    connectionState: StreamConnectionState | "idle" | "error";
+    /** Catalog responses carry the workspace revision; live-state lists do not. */
+    knownRevision?: number | undefined;
+    refresh: () => Promise<void>;
+    fallbackPollIntervalMs?: number | undefined;
+};
+/**
+ * Refetch authoritative lists on the shared latest-revision stream. Poll only
+ * while that stream is unavailable, preserving standalone-hook degradation
+ * without multiplying healthy-provider traffic.
+ */
+export declare function useInteractionInvalidation(options: InteractionInvalidationOptions): void;

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

@@ -1,6 +1,6 @@
 import type { LatencyMode, ReasoningEffort, SessionEvent } from "@opengeni/sdk";
-import { type ClientOverride } from "../session-context";
-import { type SessionEventFeedOptions } from "./internal";
+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. */
 export declare function isLastStartedTurnPolicyEvent(event: Pick<SessionEvent, "type">): boolean;
 export type LastStartedTurnPolicy = {

package/dist/hooks/use-machine-chip.d.ts

@@ -1,5 +1,5 @@
 import type { MachineState } from "@opengeni/sdk";
-import type { SessionCapabilitiesState } from "./use-session-capabilities";
+import type { SessionCapabilitiesState } from "./use-session-capabilities.js";
 /** The one truthful machine indicator. Honest staleness beats
  *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
 export type MachineChipState = "live" | "waking" | "offline";
@@ -36,7 +36,7 @@ export declare function formatAsOf(capturedAt: string, now: number): string;
  * it; the whole point is a deterministic, testable projection).
  *
  * Precedence:
- *   1. warm/draining lease → **live** (a warm box always wins).
+ *   1. warm lease → **live** (a holder-confirmed box always wins).
  *   2. actively warming (negotiating, wake-on-edit, or a reconnecting/enrolling
  *      machine) → **waking**.
  *   3. everything else (a cold/asleep box, a self-hosted machine that's offline,

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

@@ -1,6 +1,6 @@
-import type { RemoveEnrollmentRequest, RemoveEnrollmentResponse } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
-import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
+import type { RemoveEnrollmentRequest, RemoveEnrollmentResponse, SwapActiveSandboxResponse } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider.js";
+import type { MachinesResponse, MachineView, MetricSample } from "../types/machines.js";
 /**
  * The slice of the SDK client the Machines surface needs. The method NAMES +
  * SIGNATURES match M10's `OpenGeniClient` (`listMachines`, `machineMetricsSeries`)
@@ -35,7 +35,7 @@ export type MachinesClientLike = {
      */
     swapActiveSandbox?: (workspaceId: string, sessionId: string, request: {
         target: string;
-    }) => Promise<unknown>;
+    }) => Promise<SwapActiveSandboxResponse>;
     /**
      * Host-supplied swap adapter (an escape hatch). When present it wins over the
      * default `swapActiveSandbox` path. Session-scoped, like the swap it backs.

package/dist/hooks/use-network-routes.d.ts

@@ -0,0 +1,25 @@
+import type { CreateNetworkRouteRequest, NetworkRoute, NetworkRouteMutationResponse, UpdateNetworkRouteRequest } from "@opengeni/sdk/interaction";
+import type { EmbeddedBrowserInteractionClientLike } from "../client.js";
+import { type EmbeddedBrowserInteractionClientOverride } from "../session-context.js";
+export type UseNetworkRoutesOptions = EmbeddedBrowserInteractionClientOverride & {
+    enabled?: boolean | undefined;
+    includeArchived?: boolean | undefined;
+};
+export type UseNetworkRoutesResult = {
+    revision: number;
+    routes: NetworkRoute[];
+    loading: boolean;
+    refreshing: boolean;
+    mutating: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: Omit<CreateNetworkRouteRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<NetworkRouteMutationResponse>;
+    update: (networkRouteId: string, request: Omit<UpdateNetworkRouteRequest, "operationId"> & {
+        operationId?: string;
+    }) => Promise<NetworkRouteMutationResponse>;
+};
+/** Workspace network-route registry. Route mutations never expose brokered credentials. */
+export declare function useNetworkRoutes(options?: UseNetworkRoutesOptions): UseNetworkRoutesResult;
+export type NetworkRoutesClient = EmbeddedBrowserInteractionClientLike;

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

@@ -1,5 +1,5 @@
-import type { CapabilityPack, EnablePackRequest, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import type { CapabilityPack, EnablePackRequest, InstallPackRequest, PackInstallationPreview, PackInstallation, PackUninstallPreview, PreviewPackInstallationRequest, RegisterCapabilityPackRequest, UninstallPackRequest, UninstallPackResult, WorkspaceRegisteredPack } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider.js";
 export type UsePacksOptions = ClientOverride & {
     pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;
@@ -16,7 +16,12 @@ export type UsePacksResult = {
     refresh: () => Promise<void>;
     /** Register (or replace) a workspace-scoped pack manifest. */
     register: (manifest: RegisterCapabilityPackRequest) => Promise<WorkspaceRegisteredPack | null>;
+    /** @deprecated Use previewInstallation + install for component/Rig-aware Packs. */
     enable: (packId: string, request?: EnablePackRequest) => Promise<PackInstallation | null>;
+    previewInstallation: (packId: string, request?: PreviewPackInstallationRequest) => Promise<PackInstallationPreview | null>;
+    install: (packId: string, request: InstallPackRequest) => Promise<PackInstallation | null>;
+    previewUninstall: (packId: string) => Promise<PackUninstallPreview | null>;
+    uninstall: (packId: string, request: UninstallPackRequest) => Promise<UninstallPackResult | null>;
     /** Unregister a workspace-scoped pack (built-ins cannot be removed). */
     remove: (packId: string) => Promise<boolean>;
     mutating: boolean;

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

@@ -1,5 +1,5 @@
 import type { CreateRigRequest, ProposeRigChangeRequest, Rig, RigChange, RigVersion, UpdateRigRequest } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import { type ClientOverride } from "../provider.js";
 export type UseRigsOptions = ClientOverride & {
     pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;

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

@@ -1,5 +1,5 @@
-import type { FsReadResponse, FsWriteResponse, OpenGeniRequestOptions, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import type { 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";
 export type CapturedFileUnavailableReason = "not-captured" | "too-large" | "content-missing";
@@ -52,12 +52,14 @@ export type UseSandboxFilesOptions = ClientOverride & {
     active?: boolean | undefined;
     /** Repository roots advertised by capabilities, relative to the workspace. */
     repoPaths?: readonly string[] | undefined;
-    /** The lease liveness ("cold" | "warm" | "draining"). The structured FileSystem
+    /** The lease liveness. `null` means capability negotiation has not produced
+     *  an authoritative lifecycle value yet and therefore blocks live I/O. Omitting
+     *  the option preserves the legacy direct-hook behavior. The structured FileSystem
      *  capability is advertised even on a COLD box, so the mount-time list can race
      *  the box: it lists before the box is warm, gets an empty/errored result, and
      *  (with no `fs.changed` event) never re-lists. Passing liveness re-lists when
      *  the box first becomes warm, so the tree populates as soon as the box is up. */
-    liveness?: string | undefined;
+    liveness?: SessionCapabilities["liveness"] | null | undefined;
     /** The latest turn-end workspace capture (from `useWorkspaceCapture`). The tree
      *  paints immediately from this durable index, then a warm box reconciles live
      *  in place. If that live read fails, the capture remains a truthful read-only

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

@@ -1,5 +1,5 @@
-import type { GitFileDiff, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import type { GitFileDiff, SessionCapabilities, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider.js";
 export type UseSandboxGitOptions = ClientOverride & {
     /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
      *  on `git.changed`. */
@@ -19,9 +19,10 @@ export type UseSandboxGitOptions = ClientOverride & {
     enabled?: boolean | undefined;
     /** Pause live reads/invalidation while preserving the last rendered result. */
     active?: boolean | undefined;
-    /** Lease liveness ("warm" | "draining" | "cold"). When NOT warm, the diff is
-     *  served from the capture (cold/offline) instead of a live `gitDiff` RPC. */
-    liveness?: string | undefined;
+    /** Lease liveness. `null` means capability negotiation is still pending and
+     *  blocks live I/O. When not warm, the diff is served from the capture instead
+     *  of a live `gitDiff` RPC. Omission preserves legacy direct-hook behavior. */
+    liveness?: SessionCapabilities["liveness"] | null | undefined;
     /** The latest turn-end capture (from `useWorkspaceCapture`). Seeds the diff
      *  immediately; a warm box reconciles live and leaves this durable review
      *  surface in place if the live request is temporarily unavailable. */

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

@@ -1,5 +1,5 @@
 import type { SessionEvent } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import { type ClientOverride } from "../provider.js";
 export type TerminalChunk = {
     /** Stable key (the source event id) so the xterm writer tracks a written-cursor. */
     id: string;

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

@@ -1,5 +1,5 @@
 import type { ScheduledTask } from "@opengeni/sdk";
-import { type ClientOverride } from "../provider";
+import { type ClientOverride } from "../provider.js";
 export type UseScheduledTasksOptions = ClientOverride & {
     limit?: number | undefined;
     pollIntervalMs?: number | undefined;