@hoverlover/cc-discord 0.1.0

package/server/messages.ts

@@ -0,0 +1,111 @@
+/**
+ * Message persistence and formatting for inbound/outbound Discord messages.
+ */
+
+import { fetchAttachmentContent } from "./attachment.ts";
+import { CLAUDE_AGENT_ID, DEFAULT_CHANNEL_ID, DISCORD_SESSION_ID, MESSAGE_ROUTING_MODE } from "./config.ts";
+import { insertStmt } from "./db.ts";
+import { appendMemoryTurn } from "./memory.ts";
+
+export async function formatInboundMessage(message: any) {
+  const author = message.author?.username || message.author?.globalName || message.author?.id || "unknown";
+  const base = message.content?.trim() || "";
+  const attachments = [...message.attachments.values()];
+
+  let fullText = base;
+  if (attachments.length > 0) {
+    const attachmentLines = await Promise.all(attachments.map((a: any) => fetchAttachmentContent(a, message.id)));
+    const attachmentText = attachmentLines.join("\n");
+    fullText = fullText ? `${fullText}\n${attachmentText}` : attachmentText;
+  }
+
+  if (!fullText) {
+    fullText = "[No text content]";
+  }
+
+  return `${author}: ${fullText}`;
+}
+
+export async function persistInboundDiscordMessage(message: any) {
+  const normalizedContent = await formatInboundMessage(message);
+  // In channel mode, route to channelId so per-channel subagents consume independently.
+  // In agent mode (legacy), route to CLAUDE_AGENT_ID for single-agent consumption.
+  const targetAgent = MESSAGE_ROUTING_MODE === "agent" ? CLAUDE_AGENT_ID : message.channelId;
+
+  try {
+    insertStmt.run(
+      DISCORD_SESSION_ID,
+      `discord:${message.author?.id || "unknown"}`,
+      targetAgent,
+      "DISCORD_MESSAGE",
+      normalizedContent,
+      "discord",
+      message.id,
+      message.channelId,
+      0,
+    );
+
+    void appendMemoryTurn({
+      role: "user",
+      content: normalizedContent,
+      metadata: {
+        source: "discord",
+        messageId: message.id,
+        channelId: message.channelId,
+        authorId: message.author?.id || null,
+      },
+    });
+
+    console.log(`[Relay] queued Discord message ${message.id} -> ${targetAgent}`);
+  } catch (err: unknown) {
+    const msg = String((err as any)?.message || "");
+    if (msg.includes("UNIQUE constraint failed")) {
+      // Discord can re-deliver in edge cases; idempotent ignore
+      return;
+    }
+    console.error("[Relay] failed to persist inbound message:", (err as Error).message);
+  }
+}
+
+export function persistOutboundDiscordMessage({
+  content,
+  channelId,
+  externalId,
+  fromAgent,
+}: {
+  content: string;
+  channelId?: string;
+  externalId?: string;
+  fromAgent?: string;
+}) {
+  const normalizedContent = String(content);
+  const normalizedFromAgent = fromAgent || CLAUDE_AGENT_ID;
+  const normalizedChannelId = channelId || DEFAULT_CHANNEL_ID || "";
+
+  try {
+    insertStmt.run(
+      DISCORD_SESSION_ID,
+      normalizedFromAgent,
+      "discord",
+      "DISCORD_REPLY",
+      normalizedContent,
+      "relay-outbound",
+      externalId || null,
+      normalizedChannelId,
+      1,
+    );
+
+    void appendMemoryTurn({
+      role: "assistant",
+      content: normalizedContent,
+      metadata: {
+        source: "discord",
+        messageId: externalId || null,
+        channelId: normalizedChannelId,
+        fromAgent: normalizedFromAgent,
+      },
+    });
+  } catch (err: unknown) {
+    console.error("[Relay] failed to persist outbound message:", (err as Error).message);
+  }
+}

package/server/trace-thread.ts

