@cofy-x/axern-sdk 0.2.0-bootstrap.0

package/dist/generated/proto.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as grpc from "@grpc/grpc-js";
+export declare function axernProtoRoot(): string;
+export declare function loadAxernPackage(): grpc.GrpcObject;
+export declare function serviceConstructor(pathParts: string[]): grpc.ServiceClientConstructor;
+export declare function unary<TRequest extends object, TResponse>(client: grpc.Client, method: string, request: TRequest, deadlineMs?: number): Promise<TResponse>;

package/dist/generated/proto.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const defaultProtoRootCandidates = [
+    path.resolve(__dirname, "../proto"),
+    path.resolve(__dirname, "../../../proto"),
+];
+const protoFiles = [
+    "axern/control/environment/v1/environment.proto",
+    "axern/control/gateway/v1/gateway.proto",
+    "axern/control/service/v1/service.proto",
+    "axern/control/tunnel/v1/tunnel.proto",
+    "axern/node/sandbox/v1/node.proto",
+    "axern/tunnel/v1/tunnel.proto",
+];
+let loadedPackage;
+export function axernProtoRoot() {
+    if (process.env.AXERN_PROTO_ROOT !== undefined && process.env.AXERN_PROTO_ROOT !== "") {
+        return process.env.AXERN_PROTO_ROOT;
+    }
+    const protoRoot = defaultProtoRootCandidates.find((candidate) => existsSync(path.join(candidate, "axern/control/environment/v1/environment.proto")));
+    if (protoRoot === undefined) {
+        throw new Error("AXERN_PROTO_ROOT is required because bundled proto files were not found");
+    }
+    return protoRoot;
+}
+export function loadAxernPackage() {
+    if (loadedPackage !== undefined) {
+        return loadedPackage;
+    }
+    const protoRoot = axernProtoRoot();
+    const definition = protoLoader.loadSync(protoFiles.map((file) => path.join(protoRoot, file)), {
+        includeDirs: [protoRoot],
+        keepCase: true,
+        longs: String,
+        enums: Number,
+        defaults: false,
+        oneofs: true,
+    });
+    loadedPackage = grpc.loadPackageDefinition(definition);
+    return loadedPackage;
+}
+export function serviceConstructor(pathParts) {
+    let current = loadAxernPackage();
+    for (const part of pathParts) {
+        current = current[part];
+        if (current === undefined) {
+            throw new Error(`missing proto service path: ${pathParts.join(".")}`);
+        }
+    }
+    return current;
+}
+export function unary(client, method, request, deadlineMs) {
+    return new Promise((resolve, reject) => {
+        const callback = (error, response) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve(response);
+            }
+        };
+        const options = deadlineMs === undefined ? undefined : { deadline: Date.now() + deadlineMs };
+        const fn = client[method];
+        if (options === undefined) {
+            fn.call(client, request, callback);
+        }
+        else {
+            fn.call(client, request, options, callback);
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { AxernClient } from "./client/index.js";
+export type { AxernClientOptions, CreateEnvironmentOptions, CreateServiceOptions, } 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 { 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 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 { AXERN_VERSION, platformName } from "./version.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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 { SandboxProcess } from "./node/process.js";
+export { Sandbox } from "./sandbox/index.js";
+export { workspaceMount } from "./types.js";
+export { AXERN_VERSION, platformName } from "./version.js";

package/dist/node/archive.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { DownloadArchiveOptions, UploadArchiveOptions } from "../types.js";
+import type { NodeClientContext } from "./context.js";
+export declare function uploadArchive(ctx: NodeClientContext, path: string, chunks: () => AsyncIterable<Buffer | Uint8Array>, options?: UploadArchiveOptions): Promise<void>;
+export declare function downloadArchive(ctx: NodeClientContext, path: string, options?: DownloadArchiveOptions): AsyncIterable<Buffer>;

package/dist/node/archive.js

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError } from "../errors/index.js";
+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({
+            path: nonEmptyPath(path),
+            format: 1,
+            create_parents: options.createParents ?? true,
+            overwrite: options.overwrite ?? true,
+            symlink_policy: 1,
+        }), chunks(), options.rpcTimeoutMs));
+    }
+    catch (error) {
+        throw mapRpcError(error, "sandbox upload archive", ctx.allocationId);
+    }
+}
+export async function* downloadArchive(ctx, path, options = {}) {
+    const client = ctx.rpcClient();
+    try {
+        const chunks = downloadArchiveStream(client, ctx.authRequest({
+            path: nonEmptyPath(path),
+            format: 1,
+            symlink_policy: 1,
+        }), options.rpcTimeoutMs);
+        for await (const chunk of chunks) {
+            yield chunk;
+        }
+    }
+    catch (error) {
+        throw mapRpcError(error, "sandbox download archive", ctx.allocationId);
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/node/attached_process.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Command, ImageProcessOptions, 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

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError } from "../errors/index.js";
+import { normalizeCommand } from "../validation.js";
+import { execSpec, imageProcessSpec } from "./exec.js";
+import { SandboxProcess } from "./process.js";
+export async function process(ctx, command, options = {}) {
+    const argv = normalizeCommand(command);
+    const client = ctx.rpcClient();
+    const call = client
+        .Process();
+    const sandboxProcess = new SandboxProcess({
+        allocationId: ctx.allocationId,
+        call,
+        closeClient: () => client.close(),
+    });
+    call.write({
+        open: ctx.authRequest({
+            spec: execSpec(argv, options),
+        }),
+    });
+    try {
+        await sandboxProcess.waitReady();
+        return sandboxProcess;
+    }
+    catch (error) {
+        await sandboxProcess.close();
+        throw mapRpcError(error, "sandbox process", ctx.allocationId);
+    }
+}
+export async function processImage(ctx, image, command, options = {}) {
+    if (image.trim() === "") {
+        throw new Error("image is required");
+    }
+    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);
+    }
+}

