@gitterm/sdk 0.11.0 → 0.12.0

package/README.md

@@ -676,8 +676,9 @@ duplicate and blank labels are dropped. Hosted users need the API redeployed for
 
 The quick start above shows a complete relay. Rejecting a permission or dismissing a question
 ends the turn: OpenCode records a failed tool call and the run finishes. A run left
-`awaiting_input` does not keep its workspace awake; if nobody answers before the workspace's
-idle timeout pauses it, the run is cancelled with `"Workspace paused while waiting for input"`.
+`awaiting_input` keeps its workspace awake until the run's execution deadline, when it is
+cancelled. If the workspace stops anyway (paused or deleted), the run is cancelled with
+`"Workspace paused while waiting for input"`.
 To avoid prompts entirely in headless runs, allow the relevant tools in
 `opencode.config.permission` when creating the workspace.
 
@@ -853,6 +854,39 @@ await saveConfig({
 Device-code logins produce the same revocable `gt_...` API token as the dashboard;
 they appear under **API tokens** in the dashboard and can be revoked there.
 
+## Sandboxes
+
+`@gitterm/sdk/sandbox` runs commands in a plain remote sandbox, with no coding agent
+inside, on behalf of a local agent or script. The same client works against your
+Gitterm plan (`managed`) or your own provider account (`direct`, no Gitterm login needed).
+Direct mode supports E2B, Daytona, Vercel, Boat, exe.dev, and Railway; managed mode also AWS:
+
+```ts
+import { captureSource, createSandboxBackend, createSandboxClient } from "@gitterm/sdk/sandbox";
+
+const settings = {
+  account: "e2b",
+  accounts: {
+    e2b: { mode: "direct" as const, provider: "e2b" as const, apiKeyEnv: "E2B_API_KEY" },
+  },
+};
+const sandboxes = createSandboxClient({ backend: createSandboxBackend(settings) });
+
+const sandbox = await sandboxes.create({ name: "ci", lifetimeMinutes: 30 });
+await sandboxes.sync(sandbox, await captureSource(process.cwd())); // includes uncommitted changes
+const run = await sandboxes.exec(sandbox, { command: "npm test", waitMs: 300_000 });
+console.log(run.state.status, run.state.exitCode, run.job.snapshotDigest);
+console.log(run.log.text); // last 8 KiB; page with sandboxes.job(sandbox, run.job.id, { offset })
+await sandboxes.destroy(sandbox);
+```
+
+Jobs are durable: their state lives in the sandbox, so another process can reattach with
+`sandboxes.job()` or stop the whole process group with `sandboxes.cancel()`. A non-zero
+exit is a `failed` job; a provider failure throws `SandboxProviderError`. Managed
+primitives are also available directly as `client.sandboxes.*`. See
+[Agent sandboxes](../../docs/agent-sandboxes.md) for modes, credentials, charges, and
+cleanup.
+
 ## Direct provider mode
 
 Direct mode runs an agent using your cloud-provider account without a Gitterm server. It intentionally omits managed billing, proxying, policy, durable run history, and automatic cleanup; your application owns workspace state and lifecycle.
@@ -864,7 +898,7 @@ All built-in compute providers use the same provisioning plan and workspace/run
 | E2B      | OpenCode-compatible template                                   | Yes              | Yes        |
 | Daytona  | Public Gitterm OpenCode server image by default                | Yes              | Yes        |
 | Vercel   | Vercel Sandbox project                                         | Yes              | Yes        |
-| boat     | boat API key (provider type `ascii`)                           | Yes              | Yes        |
+| Boat     | Boat API key (provider type `boat`)                            | Yes              | Yes        |
 | exe.dev  | Lifecycle token, or an existing VM with `ls,ssh,share,ssh-key` | Yes              | No         |
 | Railway  | Project/environment and public service domains                 | With a volume    | No         |
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, RunWatchOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, Integration, IntegrationKey, Connection, SavedBot, ConnectionKind, CreateConnectionInput, CreateConnectionResult, GitHubRepository, GitHubBranch, GoogleSetup, McpConnectionTestResult, UpdateMcpConnectionInput } from "./types.js";
+import type { AgentType, AgentRun, AgentRunCreateInput, AgentRunListOptions, AgentRunListResult, AgentRunMessage, AgentRunReply, AuthStatus, CloudProvider, RunRef, RunWaitOptions, RunWatchOptions, WaitOptions, Workspace, WorkspaceCreateInput, WorkspaceCreateResult, WorkspaceEnsureRunningResult, WorkspaceListOptions, WorkspaceListResult, WorkspaceRef, WorkspaceRestartResult, WorkspaceRuntimeAccess, WorkspacePauseResult, WorkspaceTerminateResult, WorkspaceCatalog, WorkspaceSetupStatus, ModelCredential, ModelProviderInfo, Integration, IntegrationKey, Connection, SavedBot, ConnectionKind, CreateConnectionInput, CreateConnectionResult, GitHubRepository, GitHubBranch, GoogleSetup, McpConnectionTestResult, UpdateMcpConnectionInput, ManagedSandbox, ManagedSandboxCreateInput, ManagedSandboxSnapshot, SandboxJobFinished } from "./types.js";
 import type { AgentRunEvent, AgentRunResult, RunResultOptions, WorkspaceModelAccess } from "./types.js";
 export type GittermClientOptions = {
     serverUrl?: string;
@@ -53,6 +53,54 @@ export type GittermClient = {
         events(run: RunRef, options?: RunWatchOptions): AsyncIterable<AgentRunEvent>;
         result(run: RunRef, options?: RunResultOptions): Promise<AgentRunResult>;
     };
+    /** Plain command sandboxes billed to this account. Higher-level jobs live in `@gitterm/sdk/sandbox`. */
+    sandboxes: {
+        create(input: ManagedSandboxCreateInput): Promise<ManagedSandbox>;
+        list(input?: {
+            includeTerminated?: boolean;
+        }): Promise<ManagedSandbox[]>;
+        get(sandboxId: string): Promise<ManagedSandbox>;
+        /** A non-zero exit is returned, not thrown. At most two minutes; use jobs for longer work. */
+        run(sandboxId: string, command: string, options?: {
+            cwd?: string;
+            timeoutMs?: number;
+            env?: Record<string, string>;
+        }): Promise<{
+            exitCode: number;
+            stdout: string;
+            stderr: string;
+        }>;
+        writeFile(sandboxId: string, path: string, data: Uint8Array): Promise<void>;
+        readFile(sandboxId: string, path: string): Promise<Uint8Array>;
+        /**
+         * `headers` holds a sandbox-scoped access value for private previews. `gittermUrl`, when
+         * set, is served by Gitterm: open to anyone if `public`, else only to you signed in.
+         */
+        preview(sandboxId: string, port: number, options?: {
+            public?: boolean;
+        }): Promise<{
+            url: string;
+            headers: Record<string, string>;
+            gittermUrl?: string;
+        }>;
+        /** Resume a sandbox paused for inactivity. Subject to the same quota checks as creation. */
+        resume(sandboxId: string): Promise<void>;
+        terminate(sandboxId: string): Promise<void>;
+        /**
+         * Save a running sandbox as a snapshot new sandboxes can start from (`snapshotId` on
+         * create). Counts against your plan's snapshot limit until deleted. On Vercel, saving
+         * stops the sandbox.
+         */
+        saveSnapshot(sandboxId: string, label: string): Promise<ManagedSandboxSnapshot>;
+        listSnapshots(): Promise<ManagedSandboxSnapshot[]>;
+        deleteSnapshot(snapshotId: string): Promise<void>;
+        /**
+         * Calls `listener` as jobs in your sandboxes finish. Only Gitterm sandboxes on gitterm.dev
+         * report jobs; elsewhere nothing arrives, so keep a slower check as well. Returns a stop
+         * function. The connection reconnects by itself.
+         */
+        onJobFinished(listener: (event: SandboxJobFinished) => void): () => void;
+    };
     catalog: {
         agentTypes(input?: {
             serverOnly?: boolean;

package/dist/direct/boat.d.ts

@@ -0,0 +1,2 @@
+import type { BoatDirectProviderConfig, DirectProviderAdapter } from "./types.js";
+export declare function createBoatDirectProvider(config: BoatDirectProviderConfig): DirectProviderAdapter;

package/dist/direct/index.d.ts

@@ -1,8 +1,8 @@
 export { createDirectGittermClient, type DirectGittermClient, type DirectGittermClientOptions, } from "./client.js";
 export { createE2BDirectProvider } from "./e2b.js";
-export { createAsciiDirectProvider } from "./ascii.js";
+export { createBoatDirectProvider } from "./boat.js";
 export { createDaytonaDirectProvider } from "./daytona.js";
 export { createExeDevDirectProvider } from "./exedev.js";
 export { createRailwayDirectProvider } from "./railway.js";
 export { createVercelDirectProvider } from "./vercel.js";
-export type { AsciiDirectProviderConfig, DirectAuthAttempt, DirectAuthAttemptStatus, DirectAuthIntegration, DirectAuthMethod, DirectAuthPrompt, DirectAuthWaitOptions, DirectApiModelCredential, DaytonaDirectProviderConfig, DirectModelCredential, DirectOAuthModelCredential, DirectProviderAdapter, DirectProviderCapabilities, DirectProviderConfig, DirectProviderWorkspaceInput, DirectRun, DirectRunCreateInput, DirectRunMessage, DirectRunWaitOptions, DirectSecretFile, DirectWorkspace, DirectWorkspaceCreateInput, DirectWorkspaceLifecycle, DirectWorkspaceRuntime, DirectWorkspaceSetup, DirectWorkspaceSetupStatus, DirectWorkspaceSetupWaitOptions, E2BDirectProviderConfig, ExeDevDirectProviderConfig, RailwayDirectProviderConfig, VercelDirectProviderConfig, } from "./types.js";
+export type { BoatDirectProviderConfig, DirectAuthAttempt, DirectAuthAttemptStatus, DirectAuthIntegration, DirectAuthMethod, DirectAuthPrompt, DirectAuthWaitOptions, DirectApiModelCredential, DaytonaDirectProviderConfig, DirectModelCredential, DirectOAuthModelCredential, DirectProviderAdapter, DirectProviderCapabilities, DirectProviderConfig, DirectProviderWorkspaceInput, DirectRun, DirectRunCreateInput, DirectRunMessage, DirectRunWaitOptions, DirectSecretFile, DirectWorkspace, DirectWorkspaceCreateInput, DirectWorkspaceLifecycle, DirectWorkspaceRuntime, DirectWorkspaceSetup, DirectWorkspaceSetupStatus, DirectWorkspaceSetupWaitOptions, E2BDirectProviderConfig, ExeDevDirectProviderConfig, RailwayDirectProviderConfig, VercelDirectProviderConfig, } from "./types.js";