opencandle 0.4.0 → 0.6.0

package/src/providers/yahoo-finance.ts

@@ -1,12 +1,23 @@
-import { httpGet } from "../infra/http-client.js";
-import { cache, TTL, STALE_LIMIT } from "../infra/cache.js";
-import { rateLimiter } from "../infra/rate-limiter.js";
 import { StealthBrowser } from "../infra/browser.js";
-import type { StockQuote, OHLCV } from "../types/market.js";
-import type { OptionsChain, OptionContract } from "../types/options.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 { computeGreeks } from "../tools/options/greeks.js";
+import type { OHLCV, StockQuote } from "../types/market.js";
+import type {
+  OptionContract,
+  OptionsChain,
+  OptionsMarketSession,
+  OptionsQuoteStatus,
+} from "../types/options.js";
+import type { FundHoldings } from "../types/portfolio.js";
+import { InvalidSymbolError } from "./errors.js";
 
 const BASE_URL = "https://query1.finance.yahoo.com/v8/finance/chart";
+const QUOTE_SUMMARY_URL = "https://query1.finance.yahoo.com/v10/finance/quoteSummary";
+const STALE_QUOTE_MAX_RETRY_AFTER_MS = 1_000;
+
+type YahooNumber = number | { raw?: number; fmt?: string };
 
 interface YahooChartResponse {
   chart: {
@@ -28,6 +39,29 @@ interface YahooChartResponse {
   };
 }
 
+interface YahooQuoteSummaryResponse {
+  quoteSummary: {
+    result?: Array<{
+      price?: {
+        symbol?: string;
+        shortName?: string;
+        longName?: string;
+      };
+      topHoldings?: {
+        holdings?: Array<{
+          symbol?: string;
+          holdingName?: string;
+          holdingPercent?: YahooNumber;
+        }>;
+        equityHoldings?: {
+          sectorWeightings?: Array<Record<string, YahooNumber>>;
+        };
+      };
+    }>;
+    error?: { code?: string; description?: string } | null;
+  };
+}
+
 export async function getQuote(symbol: string): Promise<StockQuote> {
   const cacheKey = `yahoo:quote:${symbol}`;
   const cached = cache.get<StockQuote>(cacheKey);
@@ -39,6 +73,7 @@ export async function getQuote(symbol: string): Promise<StockQuote> {
     const url = `${BASE_URL}/${encodeURIComponent(symbol)}?interval=1d&range=1d`;
     const data = await httpGet<YahooChartResponse>(url, {
       headers: { "User-Agent": "OpenCandle/1.0" },
+      maxRetryAfterMs: STALE_QUOTE_MAX_RETRY_AFTER_MS,
     });
 
     if (data.chart.error) {
@@ -72,8 +107,16 @@ export async function getQuote(symbol: string): Promise<StockQuote> {
       week52High: meta.fiftyTwoWeekHigh ?? 0,
       week52Low: meta.fiftyTwoWeekLow ?? 0,
       timestamp: Date.now(),
+      currency:
+        typeof meta.currency === "string" && meta.currency.trim() !== ""
+          ? meta.currency.trim().toUpperCase()
+          : null,
     };
 
+    if (isZeroResultQuote(quote)) {
+      throw new InvalidSymbolError(symbol.toUpperCase(), "yahoo");
+    }
+
     cache.set(cacheKey, quote, TTL.QUOTE);
     return quote;
   } catch (error) {
@@ -83,6 +126,16 @@ export async function getQuote(symbol: string): Promise<StockQuote> {
   }
 }
 
+function isZeroResultQuote(quote: StockQuote): boolean {
+  return (
+    quote.price === 0 &&
+    quote.volume === 0 &&
+    quote.week52High === 0 &&
+    quote.week52Low === 0 &&
+    quote.marketCap === 0
+  );
+}
+
 export async function getHistory(
   symbol: string,
   range: string = "6mo",
@@ -128,10 +181,128 @@ export async function getHistory(
   }
 }
 
+export async function getFundHoldings(symbol: string): Promise<FundHoldings> {
+  const normalizedSymbol = symbol.toUpperCase();
+  const cacheKey = `yahoo:fund-holdings:${normalizedSymbol}`;
+  const cached = cache.get<FundHoldings>(cacheKey);
+  if (cached) return cached;
+
+  try {
+    await rateLimiter.acquire("yahoo");
+
+    const data = await getFundHoldingsSummary(normalizedSymbol);
+    const result = data.quoteSummary.result?.[0];
+    if (data.quoteSummary.error) {
+      throw new Error(
+        `Yahoo Finance: ${data.quoteSummary.error.description ?? data.quoteSummary.error.code ?? "quoteSummary error"}`,
+      );
+    }
+    if (!result?.topHoldings?.holdings?.length) {
+      throw new Error(`Yahoo Finance: no fund holdings returned for ${normalizedSymbol}`);
+    }
+
+    const holdings: FundHoldings = {
+      symbol: result.price?.symbol?.toUpperCase() ?? normalizedSymbol,
+      name: result.price?.shortName ?? result.price?.longName,
+      provider: "yahoo",
+      holdings: result.topHoldings.holdings.flatMap((holding) => {
+        const holdingSymbol = holding.symbol?.trim().toUpperCase();
+        const weight = normalizeHoldingWeight(holding.holdingPercent);
+        if (!holdingSymbol || weight === undefined) return [];
+        return [
+          {
+            symbol: holdingSymbol,
+            name: holding.holdingName?.trim() || holdingSymbol,
+            weight,
+          },
+        ];
+      }),
+      sectorWeights: normalizeSectorWeights(result.topHoldings.equityHoldings?.sectorWeightings),
+    };
+    if (holdings.holdings.length === 0) {
+      throw new Error(`Yahoo Finance: no weighted fund holdings returned for ${normalizedSymbol}`);
+    }
+
+    cache.set(cacheKey, holdings, TTL.FUNDAMENTALS);
+    return holdings;
+  } catch (error) {
+    const stale = cache.getStale<FundHoldings>(cacheKey, STALE_LIMIT.FUNDAMENTALS);
+    if (stale) return stale.value;
+    throw error;
+  }
+}
+
+async function getFundHoldingsSummary(symbol: string): Promise<YahooQuoteSummaryResponse> {
+  try {
+    return await fetchFundHoldingsSummary(symbol);
+  } catch (error) {
+    if (!isYahooAuthError(error)) throw error;
+    return fetchFundHoldingsSummaryWithCrumb(symbol);
+  }
+}
+
+async function fetchFundHoldingsSummary(symbol: string): Promise<YahooQuoteSummaryResponse> {
+  const modules = encodeURIComponent("price,topHoldings");
+  const url = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(symbol)}?modules=${modules}`;
+  return httpGet<YahooQuoteSummaryResponse>(url, {
+    headers: { "User-Agent": "OpenCandle/1.0" },
+  });
+}
+
+async function fetchFundHoldingsSummaryWithCrumb(
+  symbol: string,
+): Promise<YahooQuoteSummaryResponse> {
+  const modules = encodeURIComponent("price,topHoldings");
+  const { crumb, cookie } = await getYahooCrumb();
+  const url = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(symbol)}?modules=${modules}&crumb=${encodeURIComponent(crumb)}`;
+  try {
+    return await httpGet<YahooQuoteSummaryResponse>(url, {
+      headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+    });
+  } catch (error) {
+    if (!isYahooAuthError(error)) throw error;
+    clearCrumbCache();
+    const fresh = await getYahooCrumb();
+    const retryUrl = `${QUOTE_SUMMARY_URL}/${encodeURIComponent(symbol)}?modules=${modules}&crumb=${encodeURIComponent(fresh.crumb)}`;
+    return httpGet<YahooQuoteSummaryResponse>(retryUrl, {
+      headers: { "User-Agent": BROWSER_UA, Cookie: fresh.cookie },
+    });
+  }
+}
+
+function isYahooAuthError(error: unknown): boolean {
+  return error instanceof HttpError && (error.status === 401 || error.status === 429);
+}
+
+function normalizeHoldingWeight(value: YahooNumber | undefined): number | undefined {
+  const numeric = typeof value === "number" ? value : value?.raw;
+  if (numeric === undefined || !Number.isFinite(numeric) || numeric <= 0) return undefined;
+  return numeric > 1 ? roundWeight(numeric / 100) : roundWeight(numeric);
+}
+
+function normalizeSectorWeights(
+  sectors: Array<Record<string, YahooNumber>> | undefined,
+): Record<string, number> | undefined {
+  if (!sectors?.length) return undefined;
+  const weights: Record<string, number> = {};
+  for (const sector of sectors) {
+    for (const [name, rawWeight] of Object.entries(sector)) {
+      const weight = normalizeHoldingWeight(rawWeight);
+      if (weight !== undefined) weights[name] = weight;
+    }
+  }
+  return Object.keys(weights).length > 0 ? weights : undefined;
+}
+
+function roundWeight(value: number): number {
+  return Math.round(value * 10_000) / 10_000;
+}
+
 // --- Options Chain (v7 API with crumb+cookie auth) ---
 
 const BROWSER_UA =
   "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+const YAHOO_RAW_FETCH_TIMEOUT_MS = 10_000;
 
 let cachedCrumb: { crumb: string; cookie: string; expiresAt: number } | null = null;
 
@@ -147,15 +318,30 @@ export async function getYahooCrumb(): Promise<{ crumb: string; cookie: string }
   // Step 1: Hit fc.yahoo.com to get a session cookie
   const cookieRes = await fetch("https://fc.yahoo.com/t", {
     headers: { "User-Agent": BROWSER_UA },
+    signal: yahooRawFetchSignal(),
   });
   const setCookie = cookieRes.headers.get("set-cookie") ?? "";
   const cookie = setCookie.split(";")[0]; // Extract just the cookie value
+  if (!cookie) {
+    if (!cookieRes.ok) {
+      throw new Error(
+        `Yahoo crumb cookie request failed: HTTP ${cookieRes.status} ${cookieRes.statusText}`.trim(),
+      );
+    }
+    throw new Error("Yahoo crumb cookie request did not return a session cookie");
+  }
 
   // Step 2: Use the cookie to get a crumb
   const crumbRes = await fetch("https://query2.finance.yahoo.com/v1/test/getcrumb", {
     headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+    signal: yahooRawFetchSignal(),
   });
-  const crumb = await crumbRes.text();
+  if (!crumbRes.ok) {
+    throw new Error(
+      `Yahoo crumb request failed: HTTP ${crumbRes.status} ${crumbRes.statusText}`.trim(),
+    );
+  }
+  const crumb = (await crumbRes.text()).trim();
 
   if (!crumb || crumb.includes("Unauthorized")) {
     throw new Error("Failed to acquire Yahoo Finance crumb");
@@ -182,25 +368,23 @@ interface YahooOptionsResponse {
   };
 }
 
-export async function getOptionsChain(
-  symbol: string,
-  expiration?: number,
-): Promise<OptionsChain> {
+export async function getOptionsChain(symbol: string, expiration?: number): Promise<OptionsChain> {
   const cacheKey = `yahoo:options:${symbol}:${expiration ?? "nearest"}`;
   const cached = cache.get<OptionsChain>(cacheKey);
   if (cached) return cached;
 
   await rateLimiter.acquire("yahoo");
 
-  const { crumb, cookie } = await getYahooCrumb();
   const dateParam = expiration ? `&date=${expiration}` : "";
-  const url = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(crumb)}${dateParam}`;
 
   let res: Response | null = null;
   let fetchError: unknown;
   try {
+    const { crumb, cookie } = await getYahooCrumb();
+    const url = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(crumb)}${dateParam}`;
     res = await fetch(url, {
       headers: { "User-Agent": BROWSER_UA, Cookie: cookie },
+      signal: yahooRawFetchSignal(),
     });
   } catch (error) {
     fetchError = error;
@@ -214,6 +398,7 @@ export async function getOptionsChain(
       const retryUrl = `https://query1.finance.yahoo.com/v7/finance/options/${encodeURIComponent(symbol)}?crumb=${encodeURIComponent(fresh.crumb)}${dateParam}`;
       res = await fetch(retryUrl, {
         headers: { "User-Agent": BROWSER_UA, Cookie: fresh.cookie },
+        signal: yahooRawFetchSignal(),
       });
     } catch (error) {
       fetchError = error;
@@ -227,7 +412,7 @@ export async function getOptionsChain(
     try {
       const browserData = await fetchOptionsViaBrowser(symbol, expiration);
       if (browserData) {
-        const chain = parseOptionsResponse(symbol, browserData);
+        const chain = parseOptionsResponse(browserData);
         cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
         return chain;
       }
@@ -245,18 +430,25 @@ export async function getOptionsChain(
       throw new Error(message);
     }
     if (browserError instanceof Error) {
-      const message = fetchError instanceof Error ? fetchError.message : "Yahoo Finance options: fetch failed";
+      const message =
+        fetchError instanceof Error ? fetchError.message : "Yahoo Finance options: fetch failed";
       throw new Error(`${message}; browser fallback failed: ${browserError.message}`);
     }
-    throw fetchError instanceof Error ? fetchError : new Error("Yahoo Finance options: fetch failed");
+    throw fetchError instanceof Error
+      ? fetchError
+      : new Error("Yahoo Finance options: fetch failed");
   }
 
   const data: YahooOptionsResponse = await res.json();
-  const chain = parseOptionsResponse(symbol, data);
+  const chain = parseOptionsResponse(data);
   cache.set(cacheKey, chain, TTL.OPTIONS_CHAIN);
   return chain;
 }
 
+function yahooRawFetchSignal(): AbortSignal {
+  return AbortSignal.timeout(YAHOO_RAW_FETCH_TIMEOUT_MS);
+}
+
 /**
  * Compute time to expiry in years from a Yahoo expiration timestamp (midnight UTC).
  * US equity options expire at 4:00 PM ET. During EDT that is 20:00 UTC.
@@ -265,7 +457,7 @@ export async function getOptionsChain(
  */
 export function computeTimeToExpiry(expirationTs: number, nowMs: number = Date.now()): number {
   const MARKET_CLOSE_OFFSET_S = 21 * 3600; // 21:00 UTC ≈ 4 PM ET
-  const MIN_TIME_YEARS = 1 / (365 * 24);   // ~1 hour floor
+  const MIN_TIME_YEARS = 1 / (365 * 24); // ~1 hour floor
   const SECONDS_PER_YEAR = 365 * 24 * 3600;
 
   const expiryCloseTs = expirationTs + MARKET_CLOSE_OFFSET_S;
@@ -275,7 +467,73 @@ export function computeTimeToExpiry(expirationTs: number, nowMs: number = Date.n
   return Math.max(MIN_TIME_YEARS, remainingS / SECONDS_PER_YEAR);
 }
 
-function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): OptionsChain {
+function getUsOptionsMarketSession(now: Date = new Date()): OptionsMarketSession {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: "America/New_York",
+    weekday: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).formatToParts(now);
+  const part = (type: string): string => parts.find((p) => p.type === type)?.value ?? "";
+  const weekday = part("weekday");
+  if (weekday === "Sat" || weekday === "Sun") return "closed";
+
+  const hour = Number(part("hour"));
+  const minute = Number(part("minute"));
+  const minutes = hour * 60 + minute;
+  if (minutes < 9 * 60 + 30) return "pre_market";
+  if (minutes < 16 * 60) return "regular";
+  return "after_hours";
+}
+
+function buildOptionsQuoteStatus(
+  contracts: OptionContract[],
+  now: Date = new Date(),
+): OptionsQuoteStatus {
+  const marketSession = getUsOptionsMarketSession(now);
+  const totalContracts = contracts.length;
+  const zeroBidAskContracts = contracts.filter((c) => c.bid === 0 && c.ask === 0).length;
+  const allZeroBidAsk = totalContracts > 0 && zeroBidAskContracts === totalContracts;
+  const hasLiveBidAsk = contracts.some((c) => c.bid > 0 || c.ask > 0);
+
+  if (allZeroBidAsk && marketSession !== "regular") {
+    return {
+      marketSession,
+      bidAskState: "closed_market_or_stale_quotes",
+      zeroBidAskContracts,
+      totalContracts,
+      warning:
+        "All option contracts have $0.00/$0.00 bid/ask before regular options trading or outside market hours; treat bid/ask as closed-market or stale until the market opens.",
+    };
+  }
+
+  if (allZeroBidAsk) {
+    return {
+      marketSession,
+      bidAskState: "live_zero_bid_ask",
+      zeroBidAskContracts,
+      totalContracts,
+      warning:
+        "All option contracts have $0.00/$0.00 bid/ask during regular options trading hours; verify with a broker, but this may indicate live illiquidity.",
+    };
+  }
+
+  return {
+    marketSession,
+    bidAskState: hasLiveBidAsk ? "live_quotes" : "mixed_or_unknown",
+    zeroBidAskContracts,
+    totalContracts,
+    ...(marketSession !== "regular"
+      ? {
+          warning:
+            "Options bid/ask quotes may be stale outside regular options trading hours; verify live executable prices after the market opens.",
+        }
+      : {}),
+  };
+}
+
+function parseOptionsResponse(data: YahooOptionsResponse): OptionsChain {
   if (data.optionChain.error) {
     throw new Error(`Yahoo Finance options: ${JSON.stringify(data.optionChain.error)}`);
   }
@@ -284,6 +542,9 @@ function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): Optio
   const quote = result.quote;
   const underlyingPrice = quote.regularMarketPrice ?? 0;
   const opts = result.options[0];
+  if (!opts && underlyingPrice === 0) {
+    throw new InvalidSymbolError(result.underlyingSymbol, "yahoo");
+  }
   const riskFreeRate = 0.05;
 
   const expirationTs = opts.expirationDate;
@@ -293,7 +554,14 @@ function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): Optio
   const mapContract = (c: any, type: "call" | "put"): OptionContract => {
     const strike = c.strike ?? c.strike?.raw ?? 0;
     const iv = c.impliedVolatility ?? c.impliedVolatility?.raw ?? 0;
-    const greeks = computeGreeks({ type, spot: underlyingPrice, strike, timeYears, iv, riskFreeRate });
+    const greeks = computeGreeks({
+      type,
+      spot: underlyingPrice,
+      strike,
+      timeYears,
+      iv,
+      riskFreeRate,
+    });
     return {
       contractSymbol: c.contractSymbol ?? "",
       type,
@@ -314,17 +582,21 @@ function parseOptionsResponse(symbol: string, data: YahooOptionsResponse): Optio
   const puts = (opts.puts ?? []).map((c: any) => mapContract(c, "put"));
   const totalCallVolume = calls.reduce((s, c) => s + c.volume, 0);
   const totalPutVolume = puts.reduce((s, c) => s + c.volume, 0);
+  const quoteStatus = buildOptionsQuoteStatus([...calls, ...puts]);
 
   return {
     symbol: result.underlyingSymbol,
     underlyingPrice,
     expirationDate,
-    expirationDates: result.expirationDates.map((ts) => new Date(ts * 1000).toISOString().split("T")[0]),
+    expirationDates: result.expirationDates.map(
+      (ts) => new Date(ts * 1000).toISOString().split("T")[0],
+    ),
     calls,
     puts,
     totalCallVolume,
     totalPutVolume,
     putCallRatio: totalCallVolume > 0 ? totalPutVolume / totalCallVolume : 0,
+    quoteStatus,
     fetchedAt: new Date().toISOString(),
   };
 }

package/src/routing/classify-intent.ts

@@ -1,5 +1,5 @@
-import type { ClassificationResult, WorkflowType, ExtractedEntities } from "./types.js";
 import { extractEntities } from "./entity-extractor.js";
+import type { ClassificationResult, ExtractedEntities, WorkflowType } from "./types.js";
 
 interface Rule {
   workflow: WorkflowType;
@@ -29,7 +29,23 @@ const RULES: Rule[] = [
         entities.symbols.length === 1 &&
         (/\bis\s+\S+\s+(?:attractive|undervalued|overvalued|cheap|expensive)/i.test(lower) ||
           /\bshould\s+i\s+buy\s+\$?[a-z]{1,5}\b/i.test(lower) ||
-          /\bwhat\s+do\s+you\s+think\s+(?:of|about)\s+\$?[a-z]{1,5}\b/i.test(lower))
+          /\bwhat\s+do\s+you\s+think\s+(?:of|about)\s+\$?[a-z]{1,5}\b/i.test(lower) ||
+          /\bbull\s+(?:and|or)\s+bear\s+case\b/i.test(lower))
+      );
+    },
+  },
+  // Portfolio risk for existing holdings must route before multi-symbol compare.
+  {
+    workflow: "watchlist_or_tracking",
+    confidence: 0.9,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      return (
+        entities.symbols.length >= 1 &&
+        (/\bi\s+own\b/.test(lower) || /\bmy\s+holdings\b/.test(lower)) &&
+        (/\bportfolio\s+risk\b/.test(lower) ||
+          /\bbiggest\s+risk\b/.test(lower) ||
+          /\bconcentration\b/.test(lower))
       );
     },
   },
@@ -56,6 +72,65 @@ const RULES: Rule[] = [
       return hasNewsKeyword;
     },
   },