package/dist/node/capabilities.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { CapabilityStatus, NodeCallOptions } from "../types.js";
+import type { NodeClientContext } from "./context.js";
+export declare function capabilityStatus(ctx: NodeClientContext, options?: NodeCallOptions): Promise<CapabilityStatus>;

package/dist/node/capabilities.js

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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));
+        return {
+            ready: response.ready === true,
+            capabilities: strings(response.capabilities),
+            providers: records(response.providers).map((provider) => ({
+                name: String(provider.name ?? ""),
+                state: String(provider.state ?? ""),
+                available: provider.available === true,
+                capabilities: strings(provider.capabilities),
+                backend: String(provider.backend ?? ""),
+                reason: String(provider.reason ?? ""),
+                dependencies: records(provider.dependencies).map((dependency) => ({
+                    name: String(dependency.name ?? ""),
+                    available: dependency.available === true,
+                    reason: String(dependency.reason ?? ""),
+                })),
+            })),
+            providerSummary: providerSummary(response.provider_summary),
+        };
+    }
+    catch (error) {
+        throw mapRpcError(error, "sandbox capability status", ctx.allocationId);
+    }
+}
+function providerSummary(input) {
+    const summary = record(input);
+    return {
+        total: Number(summary.total ?? 0),
+        available: Number(summary.available ?? 0),
+        degraded: Number(summary.degraded ?? 0),
+        unavailable: Number(summary.unavailable ?? 0),
+    };
+}
+function strings(input) {
+    return Array.isArray(input) ? input.map(String) : [];
+}
+function records(input) {
+    return Array.isArray(input) ? input.map(record) : [];
+}
+function record(input) {
+    return typeof input === "object" && input !== null ? input : {};
+}

