@openwop/cli 1.1.0 → 1.2.1

package/dist/openwop.js

@@ -566,6 +566,12 @@ function httpErrorHint(err, env) {
   }
   return void 0;
 }
+function isNoCredentialChallenge(err) {
+  if (!(err instanceof HttpError) || err.status !== 401) return false;
+  const challenge = err.headers?.get?.("www-authenticate");
+  if (!challenge || !/^\s*Bearer\b/i.test(challenge)) return false;
+  return !/\berror\s*=/i.test(challenge);
+}
 function errText(err) {
   return err instanceof Error ? err.message : String(err);
 }
@@ -573,7 +579,7 @@ function errText(err) {
 // package.json
 var package_default = {
   name: "@openwop/cli",
-  version: "1.1.0",
+  version: "1.2.1",
   description: "OpenWOP CLI for operating the workflow-engine demo app and OpenWOP-compatible hosts.",
   license: "Apache-2.0",
   type: "module",
@@ -704,6 +710,7 @@ function prefixChunk(stream, label, chunk) {
 function extractGlobalOptions(argv, env = process.env) {
   const globals = {
     baseUrl: void 0,
+    streamBaseUrl: void 0,
     apiKey: void 0,
     profile: void 0,
     json: false,
@@ -721,6 +728,10 @@ function extractGlobalOptions(argv, env = process.env) {
       globals.baseUrl = value ?? takeValue(argv, ++i, "--base-url");
       continue;
     }
+    if (flag === "--stream-base-url") {
+      globals.streamBaseUrl = value ?? takeValue(argv, ++i, "--stream-base-url");
+      continue;
+    }
     if (flag === "--api-key") {
       globals.apiKey = value ?? takeValue(argv, ++i, "--api-key");
       continue;
@@ -1199,6 +1210,7 @@ async function negotiateMajor(ctx) {
     const doc = JSON.parse(await res.text());
     if (res.ok) {
       ctx.discovery = { doc, servedVersion: res.headers?.get?.("openwop-version") ?? void 0 };
+      ctx.discoveredStreamBase = streamBaseFrom(doc?.extensions, ctx.baseUrl);
       major = selectMajor(doc?.protocolVersions);
       if (major === 2) roots = hostRootsFrom(doc?.extensions);
     } else if (res.status === 406) {
@@ -1219,6 +1231,67 @@ async function resolveRequest(ctx, path, headers) {
   if (rooted !== null) return { path: rooted, headers };
   return { path, headers };
 }
+function isLoopback(url) {
+  return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+}
+function explicitStreamBase(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return void 0;
+  let url;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new CliError(`--stream-base-url / OPENWOP_STREAM_BASE_URL is not a URL: ${raw}`);
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw new CliError("--stream-base-url / OPENWOP_STREAM_BASE_URL must not carry credentials (user:pass@); pass them with --api-key.");
+  }
+  return raw.trim().replace(/\/+$/, "");
+}
+function streamBaseFrom(extensions, baseUrl) {
+  if (!extensions || typeof extensions !== "object" || Array.isArray(extensions)) return void 0;
+  let base16;
+  try {
+    base16 = new URL(baseUrl);
+  } catch {
+    return void 0;
+  }
+  for (const value of Object.values(extensions)) {
+    const raw = value && typeof value === "object" ? value.streamBase : void 0;
+    if (typeof raw !== "string") continue;
+    let url;
+    try {
+      url = new URL(raw);
+    } catch {
+      continue;
+    }
+    if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") continue;
+    const secure = url.protocol === "https:" && (base16.protocol === "https:" || isLoopback(base16));
+    const localDev = url.protocol === "http:" && isLoopback(url) && isLoopback(base16);
+    if (!secure && !localDev) continue;
+    return raw.replace(/\/+$/, "");
+  }
+  return void 0;
+}
+async function resolveStreamRequest(ctx, requestedPath, headers) {
+  const resolved = await resolveRequest(ctx, requestedPath, { accept: "text/event-stream", ...headers });
+  const { origin, source } = streamOrigin(ctx);
+  if (ctx.verbose && source !== "base") ctx.io.stderr.write(`openwop: reading the event stream from ${origin} (${STREAM_SOURCE_LABEL[source]})
+`);
+  const url = new URL(resolved.path.replace(/^\//, ""), origin.endsWith("/") ? origin : `${origin}/`);
+  const out = { ...resolved.headers };
+  if (ctx.apiKey) out.authorization = `Bearer ${ctx.apiKey}`;
+  return { url, headers: out };
+}
+var STREAM_SOURCE_LABEL = {
+  setting: "your --stream-base-url / OPENWOP_STREAM_BASE_URL / config setting",
+  advertised: "the host's advertised streamBase",
+  base: "--base-url"
+};
+function streamOrigin(ctx) {
+  if (ctx.streamBaseUrl) return { origin: ctx.streamBaseUrl, source: "setting" };
+  if (ctx.discoveredStreamBase) return { origin: ctx.discoveredStreamBase, source: "advertised" };
+  return { origin: ctx.baseUrl, source: "base" };
+}
 
 // src/wire.ts
 import { randomUUID } from "node:crypto";
@@ -1412,6 +1485,10 @@ async function streamRunEvents(ctx, runId, opts = {}) {
     } catch (err) {
       if (err instanceof HttpError && err.status >= 400 && err.status < 500 && (opts.streamMode || opts.lastEventId !== void 0 || opts.afterSequence !== void 0)) throw err;
       if (err instanceof SseResumeExhausted) throw err.reason instanceof HttpError ? err.reason : err;
+      if (err instanceof StreamSilent && err.beforeHeaders && !ctx.quiet) {
+        ctx.io.stderr.write(`openwop: the event stream sent nothing for ${err.ms >= 1e3 ? `${Math.round(err.ms / 1e3)} s` : `${err.ms} ms`} \u2014 the host's front door may be buffering streams. Following by polling instead; for live events pass --stream-base-url <a direct origin> (see \`openwop doctor\`).
+`);
+      }
     }
   }
   if (opts.streamMode && opts.streamMode !== "updates" && !ctx.quiet) {
@@ -1457,12 +1534,14 @@ async function streamViaSse(ctx, runId, deliver, opts) {
   for (; ; ) {
     let progressed = false;
     let dropError;
+    let idle;
     try {
-      const { path, headers } = await resolveRequest(ctx, `/v1/runs/${encodeURIComponent(runId)}/events${query}`, { accept: "text/event-stream" });
-      const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
-      if (ctx.apiKey) headers.authorization = `Bearer ${ctx.apiKey}`;
+      const { url, headers } = await resolveStreamRequest(ctx, `/v1/runs/${encodeURIComponent(runId)}/events${query}`, {});
       if (lastEventId !== void 0 && lastEventId !== "") headers["last-event-id"] = lastEventId;
-      const res = await ctx.fetchImpl(url, { method: "GET", headers });
+      const idleMs = opts.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+      idle = idleWatchdog(idleMs, opts.headersTimeoutMs ?? (idleMs > 0 ? Math.min(idleMs, DEFAULT_HEADERS_TIMEOUT_MS) : 0));
+      const res = await ctx.fetchImpl(url, { method: "GET", headers, signal: idle.signal });
+      idle.headersArrived();
       if (!res.ok) {
         const text = await res.text().catch(() => "");
         let body = null;
@@ -1479,7 +1558,7 @@ async function streamViaSse(ctx, runId, deliver, opts) {
         throw new HttpError("resumed events stream is not text/event-stream", res.status, null, res.headers);
       }
       opened = true;
-      await consumeSse(res.body, (frame) => {
+      await consumeSse(idle.watch(res.body), (frame) => {
         if (frame.retry !== void 0) retryMs = frame.retry;
         if (frame.id !== void 0) lastEventId = frame.id;
         if (frame.data === void 0) return;
@@ -1498,18 +1577,23 @@ async function streamViaSse(ctx, runId, deliver, opts) {
       if (!opened) throw err;
       if (err instanceof HttpError && err.status !== 429 && err.status < 500) throw new SseResumeExhausted(err.message, err);
       dropError = err;
+    } finally {
+      idle?.stop();
     }
     if (terminal) return true;
     if (lastEventId === void 0 && deliver.highest() >= 0) lastEventId = String(deliver.highest());
     if (await runIsTerminal(ctx, runId)) return true;
     failures = progressed ? 1 : failures + 1;
     if (failures > maxReconnects) {
-      throw new SseResumeExhausted(`events stream for ${runId} dropped ${failures} times without progress${dropError instanceof Error ? `: ${dropError.message}` : ""}`, dropError);
+      throw new SseResumeExhausted(`events stream for ${runId} dropped ${failures} times without progress${dropError instanceof Error ? `: ${dropError.message}` : ""}. Re-run with --since <last sequence printed> to continue, or --no-stream to follow by polling.`, dropError);
     }
     const delayMs = Math.min(retryMs * 2 ** (failures - 1), 3e4);
     opts.onReconnect?.({ attempt: failures, lastEventId, delayMs });
-    if (ctx.verbose) ctx.io.stderr.write(`openwop: events stream dropped; reconnecting in ${delayMs}ms with Last-Event-ID ${lastEventId ?? "(none)"}
+    if (ctx.verbose) {
+      const why = dropError instanceof StreamSilent ? `stalled (${dropError.message})` : "dropped";
+      ctx.io.stderr.write(`openwop: events stream ${why}; reconnecting in ${delayMs}ms with Last-Event-ID ${lastEventId ?? "(none)"}
 `);
+    }
     await sleep(delayMs);
   }
 }
@@ -1707,6 +1791,74 @@ function defaultReadTurn(ctx) {
     rl.once("close", onClose);
   });
 }
+var DEFAULT_IDLE_TIMEOUT_MS = 45e3;
+var DEFAULT_HEADERS_TIMEOUT_MS = 1e4;
+var StreamSilent = class extends Error {
+  constructor(ms2, beforeHeaders) {
+    super(beforeHeaders ? `no response headers within ${ms2}ms` : `no bytes for ${ms2}ms`);
+    this.ms = ms2;
+    this.beforeHeaders = beforeHeaders;
+    this.name = "StreamSilent";
+  }
+};
+function idleWatchdog(ms2, headersMs = ms2) {
+  const controller = new AbortController();
+  let timer;
+  let onExpire;
+  let beforeHeaders = true;
+  const expire = (after) => {
+    controller.abort(new StreamSilent(after, beforeHeaders));
+    onExpire?.();
+  };
+  const arm = (after = ms2) => {
+    if (!(after > 0)) return;
+    if (timer !== void 0) clearTimeout(timer);
+    timer = setTimeout(() => expire(after), after);
+  };
+  arm(headersMs);
+  return {
+    signal: controller.signal,
+    /** The response headers arrived: from here on only the idle timeout applies. */
+    headersArrived() {
+      beforeHeaders = false;
+      arm();
+    },
+    watch(body) {
+      if (!(ms2 > 0) || typeof body?.getReader !== "function") return body;
+      const source = body.getReader();
+      return new ReadableStream({
+        start(out) {
+          onExpire = () => {
+            out.error(new StreamSilent(ms2, false));
+            source.cancel().catch(() => {
+            });
+          };
+        },
+        async pull(out) {
+          try {
+            const { value, done: done2 } = await source.read();
+            if (done2) {
+              out.close();
+              return;
+            }
+            arm();
+            out.enqueue(value);
+          } catch (err) {
+            out.error(err);
+          }
+        },
+        cancel(reason) {
+          return source.cancel(reason);
+        }
+      });
+    },
+    stop() {
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      onExpire = void 0;
+    }
+  };
+}
 
 // src/cli/chatShared.ts
 var enc = (value) => encodeURIComponent(value);
@@ -1731,9 +1883,7 @@ function writeFields(ctx, fields) {
   }
 }
 async function streamHostSse(ctx, requestedPath, opts) {
-  const { path, headers } = await resolveRequest(ctx, requestedPath, { accept: "text/event-stream" });
-  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
-  if (ctx.apiKey) headers.authorization = `Bearer ${ctx.apiKey}`;
+  const { url, headers } = await resolveStreamRequest(ctx, requestedPath, {});
   const controller = new AbortController();
   let timer;
   if (opts.timeoutMs && opts.timeoutMs > 0) timer = setTimeout(() => controller.abort(), opts.timeoutMs);
@@ -1790,6 +1940,82 @@ function renderFrame(frame) {
 
 // src/cli/routeKit.ts
 import { readFileSync as readFileSync4 } from "node:fs";
+
+// src/cli/shared.ts
+function requireOrg(org2) {
+  if (!org2) throw new CliError("This command is org-scoped \u2014 pass --org <orgId>.", 2);
+  return String(org2);
+}
+function buildInputs(options) {
+  const fromJson = options.inputsJson ? JSON.parse(options.inputsJson) : {};
+  if (fromJson === null || typeof fromJson !== "object" || Array.isArray(fromJson)) {
+    throw new CliError("--inputs-json must be a JSON object");
+  }
+  const inputs = { ...fromJson };
+  for (const pair of options.input ?? []) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) throw new CliError(`--input must be key=value, got: ${pair}`);
+    inputs[pair.slice(0, eq)] = parseInputValue(pair.slice(eq + 1));
+  }
+  return inputs;
+}
+function parseInputValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseNodeVersion(version) {
+  const [major, minor, patch] = version.split(".").map((v) => Number(v));
+  return { major: major || 0, minor: minor || 0, patch: patch || 0 };
+}
+function defaultApiKeyFor(baseUrl) {
+  try {
+    const host = new URL(baseUrl).hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1") return DEFAULT_API_KEY;
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function normalizeBaseUrl(value) {
+  if (!value) return DEFAULT_BASE_URL;
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function npmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function ok(name, message) {
+  return { status: "ok", name, message };
+}
+function warn(name, message) {
+  return { status: "warn", name, message };
+}
+function fail(name, message) {
+  return { status: "fail", name, message };
+}
+function formatCheckTable(checks) {
+  return formatTable(
+    checks.map((c) => ({ status: c.status.toUpperCase(), check: c.name, message: c.message })),
+    ["status", "check", "message"]
+  );
+}
+
+// src/cli/routeKit.ts
+var errText2 = (err) => err instanceof Error ? err.message : String(err);
+var DEFAULT_MESSAGES = {
+  required: (flag, usage6) => `${usage6}
+${flag} is required.`,
+  refusal: (words, positionals) => `Refusing to ${words.join(" ")} ${positionals.join(" ")} without --yes.`.replace(/\s+/g, " ").trim(),
+  invalidNumber: (flag, raw) => `${flag} must be a number (got "${raw}").`,
+  invalidBool: (flag, raw) => `${flag} must be true or false (got "${raw}").`,
+  invalidJson: (flag) => `${flag} must be valid JSON.`,
+  unreadable: (flag, path, err) => `Could not read ${path} for ${flag}: ${errText2(err)}`,
+  unreadableBody: (path, err) => `Could not read ${path}: ${errText2(err)}`,
+  invalidBodyJson: "--body / --body-file must be a JSON object.",
+  bodyNotObject: "--body / --body-file must be a JSON object."
+};
 var COMMON_BOOL = ["--help", "--yes"];
 function templates(cmd) {
   return Array.isArray(cmd.path) ? cmd.path : [cmd.path];
@@ -1797,18 +2023,31 @@ function templates(cmd) {
 function paramNames(path) {
   return [...path.matchAll(/:([A-Za-z][A-Za-z0-9_]*)/g)].map((m) => m[1]);
 }
+function positionalNames(cmd, path) {
+  return paramNames(path).filter((p) => !(cmd.orgFlag && p === "org"));
+}
+function bindsOrg(cmd) {
+  return Boolean(cmd.orgFlag) && templates(cmd).some((p) => paramNames(p).includes("org"));
+}
+function fillPath(cmd, template, positionals, org2) {
+  let i = 0;
+  return template.replace(/:([A-Za-z][A-Za-z0-9_]*)/g, (_m, name) => {
+    if (cmd.orgFlag && name === "org") return encodeURIComponent(requireOrg(org2));
+    return encodeURIComponent(positionals[i++] ?? "");
+  });
+}
 function flagHint(f) {
   const t = f.type ?? "string";
-  const v = t === "boolean" ? "" : t === "file" || t === "file64" || t === "json-file" ? " <path>" : t === "map" ? " <key=value>..." : t === "list" ? ` <${f.key}>...` : t === "json" ? ` <json>` : ` <${f.key.split(".").pop()}>`;
+  const v = t === "boolean" ? "" : t === "bool" ? " <true|false>" : t === "file" || t === "file64" || t === "json-file" ? " <path>" : t === "map" ? " <key=value>..." : t === "list" ? ` <${f.key}>...` : t === "json" ? ` <json>` : ` <${f.key.split(".").pop()}>`;
   return f.required ? `${f.flag}${v}` : `[${f.flag}${v}]`;
 }
 function usageLine(group, cmd) {
   const paths = templates(cmd);
-  const longest = paths.reduce((a, b) => paramNames(b).length > paramNames(a).length ? b : a);
-  const shortest = paths.reduce((a, b) => paramNames(b).length < paramNames(a).length ? b : a);
-  const req2 = paramNames(shortest);
-  const params = paramNames(longest).map((p, i) => i < req2.length ? `<${p}>` : `[<${p}>]`);
-  const flags = [...cmd.query ?? [], ...cmd.body ?? []].map(flagHint);
+  const longest = paths.reduce((a, b) => positionalNames(cmd, b).length > positionalNames(cmd, a).length ? b : a);
+  const shortest = paths.reduce((a, b) => positionalNames(cmd, b).length < positionalNames(cmd, a).length ? b : a);
+  const req2 = positionalNames(cmd, shortest);
+  const params = positionalNames(cmd, longest).map((p, i) => i < req2.length ? `<${p}>` : `[<${p}>]`);
+  const flags = [...bindsOrg(cmd) ? ["--org <orgId>"] : [], ...[...cmd.query ?? [], ...cmd.body ?? []].map(flagHint)];
   if (cmd.body?.some((f) => f.type === "json")) flags.push("[--body <json>|--body-file <path>]");
   if (cmd.confirm ?? cmd.method === "DELETE") flags.push("--yes");
   if (cmd.method === "GET") flags.push("[--json]");
@@ -1844,9 +2083,15 @@ function setPath(target, key, value) {
   }
   node[parts[parts.length - 1]] = value;
 }
-function coerce(f, raw) {
+function coerce(f, raw, cmd, msg) {
   const t = f.type ?? "string";
   if (t === "boolean") return raw;
+  if (t === "bool") {
+    const s2 = String(raw);
+    if (s2 === "true" || s2 === "yes" || s2 === "1") return true;
+    if (s2 === "false" || s2 === "no" || s2 === "0") return false;
+    throw new CliError(msg.invalidBool(f.flag, s2), 2);
+  }
   if (t === "list") return Array.isArray(raw) ? raw.map(String) : [String(raw)];
   if (t === "map") {
     const out = {};
@@ -1862,7 +2107,7 @@ function coerce(f, raw) {
   const s = String(raw);
   if (t === "number") {
     const n = Number(s);
-    if (!Number.isFinite(n)) throw new CliError(`${f.flag} must be a number (got "${s}").`, 2);
+    if (!Number.isFinite(n) || cmd.strictNumbers && s.trim() === "") throw new CliError(msg.invalidNumber(f.flag, s), 2);
     return n;
   }
   if (t === "json-file") {
@@ -1870,7 +2115,7 @@ function coerce(f, raw) {
     try {
       text = readFileSync4(s, "utf8");
     } catch (err) {
-      throw new CliError(`Could not read ${s} for ${f.flag}: ${err instanceof Error ? err.message : String(err)}`, 2);
+      throw new CliError(msg.unreadable(f.flag, s, err), 2);
     }
     try {
       return JSON.parse(text);
@@ -1882,14 +2127,14 @@ function coerce(f, raw) {
     try {
       return readFileSync4(s).toString("base64");
     } catch (err) {
-      throw new CliError(`Could not read ${s} for ${f.flag}: ${err instanceof Error ? err.message : String(err)}`, 2);
+      throw new CliError(msg.unreadable(f.flag, s, err), 2);
     }
   }
   if (t === "file") {
     try {
       return readFileSync4(s, "utf8").replace(/\r?\n$/, "");
     } catch (err) {
-      throw new CliError(`Could not read ${s} for ${f.flag}: ${err instanceof Error ? err.message : String(err)}`, 2);
+      throw new CliError(msg.unreadable(f.flag, s, err), 2);
     }
   }
   if (t === "csv") return s.split(",").map((x) => x.trim()).filter(Boolean);
@@ -1897,18 +2142,19 @@ function coerce(f, raw) {
     try {
       return JSON.parse(s);
     } catch {
-      throw new CliError(`${f.flag} must be valid JSON.`, 2);
+      throw new CliError(msg.invalidJson(f.flag, s), 2);
     }
   }
   return s;
 }
-function readBodyOptions(options) {
+function readBodyOptions(options, msg) {
   let raw;
   if (options.bodyFile !== void 0) {
+    if (String(options.bodyFile).trim() === "") throw new CliError("--body-file needs a path (got an empty value).", 2);
     try {
       raw = readFileSync4(String(options.bodyFile), "utf8");
     } catch (err) {
-      throw new CliError(`Could not read ${String(options.bodyFile)}: ${err instanceof Error ? err.message : String(err)}`, 2);
+      throw new CliError(msg.unreadableBody(String(options.bodyFile), err), 2);
     }
   } else if (options.body !== void 0) {
     raw = String(options.body);
@@ -1918,9 +2164,9 @@ function readBodyOptions(options) {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    throw new CliError("--body / --body-file must be a JSON object.", 2);
+    throw new CliError(msg.invalidBodyJson, 2);
   }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError("--body / --body-file must be a JSON object.", 2);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError(msg.bodyNotObject, 2);
   return parsed;
 }
 function hostError(err) {
@@ -1931,30 +2177,34 @@ function hostError(err) {
   ${hint}` : line, code2);
 }
 async function runRoute(ctx, group, cmd, argv) {
+  const msg = { ...DEFAULT_MESSAGES, ...cmd.messages ?? {} };
   const rest = argv.slice(cmd.words.length);
   const fields = [...cmd.query ?? [], ...cmd.body ?? []];
   const bool = [...COMMON_BOOL, ...fields.filter((f) => f.type === "boolean").flatMap((f) => [f.flag, f.flag.replace(/^--/, "--no-")])];
   const isMulti = (f) => f.type === "list" || f.type === "map";
-  const value = ["--body", "--body-file", ...fields.filter((f) => f.type !== "boolean" && !isMulti(f)).map((f) => f.flag)];
+  const value = [
+    ...cmd.bodyFlags !== false ? ["--body", "--body-file"] : [],
+    ...bindsOrg(cmd) ? ["--org"] : [],
+    ...fields.filter((f) => f.type !== "boolean" && !isMulti(f)).map((f) => f.flag)
+  ];
   const multi = fields.filter(isMulti).map((f) => f.flag);
   const { options, positionals } = parseOptions(rest, { bool, value, multi });
   if (options.help) {
-    writeLine(ctx.io.stdout, `Usage: ${usageLine(group, cmd)}
+    if (cmd.usageText !== void 0) write(ctx.io.stdout, cmd.usageText);
+    else writeLine(ctx.io.stdout, `Usage: ${usageLine(group, cmd)}
 
 ${cmd.summary}
 Endpoint: ${cmd.method} ${templates(cmd).join(" | ")}`);
     return 0;
   }
-  const template = templates(cmd).find((p) => paramNames(p).length === positionals.length);
+  const template = templates(cmd).find((p) => positionalNames(cmd, p).length === positionals.length);
   if (!template) {
-    write(ctx.io.stderr, `Usage: ${usageLine(group, cmd)}
+    write(ctx.io.stderr, cmd.usageText ?? `Usage: ${usageLine(group, cmd)}
 `);
     return 2;
   }
-  let path = template;
-  paramNames(template).forEach((name, i) => {
-    path = path.replace(`:${name}`, encodeURIComponent(positionals[i]));
-  });
+  const path = fillPath(cmd, template, positionals, options.org);
+  const requiredError = (f) => new CliError(msg.required(f.flag, cmd.usageText ?? usageLine(group, cmd)), 2);
   const optionOf = (f) => {
     const name = f.flag.replace(/^--/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
     if (f.type === "boolean") {
@@ -1969,34 +2219,39 @@ Endpoint: ${cmd.method} ${templates(cmd).join(" | ")}`);
   for (const f of cmd.query ?? []) {
     const v = optionOf(f);
     if (v === void 0) {
-      if (f.required) throw new CliError(`${usageLine(group, cmd)}
-${f.flag} is required.`, 2);
+      if (f.required) throw requiredError(f);
       continue;
     }
-    const c = coerce(f, v);
-    if (Array.isArray(c)) c.forEach((x) => qs2.append(f.key, String(x)));
-    else qs2.set(f.key, String(c));
+    const c = coerce(f, v, cmd, msg);
+    if (f.type === "csv") qs2.set(f.key, c.join(","));
+    else if (Array.isArray(c)) c.forEach((x) => qs2.append(f.key, String(x)));
+    else qs2.set(f.key, c !== null && typeof c === "object" ? JSON.stringify(c) : String(c));
   }
   const url = qs2.size ? `${path}${path.includes("?") ? "&" : "?"}${qs2.toString()}` : path;
   const confirm2 = cmd.confirm ?? cmd.method === "DELETE";
-  if (confirm2 && !options.yes) throw new CliError(`Refusing to ${cmd.words.join(" ")} ${positionals.join(" ")} without --yes.`.replace(/\s+/g, " ").trim(), 2);
-  let body;
+  const gate = () => {
+    if (confirm2 && !options.yes) throw new CliError(msg.refusal(cmd.words, positionals), 2);
+  };
+  if (!cmd.validateFirst) gate();
   const isWrite = cmd.method !== "GET" && cmd.method !== "DELETE";
-  if (isWrite || cmd.body?.length) {
-    const explicit = readBodyOptions(options);
-    const overlay = {};
+  const takesBody = isWrite || Boolean(cmd.body?.length) || cmd.bodyFlags === true;
+  let explicit = {};
+  const overlay = {};
+  if (takesBody) {
+    explicit = readBodyOptions(options, msg);
     for (const f of cmd.body ?? []) {
       const v = optionOf(f);
-      if (v === void 0) continue;
-      setPath(overlay, f.key, coerce(f, v));
+      if (v !== void 0) setPath(overlay, f.key, coerce(f, v, cmd, msg));
+      else if (cmd.validateFirst && f.required && getPath(explicit, f.key) === void 0) throw requiredError(f);
     }
+  }
+  if (cmd.validateFirst) gate();
+  let body;
+  if (takesBody) {
     let base16 = {};
     if (cmd.rmw) {
-      let from = cmd.rmw.from ?? template;
-      paramNames(from).forEach((name, i) => {
-        from = from.replace(`:${name}`, encodeURIComponent(positionals[i]));
-      });
-      const current = await send(ctx, from, { method: "GET" }, cmd.anonymous);
+      const from = fillPath(cmd, cmd.rmw.from ?? template, positionals, options.org);
+      const current = await send(ctx, cmd, from, { method: "GET" });
       const picked = cmd.rmw.pick ? cmd.rmw.pick(current.body) : current.body;
       base16 = picked && typeof picked === "object" && !Array.isArray(picked) ? { ...picked } : {};
     }
@@ -2005,13 +2260,15 @@ ${f.flag} is required.`, 2);
       const v = getPath(overlay, f.key);
       if (v !== void 0) setPath(body, f.key, v);
     }
-    for (const f of cmd.body ?? []) {
-      if (f.required && getPath(body, f.key) === void 0) throw new CliError(`${usageLine(group, cmd)}
-${f.flag} is required.`, 2);
+    if (!cmd.validateFirst) {
+      for (const f of cmd.body ?? []) {
+        if (f.required && getPath(body, f.key) === void 0) throw requiredError(f);
+      }
     }
     if (!isWrite && Object.keys(body).length === 0) body = void 0;
     if (isWrite && body && Object.keys(body).length === 0 && cmd.emptyBody === false) body = void 0;
   }
+  if (cmd.notice !== void 0) writeLine(ctx.io.stderr, cmd.notice);
   try {
     const res = await requestJson(ctx, url, { method: cmd.method, ...body !== void 0 ? { body } : {}, ...cmd.anonymous ? { auth: false } : {} });
     render(ctx, cmd, positionals, res.status, res.body);
@@ -2021,25 +2278,42 @@ ${f.flag} is required.`, 2);
       render(ctx, { ...cmd, method: "GET" }, positionals, err.status, err.body);
       return 1;
     }
-    if (err instanceof HttpError) throw hostError(err);
+    if (err instanceof HttpError && cmd.hostErrors !== false) throw hostError(err);
     throw err;
   }
 }
 function getPath(obj, key) {
   return key.split(".").reduce((node, part) => node && typeof node === "object" ? node[part] : void 0, obj);
 }
-async function send(ctx, url, init, anonymous) {
+async function send(ctx, cmd, url, init) {
   try {
-    return await requestJson(ctx, url, { method: init.method, ...init.body !== void 0 ? { body: init.body } : {}, ...anonymous ? { auth: false } : {} });
+    return await requestJson(ctx, url, { method: init.method, ...init.body !== void 0 ? { body: init.body } : {}, ...cmd.anonymous ? { auth: false } : {} });
   } catch (err) {
-    if (err instanceof HttpError) throw hostError(err);
+    if (err instanceof HttpError && cmd.hostErrors !== false) throw hostError(err);
     throw err;
   }
 }
+function tableRows(table3, body) {
+  if (!table3.anyArray) return table3.key ? getPath(body ?? {}, table3.key) : body;
+  if (Array.isArray(body)) return body;
+  const keyed = table3.key ? getPath(body ?? {}, table3.key) : void 0;
+  if (Array.isArray(keyed)) return keyed;
+  return Object.values(body ?? {}).find((v) => Array.isArray(v)) ?? [];
+}
 function render(ctx, cmd, positionals, status, rawBody) {
   const body = cmd.transform ? cmd.transform(rawBody) : rawBody;
+  const noContent = body === null || body === void 0 ? cmd.noContent : void 0;
   if (ctx.json) {
-    writeJson(ctx.io.stdout, body);
+    writeJson(ctx.io.stdout, noContent !== void 0 ? { ok: true, status } : body);
+    return;
+  }
+  if (cmd.rawText && body && typeof body === "object" && typeof body.raw === "string" && Object.keys(body).length === 1) {
+    write(ctx.io.stdout, body.raw.endsWith("\n") ? body.raw : `${body.raw}
+`);
+    return;
+  }
+  if (noContent !== void 0) {
+    writeLine(ctx.io.stdout, noContent.replace("{status}", String(status)));
     return;
   }
   if (cmd.human) {
@@ -2047,7 +2321,7 @@ function render(ctx, cmd, positionals, status, rawBody) {
     return;
   }
   if (cmd.table) {
-    const rows = cmd.table.key ? getPath(body ?? {}, cmd.table.key) : body;
+    const rows = tableRows(cmd.table, body);
     if (rows === null || rows === void 0) {
       writeLine(ctx.io.stdout, cmd.table.empty ?? "None.");
       return;
@@ -2065,7 +2339,7 @@ function render(ctx, cmd, positionals, status, rawBody) {
       return;
     }
   }
-  if (cmd.method === "GET") {
+  if (cmd.method === "GET" || cmd.writeOutput === "json") {
     writeJson(ctx.io.stdout, body);
     return;
   }
@@ -2404,7 +2678,8 @@ async function runInterrupts(ctx, argv) {
       if (b.key) writeLine(ctx.io.stdout, `key: ${b.key}`);
       writeLine(ctx.io.stdout, `resolved: ${b.resolved ? "yes" : "no"}`);
       if (b.expiresAt) writeLine(ctx.io.stdout, `expiresAt: ${b.expiresAt}`);
-      if (b.data && typeof b.data === "object" && typeof b.data.prompt === "string") writeLine(ctx.io.stdout, `prompt: ${b.data.prompt}`);
+      const prompt = b.data && typeof b.data === "object" ? b.data.prompt : void 0;
+      if (typeof prompt === "string") writeLine(ctx.io.stdout, `prompt: ${prompt}`);
       if (b.resumeSchema !== void 0) writeLine(ctx.io.stdout, `resumeSchema: ${JSON.stringify(b.resumeSchema)}`);
       return 0;
     }
@@ -2460,67 +2735,6 @@ function lifecycleError(err) {
   throw err;
 }
 
-// src/cli/shared.ts
-function requireOrg(org2) {
-  if (!org2) throw new CliError("This command is org-scoped \u2014 pass --org <orgId>.", 2);
-  return String(org2);
-}
-function buildInputs(options) {
-  const fromJson = options.inputsJson ? JSON.parse(options.inputsJson) : {};
-  if (fromJson === null || typeof fromJson !== "object" || Array.isArray(fromJson)) {
-    throw new CliError("--inputs-json must be a JSON object");
-  }
-  const inputs = { ...fromJson };
-  for (const pair of options.input ?? []) {
-    const eq = pair.indexOf("=");
-    if (eq <= 0) throw new CliError(`--input must be key=value, got: ${pair}`);
-    inputs[pair.slice(0, eq)] = parseInputValue(pair.slice(eq + 1));
-  }
-  return inputs;
-}
-function parseInputValue(value) {
-  try {
-    return JSON.parse(value);
-  } catch {
-    return value;
-  }
-}
-function parseNodeVersion(version) {
-  const [major, minor, patch] = version.split(".").map((v) => Number(v));
-  return { major: major || 0, minor: minor || 0, patch: patch || 0 };
-}
-function defaultApiKeyFor(baseUrl) {
-  try {
-    const host = new URL(baseUrl).hostname;
-    if (host === "localhost" || host === "127.0.0.1" || host === "::1") return DEFAULT_API_KEY;
-  } catch {
-    return void 0;
-  }
-  return void 0;
-}
-function normalizeBaseUrl(value) {
-  if (!value) return DEFAULT_BASE_URL;
-  return value.endsWith("/") ? value.slice(0, -1) : value;
-}
-function npmCommand() {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
-}
-function ok(name, message) {
-  return { status: "ok", name, message };
-}
-function warn(name, message) {
-  return { status: "warn", name, message };
-}
-function fail(name, message) {
-  return { status: "fail", name, message };
-}
-function formatCheckTable(checks) {
-  return formatTable(
-    checks.map((c) => ({ status: c.status.toUpperCase(), check: c.name, message: c.message })),
-    ["status", "check", "message"]
-  );
-}
-
 // src/cli/contentHelpers.ts
 import { readFileSync as readFileSync5 } from "node:fs";
 import { resolve as resolvePath2 } from "node:path";
@@ -2873,19 +3087,37 @@ import { readFileSync as readFileSync6 } from "node:fs";
 
 // src/cli/requestHelpers.ts
 var NOT_SERVED = /* @__PURE__ */ new Set([404, 405, 501]);
+function presentsCredential(ctx, req2) {
+  if (req2.auth !== false && ctx.apiKey) return true;
+  return Object.keys(req2.headers ?? {}).some((h) => /^(authorization|cookie)$/i.test(h));
+}
 async function requestNormativeOrHost(ctx, normativePath, hostPath, options = {}) {
   const { forceHost, ...req2 } = options;
+  let anonymousRetryOf;
   if (!forceHost) {
     try {
       const res2 = await requestJson(ctx, normativePath, req2);
       if (ctx.verbose) writeLine(ctx.io.stderr, `openwop: served by the normative path ${normativePath}`);
       return { ...res2, path: normativePath, via: "normative" };
     } catch (err) {
-      if (!(err instanceof HttpError) || !NOT_SERVED.has(err.status)) throw err;
+      if (!(err instanceof HttpError)) throw err;
+      if (isNoCredentialChallenge(err) && !presentsCredential(ctx, req2)) anonymousRetryOf = err;
+      else if (!NOT_SERVED.has(err.status)) throw err;
     }
   }
-  const res = await requestJson(ctx, hostPath, req2);
-  if (ctx.verbose) writeLine(ctx.io.stderr, `openwop: served by the host-extension path ${hostPath}`);
+  let res;
+  try {
+    res = await requestJson(ctx, hostPath, req2);
+  } catch (err) {
+    if (anonymousRetryOf && err instanceof HttpError && (NOT_SERVED.has(err.status) || err.status === 401)) throw anonymousRetryOf;
+    throw err;
+  }
+  if (anonymousRetryOf) {
+    const sent = (await resolveRequest(ctx, hostPath, {})).path;
+    writeLine(ctx.io.stderr, `openwop: no credential sent \u2014 showing this host's anonymous view (${sent}), not your workspace. Pass --api-key, or run \`openwop onboard\` to save one.`);
+  } else if (ctx.verbose) {
+    writeLine(ctx.io.stderr, `openwop: served by the host-extension path ${hostPath}`);
+  }
   return { ...res, path: hostPath, via: "host" };
 }
 function failClosedOn404(err, surface) {
@@ -4847,6 +5079,8 @@ GET /v1/agents and GET /v1/agents/{agentId}. When the host does not serve the
 normative read (404/405/501) they fall back to the host-extension alias
 GET /v1/host/openwop-app/agents[/{agentId}]; --host forces the alias (which also
 reports the host's runtime posture); --verbose names the path that answered.
+With no credential, a v2 host refuses the normative read (401); the command
+then shows the host's anonymous view from the alias and says so on stderr.
 'run' dispatches one agent turn via
 POST /v1/host/openwop-app/agents/{agentId}/dispatch \u2014 the tool surface is filtered to
 the agent's toolAllowlist (RFC 0002 \xA7A14), task/return payloads are validated
@@ -5170,6 +5404,8 @@ GET /v1/agents/roster. The normative view carries only protocol-shaped entries
 (the host may omit host-only entries such as advisors); when the host does not
 serve it (404/405/501), or with --host, 'list' reads the host-extension
 GET /v1/host/openwop-app/roster instead (--verbose names the path that answered).
+With no credential, a v2 host refuses the normative read (401); 'list' then
+shows the host's anonymous view from the alias and says so on stderr.
 'get'/'create'/'update'/'delete' drive the host-extension surface
 GET/POST/PATCH/DELETE /v1/host/openwop-app/roster[/{rosterId}].
 
@@ -5352,7 +5588,9 @@ field).
 GET /v1/agents/org-chart/{departmentId}. When the host does not serve it
 (404/405/501 on 'get'), or with --host, they read the host-extension
 GET /v1/host/openwop-app/org-chart[/{departmentId}] (--verbose names the path
-that answered). 'set'/'clear' drive the host-extension PUT/DELETE
+that answered). With no credential, a v2 host refuses the normative read (401);
+'get'/'dept' then show the host's anonymous view from the alias and say so on
+stderr. 'set'/'clear' drive the host-extension PUT/DELETE
 /v1/host/openwop-app/org-chart. 'set' replaces the whole chart from a JSON file
 with { "departments": [...], "members": [...] }.
 
@@ -5734,9 +5972,7 @@ async function boardWatch(ctx, argv) {
     write(ctx.io.stdout, "Usage: openwop kanban watch <boardId>\n");
     return options.help ? 0 : 2;
   }
-  const { path, headers } = await resolveRequest(ctx, `/v1/host/openwop-app/kanban/boards/${encodeURIComponent(positionals[0])}/events`, { accept: "text/event-stream" });
-  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
-  if (ctx.apiKey) headers.authorization = `Bearer ${ctx.apiKey}`;
+  const { url, headers } = await resolveStreamRequest(ctx, `/v1/host/openwop-app/kanban/boards/${encodeURIComponent(positionals[0])}/events`, {});
   const res = await ctx.fetchImpl(url, { headers });
   if (!res.ok || !res.body) {
     throw new CliError(`Could not open the board event stream (HTTP ${res.status}).`, 1);
@@ -6061,7 +6297,6 @@ async function brandAsset(ctx, argv) {
 }
 
 // src/cli/resourceCommands.ts
-import { readFileSync as readFileSync9 } from "node:fs";
 function parseField(spec) {
   let s = spec;
   let flagOverride;
@@ -6076,35 +6311,6 @@ function parseField(spec) {
   const flag = `--${flagOverride ?? key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`).replace(/_/g, "-")}`;
   return { key, flag, type, required };
 }
-function coerce2(field, raw) {
-  switch (field.type) {
-    case "number": {
-      const n = Number(raw);
-      if (raw.trim() === "" || !Number.isFinite(n)) throw new CliError(`${field.flag} must be a number, got: ${raw}`);
-      return n;
-    }
-    case "bool":
-      if (raw === "true" || raw === "yes" || raw === "1") return true;
-      if (raw === "false" || raw === "no" || raw === "0") return false;
-      throw new CliError(`${field.flag} must be true or false, got: ${raw}`);
-    case "json":
-      try {
-        return JSON.parse(raw);
-      } catch {
-        throw new CliError(`${field.flag} must be valid JSON`);
-      }
-    case "list":
-      return raw.split(",").map((v) => v.trim()).filter((v) => v.length > 0);
-    case "file":
-      try {
-        return readFileSync9(raw, "utf8").replace(/\r?\n$/, "");
-      } catch {
-        throw new CliError(`Cannot read ${field.flag} ${raw}`);
-      }
-    default:
-      return raw;
-  }
-}
 function hasOrg(route) {
   return /:org(?![A-Za-z0-9_])/.test(route);
 }
@@ -6147,142 +6353,62 @@ ${footer ? `
 ${footer.trim()}
 ` : ""}`;
 }
-function matchSpec(specs, argv) {
-  let best = null;
-  for (const spec of specs) {
-    if (spec.cmd.length > argv.length) continue;
-    if (spec.cmd.every((w, i) => argv[i] === w) && (!best || spec.cmd.length > best.spec.cmd.length)) {
-      best = { spec, rest: argv.slice(spec.cmd.length) };
-    }
-  }
-  return best;
-}
-function readBodyOption2(options) {
-  let raw;
-  if (options.bodyFile) {
-    try {
-      raw = readFileSync9(String(options.bodyFile), "utf8");
-    } catch {
-      throw new CliError(`Cannot read --body-file ${options.bodyFile}`);
-    }
-  } else if (options.body !== void 0) {
-    raw = String(options.body);
-  }
-  if (raw === void 0) return {};
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new CliError("--body/--body-file must be valid JSON");
-  }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError("--body/--body-file must be a JSON object");
-  return parsed;
+var TYPES = { string: "string", number: "number", bool: "bool", json: "json", list: "csv", file: "file" };
+function toField(spec) {
+  const f = parseField(spec);
+  return { flag: f.flag, key: f.key, type: TYPES[f.type] ?? "string", required: f.required };
 }
-async function runSpec(ctx, group, spec, argv) {
-  const queryFields = (spec.query ?? []).map(parseField);
-  const bodyFields = (spec.body ?? []).map(parseField);
-  const allowBody = Boolean(spec.body || spec.rawBody);
-  const valueFlags = [...queryFields, ...bodyFields].map((f) => f.flag);
-  if (hasOrg(spec.route)) valueFlags.push("--org");
-  if (allowBody) valueFlags.push("--body", "--body-file");
-  const { options, positionals } = parseOptions(argv, { bool: ["--help", "--yes"], value: valueFlags });
+function toRouteCmd(group, spec) {
   const usage6 = `Usage: ${usageLine2(group, spec)}
   ${spec.method} ${spec.route} \u2014 ${spec.summary}
 `;
-  if (options.help) {
-    write(ctx.io.stdout, usage6);
-    return 0;
-  }
-  const params = paramsOf(spec.route);
-  if (positionals.length !== params.length) {
-    write(ctx.io.stderr, usage6);
-    return 2;
-  }
-  const optionValue = (f) => options[f.flag.slice(2).replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())];
-  const fill = (route) => {
-    let i = 0;
-    return route.replace(/:[A-Za-z][A-Za-z0-9_]*/g, (m) => {
-      if (m === ":org") return encodeURIComponent(requireOrg(options.org));
-      return encodeURIComponent(positionals[i++] ?? "");
-    });
-  };
-  let path = fill(spec.route);
-  const qs2 = new URLSearchParams();
-  for (const f of queryFields) {
-    const v = optionValue(f);
-    if (v === void 0) {
-      if (f.required) throw new CliError(`${f.flag} is required.
-${usage6}`);
-      continue;
-    }
-    const c = coerce2(f, String(v));
-    qs2.set(f.key, Array.isArray(c) ? c.join(",") : typeof c === "object" ? JSON.stringify(c) : String(c));
-  }
-  const q = qs2.toString();
-  if (q) path += `${path.includes("?") ? "&" : "?"}${q}`;
-  let body;
-  if (allowBody || spec.method === "POST" || spec.method === "PUT" || spec.method === "PATCH") {
-    body = allowBody ? readBodyOption2(options) : {};
-    for (const f of bodyFields) {
-      const v = optionValue(f);
-      if (v !== void 0) body[f.key] = coerce2(f, String(v));
-      else if (f.required && body[f.key] === void 0) throw new CliError(`${f.flag} is required.
-${usage6}`);
-    }
-    if (spec.method === "DELETE" && Object.keys(body).length === 0) body = void 0;
-  }
-  if (spec.confirm && !options.yes) {
-    throw new CliError(`Refusing to ${spec.summary.charAt(0).toLowerCase()}${spec.summary.slice(1).replace(/\.$/, "")} without --yes.`, 2);
-  }
-  if (spec.rmw) {
-    const current = await requestJson(ctx, fill(spec.rmw), { auth: spec.auth });
-    const base16 = spec.rmwKey ? current.body?.[spec.rmwKey] : current.body;
-    body = { ...base16 && typeof base16 === "object" && !Array.isArray(base16) ? base16 : {}, ...body ?? {} };
-  }
-  if (spec.notice) writeLine(ctx.io.stderr, spec.notice);
-  const res = await requestJson(ctx, path, {
+  const rmwKey = spec.rmwKey;
+  return {
+    words: spec.cmd,
     method: spec.method,
-    ...body !== void 0 ? { body } : {},
-    ...spec.auth === false ? { auth: false } : {}
-  });
-  return render2(ctx, spec, res.status, res.body);
-}
-function render2(ctx, spec, status, body) {
-  if (ctx.json) {
-    writeJson(ctx.io.stdout, body ?? { ok: true, status });
-    return 0;
-  }
-  if (body && typeof body === "object" && typeof body.raw === "string" && Object.keys(body).length === 1) {
-    write(ctx.io.stdout, body.raw.endsWith("\n") ? body.raw : `${body.raw}
-`);
-    return 0;
-  }
-  if (body === null || body === void 0) {
-    writeLine(ctx.io.stdout, spec.method === "DELETE" ? "Deleted." : `Done (HTTP ${status}).`);
-    return 0;
-  }
-  if (spec.list) {
-    const items = Array.isArray(body) ? body : spec.list.key && Array.isArray(body?.[spec.list.key]) ? body[spec.list.key] : Object.values(body ?? {}).find((v) => Array.isArray(v)) ?? [];
-    if (items.length === 0) {
-      writeLine(ctx.io.stdout, spec.list.empty ?? "None.");
-      return 0;
+    path: spec.route,
+    summary: spec.summary,
+    query: (spec.query ?? []).map(toField),
+    body: (spec.body ?? []).map(toField),
+    orgFlag: true,
+    bodyFlags: Boolean(spec.body || spec.rawBody),
+    emptyBody: true,
+    confirm: Boolean(spec.confirm),
+    anonymous: spec.auth === false,
+    ...spec.list ? { table: { key: spec.list.key, columns: spec.list.columns, empty: spec.list.empty ?? "None.", anyArray: true } } : {},
+    ...spec.rmw ? { rmw: { from: spec.rmw, pick: (body) => rmwKey ? body?.[rmwKey] : body } } : {},
+    ...spec.notice !== void 0 ? { notice: spec.notice } : {},
+    rawText: true,
+    // every spec, as before — `text` only documents the route
+    noContent: spec.method === "DELETE" ? "Deleted." : "Done (HTTP {status}).",
+    writeOutput: "json",
+    hostErrors: false,
+    validateFirst: true,
+    strictNumbers: true,
+    usageText: usage6,
+    messages: {
+      required: (flag, usageText) => `${flag} is required.
+${usageText}`,
+      refusal: () => `Refusing to ${spec.summary.charAt(0).toLowerCase()}${spec.summary.slice(1).replace(/\.$/, "")} without --yes.`,
+      invalidNumber: (flag, raw) => `${flag} must be a number, got: ${raw}`,
+      invalidBool: (flag, raw) => `${flag} must be true or false, got: ${raw}`,
+      invalidJson: (flag) => `${flag} must be valid JSON`,
+      unreadable: (flag, path) => `Cannot read ${flag} ${path}`,
+      unreadableBody: (path) => `Cannot read --body-file ${path}`,
+      invalidBodyJson: "--body/--body-file must be valid JSON",
+      bodyNotObject: "--body/--body-file must be a JSON object"
     }
-    writeLine(ctx.io.stdout, formatTable(items.map((row2) => {
-      const out = {};
-      for (const col of spec.list.columns) {
-        const v = row2?.[col];
-        out[col] = v === void 0 || v === null ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
-      }
-      return out;
-    }), spec.list.columns));
-    return 0;
-  }
-  writeJson(ctx.io.stdout, body);
-  return 0;
+  };
+}
+function matchSpec(specs, argv) {
+  return matchRoute(specs.map((spec) => ({ words: spec.cmd, spec })), argv)?.spec;
+}
+async function runSpec(ctx, group, spec, argv) {
+  return runRoute(ctx, group, toRouteCmd(group, spec), [...spec.cmd, ...argv]);
 }
 async function dispatchSpecs(ctx, group, specs, argv) {
-  const match = matchSpec(specs, argv);
-  return match ? runSpec(ctx, group, match.spec, match.rest) : void 0;
+  const spec = matchSpec(specs, argv);
+  return spec ? runSpec(ctx, group, spec, argv.slice(spec.cmd.length)) : void 0;
 }
 function specsUsage(group, specs) {
   return specs.map((s) => `  ${usageLine2(group, s)}
@@ -6293,12 +6419,12 @@ async function runResourceGroup(ctx, group, help, specs, argv) {
     write(ctx.io.stdout, help);
     return 0;
   }
-  const match = matchSpec(specs, argv);
-  if (!match) {
+  const spec = matchSpec(specs, argv);
+  if (!spec) {
     throw new CliError(`Unknown ${group} command: ${argv.filter((a) => !a.startsWith("-")).slice(0, 2).join(" ")}
 Run \`openwop ${group} --help\` for usage.`);
   }
-  return runSpec(ctx, group, match.spec, match.rest);
+  return runSpec(ctx, group, spec, argv.slice(spec.cmd.length));
 }
 
 // src/cli/crmOrg.ts
@@ -6975,7 +7101,7 @@ async function sharingFrameViews(ctx, argv) {
 }
 
 // src/cli/marketingShared.ts
-import { readFileSync as readFileSync10 } from "node:fs";
+import { readFileSync as readFileSync9 } from "node:fs";
 import { resolve as resolvePath5 } from "node:path";
 var APP = "/v1/host/openwop-app";
 async function dispatchTable(ctx, group, help, table3, argv, defaultSub) {
@@ -7033,14 +7159,14 @@ function jsonObject(text, flag) {
 }
 function readText(ctx, path, flag) {
   try {
-    return readFileSync10(resolvePath5(ctx.cwd, path), "utf8");
+    return readFileSync9(resolvePath5(ctx.cwd, path), "utf8");
   } catch (err) {
     throw new CliError(`Cannot read ${flag} ${path}: ${err instanceof Error ? err.message : String(err)}`, 2);
   }
 }
 function readBase64(ctx, path, flag) {
   try {
-    return readFileSync10(resolvePath5(ctx.cwd, path)).toString("base64");
+    return readFileSync9(resolvePath5(ctx.cwd, path)).toString("base64");
   } catch (err) {
     throw new CliError(`Cannot read ${flag} ${path}: ${err instanceof Error ? err.message : String(err)}`, 2);
   }
@@ -8652,10 +8778,10 @@ Run \`openwop documents --help\` for usage.`);
       if (!id) return usage(ctx, "add-version <documentId> --org <orgId> (--content <text> | --content-file <path>)");
       let content = options.content !== void 0 ? String(options.content) : void 0;
       if (options.contentFile) {
-        const { readFileSync: readFileSync23 } = await import("node:fs");
+        const { readFileSync: readFileSync22 } = await import("node:fs");
         const { resolve: resolve5 } = await import("node:path");
         try {
-          content = readFileSync23(resolve5(ctx.cwd, String(options.contentFile)), "utf8");
+          content = readFileSync22(resolve5(ctx.cwd, String(options.contentFile)), "utf8");
         } catch (err) {
           throw new CliError(`Cannot read --content-file ${String(options.contentFile)}: ${err instanceof Error ? err.message : String(err)}`);
         }
@@ -9242,7 +9368,7 @@ Run \`openwop reviews --help\` for usage.`);
 }
 
 // src/cli/adminShared.ts
-import { readFileSync as readFileSync11 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 
 // src/prompt.ts
@@ -9361,7 +9487,7 @@ async function readSecretInput(ctx, options, label) {
   let value;
   if (options.valueFile !== void 0) {
     try {
-      value = readFileSync11(resolve2(ctx.cwd, String(options.valueFile)), "utf8").replace(/\r?\n$/, "");
+      value = readFileSync10(resolve2(ctx.cwd, String(options.valueFile)), "utf8").replace(/\r?\n$/, "");
     } catch (err) {
       throw new CliError(`Cannot read --value-file ${options.valueFile}: ${err instanceof Error ? err.message : String(err)}`, 2);
     }
@@ -10315,7 +10441,7 @@ async function runCampaignsOrch(ctx, argv) {
 }
 
 // src/cli/notebooks.ts
-import { readFileSync as readFileSync12 } from "node:fs";
+import { readFileSync as readFileSync11 } from "node:fs";
 import { extname as extname3, resolve as resolvePath7 } from "node:path";
 var BASE9 = "/v1/host/openwop-app/notebooks";
 var NOTEBOOKS_HELP = `Usage:
@@ -10390,7 +10516,7 @@ var MIME = {
 function readFileBase64(ctx, file, contentType) {
   let buf;
   try {
-    buf = readFileSync12(resolvePath7(ctx.cwd, file));
+    buf = readFileSync11(resolvePath7(ctx.cwd, file));
   } catch (err) {
     throw new CliError(`Cannot read file ${file}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -12319,6 +12445,13 @@ honouring the server's \`retry:\` field), and no event is printed twice.
                       debug, or a comma list of updates/messages/debug
                       (\`values\` never combines). A host that does not serve
                       the mode answers 400 unsupported_stream_mode.
+  --idle-timeout-ms N a connection that delivers no bytes for N ms (default
+                      45000; 0 disables) is treated as dropped and resumed. A
+                      stream whose headers do not arrive within 10 s is given
+                      up on and followed by polling, with a hint on stderr.
+Streams are read from the stream origin: --stream-base-url (global), else the
+host's advertised \`streamBase\` (https only), else --base-url \u2014 some front
+doors buffer event streams entirely (e.g. a CDN rewrite).
 Exit 0 when the run completes, 1 when it fails or is cancelled. \`runs list\` pages with --cursor: pass the
 \`nextCursor\` the previous page printed.
 
@@ -12541,7 +12674,7 @@ async function runRunsBulkCancel(ctx, argv) {
   return 0;
 }
 async function runRunsEvents(ctx, argv) {
-  const { options, positionals } = parseOptions(argv, { bool: ["--help", "--follow", "--no-stream"], value: ["--since", "--limit", "--last-event-id", "--stream-mode", "--timeout-ms"] });
+  const { options, positionals } = parseOptions(argv, { bool: ["--help", "--follow", "--no-stream"], value: ["--since", "--limit", "--last-event-id", "--stream-mode", "--timeout-ms", "--idle-timeout-ms"] });
   if (options.help || positionals.length !== 1) {
     write(ctx.io.stdout, "Usage: openwop runs events <runId> [--since <sequence>] [--limit <n>] [--json]\n       openwop runs events <runId> --follow [--since <sequence> | --last-event-id <id>] [--stream-mode <mode>] [--no-stream] [--json]\n");
     return options.help ? 0 : 2;
@@ -12579,6 +12712,7 @@ async function followRunEvents(ctx, runId, options) {
     ...start,
     useStream: !options.noStream,
     timeoutMs,
+    ...options.idleTimeoutMs !== void 0 ? { idleTimeoutMs: nonNegativeInt(options.idleTimeoutMs, "--idle-timeout-ms") } : {},
     onEvent: (ev) => {
       if (isTerminalRunEvent(ev)) terminalType = canonicalEventType(ev.type);
       if (ctx.json) {
@@ -12818,10 +12952,15 @@ async function runRunsRedrive(ctx, argv) {
   })), ["runId", "redriveRunId", "error"]));
   return anyFailed ? 1 : 0;
 }
+function nonNegativeInt(value, flag) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new CliError(`${flag} must be a non-negative integer (got ${String(value)})`);
+  return n;
+}
 
 // src/cli/chat.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync7 } from "node:fs";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "node:fs";
 var CHAT_BASE = "/v1/host/openwop-app/chat";
 var CHAT_SUBCOMMANDS = ["repl", "sessions", "session", "messages", "message", "participants", "open", "feedback", "models", "search", "export", "import", "tools"];
 var CHAT_HELP = `Usage:
@@ -13411,7 +13550,7 @@ Requires a signed-in account.
   }
   let data;
   try {
-    data = JSON.parse(readFileSync13(String(options.file), "utf8"));
+    data = JSON.parse(readFileSync12(String(options.file), "utf8"));
   } catch (err) {
     throw new CliError(`--file: cannot read JSON from ${options.file} (${err instanceof Error ? err.message : String(err)})`, 2);
   }
@@ -13505,7 +13644,7 @@ Run \`openwop chat tools --help\` for usage.`, 2);
 }
 
 // src/cli/relayShared.ts
-import { existsSync as existsSync4, readFileSync as readFileSync14, writeFileSync as writeFileSync8, mkdirSync as mkdirSync3, rmSync as rmSync2, chmodSync as chmodSync3 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync13, writeFileSync as writeFileSync8, mkdirSync as mkdirSync3, rmSync as rmSync2, chmodSync as chmodSync3 } from "node:fs";
 import { dirname as dirname4, join as join5 } from "node:path";
 var MESSAGING_BASE = "/v1/host/openwop-app/messaging";
 var DEVICE_TOKEN_HEADER = "x-openwop-device-token";
@@ -13516,7 +13655,7 @@ function relayCredsPath(env) {
 function loadRelayConfig(ctx) {
   try {
     const p = relayCredsPath(ctx.env);
-    if (existsSync4(p)) return JSON.parse(readFileSync14(p, "utf8"));
+    if (existsSync4(p)) return JSON.parse(readFileSync13(p, "utf8"));
   } catch {
   }
   return {};
@@ -13552,7 +13691,7 @@ function relayLogPath(env) {
 function readRelayRecord(env) {
   try {
     const p = relayPidPath(env);
-    return existsSync4(p) ? JSON.parse(readFileSync14(p, "utf8")) : null;
+    return existsSync4(p) ? JSON.parse(readFileSync13(p, "utf8")) : null;
   } catch {
     return null;
   }
@@ -14147,7 +14286,7 @@ Usage: openwop notify <email|sms> --to <addr> --text <msg> [--subject s]`);
 
 // src/cli/relay.ts
 import { spawn as spawn2, spawnSync as spawnSync3 } from "node:child_process";
-import { existsSync as existsSync5, readFileSync as readFileSync15, writeFileSync as writeFileSync9, mkdirSync as mkdirSync4, rmSync as rmSync3 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync14, writeFileSync as writeFileSync9, mkdirSync as mkdirSync4, rmSync as rmSync3 } from "node:fs";
 import { dirname as dirname5 } from "node:path";
 import { fileURLToPath } from "node:url";
 var RELAY_HELP = `Usage:
@@ -14498,7 +14637,7 @@ async function runRelayLogs(ctx, argv) {
     const r = spawnSync3("tail", ["-f", logPath], { stdio: "inherit" });
     if (r.status === 0 || r.signal) return 0;
   }
-  write(ctx.io.stdout, readFileSync15(logPath, "utf8"));
+  write(ctx.io.stdout, readFileSync14(logPath, "utf8"));
   return 0;
 }
 
@@ -14867,7 +15006,7 @@ async function runProvidersTest(ctx, argv) {
 // src/cli/packs.ts
 import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign as ed25519Sign, verify as ed25519Verify } from "node:crypto";
 import { gunzipSync, gzipSync } from "node:zlib";
-import { existsSync as existsSync6, readFileSync as readFileSync16, writeFileSync as writeFileSync10, mkdirSync as mkdirSync5, readdirSync, statSync } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync15, writeFileSync as writeFileSync10, mkdirSync as mkdirSync5, readdirSync, statSync } from "node:fs";
 import { join as join6, resolve as resolvePath8 } from "node:path";
 import { homedir as homedir3 } from "node:os";
 var PACKS_HELP = `Usage:
@@ -15124,7 +15263,7 @@ async function runPacksPublish(ctx, argv) {
   if (!existsSync6(manifestPath)) {
     throw new CliError(`No pack.json found in ${absPackDir}.`);
   }
-  const manifest = JSON.parse(readFileSync16(manifestPath, "utf8"));
+  const manifest = JSON.parse(readFileSync15(manifestPath, "utf8"));
   const name = manifest.name;
   const version = manifest.version;
   if (!name || !version) throw new CliError('pack.json must declare both "name" and "version".');
@@ -15137,11 +15276,11 @@ async function runPacksPublish(ctx, argv) {
   let privateKey;
   let ephemeralPublicB64 = null;
   if (options.key) {
-    privateKey = createPrivateKey({ key: readFileSync16(resolvePath8(ctx.cwd, options.key), "utf8"), format: "pem" });
+    privateKey = createPrivateKey({ key: readFileSync15(resolvePath8(ctx.cwd, options.key), "utf8"), format: "pem" });
   } else {
     const conventional = join6(homedir3(), ".openwop-keys", `${keyId}.private.pem`);
     if (existsSync6(conventional)) {
-      privateKey = createPrivateKey({ key: readFileSync16(conventional, "utf8"), format: "pem" });
+      privateKey = createPrivateKey({ key: readFileSync15(conventional, "utf8"), format: "pem" });
     } else {
       const kp = generateKeyPairSync("ed25519");
       privateKey = kp.privateKey;
@@ -15220,7 +15359,7 @@ async function runPacksYank(ctx, argv) {
     throw new CliError(`Version manifest not found: ${manifestPath}
 (packs yank edits a local registry checkout; the published change lands via PR.)`);
   }
-  const manifest = JSON.parse(readFileSync16(manifestPath, "utf8"));
+  const manifest = JSON.parse(readFileSync15(manifestPath, "utf8"));
   const newValue = !options.undo;
   if (Boolean(manifest.yanked) === newValue) {
     writeLine(ctx.io.stdout, `${name}@${version} is already ${newValue ? "yanked" : "un-yanked"}; no change.`);
@@ -15277,11 +15416,11 @@ function walkPackDir(packDir) {
     const st = statSync(full);
     if (st.isFile()) {
       if (!ALLOWED_TOPS.has(entry)) continue;
-      entries2.push({ name: entry, content: readFileSync16(full) });
+      entries2.push({ name: entry, content: readFileSync15(full) });
     } else if (st.isDirectory() && ALLOWED_DIRS.has(entry)) {
       for (const f of readdirSync(full).sort()) {
         if (!f.endsWith(".json") && !f.endsWith(".pem") && !f.endsWith(".sig")) continue;
-        entries2.push({ name: `${entry}/${f}`, content: readFileSync16(join6(full, f)) });
+        entries2.push({ name: `${entry}/${f}`, content: readFileSync15(join6(full, f)) });
       }
     }
   }
@@ -15450,6 +15589,8 @@ async function protocolChecks(ctx) {
   } else if (floor.required !== void 0) {
     rows.push(warn("min client", `host minClientVersion ${floor.required} is not a <major>.<minor> version`));
   }
+  const stream = streamOrigin(ctx);
+  rows.push(stream.source === "base" ? ok("stream origin", `event streams use --base-url (${stream.origin})`) : ok("stream origin", `event streams use ${stream.origin} \u2014 ${STREAM_SOURCE_LABEL[stream.source]}; set --stream-base-url to your --base-url to keep them there`));
   return rows;
 }
 
@@ -15841,7 +15982,7 @@ async function runGovernanceEgress(ctx, argv) {
 
 // src/cli/demo.ts
 import { spawn as spawn3, spawnSync as spawnSync5 } from "node:child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync17, writeFileSync as writeFileSync12, createReadStream, openSync as openSync2, statSync as statSync2, mkdirSync as mkdirSync6, rmSync as rmSync4, chmodSync as chmodSync4, watch } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync16, writeFileSync as writeFileSync12, createReadStream, openSync as openSync2, statSync as statSync2, mkdirSync as mkdirSync6, rmSync as rmSync4, chmodSync as chmodSync4, watch } from "node:fs";
 import { join as join7, dirname as dirname7, relative as relative2 } from "node:path";
 var DEMO_HELP = `Usage:
   openwop demo status [--json]
@@ -16208,7 +16349,7 @@ async function runDemoLogs(ctx, argv) {
     return 2;
   }
   const lineCount = Number(options.lines ?? 50);
-  const existing = readFileSync17(logPath, "utf8");
+  const existing = readFileSync16(logPath, "utf8");
   const lines = existing.split("\n");
   const tail = lines.slice(Math.max(0, lines.length - lineCount - 1));
   write(ctx.io.stdout, tail.join("\n"));
@@ -17294,6 +17435,24 @@ async function runPromptsGet(ctx, argv) {
   return 0;
 }
 
+// src/redact.ts
+var BASE_SECRET_KEY = /secret|token|password|private[-_]?key|client[-_]?secret|api[-_]?key|credential/i;
+function redactSecrets(value, rules = {}) {
+  const secret = rules.secret ?? BASE_SECRET_KEY;
+  const walk = (v) => {
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === "object") {
+      const out = {};
+      for (const [k, inner] of Object.entries(v)) {
+        out[k] = secret.test(k) && !(rules.keep?.test(k) ?? false) ? "[redacted]" : walk(inner);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(value);
+}
+
 // src/cli/connections.ts
 var CONN = "/v1/host/openwop-app/connections/:id";
 var CONNECTIONS_ROUTES = [
@@ -17369,15 +17528,7 @@ Examples:
 `;
 var SECRET_KEY = /secret|token|password|private[-_]?key|client[-_]?secret|api[-_]?key|credential/i;
 function redact(value) {
-  if (Array.isArray(value)) return value.map(redact);
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-      out[k] = SECRET_KEY.test(k) ? "[redacted]" : redact(v);
-    }
-    return out;
-  }
-  return value;
+  return redactSecrets(value, { secret: SECRET_KEY });
 }
 var TOP = ["list", "get", "test", "authorize", "oauth-clients", "oauth-client"];
 async function runConnections(ctx, argv) {
@@ -17581,7 +17732,8 @@ Run \`openwop connections --help\` for usage.`);
   } catch (err) {
     gate4042(err);
   }
-  const clients = (Array.isArray(res.body?.clients) ? res.body.clients : []).map(redact);
+  const rawClients = Array.isArray(res.body?.clients) ? res.body.clients : [];
+  const clients = rawClients.map(redact);
   if (action === "get") {
     if (positionals.length !== 1) {
       write(ctx.io.stdout, "Usage: openwop connections oauth-clients get <provider> [--json]\n");
@@ -18873,7 +19025,7 @@ async function runWfList(ctx, argv) {
   writeLine(ctx.io.stdout, formatTable(rows, ["workforceId", "name", "businessFunction", "status", "autonomy", "agents"]));
   return 0;
 }
-async function runWfReadOne(ctx, argv, suffix, render3) {
+async function runWfReadOne(ctx, argv, suffix, render2) {
   const { options, positionals } = parseOptions(argv, { bool: ["--help"] });
   if (options.help || positionals.length !== 1) {
     write(ctx.io.stdout, WORKFORCES_HELP);
@@ -18890,7 +19042,7 @@ async function runWfReadOne(ctx, argv, suffix, render3) {
     writeJson(ctx.io.stdout, res.body);
     return 0;
   }
-  render3(ctx, res.body ?? {}, positionals[0]);
+  render2(ctx, res.body ?? {}, positionals[0]);
   return 0;
 }
 function renderWorkforce(ctx, w, id) {
@@ -19097,15 +19249,7 @@ Examples:
 var BASE11 = "/v1/host/openwop-app/auth";
 var SECRET_KEY2 = /secret|token|password|private[-_]?key|client[-_]?secret|api[-_]?key|credential|bearer|assertion|certificate|cert|pem/i;
 function redact2(value) {
-  if (Array.isArray(value)) return value.map(redact2);
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-      out[k] = SECRET_KEY2.test(k) ? "[redacted]" : redact2(v);
-    }
-    return out;
-  }
-  return value;
+  return redactSecrets(value, { secret: SECRET_KEY2 });
 }
 async function authRequest(ctx, path, options, notConfiguredMsg) {
   try {
@@ -20164,7 +20308,7 @@ function truncate4(s, n) {
 }
 
 // src/cli/portability.ts
-import { readFileSync as readFileSync18, writeFileSync as writeFileSync13 } from "node:fs";
+import { readFileSync as readFileSync17, writeFileSync as writeFileSync13 } from "node:fs";
 import { resolve as resolve4 } from "node:path";
 var EXPORT_HELP = `Usage:
   openwop export [--kinds <kind>]... [--out <file>] [--json]
@@ -20217,15 +20361,7 @@ Examples:
 var SECRET_KEY3 = /secret|token|password|private[-_]?key|client[-_]?secret|api[-_]?key|credential/i;
 var REF_ONLY_KEY = /^secretsToRebind$/;
 function redact3(value) {
-  if (Array.isArray(value)) return value.map(redact3);
-  if (value && typeof value === "object") {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-      out[k] = SECRET_KEY3.test(k) && !REF_ONLY_KEY.test(k) ? "[redacted]" : redact3(v);
-    }
-    return out;
-  }
-  return value;
+  return redactSecrets(value, { secret: SECRET_KEY3, keep: REF_ONLY_KEY });
 }
 async function ensureAdvertised5(ctx) {
   const wk = await safeRequest(ctx, "/.well-known/openwop", { auth: false });
@@ -20302,7 +20438,7 @@ async function runImport(ctx, argv) {
   }
   let bundle;
   try {
-    const raw = readFileSync18(resolve4(ctx.cwd, positionals[0]), "utf8");
+    const raw = readFileSync17(resolve4(ctx.cwd, positionals[0]), "utf8");
     bundle = JSON.parse(raw);
   } catch (err) {
     throw new CliError(`import: could not read bundle file ${positionals[0]} \u2014 ${err instanceof Error ? err.message : "invalid JSON"}`, 2);
@@ -21074,7 +21210,7 @@ Run \`openwop knowledge-sync --help\` for usage.`);
 }
 
 // src/cli/entities.ts
-import { readFileSync as readFileSync19, writeFileSync as writeFileSync14 } from "node:fs";
+import { readFileSync as readFileSync18, writeFileSync as writeFileSync14 } from "node:fs";
 import { resolve as resolvePath9 } from "node:path";
 var BASE13 = "/v1/host/openwop-app/entities";
 var PUBLIC_BASE2 = "/v1/host/openwop-app/public-entities";
@@ -21310,7 +21446,7 @@ async function types(ctx, sub, pos, o, project4, q) {
       if (!name || !o.file) return usage5(ctx, "types import <type> --file <file.ndjson|file.json>");
       let raw;
       try {
-        raw = readFileSync19(resolvePath9(ctx.cwd, String(o.file)), "utf8");
+        raw = readFileSync18(resolvePath9(ctx.cwd, String(o.file)), "utf8");
       } catch (err) {
         throw new CliError(`Cannot read --file ${String(o.file)}: ${err instanceof Error ? err.message : String(err)}`);
       }
@@ -21881,7 +22017,7 @@ async function startJob(ctx, path, body) {
     const res = await requestJson(ctx, path, { method: "POST", body });
     return renderDone(ctx, res.body, `Video job ${res.body?.jobId ?? ""} ${res.body?.status ?? "started"}.`);
   } catch (err) {
-    const b = err instanceof HttpError ? err.body : void 0;
+    const b = err instanceof HttpError && err.body && typeof err.body === "object" ? err.body : void 0;
     if (err instanceof HttpError && b && b.status === "failed") {
       if (ctx.json) writeJson(ctx.io.stdout, b);
       else writeLine(ctx.io.stderr, `openwop: video generation failed (HTTP ${err.status}): ${b.error ?? "unknown error"}${b.error === "no_connection" ? " \u2014 connect the video provider under Connections first" : ""}`);
@@ -22744,8 +22880,7 @@ async function followEvents(ctx, requestedPath, options) {
   const max = options.max !== void 0 ? Number(options.max) : Infinity;
   const timeoutMs = options.timeout !== void 0 ? Number(options.timeout) * 1e3 : Infinity;
   if (Number.isNaN(max) || Number.isNaN(timeoutMs)) throw new CliError("--max and --timeout must be numbers.");
-  const { path, headers } = await resolveRequest(ctx, requestedPath, { accept: "text/event-stream" });
-  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
+  const { url, headers } = await resolveStreamRequest(ctx, requestedPath, {});
   const controller = new AbortController();
   const timer = Number.isFinite(timeoutMs) ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
   let seen = 0;
@@ -26552,7 +26687,7 @@ function renderKnowledge(ctx, agentId, k) {
 }
 
 // src/cli/compatEndpoints.ts
-import { readFileSync as readFileSync20 } from "node:fs";
+import { readFileSync as readFileSync19 } from "node:fs";
 var BASE32 = "/v1/host/openwop-app/compat-endpoints";
 var COMPAT_ENDPOINTS_HELP = `Usage:
   openwop compat-endpoints list --org <orgId> [--json]
@@ -26666,7 +26801,7 @@ function readApiKey(ctx, options) {
   if (options.apiKeyFile && options.apiKeyEnv) throw new CliError("Pass only one of --api-key-file / --api-key-env.", 2);
   if (options.apiKeyFile) {
     try {
-      return readFileSync20(String(options.apiKeyFile), "utf8").trim() || void 0;
+      return readFileSync19(String(options.apiKeyFile), "utf8").trim() || void 0;
     } catch (err) {
       throw new CliError(`Could not read ${options.apiKeyFile}: ${err instanceof Error ? err.message : String(err)}`, 2);
     }
@@ -27868,7 +28003,7 @@ Run \`openwop scheduled-chats --help\` for usage.`, 2);
 }
 
 // src/cli/voice.ts
-import { readFileSync as readFileSync21, writeFileSync as writeFileSync19 } from "node:fs";
+import { readFileSync as readFileSync20, writeFileSync as writeFileSync19 } from "node:fs";
 var SESSION = "/v1/host/openwop-app/voice/session";
 var REALTIME = "/v1/host/openwop-app/voice/realtime";
 var AUDIO_CHUNK_BYTES = 192 * 1024;
@@ -27973,7 +28108,7 @@ Run \`openwop voice --help\` for usage.`, 2);
       if (options.file) {
         let bytes;
         try {
-          bytes = readFileSync21(String(options.file));
+          bytes = readFileSync20(String(options.file));
         } catch (err) {
           throw new CliError(`--file: cannot read ${options.file} (${err instanceof Error ? err.message : String(err)})`, 2);
         }
@@ -28115,7 +28250,7 @@ async function runRealtime(ctx, argv) {
       if (!options.sdpFile) throw new CliError("voice realtime connect requires --sdp-file <offer.sdp>.", 2);
       let sdp;
       try {
-        sdp = readFileSync21(String(options.sdpFile), "utf8");
+        sdp = readFileSync20(String(options.sdpFile), "utf8");
       } catch (err) {
         throw new CliError(`--sdp-file: cannot read ${options.sdpFile} (${err instanceof Error ? err.message : String(err)})`, 2);
       }
@@ -28170,10 +28305,10 @@ async function runRealtimeConfig(ctx, argv) {
     write(ctx.io.stdout, VOICE_HELP);
     return 0;
   }
-  const render3 = (b) => writeFields(ctx, [["provider", b?.provider], ["credentialRef", b?.credentialRef], ["model", b?.model]]);
+  const render2 = (b) => writeFields(ctx, [["provider", b?.provider], ["credentialRef", b?.credentialRef], ["model", b?.model]]);
   if (sub === "get") {
     const res = await requestJson(ctx, `${REALTIME}/config`);
-    return emit(ctx, res.body, () => render3(res.body));
+    return emit(ctx, res.body, () => render2(res.body));
   }
   if (sub === "set") {
     if (!options.provider && options.credentialRef === void 0 && options.model === void 0) {
@@ -28188,7 +28323,7 @@ async function runRealtimeConfig(ctx, argv) {
     const res = await requestJson(ctx, `${REALTIME}/config`, { method: "PUT", body });
     return emit(ctx, res.body, () => {
       writeLine(ctx.io.stdout, "Updated realtime voice config.");
-      render3(res.body);
+      render2(res.body);
     });
   }
   throw new CliError(`Unknown voice realtime config command: ${sub}
@@ -28196,7 +28331,7 @@ Run \`openwop voice --help\` for usage.`, 2);
 }
 
 // src/cli/ai.ts
-import { readFileSync as readFileSync22 } from "node:fs";
+import { readFileSync as readFileSync21 } from "node:fs";
 var AI = "/v1/host/openwop-app/ai";
 var AI_HELP = `Usage:
   openwop ai call (--message <text> | --messages-json <json>) [--provider p] [--model m] [--json]
@@ -28294,7 +28429,7 @@ async function runAi(ctx, argv) {
       let value;
       if (options.valueFile) {
         try {
-          value = readFileSync22(String(options.valueFile), "utf8").trim();
+          value = readFileSync21(String(options.valueFile), "utf8").trim();
         } catch (err) {
           throw new CliError(`--value-file: cannot read ${options.valueFile} (${err instanceof Error ? err.message : String(err)})`, 2);
         }
@@ -29501,6 +29636,7 @@ async function runCli(argv, options = {}) {
         parsed.globals.baseUrl ?? env.OPENWOP_BASE_URL ?? savedConfig?.host?.baseUrl ?? DEFAULT_BASE_URL
       ),
       apiKey: parsed.globals.apiKey ?? env.OPENWOP_API_KEY ?? savedConfig?.host?.apiKey,
+      streamBaseUrl: explicitStreamBase(parsed.globals.streamBaseUrl ?? env.OPENWOP_STREAM_BASE_URL ?? savedConfig?.host?.streamBaseUrl),
       json: parsed.globals.json,
       quiet: parsed.globals.quiet,
       verbose: parsed.globals.verbose,
@@ -30061,6 +30197,9 @@ Usage:
 
 Global options:
   --base-url <url>    Host base URL (default: --base-url > OPENWOP_BASE_URL > saved config > http://localhost:8080)
+  --stream-base-url <url>
+                      Where to read event streams (default: OPENWOP_STREAM_BASE_URL >
+                      saved config > the host's advertised https streamBase > --base-url)
   --api-key <key>     Bearer API key (default: OPENWOP_API_KEY > saved config > sample-token for localhost)
   --profile <name>    Use a named config profile (~/.openwop-<name>); also OPENWOP_PROFILE
   --json              Print machine-readable JSON where supported