@hoverlover/cc-discord 0.1.0

package/scripts/start-orchestrator.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$ROOT_DIR/scripts/load-env.sh"
+
+WORKER_KEYS=(
+  DISCORD_SESSION_ID
+  CLAUDE_AGENT_ID
+  RELAY_HOST
+  RELAY_PORT
+  RELAY_URL
+  RELAY_API_TOKEN
+  AUTO_REPLY_PERMISSION_MODE
+  CLAUDE_RUNTIME_ID
+  WAIT_QUIET_TIMEOUT
+  BASH_POLICY_MODE
+  ALLOW_BASH_RUN_IN_BACKGROUND
+  ALLOW_BASH_BACKGROUND_OPS
+  BASH_POLICY_NOTIFY_ON_BLOCK
+  BASH_POLICY_NOTIFY_CHANNEL_ID
+)
+
+# Preferred split env file for worker process
+load_env_keys "$ROOT_DIR/.env.worker" "${WORKER_KEYS[@]}"
+load_env_keys "${CC_DISCORD_CONFIG_DIR:-$HOME/.config/cc-discord}/.env.worker" "${WORKER_KEYS[@]}"
+# Legacy fallback (single-file mode)
+load_env_keys "$ROOT_DIR/.env" "${WORKER_KEYS[@]}"
+load_env_keys "${CC_DISCORD_CONFIG_DIR:-$HOME/.config/cc-discord}/.env" "${WORKER_KEYS[@]}"
+
+SETTINGS_PATH="$ROOT_DIR/.claude/settings.json"
+SYSTEM_PROMPT_PATH="$ROOT_DIR/prompts/orchestrator-system.md"
+
+if ! command -v claude >/dev/null 2>&1; then
+  echo "Error: 'claude' CLI not found on PATH"
+  exit 1
+fi
+
+if [ ! -f "$SETTINGS_PATH" ]; then
+  echo "Generating settings..."
+  bash "$ROOT_DIR/scripts/generate-settings.sh"
+fi
+
+if [ ! -f "$SYSTEM_PROMPT_PATH" ]; then
+  echo "Missing prompt file: $SYSTEM_PROMPT_PATH"
+  exit 1
+fi
+
+# Defensive cleanup in case parent shell exported relay-only secrets
+unset DISCORD_BOT_TOKEN DISCORD_CHANNEL_ID DISCORD_ALLOWED_CHANNEL_IDS
+
+export PATH="$ROOT_DIR/tools:$PATH"
+export ORCHESTRATOR_DIR="$ROOT_DIR"
+export DISCORD_SESSION_ID="${DISCORD_SESSION_ID:-default}"
+export CLAUDE_RUNTIME_ID="${CLAUDE_RUNTIME_ID:-rt_$(date +%s)_$RANDOM}"
+
+# Routing identity for this Claude instance:
+# - AGENT_ID is what hooks/tools use while running
+# - CLAUDE_AGENT_ID is what relay writes to in SQLite
+# Default behavior keeps them aligned.
+if [ -z "${AGENT_ID:-}" ]; then
+  export AGENT_ID="${CLAUDE_AGENT_ID:-claude}"
+fi
+export CLAUDE_AGENT_ID="${CLAUDE_AGENT_ID:-$AGENT_ID}"
+
+SYSTEM_PROMPT="$(cat "$SYSTEM_PROMPT_PATH")"
+INITIAL_PROMPT="Start now. Discover channels and spawn subagents. Then begin your health check loop."
+
+# Default to non-interactive permission behavior so orchestrator does not stall.
+# Override with AUTO_REPLY_PERMISSION_MODE=accept-edits for safer interactive-ish behavior.
+if [ "${AUTO_REPLY_PERMISSION_MODE:-skip}" = "accept-edits" ]; then
+  PERMISSION_ARGS=(--permission-mode acceptEdits)
+else
+  PERMISSION_ARGS=(--dangerously-skip-permissions)
+fi
+
+echo "Starting Claude orchestrator (session=$DISCORD_SESSION_ID, agent=$AGENT_ID, runtime=$CLAUDE_RUNTIME_ID, permission_mode=${AUTO_REPLY_PERMISSION_MODE:-skip})..."
+exec claude \
+  --settings "$SETTINGS_PATH" \
+  "${PERMISSION_ARGS[@]}" \
+  --append-system-prompt "$SYSTEM_PROMPT" \
+  -- "$INITIAL_PROMPT"

