@arker-ai/sdk 0.5.1 → 0.6.2

package/dist/cli.cjs

@@ -25,9 +25,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/cli.ts
 var import_node_fs = require("fs");
+var import_node_child_process = require("child_process");
 var import_node_os = require("os");
 var import_node_path = require("path");
-var readline = __toESM(require("readline/promises"), 1);
 var import_node_process = require("process");
 
 // src/index.ts
@@ -153,6 +153,12 @@ var Arker = class {
       );
     }
     const sourceOrgId = src.sourceOrgId ?? (src.sourceVmName !== void 0 && GOLDEN_NAMES.has(src.sourceVmName) ? ARKER_ORG_ID : void 0);
+    const legacy = src;
+    const resources = src.resources ?? (legacy.vcpu_count != null || legacy.memory_mib != null || legacy.disk_mib != null ? {
+      vcpu: legacy.vcpu_count ?? null,
+      memory_mib: legacy.memory_mib ?? null,
+      disk_mib: legacy.disk_mib ?? null
+    } : null);
     const body = {
       source_vm_id: src.sourceVmId ?? null,
       source_vm_name: src.sourceVmName ?? null,
@@ -160,12 +166,10 @@ var Arker = class {
       name: src.name ?? null,
       public: src.public ?? null,
       network: src.network ?? null,
+      egress: src.egress ?? null,
       disk: src.disk ?? true,
-      vcpu_count: src.vcpu_count ?? null,
-      memory_mib: src.memory_mib ?? null,
-      max_memory_mib: src.max_memory_mib ?? null,
-      disk_mib: src.disk_mib ?? null,
-      durable: src.durable ?? null
+      durable: src.durable ?? null,
+      resources
     };
     const useBurst = sourceOrgId === ARKER_ORG_ID && src.sourceVmName !== void 0 && isBurstRef(src.sourceVmName);
     const baseUrl = useBurst && this.burstBaseUrl ? this.burstBaseUrl : this.baseUrl;
@@ -196,6 +200,33 @@ var Arker = class {
     });
     return { vms, nextCursor: resp.next_cursor ?? null };
   }
