@cofy-x/axern-sdk 0.6.2 → 0.8.0

package/README.md

@@ -28,18 +28,14 @@ pnpm install
 make sdk-typescript-verify
 ```
 
-The SDK dynamically loads Axern proto definitions from `sdk/proto`. Set
-`AXERN_PROTO_ROOT` when running from a different layout.
+The SDK dynamically loads Axern proto definitions from `sdk/proto`. Set `AXERN_PROTO_ROOT` when running from a different layout.
 
 ## Basic Usage
 
 ```ts
 import { AxernClient, Sandbox } from "@cofy-x/axern-sdk";
 
-const client = AxernClient.fromContext(
-  process.env.AXERN_CONFIG ?? `${process.env.HOME}/.config/axern/config.json`,
-  process.env.AXERN_CONTEXT,
-);
+const client = AxernClient.fromContext(process.env.AXERN_CONFIG ?? `${process.env.HOME}/.config/axern/config.json`, process.env.AXERN_CONTEXT);
 
 const sandbox = await new Sandbox({
   client,
@@ -70,9 +66,7 @@ try {
 
 ## Network Policies
 
-Omitting `networkPolicy` keeps unrestricted v0.5 behavior. Strict policies are
-fail-closed; `denyDns` only refuses matching traditional UDP/TCP DNS queries and
-does not block direct IP traffic, DoH, DoT, or already-resolved addresses.
+Omitting `networkPolicy` requests unrestricted networking. Strict policies are fail-closed; `denyDns` only refuses matching traditional UDP/TCP DNS queries and does not block direct IP traffic, DoH, DoT, or already-resolved addresses.
 
 ```ts
 import { NetworkPolicy, Sandbox } from "@cofy-x/axern-sdk";
@@ -80,89 +74,47 @@ import { NetworkPolicy, Sandbox } from "@cofy-x/axern-sdk";
 const sandbox = await new Sandbox({
   client,
   image: "docker.io/library/python:3.12-slim",
-  networkPolicy: NetworkPolicy.denyDns(
-    "github.com",
-    "*.github.com",
-    "githubusercontent.com",
-    "*.githubusercontent.com",
-  ),
+  networkPolicy: NetworkPolicy.denyDns("github.com", "*.github.com", "githubusercontent.com", "*.githubusercontent.com"),
 }).start();
 ```
 
-`NetworkPolicy.allowDomains("example.com", "*.example.com")` allows only
-strict HTTP/HTTPS destinations validated by DNS plus HTTP Host or TLS SNI.
-`NetworkPolicy.strict({ cidrRules: [...] })` adds explicit TCP/UDP CIDR and port
-grants; `NetworkPolicy.denyAll()` allows no egress.
+`NetworkPolicy.allowDomains("example.com", "*.example.com")` allows only strict HTTP/HTTPS destinations validated by DNS plus HTTP Host or TLS SNI. `NetworkPolicy.strict({ cidrRules: [...] })` adds explicit TCP/UDP CIDR and port grants; `NetworkPolicy.denyAll()` allows no egress.
 
-Run a tool from a separate image with `execImage` or `processImage`. OCI and
-Nydus refs use the same image field. When `mounts` is omitted, the SDK requests
-`/workspace -> /workspace`; pass `mounts: []` for no shared paths. Use
-`new Sandbox({ image })` when the image should be the sandbox rootfs with normal
-files, exec, process, tunnel, and lifecycle APIs; image-backed processes are
-temporary side processes attached to an existing sandbox.
-
-```ts
-import { workspaceMount } from "@cofy-x/axern-sdk";
-
-const result = await sandbox.execImage("ghcr.io/cofy-x/agent:latest", "tool run", {
-  check: true,
-  mounts: [workspaceMount("/workspace")],
-});
-console.log(result.stdoutText());
-```
-
-`AxernClient` requires an explicit endpoint. Use `AxernClient.fromContext()` in
-interactive examples or `AxernClient.fromEnv()` in environment-driven
-automation. Neither the client constructor nor `Sandbox` silently reads the
-user directory.
+`AxernClient` requires an explicit endpoint. Use `AxernClient.fromContext()` in interactive examples or `AxernClient.fromEnv()` in environment-driven automation. Neither the client constructor nor `Sandbox` silently reads the user directory.
 
 ## Configuration
 
-`Sandbox` requires exactly one source: `templateId`, `image`, or
-`environmentId`.
+`Sandbox` requires exactly one source: `templateId`, `image`, or `environmentId`.
 
 Common options:
 
 - `namespace`: control-plane namespace, default `default`
 - `client`: explicit `AxernClient` shared by the sandbox
 - `argv`, `env`, `cwd`: initial sandbox process configuration
-- `runtimeClass`: runtime selector, for example `runsc` or `runc`
-- `requestCpu`, `requestMemory`, `requestEphemeralStorage`: scheduler resource
-  requests such as `500m`, `512MiB`, and `1GiB`; numeric CPU values are cores
-  and numeric memory/storage values are bytes
-- `limitCpu`, `limitMemory`, `limitEphemeralStorage`: runtime hard limits;
-  numeric CPU values are cores and numeric memory/storage values are bytes
-- `readyTimeoutMs`: service replica readiness timeout
+- `requestCpu`, `requestMemory`, `requestEphemeralStorage`: scheduler resource requests such as `500m`, `512MiB`, and `1GiB`; numeric CPU values are cores and numeric memory/storage values are bytes
+- `limitCpu`, `limitMemory`, `limitEphemeralStorage`: runtime hard limits; numeric CPU values are cores and numeric memory/storage values are bytes
+- `readyTimeoutMs`: Run allocation startup timeout
+- `declaredOutputs`: bounded files or directory-as-tar outputs sealed before runtime cleanup
 
 Tunnel options:
 
-- `tunnel.upstream`: local TCP address reached by the SDK connector, for
-  example `127.0.0.1:8080`
+- `tunnel.upstream`: local TCP address reached by the SDK connector, for example `127.0.0.1:8080`
 - `tunnel.proxyPort`: sandbox-local port bound by Axern, default `8786`
 - `tunnel.ttlSeconds`: control-plane tunnel session TTL, renewed by the SDK
 
-Tunnel traffic reuses the client gateway endpoint, mTLS identity, server name,
-and proxy policy.
+Tunnel traffic reuses the client gateway endpoint, mTLS identity, server name, and proxy policy.
 
-After `start()`, use `sandbox.metadata.tunnel?.boundAddr` from inside the
-sandbox, for example `http://127.0.0.1:8786`.
+After `start()`, use `sandbox.metadata.tunnel?.boundAddr` from inside the sandbox, for example `http://127.0.0.1:8786`.
 
 ## Sandbox API
 
 - Lifecycle: `start()`, `close()`, `state`, `metadata`
 - Execution: `exec(command, options)`, `process(command, options)`
-- Agent sandbox: `capabilityStatus`, `computerUseStatus`,
-  `computerUseScreenshot`, `computerUseDisplay`, `computerUseMouse`,
-  `computerUseKeyboard`
-- Files: `readFile`, `readText`, `writeFile`, `writeText`, `stat`, `listDir`,
-  `exists`, `mkdir`, `remove`, `copy`, `move`, `chmod`, `touch`
-- Directories: `uploadDir(localPath, remotePath)`,
-  `downloadDir(remotePath, localPath)`
-- Tunnel: `new Sandbox({ tunnel: { upstream, proxyPort } })`,
-  `metadata.tunnel`
-- Errors: `AxernRpcError`, `SandboxExecError`, `SandboxStateError`,
-  `SandboxValidationError`, `isNotFound`, `isPermissionDenied`, `isTimeout`,
-  `rpcCode`
+- Agent sandbox: `capabilityStatus`, `computerUseStatus`, `computerUseScreenshot`, `computerUseDisplay`, `computerUseMouse`, `computerUseKeyboard`
+- Files: `readFile`, `readText`, `writeFile`, `writeText`, `stat`, `listDir`, `exists`, `mkdir`, `remove`, `copy`, `move`, `chmod`, `touch`
+- Directories: `uploadDir(localPath, remotePath)`, `downloadDir(remotePath, localPath)`
+- Tunnel: `new Sandbox({ tunnel: { upstream, proxyPort } })`, `metadata.tunnel`
+- Errors: `AxernRpcError`, `SandboxExecError`, `SandboxStateError`, `SandboxValidationError`, `isNotFound`, `isPermissionDenied`, `isTimeout`, `rpcCode`
 
 ## Local Smoke
 
@@ -173,9 +125,7 @@ pnpm --filter @cofy-x/axern-sdk run smoke:local
 pnpm --filter @cofy-x/axern-sdk run smoke:tunnel
 ```
 
-The smoke loads `deploy/local/state/compose/axern.env` when present. It uses the
-`python311` template by default; set `AXERN_TS_SMOKE_IMAGE` to verify an image
-source instead.
+The smoke loads `deploy/local/state/compose/axern.env` when present. It uses the `python311` template by default; set `AXERN_TS_SMOKE_IMAGE` to verify an image source instead.
 
 Check package contents with:
 
@@ -185,12 +135,14 @@ pnpm --filter @cofy-x/axern-sdk run pack:dry-run
 
 ## Proto Boundary
 
-The SDK loads protobuf definitions through `@grpc/proto-loader`. Dynamic proto
-access remains isolated under `src/generated`; public callers depend only on
-the stable TypeScript DTOs and error types.
+The SDK loads protobuf definitions through `@grpc/proto-loader`. Dynamic proto access remains isolated under `src/generated`; public callers depend only on the stable TypeScript DTOs and error types.
 
 ## Scope
 
-This SDK is Node.js-first. The higher-level Browser API, generated TypeScript
-proto stubs, and full control-plane administration APIs remain outside the
-v0.2 public contract.
+This SDK is Node.js-first. Browser automation runs as caller-owned workload software through process and Computer Use operations; generated TypeScript proto stubs and full control-plane administration APIs remain outside its public contract.
+
+## Declared And Stream Output
+
+Pass `declaredOutputs` when creating a Run or Sandbox, then use `getSealedOutputManifest(runId)` and `downloadSealedOutput(runId, outputId, writable)` after the Run becomes terminal. Full downloads verify size and SHA-256 while respecting the destination stream's backpressure. Declared output is Node-local for 15 minutes after cleanup starts: it survives axnoded restart but not Node-disk loss. Limits are 16 paths, 64 MiB per file, 256 MiB per tar, and 256 MiB total. It is not a persistent workspace or object store.
+
+Attached Process queues at most 64 unread events, pauses the gRPC stream at the bound, and resumes below the low-water mark. `write`, `closeStdin`, signal, and resize promises resolve only after the gRPC write callback. Closing an attached process attempts `TERM`; durable workload termination remains Run cancellation. `Sandbox.close()` reports cleanup failures and does not wait for a terminal Run, so call `waitRun()` when terminal confirmation is required.

package/dist/client/index.d.ts

@@ -4,11 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import * as grpc from "@grpc/grpc-js";
-import { NodeSandboxClient } from "../node/client.js";
+import type { Writable } from "node:stream";
+import { AllocationClient } from "../node/client.js";
 import type { ResourceQuantity } from "../resources.js";
 import type { NetworkPolicy } from "../network-policy.js";
 import { TunnelControlClient } from "../tunnel/control.js";
-import type { VolumeMount } from "../types.js";
 import type { GatewayTransportOptions } from "../tunnel/relay.js";
 export interface AxernClientOptions {
     endpoint: string;
@@ -27,24 +27,51 @@ export interface CreateEnvironmentOptions {
     rootfsReadonly?: boolean;
     labels?: Record<string, string>;
 }
-export interface CreateServiceOptions {
+export interface CreateRunOptions {
     namespace?: string;
     environmentId: string;
     argv?: string[];
     env?: Record<string, string>;
     cwd?: string;
-    runtimeClass?: string;
     networkPolicy?: NetworkPolicy;
     extensionCapabilities?: readonly ExtensionCapability[];
-    volumes?: readonly VolumeMount[];
     requestCpu?: ResourceQuantity;
     requestMemory?: ResourceQuantity;
     requestEphemeralStorage?: ResourceQuantity;
     limitCpu?: ResourceQuantity;
     limitMemory?: ResourceQuantity;
     limitEphemeralStorage?: ResourceQuantity;
+    declaredOutputs?: readonly DeclaredOutput[];
     labels?: Record<string, string>;
 }
+export type DeclaredOutputFormat = "file" | "tar";
+export interface DeclaredOutput {
+    path: string;
+    format: DeclaredOutputFormat;
+    mediaType?: string;
+}
+export interface SealedOutput {
+    outputId: string;
+    path: string;
+    sizeBytes: number;
+    sha256: string;
+    mediaType: string;
+    format?: DeclaredOutputFormat;
+    status: "available" | "missing" | "rejected" | "capture_failed" | "node_unavailable" | "unspecified";
+    reason: string;
+    sealedAt?: Record<string, unknown>;
+    expiresAt?: Record<string, unknown>;
+}
+export interface ListOptions {
+    namespace?: string;
+    labels?: Record<string, string>;
+    cursor?: string;
+    pageSize?: number;
+}
+export interface ListResult<T> {
+    items: T[];
+    nextCursor: string;
+}
 export interface ExtensionCapability {
     name: string;
     value?: string;
@@ -53,13 +80,16 @@ export interface ReadRunOutputOptions {
     cursor?: string;
     follow?: boolean;
 }
+export interface WatchRunOptions {
+    afterVersion?: number;
+    signal?: AbortSignal;
+}
 export declare class AxernClient {
     readonly endpoint: string;
     private readonly credentials;
     private readonly controlOptions;
     private readonly environmentControl;
     private readonly runControl;
-    private readonly serviceControl;
     private readonly tunnelControl;
     private readonly gatewayTransport;
     constructor(options: AxernClientOptions);
@@ -68,12 +98,20 @@ export declare class AxernClient {
     close(): void;
     createEnvironment(options: CreateEnvironmentOptions): Promise<Record<string, unknown>>;
     deleteEnvironment(environmentId: string): Promise<void>;
-    watchRun(runId: string, afterVersion?: number): AsyncGenerator<Record<string, unknown>>;
+    getEnvironment(environmentId: string): Promise<Record<string, unknown>>;
+    listEnvironments(options?: ListOptions): Promise<ListResult<Record<string, unknown>>>;
+    createRun(options: CreateRunOptions): Promise<Record<string, unknown>>;
+    getRun(runId: string): Promise<Record<string, unknown>>;
+    listRuns(options?: ListOptions & {
+        statuses?: number[];
+    }): Promise<ListResult<Record<string, unknown>>>;
+    waitRun(runId: string, timeoutMs?: number): Promise<Record<string, unknown>>;
+    cancelRun(runId: string): Promise<void>;
+    watchRun(runId: string, options?: WatchRunOptions): AsyncGenerator<Record<string, unknown>>;
     readRunOutput(runId: string, options?: ReadRunOutputOptions): AsyncGenerator<Record<string, unknown>>;
-    createService(options: CreateServiceOptions): Promise<Record<string, unknown>>;
-    deleteService(serviceId: string): Promise<void>;
-    listServiceReplicas(serviceId: string): Promise<Record<string, unknown>[]>;
-    nodeSandbox(allocationId: string): NodeSandboxClient;
+    getSealedOutputManifest(runId: string): Promise<SealedOutput[]>;
+    downloadSealedOutput(runId: string, outputId: string, destination: Writable): Promise<SealedOutput>;
+    allocation(allocationId: string): AllocationClient;
     tunnelClient(): TunnelControlClient;
     tunnelTransport(): GatewayTransportOptions;
 }

package/dist/client/index.js

@@ -4,11 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import * as grpc from "@grpc/grpc-js";
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { loadAxernContext, loadAxernEnv, normalizeProxyMode } from "../config/index.js";
-import { mapRpcError } from "../errors/index.js";
+import { SandboxStateError, SandboxTimeoutError, mapRpcError } from "../errors/index.js";
 import { serviceConstructor, unary } from "../generated/proto.js";
-import { NodeSandboxClient } from "../node/client.js";
+import { AllocationClient } from "../node/client.js";
 import { buildResourceSpec } from "../resources.js";
 import { TunnelControlClient } from "../tunnel/control.js";
 import { required } from "../validation.js";
@@ -18,7 +19,6 @@ export class AxernClient {
     controlOptions;
     environmentControl;
     runControl;
-    serviceControl;
     tunnelControl;
     gatewayTransport;
     constructor(options) {
@@ -57,11 +57,9 @@ export class AxernClient {
             "EnvironmentControl",
         ]);
         const RunControl = serviceConstructor(["axern", "control", "run", "v1", "RunControl"]);
-        const ServiceControl = serviceConstructor(["axern", "control", "service", "v1", "ServiceControl"]);
         const TunnelControl = serviceConstructor(["axern", "control", "tunnel", "v1", "TunnelControl"]);
         this.environmentControl = new EnvironmentControl(this.endpoint, this.credentials, this.controlOptions);
         this.runControl = new RunControl(this.endpoint, this.credentials, this.controlOptions);
-        this.serviceControl = new ServiceControl(this.endpoint, this.credentials, this.controlOptions);
         this.tunnelControl = new TunnelControl(this.endpoint, this.credentials, this.controlOptions);
     }
     static fromEnv(overrides = {}) {
@@ -82,7 +80,6 @@ export class AxernClient {
     close() {
         this.environmentControl.close();
         this.runControl.close();
-        this.serviceControl.close();
         this.tunnelControl.close();
     }
     async createEnvironment(options) {
@@ -118,17 +115,118 @@ export class AxernClient {
             throw mapRpcError(error, "delete environment");
         }
     }
-    async *watchRun(runId, afterVersion = 0) {
+    async getEnvironment(environmentId) {
+        try {
+            const response = await unary(this.environmentControl, "GetEnvironment", { environment_id: required("environmentId", environmentId) });
+            return response.environment;
+        }
+        catch (error) {
+            throw mapRpcError(error, "get environment");
+        }
+    }
+    async listEnvironments(options = {}) {
+        try {
+            const response = await unary(this.environmentControl, "ListEnvironments", { filter: { namespace: options.namespace ?? "", labels: options.labels ?? {}, cursor: options.cursor ?? "", page_size: options.pageSize ?? 0 } });
+            return { items: response.environments ?? [], nextCursor: response.next_cursor ?? "" };
+        }
+        catch (error) {
+            throw mapRpcError(error, "list environments");
+        }
+    }
+    async createRun(options) {
+        const resources = buildResourceSpec(options);
+        try {
+            const response = await unary(this.runControl, "CreateRun", {
+                namespace: options.namespace ?? "default",
+                environment_id: required("environmentId", options.environmentId),
+                config: {
+                    argv: options.argv ?? [],
+                    env: options.env ?? {},
+                    cwd: options.cwd ?? "",
+                    ...(options.networkPolicy === undefined
+                        ? {}
+                        : { network: { egress_policy: options.networkPolicy.toWire() } }),
+                    extension_capability_requirements: (options.extensionCapabilities ?? []).map((capability) => ({
+                        capability: { name: capability.name, value: capability.value ?? "" },
+                    })),
+                    declared_outputs: (options.declaredOutputs ?? []).map((output) => ({
+                        path: output.path,
+                        format: output.format === "file" ? 1 : 2,
+                        media_type: output.mediaType ?? "",
+                    })),
+                    resources,
+                },
+                labels: options.labels ?? {},
+            });
+            return response.run;
+        }
+        catch (error) {
+            throw mapRpcError(error, "create run");
+        }
+    }
+    async getRun(runId) {
+        try {
+            const response = await unary(this.runControl, "GetRun", { run_id: required("runId", runId) });
+            return response.run;
+        }
+        catch (error) {
+            throw mapRpcError(error, "get run");
+        }
+    }
+    async listRuns(options = {}) {
+        try {
+            const response = await unary(this.runControl, "ListRuns", { filter: { namespace: options.namespace ?? "", labels: options.labels ?? {}, statuses: options.statuses ?? [], cursor: options.cursor ?? "", page_size: options.pageSize ?? 0 } });
+            return { items: response.runs ?? [], nextCursor: response.next_cursor ?? "" };
+        }
+        catch (error) {
+            throw mapRpcError(error, "list runs");
+        }
+    }
+    async waitRun(runId, timeoutMs) {
+        const initial = await this.getRun(runId);
+        if (terminalRun(initial))
+            return initial;
+        const controller = new AbortController();
+        const timer = timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            for await (const run of this.watchRun(runId, { afterVersion: Number(initial.version ?? 0), signal: controller.signal })) {
+                if (terminalRun(run))
+                    return run;
+            }
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        if (controller.signal.aborted)
+            throw new SandboxTimeoutError(`run ${runId} wait timed out`);
+        throw new SandboxStateError(`run ${runId} watch ended before a terminal state`);
+    }
+    async cancelRun(runId) {
+        try {
+            await unary(this.runControl, "CancelRun", { run_id: required("runId", runId) });
+        }
+        catch (error) {
+            throw mapRpcError(error, "cancel run");
+        }
+    }
+    async *watchRun(runId, options = {}) {
+        const afterVersion = options.afterVersion ?? 0;
+        const signal = options.signal;
         if (afterVersion < 0) {
             throw new Error("afterVersion must be non-negative");
         }
         let version = afterVersion;
         let retryDelayMs = 100;
         for (;;) {
+            if (signal?.aborted)
+                return;
             const stream = serverStream(this.runControl, "WatchRun", {
                 run_id: required("runId", runId),
                 after_version: version,
             });
+            const cancel = () => stream.cancel();
+            signal?.addEventListener("abort", cancel, { once: true });
             try {
                 for await (const response of stream) {
                     const run = response.run;
@@ -144,14 +242,21 @@ export class AxernClient {
                 return;
             }
             catch (error) {
+                if (signal?.aborted)
+                    return;
                 if (!transientReadError(error))
                     throw mapRpcError(error, "watch run");
             }
-            await sleep(retryDelayMs);
+            finally {
+                signal?.removeEventListener("abort", cancel);
+            }
+            await sleep(retryDelayMs, signal);
             retryDelayMs = Math.min(retryDelayMs * 2, 2_000);
         }
     }
     async *readRunOutput(runId, options = {}) {
+        // Output is Allocation-local and may be unavailable after cleanup; callers
+        // that need durable bytes must consume and persist them before then.
         const response = await unary(this.runControl, "GetRun", { run_id: required("runId", runId) });
         const allocationId = String(response.run?.allocation_id ?? "");
         if (allocationId === "")
@@ -195,57 +300,65 @@ export class AxernClient {
             retryDelayMs = Math.min(retryDelayMs * 2, 2_000);
         }
     }
-    async createService(options) {
-        const resources = buildResourceSpec(options);
+    async getSealedOutputManifest(runId) {
+        const run = await this.getRun(runId);
+        const allocationId = String(run.allocation_id ?? "");
+        if (allocationId === "")
+            throw new Error(`run ${runId} has no allocation`);
+        const NodeSandbox = serviceConstructor(["axern", "node", "sandbox", "v1", "NodeSandbox"]);
+        const node = new NodeSandbox(this.endpoint, this.credentials, this.controlOptions);
         try {
-            const response = await unary(this.serviceControl, "CreateService", {
-                namespace: options.namespace ?? "default",
-                environment_id: required("environmentId", options.environmentId),
-                replicas: 1,
-                config: {
-                    argv: options.argv ?? [],
-                    env: options.env ?? {},
-                    cwd: options.cwd ?? "",
-                    runtime_class: options.runtimeClass ?? "",
-                    ...(options.networkPolicy === undefined
-                        ? {}
-                        : { network: { egress_policy: options.networkPolicy.toWire() } }),
-                    extension_capability_requirements: (options.extensionCapabilities ?? []).map((capability) => ({
-                        capability: { name: capability.name, value: capability.value ?? "" },
-                    })),
-                    volume_mounts: serviceVolumeMounts(options.volumes),
-                    resources,
-                },
-                labels: options.labels ?? {},
-            });
-            return response.service;
+            const response = await unary(node, "GetSealedOutputManifest", { allocation_id: allocationId });
+            return (response.outputs ?? []).map(sealedOutput);
         }
         catch (error) {
-            throw mapRpcError(error, "create service");
+            throw mapRpcError(error, "get sealed output manifest", allocationId);
         }
-    }
-    async deleteService(serviceId) {
-        try {
-            await unary(this.serviceControl, "DeleteService", { service_id: required("serviceId", serviceId) });
-        }
-        catch (error) {
-            throw mapRpcError(error, "delete service");
+        finally {
+            node.close();
         }
     }
-    async listServiceReplicas(serviceId) {
+    async downloadSealedOutput(runId, outputId, destination) {
+        const outputs = await this.getSealedOutputManifest(runId);
+        const selected = outputs.find((output) => output.outputId === outputId);
+        if (selected === undefined || selected.status !== "available") {
+            throw new Error(`sealed output ${outputId} is not available`);
+        }
+        const run = await this.getRun(runId);
+        const allocationId = String(run.allocation_id ?? "");
+        const NodeSandbox = serviceConstructor(["axern", "node", "sandbox", "v1", "NodeSandbox"]);
+        const node = new NodeSandbox(this.endpoint, this.credentials, this.controlOptions);
+        const stream = serverStream(node, "DownloadSealedOutput", { allocation_id: allocationId, output_id: outputId, offset: "0" });
+        const digest = createHash("sha256");
+        let offset = 0;
         try {
-            const response = await unary(this.serviceControl, "ListServiceReplicas", {
-                service_id: required("serviceId", serviceId),
-                filter: { view: 2 },
-            });
-            return response.replicas ?? [];
+            for await (const response of stream) {
+                const data = Buffer.from(response.data ?? []);
+                const nextOffset = Number(response.next_offset ?? offset + data.length);
+                if (nextOffset !== offset + data.length)
+                    throw new Error("sealed output returned a non-contiguous offset");
+                digest.update(data);
+                await writeChunk(destination, data);
+                offset = nextOffset;
+            }
         }
         catch (error) {
-            throw mapRpcError(error, "list service replicas");
+            if (typeof error === "object" && error !== null && "code" in error) {
+                throw mapRpcError(error, "download sealed output", allocationId);
+            }
+            throw error;
+        }
+        finally {
+            node.close();
         }
+        if (offset !== selected.sizeBytes)
+            throw new Error("sealed output size does not match its manifest");
+        if (digest.digest("hex") !== selected.sha256)
+            throw new Error("sealed output digest does not match its manifest");
+        return selected;
     }
-    nodeSandbox(allocationId) {
-        return new NodeSandboxClient({
+    allocation(allocationId) {
+        return new AllocationClient({
             allocationId: required("allocationId", allocationId),
             target: this.endpoint,
             credentials: this.credentials,
@@ -259,14 +372,6 @@ export class AxernClient {
         return { ...this.gatewayTransport };
     }
 }
-function serviceVolumeMounts(mounts) {
-    return (mounts ?? []).map((mount) => ({
-        name: mount.name,
-        target: mount.target,
-        readonly: mount.readonly ?? false,
-        options: [...(mount.options ?? [])],
-    }));
-}
 function serverStream(client, method, request) {
     const fn = client[method];
     return fn.call(client, request);
@@ -275,8 +380,52 @@ function transientReadError(error) {
     const code = error.code;
     return code === grpc.status.UNAVAILABLE || code === grpc.status.DEADLINE_EXCEEDED;
 }
-function sleep(milliseconds) {
-    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+function terminalRun(run) {
+    const status = Number(run.status ?? 0);
+    return status === 4 || status === 5 || status === 6;
+}
+function sealedOutput(value) {
+    const formats = { 1: "file", 2: "tar" };
+    const statuses = ["unspecified", "available", "missing", "rejected", "capture_failed", "node_unavailable"];
+    return {
+        outputId: String(value.output_id ?? ""),
+        path: String(value.path ?? ""),
+        sizeBytes: Number(value.size_bytes ?? 0),
+        sha256: String(value.sha256 ?? ""),
+        mediaType: String(value.media_type ?? ""),
+        format: formats[Number(value.format ?? 0)],
+        status: statuses[Number(value.status ?? 0)] ?? "unspecified",
+        reason: String(value.reason ?? ""),
+        sealedAt: value.sealed_at,
+        expiresAt: value.expires_at,
+    };
+}
+function writeChunk(destination, chunk) {
+    if (destination.write(chunk))
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            destination.off("drain", drained);
+            destination.off("error", failed);
+        };
+        const drained = () => { cleanup(); resolve(); };
+        const failed = (error) => { cleanup(); reject(error); };
+        destination.once("drain", drained);
+        destination.once("error", failed);
+    });
+}
+function sleep(milliseconds, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const complete = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", complete);
+            resolve();
+        };
+        const timer = setTimeout(complete, milliseconds);
+        signal?.addEventListener("abort", complete, { once: true });
+    });
 }
 function controlCredentials(options) {
     const configured = [options.tlsCaCert, options.tlsCert, options.tlsKey].filter((value) => value !== undefined && value !== "");

package/dist/config/index.d.ts

@@ -1,7 +1,6 @@
 /** Explicit environment and context loaders for the Axern SDK. */
 export interface AxernConfig {
     endpoint: string;
-    serviceUrl?: string;
     sshEndpoint?: string;
     sshIdentityFile?: string;
     tlsCaCert?: string;