@alibaba-group/opensandbox 0.1.0-dev1

package/dist/models/sandboxes.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Domain models for sandbox lifecycle.
+ *
+ * IMPORTANT:
+ * - These are NOT OpenAPI-generated types.
+ * - They are intentionally stable and JS-friendly.
+ *
+ * The internal OpenAPI schemas may change frequently; adapters map responses into these models.
+ */
+export type SandboxId = string;
+export interface ImageAuth extends Record<string, unknown> {
+    username?: string;
+    password?: string;
+    token?: string;
+}
+export interface ImageSpec {
+    uri: string;
+    auth?: ImageAuth;
+}
+export type ResourceLimits = Record<string, string>;
+export type SandboxState = "Creating" | "Running" | "Pausing" | "Paused" | "Resuming" | "Deleting" | "Deleted" | "Error" | string;
+export interface SandboxStatus extends Record<string, unknown> {
+    state: SandboxState;
+    reason?: string;
+    message?: string;
+}
+export interface SandboxInfo extends Record<string, unknown> {
+    id: SandboxId;
+    image: ImageSpec;
+    entrypoint: string[];
+    metadata?: Record<string, string>;
+    status: SandboxStatus;
+    /**
+     * Sandbox creation time.
+     */
+    createdAt: Date;
+    /**
+     * Sandbox expiration time (server-side TTL).
+     */
+    expiresAt: Date;
+}
+export interface CreateSandboxRequest extends Record<string, unknown> {
+    image: ImageSpec;
+    entrypoint: string[];
+    /**
+     * Timeout in seconds (server semantics).
+     */
+    timeout: number;
+    resourceLimits: ResourceLimits;
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+    extensions?: Record<string, unknown>;
+}
+export interface CreateSandboxResponse extends Record<string, unknown> {
+    id: SandboxId;
+    status: SandboxStatus;
+    metadata?: Record<string, string>;
+    /**
+     * Sandbox expiration time after creation.
+     */
+    expiresAt: Date;
+    /**
+     * Sandbox creation time.
+     */
+    createdAt: Date;
+    entrypoint: string[];
+}
+export interface PaginationInfo extends Record<string, unknown> {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasNextPage: boolean;
+}
+export interface ListSandboxesResponse extends Record<string, unknown> {
+    items: SandboxInfo[];
+    pagination?: PaginationInfo;
+}
+export interface RenewSandboxExpirationRequest {
+    expiresAt: string;
+}
+export interface RenewSandboxExpirationResponse extends Record<string, unknown> {
+    /**
+     * Updated expiration time (if the server returns it).
+     */
+    expiresAt?: Date;
+}
+export interface Endpoint extends Record<string, unknown> {
+    endpoint: string;
+}
+export interface ListSandboxesParams {
+    /**
+     * Filter by lifecycle state (the API supports multiple `state` query params).
+     * Example: `{ states: ["Running", "Paused"] }`
+     */
+    states?: string[];
+    /**
+     * Filter by metadata key-value pairs.
+     * NOTE: This will be encoded to a single `metadata` query parameter as described in the spec.
+     */
+    metadata?: Record<string, string>;
+    page?: number;
+    pageSize?: number;
+}
+//# sourceMappingURL=sandboxes.d.ts.map

package/dist/models/sandboxes.d.ts.map

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

package/dist/models/sandboxes.js

@@ -0,0 +1,15 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+;
+export {};

package/dist/openapi/execdClient.d.ts

@@ -0,0 +1,25 @@
+import type { Client } from "openapi-fetch";
+import type { paths as ExecdPaths } from "../api/execd.js";
+export type ExecdClient = Client<ExecdPaths>;
+export interface CreateExecdClientOptions {
+    /**
+     * Base URL to the Execd API (no `/v1` prefix).
+     * Examples:
+     * - `http://localhost:44772`
+     * - `http://api.opensandbox.io/sandboxes/<id>/port/44772`
+     */
+    baseUrl: string;
+    /**
+     * Extra headers applied to every request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Custom fetch implementation.
+     *
+     * Useful for proxies, custom TLS, request tracing, retries, or running in environments
+     * where a global `fetch` is not available.
+     */
+    fetch?: typeof fetch;
+}
+export declare function createExecdClient(opts: CreateExecdClientOptions): ExecdClient;
+//# sourceMappingURL=execdClient.d.ts.map

package/dist/openapi/execdClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execdClient.d.ts","sourceRoot":"","sources":["../../src/openapi/execdClient.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE3D,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;AAE7C,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,WAAW,CAM7E"}

