opencandle 0.5.0 → 0.6.0

package/src/pi/session.ts

@@ -1,17 +1,17 @@
 import "../infra/node-version.js";
 import {
   type AuthStorage,
+  type CreateAgentSessionResult,
   createAgentSession,
   DefaultResourceLoader,
+  getAgentDir,
   type ModelRegistry,
-  type CreateAgentSessionResult,
-  type SettingsManager,
   type SessionManager,
-  getAgentDir,
+  type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { loadEnv } from "../config.js";
-import openCandleExtension from "./opencandle-extension.js";
 import type { AskUserHandler } from "../types/index.js";
+import openCandleExtension from "./opencandle-extension.js";
 
 export interface CreateOpenCandleSessionOptions {
   cwd?: string;
@@ -38,7 +38,9 @@ export async function createOpenCandleSession(
         cwd,
         agentDir,
         settingsManager: options.settingsManager,
-        extensionFactories: [(pi) => openCandleExtension(pi, { askUserHandler: options.askUserHandler })],
+        extensionFactories: [
+          (pi) => openCandleExtension(pi, { askUserHandler: options.askUserHandler }),
+        ],
       })
     : undefined;
 

package/src/pi/setup.ts

@@ -1,8 +1,8 @@
 import type { Model } from "@earendil-works/pi-ai";
 import {
-  LoginDialogComponent,
   type ExtensionAPI,
   type ExtensionContext,
+  LoginDialogComponent,
 } from "@earendil-works/pi-coding-agent";
 
 type SetupMode = "startup" | "manual";
@@ -54,14 +54,18 @@ function getAvailableModels(ctx: ExtensionContext, preferredProvider?: string):
   return sortModels(ctx.modelRegistry.getAvailable(), preferredProvider);
 }
 
