kalshi-trading-bot-cli 2.1.0

package/src/agent/agent.ts

@@ -0,0 +1,249 @@
+import { AIMessage } from '@langchain/core/messages';
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { callLlm } from '../model/llm.js';
+import { getTools } from '../tools/registry.js';
+import { buildSystemPrompt, buildIterationPrompt } from './prompts.js';
+import { extractTextContent, hasToolCalls } from '../utils/ai-message.js';
+import { InMemoryChatHistory } from '../utils/in-memory-chat-history.js';
+import { buildHistoryContext } from '../utils/history-context.js';
+import { estimateTokens, CONTEXT_THRESHOLD, KEEP_TOOL_USES } from '../utils/tokens.js';
+import { formatUserFacingError, isContextOverflowError } from '../utils/errors.js';
+import type { AgentConfig, AgentEvent, ContextClearedEvent, TokenUsage } from '../agent/types.js';
+import { createRunContext, type RunContext } from './run-context.js';
+import { AgentToolExecutor } from './tool-executor.js';
+
+
+const DEFAULT_MODEL = 'gpt-5.4';
+const DEFAULT_MAX_ITERATIONS = 10;
+const MAX_OVERFLOW_RETRIES = 2;
+const OVERFLOW_KEEP_TOOL_USES = 3;
+
+/**
+ * The core agent class that handles the agent loop and tool execution.
+ */
+export class Agent {
+  private readonly model: string;
+  private readonly maxIterations: number;
+  private readonly tools: StructuredToolInterface[];
+  private readonly toolMap: Map<string, StructuredToolInterface>;
+  private readonly toolExecutor: AgentToolExecutor;
+  private readonly systemPrompt: string;
+  private readonly signal?: AbortSignal;
+
+  private constructor(
+    config: AgentConfig,
+    tools: StructuredToolInterface[],
+    systemPrompt: string,
+  ) {
+    this.model = config.model ?? DEFAULT_MODEL;
+    this.maxIterations = config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    this.tools = tools;
+    this.toolMap = new Map(tools.map(t => [t.name, t]));
+    this.toolExecutor = new AgentToolExecutor(this.toolMap, config.signal, config.requestToolApproval, config.sessionApprovedTools);
+    this.systemPrompt = systemPrompt;
+    this.signal = config.signal;
+  }
+
+  /**
+   * Create a new Agent instance with tools.
+   */
+  static async create(config: AgentConfig = {}): Promise<Agent> {
+    const model = config.model ?? DEFAULT_MODEL;
+    const tools = getTools(model);
+    const systemPrompt = buildSystemPrompt(model, config.channel);
+    return new Agent(config, tools, systemPrompt);
+  }
+
+  /**
+   * Run the agent and yield events for real-time UI updates.
+   * Anthropic-style context management: full tool results during iteration,
+   * with threshold-based clearing of oldest results when context exceeds limit.
+   */
+  async *run(query: string, inMemoryHistory?: InMemoryChatHistory): AsyncGenerator<AgentEvent> {
+    const startTime = Date.now();
+
+    if (this.tools.length === 0) {
+      yield { type: 'done', answer: 'No tools available. Please check your API key configuration.', toolCalls: [], iterations: 0, totalTime: Date.now() - startTime };
+      return;
+    }
+
+    const ctx = createRunContext(query);
+
+    // Build initial prompt with conversation history context
+    let currentPrompt = this.buildInitialPrompt(query, inMemoryHistory);
+
+    // Main agent loop
+    let overflowRetries = 0;
+    while (ctx.iteration < this.maxIterations) {
+      ctx.iteration++;
+
+      let response: AIMessage | string;
+      let usage: TokenUsage | undefined;
+
+      while (true) {
+        try {
+          const result = await this.callModel(currentPrompt);
+          response = result.response;
+          usage = result.usage;
+          overflowRetries = 0;
+          break;
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+
+          if (isContextOverflowError(errorMessage) && overflowRetries < MAX_OVERFLOW_RETRIES) {
+            overflowRetries++;
+            const clearedCount = ctx.scratchpad.clearOldestToolResults(OVERFLOW_KEEP_TOOL_USES);
+
+            if (clearedCount > 0) {
+              yield { type: 'context_cleared', clearedCount, keptCount: OVERFLOW_KEEP_TOOL_USES };
+              currentPrompt = buildIterationPrompt(
+                query,
+                ctx.scratchpad.getToolResults(),
+                ctx.scratchpad.formatToolUsageForPrompt()
+              );
+              continue;
+            }
+          }
+
+          const totalTime = Date.now() - ctx.startTime;
+          yield {
+            type: 'done',
+            answer: `Error: ${formatUserFacingError(errorMessage)}`,
+            toolCalls: ctx.scratchpad.getToolCallRecords(),
+            iterations: ctx.iteration,
+            totalTime,
+            tokenUsage: ctx.tokenCounter.getUsage(),
+            tokensPerSecond: ctx.tokenCounter.getTokensPerSecond(totalTime),
+          };
+          return;
+        }
+      }
+
+      ctx.tokenCounter.add(usage);
+      const responseText = typeof response === 'string' ? response : extractTextContent(response);
+
+      // Emit thinking if there are also tool calls (skip whitespace-only responses)
+      if (responseText?.trim() && typeof response !== 'string' && hasToolCalls(response)) {
+        const trimmedText = responseText.trim();
+        ctx.scratchpad.addThinking(trimmedText);
+        yield { type: 'thinking', message: trimmedText };
+      }
+
+      // No tool calls = final answer is in this response
+      if (typeof response === 'string' || !hasToolCalls(response)) {
+        yield* this.handleDirectResponse(responseText ?? '', ctx);
+        return;
+      }
+
+      // Execute tools and add results to scratchpad (response is AIMessage here)
+      for await (const event of this.toolExecutor.executeAll(response, ctx)) {
+        yield event;
+        if (event.type === 'tool_denied') {
+          const totalTime = Date.now() - ctx.startTime;
+          yield {
+            type: 'done',
+            answer: '',
+            toolCalls: ctx.scratchpad.getToolCallRecords(),
+            iterations: ctx.iteration,
+            totalTime,
+            tokenUsage: ctx.tokenCounter.getUsage(),
+            tokensPerSecond: ctx.tokenCounter.getTokensPerSecond(totalTime),
+          };
+          return;
+        }
+      }
+      yield* this.manageContextThreshold(ctx, query);
+
+      // Build iteration prompt with full tool results (Anthropic-style)
+      currentPrompt = buildIterationPrompt(
+        query,
+        ctx.scratchpad.getToolResults(),
+        ctx.scratchpad.formatToolUsageForPrompt()
+      );
+    }
+
+    // Max iterations reached with no final response
+    const totalTime = Date.now() - ctx.startTime;
+    yield {
+      type: 'done',
+      answer: `Reached maximum iterations (${this.maxIterations}). I was unable to complete the research in the allotted steps.`,
+      toolCalls: ctx.scratchpad.getToolCallRecords(),
+      iterations: ctx.iteration,
+      totalTime,
+      tokenUsage: ctx.tokenCounter.getUsage(),
+      tokensPerSecond: ctx.tokenCounter.getTokensPerSecond(totalTime),
+    };
+  }
+
+  /**
+   * Call the LLM with the current prompt.
+   */
+  private async callModel(prompt: string, useTools: boolean = true): Promise<{ response: AIMessage | string; usage?: TokenUsage }> {
+    const result = await callLlm(prompt, {
+      model: this.model,
+      systemPrompt: this.systemPrompt,
+      tools: useTools ? this.tools : undefined,
+      signal: this.signal,
+    });
+    return { response: result.response, usage: result.usage };
+  }
+
+  /**
+   * Emit the response text as the final answer.
+   */
+  private async *handleDirectResponse(
+    responseText: string,
+    ctx: RunContext
+  ): AsyncGenerator<AgentEvent, void> {
+    const totalTime = Date.now() - ctx.startTime;
+    yield {
+      type: 'done',
+      answer: responseText,
+      toolCalls: ctx.scratchpad.getToolCallRecords(),
+      iterations: ctx.iteration,
+      totalTime,
+      tokenUsage: ctx.tokenCounter.getUsage(),
+      tokensPerSecond: ctx.tokenCounter.getTokensPerSecond(totalTime),
+    };
+  }
+
+  /**
+   * Clear oldest tool results if context size exceeds threshold.
+   */
+  private async *manageContextThreshold(
+    ctx: RunContext,
+    query: string,
+  ): AsyncGenerator<ContextClearedEvent, void> {
+    const fullToolResults = ctx.scratchpad.getToolResults();
+    const estimatedContextTokens = estimateTokens(this.systemPrompt + ctx.query + fullToolResults);
+
+    if (estimatedContextTokens > CONTEXT_THRESHOLD) {
+      const clearedCount = ctx.scratchpad.clearOldestToolResults(KEEP_TOOL_USES);
+      if (clearedCount > 0) {
+        yield { type: 'context_cleared', clearedCount, keptCount: KEEP_TOOL_USES };
+      }
+    }
+  }
+
+  /**
+   * Build initial prompt with conversation history context if available
+   */
+  private buildInitialPrompt(
+    query: string,
+    inMemoryChatHistory?: InMemoryChatHistory
+  ): string {
+    if (!inMemoryChatHistory?.hasMessages()) {
+      return query;
+    }
+
+    const recentTurns = inMemoryChatHistory.getRecentTurns();
+    if (recentTurns.length === 0) {
+      return query;
+    }
+
+    return buildHistoryContext({
+      entries: recentTurns,
+      currentMessage: query,
+    });
+  }
+}

