xapi-to 0.1.20 → 0.1.22

package/dist/index.js

@@ -13,6 +13,7 @@ import {
   actionSearch,
   actionServices,
   actionStream,
+  apiKeyApiRequest,
   assertAllowedHost,
   deleteOAuthBinding,
   enableOAuthForKey,
@@ -48,7 +49,7 @@ import {
   saveConfig,
   scheme,
   showConfig
-} from "./chunk-TYY6JR6O.js";
+} from "./chunk-2YRWNREY.js";
 
 // src/codegen.ts
 var TARGET_MAP = {
@@ -970,6 +971,203 @@ async function balance(args, flags) {
   }
 }
 
+// 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 sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
+}
+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 {
+      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, {
@@ -994,24 +1192,97 @@ function bindingChangedAfter(binding, startedAtMs, existingBindingIds) {
   if (!Number.isFinite(changedAt)) return !existingBindingIds.has(binding.id);
   return changedAt >= startedAtMs;
 }
+var POLL_DEADLINE = /* @__PURE__ */ Symbol("oauth poll deadline");
+function waitForPollInterval(ms, signal) {
+  return new Promise((resolve4) => {
+    if (signal.aborted) {
+      resolve4(false);
+      return;
+    }
+    let timer;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      cleanup();
+      resolve4(false);
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolve4(true);
+    }, Math.max(0, ms));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+}
+function resolveOnPollAbort(operation, signal) {
+  return new Promise((resolve4, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve4(POLL_DEADLINE);
+    };
+    const resolveOperation = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve4(value);
+    };
+    const rejectOperation = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(resolveOperation, rejectOperation);
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+  });
+}
 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);
-      process.stdout.write(`\r  Waiting for authorization... (${remaining}s remaining)  `);
+  const controller = new AbortController();
+  const deadlineTimer = setTimeout(
+    () => controller.abort(),
+    Math.max(0, deadline - Date.now())
+  );
+  try {
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      const intervalElapsed = await waitForPollInterval(
+        Math.min(Math.max(0, intervalMs), remaining),
+        controller.signal
+      );
+      if (!intervalElapsed || Date.now() >= deadline || controller.signal.aborted) break;
+      try {
+        const bindings = await resolveOnPollAbort(
+          listOAuthBindings(jwtToken, XAPI_API_HOST, controller.signal),
+          controller.signal
+        );
+        if (bindings === POLL_DEADLINE || Date.now() >= deadline) break;
+        const match = Array.isArray(bindings) ? bindings.find(
+          (b) => b.apiKeyId === apiKeyId && b.providerId === providerId && bindingChangedAfter(b, startedAtMs, existingBindingIds)
+        ) : null;
+        if (match) return match;
+      } catch (e) {
+        if (controller.signal.aborted || Date.now() >= deadline) break;
+        if (!isRetryableRequestError(e)) throw e;
+      }
+      if (isTTY) {
+        const remaining2 = Math.ceil((deadline - Date.now()) / 1e3);
+        process.stdout.write(`\r  Waiting for authorization... (${remaining2}s remaining)  `);
+      }
     }
+  } finally {
+    clearTimeout(deadlineTimer);
+    controller.abort();
   }
   if (process.stdout.isTTY) process.stdout.write("\n");
   return null;
@@ -1038,11 +1309,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,
@@ -1051,21 +1322,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`);
     }
@@ -1088,7 +1359,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);
@@ -1099,7 +1370,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();
@@ -1178,10 +1449,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}`
@@ -1195,13 +1466,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();
@@ -1210,7 +1481,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);
             }
           }
