opencandle 0.4.0 → 0.6.0

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

@@ -1,5 +1,5 @@
-import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 import { promptUser } from "../../onboarding/prompt-user.js";
 import type { AskUserHandler } from "../../types/index.js";
 
@@ -14,14 +14,15 @@ 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)" },
+    {
+      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" }),
-  ),
+  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" }),
   ),
@@ -45,7 +46,12 @@ export function registerAskUserTool(pi: ExtensionAPI, askUserHandler?: AskUserHa
       // 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." }],
+          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,
         };
       }
@@ -63,9 +69,10 @@ export function registerAskUserTool(pi: ExtensionAPI, askUserHandler?: AskUserHa
       );
 
       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.";
+        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,
@@ -74,7 +81,12 @@ export function registerAskUserTool(pi: ExtensionAPI, askUserHandler?: AskUserHa
 
       return {
         content: [{ type: "text", text: `User answered: ${result.answer}` }],
-        details: { question, questionType, answer: result.answer, cancelled: false } as AskUserDetails,
+        details: {
+          question,
+          questionType,
+          answer: result.answer,
+          cancelled: false,
+        } as AskUserDetails,
       };
     },
   });

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

@@ -1,7 +1,7 @@
 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";
+import { Type } from "@sinclair/typebox";
+import type { BrowserContext } from "playwright-core";
 
 interface TwitterLoginResult {
   success: boolean;
@@ -47,7 +47,10 @@ export async function runTwitterLogin(notify: (msg: string) => void): Promise<Tw
         if (found.length >= 2) {
           await page.waitForTimeout(3000);
           await context.close();
-          return { success: true, message: `Twitter login successful! (${found.map((c) => c.name).join(", ")})` };
+          return {
+            success: true,
+            message: `Twitter login successful! (${found.map((c) => c.name).join(", ")})`,
+          };
         }
       } catch {
         return { success: false, message: "Twitter login cancelled (browser closed)." };
@@ -58,7 +61,11 @@ export async function runTwitterLogin(notify: (msg: string) => void): Promise<Tw
     await context.close();
     return { success: false, message: "Twitter login timed out after 5 minutes." };
   } catch (error) {
-    try { await context.close(); } catch { /* already closed */ }
+    try {
+      await context.close();
+    } catch {
+      /* already closed */
+    }
     const msg = error instanceof Error ? error.message : String(error);
     return { success: false, message: `Twitter login failed: ${msg}` };
   }
@@ -77,7 +84,12 @@ export function registerTwitterLoginTool(pi: ExtensionAPI): void {
     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." }],
+          content: [
+            {
+              type: "text",
+              text: "Cannot open browser in non-interactive mode. Twitter login requires a terminal session with UI.",
+            },
+          ],
           details: { success: false },
         };
       }

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

@@ -1,5 +1,5 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
 import { getFearGreedIndex } from "../../providers/fear-greed.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
 import type { FearGreedData } from "../../types/sentiment.js";
@@ -12,7 +12,7 @@ export const fearGreedTool: AgentTool<typeof params, FearGreedData> = {
   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) {
+  async execute(_toolCallId, _args) {
     const result = await wrapProvider("feargreed", () => getFearGreedIndex());
     if (result.status === "unavailable") {
       return {

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

@@ -1,54 +1,92 @@
-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 { Type } from "@sinclair/typebox";
 import { getConfig } from "../../config.js";
 import { withCredentialCheck } from "../../onboarding/tool-helpers.js";
-import { FRED_SERIES } from "../../types/macro.js";
+import { getSeries } from "../../providers/fred.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
 import type { FredSeries } from "../../types/macro.js";
+import { FRED_SERIES } 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(", ")}`,
+    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" }),
+    Type.Integer({
+      minimum: 1,
+      maximum: 1000,
+      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 };
-    });
-  },
-};
+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 seriesId = args.series_id.toUpperCase();
+        const limit = normalizeLimit(seriesId, args.limit);
+        const result = await wrapProvider("fred", () => getSeries(seriesId, apiKey, limit));
+        if (result.status === "unavailable") {
+          return {
+            content: [
+              { type: "text", text: `⚠ FRED data unavailable for ${seriesId} (${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";
+        const derived = formatDerivedChange(series);
+
+        // 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, derived, "", "Recent observations:", table]
+          .filter(Boolean)
+          .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 };
+      });
+    },
+  };
+
+function normalizeLimit(seriesId: string, requested: number | undefined): number {
+  const limit = requested ?? 30;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+    throw new Error("limit must be an integer between 1 and 1000.");
+  }
+  if (seriesId === FRED_SERIES.CPI && limit < 13) return 13;
+  return limit;
+}
+
+function formatDerivedChange(series: FredSeries): string | null {
+  const latest = series.observations.at(-1);
+  if (!latest) return null;
+  if (!/monthly/i.test(series.frequency) || !/\bindex\b/i.test(series.units)) return null;
+
+  const latestYear = Number(latest.date.slice(0, 4));
+  const monthDay = latest.date.slice(4);
+  const prior = series.observations.find(
+    (observation) => observation.date === `${latestYear - 1}${monthDay}`,
+  );
+  if (!prior || prior.value === 0) return null;
+
+  const pct = (latest.value / prior.value - 1) * 100;
+  return `Derived YoY change: ${pct.toFixed(2)}% (${prior.date} to ${latest.date}).`;
+}

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

