@opengeni/react 0.28.2 → 0.32.1

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

@@ -0,0 +1,35 @@
+import type { CreateVariableSetRequest, UpdateVariableSetRequest, VariableSet, VariableSetVariableMetadata } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseVariableSetsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseVariableSetsResult = {
+    variableSets: VariableSet[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateVariableSetRequest) => Promise<VariableSet | null>;
+    update: (variableSetId: string, request: UpdateVariableSetRequest) => Promise<VariableSet | null>;
+    remove: (variableSetId: string) => Promise<boolean>;
+    /** Set/rotate a variable. Values are write-only — reads expose metadata only. */
+    setVariable: (variableSetId: string, name: string, value: string) => Promise<VariableSetVariableMetadata | null>;
+    deleteVariable: (variableSetId: string, name: string) => Promise<boolean>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * Variable sets (named, encrypted variable sets attached to sessions
+ * and scheduled tasks). Variable values are write-only end to end: this hook
+ * never sees a value after it is sent.
+ */
+export declare function useVariableSets(options?: UseVariableSetsOptions): UseVariableSetsResult;
+/** @deprecated use UseVariableSetsOptions */
+export type UseEnvironmentsOptions = UseVariableSetsOptions;
+/** @deprecated use UseVariableSetsResult */
+export type UseEnvironmentsResult = UseVariableSetsResult & {
+    environments: VariableSet[];
+};
+/** @deprecated use useVariableSets */
+export declare function useEnvironments(options?: UseEnvironmentsOptions): UseEnvironmentsResult;

package/dist/{use-file-attachments-BmT8WtqO.d.ts → hooks/use-file-attachments.d.ts}

@@ -1,7 +1,6 @@
-import { FileAsset, FileResourceRef } from '@opengeni/sdk';
-import { E as EmbeddedFileAttachmentClientOverride } from './session-context-CAjlaeZb.js';
-
-type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
+import type { FileAsset, FileResourceRef } from "@opengeni/sdk";
+import { type EmbeddedFileAttachmentClientOverride } from "../session-context";
+export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
     /**
      * Only files matching this predicate are accepted by {@link
      * UseFileAttachmentsResult.addFromPaste} (the clipboard path). Defaults to
@@ -11,7 +10,7 @@ type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
      */
     pasteFilter?: ((file: File) => boolean) | undefined;
 };
