@arker-ai/sdk 0.5.1 → 0.6.2

package/README.md

@@ -29,6 +29,27 @@ const data = await vm.sync("/tmp/data.txt"); // read -> Uint8Array
 await vm.delete();
 ```
 
+## Interactive PTY
+
+`arker shell` opens a native PTY session over WebSocket. It does not use SSH and
+does not call `/runs` for each line:
+
+```bash
+arker shell vm_123
+arker shell vm_123 --session-id sess_123
+```
+
+The SDK exposes the same transport:
+
+```ts
+const pty = await vm.connectPty({ cols: 120, rows: 32 });
+pty.onData((chunk) => process.stdout.write(chunk));
+await pty.ready;
+pty.send("echo hello\n");
+pty.resize(100, 30);
+pty.close(); // detach; the session is not deleted
+```
+
 ## Core API
 
 ```ts
@@ -41,6 +62,7 @@ await ar.fork({ sourceVmName, sourceOrgId, name?, durable? });
 await ar.listVms({ state? });
 ar.vm(vmId);                                  // bare handle
 await ar.vm(vmId).run(command, options?);
+await ar.vm(vmId).connectPty({ sessionId?, cols?, rows?, command?, persist? });
 await ar.vm(vmId).resize({ vcpu_count, memory_mib });
 await ar.vm(vmId).delete();
 
@@ -61,6 +83,42 @@ await vm.deleteSync(syncId);
 
 `apiKey` falls back to `ARKER_API_KEY`; `region` to `ARKER_REGION`. Pass `baseUrl` for dev targets. Configure retries with `retry: { attempts, baseDelayMs, maxDelayMs }`, or `retry: false` to disable.
 
+## Interactive terminal (PTY)
+
+Open a real pseudo-terminal in a VM and drive it interactively — stream raw
+terminal bytes out, send keystrokes in (incl. control chars like Ctrl-C),
+resize, and kill. `isatty()` is true inside, so an interactive shell, `vim`,
+`htop`, a language REPL, and `claude` all work. Transport is a TLS WebSocket;
+a key can only attach to its own org's VMs.
+
+```ts
+const vm = await ar.fork("ubuntu-full");
+
+const pty = await vm.createPty({
+  cols: 80,
+  rows: 24,
+  // command defaults to the login shell. It is a single executable path —
+  // the guest does not shell-split, so launch a shell and `sendInput` it.
+  onData: (bytes) => process.stdout.write(bytes), // raw output (ANSI/colors)
+});
+
+await pty.sendInput(new TextEncoder().encode("ls -la\n"));
+await pty.resize({ cols: 120, rows: 40 });        // a full-screen app reflows
+await pty.kill();                                  // tears down the shell
+```
+
+Wire it into `xterm.js` in a browser (`term.onData → pty.sendInput`,
+`pty onData → term.write`, `term.onResize → pty.resize`), or pipe it to a local
+TTY in a script. Node needs the optional `ws` package (installed by default).
+
+The CLI exposes the same thing — `arker pty <vm>` (and `arker shell` on a TTY)
+drop you into a live terminal you can run `claude` in:
+
+```bash
+arker pty <vm_id>                 # login shell in a fresh/!existing VM
+arker pty --command /usr/bin/htop # launch a program directly
+```
+
 ## Durability
 
 For long-running or non-idempotent work, fork with `durable: true` and pass an idempotency key when retrying a run:
