@cofy-x/axern-sdk 0.6.2 → 0.7.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,26 +74,13 @@ 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.
+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";
@@ -111,58 +92,40 @@ const result = await sandbox.execImage("ghcr.io/cofy-x/agent:latest", "tool run"
 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
 
 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 +136,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 +146,12 @@ 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.
+
+## Run Output Retention
+
+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.

package/dist/client/index.d.ts

@@ -4,11 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import * as grpc from "@grpc/grpc-js";
-import { NodeSandboxClient } from "../node/client.js";
+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,16 +26,14 @@ 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;
@@ -53,13 +50,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 +68,11 @@ 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>>;
+    createRun(options: CreateRunOptions): 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;
+    allocation(allocationId: string): AllocationClient;
     tunnelClient(): TunnelControlClient;
     tunnelTransport(): GatewayTransportOptions;
 }

package/dist/client/index.js

@@ -8,7 +8,7 @@ import { readFileSync } from "node:fs";
 import { loadAxernContext, loadAxernEnv, normalizeProxyMode } from "../config/index.js";
 import { 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 +18,6 @@ export class AxernClient {
     controlOptions;
     environmentControl;
     runControl;
-    serviceControl;
     tunnelControl;
     gatewayTransport;
     constructor(options) {
@@ -57,11 +56,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 +79,6 @@ export class AxernClient {
     close() {
         this.environmentControl.close();
         this.runControl.close();
-        this.serviceControl.close();
         this.tunnelControl.close();
     }
     async createEnvironment(options) {
@@ -118,17 +114,57 @@ export class AxernClient {
             throw mapRpcError(error, "delete environment");
         }
     }
-    async *watchRun(runId, afterVersion = 0) {
+    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 ?? "" },
+                    })),
+                    resources,
+                },
+                labels: options.labels ?? {},
+            });
+            return response.run;
+        }
+        catch (error) {
+            throw mapRpcError(error, "create run");
+        }
+    }
+    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 +180,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 +238,8 @@ export class AxernClient {
             retryDelayMs = Math.min(retryDelayMs * 2, 2_000);
         }
     }
