@watasu/sdk 0.1.25 → 0.1.40

package/README.md

@@ -16,7 +16,7 @@ Set `WATASU_API_KEY` before using the SDK.
 import { Sandbox } from '@watasu/sdk'
 
 const sbx = await Sandbox.create()
-await sbx.filesystem.write('/home/user/a.js', 'console.log(2 + 2)')
+await sbx.files.write('/home/user/a.js', 'console.log(2 + 2)')
 const result = await sbx.process.startAndWait('node /home/user/a.js')
 console.log(result.stdout)
 console.log(await sbx.isRunning())
@@ -31,23 +31,63 @@ await sbx.betaPause()
 await sbx.resume({ timeoutMs: 300_000 })
 ```
 
+Choose what happens when the sandbox timeout expires:
+
+```ts
+const sbx = await Sandbox.create({
+  lifecycle: { onTimeout: 'pause', autoResume: true },
+})
+```
+
+`onTimeout: 'kill'` is the default. `onTimeout: 'pause'` keeps the retained
+disk after timeout; `autoResume` lets a later data-plane request resume that
+paused sandbox automatically.
+
+Mount a named persistent volume when the sandbox starts:
+
+```ts
+const sbx = await Sandbox.create({
+  volumeMounts: {
+    '/workspace/cache': 'cache',
+    '/data/models': { name: 'models' },
+  },
+})
+```
+
+Create and edit a persistent volume while it is detached:
+
+```ts
+import { Volume } from '@watasu/sdk'
+
+const volume = await Volume.create('cache')
+await volume.makeDir('/workspace')
+await volume.writeFile('/workspace/status.txt', 'ready\n', { mode: '0644' })
+console.log(await volume.readFile('/workspace/status.txt'))
+console.log((await volume.list('/workspace')).map((entry) => entry.path))
+await volume.remove('/workspace/status.txt')
+await volume.destroy()
+```
+
 ## Code Interpreter
 
 ```ts
 import { Sandbox } from '@watasu/sdk/code-interpreter'
 
 const sbx = await Sandbox.create()
+const context = await sbx.createCodeContext()
 const execution = await sbx.runCode("print('hello')\n2 + 3", {
-  language: 'python',
+  context,
   onStdout: (message) => console.log(message.line),
 })
 
 console.log(execution.text)
