kalshi-trading-bot-cli 2.1.0

package/src/gateway/group/mention-detection.ts

@@ -0,0 +1,42 @@
+/**
+ * Detect if the bot was @-mentioned in a group message.
+ */
+export function isBotMentioned(params: {
+  mentionedJids?: string[];
+  selfJid?: string | null;
+  selfLid?: string | null;
+  selfE164?: string | null;
+  body: string;
+}): boolean {
+  const { mentionedJids, selfJid, selfLid, selfE164, body } = params;
+
+  if (mentionedJids?.length) {
+    // Collect all known base identifiers for the bot (phone JID + LID)
+    const selfBases = new Set<string>();
+    for (const id of [selfJid, selfLid]) {
+      if (id) {
+        const base = id.split('@')[0]?.split(':')[0];
+        if (base) selfBases.add(base);
+      }
+    }
+
+    if (selfBases.size > 0) {
+      for (const jid of mentionedJids) {
+        const base = jid.split('@')[0]?.split(':')[0];
+        if (base && selfBases.has(base)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  // Fallback: check if bot's phone digits appear in message body
+  if (selfE164) {
+    const digits = selfE164.replace(/\D/g, '');
+    if (digits.length >= 7 && body.includes(digits)) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/gateway/heartbeat/index.ts

@@ -0,0 +1,8 @@
+export { startHeartbeatRunner, type HeartbeatRunner } from './runner.js';
+export { buildHeartbeatQuery, loadHeartbeatDocument, isHeartbeatContentEmpty } from './prompt.js';
+export {
+  HEARTBEAT_OK_TOKEN,
+  evaluateSuppression,
+  type SuppressionResult,
+  type SuppressionState,
+} from './suppression.js';

package/src/gateway/heartbeat/prompt.ts

@@ -0,0 +1,73 @@
+import { readFile } from 'node:fs/promises';
+import { HEARTBEAT_OK_TOKEN } from './suppression.js';
+import { appPath } from '../../utils/paths.js';
+
+const HEARTBEAT_MD_PATH = appPath('HEARTBEAT.md');
+
+const DEFAULT_CHECKLIST = `- Major index moves (S&P 500, NASDAQ, Dow) — alert if any move more than 2% in a session
+- Breaking financial news — major earnings surprises, Fed announcements, significant market events`;
+
+/**
+ * Load HEARTBEAT.md content from the app directory.
+ * Returns the content string, or null if the file doesn't exist.
+ */
+export async function loadHeartbeatDocument(): Promise<string | null> {
+  try {
+    return await readFile(HEARTBEAT_MD_PATH, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if heartbeat content is effectively empty
+ * (only headers, whitespace, or empty list items).
+ */
+export function isHeartbeatContentEmpty(content: string): boolean {
+  const lines = content.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip empty lines, headers, and empty list items
+    if (!trimmed) continue;
+    if (/^#+\s*$/.test(trimmed)) continue;
+    if (/^#+\s/.test(trimmed)) continue;
+    if (/^[-*]\s*$/.test(trimmed)) continue;
+    // Non-empty content found
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Build the heartbeat query to send to the agent.
+ * Returns null if the file exists but is empty (skip heartbeat).
+ * Uses a default checklist if no file exists.
+ */
+export async function buildHeartbeatQuery(): Promise<string | null> {
+  const content = await loadHeartbeatDocument();
+
+  let checklist: string;
+  if (content !== null) {
+    if (isHeartbeatContentEmpty(content)) {
+      return null; // File exists but is empty — skip heartbeat
+    }
+    checklist = content;
+  } else {
+    checklist = DEFAULT_CHECKLIST;
+  }
+
+  return `[HEARTBEAT CHECK]
+
+You are running as a periodic heartbeat. Review the following checklist and check if anything noteworthy has happened that the user should know about.
+
+## Checklist
+${checklist}
+
+## Instructions
+- Use your tools to check each item on the checklist
+- If you find something noteworthy, write a concise alert message for the user
+- If nothing noteworthy is happening, respond with exactly: ${HEARTBEAT_OK_TOKEN}
+- Do NOT send a message just to say "everything is fine" — only message if there's something actionable or noteworthy
+- Keep alerts brief and focused — lead with the key finding
+- You may combine multiple findings into one message`;
+}

package/src/gateway/heartbeat/runner.ts

@@ -0,0 +1,200 @@
+import { appendFileSync } from 'node:fs';
+import { loadGatewayConfig } from '../config.js';
+import { runAgentForMessage } from '../agent-runner.js';
+import { assertOutboundAllowed, sendMessageWhatsApp } from '../channels/whatsapp/index.js';
+import { resolveSessionStorePath, loadSessionStore, type SessionEntry } from '../sessions/store.js';
+import { cleanMarkdownForWhatsApp } from '../utils.js';
+import { buildHeartbeatQuery } from './prompt.js';
+import { evaluateSuppression, type SuppressionState } from './suppression.js';
+import { appPath } from '../../utils/paths.js';
+import { getSetting } from '../../utils/config.js';
+
+const LOG_PATH = appPath('gateway-debug.log');
+
+function debugLog(msg: string) {
+  appendFileSync(LOG_PATH, `${new Date().toISOString()} ${msg}\n`);
+}
+
+/**
+ * Check if the current time is within the configured active hours and days.
+ * Defaults to NYSE market hours: 9:30 AM - 4:00 PM ET, Mon-Fri.
+ */
+function isWithinActiveHours(activeHours?: {
+  start: string;
+  end: string;
+  timezone?: string;
+  daysOfWeek?: number[];
+}): boolean {
+  if (!activeHours) return true;
+
+  const tz = activeHours.timezone ?? 'America/New_York';
+  const now = new Date();
+
+  // Check day of week (0=Sun, 1=Mon, ..., 6=Sat)
+  const allowedDays = activeHours.daysOfWeek ?? [1, 2, 3, 4, 5];
+  const dayFormatter = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    weekday: 'short',
+  });
+  const dayStr = dayFormatter.format(now);
+  const dayMap: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  const currentDay = dayMap[dayStr] ?? new Date().getDay();
+  if (!allowedDays.includes(currentDay)) {
+    return false;
+  }
+
+  // Check time window
+  const timeFormatter = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  });
+  const currentTime = timeFormatter.format(now); // "HH:MM"
+
+  return currentTime >= activeHours.start && currentTime <= activeHours.end;
+}
+
+/**
+ * Find the most recently updated session that has a delivery target (lastTo).
+ */
+function findTargetSession(): SessionEntry | null {
+  const storePath = resolveSessionStorePath('default');
+  const store = loadSessionStore(storePath);
+  const entries = Object.values(store).filter((e) => e.lastTo);
+
+  if (entries.length === 0) return null;
+
+  // Sort by updatedAt descending, return the most recent
+  entries.sort((a, b) => b.updatedAt - a.updatedAt);
+  return entries[0];
+}
+
+export type HeartbeatRunner = {
+  stop: () => void;
+};
+
+/**
+ * Start the heartbeat runner. Schedules periodic heartbeat checks using setTimeout.
+ * Re-reads config each cycle so changes take effect without restart.
+ * First tick fires after one full interval (no startup burst).
+ */
+export function startHeartbeatRunner(params: { configPath?: string }): HeartbeatRunner {
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let running = false;
+  const suppressionState: SuppressionState = {
+    lastMessageText: null,
+    lastMessageAt: null,
+  };
+
+  async function tick(): Promise<void> {
+    if (stopped || running) return;
+    running = true;
+
+    try {
+      const cfg = loadGatewayConfig(params.configPath);
+      const heartbeatCfg = cfg.gateway.heartbeat;
+
+      // Check if enabled
+      if (!heartbeatCfg?.enabled) {
+        debugLog('[heartbeat] disabled in config, skipping');
+        return;
+      }
+
+      // Check active hours
+      if (!isWithinActiveHours(heartbeatCfg.activeHours)) {
+        debugLog('[heartbeat] outside active hours, skipping');
+        return;
+      }
+
+      // Find target session
+      const session = findTargetSession();
+      if (!session || !session.lastTo || !session.lastAccountId) {
+        debugLog('[heartbeat] no target session found (user has not messaged yet), skipping');
+        return;
+      }
+
+      // Verify outbound is allowed
+      try {
+        assertOutboundAllowed({ to: session.lastTo, accountId: session.lastAccountId });
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        debugLog(`[heartbeat] outbound BLOCKED: ${msg}`);
+        return;
+      }
+
+      // Build heartbeat query
+      const query = await buildHeartbeatQuery();
+      if (query === null) {
+        debugLog('[heartbeat] HEARTBEAT.md exists but is empty, skipping');
+        return;
+      }
+
+      // Run agent
+      debugLog(`[heartbeat] running agent for session=${session.sessionKey}`);
+      const model = heartbeatCfg.model ?? getSetting('modelId', 'gpt-5.4') as string;
+      const modelProvider = heartbeatCfg.modelProvider ?? getSetting('provider', 'openai') as string;
+      const answer = await runAgentForMessage({
+        sessionKey: session.sessionKey,
+        query,
+        model,
+        modelProvider,
+        maxIterations: heartbeatCfg.maxIterations,
+        isHeartbeat: true,
+        channel: 'whatsapp',
+      });
+      debugLog(`[heartbeat] agent answer length=${answer.length}`);
+
+      // Evaluate suppression
+      const result = evaluateSuppression(answer, suppressionState);
+      debugLog(`[heartbeat] suppression: shouldSuppress=${result.shouldSuppress} reason=${result.reason}`);
+
+      if (!result.shouldSuppress) {
+        const cleaned = cleanMarkdownForWhatsApp(result.cleanedText);
+        await sendMessageWhatsApp({
+          to: session.lastTo,
+          body: cleaned,
+          accountId: session.lastAccountId,
+        });
+        debugLog(`[heartbeat] sent message to ${session.lastTo}`);
+
+        // Update suppression state for duplicate detection
+        suppressionState.lastMessageText = result.cleanedText;
+        suppressionState.lastMessageAt = Date.now();
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      debugLog(`[heartbeat] ERROR: ${msg}`);
+    } finally {
+      running = false;
+      scheduleNext();
+    }
+  }
+
+  function scheduleNext(): void {
+    if (stopped) return;
+
+    // Re-read config for interval (may have changed)
+    const cfg = loadGatewayConfig(params.configPath);
+    const intervalMs = (cfg.gateway.heartbeat?.intervalMinutes ?? 30) * 60 * 1000;
+
+    timer = setTimeout(() => void tick(), intervalMs);
+    timer.unref(); // Don't block shutdown
+  }
+
+  // Schedule first tick after one full interval (no startup burst)
+  debugLog('[heartbeat] runner started');
+  scheduleNext();
+
+  return {
+    stop() {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      debugLog('[heartbeat] runner stopped');
+    },
+  };
+}

package/src/gateway/heartbeat/suppression.ts

@@ -0,0 +1,74 @@
+export const HEARTBEAT_OK_TOKEN = 'HEARTBEAT_OK';
+
+type SuppressionReason = 'ok-token' | 'empty' | 'duplicate' | 'none';
+
+export type SuppressionResult = {
+  shouldSuppress: boolean;
+  cleanedText: string;
+  reason: SuppressionReason;
+};
+
+export type SuppressionState = {
+  lastMessageText: string | null;
+  lastMessageAt: number | null;
+};
+
+const DUPLICATE_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Strip the HEARTBEAT_OK token from text, handling bold markdown wrappers
+ * and trailing punctuation.
+ */
+function stripOkToken(text: string): string {
+  // Match HEARTBEAT_OK with optional bold wrappers (**) and trailing punctuation
+  const pattern = /^\s*(?:\*\*)?HEARTBEAT_OK(?:\*\*)?[.!]?\s*|\s*(?:\*\*)?HEARTBEAT_OK(?:\*\*)?[.!]?\s*$/gi;
+  return text.replace(pattern, '').trim();
+}
+
+/**
+ * Check if the text is essentially just the HEARTBEAT_OK token
+ * (possibly with bold wrappers and punctuation).
+ */
+function isJustOkToken(text: string): boolean {
+  const stripped = text.trim();
+  return /^(?:\*\*)?HEARTBEAT_OK(?:\*\*)?[.!]?\s*$/.test(stripped);
+}
+
+/**
+ * Evaluate whether a heartbeat response should be suppressed.
+ */
+export function evaluateSuppression(
+  text: string,
+  state: SuppressionState,
+): SuppressionResult {
+  const trimmed = text.trim();
+
+  // Empty response
+  if (!trimmed) {
+    return { shouldSuppress: true, cleanedText: '', reason: 'empty' };
+  }
+
+  // Response is just the HEARTBEAT_OK token
+  if (isJustOkToken(trimmed)) {
+    return { shouldSuppress: true, cleanedText: '', reason: 'ok-token' };
+  }
+
+  // Strip token from start/end if it appears alongside other content
+  const cleaned = stripOkToken(trimmed);
+
+  if (!cleaned) {
+    return { shouldSuppress: true, cleanedText: '', reason: 'ok-token' };
+  }
+
+  // Duplicate suppression: same text within 24h
+  if (
+    state.lastMessageText !== null &&
+    state.lastMessageAt !== null &&
+    Date.now() - state.lastMessageAt < DUPLICATE_WINDOW_MS &&
+    cleaned === state.lastMessageText
+  ) {
+    return { shouldSuppress: true, cleanedText: cleaned, reason: 'duplicate' };
+  }
+
+  return { shouldSuppress: false, cleanedText: cleaned, reason: 'none' };
+}

package/src/gateway/index.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env tsx
+import { existsSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import util from 'node:util';
+import {
+  resolveWhatsAppAccount,
+  loadGatewayConfig,
+  saveGatewayConfig,
+  getGatewayConfigPath,
+  type GatewayConfig,
+} from './config.js';
+import { loginWhatsApp } from './channels/whatsapp/login.js';
+import { startGateway } from './gateway.js';
+
+// Suppress noisy Baileys Signal protocol session logs
+const SUPPRESSED_PREFIXES = [
+  'Closing session:',
+  'Opening session:',
+  'Removing old closed session:',
+  'Session already closed',
+  'Session already open',
+];
+
+const originalLog = console.log;
+console.log = (...args: unknown[]) => {
+  const formatted = util.format(...args);
+  if (SUPPRESSED_PREFIXES.some((prefix) => formatted.startsWith(prefix))) {
+    return;
+  }
+  originalLog.apply(console, args);
+};
+
+const E164_RE = /^\+\d{7,15}$/;
+
+async function promptSetupMode(cfg: GatewayConfig, linkedPhone: string): Promise<void> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    console.log('');
+    console.log(`Linked phone: ${linkedPhone}`);
+    console.log('');
+    console.log('How will you use the bot with WhatsApp?');
+    console.log('  1) Self-chat  — message yourself to talk to the bot');
+    console.log('  2) Bot phone  — this is a dedicated bot phone, others message it');
+
+    let mode = '';
+    while (mode !== '1' && mode !== '2') {
+      mode = (await rl.question('\nChoose (1 or 2): ')).trim();
+    }
+
+    const accountId = cfg.gateway.accountId ?? 'default';
+
+    if (mode === '1') {
+      cfg.channels.whatsapp.allowFrom = [linkedPhone];
+      return;
+    }
+
+    // Bot mode: collect allowed sender phone numbers
+    console.log('');
+    console.log('Enter the phone number(s) allowed to message the bot (E.164 format, e.g. +15551234567).');
+    console.log('Separate multiple numbers with commas, or type * to allow anyone.');
+
+    let phones: string[] = [];
+    while (phones.length === 0) {
+      const input = (await rl.question('Allowed number(s): ')).trim();
+      if (!input) continue;
+
+      if (input === '*') {
+        phones = ['*'];
+        break;
+      }
+
+      phones = input.split(',').map((s) => s.trim()).filter(Boolean);
+      const invalid = phones.filter((p) => !E164_RE.test(p));
+      if (invalid.length > 0) {
+        console.log(`Invalid format: ${invalid.join(', ')}. Use E.164 format (e.g. +15551234567).`);
+        phones = [];
+      }
+    }
+
+    cfg.channels.whatsapp.accounts[accountId] = {
+      enabled: true,
+      dmPolicy: 'allowlist',
+      allowFrom: phones,
+      groupPolicy: 'disabled',
+      groupAllowFrom: [],
+      sendReadReceipts: true,
+    };
+    cfg.channels.whatsapp.allowFrom = phones;
+  } finally {
+    rl.close();
+  }
+}
+
+async function run(): Promise<void> {
+  const args = process.argv.slice(2);
+  const command = args[0] ?? 'run';
+
+  if (command === 'login') {
+    const cfg = loadGatewayConfig();
+    const accountId = cfg.gateway.accountId ?? 'default';
+    const account = resolveWhatsAppAccount(cfg, accountId);
+    const result = await loginWhatsApp({ authDir: account.authDir });
+
+    const configPath = getGatewayConfigPath();
+    const configExists = existsSync(configPath);
+
+    if (result.phone && (!configExists || cfg.channels.whatsapp.allowFrom.length === 0)) {
+      await promptSetupMode(cfg, result.phone);
+      saveGatewayConfig(cfg);
+      console.log(`Saved gateway config to ${configPath}`);
+    } else if (result.phone && configExists) {
+      const currentAllowFrom = cfg.channels.whatsapp.allowFrom;
+      if (!currentAllowFrom.includes(result.phone)) {
+        console.log(`Config already exists at ${configPath} — no changes made.`);
+        console.log(`Linked phone ${result.phone} is not in allowFrom. Edit the config if needed.`);
+      }
+    } else if (!configExists) {
+      saveGatewayConfig(cfg);
+      console.log(`Created default config at ${configPath}`);
+      console.log('Add your phone number to channels.whatsapp.allowFrom to receive messages.');
+    }
+    return;
+  }
+
+  const server = await startGateway();
+  console.log('Gateway running. Press Ctrl+C to stop.');
+
+  const shutdown = async () => {
+    await server.stop();
+    process.exit(0);
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+}
+
+void run();
+

package/src/gateway/routing/resolve-route.ts

@@ -0,0 +1,119 @@
+import type { GatewayConfig } from '../config.js';
+
+export type RoutePeer = {
+  kind: 'direct' | 'group';
+  id: string;
+};
+
+export type ResolvedRoute = {
+  agentId: string;
+  channel: string;
+  accountId: string;
+  sessionKey: string;
+  mainSessionKey: string;
+  matchedBy: 'binding.peer' | 'binding.account' | 'binding.channel' | 'default';
+};
+
+const DEFAULT_AGENT_ID = 'default';
+const DEFAULT_ACCOUNT_ID = 'default';
+
+function normalizeToken(value: string | null | undefined): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+export function buildSessionKey(params: {
+  agentId: string;
+  channel: string;
+  accountId: string;
+  peer?: RoutePeer | null;
+}): string {
+  const channel = normalizeToken(params.channel);
+  const accountId = params.accountId.trim() || DEFAULT_ACCOUNT_ID;
+  if (!params.peer) {
+    return `agent:${params.agentId}:main`;
+  }
+  const peerKind = params.peer.kind;
+  const peerId = params.peer.id.trim().toLowerCase();
+  return `agent:${params.agentId}:${channel}:${accountId}:${peerKind}:${peerId}`;
+}
+
+export function resolveRoute(input: {
+  cfg: GatewayConfig;
+  channel: string;
+  accountId?: string | null;
+  peer?: RoutePeer | null;
+}): ResolvedRoute {
+  const channel = normalizeToken(input.channel);
+  const accountId = (input.accountId ?? DEFAULT_ACCOUNT_ID).trim() || DEFAULT_ACCOUNT_ID;
+  const peer = input.peer ? { kind: input.peer.kind, id: input.peer.id.trim() } : null;
+
+  const bindings = input.cfg.bindings.filter((binding) => {
+    if (normalizeToken(binding.match.channel) !== channel) {
+      return false;
+    }
+    if (binding.match.accountId && binding.match.accountId !== '*' && binding.match.accountId !== accountId) {
+      return false;
+    }
+    return true;
+  });
+
+  if (peer) {
+    const peerMatch = bindings.find(
+      (binding) => binding.match.peerKind === peer.kind && binding.match.peerId === peer.id,
+    );
+    if (peerMatch) {
+      const agentId = peerMatch.agentId.trim() || DEFAULT_AGENT_ID;
+      return {
+        agentId,
+        channel,
+        accountId,
+        sessionKey: buildSessionKey({ agentId, channel, accountId, peer }),
+        mainSessionKey: buildSessionKey({ agentId, channel, accountId, peer: null }),
+        matchedBy: 'binding.peer',
+      };
+    }
+  }
+
+  const accountMatch = bindings.find(
+    (binding) => Boolean(binding.match.accountId) && !binding.match.peerId,
+  );
+  if (accountMatch) {
+    const agentId = accountMatch.agentId.trim() || DEFAULT_AGENT_ID;
+    return {
+      agentId,
+      channel,
+      accountId,
+      sessionKey: buildSessionKey({ agentId, channel, accountId, peer }),
+      mainSessionKey: buildSessionKey({ agentId, channel, accountId, peer: null }),
+      matchedBy: 'binding.account',
+    };
+  }
+
+  const channelMatch = bindings.find((binding) => !binding.match.accountId && !binding.match.peerId);
+  if (channelMatch) {
+    const agentId = channelMatch.agentId.trim() || DEFAULT_AGENT_ID;
+    return {
+      agentId,
+      channel,
+      accountId,
+      sessionKey: buildSessionKey({ agentId, channel, accountId, peer }),
+      mainSessionKey: buildSessionKey({ agentId, channel, accountId, peer: null }),
+      matchedBy: 'binding.channel',
+    };
+  }
+
+  return {
+    agentId: DEFAULT_AGENT_ID,
+    channel,
+    accountId,
+    sessionKey: buildSessionKey({ agentId: DEFAULT_AGENT_ID, channel, accountId, peer }),
+    mainSessionKey: buildSessionKey({
+      agentId: DEFAULT_AGENT_ID,
+      channel,
+      accountId,
+      peer: null,
+    }),
+    matchedBy: 'default',
+  };
+}
+