alphacouncil-agent 0.5.0

package/mcp/lib/output-modes.mjs

@@ -0,0 +1,144 @@
+import { OUTPUT_MODES } from "./constants.mjs";
+import { isChineseLanguage } from "./lang.mjs";
+
+/**
+ * The output shapes the portfolio manager can target.
+ *
+ * best_for/effect used to be Chinese-only strings that outputModeInstruction interpolated
+ * straight into English PM prompts, so an English run received two lines of Chinese
+ * instructions. They are per-language now.
+ *
+ * The former product_design / creative_production / sales modes described themselves as
+ * "not for investment summary" and have been removed. Unknown values still fall back to
+ * public_equity, so a host that passes an old name degrades instead of erroring.
+ */
+export function summaryModes(language = "English") {
+  const zh = isChineseLanguage(language);
+  const pick = (pair) => (zh ? pair.zh : pair.en);
+  return MODES.map((mode) => ({
+    mode: mode.mode,
+    best_for: pick(mode.best_for),
+    effect: pick(mode.effect),
+    fit: mode.fit,
+  }));
+}
+
+const MODES = [
+  {
+    mode: "chat",
+    best_for: {
+      zh: "默认最终答复、快速判断、直接复制到聊天窗口。",
+      en: "Default final reply, quick judgment, paste straight into chat.",
+    },
+    effect: {
+      zh: "聊天里给不冗长但完整的交付摘要；完整报告必须写入 final_report.md，并覆盖新闻、财报、前瞻、估值、风险和文件位置。",
+      en: "A short but complete handoff in chat; the full report still goes to final_report.md and must cover news, earnings, forward thresholds, valuation, risks, and file locations.",
+    },
+    fit: "best_default",
+  },
+  {
+    mode: "documents",
+    best_for: {
+      zh: "正式投资备忘录、IC memo、可继续编辑的 Word/Google Docs 文档。",
+      en: "Formal investment memos, IC memos, editable Word/Google Docs deliverables.",
+    },
+    effect: {
+      zh: "更像严肃 memo：封面信息、执行摘要、论证、来源附录、风险和反证条件。",
+      en: "Reads like a serious memo: cover details, executive summary, argument, source appendix, risks, and invalidation conditions.",
+    },
+    fit: "best_formal_memo",
+  },
+  {
+    mode: "pdf",
+    best_for: {
+      zh: "只读交付、归档、对外发送、版式固定的正式报告。",
+      en: "Read-only delivery, archiving, external distribution, fixed-layout reports.",
+    },
+    effect: {
+      zh: "内容应先按报告写好，再渲染为 PDF；适合最终版，不适合迭代。",
+      en: "Write the report first, then render to PDF. Good for a final version, poor for iteration.",
+    },
+    fit: "best_locked_report",
+  },
+  {
+    mode: "presentations",
+    best_for: {
+      zh: "投资委员会汇报、pitch deck、老板快速看结论。",
+      en: "Investment-committee readouts, pitch decks, a fast look at the conclusion.",
+    },
+    effect: {
+      zh: "8-10 页 slide outline：结论页、多头页、空头页、估值页、催化剂页、风险页、仓位页。",
+      en: "An 8-10 slide outline: conclusion, long case, short case, valuation, catalysts, risks, position.",
+    },
+    fit: "best_committee_deck",
+  },
+  {
+    mode: "data_analytics",
+    best_for: {
+      zh: "指标表、KPI、估值敏感性、可视化 dashboard。",
+      en: "Metric tables, KPIs, valuation sensitivity, dashboard visuals.",
+    },
+    effect: {
+      zh: "适合把 revenue、margin、multiple、scenario 做成表和图；不适合单独写最终投资判断。",
+      en: "Good for turning revenue, margin, multiple and scenario work into tables and charts; not a substitute for the investment judgment itself.",
+    },
+    fit: "supporting_analytics",
+  },
+  {
+    mode: "public_equity",
+    best_for: {
+      zh: "上市股票 long/short、财报、估值、催化剂、仓位建议。",
+      en: "Listed-equity long/short, earnings, valuation, catalysts, position sizing.",
+    },
+    effect: {
+      zh: "最适合作为研究子代理和最终 PM memo 的核心材料。",
+      en: "The best fit for both the research subagents and the final PM memo.",
+    },
+    fit: "best_research_brain",
+  },
+  {
+    mode: "investment_banking",
+    best_for: {
+      zh: "增发、并购、融资、稀释、accretion/dilution、交易影响。",
+      en: "Offerings, M&A, financing, dilution, accretion/dilution, transaction impact.",
+    },
+    effect: {
+      zh: "适合写交易事件章节；没有活跃交易时不应让它主导最终结论。",
+      en: "Good for the transaction-event section; it should not drive the final conclusion when there is no live transaction.",
+    },
+    fit: "event_specialist",
+  },
+];
+
+export function outputModeInstruction(mode, language = "English") {
+  const selected = OUTPUT_MODES.includes(mode) ? mode : "public_equity";
+  const picked = summaryModes(language).find((item) => item.mode === selected);
+  const chinese = isChineseLanguage(language);
+  return [
+    chinese ? "最终报告语言：中文。" : `Final report language: ${language}.`,
+    `Final output mode: ${selected}.`,
+    `Mode purpose: ${picked?.best_for || ""}`,
+    `Mode effect: ${picked?.effect || ""}`,
+    chinese
+      ? "report_markdown 必须是完整正文，不是运行说明。必须覆盖 report contract 的所有章节，尤其新闻、最新财报、前瞻门槛、卖方修正、估值、风险、仓位、数据缺口和来源表。聊天摘要可以简洁，但 final_report.md 不得偷懒。"
+      : "report_markdown must be the complete report body, not an execution note. It must cover every report-contract section, especially news, latest earnings, forward thresholds, sell-side revisions, valuation, risks, position sizing, data gaps, and source table. The chat handoff may be concise; final_report.md must not be lazy.",
+    selected === "presentations"
+      ? "In report_markdown, write a slide-by-slide outline with slide titles and concise bullets, not dense prose."
+      : "",
+    selected === "documents"
+      ? "In report_markdown, write a formal investment memo suitable for DOCX conversion: title, executive summary, recommendation, evidence, risks, source appendix."
+      : "",
+    selected === "pdf"
+      ? "In report_markdown, write a polished locked-report structure with page-ready headings, source table, and concise executive summary."
+      : "",
+    selected === "data_analytics"
+      ? "In report_markdown, emphasize tables, chart specs, metrics, scenario sensitivity, and dashboard-ready fields."
+      : "",
+    selected === "public_equity"
+      ? "In report_markdown, write like a Public Equity Investing memo-builder final output: Recommendation / Decision Ask, Executive Summary, Thesis and Evidence, What Must Be True, Valuation / Scenario Work, Risks and Disconfirmers, Catalysts and Monitoring, Short / Medium / Long-Term View, Implementation Considerations, Open Items, and Source Table. Make it read like a PM-facing equity research report, not a generic chatbot answer."
+      : "",
+    selected === "investment_banking"
+      ? "In report_markdown, write the final synthesis like a banker event-analysis section only when transaction evidence exists: transaction overview, dilution/accretion, EPS/share-count impact, net cash/debt, valuation multiple, stock-pressure implications, and deal risks. If there is no live transaction, state that Investment Banking is supporting context rather than the final owner."
+      : "",
+  ].filter(Boolean).join("\n");
+}

