opencandle 0.10.0 → 0.11.1

package/src/system-prompt.ts

@@ -19,7 +19,7 @@ You are an analyst, not a fiduciary advisor. When asked for entry levels, price
 - **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
 - **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, 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, and prediction tracking with accuracy scoring
+- **Portfolio**: track_portfolio, analyze_risk, manage_watchlist, analyze_correlation, manage_alerts, daily_watchlist_report, manage_notifications — position tracking, P&L, Sharpe ratio, VaR, watchlist tracking, durable local alerts, daily watchlist reports, notification history, and correlation matrix
 - **User Interaction**: ask_user — ask clarification questions and setup confirmations
 
 ## Analytical Framework

package/src/tools/AGENTS.md

@@ -10,7 +10,7 @@ src/tools/
 ├── options/       # Options chains, Greeks computation
 ├── macro/         # FRED economic data, fear & greed index
 ├── sentiment/     # Reddit sentiment, news sentiment
-├── portfolio/     # Tracker, risk analysis, watchlist, correlation, predictions
+├── portfolio/     # Tracker, risk analysis, watchlist, correlation
 ├── market/        # Stock quotes, history, crypto, ticker search
 └── index.ts       # getAllTools() registry — add new tools here
 ```

package/src/tools/fundamentals/comps.ts

@@ -4,6 +4,7 @@ import { getConfig } from "../../config.js";
 import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
 import { getOverview } from "../../providers/alpha-vantage.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getYahooCompanyOverview } from "../../providers/yahoo-finance.js";
 import type { CompanyOverview } from "../../types/fundamentals.js";
 
 export interface CompsMetric {
@@ -20,6 +21,7 @@ export interface CompsResult {
   companies: CompanyOverview[];
   metrics: CompsMetric[];
   unavailableSymbols: string[];
+  unavailableReasons: Record<string, string>;
 }
 
 type MetricDef = {
@@ -65,7 +67,7 @@ export function computeComps(companies: CompanyOverview[]): CompsResult {
     return { metric: def.name, values, median, p25, p75, best, worst };
   });
 
-  return { companies, metrics, unavailableSymbols: [] };
+  return { companies, metrics, unavailableSymbols: [], unavailableReasons: {} };
 }
 
 function computeMedian(sorted: number[]): number | null {
@@ -103,23 +105,26 @@ export const compsTool: AgentTool<typeof params> = {
       const config = getConfig();
       const symbols = args.symbols.map((s) => s.toUpperCase());
 
-      const results = await Promise.all(
-        symbols.map(async (s) => ({
-          symbol: s,
-          result: await wrapProvider("alphavantage", () =>
-            getOverview(s, config.alphaVantageApiKey!),
-          ),
-        })),
-      );
-
       const companies: CompanyOverview[] = [];
       const unavailableSymbols: string[] = [];
+      const unavailableReasons: Record<string, string> = {};
+
+      for (const sym of symbols) {
+        const alphaResult = await wrapProvider("alphavantage", () =>
+          getOverview(sym, config.alphaVantageApiKey!),
+        );
+        if (alphaResult.status === "ok") {
+          companies.push(alphaResult.data);
+          continue;
+        }
 
-      for (const { symbol: sym, result: r } of results) {
-        if (r.status === "ok") {
-          companies.push(r.data);
+        const yahooResult = await wrapProvider("yahoo", () => getYahooCompanyOverview(sym));
+        if (yahooResult.status === "ok") {
+          companies.push(yahooResult.data);
         } else {
           unavailableSymbols.push(sym);
+          unavailableReasons[sym] =
+            `Alpha Vantage: ${alphaResult.reason}; Yahoo Finance: ${yahooResult.reason}`;
         }
       }
 
@@ -137,6 +142,7 @@ export const compsTool: AgentTool<typeof params> = {
 
       const result = computeComps(companies);
       result.unavailableSymbols = unavailableSymbols;
+      result.unavailableReasons = unavailableReasons;
 
       const availableSymbols = companies.map((company) => company.symbol);
       const header = `**Comparable Company Analysis**: ${availableSymbols.join(" vs ")}`;
@@ -161,9 +167,14 @@ export const compsTool: AgentTool<typeof params> = {
         unavailableSymbols.length > 0
           ? ["", `Unavailable fundamentals: ${unavailableSymbols.join(", ")}`]
           : [];
+      const reasonLines =
+        unavailableSymbols.length > 0
+          ? unavailableSymbols.map((symbol) => `  - ${symbol} (${unavailableReasons[symbol]})`)
+          : [];
       const text = [header, "", symHeader, ...rows, ...noteLines].join("\n");
+      const textWithReasons = reasonLines.length > 0 ? `${text}\n${reasonLines.join("\n")}` : text;
 
-      return { content: [{ type: "text", text }], details: result };
+      return { content: [{ type: "text", text: textWithReasons }], details: result };
     });
   },
 };

package/src/tools/fundamentals/dcf.ts

@@ -1,10 +1,11 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@sinclair/typebox";
 import { getConfig } from "../../config.js";
-import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
 import { getFinancials, getOverview } from "../../providers/alpha-vantage.js";
+import { ProviderCredentialError } from "../../providers/provider-credential-error.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
-import { getQuote } from "../../providers/yahoo-finance.js";
+import { getQuote, getYahooFinancials } from "../../providers/yahoo-finance.js";
+import type { ProviderResult } from "../../runtime/evidence.js";
 import type { FinancialStatement } from "../../types/fundamentals.js";
 
 export interface DCFResult {
@@ -45,6 +46,14 @@ export function computeDCF(params: DCFParams): DCFResult {
     sharesOutstanding,
   } = params;
 
+  // Gordon Growth requires discount > terminal growth; a non-positive spread
+  // divides by zero or flips the terminal value's sign.
+  if (discountRate <= terminalGrowth) {
+    throw new Error(
+      `Gordon Growth constraint violated: terminal growth (${(terminalGrowth * 100).toFixed(1)}%) must be below the discount rate (${(discountRate * 100).toFixed(1)}%).`,
+    );
+  }
+
   // Project future cash flows (mid-year convention: discount at year-0.5)
   const projectedCashFlows: Array<{ year: number; fcf: number; presentValue: number }> = [];
   for (let y = 1; y <= years; y++) {
@@ -152,12 +161,36 @@ function computeDCFSimple(
   return (sumPV + pvTV - debt) / shares;
 }
 
-export function computeNetDebt(f: FinancialStatement): number {
+export function computeNetDebt(f: FinancialStatement): number | null {
   if (f.totalDebt != null && f.cashAndEquivalents != null) {
     return f.totalDebt - f.cashAndEquivalents;
   }
-  // Fallback: totalLiabilities - totalAssets (negative means net cash position)
-  return f.totalLiabilities - f.totalAssets;
+  return null;
+}
+
+async function optionalAlphaVantage<T>(
+  apiKey: string | undefined,
+  fn: (apiKey: string) => Promise<T>,
+): Promise<ProviderResult<T>> {
+  if (!apiKey) {
+    return {
+      status: "unavailable",
+      reason: "Alpha Vantage API key not configured",
+      provider: "alphavantage",
+    };
+  }
+  try {
+    return await wrapProvider("alphavantage", () => fn(apiKey));
+  } catch (error) {
+    if (error instanceof ProviderCredentialError) {
+      return {
+        status: "unavailable",
+        reason: `Alpha Vantage credential ${error.reason}`,
+        provider: "alphavantage",
+      };
+    }
+    throw error;
+  }
 }
 
 const params = Type.Object({
@@ -186,113 +219,210 @@ export const dcfTool: AgentTool<typeof params> = {
     "Compute a Discounted Cash Flow (DCF) intrinsic value estimate for a stock. Uses free cash flow, growth projections, and a discount rate to estimate what the stock is worth. Returns intrinsic value per share, margin of safety vs current price, and a sensitivity table.",
   parameters: params,
   async execute(_toolCallId, args) {
-    return withCredentialCheck("alpha_vantage", async () => {
-      const symbol = args.symbol.toUpperCase();
-      const config = getConfig();
-
-      const [overviewResult, financialsResult, quoteResult] = await Promise.all([
-        wrapProvider("alphavantage", () => getOverview(symbol, config.alphaVantageApiKey!)),
-        wrapProvider("alphavantage", () => getFinancials(symbol, config.alphaVantageApiKey!)),
-        wrapProvider("yahoo", () => getQuote(symbol)),
-      ]);
-
-      const missing: string[] = [];
-      if (overviewResult.status === "unavailable")
-        missing.push(`company overview (${overviewResult.reason})`);
-      if (financialsResult.status === "unavailable")
-        missing.push(`financial statements (${financialsResult.reason})`);
-      if (quoteResult.status === "unavailable") missing.push(`stock quote (${quoteResult.reason})`);
-
-      if (financialsResult.status === "unavailable" || quoteResult.status === "unavailable") {
+    const symbol = args.symbol.toUpperCase();
+    const config = getConfig();
+    const alphaVantageApiKey = config.alphaVantageApiKey;
+
+    const [alphaVantageFinancialsResult, quoteResult] = await Promise.all([
+      optionalAlphaVantage(alphaVantageApiKey, (apiKey) => getFinancials(symbol, apiKey)),
+      wrapProvider("yahoo", () => getQuote(symbol)),
+    ]);
+
+    const missing: string[] = [];
+    if (quoteResult.status === "unavailable") missing.push(`stock quote (${quoteResult.reason})`);
+
+    if (quoteResult.status === "unavailable") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `⚠ DCF valuation unavailable for ${symbol}. Missing: ${missing.join(", ")}. Both financials and current price are required.`,
+          },
+        ],
+        details: null,
+      };
+    }
+
+    const quote = quoteResult.data;
+    if (quote.price <= 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `⚠ DCF valuation unavailable for ${symbol}. Missing: current stock price. DCF output requires a real current quote price.`,
+          },
+        ],
+        details: null,
+      };
+    }
+
+    let financialsSource = "Alpha Vantage";
+    let financials: FinancialStatement[];
+    if (alphaVantageFinancialsResult.status === "ok" && !alphaVantageFinancialsResult.stale) {
+      financials = alphaVantageFinancialsResult.data;
+    } else {
+      const alphaVantageReason =
+        alphaVantageFinancialsResult.status === "ok"
+          ? `stale cached financial statements${
+              alphaVantageFinancialsResult.timestamp
+                ? ` from ${alphaVantageFinancialsResult.timestamp}`
+                : ""
+            }`
+          : alphaVantageFinancialsResult.reason;
+      const yahooFinancialsResult = await wrapProvider("yahoo", () => getYahooFinancials(symbol));
+      if (yahooFinancialsResult.status === "unavailable") {
         return {
           content: [
             {
               type: "text",
-              text: `⚠ DCF valuation unavailable for ${symbol}. Missing: ${missing.join(", ")}. Both financials and current price are required.`,
+              text: `⚠ DCF valuation unavailable for ${symbol}. Missing: financial statements (Alpha Vantage: ${alphaVantageReason}; Yahoo Finance: ${yahooFinancialsResult.reason}). Both financials and current price are required.`,
             },
           ],
           details: null,
         };
       }
-
-      const overview = overviewResult.status === "ok" ? overviewResult.data : null;
-      const financials = financialsResult.data;
-      const quote = quoteResult.data;
-
-      const latestFCF = financials[0]?.freeCashFlow ?? 0;
-      if (latestFCF <= 0) {
+      if (yahooFinancialsResult.stale) {
+        const cachedAt = yahooFinancialsResult.timestamp
+          ? ` from ${yahooFinancialsResult.timestamp}`
+          : "";
         return {
           content: [
             {
               type: "text",
-              text: `${symbol} has negative or zero free cash flow ($${latestFCF.toLocaleString()}). DCF is not meaningful for companies without positive FCF.`,
+              text: `⚠ DCF valuation unavailable for ${symbol}. Yahoo Finance returned stale cached financial statements${cachedAt} after Alpha Vantage could not provide fresh financial statements (${alphaVantageReason}). DCF output requires fresh financial statements and a current price.`,
             },
           ],
           details: null,
         };
       }
+      financials = yahooFinancialsResult.data;
+      financialsSource = "Yahoo Finance";
+    }
+
+    const latestFCF = financials[0]?.freeCashFlow ?? 0;
+    if (latestFCF <= 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${symbol} has negative or zero free cash flow ($${latestFCF.toLocaleString()}). DCF is not meaningful for companies without positive FCF.`,
+          },
+        ],
+        details: null,
+      };
+    }
 
