opencandle 0.2.0 → 0.4.0

package/src/tools/fundamentals/financials.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getFinancials } from "../../providers/alpha-vantage.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
+import type { FinancialStatement } from "../../types/fundamentals.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT)" }),
+});
+
+export const financialsTool: AgentTool<typeof params, FinancialStatement[] | { credentialRequired: unknown }> = {
+  name: "get_financials",
+  label: "Financial Statements",
+  description:
+    "Get annual income statement data: revenue, gross profit, operating income, net income, and EPS. Requires Alpha Vantage.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    return withCredentialCheck("alpha_vantage", async () => {
+      const apiKey = getConfig().alphaVantageApiKey!;
+      const result = await wrapProvider("alphavantage", () =>
+        getFinancials(args.symbol.toUpperCase(), apiKey),
+      );
+      if (result.status === "unavailable") {
+        return {
+          content: [{ type: "text", text: `⚠ Financial statements unavailable for ${args.symbol.toUpperCase()} (${result.reason}). Analysis will proceed without financials.` }],
+          details: [],
+        };
+      }
+      const statements = result.data;
+      if (statements.length === 0) {
+        return {
+          content: [{ type: "text", text: `No financial data found for ${args.symbol}` }],
+          details: [],
+        };
+      }
+
+      const header = `${args.symbol.toUpperCase()} — Annual Income Statement (${statements.length} years)`;
+      const rows = statements.map((s) =>
+        `${s.fiscalDate} | Rev: $${fmt(s.revenue)} | GP: $${fmt(s.grossProfit)} | OpInc: $${fmt(s.operatingIncome)} | Net: $${fmt(s.netIncome)}`,
+      );
+
+      const text = [header, ...rows].join("\n");
+      return { content: [{ type: "text", text }], details: statements };
+    });
+  },
+};
+
+function fmt(n: number): string {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  return n.toLocaleString();
+}

package/src/tools/fundamentals/sec-filings.ts

