@thesammykins/tether 1.0.0

package/src/db.ts

@@ -0,0 +1,123 @@
+/**
+ * Database - SQLite for thread → session mappings
+ *
+ * Simple key-value store:
+ * - thread_id (Discord thread ID)
+ * - session_id (Claude session UUID)
+ *
+ * When a follow-up message comes in a thread, we look up
+ * the session ID to use --resume.
+ */
+
+import { Database } from 'bun:sqlite';
+
+const DB_PATH = process.env.DB_PATH || './data/threads.db';
+
+// Ensure data directory exists
+import { mkdirSync } from 'fs';
+import { dirname } from 'path';
+try {
+    mkdirSync(dirname(DB_PATH), { recursive: true });
+} catch {}
+
+// Open database
+export const db = new Database(DB_PATH);
+
+// Create tables if they don't exist
+db.run(`
+    CREATE TABLE IF NOT EXISTS threads (
+        thread_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    )
+`);
+
+// Create channels config table
+db.run(`
+    CREATE TABLE IF NOT EXISTS channels (
+        channel_id TEXT PRIMARY KEY,
+        working_dir TEXT,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    )
+`);
+
+// Add working_dir column to threads table (migration)
+try {
+    db.run(`ALTER TABLE threads ADD COLUMN working_dir TEXT`);
+} catch {} // Column may already exist
+
+// Create index for faster lookups
+db.run(`
+    CREATE INDEX IF NOT EXISTS idx_threads_session
+    ON threads(session_id)
+`);
+
+// Create paused_threads table
+db.run(`
+    CREATE TABLE IF NOT EXISTS paused_threads (
+        thread_id TEXT PRIMARY KEY,
+        paused_at INTEGER NOT NULL,
+        paused_by TEXT
+    )
+`);
+
+// Create held_messages table
+db.run(`
+    CREATE TABLE IF NOT EXISTS held_messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        thread_id TEXT NOT NULL,
+        author_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+    )
+`);
+
+// Create rate_limits table
+db.run(`
+    CREATE TABLE IF NOT EXISTS rate_limits (
+        user_id TEXT NOT NULL,
+        timestamp INTEGER NOT NULL
+    )
+`);
+
+// Create index for rate limit cleanup
+db.run(`
+    CREATE INDEX IF NOT EXISTS idx_rate_limits_timestamp
+    ON rate_limits(timestamp)
+`);
+
+console.log(`[db] SQLite database ready at ${DB_PATH}`);
+
+// In-memory cache for channel configs (TTL: 5 minutes)
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const channelConfigCache = new Map<string, { data: { working_dir: string | null } | null; expiresAt: number }>();
+
+// Helper functions for channel config
+function getChannelConfig(channelId: string): { working_dir: string | null } | null {
+    return db.query('SELECT working_dir FROM channels WHERE channel_id = ?')
+        .get(channelId) as { working_dir: string | null } | null;
+}
+
+export function getChannelConfigCached(channelId: string): { working_dir: string | null } | null {
+    const cached = channelConfigCache.get(channelId);
+    const now = Date.now();
+
+    if (cached && cached.expiresAt > now) {
+        return cached.data;
+    }
+
+    // Cache miss or expired - fetch from DB
+    const data = getChannelConfig(channelId);
+    channelConfigCache.set(channelId, { data, expiresAt: now + CACHE_TTL_MS });
+    return data;
+}
+
+export function setChannelConfig(channelId: string, workingDir: string): void {
+    db.run(`
+        INSERT INTO channels (channel_id, working_dir) VALUES (?, ?)
+        ON CONFLICT(channel_id) DO UPDATE SET working_dir = ?, updated_at = CURRENT_TIMESTAMP
+    `, [channelId, workingDir, workingDir]);
+
+    // Invalidate cache
+    channelConfigCache.delete(channelId);
+}

package/src/discord.ts

