@opengeni/react 0.15.0 → 0.23.0

package/dist/index.d.ts

@@ -1,21 +1,30 @@
-import { C as ClientOverride, S as SessionClientLike } from './machines-BpdwuQcD.js';
-export { a as CONNECTION_STATUS_META, b as ConnectionDot, c as ConnectionDotProps, d as ConnectionStatus, e as ConnectionStatusMeta, f as ConnectionStatusPill, g as ConnectionStatusPillProps, D as DeviceFlowPhase, E as EnrollmentConsent, h as EnrollmentConsentMachine, i as EnrollmentConsentPhase, j as EnrollmentConsentProps, k as EnrollmentDeviceFlow, l as EnrollmentDeviceFlowProps, H as HEALTH_TOKEN, m as HealthLevel, n as HealthVerdict, M as MACHINE_STATE_BADGE_META, o as METRICS, p as METRIC_WINDOWS, q as MachineCard, r as MachineCardProps, s as MachineDetail, t as MachineDetailProps, u as MachineDockBar, v as MachineDockBarProps, w as MachineHealthPill, x as MachineHealthPillProps, y as MachineMetrics, z as MachineMetricsProps, A as MachineStateBadgeMeta, B as MachineStatusPill, F as MachineStatusPillProps, G as MachinesClientLike, I as MachinesDashboard, J as MachinesDashboardProps, K as MetricDef, L as MetricHistoryChart, N as MetricHistoryChartProps, O as MetricKey, P as MetricSparkline, Q as MetricSparklineProps, R as MetricWindow, T as OpenGeniContextValue, U as OpenGeniProvider, V as OpenGeniProviderProps, W as SeriesPoint, X as SharedMachineDisclosure, Y as SharedMachineDisclosureProps, Z as UseMachinesOptions, _ as UseMachinesResult, $ as WINDOW_LABEL, a0 as connectionStatusForState, a1 as deriveHealth, a2 as healthPulses, a3 as pointsFor, a4 as useMachines, a5 as useOpenGeni, a6 as useOpenGeniClient } from './machines-BpdwuQcD.js';
-import { SessionEvent, Session, ResourceRef, ToolRef, SessionStatus as SessionStatus$1, GitFileDiff, StreamConnectionState, EffectiveControlResumeOption, ComposerDraft, SendMessageInput, EffectiveSessionControl, FileAsset, FileResourceRef, SessionQueueSnapshot, SessionTurn, Permission, ClientModel, SessionGoal, SessionControlResponse, ScheduledTask, SessionLineageResponse, VariableSet, CreateVariableSetRequest, UpdateVariableSetRequest, VariableSetVariableMetadata, RigChange, Rig, UpdateRigRequest, RigVersion, ProposeRigChangeRequest, CreateRigRequest, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, SessionCapabilities, DesktopStreamCapability, DesktopConnectionState, DesktopRfbFactory, TerminalCapability, FsReadResponse, FsWriteResponse, WorkspaceCaptureManifest, WorkspaceCaptureDegradedReason, MachineState, CapabilityUnavailableReason, MachineView, CodexAccountsResponse, CodexAccount, CodexRotationSettings } from '@opengeni/sdk';
-export { MachineKind, MachineMetricsSeriesResponse, MachineState, MachineView, MachinesResponse, MetricSample } from '@opengeni/sdk';
+import { S as SessionClientLike, C as ClientOverride } from './session-context-rgrfElMl.js';
+export { a as EmbeddedHumanInputSessionClientLike, b as EmbeddedSessionClientLike, c as EmbeddedSessionMcpApprovalPolicyClientLike, O as OpenGeniContextValue, u as useOpenGeni, d as useOpenGeniClient } from './session-context-rgrfElMl.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { WorkspaceControlEvent, Session, SessionEvent, EffectiveSessionControl, ClientModel, SessionGoal, ScheduledTask, SessionLineageResponse, VariableSet, CreateVariableSetRequest, UpdateVariableSetRequest, VariableSetVariableMetadata, RigChange, Rig, UpdateRigRequest, RigVersion, ProposeRigChangeRequest, CreateRigRequest, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, SessionCapabilities, DesktopStreamCapability, DesktopConnectionState, DesktopRfbFactory, TerminalCapability, OpenGeniRequestOptions, FsReadResponse, FsWriteResponse, WorkspaceCaptureManifest, GitFileDiff, WorkspaceCaptureDegradedReason, MachineState, SessionHumanInputRequest, SubmitHumanInputResponseRequest, HumanInputQuestion, HumanInputAnswer, Permission, SessionStatus as SessionStatus$1, CapabilityUnavailableReason, MachineView, CodexAccountsResponse, CodexAccount, CodexRotationSettings } from '@opengeni/sdk';
+export { MachineKind, MachineMetricsSeriesResponse, MachineState, MachineView, MachinesResponse, MetricSample } from '@opengeni/sdk';
 import * as react from 'react';
-import { ComponentType, ReactNode, KeyboardEvent, ClipboardEvent, RefObject } from 'react';
+import { ReactNode, ClipboardEvent, RefObject, ComponentType } from 'react';
+import { S as SessionEventFeedOptions, C as ComposerState } from './use-composer-By1wn3MM.js';
+export { a as ComposerSendExtras, F as FILE_ONLY_MESSAGE_TEXT, U as UseComposerOptions, c as composeSendInput, s as shouldSteerOnKey, b as shouldSubmitOnKey, u as useComposer } from './use-composer-By1wn3MM.js';
+import { U as UseTurnQueueResult, P as PendingApproval, T as ToolCallItem, A as ActivityItem, a as TurnOutcome, b as TimelineItem, c as AgentMessageItem, d as UserMessageItem, e as AuthNeededItem } from './session-Db00TRwl.js';
+export { B as BrowserSessionEventWindow, G as GoalItem, N as NoticeItem, f as PendingHumanInputRequest, Q as QueueMutationKind, R as ReasoningItem, S as SESSION_EVENT_BROWSER_MAX_BYTES, g as SESSION_EVENT_BROWSER_MAX_COUNT, h as SESSION_EVENT_BROWSER_PENDING_MAX_BYTES, i as SESSION_EVENT_BROWSER_PENDING_MAX_COUNT, j as SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES, k as SandboxItem, l as SessionEventsConnectionState, m as SessionStatusItem, n as TimelineGroup, o as TurnEndItem, p as UseHumanInputRequestsOptions, q as UseHumanInputRequestsResult, r as UseSessionControlOptions, s as UseSessionControlResult, t as UseSessionEventsOptions, u as UseSessionEventsResult, v as UseSessionMcpApprovalPolicyOptions, w as UseSessionMcpApprovalPolicyResult, x as UseTurnQueueOptions, W as WorkerItem, y as approvalsFromRequiresAction, z as boundBrowserSessionEventWindow, C as buildTimeline, D as creditExhaustedFromEvents, E as extractSessionRef, F as groupTimeline, H as humanInputRequestFromEvent, I as isHumanInputEvent, J as isSessionMcpApprovalPolicyEvent, K as isTurnQueueEvent, L as projectPendingApprovals, M as projectPendingHumanInputRequests, O as sessionStatusFromEvents, V as toolDisplayName, X as useHumanInputRequests, Y as useSessionControl, Z as useSessionEvents, _ as useSessionMcpApprovalPolicy, $ as useTurnQueue } from './session-Db00TRwl.js';
+import { C as ComposerControlLinks, a as ComposerTranscriptionControlProps, U as UseFileAttachmentsResult, S as SlashCommand, b as SlashCommandContext, c as ChatComposerMessages, d as SlashArg, e as CommandContext } from './composer-CVm5uoUI.js';
+export { f as CommandResult, g as ComposerTranscriptionControl, h as ComposerTranscriptionMessages, i as ConfirmState, F as FileAttachment, I as INITIAL_TRANSCRIPTION_CONTROL_STATE, N as Notice, O as OPEN_WORKSTREAM_CONTROL_EVENT, j as SlashCommandHandlers, T as TranscriptionControlAction, k as TranscriptionControlState, l as TranscriptionControlTransition, m as UseFileAttachmentsOptions, n as UseSlashCommandsOptions, o as UseSlashCommandsResult, p as UseTranscriptionOptions, q as UseTranscriptionResult, r as appendFinalTranscript, s as defaultChatComposerMessages, t as transitionTranscriptionControl, u as useFileAttachments, v as useSlashCommands, w as useTranscription } from './composer-CVm5uoUI.js';
+export { CONNECTION_STATUS_META, ConnectionDot, ConnectionDotProps, ConnectionStatus, ConnectionStatusMeta, ConnectionStatusPill, ConnectionStatusPillProps, DeviceFlowPhase, EnrollmentConsent, EnrollmentConsentMachine, EnrollmentConsentPhase, EnrollmentConsentProps, EnrollmentDeviceFlow, EnrollmentDeviceFlowProps, HEALTH_TOKEN, HealthLevel, HealthVerdict, MACHINE_STATE_BADGE_META, METRICS, METRIC_WINDOWS, MachineCard, MachineCardProps, MachineDetail, MachineDetailProps, MachineDockBar, MachineDockBarProps, MachineHealthPill, MachineHealthPillProps, MachineMetrics, MachineMetricsProps, MachineStateBadgeMeta, MachineStatusPill, MachineStatusPillProps, MachinesClientLike, MachinesDashboard, MachinesDashboardProps, MetricDef, MetricHistoryChart, MetricHistoryChartProps, MetricKey, MetricSparkline, MetricSparklineProps, MetricWindow, SeriesPoint, SharedMachineDisclosure, SharedMachineDisclosureProps, UseMachinesOptions, UseMachinesResult, WINDOW_LABEL, connectionStatusForState, deriveHealth, healthPulses, pointsFor, useMachines } from './machines.js';
 import { ClassValue } from 'clsx';
 
-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 OpenGeniProviderProps = {
+    client: SessionClientLike;
+    workspaceId: string;
+    onWorkspaceControlEvent?: ((event: WorkspaceControlEvent) => void) | undefined;
+    children?: ReactNode;
 };
+/**
+ * Supplies the OpenGeni client + workspace to all hooks below it. Hooks also
+ * accept `{ client, workspaceId }` overrides per call for multi-workspace UIs.
+ */
+declare function OpenGeniProvider({ client, workspaceId, onWorkspaceControlEvent, children, }: OpenGeniProviderProps): react_jsx_runtime.JSX.Element;
 
 type UseSessionOptions = ClientOverride & SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