@@ -0,0 +1,61 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { searchFilings } from "../../providers/sec-edgar.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+
+const params = Type.Object({
+  symbol: Type.String({ description: "Stock ticker symbol (e.g. AAPL, MSFT, TSLA)" }),
+  form_types: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Filing types to search: 10-K (annual), 10-Q (quarterly), 8-K (material events). Default: all three.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Maximum number of filings to return (default: 10)" }),
+  ),
+});
+
+export const secFilingsTool: AgentTool<typeof params> = {
+  name: "get_sec_filings",
+  label: "SEC Filings",
+  description:
+    "Search SEC EDGAR for company filings (10-K annual reports, 10-Q quarterly reports, 8-K material events). Returns filing dates, types, and direct links to the documents. Free API, no key required.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const symbol = args.symbol.toUpperCase();
+    const formTypes = args.form_types ?? ["10-K", "10-Q", "8-K"];
+    const limit = args.limit ?? 10;
+
+    const result = await wrapProvider("sec-edgar", () => searchFilings(symbol, formTypes, limit));
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ SEC filings unavailable for ${symbol} (${result.reason}).` }],
+        details: null,
+      };
+    }
+    const filings = result.data;
+
+    if (filings.length === 0) {
+      return {
+        content: [{ type: "text", text: `No SEC filings found for ${symbol}. Verify the ticker is a US-listed company.` }],
+        details: null,
+      };
+    }
+
+    const lines = [
+      `**${symbol} SEC Filings** (${filings.length} found)`,
+      ``,
+      ...filings.map((f) =>
+        `  ${f.formType.padEnd(6)} | Filed: ${f.filedDate} | Period: ${f.periodOfReport || "N/A"} | ${f.entityName}`
+      ),
+      ``,
+      `Links:`,
+      ...filings.map((f) => `  ${f.formType} (${f.filedDate}): ${f.url}`),
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { symbol, filings },
+    };
+  },
+};

package/src/tools/index.ts

@@ -0,0 +1,88 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { stockQuoteTool } from "./market/stock-quote.js";
+import { stockHistoryTool } from "./market/stock-history.js";
+import { cryptoPriceTool } from "./market/crypto-price.js";
+import { cryptoHistoryTool } from "./market/crypto-history.js";
+import { searchTickerTool } from "./market/search-ticker.js";
+import { companyOverviewTool } from "./fundamentals/company-overview.js";
+import { financialsTool } from "./fundamentals/financials.js";
+import { earningsTool } from "./fundamentals/earnings.js";
+import { fredDataTool } from "./macro/fred-data.js";
+import { fearGreedTool } from "./macro/fear-greed.js";
+import { redditSentimentTool } from "./sentiment/reddit-sentiment.js";
+import { twitterSentimentTool } from "./sentiment/twitter-sentiment.js";
+import { technicalIndicatorsTool } from "./technical/indicators.js";
+import { portfolioTrackerTool } from "./portfolio/tracker.js";
+import { riskAnalysisTool } from "./portfolio/risk-analysis.js";
+import { watchlistTool } from "./portfolio/watchlist.js";
+import { correlationTool } from "./portfolio/correlation.js";
+import { optionChainTool } from "./options/option-chain.js";
+import { dcfTool } from "./fundamentals/dcf.js";
+import { compsTool } from "./fundamentals/comps.js";
+import { secFilingsTool } from "./fundamentals/sec-filings.js";
+import { backtestTool } from "./technical/backtest.js";
+import { predictionsTool } from "./portfolio/predictions.js";
+import { webSearchTool } from "./sentiment/web-search.js";
+import { webSentimentTool } from "./sentiment/web-sentiment.js";
+import { sentimentTrendTool } from "./sentiment/sentiment-trend.js";
+import { sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
+
+export { stockQuoteTool } from "./market/stock-quote.js";
+export { stockHistoryTool } from "./market/stock-history.js";
+export { cryptoPriceTool } from "./market/crypto-price.js";
+export { cryptoHistoryTool } from "./market/crypto-history.js";
+export { searchTickerTool } from "./market/search-ticker.js";
+export { companyOverviewTool } from "./fundamentals/company-overview.js";
+export { financialsTool } from "./fundamentals/financials.js";
+export { earningsTool } from "./fundamentals/earnings.js";
+export { dcfTool } from "./fundamentals/dcf.js";
+export { compsTool } from "./fundamentals/comps.js";
+export { secFilingsTool } from "./fundamentals/sec-filings.js";
+export { fredDataTool } from "./macro/fred-data.js";
+export { fearGreedTool } from "./macro/fear-greed.js";
+export { redditSentimentTool } from "./sentiment/reddit-sentiment.js";
+export { twitterSentimentTool } from "./sentiment/twitter-sentiment.js";
+export { webSearchTool } from "./sentiment/web-search.js";
+export { webSentimentTool } from "./sentiment/web-sentiment.js";
+export { sentimentTrendTool } from "./sentiment/sentiment-trend.js";
+export { sentimentSummaryTool } from "./sentiment/sentiment-summary.js";
+export { technicalIndicatorsTool } from "./technical/indicators.js";
+export { backtestTool } from "./technical/backtest.js";
+export { portfolioTrackerTool } from "./portfolio/tracker.js";
+export { riskAnalysisTool } from "./portfolio/risk-analysis.js";
+export { watchlistTool } from "./portfolio/watchlist.js";
+export { correlationTool } from "./portfolio/correlation.js";
+export { predictionsTool } from "./portfolio/predictions.js";
+export { optionChainTool } from "./options/option-chain.js";
+
+export function getAllTools(): AgentTool<any>[] {
+  return [
+    searchTickerTool,
+    stockQuoteTool,
+    stockHistoryTool,
+    cryptoPriceTool,
+    cryptoHistoryTool,
+    companyOverviewTool,
+    financialsTool,
+    earningsTool,
+    dcfTool,
+    compsTool,
+    secFilingsTool,
+    fredDataTool,
+    fearGreedTool,
+    redditSentimentTool,
+    twitterSentimentTool,
+    technicalIndicatorsTool,
+    backtestTool,
+    portfolioTrackerTool,
+    riskAnalysisTool,
+    watchlistTool,
+    correlationTool,
+    predictionsTool,
+    optionChainTool,
+    webSearchTool,
+    webSentimentTool,
+    sentimentTrendTool,
+    sentimentSummaryTool,
+  ];
+}

package/src/tools/interaction/ask-user.ts

@@ -0,0 +1,81 @@
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promptUser } from "../../onboarding/prompt-user.js";
+import type { AskUserHandler } from "../../types/index.js";
+
+interface AskUserDetails {
+  question: string;
+  questionType: string;
+  answer: string | null;
+  cancelled: boolean;
+}
+
+const AskUserParams = Type.Object({
+  question: Type.String({ description: "The question to ask the user" }),
+  question_type: Type.Union(
+    [Type.Literal("select"), Type.Literal("text"), Type.Literal("confirm")],
+    { description: "Type of answer expected: select (pick from options), text (free input), or confirm (yes/no)" },
+  ),
+  options: Type.Optional(
+    Type.Array(Type.String(), { description: "Choices for select-type questions" }),
+  ),
+  placeholder: Type.Optional(
+    Type.String({ description: "Hint text for text input" }),
+  ),
+  reason: Type.Optional(
+    Type.String({ description: "Brief context for why this clarification is needed" }),
+  ),
+});
+
+export function registerAskUserTool(pi: ExtensionAPI, askUserHandler?: AskUserHandler): void {
+  pi.registerTool({
+    name: "ask_user",
+    label: "Ask User",
+    description:
+      "Ask the user a clarification question when their request is ambiguous or missing key details. Use select for multiple-choice, text for free input, or confirm for yes/no.",
+    promptSnippet:
+      "ask_user: Ask the user a clarification question when their request is ambiguous or missing key details",
+    parameters: AskUserParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { question, question_type: questionType } = params;
+
+      // Preserve the pre-refactor error message for the specific misuse case
+      // where the model asks a select question with no options — this is a
+      // model/caller bug, not a cancellation.
+      if (questionType === "select" && (!params.options || params.options.length === 0)) {
+        return {
+          content: [{ type: "text", text: "Error: No options provided for select question. Provide options or use text type instead." }],
+          details: { question, questionType, answer: null, cancelled: true } as AskUserDetails,
+        };
+      }
+
+      const result = await promptUser(
+        ctx!,
+        {
+          question,
+          questionType,
+          options: params.options,
+          placeholder: params.placeholder,
+          reason: params.reason,
+        },
+        askUserHandler,
+      );
+
+      if (result.cancelled) {
+        const text = !askUserHandler && !ctx?.hasUI
+          ? "UI not available (non-interactive mode). Proceed with your best judgment and clearly disclose your assumption."
+          : "User cancelled the selection. Proceed with your best judgment and disclose your assumption.";
+        return {
+          content: [{ type: "text", text }],
+          details: { question, questionType, answer: null, cancelled: true } as AskUserDetails,
+        };
+      }
+
+      return {
+        content: [{ type: "text", text: `User answered: ${result.answer}` }],
+        details: { question, questionType, answer: result.answer, cancelled: false } as AskUserDetails,
+      };
+    },
+  });
+}

package/src/tools/interaction/twitter-login.ts

@@ -0,0 +1,93 @@
+import { mkdirSync } from "node:fs";
+import type { BrowserContext } from "playwright-core";
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+interface TwitterLoginResult {
+  success: boolean;
+  message: string;
+}
+
+export async function runTwitterLogin(notify: (msg: string) => void): Promise<TwitterLoginResult> {
+  const { getBrowserProfileDir } = await import("../../infra/opencandle-paths.js");
+  const { Camoufox } = await import("camoufox-js");
+
+  const profileDir = getBrowserProfileDir();
+  mkdirSync(profileDir, { recursive: true });
+
+  notify("Launching browser for Twitter login...");
+
+  const context = (await Camoufox({
+    headless: false,
+    user_data_dir: profileDir,
+    geoip: true,
+    humanize: true,
+    os: "macos",
+    block_webrtc: true,
+    window: [1440, 900],
+  })) as unknown as BrowserContext;
+
+  try {
+    const pages = context.pages();
+    const page = pages.length > 0 ? pages[0] : await context.newPage();
+
+    await page.goto("https://x.com/login", {
+      waitUntil: "domcontentloaded",
+      timeout: 30_000,
+    });
+
+    notify("Log in via the browser window. Waiting for auth cookies...");
+
+    const deadline = Date.now() + 300_000;
+    while (Date.now() < deadline) {
+      try {
+        const cookies = await context.cookies("https://x.com");
+        const authNames = ["auth_token", "ct0", "twid"];
+        const found = cookies.filter((c) => authNames.includes(c.name));
+        if (found.length >= 2) {
+          await page.waitForTimeout(3000);
+          await context.close();
+          return { success: true, message: `Twitter login successful! (${found.map((c) => c.name).join(", ")})` };
+        }
+      } catch {
+        return { success: false, message: "Twitter login cancelled (browser closed)." };
+      }
+      await page.waitForTimeout(2000);
+    }
+
+    await context.close();
+    return { success: false, message: "Twitter login timed out after 5 minutes." };
+  } catch (error) {
+    try { await context.close(); } catch { /* already closed */ }
+    const msg = error instanceof Error ? error.message : String(error);
+    return { success: false, message: `Twitter login failed: ${msg}` };
+  }
+}
+
+export function registerTwitterLoginTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "trigger_twitter_login",
+    label: "Twitter Login",
+    description:
+      "Open a browser window for the user to log in to Twitter/X. Call this when get_twitter_sentiment reports that login is needed and the user has confirmed they want to proceed. Returns success/failure. After success, retry get_twitter_sentiment.",
+    promptSnippet:
+      "trigger_twitter_login: Opens a browser for Twitter/X login. Use when Twitter sentiment is unavailable due to missing session.",
+    parameters: Type.Object({}),
+
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      if (!ctx?.hasUI) {
+        return {
+          content: [{ type: "text", text: "Cannot open browser in non-interactive mode. Twitter login requires a terminal session with UI." }],
+          details: { success: false },
+        };
+      }
+
+      const result = await runTwitterLogin((msg) => ctx.ui.notify(msg, "info"));
+
+      return {
+        content: [{ type: "text", text: result.message }],
+        details: { success: result.success },
+      };
+    },
+  });
+}

package/src/tools/macro/fear-greed.ts

@@ -0,0 +1,41 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getFearGreedIndex } from "../../providers/fear-greed.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { FearGreedData } from "../../types/sentiment.js";
+
+const params = Type.Object({});
+
+export const fearGreedTool: AgentTool<typeof params, FearGreedData> = {
+  name: "get_fear_greed",
+  label: "Fear & Greed Index",
+  description:
+    "Get the Crypto Fear & Greed Index (alternative.me) — a sentiment indicator from 0 (Extreme Fear) to 100 (Extreme Greed). Includes current value and previous close.",
+  parameters: params,
+  async execute(toolCallId, _args) {
+    const result = await wrapProvider("feargreed", () => getFearGreedIndex());
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Fear & Greed Index unavailable (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+    const fg = result.data;
+
+    const gauge = buildGauge(fg.value);
+    const text = [
+      `**Fear & Greed Index: ${fg.value} — ${fg.label}**`,
+      gauge,
+      `Previous Close: ${fg.previousClose}${fg.weekAgo != null ? ` | Week Ago: ${fg.weekAgo}` : ""}${fg.monthAgo != null ? ` | Month Ago: ${fg.monthAgo}` : ""}`,
+    ].join("\n");
+
+    return { content: [{ type: "text", text }], details: fg };
+  },
+};
+
+function buildGauge(value: number): string {
+  const width = 20;
+  const pos = Math.round((value / 100) * width);
+  const bar = "█".repeat(pos) + "░".repeat(width - pos);
+  return `[${bar}] ${value}/100`;
+}

package/src/tools/macro/fred-data.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getSeries } from "../../providers/fred.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import { getConfig } from "../../config.js";
+import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
+import { FRED_SERIES } from "../../types/macro.js";
+import type { FredSeries } from "../../types/macro.js";
+
+const params = Type.Object({
+  series_id: Type.String({
+    description: `FRED series ID. Common ones: ${Object.entries(FRED_SERIES).map(([k, v]) => `${v} (${k})`).join(", ")}`,
+  }),
+  limit: Type.Optional(
+    Type.Number({ description: "Number of observations to return. Default: 30" }),
+  ),
+});
+
+export const fredDataTool: AgentTool<typeof params, FredSeries | { credentialRequired: unknown }> = {
+  name: "get_economic_data",
+  label: "FRED Economic Data",
+  description:
+    "Get economic data from FRED (Federal Reserve Economic Data): interest rates, CPI, GDP, unemployment, yield curve, and more. Requires FRED.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    return withCredentialCheck("fred", async () => {
+      const apiKey = getConfig().fredApiKey!;
+      const limit = args.limit ?? 30;
+      const result = await wrapProvider("fred", () => getSeries(args.series_id.toUpperCase(), apiKey, limit));
+      if (result.status === "unavailable") {
+        return {
+          content: [{ type: "text", text: `⚠ FRED data unavailable for ${args.series_id.toUpperCase()} (${result.reason}).` }],
+          details: null as any,
+        };
+      }
+      const series = result.data;
+
+      const latest = series.observations[series.observations.length - 1];
+      const header = `**${series.title}** (${series.id})`;
+      const meta = `Units: ${series.units} | Frequency: ${series.frequency} | Last updated: ${series.lastUpdated}`;
+      const current = latest ? `Latest: ${latest.value} (${latest.date})` : "No data";
+
+      // Show last 10 observations
+      const recent = series.observations.slice(-10);
+      const table = recent.map((o) => `${o.date}: ${o.value}`).join("\n");
+
+      const text = [header, meta, current, "", "Recent observations:", table].join("\n");
+      const prefix = result.stale
+        ? `⚠ Using cached FRED data from ${result.timestamp} (FRED unavailable)\n`
+        : "";
+      return { content: [{ type: "text", text: prefix + text }], details: series };
+    });
+  },
+};

package/src/tools/market/crypto-history.ts

@@ -0,0 +1,51 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getCryptoHistory } from "../../providers/coingecko.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { OHLCV } from "../../types/market.js";
+
+const params = Type.Object({
+  id: Type.String({
+    description: "CoinGecko coin ID (e.g. bitcoin, ethereum, solana)",
+  }),
+  days: Type.Optional(
+    Type.Number({
+      description: "Number of days of history: 1, 7, 14, 30, 90, 180, 365, max. Default: 180",
+    }),
+  ),
+});
+
+export const cryptoHistoryTool: AgentTool<typeof params, OHLCV[]> = {
+  name: "get_crypto_history",
+  label: "Crypto History",
+  description: "Get historical OHLC data for a cryptocurrency",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const id = args.id.toLowerCase();
+    const days = args.days ?? 180;
+    const result = await wrapProvider("coingecko", () => getCryptoHistory(id, days));
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Crypto history unavailable for ${id} (${result.reason}).` }],
+        details: [],
+      };
+    }
+    const bars = result.data;
+
+    const summary = [
+      `${id} — ${bars.length} bars (${days} days)`,
+      `Period: ${bars[0]?.date} to ${bars[bars.length - 1]?.date}`,
+    ];
+
+    const recent = bars.slice(-10);
+    const table = recent
+      .map(
+        (b) =>
+          `${b.date} | O:${b.open.toFixed(2)} H:${b.high.toFixed(2)} L:${b.low.toFixed(2)} C:${b.close.toFixed(2)}`,
+      )
+      .join("\n");
+
+    const text = [...summary, "", "Recent bars:", table].join("\n");
+    return { content: [{ type: "text", text }], details: bars };
+  },
+};

