xapi-to 0.1.16 → 0.1.18

package/README.md

@@ -66,6 +66,16 @@ xapi-to get twitter.tweet_detail                        # get action schema
 xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'  # execute
 ```
 
+### Async Task Commands
+
+Task helpers built on top of the `task.poll` capability.
+
+```bash
+xapi-to task poll 550e8400-e29b-41d4-a716-446655440000                 # poll once
+xapi-to task wait 550e8400-e29b-41d4-a716-446655440000                 # wait until terminal status
+xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m
+```
+
 ### OAuth
 
 Bind third-party OAuth accounts (e.g. Twitter) to your API key.
@@ -112,6 +122,15 @@ xapi-to get twitter.tweet_detail
 xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
 ```
 
+For APIs that return binary data, use `--output` to request raw bytes and save
+them directly. The CLI refuses to overwrite an existing file.
+
+```bash
+xapi-to call openrouter.audio_speech \
+  --input '{"body":{"input":"Hello","model":"hexgrad/kokoro-82m","voice":"af_bella"}}' \
+  --output speech.mp3
+```
+
 ## Output Formats
 
 All output is JSON by default — designed for agent consumption.

package/dist/index.js

@@ -100,7 +100,43 @@ import { join } from "path";
 var XAPI_ACTION_HOST = process.env.XAPI_ACTION_HOST || "action.xapi.to";
 var XAPI_API_HOST = process.env.XAPI_API_HOST || "api.xapi.to";
 function scheme(host) {
-  return host.startsWith("localhost") || host.startsWith("127.") ? "http" : "https";
+  return isLoopbackHost(host) ? "http" : "https";
+}
+var ALLOWED_HOST_EXACT = ["xapi.to", "xapi.xyz"];
+var ALLOWED_HOST_SUFFIXES = [".xapi.to", ".xapi.xyz"];
+function hostnameOf(hostOrUrl) {
+  const raw = hostOrUrl.includes("://") ? hostOrUrl : `http://${hostOrUrl}`;
+  try {
+    return new URL(raw).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+function isLoopbackIPv4(h) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+  if (!m) return false;
+  const octets = m.slice(1).map(Number);
+  return octets.every((o) => o <= 255) && octets[0] === 127;
+}
+function isLoopbackHostname(h) {
+  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "[::1]" || isLoopbackIPv4(h);
+}
+function isLoopbackHost(hostOrUrl) {
+  return isLoopbackHostname(hostnameOf(hostOrUrl));
+}
+function isAllowedHost(hostOrUrl) {
+  const h = hostnameOf(hostOrUrl);
+  if (!h) return false;
+  if (isLoopbackHostname(h)) return true;
+  if (ALLOWED_HOST_EXACT.includes(h)) return true;
+  return ALLOWED_HOST_SUFFIXES.some((suffix) => h.endsWith(suffix));
+}
+function assertAllowedHost(hostOrUrl) {
+  if (!isAllowedHost(hostOrUrl)) {
+    throw new Error(
+      `refusing to contact untrusted host "${hostnameOf(hostOrUrl) || hostOrUrl}": the xapi API key may only be sent to *.xapi.to, *.xapi.xyz, or localhost`
+    );
+  }
 }
 var CONFIG_DIR = join(homedir(), ".xapi");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -144,41 +180,134 @@ function showConfig() {
 }
 
 // src/client.ts
+import { open, rm } from "fs/promises";
+import { resolve } from "path";
+import { Readable, Transform } from "stream";
+import { pipeline } from "stream/promises";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var EXECUTE_TIMEOUT_MS = 6e4;
-async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetch(url, { ...options, signal: controller.signal });
-    if (!res.ok) {
-      const text2 = await res.text();
-      throw new Error(`HTTP ${res.status}: ${text2.slice(0, 300)}`);
-    }
-    if (res.status === 204) {
-      return void 0;
-    }
-    const text = await res.text();
-    if (!text.trim()) {
-      return void 0;
-    }
-    const body = JSON.parse(text);
-    if (body && typeof body === "object" && "success" in body && body.success === false) {
-      const data = body.data;
-      if (data?.statusCode === 401 || data?.error === "Unauthorized") {
+var IDEMPOTENT_RETRIES = 2;
+var RETRY_BASE_DELAY_MS = 500;
+var RETRY_MAX_DELAY_MS = 8e3;
+var HttpError = class extends Error {
+  constructor(status, detail, retryAfterMs) {
+    super(`HTTP ${status}: ${detail}`);
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "HttpError";
+  }
+  status;
+  retryAfterMs;
+};
+var RequestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`request timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "RequestTimeoutError";
+  }
+  timeoutMs;
+};
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
+}
+function isRetryableNetworkError(e) {
+  if (!(e instanceof Error)) return false;
+  if (e instanceof HttpError || e instanceof RequestTimeoutError) return false;
+  if (e.name === "AbortError") return false;
+  return e instanceof TypeError || /network|fetch failed|econn|etimedout|eai_again|socket|dns/i.test(e.message);
+}
+function isRetryableRequestError(e) {
+  if (e instanceof HttpError) return isRetryableStatus(e.status);
+  if (e instanceof RequestTimeoutError) return true;
+  return isRetryableNetworkError(e);
+}
+function retryBaseDelayMs() {
+  const override = Number(process.env.XAPI_RETRY_BASE_MS);
+  return Number.isFinite(override) && override > 0 ? override : RETRY_BASE_DELAY_MS;
+}
+function backoffDelayMs(attempt, retryAfterMs) {
+  if (retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
+    return Math.min(retryAfterMs, RETRY_MAX_DELAY_MS);
+  }
+  const capped = Math.min(retryBaseDelayMs() * 2 ** attempt, RETRY_MAX_DELAY_MS);
+  return capped / 2 + Math.random() * (capped / 2);
+}
+function parseRetryAfterMs(res) {
+  const header = res.headers.get("retry-after");
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return seconds * 1e3;
+  const at = Date.parse(header);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0) {
+  assertAllowedHost(url);
+  let attempt = 0;
+  while (true) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    try {
+      const res = await fetch(url, { ...options, redirect: "manual", signal: controller.signal });
+      if (res.status >= 300 && res.status < 400) {
         throw new Error(
-          "Authentication failed: " + (data.message || "Invalid or missing API key") + '. Run "npx xapi-to config set apiKey=<key>" to update your key.'
+          `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
         );
       }
-      if (data?.error === "OAuth Required" || data?.statusCode === 403 && data?.message?.includes("OAuth")) {
-        throw new Error(
-          (data.message || "OAuth authorization required") + '. Run "xapi-to oauth bind" to connect your account.'
-        );
+      if (!res.ok) {
+        const retryAfterMs = isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0;
+        if (isRetryableStatus(res.status) && attempt < retries) {
+          await res.text().catch(() => "");
+          clearTimeout(timer);
+          await sleep(backoffDelayMs(attempt, retryAfterMs));
+          attempt++;
+          continue;
+        }
+        const text2 = await res.text();
+        throw new HttpError(res.status, text2.slice(0, 300), retryAfterMs);
+      }
+      if (res.status === 204) {
+        return void 0;
+      }
+      const text = await res.text();
+      if (!text.trim()) {
+        return void 0;
+      }
+      const body = JSON.parse(text);
+      if (body && typeof body === "object" && "success" in body && body.success === false) {
+        const data = body.data;
+        if (data?.statusCode === 401 || data?.error === "Unauthorized") {
+          throw new Error(
+            "Authentication failed: " + (data.message || "Invalid or missing API key") + '. Run "npx xapi-to config set apiKey=<key>" to update your key.'
+          );
+        }
+        if (data?.error === "OAuth Required" || data?.statusCode === 403 && data?.message?.includes("OAuth")) {
+          throw new Error(
+            (data.message || "OAuth authorization required") + '. Run "xapi-to oauth bind" to connect your account.'
+          );
+        }
       }
+      return body;
+    } catch (e) {
+      if (timedOut) {
+        throw new RequestTimeoutError(timeoutMs);
+      }
+      if (isRetryableNetworkError(e) && attempt < retries) {
+        clearTimeout(timer);
+        await sleep(backoffDelayMs(attempt));
+        attempt++;
+        continue;
+      }
+      throw e;
+    } finally {
+      clearTimeout(timer);
     }
-    return body;
-  } finally {
-    clearTimeout(timer);
   }
 }
 function headers(apiKey) {
@@ -198,7 +327,9 @@ async function actionList(opts, params = {}) {
   if (params.service_id) url.searchParams.set("service_id", params.service_id);
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function actionSearch(query, opts, params = {}) {
@@ -210,7 +341,9 @@ async function actionSearch(query, opts, params = {}) {
   if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function actionCategories(opts, params = {}) {
@@ -218,16 +351,20 @@ async function actionCategories(opts, params = {}) {
   if (params.source) url.searchParams.set("source", params.source);
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function actionGet(id, opts) {
   return request(
     `${baseUrl(opts)}/v1/actions/${encodeURIComponent(id)}`,
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
-async function actionCall(actionId, input, opts, httpMethod) {
+async function actionCall(actionId, input, opts, httpMethod, retries = 0, timeoutMs = EXECUTE_TIMEOUT_MS) {
   return request(
     `${baseUrl(opts)}/v1/actions/execute`,
     {
@@ -235,9 +372,88 @@ async function actionCall(actionId, input, opts, httpMethod) {
       headers: headers(opts.apiKey),
       body: JSON.stringify({ action_id: actionId, ...httpMethod ? { method: httpMethod } : {}, input })
     },
-    EXECUTE_TIMEOUT_MS
+    Math.min(timeoutMs, EXECUTE_TIMEOUT_MS),
+    retries
   );
 }
+async function actionDownload(actionId, input, opts, outputPath, httpMethod) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, EXECUTE_TIMEOUT_MS);
+  const target = resolve(outputPath);
+  let file;
+  let complete = false;
+  try {
+    try {
+      file = await open(target, "wx");
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        throw new Error(`Output file already exists: ${target}`);
+      }
+      throw error;
+    }
+    const url = `${baseUrl(opts)}/v1/actions/execute`;
+    assertAllowedHost(url);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: headers(opts.apiKey),
+      body: JSON.stringify({
+        action_id: actionId,
+        ...httpMethod ? { method: httpMethod } : {},
+        input,
+        response_mode: "raw"
+      }),
+      redirect: "manual",
+      signal: controller.signal
+    });
+    if (res.status >= 300 && res.status < 400) {
+      throw new Error(
+        `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
+      );
+    }
+    if (!res.ok) {
+      const text = await res.text();
+      throw new HttpError(
+        res.status,
+        text.slice(0, 300),
+        isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0
+      );
+    }
+    let bytes = 0;
+    if (res.body) {
+      const source = Readable.fromWeb(res.body);
+      const counter = new Transform({
+        transform(chunk, _encoding, callback) {
+          bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
+          callback(null, chunk);
+        }
+      });
+      await pipeline(source, counter, file.createWriteStream());
+    } else {
+      await file.close();
+    }
+    complete = true;
+    return {
+      output: target,
+      bytes,
+      contentType: res.headers.get("content-type") || void 0,
+      contentDisposition: res.headers.get("content-disposition") || void 0,
+      status: res.status
+    };
+  } catch (error) {
+    if (timedOut) throw new RequestTimeoutError(EXECUTE_TIMEOUT_MS);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    if (!complete && file) {
+      await file.close().catch(() => void 0);
+      await rm(target, { force: true }).catch(() => void 0);
+    }
+  }
+}
 async function actionServices(opts, params = {}) {
   const url = new URL(`${baseUrl(opts)}/v1/actions/services`);
   if (params.page) url.searchParams.set("page", String(params.page));
@@ -245,14 +461,18 @@ async function actionServices(opts, params = {}) {
   if (params.category) url.searchParams.set("category", params.category);
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function healthCheck(opts) {
   return request(
     `${baseUrl(opts)}/health`,
     { method: "GET", headers: headers(opts.apiKey) },
-    5e3
+    5e3,
+    0
+    // health is a quick connectivity probe — fail fast, don't retry
   );
 }
 async function loginWithApiKey(apiKey, apiHost) {
@@ -262,7 +482,10 @@ async function loginWithApiKey(apiKey, apiHost) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ apiKey })
-    }
+    },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
+    // auth exchange has no side effect — safe to retry
   );
 }
 function jwtHeaders(jwtToken) {
@@ -271,7 +494,9 @@ function jwtHeaders(jwtToken) {
 async function listKeys(jwtToken, apiHost) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/keys`,
-    { method: "GET", headers: jwtHeaders(jwtToken) }
+    { method: "GET", headers: jwtHeaders(jwtToken) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
@@ -287,7 +512,9 @@ async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
 async function listOAuthProviders(apiHost) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/providers`,
-    { method: "GET", headers: { "Content-Type": "application/json" } }
+    { method: "GET", headers: { "Content-Type": "application/json" } },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost, scopes) {
@@ -305,7 +532,9 @@ async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost, scopes) {
 async function listOAuthBindings(jwtToken, apiHost) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
-    { method: "GET", headers: jwtHeaders(jwtToken) }
+    { method: "GET", headers: jwtHeaders(jwtToken) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function deleteOAuthBinding(bindingId, jwtToken, apiHost) {
@@ -648,6 +877,7 @@ USAGE
 FLAGS
   --input <json>            Input payload as JSON (required for execution)
   --method GET|POST|...     Override HTTP method
+  --output <path>           Save a raw binary response to a new file
   --code <target>           Generate code snippet instead of executing
   --format json|pretty|table  Output format
 
@@ -670,6 +900,7 @@ CODE TARGETS
 
 EXAMPLES
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi-to call openrouter.audio_speech --input '{"body":{"input":"Hello"}}' --output speech.mp3
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"123"}' --code py
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"123"}' --code curl --format pretty
 `;
@@ -838,6 +1069,10 @@ async function actionCall2(args, flags) {
   const id = args[0];
   if (!id) err(`usage: xapi-to call <id> --input '{"key":"val"}'`);
   if (flags.code) validateCodeFlag(flags);
+  if (flags.output === "true") err("--output requires a file path");
+  if (flags.code && flags.output) {
+    err("--output cannot be combined with --code");
+  }
   const cfg = getConfig();
   let input = {};
   if (flags.input) {
@@ -859,6 +1094,27 @@ async function actionCall2(args, flags) {
   }
   requireApiKey(cfg);
   try {
+    if (flags.output) {
+      const result = await actionDownload(
+        id,
+        cleanInput,
+        cfg,
+        flags.output,
+        method
+      );
+      output(
+        {
+          success: true,
+          output: result.output,
+          bytes: result.bytes,
+          status: result.status,
+          content_type: result.contentType,
+          content_disposition: result.contentDisposition
+        },
+        flags.format
+      );
+      return;
+    }
     const res = await actionCall(id, cleanInput, cfg, method);
     output(res, flags.format);
   } catch (e) {
@@ -874,6 +1130,7 @@ __export(config_exports, {
   configSet: () => configSet,
   configShow: () => configShow
 });
+import { readFileSync as readFileSync2 } from "fs";
 var CONFIG_HELP = `xapi-to config - Manage CLI configuration
 
 USAGE
@@ -881,7 +1138,7 @@ USAGE
 
 COMMANDS
   show                       Show current config (host, apiKey path, etc.)
-  set apiKey=<key>           Save API key to ~/.xapi/config.json
+  set apiKey=<key>           Save API key to ~/.xapi/config.json (apiKey=- reads from stdin)
   health                     Check backend connectivity (alias: xapi-to health)
 
 FLAGS
@@ -890,6 +1147,7 @@ FLAGS
 EXAMPLES
   xapi-to config show
   xapi-to config set apiKey=xapi_abc123
+  echo "$XAPI_KEY" | xapi-to config set apiKey=-   # keeps the key out of shell history
   xapi-to config health
 `;
 async function configShow(args, flags) {
@@ -904,7 +1162,12 @@ async function configSet(args, flags) {
     const key = arg.slice(0, eq);
     if (key === "host") err("host is built-in and cannot be configured");
     if (key !== "apiKey") err(`unknown config key: ${key} (only apiKey is configurable)`);
-    updates.apiKey = arg.slice(eq + 1);
+    let value = arg.slice(eq + 1);
+    if (value === "-") {
+      value = readFileSync2(0, "utf-8").trim();
+    }
+    if (!value) err("apiKey is empty");
+    updates.apiKey = value;
   }
   saveConfig(updates);
   console.log(JSON.stringify({ ok: true, updated: Object.keys(updates) }));
@@ -923,6 +1186,7 @@ async function configHealth(args, flags) {
 
 // src/commands/register.ts
 async function registerAccount(referralCode) {
+  assertAllowedHost(XAPI_API_HOST);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 15e3);
   try {
@@ -1070,15 +1334,13 @@ async function findCurrentKeyRecord(plaintextKey, jwtToken) {
   if (!Array.isArray(keys) || keys.length === 0) {
     throw new Error("No API keys found for this account");
   }
-  if (keys.length === 1) return keys[0];
   const prefix = plaintextKey.substring(0, 7);
   const match = keys.find((k) => k.keyPreview.startsWith(prefix));
-  if (!match) {
-    throw new Error(
-      `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.`
-    );
-  }
-  return match;
+  if (match) return match;
+  if (keys.length === 1) return keys[0];
+  throw new Error(
+    `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) {
@@ -1130,7 +1392,7 @@ async function selectScopesInteractive(provider) {
     out.write("\x1B[J");
     out.write(buildFrame());
   };
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const { stdin } = process;
     const wasRaw = stdin.isRaw;
     stdin.setRawMode(true);
@@ -1141,7 +1403,7 @@ async function selectScopesInteractive(provider) {
       stdin.pause();
       out.write("\x1B[?25h");
       out.write("\n");
-      resolve(result);
+      resolve2(result);
     };
     const onData = (buf) => {
       const key = buf.toString();
@@ -1358,19 +1620,217 @@ async function oauthProviders(args, flags) {
   }
 }
 
-// src/index.ts
-var { CONFIG_HELP: CONFIG_HELP2 } = config_exports;
-var { OAUTH_HELP: OAUTH_HELP2 } = oauth_exports;
+// src/commands/task.ts
+var POLL_HELP = `xapi-to task poll - Poll an async task once
+
+USAGE
+  xapi-to task poll <task_id> [flags]
+
+FLAGS
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
+`;
+var WAIT_HELP = `xapi-to task wait - Wait until async task reaches terminal status
+
+USAGE
+  xapi-to task wait <task_id> [flags]
+
+FLAGS
+  --interval <duration>       Poll interval (default: 2s). Supports ms/s/m/h
+  --timeout <duration>        Max wait duration (optional). Supports ms/s/m/h
+  --max-attempts <number>     Max poll attempts (optional)
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m
+`;
+var TASK_HELP = `xapi-to task - Async task helpers
+
+USAGE
+  xapi-to task <command> [args] [flags]
+
+COMMANDS
+  poll <task_id>              Poll task status once (wraps action: task.poll)
+  wait <task_id>              Poll repeatedly until terminal status
+
+EXAMPLES
+  xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 2s --timeout 10m
+`;
+function showHelpIfRequested2(flags, helpText) {
+  if (flags.help) {
+    console.log(helpText);
+    process.exit(0);
+  }
+}
+function parseDurationMs(raw) {
+  const text = raw.trim().toLowerCase();
+  const match = text.match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match) {
+    err(`invalid duration "${raw}". Use formats like 500ms, 2s, 5m, 1h.`);
+  }
+  const value = Number(match[1]);
+  const unit = match[2] || "ms";
+  if (!Number.isFinite(value) || value < 0) {
+    err(`invalid duration "${raw}". Duration must be >= 0.`);
+  }
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 6e4;
+    case "h":
+      return value * 36e5;
+    default:
+      return value;
+  }
+}
+function parsePositiveDurationMs(raw, flagName) {
+  const ms = parseDurationMs(raw);
+  if (ms <= 0) {
+    err(`${flagName} must be greater than 0`);
+  }
+  return ms;
+}
+function parsePositiveInt(raw, flagName) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    err(`${flagName} must be a positive integer`);
+  }
+  return n;
+}
+function sleep2(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function extractTaskPayload(res) {
+  if (res && typeof res === "object") {
+    const obj = res;
+    if (typeof obj.status === "string") return obj;
+    if (obj.data && typeof obj.data === "object" && !Array.isArray(obj.data)) {
+      const dataObj = obj.data;
+      if (typeof dataObj.status === "string") return dataObj;
+    }
+  }
+  return res ?? {};
+}
+function getStatus(payload) {
+  const status = payload.status;
+  if (status === "pending" || status === "processing" || status === "succeeded" || status === "failed" || status === "expired") {
+    return status;
+  }
+  return void 0;
+}
+async function taskPoll(args, flags) {
+  showHelpIfRequested2(flags, POLL_HELP);
+  const taskId = args[0];
+  if (!taskId) err("usage: xapi-to task poll <task_id>");
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  try {
+    const res = await actionCall("task.poll", { task_id: taskId }, cfg, void 0, 2);
+    const payload = extractTaskPayload(res);
+    output(payload, flags.format);
+  } catch (e) {
+    err("task poll failed", e.message);
+  }
+}
+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 timeoutMs = flags.timeout ? parseDurationMs(flags.timeout) : void 0;
+  const maxAttempts = flags["max-attempts"] ? parsePositiveInt(flags["max-attempts"], "--max-attempts") : void 0;
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const startedAt = Date.now();
+  const deadline = timeoutMs !== void 0 ? startedAt + timeoutMs : void 0;
+  let attempts = 0;
+  while (true) {
+    if (deadline !== void 0 && Date.now() >= deadline) {
+      err(
+        "task wait timeout",
+        `task_id=${taskId}, elapsed_ms=${Date.now() - startedAt}, timeout_ms=${timeoutMs}`
+      );
+    }
+    attempts += 1;
+    let retryDelayMs;
+    try {
+      const remaining = deadline !== void 0 ? Math.max(1, deadline - Date.now()) : void 0;
+      const res = await actionCall("task.poll", { task_id: taskId }, cfg, void 0, 0, remaining);
+      const payload = extractTaskPayload(res);
+      const status = getStatus(payload);
+      if (!status) {
+        err("task wait failed", "task.poll returned invalid response: missing status");
+      }
+      if (status === "succeeded") {
+        output(payload, flags.format);
+        return;
+      }
+      if (status === "failed" || status === "expired") {
+        output(payload, flags.format);
+        process.exit(1);
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message === "process.exit") {
+        throw e;
+      }
+      if (deadline !== void 0 && Date.now() >= deadline) {
+        err(
+          "task wait timeout",
+          `task_id=${taskId}, elapsed_ms=${Date.now() - startedAt}, timeout_ms=${timeoutMs}`
+        );
+      }
+      if (isRetryableRequestError(e)) {
+        retryDelayMs = e instanceof HttpError ? e.retryAfterMs : void 0;
+      } else {
+        err("task wait failed", e.message);
+      }
+    }
+    if (maxAttempts && attempts >= maxAttempts) {
+      err(
+        "task wait exceeded max attempts",
+        `task_id=${taskId}, attempts=${attempts}, max_attempts=${maxAttempts}`
+      );
+    }
+    const desiredWaitMs = retryDelayMs ?? intervalMs;
+    const waitMs = deadline !== void 0 ? Math.min(desiredWaitMs, Math.max(0, deadline - Date.now())) : desiredWaitMs;
+    await sleep2(waitMs);
+  }
+}
+function taskHelp() {
+  return TASK_HELP;
+}
+
+// src/args.ts
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
   let i = 0;
+  let onlyPositional = false;
   while (i < argv.length) {
     const arg = argv[i];
-    if (arg.startsWith("--")) {
+    if (!onlyPositional && arg === "--") {
+      onlyPositional = true;
+      i++;
+      continue;
+    }
+    if (!onlyPositional && arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        i++;
+        continue;
+      }
       const key = arg.slice(2);
       const next = argv[i + 1];
-      if (next && !next.startsWith("--")) {
+      if (next !== void 0 && !next.startsWith("--")) {
         flags[key] = next;
         i += 2;
       } else {
@@ -1384,6 +1844,10 @@ function parseArgs(argv) {
   }
   return { positional, flags };
 }
+
+// src/index.ts
+var { CONFIG_HELP: CONFIG_HELP2 } = config_exports;
+var { OAUTH_HELP: OAUTH_HELP2 } = oauth_exports;
 var HELP = `xapi-to - agent-friendly CLI for xapi
 
 USAGE
@@ -1408,9 +1872,16 @@ COMMANDS
     --code <target>                  Generate code snippet (curl, py, js, ts, go)
   call <id> --input '{"key":"val"}'  Execute an action
     --method GET|POST|...            Override HTTP method
+    --output <path>                   Save a raw binary response to a new file
     --code <target>                  Generate code snippet instead of executing
     Variants: python.requests, python.httpx, javascript.fetch, javascript.axios
 
+  task poll <task_id>                Poll async task once (wraps task.poll)
+  task wait <task_id>                Wait until async task completes
+    --interval <duration>            Poll interval, e.g. 2s (default: 2s)
+    --timeout <duration>             Max wait duration, e.g. 10m
+    --max-attempts <number>          Max poll attempts
+
   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
@@ -1448,7 +1919,10 @@ EXAMPLES
   xapi-to get twitter.tweet_detail --code curl
   xapi-to get twitter.tweet_detail --code py --format pretty
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi-to call openrouter.audio_speech --input '{"body":{"input":"Hello"}}' --output speech.mp3
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}' --code python
+  xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 2s --timeout 10m
   xapi-to categories
   xapi-to services --format table
   xapi-to config set apiKey=xapi_abc123
@@ -1476,6 +1950,23 @@ async function main() {
       return actionGet2(rest, flags);
     case "call":
       return actionCall2(rest, flags);
+    case "task": {
+      if (rest.length === 0) {
+        console.log(taskHelp());
+        process.exit(0);
+      }
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case "poll":
+          return taskPoll(subRest, flags);
+        case "wait":
+          return taskWait(subRest, flags);
+        default:
+          console.error(JSON.stringify({ error: `unknown task command: ${subCmd}`, hint: "valid commands: poll, wait" }));
+          process.exit(1);
+      }
+      break;
+    }
     // ── OAuth commands ──
     case "oauth": {
       if (flags.help || rest.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xapi-to",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Agent-friendly CLI for xapi - discover and call capabilities and APIs",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --target node18 --clean --out-dir dist --tsconfig tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "dev": "XAPI_ACTION_HOST=localhost:3003 bun run src/index.ts",
     "prepublishOnly": "npm run build",