-      // Estimate growth from historical FCF if not provided
-      let growthRate = args.growth_rate ?? 0.1;
-      if (!args.growth_rate && financials.length >= 2) {
-        const olderFCF = financials[1]?.freeCashFlow;
-        if (olderFCF && olderFCF > 0) {
-          growthRate = Math.max(0.02, Math.min(0.25, (latestFCF - olderFCF) / olderFCF));
-        }
+    // Estimate growth from historical FCF if not provided
+    let growthRate = args.growth_rate ?? 0.1;
+    if (!args.growth_rate && financials.length >= 2) {
+      const olderFCF = financials[1]?.freeCashFlow;
+      if (olderFCF && olderFCF > 0) {
+        growthRate = Math.max(0.02, Math.min(0.25, (latestFCF - olderFCF) / olderFCF));
       }
+    }
 
-      const discountRate = args.discount_rate ?? 0.1;
-      const terminalGrowth = args.terminal_growth ?? 0.03;
-      const years = args.projection_years ?? 5;
-      const marketCap = overview?.marketCap ?? 0;
-      const sharesOutstanding = quote.price > 0 && marketCap > 0 ? marketCap / quote.price : 1;
-      const netDebt = financials[0] ? computeNetDebt(financials[0]) : 0;
-
-      const result = computeDCF({
-        freeCashFlow: latestFCF,
-        growthRate,
-        discountRate,
-        terminalGrowth,
-        years,
-        netDebt: Math.max(0, netDebt),
-        sharesOutstanding,
-      });
-
-      const marginOfSafety = (result.intrinsicValue - quote.price) / result.intrinsicValue;
-      const upside = (result.intrinsicValue - quote.price) / quote.price;
-
-      const lines = [
-        `**${symbol} DCF Valuation**`,
-        ``,
-        `Current Price: $${quote.price.toFixed(2)}`,
-        `Intrinsic Value: $${result.intrinsicValue.toFixed(2)}`,
-        `Margin of Safety: ${(marginOfSafety * 100).toFixed(1)}%`,
-        `Upside/Downside: ${upside >= 0 ? "+" : ""}${(upside * 100).toFixed(1)}%`,
-        ``,
-        `**Assumptions**`,
-        `Free Cash Flow: $${(latestFCF / 1e9).toFixed(2)}B`,
-        `Growth Rate: ${(growthRate * 100).toFixed(1)}%`,
-        `Discount Rate (WACC): ${(discountRate * 100).toFixed(1)}%`,
-        `Terminal Growth: ${(terminalGrowth * 100).toFixed(1)}%`,
-        `Projection: ${years} years`,
-        ``,
-        `**Projected Cash Flows**`,
-        ...result.projectedCashFlows.map(
-          (cf) =>
-            `  Year ${cf.year}: FCF $${(cf.fcf / 1e9).toFixed(2)}B → PV $${(cf.presentValue / 1e9).toFixed(2)}B`,
-        ),
-        `  Terminal Value: $${(result.terminalValue / 1e9).toFixed(2)}B`,
-        `  Enterprise Value: $${(result.enterpriseValue / 1e9).toFixed(2)}B`,
-        ``,
-        `**Sensitivity Table** (Intrinsic Value at different Growth/Discount rates)`,
-        ...formatSensitivityTable(result.sensitivityTable),
-      ];
+    const discountRate = args.discount_rate ?? 0.1;
+    const terminalGrowth = args.terminal_growth ?? 0.03;
+    if (discountRate <= terminalGrowth) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `⚠ Invalid DCF assumptions for ${symbol}: terminal growth (${(terminalGrowth * 100).toFixed(1)}%) must be below the discount rate (${(discountRate * 100).toFixed(1)}%) for the Gordon Growth terminal value to be meaningful. Lower terminal_growth or raise discount_rate.`,
+          },
+        ],
+        details: null,
+      };
+    }
 
