@aexhq/sdk 0.39.0 → 0.40.0

package/dist/cli.mjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 
 // dist/cli.js
 import { readFile, writeFile, readdir, stat, mkdir, chmod, rm } from "node:fs/promises";
-import { resolve as resolvePath4, join, dirname as dirname2 } from "node:path";
+import { resolve as resolvePath5, join, dirname as dirname2 } from "node:path";
 import { homedir } from "node:os";
 
 // ../contracts/dist/provider-support.js
@@ -98,6 +98,46 @@ var PROVIDER_PUBLIC_SUPPORT = {
   }
 };
 
+// ../contracts/dist/suggest.js
+function suggest(input, candidates) {
+  const needle = input.trim();
+  if (!needle)
+    return void 0;
+  const lower = needle.toLowerCase();
+  const prefixHits = candidates.filter((c) => c.toLowerCase().startsWith(lower));
+  if (prefixHits.length === 1)
+    return prefixHits[0];
+  let best;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const dist = levenshtein(needle, candidate);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+  return bestDist <= 2 ? best : void 0;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0)
+    return n;
+  if (n === 0)
+    return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = new Array(n + 1);
+  for (let i2 = 1; i2 <= m; i2++) {
+    curr[0] = i2;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i2 - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+
 // ../contracts/dist/models.js
 var MODEL_PROVIDER_IDS = {
   "claude-haiku-4-5": { anthropic: "claude-haiku-4-5" },
@@ -190,6 +230,21 @@ function providersForModel(model) {
 function providerForModel(model) {
   return providersForModel(model)[0];
 }
+function resolveModelProvider(model, provider) {
+  const providers = providersForModel(model);
+  if (provider !== void 0) {
+    if (providers.length > 0 && !providers.includes(provider)) {
+      throw new Error(`model ${JSON.stringify(model)} is not available for provider ${provider}; available: ${providers.join(", ")}`);
+    }
+    return provider;
+  }
+  const inferred = providers[0];
+  if (inferred === void 0) {
+    const hint = suggest(model, RUN_MODELS);
+    throw new Error(`${JSON.stringify(model)} is not a known model id` + (hint ? ` (did you mean ${JSON.stringify(hint)}?)` : "") + "; pass provider explicitly to run it");
+  }
+  return inferred;
+}
 function isRunModel(input) {
   return typeof input === "string" && RUN_MODELS.includes(input);
 }
@@ -201,6 +256,33 @@ function parseRunModel(input, field = "submission.model") {
 }
 
 // ../contracts/dist/status.js
+var SESSION_LIFECYCLE_STATUSES = [
+  "creating",
+  "running",
+  "idle",
+  "suspending",
+  "suspended",
+  "cancelling",
+  "deleting",
+  "deleted",
+  "expired"
+];
+var SESSION_TERMINAL_OUTCOMES = [
+  "succeeded",
+  "failed",
+  "timed_out",
+  "cancelled"
+];
+var SESSION_STATUSES = [
+  ...SESSION_LIFECYCLE_STATUSES,
+  ...SESSION_TERMINAL_OUTCOMES,
+  "awaiting_approval"
+];
+var SESSION_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  ...SESSION_TERMINAL_OUTCOMES,
+  "deleted",
+  "expired"
+]);
 var TERMINAL_RUN_STATUSES = [
   "succeeded",
   "failed",
@@ -222,6 +304,9 @@ var CLEANUP_STATUSES = [
 ];
 
 // ../contracts/dist/run-config.js
+var SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
+var TOOL_NAME_PATTERN = SKILL_NAME_PATTERN;
+var SKILL_RESERVED_NAMES = /* @__PURE__ */ new Set(["skills", "skill"]);
 var SKILL_BUNDLE_LIMITS = {
   /** Compressed (.zip) ceiling. */
   maxCompressedBytes: 10 * 1024 * 1024 * 1024,
@@ -244,6 +329,66 @@ var SKILL_BUNDLE_LIMITS = {
   /** Stored directory mode. */
   defaultDirMode: 493
 };
+var DEFAULT_FILE_MOUNT_PATH = "/workspace";
+var SkillBundleValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SkillBundleValidationError";
+  }
+};
+function normaliseSkillBundlePath(input) {
+  if (typeof input !== "string") {
+    throw new SkillBundleValidationError("bundle entry path must be a string");
+  }
+  if (input.length === 0 || input.trim().length === 0) {
+    throw new SkillBundleValidationError("bundle entry path must be non-empty");
+  }
+  if (input.length > SKILL_BUNDLE_LIMITS.maxPathLength) {
+    throw new SkillBundleValidationError(`bundle entry path exceeds maxPathLength (${SKILL_BUNDLE_LIMITS.maxPathLength}): ${input}`);
+  }
+  if (input.includes("\0")) {
+    throw new SkillBundleValidationError(`bundle entry path contains NUL byte: ${JSON.stringify(input)}`);
+  }
+  if (input.includes("\\")) {
+    throw new SkillBundleValidationError(`bundle entry path uses backslash separator: ${input}`);
+  }
+  if (/^[A-Za-z]:[\\/]/.test(input)) {
+    throw new SkillBundleValidationError(`bundle entry path uses a drive letter: ${input}`);
+  }
+  if (input.startsWith("/")) {
+    throw new SkillBundleValidationError(`bundle entry path must be relative: ${input}`);
+  }
+  if (input.endsWith("/")) {
+    throw new SkillBundleValidationError(`bundle entry path must not end with '/': ${input}`);
+  }
+  const segments = input.split("/");
+  for (const segment of segments) {
+    if (segment === "..") {
+      throw new SkillBundleValidationError(`bundle entry path contains '..' segment: ${input}`);
+    }
+    if (segment === "." || segment === "") {
+      throw new SkillBundleValidationError(`bundle entry path contains empty or '.' segment: ${input}`);
+    }
+  }
+  if (segments.length > SKILL_BUNDLE_LIMITS.maxDepth) {
+    throw new SkillBundleValidationError(`bundle entry path exceeds maxDepth (${SKILL_BUNDLE_LIMITS.maxDepth}): ${input}`);
+  }
+  return input;
+}
+function validateSkillBundleEntry(input) {
+  const path = normaliseSkillBundlePath(input.path);
+  if (!Number.isFinite(input.size) || !Number.isInteger(input.size) || input.size < 0) {
+    throw new SkillBundleValidationError(`bundle entry size must be a non-negative integer (${path})`);
+  }
+  if (input.size > SKILL_BUNDLE_LIMITS.maxDecompressedBytes) {
+    throw new SkillBundleValidationError(`bundle entry size exceeds maxDecompressedBytes (${SKILL_BUNDLE_LIMITS.maxDecompressedBytes}): ${path}`);
+  }
+  const mode = (input.mode ?? SKILL_BUNDLE_LIMITS.defaultFileMode) & 511;
+  if (mode !== SKILL_BUNDLE_LIMITS.defaultFileMode && mode !== SKILL_BUNDLE_LIMITS.defaultDirMode) {
+    return { path, size: input.size, mode: SKILL_BUNDLE_LIMITS.defaultFileMode };
+  }
+  return { path, size: input.size, mode };
+}
 var REMOTE_MCP_TRANSPORTS = ["http", "sse"];
 var REMOTE_MCP_STDIO_REJECTED_MESSAGE = "stdio MCP servers are not supported by Aex. Aex supports remote MCP servers over HTTP/SSE only.";
 var STDIO_ONLY_FIELDS = ["command", "args", "env"];
@@ -497,6 +642,36 @@ var DEFAULT_RUNTIME_SIZE = "shared-0.25x-1gb";
 var DEFAULT_RUN_TIMEOUT_MS = 8 * 60 * 60 * 1e3;
 var MAX_RUN_TIMEOUT_MS = 8 * 60 * 60 * 1e3;
 var MIN_RUN_TIMEOUT_MS = 60 * 1e3;
+var DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/;
+function parseDurationToMs(input) {
+  const match = DURATION_PATTERN.exec(input.trim());
+  if (!match) {
+    throw new Error(`invalid duration ${JSON.stringify(input)} (expected e.g. "1h", "90m", "30s", "500ms", or a bare ms integer)`);
+  }
+  const value = Number(match[1]);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`invalid duration ${JSON.stringify(input)} (must be a non-negative number)`);
+  }
+  const unit = match[2] ?? "ms";
+  const factor = unit === "h" ? 36e5 : unit === "m" ? 6e4 : unit === "s" ? 1e3 : 1;
+  return Math.round(value * factor);
+}
+function parseRunTimeout(input) {
+  if (input === void 0) {
+    return void 0;
+  }
+  if (typeof input !== "string") {
+    throw new Error(`timeout must be a duration string (e.g. "1h", "30m"); got ${JSON.stringify(input)}`);
+  }
+  const ms = parseDurationToMs(input);
+  if (ms < MIN_RUN_TIMEOUT_MS) {
+    throw new Error(`timeout must be at least ${MIN_RUN_TIMEOUT_MS}ms (1m); got ${ms}ms`);
+  }
+  if (ms > MAX_RUN_TIMEOUT_MS) {
+    throw new Error(`timeout must be at most ${MAX_RUN_TIMEOUT_MS}ms (8h); got ${ms}ms`);
+  }
+  return ms;
+}
 var RUN_PROCESS_KILL_GRACE_MS = 60 * 1e3;
 var RUN_TERMINAL_GRACE_MS = 90 * 1e3;
 
@@ -540,7 +715,90 @@ var RUN_PROVIDERS = [
   "doubao",
   "doubao-cn"
 ];