package/src/tools/market/crypto-price.ts

@@ -0,0 +1,53 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { getCryptoPrice } from "../../providers/coingecko.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+import type { CryptoPrice } from "../../types/market.js";
+
+const params = Type.Object({
+  id: Type.String({
+    description:
+      "CoinGecko coin ID (e.g. bitcoin, ethereum, solana, dogecoin). Use lowercase.",
+  }),
+});
+
+export const cryptoPriceTool: AgentTool<typeof params, CryptoPrice> = {
+  name: "get_crypto_price",
+  label: "Crypto Price",
+  description:
+    "Get current crypto price, 24h change, market cap, volume, ATH, and supply data",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const result = await wrapProvider("coingecko", () => getCryptoPrice(args.id.toLowerCase()));
+    if (result.status === "unavailable") {
+      return {
+        content: [{ type: "text", text: `⚠ Crypto price unavailable for ${args.id} (${result.reason}).` }],
+        details: null as any,
+      };
+    }
+    const crypto = result.data;
+    const sign = crypto.changePercent24h >= 0 ? "+" : "";
+    const text = [
+      `${crypto.name} (${crypto.symbol.toUpperCase()}): $${formatPrice(crypto.price)} (${sign}${crypto.changePercent24h.toFixed(2)}%)`,
+      `24h High: $${formatPrice(crypto.high24h)} | 24h Low: $${formatPrice(crypto.low24h)}`,
+      `Market Cap: $${formatLargeNumber(crypto.marketCap)} | 24h Volume: $${formatLargeNumber(crypto.volume24h)}`,
+      `ATH: $${formatPrice(crypto.ath)} (${crypto.athDate.split("T")[0]})`,
+      `Circulating: ${formatLargeNumber(crypto.circulatingSupply)} ${crypto.symbol.toUpperCase()}`,
+    ].join("\n");
+
+    return { content: [{ type: "text", text }], details: crypto };
+  },
+};
+
+function formatPrice(n: number): string {
+  if (n >= 1) return n.toFixed(2);
+  if (n >= 0.01) return n.toFixed(4);
+  return n.toFixed(8);
+}
+
+function formatLargeNumber(n: number): string {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  return n.toLocaleString();
+}

