@watasu/sdk 0.1.51 → 0.1.66

package/dist/git.js

@@ -1,3 +1,4 @@
+import { InvalidArgumentError } from './errors.js';
 /** Git helper backed by sandbox data-plane routes. */
 export class Git {
     dataPlane;
@@ -162,6 +163,31 @@ export class Git {
         }, opts);
         return String(result.value ?? '');
     }
+    async getRemoteUrl(path, remote, opts = {}) {
+        const url = await this.remoteGet(path, remote, opts);
+        if (!url) {
+            throw new InvalidArgumentError(`Remote "${remote}" URL not found in repository.`);
+        }
+        return url;
+    }
+    async resolveRemoteName(path, remote, opts = {}) {
+        if (remote)
+            return remote;
+        const status = await this.status(path, opts);
+        const upstreamRemote = status.upstream?.split('/')[0];
+        if (upstreamRemote)
+            return upstreamRemote;
+        throw new InvalidArgumentError('Remote is required when the repository has no upstream remote.');
+    }
+    async hasUpstream(path, opts = {}) {
+        try {
+            const status = await this.status(path, opts);
+            return Boolean(status.upstream);
+        }
+        catch {
+            return false;
+        }
+    }
     async run(path, json, opts) {
         const payload = await this.dataPlane.postJson(path, {
             json: compact(json),
@@ -173,7 +199,7 @@ export class Git {
 }
 function gitOpts(opts) {
     return {
-        env_vars: opts.envs,
+        envs: opts.envs,
         user: opts.user,
         cwd: opts.cwd,
         timeout_seconds: opts.timeoutMs === undefined ? undefined : Math.ceil(opts.timeoutMs / 1000),

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export type { CommandConnectOpts, CommandRequestOpts, CommandResult, CommandStar
 export { Process, ProcessManager, ProcessMessage, ProcessOutput } from './process.js';
 export type { ProcessOpts } from './process.js';
 export { FileType, Filesystem, FilesystemEventType, FilesystemWatcher, WatchHandle, } from './filesystem.js';
-export type { EntryInfo, FilesystemEvent, FilesystemReadOpts, FilesystemRequestOpts, FilesystemWriteOpts, WatchOpts, WriteData, WriteEntry, WriteInfo, } from './filesystem.js';
+export type { ApplyDiffFailure, ApplyDiffFailedHunk, ApplyDiffFileSummary, ApplyDiffOpts, ApplyDiffReport, ApplyDiffSummary, 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, GitConfigScope, GitConfigOpts, GitConfigureUserOpts, GitCredentialOpts, GitCommitOpts, GitDangerouslyAuthenticateOpts, GitDeleteBranchOpts, GitFileStatus, GitInitOpts, GitPullOpts, GitPushOpts, GitRemoteAddOpts, GitResetMode, GitResetOpts, GitRestoreOpts, GitRequestOpts, GitStatus, } from './git.js';
 export { Pty } from './pty.js';

package/dist/pty.d.ts

@@ -1,16 +1,21 @@
-import { CommandHandle, CommandStartOpts } from './commands.js';
-import { ConnectionConfig, type ConnectionOpts } from './connectionConfig.js';
+import { CommandHandle } from './commands.js';
+import { ConnectionConfig, type ConnectionOpts, type Username } from './connectionConfig.js';
 import { DataPlaneClient } from './transport.js';
 export interface PtySize {
     cols: number;
     rows: number;
 }
-export interface PtyCreateOpts extends Omit<CommandStartOpts, 'background' | 'onStdout' | 'onStderr'> {
+export interface PtyCreateOpts extends Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'> {
     cols?: number;
     rows?: number;
     size?: PtySize;
     cmd?: string;
+    cwd?: string;
+    user?: Username;
+    envs?: Record<string, string>;
+    timeoutMs?: number;
     onData?: (data: Uint8Array) => void | Promise<void>;
+    onPty?: (data: Uint8Array) => void | Promise<void>;
 }
 export interface PtyConnectOpts {
     onData?: (data: Uint8Array) => void | Promise<void>;

package/dist/sandbox.d.ts

@@ -81,31 +81,55 @@ export interface SandboxListOpts extends ConnectionOpts {
     /** Team slug to list within. */
     team?: string;
 }
-type SandboxRequestOpts = Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'>;
 export interface SandboxInfo {
     sandboxId: string;
     templateId?: string;
     name?: string;
     state?: string;
+    cpuCount?: number;
+    memoryMB?: number;
+    envdVersion?: string;
+    allowInternetAccess?: boolean;
+    network?: SandboxNetworkInfo;
+    sandboxDomain?: string;
     lifecycle?: SandboxInfoLifecycle;
     volumeMounts?: Array<{
         name: string;
         path: string;
     }>;
     metadata: Record<string, string>;
-    startedAt?: string;
-    endAt?: string;
+    startedAt?: Date;
+    endAt?: Date;
 }
 export interface SandboxInfoLifecycle {
     onTimeout: 'kill' | 'pause' | string;
     autoResume: boolean;
 }
+type SandboxConnectionDetails = {
+    sandboxId: string;
+    sandboxDomain: string | undefined;
+    envdVersion: string;
+    envdAccessToken: string | undefined;
+    trafficAccessToken: string | undefined;
+    connectionConfig: ConnectionConfig;
+    control: ControlClient;
+    session: unknown;
+    sandbox: Record<string, unknown>;
+    envs?: Record<string, string>;
+};
 export interface SandboxMetrics {
+    timestamp?: Date;
     sandboxId?: string;
     state?: string;
     node?: string;
     backend?: string;
     cpuCount?: number;
+    cpuUsedPct?: number;
+    memUsed?: number;
+    memTotal?: number;
+    memCache?: number;
+    diskUsed?: number;
+    diskTotal?: number;
     memoryMb?: number;
     raw: Record<string, unknown>;
 }
@@ -117,6 +141,7 @@ export interface SandboxMetricsOpts extends ConnectionOpts {
 }
 export interface SnapshotInfo {
     snapshotId: string;
+    names: string[];
     sandboxId?: string;
     name?: string;
     status?: string;
@@ -196,22 +221,28 @@ 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: string;
+    protected static readonly defaultTemplate: string;
     /** Default template slug used by MCP creation once Watasu supports it. */
-    static readonly defaultMcpTemplate: string;
+    protected static readonly defaultMcpTemplate: string;
     /** Default sandbox lifetime in milliseconds. */
-    static readonly defaultSandboxTimeoutMs = 300000;
-    files: Filesystem;
-    commands: Commands;
-    process: ProcessManager;
-    pty: Pty;
-    terminal: TerminalManager;
-    git: Git;
+    protected static readonly defaultSandboxTimeoutMs = 300000;
+    readonly files: Filesystem;
+    readonly commands: Commands;
+    readonly process: ProcessManager;
+    readonly pty: Pty;
+    readonly terminal: TerminalManager;
+    readonly git: Git;
     cwd: string | undefined;
     readonly sandboxId: string;
-    private readonly mcpPort;
-    private mcpToken;
-    private readonly config;
+    readonly sandboxDomain: string;
+    readonly trafficAccessToken?: string;
+    protected readonly mcpPort = 50005;
+    protected readonly envdPort = 49983;
+    protected readonly connectionConfig: ConnectionConfig;
+    protected readonly envdAccessToken?: string;
+    private readonly envdApiUrl;
+    private readonly envdDirectUrl;
+    private mcpToken?;
     private readonly control;
     private readonly envs;
     private dataPlane;
@@ -226,10 +257,13 @@ export declare class Sandbox {
     });
     /** Unique sandbox identifier. */
     get id(): string;
-    static create(opts?: SandboxCreateOpts): Promise<Sandbox>;
-    static create(template: string, opts?: SandboxCreateOpts): Promise<Sandbox>;
+    static create<S extends typeof Sandbox>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>;
+    static create<S extends typeof Sandbox>(this: S, template: string, opts?: SandboxOpts): Promise<InstanceType<S>>;
+    protected static createSandbox(template: string, timeoutMs: number, opts?: SandboxCreateOpts): Promise<SandboxConnectionDetails>;
+    protected static createSandbox(template: string | undefined, timeoutMs: number, opts?: SandboxCreateOpts): Promise<SandboxConnectionDetails>;
     /** Connect to an existing sandbox and return it with a fresh data-plane session. */
-    static connect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
+    static connect<S extends typeof Sandbox>(this: S, sandboxId: string, opts?: SandboxConnectOpts): Promise<InstanceType<S>>;
+    protected static connectSandbox(sandboxId: string, opts?: SandboxConnectOpts): Promise<SandboxConnectionDetails>;
     /** Refresh this sandbox's data-plane session in place. */
     connect(opts?: SandboxConnectOpts): Promise<this>;
     /** Resume a paused sandbox by id. */
@@ -239,7 +273,7 @@ export declare class Sandbox {
     /** Pause a sandbox by id. */
     static pause(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy a sandbox by id. */
-    static kill(sandboxId: string, opts?: ConnectionOpts | string): Promise<boolean>;
+    static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Fetch sandbox metrics by id. */
     static getMetrics(sandboxId: string, opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Atomically replace a sandbox's network egress policy by id. */
@@ -252,19 +286,19 @@ export declare class Sandbox {
     /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this sandbox. */
-    kill(opts?: SandboxRequestOpts): Promise<boolean>;
+    kill(opts?: Pick<SandboxOpts, 'requestTimeoutMs' | 'signal'>): Promise<boolean>;
     /** Check if this sandbox is in a runtime-active lifecycle state. */
-    isRunning(opts?: SandboxRequestOpts): Promise<boolean>;
+    isRunning(opts?: Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'>): Promise<boolean>;
     /** Set a sandbox's lifetime by id. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /** Set this sandbox's lifetime. */
-    setTimeout(timeoutMs: number, opts?: SandboxRequestOpts): Promise<void>;
+    setTimeout(timeoutMs: number, opts?: Pick<SandboxOpts, 'requestTimeoutMs' | 'signal'>): Promise<void>;
     /** Fetch control-plane metadata for a sandbox by id. */
     static getInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch full control-plane metadata for a sandbox by id. */
     static getFullInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch the latest control-plane metadata for this sandbox. */
-    getInfo(opts?: SandboxRequestOpts): Promise<SandboxInfo>;
+    getInfo(opts?: Pick<SandboxOpts, 'requestTimeoutMs' | 'signal'>): Promise<SandboxInfo>;
     /** Fetch latest sandbox metrics. */
     getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Create a Watasu checkpoint using snapshot naming. */
@@ -276,7 +310,7 @@ export declare class Sandbox {
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
     restore(opts?: RestoreSnapshotOpts | string | number): Promise<SandboxInfo>;
     /** Return a paginator for sandboxes visible to the configured API key. */
-    static list(opts?: SandboxListOpts | string): SandboxPaginator;
+    static list(opts?: SandboxListOpts): SandboxPaginator;
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port: number): string;
     /** Return the conventional MCP URL for this sandbox. */
@@ -292,7 +326,7 @@ export declare class Sandbox {
     /** Get signed download URL metadata for a sandbox file path. */
     downloadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
     /** Atomically replace this sandbox's network egress policy. */
-    updateNetwork(network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
+    updateNetwork(network: SandboxNetworkUpdate, opts?: Pick<SandboxOpts, 'requestTimeoutMs' | 'signal'>): Promise<void>;
     /** Pause this sandbox. Returns false when it was already paused. */
     betaPause(opts?: ConnectionOpts): Promise<boolean>;
     /** Pause this sandbox. Returns false when it was already paused. */
@@ -300,12 +334,14 @@ export declare class Sandbox {
     /** Resume this sandbox and refresh its data-plane session. */
     resume(opts?: SandboxConnectOpts): Promise<boolean>;
     private fileUrl;
+    /** Base URL for the sandbox data-plane runtime API. */
+    protected get runtimeBaseUrl(): string;
     /** 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;
+    private resolveApiOpts;
 }
 export {};

package/dist/sandbox.js

@@ -101,25 +101,37 @@ export class Sandbox {
     git;
     cwd;
     sandboxId;
+    sandboxDomain;
+    trafficAccessToken;
     mcpPort = 50005;
+    envdPort = 49983;
+    connectionConfig;
+    envdAccessToken;
+    envdApiUrl;
+    envdDirectUrl;
     mcpToken;
-    config;
     control;
     envs;
     dataPlane;
     sandbox;
     constructor(opts) {
         this.sandboxId = String(opts.sandboxId);
-        this.config = opts.connectionConfig;
-        this.control = opts.control ?? new ControlClient(this.config);
+        this.connectionConfig = opts.connectionConfig;
+        this.control = opts.control ?? new ControlClient(this.connectionConfig);
         this.envs = opts.envs ?? {};
         this.sandbox = opts.sandbox ?? {};
-        const dataPlane = dataPlaneFromSession(opts.session, this.config);
+        const session = record(opts.session);
+        this.sandboxDomain = stringValue(session.sandbox_domain ?? session.sandboxDomain ?? this.sandbox.sandbox_domain ?? this.sandbox.domain) ?? '';
+        this.trafficAccessToken = stringValue(session.traffic_access_token ?? session.trafficAccessToken ?? this.sandbox.traffic_access_token ?? this.sandbox.trafficAccessToken);
+        this.envdAccessToken = stringValue(session.envd_access_token ?? session.envdAccessToken ?? session.token);
+        const dataPlane = dataPlaneFromSession(opts.session, this.connectionConfig);
         this.dataPlane = dataPlane;
+        this.envdApiUrl = dataPlane.baseUrl;
+        this.envdDirectUrl = dataPlane.baseUrl;
         this.files = new Filesystem(dataPlane);
-        this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.commands = new Commands(dataPlane, this.connectionConfig, this.envs);
         this.process = new ProcessManager(this.commands);
-        this.pty = new Pty(dataPlane, this.config);
+        this.pty = new Pty(dataPlane, this.connectionConfig);
         this.terminal = new TerminalManager(this.pty);
         this.git = new Git(dataPlane);
     }
@@ -133,42 +145,62 @@ export class Sandbox {
         const template = typeof templateOrOpts === 'string'
             ? templateOrOpts
             : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? this.defaultTemplate : undefined);
-        const config = new ConnectionConfig(sandboxOpts);
+        const sandboxInfo = await this.createSandbox(template, sandboxOpts.timeoutMs ?? this.defaultSandboxTimeoutMs, sandboxOpts);
+        return new this({
+            sandboxId: sandboxInfo.sandboxId,
+            connectionConfig: sandboxInfo.connectionConfig,
+            control: sandboxInfo.control,
+            session: sandboxInfo.session,
+            sandbox: sandboxInfo.sandbox,
+            envs: sandboxInfo.envs,
+        });
+    }
+    static async createSandbox(template, timeoutMs, opts = {}) {
+        const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
         const sandboxPayload = {
-            timeout: Math.ceil((sandboxOpts.timeoutMs ?? 300_000) / 1000),
-            metadata: sandboxOpts.metadata ?? {},
-            env_vars: sandboxOpts.envs ?? {},
-            secure: sandboxOpts.secure ?? true,
-            allow_internet_access: sandboxOpts.allowInternetAccess ?? true,
+            timeout: Math.ceil(timeoutMs / 1000),
+            metadata: opts.metadata ?? {},
+            envs: opts.envs ?? {},
+            secure: opts.secure ?? true,
+            allow_internet_access: opts.allowInternetAccess ?? true,
         };
-        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);
+        putIfPresent(sandboxPayload, 'template', template);
+        putIfPresent(sandboxPayload, 'mcp', opts.mcp);
+        putIfPresent(sandboxPayload, 'lifecycle', lifecyclePayload(opts.lifecycle));
+        putIfPresent(sandboxPayload, 'volume_mounts', volumeMountsPayload(opts.volumeMounts));
+        Object.assign(sandboxPayload, networkUpdatePayload(opts.network));
+        putIfPresent(sandboxPayload, 'team', opts.team);
         const response = await control.post('/sandboxes', {
             json: sandboxPayload,
-            requestTimeoutMs: sessionOperationRequestTimeout(config, sandboxOpts),
-            signal: sandboxOpts.signal,
+            requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
+            signal: opts.signal,
         });
         const sandbox = record(response.sandbox ?? response);
         const sandboxId = sandbox.id ?? sandbox.sandbox_id;
         if (sandboxId === undefined)
             throw new SandboxError('create response did not include sandbox id');
-        const sandboxInstance = new this({
+        return sandboxConnectionDetails({
             sandboxId: String(sandboxId),
-            connectionConfig: config,
+            config,
             control,
             session: response.session,
             sandbox,
-            envs: sandboxOpts.envs,
+            envs: opts.envs,
         });
-        return sandboxInstance;
     }
     /** Connect to an existing sandbox and return it with a fresh data-plane session. */
     static async connect(sandboxId, opts = {}) {
+        const sandboxInfo = await this.connectSandbox(sandboxId, opts);
+        return new this({
+            sandboxId: sandboxInfo.sandboxId,
+            connectionConfig: sandboxInfo.connectionConfig,
+            control: sandboxInfo.control,
+            session: sandboxInfo.session,
+            sandbox: sandboxInfo.sandbox,
+        });
+    }
+    static async connectSandbox(sandboxId, opts = {}) {
         const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
         const info = await control.get(`/sandboxes/${sandboxId}`, {
@@ -180,9 +212,9 @@ export class Sandbox {
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
             signal: opts.signal,
         });
-        return new this({
+        return sandboxConnectionDetails({
             sandboxId,
-            connectionConfig: config,
+            config,
             control,
             session: response.session,
             sandbox: record(response.sandbox ?? info.sandbox ?? {}),
@@ -192,18 +224,19 @@ export class Sandbox {
     async connect(opts = {}) {
         const response = await this.control.post(`/sandboxes/${this.sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
-            requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
+            requestTimeoutMs: sessionOperationRequestTimeout(this.connectionConfig, opts),
             signal: opts.signal,
         });
         this.sandbox = record(response.sandbox ?? this.sandbox);
-        const dataPlane = dataPlaneFromSession(response.session, this.config);
+        const dataPlane = dataPlaneFromSession(response.session, this.connectionConfig);
+        const mutable = this;
         this.dataPlane = dataPlane;
-        this.files = new Filesystem(dataPlane);
-        this.commands = new Commands(dataPlane, this.config, this.envs);
-        this.process = new ProcessManager(this.commands);
-        this.pty = new Pty(dataPlane, this.config);
-        this.terminal = new TerminalManager(this.pty);
-        this.git = new Git(dataPlane);
+        mutable.files = new Filesystem(dataPlane);
+        mutable.commands = new Commands(dataPlane, this.connectionConfig, this.envs);
+        mutable.process = new ProcessManager(this.commands);
+        mutable.pty = new Pty(dataPlane, this.connectionConfig);
+        mutable.terminal = new TerminalManager(this.pty);
+        mutable.git = new Git(dataPlane);
         return this;
     }
     /** Resume a paused sandbox by id. */
@@ -233,11 +266,10 @@ export class Sandbox {
     }
     /** Destroy a sandbox by id. */
     static async kill(sandboxId, opts = {}) {
-        const requestOpts = typeof opts === 'string' ? {} : opts;
-        const control = new ControlClient(new ConnectionConfig(typeof opts === 'string' ? { apiKey: opts } : opts));
+        const control = new ControlClient(new ConnectionConfig(opts));
         await control.delete(`/sandboxes/${sandboxId}`, {
-            requestTimeoutMs: requestOpts.requestTimeoutMs,
-            signal: requestOpts.signal,
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return true;
     }
@@ -357,19 +389,19 @@ export class Sandbox {
     }
     /** Fetch latest sandbox metrics. */
     async getMetrics(opts = {}) {
-        return Sandbox.getMetrics(this.sandboxId, { ...this.configOptions(), ...opts });
+        return Sandbox.getMetrics(this.sandboxId, { ...this.resolveApiOpts(), ...opts });
     }
     /** Create a Watasu checkpoint using snapshot naming. */
     async createSnapshot(opts = {}) {
-        return Sandbox.createSnapshot(this.sandboxId, { ...this.configOptions(), ...opts });
+        return Sandbox.createSnapshot(this.sandboxId, { ...this.resolveApiOpts(), ...opts });
     }
     /** Delete a snapshot by id. */
     async deleteSnapshot(snapshotId, opts = {}) {
-        return Sandbox.deleteSnapshot(snapshotId, { ...this.configOptions(), ...opts });
+        return Sandbox.deleteSnapshot(snapshotId, { ...this.resolveApiOpts(), ...opts });
     }
     /** List checkpoints for this sandbox using snapshot naming. */
     listSnapshots(opts = {}) {
-        return Sandbox.listSnapshots({ ...this.configOptions(), ...opts, sandboxId: this.sandboxId });
+        return Sandbox.listSnapshots({ ...this.resolveApiOpts(), ...opts, sandboxId: this.sandboxId });
     }
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
     async restore(opts = {}) {
@@ -391,17 +423,16 @@ export class Sandbox {
     }
     /** Return a paginator for sandboxes visible to the configured API key. */
     static list(opts = {}) {
-        const listOpts = typeof opts === 'string' ? { apiKey: opts } : opts;
-        return new SandboxPaginator(listOpts);
+        return new SandboxPaginator(opts);
     }
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port) {
         const routeToken = this.sandbox.route_token ??
             this.sandbox.routeToken ??
-            routeTokenFromDataPlaneUrl(this.dataPlane.baseUrl, this.config.dataPlaneDomain);
+            routeTokenFromDataPlaneUrl(this.dataPlane.baseUrl, this.connectionConfig.dataPlaneDomain);
         if (typeof routeToken !== 'string')
             throw new SandboxError('port response did not include host or url');
-        return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
+        return `p${port}-${routeToken}.sandbox.${this.connectionConfig.dataPlaneDomain}`;
     }
     /** Return the conventional MCP URL for this sandbox. */
     getMcpUrl() {
@@ -442,12 +473,12 @@ export class Sandbox {
     }
     /** Atomically replace this sandbox's network egress policy. */
     async updateNetwork(network, opts = {}) {
-        const sandbox = await Sandbox.putNetwork(this.sandboxId, network, { ...this.configOptions(), ...opts });
+        const sandbox = await Sandbox.putNetwork(this.sandboxId, network, { ...this.resolveApiOpts(), ...opts });
         this.sandbox = sandbox ?? this.sandbox;
     }
     /** Pause this sandbox. Returns false when it was already paused. */
     async betaPause(opts = {}) {
-        return Sandbox.betaPause(this.sandboxId, { ...this.configOptions(), ...opts });
+        return Sandbox.betaPause(this.sandboxId, { ...this.resolveApiOpts(), ...opts });
     }
     /** Pause this sandbox. Returns false when it was already paused. */
     async pause(opts = {}) {
@@ -471,6 +502,10 @@ export class Sandbox {
         });
         return fileUrlInfo(record(payload.file_url ?? payload));
     }
+    /** Base URL for the sandbox data-plane runtime API. */
+    get runtimeBaseUrl() {
+        return this.dataPlane.baseUrl;
+    }
     /** POST JSON to the sandbox data-plane runtime API. */
     async runtimePostJson(path, json, opts = {}) {
         return this.dataPlane.postJson(path, {
@@ -493,18 +528,18 @@ export class Sandbox {
             signal: opts.signal,
         });
     }
-    configOptions() {
+    resolveApiOpts() {
         return {
-            apiKey: this.config.apiKey,
-            apiUrl: this.config.apiUrl,
-            sandboxUrl: this.config.sandboxUrl,
-            dataPlaneDomain: this.config.dataPlaneDomain,
-            requestTimeoutMs: this.config.requestTimeoutMs,
-            headers: this.config.headers,
-            apiHeaders: this.config.apiHeaders,
-            debug: this.config.debug,
-            signal: this.config.signal,
-            proxy: this.config.proxy,
+            apiKey: this.connectionConfig.apiKey,
+            apiUrl: this.connectionConfig.apiUrl,
+            sandboxUrl: this.connectionConfig.sandboxUrl,
+            dataPlaneDomain: this.connectionConfig.dataPlaneDomain,
+            requestTimeoutMs: this.connectionConfig.requestTimeoutMs,
+            headers: this.connectionConfig.headers,
+            apiHeaders: this.connectionConfig.apiHeaders,
+            debug: this.connectionConfig.debug,
+            signal: this.connectionConfig.signal,
+            proxy: this.connectionConfig.proxy,
         };
     }
 }
@@ -567,6 +602,21 @@ function fileUrlInfo(payload) {
         raw: payload,
     };
 }
+function sandboxConnectionDetails(opts) {
+    const session = record(opts.session);
+    return {
+        sandboxId: opts.sandboxId,
+        sandboxDomain: stringValue(session.sandbox_domain ?? session.sandboxDomain ?? opts.sandbox.sandbox_domain ?? opts.sandbox.domain),
+        envdVersion: stringValue(session.envd_version ?? session.envdVersion ?? opts.sandbox.envd_version ?? opts.sandbox.envdVersion) ?? '',
+        envdAccessToken: stringValue(session.envd_access_token ?? session.envdAccessToken ?? session.token),
+        trafficAccessToken: stringValue(session.traffic_access_token ?? session.trafficAccessToken ?? opts.sandbox.traffic_access_token ?? opts.sandbox.trafficAccessToken),
+        connectionConfig: opts.config,
+        control: opts.control,
+        session: opts.session,
+        sandbox: opts.sandbox,
+        envs: opts.envs,
+    };
+}
 function compactRecord(payload) {
     return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
 }
@@ -581,15 +631,17 @@ 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,
+        cpuCount: numberValue(payload.cpu_count ?? payload.cpuCount),
+        memoryMB: numberValue(payload.memory_mb ?? payload.memoryMB ?? payload.memoryMb),
+        envdVersion: stringValue(payload.envd_version ?? payload.envdVersion),
+        allowInternetAccess: booleanValue(payload.allow_internet_access ?? payload.allowInternetAccess),
+        network: sandboxNetworkInfo(payload.network),
+        sandboxDomain: stringValue(payload.sandbox_domain ?? payload.sandboxDomain),
         lifecycle: sandboxLifecycleInfo(payload.lifecycle),
         volumeMounts: volumeMountsInfo(payload.volume_mounts ?? payload.volumeMounts),
         metadata: recordOfStrings(payload.metadata),
-        startedAt: typeof payload.started_at === 'string'
-            ? payload.started_at
-            : typeof payload.created_at === 'string' ? payload.created_at : undefined,
-        endAt: typeof payload.end_at === 'string'
-            ? payload.end_at
-            : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
+        startedAt: dateValue(payload.started_at ?? payload.startedAt ?? payload.created_at ?? payload.createdAt ?? payload.ready_at ?? payload.readyAt),
+        endAt: dateValue(payload.end_at ?? payload.endAt ?? payload.deadline_at ?? payload.deadlineAt),
     };
 }
 function lifecyclePayload(lifecycle) {
@@ -631,6 +683,10 @@ function sandboxLifecycleInfo(value) {
         autoResume: autoResume ?? false,
     };
 }
+function sandboxNetworkInfo(value) {
+    const item = record(value);
+    return Object.keys(item).length > 0 ? item : undefined;
+}
 function metricsList(value) {
     if (Array.isArray(value))
         return value.map((item) => metricsInfo(record(item)));
@@ -638,11 +694,18 @@ function metricsList(value) {
 }
 function metricsInfo(value) {
     return {
+        timestamp: dateValue(value.timestamp ?? value.time ?? value.created_at ?? value.createdAt),
         sandboxId: stringValue(value.sandbox_id ?? value.sandboxId),
         state: stringValue(value.state),
         node: stringValue(value.node),
         backend: stringValue(value.backend),
         cpuCount: numberValue(value.cpu_count ?? value.cpuCount),
+        cpuUsedPct: numberValue(value.cpu_used_pct ?? value.cpuUsedPct ?? value.cpu_pct ?? value.cpuPct),
+        memUsed: numberValue(value.mem_used ?? value.memUsed ?? value.memory_used ?? value.memoryUsed),
+        memTotal: numberValue(value.mem_total ?? value.memTotal ?? value.memory_total ?? value.memoryTotal),
+        memCache: numberValue(value.mem_cache ?? value.memCache ?? value.memory_cache ?? value.memoryCache),
+        diskUsed: numberValue(value.disk_used ?? value.diskUsed),
+        diskTotal: numberValue(value.disk_total ?? value.diskTotal),
         memoryMb: numberValue(value.memory_mb ?? value.memoryMb),
         raw: value,
     };
@@ -659,10 +722,12 @@ function snapshotInfo(value) {
     const id = value.snapshot_id ?? value.snapshotId ?? value.checkpoint_id ?? value.checkpointId ?? value.id;
     if (id === undefined)
         throw new SandboxError('snapshot response did not include id');
+    const name = stringValue(value.name);
     return {
         snapshotId: String(id),
+        names: arrayOfStrings(value.names ?? value.name ?? value.snapshot_names ?? value.snapshotNames),
         sandboxId: stringValue(value.sandbox_id ?? value.sandboxId),
-        name: stringValue(value.name),
+        name,
         status: stringValue(value.status),
         sizeBytes: numberValue(value.size_bytes ?? value.sizeBytes),
         createdAt: stringValue(value.created_at ?? value.createdAt),
@@ -677,9 +742,26 @@ function stringValue(value) {
         return String(value);
     return undefined;
 }
+function arrayOfStrings(value) {
+    if (Array.isArray(value))
+        return value.map(String);
+    if (value === undefined || value === null || value === '')
+        return [];
+    return [String(value)];
+}
 function numberValue(value) {
     return typeof value === 'number' ? value : undefined;
 }
+function dateValue(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'string' || typeof value === 'number') {
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime()))
+            return date;
+    }
+    return undefined;
+}
 function booleanValue(value) {
     if (typeof value === 'boolean')
         return value;