opencandle 0.3.0 → 0.4.0

package/src/tool-kit.ts

@@ -0,0 +1,68 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { agentToolToPiTool } from "./pi/tool-adapter.js";
+
+// Re-exports for tool authors — import from "opencandle/tool-kit"
+export { cache, Cache, TTL } from "./infra/cache.js";
+export { rateLimiter, RateLimiter } from "./infra/rate-limiter.js";
+export { httpGet, HttpError, type HttpClientOptions } from "./infra/http-client.js";
+export { agentToolToPiTool } from "./pi/tool-adapter.js";
+export { Type } from "@sinclair/typebox";
+export type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export type { AgentTool } from "@earendil-works/pi-agent-core";
+
+// Module-level registry — all extensions run in the same Node.js process,
+// so keep a deduped index keyed by tool name.
+const addonToolRegistry = new Map<string, { name: string; description: string }>();
+
+export function getAddonToolDescriptions(): ReadonlyArray<{ name: string; description: string }> {
+  return Array.from(addonToolRegistry.values());
+}
+
+const SNAKE_CASE_VERB_RE = /^(get|analyze|search|calculate|compare|compute|track|manage|backtest|list|fetch|check)_[a-z][a-z0-9_]*$/;
+
+export interface ToolConfig<TParams extends TSchema, TDetails = unknown> {
+  name: string;
+  label: string;
+  description: string;
+  parameters: TParams;
+  execute: AgentTool<TParams, TDetails>["execute"];
+}
+
+export function createTool<TParams extends TSchema, TDetails = unknown>(
+  config: ToolConfig<TParams, TDetails>,
+): AgentTool<TParams, TDetails> {
+  if (!config.name || !SNAKE_CASE_VERB_RE.test(config.name)) {
+    throw new Error(
+      `Invalid tool name "${config.name}": must be snake_case and start with a verb prefix ` +
+      `(get_, analyze_, search_, calculate_, compare_, compute_, track_, manage_, backtest_, list_, fetch_, check_)`,
+    );
+  }
+  if (!config.description || config.description.trim().length === 0) {
+    throw new Error(`Tool "${config.name}" requires a non-empty description`);
+  }
+  if (!config.parameters) {
+    throw new Error(`Tool "${config.name}" requires parameters (Typebox schema)`);
+  }
+  return {
+    name: config.name,
+    label: config.label,
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute,
+  };
+}
+
+export function registerTools<TParams extends TSchema>(
+  pi: ExtensionAPI,
+  tools: AgentTool<TParams>[],
+): void {
+  for (const tool of tools) {
+    if (addonToolRegistry.has(tool.name)) {
+      console.warn(`[opencandle] Warning: tool "${tool.name}" already registered (overwriting)`);
+    }
+    pi.registerTool(agentToolToPiTool(tool));
+    addonToolRegistry.set(tool.name, { name: tool.name, description: tool.description });
+  }
+}

package/src/tools/AGENTS.md

@@ -0,0 +1,36 @@
+# TOOLS
+
+Market analysis tools organized by financial domain. Tools fetch data from `src/providers/`, return structured results for LLM synthesis.
+
+## STRUCTURE
+```
+src/tools/
+├── fundamentals/  # Earnings, financials, DCF, comps, SEC filings
+├── technical/     # Indicators (SMA, RSI, MACD), backtesting
+├── options/       # Options chains, Greeks computation
+├── macro/         # FRED economic data, fear & greed index
+├── sentiment/     # Reddit sentiment, news sentiment
+├── portfolio/     # Tracker, risk analysis, watchlist, correlation, predictions
+├── market/        # Stock quotes, history, crypto, ticker search
+└── index.ts       # getAllTools() registry — add new tools here
+```
+
+## LOOKUP
+| Domain | Location |
+|--------|----------|
+| P/E, EPS, balance sheets, DCF | `fundamentals/` |
+| RSI, MACD, SMA, backtest | `technical/` |
+| Put/call ratio, IV, Greeks | `options/` |
+| GDP, inflation, Fed rates | `macro/` |
+| Reddit buzz, news | `sentiment/` |
+| Positions, Sharpe, VaR, watchlist | `portfolio/` |
+| Quotes, OHLCV, crypto, search | `market/` |
+
+## ADDING A TOOL
+1. Create `src/tools/<domain>/my-tool.ts` with Typebox params + `AgentTool` export.
+2. Register in `src/tools/index.ts` (`getAllTools()` array).
+3. Add test in `tests/unit/tools/` with fixture-based fetch mocking.
+
+## ANTI-PATTERNS
+- Never hardcode mock data in tools; call providers.
+- Tools return structured data. The LLM analyzes it, not the tool.

