alphacouncil-agent 0.5.0

package/mcp/lib/codex.mjs

@@ -0,0 +1,152 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { CODEX_CMD, DATA_DIR, LIMITS } from "./constants.mjs";
+import { appendLimited } from "./text.mjs";
+
+export function quoteCmdArg(value) {
+  const text = String(value);
+  if (!text) return "\"\"";
+  if (!/[ \t"&|<>^]/.test(text)) return text;
+  return `"${text.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/g, "$1$1")}"`;
+}
+
+export function codexInvocation(args, platform = process.platform, env = process.env) {
+  const fullArgs = [...args, "-"];
+  if (platform === "win32") {
+    return {
+      command: env.ComSpec || "cmd.exe",
+      args: ["/d", "/s", "/c", [env.ALPHACOUNCIL_AGENT_CODEX_CMD || CODEX_CMD, ...fullArgs].map(quoteCmdArg).join(" ")],
+      options: { detached: false, windowsHide: true },
+    };
+  }
+  return { command: CODEX_CMD, args: fullArgs, options: { detached: true } };
+}
+
+export function stopChild(child, force = false) {
+  if (!child.pid) return;
+  if (process.platform === "win32") {
+    const args = ["/pid", String(child.pid), "/t"];
+    if (force) args.push("/f");
+    const killer = spawn("taskkill", args, { stdio: "ignore", windowsHide: true });
+    killer.on("error", () => child.kill(force ? "SIGKILL" : "SIGTERM"));
+    return;
+  }
+  try {
+    process.kill(-child.pid, force ? "SIGKILL" : "SIGTERM");
+  } catch {
+    child.kill(force ? "SIGKILL" : "SIGTERM");
+  }
+}
+
+export function runCodex(prompt, timeoutMs, onStart = () => {}, onHeartbeat = () => {}) {
+  return new Promise((resolvePromise) => {
+    mkdirSync(DATA_DIR, { recursive: true });
+    const outFile = join(DATA_DIR, `codex-${Date.now()}-${Math.random().toString(16).slice(2)}.txt`);
+    const args = [
+      "--search",
+      "-s",
+      "read-only",
+      "-a",
+      "never",
+      "exec",
+      "--ephemeral",
+      "--skip-git-repo-check",
+      "-C",
+      DATA_DIR,
+      "-o",
+      outFile,
+    ];
+    const invocation = codexInvocation(args);
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: DATA_DIR,
+      stdio: ["pipe", "pipe", "pipe"],
+      ...invocation.options,
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(prompt, "utf8");
+    onStart({ pid: child.pid, output: outFile });
+    const startedAt = Date.now();
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let killTimer = null;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearInterval(heartbeat);
+      if (killTimer) clearTimeout(killTimer);
+      // The caller already has the text by now. Nothing deleted this before, so every
+      // analyst of every run left one file behind in DATA_DIR forever.
+      try {
+        unlinkSync(outFile);
+      } catch {
+        // Codex may never have created it (spawn error, immediate timeout).
+      }
+      resolvePromise(value);
+    };
+    const heartbeat = setInterval(() => {
+      onHeartbeat({ pid: child.pid, output: outFile, elapsed_ms: Date.now() - startedAt });
+    }, LIMITS.HEARTBEAT_MS);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stopChild(child);
+      killTimer = setTimeout(() => {
+        stopChild(child, true);
+      }, LIMITS.SIGKILL_GRACE_MS);
+    }, timeoutMs);
+    // Drain both pipes; switch to streaming logs if a progress UI needs live CLI output.
+    child.stdout.on("data", (chunk) => { stdout = appendLimited(stdout, chunk.toString()); });
+    child.stderr.on("data", (chunk) => { stderr = appendLimited(stderr, chunk.toString()); });
+    child.on("error", (error) => {
+      finish({ ok: false, code: null, text: "", stderr: String(error.message || error), stdout, outFile, timedOut });
+    });
+    child.on("close", (code) => {
+      let text = "";
+      if (existsSync(outFile)) text = readFileSync(outFile, "utf8");
+      finish({ ok: code === 0 && text.trim().length > 0, code, text, stderr, stdout, outFile, timedOut });
+    });
+  });
+}
+
+/**
+ * Delete Codex output files left behind by older versions (and by any run killed
+ * between spawn and finish). Called once at server start; never throws.
+ */
+export function sweepStaleOutputs(now = Date.now()) {
+  let removed = 0;
+  let entries;
+  try {
+    entries = readdirSync(DATA_DIR);
+  } catch {
+    return removed;
+  }
+  for (const name of entries) {
+    if (!/^codex-\d+-[0-9a-f]+\.txt$/.test(name)) continue;
+    const path = join(DATA_DIR, name);
+    try {
+      if (now - statSync(path).mtimeMs < LIMITS.STALE_OUTPUT_MS) continue;
+      unlinkSync(path);
+      removed += 1;
+    } catch {
+      // Another process may have removed it, or it may not be ours to delete.
+    }
+  }
+  return removed;
+}
+
+export async function mapLimit(items, limit, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function runOne() {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      results[index] = await worker(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runOne));
+  return results;
+}

