echopai 2.8.0 → 2.9.0

package/dist/bin.js

@@ -2928,97 +2928,43 @@ async function downloadAndVerify(url, expectedSha) {
   }
 }
 
-// src/runtime/invoker.ts
-import AjvPkg from "ajv";
-import addFormatsPkg from "ajv-formats";
-
-// src/runtime/auth.ts
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-
-class AuthMissingError extends Error {
-  recovery_hint;
-  constructor(message, recovery_hint) {
-    super(message);
-    this.recovery_hint = recovery_hint;
-    this.name = "AuthMissingError";
-  }
-}
-function configDir() {
-  if (process.platform === "win32") {
-    const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
-    return path.join(appdata, "echopai");
-  }
-  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
-  return path.join(xdg, "echopai");
-}
-function configPath() {
-  return path.join(configDir(), "config.toml");
-}
-function readConfigFile() {
-  const p = configPath();
-  if (!fs.existsSync(p))
-    return {};
-  try {
-    const raw = fs.readFileSync(p, "utf-8");
-    return parseToml(raw);
-  } catch {
-    return {};
-  }
-}
-function writeConfigFile(cfg) {
-  const dir = configDir();
-  fs.mkdirSync(dir, { recursive: true, mode: 448 });
-  const data = stringifyToml(cfg);
-  fs.writeFileSync(configPath(), data, { mode: 384 });
-}
-function resolveCredentials(opts = {}) {
-  const DEFAULT_BASE_URL = "https://api.echopai.com";
-  if (opts.key) {
-    return { key: opts.key, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
-  }
-  const envKey = process.env.ECHOPAI_KEY;
-  if (envKey) {
-    return { key: envKey, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
-  }
-  const cfg = readConfigFile();
-  const profileName = opts.profile || process.env.ECHOPAI_PROFILE || cfg.default_profile;
-  if (profileName && cfg.profiles && cfg.profiles[profileName]) {
-    const p = cfg.profiles[profileName];
-    if (p.key) {
-      return {
-        key: p.key,
-        baseUrl: p.base_url || process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL,
-        profile: profileName
-      };
-    }
-  }
-  throw new AuthMissingError(profileName ? `No key configured for profile '${profileName}'.` : "No credential found.", "Set ECHOPAI_KEY env var, or run `echopai login --key eps_live_<lookup>_<secret>`.");
-}
-
-// src/runtime/envelope.ts
-function mergeMeta(serverMeta, cli) {
-  const merged = {
-    ...serverMeta ?? {},
-    request_id: cli.requestId,
-    endpoint: cli.endpoint,
-    method: cli.method,
-    cli_version: cli.cliVersion,
-    duration_ms: cli.durationMs,
-    truncated: false
-  };
-  if (cli.apiVersion)
-    merged.api_version = cli.apiVersion;
-  return merged;
+// src/runtime/tty.ts
+var enable = (() => {
+  if (!process.stderr.isTTY)
+    return false;
+  if (process.env.CI)
+    return false;
+  if (process.env.NO_COLOR)
+    return false;
+  if (process.env.TERM === "dumb")
+    return false;
+  return true;
+})();
+var isTtyHuman = enable;
+var ESC = "\x1B[";
+function ansi(code, s) {
+  if (!enable)
+    return s;
+  return `${ESC}${code}m${s}${ESC}0m`;
 }
-function buildResponseEnvelope(body, cli) {
-  if (typeof body === "object" && body !== null && !Array.isArray(body) && "data" in body && "meta" in body) {
-    const e = body;
-    return { data: e.data, meta: mergeMeta(e.meta, cli) };
-  }
-  return { data: body, meta: mergeMeta(undefined, cli) };
+var red = (s) => ansi("31", s);
+var green = (s) => ansi("32", s);
+var yellow = (s) => ansi("33", s);
+var cyan = (s) => ansi("36", s);
+var dim = (s) => ansi("2", s);
+var bold = (s) => ansi("1", s);
+function renderError(env) {
+  if (!enable)
+    return JSON.stringify(env);
+  const e = env.error;
+  const label = `${red(bold("✗ " + e.code))}${e.retryable ? " " + dim("(retryable)") : ""}`;
+  const lines = [`${label} ${dim("—")} ${e.message}`];
+  if (e.recovery_hint)
+    lines.push(`  ${cyan("hint:")} ${e.recovery_hint}`);
+  if (e.request_id)
+    lines.push(`  ${dim("request_id: " + e.request_id)}`);
+  return lines.join(`
+`);
 }
 
 // src/runtime/errors.ts
@@ -3157,6 +3103,128 @@ function exitCodeForStatus(httpStatus) {
     return 1;
   return 2;
 }
+var SERVICE_ERROR_CODES = new Set([
+  "network_error",
+  "timeout",
+  "stream_error",
+  "upstream_unavailable",
+  "internal_error",
+  "http_error"
+]);
+function classifyExitCode(code) {
+  return SERVICE_ERROR_CODES.has(code) ? 2 : 1;
+}
+function emitErrorEnvelope(args, exitCode) {
+  const retryable = args.retryable ?? isRetryableByCode(args.code);
+  const hint = resolveRecoveryHint(args.code, args.recovery_hint);
+  const env = { error: { code: args.code, message: args.message, retryable } };
+  if (hint)
+    env.error.recovery_hint = hint;
+  if (args.request_id)
+    env.error.request_id = args.request_id;
+  const ec = exitCode ?? classifyExitCode(args.code);
+  if (isTtyHuman) {
+    process.stderr.write(renderError(env) + `
+`);
+  } else {
+    process.stdout.write(JSON.stringify(env) + `
+`);
+  }
+  process.exit(ec);
+}
+
+// src/runtime/invoker.ts
+import AjvPkg from "ajv";
+import addFormatsPkg from "ajv-formats";
+
+// src/runtime/auth.ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+
+class AuthMissingError extends Error {
+  recovery_hint;
+  constructor(message, recovery_hint) {
+    super(message);
+    this.recovery_hint = recovery_hint;
+    this.name = "AuthMissingError";
+  }
+}
+function configDir() {
+  if (process.platform === "win32") {
+    const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appdata, "echopai");
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(xdg, "echopai");
+}
+function configPath() {
+  return path.join(configDir(), "config.toml");
+}
+function readConfigFile() {
+  const p = configPath();
+  if (!fs.existsSync(p))
+    return {};
+  try {
+    const raw = fs.readFileSync(p, "utf-8");
+    return parseToml(raw);
+  } catch {
+    return {};
+  }
+}
+function writeConfigFile(cfg) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  const data = stringifyToml(cfg);
+  fs.writeFileSync(configPath(), data, { mode: 384 });
+}
+function resolveCredentials(opts = {}) {
+  const DEFAULT_BASE_URL = "https://api.echopai.com";
+  if (opts.key) {
+    return { key: opts.key, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
+  }
+  const envKey = process.env.ECHOPAI_KEY;
+  if (envKey) {
+    return { key: envKey, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
+  }
+  const cfg = readConfigFile();
+  const profileName = opts.profile || process.env.ECHOPAI_PROFILE || cfg.default_profile;
+  if (profileName && cfg.profiles && cfg.profiles[profileName]) {
+    const p = cfg.profiles[profileName];
+    if (p.key) {
+      return {
+        key: p.key,
+        baseUrl: p.base_url || process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL,
+        profile: profileName
+      };
+    }
+  }
+  throw new AuthMissingError(profileName ? `No key configured for profile '${profileName}'.` : "No credential found.", "Set ECHOPAI_KEY env var, or run `echopai login --key eps_live_<lookup>_<secret>`.");
+}
+
+// src/runtime/envelope.ts
+function mergeMeta(serverMeta, cli) {
+  const merged = {
+    ...serverMeta ?? {},
+    request_id: cli.requestId,
+    endpoint: cli.endpoint,
+    method: cli.method,
+    cli_version: cli.cliVersion,
+    duration_ms: cli.durationMs,
+    truncated: false
+  };
+  if (cli.apiVersion)
+    merged.api_version = cli.apiVersion;
+  return merged;
+}
+function buildResponseEnvelope(body, cli) {
+  if (typeof body === "object" && body !== null && !Array.isArray(body) && "data" in body && "meta" in body) {
+    const e = body;
+    return { data: e.data, meta: mergeMeta(e.meta, cli) };
+  }
+  return { data: body, meta: mergeMeta(undefined, cli) };
+}
 
 // src/runtime/filters.ts
 import jmespathPkg from "jmespath";
@@ -3430,6 +3498,22 @@ function buildHttpHeaders(ctx) {
 function resolveRequestId(serverHeader, clientGenerated) {
   return serverHeader && serverHeader.length > 0 ? serverHeader : clientGenerated;
 }
+var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+var WHOAMI_TIMEOUT_MS = 8000;
+async function fetchWithTimeout(fn, url, init, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const ac = new AbortController;
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    return await fn(url, { ...init, signal: ac.signal });
+  } catch (e) {
+    if (ac.signal.aborted) {
+      throw new Error(`request timed out after ${timeoutMs}ms: ${url}`);
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 
 // src/runtime/trace.ts
 import {
@@ -3560,7 +3644,10 @@ async function paginate(op, initialParams, ctx, write = writeStdout) {
       process.stderr.write(`> [page ${pages + 1}] ${op.method} ${url}
 `);
     }
-    const res = await fetchFn(url, { method: op.method, headers });
+    const res = await fetchWithTimeout(fetchFn, url, {
+      method: op.method,
+      headers
+    });
     const body = await res.text();
     let json = null;
     try {
@@ -3655,52 +3742,13 @@ function exitCodeForPaginateError(e) {
   return 2;
 }
 
-// src/runtime/tty.ts
-var enable = (() => {
-  if (!process.stderr.isTTY)
-    return false;
-  if (process.env.CI)
-    return false;
-  if (process.env.NO_COLOR)
-    return false;
-  if (process.env.TERM === "dumb")
-    return false;
-  return true;
-})();
-var isTtyHuman = enable;
-var ESC = "\x1B[";
-function ansi(code, s) {
-  if (!enable)
-    return s;
-  return `${ESC}${code}m${s}${ESC}0m`;
-}
-var red = (s) => ansi("31", s);
-var green = (s) => ansi("32", s);
-var yellow = (s) => ansi("33", s);
-var cyan = (s) => ansi("36", s);
-var dim = (s) => ansi("2", s);
-var bold = (s) => ansi("1", s);
-function renderError(env) {
-  if (!enable)
-    return JSON.stringify(env);
-  const e = env.error;
-  const label = `${red(bold("✗ " + e.code))}${e.retryable ? " " + dim("(retryable)") : ""}`;
-  const lines = [`${label} ${dim("—")} ${e.message}`];
-  if (e.recovery_hint)
-    lines.push(`  ${cyan("hint:")} ${e.recovery_hint}`);
-  if (e.request_id)
-    lines.push(`  ${dim("request_id: " + e.request_id)}`);
-  return lines.join(`
-`);
-}
-
 // src/runtime/update_check.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync as mkdirSync3, renameSync as renameSync2 } from "node:fs";
 import os2 from "node:os";
 import path2 from "node:path";
 
 // src/version.ts
-var CLI_VERSION = "2.8.0";
+var CLI_VERSION = "2.9.0";
 
 // src/runtime/update_check.ts
 var UPDATE_CACHE_PATH = path2.join(os2.homedir(), ".config", "echopai", "update_cache.json");
@@ -3943,7 +3991,7 @@ async function invoke(op, args, ctx) {
   const startedAt = Date.now();
   let res;
   try {
-    res = await fetch(url, init);
+    res = await fetchWithTimeout(fetch, url, init);
   } catch (e) {
     trace(op, { exit_code: 2, error_code: "network_error" });
     writeError("network_error", e instanceof Error ? e.message : String(e), 2);
@@ -4060,23 +4108,13 @@ function trace(op, t) {
   });
 }
 function writeError(code, message, exitCode, extras) {
-  const retryable = extras?.retryable ?? isRetryableByCode(code);
-  const hint = resolveRecoveryHint(code, extras?.recovery_hint);
-  const env = {
-    error: { code, message, retryable }
-  };
-  if (hint)
-    env.error.recovery_hint = hint;
-  if (extras?.request_id)
-    env.error.request_id = extras.request_id;
-  if (isTtyHuman) {
-    process.stderr.write(renderError(env) + `
-`);
-  } else {
-    process.stderr.write(JSON.stringify(env) + `
-`);
-  }
-  process.exit(exitCode);
+  emitErrorEnvelope({
+    code,
+    message,
+    ...extras?.retryable !== undefined ? { retryable: extras.retryable } : {},
+    ...extras?.recovery_hint ? { recovery_hint: extras.recovery_hint } : {},
+    ...extras?.request_id ? { request_id: extras.request_id } : {}
+  }, exitCode);
 }
 
 // src/tools/api.ts
@@ -4138,12 +4176,7 @@ function buildApiCommand() {
   return api;
 }
 function die(code, message, exitCode, recovery_hint) {
-  const env = { error: { code, message } };
-  if (recovery_hint)
-    env.error.recovery_hint = recovery_hint;
-  process.stderr.write(JSON.stringify(env) + `
-`);
-  process.exit(exitCode);
+  emitErrorEnvelope({ code, message, ...recovery_hint ? { recovery_hint } : {} }, exitCode);
 }
 
 // src/tools/mcp.ts
@@ -4172,7 +4205,7 @@ async function getWhoami(ctx, opts) {
   if (inflight && inflight.key === key) {
     return inflight.promise;
   }
-  const promise = doFetch(ctx, opts?.fetchImpl).then((resp) => {
+  const promise = doFetch(ctx, opts?.fetchImpl, opts?.requestTimeoutMs).then((resp) => {
     cache = { key, resp, expiresAt: Date.now() + ttlMs };
     return resp;
   }).finally(() => {
@@ -4182,7 +4215,7 @@ async function getWhoami(ctx, opts) {
   inflight = { key, promise };
   return promise;
 }
-async function doFetch(ctx, fetchImpl) {
+async function doFetch(ctx, fetchImpl, requestTimeoutMs = WHOAMI_TIMEOUT_MS) {
   const fn = fetchImpl ?? fetch;
   const url = ctx.baseUrl.replace(/\/+$/, "") + "/v1/auth/whoami";
   const { headers, requestId: clientRequestId } = buildHttpHeaders({
@@ -4192,7 +4225,7 @@ async function doFetch(ctx, fetchImpl) {
   });
   let res;
   try {
-    res = await fn(url, { method: "GET", headers });
+    res = await fetchWithTimeout(fn, url, { method: "GET", headers }, requestTimeoutMs);
   } catch (e) {
     throw new CallApiError({
       code: "network_error",
@@ -4256,29 +4289,18 @@ async function executeVerb(handler) {
     process.exit(0);
   } catch (e) {
     if (e instanceof CallApiError) {
-      emitVerbError(e.code, e.message, e.recovery_hint, e.httpStatus && e.httpStatus < 500 ? 1 : 2, e.requestId);
+      emitVerbError(e.code, e.message, e.recovery_hint, e.httpStatus ? e.httpStatus < 500 ? 1 : 2 : classifyExitCode(e.code), e.requestId);
     }
     emitVerbError("internal_error", e instanceof Error ? e.message : String(e), undefined, 2);
   }
 }
 function emitVerbError(code, message, recoveryHint, exitCode, requestId) {
-  const env = {
-    error: {
-      code,
-      message,
-      retryable: false,
-      ...recoveryHint ? { recovery_hint: recoveryHint } : {},
-      ...requestId ? { request_id: requestId } : {}
-    }
-  };
-  if (isTtyHuman) {
-    process.stderr.write(renderError(env) + `
-`);
-  } else {
-    process.stderr.write(JSON.stringify(env) + `
-`);
-  }
-  process.exit(exitCode);
+  emitErrorEnvelope({
+    code,
+    message,
+    ...recoveryHint ? { recovery_hint: recoveryHint } : {},
+    ...requestId ? { request_id: requestId } : {}
+  }, exitCode);
 }
 
 // src/runtime/verb_runner.ts
@@ -4338,7 +4360,7 @@ async function callOp(op, args, ctx) {
   const startedAt = Date.now();
   let res;
   try {
-    res = await fetchFn(url, init);
+    res = await fetchWithTimeout(fetchFn, url, init);
   } catch (e) {
     throw new CallApiError({
       code: "network_error",
@@ -6606,24 +6628,51 @@ function buildMcpCommand() {
       }
       throw e;
     }
-    let whoami;
-    try {
-      whoami = await getWhoami({
-        baseUrl: creds.baseUrl,
-        bearer: creds.key,
-        cliVersion: CLI_VERSION,
-        channel: "mcp"
-      });
-    } catch (e) {
-      process.stderr.write(`[mcp] whoami failed: ${e instanceof Error ? e.message : String(e)}
+    const WHOAMI_MAX_ATTEMPTS = 3;
+    const WHOAMI_BACKOFF_MS = [500, 1500];
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    let whoami = null;
+    let lastErr = null;
+    for (let attempt = 1;attempt <= WHOAMI_MAX_ATTEMPTS; attempt++) {
+      try {
+        whoami = await getWhoami({
+          baseUrl: creds.baseUrl,
+          bearer: creds.key,
+          cliVersion: CLI_VERSION,
+          channel: "mcp"
+        });
+        break;
+      } catch (e) {
+        lastErr = e;
+        const status = e instanceof CallApiError ? e.httpStatus : undefined;
+        const code = e instanceof CallApiError ? e.code : undefined;
+        const isAuthError = status === 401 || status === 403 || code === "auth_missing" || code === "forbidden";
+        if (isAuthError) {
+          process.stderr.write(`[mcp] whoami auth failed${status ? ` (HTTP ${status})` : ""}: ` + `${e instanceof Error ? e.message : String(e)}
+` + "[mcp] hint: key 失效或无权限，请 `echopai login` 或检查 ECHOPAI_KEY。\n");
+          process.exit(1);
+        }
+        if (attempt < WHOAMI_MAX_ATTEMPTS) {
+          const backoffMs = WHOAMI_BACKOFF_MS[attempt - 1] ?? 1500;
+          process.stderr.write(`[mcp] whoami attempt ${attempt}/${WHOAMI_MAX_ATTEMPTS} failed ` + `(${e instanceof Error ? e.message : String(e)}); ` + `retrying in ${backoffMs}ms
 `);
-      process.exit(1);
+          await sleep(backoffMs);
+        }
+      }
     }
-    const tokenScopes = new Set(whoami.scopes);
-    const availableVerbs = filterAvailableVerbs(ALL_VERB_SPECS, tokenScopes);
-    process.stderr.write(`[mcp] kind=${whoami.kind} scopes=[${whoami.scopes.join(",")}]
+    let availableVerbs;
+    if (whoami) {
+      const tokenScopes = new Set(whoami.scopes);
+      availableVerbs = filterAvailableVerbs(ALL_VERB_SPECS, tokenScopes);
+      process.stderr.write(`[mcp] kind=${whoami.kind} scopes=[${whoami.scopes.join(",")}]
 ` + `[mcp] exposing ${availableVerbs.length}/${ALL_VERB_SPECS.length} curated verbs as MCP tools
 `);
+    } else {
+      availableVerbs = [...ALL_VERB_SPECS];
+      process.stderr.write(`[mcp] whoami failed after ${WHOAMI_MAX_ATTEMPTS} attempts: ` + `${lastErr instanceof Error ? lastErr.message : String(lastErr)}
+` + `[mcp] degraded start: exposing all ${availableVerbs.length} curated verbs; ` + `scopes enforced per-call by the server
+`);
+    }
     const server = new McpServer({
       name: "echopai",
       version: CLI_VERSION,
@@ -6762,14 +6811,7 @@ function buildRawCallCommand() {
   return call;
 }
 function die2(code, message, exitCode, recovery_hint) {
-  const env = {
-    error: { code, message, retryable: false }
-  };
-  if (recovery_hint)
-    env.error.recovery_hint = recovery_hint;
-  process.stderr.write(JSON.stringify(env) + `
-`);
-  process.exit(exitCode);
+  emitErrorEnvelope({ code, message, ...recovery_hint ? { recovery_hint } : {} }, exitCode);
 }
 
 // src/tools/completion.ts
@@ -6960,12 +7002,7 @@ function redactKey(key) {
   return `eps_live_${parts[2]}_***${last.slice(-4)}`;
 }
 function writeError2(code, message, recovery_hint, exitCode) {
-  const env = { error: { code, message } };
-  if (recovery_hint)
-    env.error.recovery_hint = recovery_hint;
-  process.stderr.write(JSON.stringify(env) + `
-`);
-  process.exit(exitCode);
+  emitErrorEnvelope({ code, message, ...recovery_hint ? { recovery_hint } : {} }, exitCode);
 }
 
 // src/tools/login.ts
@@ -7145,23 +7182,12 @@ function buildWhoamiCommand() {
   return cmd;
 }
 function emitError(code, message, recoveryHint, exitCode, requestId) {
-  const env = {
-    error: {
-      code,
-      message,
-      retryable: false,
-      ...recoveryHint ? { recovery_hint: recoveryHint } : {},
-      ...requestId ? { request_id: requestId } : {}
-    }
-  };
-  if (isTtyHuman) {
-    process.stderr.write(renderError(env) + `
-`);
-  } else {
-    process.stderr.write(JSON.stringify(env) + `
-`);
-  }
-  process.exit(exitCode);
+  emitErrorEnvelope({
+    code,
+    message,
+    ...recoveryHint ? { recovery_hint: recoveryHint } : {},
+    ...requestId ? { request_id: requestId } : {}
+  }, exitCode);
 }
 
 // src/tools/doctor.ts
@@ -8118,10 +8144,10 @@ var program = new Command31;
 program.name("echopai").description(`Command-line access to the EchoPai market-data platform: quotes, news,
 ` + `analyst research, fundamentals, and sentiment.
 
-` + `Machine-readable by design — a JSON envelope on stdout, JSON errors on
-` + `stderr, and three-state exit codes (0 success / 1 user error / 2 service
-` + `error) — built for AI agents and scripts. Authenticate with the
-` + "ECHOPAI_KEY environment variable or `echopai login`.").version(CLI_VERSION, "-V, --version").addOption(new Option23("--debug", "Print HTTP wire trace to stderr (Bearer redacted)")).addOption(new Option23("--raw", "Pass through raw response body (skip envelope wrap)")).addOption(new Option23("--jq <jmespath>", "Filter or transform output with a JMESPath expression.")).addOption(new Option23("--fields <a,b,c>", "Keep only listed top-level fields per item")).addOption(new Option23("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)")).addOption(new Option23("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)")).addOption(new Option23("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support")).addHelpText("after", `
+` + `Machine-readable by design — in non-TTY (agent/script) mode both success
+` + "`{data:...}` and error `{error:{code,retryable,...}}` envelopes go to stdout\n" + `(one stream to parse), with three-state exit codes (0 success / 1 user error
+` + `/ 2 service error). On a TTY, errors render to stderr for humans. Built for AI
+` + "agents and scripts. Authenticate with ECHOPAI_KEY or `echopai login`.").version(CLI_VERSION, "-V, --version").addOption(new Option23("--debug", "Print HTTP wire trace to stderr (Bearer redacted)")).addOption(new Option23("--raw", "Pass through raw response body (skip envelope wrap)")).addOption(new Option23("--jq <jmespath>", "Filter or transform output with a JMESPath expression.")).addOption(new Option23("--fields <a,b,c>", "Keep only listed top-level fields per item")).addOption(new Option23("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)")).addOption(new Option23("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)")).addOption(new Option23("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support")).addHelpText("after", `
 Authentication:  ECHOPAI_KEY=<eps_live_...> echopai <command>
 ` + `Curated verbs:   echopai <verb>                                  # task-level commands (recommended)
 ` + `Raw operations:  echopai raw <noun> <verb>                       # low-level access to every API operation
@@ -8145,21 +8171,30 @@ var dispatch = async (op, args) => {
   }
   await invoke(op, { ...globalsSnake, ...args }, { cliVersion: CLI_VERSION });
 };
+function detectStrayCodeArgs(args) {
+  if (!Array.isArray(args))
+    return [];
+  const codeLike = /^((SSE|SZSE|BSE|SH|SZ|BJ):)?[0-9]{6}$/i;
+  return args.filter((a) => typeof a === "string" && codeLike.test(a));
+}
 function applyAiFirstHooks(cmd) {
   cmd.configureOutput({ writeErr: () => {} });
   cmd.exitOverride((err) => {
     if (err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version") {
       process.exit(0);
     }
-    process.stderr.write(JSON.stringify({
-      error: {
-        code: "invalid_args",
-        message: err.message,
-        recovery_hint: "Run with `--help` for usage."
-      }
-    }) + `
-`);
-    process.exit(1);
+    let message = err.message;
+    const stray = detectStrayCodeArgs(cmd.args);
+    if (stray.length > 0) {
+      const opt = /code\b/i.test(err.message) ? "--code" : "--codes";
+      message += `. Detected positional argument(s) [${stray.join(", ")}] — these commands ` + `take codes via an option, not positionally; did you mean ` + `\`${opt} ${stray.join(",")}\`?`;
+    }
+    emitErrorEnvelope({
+      code: "invalid_args",
+      message,
+      retryable: false,
+      recovery_hint: "Run with `--help` for usage."
+    }, 1);
   });
   for (const sub of cmd.commands)
     applyAiFirstHooks(sub);
@@ -8231,12 +8266,5 @@ if (shouldShowWelcome(process.argv)) {
   process.exit(0);
 }
 program.parseAsync(process.argv).catch((e) => {
-  process.stderr.write(JSON.stringify({
-    error: {
-      code: "internal_error",
-      message: e instanceof Error ? e.message : String(e)
-    }
-  }) + `
-`);
-  process.exit(2);
+  emitErrorEnvelope({ code: "internal_error", message: e instanceof Error ? e.message : String(e) }, 2);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echopai",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Command-line interface for the EchoPai Open Platform: stock-market data, news, analyst views, sentiment, signals, backtests.",
   "license": "MIT",
   "homepage": "https://echopai.com",