@watasu/sdk 0.1.24 → 0.1.30

package/README.md

@@ -31,6 +31,64 @@ 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", {
+  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.
+Code runs in persistent Python contexts and returns structured `results`, `logs`,
+and `error` fields for each execution.
+
 ## MCP Gateway
 
 ```ts
@@ -173,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

@@ -0,0 +1,100 @@
+import { Sandbox as BaseSandbox, SandboxConnectOpts, SandboxCreateOpts } from './sandbox.js';
+export type RunCodeLanguage = 'python' | 'python3' | string;
+export interface RunCodeOpts {
+    language?: RunCodeLanguage;
+    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;
+    requestTimeoutMs?: number;
+}
+export interface CreateCodeContextOpts {
+    cwd?: string;
+    language?: RunCodeLanguage;
+    requestTimeoutMs?: number;
+}
+/** One stdout or stderr line emitted by code execution. */
+export declare class OutputMessage {
+    readonly line: string;
+    readonly timestamp: number;
+    readonly error: boolean;
+    constructor(line: string, timestamp?: number, error?: boolean);
+    toString(): string;
+    toJSON(): Record<string, unknown>;
+}
+/** Structured exception raised by user code inside the sandbox. */
+export declare class ExecutionError {
+    readonly name: string;
+    readonly value: string;
+    readonly traceback: string;
+    constructor(name: string, value: string, traceback: string);
+    toJSON(): Record<string, unknown>;
+}
+/** Rich result produced by the last expression of a code execution. */
+export declare class Result {
+    readonly text?: string;
+    readonly html?: string;
+    readonly markdown?: string;
+    readonly svg?: string;
+    readonly png?: string;
+    readonly jpeg?: string;
+    readonly pdf?: string;
+    readonly latex?: string;
+    readonly json?: unknown;
+    readonly javascript?: string;
+    readonly data?: unknown;
+    readonly chart?: unknown;
+    readonly extra: Record<string, unknown>;
+    readonly isMainResult: boolean;
+    constructor(payload?: Record<string, unknown>);
+    formats(): string[];
+    toJSON(): Record<string, unknown>;
+}
+export interface Logs {
+    stdout: OutputMessage[];
+    stderr: OutputMessage[];
+}
+/** Complete result of a sandbox code execution. */
+export declare class Execution {
+    readonly results: Result[];
+    readonly logs: Logs;
+    readonly error: ExecutionError | undefined;
+    readonly executionCount: number | undefined;
+    constructor(results?: Result[], logs?: Logs, error?: ExecutionError | undefined, executionCount?: number | undefined);
+    get text(): string | undefined;
+    toJSON(): Record<string, unknown>;
+}
+/** Code execution context metadata. */
+export declare class Context {
+    readonly id: string;
+    readonly language?: string | undefined;
+    readonly cwd?: string | undefined;
+    constructor(id: string, language?: string | undefined, cwd?: string | undefined);
+    toJSON(): Record<string, unknown>;
+}
+/** Sandbox specialized for running Python code. */
+export declare class Sandbox extends BaseSandbox {
+    static readonly defaultTemplate = "code-interpreter";
+    static create(opts?: SandboxCreateOpts): Promise<Sandbox>;
+    static create(template: string, opts?: SandboxCreateOpts): Promise<Sandbox>;
+    static connect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
+    /** Run Python code in the sandbox and return structured execution output. */
+    runCode(code: string, opts?: RunCodeOpts): Promise<Execution>;
+    /** Create a persistent code context. */
+    createCodeContext(_opts?: CreateCodeContextOpts): Promise<Context>;
+    /** Remove a persistent code context. */
+    removeCodeContext(context: Context | string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
+    /** List persistent code contexts. */
+    listCodeContexts(opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<Context[]>;
+    /** Restart a persistent code context. */
+    restartCodeContext(context: Context | string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
+}

package/dist/codeInterpreter.js

@@ -0,0 +1,265 @@
+import { InvalidArgumentError } from './errors.js';
+import { Sandbox as BaseSandbox } from './sandbox.js';
+/** One stdout or stderr line emitted by code execution. */
+export class OutputMessage {
+    line;
+    timestamp;
+    error;
+    constructor(line, timestamp = Date.now() / 1000, error = false) {
+        this.line = line;
+        this.timestamp = timestamp;
+        this.error = error;
+    }
+    toString() {
+        return this.line;
+    }
+    toJSON() {
+        return {
+            line: this.line,
+            timestamp: this.timestamp,
+            error: this.error,
+        };
+    }
+}
+/** Structured exception raised by user code inside the sandbox. */
+export class ExecutionError {
+    name;
+    value;
+    traceback;
+    constructor(name, value, traceback) {
+        this.name = name;
+        this.value = value;
+        this.traceback = traceback;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            value: this.value,
+            traceback: this.traceback,
+        };
+    }
+}
+/** Rich result produced by the last expression of a code execution. */
+export class Result {
+    text;
+    html;
+    markdown;
+    svg;
+    png;
+    jpeg;
+    pdf;
+    latex;
+    json;
+    javascript;
+    data;
+    chart;
+    extra;
+    isMainResult;
+    constructor(payload = {}) {
+        this.text = stringValue(payload.text);
+        this.html = stringValue(payload.html);
+        this.markdown = stringValue(payload.markdown);
+        this.svg = stringValue(payload.svg);
+        this.png = stringValue(payload.png);
+        this.jpeg = stringValue(payload.jpeg);
+        this.pdf = stringValue(payload.pdf);
+        this.latex = stringValue(payload.latex);
+        this.json = payload.json;
+        this.javascript = stringValue(payload.javascript);
+        this.data = payload.data;
+        this.chart = payload.chart;
+        this.extra = record(payload.extra);
+        this.isMainResult = Boolean(payload.is_main_result ?? payload.isMainResult);
+    }
+    formats() {
+        const names = ['text', 'html', 'markdown', 'svg', 'png', 'jpeg', 'pdf', 'latex', 'json', 'javascript', 'data', 'chart'];
+        return names.filter((name) => this[name] !== undefined);
+    }
+    toJSON() {
+        return compactRecord({
+            text: this.text,
+            html: this.html,
+            markdown: this.markdown,
+            svg: this.svg,
+            png: this.png,
+            jpeg: this.jpeg,
+            pdf: this.pdf,
+            latex: this.latex,
+            json: this.json,
+            javascript: this.javascript,
+            data: this.data,
+            chart: this.chart,
+            extra: Object.keys(this.extra).length === 0 ? undefined : this.extra,
+            is_main_result: this.isMainResult,
+        });
+    }
+}
+/** Complete result of a sandbox code execution. */
+export class Execution {
+    results;
+    logs;
+    error;
+    executionCount;
+    constructor(results = [], logs = { stdout: [], stderr: [] }, error = undefined, executionCount = undefined) {
+        this.results = results;
+        this.logs = logs;
+        this.error = error;
+        this.executionCount = executionCount;
+    }
+    get text() {
+        return this.results.find((result) => result.isMainResult && result.text !== undefined)?.text ??
+            this.results.find((result) => result.text !== undefined)?.text;
+    }
+    toJSON() {
+        return {
+            results: this.results.map((result) => result.toJSON()),
+            logs: {
+                stdout: this.logs.stdout.map((message) => message.toJSON()),
+                stderr: this.logs.stderr.map((message) => message.toJSON()),
+            },
+            error: this.error?.toJSON() ?? null,
+            execution_count: this.executionCount,
+        };
+    }
+}
+/** Code execution context metadata. */
+export class Context {
+    id;
+    language;
+    cwd;
+    constructor(id, language, cwd) {
+        this.id = id;
+        this.language = language;
+        this.cwd = cwd;
+    }
+    toJSON() {
+        return compactRecord({
+            id: this.id,
+            language: this.language,
+            cwd: this.cwd,
+        });
+    }
+}
+/** Sandbox specialized for running Python code. */
+export class Sandbox extends BaseSandbox {
+    static defaultTemplate = 'code-interpreter';
+    static async create(templateOrOpts, opts = {}) {
+        return await super.create(templateOrOpts, opts);
+    }
+    static async connect(sandboxId, opts = {}) {
+        return await super.connect(sandboxId, opts);
+    }
+    /** Run Python code in the sandbox and return structured execution output. */
+    async runCode(code, opts = {}) {
+        if (typeof code !== 'string')
+            throw new InvalidArgumentError('code must be a string');
+        if (opts.language !== undefined && opts.context !== undefined) {
+            throw new InvalidArgumentError('language and context cannot both be set');
+        }
+        const payload = compactRecord({
+            code,
+            language: opts.language,
+            context_id: contextId(opts.context),
+            env_vars: opts.envs,
+            timeout_seconds: opts.timeout,
+        });
+        const response = await this.runtimePostJson('/runtime/v1/code/run', payload, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        const execution = executionFromApi(response);
+        emitCallbacks(execution, opts);
+        return execution;
+    }
+    /** Create a persistent code context. */
+    async createCodeContext(_opts = {}) {
+        const response = await this.runtimePostJson('/runtime/v1/code/contexts', compactRecord({
+            cwd: _opts.cwd,
+            language: _opts.language,
+        }), {
+            requestTimeoutMs: _opts.requestTimeoutMs,
+        });
+        return contextFromApi(response);
+    }
+    /** Remove a persistent code context. */
+    async removeCodeContext(context, opts = {}) {
+        await this.runtimeDeleteJson(`/runtime/v1/code/contexts/${encodeURIComponent(requireContextId(context))}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
+    /** List persistent code contexts. */
+    async listCodeContexts(opts = {}) {
+        const response = await this.runtimeGetJson('/runtime/v1/code/contexts', {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        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 = {}) {
+        await this.runtimePostJson(`/runtime/v1/code/contexts/${encodeURIComponent(requireContextId(context))}/restart`, {}, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
+}
+function executionFromApi(payload) {
+    const execution = record(payload.execution ?? payload);
+    const logs = record(execution.logs);
+    return new Execution(arrayOfRecords(execution.results).map((item) => new Result(item)), {
+        stdout: arrayOfUnknown(logs.stdout).map((item) => outputMessageFromApi(item, false)),
+        stderr: arrayOfUnknown(logs.stderr).map((item) => outputMessageFromApi(item, true)),
+    }, executionErrorFromApi(execution.error), numberValue(execution.execution_count ?? execution.executionCount));
+}
+function outputMessageFromApi(value, error) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const item = value;
+        return new OutputMessage(String(item.line ?? ''), numberValue(item.timestamp) ?? Date.now() / 1000, Boolean(item.error ?? error));
+    }
+    return new OutputMessage(String(value), Date.now() / 1000, error);
+}
+function executionErrorFromApi(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const item = value;
+    return new ExecutionError(String(item.name ?? ''), String(item.value ?? ''), String(item.traceback ?? ''));
+}
+function emitCallbacks(execution, opts) {
+    for (const message of execution.logs.stdout)
+        opts.onStdout?.(message);
+    for (const message of execution.logs.stderr)
+        opts.onStderr?.(message);
+    for (const result of execution.results)
+        opts.onResult?.(result);
+    if (execution.error !== undefined)
+        opts.onError?.(execution.error);
+}
+function contextId(context) {
+    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));
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function arrayOfRecords(value) {
+    return Array.isArray(value) ? value.map((item) => record(item)) : [];
+}
+function arrayOfUnknown(value) {
+    return Array.isArray(value) ? value : [];
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' ? value : undefined;
+}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 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 { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
-export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxListOpts, SandboxMetrics, McpServer, McpServerName, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.js';
+export { Sandbox as CodeInterpreterSandbox } from './codeInterpreter.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';
 export type { CommandResult, CommandStartOpts, ProcessInfo } from './commands.js';
 export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
@@ -14,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 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

@@ -1,11 +1,14 @@
 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 { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
+export { Sandbox as CodeInterpreterSandbox } 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';
 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, waitForUrl, } from './template.js';

package/dist/sandbox.d.ts

@@ -19,7 +19,16 @@ export interface SandboxCreateOpts extends ConnectionOpts {
     team?: string;
     /** MCP gateway configuration to launch inside an `mcp-gateway` sandbox. */
     mcp?: McpServer;
-    volumeMounts?: unknown;
+    /** Timeout lifecycle policy. Defaults to killing the sandbox at timeout. */
+    lifecycle?: SandboxLifecycle;
+    /** Persistent volumes to mount, keyed by guest path. */
+    volumeMounts?: Record<string, string | {
+        name: string;
+    }>;
+}
+export interface SandboxLifecycle {
+    onTimeout: 'kill' | 'pause';
+    autoResume?: boolean;
 }
 export type SandboxNetworkSelector = string | string[];
 export interface SandboxNetworkUpdate {
@@ -58,10 +67,19 @@ export interface SandboxInfo {
     templateId?: string;
     name?: string;
     state?: string;
+    lifecycle?: SandboxInfoLifecycle;
+    volumeMounts?: Array<{
+        name: string;
+        path: string;
+    }>;
     metadata: Record<string, string>;
     startedAt?: string;
     endAt?: string;
 }
+export interface SandboxInfoLifecycle {
+    onTimeout: 'kill' | 'pause' | string;
+    autoResume: boolean;
+}
 export interface SandboxMetrics {
     sandboxId?: string;
     state?: string;
@@ -71,6 +89,12 @@ export interface SandboxMetrics {
     memoryMb?: number;
     raw: Record<string, unknown>;
 }
+export interface SandboxMetricsOpts extends ConnectionOpts {
+    /** Start time for the metrics. Defaults to the sandbox start time. */
+    start?: Date;
+    /** End time for the metrics. Defaults to the current time. */
+    end?: Date;
+}
 export interface SnapshotInfo {
     snapshotId: string;
     sandboxId?: string;
@@ -142,9 +166,9 @@ export declare class SandboxPaginator {
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export declare class Sandbox {
     /** Default template slug used when create is called without a template. */
-    static readonly defaultTemplate = "base";
+    static readonly defaultTemplate: string;
     /** Default template slug used by MCP creation once Watasu supports it. */
-    static readonly defaultMcpTemplate = "mcp-gateway";
+    static readonly defaultMcpTemplate: string;
     /** Default sandbox lifetime in milliseconds. */
     static readonly defaultSandboxTimeoutMs = 300000;
     files: Filesystem;
@@ -194,7 +218,7 @@ export declare class Sandbox {
     /** Destroy a sandbox by id. */
     static kill(sandboxId: string, opts?: ConnectionOpts | string): Promise<boolean>;
     /** Fetch sandbox metrics by id. */
-    static getMetrics(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    static getMetrics(sandboxId: string, opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Atomically replace a sandbox's network egress policy by id. */
     static updateNetwork(sandboxId: string, network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
     private static putNetwork;
@@ -221,7 +245,7 @@ export declare class Sandbox {
     /** Fetch the latest control-plane metadata for this sandbox. */
     getInfo(): Promise<SandboxInfo>;
     /** Fetch latest sandbox metrics. */
-    getMetrics(opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Create a Watasu checkpoint using snapshot naming. */
     createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** Delete a snapshot by id. */
@@ -263,5 +287,11 @@ export declare class Sandbox {
     /** Resume this sandbox and refresh its data-plane session. */
     resume(opts?: SandboxConnectOpts): Promise<boolean>;
     private fileUrl;
+    /** POST JSON to the sandbox data-plane runtime API. */
+    protected runtimePostJson(path: string, json: Record<string, unknown>, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
+    /** GET JSON from the sandbox data-plane runtime API. */
+    protected runtimeGetJson(path: string, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
+    /** DELETE JSON from the sandbox data-plane runtime API. */
+    protected runtimeDeleteJson(path: string, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
     private configOptions;
 }

package/dist/sandbox.js

@@ -1,6 +1,6 @@
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
-import { DataPlaneClient, ControlClient } from './transport.js';
+import { DataPlaneClient, ControlClient, withQuery } from './transport.js';
 import { ConflictError, FileNotFoundError, NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
 import { Git } from './git.js';
@@ -122,9 +122,7 @@ export class Sandbox {
         const sandboxOpts = typeof templateOrOpts === 'string' ? opts : templateOrOpts ?? {};
         const template = typeof templateOrOpts === 'string'
             ? templateOrOpts
-            : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? Sandbox.defaultTemplate : undefined);
-        if (sandboxOpts.volumeMounts !== undefined)
-            unsupported('volumeMounts');
+            : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? this.defaultTemplate : undefined);
         const config = new ConnectionConfig(sandboxOpts);
         const control = new ControlClient(config);
         const sandboxPayload = {
@@ -136,6 +134,8 @@ export class Sandbox {
         };
         putIfPresent(sandboxPayload, 'template_id', template);
         putIfPresent(sandboxPayload, 'mcp', sandboxOpts.mcp);
+        putIfPresent(sandboxPayload, 'lifecycle', lifecyclePayload(sandboxOpts.lifecycle));
+        putIfPresent(sandboxPayload, 'volume_mounts', volumeMountsPayload(sandboxOpts.volumeMounts));
         Object.assign(sandboxPayload, networkUpdatePayload(sandboxOpts.network));
         putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
         const response = await control.post('/sandboxes', {
@@ -146,7 +146,7 @@ export class Sandbox {
         const sandboxId = sandbox.id ?? sandbox.sandbox_id;
         if (sandboxId === undefined)
             throw new SandboxError('create response did not include sandbox id');
-        const sandboxInstance = new Sandbox({
+        const sandboxInstance = new this({
             sandboxId: String(sandboxId),
             connectionConfig: config,
             control,
@@ -165,7 +165,7 @@ export class Sandbox {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
         });
-        return new Sandbox({
+        return new this({
             sandboxId,
             connectionConfig: config,
             control,
@@ -229,7 +229,7 @@ export class Sandbox {
     /** Fetch sandbox metrics by id. */
     static async getMetrics(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.get(`/sandboxes/${sandboxId}/metrics`, {
+        const payload = await control.get(metricsPath(sandboxId, opts), {
             requestTimeoutMs: opts.requestTimeoutMs,
         });
         return metricsList(payload.metrics ?? payload);
@@ -458,6 +458,25 @@ export class Sandbox {
         });
         return fileUrlInfo(record(payload.file_url ?? payload));
     }
+    /** POST JSON to the sandbox data-plane runtime API. */
+    async runtimePostJson(path, json, opts = {}) {
+        return this.dataPlane.postJson(path, {
+            json,
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
+    /** GET JSON from the sandbox data-plane runtime API. */
+    async runtimeGetJson(path, opts = {}) {
+        return this.dataPlane.getJson(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
+    /** DELETE JSON from the sandbox data-plane runtime API. */
+    async runtimeDeleteJson(path, opts = {}) {
+        return this.dataPlane.deleteJson(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
     configOptions() {
         return {
             apiKey: this.config.apiKey,
@@ -508,6 +527,15 @@ function snapshotListPath(opts, nextToken) {
     const query = params.toString();
     return query ? `/sandbox_snapshots?${query}` : '/sandbox_snapshots';
 }
+function metricsPath(sandboxId, opts) {
+    return withQuery(`/sandboxes/${sandboxId}/metrics`, {
+        start: dateTimestampSeconds(opts.start),
+        end: dateTimestampSeconds(opts.end),
+    });
+}
+function dateTimestampSeconds(value) {
+    return value === undefined ? undefined : Math.round(value.getTime() / 1000);
+}
 function fileUrlInfo(payload) {
     return {
         method: String(payload.method ?? ''),
@@ -531,6 +559,8 @@ function sandboxInfo(payload) {
         templateId: typeof payload.template_id === 'string' ? payload.template_id : templateSlug(payload.template),
         name: typeof payload.name === 'string' ? payload.name : undefined,
         state: typeof payload.state === 'string' ? payload.state : undefined,
+        lifecycle: sandboxLifecycleInfo(payload.lifecycle),
+        volumeMounts: volumeMountsInfo(payload.volume_mounts ?? payload.volumeMounts),
         metadata: recordOfStrings(payload.metadata),
         startedAt: typeof payload.started_at === 'string'
             ? payload.started_at
@@ -540,6 +570,45 @@ function sandboxInfo(payload) {
             : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
     };
 }
+function lifecyclePayload(lifecycle) {
+    if (lifecycle === undefined)
+        return undefined;
+    const onTimeout = lifecycle.onTimeout ?? 'kill';
+    const autoResume = lifecycle.autoResume ?? false;
+    if (autoResume && onTimeout !== 'pause') {
+        throw new SandboxError("lifecycle.autoResume can only be true when lifecycle.onTimeout is 'pause'");
+    }
+    return { on_timeout: onTimeout, auto_resume: autoResume };
+}
+function volumeMountsPayload(volumeMounts) {
+    if (volumeMounts === undefined)
+        return undefined;
+    return Object.entries(volumeMounts).map(([path, volume]) => ({
+        path,
+        name: typeof volume === 'string' ? volume : volume.name,
+    }));
+}
+function volumeMountsInfo(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .map((item) => {
+        const entry = record(item);
+        return { name: String(entry.name ?? ''), path: String(entry.path ?? '') };
+    })
+        .filter((entry) => entry.name !== '' && entry.path !== '');
+}
+function sandboxLifecycleInfo(value) {
+    const lifecycle = record(value);
+    const onTimeout = stringValue(lifecycle.on_timeout ?? lifecycle.onTimeout);
+    const autoResume = booleanValue(lifecycle.auto_resume ?? lifecycle.autoResume);
+    if (onTimeout === undefined && autoResume === undefined)
+        return undefined;
+    return {
+        onTimeout: onTimeout ?? 'kill',
+        autoResume: autoResume ?? false,
+    };
+}
 function metricsList(value) {
     if (Array.isArray(value))
         return value.map((item) => metricsInfo(record(item)));
@@ -589,6 +658,15 @@ function stringValue(value) {
 function numberValue(value) {
     return typeof value === 'number' ? value : undefined;
 }
+function booleanValue(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return undefined;
+}
 function templateSlug(value) {
     const template = record(value);
     return typeof template.slug === 'string' ? template.slug : undefined;

package/dist/volume.d.ts

@@ -0,0 +1,120 @@
+import { Blob } from 'node:buffer';
+import { ConnectionConfig, type ConnectionOpts } from './connectionConfig.js';
+import { ControlClient } from './transport.js';
+export type VolumeFileType = 'file' | 'directory' | 'symlink' | string;
+export type VolumeReadFormat = 'text' | 'bytes' | 'blob' | 'stream';
+export type VolumeWriteData = string | Uint8Array | ArrayBuffer | Blob;
+/** Control-plane metadata for a persistent Watasu volume. */
+export interface VolumeInfo {
+    volumeId: string;
+    id: string;
+    name: string;
+    state?: string;
+    token?: string;
+    sizeMb?: number;
+    sizeBytes?: number;
+    node?: string;
+    metadata: Record<string, string>;
+    createdAt?: string;
+    updatedAt?: string;
+    raw: Record<string, unknown>;
+}
+/** File or directory metadata returned by volume content operations. */
+export interface VolumeEntryStat {
+    path: string;
+    name: string;
+    type: VolumeFileType;
+    size?: number;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    atime?: unknown;
+    mtime?: unknown;
+    ctime?: unknown;
+    raw: Record<string, unknown>;
+}
+export interface VolumeApiParams extends ConnectionOpts {
+    team?: string;
+}
+export interface VolumeConnectionConfig extends ConnectionOpts {
+}
+export interface VolumeListOpts extends ConnectionOpts {
+    team?: string;
+}
+export interface VolumeListFilesOpts extends ConnectionOpts {
+    depth?: number;
+}
+export interface VolumeReadFileOpts extends ConnectionOpts {
+    format?: VolumeReadFormat;
+}
+export interface VolumeWriteFileOpts extends ConnectionOpts {
+    uid?: number;
+    gid?: number;
+    mode?: number | string;
+    force?: boolean;
+}
+export interface VolumeMetadataOpts extends ConnectionOpts {
+    uid?: number;
+    gid?: number;
+    mode?: number | string;
+}
+/** Persistent volume that can be mounted into sandboxes and edited while detached. */
+export declare class Volume {
+    readonly volumeId: string;
+    readonly id: string;
+    readonly name: string;
+    readonly token?: string;
+    private readonly config;
+    private readonly control;
+    constructor(opts: {
+        volumeId: string;
+        name?: string;
+        token?: string;
+        connectionConfig: ConnectionConfig;
+        control?: ControlClient;
+    });
+    /** Create a persistent volume and return a connected SDK object. */
+    static create(name: string, opts?: VolumeApiParams): Promise<Volume>;
+    /** Connect to an existing volume by id or name. */
+    static connect(volumeId: string, opts?: VolumeConnectionConfig): Promise<Volume>;
+    /** Fetch metadata for an existing volume by id or name. */
+    static getInfo(volumeId: string, opts?: VolumeConnectionConfig): Promise<VolumeInfo>;
+    /** List volumes visible to the configured API key. */
+    static list(opts?: VolumeListOpts): Promise<VolumeInfo[]>;
+    /** Destroy a volume by id or name. Returns false when it does not exist. */
+    static destroy(volumeId: string, opts?: VolumeConnectionConfig): Promise<boolean>;
+    /** Alias for `destroy`. */
+    static delete(volumeId: string, opts?: VolumeConnectionConfig): Promise<boolean>;
+    /** Fetch this volume's latest metadata. */
+    getInfo(): Promise<VolumeInfo>;
+    /** Fetch metadata for a path inside this volume. */
+    getInfo(path: string, opts?: ConnectionOpts): Promise<VolumeEntryStat>;
+    /** List files and directories under `path`. */
+    list(path?: string, opts?: VolumeListFilesOpts): Promise<VolumeEntryStat[]>;
+    /** Create a directory inside the detached volume. */
+    makeDir(path: string, opts?: VolumeWriteFileOpts): Promise<VolumeEntryStat>;
+    /** Return whether a path exists inside the detached volume. */
+    exists(path: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Update ownership or mode metadata for a path. */
+    updateMetadata(path: string, opts?: VolumeMetadataOpts): Promise<VolumeEntryStat>;
+    /** Read a file from the detached volume. */
+    readFile(path: string, opts: VolumeReadFileOpts & {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    readFile(path: string, opts: VolumeReadFileOpts & {
+        format: 'blob';
+    }): Promise<Blob>;
+    readFile(path: string, opts: VolumeReadFileOpts & {
+        format: 'stream';
+    }): Promise<ReadableStream<Uint8Array>>;
+    readFile(path: string, opts?: VolumeReadFileOpts): Promise<string>;
+    /** Write a file into the detached volume. */
+    writeFile(path: string, data: VolumeWriteData, opts?: VolumeWriteFileOpts): Promise<VolumeEntryStat>;
+    /** Remove a file or directory from the detached volume. */
+    remove(path: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Destroy this volume. Returns false when it no longer exists. */
+    destroy(opts?: ConnectionOpts): Promise<boolean>;
+    /** Alias for `destroy`. */
+    delete(opts?: ConnectionOpts): Promise<boolean>;
+    private configOptions;
+}

package/dist/volume.js

@@ -0,0 +1,267 @@
+import { Blob } from 'node:buffer';
+import { ConnectionConfig } from './connectionConfig.js';
+import { NotFoundError, SandboxError } from './errors.js';
+import { base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+import { ControlClient, withQuery } from './transport.js';
+/** Persistent volume that can be mounted into sandboxes and edited while detached. */
+export class Volume {
+    volumeId;
+    id;
+    name;
+    token;
+    config;
+    control;
+    constructor(opts) {
+        this.volumeId = String(opts.volumeId);
+        this.id = this.volumeId;
+        this.name = opts.name ?? this.volumeId;
+        this.token = opts.token;
+        this.config = opts.connectionConfig;
+        this.control = opts.control ?? new ControlClient(this.config);
+    }
+    /** Create a persistent volume and return a connected SDK object. */
+    static async create(name, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const payload = await control.post('/volumes', {
+            json: compactRecord({ name, team: opts.team }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeFromPayload(payload, config, control);
+    }
+    /** Connect to an existing volume by id or name. */
+    static async connect(volumeId, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const payload = await control.get(`/volumes/${encodeURIComponent(volumeId)}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeFromPayload(payload, config, control);
+    }
+    /** Fetch metadata for an existing volume by id or name. */
+    static async getInfo(volumeId, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const payload = await control.get(`/volumes/${encodeURIComponent(volumeId)}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeInfo(record(payload.volume ?? payload));
+    }
+    /** List volumes visible to the configured API key. */
+    static async list(opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const path = withQuery('/volumes', { team: opts.team });
+        const payload = await control.get(path, { requestTimeoutMs: opts.requestTimeoutMs });
+        const volumes = Array.isArray(payload.volumes) ? payload.volumes : [];
+        return volumes.map((item) => volumeInfo(record(item)));
+    }
+    /** Destroy a volume by id or name. Returns false when it does not exist. */
+    static async destroy(volumeId, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        try {
+            await control.delete(`/volumes/${encodeURIComponent(volumeId)}`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Alias for `destroy`. */
+    static async delete(volumeId, opts = {}) {
+        return this.destroy(volumeId, opts);
+    }
+    async getInfo(path, opts = {}) {
+        if (path === undefined) {
+            return Volume.getInfo(this.volumeId, this.configOptions(opts));
+        }
+        const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/path`, { path }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    /** List files and directories under `path`. */
+    async list(path = '/', opts = {}) {
+        const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/directories`, {
+            path,
+            depth: opts.depth,
+        }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        const entries = Array.isArray(payload.entries) ? payload.entries : [];
+        return entries.map((item) => volumeEntry(record(item)));
+    }
+    /** Create a directory inside the detached volume. */
+    async makeDir(path, opts = {}) {
+        const payload = await this.control.post(`/volumes/${this.volumeId}/directories`, {
+            json: compactRecord({ path, ...metadataPayload(opts) }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    /** Return whether a path exists inside the detached volume. */
+    async exists(path, opts = {}) {
+        try {
+            await this.getInfo(path, opts);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Update ownership or mode metadata for a path. */
+    async updateMetadata(path, opts = {}) {
+        const payload = await this.control.patch(`/volumes/${this.volumeId}/path`, {
+            json: compactRecord({ path, ...metadataPayload(opts) }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    async readFile(path, opts = {}) {
+        const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/files`, { path }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        const file = record(payload.file ?? payload);
+        const content = file.content_b64 ?? file.contentBase64 ?? file.content ?? '';
+        switch (opts.format ?? 'text') {
+            case 'bytes':
+                return base64DecodeBytes(content);
+            case 'blob':
+                return new Blob([base64DecodeBytes(content)]);
+            case 'stream':
+                return new Blob([base64DecodeBytes(content)]).stream();
+            case 'text':
+                return file.content_b64 || file.contentBase64 ? base64DecodeText(content) : String(content);
+            default:
+                throw new SandboxError(`unsupported volume read format: ${String(opts.format)}`);
+        }
+    }
+    /** Write a file into the detached volume. */
+    async writeFile(path, data, opts = {}) {
+        const bytes = await bytesFromWriteData(data);
+        const payload = await this.control.put(`/volumes/${this.volumeId}/files`, {
+            json: compactRecord({
+                path,
+                content_b64: base64Encode(bytes),
+                ...metadataPayload(opts),
+                force: opts.force,
+            }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    /** Remove a file or directory from the detached volume. */
+    async remove(path, opts = {}) {
+        await this.control.delete(withQuery(`/volumes/${this.volumeId}/path`, { path }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return true;
+    }
+    /** Destroy this volume. Returns false when it no longer exists. */
+    async destroy(opts = {}) {
+        return Volume.destroy(this.volumeId, this.configOptions(opts));
+    }
+    /** Alias for `destroy`. */
+    async delete(opts = {}) {
+        return this.destroy(opts);
+    }
+    configOptions(opts = {}) {
+        return {
+            apiKey: this.config.apiKey,
+            apiUrl: this.config.apiUrl,
+            dataPlaneDomain: this.config.dataPlaneDomain,
+            requestTimeoutMs: this.config.requestTimeoutMs,
+            ...opts,
+        };
+    }
+}
+function volumeFromPayload(payload, config, control) {
+    const info = volumeInfo(record(payload.volume ?? payload));
+    return new Volume({
+        volumeId: info.volumeId,
+        name: info.name,
+        token: info.token,
+        connectionConfig: config,
+        control,
+    });
+}
+function volumeInfo(payload) {
+    const id = payload.volume_id ?? payload.volumeId ?? payload.id;
+    if (id === undefined)
+        throw new SandboxError('volume response did not include id');
+    return {
+        volumeId: String(id),
+        id: String(id),
+        name: String(payload.name ?? id),
+        state: stringValue(payload.state),
+        token: stringValue(payload.token),
+        sizeMb: numberValue(payload.size_mb ?? payload.sizeMb),
+        sizeBytes: numberValue(payload.size_bytes ?? payload.sizeBytes),
+        node: stringValue(payload.node ?? payload.node_name ?? payload.nodeName),
+        metadata: recordOfStrings(payload.metadata),
+        createdAt: stringValue(payload.created_at ?? payload.createdAt),
+        updatedAt: stringValue(payload.updated_at ?? payload.updatedAt),
+        raw: payload,
+    };
+}
+function volumeEntry(payload) {
+    return {
+        path: String(payload.path ?? ''),
+        name: String(payload.name ?? ''),
+        type: String(payload.type ?? 'file'),
+        size: numberValue(payload.size ?? payload.bytes),
+        mode: numberValue(payload.mode),
+        uid: numberValue(payload.uid),
+        gid: numberValue(payload.gid),
+        atime: payload.atime,
+        mtime: payload.mtime,
+        ctime: payload.ctime,
+        raw: payload,
+    };
+}
+async function bytesFromWriteData(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (data instanceof Blob)
+        return new Uint8Array(await data.arrayBuffer());
+    throw new SandboxError('unsupported volume write data');
+}
+function metadataPayload(opts) {
+    return compactRecord({
+        uid: opts.uid,
+        gid: opts.gid,
+        mode: opts.mode,
+    });
+}
+function compactRecord(payload) {
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
+function record(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function recordOfStrings(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' ? value : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.24",
+  "version": "0.1.30",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",
@@ -11,6 +11,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./code-interpreter": {
+      "types": "./dist/codeInterpreter.d.ts",
+      "import": "./dist/codeInterpreter.js"
     }
   },
   "types": "./dist/index.d.ts",