opencandle 0.3.0 → 0.5.0

package/src/tools/portfolio/risk-analysis.ts

@@ -0,0 +1,134 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getHistory } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { RiskMetrics } from "../../types/portfolio.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT, SPY)" }),
+  period: Type.Optional(
+    Type.String({ description: "Historical period for analysis: 6mo, 1y, 2y. Default: 1y" }),
+  ),
+});
+
+export const riskAnalysisTool: AgentTool<typeof params, RiskMetrics> = {
+  name: "analyze_risk",
+  label: "Risk Analysis",
+  description:
+    "Compute risk metrics for a stock: annualized return, volatility, Sharpe ratio, max drawdown, and Value at Risk (95%). All computed locally from historical data.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const period = args.period ?? "1y";
+    const result = await wrapProvider("yahoo", () => getHistory(symbol, period, "1d"));
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Risk analysis unavailable for ${symbol} (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+    const bars = result.data;
+    const closes = bars.map((b) => b.close);
+
+    if (closes.length < 30) {
+      return {
+        content: [{ type: "text", text: `Insufficient data for risk analysis (need 30+ days, got ${closes.length})` }],
+        details: null as any,
+      };
+    }
+
+    const metrics = computeRiskMetrics(symbol, closes);
+
+    const text = [
+      `**${symbol} Risk Analysis** (${bars[0].date} to ${bars[bars.length - 1].date}, ${closes.length} days)`,
+      ``,
+      `Annualized Return: ${(metrics.annualizedReturn * 100).toFixed(2)}%`,
+      `Annualized Volatility: ${(metrics.annualizedVolatility * 100).toFixed(2)}%`,
+      `Sharpe Ratio: ${metrics.sharpeRatio.toFixed(2)} ${sharpeLabel(metrics.sharpeRatio)}`,
+      `Max Drawdown: ${(metrics.maxDrawdown * 100).toFixed(2)}%`,
+      `Value at Risk (95%, daily): ${(metrics.var95 * 100).toFixed(2)}%`,
+      ``,
+      riskSummary(metrics),
+    ].join("\n");
+
+    return { content: [{ type: "text", text }], details: metrics };
+  },
+};
+
+export function computeRiskMetrics(symbol: string, closes: number[]): RiskMetrics {
+  const dailyReturns = computeDailyReturns(closes);
+  const avgDailyReturn = mean(dailyReturns);
+  const dailyVol = stddev(dailyReturns);
+
+  const annualizedReturn = avgDailyReturn * 252;
+  const annualizedVolatility = dailyVol * Math.sqrt(252);
+
+  // Sharpe ratio (assuming 5% risk-free rate)
+  const riskFreeDaily = 0.05 / 252;
+  const sharpeRatio =
+    dailyVol === 0 ? 0 : ((avgDailyReturn - riskFreeDaily) / dailyVol) * Math.sqrt(252);
+
+  const maxDrawdown = computeMaxDrawdown(closes);
+  const var95 = computeVaR(dailyReturns, 0.05);
+
+  return {
+    symbol,
+    annualizedReturn,
+    annualizedVolatility,
+    sharpeRatio,
+    maxDrawdown,
+    var95,
+  };
+}
+
+export function computeDailyReturns(prices: number[]): number[] {
+  const returns: number[] = [];
+  for (let i = 1; i < prices.length; i++) {
+    returns.push((prices[i] - prices[i - 1]) / prices[i - 1]);
+  }
+  return returns;
+}
+
+export function computeMaxDrawdown(prices: number[]): number {
+  let peak = prices[0];
+  let maxDd = 0;
+  for (const price of prices) {
+    if (price > peak) peak = price;
+    const dd = (peak - price) / peak;
+    if (dd > maxDd) maxDd = dd;
+  }
+  return maxDd;
+}
+
+export function computeVaR(returns: number[], confidence: number): number {
+  const sorted = [...returns].sort((a, b) => a - b);
+  const idx = Math.floor(sorted.length * confidence);
+  return Math.abs(sorted[idx]);
+}
+
+function mean(arr: number[]): number {
+  return arr.reduce((a, b) => a + b, 0) / arr.length;
+}
+
+function stddev(arr: number[]): number {
+  const m = mean(arr);
+  const variance = arr.reduce((sum, val) => sum + (val - m) ** 2, 0) / arr.length;
+  return Math.sqrt(variance);
+}
+
+function sharpeLabel(s: number): string {
+  if (s >= 2) return "(Excellent)";
+  if (s >= 1) return "(Good)";
+  if (s >= 0) return "(Below average)";
+  return "(Negative — losing money)";
+}
+
+function riskSummary(m: RiskMetrics): string {
+  const signals: string[] = [];
+  if (m.annualizedVolatility > 0.4) signals.push("High volatility stock");
+  if (m.maxDrawdown > 0.3) signals.push("Large historical drawdown (>30%)");
+  if (m.sharpeRatio < 0) signals.push("Negative risk-adjusted returns");
+  if (m.sharpeRatio >= 1.5) signals.push("Strong risk-adjusted performance");
+  if (m.var95 > 0.03) signals.push("High daily VaR (>3%)");
+  return signals.length > 0 ? "Flags: " + signals.join(" | ") : "Risk profile appears moderate";
+}

