opencandle 0.3.0 → 0.5.0

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

@@ -0,0 +1,316 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getSubredditPosts, getPostComments } from "../../providers/reddit.js";
+import { getTwitterSentiment } from "../../providers/twitter.js";
+import { searchWeb } from "../../providers/web-search.js";
+import { getCompanyNews, finnhubDateRange } from "../../providers/finnhub.js";
+import { getQuote } from "../../providers/yahoo-finance.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { TwitterAdapter } from "../../sentiment/adapters/twitter.js";
+import { RedditAdapter } from "../../sentiment/adapters/reddit.js";
+import { WebAdapter } from "../../sentiment/adapters/web.js";
+import { FinnhubAdapter, extractTickersFromQuery } from "../../sentiment/adapters/finnhub.js";
+import { getSentimentPipeline } from "../../sentiment/index.js";
+import type { SentinelRecord } from "../../sentiment/types.js";
+import { hasCredential } from "../../onboarding/providers.js";
+import { buildSoftDegradedTag } from "../../onboarding/tool-tags.js";
+
+const params = Type.Object({
+  query: Type.String({ description: "Ticker or topic for cross-source sentiment summary" }),
+  hours: Type.Optional(
+    Type.Number({ description: "Lookback window in hours for live fetching. Default: 24" }),
+  ),
+});
+
+export const sentimentSummaryTool: AgentTool<typeof params> = {
+  name: "get_sentiment_summary",
+  label: "Sentiment Summary",
+  description:
+    "Cross-source sentiment summary combining Twitter, Reddit, and web/news. Returns per-source scores, aggregate sentiment, and divergence detection.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const hours = args.hours ?? 24;
+    const config = getConfig();
+    const warnings: string[] = [];
+    const allRecords: SentinelRecord[] = [];
+
+    const twitterAdapter = new TwitterAdapter();
+    const webAdapter = new WebAdapter();
+    const finnhubAdapter = new FinnhubAdapter();
+
+    // Determine if Finnhub should be included (key configured + ticker in
+    // query). `candidateTickers` is extracted unconditionally so we can tell
+    // a "no finnhub-mappable ticker in the query" case apart from a "query
+    // has tickers but user has no Finnhub key" case — the latter warrants a
+    // soft-degraded tag so the LLM surfaces it in the Data gaps section.
+    const candidateTickers = extractTickersFromQuery(args.query);
+    const finnhubTickers = config.finnhubApiKey ? candidateTickers : [];
+    const includeFinnhub = finnhubTickers.length > 0 && Boolean(config.finnhubApiKey);
+    const finnhubSoftDegraded =
+      candidateTickers.length > 0 && !hasCredential("finnhub");
+
+    // Finnhub fetch (built separately to avoid mixing promise types in allSettled)
+    const finnhubFetch: Promise<import("../../providers/finnhub.js").FinnhubArticle[]> = includeFinnhub
+      ? (async () => {
+          const { from, to } = finnhubDateRange("day");
+          const arrays = await Promise.all(
+            finnhubTickers.map((sym) => getCompanyNews(sym, from, to, config.finnhubApiKey!)),
+          );
+          return arrays.flat();
+        })()
+      : Promise.resolve([]);
+
+    // Fetch all sources in parallel
+    const [twitterResult, redditResults, webResult, finnhubResult] = await Promise.allSettled([
+      // Twitter
+      wrapProvider("twitter", () => getTwitterSentiment(args.query, 50, hours)),
+      // Reddit — cross-subreddit
+      fetchRedditCrossSubreddit(args.query, config.sentiment?.defaultSubreddits ?? ["wallstreetbets", "stocks", "investing", "options"]),
+      // Web
+      searchWeb(args.query, { freshness: "day", limit: 10, category: "news" }),
+      // Finnhub — only when includeFinnhub; otherwise resolves to []
+      finnhubFetch,
+    ]);
+
+    // Process Twitter
+    if (twitterResult.status === "fulfilled" && twitterResult.value.status === "ok") {
+      const records = twitterAdapter.mapToRecords(twitterResult.value.data, args.query);
+      allRecords.push(...records);
+    } else {
+      const reason = twitterResult.status === "rejected"
+        ? twitterResult.reason?.message ?? "unknown error"
+        : (twitterResult.value as any).reason ?? "unavailable";
+      warnings.push(`Twitter: ${reason}`);
+    }
+
+    // Process Reddit
+    if (redditResults.status === "fulfilled") {
+      const { records: redditRecords, warnings: redditWarnings } = redditResults.value;
+      allRecords.push(...redditRecords);
+      warnings.push(...redditWarnings);
+    } else {
+      warnings.push(`Reddit: ${redditResults.reason?.message ?? "unknown error"}`);
+    }
+
+    // Process Web
+    if (webResult.status === "fulfilled" && webResult.value.status === "ok") {
+      const records = webAdapter.mapToRecords(webResult.value.data, args.query);
+      allRecords.push(...records);
+    } else {
+      const reason = webResult.status === "rejected"
+        ? webResult.reason?.message ?? "unknown error"
+        : (webResult.value as any).reason ?? "unavailable";
+      warnings.push(`Web: ${reason}`);
+    }
+
+    // Process Finnhub (only when included — otherwise resolves to empty array anyway)
+    if (includeFinnhub) {
+      if (finnhubResult.status === "fulfilled") {
+        const articles = finnhubResult.value;
+        if (articles.length > 0) {
+          const records = finnhubAdapter.mapToRecords(articles, args.query);
+          allRecords.push(...records);
+        }
+      } else {
+        warnings.push(`Finnhub: ${finnhubResult.reason?.message ?? "unknown error"}`);
+      }
+    }
+
+    const softDegradedPrefix = finnhubSoftDegraded
+      ? `${buildSoftDegradedTag({
+          provider: "finnhub",
+          fallback: "other-sentiment-sources",
+          remediation: "run /connect news to enable Finnhub company news",
+        })}\n\n`
+      : "";
+
+    if (allRecords.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${softDegradedPrefix}⚠ Sentiment summary unavailable for "${args.query}" — no sources returned data.\n${warnings.join("\n")}`,
+          },
+        ],
+        details: null as any,
+      };
+    }
+
+    // Score and index through pipeline
+    const pipeline = getSentimentPipeline();
+    const result = await pipeline.processRecords(allRecords, args.query);
+
+    // Group by source (exclude comments from per-source averages)
+    const bySource: Record<string, { total: number; count: number }> = {};
+    for (const rec of result.fresh) {
+      if (rec.metadata.isComment) continue;
+      if (!bySource[rec.source]) bySource[rec.source] = { total: 0, count: 0 };
+      bySource[rec.source].total += rec.sentiment.score;
+      bySource[rec.source].count++;
+    }
+
+    const lines: string[] = [];
+    lines.push(`**Sentiment summary for "${args.query}"** (last ${hours}h):`);
+    lines.push("");
+    lines.push("| Source | Score | Count | Signal |");
+    lines.push("|--------|-------|-------|--------|");
+
+    let totalScore = 0;
+    let totalCount = 0;
+    for (const [source, stats] of Object.entries(bySource)) {
+      const avg = stats.count > 0 ? stats.total / stats.count : 0;
+      const label = sentimentLabel(avg);
+      const sourceName = source === "web" ? "Web/News" : source.charAt(0).toUpperCase() + source.slice(1);
+      lines.push(`| ${sourceName} | ${avg >= 0 ? "+" : ""}${avg.toFixed(2)} | ${stats.count} | ${label} |`);
+      totalScore += stats.total;
+      totalCount += stats.count;
+    }
+
+    const aggregate = totalCount > 0 ? totalScore / totalCount : 0;
+    lines.push("");
+    lines.push(`**Aggregate:** ${aggregate >= 0 ? "+" : ""}${aggregate.toFixed(2)} (${sentimentLabel(aggregate)})`);
+
+    const priceContext = await buildPriceContext(candidateTickers[0], aggregate);
+    if (priceContext) {
+      lines.push("");
+      lines.push(priceContext);
+    }
+
+    lines.push("");
+    lines.push("Source-coverage risk: sentiment can be noisy and missing sources can skew the signal; treat this as supporting evidence, not a standalone buy/sell input.");
+
+    // Divergence
+    if (result.divergence && result.divergence.detected) {
+      lines.push("");
+      lines.push(result.divergence.message);
+    } else if (result.divergence && !result.divergence.detected) {
+      lines.push("");
+      lines.push(result.divergence.message);
+    }
+
+    // Trend
+    if (result.trend && result.trend.length > 0) {
+      const t = result.trend[0];
+      lines.push("");
+      lines.push(`Trend: ${t.sparkline} ${t.direction} (${t.count} records)`);
+    }
+
+    if (warnings.length > 0) {
+      lines.push("");
+      lines.push(warnings.map((w) => `⚠ ${w}`).join("\n"));
+    }
+
+    const output = softDegradedPrefix + lines.join("\n");
+    return { content: [{ type: "text", text: output }], details: result };
+  },
+};
+
+async function buildPriceContext(symbol: string | undefined, aggregateSentiment: number): Promise<string | null> {
+  if (!symbol) return null;
+  try {
+    const quote = await getQuote(symbol);
+    const sign = quote.changePercent >= 0 ? "+" : "";
+    const direction = quote.changePercent > 0 ? "positive" : quote.changePercent < 0 ? "negative" : "flat";
+    const sentimentDirection = aggregateSentiment > 0 ? "positive" : aggregateSentiment < 0 ? "negative" : "neutral";
+    const relationship = sentimentDirection === "neutral" || direction === "flat" || sentimentDirection === direction
+      ? "roughly aligns with price action"
+      : "diverges from price action";
+    const freshnessNote = formatQuoteFreshnessNote(quote.timestamp);
+    return `Price context: ${quote.symbol}: $${quote.price.toFixed(2)} (${sign}${quote.changePercent.toFixed(2)}%).${freshnessNote} The ${sentimentDirection} sentiment signal ${relationship}.`;
+  } catch {
+    return null;
+  }
+}
+
+function formatQuoteFreshnessNote(timestamp: number | undefined): string {
+  if (!timestamp) return "";
+  const quoteDate = new Date(timestamp);
+  if (Number.isNaN(quoteDate.getTime())) return "";
+
+  const now = new Date();
+  const quoteDay = quoteDate.toLocaleDateString("en-US", { timeZone: "America/New_York" });
+  const currentDay = now.toLocaleDateString("en-US", { timeZone: "America/New_York" });
+  const quoteStamp = quoteDate.toLocaleString("en-US", {
+    dateStyle: "medium",
+    timeStyle: "short",
+    timeZone: "America/New_York",
+  });
+
+  const weekday = new Intl.DateTimeFormat("en-US", {
+    weekday: "long",
+    timeZone: "America/New_York",
+  }).format(now);
+  const isWeekend = weekday === "Saturday" || weekday === "Sunday";
+
+  if (quoteDay === currentDay) {
+    const marketClosedNote = isWeekend
+      ? " U.S. markets are closed today, so treat this as delayed or last available price context, not active intraday trading."
+      : "";
+    return ` Quote timestamp: ${quoteStamp} ET.${marketClosedNote}`;
+  }
+
+  const marketClosedNote = isWeekend
+    ? " U.S. markets are closed today, so treat this as last trading-session price action."
+    : "";
+
+  return ` Last available quote timestamp: ${quoteStamp} ET.${marketClosedNote}`;
+}
+
+async function fetchRedditCrossSubreddit(
+  query: string,
+  subreddits: string[],
+): Promise<{ records: SentinelRecord[]; warnings: string[] }> {
+  const adapter = new RedditAdapter();
+  const records: SentinelRecord[] = [];
+  const warnings: string[] = [];
+  const config = getConfig();
+  const commentsPerPost = config.sentiment?.commentsPerPost ?? 5;
+
+  for (const sub of subreddits) {
+    const result = await wrapProvider("reddit", () => getSubredditPosts(sub, 25));
+    if (result.status === "unavailable") {
+      warnings.push(`Reddit r/${sub}: ${result.reason}`);
+      continue;
+    }
+    const postRecords = adapter.mapPostsToRecords(result.data, query);
+
+    // Topic filter
+    const queryLower = query.toLowerCase();
+    const filtered = postRecords.filter((r) =>
+      r.text.toLowerCase().includes(queryLower) ||
+      (r.title?.toLowerCase().includes(queryLower) ?? false),
+    );
+    records.push(...filtered);
+
+    // Fetch comments for top posts
+    const topPosts = [...filtered]
+      .sort((a, b) => b.engagement.score - a.engagement.score)
+      .slice(0, 3); // fewer per sub since we're searching multiple
+    for (const post of topPosts) {
+      if ((post.engagement.replies ?? 0) === 0) continue;
+      try {
+        const comments = await getPostComments(sub, post.sourceId, commentsPerPost);
+        records.push(...adapter.mapCommentsToRecords(comments, post.sourceId, sub, query));
+      } catch { /* non-fatal */ }
+    }
+  }
+
+  // Deduplicate
+  const seen = new Set<string>();
+  const deduped = records.filter((r) => {
+    if (seen.has(r.sourceId)) return false;
+    seen.add(r.sourceId);
+    return true;
+  });
+
+  return { records: deduped, warnings };
+}
+
+function sentimentLabel(score: number): string {
+  if (score > 0.3) return "Bullish";
+  if (score < -0.3) return "Bearish";
+  if (score > 0) return "Leaning Bullish";
+  if (score < 0) return "Leaning Bearish";
+  return "Neutral";
+}

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

@@ -0,0 +1,58 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { SentimentStore } from "../../sentiment/store.js";
+import { getSentimentStore } from "../../sentiment/index.js";
+import { computeTrend } from "../../sentiment/trends.js";
+
+const params = Type.Object({
+  query: Type.String({ description: "Ticker or topic to look up sentiment history" }),
+  days: Type.Optional(
+    Type.Number({ description: "Number of days of history. Default: 7, max: 30" }),
+  ),
+  source: Type.Optional(
+    Type.Union([Type.Literal("twitter"), Type.Literal("reddit"), Type.Literal("web"), Type.Literal("finnhub")], {
+      description: "Filter to a single source. Default: all sources.",
+    }),
+  ),
+});
+
+interface TrendToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: any;
+}
+
+export const sentimentTrendTool: AgentTool<typeof params> & {
+  executeWithStore: (toolCallId: string, args: { query: string; days?: number; source?: string }, store: SentimentStore) => Promise<TrendToolResult>;
+} = {
+  name: "get_sentiment_trend",
+  label: "Sentiment Trend",
+  description:
+    "Query historical sentiment data from the local store. No live API calls — returns trends from previously fetched data. Run a sentiment query first to populate the store.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const store = getSentimentStore();
+    return sentimentTrendTool.executeWithStore(toolCallId, args, store);
+  },
+  async executeWithStore(_toolCallId, args, store) {
+    const days = Math.min(args.days ?? 7, 30);
+    const series = store.getTimeSeries(args.query, { days, bucketHours: 24 });
+
+    if (series.length === 0) {
+      return {
+        content: [{ type: "text", text: `No historical sentiment data for "${args.query}". Run a sentiment query first to populate the store.` }],
+        details: null,
+      };
+    }
+
+    const trend = computeTrend(series, (args.source as any) ?? "aggregate");
+
+    const lines = [
+      `**Sentiment trend for "${args.query}"** (${days}d):`,
+      "",
+      `${trend.sparkline}  ${trend.direction} (${trend.delta >= 0 ? "+" : ""}${trend.delta.toFixed(2)})`,
+      `Avg: ${trend.avgScore.toFixed(2)} | Records: ${trend.count}`,
+    ];
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: { trend, series } };
+  },
+};

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

@@ -0,0 +1,96 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getTwitterSentiment } from "../../providers/twitter.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { TwitterSentimentResult } from "../../types/sentiment.js";
+import { TwitterAdapter } from "../../sentiment/adapters/twitter.js";
+import { getSentimentPipeline } from "../../sentiment/index.js";
+
+const params = Type.Object({
+  query: Type.String({
+    description: "Stock ticker (e.g. AAPL) or search term (e.g. 'AAPL earnings call')",
+  }),
+  limit: Type.Optional(
+    Type.Number({ description: "Max tweets to fetch. Default: 50, max: 200" }),
+  ),
+  hours: Type.Optional(
+    Type.Number({ description: "Lookback window in hours. Default: 24" }),
+  ),
+});
+
+export const twitterSentimentTool: AgentTool<typeof params, TwitterSentimentResult> = {
+  name: "get_twitter_sentiment",
+  label: "Twitter Sentiment",
+  description:
+    "Fetch recent tweets for a stock ticker or search query and compute engagement-weighted sentiment. Returns tweet data, sentiment score, and co-mentioned tickers. Requires a Twitter session via trigger_twitter_login.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const limit = Math.min(args.limit ?? 50, 200);
+    const hours = args.hours ?? 24;
+
+    const providerResult = await wrapProvider("twitter", () =>
+      getTwitterSentiment(args.query, limit, hours),
+    );
+
+    if (providerResult.status === "unavailable") {
+      const isLoginIssue =
+        providerResult.reason.includes("No Twitter session") ||
+        providerResult.reason.includes("session expired");
+      const text = isLoginIssue
+        ? `⚠ Twitter sentiment unavailable: ${providerResult.reason}\n[LOGIN_NEEDED] Use ask_user to confirm, then call trigger_twitter_login. After success, retry this tool.`
+        : `⚠ Twitter sentiment unavailable (${providerResult.reason}).`;
+      return {
+        content: [{ type: "text", text }],
+        details: null as any,
+      };
+    }
+
+    const result = providerResult.data;
+
+    const sentimentLabel =
+      result.sentimentScore > 0.3 ? "Bullish" :
+      result.sentimentScore < -0.3 ? "Bearish" :
+      result.sentimentScore > 0 ? "Leaning Bullish" :
+      result.sentimentScore < 0 ? "Leaning Bearish" : "Neutral";
+
+    const lines = [
+      `**Twitter: ${result.query}** — ${result.tweetCount} tweets (last ${hours}h, ${result.fetchedAt})`,
+      `Sentiment: ${result.sentimentScore.toFixed(2)} (${sentimentLabel}) | Bullish: ${result.bullishCount} | Bearish: ${result.bearishCount}`,
+    ];
+
+    if (result.topMentions.length > 0) {
+      lines.push(`Co-mentions: ${result.topMentions.map((t) => `$${t}`).join(", ")}`);
+    }
+
+    lines.push("");
+    lines.push("| Author | Tweet | ❤️ | 🔁 | 💬 |");
+    lines.push("|--------|-------|----|----|----|");
+    const top = result.tweets.slice(0, 15);
+    for (const tweet of top) {
+      const text = tweet.text.replace(/\|/g, "\\|").replace(/\n/g, " ").slice(0, 100);
+      lines.push(`| @${tweet.author} | ${text} | ${tweet.likes} | ${tweet.retweets} | ${tweet.replies} |`);
+    }
+
+    if (providerResult.stale) {
+      lines.push("");
+      lines.push(`⚠ Stale data (cached at ${providerResult.timestamp})`);
+    }
+
+    // Index in sentiment store and append trend context
+    try {
+      const adapter = new TwitterAdapter();
+      const records = adapter.mapToRecords(result, args.query);
+      const pipeline = getSentimentPipeline();
+      const pipelineResult = await pipeline.processRecords(records, args.query);
+      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)`);
+      }
+    } catch {
+      // Sentiment indexing is best-effort — don't fail the tool
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: result };
+  },
+};