@@ -0,0 +1,80 @@
+/**
+ * Discord utilities - Helper functions for posting to Discord
+ *
+ * Separated from bot.ts so the worker can send messages
+ * without importing the full client.
+ */
+
+const DISCORD_BOT_TOKEN = process.env.DISCORD_BOT_TOKEN;
+
+if (!DISCORD_BOT_TOKEN) {
+    console.warn('[discord] DISCORD_BOT_TOKEN not set - sendToThread will fail');
+}
+
+/**
+ * Send a message to a Discord thread
+ *
+ * Uses the REST API directly so we don't need the gateway client
+ */
+export async function sendToThread(threadId: string, content: string): Promise<void> {
+    // Discord message limit is 2000 chars
+    const MAX_LENGTH = 2000;
+
+    // Split long messages
+    const chunks: string[] = [];
+    let remaining = content;
+
+    while (remaining.length > 0) {
+        if (remaining.length <= MAX_LENGTH) {
+            chunks.push(remaining);
+            break;
+        }
+
+        // Find a good split point (newline or space)
+        let splitAt = remaining.lastIndexOf('\n', MAX_LENGTH);
+        if (splitAt === -1 || splitAt < MAX_LENGTH / 2) {
+            splitAt = remaining.lastIndexOf(' ', MAX_LENGTH);
+        }
+        if (splitAt === -1 || splitAt < MAX_LENGTH / 2) {
+            splitAt = MAX_LENGTH;
+        }
+
+        chunks.push(remaining.slice(0, splitAt));
+        remaining = remaining.slice(splitAt).trim();
+    }
+
+    // Send each chunk
+    for (const chunk of chunks) {
+        const response = await fetch(
+            `https://discord.com/api/v10/channels/${threadId}/messages`,
+            {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bot ${DISCORD_BOT_TOKEN}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ content: chunk }),
+            }
+        );
+
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Discord API error: ${response.status} ${error}`);
+        }
+    }
+}
+
+/**
+ * Send typing indicator to a thread
+ */
+export async function sendTyping(channelId: string): Promise<void> {
+    await fetch(
+        `https://discord.com/api/v10/channels/${channelId}/typing`,
+        {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bot ${DISCORD_BOT_TOKEN}`,
+            },
+        }
+    );
+}

package/src/features/ack.ts

@@ -0,0 +1,10 @@
+import type { Message } from 'discord.js';
+
+export async function acknowledgeMessage(message: Message): Promise<void> {
+  try {
+    // React with 👀 to show the bot has seen the message
+    await message.react('👀');
+  } catch {
+    // Silently fail if we can't react (permissions, etc.)
+  }
+}

package/src/features/brb.ts

@@ -0,0 +1,79 @@
+/**
+ * BRB (Be Right Back) state management
+ * 
+ * Tracks which threads/DM channels have users who are temporarily away.
+ * State is ephemeral (in-memory) - if bot restarts, all users are assumed back.
+ */
+
+// In-memory storage of away thread IDs
+const awayThreads = new Set<string>();
+
+/**
+ * Mark a thread as user-away
+ */
+export function setBrb(threadId: string): void {
+  awayThreads.add(threadId);
+}
+
+/**
+ * Mark a thread as user-returned
+ */
+export function setBack(threadId: string): void {
+  awayThreads.delete(threadId);
+}
+
+/**
+ * Check if user is away in a thread
+ */
+export function isAway(threadId: string): boolean {
+  return awayThreads.has(threadId);
+}
+
+/**
+ * Get all away threads (for diagnostics)
+ */
+export function getAwayThreads(): string[] {
+  return Array.from(awayThreads);
+}
+
+/**
+ * Check if message content indicates user is going away
+ * Matches: 'brb', 'be right back', 'afk', 'stepping away'
+ */
+export function isBrbMessage(content: string): boolean {
+  const normalized = content.trim().toLowerCase();
+  
+  if (normalized === '') {
+    return false;
+  }
+  
+  const patterns = [
+    'brb',
+    'be right back',
+    'afk',
+    'stepping away',
+  ];
+  
+  return patterns.includes(normalized);
+}
+
+/**
+ * Check if message content indicates user is back
+ * Matches: 'back', 'im back', "i'm back", 'here'
+ */
+export function isBackMessage(content: string): boolean {
+  const normalized = content.trim().toLowerCase();
+  
+  if (normalized === '') {
+    return false;
+  }
+  
+  const patterns = [
+    'back',
+    'im back',
+    "i'm back",
+    'here',
+  ];
+  
+  return patterns.includes(normalized);
+}

package/src/features/channel-context.ts

@@ -0,0 +1,23 @@
+import type { TextChannel, ThreadChannel } from 'discord.js';
+
+const MAX_CONTEXT_MESSAGES = 10;
+
+export async function getChannelContext(channel: TextChannel | ThreadChannel): Promise<string> {
+  try {
+    const messages = await channel.messages.fetch({ limit: MAX_CONTEXT_MESSAGES });
+    
+    if (messages.size === 0) return '';
+    
+    // Build context string from most recent messages (reversed to chronological)
+    const contextLines = Array.from(messages.values())
+      .reverse()
+      .filter(m => m.content && m.content.trim().length > 0)
+      .map(m => `${m.author.tag}: ${m.content}`);
+    
+    if (contextLines.length === 0) return '';
+    
+    return `Recent channel context:\n${contextLines.join('\n')}`;
+  } catch {
+    return ''; // Fail silently — context is optional
+  }
+}

package/src/features/pause-resume.ts

@@ -0,0 +1,86 @@
+/**
+ * Pause/Resume - Manage thread pausing and message queueing
+ * 
+ * Keywords:
+ * - pause, stop, hold (or with ! prefix)
+ * - resume, continue, unpause (or with ! prefix)
+ * 
+ * When paused, messages are stored in held_messages table.
+ * When resumed, held messages can be retrieved via getHeldMessages().
+ */
+
+import type { Message } from 'discord.js';
+import { db } from '../db.js';
+
+const PAUSE_KEYWORDS = ['pause', 'stop', 'hold'];
+const RESUME_KEYWORDS = ['resume', 'continue', 'unpause'];
+
+export function handlePauseResume(message: Message): { paused: boolean } {
+  const content = message.content.toLowerCase().trim();
+  const threadId = message.channel.isThread() ? message.channel.id : null;
+  
+  if (!threadId) return { paused: false }; // Only works in threads
+  
+  // Check for resume command
+  if (RESUME_KEYWORDS.some(kw => content === kw || content === `!${kw}`)) {
+    resumeThread(threadId);
+    // Don't mark as paused — let the message through to process held messages
+    return { paused: false };
+  }
+  
+  // Check for pause command
+  if (PAUSE_KEYWORDS.some(kw => content === kw || content === `!${kw}`)) {
+    pauseThread(threadId, message.author.id);
+    return { paused: true };
+  }
+  
+  // Check if thread is currently paused
+  if (isThreadPaused(threadId)) {
+    // Hold this message
+    holdMessage(threadId, message.author.id, message.content);
+    return { paused: true };
+  }
+  
+  return { paused: false };
+}
+
+function isThreadPaused(threadId: string): boolean {
+  const row = db.query('SELECT 1 FROM paused_threads WHERE thread_id = ?').get(threadId);
+  return !!row;
+}
+
+function pauseThread(threadId: string, userId: string): void {
+  db.run(
+    'INSERT OR REPLACE INTO paused_threads (thread_id, paused_at, paused_by) VALUES (?, ?, ?)',
+    [threadId, Date.now(), userId]
+  );
+}
+
+function resumeThread(threadId: string): void {
+  db.run('DELETE FROM paused_threads WHERE thread_id = ?', [threadId]);
+  // Held messages remain in the table — they can be processed by the caller
+}
+
+function holdMessage(threadId: string, authorId: string, content: string): void {
+  db.run(
+    'INSERT INTO held_messages (thread_id, author_id, content, created_at) VALUES (?, ?, ?, ?)',
+    [threadId, authorId, content, Date.now()]
+  );
+}
+
+// Exported for use by bot when resuming
+export function getHeldMessages(threadId: string): Array<{ author_id: string; content: string }> {
+  const rows = db.query(
+    'SELECT author_id, content FROM held_messages WHERE thread_id = ? ORDER BY created_at ASC'
+  ).all(threadId) as Array<{ author_id: string; content: string }>;
+  
+  // Clear held messages after retrieval
+  db.run('DELETE FROM held_messages WHERE thread_id = ?', [threadId]);
+  
+  return rows;
+}
+
+// Exported for testing
+export function isThreadPausedExport(threadId: string): boolean {
+  return isThreadPaused(threadId);
+}

package/src/features/session-limits.ts

@@ -0,0 +1,48 @@
+/**
+ * Session Limits - Track turns per session and session duration
+ * 
+ * Enforces:
+ * - MAX_TURNS_PER_SESSION: Maximum messages in a thread (0 = disabled)
+ * - MAX_SESSION_DURATION_MS: Maximum session lifetime (0 = disabled)
+ */
+
+import { db } from '../db.js';
+
+// In-memory turn counter: threadId -> turn count
+const turnCounts = new Map<string, number>();
+
+export function checkSessionLimits(threadId: string): boolean {
+  const MAX_TURNS = parseInt(process.env.MAX_TURNS_PER_SESSION || '50');
+  const MAX_DURATION_MS = parseInt(process.env.MAX_SESSION_DURATION_MS || '3600000');
+  
+  if (MAX_TURNS <= 0 && MAX_DURATION_MS <= 0) return true; // Disabled
+  
+  // Check turn limit
+  if (MAX_TURNS > 0) {
+    const turns = (turnCounts.get(threadId) || 0) + 1;
+    turnCounts.set(threadId, turns);
+    if (turns > MAX_TURNS) return false;
+  }
+  
+  // Check duration limit
+  if (MAX_DURATION_MS > 0) {
+    const thread = db.query('SELECT created_at FROM threads WHERE thread_id = ?')
+      .get(threadId) as { created_at: string } | null;
+    
+    if (thread) {
+      const created = new Date(thread.created_at).getTime();
+      if (Date.now() - created > MAX_DURATION_MS) return false;
+    }
+  }
+  
+  return true;
+}
+
+// Exported for testing
+export function resetSessionLimits(): void {
+  turnCounts.clear();
+}
+
+export function getSessionTurns(threadId: string): number {
+  return turnCounts.get(threadId) || 0;
+}

package/src/features/thread-naming.ts

@@ -0,0 +1,33 @@
+const MAX_THREAD_NAME_LENGTH = 80;
+
+export function generateThreadName(content: string): string {
+  if (!content || content.trim().length === 0) {
+    return 'New conversation';
+  }
+  
+  let name = content.trim();
+  
+  // Strip markdown formatting
+  name = name.replace(/[*_~`#]/g, '');
+  
+  // Use first line only
+  const firstLine = name.split('\n')[0].trim();
+  name = firstLine || name;
+  
+  // If short enough, return as-is
+  if (name.length <= MAX_THREAD_NAME_LENGTH) {
+    return name;
+  }
+  
+  // Truncate at word boundary
+  const truncated = name.slice(0, MAX_THREAD_NAME_LENGTH - 1); // -1 for ellipsis char
+  const lastSpace = truncated.lastIndexOf(' ');
+  
+  if (lastSpace > MAX_THREAD_NAME_LENGTH * 0.5) {
+    // Break at word boundary if it doesn't lose too much
+    return truncated.slice(0, lastSpace) + '…';
+  }
+  
+  // Hard truncate if no good word boundary
+  return truncated + '…';
+}

