@watasu/sdk 0.1.6 → 0.1.25

package/README.md

@@ -16,8 +16,8 @@ Set `WATASU_API_KEY` before using the SDK.
 import { Sandbox } from '@watasu/sdk'
 
 const sbx = await Sandbox.create()
-await sbx.files.write('/home/user/a.js', 'console.log(2 + 2)')
-const result = await sbx.commands.run('node /home/user/a.js')
+await sbx.filesystem.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())
 await sbx.kill()
@@ -26,11 +26,67 @@ await sbx.kill()
 `Sandbox.create` and `Sandbox.connect` return only after the Watasu API supplies
 a usable data-plane session. The SDK does not poll sandbox readiness.
 
+```ts
+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
+const sbx = await Sandbox.create({
+  mcp: {
+    github: {
+      command: 'github-mcp-server',
+      args: ['stdio'],
+      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
+    },
+  },
+})
+
+console.log(sbx.getMcpUrl())
+console.log(await sbx.getMcpToken())
+```
+
+## Listing Sandboxes
+
+```ts
+import { Sandbox } from '@watasu/sdk'
+
+const paginator = Sandbox.list({
+  query: { metadata: { purpose: 'ci' }, state: ['running'] },
+  limit: 20,
+})
+
+for (const sandbox of await paginator.listItems()) {
+  console.log(sandbox.sandboxId, sandbox.state)
+}
+```
+
 ## Git, Watch, PTY, And Signed File URLs
 
 ```ts
 const sbx = await Sandbox.create()
 
+await sbx.git.init('/workspace/new-project', { initialBranch: 'main' })
 await sbx.git.clone('https://github.com/acme/project.git', {
   path: '/workspace/project',
   branch: 'main',
@@ -52,17 +108,26 @@ await sbx.git.push('/workspace/project', {
   branch: 'feature/docs',
   setUpstream: true,
 })
+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([
+  { path: '/workspace/project/a.txt', data: 'alpha' },
+  { path: '/workspace/project/b.bin', data: new Uint8Array([0, 1, 2]) },
+])
 
-const watcher = await sbx.files.watchDir('/workspace/project', (event) => {
+const watcher = sbx.filesystem.watchDir('/workspace/project')
+watcher.addEventListener((event) => {
   console.log(event.type, event.path)
-}, { recursive: true })
+})
+await watcher.start({ recursive: true })
 
-const terminal = await sbx.pty.create({
-  cols: 100,
-  rows: 30,
+const terminal = await sbx.terminal.start({
+  size: { cols: 100, rows: 30 },
   onData: (data) => process.stdout.write(data),
 })
-await terminal.sendStdin('echo hello\n')
+await terminal.sendData('echo hello\n')
 
 const uploadUrl = await sbx.uploadUrl('/workspace/input.bin')
 const downloadUrl = await sbx.downloadUrl('/workspace/output.bin')
@@ -72,6 +137,54 @@ await terminal.kill()
 await sbx.kill()
 ```
 