+    const years = args.projection_years ?? 5;
+    // Prefer an actual reported share count, then derive from market cap
+    // only when needed. Never substitute a placeholder share count.
+    const statementSharesOutstanding = financials[0]?.sharesOutstanding;
+    let marketCap = quote.marketCap > 0 ? quote.marketCap : 0;
+    let sharesOutstanding =
+      statementSharesOutstanding && statementSharesOutstanding > 0 ? statementSharesOutstanding : 0;
+    if (sharesOutstanding <= 0 && marketCap <= 0) {
+      const overviewResult = await optionalAlphaVantage(alphaVantageApiKey, (apiKey) =>
+        getOverview(symbol, apiKey),
+      );
+      if (overviewResult.status === "ok" && overviewResult.data.marketCap > 0) {
+        marketCap = overviewResult.data.marketCap;
+      }
+    }
+    if (sharesOutstanding <= 0 && quote.price > 0 && marketCap > 0) {
+      sharesOutstanding = marketCap / quote.price;
+    }
+    if (sharesOutstanding <= 0) {
       return {
-        content: [{ type: "text", text: lines.join("\n") }],
-        details: { ...result, currentPrice: quote.price, marginOfSafety, upside },
+        content: [
+          {
+            type: "text",
+            text: `⚠ Cannot compute a per-share DCF for ${symbol}: shares outstanding are unavailable from financial statements and cannot be derived because ${quote.price <= 0 ? "the current quote price is unavailable" : "market capitalization is unavailable from the overview and quote providers"}. Per-share intrinsic value requires a real share count.`,
+          },
+        ],
+        details: null,
       };
+    }
+    // Signed on purpose: net cash (negative net debt) adds to equity value.
+    // Omit the adjustment if debt/cash fields are missing; assets minus
+    // liabilities is book equity, not a net-cash proxy.
+    const computedNetDebt = financials[0] ? computeNetDebt(financials[0]) : null;
+    const netDebt = computedNetDebt ?? 0;
+
+    const result = computeDCF({
+      freeCashFlow: latestFCF,
+      growthRate,
+      discountRate,
+      terminalGrowth,
+      years,
+      netDebt,
+      sharesOutstanding,
     });