-var DEFAULT_RUN_PROVIDER = "anthropic";
+function requireRecord(input, field) {
+  if (!isRecord(input)) {
+    throw new Error(`${field} must be an object`);
+  }
+  return input;
+}
+function isRecord(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function requireString(input, field) {
+  if (typeof input !== "string" || input.length === 0) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return input;
+}
+function optionalPositiveInt(input, field) {
+  if (input === void 0) {
+    return void 0;
+  }
+  if (typeof input !== "number" || !Number.isSafeInteger(input) || input <= 0) {
+    throw new Error(`${field} must be a positive safe integer`);
+  }
+  return input;
+}
+function optionalPositiveNumber(input, field) {
+  if (input === void 0) {
+    return void 0;
+  }
+  if (typeof input !== "number" || !Number.isFinite(input) || input <= 0) {
+    throw new Error(`${field} must be a positive finite number`);
+  }
+  return input;
+}
+function parseRunWebhook(input) {
+  if (input === void 0) {
+    return void 0;
+  }
+  const value = requireRecord(input, "webhook");
+  const allowed = /* @__PURE__ */ new Set(["url"]);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new Error(`webhook.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+    }
+  }
+  const url = requireString(value.url, "webhook.url");
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`webhook.url must be a valid absolute URL (got ${JSON.stringify(url)})`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(`webhook.url must use https (got ${parsed.protocol.replace(/:$/, "")})`);
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    throw new Error("webhook.url must not contain userinfo (user:pass@host)");
+  }
+  return { url };
+}
+function parseRunLimits(input) {
+  if (input === void 0) {
+    return void 0;
+  }
+  const value = requireRecord(input, "limits");
+  const allowed = /* @__PURE__ */ new Set(["maxConcurrentChildRuns", "maxSubagentDepth", "maxSpendUsd", "maxTurns"]);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new Error(`limits.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+    }
+  }
+  const maxConcurrentChildRuns = optionalPositiveInt(value.maxConcurrentChildRuns, "limits.maxConcurrentChildRuns");
+  const maxSubagentDepth = optionalPositiveInt(value.maxSubagentDepth, "limits.maxSubagentDepth");
+  const maxSpendUsd = optionalPositiveNumber(value.maxSpendUsd, "limits.maxSpendUsd");
+  const maxTurns = optionalPositiveInt(value.maxTurns, "limits.maxTurns");
+  if (maxConcurrentChildRuns === void 0 && maxSubagentDepth === void 0 && maxSpendUsd === void 0 && maxTurns === void 0) {
+    return void 0;
+  }
+  return {
+    ...maxConcurrentChildRuns !== void 0 ? { maxConcurrentChildRuns } : {},
+    ...maxSubagentDepth !== void 0 ? { maxSubagentDepth } : {},
+    ...maxSpendUsd !== void 0 ? { maxSpendUsd } : {},
+    ...maxTurns !== void 0 ? { maxTurns } : {}
+  };
+}
 var BUILTIN_TOOL_NAMES = [
   "bash",
   "read_file",
@@ -559,10 +817,14 @@ var BUILTIN_TOOL_NAMES = [
   "bash_kill",
   "code_execution",
   "wait",
-  "git"
+  "git",
+  "ls",
+  "stat",
+  "wc"
 ];
 var DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES;
 var MAX_OUTPUT_CAPTURE_TIMEOUT_MS = 6 * 60 * 60 * 1e3;
+var SKILLS_MAX = 64;
 
 // ../contracts/dist/event-envelope.js
 var AEX_EVENT_SOURCES = ["agent", "api", "runtime", "mcp", "aex", "workflow", "host"];
@@ -580,7 +842,14 @@ var AEX_EVENT_TYPES = [
   // off-the-shelf AG-UI client filters logs out by `channel`.
   "LOG"
 ];
-var AEX_SESSION_PARKED_NAMES = ["aex.session.idle", "aex.session.error", "aex.session.suspended"];
+var AEX_SESSION_PARKED_NAMES = [
+  "aex.session.idle",
+  "aex.session.suspended",
+  "aex.session.succeeded",
+  "aex.session.failed",
+  "aex.session.timed_out",
+  "aex.session.cancelled"
+];
 function isSessionParked(e) {
   const name = customName(e);
   return name !== null && AEX_SESSION_PARKED_NAMES.includes(name);
@@ -847,8 +1116,8 @@ function parseRunUnitSubmission(input, fallbackModel) {
   return fallbackFlat(fallbackModel);
 }
 function parseFlatProjection(value, fallbackModel) {
-  const submissionRaw = isRecord(value.submission) ? value.submission : {};
-  const outputsRaw = isRecord(submissionRaw.outputs) ? submissionRaw.outputs : {};
+  const submissionRaw = isRecord2(value.submission) ? value.submission : {};
+  const outputsRaw = isRecord2(submissionRaw.outputs) ? submissionRaw.outputs : {};
   const allowedDirs = toOptionalStringArray(outputsRaw.allowedDirs);
   const deniedDirs = toOptionalStringArray(outputsRaw.deniedDirs);
   const captureTimeoutMs = toOptionalPositiveInteger(outputsRaw.captureTimeoutMs);
@@ -901,12 +1170,12 @@ function fallbackFlat(fallbackModel) {
     }
   };
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizeRunUnit(raw) {
-  const r = isRecord(raw) ? raw : {};
-  const eventsRaw = isRecord(r.events) ? r.events : {};
+  const r = isRecord2(raw) ? raw : {};
+  const eventsRaw = isRecord2(r.events) ? r.events : {};
   const str3 = (v) => typeof v === "string" ? v : void 0;
   const arr = (v) => Array.isArray(v) ? v : [];
   return {
@@ -925,7 +1194,7 @@ function normalizeRunUnit(raw) {
     // 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 } : {},
+    ...isRecord2(r.capsSnapshot) ? { capsSnapshot: r.capsSnapshot } : {},
     attempts: arr(r.attempts),
     events: {
       entries: arr(eventsRaw.entries),
@@ -936,8 +1205,8 @@ function normalizeRunUnit(raw) {
     rawEventPages: arr(r.rawEventPages),
     outputs: arr(r.outputs),
     outputCaptureFailures: arr(r.outputCaptureFailures),
-    ...isRecord(r.costTelemetry) ? { costTelemetry: r.costTelemetry } : {},
-    ...isRecord(r.runtimeManifest) ? { runtimeManifest: r.runtimeManifest } : {}
+    ...isRecord2(r.costTelemetry) ? { costTelemetry: r.costTelemetry } : {},
+    ...isRecord2(r.runtimeManifest) ? { runtimeManifest: r.runtimeManifest } : {}
   };
 }
 function coerceRunUnitModel(value) {
@@ -950,7 +1219,7 @@ function coerceRunUnitModel(value) {
   }
 }
 function isJsonRecord(value) {
-  return isRecord(value);
+  return isRecord2(value);
 }
 function toStringArray(value) {
   if (!Array.isArray(value)) {
@@ -979,11 +1248,11 @@ function toMcpServerRefArray(value) {
   return out;
 }
 function parseEnvironment(value) {
-  if (!isRecord(value)) {
+  if (!isRecord2(value)) {
     return void 0;
   }
   const env = {};
-  if (isRecord(value.networking)) {
+  if (isRecord2(value.networking)) {
     const mode = value.networking.mode;
     const allowedHosts = value.networking.allowedHosts;
     if (mode === "limited" || mode === "open") {
@@ -994,7 +1263,7 @@ function parseEnvironment(value) {
     }
   }
   if (Array.isArray(value.packages)) {
-    const pkgs = value.packages.filter(isRecord).map((p) => {
+    const pkgs = value.packages.filter(isRecord2).map((p) => {
       const r = p;
       if (typeof r.name !== "string")
         return null;
@@ -1009,7 +1278,7 @@ function parseEnvironment(value) {
       env.packages = pkgs;
     }
   }
-  if (isRecord(value.envVars)) {
+  if (isRecord2(value.envVars)) {
     const out = {};
     for (const [k, v] of Object.entries(value.envVars)) {
       if (typeof v === "string") {
@@ -1438,6 +1707,9 @@ function isSecretKey(key) {
   return /(?:api[_-]?key|authorization|token|secret|password|credential)/i.test(key);
 }
 function looksHighEntropySecret(value) {
+  return value.split("-").some(isOpaqueSecretRun);
+}
+function isOpaqueSecretRun(value) {
   if (charClassCount(value) < MIN_CHAR_CLASSES)
     return false;
   if (shannonEntropyBits(value) < ENTROPY_BITS_PER_CHAR)
@@ -1481,6 +1753,11 @@ var AexError = class extends Error {
     this.details = details === void 0 ? void 0 : redactSecrets(details);
   }
 };
+var RunConfigValidationError = class extends AexError {
+  constructor(message, details) {
+    super("RUN_CONFIG_INVALID", message, details);
+  }
+};
 var RunStateError = class extends AexError {
   constructor(message, details) {
     super("RUN_STATE_ERROR", message, details);
@@ -1489,10 +1766,58 @@ var RunStateError = class extends AexError {
 var AexApiError = class extends AexError {
   status;
   body;
-  constructor(status2, message, body) {
-    super("API_ERROR", message, body);
+  /** The server's stable error code, when the body carried a known one. */
+  apiCode;
+  /** Request id (body `requestId` or a response header) for support correlation. */
+  requestId;
+  constructor(status2, message, body, options) {
+    super("API_ERROR", message, body, options?.cause === void 0 ? void 0 : { cause: options.cause });
     this.status = status2;
     this.body = redactSecrets(body);
+    this.apiCode = options?.apiCode;
+    this.requestId = options?.requestId;
+  }
+};
+var AexAuthError = class extends AexApiError {
+  /** The scope the endpoint required, when the server named it (insufficient_scope). */
+  requiredScope;
+  constructor(init) {
+    super(init.status, init.message, init.body, {
+      apiCode: init.apiCode,
+      requestId: init.requestId,
+      cause: init.cause
+    });
+    this.requiredScope = init.requiredScope;
+  }
+};
+var AexIdempotencyConflictError = class extends AexApiError {
+  constructor(init) {
+    super(init.status, init.message, init.body, {
+      apiCode: init.apiCode,
+      requestId: init.requestId,
+      cause: init.cause
+    });
+  }
+};
+var AexNotFoundError = class extends AexApiError {
+  constructor(init) {
+    super(init.status, init.message, init.body, {
+      apiCode: init.apiCode,
+      requestId: init.requestId,
+      cause: init.cause
+    });
+  }
+};
+var AexRateLimitError = class extends AexApiError {
+  /** Suggested backoff (ms), when the server advertised one (Retry-After). */
+  retryAfterMs;
+  constructor(init) {
+    super(init.status, init.message, init.body, {
+      apiCode: init.apiCode,
+      requestId: init.requestId,
+      cause: init.cause
+    });
+    this.retryAfterMs = init.retryAfterMs;
   }
 };
 var AexNetworkError = class extends AexError {
@@ -1504,6 +1829,8 @@ var AexNetworkError = class extends AexError {
   causeCode;
   /** Attempts made when a retry layer exhausted its budget; `1` otherwise. */
   attempts;
+  /** Total elapsed time (ms) across all attempts, when the retry layer set it. */
+  elapsedMs;
   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 });
@@ -1512,6 +1839,7 @@ var AexNetworkError = class extends AexError {
     this.path = args.path;
     this.causeCode = causeCode;
     this.attempts = args.attempts ?? 1;
+    this.elapsedMs = args.elapsedMs;
   }
 };
 function networkErrorMessage(args, causeCode) {
@@ -1575,9 +1903,185 @@ function stringProperty(value, key) {
   return typeof prop === "string" && prop.length > 0 ? prop : void 0;
 }
 
+// ../contracts/dist/bundle-manifest.js
+var META_TEXT_ENCODER = new TextEncoder();
+var META_TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
+
 // ../contracts/dist/webhook-verify.js
 var encoder2 = new TextEncoder();
 
+// ../contracts/dist/error-codes.js
+var AEX_API_ERROR_CODES = [
+  "unauthorized",
+  "forbidden",
+  "insufficient_scope",
+  "token_invalid",
+  "token_revoked",
+  "token_expired",
+  "malformed_token",
+  "not_found",
+  "idempotency_conflict",
+  "session_busy",
+  "run_not_terminal",
+  "unknown_workspace",
+  "workspace_concurrency_exceeded",
+  "workspace_submit_rate_exceeded",
+  "workspace_spend_cap_exceeded",
+  "insufficient_balance",
+  "rate_limited",
+  "upstream_error",
+  "internal_error"
+];
+var AEX_API_ERROR_MESSAGES = {
+  unauthorized: "The request was not authenticated.",
+  forbidden: "The API key is not permitted to perform this action.",
+  insufficient_scope: "The API key is missing a scope this endpoint requires.",
+  token_invalid: "The API key is not valid.",
+  token_revoked: "The API key has been revoked.",
+  token_expired: "The API key has expired.",
+  malformed_token: "The API key is malformed.",
+  not_found: "The requested resource was not found.",
+  idempotency_conflict: "This idempotency key was already used with a different request body.",
+  session_busy: "The session is busy handling another turn.",
+  run_not_terminal: "The run has not reached a terminal state yet.",
+  unknown_workspace: "The workspace could not be resolved from the API key.",
+  workspace_concurrency_exceeded: "The workspace has reached its concurrent-run limit.",
+  workspace_submit_rate_exceeded: "The workspace submit-rate limit was exceeded.",
+  workspace_spend_cap_exceeded: "The workspace monthly spend cap was reached.",
+  insufficient_balance: "The workspace prepaid balance is insufficient to submit this run.",
+  rate_limited: "Too many requests \u2014 retry after a short backoff.",
+  upstream_error: "An upstream provider returned an error.",
+  internal_error: "The aex API encountered an internal error."
+};
+var API_ERROR_CODE_SET = new Set(AEX_API_ERROR_CODES);
+function isAexApiErrorCode(value) {
+  return typeof value === "string" && API_ERROR_CODE_SET.has(value);
+}
+
+// ../contracts/dist/error-factory.js
+function apiErrorKindForCode(code) {
+  switch (code) {
+    case "unauthorized":
+    case "forbidden":
+    case "insufficient_scope":
+    case "token_invalid":
+    case "token_revoked":
+    case "token_expired":
+    case "malformed_token":
+      return "auth";
+    case "idempotency_conflict":
+      return "idempotency";
+    case "not_found":
+      return "not_found";
+    case "rate_limited":
+    case "workspace_concurrency_exceeded":
+    case "workspace_submit_rate_exceeded":
+      return "rate_limit";
+    case "session_busy":
+    case "run_not_terminal":
+    case "unknown_workspace":
+    case "workspace_spend_cap_exceeded":
+    case "insufficient_balance":
+    case "upstream_error":
+    case "internal_error":
+      return "generic";
+  }
+}
+function kindForStatus(status2) {
+  if (status2 === 401 || status2 === 403)
+    return "auth";
+  if (status2 === 404)
+    return "not_found";
+  if (status2 === 409)
+    return "idempotency";
+  if (status2 === 429)
+    return "rate_limit";
+  return "generic";
+}
+function apiErrorFromResponse(input) {
+  const apiCode = apiCodeFromBody(input.body);
+  const requestId = input.requestId ?? requestIdFromBody(input.body);
+  const message = input.message ?? fallbackMessage(apiCode, input.body);
+  const kind = apiCode !== void 0 ? apiErrorKindForCode(apiCode) : kindForStatus(input.status);
+  const init = {
+    status: input.status,
+    message,
+    body: input.body,
+    apiCode,
+    requestId,
+    cause: input.cause
+  };
+  switch (kind) {
+    case "auth":
+      return new AexAuthError({ ...init, requiredScope: requiredScopeFromBody(input.body) });
+    case "idempotency":
+      return new AexIdempotencyConflictError(init);
+    case "not_found":
+      return new AexNotFoundError(init);
+    case "rate_limit":
+      return new AexRateLimitError({ ...init, retryAfterMs: retryAfterMsFromBody(input.body) });
+    case "generic":
+      return new AexApiError(input.status, message, input.body, {
+        apiCode,
+        requestId,
+        ...input.cause !== void 0 ? { cause: input.cause } : {}
+      });
+  }
+}
+function asRecord(body) {
+  return body !== null && typeof body === "object" && !Array.isArray(body) ? body : void 0;
+}
+function apiCodeFromBody(body) {
+  const record = asRecord(body);
+  if (!record)
+    return void 0;
+  if (isAexApiErrorCode(record.error))
+    return record.error;
+  if (isAexApiErrorCode(record.code))
+    return record.code;
+  return void 0;
+}
+function requestIdFromBody(body) {
+  const record = asRecord(body);
+  const value = record?.requestId;
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function requiredScopeFromBody(body) {
+  const record = asRecord(body);
+  if (!record)
+    return void 0;
+  for (const key of ["requiredScope", "required_scope", "scope"]) {
+    const value = record[key];
+    if (typeof value === "string" && value.length > 0)
+      return value;
+  }
+  return void 0;
+}
+function retryAfterMsFromBody(body) {
+  const record = asRecord(body);
+  if (!record)
+    return void 0;
+  if (typeof record.retryAfterMs === "number" && Number.isFinite(record.retryAfterMs)) {
+    return record.retryAfterMs;
+  }
+  if (typeof record.retryAfter === "number" && Number.isFinite(record.retryAfter)) {
+    return record.retryAfter * 1e3;
+  }
+  return void 0;
+}
+function fallbackMessage(apiCode, body) {
+  if (apiCode !== void 0)
+    return AEX_API_ERROR_MESSAGES[apiCode];
+  const record = asRecord(body);
+  const message = record?.message;
+  if (typeof message === "string" && message.length > 0)
+    return message;
+  const error = record?.error;
+  if (typeof error === "string" && error.length > 0)
+    return error;
+  return "aex API request failed";
+}
+
 // ../contracts/dist/http.js
 var HttpClient = class {
   #baseUrl;
@@ -1629,7 +2133,11 @@ var HttpClient = class {
     const body = await readJson(response);
     if (!response.ok) {
       const errorBody = withResponseRequestId(body, response.headers);
-      throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
+      throw apiErrorFromResponse({
+        status: response.status,
+        body: errorBody,
+        message: extractErrorMessage(errorBody)
+      });
     }
     return body;
   }
@@ -1653,7 +2161,11 @@ var HttpClient = class {
     if (!response.ok) {
       const body = await readJson(response);
       const errorBody = withResponseRequestId(body, response.headers);
-      throw new AexApiError(response.status, extractErrorMessage(errorBody), errorBody);
+      throw apiErrorFromResponse({
+        status: response.status,
+        body: errorBody,
+        message: extractErrorMessage(errorBody)
+      });
     }
     return { response };
   }
@@ -1735,6 +2247,7 @@ var operations_exports = {};
 __export(operations_exports, {
   READ_OUTPUT_TEXT_DEFAULT_BYTES: () => READ_OUTPUT_TEXT_DEFAULT_BYTES,
   READ_OUTPUT_TEXT_MAX_BYTES: () => READ_OUTPUT_TEXT_MAX_BYTES,
+  approveSession: () => approveSession,
   cancelRun: () => cancelRun,
   cancelSession: () => cancelSession,
   classifyOutput: () => classifyOutput,
@@ -1750,6 +2263,7 @@ __export(operations_exports, {
   deleteSession: () => deleteSession,
   deleteSkill: () => deleteSkill,
   deleteWorkspaceAsset: () => deleteWorkspaceAsset,
+  denySession: () => denySession,
   download: () => download,
   downloadEvents: () => downloadEvents,
   downloadMetadata: () => downloadMetadata,
@@ -1776,6 +2290,7 @@ __export(operations_exports, {
   listAgentsMd: () => listAgentsMd,
   listFiles: () => listFiles,
   listOutputs: () => listOutputs,
+  listRunChildren: () => listRunChildren,
   listRunEvents: () => listRunEvents,
   listRuns: () => listRuns,
   listSecrets: () => listSecrets,
@@ -1788,12 +2303,16 @@ __export(operations_exports, {
   outputLink: () => outputLink,
   readOutputText: () => readOutputText,
   redeliverRunWebhook: () => redeliverRunWebhook,
+  requestApproval: () => requestApproval,
+  resolveIdempotencyKey: () => resolveIdempotencyKey,
   resolveOutputFileSelector: () => resolveOutputFileSelector,
   resumeSession: () => resumeSession,
   rotateSecret: () => rotateSecret,
   sendSessionMessage: () => sendSessionMessage,
+  submit: () => submit,
   submitRun: () => submitRun,
   suspendSession: () => suspendSession,
+  toFilenameMatcher: () => toFilenameMatcher,
   uploadWorkspaceAsset: () => uploadWorkspaceAsset,
   upsertSkill: () => upsertSkill,
   whoami: () => whoami
@@ -2516,6 +3035,7 @@ function zipSync(data, opts) {
 }
 
 // ../contracts/dist/operations.js
+import { randomUUID } from "node:crypto";
 async function getRun(http, runId) {
   const result = await http.request(`/api/runs/${encodeURIComponent(runId)}`);
   return hasRun(result) ? result.run : result;
@@ -2551,8 +3071,28 @@ async function listRuns(http, query) {
   }
   return changed ? { ...page, runs } : page;
 }
+function resolveIdempotencyKey(key) {
+  if (key === void 0) {
+    return `aex-idem-${randomUUID()}`;
+  }
+  if (typeof key !== "string" || key.trim().length === 0) {
+    throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+      field: "idempotencyKey",
+      value: key
+    });
+  }
+  return key;
+}
 function idempotencyHeaders(options) {
-  return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : void 0;
+  if (options?.idempotencyKey === void 0)
+    return void 0;
+  if (typeof options.idempotencyKey !== "string" || options.idempotencyKey.trim().length === 0) {
+    throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+      field: "idempotencyKey",
+      value: options.idempotencyKey
+    });
+  }
+  return { "Idempotency-Key": options.idempotencyKey };
 }
 async function createSession(http, request, options) {
   const headers = idempotencyHeaders(options);
@@ -2563,6 +3103,10 @@ async function createSession(http, request, options) {
   });
   return unwrapSession(result);
 }
+async function submit(http, request, options) {
+  const session = await createSession(http, request, options);
+  return { runId: session.sessionId ?? session.id, session };
+}
 async function getSession(http, sessionId) {
   const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}`);
   return unwrapSession(result);
@@ -2609,6 +3153,18 @@ async function resumeSession(http, sessionId, options) {
   const headers = idempotencyHeaders(options);
   return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/resume`, { method: "POST", ...headers ? { headers } : {} });
 }
+async function requestApproval(http, sessionId, options) {
+  const headers = idempotencyHeaders(options);
+  return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/request-approval`, { method: "POST", ...headers ? { headers } : {} });
+}
+async function approveSession(http, sessionId, options) {
+  const headers = idempotencyHeaders(options);
+  return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/approve`, { method: "POST", ...headers ? { headers } : {} });
+}
+async function denySession(http, sessionId, options) {
+  const headers = idempotencyHeaders(options);
+  return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/deny`, { method: "POST", ...headers ? { headers } : {} });
+}
 async function deleteSession(http, sessionId, options) {
   const headers = idempotencyHeaders(options);
   return http.request(`/api/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE", ...headers ? { headers } : {} });
@@ -2665,7 +3221,7 @@ async function findOutput(http, runId, query) {
     return null;
   if (matches.length === 1)
     return matches[0];
-  throw new RunStateError("findOutput: output query matched multiple files", {
+  throw new RunStateError("outputs.findOne: output query matched multiple files", {
     runId,
     matches: matches.map((output) => output.filename ?? output.id)
   });
@@ -2708,7 +3264,7 @@ function resolveOutputFileSelector(outputs, selector, runId) {
   if (isPathSelector(selector)) {
     const target = normalizeOutputLookupPath(selector.path);
     if (!target) {
-      throw new RunStateError("downloadOutput: output path must be non-empty", { runId, path: selector.path });
+      throw new RunStateError("outputs.download: output path must be non-empty", { runId, path: selector.path });
     }
     const matches = outputs.filter((output) => {
       if (typeof output.filename !== "string")
@@ -2722,15 +3278,15 @@ function resolveOutputFileSelector(outputs, selector, runId) {
     if (matches.length === 1)
       return matches[0];
     if (matches.length > 1) {
-      throw new RunStateError(`downloadOutput: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
+      throw new RunStateError(`outputs.download: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
     }
-    throw new RunStateError(`downloadOutput: output path "${selector.path}" was not found`, {
+    throw new RunStateError(`outputs.download: output path "${selector.path}" was not found`, {
       runId,
       path: selector.path
     });
   }
   if (typeof selector?.id !== "string" || selector.id.length === 0) {
-    throw new RunStateError("downloadOutput: selector must include an output id or path", { runId });
+    throw new RunStateError("outputs.download: selector must include an output id or path", { runId });
   }
   return { ...selector, id: selector.id };
 }
@@ -2807,6 +3363,10 @@ function grepLines(text, pattern) {
   const test = typeof pattern === "string" ? (line) => line.toLowerCase().includes(pattern.toLowerCase()) : (line) => pattern.test(line);
   return text.split("\n").filter((line) => test(line)).join("\n");
 }
+async function listRunChildren(http, runId) {
+  const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/children`);
+  return Array.isArray(result) ? result : result.children;
+}
 async function cancelRun(http, runId) {
   await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
 }
@@ -2889,6 +3449,16 @@ function normalizeOutputLookupPath(path) {
 function filterOutputs(outputs, query) {
   return outputs.filter((output) => outputMatchesQuery(output, query));
 }
+function toFilenameMatcher(filename) {
+  if (typeof filename === "string") {
+    const needle = filename.toLowerCase();
+    return (name) => name.toLowerCase().includes(needle);
+  }
+  return (name) => {
+    filename.lastIndex = 0;
+    return filename.test(name);
+  };
+}
 function classifyOutput(output) {
   const contentType = normalizeContentType(output.contentType);
   if (contentType) {
@@ -3117,7 +3687,7 @@ function jsonlEntry(path, events) {
 }
 function extractSubmissionSnapshot(run) {
   const raw = run.submission;
-  if (!isRecord2(raw) || raw.kind !== "submission" || !isRecord2(raw.submission)) {
+  if (!isRecord3(raw) || raw.kind !== "submission" || !isRecord3(raw.submission)) {
     return void 0;
   }
   return {
@@ -3126,9 +3696,9 @@ function extractSubmissionSnapshot(run) {
 }
 function extractCostTelemetry(run) {
   const raw = run.costTelemetry;
-  return isRecord2(raw) ? raw : void 0;
+  return isRecord3(raw) ? raw : void 0;
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function submitRun(http, request) {
@@ -3277,6 +3847,16 @@ async function uploadWorkspaceAsset(http, input) {
   });
 }
 
+// ../contracts/dist/api-key.js
+var API_KEY_PLANES = ["dev", "prd"];
+var API_KEY_REGION_TO_CODE = {
+  "eu-west-2": "euw2",
+  "us-west-2": "usw2",
+  "ap-northeast-1": "apn1"
+};
+var CODE_TO_REGION = Object.fromEntries(Object.entries(API_KEY_REGION_TO_CODE).map(([region, code]) => [code, region]));
+var API_KEY_PLANE_SET = new Set(API_KEY_PLANES);
+
 // dist/internal.js
 var AEX_INDEX_PATH = "/mnt/session/uploads/aex/index.json";
 
@@ -3296,6 +3876,7 @@ function extractCommonHostFlags(argv) {
   let apiKey = null;
   let aexUrl = null;
   let debug2 = false;
+  let json = false;
   const rest = [];
   for (let i2 = 0; i2 < argv.length; i2++) {
     const arg = argv[i2];
@@ -3303,6 +3884,10 @@ function extractCommonHostFlags(argv) {
       debug2 = true;
       continue;
     }
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
     if (arg === "--api-key") {
       const v = argv[++i2];
       if (v === void 0)
@@ -3325,13 +3910,13 @@ function extractCommonHostFlags(argv) {
     }
     rest.push(arg);
   }
-  return { ok: true, flags: { apiKey, aexUrl, debug: debug2, rest } };
+  return { ok: true, flags: { apiKey, aexUrl, debug: debug2, json, rest } };
 }
 async function resolveCommonHostFlags(io2, argv) {
   const extracted = extractCommonHostFlags(argv);
   if (!extracted.ok)
     return extracted;
-  const { apiKey: flagToken, aexUrl: flagUrl, debug: debug2, rest } = extracted.flags;
+  const { apiKey: flagToken, aexUrl: flagUrl, debug: debug2, json, rest } = extracted.flags;
   let token = flagToken;
   let url = flagUrl;
   let source = flagToken ? "flag" : "none";
@@ -3355,7 +3940,7 @@ async function resolveCommonHostFlags(io2, argv) {
   if (!token) {
     return { ok: false, reason: "no API key \u2014 pass --api-key or run `aex login`" };
   }
-  return { ok: true, flags: { apiKey: token, aexUrl: resolvedUrl, debug: debug2 }, rest };
+  return { ok: true, flags: { apiKey: token, aexUrl: resolvedUrl, debug: debug2, json }, rest };
 }
 function describeApiError(err2) {
   if (err2 instanceof AexApiError) {
@@ -3428,44 +4013,6 @@ function remedyForNetworkCode(code) {
       return void 0;
   }
 }
-function suggest(input, candidates) {
-  const needle = input.trim();
-  if (!needle)
-    return void 0;
-  const lower = needle.toLowerCase();
-  const prefixHits = candidates.filter((c) => c.toLowerCase().startsWith(lower));
-  if (prefixHits.length === 1)
-    return prefixHits[0];
-  let best;
-  let bestDist = Number.POSITIVE_INFINITY;
-  for (const candidate of candidates) {
-    const dist = levenshtein(needle, candidate);
-    if (dist < bestDist) {
-      bestDist = dist;
-      best = candidate;
-    }
-  }
-  return bestDist <= 2 ? best : void 0;
-}
-function levenshtein(a, b) {
-  const m = a.length;
-  const n = b.length;
-  if (m === 0)
-    return n;
-  if (n === 0)
-    return m;
-  let prev = Array.from({ length: n + 1 }, (_, j) => j);
-  let curr = new Array(n + 1);
-  for (let i2 = 1; i2 <= m; i2++) {
-    curr[0] = i2;
-    for (let j = 1; j <= n; j++) {
-      const cost = a[i2 - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[n];
-}
 function makeHttpClient(io2, flags) {
   return new HttpClient({
     baseUrl: flags.aexUrl,
@@ -3665,20 +4212,818 @@ async function runOutputsSyncCmd(io2, dirs) {
   return SUCCESS;
 }
 
-// dist/host/run-cmd.js
-import { resolve as resolvePath } from "node:path";
-var DEFAULT_SESSION_IDLE_TTL = "3m";
-async function runRunCmd(io2, argv) {
-  if (await refuseInsideManagedRun(io2, "run"))
-    return USAGE_ERR;
-  const common = await resolveCommonHostFlags(io2, argv);
-  if (!common.ok) {
-    io2.stderr(`${common.reason}
-`);
-    return USAGE_ERR;
-  }
-  let rest = common.rest;
-  const providerFlag = takeFlagValue(rest, "--provider");
+// dist/host/registry.js
+var COMMON_HOST_FLAGS = ["--api-key", "--aex-url", "--json", "--debug"];
+var RUN_FLAGS = [
+  "--provider",
+  "--model",
+  "--system",
+  "--prompt",
+  "--config",
+  "--skill",
+  "--tool",
+  "--agents-md",
+  "--file",
+  "--mcp",
+  "--mcp-auth",
+  "--metadata",
+  "--runtime-size",
+  "--run-timeout",
+  "--idempotency-key",
+  "--webhook",
+  "--follow",
+  "--timeout"
+];
+var OUTPUTS_SUBVERBS = ["read", "download", "link", "find", "search"];
+var CLI_VERBS = [
+  {
+    name: "run",
+    summary: "One-shot: open a session, send the prompt as the first turn (delegates to the SDK).",
+    usage: [
+      "aex run --model M --prompt P [--system S] [--provider name] --<provider>-api-key K",
+      "aex run --config <run.json> --<provider>-api-key K",
+      "  --skill @file        Attach a workspace skill bundle (repeatable)",
+      "  --tool @file.js      Attach a custom tool module (repeatable)",
+      "  --agents-md @file    Attach an AGENTS.md brief (repeatable)",
+      "  --file @path         Mount a file into /workspace (repeatable)",
+      "  --mcp name=url       MCP server (repeatable); --mcp-auth name=Hdr:Val for headers",
+      "  --metadata key=value Submission metadata (repeatable)",
+      "  --runtime-size <s>   Managed runtime preset",
+      "  --run-timeout <dur>  Server-side run deadline (validated client-side by the SDK)",
+      "  --webhook <url>      Per-run terminal callback (https)",
+      "  --follow             Stream the turn's events until the session parks"
+    ],
+    flags: RUN_FLAGS
+  },
+  {
+    name: "status",
+    summary: "Print a session/run record (GET /api/sessions/:id).",
+    usage: ["aex status <session-id>"]
+  },
+  {
+    name: "deliveries",
+    summary: "List a run's webhook delivery attempts.",
+    usage: ["aex deliveries <session-id>"]
+  },
+  {
+    name: "wait",
+    summary: "Poll a session until it parks; exit code reflects the outcome.",
+    usage: ["aex wait <session-id> [--timeout 8m] [--interval 2s]"],
+    flags: ["--timeout", "--interval"]
+  },
+  {
+    name: "events",
+    summary: "List (or --follow) a session's events as NDJSON.",
+    usage: ["aex events <session-id> [--follow] [--timeout 8m]"],
+    flags: ["--follow", "--timeout"]
+  },
+  {
+    name: "tail",
+    summary: "Live human-readable follow over the coordinator event stream.",
+    usage: ["aex tail <session-id> [--filter <type|source>] [--logs] [--from <seq>] [--settle] [--timeout <dur>]"],
+    flags: ["--filter", "--logs", "--from", "--settle", "--timeout"]
+  },
+  {
+    name: "inspect",
+    summary: "One-shot full-timeline render + jump-to-failure summary.",
+    usage: ["aex inspect <session-id> [--filter <type|source>] [--logs] [--timeout <dur>]"],
+    flags: ["--filter", "--logs", "--timeout"]
+  },
+  {
+    name: "outputs",
+    summary: "List a session's captured outputs, or read/download/link/find/search one file.",
+    usage: [
+      "aex outputs <session-id>                         List captured outputs (NDJSON)",
+      "aex outputs read <session-id> <path>             Read one file as capped text",
+      "aex outputs download <session-id> <path> [--out] Download one file's raw bytes",
+      "aex outputs link <session-id> <path>             Mint a temporary download URL",
+      "aex outputs find <session-id> [--name S] [--ext E] [--type T]",
+      "aex outputs search [--query S] [--name S] [--ext E] [--run-id ID]   Cross-run"
+    ],
+    flags: ["--out", "--name", "--ext", "--type", "--content-type", "--query", "--run-id", "--limit", "--max-bytes"],
+    subverbs: OUTPUTS_SUBVERBS
+  },
+  {
+    name: "download",
+    summary: "Download a session's content as a zip (whole or one namespace).",
+    usage: ["aex download <session-id> [--only outputs|events|metadata] [--out path]"],
+    flags: ["--only", "--out"]
+  },
+  {
+    name: "cancel",
+    summary: "Cancel a running session.",
+    usage: ["aex cancel <session-id>"]
+  },
+  {
+    name: "delete",
+    summary: "Delete a session.",
+    usage: ["aex delete <session-id>"]
+  },
+  {
+    name: "delete-asset",
+    summary: "Delete a workspace asset blob by hash.",
+    usage: ["aex delete-asset <assetId|hash>"]
+  },
+  {
+    name: "runs",
+    summary: "List the workspace's runs (newest first).",
+    usage: ["aex runs [--limit N] [--since ISO]"],
+    flags: ["--limit", "--since"]
+  },
+  {
+    name: "sessions",
+    summary: "List the workspace's sessions (newest first).",
+    usage: ["aex sessions [--limit N]"],
+    flags: ["--limit"]
+  },
+  {
+    name: "whoami",
+    summary: "Resolve the API key to its workspace + scopes.",
+    usage: ["aex whoami [--json]"]
+  },
+  {
+    name: "billing",
+    summary: "Show balance / spend / cap; ledger, upgrade, and portal sub-verbs.",
+    usage: [
+      "aex billing [--json]",
+      "aex billing ledger [--limit N]",
+      "aex billing upgrade pro|team",
+      "aex billing portal"
+    ],
+    subverbs: ["ledger", "upgrade", "portal"]
+  },
+  {
+    name: "webhooks",
+    summary: "Reveal the workspace webhook signing secret.",
+    usage: ["aex webhooks secret"],
+    subverbs: ["secret"]
+  },
+  {
+    name: "login",
+    summary: "Persist the API key + url so other verbs need no --api-key.",
+    usage: ["aex login --api-key T [--aex-url U]"]
+  },
+  {
+    name: "logout",
+    summary: "Clear the stored token.",
+    usage: ["aex logout"]
+  },
+  {
+    name: "auth",
+    summary: "Show the resolved config (token never printed).",
+    usage: ["aex auth status"],
+    subverbs: ["status"]
+  },
+  {
+    name: "models",
+    summary: "List models + default provider (no token needed).",
+    usage: ["aex models list [--json]"]
+  },
+  {
+    name: "providers",
+    summary: "List providers + their models (no token needed).",
+    usage: ["aex providers list [--json]"]
+  },
+  {
+    name: "tools",
+    summary: "List builtin tools (no token needed).",
+    usage: ["aex tools list [--json]"]
+  },
+  {
+    name: "runtime-sizes",
+    summary: "List managed runtime presets (no token needed).",
+    usage: ["aex runtime-sizes list [--json]"]
+  },
+  {
+    name: "debug",
+    summary: "Operator: read the AWS plane directly (AWS creds, not --api-key).",
+    usage: ["aex debug <run-id> [--plane dev|prd] [--region eu-west-2] [--cloudwatch] [--with-outputs]"]
+  }
+];
+var VERB_BY_NAME = new Map(CLI_VERBS.map((v) => [v.name, v]));
+var CLI_VERB_NAMES = CLI_VERBS.map((v) => v.name);
+function findVerbSpec(name) {
+  return VERB_BY_NAME.get(name);
+}
+function wantsVerbHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+function renderVerbHelp(spec) {
+  const lines = [`aex ${spec.name} \u2014 ${spec.summary}`, "", "Usage:"];
+  for (const u of spec.usage)
+    lines.push(`  ${u}`);
+  lines.push("", `Common flags: ${COMMON_HOST_FLAGS.join(" ")}`);
+  return lines.join("\n") + "\n";
+}
+
+// dist/host/run-cmd.js
+import { resolve as resolvePath } from "node:path";
+
+// dist/host/run-submit.js
+var TEXT = new TextEncoder();
+var ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
+var UPLOAD_CONCURRENCY = 5;
+async function submitCliRun(http, fetchImpl, options) {
+  const request = await buildSessionCreateRequest(http, fetchImpl, options);
+  const submitted = await operations_exports.submit(http, request, { idempotencyKey: operations_exports.resolveIdempotencyKey(options.idempotencyKey) });
+  return submitted.session;
+}
+async function buildCliSkill(content, source) {
+  const front = extractSkillFrontmatter("Skill.fromContent", { "SKILL.md": content });
+  const name = deriveSkillName("Skill.fromContent", front.name, void 0, void 0);
+  const description = front.description;
+  if (typeof description !== "string" || description.trim().length === 0) {
+    throw new Error(`${source}: a skill description is required in SKILL.md frontmatter`);
+  }
+  if (description.length > 2048) {
+    throw new Error(`${source}: description must be <= 2048 chars`);
+  }
+  const bytes = bundleSkillFiles({ "SKILL.md": content });
+  return {
+    name,
+    description,
+    contentHash: await hashBytes(bytes),
+    bytes
+  };
+}
+async function buildCliTool(args) {
+  const inputSchema = { type: "object", properties: {}, additionalProperties: true };
+  const manifest = normalizeToolManifest("Tool.fromFiles", {
+    name: args.name,
+    description: args.description,
+    input_schema: inputSchema,
+    entry: args.entry
+  }, { [args.entry]: args.content });
+  const bytes = bundleToolFiles({ [args.entry]: args.content }, manifest);
+  return {
+    ref: {
+      kind: "asset",
+      contentHash: await hashBytes(bytes),
+      ...manifest
+    },
+    bytes
+  };
+}
+async function buildCliAgentsMd(content, name) {
+  if (typeof content !== "string" || content.length === 0) {
+    throw new Error("AgentsMd.fromContent: content must be a non-empty string");
+  }
+  if (!/^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$/.test(name)) {
+    throw new Error("AgentsMd.fromContent: name must be a lowercase workspace slug");
+  }
+  const bytes = zipSync({ "AGENTS.md": [TEXT.encode(content), { mtime: ZIP_EPOCH }] }, { level: 6 });
+  return { name, contentHash: await hashBytes(bytes), bytes };
+}
+async function buildCliFile(args) {
+  const filename = sanitiseFilename(args.name);
+  if (filename === void 0) {
+    throw new Error(`File.fromBytes: name ${JSON.stringify(args.name)} is not a valid filename`);
+  }
+  const bytes = TEXT.encode(args.content);
+  if (bytes.byteLength === 0) {
+    throw new Error("File.fromBytes: bytes must be a non-empty Uint8Array");
+  }
+  const zip = zipSync({ [filename]: [bytes, { mtime: ZIP_EPOCH }] }, { level: 6 });
+  return {
+    name: slugFromFilename(filename),
+    contentHash: await hashBytes(zip),
+    mountPath: DEFAULT_FILE_MOUNT_PATH,
+    bytes: zip
+  };
+}
+function toCliSessionEnvironment(env) {
+  if (!env)
+    return void 0;
+  const out = {
+    ...env.networking ? { networking: env.networking } : {},
+    ...env.packages ? { packages: env.packages } : {},
+    ...env.envVars ? { variables: env.envVars } : {}
+  };
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
+async function buildSessionCreateRequest(http, fetchImpl, options) {
+  const input = normaliseSessionInput(options.message);
+  const provider = resolveModelProvider(options.model, options.provider);
+  validateApiKeys(options.apiKeys, provider);
+  try {
+    parseRunTimeout(options.overrides?.timeout);
+    if (options.webhook !== void 0)
+      parseRunWebhook(options.webhook);
+  } catch (err2) {
+    throw new Error(err2 instanceof Error ? err2.message : String(err2));
+  }
+  const limitsInput = {};
+  if (options.overrides?.maxSpendUsd !== void 0)
+    limitsInput.maxSpendUsd = options.overrides.maxSpendUsd;
+  if (options.overrides?.maxTurns !== void 0)
+    limitsInput.maxTurns = options.overrides.maxTurns;
+  const limits = parseRunLimits(Object.keys(limitsInput).length > 0 ? limitsInput : void 0);
+  const [preparedTools, preparedSkills, preparedAgentsMd, preparedFiles] = await Promise.all([
+    prepareTools(http, fetchImpl, options.tools ?? []),
+    prepareSkills(http, fetchImpl, options.skills ?? []),
+    prepareAgentsMd(http, fetchImpl, options.agentsMd ?? []),
+    prepareFiles(http, fetchImpl, options.files ?? [])
+  ]);
+  const { submissionMcpServers, mergedMcpSecrets } = mergeMcpServers(options.mcpServers ?? []);
+  const environment = sessionEnvironmentForWire(options.environment);
+  const submission = {
+    model: options.model,
+    ...options.system ? { system: options.system } : {},
+    tools: [...preparedTools.builtinNames, ...preparedTools.refs],
+    ...preparedSkills.length > 0 ? { skills: preparedSkills } : {},
+    agentsMd: preparedAgentsMd,
+    files: preparedFiles,
+    mcpServers: submissionMcpServers,
+    ...environment ? { environment } : {},
+    ...options.metadata ? { metadata: options.metadata } : {}
+  };
+  const secrets = {
+    ...options.apiKeys ? { apiKeys: options.apiKeys } : {},
+    ...mergedMcpSecrets.length > 0 ? { mcpServers: mergedMcpSecrets } : {}
+  };
+  return {
+    provider,
+    submission,
+    input,
+    ...options.runtime ? { runtimeSize: options.runtime } : {},
+    ...options.overrides?.timeout ? { timeout: options.overrides.timeout } : {},
+    ...limits ? { limits } : {},
+    retention: { idleTtl: options.overrides?.idleTtl ?? "3m" },
+    ...options.webhook ? { webhook: options.webhook } : {},
+    secrets
+  };
+}
+function normaliseSessionInput(input) {
+  if (typeof input === "string") {
+    if (!input)
+      throw new Error("Aex.submit: message must be a non-empty string");
+    return input;
+  }
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new Error("Aex.submit: message must be a non-empty string or string array");
+  }
+  for (const segment of input) {
+    if (typeof segment !== "string" || !segment) {
+      throw new Error("Aex.submit: message segments must be non-empty strings");
+    }
+  }
+  return [...input];
+}
+function validateApiKeys(apiKeys, provider) {
+  const key = apiKeys?.[provider];
+  if (typeof key !== "string" || key.length === 0) {
+    throw new Error(`Aex.submit: a provider API key is required for provider ${provider}; pass apiKeys.${provider}`);
+  }
+}
+async function prepareTools(http, fetchImpl, tools) {
+  const prepared = await mapWithConcurrency(tools, UPLOAD_CONCURRENCY, async (entry, i2) => {
+    if (typeof entry === "string") {
+      if (!BUILTIN_TOOL_NAMES.includes(entry)) {
+        throw new Error(`aex: tools[${i2}] (${JSON.stringify(entry)}) is not a builtin tool name`);
+      }
+      return { kind: "builtin", name: entry };
+    }
+    const uploaded = await uploadAsset(http, fetchImpl, {
+      bytes: entry.bytes,
+      hash: entry.ref.contentHash,
+      contentType: "application/zip"
+    });
+    const { contentHash: _contentHash, ...ref } = entry.ref;
+    void _contentHash;
+    return { kind: "ref", ref: { ...ref, assetId: uploaded.assetId } };
+  });
+  const refs = [];
+  const seenBuiltins = /* @__PURE__ */ new Set();
+  const builtinNames = [];
+  for (const item of prepared) {
+    if (item.kind === "builtin") {
+      if (!seenBuiltins.has(item.name)) {
+        seenBuiltins.add(item.name);
+        builtinNames.push(item.name);
+      }
+    } else {
+      refs.push(item.ref);
+    }
+  }
+  return { refs, builtinNames };
+}
+async function prepareSkills(http, fetchImpl, skills) {
+  if (skills.length > SKILLS_MAX) {
+    throw new Error(`aex: skills exceeds the ${SKILLS_MAX}-skill limit (got ${skills.length})`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const skill of skills) {
+    if (seen.has(skill.name))
+      throw new Error(`aex: skills duplicate name: ${skill.name}`);
+    seen.add(skill.name);
+  }
+  return mapWithConcurrency(skills, UPLOAD_CONCURRENCY, async (skill) => {
+    await uploadAsset(http, fetchImpl, { bytes: skill.bytes, hash: skill.contentHash, contentType: "application/zip" });
+    await operations_exports.upsertSkill(http, {
+      name: skill.name,
+      contentHash: skill.contentHash,
+      description: skill.description,
+      sizeBytes: skill.bytes.byteLength
+    });
+    return { kind: "skill", name: skill.name };
+  });
+}
+async function prepareAgentsMd(http, fetchImpl, agentsMds) {
+  return mapWithConcurrency(agentsMds, UPLOAD_CONCURRENCY, async (entry) => {
+    const uploaded = await uploadAsset(http, fetchImpl, {
+      bytes: entry.bytes,
+      hash: entry.contentHash,
+      contentType: "application/zip"
+    });
+    return { kind: "asset", assetId: uploaded.assetId, name: entry.name };
+  });
+}
+async function prepareFiles(http, fetchImpl, files) {
+  return mapWithConcurrency(files, UPLOAD_CONCURRENCY, async (entry) => {
+    const uploaded = await uploadAsset(http, fetchImpl, {
+      bytes: entry.bytes,
+      hash: entry.contentHash,
+      contentType: "application/zip"
+    });
+    return { kind: "asset", assetId: uploaded.assetId, name: entry.name, mountPath: entry.mountPath };
+  });
+}
+function mergeMcpServers(inputs) {
+  const submissionMcpServers = [];
+  const mergedMcpSecrets = [];
+  for (const entry of inputs) {
+    submissionMcpServers.push({ name: entry.name, url: entry.url });
+    if (entry.headers && Object.keys(entry.headers).length > 0) {
+      mergedMcpSecrets.push({ name: entry.name, url: entry.url, headers: { ...entry.headers } });
+    }
+  }
+  return { submissionMcpServers, mergedMcpSecrets };
+}
+function sessionEnvironmentForWire(environment) {
+  if (environment === void 0)
+    return void 0;
+  const { variables, ...rest } = environment;
+  const out = {
+    ...rest,
+    ...variables !== void 0 ? { envVars: variables } : {}
+  };
+  return Object.keys(out).length === 0 ? void 0 : out;
+}
+async function uploadAsset(http, fetchImpl, args) {
+  const expected = args.hash.startsWith("sha256:") ? args.hash.slice("sha256:".length) : args.hash;
+  const actual = await sha256Hex(args.bytes);
+  if (actual !== expected) {
+    throw new Error(`uploadAsset: client-side hash mismatch: computed sha256:${actual} but caller declared ${args.hash}`);
+  }
+  const contentHash = `sha256:${actual}`;
+  const presign = await http.request("/assets/presign", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ hash: contentHash, sizeBytes: args.bytes.byteLength })
+  });
+  if (presign.exists) {
+    const storedHash2 = presign.contentHash ?? contentHash;
+    return {
+      assetId: presign.assetId ?? assetIdFromContentHash(storedHash2),
+      contentHash: storedHash2,
+      sizeBytes: presign.sizeBytes ?? args.bytes.byteLength,
+      exists: true
+    };
+  }
+  if (!presign.uploadUrl) {
+    throw new Error("uploadAsset: presign returned no uploadUrl and exists:false");
+  }
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  const put = await doFetch(presign.uploadUrl, {
+    method: "PUT",
+    headers: {
+      "content-type": args.contentType ?? "application/zip",
+      ...presign.requiredHeaders ?? {}
+    },
+    body: args.bytes
+  });
+  if (!put.ok) {
+    throw new Error(`uploadAsset: direct upload PUT failed with status ${put.status}`);
+  }
+  const fin = await http.request("/assets/finalize", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ hash: contentHash, sizeBytes: args.bytes.byteLength })
+  });
+  const storedHash = fin.contentHash ?? presign.contentHash ?? contentHash;
+  return {
+    assetId: fin.assetId ?? presign.assetId ?? assetIdFromContentHash(storedHash),
+    contentHash: storedHash,
+    sizeBytes: fin.sizeBytes ?? args.bytes.byteLength,
+    exists: false
+  };
+}
+function bundleSkillFiles(files) {
+  const collected = collectBundleFiles("Skill bundle", files, true);
+  return zipCollected(collected);
+}
+function bundleToolFiles(files, manifest) {
+  const collected = collectBundleFiles("Tool bundle", files, false);
+  const entryPath = validateSkillBundleEntry({ path: manifest.entry, size: 0 }).path;
+  if (!collected.has(entryPath)) {
+    throw new Error(`Tool bundle entry "${entryPath}" must exist in files`);
+  }
+  if (collected.has("tool.json")) {
+    throw new Error('Tool bundle files must not include reserved "tool.json"; pass manifest fields instead');
+  }
+  collected.set("tool.json", TEXT.encode(`${JSON.stringify(manifest, null, 2)}
+`));
+  return zipCollected(collected);
+}
+function collectBundleFiles(kind, files, requireSkillMd) {
+  const entries = Object.entries(files);
+  if (entries.length === 0)
+    throw new Error(`${kind} files map cannot be empty`);
+  if (entries.length > SKILL_BUNDLE_LIMITS.maxFiles) {
+    throw new Error(`${kind} exceeds ${SKILL_BUNDLE_LIMITS.maxFiles} file limit (got ${entries.length})`);
+  }
+  const collected = /* @__PURE__ */ new Map();
+  let hasSkillMd = false;
+  let total = 0;
+  for (const [rawPath, contents] of entries) {
+    const bytes = typeof contents === "string" ? TEXT.encode(contents) : contents;
+    if (!(bytes instanceof Uint8Array))
+      throw new Error(`${kind} file "${rawPath}" must be a string or Uint8Array`);
+    const entry = validateSkillBundleEntry({ path: rawPath, size: bytes.byteLength });
+    if (entry.path === "SKILL.md")
+      hasSkillMd = true;
+    total += bytes.byteLength;
+    if (total > SKILL_BUNDLE_LIMITS.maxDecompressedBytes) {
+      throw new Error(`${kind} exceeds decompressed cap of ${SKILL_BUNDLE_LIMITS.maxDecompressedBytes} bytes`);
+    }
+    if (collected.has(entry.path))
+      throw new Error(`${kind} contains duplicate path: ${entry.path}`);
+    collected.set(entry.path, bytes);
+  }
+  if (requireSkillMd && !hasSkillMd) {
+    throw new Error('Skill bundle must contain a "SKILL.md" file at the root.');
+  }
+  return collected;
+}
+function zipCollected(collected) {
+  const sorted = [...collected.entries()].sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+  const zippable = {};
+  for (const [path, bytes] of sorted) {
+    zippable[path] = [bytes, { mtime: ZIP_EPOCH }];
+  }
+  const zip = zipSync(zippable, { level: 6 });
+  if (zip.byteLength > SKILL_BUNDLE_LIMITS.maxCompressedBytes) {
+    throw new Error(`bundle exceeds compressed cap of ${SKILL_BUNDLE_LIMITS.maxCompressedBytes} bytes (got ${zip.byteLength})`);
+  }
+  return zip;
+}
+function normalizeToolManifest(source, input, files) {
+  if (typeof input.name !== "string" || !TOOL_NAME_PATTERN.test(input.name)) {
+    throw new Error(`${source}: name must match ${TOOL_NAME_PATTERN.source}`);
+  }
+  if (input.name.includes("__")) {
+    throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
+  }
+  if (typeof input.description !== "string" || input.description.trim().length === 0 || input.description.length > 2048) {
+    throw new Error(`${source}: description must be non-empty and <= 2048 chars`);
+  }
+  const inputSchema = input.input_schema;
+  if (!inputSchema || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+    throw new Error(`${source}: inputSchema must be a JSON Schema object`);
+  }
+  if (inputSchema.type !== "object") {
+    throw new Error(`${source}: inputSchema.type must be "object"`);
+  }
+  const entry = normaliseSkillBundlePath(input.entry);
+  if (!/\.(?:js|mjs|cjs)$/i.test(entry.split("/").pop() ?? entry)) {
+    throw new Error(`${source}: entry must be a JS module (.js/.mjs/.cjs)`);
+  }
+  if (!(entry in files) && !(input.entry in files)) {
+    throw new Error(`${source}: entry ${JSON.stringify(input.entry)} is not present in files`);
+  }
+  return { ...input, entry };
+}
+function extractSkillFrontmatter(source, files) {
+  const raw = files["SKILL.md"];
+  if (raw === void 0)
+    throw new Error(`${source}: the skill bundle must contain a SKILL.md at its root`);
+  const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+  return parseSkillFrontmatter(text);
+}
+function parseSkillFrontmatter(text) {
+  const src = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(src);
+  if (!match)
+    return {};
+  const out = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z0-9_-]+)[ \t]*:[ \t]*(.*)$/.exec(line);
+    if (!kv)
+      continue;
+    const key = kv[1].toLowerCase();
+    if (key !== "name" && key !== "description")
+      continue;
+    let value = kv[2].trim();
+    if (value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (value.length > 0)
+      out[key] = value;
+  }
+  return out;
+}
+function deriveSkillName(source, frontmatterName, explicitName, dirBasename) {
+  let name = explicitName ?? frontmatterName;
+  if (name === void 0 && dirBasename !== void 0) {
+    const slug = slugifyName(dirBasename);
+    if (slug.length > 0)
+      name = slug;
+  }
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error(`${source}: a skill name is required`);
+  }
+  if (!SKILL_NAME_PATTERN.test(name)) {
+    throw new Error(`${source}: name ${JSON.stringify(name)} must match ${SKILL_NAME_PATTERN.source}`);
+  }
+  if (name.includes("__")) {
+    throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
+  }
+  if (SKILL_RESERVED_NAMES.has(name)) {
+    throw new Error(`${source}: name ${JSON.stringify(name)} is reserved (${[...SKILL_RESERVED_NAMES].join(", ")})`);
+  }
+  return name;
+}
+function sanitiseFilename(name) {
+  if (typeof name !== "string" || name.length === 0 || name.length > 255)
+    return void 0;
+  if (name.includes("/") || name.includes("\\") || name.includes("\0"))
+    return void 0;
+  if (name === "." || name === "..")
+    return void 0;
+  return name;
+}
+function slugFromFilename(filename) {
+  const stem = filename.includes(".") ? filename.slice(0, filename.lastIndexOf(".")) : filename;
+  const slug = slugifyName(stem);
+  return slug.length > 0 ? slug : "file";
+}
+function slugifyName(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function hashBytes(bytes) {
+  return `sha256:${await sha256Hex(bytes)}`;
+}
+async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("sha256: globalThis.crypto.subtle is not available");
+  }
+  const view = new Uint8Array(bytes.byteLength);
+  view.set(bytes);
+  const digest = await subtle.digest("SHA-256", view.buffer);
+  return bufferToHex(digest);
+}
+function bufferToHex(buffer) {
+  const view = new Uint8Array(buffer);
+  let out = "";
+  for (const byte of view) {
+    out += byte.toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function assetIdFromContentHash(contentHash) {
+  const hex = contentHash.startsWith("sha256:") ? contentHash.slice("sha256:".length) : contentHash;
+  return `asset_${hex}`;
+}
+async function mapWithConcurrency(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const lanes = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, async () => {
+    for (let i2 = next++; i2 < items.length; i2 = next++) {
+      out[i2] = await fn(items[i2], i2);
+    }
+  });
+  await Promise.all(lanes);
+  return out;
+}
+
+// dist/host/stream-render.js
+async function* openEnvelopeStream(io2, http, sessionId, options = {}) {
+  const first = await operations_exports.getSessionCoordinatorTicket(http, sessionId);
+  if (options.debug) {
+    let host = "(invalid)";
+    try {
+      host = new URL(first.wsUrl).host;
+    } catch {
+    }
+    options.debug(`ticket minted: host=${host} expiresInMs=${first.expiresAtMs - Date.now()} from=${options.from ?? 0}`);
+  }
+  yield* streamCoordinatorEvents({
+    wsUrl: first.wsUrl,
+    from: options.from ?? 0,
+    fetchTicket: async () => (await operations_exports.getSessionCoordinatorTicket(http, sessionId)).ticket,
+    ...io2.webSocketFactory ? { webSocketFactory: io2.webSocketFactory } : {},
+    ...options.settleConsistent ? { isTerminal: isRunSettled } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+}
+var PREVIEW_MAX = 120;
+function clip(text, max = PREVIEW_MAX) {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? oneLine.slice(0, max - 1) + "\u2026" : oneLine;
+}
+function str2(v) {
+  return typeof v === "string" ? v : v === void 0 || v === null ? "" : JSON.stringify(v);
+}
+function argsPreview(e) {
+  const d = e.data;
+  const candidate = d.input ?? d.args ?? d.arguments ?? d.params;
+  if (candidate === void 0)
+    return "";
+  return clip(typeof candidate === "string" ? candidate : JSON.stringify(candidate));
+}
+function renderEnvelope(e, options = {}) {
+  if (channelOf(e) === "log" && !options.logs)
+    return null;
+  switch (e.type) {
+    case "RUN_STARTED":
+      return "\u25B6 run started";
+    case "TEXT_MESSAGE_CONTENT": {
+      const delta = toAGUI(e).type === "TEXT_MESSAGE_CONTENT" ? toAGUI(e).delta : "";
+      return delta ? delta : null;
+    }
+    case "TOOL_CALL_START": {
+      const agui = toAGUI(e);
+      const name = agui.type === "TOOL_CALL_START" ? agui.toolCallName : str2(e.data.name);
+      const preview = argsPreview(e);
+      return `\xB7 tool ${name || "(unnamed)"}(${preview})`;
+    }
+    case "TOOL_CALL_RESULT": {
+      const name = str2(e.data.name) || "result";
+      const content = e.data.content;
+      const ok = content === void 0 || content === null ? "ok" : clip(str2(content));
+      return `  \u2190 ${name} ${ok}`;
+    }
+    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": {
+      const level = e.level ?? "info";
+      return `[${level}] ${e.message ?? str2(e.data.message)}`;
+    }
+    case "RUN_FINISHED":
+      return "\u2713 run finished";
+    case "RUN_ERROR": {
+      const agui = toAGUI(e);
+      const message = agui.type === "RUN_ERROR" ? agui.message : e.message ?? "run error";
+      return `\u2717 run error: ${message}`;
+    }
+    default:
+      return null;
+  }
+}
+function parseFilters(tokens) {
+  const flattened = tokens.flatMap((t) => t.split(",")).map((s) => s.trim()).filter(Boolean);
+  if (flattened.length === 0)
+    return {};
+  const types = /* @__PURE__ */ new Set();
+  const sources = /* @__PURE__ */ new Set();
+  for (const tok of flattened) {
+    if (AEX_EVENT_TYPES.includes(tok)) {
+      types.add(tok);
+    } else if (AEX_EVENT_SOURCES.includes(tok)) {
+      sources.add(tok);
+    } else {
+      const hint = suggest(tok, [...AEX_EVENT_TYPES, ...AEX_EVENT_SOURCES]);
+      return {
+        error: `unknown --filter token "${tok}"${hint ? `; did you mean "${hint}"?` : ""} (types: ${AEX_EVENT_TYPES.join(",")}; sources: ${AEX_EVENT_SOURCES.join(",")})`
+      };
+    }
+  }
+  const predicate = (e) => (types.size === 0 || types.has(e.type)) && (sources.size === 0 || sources.has(e.source));
+  return { predicate };
+}
+
+// dist/host/run-cmd.js
+var DEFAULT_SESSION_IDLE_TTL = "3m";
+async function runRunCmd(io2, argv) {
+  if (await refuseInsideManagedRun(io2, "run"))
+    return USAGE_ERR;
+  const common = await resolveCommonHostFlags(io2, argv);
+  if (!common.ok) {
+    io2.stderr(`${common.reason}
+`);
+    return USAGE_ERR;
+  }
+  let rest = common.rest;
+  const providerFlag = takeFlagValue(rest, "--provider");
   if (providerFlag.error) {
     io2.stderr(`${providerFlag.error}
 `);
@@ -3742,9 +5087,10 @@ async function runRunCmd(io2, argv) {
   }
   rest = runTimeoutFlag.remaining;
   if (runTimeoutFlag.value) {
-    const parsed = parseDuration(runTimeoutFlag.value);
-    if (parsed.error) {
-      io2.stderr(`--run-timeout: ${parsed.error}
+    try {
+      parseRunTimeout(runTimeoutFlag.value);
+    } catch (err2) {
+      io2.stderr(`--run-timeout: ${err2.message}
 `);
       return USAGE_ERR;
     }
@@ -3791,6 +5137,34 @@ async function runRunCmd(io2, argv) {
     return USAGE_ERR;
   }
   rest = promptFlags.remaining;
+  const skillFlags = collectRepeated(rest, "--skill");
+  if (skillFlags.error) {
+    io2.stderr(`${skillFlags.error}
+`);
+    return USAGE_ERR;
+  }
+  rest = skillFlags.remaining;
+  const toolFlags = collectRepeated(rest, "--tool");
+  if (toolFlags.error) {
+    io2.stderr(`${toolFlags.error}
+`);
+    return USAGE_ERR;
+  }
+  rest = toolFlags.remaining;
+  const agentsMdFlags = collectRepeated(rest, "--agents-md");
+  if (agentsMdFlags.error) {
+    io2.stderr(`${agentsMdFlags.error}
+`);
+    return USAGE_ERR;
+  }
+  rest = agentsMdFlags.remaining;
+  const fileFlags = collectRepeated(rest, "--file");
+  if (fileFlags.error) {
+    io2.stderr(`${fileFlags.error}
+`);
+    return USAGE_ERR;
+  }
+  rest = fileFlags.remaining;
   const mcpFlags = collectRepeatedKv(rest, "--mcp");
   if (mcpFlags.error) {
     io2.stderr(`${mcpFlags.error}
@@ -3842,79 +5216,85 @@ async function runRunCmd(io2, argv) {
 `);
     return USAGE_ERR;
   }
-  let runConfig;
-  let mcpHeadersFromConfig = /* @__PURE__ */ new Map();
+  let model;
+  let system;
+  let promptArray;
+  let configMcpServers = [];
+  let configEnvironment;
+  let configRuntimeSize;
+  let configTimeout;
+  let metadata;
+  const mcpHeaderBag = /* @__PURE__ */ new Map();
   if (config.value) {
     if (modelFlag.value || systemFlag.value || promptFlags.values.length || Object.keys(mcpFlags.entries).length || Object.keys(metadataFlags.entries).length) {
       io2.stderr("--config cannot be combined with --model/--system/--prompt/--mcp/--metadata\n");
       return USAGE_ERR;
     }
+    let runConfig;
     try {
       const absPath = resolvePath(io2.cwd(), config.value);
       const text = await io2.readFile(absPath);
       const raw = JSON.parse(text);
       const { mcpHeaders, normalised } = stripMcpHeadersForParsing(raw);
-      mcpHeadersFromConfig = mcpHeaders;
+      for (const [name, headers] of mcpHeaders)
+        mcpHeaderBag.set(name, headers);
       runConfig = parseRunRequestConfig(normalised);
     } catch (err2) {
       io2.stderr(`failed to load --config: ${err2.message}
 `);
       return USAGE_ERR;
     }
+    model = runConfig.model;
+    system = runConfig.system;
+    promptArray = Array.isArray(runConfig.prompt) ? [...runConfig.prompt] : [runConfig.prompt];
+    configMcpServers = runConfig.mcpServers ?? [];
+    configEnvironment = runConfig.environment;
+    configRuntimeSize = runConfig.runtimeSize;
+    configTimeout = runConfig.timeout;
+    metadata = runConfig.metadata ? { ...runConfig.metadata } : void 0;
   } else {
     if (!modelFlag.value) {
       io2.stderr("--model is required when --config is not provided\n");
       return USAGE_ERR;
     }
-    if (!RUN_MODELS.includes(modelFlag.value)) {
-      const hint = suggest(modelFlag.value, RUN_MODELS);
-      io2.stderr(`--model must be one of: ${RUN_MODELS.join(", ")} (got: ${modelFlag.value})${hint ? `; did you mean "${hint}"?` : ""}
-`);
-      return USAGE_ERR;
-    }
+    model = modelFlag.value;
     if (promptFlags.values.length === 0) {
       io2.stderr("--prompt is required (repeatable)\n");
       return USAGE_ERR;
     }
-    let resolvedPrompt;
     try {
-      resolvedPrompt = await Promise.all(promptFlags.values.map((v) => readMaybeFile(io2, v)));
+      promptArray = await Promise.all(promptFlags.values.map((v) => readMaybeFile(io2, v)));
     } catch (err2) {
       io2.stderr(`failed to read --prompt file: ${err2.message}
 `);
       return USAGE_ERR;
     }
-    let resolvedSystem;
     if (systemFlag.value !== null) {
       try {
-        resolvedSystem = await readMaybeFile(io2, systemFlag.value);
+        system = await readMaybeFile(io2, systemFlag.value);
       } catch (err2) {
         io2.stderr(`failed to read --system file: ${err2.message}
 `);
         return USAGE_ERR;
       }
     }
-    const mcpRefs = [];
-    for (const [name, url] of Object.entries(mcpFlags.entries)) {
-      mcpRefs.push({ name, url });
-    }
-    runConfig = {
-      model: modelFlag.value,
-      ...resolvedSystem ? { system: resolvedSystem } : {},
-      prompt: resolvedPrompt,
-      ...mcpRefs.length > 0 ? { mcpServers: mcpRefs } : {},
-      ...Object.keys(metadataFlags.entries).length > 0 ? { metadata: { ...metadataFlags.entries } } : {}
-    };
+    configMcpServers = Object.entries(mcpFlags.entries).map(([name, url]) => ({ name, url }));
+    metadata = Object.keys(metadataFlags.entries).length > 0 ? { ...metadataFlags.entries } : void 0;
+  }
+  let provider;
+  try {
+    provider = resolveModelProvider(model, explicitProvider);
+  } catch (err2) {
+    io2.stderr(`--model: ${err2.message}
+`);
+    return USAGE_ERR;
   }
-  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)
+    const inferred = explicitProvider === void 0 && providersForModel(model).length > 0;
+    io2.stderr(`--${provider}-api-key is required for provider ${provider}${inferred ? ` (inferred from --model ${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);
   for (const [name, headerSpec] of mcpAuthFlags.entries) {
     const colon = headerSpec.indexOf(":");
     if (colon <= 0 || colon >= headerSpec.length - 1) {
@@ -3938,102 +5318,135 @@ async function runRunCmd(io2, argv) {
     existing[headerName] = headerValue;
     mcpHeaderBag.set(name, existing);
   }
-  for (const ref of mcpServersForSubmission) {
-    const headers = mcpHeaderBag.get(ref.name);
-    if (headers && Object.keys(headers).length > 0) {
-      mcpServerSecrets.push({ name: ref.name, url: ref.url, headers });
-    }
-  }
   for (const name of mcpHeaderBag.keys()) {
-    if (!mcpServersForSubmission.some((m) => m.name === name)) {
+    if (!configMcpServers.some((m) => m.name === name)) {
       io2.stderr(`--mcp-auth ${name}: no matching --mcp / mcpServers entry declared
 `);
       return USAGE_ERR;
     }
   }
-  const promptArray = Array.isArray(runConfig.prompt) ? [...runConfig.prompt] : [runConfig.prompt];
-  const submission = {
-    model: runConfig.model,
-    ...runConfig.system ? { system: runConfig.system } : {},
-    agentsMd: [],
-    files: [],
-    mcpServers: mcpServersForSubmission,
-    tools: [],
-    ...runConfig.environment ? { environment: runConfig.environment } : {},
-    ...runConfig.metadata ? { metadata: runConfig.metadata } : {}
-  };
-  const hasAdditionalProviderKeys = Object.keys(providerKeyValues).some((p) => p !== provider);
-  const secrets = {
-    apiKeys: hasAdditionalProviderKeys ? providerKeyValues : { [provider]: providerKeyValues[provider] },
-    ...mcpServerSecrets.length > 0 ? { mcpServers: mcpServerSecrets } : {}
-  };
-  const request = {
+  const mcpServers = configMcpServers.map((m) => {
+    const headers = mcpHeaderBag.get(m.name);
+    return {
+      name: m.name,
+      url: m.url,
+      ...headers && Object.keys(headers).length > 0 ? { headers } : {}
+    };
+  });
+  let skills;
+  let tools;
+  let agentsMd;
+  let files;
+  try {
+    skills = await Promise.all(skillFlags.values.map((ref) => buildSkill(io2, ref)));
+    tools = await Promise.all(toolFlags.values.map((ref) => buildTool(io2, ref)));
+    agentsMd = await Promise.all(agentsMdFlags.values.map((ref) => buildAgentsMd(io2, ref)));
+    files = await Promise.all(fileFlags.values.map((ref) => buildFile(io2, ref)));
+  } catch (err2) {
+    io2.stderr(`failed to attach asset: ${err2.message}
+`);
+    return USAGE_ERR;
+  }
+  const environment = toCliSessionEnvironment(configEnvironment);
+  const runtimeSize = runtimeSizeFlag.value ?? configRuntimeSize;
+  const timeout = runTimeoutFlag.value ?? configTimeout;
+  const options = {
+    message: promptArray,
     provider,
-    submission,
-    secrets,
-    retention: { idleTtl: DEFAULT_SESSION_IDLE_TTL },
-    ...runtimeSizeFlag.value ? { runtimeSize: runtimeSizeFlag.value } : runConfig.runtimeSize ? { runtimeSize: runConfig.runtimeSize } : {},
-    ...runTimeoutFlag.value ? { timeout: runTimeoutFlag.value } : runConfig.timeout ? { timeout: runConfig.timeout } : {},
-    ...webhookFlag.value ? { webhook: { url: webhookFlag.value } } : {}
+    model,
+    ...system ? { system } : {},
+    ...skills.length > 0 ? { skills } : {},
+    ...tools.length > 0 ? { tools } : {},
+    ...agentsMd.length > 0 ? { agentsMd } : {},
+    ...files.length > 0 ? { files } : {},
+    ...mcpServers.length > 0 ? { mcpServers } : {},
+    ...metadata ? { metadata } : {},
+    apiKeys: providerKeyValues,
+    ...environment ? { environment } : {},
+    ...runtimeSize ? { runtime: runtimeSize } : {},
+    overrides: {
+      idleTtl: DEFAULT_SESSION_IDLE_TTL,
+      ...timeout ? { timeout } : {}
+    },
+    ...webhookFlag.value ? { webhook: { url: webhookFlag.value } } : {},
+    ...idempotency.value ? { idempotencyKey: idempotency.value } : {}
   };
-  const createKey = idempotency.value ?? generateIdempotencyKey();
-  const messageKey = `${createKey}:message`;
   const http = makeHttpClient(io2, common.flags);
+  if (follow.present && !io2.webSocketFactory) {
+    io2.stderr(JSON.stringify({
+      error: "websocket_unavailable",
+      message: "`aex run --follow` needs a global WebSocket (Bun or Node >= 22). Upgrade Node or run with bun."
+    }) + "\n");
+    return USAGE_ERR;
+  }
   let session;
   try {
-    session = await operations_exports.createSession(http, request, { idempotencyKey: createKey });
+    session = await submitCliRun(http, io2.fetchImpl, options);
   } catch (err2) {
     const d = describeApiError(err2);
-    return emitJsonError(io2, "create_failed", d.message, {
+    return emitJsonError(io2, "run_failed", d.message, {
       ...d.status !== void 0 ? { status: d.status } : {},
       ...d.remedy ? { remedy: d.remedy } : {}
     });
   }
-  let accepted;
+  io2.stdout(JSON.stringify(session) + "\n");
+  if (!follow.present)
+    return SUCCESS;
+  const controller = new AbortController();
+  let timedOut = false;
+  let interrupted = false;
+  io2.onSignal?.("SIGINT", () => {
+    interrupted = true;
+    controller.abort();
+  });
+  const timer = followTimeoutMs === null ? null : setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, followTimeoutMs);
+  let lastSeq = -1;
   try {
-    accepted = await operations_exports.sendSessionMessage(http, session.id, { input: promptArray }, { idempotencyKey: messageKey });
-  } catch (err2) {
-    const d = describeApiError(err2);
-    return emitJsonError(io2, "send_failed", d.message, {
-      sessionId: session.id,
-      ...d.status !== void 0 ? { status: d.status } : {},
-      ...d.remedy ? { remedy: d.remedy } : {}
+    const stream = openEnvelopeStream(io2, http, session.id, {
+      signal: controller.signal,
+      ...common.flags.debug ? { debug: (line) => io2.stderr(`[aex] ${line}
+`) } : {}
     });
-  }
-  io2.stdout(JSON.stringify(accepted.session) + "\n");
-  if (!follow.present)
-    return SUCCESS;
-  const seen = /* @__PURE__ */ new Set();
-  let currentStatus = accepted.session.status;
-  const deadline = followTimeoutMs === null ? Number.POSITIVE_INFINITY : Date.now() + followTimeoutMs;
-  while (!isSessionParked2(currentStatus)) {
-    await sleep2(2e3);
-    try {
-      const events = await operations_exports.listSessionEvents(http, session.id);
-      for (const event of events) {
-        if (!seen.has(event.id)) {
-          seen.add(event.id);
-          io2.stdout(JSON.stringify(event) + "\n");
-        }
-      }
-    } catch (err2) {
-      io2.stderr(`(transient) event poll failed: ${err2.message}
-`);
-    }
-    try {
-      const updated = await operations_exports.getSession(http, session.id);
-      currentStatus = updated.status;
-    } catch (err2) {
-      io2.stderr(`(transient) status poll failed: ${err2.message}
-`);
+    for await (const event of stream) {
+      lastSeq = event.sequence;
+      io2.stdout(JSON.stringify(event) + "\n");
     }
-    if (!isSessionParked2(currentStatus) && Date.now() >= deadline) {
+  } catch (err2) {
+    if (timer)
+      clearTimeout(timer);
+    if (timedOut) {
       emitJsonError(io2, "run_follow_timeout", `timed out after ${followTimeoutMs}ms following session`, {
         sessionId: session.id,
+        lastSeq,
         hint: `aex status ${session.id} | aex events ${session.id} | aex download ${session.id}`
       });
       return TIMEOUT_ERR;
     }
+    if (interrupted) {
+      io2.stderr(`(interrupted) followed up to seq ${lastSeq}
+`);
+      return SUCCESS;
+    }
+    io2.stderr(`(transient) event stream failed: ${err2.message}
+`);
+  }
+  if (timer)
+    clearTimeout(timer);
+  if (timedOut) {
+    emitJsonError(io2, "run_follow_timeout", `timed out after ${followTimeoutMs}ms following session`, {
+      sessionId: session.id,
+      lastSeq,
+      hint: `aex status ${session.id} | aex events ${session.id} | aex download ${session.id}`
+    });
+    return TIMEOUT_ERR;
+  }
+  if (interrupted) {
+    io2.stderr(`(interrupted) followed up to seq ${lastSeq}
+`);
+    return SUCCESS;
   }
   try {
     const final = await operations_exports.getSession(http, session.id);
@@ -4053,6 +5466,50 @@ async function runRunCmd(io2, argv) {
     return RUNTIME_ERR;
   }
 }
+async function buildSkill(io2, ref) {
+  const content = await readAtFile(io2, ref);
+  return buildCliSkill(content, ref);
+}
+async function buildTool(io2, ref) {
+  const content = await readAtFile(io2, ref);
+  const entry = baseName(stripAt(ref));
+  const name = deriveName(ref, 1);
+  return buildCliTool({
+    name,
+    description: `Custom tool ${name}`,
+    entry,
+    content
+  });
+}
+async function buildAgentsMd(io2, ref) {
+  const content = await readAtFile(io2, ref);
+  return buildCliAgentsMd(content, deriveName(ref, 2));
+}
+async function buildFile(io2, ref) {
+  const content = await readAtFile(io2, ref);
+  const name = baseName(stripAt(ref));
+  return buildCliFile({ name, content });
+}
+async function readAtFile(io2, value) {
+  const path = resolvePath(io2.cwd(), stripAt(value));
+  return io2.readFile(path);
+}
+function stripAt(value) {
+  return value.startsWith("@") ? value.slice(1) : value;
+}
+function baseName(p) {
+  const trimmed = p.replace(/[\\/]+$/, "");
+  const i2 = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+  return i2 >= 0 ? trimmed.slice(i2 + 1) : trimmed;
+}
+function deriveName(ref, minLen) {
+  const base = baseName(stripAt(ref));
+  const noExt = base.includes(".") ? base.slice(0, base.lastIndexOf(".")) : base;
+  let slug = noExt.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  while (slug.length < minLen)
+    slug += "x";
+  return slug;
+}
 function stripMcpHeadersForParsing(input) {
   const mcpHeaders = /* @__PURE__ */ new Map();
   if (input === null || typeof input !== "object" || Array.isArray(input)) {
@@ -4094,15 +5551,6 @@ async function readMaybeFile(io2, value) {
   }
   return value;
 }
-function generateIdempotencyKey() {
-  const c = globalThis.crypto;
-  if (c?.randomUUID)
-    return c.randomUUID();
-  return `idem-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
-}
-function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // dist/host/status.js
 async function runStatusCmd(io2, argv) {
@@ -4220,7 +5668,7 @@ async function runWaitCmd(io2, argv) {
 `);
       if (Date.now() >= deadline)
         return timeout({});
-      await sleep3(intervalMs);
+      await sleep2(intervalMs);
       continue;
     }
     if (isSessionParked2(session.status)) {
@@ -4229,10 +5677,10 @@ async function runWaitCmd(io2, argv) {
     }
     if (Date.now() >= deadline)
       return timeout({ lastStatus: session.status });
-    await sleep3(intervalMs);
+    await sleep2(intervalMs);
   }
 }
-function sleep3(ms) {
+function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
@@ -4292,7 +5740,7 @@ async function runEventsCmd(io2, argv) {
 `);
       if (Date.now() >= deadline)
         return emitTimeout(io2, sessionId, timeoutMs);
-      await sleep4(2e3);
+      await sleep3(2e3);
       continue;
     }
     for (const event of events) {
@@ -4312,18 +5760,19 @@ async function runEventsCmd(io2, argv) {
     }
     if (Date.now() >= deadline)
       return emitTimeout(io2, sessionId, timeoutMs);
-    await sleep4(2e3);
+    await sleep3(2e3);
   }
 }
 function emitTimeout(io2, sessionId, timeoutMs) {
   emitJsonError(io2, "events_follow_timeout", `timed out after ${timeoutMs}ms following session events`, { sessionId });
   return TIMEOUT_ERR;
 }
-function sleep4(ms) {
+function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 // dist/host/outputs.js
+import { resolve as resolvePath2 } from "node:path";
 async function runOutputsCmd(io2, argv) {
   if (await refuseInsideManagedRun(io2, "outputs"))
     return USAGE_ERR;
@@ -4333,31 +5782,241 @@ async function runOutputsCmd(io2, argv) {
 `);
     return USAGE_ERR;
   }
-  const positional = common.rest.filter((arg) => !arg.startsWith("--"));
+  const args = common.rest;
+  const sub = args[0];
+  const http = makeHttpClient(io2, common.flags);
+  switch (sub) {
+    case "read":
+      return outputsRead(io2, http, args.slice(1));
+    case "download":
+      return outputsDownload(io2, http, args.slice(1), common.flags);
+    case "link":
+      return outputsLink(io2, http, args.slice(1));
+    case "find":
+      return outputsFind(io2, http, args.slice(1));
+    case "search":
+      return outputsSearch(io2, http, args.slice(1));
+    default:
+      return outputsList(io2, http, args);
+  }
+}
+async function outputsList(io2, http, args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
   if (positional.length !== 1) {
     io2.stderr("usage: aex outputs <session-id> [common flags]\n");
     return USAGE_ERR;
   }
   const sessionId = positional[0];
-  const http = makeHttpClient(io2, common.flags);
   try {
     const outputs = await operations_exports.listSessionOutputs(http, sessionId);
-    for (const out of outputs) {
+    for (const out of outputs)
       io2.stdout(JSON.stringify(out) + "\n");
-    }
     return SUCCESS;
   } catch (err2) {
-    const d = describeApiError(err2);
-    return emitJsonError(io2, "outputs_failed", d.message, {
-      sessionId,
-      ...d.status !== void 0 ? { status: d.status } : {},
-      ...d.remedy ? { remedy: d.remedy } : {}
-    });
+    return outputsError(io2, "outputs_failed", err2, { sessionId });
+  }
+}
+async function outputsRead(io2, http, args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  if (positional.length !== 2) {
+    io2.stderr("usage: aex outputs read <session-id> <path> [common flags]\n");
+    return USAGE_ERR;
+  }
+  const [sessionId, selector] = positional;
+  try {
+    const text = await operations_exports.readOutputText(http, sessionId, { path: selector });
+    io2.stdout(JSON.stringify(text) + "\n");
+    return SUCCESS;
+  } catch (err2) {
+    return outputsError(io2, "outputs_read_failed", err2, { sessionId, path: selector });
+  }
+}
+async function outputsDownload(io2, http, args, flags) {
+  const outFlag = takeFlagValue(args, "--out");
+  if (outFlag.error) {
+    io2.stderr(`${outFlag.error}
+`);
+    return USAGE_ERR;
+  }
+  void flags;
+  const positional = outFlag.remaining.filter((a) => !a.startsWith("--"));
+  if (positional.length !== 2) {
+    io2.stderr("usage: aex outputs download <session-id> <path> [--out file] [common flags]\n");
+    return USAGE_ERR;
+  }
+  const [sessionId, selector] = positional;
+  let bytes;
+  try {
+    bytes = (await operations_exports.downloadOutput(http, sessionId, { path: selector })).bytes;
+  } catch (err2) {
+    return outputsError(io2, "outputs_download_failed", err2, { sessionId, path: selector });
+  }
+  const destination = resolvePath2(io2.cwd(), outFlag.value ?? baseName2(selector));
+  try {
+    await io2.writeFile(destination, bytes);
+  } catch (err2) {
+    return emitJsonError(io2, "write_failed", `failed to write file: ${err2.message}`, { destination });
+  }
+  io2.stdout(JSON.stringify({ sessionId, path: selector, out: destination, bytes: bytes.byteLength }) + "\n");
+  return SUCCESS;
+}
+async function outputsLink(io2, http, args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  if (positional.length !== 2) {
+    io2.stderr("usage: aex outputs link <session-id> <path> [common flags]\n");
+    return USAGE_ERR;
+  }
+  const [sessionId, selector] = positional;
+  try {
+    const link = await operations_exports.outputLink(http, sessionId, { path: selector });
+    io2.stdout(JSON.stringify(link) + "\n");
+    return SUCCESS;
+  } catch (err2) {
+    return outputsError(io2, "outputs_link_failed", err2, { sessionId, path: selector });
+  }
+}
+async function outputsFind(io2, http, args) {
+  const name = takeFlagValue(args, "--name");
+  const ext = takeFlagValue(name.remaining, "--ext");
+  const type = takeFlagValue(ext.remaining, "--type");
+  const contentType = takeFlagValue(type.remaining, "--content-type");
+  const err2 = name.error ?? ext.error ?? type.error ?? contentType.error;
+  if (err2) {
+    io2.stderr(`${err2}
+`);
+    return USAGE_ERR;
+  }
+  const positional = contentType.remaining.filter((a) => !a.startsWith("--"));
+  if (positional.length !== 1) {
+    io2.stderr("usage: aex outputs find <session-id> [--name S] [--ext E] [--type T] [--content-type CT] [common flags]\n");
+    return USAGE_ERR;
+  }
+  const sessionId = positional[0];
+  const query = {
+    ...name.value !== null ? { filename: name.value } : {},
+    ...ext.value !== null ? { extension: ext.value } : {},
+    ...type.value !== null ? { type: type.value } : {},
+    ...contentType.value !== null ? { contentType: contentType.value } : {}
+  };
+  try {
+    const hits = await searchSessionOutputs(http, sessionId, query);
+    for (const hit of hits)
+      io2.stdout(JSON.stringify(hit) + "\n");
+    return SUCCESS;
+  } catch (err22) {
+    return outputsError(io2, "outputs_find_failed", err22, { sessionId });
+  }
+}
+async function outputsSearch(io2, http, args) {
+  const query = takeFlagValue(args, "--query");
+  const name = takeFlagValue(query.remaining, "--name");
+  const ext = takeFlagValue(name.remaining, "--ext");
+  const contentType = takeFlagValue(ext.remaining, "--content-type");
+  const limit = takeFlagValue(contentType.remaining, "--limit");
+  const runIds = collectRepeated(limit.remaining, "--run-id");
+  const err2 = query.error ?? name.error ?? ext.error ?? contentType.error ?? limit.error ?? runIds.error;
+  if (err2) {
+    io2.stderr(`${err2}
+`);
+    return USAGE_ERR;
+  }
+  const filename = query.value ?? name.value;
+  let limitValue;
+  if (limit.value !== null) {
+    const n = Number(limit.value);
+    if (!Number.isInteger(n) || n < 1) {
+      io2.stderr(`--limit must be a positive integer (got: ${limit.value})
+`);
+      return USAGE_ERR;
+    }
+    limitValue = n;
+  }
+  const search = {
+    ...filename !== null ? { filename } : {},
+    ...ext.value !== null ? { extension: ext.value } : {},
+    ...contentType.value !== null ? { contentType: contentType.value } : {},
+    ...runIds.values.length > 0 ? { runIds: [...runIds.values] } : {},
+    ...limitValue !== void 0 ? { limit: limitValue } : {}
+  };
+  try {
+    const page = await searchWorkspaceOutputs(http, search);
+    io2.stdout(JSON.stringify(page) + "\n");
+    return SUCCESS;
+  } catch (err22) {
+    return outputsError(io2, "outputs_search_failed", err22, {});
+  }
+}
+function outputsError(io2, code, err2, extra) {
+  const d = describeApiError(err2);
+  return emitJsonError(io2, code, d.message, {
+    ...extra,
+    ...d.status !== void 0 ? { status: d.status } : {},
+    ...d.remedy ? { remedy: d.remedy } : {}
+  });
+}
+async function searchWorkspaceOutputs(http, query) {
+  assertMetadataOnlyOutputSearch(query, "aex outputs search");
+  const runIds = query.runIds && query.runIds.length > 0 ? [...query.runIds] : void 0;
+  const limit = query.limit ?? 100;
+  const hits = [];
+  const candidates = runIds ?? await listRecentRunIds(http, limit);
+  for (const runId of candidates) {
+    const outputs = await searchSessionOutputs(http, runId, query);
+    for (const output of outputs) {
+      hits.push(outputHit(runId, output));
+      if (hits.length >= limit)
+        return { hits };
+    }
   }
+  return { hits };
+}
+async function listRecentRunIds(http, limit) {
+  const out = [];
+  let cursor;
+  while (out.length < limit) {
+    const page = await operations_exports.listSessions(http, { limit: Math.min(100, limit - out.length), ...cursor ? { cursor } : {} });
+    out.push(...page.sessions.map((session) => session.id));
+    if (!page.nextCursor)
+      break;
+    cursor = page.nextCursor;
+  }
+  return out;
+}
+async function searchSessionOutputs(http, sessionId, query) {
+  const listQuery = {
+    ...query.extension !== void 0 ? { extension: query.extension } : {},
+    ...query.contentType !== void 0 ? { contentType: query.contentType } : {}
+  };
+  const outputs = await operations_exports.listSessionOutputs(http, sessionId, Object.keys(listQuery).length > 0 ? listQuery : void 0);
+  if (query.filename === void 0)
+    return outputs;
+  const match = operations_exports.toFilenameMatcher(query.filename);
+  return outputs.filter((output) => typeof output.filename === "string" && match(output.filename));
+}
+function outputHit(runId, output) {
+  return {
+    runId,
+    outputId: output.id,
+    ...output.filename !== void 0 ? { filename: output.filename } : {},
+    ...output.sizeBytes !== void 0 ? { sizeBytes: output.sizeBytes } : {},
+    ...output.contentType !== void 0 ? { contentType: output.contentType } : {}
+  };
+}
+function assertMetadataOnlyOutputSearch(query, surface) {
+  for (const key of ["content", "text", "query", "grep", "body"]) {
+    if (Object.prototype.hasOwnProperty.call(query, key)) {
+      throw new Error(`${surface}: ${key} is not supported; output search is metadata-only`);
+    }
+  }
+}
+function baseName2(p) {
+  const trimmed = p.replace(/[\\/]+$/, "");
+  const i2 = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+  return i2 >= 0 ? trimmed.slice(i2 + 1) : trimmed;
 }
 
 // dist/host/download.js
-import { resolve as resolvePath2 } from "node:path";
+import { resolve as resolvePath3 } from "node:path";
 var NAMESPACE_DOWNLOADERS = {
   outputs: operations_exports.downloadOutputs,
   events: operations_exports.downloadEvents,
@@ -4420,10 +6079,10 @@ async function runDownloadCmd(io2, argv) {
 }
 function resolveDestination(io2, out, sessionId, namespace2) {
   if (out) {
-    return resolvePath2(io2.cwd(), out);
+    return resolvePath3(io2.cwd(), out);
   }
   const suffix = namespace2 ? `-${namespace2}` : "";
-  return resolvePath2(io2.cwd(), `aex-session-${sessionId}${suffix}.zip`);
+  return resolvePath3(io2.cwd(), `aex-session-${sessionId}${suffix}.zip`);
 }
 
 // dist/host/cancel.js
@@ -4584,9 +6243,9 @@ async function runBillingCmd(io2, argv) {
   if (common.rest[0] === "portal") {
     return runBillingPortal(io2, common.rest.slice(1), common.flags);
   }
-  const { present: json, remaining } = takeBooleanFlag(common.rest, "--json");
-  if (remaining.length > 0) {
-    io2.stderr(`unexpected arguments: ${remaining.join(" ")}
+  const json = common.flags.json;
+  if (common.rest.length > 0) {
+    io2.stderr(`unexpected arguments: ${common.rest.join(" ")}
 `);
     io2.stderr("usage: aex billing [--json] | aex billing ledger [--limit N] | aex billing upgrade pro|team | aex billing portal [common flags]\n");
     return USAGE_ERR;
@@ -4616,8 +6275,8 @@ async function runBillingCmd(io2, argv) {
   }
 }
 async function runBillingUpgrade(io2, argv, flags) {
-  const { present: json, remaining: rest1 } = takeBooleanFlag(argv, "--json");
-  const { value: successUrl, remaining: rest2 } = takeOptionFlag(rest1, "--success-url");
+  const json = flags.json;
+  const { value: successUrl, remaining: rest2 } = takeOptionFlag(argv, "--success-url");
   const { value: cancelUrl, remaining: rest3 } = takeOptionFlag(rest2, "--cancel-url");
   const { value: idempotencyKey, remaining } = takeOptionFlag(rest3, "--idempotency-key");
   const planKey = remaining[0];
@@ -4646,8 +6305,8 @@ async function runBillingUpgrade(io2, argv, flags) {
   }
 }
 async function runBillingPortal(io2, argv, flags) {
-  const { present: json, remaining: rest1 } = takeBooleanFlag(argv, "--json");
-  const { value: returnUrl, remaining } = takeOptionFlag(rest1, "--return-url");
+  const json = flags.json;
+  const { value: returnUrl, remaining } = takeOptionFlag(argv, "--return-url");
   if (remaining.length > 0) {
     io2.stderr(`unexpected arguments: ${remaining.join(" ")}
 `);
@@ -4827,7 +6486,7 @@ async function runSessionsCmd(io2, argv) {
 }
 
 // dist/host/debug.js
-import { dirname, resolve as resolvePath3 } from "node:path";
+import { dirname, resolve as resolvePath4 } from "node:path";
 function status(source, state, opts = {}) {
   return {
     source,
@@ -5145,7 +6804,7 @@ function toMs(iso) {
 async function writeDebugBundle(io2, baseDir, bundle) {
   const encoder3 = new TextEncoder();
   for (const file2 of bundle.files) {
-    const abs = resolvePath3(baseDir, file2.path);
+    const abs = resolvePath4(baseDir, file2.path);
     if (io2.mkdirp)
       await io2.mkdirp(dirname(abs));
     await io2.writeFile(abs, encoder3.encode(file2.content));
@@ -5417,7 +7076,7 @@ ${USAGE}`);
     }
     sinceMs = d.ms;
   }
-  const outDir = resolvePath3(io2.cwd(), outF.value ?? `aex-debug-${runId}`);
+  const outDir = resolvePath4(io2.cwd(), outF.value ?? `aex-debug-${runId}`);
   const client = makeAwsSources(region);
   let targets;
   try {
@@ -5490,7 +7149,7 @@ async function runLoginCmd(io2, argv) {
     return USAGE_ERR;
   }
   const resolvedUrl = aexUrl ?? AEX_DEFAULT_BASE_URL;
-  const http = makeHttpClient(io2, { apiKey, aexUrl: resolvedUrl, debug: debug2 });
+  const http = makeHttpClient(io2, { apiKey, aexUrl: resolvedUrl, debug: debug2, json: false });
   let workspaceId;
   try {
     const me = await operations_exports.whoami(http);
@@ -5652,110 +7311,6 @@ function hasUnknown(io2, rest, verb) {
   return false;
 }
 
-// dist/host/stream-render.js
-async function* openEnvelopeStream(io2, http, sessionId, options = {}) {
-  const first = await operations_exports.getSessionCoordinatorTicket(http, sessionId);
-  if (options.debug) {
-    let host = "(invalid)";
-    try {
-      host = new URL(first.wsUrl).host;
-    } catch {
-    }
-    options.debug(`ticket minted: host=${host} expiresInMs=${first.expiresAtMs - Date.now()} from=${options.from ?? 0}`);
-  }
-  yield* streamCoordinatorEvents({
-    wsUrl: first.wsUrl,
-    from: options.from ?? 0,
-    fetchTicket: async () => (await operations_exports.getSessionCoordinatorTicket(http, sessionId)).ticket,
-    ...io2.webSocketFactory ? { webSocketFactory: io2.webSocketFactory } : {},
-    ...options.settleConsistent ? { isTerminal: isRunSettled } : {},
-    ...options.signal ? { signal: options.signal } : {}
-  });
-}
-var PREVIEW_MAX = 120;
-function clip(text, max = PREVIEW_MAX) {
-  const oneLine = text.replace(/\s+/g, " ").trim();
-  return oneLine.length > max ? oneLine.slice(0, max - 1) + "\u2026" : oneLine;
-}
-function str2(v) {
-  return typeof v === "string" ? v : v === void 0 || v === null ? "" : JSON.stringify(v);
-}
-function argsPreview(e) {
-  const d = e.data;
-  const candidate = d.input ?? d.args ?? d.arguments ?? d.params;
-  if (candidate === void 0)
-    return "";
-  return clip(typeof candidate === "string" ? candidate : JSON.stringify(candidate));
-}
-function renderEnvelope(e, options = {}) {
-  if (channelOf(e) === "log" && !options.logs)
-    return null;
-  switch (e.type) {
-    case "RUN_STARTED":
-      return "\u25B6 run started";
-    case "TEXT_MESSAGE_CONTENT": {
-      const delta = toAGUI(e).type === "TEXT_MESSAGE_CONTENT" ? toAGUI(e).delta : "";
-      return delta ? delta : null;
-    }
-    case "TOOL_CALL_START": {
-      const agui = toAGUI(e);
-      const name = agui.type === "TOOL_CALL_START" ? agui.toolCallName : str2(e.data.name);
-      const preview = argsPreview(e);
-      return `\xB7 tool ${name || "(unnamed)"}(${preview})`;
-    }
-    case "TOOL_CALL_RESULT": {
-      const name = str2(e.data.name) || "result";
-      const content = e.data.content;
-      const ok = content === void 0 || content === null ? "ok" : clip(str2(content));
-      return `  \u2190 ${name} ${ok}`;
-    }
-    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": {
-      const level = e.level ?? "info";
-      return `[${level}] ${e.message ?? str2(e.data.message)}`;
-    }
-    case "RUN_FINISHED":
-      return "\u2713 run finished";
-    case "RUN_ERROR": {
-      const agui = toAGUI(e);
-      const message = agui.type === "RUN_ERROR" ? agui.message : e.message ?? "run error";
-      return `\u2717 run error: ${message}`;
-    }
-    default:
-      return null;
-  }
-}
-function parseFilters(tokens) {
-  const flattened = tokens.flatMap((t) => t.split(",")).map((s) => s.trim()).filter(Boolean);
-  if (flattened.length === 0)
-    return {};
-  const types = /* @__PURE__ */ new Set();
-  const sources = /* @__PURE__ */ new Set();
-  for (const tok of flattened) {
-    if (AEX_EVENT_TYPES.includes(tok)) {
-      types.add(tok);
-    } else if (AEX_EVENT_SOURCES.includes(tok)) {
-      sources.add(tok);
-    } else {
-      const hint = suggest(tok, [...AEX_EVENT_TYPES, ...AEX_EVENT_SOURCES]);
-      return {
-        error: `unknown --filter token "${tok}"${hint ? `; did you mean "${hint}"?` : ""} (types: ${AEX_EVENT_TYPES.join(",")}; sources: ${AEX_EVENT_SOURCES.join(",")})`
-      };
-    }
-  }
-  const predicate = (e) => (types.size === 0 || types.has(e.type)) && (sources.size === 0 || sources.has(e.source));
-  return { predicate };
-}
-
 // dist/host/tail.js
 async function runTailCmd(io2, argv) {
   if (await refuseInsideManagedRun(io2, "tail"))
@@ -5766,8 +7321,8 @@ async function runTailCmd(io2, argv) {
 `);
     return USAGE_ERR;
   }
-  const jsonFlag = takeBooleanFlag(common.rest, "--json");
-  const logsFlag = takeBooleanFlag(jsonFlag.remaining, "--logs");
+  const json = common.flags.json;
+  const logsFlag = takeBooleanFlag(common.rest, "--logs");
   const settleFlag = takeBooleanFlag(logsFlag.remaining, "--settle");
   const filterFlag = collectRepeated(settleFlag.remaining, "--filter");
   if (filterFlag.error) {
@@ -5847,7 +7402,7 @@ async function runTailCmd(io2, argv) {
       if (filters.predicate && !filters.predicate(e)) {
         continue;
       }
-      if (jsonFlag.present) {
+      if (json) {
         if (logsFlag.present || e.channel !== "log") {
           io2.stdout(JSON.stringify(e) + "\n");
           eventCount++;
@@ -5920,8 +7475,8 @@ async function runInspectCmd(io2, argv) {
 `);
     return USAGE_ERR;
   }
-  const jsonFlag = takeBooleanFlag(common.rest, "--json");
-  const logsFlag = takeBooleanFlag(jsonFlag.remaining, "--logs");
+  const json = common.flags.json;
+  const logsFlag = takeBooleanFlag(common.rest, "--logs");
   const filterFlag = collectRepeated(logsFlag.remaining, "--filter");
   if (filterFlag.error) {
     io2.stderr(`${filterFlag.error}
@@ -5973,7 +7528,7 @@ async function runInspectCmd(io2, argv) {
       ...d.remedy ? { remedy: d.remedy } : {}
     });
   }
-  if (!jsonFlag.present) {
+  if (!json) {
     const model = typeof header.model === "string" ? ` \xB7 ${header.model}` : "";
     const created = header.createdAt ? ` \xB7 ${header.createdAt}` : "";
     io2.stdout(`session ${sessionId} \xB7 ${header.status}${model}${created}
@@ -5999,7 +7554,7 @@ async function runInspectCmd(io2, argv) {
         runErrorEvent = e;
       if (filters.predicate && !filters.predicate(e))
         continue;
-      if (jsonFlag.present) {
+      if (json) {
         if (logsFlag.present || e.channel !== "log")
           collected.push(e);
         continue;
@@ -6029,7 +7584,7 @@ async function runInspectCmd(io2, argv) {
     finalSession = await operations_exports.getSession(http, sessionId);
   } catch {
   }
-  if (jsonFlag.present) {
+  if (json) {
     io2.stdout(JSON.stringify({ session: finalSession, events: collected }) + "\n");
   } else {
     if (runErrorEvent) {
@@ -6080,6 +7635,11 @@ async function dispatch(io2, args) {
   }
   const sub = args[0];
   const rest = args.slice(1);
+  const spec = sub === void 0 ? void 0 : findVerbSpec(sub);
+  if (spec && wantsVerbHelp(rest) && !(sub === "outputs" && rest[0] === "sync")) {
+    io2.stdout(renderVerbHelp(spec));
+    return SUCCESS;
+  }
   switch (sub) {
     case "run":
       return runRunCmd(io2, rest);
@@ -6142,7 +7702,7 @@ 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("aex \u2014 unified CLI for the aex platform (a thin pass-through over the SDK)\n\n");
   io2.stdout("Usage:\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");
@@ -6214,7 +7774,7 @@ async function walkDirectory(root) {
   async function visit(dir) {
     const entries = await readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const full = resolvePath4(dir, entry.name);
+      const full = resolvePath5(dir, entry.name);
       if (entry.isDirectory()) {
         await visit(full);
       } else if (entry.isFile()) {