echopai 2.0.0

package/dist/runtime/paginator.js

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

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

package/dist/runtime/tty.js

@@ -0,0 +1,51 @@
+/**
+ * TTY 检测 + 极小 ANSI 着色（无依赖，避免 chalk/ora 拖慢 CLI 启动）。
+ *
+ * 启用规则：
+ *   - process.stdout.isTTY === true
+ *   - !process.env.CI
+ *   - !process.env.NO_COLOR
+ *   - process.env.TERM !== 'dumb'
+ *
+ * 任一失败 → color() / dim() / errSym() 返回原文（脚本/AI 场景纯洁）。
+ */
+const 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;
+})();
+export const isTtyHuman = enable;
+const ESC = "[";
+function ansi(code, s) {
+    if (!enable)
+        return s;
+    return `${ESC}${code}m${s}${ESC}0m`;
+}
+export const red = (s) => ansi("31", s);
+export const green = (s) => ansi("32", s);
+export const yellow = (s) => ansi("33", s);
+export const cyan = (s) => ansi("36", s);
+export const dim = (s) => ansi("2", s);
+export const bold = (s) => ansi("1", s);
+/**
+ * 把 error envelope 渲染成多行人性化文字（仅 TTY）。
+ * 非 TTY 直接 JSON.stringify。
+ */
+export 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("\n");
+}

package/dist/runtime/verb_cmd.js

@@ -0,0 +1,70 @@
+/**
+ * Shared scaffolding for curated agent verbs.
+ *
+ * 每个 verb 都做同样三件事：解析 credential → 调一次或多次 callOp → emit
+ * envelope + exit。本模块把样板抽出，让 verb 实现只关心"参数 → 派生 args → 映射
+ * 输出"。
+ *
+ * 与 verb_runner.ts 的区别：
+ * - verb_runner: 纯 HTTP/Ajv 层，不知道 commander / exit / stderr renderer
+ * - verb_cmd:    process / commander 层 ergonomics，把 runner 包成"一行起 verb"
+ */
+import { resolveCredentials, AuthMissingError } from "./auth.js";
+import { CallApiError } from "./errors.js";
+import { isTtyHuman, renderError } from "./tty.js";
+import { CLI_VERSION } from "../version.js";
+/**
+ * Run a verb handler end-to-end:
+ *   1. Resolve credentials (auth_missing → exit 1)
+ *   2. Invoke handler with ctx
+ *   3. Print stdout envelope + exit 0 on success
+ *   4. Map CallApiError → structured stderr + exit 1/2 by HTTP class
+ */
+export async function executeVerb(handler) {
+    let creds;
+    try {
+        creds = resolveCredentials({});
+    }
+    catch (e) {
+        if (e instanceof AuthMissingError) {
+            emitVerbError("auth_missing", e.message, e.recovery_hint, 1);
+        }
+        throw e;
+    }
+    try {
+        const env = await handler({
+            baseUrl: creds.baseUrl,
+            bearer: creds.key,
+            cliVersion: CLI_VERSION,
+        });
+        process.stdout.write(JSON.stringify(env) + "\n");
+        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);
+        }
+        // unexpected error: structured emit, exit 2
+        emitVerbError("internal_error", e instanceof Error ? e.message : String(e), undefined, 2);
+    }
+}
+export 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) + "\n");
+    }
+    else {
+        process.stderr.write(JSON.stringify(env) + "\n");
+    }
+    process.exit(exitCode);
+}
+/** Re-export for verb-local convenience. */
+export { CLI_VERSION };

package/dist/runtime/verb_runner.js