+    if (computedNetDebt == null) {
+      result.warnings.push(
+        "Net debt adjustment omitted because total debt and cash equivalents were unavailable.",
+      );
+    }
+
+    const marginOfSafety = (result.intrinsicValue - quote.price) / result.intrinsicValue;
+    const upside = (result.intrinsicValue - quote.price) / quote.price;
+
+    const lines = [
+      `**${symbol} DCF Valuation**`,
+      ``,
+      `Current Price: $${quote.price.toFixed(2)}`,
+      `Intrinsic Value: $${result.intrinsicValue.toFixed(2)}`,
+      `Margin of Safety: ${(marginOfSafety * 100).toFixed(1)}%`,
+      `Upside/Downside: ${upside >= 0 ? "+" : ""}${(upside * 100).toFixed(1)}%`,
+      ``,
+      `**Assumptions**`,
+      `Financial statements source: ${financialsSource}`,
+      `Free Cash Flow: $${(latestFCF / 1e9).toFixed(2)}B`,
+      `Growth Rate: ${(growthRate * 100).toFixed(1)}%`,
+      `Discount Rate (WACC): ${(discountRate * 100).toFixed(1)}%`,
+      `Terminal Growth: ${(terminalGrowth * 100).toFixed(1)}%`,
+      `Projection: ${years} years`,
+      ``,
+      `**Projected Cash Flows**`,
+      ...result.projectedCashFlows.map(
+        (cf) =>
+          `  Year ${cf.year}: FCF $${(cf.fcf / 1e9).toFixed(2)}B → PV $${(cf.presentValue / 1e9).toFixed(2)}B`,
+      ),
+      `  Terminal Value: $${(result.terminalValue / 1e9).toFixed(2)}B`,
+      `  Enterprise Value: $${(result.enterpriseValue / 1e9).toFixed(2)}B`,
+      ``,
+      `**Sensitivity Table** (Intrinsic Value at different Growth/Discount rates)`,
+      ...formatSensitivityTable(result.sensitivityTable),
+      ...(result.warnings.length > 0
+        ? ["", "**Warnings**", ...result.warnings.map((warning) => `- ${warning}`)]
+        : []),
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { ...result, currentPrice: quote.price, marginOfSafety, upside },
+    };
   },
 };
 

