echopai 2.0.0

package/dist/verbs/digest.js

@@ -0,0 +1,342 @@
+/**
+ * `echopai digest --code <canonical_code>` + MCP tool `digest`.
+ *
+ * Killer "one-shot research" verb:
+ *
+ *   one canonical_code  →  views + research + quote + sentiment + news
+ *
+ * Plan-doc §3.3 makes this the "agent's opening move": one call returns the
+ * full picture of a security. Buckets stay separated (no ranking imposed) so
+ * the model can weigh each itself; the description already encodes the
+ * product call that views > news.
+ *
+ * Phase 5.2 strategy — server-first with client-side fallback:
+ *   1. Try `GET /v1/digest/{code}` (single HTTP call, server-side fan-out;
+ *      response shape already matches the CLI envelope below).
+ *   2. If that returns 404 (endpoint not yet deployed) or `not_found`, fall
+ *      back to client-side Promise.allSettled fan-out (Phase 5.1).
+ *   3. Other errors (4xx auth, 5xx server, network) propagate normally — we
+ *      don't double-call.
+ *
+ * Either path produces the same envelope shape, so MCP / agent code is
+ * oblivious. Behavior parity is enforced by tests asserting the bucket order
+ * (views first, news last) is identical in both modes.
+ *
+ * Why these 5 ops in the fallback:
+ *   - views.recent  : PRIMARY research signal (analyst opinions on this code)
+ *   - research.entity-performance-list : quality layer for view authors
+ *   - quote         : current price / change %
+ *   - sentiment.overview : market regime context (not per-code; intentional —
+ *     no per-code sentiment op exists)
+ *   - news.search   : SUPPLEMENTARY breadth (event stream filter on code)
+ *
+ * Windows differ on purpose: views=168h (7d), news=24h. Encodes the rule
+ * that research time-horizon > news time-horizon.
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { CallApiError } from "../runtime/errors.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+/** Buckets in the order the description establishes (views first, news last). */
+const BUCKETS = ["views", "research", "quote", "sentiment", "news"];
+const CODE_REGEX = /^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/;
+export const digestSpec = {
+    name: "digest",
+    description: "One-shot research digest for a single security: fan-out across views (PRIMARY), research-entity performance, quote, market sentiment, and supplementary news. Returns separated buckets — does NOT rank views vs news for the agent. Partial failures surface in meta.partial_failures[] without poisoning successful buckets. Use as the agent's first call when asked 'what's going on with <stock>'.",
+    inputSchema: {
+        code: z
+            .string()
+            .regex(CODE_REGEX)
+            .describe("Canonical code, e.g. SSE:600519. Use `lookup` first if you only have a name."),
+        views_since_days: z
+            .number()
+            .int()
+            .min(1)
+            .max(90)
+            .default(7)
+            .describe("Lookback for views bucket (days, default 7 — research horizon)"),
+        news_hours: z
+            .number()
+            .int()
+            .min(1)
+            .max(168)
+            .default(24)
+            .describe("Lookback for news bucket (hours, default 24 — event horizon)"),
+        limit_per_bucket: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .default(10)
+            .describe("Per-bucket item cap (views/news). Quote/sentiment/research aren't paginated here."),
+    },
+    handler: async (args, ctx) => runDigest(args, ctx),
+    // Backing ops are listed in two groups: digest.get is the primary
+    // server-side endpoint we try first. The 5 fan-out ops are listed too
+    // because MCP `tools/list` should still expose `digest` for tokens that
+    // have *any* of these scopes — server-side `digest.get` exists for
+    // routing, but on tokens lacking the relevant per-bucket scopes the
+    // fan-out fallback (or server-side partial_failures) is what populates
+    // the response. Including all backing ops keeps the scope-derivation
+    // permissive; verbAvailable() returns true if any one is callable.
+    backingOps: [
+        "digest.get",
+        "views.recent",
+        "research.entity-performance-list",
+        "quote",
+        "sentiment.overview",
+        "news.search",
+    ],
+};
+/**
+ * Phase 5.2 entry: try server-side `/v1/digest/{code}` first; on 404
+ * (endpoint not yet deployed) fall back to client-side fan-out.
+ *
+ * Exported for tests.
+ */
+export async function runDigest(argsIn, ctx) {
+    const op = OPERATIONS["digest.get"];
+    if (op) {
+        try {
+            const args = argsIn;
+            const env = await callOp(op, {
+                code: args.code,
+                views_since_days: args.views_since_days,
+                news_hours: args.news_hours,
+                limit_per_bucket: args.limit_per_bucket,
+            }, ctx);
+            // Stamp meta so callers can tell which path served the response. Useful
+            // when debugging fallback decisions and when comparing latency.
+            env.meta = { ...env.meta, digest_path: "server" };
+            return env;
+        }
+        catch (e) {
+            if (e instanceof CallApiError && shouldFallbackToFanout(e)) {
+                // Server endpoint not yet rolled out on this gateway. Quietly drop
+                // to fan-out and stamp meta so observability can track this.
+                const env = await runDigestFanout(argsIn, ctx);
+                env.meta = {
+                    ...env.meta,
+                    digest_path: "fanout_fallback",
+                    fallback_reason: e.code,
+                };
+                return env;
+            }
+            throw e;
+        }
+    }
+    // Codegen pre-Phase 5.2: no server op available at all → fan-out only.
+    const env = await runDigestFanout(argsIn, ctx);
+    env.meta = { ...env.meta, digest_path: "fanout_only" };
+    return env;
+}
+/**
+ * Heuristic: when should we fall back to client-side fan-out instead of
+ * propagating the server-side error?
+ *
+ * - 404 / not_found: endpoint isn't deployed yet (rolling release window).
+ * - http_error with 404 status: same situation, no envelope returned.
+ *
+ * Auth / scope / rate-limit / 5xx upstream errors MUST propagate — those
+ * indicate problems the fan-out path will hit anyway, and silently retrying
+ * would mask them while spending 5× the upstream cost.
+ */
+function shouldFallbackToFanout(e) {
+    if (e.httpStatus === 404)
+        return true;
+    if (e.code === "not_found")
+        return true;
+    return false;
+}
+function buildBucketCalls(args, ctx) {
+    const opsRequired = {
+        views: "views.recent",
+        research: "research.entity-performance-list",
+        quote: "quote",
+        sentiment: "sentiment.overview",
+        news: "news.search",
+    };
+    const calls = [];
+    for (const bucket of BUCKETS) {
+        const opKey = opsRequired[bucket];
+        const op = OPERATIONS[opKey];
+        if (!op) {
+            // Codegen drift — surface as a failure on that bucket rather than
+            // exploding the whole digest; agent sees the gap in partial_failures.
+            calls.push({
+                bucket,
+                endpoint: opKey,
+                run: () => Promise.reject(new CallApiError({
+                    code: "internal_error",
+                    message: `Operation ${opKey} missing from codegen`,
+                })),
+            });
+            continue;
+        }
+        let opArgs;
+        switch (bucket) {
+            case "views":
+                opArgs = {
+                    security: args.code,
+                    since_days: args.views_since_days,
+                    limit: args.limit_per_bucket,
+                };
+                break;
+            case "research":
+                opArgs = {};
+                break;
+            case "quote":
+                opArgs = { codes: [args.code] };
+                break;
+            case "sentiment":
+                opArgs = { scope: "all_a_ex_st" };
+                break;
+            case "news":
+                opArgs = {
+                    query: args.code,
+                    since_hours: args.news_hours,
+                    limit: args.limit_per_bucket,
+                };
+                break;
+        }
+        calls.push({
+            bucket,
+            endpoint: op.path,
+            run: () => callOp(op, opArgs, ctx),
+        });
+    }
+    return calls;
+}
+/**
+ * Run the fan-out. Exported for tests; CLI/MCP enter via `digestSpec.handler`.
+ */
+export async function runDigestFanout(argsIn, ctx) {
+    const args = argsIn;
+    const calls = buildBucketCalls(args, ctx);
+    const results = await Promise.allSettled(calls.map((c) => c.run()));
+    const data = { code: args.code };
+    const partialFailures = [];
+    let succeeded = 0;
+    let totalDurationMs = 0;
+    let earliestRequestId;
+    results.forEach((result, idx) => {
+        const { bucket, endpoint } = calls[idx];
+        if (result.status === "fulfilled") {
+            // Strip CLI-wrapper meta and keep just data + relevant server meta.
+            // The outer digest envelope carries its own meta; per-bucket meta would
+            // be noisy. Preserve server-provided pagination/total on the bucket.
+            const env = result.value;
+            const bucketServerMeta = stripCliMeta(env.meta);
+            data[bucket] =
+                bucketServerMeta && Object.keys(bucketServerMeta).length > 0
+                    ? { data: env.data, meta: bucketServerMeta }
+                    : env.data;
+            succeeded++;
+            const d = env.meta.duration_ms;
+            if (typeof d === "number")
+                totalDurationMs = Math.max(totalDurationMs, d);
+            if (!earliestRequestId && typeof env.meta.request_id === "string") {
+                earliestRequestId = env.meta.request_id;
+            }
+        }
+        else {
+            data[bucket] = null;
+            const err = result.reason;
+            if (err instanceof CallApiError) {
+                partialFailures.push({
+                    bucket,
+                    code: err.code,
+                    message: err.message,
+                    endpoint,
+                    ...(err.requestId ? { request_id: err.requestId } : {}),
+                });
+            }
+            else {
+                partialFailures.push({
+                    bucket,
+                    code: "internal_error",
+                    message: err instanceof Error ? err.message : String(err),
+                    endpoint,
+                });
+            }
+        }
+    });
+    // If literally every bucket failed, that's not a partial-fail situation —
+    // surface it as a hard error so the agent doesn't act on an empty digest.
+    if (succeeded === 0) {
+        const first = partialFailures[0];
+        throw new CallApiError({
+            code: first?.code ?? "upstream_unavailable",
+            message: `All ${calls.length} digest sub-ops failed; first: ${first?.message ?? "unknown"}`,
+            ...(first?.request_id ? { requestId: first.request_id } : {}),
+        });
+    }
+    return {
+        data,
+        meta: {
+            endpoint: "digest (fanout)",
+            method: "FANOUT",
+            cli_version: ctx.cliVersion,
+            duration_ms: totalDurationMs,
+            truncated: false,
+            fanout_total: calls.length,
+            fanout_succeeded: succeeded,
+            partial_failures: partialFailures,
+            ...(earliestRequestId ? { request_id: earliestRequestId } : {}),
+        },
+    };
+}
+/** Drop CLI-injected meta fields; keep only server-originating keys. */
+function stripCliMeta(meta) {
+    if (!meta)
+        return undefined;
+    const drop = new Set([
+        "request_id",
+        "endpoint",
+        "method",
+        "cli_version",
+        "api_version",
+        "duration_ms",
+        "truncated",
+    ]);
+    const out = {};
+    for (const [k, v] of Object.entries(meta)) {
+        if (drop.has(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+function clamp(raw, min, max, fallback) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n))
+        return fallback;
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+export function buildDigestCommand() {
+    const cmd = new Command(digestSpec.name).description(digestSpec.description);
+    cmd.addOption(new Option("--code <canonical_code>", "Canonical code, e.g. SSE:600519")
+        .makeOptionMandatory(true));
+    cmd.addOption(new Option("--views-since-days <n>", "Views lookback in days (1-90)").default("7"));
+    cmd.addOption(new Option("--news-hours <n>", "News lookback in hours (1-168)").default("24"));
+    cmd.addOption(new Option("--limit-per-bucket <n>", "Items per bucket (1-50)").default("10"));
+    cmd.action(async (opts) => {
+        if (!CODE_REGEX.test(opts.code)) {
+            emitVerbError("invalid_args", `code ${JSON.stringify(opts.code)} is not a canonical_code (expected SSE|SZSE|BSE:NNNNNN)`, "Use `echopai lookup --text <name>` to resolve to a canonical_code first.", 1);
+        }
+        const args = {
+            code: opts.code,
+            views_since_days: clamp(opts.viewsSinceDays, 1, 90, 7),
+            news_hours: clamp(opts.newsHours, 1, 168, 24),
+            limit_per_bucket: clamp(opts.limitPerBucket, 1, 50, 10),
+        };
+        await executeVerb(async (ctx) => digestSpec.handler(args, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/hot.js

@@ -0,0 +1,29 @@
+/**
+ * `echopai hot` + MCP tool `hot`.
+ */
+import { Command } from "commander";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+export const hotSpec = {
+    name: "hot",
+    description: "Today's hot-stock leaderboard (East-Money composite rank: search / follow / comment).",
+    inputSchema: {},
+    handler: async (_args, ctx) => {
+        const op = OPERATIONS["stocks.hot"];
+        if (!op)
+            throw new Error("stocks.hot op missing");
+        return callOp(op, {}, ctx);
+    },
+    backingOps: ["stocks.hot"],
+};
+export function buildHotCommand() {
+    const cmd = new Command(hotSpec.name).description(hotSpec.description);
+    cmd.action(async () => {
+        if (!OPERATIONS["stocks.hot"]) {
+            emitVerbError("internal_error", "stocks.hot missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => hotSpec.handler({}, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/index.js

@@ -0,0 +1,49 @@
+/**
+ * Curated verb registry.
+ *
+ * Importing this module gives both:
+ *   - ALL_VERB_SPECS: 共用声明，MCP serve 枚举出 tools/list
+ *   - build*Command(): commander 端入口工厂
+ */
+export { barsBatchSpec, buildBarsBatchCommand } from "./bars_batch.js";
+export { chartSpec, buildChartCommand } from "./chart.js";
+export { digestSpec, buildDigestCommand } from "./digest.js";
+export { hotSpec, buildHotCommand } from "./hot.js";
+export { lookupSpec, buildLookupCommand } from "./lookup.js";
+export { newsSpec, buildNewsCommand } from "./news.js";
+export { quoteSpec, buildQuoteCommand } from "./quote.js";
+export { researchSpec, buildResearchCommand } from "./research.js";
+export { scanSpec, buildScanCommand } from "./scan.js";
+export { sentimentSpec, buildSentimentCommand } from "./sentiment.js";
+export { viewsSpec, buildViewsCommand } from "./views.js";
+import { barsBatchSpec } from "./bars_batch.js";
+import { chartSpec } from "./chart.js";
+import { digestSpec } from "./digest.js";
+import { hotSpec } from "./hot.js";
+import { lookupSpec } from "./lookup.js";
+import { newsSpec } from "./news.js";
+import { quoteSpec } from "./quote.js";
+import { researchSpec } from "./research.js";
+import { scanSpec } from "./scan.js";
+import { sentimentSpec } from "./sentiment.js";
+import { viewsSpec } from "./views.js";
+/**
+ * Ordering follows product priority (feedback_views_over_news.md):
+ * lookup (universal first step) → digest (one-shot fan-out, agent's opening
+ * move once it has a canonical_code) → quote → views/research (PRIMARY
+ * research) → news (supplementary) → sentiment → hot → chart → bars_batch →
+ * scan.
+ */
+export const ALL_VERB_SPECS = [
+    lookupSpec,
+    digestSpec,
+    quoteSpec,
+    viewsSpec,
+    researchSpec,
+    newsSpec,
+    sentimentSpec,
+    hotSpec,
+    chartSpec,
+    barsBatchSpec,
+    scanSpec,
+];

package/dist/verbs/lookup.js

@@ -0,0 +1,72 @@
+/**
+ * `echopai lookup --text <q> [--limit N]` + MCP tool `lookup`.
+ *
+ * Curated verb: 解析中文名 / 代码 / 拼音 → canonical_code 列表。Agent 几乎
+ * 每个会话的第一步。底层调 raw OpenAPI op `semantic.find`。
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+export function mapLookupResponse(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const r = item;
+        if (typeof r.canonical_code !== "string")
+            continue;
+        out.push({
+            canonical_code: r.canonical_code,
+            name_cn: typeof r.name_cn === "string" ? r.name_cn : "",
+            ticker: typeof r.ticker === "string" ? r.ticker : "",
+            exchange: typeof r.exchange === "string" ? r.exchange : "",
+        });
+    }
+    return out;
+}
+export const lookupSpec = {
+    name: "lookup",
+    description: "Resolve a Chinese name / A-share code / pinyin initials to canonical codes (e.g. SSE:600519). Use this first whenever the agent has a description but needs a canonical_code for downstream calls.",
+    inputSchema: {
+        text: z
+            .string()
+            .min(1)
+            .max(50)
+            .describe("Search text: Chinese name (贵州茅台), code (600519), or pinyin (gzmt)"),
+        limit: z.number().int().min(1).max(30).default(10).describe("Max matches (1-30)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["semantic.find"];
+        if (!op)
+            throw new Error("semantic.find op missing from codegen");
+        const env = await callOp(op, { query: args.text, limit: args.limit }, ctx);
+        const matches = mapLookupResponse(env.data);
+        return { data: { matches, count: matches.length }, meta: env.meta };
+    },
+    backingOps: ["semantic.find"],
+};
+function clampLimit(raw, min = 1, max = 30) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n) || n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+export function buildLookupCommand() {
+    const cmd = new Command(lookupSpec.name).description(lookupSpec.description);
+    cmd.addOption(new Option("--text <text>", "Search text (Chinese name / code / pinyin)")
+        .makeOptionMandatory(true));
+    cmd.addOption(new Option("--limit <n>", "Max matches (1-30)").default("10"));
+    cmd.action(async (opts) => {
+        if (!OPERATIONS["semantic.find"]) {
+            emitVerbError("internal_error", "semantic.find missing from codegen", undefined, 2);
+        }
+        await executeVerb(async (ctx) => lookupSpec.handler({ text: opts.text, limit: clampLimit(opts.limit) }, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/news.js

@@ -0,0 +1,67 @@
+/**
+ * `echopai news ...` + MCP tool `news`.
+ *
+ * SUPPLEMENTARY breadth source (feedback_views_over_news.md).
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+export const newsSpec = {
+    name: "news",
+    description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. With `query` → full-text search; without `query` → time-window feed.",
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe("Free-text query (Chinese or English); omit for time-window feed"),
+        hours: z
+            .number()
+            .int()
+            .min(1)
+            .max(168)
+            .default(24)
+            .describe("Lookback window in hours (default 24 — much narrower than views)"),
+        limit: z.number().int().min(1).max(100).default(20).describe("Max items"),
+    },
+    handler: async (args, ctx) => {
+        if (args.query) {
+            const op = OPERATIONS["news.search"];
+            if (!op)
+                throw new Error("news.search op missing");
+            return callOp(op, { query: args.query, since_hours: args.hours, limit: args.limit }, ctx);
+        }
+        const op = OPERATIONS["news.feed"];
+        if (!op)
+            throw new Error("news.feed op missing");
+        return callOp(op, {}, ctx);
+    },
+    backingOps: ["news.search", "news.feed"],
+};
+function clamp(raw, min, max, fallback) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n))
+        return fallback;
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+export function buildNewsCommand() {
+    const cmd = new Command(newsSpec.name).description(newsSpec.description);
+    cmd.addOption(new Option("--query <text>", "Free-text query; omit for time-window feed"));
+    cmd.addOption(new Option("--hours <n>", "Lookback window (1-168 hours)").default("24"));
+    cmd.addOption(new Option("--limit <n>", "Max items").default("20"));
+    cmd.action(async (opts) => {
+        const args = {
+            hours: clamp(opts.hours, 1, 168, 24),
+            limit: clamp(opts.limit, 1, 100, 20),
+        };
+        if (opts.query)
+            args.query = opts.query;
+        await executeVerb(async (ctx) => newsSpec.handler(args, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/quote.js

@@ -0,0 +1,53 @@
+/**
+ * `echopai quote --codes A,B,C` + MCP tool `quote`.
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { CallApiError } from "../runtime/errors.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+export const quoteSpec = {
+    name: "quote",
+    description: "Real-time quote for 1-200 A-share securities (last price, volume, change %, bid/ask). For >200 codes use `scan` instead.",
+    inputSchema: {
+        codes: z
+            .array(z.string().regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/))
+            .min(1)
+            .max(200)
+            .describe("Array of canonical codes (e.g. ['SSE:600519', 'SZSE:000001'])"),
+        include_l2: z
+            .boolean()
+            .optional()
+            .describe("Include L2 5-level order book (requires quote:l2 scope)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["quote"];
+        if (!op)
+            throw new Error("quote op missing from codegen");
+        return callOp(op, args, ctx);
+    },
+    backingOps: ["quote"],
+};
+export function buildQuoteCommand() {
+    const cmd = new Command(quoteSpec.name).description(quoteSpec.description);
+    cmd.addOption(new Option("--codes <csv>", "Canonical codes, comma-separated (e.g. SSE:600519,SZSE:000001)")
+        .makeOptionMandatory(true));
+    cmd.addOption(new Option("--include-l2", "Include L2 order book (requires quote:l2 scope)"));
+    cmd.action(async (opts) => {
+        const codes = opts.codes.split(",").map((s) => s.trim()).filter(Boolean);
+        if (codes.length === 0 || codes.length > 200) {
+            emitVerbError("invalid_args", `codes count ${codes.length} out of range; expected 1-200`, "Use `echopai scan` for full-market snapshot (>200 codes).", 1);
+        }
+        if (!OPERATIONS["quote"]) {
+            emitVerbError("internal_error", "quote op missing from codegen", undefined, 2);
+        }
+        const args = { codes };
+        if (opts.includeL2)
+            args.include_l2 = true;
+        await executeVerb(async (ctx) => quoteSpec.handler(args, ctx));
+    });
+    return cmd;
+}
+// Re-export CallApiError so handler call sites have a typed throw signature.
+export { CallApiError };

package/dist/verbs/research.js

@@ -0,0 +1,44 @@
+/**
+ * `echopai research [--entity <id>]` + MCP tool `research`.
+ *
+ * Views quality signal layer.
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+export const researchSpec = {
+    name: "research",
+    description: "Research-entity performance — hit rate / coverage / avg excess return. Pair with `views` (which returns research_entity_id per row) to assess analyst quality. Omit entity_id for aggregate top-performers list.",
+    inputSchema: {
+        entity_id: z
+            .string()
+            .optional()
+            .describe("Specific research_entity_id; omit for aggregate top-performers list"),
+    },
+    handler: async (args, ctx) => {
+        if (args.entity_id) {
+            const op = OPERATIONS["research.entity-performance"];
+            if (!op)
+                throw new Error("research.entity-performance op missing");
+            return callOp(op, { entity_id: args.entity_id }, ctx);
+        }
+        const op = OPERATIONS["research.entity-performance-list"];
+        if (!op)
+            throw new Error("research.entity-performance-list op missing");
+        return callOp(op, {}, ctx);
+    },
+    backingOps: ["research.entity-performance-list", "research.entity-performance"],
+};
+export function buildResearchCommand() {
+    const cmd = new Command(researchSpec.name).description(researchSpec.description);
+    cmd.addOption(new Option("--entity <id>", "Specific research_entity_id; omit for aggregate list"));
+    cmd.action(async (opts) => {
+        const args = {};
+        if (opts.entity)
+            args.entity_id = opts.entity;
+        await executeVerb(async (ctx) => researchSpec.handler(args, ctx));
+    });
+    return cmd;
+}