package/src/tools/fundamentals/company-overview.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getOverview } from "../../providers/alpha-vantage.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
+import type { CompanyOverview } from "../../types/fundamentals.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+});
+
+export const companyOverviewTool: AgentTool<typeof params, CompanyOverview | { credentialRequired: unknown }> = {
+  name: "get_company_overview",
+  label: "Company Overview",
+  description:
+    "Get company fundamentals: P/E ratio, EPS, market cap, sector, dividend yield, profit margin, beta, and description. Requires Alpha Vantage.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    return withCredentialCheck("alpha_vantage", async () => {
+      const apiKey = getConfig().alphaVantageApiKey!;
+      const result = await wrapProvider("alphavantage", () => getOverview(args.symbol.toUpperCase(), apiKey));
+      if (result.status === "unavailable") {
+        return {
+          content: [{ type: "text", text: `⚠ Company overview unavailable for ${args.symbol.toUpperCase()} (${result.reason}). Analysis will proceed without fundamentals.` }],
+          details: null as any,
+        };
+      }
+      const ov = result.data;
+      const text = [
+        `**${ov.name}** (${ov.symbol}) — ${ov.exchange}`,
+        `Sector: ${ov.sector} | Industry: ${ov.industry}`,
+        `Market Cap: $${formatLargeNumber(ov.marketCap)} | P/E: ${ov.pe ?? "N/A"} | Fwd P/E: ${ov.forwardPe ?? "N/A"}`,
+        `EPS: $${ov.eps ?? "N/A"} | Div Yield: ${ov.dividendYield ? (ov.dividendYield * 100).toFixed(2) + "%" : "N/A"}`,
+        `Beta: ${ov.beta ?? "N/A"} | Profit Margin: ${ov.profitMargin ? (ov.profitMargin * 100).toFixed(1) + "%" : "N/A"}`,
+        `52W: $${ov.week52Low.toFixed(2)} - $${ov.week52High.toFixed(2)}`,
+        ``,
+        ov.description.slice(0, 300) + (ov.description.length > 300 ? "..." : ""),
+      ].join("\n");
+
+      const prefix = result.stale
+        ? `⚠ Using cached fundamentals from ${result.timestamp} (Alpha Vantage rate limited)\n`
+        : "";
+      return { content: [{ type: "text", text: prefix + text }], details: ov };
+    });
+  },
+};
+
+function formatLargeNumber(n: number): string {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  return n.toLocaleString();
+}

package/src/tools/fundamentals/comps.ts

