@cofy-x/axern-sdk 0.7.0 → 0.8.0

package/README.md

@@ -80,18 +80,6 @@ const sandbox = await new Sandbox({
 
 `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.
 
 ## Configuration
@@ -106,6 +94,7 @@ Common options:
 - `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:
 
@@ -152,6 +141,8 @@ The SDK loads protobuf definitions through `@grpc/proto-loader`. Dynamic proto a
 
 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.
 
-## Run Output Retention
+## 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.
 
-Run output reads expose Allocation-local stdout/stderr after runtime cleanup until `output_expires_at`, fixed at 15 minutes after cleanup begins. The combined readable limit is 64 MiB, with an explicit truncation signal. Node-process restart preserves sealed output; node-disk loss does not. Ordinary writable files still require explicit download before termination. No durable output object or persistent workspace is created.
+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,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import * as grpc from "@grpc/grpc-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";
@@ -40,8 +41,37 @@ export interface CreateRunOptions {
     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;
@@ -68,10 +98,19 @@ export declare class AxernClient {
     close(): void;
     createEnvironment(options: CreateEnvironmentOptions): Promise<Record<string, unknown>>;
     deleteEnvironment(environmentId: string): Promise<void>;
+    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>>;
+    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,9 +4,10 @@
  * 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 { AllocationClient } from "../node/client.js";
 import { buildResourceSpec } from "../resources.js";
@@ -114,6 +115,24 @@ export class AxernClient {
             throw mapRpcError(error, "delete environment");
         }
     }
+    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 {
@@ -130,6 +149,11 @@ export class AxernClient {
                     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 ?? {},
@@ -140,6 +164,44 @@ export class AxernClient {
             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) });
@@ -238,6 +300,63 @@ export class AxernClient {
             retryDelayMs = Math.min(retryDelayMs * 2, 2_000);
         }
     }
+    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(node, "GetSealedOutputManifest", { allocation_id: allocationId });
+            return (response.outputs ?? []).map(sealedOutput);
+        }
+        catch (error) {
+            throw mapRpcError(error, "get sealed output manifest", allocationId);
+        }
+        finally {
+            node.close();
+        }
+    }
+    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 {
+            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) {
+            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;
+    }
     allocation(allocationId) {
         return new AllocationClient({
             allocationId: required("allocationId", allocationId),
@@ -261,6 +380,40 @@ function transientReadError(error) {
     const code = error.code;
     return code === grpc.status.UNAVAILABLE || code === grpc.status.DEADLINE_EXCEEDED;
 }
+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();

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 export { AxernClient } from "./client/index.js";
-export type { AxernClientOptions, CreateEnvironmentOptions, CreateRunOptions, } from "./client/index.js";
+export type { AxernClientOptions, CreateEnvironmentOptions, CreateRunOptions, DeclaredOutput, DeclaredOutputFormat, ListOptions, ListResult, SealedOutput, } from "./client/index.js";
 export { loadAxernContext, loadAxernEnv } from "./config/index.js";
 export type { AxernConfig } from "./config/index.js";
 export { AxernError, AxernRpcError, isNotFound, isCancelled, isUnavailable, errorRetryable, isPermissionDenied, isTimeout, rpcCode, SandboxExecError, SandboxStateError, SandboxTimeoutError, SandboxValidationError, } from "./errors/index.js";

package/dist/node/archive.js

@@ -8,7 +8,7 @@ import { nonEmptyPath } from "../validation.js";
 import { downloadArchiveStream, uploadArchiveStream } from "./streams.js";
 export async function uploadArchive(ctx, path, chunks, options = {}) {
     try {
-        await ctx.withAuthRetry(options.leaseTtlSeconds ?? 300, (client) => uploadArchiveStream(client, ctx.authRequest({
+        await ctx.withAuthRetry((client) => uploadArchiveStream(client, ctx.authRequest({
             path: nonEmptyPath(path),
             format: 1,
             create_parents: options.createParents ?? true,

package/dist/node/attached_process.js

@@ -18,12 +18,12 @@ export async function process(ctx, command, options = {}) {
         call,
         closeClient: () => client.close(),
     });
-    call.write({
+    await new Promise((resolve, reject) => call.write({
         open: ctx.authRequest({
             spec: execSpec(argv, options),
             ...(initialSize === undefined ? {} : { initial_size: initialSize }),
         }),
-    });
+    }, (error) => error == null ? resolve() : reject(error)));
     try {
         await sandboxProcess.waitReady();
         return sandboxProcess;

package/dist/node/capabilities.js

@@ -7,7 +7,7 @@ import { mapRpcError } from "../errors/index.js";
 import { unary } from "../generated/proto.js";
 export async function capabilityStatus(ctx, options = {}) {
     try {
-        const response = await ctx.withAuthRetry(60, (client) => unary(client, "CapabilityStatus", ctx.authRequest({}), options.rpcTimeoutMs));
+        const response = await ctx.withAuthRetry((client) => unary(client, "CapabilityStatus", ctx.authRequest({}), options.rpcTimeoutMs));
         return {
             ready: response.ready === true,
             capabilities: strings(response.capabilities),

package/dist/node/computer_use.js

@@ -68,7 +68,7 @@ export async function computerUseKeyboard(ctx, options = {}) {
 }
 async function computerUseUnary(ctx, method, payload, rpcTimeoutMs) {
     try {
-        return await ctx.withAuthRetry(60, (client) => unary(client, method, ctx.authRequest(payload), rpcTimeoutMs));
+        return await ctx.withAuthRetry((client) => unary(client, method, ctx.authRequest(payload), rpcTimeoutMs));
     }
     catch (error) {
         throw mapRpcError(error, `sandbox ${method}`, ctx.allocationId);

package/dist/node/context.d.ts

@@ -16,7 +16,7 @@ export declare class NodeClientContext {
     private readonly credentials;
     private readonly channelOptions;
     constructor(options: NodeClientContextOptions);
-    withAuthRetry<T>(_leaseTtlSeconds: number, operation: (client: grpc.Client) => Promise<T>): Promise<T>;
+    withAuthRetry<T>(operation: (client: grpc.Client) => Promise<T>): Promise<T>;
     rpcClient(): grpc.Client;
     authRequest(payload: Record<string, unknown>): Record<string, unknown>;
 }

package/dist/node/context.js

@@ -15,7 +15,7 @@ export class NodeClientContext {
         this.credentials = options.credentials;
         this.channelOptions = options.channelOptions ?? {};
     }
-    async withAuthRetry(_leaseTtlSeconds, operation) {
+    async withAuthRetry(operation) {
         const client = this.rpcClient();
         try {
             return await operation(client);

package/dist/node/exec.js

@@ -9,7 +9,7 @@ import { normalizeCommand } from "../validation.js";
 export async function exec(ctx, command, options = {}) {
     const argv = normalizeCommand(command);
     try {
-        const response = await ctx.withAuthRetry(options.leaseTtlSeconds ?? 300, async (client) => unary(client, "Exec", ctx.authRequest({
+        const response = await ctx.withAuthRetry(async (client) => unary(client, "Exec", ctx.authRequest({
             spec: execSpec(argv, options),
         }), options.rpcTimeoutMs));
         const result = execResult(response);

package/dist/node/files.js

@@ -70,7 +70,7 @@ export async function touch(ctx, path, options = {}) {
 }
 async function fileUnary(ctx, method, payload) {
     try {
-        return await ctx.withAuthRetry(300, (client) => unary(client, method, ctx.authRequest(payload)));
+        return await ctx.withAuthRetry((client) => unary(client, method, ctx.authRequest(payload)));
     }
     catch (error) {
         throw mapRpcError(error, `sandbox ${method}`, ctx.allocationId);

package/dist/node/process.d.ts

@@ -19,18 +19,23 @@ export declare class SandboxProcess {
     private error;
     private ended;
     private exit?;
+    private paused;
+    private closed;
+    private static readonly maxQueuedEvents;
+    private static readonly resumeQueuedEvents;
     constructor(options: SandboxProcessOptions);
-    write(data: Buffer | Uint8Array | string): void;
-    closeStdin(): void;
-    resize(cols: number, rows: number): void;
-    signal(signal: string): void;
-    terminate(): void;
-    kill(): void;
+    write(data: Buffer | Uint8Array | string): Promise<void>;
+    closeStdin(): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    signal(signal: string): Promise<void>;
+    terminate(): Promise<void>;
+    kill(): Promise<void>;
     waitReady(): Promise<void>;
     wait(): Promise<ProcessResult>;
     close(): Promise<void>;
     events(): AsyncIterable<ProcessEvent>;
     private nextEvent;
     private enqueue;
+    private writeRequest;
     private finish;
 }

package/dist/node/process.js

@@ -13,6 +13,10 @@ export class SandboxProcess {
     error;
     ended = false;
     exit;
+    paused = false;
+    closed = false;
+    static maxQueuedEvents = 64;
+    static resumeQueuedEvents = 32;
     constructor(options) {
         this.allocationId = options.allocationId;
         this.call = options.call;
@@ -25,22 +29,22 @@ export class SandboxProcess {
         this.call.on("end", () => this.finish());
     }
     write(data) {
-        this.call.write({ stdin: Buffer.isBuffer(data) ? data : Buffer.from(data) });
+        return this.writeRequest({ stdin: Buffer.isBuffer(data) ? data : Buffer.from(data) });
     }
     closeStdin() {
-        this.call.write({ close_stdin: true });
+        return this.writeRequest({ close_stdin: true });
     }
     resize(cols, rows) {
-        this.call.write({ resize: { cols, rows } });
+        return this.writeRequest({ resize: { cols, rows } });
     }
     signal(signal) {
-        this.call.write({ signal: { signal } });
+        return this.writeRequest({ signal: { signal } });
     }
     terminate() {
-        this.signal("TERM");
+        return this.signal("TERM");
     }
     kill() {
-        this.signal("KILL");
+        return this.signal("KILL");
     }
     async waitReady() {
         const next = await this.nextEvent();
@@ -69,7 +73,14 @@ export class SandboxProcess {
         throw new Error("sandbox process stream ended before exit");
     }
     async close() {
+        if (this.closed)
+            return;
+        if (!this.ended && this.exit === undefined) {
+            await this.terminate().catch(() => undefined);
+        }
+        this.closed = true;
         this.call.end();
+        this.call.cancel();
         this.closeClient();
     }
     async *events() {
@@ -90,6 +101,10 @@ export class SandboxProcess {
     nextEvent() {
         const event = this.queue.shift();
         if (event !== undefined) {
+            if (this.paused && this.queue.length <= SandboxProcess.resumeQueuedEvents) {
+                this.paused = false;
+                this.call.resume();
+            }
             return Promise.resolve({ done: false, value: event });
         }
         if (this.ended) {
@@ -108,8 +123,32 @@ export class SandboxProcess {
             waiter({ done: false, value: event });
         }
         else {
+            if (this.queue.length >= SandboxProcess.maxQueuedEvents) {
+                this.error = new Error("sandbox process consumer is too slow; event queue limit exceeded");
+                this.call.cancel();
+                this.finish();
+                return;
+            }
             this.queue.push(event);
+            if (!this.paused && this.queue.length >= SandboxProcess.maxQueuedEvents) {
+                this.paused = true;
+                this.call.pause();
+            }
+        }
+    }
+    writeRequest(request) {
+        if (this.closed || this.ended) {
+            return Promise.reject(new Error("sandbox process stream is closed"));
         }
+        return new Promise((resolve, reject) => {
+            this.call.write(request, (error) => {
+                if (error !== undefined && error !== null) {
+                    reject(mapRpcError(error, "sandbox process write", this.allocationId));
+                    return;
+                }
+                resolve();
+            });
+        });
     }
     finish() {
         if (this.ended) {

package/dist/proto/axern/control/common/v1/common.proto

@@ -103,6 +103,21 @@ message ImageMount {
   bool readonly = 3;
 }
 
+enum DeclaredOutputFormat {
+  DECLARED_OUTPUT_FORMAT_UNSPECIFIED = 0;
+  DECLARED_OUTPUT_FORMAT_FILE = 1;
+  DECLARED_OUTPUT_FORMAT_TAR = 2;
+}
+
+// DeclaredOutput identifies one bounded Allocation-local result that must be
+// sealed before runtime cleanup. It is a Run output contract, not a durable
+// artifact or workspace identity.
+message DeclaredOutput {
+  string path = 1;
+  DeclaredOutputFormat format = 2;
+  string media_type = 3;
+}
+
 message ExecutionConfig {
   repeated string argv = 1;
   map<string, string> env = 2;
@@ -114,6 +129,7 @@ message ExecutionConfig {
   repeated SecretEnvVar secret_env = 8;
   repeated SecretFile secret_files = 9;
   repeated ImageMount image_mounts = 10;
+  repeated DeclaredOutput declared_outputs = 11;
 }
 
 // AllocationLifecycleState tracks only placement and infrastructure cleanup.

package/dist/proto/axern/control/run/v1/run.proto

@@ -36,13 +36,12 @@ message Run {
   // Latest allocation capability condition projection. It is independent
   // from Run lifecycle status and message.
   axern.control.capability.v1.CapabilityConditionSet capability_conditions = 14;
-  string node_id = 15;
   // Immutable Environment input frozen atomically with Run admission. The
   // source record may be deleted after this Run is created.
-  axern.control.environment.v1.EnvironmentSpec environment_spec = 16;
-  axern.control.environment.v1.ResolvedEnvironmentSpec resolved_environment_spec = 17;
+  axern.control.environment.v1.EnvironmentSpec environment_spec = 15;
+  axern.control.environment.v1.ResolvedEnvironmentSpec resolved_environment_spec = 16;
   // Node-local stdout/stderr availability deadline; node loss may make bytes unavailable earlier.
-  google.protobuf.Timestamp output_expires_at = 18;
+  google.protobuf.Timestamp output_expires_at = 17;
 }
 
 message RunListFilter {

package/dist/proto/axern/control/tunnel/v1/tunnel.proto

@@ -66,22 +66,21 @@ enum TunnelSessionEventReasonCode {
 message TunnelSession {
   string session_id = 1;
   string allocation_id = 2;
-  string node_id = 3;
-  int32 remote_port = 4;
-  string client_edge_target = 5;
-  TunnelSessionStatus status = 6;
-  string reason = 7;
-  string bound_addr = 8;
-  google.protobuf.Timestamp created_at = 9;
-  google.protobuf.Timestamp updated_at = 10;
-  google.protobuf.Timestamp expires_at = 11;
-  string relay_id = 12;
-  google.protobuf.Timestamp ready_at = 13;
-  google.protobuf.Timestamp last_peer_event_at = 14;
-  int64 bytes_in = 15;
-  int64 bytes_out = 16;
-  string namespace = 17;
-  string creator_principal_id = 18;
+  int32 remote_port = 3;
+  string client_edge_target = 4;
+  TunnelSessionStatus status = 5;
+  string reason = 6;
+  string bound_addr = 7;
+  google.protobuf.Timestamp created_at = 8;
+  google.protobuf.Timestamp updated_at = 9;
+  google.protobuf.Timestamp expires_at = 10;
+  string relay_id = 11;
+  google.protobuf.Timestamp ready_at = 12;
+  google.protobuf.Timestamp last_peer_event_at = 13;
+  int64 bytes_in = 14;
+  int64 bytes_out = 15;
+  string namespace = 16;
+  string creator_principal_id = 17;
 }
 
 message TunnelSessionEvent {
@@ -122,9 +121,8 @@ message GetTunnelSessionResponse {
 
 message ListTunnelSessionsRequest {
   string allocation_id = 1;
-  string node_id = 2;
-  bool include_terminal = 3;
-  string namespace = 4;
+  bool include_terminal = 2;
+  string namespace = 3;
 }
 
 message ListTunnelSessionsResponse {

package/dist/proto/axern/node/sandbox/v1/node.proto

@@ -3,6 +3,8 @@ syntax = "proto3";
 package axern.node.sandbox.v1;
 
 import "axern/common/file/v1/file.proto";
+import "axern/control/common/v1/common.proto";
+import "google/protobuf/timestamp.proto";
 
 option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/node/sandbox/v1;nodesandboxv1";
 
@@ -92,6 +94,49 @@ message ReadOutputResponse {
   int64 observed_at_unix_milli = 6;
 }
 
+enum SealedOutputStatus {
+  SEALED_OUTPUT_STATUS_UNSPECIFIED = 0;
+  SEALED_OUTPUT_STATUS_AVAILABLE = 1;
+  SEALED_OUTPUT_STATUS_MISSING = 2;
+  SEALED_OUTPUT_STATUS_REJECTED = 3;
+  SEALED_OUTPUT_STATUS_CAPTURE_FAILED = 4;
+  SEALED_OUTPUT_STATUS_NODE_UNAVAILABLE = 5;
+}
+
+message SealedOutput {
+  string output_id = 1;
+  string path = 2;
+  int64 size_bytes = 3;
+  string sha256 = 4;
+  string media_type = 5;
+  axern.control.common.v1.DeclaredOutputFormat format = 6;
+  SealedOutputStatus status = 7;
+  string reason = 8;
+  google.protobuf.Timestamp sealed_at = 9;
+  google.protobuf.Timestamp expires_at = 10;
+}
+
+message GetSealedOutputManifestRequest {
+  string allocation_id = 1;
+}
+
+message GetSealedOutputManifestResponse {
+  repeated SealedOutput outputs = 1;
+  google.protobuf.Timestamp expires_at = 2;
+}
+
+message DownloadSealedOutputRequest {
+  string allocation_id = 1;
+  string output_id = 2;
+  int64 offset = 3;
+}
+
+message DownloadSealedOutputResponse {
+  bytes data = 1;
+  int64 next_offset = 2;
+  bool eof = 3;
+}
+
 // Capabilities
 
 message CapabilityStatusRequest {
@@ -338,6 +383,8 @@ service NodeSandbox {
   rpc Exec(ExecRequest) returns (ExecResponse) {}
   rpc Process(stream ProcessRequest) returns (stream ProcessResponse) {}
   rpc ReadOutput(ReadOutputRequest) returns (stream ReadOutputResponse) {}
+  rpc GetSealedOutputManifest(GetSealedOutputManifestRequest) returns (GetSealedOutputManifestResponse) {}
+  rpc DownloadSealedOutput(DownloadSealedOutputRequest) returns (stream DownloadSealedOutputResponse) {}
   rpc CapabilityStatus(CapabilityStatusRequest) returns (CapabilityStatusResponse) {}
   rpc StatFile(StatFileRequest) returns (StatFileResponse) {}
   rpc ListDir(ListDirRequest) returns (ListDirResponse) {}

package/dist/sandbox/index.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { AxernClient } from "../client/index.js";
-import type { ExtensionCapability } from "../client/index.js";
+import type { DeclaredOutput, ExtensionCapability } from "../client/index.js";
 import type { SandboxProcess } from "../node/process.js";
 import type { ResourceQuantity } from "../resources.js";
 import type { NetworkPolicy } from "../network-policy.js";
@@ -20,6 +20,7 @@ export interface SandboxOptions {
     cwd?: string;
     networkPolicy?: NetworkPolicy;
     extensionCapabilities?: readonly ExtensionCapability[];
+    declaredOutputs?: readonly DeclaredOutput[];
     requestCpu?: ResourceQuantity;
     requestMemory?: ResourceQuantity;
     requestEphemeralStorage?: ResourceQuantity;
@@ -36,7 +37,6 @@ export interface SandboxState {
     environmentId: string;
     runId: string;
     allocationId: string;
-    nodeId: string;
     startedAt: Date;
 }
 export interface SandboxMetadata extends SandboxState {

package/dist/sandbox/index.js

@@ -60,6 +60,7 @@ export class Sandbox {
                 cwd: this.options.cwd,
                 networkPolicy: this.options.networkPolicy,
                 extensionCapabilities: this.options.extensionCapabilities,
+                declaredOutputs: this.options.declaredOutputs,
                 requestCpu: this.options.requestCpu,
                 requestMemory: this.options.requestMemory,
                 requestEphemeralStorage: this.options.requestEphemeralStorage,
@@ -74,7 +75,6 @@ export class Sandbox {
                 environmentId,
                 runId: this.runId,
                 allocationId: String(runningRun.allocation_id ?? ""),
-                nodeId: String(runningRun.node_id ?? ""),
                 startedAt: new Date(),
             };
             this.currentMetadata = sandboxMetadata(this.options, this.currentState);
@@ -93,11 +93,17 @@ export class Sandbox {
             return this;
         }
         catch (error) {
-            await this.close();
+            try {
+                await this.close();
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "sandbox start and cleanup failed");
+            }
             throw error;
         }
     }
     async close() {
+        const errors = [];
         const runId = this.runId;
         const tunnelRuntime = this.tunnelRuntime;
         this.runId = "";
@@ -105,17 +111,19 @@ export class Sandbox {
         this.currentState = undefined;
         this.currentMetadata = undefined;
         if (tunnelRuntime !== undefined) {
-            await tunnelRuntime.stop().catch(() => undefined);
+            await tunnelRuntime.stop().catch((error) => errors.push(error));
         }
         if (runId !== "") {
-            await this.client.cancelRun(runId).catch(() => undefined);
+            await this.client.cancelRun(runId).catch((error) => errors.push(error));
         }
         if (this.createdEnvironment && this.environmentId !== "") {
             const environmentId = this.environmentId;
             this.environmentId = "";
             this.createdEnvironment = false;
-            await this.client.deleteEnvironment(environmentId).catch(() => undefined);
+            await this.client.deleteEnvironment(environmentId).catch((error) => errors.push(error));
         }
+        if (errors.length > 0)
+            throw new AggregateError(errors, "sandbox cleanup failed");
     }
     async exec(command, options = {}) {
         return this.nodeClient().exec(command, options);

package/dist/types.d.ts

@@ -12,7 +12,6 @@ export interface ExecOptions {
     user?: string;
     tty?: boolean;
     check?: boolean;
-    leaseTtlSeconds?: number;
     rpcTimeoutMs?: number;
 }
 export interface ExecResult {
@@ -91,11 +90,9 @@ export interface DownloadDirOptions {
 export interface UploadArchiveOptions {
     createParents?: boolean;
     overwrite?: boolean;
-    leaseTtlSeconds?: number;
     rpcTimeoutMs?: number;
 }
 export interface DownloadArchiveOptions {
-    leaseTtlSeconds?: number;
     rpcTimeoutMs?: number;
 }
 export interface TunnelOptions {

package/dist/version.d.ts

@@ -3,5 +3,5 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const AXERN_VERSION = "0.7.0";
+export declare const AXERN_VERSION = "0.8.0";
 export declare function platformName(): string;

package/dist/version.js

@@ -3,7 +3,7 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-export const AXERN_VERSION = "0.7.0";
+export const AXERN_VERSION = "0.8.0";
 export function platformName() {
     return "axern";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cofy-x/axern-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK for Axern agentic infrastructure and isolated sandboxes",
   "license": "Apache-2.0",
   "repository": {

package/dist/proto/axern/control/gateway/v1/gateway.proto

@@ -1,51 +0,0 @@
-syntax = "proto3";
-
-package axern.control.gateway.v1;
-
-option go_package = "github.com/cofy-x/axern/sdk/go/gen/axern/control/gateway/v1;gatewayv1";
-
-import "google/protobuf/timestamp.proto";
-import "google/protobuf/empty.proto";
-message ResolveAllocationTerminalRequest {
-  string allocation_id = 1;
-  int64 ttl_seconds = 2;
-  string credential_fingerprint = 3;
-  AllocationAccessPurpose purpose = 4;
-  string credential_kind = 5;
-}
-
-enum AllocationAccessPurpose {
-  ALLOCATION_ACCESS_PURPOSE_UNSPECIFIED = 0;
-  ALLOCATION_ACCESS_PURPOSE_INTERACTIVE = 1;
-  ALLOCATION_ACCESS_PURPOSE_RUN_OUTPUT = 2;
-}
-
-message ResolveAllocationTerminalResponse {
-  string allocation_id = 1;
-  string run_id = 2;
-  string node_id = 3;
-  string node_target = 4;
-  AllocationAccessGrant access_grant = 5;
-}
-
-message AllocationAccessGrant {
-  string grant_id = 1;
-  string allocation_id = 2;
-  string node_id = 3;
-  string plaintext_token = 4;
-  google.protobuf.Timestamp expires_at = 5;
-}
-
-message ResolveTunnelRelayTargetRequest {
-  string session_id = 1;
-}
-
-message ResolveTunnelRelayTargetResponse {
-  string node_edge_target = 1;
-}
-
-service GatewayControl {
-  rpc AuthorizeAllocationAccess(ResolveAllocationTerminalRequest) returns (google.protobuf.Empty) {}
-  rpc ResolveAllocationTerminal(ResolveAllocationTerminalRequest) returns (ResolveAllocationTerminalResponse) {}
-  rpc ResolveTunnelRelayTarget(ResolveTunnelRelayTargetRequest) returns (ResolveTunnelRelayTargetResponse) {}
-}