@alibaba-group/opensandbox 0.1.3 → 0.1.5

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
 import { Client } from 'openapi-fetch';
-import { S as Sandboxes, m as CreateSandboxRequest, n as CreateSandboxResponse, d as SandboxId, e as SandboxInfo, u as ListSandboxesParams, L as ListSandboxesResponse, A 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, J as SetPermissionEntry, v as MoveEntry, l as ContentReplaceEntry, H as SearchEntry, I as SearchFilesResponse, E as ExecdCommands, D as RunCommandOpts, h as ServerStreamEvent, g as ExecutionHandlers, k as CommandExecution } from './sandboxes-CLy12BN1.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-DL9uUHGR.js';
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -382,7 +382,10 @@ interface paths$1 {
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    /** @description Whether to return a server-proxied URL */
+                    use_server_proxy?: boolean;
+                };
                 header?: never;
                 path: {
                     /** @description Unique sandbox identifier */
@@ -454,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
@@ -487,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
@@ -572,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").
@@ -629,6 +635,12 @@ interface components$1 {
              *     the sidecar starts in allow-all mode until updated.
              */
             networkPolicy?: components$1["schemas"]["NetworkPolicy"];
+            /**
+             * @description Storage mounts for the sandbox. Each volume entry specifies a named backend-specific
+             *     storage source and common mount settings. Exactly one backend type must be specified
+             *     per volume entry.
+             */
+            volumes?: components$1["schemas"]["Volume"][];
             /**
              * @description Opaque container for provider-specific or transient parameters not supported by the core API.
              *
@@ -637,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;
@@ -702,6 +717,10 @@ interface components$1 {
              *     Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
              */
             endpoint: string;
+            /** @description Requests targeting the sandbox must include the corresponding header(s). */
+            headers?: {
+                [key: string]: string;
+            };
         };
         /**
          * @description Egress network policy matching the sidecar `/policy` request body.
@@ -729,6 +748,102 @@ interface components$1 {
              */
             target: string;
         };
+        /**
+         * @description Storage mount definition for a sandbox. Each volume entry contains:
+         *     - A unique name identifier
+         *     - Exactly one backend struct (host, pvc, ossfs, etc.) with backend-specific fields
+         *     - Common mount settings (mountPath, readOnly, subPath)
+         */
+        Volume: {
+            /**
+             * @description Unique identifier for the volume within the sandbox.
+             *     Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
+             */
+            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 '/'.
+             */
+            mountPath: string;
+            /**
+             * @description If true, the volume is mounted as read-only. Defaults to false (read-write).
+             * @default false
+             */
+            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;
+        };
+        /**
+         * @description Host path bind mount backend. Maps a directory on the host filesystem
+         *     into the container. Only available when the runtime supports host mounts.
+         *
+         *     Security note: Host paths are restricted by server-side allowlist.
+         *     Users must specify paths under permitted prefixes.
+         */
+        Host: {
+            /**
+             * @description Absolute path on the host filesystem to mount.
+             *     Must start with '/' and be under an allowed prefix.
+             */
+            path: string;
+        };
+        /**
+         * @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`).
+         *
+         *     The volume must already exist on the target platform before sandbox
+         *     creation.
+         */
+        PVC: {
+            /**
+             * @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 */
@@ -847,6 +962,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: {
@@ -973,6 +1094,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;
@@ -987,6 +1173,9 @@ interface paths {
          * @description Executes a shell command and streams the output in real-time using SSE (Server-Sent Events).
          *     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. You can also pass `uid`/`gid` to run
+         *     with specific user/group IDs, and `envs` to inject environment variables.
          */
         post: operations["runCommand"];
         /**
@@ -1298,6 +1487,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: {
             /**
@@ -1348,6 +1572,34 @@ interface components {
              * @example false
              */
             background: boolean;
+            /**
+             * Format: int64
+             * @description Maximum allowed execution time in milliseconds before the command is forcefully terminated by the server. If omitted, the server will not enforce any timeout.
+             * @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: {
@@ -1866,6 +2118,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;
@@ -2423,6 +2760,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>;
@@ -2431,7 +2769,7 @@ declare class SandboxesAdapter implements Sandboxes {
     pauseSandbox(sandboxId: SandboxId): Promise<void>;
     resumeSandbox(sandboxId: SandboxId): Promise<void>;
     renewSandboxExpiration(sandboxId: SandboxId, req: RenewSandboxExpirationRequest): Promise<RenewSandboxExpirationResponse>;
-    getSandboxEndpoint(sandboxId: SandboxId, port: number): Promise<Endpoint>;
+    getSandboxEndpoint(sandboxId: SandboxId, port: number, useServerProxy?: boolean): Promise<Endpoint>;
 }
 
 declare class HealthAdapter implements ExecdHealth {
@@ -2508,9 +2846,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;
+        timeout?: number;
+    }, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
+    runInSession(sessionId: string, command: string, options?: {
+        workingDirectory?: string;
+        timeout?: 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-4EF4ODU2.js";
+} from "./chunk-XHEWHFQ6.js";
 export {
   CommandsAdapter,
   FilesystemAdapter,