kalshi-trading-bot-cli 2.1.0

package/src/utils/errors.ts

@@ -0,0 +1,313 @@
+export interface ApiErrorInfo {
+  httpCode?: number;
+  type?: string;
+  code?: string;
+  message?: string;
+  requestId?: string;
+}
+
+export type ErrorType =
+  | 'context_overflow'
+  | 'rate_limit'
+  | 'billing'
+  | 'auth'
+  | 'timeout'
+  | 'overloaded'
+  | 'unknown';
+
+type ErrorPattern = RegExp | string;
+
+const ERROR_PATTERNS = {
+  rateLimit: [
+    /rate[_ ]limit|too many requests|429/i,
+    'model_cooldown',
+    'cooling down',
+    'exceeded your current quota',
+    'resource has been exhausted',
+    'quota exceeded',
+    'resource_exhausted',
+    'usage limit',
+    'tpm',
+    'tokens per minute',
+  ],
+  overloaded: [
+    /overloaded_error|"type"\s*:\s*"overloaded_error"/i,
+    'overloaded',
+    'service unavailable',
+    'high demand',
+  ],
+  timeout: [
+    'timeout',
+    'timed out',
+    'deadline exceeded',
+    'context deadline exceeded',
+  ],
+  billing: [
+    /["']?(?:status|code)["']?\s*[:=]\s*402\b/i,
+    /\bhttp\s*402\b/i,
+    'payment required',
+    'insufficient credits',
+    'credit balance',
+    'insufficient balance',
+  ],
+  auth: [
+    /invalid[_ ]?api[_ ]?key/i,
+    'incorrect api key',
+    'invalid token',
+    'authentication',
+    'unauthorized',
+    'forbidden',
+    'access denied',
+    /\b401\b/,
+    /\b403\b/,
+    'no api key found',
+  ],
+  contextOverflow: [
+    'context length exceeded',
+    'maximum context length',
+    "this model's maximum context length",
+    'prompt is too long',
+    'request_too_large',
+    'exceeds model context window',
+    'context overflow',
+    'exceed context limit',
+    'model token limit',
+    'your request exceeded model token limit',
+  ],
+} as const;
+
+const CHINESE_CONTEXT_OVERFLOW = ['上下文过长', '上下文超出', '超出最大上下文'];
+const ERROR_PAYLOAD_PREFIX_RE = /^\[[\w\s]+\]\s*|^(?:error|api\s*error)[:\s-]+/i;
+const HTTP_STATUS_PREFIX_RE = /^(\d{3})\s+(.+)$/s;
+
+export function parseApiErrorInfo(raw?: string): ApiErrorInfo | null {
+  if (!raw) return null;
+
+  let trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  let httpCode: number | undefined;
+
+  trimmed = trimmed.replace(ERROR_PAYLOAD_PREFIX_RE, '').trim();
+
+  const httpMatch = trimmed.match(HTTP_STATUS_PREFIX_RE);
+  if (httpMatch) {
+    httpCode = Number.parseInt(httpMatch[1], 10);
+    trimmed = httpMatch[2].trim();
+  }
+
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    const requestId = typeof parsed.request_id === 'string'
+      ? parsed.request_id
+      : typeof parsed.requestId === 'string'
+        ? parsed.requestId
+        : undefined;
+
+    if (parsed.error && typeof parsed.error === 'object' && !Array.isArray(parsed.error)) {
+      const err = parsed.error as Record<string, unknown>;
+      return {
+        httpCode,
+        type: typeof err.type === 'string' ? err.type : undefined,
+        code: typeof err.code === 'string' ? err.code : undefined,
+        message: typeof err.message === 'string' ? err.message : undefined,
+        requestId,
+      };
+    }
+
+    if (parsed.type === 'error' && parsed.error && typeof parsed.error === 'object' && !Array.isArray(parsed.error)) {
+      const err = parsed.error as Record<string, unknown>;
+      return {
+        httpCode,
+        type: typeof err.type === 'string' ? err.type : undefined,
+        message: typeof err.message === 'string' ? err.message : undefined,
+        requestId,
+      };
+    }
+
+    if (typeof parsed.message === 'string') {
+      return {
+        httpCode,
+        type: typeof parsed.type === 'string' ? parsed.type : undefined,
+        code: typeof parsed.code === 'string' ? parsed.code : undefined,
+        message: parsed.message,
+        requestId,
+      };
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function matchesPatterns(raw: string, patterns: readonly ErrorPattern[]): boolean {
+  const lower = raw.toLowerCase();
+  return patterns.some((pattern) =>
+    pattern instanceof RegExp ? pattern.test(raw) : lower.includes(pattern)
+  );
+}
+
+export function isContextOverflowError(raw?: string): boolean {
+  if (!raw) return false;
+  const lower = raw.toLowerCase();
+
+  if (lower.includes('tpm') || lower.includes('tokens per minute')) {
+    return false;
+  }
+
+  if (matchesPatterns(raw, ERROR_PATTERNS.contextOverflow)) {
+    return true;
+  }
+
+  if (CHINESE_CONTEXT_OVERFLOW.some(msg => raw.includes(msg))) {
+    return true;
+  }
+
+  if (lower.includes('request size exceeds') && lower.includes('context')) {
+    return true;
+  }
+  if (lower.includes('max_tokens') && lower.includes('exceed') && lower.includes('context')) {
+    return true;
+  }
+  if (lower.includes('input length') && lower.includes('exceed') && lower.includes('context')) {
+    return true;
+  }
+  if (lower.includes('413') && lower.includes('too large')) {
+    return true;
+  }
+
+  return false;
+}
+
+export function isRateLimitError(raw?: string): boolean {
+  return raw ? matchesPatterns(raw, ERROR_PATTERNS.rateLimit) : false;
+}
+
+export function isBillingError(raw?: string): boolean {
+  return raw ? matchesPatterns(raw, ERROR_PATTERNS.billing) : false;
+}
+
+export function isAuthError(raw?: string): boolean {
+  return raw ? matchesPatterns(raw, ERROR_PATTERNS.auth) : false;
+}
+
+export function isTimeoutError(raw?: string): boolean {
+  return raw ? matchesPatterns(raw, ERROR_PATTERNS.timeout) : false;
+}
+
+export function isOverloadedError(raw?: string): boolean {
+  return raw ? matchesPatterns(raw, ERROR_PATTERNS.overloaded) : false;
+}
+
+export function classifyError(raw?: string): ErrorType {
+  if (!raw) return 'unknown';
+
+  if (isContextOverflowError(raw)) return 'context_overflow';
+  if (isRateLimitError(raw)) return 'rate_limit';
+  if (isBillingError(raw)) return 'billing';
+  if (isAuthError(raw)) return 'auth';
+  if (isTimeoutError(raw)) return 'timeout';
+  if (isOverloadedError(raw)) return 'overloaded';
+
+  return 'unknown';
+}
+
+export function isNonRetryableError(raw?: string): boolean {
+  const type = classifyError(raw);
+  return type === 'context_overflow' || type === 'billing' || type === 'auth';
+}
+
+// ─── CLI exit codes ─────────────────────────────────────────────────────────
+// 0 = success
+// 1 = user / validation error  (bad args, unknown command, invalid price)
+// 2 = auth / permission error   (401, 403 from Kalshi API)
+// 3 = external / server error   (500, 503 from Kalshi API, network timeout)
+// 4 = internal error             (unhandled exception, unexpected state)
+
+export const ExitCode = {
+  SUCCESS: 0,
+  USER_ERROR: 1,
+  AUTH_ERROR: 2,
+  EXTERNAL_ERROR: 3,
+  INTERNAL_ERROR: 4,
+} as const;
+
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+
+/**
+ * Derive an exit code from an error. Inspects KalshiApiError.statusCode
+ * and falls back to message-based classification.
+ */
+export function exitCodeFromError(err: unknown): ExitCode {
+  // KalshiApiError (or anything with a numeric statusCode)
+  if (err && typeof err === 'object' && 'statusCode' in err) {
+    const code = (err as { statusCode: number }).statusCode;
+    if (code === 401 || code === 402 || code === 403) return ExitCode.AUTH_ERROR;
+    if (code === 429) return ExitCode.EXTERNAL_ERROR;
+    if (code >= 400 && code < 500) return ExitCode.USER_ERROR;
+    if (code >= 500) return ExitCode.EXTERNAL_ERROR;
+  }
+
+  // Fall back to message-based heuristics from classifyError
+  const msg = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+  const errorType = classifyError(msg);
+  switch (errorType) {
+    case 'auth':
+    case 'billing':
+      return ExitCode.AUTH_ERROR;
+    case 'rate_limit':
+    case 'timeout':
+    case 'overloaded':
+    case 'context_overflow':
+      return ExitCode.EXTERNAL_ERROR;
+    default:
+      return ExitCode.INTERNAL_ERROR;
+  }
+}
+
+export function formatUserFacingError(raw: string, provider?: string): string {
+  if (!raw.trim()) {
+    return 'LLM request failed with an unknown error.';
+  }
+
+  const errorType = classifyError(raw);
+  const info = parseApiErrorInfo(raw);
+  const providerLabel = provider ? `${provider} ` : '';
+
+  switch (errorType) {
+    case 'context_overflow':
+      return 'Context overflow: the conversation is too large for the model. ' +
+        'Try starting a new conversation or use a model with a larger context window.';
+    case 'rate_limit':
+      return `${providerLabel}API rate limit reached. Please wait a moment and try again.`;
+    case 'billing':
+      return `${providerLabel}API key has run out of credits or has an insufficient balance. ` +
+        'Check your billing dashboard and top up, or switch to a different API key.';
+    case 'auth':
+      return `${providerLabel}API key is invalid or expired. ` +
+        'Check that your API key is correct in your environment variables.';
+    case 'timeout':
+      return 'LLM request timed out. Please try again.';
+    case 'overloaded':
+      return 'The AI service is temporarily overloaded. Please try again in a moment.';
+    case 'unknown':
+    default:
+      if (info?.message) {
+        const prefix = info.httpCode ? `HTTP ${info.httpCode}` : 'LLM error';
+        const type = info.type ? ` (${info.type})` : '';
+        const requestId = info.requestId ? ` [request_id: ${info.requestId}]` : '';
+        return `${prefix}${type}: ${info.message}${requestId}`;
+      }
+
+      if (raw.length > 300) {
+        return `${raw.slice(0, 300)}...`;
+      }
+
+      return raw;
+  }
+}

package/src/utils/history-context.ts

@@ -0,0 +1,32 @@
+export const HISTORY_CONTEXT_MARKER = '[Chat history for context]';
+export const CURRENT_MESSAGE_MARKER = '[Current message - respond to this]';
+export const DEFAULT_HISTORY_LIMIT = 10;
+export const FULL_ANSWER_TURNS = 3;
+
+export interface HistoryEntry {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+export function buildHistoryContext(params: {
+  entries: HistoryEntry[];
+  currentMessage: string;
+  lineBreak?: string;
+}): string {
+  const lineBreak = params.lineBreak ?? '\n';
+  if (params.entries.length === 0) {
+    return params.currentMessage;
+  }
+
+  const historyText = params.entries
+    .map(entry => `${entry.role === 'user' ? 'User' : 'Assistant'}: ${entry.content}`)
+    .join(`${lineBreak}${lineBreak}`);
+
+  return [
+    HISTORY_CONTEXT_MARKER,
+    historyText,
+    '',
+    CURRENT_MESSAGE_MARKER,
+    params.currentMessage,
+  ].join(lineBreak);
+}

package/src/utils/in-memory-chat-history.ts

@@ -0,0 +1,268 @@
+import { createHash } from 'crypto';
+import { callLlm, DEFAULT_MODEL } from '../model/llm.js';
+import {
+  DEFAULT_HISTORY_LIMIT,
+  FULL_ANSWER_TURNS,
+  type HistoryEntry,
+} from './history-context.js';
+import { z } from 'zod';
+
+/**
+ * Represents a single conversation turn (query + answer + summary)
+ */
+export interface Message {
+  id: number;
+  query: string;
+  answer: string | null;   // null until answer completes
+  summary: string | null;  // LLM-generated summary, null until answer arrives
+}
+
+/**
+ * Schema for LLM to select relevant messages
+ */
+export const SelectedMessagesSchema = z.object({
+  message_ids: z.array(z.number()).describe('List of relevant message IDs (0-indexed)'),
+});
+
+/**
+ * System prompt for generating message summaries
+ */
+const MESSAGE_SUMMARY_SYSTEM_PROMPT = `You are a concise summarizer. Generate brief summaries of conversation answers.
+Keep summaries to 1-2 sentences that capture the key information.`;
+
+/**
+ * System prompt for selecting relevant messages
+ */
+const MESSAGE_SELECTION_SYSTEM_PROMPT = `You are a relevance evaluator. Select which previous conversation messages are relevant to the current query.
+Return only message IDs that contain information directly useful for answering the current query.`;
+
+/**
+ * Manages in-memory conversation history for multi-turn conversations.
+ * Stores user queries, final answers, and LLM-generated summaries.
+ */
+export class InMemoryChatHistory {
+  private messages: Message[] = [];
+  private model: string;
+  private readonly maxTurns: number;
+  private relevantMessagesByQuery: Map<string, Message[]> = new Map();
+
+  constructor(model: string = DEFAULT_MODEL, maxTurns: number = DEFAULT_HISTORY_LIMIT) {
+    this.model = model;
+    this.maxTurns = maxTurns;
+  }
+
+  /**
+   * Hashes a query string for cache key generation
+   */
+  private hashQuery(query: string): string {
+    return createHash('md5').update(query).digest('hex').slice(0, 12);
+  }
+
+  /**
+   * Updates the model used for LLM calls (e.g., when user switches models)
+   */
+  setModel(model: string): void {
+    this.model = model;
+  }
+
+  /**
+   * Generates a brief summary of an answer for later relevance matching
+   */
+  private async generateSummary(query: string, answer: string): Promise<string> {
+    const answerPreview = answer.slice(0, 1500); // Limit for prompt size
+
+    const prompt = `Query: "${query}"
+Answer: "${answerPreview}"
+
+Generate a brief 1-2 sentence summary of this answer.`;
+
+    try {
+      const { response } = await callLlm(prompt, {
+        systemPrompt: MESSAGE_SUMMARY_SYSTEM_PROMPT,
+        model: this.model,
+      });
+      return typeof response === 'string' ? response.trim() : String(response).trim();
+    } catch {
+      // Fallback to a simple summary if LLM fails
+      return `Answer to: ${query.slice(0, 100)}`;
+    }
+  }
+
+  /**
+   * Saves a new user query to history immediately (before answer is available).
+   * Answer and summary are null until saveAnswer() is called with the answer.
+   */
+  saveUserQuery(query: string): void {
+    // Clear the relevance cache since message history has changed
+    this.relevantMessagesByQuery.clear();
+
+    this.messages.push({
+      id: this.messages.length,
+      query,
+      answer: null,
+      summary: null,
+    });
+  }
+
+  /**
+   * Saves the answer to the most recent message and generates a summary.
+   * Should be called when the agent completes answering.
+   */
+  async saveAnswer(answer: string): Promise<void> {
+    const lastMessage = this.messages[this.messages.length - 1];
+    if (!lastMessage || lastMessage.answer !== null) {
+      return; // No pending query or already has answer
+    }
+
+    lastMessage.answer = answer;
+    lastMessage.summary = await this.generateSummary(lastMessage.query, answer);
+  }
+
+  /**
+   * Uses LLM to select which messages are relevant to the current query.
+   * Results are cached by query hash to avoid redundant LLM calls within the same query.
+   * Only considers messages with completed answers for relevance selection.
+   */
+  async selectRelevantMessages(currentQuery: string): Promise<Message[]> {
+    // Only consider messages with completed answers
+    const completedMessages = this.messages.filter((m) => m.answer !== null);
+    if (completedMessages.length === 0) {
+      return [];
+    }
+
+    // Check cache first
+    const cacheKey = this.hashQuery(currentQuery);
+    const cached = this.relevantMessagesByQuery.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const messagesInfo = completedMessages.map((message) => ({
+      id: message.id,
+      query: message.query,
+      summary: message.summary,
+    }));
+
+    const prompt = `Current user query: "${currentQuery}"
+
+Previous conversations:
+${JSON.stringify(messagesInfo, null, 2)}
+
+Select which previous messages are relevant to understanding or answering the current query.`;
+
+    try {
+      const { response } = await callLlm(prompt, {
+        systemPrompt: MESSAGE_SELECTION_SYSTEM_PROMPT,
+        model: this.model,
+        outputSchema: SelectedMessagesSchema,
+      });
+
+      const selectedIds = (response as unknown as { message_ids: number[] }).message_ids || [];
+
+      const selectedMessages = selectedIds
+        .filter((idx) => idx >= 0 && idx < this.messages.length)
+        .map((idx) => this.messages[idx])
+        .filter((m) => m.answer !== null); // Ensure we only return completed messages
+
+      // Cache the result
+      this.relevantMessagesByQuery.set(cacheKey, selectedMessages);
+
+      return selectedMessages;
+    } catch {
+      // On failure, return empty (don't inject potentially irrelevant context)
+      return [];
+    }
+  }
+
+  /**
+   * Formats selected messages for task planning (queries + summaries only, lightweight)
+   */
+  formatForPlanning(messages: Message[]): string {
+    if (messages.length === 0) {
+      return '';
+    }
+
+    return messages
+      .map((message) => `User: ${message.query}\nAssistant: ${message.summary}`)
+      .join('\n\n');
+  }
+
+  /**
+   * Formats selected messages for answer generation (queries + full answers)
+   */
+  formatForAnswerGeneration(messages: Message[]): string {
+    if (messages.length === 0) {
+      return '';
+    }
+
+    return messages
+      .map((message) => `User: ${message.query}\nAssistant: ${message.answer}`)
+      .join('\n\n');
+  }
+
+  /**
+   * Returns all messages
+   */
+  getMessages(): Message[] {
+    return [...this.messages];
+  }
+
+  /**
+   * Returns user queries in chronological order (no LLM call)
+   */
+  getUserMessages(): string[] {
+    return this.messages.map((message) => message.query);
+  }
+
+  /**
+   * Returns recent completed turns as alternating user/assistant entries.
+   * Uses full answers for the most recent turns and summaries for older ones.
+   */
+  getRecentTurns(limit: number = this.maxTurns): HistoryEntry[] {
+    const boundedLimit = Math.max(0, limit);
+    if (boundedLimit === 0) {
+      return [];
+    }
+
+    const completedMessages = this.messages.filter((message) => message.answer !== null);
+    const recentMessages = completedMessages.slice(-boundedLimit);
+
+    return recentMessages.flatMap((message, index) => {
+      const isRecentTurn = index >= recentMessages.length - FULL_ANSWER_TURNS;
+      const assistantContent = isRecentTurn
+        ? message.answer
+        : (message.summary ?? message.answer);
+
+      return [
+        { role: 'user', content: message.query },
+        { role: 'assistant', content: assistantContent ?? '' },
+      ];
+    });
+  }
+
+  /**
+   * Returns true if there are any messages
+   */
+  hasMessages(): boolean {
+    return this.messages.length > 0;
+  }
+
+  /**
+   * Removes the last message from history and clears the relevance cache.
+   * Used to prune HEARTBEAT_OK turns that add no conversational value.
+   */
+  pruneLastTurn(): void {
+    if (this.messages.length > 0) {
+      this.messages.pop();
+      this.relevantMessagesByQuery.clear();
+    }
+  }
+
+  /**
+   * Clears all messages and cache
+   */
+  clear(): void {
+    this.messages = [];
+    this.relevantMessagesByQuery.clear();
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,28 @@
+export { loadConfig, saveConfig, getSetting, setSetting } from './config.js';
+export {
+  getApiKeyNameForProvider,
+  getProviderDisplayName,
+  checkApiKeyExistsForProvider,
+  saveApiKeyForProvider,
+} from './env.js';
+export { InMemoryChatHistory } from './in-memory-chat-history.js';
+export { logger } from './logger.js';
+export type { LogEntry, LogLevel } from './logger.js';
+export { extractTextContent, hasToolCalls } from './ai-message.js';
+export { LongTermChatHistory } from './long-term-chat-history.js';
+export type { ConversationEntry } from './long-term-chat-history.js';
+export { findPrevWordStart, findNextWordEnd } from './text-navigation.js';
+export { cursorHandlers } from './input-key-handlers.js';
+export type { CursorContext } from './input-key-handlers.js';
+export { getToolDescription } from './tool-description.js';
+export { transformMarkdownTables, formatResponse } from './markdown-table.js';
+export { estimateTokens, TOKEN_BUDGET } from './tokens.js';
+export {
+  parseApiErrorInfo,
+  classifyError,
+  isContextOverflowError,
+  isNonRetryableError,
+  formatUserFacingError,
+  ExitCode,
+  exitCodeFromError,
+} from './errors.js';

package/src/utils/input-key-handlers.ts

@@ -0,0 +1,64 @@
+import {
+  findPrevWordStart,
+  findNextWordEnd,
+  getLineAndColumn,
+  getCursorPosition,
+  getLineStart,
+  getLineEnd,
+  getLineCount,
+} from './text-navigation.js';
+
+/**
+ * Context needed for cursor position calculations
+ */
+export interface CursorContext {
+  text: string;
+  cursorPosition: number;
+}
+
+/**
+ * Pure functions for computing new cursor positions.
+ * Each function takes the current context and returns the new cursor position.
+ * For vertical movement (moveUp/moveDown), returns null if at boundary to signal
+ * that the caller should handle it (e.g., history navigation).
+ */
+export const cursorHandlers = {
+  /** Move cursor one character left */
+  moveLeft: (ctx: CursorContext): number =>
+    Math.max(0, ctx.cursorPosition - 1),
+
+  /** Move cursor one character right */
+  moveRight: (ctx: CursorContext): number =>
+    Math.min(ctx.text.length, ctx.cursorPosition + 1),
+
+  /** Move cursor to start of current line */
+  moveToLineStart: (ctx: CursorContext): number =>
+    getLineStart(ctx.text, ctx.cursorPosition),
+
+  /** Move cursor to end of current line */
+  moveToLineEnd: (ctx: CursorContext): number =>
+    getLineEnd(ctx.text, ctx.cursorPosition),
+
+  /** Move cursor up one line, maintaining column position. Returns null if on first line. */
+  moveUp: (ctx: CursorContext): number | null => {
+    const { line, column } = getLineAndColumn(ctx.text, ctx.cursorPosition);
+    if (line === 0) return null; // At first line, signal to caller
+    return getCursorPosition(ctx.text, line - 1, column);
+  },
+
+  /** Move cursor down one line, maintaining column position. Returns null if on last line. */
+  moveDown: (ctx: CursorContext): number | null => {
+    const { line, column } = getLineAndColumn(ctx.text, ctx.cursorPosition);
+    const lineCount = getLineCount(ctx.text);
+    if (line >= lineCount - 1) return null; // At last line, signal to caller
+    return getCursorPosition(ctx.text, line + 1, column);
+  },
+
+  /** Move cursor to start of previous word */
+  moveWordBackward: (ctx: CursorContext): number =>
+    findPrevWordStart(ctx.text, ctx.cursorPosition),
+
+  /** Move cursor to end of next word */
+  moveWordForward: (ctx: CursorContext): number =>
+    findNextWordEnd(ctx.text, ctx.cursorPosition),
+};