opencandle 0.5.0 → 0.7.0

package/src/sentiment/adapters/web.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
-import type { SentinelRecord, SentimentAdapter } from "../types.js";
 import type { WebSearchEnvelope } from "../../types/sentiment.js";
+import type { SentimentAdapter, SentinelRecord } from "../types.js";
 
 export class WebAdapter implements SentimentAdapter {
   readonly source = "web" as const;

package/src/sentiment/index.ts

@@ -1,30 +1,30 @@
+export { RedditAdapter } from "./adapters/reddit.js";
+export { TwitterAdapter } from "./adapters/twitter.js";
+export { WebAdapter } from "./adapters/web.js";
+export { buildSentimentInsight, labelForScore } from "./insights.js";
+export { BEARISH_TERMS, BULLISH_TERMS } from "./keywords.js";
+export { SentimentPipeline } from "./pipeline.js";
+export { keywordScore, scoreRecords } from "./scorer.js";
+export { SentimentStore } from "./store.js";
+export { computeDivergence, computeTrend, renderSparkline } from "./trends.js";
 export type {
-  SentinelRecord,
+  DivergenceResult,
+  ScorerOptions,
+  SentimentAdapter,
+  SentimentSource,
+  SentimentSummary,
   SentinelEngagement,
+  SentinelRecord,
   SentinelSentiment,
-  SentimentAdapter,
-  ScorerOptions,
   TrendBucket,
   TrendResult,
-  DivergenceResult,
-  SentimentSummary,
-  SentimentSource,
 } from "./types.js";
-
 export { isSentinelRecord, SENTIMENT_SOURCES } from "./types.js";
-export { SentimentStore } from "./store.js";
-export { scoreRecords, keywordScore } from "./scorer.js";
-export { SentimentPipeline } from "./pipeline.js";
-export { renderSparkline, computeTrend, computeDivergence } from "./trends.js";
-export { BULLISH_TERMS, BEARISH_TERMS } from "./keywords.js";
-export { TwitterAdapter } from "./adapters/twitter.js";
-export { RedditAdapter } from "./adapters/reddit.js";
-export { WebAdapter } from "./adapters/web.js";
 
-import { SentimentStore } from "./store.js";
-import { SentimentPipeline } from "./pipeline.js";
 import { getConfig } from "../config.js";
 import { resolveOpenCandlePath } from "../infra/opencandle-paths.js";
+import { SentimentPipeline } from "./pipeline.js";
+import { SentimentStore } from "./store.js";
 
 let _pipeline: SentimentPipeline | null = null;
 let _store: SentimentStore | null = null;
@@ -47,12 +47,3 @@ export function getSentimentPipeline(): SentimentPipeline {
   }
   return _pipeline;
 }
-
-/** For testing: reset singletons */
-export function _resetSentimentSingletons(): void {
-  if (_store) {
-    try { _store.close(); } catch { /* ignore */ }
-  }
-  _pipeline = null;
-  _store = null;
-}

package/src/sentiment/insights.ts

