@thesammykins/tether 1.0.1 → 1.3.0

package/docs/agents.md

@@ -0,0 +1,205 @@
+# Agent Setup
+
+Tether bridges Discord messages to an AI coding agent CLI. You need at least one agent installed and available on your system PATH.
+
+Set the agent type in your config:
+
+```bash
+tether config set AGENT_TYPE claude    # or: opencode, codex
+```
+
+## Claude Code
+
+Claude Code is Anthropic's agentic coding tool. It runs natively — no Node.js required.
+
+### Install
+
+**Quick install (macOS/Linux):**
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+**Homebrew (macOS):**
+
+```bash
+brew install --cask claude-code
+```
+
+### Authenticate
+
+```bash
+claude
+# Follow prompts to log in with your Anthropic account
+```
+
+You need an active Anthropic account. Claude Code authenticates via browser — no API key needed for interactive use.
+
+### Verify
+
+```bash
+claude --version
+claude --print -p "say hello"
+```
+
+### How Tether Uses It
+
+Tether spawns Claude Code with:
+
+```bash
+claude --print --output-format json --session-id <id> -p "<prompt>"
+# Follow-ups:
+claude --print --output-format json --resume <id> -p "<prompt>"
+```
+
+Key flags:
+- `--print` — Non-interactive mode, returns output to stdout
+- `--session-id` / `--resume` — Session persistence across messages in the same thread
+- `--append-system-prompt` — Injects datetime context and channel info
+- `--output-format json` — Structured output for reliable parsing
+
+---
+
+## OpenCode
+
+OpenCode supports multiple AI providers (OpenAI, Anthropic, Google, etc.).
+
+### Install
+
+**Quick install:**
+
+```bash
+curl -fsSL https://opencode.ai/install | bash
+```
+
+**npm:**
+
+```bash
+npm install -g opencode
+```
+
+### Configure
+
+OpenCode reads its config from `~/.config/opencode/`. You'll need an API key for your chosen provider:
+
+```bash
+# Set your provider API key (e.g. for Anthropic)
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Or for OpenAI
+export OPENAI_API_KEY=sk-...
+```
+
+See the [OpenCode docs](https://opencode.ai/docs) for full provider configuration.
+
+### Verify
+
+```bash
+opencode --version
+opencode run "say hello"
+```
+
+### How Tether Uses It
+
+Tether spawns OpenCode with:
+
+```bash
+opencode run --format json "<prompt>"
+# Follow-ups:
+opencode run --format json --session <id> "<prompt>"
+```
+
+Key flags:
+- `run` — Execute a prompt
+- `--format json` — Structured output
+- `--session <id>` — Resume an existing session
+- `--cwd <path>` — Set working directory
+
+---
+
+## Codex
+
+Codex is OpenAI's CLI coding agent. Requires Node.js 22+.
+
+### Install
+
+```bash
+npm install -g @openai/codex
+```
+
+### Configure
+
+Codex requires an OpenAI API key:
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+### Verify
+
+```bash
+codex --version
+codex exec "say hello"
+```
+
+### How Tether Uses It
+
+Tether spawns Codex with:
+
+```bash
+codex exec --json "<prompt>"
+# Follow-ups:
+codex exec resume <sessionId> --json "<prompt>"
+```
+
+Key flags:
+- `exec` — Execute a prompt
+- `--json` — Structured output
+- `resume <id>` — Resume an existing session
+
+---
+
+## Having the Agent Set Up Tether
+
+If you're already running one of these agents in a project, you can ask it to install and configure Tether:
+
+### Claude Code
+
+```
+Install @thesammykins/tether globally with bun. Configure it with my Discord
+bot token (I'll provide it when prompted), set the agent type to claude, and
+set my allowed channel to 123456789. Then start the bot.
+```
+
+### OpenCode
+
+```
+Run these commands to set up Tether:
+1. bun add -g @thesammykins/tether
+2. tether config set DISCORD_BOT_TOKEN (I'll provide the token)
+3. tether config set AGENT_TYPE opencode
+4. tether config set ALLOWED_CHANNELS 123456789
+5. tether start
+```
+
+### Codex
+
+```
+Install @thesammykins/tether with: bun add -g @thesammykins/tether
+Then configure it: tether config set AGENT_TYPE codex
+Set the channel: tether config set ALLOWED_CHANNELS 123456789
+I'll set the bot token manually.
+```
+
+> **Note:** The bot token is a secret — you'll always need to provide it interactively via `tether config set DISCORD_BOT_TOKEN` (input is hidden). Don't paste tokens into agent prompts.
+
+## Switching Agents
+
+Change agents at any time:
+
+```bash
+tether config set AGENT_TYPE opencode
+tether stop && tether start
+```
+
+Existing thread sessions will not carry over — new messages start fresh sessions with the new agent.

package/docs/architecture.md

@@ -0,0 +1,117 @@
+# Architecture
+
+## Overview
+
+Tether uses a queue-based architecture for reliable, decoupled message processing:
+
+```
+Discord Bot  →  BullMQ Queue  →  Agent Worker
+ (gateway)       (Redis)          (spawns CLI)
+```
+
+The bot handles Discord events, the queue provides durability and backpressure, and the worker spawns the appropriate agent CLI to process prompts.
+
+## Components
+
+| Component | Path | Role |
+|-----------|------|------|
+| **Bot** | `src/bot.ts` | Discord gateway — receives messages, runs middleware, enqueues jobs |
+| **Worker** | `src/worker.ts` | Job processor — pulls jobs from queue, spawns agent adapter, posts responses |
+| **Adapters** | `src/adapters/` | `AgentAdapter` interface — wraps Claude/OpenCode/Codex CLIs |
+| **Middleware** | `src/middleware/` | Request pipeline — allowlist, rate limiter |
+| **Features** | `src/features/` | Ack emoji, channel context, thread naming, session limits, pause/resume |
+| **Queue** | `src/queue.ts` | BullMQ job queue backed by Redis |
+| **Database** | `src/db.ts` | SQLite — thread→session mapping, channel config |
+| **Config** | `src/config.ts` | Config store — TOML preferences + AES-256-GCM encrypted secrets |
+| **CLI** | `bin/tether.ts` | Entry point — all `tether` commands |
+
+## Message Flow
+
+### Guild Channels
+
+1. User `@mentions` the bot in a Discord channel
+2. Bot runs the middleware pipeline (allowlist → rate limiter → pause check)
+3. Bot creates a thread with an auto-generated name
+4. Bot adds a job to the BullMQ queue
+5. Worker pulls the job and spawns the configured agent adapter
+6. Adapter runs the CLI (`claude`/`opencode`/`codex`) with the prompt
+7. Worker posts the agent's response back to the Discord thread
+
+### Direct Messages
+
+1. User sends a message to the bot in DMs (no `@mention` needed)
+2. Bot checks user allowlist → rate limiter
+3. Bot creates or resumes a session for this user
+4. Bot adds a job to the BullMQ queue
+5. Worker posts the response back to the DM channel
+
+### BRB Mode
+
+When a user sends `brb` in a thread:
+
+1. The session is flagged as "BRB" — the user is away
+2. If the agent needs to ask a question, it calls `tether ask` instead of its built-in prompt
+3. `tether ask` sends interactive buttons to the Discord thread
+4. The CLI blocks until someone clicks a button or types a free-text answer
+5. The answer is returned to the agent via stdout
+
+## Middleware Pipeline
+
+Messages pass through middleware in order. Each middleware can block the message.
+
+```
+Message → Allowlist → Rate Limiter → Pause/Resume → Queue
+```
+
+1. **Allowlist** (`src/middleware/allowlist.ts`) — Block unauthorized users, channels, or roles. DMs only check `ALLOWED_USERS`.
+2. **Rate Limiter** (`src/middleware/rate-limiter.ts`) — Sliding window per-user rate limit. Configurable via `RATE_LIMIT_REQUESTS` and `RATE_LIMIT_WINDOW_MS`.
+3. **Pause/Resume** (`src/features/pause-resume.ts`) — Hold messages if the thread is paused (guild threads only). Users type `pause`/`resume` to toggle.
+
+## Adapter System
+
+Adapters implement the `AgentAdapter` interface (`src/adapters/types.ts`):
+
+```typescript
+interface AgentAdapter {
+  readonly name: string;
+  spawn(options: SpawnOptions): Promise<SpawnResult>;
+}
+```
+
+The adapter registry (`src/adapters/registry.ts`) maps `AGENT_TYPE` to the correct adapter. Each adapter handles:
+
+- CLI argument construction
+- Session ID management (new vs. resume)
+- Output parsing (JSON → text)
+- Working directory configuration
+
+## Session Management
+
+- **Turn limits** — Max messages per thread/DM session (`MAX_TURNS_PER_SESSION`)
+- **Duration limits** — Max session lifetime (`MAX_SESSION_DURATION_MS`)
+- **Pause/Resume** — Type `pause` to hold messages, `resume` to continue (threads only)
+- **DM Reset** — Type `!reset` in DMs to start a new session
+- **Auto-completion** — React with ✅ on the last message to mark "Done" (threads only)
+
+## Config Resolution
+
+Configuration values are resolved in priority order:
+
+```
+Environment variable → Config store (TOML/encrypted) → Default
+```
+
+See [Configuration](configuration.md) for the full key reference.
+
+## Data Storage
+
+| Store | Path | Contents |
+|-------|------|----------|
+| SQLite | `./data/threads.db` | Thread→session mapping, channel working dirs |
+| Config | `~/.config/tether/config.toml` | Preferences (plaintext TOML) |
+| Secrets | `~/.config/tether/secrets.enc` | Tokens (AES-256-GCM encrypted) |
+| Redis | (in-memory) | BullMQ job queue |
+
+### Privacy
+
+Tether stores only thread-to-session mappings and channel configuration. **No message content, user data, or conversation history is persisted.** Messages pass through the Redis queue transiently and are discarded after processing.

package/docs/cli.md

@@ -0,0 +1,277 @@
+# CLI Reference
+
+Full reference for the `tether` command-line interface.
+
+```bash
+tether <command> [options]
+```
+
+## Management Commands
+
+### `tether start`
+
+Start the Discord bot and job worker as child processes.
+
+```bash
+tether start
+```
+
+Blocks the terminal — both bot and worker run until you stop them. To run in the background:
+
+```bash
+nohup bun run bin/tether.ts start > /tmp/tether.log 2>&1 &
+```
+
+### `tether stop`
+
+Stop all running Tether processes.
+
+```bash
+tether stop
+```
+
+### `tether status`
+
+Show whether the bot and worker are running.
+
+```bash
+tether status
+```
+
+### `tether health`
+
+Check Discord gateway connection status.
+
+```bash
+tether health
+```
+
+### `tether setup`
+
+Interactive setup wizard — walks you through token, agent type, and channel configuration.
+
+```bash
+tether setup
+```
+
+### `tether help`
+
+Show the built-in help text.
+
+```bash
+tether help
+```
+
+---
+
+## Discord Commands
+
+### `tether send`
+
+Send a text message to a channel.
+
+```bash
+tether send <channel-id> "message"
+```
+
+### `tether embed`
+
+Send a rich embed.
+
+```bash
+tether embed <channel-id> "description" [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--title "..."` | Embed title |
+| `--url "..."` | Title link URL |
+| `--color <name\|hex>` | `red`, `green`, `blue`, `yellow`, `purple`, `orange`, or `0xHEX` |
+| `--author "..."` | Author name |
+| `--author-url "..."` | Author link |
+| `--author-icon "..."` | Author icon URL |
+| `--thumbnail "..."` | Small image (top right) |
+| `--image "..."` | Large image (bottom) |
+| `--footer "..."` | Footer text |
+| `--footer-icon "..."` | Footer icon URL |
+| `--timestamp` | Add current timestamp |
+| `--field "Name:Value"` | Add a field (append `:inline` for inline) |
+
+**Example:**
+
+```bash
+tether embed 123456789 "Status update" \
+  --title "Daily Report" \
+  --color green \
+  --field "Tasks:5 done:inline"
+```
+
+### `tether file`
+
+Send a file attachment.
+
+```bash
+tether file <channel-id> <filepath> ["message"]
+```
+
+### `tether buttons`
+
+Send interactive buttons.
+
+```bash
+tether buttons <channel-id> "prompt" --button label="..." id="..." [options]
+```
+
+Each `--button` takes these key-value pairs:
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `label="..."` | Yes | Button text |
+| `id="..."` | Yes | Custom ID for identifying clicks |
+| `style="..."` | No | `primary`, `secondary`, `success`, `danger` |
+| `reply="..."` | No | Ephemeral reply when clicked |
+| `webhook="..."` | No | URL to POST click data to |
+
+**Example:**
+
+```bash
+tether buttons 123456789 "Approve this PR?" \
+  --button label="Yes" id="approve" style="success" reply="Approved!" \
+  --button label="No" id="reject" style="danger" reply="Rejected"
+```
+
+### `tether ask`
+
+Ask a blocking question with button options. Blocks until someone answers or the timeout expires. Prints the selected answer to stdout.
+
+```bash
+tether ask <channel-id> "question" --option "A" --option "B" [--timeout 300]
+```
+
+- Exit code `0` on answer, `1` on timeout
+- Automatically includes a **"Type answer"** button for free-form text input
+- Default timeout: 300 seconds (5 minutes)
+
+**Example:**
+
+```bash
+ANSWER=$(tether ask 123456789 "Deploy to prod?" --option "Yes" --option "No" --timeout 600)
+if [ "$ANSWER" = "Yes" ]; then
+  deploy_to_prod
+fi
+```
+
+### `tether typing`
+
+Show the typing indicator in a channel.
+
+```bash
+tether typing <channel-id>
+```
+
+### `tether edit`
+
+Edit an existing message.
+
+```bash
+tether edit <channel-id> <message-id> "new content"
+```
+
+### `tether delete`
+
+Delete a message.
+
+```bash
+tether delete <channel-id> <message-id>
+```
+
+### `tether rename`
+
+Rename a thread.
+
+```bash
+tether rename <thread-id> "new name"
+```
+
+### `tether reply`
+
+Reply to a specific message.
+
+```bash
+tether reply <channel-id> <message-id> "reply text"
+```
+
+### `tether thread`
+
+Create a thread from a message.
+
+```bash
+tether thread <channel-id> <message-id> "thread name"
+```
+
+### `tether react`
+
+Add a reaction to a message.
+
+```bash
+tether react <channel-id> <message-id> "emoji"
+```
+
+### `tether state`
+
+Update a thread status message with a preset or custom text.
+
+```bash
+tether state <channel-id> <message-id> <state>
+```
+
+**Presets:** `processing`, `thinking`, `searching`, `writing`, `done`, `error`, `waiting`
+
+---
+
+## DM Commands
+
+Proactive outreach — send messages directly to a user.
+
+### `tether dm` (text)
+
+```bash
+tether dm <user-id> "message"
+```
+
+### `tether dm --embed`
+
+Send a rich embed via DM (same options as `tether embed`).
+
+```bash
+tether dm <user-id> --embed "description" --title "Title" --color green
+```
+
+### `tether dm --file`
+
+Send a file attachment via DM.
+
+```bash
+tether dm <user-id> --file ./report.md "Here's the report"
+```
+
+---
+
+## Config Commands
+
+Manage persistent configuration and encrypted secrets. See [Configuration](configuration.md) for details.
+
+```bash
+tether config set <key> [value]     # Set a value (prompts for secrets)
+tether config get <key>             # Get resolved value with source
+tether config list                  # Show all values with sources
+tether config delete <key>          # Remove a value
+tether config import [path]         # Import from .env file (default: ./.env)
+tether config path                  # Show config file locations
+```
+
+---
+
+## HTTP API
+
+Tether exposes an HTTP API on port 2643 for external scripts and webhooks. See the [API documentation](../skills/tether/HTTP-API.md).