@gitterm/sdk 0.11.0 → 0.12.0

package/dist/direct/types.d.ts

@@ -89,6 +89,11 @@ export type DirectAuthMethod = {
     id: string;
     label: string;
     form?: DirectAuthPrompt[];
+} | {
+    type: "external";
+    id: string;
+    label: string;
+    form?: DirectAuthPrompt[];
 } | {
     type: "command";
     id: string;
@@ -112,7 +117,7 @@ export type DirectAuthIntegration = {
         type: "credential";
         id: string;
         label: string;
-        method: "key" | "oauth";
+        method: "key" | "oauth" | "external";
     } | {
         type: "env";
         name: string;
@@ -301,8 +306,8 @@ export type VercelDirectProviderConfig = {
     vcpus?: number;
     timeoutMs?: number;
 };
-export type AsciiDirectProviderConfig = {
-    type: "ascii";
+export type BoatDirectProviderConfig = {
+    type: "boat";
     apiKey: string;
     size?: "small" | "default" | "large";
     runtimeSetupCommands?: string[];
@@ -333,7 +338,7 @@ export type RailwayDirectProviderConfig = {
     image?: string;
     runtimePort?: number;
 };
-export type DirectProviderConfig = E2BDirectProviderConfig | DaytonaDirectProviderConfig | VercelDirectProviderConfig | AsciiDirectProviderConfig | ExeDevDirectProviderConfig | RailwayDirectProviderConfig;
+export type DirectProviderConfig = E2BDirectProviderConfig | DaytonaDirectProviderConfig | VercelDirectProviderConfig | BoatDirectProviderConfig | ExeDevDirectProviderConfig | RailwayDirectProviderConfig;
 export type DirectRunCreateInput = {
     workspace: DirectWorkspace;
     prompt: string;

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export type { DeviceCodeInfo, LoginWithDeviceCodeOptions } from "./device-login.
 export { AgentRunError, GittermError, WorkspaceLifecycleError } from "./errors.js";
 export { createGittermWorkspaceClient, getWorkspaceEnvironment, type GittermWorkspaceClient, type WorkspaceClientOptions, type WorkspaceEnvironment, type WorkspacePort, type WorkspacePortVisibility, type WorkspaceSelf, } from "./workspace-client.js";
 export type { CredentialErrorCode, GittermErrorCode, WorkspaceLifecycleErrorCode, } from "./errors.js";
-export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunAttachment, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, Integration, IntegrationKey, IntegrationCategory, Connection, SavedBot, ConnectionKind, ConnectionStatus, ConnectionDetails, GitHubConnectionDetails, GoogleConnectionDetails, McpConnectionDetails, McpAuthentication, CreateMcpConnectionInput, UpdateMcpConnectionInput, McpConnectionTestResult, CreateConnectionInput, CreateConnectionResult, GitHubRepository, GitHubBranch, GoogleSetup, } from "./types.js";
+export type { AgentPermissionRequest, AgentQuestion, AgentQuestionOption, AgentQuestionRequest, AgentRun, AgentRunAttachment, AgentRunCreateInput, AgentRunInputRequest, AgentRunMessage, AgentRunMessagePart, AgentRunReply, AgentRunStatus, AgentRunEvent, AgentRunResult, AgentRunReplyPermission, AgentRunReplyQuestion, RunResultOptions, RunRef, RunWaitOptions, RunWatchOptions, AgentType, AgentKey, AuthStatus, BuiltInAgentKey, CloudProvider, ProviderKey, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceCatalog, WorkspaceEnsureRunningResult, WorkspaceHostingType, WorkspaceListOptions, WorkspaceListResult, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspaceStatus, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, ModelCredentialSource, WorkspaceModelsInput, WorkspaceModelAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceProviderSelection, Integration, IntegrationKey, IntegrationCategory, Connection, SavedBot, ConnectionKind, ConnectionStatus, ConnectionDetails, GitHubConnectionDetails, GoogleConnectionDetails, McpConnectionDetails, McpAuthentication, CreateMcpConnectionInput, UpdateMcpConnectionInput, McpConnectionTestResult, CreateConnectionInput, CreateConnectionResult, GitHubRepository, GitHubBranch, GoogleSetup, ManagedSandbox, ManagedSandboxCreateInput, ManagedSandboxSnapshot, SandboxJobFinished, } from "./types.js";

package/dist/index.js

@@ -652,6 +652,56 @@ ${log}` : ""}`);
       setupStatus: (ref) => run(async () => trpc.workspace.getSetupStatus.query({ workspaceId: workspaceIdOf(ref) })),
       waitForSetup: (ref, waitOptions) => run(() => waitForWorkspaceSetup(workspaceIdOf(ref), waitOptions))
     },
+    sandboxes: {
+      create: (input) => run(() => trpc.sandbox.create.mutate(input)),
+      list: (input) => run(() => trpc.sandbox.list.query(input)),
+      get: (sandboxId) => run(() => trpc.sandbox.get.query({ sandboxId })),
+      run: (sandboxId, command, options) => run(async () => {
+        const result = await trpc.sandbox.run.mutate({ sandboxId, command, ...options });
+        if (!result)
+          throw new GittermError("SERVER_ERROR", "Sandbox command returned no result");
+        return result;
+      }),
+      writeFile: (sandboxId, path, data) => run(async () => {
+        await trpc.sandbox.writeFile.mutate({
+          sandboxId,
+          path,
+          contentBase64: Buffer.from(data).toString("base64")
+        });
+      }),
+      readFile: (sandboxId, path) => run(async () => {
+        const result = await trpc.sandbox.readFile.mutate({ sandboxId, path });
+        return new Uint8Array(Buffer.from(result?.contentBase64 ?? "", "base64"));
+      }),
+      preview: (sandboxId, port, options) => run(async () => {
+        const result = await trpc.sandbox.preview.mutate({
+          sandboxId,
+          port,
+          public: options?.public
+        });
+        if (!result)
+          throw new GittermError("SERVER_ERROR", "Sandbox preview returned no result");
+        return result;
+      }),
+      resume: (sandboxId) => run(async () => {
+        await trpc.workspace.restartWorkspace.mutate({ workspaceId: sandboxId });
+      }),
+      terminate: (sandboxId) => run(async () => {
+        await trpc.sandbox.terminate.mutate({ sandboxId });
+      }),
+      saveSnapshot: (sandboxId, label) => run(() => trpc.sandbox.saveSnapshot.mutate({ sandboxId, label: label.slice(0, 120) })),
+      listSnapshots: () => run(() => trpc.sandbox.snapshots.query()),
+      deleteSnapshot: (snapshotId) => run(async () => {
+        await trpc.sandbox.deleteSnapshot.mutate({ snapshotId });
+      }),
+      onJobFinished: (listener) => {
+        const subscription = trpc.sandbox.jobEvents.subscribe(undefined, {
+          onData: (event) => listener(event),
+          onError: () => {}
+        });
+        return () => subscription.unsubscribe();
+      }
+    },
     runs: {
       create: (input) => run(async () => {
         const { signal, workspace, ...rest } = input;

package/dist/sandbox/artifacts.d.ts

@@ -0,0 +1,33 @@
+import type { SandboxBackend } from "./backend.js";
+import { type SourceSnapshot } from "./source.js";
+export declare const MAX_ARTIFACT_BYTES: number;
+export type FetchedArtifact = {
+    remotePath: string;
+    /** Outside the checkout. Local project files are untouched until `applyArtifact`. */
+    localPath: string;
+    sha256: string;
+    bytes: number;
+    /** The downloaded bytes match the sha256 computed inside the sandbox. */
+    verified: true;
+};
+export declare function artifactDirectory(): string;
+/** Relative paths resolve from the sandbox project directory. */
+export declare function remotePath(home: string, file: string): string;
+export declare function fetchArtifact(backend: SandboxBackend, sandboxId: string, file: string, options?: {
+    maxBytes?: number;
+}): Promise<FetchedArtifact>;
+export declare class ArtifactConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Copies a fetched artifact into the checkout. Refuses when the local target changed
+ * since the snapshot the job ran on, so remote output never overwrites newer local work.
+ */
+export declare function applyArtifact(input: {
+    artifact: Pick<FetchedArtifact, "localPath" | "sha256">;
+    snapshot: Pick<SourceSnapshot, "root" | "files" | "id">;
+    target: string;
+}): Promise<{
+    path: string;
+    sha256: string;
+}>;

package/dist/sandbox/backend.d.ts

@@ -0,0 +1,98 @@
+import type { GittermClient } from "../client.js";
+import { GittermError } from "../errors.js";
+import type { SandboxCapabilities, SandboxCommandResult, SandboxPreviewAccess, SandboxProviderKey } from "./types.js";
+/** `managed`: billed to a Gitterm account. `direct`: your own provider account and credentials. */
+export type SandboxMode = "managed" | "direct";
+export type SandboxProvider = SandboxProviderKey;
+/** Who owns and pays for a sandbox. Part of every reference; never inferred. */
+export type SandboxIdentity = {
+    mode: SandboxMode;
+    provider: SandboxProvider;
+    account: string;
+};
+export type SandboxRef = SandboxIdentity & {
+    id: string;
+};
+/** `deleting`: terminated in Gitterm, provider deletion not yet confirmed (managed only). */
+export type SandboxState = "pending" | "running" | "paused" | "deleting" | "terminated";
+export type SandboxInfo = SandboxRef & {
+    state: SandboxState;
+    name: string | null;
+    createdAt: string | null;
+    /** When the sandbox is deleted regardless of activity, if anything enforces that. */
+    expiresAt: string | null;
+    labels: Record<string, string>;
+};
+export type SandboxCreateRequest = {
+    name: string;
+    lifetimeMs: number;
+    labels: Record<string, string>;
+    publicPreviews: boolean;
+    /** Start from this snapshot instead of the account's image. */
+    snapshot?: string;
+};
+/** Provider snapshots of a sandbox's disk. Stored in, and billed to, the provider account. */
+export type SandboxSnapshotSupport = {
+    /** What saving does to the sandbox: `pauses` it briefly, or `stops` it for good (Vercel). */
+    effect: "pauses" | "stops";
+    /** Returns the id new sandboxes start from. */
+    create(id: string, name: string): Promise<string>;
+    delete(snapshotId: string): Promise<void>;
+};
+/** The primitives a provider account offers. Jobs, sync, and artifacts are built on these. */
+export interface SandboxBackend {
+    readonly identity: SandboxIdentity;
+    /** Home directory of the command user in the sandbox. */
+    readonly home: string;
+    readonly capabilities: SandboxCapabilities;
+    create(input: SandboxCreateRequest): Promise<SandboxInfo>;
+    /** Returns `terminated` for a sandbox that no longer exists in this account. */
+    get(id: string): Promise<SandboxInfo>;
+    list(): Promise<SandboxInfo[]>;
+    destroy(id: string): Promise<void>;
+    /** Managed sandboxes pause when idle; direct sandboxes are deleted at their deadline instead. */
+    resume?(id: string): Promise<void>;
+    run(id: string, command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+    }): Promise<SandboxCommandResult>;
+    writeFile(id: string, path: string, data: Uint8Array): Promise<void>;
+    readFile(id: string, path: string): Promise<Uint8Array>;
+    /**
+     * `gittermUrl` is set when Gitterm serves the preview: open to anyone if `public`, else
+     * only to the owner signed in to Gitterm. `url` and `headers` reach the provider directly.
+     */
+    preview(id: string, port: number, options?: {
+        public?: boolean;
+    }): Promise<SandboxPreviewAccess & {
+        gittermUrl?: string;
+    }>;
+    /**
+     * Pushes job completions as they happen, where the backend can (Gitterm sandboxes on
+     * gitterm.dev). Without it, callers learn a job finished by reading it. Returns a stop function.
+     */
+    onJobFinished?(listener: (event: {
+        sandboxId: string;
+        jobId: string;
+    }) => void): () => void;
+    /** Present on direct accounts whose provider can snapshot a sandbox. */
+    snapshots?: SandboxSnapshotSupport;
+}
+/** What a managed account offers: Gitterm serves previews of some providers itself. */
+export declare function managedCapabilities(provider: SandboxProvider): SandboxCapabilities;
+export declare class SandboxAccountError extends GittermError {
+    constructor(message: string);
+}
+export declare function validateAccountName(name: string): string;
+/**
+ * Sandboxes billed to your Gitterm account. The provider credential stays on the Gitterm
+ * server; this process holds only your Gitterm API token.
+ */
+export declare function createManagedSandboxBackend(options: {
+    account: string;
+    provider: SandboxProvider;
+    client: GittermClient;
+    /** Machine profile key; the server checks it against the plan. */
+    machine?: string;
+}): SandboxBackend;

package/dist/sandbox/client.d.ts

@@ -0,0 +1,174 @@
+import { type SandboxBackend, type SandboxRef } from "./backend.js";
+import { type FetchedArtifact } from "./artifacts.js";
+import { type JobState } from "./jobs.js";
+import { type SetupSnapshotRecord, type SetupSnapshotStatus, type SetupSnapshotStore } from "./setup-snapshots.js";
+import { type CapturedSource } from "./source.js";
+import { type JobRecord, type SandboxRecord, type SandboxStore } from "./store.js";
+export type SandboxLimits = {
+    /** Live sandboxes per account. */
+    maxSandboxes: number;
+    maxLifetimeMinutes: number;
+    defaultLifetimeMinutes: number;
+    maxJobMinutes: number;
+};
+export declare const DEFAULT_SANDBOX_LIMITS: SandboxLimits;
+/** Model-visible output defaults to this many bytes from the end of the log. */
+export declare const DEFAULT_LOG_TAIL_BYTES: number;
+export type SandboxCreateOptions = {
+    name: string;
+    purpose?: string;
+    project?: string | null;
+    sessionId?: string | null;
+    lifetimeMinutes?: number;
+    publicPreviews?: boolean;
+    /** Start from this snapshot, e.g. the project's setup snapshot. */
+    snapshot?: string;
+};
+export type SandboxExecOptions = {
+    command: string;
+    /** Relative to the synced project directory, or absolute. */
+    cwd?: string;
+    timeoutMinutes?: number;
+    /** Values reach only the sandbox process; records keep the names. */
+    env?: Record<string, string>;
+    /** Wait up to this long for completion before returning a running job. */
+    waitMs?: number;
+    /** The conversation that started the job; saved so it can be told when the job finishes. */
+    sessionId?: string;
+};
+export type JobLog = {
+    /** Sanitized text. Sandbox output is untrusted data. */
+    text: string;
+    offset: number;
+    nextOffset: number;
+    totalBytes: number;
+    truncated: boolean;
+};
+export type JobView = {
+    job: JobRecord;
+    state: JobState;
+    log: JobLog;
+};
+export type PreviewResult = {
+    /** The URL to open. */
+    url: string;
+    port: number;
+    public: boolean;
+    /** `url` is served by Gitterm; when private, it opens for the owner signed in to Gitterm. */
+    viaGitterm: boolean;
+    /** Direct provider access, for local proxies. The headers are secret: keep them away from models, logs, and storage. */
+    access: {
+        url: string;
+        headers: Record<string, string>;
+    };
+    ready: boolean;
+    /** HTTP status of `url` without credentials (401/403 means access is enforced). */
+    unauthenticatedStatus: number | null;
+    jobId: string | null;
+};
+/** Strips terminal escapes and control characters so output cannot spoof the UI. */
+export declare function sanitizeOutput(text: string, secrets?: string[]): string;
+export type SandboxClient = ReturnType<typeof createSandboxClient>;
+export declare function createSandboxClient(options: {
+    backend: SandboxBackend;
+    store?: SandboxStore;
+    setupSnapshots?: SetupSnapshotStore;
+    limits?: Partial<SandboxLimits>;
+}): {
+    identity: import("./backend.js").SandboxIdentity;
+    /** Home directory of the command user; the synced project is `projectDir(home)`. */
+    home: string;
+    capabilities: import("./types.js").SandboxCapabilities;
+    limits: {
+        maxSandboxes: number;
+        maxLifetimeMinutes: number;
+        defaultLifetimeMinutes: number;
+        maxJobMinutes: number;
+    };
+    store: SandboxStore;
+    /** Present when the backend pushes job completions; see `SandboxBackend.onJobFinished`. */
+    onJobFinished: ((listener: (event: {
+        sandboxId: string;
+        jobId: string;
+    }) => void) => () => void) | undefined;
+    create(input: SandboxCreateOptions): Promise<SandboxRecord>;
+    /** Local records reconciled with the provider, plus sandboxes this account created elsewhere. */
+    list(): Promise<SandboxRecord[]>;
+    get: (ref: SandboxRef) => Promise<SandboxRecord>;
+    sync(ref: SandboxRef, captured: CapturedSource): Promise<{
+        snapshot: import("./source.js").SourceSnapshot;
+        verified: true;
+    }>;
+    exec: (ref: SandboxRef, input: SandboxExecOptions) => Promise<JobView>;
+    wait(ref: SandboxRef, jobId: string, waitMs: number, read?: {
+        tailBytes?: number;
+    }): Promise<JobView>;
+    job(ref: SandboxRef, jobId: string, read?: {
+        offset?: number;
+        limit?: number;
+        tailBytes?: number;
+    }): Promise<JobView>;
+    cancel(ref: SandboxRef, jobId: string): Promise<JobView>;
+    /** Optionally starts `command` as a job, then waits until the port answers. */
+    preview(ref: SandboxRef, input: {
+        port: number;
+        command?: string;
+        cwd?: string;
+        readyTimeoutMs?: number;
+    }): Promise<PreviewResult>;
+    /**
+     * Downloads a file a job produced. The artifact is recorded with that job, so applying it
+     * later checks the checkout against the snapshot the job ran on, not a newer sync.
+     */
+    fetchArtifact(ref: SandboxRef, file: string, producedBy: {
+        jobId: string;
+    }): Promise<FetchedArtifact & {
+        jobId: string;
+    }>;
+    /** Writes a fetched artifact into its job's checkout, refusing stale or escaping targets. */
+    applyArtifact(ref: SandboxRef, input: {
+        localPath: string;
+        target: string;
+        /** Called with the resolved destination before anything is written, e.g. to ask approval. */
+        beforeWrite?: (plan: {
+            root: string;
+            target: string;
+            sha256: string;
+            jobId: string;
+            snapshotId: string;
+        }) => Promise<void>;
+    }): Promise<{
+        root: string;
+        snapshotId: string;
+        jobId: string;
+        path: string;
+        sha256: string;
+    }>;
+    resume(ref: SandboxRef): Promise<SandboxRecord>;
+    /** How saving a snapshot affects the sandbox, or null where this account cannot snapshot. */
+    snapshotEffect: "pauses" | "stops" | null;
+    /**
+     * This account's setup snapshots, newest first. With `project`, only those tied to that
+     * checkout or to none, each with the dependency files changed since it was saved.
+     */
+    setupSnapshots(project?: string): Promise<SetupSnapshotStatus[]>;
+    /**
+     * Snapshots the sandbox. `project` ties it to a checkout, whose dependency files are then
+     * watched for changes; `replace` names a snapshot to delete once this one is saved. Where
+     * the provider stops the sandbox to snapshot it (Vercel), the sandbox is gone after.
+     */
+    saveSetupSnapshot(ref: SandboxRef, input: {
+        label: string;
+        project?: string | null;
+        note?: string;
+        replace?: string;
+    }): Promise<{
+        record: SetupSnapshotRecord;
+        replaced: string | null;
+        leftover: string | null;
+    }>;
+    /** Deletes a setup snapshot from the provider and forgets it. */
+    deleteSetupSnapshot(snapshotId: string): Promise<SetupSnapshotRecord>;
+    /** Deletes the sandbox and confirms with the provider that it is gone. */
+    destroy(ref: SandboxRef): Promise<SandboxRecord>;
+};

package/dist/sandbox/config.d.ts

@@ -0,0 +1,128 @@
+import { type SandboxBackend, type SandboxMode } from "./backend.js";
+import type { SandboxLimits } from "./client.js";
+import { type SandboxCapabilities, type SandboxProviderKey } from "./types.js";
+type DirectCredential = {
+    /** The resolved credential (plugin options, after `{env:...}`/`{file:...}` substitution). */
+    apiKey?: string;
+    /** Name of an environment variable holding the credential (CLI settings file). */
+    apiKeyEnv?: string;
+    /**
+     * Required for providers that never delete an abandoned sandbox themselves
+     * (exe.dev, Railway): a crashed caller leaves it running until you destroy it.
+     */
+    allowUnboundedLifetime?: boolean;
+};
+/**
+ * Account settings. In OpenCode they live in the plugin options, where
+ * `"apiKey": "{env:E2B_API_KEY}"` is substituted by OpenCode before the plugin sees it.
+ * The CLI reads the same shape from a file but takes credentials only from `apiKeyEnv`.
+ */
+export type SandboxAccountConfig = ({
+    mode: "direct";
+    provider: "e2b";
+    /**
+     * Template ID or name. E2B fixes CPU and memory when a template is built, so this is
+     * also the machine size. Defaults to `base` (2 vCPU, 512 MB, no agent).
+     */
+    template?: string;
+    /** A snapshot every sandbox starts from; it keeps the size it was saved at. */
+    snapshot?: string;
+} & DirectCredential) | ({
+    mode: "direct";
+    provider: "daytona";
+    target?: "us" | "eu";
+    /** Daytona snapshot name. A snapshot carries its own size, so it excludes `resources`. */
+    snapshot?: string;
+    /** vCPUs and GiB of memory and disk. Defaults to Daytona's 1 vCPU, 1 GiB, 3 GiB. */
+    resources?: {
+        cpu?: number;
+        memory?: number;
+        disk?: number;
+    };
+} & DirectCredential) | ({
+    mode: "direct";
+    provider: "vercel";
+    teamId: string;
+    projectId: string;
+    runtime?: "node24" | "node22" | "python3.13";
+    /** 1 to 8; Vercel gives 2 GB of memory per vCPU. Defaults to 2. */
+    vcpus?: number;
+    /** A snapshot id every sandbox starts from instead of `runtime`. */
+    snapshot?: string;
+} & DirectCredential) | ({
+    mode: "direct";
+    provider: "boat";
+    size?: "small" | "default" | "large";
+    /** A named snapshot every box starts from. */
+    snapshot?: string;
+} & DirectCredential) | ({
+    mode: "direct";
+    provider: "exedev";
+    /** Container image; defaults to a plain Node image. */ image?: string;
+    /** VM size, as exe.dev's `new` flags take it, e.g. `4`, `"8GB"`, `"20GB"`. */
+    cpu?: number;
+    memory?: string;
+    disk?: string;
+} & DirectCredential) | ({
+    mode: "direct";
+    provider: "railway";
+    projectId: string;
+    environmentId: string;
+    apiUrl?: string;
+    image?: string;
+} & DirectCredential) | {
+    mode: "managed";
+    /** Defaults to e2b, or to Gitterm when `size` is set. The deployment must enable it. */
+    provider?: SandboxProviderKey;
+    /**
+     * On gitterm.dev: `small` or `medium`. Same as `provider: "gitterm"` with that machine.
+     */
+    size?: "small" | "medium";
+    /** Machine profile key, e.g. `small` or `large`. Defaults to your plan's default size. */
+    machine?: string;
+    /** Defaults to the CLI login's server. */
+    serverUrl?: string;
+    /** Defaults to the CLI login or GITTERM_API_TOKEN. */
+    token?: string;
+};
+export type SandboxSettings = {
+    /** Selected account name. */
+    account?: string;
+    accounts?: Record<string, SandboxAccountConfig>;
+    limits?: Partial<SandboxLimits>;
+    /** Extra glob patterns never uploaded. Secret-like files are always excluded. */
+    exclude?: string[];
+    /**
+     * Create every sandbox with public previews: anyone with a preview URL can open it.
+     * Setting this is the approval, so nobody is asked per sandbox.
+     */
+    publicPreviews?: boolean;
+    /**
+     * Let the agent save a setup snapshot of a sandbox once a checkout's dependencies are
+     * installed, and start that checkout's next sandboxes from it. Direct E2B, Daytona, Vercel,
+     * and Boat accounts only. Snapshots are stored in your provider account until deleted.
+     * Off by default. An account's own `snapshot` setting always wins.
+     */
+    snapshots?: boolean;
+};
+export type SandboxAccountSummary = {
+    name: string;
+    mode: SandboxMode;
+    provider: SandboxProviderKey;
+    /** Where the credential comes from. Never the credential itself. */
+    credentialSource: string;
+    credentialPresent: boolean;
+    chargedTo: string;
+    /** The machine size and who sets it: the user, in the account settings, never the agent. */
+    machine: string;
+    /** A snapshot the user set for every sandbox of this account. */
+    pinnedSnapshot: string | null;
+    capabilities: SandboxCapabilities;
+    /** Plain-language limits of this provider for sandboxes. */
+    limitations: string[];
+};
+export declare function describeLimitations(provider: SandboxProviderKey, mode: SandboxMode): string[];
+export declare function describeSandboxAccount(settings: SandboxSettings, accountName?: string): SandboxAccountSummary;
+/** Builds exactly the selected account's backend. A missing or rejected credential is an error, never a fallback. */
+export declare function createSandboxBackend(settings: SandboxSettings, accountName?: string): SandboxBackend;
+export {};

package/dist/sandbox/index.d.ts

@@ -0,0 +1,10 @@
+export { createManagedSandboxBackend, SandboxAccountError, type SandboxBackend, type SandboxIdentity, type SandboxInfo, type SandboxMode, type SandboxProvider, type SandboxRef, type SandboxState, } from "./backend.js";
+export { isSandboxProviderError, type SandboxCapabilities, type SandboxCommandResult, type SandboxFailureCode, type SandboxPreviewAccess, type SandboxProviderFailure, type SandboxProviderKey, } from "./types.js";
+export { createSandboxClient, DEFAULT_LOG_TAIL_BYTES, DEFAULT_SANDBOX_LIMITS, sanitizeOutput, type JobLog, type JobView, type PreviewResult, type SandboxClient, type SandboxCreateOptions, type SandboxExecOptions, type SandboxLimits, } from "./client.js";
+export { createSandboxBackend, describeSandboxAccount, type SandboxAccountConfig, type SandboxAccountSummary, type SandboxSettings, } from "./config.js";
+export { jobRoot, type JobState, type JobStatus } from "./jobs.js";
+export { createFileSetupSnapshotStore, type SetupSnapshotRecord, type SetupSnapshotStatus, type SetupSnapshotStore, } from "./setup-snapshots.js";
+export { captureSource, MAX_SOURCE_BYTES, projectDir, sensitivePath, type CapturedSource, type SnapshotFile, type SourceSnapshot, } from "./source.js";
+export { applyArtifact, ArtifactConflictError, artifactDirectory, type FetchedArtifact, } from "./artifacts.js";
+export { createFileSandboxStore, defaultStoreDirectory, type JobRecord, type SandboxRecord, type SandboxStore, } from "./store.js";
+export { startPreviewProxy, type PreviewProxy } from "./proxy.js";