kalshi-trading-bot-cli 2.1.0

package/src/tools/v2/octagon-report.ts

@@ -0,0 +1,112 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { getDb } from '../../db/index.js';
+import { getLatestReport } from '../../db/octagon-cache.js';
+import { createOctagonInvoker, callOctagon } from '../../scan/invoker.js';
+import { OctagonClient } from '../../scan/octagon-client.js';
+import { auditTrail } from '../../audit/index.js';
+import { formatToolResult } from '../types.js';
+
+export const octagonReportTool = new DynamicStructuredTool({
+  name: 'octagon_report',
+  description: 'Fetch a full Octagon AI research report for a Kalshi market. Accepts a ticker or a full Kalshi market URL.',
+  schema: z.object({
+    ticker: z.string().describe('Market ticker (e.g. KXBTC-26MAR-B80000) or full Kalshi URL (e.g. https://kalshi.com/markets/kxcpiyoy/inflation/kxcpiyoy-26mar)'),
+    forceRefresh: z.boolean().optional().describe('Force a fresh API call instead of using cache'),
+  }),
+  func: async ({ ticker, forceRefresh }) => {
+    const db = getDb();
+    const isUrl = ticker.startsWith('http');
+
+    // Extract ticker from URL for cache lookup if needed
+    const cacheKey = isUrl ? ticker.split('/').pop() ?? ticker : ticker;
+
+    // Always call Octagon API — no local DB cache
+    // Octagon's own API has a cache variant (0 credits) that handles caching server-side
+    if (!process.env.OCTAGON_API_KEY) {
+      return formatToolResult({
+        error: 'OCTAGON_API_KEY not set. Cannot fetch fresh report.',
+        ticker: cacheKey,
+        ...((() => {
+          const stale = getLatestReport(db, cacheKey);
+          if (stale) {
+            return {
+              staleCache: true,
+              modelProb: stale.model_prob,
+              marketProb: stale.market_prob,
+              mispricingSignal: stale.mispricing_signal,
+              drivers: stale.drivers_json ? JSON.parse(stale.drivers_json) : [],
+              fetchedAt: stale.fetched_at,
+            };
+          }
+          return {};
+        })()),
+      });
+    }
+
+    const invoker = createOctagonInvoker();
+    const client = new OctagonClient(invoker, db, auditTrail);
+    const parts = cacheKey.split('-');
+    const eventTicker = parts.length >= 2 ? `${parts[0]}-${parts[1]}` : cacheKey;
+
+    // Try Octagon's cache first (0 credits), fall back to default if useless
+    const input = isUrl ? ticker : cacheKey;
+    let variant: 'cache' | 'default' | 'refresh' = 'cache';
+    let raw = await callOctagon(input, variant);
+    let report = client.parseReport(raw, cacheKey, eventTicker, variant);
+
+    // If cache returned a useless report (default 0.5/0.5), retry with 'default'
+    if (report.modelProb === 0.5 && report.drivers.length === 0) {
+      variant = 'default';
+      raw = await callOctagon(input, variant);
+      report = client.parseReport(raw, cacheKey, eventTicker, variant);
+    }
+
+    // Persist to DB
+    const { insertReport } = await import('../../db/octagon-cache.js');
+    const dbRow = client.toDbRow(report);
+    insertReport(db, dbRow);
+
+    return formatToolResult({
+      ticker: cacheKey,
+      cached: variant === 'cache',
+      modelProb: report.modelProb,
+      marketProb: report.marketProb,
+      mispricingSignal: report.mispricingSignal,
+      drivers: report.drivers,
+      catalysts: report.catalysts,
+      sources: report.sources,
+      resolutionHistory: report.resolutionHistory,
+      contractSnapshot: report.contractSnapshot,
+      variantUsed: report.variantUsed,
+      fetchedAt: report.fetchedAt,
+    });
+  },
+});
+
+export const OCTAGON_REPORT_DESCRIPTION = `
+Fetch a full Octagon AI research report for a Kalshi market. Returns model probability, price drivers, catalysts, and sources.
+
+## When to Use
+- User asks for a deep dive, analysis, or research on any market
+- User asks about edge, mispricing, or probability estimates
+- Any time you want model fair value vs market price
+- Use alongside kalshi_search for comprehensive analysis
+
+## Input
+- IMPORTANT: NEVER guess or construct tickers yourself — only use exact tickers returned by kalshi_search results
+- kalshi_search already auto-fetches an Octagon report for the top result — check if the data you need is already in the kalshi_search response before calling this tool separately
+- PREFERRED: Pass a full Kalshi URL (e.g. https://kalshi.com/markets/kxcpiyoy/inflation/kxcpiyoy-26mar) — this is what Octagon expects
+- Also accepts a market ticker (e.g. KXBTC-26MAR-B80000) — will be resolved to a URL automatically
+- If you got market data from kalshi_search, construct the URL as: https://kalshi.com/markets/SERIES/EVENT/TICKER (all lowercase) using the series_ticker, event_ticker, and ticker fields
+
+## When NOT to Use
+- For quick edge data already in the database (use edge_query)
+- For market prices or orderbook data only (use kalshi_search)
+- When kalshi_search already returned an octagon_report in its response — don't call again
+
+## Notes
+- Returns cached reports when available (< 24h old)
+- Use forceRefresh=true to get a fresh report (costs API credits)
+- When analyzing an event with multiple markets, pick the most relevant ticker and call this tool — don't ask the user to choose
+`.trim();

