@alibaba-group/opensandbox 0.1.4 → 0.1.6

package/src/api/execd.ts

@@ -17,6 +17,13 @@
  * Do not make direct changes to the file.
  */
 
+
+/**
+ * NOTE: The session-related path types and operations in this file (e.g. /session, runInSession)
+ * are generated from the execd OpenAPI spec. They are not the recommended runtime entry point.
+ * Use `sandbox.commands.createSession()`, `sandbox.commands.runInSession()`, and
+ * `sandbox.commands.deleteSession()` instead.
+ */
 export interface paths {
     "/ping": {
         parameters: {
@@ -143,6 +150,71 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/session": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create bash session (create_session)
+         * @description Creates a new bash session and returns a session ID for subsequent run_in_session requests.
+         *     The session maintains shell state (e.g. working directory, environment) across multiple
+         *     code executions. Request body is optional; an empty body uses default options (no cwd override).
+         */
+        post: operations["createSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/session/{sessionId}/run": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run command in bash session (run_in_session)
+         * @description Executes a shell command in an existing bash session and streams the output in real-time via SSE
+         *     (Server-Sent Events). The session must have been created by create_session. Supports
+         *     optional working directory override and timeout (milliseconds).
+         */
+        post: operations["runInSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/session/{sessionId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /**
+         * Delete bash session (delete_session)
+         * @description Deletes an existing bash session by ID. Terminates the underlying shell process
+         *     and releases resources. The session ID must have been returned by create_session.
+         */
+        delete: operations["deleteSession"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/command": {
         parameters: {
             query?: never;
@@ -158,7 +230,8 @@ export interface paths {
          *     The command can run in foreground or background mode. The response includes stdout, stderr,
          *     execution status, and completion events.
          *     Optionally specify `timeout` (milliseconds) to enforce a maximum runtime; the server will
-         *     terminate the process when the timeout is reached.
+         *     terminate the process when the timeout is reached. You can also pass `uid`/`gid` to run
+         *     with specific user/group IDs, and `envs` to inject environment variables.
          */
         post: operations["runCommand"];
         /**
@@ -471,6 +544,41 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /** @description Request to create a bash session (optional body; empty treated as defaults) */
+        CreateSessionRequest: {
+            /**
+             * @description Working directory for the session (optional)
+             * @example /workspace
+             */
+            cwd?: string;
+        };
+        /** @description Response for create_session */
+        CreateSessionResponse: {
+            /**
+             * @description Unique session ID for run_in_session and delete_session
+             * @example session-abc123
+             */
+            session_id: string;
+        };
+        /** @description Request to run a command in an existing bash session */
+        RunInSessionRequest: {
+            /**
+             * @description Shell command to execute in the session
+             * @example echo "Hello"
+             */
+            command: string;
+            /**
+             * @description Working directory override for this run (optional)
+             * @example /workspace
+             */
+            cwd?: string;
+            /**
+             * Format: int64
+             * @description Maximum execution time in milliseconds (optional; server may not enforce if omitted)
+             * @example 30000
+             */
+            timeout?: number;
+        };
         /** @description Request to create a code execution context */
         CodeContextRequest: {
             /**
@@ -527,6 +635,28 @@ export interface components {
              * @example 60000
              */
             timeout?: number;
+            /**
+             * Format: int32
+             * @description Unix user ID used to run the command. If `gid` is provided, `uid` is required.
+             * @example 1000
+             */
+            uid?: number;
+            /**
+             * Format: int32
+             * @description Unix group ID used to run the command. Requires `uid` to be provided.
+             * @example 1000
+             */
+            gid?: number;
+            /**
+             * @description Environment variables injected into the command process.
+             * @example {
+             *       "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+             *       "PYTHONUNBUFFERED": "1"
+             *     }
+             */
+            envs?: {
+                [key: string]: string;
+            };
         };
         /** @description Command execution status (foreground or background) */
         CommandStatusResponse: {
@@ -1046,6 +1176,91 @@ export interface operations {
             500: components["responses"]["InternalServerError"];
         };
     };
+    createSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["CreateSessionRequest"];
+            };
+        };
+        responses: {
+            /** @description Session created successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateSessionResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            500: components["responses"]["InternalServerError"];
+        };
+    };
+    runInSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /**
+                 * @description Session ID returned by create_session
+                 * @example session-abc123
+                 */
+                sessionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RunInSessionRequest"];
+            };
+        };
+        responses: {
+            /** @description Stream of execution events */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": components["schemas"]["ServerStreamEvent"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            500: components["responses"]["InternalServerError"];
+        };
+    };
+    deleteSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /**
+                 * @description Session ID to delete
+                 * @example session-abc123
+                 */
+                sessionId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Session deleted successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            400: components["responses"]["BadRequest"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalServerError"];
+        };
+    };
     runCommand: {
         parameters: {
             query?: never;

package/src/api/lifecycle.ts

@@ -470,9 +470,9 @@ export interface components {
             };
             /**
              * Format: date-time
-             * @description Timestamp when sandbox will auto-terminate
+             * @description Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
              */
-            expiresAt: string;
+            expiresAt?: string;
             /**
              * Format: date-time
              * @description Sandbox creation timestamp
@@ -503,9 +503,9 @@ export interface components {
             entrypoint: string[];
             /**
              * Format: date-time
-             * @description Timestamp when sandbox will auto-terminate
+             * @description Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
              */
-            expiresAt: string;
+            expiresAt?: string;
             /**
              * Format: date-time
              * @description Sandbox creation timestamp
@@ -588,9 +588,12 @@ export interface components {
             image: components["schemas"]["ImageSpec"];
             /**
              * @description Sandbox timeout in seconds. The sandbox will automatically terminate after this duration.
-             *     SDK clients should provide a default value (e.g., 3600 seconds / 1 hour).
+             *     The maximum is controlled by the server configuration (`server.max_sandbox_timeout_seconds`).
+             *     Omit this field or set it to null to disable automatic expiration and require explicit cleanup.
+             *     Note: manual cleanup support is runtime-dependent; Kubernetes providers may reject
+             *     omitted or null timeout when the underlying workload provider does not support non-expiring sandboxes.
              */
-            timeout: number;
+            timeout?: number | null;
             /**
              * @description Runtime resource constraints for the sandbox instance.
              *     SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi").
@@ -659,6 +662,9 @@ export interface components {
              *     **Best Practices**:
              *     - **Namespacing**: Use prefixed keys (e.g., `storage.id`) to prevent collisions.
              *     - **Pass-through**: SDKs and middleware must treat this object as opaque and pass it through transparently.
+             *
+             *     **Well-known keys**:
+             *     - `access.renew.extend.seconds` (optional): Decimal integer string from **300** to **86400** (5 minutes to 24 hours inclusive). Opts the sandbox into OSEP-0009 renew-on-access and sets per-renewal extension seconds. Omit to disable. Invalid values are rejected at creation with HTTP 400 (validated on the lifecycle create endpoint via `validate_extensions` in server `src/extensions/validation.py`).
              */
             extensions?: {
                 [key: string]: string;
@@ -758,7 +764,7 @@ export interface components {
         /**
          * @description Storage mount definition for a sandbox. Each volume entry contains:
          *     - A unique name identifier
-         *     - Exactly one backend struct (host, pvc, etc.) with backend-specific fields
+         *     - Exactly one backend struct (host, pvc, ossfs, etc.) with backend-specific fields
          *     - Common mount settings (mountPath, readOnly, subPath)
          */
         Volume: {
@@ -769,6 +775,7 @@ export interface components {
             name: string;
             host?: components["schemas"]["Host"];
             pvc?: components["schemas"]["PVC"];
+            ossfs?: components["schemas"]["OSSFS"];
             /**
              * @description Absolute path inside the container where the volume is mounted.
              *     Must start with '/'.
@@ -781,6 +788,7 @@ export interface components {
             readOnly: boolean;
             /**
              * @description Optional subdirectory under the backend path to mount.
+             *     For `ossfs` backend, this field is used as the bucket prefix.
              *     Must be a relative path without '..' components.
              */
             subPath?: string;
@@ -795,23 +803,61 @@ export interface components {
         Host: {
             /**
              * @description Absolute path on the host filesystem to mount.
-             *     Must start with '/' and be under an allowed prefix.
+             *     Must start with '/' (Unix) or a drive letter such as 'C:\' or 'D:/'
+             *     (Windows), and be under an allowed prefix.
              */
             path: string;
         };
         /**
-         * @description Kubernetes PersistentVolumeClaim mount backend. References an existing
-         *     PVC in the same namespace as the sandbox pod.
+         * @description Platform-managed named volume backend. A runtime-neutral abstraction
+         *     for referencing a pre-existing, platform-managed named volume.
+         *
+         *     - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
+         *     - Docker: maps to a Docker named volume (created via `docker volume create`).
          *
-         *     Only available in Kubernetes runtime.
+         *     The volume must already exist on the target platform before sandbox
+         *     creation.
          */
         PVC: {
             /**
-             * @description Name of the PersistentVolumeClaim in the same namespace.
-             *     Must be a valid Kubernetes resource name.
+             * @description Name of the volume on the target platform.
+             *     In Kubernetes this is the PVC name; in Docker this is the named
+             *     volume name. Must be a valid DNS label.
              */
             claimName: string;
         };
+        /**
+         * @description Alibaba Cloud OSS mount backend via ossfs.
+         *
+         *     The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
+         *     and bind-mounts the resolved path into the sandbox container.
+         *     Prefix selection is expressed via `Volume.subPath`.
+         *     In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
+         */
+        OSSFS: {
+            /** @description OSS bucket name. */
+            bucket: string;
+            /** @description OSS endpoint (e.g., `oss-cn-hangzhou.aliyuncs.com`). */
+            endpoint: string;
+            /**
+             * @description ossfs major version used by runtime mount integration.
+             * @default 2.0
+             * @enum {string}
+             */
+            version: "1.0" | "2.0";
+            /**
+             * @description Additional ossfs mount options.
+             *     Runtime encodes options by `version`:
+             *     - `1.0`: mounts with `ossfs ... -o <option>`
+             *     - `2.0`: mounts with `ossfs2 mount ... -c <config-file>` and encodes options as `--<option>` lines in the config file
+             *     Option values must be provided as raw payloads without leading `-`.
+             */
+            options?: string[];
+            /** @description OSS access key ID for inline credentials mode. */
+            accessKeyId: string;
+            /** @description OSS access key secret for inline credentials mode. */
+            accessKeySecret: string;
+        };
     };
     responses: {
         /** @description Error response envelope */

package/src/core/constants.ts

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 export const DEFAULT_EXECD_PORT = 44772;
+export const DEFAULT_EGRESS_PORT = 18080;
 
 export const DEFAULT_ENTRYPOINT: string[] = ["tail", "-f", "/dev/null"];
 
@@ -26,4 +27,4 @@ export const DEFAULT_READY_TIMEOUT_SECONDS = 30;
 export const DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS = 200;
 
 export const DEFAULT_REQUEST_TIMEOUT_SECONDS = 30;
-export const DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.4";
+export const DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.6";

package/src/core/exceptions.ts

@@ -44,6 +44,7 @@ interface SandboxExceptionOpts {
   message?: string;
   cause?: unknown;
   error?: SandboxError;
+  requestId?: string;
 }
 
 /**
@@ -55,32 +56,32 @@ export class SandboxException extends Error {
   readonly name: string = "SandboxException";
   readonly error: SandboxError;
   readonly cause?: unknown;
+  readonly requestId?: string;
 
   constructor(opts: SandboxExceptionOpts = {}) {
     super(opts.message);
     this.cause = opts.cause;
     this.error = opts.error ?? new SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR);
+    this.requestId = opts.requestId;
   }
 }
 
 export class SandboxApiException extends SandboxException {
   readonly name: string = "SandboxApiException";
   readonly statusCode?: number;
-  readonly requestId?: string;
   readonly rawBody?: unknown;
 
   constructor(opts: SandboxExceptionOpts & {
     statusCode?: number;
-    requestId?: string;
     rawBody?: unknown;
   }) {
     super({
       message: opts.message,
       cause: opts.cause,
       error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message),
+      requestId: opts.requestId,
     });
     this.statusCode = opts.statusCode;
-    this.requestId = opts.requestId;
     this.rawBody = opts.rawBody;
   }
 }
@@ -131,4 +132,4 @@ export class InvalidArgumentException extends SandboxException {
       error: new SandboxError(SandboxError.INVALID_ARGUMENT, opts.message),
     });
   }
-}
+}

package/src/factory/adapterFactory.ts

@@ -14,6 +14,7 @@
 
 import type { ConnectionConfig } from "../config/connection.js";
 import type { SandboxFiles } from "../services/filesystem.js";
+import type { Egress } from "../services/egress.js";
 import type { ExecdCommands } from "../services/execdCommands.js";
 import type { ExecdHealth } from "../services/execdHealth.js";
 import type { ExecdMetrics } from "../services/execdMetrics.js";
@@ -41,6 +42,16 @@ export interface ExecdStack {
   metrics: ExecdMetrics;
 }
 
+export interface CreateEgressStackOptions {
+  connectionConfig: ConnectionConfig;
+  egressBaseUrl: string;
+  endpointHeaders?: Record<string, string>;
+}
+
+export interface EgressStack {
+  egress: Egress;
+}
+
 /**
  * Factory abstraction to keep `Sandbox` and `SandboxManager` decoupled from concrete adapter implementations.
  *
@@ -49,4 +60,5 @@ export interface ExecdStack {
 export interface AdapterFactory {
   createLifecycleStack(opts: CreateLifecycleStackOptions): LifecycleStack;
   createExecdStack(opts: CreateExecdStackOptions): ExecdStack;
-}
+  createEgressStack(opts: CreateEgressStackOptions): EgressStack;
+}

package/src/factory/defaultAdapterFactory.ts

@@ -13,15 +13,25 @@
 // limitations under the License.
 
 import { createExecdClient } from "../openapi/execdClient.js";
+import { createEgressClient } from "../openapi/egressClient.js";
 import { createLifecycleClient } from "../openapi/lifecycleClient.js";
 
 import { CommandsAdapter } from "../adapters/commandsAdapter.js";
+import { EgressAdapter } from "../adapters/egressAdapter.js";
 import { FilesystemAdapter } from "../adapters/filesystemAdapter.js";
 import { HealthAdapter } from "../adapters/healthAdapter.js";
 import { MetricsAdapter } from "../adapters/metricsAdapter.js";
 import { SandboxesAdapter } from "../adapters/sandboxesAdapter.js";
 
-import type { AdapterFactory, CreateExecdStackOptions, CreateLifecycleStackOptions, ExecdStack, LifecycleStack } from "./adapterFactory.js";
+import type {
+  AdapterFactory,
+  CreateEgressStackOptions,
+  CreateExecdStackOptions,
+  CreateLifecycleStackOptions,
+  EgressStack,
+  ExecdStack,
+  LifecycleStack,
+} from "./adapterFactory.js";
 
 export class DefaultAdapterFactory implements AdapterFactory {
   createLifecycleStack(opts: CreateLifecycleStackOptions): LifecycleStack {
@@ -66,8 +76,23 @@ export class DefaultAdapterFactory implements AdapterFactory {
       metrics,
     };
   }
+
+  createEgressStack(opts: CreateEgressStackOptions): EgressStack {
+    const headers: Record<string, string> = {
+      ...(opts.connectionConfig.headers ?? {}),
+      ...(opts.endpointHeaders ?? {}),
+    };
+    const egressClient = createEgressClient({
+      baseUrl: opts.egressBaseUrl,
+      headers,
+      fetch: opts.connectionConfig.fetch,
+    });
+    return {
+      egress: new EgressAdapter(egressClient),
+    };
+  }
 }
 
 export function createDefaultAdapterFactory(): AdapterFactory {
   return new DefaultAdapterFactory();
-}
+}

package/src/index.ts

@@ -39,6 +39,7 @@ export type {
   NetworkPolicy,
   NetworkRule,
   NetworkRuleAction,
+  OSSFS,
   PVC,
   RenewSandboxExpirationRequest,
   RenewSandboxExpirationResponse,
@@ -91,6 +92,7 @@ export { ExecutionEventDispatcher } from "./models/executionEventDispatcher.js";
 
 export {
   DEFAULT_ENTRYPOINT,
+  DEFAULT_EGRESS_PORT,
   DEFAULT_EXECD_PORT,
   DEFAULT_RESOURCE_LIMITS,
   DEFAULT_TIMEOUT_SECONDS,
@@ -112,4 +114,4 @@ export type {
   SetPermissionEntry,
   WriteEntry,
 } from "./models/filesystem.js";
-export type { SandboxFiles } from "./services/filesystem.js";
+export type { SandboxFiles } from "./services/filesystem.js";

package/src/models/execd.ts

@@ -63,6 +63,18 @@ export interface RunCommandOpts {
    * If omitted, the server will not enforce any timeout.
    */
   timeoutSeconds?: number;
+  /**
+   * Unix user ID used to run the command process.
+   */
+  uid?: number;
+  /**
+   * Unix group ID used to run the command process. Requires `uid`.
+   */
+  gid?: number;
+  /**
+   * Environment variables injected into the command process.
+   */
+  envs?: Record<string, string>;
 }
 
 export interface CommandStatus {

package/src/models/execution.ts

@@ -54,6 +54,7 @@ export interface Execution {
   result: ExecutionResult[];
   error?: ExecutionError;
   complete?: ExecutionComplete;
+  exitCode?: number | null;
 }
 
 export interface ExecutionHandlers {
@@ -68,4 +69,4 @@ export interface ExecutionHandlers {
   onExecutionComplete?: (c: ExecutionComplete) => void | Promise<void>;
   onError?: (err: ExecutionError) => void | Promise<void>;
   onInit?: (init: ExecutionInit) => void | Promise<void>;
-}
+}