kalshi-trading-bot-cli 2.1.0

package/src/agent/types.ts

@@ -0,0 +1,221 @@
+// ============================================================================
+// Channel Profiles
+// ============================================================================
+
+/**
+ * Per-channel formatting profile that controls how the agent responds.
+ * Add new entries to CHANNEL_PROFILES in prompts.ts when adding channels.
+ */
+export interface ChannelProfile {
+  /** Human-readable label used in the system prompt preamble (e.g., "CLI", "WhatsApp") */
+  label: string;
+  /** One-liner describing the output surface, injected after the date line */
+  preamble: string;
+  /** Bullet points for the ## Behavior section */
+  behavior: string[];
+  /** Bullet points for the ## Response Format section */
+  responseFormat: string[];
+  /** Full tables instruction block, or null to omit the section entirely */
+  tables: string | null;
+}
+
+// ============================================================================
+// Approval
+// ============================================================================
+
+/**
+ * User's response to a tool approval prompt.
+ * - 'allow-once': approve this single invocation
+ * - 'allow-session': approve all invocations of this tool for the rest of the session
+ * - 'deny': reject and immediately end the agent's turn
+ */
+export type ApprovalDecision = 'allow-once' | 'allow-session' | 'deny';
+
+/**
+ * Agent configuration
+ */
+export interface AgentConfig {
+  /** Model to use for LLM calls (e.g., 'gpt-5.4', 'claude-sonnet-4-20250514') */
+  model?: string;
+  /** Model provider (e.g., 'openai', 'anthropic', 'google', 'ollama') */
+  modelProvider?: string;
+  /** Maximum agent loop iterations (default: 10) */
+  maxIterations?: number;
+  /** AbortSignal for cancelling agent execution */
+  signal?: AbortSignal;
+  /** Delivery channel (e.g., 'cli') — affects response formatting */
+  channel?: string;
+  /** Group chat context (e.g., WhatsApp groups) */
+  groupContext?: import('./prompts.js').GroupContext;
+  /** Called when a tool needs explicit user approval to proceed */
+  requestToolApproval?: (request: { tool: string; args: Record<string, unknown> }) => Promise<ApprovalDecision>;
+  /** Shared set of tool names that have been session-approved (persists across queries) */
+  sessionApprovedTools?: Set<string>;
+}
+
+/**
+ * Message in conversation history
+ */
+export interface Message {
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+}
+
+// ============================================================================
+// Agent Events (for real-time streaming UI)
+// ============================================================================
+
+/**
+ * Agent is processing/thinking
+ */
+export interface ThinkingEvent {
+  type: 'thinking';
+  message: string;
+}
+
+/**
+ * Tool execution started
+ */
+export interface ToolStartEvent {
+  type: 'tool_start';
+  tool: string;
+  args: Record<string, unknown>;
+}
+
+/**
+ * Tool execution completed successfully
+ */
+export interface ToolEndEvent {
+  type: 'tool_end';
+  tool: string;
+  args: Record<string, unknown>;
+  result: string;
+  duration: number;
+}
+
+/**
+ * Tool execution failed
+ */
+export interface ToolErrorEvent {
+  type: 'tool_error';
+  tool: string;
+  error: string;
+}
+
+/**
+ * Mid-execution progress update from a subagent tool
+ */
+export interface ToolProgressEvent {
+  type: 'tool_progress';
+  tool: string;
+  message: string;
+}
+
+/**
+ * Tool call warning due to approaching/exceeding suggested limits
+ */
+export interface ToolLimitEvent {
+  type: 'tool_limit';
+  tool: string;
+  /** Warning message about tool usage limits */
+  warning?: string;
+  /** Whether the tool call was blocked (always false - we only warn, never block) */
+  blocked: boolean;
+}
+
+/**
+ * Tool approval decision event for sensitive tools.
+ */
+export interface ToolApprovalEvent {
+  type: 'tool_approval';
+  tool: string;
+  args: Record<string, unknown>;
+  approved: ApprovalDecision;
+}
+
+/**
+ * Tool execution was denied by user approval flow.
+ */
+export interface ToolDeniedEvent {
+  type: 'tool_denied';
+  tool: string;
+  args: Record<string, unknown>;
+}
+
+/**
+ * Context was cleared due to exceeding token threshold (Anthropic-style)
+ */
+export interface ContextClearedEvent {
+  type: 'context_cleared';
+  /** Number of tool results that were cleared from context */
+  clearedCount: number;
+  /** Number of most recent tool results that were kept */
+  keptCount: number;
+}
+
+/**
+ * Session-start memory context was loaded into the system prompt.
+ */
+export interface MemoryRecalledEvent {
+  type: 'memory_recalled';
+  filesLoaded: string[];
+  tokenCount: number;
+}
+
+/**
+ * Pre-compaction memory flush lifecycle event.
+ */
+export interface MemoryFlushEvent {
+  type: 'memory_flush';
+  phase: 'start' | 'end';
+  filesWritten?: string[];
+}
+
+/**
+ * Token usage statistics
+ */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+}
+
+/**
+ * Agent completed with final result
+ */
+export interface DoneEvent {
+  type: 'done';
+  answer: string;
+  toolCalls: Array<{ tool: string; args: Record<string, unknown>; result: string }>;
+  iterations: number;
+  totalTime: number;
+  tokenUsage?: TokenUsage;
+  tokensPerSecond?: number;
+}
+
+/**
+ * Union type for all agent events
+ */
+export type AgentEvent =
+  | ThinkingEvent
+  | ToolStartEvent
+  | ToolProgressEvent
+  | ToolEndEvent
+  | ToolErrorEvent
+  | ToolApprovalEvent
+  | ToolDeniedEvent
+  | ToolLimitEvent
+  | ContextClearedEvent
+  | DoneEvent;
+
+/**
+ * Aggregated event used by the CLI history renderer.
+ * Combines lifecycle events (tool_start/tool_end/tool_error) into a single display row.
+ */
+export interface DisplayEvent {
+  id: string;
+  event: AgentEvent;
+  completed?: boolean;
+  endEvent?: AgentEvent;
+  progressMessage?: string;
+}

