@thesammykins/tether 1.0.0 → 1.2.0

package/docs/installation.md

@@ -0,0 +1,151 @@
+# Installation
+
+## Prerequisites
+
+| Requirement | Version | Check |
+|-------------|---------|-------|
+| [Bun](https://bun.sh) | 1.1.0+ | `bun --version` |
+| [Redis](https://redis.io) | 6+ | `redis-cli ping` |
+| Discord bot token | — | [Create one](discord-setup.md) |
+| An AI agent CLI | — | [Setup guides](agents.md) |
+
+## Install Tether
+
+### From npm (recommended)
+
+```bash
+bun add -g @thesammykins/tether
+```
+
+This installs the `tether` CLI globally. Verify:
+
+```bash
+tether help
+```
+
+### From source
+
+```bash
+git clone https://github.com/thesammykins/tether.git
+cd tether
+bun install
+```
+
+When running from source, use `bun run bin/tether.ts` instead of `tether`.
+
+## Quick Setup
+
+### 1. Create your Discord bot
+
+Follow the [Discord Bot Setup](discord-setup.md) guide to create a bot and get your token.
+
+### 2. Install your AI agent
+
+Tether bridges Discord to a CLI agent. You need at least one installed:
+
+| Agent | Install command | Verify |
+|-------|----------------|--------|
+| [Claude Code](agents.md#claude-code) | `curl -fsSL https://claude.ai/install.sh \| bash` | `claude --version` |
+| [OpenCode](agents.md#opencode) | `curl -fsSL https://opencode.ai/install \| bash` | `opencode --version` |
+| [Codex](agents.md#codex) | `npm install -g @openai/codex` | `codex --version` |
+
+See [Agent Setup](agents.md) for full instructions including API keys and authentication.
+
+### 3. Configure
+
+**Option A — Interactive setup:**
+
+```bash
+tether setup
+```
+
+This walks you through token, agent type, and channel configuration.
+
+**Option B — Import from `.env`:**
+
+```bash
+cp .env.example .env
+# Edit .env with your values
+tether config import .env
+```
+
+**Option C — Set values directly:**
+
+```bash
+tether config set DISCORD_BOT_TOKEN       # prompts for value (hidden input)
+tether config set AGENT_TYPE opencode
+tether config set ALLOWED_CHANNELS 123456789
+```
+
+See [Configuration](configuration.md) for all options.
+
+### 4. Start Redis
+
+```bash
+redis-server
+```
+
+Or if using Homebrew on macOS:
+
+```bash
+brew services start redis
+```
+
+### 5. Start Tether
+
+```bash
+tether start
+```
+
+You should see:
+
+```
+[bot] Connecting to Discord gateway (attempt 1)...
+[bot] Logged in as YourBot#1234
+[worker] Worker started, waiting for jobs...
+```
+
+### 6. Test it
+
+In your Discord server, `@mention` the bot:
+
+```
+@Tether what time is it?
+```
+
+The bot will react with 👀, create a thread, and post the agent's response.
+
+## Letting the Agent Set Itself Up
+
+If you're already running Claude Code or OpenCode in a project, the agent can set up Tether for you:
+
+> "Install @thesammykins/tether and configure it with my Discord bot token. Use opencode as the agent type. My allowed channel is 123456789."
+
+The agent will:
+1. Run `bun add -g @thesammykins/tether`
+2. Run `tether config set DISCORD_BOT_TOKEN` (you'll need to provide the token)
+3. Run `tether config set AGENT_TYPE opencode`
+4. Run `tether config set ALLOWED_CHANNELS 123456789`
+5. Start the bot with `tether start`
+
+See [Agent Setup](agents.md) for agent-specific instructions on how to have the agent bootstrap Tether.
+
+## Updating
+
+```bash
+# npm install
+bun add -g @thesammykins/tether@latest
+
+# From source
+git pull && bun install
+```
+
+## Uninstall
+
+```bash
+# Remove the package
+bun remove -g @thesammykins/tether
+
+# Remove config (optional)
+rm -rf ~/.config/tether
+```

package/docs/troubleshooting.md

@@ -0,0 +1,74 @@
+# Troubleshooting
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Bot connects but doesn't respond | Enable **Message Content Intent** in Developer Portal → Bot tab. This is the #1 setup issue. |
+| `TokenInvalid` error | Regenerate your bot token in the Developer Portal and update: `tether config set DISCORD_BOT_TOKEN` |
+| `DisallowedIntents` error | Enable the required intents in Developer Portal → Bot tab (see [Discord Setup](discord-setup.md#3-configure-privileged-intents)) |
+| Bot doesn't receive DMs | Set `ENABLE_DMS=true`: `tether config set ENABLE_DMS true` |
+| "Rate limit exceeded" | Adjust `RATE_LIMIT_REQUESTS` / `RATE_LIMIT_WINDOW_MS` (see [Configuration](configuration.md#limits)) |
+| Agent command not found | Ensure `claude`/`opencode`/`codex` is installed and on PATH (see [Agent Setup](agents.md)) |
+| Redis connection refused | Start Redis: `redis-server` (or `brew services start redis` on macOS) |
+| Bot can't create threads | Check bot has **Create Public Threads** permission in your server |
+| `tether start` hangs / does nothing | Check for a stale PID file: `rm -f .tether.pid` then try again |
+| Bot responds to wrong channels | Set `ALLOWED_CHANNELS` to restrict which channels the bot listens in |
+
+## Checking Status
+
+```bash
+# Is tether running?
+tether status
+
+# Is Discord connected?
+tether health
+
+# What config is active?
+tether config list
+```
+
+## Logs
+
+`tether start` logs to stdout. If running in the background:
+
+```bash
+# Run with logging
+nohup bun run bin/tether.ts start > /tmp/tether.log 2>&1 &
+
+# View logs
+tail -f /tmp/tether.log
+```
+
+## Agent-Specific Issues
+
+### Claude Code
+
+| Problem | Solution |
+|---------|----------|
+| `claude: command not found` | Install: `curl -fsSL https://claude.ai/install.sh \| bash` |
+| Authentication expired | Run `claude` interactively to re-authenticate |
+| Session resume fails | Sessions may expire — new messages will start fresh automatically |
+
+### OpenCode
+
+| Problem | Solution |
+|---------|----------|
+| `opencode: command not found` | Install: `curl -fsSL https://opencode.ai/install \| bash` |
+| API key not set | Set your provider key: `export ANTHROPIC_API_KEY=sk-ant-...` or `export OPENAI_API_KEY=sk-...` |
+
+### Codex
+
+| Problem | Solution |
+|---------|----------|
+| `codex: command not found` | Install: `npm install -g @openai/codex` (requires Node.js 22+) |
+| `OPENAI_API_KEY` not set | `export OPENAI_API_KEY=sk-...` |
+
+## Getting Help
+
+If you're stuck:
+
+1. Check `tether config list` — verify your settings and their sources
+2. Check `tether health` — verify Discord connectivity
+3. Look at the logs for error messages
+4. [Open an issue](https://github.com/thesammykins/tether/issues) with the error output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thesammykins/tether",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Discord bot that bridges messages to AI agent sessions (Claude, OpenCode, Codex)",
   "license": "MIT",
   "author": "thesammykins",
@@ -36,6 +36,7 @@
     "src/",
     "bin/tether.ts",
     "index.ts",
+    "docs/",
     "README.md",
     "LICENSE",
     ".env.example"

package/src/api.ts

@@ -28,16 +28,50 @@ export const questionResponses = new Map<string, { answer: string; optionIndex:
 // Track which threads are waiting for a typed answer
 export const pendingTypedAnswers = new Map<string, string>(); // threadId → requestId
 
+// Pending questions with TTL tracking
+type PendingQuestion = {
+    timeoutId: NodeJS.Timeout;
+};
+export const pendingQuestions = new Map<string, PendingQuestion>();
+
+// Binary file extensions - files with these extensions should be base64 encoded
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.svg',
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+    '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar',
+    '.mp3', '.mp4', '.avi', '.mov', '.mkv', '.flv', '.wmv',
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.bin', '.exe', '.dll', '.so', '.dylib',
+]);
+
 /**
  * Start the HTTP API server
  */
 export function startApiServer(client: Client, port: number = 2643) {
+    // Optional API token authentication
+    const apiToken = process.env.API_TOKEN;
+    const hostname = process.env.TETHER_API_HOST || '127.0.0.1';
+    
     const server = Bun.serve({
         port,
+        hostname,
         async fetch(req) {
             const url = new URL(req.url);
             const headers = { 'Content-Type': 'application/json' };
 
+            // Authentication check - skip for /health endpoint
+            if (apiToken && url.pathname !== '/health') {
+                const authHeader = req.headers.get('Authorization');
+                const expectedAuth = `Bearer ${apiToken}`;
+                
+                if (!authHeader || authHeader !== expectedAuth) {
+                    return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+                        status: 401,
+                        headers,
+                    });
+                }
+            }
+
             // Health check
             if (url.pathname === '/health' && req.method === 'GET') {
                 return new Response(JSON.stringify({
@@ -74,6 +108,7 @@ export function startApiServer(client: Client, port: number = 2643) {
                         fileName: string;
                         fileContent: string;
                         content?: string;
+                        isBase64?: boolean;
                     };
 
                     const channel = await client.channels.fetch(body.channelId);
@@ -84,7 +119,12 @@ export function startApiServer(client: Client, port: number = 2643) {
                         });
                     }
 
-                    const buffer = Buffer.from(body.fileContent, 'utf-8');
+                    // Determine encoding - check if file is binary based on extension
+                    const ext = body.fileName.toLowerCase().match(/\.[^.]+$/)?.[0];
+                    const isBinary = ext ? BINARY_EXTENSIONS.has(ext) : false;
+                    const encoding = body.isBase64 || isBinary ? 'base64' : 'utf-8';
+                    
+                    const buffer = Buffer.from(body.fileContent, encoding);
                     const message = await (channel as TextChannel).send({
                         content: body.content || undefined,
                         files: [{
@@ -114,10 +154,17 @@ export function startApiServer(client: Client, port: number = 2643) {
                         fileName: string;
                         fileContent: string;
                         content?: string;
+                        isBase64?: boolean;
                     };
 
                     const user = await client.users.fetch(body.userId);
-                    const buffer = Buffer.from(body.fileContent, 'utf-8');
+                    
+                    // Determine encoding - check if file is binary based on extension
+                    const ext = body.fileName.toLowerCase().match(/\.[^.]+$/)?.[0];
+                    const isBinary = ext ? BINARY_EXTENSIONS.has(ext) : false;
+                    const encoding = body.isBase64 || isBinary ? 'base64' : 'utf-8';
+                    
+                    const buffer = Buffer.from(body.fileContent, encoding);
                     const message = await user.send({
                         content: body.content || undefined,
                         files: [{
@@ -156,7 +203,7 @@ export function startApiServer(client: Client, port: number = 2643) {
                         buttons: Array<{
                             label: string;
                             customId: string;
-                            style: 'primary' | 'secondary' | 'success' | 'danger';
+                            style: number | 'primary' | 'secondary' | 'success' | 'danger';
                             handler?: ButtonHandler;
                         }>;
                     };
@@ -180,7 +227,7 @@ export function startApiServer(client: Client, port: number = 2643) {
                         return embed;
                     });
 
-                    // Build button row
+                    // Build button row - handle both number and string styles
                     const styleMap: Record<string, ButtonStyle> = {
                         primary: ButtonStyle.Primary,
                         secondary: ButtonStyle.Secondary,
@@ -196,10 +243,19 @@ export function startApiServer(client: Client, port: number = 2643) {
                         } else {
                             log(`No handler for button: ${b.customId}`);
                         }
+                        
+                        // Handle both number styles (from CLI) and string styles (legacy)
+                        let buttonStyle: ButtonStyle;
+                        if (typeof b.style === 'number') {
+                            buttonStyle = b.style as ButtonStyle;
+                        } else {
+                            buttonStyle = styleMap[b.style] || ButtonStyle.Primary;
+                        }
+                        
                         return new ButtonBuilder()
                             .setCustomId(b.customId)
                             .setLabel(b.label)
-                            .setStyle(styleMap[b.style] || ButtonStyle.Primary);
+                            .setStyle(buttonStyle);
                     });
 
                     const row = new ActionRowBuilder<ButtonBuilder>().addComponents(buttons);
@@ -210,6 +266,26 @@ export function startApiServer(client: Client, port: number = 2643) {
                         components: [row],
                     });
 
+                    // Register question buttons with TTL (5 minutes)
+                    // Extract requestId from button customIds that match "ask_<uuid>_*" pattern
+                    body.buttons.forEach(b => {
+                        const match = b.customId.match(/^ask_([a-f0-9-]+)_/);
+                        if (match) {
+                            const requestId = match[1];
+                            // Only register once per requestId
+                            if (!pendingQuestions.has(requestId)) {
+                                const timeoutId = setTimeout(() => {
+                                    pendingQuestions.delete(requestId);
+                                    questionResponses.delete(requestId);
+                                    log(`Question ${requestId} expired after 5 minutes`);
+                                }, 300_000); // 5 minutes
+                                
+                                pendingQuestions.set(requestId, { timeoutId });
+                                log(`Registered question ${requestId} with 5-minute TTL`);
+                            }
+                        }
+                    });
+
                     return new Response(JSON.stringify({
                         success: true,
                         messageId: message.id,
@@ -256,6 +332,13 @@ export function startApiServer(client: Client, port: number = 2643) {
                         pendingTypedAnswers.set(body.data.threadId, requestId);
                     }
 
+                    // Clear TTL timeout if it exists
+                    const pending = pendingQuestions.get(requestId);
+                    if (pending) {
+                        clearTimeout(pending.timeoutId);
+                        pendingQuestions.delete(requestId);
+                    }
+
                     // Auto-cleanup after 10 minutes
                     setTimeout(() => questionResponses.delete(requestId), 600_000);
 
@@ -310,7 +393,7 @@ export function startApiServer(client: Client, port: number = 2643) {
         },
     });
 
-    log(`HTTP API server listening on port ${port}`);
+    log(`HTTP API server listening on ${hostname}:${port}`);
     return server;
 }
 

package/src/bot.ts

@@ -162,7 +162,7 @@ client.once(Events.ClientReady, async (c) => {
     }
 
     // Start HTTP API server
-    const apiPort = parseInt(process.env.API_PORT || '2643');
+    const apiPort = parseInt(process.env.TETHER_API_PORT || '2643');
     startApiServer(client, apiPort);
 });
 
@@ -312,19 +312,19 @@ client.on(Events.MessageCreate, async (message: Message) => {
         await (message.channel as DMChannel).sendTyping();
 
         if (mapping) {
-            // Check session limits for ongoing DM session
-            if (!checkSessionLimits(dmChannelId)) {
-                await message.reply('⚠️ Session limit reached. Send `!reset` to start a new session.');
-                return;
-            }
-
-            // Handle !reset to start fresh DM session
+            // Handle !reset to start fresh DM session (BEFORE session limit check)
             if (content.toLowerCase() === '!reset') {
                 db.run('DELETE FROM threads WHERE thread_id = ?', [dmChannelId]);
                 await message.reply('🔄 Session reset. Your next message starts a new conversation.');
                 return;
             }
 
+            // Check session limits for ongoing DM session
+            if (!checkSessionLimits(dmChannelId)) {
+                await message.reply('⚠️ Session limit reached. Send `!reset` to start a new session.');
+                return;
+            }
+
             // Resume existing session
             const workingDir = mapping.working_dir ||
                 process.env.CLAUDE_WORKING_DIR ||
@@ -388,6 +388,42 @@ client.on(Events.MessageCreate, async (message: Message) => {
         // Message will be held in held_messages table
         return;
     }
+    
+    // If resumed, replay held messages
+    if (pauseState.resumed) {
+        const heldCount = pauseState.heldMessages?.length || 0;
+        if (heldCount > 0) {
+            await message.reply(`✅ Resuming — replaying ${heldCount} held message${heldCount !== 1 ? 's' : ''}...`);
+            
+            // Look up session for this thread
+            const threadId = message.channel.id;
+            const mapping = db.query('SELECT session_id, working_dir FROM threads WHERE thread_id = ?')
+                .get(threadId) as { session_id: string; working_dir: string | null } | null;
+            
+            if (mapping) {
+                const workingDir = mapping.working_dir ||
+                    getChannelConfigCached(message.channel.isThread() ? message.channel.parentId || '' : '')?.working_dir ||
+                    process.env.CLAUDE_WORKING_DIR ||
+                    process.cwd();
+                
+                // Replay each held message in order
+                for (const held of pauseState.heldMessages || []) {
+                    await claudeQueue.add('process', {
+                        prompt: held.content,
+                        threadId,
+                        sessionId: mapping.session_id,
+                        resume: true,
+                        userId: held.author_id,
+                        username: 'held-message', // We don't have username stored
+                        workingDir,
+                    });
+                }
+            }
+        } else {
+            await message.reply('✅ Resumed (no held messages).');
+        }
+        return;
+    }
 
     // Feature: Acknowledge message (fire and forget)
     acknowledgeMessage(message).catch(err => log(`Failed to acknowledge message: ${err}`));
@@ -498,6 +534,7 @@ client.on(Events.MessageCreate, async (message: Message) => {
     // This allows us to update the status message later (Processing... → Done)
     let statusMessage;
     let thread;
+    let channelContext = '';
     try {
         // Post status message in the channel
         statusMessage = await (message.channel as TextChannel).send('Processing...');
@@ -512,7 +549,7 @@ client.on(Events.MessageCreate, async (message: Message) => {
         });
 
         // Feature: Get channel context for new conversations
-        const channelContext = await getChannelContext(message.channel as TextChannel);
+        channelContext = await getChannelContext(message.channel as TextChannel);
         if (channelContext) {
             log(`Channel context: ${channelContext.slice(0, 100)}...`);
         }
@@ -560,6 +597,7 @@ client.on(Events.MessageCreate, async (message: Message) => {
         userId: message.author.id,
         username: message.author.tag,
         workingDir,
+        channelContext,
     });
 });