package/scripts/start-relay.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -e
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+source "$ROOT_DIR/scripts/load-env.sh"
+# Preferred split env file for relay process
+load_env_file "$ROOT_DIR/.env.relay"
+load_env_file "${CC_DISCORD_CONFIG_DIR:-$HOME/.config/cc-discord}/.env.relay"
+# Legacy fallback (single-file mode)
+load_env_file "$ROOT_DIR/.env"
+load_env_file "${CC_DISCORD_CONFIG_DIR:-$HOME/.config/cc-discord}/.env"
+
+# Ensure bun is on PATH (launchd doesn't inherit user shell PATH)
+export PATH="$HOME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+cd "$ROOT_DIR"
+exec bun server/index.ts

package/scripts/start.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+# start.sh — Master startup script for cc-discord.
+#
+# Starts both:
+# 1. The relay server (bun server/index.ts) — as a child process
+# 2. The orchestrator (orchestrator.sh) — which spawns channel agents
+#
+# On SIGTERM/SIGINT, cleanly shuts down both.
+#
+# Usage: start.sh
+#
+# Prerequisites:
+#   - bun installed
+#   - claude CLI installed
+#   - .env.relay and/or .env.worker configured
+#
+# Logs:
+#   CC_DISCORD_LOG_DIR (default: /tmp/cc-discord/logs)
+#   - relay.log          — relay server output
+#   - orchestrator.log   — orchestrator process management
+#   - channel-<name>.log — per-channel Claude agent output
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# User config directory (~/.config/cc-discord by default, override with CC_DISCORD_CONFIG_DIR)
+export CC_DISCORD_CONFIG_DIR="${CC_DISCORD_CONFIG_DIR:-$HOME/.config/cc-discord}"
+if [ ! -d "$CC_DISCORD_CONFIG_DIR" ]; then
+  mkdir -p "$CC_DISCORD_CONFIG_DIR"
+  log_setup=true
+else
+  log_setup=false
+fi
+
+# Seed example env files into config dir if they don't exist.
+# If the user's config already exists but the example is newer, print a hint.
+_is_newer() {
+  # Return 0 if $1 is newer than $2. Works on both macOS and Linux.
+  if stat -f %m "$1" >/dev/null 2>&1; then
+    [ "$(stat -f %m "$1")" -gt "$(stat -f %m "$2")" ]
+  else
+    [ "$(stat -c %Y "$1")" -gt "$(stat -c %Y "$2")" ]
+  fi
+}
+_seed_config() {
+  local src="$1" dest="$2"
+  [ -f "$src" ] || return 0
+  if [ ! -f "$dest" ]; then
+    cp "$src" "$dest"
+    echo "[start] Seeded $dest — edit this file to configure cc-discord."
+  elif _is_newer "$src" "$dest"; then
+    echo "[start] NOTE: $(basename "$src") has new options. Compare with your config:"
+    echo "[start]   diff $dest $src"
+  fi
+}
+_seed_config "$ROOT_DIR/.env.relay.example" "$CC_DISCORD_CONFIG_DIR/.env.relay"
+_seed_config "$ROOT_DIR/.env.worker.example" "$CC_DISCORD_CONFIG_DIR/.env.worker"
+
+if $log_setup; then
+  echo "[start] Created config directory: $CC_DISCORD_CONFIG_DIR"
+  echo "[start] Edit .env.relay and .env.worker in that directory, then restart."
+fi
+
+# Log directory (shared with orchestrator and channel agents)
+export CC_DISCORD_LOG_DIR="${CC_DISCORD_LOG_DIR:-/tmp/cc-discord/logs}"
+mkdir -p "$CC_DISCORD_LOG_DIR"
+
+RELAY_LOG="$CC_DISCORD_LOG_DIR/relay.log"
+RELAY_PID=""
+ORCHESTRATOR_PID=""
+
+log() {
+  echo "[start] $(date '+%H:%M:%S') $*"
+}
+
+cleanup() {
+  log "Shutting down..."
+
+  if [ -n "$ORCHESTRATOR_PID" ] && kill -0 "$ORCHESTRATOR_PID" 2>/dev/null; then
+    log "Stopping orchestrator (PID $ORCHESTRATOR_PID)..."
+    kill -TERM "$ORCHESTRATOR_PID" 2>/dev/null || true
+    wait "$ORCHESTRATOR_PID" 2>/dev/null || true
+  fi
+
+  if [ -n "$RELAY_PID" ] && kill -0 "$RELAY_PID" 2>/dev/null; then
+    log "Stopping relay server (PID $RELAY_PID)..."
+    kill -TERM "$RELAY_PID" 2>/dev/null || true
+    wait "$RELAY_PID" 2>/dev/null || true
+  fi
+
+  log "All processes stopped."
+  exit 0
+}
+
+trap cleanup SIGTERM SIGINT
+
+# ---- Start relay server ----
+log "Starting relay server..."
+bash "$ROOT_DIR/scripts/start-relay.sh" >> "$RELAY_LOG" 2>&1 &
+RELAY_PID=$!
+log "Relay server started (PID $RELAY_PID, log: $RELAY_LOG)"
+
+# Wait for relay to be ready
+MAX_WAIT=30
+WAITED=0
+source "$ROOT_DIR/scripts/load-env.sh"
+load_env_file "$ROOT_DIR/.env.worker"
+load_env_file "$CC_DISCORD_CONFIG_DIR/.env.worker"
+load_env_file "$ROOT_DIR/.env"
+load_env_file "$CC_DISCORD_CONFIG_DIR/.env"
+RELAY_HOST="${RELAY_HOST:-127.0.0.1}"
+RELAY_PORT="${RELAY_PORT:-3199}"
+RELAY_API_TOKEN="${RELAY_API_TOKEN:-}"
+
+# Ensure bun/curl/claude are findable
+export PATH="$HOME/.bun/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# ---- Pre-flight: Claude auth check ----
+if ! claude auth status >/dev/null 2>&1; then
+  log "ERROR: Claude CLI is not authenticated."
+  log "Run 'claude auth login' to log in, then try again."
+  kill -TERM "$RELAY_PID" 2>/dev/null || true
+  wait "$RELAY_PID" 2>/dev/null || true
+  exit 1
+fi
+log "Claude auth verified."
+
+while ! curl -s --max-time 2 -H "x-api-token: ${RELAY_API_TOKEN}" "http://${RELAY_HOST}:${RELAY_PORT}/api/channels" >/dev/null 2>&1; do
+  if ! kill -0 "$RELAY_PID" 2>/dev/null; then
+    log "ERROR: Relay server exited unexpectedly. Check $RELAY_LOG"
+    exit 1
+  fi
+  if [ "$WAITED" -ge "$MAX_WAIT" ]; then
+    log "ERROR: Relay server did not become ready within ${MAX_WAIT}s. Check $RELAY_LOG"
+    cleanup
+  fi
+  sleep 1
+  WAITED=$((WAITED + 1))
+done
+
+log "Relay server is ready."
+
+# ---- Start orchestrator ----
+log "Starting orchestrator..."
+bash "$ROOT_DIR/scripts/orchestrator.sh" &
+ORCHESTRATOR_PID=$!
+log "Orchestrator started (PID $ORCHESTRATOR_PID, log: $CC_DISCORD_LOG_DIR/orchestrator.log)"
+
+# Print monitoring instructions
+log ""
+log "=== cc-discord is running ==="
+log "  Relay:        PID $RELAY_PID"
+log "  Orchestrator: PID $ORCHESTRATOR_PID"
+log ""
+log "  Log directory: $CC_DISCORD_LOG_DIR"
+log "  Monitor all:   tail -f $CC_DISCORD_LOG_DIR/*.log"
+log "  Monitor relay: tail -f $RELAY_LOG"
+log "  Monitor agent: tail -f $CC_DISCORD_LOG_DIR/channel-<name>.log"
+log ""
+log "  Press Ctrl+C to stop all processes."
+log "==============================="
+
+# Monitor both processes — if either exits, shut down the other
+while true; do
+  if ! kill -0 "$RELAY_PID" 2>/dev/null; then
+    log "Relay server exited. Shutting down orchestrator..."
+    cleanup
+  fi
+  if ! kill -0 "$ORCHESTRATOR_PID" 2>/dev/null; then
+    log "Orchestrator exited. Shutting down relay..."
+    cleanup
+  fi
+  sleep 5
+done