package/dist/node/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * 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 { SandboxProcess } from "./process.js";
+export interface NodeSandboxClientOptions {
+    allocationId: string;
+    target: string;
+    credentials: grpc.ChannelCredentials;
+    channelOptions?: grpc.ChannelOptions;
+}
+export declare class NodeSandboxClient {
+    readonly allocationId: string;
+    private readonly ctx;
+    constructor(options: NodeSandboxClientOptions);
+    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>;
+    computerUseDisplay(options?: NodeCallOptions): Promise<ComputerUseDisplay>;
+    computerUseMouse(options?: ComputerUseMouseOptions): Promise<void>;
+    computerUseKeyboard(options?: ComputerUseKeyboardOptions): Promise<void>;
+    stat(path: string): Promise<SandboxFileInfo>;
+    listDir(path: string): Promise<SandboxFileInfo[]>;
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<Buffer>;
+    readText(path: string, encoding?: BufferEncoding): Promise<string>;
+    writeFile(path: string, data: Buffer | Uint8Array | string, options?: WriteFileOptions): Promise<void>;
+    writeText(path: string, data: string, options?: WriteFileOptions): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    remove(path: string, options?: RemoveOptions): Promise<void>;
+    copy(srcPath: string, dstPath: string, options?: CopyOptions): Promise<void>;
+    move(srcPath: string, dstPath: string, options?: MoveOptions): Promise<void>;
+    chmod(path: string, mode: number, options?: ChmodOptions): Promise<void>;
+    touch(path: string, options?: TouchOptions): Promise<void>;
+    uploadArchive(path: string, chunks: () => AsyncIterable<Buffer | Uint8Array>, options?: UploadArchiveOptions): Promise<void>;
+    downloadArchive(path: string, options?: DownloadArchiveOptions): AsyncIterable<Buffer>;
+}

package/dist/node/client.js

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { uploadArchive, downloadArchive } from "./archive.js";
+import { capabilityStatus } from "./capabilities.js";
+import * as computerUse from "./computer_use.js";
+import { process as startProcess } from "./attached_process.js";
+import { processImage as startImageProcess } from "./attached_process.js";
+import { NodeClientContext } from "./context.js";
+import { exec, execImage } from "./exec.js";
+import * as files from "./files.js";
+export class NodeSandboxClient {
+    allocationId;
+    ctx;
+    constructor(options) {
+        this.allocationId = options.allocationId;
+        this.ctx = new NodeClientContext(options);
+    }
+    async exec(command, options = {}) {
+        return exec(this.ctx, command, options);
+    }
+    async process(command, options = {}) {
+        return startProcess(this.ctx, command, options);
+    }
+    async execImage(image, command, options = {}) {
+        return execImage(this.ctx, image, command, options);
+    }
+    async processImage(image, command, options = {}) {
+        return startImageProcess(this.ctx, image, command, options);
+    }
+    async capabilityStatus(options = {}) {
+        return capabilityStatus(this.ctx, options);
+    }
+    async computerUseStatus(options = {}) {
+        return computerUse.computerUseStatus(this.ctx, options);
+    }
+    async computerUseScreenshot(options = {}) {
+        return computerUse.computerUseScreenshot(this.ctx, options);
+    }
+    async computerUseDisplay(options = {}) {
+        return computerUse.computerUseDisplay(this.ctx, options);
+    }
+    async computerUseMouse(options = {}) {
+        return computerUse.computerUseMouse(this.ctx, options);
+    }
+    async computerUseKeyboard(options = {}) {
+        return computerUse.computerUseKeyboard(this.ctx, options);
+    }
+    async stat(path) {
+        return files.stat(this.ctx, path);
+    }
+    async listDir(path) {
+        return files.listDir(this.ctx, path);
+    }
+    async exists(path) {
+        return files.exists(this.ctx, path);
+    }
+    async readFile(path) {
+        return files.readFile(this.ctx, path);
+    }
+    async readText(path, encoding = "utf8") {
+        return (await this.readFile(path)).toString(encoding);
+    }
+    async writeFile(path, data, options = {}) {
+        return files.writeFile(this.ctx, path, data, options);
+    }
+    async writeText(path, data, options = {}) {
+        return this.writeFile(path, data, options);
+    }
+    async mkdir(path, options = {}) {
+        return files.mkdir(this.ctx, path, options);
+    }
+    async remove(path, options = {}) {
+        return files.remove(this.ctx, path, options);
+    }
+    async copy(srcPath, dstPath, options = {}) {
+        return files.copy(this.ctx, srcPath, dstPath, options);
+    }
+    async move(srcPath, dstPath, options = {}) {
+        return files.move(this.ctx, srcPath, dstPath, options);
+    }
+    async chmod(path, mode, options = {}) {
+        return files.chmod(this.ctx, path, mode, options);
+    }
+    async touch(path, options = {}) {
+        return files.touch(this.ctx, path, options);
+    }
+    async uploadArchive(path, chunks, options = {}) {
+        return uploadArchive(this.ctx, path, chunks, options);
+    }
+    downloadArchive(path, options = {}) {
+        return downloadArchive(this.ctx, path, options);
+    }
+}

