alphacouncil-agent 0.9.4 → 1.0.1

package/mcp/lib/prompts.mjs

@@ -1,11 +1,13 @@
 import { join } from "node:path";
-import { isChineseLanguage, resolveLanguage } from "./lang.mjs";
+import { isChineseLanguage, localized, resolveLanguage } from "./lang.mjs";
 import { runPath } from "./run-store.mjs";
 import { compactDebateContext, compactEvidence, compactMasterOpinions, compactQuickEvidence } from "./packets.mjs";
 import { outputModeInstruction } from "./output-modes.mjs";
 import { resolveSeatWeights, weightTableMarkdown } from "./weights.mjs";
 import { groundingBlock } from "./grounding.mjs";
+import { isFundOrIndex } from "./instruments.mjs";
 import { personaPrompt, personaTitle, registry, selectRoster } from "./personas/registry.mjs";
+import { intentsForStance } from "./voice.mjs";
 
 /**
  * Prompt text lives in personas/, not here.
@@ -22,6 +24,73 @@ function render(template, values) {
     (Object.prototype.hasOwnProperty.call(values, key) ? String(values[key] ?? "") : match));
 }
 
+function fundOrIndexTaskInstruction(task, instrument, language) {
+  if (!isFundOrIndex(instrument)) return "";
+  const type = instrument.asset_type || "fund_or_index";
+  const details = {
+    market_data: {
+      en: "Establish the tracked index or calculation methodology, holdings/constituent as-of date, weights, top-ten and sector concentration, fee or index rules, AUM where applicable, liquidity/spread, premium-discount or tracking difference, and dated flows. Separate missing fields.",
+      zh: "查清跟踪指数或计算方法、持仓/成分时点、权重、前十大和行业集中度、费率或指数规则、适用时的规模、流动性/点差、溢折价或跟踪差及带日期资金流；逐项列出缺失数据。",
+      ja: "連動指数または算出方法、保有銘柄・構成銘柄の基準日とウェイト、上位10銘柄・業種集中度、経費率または指数ルール、該当する純資産、流動性・スプレッド、乖離・トラッキング差、日付付き資金フローを確認し、欠落項目を分けて示す。",
+      ko: "추종 지수 또는 산출 방법, 보유·구성 종목 기준일과 비중, 상위 10개·섹터 집중도, 보수 또는 지수 규칙, 해당 시 AUM, 유동성·스프레드, 괴리율·추적 차이, 날짜가 있는 자금 흐름을 확인하고 누락 항목을 분리해 기록한다.",
+    },
+    earnings_deep_dive: {
+      en: "Perform holdings-level earnings look-through. State the covered portfolio weight and one-date aggregation method; keep issuer results separate. Never report fund/index revenue, EPS, cash flow, or an earnings call as though the instrument were an operating company.",
+      zh: "做持仓层盈利穿透，披露覆盖的组合权重与同日聚合方法，并分开记录各发行人结果。不得编造基金/指数自身营收、EPS、现金流或把成分公司电话会写成基金电话会。",
+      ja: "保有銘柄レベルの利益ルックスルーを行い、カバーしたポートフォリオウェイトと同一基準日の集計方法を示し、発行体ごとの結果を分離する。ファンド・指数固有の売上高、EPS、CF、決算説明会を作らない。",
+      ko: "보유 종목 수준 이익 룩스루를 수행하고 커버한 포트폴리오 비중과 동일 기준일 집계 방법을 밝히며 발행사 결과를 분리한다. 펀드·지수 자체 매출, EPS, 현금흐름 또는 실적 발표 콜을 만들지 않는다.",
+    },
+    forward_expectations: {
+      en: "Use weighted constituent or provider-published aggregate expectations with one date and a coverage percentage. Analyse top-constituent, sector, factor and macro expectation changes; never label a few issuer estimates as the fund's own guidance.",
+      zh: "只使用同一时点、披露覆盖权重的加权成分预期或指数提供方聚合预期；分析头部成分、行业、因子与宏观预期变化，不得把少数公司预测称为基金自身指引。",
+      ja: "同一基準日とカバーウェイトを示す加重構成銘柄予想または提供者公表の集計予想を使い、上位銘柄・業種・ファクター・マクロ予想の変化を分析する。一部発行体予想をファンド固有ガイダンスと呼ばない。",
+      ko: "동일 기준일과 커버 비중을 밝힌 가중 구성 종목 전망 또는 제공자 공개 집계 전망을 사용하고 상위 종목·섹터·팩터·거시 전망 변화를 분석한다. 일부 발행사 전망을 펀드 자체 가이던스로 부르지 않는다.",
+    },
+    quant_factor: {
+      en: "Measure total and relative return, breadth, factor/sector exposure, volatility, correlation, drawdown, tracking behaviour, liquidity and flows where available. Distinguish the tradable fund from the cash index and from any derivative proxy.",
+      zh: "衡量总收益与相对收益、市场广度、因子/行业暴露、波动、相关性、回撤、跟踪表现、流动性及可得的资金流；分开可交易基金、现金指数与衍生品代理。",
+      ja: "トータル・相対リターン、ブレッドス、ファクター・業種エクスポージャー、ボラティリティ、相関、ドローダウン、トラッキング、流動性、利用可能な資金フローを測り、上場ファンド、現物指数、デリバティブ代理を分ける。",
+      ko: "총수익·상대수익, 시장 폭, 팩터·섹터 노출, 변동성, 상관, 낙폭, 추적 성과, 유동성 및 가능한 자금 흐름을 측정하고 거래 펀드, 현물 지수, 파생상품 대용물을 구분한다.",
+    },
+    valuation_long_short: {
+      en: "Use same-date aggregate P/E, P/B, cash-flow yield or other portfolio metrics only with the provider/methodology and covered weight. Compare concentration and factor exposures. Never add a handful of constituent financial statements into portfolio financials.",
+      zh: "聚合 P/E、P/B、现金流收益率等组合指标必须同日、说明数据提供方/方法及覆盖权重，并比较集中度与因子暴露；不得把少数成分财报相加成组合财报。",
+      ja: "集計P/E、P/B、CF利回り等は同一基準日、提供者・方法、カバーウェイトを示し、集中度とファクターを比較する。一部構成銘柄の財務諸表を足してポートフォリオ財務にしない。",
+      ko: "집계 P/E, P/B, 현금흐름 수익률 등은 동일 기준일, 제공자·방법, 커버 비중을 밝히고 집중도와 팩터 노출을 비교한다. 일부 구성 종목 재무제표를 더해 포트폴리오 재무로 만들지 않는다.",
+    },
+    news_industry_management: {
+      en: "Cover sponsor and index-provider changes, methodology/rebalance notices, regulation and market-structure news, plus material dated news from top holdings and dominant sectors. Do not invent fund management guidance.",
+      zh: "覆盖基金管理人/指数提供方变化、方法与再平衡公告、监管和市场结构新闻，以及头部持仓和主导行业的重大带日期新闻；不得编造基金经营层指引。",
+      ja: "運用会社・指数提供者の変更、方法・リバランス通知、規制・市場構造ニュース、上位保有銘柄と主要業種の重要な日付付きニュースを扱い、ファンド経営ガイダンスを作らない。",
+      ko: "운용사·지수 제공자 변경, 방법론·리밸런싱 공지, 규제·시장 구조 뉴스와 상위 보유 종목·주요 섹터의 중요한 날짜가 있는 뉴스를 다루며 펀드 경영진 가이던스를 만들지 않는다.",
+    },
+    insider_sec: {
+      en: "Review applicable fund/index filings, prospectus and methodology changes, holdings reports, lending/derivative disclosures and sponsor conflicts. Constituent Form 4 filings are issuer activity, not fund insider trading.",
+      zh: "检查适用的基金/指数申报、招募说明书和方法变更、持仓报告、证券出借/衍生品披露及管理人冲突；成分股 Form 4 属于发行人活动，不是基金内部人交易。",
+      ja: "適用するファンド・指数届出、目論見書・方法変更、保有報告、貸株・デリバティブ開示、運用会社の利益相反を確認する。構成銘柄のForm 4は発行体の活動であり、ファンドの内部者取引ではない。",
+      ko: "적용 가능한 펀드·지수 신고, 투자설명서·방법론 변경, 보유 보고, 대차·파생상품 공시, 운용사 이해상충을 검토한다. 구성 종목 Form 4는 발행사 활동이지 펀드 내부자 거래가 아니다.",
+    },
+    ib_event_analysis: {
+      en: "Treat reconstitution, rebalances, methodology/provider changes, fee or sponsor changes, closures/mergers/splits and capital-market plumbing as instrument events. Constituent M&A matters only through explicit weight, replacement and flow effects.",
+      zh: "把指数重构/再平衡、方法或提供方变化、费率或管理人变化、清盘/合并/拆分及资本市场机制视为资产事件；成分股并购只通过明确的权重、替换与资金流影响纳入。",
+      ja: "入替・リバランス、方法・提供者変更、経費率・運用会社変更、償還・合併・分割、資本市場の仕組みを銘柄イベントとして扱う。構成銘柄M&Aは明示したウェイト、置換、フロー効果だけで反映する。",
+      ko: "지수 재구성·리밸런싱, 방법론·제공자 변경, 보수·운용사 변경, 청산·합병·분할 및 자본시장 구조를 종목 이벤트로 다룬다. 구성 종목 M&A는 명시한 비중·교체·자금 흐름 효과로만 반영한다.",
+    },
+  }[task];
+  const generic = {
+    en: "Use the fund/index research contract and record unavailable fields explicitly.",
+    zh: "使用基金/指数研究合同，并逐项记录不可得数据。",
+    ja: "ファンド・指数調査契約を使い、取得できない項目を明記する。",
+    ko: "펀드·지수 조사 계약을 사용하고 확보하지 못한 항목을 명시한다.",
+  };
+  return localized(language, {
+    en: `## ${type} task override\n${(details || generic).en}`,
+    zh: `## ${type} 专用任务改写\n${(details || generic).zh}`,
+    ja: `## ${type} 専用タスク\n${(details || generic).ja}`,
+    ko: `## ${type} 전용 작업\n${(details || generic).ko}`,
+  });
+}
+
 export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "auto", grounding = null) {
   const resolvedLanguage = resolveLanguage({ language, prompt: userPrompt });
   const chinese = isChineseLanguage(resolvedLanguage);
@@ -41,8 +110,9 @@ export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "
 
   // Grounding goes AFTER the role brief: the analyst must know its job before it is told
   // which facts are already settled, or it reads them as the whole assignment.
+  const instrumentOverride = fundOrIndexTaskInstruction(task, grounding?.instrument, resolvedLanguage);
   const grounded = groundingBlock(grounding, resolvedLanguage);
-  return [`${base}\n\n${chinese ? "任务：" : "Task: "}${task}\n${body}`, grounded].filter(Boolean).join("\n\n");
+  return [`${base}\n\n${chinese ? "任务：" : "Task: "}${task}\n${body}`, instrumentOverride, grounded].filter(Boolean).join("\n\n");
 }
 
 export function debatePrompt(role, run, context = {}) {
@@ -83,6 +153,11 @@ export function debatePrompt(role, run, context = {}) {
           ? "这是快速委员会的唯一多空陈述轮。只给最有信息量的 4–6 条论点，使用已提供来源 ID，明确回应方法席分歧；不要生成第二/第三轮问题，也不要写长报告。"
           : "This is the quick council's only bull/bear statement round. Give only the 4-6 highest-information arguments, use supplied source IDs, and engage with method-seat disagreements. Do not create round-2/3 questions or a long report.")
     : "";
+  const instrumentReportInstruction = role === "portfolio_manager" && isFundOrIndex(run?.grounding?.instrument)
+    ? (chinese
+        ? "这是ETF、基金或大盘指数研究。报告必须新增真实 Markdown 标题 `## 基金与指数结构`，明确资产类型、跟踪方法、持仓/成分权重时点、集中度、费用或指数规则、流动性/溢折价/跟踪差/资金流（适用时）、聚合盈利与估值口径，以及每项未取得的数据。不得写基金或指数自身营收/EPS，也不得把少数成分股相加成组合财报。"
+        : "This is ETF, fund or broad-index research. Add a real Markdown heading `## Fund and Index Structure` covering asset type, tracking methodology, dated holdings/constituent weights, concentration, fee or index rules, liquidity/premium-discount/tracking difference/flows when applicable, aggregate earnings and valuation methodology, and every unavailable item. Do not invent fund/index revenue or EPS and never add a few constituents into portfolio financials.")
+    : "";
 
   return [
     // The original spread the preamble's lines as separate array elements, so they are
@@ -90,6 +165,7 @@ export function debatePrompt(role, run, context = {}) {
     ...base.split("\n"),
     roleText,
     quickInstruction,
+    instrumentReportInstruction,
     roundTwoInstruction,
     roundThreeInstruction,
     context.round ? `Debate round: ${context.round}` : "",
@@ -184,7 +260,15 @@ export function masterVoicePrompt(masterId, run, frozenOpinion) {
       frozen_decision_hash: frozenOpinion?.frozen_decision_hash || null,
     })}`,
     `Method instructions (for explanation only):\n${render(personaPrompt(persona, language), values)}`,
-    "Return ONLY one valid JSON object, no Markdown fence. Schema: {\"master\":\"stable id\",\"acknowledged_stance\":\"constructive|cautious|opposed|out_of_scope\",\"statement\":\"reader-facing explanation\",\"key_findings\":[\"string\"],\"disagreements\":[\"string\"],\"what_would_change_my_mind\":[\"string\"],\"source_ids\":[\"task:S1\"],\"confidence\":\"high|medium|low\"}.",
+    [
+      "Write the five `voice` fields in the first person, as the METHOD speaks -- \"I look for X, here the number is Y, so I would Z\".",
+      "First person is the voice of the method, never a claim about what the living person currently thinks: write \"this standard asks for...\", never \"he now believes...\".",
+      "Every figure you cite must already appear in the evidence or the frozen result, with its source ID. Cite the number, not an adjective about the number.",
+      "`what_changes_my_mind` must name a threshold or an observation that would flip the reading, not a wish for more research.",
+      "If the frozen stance is out_of_scope, say plainly and in the method's own voice which input it needs and why its absence is not a bearish view.",
+    ].join(" "),
+    `\`position_intent\` MUST be one of: ${intentsForStance(frozenOpinion?.stance).join(" | ")}. Those are the only intents the frozen stance admits; anything else is rejected without changing run state.`,
+    "Return ONLY one valid JSON object, no Markdown fence. Schema: {\"master\":\"stable id\",\"acknowledged_stance\":\"constructive|cautious|opposed|out_of_scope\",\"position_intent\":\"one of the allowed intents above\",\"voice\":{\"what_i_see\":\"string\",\"how_my_method_reads_it\":\"string\",\"would_i_act\":\"string\",\"what_changes_my_mind\":\"string\",\"where_i_disagree\":\"string\"},\"key_findings\":[\"string\"],\"disagreements\":[\"string\"],\"what_would_change_my_mind\":[\"string\"],\"source_ids\":[\"task:S1\"],\"confidence\":\"high|medium|low\"}.",
     `Bounded shared evidence JSON: ${evidence}`,
   ].join("\n\n");
 }

package/mcp/lib/quotes.mjs

@@ -45,6 +45,10 @@ export function parseYahooChart(json, requested) {
     change_pct: changePct != null ? Number(changePct.toFixed(2)) : null,
     currency: meta.currency || null,
     exchange: meta.exchangeName || null,
+    instrument_type: meta.instrumentType || null,
+    short_name: meta.shortName || null,
+    long_name: meta.longName || null,
+    exchange_timezone: meta.exchangeTimezoneName || null,
     market_state: meta.marketState || null,
     quote_time: meta.regularMarketTime ? new Date(meta.regularMarketTime * 1000).toISOString() : null,
     source: "yahoo",
@@ -62,6 +66,7 @@ export function parseStooqCsv(csv, requested) {
     query: requested, symbol: cols[0] || requested, price: close,
     previous_close: null, change: null, change_pct: null,
     currency: null, exchange: "stooq", market_state: null,
+    instrument_type: null, short_name: null, long_name: null, exchange_timezone: null,
     quote_time: (cols[1] && cols[2]) ? `${cols[1]}T${cols[2]}` : null,
     source: "stooq", note: "delayed / EOD fallback, not real-time",
   };

package/mcp/lib/rpc.mjs

@@ -446,7 +446,7 @@ export function tools() {
         { required: ["selection"], not: { anyOf: [{ required: ["selected_master_ids"] }, { required: ["select_all"] }] } },
       ],
     }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }),
-    tool("plan_visible_run", "Create the visible-host-thread AlphaCouncil run after a confirmed master selection. Requires a one-time selection_receipt. Does NOT execute. You MUST then run every planned evidence agent and every selected master, record bull_researcher and bear_researcher, and only then record the portfolio_manager decision.", {
+    tool("plan_visible_run", "Create the visible-host-thread AlphaCouncil run after a confirmed master selection. Requires a one-time selection_receipt. Does NOT execute. Run every returned evidence_agent, then every returned master_agent. Physical v3 master agents explain a frozen deterministic stance and may not change it. Record all required bull/bear rounds before the portfolio_manager decision; PM rejects any returned master_agent that was not recorded.", {
       type: "object",
       properties: {
         symbol: common.symbol,
@@ -501,7 +501,7 @@ export function tools() {
       properties: common,
       required: ["symbol", "selection_receipt"],
     }),
-    tool("analyze_symbol", "Collect evidence and write a manager-style decision summary. Set council_mode=quick for the bounded news-inclusive quick_v1 path; the default remains the full council.", {
+    tool("analyze_symbol", "Research an operating company, ETF, mutual fund or market index and write a manager-style decision summary. The instrument is classified before evidence routing: funds use holdings look-through, indices use aggregate methodology, and Company Facts screens apply only to operating companies. Set council_mode=quick for the bounded news-inclusive quick_v1 path; the default remains the full council.", {
       type: "object",
       properties: {
         ...common,
@@ -543,15 +543,27 @@ export function tools() {
       type: "object",
       properties: { language: common.language },
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
-    tool("record_master_opinion", "Record one completed selected master-seat opinion into a planned visible run. Every reader-facing field must use the run language or the opinion is rejected without changing run state. Masters run AFTER every evidence packet is recorded and BEFORE the bull/bear debate, so the debate has their disagreements to argue with. A master may return stance=out_of_scope, which is a recorded conclusion rather than an abstention. Every selected seat must either report or be settled deterministically before the run can be complete.", {
+    tool("record_master_opinion", "Record one returned visible method-seat worker after evidence and before debate. For physical v3 seats, submit the method-voice schema from plan_visible_run: master, acknowledged_stance, statement, key_findings, disagreements, what_would_change_my_mind, source_ids and confidence. acknowledged_stance must equal the frozen stance; the worker cannot vote again. Legacy packets may use stance/verdict/summary. Reader-facing fields in the wrong run language are rejected without changing state. Every returned selected seat must be recorded before PM.", {
       type: "object",
       properties: {
         run_id: { type: "string" },
         master: { type: "string", enum: masterIds },
         packet: {
           type: "object",
-          description: `The master_opinion packet. stance MUST be one of ${MASTER_STANCES.join(" | ")} -- anything else is recorded as out_of_scope and carries zero weight, so a seat whose stance does not survive normalization silently stops voting. Common synonyms (long/bullish, neutral/hold, short/bearish/avoid, n/a/abstain) are mapped for you.`,
-          properties: { stance: { type: "string", enum: MASTER_STANCES } },
+          description: `Current physical v3 seats use acknowledged_stance + statement; acknowledged_stance MUST be one of ${MASTER_STANCES.join(" | ")} and match the frozen stance returned by plan_visible_run. The legacy stance/verdict/summary shape remains accepted only for a legacy seat.`,
+          properties: {
+            master: { type: "string", enum: masterIds },
+            acknowledged_stance: { type: "string", enum: MASTER_STANCES },
+            statement: { type: "string", minLength: 1 },
+            key_findings: { type: "array", items: { type: "string" } },
+            disagreements: { type: "array", items: { type: "string" } },
+            what_would_change_my_mind: { type: "array", items: { type: "string" } },
+            source_ids: { type: "array", items: { type: "string" } },
+            confidence: { type: "string", enum: ["high", "medium", "low"] },
+            stance: { type: "string", enum: MASTER_STANCES },
+            verdict: { type: "string" },
+            summary: { type: "string" },
+          },
         },
         thread_id: { type: "string" },
       },
@@ -651,7 +663,7 @@ export function tools() {
       properties: { symbols: { type: "array", items: { type: "string" } } },
       required: ["symbols"],
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
-    tool("compose_research_brief", "Assemble the hard facts BEFORE the analysts search: quote, SEC filer profile, the mechanical screen with every computed metric, macro readings, and the industry chain map. Returns both the structured data and a prompt block that tells an analyst these numbers are already established and that its search exists to explain, extend and challenge them -- with the rule that a searched number never silently overwrites a filed one. Pass the returned `grounding` object to plan_visible_run so every analyst prompt carries it.", {
+    tool("compose_research_brief", "Classify the instrument and assemble hard facts BEFORE analysts search. Operating companies may receive SEC Company Facts or local-market financials; ETFs and funds receive a holdings look-through contract; indices receive an aggregate-index contract. The result also carries quote, applicable filer profile, options/macro/industry context, explicit not-applicable routes, typed facts, and a prompt block. A searched number never silently overwrites a filed one. Pass the returned `grounding` object to plan_visible_run so every analyst prompt carries it.", {
       type: "object",
       properties: {
         symbol: common.symbol,
@@ -679,7 +691,7 @@ export function tools() {
       type: "object",
       properties: {},
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }),
-    tool("screen_ticker", "Run the mechanical elimination screen against a company's own SEC filings. No language model is involved: seven hard rules (10y ROE, 5y cumulative FCF, interest cover, gross margin, OCF/NI, net margin, dilution) with three exemptions, and every rejection names the metric, the measured value and the threshold. Rules whose inputs are missing from the filings are reported as skipped, never as passes. Surviving is not a recommendation -- it means the name is worth research time. US filers only; other markets need their own regulator feed.", {
+    tool("screen_ticker", "Run the mechanical elimination screen against an operating company's own SEC filings. It is not applicable to ETFs, funds or indices; use compose_research_brief so those instruments are classified and routed correctly. No language model is involved: seven hard rules (10y ROE, 5y cumulative FCF, interest cover, gross margin, OCF/NI, net margin, dilution) with three exemptions, and every rejection names the metric, value and threshold. Missing rules are skipped, never passes. Surviving is not a recommendation. US operating-company filers only.", {
       type: "object",
       properties: {
         cik: { type: "string", description: "SEC CIK. Use list_us_universe to resolve a ticker." },
@@ -761,7 +773,7 @@ export async function handleToolCall(id, params) {
       // no macro, and nothing in the output says so. Same reasoning as the preflight below:
       // the host that skips the optional step is exactly the host whose seats fail quietly.
       if (!run.grounding) {
-        run.grounding = await gatherGrounding({ symbol: run.symbol, asOf: run.as_of })
+        run.grounding = await gatherGrounding({ symbol: run.symbol, asOf: run.as_of, language: run.language })
           .catch((error) => ({ error: String(error?.message || error), facts_unavailable: true }));
         saveRun(run);
       }
@@ -815,6 +827,10 @@ export async function handleToolCall(id, params) {
         idempotent_replay: result.idempotent_replay === true,
         report_quality: result.report_quality?.status,
         missing_report_items: result.report_quality?.missing || [],
+        ...(args.role === "portfolio_manager" ? {
+          handoff_contract: "inline_user_response_v1",
+          user_response_markdown: result.user_response_markdown || "",
+        } : {}),
       }),
     ));
     return;
@@ -886,10 +902,11 @@ export async function handleToolCall(id, params) {
   if (name === "compose_research_brief") {
     const grounding = await gatherGrounding({
       symbol: args.symbol, cik: args.cik, industry: args.industry,
-      macro: args.macro !== false, asOf: args.as_of,
+      macro: args.macro !== false, asOf: args.as_of, language: resolveLanguage(args),
     });
     const block = groundingBlock(grounding, resolveLanguage(args));
     const facts = [
+      grounding.instrument ? `instrument (${grounding.instrument.asset_type}/${grounding.instrument.research_model})` : null,
       grounding.quote ? "quote" : null,
       grounding.filer ? "filer profile" : null,
       grounding.screen ? `screen (${grounding.screen.rules_computed}/${grounding.screen.rules_total} rules)` : null,
@@ -898,7 +915,7 @@ export async function handleToolCall(id, params) {
     ].filter(Boolean);
     sendResult(id, jsonContent(
       groundingDashboard(grounding, resolveLanguage(args)),
-      { grounding, prompt_block: block, dashboard: groundingDashboard(grounding, resolveLanguage(args)) },
+      { grounding, prompt_block: block, facts_available: facts, dashboard: groundingDashboard(grounding, resolveLanguage(args)) },
     ));
     return;
   }

package/mcp/lib/run-store.mjs

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { DEBATE_ROLES, RUNS_DIR } from "./constants.mjs";
 import { invalidParams } from "./errors.mjs";
 import { readJson, writeJson } from "./fsutil.mjs";
-import { agentState, completenessStatus, sourceManifest, taskState, verificationStatus } from "./gates.mjs";
+import { agentState, completenessStatus, masterSeatIncomplete, sourceManifest, taskState, verificationStatus } from "./gates.mjs";
 
 export { agentState, taskState };
 
@@ -52,8 +52,7 @@ export function statusSnapshot(run) {
   const verifierVerdicts = Array.isArray(run.verifier_verdicts) ? run.verifier_verdicts : [];
   const selectedMasters = Array.isArray(run.masters) ? run.masters : [];
   const recordedMasters = (run.master_opinions || []).map((opinion) => opinion.master);
-  const recordedSet = new Set(recordedMasters);
-  const pendingMasters = selectedMasters.filter((master) => !recordedSet.has(master));
+  const pendingMasters = selectedMasters.filter((master) => masterSeatIncomplete(run, master));
   const visibleDebate = run.execution_mode === "visible_host_threads" ? run.visible_debate : null;
   const visibleDebateRounds = visibleDebate
     ? Object.fromEntries(["bull_researcher", "bear_researcher"].map((role) => [
@@ -64,6 +63,9 @@ export function statusSnapshot(run) {
   return {
     run_id: run.run_id,
     symbol: run.symbol,
+    asset_type: run.grounding?.instrument?.asset_type || "unknown",
+    research_model: run.grounding?.instrument?.research_model || "unknown",
+    instrument_classification_source: run.grounding?.instrument?.classification_source || "unknown",
     as_of: run.as_of,
     language: run.language,
     execution_mode: run.execution_mode,

package/mcp/lib/sec.mjs

@@ -48,6 +48,38 @@ async function secJson(url, timeoutMs = LIMITS.QUOTE_FETCH_MS * 2, upstreamSigna
   }
 }
 
+/** Raw filing index for one registrant. Callers that need form types read this, not `fetchSubmissions`. */
+export async function fetchFilingIndex(cik, { signal } = {}) {
+  const padded = String(cik).replace(/\D/gu, "").padStart(10, "0");
+  if (padded.length !== 10) throw invalidParams(`invalid CIK: ${cik}`);
+  const data = await secJson(`https://data.sec.gov/submissions/CIK${padded}.json`, LIMITS.QUOTE_FETCH_MS * 2, signal);
+  const recent = data?.filings?.recent || {};
+  const rows = (recent.form || []).map((form, index) => ({
+    form,
+    accession: recent.accessionNumber?.[index] || null,
+    primary_document: recent.primaryDocument?.[index] || null,
+    filing_date: recent.filingDate?.[index] || null,
+    report_date: recent.reportDate?.[index] || null,
+  })).filter((row) => row.accession && row.primary_document);
+  return { cik: padded, name: data?.name || null, filings: rows };
+}
+
+/** One filing document, fetched as text. Same throttle and User-Agent as every other call. */
+export async function fetchFilingDocument(cik, accession, document, { signal } = {}) {
+  await throttle();
+  const stripped = String(cik).replace(/\D/gu, "").replace(/^0+/u, "");
+  const folder = String(accession).replace(/-/gu, "");
+  const url = `https://www.sec.gov/Archives/edgar/data/${stripped}/${folder}/${document}`;
+  const abort = linkedAbort(LIMITS.QUOTE_FETCH_MS * 2, signal);
+  try {
+    const res = await fetch(url, { signal: abort.signal, headers: { "User-Agent": UA } });
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+    return { url, text: await res.text() };
+  } finally {
+    abort.cleanup();
+  }
+}
+
 /** The full US listed universe: ~10k entries of {cik, ticker, title}. */
 export async function fetchUniverse({ signal } = {}) {
   const raw = await secJson("https://www.sec.gov/files/company_tickers.json", LIMITS.QUOTE_FETCH_MS * 2, signal);

package/mcp/lib/tables.mjs

@@ -93,6 +93,12 @@ export function groundingDashboard(g, language = "English") {
   out.push(`# ${t("Research dashboard", "研究总览")}${g.quote?.symbol ? ` — ${g.quote.symbol}` : ""}`);
 
   const facts = [];
+  if (g.instrument) facts.push([
+    t("Instrument", "资产类型"),
+    g.instrument.asset_type,
+    g.instrument.research_model,
+    g.instrument.classification_source,
+  ]);
   if (g.filer) facts.push([t("Filer", "主体"), `${g.filer.name} (SIC ${g.filer.sic ?? "?"})`, g.filer.sic_description ?? "-", "SEC"]);
   if (g.quote) {
     facts.push([t("Quote", "行情"), `${g.quote.price}${g.quote.currency ? " " + g.quote.currency : ""}`,
@@ -146,5 +152,10 @@ export function groundingDashboard(g, language = "English") {
       ...g.unavailable.map((u) => `- ${u}`));
   }
 
+  if (g.not_applicable?.length) {
+    out.push("", `**${t("Not applicable for this instrument", "本资产不适用项")}**`, "",
+      ...g.not_applicable.map((item) => `- ${item}`));
+  }
+
   return out.join("\n");
 }

package/mcp/lib/voice.mjs

@@ -0,0 +1,122 @@
+/**
+ * The reader-facing shape of a method seat's statement.
+ *
+ * A frozen stance plus a paragraph of machine diagnostics is technically complete and
+ * practically useless: "master_buffett: no_required_fact_types_present" tells a reader that
+ * something broke, not what the method concluded. This module defines the five things a
+ * reader actually wants -- what the method saw, how its own standard reads that, whether it
+ * would act, what would change it, and where it disagrees with the room -- and the vocabulary
+ * for the one field that expresses intent.
+ *
+ * The stance stays frozen and deterministic. Intent is a NARROWING of the stance, never a
+ * second vote: each stance admits only intents that mean the same thing, so a worker can pick
+ * the honest shade without being able to convert an `opposed` into a `would_buy`.
+ */
+
+import { localized } from "./lang.mjs";
+
+export const POSITION_INTENTS = Object.freeze([
+  "would_buy",
+  "would_add",
+  "would_hold",
+  "would_watch",
+  "would_pass",
+  "would_avoid",
+  "not_in_my_circle",
+]);
+
+/**
+ * Which intents each frozen stance admits. Enforced server-side on the way in, exactly like
+ * the acknowledged-stance check, so a persuasive narrative cannot widen its own mandate.
+ */
+const INTENTS_BY_STANCE = Object.freeze({
+  constructive: Object.freeze(["would_buy", "would_add"]),
+  cautious: Object.freeze(["would_hold", "would_watch"]),
+  opposed: Object.freeze(["would_pass", "would_avoid"]),
+  out_of_scope: Object.freeze(["not_in_my_circle"]),
+});
+
+export function intentsForStance(stance) {
+  return INTENTS_BY_STANCE[String(stance || "")] || INTENTS_BY_STANCE.out_of_scope;
+}
+
+export function defaultIntentForStance(stance) {
+  return intentsForStance(stance)[0];
+}
+
+export function isIntentAllowed(intent, stance) {
+  return intentsForStance(stance).includes(String(intent || ""));
+}
+
+/** The five reader-facing fields, in the order a reader wants them. */
+export const VOICE_FIELDS = Object.freeze([
+  "what_i_see",
+  "how_my_method_reads_it",
+  "would_i_act",
+  "what_changes_my_mind",
+  "where_i_disagree",
+]);
+
+const FIELD_LABELS = Object.freeze({
+  what_i_see: { en: "What I see", zh: "我看到的", ja: "私が見ているもの", ko: "내가 보는 것" },
+  how_my_method_reads_it: {
+    en: "How my standard reads it", zh: "用我的标准怎么看", ja: "私の基準での読み方", ko: "내 기준으로 본 해석",
+  },
+  would_i_act: { en: "Would I act", zh: "我会不会动手", ja: "私なら動くか", ko: "나라면 움직이는가" },
+  what_changes_my_mind: {
+    en: "What would change my mind", zh: "什么会让我改主意", ja: "何があれば考えを変えるか", ko: "무엇이 내 생각을 바꾸는가",
+  },
+  where_i_disagree: { en: "Where I disagree", zh: "我和谁分歧", ja: "どこで意見が分かれるか", ko: "어디서 의견이 갈리는가" },
+});
+
+export function voiceFieldLabel(field, language) {
+  return localized(language, FIELD_LABELS[field] || {}) || field;
+}
+
+const INTENT_LABELS = Object.freeze({
+  would_buy: { en: "would buy", zh: "会买", ja: "買う", ko: "매수한다" },
+  would_add: { en: "would add", zh: "会加仓", ja: "買い増す", ko: "추가 매수한다" },
+  would_hold: { en: "would hold", zh: "会持有", ja: "保有する", ko: "보유한다" },
+  would_watch: { en: "would watch", zh: "会观望", ja: "様子を見る", ko: "지켜본다" },
+  would_pass: { en: "would pass", zh: "会放弃", ja: "見送る", ko: "보류한다" },
+  would_avoid: { en: "would avoid", zh: "会回避", ja: "回避する", ko: "회피한다" },
+  not_in_my_circle: {
+    en: "outside my circle of competence",
+    zh: "在我的能力圈之外",
+    ja: "私の能力の輪の外",
+    ko: "내 능력 범위 밖",
+  },
+});
+
+export function intentLabel(intent, language) {
+  return localized(language, INTENT_LABELS[intent] || {}) || intent;
+}
+
+/**
+ * The disclaimer that must accompany first-person method prose.
+ *
+ * First person is what makes the output readable, and it is also exactly what could be
+ * mistaken for a quotation. The wording is deliberate: it describes what the METHOD concludes,
+ * and never asserts what the living person currently thinks.
+ */
+export function voiceDisclaimer(language) {
+  return localized(language, {
+    en: "First-person reasoning by a project-derived method model. Not a quotation, endorsement, or current view of the named person.",
+    zh: "以下为项目派生方法模型的第一人称推演，非本人言论、授权或当前观点。",
+    ja: "以下はプロジェクト由来のメソッドモデルによる一人称の推論です。本人の発言・承認・現在の見解ではありません。",
+    ko: "아래는 프로젝트 파생 방법론 모델의 1인칭 추론입니다. 본인의 발언·승인·현재 견해가 아닙니다.",
+  });
+}
+
+/**
+ * Compose the five fields into one continuous statement for surfaces that carry a single
+ * line per seat. Empty fields are dropped rather than rendered as an empty heading.
+ */
+export function composeVoiceStatement(voice, language) {
+  if (!voice || typeof voice !== "object") return "";
+  return VOICE_FIELDS
+    .map((field) => [field, String(voice[field] ?? "").trim()])
+    .filter(([, text]) => text.length > 0)
+    .map(([field, text]) => `${voiceFieldLabel(field, language)}: ${text}`)
+    .join(" ");
+}