@gitterm/sdk 0.11.0 → 0.12.1

package/dist/sandbox/jobs.d.ts

@@ -0,0 +1,41 @@
+import type { SandboxBackend } from "./backend.js";
+/**
+ * Durable jobs. State lives in the sandbox (`~/.gitterm/jobs/<id>`), so any process holding
+ * the sandbox reference can reattach: a plugin restart loses nothing.
+ *
+ * The command runs in its own session/process group. Cancellation and the timeout
+ * signal that whole group, and status reports whether the group is actually alive.
+ */
+export declare const jobRoot: (home: string) => string;
+export type JobStatus = "running" | "succeeded" | "failed" | "timed_out" | "cancelled" | "lost";
+export type JobState = {
+    id: string;
+    status: JobStatus;
+    /** The command's exit code. A non-zero code is a command failure, not a provider failure. */
+    exitCode: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    /** Whether any process of the job's group is still running in the sandbox. */
+    processAlive: boolean;
+    logBytes: number;
+};
+export type JobStartInput = {
+    command: string;
+    /** Absolute directory in the sandbox. */
+    cwd: string;
+    timeoutMs: number;
+    env?: Record<string, string>;
+};
+export declare function newJobId(): string;
+/**
+ * Secret values are redacted line by line inside the sandbox, so a value spanning lines
+ * (a PEM key, say) or one too short to match safely cannot be protected: refuse it before
+ * anything is sent.
+ */
+export declare function assertRedactableSecrets(env?: Record<string, string>): void;
+export declare function startJob(backend: SandboxBackend, sandboxId: string, id: string, input: JobStartInput): Promise<void>;
+export declare function readJobState(backend: SandboxBackend, sandboxId: string, id: string): Promise<JobState | null>;
+/** Reads `limit` bytes of combined stdout/stderr starting at `offset`. */
+export declare function readJobLog(backend: SandboxBackend, sandboxId: string, id: string, offset: number, limit: number): Promise<Buffer>;
+/** Signals the job's process group: TERM, then KILL after `graceSeconds`. */
+export declare function cancelJob(backend: SandboxBackend, sandboxId: string, id: string, graceSeconds?: number): Promise<void>;

package/dist/sandbox/proxy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A loopback-only proxy for a private preview. Local tools (for example browser
+ * automation the user approved) open `url`; the proxy adds the sandbox access headers, so
+ * they are never shown to a model or pasted into a browser.
+ *
+ * Each preview is served from its own hostname, `p-<random>.localhost`, which browsers and
+ * Node resolve to loopback. Cookies are scoped by host (not port), so a separate hostname
+ * keeps the preview's cookies, and its JavaScript, apart from every other local app and
+ * other previews, while the app's own cookie names keep working. Paths start at `/`, so
+ * root-relative assets and client-side routes work. The capability token in `url` is
+ * exchanged for an HttpOnly cookie on first use; requests without it, or for any other
+ * Host, are refused. The proxy lives only as long as this process. No WebSockets.
+ */
+export type PreviewProxy = {
+    url: string;
+    close(): Promise<void>;
+};
+export declare function startPreviewProxy(access: {
+    url: string;
+    headers: Record<string, string>;
+}): Promise<PreviewProxy>;

package/dist/sandbox/setup-snapshots.d.ts

@@ -0,0 +1,38 @@
+import type { SandboxIdentity } from "./backend.js";
+/**
+ * A setup snapshot is a provider snapshot of a sandbox taken after setup work (dependencies,
+ * toolchains, services), so new sandboxes start ready instead of redoing it. An account can
+ * keep several; each may be tied to the checkout it was made for. Records live locally next
+ * to the sandbox records and never hold credentials.
+ */
+export type SetupSnapshotRecord = SandboxIdentity & {
+    /** The provider's snapshot id; new sandboxes start from it. */
+    snapshotId: string;
+    /** A short label, e.g. "deps" or "deps + postgres". */
+    label: string;
+    /** The checkout it was made for, or null when it serves any project. */
+    project: string | null;
+    /** What the sandbox has set up, in the agent's own words. */
+    note: string;
+    /** Hashes of the checkout's dependency files when saved; a change means it is out of date. */
+    fingerprint: Record<string, string>;
+    sandboxId: string;
+    createdAt: string;
+};
+export type SetupSnapshotStatus = {
+    record: SetupSnapshotRecord;
+    /** Dependency files added, changed, or removed since; empty for untied snapshots. */
+    changed: string[];
+};
+/** Hashes of the setup files present at the checkout root. */
+export declare function setupFingerprint(project: string): Promise<Record<string, string>>;
+export declare function changedSetupFiles(saved: Record<string, string>, current: Record<string, string>): string[];
+/** A provider-safe snapshot name that says what it is and, if tied, which checkout. */
+export declare function setupSnapshotName(label: string, project: string | null): string;
+export interface SetupSnapshotStore {
+    /** This account's snapshots, newest first. */
+    list(identity: SandboxIdentity): Promise<SetupSnapshotRecord[]>;
+    put(record: SetupSnapshotRecord): Promise<void>;
+    remove(identity: SandboxIdentity, snapshotId: string): Promise<void>;
+}
+export declare function createFileSetupSnapshotStore(directory?: string): SetupSnapshotStore;

