@watasu/sdk 0.1.6 → 0.1.24

package/dist/filesystem.js

@@ -1,6 +1,6 @@
 import { withQuery } from './transport.js';
-import { FileNotFoundError } from './errors.js';
-import { ProcessSocket } from './processSocket.js';
+import { FileNotFoundError, InvalidArgumentError } from './errors.js';
+import { ProcessSocket, base64Encode } from './processSocket.js';
 export var FileType;
 (function (FileType) {
     /** Regular file. */
@@ -50,27 +50,93 @@ export class WatchHandle {
         }
     }
 }
+/** Lazy filesystem watcher. Add listeners, then call `start()`. */
+export class FilesystemWatcher {
+    dataPlane;
+    path;
+    opts;
+    handle;
+    listeners = [];
+    constructor(dataPlane, path, opts = {}) {
+        this.dataPlane = dataPlane;
+        this.path = path;
+        this.opts = opts;
+    }
+    async start(opts = {}) {
+        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();
+        this.handle = new WatchHandle(socket, socket, async (event) => {
+            for (const listener of this.listeners)
+                await listener(event);
+        }, nextOpts.onExit);
+    }
+    async stop() {
+        this.handle?.stop();
+    }
+    addEventListener(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index === -1)
+                return false;
+            this.listeners.splice(index, 1);
+            return true;
+        };
+    }
+    wait() {
+        return this.handle?.wait() ?? Promise.resolve();
+    }
+}
 /** Filesystem helper for a sandbox data-plane session. */
 export class Filesystem {
     dataPlane;
     constructor(dataPlane) {
         this.dataPlane = dataPlane;
     }
-    /** Read a file as UTF-8 text, bytes, or a one-chunk async byte stream. */
     async read(path, opts = {}) {
         const bytes = await this.dataPlane.getBytes(withQuery('/runtime/v1/files', { path, gzip: opts.gzip }), opts);
         if (opts.format === 'bytes')
             return bytes;
+        if (opts.format === 'blob')
+            return new Blob([toArrayBuffer(bytes)]);
         if (opts.format === 'stream')
-            return (async function* () { yield bytes; })();
+            return new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } });
         return new TextDecoder().decode(bytes);
     }
-    /** Write UTF-8 text or bytes to a file. */
-    async write(path, data, opts = {}) {
-        const body = typeof data === 'string' ? new TextEncoder().encode(data) : data;
-        const payload = await this.dataPlane.putJson(withQuery('/runtime/v1/files', { path, gzip: opts.gzip }), body, opts);
+    /** Read a file as raw bytes. */
+    async readBytes(path, opts = {}) {
+        return this.read(path, { ...opts, format: 'bytes' });
+    }
+    async write(pathOrFiles, dataOrOpts, opts = {}) {
+        if (Array.isArray(pathOrFiles)) {
+            return this.writeFiles(pathOrFiles, dataOrOpts);
+        }
+        const body = await writeDataToBytes(dataOrOpts);
+        const payload = await this.dataPlane.putJson(withQuery('/runtime/v1/files', { path: pathOrFiles, gzip: opts.gzip }), body, opts);
         return entryInfo(payload.file ?? payload);
     }
+    /** Write raw bytes to a file. */
+    async writeBytes(path, data, opts = {}) {
+        return this.write(path, data, opts);
+    }
+    /** Write several files in one runtime API call. */
+    async writeFiles(files, opts = {}) {
+        if (files.length === 0)
+            return [];
+        const payload = await this.dataPlane.postJson('/runtime/v1/files/write_files', {
+            ...opts,
+            json: {
+                files: await Promise.all(files.map(async (file) => ({
+                    path: file.path,
+                    data_base64: base64Encode(await writeDataToBytes(file.data)),
+                }))),
+            },
+        });
+        const written = Array.isArray(payload.files) ? payload.files : [];
+        return written.map(entryInfo);
+    }
     /** List directory entries below `path`. */
     async list(path, opts = {}) {
         const payload = await this.dataPlane.getJson(withQuery('/runtime/v1/directories', { path, depth: opts.depth }), opts);
@@ -111,11 +177,61 @@ export class Filesystem {
         await this.dataPlane.postJson(withQuery('/runtime/v1/directories', { path }), opts);
         return true;
     }
-    /** Start watching a directory for filesystem events. */
-    async watchDir(path, onEvent, opts = {}) {
-        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, withQuery('/runtime/v1/files/watch', { path, recursive: opts.recursive ?? false, include_entry: opts.includeEntry }), opts.requestTimeoutMs).connect();
-        return new WatchHandle(socket, socket, onEvent, opts.onExit);
+    watchDir(path, onEvent, opts = {}) {
+        const watcher = new FilesystemWatcher(this.dataPlane, path, opts);
+        if (!onEvent)
+            return watcher;
+        watcher.addEventListener(onEvent);
+        return watcher.start().then(() => watcher);
+    }
+}
+async function writeDataToBytes(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 (typeof Blob !== 'undefined' && data instanceof Blob)
+        return new Uint8Array(await data.arrayBuffer());
+    if (isReadableStream(data))
+        return readStreamToBytes(data);
+    throw new InvalidArgumentError(`Unsupported file data type: ${Object.prototype.toString.call(data)}`);
+}
+function toArrayBuffer(bytes) {
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    return buffer;
+}
+function isReadableStream(value) {
+    return Boolean(value && typeof value === 'object' && typeof value.getReader === 'function');
+}
+async function readStreamToBytes(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!(value instanceof Uint8Array)) {
+                throw new InvalidArgumentError('ReadableStream file data must yield Uint8Array chunks');
+            }
+            chunks.push(value);
+            total += value.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
     }