package/src/tools/index.ts

@@ -6,6 +6,7 @@ import { dcfTool } from "./fundamentals/dcf.js";
 import { earningsTool } from "./fundamentals/earnings.js";
 import { financialsTool } from "./fundamentals/financials.js";
 import { secFilingsTool } from "./fundamentals/sec-filings.js";
+import { eventProbabilitiesTool } from "./macro/event-probabilities.js";
 import { fearGreedTool } from "./macro/fear-greed.js";
 import { fredDataTool } from "./macro/fred-data.js";
 import { cryptoHistoryTool } from "./market/crypto-history.js";
@@ -20,7 +21,6 @@ import { correlationTool } from "./portfolio/correlation.js";
 import { dailyReportTool } from "./portfolio/daily-report.js";
 import { holdingsOverlapTool } from "./portfolio/holdings-overlap.js";
 import { notificationsTool } from "./portfolio/notifications.js";
-import { predictionsTool } from "./portfolio/predictions.js";
 import { riskAnalysisTool } from "./portfolio/risk-analysis.js";
 import { portfolioTrackerTool } from "./portfolio/tracker.js";
 import { watchlistTool } from "./portfolio/watchlist.js";
@@ -39,6 +39,7 @@ export { dcfTool } from "./fundamentals/dcf.js";
 export { earningsTool } from "./fundamentals/earnings.js";
 export { financialsTool } from "./fundamentals/financials.js";
 export { secFilingsTool } from "./fundamentals/sec-filings.js";
