alphacouncil-agent 0.5.0

package/mcp/lib/personas/registry.mjs

@@ -0,0 +1,215 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, relative } from "node:path";
+import { DEBATE_ROLES, DEFAULT_TASKS } from "../constants.mjs";
+import { parsePersonaFile } from "./frontmatter.mjs";
+
+export const PERSONA_KINDS = ["analyst", "debate", "master", "verifier"];
+const OUTPUT_CONTRACTS = ["evidence_packet", "debate_packet", "master_opinion", "verifier_verdict", "none"];
+const ID_PATTERN = /^[a-z0-9_]{2,48}$/;
+
+/** Resolved from import.meta.url. Hosts launch the server from arbitrary cwds. */
+export function defaultPersonaDir() {
+  return process.env.ALPHACOUNCIL_PERSONAS_DIR
+    || fileURLToPath(new URL("../../../personas/", import.meta.url));
+}
+
+/** Node 18 has no readdirSync({recursive:true}); ten lines beats a version floor bump. */
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) walk(path, out);
+    else if (entry.endsWith(".md")) out.push(path);
+  }
+  return out;
+}
+
+function validate(meta, bodies, file, errors) {
+  const fail = (message) => errors.push(`${file}: ${message}`);
+
+  if (meta.schema_version !== 1) fail(`schema_version must be 1, got ${JSON.stringify(meta.schema_version)}`);
+  if (typeof meta.id !== "string" || !ID_PATTERN.test(meta.id)) {
+    fail(`id must match ${ID_PATTERN}, got ${JSON.stringify(meta.id)}`);
+  }
+  if (!PERSONA_KINDS.includes(meta.kind)) fail(`kind must be one of ${PERSONA_KINDS.join("|")}, got ${JSON.stringify(meta.kind)}`);
+  if (!Number.isFinite(meta.order)) fail("order must be a finite number");
+  if (typeof meta.enabled !== "boolean") fail("enabled must be a boolean");
+  if (!Array.isArray(meta.rosters) || meta.rosters.some((r) => typeof r !== "string")) {
+    fail("rosters must be an array of strings");
+  }
+  if (!Array.isArray(meta.langs) || meta.langs.length === 0) fail("langs must be a non-empty array");
+  else {
+    for (const lang of meta.langs) {
+      // A declared language with no body is the drift this format exists to prevent.
+      if (!bodies[lang] || !bodies[lang].trim()) fail(`declares langs "${lang}" but has no non-empty <!-- lang:${lang} --> section`);
+    }
+    for (const lang of Object.keys(bodies)) {
+      if (!meta.langs.includes(lang)) fail(`has a <!-- lang:${lang} --> section that is not declared in langs`);
+    }
+    if (!meta.langs.includes(meta.default_lang)) fail(`default_lang ${JSON.stringify(meta.default_lang)} is not in langs`);
+  }
+  if (meta.output_contract !== undefined && !OUTPUT_CONTRACTS.includes(meta.output_contract)) {
+    fail(`output_contract must be one of ${OUTPUT_CONTRACTS.join("|")}, got ${JSON.stringify(meta.output_contract)}`);
+  }
+  if (meta.default_weight !== undefined) {
+    if (!Number.isFinite(meta.default_weight) || meta.default_weight <= 0) {
+      fail(`default_weight must be a positive number, got ${JSON.stringify(meta.default_weight)}`);
+    }
+  }
+
+  if (meta.kind === "master") {
+    // A master persona is a point of view with an explicit failure condition. Without
+    // disqualifiers it degrades into generic commentary that agrees with everything.
+    if (!Array.isArray(meta.philosophy_tags) || meta.philosophy_tags.length === 0) {
+      fail("a master persona must declare philosophy_tags");
+    }
+    if (!Array.isArray(meta.disqualifiers) || meta.disqualifiers.length === 0) {
+      fail("a master persona must declare disqualifiers: what would make this master walk away");
+    }
+    if (typeof meta.era !== "string" || !meta.era) fail("a master persona must declare era");
+    if (typeof meta.holding_period !== "string" || !meta.holding_period) fail("a master persona must declare holding_period");
+  }
+
+  if (meta.kind === "verifier") {
+    // A verifier whose verdict space is undefined cannot be aggregated: the caller has
+    // no way to decide what "2 of 3 confirmed" means.
+    if (!Array.isArray(meta.verdict_values) || meta.verdict_values.length < 2) {
+      fail("a verifier persona must declare verdict_values with at least two outcomes");
+    }
+    if (meta.output_contract !== "verifier_verdict") {
+      fail(`a verifier persona must use output_contract "verifier_verdict", got ${JSON.stringify(meta.output_contract)}`);
+    }
+  }
+
+  if (meta.source !== undefined && meta.source !== null) {
+    const s = meta.source;
+    if (typeof s !== "object" || !s.name || !s.license) {
+      fail("source must be null or an object with at least { name, license } -- adapted content must carry its attribution");
+    }
+  }
+}
+
+/**
+ * Load every persona under `dir` into a frozen registry.
+ *
+ * Collects ALL errors and throws once, so a malformed set is fixed in one pass rather
+ * than one file per run. Deliberately does not degrade: once the inline prompt literals
+ * are gone there is no fallback text, and a "graceful" degrade would silently ship empty
+ * prompts -- exactly the class of bug this layer exists to remove.
+ */
+export function loadPersonas({ dir = defaultPersonaDir() } = {}) {
+  let files;
+  try {
+    files = walk(dir).sort();
+  } catch (error) {
+    throw new Error(`persona directory is unreadable: ${dir} (${error.code || error.message}). Set ALPHACOUNCIL_PERSONAS_DIR to override.`);
+  }
+  if (files.length === 0) throw new Error(`no persona files found under ${dir}`);
+
+  const errors = [];
+  const byId = new Map();
+  for (const file of files) {
+    const label = relative(dir, file);
+    let parsed;
+    try {
+      parsed = parsePersonaFile(readFileSync(file, "utf8"), label);
+    } catch (error) {
+      errors.push(error.message);
+      continue;
+    }
+    validate(parsed.meta, parsed.bodies, label, errors);
+    const id = parsed.meta.id;
+    if (typeof id === "string") {
+      if (byId.has(id)) errors.push(`${label}: duplicate persona id "${id}" (also in ${byId.get(id).file})`);
+      else byId.set(id, { ...parsed.meta, bodies: parsed.bodies, file: label });
+    }
+  }
+
+  // Closure check: the task and role lists the server ships must all resolve.
+  for (const task of DEFAULT_TASKS) {
+    const persona = byId.get(task);
+    if (!persona) errors.push(`DEFAULT_TASKS includes "${task}" but no persona defines it`);
+    else if (persona.kind !== "analyst") errors.push(`"${task}" is a default task but its persona kind is "${persona.kind}"`);
+  }
+  for (const role of DEBATE_ROLES) {
+    const persona = byId.get(role);
+    if (!persona) errors.push(`DEBATE_ROLES includes "${role}" but no persona defines it`);
+    else if (persona.kind !== "debate") errors.push(`"${role}" is a debate role but its persona kind is "${persona.kind}"`);
+  }
+
+  if (errors.length) {
+    throw new Error(`invalid persona set in ${dir}:\n- ${errors.join("\n- ")}`);
+  }
+
+  return Object.freeze({
+    dir,
+    personas: byId,
+    get: (id) => byId.get(id),
+    all: () => [...byId.values()],
+    ids: (kind) => [...byId.values()]
+      .filter((p) => (kind ? p.kind === kind : true) && p.enabled)
+      .sort((a, b) => a.order - b.order || a.id.localeCompare(b.id))
+      .map((p) => p.id),
+  });
+}
+
+let cached = null;
+
+/** Loaded once per server process; personas are static and hosts restart the server. */
+export function registry() {
+  if (!cached) cached = loadPersonas();
+  return cached;
+}
+
+/** Tests only. */
+export function resetRegistry() {
+  cached = null;
+}
+
+export function selectRoster(reg, { kind, roster, ids } = {}) {
+  let list = reg.all();
+  if (ids?.length) {
+    const wanted = new Set(ids);
+    list = list.filter((p) => wanted.has(p.id));
+    const missing = ids.filter((id) => !reg.get(id));
+    if (missing.length) throw new Error(`unknown persona id(s): ${missing.join(", ")}`);
+  } else {
+    list = list.filter((p) => p.enabled);
+    if (kind) list = list.filter((p) => p.kind === kind);
+    if (roster) list = list.filter((p) => p.rosters.includes(roster));
+  }
+  return list.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+}
+
+/**
+ * The prompt body for a persona in the requested language.
+ *
+ * Falls back to the persona's default_lang, then to any body it has, so a persona that
+ * has not been translated yet still produces a usable prompt instead of an empty one.
+ */
+export function personaPrompt(persona, lang) {
+  if (!persona) return "";
+  const key = personaLangKey(persona, lang);
+  return persona.bodies[key] || "";
+}
+
+/** Map a resolved display language ("中文", "English", ...) onto a persona body key. */
+export function personaLangKey(persona, lang) {
+  const text = String(lang || "");
+  const wanted = /中文|chinese|zh/i.test(text) ? "zh"
+    : /日本語|japanese|ja/i.test(text) ? "ja"
+      : /한국어|korean|ko/i.test(text) ? "ko"
+        : "en";
+  if (persona.bodies[wanted]) return wanted;
+  if (persona.bodies[persona.default_lang]) return persona.default_lang;
+  return Object.keys(persona.bodies)[0];
+}
+
+/** Localized title, falling back through the same chain as the body. */
+export function personaTitle(persona, lang) {
+  if (!persona) return "";
+  const title = persona.title;
+  if (typeof title === "string") return title;
+  if (!title || typeof title !== "object") return persona.id;
+  return title[personaLangKey(persona, lang)] || title[persona.default_lang] || persona.id;
+}