package/mcp/lib/constants.mjs

@@ -0,0 +1,139 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+
+export const DATA_DIR = process.env.ALPHACOUNCIL_AGENT_DATA_DIR || join(os.homedir(), ".alphacouncil-agent");
+export const RUNS_DIR = join(DATA_DIR, "runs");
+export const SERVER_NAME = "alphacouncil-agent";
+// Single source of truth for the version. Resolved from import.meta.url, never process.cwd(),
+// because hosts launch this server from arbitrary working directories.
+export const VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+export const CODEX_CMD = process.env.ALPHACOUNCIL_AGENT_CODEX_CMD || "codex";
+// Eight roles, down from eleven. The three removed were merged rather than dropped:
+// the earnings call is part of the earnings read, sell-side revisions are part of the
+// forward-expectations read, and "industry voices" and "industry news" were searching the
+// same ground. Fewer, wider roles means fewer duplicated searches for the same facts.
+export const DEFAULT_TASKS = [
+  "market_data",
+  "earnings_deep_dive",
+  "forward_expectations",
+  "quant_factor",
+  "valuation_long_short",
+  "news_industry_management",
+  "insider_sec",
+  "ib_event_analysis",
+];
+export const RATINGS = ["Buy", "Overweight", "Hold", "Underweight", "Sell"];
+export const DEBATE_ROLES = ["bull_researcher", "bear_researcher", "portfolio_manager"];
+export const MASTER_STANCES = ["constructive", "cautious", "opposed", "out_of_scope"];
+// product_design / creative_production / sales were removed: each described itself as
+// "not for investment summary". Unknown values fall back to public_equity, so a host
+// still passing an old name degrades cleanly instead of erroring.
+export const OUTPUT_MODES = [
+  "chat",
+  "documents",
+  "pdf",
+  "presentations",
+  "data_analytics",
+  "public_equity",
+  "investment_banking",
+];
+/**
+ * The report contract, as a structured registry.
+ *
+ * `aliases` are matched against normalized headings; the LONGEST matching alias wins, so
+ * a heading like "Quant Factor / Technical Risk View" is assigned to `quant` rather than
+ * being allowed to satisfy `risks`. `min_body` is the number of non-space characters the
+ * section body must carry, calibrated against the manager fallback report, which emits
+ * several legitimately terse sections ("## Confidence\nmedium").
+ */
+export const REPORT_SECTIONS = [
+  { id: "conclusion", aliases: ["结论", "conclusion"], min_body: 6 },
+  { id: "analyst_work_log", aliases: ["分析师工作记录", "analyst work log"], min_body: 12, per_task: true },
+  { id: "debate_record", aliases: ["多空辩论记录", "bull bear debate", "debate record"], min_body: 20 },
+  { id: "market_expectations", aliases: ["市场预期", "market expectations"], min_body: 8 },
+  { id: "analyst_rating", aliases: ["分析师评级", "analyst rating", "target price"], min_body: 8 },
+  { id: "earnings_call", aliases: ["电话会", "earnings call"], min_body: 8 },
+  { id: "quant", aliases: ["量化", "quant"], min_body: 8 },
+  { id: "news", aliases: ["新闻", "news"], min_body: 8 },
+  { id: "short_interest", aliases: ["short interest", "borrow"], min_body: 8 },
+  { id: "strategic_transaction", aliases: ["战略交易", "strategic transaction", "banking event"], min_body: 8 },
+  { id: "valuation", aliases: ["估值", "valuation"], min_body: 8 },
+  // Required, and deliberately not called "target price". A single number pretends to a
+  // precision nobody has; what a reader needs is the price at which the case changes.
+  // Three master lenses already demand this -- Marks asks at what price it stops being
+  // "leave it", Graham asks for a calculable floor, Thorp asks for a size -- and the PM
+  // used to be able to skip it with "the cycle position is undetermined".
+  { id: "price_levels", aliases: ["价位", "入场价位", "price levels", "entry level", "价格条件"], min_body: 30 },
+  { id: "catalysts", aliases: ["催化剂", "catalyst"], min_body: 8 },
+  { id: "risks", aliases: ["风险", "risk"], min_body: 8 },
+  { id: "position", aliases: ["仓位", "position"], min_body: 8 },
+  { id: "short_term", aliases: ["短线", "short term"], min_body: 6 },
+  { id: "medium_term", aliases: ["中期", "medium term"], min_body: 6 },
+  { id: "long_term", aliases: ["长期", "long term"], min_body: 6 },
+  { id: "data_gaps", aliases: ["数据缺口", "data gaps", "unavailable data"], min_body: 8 },
+  { id: "invalidation", aliases: ["反证", "invalidation"], min_body: 8 },
+  { id: "confidence", aliases: ["置信", "confidence"], min_body: 3 },
+  { id: "source_table", aliases: ["来源表", "source table"], min_body: 6 },
+];
+
+/** Bodies that look like a section but say nothing. */
+export const PLACEHOLDER_BODIES = [
+  "", "-", "n/a", "na", "tbd", "todo", "none", "- none", "待补充", "- 待补充", "无", "- 无",
+];
+
+/** @deprecated Superseded by REPORT_SECTIONS; kept only for external readers. */
+export const REPORT_SECTION_TERMS = [
+  ["结论", "Conclusion"],
+  ["分析师工作记录", "Analyst Work Log"],
+  ["多空辩论记录", "Bull/Bear Debate"],
+  ["市场预期", "Market Expectations"],
+  ["分析师评级", "Analyst Rating"],
+  ["电话会", "Earnings Call"],
+  ["量化", "Quant"],
+  ["新闻", "News"],
+  ["short interest", "Short Interest"],
+  ["战略交易", "Strategic Transaction"],
+  ["估值", "Valuation"],
+  ["催化剂", "Catalyst"],
+  ["风险", "Risk"],
+  ["仓位", "Position"],
+  ["短线", "Short-Term"],
+  ["中期", "Medium-Term"],
+  ["长期", "Long-Term"],
+  ["数据缺口", "Data Gaps"],
+  ["反证", "Invalidation"],
+  ["置信", "Confidence"],
+  ["来源表", "Source Table"],
+];
+
+/**
+ * Every tunable that used to be a bare number inline. Frozen so a typo is a TypeError
+ * in strict mode rather than a silent global retune.
+ */
+export const LIMITS = Object.freeze({
+  /** Rolling cap on captured child stdout/stderr. */
+  LOG_TAIL_BYTES: 20000,
+  /** Cap applied when a log is cleaned for display or storage. */
+  CLEAN_LOG_BYTES: 4000,
+  /** Cap for one-line summaries in handoffs and fallback reports. */
+  CLIP_CHARS: 520,
+  /** How often a long-running Codex child reports that it is still alive. */
+  HEARTBEAT_MS: 30000,
+  /** Grace period between SIGTERM and SIGKILL for a timed-out child. */
+  SIGKILL_GRACE_MS: 5000,
+  /** Default per-subagent Codex timeout. */
+  CODEX_TIMEOUT_MS: Number(process.env.ALPHACOUNCIL_AGENT_TIMEOUT_MS) || 600000,
+  CONCURRENCY_MIN: 1,
+  CONCURRENCY_MAX: 6,
+  CONCURRENCY_DEFAULT: Number(process.env.ALPHACOUNCIL_AGENT_CONCURRENCY) || 3,
+  /** Minimum non-space characters before a final report is considered a real report. */
+  REPORT_MIN_CHARS: 1600,
+  REPORT_MIN_CHARS_DRY: 600,
+  /** Timeout for one keyless quote fetch. */
+  QUOTE_FETCH_MS: 8000,
+  /** Cap on symbols per get_quote call. */
+  QUOTE_MAX_SYMBOLS: 25,
+  /** Age after which a leftover Codex output file is swept at startup. */
+  STALE_OUTPUT_MS: 24 * 60 * 60 * 1000,
+});