package/server/attachment.ts

@@ -0,0 +1,182 @@
+/**
+ * Attachment handling: fetch text attachments inline, download binary attachments locally.
+ */
+
+import { mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ATTACHMENT_DIR,
+  ATTACHMENT_TTL_MS,
+  MAX_ATTACHMENT_DOWNLOAD_BYTES,
+  MAX_ATTACHMENT_INLINE_BYTES,
+} from "./config.ts";
+
+mkdirSync(ATTACHMENT_DIR, { recursive: true });
+
+// File extensions we will fetch and inline as text content
+const TEXT_ATTACHMENT_EXTENSIONS = new Set([
+  "txt",
+  "md",
+  "markdown",
+  "rst",
+  "log",
+  "js",
+  "mjs",
+  "cjs",
+  "ts",
+  "tsx",
+  "jsx",
+  "py",
+  "rb",
+  "go",
+  "rs",
+  "java",
+  "kt",
+  "swift",
+  "c",
+  "cpp",
+  "h",
+  "hpp",
+  "sh",
+  "bash",
+  "zsh",
+  "fish",
+  "json",
+  "yaml",
+  "yml",
+  "toml",
+  "ini",
+  "env",
+  "cfg",
+  "conf",
+  "html",
+  "css",
+  "scss",
+  "sass",
+  "less",
+  "xml",
+  "svg",
+  "sql",
+  "csv",
+  "tsv",
+  "diff",
+  "patch",
+]);
+
+/**
+ * Periodically clean up old downloaded attachment files.
+ * Runs every 10 minutes; removes files older than ATTACHMENT_TTL_MS.
+ */
+export function cleanupOldAttachments() {
+  try {
+    const files = readdirSync(ATTACHMENT_DIR);
+    const now = Date.now();
+    let cleaned = 0;
+    for (const file of files) {
+      const filePath = join(ATTACHMENT_DIR, file);
+      try {
+        const stat = statSync(filePath);
+        if (now - stat.mtimeMs > ATTACHMENT_TTL_MS) {
+          unlinkSync(filePath);
+          cleaned++;
+        }
+      } catch {
+        // file may have been removed concurrently; ignore
+      }
+    }
+    if (cleaned > 0) {
+      console.log(`[Relay] Cleaned up ${cleaned} old attachment file(s)`);
+    }
+  } catch (err: unknown) {
+    console.warn(`[Relay] Attachment cleanup error: ${(err as Error).message}`);
+  }
+}
+
+/**
+ * Download a non-text attachment from Discord CDN to local disk.
+ * Returns the local file path on success, or null on failure.
+ */
+async function downloadAttachmentToLocal(attachment: any, messageId: string): Promise<string | null> {
+  const name = attachment.name || "unknown";
+  const url = attachment.url;
+
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+    if (!response.ok) {
+      console.warn(`[Relay] Failed to download attachment ${name}: HTTP ${response.status}`);
+      return null;
+    }
+
+    const contentLength = Number(response.headers.get("content-length") || 0);
+    if (contentLength > MAX_ATTACHMENT_DOWNLOAD_BYTES) {
+      console.warn(
+        `[Relay] Attachment ${name} too large to download (${contentLength} bytes, max ${MAX_ATTACHMENT_DOWNLOAD_BYTES})`,
+      );
+      return null;
+    }
+
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > MAX_ATTACHMENT_DOWNLOAD_BYTES) {
+      console.warn(`[Relay] Attachment ${name} body too large (${buffer.length} bytes), skipping download`);
+      return null;
+    }
+
+    // Sanitize filename: prefix with messageId to avoid collisions
+    const safeName = name.replace(/[^a-zA-Z0-9._-]/g, "_");
+    const localFilename = `${messageId || Date.now()}-${safeName}`;
+    const localPath = join(ATTACHMENT_DIR, localFilename);
+    writeFileSync(localPath, buffer);
+    console.log(`[Relay] Downloaded attachment ${name} (${buffer.length} bytes) -> ${localPath}`);
+    return localPath;
+  } catch (err: unknown) {
+    console.warn(`[Relay] Error downloading attachment ${name}: ${(err as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * Fetch attachment content for inclusion in the message.
+ * Text files are inlined; binary files are downloaded to disk for Claude to read.
+ */
+export async function fetchAttachmentContent(attachment: any, messageId: string): Promise<string> {
+  const name = attachment.name || "";
+  const ext = name.split(".").pop()?.toLowerCase() || "";
+  const url = attachment.url;
+
+  if (!TEXT_ATTACHMENT_EXTENSIONS.has(ext)) {
+    // Non-text file: download to local disk so Claude Code can read it via file path
+    const localPath = await downloadAttachmentToLocal(attachment, messageId);
+    if (localPath) {
+      return `Attachment: ${localPath}`;
+    }
+    // Fallback to URL if download failed
+    return `Attachment: ${url}`;
+  }
+
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!response.ok) {
+      console.warn(`[Relay] Failed to fetch attachment ${name}: HTTP ${response.status}`);
+      return `Attachment: ${url}`;
+    }
+
+    const contentLength = Number(response.headers.get("content-length") || 0);
+    if (contentLength > MAX_ATTACHMENT_INLINE_BYTES) {
+      console.warn(`[Relay] Attachment ${name} too large (${contentLength} bytes), including URL only`);
+      return `Attachment: ${url}`;
+    }
+
+    const text = await response.text();
+    if (text.length > MAX_ATTACHMENT_INLINE_BYTES) {
+      const truncated = text.slice(0, MAX_ATTACHMENT_INLINE_BYTES);
+      console.warn(`[Relay] Attachment ${name} content truncated to ${MAX_ATTACHMENT_INLINE_BYTES} bytes`);
+      return `Attachment (${name}):\n\`\`\`\n${truncated}\n... [truncated]\n\`\`\``;
+    }
+
+    console.log(`[Relay] Inlined attachment ${name} (${text.length} bytes)`);
+    return `Attachment (${name}):\n\`\`\`\n${text}\n\`\`\``;
+  } catch (err: unknown) {
+    console.warn(`[Relay] Error fetching attachment ${name}: ${(err as Error).message}`);
+    return `Attachment: ${url}`;
+  }
+}

