@opengeni/react 0.3.1 → 0.5.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { OpenGeniClient, Session, ResourceRef, ToolRef, SessionStatus as SessionStatus$1, SessionEvent, StreamConnectionState, SendMessageInput, FileAsset, FileResourceRef, SessionTurn, UpdateSessionTurnRequest, SessionGoal, ScheduledTask, WorkspaceEnvironment, CreateWorkspaceEnvironmentRequest, UpdateWorkspaceEnvironmentRequest, WorkspaceEnvironmentVariableMetadata, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, ClientModel, Permission } from '@opengeni/sdk';
+import { OpenGeniClient, SessionEvent, Session, ResourceRef, ToolRef, SessionStatus as SessionStatus$1, GitFileDiff, StreamConnectionState, SendMessageInput, FileAsset, FileResourceRef, SessionTurn, UpdateSessionTurnRequest, SessionGoal, ScheduledTask, WorkspaceEnvironment, CreateWorkspaceEnvironmentRequest, UpdateWorkspaceEnvironmentRequest, WorkspaceEnvironmentVariableMetadata, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, ClientModel, SessionCapabilities, DesktopStreamCapability, DesktopRfbFactory, DesktopConnectionState, TerminalCapability, FsReadResponse, FsWriteResponse, Permission, CapabilityUnavailableReason } from '@opengeni/sdk';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { ReactNode, KeyboardEvent, ClipboardEvent } from 'react';
+import { ReactNode, ComponentType, RefObject, KeyboardEvent, ClipboardEvent } from 'react';
 import { ClassValue } from 'clsx';
 
 /**
@@ -9,7 +9,7 @@ import { ClassValue } from 'clsx';
  * pass the real SDK client, a proxy-backed client that routes through their
  * own API, or a scripted client in tests/demos.
  */
-type SessionClientLike = Pick<OpenGeniClient, "getClientConfig" | "getSession" | "listSessions" | "sendMessage" | "steerMessage" | "interrupt" | "sendApprovalDecision" | "streamEvents" | "listTurns" | "updateQueuedTurn" | "reorderQueuedTurns" | "deleteQueuedTurn" | "getGoal" | "updateGoal" | "clearSessionContext" | "compactSessionContext" | "listScheduledTasks" | "uploadFile" | "getFile" | "createFileDownloadUrl" | "listEnvironments" | "createEnvironment" | "updateEnvironment" | "deleteEnvironment" | "setEnvironmentVariable" | "deleteEnvironmentVariable" | "listPacks" | "registerPack" | "enablePack" | "deletePack" | "listWorkspaces" | "createWorkspace" | "updateWorkspace" | "getBillingUsage">;
+type SessionClientLike = Pick<OpenGeniClient, "getClientConfig" | "getSession" | "updateSession" | "listSessions" | "sendMessage" | "steerMessage" | "interrupt" | "sendApprovalDecision" | "streamEvents" | "listTurns" | "updateQueuedTurn" | "reorderQueuedTurns" | "deleteQueuedTurn" | "getGoal" | "updateGoal" | "clearSessionContext" | "compactSessionContext" | "listScheduledTasks" | "uploadFile" | "getFile" | "createFileDownloadUrl" | "listEnvironments" | "createEnvironment" | "updateEnvironment" | "deleteEnvironment" | "setEnvironmentVariable" | "deleteEnvironmentVariable" | "listPacks" | "registerPack" | "enablePack" | "deletePack" | "listWorkspaces" | "createWorkspace" | "updateWorkspace" | "getBillingUsage" | "getClientConfig" | "getStreamCapabilities" | "acknowledgeStream" | "attachViewer" | "heartbeatViewer" | "detachViewer" | "fsList" | "fsRead" | "fsWrite" | "fsDelete" | "fsMove" | "fsMkdir" | "gitStatus" | "gitDiff" | "terminalExec" | "terminalPtyOpen" | "terminalPtyWrite" | "terminalPtyResize" | "terminalPtyClose">;
 
 type OpenGeniContextValue = {
     client: SessionClientLike;
@@ -37,18 +37,35 @@ declare function useOpenGeni(override?: ClientOverride): OpenGeniContextValue;
  */
 declare function useOpenGeniClient(override?: Pick<ClientOverride, "client">): SessionClientLike;
 
-type UseSessionOptions = ClientOverride & {
+type SessionEventFeedOptions = {
+    /**
+     * Share an existing event log (from `useSessionEvents`) instead of opening
+     * a second stream. When omitted the hook tails the session's event stream
+     * itself, starting at the current `lastSequence`.
+     */
+    events?: SessionEvent[] | undefined;
+    enabled?: boolean | undefined;
+};
+
+type UseSessionOptions = ClientOverride & SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
     pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
 };
 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;
 };