package/src/tools/v2/portfolio-query.ts

@@ -0,0 +1,79 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { getDb } from '../../db/index.js';
+import { getOpenPositions, getPositionWithEdge } from '../../db/positions.js';
+import { fetchLiveBankroll } from '../../risk/kelly.js';
+import { getLatestSnapshot } from '../../db/risk.js';
+import { computePerformance } from '../../eval/performance.js';
+import { formatToolResult } from '../types.js';
+
+export const portfolioQueryTool = new DynamicStructuredTool({
+  name: 'portfolio_query',
+  description: 'Get positions with current edge data, P&L, bankroll summary, and optional performance stats.',
+  schema: z.object({
+    includePerformance: z.boolean().optional().describe('Include historical performance stats (win rate, Sharpe, Brier scores)'),
+  }),
+  func: async ({ includePerformance }) => {
+    const db = getDb();
+
+    const openPositions = getOpenPositions(db);
+    const positions = openPositions.map((pos) => {
+      const withEdge = getPositionWithEdge(db, pos.position_id);
+      return {
+        ticker: pos.ticker,
+        direction: pos.direction,
+        size: pos.size,
+        entryPrice: pos.entry_price,
+        entryEdge: pos.entry_edge ?? null,
+        currentEdge: withEdge?.latest_edge?.edge ?? null,
+        unrealizedPnl: pos.current_pnl ?? null,
+        status: pos.status,
+      };
+    });
+
+    let bankroll;
+    try {
+      bankroll = await fetchLiveBankroll();
+    } catch {
+      bankroll = null;
+    }
+
+    const riskSnapshot = getLatestSnapshot(db);
+
+    const result: Record<string, unknown> = {
+      positions,
+      positionsCount: positions.length,
+      bankroll: bankroll ? {
+        cashBalance: bankroll.cashBalance,
+        portfolioValue: bankroll.portfolioValue,
+        openExposure: bankroll.openExposure,
+        available: bankroll.availableBankroll,
+      } : null,
+      riskSnapshot: riskSnapshot ? {
+        drawdownCurrent: riskSnapshot.drawdown_current,
+        drawdownMax: riskSnapshot.drawdown_max,
+        dailyPnl: riskSnapshot.daily_pnl,
+        circuitBreakerOn: !!riskSnapshot.circuit_breaker_on,
+      } : null,
+    };
+
+    if (includePerformance) {
+      result.performance = computePerformance(db);
+    }
+
+    return formatToolResult(result);
+  },
+});
+
+export const PORTFOLIO_QUERY_DESCRIPTION = `
+Get positions with current edge data, P&L, bankroll summary, and optional performance stats.
+
+## When to Use
+- User asks about their positions with edge context ("how are my positions doing?")
+- Needs bankroll + positions + risk in one call
+- Wants performance stats (win rate, Sharpe, Brier)
+
+## When NOT to Use
+- Quick balance check only (use portfolio_overview)
+- Detailed order history or fills (use kalshi_search)
+`.trim();

package/src/tools/v2/portfolio-review.ts