package/dist/sandbox/source.d.ts

@@ -0,0 +1,57 @@
+import type { SandboxBackend } from "./backend.js";
+/**
+ * Source snapshots for sandbox builds: the working tree exactly as it is on disk
+ * (committed, staged, unstaged, and non-ignored untracked files; deleted files absent),
+ * without Git history or the conversation. Secret-looking files are excluded.
+ */
+/** The synced checkout and Gitterm bookkeeping live below the sandbox user's home. */
+export declare const projectDir: (home: string) => string;
+export declare const MAX_SOURCE_BYTES: number;
+export type SnapshotFile = {
+    path: string;
+    kind: "file" | "executable" | "symlink";
+    size: number;
+    /** sha256 of the content, or of the link target for symlinks. */
+    sha256: string;
+};
+export type SourceSnapshot = {
+    id: string;
+    /** sha256 over the sorted manifest. Identifies exactly what runs remotely. */
+    digest: string;
+    root: string;
+    head: string | null;
+    files: SnapshotFile[];
+    /** Tracked files deleted in the working tree; they are absent from the snapshot. */
+    deleted: string[];
+    /** Tracked files with uncommitted changes. */
+    modified: string[];
+    /** Non-ignored untracked files included in the snapshot. */
+    untracked: string[];
+    excluded: Array<{
+        path: string;
+        reason: string;
+    }>;
+    bytes: number;
+};
+export type CapturedSource = {
+    snapshot: SourceSnapshot;
+    archive: Buffer;
+};
+export declare function safeRelativePath(file: string): boolean;
+export declare function sensitivePath(file: string): boolean;
+/** `*` stays within a path segment, `**` crosses segments. A pattern without `/` matches any basename. */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function captureSource(directory: string, options?: {
+    exclude?: string[];
+    maxBytes?: number;
+}): Promise<CapturedSource>;
+/**
+ * Makes the sandbox project directory match the snapshot: files from the previous
+ * snapshot that are absent now are deleted, every snapshot file is written, and each
+ * regular file is checked against its sha256 before success is reported. Ignored build
+ * output (e.g. node_modules) that was never part of a snapshot is left in place.
+ */
+export declare function uploadSource(backend: SandboxBackend, sandboxId: string, captured: CapturedSource): Promise<{
+    verified: true;
+    digest: string;
+}>;

package/dist/sandbox/store.d.ts