+await sbx.removeCodeContext(context)
 await sbx.kill()
 ```
 
-`@watasu/sdk/code-interpreter` starts the `code-interpreter` template by default
-and returns structured `results`, `logs`, and `error` fields for each execution.
+`@watasu/sdk/code-interpreter` starts the `code-interpreter` template by default.
+Code runs in persistent Python contexts and returns structured `results`, `logs`,
+and `error` fields for each execution.
 
 ## MCP Gateway
 
@@ -112,12 +152,12 @@ const remoteUrl = await sbx.git.remoteGet('/workspace/project', 'origin')
 await sbx.git.restore('/workspace/project', { paths: ['README.md'] })
 await sbx.git.reset('/workspace/project', { mode: 'hard', target: 'HEAD' })
 
-await sbx.filesystem.writeFiles([
+await sbx.files.writeFiles([
   { path: '/workspace/project/a.txt', data: 'alpha' },
   { path: '/workspace/project/b.bin', data: new Uint8Array([0, 1, 2]) },
 ])
 
-const watcher = sbx.filesystem.watchDir('/workspace/project')
+const watcher = sbx.files.watchDir('/workspace/project')
 watcher.addEventListener((event) => {
   console.log(event.type, event.path)
 })
@@ -191,7 +231,10 @@ instructions into Watasu's package-spec builder.
 import { Sandbox } from '@watasu/sdk'
 
 const sbx = await Sandbox.create()
-const metrics = await sbx.getMetrics()
+const metrics = await sbx.getMetrics({
+  start: new Date(Date.now() - 5 * 60_000),
+  end: new Date(),
+})
 const snapshot = await sbx.createSnapshot({ name: 'ready' })
 const snapshots = await sbx.listSnapshots().nextItems()
 const allSnapshots = await Sandbox.listSnapshots({ limit: 100 }).nextItems()

package/dist/codeInterpreter.d.ts

@@ -1,20 +1,43 @@
 import { Sandbox as BaseSandbox, SandboxConnectOpts, SandboxCreateOpts } from './sandbox.js';
+export { ApiError, AuthenticationError, ConflictError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
+export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
+export { SandboxPaginator, SnapshotPaginator } from './sandbox.js';
+export type { CreateSnapshotOpts, FileUrlInfo, McpServer, McpServerName, RestoreSnapshotOpts, SandboxConnectOpts, SandboxCreateOpts, SandboxInfo, SandboxInfoLifecycle, SandboxLifecycle, SandboxListOpts, SandboxMetrics, SandboxMetricsOpts, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, } from './sandbox.js';
+export { CommandExitError, CommandHandle, Commands } from './commands.js';
+export type { CommandResult, CommandStartOpts, ProcessInfo } from './commands.js';
+export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
+export type { ProcessOpts } from './process.js';
+export { FileType, Filesystem, FilesystemWatcher, WatchHandle } from './filesystem.js';
+export type { EntryInfo, FilesystemEvent, FilesystemReadOpts, FilesystemRequestOpts, FilesystemWriteOpts, WatchOpts, WriteData, WriteEntry, WriteInfo, } from './filesystem.js';
+export { Git } from './git.js';
+export type { GitAddOpts, GitAuthOpts, GitBranches, GitBranchOpts, GitCloneOpts, GitCommandResult, GitCommitOpts, GitConfigOpts, GitConfigureUserOpts, GitCredentialOpts, GitFileStatus, GitInitOpts, GitPullOpts, GitPushOpts, GitRemoteAddOpts, GitResetMode, GitResetOpts, GitRestoreOpts, GitStatus, } from './git.js';
+export { Pty } from './pty.js';
+export type { PtyConnectOpts, PtyCreateOpts, PtySize } from './pty.js';
+export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
+export type { TerminalOpts } from './terminal.js';
+export { Volume } from './volume.js';
+export type { VolumeApiParams, VolumeConnectionConfig, VolumeEntryStat, VolumeFileType, VolumeInfo, VolumeListFilesOpts, VolumeListOpts, VolumeMetadataOpts, VolumeReadFileOpts, VolumeReadFormat, VolumeWriteData, VolumeWriteFileOpts, } from './volume.js';
+export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, } from './template.js';
+export type { BuildInfo, BuildOptions, BuildStatusReason, CopyItem, GetBuildStatusOptions, LogEntry, ReadyCommand, TemplateBuilder, TemplateBuildStatus, TemplateBuildStatusResponse, TemplateClass, TemplateFactory, TemplateFinal, TemplateFromImage, TemplateOptions, TemplateTag, TemplateTagInfo, } from './template.js';
 export type RunCodeLanguage = 'python' | 'python3' | string;
 export interface RunCodeOpts {
     language?: RunCodeLanguage;
-    context?: Context;
+    context?: Context | string;
     onStdout?: (message: OutputMessage) => void;
     onStderr?: (message: OutputMessage) => void;
     onResult?: (result: Result) => void;
     onError?: (error: ExecutionError) => void;
     envs?: Record<string, string>;
-    timeout?: number;
+    timeoutMs?: number;
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 export interface CreateCodeContextOpts {
     cwd?: string;
     language?: RunCodeLanguage;
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 /** One stdout or stderr line emitted by code execution. */
 export declare class OutputMessage {
@@ -86,15 +109,18 @@ export declare class Sandbox extends BaseSandbox {
     /** Create a persistent code context. */
     createCodeContext(_opts?: CreateCodeContextOpts): Promise<Context>;
     /** Remove a persistent code context. */
-    removeCodeContext(_context: Context, _opts?: {
+    removeCodeContext(context: Context | string, opts?: {
         requestTimeoutMs?: number;
-    }): Promise<boolean>;
+        signal?: AbortSignal;
+    }): Promise<void>;
     /** List persistent code contexts. */
-    listCodeContexts(_opts?: {
+    listCodeContexts(opts?: {
         requestTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<Context[]>;
     /** Restart a persistent code context. */
-    restartCodeContext(_context: Context, _opts?: {
+    restartCodeContext(context: Context | string, opts?: {
         requestTimeoutMs?: number;
-    }): Promise<Context>;
+        signal?: AbortSignal;
+    }): Promise<void>;
 }

package/dist/codeInterpreter.js

@@ -1,5 +1,17 @@
-import { InvalidArgumentError, NotImplementedError } from './errors.js';
+import { InvalidArgumentError } from './errors.js';
 import { Sandbox as BaseSandbox } from './sandbox.js';
+export { ApiError, AuthenticationError, ConflictError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
+export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
+export { SandboxPaginator, SnapshotPaginator } from './sandbox.js';
+export { CommandExitError, CommandHandle, Commands } from './commands.js';
+export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
+export { FileType, Filesystem, FilesystemWatcher, WatchHandle } from './filesystem.js';
+export { Git } from './git.js';
+export { Pty } from './pty.js';
+export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
+export { Volume } from './volume.js';
+export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, } from './template.js';
 /** One stdout or stderr line emitted by code execution. */
 export class OutputMessage {
     line;
@@ -161,10 +173,11 @@ export class Sandbox extends BaseSandbox {
             language: opts.language,
             context_id: contextId(opts.context),
             env_vars: opts.envs,
-            timeout_seconds: opts.timeout,
+            timeout_ms: opts.timeoutMs,
         });
         const response = await this.runtimePostJson('/runtime/v1/code/run', payload, {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         const execution = executionFromApi(response);
         emitCallbacks(execution, opts);
@@ -172,19 +185,37 @@ export class Sandbox extends BaseSandbox {
     }
     /** Create a persistent code context. */
     async createCodeContext(_opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+        const response = await this.runtimePostJson('/runtime/v1/code/contexts', compactRecord({
+            cwd: _opts.cwd,
+            language: _opts.language,
+        }), {
+            requestTimeoutMs: _opts.requestTimeoutMs,
+            signal: _opts.signal,
+        });
+        return contextFromApi(response);
     }
     /** Remove a persistent code context. */
-    async removeCodeContext(_context, _opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    async removeCodeContext(context, opts = {}) {
+        await this.runtimeDeleteJson(`/runtime/v1/code/contexts/${encodeURIComponent(requireContextId(context))}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
     }
     /** List persistent code contexts. */