@@ -0,0 +1,269 @@
+import type { SentimentConfig } from "../config.js";
+import type {
+  SentimentInsight,
+  SentimentInsightConfidence,
+  SentimentInsightDriver,
+  SentimentRepresentativeItem,
+} from "../types/sentiment.js";
+import type { SentimentSource, SentinelRecord } from "./types.js";
+
+const DEFAULT_MIN_SAMPLE = 10;
+const DEFAULT_DRIVER_CAP = 3;
+const DEFAULT_SOURCE_ITEM_CAP = 5;
+const DEFAULT_AGGREGATE_ITEM_CAP = 8;
+const DEFAULT_CLAIM_CAP = 5;
+
+export interface BuildSentimentInsightOptions {
+  query: string;
+  records: SentinelRecord[];
+  score?: number;
+  label?: string;
+  source?: SentimentSource | "aggregate";
+  missingSources?: string[];
+  sourceNotes?: string[];
+  config?: Partial<SentimentConfig>;
+  aggregate?: boolean;
+  extraCaveats?: string[];
+}
+
+interface TermBucket {
+  term: string;
+  count: number;
+  sourceIds: Set<string>;
+}
+
+export function buildSentimentInsight(options: BuildSentimentInsightOptions): SentimentInsight {
+  const records = options.records;
+  const scored = records.filter((record) => Math.abs(record.sentiment.score) > 0);
+  const score =
+    typeof options.score === "number"
+      ? options.score
+      : records.length > 0
+        ? records.reduce((sum, record) => sum + record.sentiment.score, 0) / records.length
+        : 0;
+  const sourceCounts = countBySource(records);
+  const positiveDrivers = driversFromTerms(records, "positive", options.config);
+  const negativeDrivers = driversFromTerms(records, "negative", options.config);
+  const caveats = buildCaveats(records, scored, sourceCounts, options);
+  const confidence = buildConfidence(records, scored, sourceCounts, caveats, options.config);
+  const representativeItems = representativeItemsFor(records, options);
+
+  return {
+    label: options.label ?? labelForScore(score),
+    score,
+    sampleSize: records.length,
+    scoredSampleSize: scored.length,
+    confidence,
+    positiveDrivers,
+    negativeDrivers,
+    mixedDrivers: buildMixedDrivers(positiveDrivers, negativeDrivers, score),
+    notableClaims: notableClaimsFor(records, options),
+    representativeItems,
+    sourceCoverage: {
+      sources: Object.keys(sourceCounts),
+      counts: sourceCounts,
+      missingSources: options.missingSources?.filter(Boolean),
+      notes: options.sourceNotes?.filter(Boolean),
+    },
+    caveats,
+    method: "deterministic-keyword-v1",
+  };
+}
+
+export function labelForScore(score: number): string {
+  if (score > 0.3) return "Bullish";
+  if (score < -0.3) return "Bearish";
+  if (score > 0) return "Leaning Bullish";
+  if (score < 0) return "Leaning Bearish";
+  return "Neutral";
+}
+
+function driversFromTerms(
+  records: SentinelRecord[],
+  polarity: "positive" | "negative",
+  config: Partial<SentimentConfig> | undefined,
+): SentimentInsightDriver[] {
+  const buckets = new Map<string, TermBucket>();
+  const metadataKey = polarity === "positive" ? "matchedBullishTerms" : "matchedBearishTerms";
+
+  for (const record of records) {
+    const terms = stringArray(record.metadata[metadataKey]);
+    for (const term of terms) {
+      const existing = buckets.get(term) ?? { term, count: 0, sourceIds: new Set<string>() };
+      existing.count += 1;
+      existing.sourceIds.add(record.sourceId);
+      buckets.set(term, existing);
+    }
+  }
+
+  return [...buckets.values()]
+    .sort((a, b) => b.count - a.count || a.term.localeCompare(b.term))
+    .slice(0, config?.maxInsightDriversPerPolarity ?? DEFAULT_DRIVER_CAP)
+    .map((bucket) => ({
+      label: bucket.term,
+      count: bucket.count,
+      polarity,
+      terms: [bucket.term],
+      sourceIds: [...bucket.sourceIds],
+    }));
+}
+
+function buildMixedDrivers(
+  positiveDrivers: SentimentInsightDriver[],
+  negativeDrivers: SentimentInsightDriver[],
+  score: number,
+): SentimentInsightDriver[] {
+  if (positiveDrivers.length === 0 || negativeDrivers.length === 0) return [];
+  if (Math.abs(score) > 0.3) return [];
+  return [
+    {
+      label: "offsetting bullish and bearish evidence",
+      count: Math.min(sumDriverCounts(positiveDrivers), sumDriverCounts(negativeDrivers)),
+      polarity: "mixed",
+      terms: [
+        ...positiveDrivers.flatMap((d) => d.terms),
+        ...negativeDrivers.flatMap((d) => d.terms),
+      ],
+      sourceIds: [
+        ...new Set([
+          ...positiveDrivers.flatMap((d) => d.sourceIds),
+          ...negativeDrivers.flatMap((d) => d.sourceIds),
+        ]),
+      ],
+    },
+  ];
+}
+
+function representativeItemsFor(
+  records: SentinelRecord[],
+  options: BuildSentimentInsightOptions,
+): SentimentRepresentativeItem[] {
+  const cap = options.aggregate
+    ? (options.config?.maxAggregateRepresentativeItems ?? DEFAULT_AGGREGATE_ITEM_CAP)
+    : (options.config?.maxRepresentativeItemsPerSource ?? DEFAULT_SOURCE_ITEM_CAP);
+
+  return [...records]
+    .sort((a, b) => itemRank(b) - itemRank(a))
+    .slice(0, cap)
+    .map((record) => ({
+      source: record.source,
+      sourceId: record.sourceId,
+      title: record.title,
+      excerpt: excerptFor(record),
+      url: record.url || null,
+      author: record.author,
+      publishedAt: record.publishedAt,
+      engagement: Number.isFinite(record.engagement.score) ? record.engagement.score : null,
+      score: record.sentiment.score,
+      matchedTerms: [
+        ...stringArray(record.metadata.matchedBullishTerms),
+        ...stringArray(record.metadata.matchedBearishTerms),
+      ],
+      metadata: record.metadata,
+    }));
+}
+
+function notableClaimsFor(
+  records: SentinelRecord[],
+  options: BuildSentimentInsightOptions,
+): string[] {
+  const cap = options.config?.maxNotableClaims ?? DEFAULT_CLAIM_CAP;
+  const claims = new Set<string>();
+  for (const record of representativeItemsFor(records, { ...options, aggregate: false })) {
+    const claim = record.title ?? record.excerpt;
+    if (claim) claims.add(claim);
+    if (claims.size >= cap) break;
+  }
+  return [...claims];
+}
+
+function buildConfidence(
+  records: SentinelRecord[],
+  scored: SentinelRecord[],
+  sourceCounts: Record<string, number>,
+  caveats: string[],
+  config: Partial<SentimentConfig> | undefined,
+): SentimentInsightConfidence {
+  const minSample = config?.minUsefulSampleSize ?? DEFAULT_MIN_SAMPLE;
+  const sampleRatio = Math.min(records.length / minSample, 1);
+  const scoredRatio = records.length === 0 ? 0 : scored.length / records.length;
+  const coverageRatio = Math.min(Object.keys(sourceCounts).length / 3, 1);
+  let score = sampleRatio * 0.4 + scoredRatio * 0.4 + coverageRatio * 0.2;
+  const reasons: string[] = [];
+
+  if (records.length < minSample) {
+    reasons.push(`low sample size (${records.length}/${minSample})`);
+  }
+  if (scoredRatio < 0.5) {
+    reasons.push("most records were neutral or had no keyword sentiment match");
+  }
+  if (Object.keys(sourceCounts).length <= 1) {
+    reasons.push("single-source sentiment coverage");
+  }
+  if (caveats.length > 0) {
+    score -= Math.min(0.2, caveats.length * 0.05);
+  }
+
+  score = clamp01(score);
+  return {
+    level: score >= 0.7 ? "high" : score >= 0.4 ? "medium" : "low",
+    score,
+    reasons,
+  };
+}
+
+function buildCaveats(
+  records: SentinelRecord[],
+  scored: SentinelRecord[],
+  sourceCounts: Record<string, number>,
+  options: BuildSentimentInsightOptions,
+): string[] {
+  const minSample = options.config?.minUsefulSampleSize ?? DEFAULT_MIN_SAMPLE;
+  const caveats = [...(options.extraCaveats ?? [])];
+  if (records.length < minSample) caveats.push(`Low sample size: ${records.length} records.`);
+  if (records.length > 0 && scored.length === 0)
+    caveats.push("No records contained keyword sentiment matches.");
+  if (records.length > 0 && scored.length / records.length < 0.5) {
+    caveats.push("Most records were neutral or unscored by keyword matching.");
+  }
+  if (Object.keys(sourceCounts).length <= 1) caveats.push("Single-source sentiment coverage.");
+  if (options.missingSources && options.missingSources.length > 0) {
+    caveats.push(`Missing sources: ${options.missingSources.join(", ")}.`);
+  }
+  return [...new Set(caveats)];
+}
+
+function countBySource(records: SentinelRecord[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const record of records) {
+    counts[record.source] = (counts[record.source] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function sumDriverCounts(drivers: SentimentInsightDriver[]): number {
+  return drivers.reduce((sum, driver) => sum + driver.count, 0);
+}
+
+function itemRank(record: SentinelRecord): number {
+  const sentimentWeight = Math.abs(record.sentiment.score) * 100;
+  const confidenceWeight = record.sentiment.confidence * 20;
+  const engagementWeight = Math.log10(Math.max(0, record.engagement.score) + 1);
+  return sentimentWeight + confidenceWeight + engagementWeight;
+}
+
+function excerptFor(record: SentinelRecord): string {
+  const raw = record.title ? `${record.title} ${record.text}` : record.text;
+  const normalized = raw.replace(/\s+/g, " ").trim();
+  return normalized.length > 220 ? `${normalized.slice(0, 219)}…` : normalized;
+}
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}

package/src/sentiment/keywords.ts

@@ -1,9 +1,31 @@
 export const BULLISH_TERMS = [
-  "moon", "buy", "undervalued", "breakout", "calls", "bullish",
-  "rocket", "diamond hands", "accumulate", "dip buy", "long", "rip", "squeeze",
+  "moon",
+  "buy",
+  "undervalued",
+  "breakout",
+  "calls",
+  "bullish",
+  "rocket",
+  "diamond hands",
+  "accumulate",
+  "dip buy",
+  "long",
+  "rip",
+  "squeeze",
 ] as const;
 
 export const BEARISH_TERMS = [
-  "crash", "overvalued", "sell", "puts", "bearish", "bubble",
-  "dump", "short", "bagholding", "exit", "drill", "tank", "rug",
+  "crash",
+  "overvalued",
+  "sell",
+  "puts",
+  "bearish",
+  "bubble",
+  "dump",
+  "short",
+  "bagholding",
+  "exit",
+  "drill",
+  "tank",
+  "rug",
 ] as const;

package/src/sentiment/pipeline.ts

@@ -1,8 +1,15 @@
-import type { SentinelRecord, SentimentSummary, TrendResult, DivergenceResult, SentimentSource } from "./types.js";
 import type { SentimentConfig } from "../config.js";
+import { buildSentimentInsight } from "./insights.js";
 import { scoreRecords } from "./scorer.js";
-import { SentimentStore } from "./store.js";
-import { computeTrend, computeDivergence, type SourceStats } from "./trends.js";
+import type { SentimentStore } from "./store.js";
+import { computeDivergence, computeTrend, type SourceStats } from "./trends.js";
+import type {
+  DivergenceResult,
+  SentimentSource,
+  SentimentSummary,
+  SentinelRecord,
+  TrendResult,
+} from "./types.js";
 
 export class SentimentPipeline {
   constructor(
@@ -39,7 +46,12 @@ export class SentimentPipeline {
     // Compute divergence from fresh records
     let divergence: DivergenceResult | null = null;
     const sourceGroups = groupBySource(scored);
-    const sourceStats: { twitter?: SourceStats; reddit?: SourceStats; web?: SourceStats; finnhub?: SourceStats } = {};
+    const sourceStats: {
+      twitter?: SourceStats;
+      reddit?: SourceStats;
+      web?: SourceStats;
+      finnhub?: SourceStats;
+    } = {};
 
     for (const [source, recs] of Object.entries(sourceGroups)) {
       // Exclude comments from divergence calculation
@@ -54,7 +66,18 @@ export class SentimentPipeline {
       divergence = computeDivergence(sourceStats, this.config.divergenceThreshold);
     }
 
-    return { fresh: scored, trend, divergence, warnings };
+    return {
+      fresh: scored,
+      trend,
+      divergence,
+      warnings,
+      insight: buildSentimentInsight({
+        query,
+        records: scored,
+        config: this.config,
+        aggregate: true,
+      }),
+    };
   }
 }
 

package/src/sentiment/scorer.ts

@@ -1,4 +1,4 @@
-import { BULLISH_TERMS, BEARISH_TERMS } from "./keywords.js";
+import { BEARISH_TERMS, BULLISH_TERMS } from "./keywords.js";
 import type { SentinelRecord } from "./types.js";
 
 const TICKER_REGEX = /\$([A-Z]{1,5})\b/g;
@@ -7,6 +7,8 @@ interface ScoreResult {
   score: number;
   confidence: number;
   tickers: string[];
+  bullishTerms: string[];
+  bearishTerms: string[];
 }
 
 export function keywordScore(record: SentinelRecord): ScoreResult {
@@ -17,11 +19,14 @@ export function keywordScore(record: SentinelRecord): ScoreResult {
   let bearishWeight = 0;
   let bullishCount = 0;
   let bearishCount = 0;
+  const bullishTerms: string[] = [];
+  const bearishTerms: string[] = [];
 
   for (const term of BULLISH_TERMS) {
     if (lower.includes(term)) {
       bullishCount++;
       bullishWeight += engagement;
+      bullishTerms.push(term);
     }
   }
 
@@ -29,6 +34,7 @@ export function keywordScore(record: SentinelRecord): ScoreResult {
     if (lower.includes(term)) {
       bearishCount++;
       bearishWeight += engagement;
+      bearishTerms.push(term);
     }
   }
 
@@ -59,7 +65,7 @@ export function keywordScore(record: SentinelRecord): ScoreResult {
     }
   }
 
-  return { score, confidence, tickers };
+  return { score, confidence, tickers, bullishTerms, bearishTerms };
 }
 
 export function scoreRecords(records: SentinelRecord[]): SentinelRecord[] {
@@ -73,6 +79,11 @@ export function scoreRecords(records: SentinelRecord[]): SentinelRecord[] {
         method: "keyword" as const,
         tickers: result.tickers,
       },
+      metadata: {
+        ...record.metadata,
+        matchedBullishTerms: result.bullishTerms,
+        matchedBearishTerms: result.bearishTerms,
+      },
     };
   });
 }

package/src/sentiment/store.ts

@@ -1,7 +1,7 @@
-import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import type { SentinelRecord, SentimentSource, TrendBucket } from "./types.js";
+import Database from "better-sqlite3";
+import type { SentimentSource, SentinelRecord, TrendBucket } from "./types.js";
 
 const SCHEMA_VERSION = 1;
 

package/src/sentiment/trends.ts

@@ -1,4 +1,4 @@
-import type { TrendBucket, TrendResult, DivergenceResult, SentimentSource } from "./types.js";
+import type { DivergenceResult, SentimentSource, TrendBucket, TrendResult } from "./types.js";
 
 const SPARKLINE_CHARS = "▁▂▃▄▅▆▇█";
 
@@ -24,7 +24,8 @@ export function computeTrend(
 ): TrendResult {
   const scores = buckets.map((b) => b.avgScore);
   const totalCount = buckets.reduce((sum, b) => sum + b.count, 0);
-  const avgScore = totalCount === 0 ? 0 : buckets.reduce((sum, b) => sum + b.avgScore * b.count, 0) / totalCount;
+  const avgScore =
+    totalCount === 0 ? 0 : buckets.reduce((sum, b) => sum + b.avgScore * b.count, 0) / totalCount;
 
   const sparkline = renderSparkline(scores);
 
@@ -45,7 +46,12 @@ export interface SourceStats {
 }
 
 export function computeDivergence(
-  sources: { twitter?: SourceStats; reddit?: SourceStats; web?: SourceStats; finnhub?: SourceStats },
+  sources: {
+    twitter?: SourceStats;
+    reddit?: SourceStats;
+    web?: SourceStats;
+    finnhub?: SourceStats;
+  },
   threshold: number,
 ): DivergenceResult {
   const retailSources: SourceStats[] = [];

package/src/sentiment/types.ts

@@ -1,3 +1,5 @@
+import type { SentimentInsight } from "../types/sentiment.js";
+
 export const SENTIMENT_SOURCES = ["twitter", "reddit", "web", "finnhub"] as const;
 export type SentimentSource = (typeof SENTIMENT_SOURCES)[number];
 
@@ -9,9 +11,9 @@ export interface SentinelEngagement {
 }
 
 export interface SentinelSentiment {
-  score: number;       // -1.0 to +1.0
-  confidence: number;  // 0.0 to 1.0
-  method: "keyword";   // v1 is keyword-only; future: "llm"
+  score: number; // -1.0 to +1.0
+  confidence: number; // 0.0 to 1.0
+  method: "keyword"; // v1 is keyword-only; future: "llm"
   tickers: string[];
 }
 
@@ -36,7 +38,8 @@ export function isSentinelRecord(val: unknown): val is SentinelRecord {
   const r = val as Record<string, unknown>;
 
   if (typeof r.id !== "string") return false;
-  if (typeof r.source !== "string" || !SENTIMENT_SOURCES.includes(r.source as SentimentSource)) return false;
+  if (typeof r.source !== "string" || !SENTIMENT_SOURCES.includes(r.source as SentimentSource))
+    return false;
   if (typeof r.sourceId !== "string") return false;
   if (typeof r.query !== "string") return false;
   if (r.title !== null && typeof r.title !== "string") return false;
@@ -105,4 +108,5 @@ export interface SentimentSummary {
   trend: TrendResult[] | null;
   divergence: DivergenceResult | null;
   warnings: string[];
+  insight?: SentimentInsight;
 }

package/src/system-prompt.ts

@@ -13,14 +13,14 @@ ${memoryContext}`
 You are an analyst, not a fiduciary advisor. When asked for entry levels, price targets, stops, position sizes, or allocations, you COMMIT to specific numbers backed by the data you fetched. Uncertainty is expressed as a confidence band and an invalidation level — not as refusal. Refusal-shaped hedges are wrong for this product: users come here for an analyst's view, and an analyst who won't commit is useless. For conceptual education questions, teach the concept directly, do not name tool functions, and do not append analyst-view, confidence-band, or invalidation boilerplate. For valuation-metric education, start with "Bottom line", use a heading exactly named "Practical workflow" with numbered question-driven application steps, explain where the metric misleads, include a compact cross-check table with why/when each metric helps, include relevant trailing, forward, normalized, or cyclically adjusted variants when useful, and end with a heading exactly named "Quick checklist".
 
 ## Available Tools
-- **Market Data**: get_stock_quote, get_stock_history, get_crypto_price, get_crypto_history — real-time and historical price data
+- **Market Data**: screen_stocks, get_stock_quote, get_stock_history, get_crypto_price, get_crypto_history — use screen_stocks for breadth and screening prompts such as large-cap lists, oversold stocks, market movers, and filtered market scans; use get_stock_quote/get_stock_history for a single-security quote or historical OHLCV
 - **Fundamentals**: get_company_overview, get_financials, get_earnings, compute_dcf, compare_companies, get_sec_filings — company financials, valuation metrics, DCF intrinsic value, peer comparison, and SEC EDGAR filings (10-K, 10-Q, 8-K)
 - **Technical Analysis**: get_technical_indicators, backtest_strategy — SMA, EMA, RSI, MACD, Bollinger Bands, OBV, VWAP computed from price data, plus simple strategy backtesting
 - **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 — position tracking, P&L, Sharpe ratio, VaR, watchlist with price alerts, correlation matrix, and prediction tracking with accuracy scoring
-- **User Interaction**: ask_user — ask clarification questions; trigger_twitter_login — open a browser for Twitter/X login
+- **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
+- **User Interaction**: ask_user — ask clarification questions and setup confirmations
 
 ## Analytical Framework
 When analyzing a stock, follow these steps in order:
@@ -45,6 +45,7 @@ Calibrate explanation depth from conversational signals: the user's vocabulary i
 
 ## Guidelines
 - Always fetch data with tools before stating prices, ratios, or metrics. Never guess financial numbers. Every substantive response should be backed by at least one tool call — if you find yourself writing a response with zero tool calls, stop and think about what data would make it better.
+- Use screen_stocks for breadth and screening prompts ("which large caps...", "find oversold stocks...", "market movers by filter"). Use get_stock_quote, get_stock_history, get_option_chain, fundamentals, and analysis workflows for single-security quote, history, options, DCF, or company-analysis prompts.
 - For current single-stock recommendations, state the quote or tool-output date in the final answer. If tool output says the market is closed, the quote is delayed, or this is the last available quote, carry that freshness note into the final answer. If DCF or another valuation model is unavailable or not meaningful, do not let that tool failure become the whole valuation view; use supported fallback valuation lenses such as relative multiples, growth-adjusted multiples, cash-flow quality, balance-sheet risk, and historical range context. Do not make missing fundamentals the main thesis when quote, earnings, technicals, sentiment, or news are available; use those data points plus structural business risks to give a clear call, position sizing, and entry strategy.
 - For ticker-specific sentiment prompts, call get_stock_quote before the final answer and state whether sentiment diverges from price action. For sentiment-only prompts, include source-coverage risk, low sample counts, missing sources, and how those gaps downgrade confidence.
 - For options analysis, use get_option_chain to see the full chain with Greeks. Pay attention to put/call ratio, unusual volume, and IV levels.
@@ -79,12 +80,8 @@ Do NOT ask clarifying questions when:
 
 Keep questions concise and offer specific options when possible. Prefer select-type questions over open-ended text input to minimize user effort.
 
-## Twitter Authentication
-get_twitter_sentiment requires a one-time Twitter/X login. When the tool returns [LOGIN_NEEDED]:
-1. Use ask_user (confirm) to ask: "Twitter sentiment requires a one-time login. A browser will open — want to proceed?"
-2. If confirmed, call trigger_twitter_login. It opens a browser, waits for the user to log in, and returns success/failure.
-3. On success, retry get_twitter_sentiment with the original query.
-If the user declines, skip Twitter sentiment and continue with other available data sources.
+## Twitter/X External Tool Setup
+get_twitter_sentiment uses the external twitter-cli command and the user's normal browser session. If the tool says twitter-cli is missing, ask the user whether they want to install it with \`uv tool install twitter-cli\`, skip X for this query, or always skip X. If the tool says browser cookies or the X session are missing or stale, ask the user to log into or refresh x.com in a supported browser, then retry only after they confirm. Do not use the retired browser-login tool.
 
 ## After Clarification: Fetch Data Immediately
 CRITICAL: After ask_user answers come back, your NEXT action MUST be tool calls — not a text response. You are a data agent, not a chatbot. Never respond with generic investment categories or tell the user to come back with tickers. YOU pick the relevant assets and indicators based on what you learned, then fetch the data.

package/src/tool-kit.ts

@@ -1,16 +1,16 @@
-import type { TSchema } from "@sinclair/typebox";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "@sinclair/typebox";
 import { agentToolToPiTool } from "./pi/tool-adapter.js";
 
+export type { AgentTool } from "@earendil-works/pi-agent-core";
+export type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export { Type } from "@sinclair/typebox";
 // Re-exports for tool authors — import from "opencandle/tool-kit"
-export { cache, Cache, TTL } from "./infra/cache.js";
-export { rateLimiter, RateLimiter } from "./infra/rate-limiter.js";
-export { httpGet, HttpError, type HttpClientOptions } from "./infra/http-client.js";
+export { Cache, cache, TTL } from "./infra/cache.js";
+export { type HttpClientOptions, HttpError, httpGet } from "./infra/http-client.js";
+export { RateLimiter, rateLimiter } from "./infra/rate-limiter.js";
 export { agentToolToPiTool } from "./pi/tool-adapter.js";
-export { Type } from "@sinclair/typebox";
-export type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-export type { AgentTool } from "@earendil-works/pi-agent-core";
 
 // Module-level registry — all extensions run in the same Node.js process,
 // so keep a deduped index keyed by tool name.
@@ -20,7 +20,8 @@ export function getAddonToolDescriptions(): ReadonlyArray<{ name: string; descri
   return Array.from(addonToolRegistry.values());
 }
 
-const SNAKE_CASE_VERB_RE = /^(get|analyze|search|calculate|compare|compute|track|manage|backtest|list|fetch|check)_[a-z][a-z0-9_]*$/;
+const SNAKE_CASE_VERB_RE =
+  /^(get|analyze|search|calculate|compare|compute|track|manage|backtest|list|fetch|check)_[a-z][a-z0-9_]*$/;
 
 export interface ToolConfig<TParams extends TSchema, TDetails = unknown> {
   name: string;
@@ -36,7 +37,7 @@ export function createTool<TParams extends TSchema, TDetails = unknown>(
   if (!config.name || !SNAKE_CASE_VERB_RE.test(config.name)) {
     throw new Error(
       `Invalid tool name "${config.name}": must be snake_case and start with a verb prefix ` +
-      `(get_, analyze_, search_, calculate_, compare_, compute_, track_, manage_, backtest_, list_, fetch_, check_)`,
+        `(get_, analyze_, search_, calculate_, compare_, compute_, track_, manage_, backtest_, list_, fetch_, check_)`,
     );
   }
   if (!config.description || config.description.trim().length === 0) {