xapi-to 0.1.19 → 0.1.21

package/dist/index.js

@@ -1,661 +1,55 @@
 #!/usr/bin/env node
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// src/config.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
-
-// src/format.ts
-function getFormat() {
-  const f = process.env.XAPI_OUTPUT || "json";
-  if (f === "pretty" || f === "table") return f;
-  return "json";
-}
-function output(data, format) {
-  const fmt = format || getFormat();
-  if (fmt === "json") {
-    console.log(JSON.stringify(data));
-    return;
-  }
-  if (fmt === "pretty") {
-    console.log(JSON.stringify(data, null, 2));
-    return;
-  }
-  if (fmt === "table") {
-    const rows = tableRows(data);
-    if (rows) {
-      printTable(rows);
-      return;
-    }
-  }
-  console.log(JSON.stringify(data, null, 2));
-}
-function tableRows(data) {
-  if (Array.isArray(data)) return normalizeRows(data, "value");
-  if (!data || typeof data !== "object") return null;
-  const obj = data;
-  const preferredKeys = ["items", "actions", "results", "services", "categories", "bindings", "providers"];
-  for (const key of preferredKeys) {
-    const value = obj[key];
-    if (Array.isArray(value)) return normalizeRows(value, singularKey(key));
-  }
-  const firstArray = Object.entries(obj).find(([, value]) => Array.isArray(value));
-  return firstArray ? normalizeRows(firstArray[1], singularKey(firstArray[0])) : null;
-}
-function normalizeRows(rows, primitiveKey) {
-  return rows.map((row) => {
-    if (row && typeof row === "object" && !Array.isArray(row)) {
-      return row;
-    }
-    return { [primitiveKey]: row };
-  });
-}
-function singularKey(key) {
-  if (key === "categories") return "category";
-  if (key.endsWith("ies")) return `${key.slice(0, -3)}y`;
-  if (key.endsWith("s")) return key.slice(0, -1);
-  return "value";
-}
-function formatCell(value) {
-  if (value === null || value === void 0) return "";
-  if (typeof value === "object") return JSON.stringify(value);
-  return String(value);
-}
-function printTable(rows) {
-  if (rows.length === 0) {
-    console.log("(empty)");
-    return;
-  }
-  const keys = Object.keys(rows[0]);
-  const widths = keys.map(
-    (k) => Math.min(40, Math.max(k.length, ...rows.map((r) => formatCell(r[k]).length)))
-  );
-  const sep = widths.map((w) => "-".repeat(w)).join("  ");
-  const header = keys.map((k, i) => k.padEnd(widths[i])).join("  ");
-  console.log(header);
-  console.log(sep);
-  for (const row of rows) {
-    const line = keys.map((k, i) => formatCell(row[k]).slice(0, widths[i]).padEnd(widths[i])).join("  ");
-    console.log(line);
-  }
-}
-function err(msg, detail) {
-  if (process.stderr.isTTY) {
-    console.error(`Error: ${msg}`);
-    if (detail !== void 0) console.error(`  ${detail}`);
-  } else {
-    const out = { error: msg };
-    if (detail !== void 0) out.detail = detail;
-    console.error(JSON.stringify(out));
-  }
-  process.exit(1);
-}
-
-// src/config.ts
-import { homedir } from "os";
-import { join } from "path";
-var XAPI_ACTION_HOST = process.env.XAPI_ACTION_HOST || "action.xapi.to";
-var XAPI_API_HOST = process.env.XAPI_API_HOST || "api.xapi.to";
-function scheme(host) {
-  return isLoopbackHost(host) ? "http" : "https";
-}
-var ALLOWED_HOST_EXACT = ["xapi.to", "xapi.xyz"];
-var ALLOWED_HOST_SUFFIXES = [".xapi.to", ".xapi.xyz"];
-function hostnameOf(hostOrUrl) {
-  const raw = hostOrUrl.includes("://") ? hostOrUrl : `http://${hostOrUrl}`;
-  try {
-    return new URL(raw).hostname.toLowerCase();
-  } catch {
-    return "";
-  }
-}
-function isLoopbackIPv4(h) {
-  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
-  if (!m) return false;
-  const octets = m.slice(1).map(Number);
-  return octets.every((o) => o <= 255) && octets[0] === 127;
-}
-function isLoopbackHostname(h) {
-  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "[::1]" || isLoopbackIPv4(h);
-}
-function isLoopbackHost(hostOrUrl) {
-  return isLoopbackHostname(hostnameOf(hostOrUrl));
-}
-function isAllowedHost(hostOrUrl) {
-  const h = hostnameOf(hostOrUrl);
-  if (!h) return false;
-  if (isLoopbackHostname(h)) return true;
-  if (ALLOWED_HOST_EXACT.includes(h)) return true;
-  return ALLOWED_HOST_SUFFIXES.some((suffix) => h.endsWith(suffix));
-}
-function assertAllowedHost(hostOrUrl) {
-  if (!isAllowedHost(hostOrUrl)) {
-    throw new Error(
-      `refusing to contact untrusted host "${hostnameOf(hostOrUrl) || hostOrUrl}": the xapi API key may only be sent to *.xapi.to, *.xapi.xyz, or localhost`
-    );
-  }
-}
-var CONFIG_DIR = join(homedir(), ".xapi");
-var CONFIG_FILE = join(CONFIG_DIR, "config.json");
-function loadFileConfig() {
-  if (!existsSync(CONFIG_FILE)) return {};
-  try {
-    const parsed = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
-    if (!parsed || typeof parsed !== "object") return {};
-    return typeof parsed.apiKey === "string" && parsed.apiKey.trim() ? { apiKey: parsed.apiKey } : {};
-  } catch {
-    return {};
-  }
-}
-function getApiKeySource() {
-  if (process.env.XAPI_KEY) return "XAPI_KEY";
-  if (process.env.XAPI_API_KEY) return "XAPI_API_KEY";
-  return loadFileConfig().apiKey ? "file" : "none";
-}
-function getConfig() {
-  const file = loadFileConfig();
-  return {
-    actionHost: XAPI_ACTION_HOST,
-    apiKey: process.env.XAPI_KEY || process.env.XAPI_API_KEY || file.apiKey
-  };
-}
-function requireApiKey(cfg) {
-  if (!cfg.apiKey) {
-    err("API key not configured", 'Run "npx xapi-to register" to create an account, or "npx xapi-to config set apiKey=<key>" to set an existing key.');
-  }
-}
-function saveConfig(updates) {
-  const current = loadFileConfig();
-  const merged = { ...current, ...updates };
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
-  if (process.platform !== "win32") chmodSync(CONFIG_DIR, 448);
-  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
-  if (process.platform !== "win32") chmodSync(CONFIG_FILE, 384);
-}
-function showConfig() {
-  const cfg = getConfig();
-  return {
-    actionHost: cfg.actionHost,
-    apiKey: cfg.apiKey ? `${cfg.apiKey.slice(0, 8)}...` : void 0,
-    source: {
-      apiKey: getApiKeySource()
-    },
-    configFile: CONFIG_FILE
-  };
-}
-
-// src/client.ts
-import { open, rm } from "fs/promises";
-import { once } from "events";
-import { resolve } from "path";
-import { Readable, Transform } from "stream";
-import { pipeline } from "stream/promises";
-var DEFAULT_TIMEOUT_MS = 3e4;
-var EXECUTE_TIMEOUT_MS = 6e4;
-var TRANSFER_IDLE_TIMEOUT_MS = 6e4;
-var IDEMPOTENT_RETRIES = 2;
-var RETRY_BASE_DELAY_MS = 500;
-var RETRY_MAX_DELAY_MS = 8e3;
-var HttpError = class extends Error {
-  constructor(status, detail, retryAfterMs) {
-    super(`HTTP ${status}: ${detail}`);
-    this.status = status;
-    this.retryAfterMs = retryAfterMs;
-    this.name = "HttpError";
-  }
-  status;
-  retryAfterMs;
-};
-var RequestTimeoutError = class extends Error {
-  constructor(timeoutMs) {
-    super(`request timed out after ${timeoutMs}ms`);
-    this.timeoutMs = timeoutMs;
-    this.name = "RequestTimeoutError";
-  }
-  timeoutMs;
-};
-function isRetryableStatus(status) {
-  return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
-}
-function isRetryableNetworkError(e) {
-  if (!(e instanceof Error)) return false;
-  if (e instanceof HttpError || e instanceof RequestTimeoutError) return false;
-  if (e.name === "AbortError") return false;
-  return e instanceof TypeError || /network|fetch failed|econn|etimedout|eai_again|socket|dns/i.test(e.message);
-}
-function isRetryableRequestError(e) {
-  if (e instanceof HttpError) return isRetryableStatus(e.status);
-  if (e instanceof RequestTimeoutError) return true;
-  return isRetryableNetworkError(e);
-}
-function retryBaseDelayMs() {
-  const override = Number(process.env.XAPI_RETRY_BASE_MS);
-  return Number.isFinite(override) && override > 0 ? override : RETRY_BASE_DELAY_MS;
-}
-function transferIdleTimeoutMs() {
-  const override = Number(process.env.XAPI_TRANSFER_IDLE_TIMEOUT_MS);
-  return Number.isFinite(override) && override > 0 ? override : TRANSFER_IDLE_TIMEOUT_MS;
-}
-function backoffDelayMs(attempt, retryAfterMs) {
-  if (retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
-    return Math.min(retryAfterMs, RETRY_MAX_DELAY_MS);
-  }
-  const capped = Math.min(retryBaseDelayMs() * 2 ** attempt, RETRY_MAX_DELAY_MS);
-  return capped / 2 + Math.random() * (capped / 2);
-}
-function parseRetryAfterMs(res) {
-  const header = res.headers.get("retry-after");
-  if (!header) return void 0;
-  const seconds = Number(header);
-  if (Number.isFinite(seconds)) return seconds * 1e3;
-  const at = Date.parse(header);
-  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
-}
-function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
-}
-async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0) {
-  assertAllowedHost(url);
-  let attempt = 0;
-  while (true) {
-    const controller = new AbortController();
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
-      controller.abort();
-    }, timeoutMs);
-    try {
-      const res = await fetch(url, { ...options, redirect: "manual", signal: controller.signal });
-      if (res.status >= 300 && res.status < 400) {
-        throw new Error(
-          `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
-        );
-      }
-      if (!res.ok) {
-        const retryAfterMs = isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0;
-        if (isRetryableStatus(res.status) && attempt < retries) {
-          await res.text().catch(() => "");
-          clearTimeout(timer);
-          await sleep(backoffDelayMs(attempt, retryAfterMs));
-          attempt++;
-          continue;
-        }
-        const text2 = await res.text();
-        throw new HttpError(res.status, text2.slice(0, 300), retryAfterMs);
-      }
-      if (res.status === 204) {
-        return void 0;
-      }
-      const text = await res.text();
-      if (!text.trim()) {
-        return void 0;
-      }
-      const body = JSON.parse(text);
-      if (body && typeof body === "object" && "success" in body && body.success === false) {
-        const data = body.data;
-        if (data?.statusCode === 401 || data?.error === "Unauthorized") {
-          throw new Error(
-            "Authentication failed: " + (data.message || "Invalid or missing API key") + '. Run "npx xapi-to config set apiKey=<key>" to update your key.'
-          );
-        }
-        if (data?.error === "OAuth Required" || data?.statusCode === 403 && data?.message?.includes("OAuth")) {
-          throw new Error(
-            (data.message || "OAuth authorization required") + '. Run "xapi-to oauth bind" to connect your account.'
-          );
-        }
-      }
-      return body;
-    } catch (e) {
-      if (timedOut) {
-        const timeoutError = new RequestTimeoutError(timeoutMs);
-        if (attempt < retries) {
-          await sleep(backoffDelayMs(attempt));
-          attempt++;
-          continue;
-        }
-        throw timeoutError;
-      }
-      if (isRetryableNetworkError(e) && attempt < retries) {
-        clearTimeout(timer);
-        await sleep(backoffDelayMs(attempt));
-        attempt++;
-        continue;
-      }
-      throw e;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-}
-function headers(apiKey) {
-  const h = { "Content-Type": "application/json" };
-  if (apiKey) h["XAPI-Key"] = apiKey;
-  return h;
-}
-function baseUrl(opts) {
-  return `${scheme(opts.actionHost)}://${opts.actionHost}`;
-}
-async function actionList(opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions`);
-  if (params.page) url.searchParams.set("page", String(params.page));
-  if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
-  if (params.category) url.searchParams.set("category", params.category);
-  if (params.source) url.searchParams.set("source", params.source);
-  if (params.service_id) url.searchParams.set("service_id", params.service_id);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionSearch(query, opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions/search`);
-  url.searchParams.set("q", query);
-  if (params.category) url.searchParams.set("category", params.category);
-  if (params.source) url.searchParams.set("source", params.source);
-  if (params.page) url.searchParams.set("page", String(params.page));
-  if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
-  if (params.include_all_versions) url.searchParams.set("include_all_versions", "true");
-  if (params.sort) url.searchParams.set("sort", params.sort);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionCategories(opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions/categories`);
-  if (params.source) url.searchParams.set("source", params.source);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionGet(id, opts) {
-  return request(
-    `${baseUrl(opts)}/v1/actions/${encodeURIComponent(id)}`,
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function actionBatch(ids, opts) {
-  return request(
-    `${baseUrl(opts)}/v1/actions/batch`,
-    {
-      method: "POST",
-      headers: headers(opts.apiKey),
-      body: JSON.stringify({ ids })
-    },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-    // read-only metadata fetch — safe to retry
-  );
-}
-async function actionCall(actionId, input, opts, httpMethod, retries = 0, timeoutMs = EXECUTE_TIMEOUT_MS) {
-  return request(
-    `${baseUrl(opts)}/v1/actions/execute`,
-    {
-      method: "POST",
-      headers: headers(opts.apiKey),
-      body: JSON.stringify({ action_id: actionId, ...httpMethod ? { method: httpMethod } : {}, input })
-    },
-    Math.min(timeoutMs, EXECUTE_TIMEOUT_MS),
-    retries
-  );
-}
-async function actionStream(actionId, input, opts, httpMethod) {
-  const controller = new AbortController();
-  let timedOut = false;
-  let activeTimeoutMs = EXECUTE_TIMEOUT_MS;
-  let timer;
-  const resetTimeout = (timeoutMs) => {
-    if (timer) clearTimeout(timer);
-    activeTimeoutMs = timeoutMs;
-    timer = setTimeout(() => {
-      timedOut = true;
-      controller.abort();
-    }, timeoutMs);
-  };
-  resetTimeout(EXECUTE_TIMEOUT_MS);
-  const url = `${baseUrl(opts)}/v1/actions/execute`;
-  assertAllowedHost(url);
-  try {
-    const res = await fetch(url, {
-      method: "POST",
-      headers: {
-        ...headers(opts.apiKey),
-        Accept: "text/event-stream"
-      },
-      body: JSON.stringify({
-        action_id: actionId,
-        ...httpMethod ? { method: httpMethod } : {},
-        input,
-        stream: true
-      }),
-      redirect: "manual",
-      signal: controller.signal
-    });
-    if (res.status >= 300 && res.status < 400) {
-      throw new Error(
-        `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
-      );
-    }
-    if (!res.ok) {
-      const text = await res.text();
-      throw new HttpError(
-        res.status,
-        text.slice(0, 300),
-        isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0
-      );
-    }
-    const contentType = res.headers.get("content-type") || "";
-    if (!contentType.toLowerCase().includes("text/event-stream")) {
-      const text = await res.text();
-      throw new Error(
-        `expected an SSE response but received "${contentType || "unknown"}": ${text.slice(0, 300)}`
-      );
-    }
-    if (!res.body) return;
-    const idleTimeoutMs = transferIdleTimeoutMs();
-    resetTimeout(idleTimeoutMs);
-    const source = Readable.fromWeb(res.body);
-    for await (const chunk of source) {
-      resetTimeout(idleTimeoutMs);
-      if (!process.stdout.write(chunk)) await once(process.stdout, "drain");
-    }
-  } catch (error) {
-    if (timedOut) throw new RequestTimeoutError(activeTimeoutMs);
-    throw error;
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-async function actionDownload(actionId, input, opts, outputPath, httpMethod) {
-  const controller = new AbortController();
-  let timedOut = false;
-  let activeTimeoutMs = EXECUTE_TIMEOUT_MS;
-  let timer;
-  const resetTimeout = (timeoutMs) => {
-    if (timer) clearTimeout(timer);
-    activeTimeoutMs = timeoutMs;
-    timer = setTimeout(() => {
-      timedOut = true;
-      controller.abort();
-    }, timeoutMs);
-  };
-  resetTimeout(EXECUTE_TIMEOUT_MS);
-  const target = resolve(outputPath);
-  let file;
-  let complete = false;
-  try {
-    try {
-      file = await open(target, "wx");
-    } catch (error) {
-      if (error?.code === "EEXIST") {
-        throw new Error(`Output file already exists: ${target}`);
-      }
-      throw error;
-    }
-    const url = `${baseUrl(opts)}/v1/actions/execute`;
-    assertAllowedHost(url);
-    const res = await fetch(url, {
-      method: "POST",
-      headers: headers(opts.apiKey),
-      body: JSON.stringify({
-        action_id: actionId,
-        ...httpMethod ? { method: httpMethod } : {},
-        input,
-        response_mode: "raw"
-      }),
-      redirect: "manual",
-      signal: controller.signal
-    });
-    if (res.status >= 300 && res.status < 400) {
-      throw new Error(
-        `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
-      );
-    }
-    if (!res.ok) {
-      const text = await res.text();
-      throw new HttpError(
-        res.status,
-        text.slice(0, 300),
-        isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0
-      );
-    }
-    let bytes = 0;
-    if (res.body) {
-      const idleTimeoutMs = transferIdleTimeoutMs();
-      resetTimeout(idleTimeoutMs);
-      const source = Readable.fromWeb(res.body);
-      const counter = new Transform({
-        transform(chunk, _encoding, callback) {
-          resetTimeout(idleTimeoutMs);
-          bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
-          callback(null, chunk);
-        }
-      });
-      await pipeline(source, counter, file.createWriteStream());
-    } else {
-      await file.close();
-    }
-    complete = true;
-    return {
-      output: target,
-      bytes,
-      contentType: res.headers.get("content-type") || void 0,
-      contentDisposition: res.headers.get("content-disposition") || void 0,
-      status: res.status
-    };
-  } catch (error) {
-    if (timedOut) throw new RequestTimeoutError(activeTimeoutMs);
-    throw error;
-  } finally {
-    if (timer) clearTimeout(timer);
-    if (!complete && file) {
-      await file.close().catch(() => void 0);
-      await rm(target, { force: true }).catch(() => void 0);
-    }
-  }
-}
-async function actionServices(opts, params = {}) {
-  const url = new URL(`${baseUrl(opts)}/v1/actions/services`);
-  if (params.page) url.searchParams.set("page", String(params.page));
-  if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
-  if (params.category) url.searchParams.set("category", params.category);
-  return request(
-    url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function healthCheck(opts) {
-  return request(
-    `${baseUrl(opts)}/health`,
-    { method: "GET", headers: headers(opts.apiKey) },
-    5e3,
-    0
-    // health is a quick connectivity probe — fail fast, don't retry
-  );
-}
-async function loginWithApiKey(apiKey, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/auth/login/apikey`,
-    {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ apiKey })
-    },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-    // auth exchange has no side effect — safe to retry
-  );
-}
-function jwtHeaders(jwtToken) {
-  return { "Content-Type": "application/json", Authorization: `Bearer ${jwtToken}` };
-}
-async function listKeys(jwtToken, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/keys`,
-    { method: "GET", headers: jwtHeaders(jwtToken) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/keys/${keyId}/enable-oauth`,
-    {
-      method: "POST",
-      headers: jwtHeaders(jwtToken),
-      body: JSON.stringify({ plaintextKey })
-    }
-  );
-}
-async function listOAuthProviders(apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/providers`,
-    { method: "GET", headers: { "Content-Type": "application/json" } },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost, scopes) {
-  const body = { apiKeyId, providerId };
-  if (scopes) body.scopes = scopes;
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/authorize`,
-    {
-      method: "POST",
-      headers: jwtHeaders(jwtToken),
-      body: JSON.stringify(body)
-    }
-  );
-}
-async function listOAuthBindings(jwtToken, apiHost) {
-  return request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
-    { method: "GET", headers: jwtHeaders(jwtToken) },
-    DEFAULT_TIMEOUT_MS,
-    IDEMPOTENT_RETRIES
-  );
-}
-async function deleteOAuthBinding(bindingId, jwtToken, apiHost) {
-  const result = await request(
-    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings/${bindingId}`,
-    { method: "DELETE", headers: jwtHeaders(jwtToken) }
-  );
-  return result ?? { success: true };
-}
+import {
+  HttpError,
+  XAPI_API_HOST,
+  XAPI_SANDBOX_HOST,
+  __export,
+  actionBatch,
+  actionCall,
+  actionCategories,
+  actionDownload,
+  actionGet,
+  actionList,
+  actionSearch,
+  actionServices,
+  actionStream,
+  apiKeyApiRequest,
+  assertAllowedHost,
+  deleteOAuthBinding,
+  enableOAuthForKey,
+  err,
+  getApiKeySource,
+  getConfig,
+  getFormat,
+  healthCheck,
+  initiateOAuth,
+  isRetryableRequestError,
+  listKeys,
+  listOAuthBindings,
+  listOAuthProviders,
+  loginWithApiKey,
+  output,
+  request,
+  requireApiKey,
+  sandboxAudit,
+  sandboxCreate,
+  sandboxExec,
+  sandboxExtension,
+  sandboxFileList,
+  sandboxFileRead,
+  sandboxFileWrite,
+  sandboxGet,
+  sandboxHistory,
+  sandboxList,
+  sandboxOfferings,
+  sandboxPort,
+  sandboxQuote,
+  sandboxStateAction,
+  sandboxWait,
+  saveConfig,
+  scheme,
+  showConfig
+} from "./chunk-UEQCIJ7T.js";
 
 // src/codegen.ts
 var TARGET_MAP = {
@@ -730,7 +124,7 @@ function validateHost(host) {
     throw new Error(`invalid actionHost: "${host}" \u2014 must be a valid hostname with optional port`);
   }
 }
-function baseUrl2(actionHost) {
+function baseUrl(actionHost) {
   validateHost(actionHost);
   return `${scheme(actionHost)}://${actionHost}/v1/actions/execute`;
 }
@@ -746,7 +140,7 @@ function shellEscape(s) {
   return s.replace(/'/g, "'\\''");
 }
 function genCurl(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "# Set XAPI_KEY env var or replace with your key",
@@ -757,7 +151,7 @@ function genCurl(params) {
   ].join("\n");
 }
 function genPython(lib, params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const payload = { action_id: params.actionId, ...params.method ? { method: params.method } : {}, input: params.input };
   return [
     `# pip install ${lib}`,
@@ -777,7 +171,7 @@ function genPython(lib, params) {
   ].join("\n");
 }
 function genJavaScriptFetch(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "// Set XAPI_KEY env var or replace with your key",
@@ -793,7 +187,7 @@ function genJavaScriptFetch(params) {
   ].join("\n");
 }
 function genJavaScriptAxios(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "// npm install axios",
@@ -814,7 +208,7 @@ function genJavaScriptAxios(params) {
   ].join("\n");
 }
 function genTypescriptFetch(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   return [
     "// Set XAPI_KEY env var or replace with your key",
@@ -831,7 +225,7 @@ function genTypescriptFetch(params) {
   ].join("\n");
 }
 function genGo(params) {
-  const url = baseUrl2(params.actionHost);
+  const url = baseUrl(params.actionHost);
   const body = jsonBody(params.actionId, params.input, params.method);
   const escaped = body.replace(/`/g, '` + "`" + `');
   return [
@@ -1152,7 +546,8 @@ async function actionSearch2(args, flags) {
       category: flags.category,
       page: positiveIntegerFlag(flags.page, "--page"),
       page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
-      include_all_versions: flags["include-all-versions"] === "true",
+      // Backward-compatible aliases from the original feature branch.
+      include_all_versions: ["include-all-versions", "all-versions", "include-history"].some((name) => flags[name] === "true"),
       sort: requestedSort
     });
     if (requestedSort && res.sort !== requestedSort) {
@@ -1339,7 +734,7 @@ __export(config_exports, {
   configSet: () => configSet,
   configShow: () => configShow
 });
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync } from "fs";
 var CONFIG_HELP = `xapi-to config - Manage CLI configuration
 
 USAGE
@@ -1382,7 +777,7 @@ async function configSet(args, flags) {
     if (key !== "apiKey") err(`unknown config key: ${key} (only apiKey is configurable)`);
     let value = arg.slice(eq + 1);
     if (value === "-") {
-      value = readFileSync2(0, "utf-8").trim();
+      value = readFileSync(0, "utf-8").trim();
     }
     if (!value) err("apiKey is empty");
     updates.apiKey = value;
@@ -1576,43 +971,240 @@ async function balance(args, flags) {
   }
 }
 
-// src/commands/oauth.ts
-var oauth_exports = {};
-__export(oauth_exports, {
-  OAUTH_HELP: () => OAUTH_HELP,
-  oauthBind: () => oauthBind,
-  oauthProviders: () => oauthProviders,
-  oauthStatus: () => oauthStatus,
-  oauthUnbind: () => oauthUnbind,
-  pollForBinding: () => pollForBinding
-});
-import { spawnSync } from "child_process";
-function openBrowser(url) {
-  const cmd = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
-  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
-  try {
-    spawnSync(cmd, args, { stdio: "ignore" });
-  } catch {
+// src/commands/usage.ts
+var READ_RETRIES = 2;
+var USAGE_HELP = `xapi-to usage - Read a finalized request cost receipt
+
+USAGE
+  xapi-to usage <request-id> [--format json|pretty|table]
+  xapi-to usage wait <request-id> [--interval 1s] [--timeout 30s]
+
+Use the request ID returned in X-XAPI-Request-Id or the final xapi.usage SSE event.
+The receipt is visible only to the API key that made the request.
+
+"usage wait" polls through the normal finalization window. A 404 means the
+receipt is not finalized yet; invalid credentials and other permanent errors
+still fail immediately.
+`;
+function parsePositiveDurationMs(raw, flagName) {
+  const match = raw.trim().toLowerCase().match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match) {
+    err(`${flagName} must be a duration such as 500ms, 2s, 5m, or 1h`);
+  }
+  const value = Number(match[1]);
+  const unit = match[2] || "ms";
+  const multiplier = unit === "h" ? 36e5 : unit === "m" ? 6e4 : unit === "s" ? 1e3 : 1;
+  const result = value * multiplier;
+  if (!Number.isSafeInteger(result) || result <= 0) {
+    err(`${flagName} must be greater than 0`);
   }
+  return result;
 }
-function bindingChangedAfter(binding, startedAtMs, existingBindingIds) {
-  const changedAt = Date.parse(binding.updatedAt || binding.createdAt || "");
-  if (!Number.isFinite(changedAt)) return !existingBindingIds.has(binding.id);
-  return changedAt >= startedAtMs;
+function sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
-async function pollForBinding(apiKeyId, providerId, jwtToken, startedAt, existingBindingIds = /* @__PURE__ */ new Set(), timeoutMs = 5 * 60 * 1e3, intervalMs = 3e3) {
-  const deadline = Date.now() + timeoutMs;
-  const isTTY = process.stdout.isTTY;
-  const startedAtMs = startedAt.getTime() - 5e3;
-  while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, intervalMs));
+function receiptUrl(requestId) {
+  return `${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/usage/requests/${encodeURIComponent(requestId)}`;
+}
+async function fetchReceipt(requestId, apiKey, timeoutMs, retries) {
+  return request(
+    receiptUrl(requestId),
+    {
+      method: "GET",
+      headers: { "XAPI-KEY": apiKey }
+    },
+    timeoutMs,
+    retries
+  );
+}
+async function waitForReceipt(requestId, apiKey, flags) {
+  const intervalMs = parsePositiveDurationMs(flags.interval || "1s", "--interval");
+  const timeoutMs = parsePositiveDurationMs(flags.timeout || "30s", "--timeout");
+  const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
+  while (true) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      err(
+        "usage receipt wait timeout",
+        `request_id=${requestId}, elapsed_ms=${Date.now() - startedAt}, timeout_ms=${timeoutMs}`
+      );
+    }
     try {
-      const bindings = await listOAuthBindings(jwtToken, XAPI_API_HOST);
-      const match = Array.isArray(bindings) ? bindings.find(
-        (b) => b.apiKeyId === apiKeyId && b.providerId === providerId && bindingChangedAfter(b, startedAtMs, existingBindingIds)
-      ) : null;
-      if (match) return match;
-    } catch {
+      return await fetchReceipt(requestId, apiKey, remainingMs, 0);
+    } catch (e) {
+      const pending = e instanceof HttpError && e.status === 404;
+      if (!pending && !isRetryableRequestError(e)) throw e;
+    }
+    await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+  }
+}
+async function usage(args, flags) {
+  if (flags.help) {
+    console.log(USAGE_HELP);
+    return;
+  }
+  const shouldWait = args[0] === "wait";
+  const requestId = args[shouldWait ? 1 : 0]?.trim();
+  if (!requestId) {
+    err(
+      "request ID required",
+      shouldWait ? "Run: xapi-to usage wait <request-id>" : "Run: xapi-to usage <request-id>"
+    );
+  }
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  try {
+    const result = shouldWait ? await waitForReceipt(requestId, cfg.apiKey, flags) : await fetchReceipt(requestId, cfg.apiKey, 3e4, READ_RETRIES);
+    output(result, flags.format);
+  } catch (e) {
+    err(
+      shouldWait ? "usage receipt wait failed" : "usage receipt fetch failed",
+      e.message
+    );
+  }
+}
+
+// src/commands/earnings.ts
+var READ_RETRIES2 = 2;
+var EARNINGS_HELP = `xapi-to earnings - Inspect and reinvest provider earnings
+
+USAGE
+  xapi-to earnings [summary] [--format json|pretty|table]
+  xapi-to earnings list [--status PENDING|SETTLED] [--limit 20] [--cursor <id>]
+  xapi-to earnings transfer <amount> --idempotency-key <key>
+
+SCOPES
+  summary/list  earnings:read
+  transfer      earnings:transfer
+
+The transfer is one-way: settled provider earnings become spendable xapi balance.
+Reuse the same idempotency key only when retrying the same amount.
+`;
+function baseUrl2() {
+  return `${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/agent`;
+}
+function keyHeaders(apiKey) {
+  return { "Content-Type": "application/json", "XAPI-KEY": apiKey };
+}
+async function earnings(args, flags) {
+  if (flags.help) {
+    console.log(EARNINGS_HELP);
+    return;
+  }
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey;
+  const subcommand = args[0] ?? "summary";
+  try {
+    if (subcommand === "summary") {
+      const result = await request(
+        `${baseUrl2()}/economy`,
+        { method: "GET", headers: keyHeaders(apiKey) },
+        3e4,
+        READ_RETRIES2
+      );
+      output(result, flags.format);
+      return;
+    }
+    if (subcommand === "list") {
+      const url = new URL(`${baseUrl2()}/earnings`);
+      if (flags.status) {
+        const status = flags.status.toUpperCase();
+        if (!["PENDING", "SETTLED"].includes(status)) {
+          err("invalid earnings status", "Expected PENDING or SETTLED.");
+        }
+        url.searchParams.set("status", status);
+      }
+      if (flags.limit) {
+        const limit = Number(flags.limit);
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+          err("invalid earnings limit", "Expected an integer from 1 to 100.");
+        }
+        url.searchParams.set("limit", String(limit));
+      }
+      if (flags.cursor) url.searchParams.set("cursor", flags.cursor);
+      const result = await request(
+        url.toString(),
+        { method: "GET", headers: keyHeaders(apiKey) },
+        3e4,
+        READ_RETRIES2
+      );
+      output(result, flags.format);
+      return;
+    }
+    if (subcommand === "transfer") {
+      const amount = Number(args[1]);
+      if (!Number.isFinite(amount) || amount <= 0) {
+        err("invalid transfer amount", "Pass a positive USD amount.");
+      }
+      const idempotencyKey = flags["idempotency-key"] || flags.idempotencyKey;
+      if (!idempotencyKey) {
+        err(
+          "idempotency key required",
+          "Pass --idempotency-key <stable-key> and reuse it only when retrying this same transfer."
+        );
+      }
+      const result = await request(
+        `${baseUrl2()}/earnings/transfer`,
+        {
+          method: "POST",
+          headers: keyHeaders(apiKey),
+          body: JSON.stringify({ amount, idempotencyKey })
+        },
+        3e4,
+        // The server binds the idempotency key to the amount, so transport retries are safe.
+        READ_RETRIES2
+      );
+      output(result, flags.format);
+      return;
+    }
+    err(
+      `unknown earnings command: ${subcommand}`,
+      "Valid commands: summary, list, transfer."
+    );
+  } catch (e) {
+    err("earnings request failed", e.message);
+  }
+}
+
+// src/commands/oauth.ts
+var oauth_exports = {};
+__export(oauth_exports, {
+  OAUTH_HELP: () => OAUTH_HELP,
+  oauthBind: () => oauthBind,
+  oauthProviders: () => oauthProviders,
+  oauthStatus: () => oauthStatus,
+  oauthUnbind: () => oauthUnbind,
+  pollForBinding: () => pollForBinding
+});
+import { spawnSync } from "child_process";
+function openBrowser(url) {
+  const cmd = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+  try {
+    spawnSync(cmd, args, { stdio: "ignore" });
+  } catch {
+  }
+}
+function bindingChangedAfter(binding, startedAtMs, existingBindingIds) {
+  const changedAt = Date.parse(binding.updatedAt || binding.createdAt || "");
+  if (!Number.isFinite(changedAt)) return !existingBindingIds.has(binding.id);
+  return changedAt >= startedAtMs;
+}
+async function pollForBinding(apiKeyId, providerId, jwtToken, startedAt, existingBindingIds = /* @__PURE__ */ new Set(), timeoutMs = 5 * 60 * 1e3, intervalMs = 3e3) {
+  const deadline = Date.now() + timeoutMs;
+  const isTTY = process.stdout.isTTY;
+  const startedAtMs = startedAt.getTime() - 5e3;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    try {
+      const bindings = await listOAuthBindings(jwtToken, XAPI_API_HOST);
+      const match = Array.isArray(bindings) ? bindings.find(
+        (b) => b.apiKeyId === apiKeyId && b.providerId === providerId && bindingChangedAfter(b, startedAtMs, existingBindingIds)
+      ) : null;
+      if (match) return match;
+    } catch {
     }
     if (isTTY) {
       const remaining = Math.ceil((deadline - Date.now()) / 1e3);
@@ -1644,11 +1236,11 @@ async function findCurrentKeyRecord(plaintextKey, jwtToken) {
     `Current API key (${prefix}...) was not found in your account keys. Run "xapi-to config set apiKey=<key>" with a valid key before binding OAuth.`
   );
 }
-function resolveScopeDefs(provider) {
-  if (Array.isArray(provider.scopeDefinitions) && provider.scopeDefinitions.length > 0) {
-    return provider.scopeDefinitions;
+function resolveScopeDefs(provider2) {
+  if (Array.isArray(provider2.scopeDefinitions) && provider2.scopeDefinitions.length > 0) {
+    return provider2.scopeDefinitions;
   }
-  const raw = (provider.defaultScopes || "").split(/[\s,]+/).filter(Boolean);
+  const raw = (provider2.defaultScopes || "").split(/[\s,]+/).filter(Boolean);
   return raw.map((s) => ({
     scope: s,
     label: s,
@@ -1657,21 +1249,21 @@ function resolveScopeDefs(provider) {
     category: ""
   }));
 }
-async function selectScopesInteractive(provider) {
-  const defs = resolveScopeDefs(provider);
+async function selectScopesInteractive(provider2) {
+  const defs = resolveScopeDefs(provider2);
   if (defs.length === 0) return "";
-  const required = defs.filter((d) => d.required);
+  const required3 = defs.filter((d) => d.required);
   const optional = defs.filter((d) => !d.required);
   const selected = new Set(defs.map((d) => d.scope));
   if (optional.length === 0) {
-    return required.map((d) => d.scope).join(" ");
+    return required3.map((d) => d.scope).join(" ");
   }
   const out = process.stderr;
   let cursor = 0;
   const hint = "  \u2191\u2193 navigate \xB7 space toggle \xB7 a all \xB7 n none \xB7 enter confirm";
   const buildFrame = () => {
     const lines = [];
-    for (const d of required) {
+    for (const d of required3) {
       const desc = d.description ? ` \u2014 ${d.description}` : "";
       lines.push(`    \x1B[2m[*] ${d.label}${desc} (required)\x1B[0m`);
     }
@@ -1694,7 +1286,7 @@ async function selectScopesInteractive(provider) {
     out.write("\x1B[J");
     out.write(buildFrame());
   };
-  return new Promise((resolve2) => {
+  return new Promise((resolve4) => {
     const { stdin } = process;
     const wasRaw = stdin.isRaw;
     stdin.setRawMode(true);
@@ -1705,7 +1297,7 @@ async function selectScopesInteractive(provider) {
       stdin.pause();
       out.write("\x1B[?25h");
       out.write("\n");
-      resolve2(result);
+      resolve4(result);
     };
     const onData = (buf) => {
       const key = buf.toString();
@@ -1784,10 +1376,10 @@ async function oauthBind(args, flags) {
     if (!Array.isArray(providers) || providers.length === 0) {
       throw new Error("No OAuth providers available");
     }
-    const provider = providers.find(
+    const provider2 = providers.find(
       (p) => p.type.toLowerCase() === providerName || p.name.toLowerCase().includes(providerName)
     );
-    if (!provider) {
+    if (!provider2) {
       const available = providers.map((p) => p.type).join(", ");
       throw new Error(
         `Provider "${providerName}" not found. Available: ${available}`
@@ -1801,13 +1393,13 @@ async function oauthBind(args, flags) {
     if (flags.scopes) {
       scopes = flags.scopes;
     } else if (isTTY) {
-      const defs = resolveScopeDefs(provider);
+      const defs = resolveScopeDefs(provider2);
       if (defs.length > 0) {
         console.error(`
-  Provider : ${provider.name}`);
+  Provider : ${provider2.name}`);
         console.error(`  API Key  : ${keyRecord.keyPreview}`);
         headerPrinted = true;
-        scopes = await selectScopesInteractive(provider) || void 0;
+        scopes = await selectScopesInteractive(provider2) || void 0;
       }
     }
     const existingBindingIds = /* @__PURE__ */ new Set();
@@ -1816,7 +1408,7 @@ async function oauthBind(args, flags) {
         const existingBindings = await listOAuthBindings(jwtToken, XAPI_API_HOST);
         if (Array.isArray(existingBindings)) {
           for (const binding of existingBindings) {
-            if (binding.apiKeyId === keyRecord.id && binding.providerId === provider.id) {
+            if (binding.apiKeyId === keyRecord.id && binding.providerId === provider2.id) {
               existingBindingIds.add(binding.id);
             }
           }
@@ -1825,7 +1417,7 @@ async function oauthBind(args, flags) {
       }
     }
     const authorizationStartedAt = /* @__PURE__ */ new Date();
-    const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST, scopes);
+    const result = await initiateOAuth(keyRecord.id, provider2.id, jwtToken, XAPI_API_HOST, scopes);
     const { authorizationUrl } = result;
     let authorizationTarget;
     try {
@@ -1840,7 +1432,7 @@ async function oauthBind(args, flags) {
     if (isTTY) {
       if (!headerPrinted) {
         console.error(`
-  Provider : ${provider.name}`);
+  Provider : ${provider2.name}`);
         console.error(`  API Key  : ${keyRecord.keyPreview}`);
       }
       if (scopes) {
@@ -1855,7 +1447,7 @@ async function oauthBind(args, flags) {
       console.error("  Waiting for you to complete authorization in the browser...\n");
       const binding = await pollForBinding(
         keyRecord.id,
-        provider.id,
+        provider2.id,
         jwtToken,
         authorizationStartedAt,
         existingBindingIds
@@ -1866,14 +1458,14 @@ async function oauthBind(args, flags) {
         console.error(`
   Authorization complete! Bound to @${account}
 `);
-        output({ status: "success", provider: provider.name, account, scopes }, flags.format);
+        output({ status: "success", provider: provider2.name, account, scopes }, flags.format);
       } else {
         err("oauth bind timed out", 'Authorization was not completed within 5 minutes. Run "xapi-to oauth bind" again.');
       }
     } else {
       output({
         status: "pending",
-        provider: provider.name,
+        provider: provider2.name,
         apiKey: keyRecord.keyPreview,
         authorizationUrl,
         scopes
@@ -2009,7 +1601,7 @@ function parseDurationMs(raw) {
       return value;
   }
 }
-function parsePositiveDurationMs(raw, flagName) {
+function parsePositiveDurationMs2(raw, flagName) {
   const ms = parseDurationMs(raw);
   if (ms <= 0) {
     err(`${flagName} must be greater than 0`);
@@ -2025,7 +1617,7 @@ function parsePositiveInt(raw, flagName) {
 }
 function sleep2(ms) {
   if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 function extractTaskPayload(res) {
   if (res && typeof res === "object") {
@@ -2063,7 +1655,7 @@ async function taskWait(args, flags) {
   showHelpIfRequested2(flags, WAIT_HELP);
   const taskId = args[0];
   if (!taskId) err("usage: xapi-to task wait <task_id>");
-  const intervalMs = parsePositiveDurationMs(flags.interval || "2s", "--interval");
+  const intervalMs = parsePositiveDurationMs2(flags.interval || "2s", "--interval");
   const timeoutMs = flags.timeout ? parseDurationMs(flags.timeout) : void 0;
   const maxAttempts = flags["max-attempts"] ? parsePositiveInt(flags["max-attempts"], "--max-attempts") : void 0;
   const cfg = getConfig();
@@ -2127,6 +1719,1400 @@ function taskHelp() {
   return TASK_HELP;
 }
 
+// src/commands/sandbox.ts
+import { randomUUID } from "crypto";
+import { readFile, open, rm } from "fs/promises";
+import { resolve } from "path";
+var SANDBOX_HELP = `xapi-to sandbox - Managed, auditable cloud sandboxes
+
+USAGE
+  xapi-to sandbox <command> [args] [flags]
+
+QUICK START
+  sandbox run --command <shell>     Quote, create, wait, execute, and terminate
+  sandbox run -- <command...>       Positional shorthand after a bare --
+
+LIFECYCLE
+  offerings                         List available provider offerings
+  quote                             Quote requirements without creating
+  list                              List sandbox instances
+  history                           Search paginated instance history
+  get <id>                          Get instance state, usage, and cost
+  create                            Create from a quote, offering, or requirements
+  wait <id>                         Wait for a state (default: RUNNING)
+  exec <id> --command <shell>       Execute a shell command
+  suspend|resume|terminate <id>     Change state and wait for completion
+
+FILES, PORTS, AUDIT
+  file write <id> <remote> --file <local>
+  file write <id> <remote> --content <text>
+  file read <id> <remote> [--output <local>]
+  file list <id> [--path <remote>] [--depth N]
+  port <id> <port>                  Get a public URL for a listening port
+  extension <id> <extension-id>     Invoke an offering-declared extension
+  audit <id> [--kind operations|events|usageSegments|billingPeriods]
+
+SELECTION FLAGS
+  --provider auto|daytona|cf-edge|e2b|runpod|runloop|modal|vc-sandbox|fly|blaxel|cubesandbox
+                                      Pin a provider gateway (default: auto)
+  --capabilities exec,files,ports   Required capabilities
+  --cpu N  --memory N  --volume N  Minimum resources
+  --gpu-count N  --gpu-model NAME   GPU requirements
+  --regions a,b                     Allowed regions
+  --min-runtime 24h                 Minimum documented continuous runtime
+  --requirements <json>             Complete requirements object
+  --max-hourly-usd N                Price ceiling (sandbox run default: 0.20)
+
+COMMON FLAGS
+  --host <sandbox.xapi.to>          Override gateway; must be *.xapi.to/localhost
+  --wait-timeout 5m                 State wait timeout (default: 5m)
+  --interval 2s                     State polling interval (default: 2s)
+  --format json|pretty|table        Output format
+
+HISTORY FLAGS
+  --state ALL|ACTIVE|HISTORY|RUNNING|SUSPENDED|TERMINATED|FAILED
+  --search <text>  --from <ISO time>  --to <ISO time>
+  --page N  --page-size N           Pagination (page size: 1-100)
+
+SAFETY
+  sandbox run terminates in finally, including command failure. Use --keep only
+  when you intentionally want billing to continue after the CLI exits.
+
+EXAMPLES
+  xapi-to sandbox offerings --format table
+  xapi-to sandbox quote --capabilities exec,files --max-hourly-usd 0.20
+  xapi-to sandbox run --command 'python3 -c "print(6*7)"'
+  xapi-to sandbox run --provider cf-edge --capabilities exec,files,ports --command 'pwd'
+  xapi-to sandbox exec <id> -- npm test
+  xapi-to sandbox extension <id> runpod.connection_info --input '{}'
+  xapi-to sandbox terminate <id>
+`;
+var SANDBOX_COMMAND_HELP = {
+  offerings: `USAGE
+  xapi-to sandbox offerings [--provider NAME] [--format json|pretty|table]
+
+Lists current resources, capabilities, lifecycle support, and hourly prices.
+This command does not create or bill an instance.`,
+  quote: `USAGE
+  xapi-to sandbox quote [selection flags] [--max-hourly-usd N]
+
+SELECTION
+  --capabilities exec,files,ports   Required capabilities
+  --cpu N  --memory N  --volume N  Minimum resources
+  --gpu-count N  --gpu-model NAME   GPU requirements
+  --regions a,b                     Allowed regions
+  --min-runtime 24h                 Minimum documented continuous runtime
+  --requirements <json>             Complete requirements object
+  --max-hourly-usd N                Hard hourly price ceiling
+
+Returns a short-lived quote without creating or billing an instance.`,
+  list: `USAGE
+  xapi-to sandbox list [--provider NAME] [--format json|pretty|table]
+
+Lists current Sandbox instances visible to the configured xAPI key.`,
+  history: `USAGE
+  xapi-to sandbox history [--state STATE] [--search TEXT] [--from ISO] [--to ISO]
+    [--page N] [--page-size 1-100] [--format json|pretty|table]
+
+Searches current and historical Sandbox instances with server-side pagination.`,
+  get: `USAGE
+  xapi-to sandbox get <id> [--format json|pretty|table]
+
+Returns current state, operations, usage, billing, and service-calculated cost.`,
+  create: `USAGE
+  xapi-to sandbox create [selection flags] [--max-hourly-usd N] [--wait]
+
+SELECTION MODES
+  --quote-id ID                      Create from an existing quote
+  --offering-id ID                   Create an exact offering (cannot use a price ceiling)
+  --requirements <json>              Create from requirements
+  --capabilities/--cpu/--memory/...  Requirements shortcuts
+
+CONTROL
+  --idempotency-key KEY              Stable retry key; generated and returned if omitted
+  --metadata <json>                  Instance metadata
+  --resume-on-access                 Request automatic resume on supported providers
+  --wait                             Wait until RUNNING
+  --wait-timeout 5m  --interval 2s   Polling controls
+
+On a wait failure, the error includes the instance ID and recovery instructions.`,
+  wait: `USAGE
+  xapi-to sandbox wait <id> [--state RUNNING[,STATE]]
+    [--wait-timeout 5m] [--interval 2s]
+
+State names are case-insensitive and validated before polling.`,
+  exec: `USAGE
+  xapi-to sandbox exec <id> --command <shell> [--cwd PATH] [--timeout SECONDS]
+    [--background]
+  xapi-to sandbox exec <id> -- <command...>
+
+Executes a command and maps a remote non-zero exit code to the local process.
+--background requires offering.capabilities.backgroundExec=true and returns a
+provider-managed session immediately; use it for long-running Web servers.`,
+  file: `USAGE
+  xapi-to sandbox file write <id> <remote> (--file <local>|--content <text>)
+  xapi-to sandbox file read <id> <remote> [--output <local>]
+  xapi-to sandbox file list <id> [--path <remote>] [--depth N]
+
+Binary local files are transferred as base64. --output never overwrites a file.`,
+  port: `USAGE
+  xapi-to sandbox port <id> <1-65535>
+
+Returns the provider's temporary public URL for a listening instance port.`,
+  extension: `USAGE
+  xapi-to sandbox extension <id> <extension-id> [--input <json>]
+    [--idempotency-key KEY]
+
+Invoke only extension IDs declared by the selected offering.`,
+  audit: `USAGE
+  xapi-to sandbox audit <id> [--kind operations|events|usageSegments|billingPeriods]
+    [--page N] [--page-size 1-100] [--format json|pretty|table]`,
+  suspend: `USAGE
+  xapi-to sandbox suspend <id> [--no-wait] [--idempotency-key KEY]
+    [--wait-timeout 5m] [--interval 2s]
+
+Check offering lifecycle support before suspending; storage may continue billing.`,
+  resume: `USAGE
+  xapi-to sandbox resume <id> [--no-wait] [--idempotency-key KEY]
+    [--wait-timeout 5m] [--interval 2s]`,
+  terminate: `USAGE
+  xapi-to sandbox terminate <id> [--no-wait] [--idempotency-key KEY]
+    [--wait-timeout 5m] [--interval 2s]
+
+Waits for TERMINATED or FAILED by default.`,
+  run: `USAGE
+  xapi-to sandbox run --command <shell> [selection flags] [run flags]
+  xapi-to sandbox run [selection flags] -- <command...>
+
+RUN FLAGS
+  --max-hourly-usd N                Hard ceiling (default: 0.20)
+  --timeout SECONDS                 Remote command timeout (default: 60)
+  --cwd PATH                        Remote working directory
+  --metadata <json>                 Instance metadata for audit correlation
+  --idempotency-key KEY             Stable create retry key
+  --wait-timeout 5m  --interval 2s  Lifecycle polling controls
+  --keep                            Keep the instance running and billing
+
+Runs quote -> create -> wait -> exec -> terminate. Cleanup also runs after
+command failure, SIGINT, or SIGTERM.`
+};
+var COMMON_FLAGS = ["help", "host", "provider", "format"];
+var SELECTION_FLAGS = [
+  "capabilities",
+  "cpu",
+  "memory",
+  "volume",
+  "gpu-count",
+  "gpu-model",
+  "regions",
+  "min-runtime",
+  "requirements",
+  "max-hourly-usd"
+];
+var POLL_FLAGS = ["wait-timeout", "interval"];
+function help(flags, command) {
+  if (flags.help) {
+    console.log(`xapi-to sandbox ${command}
+
+${SANDBOX_COMMAND_HELP[command]}
+
+COMMON
+  --host HOST  --provider NAME  --format json|pretty|table  --help`);
+    process.exit(0);
+  }
+}
+function validateFlags(flags, command, allowed = []) {
+  const valid = /* @__PURE__ */ new Set([...COMMON_FLAGS, ...allowed]);
+  const unknown = Object.keys(flags).filter((flag) => !valid.has(flag));
+  if (unknown.length) {
+    err(`unknown flag${unknown.length > 1 ? "s" : ""} for sandbox ${command}: ${unknown.map((flag) => `--${flag}`).join(", ")}`, {
+      hint: `run xapi-to sandbox ${command} --help`,
+      validFlags: [...valid].sort().map((flag) => `--${flag}`)
+    });
+  }
+  if (flags.format && !["json", "pretty", "table"].includes(flags.format)) {
+    err("--format must be one of: json, pretty, table");
+  }
+}
+function collection(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.items)) return data.items;
+  if (Array.isArray(data?.data)) return data.data;
+  return data ? [data] : [];
+}
+function capability(value, name) {
+  const enabled = value?.capabilities?.[name];
+  return enabled === true ? "yes" : enabled === false ? "no" : "";
+}
+function sandboxTableRows(view, data) {
+  if (view === "offerings") {
+    return collection(data).map((item) => ({
+      id: item.id,
+      name: item.name,
+      cpu: item.resources?.cpu,
+      memoryGiB: item.resources?.memoryGiB,
+      volumeGiB: item.resources?.volumeGiB,
+      gpu: Array.isArray(item.resources?.gpu) ? item.resources.gpu.map((gpu) => `${gpu.count || 1}x ${gpu.model || "GPU"}`).join(", ") : "",
+      exec: capability(item, "exec"),
+      background: capability(item, "backgroundExec"),
+      files: capability(item, "files"),
+      ports: capability(item, "ports"),
+      suspend: item.lifecycle?.suspension?.supported === true ? "yes" : "no",
+      hourlyUsd: item.billing?.estimatedHourlyUsdByState?.RUNNING,
+      extensions: Array.isArray(item.capabilities?.extensionIds) ? item.capabilities.extensionIds.join(",") : ""
+    }));
+  }
+  if (view === "quote") {
+    return collection(data).map((item) => ({
+      quoteId: item.quoteId || item.id,
+      offeringId: item.offeringId || item.offering?.id,
+      offering: item.offering?.name || item.offeringName,
+      provider: item.provider?.name || item.providerName || item.provider,
+      hourlyUsd: item.estimatedHourlyUsd || item.hourlyUsd || item.offering?.billing?.estimatedHourlyUsdByState?.RUNNING,
+      expiresAt: item.expiresAt
+    }));
+  }
+  if (view === "run") {
+    return collection(data).map((item) => ({
+      instanceId: item.instanceId,
+      provider: item.provider,
+      offering: item.offering?.name || item.offering,
+      exitCode: item.result?.exitCode,
+      finalState: item.finalState,
+      cleanup: item.cleanup?.state || (item.cleanup?.kept ? "KEPT" : ""),
+      totalCost: item.totalCost
+    }));
+  }
+  return collection(data).map((item) => ({
+    id: item.id || item.instanceId,
+    state: item.observedState || item.state || item.finalState,
+    desiredState: item.desiredState,
+    offering: item.offering?.name || item.offeringName || item.offeringId,
+    provider: item.provider?.name || item.providerName || item.provider,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    totalCost: item.totalCost
+  }));
+}
+function sandboxOutput(view, data, flags) {
+  const format = flags.format || getFormat();
+  if (format === "table") {
+    output(sandboxTableRows(view, data), "table");
+    return;
+  }
+  output(data, flags.format);
+}
+function flagValue(flags, name) {
+  const value = flags[name];
+  if (value === "true") err(`--${name} requires a value`);
+  return value;
+}
+function booleanFlag(flags, name) {
+  const raw = flags[name];
+  if (raw === void 0 || raw === "false") return false;
+  if (raw === "true") return true;
+  err(`--${name} must be a boolean flag or --${name}=true|false`);
+}
+function positiveNumber(raw, name) {
+  if (raw === void 0) return void 0;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) err(`--${name} must be a positive number`);
+  return value;
+}
+function positiveInteger(raw, name) {
+  const value = positiveNumber(raw, name);
+  if (value !== void 0 && !Number.isInteger(value)) err(`--${name} must be a positive integer`);
+  return value;
+}
+function durationMs(raw, fallback, name) {
+  if (raw === void 0) return fallback;
+  if (raw === "true") err(`--${name} requires a value`);
+  const match = raw.trim().toLowerCase().match(/^(\d+)(ms|s|m|h|d)?$/);
+  if (!match || Number(match[1]) <= 0) err(`--${name} must be a duration like 500ms, 2s, 5m, 1h, or 1d`);
+  const value = Number(match[1]);
+  return value * { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5 }[match[2] || "ms"];
+}
+function jsonObject(raw, name) {
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected an object");
+    return value;
+  } catch (error) {
+    err(`--${name} must be a valid JSON object`, error.message);
+  }
+}
+function csv(raw) {
+  if (!raw) return void 0;
+  return raw.split(",").map((value) => value.trim()).filter(Boolean);
+}
+function sandboxOptions(flags) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const host = flagValue(flags, "host") || cfg.sandboxHost || XAPI_SANDBOX_HOST;
+  const provider2 = flagValue(flags, "provider");
+  return { sandboxHost: host, apiKey: cfg.apiKey, ...provider2 ? { provider: provider2 } : {} };
+}
+function requirementsFromFlags(flags, defaultCapabilities) {
+  const requirements = flagValue(flags, "requirements") ? jsonObject(flagValue(flags, "requirements"), "requirements") : {};
+  const capabilities = csv(flagValue(flags, "capabilities")) || (Array.isArray(requirements.capabilities) ? void 0 : defaultCapabilities);
+  const regions = csv(flagValue(flags, "regions"));
+  const cpu = positiveNumber(flagValue(flags, "cpu"), "cpu");
+  const memory = positiveNumber(flagValue(flags, "memory"), "memory");
+  const volume = positiveNumber(flagValue(flags, "volume"), "volume");
+  const gpuCount = positiveInteger(flagValue(flags, "gpu-count"), "gpu-count");
+  const gpuModel = flagValue(flags, "gpu-model");
+  const minRuntime = flagValue(flags, "min-runtime");
+  if (gpuModel && gpuCount === void 0 && !(Number(requirements.gpu?.count) > 0)) {
+    err("--gpu-model requires --gpu-count (or requirements.gpu.count)");
+  }
+  if (capabilities?.length) requirements.capabilities = capabilities;
+  if (regions?.length) requirements.regions = regions;
+  if (cpu !== void 0) requirements.cpu = { ...requirements.cpu || {}, min: cpu };
+  if (memory !== void 0) requirements.memoryGiB = { ...requirements.memoryGiB || {}, min: memory };
+  if (volume !== void 0) requirements.volumeGiB = { ...requirements.volumeGiB || {}, min: volume };
+  if (gpuCount !== void 0 || gpuModel) {
+    requirements.gpu = {
+      ...requirements.gpu || {},
+      ...gpuCount !== void 0 ? { count: gpuCount } : {},
+      ...gpuModel ? { model: gpuModel } : {}
+    };
+  }
+  if (minRuntime !== void 0) {
+    requirements.minContinuousRuntimeSeconds = Math.ceil(
+      durationMs(minRuntime, 0, "min-runtime") / 1e3
+    );
+  }
+  return requirements;
+}
+function quoteBody(flags, defaultCapabilities) {
+  const max = positiveNumber(flagValue(flags, "max-hourly-usd"), "max-hourly-usd");
+  return {
+    requirements: requirementsFromFlags(flags, defaultCapabilities),
+    ...max !== void 0 ? { maxEstimatedHourlyUsd: max.toFixed(8) } : {}
+  };
+}
+function createDefaultCapabilities(flags) {
+  if (flagValue(flags, "requirements") || flagValue(flags, "provider") === "runpod" || flagValue(flags, "gpu-count") || flagValue(flags, "gpu-model")) return void 0;
+  return ["exec"];
+}
+function waitSettings(flags) {
+  return {
+    timeoutMs: durationMs(flags["wait-timeout"], 3e5, "wait-timeout"),
+    intervalMs: durationMs(flags.interval, 2e3, "interval")
+  };
+}
+function commandFrom(args, flags, usage2) {
+  const fromFlag = flagValue(flags, "command");
+  const command = fromFlag ?? args.join(" ");
+  if (!command.trim()) err(usage2);
+  return command;
+}
+function instanceId(args, usage2) {
+  if (!args[0]) err(usage2);
+  return args[0];
+}
+async function terminateAndWait(opts, id, flags) {
+  const { timeoutMs, intervalMs } = waitSettings(flags);
+  const deadline = Date.now() + timeoutMs;
+  const clientIdempotencyKey = flagValue(flags, "idempotency-key") || `cli:terminate:${randomUUID()}`;
+  let operation;
+  while (Date.now() < deadline) {
+    const detail2 = await sandboxGet(opts, id);
+    if (["TERMINATED", "FAILED"].includes(String(detail2.observedState))) {
+      return { operation, sandbox: detail2, clientIdempotencyKey };
+    }
+    try {
+      operation = await sandboxStateAction(opts, id, "terminate", {
+        idempotencyKey: clientIdempotencyKey
+      });
+      break;
+    } catch (error) {
+      if (!(error instanceof HttpError) || error.status !== 409) throw error;
+      await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
+    }
+  }
+  const remaining = Math.max(1, deadline - Date.now());
+  let detail;
+  try {
+    detail = await sandboxWait(opts, id, ["TERMINATED", "FAILED"], remaining, intervalMs);
+  } catch (error) {
+    if (!(error instanceof HttpError) || error.status !== 404 || !opts.provider) throw error;
+    detail = await sandboxWait(
+      { ...opts, provider: void 0 },
+      id,
+      ["TERMINATED", "FAILED"],
+      Math.max(1, deadline - Date.now()),
+      intervalMs
+    );
+  }
+  return { operation, sandbox: detail, clientIdempotencyKey };
+}
+function cleanupSummary(cleanup) {
+  if (!cleanup) return void 0;
+  if (cleanup.error) return { error: cleanup.error };
+  return {
+    operationId: cleanup.operation?.id,
+    operationStatus: cleanup.sandbox?.operations?.find?.((item) => item.type === "TERMINATE")?.status || cleanup.operation?.status,
+    state: cleanup.sandbox?.observedState,
+    totalCost: cleanup.sandbox?.totalCost
+  };
+}
+function sandboxResultExitCode(result) {
+  const value = result?.exitCode;
+  if (typeof value !== "number" || value === 0) return void 0;
+  return Math.min(255, Math.max(1, Math.trunc(value)));
+}
+async function sandboxOfferings2(args, flags) {
+  help(flags, "offerings");
+  validateFlags(flags, "offerings");
+  try {
+    sandboxOutput("offerings", await sandboxOfferings(sandboxOptions(flags)), flags);
+  } catch (error) {
+    err("sandbox offerings failed", error.message);
+  }
+}
+async function sandboxQuote2(args, flags) {
+  help(flags, "quote");
+  validateFlags(flags, "quote", SELECTION_FLAGS);
+  try {
+    sandboxOutput("quote", await sandboxQuote(sandboxOptions(flags), quoteBody(flags)), flags);
+  } catch (error) {
+    err("sandbox quote failed", error.message);
+  }
+}
+async function sandboxList2(args, flags) {
+  help(flags, "list");
+  validateFlags(flags, "list");
+  try {
+    sandboxOutput("instances", await sandboxList(sandboxOptions(flags)), flags);
+  } catch (error) {
+    err("sandbox list failed", error.message);
+  }
+}
+async function sandboxHistory2(args, flags) {
+  help(flags, "history");
+  validateFlags(flags, "history", ["state", "search", "from", "to", "page", "page-size"]);
+  const state = flagValue(flags, "state");
+  const allowedStates = ["ALL", "ACTIVE", "HISTORY", "PROVISIONING", "RUNNING", "SUSPENDED", "TERMINATED", "FAILED", "UNKNOWN"];
+  if (state && !allowedStates.includes(state.toUpperCase())) {
+    err(`--state must be one of: ${allowedStates.join(", ")}`);
+  }
+  const page = positiveInteger(flagValue(flags, "page"), "page") || 1;
+  const pageSize = positiveInteger(flagValue(flags, "page-size"), "page-size") || 100;
+  if (pageSize > 100) err("--page-size must be at most 100");
+  try {
+    sandboxOutput("instances", await sandboxHistory(sandboxOptions(flags), {
+      ...state ? { state: state.toUpperCase() } : {},
+      ...flagValue(flags, "search") ? { search: flagValue(flags, "search") } : {},
+      ...flagValue(flags, "from") ? { from: flagValue(flags, "from") } : {},
+      ...flagValue(flags, "to") ? { to: flagValue(flags, "to") } : {},
+      page,
+      pageSize
+    }), flags);
+  } catch (error) {
+    err("sandbox history failed", error.message);
+  }
+}
+async function sandboxGet2(args, flags) {
+  help(flags, "get");
+  validateFlags(flags, "get");
+  const id = instanceId(args, "usage: xapi-to sandbox get <id>");
+  try {
+    sandboxOutput("detail", await sandboxGet(sandboxOptions(flags), id), flags);
+  } catch (error) {
+    err("sandbox get failed", error.message);
+  }
+}
+async function sandboxCreate2(args, flags) {
+  help(flags, "create");
+  validateFlags(flags, "create", [
+    ...SELECTION_FLAGS,
+    ...POLL_FLAGS,
+    "quote-id",
+    "offering-id",
+    "metadata",
+    "idempotency-key",
+    "resume-on-access",
+    "wait"
+  ]);
+  const wait = booleanFlag(flags, "wait");
+  const resumeOnAccess = booleanFlag(flags, "resume-on-access");
+  const opts = sandboxOptions(flags);
+  const quoteId = flagValue(flags, "quote-id");
+  const offeringId = flagValue(flags, "offering-id");
+  const maxHourly = flagValue(flags, "max-hourly-usd");
+  const requirementFlags = [
+    "requirements",
+    "capabilities",
+    "cpu",
+    "memory",
+    "volume",
+    "gpu-count",
+    "gpu-model",
+    "regions",
+    "min-runtime"
+  ].filter((name) => flagValue(flags, name) !== void 0);
+  if (quoteId && offeringId) err("--quote-id and --offering-id are mutually exclusive");
+  if ((quoteId || offeringId) && requirementFlags.length) {
+    err(`${quoteId ? "--quote-id" : "--offering-id"} cannot be combined with requirement flags`, {
+      conflictingFlags: requirementFlags.map((name) => `--${name}`)
+    });
+  }
+  if (quoteId && maxHourly) {
+    err("--max-hourly-usd cannot be combined with --quote-id; the quote already fixes the price");
+  }
+  if (offeringId && maxHourly) {
+    err("--max-hourly-usd cannot be combined with --offering-id; create from requirements to enforce a price ceiling");
+  }
+  const idempotencyKey = flagValue(flags, "idempotency-key") || `cli:create:${randomUUID()}`;
+  let created;
+  try {
+    let selection;
+    if (quoteId) selection = { quoteId };
+    else if (offeringId) selection = { offeringId };
+    else if (maxHourly) {
+      const quoted = await sandboxQuote(opts, quoteBody(flags, createDefaultCapabilities(flags)));
+      if (!quoted?.quoteId) throw new Error("quote response did not include quoteId");
+      selection = { quoteId: quoted.quoteId };
+    } else selection = { requirements: requirementsFromFlags(flags, createDefaultCapabilities(flags)) };
+    const metadata = flagValue(flags, "metadata") ? jsonObject(flagValue(flags, "metadata"), "metadata") : { client: "xapi-cli" };
+    created = await sandboxCreate(opts, {
+      selection,
+      metadata,
+      idempotencyKey,
+      policy: { resumeOnAccess }
+    });
+    let result = created;
+    if (wait && created.id) {
+      const settings = waitSettings(flags);
+      result = await sandboxWait(opts, created.id, ["RUNNING"], settings.timeoutMs, settings.intervalMs);
+    }
+    sandboxOutput("detail", { ...result, clientIdempotencyKey: idempotencyKey }, flags);
+  } catch (error) {
+    let latest = created;
+    if (created?.id) {
+      try {
+        latest = await sandboxGet(opts, created.id);
+      } catch {
+      }
+    }
+    err("sandbox create failed", {
+      message: error.message,
+      instanceId: created?.id,
+      observedState: latest?.observedState,
+      clientIdempotencyKey: idempotencyKey,
+      recovery: created?.id ? {
+        inspect: `xapi-to sandbox get ${created.id}`,
+        terminate: `xapi-to sandbox terminate ${created.id}`
+      } : {
+        retry: `repeat the create command with --idempotency-key ${idempotencyKey}`,
+        reconcile: "xapi-to sandbox history --state ACTIVE --page-size 100"
+      }
+    });
+  }
+}
+async function sandboxWait2(args, flags) {
+  help(flags, "wait");
+  validateFlags(flags, "wait", ["state", ...POLL_FLAGS]);
+  const id = instanceId(args, "usage: xapi-to sandbox wait <id> [--state RUNNING]");
+  const allowedStates = ["PROVISIONING", "RUNNING", "SUSPENDING", "SUSPENDED", "RESUMING", "TERMINATING", "TERMINATED", "FAILED", "UNKNOWN"];
+  const wanted = (csv(flagValue(flags, "state")) || ["RUNNING"]).map((state) => state.toUpperCase());
+  const invalid = wanted.filter((state) => !allowedStates.includes(state));
+  if (invalid.length) err(`--state must contain only: ${allowedStates.join(", ")}`);
+  const settings = waitSettings(flags);
+  try {
+    output(await sandboxWait(sandboxOptions(flags), id, wanted, settings.timeoutMs, settings.intervalMs), flags.format);
+  } catch (error) {
+    err("sandbox wait failed", error.message);
+  }
+}
+async function sandboxExec2(args, flags) {
+  help(flags, "exec");
+  validateFlags(flags, "exec", ["command", "timeout", "cwd", "background"]);
+  const id = instanceId(args, "usage: xapi-to sandbox exec <id> --command <shell>");
+  const command = commandFrom(args.slice(1), flags, "usage: xapi-to sandbox exec <id> --command <shell>");
+  const timeoutSeconds = positiveInteger(flagValue(flags, "timeout"), "timeout") || 60;
+  const background = booleanFlag(flags, "background");
+  try {
+    const result = await sandboxExec(sandboxOptions(flags), id, {
+      command,
+      timeoutSeconds,
+      ...flagValue(flags, "cwd") ? { cwd: flagValue(flags, "cwd") } : {},
+      ...background ? { background: true } : {}
+    });
+    output(result, flags.format);
+    const exitCode = sandboxResultExitCode(result);
+    if (exitCode !== void 0) process.exitCode = exitCode;
+  } catch (error) {
+    err("sandbox exec failed", error.message);
+  }
+}
+async function sandboxFile(args, flags) {
+  help(flags, "file");
+  validateFlags(flags, "file", ["file", "content", "output", "path", "depth"]);
+  const [action, id, remote] = args;
+  if (!action || !id) err("usage: xapi-to sandbox file <write|read|list> <id> [remote-path]");
+  const opts = sandboxOptions(flags);
+  try {
+    if (action === "write") {
+      if (!remote) err("usage: xapi-to sandbox file write <id> <remote-path> (--file <local>|--content <text>)");
+      const local = flagValue(flags, "file");
+      const inline = flagValue(flags, "content");
+      if (Boolean(local) === Boolean(inline)) err("provide exactly one of --file or --content");
+      const body = local ? { path: remote, content: (await readFile(local)).toString("base64"), encoding: "base64" } : { path: remote, content: inline, encoding: "utf8" };
+      output(await sandboxFileWrite(opts, id, body), flags.format);
+      return;
+    }
+    if (action === "read") {
+      if (!remote) err("usage: xapi-to sandbox file read <id> <remote-path> [--output <local>]");
+      const outputPath = flagValue(flags, "output");
+      const result = await sandboxFileRead(opts, id, remote, outputPath ? "base64" : "utf8");
+      if (!outputPath) {
+        output(result, flags.format);
+        return;
+      }
+      const target = resolve(outputPath);
+      const file = await open(target, "wx");
+      let complete = false;
+      try {
+        const data = result?.encoding === "base64" ? Buffer.from(String(result.content || ""), "base64") : Buffer.from(String(result?.content || ""), "utf8");
+        await file.writeFile(data);
+        complete = true;
+        output({ output: target, bytes: data.length, path: remote }, flags.format);
+      } finally {
+        await file.close();
+        if (!complete) await rm(target, { force: true });
+      }
+      return;
+    }
+    if (action === "list") {
+      const depth = positiveInteger(flagValue(flags, "depth"), "depth") || 2;
+      output(await sandboxFileList(opts, id, flagValue(flags, "path") || remote || ".", depth), flags.format);
+      return;
+    }
+    err(`unknown sandbox file command: ${action}`);
+  } catch (error) {
+    err(`sandbox file ${action} failed`, error.message);
+  }
+}
+async function sandboxPort2(args, flags) {
+  help(flags, "port");
+  validateFlags(flags, "port");
+  const id = instanceId(args, "usage: xapi-to sandbox port <id> <port>");
+  const port = positiveInteger(args[1], "port");
+  if (!port || port > 65535) err("port must be between 1 and 65535");
+  try {
+    output(await sandboxPort(sandboxOptions(flags), id, port), flags.format);
+  } catch (error) {
+    err("sandbox port failed", error.message);
+  }
+}
+async function sandboxExtension2(args, flags) {
+  help(flags, "extension");
+  validateFlags(flags, "extension", ["input", "idempotency-key"]);
+  const id = instanceId(args, "usage: xapi-to sandbox extension <id> <extension-id> --input <json>");
+  const extensionId = args[1];
+  if (!extensionId) err("usage: xapi-to sandbox extension <id> <extension-id> --input <json>");
+  if (!/^[a-z0-9][a-z0-9._-]{0,119}$/i.test(extensionId)) err("invalid Sandbox extension id");
+  const input = flagValue(flags, "input") ? jsonObject(flagValue(flags, "input"), "input") : {};
+  const clientIdempotencyKey = flagValue(flags, "idempotency-key") || `cli:extension:${extensionId}:${randomUUID()}`;
+  try {
+    const result = await sandboxExtension(sandboxOptions(flags), id, extensionId, {
+      input,
+      idempotencyKey: clientIdempotencyKey
+    });
+    output({ ...result, clientIdempotencyKey }, flags.format);
+  } catch (error) {
+    err("sandbox extension failed", {
+      message: error.message,
+      clientIdempotencyKey,
+      retry: `repeat with --idempotency-key ${clientIdempotencyKey}`
+    });
+  }
+}
+async function sandboxAudit2(args, flags) {
+  help(flags, "audit");
+  validateFlags(flags, "audit", ["kind", "page", "page-size"]);
+  const id = instanceId(args, "usage: xapi-to sandbox audit <id> [--kind operations]");
+  const kind = flagValue(flags, "kind") || "operations";
+  const allowed = ["operations", "events", "usageSegments", "billingPeriods"];
+  if (!allowed.includes(kind)) err(`--kind must be one of: ${allowed.join(", ")}`);
+  const page = positiveInteger(flagValue(flags, "page"), "page") || 1;
+  const pageSize = positiveInteger(flagValue(flags, "page-size"), "page-size") || 100;
+  if (pageSize > 100) err("--page-size must be at most 100");
+  try {
+    output(await sandboxAudit(sandboxOptions(flags), id, kind, page, pageSize), flags.format);
+  } catch (error) {
+    err("sandbox audit failed", error.message);
+  }
+}
+async function sandboxState(action, args, flags) {
+  help(flags, action);
+  validateFlags(flags, action, [...POLL_FLAGS, "no-wait", "idempotency-key"]);
+  const id = instanceId(args, `usage: xapi-to sandbox ${action} <id>`);
+  const opts = sandboxOptions(flags);
+  const noWait = booleanFlag(flags, "no-wait");
+  const clientIdempotencyKey = flagValue(flags, "idempotency-key") || `cli:${action}:${randomUUID()}`;
+  try {
+    if (action === "terminate" && !noWait) {
+      output(await terminateAndWait(opts, id, flags), flags.format);
+      return;
+    }
+    const operation = await sandboxStateAction(opts, id, action, {
+      idempotencyKey: clientIdempotencyKey
+    });
+    if (noWait) {
+      output({ ...operation, clientIdempotencyKey }, flags.format);
+      return;
+    }
+    const wanted = action === "suspend" ? ["SUSPENDED"] : action === "resume" ? ["RUNNING"] : ["TERMINATED", "FAILED"];
+    const settings = waitSettings(flags);
+    const detail = await sandboxWait(opts, id, wanted, settings.timeoutMs, settings.intervalMs);
+    output({ operation, sandbox: detail, clientIdempotencyKey }, flags.format);
+  } catch (error) {
+    err(`sandbox ${action} failed`, {
+      message: error.message,
+      instanceId: id,
+      clientIdempotencyKey,
+      recovery: {
+        inspect: `xapi-to sandbox get ${id}`,
+        retry: `repeat with --idempotency-key ${clientIdempotencyKey}`
+      }
+    });
+  }
+}
+async function sandboxRun(args, flags) {
+  help(flags, "run");
+  validateFlags(flags, "run", [
+    ...SELECTION_FLAGS,
+    ...POLL_FLAGS,
+    "command",
+    "timeout",
+    "cwd",
+    "metadata",
+    "keep",
+    "idempotency-key"
+  ]);
+  const command = commandFrom(args, flags, "usage: xapi-to sandbox run --command <shell>");
+  const opts = sandboxOptions(flags);
+  const maxHourly = flagValue(flags, "max-hourly-usd") || "0.20";
+  positiveNumber(maxHourly, "max-hourly-usd");
+  const timeoutSeconds = positiveInteger(flagValue(flags, "timeout"), "timeout") || 60;
+  const settings = waitSettings(flags);
+  const idempotencyKey = flagValue(flags, "idempotency-key") || `cli:run:${randomUUID()}`;
+  const metadata = flagValue(flags, "metadata") ? jsonObject(flagValue(flags, "metadata"), "metadata") : {};
+  const keep = booleanFlag(flags, "keep");
+  let id;
+  let failure;
+  let quote;
+  let created;
+  let ready;
+  let result;
+  let cleanup;
+  let interruptedBy;
+  const waitAbort = new AbortController();
+  const interrupt = (signal) => {
+    interruptedBy = signal;
+    waitAbort.abort();
+  };
+  const interruptSigint = () => interrupt("SIGINT");
+  const interruptSigterm = () => interrupt("SIGTERM");
+  const throwIfInterrupted = () => {
+    if (interruptedBy) throw new Error(`interrupted by ${interruptedBy}`);
+  };
+  process.once("SIGINT", interruptSigint);
+  process.once("SIGTERM", interruptSigterm);
+  try {
+    quote = await sandboxQuote(
+      opts,
+      quoteBody({ ...flags, "max-hourly-usd": maxHourly }, ["exec"]),
+      waitAbort.signal
+    );
+    if (!quote?.quoteId) throw new Error("quote response did not include quoteId");
+    throwIfInterrupted();
+    created = await sandboxCreate(opts, {
+      selection: { quoteId: quote.quoteId },
+      metadata: { ...metadata, client: "xapi-cli", command: "sandbox run" },
+      policy: { resumeOnAccess: false },
+      idempotencyKey
+    });
+    id = created?.id;
+    if (!id) throw new Error("create response did not include sandbox id");
+    throwIfInterrupted();
+    ready = await sandboxWait(
+      opts,
+      id,
+      ["RUNNING"],
+      settings.timeoutMs,
+      settings.intervalMs,
+      waitAbort.signal
+    );
+    throwIfInterrupted();
+    result = await sandboxExec(opts, id, {
+      command,
+      timeoutSeconds,
+      ...flagValue(flags, "cwd") ? { cwd: flagValue(flags, "cwd") } : {}
+    }, waitAbort.signal);
+    throwIfInterrupted();
+  } catch (error) {
+    failure = error;
+  } finally {
+    if (id && !keep) {
+      try {
+        cleanup = await terminateAndWait(opts, id, flags);
+      } catch (cleanupError) {
+        cleanup = { error: cleanupError.message };
+        if (!failure) failure = new Error(`command completed but cleanup failed: ${cleanupError.message}`);
+      }
+    }
+    process.removeListener("SIGINT", interruptSigint);
+    process.removeListener("SIGTERM", interruptSigterm);
+  }
+  if (failure) {
+    err("sandbox run failed", {
+      message: failure?.message || String(failure),
+      instanceId: id,
+      clientIdempotencyKey: idempotencyKey,
+      cleanup: keep ? { kept: true, warning: "billing continues until terminated" } : cleanupSummary(cleanup),
+      recovery: id ? { inspect: `xapi-to sandbox get ${id}`, terminate: `xapi-to sandbox terminate ${id}` } : {
+        reconcile: "xapi-to sandbox history --state ACTIVE --page-size 100",
+        retryCreateWithSameKey: idempotencyKey
+      }
+    });
+  }
+  let finalDetail;
+  let finalReadError;
+  if (id) {
+    try {
+      finalDetail = await sandboxGet(opts, id);
+    } catch (error) {
+      finalReadError = error.message;
+    }
+  }
+  const summary = {
+    instanceId: id,
+    clientIdempotencyKey: idempotencyKey,
+    provider: opts.provider || "auto",
+    offering: quote?.offering,
+    createdState: created?.observedState,
+    readyState: ready?.observedState,
+    result,
+    cleanup: keep ? { kept: true, warning: "billing continues until terminated" } : cleanupSummary(cleanup),
+    finalState: finalDetail?.observedState || cleanup?.sandbox?.observedState,
+    totalCost: finalDetail?.totalCost || cleanup?.sandbox?.totalCost,
+    ...finalReadError ? { finalReadError } : {}
+  };
+  sandboxOutput("run", summary, flags);
+  const remoteExitCode = sandboxResultExitCode(result);
+  if (remoteExitCode !== void 0) process.exitCode = remoteExitCode;
+}
+
+// src/commands/provider.ts
+import { mkdir, open as open2, readFile as readFile2 } from "fs/promises";
+import { dirname, resolve as resolve2 } from "path";
+var READ_RETRIES3 = 2;
+var BASE = "/api/api-services/agent";
+var PROVIDER_HELP = `xapi-to provider - Manage provider services and their content
+
+USAGE
+  xapi-to provider list
+  xapi-to provider get <service-id> [--version <version>]
+  xapi-to provider create --file <service.json>
+  xapi-to provider update <service-id> [metadata flags]
+  xapi-to provider versions <service-id>
+  xapi-to provider version update <service-id> <version-id> --file <contract.json> [--replace]
+  xapi-to provider major create <service-id>
+  xapi-to provider revision start <service-id> <major>
+  xapi-to provider publish <service-id> <revision-id> [--changelog <text>|--changelog-file <path>]
+  xapi-to provider rollback <service-id> <major> --revision <revision-id> [--reason <text>|--reason-file <path>]
+  xapi-to provider default-major <service-id> <major>
+  xapi-to provider deprecate|restore <service-id> <major>
+  xapi-to provider review <service-id> <revision-id>
+  xapi-to provider diff <service-id> <major>
+  xapi-to provider metrics [service-id] [--days 30]
+  xapi-to provider events [--after <cursor>] [--limit 50]
+  xapi-to provider skill context <service-id>
+  xapi-to provider skill scaffold <service-id> --output <SKILL.md> [--force]
+  xapi-to provider skill link <service-id> <skill-id>
+  xapi-to provider skill unlink <service-id>
+  xapi-to provider skill fingerprint <service-id> [--skill-version-id <id>]
+  xapi-to provider delete <service-id> --confirm <service-name-or-id>
+
+METADATA FLAGS
+  --file <metadata.json>            Read metadata from JSON
+  --name <name>                    Service display name
+  --description <text>             Marketplace card description
+  --description-file <path|->      Read description from a file or stdin
+  --about <markdown>               Long About content
+  --about-file <path|->            Read About Markdown from a file or stdin
+  --clear-about                    Clear About content
+  --website <url>                  Public service website
+  --clear-website                  Clear website
+  --logo-url <url>                 Service logo URL
+  --category <category>            Marketplace category
+
+SCOPES
+  list/get/versions/review/diff/skill context: service:read
+  create: service:create
+  update/version update/skill link/fingerprint: service:update
+  major/revision start: version:create
+  publish: service:publish
+  rollback/default-major/deprecate/restore: service:rollback
+  metrics/events: observability:read
+  delete: service:delete
+`;
+function servicePath(serviceId, suffix = "") {
+  return `${BASE}/services/${encodeURIComponent(serviceId)}${suffix}`;
+}
+function required(value, usage2) {
+  if (!value?.trim()) err(`usage: ${usage2}`);
+  return value.trim();
+}
+function requiredFlag(value, usage2) {
+  if (!value?.trim() || value === "true") err(`usage: ${usage2}`);
+  return value.trim();
+}
+function optionalFlag(value, flagName) {
+  if (value === void 0) return void 0;
+  if (value === "true") err(`${flagName} requires a value`);
+  return value;
+}
+function positiveInt(raw, name, max) {
+  if (raw === void 0) return void 0;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || max !== void 0 && value > max) {
+    err(`invalid ${name}`, `Expected an integer from 1${max ? ` to ${max}` : ""}.`);
+  }
+  return value;
+}
+function boolFlag(flags, name) {
+  return ["true", "1", "yes"].includes((flags[name] || "").toLowerCase());
+}
+async function readText(path, flagName) {
+  if (path === "true") err(`${flagName} requires a path or - for stdin`);
+  if (path === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+  }
+  return readFile2(resolve2(path), "utf8");
+}
+async function textOption(flags, directName, fileName) {
+  const direct = flags[directName];
+  const file = flags[fileName];
+  if (direct !== void 0 && file !== void 0) {
+    err(`--${directName} and --${fileName} are mutually exclusive`);
+  }
+  if (direct === "true") err(`--${directName} requires a value`);
+  if (file !== void 0) return readText(file, `--${fileName}`);
+  return direct;
+}
+async function readJsonObject(path, flagName = "--file") {
+  if (!path || path === "true") err(`${flagName} requires a JSON file path or - for stdin`);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readText(path, flagName));
+  } catch (error) {
+    err(`invalid JSON from ${flagName}`, error.message);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    err(`${flagName} must contain a JSON object`);
+  }
+  return parsed;
+}
+async function metadataBody(flags) {
+  const body = flags.file ? await readJsonObject(flags.file) : {};
+  const description = await textOption(flags, "description", "description-file");
+  const about = await textOption(flags, "about", "about-file");
+  if (boolFlag(flags, "clear-about") && about !== void 0) {
+    err("--clear-about cannot be combined with --about or --about-file");
+  }
+  if (boolFlag(flags, "clear-website") && flags.website !== void 0) {
+    err("--clear-website cannot be combined with --website");
+  }
+  if (description !== void 0) body.description = description;
+  if (about !== void 0) body.aboutMarkdown = about;
+  for (const [flagName, fieldName] of [
+    ["name", "name"],
+    ["website", "website"],
+    ["logo-url", "logoUrl"],
+    ["category", "category"]
+  ]) {
+    if (flags[flagName] === "true") err(`--${flagName} requires a value`);
+    if (flags[flagName] !== void 0) body[fieldName] = flags[flagName];
+  }
+  if (boolFlag(flags, "clear-about")) body.aboutMarkdown = null;
+  if (boolFlag(flags, "clear-website")) body.website = null;
+  if (Object.keys(body).length === 0) {
+    err("no provider metadata supplied", "Pass --file or at least one metadata flag.");
+  }
+  return body;
+}
+async function writeExclusive(path, content, force) {
+  const target = resolve2(path);
+  await mkdir(dirname(target), { recursive: true });
+  const handle = await open2(target, force ? "w" : "wx");
+  try {
+    await handle.writeFile(content, "utf8");
+  } finally {
+    await handle.close();
+  }
+  return target;
+}
+async function provider(args, flags) {
+  if (flags.help || args.length === 0) {
+    console.log(PROVIDER_HELP);
+    return;
+  }
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey;
+  const [command, ...rest] = args;
+  try {
+    let result;
+    switch (command) {
+      case "list":
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${BASE}/services`, { retries: READ_RETRIES3 });
+        break;
+      case "get": {
+        const id = required(rest[0], "xapi-to provider get <service-id>");
+        const path = new URL(`https://placeholder${servicePath(id)}`);
+        const version = optionalFlag(flags.version, "--version");
+        if (version !== void 0) path.searchParams.set("version", version);
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${path.pathname}${path.search}`, { retries: READ_RETRIES3 });
+        break;
+      }
+      case "create":
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${BASE}/services`, {
+          method: "POST",
+          body: await readJsonObject(required(flags.file, "xapi-to provider create --file <service.json>"))
+        });
+        break;
+      case "update": {
+        const id = required(rest[0], "xapi-to provider update <service-id> [metadata flags]");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id), {
+          method: "PATCH",
+          body: await metadataBody(flags)
+        });
+        break;
+      }
+      case "versions": {
+        const id = required(rest[0], "xapi-to provider versions <service-id>");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, "/version-overview"), { retries: READ_RETRIES3 });
+        break;
+      }
+      case "version": {
+        if (rest[0] !== "update") err("usage: xapi-to provider version update <service-id> <version-id> --file <contract.json> [--replace]");
+        const id = required(rest[1], "xapi-to provider version update <service-id> <version-id> --file <contract.json>");
+        const versionId = required(rest[2], "xapi-to provider version update <service-id> <version-id> --file <contract.json>");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/versions/${encodeURIComponent(versionId)}`), {
+          method: boolFlag(flags, "replace") ? "PUT" : "PATCH",
+          body: await readJsonObject(required(flags.file, "xapi-to provider version update <service-id> <version-id> --file <contract.json>"))
+        });
+        break;
+      }
+      case "major": {
+        if (rest[0] !== "create") err("usage: xapi-to provider major create <service-id>");
+        const id = required(rest[1], "xapi-to provider major create <service-id>");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, "/majors"), { method: "POST" });
+        break;
+      }
+      case "revision": {
+        if (rest[0] !== "start") err("usage: xapi-to provider revision start <service-id> <major>");
+        const id = required(rest[1], "xapi-to provider revision start <service-id> <major>");
+        const major = positiveInt(required(rest[2], "xapi-to provider revision start <service-id> <major>"), "major");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/majors/${major}/working-revision`), { method: "POST" });
+        break;
+      }
+      case "publish": {
+        const id = required(rest[0], "xapi-to provider publish <service-id> <revision-id>");
+        const revisionId = required(rest[1], "xapi-to provider publish <service-id> <revision-id>");
+        const changelog = await textOption(flags, "changelog", "changelog-file");
+        if (changelog !== void 0 && changelog.length > 2e3) err("changelog is too long", "Maximum length is 2000 characters.");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/revisions/${encodeURIComponent(revisionId)}/submit`), {
+          method: "POST",
+          body: changelog === void 0 ? {} : { changelog }
+        });
+        break;
+      }
+      case "rollback": {
+        const id = required(rest[0], "xapi-to provider rollback <service-id> <major> --revision <revision-id>");
+        const major = positiveInt(required(rest[1], "xapi-to provider rollback <service-id> <major> --revision <revision-id>"), "major");
+        const revisionId = requiredFlag(flags.revision, "xapi-to provider rollback <service-id> <major> --revision <revision-id>");
+        const reason = await textOption(flags, "reason", "reason-file");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/majors/${major}/rollback`), {
+          method: "POST",
+          body: { revisionId, ...reason !== void 0 ? { reason } : {} }
+        });
+        break;
+      }
+      case "default-major": {
+        const id = required(rest[0], "xapi-to provider default-major <service-id> <major>");
+        const major = positiveInt(required(rest[1], "xapi-to provider default-major <service-id> <major>"), "major");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, "/default-major"), { method: "PUT", body: { major } });
+        break;
+      }
+      case "deprecate":
+      case "restore": {
+        const id = required(rest[0], `xapi-to provider ${command} <service-id> <major>`);
+        const major = positiveInt(required(rest[1], `xapi-to provider ${command} <service-id> <major>`), "major");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/majors/${major}/deprecated`), {
+          method: "PUT",
+          body: { deprecated: command === "deprecate" }
+        });
+        break;
+      }
+      case "review": {
+        const id = required(rest[0], "xapi-to provider review <service-id> <revision-id>");
+        const revisionId = required(rest[1], "xapi-to provider review <service-id> <revision-id>");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/revisions/${encodeURIComponent(revisionId)}/review`), { retries: READ_RETRIES3 });
+        break;
+      }
+      case "diff": {
+        const id = required(rest[0], "xapi-to provider diff <service-id> <major>");
+        const major = positiveInt(required(rest[1], "xapi-to provider diff <service-id> <major>"), "major");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, `/majors/${major}/diff-preview`), { retries: READ_RETRIES3 });
+        break;
+      }
+      case "metrics": {
+        const days = positiveInt(flags.days, "days", 365);
+        const path = new URL(`https://placeholder${rest[0] ? servicePath(rest[0], "/metrics") : `${BASE}/metrics`}`);
+        if (days) path.searchParams.set("days", String(days));
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${path.pathname}${path.search}`, { retries: READ_RETRIES3 });
+        break;
+      }
+      case "events": {
+        const limit = positiveInt(flags.limit, "limit", 100);
+        const path = new URL("https://placeholder/api/agent/events");
+        const after = optionalFlag(flags.after, "--after");
+        if (after !== void 0) path.searchParams.set("after", after);
+        if (limit) path.searchParams.set("limit", String(limit));
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${path.pathname}${path.search}`, { retries: READ_RETRIES3 });
+        break;
+      }
+      case "skill": {
+        const subcommand = required(rest[0], "xapi-to provider skill context|scaffold|link|unlink|fingerprint ...");
+        const id = required(rest[1], `xapi-to provider skill ${subcommand} <service-id>`);
+        if (subcommand === "context" || subcommand === "scaffold") {
+          const destination = subcommand === "scaffold" ? requiredFlag(flags.output, "xapi-to provider skill scaffold <service-id> --output <SKILL.md>") : void 0;
+          const context = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, "/skill-context"), { retries: READ_RETRIES3 });
+          if (subcommand === "scaffold") {
+            if (!context || typeof context.scaffoldMarkdown !== "string") throw new Error("skill context response is missing scaffoldMarkdown");
+            const savedTo = await writeExclusive(destination, context.scaffoldMarkdown, boolFlag(flags, "force"));
+            result = { serviceId: id, savedTo, currentFingerprint: context.currentFingerprint };
+          } else {
+            result = context;
+          }
+        } else if (subcommand === "link") {
+          const skillId = required(rest[2], "xapi-to provider skill link <service-id> <skill-id>");
+          result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id), { method: "PATCH", body: { linkedSkillId: skillId } });
+        } else if (subcommand === "unlink") {
+          result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id), { method: "PATCH", body: { linkedSkillId: null } });
+        } else if (subcommand === "fingerprint") {
+          const skillVersionId = optionalFlag(flags["skill-version-id"], "--skill-version-id");
+          result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id, "/skill-fingerprint"), {
+            method: "PUT",
+            body: skillVersionId !== void 0 ? { skillVersionId } : {}
+          });
+        } else {
+          err(`unknown provider skill command: ${subcommand}`, "Valid commands: context, scaffold, link, unlink, fingerprint.");
+        }
+        break;
+      }
+      case "delete": {
+        const id = required(rest[0], "xapi-to provider delete <service-id> --confirm <service-name-or-id>");
+        const confirm = requiredFlag(flags.confirm, "xapi-to provider delete <service-id> --confirm <service-name-or-id>");
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, servicePath(id), { method: "DELETE", body: { confirm } });
+        break;
+      }
+      default:
+        err(`unknown provider command: ${command}`, 'Run "xapi-to provider --help".');
+    }
+    output(result, flags.format);
+  } catch (error) {
+    err("provider request failed", error.message);
+  }
+}
+
+// src/commands/skill.ts
+import { readdir, readFile as readFile3 } from "fs/promises";
+import { relative, resolve as resolve3, sep } from "path";
+var READ_RETRIES4 = 2;
+var MAX_FILES = 100;
+var MAX_PACKAGE_BYTES = 2 * 1024 * 1024;
+var MAX_FILE_BYTES = 512 * 1024;
+var BASE2 = "/api/skills/agent";
+var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([".git", "node_modules"]);
+var SKILL_HELP = `xapi-to skill - Upload and publish service usage skills
+
+USAGE
+  xapi-to skill spec
+  xapi-to skill submit --dir <skill-directory>
+  xapi-to skill submit --github <public-github-url> [metadata flags]
+  xapi-to skill status <submission-id>
+  xapi-to skill wait <submission-id> [--interval 2s] [--timeout 10m]
+
+GITHUB METADATA FLAGS
+  --version <semver>
+  --name <display-name>
+  --description <text>
+  --category <value>                Repeat is not supported; use comma-separated values
+  --tag <value>                     Repeat is not supported; use comma-separated values
+
+Local submissions recursively upload regular files. Symlinks, .git, and
+node_modules are excluded. The package must contain SKILL.md, have at most
+100 files, keep each file at or below 512 KiB, and keep the encoded package
+at or below 2 MiB.
+
+SCOPES
+  spec/status/wait: skill:read
+  submit: skill:submit
+`;
+function required2(value, usage2) {
+  if (!value?.trim() || value === "true") err(`usage: ${usage2}`);
+  return value.trim();
+}
+function parseDuration(raw, flagName) {
+  const match = raw.trim().toLowerCase().match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match) err(`${flagName} must be a duration such as 500ms, 2s, 5m, or 1h`);
+  const value = Number(match[1]);
+  const multiplier = match[2] === "h" ? 36e5 : match[2] === "m" ? 6e4 : match[2] === "s" ? 1e3 : 1;
+  const result = value * multiplier;
+  if (!Number.isSafeInteger(result) || result <= 0) err(`${flagName} must be greater than 0`);
+  return result;
+}
+function listFlag(value) {
+  if (!value || value === "true") return void 0;
+  const items = [...new Set(value.split(",").map((item) => item.trim()).filter(Boolean))];
+  return items.length ? items : void 0;
+}
+async function collectInlineFiles(directory) {
+  const root = resolve3(directory);
+  const files = [];
+  async function walk(current) {
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.isSymbolicLink()) continue;
+      const absolute = resolve3(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) await walk(absolute);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (files.length >= MAX_FILES) {
+        throw new Error(`skill package exceeds ${MAX_FILES} files`);
+      }
+      const content = await readFile3(absolute);
+      if (content.byteLength > MAX_FILE_BYTES) {
+        throw new Error(`skill file ${entry.name} exceeds ${MAX_FILE_BYTES} bytes`);
+      }
+      const path = relative(root, absolute).split(sep).join("/");
+      if (!path || path.startsWith("../")) throw new Error("skill file escaped the selected directory");
+      files.push({ path, contentBase64: content.toString("base64") });
+    }
+  }
+  await walk(root);
+  if (!files.some((file) => file.path === "SKILL.md")) {
+    throw new Error("skill package root must contain SKILL.md");
+  }
+  const encodedBytes = Buffer.byteLength(JSON.stringify({ sourceType: "inline", files }), "utf8");
+  if (encodedBytes > MAX_PACKAGE_BYTES) {
+    throw new Error(`encoded skill package exceeds ${MAX_PACKAGE_BYTES} bytes`);
+  }
+  return files;
+}
+function statusOf(value) {
+  return value?.status || value?.submission?.status || value?.skill?.status;
+}
+function sleep3(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+async function getSubmission(apiKey, id, timeoutMs = 3e4, retries = READ_RETRIES4) {
+  return apiKeyApiRequest(
+    XAPI_API_HOST,
+    apiKey,
+    `${BASE2}/submissions/${encodeURIComponent(id)}`,
+    { timeoutMs, retries }
+  );
+}
+async function waitForSubmission(apiKey, id, flags) {
+  const intervalMs = parseDuration(flags.interval || "2s", "--interval");
+  const timeoutMs = parseDuration(flags.timeout || "10m", "--timeout");
+  const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
+  while (true) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      err("skill wait timeout", `submission_id=${id}, elapsed_ms=${Date.now() - startedAt}, timeout_ms=${timeoutMs}`);
+    }
+    try {
+      const result = await getSubmission(apiKey, id, remaining, 0);
+      const status = statusOf(result);
+      if (status === "PUBLISHED") return result;
+      if (["NEEDS_CHANGES", "REJECTED", "SUSPENDED", "ARCHIVED"].includes(String(status))) {
+        output(result, flags.format);
+        process.exit(1);
+      }
+    } catch (error) {
+      const pending = error instanceof HttpError && error.status === 404;
+      if (!pending && !isRetryableRequestError(error)) throw error;
+    }
+    await sleep3(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+  }
+}
+async function skill(args, flags) {
+  if (flags.help || args.length === 0) {
+    console.log(SKILL_HELP);
+    return;
+  }
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey;
+  const [command, ...rest] = args;
+  try {
+    let result;
+    if (command === "spec") {
+      result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${BASE2}/spec`, { retries: READ_RETRIES4 });
+    } else if (command === "submit") {
+      const directory = flags.dir;
+      const github = flags.github;
+      if (directory && github || !directory && !github) {
+        err("choose exactly one skill source", "Pass either --dir <path> or --github <public-url>.");
+      }
+      if (directory) {
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${BASE2}/submissions`, {
+          method: "POST",
+          body: { files: await collectInlineFiles(required2(directory, "xapi-to skill submit --dir <skill-directory>")) }
+        });
+      } else {
+        const body = {
+          url: required2(github, "xapi-to skill submit --github <public-github-url>")
+        };
+        for (const name of ["version", "name", "description"]) {
+          if (flags[name] && flags[name] !== "true") body[name] = flags[name];
+        }
+        const categories = listFlag(flags.category);
+        const tags = listFlag(flags.tag);
+        if (categories) body.categories = categories;
+        if (tags) body.tags = tags;
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${BASE2}/submissions/github`, { method: "POST", body });
+      }
+    } else if (command === "status") {
+      result = await getSubmission(apiKey, required2(rest[0], "xapi-to skill status <submission-id>"));
+    } else if (command === "wait") {
+      result = await waitForSubmission(apiKey, required2(rest[0], "xapi-to skill wait <submission-id>"), flags);
+    } else {
+      err(`unknown skill command: ${command}`, "Valid commands: spec, submit, status, wait.");
+    }
+    output(result, flags.format);
+  } catch (error) {
+    if (error instanceof Error && error.message === "process.exit") throw error;
+    err("skill request failed", error.message);
+  }
+}
+
 // src/args.ts
 function parseArgs(argv) {
   const positional = [];
@@ -2178,7 +3164,7 @@ COMMANDS
     --page N  --page-size N         Pagination
     --category <name>               Filter by category
     --service-id <id>               Filter by service
-  search <query>                    Search actions by keyword
+  search <query>                    Search actions by keyword (--all-versions: \u542B\u975E\u9ED8\u8BA4\u4F46\u4ECD\u5728\u8DD1\u7684\u5927\u7248\u672C)
     --source capability|api         Filter by source type
     --category <name>               Filter by category
     --page N  --page-size N         Pagination
@@ -2205,6 +3191,22 @@ COMMANDS
     --timeout <duration>             Max wait duration, e.g. 10m
     --max-attempts <number>          Max poll attempts
 
+  sandbox <command>                  Managed cloud sandbox lifecycle
+    run --command <shell>            Quote, create, execute, and auto-terminate
+    offerings|quote|list|history|get|create|wait|exec
+    file|port|extension|audit|suspend|resume|terminate
+    Run "xapi-to sandbox --help" for selection and safety flags
+
+  provider <command>                 Manage provider services, releases, metrics, events, and linked skills
+    list|get|create|update|versions|version|major|revision
+    publish|rollback|default-major|deprecate|restore|review|diff
+    metrics|events|skill|delete
+    Run "xapi-to provider --help" for metadata and lifecycle flags
+
+  skill <command>                    Upload and submit service usage skills
+    spec|submit|status|wait
+    Run "xapi-to skill --help" for local directory and GitHub workflows
+
   oauth bind [--provider twitter]   Bind Twitter OAuth to your API key
   oauth status                      List current OAuth bindings
   oauth unbind <binding-id>         Remove an OAuth binding
@@ -2214,6 +3216,14 @@ COMMANDS
     --referral-code <code>          Register with an inviter's referral code (also: --referralCode, or as positional arg)
     --force                         Replace an existing file-based apiKey
   balance                           Show current account balance
+  usage <request-id>                Show a finalized per-request cost receipt
+  usage wait <request-id>           Wait until a request receipt is finalized
+    --interval <duration>           Poll interval (default: 1s)
+    --timeout <duration>            Max wait duration (default: 30s)
+  earnings [summary]                Show spendable balance and provider earnings
+  earnings list                    List provider earning records
+  earnings transfer <usd> --idempotency-key <key>
+                                    Reinvest settled earnings into xapi balance
   topup [--amount <usd>] [--method stripe|x402]   Generate payment URL
 
   health                            Check backend connectivity
@@ -2231,6 +3241,7 @@ ENV VARS
   XAPI_API_KEY      Compatible API key alias
   XAPI_ACTION_HOST   Action service host (default: action.xapi.to)
   XAPI_API_HOST      Auth/account service host (default: api.xapi.to)
+  XAPI_SANDBOX_HOST  Sandbox gateway host (default: sandbox.xapi.to)
   XAPI_OUTPUT        Default output format
   XAPI_TRANSFER_IDLE_TIMEOUT_MS  SSE/download idle timeout (default: 60000)
 
@@ -2250,9 +3261,18 @@ EXAMPLES
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}' --code python
   xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
   xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 2s --timeout 10m
+  xapi-to sandbox run --command 'python3 -c "print(6*7)"'
   xapi-to categories
   xapi-to services --format table
   xapi-to config set apiKey=xapi_abc123
+  xapi-to earnings
+  xapi-to usage c7fe24d5-e1d4-4bc1-a9bb-e16df8ab93b0
+  xapi-to usage wait c7fe24d5-e1d4-4bc1-a9bb-e16df8ab93b0 --timeout 1m
+  xapi-to earnings transfer 1 --idempotency-key reinvest-001
+  xapi-to provider update svc_123 --about-file ./ABOUT.md --website https://example.com
+  xapi-to provider publish svc_123 rev_456 --changelog-file ./CHANGELOG.md
+  xapi-to skill submit --dir ./skills/my-service
+  xapi-to provider skill link svc_123 11111111-1111-4111-8111-111111111111
   xapi-to health
 `;
 async function main() {
@@ -2288,6 +3308,10 @@ async function main() {
       return actionBatchGet(rest, flags);
     case "call":
       return actionCall2(rest, flags);
+    case "provider":
+      return provider(rest, flags);
+    case "skill":
+      return skill(rest, flags);
     case "task": {
       if (rest.length === 0) {
         console.log(taskHelp());
@@ -2305,6 +3329,54 @@ async function main() {
       }
       break;
     }
+    case "sandbox": {
+      if (rest.length === 0) {
+        console.log(SANDBOX_HELP);
+        process.exit(0);
+      }
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case "offerings":
+          return sandboxOfferings2(subRest, flags);
+        case "quote":
+          return sandboxQuote2(subRest, flags);
+        case "list":
+          return sandboxList2(subRest, flags);
+        case "history":
+          return sandboxHistory2(subRest, flags);
+        case "get":
+          return sandboxGet2(subRest, flags);
+        case "create":
+          return sandboxCreate2(subRest, flags);
+        case "wait":
+          return sandboxWait2(subRest, flags);
+        case "exec":
+          return sandboxExec2(subRest, flags);
+        case "file":
+          return sandboxFile(subRest, flags);
+        case "port":
+          return sandboxPort2(subRest, flags);
+        case "extension":
+          return sandboxExtension2(subRest, flags);
+        case "audit":
+          return sandboxAudit2(subRest, flags);
+        case "suspend":
+          return sandboxState("suspend", subRest, flags);
+        case "resume":
+          return sandboxState("resume", subRest, flags);
+        case "terminate":
+          return sandboxState("terminate", subRest, flags);
+        case "run":
+          return sandboxRun(subRest, flags);
+        default:
+          console.error(JSON.stringify({
+            error: `unknown sandbox command: ${subCmd}`,
+            hint: "run xapi-to sandbox --help"
+          }));
+          process.exit(1);
+      }
+      break;
+    }
     // ── OAuth commands ──
     case "oauth": {
       if (flags.help || rest.length === 0) {
@@ -2332,6 +3404,10 @@ async function main() {
       return register(rest, flags);
     case "balance":
       return balance(rest, flags);
+    case "usage":
+      return usage(rest, flags);
+    case "earnings":
+      return earnings(rest, flags);
     case "topup":
       return topup(rest, flags);
     case "health":