-type FileAttachment = {
+export type FileAttachment = {
     id: string;
     name: string;
     contentType: string;
@@ -23,7 +22,7 @@ type FileAttachment = {
     previewUrl?: string | undefined;
     error?: string | undefined;
 };
-type UseFileAttachmentsResult = {
+export type UseFileAttachmentsResult = {
     attachments: FileAttachment[];
     /**
      * `FileResourceRef[]` for every attachment that finished uploading — feed
@@ -71,6 +70,4 @@ type UseFileAttachmentsResult = {
  * `resources`. Workspace-scoped, so it resolves both client and workspace from
  * the {@link OpenGeniProvider} (or a per-call `{ client, workspaceId }`).
  */
-declare function useFileAttachments(options?: UseFileAttachmentsOptions): UseFileAttachmentsResult;
-
-export { type FileAttachment as F, type UseFileAttachmentsResult as U, type UseFileAttachmentsOptions as a, useFileAttachments as u };
+export declare function useFileAttachments(options?: UseFileAttachmentsOptions): UseFileAttachmentsResult;

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

@@ -0,0 +1,46 @@
+import { type SessionEvent, type SessionGoal } from "@opengeni/sdk";
+import { type EmbeddedGoalClientOverride } from "../session-context";
+import { type SessionEventFeedOptions } from "./internal";
+/** Event types that change the session goal (set/updated/completed/paused/...). */
+export declare function isGoalEvent(event: Pick<SessionEvent, "type">): boolean;
+/**
+ * Events that can change the server-authoritative continuation projection.
+ * The projection is derived from durable turn, session, control, and system
+ * update state, so those events refresh the goal without model polling.
+ */
+export declare function isGoalRefreshEvent(event: Pick<SessionEvent, "type">): boolean;
+export type UseGoalOptions = EmbeddedGoalClientOverride & SessionEventFeedOptions & {
+    /** Optional safety-net polling (ms). Off by default — event refreshes drive updates. */
+    pollIntervalMs?: number | undefined;
+};
+export type UseGoalResult = {
+    /** The session goal, or null when the session has none. */
+    goal: SessionGoal | null;
+    /** Convenience flags over `goal.status`. */
+    isActive: boolean;
+    isPaused: boolean;
+    isCompleted: boolean;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** Pause the goal loop (PATCH status=paused). */
+    pause: (rationale?: string) => Promise<SessionGoal | null>;
+    /** Resume a paused goal: resets counters and re-arms continuations. */
+    resume: () => Promise<SessionGoal | null>;
+    /** Clear the session goal; goal-less sessions remain a successful no-op. */
+    clearGoal: () => Promise<void>;
+    /** Alias for `clearGoal`. */
+    deleteGoal: () => Promise<void>;
+    /** True while a pause/resume/clear is in flight. */
+    updating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * 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,
+ * control, and system-update events — pass `options.events` from
+ * `useSessionEvents` to reuse its stream.
+ */
+export declare function useGoal(sessionId: string | null | undefined, options?: UseGoalOptions): UseGoalResult;

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

@@ -0,0 +1,26 @@
+import type { SessionEvent, SessionHumanInputRequest, SubmitHumanInputResponseRequest } from "@opengeni/sdk";
+import { type EmbeddedHumanInputClientOverride } from "../session-context";
+import { type SessionEventFeedOptions } from "./internal";
+/** Events that can create, settle, or invalidate an actionable request. */
+export declare function isHumanInputEvent(event: Pick<SessionEvent, "type">): boolean;
+export type UseHumanInputRequestsOptions = EmbeddedHumanInputClientOverride & SessionEventFeedOptions & {
+    /** Optional safety-net polling. Durable events drive refresh by default. */
+    pollIntervalMs?: number | undefined;
+};
+export type UseHumanInputRequestsResult = {
+    requests: SessionHumanInputRequest[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    respond: (requestId: string, response: SubmitHumanInputResponseRequest) => Promise<SessionEvent | null>;
+    respondingRequestId: string | null;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * Authoritative structured-human-input hook. The server's pending-request
+ * table is the read model; events only trigger reconciliation. This lets an
+ * embedded host use the same primitive with a shared event feed or its own SDK
+ * proxy without rebuilding request lifecycle logic.
+ */
+export declare function useHumanInputRequests(sessionId: string | null | undefined, options?: UseHumanInputRequestsOptions): UseHumanInputRequestsResult;

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

@@ -0,0 +1,27 @@
+import type { LatencyMode, ReasoningEffort, SessionEvent } from "@opengeni/sdk";
+import { type ClientOverride } from "../session-context";
+import { type SessionEventFeedOptions } from "./internal";
+/** 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 = {
+    model: string;
+    reasoningEffort: ReasoningEffort;
+    latencyMode: LatencyMode;
+    turnId: string;
+};
+export type UseLastStartedTurnPolicyOptions = ClientOverride & SessionEventFeedOptions & {
+    pollIntervalMs?: number | undefined;
+};
+export type UseLastStartedTurnPolicyResult = {
+    /** Null until some turn has durably emitted `turn.started`. */
+    policy: LastStartedTurnPolicy | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Model·effort·latency of the newest admitted turn (`turn.started`). This is
+ * historical runtime truth for the session header — not the composer next-turn
+ * picker and not the frozen session creation defaults.
+ */
+export declare function useLastStartedTurnPolicy(sessionId: string | null | undefined, options?: UseLastStartedTurnPolicyOptions): UseLastStartedTurnPolicyResult;

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

@@ -0,0 +1,54 @@
+import type { MachineState } from "@opengeni/sdk";
+import type { SessionCapabilitiesState } from "./use-session-capabilities";
+/** 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";
+export type MachineChip = {
+    state: MachineChipState;
+    /** A ready-to-render label ("Live" / "Waking…" / "Offline — as of 3m ago"). */
+    label: string;
+    /** The capture time backing an offline/stale label (ISO), or null. M4 may
+     *  reformat this; `label` already embeds a relative form. */
+    asOf: string | null;
+};
+export type DeriveMachineChipInput = {
+    /** `capabilities.liveness` — "warm" | "draining" | "cold" (or null pre-negotiation). */
+    liveness?: string | null | undefined;
+    /** `useSessionCapabilities().state` — drives the "waking" (negotiating) read. */
+    capabilitiesState?: SessionCapabilitiesState | null | undefined;
+    /** The ACTIVE machine's connection state (from `useMachines`), when known. A
+     *  self-hosted machine that is `offline` cannot be remotely woken. */
+    activeMachineState?: MachineState | null | undefined;
+    /** Whether the active sandbox is a user-owned self-hosted machine (no remote wake). */
+    activeIsSelfhosted?: boolean | undefined;
+    /** An interaction (wake-on-edit, terminal focus) is actively warming the box. */
+    wantsWarm?: boolean | undefined;
+    /** The latest capture's `capturedAt` (ISO) — the "as of <time>" backing. */
+    capturedAt?: string | null | undefined;
+    /** Injectable clock for deterministic relative labels (defaults to Date.now). */
+    now?: number | undefined;
+};
+/** Compact relative-time for the "as of" label. Pure, no Intl dependency. */
+export declare function formatAsOf(capturedAt: string, now: number): string;
+/**
+ * Derive the machine-state chip from the live capability/liveness surface, the
+ * active machine's connection state, and the latest capture time. PURE (M4 renders
+ * it; the whole point is a deterministic, testable projection).
+ *
+ * Precedence:
+ *   1. warm/draining lease → **live** (a warm 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,
+ *      an error) → **offline**, labelled "as of <capture time>".
+ */
+export declare function deriveMachineChip(input: DeriveMachineChipInput): MachineChip;
+export type UseMachineChipOptions = DeriveMachineChipInput;
+/**
+ * Thin memoized wrapper over `deriveMachineChip` for the dock header (M4). The
+ * dock already runs `useSessionCapabilities` + `useMachines` + `useWorkspace
+ * capture`; it feeds their `liveness` / `state` / active-machine state /
+ * `capturedAt` here. Pass a periodically-updated `now` if you want the relative
+ * "as of" label to tick.
+ */
+export declare function useMachineChip(input: UseMachineChipOptions): MachineChip;

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

@@ -0,0 +1,81 @@
+import { type ClientOverride } from "../provider";
+import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
+/**
+ * The slice of the SDK client the Machines surface needs. The method NAMES +
+ * SIGNATURES match M10's `OpenGeniClient` (`listMachines`, `machineMetricsSeries`)
+ * so the real SDK client satisfies this surface DIRECTLY for the read paths — no
+ * adapter needed. It is declared structurally (not a hard `OpenGeniClient` Pick)
+ * so a test/demo/Geni-frontend client can stand in, keeping the hook dual-consumer
+ * safe (works in apps/web AND the separate Geni frontend).
+ *
+ * The active-sandbox SWAP is now a typed SDK call (`swapActiveSandbox`, the M7
+ * user-authenticated REST equivalent of the `sandbox_swap` MCP tool). The real
+ * SDK client satisfies it structurally, so the default attach path is wired
+ * WHENEVER a sessionId is in scope (the swap is session-scoped). `attachMachine`
+ * stays an OPTIONAL escape hatch for a host that wants to supply its own swap
+ * adapter; when neither it nor a sessionId is present, attach is a no-op and the
+ * card hides the button.
+ */
+export type MachinesClientLike = {
+    /** GET /v1/workspaces/:ws/machines — the dashboard list + active pointer. */
+    listMachines: (workspaceId: string, options?: {
+        sessionId?: string;
+        signal?: AbortSignal;
+    }) => Promise<MachinesResponse>;
+    /** GET .../machines/:enrollmentId/metrics/series — the downsampled history. */
+    machineMetricsSeries?: (workspaceId: string, enrollmentId: string, options?: {
+        window?: "15m" | "1h" | "6h" | "24h";
+    }) => Promise<MetricSample[]>;
+    /**
+     * POST .../sessions/:sessionId/active-sandbox — swap the session's active
+     * sandbox to a machine. The default swap path; the real SDK client provides it.
+     */
+    swapActiveSandbox?: (workspaceId: string, sessionId: string, request: {
+        target: string;
+    }) => Promise<unknown>;
+    /**
+     * Host-supplied swap adapter (an escape hatch). When present it wins over the
+     * default `swapActiveSandbox` path. Session-scoped, like the swap it backs.
+     */
+    attachMachine?: (workspaceId: string, sessionId: string, sandboxId: string) => Promise<unknown>;
+};
+export type UseMachinesOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+    /** Scope the list to a session (adds the synthetic Modal group box + pointer). */
+    sessionId?: string | undefined;
+    /**
+     * Override the client with one implementing `MachinesClientLike`. Defaults to
+     * the provider client cast to the surface (the real SDK client satisfies the
+     * read paths). An app supplies an adapter to wire `attachMachine` (the swap).
+     */
+    machinesClient?: MachinesClientLike | undefined;
+};
+export type UseMachinesResult = {
+    machines: MachineView[];
+    activeSandboxId: string | null;
+    activeEpoch: number;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** Attach/swap the session's active sandbox to a machine (returns the new pointer). */
+    attach: (sandboxId: string) => Promise<boolean>;
+    /** Whether the host wired an attach/swap path (drives the card affordance). */
+    canAttach: boolean;
+    /** Fetch a downsampled metric series for one enrolled machine. */
+    fetchSeries: (enrollmentId: string, window?: "15m" | "1h" | "6h" | "24h") => Promise<MetricSample[]>;
+    attaching: boolean;
+    /** The sandbox id of the in-flight attach (for per-card spinner gating). */
+    attachingSandboxId: string | null;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * The workspace Machines fleet: the selfhosted enrollments + the session's Modal
+ * box, each with latest metrics + state, plus the active-sandbox pointer. Polls
+ * the M10 `GET /machines` endpoint and exposes attach/swap + a metric-series
+ * fetch. Renders via `<MachinesDashboard>`. Dual-consumer safe: it reads only the
+ * structural `MachinesClientLike` surface, so it works in apps/web AND the Geni
+ * frontend (each provides its own client/adapter).
+ */
+export declare function useMachines(options?: UseMachinesOptions): UseMachinesResult;

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

@@ -0,0 +1,27 @@
+import type { CapabilityPack, EnablePackRequest, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UsePacksOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UsePacksResult = {
+    /** Built-in + registered packs available to the workspace. */
+    packs: CapabilityPack[];
+    /** Enable/disable state per pack. */
+    installations: PackInstallation[];
+    /** The installation for a pack id, if any. */
+    installationFor: (packId: string) => PackInstallation | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** Register (or replace) a workspace-scoped pack manifest. */
+    register: (manifest: RegisterCapabilityPackRequest) => Promise<WorkspaceRegisteredPack | null>;
+    enable: (packId: string, request?: EnablePackRequest) => Promise<PackInstallation | null>;
+    /** Unregister a workspace-scoped pack (built-ins cannot be removed). */
+    remove: (packId: string) => Promise<boolean>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/** Capability packs: catalog + installations + register/enable/unregister. */
+export declare function usePacks(options?: UsePacksOptions): UsePacksResult;

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

@@ -0,0 +1,53 @@
+import type { DesktopConnectionState, DesktopStreamCapability } from "@opengeni/sdk";
+import { type RefObject } from "react";
+/**
+ * The minimal WebSocket surface the frame renderer drives. Lets tests (and a
+ * future transport swap) inject a fake without a live socket — the exact
+ * analogue of `DesktopRfbFactory` for the noVNC path. Structurally a subset of
+ * the browser `WebSocket`.
+ */
+export interface DesktopWebSocketLike {
+    binaryType: string;
+    send(data: ArrayBuffer): void;
+    close(): void;
+    addEventListener(type: "open" | "message" | "error" | "close", listener: (ev: {
+        data?: unknown;
+    } & Record<string, unknown>) => void): void;
+    removeEventListener(type: "open" | "message" | "error" | "close", listener: (ev: {
+        data?: unknown;
+    } & Record<string, unknown>) => void): void;
+}
+export type DesktopWebSocketFactory = (url: string) => DesktopWebSocketLike;
+export type UseRelayFrameStreamOptions = {
+    /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
+    capability: DesktopStreamCapability | null;
+    /** The mount target. A `<canvas>` is appended here on connect. */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Custom socket factory (tests / a transport swap). Defaults to `new WebSocket(url)`. */
+    webSocketFactory?: DesktopWebSocketFactory | undefined;
+};
+export type UseRelayFrameStreamResult = {
+    state: DesktopConnectionState;
+    error: Error | null;
+    /** Tear down + reopen the socket (e.g. after a drop, once a fresh url arrives). */
+    reconnect: () => void;
+};
+/**
+ * VIEW-ONLY PNG-frame renderer for a SELF-HOSTED desktop stream — the relay
+ * transport (`transport: "relay-frames"`, `client: "frames"`). The self-hosted
+ * agent produces one PNG per frame as a protobuf datagram over the relay; there
+ * is no RFB/noVNC here. This hook opens the relay DESKTOP channel as a CLIENT
+ * (mirroring the proven diagnostic wire protocol), decodes each PNG onto a
+ * `<canvas>` mounted into `containerRef`, and drives the connection state
+ * machine: idle → connecting (ws opening) → connected (first painted frame) →
+ * error (ws error/close/ack rejection).
+ *
+ * It is DORMANT for any other transport (or no url): it stays idle and touches
+ * nothing, so the noVNC path owns the surface. SSR-safe: the socket + DOM attach
+ * live inside `useEffect`.
+ *
+ * Backpressure (critical — frames are ~1.8MB at ~10fps): at most one frame is
+ * decoded at a time; a frame arriving mid-decode replaces the pending one
+ * (latest-wins), so a slow decode can never build an unbounded queue.
+ */
+export declare function useRelayFrameStream(options: UseRelayFrameStreamOptions): UseRelayFrameStreamResult;

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

@@ -0,0 +1,87 @@
+import type { CreateRigRequest, ProposeRigChangeRequest, Rig, RigChange, RigVersion, UpdateRigRequest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseRigsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseRigsResult = {
+    rigs: Rig[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateRigRequest) => Promise<Rig | null>;
+    update: (rigId: string, request: UpdateRigRequest) => Promise<Rig | null>;
+    remove: (rigId: string) => Promise<boolean>;
+    listVersions: (rigId: string) => Promise<RigVersion[] | null>;
+    activateVersion: (rigId: string, versionId: string) => Promise<RigVersion | null>;
+    listChanges: (rigId: string) => Promise<RigChange[] | null>;
+    proposeChange: (rigId: string, request: ProposeRigChangeRequest) => Promise<RigChange | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * Rigs (workspace-scoped, versioned sandbox machine definitions). The list
+ * polls; version/change reads are on-demand (they are per-rig detail, not part
+ * of the list surface).
+ */
+export declare function useRigs(options?: UseRigsOptions): UseRigsResult;
+export type UseRigOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseRigResult = {
+    rig: Rig | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    update: (request: UpdateRigRequest) => Promise<Rig | null>;
+    remove: () => Promise<boolean>;
+    activateVersion: (versionId: string) => Promise<RigVersion | null>;
+    proposeChange: (request: ProposeRigChangeRequest) => Promise<RigChange | null>;
+    /** Re-run verification for a change (asynchronous — poll for the outcome). */
+    verifyChange: (changeId: string) => Promise<RigChange | null>;
+    /** Promote a verified definition_edit into a new active version (rigs:manage). */
+    promoteChange: (changeId: string) => Promise<RigVersion | null>;
+    /** Re-verify the active version's checks in a clean throwaway sandbox. */
+    verify: () => Promise<{
+        ok: boolean;
+        versionId: string;
+    } | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * A single rig (its active version + counts), polled so verification and
+ * promotion state stay live. Owns the rig's write actions; the versions and
+ * changes lists are separate polled reads (`useRigVersions`/`useRigChanges`).
+ */
+export declare function useRig(rigId: string, options?: UseRigOptions): UseRigResult;
+export type UseRigVersionsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseRigVersionsResult = {
+    versions: RigVersion[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** A rig's append-only version history, newest-first (polled). */
+export declare function useRigVersions(rigId: string, options?: UseRigVersionsOptions): UseRigVersionsResult;
+export type UseRigChangesOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+export type UseRigChangesResult = {
+    changes: RigChange[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * A rig's change queue (polled). The default poll cadence lets a change move
+ * through verifying → merged/rejected without a manual refresh.
+ */
+export declare function useRigChanges(rigId: string, options?: UseRigChangesOptions): UseRigChangesResult;

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

@@ -0,0 +1,108 @@
+import type { FsReadResponse, FsWriteResponse, OpenGeniRequestOptions, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+/** 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";
+/** A cold capture can index a path without retaining its contents. Components
+ *  use this typed result to offer an explicit wake action instead of silently
+ *  turning passive review into a live sandbox read. */
+export declare class CapturedFileUnavailableError extends Error {
+    readonly path: string;
+    readonly reason: CapturedFileUnavailableReason;
+    readonly code = "captured_file_unavailable";
+    constructor(path: string, reason: CapturedFileUnavailableReason);
+}
+export declare class FileWriteConflictError extends Error {
+    readonly path: string;
+    readonly expectedContent: string;
+    readonly liveContent: string;
+    readonly code = "file_write_conflict";
+    constructor(path: string, expectedContent: string, liveContent: string);
+}
+export type SandboxWriteFileOptions = {
+    /** Exact text loaded into the editor. The live file is re-read before write;
+     *  divergence fails closed with FileWriteConflictError. */
+    expectedContent?: string | undefined;
+    /** Deliberately bypass the expected-content guard after a visible conflict. */
+    force?: boolean | undefined;
+};
+/** A node in the Pierre file tree. `children === undefined` ⇒ an unexpanded dir
+ *  (lazy treeMode); `children: []` ⇒ an expanded-but-empty dir. */
+export type FileTreeNode = {
+    path: string;
+    name: string;
+    kind: "file" | "dir";
+    children?: FileTreeNode[] | undefined;
+    size?: number | null | undefined;
+    status?: FileTreeStatus | undefined;
+    /** A residue dir the capture COLLAPSED (node_modules, .git, dist, …): its
+     *  contents were never indexed. Cold, expanding it can't list children — the
+     *  UI shows an inline "contents on machine" row until the box is warm. */
+    truncated?: boolean | undefined;
+};
+export type UseSandboxFilesOptions = ClientOverride & {
+    /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
+     *  on `fs.changed` / `git.changed`. */
+    events?: SessionEvent[] | undefined;
+    /** Initial path to list (workspace root by default). */
+    rootPath?: string | undefined;
+    /** Hold off the initial list (e.g. panel collapsed). Default true. */
+    enabled?: boolean | undefined;
+    /** The lease liveness ("cold" | "warm" | "draining"). 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;
+    /** 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
+     *  fallback instead of turning into an empty error surface. */
+    capture?: WorkspaceCaptureManifest | null | undefined;
+    /** Called when an OPTIMISTIC mutation is reverted because its background
+     *  Channel-A op failed (e.g. a 409 rename collision). The host wires this to a
+     *  toast — the tree silently rolls the node back, the user sees why. */
+    onMutationError?: ((error: Error, op: string) => void) | undefined;
+};
+export type UseSandboxFilesResult = {
+    /** The tree roots (the listed root's children). */
+    tree: FileTreeNode[];
+    /** Lazy-expand a directory node in place (lists its immediate children). */
+    expand: (path: string) => Promise<void>;
+    /** Paths whose lazy `fs.list` is currently in flight — the FileBrowser shows a
+     *  spinner on these nodes so a 2-3s Channel-A list never looks frozen. */
+    expandingPaths: Set<string>;
+    /** Read a file for the preview pane (text or base64-for-binary, size-capped). */
+    readFile: (path: string, options?: OpenGeniRequestOptions) => Promise<FsReadResponse>;
+    /** Write a file (overwrite, last-writer-wins) — the editor save path.
+     *  Optimistic: a brand-new file is spliced into the tree immediately and the
+     *  Channel-A write runs in the background; on failure the splice is reverted. */
+    writeFile: (path: string, content: string, options?: SandboxWriteFileOptions) => Promise<FsWriteResponse>;
+    /** Create a new empty file (refuses to clobber an existing path: overwrite=false). */
+    createFile: (path: string) => Promise<void>;
+    /** Create a directory (recursive by default). */
+    createDir: (path: string) => Promise<void>;
+    /** Delete a path (pass recursive=true for a non-empty directory). */
+    deleteEntry: (path: string, recursive?: boolean) => Promise<void>;
+    /** Move / rename a path (rename == move). Refuses to clobber unless overwrite=true. */
+    moveEntry: (path: string, newPath: string, opts?: {
+        overwrite?: boolean;
+    }) => Promise<void>;
+    /** Re-list the whole tree from the root. */
+    refresh: () => Promise<void>;
+    /** Which source the tree is currently served from: the live box, the turn-end
+     *  capture (cold/offline), or neither yet. M5's source badge reads this. */
+    source: "live" | "capture" | null;
+    /** When the served capture was taken (ISO), when `source === "capture"`. */
+    capturedAt: string | null;
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Project the FileSystem service into a lazy-loaded Pierre tree. The initial
+ * list pulls one level (depth 1); `expand(path)` lists a directory's immediate
+ * children on demand (the fast lazy-tree UX). A git-status overlay tints
+ * modified files. Auto-refreshes when an `fs.changed` / `git.changed` event
+ * arrives on the live log.
+ */
+export declare function useSandboxFiles(sessionId: string | null | undefined, options?: UseSandboxFilesOptions): UseSandboxFilesResult;

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

@@ -0,0 +1,58 @@
+import type { GitFileDiff, SessionEvent, WorkspaceCaptureManifest } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+export type UseSandboxGitOptions = ClientOverride & {
+    /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
+     *  on `git.changed`. */
+    events?: SessionEvent[] | undefined;
+    /** Repo root within the workspace (multi-repo). Default: workspace root. */
+    repoPath?: string | undefined;
+    /** All repository roots in the workspace. When supplied, status and diff are
+     *  aggregated into one workspace-wide result and paths are workspace-relative. */
+    repoPaths?: readonly string[] | undefined;
+    /** Diff the staged index vs HEAD (`--cached`) instead of the working tree. */
+    staged?: boolean | undefined;
+    /** Hold off the initial fetch. Default true. */
+    enabled?: 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;
+    /** 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. */
+    capture?: WorkspaceCaptureManifest | null | undefined;
+};
+/** A Git diff qualified into workspace scope. `repoRoot` is present for the
+ *  workspace-wide path and lets review UI group real repositories without
+ *  guessing from the first path segment. */
+export type SandboxGitFileDiff = GitFileDiff & {
+    repoRoot?: string | undefined;
+};
+export type UseSandboxGitResult = {
+    /** Working-tree (or staged) diff vs HEAD — the structured hunks the Pierre
+     *  diff view renders. */
+    diff: SandboxGitFileDiff[];
+    branch: string | null;
+    /** Whether a repo is actually mounted (drives "no repository" vs "no changes"). */
+    isRepo: boolean;
+    ahead: number;
+    behind: number;
+    /** Number and workspace-relative roots of repositories represented here. */
+    repoCount: number;
+    repoRoots: string[];
+    refresh: () => Promise<void>;
+    /** Which source the diff is served from: the live box or the turn-end capture. */
+    source: "live" | "capture" | null;
+    /** When the served capture was taken (ISO), when `source === "capture"`. */
+    capturedAt: string | null;
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Project the Git service into the Pierre diff data contract: structured
+ * `GitFileDiff[]` (per-file hunks with per-line old/new numbers, rename
+ * detection, binary flag, add/del counts) plus branch + ahead/behind. When the
+ * box is warm the `git diff` runs in-box (API-direct); when it is cold/offline the
+ * diff is served from the turn-end capture instead. Refreshes on
+ * `git.changed`; reconciles live in place on the cold→warm transition.
+ */
+export declare function useSandboxGit(sessionId: string | null | undefined, options?: UseSandboxGitOptions): UseSandboxGitResult;