package/server/busy-notify.ts

@@ -0,0 +1,69 @@
+/**
+ * Busy queue notification: send a Discord message when Claude is working on another task
+ * and a new message arrives.
+ */
+
+import {
+  BUSY_NOTIFY_COOLDOWN_MS,
+  BUSY_NOTIFY_MIN_DURATION_MS,
+  BUSY_NOTIFY_ON_QUEUE,
+  CLAUDE_AGENT_ID,
+  DISCORD_SESSION_ID,
+  MESSAGE_ROUTING_MODE,
+} from "./config.ts";
+import { getCurrentAgentActivity } from "./db.ts";
+
+// Deduplicate busy queue notifications per activity window
+const busyQueueNotifyCache = new Map<string, number>();
+
+function isWaitActivity(row: any): boolean {
+  const text = `${row?.activity_type || ""} ${row?.activity_summary || ""}`.toLowerCase();
+  return text.includes("wait-for-discord-messages");
+}
+
+function isSleepActivity(row: any): boolean {
+  const text = `${row?.activity_type || ""} ${row?.activity_summary || ""}`.toLowerCase();
+  return /\bsleep\b/.test(text);
+}
+
+export function maybeNotifyBusyQueued(message: any, client: any, persistOutbound: (...args: any[]) => any) {
+  if (!BUSY_NOTIFY_ON_QUEUE) return;
+
+  // In channel routing mode, check the channel's subagent activity, not the orchestrator
+  const channelAgentId = MESSAGE_ROUTING_MODE === "channel" ? message.channelId : null;
+  const activity = channelAgentId
+    ? getCurrentAgentActivity(DISCORD_SESSION_ID, CLAUDE_AGENT_ID, channelAgentId)
+    : (getCurrentAgentActivity(DISCORD_SESSION_ID, CLAUDE_AGENT_ID) as any);
+  if (!activity || activity.status !== "busy") return;
+  if (isWaitActivity(activity)) return;
+  if (isSleepActivity(activity)) return;
+
+  // Only notify if the current activity has been running long enough to warrant it.
+  // Short operations finish quickly and the agent will naturally address the message via steering prompts.
+  const activityStart = activity.started_at ? new Date(activity.started_at).getTime() : 0;
+  const now = Date.now();
+  if (activityStart && now - activityStart < BUSY_NOTIFY_MIN_DURATION_MS) return;
+
+  const activityKey = `${message.channelId}:${activity.started_at || activity.updated_at || activity.activity_summary || activity.activity_type || "busy"}`;
+  const lastSent = busyQueueNotifyCache.get(activityKey) || 0;
+  if (now - lastSent < BUSY_NOTIFY_COOLDOWN_MS) return;
+  busyQueueNotifyCache.set(activityKey, now);
+
+  const content = "👋 Got your message — I'll address it when my current task finishes.";
+
+  void (async () => {
+    try {
+      const channel = await client.channels.fetch(message.channelId);
+      if (!channel || !channel.isTextBased()) return;
+      const sent = await channel.send(content);
+      persistOutbound({
+        content,
+        channelId: message.channelId,
+        externalId: sent.id,
+        fromAgent: "relay",
+      });
+    } catch {
+      // best effort only
+    }
+  })();
+}