package/src/tools/portfolio/tracker.ts

@@ -0,0 +1,147 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { getQuote } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { Position, PortfolioSummary } from "../../types/portfolio.js";
+import { ensureParentDir, getPortfolioPath } from "../../infra/opencandle-paths.js";
+
+function loadPortfolio(): Position[] {
+  const portfolioPath = getPortfolioPath();
+  if (!existsSync(portfolioPath)) return [];
+  try {
+    return JSON.parse(readFileSync(portfolioPath, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+function savePortfolio(positions: Position[]): void {
+  const portfolioPath = getPortfolioPath();
+  ensureParentDir(portfolioPath);
+  writeFileSync(portfolioPath, JSON.stringify(positions, null, 2));
+}
+
+async function getCurrentPrice(symbol: string): Promise<number | null> {
+  const result = await wrapProvider("yahoo", () => getQuote(symbol));
+  if (result.status === "unavailable") return null;
+  return result.data.price;
+}
+
+const params = Type.Object({
+  action: Type.Union([
+    Type.Literal("add"),
+    Type.Literal("remove"),
+    Type.Literal("view"),
+  ], { description: "Action: add a position, remove a position, or view portfolio" }),
+  symbol: Type.Optional(
+    Type.String({ description: "Ticker symbol — stocks (AAPL, MSFT) or crypto with -USD suffix (BTC-USD, ETH-USD, SOL-USD). Use search_ticker to find the right ticker." }),
+  ),
+  shares: Type.Optional(
+    Type.Number({ description: "Number of shares/units (required for add)" }),
+  ),
+  avg_cost: Type.Optional(
+    Type.Number({ description: "Average cost per share/unit in USD (required for add)" }),
+  ),
+});
+
+export const portfolioTrackerTool: AgentTool<typeof params, PortfolioSummary | null> = {
+  name: "track_portfolio",
+  label: "Portfolio Tracker",
+  description:
+    "Track your portfolio of stocks and crypto. Add/remove positions with cost basis, or view current holdings with live P&L. For stocks use standard tickers (AAPL, MSFT). For crypto use the -USD suffix (BTC-USD, ETH-USD, SOL-USD). Use search_ticker first if you're unsure of the exact ticker. Data persisted to ~/.opencandle/portfolio.json.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const positions = loadPortfolio();
+
+    if (args.action === "add") {
+      if (!args.symbol || !args.shares || !args.avg_cost) {
+        throw new Error("symbol, shares, and avg_cost are required for add action.");
+      }
+      const symbol = args.symbol.toUpperCase();
+      const existing = positions.find((p) => p.symbol === symbol);
+      if (existing) {
+        const totalShares = existing.shares + args.shares;
+        existing.avgCost =
+          (existing.avgCost * existing.shares + args.avg_cost * args.shares) / totalShares;
+        existing.shares = totalShares;
+      } else {
+        positions.push({
+          symbol,
+          shares: args.shares,
+          avgCost: args.avg_cost,
+          addedAt: new Date().toISOString(),
+        });
+      }
+      savePortfolio(positions);
+      return {
+        content: [{ type: "text", text: `Added ${args.shares} shares of ${symbol} at $${args.avg_cost.toFixed(2)}` }],
+        details: null,
+      };
+    }
+
+    if (args.action === "remove") {
+      if (!args.symbol) {
+        throw new Error("symbol is required for remove action.");
+      }
+      const symbol = args.symbol.toUpperCase();
+      const idx = positions.findIndex((p) => p.symbol === symbol);
+      if (idx === -1) {
+        return {
+          content: [{ type: "text", text: `${symbol} not found in portfolio` }],
+          details: null,
+        };
+      }
+      positions.splice(idx, 1);
+      savePortfolio(positions);
+      return {
+        content: [{ type: "text", text: `Removed ${symbol} from portfolio` }],
+        details: null,
+      };
+    }
+
+    // View portfolio
+    if (positions.length === 0) {
+      return {
+        content: [{ type: "text", text: "Portfolio is empty. Use add action to add positions." }],
+        details: null,
+      };
+    }
+
+    const enriched = await Promise.all(
+      positions.map(async (p) => {
+        const currentPrice = await getCurrentPrice(p.symbol) ?? p.avgCost;
+        const marketValue = currentPrice * p.shares;
+        const totalCost = p.avgCost * p.shares;
+        return {
+          ...p,
+          currentPrice,
+          marketValue,
+          totalCost,
+          pnl: marketValue - totalCost,
+          pnlPercent: ((marketValue - totalCost) / totalCost) * 100,
+        };
+      }),
+    );
+
+    const totalValue = enriched.reduce((s, p) => s + p.marketValue, 0);
+    const totalCost = enriched.reduce((s, p) => s + p.totalCost, 0);
+
+    const summary: PortfolioSummary = {
+      positions: enriched,
+      totalValue,
+      totalCost,
+      totalPnl: totalValue - totalCost,
+      totalPnlPercent: totalCost > 0 ? ((totalValue - totalCost) / totalCost) * 100 : 0,
+    };
+
+    const header = `**Portfolio** — ${enriched.length} positions | Value: $${totalValue.toFixed(2)} | P&L: $${summary.totalPnl.toFixed(2)} (${summary.totalPnlPercent >= 0 ? "+" : ""}${summary.totalPnlPercent.toFixed(2)}%)`;
+    const rows = enriched.map((p) => {
+      const sign = p.pnlPercent >= 0 ? "+" : "";
+      return `  ${p.symbol}: ${p.shares} @ $${p.avgCost.toFixed(2)} → $${p.currentPrice.toFixed(2)} | P&L: $${p.pnl.toFixed(2)} (${sign}${p.pnlPercent.toFixed(2)}%)`;
+    });
+
+    const text = [header, ...rows].join("\n");
+    return { content: [{ type: "text", text }], details: summary };
+  },
+};

package/src/tools/portfolio/watchlist.ts

@@ -0,0 +1,159 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { getQuote } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { ensureParentDir, getWatchlistPath } from "../../infra/opencandle-paths.js";
+
+interface WatchlistItem {
+  symbol: string;
+  addedAt: string;
+  targetPrice?: number;
+  stopPrice?: number;
+  notes?: string;
+}
+
+function loadWatchlist(): WatchlistItem[] {
+  const watchlistPath = getWatchlistPath();
+  if (!existsSync(watchlistPath)) return [];
+  try {
+    return JSON.parse(readFileSync(watchlistPath, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+function saveWatchlist(items: WatchlistItem[]): void {
+  const watchlistPath = getWatchlistPath();
+  ensureParentDir(watchlistPath);
+  writeFileSync(watchlistPath, JSON.stringify(items, null, 2));
+}
+
+const params = Type.Object({
+  action: Type.Union(
+    [Type.Literal("add"), Type.Literal("remove"), Type.Literal("check")],
+    { description: "One of: 'add', 'remove', or 'check'" },
+  ),
+  symbol: Type.Optional(
+    Type.String({ description: "Ticker symbol (required for add/remove)" }),
+  ),
+  target_price: Type.Optional(
+    Type.Number({ description: "Alert when price rises above this level" }),
+  ),
+  stop_price: Type.Optional(
+    Type.Number({ description: "Alert when price falls below this level" }),
+  ),
+  notes: Type.Optional(
+    Type.String({ description: "Optional notes for why you're watching this" }),
+  ),
+});
+
+export const watchlistTool: AgentTool<typeof params> = {
+  name: "manage_watchlist",
+  label: "Watchlist",
+  description:
+    "Manage your watchlist of stocks and crypto. Add symbols with optional target and stop prices, remove symbols, or check current prices against your alert levels. Data persisted to ~/.opencandle/watchlist.json.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const items = loadWatchlist();
+
+    if (args.action === "add") {
+      if (!args.symbol) {
+        throw new Error("symbol is required for add action.");
+      }
+      const symbol = args.symbol.toUpperCase();
+      const existing = items.findIndex((i) => i.symbol === symbol);
+      const item: WatchlistItem = {
+        symbol,
+        addedAt: new Date().toISOString(),
+        ...(args.target_price != null && { targetPrice: args.target_price }),
+        ...(args.stop_price != null && { stopPrice: args.stop_price }),
+        ...(args.notes != null && { notes: args.notes }),
+      };
+      if (existing >= 0) {
+        items[existing] = item;
+      } else {
+        items.push(item);
+      }
+      saveWatchlist(items);
+      const alerts = [];
+      if (args.target_price) alerts.push(`target: $${args.target_price}`);
+      if (args.stop_price) alerts.push(`stop: $${args.stop_price}`);
+      const alertStr = alerts.length > 0 ? ` (${alerts.join(", ")})` : "";
+      return {
+        content: [{ type: "text", text: `Added ${symbol} to watchlist${alertStr}` }],
+        details: null,
+      };
+    }
+
+    if (args.action === "remove") {
+      if (!args.symbol) {
+        throw new Error("symbol is required for remove action.");
+      }
+      const symbol = args.symbol.toUpperCase();
+      const idx = items.findIndex((i) => i.symbol === symbol);
+      if (idx === -1) {
+        return {
+          content: [{ type: "text", text: `${symbol} not found in watchlist` }],
+          details: null,
+        };
+      }
+      items.splice(idx, 1);
+      saveWatchlist(items);
+      return {
+        content: [{ type: "text", text: `Removed ${symbol} from watchlist` }],
+        details: null,
+      };
+    }
+
+    // Check action
+    if (items.length === 0) {
+      return {
+        content: [{ type: "text", text: "Watchlist is empty. Use add action to add symbols." }],
+        details: null,
+      };
+    }
+
+    const checks = await Promise.all(
+      items.map(async (item) => {
+        const result = await wrapProvider("yahoo", () => getQuote(item.symbol));
+        if (result.status === "unavailable") {
+          return { ...item, currentPrice: 0, alerts: [`UNAVAILABLE: ${result.reason}`], statuses: [] };
+        }
+        const quote = result.data;
+        const alerts: string[] = [];
+        const statuses: string[] = [];
+        if (item.targetPrice && quote.price >= item.targetPrice) {
+          alerts.push(`TARGET HIT: $${quote.price.toFixed(2)} >= $${item.targetPrice}`);
+        } else if (item.targetPrice) {
+          statuses.push(`Target pending: $${quote.price.toFixed(2)} < $${item.targetPrice}`);
+        }
+        if (item.stopPrice && quote.price <= item.stopPrice) {
+          alerts.push(`STOP ALERT: $${quote.price.toFixed(2)} fell below $${item.stopPrice}`);
+        } else if (item.stopPrice) {
+          statuses.push(`Stop OK: $${quote.price.toFixed(2)} > $${item.stopPrice}`);
+        }
+        return { ...item, currentPrice: quote.price, alerts, statuses };
+      }),
+    );
+
+    const alertItems = checks.filter((c) => c.alerts.length > 0);
+    const lines = [
+      `**Watchlist** — ${items.length} symbols${alertItems.length > 0 ? ` | ${alertItems.length} ALERT(S)` : ""}`,
+      "",
+    ];
+
+    for (const c of checks) {
+      const alertStr = c.alerts.length > 0 ? ` ** ${c.alerts.join(" | ")} **` : "";
+      const statusStr = c.statuses.length > 0 ? ` | ${c.statuses.join(" | ")}` : "";
+      const targetStr = c.targetPrice ? ` | Target: $${c.targetPrice}` : "";
+      const stopStr = c.stopPrice ? ` | Stop: $${c.stopPrice}` : "";
+      lines.push(`  ${c.symbol}: $${c.currentPrice.toFixed(2)}${targetStr}${stopStr}${statusStr}${alertStr}`);
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { items: checks },
+    };
+  },
+};

package/src/tools/sentiment/reddit-sentiment.ts

@@ -0,0 +1,164 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getSubredditPosts, getPostComments } from "../../providers/reddit.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { RedditSentimentResult } from "../../types/sentiment.js";
+import { RedditAdapter } from "../../sentiment/adapters/reddit.js";
+import { getSentimentPipeline } from "../../sentiment/index.js";
+import { getConfig } from "../../config.js";
+
+const params = Type.Object({
+  subreddit: Type.Optional(
+    Type.String({
+      description:
+        "Subreddit name (e.g. wallstreetbets, stocks). If omitted, searches across default subreddits.",
+    }),
+  ),
+  query: Type.Optional(
+    Type.String({
+      description:
+        "Topic or ticker to filter posts by (e.g. AAPL, bitcoin). Searches titles and post bodies.",
+    }),
+  ),
+  subreddits: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Multiple subreddits to search. Overrides single subreddit param.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Number of posts per subreddit. Default: 25, max: 100" }),
+  ),
+});
+
+export const redditSentimentTool: AgentTool<typeof params, RedditSentimentResult> = {
+  name: "get_reddit_sentiment",
+  label: "Reddit Sentiment",
+  description:
+    "Analyze sentiment from financial Reddit communities. Supports single subreddit, multi-subreddit, and topic filtering. Returns scored posts with comment analysis and trend context.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const limit = Math.min(args.limit ?? 25, 100);
+    const config = getConfig();
+
+    // Determine subreddits to search
+    let subreddits: string[];
+    if (args.subreddits && args.subreddits.length > 0) {
+      subreddits = args.subreddits;
+    } else if (args.subreddit) {
+      subreddits = [args.subreddit];
+    } else {
+      subreddits = config.sentiment?.defaultSubreddits ?? ["wallstreetbets", "stocks", "investing", "options"];
+    }
+
+    // Fetch from all subreddits
+    const allResults: RedditSentimentResult[] = [];
+    const warnings: string[] = [];
+    for (const sub of subreddits) {
+      const providerResult = await wrapProvider("reddit", () => getSubredditPosts(sub, limit));
+      if (providerResult.status === "unavailable") {
+        warnings.push(`r/${sub}: ${providerResult.reason}`);
+        continue;
+      }
+      allResults.push(providerResult.data);
+    }
+
+    if (allResults.length === 0) {
+      return {
+        content: [{ type: "text", text: `⚠ Reddit sentiment unavailable (${warnings.join("; ")}).` }],
+        details: null as any,
+      };
+    }
+
+    // Merge and filter by query if provided
+    const adapter = new RedditAdapter();
+    let allRecords = allResults.flatMap((r) => adapter.mapPostsToRecords(r, args.query ?? subreddits.join("+")));
+
+    // Topic filtering
+    if (args.query) {
+      const queryLower = args.query.toLowerCase();
+      allRecords = allRecords.filter((r) =>
+        r.text.toLowerCase().includes(queryLower) ||
+        (r.title?.toLowerCase().includes(queryLower) ?? false),
+      );
+    }
+
+    // Deduplicate by sourceId (crossposts)
+    const seen = new Set<string>();
+    allRecords = allRecords.filter((r) => {
+      if (seen.has(r.sourceId)) return false;
+      seen.add(r.sourceId);
+      return true;
+    });
+
+    // Fetch comments for top 10 posts by engagement
+    const commentsPerPost = config.sentiment?.commentsPerPost ?? 5;
+    const topPosts = [...allRecords]
+      .sort((a, b) => b.engagement.score - a.engagement.score)
+      .slice(0, 10);
+
+    for (const post of topPosts) {
+      const sub = (post.metadata.subreddit as string) ?? subreddits[0];
+      if ((post.engagement.replies ?? 0) === 0) continue;
+      try {
+        const comments = await getPostComments(sub, post.sourceId, commentsPerPost);
+        const commentRecords = adapter.mapCommentsToRecords(
+          comments,
+          post.sourceId,
+          sub,
+          args.query ?? subreddits.join("+"),
+        );
+        allRecords.push(...commentRecords);
+      } catch {
+        // Comment fetch failures are non-fatal
+      }
+    }
+
+    // Process through pipeline
+    const pipeline = getSentimentPipeline();
+    const pipelineResult = await pipeline.processRecords(allRecords, args.query ?? subreddits.join("+"));
+
+    // Build output using first result as base for backward compatibility
+    const firstResult = allResults[0];
+    const postRecords = pipelineResult.fresh.filter((r) => !r.metadata.isComment);
+    const commentRecords = pipelineResult.fresh.filter((r) => r.metadata.isComment);
+    const avgScore = postRecords.length > 0
+      ? postRecords.reduce((s, r) => s + r.sentiment.score, 0) / postRecords.length
+      : 0;
+
+    const sentimentLabel =
+      avgScore > 0.3 ? "Bullish" :
+      avgScore < -0.3 ? "Bearish" :
+      avgScore > 0 ? "Leaning Bullish" :
+      avgScore < 0 ? "Leaning Bearish" : "Neutral";
+
+    const subLabel = subreddits.length === 1 ? `r/${subreddits[0]}` : `${subreddits.length} subreddits`;
+    const lines = [
+      `**Reddit: ${args.query ?? subLabel}** — ${postRecords.length} posts, ${commentRecords.length} comments`,
+      `Sentiment: ${avgScore.toFixed(2)} (${sentimentLabel})`,
+    ];
+
+    if (firstResult.topMentions.length > 0) {
+      lines.push(`Tickers: ${firstResult.topMentions.map((t) => `$${t}`).join(", ")}`);
+    }
+
+    lines.push("");
+    lines.push("Top posts:");
+    for (const post of postRecords.slice(0, 10)) {
+      const scoreIndicator = post.sentiment.score > 0 ? "🟢" : post.sentiment.score < 0 ? "🔴" : "⚪";
+      lines.push(`  ${scoreIndicator} ⬆${post.engagement.score} 💬${post.engagement.replies ?? 0} — ${(post.title ?? post.text).slice(0, 100)}`);
+    }
+
+    if (pipelineResult.trend && pipelineResult.trend.length > 0) {
+      const t = pipelineResult.trend[0];
+      lines.push("");
+      lines.push(`Trend: ${t.sparkline} ${t.direction} (${t.delta >= 0 ? "+" : ""}${t.delta.toFixed(2)}, ${t.count} records)`);
+    }
+
+    if (warnings.length > 0) {
+      lines.push("");
+      lines.push(`⚠ ${warnings.join("; ")}`);
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: firstResult };
+  },
+};