@@ -1219,7 +1490,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 {
@@ -1234,7 +1505,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) {
@@ -1249,7 +1520,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
@@ -1260,14 +1531,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
@@ -1403,7 +1674,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`);
@@ -1417,9 +1688,9 @@ function parsePositiveInt(raw, flagName) {
   }
   return n;
 }
-function sleep(ms) {
+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") {
@@ -1457,7 +1728,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();
@@ -1514,7 +1785,7 @@ async function taskWait(args, flags) {
     }
     const desiredWaitMs = retryDelayMs ?? intervalMs;
     const waitMs = deadline !== void 0 ? Math.min(desiredWaitMs, Math.max(0, deadline - Date.now())) : desiredWaitMs;
-    await sleep(waitMs);
+    await sleep2(waitMs);
   }
 }
 function taskHelp() {
@@ -1561,6 +1832,7 @@ SELECTION FLAGS
   --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)
 
@@ -1602,6 +1874,7 @@ SELECTION
   --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
 
@@ -1705,6 +1978,7 @@ var SELECTION_FLAGS = [
   "gpu-count",
   "gpu-model",
   "regions",
+  "min-runtime",
   "requirements",
   "max-hourly-usd"
 ];
@@ -1722,11 +1996,11 @@ COMMON
 }
 function validateFlags(flags, command, allowed = []) {
   const valid = /* @__PURE__ */ new Set([...COMMON_FLAGS, ...allowed]);
-  const unknown = Object.keys(flags).filter((flag) => !valid.has(flag));
+  const unknown = Object.keys(flags).filter((flag2) => !valid.has(flag2));
   if (unknown.length) {
-    err(`unknown flag${unknown.length > 1 ? "s" : ""} for sandbox ${command}: ${unknown.map((flag) => `--${flag}`).join(", ")}`, {
+    err(`unknown flag${unknown.length > 1 ? "s" : ""} for sandbox ${command}: ${unknown.map((flag2) => `--${flag2}`).join(", ")}`, {
       hint: `run xapi-to sandbox ${command} --help`,
-      validFlags: [...valid].sort().map((flag) => `--${flag}`)
+      validFlags: [...valid].sort().map((flag2) => `--${flag2}`)
     });
   }
   if (flags.format && !["json", "pretty", "table"].includes(flags.format)) {
@@ -1826,10 +2100,10 @@ function positiveInteger(raw, name) {
 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)?$/);
-  if (!match || Number(match[1]) <= 0) err(`--${name} must be a duration like 500ms, 2s, 5m, or 1h`);
+  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 }[match[2] || "ms"];
+  return value * { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5 }[match[2] || "ms"];
 }
 function jsonObject(raw, name) {
   try {
@@ -1848,8 +2122,8 @@ function sandboxOptions(flags) {
   const cfg = getConfig();
   requireApiKey(cfg);
   const host = flagValue(flags, "host") || cfg.sandboxHost || XAPI_SANDBOX_HOST;
-  const provider = flagValue(flags, "provider");
-  return { sandboxHost: host, apiKey: cfg.apiKey, ...provider ? { provider } : {} };
+  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") : {};
@@ -1860,6 +2134,7 @@ function requirementsFromFlags(flags, defaultCapabilities) {
   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)");
   }
@@ -1875,6 +2150,11 @@ function requirementsFromFlags(flags, defaultCapabilities) {
       ...gpuModel ? { model: gpuModel } : {}
     };
   }
+  if (minRuntime !== void 0) {
+    requirements.minContinuousRuntimeSeconds = Math.ceil(
+      durationMs(minRuntime, 0, "min-runtime") / 1e3
+    );
+  }
   return requirements;
 }
 function quoteBody(flags, defaultCapabilities) {
@@ -1894,14 +2174,14 @@ function waitSettings(flags) {
     intervalMs: durationMs(flags.interval, 2e3, "interval")
   };
 }
-function commandFrom(args, flags, usage) {
+function commandFrom(args, flags, usage2) {
   const fromFlag = flagValue(flags, "command");
   const command = fromFlag ?? args.join(" ");
-  if (!command.trim()) err(usage);
+  if (!command.trim()) err(usage2);
   return command;
 }
-function instanceId(args, usage) {
-  if (!args[0]) err(usage);
+function instanceId(args, usage2) {
+  if (!args[0]) err(usage2);
   return args[0];
 }
 async function terminateAndWait(opts, id, flags) {
@@ -1921,7 +2201,7 @@ async function terminateAndWait(opts, id, flags) {
       break;
     } catch (error) {
       if (!(error instanceof HttpError) || error.status !== 409) throw error;
-      await new Promise((resolve2) => setTimeout(resolve2, intervalMs));
+      await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
     }
   }
   const remaining = Math.max(1, deadline - Date.now());
@@ -2042,7 +2322,8 @@ async function sandboxCreate2(args, flags) {
     "volume",
     "gpu-count",
     "gpu-model",
-    "regions"
+    "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) {
@@ -2399,6 +2680,881 @@ async function sandboxRun(args, flags) {
   if (remoteExitCode !== void 0) process.exitCode = remoteExitCode;
 }
 
+// src/commands/provider.ts
+import { mkdir, open as open2, readFile as readFile3 } from "fs/promises";
+import { dirname, resolve as resolve2 } from "path";
+
+// src/commands/provider-onboarding.ts
+import { readFile as readFile2 } from "fs/promises";
+
+// src/provider-client.ts
+function providerRequest(path, apiKey, method = "GET", body, timeoutMs = 3e4, retries = method === "GET" ? 2 : 0) {
+  return request(`${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/api-services/agent/${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...apiKey ? { "XAPI-KEY": apiKey } : {}
+    },
+    ...body === void 0 ? {} : { body: JSON.stringify(body) }
+  }, Math.min(timeoutMs, 3e4), retries);
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+var SECRET_FIELD = /^(authConfig|privateHeaders|authorization|proxy-authorization|api[-_]?key|xapi[-_]?key|x-api-key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|token|cookie|set-cookie)$/i;
+var CONTRACT_FIELD = /* @__PURE__ */ new Set([
+  "openApiSpec",
+  "bodySchema",
+  "schema",
+  "schemas",
+  "properties",
+  "definitions",
+  "$defs",
+  "params",
+  "pathParams",
+  "responses",
+  "securitySchemes"
+]);
+function isContract(key, value, parent) {
+  if (CONTRACT_FIELD.has(key)) return true;
+  const obj = object(value);
+  if (typeof obj?.openapi === "string") return true;
+  return parent === "headers" && !!obj && ("type" in obj || "schema" in obj || "$ref" in obj);
+}
+function collectProviderSecrets(value) {
+  const secrets = [];
+  function visit(item, sensitive = false, contract = false, parent) {
+    if (typeof item === "string" && sensitive && item) secrets.push(item);
+    else if (Array.isArray(item)) item.forEach((v) => visit(v, sensitive, contract, parent));
+    else if (object(item)) {
+      for (const [key, val] of Object.entries(item)) {
+        const definition = !sensitive && (contract || isContract(key, val, parent));
+        visit(val, sensitive || !definition && SECRET_FIELD.test(key), definition, key);
+      }
+    }
+  }
+  visit(value);
+  return secrets;
+}
+function redactProvider(value, knownSecrets = []) {
+  const secrets = [.../* @__PURE__ */ new Set([...knownSecrets, ...collectProviderSecrets(value)])].filter(Boolean).sort((a, b) => b.length - a.length);
+  function visit(item, contract = false, parent) {
+    if (typeof item === "string") {
+      return secrets.reduce((text, secret) => text.split(secret).join("[REDACTED]"), item);
+    }
+    if (Array.isArray(item)) return item.map((val) => visit(val, contract, parent));
+    if (object(item)) return Object.fromEntries(Object.entries(item).map(([key, val]) => {
+      const definition = contract || isContract(key, val, parent);
+      return [key, !definition && SECRET_FIELD.test(key) ? "[REDACTED]" : visit(val, definition, key)];
+    }));
+    return item;
+  }
+  return visit(value);
+}
+
+// src/commands/provider-onboarding.ts
+var PROVIDER_ONBOARDING_HELP = `xapi-to provider - Import and publish your API services
+
+COMMANDS
+  spec-rules                       Read current OpenAPI rules (public)
+  import --file openapi.json        Create a DRAFT service from OpenAPI JSON
+    --private-headers-file <path>   Upstream credentials as a JSON object
+  update <service-id> --revision <id> --file config.json
+    --mode merge|replace           PATCH merge (default) or PUT replacement
+    --allow-new-endpoints          Allow merge entries without IDs to create endpoints
+  submit <service-id> --revision <id>
+    --changelog <text>             Submit for review; this alone is not publication
+  review <service-id> --revision <id>
+                                   Read latest review and previous attempts
+  wait <service-id> --revision <id>
+    --interval <duration>          Poll interval (default: 2s; ms/s/m/h)
+    --timeout <duration>           Overall deadline (default: 10m; ms/s/m/h)
+    --max-attempts <number>         Optional cap, including transient failures
+
+COMMON FLAGS
+  --format json|pretty|table
+  --help
+
+Files must contain JSON objects; --file - reads stdin. Import reads a raw
+OpenAPI spec; update reads version configuration (not a raw OpenAPI spec).
+Merge updates to existing endpoints require their IDs. Use --mode replace
+to replace the endpoint list, or --allow-new-endpoints to intentionally add.
+Saving a draft configuration moves it to SANDBOX, ready for submit.
+
+PERMISSIONS
+  import: service:create (legacy allowRegister also accepted)
+  list/get/review/wait: service:read; update: service:update
+  submit: service:publish. Grant scopes in the xAPI Console API Keys settings.
+
+wait succeeds only for PUBLISHED. Rejection, unpublished terminal states,
+manual review, invalid responses, and timeouts exit nonzero with details.
+Writes are not retried automatically. Credentials are redacted from output.
+`;
+var FLAGS = {
+  "spec-rules": [],
+  import: ["file", "private-headers-file"],
+  update: ["revision", "file", "mode", "allow-new-endpoints"],
+  submit: ["revision", "changelog"],
+  review: ["revision"],
+  wait: ["revision", "interval", "timeout", "max-attempts"]
+};
+var SCOPES = {
+  import: "service:create",
+  update: "service:update",
+  submit: "service:publish",
+  review: "service:read",
+  wait: "service:read"
+};
+function flag(flags, name, required3 = false) {
+  const value = flags[name];
+  if (required3 && value === void 0 || value === "" || value === "true") {
+    throw new Error(`--${name} requires a value`);
+  }
+  return value;
+}
+function duration(raw, name) {
+  const match = /^(\d+)(ms|s|m|h)?$/.exec(raw);
+  const units = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+  const ms = match ? Number(match[1]) * units[match[2] || "ms"] : NaN;
+  if (!Number.isSafeInteger(ms) || ms <= 0 || ms > 2147483647) {
+    throw new Error(`--${name} must be a positive duration (ms/s/m/h), at most 2147483647ms`);
+  }
+  return ms;
+}
+async function jsonFile(path) {
+  let text;
+  try {
+    if (path === "-") {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+      text = Buffer.concat(chunks).toString("utf8");
+    } else text = await readFile2(path, "utf8");
+  } catch {
+    throw new Error("Could not read JSON input file");
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error("Input must be valid JSON (JSON objects only; YAML is not supported)");
+  }
+  const result = object(value);
+  if (!result) throw new Error("Input must be a JSON object");
+  return result;
+}
+function segment(value) {
+  const normalized = value.trim();
+  if (!normalized || normalized === "." || normalized === "..") {
+    throw new Error("Invalid service or revision ID");
+  }
+  return encodeURIComponent(normalized);
+}
+async function providerOnboarding(args, flags) {
+  const [command, ...rest] = args;
+  if (flags.help || !command) {
+    console.log(PROVIDER_ONBOARDING_HELP);
+    return;
+  }
+  const secrets = [];
+  const emit = (value) => output(redactProvider(value, secrets), flags.format);
+  try {
+    if (!Object.hasOwn(FLAGS, command)) throw new Error(`Unknown provider command: ${command}`);
+    for (const key of Object.keys(flags)) {
+      if (!["format", ...FLAGS[command]].includes(key)) throw new Error(`Unknown flag for provider ${command}: --${key}`);
+    }
+    const needsService = !["spec-rules", "import"].includes(command);
+    if (rest.length !== (needsService ? 1 : 0)) throw new Error(`provider ${command} expects ${needsService ? "one service ID" : "no positional arguments"}`);
+    const serviceId = rest[0];
+    const base = serviceId ? `services/${segment(serviceId)}` : "services";
+    const revisionId = flag(flags, "revision", ["update", "submit", "review", "wait"].includes(command));
+    const revisionPath = revisionId ? `${base}/revisions/${segment(revisionId)}` : "";
+    const cfg = getConfig();
+    if (cfg.apiKey) secrets.push(cfg.apiKey);
+    if (command !== "spec-rules") requireApiKey(cfg);
+    const read = (path) => providerRequest(path, cfg.apiKey);
+    if (command === "spec-rules") {
+      emit(await providerRequest("spec-rules", void 0));
+      return;
+    }
+    if (command === "import") {
+      const file = flag(flags, "file", true);
+      const headersFile = flag(flags, "private-headers-file");
+      if (file === "-" && headersFile === "-") throw new Error("Only one input may read stdin");
+      const spec = await jsonFile(file);
+      const body = { openApiSpec: spec };
+      if (headersFile) {
+        body.privateHeaders = await jsonFile(headersFile);
+        if (Object.values(body.privateHeaders).some((v) => typeof v !== "string")) {
+          throw new Error("Private header values must be strings");
+        }
+      }
+      secrets.push(...collectProviderSecrets(body));
+      const result = await providerRequest("register-api-service", cfg.apiKey, "POST", body);
+      if (result?.success === false) {
+        emit(result);
+        process.exitCode = 1;
+        return;
+      }
+      const service = object(result?.apiService);
+      if (result?.success !== true || typeof service?.id !== "string") {
+        throw new Error("Unexpected import response; creation may have succeeded. Check provider list before retrying");
+      }
+      const active = object(service.activeVersion);
+      const revision = active ?? (Array.isArray(service.versions) ? object(service.versions[0]) : void 0);
+      emit({
+        ...result,
+        serviceId: service.id,
+        revisionId: revision?.id ?? service.activeVersionId ?? null,
+        state: revision?.state ?? service.status ?? null
+      });
+      return;
+    }
+    if (command === "update") {
+      const mode = flag(flags, "mode") ?? "merge";
+      if (!["merge", "replace"].includes(mode)) throw new Error("--mode must be merge or replace");
+      if (flags["allow-new-endpoints"] !== void 0 && flags["allow-new-endpoints"] !== "true") {
+        throw new Error("--allow-new-endpoints is a boolean flag");
+      }
+      const body = await jsonFile(flag(flags, "file", true));
+      secrets.push(...collectProviderSecrets(body));
+      if ("openapi" in body) throw new Error("update expects version configuration, not a raw OpenAPI spec");
+      if (body.endpoints !== void 0) {
+        if (!Array.isArray(body.endpoints) || body.endpoints.some((ep) => !object(ep))) throw new Error("endpoints must be an array of objects");
+        if (mode === "merge" && !flags["allow-new-endpoints"] && body.endpoints.some((ep) => typeof ep.id !== "string" || !ep.id.trim())) {
+          throw new Error("Merge endpoints require IDs. Use --mode replace for a full list, or --allow-new-endpoints to intentionally create endpoints");
+        }
+      }
+      const revision = await providerRequest(`${base}/versions/${segment(revisionId)}`, cfg.apiKey, mode === "merge" ? "PATCH" : "PUT", body);
+      emit({ serviceId, revisionId, state: revision?.state ?? null, revision });
+      return;
+    }
+    if (command === "submit") {
+      const changelog = flag(flags, "changelog");
+      if (changelog !== void 0 && changelog.length > 2e3) {
+        throw new Error("--changelog must be at most 2000 characters");
+      }
+      const submission = await providerRequest(`${revisionPath}/submit`, cfg.apiKey, "POST", changelog ? { changelog } : {});
+      emit({ serviceId, revisionId, submission });
+      return;
+    }
+    if (command === "review") {
+      emit(await read(`${revisionPath}/review`));
+      return;
+    }
+    const intervalMs = duration(flag(flags, "interval") ?? "2s", "interval");
+    const timeoutMs = duration(flag(flags, "timeout") ?? "10m", "timeout");
+    const attemptsFlag = flag(flags, "max-attempts");
+    const maxAttempts = attemptsFlag === void 0 ? Infinity : Number(attemptsFlag);
+    if (attemptsFlag !== void 0 && (!/^\d+$/.test(attemptsFlag) || !Number.isSafeInteger(maxAttempts) || maxAttempts <= 0)) {
+      throw new Error("--max-attempts must be a positive integer");
+    }
+    const deadline = Date.now() + timeoutMs;
+    let attempts = 0;
+    let last;
+    while (true) {
+      if (Date.now() >= deadline) {
+        emit({ serviceId, revisionId, success: false, reason: "timeout", attempts, last });
+        process.exitCode = 1;
+        return;
+      }
+      let delay = intervalMs;
+      let report;
+      let received = false;
+      attempts++;
+      try {
+        report = await providerRequest(`${revisionPath}/review`, cfg.apiKey, "GET", void 0, Math.max(1, deadline - Date.now()), 0);
+        received = true;
+      } catch (e) {
+        if (!isRetryableRequestError(e)) throw e;
+        if (e instanceof HttpError && e.retryAfterMs !== void 0) delay = Math.max(intervalMs, e.retryAfterMs);
+      }
+      if (Date.now() >= deadline) continue;
+      if (received) {
+        const revision = object(report?.revision);
+        const state = revision?.state;
+        if (revision?.id !== revisionId || !["DRAFT", "SANDBOX", "IN_REVIEW", "PUBLISHED", "SUSPENDED"].includes(String(state))) {
+          throw new Error("Invalid review response: expected requested revision ID and known state");
+        }
+        last = report;
+        const review = object(report?.review);
+        const manual = review?.outcome === "pending_human" || review?.status === "PENDING_HUMAN";
+        const rejected = review?.outcome === "rejected" || ["REJECTED", "AUTO_FAILED"].includes(String(review?.status));
+        if (state === "PUBLISHED" || state !== "IN_REVIEW" || manual || rejected) {
+          const success = state === "PUBLISHED";
+          emit({ ...report, serviceId, revisionId, success, reason: success ? "published" : manual ? "manual_review_required" : rejected ? "rejected" : "not_published" });
+          if (!success) process.exitCode = 1;
+          return;
+        }
+      }
+      if (attempts >= maxAttempts) {
+        emit({ serviceId, revisionId, success: false, reason: "max_attempts", attempts, last });
+        process.exitCode = 1;
+        return;
+      }
+      await new Promise((resolve4) => setTimeout(resolve4, Math.min(delay, Math.max(0, deadline - Date.now()))));
+    }
+  } catch (e) {
+    let message;
+    if (e instanceof HttpError) {
+      message = `HTTP ${e.status}`;
+      if (e.status === 403) message += `: requires ${SCOPES[command]}; check key permissions, service ownership, and IP restrictions in the xAPI Console`;
+      else if (e.status === 401) message += ": invalid or expired API key";
+      else if (e.status === 400) message += ": request rejected; check spec-rules, configuration, and revision state";
+      else if (e.status === 409 && /"code"\s*:\s*"REVISION_NOT_EDITABLE"/.test(e.message)) {
+        message += ": revision is not editable. Only DRAFT or SANDBOX can be updated; use a working revision for changes to a published API";
+      }
+      if (["import", "update", "submit"].includes(command)) message += ". No automatic retry was made; inspect provider list/get/review before retrying";
+    } else message = e instanceof SyntaxError ? "Invalid JSON response from provider API" : e instanceof Error ? e.message : "Unknown error";
+    err(`provider ${command} failed`, redactProvider(message, secrets));
+  }
+}
+
+// src/commands/provider.ts
+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 spec-rules
+  xapi-to provider import --file <openapi.json> [--private-headers-file <path>]
+  xapi-to provider update <service-id> --revision <id> --file <contract.json>
+  xapi-to provider submit <service-id> --revision <id> [--changelog <text>]
+  xapi-to provider wait <service-id> --revision <id> [--interval 2s] [--timeout 10m]
+  xapi-to provider list
+  xapi-to provider get <service-id> [--version <version>]
+  xapi-to provider create --file <service.json> [rate-limit flags]
+  xapi-to provider update <service-id> [metadata/rate-limit 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
+
+SERVICE RATE-LIMIT FLAGS
+  --rate-limit-requests <count>          Allowed requests per period (1-1000000)
+  --rate-limit-period-seconds <seconds>  Period length in seconds (1-86400)
+  --clear-rate-limit                     Disable the service rate limit
+
+Set both numeric flags together. Limits apply only to PROXY services and use
+one shared quota for each user and service, including all API keys of that user.
+
+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());
+}
+function applyRateLimitFlags(body, flags) {
+  const requests = flags["rate-limit-requests"];
+  const periodSeconds = flags["rate-limit-period-seconds"];
+  const clear = boolFlag(flags, "clear-rate-limit");
+  if (clear && (requests !== void 0 || periodSeconds !== void 0)) {
+    err("--clear-rate-limit cannot be combined with --rate-limit-requests or --rate-limit-period-seconds");
+  }
+  if (requests === void 0 !== (periodSeconds === void 0)) {
+    err("--rate-limit-requests and --rate-limit-period-seconds must be provided together");
+  }
+  if (clear) {
+    body.rateLimitConfig = null;
+  } else if (requests !== void 0) {
+    body.rateLimitConfig = {
+      requests: positiveInt(requests, "--rate-limit-requests", 1e6),
+      periodSeconds: positiveInt(periodSeconds, "--rate-limit-period-seconds", 86400)
+    };
+  }
+  return body;
+}
+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 readFile3(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`);
+  const text = await readText(path, flagName);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    err(`invalid JSON from ${flagName}`, "Input must be valid JSON.");
+  }
+  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;
+  applyRateLimitFlags(body, flags);
+  if (Object.keys(body).length === 0) {
+    err("no provider settings supplied", "Pass --file or at least one metadata or rate-limit 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 + "\n" + PROVIDER_ONBOARDING_HELP);
+    return;
+  }
+  const onboardingCommand = ["spec-rules", "import", "submit", "wait"].includes(args[0]);
+  const revisionAlias = ["update", "review"].includes(args[0]) && flags.revision !== void 0;
+  if (onboardingCommand || revisionAlias) return providerOnboarding(args, flags);
+  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": {
+        const body = await readJsonObject(required(flags.file, "xapi-to provider create --file <service.json>"));
+        applyRateLimitFlags(body, flags);
+        result = await apiKeyApiRequest(XAPI_API_HOST, apiKey, `${BASE}/services`, {
+          method: "POST",
+          body
+        });
+        break;
+      }
+      case "update": {
+        const id = required(rest[0], "xapi-to provider update <service-id> [metadata/rate-limit 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(redactProvider(result, [apiKey]), flags.format);
+  } catch (error) {
+    const message = error instanceof HttpError ? `HTTP ${error.status}` : String(redactProvider(error instanceof Error ? error.message : "Unknown error", [apiKey]));
+    err("provider request failed", message);
+  }
+}
+
+// src/commands/skill.ts
+import { readdir, readFile as readFile4 } 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 readFile4(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 = [];
@@ -2483,6 +3639,16 @@ COMMANDS
     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
@@ -2492,6 +3658,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
@@ -2533,6 +3707,14 @@ EXAMPLES
   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() {
@@ -2568,6 +3750,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());
@@ -2660,6 +3846,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":