@@ -0,0 +1,59 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { reviewPortfolio } from '../../commands/review.js';
+import { formatToolResult } from '../types.js';
+
+export const portfolioReviewTool = new DynamicStructuredTool({
+  name: 'portfolio_review',
+  description: 'Review all open positions for close recommendations. Analyzes edge direction vs position direction and flags positions where the edge has reversed.',
+  schema: z.object({
+    sellOnly: z.boolean().optional().describe('If true, only return positions with SELL signals'),
+  }),
+  func: async ({ sellOnly }) => {
+    const reviews = await reviewPortfolio();
+
+    const filtered = sellOnly ? reviews.filter((r) => r.signal === 'SELL') : reviews;
+
+    const summary = {
+      totalPositions: reviews.length,
+      sellSignals: reviews.filter((r) => r.signal === 'SELL').length,
+      holdSignals: reviews.filter((r) => r.signal === 'HOLD').length,
+    };
+
+    return formatToolResult({
+      summary,
+      positions: filtered.map((r) => ({
+        ticker: r.ticker,
+        direction: r.direction,
+        size: r.size,
+        edge: r.edge,
+        edgePp: `${r.edge >= 0 ? '+' : ''}${(r.edge * 100).toFixed(0)}pp`,
+        signal: r.signal,
+        reason: r.reason,
+        closePriceCents: r.closePriceCents,
+        sellCommand: r.signal === 'SELL'
+          ? `/sell ${r.ticker} ${r.size} ${r.closePriceCents} ${r.direction}`
+          : null,
+        analyzeError: r.analyzeError ?? null,
+      })),
+    });
+  },
+});
+
+export const PORTFOLIO_REVIEW_DESCRIPTION = `
+Review all open positions for close (sell) recommendations based on edge reversal.
+
+## When to Use
+- User asks "what should I close?", "review my positions", "any sells?"
+- User wants to close underwater or reversed-edge positions
+- Before executing portfolio-wide close actions
+- User asks to "close my positions" or "sell my holdings"
+
+## When NOT to Use
+- Quick balance check only (use portfolio_overview)
+- Opening new positions (use edge_query or scan_markets)
+
+## How to Act on Results
+For each position with signal=SELL, use kalshi_trade to execute the close.
+Each trade requires user approval. Present the sell recommendations first, then execute.
+`.trim();

package/src/tools/v2/risk-status.ts

@@ -0,0 +1,94 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { getDb } from '../../db/index.js';
+import { getOpenPositions } from '../../db/positions.js';
+import { getLatestSnapshot } from '../../db/risk.js';
+import { formatToolResult } from '../types.js';
+
+export const riskStatusTool = new DynamicStructuredTool({
+  name: 'risk_status',
+  description: 'Check risk gate status: circuit breaker, drawdown, correlation, concentration limits.',
+  schema: z.object({}),
+  func: async () => {
+    const db = getDb();
+
+    const snapshot = getLatestSnapshot(db);
+    const openPositions = getOpenPositions(db);
+
+    const maxDrawdownPct = 0.20;
+    const maxTotalPositions = 10;
+
+    const checks = [];
+
+    // Circuit breaker
+    const circuitBreakerOn = !!snapshot?.circuit_breaker_on;
+    checks.push({
+      name: 'circuit_breaker',
+      status: circuitBreakerOn ? 'TRIGGERED' : 'OK',
+      detail: circuitBreakerOn ? 'Circuit breaker is active — no new trades allowed' : 'Circuit breaker inactive',
+    });
+
+    // Drawdown
+    const drawdown = snapshot?.drawdown_current ?? 0;
+    const drawdownOk = drawdown < maxDrawdownPct;
+    checks.push({
+      name: 'drawdown',
+      status: drawdownOk ? 'OK' : 'EXCEEDED',
+      detail: `Current: ${(drawdown * 100).toFixed(1)}% / Max allowed: ${maxDrawdownPct * 100}%`,
+      current: drawdown,
+      limit: maxDrawdownPct,
+    });
+
+    // Concentration
+    const posCount = openPositions.length;
+    const concentrationOk = posCount < maxTotalPositions;
+    checks.push({
+      name: 'concentration',
+      status: concentrationOk ? 'OK' : 'EXCEEDED',
+      detail: `${posCount} open positions / Max: ${maxTotalPositions}`,
+      current: posCount,
+      limit: maxTotalPositions,
+    });
+
+    // Max drawdown
+    checks.push({
+      name: 'max_drawdown',
+      status: 'INFO',
+      detail: snapshot?.drawdown_max != null
+        ? `Peak drawdown: ${(snapshot.drawdown_max * 100).toFixed(1)}%`
+        : 'No drawdown history yet',
+      current: snapshot?.drawdown_max ?? null,
+    });
+
+    // Daily P&L
+    checks.push({
+      name: 'daily_pnl',
+      status: 'INFO',
+      detail: snapshot?.daily_pnl != null
+        ? `Daily P&L: $${(snapshot.daily_pnl / 100).toFixed(2)}`
+        : 'No daily P&L data',
+      current: snapshot?.daily_pnl ?? null,
+    });
+
+    const allPassed = !circuitBreakerOn && drawdownOk && concentrationOk;
+
+    return formatToolResult({
+      overallStatus: allPassed ? 'CLEAR' : 'BLOCKED',
+      checks,
+      snapshotTimestamp: snapshot?.timestamp ?? null,
+    });
+  },
+});
+
+export const RISK_STATUS_DESCRIPTION = `
+Check the current risk gate status including circuit breaker, drawdown, and concentration limits.
+
+## When to Use
+- User asks "can I trade?" or "what's the risk status?"
+- Before recommending trades, to check if risk gates allow it
+- Checking if circuit breaker has been triggered
+
+## When NOT to Use
+- For portfolio positions or P&L (use portfolio_query)
+- For specific market risk analysis
+`.trim();