package/src/tools/market/search-ticker.ts

@@ -0,0 +1,53 @@
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { httpGet } from "../../infra/http-client.js";
+
+const params = Type.Object({
+  query: Type.String({
+    description: "Search query — company name, ticker symbol, or crypto name (e.g. 'apple', 'AAPL', 'ethereum', 'bitcoin')",
+  }),
+});
+
+interface YahooSearchResponse {
+  quotes: Array<{
+    symbol: string;
+    shortname?: string;
+    longname?: string;
+    quoteType: string;
+    exchange: string;
+    score: number;
+  }>;
+}
+
+export const searchTickerTool: AgentTool<typeof params> = {
+  name: "search_ticker",
+  label: "Search Ticker",
+  description:
+    "Search for any ticker symbol — stocks, crypto, ETFs, indices, forex. Returns matching symbols with names and exchange info. Use this when you don't know the exact ticker for an asset.",
+  parameters: params,
+  async execute(toolCallId, args) {
+    const url = `https://query1.finance.yahoo.com/v1/finance/search?q=${encodeURIComponent(args.query)}&quotesCount=10&newsCount=0`;
+    const data = await httpGet<YahooSearchResponse>(url, {
+      headers: { "User-Agent": "OpenCandle/1.0" },
+    });
+
+    const quotes = data.quotes ?? [];
+    if (quotes.length === 0) {
+      return {
+        content: [{ type: "text", text: `No results found for "${args.query}"` }],
+        details: quotes,
+      };
+    }
+
+    const lines = [
+      `**Search results for "${args.query}"** — ${quotes.length} matches`,
+      "",
+      ...quotes.map(
+        (q) =>
+          `  ${q.symbol} — ${q.longname || q.shortname || "N/A"} (${q.quoteType}, ${q.exchange})`,
+      ),
+    ];
+
+    return { content: [{ type: "text", text: lines.join("\n") }], details: quotes };
+  },
+};