@@ -0,0 +1,78 @@
+import type { SandboxRef, SandboxState } from "./backend.js";
+import type { JobStatus } from "./jobs.js";
+import type { SourceSnapshot } from "./source.js";
+/**
+ * Local, non-secret bookkeeping shared by the CLI and the OpenCode plugin. It never
+ * holds credentials, preview access headers, file contents, or command output.
+ */
+export type JobRecord = {
+    id: string;
+    command: string;
+    cwd: string;
+    snapshotId: string | null;
+    snapshotDigest: string | null;
+    /** Checkout the snapshot was captured from; together with `snapshotId` it names the manifest. */
+    snapshotRoot?: string | null;
+    status: JobStatus;
+    exitCode: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    timeoutMs: number;
+    /** Names (never values) of variables passed to the job. */
+    secretNames: string[];
+    /** The conversation that started the job, told when it finishes. */
+    sessionId?: string | null;
+};
+/** A downloaded file and the job (and therefore snapshot) that produced it. */
+export type ArtifactRecord = {
+    localPath: string;
+    remotePath: string;
+    sha256: string;
+    bytes: number;
+    jobId: string;
+    fetchedAt: string;
+};
+export type SandboxRecord = SandboxRef & {
+    name: string;
+    purpose: string;
+    /** Local checkout the sandbox serves, when known. */
+    project: string | null;
+    sessionId: string | null;
+    state: SandboxState;
+    publicPreviews: boolean;
+    createdAt: string;
+    expiresAt: string | null;
+    snapshot: {
+        id: string;
+        digest: string;
+        root?: string;
+        syncedAt: string;
+    } | null;
+    jobs: Record<string, JobRecord>;
+    artifacts?: Record<string, ArtifactRecord>;
+    previews: Record<string, {
+        port: number;
+        jobId: string | null;
+        url: string;
+        public: boolean;
+    }>;
+    updatedAt: string;
+};
+export interface SandboxStore {
+    list(): Promise<SandboxRecord[]>;
+    get(ref: SandboxRef): Promise<SandboxRecord | null>;
+    put(record: SandboxRecord): Promise<void>;
+    /**
+     * Read-modify-write under a lock shared by every process using this directory, so the
+     * CLI and the plugin never drop each other's jobs. `create` supplies a record when none
+     * is stored; without one, nothing is written and null is returned.
+     */
+    update(ref: SandboxRef, mutate: (record: SandboxRecord) => void, create?: () => SandboxRecord | null): Promise<SandboxRecord | null>;
+    remove(ref: SandboxRef): Promise<void>;
+    /** Manifests (paths and hashes, no contents) for stale checks when applying artifacts. */
+    putSnapshot(snapshot: SourceSnapshot): Promise<void>;
+    /** Snapshot ids describe content only; the checkout root selects the right manifest. */
+    getSnapshot(id: string, root: string): Promise<SourceSnapshot | null>;
+}
+export declare function defaultStoreDirectory(): string;
+export declare function createFileSandboxStore(directory?: string): SandboxStore;

package/dist/sandbox/store.js