package/src/tools/sentiment/web-search.ts

@@ -0,0 +1,183 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { searchWeb } from "../../providers/web-search.js";
+import type { WebSearchEnvelope } from "../../types/sentiment.js";
+import { hasCredential } from "../../onboarding/providers.js";
+import { buildSoftDegradedTag } from "../../onboarding/tool-tags.js";
+
+const params = Type.Object({
+  query: Type.String({ description: "Search query — ticker, topic, or question" }),
+  category: Type.Optional(
+    Type.Union([Type.Literal("news"), Type.Literal("general")], {
+      description: 'Search category. "news" for recent articles, "general" for broader web. Default: "news"',
+    }),
+  ),
+  freshness: Type.Optional(
+    Type.Union(
+      [Type.Literal("hours"), Type.Literal("day"), Type.Literal("week"), Type.Literal("month")],
+      { description: 'Time range filter. Default: "day"' },
+    ),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Number of results (1-20). Default: 10", minimum: 1, maximum: 20 }),
+  ),
+  provider: Type.Optional(
+    Type.Union([Type.Literal("exa"), Type.Literal("brave"), Type.Literal("ddg")], {
+      description: "Override search provider (skip cascade). Default: auto (Exa → Brave → DDG)",
+    }),
+  ),
+});
+
+function escapeMd(text: string): string {
+  return text.replace(/([[\]|])/g, "\\$1");
+}
+
+function safeUrl(url: string): string {
+  if (url.startsWith("https://") || url.startsWith("http://")) return url;
+  return `https://${url}`;
+}
+
+/**
+ * Build soft-degradation tags for search providers whose credentials are
+ * missing at call time. Returns an empty string when nothing is degraded, or
+ * a newline-terminated block of `[OPENCANDLE_SOFT_DEGRADED ...]` tags ready to
+ * prepend to the tool result content. The extension's `tool_result` handler
+ * records these into the per-turn degradation accumulator; the system prompt
+ * instructs the LLM to surface them in a `**Data gaps**` section.
+ *
+ * Emission rules:
+ *   - Brave: if `hasCredential("brave") === false` AND the envelope's
+ *     provider is not `"brave"`, the cascade fell back from Brave.
+ *   - Exa:   if `hasCredential("exa") === false` AND the envelope's provider
+ *     is `"exa"`, the Exa provider used the keyless MCP path instead of the
+ *     keyed API. Envelopes served by `ddg` are NOT tagged for Exa (Exa was
+ *     tried first and failed for a reason unrelated to credentials).
+ */
+function buildSoftDegradedPrefix(data: WebSearchEnvelope): string {
+  const tags: string[] = [];
+
+  if (!hasCredential("brave") && data.provider !== "brave") {
+    tags.push(
+      buildSoftDegradedTag({
+        provider: "brave",
+        fallback: data.provider === "exa" ? "exa" : "ddg",
+        remediation: "run /connect search to enable Brave",
+      }),
+    );
+  }
+
+  if (!hasCredential("exa") && data.provider === "exa") {
+    tags.push(
+      buildSoftDegradedTag({
+        provider: "exa",
+        fallback: "keyless-mcp",
+        remediation: "run /connect search to enable keyed Exa",
+      }),
+    );
+  }
+
+  return tags.length === 0 ? "" : `${tags.join("\n")}\n\n`;
+}
+
+function buildOfficialSourceGapPrefix(query: string, data: WebSearchEnvelope): string {
+  if (!hasOfficialFedSourceGap(query, data)) return "";
+
+  return [
+    "[OPENCANDLE_SOURCE_GAP source=fed_official evidence=missing remediation=\"verify against federalreserve.gov/FOMC before stating Fed announcements\"]",
+    "Hard source gap: no official Fed/FOMC source was returned. Do not present meeting announcements, votes, quotes, appointments, leadership changes, or named policy rationales as verified; treat results as market commentary only.",
+    "",
+  ].join("\n");
+}
+
+function hasOfficialFedSourceGap(query: string, data: WebSearchEnvelope): boolean {
+  return isFedAnnouncementQuery(query) &&
+    !data.results.some((result) => isOfficialFedSource(result.source) || isOfficialFedSource(result.url));
+}
+
+function isFedAnnouncementQuery(query: string): boolean {
+  const lower = query.toLowerCase();
+  const mentionsFed = /\b(?:fed|fomc|federal reserve)\b/.test(lower);
+  const asksOfficialFact = /\b(?:announcement|meeting|minutes|statement|decision|vote|chair|governor|appointment|leadership)\b/.test(lower);
+  return mentionsFed && asksOfficialFact;
+}
+
+function isOfficialFedSource(value: string): boolean {
+  const lower = value.toLowerCase();
+  return lower.includes("federalreserve.gov") || lower.includes("fomc.gov");
+}
+
+export const webSearchTool: AgentTool<typeof params, WebSearchEnvelope> = {
+  name: "search_web",
+  label: "Web Search",
+  description:
+    "Search the web for financial news, earnings context, company events, regulatory developments, or general information. " +
+    "NOT for real-time prices, historical data, fundamentals, macro data, SEC filings, or social sentiment — those have dedicated tools.",
+  parameters: params,
+
+  async execute(_toolCallId, args) {
+    const query = args.query?.trim();
+    if (!query) {
+      return {
+        content: [{ type: "text", text: "⚠ Cannot search with an empty query." }],
+        details: null as any,
+      };
+    }
+
+    const category = args.category ?? "news";
+    const freshness = args.freshness ?? "day";
+    const limit = Math.max(1, Math.min(args.limit ?? 10, 20));
+
+    const provider = args.provider;
+    const result = await searchWeb(query, { category, freshness, limit, provider });
+
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Web search unavailable (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+
+    const data = result.data;
+
+    if (data.resultCount === 0) {
+      const zeroPrefix = buildSoftDegradedPrefix(data);
+      const sourceGapPrefix = buildOfficialSourceGapPrefix(query, data);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${zeroPrefix}${sourceGapPrefix}No results found for "${query}" (${category}, past ${freshness}).`,
+          },
+        ],
+        details: data,
+      };
+    }
+
+    const stalePrefix = result.stale
+      ? `⚠ Using cached data from ${result.timestamp}\n\n`
+      : "";
+
+    const softDegradedPrefix = buildSoftDegradedPrefix(data);
+    const sourceGapPrefix = buildOfficialSourceGapPrefix(query, data);
+    const shouldOmitResults = hasOfficialFedSourceGap(query, data);
+
+    const header = `**Web Search** — ${data.resultCount} results for "${query}" (${category}, past ${freshness}, via ${data.provider})`;
+    const items = data.results.map((r) => {
+      const title = escapeMd(r.title);
+      const snippet = escapeMd(r.snippet);
+      const url = safeUrl(r.url);
+      const pub = r.published ? `Published: ${r.published}` : "Published: unknown";
+      return `• [${title}](${url}) — ${r.source}\n  ${snippet}\n  ${pub}`;
+    });
+    const body = shouldOmitResults
+      ? "Non-official results were omitted from assistant-visible evidence for this Fed/FOMC announcement query. Verify against an official Federal Reserve or FOMC source before naming announcements or personnel changes."
+      : items.join("\n\n");
+
+    const text = `${softDegradedPrefix}${sourceGapPrefix}${stalePrefix}${header}\n\n${body}`;
+
+    return {
+      content: [{ type: "text", text }],
+      details: data,
+    };
+  },
+};