@@ -0,0 +1,156 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getOverview } from "../../providers/alpha-vantage.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
+import type { CompanyOverview } from "../../types/fundamentals.js";
+
+export interface CompsMetric {
+  metric: string;
+  values: Record<string, number | null>;
+  median: number | null;
+  p25: number | null;
+  p75: number | null;
+  best: string;
+  worst: string;
+}
+
+export interface CompsResult {
+  companies: CompanyOverview[];
+  metrics: CompsMetric[];
+  unavailableSymbols: string[];
+}
+
+type MetricDef = {
+  name: string;
+  extract: (c: CompanyOverview) => number | null;
+  lowerIsBetter: boolean;
+};
+
+const METRIC_DEFS: MetricDef[] = [
+  { name: "P/E", extract: (c) => c.pe, lowerIsBetter: true },
+  { name: "Forward P/E", extract: (c) => c.forwardPe, lowerIsBetter: true },
+  { name: "EPS", extract: (c) => c.eps, lowerIsBetter: false },
+  { name: "Profit Margin", extract: (c) => c.profitMargin, lowerIsBetter: false },
+  { name: "Revenue Growth", extract: (c) => c.revenueGrowth, lowerIsBetter: false },
+  { name: "Dividend Yield", extract: (c) => c.dividendYield, lowerIsBetter: false },
+  { name: "Beta", extract: (c) => c.beta, lowerIsBetter: true },
+];
+
+export function computeComps(companies: CompanyOverview[]): CompsResult {
+  const metrics: CompsMetric[] = METRIC_DEFS.map((def) => {
+    const values: Record<string, number | null> = {};
+    for (const c of companies) {
+      values[c.symbol] = def.extract(c);
+    }
+
+    const nonNull = Object.entries(values)
+      .filter(([, v]) => v != null)
+      .map(([sym, v]) => ({ sym, v: v! }));
+
+    const sorted = [...nonNull].sort((a, b) => a.v - b.v);
+    const sortedVals = sorted.map((s) => s.v);
+    const median = computeMedian(sortedVals);
+    const p25 = computePercentile(sortedVals, 0.25);
+    const p75 = computePercentile(sortedVals, 0.75);
+
+    const best = def.lowerIsBetter ? sorted[0]?.sym ?? "" : sorted[sorted.length - 1]?.sym ?? "";
+    const worst = def.lowerIsBetter ? sorted[sorted.length - 1]?.sym ?? "" : sorted[0]?.sym ?? "";
+
+    return { metric: def.name, values, median, p25, p75, best, worst };
+  });
+
+  return { companies, metrics, unavailableSymbols: [] };
+}
+
+function computeMedian(sorted: number[]): number | null {
+  if (sorted.length === 0) return null;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0
+    ? (sorted[mid - 1] + sorted[mid]) / 2
+    : sorted[mid];
+}
+
+function computePercentile(sorted: number[], p: number): number | null {
+  if (sorted.length === 0) return null;
+  if (sorted.length === 1) return sorted[0];
+  const idx = p * (sorted.length - 1);
+  const lower = Math.floor(idx);
+  const upper = Math.ceil(idx);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
+}
+
+const params = Type.Object({
+  symbols: Type.Array(Type.String(), {
+    description: "Array of 2-6 ticker symbols to compare (e.g. ['AAPL','MSFT','GOOGL'])",
+    minItems: 2,
+    maxItems: 6,
+  }),
+});
+
+export const compsTool: AgentTool<typeof params> = {
+  name: "compare_companies",
+  label: "Comparable Company Analysis",
+  description:
+    "Compare 2-6 companies side-by-side on key valuation and financial metrics: P/E, Forward P/E, EPS, Profit Margin, Revenue Growth, Dividend Yield, Beta. Identifies the cheapest and most expensive on each metric.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    return withCredentialCheck("alpha_vantage", async () => {
+    const config = getConfig();
+    const symbols = args.symbols.map((s) => s.toUpperCase());
+
+    const results = await Promise.all(
+      symbols.map(async (s) => ({
+        symbol: s,
+        result: await wrapProvider("alphavantage", () => getOverview(s, config.alphaVantageApiKey!)),
+      })),
+    );
+
+    const companies: CompanyOverview[] = [];
+    const unavailableSymbols: string[] = [];
+
+    for (const { symbol: sym, result: r } of results) {
+      if (r.status === "ok") {
+        companies.push(r.data);
+      } else {
+        unavailableSymbols.push(sym);
+      }
+    }
+
+    if (companies.length === 0) {
+      return {
+        content: [{ type: "text", text: `⚠ Company fundamentals unavailable for all symbols: ${symbols.join(", ")}. Alpha Vantage may be rate limited.` }],
+        details: null as any,
+      };
+    }
+
+    const result = computeComps(companies);
+    result.unavailableSymbols = unavailableSymbols;
+
+    const availableSymbols = companies.map((company) => company.symbol);
+    const header = `**Comparable Company Analysis**: ${availableSymbols.join(" vs ")}`;
+    const rows = result.metrics.map((m) => {
+      const vals = availableSymbols.map((s) => {
+        const v = m.values[s];
+        if (v == null) return "N/A".padStart(10);
+        if (Math.abs(v) < 1) return `${(v * 100).toFixed(1)}%`.padStart(10);
+        return v.toFixed(2).padStart(10);
+      });
+      const medStr = m.median != null
+        ? (Math.abs(m.median) < 1 ? `${(m.median * 100).toFixed(1)}%` : m.median.toFixed(2))
+        : "N/A";
+      return `  ${m.metric.padEnd(16)} ${vals.join("")}  Med: ${medStr}  Best: ${m.best}`;
+    });
+
+    const symHeader = `  ${"Metric".padEnd(16)} ${availableSymbols.map((s) => s.padStart(10)).join("")}`;
+    const noteLines = unavailableSymbols.length > 0
+      ? ["", `Unavailable fundamentals: ${unavailableSymbols.join(", ")}`]
+      : [];
+    const text = [header, "", symHeader, ...rows, ...noteLines].join("\n");
+
+    return { content: [{ type: "text", text }], details: result };
+    });
+  },
+};

