opencandle 0.11.0 → 0.11.1

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 {
@@ -167,6 +168,31 @@ export function computeNetDebt(f: FinancialStatement): number | null {
   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({
   symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
   growth_rate: Type.Optional(
@@ -193,156 +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") {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `⚠ DCF valuation unavailable for ${symbol}. Missing: ${missing.join(", ")}. Both financials and current price are required.`,
-            },
-          ],
-          details: null,
-        };
-      }
+    const symbol = args.symbol.toUpperCase();
+    const config = getConfig();
+    const alphaVantageApiKey = config.alphaVantageApiKey;
 
-      const overview = overviewResult.status === "ok" ? overviewResult.data : null;
-      const financials = financialsResult.data;
-      const quote = quoteResult.data;
+    const [alphaVantageFinancialsResult, quoteResult] = await Promise.all([
+      optionalAlphaVantage(alphaVantageApiKey, (apiKey) => getFinancials(symbol, apiKey)),
+      wrapProvider("yahoo", () => getQuote(symbol)),
+    ]);
 
-      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,
-        };
-      }
+    const missing: string[] = [];
+    if (quoteResult.status === "unavailable") missing.push(`stock quote (${quoteResult.reason})`);
 
-      // 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));
-        }
-      }
+    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 discountRate = args.discount_rate ?? 0.1;
-      const terminalGrowth = args.terminal_growth ?? 0.03;
-      if (discountRate <= terminalGrowth) {
+    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: `⚠ 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.`,
+              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 years = args.projection_years ?? 5;
-      // Prefer the overview market cap; fall back to the quote's market cap.
-      // Never substitute a placeholder share count — a fabricated
-      // per-share value is worse than an honest refusal.
-      const marketCap =
-        overview?.marketCap && overview.marketCap > 0
-          ? overview.marketCap
-          : quote.marketCap > 0
-            ? quote.marketCap
-            : 0;
-      if (quote.price <= 0 || marketCap <= 0) {
+      if (yahooFinancialsResult.stale) {
+        const cachedAt = yahooFinancialsResult.timestamp
+          ? ` from ${yahooFinancialsResult.timestamp}`
+          : "";
         return {
           content: [
             {
               type: "text",
-              text: `⚠ Cannot compute a per-share DCF for ${symbol}: shares outstanding 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.`,
+              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,
         };
       }
-      const sharesOutstanding = marketCap / quote.price;
-      // 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.",
-        );
+      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));
       }
+    }
 
-      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),
-        ...(result.warnings.length > 0
-          ? ["", "**Warnings**", ...result.warnings.map((warning) => `- ${warning}`)]
-          : []),
-      ];
+    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";
@@ -38,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";
@@ -78,6 +80,7 @@ export function getAllTools(options: { askUserHandler?: AskUserHandler } = {}):
     dcfTool,
     compsTool,
     secFilingsTool,
+    eventProbabilitiesTool,
     fredDataTool,
     fearGreedTool,
     createRedditSentimentTool({ askUserHandler: options.askUserHandler }),

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");
+}