opencandle 0.3.0 → 0.5.0

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

package/src/tools/fundamentals/financials.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getFinancials } 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 { FinancialStatement } from "../../types/fundamentals.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+});
+
+export const financialsTool: AgentTool<typeof params, FinancialStatement[] | { credentialRequired: unknown }> = {
+  name: "get_financials",
+  label: "Financial Statements",
+  description:
+    "Get annual income statement data: revenue, gross profit, operating income, net income, and EPS. Requires Alpha Vantage.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    return withCredentialCheck("alpha_vantage", async () => {
+      const apiKey = getConfig().alphaVantageApiKey!;
+      const result = await wrapProvider("alphavantage", () =>
+        getFinancials(args.symbol.toUpperCase(), apiKey),
+      );
+      if (result.status === "unavailable") {
+        return {
+          content: [{ type: "text", text: `⚠ Financial statements unavailable for ${args.symbol.toUpperCase()} (${result.reason}). Analysis will proceed without financials.` }],
+          details: [],
+        };
+      }
+      const statements = result.data;
+      if (statements.length === 0) {
+        return {
+          content: [{ type: "text", text: `No financial data found for ${args.symbol}` }],
+          details: [],
+        };
+      }
+
+      const header = `${args.symbol.toUpperCase()} — Annual Income Statement (${statements.length} years)`;
+      const rows = statements.map((s) =>
+        `${s.fiscalDate} | Rev: $${fmt(s.revenue)} | GP: $${fmt(s.grossProfit)} | OpInc: $${fmt(s.operatingIncome)} | Net: $${fmt(s.netIncome)}`,
+      );
+
+      const text = [header, ...rows].join("\n");
+      return { content: [{ type: "text", text }], details: statements };
+    });
+  },
+};
+
+function fmt(n: number): string {
+  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/sec-filings.ts

@@ -0,0 +1,84 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { searchFilings } from "../../providers/sec-edgar.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT, TSLA)" }),
+  form_types: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Filing types to search: 10-K (annual), 10-Q (quarterly), 8-K (material events). Default: all three.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Maximum number of filings to return (default: 10)" }),
+  ),
+  include_snippets: Type.Optional(
+    Type.Boolean({ description: "Include short filing-text evidence snippets for risk/MD&A/litigation themes. Default: true." }),
+  ),
+});
+
+export const secFilingsTool: AgentTool<typeof params> = {
+  name: "get_sec_filings",
+  label: "SEC Filings",
+  description:
+    "Search SEC EDGAR for company filings (10-K annual reports, 10-Q quarterly reports, 8-K material events). Returns filing dates, types, and direct links to the documents. Free API, no key required.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const formTypes = args.form_types ?? ["10-K", "10-Q", "8-K"];
+    const limit = args.limit ?? 10;
+    const includeSnippets = args.include_snippets ?? true;
+
+    const result = await wrapProvider("sec-edgar", () =>
+      searchFilings(symbol, formTypes, limit, { includeSnippets, snippetLimitPerFiling: 2 })
+    );
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ SEC filings unavailable for ${symbol} (${result.reason}).` }],
+        details: null,
+      };
+    }
+    const filings = result.data;
+
+    if (filings.length === 0) {
+      return {
+        content: [{ type: "text", text: `No SEC filings found for ${symbol}. Verify the ticker is a US-listed company.` }],
+        details: null,
+      };
+    }
+
+    const lines = [
+      `**${symbol} SEC Filings** (${filings.length} found)`,
+      ``,
+      ...filings.map((f) =>
+        `  ${f.formType.padEnd(6)} | Filed: ${f.filedDate} | Period: ${f.periodOfReport || "N/A"} | ${f.entityName}`
+      ),
+      ``,
+      `Links:`,
+      ...filings.map((f) => `  ${f.formType} (${f.filedDate}): ${f.url}`),
+      ``,
+      `Primary documents:`,
+      ...filings.flatMap((f) => [
+        `  ${f.formType} (${f.filedDate}): ${f.primaryDocumentUrl ?? "N/A"}`,
+        ...(f.items?.length ? [`    8-K items: ${f.items.join(", ")}`] : []),
+      ]),
+      ...(includeSnippets
+        ? [
+          ``,
+          `Evidence snippets (short excerpts; review source filing for full context):`,
+          ...filings.flatMap((f) =>
+            (f.evidenceSnippets?.length
+              ? f.evidenceSnippets.map((snippet) => `  ${f.formType} ${f.filedDate}: ${snippet}`)
+              : [`  ${f.formType} ${f.filedDate}: No keyword snippet found in fetched primary document.`])
+          ),
+        ]
+        : []),
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { symbol, filings },
+    };
+  },
+};

package/src/tools/index.ts

@@ -0,0 +1,91 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { stockQuoteTool } from "./market/stock-quote.js";
+import { stockHistoryTool } from "./market/stock-history.js";
+import { cryptoPriceTool } from "./market/crypto-price.js";
+import { cryptoHistoryTool } from "./market/crypto-history.js";
+import { searchTickerTool } from "./market/search-ticker.js";
+import { companyOverviewTool } from "./fundamentals/company-overview.js";
+import { financialsTool } from "./fundamentals/financials.js";
+import { earningsTool } from "./fundamentals/earnings.js";
+import { fredDataTool } from "./macro/fred-data.js";
+import { fearGreedTool } from "./macro/fear-greed.js";
+import { redditSentimentTool } from "./sentiment/reddit-sentiment.js";
+import { twitterSentimentTool } from "./sentiment/twitter-sentiment.js";
+import { technicalIndicatorsTool } from "./technical/indicators.js";
+import { portfolioTrackerTool } from "./portfolio/tracker.js";
+import { riskAnalysisTool } from "./portfolio/risk-analysis.js";
+import { watchlistTool } from "./portfolio/watchlist.js";
+import { correlationTool } from "./portfolio/correlation.js";
+import { holdingsOverlapTool } from "./portfolio/holdings-overlap.js";
+import { optionChainTool } from "./options/option-chain.js";
+import { dcfTool } from "./fundamentals/dcf.js";
+import { compsTool } from "./fundamentals/comps.js";
+import { secFilingsTool } from "./fundamentals/sec-filings.js";
+import { backtestTool } from "./technical/backtest.js";
+import { predictionsTool } from "./portfolio/predictions.js";
+import { webSearchTool } from "./sentiment/web-search.js";
+import { webSentimentTool } from "./sentiment/web-sentiment.js";
+import { sentimentTrendTool } from "./sentiment/sentiment-trend.js";
+import { sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
+
+export { stockQuoteTool } from "./market/stock-quote.js";
+export { stockHistoryTool } from "./market/stock-history.js";
+export { cryptoPriceTool } from "./market/crypto-price.js";
+export { cryptoHistoryTool } from "./market/crypto-history.js";
+export { searchTickerTool } from "./market/search-ticker.js";
+export { companyOverviewTool } from "./fundamentals/company-overview.js";
+export { financialsTool } from "./fundamentals/financials.js";
+export { earningsTool } from "./fundamentals/earnings.js";
+export { dcfTool } from "./fundamentals/dcf.js";
+export { compsTool } from "./fundamentals/comps.js";
+export { secFilingsTool } from "./fundamentals/sec-filings.js";
+export { fredDataTool } from "./macro/fred-data.js";
+export { fearGreedTool } from "./macro/fear-greed.js";
+export { redditSentimentTool } from "./sentiment/reddit-sentiment.js";
+export { twitterSentimentTool } from "./sentiment/twitter-sentiment.js";
+export { webSearchTool } from "./sentiment/web-search.js";
+export { webSentimentTool } from "./sentiment/web-sentiment.js";
+export { sentimentTrendTool } from "./sentiment/sentiment-trend.js";
+export { sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
+export { technicalIndicatorsTool } from "./technical/indicators.js";
+export { backtestTool } from "./technical/backtest.js";
+export { portfolioTrackerTool } from "./portfolio/tracker.js";
+export { riskAnalysisTool } from "./portfolio/risk-analysis.js";
+export { watchlistTool } from "./portfolio/watchlist.js";
+export { correlationTool } from "./portfolio/correlation.js";
+export { holdingsOverlapTool } from "./portfolio/holdings-overlap.js";
+export { predictionsTool } from "./portfolio/predictions.js";
+export { optionChainTool } from "./options/option-chain.js";
+
+export function getAllTools(): AgentTool<any>[] {
+  return [
+    searchTickerTool,
+    stockQuoteTool,
+    stockHistoryTool,
+    cryptoPriceTool,
+    cryptoHistoryTool,
+    companyOverviewTool,
+    financialsTool,
+    earningsTool,
+    dcfTool,
+    compsTool,
+    secFilingsTool,
+    fredDataTool,
+    fearGreedTool,
+    redditSentimentTool,
+    twitterSentimentTool,
+    technicalIndicatorsTool,
+    backtestTool,
+    portfolioTrackerTool,
+    riskAnalysisTool,
+    watchlistTool,
+    correlationTool,
+    holdingsOverlapTool,
+    predictionsTool,
+    optionChainTool,
+    webSearchTool,
+    webSentimentTool,
+    sentimentTrendTool,
+    sentimentSummaryTool,
+  ];
+}

package/src/tools/interaction/ask-user.ts

@@ -0,0 +1,81 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promptUser } from "../../onboarding/prompt-user.js";
+import type { AskUserHandler } from "../../types/index.js";
+
+interface AskUserDetails {
+  question: string;
+  questionType: string;
+  answer: string | null;
+  cancelled: boolean;
+}
+
+const AskUserParams = Type.Object({
+  question: Type.String({ description: "The question to ask the user" }),
+  question_type: Type.Union(
+    [Type.Literal("select"), Type.Literal("text"), Type.Literal("confirm")],
+    { description: "Type of answer expected: select (pick from options), text (free input), or confirm (yes/no)" },
+  ),
+  options: Type.Optional(
+    Type.Array(Type.String(), { description: "Choices for select-type questions" }),
+  ),
+  placeholder: Type.Optional(
+    Type.String({ description: "Hint text for text input" }),
+  ),
+  reason: Type.Optional(
+    Type.String({ description: "Brief context for why this clarification is needed" }),
+  ),
+});
+
+export function registerAskUserTool(pi: ExtensionAPI, askUserHandler?: AskUserHandler): void {
+  pi.registerTool({
+    name: "ask_user",
+    label: "Ask User",
+    description:
+      "Ask the user a clarification question when their request is ambiguous or missing key details. Use select for multiple-choice, text for free input, or confirm for yes/no.",
+    promptSnippet:
+      "ask_user: Ask the user a clarification question when their request is ambiguous or missing key details",
+    parameters: AskUserParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { question, question_type: questionType } = params;
+
+      // Preserve the pre-refactor error message for the specific misuse case
+      // where the model asks a select question with no options — this is a
+      // model/caller bug, not a cancellation.
+      if (questionType === "select" && (!params.options || params.options.length === 0)) {
+        return {
+          content: [{ type: "text", text: "Error: No options provided for select question. Provide options or use text type instead." }],
+          details: { question, questionType, answer: null, cancelled: true } as AskUserDetails,
+        };
+      }
+
+      const result = await promptUser(
+        ctx!,
+        {
+          question,
+          questionType,
+          options: params.options,
+          placeholder: params.placeholder,
+          reason: params.reason,
+        },
+        askUserHandler,
+      );
+
+      if (result.cancelled) {
+        const text = !askUserHandler && !ctx?.hasUI
+          ? "UI not available (non-interactive mode). Proceed with your best judgment and clearly disclose your assumption."
+          : "User cancelled the selection. Proceed with your best judgment and disclose your assumption.";
+        return {
+          content: [{ type: "text", text }],
+          details: { question, questionType, answer: null, cancelled: true } as AskUserDetails,
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: `User answered: ${result.answer}` }],
+        details: { question, questionType, answer: result.answer, cancelled: false } as AskUserDetails,
+      };
+    },
+  });
+}