+  // Tool-backed finance tasks that are not a structured multi-step workflow.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.9,
+    test: (input, entities) => {
+      const lower = input.toLowerCase();
+      const hasOptionKeywords =
+        /\bcalls?\b/.test(lower) ||
+        /\bputs?\b/.test(lower) ||
+        /\boption(?:s)?\s*chain\b/.test(lower) ||
+        /\boptions?\b/.test(lower);
+      const hasCompareKeywords =
+        /\bcompare\b/.test(lower) ||
+        /\bvs\.?\b/.test(lower) ||
+        /\bversus\b/.test(lower) ||
+        /\bwhich\s+is\s+better\b/.test(lower);
+
+      if (hasOptionKeywords && entities.symbols.length >= 1) return false;
+      if (hasCompareKeywords && entities.symbols.length >= 2) return false;
+
+      return (
+        /\bbacktest\b/.test(lower) || /\bsentiment\b/.test(lower) || /\brate\s+cuts?\b/.test(lower)
+      );
+    },
+  },
+  // Broad market / sector / macro research that should receive the general
+  // analyst fallback rather than disappearing into an unclassified turn.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.85,
+    test: (input) => {
+      const lower = input.toLowerCase();
+      const hasResearchVerb =
+        /\banaly[sz]e\b/.test(lower) ||
+        /\bevaluat(?:e|ion)\b/.test(lower) ||
+        /\breview\b/.test(lower) ||
+        /\bdiscuss\b/.test(lower) ||
+        /\bpredict\b/.test(lower) ||
+        /\bassess\b/.test(lower) ||
+        /^what\b/.test(lower);
+      const hasBroadFinanceTopic =
+        /\bmarket\s+structure\b/.test(lower) ||
+        /\b(?:sector|industry)\b/.test(lower) ||
+        /\bmacro\s+risks?\b/.test(lower) ||
+        /\bmonetary\s+policy\b/.test(lower) ||
+        /\bemerging\s+markets?\b/.test(lower) ||
+        /\bcapital\s+flows?\b/.test(lower) ||
+        /\bcurrency\s+fluctuations?\b/.test(lower) ||
+        /\binflation\b/.test(lower);
+      return hasResearchVerb && hasBroadFinanceTopic;
+    },
+  },
+  // Existing allocation / portfolio review. This is not portfolio construction
+  // and should not require a budget.
+  {
+    workflow: "general_finance_qa",
+    confidence: 0.85,
+    test: (input) => isPortfolioEvaluationRequest(input),
+  },
   // Options: symbol + option keyword
   {
     workflow: "options_screener",
@@ -70,6 +145,14 @@ const RULES: Rule[] = [
       return hasOptionKeywords && entities.symbols.length >= 1;
     },
   },