package/mcp/lib/council-options.mjs

@@ -0,0 +1,111 @@
+import { registry, selectRoster, personaTitle } from "./personas/registry.mjs";
+import { DEFAULT_TASKS } from "./constants.mjs";
+
+/**
+ * The menu a host shows before a run starts.
+ *
+ * A council can be four seats or thirty-eight, and the difference is minutes and money the
+ * user is spending. Choosing silently on their behalf is the wrong default in both
+ * directions: pick small and the bench they were promised never runs, pick everything and
+ * a quick question costs a full fan-out.
+ *
+ * MCP cannot draw a dialog, so this supplies the menu as data and the runtime skill
+ * requires the host to ask. That works identically in Claude Code, Codex, OpenCode and
+ * Grok Build, because all four can ask a question in chat.
+ */
+
+/** Rough per-seat cost, used only to rank presets. Not a promise about wall-clock time. */
+const SEAT_MINUTES = { analyst: 1.5, master: 0.8, verifier: 0.5, debate: 1.5 };
+
+const estimate = ({ analysts = 0, masters = 0, verifiers = 0, debate = 3 }) => {
+  const seats = analysts + masters + verifiers + debate;
+  const minutes = analysts * SEAT_MINUTES.analyst + masters * SEAT_MINUTES.master
+    + verifiers * SEAT_MINUTES.verifier + debate * SEAT_MINUTES.debate;
+  return { seats, rough_minutes: Math.round(minutes) };
+};
+
+export function councilOptions({ language = "English" } = {}) {
+  const chinese = /中文|chinese|zh/i.test(String(language));
+  const reg = registry();
+
+  const allAnalysts = reg.ids("analyst").map((id) => reg.get(id)).filter((p) => p.enabled);
+  const masterRosters = [...new Set(
+    reg.ids("master").flatMap((id) => reg.get(id).rosters || []),
+  )].filter((r) => r !== "masters-core").sort();
+
+  const analystChoices = allAnalysts.map((p) => ({
+    id: p.id,
+    title: personaTitle(p, language),
+    in_default: DEFAULT_TASKS.includes(p.id),
+    covers: (p.tags || []).join(", "),
+  }));
+
+  const rosterChoices = masterRosters.map((roster) => {
+    const members = selectRoster(reg, { kind: "master", roster });
+    return {
+      roster,
+      count: members.length,
+      members: members.map((m) => ({ id: m.id, title: personaTitle(m, language) })),
+    };
+  });
+
+  const allMasters = reg.ids("master").length;
+  const verifiers = reg.ids("verifier");
+
+  const presets = [
+    {
+      id: "quick",
+      label: chinese ? "快速：4 位分析师 + 辩论" : "Quick: 4 analysts + debate",
+      analysts: DEFAULT_TASKS.slice(0, 4),
+      masters_roster: null,
+      verify: false,
+      ...estimate({ analysts: 4 }),
+      good_for: chinese
+        ? "只想要一个方向性看法，接受没有大师视角、没有交叉验证"
+        : "A directional read only. No master lenses and no cross-verification.",
+    },
+    {
+      id: "standard",
+      label: chinese ? "标准：8 位分析师 + 核心大师 + 辩论" : "Standard: 8 analysts + core bench + debate",
+      analysts: DEFAULT_TASKS,
+      masters_roster: "masters-core",
+      verify: false,
+      ...estimate({ analysts: DEFAULT_TASKS.length, masters: allMasters }),
+      good_for: chinese
+        ? "默认推荐。覆盖完整证据面并让全部大师议席发言"
+        : "The recommended default. Full evidence coverage with every master lens reporting.",
+    },
+    {
+      id: "deep",
+      label: chinese ? "深度：全部分析师 + 全部大师 + 交叉验证 + 辩论" : "Deep: every analyst + every master + verification + debate",
+      analysts: allAnalysts.map((p) => p.id),
+      masters_roster: "masters-core",
+      verify: true,
+      ...estimate({ analysts: allAnalysts.length, masters: allMasters, verifiers: verifiers.length * 3 }),
+      good_for: chinese
+        ? "要下真钱的时候用。每条承重论断都会被回源、独立重算和反面检索"
+        : "For a decision with real money behind it. Every load-bearing claim is re-sourced, re-derived and attacked.",
+    },
+  ];
+
+  return {
+    language,
+    presets,
+    analysts: analystChoices,
+    default_analysts: DEFAULT_TASKS,
+    master_rosters: rosterChoices,
+    all_masters_count: allMasters,
+    verifiers: verifiers.map((id) => ({ id, title: personaTitle(reg.get(id), language) })),
+    how_to_ask: chinese ? [
+      "开始跑之前，把上面的预设念给用户，让他们选一个，或者自己点名要哪些分析师和哪个大师名册。",
+      "用户已经说清楚要什么（点了名册、说了「全部」、或说了「快点」），就不要再问——重复确认是打扰。",
+      "预估时间是相对量级，不是承诺。说清楚「大师多一倍，时间大概多这些」，不要报一个精确分钟数。",
+      "用户说「全都要」时照做，但先说一句它会明显更慢，让他们知道自己在换什么。",
+    ] : [
+      "Before starting, read the presets to the user and let them pick one, or name analysts and a master roster themselves.",
+      "If the user already said what they want -- named a roster, said 'everything', said 'be quick' -- do not ask. A confirmation they did not need is an interruption.",
+      "The estimates are relative magnitudes, not promises. Say that twice the bench costs roughly this much more; do not quote an exact number of minutes.",
+      "If they say 'run everything', do it -- but say once that it will be noticeably slower, so they know what they are trading.",
+    ],
+  };
+}