package/src/audit/index.ts

@@ -0,0 +1,25 @@
+export { AuditTrail } from './trail.js';
+export { readAuditLog } from './reader.js';
+export type { ReadAuditLogOpts } from './reader.js';
+export type {
+  AuditEvent,
+  AuditEventType,
+  AuditBase,
+  DistributiveOmit,
+  ScanStartEvent,
+  ScanCompleteEvent,
+  OctagonCallEvent,
+  EdgeDetectedEvent,
+  RecommendationEvent,
+  TradeExecutedEvent,
+  AlertSentEvent,
+  WatchdogCheckEvent,
+  ApiRetryEvent,
+  DlqEntryEvent,
+  ConfigChangeEvent,
+  ConfigSetEvent,
+} from './types.js';
+
+import { AuditTrail } from './trail.js';
+
+export const auditTrail = new AuditTrail();

package/src/audit/reader.ts

@@ -0,0 +1,43 @@
+import { readFileSync, existsSync } from 'fs';
+import type { AuditEvent } from './types.js';
+import { appPath } from '../utils/paths.js';
+
+const DEFAULT_PATH = appPath('audit.jsonl');
+
+export interface ReadAuditLogOpts {
+  filePath?: string;
+  since?: Date;
+  type?: string;
+  ticker?: string;
+  limit?: number;
+}
+
+export function readAuditLog(opts: ReadAuditLogOpts = {}): AuditEvent[] {
+  const filePath = opts.filePath ?? DEFAULT_PATH;
+
+  if (!existsSync(filePath)) return [];
+
+  const content = readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n').filter((line) => line.length > 0);
+
+  let events: AuditEvent[] = lines.map((line) => JSON.parse(line));
+
+  if (opts.since) {
+    const sinceIso = opts.since.toISOString();
+    events = events.filter((e) => e.ts >= sinceIso);
+  }
+
+  if (opts.type) {
+    events = events.filter((e) => e.type === opts.type);
+  }
+
+  if (opts.ticker) {
+    events = events.filter((e) => 'ticker' in e && (e as any).ticker === opts.ticker);
+  }
+
+  if (opts.limit !== undefined) {
+    events = events.slice(0, opts.limit);
+  }
+
+  return events;
+}

package/src/audit/trail.ts

@@ -0,0 +1,29 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import type { AuditEvent, DistributiveOmit } from './types.js';
+import { appPath } from '../utils/paths.js';
+
+const DEFAULT_PATH = appPath('audit.jsonl');
+
+export class AuditTrail {
+  private filePath: string;
+  private dirCreated = false;
+
+  constructor(filePath?: string) {
+    this.filePath = filePath ?? DEFAULT_PATH;
+  }
+
+  log(event: DistributiveOmit<AuditEvent, 'ts'>): void {
+    if (!this.dirCreated) {
+      mkdirSync(dirname(this.filePath), { recursive: true });
+      this.dirCreated = true;
+    }
+
+    const record = { ts: new Date().toISOString(), ...event };
+    appendFileSync(this.filePath, JSON.stringify(record) + '\n');
+  }
+
+  close(): void {
+    // No-op for sync I/O — included for interface symmetry
+  }
+}

package/src/audit/types.ts

