opencandle 0.4.0 → 0.6.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 "";
   }
@@ -48,7 +49,11 @@ const DISPLAY_NAMES: Record<string, string> = {
   objective: "objective",
   moneynessPreference: "moneyness",
   liquidityMinimum: "liquidity",
+  optionStrategy: "option strategy",
+  costBasis: "cost basis",
+  shareQuantity: "share quantity",
   symbols: "symbols",
+  metrics: "metrics",
 };
 
 /**
@@ -62,6 +67,8 @@ export function buildDisclosureBlock(
 ): string {
   const userSpecified: string[] = [];
   const fromPreferences: string[] = [];
+  const fromPriorContext: string[] = [];
+  const fromMemory: string[] = [];
   const defaults: string[] = [];
 
   for (const [key, source] of Object.entries(slotSources)) {
@@ -75,6 +82,12 @@ export function buildDisclosureBlock(
       case "preference":
         fromPreferences.push(display);
         break;
+      case "prior_context":
+        fromPriorContext.push(display);
+        break;
+      case "memory":
+        fromMemory.push(display);
+        break;
       case "default":
         defaults.push(display);
         break;
@@ -84,7 +97,11 @@ 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 (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) {
     lines.push(`  Workflow constraints: ${workflowConstraints.join(", ")}`);
@@ -124,7 +141,11 @@ function formatSlotValue(value: unknown): string {
 
 export function buildPortfolioPrompt(resolution: SlotResolution<PortfolioSlots>): string {
   const { resolved: s, sources } = resolution;
-  const isEtfOnly = s.assetScope.toLowerCase().startsWith("etf");
+  const normalizedScope = s.assetScope.toLowerCase();
+  const isFundBuildingBlocks =
+    normalizedScope.includes("etf") ||
+    normalizedScope.includes("fund") ||
+    normalizedScope.includes("building_blocks");
 
   const disclosureBlock = buildDisclosureBlock(
     {
@@ -138,12 +159,14 @@ export function buildPortfolioPrompt(resolution: SlotResolution<PortfolioSlots>)
     sources as Record<string, SlotSource | undefined>,
   );
 
-  const toolSteps = isEtfOnly
-    ? `1. Identify ${s.positionCount} diverse ETF candidates appropriate for a ${s.riskProfile} ${s.timeHorizon} portfolio.
+  const toolSteps = isFundBuildingBlocks
+    ? `1. Identify ${s.positionCount} diversified fund/ETF building-block candidates appropriate for a ${s.riskProfile} ${s.timeHorizon} portfolio.
+   Include distinct asset-class roles such as core domestic equity, international equity, fixed income, short-duration or cash-like stability, and inflation-sensitive ballast when appropriate.
 2. Use get_stock_quote for each candidate to get current prices.
 3. Use analyze_risk on each candidate for volatility, Sharpe, and max drawdown.
 4. Use analyze_correlation across all candidates to check diversification.`
     : `1. Identify ${s.positionCount} diverse candidates appropriate for a ${s.riskProfile} ${s.timeHorizon} portfolio.
+   Avoid over-concentration in individual equities unless the user explicitly asked for stock picks; use diversified funds where they better fit the requested horizon and risk profile.
 2. Use get_stock_quote for each candidate to get current prices.
 3. Use get_company_overview for fundamentals on each candidate.
 4. Use analyze_risk on each candidate for volatility, Sharpe, and max drawdown.
@@ -162,17 +185,28 @@ Build a draft portfolio under these parameters:
 Steps:
 ${toolSteps}
 
+Portfolio construction guardrails:
+- For broad balanced portfolio requests, prefer diversified building blocks over individual-company concentration unless the user explicitly asks for stocks.
+- For horizons under 5 years, include enough fixed-income, short-duration, cash-like, or inflation-sensitive ballast to make the drawdown risk match the horizon.
+- If a candidate's risk metrics undermine its role (for example materially negative risk-adjusted returns, high drawdown, or excessive correlation), lower the allocation, name a role-equivalent replacement, or explain why you are keeping it.
+- Keep rationale tied to each holding's role in this portfolio; do not paste company descriptions or generic issuer background.
+
 ${disclosureBlock}
 
 Response format:
 - Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
+- Then start the analysis with "Bottom line:" and directly say what portfolio you would build for the user.
 - Commit to the draft: give concrete percentages for each position, not ranges, and not "consider allocating X-Y%".
-- Present an allocation table: symbol, allocation %, dollar amount, and a one-line analyst rationale for each position (what the data showed).
+- Present an allocation table: symbol, allocation %, dollar amount, current price used, estimated shares, role, and a one-line analyst rationale for each position (what the data showed and why it belongs in this portfolio).
+- After the table, add a brief "Why this fits the horizon" summary explaining the growth/stability tradeoff and horizon-specific risks for the stated time horizon.
 - Include a risk summary (portfolio volatility, diversification quality) and an invalidation condition for the overall draft ("revisit if correlation exceeds 0.7 across the core ETFs" or equivalent).
+- Include practical implementation notes: rebalance cadence, low-cost/liquid implementation, and tax/account caveats where relevant.
 - 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();
@@ -199,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(
     {
@@ -216,11 +251,70 @@ For LEAPS / long-dated options:
       objective: s.objective,
       moneynessPreference: s.moneynessPreference,
       liquidityMinimum: s.liquidityMinimum,
+      ...(s.maxPremium !== undefined ? { maxPremium: formatBudget(s.maxPremium) } : {}),
+      ...(s.optionStrategy ? { optionStrategy: s.optionStrategy } : {}),
+      ...(s.costBasis !== undefined ? { costBasis: formatBudget(s.costBasis) } : {}),
+      ...(s.shareQuantity !== undefined ? { shareQuantity: `${s.shareQuantity} shares` } : {}),
+      ...(s.catalystSymbols?.length ? { catalystSymbols: s.catalystSymbols.join(", ") } : {}),
     },
     sources as Record<string, SlotSource | undefined>,
     workflowConstraints,
   );
 
+  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)}`
+      : "",
+  ].join("");
+
+  const isProtectivePutContext = s.optionStrategy === "protective_put";
+  const isCoveredCallContext =
+    !isProtectivePutContext &&
+    (s.optionStrategy === "covered_call" ||
+      s.costBasis !== undefined ||
+      (s.catalystSymbols?.length ?? 0) > 0);
+  const coveredCallInstructions = isCoveredCallContext
+    ? `
+Covered-call sale guidance:
+- Treat this as selling covered calls against an existing ${s.symbol} share position, not buying calls.
+- Treat ${s.symbol} as the option-chain underlying.
+- Because the user phrased ${s.symbol} as an existing holding, briefly state that you are treating ${s.symbol} as the held ticker. If they meant memory exposure or a different ticker, tell them to clarify and do not silently switch to another underlying.
+- Do not substitute catalyst/context tickers as the option-chain underlying.
+- Use catalyst/context tickers only to frame event risk, sympathy moves, and whether a nearer expiration is appropriate.
+- Rank by premium collected, strike above cost basis, assignment risk, event risk, and live liquidity.
+- Do not describe max loss as the option premium paid. Covered-call sale risks are assignment/capped upside, share-price downside in the owned stock, IV/event risk, and poor exit liquidity.
+- If the option-chain tool reports closed_market_or_stale_quotes, do not treat zero bid/ask as confirmed live illiquidity; say the chain was checked outside regular options trading and recheck after regular options trading opens.
+- If retrieved contracts have zero bid/ask, zero open interest, or otherwise unusable live quotes, the final answer MUST still include "Best action:" and "Conditional candidate:".
+- In that fallback, "Best action:" should be no trade unless the user's broker shows a real bid, and "Conditional candidate:" should be a strike above cost basis labeled conditional on live bid/ask.
+`
+    : "";
+  const protectivePutInstructions = isProtectivePutContext
+    ? `
+Protective-put hedge guidance:
+- Treat this as buying puts to hedge an existing long ${s.symbol} share position, not buying calls.
+- Treat ${s.symbol} as the option-chain underlying.
+- Rank put contracts by protection per dollar of premium: expiration fit, hedge floor, moneyness, liquidity, and premium as a percent of the stock position.
+- For "doesn't cost too much" or similar cost-sensitive language, prefer liquid puts modestly below the current stock price before far-OTM lottery hedges; explain the tradeoff between cheaper premium and weaker protection.
+- If share quantity is provided, use 1 put contract per 100 shares when discussing coverage and contract count.
+- If share quantity is provided, state total premium for the required number of contracts in the ranked table or top-pick explanation.
+- Include the hedge floor: approximate protected stock value at strike, net of premium where possible.
+- Mention lower-cost alternatives such as a collar or put spread when outright put premium is high.
+- Long protective puts have premium/decay risk and exercise/exit choices; do not frame assignment risk like a short option sale.
+`
+    : "";
+  const topPickExplanation = isCoveredCallContext
+    ? `Explain why the top pick is ranked #1. For covered calls with a cost basis, include the effective assignment sale price (strike + premium collected) and compare it with the ${s.costBasis !== undefined ? formatBudget(s.costBasis) : "user's"} cost basis.`
+    : "Explain why the top pick is ranked #1.";
+
   return `Current date: ${dateStr}
 Do NOT invent or assume a different current date.${expirationSection}
 
@@ -229,51 +323,160 @@ Screen and rank options contracts for ${s.symbol}:
 - DTE target: ${s.dteTarget}${tag(sources.dteTarget)}
 - Objective: ${s.objective}${tag(sources.objective)}
 - Moneyness: ${s.moneynessPreference}${tag(sources.moneynessPreference)}
-- Liquidity: ${s.liquidityMinimum}${tag(sources.liquidityMinimum)}${s.budget ? `\n- Budget: ${formatBudget(s.budget)}` : ""}${s.maxPremium ? `\n- Max premium: ${formatBudget(s.maxPremium)}` : ""}
+- Liquidity: ${s.liquidityMinimum}${tag(sources.liquidityMinimum)}${coveredCallContext}${s.budget ? `\n- Budget: ${formatBudget(s.budget)}` : ""}${s.maxPremium ? `\n- Max premium: ${formatBudget(s.maxPremium)}` : ""}
 
 Steps:
 1. Use get_stock_quote for ${s.symbol} to get current price and recent movement.
 2. Use get_option_chain for ${s.symbol} to get the full chain with Greeks. If you filter by contract type, pass \`type: "call"\` or \`type: "put"\` in lowercase.
-3. Filter contracts matching: ${s.direction === "bullish" ? "calls" : "puts"}, DTE near ${s.dteTarget}, ${s.moneynessPreference} strikes.
-4. Rank by ${s.objective}: balance premium cost, delta exposure, and probability of profit.
+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.
+`
+    : ""
+}
 ${longDatedInstructions}
+${coveredCallInstructions}
+${protectivePutInstructions}
 ${rankingConstraints}
 ${disclosureBlock}
 
 Response format:
 - Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
-- Present top 3-5 ranked contracts in a table: strike, expiry, premium, delta, IV, OI, bid-ask spread.
-- Explain why the top pick is ranked #1.
-- Include risk caveats (max loss = premium, IV crush risk, time decay).`;
+- ${isCoveredCallContext ? `Start with an Interpretation line: "Interpretation: Treating ${s.symbol} as the held ticker because you phrased it as an existing position. If you meant ${s.symbol} as memory exposure or another ticker, clarify before trading."` : isProtectivePutContext ? `Start with an Interpretation line: "Interpretation: Treating this as buying protective puts on an existing long ${s.symbol} share position."` : "State the interpretation only if the user's requested underlying is ambiguous."}
+- Present top 3-5 ranked contracts in a table: strike, expiry, premium, delta, gamma, theta, vega, rho, IV, OI, bid-ask spread${isProtectivePutContext ? ", hedge floor, premium % of position" : ""}.
+- ${topPickExplanation}
+- Verify bid/ask and open interest in the user's broker before trading, even when OC shows live values.
+- Include ${isCoveredCallContext ? "covered-call sale risks (assignment/capped upside, share-price downside in the owned stock, IV/event risk, exit liquidity). Do not describe max loss as the option premium paid" : isProtectivePutContext ? "protective-put risks (premium decay/cost, imperfect hedge before the strike, liquidity, and opportunity cost). Do not discuss short-option assignment risk" : "risk caveats (max loss = premium, IV crush risk, time decay)"}.`;
 }
 
 export function buildCompareAssetsPrompt(resolution: SlotResolution<CompareAssetsSlots>): string {
   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.`
+    : "";
+  const interestRateStep = isInterestRateSensitive
+    ? `\n${includeSentiment ? "7" : "6"}. Use get_economic_data for the current Fed funds backdrop. Treat this as historical/current context unless you also have explicit futures or forecast evidence.`
+    : "";
+  const sentimentMetric = includeSentiment ? ", sentiment score/summary" : "";
+  const interestRateGuidance = isInterestRateSensitive
+    ? `
+interest-rate comparison guidance:
+- Separate the user's conditional premise from observed data: if the prompt says rates "start falling," state that the recommendation depends on why rates fall and whether market pricing confirms it.
+- Give a compact scenario split: benign disinflation/soft landing, recession or earnings shock, and sticky inflation or renewed rate pressure. State which asset type should benefit in each case and why.
+- Connect rates to asset mechanics: duration-like sensitivity of future earnings, cost of capital, earnings resilience, valuation multiples, and risk appetite.
+- For ETF or fund comparisons, include concentration and sector-exposure risk when one asset is meaningfully narrower or more growth/technology-heavy than the other.
+- If forward valuation, earnings estimates, or rate-futures evidence is unavailable, say that directly and avoid treating historical Fed funds data as a forecast.`
+    : "";
+  const overlapGuidance = isOverlapComparison
+    ? `
+ETF overlap guidance:
+- Treat this as an ETF overlap and diversification question, not a generic return ranking.
+- Lead with whether adding the second ETF creates a mega-cap technology tilt, growth-factor tilt, or real diversification.
+- Explain that holdings overlap and sector concentration are not the same as correlation; correlation is supporting evidence, not the answer.
+- 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:
+- Treat this as a hedge-role comparison, not a generic "which asset has better recent technicals" ranking.
+- Prioritize what each asset hedges: inflation, falling real yields, USD weakness, geopolitical/systemic shocks, liquidity stress, and risk-asset drawdowns.
+- Compare volatility, drawdown, and correlation regime stability. If a metric is unavailable for one asset, explain how that limits confidence instead of awarding the other asset by default.
+- Use current macro evidence where available: real yields or Fed-rate direction, inflation trend, USD/liquidity backdrop, and risk-on/risk-off conditions.
+- Include a compact scenario map for stagflation, rising real yields, liquidity crunch/risk-off, USD debasement, and geopolitical shock. State which asset is likely the better hedge in each scenario and why.
+- End with conditional guidance: prefer the steadier hedge for capital preservation; prefer the higher-volatility asset only for debasement/asymmetric-upside exposure.`
+    : "";
+  const tableInstruction = isMacroHedge
+    ? "- 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."
+      : 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.`
+    : 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.
+7. Use historical risk and technical metrics as context, but explain what they do and do not imply over ${timeHorizon}.`
+    : "";
+  const horizonResponse = timeHorizon
+    ? `
+- Start the verdict by directly answering whether the assets should compare for a ${timeHorizon} horizon and why.
+- Prioritize the evidence that matters most over ${timeHorizon}: near-term catalysts, earnings/guidance, forward-looking valuation/estimates, sentiment, macro sensitivity, and company-specific risks.
+- Call out evidence that is missing or unavailable, especially forward-looking estimates or company-specific catalysts.`
+    : "";
 
   const disclosureBlock = buildDisclosureBlock(
-    { symbols: symbolList },
+    {
+      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>,
   );
 
   return `Current date: ${todayStr()}
 
-Compare these assets side by side: ${symbolList}
+Compare these assets side by side: ${symbolList}${horizonLine}${budgetLine}
 
 Steps:
 1. Use get_stock_quote for each of: ${symbolList}.
 2. Use compare_companies with symbols [${symbols.map((s) => `"${s}"`).join(", ")}] for peer metrics. If some fundamentals are unavailable, continue the comparison with the available symbols and mark missing metrics as unavailable.
-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.
+${technicalRiskSteps}${sentimentStep}${interestRateStep}${horizonSteps}
+${macroHedgeSteps}
+${interestRateGuidance}
+${overlapGuidance}
 
 ${disclosureBlock}
 
 Response format:
 - Start with the assumptions block above exactly as written. Do not relabel source attribution anywhere else in your response.
-- Present a comparison table with key metrics: price, P/E, revenue growth, profit margin, RSI, Sharpe, max drawdown.
-- Highlight which asset is stronger on each metric.
+${tableInstruction}
 - Provide a summary verdict: which is most attractive and why.
-- Note any caveats (different sectors, market cap disparity, unavailable fundamentals, etc.).`;
+- Note any caveats (different sectors, concentration, market cap disparity, unavailable fundamentals, unavailable forward-looking estimates, etc.).${horizonResponse}`;
 }

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;
@@ -27,10 +27,24 @@ function buildUrl(fn: string, params: Record<string, string>, apiKey: string): s
   return `${BASE_URL}?${qs}`;
 }
 
-export async function getOverview(
-  symbol: string,
-  apiKey: string,
-): Promise<CompanyOverview> {
+function throwIfApiMessage(data: unknown): void {
+  if (!data || typeof data !== "object") return;
+
+  const payload = data as Record<string, unknown>;
+  const message = payload.Note ?? payload.Information ?? payload["Error Message"];
+  if (typeof message !== "string" || message.length === 0) return;
+
+  const normalized = message.toLowerCase();
+  if (normalized.includes("api call frequency") || normalized.includes("rate limit")) {
+    throw new Error(`Alpha Vantage rate limited: ${message}`);
+  }
+  if (normalized.includes("invalid api")) {
+    throw new ProviderCredentialError("alpha_vantage", "stale");
+  }
+  throw new Error(`Alpha Vantage error: ${message}`);
+}
+
+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);
@@ -44,6 +58,7 @@ export async function getOverview(
 
     const url = buildUrl("OVERVIEW", { symbol }, apiKey);
     const data = await httpGet<Record<string, string>>(url);
+    throwIfApiMessage(data);
 
     if (!data.Symbol) {
       cache.set(missingCacheKey, "missing", MISSING_OVERVIEW_TTL);
@@ -80,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;
@@ -93,6 +105,7 @@ export async function getEarnings(
 
     const url = buildUrl("EARNINGS", { symbol }, apiKey);
     const data = await httpGet<{ quarterlyEarnings: any[] }>(url);
+    throwIfApiMessage(data);
 
     const quarterly = (data.quarterlyEarnings ?? []).slice(0, 8).map((e: any) => ({
       date: e.fiscalDateEnding,
@@ -113,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) ?? {};
@@ -178,13 +196,12 @@ export async function getFinancials(
 async function fetchStatement<T>(fn: string, symbol: string, apiKey: string): Promise<T> {
   await rateLimiter.acquire("alphavantage");
   const url = buildUrl(fn, { symbol }, apiKey);
-  return httpGet<T>(url);
+  const data = await httpGet<T>(url);
+  throwIfApiMessage(data);
+  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;
@@ -194,6 +211,7 @@ export async function getGlobalQuote(
 
     const url = buildUrl("GLOBAL_QUOTE", { symbol }, apiKey);
     const data = await httpGet<{ "Global Quote": Record<string, string> }>(url);
+    throwIfApiMessage(data);
     const gq = data["Global Quote"];
 
     if (!gq || !gq["05. price"]) {
@@ -211,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(),
     };
 
@@ -244,14 +262,17 @@ 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)"];
     if (!timeSeries) {
       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,
@@ -260,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;
@@ -275,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";
+  }
+}