@alibaba-group/opensandbox 0.1.0-dev3 → 0.1.0-dev4

package/README.md

@@ -52,6 +52,7 @@ try {
 
   // Optional but recommended: terminate the remote instance when you are done.
   await sandbox.kill();
+  await sandbox.close();
 } catch (err) {
   if (err instanceof SandboxException) {
     console.error(`Sandbox Error: [${err.error.code}] ${err.error.message ?? ""}`);
@@ -157,6 +158,7 @@ import { SandboxManager } from "@alibaba-group/opensandbox";
 const manager = SandboxManager.create({ connectionConfig: config });
 const list = await manager.listSandboxInfos({ states: ["Running"], pageSize: 10 });
 console.log(list.items.map((s) => s.id));
+await manager.close();
 ```
 
 ## Configuration
@@ -167,7 +169,7 @@ The `ConnectionConfig` class manages API server connection settings.
 
 Runtime notes:
 - In browsers, the SDK uses the global `fetch` implementation.
-- In Node.js, the SDK creates a dedicated internal `fetch` backed by an isolated connection pool.
+- In Node.js, every `Sandbox` and `SandboxManager` clones the base `ConnectionConfig` via `withTransportIfMissing()`, so each instance gets an isolated `undici` keep-alive pool. Call `sandbox.close()` or `manager.close()` when you are done so the SDK can release the associated agent.
 
 | Parameter | Description | Default | Environment Variable |
 | --- | --- | --- | --- |
@@ -214,6 +216,13 @@ const config2 = new ConnectionConfig({
 | `readyTimeoutSeconds` | Max time to wait for readiness | 30 seconds |
 | `healthCheckPollingInterval` | Poll interval while waiting (milliseconds) | 200 ms |
 
+### 3. Resource cleanup
+
+Both `Sandbox` and `SandboxManager` own a scoped HTTP agent when running on Node.js
+so you can safely reuse the same `ConnectionConfig`. Once you are finished interacting
+with the sandbox or administration APIs, call `sandbox.close()` / `manager.close()` to
+release the underlying agent. 
+
 ## Browser Notes
 
 - The SDK can run in browsers, but **streaming file uploads are Node-only**.

package/dist/config/connection.d.ts

@@ -33,18 +33,14 @@ export declare class ConnectionConfig {
     readonly domain: string;
     readonly apiKey?: string;
     readonly headers: Record<string, string>;
-    readonly fetch: typeof fetch;
-    /**
-     * Fetch function intended for long-lived streaming requests (SSE).
-     *
-     * This is separate from {@link fetch} so callers can supply a different implementation
-     * (e.g. Node undici with bodyTimeout disabled) and so the SDK can apply distinct
-     * timeout semantics for streaming vs normal HTTP calls.
-     */
-    readonly sseFetch: typeof fetch;
+    private _fetch;
+    private _sseFetch;
     readonly requestTimeoutSeconds: number;
     readonly debug: boolean;
     readonly userAgent: string;
+    private _closeTransport;
+    private _closePromise;
+    private _transportInitialized;
     /**
      * Create a connection configuration.
      *
@@ -53,6 +49,21 @@ export declare class ConnectionConfig {
      * - `OPEN_SANDBOX_API_KEY`
      */
     constructor(opts?: ConnectionConfigOptions);
+    get fetch(): typeof fetch;
+    get sseFetch(): typeof fetch;
     getBaseUrl(): string;
+    private initializeTransport;
+    /**
+     * Ensure this configuration has transport helpers (fetch/SSE) allocated.
+     *
+     * On Node.js this creates a dedicated `undici` dispatcher; on browsers it
+     * simply reuses the global fetch. Returns either `this` or a cloned config
+     * with the transport initialized.
+     */
+    withTransportIfMissing(): ConnectionConfig;
+    /**
+     * Close the Node.js agent owned by this configuration.
+     */
+    closeTransport(): Promise<void>;
 }
 //# sourceMappingURL=connection.d.ts.map

package/dist/config/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/config/connection.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA2KD,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC;IAChC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAA8B;IAExD;;;;;;OAMG;gBACS,IAAI,GAAE,uBAA4B;IAyD9C,UAAU,IAAI,MAAM;CAUrB"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/config/connection.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAsMD,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAsB;IACvC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAA8B;IACxD,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,qBAAqB,CAAS;IAEtC;;;;;;OAMG;gBACS,IAAI,GAAE,uBAA4B;IAsC9C,IAAI,KAAK,IAAI,OAAO,KAAK,CAExB;IAED,IAAI,QAAQ,IAAI,OAAO,KAAK,CAE3B;IAED,UAAU,IAAI,MAAM;IAWpB,OAAO,CAAC,mBAAmB;IAqB3B;;;;;;OAMG;IACH,sBAAsB,IAAI,gBAAgB;IAiB1C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CAKtC"}

package/dist/config/connection.js

@@ -35,7 +35,7 @@ function stripV1Suffix(s) {
     const trimmed = stripTrailingSlashes(s);
     return trimmed.endsWith("/v1") ? trimmed.slice(0, -3) : trimmed;
 }
-const DEFAULT_KEEPALIVE_TIMEOUT_MS = 15_000;
+const DEFAULT_KEEPALIVE_TIMEOUT_MS = 30_000;
 function normalizeDomainBase(input) {
     // Accept a full URL and preserve its path prefix (if any).
     if (input.startsWith("http://") || input.startsWith("https://")) {
@@ -50,17 +50,21 @@ function normalizeDomainBase(input) {
 }
 function createNodeFetch() {
     if (!isNodeRuntime()) {
-        return fetch;
+        return {
+            fetch,
+            close: async () => {
+                // Browser fetch has no pooled dispatcher to close.
+            },
+        };
     }
+    const baseFetch = fetch;
     let dispatcher;
     let dispatcherPromise = null;
-    const baseFetch = fetch;
-    return async (input, init) => {
+    const nodeFetch = async (input, init) => {
         dispatcherPromise ??= (async () => {
             try {
                 const mod = await import("undici");
-                const Agent = mod
-                    .Agent;
+                const Agent = mod.Agent;
                 if (!Agent) {
                     return undefined;
                 }
@@ -83,6 +87,24 @@ function createNodeFetch() {
         }
         return baseFetch(input, init);
     };
+    return {
+        fetch: nodeFetch,
+        close: async () => {
+            if (dispatcherPromise) {
+                await dispatcherPromise.catch(() => undefined);
+            }
+            if (dispatcher &&
+                typeof dispatcher === "object" &&
+                typeof dispatcher.close === "function") {
+                try {
+                    await dispatcher.close();
+                }
+                catch {
+                    // swallow close errors
+                }
+            }
+        },
+    };
 }
 function createTimedFetch(opts) {
     const baseFetch = opts.baseFetch;
@@ -140,18 +162,14 @@ export class ConnectionConfig {
     domain;
     apiKey;
     headers;
-    fetch;
-    /**
-     * Fetch function intended for long-lived streaming requests (SSE).
-     *
-     * This is separate from {@link fetch} so callers can supply a different implementation
-     * (e.g. Node undici with bodyTimeout disabled) and so the SDK can apply distinct
-     * timeout semantics for streaming vs normal HTTP calls.
-     */
-    sseFetch;
+    _fetch;
+    _sseFetch;
     requestTimeoutSeconds;
     debug;
     userAgent = "OpenSandbox-JS-SDK/0.1.0";
+    _closeTransport;
+    _closePromise = null;
+    _transportInitialized = false;
     /**
      * Create a connection configuration.
      *
@@ -186,33 +204,75 @@ export class ConnectionConfig {
             headers["user-agent"] = this.userAgent;
         }
         this.headers = headers;
-        // Node SDK: do not expose custom fetch in ConnectionConfigOptions.
-        // Use a node-scoped fetch with a dedicated dispatcher (keep-alive 30s).
-        const baseFetch = createNodeFetch();
-        const baseSseFetch = baseFetch;
-        // Normal HTTP calls: apply requestTimeoutSeconds.
-        this.fetch = createTimedFetch({
+        this._fetch = null;
+        this._sseFetch = null;
+        this._closeTransport = async () => { };
+        this._transportInitialized = false;
+    }
+    get fetch() {
+        return this._fetch ?? fetch;
+    }
+    get sseFetch() {
+        return this._sseFetch ?? fetch;
+    }
+    getBaseUrl() {
+        // If `domain` already contains a scheme, treat it as a full base URL prefix.
+        if (this.domain.startsWith("http://") ||
+            this.domain.startsWith("https://")) {
+            return `${stripV1Suffix(this.domain)}/v1`;
+        }
+        return `${this.protocol}://${stripV1Suffix(this.domain)}/v1`;
+    }
+    initializeTransport() {
+        if (this._transportInitialized)
+            return;
+        const { fetch: baseFetch, close } = createNodeFetch();
+        this._fetch = createTimedFetch({
             baseFetch,
             timeoutSeconds: this.requestTimeoutSeconds,
             debug: this.debug,
             defaultHeaders: this.headers,
             label: "http",
         });
-        // Streaming calls (SSE): do not apply SDK-side timeouts; do not proactively disconnect.
-        this.sseFetch = createTimedFetch({
-            baseFetch: baseSseFetch,
+        this._sseFetch = createTimedFetch({
+            baseFetch,
             timeoutSeconds: 0,
             debug: this.debug,
             defaultHeaders: this.headers,
             label: "sse",
         });
+        this._closeTransport = close;
+        this._transportInitialized = true;
     }
-    getBaseUrl() {
-        // If `domain` already contains a scheme, treat it as a full base URL prefix.
-        if (this.domain.startsWith("http://") ||
-            this.domain.startsWith("https://")) {
-            return `${stripV1Suffix(this.domain)}/v1`;
+    /**
+     * Ensure this configuration has transport helpers (fetch/SSE) allocated.
+     *
+     * On Node.js this creates a dedicated `undici` dispatcher; on browsers it
+     * simply reuses the global fetch. Returns either `this` or a cloned config
+     * with the transport initialized.
+     */
+    withTransportIfMissing() {
+        if (this._transportInitialized) {
+            return this;
         }
-        return `${this.protocol}://${stripV1Suffix(this.domain)}/v1`;
+        const clone = new ConnectionConfig({
+            domain: this.domain,
+            protocol: this.protocol,
+            apiKey: this.apiKey,
+            headers: { ...this.headers },
+            requestTimeoutSeconds: this.requestTimeoutSeconds,
+            debug: this.debug,
+        });
+        clone.initializeTransport();
+        return clone;
+    }
+    /**
+     * Close the Node.js agent owned by this configuration.
+     */
+    async closeTransport() {
+        if (!this._transportInitialized)
+            return;
+        this._closePromise ??= this._closeTransport();
+        await this._closePromise;
     }
 }

package/dist/factory/defaultAdapterFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaultAdapterFactory.d.ts","sourceRoot":"","sources":["../../src/factory/defaultAdapterFactory.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE5I,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc;IAWvE,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU;CA4B5D;AAED,wBAAgB,2BAA2B,IAAI,cAAc,CAE5D"}
+{"version":3,"file":"defaultAdapterFactory.d.ts","sourceRoot":"","sources":["../../src/factory/defaultAdapterFactory.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE5I,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc;IAWvE,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,UAAU;CA2B5D;AAED,wBAAgB,2BAA2B,IAAI,cAAc,CAE5D"}

package/dist/factory/defaultAdapterFactory.js

@@ -44,7 +44,6 @@ export class DefaultAdapterFactory {
         });
         const commands = new CommandsAdapter(execdClient, {
             baseUrl: opts.execdBaseUrl,
-            // Streaming calls (SSE) use a dedicated fetch, aligned with Kotlin/Python SDKs.
             fetch: opts.connectionConfig.sseFetch,
             headers: opts.connectionConfig.headers,
         });

package/dist/manager.d.ts

@@ -18,6 +18,7 @@ export interface SandboxFilter {
  */
 export declare class SandboxManager {
     private readonly sandboxes;
+    private readonly connectionConfig;
     private constructor();
     static create(opts?: SandboxManagerOptions): SandboxManager;
     listSandboxInfos(filter?: SandboxFilter): Promise<ListSandboxesResponse>;
@@ -30,10 +31,11 @@ export declare class SandboxManager {
      */
     renewSandbox(sandboxId: SandboxId, timeoutSeconds: number): Promise<void>;
     /**
-     * No-op for now (fetch-based implementation doesn't own a pooled transport).
+     * Release the HTTP agent resources allocated for this manager instance.
      *
-     * This method exists so callers can consistently release resources when using
-     * a custom {@link AdapterFactory} implementation.
+     * Each manager clone owns a scoped `ConnectionConfig` clone.
+     *
+     * This mirrors the Python SDK's default transport lifecycle.
      */
     close(): Promise<void>;
 }

package/dist/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAExF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAG3F,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IAC9D,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,OAAO;IAIP,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,qBAA0B,GAAG,cAAc;IAU/D,gBAAgB,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAS5E,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAI1D,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/E;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAExF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAG3F,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IAC9D,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD,OAAO;IAKP,MAAM,CAAC,MAAM,CAAC,IAAI,GAAE,qBAA0B,GAAG,cAAc;IAoB/D,gBAAgB,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAS5E,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAI1D,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/E;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/manager.js

@@ -20,17 +20,30 @@ import { createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js"
  */
 export class SandboxManager {
     sandboxes;
+    connectionConfig;
     constructor(opts) {
         this.sandboxes = opts.sandboxes;
+        this.connectionConfig = opts.connectionConfig;
     }
     static create(opts = {}) {
-        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+        const baseConnectionConfig = opts.connectionConfig instanceof ConnectionConfig
             ? opts.connectionConfig
             : new ConnectionConfig(opts.connectionConfig);
+        const connectionConfig = baseConnectionConfig.withTransportIfMissing();
         const lifecycleBaseUrl = connectionConfig.getBaseUrl();
         const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
-        const { sandboxes } = adapterFactory.createLifecycleStack({ connectionConfig, lifecycleBaseUrl });
-        return new SandboxManager({ sandboxes });
+        let sandboxes;
+        try {
+            sandboxes = adapterFactory.createLifecycleStack({
+                connectionConfig,
+                lifecycleBaseUrl,
+            }).sandboxes;
+        }
+        catch (err) {
+            void connectionConfig.closeTransport().catch(() => undefined);
+            throw err;
+        }
+        return new SandboxManager({ sandboxes, connectionConfig });
     }
     listSandboxInfos(filter = {}) {
         return this.sandboxes.listSandboxes({
@@ -60,12 +73,13 @@ export class SandboxManager {
         await this.sandboxes.renewSandboxExpiration(sandboxId, { expiresAt });
     }
     /**
-     * No-op for now (fetch-based implementation doesn't own a pooled transport).
+     * Release the HTTP agent resources allocated for this manager instance.
      *
-     * This method exists so callers can consistently release resources when using
-     * a custom {@link AdapterFactory} implementation.
+     * Each manager clone owns a scoped `ConnectionConfig` clone.
+     *
+     * This mirrors the Python SDK's default transport lifecycle.
      */
     async close() {
-        // no-op
+        await this.connectionConfig.closeTransport();
     }
 }

package/dist/sandbox.d.ts

@@ -111,6 +111,10 @@ export declare class Sandbox {
      */
     static resume(opts: SandboxConnectOptions): Promise<Sandbox>;
     kill(): Promise<void>;
+    /**
+     * Release any client-side resources (e.g. Node.js HTTP agents) owned by this Sandbox instance.
+     */
+    close(): Promise<void>;
     /**
      * Renew expiration by setting expiresAt to now + timeoutSeconds.
      */

package/dist/sandbox.d.ts.map

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

package/dist/sandbox.js

@@ -61,15 +61,23 @@ export class Sandbox {
         this.metrics = opts.metrics;
     }
     static async create(opts) {
-        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+        const baseConnectionConfig = opts.connectionConfig instanceof ConnectionConfig
             ? opts.connectionConfig
             : new ConnectionConfig(opts.connectionConfig);
+        const connectionConfig = baseConnectionConfig.withTransportIfMissing();
         const lifecycleBaseUrl = connectionConfig.getBaseUrl();
         const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
-        const { sandboxes } = adapterFactory.createLifecycleStack({
-            connectionConfig,
-            lifecycleBaseUrl,
-        });
+        let sandboxes;
+        try {
+            sandboxes = adapterFactory.createLifecycleStack({
+                connectionConfig,
+                lifecycleBaseUrl,
+            }).sandboxes;
+        }
+        catch (err) {
+            await connectionConfig.closeTransport();
+            throw err;
+        }
         const req = {
             image: toImageSpec(opts.image),
             entrypoint: opts.entrypoint ?? DEFAULT_ENTRYPOINT,
@@ -120,46 +128,61 @@ export class Sandbox {
                     // Ignore cleanup failure; surface original error.
                 }
             }
+            await connectionConfig.closeTransport();
             throw err;
         }
     }
     static async connect(opts) {
-        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+        const baseConnectionConfig = opts.connectionConfig instanceof ConnectionConfig
             ? opts.connectionConfig
             : new ConnectionConfig(opts.connectionConfig);
+        const connectionConfig = baseConnectionConfig.withTransportIfMissing();
         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,
+        let sandboxes;
+        try {
+            sandboxes = adapterFactory.createLifecycleStack({
+                connectionConfig,
+                lifecycleBaseUrl,
+            }).sandboxes;
+        }
+        catch (err) {
+            await connectionConfig.closeTransport();
+            throw err;
+        }
+        try {
+            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;
+        }
+        catch (err) {
+            await connectionConfig.closeTransport();
+            throw err;
         }
-        return sbx;
     }
     async getInfo() {
         return await this.sandboxes.getSandbox(this.id);
@@ -199,21 +222,36 @@ export class Sandbox {
      * Resume a paused sandbox by id, then connect to its execd endpoint.
      */
     static async resume(opts) {
-        const connectionConfig = opts.connectionConfig instanceof ConnectionConfig
+        const baseConnectionConfig = 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 });
+        const resumeConnectionConfig = baseConnectionConfig.withTransportIfMissing();
+        const lifecycleBaseUrl = resumeConnectionConfig.getBaseUrl();
+        let sandboxes;
+        try {
+            sandboxes = adapterFactory.createLifecycleStack({
+                connectionConfig: resumeConnectionConfig,
+                lifecycleBaseUrl,
+            }).sandboxes;
+            await sandboxes.resumeSandbox(opts.sandboxId);
+        }
+        catch (err) {
+            await resumeConnectionConfig.closeTransport();
+            throw err;
+        }
+        await resumeConnectionConfig.closeTransport();
+        return await Sandbox.connect({ ...opts, connectionConfig: baseConnectionConfig, adapterFactory });
     }
     async kill() {
         await this.sandboxes.deleteSandbox(this.id);
     }
+    /**
+     * Release any client-side resources (e.g. Node.js HTTP agents) owned by this Sandbox instance.
+     */
+    async close() {
+        await this.connectionConfig.closeTransport();
+    }
     /**
      * Renew expiration by setting expiresAt to now + timeoutSeconds.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alibaba-group/opensandbox",
-  "version": "0.1.0-dev3",
+  "version": "0.1.0-dev4",
   "description": "OpenSandbox TypeScript/JavaScript SDK (sandbox lifecycle + execd APIs)",
   "license": "Apache-2.0",
   "type": "module",