-/** Fetch one session (with optional polling). */
+/** Event types that change the session title (auto + cross-client renames). */
+declare function isTitleEvent(event: Pick<SessionEvent, "type">): boolean;
+/** Fetch one session (with optional polling), live-patching its title on `session.title_set`. */
 declare function useSession(sessionId: string | null | undefined, options?: UseSessionOptions): UseSessionResult;
 
 type UserMessageItem = {
@@ -86,7 +103,15 @@ type ToolCallItem = {
     name: string;
     arguments: unknown;
     output: unknown;
-    status: "running" | "complete";
+    /**
+     * The provider-native tool item (`agent.toolCall.created.payload.raw`). Carries
+     * `type` (e.g. `apply_patch_call`, `computer_call`, `hosted_tool_call`) and the
+     * tool-specific fields the per-tool renderers read (`operation`, `action`,
+     * `providerData`, …). `undefined` for first-party MCP tools, which carry their
+     * payload in `arguments`/`output` instead.
+     */
+    raw: unknown;
+    status: "running" | "complete" | "failed" | "cancelled";
     occurredAt: string;
 };
 /**
@@ -104,7 +129,7 @@ type WorkerItem = {
     prompt: string | null;
     /** The target/spawned worker session id, when parseable from args/output. */
     workerSessionId: string | null;
-    status: "running" | "complete";
+    status: "running" | "complete" | "failed" | "cancelled";
     occurredAt: string;
 };
 type SandboxItem = {
@@ -114,7 +139,7 @@ type SandboxItem = {
     name: string;
     command: string | null;
     output: string;
-    status: "running" | "complete" | "failed";
+    status: "running" | "complete" | "failed" | "cancelled";
     occurredAt: string;
 };
 type SessionStatusItem = {
@@ -138,17 +163,20 @@ type NoticeItem = {
     occurredAt: string;
 };
 type TimelineItem = UserMessageItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | SessionStatusItem | GoalItem | NoticeItem;
-declare function buildTimeline(events: SessionEvent[]): TimelineItem[];
-/** The latest session status carried in the event log, if any. */
-declare function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus$1 | null;
+/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox). */
+type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem;
 type TimelineGroup = {
     kind: "item";
     item: TimelineItem;
 } | {
     kind: "activity";
     id: string;
-    items: (ReasoningItem | ToolCallItem | WorkerItem | SandboxItem)[];
+    items: ActivityItem[];
 };
+
+declare function buildTimeline(events: SessionEvent[]): TimelineItem[];
+/** The latest session status carried in the event log, if any. */
+declare function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus$1 | null;
 declare function groupTimeline(items: TimelineItem[]): TimelineGroup[];
 /**
  * Find a session id in orchestration tool arguments or output. Handles raw
@@ -158,8 +186,308 @@ declare function groupTimeline(items: TimelineItem[]): TimelineGroup[];
 declare function extractSessionRef(value: unknown, depth?: number): string | null;
 /** Readable label for a tool call ("session_create" -> "session create"). */
 declare function toolDisplayName(name: string): string;
-/** Compact, single-line preview of tool arguments/outputs for collapsed rows. */
-declare function compactPayloadPreview(value: unknown, maxLength?: number): string;
+
+type ToolRendererProps = {
+    item: ToolCallItem;
+};
+type ToolRenderer = ComponentType<ToolRendererProps>;
+/** A registry entry: which key it matches and the component that renders it. */
+type ToolRegistryEntry = {
+    match: "rawType";
+    type: string;
+    render: ToolRenderer;
+} | {
+    match: "name";
+    name: string;
+    render: ToolRenderer;
+};
+type ToolRegistry = {
+    /** Resolve the renderer for a call (never null — falls back to generic). */
+    resolve: (item: ToolCallItem) => ToolRenderer;
+    /** The generic fallback renderer. */
+    fallback: ToolRenderer;
+};
+type CreateToolRegistryOptions = {
+    /**
+     * Entries that take precedence over the built-ins. Earlier entries win, so a
+     * consumer can shadow a default renderer for the same key.
+     */
+    entries?: ToolRegistryEntry[] | undefined;
+    /** Replace the generic fallback used for unmatched tools. */
+    fallback?: ToolRenderer | undefined;
+};
+/** The `raw.type` of a projected tool call, when the provider item carries one. */
+declare function rawTypeOf(item: ToolCallItem): string | null;
+/**
+ * Build a tool registry from a set of entries and a fallback. The returned
+ * registry resolves in priority order: `raw.type` entries first, then `name`
+ * entries, then the fallback. Consumer `entries` are consulted before the
+ * built-in `baseEntries`, so they shadow defaults cleanly.
+ */
+declare function createToolRegistry(baseEntries: ToolRegistryEntry[], baseFallback: ToolRenderer, options?: CreateToolRegistryOptions): ToolRegistry;
+
+/** The built-in tool renderer registry: every first-party tool plus a fallback. */
+declare const defaultToolRegistry: ToolRegistry;
+/** Build a registry that extends the built-ins with consumer entries/fallback. */
+declare function createDefaultToolRegistry(options?: Parameters<typeof createToolRegistry>[2]): ToolRegistry;
+
+type ActivityRailProps = {
+    items: ActivityItem[];
+    /** Renderer registry for tool calls. Defaults to {@link defaultToolRegistry}. */
+    toolRegistry?: ToolRegistry | undefined;
+    /** Drill into a spawned worker session. */
+    onOpenSession?: ((sessionId: string) => void) | undefined;
+    /** Drop the left rule + indent (used inside a folded turn summary). */
+    bare?: boolean | undefined;
+    className?: string | undefined;
+};
+declare function ActivityRail({ items, toolRegistry, onOpenSession, bare, className }: ActivityRailProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A subtle settle signal — see the CHIP DOCTRINE above. The closed tone set.
+ * `"interrupted"` is a calm neutral tone for cancelled items — no dot, same
+ * quiet weight as `"muted"`, but semantically distinct from metadata.
+ */
+type DisclosureChip = {
+    tone: "ok" | "bad" | "muted" | "interrupted";
+    text: string;
+};
+type ActivityDisclosureProps = {
+    icon: ReactNode;
+    /** Icon tint. Defaults to the muted foreground; renderers pass accent/failed. */
+    iconTone?: "accent" | "failed" | "running" | "muted" | undefined;
+    title: ReactNode;
+    /** Render the title in the mono face (commands, paths). */
+    titleMono?: boolean | undefined;
+    /** Shimmer the title while the tool is in-flight. */
+    running?: boolean | undefined;
+    /**
+     * Quiet single-line secondary text (truncated). It is detail-on-demand: hidden
+     * when a media preview is set, AND hidden once the row is expanded (the body
+     * then owns the detail), so a stat/path never appears twice at once.
+     */
+    preview?: ReactNode | undefined;
+    /** A small inline media preview (a screenshot thumbnail) shown in place of `preview`. */
+    media?: ReactNode | undefined;
+    /** At most one quiet settle chip, right-aligned to the gutter. */
+    chip?: DisclosureChip | undefined;
+    /**
+     * When true the row carries the standard failure affordance: the icon is tinted
+     * red and a "failed" bad-chip appears in the right gutter (unless an explicit
+     * `chip` is already supplied — the caller's chip wins). Output is still visible
+     * on expand; this is a quiet status signal, not a blocking banner.
+     *
+     * Renderers should pass `failed={item.status === "failed"}` on their settled
+     * (non-running) paths so any tool with a failed status shows a consistent
+     * affordance without each renderer having to duplicate the logic.
+     */
+    failed?: boolean | undefined;
+    /**
+     * When true the row carries a calm "interrupted" affordance: the icon stays
+     * muted (no red) and a quiet "interrupted" chip appears in the right gutter
+     * (unless an explicit `chip` is already supplied — the caller's chip wins).
+     * This is the cancelled-status analogue of `failed`, but deliberately calm
+     * and neutral — it is NOT an error; the user chose to stop.
+     *
+     * Renderers should pass `cancelled={item.status === "cancelled"}` so any
+     * in-flight item that was interrupted on turn.cancelled reads consistently.
+     * `cancelled` is ignored when `failed` is also true (failure takes precedence).
+     */
+    cancelled?: boolean | undefined;
+    /** When false the row is a static line (no expand affordance). */
+    expandable?: boolean | undefined;
+    children?: ReactNode | undefined;
+};
+/**
+ * The one disclosure row shape every activity row reuses (tool calls, reasoning,
+ * sandbox ops): a chevron, a tinted icon, a title, an optional muted preview or
+ * inline media, and at most one right-gutter settle chip. Compact by default;
+ * the body mounts only when expanded.
+ */
+declare function ActivityDisclosure({ icon, iconTone: iconToneProp, title, titleMono, running, preview, media, chip: chipProp, failed, cancelled, expandable, children, }: ActivityDisclosureProps): react_jsx_runtime.JSX.Element;
+declare function TermBlock({ command, workdir, output, live, tailLines, }: {
+    /**
+     * The command shown in the prompt header. Pass `null` when the row title
+     * already carries it (e.g. an exec row titled `$ cmd`): the header then drops
+     * the command — and the whole prompt line if there is no workdir either — so
+     * the command never reads twice, stacked, above the output.
+     */
+    command: string | null;
+    workdir?: string | null | undefined;
+    /** The FULL output. TermBlock owns the tail/full slicing internally. */
+    output: string;
+    live?: boolean | undefined;
+    /**
+     * When the output exceeds the tail window, only the last `tailLines` are shown
+     * with a "show full output" toggle. The component holds the full text, so the
+     * toggle reveals the rest (never a dead affordance). Defaults to 12.
+     */
+    tailLines?: number | undefined;
+}): react_jsx_runtime.JSX.Element;
+declare function PayloadBlock({ label, value, failed }: {
+    label: string;
+    value: unknown;
+    failed?: boolean | undefined;
+}): react_jsx_runtime.JSX.Element | null;
+/** A quiet inline note inside an expanded body (lost output, empty frame, …). */
+declare function BodyNote({ children, tone }: {
+    children: ReactNode;
+    tone?: "error" | "muted" | undefined;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * A loading screenshot placeholder. A faint camera glyph over a shimmering box,
+ * so a still frame of the running state reads unambiguously as "capturing" — not
+ * a broken thumbnail.
+ */
+declare function MediaSkeleton(): react_jsx_runtime.JSX.Element;
+/** A standardized "tool ran, produced no image" placeholder in the media slot. */
+declare function MediaEmpty(): react_jsx_runtime.JSX.Element;
+/**
+ * A small inline screenshot thumbnail that opens the app lightbox on click.
+ *
+ * Requires a `LightboxProvider` ancestor for the click-to-expand affordance.
+ * Outside one it degrades to a plain, non-interactive image — never a dead
+ * "Expand" button that announces an action it cannot perform.
+ */
+declare function Thumbnail({ src, caption, alt }: {
+    src: string;
+    caption?: string | undefined;
+    alt?: string;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * The expanded screenshot inside a tool body: a contained, clickable preview
+ * (opens the lightbox) with a quiet caption. Constrained height + object-contain
+ * so it never breaks the row layout. Like {@link Thumbnail}, it degrades to a
+ * plain image outside a `LightboxProvider`.
+ */
+declare function ScreenshotFigure({ src, caption, alt }: {
+    src: string;
+    caption?: string | undefined;
+    alt?: string;
+}): react_jsx_runtime.JSX.Element;
+
+type LightboxController = {
+    open: (src: string, caption?: string) => void;
+};
+/** Open the app-level screenshot lightbox. No-op outside a `LightboxProvider`. */
+declare function useLightbox(): LightboxController;
+/**
+ * The lightbox controller when one is mounted, or `null` outside a
+ * `LightboxProvider`. Lets a media primitive degrade to a non-interactive image
+ * (rather than a dead "Expand" button that announces an action it cannot do).
+ */
+declare function useLightboxOptional(): LightboxController | null;
+/**
+ * The app-level screenshot lightbox. Render once near the timeline; renderers
+ * call `useLightbox().open(src)`.
+ *
+ * Idempotent by design: when an ancestor `LightboxProvider` already exists (e.g.
+ * a `MessageTimeline` mounted inside an app that already wraps its shell), this
+ * one becomes a pass-through and does NOT mount a second focus-trapping Dialog.
+ * That keeps `MessageTimeline` self-sufficient (it owns its own provider) while
+ * composing cleanly when nested.
+ */
+declare function LightboxProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Seed the initial open state of every timeline collapsible below this node.
+ * Intended for screenshot/test instrumentation only; absent by default.
+ */
+declare function DisclosureDefaultsProvider({ defaultOpen, children }: {
+    defaultOpen: boolean;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+type TurnOutcome = "complete" | "failed" | "cancelled";
+type TurnSummaryProps = {
+    /** The activity items in the turn (used only to compute the facet counts). */
+    items: ActivityItem[];
+    outcome: TurnOutcome;
+    /** A short failure reason shown inline on a failed chip (never hidden). */
+    failureText?: string | undefined;
+    /** Start expanded. */
+    defaultOpen?: boolean | undefined;
+    /** The rendered activity rail revealed on expand. */
+    children: React.ReactNode;
+};
+declare function TurnSummary({ items, outcome, failureText, defaultOpen, children }: TurnSummaryProps): react_jsx_runtime.JSX.Element;
+
+/** Recover the exit code from a sandbox exec banner (`Process exited with code N`). */
+declare function sandboxCommandExitCode(out: unknown): number | null;
+/**
+ * Recover the numeric exec-session id the sandbox embeds for a STILL-RUNNING
+ * (backgrounded) process (`Process running with session ID N`). A finished
+ * command emits `Process exited with code N` instead, which yields `null`.
+ */
+declare function parseExecBannerSessionId(out: unknown): number | null;
+/** Strip the exec banner (`Chunk ID ...\n...\nOutput:\n`) down to the command's stdout. */
+declare function stripExecBanner(out: unknown): string;
+/** The sandbox clamped the output (token/line truncation markers in the banner). */
+declare function execTruncated(out: unknown): boolean;
+/** A `write_stdin` whose target PTY vanished (`write_stdin failed: session not found: N`). */
+declare function isExecSessionLostBanner(out: unknown): boolean;
+/** True when the exec stdout looks binary/garbled (a NUL byte or ELF magic). */
+declare function looksBinary(text: string): boolean;
+/**
+ * Render unprintable control characters as caret notation (0x03 -> `^C`) so a
+ * `write_stdin` keystroke payload reads cleanly in the row title.
+ */
+declare function controlCaret(printable: string): string;
+/** One operation inside an `apply_patch_call` (a V4A file edit). */
+type ApplyPatchOperation = {
+    /**
+     * The V4A op kind. The three canonical values are `create_file`,
+     * `update_file`, and `delete_file`; the open `string` tail tolerates a
+     * forward-compatible/unknown op kind from the provider without a type error
+     * (it falls through to the "Edited" treatment).
+     */
+    type: "create_file" | "update_file" | "delete_file" | (string & {});
+    path: string;
+    /** Rename target -- when present the op is a move/rename. */
+    moveTo?: string | null | undefined;
+    /** The V4A hunk string (`@@ ...` lines with `+`/`-`/context prefixes). */
+    diff?: string | undefined;
+};
+/**
+ * Parse a single V4A `apply_patch` operation into the SDK's `GitFileDiff` shape
+ * so it can flow into the SAME `DiffView` / `PierreDiff` the Files tab uses.
+ * Throws on a hunk string it cannot structure (no `@@` anchor on an update); the
+ * renderer catches and falls back to a raw-patch view.
+ */
+declare function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff;
+/**
+ * Extract the `apply_patch` operations from a provider-native tool item's `raw`
+ * payload, normalizing the two wire shapes (`raw.operations[]` for a multi-file
+ * patch, `raw.operation` for a single op). The single owner of this shape so the
+ * renderer and the turn-summary facet counter never drift.
+ */
+declare function applyPatchOps(raw: unknown): ApplyPatchOperation[];
+/**
+ * True when a tool item is an `apply_patch_call` — by its provider-native
+ * `raw.type` (the live-wire source of truth) or by tool `name` (first-party
+ * replays that omit `raw`). Centralizes the rawType-or-name check.
+ */
+declare function isApplyPatch(item: {
+    name: string;
+    raw: unknown;
+}): boolean;
+/** Deep-redact secret-looking values so arguments never leak a key into the UI. */
+declare function redactSecrets(value: unknown): unknown;
+/** Parse tool arguments that may arrive as a JSON string or an object. */
+declare function parseToolArgs(args: unknown): Record<string, unknown>;
+/** The last non-empty line of a string -- the compact "what happened" peek. */
+declare function tailPeek(text: string): string;
+/**
+ * Unwrap an MCP tool result (`{ content: [{ type: "text", text }], isError? }`)
+ * into a flat `{ text, isError }`. Non-MCP outputs pass through as their string
+ * form.
+ */
+declare function unwrapMcpOutput(output: unknown): {
+    text: string;
+    isError: boolean;
+};
 
 type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
 type UseSessionEventsOptions = ClientOverride & {
@@ -296,16 +624,6 @@ type UseFileAttachmentsResult = {
  */
 declare function useFileAttachments(options?: UseFileAttachmentsOptions): UseFileAttachmentsResult;
 
-type SessionEventFeedOptions = {
-    /**
-     * Share an existing event log (from `useSessionEvents`) instead of opening
-     * a second stream. When omitted the hook tails the session's event stream
-     * itself, starting at the current `lastSequence`.
-     */
-    events?: SessionEvent[] | undefined;
-    enabled?: boolean | undefined;
-};
-
 /** Event types that change the turn queue (queue/edit/reorder/claim/finish). */
 declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
 /** Queued turns in execution order (position, then creation time). */
@@ -561,6 +879,323 @@ type UseAvailableModelsResult = {
  */
 declare function useAvailableModels(options?: UseAvailableModelsOptions): UseAvailableModelsResult;
 
+type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "error";
+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 purely to KEEP THE BOX WARM while the
+     * structured Files surface is open. Shares the SAME viewer attach as the
+     * desktop/terminal (one warm box, one holder) and — like the terminal — needs
+     * NO un-redacted acknowledgment: listing/reading/writing files is the ordinary
+     * Channel-A control plane, not the pixel plane. Default false: the Files tab
+     * negotiates read-only and each op pays the cold-box resume (~5s). When true,
+     * the holder warms the box once and heartbeats it, so subsequent fs ops are
+     * ~100ms instead of re-resuming the box on every list/write. It folds NO live
+     * URL (files ride the stateless HTTP plane) — it only refcounts liveness.
+     */
+    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 (must agree with
+     * the lease warming TTL — I15). 0 disables the deadline.
+     */
+    warmingDeadlineMs?: number | undefined;
+};
+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.
+ */
+declare function useSessionCapabilities(sessionId: string | null | undefined, options?: UseSessionCapabilitiesOptions): UseSessionCapabilitiesResult;
+
+type UseDesktopStreamOptions = {
+    /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
+    capability: DesktopStreamCapability | null;
+    /** The mount target. RFB attaches here on connect. */
+    containerRef: RefObject<HTMLDivElement | null>;
+    /** Read-only by default (v1 ruling H). interactive only when cap.mode allows. */
+    interactive?: boolean | undefined;
+    scaleViewport?: boolean | undefined;
+    /** Custom RFB factory (tests / a WebRTC swap). Defaults to a lazy @novnc/novnc. */
+    rfbFactory?: DesktopRfbFactory | undefined;
+};
+type UseDesktopStreamResult = {
+    state: DesktopConnectionState;
+    error: Error | null;
+    /** Manual reconnect (e.g. after a securityfailure once a fresh URL arrives). */
+    reconnect: () => void;
+};
+/**
+ * Drive the noVNC RFB lifecycle from a `DesktopStreamCapability`, using the
+ * SDK's `desktop.ts` reducer + `desktopSocketUrl`. SSR-safe: the RFB import and
+ * the DOM attach happen inside `useEffect`, so a server render is a no-op and
+ * the component shows its placeholder until hydration.
+ *
+ * Read-only is enforced at three layers: `capability.mode` (server) →
+ * `interactive` prop → `RFB.viewOnly`. v1 always resolves to read-only. On a
+ * capability `url` change (a rotation), the old RFB disconnects and a fresh one
+ * connects to the new URL — a brief "desktop blink", acceptable on rollover.
+ */
+declare function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopStreamResult;
+
+/** The ttyd connection lifecycle as surfaced to the component. */
+type TerminalStreamStatus = "connecting" | "open" | "closed" | "error";
+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;
+};
+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.
+ */
+declare function useTerminalStream(options: UseTerminalStreamOptions): UseTerminalStreamResult;
+
+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;
+};
+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;
+};
+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).
+ */
+declare function useSandboxTerminal(sessionId: string | null | undefined, options: UseSandboxTerminalOptions): UseSandboxTerminalResult;
+
+/** The git-status overlay a file row may carry (tints modified files in the tree). */
+type FileTreeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
+/** A node in the Pierre file tree. `children === undefined` ⇒ an unexpanded dir
+ *  (lazy treeMode); `children: []` ⇒ an expanded-but-empty dir. */
+type FileTreeNode = {
+    path: string;
+    name: string;
+    kind: "file" | "dir";
+    children?: FileTreeNode[] | undefined;
+    size?: number | null | undefined;
+    status?: FileTreeStatus | undefined;
+};
+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;
+    /** 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;
+};
+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) => 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) => 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>;
+    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.
+ */
+declare function useSandboxFiles(sessionId: string | null | undefined, options?: UseSandboxFilesOptions): UseSandboxFilesResult;
+
+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;
+    /** 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;
+};
+type UseSandboxGitResult = {
+    /** Working-tree (or staged) diff vs HEAD — the structured hunks the Pierre
+     *  diff view renders. */
+    diff: GitFileDiff[];
+    branch: string | null;
+    /** Whether a repo is actually mounted (drives "no repository" vs "no changes"). */
+    isRepo: boolean;
+    ahead: number;
+    behind: number;
+    refresh: () => Promise<void>;
+    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. The
+ * `git diff` runs in-box (API-direct) and the hunks come back inline. Refreshes
+ * on `git.changed`.
+ */
+declare function useSandboxGit(sessionId: string | null | undefined, options?: UseSandboxGitOptions): UseSandboxGitResult;
+
 type PendingApproval = {
     /** The id to send back via `user.approvalDecision` (`approvalId`). */
     id: string;
@@ -884,6 +1519,12 @@ type MessageTimelineProps = {
     renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
     /** Drill into a spawned worker session. */
     onOpenSession?: ((sessionId: string) => void) | undefined;
+    /**
+     * The tool-renderer registry that resolves how each tool call is drawn.
+     * Defaults to {@link defaultToolRegistry}; pass a registry from
+     * `createDefaultToolRegistry({ entries })` to add custom tool renderers.
+     */
+    toolRegistry?: ToolRegistry | undefined;
     /** Follow new events when pinned to the bottom. Defaults to true. */
     autoFollow?: boolean | undefined;
     emptyState?: ReactNode | undefined;
@@ -895,7 +1536,16 @@ type MessageTimelineProps = {
  * cards, goal markers, and status transitions. Owns stick-to-bottom scrolling
  * with a "jump to latest" affordance when the reader scrolls back.
  */
-declare function MessageTimeline({ events, items, status, renderMessageText, onOpenSession, autoFollow, emptyState, className, }: MessageTimelineProps): react_jsx_runtime.JSX.Element;
+declare function MessageTimeline({ events, items, status, renderMessageText, onOpenSession, toolRegistry, autoFollow, emptyState, className, }: MessageTimelineProps): react_jsx_runtime.JSX.Element;
+/**
+ * Render one non-activity timeline item (chat message, status divider, goal
+ * landmark, notice). Exported so the component demo draws the EXACT same rows as
+ * the live app — no forked bubble/goal markup.
+ */
+declare function TimelineRow({ item, renderMessageText, }: {
+    item: TimelineItem;
+    renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
+}): react_jsx_runtime.JSX.Element | null;
 
 /**
  * The default renderer for chat message bodies in {@link MessageTimeline}.
@@ -962,6 +1612,384 @@ declare function sessionDisplayTitle(session: Session): string;
  */
 declare function FleetTile({ session, title, subtitle, onOpen, className }: FleetTileProps): react_jsx_runtime.JSX.Element;
 
+/** A subset of xterm.js's ITheme — the tokens worth themeing from a host app. */
+type XtermTheme = {
+    background?: string;
+    foreground?: string;
+    cursor?: string;
+    cursorAccent?: string;
+    selectionBackground?: string;
+};
+type SandboxTerminalProps = {
+    /** From `useSandboxTerminal(...)`. */
+    result: UseSandboxTerminalResult;
+    /**
+     * The negotiated Terminal capability cell. When it advertises `transport:
+     * "pty-ws"` + a live `url` (a warm box with a viewer attached), the terminal is
+     * driven by a REAL bidirectional PTY over the Modal tunnel (ttyd-over-websocket)
+     * INSTEAD of the broken ptyWrite-over-HTTP path: xterm input → the socket, the
+     * socket's output → xterm, xterm resize → the socket. On a cold box / no url
+     * (`transport: "sse-events"`) it stays on the read-only Channel-A firehose
+     * (`result.chunks`). Omit to force the legacy firehose-only behavior.
+     */
+    terminalCapability?: TerminalCapability | null | undefined;
+    theme?: XtermTheme | undefined;
+    fontFamily?: string | undefined;
+    fontSize?: number | undefined;
+    /**
+     * Force read-only even when the PTY accepts stdin. Default: interactive
+     * whenever a live pty-ws stream is connected OR `result.write !== null` (the box
+     * advertises an interactive PTY); otherwise the read-only agent firehose.
+     */
+    readOnly?: boolean | undefined;
+    /** Shown on the server / before xterm hydrates (SSR-safe placeholder). */
+    placeholder?: ReactNode | undefined;
+    /** Render the small status header (pty/shell + running dot + read-only pill). */
+    showHeader?: boolean | undefined;
+    /** Shell label for the header (e.g. `/bin/bash`). */
+    shell?: string | undefined;
+    /**
+     * Fired the first time the user engages the terminal surface (focus or click).
+     * The host wires this to warm the box for the REAL pty-ws terminal (the viewer
+     * attach), so a cold box upgrades from the read-only firehose to a live PTY ON
+     * INTERACT — never on mere mount (which would force a box spin-up and regress
+     * the firehose-only default).
+     */
+    onActivate?: (() => void) | undefined;
+    className?: string | undefined;
+};
+/**
+ * An xterm.js terminal fed by the Channel-A event projection
+ * (`useSandboxTerminal`). xterm + the fit + web-links addons are lazy-imported
+ * inside an effect, so SSR renders the placeholder and the terminal mounts on
+ * hydration. Output chunks are written incrementally (tracking a written-cursor
+ * by chunk id so a re-render never re-writes). When `result.write` is non-null
+ * and not forced read-only, keystrokes pipe back through the PTY.
+ *
+ * Resizes are tracked with a `ResizeObserver` on the container (not just
+ * `window.resize`) so dragging the dock handle refits the grid instead of
+ * leaving the terminal mis-sized.
+ */
+declare function SandboxTerminal({ result, terminalCapability, theme, fontFamily, fontSize, readOnly, placeholder, showHeader, shell, onActivate, className, }: SandboxTerminalProps): react_jsx_runtime.JSX.Element;
+
+type FileBrowserProps = {
+    /** From `useSandboxFiles(...)`. */
+    result: UseSandboxFilesResult;
+    /**
+     * Rendered instead of the built-in tree when the file surface is unavailable
+     * (e.g. a `FileSystem.available === false` capability). Default: a quiet notice.
+     */
+    fallback?: ReactNode | undefined;
+    /** Selection callback for the preview pane. */
+    onSelectFile?: ((path: string) => void) | undefined;
+    selectedPath?: string | undefined;
+    /** Render-prop to theme/replace a row entirely (the Pierre-swap escape hatch). */
+    renderNode?: ((node: FileTreeNode, depth: number, expanded: boolean) => ReactNode) | undefined;
+    /** Shown when the tree is empty (no files / not loaded yet). */
+    emptyState?: ReactNode | undefined;
+    /**
+     * Enable the file-manager affordances (toolbar, context menu, drag-drop move,
+     * inline rename, delete, new file/folder). Defaults to `true` when the hook
+     * exposes the mutation methods; pass `false` for a strictly read-only tree.
+     */
+    editable?: boolean | undefined;
+    /**
+     * Confirm a (recursive) delete before it runs. Return `false` to cancel.
+     * Defaults to `window.confirm`. Pass a no-op returning `true` to skip.
+     */
+    confirmDelete?: ((node: FileTreeNode) => boolean | Promise<boolean>) | undefined;
+    className?: string | undefined;
+};
+/**
+ * The file MANAGER, fed by the FileSystem service via `useSandboxFiles`. This is
+ * a first-class editable tree (not a render-only view): lazy-expand with a
+ * spinner on the in-flight node, git-status tinting, full keyboard navigation,
+ * selection, and the mutating affordances wired straight to the hook —
+ *
+ *   • drag-and-drop MOVE  → `moveEntry(from, to)`
+ *   • inline RENAME       → `moveEntry(path, newPath)`  (F2 / double-click / menu)
+ *   • DELETE              → `deleteEntry(path, recursive)`  (Del / menu, confirmed)
+ *   • NEW FILE / FOLDER   → `createFile` / `createDir` (toolbar + menu), then open
+ *   • right-click CONTEXT MENU
+ *
+ * `renderNode` is still honoured as the Pierre-swap escape hatch for the row
+ * chrome; the manager scaffolding (toolbar, dnd, menu, inline inputs) wraps it.
+ */
+declare function FileBrowser({ result, fallback, onSelectFile, selectedPath, renderNode, emptyState, editable, confirmDelete, className, }: FileBrowserProps): react_jsx_runtime.JSX.Element;
+
+/** Theme tokens for the diff line backgrounds. */
+type DiffTheme = {
+    addBackground?: string;
+    delBackground?: string;
+    contextBackground?: string;
+    metaForeground?: string;
+};
+type DiffViewProps = {
+    /** From `useSandboxGit().diff` — the structured per-file hunks. */
+    diff: GitFileDiff[];
+    /** Rendered instead of the built-in diff (the Pierre-swap escape hatch). */
+    fallback?: ReactNode | undefined;
+    /** unified | split. Default "unified". */
+    layout?: "unified" | "split" | undefined;
+    theme?: DiffTheme | undefined;
+    onSelectFile?: ((path: string) => void) | undefined;
+    /** Distinguishes "no changes" from "no repository mounted". */
+    isRepo?: boolean | undefined;
+    emptyState?: ReactNode | undefined;
+    className?: string | undefined;
+};
+/**
+ * The diff view, fed by the Git service via `useSandboxGit().diff`. This is our
+ * `PierreDiff` boundary: the built-in renderer delivers the same UX (per-file
+ * hunks, unified or side-by-side, old/new line numbers, add/del counts), and a
+ * consumer with Pierre's `@pierre/diffs` installed can swap it via `fallback`
+ * while keeping the same `GitFileDiff[]` data contract from the hook.
+ */
+declare function DiffView({ diff, fallback, layout, theme, onSelectFile, isRepo, emptyState, className, }: DiffViewProps): react_jsx_runtime.JSX.Element;
+
+type PierreDiffProps = {
+    diff: GitFileDiff[];
+    layout?: "unified" | "split" | undefined;
+    themeType?: "dark" | "light" | undefined;
+    /** Shiki bundled theme names (dark/light) — derived from the host palette. */
+    theme?: {
+        dark: string;
+        light: string;
+    } | undefined;
+    /** Disable Pierre's worker pool if its worker bundling fights the host bundler. */
+    disableWorkerPool?: boolean | undefined;
+    /** Rendered while the (lazy) Pierre bundle loads. */
+    loading?: ReactNode | undefined;
+    /** Rendered if `@pierre/diffs/react` is not installed / fails to import. */
+    fallback?: ReactNode | undefined;
+    className?: string | undefined;
+};
+/**
+ * The Pierre-backed diff: Shiki-highlighted, virtualized, unified/split. Renders
+ * one `PatchDiff` per changed file (a reconstructed unified patch from the
+ * `GitFileDiff` hunks). This sits behind `DiffView`'s `fallback` seam so a host
+ * that lacks `@pierre/diffs` keeps the hand-rolled renderer.
+ */
+declare function PierreDiff({ diff, layout, themeType, theme, disableWorkerPool, loading, fallback, className, }: PierreDiffProps): react_jsx_runtime.JSX.Element;
+
+type PierreFileProps = {
+    /** Workspace-relative path (used for the header + language inference). */
+    path: string;
+    /** The decoded text contents. */
+    contents: string;
+    themeType?: "dark" | "light" | undefined;
+    /** Shiki bundled theme names (dark/light) — derived from the host palette. */
+    theme?: {
+        dark: string;
+        light: string;
+    } | undefined;
+    /** Disable Pierre's worker pool if its worker bundling fights the host bundler. */
+    disableWorkerPool?: boolean | undefined;
+    /** Rendered while the (lazy) Pierre bundle loads. */
+    loading?: ReactNode | undefined;
+    /** Rendered if `@pierre/diffs/react` is not installed / fails to import. */
+    fallback?: ReactNode | undefined;
+    className?: string | undefined;
+};
+/**
+ * The Pierre-backed single-file VIEWER: Shiki-highlighted, language inferred from
+ * the filename — the read complement of `PierreDiff`. Wired to `fs.read` so
+ * clicking any file in the tree shows its contents (NOT a diff; no repo needed).
+ * Falls back to a plain `<pre>` when `@pierre/diffs` is absent / fails to import.
+ */
+declare function PierreFile({ path, contents, themeType, theme, disableWorkerPool, loading, fallback, className, }: PierreFileProps): react_jsx_runtime.JSX.Element;
+
+/** Language grammar loaders, keyed by the extension class we infer from the path. */
+declare const LANGUAGE_LOADERS: Record<string, () => Promise<unknown>>;
+/** Map a filename to a grammar key (or null for plain text — still fully editable). */
+declare function languageForPath(path: string): keyof typeof LANGUAGE_LOADERS | null;
+type CodeEditorProps = {
+    /** Workspace-relative path — drives language inference (and the save target upstream). */
+    path: string;
+    /** The decoded text contents to seed the editor with. */
+    initialContents: string;
+    /** Persist the current buffer. Resolves when the write lands; rejects to surface an error. */
+    onSave: (contents: string) => Promise<unknown>;
+    /** Read-only mode (e.g. a truncated/too-large file shown for reference only). */
+    readOnly?: boolean | undefined;
+    themeType?: "dark" | "light" | undefined;
+    /** Rendered while the (lazy) CodeMirror bundle loads. */
+    loading?: ReactNode | undefined;
+    /** Rendered if `@uiw/react-codemirror` is not installed / fails to import. */
+    fallback?: ReactNode | undefined;
+    className?: string | undefined;
+};
+/**
+ * The EDITABLE single-file pane: CodeMirror 6 with a per-language grammar chosen
+ * from the filename, og-* themed, with dirty tracking and a save path wired to
+ * `Cmd/Ctrl+S` *and* an explicit Save button. The viewer (Pierre `File`) stays
+ * the read-only complement — this is only mounted when the user opts to edit.
+ *
+ * Save semantics: the buffer is "dirty" the moment it diverges from the last
+ * saved baseline; a successful `onSave` clears dirty and re-baselines. A failed
+ * save keeps the buffer dirty (nothing is lost) and surfaces the error inline.
+ * `readOnly` suppresses every mutation path so a truncated/binary file can never
+ * be saved back (which would corrupt it by writing the truncated prefix).
+ */
+declare function CodeEditor({ path, initialContents, onSave, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
+
+type SandboxFilesProps = {
+    /** From `useSandboxFiles(...)`. */
+    files: UseSandboxFilesResult;
+    /** From `useSandboxGit(...)` — the working-tree diff. */
+    git: UseSandboxGitResult;
+    /** From a second `useSandboxGit(..., { staged: true })` — the staged diff. */
+    stagedGit?: UseSandboxGitResult | undefined;
+    /** Whether a FileSystem surface is advertised (drives the unavailable notice). */
+    fileSystemAvailable?: boolean | undefined;
+    /** Use Pierre's Shiki-highlighted diff (default true; falls back to built-in). */
+    usePierre?: boolean | undefined;
+    /** Allow in-place editing of tree files (CodeMirror). Default true. When false
+     *  the surface is review-only: every text file opens in the read-only viewer. */
+    editable?: boolean | undefined;
+    themeType?: "dark" | "light" | undefined;
+    className?: string | undefined;
+};
+/**
+ * The review-first Files surface: a sticky branch/dirty header, a "Changes"
+ * group (changed files vs HEAD, badged), the full lazy file tree for context,
+ * and an inline diff pane below for the selected changed file. The agent
+ * commits; the human reviews — there is no stage/commit/push UI here (power-git
+ * lives in the terminal).
+ */
+declare function SandboxFiles({ files, git, stagedGit, fileSystemAvailable, usePierre, editable, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
+
+type DesktopViewerProps = {
+    /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
+    capability: DesktopStreamCapability | null;
+    /**
+     * Initial control mode. Default false (watch). When the user flips
+     * "Take control" the viewer drives input — but only if `capability.mode`
+     * permits it (server-gated; a read-only deployment disables the toggle).
+     * Pass a value to control it externally; omit to let the viewer own the state.
+     */
+    interactive?: boolean | undefined;
+    /** Render the built-in Watching ⇄ Take control toggle (default true). */
+    showControlToggle?: boolean | undefined;
+    scaleViewport?: boolean | undefined;
+    /** Custom RFB factory (tests / a WebRTC swap). Defaults to lazy @novnc/novnc. */
+    rfbFactory?: DesktopRfbFactory | undefined;
+    /**
+     * Consent gate for the un-redacted (and possibly shared) pixel plane. Rendered
+     * BEFORE connecting whenever the desktop requires acknowledgment that hasn't
+     * been given. Call `onAccept` to record consent (the host wires it to
+     * `client.acknowledgeStream` + a re-negotiate). When omitted, a default
+     * banner is shown.
+     */
+    renderConsentGate?: ((onAccept: () => void, shared: boolean) => ReactNode) | undefined;
+    /** Called when the default consent gate's accept button is pressed. */
+    onAcknowledge?: (() => void) | undefined;
+    /**
+     * Whether the host has the viewer attach engaged (i.e. the user has opted into
+     * watching — the parent's `watchDesktop`/`attachDesktop`). Drives the
+     * cold-state behaviour: when watching, a cold-but-warmable lease AUTO-WARMS
+     * (and re-warms when the box drains) instead of dead-ending. When omitted we
+     * infer it from a recorded consent (the default gate's accept), so the
+     * component still self-heals after the first acknowledgment.
+     */
+    watching?: boolean | undefined;
+    /**
+     * Request a (re)warm of the sandbox WITHOUT re-acknowledging (the consent has
+     * already been recorded — only the box drained). The host wires this to
+     * "engage the viewer attach + re-negotiate". Called automatically when a
+     * watched desktop is found cold-but-warmable, and behind the manual retry on
+     * the warming notice. Distinct from `onAcknowledge`, which is the FIRST,
+     * consent-bearing warm.
+     */
+    onWarm?: (() => void) | undefined;
+    /** Shown when transport is null (headless backend / degraded / disabled). */
+    renderUnavailable?: ((reason: CapabilityUnavailableReason | null) => ReactNode) | undefined;
+    /** Shown while the box is cold/warming (no live address yet). */
+    renderWarming?: (() => ReactNode) | undefined;
+    /** Shown when the per-session viewer cap (429) was hit. */
+    renderViewerCap?: (() => ReactNode) | undefined;
+    /** Surface the 429 cap state from `useSessionCapabilities().viewerCapReached`. */
+    viewerCapReached?: boolean | undefined;
+    /**
+     * Connect watchdog (ms): if a live url is present but the RFB hasn't connected
+     * within this window, surface a "Couldn't connect" + Reconnect instead of an
+     * eternal idle scrim. Default 13000. 0 disables the watchdog.
+     */
+    connectTimeoutMs?: number | undefined;
+    className?: string | undefined;
+};
+/**
+ * The desktop surface: a noVNC client connecting to the Channel-B scoped tunnel
+ * URL from the capability doc. Owns the mount `<div ref>`, drives
+ * `useDesktopStream` (SSR-safe lazy RFB), and renders a real
+ * cold → warming → connecting → connected → error state machine with live
+ * feedback (spinners, transitions) — never a dead black box with stale text.
+ *
+ * The read-only vs interactive decision is enforced server-first
+ * (`capability.mode`): when the deployment advertises mode "interactive" the
+ * viewer can TAKE CONTROL and drive the mouse & keyboard into the box's :0; a
+ * "read-only" deployment disables the take-control affordance (graceful, with a
+ * reason).
+ *
+ * Warming: a cold-but-warmable lease (`reason: "lease_cold"`) is NOT a dead end.
+ * When the user is watching (consented), the viewer asks the host to (re)warm
+ * the box (`onWarm`) and shows a "Warming…" spinner; if the box later drains to
+ * cold it re-warms. Genuinely-unavailable surfaces (headless/policy/os/backend)
+ * keep a clear, static unavailable notice.
+ */
+declare function DesktopViewer({ capability, interactive, showControlToggle, scaleViewport, rfbFactory, renderConsentGate, onAcknowledge, watching, onWarm, renderUnavailable, renderWarming, renderViewerCap, viewerCapReached, connectTimeoutMs, className, }: DesktopViewerProps): react_jsx_runtime.JSX.Element;
+
+type WorkspaceTab = {
+    id: string;
+    label: ReactNode;
+    /** Rendered as the active surface. */
+    content: ReactNode;
+    /** A small badge after the label (e.g. dirty count, live pill). */
+    badge?: ReactNode | undefined;
+};
+type WorkspaceDockProps = {
+    /** The chat / primary pane shown beside the dock. */
+    primary: ReactNode;
+    tabs: WorkspaceTab[];
+    /** Controlled active tab. Falls back to the first tab. */
+    activeTab?: string | undefined;
+    onActiveTabChange?: ((id: string) => void) | undefined;
+    /** Persisted layout id (localStorage key) for react-resizable-panels. */
+    autoSaveId?: string | undefined;
+    /** Default dock width as a percent of the session area. */
+    defaultSize?: number | undefined;
+    minSize?: number | undefined;
+    maxSize?: number | undefined;
+    className?: string | undefined;
+};
+/**
+ * The resizable / collapsible / maximizable right-hand Workspace dock. Replaces
+ * a fixed grid column: drag the separator to set width, collapse to a thin rail
+ * that re-opens on click, and maximize to a full-workspace overlay (Esc /
+ * restore button returns). Layout persists via `useDefaultLayout` keyed on
+ * `autoSaveId`. Maximize is a mode ABOVE the Group (a `fixed inset-0` overlay) —
+ * pushing a Panel to ~100% still fights min sizes and leaves a chat sliver.
+ */
+declare function WorkspaceDock({ primary, tabs, activeTab, onActiveTabChange, autoSaveId, defaultSize, minSize, maxSize, className, }: WorkspaceDockProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Reconstruct a unified-diff patch string for a single `GitFileDiff` so it can
+ * be fed to a generic patch renderer (e.g. Pierre's `PatchDiff`). The hook
+ * already carries per-line old/new numbers and a hunk header, so we emit a
+ * conventional `--- / +++ / @@` patch the parser understands.
+ */
+declare function gitFileDiffToPatch(file: GitFileDiff): string;
+
+/**
+ * Derive an xterm `ITheme` subset from the live OKLCH `--og-*` token system (or
+ * the app's `--color-*` aliases). Reads the COMPUTED values so xterm — which
+ * paints into a canvas and can't consume CSS vars — gets concrete colors. Call
+ * on mount and re-derive on a `data-og-theme` flip.
+ *
+ * SSR-safe: returns undefined off the DOM (the caller keeps xterm's defaults).
+ */
+declare function xtermThemeFromTokens(root?: HTMLElement | null): XtermTheme | undefined;
+
 /** Merge class names with Tailwind-aware conflict resolution. */
 declare function cn(...inputs: ClassValue[]): string;
 
@@ -976,4 +2004,4 @@ declare function stringifyPayload(value: unknown): string;
 /** JSON.parse that returns `undefined` instead of throwing. */
 declare function tryParseJson(text: string): unknown;
 
-export { type AgentMessageItem, ChatComposer, type ChatComposerProps, type ClientOverride, type CommandContext, CommandPalette, type CommandPaletteProps, type CommandResult, type ComposerMode, type ComposerSendExtras, type ComposerState, type ConfirmState, type FileAttachment, FleetTile, type FleetTileProps, type GoalItem, Markdown, type MarkdownProps, MessageTimeline, type MessageTimelineProps, ModelPicker, type ModelPickerProps, type Notice, type NoticeItem, type OpenGeniContextValue, OpenGeniProvider, type OpenGeniProviderProps, type ParsedCommandLine, type PendingApproval, type ReasoningItem, SESSION_STATUS_META, type SandboxItem, type SessionClientLike, type SessionEventsConnectionState, SessionStatus, type SessionStatusItem, type SessionStatusMeta, type SessionStatusProps, type SlashArg, type SlashCommand, type SlashCommandContext, type SlashCommandHandlers, StatusDot, type StatusDotProps, type TimelineGroup, type TimelineItem, type ToolCallItem, type UseAvailableModelsOptions, type UseAvailableModelsResult, type UseBillingUsageOptions, type UseBillingUsageResult, type UseComposerOptions, type UseEnvironmentsOptions, type UseEnvironmentsResult, type UseFileAttachmentsOptions, type UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UsePacksOptions, type UsePacksResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionControlOptions, type UseSessionControlResult, type UseSessionEventsOptions, type UseSessionEventsResult, type UseSessionOptions, type UseSessionResult, type UseSlashCommandsOptions, type UseSlashCommandsResult, type UseTurnQueueOptions, type UseTurnQueueResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, type UserMessageItem, type WorkerItem, activeTurnFromTurns, applyTurnEdit, applyTurnRemoval, applyTurnReorder, approvalsFromRequiresAction, argHint, buildTimeline, cn, compactPayloadPreview, composeSendInput, defaultCommands, extractSessionRef, filterCommands, firstMissingRequiredArg, formatBytes, formatRelativeTime, groupTimeline, hasPermission, isGoalEvent, isTurnQueueEvent, matchCommand, parseCommandLine, projectPendingApprovals, queueFromTurns, sessionDisplayTitle, sessionStatusFromEvents, shouldSubmitOnKey, stringifyPayload, toolDisplayName, truncate, tryParseJson, useAvailableModels, useBillingUsage, useComposer, useEnvironments, useFileAttachments, useGoal, useOpenGeni, useOpenGeniClient, usePacks, useScheduledTasks, useSession, useSessionControl, useSessionEvents, useSlashCommands, useTurnQueue, useWorkspaceSessions, useWorkspaces };
+export { ActivityDisclosure, type ActivityDisclosureProps, type ActivityItem, ActivityRail, type ActivityRailProps, type AgentMessageItem, type ApplyPatchOperation, BodyNote, ChatComposer, type ChatComposerProps, type ClientOverride, CodeEditor, type CodeEditorProps, type CommandContext, CommandPalette, type CommandPaletteProps, type CommandResult, type ComposerMode, type ComposerSendExtras, type ComposerState, type ConfirmState, type CreateToolRegistryOptions, DesktopViewer, type DesktopViewerProps, type DiffTheme, DiffView, type DiffViewProps, type DisclosureChip, DisclosureDefaultsProvider, type FileAttachment, FileBrowser, type FileBrowserProps, type FileTreeNode, type FileTreeStatus, FleetTile, type FleetTileProps, type GoalItem, LightboxProvider, Markdown, type MarkdownProps, MediaEmpty, MediaSkeleton, MessageTimeline, type MessageTimelineProps, ModelPicker, type ModelPickerProps, type Notice, type NoticeItem, type OpenGeniContextValue, OpenGeniProvider, type OpenGeniProviderProps, type ParsedCommandLine, PayloadBlock, type PendingApproval, PierreDiff, type PierreDiffProps, PierreFile, type PierreFileProps, type ReasoningItem, SESSION_STATUS_META, SandboxFiles, type SandboxFilesProps, type SandboxItem, SandboxTerminal, type SandboxTerminalProps, ScreenshotFigure, type SessionCapabilitiesState, type SessionClientLike, type SessionEventsConnectionState, SessionStatus, type SessionStatusItem, type SessionStatusMeta, type SessionStatusProps, type SlashArg, type SlashCommand, type SlashCommandContext, type SlashCommandHandlers, StatusDot, type StatusDotProps, TermBlock, type TerminalChunk, type TerminalStreamStatus, Thumbnail, type TimelineGroup, type TimelineItem, TimelineRow, type ToolCallItem, type ToolRegistry, type ToolRegistryEntry, type ToolRenderer, type ToolRendererProps, type TurnOutcome, TurnSummary, type TurnSummaryProps, type UseAvailableModelsOptions, type UseAvailableModelsResult, type UseBillingUsageOptions, type UseBillingUsageResult, type UseComposerOptions, type UseDesktopStreamOptions, type UseDesktopStreamResult, type UseEnvironmentsOptions, type UseEnvironmentsResult, type UseFileAttachmentsOptions, type UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UsePacksOptions, type UsePacksResult, type UseSandboxFilesOptions, type UseSandboxFilesResult, type UseSandboxGitOptions, type UseSandboxGitResult, type UseSandboxTerminalOptions, type UseSandboxTerminalResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionCapabilitiesOptions, type UseSessionCapabilitiesResult, type UseSessionControlOptions, type UseSessionControlResult, type UseSessionEventsOptions, type UseSessionEventsResult, type UseSessionOptions, type UseSessionResult, type UseSlashCommandsOptions, type UseSlashCommandsResult, type UseTerminalStreamOptions, type UseTerminalStreamResult, type UseTurnQueueOptions, type UseTurnQueueResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, type UserMessageItem, type WorkerItem, WorkspaceDock, type WorkspaceDockProps, type WorkspaceTab, type XtermTheme, activeTurnFromTurns, applyPatchOps, applyTurnEdit, applyTurnRemoval, applyTurnReorder, approvalsFromRequiresAction, argHint, buildTimeline, cn, composeSendInput, controlCaret, createDefaultToolRegistry, createToolRegistry, defaultCommands, defaultToolRegistry, execTruncated, extractSessionRef, filterCommands, firstMissingRequiredArg, formatBytes, formatRelativeTime, gitFileDiffToPatch, groupTimeline, hasPermission, isApplyPatch, isExecSessionLostBanner, isGoalEvent, isTitleEvent, isTurnQueueEvent, languageForPath, looksBinary, matchCommand, parseCommandLine, parseExecBannerSessionId, parseToolArgs, projectPendingApprovals, queueFromTurns, rawTypeOf, redactSecrets, sandboxCommandExitCode, sessionDisplayTitle, sessionStatusFromEvents, shouldSubmitOnKey, stringifyPayload, stripExecBanner, tailPeek, toolDisplayName, truncate, tryParseJson, unwrapMcpOutput, useAvailableModels, useBillingUsage, useComposer, useDesktopStream, useEnvironments, useFileAttachments, useGoal, useLightbox, useLightboxOptional, useOpenGeni, useOpenGeniClient, usePacks, useSandboxFiles, useSandboxGit, useSandboxTerminal, useScheduledTasks, useSession, useSessionCapabilities, useSessionControl, useSessionEvents, useSlashCommands, useTerminalStream, useTurnQueue, useWorkspaceSessions, useWorkspaces, v4aToGitFileDiff, xtermThemeFromTokens };