+## Network Policy
+
+```ts
+const sbx = await Sandbox.create({
+  network: {
+    allowOut: ['pypi.org:443'],
+    denyOut: ['169.254.169.254'],
+  },
+})
+
+await sbx.updateNetwork({
+  allowInternetAccess: false,
+  allowPackageRegistryAccess: true,
+  allowOut: ['pypi.org:443', 'registry.npmjs.org:443'],
+})
+```
+
+## Template Builds
+
+```ts
+import { Template } from '@watasu/sdk'
+
+const template = Template()
+  .fromPythonImage('3.12')
+  .copy('requirements.txt', '/workspace/requirements.txt')
+  .aptInstall(['git'])
+  .pipInstall(['pytest'])
+  .setEnvs({ PIP_DISABLE_PIP_VERSION_CHECK: '1' })
+  .runCmd('echo ready')
+
+const build = await Template.buildInBackground(template, 'python-ci:stable', {
+  tags: ['stable'],
+  cpuCount: 2,
+  memoryMB: 2048,
+})
+const status = await Template.getBuildStatus(build)
+
+await Template.assignTags('python-ci:stable', ['prod'])
+console.log(await Template.exists('python-ci'))
+```
+
+Template names resolve server-side. `python-ci` starts the latest ready build;
+`python-ci:stable` starts the tagged build.
+
+`Template({ fileContextPath: process.cwd() }).fromDockerfile('Dockerfile')`
+parses common `FROM`, `WORKDIR`, `COPY`, `RUN`, `ENV`, `CMD`, and `ENTRYPOINT`
+instructions into Watasu's package-spec builder.
+
 ## Metrics And Snapshots
 
 ```ts
@@ -81,6 +194,7 @@ const sbx = await Sandbox.create()
 const metrics = await sbx.getMetrics()
 const snapshot = await sbx.createSnapshot({ name: 'ready' })
 const snapshots = await sbx.listSnapshots().nextItems()
+const allSnapshots = await Sandbox.listSnapshots({ limit: 100 }).nextItems()
 const restored = await sbx.restore({ snapshotId: snapshot.snapshotId })
 await sbx.deleteSnapshot(snapshot.snapshotId)
 await sbx.kill()

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/commands.d.ts

@@ -29,14 +29,26 @@ export interface ProcessInfo {
 export interface CommandStartOpts {
     /** Return a `CommandHandle` immediately instead of waiting for exit. */
     background?: boolean;
+    /** Executable to start directly. When omitted, `cmd` strings run through a login shell. */
+    cmd?: string;
+    /** 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;
 }
 /** Live handle for one sandbox process stream. */
@@ -48,28 +60,31 @@ export declare class CommandHandle implements Partial<CommandResult> {
     private readonly onStdout?;
     private readonly onStderr?;
     private readonly onPty?;
+    private readonly onExit?;
     private _stdout;
     private _stderr;
     private result?;
     private readonly pending;
-    constructor(pid: number | string, socket: ProcessSocket, handleKill: () => Promise<boolean>, events: AsyncIterable<ProcessFrame>, onStdout?: ((data: string) => void | Promise<void>) | undefined, onStderr?: ((data: string) => void | Promise<void>) | undefined, onPty?: ((data: Uint8Array) => void | Promise<void>) | undefined);
+    constructor(pid: number | string, socket: ProcessSocket, handleKill: () => Promise<boolean>, events: AsyncIterable<ProcessFrame>, onStdout?: ((data: string) => void | Promise<void>) | undefined, onStderr?: ((data: string) => void | Promise<void>) | undefined, onPty?: ((data: Uint8Array) => void | Promise<void>) | undefined, onExit?: ((exitCode: number) => void | Promise<void>) | undefined);
     get stdout(): string;
     get stderr(): string;
     get exitCode(): number | undefined;
     get error(): string | undefined;
     /** Wait until the process exits and return captured output. */
-    wait(): Promise<CommandResult>;
+    wait(timeoutMs?: number): Promise<CommandResult>;
     /** Kill the process. */
     kill(): Promise<boolean>;
     /** Send stdin bytes or text to the process. */
     sendStdin(data: string | Uint8Array): Promise<void>;
+    /** Close the stdin stream and signal EOF to the process. */
+    closeStdin(): Promise<void>;
     /** Resize the attached PTY stream when this handle was created as a PTY. */
     resize(size: {
         cols: number;
         rows: number;
     }): Promise<void>;
     /** Detach the local stream without killing the process. */
-    disconnect(): void;
+    disconnect(): Promise<void>;
     private handleEvents;
 }
 /** Command runner for a sandbox data-plane session. */
@@ -78,6 +93,8 @@ export declare class Commands {
     private readonly config;
     private readonly sandboxEnvs;
     constructor(dataPlane: DataPlaneClient, config: ConnectionConfig, sandboxEnvs?: Record<string, string>);
+    /** Whether this runtime supports stdin EOF frames. */
+    get supportsStdinClose(): boolean;
     /** List processes currently known by the sandbox runtime. */
     list(opts?: {
         requestTimeoutMs?: number;
@@ -90,11 +107,16 @@ export declare class Commands {
     sendStdin(pid: number | string, data: string | Uint8Array, opts?: {
         requestTimeoutMs?: number;
     }): Promise<void>;
+    /** Attach to a process and close stdin, signalling EOF. */
+    closeStdin(pid: number | string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
     run(cmd: string, opts: CommandStartOpts & {
         background: true;
     }): Promise<CommandHandle>;
     run(cmd: string, opts?: CommandStartOpts): Promise<CommandResult>;
     /** Reconnect to a live process stream by pid. */
     connect(pid: number | string, opts?: CommandStartOpts): Promise<CommandHandle>;
-    private start;
+    /** Start a command and return a live handle immediately. */
+    start(cmd: string, opts?: CommandStartOpts): Promise<CommandHandle>;
 }