@opengeni/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,128 @@
 type SessionStatus = "queued" | "running" | "idle" | "requires_action" | "failed" | "cancelled";
-type SandboxBackend = "docker" | "modal" | "local" | "none";
+type SandboxBackend = "docker" | "modal" | "local" | "none" | "daytona" | "runloop" | "e2b" | "blaxel" | "cloudflare" | "vercel";
+type SandboxOs = "linux" | "macos" | "windows";
+type SandboxCapabilityName = "FileSystem" | "Terminal" | "Git" | "DesktopStream" | "Recording";
+type CapabilityUnavailableReason = "backend_unsupported" | "os_unsupported" | "not_provisioned" | "disabled_by_policy" | "lease_cold" | "tier_headless";
+type SessionCapabilities = {
+    sessionId: string;
+    backend: SandboxBackend;
+    os: SandboxOs;
+    liveness: "cold" | "warming" | "warm" | "draining";
+    leaseEpoch: number;
+    viewerHeartbeatIntervalMs: number;
+    FileSystem: {
+        available: boolean;
+        readOnly: boolean;
+        root: string;
+        pathSep: "/" | "\\";
+        treeMode: "lazy" | "snapshot";
+        reason: CapabilityUnavailableReason | null;
+    };
+    Terminal: {
+        transport: "sse-events" | "pty-ws" | null;
+        ptyCapable: boolean;
+        shell: string;
+        url: string | null;
+        token: string | null;
+        reason: CapabilityUnavailableReason | null;
+    };
+    Git: {
+        available: boolean;
+        repos: string[];
+        reason: CapabilityUnavailableReason | null;
+    };
+    DesktopStream: {
+        transport: "vnc-ws" | "rdp-ws" | "webrtc" | null;
+        client: "novnc" | "web-rdp" | null;
+        mode: "read-only" | "interactive";
+        url: string | null;
+        token: string | null;
+        expiresAt: string | null;
+        resolution: [number, number];
+        unredacted: boolean;
+        requiresAcknowledgment: boolean;
+        acknowledged: boolean;
+        shared: boolean;
+        sharedSessionIds: string[];
+        reason: CapabilityUnavailableReason | null;
+    };
+    Recording: {
+        available: boolean;
+        modes: ("manual" | "on-turn" | "on-verify")[];
+        codecs: ("h264-mp4" | "vp9-webm")[];
+        reason: CapabilityUnavailableReason | null;
+    };
+    ComputerUse: {
+        available: boolean;
+        readOnly: boolean;
+        reason: CapabilityUnavailableReason | null;
+    };
+    negotiatedAt: string;
+};
+type FileSystemCapability = SessionCapabilities["FileSystem"];
+type TerminalCapability = SessionCapabilities["Terminal"];
+type GitCapability = SessionCapabilities["Git"];
+type DesktopStreamCapability = SessionCapabilities["DesktopStream"];
+type RecordingCapability = SessionCapabilities["Recording"];
+type ComputerUseCapability = SessionCapabilities["ComputerUse"];
+type StreamUrlRotatedPayload = {
+    url: string;
+    token: string | null;
+    expiresAt: string | null;
+    leaseEpoch: number;
+    transport: "vnc-ws";
+    viewerId: string | null;
+};
+type StreamOpenedPayload = {
+    viewerId: string;
+    shared: boolean;
+    viewerCount: number;
+};
+type StreamClosedPayload = {
+    viewerId: string;
+    reason: "client-disconnect" | "reaped" | "revoked" | "box-rollover";
+    viewerCount: number;
+};
+type StreamRevokedPayload = {
+    viewerId: string | null;
+    reason: "grant-revoked" | "session-failed" | "admin";
+};
+type AttachViewerRequest = {
+    viewerId?: string | undefined;
+    desktop?: boolean | undefined;
+};
+type ViewerHolder = {
+    viewerId: string;
+    sandboxGroupId: string;
+    liveness: "cold" | "warming" | "warm" | "draining";
+    leaseEpoch: number;
+    viewerHeartbeatIntervalMs: number;
+    dataPlaneUrl: string | null;
+};
+type AttachViewerResponse = ViewerHolder & {
+    streamToken: string | null;
+    streamExpiresAt: string | null;
+    resolution: [number, number] | null;
+    transport: "vnc-ws" | null;
+    client: "novnc" | null;
+    terminalUrl: string | null;
+    terminalToken: string | null;
+    terminalTransport: "pty-ws" | null;
+};
+type AcknowledgeStreamRequest = {
+    acknowledgeUnredacted?: boolean | undefined;
+    acknowledgeShared?: boolean | undefined;
+};
+type AcknowledgeStreamResponse = {
+    acknowledged: boolean;
+    acknowledgedShared: boolean;
+};
+type ViewerHeartbeatRequest = {
+    leaseEpoch: number;
+};
+type ViewerHeartbeatResponse = {
+    alive: boolean;
+};
 type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 type RepositoryResourceRef = {
     kind: "repository";
@@ -68,7 +191,7 @@ type SessionTurn = {
     createdAt: string;
     updatedAt: string;
 };
-declare const SESSION_EVENT_TYPES: readonly ["session.created", "session.status.changed", "session.requiresAction", "session.context.compacted", "session.context.cleared", "user.message", "user.interrupt", "user.approvalDecision", "turn.queued", "turn.updated", "turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.preempted", "agent.message.delta", "agent.message.completed", "agent.reasoning.delta", "agent.toolCall.created", "agent.toolCall.output", "agent.updated", "sandbox.operation.started", "sandbox.operation.completed", "sandbox.operation.failed", "sandbox.command.output.delta", "artifact.created", "goal.set", "goal.updated", "goal.completed", "goal.paused", "goal.resumed", "goal.continuation"];
+declare const SESSION_EVENT_TYPES: readonly ["session.created", "session.status.changed", "session.requiresAction", "session.context.compacted", "session.context.cleared", "user.message", "user.interrupt", "user.approvalDecision", "turn.queued", "turn.updated", "turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.preempted", "agent.message.delta", "agent.message.completed", "agent.reasoning.delta", "agent.toolCall.created", "agent.toolCall.output", "agent.updated", "sandbox.operation.started", "sandbox.operation.completed", "sandbox.operation.failed", "sandbox.command.output.delta", "artifact.created", "goal.set", "goal.updated", "goal.completed", "goal.paused", "goal.resumed", "goal.continuation", "stream.url.rotated", "stream.opened", "stream.closed", "stream.revoked", "recording.started", "recording.available", "recording.failed", "fs.changed", "git.changed", "terminal.pty.started", "terminal.pty.output.delta", "terminal.pty.exited"];
 type KnownSessionEventType = (typeof SESSION_EVENT_TYPES)[number];
 /**
  * Event types the SDK knows about today, kept open so a newer OpenGeni server
@@ -106,6 +229,319 @@ type AgentToolCallOutputPayload = {
 type SessionStatusChangedPayload = {
     status: SessionStatus;
 };
+type RecordingMode = "manual" | "on-turn" | "on-verify";
+type RecordingCodec = "h264-mp4" | "vp9-webm";
+type RecordingContentType = "video/mp4" | "video/webm";
+type RecordingFailedReason = "ffmpeg-error" | "box-death" | "box-rollover" | "upload-failed" | "max-bytes-exceeded" | "display-unavailable";
+type RecordingStartedPayload = {
+    recordingId: string;
+    turnId: string | null;
+    mode: RecordingMode;
+    codec: RecordingCodec;
+    dimensions: [number, number];
+    framerate: number;
+    startedAt: string;
+    reason?: string | null | undefined;
+};
+type RecordingAvailablePayload = {
+    recordingId: string;
+    turnId: string | null;
+    codec: RecordingCodec;
+    contentType: RecordingContentType;
+    storageKey: string;
+    durationSeconds: number | null;
+    sizeBytes: number;
+    dimensions: [number, number];
+};
+type RecordingFailedPayload = {
+    recordingId: string;
+    turnId: string | null;
+    reason: RecordingFailedReason;
+    detail?: string | null | undefined;
+};
+type SandboxCommandOutputDeltaPayload = {
+    stream: "stdout" | "stderr";
+    chunk: string;
+    commandId?: string | undefined;
+    seq?: number | undefined;
+};
+type FsChangeKind = "created" | "modified" | "deleted" | "renamed";
+type FsChangedPayload = {
+    changes: {
+        path: string;
+        kind: FsChangeKind;
+        isDir: boolean;
+        sizeBytes: number | null;
+        oldPath?: string | undefined;
+    }[];
+    source: "write" | "watch" | "agent";
+    revision: number;
+    leaseEpoch: number;
+};
+type GitChangedPayload = {
+    head: string | null;
+    dirty: boolean;
+    ahead: number;
+    behind: number;
+    changedFileCount: number;
+    reason: "commit" | "checkout" | "stage" | "worktree" | "fetch" | "unknown";
+    revision: number;
+    leaseEpoch: number;
+};
+type TerminalPtyStartedPayload = {
+    ptyId: string;
+    cols: number;
+    rows: number;
+    shell: string;
+    cwd: string;
+};
+type TerminalPtyOutputDeltaPayload = {
+    ptyId: string;
+    stream: "stdout" | "stderr";
+    chunk: string;
+    seq: number;
+};
+type TerminalPtyExitedPayload = {
+    ptyId: string;
+    exitCode: number | null;
+    reason: "exit" | "killed" | "owner_gone" | "timeout";
+};
+type FsNodeType = "file" | "dir" | "symlink" | "other";
+type FsTreeNode = {
+    name: string;
+    path: string;
+    type: FsNodeType;
+    sizeBytes: number | null;
+    mtimeMs: number | null;
+    mode: number | null;
+    children?: FsTreeNode[] | undefined;
+    truncated: boolean;
+};
+type FsEncoding = "utf8" | "base64";
+type FsListRequest = {
+    path?: string;
+    depth?: number;
+    maxEntries?: number;
+    includeHidden?: boolean;
+};
+type FsListResponse = {
+    root: FsTreeNode;
+    revision: number;
+    truncated: boolean;
+};
+type FsReadRequest = {
+    path: string;
+    encoding?: FsEncoding;
+    maxBytes?: number;
+};
+type FsReadResponse = {
+    path: string;
+    encoding: FsEncoding;
+    content: string;
+    sizeBytes: number;
+    truncated: boolean;
+    isBinary: boolean;
+    revision: number;
+};
+type FsWriteRequest = {
+    path: string;
+    encoding?: FsEncoding;
+    content: string;
+    overwrite?: boolean;
+    createParents?: boolean;
+};
+type FsWriteResponse = {
+    path: string;
+    sizeBytes: number;
+    revision: number;
+};
+type FsDeleteRequest = {
+    path: string;
+    recursive?: boolean;
+};
+type FsDeleteResponse = {
+    revision: number;
+};
+type FsMoveRequest = {
+    path: string;
+    newPath: string;
+    overwrite?: boolean;
+    createParents?: boolean;
+};
+type FsMoveResponse = {
+    path: string;
+    newPath: string;
+    revision: number;
+};
+type FsMkdirRequest = {
+    path: string;
+    recursive?: boolean;
+};
+type FsMkdirResponse = {
+    path: string;
+    revision: number;
+};
+type GitFileStatusCode = "added" | "modified" | "deleted" | "renamed" | "copied" | "untracked" | "ignored" | "conflicted" | "typechange";
+type GitFileStatus = {
+    path: string;
+    oldPath: string | null;
+    index: GitFileStatusCode | null;
+    worktree: GitFileStatusCode | null;
+    isConflicted: boolean;
+};
+type GitStatusRequest = {
+    path?: string;
+};
+type GitStatusResponse = {
+    isRepo: boolean;
+    head: string | null;
+    detached: boolean;
+    upstream: string | null;
+    ahead: number;
+    behind: number;
+    files: GitFileStatus[];
+    revision: number;
+};
+type GitDiffLineType = "context" | "add" | "del" | "meta";
+type GitDiffLine = {
+    type: GitDiffLineType;
+    oldNo: number | null;
+    newNo: number | null;
+    text: string;
+};
+type GitDiffHunk = {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    header: string;
+    lines: GitDiffLine[];
+};
+type GitFileDiff = {
+    path: string;
+    oldPath: string | null;
+    status: GitFileStatusCode;
+    isBinary: boolean;
+    isImage: boolean;
+    additions: number;
+    deletions: number;
+    hunks: GitDiffHunk[];
+    truncated: boolean;
+};
+type GitDiffRequest = {
+    path?: string;
+    staged?: boolean;
+    fromRef?: string;
+    toRef?: string;
+    pathspec?: string[];
+    contextLines?: number;
+    maxBytesPerFile?: number;
+};
+type GitDiffResponse = {
+    files: GitFileDiff[];
+    revision: number;
+};
+type GitLogRequest = {
+    path?: string;
+    ref?: string;
+    maxCount?: number;
+    skip?: number;
+    pathspec?: string[];
+};
+type GitCommit = {
+    sha: string;
+    shortSha: string;
+    parents: string[];
+    author: {
+        name: string;
+        email: string;
+        timestamp: number;
+    };
+    committer: {
+        name: string;
+        email: string;
+        timestamp: number;
+    };
+    subject: string;
+    body: string;
+    refs: string[];
+};
+type GitLogResponse = {
+    commits: GitCommit[];
+    hasMore: boolean;
+};
+type GitShowRequest = {
+    path?: string;
+    ref: string;
+    filePath?: string;
+    encoding?: FsEncoding;
+    maxBytesPerFile?: number;
+};
+type GitShowResponse = {
+    commit: GitCommit | null;
+    files: GitFileDiff[];
+    blob: {
+        content: string;
+        encoding: FsEncoding;
+        sizeBytes: number;
+        truncated: boolean;
+    } | null;
+    revision: number;
+};
+type TerminalExecRequest = {
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+    emitStream?: boolean;
+};
+type TerminalExecResponse = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    running: boolean;
+    wallTimeSeconds: number;
+};
+type PtyOpenRequest = {
+    cols?: number;
+    rows?: number;
+    cwd?: string;
+    shell?: string;
+};
+type PtyOpenResponse = {
+    ptyId: string;
+    streamVia: "sse-events";
+    supportsInput: boolean;
+};
+type PtyWriteRequest = {
+    ptyId: string;
+    data: string;
+};
+type PtyResizeRequest = {
+    ptyId: string;
+    cols: number;
+    rows: number;
+};
+type PtyCloseRequest = {
+    ptyId: string;
+};
+type SessionStructuredCapabilities = {
+    FileSystem: {
+        available: boolean;
+        readOnly: boolean;
+        root: string;
+    };
+    Terminal: {
+        events: boolean;
+        exec: boolean;
+        pty: {
+            available: boolean;
+        };
+    };
+    Git: {
+        available: boolean;
+        repos: string[];
+    };
+};
 type ScheduledTaskStatus = "active" | "paused";
 type ScheduledTaskRunMode = "new_session_per_run" | "reusable_session";
 type ScheduledTaskOverlapPolicy = "allow_concurrent" | "skip" | "buffer_one";
@@ -167,7 +603,7 @@ type CreateSessionRequest = {
     idempotencyKey?: string | undefined;
     firstPartyMcpPermissions?: string[] | undefined;
 };
-declare const KNOWN_PERMISSIONS: readonly ["account:read", "account:admin", "members:manage", "workspace:create", "billing:read", "billing:manage", "workspace:read", "workspace:admin", "sessions:create", "sessions:read", "sessions:control", "files:upload", "files:read", "documents:manage", "documents:search", "scheduled_tasks:manage", "scheduled_tasks:run", "github:manage", "github:use", "api_keys:manage", "environments:manage", "environments:use", "goals:manage"];
+declare const KNOWN_PERMISSIONS: readonly ["account:read", "account:admin", "members:manage", "workspace:create", "billing:read", "billing:manage", "workspace:read", "workspace:admin", "sessions:create", "sessions:read", "sessions:control", "stream:view", "stream:control", "stream:acknowledge", "files:upload", "files:read", "files:write", "terminal:attach", "documents:manage", "documents:search", "scheduled_tasks:manage", "scheduled_tasks:run", "github:manage", "github:use", "api_keys:manage", "environments:manage", "environments:use", "goals:manage"];
 type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
 /**
  * Permissions the SDK knows about today, kept open so a newer OpenGeni server
@@ -175,6 +611,69 @@ type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
  */
 type Permission = KnownPermission | (string & {});
 type ProductAccessMode = "local" | "configured" | "managed";
+/**
+ * One model a client may select at send time, plus the provider that serves it.
+ * The wire API (`responses` | `chat`) lets a client reason about provider
+ * capabilities; the provider id/label drive a picker's grouping. Mirrors the
+ * `ClientModel` shape projected into `ClientConfig` by the server.
+ */
+type ClientModel = {
+    id: string;
+    label: string;
+    /** Provider id (e.g. `openai`, `azure`, or a registry provider id). */
+    provider: string;
+    providerLabel: string;
+    api: "responses" | "chat";
+    contextWindowTokens?: number | undefined;
+};
+/**
+ * How a deployment expects clients to authenticate to it, surfaced so a UI can
+ * wire up the right header/cookie without prior knowledge of the host setup.
+ * Discriminated on `mode`; `none` is the back-compat default.
+ */
+type ClientAuthConfig = {
+    mode: "none";
+} | {
+    mode: "deploymentKey";
+    headerName: "x-opengeni-access-key";
+} | {
+    mode: "configuredToken";
+    headerName: "authorization";
+    scheme: "bearer";
+} | {
+    mode: "managedSession";
+    session: "cookie";
+};
+/**
+ * Public, unauthenticated-by-default client bootstrap config returned by
+ * `GET /v1/config/client`: which models + reasoning efforts are exposed, the
+ * MCP servers and file-upload limits a composer should offer, and how the
+ * deployment expects the client to authenticate. `allowedModels` is kept for
+ * back-compat; `models` carries the richer provider-grouped list for a picker.
+ */
+type ClientConfig = {
+    deploymentRevision: string;
+    defaultModel: string;
+    allowedModels: string[];
+    models: ClientModel[];
+    defaultReasoningEffort: ReasoningEffort;
+    allowedReasoningEfforts: ReasoningEffort[];
+    mcpServers: {
+        id: string;
+        name: string;
+    }[];
+    fileUploads: {
+        enabled: boolean;
+        maxSizeBytes: number;
+    };
+    productAccessMode: ProductAccessMode;
+    auth: ClientAuthConfig;
+    structuredServices: {
+        fileSystem: boolean;
+        git: boolean;
+        terminalEvents: boolean;
+    };
+};
 type AccountRole = "owner" | "admin" | "member";
 type AccountGrant = {
     accountId: string;
@@ -251,6 +750,25 @@ type CreateApiKeyResponse = {
 type ListApiKeysResponse = {
     apiKeys: ApiKey[];
 };
+type WorkspaceMember = {
+    subjectId: string;
+    subjectLabel: string | null;
+    role: string;
+    permissions: Permission[];
+    createdAt: string;
+};
+type ListWorkspaceMembersResponse = {
+    members: WorkspaceMember[];
+};
+type AddWorkspaceMemberRequest = {
+    email: string;
+    role?: string | undefined;
+    permissions: Permission[];
+};
+type UpdateWorkspaceMemberRequest = {
+    role?: string | undefined;
+    permissions: Permission[];
+};
 type SessionGoalStatus = "active" | "paused" | "completed";
 type SessionGoalCreatedBy = "api" | "agent" | "scheduled_task";
 type SessionGoal = {
@@ -730,7 +1248,7 @@ type BillingBalance = {
     currency: "usd";
     updatedAt: string;
 };
-declare const KNOWN_USAGE_EVENT_TYPES: readonly ["agent_run.created", "agent_run.completed", "model.tokens", "model.cost", "file.uploaded", "file.deleted", "document.indexed", "scheduled_task.fired", "api_key.request"];
+declare const KNOWN_USAGE_EVENT_TYPES: readonly ["agent_run.created", "agent_run.completed", "model.tokens", "model.cost", "file.uploaded", "file.deleted", "document.indexed", "scheduled_task.fired", "api_key.request", "sandbox.warm_seconds", "sandbox.warm_cost"];
 type KnownUsageEventType = (typeof KNOWN_USAGE_EVENT_TYPES)[number];
 type UsageEventType = KnownUsageEventType | (string & {});
 type UsageEvent = {
@@ -985,12 +1503,95 @@ declare class OpenGeniClient {
      * it is a no-op (`status:"noop"`) with an explanatory message.
      */
     compactSessionContext(workspaceId: string, sessionId: string): Promise<CompactSessionContextResult>;
+    /** FileSystem: list a directory tree (feeds the Pierre file tree). */
+    fsList(workspaceId: string, sessionId: string, request?: FsListRequest): Promise<FsListResponse>;
+    /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
+    fsRead(workspaceId: string, sessionId: string, request: FsReadRequest): Promise<FsReadResponse>;
+    /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
+    fsWrite(workspaceId: string, sessionId: string, request: FsWriteRequest): Promise<FsWriteResponse>;
+    /** FileSystem: delete a path (emits fs.changed). */
+    fsDelete(workspaceId: string, sessionId: string, request: FsDeleteRequest): Promise<FsDeleteResponse>;
+    /** FileSystem: move/rename a path (emits fs.changed; 409 if destination exists and overwrite is false). */
+    fsMove(workspaceId: string, sessionId: string, request: FsMoveRequest): Promise<FsMoveResponse>;
+    /** FileSystem: create a directory (emits fs.changed; recursive defaults to true). */
+    fsMkdir(workspaceId: string, sessionId: string, request: FsMkdirRequest): Promise<FsMkdirResponse>;
+    /** Git: working-tree/index status (the Pierre file-status feed). */
+    gitStatus(workspaceId: string, sessionId: string, request?: GitStatusRequest): Promise<GitStatusResponse>;
+    /** Git: structured diff hunks (the Pierre diff feed). */
+    gitDiff(workspaceId: string, sessionId: string, request?: GitDiffRequest): Promise<GitDiffResponse>;
+    /** Git: commit log. */
+    gitLog(workspaceId: string, sessionId: string, request?: GitLogRequest): Promise<GitLogResponse>;
+    /** Git: show a commit (diff vs first parent) or fetch a raw blob at a ref. */
+    gitShow(workspaceId: string, sessionId: string, request: GitShowRequest): Promise<GitShowResponse>;
+    /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
+    terminalExec(workspaceId: string, sessionId: string, request: TerminalExecRequest): Promise<TerminalExecResponse>;
+    /** Terminal: open an interactive PTY. Output streams on the event SSE as
+     *  terminal.pty.output.delta; drive it with terminalPtyWrite. */
+    terminalPtyOpen(workspaceId: string, sessionId: string, request?: PtyOpenRequest): Promise<PtyOpenResponse>;
+    /** Terminal: send stdin to an open PTY (output rides A1). */
+    terminalPtyWrite(workspaceId: string, sessionId: string, request: PtyWriteRequest): Promise<void>;
+    /** Terminal: resize an open PTY. */
+    terminalPtyResize(workspaceId: string, sessionId: string, request: PtyResizeRequest): Promise<void>;
+    /** Terminal: close an open PTY (idempotent). */
+    terminalPtyClose(workspaceId: string, sessionId: string, request: PtyCloseRequest): Promise<void>;
+    /** Read the negotiated capability doc for a session WITHOUT acquiring a viewer
+     *  holder (no warm, no spawn). Drives capability-gated rendering: which
+     *  surfaces mount, the per-surface unavailability reasons, and the lease
+     *  liveness the client polls on while `cold`/`warming`. The desktop URL/token
+     *  are minted in-process only when the box is warm AND the principal has
+     *  acknowledged the un-redacted plane. */
+    getStreamCapabilities(workspaceId: string, sessionId: string): Promise<SessionCapabilities>;
+    /** Record the calling principal's acknowledgment of the un-redacted desktop
+     *  pixel plane (and, when the box is shared, the shared-exposure disclosure).
+     *  The desktop viewer-attach path returns 409 until this is recorded. */
+    acknowledgeStream(workspaceId: string, sessionId: string, request?: AcknowledgeStreamRequest): Promise<AcknowledgeStreamResponse>;
+    /** Attach a viewer holder (refcounted liveness — keeps the box warm while
+     *  watched/used), spinning the box up in-process when cold, and mint the scoped
+     *  direct-to-provider URLs for the requested plane(s). `request.desktop:true`
+     *  opts into the un-redacted pixel plane and mints the noVNC URL — that plane
+     *  alone throws `OpenGeniApiError(409)` when the un-redacted/shared
+     *  acknowledgment is missing (the consent gate). A terminal-only attach
+     *  (`desktop` omitted/false) warms the box + mints the pty-ws terminal cell with
+     *  NO consent gate. An omitted `viewerId` mints a fresh one. */
+    attachViewer(workspaceId: string, sessionId: string, request?: AttachViewerRequest): Promise<AttachViewerResponse>;
+    /** Heartbeat a viewer holder (Channel-A app-level liveness). A closed laptop
+     *  stops sending these → the reaper drops the holder within ~90s. Echoes
+     *  `leaseEpoch` so a superseded epoch is rejected (`alive:false` → re-attach). */
+    heartbeatViewer(workspaceId: string, sessionId: string, viewerId: string, request: ViewerHeartbeatRequest): Promise<ViewerHeartbeatResponse>;
+    /** Detach a viewer (delete this holder; idempotent delete-my-row). */
+    detachViewer(workspaceId: string, sessionId: string, viewerId: string): Promise<void>;
+    /**
+     * The deployment's public client bootstrap config: the host-exposed models
+     * (provider-grouped in `models`, flat in `allowedModels` for back-compat),
+     * reasoning efforts, MCP servers, file-upload limits, and how the client is
+     * expected to authenticate. Drives a composer's model picker without prior
+     * knowledge of the host setup; safe to call before any auth is established.
+     */
+    getClientConfig(): Promise<ClientConfig>;
     /** The caller's access context: subject, account + workspace grants, defaults. */
     getAccessContext(): Promise<AccessContext>;
     listWorkspaces(): Promise<Workspace[]>;
     createWorkspace(request: CreateWorkspaceRequest): Promise<Workspace>;
     getWorkspace(workspaceId: string): Promise<Workspace>;
     updateWorkspace(workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace>;
+    /**
+     * Delete a workspace and everything in it. Refused (409) for the account's
+     * only workspace and while it still has a running session. Irreversible.
+     */
+    deleteWorkspace(workspaceId: string): Promise<void>;
+    /** The workspace's members (user + api_key subjects). */
+    listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMember[]>;
+    /**
+     * Add an already-registered user by email. 404s when no user with that email
+     * exists (email invites for unknown users are deferred).
+     */
+    addWorkspaceMember(workspaceId: string, request: AddWorkspaceMemberRequest): Promise<WorkspaceMember>;
+    updateWorkspaceMember(workspaceId: string, subjectId: string, request: UpdateWorkspaceMemberRequest): Promise<WorkspaceMember>;
+    /**
+     * Remove a member. Refused (409) for your own membership and for the last
+     * member who can still manage the workspace.
+     */
+    removeWorkspaceMember(workspaceId: string, subjectId: string): Promise<void>;
     createScheduledTask(workspaceId: string, request: CreateScheduledTaskRequest): Promise<ScheduledTask>;
     updateScheduledTask(workspaceId: string, taskId: string, request: UpdateScheduledTaskRequest): Promise<ScheduledTask>;
     pauseScheduledTask(workspaceId: string, taskId: string): Promise<ScheduledTask>;
@@ -1038,6 +1639,11 @@ declare class OpenGeniClient {
     listDocuments(workspaceId: string, baseId: string): Promise<Document[]>;
     /** Retry indexing for a failed document. */
     reindexDocument(workspaceId: string, baseId: string, documentId: string): Promise<Document>;
+    /**
+     * Delete a document from a base. Removes the document row and its indexed
+     * chunks while leaving the uploaded file asset available for other uses.
+     */
+    deleteDocument(workspaceId: string, baseId: string, documentId: string): Promise<void>;
     searchDocuments(workspaceId: string, baseId: string, request: {
         query: string;
         limit?: number;
@@ -1193,4 +1799,124 @@ type SseMessage = {
 };
 declare function parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage, void, void>;
 
-export { type AccessContext, type AccessGrant, type AccountGrant, type AccountRole, type AgentMessageCompletedPayload, type AgentTextDeltaPayload, type AgentToolCallCreatedPayload, type AgentToolCallOutputPayload, type ApiKey, type BillingBalance, type BillingEntitlementsResponse, type BillingMode, type BillingSummary, type BillingUsageResponse, type CapabilityCatalogItem, type CapabilityCatalogResponse, type CapabilityInstallation, type CapabilityInstallationStatus, type CapabilityKind, type CapabilityPack, type CapabilityPackConnector, type CapabilityPackConnectorAuthModel, type CapabilityPackEnvironmentSpec, type CapabilityPackKnowledge, type CapabilityPackScheduledTaskTemplate, type CapabilityPackSkill, type CapabilityPackSkillFile, type CapabilityRuntime, type CapabilitySource, type ClientSessionEventInput, type CompactSessionContextResult, type CompleteFileUploadResponse, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateCapabilityCatalogItemRequest, type CreateCheckoutRequest, type CreateCheckoutResponse, type CreateDocumentBaseRequest, type CreateFileUploadRequest, type CreateFileUploadResponse, type CreateGitHubAppManifestRequest, type CreateGitHubAppManifestResponse, type CreateScheduledTaskRequest, type CreateSessionRequest, type CreateWorkspaceEnvironmentRequest, type CreateWorkspaceRequest, type DiscoverMcpCapabilitiesResponse, type Document, type DocumentBase, type DocumentSearchRequest, type DocumentSearchResponse, type DocumentSearchResult, type DocumentStatus, type EnableCapabilityRequest, type EnablePackRequest, type EntitlementValue, type Entitlements, type EntitlementsMode, type FetchLike, type FileAsset, type FileDownloadUrlResponse, type FileResourceRef, type FileStatus, type FileUploadData, type GetPackResponse, type GitHubAppInfo, type GitHubRepositoriesResponse, type GitHubRepository, type GoalSpec, KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, type KnownPermission, type KnownSessionEventType, type KnownUsageEventType, type ListApiKeysResponse, type ListPacksResponse, OpenGeniApiError, OpenGeniClient, type OpenGeniClientOptions, OpenGeniStreamError, type PackInstallation, type PackInstallationStatus, type Permission, type ProductAccessMode, type ProxySessionEventStreamOptions, type ReasoningEffort, type RegisterCapabilityPackRequest, type RepositoryResourceRef, type ResourceRef, SESSION_EVENT_TYPES, type SandboxBackend, type ScheduledTask, type ScheduledTaskAgentConfig, type ScheduledTaskAgentConfigInput, type ScheduledTaskDayOfWeek, type ScheduledTaskOverlapPolicy, type ScheduledTaskRun, type ScheduledTaskRunMode, type ScheduledTaskRunStatus, type ScheduledTaskScheduleSpec, type ScheduledTaskStatus, type ScheduledTaskTriggerType, type SendMessageInput, type Session, type SessionEvent, type SessionEventStreamTransport, type SessionEventType, type SessionGoal, type SessionGoalCreatedBy, type SessionGoalStatus, type SessionStatus, type SessionStatusChangedPayload, type SessionTurn, type SessionTurnSource, type SessionTurnStatus, type SseMessage, type SseReStreamOptions, type SteerMessageResult, type StreamConnectionState, type StreamSessionEventsOptions, type ToolRef, type UpdateScheduledTaskRequest, type UpdateSessionGoalRequest, type UpdateSessionTurnRequest, type UpdateWorkspaceEnvironmentRequest, type UpdateWorkspaceRequest, type UploadFileInput, type UsageEvent, type UsageEventType, type UserApprovalDecisionEventInput, type UserInterruptEventInput, type UserMessageEventInput, type Workspace, type WorkspaceEnvironment, type WorkspaceEnvironmentVariableMetadata, type WorkspaceRegisteredPack, formatSseEvent, isRetryableStreamError, parseSseStream, proxySessionEventStream, resumeSequenceFromRequest, sessionEventsToSseResponse, sessionEventsToSseStream, streamSessionEvents };
+/**
+ * Translate the negotiated desktop capability into the WebSocket URL the noVNC
+ * RFB client connects to. The scoped provider token is ALREADY embedded in the
+ * minted `url` (Modal tunnel host, Blaxel `bl_preview_token`, Daytona signed
+ * preview) by `session.resolveExposedPort(6080)` — we do NOT append `cap.token`
+ * as a query param (that double-auth was an adversarial-review bug: the box runs
+ * `-nopw` in v1, so the RFB password is meaningless and the real auth is the
+ * tunnel token in the host). We only normalize the scheme to `ws`/`wss` and, when
+ * the minted URL points at a `vnc.html` viewer page, rewrite it to the
+ * websockify socket path noVNC actually dials.
+ */
+declare function desktopSocketUrl(cap: Pick<DesktopStreamCapability, "url">): string;
+/**
+ * The minimal RFB surface the React component drives. Lets tests (and 3rd
+ * parties swapping noVNC for a WebRTC client in v3) provide a fake without the
+ * DOM. Matches `@novnc/novnc`'s RFB constructor + lifecycle.
+ */
+interface DesktopRfbLike {
+    viewOnly: boolean;
+    scaleViewport: boolean;
+    /**
+     * 1:1 viewport clipping. We always drive this FALSE: with clipping on, noVNC
+     * paints the framebuffer pixel-for-pixel and scrolls/crops to the container
+     * (the "zoomed in" look). FALSE lets `scaleViewport` shrink the 1280x800 frame
+     * to fit the panel (aspect-preserved). Declared so the hook can pin it instead
+     * of relying on noVNC's default — `scaleViewport=true` forces clip off
+     * internally, but a stale/partial state on reconnect could leave it on.
+     */
+    clipViewport: boolean;
+    addEventListener(type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void): void;
+    removeEventListener?: (type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void) => void;
+    disconnect(): void;
+}
+type DesktopRfbFactory = (target: HTMLElement, url: string, opts: {
+    credentials?: {
+        password?: string | undefined;
+    } | undefined;
+}) => DesktopRfbLike;
+type DesktopConnectionState = "idle" | "negotiating" | "connecting" | "connected" | "rotating" | "reconnecting" | "error" | "ended";
+type DesktopStreamEvent = {
+    type: "negotiated";
+} | {
+    type: "connected";
+} | {
+    type: "disconnected";
+} | {
+    type: "rotate";
+} | {
+    type: "fail";
+} | {
+    type: "abort";
+};
+/**
+ * Pure reducer for the desktop connection lifecycle. The component owns the RFB
+ * object + DOM; this owns the transitions so they are unit-testable. Mirrors the
+ * Channel-A stream reducer discipline.
+ */
+declare function nextDesktopState(current: DesktopConnectionState, ev: DesktopStreamEvent): DesktopConnectionState;
+type DesktopStreamCapabilityLike = {
+    url: string | null;
+    token: string | null;
+    expiresAt: string | null;
+};
+/**
+ * Apply a `stream.url.rotated` event onto a desktop capability, fencing on
+ * leaseEpoch (split-brain). A rotation minted under an epoch the client has
+ * already advanced PAST is from a superseded owner and is dropped (returns
+ * null); otherwise the fresh url/token/expiresAt are folded in.
+ */
+declare function applyUrlRotation<T extends DesktopStreamCapabilityLike>(cap: T, payload: StreamUrlRotatedPayload, knownEpoch: number): T | null;
+
+/**
+ * Translate the negotiated `pty-ws` Terminal capability into the WebSocket URL
+ * the ttyd client dials. The scoped provider token is ALREADY embedded in the
+ * minted `url` (the Modal tunnel host) by `session.resolveExposedPort(7681)` —
+ * we do NOT append `cap.token` (identical posture to the desktop: the gate is the
+ * unguessable short-TTL tunnel URL + the server-recorded scoped stream token; ttyd
+ * runs `--writable` with no `-c` credential in v1). We only normalize the scheme
+ * to `ws`/`wss`; a bare host is already the ttyd websocket endpoint.
+ */
+declare function terminalSocketUrl(cap: Pick<TerminalCapability, "url">): string;
+/** ttyd subprotocol — REQUIRED on the WebSocket handshake or ttyd refuses it. */
+declare const TTYD_SUBPROTOCOL = "tty";
+/** Client→server command bytes (the first char of each outbound text frame). */
+declare const TtydClientCommand: {
+    /** stdin: "0" + raw input bytes. */
+    readonly INPUT: "0";
+    /** window resize: "1" + JSON.stringify({ columns, rows }). */
+    readonly RESIZE: "1";
+    /** flow-control pause (back-pressure): "2". */
+    readonly PAUSE: "2";
+    /** flow-control resume: "3". */
+    readonly RESUME: "3";
+};
+/** Server→client command bytes (the first char of each inbound frame). */
+declare const TtydServerCommand: {
+    /** stdout/stderr: "0" + raw output bytes (write the rest into xterm). */
+    readonly OUTPUT: "0";
+    /** set the window title: "1" + title string. */
+    readonly SET_WINDOW_TITLE: "1";
+    /** ttyd client preferences JSON: "2" + json (ignored by us). */
+    readonly SET_PREFERENCES: "2";
+};
+/**
+ * The ttyd handshake's first frame: an auth message. ttyd expects
+ * `JSON.stringify({ AuthToken })` as the FIRST text frame on the socket. We send
+ * an empty token — our gate is the tunnel URL + scoped stream token, NOT a ttyd
+ * `-c` basic-auth credential (which the box does not set in v1). Optional ttyd
+ * `columns`/`rows` can ride this frame to seed the PTY size before the first
+ * resize. Pure (string-building only) so it stays unit-testable in the SDK.
+ */
+declare function ttydAuthFrame(opts?: {
+    columns?: number;
+    rows?: number;
+}): string;
+/** Build a client→server INPUT (stdin) frame: "0" + data. */
+declare function ttydInputFrame(data: string): string;
+/** Build a client→server RESIZE frame: "1" + JSON.stringify({ columns, rows }). */
+declare function ttydResizeFrame(columns: number, rows: number): string;
+
+export { type AccessContext, type AccessGrant, type AccountGrant, type AccountRole, type AcknowledgeStreamRequest, type AcknowledgeStreamResponse, type AddWorkspaceMemberRequest, type AgentMessageCompletedPayload, type AgentTextDeltaPayload, type AgentToolCallCreatedPayload, type AgentToolCallOutputPayload, type ApiKey, type AttachViewerRequest, type AttachViewerResponse, type BillingBalance, type BillingEntitlementsResponse, type BillingMode, type BillingSummary, type BillingUsageResponse, type CapabilityCatalogItem, type CapabilityCatalogResponse, type CapabilityInstallation, type CapabilityInstallationStatus, type CapabilityKind, type CapabilityPack, type CapabilityPackConnector, type CapabilityPackConnectorAuthModel, type CapabilityPackEnvironmentSpec, type CapabilityPackKnowledge, type CapabilityPackScheduledTaskTemplate, type CapabilityPackSkill, type CapabilityPackSkillFile, type CapabilityRuntime, type CapabilitySource, type CapabilityUnavailableReason, type ClientAuthConfig, type ClientConfig, type ClientModel, type ClientSessionEventInput, type CompactSessionContextResult, type CompleteFileUploadResponse, type ComputerUseCapability, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateCapabilityCatalogItemRequest, type CreateCheckoutRequest, type CreateCheckoutResponse, type CreateDocumentBaseRequest, type CreateFileUploadRequest, type CreateFileUploadResponse, type CreateGitHubAppManifestRequest, type CreateGitHubAppManifestResponse, type CreateScheduledTaskRequest, type CreateSessionRequest, type CreateWorkspaceEnvironmentRequest, type CreateWorkspaceRequest, type DesktopConnectionState, type DesktopRfbFactory, type DesktopRfbLike, type DesktopStreamCapability, type DesktopStreamEvent, type DiscoverMcpCapabilitiesResponse, type Document, type DocumentBase, type DocumentSearchRequest, type DocumentSearchResponse, type DocumentSearchResult, type DocumentStatus, type EnableCapabilityRequest, type EnablePackRequest, type EntitlementValue, type Entitlements, type EntitlementsMode, type FetchLike, type FileAsset, type FileDownloadUrlResponse, type FileResourceRef, type FileStatus, type FileSystemCapability, type FileUploadData, type FsChangeKind, type FsChangedPayload, type FsDeleteRequest, type FsDeleteResponse, type FsEncoding, type FsListRequest, type FsListResponse, type FsMkdirRequest, type FsMkdirResponse, type FsMoveRequest, type FsMoveResponse, type FsNodeType, type FsReadRequest, type FsReadResponse, type FsTreeNode, type FsWriteRequest, type FsWriteResponse, type GetPackResponse, type GitCapability, type GitChangedPayload, type GitCommit, type GitDiffHunk, type GitDiffLine, type GitDiffLineType, type GitDiffRequest, type GitDiffResponse, type GitFileDiff, type GitFileStatus, type GitFileStatusCode, type GitHubAppInfo, type GitHubRepositoriesResponse, type GitHubRepository, type GitLogRequest, type GitLogResponse, type GitShowRequest, type GitShowResponse, type GitStatusRequest, type GitStatusResponse, type GoalSpec, KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, type KnownPermission, type KnownSessionEventType, type KnownUsageEventType, type ListApiKeysResponse, type ListPacksResponse, type ListWorkspaceMembersResponse, OpenGeniApiError, OpenGeniClient, type OpenGeniClientOptions, OpenGeniStreamError, type PackInstallation, type PackInstallationStatus, type Permission, type ProductAccessMode, type ProxySessionEventStreamOptions, type PtyCloseRequest, type PtyOpenRequest, type PtyOpenResponse, type PtyResizeRequest, type PtyWriteRequest, type ReasoningEffort, type RecordingAvailablePayload, type RecordingCapability, type RecordingCodec, type RecordingContentType, type RecordingFailedPayload, type RecordingFailedReason, type RecordingMode, type RecordingStartedPayload, type RegisterCapabilityPackRequest, type RepositoryResourceRef, type ResourceRef, SESSION_EVENT_TYPES, type SandboxBackend, type SandboxCapabilityName, type SandboxCommandOutputDeltaPayload, type SandboxOs, type ScheduledTask, type ScheduledTaskAgentConfig, type ScheduledTaskAgentConfigInput, type ScheduledTaskDayOfWeek, type ScheduledTaskOverlapPolicy, type ScheduledTaskRun, type ScheduledTaskRunMode, type ScheduledTaskRunStatus, type ScheduledTaskScheduleSpec, type ScheduledTaskStatus, type ScheduledTaskTriggerType, type SendMessageInput, type Session, type SessionCapabilities, type SessionEvent, type SessionEventStreamTransport, type SessionEventType, type SessionGoal, type SessionGoalCreatedBy, type SessionGoalStatus, type SessionStatus, type SessionStatusChangedPayload, type SessionStructuredCapabilities, type SessionTurn, type SessionTurnSource, type SessionTurnStatus, type SseMessage, type SseReStreamOptions, type SteerMessageResult, type StreamClosedPayload, type StreamConnectionState, type StreamOpenedPayload, type StreamRevokedPayload, type StreamSessionEventsOptions, type StreamUrlRotatedPayload, TTYD_SUBPROTOCOL, type TerminalCapability, type TerminalExecRequest, type TerminalExecResponse, type TerminalPtyExitedPayload, type TerminalPtyOutputDeltaPayload, type TerminalPtyStartedPayload, type ToolRef, TtydClientCommand, TtydServerCommand, type UpdateScheduledTaskRequest, type UpdateSessionGoalRequest, type UpdateSessionTurnRequest, type UpdateWorkspaceEnvironmentRequest, type UpdateWorkspaceMemberRequest, type UpdateWorkspaceRequest, type UploadFileInput, type UsageEvent, type UsageEventType, type UserApprovalDecisionEventInput, type UserInterruptEventInput, type UserMessageEventInput, type ViewerHeartbeatRequest, type ViewerHeartbeatResponse, type ViewerHolder, type Workspace, type WorkspaceEnvironment, type WorkspaceEnvironmentVariableMetadata, type WorkspaceMember, type WorkspaceRegisteredPack, applyUrlRotation, desktopSocketUrl, formatSseEvent, isRetryableStreamError, nextDesktopState, parseSseStream, proxySessionEventStream, resumeSequenceFromRequest, sessionEventsToSseResponse, sessionEventsToSseStream, streamSessionEvents, terminalSocketUrl, ttydAuthFrame, ttydInputFrame, ttydResizeFrame };