@alibaba-group/opensandbox 0.1.3 → 0.1.5

package/dist/{sandboxes-CLy12BN1.d.ts → sandboxes-DL9uUHGR.d.ts}

@@ -103,6 +103,246 @@ interface SandboxFiles {
     setPermissions(entries: SetPermissionEntry[]): Promise<void>;
 }
 
+/**
+ * Domain models for sandbox lifecycle.
+ *
+ * IMPORTANT:
+ * - These are NOT OpenAPI-generated types.
+ * - They are intentionally stable and JS-friendly.
+ *
+ * The internal OpenAPI schemas may change frequently; adapters map responses into these models.
+ */
+type SandboxId = string;
+interface ImageAuth extends Record<string, unknown> {
+    username?: string;
+    password?: string;
+    token?: string;
+}
+interface ImageSpec {
+    uri: string;
+    auth?: ImageAuth;
+}
+type ResourceLimits = Record<string, string>;
+type NetworkRuleAction = "allow" | "deny";
+interface NetworkRule extends Record<string, unknown> {
+    /**
+     * Whether to allow or deny matching targets.
+     */
+    action: NetworkRuleAction;
+    /**
+     * FQDN or wildcard domain (e.g., "example.com", "*.example.com").
+     * IP/CIDR is not supported in the egress MVP.
+     */
+    target: string;
+}
+interface NetworkPolicy extends Record<string, unknown> {
+    /**
+     * Default action when no egress rule matches. Defaults to "deny".
+     */
+    defaultAction?: NetworkRuleAction;
+    /**
+     * List of egress rules evaluated in order.
+     */
+    egress?: NetworkRule[];
+}
+/**
+ * Host path bind mount backend.
+ *
+ * Maps a directory on the host filesystem into the container.
+ * Only available when the runtime supports host mounts.
+ */
+interface Host extends Record<string, unknown> {
+    /**
+     * Absolute path on the host filesystem to mount.
+     */
+    path: string;
+}
+/**
+ * Kubernetes PersistentVolumeClaim mount backend.
+ *
+ * References an existing PVC in the same namespace as the sandbox pod.
+ * Only available in Kubernetes runtime.
+ */
+interface PVC extends Record<string, unknown> {
+    /**
+     * Name of the PersistentVolumeClaim in the same namespace.
+     */
+    claimName: string;
+}
+/**
+ * Alibaba Cloud OSS mount backend via ossfs.
+ *
+ * The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
+ * so the container sees the bucket contents at the specified mount path.
+ *
+ * In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
+ */
+interface OSSFS extends Record<string, unknown> {
+    /**
+     * OSS bucket name.
+     */
+    bucket: string;
+    /**
+     * OSS endpoint (e.g., "oss-cn-hangzhou.aliyuncs.com").
+     */
+    endpoint: string;
+    /**
+     * ossfs major version used by runtime mount integration.
+     * @default "2.0"
+     */
+    version?: "1.0" | "2.0";
+    /**
+     * Additional ossfs mount options.
+     *
+     * - `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
+     */
+    options?: string[];
+    /**
+     * OSS access key ID for inline credentials mode.
+     */
+    accessKeyId: string;
+    /**
+     * OSS access key secret for inline credentials mode.
+     */
+    accessKeySecret: string;
+}
+/**
+ * Storage mount definition for a sandbox.
+ *
+ * Each volume entry contains:
+ * - A unique name identifier
+ * - Exactly one backend (host, pvc, ossfs) with backend-specific fields
+ * - Common mount settings (mountPath, readOnly, subPath)
+ */
+interface Volume extends Record<string, unknown> {
+    /**
+     * Unique identifier for the volume within the sandbox.
+     */
+    name: string;
+    /**
+     * Host path bind mount backend (mutually exclusive with pvc, ossfs).
+     */
+    host?: Host;
+    /**
+     * Kubernetes PVC mount backend (mutually exclusive with host, ossfs).
+     */
+    pvc?: PVC;
+    /**
+     * Alibaba Cloud OSSFS mount backend (mutually exclusive with host, pvc).
+     */
+    ossfs?: OSSFS;
+    /**
+     * Absolute path inside the container where the volume is mounted.
+     */
+    mountPath: string;
+    /**
+     * If true, the volume is mounted as read-only. Defaults to false (read-write).
+     */
+    readOnly?: boolean;
+    /**
+     * Optional subdirectory under the backend path to mount.
+     */
+    subPath?: string;
+}
+type SandboxState = "Creating" | "Running" | "Pausing" | "Paused" | "Resuming" | "Deleting" | "Deleted" | "Error" | string;
+interface SandboxStatus extends Record<string, unknown> {
+    state: SandboxState;
+    reason?: string;
+    message?: string;
+}
+interface SandboxInfo extends Record<string, unknown> {
+    id: SandboxId;
+    image: ImageSpec;
+    entrypoint: string[];
+    metadata?: Record<string, string>;
+    status: SandboxStatus;
+    /**
+     * Sandbox creation time.
+     */
+    createdAt: Date;
+    /**
+     * Sandbox expiration time (server-side TTL).
+     */
+    expiresAt: Date | null;
+}
+interface CreateSandboxRequest extends Record<string, unknown> {
+    image: ImageSpec;
+    entrypoint: string[];
+    /**
+     * Timeout in seconds (server semantics).
+     */
+    timeout?: number | null;
+    resourceLimits: ResourceLimits;
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+    /**
+     * Optional outbound network policy for the sandbox.
+     */
+    networkPolicy?: NetworkPolicy;
+    /**
+     * Optional list of volume mounts for persistent storage.
+     */
+    volumes?: Volume[];
+    extensions?: Record<string, unknown>;
+}
+interface CreateSandboxResponse extends Record<string, unknown> {
+    id: SandboxId;
+    status: SandboxStatus;
+    metadata?: Record<string, string>;
+    /**
+     * Sandbox expiration time after creation.
+     */
+    expiresAt: Date | null;
+    /**
+     * Sandbox creation time.
+     */
+    createdAt: Date;
+    entrypoint: string[];
+}
+interface PaginationInfo extends Record<string, unknown> {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasNextPage: boolean;
+}
+interface ListSandboxesResponse extends Record<string, unknown> {
+    items: SandboxInfo[];
+    pagination?: PaginationInfo;
+}
+interface RenewSandboxExpirationRequest {
+    expiresAt: string;
+}
+interface RenewSandboxExpirationResponse extends Record<string, unknown> {
+    /**
+     * Updated expiration time (if the server returns it).
+     */
+    expiresAt?: Date;
+}
+interface Endpoint extends Record<string, unknown> {
+    endpoint: string;
+    /**
+     * Headers that must be included on every request targeting this endpoint
+     * (e.g. when the server requires them for routing or auth). Omit or empty if not required.
+     */
+    headers?: Record<string, string>;
+}
+interface ListSandboxesParams {
+    /**
+     * Filter by lifecycle state (the API supports multiple `state` query params).
+     * Example: `{ states: ["Running", "Paused"] }`
+     */
+    states?: string[];
+    /**
+     * Filter by metadata key-value pairs.
+     * NOTE: This will be encoded to a single `metadata` query parameter as described in the spec.
+     */
+    metadata?: Record<string, string>;
+    page?: number;
+    pageSize?: number;
+}
+
 interface OutputMessage {
     text: string;
     timestamp: number;
@@ -140,6 +380,7 @@ interface Execution {
     result: ExecutionResult[];
     error?: ExecutionError;
     complete?: ExecutionComplete;
+    exitCode?: number | null;
 }
 interface ExecutionHandlers {
     /**
@@ -169,11 +410,6 @@ interface ServerStreamEvent extends Record<string, unknown> {
     results?: Record<string, unknown>;
     error?: Record<string, unknown>;
 }
-interface RunCommandRequest extends Record<string, unknown> {
-    command: string;
-    cwd?: string;
-    background?: boolean;
-}
 interface CodeContextRequest extends Record<string, unknown> {
     language: string;
 }
@@ -187,6 +423,36 @@ interface RunCommandOpts {
      * Run command in detached mode.
      */
     background?: boolean;
+    /**
+     * Maximum execution time in seconds; server will terminate the command when reached.
+     * 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>;
+}
+interface CommandStatus {
+    id?: string;
+    content?: string;
+    running?: boolean;
+    exitCode?: number | null;
+    error?: string;
+    startedAt?: Date;
+    finishedAt?: Date | null;
+}
+interface CommandLogs {
+    content: string;
+    cursor?: number;
 }
 type CommandExecution = Execution;
 interface Metrics extends Record<string, unknown> {
@@ -223,145 +489,41 @@ interface ExecdCommands {
      * Note: Execd spec uses `DELETE /command?id=<sessionId>`.
      */
     interrupt(sessionId: string): Promise<void>;
-}
-
-interface ExecdHealth {
-    ping(): Promise<boolean>;
-}
-
-interface ExecdMetrics {
-    getMetrics(): Promise<SandboxMetrics>;
-}
-
-/**
- * Domain models for sandbox lifecycle.
- *
- * IMPORTANT:
- * - These are NOT OpenAPI-generated types.
- * - They are intentionally stable and JS-friendly.
- *
- * The internal OpenAPI schemas may change frequently; adapters map responses into these models.
- */
-type SandboxId = string;
-interface ImageAuth extends Record<string, unknown> {
-    username?: string;
-    password?: string;
-    token?: string;
-}
-interface ImageSpec {
-    uri: string;
-    auth?: ImageAuth;
-}
-type ResourceLimits = Record<string, string>;
-type NetworkRuleAction = "allow" | "deny";
-interface NetworkRule extends Record<string, unknown> {
-    /**
-     * Whether to allow or deny matching targets.
-     */
-    action: NetworkRuleAction;
     /**
-     * FQDN or wildcard domain (e.g., "example.com", "*.example.com").
-     * IP/CIDR is not supported in the egress MVP.
+     * Get the current running status for a command id.
      */
-    target: string;
-}
-interface NetworkPolicy extends Record<string, unknown> {
+    getCommandStatus(commandId: string): Promise<CommandStatus>;
     /**
-     * Default action when no egress rule matches. Defaults to "deny".
+     * Get background command logs (non-streamed).
      */
-    defaultAction?: NetworkRuleAction;
+    getBackgroundCommandLogs(commandId: string, cursor?: number): Promise<CommandLogs>;
     /**
-     * List of egress rules evaluated in order.
+     * Create a bash session with optional working directory.
+     * Returns session ID for use with runInSession and deleteSession.
      */
-    egress?: NetworkRule[];
-}
-type SandboxState = "Creating" | "Running" | "Pausing" | "Paused" | "Resuming" | "Deleting" | "Deleted" | "Error" | string;
-interface SandboxStatus extends Record<string, unknown> {
-    state: SandboxState;
-    reason?: string;
-    message?: string;
-}
-interface SandboxInfo extends Record<string, unknown> {
-    id: SandboxId;
-    image: ImageSpec;
-    entrypoint: string[];
-    metadata?: Record<string, string>;
-    status: SandboxStatus;
-    /**
-     * Sandbox creation time.
-     */
-    createdAt: Date;
-    /**
-     * Sandbox expiration time (server-side TTL).
-     */
-    expiresAt: Date;
-}
-interface CreateSandboxRequest extends Record<string, unknown> {
-    image: ImageSpec;
-    entrypoint: string[];
-    /**
-     * Timeout in seconds (server semantics).
-     */
-    timeout: number;
-    resourceLimits: ResourceLimits;
-    env?: Record<string, string>;
-    metadata?: Record<string, string>;
-    /**
-     * Optional outbound network policy for the sandbox.
-     */
-    networkPolicy?: NetworkPolicy;
-    extensions?: Record<string, unknown>;
-}
-interface CreateSandboxResponse extends Record<string, unknown> {
-    id: SandboxId;
-    status: SandboxStatus;
-    metadata?: Record<string, string>;
+    createSession(options?: {
+        workingDirectory?: string;
+    }): Promise<string>;
     /**
-     * Sandbox expiration time after creation.
+     * Run a shell command in an existing bash session (SSE stream, same event shape as run).
+     * Optional workingDirectory and timeout apply to this run only; session state (e.g. env) persists.
      */
-    expiresAt: Date;
+    runInSession(sessionId: string, command: string, options?: {
+        workingDirectory?: string;
+        timeout?: number;
+    }, handlers?: ExecutionHandlers, signal?: AbortSignal): Promise<CommandExecution>;
     /**
-     * Sandbox creation time.
+     * Delete a bash session by ID. Frees resources; session ID must have been returned by createSession.
      */
-    createdAt: Date;
-    entrypoint: string[];
+    deleteSession(sessionId: string): Promise<void>;
 }
-interface PaginationInfo extends Record<string, unknown> {
-    page: number;
-    pageSize: number;
-    totalItems: number;
-    totalPages: number;
-    hasNextPage: boolean;
-}
-interface ListSandboxesResponse extends Record<string, unknown> {
-    items: SandboxInfo[];
-    pagination?: PaginationInfo;
-}
-interface RenewSandboxExpirationRequest {
-    expiresAt: string;
-}
-interface RenewSandboxExpirationResponse extends Record<string, unknown> {
-    /**
-     * Updated expiration time (if the server returns it).
-     */
-    expiresAt?: Date;
-}
-interface Endpoint extends Record<string, unknown> {
-    endpoint: string;
+
+interface ExecdHealth {
+    ping(): Promise<boolean>;
 }
-interface ListSandboxesParams {
-    /**
-     * Filter by lifecycle state (the API supports multiple `state` query params).
-     * Example: `{ states: ["Running", "Paused"] }`
-     */
-    states?: string[];
-    /**
-     * Filter by metadata key-value pairs.
-     * NOTE: This will be encoded to a single `metadata` query parameter as described in the spec.
-     */
-    metadata?: Record<string, string>;
-    page?: number;
-    pageSize?: number;
+
+interface ExecdMetrics {
+    getMetrics(): Promise<SandboxMetrics>;
 }
 
 interface Sandboxes {
@@ -372,7 +534,7 @@ interface 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>;
 }
 
-export type { RenewSandboxExpirationRequest as A, ReplaceFileContentItem as B, CodeContextRequest as C, RunCommandOpts as D, ExecdCommands as E, FileInfo as F, RunCommandRequest as G, SearchEntry as H, SearchFilesResponse as I, SetPermissionEntry as J, SupportedLanguage as K, ListSandboxesResponse as L, Metrics as M, NetworkPolicy as N, OutputMessage as O, Permission as P, RenewSandboxExpirationResponse as R, Sandboxes as S, WriteEntry as W, SandboxFiles as a, ExecdHealth as b, ExecdMetrics as c, SandboxId as d, SandboxInfo as e, Execution as f, ExecutionHandlers as g, ServerStreamEvent as h, SandboxMetrics as i, Endpoint as j, CommandExecution as k, ContentReplaceEntry as l, CreateSandboxRequest as m, CreateSandboxResponse as n, ExecutionComplete as o, ExecutionError as p, ExecutionInit as q, ExecutionResult as r, FileMetadata as s, FilesInfoResponse as t, ListSandboxesParams as u, MoveEntry as v, NetworkRule as w, NetworkRuleAction as x, PingResponse as y, RenameFileItem as z };
+export type { OutputMessage as A, Permission as B, CodeContextRequest as C, PingResponse as D, ExecdCommands as E, FileInfo as F, RenameFileItem as G, Host as H, RenewSandboxExpirationRequest as I, ReplaceFileContentItem as J, RunCommandOpts as K, ListSandboxesResponse as L, Metrics as M, NetworkPolicy as N, OSSFS as O, PVC as P, SearchEntry as Q, RenewSandboxExpirationResponse as R, Sandboxes as S, SearchFilesResponse as T, SetPermissionEntry as U, Volume as V, SupportedLanguage as W, WriteEntry as X, NetworkRule as a, SandboxFiles as b, ExecdHealth as c, ExecdMetrics as d, SandboxId as e, SandboxInfo as f, Execution as g, ExecutionHandlers as h, ServerStreamEvent as i, SandboxMetrics as j, Endpoint as k, CommandExecution as l, CommandLogs as m, CommandStatus as n, ContentReplaceEntry as o, CreateSandboxRequest as p, CreateSandboxResponse as q, ExecutionComplete as r, ExecutionError as s, ExecutionInit as t, ExecutionResult as u, FileMetadata as v, FilesInfoResponse as w, ListSandboxesParams as x, MoveEntry as y, NetworkRuleAction as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alibaba-group/opensandbox",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "OpenSandbox TypeScript/JavaScript SDK (sandbox lifecycle + execd APIs)",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,7 @@
   "bugs": {
     "url": "https://github.com/alibaba/OpenSandbox/issues"
   },
-  "homepage": "https://github.com/alibaba/OpenSandbox",
+  "homepage": "https://open-sandbox.ai",
   "files": [
     "dist",
     "src"
@@ -53,6 +53,7 @@
   "scripts": {
     "gen:api": "node ./scripts/generate-api.mjs",
     "build": "pnpm run gen:api && tsup",
+    "test": "pnpm run build && node --test tests/*.test.mjs",
     "lint": "eslint src scripts --max-warnings 0",
     "clean": "rm -rf dist"
   }