package/mcp/lib/preflight.mjs

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import { registry, selectRoster } from "./personas/registry.mjs";
+
+/**
+ * Network-permission preflight.
+ *
+ * The failure this exists for: background subagents cannot raise an interactive
+ * permission prompt. If WebSearch is not allowed, their searches are blocked silently and
+ * the agent falls back on training knowledge -- while still filling in every section of
+ * the report template. The output looks complete and is entirely unsourced, and nothing
+ * in the run signals it.
+ *
+ * The check is deliberately three-valued, and the bar for "blocked" is high:
+ *
+ *   blocked  the host explicitly denies the tool. Definitive.
+ *   ok       bypassPermissions is set, or the tool is on an allowlist.
+ *   unknown  no persistent grant found. A foreground session prompts and works; a
+ *            background fan-out does not. This is a warning, not a stop.
+ *
+ * An earlier version treated "an allowlist exists but omits the tool" as blocked. That
+ * was wrong and fired on ordinary setups: an allowlist full of Bash entries says nothing
+ * about network access, and a machine with defaultMode bypassPermissions -- where
+ * everything is in fact granted -- was reported as blocked.
+ */
+
+/** Host config files that can carry a tool permission allowlist. */
+export function permissionSources({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return [
+    join(cwd, ".claude", "settings.local.json"),
+    join(cwd, ".claude", "settings.json"),
+    join(home, ".claude", "settings.local.json"),
+    join(home, ".claude", "settings.json"),
+    join(cwd, "opencode.json"),
+    join(home, ".config", "opencode", "opencode.json"),
+  ];
+}
+
+/** Normalize the tool names the two hosts use so one allowlist check covers both. */
+export function canonicalTool(name) {
+  const text = String(name || "").trim().toLowerCase().replace(/[^a-z]/g, "");
+  if (text.startsWith("websearch")) return "websearch";
+  if (text.startsWith("webfetch")) return "webfetch";
+  if (text.startsWith("getquote")) return "get_quote";
+  return String(name || "").trim().toLowerCase();
+}
+
+function readPermissions(path) {
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    return { path, unreadable: error.message };
+  }
+  // Claude Code: { permissions: { allow: [...], deny: [...] } }
+  // OpenCode:    { permission: { websearch: "allow" | "ask" | "deny", ... } }
+  const claude = parsed?.permissions;
+  const opencode = parsed?.permission || parsed?.permissions;
+  const allow = new Set();
+  const deny = new Set();
+  let declared = false;
+  // bypassPermissions grants everything without prompting, including in background
+  // subagents. Ignoring it made this check report "blocked" on a fully permissive setup.
+  const bypass = claude?.defaultMode === "bypassPermissions";
+
+  if (Array.isArray(claude?.allow)) {
+    declared = true;
+    for (const entry of claude.allow) allow.add(canonicalTool(entry));
+  }
+  if (Array.isArray(claude?.deny)) {
+    declared = true;
+    for (const entry of claude.deny) deny.add(canonicalTool(entry));
+  }
+  if (opencode && !Array.isArray(opencode) && typeof opencode === "object") {
+    for (const [key, value] of Object.entries(opencode)) {
+      if (typeof value !== "string") continue;
+      declared = true;
+      if (value === "allow") allow.add(canonicalTool(key));
+      else if (value === "deny") deny.add(canonicalTool(key));
+    }
+  }
+  return { path, allow, deny, declared, bypass };
+}
+
+/** Every tool the personas in a roster say they need. */
+export function requiredTools({ reg = registry(), roster = "default", kind = "analyst" } = {}) {
+  const personas = selectRoster(reg, { kind, roster });
+  const tools = new Set();
+  for (const persona of personas) {
+    for (const tool of persona.tools_hint || []) tools.add(canonicalTool(tool));
+  }
+  // get_quote is served by this MCP server itself; it never needs a host allowlist entry.
+  tools.delete("get_quote");
+  return [...tools].sort();
+}
+
+const REMEDY = {
+  claude: 'Add the tools to permissions.allow in .claude/settings.local.json, e.g. {"permissions":{"allow":["WebSearch","WebFetch"]}}',
+  opencode: 'Set them to "allow" in opencode.json, e.g. {"permission":{"websearch":"allow","webfetch":"allow"}}. Note OpenCode gates websearch behind its own provider or OPENCODE_ENABLE_EXA=1.',
+};
+
+/**
+ * @returns {{status:"ok"|"blocked"|"unknown", required:string[], missing:string[],
+ *            denied:string[], checked:object[], remedy:string, message:string}}
+ */
+export function preflightNetworkPermissions(options = {}) {
+  const required = options.required || requiredTools(options);
+  const sources = permissionSources(options).map(readPermissions).filter(Boolean);
+  const allow = new Set();
+  const deny = new Set();
+  let bypass = false;
+  for (const source of sources) {
+    if (source.bypass) bypass = true;
+    for (const tool of source.allow || []) allow.add(tool);
+    for (const tool of source.deny || []) deny.add(tool);
+  }
+
+  const denied = required.filter((tool) => deny.has(tool));
+  // Only an explicit denial is "blocked". An allowlist that happens to exist for other
+  // tools says nothing about network access: a foreground session still prompts and
+  // works. Treating that as blocked was a false positive on ordinary setups.
+  const ungranted = required.filter((tool) => !deny.has(tool) && !allow.has(tool));
+
+  const checked = sources.map((s) => ({
+    path: s.path,
+    declares_permissions: Boolean(s.declared),
+    ...(s.unreadable ? { unreadable: s.unreadable } : {}),
+  }));
+
+  if (denied.length) {
+    return {
+      status: "blocked",
+      required,
+      missing: ungranted,
+      denied,
+      checked,
+      remedy: REMEDY.claude,
+      message: `The host explicitly denies ${denied.join(", ")}. Evidence agents cannot search, and a background subagent cannot prompt to ask. Do not run the council until this is changed: it will produce a complete-looking report with no sources behind it.`,
+    };
+  }
+  if (bypass) {
+    return {
+      status: "ok",
+      required,
+      missing: [],
+      denied: [],
+      checked,
+      remedy: "",
+      message: `Permission mode is bypassPermissions, so all required tools (${required.join(", ") || "none"}) are granted without prompting.`,
+    };
+  }
+  if (ungranted.length === 0 && required.length > 0) {
+    return {
+      status: "ok",
+      required,
+      missing: [],
+      denied: [],
+      checked,
+      remedy: "",
+      message: `All required network tools are on the allowlist: ${required.join(", ")}.`,
+    };
+  }
+  return {
+    status: "unknown",
+    required,
+    missing: ungranted,
+    denied: [],
+    checked,
+    remedy: REMEDY.claude,
+    message: `${ungranted.join(", ") || "The required tools"} are not on any persistent allowlist. A FOREGROUND session will prompt you and work normally. BACKGROUND subagents cannot prompt: their searches are blocked silently and they will answer from training knowledge while still filling in every report section. Allowlist them before a background fan-out, or run the evidence agents in the foreground.`,
+  };
+}