@@ -1,8 +1,9 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
 import { getCryptoHistory } from "../../providers/coingecko.js";
 import { wrapProvider } from "../../providers/wrap-provider.js";
 import type { OHLCV } from "../../types/market.js";
+import { computeRiskMetrics } from "../portfolio/risk-analysis.js";
 
 const params = Type.Object({
   id: Type.String({
@@ -20,13 +21,15 @@ export const cryptoHistoryTool: AgentTool<typeof params, OHLCV[]> = {
   label: "Crypto History",
   description: "Get historical OHLC data for a cryptocurrency",
   parameters: params,
-  async execute(toolCallId, args) {
+  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}).` }],
+        content: [
+          { type: "text", text: `⚠ Crypto history unavailable for ${id} (${result.reason}).` },
+        ],
         details: [],
       };
     }
@@ -45,7 +48,25 @@ export const cryptoHistoryTool: AgentTool<typeof params, OHLCV[]> = {
       )
       .join("\n");
 
-    const text = [...summary, "", "Recent bars:", table].join("\n");
+    const riskLines = buildRiskLines(id, bars);
+    const text = [...summary, ...riskLines, "", "Recent bars:", table].join("\n");
     return { content: [{ type: "text", text }], details: bars };
   },
 };
+
+function buildRiskLines(id: string, bars: OHLCV[]): string[] {
+  if (bars.length < 30) return [];
+  const metrics = computeRiskMetrics(
+    id.toUpperCase(),
+    bars.map((bar) => bar.close),
+  );
+  return [
+    "",
+    "Risk metrics from crypto history:",
+    `Annualized Return: ${(metrics.annualizedReturn * 100).toFixed(2)}%`,
+    `Annualized Volatility: ${(metrics.annualizedVolatility * 100).toFixed(2)}%`,
+    `Sharpe Ratio: ${metrics.sharpeRatio.toFixed(2)}`,
+    `Max Drawdown: ${(metrics.maxDrawdown * 100).toFixed(2)}%`,
+    `Value at Risk (95%, daily): ${(metrics.var95 * 100).toFixed(2)}%`,
+  ];
+}

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

@@ -1,27 +1,27 @@
-import { Type } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "@sinclair/typebox";
 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.",
+    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",
+  description: "Get current crypto price, 24h change, market cap, volume, ATH, and supply data",
   parameters: params,
-  async execute(toolCallId, args) {
+  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}).` }],
+        content: [
+          { type: "text", text: `⚠ Crypto price unavailable for ${args.id} (${result.reason}).` },
+        ],
         details: null as any,
       };
     }

package/src/tools/market/screen-stocks.ts