package/src/agent/channels.ts

@@ -0,0 +1,53 @@
+import type { ChannelProfile } from './types.js';
+
+// ============================================================================
+// Channel Profiles — add new channels here
+// ============================================================================
+
+const CLI_PROFILE: ChannelProfile = {
+  label: 'CLI',
+  preamble:
+    'Your output is displayed on a command line interface. Keep responses short and concise.\nType /help to see available slash commands for quick market actions.',
+  behavior: [
+    "Prioritize accuracy over validation - don't cheerfully agree with flawed assumptions",
+    'Use professional, objective tone without excessive praise or emotional validation',
+    'For research tasks, be thorough but efficient',
+    'Avoid over-engineering responses - match the scope of your answer to the question',
+    'Never expose raw API internals or ask users to paste JSON - synthesize the data into readable answers',
+    'If data is incomplete, answer with what you have without exposing implementation details',
+  ],
+  responseFormat: [
+    'Keep casual responses brief and direct',
+    'For research: lead with the key finding and include specific data points',
+    'For non-comparative information, prefer plain text or simple lists over tables',
+    "Don't narrate your actions or ask leading questions about what the user wants",
+    'Do not use markdown headers or *italics* - use **bold** sparingly for emphasis',
+  ],
+  tables: `Use markdown tables. They will be rendered as formatted box tables.
+
+STRICT FORMAT - each row must:
+- Start with | and end with |
+- Have no trailing spaces after the final |
+- Use |---| separator (with optional : for alignment)
+
+| Ticker | YES   | NO    | Volume |
+|--------|-------|-------|--------|
+| KXBTC  | $0.56 | $0.44 | 12,450 |
+
+Keep tables compact:
+- Max 4 columns; prefer multiple small tables over one wide table
+- Headers: 1-3 words max
+- Prices: $0.56 not $0.5600
+- Tickers not full names where possible
+- Numbers compact: 12.5K not 12,500`,
+};
+
+/** Registry of channel profiles. Add new channels here. */
+const CHANNEL_PROFILES: Record<string, ChannelProfile> = {
+  cli: CLI_PROFILE,
+};
+
+/** Resolve the profile for a channel, falling back to CLI. */
+export function getChannelProfile(channel?: string): ChannelProfile {
+  return CHANNEL_PROFILES[channel ?? 'cli'] ?? CLI_PROFILE;
+}