package/dist/openapi/execdClient.js

@@ -0,0 +1,21 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import createClient from "openapi-fetch";
+export function createExecdClient(opts) {
+    return createClient({
+        baseUrl: opts.baseUrl,
+        headers: opts.headers,
+        fetch: opts.fetch,
+    });
+}

package/dist/openapi/lifecycleClient.d.ts

@@ -0,0 +1,28 @@
+import type { Client } from "openapi-fetch";
+import type { paths as LifecyclePaths } from "../api/lifecycle.js";
+export type LifecycleClient = Client<LifecyclePaths>;
+export interface CreateLifecycleClientOptions {
+    /**
+     * Base URL to OpenSandbox Lifecycle API, including the `/v1` prefix.
+     * Example: `http://localhost:8080/v1`
+     */
+    baseUrl?: string;
+    /**
+     * API key for `OPEN-SANDBOX-API-KEY` header.
+     * If omitted, reads from `process.env.OPEN_SANDBOX_API_KEY` when available.
+     */
+    apiKey?: string;
+    /**
+     * Extra headers applied to every request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Custom fetch implementation.
+     *
+     * Useful for proxies, custom TLS, request tracing, retries, or running in environments
+     * where a global `fetch` is not available.
+     */
+    fetch?: typeof fetch;
+}
+export declare function createLifecycleClient(opts?: CreateLifecycleClientOptions): LifecycleClient;
+//# sourceMappingURL=lifecycleClient.d.ts.map

package/dist/openapi/lifecycleClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycleClient.d.ts","sourceRoot":"","sources":["../../src/openapi/lifecycleClient.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,KAAK,EAAE,KAAK,IAAI,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEnE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAErD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAUD,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,4BAAiC,GAAG,eAAe,CAgB9F"}

package/dist/openapi/lifecycleClient.js