-    async createService(options) {
-        const resources = buildResourceSpec(options);
-        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;
-        }
-        catch (error) {
-            throw mapRpcError(error, "create service");
-        }
-    }
-    async deleteService(serviceId) {
-        try {
-            await unary(this.serviceControl, "DeleteService", { service_id: required("serviceId", serviceId) });
-        }
-        catch (error) {
-            throw mapRpcError(error, "delete service");
-        }
-    }
-    async listServiceReplicas(serviceId) {
-        try {
-            const response = await unary(this.serviceControl, "ListServiceReplicas", {
-                service_id: required("serviceId", serviceId),
-                filter: { view: 2 },
-            });
-            return response.replicas ?? [];
-        }
-        catch (error) {
-            throw mapRpcError(error, "list service replicas");
-        }
-    }
-    nodeSandbox(allocationId) {
-        return new NodeSandboxClient({
+    allocation(allocationId) {
+        return new AllocationClient({
             allocationId: required("allocationId", allocationId),
             target: this.endpoint,
             credentials: this.credentials,
@@ -259,14 +253,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 +261,18 @@ 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 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;

package/dist/config/index.js

@@ -3,7 +3,6 @@ import { readFileSync } from "node:fs";
 export function loadAxernEnv(overrides = {}) {
     return {
         endpoint: overrides.endpoint ?? process.env.AXERN_ENDPOINT ?? "127.0.0.1:25000",
-        serviceUrl: overrides.serviceUrl ?? process.env.AXERN_SERVICE_URL,
         sshEndpoint: overrides.sshEndpoint ?? process.env.AXERN_SSH_ENDPOINT,
         sshIdentityFile: overrides.sshIdentityFile ?? process.env.AXERN_SSH_IDENTITY_FILE,
         tlsCaCert: overrides.tlsCaCert ?? process.env.AXERN_TLS_CA_CERT,
@@ -15,18 +14,17 @@ export function loadAxernEnv(overrides = {}) {
 }
 export function loadAxernContext(path, name = "") {
     const file = JSON.parse(readFileSync(path, "utf8"));
-    rejectUnknown(file, ["current_context", "contexts", "agent_profiles"], "config");
+    rejectUnknown(file, ["current_context", "contexts"], "config");
     const contextName = name || stringValue(file.current_context);
     if (!contextName)
         throw new Error("Axern context name is required");
     const contexts = objectValue(file.contexts, "contexts");
     const context = objectValue(contexts[contextName], `context ${JSON.stringify(contextName)}`);
-    rejectUnknown(context, ["endpoint", "service_url", "ssh_endpoint", "ssh_identity_file", "tls", "proxy_mode"], "context");
+    rejectUnknown(context, ["endpoint", "ssh_endpoint", "ssh_identity_file", "tls", "proxy_mode"], "context");
     const tls = objectValue(context.tls, "context.tls");
     rejectUnknown(tls, ["ca_cert", "cert", "key", "server_name"], "context.tls");
     const config = {
         endpoint: stringValue(context.endpoint),
-        serviceUrl: stringValue(context.service_url) || undefined,
         sshEndpoint: stringValue(context.ssh_endpoint) || undefined,
         sshIdentityFile: stringValue(context.ssh_identity_file) || undefined,
         tlsCaCert: stringValue(tls.ca_cert),

package/dist/generated/proto.js

@@ -16,7 +16,6 @@ const defaultProtoRootCandidates = [
 const protoFiles = [
     "axern/control/environment/v1/environment.proto",
     "axern/control/run/v1/run.proto",
-    "axern/control/service/v1/service.proto",
     "axern/control/tunnel/v1/tunnel.proto",
     "axern/node/sandbox/v1/node.proto",
     "axern/tunnel/v1/tunnel.proto",

package/dist/index.d.ts

@@ -4,18 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 export { AxernClient } from "./client/index.js";
-export type { AxernClientOptions, CreateEnvironmentOptions, CreateServiceOptions, } from "./client/index.js";
+export type { AxernClientOptions, CreateEnvironmentOptions, CreateRunOptions, } 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";
-export { NodeSandboxClient } from "./node/client.js";
-export type { NodeSandboxClientOptions } from "./node/client.js";
+export { AllocationClient } from "./node/client.js";
+export type { AllocationClientOptions } from "./node/client.js";
 export { SandboxProcess } from "./node/process.js";
 export type { ResourceQuantity } from "./resources.js";
 export { Sandbox } from "./sandbox/index.js";
 export type { SandboxMetadata, SandboxOptions, SandboxState } from "./sandbox/index.js";
 export { NetworkPolicy, cidrRule, portRange } from "./network-policy.js";
 export type { CIDRRule, PortRange, StrictNetworkPolicyOptions } from "./network-policy.js";
-export type { ChmodOptions, CapabilityDependencyStatus, CapabilityProviderStatus, CapabilityProviderSummary, CapabilityStatus, Command, ComputerUseDependencyStatus, ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseRegion, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, CopyOptions, DownloadArchiveOptions, DownloadDirOptions, ExecOptions, ExecResult, ImageExecOptions, ImageProcessMount, ImageProcessOptions, MkdirOptions, MoveOptions, NodeCallOptions, ProcessEvent, ProcessOptions, ProcessResult, RemoveOptions, SandboxFileInfo, SandboxFileKind, TouchOptions, TunnelConnectorOptions, TunnelMetadata, TunnelOptions, UploadArchiveOptions, UploadDirOptions, VolumeMount, WriteFileOptions, } from "./types.js";
-export { workspaceMount } from "./types.js";
+export type { ChmodOptions, CapabilityProviderDependencyStatus, CapabilityProviderStatus, CapabilityProviderSummary, CapabilityStatus, Command, ComputerUseDependencyStatus, ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseRegion, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, CopyOptions, DownloadArchiveOptions, DownloadDirOptions, ExecOptions, ExecResult, MkdirOptions, MoveOptions, NodeCallOptions, ProcessEvent, ProcessOptions, ProcessResult, RemoveOptions, SandboxFileInfo, SandboxFileKind, TouchOptions, TunnelConnectorOptions, TunnelMetadata, TunnelOptions, UploadArchiveOptions, UploadDirOptions, WriteFileOptions, } from "./types.js";
 export { AXERN_VERSION, platformName } from "./version.js";

package/dist/index.js

@@ -6,9 +6,8 @@
 export { AxernClient } from "./client/index.js";
 export { loadAxernContext, loadAxernEnv } from "./config/index.js";
 export { AxernError, AxernRpcError, isNotFound, isCancelled, isUnavailable, errorRetryable, isPermissionDenied, isTimeout, rpcCode, SandboxExecError, SandboxStateError, SandboxTimeoutError, SandboxValidationError, } from "./errors/index.js";
-export { NodeSandboxClient } from "./node/client.js";
+export { AllocationClient } from "./node/client.js";
 export { SandboxProcess } from "./node/process.js";
 export { Sandbox } from "./sandbox/index.js";
 export { NetworkPolicy, cidrRule, portRange } from "./network-policy.js";
-export { workspaceMount } from "./types.js";
 export { AXERN_VERSION, platformName } from "./version.js";

package/dist/node/attached_process.d.ts

@@ -3,8 +3,7 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-import type { Command, ImageProcessOptions, ProcessOptions } from "../types.js";
+import type { Command, ProcessOptions } from "../types.js";
 import { NodeClientContext } from "./context.js";
 import { SandboxProcess } from "./process.js";
 export declare function process(ctx: NodeClientContext, command: Command, options?: ProcessOptions): Promise<SandboxProcess>;
-export declare function processImage(ctx: NodeClientContext, image: string, command: Command, options?: ImageProcessOptions): Promise<SandboxProcess>;

package/dist/node/attached_process.js

@@ -3,12 +3,13 @@
  * Copyright 2026 cofy-x
  * SPDX-License-Identifier: Apache-2.0
  */
-import { mapRpcError } from "../errors/index.js";
+import { mapRpcError, SandboxValidationError } from "../errors/index.js";
 import { normalizeCommand } from "../validation.js";
-import { execSpec, imageProcessSpec } from "./exec.js";
+import { execSpec } from "./exec.js";
 import { SandboxProcess } from "./process.js";
 export async function process(ctx, command, options = {}) {
     const argv = normalizeCommand(command);
+    const initialSize = processInitialSize(options);
     const client = ctx.rpcClient();
     const call = client
         .Process();
@@ -20,6 +21,7 @@ export async function process(ctx, command, options = {}) {
     call.write({
         open: ctx.authRequest({
             spec: execSpec(argv, options),
+            ...(initialSize === undefined ? {} : { initial_size: initialSize }),
         }),
     });
     try {
@@ -31,30 +33,14 @@ export async function process(ctx, command, options = {}) {
         throw mapRpcError(error, "sandbox process", ctx.allocationId);
     }
 }
-export async function processImage(ctx, image, command, options = {}) {
-    if (image.trim() === "") {
-        throw new Error("image is required");
+function processInitialSize(options) {
+    const cols = options.initialCols ?? 0;
+    const rows = options.initialRows ?? 0;
+    if ((cols === 0) !== (rows === 0)) {
+        throw new SandboxValidationError("initialCols and initialRows must both be zero or both be positive");
     }
-    const argv = normalizeCommand(command);
-    const client = ctx.rpcClient();
-    const call = client
-        .ProcessImage();
-    const sandboxProcess = new SandboxProcess({
-        allocationId: ctx.allocationId,
-        call,
-        closeClient: () => client.close(),
-    });
-    call.write({
-        open: ctx.authRequest({
-            spec: imageProcessSpec(image, argv, options),
-        }),
-    });
-    try {
-        await sandboxProcess.waitReady();
-        return sandboxProcess;
-    }
-    catch (error) {
-        await sandboxProcess.close();
-        throw mapRpcError(error, "sandbox image process", ctx.allocationId);
+    if (cols < 0 || rows < 0 || !Number.isInteger(cols) || !Number.isInteger(rows)) {
+        throw new SandboxValidationError("initialCols and initialRows must be non-negative integers");
     }
+    return cols === 0 ? undefined : { cols, rows };
 }

package/dist/node/client.d.ts

@@ -4,22 +4,20 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type * as grpc from "@grpc/grpc-js";
-import type { ChmodOptions, CapabilityStatus, Command, ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, CopyOptions, DownloadArchiveOptions, ExecOptions, ExecResult, ImageExecOptions, ImageProcessOptions, MkdirOptions, MoveOptions, NodeCallOptions, ProcessOptions, RemoveOptions, SandboxFileInfo, TouchOptions, UploadArchiveOptions, WriteFileOptions } from "../types.js";
+import type { ChmodOptions, CapabilityStatus, Command, ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, CopyOptions, DownloadArchiveOptions, ExecOptions, ExecResult, MkdirOptions, MoveOptions, NodeCallOptions, ProcessOptions, RemoveOptions, SandboxFileInfo, TouchOptions, UploadArchiveOptions, WriteFileOptions } from "../types.js";
 import type { SandboxProcess } from "./process.js";
-export interface NodeSandboxClientOptions {
+export interface AllocationClientOptions {
     allocationId: string;
     target: string;
     credentials: grpc.ChannelCredentials;
     channelOptions?: grpc.ChannelOptions;
 }
-export declare class NodeSandboxClient {
+export declare class AllocationClient {
     readonly allocationId: string;
     private readonly ctx;
-    constructor(options: NodeSandboxClientOptions);
+    constructor(options: AllocationClientOptions);
     exec(command: Command, options?: ExecOptions): Promise<ExecResult>;
     process(command: Command, options?: ProcessOptions): Promise<SandboxProcess>;
-    execImage(image: string, command: Command, options?: ImageExecOptions): Promise<ExecResult>;
-    processImage(image: string, command: Command, options?: ImageProcessOptions): Promise<SandboxProcess>;
     capabilityStatus(options?: NodeCallOptions): Promise<CapabilityStatus>;
     computerUseStatus(options?: NodeCallOptions): Promise<ComputerUseStatus>;
     computerUseScreenshot(options?: ComputerUseScreenshotOptions): Promise<ComputerUseScreenshot>;