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

package/dist/tunnel/session.js

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import net from "node:net";
+import { debugFrame } from "./debug.js";
+const defaultDialTimeoutMs = 5_000;
+const defaultMaxStreams = 128;
+export class TunnelRelaySession {
+    call;
+    options;
+    streams = new Map();
+    constructor(call, options) {
+        this.call = call;
+        this.options = options;
+    }
+    handleFrame(frame) {
+        if ("ping" in frame) {
+            const ping = frame.ping;
+            this.send({ pong: { id: String(ping.id ?? "") } });
+            return;
+        }
+        if ("stream_open" in frame) {
+            this.openLocal(streamIdOf(frame.stream_open));
+            return;
+        }
+        if ("stream_data" in frame) {
+            const data = frame.stream_data;
+            this.writeLocal(streamIdOf(data), Buffer.from(data.data ?? []));
+            return;
+        }
+        if ("stream_close" in frame) {
+            this.closeLocal(streamIdOf(frame.stream_close));
+        }
+    }
+    send(frame) {
+        debugFrame("send", frame);
+        this.call.write(frame);
+    }
+    closeAll() {
+        for (const socket of this.streams.values()) {
+            socket.destroy();
+        }
+        this.streams.clear();
+    }
+    openLocal(streamId) {
+        if (this.streams.size >= (this.options.maxStreams ?? defaultMaxStreams)) {
+            this.sendClose(streamId, "max local streams reached");
+            return;
+        }
+        const socket = net.connect(this.options.upstreamTarget);
+        const timeout = this.options.dialTimeoutMs ?? defaultDialTimeoutMs;
+        this.streams.set(streamId, socket);
+        socket.setTimeout(timeout, () => {
+            this.sendClose(streamId, `dial timeout after ${timeout}ms`);
+            this.closeLocal(streamId);
+        });
+        socket.on("connect", () => {
+            socket.setTimeout(0);
+        });
+        socket.on("data", (data) => this.send({ stream_data: { stream_id: streamId, data } }));
+        socket.on("error", (error) => {
+            this.sendClose(streamId, error.message);
+            this.closeLocal(streamId);
+        });
+        socket.on("close", () => {
+            this.sendClose(streamId, "");
+            this.streams.delete(streamId);
+        });
+    }
+    writeLocal(streamId, data) {
+        const socket = this.streams.get(streamId);
+        if (socket === undefined) {
+            this.sendClose(streamId, "local stream is not open");
+            return;
+        }
+        socket.write(data);
+    }
+    closeLocal(streamId) {
+        const socket = this.streams.get(streamId);
+        this.streams.delete(streamId);
+        socket?.destroy();
+    }
+    sendClose(streamId, message) {
+        this.send({ stream_close: { stream_id: streamId, error: message } });
+    }
+}
+function streamIdOf(value) {
+    const streamId = String(value?.stream_id ?? "");
+    if (streamId === "") {
+        throw new Error("tunnel stream frame is missing stream_id");
+    }
+    return streamId;
+}

package/dist/tunnel/target.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type net from "node:net";
+export declare function parseTcpTarget(target: string): net.NetConnectOpts;

package/dist/tunnel/target.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SandboxValidationError } from "../errors/index.js";
+export function parseTcpTarget(target) {
+    if (target.startsWith("[")) {
+        const end = target.indexOf("]");
+        if (end === -1 || target[end + 1] !== ":") {
+            throw new SandboxValidationError(`invalid tunnel upstream target: ${target}`);
+        }
+        const port = Number(target.slice(end + 2));
+        if (!Number.isInteger(port) || port <= 0) {
+            throw new SandboxValidationError(`invalid tunnel upstream port: ${target}`);
+        }
+        return { host: target.slice(1, end), port };
+    }
+    const colon = target.lastIndexOf(":");
+    if (colon <= 0 || colon === target.length - 1) {
+        throw new SandboxValidationError(`invalid tunnel upstream target: ${target}`);
+    }
+    const port = Number(target.slice(colon + 1));
+    if (!Number.isInteger(port) || port <= 0) {
+        throw new SandboxValidationError(`invalid tunnel upstream port: ${target}`);
+    }
+    return { host: target.slice(0, colon), port };
+}

