@aexhq/sdk 0.37.2 → 0.37.4

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();
@@ -1474,7 +1590,11 @@ var HttpClient = class {
     }
     const raw = options.baseUrl ?? AEX_DEFAULT_BASE_URL;
     const normalized = raw.endsWith("/") ? raw : `${raw}/`;
-    this.#baseUrl = new URL(normalized);
+    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.#apiToken = options.apiToken;
     this.#fetch = options.fetch ?? fetch;
     this.#debug = options.debug;
@@ -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;
   }
@@ -1517,15 +1643,33 @@ var HttpClient = class {
       ...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) {
@@ -3127,18 +3319,39 @@ async function resolveCommonHostFlags(io2, argv) {
 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`";
@@ -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)
@@ -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);
@@ -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": {

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-0b259b81011fcda9d15954453cc67f17d1b28add9a32903218d068c3dd1c2e9d  cli.mjs
+c8d969d9ee5c6e6bb2e0a642ba8adce0aa235ef2bba96b99d8832ae1957ed2a3  cli.mjs

package/dist/client.d.ts

@@ -68,7 +68,14 @@ export interface RunResult {
     readonly outputs: readonly Output[];
     /** Aggregate token usage when the deployment exposes it on the record. */
     readonly usage?: UsageSummary;
-    /** Settle-time showback estimate (USD), from `run.costTelemetry`. */
+    /**
+     * Settle-time showback estimate (USD), from the settle-stamped session
+     * record's `costUsd` (the full `costTelemetry` block is served on
+     * `GET /api/runs/:id`, not on the session projection). The settle
+     * write lands tens of seconds AFTER the turn parks, so by default this is
+     * usually absent on a fresh run — pass `settleConsistent: true` to wait for
+     * it, or read `sessions.get(runId).costUsd` later.
+     */
     readonly costUsd?: number;
     /** The run's error message when `!ok`. */
     readonly error?: string;
@@ -82,6 +89,14 @@ export interface RunCollectOptions {
     readonly pingIntervalMs?: number;
     /** Throw a {@link RunStateError} when the run does not succeed. Default false. */
     readonly throwOnFailure?: boolean;
+    /**
+     * Wait (bounded, ~60s) for the settle write after the turn parks, so the
+     * result carries the settle-stamped `costUsd`/`usage`/`errorMessage`. The
+     * settle lambda lands tens of seconds after the park event, so this trades
+     * latency for a complete record. Default false: return at park; read
+     * `sessions.get(runId)` later for the showback.
+     */
+    readonly settleConsistent?: boolean;
 }
 export type SessionInput = string | readonly string[];
 export interface SessionEnvironmentOptions extends Omit<PlatformEnvironmentInput, "envVars"> {
@@ -342,6 +357,7 @@ export declare class SessionClient {
     create(options: SessionCreateOptions): Promise<SessionHandle>;
     open(sessionId: string): Promise<SessionHandle>;
     get(sessionId: string): Promise<Session>;
+    delete(sessionId: string, options?: Pick<SessionSendOptions, "idempotencyKey">): Promise<void>;
     list(query?: SessionListQuery): Promise<SessionListPage>;
     /**
      * Accessor over one session's captured output files, addressed by id without