@@ -0,0 +1,133 @@
+import type { ConfidenceLevel } from '../scan/types.js';
+
+export interface AuditBase {
+  ts: string; // ISO 8601 UTC
+  type: string;
+}
+
+export interface ScanStartEvent extends AuditBase {
+  type: 'SCAN_START';
+  theme: string;
+  events_count: number;
+}
+
+export interface ScanCompleteEvent extends AuditBase {
+  type: 'SCAN_COMPLETE';
+  scan_id: string;
+  theme: string;
+  events_scanned: number;
+  edges_found: number;
+  duration_ms: number;
+}
+
+export interface OctagonCallEvent extends AuditBase {
+  type: 'OCTAGON_CALL';
+  ticker: string;
+  variant: string;
+  cache_hit: boolean;
+  credits_used: number;
+}
+
+export interface EdgeDetectedEvent extends AuditBase {
+  type: 'EDGE_DETECTED';
+  ticker: string;
+  model_prob: number;
+  market_prob: number;
+  edge: number;
+  confidence: ConfidenceLevel;
+  drivers: string[];
+}
+
+export interface RecommendationEvent extends AuditBase {
+  type: 'RECOMMENDATION';
+  ticker: string;
+  action: string;
+  size: number;
+  kelly: number;
+  risk_gate: string;
+}
+
+export interface TradeExecutedEvent extends AuditBase {
+  type: 'TRADE_EXECUTED';
+  ticker: string;
+  order_id: string;
+  fill_price: number;
+  size: number;
+}
+
+export interface AlertSentEvent extends AuditBase {
+  type: 'ALERT_SENT';
+  alert_id: string;
+  channels: string[];
+}
+
+export interface WatchdogCheckEvent extends AuditBase {
+  type: 'WATCHDOG_CHECK';
+  ticker: string;
+  entry_edge: number;
+  current_edge: number;
+  status: string;
+}
+
+export interface ApiRetryEvent extends AuditBase {
+  type: 'API_RETRY';
+  method: string;
+  path: string;
+  attempt: number;
+  max_retries: number;
+  status_code: number;
+  delay_ms: number;
+}
+
+export interface DlqEntryEvent extends AuditBase {
+  type: 'DLQ_ENTRY';
+  method: string;
+  path: string;
+  error: string;
+  attempts: number;
+}
+
+export interface ConfigChangeEvent extends AuditBase {
+  type: 'CONFIG_CHANGE';
+  category: string;
+  avg_brier: number;
+  trigger: string;
+  recommendation: string;
+}
+
+export interface ConfigSetEvent extends AuditBase {
+  type: 'CONFIG_SET';
+  key: string;
+  old_value: string;  // JSON.stringify'd
+  new_value: string;  // JSON.stringify'd
+}
+
+export interface OctagonErrorEvent extends AuditBase {
+  type: 'OCTAGON_ERROR';
+  ticker: string;
+  event_ticker: string;
+  error: string;
+}
+
+export type AuditEvent =
+  | ScanStartEvent
+  | ScanCompleteEvent
+  | OctagonCallEvent
+  | EdgeDetectedEvent
+  | RecommendationEvent
+  | TradeExecutedEvent
+  | AlertSentEvent
+  | WatchdogCheckEvent
+  | ApiRetryEvent
+  | DlqEntryEvent
+  | ConfigChangeEvent
+  | ConfigSetEvent
+  | OctagonErrorEvent;
+
+export type AuditEventType = AuditEvent['type'];
+
+/**
+ * Distributive Omit that preserves discriminated union narrowing.
+ * Standard Omit<Union, K> collapses the union; this distributes over each member.
+ */
+export type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;

package/src/backtest/discovery.ts