package/server/config.ts

@@ -0,0 +1,121 @@
+/**
+ * Configuration: load env vars and export typed settings for the relay server.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const ROOT_DIR = join(__dirname, "..");
+export const DATA_DIR = join(ROOT_DIR, "data");
+
+// User config directory (~/.config/cc-discord by default, override with CC_DISCORD_CONFIG_DIR)
+const CONFIG_DIR =
+  process.env.CC_DISCORD_CONFIG_DIR ||
+  join(process.env.HOME || "", ".config", "cc-discord");
+
+// Preferred split env file for relay process; legacy fallback for compatibility.
+// Precedence: ROOT_DIR > CONFIG_DIR (loadDotEnv skips keys already set)
+loadDotEnv(join(ROOT_DIR, ".env.relay"));
+loadDotEnv(join(CONFIG_DIR, ".env.relay"));
+loadDotEnv(join(ROOT_DIR, ".env"));
+loadDotEnv(join(CONFIG_DIR, ".env"));
+
+export const DISCORD_BOT_TOKEN = process.env.DISCORD_BOT_TOKEN;
+export const DEFAULT_CHANNEL_ID = process.env.DISCORD_CHANNEL_ID;
+
+export const ALLOWED_CHANNEL_IDS = (process.env.DISCORD_ALLOWED_CHANNEL_IDS || "")
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+export const IGNORED_CHANNEL_IDS = new Set(
+  (process.env.DISCORD_IGNORED_CHANNEL_IDS || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean),
+);
+
+export const ALLOWED_DISCORD_USER_IDS = (process.env.ALLOWED_DISCORD_USER_IDS || "")
+  .split(",")
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+export const DISCORD_SESSION_ID = process.env.DISCORD_SESSION_ID || "default";
+export const CLAUDE_AGENT_ID = process.env.CLAUDE_AGENT_ID || "claude";
+
+/**
+ * Message routing mode:
+ * - 'channel' (default): route inbound messages to to_agent=channelId (orchestrator/subagent mode)
+ * - 'agent': route to to_agent=CLAUDE_AGENT_ID (legacy single-agent mode)
+ */
+export const MESSAGE_ROUTING_MODE = String(process.env.MESSAGE_ROUTING_MODE || "channel")
+  .toLowerCase()
+  .trim();
+
+export const RELAY_HOST = process.env.RELAY_HOST || "127.0.0.1";
+export const RELAY_PORT = Number(process.env.RELAY_PORT || 3199);
+export const RELAY_API_TOKEN = process.env.RELAY_API_TOKEN || "";
+export const RELAY_ALLOW_NO_AUTH = String(process.env.RELAY_ALLOW_NO_AUTH || "false").toLowerCase() === "true";
+
+export const TYPING_INTERVAL_MS = Number(process.env.TYPING_INTERVAL_MS || 8000);
+export const TYPING_MAX_MS = Number(process.env.TYPING_MAX_MS || 120000);
+export const THINKING_FALLBACK_ENABLED =
+  String(process.env.THINKING_FALLBACK_ENABLED || "true").toLowerCase() !== "false";
+export const THINKING_FALLBACK_TEXT =
+  process.env.THINKING_FALLBACK_TEXT || "Still working on that—thanks for your patience.";
+
+export const BUSY_NOTIFY_ON_QUEUE = String(process.env.BUSY_NOTIFY_ON_QUEUE || "true").toLowerCase() !== "false";
+export const BUSY_NOTIFY_COOLDOWN_MS = Number(process.env.BUSY_NOTIFY_COOLDOWN_MS || 30000);
+/** Only send a busy notification if the current activity has been running for at least this long (ms). */
+export const BUSY_NOTIFY_MIN_DURATION_MS = Number(process.env.BUSY_NOTIFY_MIN_DURATION_MS || 30000);
+
+// ── Live Trace Thread ───────────────────────────────────────────────
+export const TRACE_THREAD_ENABLED =
+  String(process.env.TRACE_THREAD_ENABLED || "true").toLowerCase() !== "false";
+export const TRACE_THREAD_NAME = process.env.TRACE_THREAD_NAME || "🔍 Agent Trace";
+export const TRACE_FLUSH_INTERVAL_MS = Number(process.env.TRACE_FLUSH_INTERVAL_MS || 3000);
+
+export const MAX_ATTACHMENT_INLINE_BYTES = Number(process.env.MAX_ATTACHMENT_INLINE_BYTES || 100_000);
+export const MAX_ATTACHMENT_DOWNLOAD_BYTES = Number(process.env.MAX_ATTACHMENT_DOWNLOAD_BYTES || 10_000_000);
+export const ATTACHMENT_TTL_MS = Number(process.env.ATTACHMENT_TTL_MS || 3_600_000);
+
+export const ATTACHMENT_DIR = join("/tmp", "cc-discord", "attachments");
+
+function loadDotEnv(path: string) {
+  if (!existsSync(path)) return;
+  const raw = readFileSync(path, "utf8");
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line || line.trim().startsWith("#")) continue;
+    const idx = line.indexOf("=");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (!(key in process.env)) {
+      process.env[key] = value;
+    }
+  }
+}
+
+export function validateConfig() {
+  if (!DISCORD_BOT_TOKEN) {
+    console.error("Missing DISCORD_BOT_TOKEN (set in .env.relay or env var).");
+    process.exit(1);
+  }
+
+  if (!DEFAULT_CHANNEL_ID) {
+    console.error("Missing DISCORD_CHANNEL_ID (set in .env.relay or env var).");
+    process.exit(1);
+  }
+
+  if (!RELAY_API_TOKEN && !RELAY_ALLOW_NO_AUTH) {
+    console.error(
+      "Missing RELAY_API_TOKEN. Set RELAY_API_TOKEN in .env.relay (recommended), or explicitly set RELAY_ALLOW_NO_AUTH=true for local-only dev.",
+    );
+    process.exit(1);
+  }
+}