+export { eventProbabilitiesTool } from "./macro/event-probabilities.js";
 export { fearGreedTool } from "./macro/fear-greed.js";
 export { fredDataTool } from "./macro/fred-data.js";
 export { cryptoHistoryTool } from "./market/crypto-history.js";
@@ -53,7 +54,6 @@ export { correlationTool } from "./portfolio/correlation.js";
 export { dailyReportTool } from "./portfolio/daily-report.js";
 export { holdingsOverlapTool } from "./portfolio/holdings-overlap.js";
 export { notificationsTool } from "./portfolio/notifications.js";
-export { predictionsTool } from "./portfolio/predictions.js";
 export { riskAnalysisTool } from "./portfolio/risk-analysis.js";
 export { portfolioTrackerTool } from "./portfolio/tracker.js";
 export { watchlistTool } from "./portfolio/watchlist.js";
@@ -80,6 +80,7 @@ export function getAllTools(options: { askUserHandler?: AskUserHandler } = {}):
     dcfTool,
     compsTool,
     secFilingsTool,
+    eventProbabilitiesTool,
     fredDataTool,
     fearGreedTool,
     createRedditSentimentTool({ askUserHandler: options.askUserHandler }),
@@ -91,7 +92,6 @@ export function getAllTools(options: { askUserHandler?: AskUserHandler } = {}):
     watchlistTool,
     correlationTool,
     holdingsOverlapTool,
-    predictionsTool,
     alertsTool,
     dailyReportTool,
     notificationsTool,

package/src/tools/macro/event-probabilities.ts

