@openkaiden/opnshll-sdk 0.0.116 → 0.1.2

package/dist/client.js

@@ -1,13 +1,39 @@
 // SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 import * as net from 'node:net';
+import { durationFromMs } from '@bufbuild/protobuf/wkt';
 import { createClient } from '@connectrpc/connect';
 import { errorCode, fromConnect, SdkError } from './errors.js';
 import { OpenShell, SandboxPhase, ServiceStatus, } from './gen/openshell_pb.js';
 import { PolicySource, SettingScope } from './gen/sandbox_pb.js';
 import { validateSshResponse } from './ssh-validate.js';
 import { buildTransport } from './transport.js';
+function durationFromSeconds(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new RangeError('timeoutSecs must be a finite, non-negative number');
+    }
+    return seconds === 0 ? undefined : durationFromMs(seconds * 1000);
+}
+function timestampMillis(timestamp) {
+    if (!timestamp)
+        return undefined;
+    const millis = timestamp.seconds * 1000n + BigInt(Math.trunc(timestamp.nanos / 1_000_000));
+    return millis === 0n ? undefined : millis.toString();
+}
 export { errorCode };
+function deletionResult(response) {
+    const names = {
+        0: 'unspecified',
+        1: 'completed',
+        2: 'accepted',
+        3: 'already_absent',
+    };
+    return {
+        outcome: names[response.outcome] ?? 'unknown',
+        rawOutcome: response.outcome,
+        ...(response.sandboxId ? { sandboxId: response.sandboxId } : {}),
+    };
+}
 // ---- enum → lowercase string -----------------------------------------------
 // Exported for the enum-name drift test only; not re-exported from index.ts, so
 // they are not part of the public package API.