-    async listCodeContexts(_opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    async listCodeContexts(opts = {}) {
+        const response = await this.runtimeGetJson('/runtime/v1/code/contexts', {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
+        const contexts = Array.isArray(response) ? response : arrayOfUnknown(response.contexts);
+        return contexts.map((item) => contextFromApi(record(item)));
     }
     /** Restart a persistent code context. */
-    async restartCodeContext(_context, _opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    async restartCodeContext(context, opts = {}) {
+        await this.runtimePostJson(`/runtime/v1/code/contexts/${encodeURIComponent(requireContextId(context))}/restart`, {}, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
     }
 }
 function executionFromApi(payload) {
@@ -219,7 +250,17 @@ function emitCallbacks(execution, opts) {
         opts.onError?.(execution.error);
 }
 function contextId(context) {
-    return context?.id;
+    if (context === undefined)
+        return undefined;
+    return requireContextId(context);
+}
+function requireContextId(context) {
+    if (typeof context === 'string')
+        return context;
+    return context.id;
+}
+function contextFromApi(payload) {
+    return new Context(String(payload.id ?? ''), stringValue(payload.language), stringValue(payload.cwd));
 }
 function compactRecord(payload) {
     return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));

package/dist/commands.d.ts

@@ -34,22 +34,17 @@ export interface CommandStartOpts {
     /** Arguments for `cmd` when starting a direct executable. */
     args?: string[];
     cwd?: string;
-    /** Deprecated alias for `cwd`. */
-    rootDir?: string;
     user?: string;
     envs?: Record<string, string>;
-    /** Alias for `envs`. */
-    envVars?: Record<string, string>;
     onStdout?: (data: string) => void | Promise<void>;
     onStderr?: (data: string) => void | Promise<void>;
     onPty?: (data: Uint8Array) => void | Promise<void>;
     onExit?: (exitCode: number) => void | Promise<void>;
     stdin?: boolean;
     timeoutMs?: number;
-    /** Alias for `timeoutMs`. */
-    timeout?: number;
     processID?: string;
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 /** Live handle for one sandbox process stream. */
 export declare class CommandHandle implements Partial<CommandResult> {
@@ -98,18 +93,22 @@ export declare class Commands {
     /** List processes currently known by the sandbox runtime. */
     list(opts?: {
         requestTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<ProcessInfo[]>;
     /** Send SIGKILL to a process by pid. */
     kill(pid: number | string, opts?: {
         requestTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<boolean>;
     /** Attach to a process and send stdin bytes or text. */
     sendStdin(pid: number | string, data: string | Uint8Array, opts?: {
         requestTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<void>;
     /** Attach to a process and close stdin, signalling EOF. */
     closeStdin(pid: number | string, opts?: {
         requestTimeoutMs?: number;
+        signal?: AbortSignal;
     }): Promise<void>;
     run(cmd: string, opts: CommandStartOpts & {
         background: true;

package/dist/commands.js

@@ -167,31 +167,31 @@ export class Commands {
         const handle = await this.start(cmd, opts);
         if (opts.background)
             return handle;
-        return handle.wait(opts.timeoutMs ?? opts.timeout);
+        return handle.wait(opts.timeoutMs);
     }
     /** Reconnect to a live process stream by pid. */
     async connect(pid, opts = {}) {
-        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, `/runtime/v1/process/${pid}/connect?since=0`, opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, `/runtime/v1/process/${pid}/connect?since=0`, opts.requestTimeoutMs ?? this.config.requestTimeoutMs, this.config.headers).connect();
         const first = await nextStarted(socket);
         const actualPid = framePid(first) ?? pid;
         return new CommandHandle(actualPid, socket, () => this.kill(actualPid), socket, opts.onStdout, opts.onStderr, opts.onPty);
     }
     /** Start a command and return a live handle immediately. */
     async start(cmd, opts = {}) {
-        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
-        const environment = { ...this.sandboxEnvs, ...(opts.envVars ?? opts.envs ?? {}) };
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs, this.config.headers).connect();
+        const environment = { ...this.sandboxEnvs, ...(opts.envs ?? {}) };
         const processConfig = processStartConfig(cmd, opts);
         socket.sendJson({
             type: 'start',
             id: opts.processID,
             cmd: processConfig.cmd,
             args: processConfig.args,
-            cwd: opts.cwd ?? opts.rootDir,
+            cwd: opts.cwd,
             user: opts.user,
             environment,
             envs: environment,
             stdin: opts.stdin ?? false,
-            timeout_ms: opts.timeoutMs ?? opts.timeout ?? 60_000,
+            timeout_ms: opts.timeoutMs ?? 60_000,
         });
         const first = await nextStarted(socket);
         const pid = framePid(first);

package/dist/connectionConfig.d.ts

@@ -6,9 +6,14 @@ export interface ConnectionOpts {
     accessToken?: string;
     domain?: string;
     apiUrl?: string;
+    /** Absolute sandbox data-plane URL override, primarily for local runtimes. */
+    sandboxUrl?: string;
     dataPlaneDomain?: string;
     requestTimeoutMs?: number;
     headers?: Record<string, string>;
+    apiHeaders?: Record<string, string>;
+    debug?: boolean;
+    signal?: AbortSignal;
     proxy?: unknown;
 }
 /** Resolved connection settings used by control-plane and data-plane clients. */
@@ -16,11 +21,30 @@ export declare class ConnectionConfig {
     readonly apiKey?: string;
     readonly domain: string;
     readonly apiUrl: string;
+    /** Absolute sandbox data-plane URL override, primarily for local runtimes. */
+    readonly sandboxUrl?: string;
     readonly dataPlaneDomain: string;
     readonly requestTimeoutMs: number;
     readonly headers: Record<string, string>;
+    readonly apiHeaders: Record<string, string>;
+    readonly debug: boolean;
+    readonly signal?: AbortSignal;
     readonly proxy?: unknown;
     constructor(opts?: ConnectionOpts);
     /** HTTP headers including the configured bearer token. */
     get authHeaders(): Record<string, string>;
+    /** Return an abort signal that follows the caller signal and optional timeout. */
+    getSignal(requestTimeoutMs?: number, signal?: AbortSignal | undefined): AbortSignal | undefined;
+    /** Return the sandbox data-plane API URL for a Watasu route token. */
+    getSandboxUrl(sandboxId: string, opts: {
+        sandboxDomain?: string;
+        envdPort: number;
+    }): string;
+    /** Return the direct sandbox data-plane API URL for a Watasu route token. */
+    getSandboxDirectUrl(sandboxId: string, opts: {
+        sandboxDomain?: string;
+        envdPort: number;
+    }): string;
+    /** Return the public hostname for a Watasu sandbox route token and port. */
+    getHost(sandboxId: string, port: number, sandboxDomain?: string): string;
 }

package/dist/connectionConfig.js

@@ -5,9 +5,14 @@ export class ConnectionConfig {
     apiKey;
     domain;
     apiUrl;
+    /** Absolute sandbox data-plane URL override, primarily for local runtimes. */
+    sandboxUrl;
     dataPlaneDomain;
     requestTimeoutMs;
     headers;
+    apiHeaders;
+    debug;
+    signal;
     proxy;
     constructor(opts = {}) {
         const env = typeof process !== 'undefined' ? process.env : {};
@@ -18,18 +23,60 @@ export class ConnectionConfig {
         this.domain = opts.domain ?? env.WATASU_DOMAIN ?? 'watasu.io';
         this.apiUrl =
             opts.apiUrl ?? env.WATASU_API_URL ?? `https://api.${this.domain}/v1`;
+        this.sandboxUrl =
+            opts.sandboxUrl ??
+                env.WATASU_SANDBOX_URL;
         this.dataPlaneDomain =
             opts.dataPlaneDomain ??
                 env.WATASU_DATA_PLANE_DOMAIN ??
                 'watasuhost.com';
         this.requestTimeoutMs = opts.requestTimeoutMs ?? 60_000;
         this.headers = opts.headers ?? {};
+        this.apiHeaders = opts.apiHeaders ?? {};
+        this.debug = opts.debug ?? false;
+        this.signal = opts.signal;
         this.proxy = opts.proxy;
     }
     /** HTTP headers including the configured bearer token. */
     get authHeaders() {
         return this.apiKey
-            ? { ...this.headers, Authorization: `Bearer ${this.apiKey}` }
-            : { ...this.headers };
+            ? { ...this.headers, ...this.apiHeaders, Authorization: `Bearer ${this.apiKey}` }
+            : { ...this.headers, ...this.apiHeaders };
+    }
+    /** Return an abort signal that follows the caller signal and optional timeout. */
+    getSignal(requestTimeoutMs = this.requestTimeoutMs, signal = this.signal) {
+        if (requestTimeoutMs === undefined && signal === undefined)
+            return undefined;
+        const controller = new AbortController();
+        if (signal?.aborted)
+            controller.abort();
+        else
+            signal?.addEventListener('abort', () => controller.abort(), { once: true });
+        if (requestTimeoutMs > 0) {
+            const timeout = setTimeout(() => controller.abort(), requestTimeoutMs);
+            const maybeTimeout = timeout;
+            if (typeof maybeTimeout.unref === 'function')
+                maybeTimeout.unref();
+            controller.signal.addEventListener('abort', () => clearTimeout(timeout), { once: true });
+        }
+        return controller.signal;
+    }
+    /** Return the sandbox data-plane API URL for a Watasu route token. */
+    getSandboxUrl(sandboxId, opts) {
+        if (this.sandboxUrl)
+            return this.sandboxUrl;
+        if (this.debug)
+            return `http://localhost:${opts.envdPort}`;
+        return `https://${sandboxId}.sandbox.${opts.sandboxDomain ?? this.dataPlaneDomain}`;
+    }
+    /** Return the direct sandbox data-plane API URL for a Watasu route token. */
+    getSandboxDirectUrl(sandboxId, opts) {
+        return this.getSandboxUrl(sandboxId, opts);
+    }
+    /** Return the public hostname for a Watasu sandbox route token and port. */
+    getHost(sandboxId, port, sandboxDomain = this.dataPlaneDomain) {
+        if (this.debug)
+            return `localhost:${port}`;
+        return `p${port}-${sandboxId}.sandbox.${sandboxDomain}`;
     }
 }

package/dist/filesystem.d.ts

@@ -40,6 +40,7 @@ export interface WatchOpts {
 }
 export interface FilesystemRequestOpts {
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
     user?: string;
 }
 export interface FilesystemReadOpts extends FilesystemRequestOpts {
@@ -56,8 +57,6 @@ export declare class WatchHandle {
     constructor(socket: ProcessSocket, events: AsyncIterable<ProcessFrame>, onEvent: (event: FilesystemEvent) => void | Promise<void>, onExit?: (error?: Error) => void | Promise<void>);
     /** Stop watching the directory. */
     stop(): void;
-    /** Alias for `stop`. */
-    close(): void;
     /** Resolves when the watcher stream exits. */
     wait(): Promise<void>;
     private pump;
@@ -102,30 +101,19 @@ export declare class Filesystem {
     /** Write several files in one runtime API call. */
     writeFiles(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>;
     /** List directory entries below `path`. */
-    list(path: string, opts?: {
-        requestTimeoutMs?: number;
+    list(path: string, opts?: FilesystemRequestOpts & {
         depth?: number;
     }): Promise<EntryInfo[]>;
     /** Return whether a file or directory exists at `path`. */
-    exists(path: string, opts?: {
-        requestTimeoutMs?: number;
-    }): Promise<boolean>;
+    exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
     /** Return stat metadata for `path`. */
-    getInfo(path: string, opts?: {
-        requestTimeoutMs?: number;
-    }): Promise<EntryInfo>;
+    getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
     /** Remove a file at `path`. */
-    remove(path: string, opts?: {
-        requestTimeoutMs?: number;
-    }): Promise<void>;
+    remove(path: string, opts?: FilesystemRequestOpts): Promise<void>;
     /** Move or rename a file. */
-    rename(oldPath: string, newPath: string, opts?: {
-        requestTimeoutMs?: number;
-    }): Promise<EntryInfo>;
+    rename(oldPath: string, newPath: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
     /** Create a directory. */
-    makeDir(path: string, opts?: {
-        requestTimeoutMs?: number;
-    }): Promise<boolean>;
+    makeDir(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
     /** Start watching a directory for filesystem events. */
     watchDir(path: string): FilesystemWatcher;
     watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts): Promise<FilesystemWatcher>;

package/dist/filesystem.js

@@ -22,10 +22,6 @@ export class WatchHandle {
     stop() {
         this.socket.close();
     }
-    /** Alias for `stop`. */
-    close() {
-        this.stop();
-    }
     /** Resolves when the watcher stream exits. */
     wait() {
         return this.done;
@@ -66,7 +62,7 @@ export class FilesystemWatcher {
         if (this.handle)
             return;
         const nextOpts = { ...this.opts, ...opts };
-        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, withQuery('/runtime/v1/files/watch', { path: this.path, recursive: nextOpts.recursive ?? false, include_entry: nextOpts.includeEntry }), nextOpts.requestTimeoutMs).connect();
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, withQuery('/runtime/v1/files/watch', { path: this.path, recursive: nextOpts.recursive ?? false, include_entry: nextOpts.includeEntry }), nextOpts.requestTimeoutMs, this.dataPlane.headers).connect();
         this.handle = new WatchHandle(socket, socket, async (event) => {
             for (const listener of this.listeners)
                 await listener(event);

package/dist/git.d.ts

@@ -20,16 +20,15 @@ export interface GitAuthOpts {
     envs?: Record<string, string>;
     user?: string;
     cwd?: string;
-    timeout?: number;
     timeoutMs?: number;
     requestTimeoutMs?: number;
+    signal?: AbortSignal;
 }
 export interface GitCloneOpts extends GitAuthOpts {
     path?: string;
     branch?: string;
     depth?: number;
     recursive?: boolean;
-    submodules?: boolean;
     dangerouslyStoreCredentials?: boolean;
 }
 export interface GitRequestOpts extends GitAuthOpts {

package/dist/git.js

@@ -9,7 +9,7 @@ export class Git {
         return this.run('/runtime/v1/git/clone', {
             url,
             ...gitOpts(opts),
-            ...pick(opts, ['path', 'branch', 'depth', 'recursive', 'submodules', 'username', 'password']),
+            ...pick(opts, ['path', 'branch', 'depth', 'recursive', 'username', 'password']),
             dangerously_store_credentials: opts.dangerouslyStoreCredentials,
         }, opts);
     }
@@ -163,7 +163,11 @@ export class Git {
         return String(result.value ?? '');
     }
     async run(path, json, opts) {
-        const payload = await this.dataPlane.postJson(path, { json: compact(json), requestTimeoutMs: opts.requestTimeoutMs });
+        const payload = await this.dataPlane.postJson(path, {
+            json: compact(json),
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return gitResult(payload.git ?? payload);
     }
 }
@@ -172,7 +176,7 @@ function gitOpts(opts) {
         env_vars: opts.envs,
         user: opts.user,
         cwd: opts.cwd,
-        timeout_seconds: opts.timeout ?? (opts.timeoutMs === undefined ? undefined : Math.ceil(opts.timeoutMs / 1000)),
+        timeout_seconds: opts.timeoutMs === undefined ? undefined : Math.ceil(opts.timeoutMs / 1000),
     };
 }
 function pick(source, keys) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { ApiError, AuthenticationError, ConflictError, FileNotFoundError, Invali
 export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
 export { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
 export { Sandbox as CodeInterpreterSandbox } from './codeInterpreter.js';
-export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxListOpts, SandboxMetrics, McpServer, McpServerName, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.js';
+export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxInfoLifecycle, SandboxLifecycle, SandboxListOpts, SandboxMetrics, SandboxMetricsOpts, McpServer, McpServerName, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.js';
 export type { CreateCodeContextOpts, RunCodeLanguage, RunCodeOpts, } from './codeInterpreter.js';
 export { Context as CodeInterpreterContext, Execution as CodeInterpreterExecution, ExecutionError as CodeInterpreterExecutionError, OutputMessage as CodeInterpreterOutputMessage, Result as CodeInterpreterResult, } from './codeInterpreter.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
@@ -17,6 +17,8 @@ export { Pty } from './pty.js';
 export type { PtyConnectOpts, PtyCreateOpts, PtySize } from './pty.js';
 export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
 export type { TerminalOpts } from './terminal.js';
+export { Volume } from './volume.js';
+export type { VolumeApiParams, VolumeConnectionConfig, VolumeEntryStat, VolumeFileType, VolumeInfo, VolumeListFilesOpts, VolumeListOpts, VolumeMetadataOpts, VolumeReadFileOpts, VolumeReadFormat, VolumeWriteData, VolumeWriteFileOpts, } from './volume.js';
 export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
-export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, } from './template.js';
 export type { BuildInfo, BuildOptions, BuildStatusReason, CopyItem, GetBuildStatusOptions, LogEntry, ReadyCommand, TemplateBuildStatus, TemplateBuildStatusResponse, TemplateBuilder, TemplateClass, TemplateFactory, TemplateFinal, TemplateFromImage, TemplateOptions, TemplateTag, TemplateTagInfo, } from './template.js';

package/dist/index.js

@@ -9,5 +9,6 @@ export { FileType, Filesystem, FilesystemWatcher, WatchHandle } from './filesyst
 export { Git } from './git.js';
 export { Pty } from './pty.js';
 export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
+export { Volume } from './volume.js';
 export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
-export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, } from './template.js';

package/dist/process.d.ts

@@ -41,7 +41,7 @@ export declare class Process {
     private waitPromise?;
     constructor(processID: string, handle: CommandHandle, output: ProcessOutput, onExit?: ((exitCode: number) => Promise<void> | void) | undefined);
     kill(): Promise<void>;
-    wait(timeout?: number): Promise<ProcessOutput>;
+    wait(timeoutMs?: number): Promise<ProcessOutput>;
     private waitOnce;
     sendStdin(data: string): Promise<void>;
 }