@@ -72,6 +130,102 @@ await vm.run("python3 train.py", { background: true, idempotencyKey: crypto.rand
 
 If the host fails mid-run, the run resumes on a healthy host with the VM's filesystem state preserved. Backends without durability return `ArkerError` code `unsupported_operation`.
 
+## Compatibility imports
+
+The SDK includes limited compatibility layers for common Daytona, E2B, and Modal sandbox workflows. These entrypoints keep the original SDK-shaped calls, route through ComputeSDK, use Arker as the first provider, and fall back to the original provider when resolving an existing non-Arker sandbox ID.
+
+For the supported surface below, migration is a one-line import change:
+
+| SDK | Replace | With |
+| --- | --- | --- |
+| Daytona | `import { Daytona } from "@daytonaio/sdk";` | `import { Daytona } from "@arker-ai/sdk/daytona";` |
+| E2B | `import { Sandbox } from "e2b";` | `import { Sandbox } from "@arker-ai/sdk/e2b";` |
+| Modal | `import { ModalClient } from "modal";` | `import { ModalClient } from "@arker-ai/sdk/modal";` |
+
+### Daytona
+
+```ts
+import { Daytona } from "@arker-ai/sdk/daytona";
+
+const daytona = new Daytona({ apiKey: process.env.DAYTONA_API_KEY });
+const sandbox = await daytona.create();
+const result = await sandbox.process.exec("echo hello");
+
+console.log(result.result);
+await daytona.delete(sandbox);
+```
+
+Supported Daytona surface:
+
+- `new Daytona({ apiKey?, arker? })`
+- `daytona.create()`
+- `daytona.get(id)`
+- `daytona.delete(idOrSandbox)`
+- `sandbox.id`
+- `sandbox.process.exec(command)`
+- `sandbox.process.executeCommand(command)`
+- `sandbox.delete()`
+
+### E2B
+
+```ts
+import { Sandbox } from "@arker-ai/sdk/e2b";
+
+const sandbox = await Sandbox.create();
+const result = await sandbox.commands.run("echo hello");
+
+console.log(result.stdout);
+await sandbox.kill();
+```
+
+Supported E2B surface:
+
+- `Sandbox.create()`
+- `Sandbox.create(templateId, { timeoutMs? })`
+- `Sandbox.connect(id)`
+- `sandbox.sandboxId`
+- `sandbox.commands.run(command)`
+- `sandbox.files.read/write/makeDir/list/exists/remove`
+- `sandbox.kill()`
+
+### Modal
+
+```ts
+import { ModalClient } from "@arker-ai/sdk/modal";
+
+const client = new ModalClient({
+  tokenId: process.env.MODAL_TOKEN_ID,
+  tokenSecret: process.env.MODAL_TOKEN_SECRET,
+});
+const sandbox = await client.sandboxes.create();
+const proc = await sandbox.exec(["sh", "-c", "echo hello"]);
+
+console.log(await proc.stdout.readText());
+await sandbox.terminate();
+```
+
+Supported Modal surface:
+
+- `new ModalClient({ tokenId?, tokenSecret?, arker? })`
+- `client.sandboxes.create()`
+- `client.sandboxes.fromId(id)`
+- `sandbox.sandboxId`
+- `sandbox.exec(commandOrArgv, { workdir?, env?, timeoutMs?, stdout?: "pipe", stderr?: "pipe", mode?: "text" })`
+- `process.stdout.readText()`
+- `process.stderr.readText()`
+- `process.wait()`
+- `sandbox.terminate()`
+
+Unsupported provider-specific methods and options throw explicit errors instead of being silently ignored. Arker credentials come from `ARKER_API_KEY` and optional `ARKER_REGION` / `ARKER_BASE_URL`; original provider credentials are only used for fallback.
+
+Compatibility test commands:
+
+```bash
+npm run test:compat
+ARKER_API_KEY=... npm run test:compat-live
+ARKER_API_KEY=... DAYTONA_API_KEY=... E2B_API_KEY=... MODAL_TOKEN_ID=... MODAL_TOKEN_SECRET=... npm run test:compat-fallback-live
+```
+
 ## License
 
 Apache-2.0

package/dist/arker-provider-BNIL8NdM.d.ts

@@ -0,0 +1,7 @@
+import { ArkerOptions } from './index.js';
+
+interface ArkerComputeProviderConfig extends ArkerOptions {
+    source?: string;
+}
+
+export type { ArkerComputeProviderConfig as A };

package/dist/arker-provider-DwUib5ZW.d.cts

@@ -0,0 +1,7 @@
+import { ArkerOptions } from './index.cjs';
+
+interface ArkerComputeProviderConfig extends ArkerOptions {
+    source?: string;
+}
+
+export type { ArkerComputeProviderConfig as A };

package/dist/chunk-35IEV6BU.js

@@ -0,0 +1,286 @@
+import {
+  Arker,
+  ArkerError
+} from "./chunk-7BHPVQNG.js";
+
+// src/compat/common.ts
+function shouldGuardNested(value) {
+  return !!value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+}
+function guardUnsupported(instance, shimName) {
+  const passthrough = /* @__PURE__ */ new Set([
+    "then",
+    "catch",
+    "finally",
+    "constructor",
+    "toJSON",
+    "toString",
+    "valueOf",
+    Symbol.toStringTag
+  ]);
+  const supported = /* @__PURE__ */ new Set();
+  for (let current = instance; current && current !== Object.prototype; current = Object.getPrototypeOf(current)) {
+    for (const key of Reflect.ownKeys(current)) supported.add(key);
+  }
+  return new Proxy(instance, {
+    get(target, prop) {
+      if (typeof prop === "symbol" || passthrough.has(prop) || supported.has(prop)) {
+        const value = Reflect.get(target, prop, target);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return shouldGuardNested(value) ? guardUnsupported(value, shimName) : value;
+      }
+      throw new Error(
+        `'${String(prop)}' is not supported by the Arker compatibility layer for ${shimName}. The compatibility layer covers create/connect/get, command execution, and core filesystem operations. Use the native ${shimName} SDK directly for the full API.`
+      );
+    }
+  });
+}
+function isPlainRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function formatKeys(keys) {
+  return keys.map((key) => `'${key}'`).join(", ");
+}
+function assertNoUnsupportedArgs(args, shimName, methodName) {
+  if (args.length === 0) return;
+  throw new Error(
+    `${methodName} received unsupported positional argument(s) in the Arker compatibility layer for ${shimName}. Those values would be ignored, so this layer fails fast. Use the native ${shimName} SDK for app/image/provider-specific options.`
+  );
+}
+function assertSupportedObjectKeys(value, supportedKeys, shimName, methodName) {
+  if (value === void 0) return;
+  if (!isPlainRecord(value)) {
+    throw new Error(
+      `${methodName} only accepts an options object in the Arker compatibility layer for ${shimName}. Use the native ${shimName} SDK for unsupported call signatures.`
+    );
+  }
+  const supported = new Set(supportedKeys);
+  const unsupported = Object.keys(value).filter((key) => !supported.has(key));
+  if (unsupported.length > 0) {
+    throw new Error(
+      `${methodName} received unsupported option(s) ${formatKeys(unsupported)} in the Arker compatibility layer for ${shimName}. Those options would be ignored, so this layer fails fast. Supported option(s): ${supportedKeys.length > 0 ? formatKeys([...supportedKeys]) : "(none)"}.`
+    );
+  }
+}
+function resolveTimeout(opts) {
+  if (opts?.timeout !== void 0 && opts.timeoutMs !== void 0 && opts.timeout !== opts.timeoutMs) {
+    throw new Error("Received both 'timeout' and 'timeoutMs' with different values. Use one timeout value.");
+  }
+  return opts?.timeoutMs ?? opts?.timeout;
+}
+function isStringRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function shellQuote(value) {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function commandName(command) {
+  return command.split("/").pop() || command;
+}
+function argvToCommand(cmd) {
+  if (typeof cmd === "string") return cmd;
+  const executable = commandName(cmd[0] ?? "");
+  if ((executable === "sh" || executable === "bash") && cmd.length >= 3 && (cmd[1] === "-c" || cmd[1] === "-lc")) {
+    return cmd[2];
+  }
+  return cmd.map(shellQuote).join(" ");
+}
+function emitFinalOutput(result, options) {
+  if (result.stdout && options?.onStdout) options.onStdout(result.stdout);
+  if (result.stderr && options?.onStderr) options.onStderr(result.stderr);
+}
+
+// src/compat/runtime.ts
+import { compute } from "computesdk";
+
+// src/compat/arker-provider.ts
+var DEFAULT_REGION = "aws-us-east-1";
+var DEFAULT_SOURCE = "ubuntu-full";
+function env(key) {
+  const value = globalThis.process?.env?.[key];
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+}
+function makeClient(config = {}) {
+  const endpointConfigured = config.baseUrl || config.region || env("ARKER_BASE_URL") || env("ARKER_REGION");
+  return new Arker({
+    ...config,
+    region: config.region ?? (endpointConfigured ? void 0 : DEFAULT_REGION)
+  });
+}
+function decode(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+function toFileEntries(stdout) {
+  const entries = [];
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const parts = line.split("	");
+    if (parts.length < 4) continue;
+    const [type, size, mtime, ...nameParts] = parts;
+    entries.push({
+      name: nameParts.join("	"),
+      type: type === "d" ? "directory" : "file",
+      size: Number(size) || 0,
+      modified: new Date((Number(mtime) || 0) * 1e3)
+    });
+  }
+  return entries;
+}
+var ArkerComputeSandbox = class {
+  constructor(vm, destroyVm) {
+    this.vm = vm;
+    this.destroyVm = destroyVm;
+    this.sandboxId = vm.id;
+    this.filesystem = {
+      readFile: async (path) => decode(await this.vm.sync(path)),
+      writeFile: async (path, content) => {
+        await this.vm.sync(path, content);
+      },
+      mkdir: async (path) => {
+        const result = await this.runCommand(`mkdir -p ${shellQuote(path)}`);
+        if (result.exitCode !== 0) throw new Error(`Arker mkdir failed for ${path}: ${result.stderr || `exit ${result.exitCode}`}`);
+      },
+      readdir: async (path) => {
+        const p = shellQuote(path);
+        const script = `cd ${p} 2>/dev/null || exit 3; for e in * .*; do [ "$e" = "." ] && continue; [ "$e" = ".." ] && continue; [ -e "$e" ] || continue; if [ -d "$e" ]; then t=d; else t=f; fi; s=$(stat -c %s "$e" 2>/dev/null || echo 0); m=$(stat -c %Y "$e" 2>/dev/null || echo 0); printf '%s\\t%s\\t%s\\t%s\\n' "$t" "$s" "$m" "$e"; done`;
+        const result = await this.runCommand(script);
+        if (result.exitCode !== 0) throw new Error(`Arker readdir failed for ${path}: ${result.stderr || `exit ${result.exitCode}`}`);
+        return toFileEntries(result.stdout);
+      },
+      exists: async (path) => {
+        const result = await this.runCommand(`test -e ${shellQuote(path)}`);
+        return result.exitCode === 0;
+      },
+      remove: async (path) => {
+        const result = await this.runCommand(`rm -rf ${shellQuote(path)}`);
+        if (result.exitCode !== 0) throw new Error(`Arker remove failed for ${path}: ${result.stderr || `exit ${result.exitCode}`}`);
+      }
+    };
+  }
+  vm;
+  destroyVm;
+  sandboxId;
+  provider = "arker";
+  filesystem;
+  getInstance() {
+    return this.vm;
+  }
+  async runCommand(command, options) {
+    const startTime = Date.now();
+    let fullCommand = command;
+    if (options?.env && Object.keys(options.env).length > 0) {
+      const envPrefix = Object.entries(options.env).map(([key, value]) => `${key}=${shellQuote(String(value))}`).join(" ");
+      fullCommand = `${envPrefix} ${fullCommand}`;
+    }
+    if (options?.cwd) fullCommand = `cd ${shellQuote(options.cwd)} && ${fullCommand}`;
+    if (options?.background) fullCommand = `nohup sh -lc ${shellQuote(fullCommand)} > /dev/null 2>&1 &`;
+    const runOptions = {};
+    if (options?.timeout) runOptions.timeout = options.timeout;
+    const result = await this.vm.run(fullCommand, runOptions);
+    if (result.type !== "completed") {
+      throw new Error(`Arker run did not complete synchronously (type=${result.type}). runCommand requires a foreground command.`);
+    }
+    const commandResult = {
+      stdout: decode(result.stdout),
+      stderr: decode(result.stderr),
+      exitCode: result.exitCode,
+      durationMs: Date.now() - startTime
+    };
+    emitFinalOutput(commandResult, options);
+    return commandResult;
+  }
+  async getInfo() {
+    return {
+      id: this.sandboxId,
+      provider: "arker",
+      status: "running",
+      createdAt: this.vm.created_at ? new Date(this.vm.created_at) : /* @__PURE__ */ new Date(),
+      timeout: 0,
+      metadata: {
+        name: this.vm.name,
+        region: this.vm.region,
+        provider: this.vm.provider
+      }
+    };
+  }
+  async getUrl(_options) {
+    throw new ArkerError(
+      "unsupported_operation",
+      "getUrl is not supported: the Arker VM API does not expose tunnel URLs",
+      422
+    );
+  }
+  async destroy() {
+    await this.destroyVm(this.sandboxId);
+  }
+};
+function createArkerComputeProvider(config = {}) {
+  async function destroy(sandboxId) {
+    const client = makeClient(config);
+    try {
+      await client.vm(sandboxId).delete();
+    } catch (error) {
+      if (error instanceof ArkerError && error.status === 404) return;
+      throw error;
+    }
+  }
+  function wrap(vm) {
+    return new ArkerComputeSandbox(vm, destroy);
+  }
+  return {
+    name: "arker",
+    sandbox: {
+      create: async (options) => {
+        const client = makeClient(config);
+        const source = options?.templateId || options?.snapshotId || config.source || env("ARKER_SOURCE") || DEFAULT_SOURCE;
+        const forkRequest = {};
+        if (options?.name) forkRequest.name = options.name;
+        const vm = await client.fork(source, forkRequest);
+        return wrap(vm);
+      },
+      getById: async (sandboxId) => {
+        const client = makeClient(config);
+        try {
+          return wrap(await client.getVm(sandboxId));
+        } catch (error) {
+          if (error instanceof ArkerError && error.status === 404) return null;
+          throw error;
+        }
+      },
+      list: async () => {
+        const client = makeClient(config);
+        const { vms } = await client.listVms();
+        return (vms ?? []).map(wrap);
+      },
+      destroy
+    }
+  };
+}
+
+// src/compat/runtime.ts
+var computeFactory = compute;
+function createCompatSdk(options) {
+  return computeFactory({
+    providers: [
+      createArkerComputeProvider(options.arker),
+      options.fallbackProvider
+    ],
+    providerStrategy: "priority",
+    fallbackOnError: true
+  });
+}
+
+export {
+  guardUnsupported,
+  assertNoUnsupportedArgs,
+  assertSupportedObjectKeys,
+  resolveTimeout,
+  isStringRecord,
+  argvToCommand,
+  createCompatSdk
+};