package/mcp/lib/packets.mjs

@@ -0,0 +1,256 @@
+import { join } from "node:path";
+import { LIMITS, MASTER_STANCES, RATINGS } from "./constants.mjs";
+import { internalError } from "./errors.mjs";
+import { isChineseLanguage } from "./lang.mjs";
+import { cleanLog, clip } from "./text.mjs";
+import { scopedSourceId } from "./gates.mjs";
+import { runPath } from "./run-store.mjs";
+import { packetSummary } from "./markdown.mjs";
+
+export function rawRecordText(packet) {
+  if (typeof packet?.raw_text === "string" && packet.raw_text.trim()) return packet.raw_text;
+  if (!packet || typeof packet !== "object" || Array.isArray(packet)) return JSON.stringify(packet || {}, null, 2);
+  const { raw_text, ...withoutRawText } = packet;
+  return JSON.stringify(withoutRawText, null, 2);
+}
+
+export function extractJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start !== -1 && end > start) {
+      return JSON.parse(text.slice(start, end + 1));
+    }
+    throw internalError("subagent did not return JSON");
+  }
+}
+
+export function normalizePacket(packet, task, symbol, asOfDate, raw = "") {
+  const sourceIdMap = new Map();
+  const sources = Array.isArray(packet?.sources) ? packet.sources.map((source, index) => {
+    const original = String(source?.id || `S${index + 1}`);
+    const id = scopedSourceId(task, original, index);
+    sourceIdMap.set(original, id);
+    return { ...(source && typeof source === "object" ? source : {}), id };
+  }) : [];
+  const claims = Array.isArray(packet?.claims) ? packet.claims.map((claim) => ({
+    ...(claim && typeof claim === "object" ? claim : {}),
+    source_ids: Array.isArray(claim?.source_ids)
+      ? claim.source_ids.map((id) => sourceIdMap.get(String(id)) || scopedSourceId(task, id)).filter(Boolean)
+      : [],
+  })) : [];
+  return {
+    task,
+    symbol,
+    as_of: asOfDate,
+    summary: typeof packet?.summary === "string" ? packet.summary : raw.slice(0, LIMITS.CLEAN_LOG_BYTES),
+    claims,
+    metrics: packet?.metrics && typeof packet.metrics === "object" ? packet.metrics : {},
+    sources,
+    open_questions: Array.isArray(packet?.open_questions) ? packet.open_questions : [],
+    confidence: ["high", "medium", "low"].includes(packet?.confidence) ? packet.confidence : "low",
+    // How much material this task actually had. Deliberately separate from confidence:
+    // a rich-but-contradictory task can be A/low, a sparse-but-decisive one C/high.
+    information_richness: ["A", "B", "C"].includes(packet?.information_richness) ? packet.information_richness : "unrated",
+    thread_id: typeof packet?.thread_id === "string" ? packet.thread_id : undefined,
+    thread_title: typeof packet?.thread_title === "string" ? packet.thread_title : undefined,
+    execution_mode: typeof packet?.execution_mode === "string" ? packet.execution_mode : undefined,
+    raw_text: raw,
+  };
+}
+
+export function normalizeDebate(packet, role, run, raw = "") {
+  return {
+    role,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    verdict: typeof packet?.verdict === "string" ? packet.verdict : "",
+    rating: RATINGS.includes(packet?.rating) ? packet.rating : "Hold",
+    winner: ["bull", "bear", "balanced", "unknown"].includes(packet?.winner) ? packet.winner : "unknown",
+    summary: typeof packet?.summary === "string" ? packet.summary : raw.slice(0, LIMITS.CLEAN_LOG_BYTES),
+    long_thesis: Array.isArray(packet?.long_thesis) ? packet.long_thesis : [],
+    short_thesis: Array.isArray(packet?.short_thesis) ? packet.short_thesis : [],
+    valuation_range: typeof packet?.valuation_range === "string" ? packet.valuation_range : "",
+    catalysts: Array.isArray(packet?.catalysts) ? packet.catalysts : [],
+    risks: Array.isArray(packet?.risks) ? packet.risks : [],
+    position: typeof packet?.position === "string" ? packet.position : "",
+    invalidation: Array.isArray(packet?.invalidation) ? packet.invalidation : [],
+    source_ids: Array.isArray(packet?.source_ids) ? packet.source_ids : [],
+    confidence: ["high", "medium", "low"].includes(packet?.confidence) ? packet.confidence : "low",
+    questions: Array.isArray(packet?.questions) ? packet.questions : [],
+    questions_answered: Array.isArray(packet?.questions_answered) ? packet.questions_answered : [],
+    debate_rounds: Array.isArray(packet?.debate_rounds) ? packet.debate_rounds : [],
+    report_markdown: typeof packet?.report_markdown === "string" ? packet.report_markdown : "",
+    thread_id: typeof packet?.thread_id === "string" ? packet.thread_id : undefined,
+    thread_title: typeof packet?.thread_title === "string" ? packet.thread_title : undefined,
+    execution_mode: typeof packet?.execution_mode === "string" ? packet.execution_mode : undefined,
+    raw_text: raw,
+  };
+}
+
+export function dryPacket(task, symbol, asOfDate, prompt, language = "English") {
+  const chinese = isChineseLanguage(language);
+  return normalizePacket({
+    summary: chinese ? `已计划 ${symbol} 的 ${task} 子代理。` : `Planned ${task} subagent for ${symbol}.`,
+    claims: [{
+      claim: chinese ? "仅 dry run；没有执行外部研究。" : "Dry run only; no external research executed.",
+      evidence: chinese ? "生成的 prompt 已保存在 raw_text。" : "The generated prompt is stored in raw_text.",
+      confidence: "low",
+      source_ids: [],
+    }],
+    open_questions: [chinese ? "不要传 dry_run，或传 dry_run=false，即可执行 Codex 子代理。" : "Run again without dry_run, or with dry_run=false, to execute Codex subagents."],
+    confidence: "low",
+  }, task, symbol, asOfDate, prompt);
+}
+
+export function dryDebate(role, run, prompt) {
+  const chinese = isChineseLanguage(run.language);
+  return normalizeDebate({
+    verdict: "DRY_RUN",
+    rating: "Hold",
+    winner: "unknown",
+    summary: chinese ? `已计划 ${run.symbol} 的 ${role} 综合。` : `Planned ${role} synthesis for ${run.symbol}.`,
+    confidence: "low",
+    report_markdown: chinese ? `# ${run.symbol} ${role}\n\n仅 dry run。\n` : `# ${run.symbol} ${role}\n\nDry run only.\n`,
+  }, role, run, prompt);
+}
+
+export function compactEvidence(run) {
+  return {
+    run_id: run.run_id,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    packets: run.packets.map((packet) => ({
+      task: packet.task,
+      summary: packet.summary,
+      claims: packet.claims,
+      metrics: packet.metrics,
+      sources: packet.sources,
+      open_questions: packet.open_questions,
+      confidence: packet.confidence,
+    })),
+  };
+}
+
+export function debateFromCodex(result, role, run, fallbackPrompt) {
+  if (!result.ok) return dryDebate(role, run, cleanLog(result.stderr || result.text || fallbackPrompt));
+  try {
+    return normalizeDebate(extractJson(result.text), role, run, result.text);
+  } catch {
+    return normalizeDebate({
+      verdict: "PARSE_FAILED",
+      rating: "Hold",
+      winner: "unknown",
+      summary: `${role} returned non-JSON output.`,
+      confidence: "low",
+      report_markdown: cleanLog(result.text),
+    }, role, run, cleanLog(result.text));
+  }
+}
+
+export function mergeDebateRounds(rounds) {
+  const list = (rounds || []).filter(Boolean);
+  if (list.length === 0) return null;
+  const base = list[list.length - 1];
+  const debate_rounds = list.map((packet, index) => ({
+    round: index + 1,
+    summary: packet.summary || "",
+    long_thesis: packet.long_thesis || [],
+    short_thesis: packet.short_thesis || [],
+    questions: packet.questions || [],
+    questions_answered: packet.questions_answered || [],
+    raw_text: packet.raw_text || "",
+  }));
+  return { ...base, debate_rounds };
+}
+
+export function confidenceScore(value) {
+  return ({ high: 3, medium: 2, low: 1 })[value] || 1;
+}
+
+export function summarizeRun(run, userPrompt = "") {
+  const claims = run.packets.flatMap((packet) =>
+    packet.claims.map((claim) => ({ ...claim, task: packet.task, packet_confidence: packet.confidence }))
+  );
+  const avg = run.packets.reduce((sum, packet) => sum + confidenceScore(packet.confidence), 0) / Math.max(1, run.packets.length);
+  const confidence = avg >= 2.5 ? "high" : avg >= 1.7 ? "medium" : "low";
+  return {
+    run_id: run.run_id,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    objective: userPrompt,
+    final_decision: run.dry_run ? "DRY_RUN" : "NEEDS_MANAGER_REVIEW",
+    confidence,
+    thesis: claims.slice(0, 12),
+    open_questions: [...new Set(run.packets.flatMap((packet) => packet.open_questions || []))],
+    source_count: run.packets.reduce((sum, packet) => sum + (packet.sources?.length || 0), 0),
+    evidence_path: join(runPath(run.run_id), "evidence.json"),
+  };
+}
+
+export function managerFallback(run, userPrompt = "") {
+  const summary = summarizeRun(run, userPrompt);
+  const chinese = isChineseLanguage(run.language);
+  const analystLog = run.packets.length
+    ? run.packets.map((packet) => {
+        const claims = (packet.claims || []).slice(0, 5).map((claim) => `  - ${claim.claim}`).join("\n");
+        const gaps = (packet.open_questions || []).slice(0, 3).map((item) => `  - ${item}`).join("\n");
+        return `### ${packet.task}\n- Confidence: ${packet.confidence || "unknown"}\n- Summary: ${packet.summary || "None"}\n${claims ? `- Key findings:\n${claims}\n` : ""}${gaps ? `- Data gaps:\n${gaps}\n` : ""}`;
+      }).join("\n\n")
+    : (chinese ? "未生成 evidence packets。" : "No evidence packets were generated.");
+  const debateRecord = chinese
+    ? "经理综合子代理未完成，因此没有完整多空交叉辩论记录；以上证据只能作为投资委员会初稿。"
+    : "The manager synthesis subagent did not complete, so a full bull/bear cross-debate record is unavailable; the evidence above is only an investment-committee draft.";
+  return normalizeDebate({
+    verdict: summary.final_decision,
+    rating: "Hold",
+    winner: "unknown",
+    summary: chinese ? "证据已收集，但未运行经理综合子代理。" : "Evidence was collected, but the manager synthesis subagent did not run.",
+    long_thesis: summary.thesis.filter((claim) => claim.confidence !== "low").slice(0, 6).map((claim) => claim.claim),
+    short_thesis: summary.open_questions.slice(0, 6),
+    confidence: summary.confidence,
+    report_markdown: chinese
+      ? `# ${run.symbol} 投资委员会初稿\n\n## 结论\n${summary.final_decision}\n\n## 分析师工作记录\n${analystLog}\n\n## 多空辩论记录\n${debateRecord}\n\n## 多头观点\n${summary.thesis.filter((claim) => claim.confidence !== "low").slice(0, 6).map((claim) => `- ${claim.claim}`).join("\n") || "- 本轮没有可用多头论点。"}\n\n## 空头观点\n${summary.open_questions.slice(0, 6).map((item) => `- ${item}`).join("\n") || "- 本轮没有可用空头论点。"}\n\n## 市场预期与隐含门槛\n${clip(packetSummary(run, "forward_expectations"), 900) || "- 本轮没有前瞻预期证据。"}\n\n## 分析师评级/目标价变化\n${clip(packetSummary(run, "sell_side_revisions"), 900) || "- 本轮没有卖方修正证据。"}\n\n## 电话会管理层信号\n${clip(packetSummary(run, "earnings_call_transcript"), 900) || "- 本轮没有电话会证据。"}\n\n## 量化/因子视角\n${clip(packetSummary(run, "quant_factor"), 900) || "- 本轮没有量化因子证据。"}\n\n## 新闻和公司/行业人物发言信号\n${clip([packetSummary(run, "news_industry_management"), packetSummary(run, "management_industry_voices")].filter(Boolean).join("\n"), 1200) || "- 本轮没有新闻或人物发言证据。"}\n\n## short interest / borrow / options 信息\n${clip(packetSummary(run, "quant_factor"), 700) || "- 本轮没有 short interest / borrow / options 数据。"}\n\n## 战略交易 / 银行事件\n${clip(packetSummary(run, "ib_event_analysis"), 900) || "- 本轮没有交易事件证据。"}\n\n## 估值区间\n${clip(packetSummary(run, "valuation_long_short"), 900) || "- 本轮没有估值证据。"}\n\n## 价位参考\n- 经理综合未完成，无法给出价格条件表。需要：估值区间、最差年份盈利、历史估值分位。\n\n## 关键催化剂\n- 等待 portfolio_manager 完整综合。\n\n## 主要风险\n${summary.open_questions.slice(0, 6).map((item) => `- ${item}`).join("\n") || "- 暂未发现额外风险。"}\n\n## 仓位建议\n- 经理综合未完成前仅作为初稿，不给正式仓位。\n\n## 短线 1-4 周判断\n- 需等待完整经理综合。\n\n## 中期 3-6 个月判断\n- 需等待完整经理综合。\n\n## 长期 12 个月判断\n- 需等待完整经理综合。\n\n## 数据缺口/未覆盖项\n${summary.open_questions.length ? summary.open_questions.map((item) => `- ${item}`).join("\n") : "- 未发现关键数据缺口。"}\n\n## 反证条件\n- 若证据来源缺失或完整经理综合失败，本初稿不能作为正式结论。\n\n## 置信度\n${summary.confidence}\n\n## 来源表\n- 来源数量: ${summary.source_count}\n`
+      : `# ${run.symbol} Investment Committee Draft\n\n## Conclusion\n${summary.final_decision}\n\n## Analyst Work Log\n${analystLog}\n\n## Bull/Bear Debate Record\n${debateRecord}\n\n## Long Thesis\n${summary.thesis.filter((claim) => claim.confidence !== "low").slice(0, 6).map((claim) => `- ${claim.claim}`).join("\n") || "- No usable long thesis yet."}\n\n## Short Thesis\n${summary.open_questions.slice(0, 6).map((item) => `- ${item}`).join("\n") || "- No usable short thesis yet."}\n\n## Market Expectations and Implied Thresholds\n${clip(packetSummary(run, "forward_expectations"), 900) || "- No forward-expectations evidence in this run."}\n\n## Analyst Rating and Target-Price Revisions\n${clip(packetSummary(run, "sell_side_revisions"), 900) || "- No sell-side revision evidence in this run."}\n\n## Earnings Call Management Signals\n${clip(packetSummary(run, "earnings_call_transcript"), 900) || "- No earnings-call evidence in this run."}\n\n## Quant Factor / Technical Risk View\n${clip(packetSummary(run, "quant_factor"), 900) || "- No quant-factor evidence in this run."}\n\n## News and Company / Industry Voice Signals\n${clip([packetSummary(run, "news_industry_management"), packetSummary(run, "management_industry_voices")].filter(Boolean).join("\n"), 1200) || "- No news or voice evidence in this run."}\n\n## Short Interest / Borrow / Options Information\n${clip(packetSummary(run, "quant_factor"), 700) || "- No short interest / borrow / options data in this run."}\n\n## Strategic Transaction or Banking Event\n${clip(packetSummary(run, "ib_event_analysis"), 900) || "- No transaction evidence in this run."}\n\n## Valuation Range\n${clip(packetSummary(run, "valuation_long_short"), 900) || "- No valuation evidence in this run."}\n\n## Price Levels\n- Manager synthesis did not complete, so no price-condition table can be given. Needed: a valuation range, worst-year earnings, and the historical valuation percentile.\n\n## Key Catalysts\n- Wait for completed portfolio-manager synthesis.\n\n## Major Risks\n${summary.open_questions.slice(0, 6).map((item) => `- ${item}`).join("\n") || "- No additional risks surfaced yet."}\n\n## Position Recommendation\n- Draft only; no formal position before completed manager synthesis.\n\n## Short-Term 1-4 Week View\n- Requires completed manager synthesis.\n\n## Medium-Term 3-6 Month View\n- Requires completed manager synthesis.\n\n## Long-Term 12 Month View\n- Requires completed manager synthesis.\n\n## Data Gaps / Unavailable Data\n${summary.open_questions.length ? summary.open_questions.map((item) => `- ${item}`).join("\n") : "- No critical data gaps were found."}\n\n## Invalidation Conditions\n- If evidence sources are missing or manager synthesis fails, this draft cannot stand as the final decision.\n\n## Confidence\n${summary.confidence}\n\n## Source Table\n- Source count: ${summary.source_count}\n`,
+  }, "portfolio_manager", run);
+}
+
+/**
+ * A master's opinion. Deliberately NOT a debate packet: a master issues no rating and
+ * declares no winner. out_of_scope is a first-class stance -- "by my method this name is
+ * outside what I can judge" is a conclusion, not an abstention.
+ */
+export function normalizeMasterOpinion(packet, masterId, run, raw = "") {
+  const list = (value) => (Array.isArray(value) ? value.filter((x) => typeof x === "string") : []);
+  return {
+    master: masterId,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    verdict: typeof packet?.verdict === "string" ? packet.verdict : "",
+    stance: MASTER_STANCES.includes(packet?.stance) ? packet.stance : "cautious",
+    summary: typeof packet?.summary === "string" ? packet.summary : raw.slice(0, LIMITS.CLEAN_LOG_BYTES),
+    key_findings: list(packet?.key_findings),
+    disagreements: list(packet?.disagreements),
+    disqualifiers_triggered: list(packet?.disqualifiers_triggered),
+    what_would_change_my_mind: list(packet?.what_would_change_my_mind),
+    source_ids: list(packet?.source_ids),
+    confidence: ["high", "medium", "low"].includes(packet?.confidence) ? packet.confidence : "low",
+    thread_id: typeof packet?.thread_id === "string" ? packet.thread_id : undefined,
+    raw_text: raw,
+  };
+}
+
+/** Compact master opinions for injection into the debate prompt. */
+export function compactMasterOpinions(run) {
+  return (run.master_opinions || []).map((opinion) => ({
+    master: opinion.master,
+    stance: opinion.stance,
+    verdict: opinion.verdict,
+    key_findings: opinion.key_findings,
+    disagreements: opinion.disagreements,
+    disqualifiers_triggered: opinion.disqualifiers_triggered,
+    confidence: opinion.confidence,
+  }));
+}

