echopai 2.0.0

package/dist/runtime/format.js

@@ -0,0 +1,143 @@
+/**
+ * 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

@@ -0,0 +1,65 @@
+/**
+ * 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;
+}

package/dist/runtime/idempotency.js

@@ -0,0 +1,18 @@
+/**
+ * Idempotency-Key 自动生成。
+ *
+ * 端点 op.idempotencyRequired === true 时，invoker 自动 gen UUIDv4 并：
+ *   - 加 Idempotency-Key request header
+ *   - echo 到 stderr 让用户 / AI agent 能记下来重试时复用同一 key
+ *
+ * 用户也可显式 --idempotency-key <uuid> 覆盖（debug 重放用）。
+ */
+import * as crypto from "node:crypto";
+export function generateIdempotencyKey() {
+    return crypto.randomUUID();
+}
+export function announceKey(key, op) {
+    // stderr 不污染 stdout JSON envelope
+    process.stderr.write(`[idempotency-key] ${op}: ${key}\n` +
+        `[idempotency-key] retry: pass --idempotency-key ${key} to dedupe.\n`);
+}

package/dist/runtime/invoker.js

@@ -0,0 +1,387 @@
+/**
+ * 端点调用器：Ajv pre-flight → undici fetch → envelope 解析 → render → exit。
+ *
+ * 由 _generated/commands.ts 的 dispatch 入口调用。
+ *
+ * 支持参数：
+ *   --output <fmt>   覆盖默认 outputDefault
+ *   --query <jmespath>  Phase 3 加，本 PR 不接
+ *   --debug          stderr 打 HTTP wire trace（脱敏 Bearer）
+ *   --raw            跳 envelope 解析，输出原始 body
+ */
+import AjvPkg from "ajv";
+import addFormatsPkg from "ajv-formats";
+import { fetch } from "undici";
+import { resolveCredentials, AuthMissingError } from "./auth.js";
+import { buildResponseEnvelope } from "./envelope.js";
+import { exitCodeForStatus, isRetryableByCode, resolveRecoveryHint, tryParseErrorEnvelope, CallApiError, } from "./errors.js";
+import { applyFilters, parseFieldsFlag, parseMaxBytesFlag, FilterError, } from "./filters.js";
+import { isOutputFormat, render } from "./format.js";
+import { buildHttpHeaders, resolveRequestId } from "./http.js";
+import { appendTrace } from "./trace.js";
+import { generateIdempotencyKey, announceKey } from "./idempotency.js";
+import { writeStdout, writeStderr } from "./io.js";
+import { paginate, exitCodeForPaginateError } from "./paginator.js";
+import { renderError, isTtyHuman } from "./tty.js";
+const Ajv = (AjvPkg.default ??
+    AjvPkg);
+const addFormats = (addFormatsPkg.default ??
+    addFormatsPkg);
+// strict: false 让 Ajv 接受 OpenAPI 3.0 的 `example` / `examples` 关键字（不是
+// 标准 JSON Schema draft 7，但 OpenAPI 普遍用）。
+// coerceTypes: 'array' 允许 --codes SSE:000001 自动包成 ["SSE:000001"]，
+// 也允许 --codes "A,B,C" 字符串入 array schema（但用户更常用单值）。
+const ajv = new Ajv({
+    allErrors: true,
+    useDefaults: true,
+    coerceTypes: "array",
+    strict: false,
+});
+addFormats(ajv);
+const SYSTEM_FLAGS = new Set([
+    "output",
+    "all",
+    "key",
+    "profile",
+    "debug",
+    "raw",
+    "idempotency_key",
+    "max_pages",
+    "max_items",
+    // PR 1.4 — output filter pipeline (renamed root --query → --jq in Phase 6
+    // smoke-fix because subcommand specs declare their own --query as a body
+    // param, e.g. news.search. Stripping "query" here would eat that param.)
+    "jq",
+    "fields",
+    "max_bytes",
+    // Phase 6 — write safety + dry-run
+    "yes",
+    "dry_run",
+]);
+export async function invoke(op, args, ctx) {
+    const isTty = process.stdout.isTTY === true && !process.env.CI;
+    // 1. resolve --output
+    let outputFmt = op.outputDefault;
+    if (typeof args.output === "string" && isOutputFormat(args.output)) {
+        outputFmt = args.output;
+    }
+    const debug = Boolean(args.debug);
+    const raw = Boolean(args.raw);
+    // 2. resolve credentials
+    const resolveOpts = {};
+    if (typeof args.key === "string")
+        resolveOpts.key = args.key;
+    if (typeof args.profile === "string")
+        resolveOpts.profile = args.profile;
+    let creds;
+    try {
+        creds = resolveCredentials(resolveOpts);
+    }
+    catch (e) {
+        if (e instanceof AuthMissingError) {
+            trace(op, { exit_code: 1, error_code: "auth_missing" });
+            writeError("auth_missing", e.message, 1, e.recovery_hint ? { recovery_hint: e.recovery_hint } : undefined);
+        }
+        throw e;
+    }
+    // 3. strip system flags + undefined to get actual API params
+    const apiParams = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (SYSTEM_FLAGS.has(k))
+            continue;
+        if (v === undefined || v === "")
+            continue;
+        apiParams[k] = v;
+    }
+    // 4a. coerce CSV → array for params declared as array in schema (Ajv coerce
+    // wraps single-string as 1-element array, but for "A,B,C" we want split-on-comma).
+    for (const [pname, pschema] of Object.entries(op.inputSchema.properties)) {
+        if (typeof pschema === "object" &&
+            pschema !== null &&
+            pschema.type === "array" &&
+            typeof apiParams[pname] === "string" &&
+            apiParams[pname].includes(",")) {
+            apiParams[pname] = apiParams[pname].split(",").map((s) => s.trim());
+        }
+    }
+    // 4b. Ajv pre-flight schema validation
+    const validate = ajv.compile(op.inputSchema);
+    if (!validate(apiParams)) {
+        const errs = (validate.errors || [])
+            .map((e) => `${e.instancePath || "(root)"}: ${e.message ?? "invalid"}`)
+            .join("; ");
+        trace(op, { exit_code: 1, error_code: "invalid_args" });
+        writeError("invalid_args", `Input validation failed: ${errs}`, 1);
+    }
+    // 4c. Phase 6 — write safety + dry-run gates
+    //
+    // Two CLI-side preflight checks, both fail-closed:
+    //
+    // a) non-TTY write without --yes → confirmation_required
+    //    Agents/scripts can never accidentally trigger a side-effect; they
+    //    must opt in explicitly. TTY users get the usual interactive flow
+    //    (commander itself prompts? no — we keep this simple: TTY skips the
+    //    gate and assumes the user typed the command knowingly).
+    //
+    // b) --dry-run on op where dryRunSupported=false → dry_run_unsupported
+    //    Refuse to silently noop. The agent gets a structured error and
+    //    knows to retry without --dry-run (or pick a different op).
+    //
+    // When --dry-run is honored we set X-Dry-Run:1 in the outgoing headers
+    // further down (step 5c). Read ops with --dry-run are a noop client-side
+    // (they don't mutate anyway) — we treat them as a soft success but stamp
+    // meta.dry_run=true so callers know nothing happened.
+    const yes = Boolean(args.yes);
+    const dryRun = Boolean(args.dry_run);
+    if (op.sideEffect === "write" && !isTty && !yes) {
+        trace(op, { exit_code: 1, error_code: "confirmation_required" });
+        writeError("confirmation_required", `Operation ${op.cliKey} is a write (side-effect=write) and stdout is not a TTY. Pass --yes to confirm.`, 1);
+    }
+    if (dryRun && !op.dryRunSupported && op.sideEffect === "write") {
+        trace(op, { exit_code: 1, error_code: "dry_run_unsupported" });
+        writeError("dry_run_unsupported", `Operation ${op.cliKey} does not support server-side dry-run (X-Dry-Run).`, 1);
+    }
+    // 5. build URL + query string
+    let url = creds.baseUrl + op.path;
+    // path templating: {id} → URL-encoded value, removed from query
+    const pathParamRegex = /\{([^}]+)\}/g;
+    url = url.replace(pathParamRegex, (_full, name) => {
+        const v = apiParams[name];
+        if (v === undefined) {
+            trace(op, { exit_code: 1, error_code: "invalid_args" });
+            writeError("invalid_args", `Path parameter '${name}' is required.`, 1);
+        }
+        delete apiParams[name];
+        return encodeURIComponent(String(v));
+    });
+    // 5a. WS streaming endpoint — REMOVED. CLI no longer ships /v1/ws/{news,views}
+    //     as commands. The OpenAPI ops still exist for partner SDKs but the
+    //     codegen drops x-cli-key, so this branch is unreachable today and
+    //     should stay deleted unless the partner-side WS auth model is reworked
+    //     (see WS removal commit + plan §3 follow-ups).
+    // 5b. paginate `--all`
+    if (args.all && op.pagination !== "none") {
+        try {
+            const result = await paginate(op, apiParams, {
+                baseUrl: creds.baseUrl,
+                bearer: creds.key,
+                cliVersion: ctx.cliVersion,
+                debug,
+                ...(typeof args.max_pages === "string"
+                    ? { maxPages: Number(args.max_pages) }
+                    : typeof args.max_pages === "number"
+                        ? { maxPages: args.max_pages }
+                        : {}),
+                ...(typeof args.max_items === "string"
+                    ? { maxItems: Number(args.max_items) }
+                    : typeof args.max_items === "number"
+                        ? { maxItems: args.max_items }
+                        : {}),
+            });
+            await writeStderr(`[paginate] ${result.pages} pages, ${result.items} items\n`);
+            trace(op, { exit_code: 0 });
+            process.exit(0);
+        }
+        catch (e) {
+            if (e instanceof CallApiError) {
+                const exitCode = exitCodeForPaginateError(e);
+                trace(op, {
+                    request_id: e.requestId,
+                    status: e.httpStatus,
+                    exit_code: exitCode,
+                    error_code: e.code,
+                });
+                writeError(e.code, e.message, exitCode, {
+                    retryable: e.retryable,
+                    ...(e.recovery_hint ? { recovery_hint: e.recovery_hint } : {}),
+                    ...(e.requestId ? { request_id: e.requestId } : {}),
+                });
+            }
+            trace(op, { exit_code: 2, error_code: "internal_error" });
+            writeError("internal_error", e instanceof Error ? e.message : String(e), 2);
+        }
+    }
+    // 5c. single-shot HTTP request
+    const queryString = buildQueryString(apiParams);
+    if (op.method === "GET" && queryString)
+        url += "?" + queryString;
+    const { headers, requestId: clientRequestId } = buildHttpHeaders({
+        bearer: creds.key,
+        cliVersion: ctx.cliVersion,
+    });
+    // Idempotency-Key for endpoints that require it
+    if (op.idempotencyRequired) {
+        const userKey = typeof args.idempotency_key === "string" ? args.idempotency_key : null;
+        const idemKey = userKey || generateIdempotencyKey();
+        headers.set("Idempotency-Key", idemKey);
+        if (!userKey)
+            announceKey(idemKey, op.cliKey);
+    }
+    // X-Dry-Run: only set on writes where the server explicitly advertises
+    // support (op.dryRunSupported). Read ops with --dry-run flow through
+    // unchanged — they're a noop server-side, so there's nothing to dry-run.
+    if (dryRun && op.dryRunSupported) {
+        headers.set("X-Dry-Run", "1");
+    }
+    const init = {
+        method: op.method,
+        headers,
+    };
+    if (op.method === "POST") {
+        headers.set("Content-Type", "application/json");
+        init.body = JSON.stringify(apiParams);
+    }
+    if (debug) {
+        process.stderr.write(`> ${op.method} ${url}\n` +
+            `> Authorization: Bearer eps_live_***_***\n` +
+            Array.from(headers.entries())
+                .filter(([k]) => k.toLowerCase() !== "authorization")
+                .map(([k, v]) => `> ${k}: ${v}`)
+                .join("\n") +
+            "\n");
+    }
+    // 6. fire request
+    const startedAt = Date.now();
+    let res;
+    try {
+        res = await 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);
+    }
+    const requestId = resolveRequestId(res.headers.get("x-request-id"), clientRequestId);
+    const apiVersion = res.headers.get("x-api-version") || undefined;
+    const ct = res.headers.get("content-type") || "";
+    const bodyText = await res.text();
+    let bodyJson = null;
+    if (ct.includes("application/json") && bodyText) {
+        try {
+            bodyJson = JSON.parse(bodyText);
+        }
+        catch {
+            // body 不是 JSON
+        }
+    }
+    const durationMs = Date.now() - startedAt;
+    if (debug) {
+        process.stderr.write(`< ${res.status} ${res.statusText}\n`);
+        if (requestId)
+            process.stderr.write(`< x-request-id: ${requestId}\n`);
+    }
+    // 7. error path
+    if (res.status >= 400) {
+        const apiErr = tryParseErrorEnvelope(bodyJson, res.status, requestId);
+        const exitCode = exitCodeForStatus(res.status);
+        const code = apiErr?.code ?? "http_error";
+        trace(op, {
+            request_id: requestId,
+            status: res.status,
+            duration_ms: durationMs,
+            exit_code: exitCode,
+            error_code: code,
+        });
+        if (apiErr) {
+            writeError(apiErr.code, apiErr.message, exitCode, {
+                retryable: apiErr.retryable,
+                ...(apiErr.recovery_hint ? { recovery_hint: apiErr.recovery_hint } : {}),
+                request_id: requestId,
+            });
+        }
+        writeError("http_error", `HTTP ${res.status} ${res.statusText}: ${bodyText.slice(0, 200)}`, exitCode, { request_id: requestId });
+    }
+    // 8. success path — render
+    if (raw) {
+        await writeStdout(bodyText + "\n");
+        process.exit(0);
+    }
+    const rawEnvelope = buildResponseEnvelope(bodyJson ?? bodyText, {
+        requestId,
+        endpoint: op.path,
+        method: op.method,
+        cliVersion: ctx.cliVersion,
+        durationMs,
+        ...(apiVersion ? { apiVersion } : {}),
+    });
+    let envelope = rawEnvelope;
+    try {
+        // Global JMESPath filter is `--jq` (renamed from --query in Phase 6
+        // smoke-fix to avoid clashing with subcommand `--query` body params,
+        // e.g. news.search). Do NOT fall back to args.query here — that's the
+        // subcommand body field, not a JMESPath expression.
+        const jq = typeof args.jq === "string" ? args.jq : undefined;
+        envelope = applyFilters(rawEnvelope, {
+            ...(jq ? { query: jq } : {}),
+            ...(parseFieldsFlag(args.fields) ? { fields: parseFieldsFlag(args.fields) } : {}),
+            ...(parseMaxBytesFlag(args.max_bytes) ? { maxBytes: parseMaxBytesFlag(args.max_bytes) } : {}),
+        });
+    }
+    catch (e) {
+        if (e instanceof FilterError) {
+            trace(op, {
+                request_id: requestId,
+                status: res.status,
+                duration_ms: durationMs,
+                exit_code: 1,
+                error_code: "invalid_args",
+            });
+            writeError("invalid_args", e.message, 1);
+        }
+        throw e;
+    }
+    await writeStdout(render(envelope, outputFmt, isTty) + "\n");
+    trace(op, {
+        request_id: requestId,
+        status: res.status,
+        duration_ms: durationMs,
+        exit_code: 0,
+        truncated: envelope.meta.truncated === true,
+    });
+    process.exit(0);
+}
+function buildQueryString(params) {
+    const parts = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            // edge-gateway expects ?codes=A,B not ?codes=A&codes=B
+            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v.join(","))}`);
+        }
+        else {
+            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+        }
+    }
+    return parts.join("&");
+}
+function trace(op, t) {
+    appendTrace({
+        ts: new Date().toISOString(),
+        request_id: t.request_id ?? null,
+        cmd: op.cliKey,
+        status: t.status ?? null,
+        duration_ms: t.duration_ms ?? null,
+        exit_code: t.exit_code,
+        ...(t.truncated ? { truncated: true } : {}),
+        ...(t.error_code ? { error_code: t.error_code } : {}),
+    });
+}
+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;
+    // TTY: 多行人性化输出 (color + recovery_hint 高亮)；非 TTY 输出 single-line JSON。
+    if (isTtyHuman) {
+        process.stderr.write(renderError(env) + "\n");
+    }
+    else {
+        process.stderr.write(JSON.stringify(env) + "\n");
+    }
+    process.exit(exitCode);
+}

package/dist/runtime/io.js

@@ -0,0 +1,16 @@
+function writeStream(stream, text) {
+    return new Promise((resolve, reject) => {
+        stream.write(text, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+export function writeStdout(text) {
+    return writeStream(process.stdout, text);
+}
+export function writeStderr(text) {
+    return writeStream(process.stderr, text);
+}