@watasu/sdk 0.1.24 → 0.1.25

package/README.md

@@ -31,6 +31,24 @@ await sbx.betaPause()
 await sbx.resume({ timeoutMs: 300_000 })
 ```
 
+## Code Interpreter
+
+```ts
+import { Sandbox } from '@watasu/sdk/code-interpreter'
+
+const sbx = await Sandbox.create()
+const execution = await sbx.runCode("print('hello')\n2 + 3", {
+  language: 'python',
+  onStdout: (message) => console.log(message.line),
+})
+
+console.log(execution.text)
+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.
+
 ## MCP Gateway
 
 ```ts

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;
+    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, _opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<boolean>;
+    /** List persistent code contexts. */
+    listCodeContexts(_opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<Context[]>;
+    /** Restart a persistent code context. */
+    restartCodeContext(_context: Context, _opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<Context>;
+}

package/dist/codeInterpreter.js

@@ -0,0 +1,241 @@
+import { InvalidArgumentError, NotImplementedError } 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 = {}) {
+        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    }
+    /** Remove a persistent code context. */
+    async removeCodeContext(_context, _opts = {}) {
+        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    }
+    /** List persistent code contexts. */
+    async listCodeContexts(_opts = {}) {
+        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    }
+    /** Restart a persistent code context. */
+    async restartCodeContext(_context, _opts = {}) {
+        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    }
+}
+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) {
+    return context?.id;
+}
+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 { 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 { 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';

package/dist/index.js

@@ -1,6 +1,8 @@
 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';

package/dist/sandbox.d.ts

@@ -142,9 +142,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;
@@ -263,5 +263,7 @@ 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>>;
     private configOptions;
 }

package/dist/sandbox.js

@@ -122,7 +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);
+            : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? this.defaultTemplate : undefined);
         if (sandboxOpts.volumeMounts !== undefined)
             unsupported('volumeMounts');
         const config = new ConnectionConfig(sandboxOpts);
@@ -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,
@@ -458,6 +458,13 @@ 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,
+        });
+    }
     configOptions() {
         return {
             apiKey: this.config.apiKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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",