+  // Stateful portfolio/watchlist/alert/prediction mutations must not be
+  // mistaken for compare or portfolio-construction workflows just because a
+  // cost basis, target, or currency token is present.
+  {
+    workflow: "watchlist_or_tracking",
+    confidence: 0.95,
+    test: (input) => isStatefulTrackingRequest(input),
+  },
   // Compare: keyword + 2+ symbols (uppercase)
   {
     workflow: "compare_assets",
@@ -88,9 +171,12 @@ const RULES: Rule[] = [
   {
     workflow: "compare_assets",
     confidence: 0.85,
-    test: (input) => {
+    test: (input, entities) => {
       const lower = input.toLowerCase();
-      return /\bcompare\s+[a-z]{1,5}(?:\s*,?\s*(?:and\s+)?[a-z]{1,5})+/.test(lower);
+      return (
+        entities.symbols.length >= 2 &&
+        /\bcompare\s+[a-z]{1,5}\b(?:\s*,?\s*(?:and\s+)?[a-z]{1,5}\b)+/.test(lower)
+      );
     },
   },
   // Compare: 2+ uppercase symbols without explicit keyword
@@ -161,6 +247,9 @@ const RULES: Rule[] = [
   },
 ];
 
+/**
+ * @deprecated Use the LLM router (`route`) for new classification paths; keep this only for rules-mode fallback and deterministic safety nets.
+ */
 export function classifyIntent(input: string): ClassificationResult {
   const trimmed = input.trim();
   if (!trimmed) {
@@ -192,3 +281,96 @@ export function classifyIntent(input: string): ClassificationResult {
     entities,
   };
 }
+
+function isPortfolioEvaluationRequest(input: string): boolean {
+  const lower = input.toLowerCase();
+  const hasEvaluationIntent =
+    /\b(?:evaluat(?:e|ion)|review|assess|analy[sz]e|prospects?|risks?|opportunities?|mitigat(?:e|ion)|adjustment)\b/.test(
+      lower,
+    );
+  const hasPortfolioObject =
+    /\b(?:portfolio|allocation|asset\s+allocation|60\/40|equity|fixed\s+income|bonds?)\b/.test(
+      lower,
+    );
+  const hasConstructionIntent =
+    /\b(?:build|create|construct|put\s+together|invest|allocate)\b/.test(lower) &&
+    /\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower);
+  return hasEvaluationIntent && hasPortfolioObject && !hasConstructionIntent;
+}
+
+function isStatefulTrackingRequest(input: string): boolean {
+  const lower = input.toLowerCase();
+  const hasPortfolioConstructionIntent =
+    /\b(?:build|create|construct|put\s+together)\b/.test(lower) &&
+    /\bportfolio\b/.test(lower) &&
+    /\$\s*\d|\b\d+(?:\.\d+)?\s*k\b|\bbudget\b|\bcapital\b/.test(lower);
+  const hasStateVerb =
+    /\b(?:add|remove|update|record|track|create|configure|check|show|list|view|cancel)\b/.test(
+      lower,
+    );
+  const hasStateObject =
+    /\b(?:watchlist|portfolio|holding|holdings|position|positions|prediction|predictions|alert|alerts|daily\s+report|watchlist\s+report|report\s+history)\b/.test(
+      lower,
+    );
+  const hasPortfolioLotShape =
+    /\b(?:add|record|track)\b/.test(lower) &&
+    /\b\d+(?:\.\d+)?\s+shares?\b/.test(lower) &&
+    /\b(?:portfolio|holding|holdings|position|positions)\b/.test(lower);
+  if (hasPortfolioConstructionIntent) return false;
+  return (hasStateVerb && hasStateObject) || hasPortfolioLotShape;
+}
+
+const FINANCE_SIGNAL_TERMS = [
+  "stock",
+  "stocks",
+  "shares",
+  "ticker",
+  "tickers",
+  "etf",
+  "etfs",
+  "ipo",
+  "earnings",
+  "dividend",
+  "dividends",
+  "valuation",
+  "stock market",
+  "invest",
+  "investing",
+  "investment",
+  "portfolio",
+  "watchlist",
+  "bond",
+  "bonds",
+  "bond yield",
+  "treasury",
+  "the fed",
+  "inflation",
+  "interest rates",
+  "crypto",
+  "bitcoin",
+  "ethereum",
+  "options chain",
+  "covered call",
+  "puts",
+  "bullish",
+  "bearish",
+  "hedge",
+  "price target",
+  "cost basis",
+  "nasdaq",
+  "s&p",
+];
+
+const FINANCE_SIGNAL_PATTERN = new RegExp(
+  `\\b(?:${FINANCE_SIGNAL_TERMS.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`,
+  "i",
+);
+
+/**
+ * Deterministic finance-vocabulary check for rules-mode fallback turns whose
+ * intent did not match a workflow and whose entities carry no symbols (for
+ * example theme prompts about private companies or sectors).
+ */
+export function hasFinanceSignals(input: string): boolean {
+  return FINANCE_SIGNAL_PATTERN.test(input);
+}