brainiac 0.0.6 → 0.0.8

data/bin/brainiac-completion.bash

@@ -9,7 +9,7 @@ _brainiac() {
   local brainiac_dir="${BRAINIAC_DIR:-$HOME/.brainiac}"
 
   # Top-level commands
-  local commands="server stop restart logs status register unregister list show brain discord cron provider role agent config path version help setup projects card-map"
+  local commands="server stop restart logs status register unregister list show brain discord cron provider role agent config path version help setup projects card-map handler"
 
   # Helper: list agent keys from registry
   _brainiac_agents() {

data/lib/brainiac/agents.rb

@@ -7,10 +7,10 @@
 #
 #   {
 #     "galen": {
-#       "fizzy_name": "Galen",
+#       "display_name": "Galen",
 #       "local": true,
 #       "env": {
-#         "FIZZY_TOKEN": "fizzy_abc...",
+#         "SOME_TOKEN": "token_abc...",
 #         "DISCORD_BOT_TOKEN": "Bot_abc..."
 #       }
 #     }
@@ -20,49 +20,26 @@
 # (card assignments). Agents without "local": true are still known for
 # mention detection, display names, tokens, and cross-agent interactions —
 # they just won't pick up card assignments on this machine.
-#
-# Legacy format with top-level `fizzy_token` / `discord_bot_token` keys is
-# auto-migrated into the `env` hash at load time.
-
 def load_agent_registry
-  if File.exist?(AGENT_REGISTRY_FILE)
-    raw_registry = JSON.parse(File.read(AGENT_REGISTRY_FILE))
-    LOG.info "Loaded agent registry (#{raw_registry.size} agents) from #{AGENT_REGISTRY_FILE}"
-
-    # Normalize keys: convert to lowercase, replace non-alphanumeric with hyphens
-    registry = {}
-    raw_registry.each do |key, entry|
-      normalized_key = key.downcase.gsub(/[^a-z0-9-]/, "-")
-      if registry.key?(normalized_key) && registry[normalized_key] != entry
-        LOG.warn "Duplicate agent key after normalization: '#{key}' → '#{normalized_key}' (already exists)"
-      end
-      registry[normalized_key] = entry
-    end
-
-    # Migrate legacy keys into env hash
-    registry.each_value do |entry|
-      next unless entry.is_a?(Hash)
-
-      entry["env"] ||= {}
-      # Migrate fizzy_token → FIZZY_TOKEN
-      if (ft = entry.delete("fizzy_token"))
-        entry["env"]["FIZZY_TOKEN"] ||= ft
-      end
-      # Migrate discord_bot_token → DISCORD_BOT_TOKEN
-      if (dt = entry.delete("discord_bot_token"))
-        entry["env"]["DISCORD_BOT_TOKEN"] ||= dt
-      end
-    end
-    return registry
+  unless File.exist?(AGENT_REGISTRY_FILE)
+    LOG.info "No agent registry found at #{AGENT_REGISTRY_FILE}"
+    return {}
   end
 
-  if File.exist?(AGENT_TOKENS_FILE)
-    tokens = JSON.parse(File.read(AGENT_TOKENS_FILE))
-    LOG.info "Loaded legacy agent tokens (#{tokens.size} agents) from #{AGENT_TOKENS_FILE}"
-    return tokens.transform_values { |token| { "env" => { "FIZZY_TOKEN" => token } } }
+  raw_registry = JSON.parse(File.read(AGENT_REGISTRY_FILE))
+  LOG.info "Loaded agent registry (#{raw_registry.size} agents) from #{AGENT_REGISTRY_FILE}"
+
+  # Normalize keys: convert to lowercase, replace non-alphanumeric with hyphens
+  registry = {}
+  raw_registry.each do |key, entry|
+    normalized_key = key.downcase.gsub(/[^a-z0-9-]/, "-")
+    if registry.key?(normalized_key) && registry[normalized_key] != entry
+      LOG.warn "Duplicate agent key after normalization: '#{key}' → '#{normalized_key}' (already exists)"
+    end
+    registry[normalized_key] = entry
   end
 
-  {}
+  registry
 rescue JSON::ParserError => e
   LOG.error "Failed to parse agent registry: #{e.message}"
   {}
@@ -93,30 +70,17 @@ def agent_env_var(agent_name, var_name)
   agent_env_for(agent_name)[var_name]
 end
 
-# Convenience: get the Fizzy token for an agent.
-def fizzy_token_for(agent_name)
-  agent_env_var(agent_name, "FIZZY_TOKEN")
-end
-
-# Convenience: build env hash for fizzy CLI calls (backward compat).
-# Falls back to default agent token when the given agent has no token.
-def fizzy_env_for(agent_name)
-  token = fizzy_token_for(agent_name) || fizzy_token_for(AI_AGENT_NAME)
-  token ? { "FIZZY_TOKEN" => token } : {}
-end
-
-def default_fizzy_env
-  fizzy_env_for(AI_AGENT_NAME)
-end
-
-def fizzy_display_name(agent_name)
+# Get the display name for an agent (from agents.json registry).
+# This is the human-readable canonical name (e.g., "GLaDOS" not "glados").
+# Core owns this — it's the identity used across all channels and plugins.
+def agent_display_name(agent_name)
   return agent_name unless agent_name
 
   key = agent_name.downcase.gsub(/[^a-z0-9-]/, "-")
   entry = AGENT_REGISTRY[key]
   return agent_name unless entry.is_a?(Hash)
 
-  entry["fizzy_name"] || agent_name
+  entry["display_name"] || agent_name
 end
 
 # Get the role name(s) configured for an agent in agents.json.
@@ -155,7 +119,7 @@ end
 
 def agent_roster
   roster = {}
-  all_agent_names.each { |name| roster[name.downcase] = fizzy_display_name(name) }
+  all_agent_names.each { |name| roster[name.downcase] = agent_display_name(name) }
   roster
 end
 
@@ -176,9 +140,9 @@ def all_agent_names
   names = Set.new([AI_AGENT_NAME])
   PROJECTS.each_value { |config| names << config["agent_name"] if config["agent_name"] }
   discover_kiro_agents.each { |name| names << name.capitalize }
-  # Include agents from the registry (with their fizzy_name if specified)
+  # Include agents from the registry
   AGENT_REGISTRY.each do |key, entry|
-    names << (entry["fizzy_name"] || key.capitalize)
+    names << (entry["display_name"] || key.capitalize)
   end
   names
 end
@@ -198,7 +162,7 @@ def local_agent_names
   AGENT_REGISTRY.each do |key, entry|
     next unless entry.is_a?(Hash) && entry["local"]
 
-    names << (entry["fizzy_name"] || key.capitalize)
+    names << (entry["display_name"] || key.capitalize)
   end
   names
 end
@@ -209,7 +173,7 @@ def detect_mentioned_agent(text)
   all_agent_names.each do |name|
     return name if downcased.include?("@#{name.downcase}")
 
-    # Fizzy renders mentions using first name only (e.g. "@Sleeper" not "@Sleeper Service").
+    # Some systems render mentions using first name only (e.g. "@Sleeper" not "@Sleeper Service").
     # Fall back to matching the first word of multi-word agent names.
     first_word = name.split.first.downcase
     next if first_word == name.downcase # already checked above
@@ -218,17 +182,6 @@ def detect_mentioned_agent(text)
   nil
 end
 
-def detect_mentioned_user_ids(text)
-  return [] unless FIZZY_CONFIG["authorized_users"]
-
-  mentioned_ids = []
-  FIZZY_CONFIG["authorized_users"].each do |user|
-    name = user["name"]
-    mentioned_ids << user["id"] if text.downcase.include?("@#{name.downcase}")
-  end
-  mentioned_ids
-end
-
 def comment_from_agent?(name)
   return false unless name
 

data/lib/brainiac/brain.rb

@@ -162,9 +162,6 @@ def build_brain_context(agent_name: AI_AGENT_NAME, card_title: "", card_number:
   primary_query = topics.first(5).join(" ")
   primary_query = "project conventions" if primary_query.empty?
 
-  fizzy_mentioned = [card_title, comment_body].any? { |s| s&.match?(/fizzy/i) }
-  fizzy_originated = source == :fizzy
-
   search_queries = [primary_query]
 
   knowledge_threads = [
@@ -173,9 +170,12 @@ def build_brain_context(agent_name: AI_AGENT_NAME, card_title: "", card_number:
   ]
   search_queries << agent_name
 
-  if fizzy_mentioned || fizzy_originated
-    knowledge_threads << Thread.new { query_brain("fizzy CLI commands", scope: :knowledge, max_results: 2) }
-    search_queries << "fizzy CLI commands"
+  # Plugin hook: source-specific brain queries (e.g., plugins inject source-specific knowledge)
+  plugin_queries = Brainiac.emit(:build_brain_context,
+                                 source: source, card_title: card_title, comment_body: comment_body)
+  plugin_queries.flatten.compact.each do |query|
+    knowledge_threads << Thread.new { query_brain(query, scope: :knowledge, max_results: 2) }
+    search_queries << query
   end
 
   persona_thread = Thread.new { query_brain("personality tone voice communication style", agent_name: agent_name, scope: :persona, max_results: 5) }

data/lib/brainiac/config.rb

@@ -15,21 +15,46 @@ BRAINIAC_VERSION = Brainiac::VERSION
 
 # --- Environment & paths ---
 
-FIZZY_WEBHOOK_SECRET = ENV.fetch("FIZZY_WEBHOOK_SECRET", nil)
-AI_AGENT_NAME = ENV.fetch("AI_AGENT_NAME") do
-  case RbConfig::CONFIG["host_os"]
-  when /darwin/i then "Kaylee"
-  else "Galen"
-  end
-end
-
 BRAINIAC_DIR = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
 PROJECTS_FILE = File.join(BRAINIAC_DIR, "projects.json")
 KIRO_AGENTS_DIR = File.join(Dir.home, ".kiro", "agents")
-CARD_MAP_FILE   = File.join(BRAINIAC_DIR, "card_map.json")
-AGENT_TOKENS_FILE = File.join(BRAINIAC_DIR, "agent_tokens.json")
+WORK_ITEM_MAP_FILE = File.join(BRAINIAC_DIR, "work_items.json")
 AGENT_REGISTRY_FILE = File.join(BRAINIAC_DIR, "agents.json")
 
+# --- Master config (handler toggles, global settings) ---
+
+BRAINIAC_CONFIG_FILE = File.join(BRAINIAC_DIR, "brainiac.json")
+
+def load_brainiac_config
+  return {} unless File.exist?(BRAINIAC_CONFIG_FILE)
+
+  JSON.parse(File.read(BRAINIAC_CONFIG_FILE))
+rescue JSON::ParserError => e
+  LOG.error "Failed to parse brainiac.json: #{e.message}" if defined?(LOG)
+  {}
+end
+
+BRAINIAC_CONFIG = load_brainiac_config
+
+# --- Default agent name ---
+# Priority: AI_AGENT_NAME env var → brainiac.json "default_agent" → error.
+AI_AGENT_NAME = ENV.fetch("AI_AGENT_NAME", nil) || BRAINIAC_CONFIG["default_agent"] || begin
+  raise <<~MSG
+    No default agent configured. Set one of:
+      1. Environment variable: export AI_AGENT_NAME="YourAgent"
+      2. In ~/.brainiac/brainiac.json: { "default_agent": "YourAgent" }
+  MSG
+end
+
+# Check whether a handler is enabled. Defaults to true when brainiac.json
+# doesn't exist or doesn't list the handler (backwards compatible — all on).
+def handler_enabled?(name)
+  handlers = BRAINIAC_CONFIG["handlers"]
+  return true unless handlers # No config = everything enabled
+
+  handlers.fetch(name.to_s, true)
+end
+
 LOG_LEVEL = ENV.fetch("LOG_LEVEL", "info").downcase
 LOG = Logger.new($stdout)
 LOG.level = case LOG_LEVEL
@@ -53,21 +78,6 @@ KNOWLEDGE_COLLECTION = "brainiac-knowledge"
 
 ROLES_DIR = File.join(BRAINIAC_DIR, "roles")
 
-# --- Fizzy auth ---
-
-FIZZY_CONFIG_FILE = File.join(BRAINIAC_DIR, "fizzy.json")
-
-def load_fizzy_config
-  return {} unless File.exist?(FIZZY_CONFIG_FILE)
-
-  JSON.parse(File.read(FIZZY_CONFIG_FILE))
-rescue JSON::ParserError => e
-  LOG.error "Failed to parse Fizzy config: #{e.message}"
-  {}
-end
-
-FIZZY_CONFIG = load_fizzy_config
-
 # --- GitHub auth ---
 
 GITHUB_CONFIG_FILE = File.join(BRAINIAC_DIR, "github.json")
@@ -84,57 +94,10 @@ end
 GITHUB_CONFIG = load_github_config
 
 def github_webhook_secret
-  # Fallback to env var for backwards compatibility
+  # Fallback to env var
   GITHUB_CONFIG["webhook_secret"] || ENV.fetch("GITHUB_WEBHOOK_SECRET", nil)
 end
 
-# --- Board config ---
-
-FIZZY_BOARDS = FIZZY_CONFIG["boards"] || {}
-
-def board_config(board_key)
-  FIZZY_BOARDS[board_key.to_s]
-end
-
-def board_webhook_secret(board_key)
-  config = board_config(board_key)
-  config&.dig("webhook_secret") || FIZZY_WEBHOOK_SECRET
-end
-
-def board_column_id(board_key, column_name)
-  config = board_config(board_key)
-  config&.dig("columns", column_name.to_s)
-end
-
-# Find board_key by board_id (from .fizzy.yaml or payload)
-def board_key_for_id(board_id)
-  FIZZY_BOARDS.each do |key, config|
-    return key if config["board_id"] == board_id
-  end
-  nil
-end
-
-# Determine board_key for a project by reading its .fizzy.yaml
-def board_key_for_project(project_config)
-  fizzy_yaml = File.join(project_config["repo_path"], ".fizzy.yaml")
-  return nil unless File.exist?(fizzy_yaml)
-
-  require "yaml"
-  data = YAML.safe_load_file(fizzy_yaml)
-  board_id = data["board"]
-  board_key_for_id(board_id)
-rescue StandardError => e
-  LOG.warn "Could not read .fizzy.yaml for board lookup: #{e.message}"
-  nil
-end
-
-# Build authorized user IDs from config or env var (env var overrides)
-AUTHORIZED_USER_IDS = if ENV["AUTHORIZED_USER_IDS"] && !ENV["AUTHORIZED_USER_IDS"].empty?
-                        ENV["AUTHORIZED_USER_IDS"].split(",").map(&:strip)
-                      else
-                        (FIZZY_CONFIG["authorized_users"] || []).map { |u| u["id"] }
-                      end
-
 NOTIFICATION_COMMAND = ENV.fetch("NOTIFICATION_COMMAND", nil)
 
 # --- Projects ---
@@ -185,8 +148,10 @@ PROJECTS = load_projects_config
 
 DEFAULT_PROJECT = {
   "repo_path" => ENV.fetch("REPO_PATH", Dir.pwd),
-  "fizzy_tags" => [],
   "github_repo" => ENV.fetch("GITHUB_REPO", nil),
+  # CLI defaults below are overridden by ~/.brainiac/cli-providers/*.json when a
+  # cli_provider is configured on the project or agent. These only apply as a
+  # last-resort fallback when no provider config exists.
   "agent_cli" => ENV.fetch("AGENT_CLI", "kiro-cli"),
   "agent_cli_args" => ENV.fetch("AGENT_CLI_ARGS", "chat --trust-all-tools --no-interactive"),
   "agent_model_flag" => ENV["AGENT_MODEL_FLAG"] || "--model",
@@ -208,8 +173,7 @@ DEFAULT_PROJECT = {
 }.freeze
 
 # --- Discord (optional) ---
-# Discord is enabled when any agent in the registry has a discord_bot_token,
-# OR when the legacy DISCORD_BOT_TOKEN env var is set.
+# Discord is enabled when any agent in the registry has a discord_bot_token
 # Requires the websocket-client-simple gem.
 
 DISCORD_ENABLED = begin

data/lib/brainiac/handlers/discord/api.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+# Discord REST API helpers.
+#
+# Low-level HTTP methods and convenience wrappers for the Discord v10 API.
+# Used by the Discord handler itself, but also by GitHub (deploy notifications)
+# and Zoho (email notifications).
+
+DISCORD_API_BASE = "https://discord.com/api/v10"
+
+# Emojis reserved for brainiac functionality — not treated as feedback
+RESERVED_EMOJIS = %w[👀 ❌ 🛑 🚫 ⚠️ ⏳ 😶 ❔ ❓ 🧠].freeze
+
+def discord_api(method, path, token:, body: nil, log_errors: true)
+  uri = URI("#{DISCORD_API_BASE}#{path}")
+  http = Net::HTTP.new(uri.host, uri.port)
+  http.use_ssl = true
+
+  req = case method
+        when :get    then Net::HTTP::Get.new(uri)
+        when :post   then Net::HTTP::Post.new(uri)
+        when :put    then Net::HTTP::Put.new(uri)
+        when :delete then Net::HTTP::Delete.new(uri)
+        end
+
+  req["Authorization"] = "Bot #{token}"
+  req["Content-Type"] = "application/json"
+  req.body = body.to_json if body
+
+  response = http.request(req)
+
+  if response.code.to_i == 429
+    retry_after = JSON.parse(response.body)["retry_after"] || 1
+    LOG.warn "Discord rate limited, waiting #{retry_after}s"
+    sleep retry_after
+    return discord_api(method, path, token: token, body: body, log_errors: log_errors)
+  end
+
+  LOG.error "Discord API error (#{method} #{path}): HTTP #{response.code} - #{response.body}" if response.code.to_i >= 400 && log_errors
+
+  JSON.parse(response.body) unless response.body.nil? || response.body.empty?
+rescue StandardError => e
+  LOG.error "Discord API error (#{method} #{path}): #{e.message}" if log_errors
+  nil
+end
+
+# --- Channel & Message Operations ---
+
+def fetch_discord_channel_history(channel_id, before_message_id, token:, limit: 10)
+  messages = discord_api(:get, "/channels/#{channel_id}/messages?before=#{before_message_id}&limit=#{limit}", token: token)
+
+  all_messages = messages.is_a?(Array) ? messages : []
+
+  # If we're in a thread, check if the oldest message is a THREAD_STARTER_MESSAGE (type 21).
+  # These messages have no content but point to the original message via referenced_message.
+  # We need to include that original message for full context.
+  if all_messages.any?
+    oldest = all_messages.last # API returns newest-first
+    all_messages << oldest["referenced_message"] if oldest && oldest["type"] == 21 && oldest["referenced_message"]
+  end
+
+  return "" if all_messages.empty?
+
+  # Messages come newest-first from the API, reverse for chronological order
+  lines = all_messages.reverse.filter_map do |msg|
+    author = msg.dig("author", "username") || "unknown"
+    content = msg["content"]&.strip || ""
+    next if content.empty?
+
+    "#{author}: #{content}"
+  end
+
+  return "" if lines.empty?
+
+  lines.join("\n")
+rescue StandardError => e
+  LOG.warn "Failed to fetch channel history: #{e.message}"
+  ""
+end
+
+def fetch_channel_info(channel_id, token:)
+  discord_api(:get, "/channels/#{channel_id}", token: token)
+end
+
+def fetch_discord_message(channel_id, message_id, token:, log_errors: true)
+  discord_api(:get, "/channels/#{channel_id}/messages/#{message_id}", token: token, log_errors: log_errors)
+end
+
+def fetch_guild_member(guild_id, user_id, token:)
+  discord_api(:get, "/guilds/#{guild_id}/members/#{user_id}", token: token)
+end
+
+# --- Messaging ---
+
+def send_discord_message(channel_id, content, token:, reply_to: nil)
+  body = { content: content }
+  body[:message_reference] = { message_id: reply_to } if reply_to
+  result = discord_api(:post, "/channels/#{channel_id}/messages", token: token, body: body)
+  if result && result["id"]
+    LOG.info "[Discord] Message posted successfully to channel #{channel_id}, message_id: #{result["id"]}"
+  else
+    LOG.error "[Discord] Failed to post message to channel #{channel_id}, result: #{result.inspect}"
+  end
+  result
+end
+
+def send_long_discord_message(channel_id, content, token:, reply_to: nil)
+  if content.length <= 2000
+    send_discord_message(channel_id, content, token: token, reply_to: reply_to)
+    return
+  end
+
+  chunks = []
+  remaining = content
+  while remaining.length.positive?
+    if remaining.length <= 2000
+      chunks << remaining
+      remaining = ""
+    else
+      split_at = remaining.rindex("\n", 1990) || 1990
+      chunks << remaining[0...split_at]
+      remaining = remaining[split_at..].lstrip
+    end
+  end
+
+  chunks.each_with_index do |chunk, i|
+    send_discord_message(channel_id, chunk, token: token, reply_to: i.zero? ? reply_to : nil)
+    sleep 0.5
+  end
+end
+
+def send_discord_typing(channel_id, token:)
+  discord_api(:post, "/channels/#{channel_id}/typing", token: token)
+end
+
+# --- Reactions ---
+
+def add_discord_reaction(channel_id, message_id, emoji, token:)
+  encoded = URI.encode_www_form_component(emoji)
+  discord_api(:put, "/channels/#{channel_id}/messages/#{message_id}/reactions/#{encoded}/@me", token: token)
+end
+
+def remove_discord_reaction(channel_id, message_id, emoji, token:)
+  encoded = URI.encode_www_form_component(emoji)
+  discord_api(:delete, "/channels/#{channel_id}/messages/#{message_id}/reactions/#{encoded}/@me", token: token)
+end
+
+# --- Threads & Forums ---
+
+def create_discord_thread(channel_id, message_id, name:, token:)
+  thread_name = name.length > 100 ? "#{name[0..96]}..." : name
+  discord_api(:post, "/channels/#{channel_id}/messages/#{message_id}/threads", token: token, body: {
+                name: thread_name,
+                auto_archive_duration: 1440
+              })
+end
+
+def forum_channel?(channel_id, token:)
+  info = fetch_channel_info(channel_id, token: token)
+  info && info["type"] == 15
+end
+
+def find_latest_forum_thread(channel_id, token:)
+  channel_info = fetch_channel_info(channel_id, token: token)
+  return nil unless channel_info && channel_info["guild_id"]
+
+  guild_id = channel_info["guild_id"]
+  result = discord_api(:get, "/guilds/#{guild_id}/threads/active", token: token)
+  return nil unless result && result["threads"]
+
+  forum_threads = result["threads"]
+                  .select { |t| t["parent_id"] == channel_id }
+                  .sort_by { |t| t["id"].to_i }
+                  .reverse
+
+  return nil if forum_threads.empty?
+
+  latest = forum_threads.first
+  LOG.info "[Discord] Found latest forum thread: #{latest["id"]} (#{latest["name"]}) in channel #{channel_id}"
+  latest
+end
+
+def create_forum_post(channel_id, title:, content:, token:)
+  thread_name = title.length > 100 ? "#{title[0..96]}..." : title
+  result = discord_api(:post, "/channels/#{channel_id}/threads", token: token, body: {
+                         name: thread_name,
+                         message: { content: content },
+                         auto_archive_duration: 1440
+                       })
+  if result && result["id"]
+    LOG.info "[Discord] Forum post created in channel #{channel_id}, thread_id: #{result["id"]}"
+  else
+    LOG.error "[Discord] Failed to create forum post in channel #{channel_id}, result: #{result.inspect}"
+  end
+  result
+end

data/lib/brainiac/handlers/discord/config.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# Discord configuration and shared state.
+#
+# Constants, config loading, and thread map persistence used across
+# all Discord sub-modules.
+
+DISCORD_CONFIG_FILE = File.join(BRAINIAC_DIR, "discord.json")
+
+# Discord thread worktree map: tracks worktrees created for Discord thread conversations.
+# Keyed by "agent_key:channel_id" → { worktree, branch, project, created_at }
+# Persisted to disk so sessions survive restarts.
+DISCORD_THREAD_MAP_FILE = File.join(BRAINIAC_DIR, "discord_thread_map.json")
+DISCORD_THREAD_MAP_MUTEX = Mutex.new
+
+def load_discord_config
+  default = { "channel_mappings" => {}, "authorized_role_ids" => [], "authorized_user_ids" => [] }
+  return default unless File.exist?(DISCORD_CONFIG_FILE)
+
+  JSON.parse(File.read(DISCORD_CONFIG_FILE))
+rescue JSON::ParserError => e
+  LOG.error "Failed to parse discord config: #{e.message}"
+  default
+end
+
+DISCORD_CONFIG = load_discord_config
+
+def reload_discord_config!
+  DISCORD_CONFIG.replace(load_discord_config)
+end
+
+# Collect all agent Discord bot tokens from the registry.
+# Returns { "galen" => "token...", "glados" => "token..." }
+def discord_bot_tokens
+  tokens = {}
+  AGENT_REGISTRY.each do |key, entry|
+    next unless entry.is_a?(Hash)
+
+    token = (entry["env"] || {})["DISCORD_BOT_TOKEN"]
+    next unless token
+
+    tokens[key] = token
+  end
+  tokens
+end
+
+# --- Thread Map Persistence ---
+
+def load_discord_thread_map
+  return {} unless File.exist?(DISCORD_THREAD_MAP_FILE)
+
+  JSON.parse(File.read(DISCORD_THREAD_MAP_FILE))
+rescue JSON::ParserError
+  {}
+end
+
+def save_discord_thread_map(map)
+  File.write(DISCORD_THREAD_MAP_FILE, JSON.pretty_generate(map))
+end
+
+# --- Channel/Project Routing ---
+
+def find_project_for_discord_channel(channel_id)
+  mapping = DISCORD_CONFIG.dig("channel_mappings", channel_id)
+
+  unless mapping
+    default_project = DISCORD_CONFIG["default_project"]
+    mapping = { "project" => default_project } if default_project
+  end
+
+  return nil unless mapping
+
+  project_key = mapping["project"]
+  project_config = PROJECTS[project_key]
+  return nil unless project_config
+
+  [project_key, project_config, mapping]
+end
+
+# Find the root message for a conversation thread.
+# Walks back through message_reference chain to find the original message.
+def find_root_message(message, channel_id, bot_token)
+  current_msg = message
+  visited = Set.new
+  max_depth = 20
+  walked = false
+
+  max_depth.times do
+    msg_id = current_msg["id"]
+    return { id: msg_id, content: nil, author: nil } if visited.include?(msg_id)
+
+    visited << msg_id
+
+    ref = current_msg["message_reference"]
+    break unless ref
+
+    ref_msg_id = ref["message_id"]
+    ref_channel = ref["channel_id"] || channel_id
+    break unless ref_msg_id
+
+    referenced = discord_api(:get, "/channels/#{ref_channel}/messages/#{ref_msg_id}", token: bot_token)
+    break unless referenced
+
+    current_msg = referenced
+    walked = true
+  end
+
+  {
+    id: current_msg["id"],
+    content: walked ? current_msg["content"]&.strip : nil,
+    author: walked ? current_msg.dig("author", "username") : nil
+  }
+end
+
+# Build a Discord mention roster so the agent can @mention people and other bots.
+def discord_mention_roster
+  lines = []
+
+  DISCORD_BOTS_MUTEX.synchronize do
+    DISCORD_BOTS.each do |agent_key, info|
+      next unless info[:user_id]
+
+      display = agent_display_name(agent_key) || agent_key.capitalize
+      lines << "  - #{display}: `<@#{info[:user_id]}>`"
+    end
+  end
+
+  user_mappings = DISCORD_CONFIG["user_mappings"] || {}
+  user_mappings.each do |name, discord_id|
+    lines << "  - #{name}: `<@#{discord_id}>`"
+  end
+
+  lines.join("\n")
+end