package/mcp/lib/personas/frontmatter.mjs

@@ -0,0 +1,80 @@
+/**
+ * Persona file format: a `---json` fenced frontmatter block, then a body split into
+ * language sections by `<!-- lang:xx -->` markers.
+ *
+ * JSON rather than YAML because this repo has no dependencies and a hand-rolled YAML
+ * subset parser mis-parses things like `description: Buy: or Sell` silently, producing a
+ * wrong prompt with no error. JSON.parse is exact and fails loudly with a position.
+ * Persona files are source data; the generator emits real YAML frontmatter for the host
+ * surfaces, and serializing a known key set is safe in a way parsing arbitrary YAML is not.
+ *
+ * `<!-- lang:xx -->` rather than `## zh` because persona bodies legitimately contain `##`
+ * headings, an HTML comment can never collide, and GitHub renders it as nothing.
+ */
+
+const FRONTMATTER = /^---json\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/;
+const LANG_MARKER = /^<!--\s*lang:\s*([a-z]{2}(?:-[a-z]{2})?)\s*-->\s*$/i;
+
+export function parsePersonaFile(text, file = "<persona>") {
+  const match = FRONTMATTER.exec(String(text ?? ""));
+  if (!match) throw new Error(`${file}: missing ---json frontmatter block`);
+
+  let meta;
+  try {
+    meta = JSON.parse(match[1]);
+  } catch (error) {
+    throw new Error(`${file}: frontmatter is not valid JSON: ${error.message}`);
+  }
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    throw new Error(`${file}: frontmatter must be a JSON object`);
+  }
+
+  const bodies = {};
+  let current = null;
+  let sawMarker = false;
+  const preamble = [];
+  for (const line of String(text).slice(match[0].length).split(/\r?\n/)) {
+    const marker = LANG_MARKER.exec(line);
+    if (marker) {
+      sawMarker = true;
+      current = marker[1].toLowerCase();
+      if (!bodies[current]) bodies[current] = [];
+      continue;
+    }
+    if (current) bodies[current].push(line);
+    else preamble.push(line);
+  }
+  if (!sawMarker) throw new Error(`${file}: body has no <!-- lang:xx --> section`);
+  if (preamble.join("").trim()) {
+    throw new Error(`${file}: text before the first <!-- lang:xx --> marker would be silently dropped`);
+  }
+
+  return {
+    meta,
+    bodies: Object.fromEntries(Object.entries(bodies).map(([lang, lines]) => [lang, lines.join("\n").trim()])),
+  };
+}
+
+/** Serialize a fixed, known key set to YAML frontmatter for generated host files. */
+export function toYamlFrontmatter(fields) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || value === null || value === "") continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      lines.push(`${key}: ${value.map(yamlScalar).join(", ")}`);
+      continue;
+    }
+    lines.push(`${key}: ${yamlScalar(value)}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function yamlScalar(value) {
+  const text = String(value);
+  // Quote anything a YAML reader could misinterpret. Cheap and always safe.
+  return /^[A-Za-z0-9][A-Za-z0-9 ._/-]*$/.test(text) && !/:\s/.test(text)
+    ? text
+    : JSON.stringify(text);
+}