package/src/tools/v2/scan.ts

@@ -0,0 +1,78 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+import { getDb } from '../../db/index.js';
+import { auditTrail } from '../../audit/index.js';
+import { ScanLoop } from '../../scan/loop.js';
+import { createOctagonInvoker } from '../../scan/invoker.js';
+import { formatToolResult } from '../types.js';
+
+export const scanTool = new DynamicStructuredTool({
+  name: 'scan_markets',
+  description: 'Run a live market scan: fetches events from Kalshi, calls Octagon for model probabilities, computes edges, and stores results in the local database.',
+  schema: z.object({
+    theme: z.string().optional().describe('Theme to scan: "top50" (default), or any Kalshi category — "climate", "companies", "crypto", "economics", "elections", "entertainment", "financials", "health", "mentions", "politics", "science", "social", "sports", "transportation", "world", or a custom theme ID'),
+  }),
+  func: async ({ theme }) => {
+    const db = getDb();
+    const invoker = createOctagonInvoker();
+    const loop = new ScanLoop(db, auditTrail, invoker);
+
+    const result = await loop.runOnce({
+      theme: theme ?? 'top50',
+    });
+
+    const actionable = result.edgeSnapshots.filter(
+      (s) => s.confidence === 'high' || s.confidence === 'very_high'
+    );
+
+    // Return a compact summary with the most interesting edges
+    const edges = result.edgeSnapshots
+      .sort((a, b) => Math.abs(b.edge) - Math.abs(a.edge))
+      .slice(0, 30)
+      .map((s) => ({
+        ticker: s.ticker,
+        eventTicker: s.eventTicker,
+        modelProb: s.modelProb,
+        marketProb: s.marketProb,
+        edge: s.edge,
+        edgePct: `${(s.edge * 100).toFixed(1)}%`,
+        confidence: s.confidence,
+        drivers: s.drivers.slice(0, 2),
+      }));
+
+    return formatToolResult({
+      scanId: result.scanId,
+      theme: theme ?? 'top50',
+      eventsScanned: result.eventsScanned,
+      totalEdges: result.edgeSnapshots.length,
+      actionableCount: actionable.length,
+      octagonCreditsUsed: result.octagonCreditsUsed,
+      durationMs: result.duration,
+      topEdges: edges,
+      alerts: result.alerts.map((a) => ({ alertType: a.alertType, message: a.message })),
+    });
+  },
+});
+
+export const SCAN_DESCRIPTION = `
+Run a live market scan. Fetches events from Kalshi, calls Octagon AI for model probabilities, computes pricing edges (model vs market), and stores all results in the local database.
+
+## When to Use
+- User says "scan", "scan crypto", "scan politics", "find edges", "run a scan"
+- User wants to discover mispriced markets across a category
+- User wants to populate/refresh the edge database before querying it
+
+## When NOT to Use
+- For querying existing edge data already in the database (use edge_query instead — it's instant)
+- For looking up a specific market's price or details (use kalshi_search)
+
+## Themes
+- "top50" (default): Top 50 markets by 24h volume
+- "crypto", "politics", "economics", "sports", "entertainment", "science", "climate": Category-based scans
+- Custom theme ID: Pre-configured in database
+
+## Notes
+- Scans can take 30-120 seconds depending on the number of events
+- Each fresh Octagon call costs 3 credits (cached calls are free)
+- Results are stored in edge_history and can be queried later with edge_query
+`.trim();

