echopai 2.3.0 → 2.4.0

package/dist/runtime/auth.js

@@ -1,95 +0,0 @@
-/**
- * Credential / profile resolution.
- *
- * Precedence（高 → 低）：
- *   1. --key <eps_live_X_Y>   命令行
- *   2. ECHOPAI_KEY env
- *   3. ~/.config/echopai/config.toml 默认 profile
- *   4. ~/.config/echopai/config.toml 指定 profile（--profile <name> 或 ECHOPAI_PROFILE）
- *   5. 报错 auth_missing
- *
- * 配置文件格式（TOML）：
- *
- *   default_profile = "prod"
- *
- *   [profiles.prod]
- *   key = "eps_live_xxx_yyy"
- *   base_url = "https://api.echopai.com"
- *
- *   [profiles.staging]
- *   key = "eps_live_aaa_bbb"
- *   base_url = "https://staging.echopai.com"
- *
- * XDG paths：
- *   Linux/macOS: $XDG_CONFIG_HOME/echopai/config.toml or ~/.config/echopai/config.toml
- *   Windows:     %APPDATA%/echopai/config.toml
- */
-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";
-export class AuthMissingError extends Error {
-    recovery_hint;
-    constructor(message, recovery_hint) {
-        super(message);
-        this.recovery_hint = recovery_hint;
-        this.name = "AuthMissingError";
-    }
-}
-export 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");
-}
-export function configPath() {
-    return path.join(configDir(), "config.toml");
-}
-export function readConfigFile() {
-    const p = configPath();
-    if (!fs.existsSync(p))
-        return {};
-    try {
-        const raw = fs.readFileSync(p, "utf-8");
-        return parseToml(raw);
-    }
-    catch {
-        return {};
-    }
-}
-export function writeConfigFile(cfg) {
-    const dir = configDir();
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const data = stringifyToml(cfg);
-    fs.writeFileSync(configPath(), data, { mode: 0o600 });
-}
-export function resolveCredentials(opts = {}) {
-    const DEFAULT_BASE_URL = "https://api.echopai.com";
-    // 1. --key arg
-    if (opts.key) {
-        return { key: opts.key, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
-    }
-    // 2. env var
-    const envKey = process.env.ECHOPAI_KEY;
-    if (envKey) {
-        return { key: envKey, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
-    }
-    // 3+4. config file
-    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>`.");
-}

package/dist/runtime/envelope.js

@@ -1,52 +0,0 @@
-/**
- * Standard CLI success envelope.
- *
- * 服务端响应有时含 `{data, meta}`（pagination cursors / has_more / total 等），
- * 有时只返 data。本模块统一对外输出：
- *
- *   { data, meta: { ...serverMeta, request_id, endpoint, method, cli_version,
- *                   api_version?, duration_ms, truncated } }
- *
- * CLI 字段永远覆盖 server 同名字段——CLI 是观察者，知道真相（例如 server 没 echo
- * X-Request-Id 时，CLI 端的 uuid 才是 canonical）。
- *
- * truncated 默认 false；PR 1.4 引入 --max-bytes / --fields 等截断逻辑后，
- * 触发时由 invoker / paginator 写为 true 并附 truncation_reason。
- *
- * 与 http.ts 关系：http.ts 出站（request headers），envelope.ts 入站（response meta）。
- */
-/**
- * Merge server-provided meta with CLI-known truth. CLI fields win on collision.
- */
-export 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;
-}
-/**
- * Build a complete response envelope from a raw response body.
- *
- * - 若 body 是 `{data, meta}` 形态：data 透传，meta 合并 CLI 字段。
- * - 否则：整 body 当 data，meta 全部由 CLI 提供。
- * - body 为 null/字符串/数组时也走"整 body 当 data"分支。
- */
-export 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) };
-}

package/dist/runtime/errors.js

@@ -1,186 +0,0 @@
-/**
- * 错误层：解析 API envelope，分级 exit code，输出 stderr JSON。
- *
- * Canonical envelope (server + CLI uniform):
- *   { "error": {
- *       "code": "<machine_code>",
- *       "message": "<human>",
- *       "retryable": <bool>,
- *       "recovery_hint": "<actionable>",
- *       "request_id": "<uuid>"
- *   } }
- *
- * `code` must be a member of KNOWN_ERROR_CODES (see docs/api-contract/error-codes.md).
- * Server may emit codes outside this set; CLI accepts them but logs a warning under
- * --debug. `recovery_hint` falls back to DEFAULT_RECOVERY_HINTS when server omits it.
- *
- * Exit code 三态：
- *   0 success
- *   1 user error      (4xx — auth_missing / scope_insufficient / kind_not_allowed /
- *                      invalid_args / validation_failed / not_found / confirmation_required ...)
- *   2 service error   (5xx, 429 retryable, network failure, internal_error, stream_error)
- */
-export const KNOWN_ERROR_CODES = [
-    // auth / identity
-    "auth_missing",
-    "auth_invalid",
-    "auth_expired",
-    // permission / scope
-    "scope_insufficient",
-    "kind_not_allowed",
-    "channel_not_allowed",
-    // input / validation
-    "invalid_args",
-    "validation_failed",
-    "not_found",
-    "idempotency_conflict",
-    // write / confirmation
-    "confirmation_required",
-    "dry_run_unsupported",
-    "unsafe_command",
-    // rate / quota
-    "rate_limited",
-    "quota_exhausted",
-    "agent_budget_exhausted",
-    // transport / infrastructure
-    "network_error",
-    "timeout",
-    "stream_error",
-    "upstream_unavailable",
-    // server / internal
-    "internal_error",
-    "http_error",
-];
-const KNOWN_CODE_SET = new Set(KNOWN_ERROR_CODES);
-export function isKnownErrorCode(code) {
-    return KNOWN_CODE_SET.has(code);
-}
-/**
- * Codes that are safe to retry with the same input. Server may also set
- * `retryable` per-response; if it does, server wins. This map is the
- * fallback when server omits `retryable`.
- */
-const RETRYABLE_CODES = new Set([
-    "rate_limited",
-    "network_error",
-    "timeout",
-    "stream_error",
-    "upstream_unavailable",
-    "internal_error",
-]);
-export function isRetryableByCode(code) {
-    return RETRYABLE_CODES.has(code);
-}
-/**
- * Default recovery hints when server omits `recovery_hint`. Keep in sync with
- * docs/api-contract/error-codes.md.
- */
-export const DEFAULT_RECOVERY_HINTS = {
-    auth_missing: "Run `echopai login`, or set `ECHOPAI_KEY=<token>`.",
-    auth_invalid: "Token rejected. Re-issue via `echopai login` or check token revocation.",
-    auth_expired: "Token expired. Re-issue via `echopai login`.",
-    scope_insufficient: "Run `echopai whoami` to see available scopes; request the missing scope from your app admin.",
-    kind_not_allowed: "Endpoint not available for this token kind. See `echopai whoami` for your kind.",
-    channel_not_allowed: "This CLI/MCP channel is not authorized for the current token. Check `allowed_clients` on your app config.",
-    invalid_args: "Check parameter types/format. Run with `--help` for the schema.",
-    validation_failed: "Server rejected the request body. Check the `message` for the offending field.",
-    not_found: "Resource does not exist or is not visible to this token.",
-    idempotency_conflict: "Same Idempotency-Key seen with a different body. Use a new key or replay the original request exactly.",
-    confirmation_required: "Non-TTY write requires `--yes`. Re-run with `--yes` after verifying the operation.",
-    dry_run_unsupported: "This endpoint does not support `--dry-run`. Run without `--dry-run` (and `--yes` if it's a write).",
-    unsafe_command: "This command is gated. See `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §6 for safety model.",
-    rate_limited: "Slow down. Honor `Retry-After` header if present; back off and retry.",
-    quota_exhausted: "Monthly quota for this endpoint class exceeded. Upgrade plan or wait until reset.",
-    agent_budget_exhausted: "Agent budget exhausted. Start a new session via `agent session-start` or request a budget bump.",
-    network_error: "Verify network reachability and `base_url`. Use `--debug` for full trace.",
-    timeout: "Server took too long. Retry; if persistent, check `echopai doctor`.",
-    stream_error: "WebSocket closed abnormally. Use `--debug` to see the close code/reason; `--reconnect` to auto-retry.",
-    upstream_unavailable: "Upstream service is temporarily unavailable. Retry with backoff.",
-    internal_error: "Server-side error. Retry; include the `request_id` when reporting.",
-    http_error: "Server did not return a typed error envelope. See `message` and `request_id`.",
-};
-/**
- * Resolve effective recovery hint:
- *   1. Explicit hint (server-provided or CLI-passed)
- *   2. DEFAULT_RECOVERY_HINTS[code] fallback
- *   3. undefined if code unknown and no hint
- */
-export function resolveRecoveryHint(code, explicit) {
-    if (explicit && explicit.length > 0)
-        return explicit;
-    if (isKnownErrorCode(code))
-        return DEFAULT_RECOVERY_HINTS[code];
-    return undefined;
-}
-export class CallApiError extends Error {
-    code;
-    retryable;
-    recovery_hint;
-    httpStatus;
-    requestId;
-    raw;
-    constructor(args) {
-        super(args.message);
-        this.name = "CallApiError";
-        this.code = args.code;
-        this.retryable = args.retryable ?? isRetryableByCode(args.code);
-        this.recovery_hint = resolveRecoveryHint(args.code, args.recovery_hint);
-        this.httpStatus = args.httpStatus;
-        this.requestId = args.requestId;
-        this.raw = args.raw;
-    }
-}
-/**
- * Parse possibly-envelope JSON body. Returns CallApiError if it looks like a
- * standard EchoPai error, else null.
- */
-export function tryParseErrorEnvelope(body, httpStatus, requestId) {
-    if (typeof body !== "object" || body === null)
-        return null;
-    const obj = body;
-    const direct = errorFromObject(obj.error, body, httpStatus, requestId);
-    if (direct)
-        return direct;
-    // FastAPI sometimes wraps the service envelope as {detail: {error: {...}}}.
-    if (typeof obj.detail === "object" && obj.detail !== null) {
-        const detail = obj.detail;
-        const nested = errorFromObject(detail.error, body, httpStatus, requestId);
-        if (nested)
-            return nested;
-    }
-    // FastAPI fallback {detail: "..."}
-    if (typeof obj.detail === "string") {
-        return new CallApiError({
-            code: httpStatus === 401 ? "auth_missing" : "http_error",
-            message: obj.detail,
-            httpStatus,
-            requestId,
-            raw: body,
-        });
-    }
-    return null;
-}
-function errorFromObject(value, raw, httpStatus, requestId) {
-    if (typeof value !== "object" || value === null)
-        return null;
-    const env = value;
-    if (typeof env.code !== "string" || typeof env.message !== "string") {
-        return null;
-    }
-    return new CallApiError({
-        code: env.code,
-        message: env.message,
-        ...(typeof env.retryable === "boolean" ? { retryable: env.retryable } : {}),
-        ...(typeof env.recovery_hint === "string"
-            ? { recovery_hint: env.recovery_hint }
-            : {}),
-        httpStatus,
-        requestId,
-        raw,
-    });
-}
-export function exitCodeForStatus(httpStatus) {
-    if (httpStatus >= 400 && httpStatus < 500)
-        return 1;
-    return 2;
-}

package/dist/runtime/filters.js

@@ -1,153 +0,0 @@
-/**
- * Output filter pipeline applied between response envelope and render.
- *
- * Pipeline order (each step optional, --flag triggers):
- *   1. --query <jmespath>     data = jmespath.search(data, expr)
- *   2. --fields a,b,c          keep only these keys per item/object
- *   3. --max-bytes N           binary-search items truncation; meta.truncated=true
- *
- * 设计原则：
- * - JMESPath 错误算 user error（exit 1），调用方负责捕获并 writeError("invalid_args")。
- * - --fields 对 array / {items:[]} / 普通 object 都做 best-effort projection。
- * - --max-bytes 是 serialized envelope 的字节数；items 数组形态可智能裁剪，
- *   其他形态退化为整 data 替换为 omitted 占位符。
- * - 截断时 meta.truncated 翻为 true，加 truncation_reason / truncated_items_dropped。
- */
-import jmespathPkg from "jmespath";
-const jmes = jmespathPkg;
-const jmesSearch = jmes.search ?? (jmes.default ? jmes.default.search : (() => null));
-export class FilterError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "FilterError";
-    }
-}
-export function applyFilters(envelope, opts) {
-    let data = envelope.data;
-    let meta = { ...envelope.meta };
-    if (opts.query && opts.query.length > 0) {
-        try {
-            data = jmesSearch(data, opts.query);
-        }
-        catch (e) {
-            throw new FilterError(`Invalid --query expression: ${e instanceof Error ? e.message : String(e)}`);
-        }
-    }
-    if (opts.fields && opts.fields.length > 0) {
-        data = pickFields(data, opts.fields);
-    }
-    if (opts.maxBytes !== undefined && opts.maxBytes > 0) {
-        return enforceMaxBytes({ data, meta }, opts.maxBytes);
-    }
-    return { data, meta };
-}
-/**
- * Recursively project: array → map; {items:[...]} → recurse into items;
- * plain object → pick listed keys; primitive → unchanged.
- */
-export function pickFields(value, fields) {
-    if (Array.isArray(value)) {
-        return value.map((item) => pickFields(item, fields));
-    }
-    if (value !== null && typeof value === "object") {
-        const obj = value;
-        if (Array.isArray(obj.items)) {
-            return {
-                ...obj,
-                items: obj.items.map((it) => pickFields(it, fields)),
-            };
-        }
-        const out = {};
-        for (const f of fields) {
-            if (f in obj)
-                out[f] = obj[f];
-        }
-        return out;
-    }
-    return value;
-}
-function enforceMaxBytes(env, maxBytes) {
-    const initialSize = JSON.stringify(env).length;
-    if (initialSize <= maxBytes)
-        return env;
-    const data = env.data;
-    // Truncatable shape 1: object with {items: [...]} (envelope-style)
-    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
-        const obj = data;
-        if (Array.isArray(obj.items)) {
-            const items = obj.items;
-            const total = items.length;
-            const buildEnv = (n) => ({
-                data: { ...obj, items: items.slice(0, n) },
-                meta: {
-                    ...env.meta,
-                    truncated: true,
-                    truncation_reason: "max_bytes",
-                    truncated_items_dropped: total - n,
-                },
-            });
-            const fit = binarySearchFit(buildEnv, total, maxBytes);
-            return buildEnv(fit);
-        }
-    }
-    // Truncatable shape 2: top-level array
-    if (Array.isArray(data)) {
-        const total = data.length;
-        const buildEnv = (n) => ({
-            data: data.slice(0, n),
-            meta: {
-                ...env.meta,
-                truncated: true,
-                truncation_reason: "max_bytes",
-                truncated_items_dropped: total - n,
-            },
-        });
-        const fit = binarySearchFit(buildEnv, total, maxBytes);
-        return buildEnv(fit);
-    }
-    // Non-truncatable: replace data with placeholder
-    return {
-        data: {
-            omitted: true,
-            reason: "response exceeded --max-bytes; data is not paginatable",
-        },
-        meta: {
-            ...env.meta,
-            truncated: true,
-            truncation_reason: "max_bytes",
-        },
-    };
-}
-function binarySearchFit(shape, total, maxBytes) {
-    // Find largest n in [0, total] where JSON.stringify(shape(n)).length <= maxBytes
-    let lo = 0;
-    let hi = total;
-    while (lo < hi) {
-        const mid = Math.floor((lo + hi + 1) / 2);
-        const size = JSON.stringify(shape(mid)).length;
-        if (size <= maxBytes)
-            lo = mid;
-        else
-            hi = mid - 1;
-    }
-    return lo;
-}
-export function parseFieldsFlag(raw) {
-    if (typeof raw !== "string" || raw.length === 0)
-        return undefined;
-    const fields = raw
-        .split(",")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0);
-    return fields.length > 0 ? fields : undefined;
-}
-export function parseMaxBytesFlag(raw) {
-    if (typeof raw === "number" && raw > 0)
-        return raw;
-    if (typeof raw === "string" && raw.length > 0) {
-        const n = Number(raw);
-        if (Number.isFinite(n) && n > 0)
-            return n;
-    }
-    return undefined;
-}