@@ -0,0 +1,279 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type Static, Type } from "@sinclair/typebox";
+import type { ScreenerRow, ScreenFilterOp } from "../../providers/tradingview.js";
+import { screenStocks } from "../../providers/tradingview.js";
+import { wrapProvider } from "../../providers/wrap-provider.js";
+
+const filterOps = [
+  "greater",
+  "GREATER",
+  "gt",
+  "GT",
+  ">",
+  "egreater",
+  "EGREATER",
+  "gte",
+  "GTE",
+  ">=",
+  "less",
+  "LESS",
+  "lt",
+  "LT",
+  "<",
+  "eless",
+  "ELESS",
+  "lte",
+  "LTE",
+  "<=",
+  "equal",
+  "EQUAL",
+  "eq",
+  "EQ",
+  "==",
+  "nequal",
+  "NEQUAL",
+  "neq",
+  "NEQ",
+  "!=",
+  "in_range",
+  "IN_RANGE",
+  "not_in_range",
+  "NOT_IN_RANGE",
+  "crosses",
+  "CROSSES",
+  "crosses_above",
+  "CROSSES_ABOVE",
+  "crosses_below",
+  "CROSSES_BELOW",
+  "above%",
+  "ABOVE%",
+  "below%",
+  "BELOW%",
+  "match",
+  "MATCH",
+  "nmatch",
+  "NMATCH",
+  "has",
+  "HAS",
+  "has_none_of",
+  "HAS_NONE_OF",
+  "empty",
+  "EMPTY",
+  "nempty",
+  "NEMPTY",
+] as const;
+
+const filterOp = Type.String({ enum: [...filterOps] });
+
+const params = Type.Object({
+  market: Type.Optional(
+    Type.String({ description: "TradingView market path segment. Default: america" }),
+  ),
+  columns: Type.Optional(
+    Type.Array(
+      Type.String({
+        description:
+          "TradingView scanner field, optionally timeframe-qualified (for example RSI|60)",
+      }),
+    ),
+  ),
+  filter: Type.Optional(
+    Type.Array(
+      Type.Object({
+        field: Type.String({
+          description: "TradingView scanner field, optionally timeframe-qualified",
+        }),
+        op: filterOp,
+        value: Type.Optional(
+          Type.Unknown({ description: "Filter value for operations that require one" }),
+        ),
+      }),
+      { description: "Flat AND filter clauses; nested OR trees are not supported" },
+    ),
+  ),
+  sort: Type.Optional(
+    Type.Object({
+      field: Type.String({ description: "TradingView scanner field to sort by" }),
+      direction: Type.Optional(Type.String({ enum: ["asc", "ASC", "desc", "DESC"] })),
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({ description: "Maximum rows to return. Default 50; maximum 500" }),
+  ),
+});
+
+export const screenStocksTool: AgentTool<typeof params, ScreenerRow[]> = {
+  name: "screen_stocks",
+  label: "Stock Screener",
+  description:
+    'Screen stocks across a market using TradingView scanner filters, columns, sorting, and row limits. Use for breadth queries like finding large caps, oversold stocks, movers, or filtered market lists; use quote/history tools for single-security quote or history requests. Common aliases are accepted: gt/gte/lt/lte for comparisons, market_cap for market_cap_basic, change_percent for change, and RSI|14D for RSI. For sector screens, use the sector field; technology usually means sector in_range ["Electronic Technology", "Technology Services"]. Use description for company names because name is the ticker.',
+  parameters: params,
+  async execute(_toolCallId, args) {
+    const normalized = normalizeArgs(args);
+    const result = await wrapProvider("tradingview", () =>
+      screenStocks({
+        market: normalized.market,
+        columns: normalized.columns,
+        filter: normalized.filter,
+        sort: normalized.sort,
+        limit: normalized.limit,
+      }),
+    );
+
+    if (result.status === "unavailable") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `Stock screening unavailable (${result.reason}).`,
+              "Manual fallback: run the same screen in TradingView or another screener with the requested filters and sort. Treat matches as candidates, not recommendations, and verify live quotes/news before acting.",
+            ].join("\n"),
+          },
+        ],
+        details: [],
+      };
+    }
+
+    const rows = result.data;
+    if (rows.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No stocks matched the screen. TradingView scanner data may be delayed about 15 minutes and comes from an unofficial endpoint.",
+          },
+        ],
+        details: rows,
+      };
+    }
+
+    const lines = [
+      `**Stock screen** — ${rows.length} TradingView result${rows.length === 1 ? "" : "s"}`,
+      ...(result.stale ? [`⚠ Using cached TradingView screen from ${result.timestamp}.`] : []),
+      `Data freshness: ${result.stale ? `cached screen retrieved at ${result.timestamp}` : `retrieved at ${result.timestamp}`}; TradingView scanner data may be delayed about 15 minutes and comes from an unofficial endpoint.`,
+      formatInterpretationNote(normalized),
+      "",
+      ...rows.map(formatRow),
+    ];
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: rows,
+    };
+  },
+};
+
+function normalizeArgs(args: Static<typeof params>) {
+  return {
+    ...args,
+    columns: args.columns
+      ?.map(normalizeField)
+      .filter((field, index, fields) => fields.indexOf(field) === index),
+    filter: args.filter?.map((clause) => ({
+      ...clause,
+      field: normalizeField(clause.field),
+      op: normalizeFilterOp(clause.op),
+      ...(clause.value !== undefined && { value: normalizeValue(clause.value) }),
+    })),
+    sort: args.sort && {
+      ...args.sort,
+      field: normalizeField(args.sort.field),
+      direction: normalizeSortDirection(args.sort.direction),
+    },
+  };
+}
+
+function normalizeFilterOp(op: string): ScreenFilterOp {
+  const normalized = op.toLowerCase();
+  if (normalized === "gt" || normalized === ">") return "greater";
+  if (normalized === "gte" || normalized === ">=") return "egreater";
+  if (normalized === "lt" || normalized === "<") return "less";
+  if (normalized === "lte" || normalized === "<=") return "eless";
+  if (normalized === "eq" || normalized === "==") return "equal";
+  if (normalized === "neq" || normalized === "!=") return "nequal";
+  return normalized as ScreenFilterOp;
+}
+
+function normalizeSortDirection(direction?: string): "asc" | "desc" | undefined {
+  const normalized = direction?.toLowerCase();
+  if (normalized === "asc" || normalized === "desc") return normalized;
+  return undefined;
+}
+
+function normalizeField(field: string): string {
+  const trimmed = field.trim();
+  const lower = trimmed.toLowerCase();
+  if (lower === "market_cap" || lower === "marketcap") return "market_cap_basic";
+  if (lower === "total_volume" || lower === "share_volume" || lower === "shares_traded")
+    return "volume";
+  if (
+    lower === "change_percent" ||
+    lower === "percent_change" ||
+    lower === "daily_change_percent" ||
+    lower === "day_change_percent" ||
+    lower === "price_change_percent"
+  )
+    return "change";
+  if (lower === "company_name" || lower === "company" || lower === "security_name")
+    return "description";
+  if (/^rsi(?:\|(?:14|14d|14d\|close|1d|d|daily))?$/i.test(trimmed)) return "RSI";
+  return trimmed;
+}
+
+function formatInterpretationNote(args: ReturnType<typeof normalizeArgs>): string {
+  const fields = [
+    ...(args.columns ?? []),
+    ...(args.filter?.map((clause) => clause.field) ?? []),
+    args.sort?.field,
+  ].filter(Boolean);
+  const hasField = (field: string) => fields.includes(field);
+  const notes = ["Treat screen results as candidates, not recommendations."];
+  if (hasField("RSI"))
+    notes.push("RSI below 30 can mark oversold momentum, but it is not a buy signal by itself.");
+  if (args.sort?.field === "volume")
+    notes.push(
+      "Volume sorting shows the most actively traded matches rather than unusual volume by itself.",
+    );
+  if (hasField("change"))
+    notes.push(
+      "Daily percent change depends on the current market session; confirm market status and live quotes before acting.",
+    );
+  return `Interpretation note: ${notes.join(" ")}`;
+}
+
+function normalizeValue(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim().replace(/,/g, "");
+  if (/^[+-]?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  const short = /^\$?(\d+(?:\.\d+)?)\s*([kmbt])$/i.exec(trimmed);
+  if (short) return Number(short[1]) * multiplierFor(short[2]);
+  const long = /^\$?(\d+(?:\.\d+)?)\s*(thousand|million|billion|trillion)$/i.exec(trimmed);
+  if (long) return Number(long[1]) * multiplierFor(long[2]);
+  return value;
+}
+
+function multiplierFor(unit: string): number {
+  const normalized = unit.toLowerCase();
+  if (normalized === "k" || normalized === "thousand") return 1_000;
+  if (normalized === "m" || normalized === "million") return 1_000_000;
+  if (normalized === "b" || normalized === "billion") return 1_000_000_000;
+  return 1_000_000_000_000;
+}
+
+function formatRow(row: ScreenerRow): string {
+  const entries = Object.entries(row.values)
+    .filter(([field]) => field !== "name")
+    .slice(0, 8)
+    .map(([field, value]) => `${field}: ${formatValue(value)}`);
+  const suffix = entries.length > 0 ? ` — ${entries.join(" | ")}` : "";
+  return `  ${row.symbol} (${row.tvSymbol})${suffix}`;
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "number")
+    return Number.isInteger(value) ? value.toLocaleString() : value.toFixed(2);
+  if (value === null || value === undefined) return "N/A";
+  if (Array.isArray(value)) return value.join(", ");
+  return String(value);
+}