+    return bytes;
 }
 function entryInfo(value) {
     const item = value && typeof value === 'object' ? value : {};

package/dist/git.d.ts

@@ -18,6 +18,8 @@ export interface GitAuthOpts {
     username?: string;
     password?: string;
     envs?: Record<string, string>;
+    user?: string;
+    cwd?: string;
     timeout?: number;
     timeoutMs?: number;
     requestTimeoutMs?: number;
@@ -32,6 +34,10 @@ export interface GitCloneOpts extends GitAuthOpts {
 }
 export interface GitRequestOpts extends GitAuthOpts {
 }
+export interface GitInitOpts extends GitRequestOpts {
+    bare?: boolean;
+    initialBranch?: string;
+}
 export interface GitPullOpts extends GitAuthOpts {
     branch?: string;
     remote?: string;
@@ -54,12 +60,25 @@ export interface GitBranchOpts extends GitRequestOpts {
 }
 export interface GitAddOpts extends GitRequestOpts {
     files?: string[];
+    all?: boolean;
 }
 export interface GitCommitOpts extends GitRequestOpts {
     authorName?: string;
     authorEmail?: string;
     allowEmpty?: boolean;
 }
+export type GitResetMode = 'soft' | 'mixed' | 'hard' | 'merge' | 'keep';
+export interface GitResetOpts extends GitRequestOpts {
+    mode?: GitResetMode;
+    target?: string;
+    paths?: string[];
+}
+export interface GitRestoreOpts extends GitRequestOpts {
+    paths: string[];
+    staged?: boolean;
+    worktree?: boolean;
+    source?: string;
+}
 export interface GitRemoteAddOpts extends GitRequestOpts {
     fetch?: boolean;
     overwrite?: boolean;
@@ -114,6 +133,8 @@ export declare class Git {
     }): Promise<GitCommandResult>;
     /** Configure Git author identity globally or for one repository. */
     configureUser(name: string, email: string, opts?: GitConfigureUserOpts): Promise<GitCommandResult>;
+    /** Initialize a Git repository. */
+    init(path: string, opts?: GitInitOpts): Promise<GitCommandResult>;
     /** Return parsed repository status for `path`. */
     status(path: string, opts?: GitRequestOpts): Promise<GitStatus>;
     /** Return branches and the current branch for `path`. */
@@ -126,6 +147,10 @@ export declare class Git {
     add(path: string, opts?: GitAddOpts): Promise<GitCommandResult>;
     /** Commit staged files. */
     commit(path: string, message: string, opts?: GitCommitOpts): Promise<GitCommandResult>;
+    /** Reset the current HEAD to a specified state. */
+    reset(path: string, opts?: GitResetOpts): Promise<GitCommandResult>;
+    /** Restore working tree files or unstage changes. */
+    restore(path: string, opts: GitRestoreOpts): Promise<GitCommandResult>;
     /** Pull the current branch with a fast-forward-only merge. */
     pull(path: string, opts?: GitPullOpts): Promise<GitCommandResult>;
     /** Push the current branch or a selected branch. */
@@ -136,6 +161,8 @@ export declare class Git {
     checkoutBranch(path: string, branch: string, opts?: GitRequestOpts): Promise<GitCommandResult>;
     /** Add a remote. */
     remoteAdd(path: string, name: string, url: string, opts?: GitRemoteAddOpts): Promise<GitCommandResult>;
+    /** Return a remote URL, or undefined when the remote does not exist. */
+    remoteGet(path: string, name: string, opts?: GitRequestOpts): Promise<string | undefined>;
     /** Set a Git config value. */
     setConfig(key: string, value: string, opts?: GitConfigOpts): Promise<GitCommandResult>;
     /** Read a Git config value. */

package/dist/git.js

@@ -33,6 +33,15 @@ export class Git {
             path: opts.path,
         }, opts);
     }
+    /** Initialize a Git repository. */
+    async init(path, opts = {}) {
+        return this.run('/runtime/v1/git/init', {
+            path,
+            bare: opts.bare,
+            initial_branch: opts.initialBranch,
+            ...gitOpts(opts),
+        }, opts);
+    }
     /** Return parsed repository status for `path`. */
     async status(path, opts = {}) {
         const result = await this.run('/runtime/v1/git/status', { path, ...gitOpts(opts) }, opts);
@@ -58,7 +67,7 @@ export class Git {
     }
     /** Stage files. Defaults to all files. */
     async add(path, opts = {}) {
-        return this.run('/runtime/v1/git/add', { path, files: opts.files, ...gitOpts(opts) }, opts);
+        return this.run('/runtime/v1/git/add', { path, files: opts.files, all: opts.all, ...gitOpts(opts) }, opts);
     }
     /** Commit staged files. */
     async commit(path, message, opts = {}) {
@@ -71,6 +80,27 @@ export class Git {
             ...gitOpts(opts),
         }, opts);
     }
+    /** Reset the current HEAD to a specified state. */
+    async reset(path, opts = {}) {
+        return this.run('/runtime/v1/git/reset', {
+            path,
+            mode: opts.mode,
+            target: opts.target,
+            paths: opts.paths,
+            ...gitOpts(opts),
+        }, opts);
+    }
+    /** Restore working tree files or unstage changes. */
+    async restore(path, opts) {
+        return this.run('/runtime/v1/git/restore', {
+            path,
+            paths: opts.paths,
+            staged: opts.staged,
+            worktree: opts.worktree,
+            source: opts.source,
+            ...gitOpts(opts),
+        }, opts);
+    }
     /** Pull the current branch with a fast-forward-only merge. */
     async pull(path, opts = {}) {
         return this.run('/runtime/v1/git/pull', { path, ...gitOpts(opts), ...pick(opts, ['remote', 'branch', 'username', 'password']) }, opts);
@@ -81,7 +111,7 @@ export class Git {
             path,
             ...gitOpts(opts),
             ...pick(opts, ['remote', 'branch', 'username', 'password']),
-            set_upstream: opts.setUpstream,
+            set_upstream: opts.setUpstream ?? true,
         }, opts);
     }
     /** Check out an arbitrary ref in a repository. */
@@ -103,6 +133,15 @@ export class Git {
             ...gitOpts(opts),
         }, opts);
     }