@@ -38,1939 +47,1390 @@ 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 = {
-    kind: "user-message";
-    id: string;
-    text: string;
-    /** Resources attached to this message (file uploads, repositories). */
-    resources: ResourceRef[];
-    /** Tools requested for the turn this message starts. */
-    tools: ToolRef[];
-    occurredAt: string;
-};
-type AgentMessageItem = {
-    kind: "agent-message";
-    id: string;
-    turnId: string | null;
-    text: string;
-    /** Still receiving deltas (no completed/turn-end seen yet). */
-    streaming: boolean;
-    occurredAt: string;
-};
-type ReasoningItem = {
-    kind: "reasoning";
-    id: string;
-    turnId: string | null;
-    text: string;
-    streaming: boolean;
-    occurredAt: string;
-};
-type ToolCallItem = {
-    kind: "tool-call";
-    id: string;
-    turnId: string | null;
-    callId: string | null;
-    name: string;
-    arguments: unknown;
-    output: unknown;
-    /**
-     * 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;
-};
-/**
- * An orchestration call against another session — the manager spawning or
- * messaging a worker. Rendered as a first-class "worker" row, not a generic
- * tool call.
- */
-type WorkerItem = {
-    kind: "worker";
-    id: string;
-    turnId: string | null;
-    callId: string | null;
-    action: "spawn" | "message";
-    /** The worker's initial message / the message sent to it, when parseable. */
-    prompt: string | null;
-    /** The target/spawned worker session id, when parseable from args/output. */
-    workerSessionId: string | null;
-    status: "running" | "complete" | "failed" | "cancelled";
-    occurredAt: string;
-};
-type WorkerCompletionItem = {
-    kind: "worker-completion";
-    id: string;
-    turnId: string | null;
-    occurredAt: string;
-    childSessionId: string;
-    childStatus: string;
-    goalStatus: string | null;
-    goalText: string | null;
-    evidence: string | null;
-    pausedReason: string | null;
-    text: string;
+/** The sole human prompt queue: compact above Goal, Agents, and composer. */
+type QueueSurfaceCommonProps = {
+    /** Focus the composer owned by this queue after checkout/removal. */
+    onRequestComposerFocus?: (() => void) | undefined;
 };
-type SandboxItem = {
-    kind: "sandbox";
-    id: string;
-    turnId: string | null;
-    name: string;
-    command: string | null;
-    output: string;
-    origin?: "created" | "restored" | "resumed" | null;
-    status: "running" | "complete" | "failed" | "cancelled";
-    occurredAt: string;
+type QueueSurfaceProps = (QueueSurfaceCommonProps & {
+    queue: UseTurnQueueResult;
+    composer: ComposerState;
+    readOnly?: false | undefined;
+}) | (QueueSurfaceCommonProps & {
+    queue: UseTurnQueueResult;
+    composer?: undefined;
+    readOnly: true;
+});
+
+/** The sole human prompt queue: compact above Goal, Agents, and composer. */
+declare const QueueSurface: (props: QueueSurfaceProps) => react_jsx_runtime.JSX.Element | null;
+
+type ChatComposerProps = {
+    composer: ComposerState;
+    /** Canonical workstream control, separate from lifecycle status. */
+    effectiveControl?: EffectiveSessionControl | null | undefined;
+    /** Waiting prompts already ahead of a normal Send. */
+    queuedAheadCount?: number | undefined;
+    /** Whether broader Workspace Resume is authorized for this viewer. */
+    canControlWorkspace?: boolean | undefined;
+    /** Optional host routes used to navigate from effective Pause blockers. */
+    controlLinks?: ComposerControlLinks | undefined;
+    placeholder?: string | undefined;
+    disabled?: boolean | undefined;
+    autoFocus?: boolean | undefined;
+    /** Replaces the default keyboard hint under the field. */
+    hint?: string | undefined;
+    /** App controls in the footer row, replacing the hint. */
+    controlsStart?: ReactNode | undefined;
+    /** Provider-neutral speech capability. Provider configuration stays in workspace settings. */
+    transcription?: ComposerTranscriptionControlProps | undefined;
+    /** Content rendered above the textarea, inside the field chrome. */
+    header?: ReactNode | undefined;
+    /** Paste hook composed with the attachment paste path. */
+    onPaste?: ((event: ClipboardEvent<HTMLTextAreaElement>) => void) | undefined;
+    /** Opt-in file attachment state, typically from `useFileAttachments`. */
+    attachments?: UseFileAttachmentsResult | undefined;
+    /** Opt-in model picker choices. */
+    models?: ClientModel[] | undefined;
+    selectedModel?: string | undefined;
+    onSelectModel?: ((modelId: string) => void) | undefined;
+    className?: string | undefined;
+    commands?: readonly SlashCommand[] | undefined;
+    commandContext?: SlashCommandContext | undefined;
+    onClearView?: (() => void) | undefined;
+    /** Partial overrides for all composer-owned visible and accessible copy. */
+    messages?: Partial<ChatComposerMessages> | undefined;
 };
 /**
- * A first-party workspace-memory write the agent made mid-turn — a `memory.saved`
- * (it committed a new preference / fact / procedure / decision / history) or a
- * `memory.corrected` (it updated or archived an existing one). A settled save is
- * ordinary progress, not an exceptional state, so it renders as a calm NEUTRAL
- * step on the rail (never accent/color). When the host app supplies an
- * `onMemoryClick` handler the row also deep-links to the record in its memory
- * pane; without one it is non-interactive rich content.
+ * Batteries-included chat composer. This preset is assembled exclusively from
+ * the public controller and compound primitives exported by the composer
+ * subpath, so custom and default layouts share one behavioral implementation.
  */
-type MemoryItem = {
-    kind: "memory";
-    id: string;
-    turnId: string | null;
-    variant: "saved" | "corrected";
-    /** The memory's kind enum (`"preference" | "semantic" | …`); mapped to a human label at render. */
-    memoryKind: string;
-    /** The memory text, ellipsized to ≤120 chars server-side. For a supersede this is the OLD text. */
-    preview: string;
-    /** The save collapsed into an existing memory (no new row was written). Saved variant only. */
-    deduped?: boolean;
-    /** The NEW text when a correction superseded the memory with a replacement; absent = updated-in-place or archived. */
-    replacementPreview?: string;
-    /**
-     * What a `memory.corrected` did: `"superseded"` (replaced by a new record, see
-     * `replacementPreview`), `"updated"` (edited in place — the record lives on), or
-     * `"archived"` (retired). Distinguishes updated-in-place from archived when there
-     * is no replacement. Corrected variant only; read defensively (may be absent).
-     */
-    action?: string;
-    /** The saved / corrected memory's id — the deep-link target for a save. */
-    memoryId: string;
-    /** The replacement memory's id when a correction produced one — the LIVE record the deep-link targets. */
-    replacementMemoryId?: string;
-    occurredAt: string;
-};
-type SessionStatusItem = {
-    kind: "session-status";
-    id: string;
-    status: SessionStatus$1;
-    occurredAt: string;
-};
-type GoalItem = {
-    kind: "goal";
-    id: string;
-    action: "set" | "updated" | "completed" | "paused" | "resumed" | "cleared" | "continuation";
-    text: string | null;
-    occurredAt: string;
+declare function ChatComposer({ composer, effectiveControl, queuedAheadCount, canControlWorkspace, controlLinks, placeholder, disabled, autoFocus, hint, controlsStart, transcription, header, onPaste, attachments, models, selectedModel, onSelectModel, className, commands, commandContext, onClearView, messages, }: ChatComposerProps): react_jsx_runtime.JSX.Element;
+
+/** Event types that change the session goal (set/updated/completed/paused/...). */
+declare function isGoalEvent(event: Pick<SessionEvent, "type">): boolean;
+type UseGoalOptions = ClientOverride & SessionEventFeedOptions & {
+    /** Optional safety-net polling (ms). Off by default — goal.* events drive updates. */
+    pollIntervalMs?: number | undefined;
 };
-type NoticeItem = {
-    kind: "notice";
-    id: string;
-    tone: "waiting" | "cancelled" | "failed";
-    text: string;
-    /** Optional evidence kept inspectable without overwhelming the main rail. */
-    details?: {
-        label: string;
-        value: unknown;
-    };
-    action?: {
-        label: string;
-        url: string;
-    };
-    occurredAt: string;
-};
-/**
- * A tool call hit a connection whose credential lapsed — the broker asked the
- * user to reconnect the provider before the turn can continue. Carries the
- * structured `tool.auth_needed` payload so the renderer can draw a clean inline
- * reconnect affordance (provider logo + one human line + a Reconnect button)
- * and the app can start the right recovery flow (OAuth reconnect for the
- * surviving connection, or credential re-entry for an api-key one). The `reason`
- * shapes the human copy but is never shown raw.
- */
-type AuthNeededItem = {
-    kind: "auth-needed";
-    id: string;
-    turnId: string | null;
-    /** The connection's registrable domain, e.g. "linear.app". */
-    providerDomain: string;
-    /** The lapsed connection to reconnect, when the row survived. */
-    connectionId: string | null;
-    reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed" | null;
-    /** Scopes the provider now needs; may inform the copy, never shown as a raw label. */
-    scopes: string[];
-    /** The OAuth `resource` (RFC 8707) the reconnect should target, when supplied. */
-    resource: string | null;
-    /** The tool whose call triggered the reauth, for context. */
-    toolName: string | null;
-    /** A pre-minted authorization URL, when the broker already produced one. */
-    authorizationUrl: string | null;
-    occurredAt: string;
-};
-type TurnOutcome = "complete" | "failed" | "cancelled";
-type TurnEndItem = {
-    kind: "turn-end";
-    id: string;
-    turnId: string | null;
-    outcome: TurnOutcome;
-    failureText: string | null;
-    occurredAt: string;
-};
-type TimelineItem = UserMessageItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | WorkerCompletionItem | SandboxItem | SessionStatusItem | GoalItem | NoticeItem | AuthNeededItem | MemoryItem | TurnEndItem;
-/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
-type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | MemoryItem;
-type TimelineGroup = {
-    kind: "item";
-    item: TimelineItem;
-} | {
-    kind: "activity";
-    id: string;
-    items: ActivityItem[];
-    outcome?: TurnOutcome;
-    failureText?: string;
-} | {
-    kind: "turn";
-    id: string;
-    outcome: TurnOutcome;
-    failureText?: string;
-    startedAt: string;
-    endedAt: string;
-    groups: TimelineGroup[];
+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;
 };
-
-declare function buildTimeline(events: SessionEvent[]): TimelineItem[];
-/**
- * Whether the session's most recent turn ended in credit exhaustion — the
- * terminal credit state apps key their "add credits" affordances on. Derived
- * from the LAST turn-end event (completed/failed/cancelled): a later turn that
- * settles any other way (someone topped up and kept working) clears it.
- */
-declare function creditExhaustedFromEvents(events: SessionEvent[]): boolean;
-/** 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
- * objects, JSON strings, and MCP tool results (`{ content: [{ type: "text",
- * text: "{...}" }], structuredContent? }`).
+ * 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.*` events —
+ * pass `options.events` from `useSessionEvents` to reuse its stream.
  */
-declare function extractSessionRef(value: unknown, depth?: number): string | null;
-/**
- * Readable label for a tool call ("session_create" -> "session create").
- *
- * MCP tools are namespaced `<serverId>__<toolName>` (see prefixedMcpToolName),
- * and for catalog-imported servers that serverId is an opaque slug+hash
- * ("mcp-integrations-sh-supabase-com-34ed9dcf1390-0i6tcf8"). De-slugging the
- * whole thing leaked that id into the timeline; strip the server prefix and show
- * just the tool ("list organizations"). Names without the `__` boundary (plain
- * built-ins like "session_create") are unaffected.
- */
-declare function toolDisplayName(name: string): string;
+declare function useGoal(sessionId: string | null | undefined, options?: UseGoalOptions): UseGoalResult;
 
-type ToolRendererProps = {
-    item: ToolCallItem;
+type UseScheduledTasksOptions = ClientOverride & {
+    limit?: number | undefined;
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
 };
-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 UseScheduledTasksResult = {
+    tasks: ScheduledTask[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
 };
-type ToolRegistry = {
-    /** Resolve the renderer for a call (never null — falls back to generic). */
-    resolve: (item: ToolCallItem) => ToolRenderer;
-    /** The generic fallback renderer. */
-    fallback: ToolRenderer;
+/** List the workspace's scheduled tasks (drift checks, sentinels, reapers, ...). */
+declare function useScheduledTasks(options?: UseScheduledTasksOptions): UseScheduledTasksResult;
+
+type UseWorkspaceSessionsOptions = ClientOverride & {
+    limit?: number | undefined;
+    parentSessionId?: string | null | undefined;
+    cursor?: string | undefined;
+    search?: string | undefined;
+    /** Refresh interval (ms) for fleet/manager views. Off by default. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
 };
-type CreateToolRegistryOptions = {
+type UseWorkspaceSessionsResult = {
     /**
-     * Entries that take precedence over the built-ins. Earlier entries win, so a
-     * consumer can shadow a default renderer for the same key.
+     * All visible rows, with pins first. This preserves the pre-pinning hook
+     * contract for consumers that only read `sessions`.
      */
-    entries?: ToolRegistryEntry[] | undefined;
-    /** Replace the generic fallback used for unmatched tools. */
-    fallback?: ToolRenderer | undefined;
+    sessions: Session[];
+    /** The complete personal pinned section, also present in `sessions`. */
+    pinned: Session[];
+    /** True when the server omitted older pins from its bounded pinned section. */
+    pinnedTruncated: boolean;
+    nextCursor: string | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
 };
-/** 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;
+/** List the workspace's sessions — the data behind fleet and manager views. */
+declare function useWorkspaceSessions(options?: UseWorkspaceSessionsOptions): UseWorkspaceSessionsResult;
 
-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;
-    /**
-     * Deep-link a memory row to its record in the host's memory pane. Opt-in: the
-     * library draws no "View in memory" affordance without a handler (the memory
-     * row is then non-interactive rich content). See {@link MessageTimelineProps}.
-     */
-    onMemoryClick?: ((memoryId: string) => void) | undefined;
-    /** Drop the left rule + indent (used inside a folded turn summary). */
-    bare?: boolean | undefined;
-    className?: string | undefined;
+type UseSessionLineageOptions = ClientOverride & {
+    events?: SessionEvent[] | undefined;
+    /** Refresh interval (ms). Off by default. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
 };
-declare function ActivityRail({ items, toolRegistry, onOpenSession, onMemoryClick, bare, className, }: ActivityRailProps): react_jsx_runtime.JSX.Element;
+type UseSessionLineageResult = {
+    lineage: SessionLineageResponse | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+declare function isLineageRefreshEvent(event: SessionEvent): boolean;
+/** Read the ancestors + descendant tree for one session. Data-only; no UI state. */
+declare function useSessionLineage(sessionId: string | null | undefined, options?: UseSessionLineageOptions): UseSessionLineageResult;
 
+type UseVariableSetsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+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;
+};
 /**
- * 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.
+ * 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.
  */
-type DisclosureChip = {
-    tone: "ok" | "bad" | "muted" | "interrupted";
-    text: string;
+declare function useVariableSets(options?: UseVariableSetsOptions): UseVariableSetsResult;
+/** @deprecated use UseVariableSetsOptions */
+type UseEnvironmentsOptions = UseVariableSetsOptions;
+/** @deprecated use UseVariableSetsResult */
+type UseEnvironmentsResult = UseVariableSetsResult & {
+    environments: VariableSet[];
 };
-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;
+/** @deprecated use useVariableSets */
+declare function useEnvironments(options?: UseEnvironmentsOptions): UseEnvironmentsResult;
+
+type UseRigsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+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;
 };
 /**
- * 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, failed, }: {
-    /**
-     * 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;
-    /** A non-zero exit / failed call — tints the left accent red (the one hue). */
-    failed?: 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.
+ * 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).
  */
-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;
+declare function useRigs(options?: UseRigsOptions): UseRigsResult;
+type UseRigOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+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 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.
+ * 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`).
  */
-declare function Thumbnail({ src, caption, alt, }: {
-    src: string;
-    caption?: string | undefined;
-    alt?: string;
-}): react_jsx_runtime.JSX.Element;
+declare function useRig(rigId: string, options?: UseRigOptions): UseRigResult;
+type UseRigVersionsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseRigVersionsResult = {
+    versions: RigVersion[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** A rig's append-only version history, newest-first (polled). */
+declare function useRigVersions(rigId: string, options?: UseRigVersionsOptions): UseRigVersionsResult;
+type UseRigChangesOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseRigChangesResult = {
+    changes: RigChange[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
 /**
- * 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`.
+ * A rig's change queue (polled). The default poll cadence lets a change move
+ * through verifying → merged/rejected without a manual refresh.
  */
-declare function ScreenshotFigure({ src, caption, alt, }: {
-    src: string;
-    caption?: string | undefined;
-    alt?: string;
-}): react_jsx_runtime.JSX.Element;
+declare function useRigChanges(rigId: string, options?: UseRigChangesOptions): UseRigChangesResult;
 
-type LightboxController = {
-    open: (src: string, caption?: string) => void;
+type UsePacksOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
 };
-/** 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;
+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. */
+declare function usePacks(options?: UsePacksOptions): UsePacksResult;
 
+type UseWorkspacesOptions = Pick<ClientOverride, "client"> & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseWorkspacesResult = {
+    workspaces: Workspace[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateWorkspaceRequest) => Promise<Workspace | null>;
+    update: (workspaceId: string, request: UpdateWorkspaceRequest) => Promise<Workspace | null>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
 /**
- * Seed the initial open state of every timeline collapsible below this node.
- * Intended for screenshot/test instrumentation only; absent by default.
+ * The caller's workspaces (workspace switchers, onboarding). Not scoped to
+ * the provider's workspace, so it only needs the client.
  */
-declare function DisclosureDefaultsProvider({ defaultOpen, children, }: {
-    defaultOpen: boolean;
-    children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-
-type TurnSummaryProps = {
-    /** The activity items in the turn (used only to compute the facet counts). */
-    items: ActivityItem[];
-    /**
-     * The settled verdict — or absent for a completed CLUSTER of a still-running
-     * turn, which folds neutrally: no verdict glyph (the turn has none yet), a
-     * quiet pulse dot in its place so alignment and the running feel both hold.
-     */
-    outcome?: TurnOutcome | undefined;
-    /** A short failure reason shown inline on a failed chip (never hidden). */
-    failureText?: string | undefined;
-    /** Elapsed turn duration; shown as a trailing facet when at least 1s. */
-    durationMs?: number | undefined;
-    /** Start expanded. */
-    defaultOpen?: boolean | undefined;
-    /**
-     * A nested fold — a cluster or sub-turn INSIDE an already-expanded turn. It
-     * drops the bordered/filled chip and renders as a plain disclosure node on the
-     * parent's rail (chevron + glyph + facets), so expanding a turn reveals a thread
-     * of nodes, never a stack of boxes-in-boxes. The top-level fold stays a chip.
-     */
-    bare?: boolean | undefined;
-    /** The rendered activity rail revealed on expand. */
-    children: React.ReactNode;
-};
-declare function TurnSummary({ items, outcome, failureText, durationMs, defaultOpen, bare, 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;
-};
+declare function useWorkspaces(options?: UseWorkspacesOptions): UseWorkspacesResult;
 
-type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
-type UseSessionEventsOptions = ClientOverride & {
-    /** Resume after this sequence (exclusive). Nonzero keeps full replay/resume semantics. */
-    after?: number | undefined;
-    /** Load a bounded tail by default, or opt back into full replay from `after`. */
-    replay?: "windowed" | "full" | undefined;
-    /** Pause the stream without unmounting (e.g. hidden tab). Defaults to true. */
+type UseBillingUsageOptions = Pick<ClientOverride, "client"> & {
+    /** Account to read. Defaults to the caller's default account server-side. */
+    accountId?: string | undefined;
+    /** Filter usage to one workspace. */
+    workspaceId?: string | undefined;
+    /** Refresh interval (ms) for live billing meters. Off by default. */
+    pollIntervalMs?: number | undefined;
     enabled?: boolean | undefined;
 };
-type UseSessionEventsResult = {
-    /** Replayed + live events, ordered by sequence, no gaps, no duplicates. */
-    events: SessionEvent[];
-    /** Projected, renderable timeline (memoized over `events`). */
-    timeline: TimelineItem[];
-    /** Latest session status observed in the event log, if any. */
-    sessionStatus: SessionStatus$1 | null;
-    connectionState: SessionEventsConnectionState;
-    /** Highest sequence seen so far (0 before the first event). */
-    lastSequence: number;
-    /** True until the initial tail window has been applied (windowed mode). */
-    initialLoading: boolean;
-    /** Whether older durable events are available before the current window. */
-    hasOlder: boolean;
-    /** True while an older window is being fetched. */
-    loadingOlder: boolean;
-    /** Prepend an older density-bounded window; resolves true when more remain. */
-    loadOlder: () => Promise<boolean>;
-    error: Error | null;
-};
-/**
- * Live-stream a session's event log with replay-by-sequence, reconnect, and
- * batched React updates. Fresh loads default to a bounded tail window; pass
- * `replay: "full"` or a nonzero `after` for the previous full replay path.
- */
-declare function useSessionEvents(sessionId: string | null | undefined, options?: UseSessionEventsOptions): UseSessionEventsResult;
-
-type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
-type UseComposerOptions = ClientOverride & SessionEventFeedOptions & {
-    /** Called with the accepted text after a successful send. */
-    onSent?: ((text: string) => void) | undefined;
-    /**
-     * Extra message fields (resources, tools, model, reasoningEffort) merged
-     * into every send. A function is evaluated at send time so it can read the
-     * surrounding UI state (attachment pickers, model selectors, ...).
-     */
-    sendExtras?: ComposerSendExtras | (() => ComposerSendExtras) | undefined;
-    /** Latest server-derived workstream control; bound into Send/Steer OCC. */
-    effectiveControl?: EffectiveSessionControl | null | undefined;
-    /** Apply durable model/tool/reasoning settings in the host's controlled UI. */
-    onDraftApplied?: ((draft: ComposerDraft) => void) | undefined;
-};
-type ComposerState = {
-    value: string;
-    setValue: (value: string) => void;
-    /** Append the draft behind prompts already visible in the queue. */
-    send: (text?: string) => Promise<boolean>;
-    /** Supersede current direction with the draft. */
-    steer: (text?: string) => Promise<boolean>;
-    sending: boolean;
-    canSend: boolean;
-    /** Pause the session without deleting its prompt queue. */
-    pause: (reason?: string) => Promise<void>;
-    pausing: boolean;
-    resume: (reason?: string) => Promise<void>;
-    resumeScope: (option: EffectiveControlResumeOption) => Promise<void>;
-    resuming: boolean;
-    draft: ComposerDraft | null;
-    draftRevision: number;
-    draftLoading: boolean;
-    draftSaving: boolean;
-    draftConflict: Error | null;
-    /** Apply an atomic queue Edit checkout without a second read. */
-    applyDraft: (draft: ComposerDraft) => void;
-    reloadDraft: () => Promise<void>;
-    resolveDraftConflict: (choice: "keep_mine" | "use_remote") => Promise<void>;
-    restoredResources: ResourceRef[];
-    removeRestoredResource: (index: number) => void;
+type UseBillingUsageResult = {
+    /** Prepaid credit balance (micro-USD), null until loaded. */
+    balance: BillingBalance | null;
+    /** Recent usage events (runs, tokens, cost, uploads, ...). */
+    usage: UsageEvent[];
+    loading: boolean;
     error: Error | null;
-    clearError: () => void;
+    refresh: () => Promise<void>;
 };
 /**
- * Draft + send + Pause/Resume state for the chat composer — the only
- * human-to-agent input surface. The draft survives a failed send (nothing is
- * more hostile than losing a typed message); each send carries a generated
- * `clientEventId` so retries stay idempotent server-side.
- */
-declare function useComposer(sessionId: string | null | undefined, options?: UseComposerOptions): ComposerState;
-/**
- * Default text for a file-only message (attachment(s) present, no typed draft).
- * Kept non-empty so the wire contract (`text: z.string().min(1)`) and the
- * worker's non-whitespace guard accept it; the attached files still ride in
- * `resources`. Exported for tests.
- */
-declare const FILE_ONLY_MESSAGE_TEXT = "(see attached files)";
-/**
- * Merge the draft text + idempotency key with caller-provided extras. The
- * text and clientEventId always win over extras. Exported for tests.
+ * Account billing usage: credit balance + recent usage events — the data
+ * behind per-call billing meters. Account-scoped, so it only needs the
+ * client; pass `workspaceId` to narrow usage to one workspace.
  */
-declare function composeSendInput(text: string, clientEventId: string, extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined, bound?: Partial<SendMessageInput>): SendMessageInput;
-/** Submit on plain Enter; Shift+Enter inserts a newline. Exported for tests. */
-declare function shouldSubmitOnKey(event: {
-    key: string;
-    shiftKey: boolean;
-    metaKey?: boolean;
-    ctrlKey?: boolean;
-    nativeEvent?: {
-        isComposing?: boolean;
-    };
-}): boolean;
-/** Cmd/Ctrl+Enter steers; ordinary Enter appends to the queue. */
-declare function shouldSteerOnKey(event: {
-    metaKey?: boolean;
-    ctrlKey?: boolean;
-}): boolean;
-
-type UseFileAttachmentsOptions = ClientOverride & {
-    /**
-     * Only files matching this predicate are accepted by {@link
-     * UseFileAttachmentsResult.addFromPaste} (the clipboard path). Defaults to
-     * `image/*` — the console's historical paste filter. {@link
-     * UseFileAttachmentsResult.addFiles} (the explicit picker / drop path)
-     * bypasses it.
-     */
-    pasteFilter?: ((file: File) => boolean) | undefined;
-};
-type FileAttachment = {
-    id: string;
-    name: string;
-    contentType: string;
-    sizeBytes: number;
-    status: "uploading" | "ready" | "failed";
-    /** The SDK `FileAsset` once the upload finishes. */
-    file?: FileAsset | undefined;
-    /** Object-URL for an inline preview; minted for `image/*` files only. */
-    previewUrl?: string | undefined;
-    error?: string | undefined;
-};
-type UseFileAttachmentsResult = {
-    attachments: FileAttachment[];
-    /**
-     * `FileResourceRef[]` for every attachment that finished uploading — feed
-     * straight into `useComposer`'s `sendExtras.resources`.
-     */
-    readyResources: FileResourceRef[];
-    /** True while any attachment is still uploading (drives the send-gate). */
-    uploading: boolean;
-    /** Explicit picker / drop path — uploads every file, no filter. */
-    addFiles: (files: Iterable<File>) => void;
-    /** Clipboard path — applies `pasteFilter` (default `image/*`) then uploads. */
-    addFromPaste: (event: {
-        clipboardData: DataTransfer | null;
-    }) => void;
-    /**
-     * Re-run the upload for a `failed` attachment, in place (same id, same
-     * source file). No-op for an id that isn't a known failed upload.
-     */
-    retry: (id: string) => void;
-    /** Remove one attachment; revokes its object-URL. */
-    remove: (id: string) => void;
-    /** Remove all; revokes every object-URL. Call from `useComposer`'s `onSent`. */
-    clear: () => void;
-};
-/**
- * Upload-and-track state for files attached to the next message. Owns the
- * full client-side upload layer: a per-file `uploading | ready | failed`
- * status machine driven by the SDK's `client.uploadFile`, object-URL image
- * previews with create/revoke lifecycle, the `image/*` clipboard paste filter,
- * and a `FileResourceRef[]` projection that drops straight into a message's
- * `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;
+declare function useBillingUsage(options?: UseBillingUsageOptions): UseBillingUsageResult;
 
-/** Events that can change the authoritative prompt queue or effective control. */
-declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
-type QueueMutationKind = "move" | "edit" | "steer" | "delete";
-type UseTurnQueueOptions = ClientOverride & SessionEventFeedOptions & {
+type UseAvailableModelsOptions = Pick<ClientOverride, "client"> & {
+    /** Refresh interval (ms). Off by default — the host model list rarely moves. */
     pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
 };
-type UseTurnQueueResult = {
-    snapshot: SessionQueueSnapshot | null;
-    /** Human/API prompts exactly in server execution order. Never client-sorted. */
-    queue: SessionTurn[];
-    effectiveControl: EffectiveSessionControl | null;
+type UseAvailableModelsResult = {
+    /** The provider-grouped models the host exposes (empty until loaded). */
+    models: ClientModel[];
+    /** The deployment's default model id, null until loaded. */
+    defaultModel: string | null;
     loading: boolean;
     error: Error | null;
     refresh: () => Promise<void>;
-    moveTurn: (turnId: string, beforeTurnId: string | null) => Promise<boolean>;
-    /** Atomically withdraw a waiting prompt into the private durable composer draft. */
-    editTurn: (turnId: string, options: {
-        expectedDraftRevision: number;
-        replaceDraft: boolean;
-    }) => Promise<ComposerDraft | null>;
-    /** Advance the same durable waiting prompt; no duplicate prompt is created. */
-    steerTurn: (turnId: string) => Promise<boolean>;
-    removeTurn: (turnId: string) => Promise<boolean>;
-    pendingByTurn: Readonly<Record<string, QueueMutationKind>>;
-    mutationFor: (turnId: string) => QueueMutationKind | null;
-    mutating: boolean;
-    mutationError: Error | null;
-    clearMutationError: () => void;
 };
 /**
- * The one authoritative human prompt queue. Every mutation carries the exact
- * server versions the operator saw and accepts only monotonic snapshots. A
- * conflict immediately reloads server truth; the client never invents order.
+ * The host-exposed model list for a <ModelPicker>: fetches the deployment's
+ * public client config (`GET /v1/config/client`) and surfaces the richer
+ * provider-grouped `models` plus the `defaultModel` the picker should preselect.
+ * Deployment-scoped, so it only needs the client (no workspace).
  */
-declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;
-
-/** The sole human prompt queue: compact above Goal, Agents, and composer. */
-type QueueSurfaceProps = {
-    queue: UseTurnQueueResult;
-    composer: ComposerState;
-    readOnly?: false | undefined;
-} | {
-    queue: UseTurnQueueResult;
-    composer?: undefined;
-    readOnly: true;
-};
-declare function QueueSurface({ queue, composer, readOnly }: QueueSurfaceProps): react_jsx_runtime.JSX.Element | null;
+declare function useAvailableModels(options?: UseAvailableModelsOptions): UseAvailableModelsResult;
 
-/**
- * The slash-command registry. A command is a SESSION / OPERATOR control — an
- * action on the session or the UI (clear, compact, pause the goal, show help) —
- * NOT a structured way to talk to the agent. The human↔agent channel stays
- * plain chat; the palette only recognizes a leading "/" and never sends a
- * command to the model.
- *
- * Two kinds, modeled by where the handler does its work:
- *  - CLIENT commands touch only the local UI (e.g. /help, /clear-view).
- *  - SERVER commands call the API through the SDK (e.g. /clear, /compact,
- *    /goal).
- * Both are just `run(args, ctx)`; `ctx` exposes the client for server commands
- * and the UI affordances (notice, openHelp, clearView, confirm) for both.
- */
-/** A positional argument a command accepts after its name. */
-type SlashArg = {
-    name: string;
-    /** Enter runs only once every required arg is present; otherwise autocompletes. */
-    required?: boolean;
-    /** Closed value set (rendered as a hint; validated by the command itself). */
-    oneOf?: readonly string[];
-    description?: string;
-};
-/** Transient feedback surfaced in the composer (generalized error line). */
-type Notice = {
-    tone: "ok" | "error";
-    message: string;
-};
-/** Everything a command handler can reach. Assembled by the composer. */
-type CommandContext = {
-    /** SDK-shaped client for server commands. */
-    client: SessionClientLike;
-    workspaceId: string;
-    /** Null before a session exists (server commands should guard on this). */
-    sessionId: string | null;
-    status: SessionStatus$1 | null;
-    /** The operator's permissions on this workspace (gates command visibility). */
-    permissions: Permission[];
-    /** Surface a transient ok/error notice in the composer. */
-    notice: (notice: Notice) => void;
-    /** Open the in-composer /help panel (rendered from the registry). */
-    openHelp: () => void;
+type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "on-demand" | "error";
+type UseSessionCapabilitiesOptions = ClientOverride & {
     /**
-     * Reset only the LOCAL timeline view — no server call. Returns whether a
-     * view-reset affordance was actually wired (and thus had an effect): the host
-     * surface supplies one via the composer's `onClearView` prop, and consoles
-     * that don't (no resettable local timeline) get `false`. The /clear-view
-     * command uses this to avoid reporting a false "cleared" success on a no-op.
+     * 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.
      */
-    clearView: () => boolean;
-    /** Show the danger confirm bar; resolves true once the operator confirms. */
-    confirm: () => Promise<boolean>;
-};
-type CommandResult = {
-    status: "ok" | "error";
-    message?: string;
+    events?: SessionEvent[] | undefined;
     /**
-     * Keep the composer draft instead of clearing it on an ok result. Used when a
-     * command resolves to a no-op the operator may want to retry — e.g. canceling
-     * the /clear confirm bar returns ok (no error) but must NOT wipe the typed
-     * "/clear" draft. Default false: a successful command clears the draft.
+     * 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.
      */
-    keepDraft?: boolean;
-};
-type SlashCommand = {
-    /** Primary token after the slash (no leading "/"). */
-    name: string;
-    /** Alternate tokens that resolve to this command. */
-    aliases?: readonly string[];
-    description: string;
-    args?: readonly SlashArg[];
-    /** Required permission; the command is hidden from the palette without it. */
-    permission?: Permission;
-    /** Destructive — the palette shows a confirm bar before running. */
-    danger?: boolean;
+    attachDesktop?: boolean | undefined;
     /**
-     * Dynamic availability beyond the permission gate (e.g. hide a server command
-     * until a session exists). Returning false hides the command.
+     * 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.
      */
-    available?: (ctx: Pick<CommandContext, "sessionId" | "status" | "permissions">) => boolean;
-    /** Execute the command. Throwing is caught and surfaced as an error notice. */
-    run: (args: string[], ctx: CommandContext) => Promise<CommandResult> | CommandResult;
-};
-
-/**
- * Context the composer supplies for command execution and visibility. The
- * composer owns the UI affordances (notice/openHelp/clearView/confirm), so they
- * are NOT part of this slice — the hook closes over them via `handlers`.
- */
-type SlashCommandContext = Pick<CommandContext, "client" | "workspaceId" | "sessionId" | "status" | "permissions">;
-/**
- * UI affordances the composer supplies. `confirm` differs from the registry-
- * facing {@link CommandContext.confirm} (which takes no args): the composer's
- * confirm receives the command being run so the confirm bar renders from that
- * exact command's identity. The hook bridges the two in {@link buildContext}.
- */
-type SlashCommandHandlers = Pick<CommandContext, "notice" | "openHelp" | "clearView"> & {
-    confirm: (command: SlashCommand) => Promise<boolean>;
-};
-type ConfirmState = {
-    command: SlashCommand;
-    /** Resolve the pending confirm() promise. */
-    resolve: (confirmed: boolean) => void;
-} | null;
-type UseSlashCommandsOptions = {
-    commands: readonly SlashCommand[];
-    context: SlashCommandContext | undefined;
-    handlers: SlashCommandHandlers;
-    /** The current composer draft. */
-    value: string;
-    /** Replace the composer draft (autocomplete writes through this). */
-    setValue: (value: string) => void;
-};
-type UseSlashCommandsResult = {
-    /** Whether the palette is open (a command token is being typed). */
-    open: boolean;
+    attachTerminal?: boolean | undefined;
     /**
-     * Whether the draft is a slash-command attempt (matches a registered command)
-     * — true even after Escape dismisses the popover. The composer blocks its send
-     * path while this holds so a command can't be delivered to the agent as chat.
+     * Whether to acquire a viewer holder to warm the box for a FILE WRITE — the
+     * wake-on-edit INTENT (a first keystroke in the editor), NOT passive browsing.
+     * Shares the SAME viewer attach as the desktop/terminal (one warm box, one
+     * holder) and — like the terminal — needs NO un-redacted acknowledgment:
+     * reading/writing files is the ordinary Channel-A control plane, not the pixel
+     * plane. It folds NO live URL (files ride the stateless HTTP plane) — it only
+     * refcounts liveness. Unlike desktop/terminal it warms even a COLD box: an edit
+     * legitimately cold-creates (that IS the wake), so the write lands ~100ms warm
+     * instead of paying the ~5s cold resume. Default false. IMPORTANT: merely
+     * opening/reading the Files tab must NOT set this — browsing capture-served
+     * trees/diffs needs no box, and warming one on a cold glance burns box-hours to
+     * serve reads the capture already answers for free.
      */
-    isCommandDraft: boolean;
-    /** Commands shown for the current token + context, in display order. */
-    items: SlashCommand[];
-    /** Index into `items` of the highlighted row. */
-    highlight: number;
-    setHighlight: (index: number) => void;
-    /** The matched command once the name is closed by a space (arg-hint mode). */
-    activeCommand: SlashCommand | null;
-    /** The arg hint string for the active command (footer), or "". */
-    activeArgHint: string;
+    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;
     /**
-     * Key handler for the textarea. Returns true when it consumed the event
-     * (the composer must then NOT run its send path). Only consumes while open.
+     * Give up waiting for `warm` after this long while polling (ms) and surface a
+     * stalled error with a manual `renegotiate`. Default 30000. This is a UI
+     * patience deadline, independent from the worker's sandbox warming timeout.
+     * 0 disables the deadline.
      */
-    onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => boolean;
-    /** Run the highlighted command (or the active command in arg-hint mode). */
-    runHighlighted: () => Promise<void>;
+    warmingDeadlineMs?: number | undefined;
+};
+type UseSessionCapabilitiesResult = {
+    /** The negotiated capability doc — the single source of UI truth. */
+    capabilities: SessionCapabilities | null;
+    state: SessionCapabilitiesState;
+    error: Error | null;
     /**
-     * Run the command at an explicitly chosen index (a pointer click on a row).
-     * Bypasses the exact-match token heuristic that runHighlighted uses for
-     * keyboard Enter, so an explicit click always runs the clicked command.
+     * 409 from the desktop attach: the un-redacted (or shared) plane needs explicit
+     * acknowledgment before a viewer holder is granted. Drives the consent prompt.
      */
-    runAt: (index: number) => Promise<void>;
-    /** Autocomplete the highlighted command name + a trailing space. */
-    autocompleteHighlighted: () => void;
+    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;
 };
-declare function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult;
-
-type ChatComposerProps = {
-    composer: ComposerState;
-    /** Canonical workstream control, separate from lifecycle status. */
-    effectiveControl?: EffectiveSessionControl | null | undefined;
-    /** Waiting prompts already ahead of a normal Send. */
-    queuedAheadCount?: number | undefined;
-    /** Whether broader Workspace Resume is authorized for this viewer. */
-    canControlWorkspace?: boolean | undefined;
-    /** Optional host routes used to navigate from effective Pause blockers. */
-    controlLinks?: {
-        workspaceHref?: string | undefined;
-        sessionHref?: ((sessionId: string) => string) | undefined;
-    } | undefined;
-    placeholder?: string | undefined;
-    disabled?: boolean | undefined;
-    autoFocus?: boolean | undefined;
-    /** Replaces the default keyboard hint under the field. */
-    hint?: string | undefined;
-    /** App controls (model picker, attach button, ...) in the footer row, replacing the hint. */
-    controlsStart?: ReactNode | undefined;
-    /** Content rendered above the textarea, inside the field chrome (e.g. attachment chips). */
-    header?: ReactNode | undefined;
-    /** Paste hook on the textarea (e.g. paste-image-to-attach). */
-    onPaste?: ((event: ClipboardEvent<HTMLTextAreaElement>) => void) | undefined;
-    /**
-     * Opt-in file attachments. When supplied (e.g. from {@link useFileAttachments}),
-     * the composer renders a built-in attach button (prepended to `controlsStart`),
-     * an attachment-chips strip (above the textarea, before any host `header`),
-     * routes paste through `addFromPaste` (image/* filter lives in the hook), and
-     * gates send while `uploading` so a message never departs without its files.
-     * Absent → no attachment UI renders and the composer behaves exactly as before.
-     */
-    attachments?: UseFileAttachmentsResult | undefined;
-    /**
-     * Opt-in model picker. When supplied (e.g. from {@link useAvailableModels}),
-     * the composer renders a {@link ModelPicker} at the start of `controlsStart`
-     * so the operator can choose which host-exposed model serves the next message.
-     * The host owns the selection (`selectedModel`/`onSelectModel`) and is
-     * responsible for threading it into the composer's `sendExtras` (typically
-     * `useComposer({ sendExtras: () => ({ model }) })`) so `composeSendInput`
-     * carries it. Absent → no picker renders and the composer behaves as before.
-     */
-    models?: ClientModel[] | undefined;
-    /** The currently selected model id (the picker's controlled value). */
-    selectedModel?: string | undefined;
-    /** Called with the chosen model id when the operator picks one. */
-    onSelectModel?: ((modelId: string) => void) | undefined;
-    className?: string | undefined;
-    /**
-     * Slash-command palette. Defaults to the built-in {@link defaultCommands};
-     * apps concat their own. Backward-compatible: when `commandContext` is absent
-     * the palette is inert and behavior is identical to before.
-     */
-    commands?: readonly SlashCommand[] | undefined;
-    /**
-     * Wiring the palette needs to run server commands and gate visibility. The
-     * composer supplies notice/openHelp/clearView/confirm internally.
-     */
-    commandContext?: SlashCommandContext | undefined;
-    /** Reset the local timeline view (the /clear-view command target). */
-    onClearView?: (() => void) | undefined;
-};
-declare const OPEN_WORKSTREAM_CONTROL_EVENT = "opengeni:open-workstream-control";
 /**
- * The chat composer — the only human-to-agent input surface. Plain chat in,
- * everything else is the agent's job. Enter sends, Shift+Enter breaks the
- * line, and the stop control appears while a turn is running (sending while
- * running is legitimate steering, so send stays available too).
+ * 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.
  *
- * Typing a leading "/" opens the slash-command palette — SESSION/OPERATOR
- * controls (clear, compact, pause goal, help), never a structured channel to
- * the agent. The palette is purely additive: with no `commandContext` it is
- * inert and the composer behaves exactly as before.
+ * 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 ChatComposer({ composer, effectiveControl, queuedAheadCount, canControlWorkspace, controlLinks, placeholder, disabled, autoFocus, hint, controlsStart, header, onPaste, attachments, models, selectedModel, onSelectModel, className, commands, commandContext, onClearView, }: ChatComposerProps): react_jsx_runtime.JSX.Element;
+declare function useSessionCapabilities(sessionId: string | null | undefined, options?: UseSessionCapabilitiesOptions): UseSessionCapabilitiesResult;
 
-/** Event types that change the session goal (set/updated/completed/paused/...). */
-declare function isGoalEvent(event: Pick<SessionEvent, "type">): boolean;
-type UseGoalOptions = ClientOverride & SessionEventFeedOptions & {
-    /** Optional safety-net polling (ms). Off by default — goal.* events drive updates. */
-    pollIntervalMs?: number | undefined;
+/**
+ * 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`.
+ */
+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;
+}
+type DesktopWebSocketFactory = (url: string) => DesktopWebSocketLike;
+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;
 };
-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;
+type UseRelayFrameStreamResult = {
+    state: DesktopConnectionState;
     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;
+    /** Tear down + reopen the socket (e.g. after a drop, once a fresh url arrives). */
+    reconnect: () => 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.*` events —
- * pass `options.events` from `useSessionEvents` to reuse its stream.
+ * 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.
  */
-declare function useGoal(sessionId: string | null | undefined, options?: UseGoalOptions): UseGoalResult;
+declare function useRelayFrameStream(options: UseRelayFrameStreamOptions): UseRelayFrameStreamResult;
 
-type UseSessionControlOptions = ClientOverride;
-type UseSessionControlResult = {
-    pause: (reason?: string) => Promise<SessionControlResponse | null>;
-    resume: (reason?: string) => Promise<SessionControlResponse | null>;
-    controlling: boolean;
-    /** Approve a pending `requires_action` approval. */
-    approve: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
-    /** Reject a pending `requires_action` approval. */
-    reject: (approvalId: string, message?: string) => Promise<SessionEvent | null>;
-    /** True while an approval decision is in flight. */
-    responding: boolean;
+type UseDesktopStreamOptions = {
+    /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
+    capability: DesktopStreamCapability | null;
+    /** The mount target. RFB (or the frame canvas) 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;
+    /** Custom socket factory for the `relay-frames` transport (tests). Defaults to
+     *  `new WebSocket(url)`. Mirrors `rfbFactory` for the frame renderer. */
+    webSocketFactory?: DesktopWebSocketFactory | undefined;
+};
+type UseDesktopStreamResult = {
+    state: DesktopConnectionState;
     error: Error | null;
-    clearError: () => void;
+    /** Manual reconnect (e.g. after a securityfailure once a fresh URL arrives). */
+    reconnect: () => void;
 };
 /**
- * Session pause/resume and approval decisions. Pair with
- * `useSessionEvents` (for `session.requiresAction` payloads carrying the
- * `approvalId`) to render an approval bar.
+ * 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.
+ *
+ * Transport dispatch: a Modal box negotiates `transport: "vnc-ws"` and drives the
+ * noVNC RFB below. A SELF-HOSTED machine negotiates `transport: "relay-frames"`
+ * (PNG-per-frame over the relay, view-only) — that path is delegated to
+ * `useRelayFrameStream`, which paints a `<canvas>`. Both hooks are ALWAYS called
+ * (rules of hooks); each is dormant for the other's transport, and we return the
+ * result of whichever owns the surface. The public interface is identical either
+ * way, so `DesktopViewer` is transport-agnostic.
  */
-declare function useSessionControl(sessionId: string | null | undefined, options?: UseSessionControlOptions): UseSessionControlResult;
+declare function useDesktopStream(options: UseDesktopStreamOptions): UseDesktopStreamResult;
 
-type UseScheduledTasksOptions = ClientOverride & {
-    limit?: number | undefined;
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
+/** 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 UseScheduledTasksResult = {
-    tasks: ScheduledTask[];
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
+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;
 };
-/** List the workspace's scheduled tasks (drift checks, sentinels, reapers, ...). */
-declare function useScheduledTasks(options?: UseScheduledTasksOptions): UseScheduledTasksResult;
+/**
+ * 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 UseWorkspaceSessionsOptions = ClientOverride & {
-    limit?: number | undefined;
-    parentSessionId?: string | null | undefined;
-    cursor?: string | undefined;
-    search?: string | undefined;
-    /** Refresh interval (ms) for fleet/manager views. Off by default. */
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
+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 UseWorkspaceSessionsResult = {
+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;
     /**
-     * All visible rows, with pins first. This preserves the pre-pinning hook
-     * contract for consumers that only read `sessions`.
+     * 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.
      */
-    sessions: Session[];
-    /** The complete personal pinned section, also present in `sessions`. */
-    pinned: Session[];
-    nextCursor: string | null;
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
+    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;
 };
-/** List the workspace's sessions — the data behind fleet and manager views. */
-declare function useWorkspaceSessions(options?: UseWorkspaceSessionsOptions): UseWorkspaceSessionsResult;
-
-type UseSessionLineageOptions = ClientOverride & {
-    events?: SessionEvent[] | undefined;
-    /** Refresh interval (ms). Off by default. */
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
-};
-type UseSessionLineageResult = {
-    lineage: SessionLineageResponse | null;
-    loading: boolean;
+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;
-    refresh: () => Promise<void>;
 };
-declare function isLineageRefreshEvent(event: SessionEvent): boolean;
-/** Read the ancestors + descendant tree for one session. Data-only; no UI state. */
-declare function useSessionLineage(sessionId: string | null | undefined, options?: UseSessionLineageOptions): UseSessionLineageResult;
+/**
+ * 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;
 
-type UseVariableSetsOptions = ClientOverride & {
-    pollIntervalMs?: number | undefined;
+/** The git-status overlay a file row may carry (tints modified files in the tree). */
+type FileTreeStatus = "added" | "modified" | "deleted" | "renamed" | "untracked";
+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. */
+declare class CapturedFileUnavailableError extends Error {
+    readonly path: string;
+    readonly reason: CapturedFileUnavailableReason;
+    readonly code = "captured_file_unavailable";
+    constructor(path: string, reason: CapturedFileUnavailableReason);
+}
+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);
+}
+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. */
+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;
+};
+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;
 };
-type UseVariableSetsResult = {
-    variableSets: VariableSet[];
+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;
-    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.
+ * 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 useVariableSets(options?: UseVariableSetsOptions): UseVariableSetsResult;
-/** @deprecated use UseVariableSetsOptions */
-type UseEnvironmentsOptions = UseVariableSetsOptions;
-/** @deprecated use UseVariableSetsResult */
-type UseEnvironmentsResult = UseVariableSetsResult & {
-    environments: VariableSet[];
-};
-/** @deprecated use useVariableSets */
-declare function useEnvironments(options?: UseEnvironmentsOptions): UseEnvironmentsResult;
+declare function useSandboxFiles(sessionId: string | null | undefined, options?: UseSandboxFilesOptions): UseSandboxFilesResult;
 
-type UseRigsOptions = ClientOverride & {
-    pollIntervalMs?: number | undefined;
+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;
 };
-type UseRigsResult = {
-    rigs: Rig[];
+/** 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. */
+type SandboxGitFileDiff = GitFileDiff & {
+    repoRoot?: string | undefined;
+};
+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;
-    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).
+ * 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.
  */
-declare function useRigs(options?: UseRigsOptions): UseRigsResult;
-type UseRigOptions = ClientOverride & {
-    pollIntervalMs?: number | undefined;
+declare function useSandboxGit(sessionId: string | null | undefined, options?: UseSandboxGitOptions): UseSandboxGitResult;
+
+type UseWorkspaceCaptureOptions = ClientOverride & {
+    /** Live event log (usually `useSessionEvents().events`) — a
+     *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
+    events?: SessionEvent[] | undefined;
+    /** Hold off the mount fetch (e.g. the workbench panel is collapsed). Default true. */
     enabled?: boolean | undefined;
 };
-type UseRigResult = {
-    rig: Rig | null;
+type UseWorkspaceCaptureResult = {
+    /** The resolved manifest (tree index + per-repo diffs + file refs), or null when
+     *  no capture exists (falls back to the live/wake path — status quo). */
+    capture: WorkspaceCaptureManifest | null;
+    /** The loaded capture's monotonic revision, or null when unavailable. */
+    revision: number | null;
+    /** When the loaded capture was taken (ISO), for the "as of <time>" source badge. */
+    capturedAt: string | null;
+    /** Whether a capture is available at all (the `{available:false}` discriminator). */
+    available: boolean;
+    /** Why the newest durable revision is unavailable. null means no capture has
+     *  been attempted yet; a value means capture explicitly failed closed and
+     *  consumers must use the live box rather than trust an incomplete snapshot. */
+    degradedReason: WorkspaceCaptureDegradedReason | null;
+    /** The changed-file count from the capture's stats, resolved on the FIRST GET
+     *  (from the response's top-level `stats`, before any manifest-URL hop). null
+     *  until that first resolve; 0 when no capture exists. This is the pre-paint
+     *  "changes exist?" signal the dock uses to pick its default tab with no
+     *  embedder events-at-mount contract. */
+    fileCount: number | null;
+    /** A newer revision has been ANNOUNCED than the one currently loaded (a refresh
+     *  is in flight or pending). M5's source badge can show a subtle "updating…". */
+    isStale: boolean;
     loading: boolean;
     error: Error | null;
+    /** Force a re-fetch of the latest capture. */
     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`).
+ * The cold-paint data source: fetch the latest turn-end workspace capture with a
+ * SINGLE api round-trip on mount (no machine, no Channel-A — this is the <200ms
+ * first paint). The manifest is served inline in the common
+ * case; a rare >2MB manifest comes back as a short-TTL signed URL we follow.
+ *
+ * Subscribes to the live event log: a `workspace.revision.captured` for a revision
+ * newer than the one loaded triggers a background refresh (stale-while-revalidate).
+ * `{available:false}` is a value, never a crash — consumers fall back to the
+ * live/wake path exactly as before the capture feature existed.
  */
-declare function useRig(rigId: string, options?: UseRigOptions): UseRigResult;
-type UseRigVersionsOptions = ClientOverride & {
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
-};
-type UseRigVersionsResult = {
-    versions: RigVersion[];
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
+declare function useWorkspaceCapture(sessionId: string | null | undefined, options?: UseWorkspaceCaptureOptions): UseWorkspaceCaptureResult;
+
+/**
+ * The wake-on-edit state machine. This hook owns the logic and the UI renders
+ * its result. States are explicit and exhaustive:
+ *
+ *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
+ *   buffering         — local edits buffered; the box is not warm and no warm is
+ *                       yet in flight (the host has not attached).
+ *   warming           — edits buffered; the box is actively coming up (the host
+ *                       attached a viewer in response to `wantsWarm`).
+ *   flushing          — the box is warm; the guarded write is in flight.
+ *   flushed           — the buffer was written to the live box.
+ *   conflict          — the live file diverged from the captured base between
+ *                       capture and flush; NO write was issued (C2).
+ *   readonly-offline  — a self-hosted machine that is offline; read-only, no wake.
+ */
+type WorkspaceEditState = "viewing-cold" | "buffering" | "warming" | "flushing" | "flushed" | "conflict" | "readonly-offline";
+type WorkspaceEditConflict = {
+    path: string;
+    /** The capture-served content the edit was based on. */
+    base: string;
+    /** The live content found on the box at flush time (what would be overwritten). */
+    live: string;
 };
-/** A rig's append-only version history, newest-first (polled). */
-declare function useRigVersions(rigId: string, options?: UseRigVersionsOptions): UseRigVersionsResult;
-type UseRigChangesOptions = ClientOverride & {
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
+type UseWorkspaceEditOptions = ClientOverride & {
+    /** The file being edited (workspace-relative). null disables the machine. */
+    path?: string | null | undefined;
+    /** The capture-served content loaded into the editor — the flush base (C2). */
+    baseContent?: string | null | undefined;
+    /** `capabilities.liveness` — "warm" | "draining" | "cold". Drives the flush. */
+    liveness?: string | undefined;
+    /** True while the host is actively warming the box (attach in flight, not warm
+     *  yet) — lifts `buffering` → `warming`. The host sets this after acting on
+     *  `wantsWarm` (e.g. flipping `attachFiles` on `useSessionCapabilities`). */
+    warming?: boolean | undefined;
+    /** A self-hosted machine that is OFFLINE: read-only, no remote wake possible. */
+    offline?: boolean | undefined;
+    /** Called once when the first cold edit needs the box warmed — the host wires
+     *  this to its liveness primitive (flip `attachFiles`/`attachViewer`). */
+    onWarmRequested?: (() => void) | undefined;
 };
-type UseRigChangesResult = {
-    changes: RigChange[];
-    loading: boolean;
+type UseWorkspaceEditResult = {
+    state: WorkspaceEditState;
+    /** The editor should be read-only (self-hosted offline). */
+    readOnly: boolean;
+    /** The current buffered content (null = no local edit yet). */
+    buffer: string | null;
+    /** The host should warm the box (flip its attach primitive). Latches true from
+     *  the first cold edit until the buffer flushes or is discarded. */
+    wantsWarm: boolean;
+    /** Record an edit from the editor (idempotent per identical content). */
+    edit: (content: string) => void;
+    /** The conflict detail when `state === "conflict"`. */
+    conflict: WorkspaceEditConflict | null;
+    /** Flush the buffer regardless of the base guard (the user chose "overwrite"
+     *  from the conflict bar). Writes last-writer-wins. */
+    overwrite: () => Promise<void>;
+    /** Drop the local buffer and return to viewing the snapshot. */
+    discard: () => void;
     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.
+ * Cold-editing without a spinner: the editor opens instantly from the capture,
+ * the first keystroke buffers locally AND signals the host to warm the box, and on
+ * warm the buffer flushes IF the live file still matches the captured base — else a
+ * non-blocking conflict is surfaced and nothing is overwritten.
+ *
+ * The base guard compares the live content at flush time against `baseContent`
+ * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
+ * the design specifies — M1 leaves `baseHash` null, so the loaded content IS the
+ * authoritative base — and avoids async Web Crypto in the render path.
  */
-declare function useRigChanges(rigId: string, options?: UseRigChangesOptions): UseRigChangesResult;
+declare function useWorkspaceEdit(sessionId: string | null | undefined, options?: UseWorkspaceEditOptions): UseWorkspaceEditResult;
 
-type UsePacksOptions = ClientOverride & {
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
+/** The one truthful machine indicator. Honest staleness beats
+ *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
+type MachineChipState = "live" | "waking" | "offline";
+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;
 };
-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;
+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;
 };
-/** Capability packs: catalog + installations + register/enable/unregister. */
-declare function usePacks(options?: UsePacksOptions): UsePacksResult;
+/** Compact relative-time for the "as of" label. Pure, no Intl dependency. */
+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>".
+ */
+declare function deriveMachineChip(input: DeriveMachineChipInput): MachineChip;
+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.
+ */
+declare function useMachineChip(input: UseMachineChipOptions): MachineChip;
 
-type UseWorkspacesOptions = Pick<ClientOverride, "client"> & {
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
-};
-type UseWorkspacesResult = {
-    workspaces: Workspace[];
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
-    create: (request: CreateWorkspaceRequest) => Promise<Workspace | null>;
-    update: (workspaceId: string, request: UpdateWorkspaceRequest) => Promise<Workspace | null>;
-    mutating: boolean;
-    mutationError: Error | null;
-    clearMutationError: () => void;
+type ApprovalSurfaceMessages = {
+    title: string;
+    description: string;
+    approve: string;
+    reject: string;
+    approving: string;
+    rejecting: string;
+    formatToolName: (name: string) => string;
+};
+declare const defaultApprovalSurfaceMessages: ApprovalSurfaceMessages;
+type ApprovalSurfaceProps = {
+    approvals: PendingApproval[];
+    onApprove: (approval: PendingApproval) => void | Promise<void>;
+    onReject: (approval: PendingApproval) => void | Promise<void>;
+    responding?: boolean | undefined;
+    error?: string | Error | null | undefined;
+    messages?: Partial<ApprovalSurfaceMessages> | undefined;
+    renderApproval?: ((approval: PendingApproval) => ReactNode) | undefined;
+    className?: string | undefined;
 };
 /**
- * The caller's workspaces (workspace switchers, onboarding). Not scoped to
- * the provider's workspace, so it only needs the client.
+ * Host-neutral approval presentation backed by the native pending-approval
+ * projection and control callbacks. It owns only presentation and duplicate
+ * click fencing; OpenGeni remains the authority for approval state.
  */
-declare function useWorkspaces(options?: UseWorkspacesOptions): UseWorkspacesResult;
+declare function ApprovalSurface({ approvals, onApprove, onReject, responding, error, messages: overrides, renderApproval, className, }: ApprovalSurfaceProps): react_jsx_runtime.JSX.Element | null;
 
-type UseBillingUsageOptions = Pick<ClientOverride, "client"> & {
-    /** Account to read. Defaults to the caller's default account server-side. */
-    accountId?: string | undefined;
-    /** Filter usage to one workspace. */
-    workspaceId?: string | undefined;
-    /** Refresh interval (ms) for live billing meters. Off by default. */
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
+type HumanInputAnswerDraft = {
+    values: string[];
+    other: string;
+    otherSelected: boolean;
 };
-type UseBillingUsageResult = {
-    /** Prepaid credit balance (micro-USD), null until loaded. */
-    balance: BillingBalance | null;
-    /** Recent usage events (runs, tokens, cost, uploads, ...). */
-    usage: UsageEvent[];
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
+type HumanInputFormMessages = {
+    title: string;
+    description: string;
+    submit: string;
+    skip: string;
+    submitting: string;
+    other: string;
+    deadlineLabel: string;
+    formatDeadline: (value: string) => string;
+    required: string;
+    minLength: (count: number) => string;
+    maxLength: (count: number) => string;
+    otherRequired: string;
+    minSelections: (count: number) => string;
+    maxSelections: (count: number) => string;
+};
+declare const defaultHumanInputFormMessages: HumanInputFormMessages;
+type HumanInputFormProps = {
+    request: Pick<SessionHumanInputRequest, "id" | "questions" | "allowSkip" | "expiresAt">;
+    onSubmit: (response: SubmitHumanInputResponseRequest) => void | Promise<void>;
+    submitting?: boolean | undefined;
+    error?: string | null | undefined;
+    title?: ReactNode;
+    description?: ReactNode;
+    submitLabel?: string | undefined;
+    skipLabel?: string | undefined;
+    messages?: Partial<HumanInputFormMessages> | undefined;
+    autoFocus?: boolean | undefined;
+    className?: string | undefined;
 };
 /**
- * Account billing usage: credit balance + recent usage events — the data
- * behind per-call billing meters. Account-scoped, so it only needs the
- * client; pass `workspaceId` to narrow usage to one workspace.
+ * Styled but host-neutral renderer for one structured request. Hosts can use
+ * the headless `useHumanInputRequests` hook instead, or replace the title and
+ * description while retaining accessible field semantics and validation.
  */
-declare function useBillingUsage(options?: UseBillingUsageOptions): UseBillingUsageResult;
+declare function HumanInputForm({ request, onSubmit, submitting, error, title, description, submitLabel, skipLabel, messages: messageOverrides, autoFocus, className, }: HumanInputFormProps): react_jsx_runtime.JSX.Element;
+declare function answersFromDrafts(questions: HumanInputQuestion[], drafts: Record<string, HumanInputAnswerDraft>, messageOverrides?: Partial<HumanInputFormMessages>): {
+    answers: HumanInputAnswer[];
+    errors: Record<string, string>;
+};
 
-type UseAvailableModelsOptions = Pick<ClientOverride, "client"> & {
-    /** Refresh interval (ms). Off by default — the host model list rarely moves. */
-    pollIntervalMs?: number | undefined;
-    enabled?: boolean | undefined;
+type ToolRendererProps = {
+    item: ToolCallItem;
 };
-type UseAvailableModelsResult = {
-    /** The provider-grouped models the host exposes (empty until loaded). */
-    models: ClientModel[];
-    /** The deployment's default model id, null until loaded. */
-    defaultModel: string | null;
-    loading: boolean;
-    error: Error | null;
-    refresh: () => Promise<void>;
+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;
 /**
- * The host-exposed model list for a <ModelPicker>: fetches the deployment's
- * public client config (`GET /v1/config/client`) and surfaces the richer
- * provider-grouped `models` plus the `defaultModel` the picker should preselect.
- * Deployment-scoped, so it only needs the client (no workspace).
+ * 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 useAvailableModels(options?: UseAvailableModelsOptions): UseAvailableModelsResult;
+declare function createToolRegistry(baseEntries: ToolRegistryEntry[], baseFallback: ToolRenderer, options?: CreateToolRegistryOptions): ToolRegistry;
 
-type SessionCapabilitiesState = "idle" | "negotiating" | "ready" | "cold" | "on-demand" | "error";
-type UseSessionCapabilitiesOptions = ClientOverride & {
+/** 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;
     /**
-     * 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.
+     * Deep-link a memory row to its record in the host's memory pane. Opt-in: the
+     * library draws no "View in memory" affordance without a handler (the memory
+     * row is then non-interactive rich content). See {@link MessageTimelineProps}.
      */
-    events?: SessionEvent[] | undefined;
+    onMemoryClick?: ((memoryId: 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, onMemoryClick, 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;
     /**
-     * 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.
+     * 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.
      */
-    attachDesktop?: boolean | undefined;
+    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;
     /**
-     * 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.
+     * 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.
      */
-    attachTerminal?: boolean | undefined;
+    failed?: boolean | undefined;
     /**
-     * Whether to acquire a viewer holder to warm the box for a FILE WRITE — the
-     * wake-on-edit INTENT (a first keystroke in the editor), NOT passive browsing.
-     * Shares the SAME viewer attach as the desktop/terminal (one warm box, one
-     * holder) and — like the terminal — needs NO un-redacted acknowledgment:
-     * reading/writing files is the ordinary Channel-A control plane, not the pixel
-     * plane. It folds NO live URL (files ride the stateless HTTP plane) — it only
-     * refcounts liveness. Unlike desktop/terminal it warms even a COLD box: an edit
-     * legitimately cold-creates (that IS the wake), so the write lands ~100ms warm
-     * instead of paying the ~5s cold resume. Default false. IMPORTANT: merely
-     * opening/reading the Files tab must NOT set this — browsing capture-served
-     * trees/diffs needs no box, and warming one on a cold glance burns box-hours to
-     * serve reads the capture already answers for free.
+     * 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).
      */
-    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;
+    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, failed, }: {
     /**
-     * Give up waiting for `warm` after this long while polling (ms) and surface a
-     * stalled error with a manual `renegotiate`. Default 30000. This is a UI
-     * patience deadline, independent from the worker's sandbox warming timeout.
-     * 0 disables the deadline.
+     * 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.
      */
-    warmingDeadlineMs?: number | undefined;
-};
-type UseSessionCapabilitiesResult = {
-    /** The negotiated capability doc — the single source of UI truth. */
-    capabilities: SessionCapabilities | null;
-    state: SessionCapabilitiesState;
-    error: Error | null;
+    command: string | null;
+    workdir?: string | null | undefined;
+    /** The FULL output. TermBlock owns the tail/full slicing internally. */
+    output: string;
+    live?: boolean | undefined;
+    /** A non-zero exit / failed call — tints the left accent red (the one hue). */
+    failed?: boolean | undefined;
     /**
-     * 409 from the desktop attach: the un-redacted (or shared) plane needs explicit
-     * acknowledgment before a viewer holder is granted. Drives the consent prompt.
+     * 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.
      */
-    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;
-
+    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;
 /**
- * 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`.
+ * 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.
  */
-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;
-}
-type DesktopWebSocketFactory = (url: string) => DesktopWebSocketLike;
-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;
-};
-type UseRelayFrameStreamResult = {
-    state: DesktopConnectionState;
-    error: Error | null;
-    /** Tear down + reopen the socket (e.g. after a drop, once a fresh url arrives). */
-    reconnect: () => void;
-};
+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;
 /**
- * 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`.
+ * A small inline screenshot thumbnail that opens the app lightbox on click.
  *
- * 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.
+ * 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 useRelayFrameStream(options: UseRelayFrameStreamOptions): UseRelayFrameStreamResult;
-
-type UseDesktopStreamOptions = {
-    /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
-    capability: DesktopStreamCapability | null;
-    /** The mount target. RFB (or the frame canvas) 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;
-    /** Custom socket factory for the `relay-frames` transport (tests). Defaults to
-     *  `new WebSocket(url)`. Mirrors `rfbFactory` for the frame renderer. */
-    webSocketFactory?: DesktopWebSocketFactory | undefined;
-};
-type UseDesktopStreamResult = {
-    state: DesktopConnectionState;
-    error: Error | null;
-    /** Manual reconnect (e.g. after a securityfailure once a fresh URL arrives). */
-    reconnect: () => void;
-};
+declare function Thumbnail({ src, caption, alt, }: {
+    src: string;
+    caption?: string | undefined;
+    alt?: string;
+}): react_jsx_runtime.JSX.Element;
 /**
- * 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.
- *
- * Transport dispatch: a Modal box negotiates `transport: "vnc-ws"` and drives the
- * noVNC RFB below. A SELF-HOSTED machine negotiates `transport: "relay-frames"`
- * (PNG-per-frame over the relay, view-only) — that path is delegated to
- * `useRelayFrameStream`, which paints a `<canvas>`. Both hooks are ALWAYS called
- * (rules of hooks); each is dormant for the other's transport, and we return the
- * result of whichever owns the surface. The public interface is identical either
- * way, so `DesktopViewer` is transport-agnostic.
- */
-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;
-    /** 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;
-};
-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`). When the
-     *  box is NOT warm, the tree paints INSTANTLY from this capture's tree index (the
-     *  <200ms cold first paint) instead of blocking on a Channel-A list. A warm box
-     *  always wins (live path unchanged). On the cold→warm transition the live list
-     *  is merged in place — no remount, no flash (dossier §10.4 / §12-A1/D1). */
-    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;
-};
-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>;
-    /** 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.
- */
-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;
-    /** 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`). Supplies the cold
-     *  diff for this repo. A warm box always wins (live `gitDiff` unchanged). */
-    capture?: WorkspaceCaptureManifest | null | 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>;
-    /** 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 (dossier §10.4). Refreshes on
- * `git.changed`; reconciles live in place on the cold→warm transition.
- */
-declare function useSandboxGit(sessionId: string | null | undefined, options?: UseSandboxGitOptions): UseSandboxGitResult;
-
-type UseWorkspaceCaptureOptions = ClientOverride & {
-    /** Live event log (usually `useSessionEvents().events`) — a
-     *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
-    events?: SessionEvent[] | undefined;
-    /** Hold off the mount fetch (e.g. the workbench panel is collapsed). Default true. */
-    enabled?: boolean | undefined;
-};
-type UseWorkspaceCaptureResult = {
-    /** The resolved manifest (tree index + per-repo diffs + file refs), or null when
-     *  no capture exists (falls back to the live/wake path — status quo). */
-    capture: WorkspaceCaptureManifest | null;
-    /** The loaded capture's monotonic revision, or null when unavailable. */
-    revision: number | null;
-    /** When the loaded capture was taken (ISO), for the "as of <time>" source badge. */
-    capturedAt: string | null;
-    /** Whether a capture is available at all (the `{available:false}` discriminator). */
-    available: boolean;
-    /** Why the newest durable revision is unavailable. null means no capture has
-     *  been attempted yet; a value means capture explicitly failed closed and
-     *  consumers must use the live box rather than trust an incomplete snapshot. */
-    degradedReason: WorkspaceCaptureDegradedReason | null;
-    /** The changed-file count from the capture's stats, resolved on the FIRST GET
-     *  (from the response's top-level `stats`, before any manifest-URL hop). null
-     *  until that first resolve; 0 when no capture exists. This is the pre-paint
-     *  "changes exist?" signal the dock uses to pick its default tab with no
-     *  embedder events-at-mount contract. */
-    fileCount: number | null;
-    /** A newer revision has been ANNOUNCED than the one currently loaded (a refresh
-     *  is in flight or pending). M5's source badge can show a subtle "updating…". */
-    isStale: boolean;
-    loading: boolean;
-    error: Error | null;
-    /** Force a re-fetch of the latest capture. */
-    refresh: () => Promise<void>;
+ * 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 cold-paint data source: fetch the latest turn-end workspace capture with a
- * SINGLE api round-trip on mount (no machine, no Channel-A — this is the <200ms
- * first paint, dossier §10.4/§12-A1). The manifest is served inline in the common
- * case; a rare >2MB manifest comes back as a short-TTL signed URL we follow.
- *
- * Subscribes to the live event log: a `workspace.revision.captured` for a revision
- * newer than the one loaded triggers a background refresh (stale-while-revalidate).
- * `{available:false}` is a value, never a crash — consumers fall back to the
- * live/wake path exactly as before the capture feature existed.
+ * 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 useWorkspaceCapture(sessionId: string | null | undefined, options?: UseWorkspaceCaptureOptions): UseWorkspaceCaptureResult;
-
+declare function useLightboxOptional(): LightboxController | null;
 /**
- * The wake-on-edit state machine (dossier §3 #5 / §10.4 / §12-C). M3 OWNS this
- * logic; M5 renders it. States are explicit and exhaustive:
+ * The app-level screenshot lightbox. Render once near the timeline; renderers
+ * call `useLightbox().open(src)`.
  *
- *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
- *   buffering         — local edits buffered; the box is not warm and no warm is
- *                       yet in flight (the host has not attached).
- *   warming           — edits buffered; the box is actively coming up (the host
- *                       attached a viewer in response to `wantsWarm`).
- *   flushing          — the box is warm; the guarded write is in flight.
- *   flushed           — the buffer was written to the live box.
- *   conflict          — the live file diverged from the captured base between
- *                       capture and flush; NO write was issued (C2).
- *   readonly-offline  — a self-hosted machine that is offline; read-only, no wake.
+ * 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.
  */
-type WorkspaceEditState = "viewing-cold" | "buffering" | "warming" | "flushing" | "flushed" | "conflict" | "readonly-offline";
-type WorkspaceEditConflict = {
-    path: string;
-    /** The capture-served content the edit was based on. */
-    base: string;
-    /** The live content found on the box at flush time (what would be overwritten). */
-    live: string;
-};
-type UseWorkspaceEditOptions = ClientOverride & {
-    /** The file being edited (workspace-relative). null disables the machine. */
-    path?: string | null | undefined;
-    /** The capture-served content loaded into the editor — the flush base (C2). */
-    baseContent?: string | null | undefined;
-    /** `capabilities.liveness` — "warm" | "draining" | "cold". Drives the flush. */
-    liveness?: string | undefined;
-    /** True while the host is actively warming the box (attach in flight, not warm
-     *  yet) — lifts `buffering` → `warming`. The host sets this after acting on
-     *  `wantsWarm` (e.g. flipping `attachFiles` on `useSessionCapabilities`). */
-    warming?: boolean | undefined;
-    /** A self-hosted machine that is OFFLINE: read-only, no remote wake possible. */
-    offline?: boolean | undefined;
-    /** Called once when the first cold edit needs the box warmed — the host wires
-     *  this to its liveness primitive (flip `attachFiles`/`attachViewer`). */
-    onWarmRequested?: (() => void) | undefined;
-};
-type UseWorkspaceEditResult = {
-    state: WorkspaceEditState;
-    /** The editor should be read-only (self-hosted offline). */
-    readOnly: boolean;
-    /** The current buffered content (null = no local edit yet). */
-    buffer: string | null;
-    /** The host should warm the box (flip its attach primitive). Latches true from
-     *  the first cold edit until the buffer flushes or is discarded. */
-    wantsWarm: boolean;
-    /** Record an edit from the editor (idempotent per identical content). */
-    edit: (content: string) => void;
-    /** The conflict detail when `state === "conflict"`. */
-    conflict: WorkspaceEditConflict | null;
-    /** Flush the buffer regardless of the base guard (the user chose "overwrite"
-     *  from the conflict bar). Writes last-writer-wins. */
-    overwrite: () => Promise<void>;
-    /** Drop the local buffer and return to viewing the snapshot. */
-    discard: () => void;
-    error: Error | null;
-};
+declare function LightboxProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
 /**
- * Cold-editing without a spinner: the editor opens instantly from the capture,
- * the first keystroke buffers locally AND signals the host to warm the box, and on
- * warm the buffer flushes IF the live file still matches the captured base — else a
- * non-blocking conflict is surfaced and nothing is overwritten (dossier §12-C2).
- *
- * The base guard compares the live content at flush time against `baseContent`
- * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
- * the dossier describes — M1 leaves `baseHash` null, so the loaded content IS the
- * authoritative base — and avoids async Web Crypto in the render path.
+ * Seed the initial open state of every timeline collapsible below this node.
+ * Intended for screenshot/test instrumentation only; absent by default.
  */
-declare function useWorkspaceEdit(sessionId: string | null | undefined, options?: UseWorkspaceEditOptions): UseWorkspaceEditResult;
+declare function DisclosureDefaultsProvider({ defaultOpen, children, }: {
+    defaultOpen: boolean;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
 
-/** The one truthful machine indicator (dossier §3 #10). Honest staleness beats
- *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
-type MachineChipState = "live" | "waking" | "offline";
-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;
+type TurnSummaryProps = {
+    /** The activity items in the turn (used only to compute the facet counts). */
+    items: ActivityItem[];
+    /**
+     * The settled verdict — or absent for a completed CLUSTER of a still-running
+     * turn, which folds neutrally: no verdict glyph (the turn has none yet), a
+     * quiet pulse dot in its place so alignment and the running feel both hold.
+     */
+    outcome?: TurnOutcome | undefined;
+    /** A short failure reason shown inline on a failed chip (never hidden). */
+    failureText?: string | undefined;
+    /** Elapsed turn duration; shown as a trailing facet when at least 1s. */
+    durationMs?: number | undefined;
+    /** Start expanded. */
+    defaultOpen?: boolean | undefined;
+    /**
+     * A nested fold — a cluster or sub-turn INSIDE an already-expanded turn. It
+     * drops the bordered/filled chip and renders as a plain disclosure node on the
+     * parent's rail (chevron + glyph + facets), so expanding a turn reveals a thread
+     * of nodes, never a stack of boxes-in-boxes. The top-level fold stays a chip.
+     */
+    bare?: boolean | undefined;
+    /** The rendered activity rail revealed on expand. */
+    children: React.ReactNode;
 };
-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;
+declare function TurnSummary({ items, outcome, failureText, durationMs, defaultOpen, bare, 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;
 };
-/** Compact relative-time for the "as of" label. Pure, no Intl dependency. */
-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>".
+ * 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 deriveMachineChip(input: DeriveMachineChipInput): MachineChip;
-type UseMachineChipOptions = DeriveMachineChipInput;
+declare function v4aToGitFileDiff(op: ApplyPatchOperation): GitFileDiff;
 /**
- * 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.
+ * 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 useMachineChip(input: UseMachineChipOptions): MachineChip;
-
-type PendingApproval = {
-    /** The id to send back via `user.approvalDecision` (`approvalId`). */
-    id: string;
-    /** Tool/function name awaiting the decision. */
+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;
-    arguments?: unknown;
-    /** The raw approval entry from the `session.requiresAction` payload. */
-    raw?: unknown;
-};
-/** The approvals carried by one `session.requiresAction` payload. */
-declare function approvalsFromRequiresAction(payload: unknown): PendingApproval[];
-/** The approvals still awaiting a decision after replaying `events` in order. */
-declare function projectPendingApprovals(events: SessionEvent[]): PendingApproval[];
+    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;
+};
 
 /**
  * Parse a composer value into a command name + the rest. A command is
@@ -2023,6 +1483,10 @@ type CommandPaletteProps = {
     argHintText: string;
     /** id used for aria-activedescendant wiring from the textarea. */
     listboxId: string;
+    /** Accessible list label. Defaults to "Slash commands". */
+    label?: string | undefined;
+    /** Badge shown for destructive commands. Defaults to "danger". */
+    dangerLabel?: string | undefined;
 };
 /**
  * The slash-command palette: a popover anchored above the textarea, rendered
@@ -2030,7 +1494,7 @@ type CommandPaletteProps = {
  * the opengeni#46 design tokens. Full keyboard nav lives in useSlashCommands;
  * this component is presentational + aria.
  */
-declare function CommandPalette({ open, items, highlight, onHighlight, onRun, argHintText, listboxId, }: CommandPaletteProps): react_jsx_runtime.JSX.Element;
+declare function CommandPalette({ open, items, highlight, onHighlight, onRun, argHintText, listboxId, label, dangerLabel, }: CommandPaletteProps): react_jsx_runtime.JSX.Element;
 
 type ModelPickerProps = {
     /** The host-exposed models to choose from (typically {@link useAvailableModels}). */
@@ -2041,6 +1505,8 @@ type ModelPickerProps = {
     onChange: (modelId: string) => void;
     disabled?: boolean | undefined;
     className?: string | undefined;
+    /** Visible-to-assistive-technology label. Defaults to "Model". */
+    label?: string | undefined;
 };
 /**
  * The model picker — a compact dropdown for the composer footer, grouping the
@@ -2053,7 +1519,7 @@ type ModelPickerProps = {
  * the send path. Renders nothing when no models are exposed, so a single-model
  * deployment shows no chrome.
  */
-declare function ModelPicker({ models, value, onChange, disabled, className }: ModelPickerProps): react_jsx_runtime.JSX.Element | null;
+declare function ModelPicker({ models, value, onChange, disabled, className, label, }: ModelPickerProps): react_jsx_runtime.JSX.Element | null;
 
 type MessageTimelineProps = {
     /** Raw session events (projected internally) … */
@@ -2337,7 +1803,8 @@ type FileBrowserProps = {
     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.
+     * The default is an accessible, non-blocking confirmation dialog. Supply this
+     * callback to delegate confirmation to a host-owned dialog.
      */
     confirmDelete?: ((node: FileTreeNode) => boolean | Promise<boolean>) | undefined;
     className?: string | undefined;
@@ -2467,6 +1934,10 @@ type CodeEditorProps = {
     initialContents: string;
     /** Persist the current buffer. Resolves when the write lands; rejects to surface an error. */
     onSave: (contents: string) => Promise<unknown>;
+    /** Explicitly overwrite after a visible expected-content conflict. */
+    onOverwrite?: ((contents: string) => Promise<unknown>) | undefined;
+    /** Re-read the selected file after a visible save conflict. */
+    onReload?: (() => void) | undefined;
     /** Fired once when the buffer FIRST diverges from its baseline (the first real
      *  keystroke) — the wake-on-edit intent. The host warms the box on this so the
      *  eventual save lands fast; merely opening the file for reading never fires it. */
@@ -2492,7 +1963,7 @@ type CodeEditorProps = {
  * `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, onEditIntent, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
+declare function CodeEditor({ path, initialContents, onSave, onOverwrite, onReload, onEditIntent, readOnly, themeType, loading, fallback, className, }: CodeEditorProps): react_jsx_runtime.JSX.Element;
 
 type SandboxFilesProps = {
     /** From `useSandboxFiles(...)`. */
@@ -2521,6 +1992,15 @@ type SandboxFilesProps = {
     requestedPathRequestId?: string | number | undefined;
     /** False while the parent is waking a cold sandbox for `requestedPath`. */
     requestedPathReady?: boolean | undefined;
+    /** The machine is cold and no durable capture exists yet. Render an explicit
+     *  wake gate instead of an empty-tree lie or an implicit Channel-A read. */
+    workspaceResting?: boolean | undefined;
+    /** A deliberate wake has started but the live file surface is not ready yet. */
+    workspaceWaking?: boolean | undefined;
+    /** Whether live reads are currently authoritative. */
+    liveWorkspaceReady?: boolean | undefined;
+    /** Deliberately wake the machine to read content absent from the capture. */
+    onWakeWorkspace?: (() => void) | undefined;
     themeType?: "dark" | "light" | undefined;
     className?: string | undefined;
 };
@@ -2531,7 +2011,7 @@ type SandboxFilesProps = {
  * surface deliberately does NOT replicate the changed-files list, and does not
  * diff here — one job per tab). The agent commits; the human reviews.
  */
-declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, requestedPath, requestedPathRequestId, requestedPathReady, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
+declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, requestedPath, requestedPathRequestId, requestedPathReady, workspaceResting, workspaceWaking, liveWorkspaceReady, onWakeWorkspace, themeType, className, }: SandboxFilesProps): react_jsx_runtime.JSX.Element;
 
 type DesktopViewerProps = {
     /** The desktop cell of the negotiated capabilities (`capabilities.DesktopStream`). */
@@ -2659,6 +2139,15 @@ type WorkspaceNotification = {
 /** The workbench's canonical tab ids (a host injects extras around these). */
 declare const WORKBENCH_TAB_CHANGES = "changes";
 declare const WORKBENCH_TAB_FILES = "files";
+declare const WORKBENCH_TAB_TERMINAL = "terminal";
+declare const WORKBENCH_TAB_DESKTOP = "desktop";
+/**
+ * The built-in workbench surfaces in their canonical display order. Hosts can
+ * pass a subset through `surfaces`; omission preserves the complete standalone
+ * workbench.
+ */
+declare const WORKBENCH_SURFACES: readonly ["changes", "files", "terminal", "desktop"];
+type SandboxWorkspaceSurface = (typeof WORKBENCH_SURFACES)[number];
 /**
  * Decide a workspace tab from an already-local event log: the newest
  * `workspace.revision.captured` announce carries the change surface stats, so
@@ -2671,7 +2160,9 @@ declare const WORKBENCH_TAB_FILES = "files";
  */
 declare function initialWorkspaceTab(events: SessionEvent[] | undefined, override?: string | null): string;
 type WorkspaceMachine = {
-    /** The derived live/waking/offline chip model (dossier §3 #10). */
+    /** Whether at least one built-in workbench surface is enabled. */
+    enabled: boolean;
+    /** The derived live/waking/offline chip model. */
     chip: MachineChip;
     /** The machine these surfaces are bound to (the Modal group box or a
      *  self-hosted machine), or null while the fleet is still resolving. */
@@ -2684,6 +2175,12 @@ type UseSandboxWorkspaceTabsOptions = ClientOverride & {
     sessionId: string;
     /** Live event log (usually `useSessionEvents().events`). */
     events: SessionEvent[];
+    /**
+     * Built-in surfaces this host wants to expose. Omit for all four. A disabled
+     * surface is behaviorally dormant: its data hooks, warm intents, stream
+     * attachment, and navigation callbacks are not activated.
+     */
+    surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
     /** Override the source-driven default tab (e.g. a host landing tab id). When
      *  omitted the workbench picks Changes-vs-Files from capture or live Git. */
     initialTab?: string | null | undefined;
@@ -2704,7 +2201,8 @@ type UseSandboxWorkspaceTabsResult = {
     tabs: WorkspaceTab[];
     /** The source-driven default tab: Changes when the first authoritative capture
      *  or live Git result has changes, else Files (a host `initialTab` overrides).
-     *  null while that source resolves; the choice latches once. */
+     *  null while that source resolves, or permanently when neither Changes nor
+     *  Files is enabled; the choice latches once. */
     defaultTab: string | null;
     /** The machine-state model for the dock-header chip. */
     machine: WorkspaceMachine;
@@ -2721,6 +2219,11 @@ type SandboxWorkspaceProps = ClientOverride & {
     events: SessionEvent[];
     /** The chat / primary pane shown beside the dock. */
     primary: ReactNode;
+    /**
+     * Built-in surfaces this host wants to expose. Omit for Changes, Files,
+     * Terminal, and Desktop. Disabled surfaces remain behaviorally dormant.
+     */
+    surfaces?: readonly SandboxWorkspaceSurface[] | undefined;
     /** Host tabs injected BEFORE the workbench tabs (e.g. a "Run" landing tab). */
     leadingTabs?: WorkspaceTab[] | undefined;
     /** Host tabs injected AFTER the workbench tabs (e.g. a "Debug" tab). */
@@ -2882,4 +2385,4 @@ declare function isCreditExhaustion(input: {
  */
 declare function humanizeFailureReason(reason: string | null): string | null;
 
-export { ActivityDisclosure, type ActivityDisclosureProps, type ActivityItem, ActivityRail, type ActivityRailProps, type AgentMessageItem, type ApplyPatchOperation, type AuthNeededItem, BodyNote, CREDIT_EXHAUSTION_MESSAGE, ChatComposer, type ChatComposerProps, ClientOverride, CodeEditor, type CodeEditorProps, type CodexAccountsClientLike, type CommandContext, CommandPalette, type CommandPaletteProps, type CommandResult, type ComposerSendExtras, type ComposerState, type ConfirmState, type CreateToolRegistryOptions, type DeriveMachineChipInput, DesktopViewer, type DesktopViewerProps, type DesktopWebSocketFactory, type DesktopWebSocketLike, type DiffTheme, DiffView, type DiffViewProps, type DisclosureChip, DisclosureDefaultsProvider, FILE_ONLY_MESSAGE_TEXT, type FileAttachment, FileBrowser, type FileBrowserProps, type FileTreeNode, type FileTreeStatus, FleetTile, type FleetTileProps, type GoalItem, LightboxProvider, type MachineChip, type MachineChipState, Markdown, type MarkdownProps, MediaEmpty, MediaSkeleton, MessageTimeline, type MessageTimelineProps, ModelPicker, type ModelPickerProps, type Notice, type NoticeItem, OPEN_WORKSTREAM_CONTROL_EVENT, type ParsedCommandLine, PayloadBlock, type PendingApproval, PierreDiff, type PierreDiffProps, PierreFile, type PierreFileProps, type QueueMutationKind, QueueSurface, type QueueSurfaceProps, type ReasoningItem, SESSION_STATUS_META, SandboxFiles, type SandboxFilesProps, type SandboxItem, SandboxTerminal, type SandboxTerminalProps, SandboxWorkspace, type SandboxWorkspaceProps, ScreenshotFigure, type SessionCapabilitiesState, 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 TurnEndItem, type TurnOutcome, TurnSummary, type TurnSummaryProps, type UseAvailableModelsOptions, type UseAvailableModelsResult, type UseBillingUsageOptions, type UseBillingUsageResult, type UseCodexAccountsOptions, type UseCodexAccountsResult, type UseComposerOptions, type UseDesktopStreamOptions, type UseDesktopStreamResult, type UseEnvironmentsOptions, type UseEnvironmentsResult, type UseFileAttachmentsOptions, type UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UseMachineChipOptions, type UsePacksOptions, type UsePacksResult, type UseRelayFrameStreamOptions, type UseRelayFrameStreamResult, type UseRigChangesOptions, type UseRigChangesResult, type UseRigOptions, type UseRigResult, type UseRigVersionsOptions, type UseRigVersionsResult, type UseRigsOptions, type UseRigsResult, type UseSandboxFilesOptions, type UseSandboxFilesResult, type UseSandboxGitOptions, type UseSandboxGitResult, type UseSandboxTerminalOptions, type UseSandboxTerminalResult, type UseSandboxWorkspaceTabsOptions, type UseSandboxWorkspaceTabsResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionCapabilitiesOptions, type UseSessionCapabilitiesResult, type UseSessionControlOptions, type UseSessionControlResult, type UseSessionEventsOptions, type UseSessionEventsResult, type UseSessionLineageOptions, type UseSessionLineageResult, type UseSessionOptions, type UseSessionResult, type UseSlashCommandsOptions, type UseSlashCommandsResult, type UseTerminalStreamOptions, type UseTerminalStreamResult, type UseTurnQueueOptions, type UseTurnQueueResult, type UseVariableSetsOptions, type UseVariableSetsResult, type UseWorkspaceCaptureOptions, type UseWorkspaceCaptureResult, type UseWorkspaceEditOptions, type UseWorkspaceEditResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, type UserMessageItem, WORKBENCH_TAB_CHANGES, WORKBENCH_TAB_FILES, type WorkerItem, WorkspaceDock, type WorkspaceDockProps, type WorkspaceEditConflict, type WorkspaceEditState, type WorkspaceMachine, type WorkspaceNotification, type WorkspaceTab, type XtermTheme, applyPatchOps, approvalsFromRequiresAction, argHint, buildTimeline, cn, composeSendInput, controlCaret, createDefaultToolRegistry, createToolRegistry, creditExhaustedFromEvents, defaultCommands, defaultToolRegistry, deriveMachineChip, execTruncated, extractSessionRef, filterCommands, firstMissingRequiredArg, formatAsOf, formatBytes, formatRelativeTime, gitFileDiffToPatch, groupTimeline, hasPermission, humanizeFailureReason, initialWorkspaceTab, isApplyPatch, isCodexAccountEvent, isCreditExhaustion, isExecSessionLostBanner, isGoalEvent, isLineageRefreshEvent, isTitleEvent, isTurnQueueEvent, languageForPath, looksBinary, matchCommand, parseCommandLine, parseExecBannerSessionId, parseToolArgs, projectPendingApprovals, rawTypeOf, redactSecrets, sandboxCommandExitCode, sessionDisplayTitle, sessionStatusFromEvents, shouldSteerOnKey, shouldSubmitOnKey, stringifyPayload, stripExecBanner, tailPeek, toolDisplayName, truncate, tryParseJson, unwrapMcpOutput, useAvailableModels, useBillingUsage, useCodexAccounts, useComposer, useDesktopStream, useEnvironments, useFileAttachments, useGoal, useLightbox, useLightboxOptional, useMachineChip, usePacks, useRelayFrameStream, useRig, useRigChanges, useRigVersions, useRigs, useSandboxFiles, useSandboxGit, useSandboxTerminal, useSandboxWorkspaceTabs, useScheduledTasks, useSession, useSessionCapabilities, useSessionControl, useSessionEvents, useSessionLineage, useSlashCommands, useTerminalStream, useTurnQueue, useVariableSets, useWorkspaceCapture, useWorkspaceEdit, useWorkspaceSessions, useWorkspaces, v4aToGitFileDiff, xtermThemeFromTokens };
+export { ActivityDisclosure, type ActivityDisclosureProps, ActivityItem, ActivityRail, type ActivityRailProps, AgentMessageItem, type ApplyPatchOperation, ApprovalSurface, type ApprovalSurfaceMessages, type ApprovalSurfaceProps, AuthNeededItem, BodyNote, CREDIT_EXHAUSTION_MESSAGE, CapturedFileUnavailableError, type CapturedFileUnavailableReason, ChatComposer, ChatComposerMessages, type ChatComposerProps, ClientOverride, CodeEditor, type CodeEditorProps, type CodexAccountsClientLike, CommandContext, CommandPalette, type CommandPaletteProps, ComposerState, ComposerTranscriptionControlProps, type CreateToolRegistryOptions, type DeriveMachineChipInput, DesktopViewer, type DesktopViewerProps, type DesktopWebSocketFactory, type DesktopWebSocketLike, type DiffTheme, DiffView, type DiffViewProps, type DisclosureChip, DisclosureDefaultsProvider, FileBrowser, type FileBrowserProps, type FileTreeNode, type FileTreeStatus, FileWriteConflictError, FleetTile, type FleetTileProps, type HumanInputAnswerDraft, HumanInputForm, type HumanInputFormMessages, type HumanInputFormProps, LightboxProvider, type MachineChip, type MachineChipState, Markdown, type MarkdownProps, MediaEmpty, MediaSkeleton, MessageTimeline, type MessageTimelineProps, ModelPicker, type ModelPickerProps, OpenGeniProvider, type OpenGeniProviderProps, type ParsedCommandLine, PayloadBlock, PendingApproval, PierreDiff, type PierreDiffProps, PierreFile, type PierreFileProps, QueueSurface, type QueueSurfaceProps, SESSION_STATUS_META, SandboxFiles, type SandboxFilesProps, type SandboxGitFileDiff, SandboxTerminal, type SandboxTerminalProps, SandboxWorkspace, type SandboxWorkspaceProps, type SandboxWorkspaceSurface, type SandboxWriteFileOptions, ScreenshotFigure, type SessionCapabilitiesState, SessionClientLike, SessionStatus, type SessionStatusMeta, type SessionStatusProps, SlashArg, SlashCommand, SlashCommandContext, StatusDot, type StatusDotProps, TermBlock, type TerminalChunk, type TerminalStreamStatus, Thumbnail, TimelineItem, TimelineRow, ToolCallItem, type ToolRegistry, type ToolRegistryEntry, type ToolRenderer, type ToolRendererProps, TurnOutcome, TurnSummary, type TurnSummaryProps, type UseAvailableModelsOptions, type UseAvailableModelsResult, type UseBillingUsageOptions, type UseBillingUsageResult, type UseCodexAccountsOptions, type UseCodexAccountsResult, type UseDesktopStreamOptions, type UseDesktopStreamResult, type UseEnvironmentsOptions, type UseEnvironmentsResult, UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UseMachineChipOptions, type UsePacksOptions, type UsePacksResult, type UseRelayFrameStreamOptions, type UseRelayFrameStreamResult, type UseRigChangesOptions, type UseRigChangesResult, type UseRigOptions, type UseRigResult, type UseRigVersionsOptions, type UseRigVersionsResult, type UseRigsOptions, type UseRigsResult, type UseSandboxFilesOptions, type UseSandboxFilesResult, type UseSandboxGitOptions, type UseSandboxGitResult, type UseSandboxTerminalOptions, type UseSandboxTerminalResult, type UseSandboxWorkspaceTabsOptions, type UseSandboxWorkspaceTabsResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionCapabilitiesOptions, type UseSessionCapabilitiesResult, type UseSessionLineageOptions, type UseSessionLineageResult, type UseSessionOptions, type UseSessionResult, type UseTerminalStreamOptions, type UseTerminalStreamResult, UseTurnQueueResult, type UseVariableSetsOptions, type UseVariableSetsResult, type UseWorkspaceCaptureOptions, type UseWorkspaceCaptureResult, type UseWorkspaceEditOptions, type UseWorkspaceEditResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, UserMessageItem, WORKBENCH_SURFACES, WORKBENCH_TAB_CHANGES, WORKBENCH_TAB_DESKTOP, WORKBENCH_TAB_FILES, WORKBENCH_TAB_TERMINAL, WorkspaceDock, type WorkspaceDockProps, type WorkspaceEditConflict, type WorkspaceEditState, type WorkspaceMachine, type WorkspaceNotification, type WorkspaceTab, type XtermTheme, answersFromDrafts, applyPatchOps, argHint, cn, controlCaret, createDefaultToolRegistry, createToolRegistry, defaultApprovalSurfaceMessages, defaultCommands, defaultHumanInputFormMessages, defaultToolRegistry, deriveMachineChip, execTruncated, filterCommands, firstMissingRequiredArg, formatAsOf, formatBytes, formatRelativeTime, gitFileDiffToPatch, hasPermission, humanizeFailureReason, initialWorkspaceTab, isApplyPatch, isCodexAccountEvent, isCreditExhaustion, isExecSessionLostBanner, isGoalEvent, isLineageRefreshEvent, isTitleEvent, languageForPath, looksBinary, matchCommand, parseCommandLine, parseExecBannerSessionId, parseToolArgs, rawTypeOf, redactSecrets, sandboxCommandExitCode, sessionDisplayTitle, stringifyPayload, stripExecBanner, tailPeek, truncate, tryParseJson, unwrapMcpOutput, useAvailableModels, useBillingUsage, useCodexAccounts, useDesktopStream, useEnvironments, useGoal, useLightbox, useLightboxOptional, useMachineChip, usePacks, useRelayFrameStream, useRig, useRigChanges, useRigVersions, useRigs, useSandboxFiles, useSandboxGit, useSandboxTerminal, useSandboxWorkspaceTabs, useScheduledTasks, useSession, useSessionCapabilities, useSessionLineage, useTerminalStream, useVariableSets, useWorkspaceCapture, useWorkspaceEdit, useWorkspaceSessions, useWorkspaces, v4aToGitFileDiff, xtermThemeFromTokens };