+  /**
+   * List run activity visible to the authenticated caller across VMs,
+   * providers, and regions. Admin call — routed through the control plane.
+   */
+  async listRuns(opts = {}) {
+    return this._request("GET", buildQuery("/v1/runs", {
+      since: opts.since,
+      until: opts.until,
+      vm: opts.vm,
+      vms: opts.vmIds && opts.vmIds.length > 0 ? opts.vmIds.join(",") : void 0,
+      region: opts.region,
+      provider: opts.provider,
+      source: opts.source,
+      search: opts.search,
+      limit: opts.limit,
+      offset: opts.offset,
+      lite: opts.lite === void 0 ? void 0 : opts.lite,
+      runtime: opts.runtime,
+      endpoint: opts.endpoint,
+      actions: opts.actions && opts.actions.length > 0 ? opts.actions.join(",") : void 0,
+      status: opts.status && opts.status.length > 0 ? opts.status.join(",") : void 0,
+      status_min: opts.statusMin,
+      status_max: opts.statusMax,
+      sort: opts.sort,
+      dir: opts.dir
+    }), void 0, this.controlBaseUrl);
+  }
   /** Compute call — goes direct to the backend hosting this VM (no
    * control-plane hop). Returns a fully-populated VM handle. */
   async getVm(vmId) {
@@ -285,6 +316,10 @@ var Arker = class {
     return retryDelay(this.retry, attempt);
   }
   /** @internal */
+  _authHeaders() {
+    return { authorization: `Bearer ${this.apiKey}` };
+  }
+  /** @internal */
   _baseUrlFor(ref) {
     if (isBurstRef(ref) && this.burstBaseUrl) return this.burstBaseUrl;
     return this.baseUrl;
@@ -310,12 +345,15 @@ var VM = class _VM {
   vcpu_count;
   memory_mib;
   disk_mib;
+  network;
+  max_vcpus;
+  max_memory_mib;
+  min_memory_mib;
   started_at;
   root_source_vm_id;
   root_source_vm_name;
   worker_id;
   sessions;
-  tunnels;
   constructor(client, vmId, baseUrl = client._baseUrlFor(vmId), data) {
     this._client = client;
     this.id = vmId;
@@ -438,8 +476,25 @@ var VM = class _VM {
     }
     throw new ArkerError(lastError?.code ?? "internal", lastError?.message ?? "write failed", 200);
   }
+  /**
+   * Update this VM's resource allocation and/or network settings via
+   * `PATCH /v1/vms/{id}`. Returns the updated `Vm`.
+   *
+   * Accepts either a `PatchVmRequest` (`{ resources, network }`) or, for
+   * convenience, flat resource fields (`{ vcpu, memory_mib, disk_mib }`)
+   * which are folded into `resources`.
+   */
   async resize(request) {
-    return this._client._request("POST", `${vmPath(this.id)}/resize`, request, this.baseUrl);
+    const r = request;
+    const body = r.resources !== void 0 || r.vcpu === void 0 && r.memory_mib === void 0 && r.disk_mib === void 0 ? { resources: r.resources ?? null, network: r.network ?? null } : {
+      resources: {
+        vcpu: r.vcpu ?? null,
+        memory_mib: r.memory_mib ?? null,
+        disk_mib: r.disk_mib ?? null
+      },
+      network: r.network ?? null
+    };
+    return this._client._request("PATCH", vmPath(this.id), body, this.baseUrl);
   }
   async delete() {
     return this._client._request("DELETE", vmPath(this.id), void 0, this.baseUrl);
@@ -495,19 +550,30 @@ var VM = class _VM {
   async deleteSession(sessionId) {
     return this._client._request("DELETE", `${vmPath(this.id)}/sessions/${pathSegment(sessionId)}`, void 0, this.baseUrl);
   }
-  // ── Tunnels: opened as a side effect of fork/run, addressed by port ─
-  async listTunnels(opts = {}) {
-    return this._client._request("GET", buildQuery(`${vmPath(this.id)}/tunnels`, {
-      cursor: opts.cursor,
-      limit: opts.limit,
-      state: opts.state
-    }), void 0, this.baseUrl);
-  }
-  async getTunnel(port) {
-    return this._client._request("GET", `${vmPath(this.id)}/tunnels/${port}`, void 0, this.baseUrl);
-  }
-  async deleteTunnel(port) {
-    return this._client._request("DELETE", `${vmPath(this.id)}/tunnels/${port}`, void 0, this.baseUrl);
+  async connectPty(options = {}) {
+    const sessionId = options.sessionId ?? sessionIdFrom(await this.createSession());
+    const useTicket = options.useTicket ?? !isNodeRuntime();
+    const params = {
+      cols: options.cols,
+      rows: options.rows,
+      command: options.command,
+      persist: options.persist,
+      cancel_ttl_secs: options.cancelTtlSecs && options.cancelTtlSecs > 0 ? Math.floor(options.cancelTtlSecs) : void 0
+    };
+    let ticket;
+    if (useTicket) {
+      const response = await this._client._request(
+        "POST",
+        `${vmPath(this.id)}/sessions/${pathSegment(sessionId)}/pty-ticket`,
+        {},
+        this.baseUrl
+      );
+      ticket = response.ticket;
+    }
+    const url = buildPtyWebSocketUrl(this.baseUrl, this.id, sessionId, { ...params, ticket });
+    const factory = options.webSocketFactory ?? (useTicket ? browserPtyWebSocketFactory : nodePtyWebSocketFactory);
+    const socket = await factory(url, useTicket ? {} : { headers: this._client._authHeaders() });
+    return new PtyConnectionImpl(sessionId, socket);
   }
 };
 function buildQuery(path, params) {
@@ -519,6 +585,176 @@ function buildQuery(path, params) {
   const qs = usp.toString();
   return qs ? `${path}?${qs}` : path;
 }
+function buildPtyWebSocketUrl(baseUrl, vmId, sessionId, params) {
+  const url = new URL(`${normalizeBaseUrl(baseUrl)}${vmPath(vmId)}/sessions/${pathSegment(sessionId)}/pty`);
+  if (url.protocol === "https:") url.protocol = "wss:";
+  else if (url.protocol === "http:") url.protocol = "ws:";
+  else throw new Error(`unsupported PTY WebSocket protocol: ${url.protocol}`);
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+function sessionIdFrom(session) {
+  const id = session.session_id ?? session.id;
+  if (!id) throw new ArkerError("internal", "createSession response missing session_id", 200);
+  return id;
+}
+function isNodeRuntime() {
+  return typeof process !== "undefined" && Boolean(process.versions?.node);
+}
+async function nodePtyWebSocketFactory(url, init) {
+  const ws = await import("ws");
+  return new ws.default(url, { headers: init.headers });
+}
+function browserPtyWebSocketFactory(url) {
+  if (typeof globalThis.WebSocket !== "function") {
+    throw new Error("WebSocket is not available in this runtime");
+  }
+  return new globalThis.WebSocket(url);
+}
+var PtyConnectionImpl = class {
+  constructor(sessionId, socket) {
+    this.sessionId = sessionId;
+    this.socket = socket;
+    try {
+      socket.binaryType = "arraybuffer";
+    } catch {
+    }
+    this.ready = waitForSocketOpen(socket);
+    addSocketListener(socket, "message", (event) => {
+      const data = messageData(event);
+      if (data !== void 0) this.emitData(bytesFromMessageData(data));
+    });
+    addSocketListener(socket, "close", (event) => this.emitClose(closeEvent(event)));
+    addSocketListener(socket, "error", (event) => this.emitError(event));
+  }
+  sessionId;
+  socket;
+  ready;
+  dataListeners = /* @__PURE__ */ new Set();
+  closeListeners = /* @__PURE__ */ new Set();
+  errorListeners = /* @__PURE__ */ new Set();
+  onData(listener) {
+    this.dataListeners.add(listener);
+    return () => this.dataListeners.delete(listener);
+  }
+  onClose(listener) {
+    this.closeListeners.add(listener);
+    return () => this.closeListeners.delete(listener);
+  }
+  onError(listener) {
+    this.errorListeners.add(listener);
+    return () => this.errorListeners.delete(listener);
+  }
+  send(data) {
+    this.socket.send(ptyInputBytes(data));
+  }
+  resize(cols, rows) {
+    this.socket.send(JSON.stringify({ type: "resize", cols: clampPtyDimension(cols), rows: clampPtyDimension(rows) }));
+  }
+  kill() {
+    this.socket.send(JSON.stringify({ type: "kill" }));
+  }
+  close(code, reason) {
+    this.socket.close(code, reason);
+  }
+  emitData(data) {
+    for (const listener of this.dataListeners) listener(data);
+  }
+  emitClose(event) {
+    for (const listener of this.closeListeners) listener(event);
+  }
+  emitError(error) {
+    for (const listener of this.errorListeners) listener(error);
+  }
+};
+function waitForSocketOpen(socket) {
+  if (socket.readyState === 1) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let removeOpen;
+    let removeError;
+    let removeClose;
+    const cleanup = () => {
+      removeOpen?.();
+      removeError?.();
+      removeClose?.();
+    };
+    removeOpen = addSocketListener(socket, "open", () => {
+      cleanup();
+      resolve();
+    });
+    removeError = addSocketListener(socket, "error", (event) => {
+      cleanup();
+      reject(event instanceof Error ? event : new Error("PTY WebSocket failed to open"));
+    });
+    removeClose = addSocketListener(socket, "close", (event) => {
+      cleanup();
+      const ev = closeEvent(event);
+      reject(new Error(`PTY WebSocket closed before opening${ev.code ? ` (${ev.code})` : ""}`));
+    });
+  });
+}
+function addSocketListener(socket, type, listener) {
+  if (socket.addEventListener) {
+    socket.addEventListener(type, listener);
+    return () => socket.removeEventListener?.(type, listener);
+  }
+  if (socket.on) {
+    const nodeListener = (...args) => {
+      if (type === "message") listener({ data: args[0] });
+      else if (type === "close") listener({ code: args[0], reason: args[1] });
+      else listener(args[0]);
+    };
+    socket.on(type, nodeListener);
+    return () => socket.off?.(type, nodeListener);
+  }
+  return () => {
+  };
+}
+function messageData(event) {
+  if (event && typeof event === "object" && "data" in event) {
+    return event.data;
+  }
+  return void 0;
+}
+function closeEvent(event) {
+  if (!event || typeof event !== "object") return {};
+  const raw = event;
+  return {
+    code: typeof raw.code === "number" ? raw.code : void 0,
+    reason: typeof raw.reason === "string" ? raw.reason : void 0
+  };
+}
+function bytesFromMessageData(data) {
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  }
+  if (Array.isArray(data)) {
+    const chunks = data.map(bytesFromMessageData);
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const out2 = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      out2.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return out2;
+  }
+  return new Uint8Array();
+}
+function ptyInputBytes(data) {
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  return data;
+}
+function clampPtyDimension(value) {
+  if (!Number.isFinite(value)) return 1;
+  return Math.max(1, Math.min(1e3, Math.trunc(value)));
+}
 function normalizeBaseUrl(baseUrl) {
   const trimmed = baseUrl.trim().replace(/\/+$/, "");
   if (!trimmed) throw new Error("baseUrl must not be empty");
@@ -601,15 +837,17 @@ function parseRunResponse(payload) {
       stderr: decodeBytes(stderr, stderrEncoding),
       stderrEncoding,
       exitCode: numberField(body.exit_code, "run response.exit_code"),
-      failReason: typeof body.fail_reason === "string" ? body.fail_reason : null
+      failReason: typeof body.fail_reason === "string" ? body.fail_reason : null,
+      memoryRequestedMib: optionalNumberOrNull(body.memory_requested_mib),
+      memoryAchievedMib: optionalNumberOrNull(body.memory_achieved_mib),
+      memoryPartial: typeof body.memory_partial === "boolean" ? body.memory_partial : void 0
     };
   }
   if (typeof body.run_id === "string") {
     return {
       type: "background",
       runId: body.run_id,
-      state: typeof body.state === "string" ? body.state : "running",
-      tunnels: Array.isArray(body.tunnels) ? body.tunnels : []
+      state: typeof body.state === "string" ? body.state : "running"
     };
   }
   throw new ArkerError("internal", "unrecognized run response shape", 200);
@@ -673,6 +911,10 @@ function numberField(value, context) {
   if (typeof value !== "number") throw new ArkerError("internal", `${context} must be a number`, 200);
   return value;
 }
+function optionalNumberOrNull(value) {
+  if (value === null || typeof value === "number") return value;
+  return void 0;
+}
 function assertWriteComplete(result, context) {
   if (result.complete && result.written) return;
   throw new ArkerError("internal", `${context} did not complete`, 200);
@@ -748,20 +990,25 @@ function parseArgs(argv) {
   return { positional, flags };
 }
 function readFileConfig() {
-  const path = (0, import_node_path.join)((0, import_node_os.homedir)(), ".arker", "config.json");
-  if (!(0, import_node_fs.existsSync)(path)) return {};
-  try {
-    return JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
-  } catch {
-    return {};
+  for (const name of ["config.json", "config"]) {
+    const path = (0, import_node_path.join)((0, import_node_os.homedir)(), ".arker", name);
+    if (!(0, import_node_fs.existsSync)(path)) continue;
+    try {
+      return JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
+    } catch {
+      return {};
+    }
   }
+  return {};
 }
 function clientFromArgs(args) {
   const file = readFileConfig();
+  const explicitBaseUrl = args.flags["base-url"] ?? process.env.ARKER_BASE_URL;
+  const explicitRegion = args.flags.region ?? process.env.ARKER_REGION;
   const apiKey = args.flags["api-key"] ?? process.env.ARKER_API_KEY ?? file.apiKey;
-  const baseUrl = args.flags["base-url"] ?? process.env.ARKER_BASE_URL ?? file.baseUrl;
+  const baseUrl = explicitBaseUrl ?? (explicitRegion ? void 0 : file.baseUrl);
   const controlBaseUrl = args.flags["control-base-url"] ?? process.env.ARKER_CONTROL_BASE_URL;
-  const region = args.flags.region ?? process.env.ARKER_REGION ?? file.region;
+  const region = explicitRegion ?? file.region;
   const provider = args.flags.provider ?? process.env.ARKER_PROVIDER;
   if (!apiKey) {
     die("Missing API key. Set ARKER_API_KEY or pass --api-key.");
@@ -791,7 +1038,8 @@ function fmtVm(vm) {
   const region = vm.region ?? "?";
   const name = vm.name ?? "\u2014";
   const state = vm.state ?? "?";
-  return `${vm.vm_id ?? vm.id}	${provider}-${region}	${state}	${name}`;
+  const id = vm.vm_id ?? vm.id;
+  return `${id}	${provider}-${region}	${state}	${name}`;
 }
 async function cmdVms(args, client) {
   const sub = args.positional[0];
@@ -836,6 +1084,10 @@ async function cmdVms(args, client) {
       await cmdRun({ ...args, positional: rest }, client);
       return;
     }
+    case "resize": {
+      await cmdResize({ ...args, positional: rest }, client);
+      return;
+    }
     default:
       die(`unknown vms subcommand: ${sub}`);
   }
@@ -854,14 +1106,22 @@ async function cmdFork(args, client) {
     sourceVmName = refPositional;
   }
   if (!sourceVmId && !sourceVmName) {
-    die("usage: arker fork <vm_name> | --source-vm-id <id> | --source-vm-name <name> [--source-org-id <org>]");
-  }
+    die("usage: arker fork <vm_name> | --source-vm-id <id> | --source-vm-name <name> [--source-org-id <org>]\n       [--vcpu N] [--memory-mib N] [--disk-mib N] [--no-disk]");
+  }
+  const vcpu = numFlag(args, "vcpu");
+  const memoryMib = numFlag(args, "memory-mib");
+  const diskMib = numFlag(args, "disk-mib");
+  const hasResources = vcpu !== void 0 || memoryMib !== void 0 || diskMib !== void 0;
+  const resources = hasResources ? { vcpu: vcpu ?? null, memory_mib: memoryMib ?? null, disk_mib: diskMib ?? null } : void 0;
+  const disk = boolFlag(args, "no-disk") ? false : void 0;
   const computer = await client.fork({
     sourceVmId,
     sourceVmName,
     sourceOrgId,
     name,
-    public: publicFlag
+    public: publicFlag,
+    ...resources ? { resources } : {},
+    ...disk !== void 0 ? { disk } : {}
   });
   out({ vm_id: computer.id });
 }
@@ -869,19 +1129,54 @@ async function cmdRun(args, client) {
   const vmId = args.positional[0] ?? die("usage: arker run <vm_id> <command...>");
   const command = args.positional.slice(1).join(" ");
   if (!command) die("missing command to run");
+  const sessionIdx = numFlag(args, "session-idx");
   const result = await client.vm(vmId).run(command, {
     background: boolFlag(args, "background"),
     timeout: numFlag(args, "timeout"),
     acquire: args.flags.acquire,
-    release: args.flags.release
+    release: args.flags.release,
+    session_id: args.flags["session-id"],
+    ...sessionIdx !== void 0 ? { session_idx: sessionIdx } : {}
   });
+  if (args.flags.json) {
+    out(runResultForJson(result));
+    if (result.type === "completed") process.exitCode = result.exitCode === 0 ? 0 : result.exitCode;
+    return;
+  }
   if (result.type === "completed") {
+    if (result.memoryPartial) {
+      err(`Memory target partially applied: requested ${formatMib(result.memoryRequestedMib)}, achieved ${formatMib(result.memoryAchievedMib)}.`);
+    }
     process.stdout.write(new TextDecoder().decode(result.stdout));
     if (result.stderr.length) process.stderr.write(new TextDecoder().decode(result.stderr));
     process.exitCode = result.exitCode === 0 ? 0 : result.exitCode;
     return;
   }
-  out({ run_id: result.runId, tunnels: result.tunnels });
+  out({ run_id: result.runId, state: result.state });
+}
+function formatMib(value) {
+  return typeof value === "number" ? `${value} MiB` : "unknown";
+}
+function runResultForJson(result) {
+  switch (result.type) {
+    case "completed":
+      return {
+        type: result.type,
+        runId: result.runId,
+        state: result.state,
+        stdout: new TextDecoder().decode(result.stdout),
+        stdoutEncoding: result.stdoutEncoding,
+        stderr: new TextDecoder().decode(result.stderr),
+        stderrEncoding: result.stderrEncoding,
+        exitCode: result.exitCode,
+        failReason: result.failReason,
+        memoryRequestedMib: result.memoryRequestedMib,
+        memoryAchievedMib: result.memoryAchievedMib,
+        memoryPartial: result.memoryPartial
+      };
+    case "background":
+      return result;
+  }
 }
 async function cmdRuns(args, client) {
   const sub = args.positional[0];
@@ -1024,43 +1319,24 @@ async function cmdSync(args, client) {
   }
   import_node_process.stdout.write(await client.vm(vm).sync(path));
 }
-async function cmdTunnels(args, client) {
-  const sub = args.positional[0];
-  const rest = args.positional.slice(1);
-  const vm = rest[0];
-  switch (sub) {
-    case "ls":
-    case "list": {
-      if (!vm) die("usage: arker tunnels ls <vm_id>");
-      const res = await client.vm(vm).listTunnels({
-        state: args.flags.state,
-        cursor: args.flags.cursor,
-        limit: numFlag(args, "limit")
-      });
-      if (args.flags.json) return out(res);
-      for (const t of res.tunnels) {
-        out(`${t.port}	${t.state}	${t.protocol}	${t.url ?? "-"}`);
-      }
-      if (res.next_cursor) out(`# next_cursor=${res.next_cursor}`);
-      return;
-    }
-    case "get": {
-      if (!vm) die("usage: arker tunnels get <vm_id> <port>");
-      const port = Number(rest[1] ?? die("missing port"));
-      out(await client.vm(vm).getTunnel(port));
-      return;
-    }
-    case "rm":
-    case "delete": {
-      if (!vm) die("usage: arker tunnels rm <vm_id> <port>");
-      const port = Number(rest[1] ?? die("missing port"));
-      const r = await client.vm(vm).deleteTunnel(port);
-      out(r.deleted ? `deleted tunnel ${port}` : "delete failed");
-      return;
+async function cmdResize(args, client) {
+  const vm = args.positional[0];
+  if (!vm) die("usage: arker resize <vm_id> [--memory-mib N] [--vcpu N] [--disk-mib N]");
+  const memoryMib = numFlag(args, "memory-mib");
+  const vcpu = numFlag(args, "vcpu");
+  const diskMib = numFlag(args, "disk-mib");
+  if (memoryMib === void 0 && vcpu === void 0 && diskMib === void 0) {
+    die("resize: pass at least one of --memory-mib, --vcpu, --disk-mib");
+  }
+  const updated = await client.vm(vm).resize({
+    resources: {
+      vcpu: vcpu ?? null,
+      memory_mib: memoryMib ?? null,
+      disk_mib: diskMib ?? null
     }
-    default:
-      die(`usage: arker tunnels <ls|get|rm> ...`);
-  }
+  });
+  if (args.flags.json) return out(updated);
+  out(fmtVm(updated));
 }
 async function cmdFilesystems(args, client) {
   const sub = args.positional[0];
@@ -1106,6 +1382,10 @@ async function cmdFilesystems(args, client) {
 async function cmdShell(args, client) {
   let computer;
   const vmIdArg = args.flags["vm-id"] ?? args.positional[0];
+  const explicitSessionId = args.flags["session-id"];
+  if (!vmIdArg && explicitSessionId) {
+    die("usage: arker shell <vm_id> --session-id <session_id>");
+  }
   if (vmIdArg) {
     computer = await client.vm(vmIdArg).refresh();
   } else {
@@ -1114,100 +1394,242 @@ async function cmdShell(args, client) {
       sourceVmName,
       sourceOrgId: ARKER_ORG_ID
     });
+    err(`forked ${computer.id}`);
   }
-  const header = computer;
-  const session = await computer.createSession({
-    cwd: args.flags.cwd
+  let sessionId = explicitSessionId;
+  if (!sessionId) {
+    const session = await computer.createSession({
+      cwd: args.flags.cwd
+    });
+    sessionId = session.session_id ?? session.id;
+    if (!sessionId) die("createSession response missing session_id");
+  }
+  const persist = args.flags["no-persist"] === true ? false : boolFlag(args, "persist");
+  const colsFlag = numFlag(args, "cols");
+  const rowsFlag = numFlag(args, "rows");
+  const cols = colsFlag ?? import_node_process.stdout.columns ?? 80;
+  const rows = rowsFlag ?? import_node_process.stdout.rows ?? 24;
+  const cancelTtlSecs = numFlag(args, "cancel-ttl");
+  const pty = await computer.connectPty({
+    sessionId,
+    cols,
+    rows,
+    command: args.flags.command,
+    persist,
+    cancelTtlSecs
   });
-  const sessionId = session.session_id;
-  const timeout = numFlag(args, "timeout");
-  const preload = args.positional.slice(vmIdArg ? 1 : 0).join(" ").trim();
-  const exitAfter = args.flags.exit === true;
-  import_node_process.stdout.write(JSON.stringify(header, null, 2) + "\n");
-  let inFlight = false;
-  let exitCode = 0;
-  try {
-    if (preload && preload !== "exit") {
-      const step = await runShellLine(computer, sessionId, preload, timeout);
-      if (step.kind === "fatal") {
-        err(`shell ended: ${step.message}`);
-        return;
-      }
-      if (step.kind === "recoverable") {
-        err(`error: ${step.message}`);
-        exitCode = 1;
-      } else {
-        exitCode = step.exitCode;
-      }
-    }
-    if (exitAfter || preload === "exit") {
-      process.exit(exitCode);
-    }
-    const rl = readline.createInterface({ input: import_node_process.stdin, output: import_node_process.stdout, prompt: "> " });
-    rl.on("SIGINT", () => {
-      if (inFlight) {
-        process.stderr.write("^C\n");
-        return;
+  err(`connected ${computer.id} session ${sessionId}`);
+  const exitCode = await bridgePty(pty, {
+    fallbackCols: cols,
+    fallbackRows: rows,
+    autoResize: colsFlag === void 0 && rowsFlag === void 0 && Boolean(import_node_process.stdout.isTTY)
+  });
+  if (exitCode !== 0) process.exit(exitCode);
+}
+function bridgePty(pty, options) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let rawEnabled = false;
+    const wasRaw = Boolean(import_node_process.stdin.isTTY && import_node_process.stdin.isRaw);
+    const restoreTerminal = () => {
+      if (rawEnabled && import_node_process.stdin.isTTY && typeof import_node_process.stdin.setRawMode === "function") {
+        import_node_process.stdin.setRawMode(wasRaw);
       }
-      process.stdout.write("^C\n");
-      rl.write(null, { ctrl: true, name: "u" });
-      rl.prompt();
+      rawEnabled = false;
+    };
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      restoreTerminal();
+      import_node_process.stdin.off("data", onInput);
+      import_node_process.stdin.off("end", onInputEnd);
+      process.off("SIGWINCH", onResize);
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      process.off("SIGHUP", onSighup);
+      process.off("exit", restoreTerminal);
+      offData();
+      offClose();
+      offError();
+      resolve(code);
+    };
+    const onInput = (chunk) => {
+      pty.send(chunk);
+    };
+    const onInputEnd = () => {
+      pty.close();
+    };
+    const onResize = () => {
+      pty.resize(import_node_process.stdout.columns ?? options.fallbackCols, import_node_process.stdout.rows ?? options.fallbackRows);
+    };
+    const onSigint = () => {
+      pty.send(new Uint8Array([3]));
+    };
+    const onSigterm = () => {
+      pty.close();
+      finish(143);
+    };
+    const onSighup = () => {
+      pty.close();
+      finish(129);
+    };
+    const offData = pty.onData((data) => {
+      import_node_process.stdout.write(data);
     });
-    rl.prompt();
-    for await (const line of rl) {
-      const cmd = line.trim();
-      if (!cmd) {
-        rl.prompt();
-        continue;
-      }
-      if (cmd === "exit" || cmd === "quit") break;
-      inFlight = true;
-      const step = await runShellLine(computer, sessionId, cmd, timeout);
-      inFlight = false;
-      if (step.kind === "fatal") {
-        err(`shell ended: ${step.message}`);
-        exitCode = 1;
-        break;
-      }
-      if (step.kind === "recoverable") {
-        err(`error: ${step.message}`);
+    const offClose = pty.onClose(() => finish(0));
+    const offError = pty.onError((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      err(`pty error: ${message}`);
+    });
+    process.once("exit", restoreTerminal);
+    pty.ready.then(() => {
+      if (settled) return;
+      if (import_node_process.stdin.isTTY && typeof import_node_process.stdin.setRawMode === "function") {
+        import_node_process.stdin.setRawMode(true);
+        rawEnabled = true;
       }
-      rl.prompt();
-    }
-    rl.close();
-  } finally {
-    await computer.deleteSession(sessionId).catch(() => {
+      import_node_process.stdin.resume();
+      import_node_process.stdin.on("data", onInput);
+      import_node_process.stdin.on("end", onInputEnd);
+      if (options.autoResize) process.on("SIGWINCH", onResize);
+      process.on("SIGINT", onSigint);
+      process.on("SIGTERM", onSigterm);
+      process.on("SIGHUP", onSighup);
+      if (options.autoResize) onResize();
+    }).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      err(`pty failed to open: ${message}`);
+      finish(1);
     });
+  });
+}
+var SSH_PORT_DEFAULT = 22;
+function defaultIdentityBase() {
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".ssh", "id_ed25519");
+}
+function resolveLocalSshKey(args) {
+  const explicit = args.flags.identity;
+  const privateKeyPath = explicit ? explicit.replace(/\.pub$/, "") : defaultIdentityBase();
+  const publicKeyPath = `${privateKeyPath}.pub`;
+  if (!(0, import_node_fs.existsSync)(publicKeyPath)) {
+    if (!boolFlag(args, "generate")) {
+      die(
+        `no SSH public key at ${publicKeyPath}. Pass --identity <path>, or --generate to create an ed25519 key pair.`
+      );
+    }
+    err(`generating ed25519 key pair at ${privateKeyPath}`);
+    const gen = (0, import_node_child_process.spawnSync)(
+      "ssh-keygen",
+      ["-t", "ed25519", "-N", "", "-f", privateKeyPath, "-C", "arker-cli"],
+      { stdio: "inherit" }
+    );
+    if (gen.status !== 0) die("ssh-keygen failed to generate a key pair");
   }
-  if (exitCode !== 0) process.exit(exitCode);
+  const publicKey = (0, import_node_fs.readFileSync)(publicKeyPath, "utf8").trim();
+  if (!publicKey) die(`SSH public key at ${publicKeyPath} is empty`);
+  return { publicKey, privateKeyPath, publicKeyPath };
+}
+async function registerAccountSshKey(client, publicKey, label) {
+  return client._request(
+    "POST",
+    "/v1/account/ssh-keys",
+    { public_key: publicKey, label: label ?? null },
+    client.baseUrl
+  );
 }
-async function runShellLine(computer, sessionId, cmd, timeout) {
+function resolveSshHost(args, client) {
+  const explicit = args.flags.host ?? process.env.ARKER_SSH_HOST;
+  if (explicit) return explicit;
+  if (client.region) return `aws-${client.region}.arker.ai`;
   try {
-    const result = await computer.run(cmd, { session_id: sessionId, timeout });
-    if (result.type === "completed") {
-      if (result.stdout.length) process.stdout.write(new TextDecoder().decode(result.stdout));
-      if (result.stderr.length) process.stderr.write(new TextDecoder().decode(result.stderr));
-      const tail = result.stderr.length > 0 ? result.stderr[result.stderr.length - 1] : result.stdout.length > 0 ? result.stdout[result.stdout.length - 1] : void 0;
-      if (tail !== void 0 && tail !== 10) process.stdout.write("\n");
-      return { kind: "ok", exitCode: result.exitCode };
-    }
-    out({ run_id: result.runId });
-    return { kind: "ok", exitCode: 0 };
-  } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    const kind = classifyShellError(message, computer.id);
-    return { kind, message };
+    return new URL(client.baseUrl).hostname;
+  } catch {
+    die("could not determine SSH host; pass --host <hostname>");
   }
 }
-function classifyShellError(message, vmId) {
-  const msg = message.toLowerCase();
-  if (msg.includes("unauthor") || msg.includes("forbidden") || msg.includes("invalid api key")) {
-    return "fatal";
+async function cmdSsh(args, client) {
+  const vmId = args.flags["vm-id"] ?? args.positional[0];
+  if (!vmId) {
+    die(
+      "usage: arker ssh <vm_id> [--identity <path>] [--generate] [--host <h>] [--port <n>] [--connect|-c] [--skip-register]"
+    );
+  }
+  const { publicKey, privateKeyPath } = resolveLocalSshKey(args);
+  if (!boolFlag(args, "skip-register")) {
+    const label = args.flags.label ?? `arker-cli ${(0, import_node_os.homedir)().split("/").pop() ?? ""}`.trim();
+    try {
+      const key = await registerAccountSshKey(client, publicKey, label);
+      err(`registered SSH key ${key.fingerprint}${key.label ? ` (${key.label})` : ""}`);
+    } catch (e) {
+      if (e instanceof ArkerError && e.status === 409) {
+        die(`this SSH key is already registered to a different account: ${e.message}`);
+      }
+      if (e instanceof ArkerError && e.status === 403) {
+        die(
+          "your API key lacks the developer role required to register SSH keys. Register the key in the console, then re-run with --skip-register."
+        );
+      }
+      throw e;
+    }
   }
-  if ((msg.includes("not_found") || msg.includes("not found")) && msg.includes(vmId.toLowerCase())) {
-    return "fatal";
+  const host = resolveSshHost(args, client);
+  const port = numFlag(args, "port") ?? SSH_PORT_DEFAULT;
+  const sshArgs = [
+    "-i",
+    privateKeyPath,
+    ...port !== 22 ? ["-p", String(port)] : [],
+    `${vmId}@${host}`
+  ];
+  const command = `ssh ${sshArgs.join(" ")}`;
+  if (boolFlag(args, "connect") || boolFlag(args, "c")) {
+    err(`connecting: ${command}`);
+    const r = (0, import_node_child_process.spawnSync)("ssh", sshArgs, { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+  }
+  out(command);
+}
+async function cmdSshKeys(args, client) {
+  const sub = args.positional[0];
+  const rest = args.positional.slice(1);
+  switch (sub) {
+    case void 0:
+    case "ls":
+    case "list": {
+      const res = await client._request(
+        "GET",
+        "/v1/account/ssh-keys",
+        void 0,
+        client.baseUrl
+      );
+      if (args.flags.json) return out(res);
+      for (const k of res.keys) {
+        out(`${k.id}	${k.fingerprint}	${k.label ?? "\u2014"}`);
+      }
+      return;
+    }
+    case "add": {
+      const { publicKey } = resolveLocalSshKey(args);
+      const label = args.flags.label;
+      const key = await registerAccountSshKey(client, publicKey, label);
+      if (args.flags.json) return out(key);
+      out(`${key.id}	${key.fingerprint}	${key.label ?? "\u2014"}`);
+      return;
+    }
+    case "rm":
+    case "delete": {
+      const id = rest[0] ?? die("usage: arker ssh-keys rm <key_id>");
+      const r = await client._request(
+        "DELETE",
+        `/v1/account/ssh-keys/${encodeURIComponent(id)}`,
+        void 0,
+        client.baseUrl
+      );
+      out(r.deleted ? `deleted ${id}` : "delete failed");
+      return;
+    }
+    default:
+      die("usage: arker ssh-keys <ls|add|rm> ...");
   }
-  return "recoverable";
 }
 function numFlag(args, name) {
   const v = args.flags[name];
@@ -1241,16 +1663,21 @@ function usage() {
       "  arker fork --source-vm-id <id>                 fork by global id",
       "  arker fork --source-vm-name <n> --source-org-id <org>",
       "                                                 fork by name in another org",
-      "  arker run <vm> <command>                       run a command",
-      "  arker shell [vm_id]                            interactive shell (forks arkuntu if no vm)",
+      "  arker fork <vm> [--vcpu N] [--memory-mib N] [--disk-mib N] [--no-disk]",
+      "                                                 fork with resource/network overrides",
+      "  arker run <vm> <command> [--session-id <id>] [--session-idx N]   run a command",
+      "  arker resize <vm> [--memory-mib N] [--vcpu N] [--disk-mib N]   resize a VM (PATCH)",
+      "  arker shell [vm_id]                            native PTY shell (forks ubuntu-full if no vm)",
+      "  arker ssh <vm_id>                              register your SSH key + print the ssh command",
+      "  arker ssh <vm_id> --connect                    register + drop straight into the ssh session",
       "",
       "Resources:",
       "  arker vms         <ls|get|rm|fork|run> ...",
       "  arker runs        <ls|get|rm> <vm_id> ...",
       "  arker sessions    <ls|get|create|rm> <vm_id> ...",
       "  arker syncs       <ls|create|rm> <vm_id> ...",
-      "  arker tunnels     <ls|get|rm> <vm_id> ...",
       "  arker filesystems <ls|create|get|rm> ...   (alias: fs)",
+      "  arker ssh-keys    <ls|add|rm> ...           manage account SSH keys",
       "",
       "Flags:",
       "  --api-key <key>            (or env ARKER_API_KEY)",
@@ -1260,6 +1687,35 @@ function usage() {
       "  --control-base-url <url>   override CF Worker URL (env ARKER_CONTROL_BASE_URL)",
       "  --json                     emit JSON instead of tabular output",
       "",
+      "Fork flags:",
+      "  --vcpu <n>                 vCPU count for the new VM (capped by source max_vcpus)",
+      "  --memory-mib <n>           memory (MiB) for the new VM",
+      "  --disk-mib <n>             disk size (MiB) for the new VM",
+      "  --no-disk                  fork a memory-backed (nodisk) VM",
+      "",
+      "Run flags:",
+      "  --session-id <ulid>        run in a specific existing session",
+      "  --session-idx <n>          run in the session at this index (default 0)",
+      "  --background               return a run id instead of blocking",
+      "  --timeout <secs>           per-run timeout",
+      "  --acquire <list>           warm resources before the run (cpu,memory,disk)",
+      "  --release <list>           release resources after the run (cpu,memory,disk)",
+      "",
+      "Shell flags:",
+      "  --session-id <id>          reconnect to an existing PTY session",
+      "  --command <path>           shell executable path (default: /bin/bash)",
+      "  --cols <n> --rows <n>      initial terminal size",
+      "  --no-persist               close the remote PTY process on disconnect",
+      "",
+      "SSH flags:",
+      "  --identity <path>          local key (private or .pub); default ~/.ssh/id_ed25519",
+      "  --generate                 create an ed25519 key pair if none exists",
+      "  --host <hostname>          SSH host (or env ARKER_SSH_HOST; default aws-<region>.arker.ai)",
+      "  --port <n>                 SSH port (default 22)",
+      "  --connect, -c              exec ssh instead of just printing the command",
+      "  --skip-register            don't register the key (assume already registered)",
+      "  --label <text>             label for the registered key",
+      "",
       `Arker org id: ${ARKER_ORG_ID}`
     ].join("\n")
   );
@@ -1290,6 +1746,11 @@ async function main() {
         return await cmdSyncs(args, client);
       case "shell":
         return await cmdShell(args, client);
+      case "ssh":
+        return await cmdSsh(args, client);
+      case "ssh-keys":
+      case "ssh_keys":
+        return await cmdSshKeys(args, client);
       // Resources.
       case "vms":
         return await cmdVms(args, client);
@@ -1297,8 +1758,8 @@ async function main() {
         return await cmdRuns(args, client);
       case "sessions":
         return await cmdSessions(args, client);
-      case "tunnels":
-        return await cmdTunnels(args, client);
+      case "resize":
+        return await cmdResize(args, client);
       case "filesystems":
       case "fs":
         return await cmdFilesystems(args, client);