@@ -0,0 +1,152 @@
+/**
+ * Programmatic operation runner — shared core for curated agent verbs.
+ *
+ * 与 invoker.ts 的关系：invoker.ts 是 commander 入口 (强耦合 process.exit / 错误
+ * stderr 输出 / trace 记录)；本模块只做"调一次操作 → 返回 envelope"，便于 verb
+ * 实现里组合多次调用 (e.g. digest fan-out) 或在调完后映射 output。
+ *
+ * 不做的事：
+ * - --all 分页 (verb 自己决定要不要)
+ * - WebSocket streaming (单帧场景不存在)
+ * - Idempotency-Key 自动注入 (Phase 6 写 verb 显式控制)
+ * - trace 写入 (调用方自己 trace)
+ *
+ * 错误：抛 CallApiError；调用方负责 catch + 决定 exit / 部分失败容错。
+ */
+import AjvPkg from "ajv";
+import addFormatsPkg from "ajv-formats";
+import { fetch as undiciFetch } from "undici";
+import { buildResponseEnvelope } from "./envelope.js";
+import { CallApiError, tryParseErrorEnvelope } from "./errors.js";
+import { buildHttpHeaders, resolveRequestId } from "./http.js";
+const Ajv = (AjvPkg.default ??
+    AjvPkg);
+const addFormats = (addFormatsPkg.default ??
+    addFormatsPkg);
+const ajv = new Ajv({
+    allErrors: true,
+    useDefaults: true,
+    coerceTypes: "array",
+    strict: false,
+});
+addFormats(ajv);
+/**
+ * Invoke a single OpenAPI operation programmatically. Returns the standard
+ * response envelope; throws CallApiError on failure (network / HTTP 4xx-5xx /
+ * malformed response).
+ *
+ * Validation:
+ * - Pre-flight Ajv validates `args` against `op.inputSchema`. On validation
+ *   failure, throws CallApiError(code="invalid_args").
+ *
+ * Path templating: occurrences of `{name}` in `op.path` are substituted from
+ * `args[name]` and removed from query.
+ */
+export async function callOp(op, args, ctx) {
+    const params = { ...args };
+    // Pre-flight schema validation
+    const validate = ajv.compile(op.inputSchema);
+    if (!validate(params)) {
+        const errs = (validate.errors || [])
+            .map((e) => `${e.instancePath || "(root)"}: ${e.message ?? "invalid"}`)
+            .join("; ");
+        throw new CallApiError({
+            code: "invalid_args",
+            message: `Input validation failed: ${errs}`,
+        });
+    }
+    // Path templating
+    let url = ctx.baseUrl.replace(/\/+$/, "") + op.path;
+    const pathParamRegex = /\{([^}]+)\}/g;
+    const missingPathParam = [];
+    url = url.replace(pathParamRegex, (_full, name) => {
+        const v = params[name];
+        if (v === undefined) {
+            missingPathParam.push(name);
+            return _full;
+        }
+        delete params[name];
+        return encodeURIComponent(String(v));
+    });
+    if (missingPathParam.length > 0) {
+        throw new CallApiError({
+            code: "invalid_args",
+            message: `Path parameter(s) required: ${missingPathParam.join(", ")}`,
+        });
+    }
+    // Query / body
+    const qs = buildQueryString(params, op.method);
+    if (op.method === "GET" && qs)
+        url += "?" + qs;
+    const { headers, requestId: clientRequestId } = buildHttpHeaders({
+        bearer: ctx.bearer,
+        cliVersion: ctx.cliVersion,
+        ...(ctx.channel ? { channel: ctx.channel } : {}),
+    });
+    const init = { method: op.method, headers };
+    if (op.method === "POST") {
+        headers.set("Content-Type", "application/json");
+        init.body = JSON.stringify(params);
+    }
+    const fetchFn = ctx.fetchImpl ?? undiciFetch;
+    const startedAt = Date.now();
+    let res;
+    try {
+        res = await fetchFn(url, init);
+    }
+    catch (e) {
+        throw new CallApiError({
+            code: "network_error",
+            message: e instanceof Error ? e.message : String(e),
+        });
+    }
+    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 {
+            // non-JSON body — let error path below handle
+        }
+    }
+    const durationMs = Date.now() - startedAt;
+    if (res.status >= 400) {
+        const apiErr = tryParseErrorEnvelope(bodyJson, res.status, requestId);
+        if (apiErr)
+            throw apiErr;
+        throw new CallApiError({
+            code: "http_error",
+            message: `HTTP ${res.status} ${res.statusText}: ${bodyText.slice(0, 200)}`,
+            httpStatus: res.status,
+            requestId,
+        });
+    }
+    return buildResponseEnvelope(bodyJson ?? bodyText, {
+        requestId,
+        endpoint: op.path,
+        method: op.method,
+        cliVersion: ctx.cliVersion,
+        durationMs,
+        ...(apiVersion ? { apiVersion } : {}),
+    });
+}
+function buildQueryString(params, method) {
+    if (method !== "GET")
+        return "";
+    const parts = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        if (Array.isArray(v)) {
+            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v.join(","))}`);
+        }
+        else {
+            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+        }
+    }
+    return parts.join("&");
+}

package/dist/runtime/whoami_cache.js

@@ -0,0 +1,109 @@
+/**
+ * /v1/auth/whoami client + 5-minute in-process cache.
+ *
+ * 设计原则：
+ * - **单飞 (single-flight)**: 并发调用时只发一次真请求；多调用者共享 in-flight
+ *   Promise。MCP serve 长 session 多并发 list-tools 场景下避免请求风暴。
+ * - **TTL 5 分钟**: cache hit 后跨命令复用 (process 退出即失效)。shell one-shot
+ *   每次多一次 whoami 调用；MCP server 长进程几乎永远 cache hit。
+ * - **bearer 切换不复用**: cache key 含 bearer prefix，换 token 自动 miss。
+ * - **best-effort 失败传播**: 网络 / auth 错误抛 CallApiError 上去由 caller
+ *   决定 (doctor 显示 fail，whoami exit 2)。
+ *
+ * 不在这里做 verb 派生 / unavailable 列表计算——那是 tools/whoami.ts 的职责。
+ */
+import { fetch as undiciFetch } from "undici";
+import { CallApiError, tryParseErrorEnvelope } from "./errors.js";
+import { buildHttpHeaders, resolveRequestId } from "./http.js";
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+let cache = null;
+let inflight = null;
+function cacheKey(ctx) {
+    // bearer 前 8 char + baseUrl 足以区分；不存全 bearer 避免日志 / dump 泄露。
+    return `${ctx.baseUrl}|${ctx.bearer.slice(0, 8)}|${ctx.channel ?? "cli"}`;
+}
+/** Test-only hook: reset module state between specs. */
+export function clearWhoamiCache() {
+    cache = null;
+    inflight = null;
+}
+/** Public read of cache without triggering fetch (returns null if miss/expired). */
+export function peekWhoamiCache(ctx) {
+    const k = cacheKey(ctx);
+    if (cache && cache.key === k && cache.expiresAt > Date.now())
+        return cache.resp;
+    return null;
+}
+export async function getWhoami(ctx, opts) {
+    const key = cacheKey(ctx);
+    const ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+    if (!opts?.force && cache && cache.key === key && cache.expiresAt > Date.now()) {
+        return cache.resp;
+    }
+    if (inflight && inflight.key === key) {
+        return inflight.promise;
+    }
+    const promise = doFetch(ctx, opts?.fetchImpl)
+        .then((resp) => {
+        cache = { key, resp, expiresAt: Date.now() + ttlMs };
+        return resp;
+    })
+        .finally(() => {
+        if (inflight && inflight.key === key)
+            inflight = null;
+    });
+    inflight = { key, promise };
+    return promise;
+}
+async function doFetch(ctx, fetchImpl) {
+    const fn = fetchImpl ?? undiciFetch;
+    const url = ctx.baseUrl.replace(/\/+$/, "") + "/v1/auth/whoami";
+    const { headers, requestId: clientRequestId } = buildHttpHeaders({
+        bearer: ctx.bearer,
+        cliVersion: ctx.cliVersion,
+        ...(ctx.channel ? { channel: ctx.channel } : {}),
+    });
+    let res;
+    try {
+        res = await fn(url, { method: "GET", headers });
+    }
+    catch (e) {
+        throw new CallApiError({
+            code: "network_error",
+            message: e instanceof Error ? e.message : String(e),
+        });
+    }
+    const requestId = resolveRequestId(res.headers.get("x-request-id"), clientRequestId);
+    const text = await res.text();
+    let json = null;
+    if (text) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            // body not JSON — error path below will surface http_error
+        }
+    }
+    if (res.status >= 400) {
+        const env = tryParseErrorEnvelope(json, res.status, requestId);
+        if (env)
+            throw env;
+        throw new CallApiError({
+            code: "http_error",
+            message: `HTTP ${res.status} ${res.statusText}: ${text.slice(0, 200)}`,
+            httpStatus: res.status,
+            requestId,
+        });
+    }
+    if (typeof json !== "object" ||
+        json === null ||
+        !("data" in json)) {
+        throw new CallApiError({
+            code: "internal_error",
+            message: "whoami: response missing `data` envelope",
+            httpStatus: res.status,
+            requestId,
+        });
+    }
+    return json.data;
+}