@@ -0,0 +1,170 @@
+import type { Database } from 'bun:sqlite';
+import { callKalshiApi } from '../tools/kalshi/api.js';
+import type { KalshiMarket } from '../tools/kalshi/types.js';
+
+const CONCURRENCY = 10;
+
+export interface SettledMarket {
+  ticker: string;
+  event_ticker: string;
+  result: 'yes' | 'no';
+  close_time: string;
+  series_category: string;
+  last_price: number;         // last traded price (0-1)
+  volume: number;             // lifetime trading volume (used for tradeability gate)
+}
+
+export interface OpenMarket {
+  ticker: string;
+  event_ticker: string;
+  market_prob: number;        // current trading price (0-1)
+  close_time: string;
+  series_category: string;
+  volume: number;             // lifetime trading volume (tradeability gate)
+  volume_24h: number;         // 24-hour volume (liquidity-now gate)
+}
+
+/** Parse market price from Kalshi response (handles both cents and dollars formats). */
+function parsePrice(m: KalshiMarket): number {
+  const dollars = parseFloat(m.last_price_dollars ?? '');
+  if (Number.isFinite(dollars)) return dollars;
+  return typeof m.last_price === 'number' ? m.last_price / 100 : 0;
+}
+
+/** Parse lifetime volume (prefers volume_fp string from new API). */
+function parseVolume(m: KalshiMarket): number {
+  const fp = parseFloat(m.volume_fp ?? '');
+  if (Number.isFinite(fp)) return fp;
+  return typeof m.volume === 'number' ? m.volume : 0;
+}
+
+/** Parse 24h volume (prefers volume_24h_fp string from new API). */
+function parseVolume24h(m: KalshiMarket): number {
+  const fp = parseFloat(m.volume_24h_fp ?? '');
+  if (Number.isFinite(fp)) return fp;
+  return typeof m.volume_24h === 'number' ? m.volume_24h : 0;
+}
+
+/** Fetch event markets from Kalshi, returning empty array on error. */
+async function fetchEventMarkets(eventTicker: string): Promise<KalshiMarket[]> {
+  try {
+    const response = await callKalshiApi('GET', `/events/${eventTicker}`, {
+      params: { with_nested_markets: true },
+    });
+    if (!response || typeof response !== 'object') return [];
+    const obj = response as Record<string, unknown>;
+    const event = (obj.event ?? obj) as Record<string, unknown>;
+    const markets = event.markets;
+    return Array.isArray(markets) ? markets as KalshiMarket[] : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Build the event discovery query with optional category filter and extra WHERE clauses. */
+function buildEventQuery(
+  extraWhere: string,
+  category?: string,
+): { query: string; params: Record<string, string> } {
+  let query = `SELECT event_ticker, MAX(series_category) as category
+    FROM octagon_reports r WHERE variant_used = 'events-api'${extraWhere}`;
+  const params: Record<string, string> = {};
+  if (category) {
+    query += ' AND LOWER(series_category) LIKE $cat';
+    params.$cat = `%${category.toLowerCase()}%`;
+  }
+  query += ' GROUP BY event_ticker';
+  return { query, params };
+}
+
+/** Process items in parallel batches of `concurrency`. */
+export async function parallelMap<T, R>(
+  items: T[],
+  fn: (item: T) => Promise<R>,
+  concurrency: number,
+): Promise<R[]> {
+  const results: R[] = [];
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency);
+    const batchResults = await Promise.all(batch.map(fn));
+    results.push(...batchResults);
+  }
+  return results;
+}
+
+/**
+ * Discover settled Kalshi markets that have Octagon coverage with history.
+ *
+ * No close_time filter: the backtest's prediction-age window is enforced
+ * downstream via `selectSnapshotByDate`. Filtering on close_time here would
+ * wrongly exclude events that closed before the lookback window but whose
+ * predictions were still made within the prediction-age window (they'd still
+ * have outcomes to score against).
+ */
+export async function discoverSettledMarkets(
+  db: Database,
+  opts?: { category?: string },
+): Promise<SettledMarket[]> {
+  const { query, params } = buildEventQuery('', opts?.category);
+  const events = db.query(query).all(params) as Array<{ event_ticker: string; category: string | null }>;
+
+  const batchResults = await parallelMap(events, async ({ event_ticker, category: cat }) => {
+    const markets = await fetchEventMarkets(event_ticker);
+    const settled: SettledMarket[] = [];
+
+    for (const m of markets) {
+      const result = (m.result ?? '').toLowerCase();
+      if (result !== 'yes' && result !== 'no') continue;
+
+      settled.push({
+        ticker: m.ticker,
+        event_ticker,
+        result: result as 'yes' | 'no',
+        close_time: m.close_time ?? '',
+        series_category: cat ?? '',
+        last_price: parsePrice(m),
+        volume: parseVolume(m),
+      });
+    }
+    return settled;
+  }, CONCURRENCY);
+
+  return batchResults.flat();
+}
+
+/**
+ * Discover open Kalshi markets that have Octagon coverage.
+ */
+export async function discoverOpenMarkets(
+  db: Database,
+  opts?: { category?: string },
+): Promise<OpenMarket[]> {
+  const { query: q2, params: p2 } = buildEventQuery('', opts?.category);
+  const events2 = db.query(q2).all(p2) as Array<{ event_ticker: string; category: string | null }>;
+
+  const batchResults = await parallelMap(events2, async ({ event_ticker, category: cat }) => {
+    const markets = await fetchEventMarkets(event_ticker);
+    const open: OpenMarket[] = [];
+
+    for (const m of markets) {
+      const status = (m.status ?? '').toLowerCase();
+      if (status !== 'open' && status !== 'active') continue;
+
+      const marketProb = parsePrice(m);
+      if (marketProb <= 0) continue;
+
+      open.push({
+        ticker: m.ticker,
+        event_ticker,
+        market_prob: marketProb,
+        close_time: m.close_time ?? '',
+        series_category: cat ?? '',
+        volume: parseVolume(m),
+        volume_24h: parseVolume24h(m),
+      });
+    }
+    return open;
+  }, CONCURRENCY);
+
+  return batchResults.flat();
+}