package/dist/node/computer_use.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ComputerUseDisplay, ComputerUseKeyboardOptions, ComputerUseMouseOptions, ComputerUseScreenshot, ComputerUseScreenshotOptions, ComputerUseStatus, NodeCallOptions } from "../types.js";
+import type { NodeClientContext } from "./context.js";
+export declare function computerUseStatus(ctx: NodeClientContext, options?: NodeCallOptions): Promise<ComputerUseStatus>;
+export declare function computerUseScreenshot(ctx: NodeClientContext, options?: ComputerUseScreenshotOptions): Promise<ComputerUseScreenshot>;
+export declare function computerUseDisplay(ctx: NodeClientContext, options?: NodeCallOptions): Promise<ComputerUseDisplay>;
+export declare function computerUseMouse(ctx: NodeClientContext, options?: ComputerUseMouseOptions): Promise<void>;
+export declare function computerUseKeyboard(ctx: NodeClientContext, options?: ComputerUseKeyboardOptions): Promise<void>;

package/dist/node/computer_use.js

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { mapRpcError } from "../errors/index.js";
+import { unary } from "../generated/proto.js";
+export async function computerUseStatus(ctx, options = {}) {
+    const response = await computerUseUnary(ctx, "ComputerUseStatus", {}, options.rpcTimeoutMs);
+    return {
+        available: response.available === true,
+        display: String(response.display ?? ""),
+        backend: String(response.backend ?? ""),
+        reason: String(response.reason ?? ""),
+        dependencies: records(response.dependencies).map((dependency) => ({
+            name: String(dependency.name ?? ""),
+            available: dependency.available === true,
+            reason: String(dependency.reason ?? ""),
+        })),
+    };
+}
+export async function computerUseScreenshot(ctx, options = {}) {
+    const response = await computerUseUnary(ctx, "ComputerUseScreenshot", {
+        show_cursor: options.showCursor ?? false,
+        region: options.region === undefined ? undefined : {
+            x: options.region.x,
+            y: options.region.y,
+            width: options.region.width,
+            height: options.region.height,
+        },
+        format: options.format ?? "",
+        quality: options.quality ?? 0,
+        scale: options.scale ?? 0,
+    }, options.rpcTimeoutMs);
+    return {
+        data: Buffer.from(response.data ?? []),
+        contentType: String(response.content_type ?? ""),
+    };
+}
+export async function computerUseDisplay(ctx, options = {}) {
+    const response = await computerUseUnary(ctx, "ComputerUseDisplay", {}, options.rpcTimeoutMs);
+    return {
+        display: String(response.display ?? ""),
+        backend: String(response.backend ?? ""),
+        width: Number(response.width ?? 0),
+        height: Number(response.height ?? 0),
+    };
+}
+export async function computerUseMouse(ctx, options = {}) {
+    await computerUseUnary(ctx, "ComputerUseMouse", {
+        action: options.action ?? "click",
+        x: options.x ?? 0,
+        y: options.y ?? 0,
+        to_x: options.toX ?? 0,
+        to_y: options.toY ?? 0,
+        button: options.button ?? "",
+        direction: options.direction ?? "",
+        amount: options.amount ?? 0,
+    }, options.rpcTimeoutMs);
+}
+export async function computerUseKeyboard(ctx, options = {}) {
+    await computerUseUnary(ctx, "ComputerUseKeyboard", {
+        text: options.text ?? "",
+        key: options.key ?? "",
+        keys: options.keys ?? [],
+        delay_ms: options.delayMs ?? 0,
+    }, options.rpcTimeoutMs);
+}
+async function computerUseUnary(ctx, method, payload, rpcTimeoutMs) {
+    try {
+        return await ctx.withAuthRetry(60, (client) => unary(client, method, ctx.authRequest(payload), rpcTimeoutMs));
+    }
+    catch (error) {
+        throw mapRpcError(error, `sandbox ${method}`, ctx.allocationId);
+    }
+}
+function records(input) {
+    return Array.isArray(input)
+        ? input.map((item) => typeof item === "object" && item !== null ? item : {})
+        : [];
+}