-export function getLlmSetupRequirement(ctx: Pick<ExtensionContext, "model" | "modelRegistry">): SetupRequirement {
+export function getLlmSetupRequirement(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+): SetupRequirement {
   if (ctx.model && ctx.modelRegistry.hasConfiguredAuth(ctx.model)) {
     return "ready";
   }
   return ctx.modelRegistry.getAvailable().length > 0 ? "select_model" : "connect_auth";
 }
 
-async function selectProviderForApiKey(ctx: ExtensionContext): Promise<ApiKeyProviderId | undefined> {
+async function selectProviderForApiKey(
+  ctx: ExtensionContext,
+): Promise<ApiKeyProviderId | undefined> {
   const choice = await ctx.ui.select("Connect an AI model", [
     "Google Gemini API",
     "OpenAI API",
@@ -79,7 +83,9 @@ async function selectProviderForApiKey(ctx: ExtensionContext): Promise<ApiKeyPro
   }
 }
 
-async function selectProviderForLogin(ctx: ExtensionContext): Promise<OAuthProviderChoice | undefined> {
+async function selectProviderForLogin(
+  ctx: ExtensionContext,
+): Promise<OAuthProviderChoice | undefined> {
   const choice = await ctx.ui.select("Connect an AI model", [
     "Google",
     "OpenAI",
@@ -112,7 +118,9 @@ async function selectAdvancedOAuthProvider(ctx: ExtensionContext): Promise<strin
 }
 
 async function runLoginDialog(ctx: ExtensionContext, providerId: string): Promise<boolean> {
-  const provider = ctx.modelRegistry.authStorage.getOAuthProviders().find((item) => item.id === providerId);
+  const provider = ctx.modelRegistry.authStorage
+    .getOAuthProviders()
+    .find((item) => item.id === providerId);
   const providerName = provider?.name ?? providerId;
   const usesCallbackServer = provider?.usesCallbackServer ?? false;
 
@@ -136,43 +144,49 @@ async function runLoginDialog(ctx: ExtensionContext, providerId: string): Promis
     });
 
     // Cast required: advanced providers return dynamic IDs outside the SDK's static union type
-    void ctx.modelRegistry.authStorage.login(providerId as any, {
-      onAuth: (info) => {
-        dialog.showAuth(info.url, info.instructions);
-        if (usesCallbackServer) {
-          void dialog
-            .showManualInput("Paste redirect URL below, or complete login in your browser:")
-            .then((value) => {
-              if (value && manualCodeResolve) {
-                manualCodeResolve(value);
-                manualCodeResolve = undefined;
-              }
-            })
-            .catch(() => {
-              if (manualCodeReject) {
-                manualCodeReject(new Error("Login cancelled"));
-                manualCodeReject = undefined;
-              }
-            });
-        } else if (providerId === "github-copilot") {
-          dialog.showWaiting("Waiting for browser authentication...");
-        }
-      },
-      onDeviceCode: (info) => {
-        dialog.showDeviceCode(info);
-        dialog.showWaiting("Waiting for authentication...");
-      },
-      onPrompt: async (prompt) => dialog.showPrompt(prompt.message, prompt.placeholder),
-      onProgress: (message) => dialog.showProgress(message),
-      onSelect: async (prompt) => {
-        const options = prompt.options.map((option, index) => `${index + 1}. ${option.label}`).join("\n");
-        const answer = await dialog.showPrompt(`${prompt.message}\n\n${options}`, "Enter a number");
-        const selectedIndex = Number.parseInt(answer.trim(), 10) - 1;
-        return prompt.options[selectedIndex]?.id;
-      },
-      onManualCodeInput: () => manualCodePromise,
-      signal: dialog.signal,
-    })
+    void ctx.modelRegistry.authStorage
+      .login(providerId as any, {
+        onAuth: (info) => {
+          dialog.showAuth(info.url, info.instructions);
+          if (usesCallbackServer) {
+            void dialog
+              .showManualInput("Paste redirect URL below, or complete login in your browser:")
+              .then((value) => {
+                if (value && manualCodeResolve) {
+                  manualCodeResolve(value);
+                  manualCodeResolve = undefined;
+                }
+              })
+              .catch(() => {
+                if (manualCodeReject) {
+                  manualCodeReject(new Error("Login cancelled"));
+                  manualCodeReject = undefined;
+                }
+              });
+          } else if (providerId === "github-copilot") {
+            dialog.showWaiting("Waiting for browser authentication...");
+          }
+        },
+        onDeviceCode: (info) => {
+          dialog.showDeviceCode(info);
+          dialog.showWaiting("Waiting for authentication...");
+        },
+        onPrompt: async (prompt) => dialog.showPrompt(prompt.message, prompt.placeholder),
+        onProgress: (message) => dialog.showProgress(message),
+        onSelect: async (prompt) => {
+          const options = prompt.options
+            .map((option, index) => `${index + 1}. ${option.label}`)
+            .join("\n");
+          const answer = await dialog.showPrompt(
+            `${prompt.message}\n\n${options}`,
+            "Enter a number",
+          );
+          const selectedIndex = Number.parseInt(answer.trim(), 10) - 1;
+          return prompt.options[selectedIndex]?.id;
+        },
+        onManualCodeInput: () => manualCodePromise,
+        signal: dialog.signal,
+      })
       .then(() => finish(true))
       .catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
@@ -248,7 +262,11 @@ async function activateDefaultModel(
   return true;
 }
 
-async function selectModel(api: ExtensionAPI, ctx: ExtensionContext, preferredProvider?: string): Promise<boolean> {
+async function selectModel(
+  api: ExtensionAPI,
+  ctx: ExtensionContext,
+  preferredProvider?: string,
+): Promise<boolean> {
   const models = getAvailableModels(ctx, preferredProvider);
   if (models.length === 0) {
     ctx.ui.notify("No available models found yet. Connect a provider first.", "warning");

package/src/pi/tool-adapter.ts

@@ -1,9 +1,9 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { TSchema } from "@sinclair/typebox";
-import { getAllTools } from "../tools/index.js";
 import { getDefaults } from "../memory/tool-defaults.js";
 import { wrapWithDefaults } from "../runtime/tool-defaults-wrapper.js";
+import { getAllTools } from "../tools/index.js";
 
 export function agentToolToPiTool<TParams extends TSchema, TDetails>(
   tool: AgentTool<TParams, TDetails>,
@@ -24,7 +24,10 @@ export function getOpenCandleToolDefinitions(): ToolDefinition[] {
   return getAllTools()
     .map((tool) => ({ tool, defaults: safeGetDefaults(tool.name) }))
     .filter(({ defaults }) => defaults.__enabled !== false)
-    .map(({ tool, defaults }) => agentToolToPiTool(wrapWithDefaults(tool, defaults)));
+    .map(({ tool, defaults }) => {
+      const { __enabled: _enabled, ...paramDefaults } = defaults;
+      return agentToolToPiTool(wrapWithDefaults(tool, paramDefaults));
+    });
 }
 
 function safeGetDefaults(toolName: string): Record<string, unknown> {

package/src/prompts/context-builder.ts

@@ -1,7 +1,7 @@
-import type { PromptSection, SectionName } from "./sections.js";
-import { SECTION_ORDER, DEFAULT_BUDGETS, truncateTobudget } from "./sections.js";
-import { renderPolicyCardForPlanning } from "./policy-cards.js";
 import type { ResolvedTurnContext } from "../routing/turn-context.js";
+import { renderPolicyCardForPlanning } from "./policy-cards.js";
+import type { PromptSection, SectionName } from "./sections.js";
+import { DEFAULT_BUDGETS, SECTION_ORDER, truncateTobudget } from "./sections.js";
 
 export interface PromptSectionReport {
   name: SectionName;
@@ -122,10 +122,7 @@ export class PromptContextBuilder {
         policyCard ? `${policyCard}\n\n${routePlaybook}` : routePlaybook,
       );
     } else if (options.fallbackContext) {
-      this.setSection(
-        "workflow-instructions",
-        buildFallbackPlaybook(options.fallbackContext),
-      );
+      this.setSection("workflow-instructions", buildFallbackPlaybook(options.fallbackContext));
     }
     if (options.memoryContext) {
       this.setSection("memory-context", formatMemorySection(options.memoryContext));
@@ -150,12 +147,26 @@ export function buildFallbackPlaybook(ctx: FallbackContext): string {
 
 export function buildRoutePlaybook(ctx: ResolvedTurnContext): string {
   const assumptionsBlock = buildResolvedAssumptionsBlock(ctx);
+  const droppedSymbols = ctx.diagnostics
+    .filter((diagnostic) => diagnostic.code === "symbol_dropped")
+    .map((diagnostic) => diagnostic.details?.token)
+    .filter((token): token is string => typeof token === "string" && token.length > 0);
+  const dropContext =
+    droppedSymbols.length > 0
+      ? `Dropped ambiguous ticker-like tokens: ${droppedSymbols.join(", ")}.`
+      : undefined;
+  const extraContext = [
+    ctx.entities.symbols.length > 0
+      ? `Router-extracted symbols: ${ctx.entities.symbols.join(", ")}. Route kind: ${ctx.routeKind}. Tool bundles: ${ctx.toolBundles.join(", ") || "(none)"}.`
+      : `Route kind: ${ctx.routeKind}. Tool bundles: ${ctx.toolBundles.join(", ") || "(none)"}.`,
+    dropContext,
+  ]
+    .filter((part): part is string => Boolean(part))
+    .join(" ");
   const fallbackContext: FallbackContext = {
     assumptionsBlock,
     missingRequired: ctx.missingRequired,
-    extraContext: ctx.entities.symbols.length > 0
-      ? `Router-extracted symbols: ${ctx.entities.symbols.join(", ")}. Route kind: ${ctx.routeKind}. Tool bundles: ${ctx.toolBundles.join(", ") || "(none)"}.`
-      : `Route kind: ${ctx.routeKind}. Tool bundles: ${ctx.toolBundles.join(", ") || "(none)"}.`,
+    extraContext,
   };
 
   if (ctx.routeKind === "clarification") {
@@ -273,14 +284,14 @@ Keep questions concise and offer specific options when possible. Prefer select-t
 CRITICAL: After ask_user answers come back, your NEXT action MUST be tool calls — not a text response. You are a data agent, not a chatbot. Never respond with generic investment categories or tell the user to come back with tickers. YOU pick the relevant assets and indicators based on what you learned, then fetch the data.`;
 
 const TOOL_CATALOG = `## Available Tools
-- **Market Data**: get_stock_quote, get_stock_history, get_crypto_price, get_crypto_history — real-time and historical price data
+- **Market Data**: screen_stocks, get_stock_quote, get_stock_history, get_crypto_price, get_crypto_history — use screen_stocks for breadth and screening prompts such as large-cap lists, oversold stocks, market movers, and filtered market scans; use get_stock_quote/get_stock_history for a single-security quote or historical OHLCV
 - **Fundamentals**: get_company_overview, get_financials, get_earnings, compute_dcf, compare_companies, get_sec_filings — company financials, valuation metrics, DCF intrinsic value, peer comparison, and SEC EDGAR filings (10-K, 10-Q, 8-K)
 - **Technical Analysis**: get_technical_indicators, backtest_strategy — SMA, EMA, RSI, MACD, Bollinger Bands, OBV, VWAP computed from price data, plus simple strategy backtesting
 - **Macro**: get_economic_data, get_fear_greed — FRED economic indicators and market sentiment
 - **Sentiment**: get_reddit_sentiment, get_twitter_sentiment, get_web_sentiment, get_sentiment_trend, get_sentiment_summary — retail and news sentiment from Reddit, Twitter/X, and web sources with historical trends and cross-source divergence detection
 - **Web Search**: search_web — breaking news, earnings context, company events, regulatory developments. Supported freshness values are hours, day, week, and month; use category general with freshness month for broad industry context; never pass unsupported values such as all, year, 3mo, quarter, or custom date ranges. When a dedicated tool can answer the question (quotes, fundamentals, earnings, macro, SEC filings, sentiment), use that tool instead — do not add search_web as a supplementary source for data available through dedicated tools
 - **Options**: get_option_chain — full options chain with strikes, bids/asks, volume, OI, IV, and computed Greeks (delta, gamma, theta, vega, rho)
-- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, analyze_holdings_overlap, track_prediction — position tracking, P&L, Sharpe ratio, VaR, watchlist with price alerts, correlation matrix, ETF/fund holdings overlap, and prediction tracking with accuracy scoring
+- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, analyze_holdings_overlap, track_prediction, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, correlation matrix, ETF/fund holdings overlap, and prediction tracking with accuracy scoring
 - **User Interaction**: ask_user — ask the user a clarification question when their request is ambiguous or missing key details`;
 
 function buildToolCatalog(addonDescriptions?: string[]): string {

package/src/prompts/policy-cards.ts

@@ -27,7 +27,7 @@ export const POLICY_CARD_IDS = [
   "general_fallback",
 ] as const;
 
-export type PromptPolicyCardId = typeof POLICY_CARD_IDS[number];
+export type PromptPolicyCardId = (typeof POLICY_CARD_IDS)[number];
 
 export interface PolicyCard {
   id: PromptPolicyCardId;
@@ -133,7 +133,7 @@ For strategy backtest prompts, use backtest_strategy evidence before judging whe
     status: "implemented",
     capabilityGapIds: [],
     content: `## Stateful Tracking Update Policy
-For watchlist, portfolio tracking, prediction recording, and prediction-check prompts, use the state tool that owns the change or lookup: manage_watchlist, track_prediction, or track_portfolio. Do not confirm a saved change from prose alone. Confirm the persisted state update with the symbol, action, direction, entry price, target, stop, conviction, timeframe, or check result that the tool accepted. If required fields for a state mutation are missing, ask the smallest clarification question instead of inventing values. For check or list operations, summarize the saved state and say clearly when no records exist. Do not turn a state update into a buy/sell recommendation unless the user separately asks for market analysis.`,
+For watchlist, portfolio tracking, alert management, daily-report, prediction recording, and prediction-check prompts, use the state tool that owns the change or lookup: manage_watchlist, track_prediction, track_portfolio, manage_alerts, or daily_watchlist_report. Do not confirm a saved change from prose alone. Confirm the persisted state update with the symbol, action, direction, entry price, target, stop, conviction, timeframe, or check result that the tool accepted. If the user asks to create an alert and check it now in the same request, call manage_alerts with the matching create action and check_after_create=true. If required fields for a state mutation are missing, ask the smallest clarification question instead of inventing values. For check or list operations, summarize the saved state and say clearly when no records exist. Do not turn a state update into a buy/sell recommendation unless the user separately asks for market analysis.`,
   },
   retail_finance_tradeoff: {
     id: "retail_finance_tradeoff",

package/src/prompts/sections.ts

@@ -32,7 +32,7 @@ export const SECTION_ORDER = [
   "output-format",
 ] as const;
 
-export type SectionName = typeof SECTION_ORDER[number];
+export type SectionName = (typeof SECTION_ORDER)[number];
 
 /** Default character budgets per section. */
 export const DEFAULT_BUDGETS: Record<SectionName, number> = {

package/src/prompts/symbol-preflight.ts

@@ -0,0 +1,80 @@
+import { type InstrumentCandidate, searchYahooInstruments } from "../market-state/resolve.js";
+
+export interface SymbolValidation {
+  valid: boolean;
+  reason?: string;
+  checkedAt: number;
+}
+
+export type SymbolValidationCache = Map<string, SymbolValidation>;
+
+export interface SymbolPreflightDrop {
+  symbol: string;
+  reason: string;
+}
+
+export interface SymbolPreflightResult {
+  valid: string[];
+  dropped: SymbolPreflightDrop[];
+}
+
+export async function preflightSymbols(
+  symbols: string[],
+  options: {
+    cache?: SymbolValidationCache;
+    search?: (query: string) => Promise<InstrumentCandidate[]>;
+  } = {},
+): Promise<SymbolPreflightResult> {
+  const cache = options.cache;
+  const search = options.search ?? searchYahooInstruments;
+  const valid: string[] = [];
+  const dropped: SymbolPreflightDrop[] = [];
+
+  for (const rawSymbol of symbols) {
+    const symbol = rawSymbol.trim().toUpperCase();
+    if (!symbol) continue;
+
+    const cached = cache?.get(symbol);
+    const validation = cached ?? (await validateSymbol(symbol, search));
+    if (!cached) cache?.set(symbol, validation);
+
+    if (validation.valid) {
+      valid.push(symbol);
+    } else {
+      dropped.push({
+        symbol,
+        reason: validation.reason ?? "no matching ticker found via resolver search",
+      });
+    }
+  }
+
+  return { valid, dropped };
+}
+
+export function formatPreflightDropAnnotation(dropped: SymbolPreflightDrop[]): string {
+  const count = dropped.length;
+  const symbols = dropped.map((drop) => `${drop.symbol} (${drop.reason})`).join(", ");
+  return `[Pre-flight: dropped ${count} unknown symbol${count === 1 ? "" : "s"} - ${symbols}]`;
+}
+
+function validateSymbol(
+  symbol: string,
+  search: (query: string) => Promise<InstrumentCandidate[]>,
+): Promise<SymbolValidation> {
+  return search(symbol)
+    .then((candidates) => ({
+      valid: candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol),
+      reason: candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
+        ? undefined
+        : "no matching ticker found via resolver search",
+      checkedAt: Date.now(),
+    }))
+    .catch((error) => ({
+      valid: true,
+      reason:
+        error instanceof Error
+          ? `resolver search unavailable: ${error.message}`
+          : "resolver search unavailable",
+      checkedAt: Date.now(),
+    }));
+}

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}.