alphacouncil-agent 0.9.2 → 1.0.0

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,23 +52,48 @@ 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) => [
+        role,
+        Object.keys(visibleDebate.rounds?.[role] || {}).map(Number).filter(Number.isInteger).sort((a, b) => a - b),
+      ]))
+    : null;
   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,
     council_mode: run.council_mode || "full",
     debate_format: run.debate_format || "three_round_cross_exam",
+    visible_debate_contract: visibleDebate?.contract || null,
+    visible_debate_rounds_expected: visibleDebate?.rounds_expected || null,
+    visible_debate_rounds_recorded: visibleDebateRounds,
+    visible_debate_qna_gate: visibleDebate?.qna_gate?.status || null,
     report_contract: run.council_mode === "quick" ? "quick_v1" : "full_v2",
     full_council_equivalent: run.council_mode !== "quick",
+    master_worker_contract: run.execution_mode === "background_codex_exec"
+      ? "one_isolated_worker_per_selected_method_v1"
+      : run.execution_mode === "dry_run"
+        ? "planned_not_executed"
+        : "host_managed_not_plugin_enforced",
+    deadline_enforced: run.deadline_enforced === true,
     time_budget_ms: run.time_budget_ms || null,
     deadline_at: run.deadline_at || null,
     remaining_budget_ms: run.deadline_at
       ? Math.max(0, Date.parse(run.deadline_at) - Date.now())
       : null,
+    elapsed_ms: run.started_at
+      ? Math.max(0, Date.parse(run.completed_at || new Date().toISOString()) - Date.parse(run.started_at))
+      : null,
+    deadline_met: run.deadline_at && run.completed_at
+      ? Date.parse(run.completed_at) <= Date.parse(run.deadline_at)
+      : null,
     visibility_required: run.visibility_required,
     dry_run: run.dry_run,
     status: run.status,

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(" ");
+}

package/mcp/lib/xbrl-aggregates.mjs

