echopai 2.3.0 → 2.4.0

package/dist/runtime/idempotency.js

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

@@ -1,391 +0,0 @@
-/**
- * 端点调用器：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";
-import { maybeEmitUpdateBanner } from "./update_check.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 });
-            maybeEmitUpdateBanner();
-            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");
-        maybeEmitUpdateBanner();
-        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,
-    });
-    maybeEmitUpdateBanner();
-    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

@@ -1,16 +0,0 @@
-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);
-}

package/dist/runtime/paginator.js

@@ -1,146 +0,0 @@
-/**
- * Pagination 策略：自动 follow next_cursor / next_offset 把全部 page NDJSON 输出。
- *
- * 触发：用户加 `--all` flag。`x-cli-pagination` 决定策略：
- *   - `cursor`：response.meta.next_cursor 非空 → 透传到下一次请求 ?cursor=...
- *   - `offset`：response.data.has_more=true → 用 ?offset = sum(已收) 拉下一页
- *   - `none`：不该走 pagination 路径
- *
- * 输出：NDJSON，每行一条 item（剥去 envelope，便于 `| jq` `| while read` 等管道）。
- *
- * 上限：默认 1_000 页或 100_000 items 防失控；可 --max-pages / --max-items 覆盖。
- */
-import { fetch as undiciFetch } from "undici";
-import { tryParseErrorEnvelope, exitCodeForStatus, CallApiError } from "./errors.js";
-import { buildHttpHeaders, resolveRequestId } from "./http.js";
-import { writeStdout } from "./io.js";
-const DEFAULT_MAX_PAGES = 1000;
-const DEFAULT_MAX_ITEMS = 100_000;
-/**
- * 调用并 NDJSON-stream 所有 page。失败抛 CallApiError。
- *
- * write 由调用方注入（默认走 process.stdout.write 且等待 flush，便于测试 mock）。
- */
-export async function paginate(op, initialParams, ctx, write = writeStdout) {
-    if (op.pagination === "none") {
-        throw new Error(`${op.cliKey}: --all not supported (x-cli-pagination=none)`);
-    }
-    const maxPages = ctx.maxPages ?? DEFAULT_MAX_PAGES;
-    const maxItems = ctx.maxItems ?? DEFAULT_MAX_ITEMS;
-    const fetchFn = ctx.fetchImpl ?? undiciFetch;
-    const params = { ...initialParams };
-    let pages = 0;
-    let items = 0;
-    while (true) {
-        const url = ctx.baseUrl + op.path + "?" + buildQueryString(params);
-        // Rebuild headers per page — each page is a distinct request and needs
-        // its own X-Request-Id for server-side correlation.
-        const { headers, requestId: clientRequestId } = buildHttpHeaders({
-            bearer: ctx.bearer,
-            cliVersion: ctx.cliVersion,
-        });
-        if (ctx.debug) {
-            process.stderr.write(`> [page ${pages + 1}] ${op.method} ${url}\n`);
-        }
-        const res = await fetchFn(url, { method: op.method, headers });
-        const body = await res.text();
-        let json = null;
-        try {
-            json = body ? JSON.parse(body) : null;
-        }
-        catch {
-            // ignore
-        }
-        if (res.status >= 400) {
-            const reqId = resolveRequestId(res.headers.get("x-request-id"), clientRequestId);
-            const apiErr = tryParseErrorEnvelope(json, res.status, reqId);
-            throw apiErr ??
-                new CallApiError({
-                    code: "http_error",
-                    message: `HTTP ${res.status}`,
-                    httpStatus: res.status,
-                    requestId: reqId,
-                });
-        }
-        pages += 1;
-        const { itemsArr, nextParams, hasMore } = extractPage(op, json, params);
-        for (const item of itemsArr) {
-            await write(JSON.stringify(item) + "\n");
-            items += 1;
-            if (items >= maxItems) {
-                if (ctx.debug)
-                    process.stderr.write(`[paginate] hit max-items ${maxItems}, stopping\n`);
-                return { pages, items };
-            }
-        }
-        if (!hasMore)
-            return { pages, items };
-        if (pages >= maxPages) {
-            if (ctx.debug)
-                process.stderr.write(`[paginate] hit max-pages ${maxPages}, stopping\n`);
-            return { pages, items };
-        }
-        Object.assign(params, nextParams);
-    }
-}
-function extractPage(op, body, currentParams) {
-    // 公认 envelope 形态：
-    //   { data: { items: [...], total?, has_more?, next_cursor? }, meta?: { next_cursor? } }
-    //   或 { data: [...], meta: { next_cursor? } } —— 直接 array
-    let itemsArr = [];
-    let dataObj = null;
-    let metaObj = null;
-    if (typeof body === "object" && body !== null) {
-        const top = body;
-        if (Array.isArray(top.data)) {
-            itemsArr = top.data;
-        }
-        else if (typeof top.data === "object" && top.data !== null) {
-            dataObj = top.data;
-            if (Array.isArray(dataObj.items))
-                itemsArr = dataObj.items;
-        }
-        else if (Array.isArray(top.items)) {
-            dataObj = top;
-            itemsArr = top.items;
-        }
-        if (typeof top.meta === "object" && top.meta !== null) {
-            metaObj = top.meta;
-        }
-    }
-    if (op.pagination === "cursor") {
-        const nextCursor = metaObj?.next_cursor ??
-            dataObj?.next_cursor;
-        if (typeof nextCursor === "string" && nextCursor) {
-            return { itemsArr, nextParams: { cursor: nextCursor }, hasMore: true };
-        }
-        return { itemsArr, nextParams: {}, hasMore: false };
-    }
-    if (op.pagination === "offset") {
-        const hasMore = Boolean(dataObj?.has_more);
-        if (!hasMore)
-            return { itemsArr, nextParams: {}, hasMore: false };
-        const currentOffset = Number(currentParams.offset ?? 0) + itemsArr.length;
-        return { itemsArr, nextParams: { offset: currentOffset }, hasMore: true };
-    }
-    return { itemsArr, nextParams: {}, hasMore: false };
-}
-function buildQueryString(params) {
-    const parts = [];
-    for (const [k, v] of Object.entries(params)) {
-        if (v === undefined || v === null)
-            continue;
-        if (Array.isArray(v)) {
-            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v.join(","))}`);
-        }
-        else {
-            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-        }
-    }
-    return parts.join("&");
-}
-export function exitCodeForPaginateError(e) {
-    if (e instanceof CallApiError && e.httpStatus)
-        return exitCodeForStatus(e.httpStatus);
-    return 2;
-}

package/dist/runtime/trace.js

@@ -1,99 +0,0 @@
-/**
- * Local CLI invocation trace (ring buffer).
- *
- * 写入 `~/.echopai/trace.ndjson`，每行一条 NDJSON。文件达 RING_MAX_BYTES (50MB)
- * 时旋转为 `trace.ndjson.1` (覆盖前一代)。
- *
- * 用途：事后追溯 request_id / 看最近一次 401 是什么命令打的 / 排查 agent
- * 调用频率。完全本地、不外发、对 prod 零影响。
- *
- * 关闭：`ECHOPAI_NO_TRACE=1`。
- * 重定向：`ECHOPAI_TRACE_FILE=/path/to/file` (主要给测试用)。
- *
- * 失败容错：trace 是 best-effort，任何 fs 错误吞掉，绝不让用户命令因 trace
- * 失败而 crash。
- *
- * 同步写入：CLI 退出时序 (process.exit) 不等 async flush，所以全用 sync API。
- * 一次 appendFileSync ≈ μs 级，对 CLI 启停 latency 可忽略。
- */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-const DEFAULT_TRACE_FILE = join(homedir(), ".echopai", "trace.ndjson");
-const RING_MAX_BYTES = 50 * 1024 * 1024;
-export function isTraceDisabled() {
-    return process.env.ECHOPAI_NO_TRACE === "1";
-}
-export function resolveTraceFile(opts) {
-    return (opts?.filePath ?? process.env.ECHOPAI_TRACE_FILE ?? DEFAULT_TRACE_FILE);
-}
-export function appendTrace(record, opts) {
-    if (isTraceDisabled())
-        return;
-    const file = resolveTraceFile(opts);
-    const maxBytes = opts?.ringMaxBytes ?? RING_MAX_BYTES;
-    try {
-        mkdirSync(dirname(file), { recursive: true });
-        if (existsSync(file)) {
-            const size = statSync(file).size;
-            if (size >= maxBytes) {
-                renameSync(file, file + ".1");
-            }
-        }
-        appendFileSync(file, JSON.stringify(record) + "\n");
-    }
-    catch {
-        // best-effort
-    }
-}
-function readNdjsonLines(file) {
-    try {
-        if (!existsSync(file))
-            return [];
-        const raw = readFileSync(file, "utf-8");
-        const out = [];
-        for (const line of raw.split("\n")) {
-            if (line.length === 0)
-                continue;
-            try {
-                out.push(JSON.parse(line));
-            }
-            catch {
-                // skip malformed line
-            }
-        }
-        return out;
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Last N records in chronological order (oldest → newest).
- * Reads current ring file; falls back to .1 to fill if needed.
- */
-export function tailTraces(n, opts) {
-    if (n <= 0)
-        return [];
-    const file = resolveTraceFile(opts);
-    const current = readNdjsonLines(file);
-    if (current.length >= n)
-        return current.slice(-n);
-    const previous = readNdjsonLines(file + ".1");
-    return previous.concat(current).slice(-n);
-}
-/**
- * Find a single record by request_id. Scans current ring then .1; newest first
- * (so retried request_ids return the latest occurrence).
- */
-export function getTraceByRequestId(requestId, opts) {
-    const file = resolveTraceFile(opts);
-    for (const candidate of [file, file + ".1"]) {
-        const records = readNdjsonLines(candidate);
-        for (let i = records.length - 1; i >= 0; i--) {
-            if (records[i].request_id === requestId)
-                return records[i];
-        }
-    }
-    return null;
-}