@@ -21,6 +47,7 @@ export const PHASE_NAMES = {
     [SandboxPhase.STOPPING]: 'stopping',
     [SandboxPhase.STOPPED]: 'stopped',
     [SandboxPhase.STARTING]: 'starting',
+    [SandboxPhase.COMPLETED]: 'completed',
 };
 export const STATUS_NAMES = {
     [ServiceStatus.UNSPECIFIED]: 'unspecified',
@@ -50,7 +77,7 @@ function scopeName(s) {
 function policySourceName(s) {
     return POLICY_SOURCE_NAMES[s] ?? 'unspecified';
 }
-function sandboxRef(sandbox) {
+function sandboxRef(sandbox, serviceUrls = {}) {
     if (!sandbox)
         throw new SdkError('invalid_config', 'sandbox missing from gateway response');
     const meta = sandbox.metadata;
@@ -60,13 +87,26 @@ function sandboxRef(sandbox) {
     return {
         id: meta.id,
         name: meta.name,
+        workspace: meta.workspace,
         phase: phaseName(sandbox.status?.phase ?? SandboxPhase.UNSPECIFIED),
         labels: meta?.labels ?? {},
         resourceVersion: (meta?.resourceVersion ?? 0n).toString(),
         mainProcessInstanceId: sandbox.status?.mainProcessInstanceId || undefined,
         exitCode: sandbox.status?.exitCode,
+        createdFromWorkloadTemplate: sandbox.createdFromWorkloadTemplate
+            ? {
+                name: sandbox.createdFromWorkloadTemplate.name,
+                resourceVersion: sandbox.createdFromWorkloadTemplate.resourceVersion,
+            }
+            : undefined,
+        serviceUrls,
     };
 }
+function sandboxTemplate(template) {
+    if (!template)
+        throw new SdkError('invalid_config', 'sandbox template missing from gateway response');
+    return template;
+}
 function providerRef(provider) {
     const meta = provider.metadata;
     return {
@@ -128,6 +168,30 @@ function versionPin(value) {
     return pin;
 }
 const FORWARD_CHUNK = 64 * 1024;
+function workspaceName(options) {
+    const workspace = options?.workspace ?? 'default';
+    if (workspace.trim() === '')
+        throw new SdkError('invalid_config', 'workspace must be non-empty');
+    return workspace;
+}
+function workspaceScope(options) {
+    return { selection: { case: 'workspace', value: workspaceName(options) } };
+}
+function listWorkspaceScope(options) {
+    return options?.allWorkspaces ? { selection: { case: 'allWorkspaces', value: {} } } : workspaceScope(options);
+}
+function sandboxTarget(name, options) {
+    return { sandbox: name, workspaceScope: workspaceScope(options) };
+}
+function namedTarget(name, options) {
+    return { name, workspaceScope: workspaceScope(options) };
+}
+function requestCallOptions(options) {
+    if (!options)
+        return undefined;
+    const { workspace: _workspace, ...callOptions } = options;
+    return callOptions;
+}
 // Build CallOptions that bound one poll RPC by the remaining wall-clock budget
 // and honor caller cancellation, so a stalled RPC cannot outlive the deadline.
 function deadlineOptions(remainingMs, signal) {
@@ -136,12 +200,12 @@ function deadlineOptions(remainingMs, signal) {
         signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
     };
 }
-// Translate a poll failure at the wait boundary: caller cancellation and
-// deadline expiry become explicit SdkErrors; anything else propagates.
-function mapWaitError(err, name, deadline, signal) {
+// Translate a poll failure at the wait boundary: caller cancellation and the
+// poll's deadline signal both become explicit SdkErrors; anything else propagates.
+function mapWaitError(err, name, deadline, signal, pollSignal) {
     if (signal?.aborted)
         return new SdkError('connect', `wait for sandbox '${name}' aborted`);
-    if (Date.now() >= deadline)
+    if (pollSignal?.aborted || Date.now() >= deadline)
         return new SdkError('connect', `timed out waiting for sandbox '${name}'`);
     return err instanceof SdkError ? err : fromConnect(err);
 }
@@ -245,6 +309,198 @@ export class Pushable {
         }
     }
 }
+// Single producer/consumer queue. Closing wakes both directions, including a
+// producer blocked by backpressure. Successful completion drains queued values.
+class ExecOutputQueue {
+    values = [];
+    ended = false;
+    error;
+    reader;
+    writer;
+    async push(value) {
+        // The terminal exit carries no output bytes and must never block cleanup
+        // after done has already settled and its cancellation listener is removed.
+        while (!('type' in value) && this.values.length >= 16 && !this.ended) {
+            await new Promise((resolve) => {
+                this.writer = resolve;
+            });
+        }
+        if (this.ended)
+            throw this.error ?? new SdkError('canceled', 'exec output closed');
+        this.values.push(value);
+        this.reader?.();
+        this.reader = undefined;
+    }
+    end(error, discard = false) {
+        if (discard)
+            this.values.length = 0;
+        if (!this.ended) {
+            this.ended = true;
+            this.error = error;
+        }
+        this.reader?.();
+        this.writer?.();
+        this.reader = undefined;
+        this.writer = undefined;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const value = this.values.shift();
+            if (value !== undefined) {
+                this.writer?.();
+                this.writer = undefined;
+                yield value;
+            }
+            else if (this.ended) {
+                if (this.error !== undefined)
+                    throw this.error;
+                return;
+            }
+            else {
+                await new Promise((resolve) => {
+                    this.reader = resolve;
+                });
+            }
+        }
+    }
+}
+const maxConsumedPageTokens = 10_000;
+const maxConsumedPageTokenBytes = 1 << 20;
+/** Lazy, single-pass iterator that fetches one RPC page per advance. */
+export class Pager {
+    fetch;
+    maxConsumedTokens;
+    maxConsumedTokenBytes;
+    nextToken;
+    consumedTokens = new Set();
+    consumedTokenBytes = 0;
+    constructor(fetch, pageToken = '', maxConsumedTokens = maxConsumedPageTokens, maxConsumedTokenBytes = maxConsumedPageTokenBytes) {
+        this.fetch = fetch;
+        this.maxConsumedTokens = maxConsumedTokens;
+        this.maxConsumedTokenBytes = maxConsumedTokenBytes;
+        this.nextToken = pageToken;
+    }
+    validateCurrentTokenBudget(pageToken) {
+        if (pageToken === '')
+            return 0;
+        const tokenBytes = new TextEncoder().encode(pageToken).byteLength;
+        if (this.consumedTokens.size >= this.maxConsumedTokens ||
+            tokenBytes > this.maxConsumedTokenBytes - this.consumedTokenBytes) {
+            throw new Error('pager continuation token history limit exceeded');
+        }
+        return tokenBytes;
+    }
+    /** Fetch the next page, or return undefined after the final page. */
+    async nextPage() {
+        if (this.nextToken === undefined)
+            return undefined;
+        const pageToken = this.nextToken;
+        const tokenBytes = this.validateCurrentTokenBudget(pageToken);
+        const page = await this.fetch(pageToken);
+        if (pageToken !== '') {
+            this.consumedTokens.add(pageToken);
+            this.consumedTokenBytes += tokenBytes;
+        }
+        if (page.nextPageToken !== '' && this.consumedTokens.has(page.nextPageToken)) {
+            throw new Error('pager received a repeated continuation token');
+        }
+        this.nextToken = page.nextPageToken === '' ? undefined : page.nextPageToken;
+        return page;
+    }
+    /** Consume the pager and collect every remaining item. */
+    async all() {
+        const items = [];
+        for await (const page of this)
+            items.push(...page.items);
+        return items;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const page = await this.nextPage();
+            if (page === undefined)
+                return;
+            yield page;
+        }
+    }
+}
+// ---- sandbox template client ----------------------------------------------
+// Reusable sandbox workload template lifecycle. Templates intentionally return
+// generated proto messages because the resource owns portable workload fields
+// plus driver-specific config that should not be lossy in the curated layer.
+export class SandboxTemplateClient {
+    grpc;
+    raw;
+    transport;
+    constructor(transport, grpc = createClient(OpenShell, transport)) {
+        this.transport = transport;
+        this.grpc = grpc;
+        this.raw = this.grpc;
+    }
+    static async connect(options) {
+        return new SandboxTemplateClient(buildTransport(options));
+    }
+    async create(template, options) {
+        try {
+            const resp = await this.grpc.createSandboxTemplate({
+                workspaceScope: workspaceScope(options),
+                template,
+            });
+            return sandboxTemplate(resp.template);
+        }
+        catch (e) {
+            throw e instanceof SdkError ? e : fromConnect(e);
+        }
+    }
+    async get(name, options) {
+        if (name.trim() === '')
+            throw new SdkError('invalid_config', 'template name is required');
+        try {
+            const resp = await this.grpc.getSandboxTemplate({
+                workspaceScope: workspaceScope(options),
+                name,
+            });
+            return sandboxTemplate(resp.template);
+        }
+        catch (e) {
+            throw e instanceof SdkError ? e : fromConnect(e);
+        }
+    }
+    list(options) {
+        return new Pager(async (pageToken) => {
+            try {
+                const resp = await this.grpc.listSandboxTemplates({
+                    pageSize: options?.pageSize ?? 0,
+                    pageToken,
+                    labelSelector: options?.labelSelector ?? '',
+                    workspaceScope: listWorkspaceScope(options),
+                });
+                return { items: resp.templates, nextPageToken: resp.nextPageToken };
+            }
+            catch (e) {
+                throw fromConnect(e);
+            }
+        }, options?.pageToken ?? '');
+    }
+    /** List and collect every sandbox template in this scope. */
+    async listAll(options) {
+        return this.list(options).all();
+    }
+    async delete(name, options) {
+        if (name.trim() === '')
+            throw new SdkError('invalid_config', 'template name is required');
+        try {
+            const resp = await this.grpc.deleteSandboxTemplate({
+                workspaceScope: workspaceScope(options),
+                allowMissing: options?.allowMissing ?? false,
+                name,
+            });
+            return deletionResult(resp);
+        }
+        catch (e) {
+            throw fromConnect(e);
+        }
+    }
+}
 // ---- sandbox client --------------------------------------------------------
 // Sandbox lifecycle + exec. Usable standalone via `SandboxClient.connect()`,
 // or reached as `client.sandbox` on an OpenShellClient, which shares one
@@ -292,42 +548,86 @@ export class SandboxClient {
             if (spec.rawSpec)
                 Object.assign(specInit, spec.rawSpec);
             const resp = await this.grpc.createSandbox({
+                workspaceScope: workspaceScope(spec),
                 name: spec.name ?? '',
                 labels: spec.labels ?? {},
                 spec: specInit,
+                serviceExposures: spec.serviceExposures?.map((exposure) => ({
+                    service: exposure.service ?? '',
+                    targetPort: exposure.targetPort,
+                })) ?? [],
             });
-            return sandboxRef(resp.sandbox);
+            return sandboxRef(resp.sandbox, resp.serviceUrls);
         }
         catch (e) {
             throw fromConnect(e);
         }
     }
-    async get(name, callOptions) {
+    async createFromTemplate(spec) {
+        if (spec.workloadTemplate.trim() === '')
+            throw new SdkError('invalid_config', 'workloadTemplate is required');
         try {
-            const resp = await this.grpc.getSandbox({ name }, callOptions);
-            return sandboxRef(resp.sandbox);
+            const resp = await this.grpc.createSandbox({
+                workspaceScope: workspaceScope(spec),
+                name: spec.name ?? '',
+                labels: spec.labels ?? {},
+                spec: {
+                    providers: spec.providers ?? [],
+                    command: spec.command ?? [],
+                    tty: spec.tty ?? false,
+                    policy: spec.policy,
+                },
+                workloadTemplate: spec.workloadTemplate,
+                serviceExposures: spec.serviceExposures?.map((exposure) => ({
+                    service: exposure.service ?? '',
+                    targetPort: exposure.targetPort,
+                })) ?? [],
+            });
+            return sandboxRef(resp.sandbox, resp.serviceUrls);
         }
         catch (e) {
             throw fromConnect(e);
         }
     }
-    async list(options) {
+    async get(name, options) {
         try {
-            const resp = await this.grpc.listSandboxes({
-                limit: options?.limit ?? 0,
-                offset: options?.offset ?? 0,
-                labelSelector: options?.labelSelector ?? '',
-            });
-            return resp.sandboxes.map((s) => sandboxRef(s));
+            const resp = await this.grpc.getSandbox({ ...namedTarget(name, options) }, requestCallOptions(options));
+            return sandboxRef(resp.sandbox);
         }
         catch (e) {
             throw fromConnect(e);
         }
     }
-    async delete(name) {
+    list(options) {
+        return new Pager(async (pageToken) => {
+            try {
+                const resp = await this.grpc.listSandboxes({
+                    pageSize: options?.pageSize ?? 0,
+                    pageToken,
+                    labelSelector: options?.labelSelector ?? '',
+                    workspaceScope: listWorkspaceScope(options),
+                });
+                return {
+                    items: resp.sandboxes.map((sandbox) => sandboxRef(sandbox)),
+                    nextPageToken: resp.nextPageToken,
+                };
+            }
+            catch (e) {
+                throw fromConnect(e);
+            }
+        }, options?.pageToken ?? '');
+    }
+    /** List and collect every sandbox in this scope. */
+    async listAll(options) {
+        return this.list(options).all();
+    }
+    async delete(name, options) {
         try {
-            const resp = await this.grpc.deleteSandbox({ name });
-            return resp.deleted;
+            const resp = await this.grpc.deleteSandbox({
+                ...namedTarget(name, options),
+                allowMissing: options?.allowMissing ?? false,
+            });
+            return deletionResult(resp);
         }
         catch (e) {
             throw fromConnect(e);
@@ -346,14 +646,20 @@ export class SandboxClient {
             if (Date.now() >= deadline)
                 throw new SdkError('connect', `timed out waiting for sandbox '${name}'`);
             let ref;
+            const pollOptions = deadlineOptions(deadline - Date.now(), signal);
             try {
-                ref = await this.get(name, deadlineOptions(deadline - Date.now(), signal));
+                ref = await this.get(name, {
+                    ...pollOptions,
+                    workspace: options?.workspace,
+                });
             }
             catch (e) {
-                throw mapWaitError(e, name, deadline, signal);
+                throw mapWaitError(e, name, deadline, signal, pollOptions.signal);
             }
-            if (ref.phase === 'ready')
+            if (ref.phase === 'ready' || ref.phase === 'completed')
                 return ref;
+            if (ref.phase === 'stopped')
+                throw new SdkError('connect', `sandbox '${name}' stopped before becoming ready`);
             if (ref.phase === 'error')
                 throw new SdkError('connect', `sandbox '${name}' entered error phase`);
             if (Date.now() >= deadline)
@@ -362,8 +668,8 @@ export class SandboxClient {
             delay = Math.min(delay * 2, 2000);
         }
     }
-    // Poll until the sandbox is gone. Timeout and cancellation bound the returned
-    // promise the same way as waitReady.
+    // Poll until the sandbox is gone, or its name resolves to a different ID when
+    // expectedSandboxId is supplied. Timeout and cancellation work as in waitReady.
     async waitDeleted(name, timeoutSecs, options) {
         const deadline = Date.now() + timeoutSecs * 1000;
         const signal = options?.signal;
@@ -373,13 +679,16 @@ export class SandboxClient {
                 throw new SdkError('connect', `wait for sandbox '${name}' aborted`);
             if (Date.now() >= deadline)
                 throw new SdkError('connect', `timed out waiting for sandbox '${name}' to delete`);
+            const pollOptions = deadlineOptions(deadline - Date.now(), signal);
             try {
-                await this.get(name, deadlineOptions(deadline - Date.now(), signal));
+                const ref = await this.get(name, { ...pollOptions, workspace: options?.workspace });
+                if (options?.expectedSandboxId !== undefined && ref.id !== options.expectedSandboxId)
+                    return;
             }
             catch (e) {
                 if (e instanceof SdkError && e.code === 'not_found')
                     return;
-                throw mapWaitError(e, name, deadline, signal);
+                throw mapWaitError(e, name, deadline, signal, pollOptions.signal);
             }
             if (Date.now() >= deadline)
                 throw new SdkError('connect', `timed out waiting for sandbox '${name}' to delete`);
@@ -394,16 +703,20 @@ export class SandboxClient {
     // path to reconstruct the buffered result.
     async *execStream(name, command, options) {
         try {
-            // Resolve the sandbox id first, exactly like the gateway client.
-            const sandbox = await this.get(name, options?.signal ? { signal: options.signal } : undefined);
+            // Preserve the existing preflight so lookup failures surface before the stream starts.
+            await this.get(name, {
+                workspace: options?.workspace,
+                ...(options?.signal ? { signal: options.signal } : {}),
+            });
             const stream = this.grpc.execSandbox({
-                sandboxId: sandbox.id,
+                ...sandboxTarget(name, options),
                 command,
                 workdir: options?.workdir ?? '',
                 environment: options?.environment ?? {},
-                timeoutSeconds: options?.timeoutSecs ?? 0,
+                executionTimeout: durationFromSeconds(options?.timeoutSecs ?? 0),
                 stdin: options?.stdin ? new Uint8Array(options.stdin) : new Uint8Array(),
                 tty: false,
+                noLoginShell: options?.noLoginShell ?? false,
             }, { signal: options?.signal });
             let sawExit = false;
             for await (const event of stream) {
@@ -461,9 +774,8 @@ export class SandboxClient {
     // `stdin`/`resize`. No terminal glue: raw mode, signal forwarding, and
     // SIGWINCH stay with the caller.
     async execInteractive(name, command, options) {
-        let sandboxId;
         try {
-            sandboxId = (await this.get(name, options?.signal ? { signal: options.signal } : undefined)).id;
+            await this.get(name, { workspace: options?.workspace, ...(options?.signal ? { signal: options.signal } : {}) });
         }
         catch (e) {
             throw e instanceof SdkError ? e : fromConnect(e);
@@ -473,19 +785,33 @@ export class SandboxClient {
             payload: {
                 case: 'start',
                 value: {
-                    sandboxId,
+                    ...sandboxTarget(name, options),
                     command,
                     workdir: options?.workdir ?? '',
                     environment: options?.environment ?? {},
-                    timeoutSeconds: options?.timeoutSecs ?? 0,
+                    executionTimeout: durationFromSeconds(options?.timeoutSecs ?? 0),
                     stdin: new Uint8Array(),
                     tty: options?.tty ?? true,
                     cols: options?.cols ?? 0,
                     rows: options?.rows ?? 0,
+                    noLoginShell: options?.noLoginShell ?? false,
                 },
             },
         });
-        const stream = this.grpc.execSandboxInteractive(input, { signal: options?.signal });
+        const controller = new AbortController();
+        const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        const grpc = this.grpc;
+        const queue = new ExecOutputQueue();
+        let inputClosed = false;
+        let exitCode;
+        const closeInput = () => {
+            inputClosed = true;
+            input.end();
+        };
+        const assertInputOpen = () => {
+            if (inputClosed || signal.aborted)
+                throw new SdkError('io', 'exec input is closed');
+        };
         let resolveDone;
         let rejectDone;
         const done = new Promise((resolve, reject) => {
@@ -496,74 +822,118 @@ export class SandboxClient {
         // keeps an unobserved rejection from surfacing as an unhandledRejection;
         // real awaiters still receive it through their own handler.
         void done.catch(() => { });
-        // Settle exactly once. The exit code wins; error/abandonment only apply
-        // when no exit was observed.
+        // The process exit and the terminal transport status are separate outcomes.
         let settled = false;
         const settleExit = (code) => {
             if (settled)
                 return;
             settled = true;
+            signal.removeEventListener('abort', onAbort);
             resolveDone(code);
         };
         const settleError = (err) => {
             if (settled)
                 return;
             settled = true;
+            signal.removeEventListener('abort', onAbort);
             rejectDone(err);
         };
-        async function* output() {
-            let sawExit = false;
+        const onAbort = () => {
+            closeInput();
+            const error = new SdkError('canceled', 'exec cancelled');
+            queue.end(error, true);
+            settleError(error);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        async function receive() {
             try {
+                if (signal.aborted)
+                    throw new SdkError('canceled', 'exec cancelled');
+                // Start and observe the transport immediately, independently of output
+                // consumption. Backpressure bounds the queue to 16 chunks of 64 KiB.
+                const stream = grpc.execSandboxInteractive(input, { signal });
                 for await (const event of stream) {
+                    if (signal.aborted)
+                        throw new SdkError('canceled', 'exec cancelled');
+                    if (exitCode !== undefined) {
+                        throw new SdkError('rpc', 'ExecSandboxInteractive received an event after exit');
+                    }
                     switch (event.payload.case) {
                         case 'stdout':
-                            yield {
-                                stream: 'stdout',
-                                data: Buffer.from(event.payload.value.data),
-                            };
-                            break;
                         case 'stderr':
-                            yield {
-                                stream: 'stderr',
-                                data: Buffer.from(event.payload.value.data),
-                            };
+                            for (let offset = 0; offset < event.payload.value.data.length; offset += 64 * 1024) {
+                                await queue.push({
+                                    stream: event.payload.case,
+                                    data: Buffer.from(event.payload.value.data.subarray(offset, offset + 64 * 1024)),
+                                });
+                            }
                             break;
                         case 'exit':
-                            sawExit = true;
-                            // Settle `done` before yielding: a consumer that breaks on the
-                            // exit event abandons the generator at the yield, so anything
-                            // after it would never run.
-                            settleExit(event.payload.value.exitCode);
-                            yield { type: 'exit', exitCode: event.payload.value.exitCode };
+                            exitCode = event.payload.value.exitCode;
+                            closeInput();
                             break;
+                        default:
+                            throw new SdkError('rpc', 'ExecSandboxInteractive received an empty or unknown event');
                     }
                 }
-                if (!sawExit) {
+                if (exitCode === undefined) {
                     throw new SdkError('rpc', 'ExecSandboxInteractive stream ended without an exit event');
                 }
+                if (signal.aborted)
+                    throw new SdkError('canceled', 'exec cancelled before completion');
+                // Delay the public exit event until trailers have been consumed. A
+                // caller can still break on exit without losing the terminal status.
+                settleExit(exitCode);
+                await queue.push({ type: 'exit', exitCode });
+                queue.end();
             }
             catch (e) {
                 const err = e instanceof SdkError ? e : fromConnect(e);
                 settleError(err);
-                throw err;
+                queue.end(err);
+            }
+            finally {
+                closeInput();
+                controller.abort();
+            }
+        }
+        // receive catches transport failures even when nobody consumes output/done.
+        const receiving = receive();
+        async function* output() {
+            try {
+                yield* queue;
             }
             finally {
-                input.end();
-                // Consumer abandoned the stream before an exit event (early break or
-                // return): settle `done` so it can never hang.
-                settleError(new SdkError('rpc', 'exec output abandoned before exit'));
+                const error = new SdkError('rpc', 'exec output abandoned before completion');
+                settleError(error);
+                queue.end(error, true);
+                closeInput();
+                controller.abort();
+                await receiving;
             }
         }
         return {
             output: output(),
             write(data) {
+                assertInputOpen();
                 input.push({ payload: { case: 'stdin', value: new Uint8Array(data) } });
             },
             resize(cols, rows) {
+                assertInputOpen();
                 input.push({ payload: { case: 'resize', value: { cols, rows } } });
             },
-            close() {
-                input.end();
+            closeInput,
+            close: closeInput,
+            cancel() {
+                closeInput();
+                queue.end(new SdkError('canceled', 'exec cancelled'), true);
+                controller.abort();
+                settleError(new SdkError('canceled', 'exec cancelled'));
+            },
+            get exitCode() {
+                return exitCode;
             },
             done,
         };
@@ -580,7 +950,7 @@ export class SandboxClient {
         const localPort = opts.localPort ?? 0;
         let sandboxId;
         try {
-            const ref = await this.get(name, opts.signal ? { signal: opts.signal } : undefined);
+            const ref = await this.get(name, { workspace: opts.workspace, ...(opts.signal ? { signal: opts.signal } : {}) });
             if (ref.phase !== 'ready') {
                 throw new SdkError('connect', `sandbox '${name}' is not ready (phase: ${ref.phase})`);
             }
@@ -603,7 +973,7 @@ export class SandboxClient {
             socket.on('error', () => { });
             const controller = new AbortController();
             controllers.add(controller);
-            const task = this.forwardConnection(socket, sandboxId, name, targetHost, targetPort, controller.signal)
+            const task = this.forwardConnection(socket, sandboxId, name, opts.workspace, targetHost, targetPort, controller.signal)
                 .catch((error) => {
                 if (!closing) {
                     try {
@@ -674,12 +1044,12 @@ export class SandboxClient {
             closed,
         };
     }
-    async forwardConnection(socket, sandboxId, name, targetHost, targetPort, signal) {
+    async forwardConnection(socket, sandboxId, name, workspace, targetHost, targetPort, signal) {
         let token;
         const input = new Pushable();
         input.onDrain = () => socket.resume();
         try {
-            const session = await this.grpc.createSshSession({ sandboxId }, { signal });
+            const session = await this.grpc.createSshSession({ ...sandboxTarget(name, { workspace }) }, { signal });
             // Defense-in-depth: the token feeds forwardTcp authorization, so hold it
             // to the same trust-boundary contract as createSshSession. A violation
             // tears down this one socket via the catch below.
@@ -689,7 +1059,7 @@ export class SandboxClient {
                 payload: {
                     case: 'init',
                     value: {
-                        sandboxId,
+                        ...sandboxTarget(name, { workspace }),
                         serviceId: `service-forward:${name}:${targetHost}:${targetPort}`,
                         target: {
                             case: 'tcp',
@@ -743,7 +1113,7 @@ export class SandboxClient {
             input.end();
             if (token !== undefined) {
                 try {
-                    await this.grpc.revokeSshSession({ token }, { signal });
+                    await this.grpc.revokeSshSession({ token, allowMissing: true }, { signal });
                 }
                 catch {
                     // Best-effort revoke; the token expires on its own regardless.
@@ -753,10 +1123,10 @@ export class SandboxClient {
     }
     // Mint a short-lived SSH session token for the sandbox — the input side of
     // ssh-config / ProxyCommand and forwardTcp authorization.
-    async createSshSession(name) {
+    async createSshSession(name, options) {
         try {
-            const sandbox = await this.get(name);
-            const resp = await this.grpc.createSshSession({ sandboxId: sandbox.id });
+            const sandbox = await this.get(name, options);
+            const resp = await this.grpc.createSshSession({ ...sandboxTarget(name, options) });
             // Reject any response outside the proto trust-boundary contract before
             // handing these values to the caller (they feed OpenSSH ProxyCommand).
             validateSshResponse(resp, sandbox.id);
@@ -767,17 +1137,17 @@ export class SandboxClient {
                 gatewayPort: resp.gatewayPort,
                 gatewayScheme: resp.gatewayScheme,
                 ...(resp.hostKeyFingerprint ? { hostKeyFingerprint: resp.hostKeyFingerprint } : {}),
-                ...(resp.expiresAtMs !== 0n ? { expiresAtMs: resp.expiresAtMs.toString() } : {}),
+                ...(timestampMillis(resp.expirationTime) ? { expiresAtMs: timestampMillis(resp.expirationTime) } : {}),
             };
         }
         catch (e) {
             throw e instanceof SdkError ? e : fromConnect(e);
         }
     }
-    async revokeSshSession(token) {
+    async revokeSshSession(token, options) {
         try {
-            const resp = await this.grpc.revokeSshSession({ token });
-            return resp.revoked;
+            const resp = await this.grpc.revokeSshSession({ token, allowMissing: options?.allowMissing ?? false });
+            return deletionResult(resp);
         }
         catch (e) {
             throw fromConnect(e);
@@ -786,8 +1156,8 @@ export class SandboxClient {
     async attachProvider(name, provider, options) {
         try {
             const resp = await this.grpc.attachSandboxProvider({
-                sandboxName: name,
-                providerName: provider,
+                ...sandboxTarget(name, options),
+                provider,
                 expectedResourceVersion: versionPin(options?.expectedResourceVersion),
             });
             return { sandbox: sandboxRef(resp.sandbox), changed: resp.attached };
@@ -799,8 +1169,8 @@ export class SandboxClient {
     async detachProvider(name, provider, options) {
         try {
             const resp = await this.grpc.detachSandboxProvider({
-                sandboxName: name,
-                providerName: provider,
+                ...sandboxTarget(name, options),
+                provider,
                 expectedResourceVersion: versionPin(options?.expectedResourceVersion),
             });
             return { sandbox: sandboxRef(resp.sandbox), changed: resp.detached };
@@ -809,19 +1179,32 @@ export class SandboxClient {
             throw fromConnect(e);
         }
     }
-    async listProviders(name) {
-        try {
-            const resp = await this.grpc.listSandboxProviders({ sandboxName: name });
-            return resp.providers.map((p) => providerRef(p));
-        }
-        catch (e) {
-            throw fromConnect(e);
-        }
+    listProviders(name, options) {
+        return new Pager(async (pageToken) => {
+            try {
+                const resp = await this.grpc.listSandboxProviders({
+                    ...sandboxTarget(name, options),
+                    pageSize: options?.pageSize ?? 0,
+                    pageToken,
+                });
+                return {
+                    items: resp.providers.map((provider) => providerRef(provider)),
+                    nextPageToken: resp.nextPageToken,
+                };
+            }
+            catch (e) {
+                throw fromConnect(e);
+            }
+        }, options?.pageToken ?? '');
+    }
+    /** List and collect every provider attached to this sandbox. */
+    async listAllProviders(name, options) {
+        return this.listProviders(name, options).all();
     }
-    async getConfig(name, callOptions) {
+    async getConfig(name, options) {
         try {
-            const sandbox = await this.get(name, callOptions);
-            const resp = await this.grpc.getSandboxConfig({ sandboxId: sandbox.id }, callOptions);
+            await this.get(name, options);
+            const resp = await this.grpc.getSandboxConfig({ ...namedTarget(name, options) }, requestCallOptions(options));
             return sandboxConfig(resp);
         }
         catch (e) {
@@ -835,14 +1218,14 @@ export class SandboxClient {
     async setPolicy(name, policy, options) {
         try {
             const resp = await this.grpc.updateConfig({
-                name,
+                ...sandboxTarget(name, options),
                 policy,
                 global: false,
                 expectedResourceVersion: versionPin(options?.expectedResourceVersion),
             });
             const result = updateConfigResult(resp);
             if (options?.wait)
-                await this.waitForPolicyHash(name, result.policyHash, options.waitTimeoutSecs);
+                await this.waitForPolicyHash(name, result.policyHash, options.waitTimeoutSecs, options.workspace);
             return result;
         }
         catch (e) {
@@ -851,10 +1234,10 @@ export class SandboxClient {
     }
     // Upsert a single sandbox-scoped setting. Sandbox-scoped deletes are rejected
     // by the gateway, so there is no sandbox-scoped delete on this surface.
-    async setSetting(name, key, value) {
+    async setSetting(name, key, value, options) {
         try {
             const resp = await this.grpc.updateConfig({
-                name,
+                ...sandboxTarget(name, options),
                 settingKey: key,
                 settingValue: value,
                 global: false,
@@ -868,16 +1251,17 @@ export class SandboxClient {
     // Poll getConfig until the applied policy hash is observed. Each poll RPC is
     // bounded by the remaining deadline (deadlineOptions), so a stalled getConfig
     // cannot make the returned promise outlive timeoutSecs.
-    async waitForPolicyHash(name, policyHash, timeoutSecs = 60) {
+    async waitForPolicyHash(name, policyHash, timeoutSecs = 60, workspace) {
         const deadline = Date.now() + timeoutSecs * 1000;
         let delay = 100;
         for (;;) {
             let config;
+            const pollOptions = deadlineOptions(deadline - Date.now());
             try {
-                config = await this.getConfig(name, deadlineOptions(deadline - Date.now()));
+                config = await this.getConfig(name, { ...pollOptions, workspace });
             }
             catch (e) {
-                if (Date.now() >= deadline) {
+                if (pollOptions.signal?.aborted || Date.now() >= deadline) {
                     throw new SdkError('connect', `timed out waiting for policy '${policyHash}' on sandbox '${name}'`);
                 }
                 throw e instanceof SdkError ? e : fromConnect(e);
@@ -896,6 +1280,8 @@ export class SandboxClient {
 export class OpenShellClient {
     /** Sandbox lifecycle + exec: create/get/list/delete, waitReady/waitDeleted, exec. */
     sandbox;
+    /** Reusable sandbox workload template lifecycle. */
+    sandboxTemplates;
     /**
      * Advanced escape hatch: a generated client for every gateway RPC, including
      * surface the curated sub-clients do not wrap yet (gateway config, provider
@@ -912,6 +1298,7 @@ export class OpenShellClient {
         this.grpc = createClient(OpenShell, transport);
         this.raw = this.grpc;
         this.sandbox = new SandboxClient(transport, this.grpc);
+        this.sandboxTemplates = new SandboxTemplateClient(transport, this.grpc);
     }
     /**
      * Constructs a lazy Connect client. No network request is made until the