package/mcp/lib/errors.mjs

@@ -0,0 +1,46 @@
+/** JSON-RPC 2.0 reserved error codes. */
+export const RpcCode = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+};
+
+/**
+ * An error that already knows which JSON-RPC code it should surface as.
+ *
+ * Without this the RPC layer has to guess, and it used to guess INVALID_PARAMS for
+ * everything -- so a missing run directory or a failed network fetch was reported to
+ * the host as "you passed bad parameters".
+ */
+export class RpcError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.name = "RpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+export const invalidParams = (message, data) => new RpcError(RpcCode.INVALID_PARAMS, message, data);
+export const internalError = (message, data) => new RpcError(RpcCode.INTERNAL_ERROR, message, data);
+export const methodNotFound = (message, data) => new RpcError(RpcCode.METHOD_NOT_FOUND, message, data);
+
+/** Map any thrown value to a JSON-RPC error payload. */
+export function toRpcError(error) {
+  const debug = process.env.ALPHACOUNCIL_DEBUG === "1";
+  if (error instanceof RpcError) {
+    return {
+      code: error.code,
+      message: error.message,
+      ...(error.data !== undefined || debug ? { data: { ...(error.data ?? {}), ...(debug ? { stack: error.stack } : {}) } } : {}),
+    };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    code: RpcCode.INTERNAL_ERROR,
+    message,
+    ...(debug && error instanceof Error ? { data: { stack: error.stack } } : {}),
+  };
+}

