computesdk 1.11.1 → 1.12.0

package/dist/index.d.mts

@@ -1103,25 +1103,64 @@ declare class Terminal {
  * Server - Resource namespace for managed server operations
  */
 
+/**
+ * Options for starting a managed server
+ */
+interface ServerStartOptions {
+    /** Unique server identifier (URL-safe) */
+    slug: string;
+    /** Command to start the server */
+    command: string;
+    /** Working directory (optional) */
+    path?: string;
+    /** Path to .env file relative to path (optional) */
+    env_file?: string;
+    /** Inline environment variables (merged with env_file if both provided) */
+    environment?: Record<string, string>;
+    /**
+     * When to automatically restart the server:
+     * - `never`: No automatic restart (default)
+     * - `on-failure`: Restart only on non-zero exit code
+     * - `always`: Always restart on exit (including exit code 0)
+     */
+    restart_policy?: RestartPolicy;
+    /** Maximum restart attempts (0 = unlimited, default: 0) */
+    max_restarts?: number;
+    /** Delay between restart attempts in milliseconds (default: 1000) */
+    restart_delay_ms?: number;
+    /** Graceful shutdown timeout in milliseconds - SIGTERM → wait → SIGKILL (default: 10000) */
+    stop_timeout_ms?: number;
+}
 /**
  * Server resource namespace
  *
  * @example
  * ```typescript
- * // Start a new server
+ * // Start a basic server
  * const server = await sandbox.server.start({
  *   slug: 'api',
  *   command: 'npm start',
  *   path: '/app',
  * });
  *
+ * // Start with supervisor settings (auto-restart on failure)
+ * const server = await sandbox.server.start({
+ *   slug: 'web',
+ *   command: 'node server.js',
+ *   path: '/app',
+ *   environment: { NODE_ENV: 'production', PORT: '3000' },
+ *   restart_policy: 'on-failure',
+ *   max_restarts: 5,
+ *   restart_delay_ms: 2000,
+ * });
+ *
  * // List all servers
  * const servers = await sandbox.server.list();
  *
  * // Retrieve a specific server
  * const server = await sandbox.server.retrieve('api');
  *
- * // Stop a server
+ * // Stop a server (graceful shutdown with SIGTERM → SIGKILL)
  * await sandbox.server.stop('api');
  *
  * // Restart a server
@@ -1136,12 +1175,7 @@ declare class Server {
     private restartHandler;
     private updateStatusHandler;
     constructor(handlers: {
-        start: (options: {
-            slug: string;
-            command: string;
-            path?: string;
-            env_file?: string;
-        }) => Promise<ServerResponse>;
+        start: (options: ServerStartOptions) => Promise<ServerResponse>;
         list: () => Promise<ServersListResponse>;
         retrieve: (slug: string) => Promise<ServerResponse>;
         stop: (slug: string) => Promise<ServerStopResponse | void>;
@@ -1149,20 +1183,40 @@ declare class Server {
         updateStatus: (slug: string, status: ServerStatus) => Promise<void>;
     });
     /**
-     * Start a new managed server
+     * Start a new managed server with optional supervisor settings
+     *
+     * **Restart Policies:**
+     * - `never` (default): No automatic restart on exit
+     * - `on-failure`: Restart only on non-zero exit code
+     * - `always`: Always restart on exit (including exit code 0)
+     *
+     * **Graceful Shutdown:**
+     * When stopping a server, it first sends SIGTERM and waits for `stop_timeout_ms`
+     * before sending SIGKILL if the process hasn't exited.
+     *
      * @param options - Server configuration
-     * @param options.slug - Unique server slug (URL-safe identifier)
-     * @param options.command - Command to start the server
-     * @param options.path - Working directory (optional)
-     * @param options.env_file - Path to env file (optional)
      * @returns Server info
+     *
+     * @example
+     * ```typescript
+     * // Basic server
+     * const server = await sandbox.server.start({
+     *   slug: 'web',
+     *   command: 'npm run dev',
+     *   path: '/app',
+     * });
+     *
+     * // With supervisor settings
+     * const server = await sandbox.server.start({
+     *   slug: 'api',
+     *   command: 'node server.js',
+     *   environment: { NODE_ENV: 'production' },
+     *   restart_policy: 'always',
+     *   max_restarts: 0, // unlimited
+     * });
+     * ```
      */
-    start(options: {
-        slug: string;
-        command: string;
-        path?: string;
-        env_file?: string;
-    }): Promise<ServerInfo>;
+    start(options: ServerStartOptions): Promise<ServerInfo>;
     /**
      * List all managed servers
      * @returns Array of server info
@@ -2301,23 +2355,61 @@ interface TerminalResponse {
 }
 /**
  * Server status types
+ *
+ * - `starting`: Initial startup of the server process
+ * - `running`: Server process is running
+ * - `ready`: Server is running and ready to accept traffic
+ * - `failed`: Server failed to start or encountered a fatal error
+ * - `stopped`: Server was intentionally stopped
+ * - `restarting`: Server is being automatically restarted by the supervisor
+ */
+type ServerStatus = 'starting' | 'running' | 'ready' | 'failed' | 'stopped' | 'restarting';
+/**
+ * Server restart policy
+ * - `never`: No automatic restart (default)
+ * - `on-failure`: Restart only on non-zero exit code
+ * - `always`: Always restart on exit (including exit code 0)
  */
-type ServerStatus = 'starting' | 'running' | 'ready' | 'failed' | 'stopped';
+type RestartPolicy = 'never' | 'on-failure' | 'always';
 /**
  * Server information
  */
 interface ServerInfo {
+    /** Unique server identifier */
     slug: string;
+    /** Command used to start the server */
     command: string;
+    /** Working directory path */
     path: string;
+    /** Original path before resolution */
     original_path?: string;
+    /** Path to .env file */
     env_file?: string;
+    /** Inline environment variables */
+    environment?: Record<string, string>;
+    /** Auto-detected port number (populated when port monitor detects listening port) */
     port?: number;
+    /** Generated URL from subdomain + port (populated when port is detected) */
     url?: string;
+    /** Server lifecycle status */
     status: ServerStatus;
+    /** Process ID (direct process, not shell wrapper) */
     pid?: number;
-    terminal_id?: string;
+    /** Configured restart policy */
+    restart_policy?: RestartPolicy;
+    /** Maximum restart attempts (0 = unlimited) */
+    max_restarts?: number;
+    /** Delay between restarts in nanoseconds (input uses milliseconds via restart_delay_ms) */
+    restart_delay?: number;
+    /** Graceful shutdown timeout in nanoseconds (input uses milliseconds via stop_timeout_ms) */
+    stop_timeout?: number;
+    /** Number of times the server has been automatically restarted */
+    restart_count?: number;
+    /** Last exit code (null if process is still running) */
+    exit_code?: number | null;
+    /** When the server was created */
     created_at: string;
+    /** When the server was last updated */
     updated_at: string;
 }
 /**
@@ -2882,14 +2974,51 @@ declare class Sandbox {
      */
     listServers(): Promise<ServersListResponse>;
     /**
-     * Start a new managed server
+     * Start a new managed server with optional supervisor settings
+     *
      * @param options - Server configuration
+     * @param options.slug - Unique server identifier
+     * @param options.command - Command to start the server
+     * @param options.path - Working directory (optional)
+     * @param options.env_file - Path to .env file relative to path (optional)
+     * @param options.environment - Inline environment variables (merged with env_file if both provided)
+     * @param options.restart_policy - When to automatically restart: 'never' (default), 'on-failure', 'always'
+     * @param options.max_restarts - Maximum restart attempts, 0 = unlimited (default: 0)
+     * @param options.restart_delay_ms - Delay between restart attempts in milliseconds (default: 1000)
+     * @param options.stop_timeout_ms - Graceful shutdown timeout in milliseconds (default: 10000)
+     *
+     * @example
+     * ```typescript
+     * // Basic server
+     * await sandbox.startServer({
+     *   slug: 'web',
+     *   command: 'npm run dev',
+     *   path: '/app',
+     * });
+     *
+     * // With supervisor settings
+     * await sandbox.startServer({
+     *   slug: 'api',
+     *   command: 'node server.js',
+     *   path: '/app',
+     *   environment: { NODE_ENV: 'production', PORT: '3000' },
+     *   restart_policy: 'on-failure',
+     *   max_restarts: 5,
+     *   restart_delay_ms: 2000,
+     *   stop_timeout_ms: 5000,
+     * });
+     * ```
      */
     startServer(options: {
         slug: string;
         command: string;
         path?: string;
         env_file?: string;
+        environment?: Record<string, string>;
+        restart_policy?: RestartPolicy;
+        max_restarts?: number;
+        restart_delay_ms?: number;
+        stop_timeout_ms?: number;
     }): Promise<ServerResponse>;
     /**
      * Get information about a specific server

package/dist/index.d.ts

@@ -1103,25 +1103,64 @@ declare class Terminal {
  * Server - Resource namespace for managed server operations
  */
 
+/**
+ * Options for starting a managed server
+ */
+interface ServerStartOptions {
+    /** Unique server identifier (URL-safe) */
+    slug: string;
+    /** Command to start the server */
+    command: string;
+    /** Working directory (optional) */
+    path?: string;
+    /** Path to .env file relative to path (optional) */
+    env_file?: string;
+    /** Inline environment variables (merged with env_file if both provided) */
+    environment?: Record<string, string>;
+    /**
+     * When to automatically restart the server:
+     * - `never`: No automatic restart (default)
+     * - `on-failure`: Restart only on non-zero exit code
+     * - `always`: Always restart on exit (including exit code 0)
+     */
+    restart_policy?: RestartPolicy;
+    /** Maximum restart attempts (0 = unlimited, default: 0) */
+    max_restarts?: number;
+    /** Delay between restart attempts in milliseconds (default: 1000) */
+    restart_delay_ms?: number;
+    /** Graceful shutdown timeout in milliseconds - SIGTERM → wait → SIGKILL (default: 10000) */
+    stop_timeout_ms?: number;
+}
 /**
  * Server resource namespace
  *
  * @example
  * ```typescript
- * // Start a new server
+ * // Start a basic server
  * const server = await sandbox.server.start({
  *   slug: 'api',
  *   command: 'npm start',
  *   path: '/app',
  * });
  *
+ * // Start with supervisor settings (auto-restart on failure)
+ * const server = await sandbox.server.start({
+ *   slug: 'web',
+ *   command: 'node server.js',
+ *   path: '/app',
+ *   environment: { NODE_ENV: 'production', PORT: '3000' },
+ *   restart_policy: 'on-failure',
+ *   max_restarts: 5,
+ *   restart_delay_ms: 2000,
+ * });
+ *
  * // List all servers
  * const servers = await sandbox.server.list();
  *
  * // Retrieve a specific server
  * const server = await sandbox.server.retrieve('api');
  *
- * // Stop a server
+ * // Stop a server (graceful shutdown with SIGTERM → SIGKILL)
  * await sandbox.server.stop('api');
  *
  * // Restart a server
@@ -1136,12 +1175,7 @@ declare class Server {
     private restartHandler;
     private updateStatusHandler;
     constructor(handlers: {
-        start: (options: {
-            slug: string;
-            command: string;
-            path?: string;
-            env_file?: string;
-        }) => Promise<ServerResponse>;
+        start: (options: ServerStartOptions) => Promise<ServerResponse>;
         list: () => Promise<ServersListResponse>;
         retrieve: (slug: string) => Promise<ServerResponse>;
         stop: (slug: string) => Promise<ServerStopResponse | void>;
@@ -1149,20 +1183,40 @@ declare class Server {
         updateStatus: (slug: string, status: ServerStatus) => Promise<void>;
     });
     /**
-     * Start a new managed server
+     * Start a new managed server with optional supervisor settings
+     *
+     * **Restart Policies:**
+     * - `never` (default): No automatic restart on exit
+     * - `on-failure`: Restart only on non-zero exit code
+     * - `always`: Always restart on exit (including exit code 0)
+     *
+     * **Graceful Shutdown:**
+     * When stopping a server, it first sends SIGTERM and waits for `stop_timeout_ms`
+     * before sending SIGKILL if the process hasn't exited.
+     *
      * @param options - Server configuration
-     * @param options.slug - Unique server slug (URL-safe identifier)
-     * @param options.command - Command to start the server
-     * @param options.path - Working directory (optional)
-     * @param options.env_file - Path to env file (optional)
      * @returns Server info
+     *
+     * @example
+     * ```typescript
+     * // Basic server
+     * const server = await sandbox.server.start({
+     *   slug: 'web',
+     *   command: 'npm run dev',
+     *   path: '/app',
+     * });
+     *
+     * // With supervisor settings
+     * const server = await sandbox.server.start({
+     *   slug: 'api',
+     *   command: 'node server.js',
+     *   environment: { NODE_ENV: 'production' },
+     *   restart_policy: 'always',
+     *   max_restarts: 0, // unlimited
+     * });
+     * ```
      */
-    start(options: {
-        slug: string;
-        command: string;
-        path?: string;
-        env_file?: string;
-    }): Promise<ServerInfo>;
+    start(options: ServerStartOptions): Promise<ServerInfo>;
     /**
      * List all managed servers
      * @returns Array of server info
@@ -2301,23 +2355,61 @@ interface TerminalResponse {
 }
 /**
  * Server status types
+ *
+ * - `starting`: Initial startup of the server process
+ * - `running`: Server process is running
+ * - `ready`: Server is running and ready to accept traffic
+ * - `failed`: Server failed to start or encountered a fatal error
+ * - `stopped`: Server was intentionally stopped
+ * - `restarting`: Server is being automatically restarted by the supervisor
+ */
+type ServerStatus = 'starting' | 'running' | 'ready' | 'failed' | 'stopped' | 'restarting';
+/**
+ * Server restart policy
+ * - `never`: No automatic restart (default)
+ * - `on-failure`: Restart only on non-zero exit code
+ * - `always`: Always restart on exit (including exit code 0)
  */
-type ServerStatus = 'starting' | 'running' | 'ready' | 'failed' | 'stopped';
+type RestartPolicy = 'never' | 'on-failure' | 'always';
 /**
  * Server information
  */
 interface ServerInfo {
+    /** Unique server identifier */
     slug: string;
+    /** Command used to start the server */
     command: string;
+    /** Working directory path */
     path: string;
+    /** Original path before resolution */
     original_path?: string;
+    /** Path to .env file */
     env_file?: string;
+    /** Inline environment variables */
+    environment?: Record<string, string>;
+    /** Auto-detected port number (populated when port monitor detects listening port) */
     port?: number;
+    /** Generated URL from subdomain + port (populated when port is detected) */
     url?: string;
+    /** Server lifecycle status */
     status: ServerStatus;
+    /** Process ID (direct process, not shell wrapper) */
     pid?: number;
-    terminal_id?: string;
+    /** Configured restart policy */
+    restart_policy?: RestartPolicy;
+    /** Maximum restart attempts (0 = unlimited) */
+    max_restarts?: number;
+    /** Delay between restarts in nanoseconds (input uses milliseconds via restart_delay_ms) */
+    restart_delay?: number;
+    /** Graceful shutdown timeout in nanoseconds (input uses milliseconds via stop_timeout_ms) */
+    stop_timeout?: number;
+    /** Number of times the server has been automatically restarted */
+    restart_count?: number;
+    /** Last exit code (null if process is still running) */
+    exit_code?: number | null;
+    /** When the server was created */
     created_at: string;
+    /** When the server was last updated */
     updated_at: string;
 }
 /**
@@ -2882,14 +2974,51 @@ declare class Sandbox {
      */
     listServers(): Promise<ServersListResponse>;
     /**
-     * Start a new managed server
+     * Start a new managed server with optional supervisor settings
+     *
      * @param options - Server configuration
+     * @param options.slug - Unique server identifier
+     * @param options.command - Command to start the server
+     * @param options.path - Working directory (optional)
+     * @param options.env_file - Path to .env file relative to path (optional)
+     * @param options.environment - Inline environment variables (merged with env_file if both provided)
+     * @param options.restart_policy - When to automatically restart: 'never' (default), 'on-failure', 'always'
+     * @param options.max_restarts - Maximum restart attempts, 0 = unlimited (default: 0)
+     * @param options.restart_delay_ms - Delay between restart attempts in milliseconds (default: 1000)
+     * @param options.stop_timeout_ms - Graceful shutdown timeout in milliseconds (default: 10000)
+     *
+     * @example
+     * ```typescript
+     * // Basic server
+     * await sandbox.startServer({
+     *   slug: 'web',
+     *   command: 'npm run dev',
+     *   path: '/app',
+     * });
+     *
+     * // With supervisor settings
+     * await sandbox.startServer({
+     *   slug: 'api',
+     *   command: 'node server.js',
+     *   path: '/app',
+     *   environment: { NODE_ENV: 'production', PORT: '3000' },
+     *   restart_policy: 'on-failure',
+     *   max_restarts: 5,
+     *   restart_delay_ms: 2000,
+     *   stop_timeout_ms: 5000,
+     * });
+     * ```
      */
     startServer(options: {
         slug: string;
         command: string;
         path?: string;
         env_file?: string;
+        environment?: Record<string, string>;
+        restart_policy?: RestartPolicy;
+        max_restarts?: number;
+        restart_delay_ms?: number;
+        stop_timeout_ms?: number;
     }): Promise<ServerResponse>;
     /**
      * Get information about a specific server

package/dist/index.js

@@ -1390,13 +1390,38 @@ var Server = class {
     this.updateStatusHandler = handlers.updateStatus;
   }
   /**
-   * Start a new managed server
+   * Start a new managed server with optional supervisor settings
+   *
+   * **Restart Policies:**
+   * - `never` (default): No automatic restart on exit
+   * - `on-failure`: Restart only on non-zero exit code
+   * - `always`: Always restart on exit (including exit code 0)
+   *
+   * **Graceful Shutdown:**
+   * When stopping a server, it first sends SIGTERM and waits for `stop_timeout_ms`
+   * before sending SIGKILL if the process hasn't exited.
+   *
    * @param options - Server configuration
-   * @param options.slug - Unique server slug (URL-safe identifier)
-   * @param options.command - Command to start the server
-   * @param options.path - Working directory (optional)
-   * @param options.env_file - Path to env file (optional)
    * @returns Server info
+   *
+   * @example
+   * ```typescript
+   * // Basic server
+   * const server = await sandbox.server.start({
+   *   slug: 'web',
+   *   command: 'npm run dev',
+   *   path: '/app',
+   * });
+   *
+   * // With supervisor settings
+   * const server = await sandbox.server.start({
+   *   slug: 'api',
+   *   command: 'node server.js',
+   *   environment: { NODE_ENV: 'production' },
+   *   restart_policy: 'always',
+   *   max_restarts: 0, // unlimited
+   * });
+   * ```
    */
   async start(options) {
     const response = await this.startHandler(options);
@@ -2796,8 +2821,40 @@ API request failed (${response.status}): ${error}`
     return this.request("/servers");
   }
   /**
-   * Start a new managed server
+   * Start a new managed server with optional supervisor settings
+   *
    * @param options - Server configuration
+   * @param options.slug - Unique server identifier
+   * @param options.command - Command to start the server
+   * @param options.path - Working directory (optional)
+   * @param options.env_file - Path to .env file relative to path (optional)
+   * @param options.environment - Inline environment variables (merged with env_file if both provided)
+   * @param options.restart_policy - When to automatically restart: 'never' (default), 'on-failure', 'always'
+   * @param options.max_restarts - Maximum restart attempts, 0 = unlimited (default: 0)
+   * @param options.restart_delay_ms - Delay between restart attempts in milliseconds (default: 1000)
+   * @param options.stop_timeout_ms - Graceful shutdown timeout in milliseconds (default: 10000)
+   *
+   * @example
+   * ```typescript
+   * // Basic server
+   * await sandbox.startServer({
+   *   slug: 'web',
+   *   command: 'npm run dev',
+   *   path: '/app',
+   * });
+   *
+   * // With supervisor settings
+   * await sandbox.startServer({
+   *   slug: 'api',
+   *   command: 'node server.js',
+   *   path: '/app',
+   *   environment: { NODE_ENV: 'production', PORT: '3000' },
+   *   restart_policy: 'on-failure',
+   *   max_restarts: 5,
+   *   restart_delay_ms: 2000,
+   *   stop_timeout_ms: 5000,
+   * });
+   * ```
    */
   async startServer(options) {
     return this.request("/servers", {