package/src/tools/fundamentals/dcf.ts

@@ -0,0 +1,267 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getOverview, getFinancials } from "../../providers/alpha-vantage.js";
+import { getQuote } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
+import type { FinancialStatement } from "../../types/fundamentals.js";
+
+export interface DCFResult {
+  intrinsicValue: number;
+  enterpriseValue: number;
+  terminalValue: number;
+  netDebt: number;
+  projectedCashFlows: Array<{ year: number; fcf: number; presentValue: number }>;
+  assumptions: {
+    fcf: number;
+    growthRate: number;
+    discountRate: number;
+    terminalGrowth: number;
+    years: number;
+  };
+  sensitivityTable: Array<{ growthRate: number; discountRate: number; intrinsicValue: number }>;
+  warnings: string[];
+}
+
+export interface DCFParams {
+  freeCashFlow: number;
+  growthRate: number;
+  discountRate: number;
+  terminalGrowth: number;
+  years: number;
+  netDebt: number;
+  sharesOutstanding: number;
+}
+
+export function computeDCF(params: DCFParams): DCFResult {
+  const { freeCashFlow, growthRate, discountRate, terminalGrowth, years, netDebt, sharesOutstanding } = params;
+
+  // Project future cash flows (mid-year convention: discount at year-0.5)
+  const projectedCashFlows: Array<{ year: number; fcf: number; presentValue: number }> = [];
+  for (let y = 1; y <= years; y++) {
+    const fcf = freeCashFlow * (1 + growthRate) ** y;
+    const pv = fcf / (1 + discountRate) ** (y - 0.5); // mid-year convention
+    projectedCashFlows.push({ year: y, fcf, presentValue: pv });
+  }
+
+  // Terminal value (Gordon Growth Model), discounted at full year (end of projection)
+  const finalFCF = freeCashFlow * (1 + growthRate) ** years;
+  const terminalValue = (finalFCF * (1 + terminalGrowth)) / (discountRate - terminalGrowth);
+  const pvTerminal = terminalValue / (1 + discountRate) ** years;
+
+  // Enterprise value
+  const sumPVs = projectedCashFlows.reduce((s, cf) => s + cf.presentValue, 0);
+  const enterpriseValue = sumPVs + pvTerminal;
+
+  // Equity value → per share
+  const equityValue = enterpriseValue - netDebt;
+  const intrinsicValue = equityValue / sharesOutstanding;
+
+  // Sensitivity table: vary growth ±2% and discount ±2%
+  const sensitivityTable: Array<{ growthRate: number; discountRate: number; intrinsicValue: number }> = [];
+  for (let gDelta = -0.02; gDelta <= 0.02; gDelta += 0.01) {
+    for (let dDelta = -0.02; dDelta <= 0.02; dDelta += 0.01) {
+      const g = growthRate + gDelta;
+      const d = discountRate + dDelta;
+      if (d <= terminalGrowth || d <= 0 || g < 0) continue;
+      const sensResult = computeDCFSimple(freeCashFlow, g, d, terminalGrowth, years, netDebt, sharesOutstanding);
+      sensitivityTable.push({ growthRate: g, discountRate: d, intrinsicValue: sensResult });
+    }
+  }
+
+  // Validation warnings (inspired by Anthropic financial plugins + Dexter)
+  const warnings: string[] = [];
+  const tvPctOfEV = pvTerminal / enterpriseValue;
+  if (tvPctOfEV > 0.85) {
+    warnings.push(`Terminal value is ${(tvPctOfEV * 100).toFixed(0)}% of enterprise value (typical: 40-80%). The valuation is heavily dependent on terminal assumptions.`);
+  }
+  const spreadPct = discountRate - terminalGrowth;
+  if (spreadPct < 0.02) {
+    warnings.push(`Terminal growth (${(terminalGrowth * 100).toFixed(1)}%) is very close to discount rate (${(discountRate * 100).toFixed(1)}%). Small changes in assumptions will produce large swings in value.`);
+  }
+  if (discountRate < 0.05 || discountRate > 0.20) {
+    warnings.push(`Discount rate of ${(discountRate * 100).toFixed(1)}% is outside typical WACC range (5-20%).`);
+  }
+  if (growthRate > 0.20) {
+    warnings.push(`Growth rate of ${(growthRate * 100).toFixed(1)}% exceeds 20%. High growth is difficult to sustain — consider a multi-stage model.`);
+  }
+
+  return {
+    intrinsicValue,
+    enterpriseValue,
+    terminalValue,
+    netDebt,
+    projectedCashFlows,
+    assumptions: {
+      fcf: freeCashFlow,
+      growthRate,
+      discountRate,
+      terminalGrowth,
+      years,
+    },
+    sensitivityTable,
+    warnings,
+  };
+}
+
+function computeDCFSimple(
+  fcf: number, g: number, d: number, tg: number, years: number, debt: number, shares: number,
+): number {
+  let sumPV = 0;
+  for (let y = 1; y <= years; y++) {
+    sumPV += (fcf * (1 + g) ** y) / (1 + d) ** (y - 0.5); // mid-year convention
+  }
+  const finalFCF = fcf * (1 + g) ** years;
+  const tv = (finalFCF * (1 + tg)) / (d - tg);
+  const pvTV = tv / (1 + d) ** years;
+  return (sumPV + pvTV - debt) / shares;
+}
+
+export function computeNetDebt(f: FinancialStatement): number {
+  if (f.totalDebt != null && f.cashAndEquivalents != null) {
+    return f.totalDebt - f.cashAndEquivalents;
+  }
+  // Fallback: totalLiabilities - totalAssets (negative means net cash position)
+  return f.totalLiabilities - f.totalAssets;
+}
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+  growth_rate: Type.Optional(
+    Type.Number({ description: "Annual FCF growth rate as decimal (e.g. 0.10 for 10%). If omitted, estimated from historical data." }),
+  ),
+  discount_rate: Type.Optional(
+    Type.Number({ description: "Discount rate / WACC as decimal (default: 0.10 for 10%)" }),
+  ),
+  terminal_growth: Type.Optional(
+    Type.Number({ description: "Terminal growth rate as decimal (default: 0.03 for 3%)" }),
+  ),
+  projection_years: Type.Optional(
+    Type.Number({ description: "Years to project forward (default: 5)" }),
+  ),
+});
+
+export const dcfTool: AgentTool<typeof params> = {
+  name: "compute_dcf",
+  label: "DCF Valuation",
+  description:
+    "Compute a Discounted Cash Flow (DCF) intrinsic value estimate for a stock. Uses free cash flow, growth projections, and a discount rate to estimate what the stock is worth. Returns intrinsic value per share, margin of safety vs current price, and a sensitivity table.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    return withCredentialCheck("alpha_vantage", async () => {
+    const symbol = args.symbol.toUpperCase();
+    const config = getConfig();
+
+    const [overviewResult, financialsResult, quoteResult] = await Promise.all([
+      wrapProvider("alphavantage", () => getOverview(symbol, config.alphaVantageApiKey!)),
+      wrapProvider("alphavantage", () => getFinancials(symbol, config.alphaVantageApiKey!)),
+      wrapProvider("yahoo", () => getQuote(symbol)),
+    ]);
+
+    const missing: string[] = [];
+    if (overviewResult.status === "unavailable") missing.push(`company overview (${overviewResult.reason})`);
+    if (financialsResult.status === "unavailable") missing.push(`financial statements (${financialsResult.reason})`);
+    if (quoteResult.status === "unavailable") missing.push(`stock quote (${quoteResult.reason})`);
+
+    if (financialsResult.status === "unavailable" || quoteResult.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ DCF valuation unavailable for ${symbol}. Missing: ${missing.join(", ")}. Both financials and current price are required.` }],
+        details: null,
+      };
+    }
+
+    const overview = overviewResult.status === "ok" ? overviewResult.data : null;
+    const financials = financialsResult.data;
+    const quote = quoteResult.data;
+
+    const latestFCF = financials[0]?.freeCashFlow ?? 0;
+    if (latestFCF <= 0) {
+      return {
+        content: [{ type: "text", text: `${symbol} has negative or zero free cash flow ($${latestFCF.toLocaleString()}). DCF is not meaningful for companies without positive FCF.` }],
+        details: null,
+      };
+    }
+
+    // Estimate growth from historical FCF if not provided
+    let growthRate = args.growth_rate ?? 0.10;
+    if (!args.growth_rate && financials.length >= 2) {
+      const olderFCF = financials[1]?.freeCashFlow;
+      if (olderFCF && olderFCF > 0) {
+        growthRate = Math.max(0.02, Math.min(0.25, (latestFCF - olderFCF) / olderFCF));
+      }
+    }
+
+    const discountRate = args.discount_rate ?? 0.10;
+    const terminalGrowth = args.terminal_growth ?? 0.03;
+    const years = args.projection_years ?? 5;
+    const marketCap = overview?.marketCap ?? 0;
+    const sharesOutstanding = quote.price > 0 && marketCap > 0 ? marketCap / quote.price : 1;
+    const netDebt = financials[0] ? computeNetDebt(financials[0]) : 0;
+
+    const result = computeDCF({
+      freeCashFlow: latestFCF,
+      growthRate,
+      discountRate,
+      terminalGrowth,
+      years,
+      netDebt: Math.max(0, netDebt),
+      sharesOutstanding,
+    });
+
+    const marginOfSafety = (result.intrinsicValue - quote.price) / result.intrinsicValue;
+    const upside = (result.intrinsicValue - quote.price) / quote.price;
+
+    const lines = [
+      `**${symbol} DCF Valuation**`,
+      ``,
+      `Current Price: $${quote.price.toFixed(2)}`,
+      `Intrinsic Value: $${result.intrinsicValue.toFixed(2)}`,
+      `Margin of Safety: ${(marginOfSafety * 100).toFixed(1)}%`,
+      `Upside/Downside: ${upside >= 0 ? "+" : ""}${(upside * 100).toFixed(1)}%`,
+      ``,
+      `**Assumptions**`,
+      `Free Cash Flow: $${(latestFCF / 1e9).toFixed(2)}B`,
+      `Growth Rate: ${(growthRate * 100).toFixed(1)}%`,
+      `Discount Rate (WACC): ${(discountRate * 100).toFixed(1)}%`,
+      `Terminal Growth: ${(terminalGrowth * 100).toFixed(1)}%`,
+      `Projection: ${years} years`,
+      ``,
+      `**Projected Cash Flows**`,
+      ...result.projectedCashFlows.map((cf) =>
+        `  Year ${cf.year}: FCF $${(cf.fcf / 1e9).toFixed(2)}B → PV $${(cf.presentValue / 1e9).toFixed(2)}B`
+      ),
+      `  Terminal Value: $${(result.terminalValue / 1e9).toFixed(2)}B`,
+      `  Enterprise Value: $${(result.enterpriseValue / 1e9).toFixed(2)}B`,
+      ``,
+      `**Sensitivity Table** (Intrinsic Value at different Growth/Discount rates)`,
+      ...formatSensitivityTable(result.sensitivityTable),
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { ...result, currentPrice: quote.price, marginOfSafety, upside },
+    };
+    });
+  },
+};
+
+function formatSensitivityTable(
+  table: Array<{ growthRate: number; discountRate: number; intrinsicValue: number }>,
+): string[] {
+  if (table.length === 0) return ["  (insufficient data for sensitivity table)"];
+
+  const discountRates = [...new Set(table.map((e) => e.discountRate))].sort((a, b) => a - b);
+  const growthRates = [...new Set(table.map((e) => e.growthRate))].sort((a, b) => a - b);
+
+  const header = `  ${"Growth↓/WACC→".padEnd(14)} ${discountRates.map((d) => `${(d * 100).toFixed(0)}%`.padStart(8)).join("")}`;
+  const rows = growthRates.map((g) => {
+    const cells = discountRates.map((d) => {
+      const entry = table.find((e) => e.growthRate === g && e.discountRate === d);
+      return entry ? `$${entry.intrinsicValue.toFixed(0)}`.padStart(8) : "N/A".padStart(8);
+    });
+    return `  ${`${(g * 100).toFixed(0)}%`.padEnd(14)} ${cells.join("")}`;
+  });
+
+  return [header, ...rows];
+}

package/src/tools/fundamentals/earnings.ts

@@ -0,0 +1,47 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getEarnings } from "../../providers/alpha-vantage.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
+import type { EarningsData } from "../../types/fundamentals.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+});
+
+export const earningsTool: AgentTool<typeof params, EarningsData | { credentialRequired: unknown }> = {
+  name: "get_earnings",
+  label: "Earnings History",
+  description:
+    "Get quarterly earnings: reported EPS, estimated EPS, and surprise percentage for the last 8 quarters. Requires Alpha Vantage.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    return withCredentialCheck("alpha_vantage", async () => {
+      const apiKey = getConfig().alphaVantageApiKey!;
+      const result = await wrapProvider("alphavantage", () => getEarnings(args.symbol.toUpperCase(), apiKey));
+      if (result.status === "unavailable") {
+        return {
+          content: [{ type: "text", text: `⚠ Earnings data unavailable for ${args.symbol.toUpperCase()} (${result.reason}). Analysis will proceed without earnings history.` }],
+          details: null as any,
+        };
+      }
+      const earnings = result.data;
+      if (earnings.quarterly.length === 0) {
+        return {
+          content: [{ type: "text", text: `No earnings data found for ${args.symbol}` }],
+          details: earnings,
+        };
+      }
+
+      const header = `${args.symbol.toUpperCase()} — Quarterly Earnings (last ${earnings.quarterly.length} quarters)`;
+      const rows = earnings.quarterly.map((q) => {
+        const sign = q.surprisePercent >= 0 ? "+" : "";
+        return `${q.date} | Reported: $${q.reportedEPS.toFixed(2)} | Est: $${q.estimatedEPS.toFixed(2)} | Surprise: ${sign}${q.surprisePercent.toFixed(1)}%`;
+      });
+
+      const text = [header, ...rows].join("\n");
+      return { content: [{ type: "text", text }], details: earnings };
+    });
+  },
+};