package/mcp/lib/prompts.mjs

@@ -0,0 +1,151 @@
+import { join } from "node:path";
+import { isChineseLanguage, resolveLanguage } from "./lang.mjs";
+import { runPath } from "./run-store.mjs";
+import { compactEvidence, compactMasterOpinions } from "./packets.mjs";
+import { outputModeInstruction } from "./output-modes.mjs";
+import { resolveSeatWeights, weightTableMarkdown } from "./weights.mjs";
+import { groundingBlock } from "./grounding.mjs";
+import { personaPrompt, personaTitle, registry, selectRoster } from "./personas/registry.mjs";
+
+/**
+ * Prompt text lives in personas/, not here.
+ *
+ * It used to be two parallel blocks of string literals inside a 2000-line module -- one
+ * Chinese, one English -- which had already drifted apart, and which neither a human
+ * reviewer nor a host could see. These functions now only compose: preamble + persona
+ * body + run-specific context.
+ */
+
+/** Fill {{placeholders}} in a persona body. Unknown keys are left alone, not blanked. */
+function render(template, values) {
+  return String(template || "").replace(/\{\{(\w+)\}\}/g, (match, key) =>
+    (Object.prototype.hasOwnProperty.call(values, key) ? String(values[key] ?? "") : match));
+}
+
+export function taskPrompt(task, symbol, asOfDate, userPrompt = "", language = "auto", grounding = null) {
+  const resolvedLanguage = resolveLanguage({ language, prompt: userPrompt });
+  const chinese = isChineseLanguage(resolvedLanguage);
+  const reg = registry();
+
+  const base = [
+    render(personaPrompt(reg.get("_evidence_base"), resolvedLanguage), {
+      symbol,
+      as_of: asOfDate,
+      language: resolvedLanguage,
+    }),
+    userPrompt ? (chinese ? `用户目标：${userPrompt}` : `User objective: ${userPrompt}`) : "",
+  ].filter(Boolean).join("\n");
+
+  const body = render(personaPrompt(reg.get(task), resolvedLanguage), { symbol, as_of: asOfDate, language: resolvedLanguage })
+    || (chinese ? "收集与投资决策相关的证据。" : "Collect evidence relevant to the investment decision.");
+
+  // 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 grounded = groundingBlock(grounding, resolvedLanguage);
+  return [`${base}\n\n${chinese ? "任务：" : "Task: "}${task}\n${body}`, grounded].filter(Boolean).join("\n\n");
+}
+
+export function debatePrompt(role, run, context = {}) {
+  const evidencePath = join(runPath(run.run_id), "evidence.json");
+  const evidenceJson = JSON.stringify(compactEvidence(run));
+  const language = run.language || "English";
+  const chinese = isChineseLanguage(language);
+  const reg = registry();
+
+  const base = render(personaPrompt(reg.get("_debate_base"), language), {
+    symbol: run.symbol,
+    as_of: run.as_of,
+    evidence_path: evidencePath,
+    language,
+    role,
+  });
+
+  const roleText = render(personaPrompt(reg.get(role), language), { symbol: run.symbol, as_of: run.as_of, language, role })
+    || (chinese ? "产出投资组合辩论 memo。" : "Produce a portfolio debate memo.");
+
+  const roundThreeInstruction = context.round === 3
+    ? (chinese
+        ? "本轮为问答轮:在 `questions` 数组里给出恰好 3 个针对对方的尖锐问题,并在 `questions_answered` 数组里逐条回答对方提出的问题。"
+        : "This is the Q&A round: in a `questions` array list exactly 3 sharp questions for the other side, and in a `questions_answered` array answer the 3 questions the other side asked you.")
+    : "";
+
+  return [
+    // The original spread the preamble's lines as separate array elements, so they are
+    // separated by blank lines in the final prompt. Preserve that exactly.
+    ...base.split("\n"),
+    roleText,
+    roundThreeInstruction,
+    context.round ? `Debate round: ${context.round}` : "",
+    context.brief ? `Brief length for round 1: ${context.brief}` : "",
+    context.otherCaseR1 ? `Opponent prior-round case JSON: ${JSON.stringify(context.otherCaseR1)}` : "",
+    context.questionsForYou ? `Questions you must answer JSON: ${JSON.stringify(context.questionsForYou)}` : "",
+    // The masters ran before the debate; the bull and bear must argue with their
+    // disagreements rather than restate the evidence unopposed.
+    (run.master_opinions || []).length
+      ? `Master seat opinions JSON (read the disagreements; you must engage with them, not ignore them): ${JSON.stringify(compactMasterOpinions(run))}`
+      : "",
+    context.bull ? `Bull argument JSON: ${JSON.stringify(context.bull)}` : "",
+    context.bear ? `Bear argument JSON: ${JSON.stringify(context.bear)}` : "",
+    // The PM must reproduce the weighting rather than average the seats silently.
+    role === "portfolio_manager"
+      ? [
+        chinese
+          ? "各席位权重如下。你的最终裁决必须按这个权重加权，并且必须在报告里原样复现这张表（含核验调整原因）。权重为 0 的席位（自述超出判断范围）不计入。若你的结论与高权重席位相反，必须明确说明为什么。"
+          : "Seat weights follow. Weight your verdict by them, and reproduce this table verbatim in the report, including the adjustment reasons. Seats at weight 0 declared themselves out of scope and do not count. If your conclusion opposes a high-weight seat, say explicitly why.",
+        weightTableMarkdown(resolveSeatWeights(run, run.seat_weight_overrides || {}), language),
+      ].filter(Boolean).join("\n\n")
+      : "",
+    role === "portfolio_manager" ? outputModeInstruction(context.outputMode || "chat", language) : "",
+    `Evidence JSON: ${evidenceJson}`,
+  ].filter(Boolean).join("\n\n");
+}
+
+/**
+ * A master seat reads the finished evidence through one philosophy.
+ *
+ * Masters deliberately run after the evidence stage and before the debate: they are a
+ * judgment layer, not an evidence layer, and their disagreements are what the bull and
+ * bear then have to argue with.
+ */
+export function masterPrompt(masterId, run) {
+  const reg = registry();
+  const persona = reg.get(masterId);
+  if (!persona || persona.kind !== "master") throw new Error(`unknown master persona: ${masterId}`);
+  const language = run.language || "English";
+  const values = { symbol: run.symbol, as_of: run.as_of, language };
+
+  const chinese = isChineseLanguage(language);
+  // Masters see the same established facts the analysts saw, not only what the analysts
+  // chose to report. A master's value is a different selection from the same facts --
+  // Munger looking at incentives, Burry at the notes -- and reading only the analysts'
+  // packets destroys exactly that. It also means one weak packet would bias all 21 seats
+  // identically, which is the worst kind of error: large and perfectly correlated.
+  const grounded = groundingBlock(run.grounding, language);
+  const packetLabel = chinese
+    ? "以下是分析师席位的证据包。这是**其他席位对同一批事实的解读**，不是事实本身。"
+      + "你可以不同意他们的读法，但必须说明你依据的是上面哪一条原始事实。"
+    : "Below are the analyst seats' evidence packets. These are **other seats' readings of the "
+      + "same facts**, not the facts themselves. You may disagree with a reading, but say which "
+      + "established fact above your disagreement rests on.";
+
+  return [
+    render(personaPrompt(reg.get("_master_base"), language), values),
+    `Master: ${personaTitle(persona, language)} (${persona.id})`,
+    render(personaPrompt(persona, language), values),
+    `Walk-away conditions you must check explicitly: ${(persona.disqualifiers || []).join(" | ")}`,
+    grounded,
+    `${packetLabel}\nEvidence JSON: ${JSON.stringify(compactEvidence(run))}`,
+  ].filter(Boolean).join("\n\n");
+}
+
+/** The master ids a run has selected, from an explicit list or a roster name. */
+export function selectedMasters(run) {
+  const reg = registry();
+  if (Array.isArray(run.masters) && run.masters.length) {
+    return selectRoster(reg, { ids: run.masters }).filter((p) => p.kind === "master").map((p) => p.id);
+  }
+  if (run.masters_roster) {
+    return selectRoster(reg, { kind: "master", roster: run.masters_roster }).map((p) => p.id);
+  }
+  return [];
+}