@@ -0,0 +1,340 @@
+/**
+ * Live Trace Thread: creates a pinned thread per channel and posts batched
+ * trace events (tool calls, status changes) so users can watch the agent work.
+ *
+ * Architecture:
+ *   hooks write → trace_events table → flush loop reads → batches → posts to thread
+ */
+
+import {
+  ChannelType,
+  type Client,
+  type TextChannel,
+  type ThreadChannel,
+} from "discord.js";
+import {
+  TRACE_FLUSH_INTERVAL_MS,
+  TRACE_THREAD_ENABLED,
+  TRACE_THREAD_NAME,
+} from "./config.ts";
+import {
+  getPendingTraceEvents,
+  getTraceThreadId,
+  markTraceEventsPosted,
+  setTraceThreadId,
+  type TraceEvent,
+} from "./db.ts";
+
+// In-memory cache of channel → thread to avoid DB lookups every flush
+const threadCache = new Map<string, string>();
+
+// Channels that failed with access errors — skip for a cooldown period
+const failedChannels = new Map<string, number>();
+const FAILURE_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+
+let flushTimer: ReturnType<typeof setInterval> | null = null;
+
+// ── Thread lifecycle ────────────────────────────────────────────────
+
+/** Lock a thread if not already locked (idempotent). */
+async function ensureLocked(thread: ThreadChannel): Promise<void> {
+  try {
+    if (!thread.locked) await thread.setLocked(true);
+  } catch {
+    // best-effort — bot may lack MANAGE_THREADS
+  }
+}
+
+/**
+ * Find or create the trace thread for a channel. Locks the thread so
+ * only the bot (with MANAGE_THREADS) can post.
+ */
+async function ensureTraceThread(client: Client, channelId: string): Promise<ThreadChannel | null> {
+  // Skip channels that recently failed with access errors
+  const failedAt = failedChannels.get(channelId);
+  if (failedAt && Date.now() - failedAt < FAILURE_COOLDOWN_MS) return null;
+
+  // Check in-memory cache first
+  const cachedThreadId = threadCache.get(channelId);
+  if (cachedThreadId) {
+    try {
+      const thread = await client.channels.fetch(cachedThreadId);
+      if (thread && thread.isThread()) {
+        // Ensure thread is locked (idempotent — handles pre-existing unlocked threads)
+        await ensureLocked(thread as ThreadChannel);
+        return thread as ThreadChannel;
+      }
+    } catch {
+      // Thread was deleted or inaccessible; fall through to re-create
+      threadCache.delete(channelId);
+    }
+  }
+
+  // Check DB
+  const dbThreadId = getTraceThreadId(channelId);
+  if (dbThreadId) {
+    try {
+      const thread = await client.channels.fetch(dbThreadId);
+      if (thread && thread.isThread()) {
+        // Ensure thread is locked
+        await ensureLocked(thread as ThreadChannel);
+        threadCache.set(channelId, dbThreadId);
+        return thread as ThreadChannel;
+      }
+    } catch {
+      // Thread was deleted; fall through to create
+    }
+  }
+
+  // Create new thread
+  try {
+    const channel = await client.channels.fetch(channelId);
+    if (!channel || !channel.isTextBased() || channel.type !== ChannelType.GuildText) return null;
+
+    const textChannel = channel as TextChannel;
+    const thread = await textChannel.threads.create({
+      name: TRACE_THREAD_NAME,
+      autoArchiveDuration: 10080, // 7 days (max for non-boosted servers)
+      reason: "Live trace thread for agent activity",
+    });
+
+    // Lock the thread so only moderators (i.e. the bot) can send messages.
+    // Note: threads don't support permissionOverwrites — use setLocked() instead.
+    try {
+      await thread.setLocked(true);
+    } catch {
+      // May fail if bot lacks MANAGE_THREADS; continue anyway
+    }
+
+    // Pin an intro message
+    try {
+      const intro = await thread.send(
+        `📡 **${TRACE_THREAD_NAME}**\n` +
+          "This thread shows live agent activity — tool calls, status changes, and more.\n" +
+          "It updates automatically. You can watch here while chatting in the main channel.",
+      );
+      await intro.pin();
+    } catch {
+      // best effort
+    }
+
+    // Persist
+    setTraceThreadId(channelId, thread.id);
+    threadCache.set(channelId, thread.id);
+    return thread;
+  } catch (err) {
+    console.error(`[Trace] Failed to create trace thread for channel ${channelId}:`, err);
+    return null;
+  }
+}
+
+// ── Event formatting ────────────────────────────────────────────────
+
+const EVENT_ICONS: Record<string, string> = {
+  tool_start: "🔧",
+  tool_end: "✅",
+  thinking: "🧠",
+  status_busy: "⏳",
+  status_idle: "💤",
+  error: "❌",
+};
+
+function formatTraceEvent(event: TraceEvent): string {
+  const icon = EVENT_ICONS[event.event_type] || "📌";
+  const ts = formatTimestamp(event.created_at);
+
+  // Reasoning/thinking events get a distinct format
+  if (event.event_type === "thinking") {
+    const thought = event.summary ? cleanWhitespace(event.summary) : "";
+    return `${icon} \`${ts}\` ${thought}`;
+  }
+
+  const tool = event.tool_name ? `\`${event.tool_name}\`` : "";
+
+  // Tool start: ▶ marker with summary
+  if (event.event_type === "tool_start") {
+    const summary = event.summary ? ` — ${cleanWhitespace(event.summary)}` : "";
+    return `${icon} \`${ts}\` ▶ ${tool}${summary}`;
+  }
+
+  // Tool end: ✓ marker with elapsed time, no summary duplication
+  if (event.event_type === "tool_end") {
+    const elapsed = parseElapsed(event.summary);
+    const elapsedStr = elapsed !== null ? ` in ${formatElapsed(elapsed)}` : "";
+    return `${icon} \`${ts}\` ✓ ${tool} done${elapsedStr}`;
+  }
+
+  // Default format for other event types
+  const summary = event.summary ? ` — ${cleanWhitespace(event.summary)}` : "";
+  return `${icon} \`${ts}\` ${tool}${summary}`;
+}
+
+/** Parse "elapsed:1234|..." prefix from tool_end summary. Returns ms or null. */
+function parseElapsed(summary: string | null | undefined): number | null {
+  if (!summary) return null;
+  const match = summary.match(/^elapsed:(\d+)\|/);
+  if (!match) return null;
+  return parseInt(match[1], 10);
+}
+
+/** Format milliseconds into a human-friendly duration string */
+function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const secs = ms / 1000;
+  if (secs < 60) return `${secs.toFixed(1)}s`;
+  const mins = Math.floor(secs / 60);
+  const remSecs = Math.round(secs % 60);
+  return `${mins}m ${remSecs}s`;
+}
+
+function formatTimestamp(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit", second: "2-digit" });
+  } catch {
+    return iso;
+  }
+}
+
+/** Clean up text for display — convert literal \n to real newlines, preserve full content. */
+function cleanWhitespace(text: string): string {
+  return String(text || "")
+    .replace(/\\n/g, "\n")   // convert literal \n to real newlines
+    .replace(/[ \t]+/g, " ") // collapse horizontal whitespace (but keep newlines)
+    .trim();
+}
+
+// ── Flush loop ──────────────────────────────────────────────────────
+
+/**
+ * Read pending trace events from DB, group by channel, and post batched
+ * messages to each channel's trace thread.
+ */
+async function flushTraceEvents(client: Client) {
+  if (!TRACE_THREAD_ENABLED) return;
+
+  const events = getPendingTraceEvents(100);
+  if (!events.length) return;
+
+  // Group by channel
+  const byChannel = new Map<string, TraceEvent[]>();
+  for (const evt of events) {
+    const ch = evt.channel_id || "unknown";
+    const arr = byChannel.get(ch) || [];
+    arr.push(evt);
+    byChannel.set(ch, arr);
+  }
+
+  const postedIds: number[] = [];
+
+  for (const [channelId, channelEvents] of byChannel) {
+    if (channelId === "unknown") {
+      // Skip events without a channel; mark as posted to avoid infinite retry
+      postedIds.push(...channelEvents.map((e) => e.id));
+      continue;
+    }
+
+    // Filter out noisy events (wait-for-discord-messages, sleep)
+    const meaningful = channelEvents.filter((e) => {
+      const text = `${e.tool_name || ""} ${e.summary || ""}`.toLowerCase();
+      if (text.includes("wait-for-discord-messages")) return false;
+      if (/\bsleep\b/.test(text)) return false;
+      return true;
+    });
+
+    // Even if filtered out, mark all as posted
+    postedIds.push(...channelEvents.map((e) => e.id));
+
+    if (!meaningful.length) continue;
+
+    try {
+      const thread = await ensureTraceThread(client, channelId);
+      if (!thread) continue;
+
+      // Batch into a single message (Discord max 2000 chars)
+      const lines = meaningful.map(formatTraceEvent);
+      const batches = batchLines(lines, 1900);
+
+      for (const batch of batches) {
+        await thread.send(batch);
+      }
+    } catch (err) {
+      const code = (err as any)?.code;
+      if (code === 50001 || code === 50013) {
+        // Missing Access or Missing Permissions — clear cache and back off
+        console.warn(`[Trace] No access to trace thread for channel ${channelId} (${code}) — backing off 5m`);
+        threadCache.delete(channelId);
+        failedChannels.set(channelId, Date.now());
+      } else {
+        console.error(`[Trace] Failed to post trace events for channel ${channelId}:`, err);
+      }
+    }
+  }
+
+  markTraceEventsPosted(postedIds);
+}
+
+/** Split lines into batches that fit within maxLen characters.
+ *  Long lines are split across multiple batches instead of truncated. */
+function batchLines(lines: string[], maxLen: number): string[] {
+  const batches: string[] = [];
+  let current = "";
+
+  for (const line of lines) {
+    const next = current ? `${current}\n${line}` : line;
+    if (next.length > maxLen) {
+      if (current) batches.push(current);
+      // If a single line exceeds maxLen, split it into chunks
+      if (line.length > maxLen) {
+        let remaining = line;
+        while (remaining.length > maxLen) {
+          batches.push(remaining.slice(0, maxLen));
+          remaining = remaining.slice(maxLen);
+        }
+        current = remaining;
+      } else {
+        current = line;
+      }
+    } else {
+      current = next;
+    }
+  }
+
+  if (current) batches.push(current);
+  return batches;
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Start the periodic trace event flush loop.
+ * Call once after the Discord client is ready.
+ */
+export function startTraceFlushLoop(client: Client) {
+  if (!TRACE_THREAD_ENABLED) {
+    console.log("[Trace] Trace thread feature is disabled.");
+    return;
+  }
+
+  if (flushTimer) {
+    clearInterval(flushTimer);
+  }
+
+  console.log(`[Trace] Starting flush loop (interval: ${TRACE_FLUSH_INTERVAL_MS}ms)`);
+
+  flushTimer = setInterval(() => {
+    flushTraceEvents(client).catch((err) => {
+      console.error("[Trace] Flush error:", err);
+    });
+  }, TRACE_FLUSH_INTERVAL_MS);
+}
+
+/**
+ * Stop the flush loop (for graceful shutdown).
+ */
+export function stopTraceFlushLoop() {
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+}

package/server/typing.ts

@@ -0,0 +1,101 @@
+/**
+ * Discord typing indicator management.
+ * Tracks per-channel typing state; starts, stops, and times out indicators.
+ */
+
+import { THINKING_FALLBACK_ENABLED, THINKING_FALLBACK_TEXT, TYPING_INTERVAL_MS, TYPING_MAX_MS } from "./config.ts";
+
+// Channel typing state: channelId -> { interval, timeout }
+const typingSessions = new Map<
+  string,
+  { interval: ReturnType<typeof setInterval>; timeout: ReturnType<typeof setTimeout> }
+>();
+
+async function sendTypingOnce(client: any, channelId: string) {
+  if (!channelId || !client.user) return;
+  try {
+    const channel = await client.channels.fetch(channelId);
+    if (!channel || !channel.isTextBased() || typeof channel.sendTyping !== "function") return;
+    await channel.sendTyping();
+  } catch (err: unknown) {
+    const code = (err as any)?.code;
+    if (code === 50001 || code === 50013) {
+      // Missing Access or Missing Permissions — stop retrying this channel
+      console.warn(`[Relay] typing indicator stopped for channel ${channelId}: ${(err as Error).message}`);
+      const state = typingSessions.get(channelId);
+      if (state) {
+        clearInterval(state.interval);
+        clearTimeout(state.timeout);
+        typingSessions.delete(channelId);
+      }
+      return;
+    }
+    console.warn(`[Relay] typing indicator failed for channel ${channelId}: ${(err as Error).message}`);
+  }
+}
+
+async function sendThinkingFallback(client: any, channelId: string, persistOutbound: (...args: any[]) => any) {
+  if (!THINKING_FALLBACK_ENABLED) return;
+  if (!channelId || !client.user) return;
+  try {
+    const channel = await client.channels.fetch(channelId);
+    if (!channel || !channel.isTextBased()) return;
+    const sent = await channel.send(THINKING_FALLBACK_TEXT);
+    persistOutbound({
+      content: THINKING_FALLBACK_TEXT,
+      channelId,
+      externalId: sent.id,
+      fromAgent: "relay",
+    });
+    console.log(`[Relay] thinking fallback sent in channel ${channelId}`);
+  } catch (err: unknown) {
+    console.warn(`[Relay] thinking fallback failed for channel ${channelId}: ${(err as Error).message}`);
+  }
+}
+
+export function startTypingIndicator(client: any, channelId: string, persistOutbound: (...args: any[]) => any) {
+  if (!channelId) return;
+  if (typingSessions.has(channelId)) return;
+
+  const startedAt = Date.now();
+  const interval = setInterval(() => {
+    if (Date.now() - startedAt > TYPING_MAX_MS) {
+      stopTypingIndicator(client, channelId, persistOutbound, "max-duration", { sendFallback: true });
+      return;
+    }
+    void sendTypingOnce(client, channelId);
+  }, TYPING_INTERVAL_MS);
+
+  const timeout = setTimeout(() => {
+    stopTypingIndicator(client, channelId, persistOutbound, "timeout", { sendFallback: true });
+  }, TYPING_MAX_MS + 1000);
+
+  typingSessions.set(channelId, { interval, timeout });
+  void sendTypingOnce(client, channelId);
+  console.log(`[Relay] typing indicator started for channel ${channelId}`);
+}
+
+export function stopTypingIndicator(
+  client: any,
+  channelId: string,
+  persistOutbound: (...args: any[]) => any,
+  reason: string = "completed",
+  { sendFallback = false } = {},
+) {
+  const state = typingSessions.get(channelId);
+  if (!state) return;
+  clearInterval(state.interval);
+  clearTimeout(state.timeout);
+  typingSessions.delete(channelId);
+  console.log(`[Relay] typing indicator stopped for channel ${channelId} (${reason})`);
+
+  if (sendFallback) {
+    void sendThinkingFallback(client, channelId, persistOutbound);
+  }
+}
+
+export function stopAllTypingSessions(client: any, persistOutbound: (...args: any[]) => any) {
+  for (const [channelId] of typingSessions) {
+    stopTypingIndicator(client, channelId, persistOutbound, "shutdown");
+  }
+}

package/tools/memory-inspect.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+
+/**
+ * Inspect memory_turns for debugging retrieval issues.
+ *
+ * Usage:
+ *   node tools/memory-inspect.js                    # show summary + recent turns
+ *   node tools/memory-inspect.js --search mattermost # search for keyword
+ *   node tools/memory-inspect.js --all               # dump all turns
+ */
+
+import { Database as DatabaseSync } from "bun:sqlite";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = process.env.ORCHESTRATOR_DIR || join(__dirname, "..");
+const dbPath = join(ROOT_DIR, "data", "memory.db");
+
+const args = process.argv.slice(2);
+let searchTerm: string | null = null;
+let showAll = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--search" && args[i + 1]) searchTerm = args[++i];
+  else if (args[i] === "--all") showAll = true;
+  else if (!args[i].startsWith("-")) searchTerm = args[i];
+}
+
+const db = new DatabaseSync(dbPath);
+
+const total = (db.prepare("SELECT COUNT(*) c FROM memory_turns").get() as any).c;
+console.log(`total turns: ${total}`);
+
+const rs = db.prepare("SELECT * FROM memory_runtime_state").all() as any[];
+console.log(`runtime states: ${rs.length}`);
+for (const r of rs) {
+  console.log(
+    `  session=${r.session_key} ctx=${r.runtime_context_id} epoch=${r.runtime_epoch} updated=${r.updated_at}`,
+  );
+}
+
+const sessions = db.prepare("SELECT session_key, COUNT(*) c FROM memory_turns GROUP BY session_key").all() as any[];
+console.log(`sessions:`);
+for (const s of sessions) console.log(`  ${s.session_key}: ${s.c} turns`);
+
+if (searchTerm) {
+  const pattern = `%${searchTerm.toLowerCase()}%`;
+  const hits = db
+    .prepare(`
+    SELECT turn_index, role, content, created_at, metadata_json
+    FROM memory_turns
+    WHERE LOWER(content) LIKE ?
+    ORDER BY turn_index ASC
+  `)
+    .all(pattern) as any[];
+  console.log(`\nsearch "${searchTerm}": ${hits.length} hits`);
+  for (const t of hits) {
+    const meta = JSON.parse(t.metadata_json || "{}");
+    const rc = meta.runtimeContextId || "null";
+    const content = t.content.replace(/\n/g, " ").slice(0, 200);
+    console.log(`  [${t.turn_index}] ${t.created_at} rc=${rc} ${t.role}: ${content}`);
+  }
+} else if (showAll) {
+  const all = db
+    .prepare(`
+    SELECT turn_index, role, content, created_at, metadata_json
+    FROM memory_turns ORDER BY turn_index ASC
+  `)
+    .all() as any[];
+  for (const t of all) {
+    const meta = JSON.parse(t.metadata_json || "{}");
+    const rc = meta.runtimeContextId || "null";
+    const content = t.content.replace(/\n/g, " ").slice(0, 200);
+    console.log(`[${t.turn_index}] ${t.created_at} rc=${rc} ${t.role}: ${content}`);
+  }
+} else {
+  const recent = db
+    .prepare(`
+    SELECT turn_index, role, content, created_at, metadata_json
+    FROM memory_turns ORDER BY turn_index DESC LIMIT 20
+  `)
+    .all() as any[];
+  console.log(`\nlast 20 turns:`);
+  recent.reverse();
+  for (const t of recent) {
+    const meta = JSON.parse(t.metadata_json || "{}");
+    const rc = meta.runtimeContextId || "null";
+    const content = t.content.replace(/\n/g, " ").slice(0, 200);
+    console.log(`  [${t.turn_index}] ${t.created_at} rc=${rc} ${t.role}: ${content}`);
+  }
+}
+
+db.close();