package/dist/tunnel/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface TunnelSession {
+    session_id?: string;
+    allocation_id?: string;
+    edge_target?: string;
+    client_edge_target?: string;
+    bound_addr?: string;
+    remote_port?: number;
+}
+export interface CreateTunnelSessionResult {
+    session: TunnelSession;
+    clientToken: string;
+}
+export interface TunnelRuntime {
+    sessionId: string;
+    clientToken: string;
+    boundAddr: string;
+    upstream: string;
+    proxyPort: number;
+    stop(): Promise<void>;
+}

package/dist/tunnel/types.js

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type Dict<T = unknown> = Record<string, T>;
+export type Command = string | readonly string[];
+export interface ExecOptions {
+    env?: Record<string, string>;
+    cwd?: string;
+    timeoutSeconds?: number;
+    user?: string;
+    tty?: boolean;
+    check?: boolean;
+    leaseTtlSeconds?: number;
+    rpcTimeoutMs?: number;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: Buffer;
+    stderr: Buffer;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    stdoutText(encoding?: BufferEncoding): string;
+    stderrText(encoding?: BufferEncoding): string;
+}
+export interface ImageProcessMount {
+    sandboxPath: string;
+    targetPath: string;
+    readonly?: boolean;
+    options?: readonly string[];
+}
+export interface VolumeMount {
+    name: string;
+    target: string;
+    readonly?: boolean;
+    options?: readonly string[];
+}
+export declare function workspaceMount(path?: string): ImageProcessMount;
+export interface ImageExecOptions extends ExecOptions {
+    mounts?: readonly ImageProcessMount[];
+}
+export type ProcessEvent = {
+    kind: "ready";
+} | {
+    kind: "stdout";
+    data: Buffer;
+} | {
+    kind: "stderr";
+    data: Buffer;
+} | {
+    kind: "exit";
+    exitCode: number;
+    message: string;
+};
+export interface ProcessOptions extends Omit<ExecOptions, "check"> {
+}
+export interface ImageProcessOptions extends ProcessOptions {
+    mounts?: readonly ImageProcessMount[];
+}
+export interface ProcessResult {
+    exitCode: number;
+    message: string;
+}
+export type SandboxFileKind = "file" | "directory" | "symlink" | "other" | "unspecified";
+export interface SandboxFileInfo {
+    path: string;
+    kind: SandboxFileKind;
+    size: number;
+    mode: number;
+    mtimeNs: number;
+}
+export interface WriteFileOptions {
+    createParents?: boolean;
+}
+export interface MkdirOptions {
+    parents?: boolean;
+}
+export interface RemoveOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+export interface CopyOptions {
+    recursive?: boolean;
+    overwrite?: boolean;
+}
+export interface MoveOptions {
+    overwrite?: boolean;
+}
+export interface ChmodOptions {
+    recursive?: boolean;
+}
+export interface TouchOptions {
+    create?: boolean;
+    mtimeNs?: number;
+}
+export interface UploadDirOptions {
+    createParents?: boolean;
+    overwrite?: boolean;
+    chunkSize?: number;
+    rpcTimeoutMs?: number;
+}
+export interface DownloadDirOptions {
+    overwrite?: boolean;
+    chunkSize?: number;
+    rpcTimeoutMs?: number;
+}
+export interface UploadArchiveOptions {
+    createParents?: boolean;
+    overwrite?: boolean;
+    leaseTtlSeconds?: number;
+    rpcTimeoutMs?: number;
+}
+export interface DownloadArchiveOptions {
+    leaseTtlSeconds?: number;
+    rpcTimeoutMs?: number;
+}
+export interface TunnelOptions {
+    upstream: string;
+    proxyPort?: number;
+    ttlSeconds?: number;
+    readyTimeoutMs?: number;
+    renewEveryMs?: number;
+    connector?: TunnelConnectorOptions;
+}
+export interface TunnelConnectorOptions {
+    pingIntervalMs?: number;
+    dialTimeoutMs?: number;
+    maxStreams?: number;
+}
+export interface TunnelMetadata {
+    sessionId: string;
+    boundAddr: string;
+    upstream: string;
+    proxyPort: number;
+}
+export interface CapabilityDependencyStatus {
+    name: string;
+    available: boolean;
+    reason: string;
+}
+export interface CapabilityProviderStatus {
+    name: string;
+    state: string;
+    available: boolean;
+    capabilities: string[];
+    backend: string;
+    reason: string;
+    dependencies: CapabilityDependencyStatus[];
+}
+export interface CapabilityProviderSummary {
+    total: number;
+    available: number;
+    degraded: number;
+    unavailable: number;
+}
+export interface CapabilityStatus {
+    ready: boolean;
+    capabilities: string[];
+    providers: CapabilityProviderStatus[];
+    providerSummary: CapabilityProviderSummary;
+}
+export interface NodeCallOptions {
+    rpcTimeoutMs?: number;
+}
+export interface ComputerUseDependencyStatus {
+    name: string;
+    available: boolean;
+    reason: string;
+}
+export interface ComputerUseStatus {
+    available: boolean;
+    display: string;
+    backend: string;
+    reason: string;
+    dependencies: ComputerUseDependencyStatus[];
+}
+export interface ComputerUseRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ComputerUseScreenshot {
+    data: Buffer;
+    contentType: string;
+}
+export interface ComputerUseScreenshotOptions {
+    showCursor?: boolean;
+    region?: ComputerUseRegion;
+    format?: string;
+    quality?: number;
+    scale?: number;
+    rpcTimeoutMs?: number;
+}
+export interface ComputerUseDisplay {
+    display: string;
+    backend: string;
+    width: number;
+    height: number;
+}
+export interface ComputerUseMouseOptions {
+    action?: string;
+    x?: number;
+    y?: number;
+    toX?: number;
+    toY?: number;
+    button?: string;
+    direction?: string;
+    amount?: number;
+    rpcTimeoutMs?: number;
+}
+export interface ComputerUseKeyboardOptions {
+    text?: string;
+    key?: string;
+    keys?: readonly string[];
+    delayMs?: number;
+    rpcTimeoutMs?: number;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function workspaceMount(path = "/workspace") {
+    return { sandboxPath: path, targetPath: path };
+}

package/dist/validation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Command } from "./types.js";
+export declare function required(name: string, value: string | undefined | null): string;
+export declare function nonEmptyPath(path: string): string;
+export declare function normalizeCommand(command: Command): string[];
+export declare function positiveNumber(name: string, value: number | undefined): number | undefined;

