@opengeni/react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,897 @@
+import { OpenGeniClient, Session, ResourceRef, ToolRef, SessionStatus as SessionStatus$1, SessionEvent, StreamConnectionState, SendMessageInput, FileAsset, FileResourceRef, SessionTurn, UpdateSessionTurnRequest, SessionGoal, ScheduledTask, WorkspaceEnvironment, CreateWorkspaceEnvironmentRequest, UpdateWorkspaceEnvironmentRequest, WorkspaceEnvironmentVariableMetadata, CapabilityPack, PackInstallation, RegisterCapabilityPackRequest, WorkspaceRegisteredPack, EnablePackRequest, Workspace, CreateWorkspaceRequest, UpdateWorkspaceRequest, BillingBalance, UsageEvent, Permission } from '@opengeni/sdk';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, KeyboardEvent, ClipboardEvent } from 'react';
+import { ClassValue } from 'clsx';
+
+/**
+ * The slice of `OpenGeniClient` the hooks depend on. Structural, so apps can
+ * pass the real SDK client, a proxy-backed client that routes through their
+ * own API, or a scripted client in tests/demos.
+ */
+type SessionClientLike = Pick<OpenGeniClient, "getSession" | "listSessions" | "sendMessage" | "steerMessage" | "interrupt" | "sendApprovalDecision" | "streamEvents" | "listTurns" | "updateQueuedTurn" | "reorderQueuedTurns" | "deleteQueuedTurn" | "getGoal" | "updateGoal" | "clearSessionContext" | "compactSessionContext" | "listScheduledTasks" | "uploadFile" | "getFile" | "createFileDownloadUrl" | "listEnvironments" | "createEnvironment" | "updateEnvironment" | "deleteEnvironment" | "setEnvironmentVariable" | "deleteEnvironmentVariable" | "listPacks" | "registerPack" | "enablePack" | "deletePack" | "listWorkspaces" | "createWorkspace" | "updateWorkspace" | "getBillingUsage">;
+
+type OpenGeniContextValue = {
+    client: SessionClientLike;
+    workspaceId: string;
+};
+type OpenGeniProviderProps = {
+    client: SessionClientLike;
+    workspaceId: string;
+    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, children }: OpenGeniProviderProps): react_jsx_runtime.JSX.Element;
+type ClientOverride = {
+    client?: SessionClientLike | undefined;
+    workspaceId?: string | undefined;
+};
+/** Resolve client + workspace from explicit overrides or the provider. */
+declare function useOpenGeni(override?: ClientOverride): OpenGeniContextValue;
+/**
+ * Resolve the client only — for hooks that are not workspace-scoped
+ * (`useWorkspaces`, `useBillingUsage`).
+ */
+declare function useOpenGeniClient(override?: Pick<ClientOverride, "client">): SessionClientLike;
+
+type UseSessionOptions = ClientOverride & {
+    /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseSessionResult = {
+    session: Session | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** Fetch one session (with optional polling). */
+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;
+    status: "running" | "complete";
+    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";
+    occurredAt: string;
+};
+type SandboxItem = {
+    kind: "sandbox";
+    id: string;
+    turnId: string | null;
+    name: string;
+    command: string | null;
+    output: string;
+    status: "running" | "complete" | "failed";
+    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" | "continuation";
+    text: string | null;
+    occurredAt: string;
+};
+type NoticeItem = {
+    kind: "notice";
+    id: string;
+    tone: "waiting" | "cancelled" | "failed";
+    text: string;
+    occurredAt: string;
+};
+type TimelineItem = UserMessageItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | SessionStatusItem | GoalItem | NoticeItem;
+declare function buildTimeline(events: SessionEvent[]): TimelineItem[];
+/** The latest session status carried in the event log, if any. */
+declare function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus$1 | null;
+type TimelineGroup = {
+    kind: "item";
+    item: TimelineItem;
+} | {
+    kind: "activity";
+    id: string;
+    items: (ReasoningItem | ToolCallItem | WorkerItem | SandboxItem)[];
+};
+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? }`).
+ */
+declare function extractSessionRef(value: unknown, depth?: number): string | null;
+/** Readable label for a tool call ("session_create" -> "session create"). */
+declare function toolDisplayName(name: string): string;
+/** Compact, single-line preview of tool arguments/outputs for collapsed rows. */
+declare function compactPayloadPreview(value: unknown, maxLength?: number): string;
+
+type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
+type UseSessionEventsOptions = ClientOverride & {
+    /** Resume after this sequence (exclusive). Defaults to 0 = full replay. */
+    after?: number | undefined;
+    /** Pause the stream without unmounting (e.g. hidden tab). Defaults to true. */
+    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;
+    error: Error | null;
+};
+/**
+ * Live-stream a session's event log with replay-by-sequence, reconnect, and
+ * batched React updates. The SDK guarantees ordered, gap-free, exactly-once
+ * delivery; this hook accumulates the log and projects it into a timeline.
+ */
+declare function useSessionEvents(sessionId: string | null | undefined, options?: UseSessionEventsOptions): UseSessionEventsResult;
+
+type ComposerSendExtras = Omit<SendMessageInput, "text" | "clientEventId">;
+/**
+ * Compose-time delivery choice. `queue` (the default) stacks the message
+ * behind the running turn — visible, editable, reorderable until claimed.
+ * `steer` interrupts the running turn and injects the message now.
+ */
+type ComposerMode = "queue" | "steer";
+type UseComposerOptions = ClientOverride & {
+    /** 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;
+    /** Initial delivery mode. Defaults to `"queue"`. */
+    defaultMode?: ComposerMode | undefined;
+};
+type ComposerState = {
+    value: string;
+    setValue: (value: string) => void;
+    /** Send the draft (or an explicit text) using the current mode. */
+    send: (text?: string) => Promise<boolean>;
+    sending: boolean;
+    canSend: boolean;
+    /** Queue (default) vs steer — the compose-time delivery choice. */
+    mode: ComposerMode;
+    setMode: (mode: ComposerMode) => void;
+    /** Ask the agent to stop the current turn. */
+    interrupt: (reason?: string) => Promise<void>;
+    interrupting: boolean;
+    error: Error | null;
+    clearError: () => void;
+};
+/**
+ * Draft + send + interrupt 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;
+/**
+ * Merge the draft text + idempotency key with caller-provided extras. The
+ * text and clientEventId always win over extras. Exported for tests.
+ */
+declare function composeSendInput(text: string, clientEventId: string, extras: ComposerSendExtras | (() => ComposerSendExtras) | undefined): SendMessageInput;
+/** Submit on plain Enter; Shift+Enter inserts a newline. Exported for tests. */
+declare function shouldSubmitOnKey(event: {
+    key: string;
+    shiftKey: boolean;
+    nativeEvent?: {
+        isComposing?: 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;
+    /** 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;
+
+type SessionEventFeedOptions = {
+    /**
+     * Share an existing event log (from `useSessionEvents`) instead of opening
+     * a second stream. When omitted the hook tails the session's event stream
+     * itself, starting at the current `lastSequence`.
+     */
+    events?: SessionEvent[] | undefined;
+    enabled?: boolean | undefined;
+};
+
+/** Event types that change the turn queue (queue/edit/reorder/claim/finish). */
+declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
+/** Queued turns in execution order (position, then creation time). */
+declare function queueFromTurns(turns: SessionTurn[]): SessionTurn[];
+/** The turn currently holding the session (running or awaiting approval). */
+declare function activeTurnFromTurns(turns: SessionTurn[]): SessionTurn | null;
+/** Optimistic projection of a queued-turn edit. */
+declare function applyTurnEdit(turns: SessionTurn[], turnId: string, update: UpdateSessionTurnRequest): SessionTurn[];
+/**
+ * Optimistic projection of a reorder, mirroring the server: the listed
+ * queued turns get positions 1..n in the given order; everything else keeps
+ * its position.
+ */
+declare function applyTurnReorder(turns: SessionTurn[], turnIds: string[]): SessionTurn[];
+/** Optimistic projection of a queued-turn delete (server marks it cancelled). */
+declare function applyTurnRemoval(turns: SessionTurn[], turnId: string): SessionTurn[];
+type UseTurnQueueOptions = ClientOverride & SessionEventFeedOptions & {
+    /** Optional safety-net polling (ms). Off by default — turn.* events drive updates. */
+    pollIntervalMs?: number | undefined;
+};
+type UseTurnQueueResult = {
+    /** All turns the API returned (history + queue), newest server view. */
+    turns: SessionTurn[];
+    /** Queued turns in execution order — render this as the editable queue. */
+    queue: SessionTurn[];
+    /** The running / requires_action turn, if any. */
+    activeTurn: SessionTurn | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** Edit a queued turn (optimistic; rolls back via refetch on failure). */
+    editTurn: (turnId: string, update: UpdateSessionTurnRequest) => Promise<SessionTurn | null>;
+    /** Reorder the queue to the given queued-turn id order (optimistic). */
+    reorderTurns: (turnIds: string[]) => Promise<SessionTurn[] | null>;
+    /** Delete (cancel) a queued turn before it is claimed (optimistic). */
+    removeTurn: (turnId: string) => Promise<SessionTurn | null>;
+    /** True while an edit/reorder/remove is in flight. */
+    mutating: boolean;
+    /** Last failed mutation, until the next mutation or clear. */
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * The live turn queue — the heart of the queue-by-default interaction model.
+ * Messages sent mid-turn stack up here, visible and editable/reorderable/
+ * deletable until the worker claims them. Updates arrive over the session
+ * event stream (`turn.*`), either shared via `options.events` (pass the log
+ * from `useSessionEvents` to reuse its connection) or a dedicated tail
+ * stream. All mutations apply optimistically and reconcile with the server.
+ */
+declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;
+
+/** 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 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>;
+    /** True while a pause/resume is in flight. */
+    updating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * The session's goal: state, the autonomy counters (`autoContinuations`,
+ * `noProgressStreak`), and pause/resume control. A goal-less session yields
+ * `goal: null` (the 404 is absorbed). Live-updates on `goal.*` events —
+ * pass `options.events` from `useSessionEvents` to reuse its stream.
+ */
+declare function useGoal(sessionId: string | null | undefined, options?: UseGoalOptions): UseGoalResult;
+
+type UseSessionControlOptions = ClientOverride;
+type UseSessionControlResult = {
+    /** Interrupt the running turn (the explicit alternative to queueing). */
+    interrupt: (reason?: string) => Promise<SessionEvent | null>;
+    interrupting: 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;
+    error: Error | null;
+    clearError: () => void;
+};
+/**
+ * Session control events: interrupt and approval decisions. Pair with
+ * `useSessionEvents` (for `session.requiresAction` payloads carrying the
+ * `approvalId`) to render an approval bar.
+ */
+declare function useSessionControl(sessionId: string | null | undefined, options?: UseSessionControlOptions): UseSessionControlResult;
+
+type UseScheduledTasksOptions = ClientOverride & {
+    limit?: number | undefined;
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseScheduledTasksResult = {
+    tasks: ScheduledTask[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** List the workspace's scheduled tasks (drift checks, sentinels, reapers, ...). */
+declare function useScheduledTasks(options?: UseScheduledTasksOptions): UseScheduledTasksResult;
+
+type UseWorkspaceSessionsOptions = ClientOverride & {
+    limit?: number | undefined;
+    /** Refresh interval (ms) for fleet/manager views. Off by default. */
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseWorkspaceSessionsResult = {
+    sessions: Session[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+/** List the workspace's sessions — the data behind fleet and manager views. */
+declare function useWorkspaceSessions(options?: UseWorkspaceSessionsOptions): UseWorkspaceSessionsResult;
+
+type UseEnvironmentsOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+type UseEnvironmentsResult = {
+    environments: WorkspaceEnvironment[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    create: (request: CreateWorkspaceEnvironmentRequest) => Promise<WorkspaceEnvironment | null>;
+    update: (environmentId: string, request: UpdateWorkspaceEnvironmentRequest) => Promise<WorkspaceEnvironment | null>;
+    remove: (environmentId: string) => Promise<boolean>;
+    /** Set/rotate a variable. Values are write-only — reads expose metadata only. */
+    setVariable: (environmentId: string, name: string, value: string) => Promise<WorkspaceEnvironmentVariableMetadata | null>;
+    deleteVariable: (environmentId: string, name: string) => Promise<boolean>;
+    mutating: boolean;
+    mutationError: Error | null;
+    clearMutationError: () => void;
+};
+/**
+ * Workspace environments (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.
+ */
+declare function useEnvironments(options?: UseEnvironmentsOptions): UseEnvironmentsResult;
+
+type UsePacksOptions = ClientOverride & {
+    pollIntervalMs?: number | undefined;
+    enabled?: boolean | undefined;
+};
+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;
+};
+/**
+ * The caller's workspaces (workspace switchers, onboarding). Not scoped to
+ * the provider's workspace, so it only needs the client.
+ */
+declare function useWorkspaces(options?: UseWorkspacesOptions): UseWorkspacesResult;
+
+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 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>;
+};
+/**
+ * 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 useBillingUsage(options?: UseBillingUsageOptions): UseBillingUsageResult;
+
+type PendingApproval = {
+    /** The id to send back via `user.approvalDecision` (`approvalId`). */
+    id: string;
+    /** Tool/function name awaiting the decision. */
+    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[];
+
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    clearView: () => boolean;
+    /** Show the danger confirm bar; resolves true once the operator confirms. */
+    confirm: () => Promise<boolean>;
+};
+type CommandResult = {
+    status: "ok" | "error";
+    message?: string;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * Dynamic availability beyond the permission gate (e.g. hide a server command
+     * until a session exists). Returning false hides the command.
+     */
+    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;
+};
+
+/**
+ * Parse a composer value into a command name + the rest. A command is
+ * recognized ONLY when the value's first character is "/" (the start token);
+ * anything else is plain chat and returns null.
+ *
+ * "/cl"        -> { name: "cl", rest: "", hasTrailingSpace: false }
+ * "/goal "     -> { name: "goal", rest: "", hasTrailingSpace: true }
+ * "/goal pause"-> { name: "goal", rest: "pause", hasTrailingSpace: false }
+ */
+type ParsedCommandLine = {
+    name: string;
+    rest: string;
+    /** True when the name token is closed by a space — arg-hint mode. */
+    hasTrailingSpace: boolean;
+    args: string[];
+};
+declare function parseCommandLine(value: string): ParsedCommandLine | null;
+/** Whether the operator's permission set satisfies a command's gate. */
+declare function hasPermission(required: Permission | undefined, permissions: Permission[]): boolean;
+/** Match a command (by name or alias) against the value. */
+declare function matchCommand(commands: readonly SlashCommand[], value: string): SlashCommand | null;
+type FilterCtx = Pick<CommandContext, "sessionId" | "status" | "permissions">;
+/**
+ * The commands visible for the current token + context. Permission-absent and
+ * `available()===false` commands are dropped entirely (a gated command is never
+ * shown, not shown-disabled). Filtering is a prefix match on name/alias.
+ */
+declare function filterCommands(commands: readonly SlashCommand[], token: string, ctx: FilterCtx): SlashCommand[];
+/** Render a command's arg hint for the palette footer / help, e.g. "<pause|resume>". */
+declare function argHint(args: readonly SlashArg[] | undefined): string;
+/** The first required arg that has not yet been supplied, if any. */
+declare function firstMissingRequiredArg(command: SlashCommand, args: string[]): SlashArg | null;
+/**
+ * The default command set. Adding a command is one object literal here; the
+ * palette list, filter, arg-hint footer, and /help all render from this array.
+ * Apps concat their own commands via the ChatComposer `commands` prop.
+ */
+declare const defaultCommands: readonly SlashCommand[];
+
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * 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.
+     */
+    onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => boolean;
+    /** Run the highlighted command (or the active command in arg-hint mode). */
+    runHighlighted: () => Promise<void>;
+    /**
+     * 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.
+     */
+    runAt: (index: number) => Promise<void>;
+    /** Autocomplete the highlighted command name + a trailing space. */
+    autocompleteHighlighted: () => void;
+};
+declare function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult;
+
+type CommandPaletteProps = {
+    open: boolean;
+    items: SlashCommand[];
+    highlight: number;
+    /** Hover/click selects a row. */
+    onHighlight: (index: number) => void;
+    /** Click runs the row (same path as Enter). */
+    onRun: (index: number) => void;
+    /** Footer arg hint shown in arg-hint mode (e.g. "<pause|resume>"). */
+    argHintText: string;
+    /** id used for aria-activedescendant wiring from the textarea. */
+    listboxId: string;
+};
+/**
+ * The slash-command palette: a popover anchored above the textarea, rendered
+ * entirely from the filtered registry. Dark-first, Linear/Vercel-calm, using
+ * 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;
+
+type ChatComposerProps = {
+    composer: ComposerState;
+    /** Current session status; shows the stop control while a turn runs. */
+    status?: SessionStatus$1 | null | 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;
+    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;
+};
+/**
+ * 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).
+ *
+ * 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.
+ */
+declare function ChatComposer({ composer, status, placeholder, disabled, autoFocus, hint, controlsStart, header, onPaste, attachments, className, commands, commandContext, onClearView, }: ChatComposerProps): react_jsx_runtime.JSX.Element;
+
+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; drives the live "working" indicator. */
+    status?: SessionStatus$1 | 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;
+    /** Follow new events when pinned to the bottom. Defaults to true. */
+    autoFollow?: boolean | 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.
+ */
+declare function MessageTimeline({ events, items, status, renderMessageText, onOpenSession, autoFollow, emptyState, className, }: MessageTimelineProps): react_jsx_runtime.JSX.Element;
+
+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;
+};
+declare const SESSION_STATUS_META: Record<SessionStatus$1, SessionStatusMeta>;
+type SessionStatusProps = {
+    status: SessionStatus$1;
+    /** Override the label ("Running" -> "Deploying", ...). */
+    label?: string | undefined;
+    size?: "sm" | "md" | undefined;
+    className?: string | undefined;
+};
+/** Status badge with a breathing dot for live states. */
+declare function SessionStatus({ status, label, size, className }: SessionStatusProps): react_jsx_runtime.JSX.Element;
+type StatusDotProps = {
+    status: SessionStatus$1;
+    className?: string | undefined;
+};
+/** Just the dot — for dense rows and tiles. */
+declare function StatusDot({ status, className }: StatusDotProps): react_jsx_runtime.JSX.Element;
+
+type FleetTileProps = {
+    session: Session;
+    /** Overrides the derived title (metadata.title/name, else the initial message). */
+    title?: string | undefined;
+    /** Extra line under the title — e.g. "drift check" or the worker's task. */
+    subtitle?: string | undefined;
+    onOpen?: ((session: Session) => void) | undefined;
+    className?: string | undefined;
+};
+/** Best-effort display title for a session. */
+declare function sessionDisplayTitle(session: Session): string;
+/**
+ * One session in the fleet/manager view: title, live status, model, and
+ * recency — dense but calm. Running sessions carry a breathing status dot
+ * and a faint accent edge so the live ones read at a glance.
+ */
+declare function FleetTile({ session, title, subtitle, onOpen, className }: FleetTileProps): react_jsx_runtime.JSX.Element;
+
+/** Merge class names with Tailwind-aware conflict resolution. */
+declare function cn(...inputs: ClassValue[]): string;
+
+/** Compact relative time: "now", "42s", "7m", "3h", "2d", then a date. */
+declare function formatRelativeTime(iso: string, now?: Date): string;
+/** Human-readable byte size: "512 B", "8.0 KB", "1.4 MB", "3 GB". */
+declare function formatBytes(bytes: number): string;
+/** Single-line preview of arbitrary text, for tiles and collapsed rows. */
+declare function truncate(text: string, maxLength: number): string;
+/** Render an unknown payload as readable text (pretty JSON when possible). */
+declare function stringifyPayload(value: unknown): string;
+/** JSON.parse that returns `undefined` instead of throwing. */
+declare function tryParseJson(text: string): unknown;
+
+export { type AgentMessageItem, ChatComposer, type ChatComposerProps, type ClientOverride, type CommandContext, CommandPalette, type CommandPaletteProps, type CommandResult, type ComposerMode, type ComposerSendExtras, type ComposerState, type ConfirmState, type FileAttachment, FleetTile, type FleetTileProps, type GoalItem, MessageTimeline, type MessageTimelineProps, type Notice, type NoticeItem, type OpenGeniContextValue, OpenGeniProvider, type OpenGeniProviderProps, type ParsedCommandLine, type PendingApproval, type ReasoningItem, SESSION_STATUS_META, type SandboxItem, type SessionClientLike, type SessionEventsConnectionState, SessionStatus, type SessionStatusItem, type SessionStatusMeta, type SessionStatusProps, type SlashArg, type SlashCommand, type SlashCommandContext, type SlashCommandHandlers, StatusDot, type StatusDotProps, type TimelineGroup, type TimelineItem, type ToolCallItem, type UseBillingUsageOptions, type UseBillingUsageResult, type UseComposerOptions, type UseEnvironmentsOptions, type UseEnvironmentsResult, type UseFileAttachmentsOptions, type UseFileAttachmentsResult, type UseGoalOptions, type UseGoalResult, type UsePacksOptions, type UsePacksResult, type UseScheduledTasksOptions, type UseScheduledTasksResult, type UseSessionControlOptions, type UseSessionControlResult, type UseSessionEventsOptions, type UseSessionEventsResult, type UseSessionOptions, type UseSessionResult, type UseSlashCommandsOptions, type UseSlashCommandsResult, type UseTurnQueueOptions, type UseTurnQueueResult, type UseWorkspaceSessionsOptions, type UseWorkspaceSessionsResult, type UseWorkspacesOptions, type UseWorkspacesResult, type UserMessageItem, type WorkerItem, activeTurnFromTurns, applyTurnEdit, applyTurnRemoval, applyTurnReorder, approvalsFromRequiresAction, argHint, buildTimeline, cn, compactPayloadPreview, composeSendInput, defaultCommands, extractSessionRef, filterCommands, firstMissingRequiredArg, formatBytes, formatRelativeTime, groupTimeline, hasPermission, isGoalEvent, isTurnQueueEvent, matchCommand, parseCommandLine, projectPendingApprovals, queueFromTurns, sessionDisplayTitle, sessionStatusFromEvents, shouldSubmitOnKey, stringifyPayload, toolDisplayName, truncate, tryParseJson, useBillingUsage, useComposer, useEnvironments, useFileAttachments, useGoal, useOpenGeni, useOpenGeniClient, usePacks, useScheduledTasks, useSession, useSessionControl, useSessionEvents, useSlashCommands, useTurnQueue, useWorkspaceSessions, useWorkspaces };