package/src/middleware/allowlist.ts

@@ -0,0 +1,64 @@
+import { ChannelType, type Message } from 'discord.js';
+
+/**
+ * Parse comma-separated environment variable into Set.
+ * Returns null if not configured (no restriction).
+ */
+function parseEnvList(value?: string): Set<string> | null {
+  if (!value || value.trim() === '') return null;
+  return new Set(value.split(',').map(s => s.trim()).filter(Boolean));
+}
+
+// Parse env vars once at module load
+const ALLOWED_USERS = parseEnvList(process.env.ALLOWED_USERS);
+const ALLOWED_ROLES = parseEnvList(process.env.ALLOWED_ROLES);
+const ALLOWED_CHANNELS = parseEnvList(process.env.ALLOWED_CHANNELS);
+
+/**
+ * Check if message is from an allowed user/role/channel.
+ * 
+ * Guild messages:
+ * - If ALLOWED_CHANNELS set, message must be in allowed channel
+ * - If ALLOWED_USERS set, user must be in allowlist OR have allowed role
+ * - If ALLOWED_ROLES set, user must have allowed role OR be in user allowlist
+ * 
+ * DM messages:
+ * - Channel/role allowlists are ignored (DMs have no guild context)
+ * - Only ALLOWED_USERS is checked (if configured)
+ */
+export function checkAllowlist(message: Message): boolean {
+  const isDM = message.channel.type === ChannelType.DM;
+
+  // If no allowlists configured, allow everything
+  if (!ALLOWED_USERS && !ALLOWED_ROLES && !ALLOWED_CHANNELS) return true;
+
+  // DMs: only user allowlist applies (no channels or roles in DMs)
+  if (isDM) {
+    if (ALLOWED_USERS) return ALLOWED_USERS.has(message.author.id);
+    // No user allowlist configured — allow DMs from anyone (channel/role lists don't apply)
+    return true;
+  }
+
+  // Guild messages: check channel allowlist
+  if (ALLOWED_CHANNELS && !ALLOWED_CHANNELS.has(message.channelId)) {
+    // Also check parent channel for thread messages
+    const parentId = message.channel.isThread() ? message.channel.parentId : null;
+    if (!parentId || !ALLOWED_CHANNELS.has(parentId)) return false;
+  }
+  
+  // Check user allowlist
+  if (ALLOWED_USERS && ALLOWED_USERS.has(message.author.id)) return true;
+  
+  // Check role allowlist
+  if (ALLOWED_ROLES && message.member) {
+    const userRoles = message.member.roles.cache;
+    for (const roleId of ALLOWED_ROLES) {
+      if (userRoles.has(roleId)) return true;
+    }
+  }
+  
+  // If user/role allowlists exist but user matches neither, deny
+  if (ALLOWED_USERS || ALLOWED_ROLES) return false;
+  
+  return true;
+}

