@alibaba-group/opensandbox 0.1.4 → 0.1.6

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
 import { Client } from 'openapi-fetch';
-import { S as Sandboxes, o as CreateSandboxRequest, p as CreateSandboxResponse, d as SandboxId, e as SandboxInfo, w as ListSandboxesParams, L as ListSandboxesResponse, G as RenewSandboxExpirationRequest, R as RenewSandboxExpirationResponse, j as Endpoint, b as ExecdHealth, c as ExecdMetrics, i as SandboxMetrics, a as SandboxFiles, F as FileInfo, W as WriteEntry, T as SetPermissionEntry, x as MoveEntry, n as ContentReplaceEntry, K as SearchEntry, Q as SearchFilesResponse, E as ExecdCommands, m as CommandStatus, l as CommandLogs, J as RunCommandOpts, h as ServerStreamEvent, g as ExecutionHandlers, k as CommandExecution } from './sandboxes-Dc0G4ShU.js';
+import { S as Sandboxes, p as CreateSandboxRequest, q as CreateSandboxResponse, e as SandboxId, f as SandboxInfo, x as ListSandboxesParams, L as ListSandboxesResponse, I as RenewSandboxExpirationRequest, R as RenewSandboxExpirationResponse, k as Endpoint, c as ExecdHealth, d as ExecdMetrics, j as SandboxMetrics, b as SandboxFiles, F as FileInfo, X as WriteEntry, U as SetPermissionEntry, y as MoveEntry, o as ContentReplaceEntry, Q as SearchEntry, T as SearchFilesResponse, E as ExecdCommands, n as CommandStatus, m as CommandLogs, K as RunCommandOpts, i as ServerStreamEvent, h as ExecutionHandlers, l as CommandExecution } from './sandboxes-C-AZxcv6.js';
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -457,9 +457,9 @@ interface components$1 {
             };
             /**
              * 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
@@ -490,9 +490,9 @@ interface components$1 {
             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
@@ -575,9 +575,12 @@ interface components$1 {
             image: components$1["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").
@@ -646,6 +649,9 @@ interface components$1 {
              *     **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;
@@ -745,7 +751,7 @@ interface components$1 {
         /**
          * @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: {
@@ -756,6 +762,7 @@ interface components$1 {
             name: string;
             host?: components$1["schemas"]["Host"];
             pvc?: components$1["schemas"]["PVC"];
+            ossfs?: components$1["schemas"]["OSSFS"];
             /**
              * @description Absolute path inside the container where the volume is mounted.
              *     Must start with '/'.
@@ -768,6 +775,7 @@ interface components$1 {
             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;
@@ -782,23 +790,61 @@ interface components$1 {
         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.
          *
-         *     Only available in Kubernetes runtime.
+         *     - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
+         *     - Docker: maps to a Docker named volume (created via `docker volume create`).
+         *
+         *     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 */
@@ -917,6 +963,12 @@ declare function createLifecycleClient(opts?: CreateLifecycleClientOptions): Lif
  * This file was auto-generated by openapi-typescript.
  * 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.
+ */
 interface paths {
     "/ping": {
         parameters: {
@@ -1043,6 +1095,71 @@ 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;
@@ -1058,7 +1175,8 @@ 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"];
         /**
@@ -1370,6 +1488,41 @@ interface paths {
 }
 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: {
             /**
@@ -1426,6 +1579,28 @@ 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: {
@@ -1944,6 +2119,91 @@ 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;
@@ -2501,6 +2761,7 @@ declare class SandboxesAdapter implements Sandboxes {
     private readonly client;
     constructor(client: LifecycleClient);
     private parseIsoDate;
+    private parseOptionalIsoDate;
     private mapSandboxInfo;
     createSandbox(req: CreateSandboxRequest): Promise<CreateSandboxResponse>;
     getSandbox(sandboxId: SandboxId): Promise<SandboxInfo>;
@@ -2586,11 +2847,27 @@ declare class CommandsAdapter implements ExecdCommands {
     private readonly opts;
     private readonly fetch;
     constructor(client: ExecdClient, opts: CommandsAdapterOptions);
+    private buildRunStreamSpec;
+    private buildRunInSessionStreamSpec;
+    private streamExecution;
+    private consumeExecutionStream;
     interrupt(sessionId: string): Promise<void>;
     getCommandStatus(commandId: string): Promise<CommandStatus>;
     getBackgroundCommandLogs(commandId: string, cursor?: number): Promise<CommandLogs>;
     runStream(command: string, opts?: RunCommandOpts, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
     run(command: string, opts?: RunCommandOpts, handlers?: ExecutionHandlers, signal?: AbortSignal): Promise<CommandExecution>;
+    createSession(options?: {
+        workingDirectory?: string;
+    }): Promise<string>;
+    runInSessionStream(sessionId: string, command: string, opts?: {
+        workingDirectory?: string;
+        timeoutSeconds?: number;
+    }, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
+    runInSession(sessionId: string, command: string, options?: {
+        workingDirectory?: string;
+        timeoutSeconds?: number;
+    }, handlers?: ExecutionHandlers, signal?: AbortSignal): Promise<CommandExecution>;
+    deleteSession(sessionId: string): Promise<void>;
 }
 
 export { CommandsAdapter, type ExecdClient, type paths as ExecdPaths, FilesystemAdapter, HealthAdapter, type LifecycleClient, type paths$1 as LifecyclePaths, MetricsAdapter, SandboxesAdapter, createExecdClient, createLifecycleClient };

package/dist/internal.js

@@ -6,7 +6,7 @@ import {
   SandboxesAdapter,
   createExecdClient,
   createLifecycleClient
-} from "./chunk-OYTPXLWE.js";
+} from "./chunk-AFWIGM3C.js";
 export {
   CommandsAdapter,
   FilesystemAdapter,