veryfront 0.1.275 → 0.1.277

package/esm/deno.js

@@ -1,6 +1,6 @@
 export default {
     "name": "veryfront",
-    "version": "0.1.275",
+    "version": "0.1.277",
     "license": "Apache-2.0",
     "nodeModulesDir": "auto",
     "workspace": [

package/esm/src/sandbox/index.d.ts

@@ -18,4 +18,5 @@
  */
 import "../../_dnt.polyfills.js";
 export { type CommandJob, type CommandJobHeartbeatStatus, type CommandJobOutput, type CommandJobStatus, type ExecOptions, type ExecResult, type ExecStreamEvent, Sandbox, type SandboxListOptions, type SandboxListResult, type SandboxOptions, type SandboxSession, } from "./sandbox.js";
+export { LazySandbox, type LazySandboxOptions } from "./lazy-sandbox.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/src/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,OAAO,EACP,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,OAAO,EACP,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/esm/src/sandbox/index.js

@@ -18,3 +18,4 @@
  */
 import "../../_dnt.polyfills.js";
 export { Sandbox, } from "./sandbox.js";
+export { LazySandbox } from "./lazy-sandbox.js";

package/esm/src/sandbox/lazy-sandbox.d.ts

@@ -0,0 +1,57 @@
+import { type CommandJob, type CommandJobOutput, type ExecOptions, type ExecResult, type ExecStreamEvent, type SandboxOptions } from "./sandbox.js";
+export interface LazySandboxOptions extends SandboxOptions {
+    getProjectId?: () => string | null | undefined;
+    startupTimeoutMs?: number;
+    pollIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    heartbeatGraceMs?: number;
+}
+/** Lazily provisions sandbox sessions and keeps them alive while in use. */
+export declare class LazySandbox {
+    private readonly apiUrl;
+    private readonly authToken;
+    private readonly getProjectId;
+    private readonly startupTimeoutMs;
+    private readonly pollIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly heartbeatGraceMs;
+    private endpoint;
+    private sessionId;
+    private sessionProjectId;
+    private ensurePromise;
+    private closePromise;
+    private heartbeatPromise;
+    private heartbeatTimer;
+    private lastHeartbeatAt;
+    constructor(options?: LazySandboxOptions);
+    ensure(): Promise<void>;
+    executeCommand(command: string, options?: ExecOptions): Promise<ExecResult>;
+    executeStream(command: string, options?: ExecOptions): AsyncGenerator<ExecStreamEvent>;
+    readFile(path: string): Promise<string>;
+    writeFiles(files: Array<{
+        path: string;
+        content: string;
+    }>): Promise<void>;
+    startCommandJob(command: string, options?: ExecOptions): Promise<CommandJob>;
+    getCommandJob(jobId: string): Promise<CommandJob>;
+    getCommandJobOutput(jobId: string): Promise<CommandJobOutput>;
+    listCommandJobs(): Promise<CommandJob[]>;
+    cancelCommandJob(jobId: string): Promise<CommandJob>;
+    heartbeat(force?: boolean): Promise<void>;
+    close(): Promise<void>;
+    get id(): string | null;
+    get url(): string | null;
+    get isActive(): boolean;
+    private bootstrapSession;
+    private resolveReadyEndpoint;
+    private touchSession;
+    private startHeartbeatLoop;
+    private stopHeartbeatLoop;
+    private deleteSession;
+    private requireEndpoint;
+    private resolveProjectId;
+    private resetSessionState;
+    private authHeaders;
+    private jsonHeaders;
+}
+//# sourceMappingURL=lazy-sandbox.d.ts.map

package/esm/src/sandbox/lazy-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-sandbox.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/lazy-sandbox.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,gBAAgB,EAErB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EAGpB,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAaD,4EAA4E;AAC5E,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,gBAAgB,CAA8B;IACtD,OAAO,CAAC,cAAc,CAAuD;IAC7E,OAAO,CAAC,eAAe,CAAK;gBAEhB,OAAO,GAAE,kBAAuB;IAUtC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBvB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAsB1E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,eAAe,CAAC;IAwCvF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAcvC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB1E,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAkB5E,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBjD,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuB7D,eAAe,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAkBxC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBpD,SAAS,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6CvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC5B,IAAI,EAAE,IAAI,MAAM,GAAG,IAAI,CAEtB;IAED,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;YAEa,gBAAgB;YAiChB,oBAAoB;YA2BpB,YAAY;IAc1B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,iBAAiB;YAMX,aAAa;IAO3B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,WAAW;CAMpB"}

package/esm/src/sandbox/lazy-sandbox.js

@@ -0,0 +1,403 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { REQUEST_ERROR } from "../errors/index.js";
+import { resolveSandboxApiUrl, resolveSandboxAuthToken, waitForSandboxReady, } from "./sandbox.js";
+const DEFAULT_STARTUP_TIMEOUT_MS = 180_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+const DEFAULT_HEARTBEAT_GRACE_MS = 5_000;
+/** Lazily provisions sandbox sessions and keeps them alive while in use. */
+export class LazySandbox {
+    apiUrl;
+    authToken;
+    getProjectId;
+    startupTimeoutMs;
+    pollIntervalMs;
+    heartbeatIntervalMs;
+    heartbeatGraceMs;
+    endpoint = null;
+    sessionId = null;
+    sessionProjectId = null;
+    ensurePromise = null;
+    closePromise = null;
+    heartbeatPromise = null;
+    heartbeatTimer = null;
+    lastHeartbeatAt = 0;
+    constructor(options = {}) {
+        this.apiUrl = resolveSandboxApiUrl(options);
+        this.authToken = resolveSandboxAuthToken(options);
+        this.getProjectId = options.getProjectId ?? (() => options.projectId);
+        this.startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.heartbeatGraceMs = options.heartbeatGraceMs ?? DEFAULT_HEARTBEAT_GRACE_MS;
+    }
+    async ensure() {
+        if (this.endpoint)
+            return;
+        if (this.ensurePromise) {
+            await this.ensurePromise;
+            return;
+        }
+        const promise = this.bootstrapSession();
+        this.ensurePromise = promise;
+        try {
+            await promise;
+        }
+        finally {
+            if (this.ensurePromise === promise) {
+                this.ensurePromise = null;
+            }
+        }
+    }
+    async executeCommand(command, options) {
+        let stdout = "";
+        let stderr = "";
+        let exitCode = 1;
+        for await (const event of this.executeStream(command, options)) {
+            switch (event.type) {
+                case "stdout":
+                    stdout += event.data ?? "";
+                    break;
+                case "stderr":
+                    stderr += event.data ?? "";
+                    break;
+                case "exit":
+                    exitCode = event.exitCode ?? 1;
+                    break;
+            }
+        }
+        return { stdout, stderr, exitCode };
+    }
+    async *executeStream(command, options) {
+        await this.touchSession();
+        const res = await fetch(`${this.requireEndpoint()}/exec`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ command, ...options }),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({ detail: `Exec failed: ${res.status} ${await res.text()}` });
+        }
+        if (!res.body) {
+            throw new Error("Exec response has no body");
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                yield JSON.parse(line);
+            }
+        }
+        if (buffer.trim()) {
+            yield JSON.parse(buffer);
+        }
+    }
+    async readFile(path) {
+        await this.touchSession();
+        const res = await fetch(`${this.requireEndpoint()}/file?path=${encodeURIComponent(path)}`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({ detail: `Read file failed: ${res.status} ${await res.text()}` });
+        }
+        return await res.text();
+    }
+    async writeFiles(files) {
+        await this.touchSession();
+        const res = await fetch(`${this.requireEndpoint()}/files`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ files }),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Write files failed: ${res.status} ${await res.text()}`,
+            });
+        }
+    }
+    async startCommandJob(command, options) {
+        await this.touchSession();
+        const res = await fetch(`${this.requireEndpoint()}/exec/jobs`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ command, ...options }),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Start command job failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        return mapCommandJob(await res.json());
+    }
+    async getCommandJob(jobId) {
+        await this.ensure();
+        const res = await fetch(`${this.requireEndpoint()}/exec/jobs/${jobId}`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Get command job failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        return mapCommandJob(await res.json());
+    }
+    async getCommandJobOutput(jobId) {
+        await this.ensure();
+        const res = await fetch(`${this.requireEndpoint()}/exec/jobs/${jobId}/output`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Get command job output failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        const json = await res.json();
+        return {
+            ...mapCommandJob(json),
+            stdout: json.stdout,
+            stderr: json.stderr,
+            stdoutTruncated: json.stdout_truncated,
+            stderrTruncated: json.stderr_truncated,
+        };
+    }
+    async listCommandJobs() {
+        await this.ensure();
+        const res = await fetch(`${this.requireEndpoint()}/exec/jobs`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `List command jobs failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        const json = await res.json();
+        const jobs = Array.isArray(json) ? json : (json.jobs ?? []);
+        return jobs.map((job) => mapCommandJob(job));
+    }
+    async cancelCommandJob(jobId) {
+        await this.ensure();
+        const res = await fetch(`${this.requireEndpoint()}/exec/jobs/${jobId}/cancel`, {
+            method: "POST",
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Cancel command job failed: ${res.status} ${await res.text()}`,
+            });
+        }
+        return mapCommandJob(await res.json());
+    }
+    async heartbeat(force = false) {
+        const currentSessionId = this.sessionId;
+        if (!currentSessionId)
+            return;
+        if (this.heartbeatPromise) {
+            await this.heartbeatPromise;
+            return;
+        }
+        if (!force && this.lastHeartbeatAt > 0 &&
+            Date.now() - this.lastHeartbeatAt < this.heartbeatGraceMs) {
+            return;
+        }
+        const promise = (async () => {
+            const res = await fetch(`${this.apiUrl}/sandbox-sessions/${currentSessionId}/heartbeat`, {
+                method: "POST",
+                headers: this.authHeaders(),
+            });
+            if (!res.ok) {
+                if (this.sessionId === currentSessionId) {
+                    await this.deleteSession(currentSessionId);
+                    this.resetSessionState(currentSessionId);
+                }
+                throw new Error(`Sandbox heartbeat failed: ${res.status} ${await res.text()}`);
+            }
+            this.lastHeartbeatAt = Date.now();
+        })();
+        this.heartbeatPromise = promise;
+        try {
+            await promise;
+        }
+        finally {
+            if (this.heartbeatPromise === promise) {
+                this.heartbeatPromise = null;
+            }
+        }
+    }
+    async close() {
+        if (this.closePromise) {
+            await this.closePromise;
+            return;
+        }
+        const promise = (async () => {
+            if (this.ensurePromise) {
+                try {
+                    await this.ensurePromise;
+                }
+                catch {
+                    // startup failure already handled by the caller path
+                }
+            }
+            const currentSessionId = this.sessionId;
+            if (!currentSessionId) {
+                this.resetSessionState();
+                return;
+            }
+            await this.deleteSession(currentSessionId);
+            this.resetSessionState(currentSessionId);
+        })();
+        this.closePromise = promise;
+        try {
+            await promise;
+        }
+        finally {
+            if (this.closePromise === promise) {
+                this.closePromise = null;
+            }
+        }
+    }
+    get id() {
+        return this.sessionId;
+    }
+    get url() {
+        return this.endpoint;
+    }
+    get isActive() {
+        return this.endpoint !== null;
+    }
+    async bootstrapSession() {
+        const projectId = this.resolveProjectId();
+        const res = await fetch(`${this.apiUrl}/sandbox-sessions`, {
+            method: "POST",
+            headers: this.jsonHeaders(),
+            body: JSON.stringify(projectId ? { project_id: projectId } : {}),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Failed to create sandbox: ${res.status} ${await res.text()}`,
+            });
+        }
+        const session = await res.json();
+        this.sessionId = session.id;
+        this.sessionProjectId = projectId;
+        try {
+            const endpoint = await this.resolveReadyEndpoint(session);
+            this.endpoint = endpoint;
+            await this.heartbeat(true);
+            this.startHeartbeatLoop();
+        }
+        catch (error) {
+            const currentSessionId = this.sessionId;
+            if (currentSessionId) {
+                await this.deleteSession(currentSessionId);
+            }
+            this.resetSessionState(currentSessionId ?? undefined);
+            throw error;
+        }
+    }
+    async resolveReadyEndpoint(session) {
+        if (session.status === "running") {
+            return session.endpoint;
+        }
+        await waitForSandboxReady({
+            apiUrl: this.apiUrl,
+            id: session.id,
+            authToken: this.authToken,
+            maxWaitMs: this.startupTimeoutMs,
+            pollIntervalMs: this.pollIntervalMs,
+        });
+        const res = await fetch(`${this.apiUrl}/sandbox-sessions/${session.id}`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Failed to get sandbox: ${res.status} ${await res.text()}`,
+            });
+        }
+        const nextSession = await res.json();
+        return nextSession.endpoint;
+    }
+    async touchSession() {
+        const projectId = this.resolveProjectId();
+        if (this.endpoint && this.sessionProjectId !== projectId) {
+            const currentSessionId = this.sessionId;
+            if (currentSessionId) {
+                await this.deleteSession(currentSessionId);
+            }
+            this.resetSessionState(currentSessionId ?? undefined);
+        }
+        await this.ensure();
+        await this.heartbeat();
+    }
+    startHeartbeatLoop() {
+        if (!this.sessionId || this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = dntShim.setInterval(() => {
+            void this.heartbeat().catch(() => {
+                // next operation will reprovision
+            });
+        }, this.heartbeatIntervalMs);
+    }
+    stopHeartbeatLoop() {
+        if (!this.heartbeatTimer)
+            return;
+        clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    async deleteSession(sessionId) {
+        await fetch(`${this.apiUrl}/sandbox-sessions/${sessionId}`, {
+            method: "DELETE",
+            headers: this.authHeaders(),
+        });
+    }
+    requireEndpoint() {
+        if (!this.endpoint) {
+            throw new Error("Sandbox endpoint unavailable");
+        }
+        return this.endpoint;
+    }
+    resolveProjectId() {
+        return this.getProjectId() ?? null;
+    }
+    resetSessionState(sessionId) {
+        if (!sessionId || this.sessionId === sessionId) {
+            this.stopHeartbeatLoop();
+            this.endpoint = null;
+            this.sessionId = null;
+            this.sessionProjectId = null;
+            this.heartbeatPromise = null;
+            this.lastHeartbeatAt = 0;
+        }
+    }
+    authHeaders() {
+        return { Authorization: `Bearer ${this.authToken}` };
+    }
+    jsonHeaders() {
+        return {
+            ...this.authHeaders(),
+            "Content-Type": "application/json",
+        };
+    }
+}
+function mapCommandJob(json) {
+    return {
+        id: json.id,
+        status: json.status,
+        exitCode: json.exit_code,
+        signal: json.signal,
+        startedAt: json.started_at,
+        finishedAt: json.finished_at,
+        heartbeatStatus: json.heartbeat_status,
+        lastHeartbeatAt: json.last_heartbeat_at,
+        lastHeartbeatError: json.last_heartbeat_error,
+        heartbeatFailureCount: json.heartbeat_failure_count,
+    };
+}

package/esm/src/sandbox/sandbox.d.ts

@@ -1,3 +1,4 @@
+import { LazySandbox, type LazySandboxOptions } from "./lazy-sandbox.js";
 /** Options for command execution: working directory, timeout, and environment variables. */
 export interface ExecOptions {
     /** Working directory for the command. */
@@ -16,6 +17,8 @@ export interface SandboxOptions {
     /** Optional project context for project-billed / project-scoped sandbox sessions. */
     projectId?: string;
 }
+export declare function resolveSandboxApiUrl(options?: SandboxOptions): string;
+export declare function resolveSandboxAuthToken(options?: SandboxOptions): string;
 /** Result of a command execution: stdout, stderr, and exit code. */
 export interface ExecResult {
     stdout: string;
@@ -91,6 +94,8 @@ export declare class Sandbox {
     /** List sandbox sessions with optional pagination. */
     static list(options?: SandboxListOptions): Promise<SandboxListResult>;
     private static waitForReady;
+    /** Create a lazily-provisioned sandbox session with automatic heartbeats. */
+    static createLazy(options?: LazySandboxOptions): LazySandbox;
     /** Execute a bash command in the sandbox and return buffered result. */
     executeCommand(command: string, options?: ExecOptions): Promise<ExecResult>;
     /** Execute a bash command with streaming output (NDJSON). */
@@ -122,4 +127,11 @@ export declare class Sandbox {
     /** Get the sandbox endpoint URL. */
     get url(): string;
 }
+export declare function waitForSandboxReady(input: {
+    apiUrl: string;
+    id: string;
+    authToken: string;
+    maxWaitMs?: number;
+    pollIntervalMs?: number;
+}): Promise<void>;
 //# sourceMappingURL=sandbox.d.ts.map

package/esm/src/sandbox/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/src/sandbox/sandbox.ts"],"names":[],"mappings":"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"}

package/esm/src/sandbox/sandbox.js

@@ -10,6 +10,21 @@ import * as dntShim from "../../_dnt.shims.js";
 import { createError, INITIALIZATION_ERROR, REQUEST_ERROR, TIMEOUT_ERROR, toError, } from "../errors/index.js";
 import { getVeryfrontCloudAuthToken } from "../platform/cloud/resolver.js";
 import { getHostEnv } from "../platform/compat/process.js";
+import { LazySandbox } from "./lazy-sandbox.js";
+export function resolveSandboxApiUrl(options = {}) {
+    return options.apiUrl ||
+        getHostEnv("VERYFRONT_API_URL") ||
+        "https://api.veryfront.com";
+}
+export function resolveSandboxAuthToken(options = {}) {
+    const authToken = options.authToken?.trim() || getVeryfrontCloudAuthToken();
+    if (authToken)
+        return authToken;
+    throw toError(createError({
+        type: "config",
+        message: "Sandbox auth not configured. Set VERYFRONT_API_TOKEN, provide request-scoped Veryfront credentials, or pass authToken explicitly.",
+    }));
+}
 /** Client for isolated ephemeral compute environments with command execution and file I/O. */
 export class Sandbox {
     endpoint;
@@ -23,18 +38,10 @@ export class Sandbox {
         this.apiUrl = apiUrl;
     }
     static resolveApiUrl(options = {}) {
-        return options.apiUrl ||
-            getHostEnv("VERYFRONT_API_URL") ||
-            "https://api.veryfront.com";
+        return resolveSandboxApiUrl(options);
     }
     static resolveAuthToken(options = {}) {
-        const authToken = options.authToken?.trim() || getVeryfrontCloudAuthToken();
-        if (authToken)
-            return authToken;
-        throw toError(createError({
-            type: "config",
-            message: "Sandbox auth not configured. Set VERYFRONT_API_TOKEN, provide request-scoped Veryfront credentials, or pass authToken explicitly.",
-        }));
+        return resolveSandboxAuthToken(options);
     }
     /** Create a new sandbox session. Claims a warm pod or creates a new one. */
     static async create(options = {}) {
@@ -112,25 +119,11 @@ export class Sandbox {
         };
     }
     static async waitForReady(apiUrl, id, authToken, maxWaitMs = 60_000, pollIntervalMs = 2_000) {
-        const start = Date.now();
-        while (Date.now() - start < maxWaitMs) {
-            // no cleanup needed: one-shot
-            await new Promise((r) => dntShim.setTimeout(r, pollIntervalMs));
-            const res = await fetch(`${apiUrl}/sandbox-sessions/${id}`, {
-                headers: { Authorization: `Bearer ${authToken}` },
-            });
-            if (res.ok) {
-                const data = await res.json();
-                if (data.status === "running")
-                    return;
-                if (data.status === "error" || data.status === "deleting") {
-                    throw INITIALIZATION_ERROR.create({
-                        detail: `Sandbox failed to start: status=${data.status}`,
-                    });
-                }
-            }
-        }
-        throw TIMEOUT_ERROR.create({ detail: "Sandbox did not become ready within timeout" });
+        await waitForSandboxReady({ apiUrl, id, authToken, maxWaitMs, pollIntervalMs });
+    }
+    /** Create a lazily-provisioned sandbox session with automatic heartbeats. */
+    static createLazy(options = {}) {
+        return new LazySandbox(options);
     }
     /** Execute a bash command in the sandbox and return buffered result. */
     async executeCommand(command, options) {
@@ -305,17 +298,27 @@ export class Sandbox {
     }
     /** Send a heartbeat to prevent idle timeout. */
     async heartbeat() {
-        await fetch(`${this.apiUrl}/sandbox-sessions/${this.sessionId}/heartbeat`, {
+        const res = await fetch(`${this.apiUrl}/sandbox-sessions/${this.sessionId}/heartbeat`, {
             method: "POST",
             headers: { Authorization: `Bearer ${this.authToken}` },
         });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Sandbox heartbeat failed: ${res.status} ${await res.text()}`,
+            });
+        }
     }
     /** Close the sandbox session and mark for deletion. */
     async close() {
-        await fetch(`${this.apiUrl}/sandbox-sessions/${this.sessionId}`, {
+        const res = await fetch(`${this.apiUrl}/sandbox-sessions/${this.sessionId}`, {
             method: "DELETE",
             headers: { Authorization: `Bearer ${this.authToken}` },
         });
+        if (!res.ok) {
+            throw REQUEST_ERROR.create({
+                detail: `Close sandbox failed: ${res.status} ${await res.text()}`,
+            });
+        }
     }
     /** Get the session ID. */
     get id() {
@@ -326,3 +329,26 @@ export class Sandbox {
         return this.endpoint;
     }
 }
+export async function waitForSandboxReady(input) {
+    const maxWaitMs = input.maxWaitMs ?? 60_000;
+    const pollIntervalMs = input.pollIntervalMs ?? 2_000;
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        await new Promise((resolve) => dntShim.setTimeout(resolve, pollIntervalMs));
+        const res = await fetch(`${input.apiUrl}/sandbox-sessions/${input.id}`, {
+            headers: { Authorization: `Bearer ${input.authToken}` },
+        });
+        if (!res.ok) {
+            continue;
+        }
+        const data = await res.json();
+        if (data.status === "running")
+            return;
+        if (data.status === "error" || data.status === "deleting") {
+            throw INITIALIZATION_ERROR.create({
+                detail: `Sandbox failed to start: status=${data.status}`,
+            });
+        }
+    }
+    throw TIMEOUT_ERROR.create({ detail: "Sandbox did not become ready within timeout" });
+}

package/esm/src/utils/version-constant.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.275";
+export declare const VERSION = "0.1.277";
 //# sourceMappingURL=version-constant.d.ts.map