package/dist/node/context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as grpc from "@grpc/grpc-js";
+export interface NodeClientContextOptions {
+    allocationId: string;
+    target: string;
+    credentials: grpc.ChannelCredentials;
+    channelOptions?: grpc.ChannelOptions;
+}
+export declare class NodeClientContext {
+    readonly allocationId: string;
+    private readonly target;
+    private readonly credentials;
+    private readonly channelOptions;
+    constructor(options: NodeClientContextOptions);
+    withAuthRetry<T>(_leaseTtlSeconds: number, operation: (client: grpc.Client) => Promise<T>): Promise<T>;
+    rpcClient(): grpc.Client;
+    authRequest(payload: Record<string, unknown>): Record<string, unknown>;
+}

package/dist/node/context.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { serviceConstructor } from "../generated/proto.js";
+export class NodeClientContext {
+    allocationId;
+    target;
+    credentials;
+    channelOptions;
+    constructor(options) {
+        this.allocationId = options.allocationId;
+        this.target = options.target;
+        this.credentials = options.credentials;
+        this.channelOptions = options.channelOptions ?? {};
+    }
+    async withAuthRetry(_leaseTtlSeconds, operation) {
+        const client = this.rpcClient();
+        try {
+            return await operation(client);
+        }
+        finally {
+            client.close();
+        }
+    }
+    rpcClient() {
+        const NodeSandbox = serviceConstructor(["axern", "node", "sandbox", "v1", "NodeSandbox"]);
+        return new NodeSandbox(this.target, this.credentials, this.channelOptions);
+    }
+    authRequest(payload) {
+        return {
+            allocation_id: this.allocationId,
+            ...payload,
+        };
+    }
+}

package/dist/node/exec.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Command, ExecOptions, ExecResult, ImageExecOptions, ImageProcessOptions, ProcessOptions } from "../types.js";
+import type { NodeClientContext } from "./context.js";
+export declare function exec(ctx: NodeClientContext, command: Command, options?: ExecOptions): Promise<ExecResult>;
+export declare function execImage(ctx: NodeClientContext, image: string, command: Command, options?: ImageExecOptions): Promise<ExecResult>;
+export declare function execSpec(argv: string[], options: ExecOptions | ProcessOptions): Record<string, unknown>;
+export declare function imageProcessSpec(image: string, argv: string[], options: ImageExecOptions | ImageProcessOptions): Record<string, unknown>;
+export declare function execResult(response: Record<string, unknown>): ExecResult;