package/dist/runtime/format.js

@@ -1,143 +0,0 @@
-/**
- * Output format renderer。
- *
- * - json    JSON.stringify (multi-line in TTY, single-line otherwise)
- * - ndjson  one JSON object per line（流式友好）
- * - table   ASCII table（仅 array of flat object）
- * - csv     RFC-4180 quoted
- * - tsv     tab-separated
- * - yaml    minimal YAML（不依赖 lib，仅 flat / array of flat）
- *
- * 自动从 data 推断列名（取 array[0] 的 keys）；若不是 array of object 则
- * fallback 到 json（避免格式错误）。
- */
-export function isOutputFormat(s) {
-    return ["json", "ndjson", "table", "csv", "tsv", "yaml"].includes(s);
-}
-export function render(env, fmt, isTty) {
-    if (fmt === "json") {
-        // TTY: pretty 2-space; non-TTY: single line (NDJSON-friendly pipelines)
-        return JSON.stringify(env, null, isTty ? 2 : 0);
-    }
-    if (fmt === "ndjson") {
-        return ndjson(env);
-    }
-    // table / csv / tsv / yaml — only useful on array of flat object data。
-    // server envelope 常见形态 {items: [...], total, has_more} —— 对 items 表格化。
-    let target = env.data;
-    if (typeof target === "object" &&
-        target !== null &&
-        !Array.isArray(target) &&
-        Array.isArray(target.items)) {
-        target = target.items;
-    }
-    const arr = arrayOfFlatObjects(target);
-    if (arr === null) {
-        // fallback to json
-        return JSON.stringify(env, null, isTty ? 2 : 0);
-    }
-    if (fmt === "table")
-        return renderTable(arr);
-    if (fmt === "csv")
-        return renderDelimited(arr, ",", true);
-    if (fmt === "tsv")
-        return renderDelimited(arr, "\t", false);
-    if (fmt === "yaml")
-        return renderYaml(arr);
-    return JSON.stringify(env, null, isTty ? 2 : 0);
-}
-function arrayOfFlatObjects(data) {
-    if (!Array.isArray(data))
-        return null;
-    if (data.length === 0)
-        return [];
-    // 允许嵌套字段（cell 渲染时 JSON.stringify），但顶层每条必须是 object。
-    for (const item of data) {
-        if (typeof item !== "object" || item === null || Array.isArray(item))
-            return null;
-    }
-    return data;
-}
-/**
- * Pick a stable subset of columns for table / CSV — the union of keys from
- * the first few rows, capped at COLUMN_LIMIT. 防超宽表格 + 缺字段 row 不破列。
- */
-const COLUMN_LIMIT = 8;
-function pickColumns(arr) {
-    const seen = new Set();
-    for (let i = 0; i < Math.min(arr.length, 5); i++) {
-        for (const k of Object.keys(arr[i])) {
-            if (!seen.has(k)) {
-                seen.add(k);
-                if (seen.size >= COLUMN_LIMIT)
-                    return [...seen];
-            }
-        }
-    }
-    return [...seen];
-}
-function ndjson(env) {
-    if (Array.isArray(env.data)) {
-        return env.data.map((d) => JSON.stringify(d)).join("\n");
-    }
-    return JSON.stringify(env);
-}
-function renderTable(arr) {
-    if (arr.length === 0)
-        return "(empty)";
-    const cols = pickColumns(arr);
-    const CELL_MAX = 60; // truncate long cells (URLs, content)
-    const truncate = (s) => (s.length > CELL_MAX ? s.slice(0, CELL_MAX - 1) + "…" : s);
-    const rows = arr.map((r) => cols.map((c) => truncate(stringify(r[c]))));
-    const widths = cols.map((c, i) => Math.max(c.length, ...rows.map((r) => r[i].length)));
-    const sep = widths.map((w) => "-".repeat(w)).join("-+-");
-    const headerRow = cols.map((c, i) => c.padEnd(widths[i])).join(" | ");
-    const dataRows = rows.map((r) => r.map((cell, i) => cell.padEnd(widths[i])).join(" | "));
-    return [headerRow, sep, ...dataRows].join("\n");
-}
-function renderDelimited(arr, delim, csvQuote) {
-    if (arr.length === 0)
-        return "";
-    const cols = pickColumns(arr);
-    const escape = (s) => {
-        if (!csvQuote)
-            return s.replace(/\t/g, " ").replace(/\n/g, " ");
-        if (s.includes(delim) || s.includes('"') || s.includes("\n")) {
-            return `"${s.replace(/"/g, '""')}"`;
-        }
-        return s;
-    };
-    const header = cols.map(escape).join(delim);
-    const rows = arr.map((r) => cols.map((c) => escape(stringify(r[c]))).join(delim));
-    return [header, ...rows].join("\n");
-}
-function renderYaml(arr) {
-    if (arr.length === 0)
-        return "[]";
-    return arr
-        .map((r) => {
-        const lines = Object.entries(r).map(([k, v]) => `  ${k}: ${yamlScalar(v)}`);
-        return ["-", ...lines].join("\n");
-    })
-        .join("\n");
-}
-function yamlScalar(v) {
-    if (v === null || v === undefined)
-        return "null";
-    if (typeof v === "string") {
-        // quote if contains special chars
-        if (v === "" || /[:#\n"']|^\s|\s$/.test(v))
-            return JSON.stringify(v);
-        return v;
-    }
-    return String(v);
-}
-function stringify(v) {
-    if (v === null || v === undefined)
-        return "";
-    if (typeof v === "string")
-        return v;
-    if (typeof v === "number" || typeof v === "boolean")
-        return String(v);
-    return JSON.stringify(v);
-}

package/dist/runtime/http.js

@@ -1,65 +0,0 @@
-/**
- * Centralized header construction for all CLI outbound requests (HTTP + WS).
- *
- * 强制注入：
- *   - Authorization (HTTP only; WS 走 Sec-WebSocket-Protocol subprotocol)
- *   - Accept: application/json (HTTP)
- *   - User-Agent: echopai-cli/<v> Node/<v> <platform>-<arch>
- *   - X-Client: echopai-cli/<v>
- *   - X-Client-Channel: cli | mcp        (默认 cli；mcp serve 注入 mcp)
- *   - X-Request-Id: client-generated uuidv4   (server 若 echo 同名 header 以 server 为准)
- *
- * 每次构造生成新的 X-Request-Id（除非显式传 requestId）。分页 / WS 重连场景每次
- * 迭代都应该重新调一次 builder，以拿到独立的 request_id。
- *
- * 与 envelope.ts 的关系：本模块只负责出站；入站 / meta 拼装由 envelope.ts 做。
- */
-import { randomUUID } from "node:crypto";
-import { Headers } from "undici";
-export function buildUserAgent(cliVersion) {
-    // User-Agent identifier matches X-Client (also `echopai-cli/<v>`) so
-    // server-side metrics/audit can match on either header uniformly.
-    // Renamed from `@echopai/cli/<v>` in v2.0.0 alongside the npm rename
-    // from @echopai/cli → echopai. X-Client itself was already this form.
-    return `echopai-cli/${cliVersion} Node/${process.version} ${process.platform}-${process.arch}`;
-}
-export function buildHttpHeaders(ctx) {
-    const requestId = ctx.requestId ?? randomUUID();
-    const headers = new Headers({
-        Authorization: `Bearer ${ctx.bearer}`,
-        Accept: "application/json",
-        "User-Agent": buildUserAgent(ctx.cliVersion),
-        "X-Client": `echopai-cli/${ctx.cliVersion}`,
-        "X-Client-Channel": ctx.channel ?? "cli",
-        "X-Request-Id": requestId,
-    });
-    return { headers, requestId };
-}
-/**
- * WebSocket upgrade headers. NO Authorization — WS auth flows via
- * Sec-WebSocket-Protocol `bearer.<token>` subprotocol.
- *
- * Plain object because `ws` lib's `headers` option is Record<string,string>,
- * not undici Headers.
- */
-export function buildWsHeaders(ctx) {
-    const requestId = ctx.requestId ?? randomUUID();
-    const headers = {
-        "User-Agent": buildUserAgent(ctx.cliVersion),
-        "X-Client": `echopai-cli/${ctx.cliVersion}`,
-        "X-Client-Channel": ctx.channel ?? "cli",
-        "X-Request-Id": requestId,
-    };
-    return { headers, requestId };
-}
-/**
- * Effective request_id for meta envelope / logging:
- *   server echo wins (server can rewrite for correlation in its own audit);
- *   otherwise client-generated uuid is canonical.
- *
- * After Phase 1 lands, both ends will have a request_id even for endpoints
- * the server doesn't echo yet — they just won't agree until server adopts echo.
- */
-export function resolveRequestId(serverHeader, clientGenerated) {
-    return serverHeader && serverHeader.length > 0 ? serverHeader : clientGenerated;
-}