@aexhq/sdk 0.37.3 → 0.38.0

package/dist/cli.mjs

@@ -22,7 +22,7 @@ var COMMON_EVIDENCE = [
 var ANTHROPIC_LIVE_USER_EVIDENCE = [
   {
     label: "Installed-SDK Anthropic live user test",
-    href: "../../../apps/user-tests/test/live/live-sdk-anthropic-managed.test.ts"
+    href: "../../../apps/user-tests/test/live/providers/live-sdk-anthropic-managed.test.ts"
   }
 ];
 var DEEPSEEK_LIVE_USER_EVIDENCE = [
@@ -652,6 +652,7 @@ var isTerminalType = (e) => e.type === "RUN_FINISHED" || e.type === "RUN_ERROR"
 var COORDINATOR_PING = "aex:ping";
 var DEFAULT_IDLE_TIMEOUT_MS = 45e3;
 var DEFAULT_PING_INTERVAL_MS = 15e3;
+var DEFAULT_EVENT_QUIET_RECHECK_MS = 9e4;
 async function* streamCoordinatorEvents(opts) {
   const makeWs = opts.webSocketFactory ?? ((url) => new WebSocket(url));
   const isTerminal = opts.isTerminal ?? isTerminalType;
@@ -659,6 +660,7 @@ async function* streamCoordinatorEvents(opts) {
   const maxReconnects = opts.maxReconnects ?? Number.POSITIVE_INFINITY;
   const idleTimeoutMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
   const pingIntervalMs = opts.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+  const eventQuietRecheckMs = opts.eventQuietRecheckMs ?? DEFAULT_EVENT_QUIET_RECHECK_MS;
   let cursor = (opts.from ?? 0) - 1;
   let attempts = 0;
   let done = false;
@@ -681,6 +683,7 @@ async function* streamCoordinatorEvents(opts) {
     };
     let idleTimer = null;
     let pingTimer = null;
+    let quietTimer = null;
     const stopTimers = () => {
       if (idleTimer !== null) {
         clearTimeout(idleTimer);
@@ -690,6 +693,10 @@ async function* streamCoordinatorEvents(opts) {
         clearInterval(pingTimer);
         pingTimer = null;
       }
+      if (quietTimer !== null) {
+        clearTimeout(quietTimer);
+        quietTimer = null;
+      }
     };
     const armIdle = () => {
       if (idleTimeoutMs <= 0)
@@ -706,6 +713,21 @@ async function* streamCoordinatorEvents(opts) {
         wake();
       }, idleTimeoutMs);
     };
+    const armQuiet = () => {
+      if (eventQuietRecheckMs <= 0)
+        return;
+      if (quietTimer !== null)
+        clearTimeout(quietTimer);
+      quietTimer = setTimeout(() => {
+        quietTimer = null;
+        if (closed)
+          return;
+        closed = true;
+        disconnectReason = "quiet_recheck";
+        closeQuietly(ws);
+        wake();
+      }, eventQuietRecheckMs);
+    };
     ws.addEventListener("open", () => {
       armIdle();
       if (pingIntervalMs > 0 && typeof ws.send === "function") {
@@ -724,9 +746,12 @@ async function* streamCoordinatorEvents(opts) {
         return;
       try {
         const evt = JSON.parse(data);
-        if (typeof evt.sequence === "number" && evt.sequence > cursor) {
-          queue.push(evt);
-          wake();
+        if (typeof evt.sequence === "number") {
+          armQuiet();
+          if (evt.sequence > cursor) {
+            queue.push(evt);
+            wake();
+          }
         }
       } catch {
       }
@@ -756,6 +781,7 @@ async function* streamCoordinatorEvents(opts) {
     };
     opts.signal?.addEventListener("abort", onAbort, { once: true });
     armIdle();
+    armQuiet();
     try {
       while (true) {
         while (queue.length > 0) {
@@ -778,6 +804,7 @@ async function* streamCoordinatorEvents(opts) {
     } finally {
       stopTimers();
       opts.signal?.removeEventListener("abort", onAbort);
+      closeQuietly(ws);
     }
     if (done || opts.signal?.aborted)
       return;
@@ -786,7 +813,9 @@ async function* streamCoordinatorEvents(opts) {
       console.warn(`[aex] event stream gave up after ${maxReconnects} reconnect attempt(s) (last: ${disconnectReason || "unknown"}); ended before a terminal event at seq ${cursor + 1}`);
       return;
     }
-    console.warn(`[aex] event stream disconnected (${disconnectReason || "unknown"}); reconnecting attempt ${attempts} from seq ${cursor + 1}`);
+    if (disconnectReason !== "quiet_recheck") {
+      console.warn(`[aex] event stream disconnected (${disconnectReason || "unknown"}); reconnecting attempt ${attempts} from seq ${cursor + 1}`);
+    }
     await sleep(reconnectDelayMs, opts.signal);
   }
 }
@@ -807,17 +836,17 @@ function sleep(ms, signal) {
 }
 
 // ../contracts/dist/run-unit.js
-function parseRunUnitSubmission(input) {
+function parseRunUnitSubmission(input, fallbackModel) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
-    return fallbackFlat();
+    return fallbackFlat(fallbackModel);
   }
   const value = input;
   if (value.kind === "submission") {
-    return parseFlatProjection(value);
+    return parseFlatProjection(value, fallbackModel);
   }
-  return fallbackFlat();
+  return fallbackFlat(fallbackModel);
 }
-function parseFlatProjection(value) {
+function parseFlatProjection(value, fallbackModel) {
   const submissionRaw = isRecord(value.submission) ? value.submission : {};
   const outputsRaw = isRecord(submissionRaw.outputs) ? submissionRaw.outputs : {};
   const allowedDirs = toOptionalStringArray(outputsRaw.allowedDirs);
@@ -827,7 +856,7 @@ function parseFlatProjection(value) {
   const maxTotalBytes = toOptionalPositiveInteger(outputsRaw.maxTotalBytes);
   const maxFiles = toOptionalPositiveInteger(outputsRaw.maxFiles);
   const submission = {
-    model: coerceRunUnitModel(submissionRaw.model),
+    model: coerceRunUnitModel(submissionRaw.model ?? fallbackModel),
     ...typeof submissionRaw.system === "string" ? { system: submissionRaw.system } : {},
     prompt: toStringArray(submissionRaw.prompt),
     agentsMd: [],
@@ -859,11 +888,11 @@ function parseSecurityProfile(value) {
 function toOptionalPositiveInteger(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
 }
-function fallbackFlat() {
+function fallbackFlat(fallbackModel) {
   return {
     kind: "submission",
     submission: {
-      model: Models.CLAUDE_HAIKU_4_5,
+      model: coerceRunUnitModel(fallbackModel),
       prompt: [],
       agentsMd: [],
       files: [],
@@ -892,7 +921,10 @@ function normalizeRunUnit(raw) {
     ...str3(r.terminalAt) ? { terminalAt: r.terminalAt } : {},
     ...str3(r.deletedAt) ? { deletedAt: r.deletedAt } : {},
     attemptCount: typeof r.attemptCount === "number" ? r.attemptCount : Array.isArray(r.attempts) ? r.attempts.length : 0,
-    submission: parseRunUnitSubmission(r.submission),
+    // Plane responses that project a flat record (no `submission` snapshot)
+    // still carry the run's `model` at the top level — prefer it over the
+    // static fallback so `unit()` never claims a model the run did not use.
+    submission: parseRunUnitSubmission(r.submission, r.model),
     ...isRecord(r.capsSnapshot) ? { capsSnapshot: r.capsSnapshot } : {},
     attempts: arr(r.attempts),
     events: {
@@ -1363,6 +1395,11 @@ var HIGH_ENTROPY_CANDIDATE = /[A-Za-z0-9+/=-]{24,}/g;
 var ENTROPY_BITS_PER_CHAR = 3;
 var MIN_CHAR_CLASSES = 2;
 var HIGH_ENTROPY_NO_DIGIT_MIN_LEN = 40;
+function isCanonicalRunIdHex(input, matchStart, match) {
+  if (!/^[0-9a-f]{32}$/.test(match))
+    return false;
+  return input.slice(Math.max(0, matchStart - 4), matchStart) === "run_";
+}
 function redactSecrets(value) {
   if (typeof value === "string") {
     return redactString(value);
@@ -1395,7 +1432,7 @@ function redactString(input, known = []) {
     // prefix; the rest replace the whole match.
     typeof captured === "string" ? `${captured} ${REDACTED}` : REDACTED
   )), out);
-  return out.replace(HIGH_ENTROPY_CANDIDATE, (match) => looksHighEntropySecret(match) ? REDACTED : match);
+  return out.replace(HIGH_ENTROPY_CANDIDATE, (match, offset, whole) => !isCanonicalRunIdHex(whole, offset, match) && looksHighEntropySecret(match) ? REDACTED : match);
 }
 function isSecretKey(key) {
   return /(?:api[_-]?key|authorization|token|secret|password|credential)/i.test(key);
@@ -1437,8 +1474,8 @@ function shannonEntropyBits(value) {
 var AexError = class extends Error {
   code;
   details;
-  constructor(code, message, details) {
-    super(redactSecrets(message));
+  constructor(code, message, details, options) {
+    super(redactSecrets(message), options?.cause === void 0 ? void 0 : { cause: options.cause });
     this.name = this.constructor.name;
     this.code = code;
     this.details = details === void 0 ? void 0 : redactSecrets(details);
@@ -1458,6 +1495,85 @@ var AexApiError = class extends AexError {
     this.body = redactSecrets(body);
   }
 };
+var AexNetworkError = class extends AexError {
+  method;
+  /** Request host — never carries credentials or the query string. */
+  host;
+  path;
+  /** Transport failure code (e.g. `ECONNREFUSED`), when detectable. */
+  causeCode;
+  /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
+  attempts;
+  constructor(args) {
+    const causeCode = extractErrorCode(args.cause);
+    super("NETWORK_ERROR", networkErrorMessage(args, causeCode), { method: args.method, host: args.host, path: args.path, ...causeCode ? { code: causeCode } : {} }, { cause: args.cause });
+    this.method = args.method;
+    this.host = args.host;
+    this.path = args.path;
+    this.causeCode = causeCode;
+    this.attempts = args.attempts ?? 1;
+  }
+};
+function networkErrorMessage(args, causeCode) {
+  const target = args.host ? `${args.host}${args.path}` : "request";
+  const detail = shortCauseMessage(args.cause, causeCode);
+  const suffix = args.attempts === void 0 ? "" : ` after ${args.attempts} attempt${args.attempts === 1 ? "" : "s"} over ${args.elapsedMs ?? 0}ms`;
+  let message = `${args.method} ${target} failed`;
+  if (causeCode)
+    message += `: ${causeCode}`;
+  if (detail)
+    message += causeCode ? ` (${detail})` : `: ${detail}`;
+  return message + suffix;
+}
+function shortCauseMessage(cause, causeCode) {
+  const nested = cause instanceof Error && cause.cause instanceof Error ? cause.cause : cause;
+  const message = nested instanceof Error ? nested.message || nested.name : typeof nested === "string" ? nested : void 0;
+  if (!message || message === causeCode)
+    return void 0;
+  return message.replace(/https?:\/\/[^\s<>"'`]+/g, (raw) => redactUrl(raw)).slice(0, 200);
+}
+function extractErrorCode(err2) {
+  const code = stringProperty(err2, "code");
+  if (code)
+    return code;
+  const cause = objectProperty(err2, "cause");
+  const causeCode = stringProperty(cause, "code");
+  if (causeCode)
+    return causeCode;
+  const match = /\bE[A-Z0-9_]+\b/.exec(errorMessageOf(err2));
+  return match?.[0];
+}
+function redactUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const auth = parsed.username || parsed.password ? "[redacted]@" : "";
+    const query = parsed.search ? "?[redacted]" : "";
+    return `${parsed.protocol}//${auth}${parsed.host}${parsed.pathname}${query}`;
+  } catch {
+    const withoutAuth = url.replace(/\/\/[^/?#\s]+@/, "//[redacted]@");
+    const queryStart = withoutAuth.indexOf("?");
+    return queryStart === -1 ? withoutAuth : `${withoutAuth.slice(0, queryStart)}?[redacted]`;
+  }
+}
+function errorMessageOf(err2) {
+  if (err2 instanceof Error)
+    return err2.message || err2.name;
+  if (typeof err2 === "string")
+    return err2;
+  return String(err2);
+}
+function objectProperty(value, key) {
+  if (!value || typeof value !== "object")
+    return void 0;
+  const prop = value[key];
+  return prop && typeof prop === "object" ? prop : void 0;
+}
+function stringProperty(value, key) {
+  if (!value || typeof value !== "object")
+    return void 0;
+  const prop = value[key];
+  return typeof prop === "string" && prop.length > 0 ? prop : void 0;
+}
 
 // ../contracts/dist/webhook-verify.js
 var encoder2 = new TextEncoder();
@@ -1465,17 +1581,21 @@ var encoder2 = new TextEncoder();
 // ../contracts/dist/http.js
 var HttpClient = class {
   #baseUrl;
-  #apiToken;
+  #apiKey;
   #fetch;
   #debug;
   constructor(options) {
-    if (!options.apiToken) {
-      throw new Error("HttpClient: apiToken is required");
+    if (!options.apiKey) {
+      throw new Error("HttpClient: apiKey is required");
     }
     const raw = options.baseUrl ?? AEX_DEFAULT_BASE_URL;
     const normalized = raw.endsWith("/") ? raw : `${raw}/`;
-    this.#baseUrl = new URL(normalized);
-    this.#apiToken = options.apiToken;
+    try {
+      this.#baseUrl = new URL(normalized);
+    } catch (err2) {
+      throw new Error(`HttpClient: invalid aex baseUrl ${JSON.stringify(redactUrl(raw))} \u2014 expected an absolute URL like "${AEX_DEFAULT_BASE_URL}"`, { cause: err2 });
+    }
+    this.#apiKey = options.apiKey;
     this.#fetch = options.fetch ?? fetch;
     this.#debug = options.debug;
   }
@@ -1490,7 +1610,7 @@ var HttpClient = class {
     }
     const headers = {
       accept: "application/json",
-      authorization: `Bearer ${this.#apiToken}`,
+      authorization: `Bearer ${this.#apiKey}`,
       ...normalizeHeaders(init.headers)
     };
     if (init.body !== void 0 && init.body !== null && !headers["content-type"]) {
@@ -1499,11 +1619,17 @@ var HttpClient = class {
       }
     }
     const startedMs = Date.now();
-    const response = await this.#fetch(url, { ...init, headers });
+    let response;
+    try {
+      response = await this.#fetch(url, { ...init, headers });
+    } catch (err2) {
+      throw toNetworkError(init.method, url, err2);
+    }
     this.#trace(init.method, url, response.status, startedMs);
     const body = await readJson(response);
     if (!response.ok) {
-      throw new AexApiError(response.status, extractErrorMessage(body), body);
+      const errorBody = withResponseRequestId(body, response.headers);
+      throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
     }
     return body;
   }
@@ -1513,19 +1639,37 @@ var HttpClient = class {
       url.searchParams.set(key, value);
     }
     const headers = {
-      authorization: `Bearer ${this.#apiToken}`,
+      authorization: `Bearer ${this.#apiKey}`,
       ...normalizeHeaders(init.headers)
     };
     const startedMs = Date.now();
-    const response = await this.#fetch(url, { ...init, headers });
+    let response;
+    try {
+      response = await this.#fetch(url, { ...init, headers });
+    } catch (err2) {
+      throw toNetworkError(init.method, url, err2);
+    }
     this.#trace(init.method, url, response.status, startedMs);
     if (!response.ok) {
       const body = await readJson(response);
-      throw new AexApiError(response.status, extractErrorMessage(body), body);
+      const errorBody = withResponseRequestId(body, response.headers);
+      throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
     }
     return { response };
   }
 };
+function toNetworkError(method, url, err2) {
+  if (err2 instanceof AexError)
+    return err2;
+  if (err2?.name === "AbortError")
+    return err2;
+  return new AexNetworkError({
+    method: (method ?? "GET").toUpperCase(),
+    host: url.host,
+    path: url.pathname,
+    cause: err2
+  });
+}
 function normalizeHeaders(headers) {
   if (!headers)
     return {};
@@ -1545,11 +1689,36 @@ async function readJson(response) {
     return { raw: text };
   }
 }
+function withResponseRequestId(body, headers) {
+  if (!body || typeof body !== "object" || Array.isArray(body))
+    return body;
+  const record = body;
+  if (typeof record.requestId === "string" && record.requestId.trim())
+    return body;
+  const requestId = responseRequestId(headers);
+  return requestId ? { ...record, requestId } : body;
+}
+function responseRequestId(headers) {
+  for (const name of ["x-request-id", "request-id"]) {
+    const value = headers.get(name)?.trim();
+    if (value)
+      return value;
+  }
+  return void 0;
+}
 function extractErrorMessage(body) {
   if (body && typeof body === "object") {
     const obj = body;
-    if (typeof obj.error === "string")
+    if (typeof obj.error === "string") {
+      const status2 = body.status;
+      if (obj.error === "session_busy" && typeof status2 === "string") {
+        return `session_busy (session status: ${status2})`;
+      }
+      if (typeof obj.message === "string" && obj.message.length > 0 && obj.message !== obj.error) {
+        return `${obj.error}: ${obj.message}`;
+      }
       return obj.error;
+    }
     if (obj.error && typeof obj.error === "object" && "message" in obj.error) {
       const message = obj.error.message;
       if (typeof message === "string")
@@ -2360,7 +2529,23 @@ async function listRuns(http, query) {
     params.limit = String(query.limit);
   if (query?.cursor !== void 0)
     params.cursor = query.cursor;
-  return http.request("/api/runs", {}, params);
+  const page = await http.request("/api/runs", {}, params);
+  let changed = false;
+  const runs = [];
+  for (const run of page.runs) {
+    if (typeof run.id !== "string" || typeof run.status !== "string" || typeof run.createdAt !== "string" || typeof run.updatedAt !== "string") {
+      changed = true;
+      continue;
+    }
+    if (typeof run.costUsd !== "number" && run.costUsd !== void 0) {
+      const { costUsd: _dropped, ...rest } = run;
+      runs.push(rest);
+      changed = true;
+      continue;
+    }
+    runs.push(run);
+  }
+  return changed ? { ...page, runs } : page;
 }
 function idempotencyHeaders(options) {
   return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : void 0;
@@ -2488,12 +2673,17 @@ async function outputLink(http, runId, selectorOrQuery, options) {
     method: "POST",
     body: JSON.stringify({ expiresInSeconds })
   });
+  const effectiveExpiresIn = result.expiresInSeconds ?? expiresInSeconds;
   return {
     ...result,
-    expiresInSeconds: result.expiresInSeconds ?? expiresInSeconds,
+    expiresInSeconds: effectiveExpiresIn,
+    expiresAt: result.expiresAt ?? syntheticExpiresAt(effectiveExpiresIn),
     output: result.output ?? output
   };
 }
+function syntheticExpiresAt(expiresInSeconds) {
+  return new Date(Date.now() + expiresInSeconds * 1e3).toISOString();
+}
 async function createOutputLink(http, runId, selectorOrQuery, options) {
   return outputLink(http, runId, selectorOrQuery, options);
 }
@@ -2503,9 +2693,11 @@ async function eventArchiveLink(http, runId, options) {
     method: "POST",
     body: JSON.stringify({ expiresInSeconds })
   });
+  const effectiveExpiresIn = result.expiresInSeconds ?? expiresInSeconds;
   return {
     ...result,
-    expiresInSeconds: result.expiresInSeconds ?? expiresInSeconds
+    expiresInSeconds: effectiveExpiresIn,
+    expiresAt: result.expiresAt ?? syntheticExpiresAt(effectiveExpiresIn)
   };
 }
 function resolveOutputFileSelector(outputs, selector, runId) {
@@ -3060,7 +3252,7 @@ function isSessionOk(status2) {
   return status2 === "idle" || status2 === "suspended" || status2 === "succeeded";
 }
 function extractCommonHostFlags(argv) {
-  let apiToken = null;
+  let apiKey = null;
   let aexUrl = null;
   let debug2 = false;
   const rest = [];
@@ -3070,11 +3262,11 @@ function extractCommonHostFlags(argv) {
       debug2 = true;
       continue;
     }
-    if (arg === "--api-token") {
+    if (arg === "--api-key") {
       const v = argv[++i2];
       if (v === void 0)
-        return { ok: false, reason: "--api-token requires a value" };
-      apiToken = v;
+        return { ok: false, reason: "--api-key requires a value" };
+      apiKey = v;
       continue;
     }
     if (arg === "--aex-url") {
@@ -3087,18 +3279,18 @@ function extractCommonHostFlags(argv) {
     if (arg === "--workspace" || arg === "--workspace-id") {
       return {
         ok: false,
-        reason: `unknown flag ${arg}: workspace is derived from --api-token on the server; drop this flag`
+        reason: `unknown flag ${arg}: workspace is derived from --api-key on the server; drop this flag`
       };
     }
     rest.push(arg);
   }
-  return { ok: true, flags: { apiToken, aexUrl, debug: debug2, rest } };
+  return { ok: true, flags: { apiKey, aexUrl, debug: debug2, rest } };
 }
 async function resolveCommonHostFlags(io2, argv) {
   const extracted = extractCommonHostFlags(argv);
   if (!extracted.ok)
     return extracted;
-  const { apiToken: flagToken, aexUrl: flagUrl, debug: debug2, rest } = extracted.flags;
+  const { apiKey: flagToken, aexUrl: flagUrl, debug: debug2, rest } = extracted.flags;
   let token = flagToken;
   let url = flagUrl;
   let source = flagToken ? "flag" : "none";
@@ -3106,8 +3298,8 @@ async function resolveCommonHostFlags(io2, argv) {
   if (!token && io2.configStore) {
     const stored = await io2.configStore.read();
     storedLocation = io2.configStore.location();
-    if (stored?.apiToken) {
-      token = stored.apiToken;
+    if (stored?.apiKey) {
+      token = stored.apiKey;
       source = "stored";
       if (!url && stored.aexUrl)
         url = stored.aexUrl;
@@ -3115,35 +3307,56 @@ async function resolveCommonHostFlags(io2, argv) {
   }
   const resolvedUrl = url ?? AEX_DEFAULT_BASE_URL;
   if (debug2) {
-    const where = source === "flag" ? "--api-token flag" : source === "stored" ? `stored token (${storedLocation})` : "none";
+    const where = source === "flag" ? "--api-key flag" : source === "stored" ? `stored token (${storedLocation})` : "none";
     io2.stderr(`[aex] auth: ${where}; aex-url=${resolvedUrl}
 `);
   }
   if (!token) {
-    return { ok: false, reason: "no API token \u2014 pass --api-token or run `aex login`" };
+    return { ok: false, reason: "no API key \u2014 pass --api-key or run `aex login`" };
   }
-  return { ok: true, flags: { apiToken: token, aexUrl: resolvedUrl, debug: debug2 }, rest };
+  return { ok: true, flags: { apiKey: token, aexUrl: resolvedUrl, debug: debug2 }, rest };
 }
 function describeApiError(err2) {
   if (err2 instanceof AexApiError) {
     const remedy = remedyForStatus(err2.status);
+    const detail = describeErrorBody(err2.body);
     return {
       code: err2.code,
-      message: err2.message,
+      message: detail ? `${err2.message} \u2014 ${detail}` : err2.message,
       status: err2.status,
       ...remedy ? { remedy } : {}
     };
   }
   if (err2 instanceof AexError) {
-    return { code: err2.code, message: err2.message };
+    const causeCode = err2 instanceof AexNetworkError ? err2.causeCode : extractErrorCode(err2.cause);
+    const remedy = causeCode ? remedyForNetworkCode(causeCode) : void 0;
+    const message = causeCode && !err2.message.includes(causeCode) ? `${err2.message} (${causeCode})` : err2.message;
+    return { code: err2.code, message, ...remedy ? { remedy } : {} };
   }
   return { code: "error", message: err2 instanceof Error ? err2.message : String(err2) };
 }
+var STANDARD_ERROR_BODY_KEYS = /* @__PURE__ */ new Set(["ok", "error", "message", "code"]);
+function describeErrorBody(body) {
+  if (!body || typeof body !== "object")
+    return void 0;
+  const record = body;
+  const extraKeys = Object.keys(record).filter((key) => !STANDARD_ERROR_BODY_KEYS.has(key));
+  if (extraKeys.length === 0)
+    return void 0;
+  let text;
+  try {
+    text = JSON.stringify(Object.fromEntries(extraKeys.map((key) => [key, record[key]])));
+  } catch {
+    return void 0;
+  }
+  const redacted = redactSecrets(text);
+  return redacted.length > 400 ? `${redacted.slice(0, 400)}\u2026 (truncated)` : redacted;
+}
 function remedyForStatus(status2) {
   if (status2 === 400)
-    return "malformed request \u2014 if this is an auth failure, check --api-token or run `aex login`";
+    return "malformed request \u2014 if this is an auth failure, check --api-key or run `aex login`";
   if (status2 === 401)
-    return "check --api-token, or run `aex login`";
+    return "check --api-key, or run `aex login`";
   if (status2 === 403)
     return "token lacks permission for this workspace/action";
   if (status2 === 404)
@@ -3154,6 +3367,26 @@ function remedyForStatus(status2) {
     return "server error \u2014 retry; re-run with --debug to capture the request trace";
   return void 0;
 }
+function remedyForNetworkCode(code) {
+  switch (code) {
+    case "ECONNREFUSED":
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+    case "EHOSTUNREACH":
+    case "ENETUNREACH":
+      return "cannot reach the aex API \u2014 check --aex-url and network connectivity";
+    case "ECONNRESET":
+    case "ETIMEDOUT":
+    case "UND_ERR_CONNECT_TIMEOUT":
+      return "connection dropped \u2014 retry; check --aex-url, network connectivity, or any proxy/VPN";
+    case "CERT_HAS_EXPIRED":
+    case "DEPTH_ZERO_SELF_SIGNED_CERT":
+    case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+      return "TLS verification failed \u2014 check --aex-url points at the right host";
+    default:
+      return void 0;
+  }
+}
 function suggest(input, candidates) {
   const needle = input.trim();
   if (!needle)
@@ -3195,7 +3428,7 @@ function levenshtein(a, b) {
 function makeHttpClient(io2, flags) {
   return new HttpClient({
     baseUrl: flags.aexUrl,
-    apiToken: flags.apiToken,
+    apiKey: flags.apiKey,
     fetch: io2.fetchImpl,
     // `--debug`: route the transport's redacted per-request traces to stderr.
     ...flags.debug ? { debug: (line) => io2.stderr(`${line}
@@ -3411,7 +3644,7 @@ async function runRunCmd(io2, argv) {
     return USAGE_ERR;
   }
   rest = providerFlag.remaining;
-  let provider = DEFAULT_RUN_PROVIDER;
+  let explicitProvider;
   if (providerFlag.value !== null) {
     if (!RUN_PROVIDERS.includes(providerFlag.value)) {
       const hint = suggest(providerFlag.value, RUN_PROVIDERS);
@@ -3419,7 +3652,7 @@ async function runRunCmd(io2, argv) {
 `);
       return USAGE_ERR;
     }
-    provider = providerFlag.value;
+    explicitProvider = providerFlag.value;
   }
   const providerKeyValues = {};
   for (const p of RUN_PROVIDERS) {
@@ -3433,11 +3666,6 @@ async function runRunCmd(io2, argv) {
     if (flag.value !== null)
       providerKeyValues[p] = flag.value;
   }
-  if (!providerKeyValues[provider]) {
-    io2.stderr(`--${provider}-api-key is required when --provider is ${provider} (the platform does not store provider keys on your behalf)
-`);
-    return USAGE_ERR;
-  }
   const idempotency = takeFlagValue(rest, "--idempotency-key");
   if (idempotency.error) {
     io2.stderr(`${idempotency.error}
@@ -3637,6 +3865,12 @@ async function runRunCmd(io2, argv) {
       ...Object.keys(metadataFlags.entries).length > 0 ? { metadata: { ...metadataFlags.entries } } : {}
     };
   }
+  const provider = explicitProvider ?? providersForModel(runConfig.model)[0] ?? DEFAULT_RUN_PROVIDER;
+  if (!providerKeyValues[provider]) {
+    io2.stderr(`--${provider}-api-key is required for provider ${provider}${explicitProvider === void 0 ? ` (inferred from --model ${runConfig.model})` : ""} (the platform does not store provider keys on your behalf)
+`);
+    return USAGE_ERR;
+  }
   const mcpServersForSubmission = [...runConfig.mcpServers ?? []];
   const mcpServerSecrets = [];
   const mcpHeaderBag = new Map(mcpHeadersFromConfig);
@@ -5101,7 +5335,7 @@ function makeAwsSources(region) {
     }
   };
 }
-var USAGE = "usage: aex debug <run-id> [--plane dev|prd] [--region eu-west-2] [--out dir] [--account <id>] [--cloudwatch] [--since <dur>] [--with-outputs]\n  operator command \u2014 uses the standard AWS SDK credential chain (env/profile), NOT --api-token\n";
+var USAGE = "usage: aex debug <run-id> [--plane dev|prd] [--region eu-west-2] [--out dir] [--account <id>] [--cloudwatch] [--since <dur>] [--with-outputs]\n  operator command \u2014 uses the standard AWS SDK credential chain (env/profile), NOT --api-key\n";
 async function runDebugCmd(io2, argv) {
   if (await refuseInsideManagedRun(io2, "debug"))
     return USAGE_ERR;
@@ -5203,19 +5437,19 @@ async function runLoginCmd(io2, argv) {
 `);
     return USAGE_ERR;
   }
-  const { apiToken, aexUrl, debug: debug2, rest } = extracted.flags;
+  const { apiKey, aexUrl, debug: debug2, rest } = extracted.flags;
   const positional = rest.filter((a) => !a.startsWith("--"));
   if (positional.length > 0) {
     io2.stderr(`unexpected arguments: ${positional.join(" ")}
 `);
     return USAGE_ERR;
   }
-  if (!apiToken) {
-    io2.stderr("usage: aex login --api-token <token> [--aex-url <url>]\n");
+  if (!apiKey) {
+    io2.stderr("usage: aex login --api-key <token> [--aex-url <url>]\n");
     return USAGE_ERR;
   }
   const resolvedUrl = aexUrl ?? AEX_DEFAULT_BASE_URL;
-  const http = makeHttpClient(io2, { apiToken, aexUrl: resolvedUrl, debug: debug2 });
+  const http = makeHttpClient(io2, { apiKey, aexUrl: resolvedUrl, debug: debug2 });
   let workspaceId;
   try {
     const me = await operations_exports.whoami(http);
@@ -5232,7 +5466,7 @@ async function runLoginCmd(io2, argv) {
       ...described.remedy ? { remedy: described.remedy } : {}
     });
   }
-  await io2.configStore.write({ schemaVersion: 1, apiToken, ...aexUrl ? { aexUrl: resolvedUrl } : {} });
+  await io2.configStore.write({ schemaVersion: 1, apiKey, ...aexUrl ? { aexUrl: resolvedUrl } : {} });
   if (debug2)
     io2.stderr(`[aex] login: persisted to ${io2.configStore.location()}
 `);
@@ -5273,8 +5507,8 @@ async function runAuthStatusCmd(io2, argv) {
     return USAGE_ERR;
   }
   const stored = await io2.configStore.read();
-  const hasToken = Boolean(stored?.apiToken);
-  const tokenSuffix = hasToken ? stored.apiToken.slice(-4) : void 0;
+  const hasToken = Boolean(stored?.apiKey);
+  const tokenSuffix = hasToken ? stored.apiKey.slice(-4) : void 0;
   io2.stdout(JSON.stringify({
     configPath: io2.configStore.location(),
     hasToken,
@@ -5436,6 +5670,12 @@ function renderEnvelope(e, options = {}) {
     }
     case "CUSTOM": {
       const label = e.message ?? str2(e.data.name) ?? "custom";
+      if (e.data.name === "aex.session.idle") {
+        const value = e.data.value;
+        const reason = value && typeof value.reason === "string" ? value.reason : "";
+        if (reason && reason !== "completed")
+          return `[aex] ${label} (${reason})`;
+      }
       return `[aex] ${label}`;
     }
     case "LOG": {
@@ -5863,28 +6103,28 @@ async function dispatch(io2, args) {
 async function printGlobalHelp(io2) {
   io2.stdout("aex \u2014 unified CLI for the aex platform (mirrors the SDK 1:1)\n\n");
   io2.stdout("Usage:\n");
-  io2.stdout("  aex run --config <run.json> --<provider>-api-key K --api-token T [flags]\n");
-  io2.stdout("  aex run --model M --prompt P [--system S] [--mcp name=url ...] --<provider>-api-key K --api-token T [flags]\n");
-  io2.stdout("  aex status <session-id> --api-token T\n");
-  io2.stdout("  aex deliveries <session-id> --api-token T\n");
-  io2.stdout("  aex wait <session-id> [--timeout 8m] [--interval 2s] --api-token T\n");
-  io2.stdout("  aex events <session-id> [--follow] [--timeout 8m] --api-token T\n");
-  io2.stdout("  aex tail <session-id> [--json] [--filter <type|source>] [--logs] [--settle] [--timeout 8m] --api-token T\n");
-  io2.stdout("  aex inspect <session-id> [--json] [--filter <type|source>] [--logs] [--timeout 8m] --api-token T\n");
-  io2.stdout("  aex outputs <session-id> --api-token T\n");
-  io2.stdout("  aex download <session-id> [--only outputs|events|metadata] [--out path] --api-token T\n");
-  io2.stdout("  aex cancel <session-id> --api-token T\n");
-  io2.stdout("  aex delete <session-id> --api-token T\n");
-  io2.stdout("  aex delete-asset <assetId|hash> --api-token T\n");
-  io2.stdout("  aex runs [--limit N] [--since ISO] --api-token T      List the workspace's runs (newest first, JSON)\n");
-  io2.stdout("  aex sessions [--limit N] --api-token T      List the workspace's sessions (newest first, JSON)\n");
-  io2.stdout("  aex whoami --api-token T\n");
-  io2.stdout("  aex billing [--json] --api-token T          Show prepaid balance, month spend, and spend cap\n");
-  io2.stdout("  aex billing ledger [--limit N] --api-token T   Recent credit-ledger entries (newest first, JSON)\n");
-  io2.stdout("  aex billing upgrade pro|team --api-token T   Create a hosted checkout session and print its URL\n");
-  io2.stdout("  aex billing portal --api-token T             Create a hosted billing portal session and print its URL\n");
-  io2.stdout("  aex webhooks secret --api-token T           Reveal (create on first use) the webhook signing secret\n");
-  io2.stdout("  aex login --api-token T [--aex-url U]      Persist token + url (then other verbs need no --api-token)\n");
+  io2.stdout("  aex run --config <run.json> --<provider>-api-key K --api-key T [flags]\n");
+  io2.stdout("  aex run --model M --prompt P [--system S] [--mcp name=url ...] --<provider>-api-key K --api-key T [flags]\n");
+  io2.stdout("  aex status <session-id> --api-key T\n");
+  io2.stdout("  aex deliveries <session-id> --api-key T\n");
+  io2.stdout("  aex wait <session-id> [--timeout 8m] [--interval 2s] --api-key T\n");
+  io2.stdout("  aex events <session-id> [--follow] [--timeout 8m] --api-key T\n");
+  io2.stdout("  aex tail <session-id> [--json] [--filter <type|source>] [--logs] [--settle] [--timeout 8m] --api-key T\n");
+  io2.stdout("  aex inspect <session-id> [--json] [--filter <type|source>] [--logs] [--timeout 8m] --api-key T\n");
+  io2.stdout("  aex outputs <session-id> --api-key T\n");
+  io2.stdout("  aex download <session-id> [--only outputs|events|metadata] [--out path] --api-key T\n");
+  io2.stdout("  aex cancel <session-id> --api-key T\n");
+  io2.stdout("  aex delete <session-id> --api-key T\n");
+  io2.stdout("  aex delete-asset <assetId|hash> --api-key T\n");
+  io2.stdout("  aex runs [--limit N] [--since ISO] --api-key T      List the workspace's runs (newest first, JSON)\n");
+  io2.stdout("  aex sessions [--limit N] --api-key T      List the workspace's sessions (newest first, JSON)\n");
+  io2.stdout("  aex whoami --api-key T\n");
+  io2.stdout("  aex billing [--json] --api-key T          Show prepaid balance, month spend, and spend cap\n");
+  io2.stdout("  aex billing ledger [--limit N] --api-key T   Recent credit-ledger entries (newest first, JSON)\n");
+  io2.stdout("  aex billing upgrade pro|team --api-key T   Create a hosted checkout session and print its URL\n");
+  io2.stdout("  aex billing portal --api-key T             Create a hosted billing portal session and print its URL\n");
+  io2.stdout("  aex webhooks secret --api-key T           Reveal (create on first use) the webhook signing secret\n");
+  io2.stdout("  aex login --api-key T [--aex-url U]      Persist token + url (then other verbs need no --api-key)\n");
   io2.stdout("  aex logout                                 Clear the stored token\n");
   io2.stdout("  aex auth status                            Show the resolved config (token never printed)\n");
   io2.stdout("  aex models list [--json]                   List models + default provider (no token needed)\n");
@@ -5894,7 +6134,7 @@ async function printGlobalHelp(io2) {
   io2.stdout("  aex debug <run-id> [--plane dev|prd] [--region eu-west-2] [--cloudwatch] [--with-outputs]   (operator; AWS creds)\n");
   io2.stdout("  aex --help\n\n");
   io2.stdout("Common flags on every host subcommand:\n");
-  io2.stdout("  --api-token <token>         REQUIRED \u2014 aex SDK API token (workspace is derived from it)\n");
+  io2.stdout("  --api-key <token>         REQUIRED \u2014 aex SDK API key (workspace is derived from it)\n");
   io2.stdout("  --aex-url <url>         Optional; defaults to https://api.aex.dev (local/staging/hosted plane)\n");
   io2.stdout("  --debug                     Optional; print a redacted per-request trace to stderr (uploads nothing)\n\n");
   io2.stdout("aex run flags:\n");