package/mcp/lib/feeds.mjs

@@ -0,0 +1,140 @@
+import { LIMITS } from "./constants.mjs";
+import { secUserAgent } from "./sec.mjs";
+
+/**
+ * Minimal RSS/Atom reading, zero dependencies.
+ *
+ * The rule that makes this layer worth having is the recency gate: every item must carry a
+ * timestamp that parses and falls inside the requested window, or it is reported as
+ * excluded rather than quietly included. Without it a "latest news" section fills with
+ * three-year-old articles that read exactly like today's, and no reader can tell.
+ */
+
+const tag = (xml, name) => {
+  const m = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, "i").exec(xml);
+  return m ? decode(m[1]) : null;
+};
+
+/** Atom links carry the URL in an attribute rather than in the element body. */
+const atomLink = (xml) => {
+  const m = /<link[^>]*href=["']([^"']+)["'][^>]*>/i.exec(xml);
+  return m ? decode(m[1]) : null;
+};
+
+function decode(text) {
+  return String(text)
+    .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, d) => String.fromCharCode(Number(d)))
+    .replace(/&amp;/g, "&")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Parse RSS <item> and Atom <entry> into one shape. */
+export function parseFeed(xml, { source = null } = {}) {
+  const text = String(xml || "");
+  const blocks = text.match(/<(item|entry)\b[\s\S]*?<\/\1>/gi) || [];
+  return blocks.map((block) => {
+    const published = tag(block, "pubDate") || tag(block, "published") || tag(block, "updated") || null;
+    const at = published ? Date.parse(published) : NaN;
+    return {
+      title: tag(block, "title"),
+      link: tag(block, "link") || atomLink(block),
+      published_raw: published,
+      published_at: Number.isFinite(at) ? new Date(at).toISOString() : null,
+      source,
+    };
+  }).filter((item) => item.title);
+}
+
+/**
+ * Split items by whether their timestamp is inside the window.
+ *
+ * Undated items go to excluded, not to included. A headline with no date cannot be shown
+ * as recent, and guessing its date from position in the feed is how stale news gets
+ * presented as current.
+ */
+export function applyRecencyGate(items, { days = 14, asOf = null } = {}) {
+  const now = asOf ? Date.parse(`${asOf}T23:59:59Z`) : Date.now();
+  const floor = now - days * 86400000;
+  const included = [];
+  const excluded = [];
+  for (const item of items) {
+    const at = item.published_at ? Date.parse(item.published_at) : NaN;
+    if (!Number.isFinite(at)) excluded.push({ ...item, excluded_because: "no parsable timestamp" });
+    else if (at < floor) excluded.push({ ...item, excluded_because: `older than ${days}d` });
+    else if (at > now + 86400000) excluded.push({ ...item, excluded_because: "timestamp in the future" });
+    else included.push(item);
+  }
+  included.sort((a, b) => Date.parse(b.published_at) - Date.parse(a.published_at));
+  return { included, excluded };
+}
+
+export async function fetchFeed(url, { source = null, timeoutMs = LIMITS.QUOTE_FETCH_MS * 2 } = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: ctrl.signal,
+      // SEC requires a contact in the UA and returns 403 HTML without one; harmless elsewhere.
+      headers: { "User-Agent": secUserAgent(), Accept: "application/rss+xml, application/atom+xml, application/xml, text/xml, */*" },
+    });
+    if (!res.ok) return { url, source, ok: false, reason: `HTTP ${res.status}`, items: [] };
+    return { url, source, ok: true, items: parseFeed(await res.text(), { source }) };
+  } catch (error) {
+    return { url, source, ok: false, reason: String(error?.name === "AbortError" ? "timed out" : error?.message || error), items: [] };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Fetch several feeds concurrently; a dead feed is reported, never silently dropped. */
+export async function fetchFeeds(specs, { days = 14, asOf = null } = {}) {
+  const results = await Promise.all(specs.map((s) => fetchFeed(s.url, { source: s.source })));
+  const all = results.flatMap((r) => r.items);
+  const { included, excluded } = applyRecencyGate(all, { days, asOf });
+  return {
+    items: included,
+    feeds: results.map(({ url, source, ok, reason, items }) => ({ source, url, ok, reason, item_count: items.length })),
+    excluded_outside_window: excluded.length,
+    excluded_sample: excluded.slice(0, 5).map((e) => ({ title: e.title, published_at: e.published_at, why: e.excluded_because })),
+    unreachable: results.filter((r) => !r.ok).map((r) => ({ source: r.source, reason: r.reason })),
+  };
+}
+
+// ---- named feeds ----------------------------------------------------------
+
+export const tickerNewsFeed = (symbol) => ({
+  source: "Yahoo Finance RSS",
+  url: `https://feeds.finance.yahoo.com/rss/2.0/headline?s=${encodeURIComponent(symbol)}&region=US&lang=en-US`,
+});
+
+export const queryNewsFeed = (query) => ({
+  source: "Google News RSS",
+  url: `https://news.google.com/rss/search?q=${encodeURIComponent(query)}&hl=en-US&gl=US&ceid=US:en`,
+});
+
+/** A company's own filings, which are the one news source that cannot be spun. */
+export const filingsFeed = (cik, forms = "8-K") => ({
+  source: `SEC EDGAR ${forms}`,
+  url: "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany"
+    + `&CIK=${encodeURIComponent(String(cik).padStart(10, "0"))}`
+    + `&type=${encodeURIComponent(forms)}&dateb=&owner=include&count=40&output=atom`,
+});
+
+/**
+ * Broad feeds used to read what the market is talking about rather than what one company
+ * did. Deliberately mixes a regulator, a central bank and general market press: a theme
+ * that only appears in press is a story, one that also appears at the Fed is a policy fact.
+ */
+export const MARKET_FEEDS = [
+  { source: "Federal Reserve press", url: "https://www.federalreserve.gov/feeds/press_all.xml", kind: "policy" },
+  { source: "SEC press", url: "https://www.sec.gov/news/pressreleases.rss", kind: "policy" },
+  { source: "WSJ Markets", url: "https://feeds.a.dj.com/rss/RSSMarketsMain.xml", kind: "press" },
+  { source: "WSJ World News", url: "https://feeds.a.dj.com/rss/RSSWorldNews.xml", kind: "press" },
+  { source: "CNBC Finance", url: "https://search.cnbc.com/rs/search/combinedcms/view.xml?partnerId=wrss01&id=10000664", kind: "press" },
+  { source: "Yahoo Finance", url: "https://finance.yahoo.com/news/rssindex", kind: "press" },
+];

package/mcp/lib/fsutil.mjs

@@ -0,0 +1,69 @@
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { internalError, invalidParams } from "./errors.mjs";
+
+/**
+ * Write JSON atomically.
+ *
+ * collectEvidence commits packets from up to CONCURRENCY_MAX workers, and each commit
+ * rewrites evidence.json. A plain writeFileSync leaves a window where a concurrent
+ * reader (or a crash) sees a half-written file; write-then-rename does not.
+ */
+export function writeJson(path, value) {
+  const tmp = `${path}.tmp`;
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  try {
+    writeFileSync(tmp, body);
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // The temp file may never have been created; nothing to clean up.
+    }
+    throw internalError(`failed to write ${path}: ${error.message}`);
+  }
+}
+
+export function readJson(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") throw invalidParams(`not found: ${path}`);
+    throw internalError(`failed to read ${path}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw internalError(`corrupt JSON at ${path}: ${error.message}`);
+  }
+}
+
+/**
+ * Read newline-delimited JSON, skipping unparseable lines.
+ *
+ * events.jsonl is append-only and a crashed run can leave one truncated line. That must
+ * not make the whole run unreadable, so bad lines are counted and reported instead of
+ * thrown.
+ */
+export function readJsonl(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { entries: [], parse_errors: 0 };
+    throw internalError(`failed to read ${path}: ${error.message}`);
+  }
+  const entries = [];
+  let parse_errors = 0;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      parse_errors += 1;
+    }
+  }
+  return { entries, parse_errors };
+}