package/mcp/lib/quotes.mjs

@@ -0,0 +1,108 @@
+import { LIMITS } from "./constants.mjs";
+import { invalidParams } from "./errors.mjs";
+
+// ---- Keyless delayed market data (Yahoo primary, Stooq fallback) ------------
+export const MARKET_ALIASES = {
+  kospi: "^KS11", "韩股": "^KS11", "韩国综合": "^KS11", kospi200: "^KS200",
+  "标普": "^GSPC", "标普500": "^GSPC", sp500: "^GSPC", spx: "^GSPC",
+  "纳指": "^IXIC", "纳斯达克": "^IXIC", "道指": "^DJI", "道琼斯": "^DJI",
+  "罗素2000": "^RUT", "恒生": "^HSI", "恒指": "^HSI",
+  "上证": "000001.SS", "上证指数": "000001.SS", "深证": "399001.SZ",
+  "沪深300": "000300.SS", "创业板": "399006.SZ",
+  "日经": "^N225", "日经225": "^N225", "台股": "^TWII", "台湾加权": "^TWII",
+  "德指": "^GDAXI", dax: "^GDAXI", "富时100": "^FTSE", ftse: "^FTSE",
+  "标普期货": "ES=F", "纳指期货": "NQ=F", "道指期货": "YM=F", "罗素期货": "RTY=F",
+  "原油": "CL=F", wti: "CL=F", "布伦特": "BZ=F", "黄金": "GC=F", "白银": "SI=F",
+  "天然气": "NG=F", "铜": "HG=F",
+  vix: "^VIX", "恐慌指数": "^VIX", "10年美债": "^TNX", "美债10年": "^TNX",
+  "美债30年": "^TYX", "美元指数": "DX-Y.NYB", dxy: "DX-Y.NYB",
+  "美元日元": "JPY=X", "欧元美元": "EURUSD=X", "美元人民币": "CNY=X",
+  "比特币": "BTC-USD", btc: "BTC-USD", "以太坊": "ETH-USD",
+};
+
+export function resolveMarketSymbol(input) {
+  const raw = String(input || "").trim();
+  if (!raw) return "";
+  const key = raw.toLowerCase();
+  return Object.prototype.hasOwnProperty.call(MARKET_ALIASES, key) ? MARKET_ALIASES[key] : raw;
+}
+
+export function parseYahooChart(json, requested) {
+  const meta = json?.chart?.result?.[0]?.meta;
+  if (!meta || typeof meta.regularMarketPrice !== "number") throw new Error("no price in chart payload");
+  const prev = typeof meta.chartPreviousClose === "number" ? meta.chartPreviousClose
+    : (typeof meta.previousClose === "number" ? meta.previousClose : null);
+  const price = meta.regularMarketPrice;
+  const change = prev != null ? price - prev : null;
+  const changePct = prev ? (change / prev) * 100 : null;
+  return {
+    query: requested,
+    symbol: meta.symbol || requested,
+    price,
+    previous_close: prev,
+    change: change != null ? Number(change.toFixed(4)) : null,
+    change_pct: changePct != null ? Number(changePct.toFixed(2)) : null,
+    currency: meta.currency || null,
+    exchange: meta.exchangeName || null,
+    market_state: meta.marketState || null,
+    quote_time: meta.regularMarketTime ? new Date(meta.regularMarketTime * 1000).toISOString() : null,
+    source: "yahoo",
+    note: "delayed (~15m), not a real-time feed",
+  };
+}
+
+export function parseStooqCsv(csv, requested) {
+  const lines = String(csv || "").trim().split("\n");
+  if (lines.length < 2) throw new Error("empty stooq csv");
+  const cols = lines[1].split(",");
+  const close = Number(cols[6]);
+  if (!Number.isFinite(close)) throw new Error("no stooq close");
+  return {
+    query: requested, symbol: cols[0] || requested, price: close,
+    previous_close: null, change: null, change_pct: null,
+    currency: null, exchange: "stooq", market_state: null,
+    quote_time: (cols[1] && cols[2]) ? `${cols[1]}T${cols[2]}` : null,
+    source: "stooq", note: "delayed / EOD fallback, not real-time",
+  };
+}
+
+export async function fetchText(url, timeoutMs = LIMITS.QUOTE_FETCH_MS) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, headers: { "User-Agent": "Mozilla/5.0 (AlphaCouncil)" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function fetchQuote(input) {
+  const sym = resolveMarketSymbol(input);
+  if (!sym) return { query: input, error: "empty symbol" };
+  try {
+    const txt = await fetchText(`https://query1.finance.yahoo.com/v8/finance/chart/${encodeURIComponent(sym)}?range=1d&interval=1d`);
+    return parseYahooChart(JSON.parse(txt), sym);
+  } catch (e1) {
+    try {
+      const txt = await fetchText(`https://stooq.com/q/l/?s=${encodeURIComponent(sym.toLowerCase())}&f=sd2t2ohlcv&h&e=csv`);
+      return parseStooqCsv(txt, sym);
+    } catch (e2) {
+      return { query: input, symbol: sym, error: `live data unavailable (${e1.message}; ${e2.message})`, note: "fall back to WebSearch and mark open_questions" };
+    }
+  }
+}
+
+export async function getQuotes(args) {
+  const list = Array.isArray(args?.symbols) ? args.symbols : (args?.symbol ? [args.symbol] : []);
+  if (list.length === 0) throw invalidParams("get_quote requires symbols[] or symbol.");
+  const quotes = await Promise.all(
+    list.slice(0, LIMITS.QUOTE_MAX_SYMBOLS).map((s) => fetchQuote(s).catch((e) => ({ query: s, error: String((e && e.message) || e) }))),
+  );
+  return {
+    as_of: new Date().toISOString(),
+    quotes,
+    disclaimer: "Keyless delayed market data (Yahoo/Stooq, ~15m or EOD). Not real-time, not investment advice. Missing/errored symbols are data gaps -> open_questions.",
+  };
+}