package/src/middleware/rate-limiter.ts

@@ -0,0 +1,46 @@
+/**
+ * Sliding window rate limiter using in-memory Map.
+ * 
+ * Advantages over DB:
+ * - Faster (no I/O overhead)
+ * - Simpler (no cleanup job needed)
+ * - Sufficient for single-instance bot
+ */
+
+const RATE_LIMIT_REQUESTS = parseInt(process.env.RATE_LIMIT_REQUESTS || '5');
+const RATE_LIMIT_WINDOW_MS = parseInt(process.env.RATE_LIMIT_WINDOW_MS || '60000');
+
+// In-memory sliding window: userId -> array of timestamps
+const userTimestamps = new Map<string, number[]>();
+
+/**
+ * Check if user is within rate limit.
+ * Returns true if request is allowed, false if rate limited.
+ */
+export function checkRateLimit(userId: string): boolean {
+  if (RATE_LIMIT_REQUESTS <= 0) return true; // Disabled
+  
+  const now = Date.now();
+  const windowStart = now - RATE_LIMIT_WINDOW_MS;
+  
+  let timestamps = userTimestamps.get(userId) || [];
+  
+  // Remove expired timestamps
+  timestamps = timestamps.filter(t => t > windowStart);
+  
+  if (timestamps.length >= RATE_LIMIT_REQUESTS) {
+    userTimestamps.set(userId, timestamps);
+    return false; // Rate limited
+  }
+  
+  timestamps.push(now);
+  userTimestamps.set(userId, timestamps);
+  return true;
+}
+
+/**
+ * Reset all rate limits (exported for testing).
+ */
+export function resetRateLimits(): void {
+  userTimestamps.clear();
+}