package/src/types/qrcode-terminal.d.ts

@@ -0,0 +1,7 @@
+declare module 'qrcode-terminal' {
+  const qrcode: {
+    generate(text: string, options?: { small?: boolean }, cb?: (qr: string) => void): void;
+    setErrorLevel(level: string): void;
+  };
+  export default qrcode;
+}

package/src/types/whiskeysockets-baileys.d.ts

@@ -0,0 +1,41 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+declare module '@whiskeysockets/baileys' {
+  export type AnyMessageContent = Record<string, any>;
+  export type ConnectionState = {
+    connection: 'open' | 'close' | 'connecting';
+    lastDisconnect?: { error?: { output?: { statusCode?: number } }; date: Date };
+    qr?: string;
+    isNewLogin?: boolean;
+    isOnline?: boolean;
+    receivedPendingNotifications?: boolean;
+  };
+  export type WAMessage = {
+    key: { remoteJid?: string; fromMe?: boolean; id?: string; participant?: string };
+    message?: Record<string, any> | null;
+    messageTimestamp?: number | Long;
+    pushName?: string;
+  };
+  export namespace proto {
+    interface IWebMessageInfo {
+      key?: { remoteJid?: string; fromMe?: boolean; id?: string; participant?: string };
+      message?: Record<string, any> | null;
+      messageTimestamp?: number | Long;
+    }
+    interface Message {
+      conversation?: string;
+      extendedTextMessage?: { text?: string; contextInfo?: { mentionedJid?: string[] } };
+      [key: string]: any;
+    }
+  }
+  export const DisconnectReason: Record<string, number>;
+  export function fetchLatestBaileysVersion(): Promise<{ version: number[]; isLatest: boolean }>;
+  export function makeCacheableSignalKeyStore(store: any, logger: any): any;
+  export function makeWASocket(config: Record<string, any>): any;
+  export function useMultiFileAuthState(folder: string): Promise<{
+    state: any;
+    saveCreds: () => Promise<void>;
+  }>;
+  export function isJidGroup(jid: string): boolean;
+  export function normalizeMessageContent(content: any): Record<string, any> | undefined;
+  export function extractMessageContent(content: any): Record<string, any> | undefined;
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import type { DisplayEvent, TokenUsage } from './agent/types.js';
+
+export type WorkingState =
+  | { status: 'idle' }
+  | { status: 'thinking' }
+  | { status: 'tool'; toolName: string }
+  | { status: 'approval'; toolName: string };
+
+export type HistoryItemStatus = 'processing' | 'complete' | 'error' | 'interrupted';
+
+export interface HistoryItem {
+  id: string;
+  query: string;
+  events: DisplayEvent[];
+  answer: string;
+  status: HistoryItemStatus;
+  activeToolId?: string;
+  startTime?: number;
+  duration?: number;
+  tokenUsage?: TokenUsage;
+  tokensPerSecond?: number;
+}

package/src/utils/ai-message.ts

@@ -0,0 +1,26 @@
+import { AIMessage } from '@langchain/core/messages';
+
+/**
+ * Extract text content from an AIMessage
+ */
+export function extractTextContent(message: AIMessage): string {
+  if (typeof message.content === 'string') {
+    return message.content;
+  }
+
+  if (Array.isArray(message.content)) {
+    return message.content
+      .filter(block => typeof block === 'object' && 'type' in block && block.type === 'text')
+      .map(block => (block as { text: string }).text)
+      .join('\n');
+  }
+
+  return '';
+}
+
+/**
+ * Check if an AIMessage has tool calls
+ */
+export function hasToolCalls(message: AIMessage): boolean {
+  return Array.isArray(message.tool_calls) && message.tool_calls.length > 0;
+}