@@ -0,0 +1,153 @@
+/**
+ * Fiscal-year aggregates assembled from an aligned XBRL series.
+ *
+ * These answer "what does this filer report for year N", not "is that good". Debt is summed
+ * from non-overlapping buckets and names the ones a filer omits; tangible book deducts what
+ * is tagged and records the reading when a concept is absent from the whole document; the
+ * trailing-four-quarters window checks its own seams. Each returns null rather than zero when
+ * the filings do not support the figure -- a company with unknown debt is not a debt-free one.
+ */
+
+import {
+  DEBT_BUCKETS,
+  FUNDAMENTAL_CONCEPTS,
+  alignYear,
+  daysBetween,
+  decimal,
+  fiscalYearOf,
+  gap,
+} from "./xbrl-series.mjs";
+
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+
+/**
+ * Both endpoints on one profit basis. Pairing a NOPAT endpoint with a net-income endpoint
+ * would difference two different quantities and call the result a return.
+ */
+/** Four contiguous quarters ending at `index`, or null when a quarter is missing or overlaps. */
+/**
+ * Profit for the incremental-return window: NOPAT when the tax inputs exist, otherwise net
+ * income -- and the basis is named in the output rather than left for the reader to guess.
+ */
+/**
+ * Tangible book value: equity less goodwill and intangibles.
+ *
+ * A filer with goodwill on its balance sheet must tag it, so a concept absent from every
+ * period of the document is evidence of nil rather than a data gap -- and that reading is
+ * still written into `assumptions`. A concept reported in other years but not this one is
+ * treated as a genuine misalignment and refuses to compute.
+ */
+/**
+ * Total debt for one fiscal year.
+ *
+ * A single combined tag wins outright. Otherwise the three non-overlapping buckets are summed
+ * and the ones a filer does not report are named in `missing_buckets` rather than assumed
+ * away silently. No bucket at all is null, never zero: a company with unknown debt is not a
+ * debt-free company.
+ */
+export function totalDebtForYear(series, fiscalYear) {
+  const combined = series.debt_combined.find((entry) => entry.fiscal_year === fiscalYear);
+  if (combined) {
+    return { value: combined.value, entries: [combined], buckets: ["debt_combined"], missing_buckets: [] };
+  }
+  const present = DEBT_BUCKETS
+    .map((bucket) => ({ bucket, entry: series[bucket].find((item) => item.fiscal_year === fiscalYear) }))
+    .filter((item) => item.entry);
+  if (!present.length) return null;
+  return {
+    value: sum(present.map((item) => item.entry.value)),
+    entries: present.map((item) => item.entry),
+    buckets: present.map((item) => item.bucket),
+    missing_buckets: DEBT_BUCKETS.filter((bucket) => !present.some((item) => item.bucket === bucket)),
+  };
+}
+
+export function tangibleBookForYear(series, fiscalYear) {
+  const equity = series.equity.find((entry) => entry.fiscal_year === fiscalYear);
+  if (!equity) return null;
+  const deductions = [];
+  const assumptions = [];
+  const entries = [equity];
+  for (const concept of ["goodwill", "intangibles"]) {
+    const entry = series[concept].find((item) => item.fiscal_year === fiscalYear);
+    if (entry) {
+      deductions.push({ concept, tag: entry.tag, value: entry.value });
+      entries.push(entry);
+      continue;
+    }
+    if (series[concept].length) return { misaligned: concept };
+    assumptions.push(`${concept} is not tagged in any period of this filer's Company Facts and is treated as 0`);
+  }
+  return {
+    value: equity.value - sum(deductions.map((item) => item.value)),
+    equity: equity.value,
+    deductions,
+    assumptions,
+    entries,
+  };
+}
+
+export function profitForYear(series, fiscalYear) {
+  const nopat = alignYear(series, ["operating_income", "tax_expense", "pretax_income"], fiscalYear);
+  if (nopat.ok && nopat.entries.pretax_income.value > 0) {
+    const rate = nopat.entries.tax_expense.value / nopat.entries.pretax_income.value;
+    if (rate >= 0 && rate < 1) {
+      return {
+        basis: "nopat",
+        value: nopat.entries.operating_income.value * (1 - rate),
+        effective_tax_rate: decimal(rate),
+        entries: nopat.used,
+      };
+    }
+  }
+  const netIncome = series.net_income.find((entry) => entry.fiscal_year === fiscalYear);
+  if (!netIncome) return null;
+  return { basis: "net_income", value: netIncome.value, effective_tax_rate: null, entries: [netIncome] };
+}
+
+export function fourQuarters(quarters, index) {
+  if (index < 3) return null;
+  const window = quarters.slice(index - 3, index + 1);
+  const span = daysBetween(window[0].start, window.at(-1).end);
+  if (span < 330 || span > 400) return null;
+  for (let position = 1; position < window.length; position += 1) {
+    const seam = daysBetween(window[position - 1].end, window[position].start);
+    if (seam < -5 || seam > 15) return null;
+  }
+  return { total: sum(window.map((entry) => entry.val)), window };
+}
+
+export function matchedProfits(series, startYear, endYear) {
+  const profits = [startYear, endYear].map((year) => profitForYear(series, year));
+  if (profits.some((profit) => !profit)) return null;
+  if (profits.every((profit) => profit.basis === "nopat")) return { basis: "nopat", profits };
+  const fallback = [startYear, endYear]
+    .map((year) => series.net_income.find((entry) => entry.fiscal_year === year));
+  if (fallback.some((entry) => !entry)) return null;
+  return {
+    basis: "net_income",
+    profits: fallback.map((entry) => ({ basis: "net_income", value: entry.value, entries: [entry] })),
+  };
+}
+
+export function investedCapital(series, fiscalYear) {
+  const alignment = alignYear(series, ["equity", "cash"], fiscalYear);
+  if (!alignment.ok) return null;
+  const debt = totalDebtForYear(series, fiscalYear);
+  if (!debt) return null;
+  return {
+    value: alignment.entries.equity.value + debt.value - alignment.entries.cash.value,
+    period_end: alignment.period_end,
+    entries: [...alignment.used, ...debt.entries],
+  };
+}
+
+export function ebitdaForYear(series, fiscalYear) {
+  const alignment = alignYear(series, ["operating_income", "depreciation_amortisation"], fiscalYear);
+  if (!alignment.ok) return null;
+  return {
+    value: alignment.entries.operating_income.value + alignment.entries.depreciation_amortisation.value,
+    entries: alignment.used,
+  };
+}