+    /** Return a remote URL, or undefined when the remote does not exist. */
+    async remoteGet(path, name, opts = {}) {
+        const result = await this.run('/runtime/v1/git/remote_get', {
+            path,
+            name,
+            ...gitOpts(opts),
+        }, opts);
+        return result.value ?? result.url;
+    }
     /** Set a Git config value. */
     async setConfig(key, value, opts = {}) {
         return this.run('/runtime/v1/git/set_config', {
@@ -131,6 +170,8 @@ export class Git {
 function gitOpts(opts) {
     return {
         env_vars: opts.envs,
+        user: opts.user,
+        cwd: opts.cwd,
         timeout_seconds: opts.timeout ?? (opts.timeoutMs === undefined ? undefined : Math.ceil(opts.timeoutMs / 1000)),
     };
 }

package/dist/index.d.ts

@@ -1,13 +1,19 @@
-export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.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 { Sandbox, SnapshotPaginator } from './sandbox.js';
-export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxMetrics, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.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 { CommandExitError, CommandHandle, Commands } from './commands.js';
 export type { CommandResult, CommandStartOpts, ProcessInfo } from './commands.js';
-export { FileType, Filesystem, WatchHandle } from './filesystem.js';
-export type { EntryInfo, FilesystemEvent, WatchOpts, WriteInfo } from './filesystem.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, GitConfigOpts, GitConfigureUserOpts, GitCredentialOpts, GitCommitOpts, GitFileStatus, GitPullOpts, GitPushOpts, GitRemoteAddOpts, GitRequestOpts, GitStatus, } from './git.js';
+export type { GitAddOpts, GitAuthOpts, GitBranches, GitBranchOpts, GitCloneOpts, GitCommandResult, GitConfigOpts, GitConfigureUserOpts, GitCredentialOpts, GitCommitOpts, GitFileStatus, GitInitOpts, GitPullOpts, GitPushOpts, GitRemoteAddOpts, GitResetMode, GitResetOpts, GitRestoreOpts, GitRequestOpts, 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 { 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,8 +1,11 @@
-export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.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 { Sandbox, SnapshotPaginator } from './sandbox.js';
+export { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
-export { FileType, Filesystem, WatchHandle } from './filesystem.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 { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';

package/dist/process.d.ts

@@ -0,0 +1,56 @@
+import { CommandHandle, CommandResult, Commands, CommandStartOpts } from './commands.js';
+/** A message emitted by a sandbox process. */
+export declare class ProcessMessage {
+    readonly line: string;
+    /** Unix epoch in nanoseconds. */
+    readonly timestamp: number;
+    readonly error: boolean;
+    constructor(line: string, 
+    /** Unix epoch in nanoseconds. */
+    timestamp: number, error: boolean);
+    toString(): string;
+}
+/** Captured output from a sandbox process. */
+export declare class ProcessOutput {
+    private messages;
+    private _finished;
+    private _error;
+    private _exitCode;
+    get error(): boolean;
+    get exitCode(): number | undefined;
+    get stdout(): string;
+    get stderr(): string;
+    addStdout(message: ProcessMessage): void;
+    addStderr(message: ProcessMessage): void;
+    setExitCode(exitCode: number): void;
+    replace(result: CommandResult): void;
+}
+export interface ProcessOpts extends Omit<CommandStartOpts, 'cmd' | 'args' | 'onStdout' | 'onStderr' | 'onExit'> {
+    cmd: string;
+    onStdout?: (out: ProcessMessage) => Promise<void> | void;
+    onStderr?: (out: ProcessMessage) => Promise<void> | void;
+    onExit?: ((exitCode: number) => Promise<void> | void) | (() => Promise<void> | void);
+}
+/** A running sandbox process. */
+export declare class Process {
+    readonly processID: string;
+    private readonly handle;
+    readonly output: ProcessOutput;
+    private readonly onExit?;
+    readonly finished: Promise<ProcessOutput>;
+    private waitPromise?;
+    constructor(processID: string, handle: CommandHandle, output: ProcessOutput, onExit?: ((exitCode: number) => Promise<void> | void) | undefined);
+    kill(): Promise<void>;
+    wait(timeout?: number): Promise<ProcessOutput>;
+    private waitOnce;
+    sendStdin(data: string): Promise<void>;
+}
+/** Manager for starting and interacting with sandbox processes. */
+export declare class ProcessManager {
+    private readonly commands;
+    constructor(commands: Commands);
+    start(cmd: string): Promise<Process>;
+    start(opts: ProcessOpts): Promise<Process>;
+    startAndWait(cmd: string): Promise<ProcessOutput>;
+    startAndWait(opts: ProcessOpts): Promise<ProcessOutput>;
+}

package/dist/process.js

@@ -0,0 +1,137 @@
+import { CommandExitError } from './commands.js';
+import { TimeoutError } from './errors.js';
+/** A message emitted by a sandbox process. */
+export class ProcessMessage {
+    line;
+    timestamp;
+    error;
+    constructor(line, 
+    /** Unix epoch in nanoseconds. */
+    timestamp, error) {
+        this.line = line;
+        this.timestamp = timestamp;
+        this.error = error;
+    }
+    toString() {
+        return this.line;
+    }
+}
+/** Captured output from a sandbox process. */
+export class ProcessOutput {
+    messages = [];
+    _finished = false;
+    _error = false;
+    _exitCode;
+    get error() { return this._error; }
+    get exitCode() { return this._exitCode; }
+    get stdout() { return this.messages.filter((message) => !message.error).map(String).join(''); }
+    get stderr() { return this.messages.filter((message) => message.error).map(String).join(''); }
+    addStdout(message) {
+        this.messages.push(message);
+    }
+    addStderr(message) {
+        this.messages.push(message);
+        this._error = true;
+    }
+    setExitCode(exitCode) {
+        this._exitCode = exitCode;
+        this._finished = true;
+        if (exitCode !== 0)
+            this._error = true;
+    }
+    replace(result) {
+        this.messages = [];
+        if (result.stdout)
+            this.addStdout(processMessage(result.stdout, false));
+        if (result.stderr)
+            this.addStderr(processMessage(result.stderr, true));
+        this.setExitCode(result.exitCode);
+    }
+}
+/** A running sandbox process. */
+export class Process {
+    processID;
+    handle;
+    output;
+    onExit;
+    finished;
+    waitPromise;
+    constructor(processID, handle, output, onExit) {
+        this.processID = processID;
+        this.handle = handle;
+        this.output = output;
+        this.onExit = onExit;
+        this.waitPromise = this.waitOnce();
+        this.finished = this.waitPromise;
+    }
+    async kill() {
+        await this.handle.kill();
+    }
+    async wait(timeout) {
+        if (!this.waitPromise)
+            this.waitPromise = this.waitOnce();
+        return waitFor(this.waitPromise, timeout);
+    }
+    async waitOnce() {
+        try {
+            this.output.replace(await this.handle.wait());
+        }
+        catch (error) {
+            if (error instanceof CommandExitError) {
+                this.output.replace(error);
+            }
+            else {
+                throw error;
+            }
+        }
+        await this.onExit?.(this.output.exitCode ?? 0);
+        return this.output;
+    }
+    async sendStdin(data) {
+        await this.handle.sendStdin(data);
+    }
+}
+function waitFor(promise, timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError()), timeoutMs);
+        promise.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
+/** Manager for starting and interacting with sandbox processes. */
+export class ProcessManager {
+    commands;
+    constructor(commands) {
+        this.commands = commands;
+    }
+    async start(cmdOrOpts) {
+        const opts = processOpts(cmdOrOpts);
+        const { cmd, onStdout, onStderr, onExit, ...commandOpts } = opts;
+        const output = new ProcessOutput();
+        const handle = await this.commands.start(cmd, {
+            ...commandOpts,
+            onStdout: async (data) => {
+                const message = processMessage(data, false);
+                output.addStdout(message);
+                await onStdout?.(message);
+            },
+            onStderr: async (data) => {
+                const message = processMessage(data, true);
+                output.addStderr(message);
+                await onStderr?.(message);
+            },
+        });
+        return new Process(String(handle.pid), handle, output, onExit);
+    }
+    async startAndWait(cmdOrOpts) {
+        const process = await this.start(cmdOrOpts);
+        return process.wait(typeof cmdOrOpts === 'string' ? undefined : cmdOrOpts.timeout);
+    }
+}
+function processOpts(cmdOrOpts) {
+    return typeof cmdOrOpts === 'string' ? { cmd: cmdOrOpts } : cmdOrOpts;
+}
+function processMessage(line, error) {
+    return new ProcessMessage(line, Date.now() * 1_000_000, error);
+}

package/dist/processSocket.d.ts

@@ -14,6 +14,7 @@ export declare class ProcessSocket implements AsyncIterable<ProcessFrame> {
     connect(): Promise<this>;
     sendJson(payload: ProcessFrame): void;
     sendStdin(data: string | Uint8Array): void;
+    closeStdin(): void;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<ProcessFrame>;
     private next;

package/dist/processSocket.js

@@ -55,6 +55,9 @@ export class ProcessSocket {
         const raw = typeof data === 'string' ? new TextEncoder().encode(data) : data;
         this.sendJson({ type: 'stdin', data: base64Encode(raw) });
     }
+    closeStdin() {
+        this.sendJson({ type: 'close_stdin' });
+    }
     close() {
         this.closed = true;
         if (this.keepalive)

package/dist/pty.d.ts

@@ -5,7 +5,11 @@ export interface PtySize {
     cols: number;
     rows: number;
 }
-export interface PtyCreateOpts extends Omit<CommandStartOpts, 'background' | 'onStdout' | 'onStderr'>, PtySize {
+export interface PtyCreateOpts extends Omit<CommandStartOpts, 'background' | 'onStdout' | 'onStderr'> {
+    cols?: number;
+    rows?: number;
+    size?: PtySize;
+    cmd?: string;
     onData?: (data: Uint8Array) => void | Promise<void>;
 }
 export interface PtyConnectOpts {

package/dist/pty.js

@@ -12,18 +12,20 @@ export class Pty {
     /** Create an interactive shell PTY and return its live command handle. */
     async create(opts) {
         const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
-        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envs ?? {}) };
+        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envVars ?? opts.envs ?? {}) };
+        const size = opts.size ?? { cols: opts.cols ?? 80, rows: opts.rows ?? 24 };
+        const args = opts.cmd === undefined ? ['-i', '-l'] : ['-l', '-c', opts.cmd];
         socket.sendJson({
             type: 'start',
             cmd: '/bin/bash',
-            args: ['-i', '-l'],
-            cwd: opts.cwd,
+            args,
+            cwd: opts.cwd ?? opts.rootDir,
             user: opts.user,
             environment: envs,
             envs,
             stdin: true,
-            pty: { cols: opts.cols, rows: opts.rows },
-            timeout_ms: opts.timeoutMs ?? 60_000,
+            pty: { cols: size.cols, rows: size.rows },
+            timeout_ms: opts.timeoutMs ?? opts.timeout ?? 60_000,
         });
         const first = await nextStarted(socket);
         const pid = framePid(first);
@@ -45,7 +47,7 @@ export class Pty {
             await handle.sendStdin(data);
         }
         finally {
-            handle.disconnect();
+            await handle.disconnect();
         }
     }
     /** Alias for `sendStdin`. */
@@ -59,7 +61,7 @@ export class Pty {
             await handle.resize(size);
         }
         finally {
-            handle.disconnect();
+            await handle.disconnect();
         }
     }
     /** Kill a running PTY. */