@@ -0,0 +1,141 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import { searchPredictionMarkets } from "../../providers/polymarket.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { PredictionMarketQuote } from "../../types/prediction-markets.js";
+import { renderUntrustedText, untrustedContentHeader } from "../sentiment/untrusted-text.js";
+
+const LOW_LIQUIDITY_VOLUME_USD = 10_000;
+
+const params = Type.Object({
+  query: Type.String({
+    minLength: 1,
+    description: "Free-text event question to search on Polymarket.",
+  }),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 50,
+      description: "Maximum number of outcome quotes to return. Default: 8.",
+    }),
+  ),
+});
+
+export const eventProbabilitiesTool: AgentTool<typeof params, PredictionMarketQuote[]> = {
+  name: "get_event_probabilities",
+  label: "Event Probabilities",
+  description:
+    "Search Polymarket for market-implied event probabilities. Fetches and formats probabilities only; it does not analyze or forecast outcomes.",
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const query = args.query.trim();
+    const limit = args.limit ?? 8;
+    const result = await wrapProvider("polymarket", () => searchPredictionMarkets(query, limit));
+
+    if (result.status === "unavailable") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `Polymarket prediction markets unavailable for "${query}" (${result.reason}).`,
+              "",
+              caveatText(),
+            ].join("\n"),
+          },
+        ],
+        details: [] as PredictionMarketQuote[],
+      };
+    }
+
+    const quotes = result.data;
+    const cacheDisclosure =
+      result.stale && result.timestamp
+        ? [
+            `Using cached Polymarket data from ${new Date(result.timestamp).toISOString()} because the provider fallback returned stale cache.`,
+            "",
+          ]
+        : [];
+    const text =
+      quotes.length === 0
+        ? [
+            ...cacheDisclosure,
+            `No Polymarket prediction markets found for "${query}".`,
+            "",
+            caveatText(),
+          ].join("\n")
+        : [
+            `**Polymarket event probabilities for "${query}"**`,
+            "",
+            ...cacheDisclosure,
+            untrustedContentHeader("Polymarket market text"),
+            "",
+            ...quotes.map(formatQuote),
+            "",
+            caveatText(),
+          ].join("\n");
+
+    return { content: [{ type: "text", text }], details: quotes.map(sanitizeQuoteDetails) };
+  },
+};
+
+function sanitizeQuoteDetails(quote: PredictionMarketQuote): PredictionMarketQuote {
+  return {
+    source: quote.source,
+    marketId: renderUntrustedText(quote.marketId, 120),
+    title: renderUntrustedText(quote.title, 220),
+    outcome: renderUntrustedText(quote.outcome, 80),
+    probability: quote.probability,
+    ...(quote.volumeUsd !== undefined && { volumeUsd: quote.volumeUsd }),
+    ...(quote.liquidityUsd !== undefined && { liquidityUsd: quote.liquidityUsd }),
+    url: renderUntrustedText(quote.url, 500),
+    ...(quote.asOf && { asOf: renderUntrustedText(quote.asOf, 80) }),
+    ...(quote.closeDate && { closeDate: renderUntrustedText(quote.closeDate, 80) }),
+    ...(quote.resolutionCriteria && {
+      resolutionCriteria: renderUntrustedText(quote.resolutionCriteria, 1000),
+    }),
+  };
+}
+
+function formatQuote(quote: PredictionMarketQuote): string {
+  return [
+    `- ${formatPercent(quote.probability)} - ${renderUntrustedText(quote.outcome, 80)}: ${renderUntrustedText(quote.title, 220)}`,
+    `  Volume: ${formatUsd(quote.volumeUsd)} | Liquidity: ${formatUsd(quote.liquidityUsd)} | Close: ${
+      quote.closeDate ? renderUntrustedText(quote.closeDate, 80) : "unknown"
+    }`,
+    `  Updated: ${quote.asOf ? renderUntrustedText(quote.asOf, 80) : "unavailable from Polymarket"}`,
+    quote.volumeUsd !== undefined && quote.volumeUsd < LOW_LIQUIDITY_VOLUME_USD
+      ? "  LOW-LIQUIDITY: volume under $10,000"
+      : undefined,
+    `  Resolution criteria: ${
+      quote.resolutionCriteria
+        ? renderUntrustedText(quote.resolutionCriteria, 1000)
+        : "Resolution criteria unavailable from Polymarket."
+    }`,
+    `  URL: ${renderUntrustedText(quote.url, 500)}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function formatPercent(value: number): string {
+  return `${(value * 100).toFixed(1)}%`;
+}
+
+function formatUsd(value: number | undefined): string {
+  if (value === undefined) return "unavailable";
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    maximumFractionDigits: 2,
+  }).format(value);
+}
+
+function caveatText(): string {
+  return [
+    "Caveats:",
+    "- These are market-implied probabilities from trader positioning, not calibrated forecasts.",
+    "- Thin markets can show noisy or stale prices; results with volume under $10,000 are explicitly flagged low-liquidity.",
+    "- Polymarket is a crypto-settled venue with platform and settlement risks distinct from regulated exchanges.",
+  ].join("\n");
+}