xapi-to 0.1.20 → 0.1.21

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-UEQCIJ7T.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, {
@@ -1038,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,
@@ -1051,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`);
     }
@@ -1088,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);
@@ -1099,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();
@@ -1178,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}`
@@ -1195,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();
@@ -1210,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);
             }
           }
@@ -1219,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 {
@@ -1234,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) {
@@ -1249,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
@@ -1260,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
@@ -1403,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`);
@@ -1417,9 +1615,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 +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();
@@ -1514,7 +1712,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 +1759,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 +1801,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 +1905,7 @@ var SELECTION_FLAGS = [
   "gpu-count",
   "gpu-model",
   "regions",
+  "min-runtime",
   "requirements",
   "max-hourly-usd"
 ];
@@ -1826,10 +2027,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 +2049,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 +2061,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 +2077,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 +2101,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 +2128,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 +2249,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 +2607,512 @@ async function sandboxRun(args, flags) {
   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 = [];
@@ -2483,6 +3197,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 +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
@@ -2533,6 +3265,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 +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());
@@ -2660,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":