opencandle 0.5.0 → 0.7.0

package/src/prompts/workflow-prompts.ts

@@ -1,12 +1,14 @@
+import { parseDteTarget } from "../routing/defaults.js";
+import { areLikelyFundOrIndexSymbols, isFundOrIndexAssetScope } from "../routing/fund-symbols.js";
+import { isLongInvestmentHorizon } from "../routing/horizon.js";
+import type { RouterOutput } from "../routing/router-types.js";
 import type {
-  PortfolioSlots,
-  OptionsScreenerSlots,
   CompareAssetsSlots,
+  OptionsScreenerSlots,
+  PortfolioSlots,
   SlotResolution,
   SlotSource,
 } from "../routing/types.js";
-import type { RouterOutput } from "../routing/router-types.js";
-import { parseDteTarget } from "../routing/defaults.js";
 
 function tag(source: string | undefined): string {
   switch (source) {
@@ -14,7 +16,6 @@ function tag(source: string | undefined): string {
       return " [DEFAULT]";
     case "preference":
       return " [SAVED PREFERENCE]";
-    case "user":
     default:
       return "";
   }
@@ -96,8 +97,10 @@ export function buildDisclosureBlock(
   const lines: string[] = [];
   lines.push("Assumptions (reproduce this block exactly — do not relabel sources):");
   if (userSpecified.length > 0) lines.push(`  User-specified: ${userSpecified.join(", ")}`);
-  if (fromPreferences.length > 0) lines.push(`  From saved preferences: ${fromPreferences.join(", ")}`);
-  if (fromPriorContext.length > 0) lines.push(`  From prior context: ${fromPriorContext.join(", ")}`);
+  if (fromPreferences.length > 0)
+    lines.push(`  From saved preferences: ${fromPreferences.join(", ")}`);
+  if (fromPriorContext.length > 0)
+    lines.push(`  From prior context: ${fromPriorContext.join(", ")}`);
   if (fromMemory.length > 0) lines.push(`  From memory: ${fromMemory.join(", ")}`);
   if (defaults.length > 0) lines.push(`  Defaults: ${defaults.join(", ")}`);
   if (workflowConstraints && workflowConstraints.length > 0) {
@@ -139,7 +142,10 @@ function formatSlotValue(value: unknown): string {
 export function buildPortfolioPrompt(resolution: SlotResolution<PortfolioSlots>): string {
   const { resolved: s, sources } = resolution;
   const normalizedScope = s.assetScope.toLowerCase();
-  const isFundBuildingBlocks = normalizedScope.includes("etf") || normalizedScope.includes("fund") || normalizedScope.includes("building_blocks");
+  const isFundBuildingBlocks =
+    normalizedScope.includes("etf") ||
+    normalizedScope.includes("fund") ||
+    normalizedScope.includes("building_blocks");
 
   const disclosureBlock = buildDisclosureBlock(
     {
@@ -198,7 +204,9 @@ Response format:
 - Suggest what to change for more growth or more safety.`;
 }
 
-export function buildOptionsScreenerPrompt(resolution: SlotResolution<OptionsScreenerSlots>): string {
+export function buildOptionsScreenerPrompt(
+  resolution: SlotResolution<OptionsScreenerSlots>,
+): string {
   const { resolved: s, sources } = resolution;
 
   const dateStr = todayStr();
@@ -225,14 +233,15 @@ Ranking constraints:
 - Do NOT rank ultra-cheap near-zero-delta contracts as "best."
 `
     : "";
-  const longDatedInstructions = s.dteTarget === "180_plus_days"
-    ? `
+  const longDatedInstructions =
+    s.dteTarget === "180_plus_days"
+      ? `
 For LEAPS / long-dated options:
 - First call get_option_chain without an expiration to inspect available expirations.
 - Choose available expirations inside the target window, then call get_option_chain again with explicit \`expiration\` dates before ranking contracts.
 - Do not rank the nearest-expiration chain as a LEAPS result.
 `
-    : "";
+      : "";
 
   const disclosureBlock = buildDisclosureBlock(
     {
@@ -253,18 +262,26 @@ For LEAPS / long-dated options:
   );
 
   const coveredCallContext = [
-    s.optionStrategy ? `\n- Option strategy: ${s.optionStrategy}${tag(sources.optionStrategy)}` : "",
-    s.costBasis !== undefined ? `\n- Cost basis: ${formatBudget(s.costBasis)} (Position cost basis: ${formatBudget(s.costBasis)})${tag(sources.costBasis)}` : "",
-    s.shareQuantity !== undefined ? `\n- Share quantity: ${s.shareQuantity} shares${tag(sources.shareQuantity)}` : "",
-    s.catalystSymbols?.length ? `\n- Catalyst/context tickers: ${s.catalystSymbols.join(", ")}${tag(sources.catalystSymbols)}` : "",
+    s.optionStrategy
+      ? `\n- Option strategy: ${s.optionStrategy}${tag(sources.optionStrategy)}`
+      : "",
+    s.costBasis !== undefined
+      ? `\n- Cost basis: ${formatBudget(s.costBasis)} (Position cost basis: ${formatBudget(s.costBasis)})${tag(sources.costBasis)}`
+      : "",
+    s.shareQuantity !== undefined
+      ? `\n- Share quantity: ${s.shareQuantity} shares${tag(sources.shareQuantity)}`
+      : "",
+    s.catalystSymbols?.length
+      ? `\n- Catalyst/context tickers: ${s.catalystSymbols.join(", ")}${tag(sources.catalystSymbols)}`
+      : "",
   ].join("");
 
   const isProtectivePutContext = s.optionStrategy === "protective_put";
-  const isCoveredCallContext = !isProtectivePutContext && (
-    s.optionStrategy === "covered_call" ||
-    s.costBasis !== undefined ||
-    (s.catalystSymbols?.length ?? 0) > 0
-  );
+  const isCoveredCallContext =
+    !isProtectivePutContext &&
+    (s.optionStrategy === "covered_call" ||
+      s.costBasis !== undefined ||
+      (s.catalystSymbols?.length ?? 0) > 0);
   const coveredCallInstructions = isCoveredCallContext
     ? `
 Covered-call sale guidance:
@@ -314,9 +331,17 @@ Steps:
 3. Filter contracts matching: ${s.direction === "bullish" && !isProtectivePutContext ? "calls" : "puts"}, DTE near ${s.dteTarget}, ${s.moneynessPreference} strikes.
 4. ${isProtectivePutContext ? "Rank by hedge quality: protection per dollar of premium, expiration fit, moneyness, liquidity, and hedge floor." : `Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit.`}${s.maxPremium !== undefined ? ` Do not rank contracts above the user's max premium of ${formatBudget(s.maxPremium)} unless no contracts under that cap are liquid; if so, say the cap could not be met.` : ""}
 5. Filter for ${s.liquidityMinimum}: high open interest and tight bid-ask spread.
-${s.optionStrategy === "covered_call" ? `6. Covered call framing: treat option premium as premium received, not paid. Use the user's cost basis when provided, and include return-if-assigned and assignment/downside risk instead of long-call max-loss framing.
-` : ""}${isCoveredCallContext && s.costBasis !== undefined ? `Cost-basis math: if assigned, share gain/loss is strike minus ${formatBudget(s.costBasis)} before premium. Total return if assigned is (strike - cost basis + premium received) / cost basis.
-` : ""}
+${
+  s.optionStrategy === "covered_call"
+    ? `6. Covered call framing: treat option premium as premium received, not paid. Use the user's cost basis when provided, and include return-if-assigned and assignment/downside risk instead of long-call max-loss framing.
+`
+    : ""
+}${
+  isCoveredCallContext && s.costBasis !== undefined
+    ? `Cost-basis math: if assigned, share gain/loss is strike minus ${formatBudget(s.costBasis)} before premium. Total return if assigned is (strike - cost basis + premium received) / cost basis.
+`
+    : ""
+}
 ${longDatedInstructions}
 ${coveredCallInstructions}
 ${protectivePutInstructions}
@@ -336,10 +361,15 @@ export function buildCompareAssetsPrompt(resolution: SlotResolution<CompareAsset
   const symbols = resolution.resolved.symbols;
   const symbolList = symbols.join(", ");
   const timeHorizon = resolution.resolved.timeHorizon;
+  const budget = resolution.resolved.budget;
   const includeSentiment = resolution.resolved.metrics?.includes("sentiment") ?? false;
   const isMacroHedge = resolution.resolved.metrics?.includes("macro_hedge") ?? false;
   const isInterestRateSensitive = resolution.resolved.metrics?.includes("interest_rates") ?? false;
   const isOverlapComparison = resolution.resolved.metrics?.includes("overlap") ?? false;
+  const hasFundContext =
+    isFundOrIndexAssetScope(resolution.resolved.assetScope) || areLikelyFundOrIndexSymbols(symbols);
+  const shouldProbeFundOverlap =
+    !isOverlapComparison && isLongInvestmentHorizon(timeHorizon) && hasFundContext;
   const sentimentStep = includeSentiment
     ? `\n6. Use get_sentiment_summary for each of: ${symbolList} to compare retail/news sentiment and note source availability.`
     : "";
@@ -365,7 +395,16 @@ ETF overlap guidance:
 - Use provider top holdings and overlap weights when available. If provider coverage is partial or unavailable, say so directly and fall back to plain-language fund structure.
 - Discuss top holdings, shared mega-cap names, sector concentration, and whether the position is a deliberate tilt or accidental duplication.
 - avoid treating price, RSI, or generic risk metrics as the main answer.`
-    : "";
+    : shouldProbeFundOverlap
+      ? `
+ETF/fund overlap check:
+- If these assets are ETFs, funds, or index products, use provider-backed holdings-overlap evidence before making diversification claims.
+- Compare fund role, style/factor tilt, concentration, and broad sector exposure when available; do not invent exact holdings or weights.
+- For dividend/income funds versus growth funds over multi-year horizons, explain taxable account dividend drag: dividends can be taxed annually even when reinvested, while more return may be deferred as capital gains in growth-oriented funds. Contrast that with tax-advantaged accounts.
+- Include expense ratios, dividend yields, and AUM only when fetched evidence supports them; otherwise tell the user to verify current fund facts before acting.
+- Treat holdings overlap and sector concentration as different from correlation; correlation is supporting evidence, not a substitute for constituent exposure.
+- If provider holdings coverage is partial or unavailable, say so directly and continue with the available price, risk, and correlation evidence.`
+      : "";
   const macroHedgeSteps = isMacroHedge
     ? `
 macro hedge decision guidance:
@@ -380,16 +419,24 @@ macro hedge decision guidance:
     ? "- Present a comparison table with hedge-relevant columns: hedge role, macro drivers, volatility/drawdown evidence, correlation regime, liquidity/risk-on sensitivity, current data, and missing evidence."
     : isOverlapComparison
       ? "- Present an ETF overlap table with columns: fund role, shared top holdings/overlap weight from provider when available, sector concentration, what exposure is duplicated, what exposure is new, and diversification implication."
-    : `- Present a comparison table with key metrics: price, P/E, revenue growth, profit margin, RSI, Sharpe, max drawdown${sentimentMetric}.
+      : shouldProbeFundOverlap
+        ? "- Present a long-horizon fund comparison table with columns: fund role/style, dividend/income versus growth tradeoff, risk evidence, holdings-overlap availability, tax and expense/yield/AUM verification gaps, and horizon fit."
+        : `- Present a comparison table with key metrics: price, P/E, revenue growth, profit margin, RSI, Sharpe, max drawdown${sentimentMetric}.
 - Highlight which asset is stronger on each metric.`;
   const technicalRiskSteps = isOverlapComparison
     ? `3. Use analyze_holdings_overlap with symbols [${symbolList}] to fetch provider top holdings and compute pairwise overlap by weight.
 4. Use analyze_correlation across [${symbolList}] only as supporting diversification evidence; do not substitute correlation for holdings overlap.
 5. Skip momentum/risk tool calls unless the user asks about timing or trade setup; the core question is top holdings and sector overlap.`
-    : `3. Use get_technical_indicators for each to compare momentum and trend.
+    : shouldProbeFundOverlap
+      ? `3. Use analyze_holdings_overlap with symbols [${symbolList}] to fetch provider top holdings and compute pairwise overlap by weight.
+4. Use analyze_correlation across [${symbolList}] as supporting diversification evidence.
+5. Use analyze_risk for each to compare long-horizon risk context.
+6. Use get_technical_indicators only as secondary timing context; do not let RSI or short-term momentum dominate the long-horizon fund decision.`
+      : `3. Use get_technical_indicators for each to compare momentum and trend.
 4. Use analyze_risk for each to compare risk metrics.
 5. Use analyze_correlation across [${symbolList}] to check diversification.`;
   const horizonLine = timeHorizon ? `\nTime horizon: ${timeHorizon}` : "";
+  const budgetLine = budget !== undefined ? `\nBudget: ${formatBudget(budget)}` : "";
   const horizonSteps = timeHorizon
     ? `
 6. Adapt the comparison to the ${timeHorizon} horizon: prioritize near-term catalysts, earnings/guidance, estimate revisions, sentiment, and forward-looking valuation evidence over long-term historical averages.
@@ -406,6 +453,8 @@ macro hedge decision guidance:
     {
       symbols: symbolList,
       ...(timeHorizon ? { timeHorizon } : {}),
+      ...(budget !== undefined ? { budget: formatBudget(budget) } : {}),
+      ...(resolution.resolved.assetScope ? { assetScope: resolution.resolved.assetScope } : {}),
       ...(resolution.resolved.metrics ? { metrics: resolution.resolved.metrics.join(", ") } : {}),
     },
     resolution.sources as Record<string, SlotSource | undefined>,
@@ -413,7 +462,7 @@ macro hedge decision guidance:
 
   return `Current date: ${todayStr()}
 
-Compare these assets side by side: ${symbolList}${horizonLine}
+Compare these assets side by side: ${symbolList}${horizonLine}${budgetLine}
 
 Steps:
 1. Use get_stock_quote for each of: ${symbolList}.

package/src/providers/alpha-vantage.ts

@@ -1,9 +1,9 @@
-import { httpGet, HttpError } from "../infra/http-client.js";
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
+import { HttpError, httpGet } from "../infra/http-client.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
-import { ProviderCredentialError } from "./provider-credential-error.js";
 import type { CompanyOverview, EarningsData, FinancialStatement } from "../types/fundamentals.js";
-import type { StockQuote, OHLCV } from "../types/market.js";
+import type { OHLCV, StockQuote } from "../types/market.js";
+import { ProviderCredentialError } from "./provider-credential-error.js";
 
 const BASE_URL = "https://www.alphavantage.co/query";
 const MISSING_OVERVIEW_TTL = 15 * 60_000;
@@ -44,10 +44,7 @@ function throwIfApiMessage(data: unknown): void {
   throw new Error(`Alpha Vantage error: ${message}`);
 }
 
-export async function getOverview(
-  symbol: string,
-  apiKey: string,
-): Promise<CompanyOverview> {
+export async function getOverview(symbol: string, apiKey: string): Promise<CompanyOverview> {
   const cacheKey = `av:overview:${symbol}`;
   const missingCacheKey = `${cacheKey}:missing`;
   const cached = cache.get<CompanyOverview>(cacheKey);
@@ -98,10 +95,7 @@ export async function getOverview(
   }
 }
 
-export async function getEarnings(
-  symbol: string,
-  apiKey: string,
-): Promise<EarningsData> {
+export async function getEarnings(symbol: string, apiKey: string): Promise<EarningsData> {
   const cacheKey = `av:earnings:${symbol}`;
   const cached = cache.get<EarningsData>(cacheKey);
   if (cached) return cached;
@@ -132,31 +126,36 @@ export async function getEarnings(
   }
 }
 
-export async function getFinancials(
-  symbol: string,
-  apiKey: string,
-): Promise<FinancialStatement[]> {
+export async function getFinancials(symbol: string, apiKey: string): Promise<FinancialStatement[]> {
   const cacheKey = `av:financials:${symbol}`;
   const cached = cache.get<FinancialStatement[]>(cacheKey);
   if (cached) return cached;
 
   try {
     // Fetch sequentially to respect Alpha Vantage rate limits (5 req/min free tier)
-    const incomeData = await fetchStatement<{ annualReports: any[] }>("INCOME_STATEMENT", symbol, apiKey);
-    const balanceData = await fetchStatement<{ annualReports: any[] }>("BALANCE_SHEET", symbol, apiKey);
-    const cashFlowData = await fetchStatement<{ annualReports: any[] }>("CASH_FLOW", symbol, apiKey);
+    const incomeData = await fetchStatement<{ annualReports: any[] }>(
+      "INCOME_STATEMENT",
+      symbol,
+      apiKey,
+    );
+    const balanceData = await fetchStatement<{ annualReports: any[] }>(
+      "BALANCE_SHEET",
+      symbol,
+      apiKey,
+    );
+    const cashFlowData = await fetchStatement<{ annualReports: any[] }>(
+      "CASH_FLOW",
+      symbol,
+      apiKey,
+    );
 
     const incomeReports = incomeData.annualReports ?? [];
     const balanceReports = balanceData.annualReports ?? [];
     const cashFlowReports = cashFlowData.annualReports ?? [];
 
     // Index balance sheet and cash flow by fiscal date for merging
-    const balanceByDate = new Map(
-      balanceReports.map((r: any) => [r.fiscalDateEnding, r]),
-    );
-    const cashFlowByDate = new Map(
-      cashFlowReports.map((r: any) => [r.fiscalDateEnding, r]),
-    );
+    const balanceByDate = new Map(balanceReports.map((r: any) => [r.fiscalDateEnding, r]));
+    const cashFlowByDate = new Map(cashFlowReports.map((r: any) => [r.fiscalDateEnding, r]));
 
     const statements = incomeReports.slice(0, 4).map((r: any) => {
       const balance = balanceByDate.get(r.fiscalDateEnding) ?? {};
@@ -202,10 +201,7 @@ async function fetchStatement<T>(fn: string, symbol: string, apiKey: string): Pr
   return data;
 }
 
-export async function getGlobalQuote(
-  symbol: string,
-  apiKey: string,
-): Promise<StockQuote> {
+export async function getGlobalQuote(symbol: string, apiKey: string): Promise<StockQuote> {
   const cacheKey = `av:globalquote:${symbol}`;
   const cached = cache.get<StockQuote>(cacheKey);
   if (cached) return cached;
@@ -233,10 +229,10 @@ export async function getGlobalQuote(
       low: parseFloat(gq["04. low"]) || 0,
       previousClose: parseFloat(gq["08. previous close"]) || 0,
       volume: parseInt(gq["06. volume"], 10) || 0,
-      marketCap: 0,      // Not available from GLOBAL_QUOTE
-      pe: null,           // Not available from GLOBAL_QUOTE
-      week52High: 0,      // Not available from GLOBAL_QUOTE
-      week52Low: 0,       // Not available from GLOBAL_QUOTE
+      marketCap: 0, // Not available from GLOBAL_QUOTE
+      pe: null, // Not available from GLOBAL_QUOTE
+      week52High: 0, // Not available from GLOBAL_QUOTE
+      week52Low: 0, // Not available from GLOBAL_QUOTE
       timestamp: Date.now(),
     };
 
@@ -266,7 +262,9 @@ export async function getDailyHistory(
     const daysNeeded = rangeToDays(range);
     const outputsize = daysNeeded > 100 ? "full" : "compact";
     const url = buildUrl("TIME_SERIES_DAILY", { symbol, outputsize }, apiKey);
-    const data = await httpGet<{ "Time Series (Daily)": Record<string, Record<string, string>> }>(url);
+    const data = await httpGet<{ "Time Series (Daily)": Record<string, Record<string, string>> }>(
+      url,
+    );
     throwIfApiMessage(data);
 
     const timeSeries = data["Time Series (Daily)"];
@@ -274,7 +272,7 @@ export async function getDailyHistory(
       throw new Error(`Alpha Vantage: No daily history for ${symbol}`);
     }
 
-    const ohlcv: OHLCV[] = Object.entries(timeSeries)
+    const sorted = Object.entries(timeSeries)
       .map(([date, bar]) => ({
         date,
         open: parseFloat(bar["1. open"]) || 0,
@@ -283,8 +281,14 @@ export async function getDailyHistory(
         close: parseFloat(bar["4. close"]) || 0,
         volume: parseInt(bar["5. volume"], 10) || 0,
       }))
-      .sort((a, b) => a.date.localeCompare(b.date))
-      .slice(-daysNeeded);
+      .sort((a, b) => a.date.localeCompare(b.date));
+
+    // Count-based slicing for ytd is only an estimate (ignores holidays and
+    // the starting weekday) and can leak prior-year bars; filter by date.
+    const ohlcv: OHLCV[] =
+      range === "ytd"
+        ? sorted.filter((bar) => bar.date >= `${new Date().getFullYear()}-01-01`)
+        : sorted.slice(-daysNeeded);
 
     cache.set(cacheKey, ohlcv, TTL.HISTORY);
     return ohlcv;
@@ -298,12 +302,27 @@ export async function getDailyHistory(
 
 function rangeToDays(range: string): number {
   const map: Record<string, number> = {
-    "1d": 1, "5d": 5, "1mo": 22, "3mo": 66, "6mo": 130,
-    "1y": 252, "2y": 504, "5y": 1260, "max": 5000,
+    "1d": 1,
+    "5d": 5,
+    "1mo": 22,
+    "3mo": 66,
+    "6mo": 130,
+    "1y": 252,
+    "2y": 504,
+    "5y": 1260,
+    "10y": 2520,
+    max: 5000,
   };
+  if (range === "ytd") return tradingDaysSinceStartOfYear();
   return map[range] ?? 130;
 }
 
+function tradingDaysSinceStartOfYear(date = new Date()): number {
+  const start = new Date(date.getFullYear(), 0, 1);
+  const calendarDays = Math.max(1, Math.ceil((date.getTime() - start.getTime()) / 86_400_000) + 1);
+  return Math.max(1, Math.ceil((calendarDays / 7) * 5));
+}
+
 function parseNum(s: string | undefined): number {
   return parseFloat(s ?? "0") || 0;
 }

package/src/providers/coingecko.ts

@@ -1,5 +1,5 @@
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
 import { httpGet } from "../infra/http-client.js";
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
 import type { CryptoPrice, OHLCV } from "../types/market.js";
 
@@ -63,10 +63,7 @@ export async function getCryptoPrice(id: string): Promise<CryptoPrice> {
   }
 }
 
-export async function getCryptoHistory(
-  id: string,
-  days: number = 180,
-): Promise<OHLCV[]> {
+export async function getCryptoHistory(id: string, days: number = 180): Promise<OHLCV[]> {
   const cacheKey = `coingecko:history:${id}:${days}`;
   const cached = cache.get<OHLCV[]>(cacheKey);
   if (cached) return cached;

package/src/providers/errors.ts

@@ -0,0 +1,9 @@
+export class InvalidSymbolError extends Error {
+  constructor(
+    public readonly symbol: string,
+    public readonly provider: string,
+  ) {
+    super(`Invalid symbol ${symbol} for ${provider}`);
+    this.name = "InvalidSymbolError";
+  }
+}

package/src/providers/exa-search.ts

@@ -1,8 +1,8 @@
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
-import { rateLimiter } from "../infra/rate-limiter.js";
 import { getConfig } from "../config.js";
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
+import { rateLimiter } from "../infra/rate-limiter.js";
+import type { WebSearchEnvelope, WebSearchResult } from "../types/sentiment.js";
 import { ProviderCredentialError } from "./provider-credential-error.js";
-import type { WebSearchResult, WebSearchEnvelope } from "../types/sentiment.js";
 import type { WebSearchOpts } from "./web-search.js";
 
 const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
@@ -19,19 +19,27 @@ let requestIdCounter = 0;
 
 function freshnessToMs(freshness: WebSearchOpts["freshness"]): number {
   switch (freshness) {
-    case "hours": return 60 * 60 * 1000;
-    case "day": return 24 * 60 * 60 * 1000;
-    case "week": return 7 * 24 * 60 * 60 * 1000;
-    case "month": return 30 * 24 * 60 * 60 * 1000;
+    case "hours":
+      return 60 * 60 * 1000;
+    case "day":
+      return 24 * 60 * 60 * 1000;
+    case "week":
+      return 7 * 24 * 60 * 60 * 1000;
+    case "month":
+      return 30 * 24 * 60 * 60 * 1000;
   }
 }
 
 function enrichQueryForMcp(query: string, freshness: WebSearchOpts["freshness"]): string {
   switch (freshness) {
-    case "hours": return `${query} past hour`;
-    case "day": return `${query} past 24 hours`;
-    case "week": return `${query} past week`;
-    case "month": return `${query} past month`;
+    case "hours":
+      return `${query} past hour`;
+    case "day":
+      return `${query} past 24 hours`;
+    case "week":
+      return `${query} past week`;
+    case "month":
+      return `${query} past month`;
   }
 }
 
@@ -192,10 +200,7 @@ function exaCacheKey(query: string, opts: WebSearchOpts): string {
 // MCP path
 // ---------------------------------------------------------------------------
 
-async function exaMcpSearch(
-  query: string,
-  opts: WebSearchOpts,
-): Promise<WebSearchEnvelope> {
+async function exaMcpSearch(query: string, opts: WebSearchOpts): Promise<WebSearchEnvelope> {
   const enrichedQuery = enrichQueryForMcp(query, opts.freshness);
 
   const response = await fetch(EXA_MCP_URL, {
@@ -330,10 +335,7 @@ async function exaApiSearch(
 // Public entry point
 // ---------------------------------------------------------------------------
 
-export async function exaSearch(
-  query: string,
-  opts: WebSearchOpts,
-): Promise<WebSearchEnvelope> {
+export async function exaSearch(query: string, opts: WebSearchOpts): Promise<WebSearchEnvelope> {
   const key = exaCacheKey(query, opts);
   const cached = cache.get<WebSearchEnvelope>(key);
   if (cached) return cached;
@@ -362,12 +364,12 @@ export async function exaSearch(
   }
 }
 
+export type { ExaApiResponse, McpRpcResponse, ParsedResult };
 // Exported for testing
 export {
-  parseMcpResultBlocks,
-  extractJsonRpcPayload,
   enrichQueryForMcp,
+  extractJsonRpcPayload,
   filterByFreshness,
   mapApiResults,
+  parseMcpResultBlocks,
 };
-export type { ParsedResult, McpRpcResponse, ExaApiResponse };

package/src/providers/external-tool-error.ts

@@ -0,0 +1,20 @@
+export class ExternalToolError extends Error {
+  constructor(
+    public readonly toolName: string,
+    message: string,
+    public readonly code?: string,
+  ) {
+    super(message);
+    this.name = "ExternalToolError";
+  }
+}
+
+export class ExternalToolNotInstalled extends Error {
+  constructor(
+    public readonly toolName: string,
+    public readonly installCmd: string,
+  ) {
+    super(`${toolName} is not installed. Install it with: ${installCmd}`);
+    this.name = "ExternalToolNotInstalled";
+  }
+}

package/src/providers/fear-greed.ts

@@ -1,5 +1,5 @@
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
 import { httpGet } from "../infra/http-client.js";
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
 import type { FearGreedData } from "../types/sentiment.js";
 
 // alternative.me provides a free crypto Fear & Greed index

package/src/providers/finnhub.ts

@@ -1,5 +1,5 @@
-import { httpGet, HttpError } from "../infra/http-client.js";
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
+import { HttpError, httpGet } from "../infra/http-client.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
 import { ProviderCredentialError } from "./provider-credential-error.js";
 
@@ -36,7 +36,10 @@ const TICKER_NAMES: Record<string, string> = {
   ORCL: "oracle",
 };
 
-export function finnhubDateRange(freshness: "hours" | "day" | "week" | "month"): { from: string; to: string } {
+export function finnhubDateRange(freshness: "hours" | "day" | "week" | "month"): {
+  from: string;
+  to: string;
+} {
   const now = new Date();
   const to = formatDate(now);
 
@@ -86,9 +89,7 @@ export function filterByRelevance(
   });
 
   // Most recent first, capped
-  return filtered
-    .sort((a, b) => b.datetime - a.datetime)
-    .slice(0, limit);
+  return filtered.sort((a, b) => b.datetime - a.datetime).slice(0, limit);
 }
 
 export async function getCompanyNews(

package/src/providers/fred.ts

@@ -1,8 +1,8 @@
-import { httpGet, HttpError } from "../infra/http-client.js";
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
+import { cache, STALE_LIMIT, TTL } from "../infra/cache.js";
+import { HttpError, httpGet } from "../infra/http-client.js";
 import { rateLimiter } from "../infra/rate-limiter.js";
+import type { FredObservation, FredSeries } from "../types/macro.js";
 import { ProviderCredentialError } from "./provider-credential-error.js";
-import type { FredSeries, FredObservation } from "../types/macro.js";
 
 const BASE_URL = "https://api.stlouisfed.org/fred";
 

package/src/providers/index.ts

@@ -1,9 +1,17 @@
-export { getQuote, getHistory, getOptionsChain, clearCrumbCache, getYahooCrumb, computeTimeToExpiry } from "./yahoo-finance.js";
-export { getOverview, getEarnings, getFinancials } from "./alpha-vantage.js";
+export { getEarnings, getFinancials, getOverview } from "./alpha-vantage.js";
+export { getCryptoHistory, getCryptoPrice } from "./coingecko.js";
+export { getFearGreedIndex } from "./fear-greed.js";
 export { getSeries } from "./fred.js";
-export { getCryptoPrice, getCryptoHistory } from "./coingecko.js";
 export { getSubredditPosts, scoreSentiment } from "./reddit.js";
-export { searchFilings, type SECFiling } from "./sec-edgar.js";
-export { getFearGreedIndex } from "./fear-greed.js";
-export { searchWeb, ddgSearch, braveSearch, normalizeFinancialQuery } from "./web-search.js";
+export { type SECFiling, searchFilings } from "./sec-edgar.js";
+export { getQuotes, screenStocks } from "./tradingview.js";
 export type { WebSearchOpts } from "./web-search.js";
+export { braveSearch, ddgSearch, normalizeFinancialQuery, searchWeb } from "./web-search.js";
+export {
+  clearCrumbCache,
+  computeTimeToExpiry,
+  getHistory,
+  getOptionsChain,
+  getQuote,
+  getYahooCrumb,
+} from "./yahoo-finance.js";