package/dist/validation.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { SandboxValidationError } from "./errors/index.js";
+export function required(name, value) {
+    if (value === undefined || value === null || value.length === 0) {
+        throw new SandboxValidationError(`${name} is required`);
+    }
+    return value;
+}
+export function nonEmptyPath(path) {
+    if (path.length === 0) {
+        throw new SandboxValidationError("path is required");
+    }
+    return path;
+}
+export function normalizeCommand(command) {
+    if (typeof command === "string") {
+        if (command.length === 0) {
+            throw new SandboxValidationError("command is required");
+        }
+        return ["/bin/sh", "-lc", command];
+    }
+    const argv = [...command];
+    if (argv.length === 0 || argv.some((part) => part.length === 0)) {
+        throw new SandboxValidationError("command argv must contain non-empty strings");
+    }
+    return argv;
+}
+export function positiveNumber(name, value) {
+    if (value !== undefined && value < 0) {
+        throw new SandboxValidationError(`${name} must be non-negative`);
+    }
+    return value;
+}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare const AXERN_VERSION = "0.2.0";
+export declare function platformName(): string;

package/dist/version.js

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2026 cofy-x
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export const AXERN_VERSION = "0.2.0-bootstrap.0";
+export function platformName() {
+    return "axern";
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@cofy-x/axern-sdk",
+  "version": "0.2.0-bootstrap.0",
+  "description": "TypeScript SDK for Axern agentic infrastructure and isolated sandboxes",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cofy-x/axern.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://axern.cofy-x.space/sdk/typescript/",
+  "bugs": {
+    "url": "https://github.com/cofy-x/axern/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/*.d.ts",
+    "dist/*.js",
+    "dist/client",
+    "dist/config",
+    "dist/errors",
+    "dist/generated",
+    "dist/node",
+    "dist/proto",
+    "dist/sandbox",
+    "dist/tunnel",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-proto.mjs",
+    "test": "tsx --test tests/*.test.ts",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "pack:dry-run": "node scripts/clean-dist.mjs && pnpm run build && npm pack --dry-run --json",
+    "smoke:local": "pnpm run build && node dist/smoke/local.js",
+    "smoke:tunnel": "pnpm run build && node dist/smoke/tunnel.js"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/proto-loader": "^0.8.0",
+    "tar-stream": "^3.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/tar-stream": "^3.1.4"
+  }
+}