@@ -0,0 +1,35 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import createClient from "openapi-fetch";
+function readEnvApiKey() {
+    // Avoid requiring @types/node by not referencing `process` directly.
+    // In Node, `globalThis.process.env` exists; in browsers it won't.
+    const env = globalThis?.process?.env;
+    const v = env?.OPEN_SANDBOX_API_KEY;
+    return typeof v === "string" && v.length ? v : undefined;
+}
+export function createLifecycleClient(opts = {}) {
+    const apiKey = opts.apiKey ?? readEnvApiKey();
+    const headers = {
+        ...(opts.headers ?? {}),
+    };
+    if (apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
+        headers["OPEN-SANDBOX-API-KEY"] = apiKey;
+    }
+    return createClient({
+        baseUrl: opts.baseUrl ?? "http://localhost:8080/v1",
+        headers,
+        fetch: opts.fetch,
+    });
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,132 @@
+import { ConnectionConfig, type ConnectionConfigOptions } from "./config/connection.js";
+import type { SandboxFiles } from "./services/filesystem.js";
+import type { AdapterFactory } from "./factory/adapterFactory.js";
+import type { Sandboxes } from "./services/sandboxes.js";
+import type { ExecdCommands } from "./services/execdCommands.js";
+import type { ExecdHealth } from "./services/execdHealth.js";
+import type { ExecdMetrics } from "./services/execdMetrics.js";
+import type { Endpoint, RenewSandboxExpirationResponse, SandboxId, SandboxInfo } from "./models/sandboxes.js";
+export interface SandboxCreateOptions {
+    /**
+     * Connection configuration for calling the OpenSandbox Lifecycle API and the sandbox's execd API.
+     */
+    connectionConfig?: ConnectionConfig | ConnectionConfigOptions;
+    /**
+     * Advanced override: inject a custom adapter factory (custom transports, dependency injection).
+     */
+    adapterFactory?: AdapterFactory;
+    /**
+     * Container image uri, e.g. `python:3.11`
+     */
+    image: string | {
+        uri: string;
+        auth?: {
+            username: string;
+            password: string;
+        };
+    };
+    entrypoint?: string[];
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+    extensions?: Record<string, string>;
+    /**
+     * Resource limits applied to the sandbox container.
+     *
+     * This is forwarded to the Lifecycle API as `resourceLimits`.
+     */
+    resource?: Record<string, string>;
+    /**
+     * Sandbox timeout in seconds.
+     */
+    timeoutSeconds?: number;
+    /**
+     * Skip readiness checks during create/connect.
+     *
+     * When true, the SDK will not wait for lifecycle state `Running` or perform the health check.
+     * The returned sandbox instance may not be ready yet.
+     */
+    skipHealthCheck?: boolean;
+    /**
+     * Optional custom readiness check used by {@link Sandbox.waitUntilReady}.
+     *
+     * If provided, the SDK will call this function during readiness checks instead of
+     * using the default `execd` ping check.
+     */
+    healthCheck?: (sbx: Sandbox) => boolean | Promise<boolean>;
+    readyTimeoutSeconds?: number;
+    healthCheckPollingInterval?: number;
+}
+export interface SandboxConnectOptions {
+    connectionConfig?: ConnectionConfig | ConnectionConfigOptions;
+    adapterFactory?: AdapterFactory;
+    sandboxId: SandboxId;
+    skipHealthCheck?: boolean;
+    healthCheck?: (sbx: Sandbox) => boolean | Promise<boolean>;
+    readyTimeoutSeconds?: number;
+    healthCheckPollingInterval?: number;
+}
+export declare class Sandbox {
+    readonly id: SandboxId;
+    readonly connectionConfig: ConnectionConfig;
+    /**
+     * Lifecycle (sandbox management) service.
+     */
+    readonly sandboxes: Sandboxes;
+    /**
+     * Execd services.
+     */
+    readonly commands: ExecdCommands;
+    /**
+     * High-level filesystem facade (JS-friendly).
+     */
+    readonly files: SandboxFiles;
+    readonly health: ExecdHealth;
+    readonly metrics: ExecdMetrics;
+    /**
+     * Internal state kept out of the public instance shape.
+     *
+     * This avoids nominal typing issues when multiple copies of the SDK exist in a dependency graph.
+     */
+    private static readonly _priv;
+    private constructor();
+    static create(opts: SandboxCreateOptions): Promise<Sandbox>;
+    static connect(opts: SandboxConnectOptions): Promise<Sandbox>;
+    getInfo(): Promise<SandboxInfo>;
+    isHealthy(): Promise<boolean>;
+    getMetrics(): Promise<import("./index.js").SandboxMetrics>;
+    pause(): Promise<void>;
+    /**
+     * Resume a paused sandbox and return a fresh, connected Sandbox instance.
+     *
+     * After resume, the execd endpoint may change, so this method returns a new
+     * {@link Sandbox} instance with a refreshed execd base URL.
+     */
+    resume(opts?: {
+        skipHealthCheck?: boolean;
+        readyTimeoutSeconds?: number;
+        healthCheckPollingInterval?: number;
+    }): Promise<Sandbox>;
+    /**
+     * Resume a paused sandbox by id, then connect to its execd endpoint.
+     */
+    static resume(opts: SandboxConnectOptions): Promise<Sandbox>;
+    kill(): Promise<void>;
+    /**
+     * Renew expiration by setting expiresAt to now + timeoutSeconds.
+     */
+    renew(timeoutSeconds: number): Promise<RenewSandboxExpirationResponse>;
+    /**
+     * Get sandbox endpoint for a port (STRICT: no scheme), e.g. "localhost:44772" or "domain/route/.../44772".
+     */
+    getEndpoint(port: number): Promise<Endpoint>;
+    /**
+     * Get absolute endpoint URL with scheme (convenience for HTTP clients).
+     */
+    getEndpointUrl(port: number): Promise<string>;
+    waitUntilReady(opts: {
+        readyTimeoutSeconds: number;
+        pollingIntervalMillis: number;
+        healthCheck?: (sbx: Sandbox) => boolean | Promise<boolean>;
+    }): Promise<void>;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

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

package/dist/sandbox.js

@@ -0,0 +1,250 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+import { DEFAULT_ENTRYPOINT, DEFAULT_EXECD_PORT, DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS, DEFAULT_READY_TIMEOUT_SECONDS, DEFAULT_RESOURCE_LIMITS, DEFAULT_TIMEOUT_SECONDS, } from "./core/constants.js";
+import { ConnectionConfig } from "./config/connection.js";
+import { createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js";
+import { SandboxReadyTimeoutException } from "./core/exceptions.js";
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function toImageSpec(image) {
+    if (typeof image === "string")
+        return { uri: image };
+    return { uri: image.uri, auth: image.auth };
+}
+export class Sandbox {
+    id;
+    connectionConfig;
+    /**
+     * Lifecycle (sandbox management) service.
+     */
+    sandboxes;
+    /**
+     * Execd services.
+     */
+    commands;
+    /**
+     * High-level filesystem facade (JS-friendly).
+     */
+    files;
+    health;
+    metrics;
+    /**
+     * Internal state kept out of the public instance shape.
+     *
+     * This avoids nominal typing issues when multiple copies of the SDK exist in a dependency graph.
+     */
+    static _priv = new WeakMap();
+    constructor(opts) {
+        this.id = opts.id;
+        this.connectionConfig = opts.connectionConfig;
+        Sandbox._priv.set(this, {
+            adapterFactory: opts.adapterFactory,
+            lifecycleBaseUrl: opts.lifecycleBaseUrl,
+            execdBaseUrl: opts.execdBaseUrl,
+        });
+        this.sandboxes = opts.sandboxes;
+        this.commands = opts.commands;
+        this.files = opts.files;
+        this.health = opts.health;
+        this.metrics = opts.metrics;
+    }
+    static async create(opts) {
+        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+            ? opts.connectionConfig
+            : new ConnectionConfig(opts.connectionConfig);
+        const lifecycleBaseUrl = connectionConfig.getBaseUrl();
+        const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
+        const { sandboxes } = adapterFactory.createLifecycleStack({
+            connectionConfig,
+            lifecycleBaseUrl,
+        });
+        const req = {
+            image: toImageSpec(opts.image),
+            entrypoint: opts.entrypoint ?? DEFAULT_ENTRYPOINT,
+            timeout: Math.max(60, Math.floor(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS)),
+            resourceLimits: opts.resource ?? DEFAULT_RESOURCE_LIMITS,
+            env: opts.env ?? {},
+            metadata: opts.metadata ?? {},
+            extensions: opts.extensions ?? {},
+        };
+        const created = await sandboxes.createSandbox(req);
+        const sandboxId = created.id;
+        const endpoint = await sandboxes.getSandboxEndpoint(sandboxId, DEFAULT_EXECD_PORT);
+        const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+        const { commands, files, health, metrics } = adapterFactory.createExecdStack({
+            connectionConfig,
+            execdBaseUrl,
+        });
+        const sbx = new Sandbox({
+            id: sandboxId,
+            connectionConfig,
+            adapterFactory,
+            lifecycleBaseUrl,
+            execdBaseUrl,
+            sandboxes,
+            commands,
+            files,
+            health,
+            metrics,
+        });
+        if (!(opts.skipHealthCheck ?? false)) {
+            await sbx.waitUntilReady({
+                readyTimeoutSeconds: opts.readyTimeoutSeconds ?? DEFAULT_READY_TIMEOUT_SECONDS,
+                pollingIntervalMillis: opts.healthCheckPollingInterval ??
+                    DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
+                healthCheck: opts.healthCheck,
+            });
+        }
+        return sbx;
+    }
+    static async connect(opts) {
+        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+            ? opts.connectionConfig
+            : new ConnectionConfig(opts.connectionConfig);
+        const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
+        const lifecycleBaseUrl = connectionConfig.getBaseUrl();
+        const { sandboxes } = adapterFactory.createLifecycleStack({
+            connectionConfig,
+            lifecycleBaseUrl,
+        });
+        const endpoint = await sandboxes.getSandboxEndpoint(opts.sandboxId, DEFAULT_EXECD_PORT);
+        const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+        const { commands, files, health, metrics } = adapterFactory.createExecdStack({
+            connectionConfig,
+            execdBaseUrl,
+        });
+        const sbx = new Sandbox({
+            id: opts.sandboxId,
+            connectionConfig,
+            adapterFactory,
+            lifecycleBaseUrl,
+            execdBaseUrl,
+            sandboxes,
+            commands,
+            files,
+            health,
+            metrics,
+        });
+        if (!(opts.skipHealthCheck ?? false)) {
+            await sbx.waitUntilReady({
+                readyTimeoutSeconds: opts.readyTimeoutSeconds ?? DEFAULT_READY_TIMEOUT_SECONDS,
+                pollingIntervalMillis: opts.healthCheckPollingInterval ??
+                    DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
+                healthCheck: opts.healthCheck,
+            });
+        }
+        return sbx;
+    }
+    async getInfo() {
+        return await this.sandboxes.getSandbox(this.id);
+    }
+    async isHealthy() {
+        try {
+            return await this.health.ping();
+        }
+        catch {
+            return false;
+        }
+    }
+    async getMetrics() {
+        return await this.metrics.getMetrics();
+    }
+    async pause() {
+        await this.sandboxes.pauseSandbox(this.id);
+    }
+    /**
+     * Resume a paused sandbox and return a fresh, connected Sandbox instance.
+     *
+     * After resume, the execd endpoint may change, so this method returns a new
+     * {@link Sandbox} instance with a refreshed execd base URL.
+     */
+    async resume(opts = {}) {
+        await this.sandboxes.resumeSandbox(this.id);
+        return await Sandbox.connect({
+            sandboxId: this.id,
+            connectionConfig: this.connectionConfig,
+            adapterFactory: Sandbox._priv.get(this).adapterFactory,
+            skipHealthCheck: opts.skipHealthCheck ?? false,
+            readyTimeoutSeconds: opts.readyTimeoutSeconds,
+            healthCheckPollingInterval: opts.healthCheckPollingInterval,
+        });
+    }
+    /**
+     * Resume a paused sandbox by id, then connect to its execd endpoint.
+     */
+    static async resume(opts) {
+        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+            ? opts.connectionConfig
+            : new ConnectionConfig(opts.connectionConfig);
+        const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
+        const lifecycleBaseUrl = connectionConfig.getBaseUrl();
+        const { sandboxes } = adapterFactory.createLifecycleStack({
+            connectionConfig,
+            lifecycleBaseUrl,
+        });
+        await sandboxes.resumeSandbox(opts.sandboxId);
+        return await Sandbox.connect({ ...opts, connectionConfig, adapterFactory });
+    }
+    async kill() {
+        await this.sandboxes.deleteSandbox(this.id);
+    }
+    /**
+     * Renew expiration by setting expiresAt to now + timeoutSeconds.
+     */
+    async renew(timeoutSeconds) {
+        const expiresAt = new Date(Date.now() + timeoutSeconds * 1000).toISOString();
+        return await this.sandboxes.renewSandboxExpiration(this.id, { expiresAt });
+    }
+    /**
+     * Get sandbox endpoint for a port (STRICT: no scheme), e.g. "localhost:44772" or "domain/route/.../44772".
+     */
+    async getEndpoint(port) {
+        return await this.sandboxes.getSandboxEndpoint(this.id, port);
+    }
+    /**
+     * Get absolute endpoint URL with scheme (convenience for HTTP clients).
+     */
+    async getEndpointUrl(port) {
+        const ep = await this.getEndpoint(port);
+        return `${this.connectionConfig.protocol}://${ep.endpoint}`;
+    }
+    async waitUntilReady(opts) {
+        const deadline = Date.now() + opts.readyTimeoutSeconds * 1000;
+        // Wait until execd becomes reachable and passes health check.
+        while (true) {
+            if (Date.now() > deadline) {
+                throw new SandboxReadyTimeoutException({
+                    message: `Sandbox not ready: timed out waiting for health check (timeoutSeconds=${opts.readyTimeoutSeconds})`,
+                });
+            }
+            try {
+                if (opts.healthCheck) {
+                    const ok = await opts.healthCheck(this);
+                    if (ok)
+                        return;
+                }
+                else {
+                    const ok = await this.health.ping();
+                    if (ok)
+                        return;
+                }
+            }
+            catch {
+                // ignore and retry
+            }
+            await sleep(opts.pollingIntervalMillis);
+        }
+    }
+}

package/dist/services/execdCommands.d.ts

@@ -0,0 +1,19 @@
+import type { ExecutionHandlers } from "../models/execution.js";
+import type { CommandExecution, RunCommandOpts, ServerStreamEvent } from "../models/execd.js";
+export interface ExecdCommands {
+    /**
+     * Run a command and stream server events (SSE). This is the lowest-level API.
+     */
+    runStream(command: string, opts?: RunCommandOpts, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
+    /**
+     * Convenience: run a command, consume the stream, and build a structured execution result.
+     */
+    run(command: string, opts?: RunCommandOpts, handlers?: ExecutionHandlers, signal?: AbortSignal): Promise<CommandExecution>;
+    /**
+     * Interrupt the current execution in the given context/session.
+     *
+     * Note: Execd spec uses `DELETE /command?id=<sessionId>`.
+     */
+    interrupt(sessionId: string): Promise<void>;
+}
+//# sourceMappingURL=execdCommands.d.ts.map

package/dist/services/execdCommands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execdCommands.d.ts","sourceRoot":"","sources":["../../src/services/execdCommands.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE9F,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAE1G;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE3H;;;;OAIG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}