package/src/agent/index.ts

@@ -0,0 +1,29 @@
+export { Agent } from './agent.js';
+
+export { Scratchpad } from './scratchpad.js';
+
+export { getCurrentDate, buildSystemPrompt, buildIterationPrompt, DEFAULT_SYSTEM_PROMPT } from './prompts.js';
+
+export type { 
+  ApprovalDecision,
+  AgentConfig, 
+  Message,
+  AgentEvent,
+  ThinkingEvent,
+  ToolStartEvent,
+  ToolProgressEvent,
+  ToolEndEvent,
+  ToolErrorEvent,
+  ToolApprovalEvent,
+  ToolDeniedEvent,
+  ToolLimitEvent,
+  ContextClearedEvent,
+  DoneEvent,
+} from './types.js';
+
+export type { 
+  ToolCallRecord, 
+  ScratchpadEntry,
+  ToolLimitConfig,
+  ToolUsageStatus,
+} from './scratchpad.js';

package/src/agent/prompts.ts

@@ -0,0 +1,171 @@
+import { buildToolDescriptions } from '../tools/registry.js';
+import { getChannelProfile } from './channels.js';
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Returns the current date formatted for prompts.
+ */
+export function getCurrentDate(): string {
+  const options: Intl.DateTimeFormatOptions = {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  };
+  return new Date().toLocaleDateString('en-US', options);
+}
+
+// ============================================================================
+// Group Context
+// ============================================================================
+
+/**
+ * Context for group chat conversations (e.g., WhatsApp groups).
+ */
+export interface GroupContext {
+  /** Display name of the group */
+  groupName?: string;
+  /** Formatted list of group members */
+  membersList?: string;
+  /** How the bot was activated in the group */
+  activationMode?: 'mention' | 'command' | 'direct';
+}
+
+// ============================================================================
+// Default System Prompt (for backward compatibility)
+// ============================================================================
+
+export const DEFAULT_SYSTEM_PROMPT = `You are Kalshi Trading Bot CLI, a prediction market research and trading assistant.
+
+Current date: ${getCurrentDate()}
+
+Your output is displayed on a command line interface. Keep responses short and concise.
+
+## Behavior
+
+- Prioritize accuracy over validation
+- Use professional, objective tone
+- Be thorough but efficient
+
+## Response Format
+
+- Keep responses brief and direct
+- For non-comparative information, prefer plain text or simple lists over tables
+- Do not use markdown headers or *italics* - use **bold** sparingly for emphasis
+
+## Tables (for comparative/tabular data)
+
+Use markdown tables. They will be rendered as formatted box tables.
+
+STRICT FORMAT - each row must:
+- Start with | and end with |
+- Have no trailing spaces after the final |
+- Use |---| separator (with optional : for alignment)
+
+| Ticker | YES  | NO   |
+|--------|------|------|
+| KXBTC  | $0.56| $0.44|
+
+Keep tables compact:
+- Max 3-4 columns; prefer multiple small tables over one wide table
+- Headers: 1-3 words max
+- Numbers compact: $0.56 not $0.5600
+- Omit units in cells if header has them`;
+
+// ============================================================================
+// System Prompt
+// ============================================================================
+
+/**
+ * Build the system prompt for the agent.
+ * @param model - The model name (used to get appropriate tool descriptions)
+ * @param channel - Delivery channel (e.g., 'cli') — selects formatting profile
+ */
+export function buildSystemPrompt(model: string, channel?: string): string {
+  const toolDescriptions = buildToolDescriptions(model);
+  const profile = getChannelProfile(channel);
+
+  const behaviorBullets = profile.behavior.map((b) => `- ${b}`).join('\n');
+  const formatBullets = profile.responseFormat.map((b) => `- ${b}`).join('\n');
+
+  const tablesSection = profile.tables
+    ? `\n## Tables (for comparative/tabular data)\n\n${profile.tables}`
+    : '';
+
+  return `You are Kalshi Trading Bot CLI, an AI-powered prediction market research and trading assistant.
+
+Current date: ${getCurrentDate()}
+
+${profile.preamble}
+
+## Available Tools
+
+${toolDescriptions}
+
+## Tool Usage Policy
+
+- For market data, events, orderbooks, historical data, portfolio info → use kalshi_search
+- For placing, amending, or canceling orders → use kalshi_trade (requires user approval)
+- For a quick portfolio balance + positions check → use portfolio_overview
+- For background research on real-world events behind markets → use web_search or web_fetch
+- For running a live scan to find mispriced markets → use scan_markets (fetches from Kalshi + Octagon, populates DB)
+- For querying existing edge signals already in the database → use edge_query (instant, reads from DB)
+- For positions with current edge, P&L, and bankroll → use portfolio_query
+- For risk gate status, circuit breaker, drawdown → use risk_status
+- For reviewing positions and identifying close (sell) opportunities → use portfolio_review. Present the SELL signals and trade recommendations to the user. Only invoke kalshi_trade after the user has explicitly approved execution of the specific trade(s)
+- IMPORTANT: Whenever the user asks about ANY specific market, event, or ticker — call octagon_report. This applies to deep dives, research, analysis, "tell me about", "what do you think of", price checks, edge questions, or any query that references a market. The Octagon report provides model probabilities, price drivers, catalysts, and sources that make your answer dramatically better. Call it alongside kalshi_search by default. Pick the most relevant ticker yourself — never ask the user to choose. Pass a full Kalshi URL when possible (like https://kalshi.com/markets/kxcpiyoy/inflation/kxcpiyoy-26mar) — construct it from kalshi_search results using the series_ticker, event_ticker, and ticker fields. The only exceptions are pure account queries (balance, orders, positions) or trade execution
+- The edge/portfolio/risk/octagon tools query the local database populated by the scan loop
+- NEVER place trades without explicit user confirmation
+- Prices are in cents: $0.56 = 56 cents = 56% implied probability
+- YES price + NO price ≈ 100 cents (they are complements)
+- CRITICAL TABLE FORMAT: When Octagon data is available (look for octagon_report in kalshi_search results — it contains outcome_probabilities with per-market model_probability and market_probability), you MUST show a SINGLE unified table. Match each market ticker to its Octagon outcome by market_ticker field, then show:
+  | Ticker | Market | Model | Edge | Vol |
+  |--------|--------|-------|------|-----|
+  | KXTESLA-26-Q1-330000 | 72% | 95% | +23% | 67.5K |
+  | KXTESLA-26-Q1-340000 | 65% | 65% | 0% | 92.1K |
+  Market = YES price as %. Model = model_probability from octagon outcome_probabilities. Edge = Model - Market.
+  NEVER show a table without Model and Edge columns when Octagon data is present. NEVER show Octagon data in a separate section — it must be in the same table as market data
+
+## Behavior
+
+${behaviorBullets}
+
+## Response Format
+
+${formatBullets}${tablesSection}`;
+}
+
+// ============================================================================
+// User Prompts
+// ============================================================================
+
+/**
+ * Build user prompt for agent iteration with full tool results.
+ * Anthropic-style: full results in context for accurate decision-making.
+ *
+ * @param originalQuery - The user's original query
+ * @param fullToolResults - Formatted full tool results
+ * @param toolUsageStatus - Optional tool usage status for graceful exit mechanism
+ */
+export function buildIterationPrompt(
+  originalQuery: string,
+  fullToolResults: string,
+  toolUsageStatus?: string | null
+): string {
+  let prompt = `Query: ${originalQuery}`;
+
+  if (fullToolResults.trim()) {
+    prompt += `\n\nData retrieved from tool calls:\n${fullToolResults}`;
+  }
+
+  if (toolUsageStatus) {
+    prompt += `\n\n${toolUsageStatus}`;
+  }
+
+  prompt += `\n\nContinue working toward answering the query. When you have gathered sufficient data to answer, write your complete answer directly and do not call more tools. NEVER guess at URLs - use ONLY URLs visible in tool results.`;
+
+  return prompt;
+}

package/src/agent/run-context.ts

@@ -0,0 +1,23 @@
+import { Scratchpad } from './scratchpad.js';
+import { TokenCounter } from './token-counter.js';
+
+/**
+ * Mutable state for a single agent run.
+ */
+export interface RunContext {
+  readonly query: string;
+  readonly scratchpad: Scratchpad;
+  readonly tokenCounter: TokenCounter;
+  readonly startTime: number;
+  iteration: number;
+}
+
+export function createRunContext(query: string): RunContext {
+  return {
+    query,
+    scratchpad: new Scratchpad(query),
+    tokenCounter: new TokenCounter(),
+    startTime: Date.now(),
+    iteration: 0,
+  };
+}