@opengeni/react 0.29.0 → 0.33.1

package/dist/components/message-timeline.d.ts

@@ -0,0 +1,98 @@
+import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
+import { type ReactNode } from "react";
+import { type AgentMessageItem, type AuthNeededItem, type TimelineGroup, type TimelineItem, type ToolRegistry, type TurnSummaryOptions, type UserMessageItem } from "../timeline";
+export type MessageTimelineProps = {
+    /** Raw session events (projected internally) … */
+    events?: SessionEvent[] | undefined;
+    /** … or pre-projected items (e.g. from `useSessionEvents().timeline`). */
+    items?: TimelineItem[] | undefined;
+    /** Current session status (reserved; tip "Working…" chrome removed for now). */
+    status?: SessionStatus | null | undefined;
+    /** Plug a markdown renderer for message bodies (e.g. streamdown). */
+    renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
+    /** Drill into a spawned worker session. */
+    onOpenSession?: ((sessionId: string) => void) | undefined;
+    /**
+     * Deep-link a memory row (a `memory.saved` / `memory.corrected` step) to its
+     * record in the host's memory pane. Opt-in, exactly like `onReconnect`: the
+     * library draws no "View in memory" affordance without a handler — the memory
+     * row is then non-interactive rich content. This is the switch that makes the
+     * deep-link a first-party OpenGeni capability without other SDK consumers
+     * opting into it. The app supplies it (it owns routing to the memory pane).
+     */
+    onMemoryClick?: ((memoryId: string) => void) | undefined;
+    /**
+     * Start the reconnect flow when a tool needs its connection reauthorized. The
+     * app supplies this (it owns the SDK client + workspace): it typically kicks
+     * off `startConnectionOAuth` and redirects, or routes to credential entry.
+     * Rejecting surfaces a calm inline error on the card; the library never draws
+     * a Reconnect button without a handler to run it.
+     */
+    onReconnect?: ((item: AuthNeededItem) => void | Promise<void>) | undefined;
+    /**
+     * Resolve a provider domain (from a reconnect card) to a logo URL the host
+     * serves itself — the app maps it through its catalog + `catalogAssetUrl`.
+     * Return null/undefined to fall back to a calm monogram. The library never
+     * fetches an off-origin favicon (CSP + privacy); an unresolved logo is a
+     * monogram, not an external image.
+     */
+    resolveProviderLogo?: ((providerDomain: string) => string | null | undefined) | undefined;
+    /**
+     * The tool-renderer registry that resolves how each tool call is drawn.
+     * Defaults to {@link defaultToolRegistry}; pass a registry from
+     * `createDefaultToolRegistry({ entries })` to add custom tool renderers.
+     */
+    toolRegistry?: ToolRegistry | undefined;
+    /** Customize collapsed turn facets for this timeline instance. */
+    turnSummary?: TurnSummaryOptions | undefined;
+    /** Follow new events when pinned to the bottom. Defaults to true. */
+    autoFollow?: boolean | undefined;
+    /** Older durable history exists above the current window (see useSessionEvents). */
+    hasOlder?: boolean | undefined;
+    /** An older window is being fetched; shows the quiet top shimmer. */
+    loadingOlder?: boolean | undefined;
+    /** Called when the reader nears the top and older history should backfill. */
+    onLoadOlder?: (() => void) | undefined;
+    /** Jump to the durable session start (bounded oldest window, no middle). */
+    onJumpToStart?: (() => void | Promise<void>) | undefined;
+    /** True while the oldest window is loading. */
+    loadingOldest?: boolean | undefined;
+    /** Newer durable history exists below the current (history) window. */
+    hasNewer?: boolean | undefined;
+    /** A newer history page is being fetched. */
+    loadingNewer?: boolean | undefined;
+    /** Page forward through history without loading the whole gap to the tip. */
+    onLoadNewer?: (() => void) | undefined;
+    /**
+     * Reload the live tip window. When omitted, Jump to latest only re-pins and
+     * scrolls the in-memory window.
+     */
+    onJumpToLatest?: (() => void | Promise<void>) | undefined;
+    emptyState?: ReactNode | undefined;
+    className?: string | undefined;
+};
+/**
+ * The session timeline: chat messages with streaming deltas, collapsed
+ * activity clusters (reasoning, tool calls, sandbox work), spawned-worker
+ * cards, goal markers, and status transitions. Owns stick-to-bottom scrolling
+ * with a "jump to latest" affordance when the reader scrolls back.
+ */
+export declare function MessageTimeline({ events, items, status: _status, renderMessageText, onOpenSession, onMemoryClick, onReconnect, resolveProviderLogo, toolRegistry, turnSummary, autoFollow, hasOlder, loadingOlder, onLoadOlder, onJumpToStart, loadingOldest, hasNewer, loadingNewer, onLoadNewer, onJumpToLatest, emptyState, className, }: MessageTimelineProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Settled turns lift the final agent answer out as a sibling group. Include it
+ * in "Copy turn" when present so the chip copies the full assistant reply.
+ * Fenced by turnId so the next turn's answer is never stolen.
+ */
+export declare function trailingAgentTextAfterTurn(group: TimelineGroup, next: TimelineGroup | undefined): string | undefined;
+/**
+ * Render one non-activity timeline item (chat message, status divider, goal
+ * landmark, notice). Exported so the component demo draws the EXACT same rows as
+ * the live app — no forked bubble/goal markup.
+ */
+export declare function TimelineRow({ item, renderMessageText, onReconnect, resolveProviderLogo, onOpenSession, }: {
+    item: TimelineItem;
+    renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
+    onReconnect?: ((item: AuthNeededItem) => void | Promise<void>) | undefined;
+    resolveProviderLogo?: ((providerDomain: string) => string | null | undefined) | undefined;
+    onOpenSession?: ((sessionId: string) => void) | undefined;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/model-picker.d.ts

@@ -0,0 +1,19 @@
+import type { ClientModel } from "@opengeni/sdk";
+import { type PickerModelRow } from "../model-policy";
+export type ModelPickerProps = {
+    /** Legacy host config models grouped by provider. */
+    models?: ClientModel[] | undefined;
+    /** Catalog-backed rows grouped by billing class. Preferred when available. */
+    rows?: PickerModelRow[] | undefined;
+    value?: string | undefined;
+    onChange: (modelId: string) => void;
+    disabled?: boolean | undefined;
+    className?: string | undefined;
+    label?: string | undefined;
+    /**
+     * When true (remote compaction v2), non-Codex models remain listed but are
+     * disabled. Same picker chrome — only selectability changes.
+     */
+    codexOnly?: boolean | undefined;
+};
+export declare function ModelPicker({ models, rows, value, onChange, disabled, className, label, codexOnly, }: ModelPickerProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/pierre-diff.d.ts

@@ -0,0 +1,34 @@
+import type { GitFileDiff } from "@opengeni/sdk";
+import { type ReactNode } from "react";
+export type PierreDiffProps = {
+    diff: GitFileDiff[];
+    layout?: "unified" | "split" | undefined;
+    themeType?: "dark" | "light" | undefined;
+    /** Shiki bundled theme names (dark/light) — derived from the host palette. */
+    theme?: {
+        dark: string;
+        light: string;
+    } | undefined;
+    /** Disable Pierre's worker pool if its worker bundling fights the host bundler. */
+    disableWorkerPool?: boolean | undefined;
+    /** Rendered while the (lazy) Pierre bundle loads. */
+    loading?: ReactNode | undefined;
+    /** Rendered if `@pierre/diffs/react` is not installed / fails to import. */
+    fallback?: ReactNode | undefined;
+    /** Skip the Shiki renderer entirely and show the plain-text degrade (the old
+     *  `usePierre={false}` path — one renderer, opted out of highlighting). */
+    plain?: boolean | undefined;
+    /** Long-line handling: `"wrap"` soft-wraps (the default — a diff in a narrow
+     *  dock pane should be readable without a horizontal-scroll tax), `"scroll"`
+     *  keeps lines on one row behind a horizontal scrollbar (better for a wide
+     *  viewport or pathological minified lines). */
+    overflow?: "wrap" | "scroll" | undefined;
+    className?: string | undefined;
+};
+/**
+ * The Pierre-backed diff: Shiki-highlighted, virtualized, unified/split. Renders
+ * one `PatchDiff` per changed file (a reconstructed unified patch from the
+ * `GitFileDiff` hunks). The ONE workbench diff renderer; a host without
+ * `@pierre/diffs` gets the built-in plain-text degrade (`PlainPatch`).
+ */
+export declare function PierreDiff({ diff, layout, themeType, theme, disableWorkerPool, loading, fallback, plain, overflow, className, }: PierreDiffProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/pierre-file.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+export type PierreFileProps = {
+    /** Workspace-relative path (used for the header + language inference). */
+    path: string;
+    /** The decoded text contents. */
+    contents: string;
+    themeType?: "dark" | "light" | undefined;
+    /** Shiki bundled theme names (dark/light) — derived from the host palette. */
+    theme?: {
+        dark: string;
+        light: string;
+    } | undefined;
+    /** Disable Pierre's worker pool if its worker bundling fights the host bundler. */
+    disableWorkerPool?: boolean | undefined;
+    /** Rendered while the (lazy) Pierre bundle loads. */
+    loading?: ReactNode | undefined;
+    /** Rendered if `@pierre/diffs/react` is not installed / fails to import. */
+    fallback?: ReactNode | undefined;
+    className?: string | undefined;
+};
+/**
+ * The Pierre-backed single-file VIEWER: Shiki-highlighted, language inferred from
+ * the filename — the read complement of `PierreDiff`. Wired to `fs.read` so
+ * clicking any file in the tree shows its contents (NOT a diff; no repo needed).
+ * Falls back to a plain `<pre>` when `@pierre/diffs` is absent / fails to import.
+ */
+export declare function PierreFile({ path, contents, themeType, theme, disableWorkerPool, loading, fallback, className, }: PierreFileProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/queue-draft-policy.d.ts

@@ -0,0 +1,7 @@
+import type { ComposerState } from "../hooks/use-composer";
+/**
+ * Decide whether checking out a queued prompt would replace current composer
+ * content. `hasDraftContent` reads the synchronous draft refs, so this stays
+ * correct even when a controlled input update has not rendered yet.
+ */
+export declare function requestQueueDraftEdit(composer: Pick<ComposerState, "hasDraftContent">, confirmReplacement: () => void, editImmediately: () => void): void;

package/dist/components/queue-surface-implementation.d.ts

@@ -0,0 +1,20 @@
+import type { ComposerState } from "../hooks/use-composer";
+import type { UseTurnQueueResult } from "../hooks/use-turn-queue";
+/** The sole pending-input surface: compact above Goal, Agents, and composer. */
+type QueueSurfaceCommonProps = {
+    /** Focus the composer owned by this queue after checkout/removal. */
+    onRequestComposerFocus?: (() => void) | undefined;
+};
+export type QueueSurfaceProps = (QueueSurfaceCommonProps & {
+    queue: UseTurnQueueResult;
+    composer: ComposerState;
+    readOnly?: false | undefined;
+}) | (QueueSurfaceCommonProps & {
+    queue: UseTurnQueueResult;
+    composer?: undefined;
+    readOnly: true;
+});
+/** @internal Pure policy seam for queue/composer embedding tests. */
+export declare function queueComposerCheckoutEnabled(composer: ComposerState | undefined, readOnly: boolean): boolean;
+export declare function QueueSurface({ queue, composer, readOnly, onRequestComposerFocus, }: QueueSurfaceProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/queue-surface-state.d.ts

@@ -0,0 +1,12 @@
+import type { UseTurnQueueResult } from "../hooks/use-turn-queue";
+type QueueStateProps = {
+    queue: UseTurnQueueResult;
+};
+export declare function EmptyQueueStateSurface({ queue }: QueueStateProps): import("react/jsx-runtime").JSX.Element;
+export declare function QueueStoppingStatus({ queue, dividerAfter, }: QueueStateProps & {
+    dividerAfter?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function QueueErrorAlert({ queue, dividerBefore, }: QueueStateProps & {
+    dividerBefore?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/queue-surface.d.ts

@@ -0,0 +1,12 @@
+import { type ComponentType } from "react";
+import type { QueueSurfaceProps } from "./queue-surface-implementation";
+export { requestQueueDraftEdit } from "./queue-draft-policy";
+export type { QueueSurfaceProps } from "./queue-surface-implementation";
+type QueueSurfaceModule = {
+    QueueSurface: ComponentType<QueueSurfaceProps>;
+};
+type QueueSurfaceLoader = () => Promise<QueueSurfaceModule>;
+/** The sole pending-input surface: compact above Goal, Agents, and composer. */
+export declare const QueueSurface: (props: QueueSurfaceProps) => import("react/jsx-runtime").JSX.Element | null;
+/** @internal Deterministic Suspense seam for the QueueSurface regression suite. */
+export declare function createQueueSurfaceForTest(loadImplementation: QueueSurfaceLoader): (props: QueueSurfaceProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/sandbox-files.d.ts

@@ -0,0 +1,49 @@
+import { type UseSandboxFilesResult } from "../hooks/use-sandbox-files";
+import type { UseSandboxGitResult } from "../hooks/use-sandbox-git";
+export type SandboxFilesProps = {
+    /** From `useSandboxFiles(...)`. */
+    files: UseSandboxFilesResult;
+    /** From `useSandboxGit(...)` — drives the branch/dirty header only. */
+    git: UseSandboxGitResult;
+    /** @deprecated Diffs live in the dedicated Changes tab now; accepted for
+     *  source-compat but unused (the Files surface is a browser + viewer). */
+    stagedGit?: UseSandboxGitResult | undefined;
+    /** Whether a FileSystem surface is advertised (drives the unavailable notice). */
+    fileSystemAvailable?: boolean | undefined;
+    /** Use Pierre's Shiki highlighter for the viewer (default true; plain fallback). */
+    usePierre?: boolean | undefined;
+    /** Allow in-place editing of tree files (CodeMirror). Default true. When false
+     *  the surface is review-only: every text file opens in the read-only viewer. */
+    editable?: boolean | undefined;
+    /** Fired once when the user first edits an open file (wake-on-edit intent). The
+     *  dock warms the box on this so the save lands fast; opening/reading never fires
+     *  it. Browsing the tree/diff must not warm a box. */
+    onEditIntent?: (() => void) | undefined;
+    /** A guarded diff path routed here by the parent workspace. */
+    requestedPath?: string | undefined;
+    /** Identity for one guarded-file request. Increment this when the same path is
+     *  deliberately requested again; it also lets a pending request be consumed
+     *  without overriding later manual tree navigation. Defaults to the path. */
+    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;
+};
+/**
+ * The Files surface: a branch/dirty header, the full lazy file tree, and a
+ * viewer/editor pane for the selected file. This is the workspace BROWSER — pick
+ * a file to read or edit it. Diff review lives in the dedicated Changes tab (this
+ * surface deliberately does NOT replicate the changed-files list, and does not
+ * diff here — one job per tab). The agent commits; the human reviews.
+ */
+export declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, requestedPath, requestedPathRequestId, requestedPathReady, workspaceResting, workspaceWaking, liveWorkspaceReady, onWakeWorkspace, themeType, className, }: SandboxFilesProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/sandbox-terminal.d.ts

@@ -0,0 +1,123 @@
+import type { TerminalCapability } from "@opengeni/sdk";
+import { type ReactNode } from "react";
+import type { UseSandboxTerminalResult } from "../hooks/use-sandbox-terminal";
+import { type RendererTier } from "../lib/xterm-renderer";
+/**
+ * A COMPLETE xterm `ITheme` (subset by intent, but every field xterm colors a
+ * cell with is present so it never falls back to its stock VGA palette). Built
+ * from the og tokens via `xtermThemeFromTokens`.
+ */
+export type XtermTheme = {
+    background?: string;
+    foreground?: string;
+    cursor?: string;
+    cursorAccent?: string;
+    selectionBackground?: string;
+    selectionForeground?: string;
+    selectionInactiveBackground?: string;
+    black?: string;
+    red?: string;
+    green?: string;
+    yellow?: string;
+    blue?: string;
+    magenta?: string;
+    cyan?: string;
+    white?: string;
+    brightBlack?: string;
+    brightRed?: string;
+    brightGreen?: string;
+    brightYellow?: string;
+    brightBlue?: string;
+    brightMagenta?: string;
+    brightCyan?: string;
+    brightWhite?: string;
+};
+export type SandboxTerminalProps = {
+    /** From `useSandboxTerminal(...)`. */
+    result: UseSandboxTerminalResult;
+    /**
+     * The negotiated Terminal capability cell. When it advertises `transport:
+     * "pty-ws"` + a live `url` (a warm box with a viewer attached), the terminal is
+     * driven by a REAL bidirectional PTY over the Modal tunnel (ttyd-over-websocket)
+     * INSTEAD of the broken ptyWrite-over-HTTP path: xterm input → the socket, the
+     * socket's output → xterm, xterm resize → the socket. On a cold box / no url
+     * (`transport: "sse-events"`) it stays on the read-only Channel-A firehose
+     * (`result.chunks`). Omit to force the legacy firehose-only behavior.
+     */
+    terminalCapability?: TerminalCapability | null | undefined;
+    /**
+     * Full xterm theme. When omitted the terminal self-derives it from the `--og-*`
+     * tokens of its own container (correct even inside a nested `data-og-theme`
+     * subtree). Passing it lets the host drive re-theme on a theme flip.
+     */
+    theme?: XtermTheme | undefined;
+    fontFamily?: string | undefined;
+    fontSize?: number | undefined;
+    /**
+     * Lease liveness (`cold` | `warming` | `warm` | `draining`). Drives the
+     * boot-in-terminal status lines: once the user has focused the terminal and
+     * the box is not yet warm, a styled "● waking machine — Ns…" line is rendered
+     * INSIDE xterm (no overlay/spinner) until the live PTY connects.
+     */
+    liveness?: string | undefined;
+    /**
+     * Force read-only even when the PTY accepts stdin. Default: interactive
+     * whenever a live pty-ws stream is connected OR `result.write !== null` (the box
+     * advertises an interactive PTY); otherwise the read-only agent firehose.
+     */
+    readOnly?: boolean | undefined;
+    /** Shown on the server / before xterm hydrates (SSR-safe placeholder). */
+    placeholder?: ReactNode | undefined;
+    /** Render the small status header (pty/shell + running dot + read-only pill). */
+    showHeader?: boolean | undefined;
+    /** Shell label for the header (e.g. `/bin/bash`). */
+    shell?: string | undefined;
+    /**
+     * Fired the first time the user engages the terminal surface (focus or click).
+     * The host wires this to warm the box for the REAL pty-ws terminal (the viewer
+     * attach), so a cold box upgrades from the read-only firehose to a live PTY ON
+     * INTERACT — never on mere mount (which would force a box spin-up and regress
+     * the firehose-only default).
+     */
+    onActivate?: (() => void) | undefined;
+    className?: string | undefined;
+};
+/** Debug seam (dev/evidence only, never a typed public API): a global hook the
+ *  screenshot harness reads to probe the settled renderer tier + resolved font
+ *  without mounting a real WebGL context in unit tests. */
+type TerminalDebugInfo = {
+    renderer: RendererTier | null;
+    fontFamily: string | undefined;
+    fontSize: number | undefined;
+    hasVarInFont: boolean;
+    theme: XtermTheme | undefined;
+    /** The live xterm instance (opaque) — the evidence harness reads its buffer to
+     *  prove screen preservation (E5) and drive the burst-responsiveness probe. */
+    term: unknown;
+};
+declare global {
+    var __OG_TERMINAL_DEBUG__: ((info: TerminalDebugInfo) => void) | undefined;
+    var __OG_FORCE_RENDERER_FAIL__: string | undefined;
+}
+/**
+ * An xterm.js terminal fed by the Channel-A event projection
+ * (`useSandboxTerminal`) or a live ttyd PTY. xterm + its addons are lazy-imported
+ * inside an effect, so SSR renders the placeholder and the terminal mounts on
+ * hydration.
+ *
+ * Renderer: WebGL (GPU-composited cells) with a canvas → DOM fallback ladder
+ * (`attachRenderer`), so bursty output stays smooth but a lost/blocklisted
+ * context degrades gracefully. Font + theme are resolved to CONCRETE values
+ * from the og tokens BEFORE construction (xterm measures glyphs in a canvas
+ * where `var()` never resolves, and colors every cell from a full ANSI palette).
+ *
+ * The terminal is mounted ONCE and its data source is swapped in place: the
+ * read-only firehose (`result.chunks`) → the live PTY. Stdin is toggled via
+ * `term.options.disableStdin` at runtime (not a remount), so scrollback and the
+ * visible screen survive the projection→PTY handoff.
+ *
+ * Resizes are tracked with a `ResizeObserver` on the container (not just
+ * `window.resize`) so dragging the dock handle refits the grid.
+ */
+export declare function SandboxTerminal({ result, terminalCapability, theme, fontFamily, fontSize, liveness, readOnly, placeholder, showHeader, shell, onActivate, className, }: SandboxTerminalProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/sandbox-workspace.d.ts

@@ -0,0 +1,128 @@
+import { type ReactNode } from "react";
+import type { SessionEvent } from "@opengeni/sdk";
+import { type ClientOverride } from "../provider";
+import { type MachineChip } from "../hooks/use-machine-chip";
+import type { MachineView } from "../types/machines";
+import { type WorkspaceDockProps, type WorkspaceTab } from "./workspace-dock";
+/** A host-routed notification (replaces the app-only `sonner` toast coupling). */
+export type WorkspaceNotification = {
+    kind: "error" | "info";
+    message: string;
+};
+/** The workbench's canonical tab ids (a host injects extras around these). */
+export declare const WORKBENCH_TAB_CHANGES = "changes";
+export declare const WORKBENCH_TAB_FILES = "files";
+export declare const WORKBENCH_TAB_TERMINAL = "terminal";
+export 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.
+ */
+export declare const WORKBENCH_SURFACES: readonly ["changes", "files", "terminal", "desktop"];
+export 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
+ * "changes exist → Changes, else Files" needs zero machine round-trips. A host
+ * `override` (e.g. a landing "run" tab) wins when supplied.
+ *
+ * `<SandboxWorkspace>` uses this only as an optional early hint after its own
+ * capture GET reports no durable capture. A pure embedder needs no events-at-mount
+ * contract: it falls through to authoritative live Git instead.
+ */
+export declare function initialWorkspaceTab(events: SessionEvent[] | undefined, override?: string | null): string;
+export type WorkspaceMachine = {
+    /** 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. */
+    activeMachine: MachineView | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+export 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;
+    /** Host-routed notifications (mutation errors, desktop-consent failures). The
+     *  package never imports a toast library — the host decides how to surface. */
+    onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
+    /** File requested by a Changes guard. The Files surface defers the read until
+     *  the sandbox is live, then reveals this path. */
+    requestedFilePath?: string | null | undefined;
+    /** Unique identity for `requestedFilePath`, including repeated requests for the
+     *  same path. */
+    requestedFileRequestId?: string | number | null | undefined;
+    /** Route a guarded diff into the host's Files tab. */
+    onOpenFile?: ((path: string) => void) | undefined;
+};
+export type UseSandboxWorkspaceTabsResult = {
+    /** Changes | Files | Terminal | Desktop (capability-gated where noted). */
+    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, 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;
+};
+/**
+ * Build the workbench tabs + the machine-chip model for one session. This is the
+ * dock "brain": capability negotiation, capture-backed cold reads, prewarm
+ * flags, desktop consent, and the xterm theme observer — all package-local.
+ */
+export declare function useSandboxWorkspaceTabs(options: UseSandboxWorkspaceTabsOptions): UseSandboxWorkspaceTabsResult;
+export type SandboxWorkspaceProps = ClientOverride & {
+    sessionId: string;
+    /** Live event log (usually `useSessionEvents().events`). */
+    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). */
+    trailingTabs?: WorkspaceTab[] | undefined;
+    /** Override the pre-paint default tab (e.g. a host landing tab id). When
+     *  omitted the workbench decides from capture, then live Git when no capture exists. */
+    initialTab?: string | undefined;
+    /** Host-routed notifications (no toast dependency in the package). */
+    onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
+    /** Controlled collapsed state for hosts with their own dock toggle. */
+    collapsed?: boolean | undefined;
+    onCollapsedChange?: ((collapsed: boolean) => void) | undefined;
+    /** Host navigation shown only in the phone workspace overlay header. */
+    mobileLeadingControl?: ReactNode | undefined;
+    autoSaveId?: string | undefined;
+    defaultSize?: number | undefined;
+    minSize?: number | undefined;
+    maxSize?: number | undefined;
+    className?: string | undefined;
+};
+/**
+ * The whole session workspace, ready to mount: `<SandboxWorkspace>` assembles the
+ * capability-gated tabs, pins the machine-state chip in the dock header, and
+ * renders the resizable `<WorkspaceDock>`. Wrap the tree in `<OpenGeniProvider>`
+ * (client + workspaceId) and import `@opengeni/react/styles.css`; that is the
+ * entire integration (see `docs/embedding-workbench.md`).
+ */
+export declare function SandboxWorkspace(props: SandboxWorkspaceProps): ReactNode;
+export type { WorkspaceDockProps };

package/dist/components/session-chrome.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SessionChrome — compact merged session signals above the composer.
+ *
+ * Built-in session chrome for production and embeds. Token-themed
+ * (`--og-session-chrome-*`); hosts override on `.og-session-chrome` or an ancestor.
+ *
+ * ## Host tokens
+ * Defaults live in `tokens.css`.
+ *
+ * | Token | Role |
+ * | --- | --- |
+ * | `--og-session-chrome-surface` / `-open` | Dock fill (collapsed / expanded) |
+ * | `--og-session-chrome-border` / `-open` | Dock edge |
+ * | `--og-session-chrome-highlight` | Sliding chip selection pill |
+ * | `--og-session-chrome-shadow` / `-open` | Elevation |
+ * | `--og-session-chrome-radius` | Dock corner radius |
+ * | `--og-session-chrome-chip-min-height` | Signal chip height |
+ * | `--og-session-chrome-chip-pad-x` / `--og-session-chrome-chip-gap` | Chip padding / rail gap |
+ * | `--og-session-chrome-rail-pad` | Outer rail inset |
+ * | `--og-session-chrome-panel-pad-x` / `-y` | Expanded panel padding |
+ * | `--og-session-chrome-duration` / `--og-session-chrome-ease` | Expand + pill motion |
+ * | `--og-session-chrome-crossfade-duration` | Segment content opacity crossfade |
+ * | `--og-session-chrome-row-hover` | Inbox / queue row hover wash |
+ *
+ * Inbox and queue stay separate segments. Queue hover actions wire to
+ * `UseTurnQueueResult` (`editTurn` / `steerTurn` / `moveTurn` / `removeTurn`).
+ * Inbox has no product dismiss API; pass `onDismissIncoming` when the host
+ * wants a visible action (dev harness may use a local dummy).
+ *
+ * Segment switches keep the panel shell mounted and crossfade content while
+ * animating measured height — no `mode="wait"` unmount flash.
+ */
+import type { SessionGoal } from "@opengeni/sdk";
+import { type ReactNode } from "react";
+import type { ComposerState } from "../hooks/use-composer";
+import type { UseGoalResult } from "../hooks/use-goal";
+import type { UseTurnQueueResult } from "../hooks/use-turn-queue";
+export type SessionChromeSignalId = "incoming" | "queue" | "goal" | "agents";
+export type SessionChromeSignalTone = "neutral" | "accent" | "waiting" | "running";
+export type SessionChromeAgentsSignal = {
+    count: number;
+    detail?: string | undefined;
+    tone?: SessionChromeSignalTone | undefined;
+};
+export type SessionChromeProps = {
+    queue: UseTurnQueueResult;
+    /** Needed for queue edit → composer checkout. Omit with `readOnly`. */
+    composer?: ComposerState | undefined;
+    goal?: UseGoalResult | null | undefined;
+    /** Expanded agents body (host supplies tree / list). */
+    agentsPanel?: ReactNode;
+    /** Chip summary; when `count > 0` the agents segment appears. */
+    agentsSignal?: SessionChromeAgentsSignal | undefined;
+    /**
+     * Optional inbox dismiss. Product pending-inputs have no remove API — hosts
+     * (and the gallery) may still pass a handler so the action is visible.
+     */
+    onDismissIncoming?: ((inputId: string) => void) | undefined;
+    readOnly?: boolean | undefined;
+    className?: string | undefined;
+    /** Controlled active segment; omit for uncontrolled. */
+    active?: SessionChromeSignalId | null | undefined;
+    defaultActive?: SessionChromeSignalId | null | undefined;
+    onActiveChange?: ((next: SessionChromeSignalId | null) => void) | undefined;
+};
+type GoalPillState = "pursuing" | "scheduled" | "blocked" | "held" | "paused" | "invariant_broken" | "completed";
+/** Select pill state from the goal's authoritative continuation projection. */
+export declare function sessionChromeGoalPillState(goalStatus: "active" | "paused" | "completed", continuation: SessionGoal["continuation"] | null | undefined): GoalPillState;
+export declare function SessionChrome({ queue, composer, goal, agentsPanel, agentsSignal, onDismissIncoming, readOnly, className, active: activeControlled, defaultActive, onActiveChange, }: SessionChromeProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/session-status.d.ts

@@ -0,0 +1,25 @@
+import type { SessionStatus as SessionStatusValue } from "@opengeni/sdk";
+export type SessionStatusMeta = {
+    label: string;
+    /** Token-backed color classes for the dot and tinted badge. */
+    dotClassName: string;
+    badgeClassName: string;
+    /** Live states breathe; terminal states hold still. */
+    pulse: boolean;
+};
+export declare const SESSION_STATUS_META: Record<SessionStatusValue, SessionStatusMeta>;
+export type SessionStatusProps = {
+    status: SessionStatusValue;
+    /** Override the label ("Running" -> "Deploying", ...). */
+    label?: string | undefined;
+    size?: "sm" | "md" | undefined;
+    className?: string | undefined;
+};
+/** Status badge with a breathing dot for live states. */
+export declare function SessionStatus({ status, label, size, className }: SessionStatusProps): import("react/jsx-runtime").JSX.Element;
+export type StatusDotProps = {
+    status: SessionStatusValue;
+    className?: string | undefined;
+};
+/** Just the dot — for dense rows and tiles. */
+export declare function StatusDot({ status, className }: StatusDotProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/soften-streaming-markdown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Display-only softener for mid-stream markdown.
+ *
+ * While tokens are still arriving, incomplete markers (`**bold`, an open
+ * fence, a half-finished link) would otherwise render as raw punctuation —
+ * the hard "breaking" flash. This closes a small set of common unfinished
+ * constructs so the parse looks settled; the SOURCE string is never mutated
+ * (callers pass the softened copy only into the markdown parser).
+ *
+ * When the real closers land, the softened and true parses converge and the
+ * crystallize breath covers the remount.
+ */
+export declare function softenStreamingMarkdown(source: string): string;