@@ -0,0 +1,100 @@
+// src/sandbox/store.ts
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+function defaultStoreDirectory() {
+  const base = process.env.XDG_STATE_HOME || path.join(homedir(), ".local", "state");
+  return path.join(base, "gitterm", "sandboxes");
+}
+var fileName = (ref) => `${ref.mode}-${ref.provider}-${ref.account}-${ref.id}`.replace(/[^A-Za-z0-9_.-]/g, "_") + ".json";
+var snapshotFile = (id, root) => `${id.replace(/[^A-Za-z0-9_]/g, "")}-${createHash("sha256").update(root).digest("hex").slice(0, 16)}.json`;
+var LOCK_STALE_MS = 30000;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function withFileLock(target, action) {
+  const lock = `${target}.lock`;
+  const deadline = Date.now() + 2 * LOCK_STALE_MS;
+  while (true) {
+    try {
+      await writeFile(lock, String(process.pid), { flag: "wx", mode: 384 });
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+      const age = await stat(lock).then((info) => Date.now() - info.mtimeMs, () => 0);
+      if (age > LOCK_STALE_MS)
+        await rm(lock, { force: true });
+      else if (Date.now() > deadline)
+        throw new Error(`Timed out waiting for ${lock}`);
+      else
+        await sleep(5 + Math.random() * 20);
+    }
+  }
+  try {
+    return await action();
+  } finally {
+    await rm(lock, { force: true });
+  }
+}
+function createFileSandboxStore(directory = defaultStoreDirectory()) {
+  const read = async (file) => JSON.parse(await readFile(path.join(directory, file), "utf8"));
+  const write = async (target, record) => {
+    const temporary = `${target}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+      await writeFile(temporary, JSON.stringify(record, null, 2), { mode: 384 });
+      await rename(temporary, target);
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  };
+  const queues = new Map;
+  const serialized = (target, action) => {
+    const next = (queues.get(target) ?? Promise.resolve()).catch(() => {}).then(() => withFileLock(target, action));
+    queues.set(target, next);
+    next.then(() => queues.get(target) === next && queues.delete(target), () => queues.get(target) === next && queues.delete(target));
+    return next;
+  };
+  return {
+    async list() {
+      const files = await readdir(directory).catch(() => []);
+      const records = await Promise.all(files.filter((file) => file.endsWith(".json")).map((file) => read(file).catch(() => null)));
+      return records.filter((record) => record !== null);
+    },
+    async get(ref) {
+      return read(fileName(ref)).catch(() => null);
+    },
+    async put(record) {
+      await mkdir(directory, { recursive: true, mode: 448 });
+      const target = path.join(directory, fileName(record));
+      await serialized(target, () => write(target, record));
+    },
+    async update(ref, mutate, create) {
+      await mkdir(directory, { recursive: true, mode: 448 });
+      const target = path.join(directory, fileName(ref));
+      return serialized(target, async () => {
+        const current = await read(fileName(ref)).catch(() => null) ?? create?.() ?? null;
+        if (!current)
+          return null;
+        mutate(current);
+        current.updatedAt = new Date().toISOString();
+        await write(target, current);
+        return current;
+      });
+    },
+    async remove(ref) {
+      await rm(path.join(directory, fileName(ref)), { force: true });
+    },
+    async putSnapshot(snapshot) {
+      const target = path.join(directory, "snapshots", snapshotFile(snapshot.id, snapshot.root));
+      await mkdir(path.dirname(target), { recursive: true, mode: 448 });
+      await writeFile(target, JSON.stringify(snapshot), { mode: 384 });
+    },
+    async getSnapshot(id, root) {
+      return readFile(path.join(directory, "snapshots", snapshotFile(id, root)), "utf8").then((text) => JSON.parse(text)).catch(() => null);
+    }
+  };
+}
+export {
+  createFileSandboxStore,
+  defaultStoreDirectory
+};

package/dist/sandbox/tar.d.ts

@@ -0,0 +1,12 @@
+/** A minimal POSIX (pax) tar writer, so archives are byte-identical on every platform. */
+export type TarEntry = {
+    path: string;
+    type: "file";
+    data: Uint8Array;
+    executable: boolean;
+} | {
+    path: string;
+    type: "symlink";
+    target: string;
+};
+export declare function createTarGz(entries: TarEntry[]): Buffer;

package/dist/sandbox/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Public sandbox types. The provider implementations live in a private package that the
+ * SDK bundles, so published declarations must not reference it; these mirror its shapes
+ * and the assertions below keep the two in step.
+ */
+export type SandboxProviderKey = "e2b" | "daytona" | "vercel" | "boat" | "exedev" | "railway" | "aws" | "gitterm";
+export type SandboxCapabilities = {
+    /**
+     * How an abandoned sandbox ends without the caller: `hard` deleted at the lifetime even
+     * while busy; `idle` deleted after a period without API activity; `archive` stopped and
+     * archived at the lifetime with storage kept until deleted; `none` never.
+     */
+    expiry: "hard" | "idle" | "archive" | "none";
+    /**
+     * `private` needs the access header, `public` is open to anyone with the URL, `either` is
+     * private unless created with public previews.
+     */
+    previews: "private" | "public" | "either" | "none";
+    pause: "stateful" | "state-losing";
+    maxLifetimeMs: number;
+    /** Whether sandboxes can be snapshotted, and whether saving `pauses` or `stops` (Vercel) them. */
+    snapshots: "pauses" | "stops" | "none";
+};
+export type SandboxCommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type SandboxPreviewAccess = {
+    url: string;
+    headers: Record<string, string>;
+};
+export type SandboxFailureCode = "auth" | "not_found" | "rate_limited" | "timeout" | "provider";
+/** A provider or API failure, as opposed to a command that exited non-zero. */
+export type SandboxProviderFailure = Error & {
+    name: "SandboxProviderError";
+    code: SandboxFailureCode;
+};
+export declare function isSandboxProviderError(error: unknown): error is SandboxProviderFailure;

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxProviderKey } from "./sandbox/types.js";
 export type AuthStatus = {
     loggedIn: true;
     userId: string;
@@ -103,7 +104,9 @@ export type WorkspaceListResult = {
         hasMore: boolean;
     };
 };
-export type ProviderKey = "railway" | "aws" | "e2b" | "daytona" | "cloudflare" | "vercel" | "ascii" | "exedev";
+export type ProviderKey = "railway" | "aws" | "e2b" | "daytona" | "cloudflare" | "vercel" | "boat" | "exedev"
+/** gitterm.dev's own sandboxes: pick a size (`small` or `medium`) as the machine. */
+ | "gitterm";
 type ProviderSelectionBase = {
     /** Select a specific provider installation. Usually omitted. */
     providerId?: string;
@@ -122,7 +125,7 @@ export type WorkspaceProviderSelection = {
     region?: string;
     accessProfile?: string;
 } & ProviderSelectionBase) | ({
-    type: "daytona" | "vercel" | "exedev" | "e2b" | "ascii";
+    type: "daytona" | "vercel" | "exedev" | "e2b" | "boat" | "gitterm";
 } & ProviderSelectionBase) | {
     type: "cloudflare";
     providerId?: string;
@@ -777,4 +780,50 @@ export type SavedBot = {
     /** When the settings last changed (ISO 8601); absent from older servers. */
     updatedAt?: string;
 };
+/** A plain command sandbox billed to the signed-in Gitterm account. No agent runs inside it. */
+export type ManagedSandbox = {
+    id: string;
+    provider: SandboxProviderKey;
+    name: string | null;
+    status: WorkspaceStatus;
+    metadata: Record<string, string>;
+    createdAt: string;
+    pausedAt: string | null;
+    terminatedAt: string | null;
+    lastActiveAt: string | null;
+    /** When Gitterm terminates the sandbox regardless of activity. */
+    expiresAt: string | null;
+    /** Terminated and confirmed deleted at the provider. A terminated sandbox without this is still being cleaned up. */
+    deleted: boolean;
+    machineProfileId: string | null;
+};
+/** A job finished in one of your sandboxes (Gitterm sandboxes on gitterm.dev only). */
+export type SandboxJobFinished = {
+    sandboxId: string;
+    jobId: string;
+    status: string;
+    exitCode: number | null;
+};
+export type ManagedSandboxCreateInput = {
+    /** Defaults to e2b. Must be enabled for sandboxes on the deployment. */
+    provider?: SandboxProviderKey;
+    name?: string;
+    lifetimeMinutes: number;
+    /** Machine profile key, e.g. `small` or `large`. Defaults to the plan's default size. */
+    machine?: string;
+    /** Serve preview URLs without the access header. Cannot be changed later. */
+    publicPreviews?: boolean;
+    metadata?: Record<string, string>;
+    idempotencyKey?: string;
+    /** Start from one of your snapshots (same provider). It keeps the size it was saved at. */
+    snapshotId?: string;
+};
+/** A managed sandbox saved as a snapshot, counted against your plan's snapshot limit. */
+export type ManagedSandboxSnapshot = {
+    id: string;
+    provider: SandboxProviderKey;
+    label: string;
+    machineProfileId: string | null;
+    createdAt: string;
+};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitterm/sdk",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "files": [
     "dist"
   ],
@@ -19,13 +19,25 @@
       "bun": "./dist/direct/index.js",
       "import": "./dist/direct/index.js",
       "default": "./dist/direct/index.js"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox/index.d.ts",
+      "bun": "./dist/sandbox/index.js",
+      "import": "./dist/sandbox/index.js",
+      "default": "./dist/sandbox/index.js"
+    },
+    "./sandbox/store": {
+      "types": "./dist/sandbox/store.d.ts",
+      "bun": "./dist/sandbox/store.js",
+      "import": "./dist/sandbox/store.js",
+      "default": "./dist/sandbox/store.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/direct/index.ts --outdir dist --target node --format esm --external @trpc/client --external eventsource --external e2b --external @asciidev/box-sdk --external @daytonaio/sdk --external @vercel/sandbox && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/direct/index.ts src/sandbox/index.ts src/sandbox/store.ts --outdir dist --target node --format esm --external @trpc/client --external eventsource --external e2b --external @asciidev/box-sdk --external @daytonaio/sdk --external @vercel/sandbox && tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run check-types && bun run build",
     "check-types": "tsc --noEmit"
   },
@@ -40,7 +52,7 @@
   "devDependencies": {
     "@gitterm/agent-runtime": "workspace:*",
     "@gitterm/api": "workspace:*",
-    "@opencode/client": "^2.0.19",
+    "@opencode/client": "2.2.6",
     "@trpc/server": "catalog:",
     "@types/bun": "^1.2.6",
     "typescript": "^5.8.2"

package/dist/direct/ascii.d.ts

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