package/src/queue.ts

@@ -0,0 +1,43 @@
+/**
+ * Queue - BullMQ job queue for Claude processing
+ *
+ * Why a queue?
+ * 1. Claude can take minutes to respond - Discord would timeout
+ * 2. Rate limiting - don't spawn 100 Claude processes at once
+ * 3. Persistence - if the bot crashes, jobs aren't lost
+ */
+
+import { Queue } from 'bullmq';
+import IORedis from 'ioredis';
+
+// Redis connection for BullMQ
+const connection = new IORedis({
+    host: process.env.REDIS_HOST || 'localhost',
+    port: parseInt(process.env.REDIS_PORT || '6379'),
+    maxRetriesPerRequest: null, // Required for BullMQ
+});
+
+// The queue that holds Claude processing jobs
+export const claudeQueue = new Queue('claude', {
+    connection,
+    defaultJobOptions: {
+        attempts: 3,
+        backoff: {
+            type: 'exponential',
+            delay: 1000,
+        },
+        removeOnComplete: 100, // Keep last 100 completed jobs
+        removeOnFail: 50,      // Keep last 50 failed jobs
+    },
+});
+
+// Job data structure
+export interface ClaudeJob {
+    prompt: string;
+    threadId: string;
+    sessionId: string;
+    resume: boolean;
+    userId: string;
+    username: string;
+    workingDir?: string;
+}