compass-agent 2.0.4

package/src/lib/log.ts

@@ -0,0 +1,16 @@
+export function ts(): string {
+  return new Date().toISOString();
+}
+
+export function log(channel: string | null, ...args: unknown[]): void {
+  console.log(`${ts()} [${channel || "system"}]`, ...args);
+}
+
+export function logErr(channel: string | null, ...args: unknown[]): void {
+  console.error(`${ts()} [${channel || "system"}]`, ...args);
+}
+
+export function toSqliteDatetime(d: Date | string): string {
+  const date = typeof d === "string" ? new Date(d) : d;
+  return date.toISOString().replace("T", " ").replace(/\.\d+Z$/, "");
+}

package/src/lib/thread-context.ts

@@ -0,0 +1,99 @@
+/**
+ * Thread context extraction for bot mentions.
+ *
+ * When the bot is @mentioned in a thread, fetches the "gap" messages —
+ * messages between the bot's last reply and the current mention — so
+ * Claude has context of the conversation it missed.
+ */
+
+import { log, logErr } from "./log.ts";
+
+const MAX_GAP_MESSAGES = 50;
+
+export interface ThreadMessage {
+  user?: string;
+  text?: string;
+  ts: string;
+  bot_id?: string;
+}
+
+/**
+ * Pure logic: extract gap messages from a list of thread messages.
+ *
+ * Walks backwards from the end, collecting messages until it hits one
+ * from the bot (identified by `bot_id` field or `user === botUserId`).
+ * The current mention message is excluded. Returns up to 50 messages
+ * in chronological order.
+ */
+export function extractGapMessages(
+  messages: ThreadMessage[],
+  currentMessageTs: string,
+  botUserId: string | null,
+): ThreadMessage[] {
+  // Filter out the current mention message
+  const filtered = messages.filter((m) => m.ts !== currentMessageTs);
+
+  const gap: ThreadMessage[] = [];
+  for (let i = filtered.length - 1; i >= 0; i--) {
+    const msg = filtered[i];
+    if (msg.bot_id || (botUserId && msg.user === botUserId)) break;
+    gap.unshift(msg);
+    if (gap.length >= MAX_GAP_MESSAGES) break;
+  }
+
+  return gap;
+}
+
+/**
+ * Format gap messages into a context string for Claude's prompt.
+ */
+export function formatGapMessages(gap: ThreadMessage[]): string {
+  if (gap.length === 0) return "";
+
+  const lines = gap.map((m) => `<@${m.user || "unknown"}>: ${m.text || ""}`);
+  return (
+    "[Thread context — messages since my last reply]\n" +
+    lines.join("\n") +
+    "\n\n---\n"
+  );
+}
+
+/**
+ * Fetch thread replies from Slack and return formatted gap context.
+ *
+ * Returns an empty string if there are no gap messages or if the
+ * mention is not in a thread.
+ */
+export async function fetchThreadContext(
+  client: any,
+  channelId: string,
+  threadTs: string,
+  currentMessageTs: string,
+  botUserId: string | null,
+): Promise<string> {
+  try {
+    log(channelId, `Fetching thread context: threadTs=${threadTs} currentTs=${currentMessageTs} botUserId=${botUserId}`);
+
+    const result = await client.conversations.replies({
+      channel: channelId,
+      ts: threadTs,
+      limit: 200,
+    });
+
+    const messages: ThreadMessage[] = result.messages || [];
+    log(channelId, `Thread replies: ${messages.length} message(s) fetched`);
+
+    const gap = extractGapMessages(messages, currentMessageTs, botUserId);
+    log(channelId, `Thread context: ${gap.length} gap message(s) found`);
+
+    const formatted = formatGapMessages(gap);
+    if (formatted) {
+      log(channelId, `Thread context injected (${formatted.length} chars)`);
+    }
+
+    return formatted;
+  } catch (err: any) {
+    logErr(channelId, `Failed to fetch thread context: ${err.message}`);
+    return "";
+  }
+}

package/src/lib/worktree.ts

@@ -0,0 +1,103 @@
+import { execFileSync } from "child_process";
+import path from "path";
+import fs from "fs";
+import type { GitInfo, WorktreeResult } from "../types.ts";
+
+export function detectGitRepo(cwd: string): GitInfo {
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return { isGit: true, repoRoot: root };
+  } catch {
+    return { isGit: false, repoRoot: null };
+  }
+}
+
+export function branchNameFromThread(threadTs: string): string {
+  return `slack/${threadTs.replace(".", "-")}`;
+}
+
+export function createWorktree(repoRoot: string, threadTs: string, baseBranch?: string): WorktreeResult {
+  const branchName = branchNameFromThread(threadTs);
+  const treesDir = path.join(repoRoot, "trees");
+  const wtPath = path.join(treesDir, branchName.replace(/\//g, "-"));
+
+  if (!fs.existsSync(treesDir)) {
+    fs.mkdirSync(treesDir, { recursive: true });
+  }
+
+  if (!baseBranch) {
+    try {
+      baseBranch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: repoRoot,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      baseBranch = "main";
+    }
+  }
+
+  execFileSync("git", ["worktree", "add", "-b", branchName, wtPath, baseBranch], {
+    cwd: repoRoot,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  try {
+    execFileSync("git", ["worktree", "lock", wtPath, "--reason", `Slack thread: ${threadTs}`], {
+      cwd: repoRoot,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    // lock may fail if already locked, non-critical
+  }
+
+  return { worktreePath: wtPath, branchName };
+}
+
+export function removeWorktree(repoRoot: string, worktreePath: string, branchName: string): void {
+  try {
+    execFileSync("git", ["worktree", "unlock", worktreePath], {
+      cwd: repoRoot,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {}
+
+  execFileSync("git", ["worktree", "remove", worktreePath, "--force"], {
+    cwd: repoRoot,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  try {
+    execFileSync("git", ["branch", "-D", branchName], {
+      cwd: repoRoot,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {}
+}
+
+export function hasUncommittedChanges(worktreePath: string): boolean {
+  try {
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: worktreePath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return status.trim().length > 0;
+  } catch {
+    return true; // assume dirty if we can't check
+  }
+}
+
+export function copyEnvFiles(sourceDir: string, targetDir: string): void {
+  const envFiles = [".env", ".env.local", ".env.development"];
+  for (const f of envFiles) {
+    const src = path.join(sourceDir, f);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(targetDir, f));
+    }
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env bun
+
+/**
+ * Compass MCP Server
+ *
+ * Exposes bot management tools (reminders, teachings, etc.) via MCP stdio transport.
+ * Can run standalone or be spawned by the Claude CLI as an MCP server.
+ *
+ * Usage:
+ *   bun src/mcp/server.ts           # stdio transport (for Claude CLI)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CronExpressionParser } from "cron-parser";
+import { toSqliteDatetime } from "../lib/log.ts";
+
+// ── Database ────────────────────────────────────────────────
+import {
+  addReminder,
+  getDueReminders,
+  updateNextTrigger,
+  deactivateReminder,
+  getActiveReminders,
+  addTeaching,
+  getTeachings,
+  removeTeaching,
+  getTeachingCount,
+  getChannelDefault,
+  setChannelDefault,
+} from "../db.ts";
+
+// Context defaults from env (injected by stream-handler when spawning Claude CLI)
+const DEFAULT_CHANNEL_ID = process.env.SLACK_CHANNEL_ID || null;
+const DEFAULT_USER_ID = process.env.SLACK_USER_ID || null;
+const DEFAULT_BOT_USER_ID = process.env.SLACK_BOT_USER_ID || null;
+
+// ── Server ──────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: "compass",
+  version: "1.0.0",
+});
+
+// ── Reminder tools ──────────────────────────────────────────
+
+server.registerTool(
+  "claude_bot_create_reminder",
+  {
+    description:
+      "Create a scheduled reminder. For recurring reminders, provide a 5-field cron expression. For one-time reminders, provide an ISO 8601 datetime. The reminder will trigger Claude in the specified Slack channel at the scheduled time.",
+    inputSchema: {
+      channel_id: z.string().optional().describe("Slack channel ID (auto-detected from session context)"),
+      user_id: z.string().optional().describe("Slack user ID (auto-detected from session context)"),
+      bot_id: z.string().optional().describe("Bot user ID (auto-detected from session context)"),
+      content: z.string().describe("The task/action Claude should perform when the reminder fires"),
+      cron: z
+        .string()
+        .optional()
+        .describe("5-field cron expression for recurring reminders (e.g. '0 9 * * 1-5' for weekdays at 9am)"),
+      one_time_at: z
+        .string()
+        .optional()
+        .describe("ISO 8601 datetime for one-time reminders (e.g. '2026-02-17T15:00:00Z')"),
+    },
+  },
+  async (params: any) => {
+    const channel_id = params.channel_id || DEFAULT_CHANNEL_ID;
+    const user_id = params.user_id || DEFAULT_USER_ID;
+    const bot_id = params.bot_id || DEFAULT_BOT_USER_ID;
+
+    if (!channel_id || !user_id || !bot_id) {
+      return { content: [{ type: "text" as const, text: "Error: Missing channel_id, user_id, or bot_id and no session context available." }] };
+    }
+
+    const { content, cron, one_time_at } = params;
+
+    if (!cron && !one_time_at) {
+      return { content: [{ type: "text" as const, text: "Error: Provide either 'cron' (recurring) or 'one_time_at' (one-time)." }] };
+    }
+
+    let nextTriggerAt: string;
+    let cronExpression: string | null = null;
+    let oneTime = 0;
+
+    if (cron) {
+      try {
+        const interval = CronExpressionParser.parse(cron);
+        nextTriggerAt = toSqliteDatetime(interval.next().toDate());
+        cronExpression = cron;
+      } catch (err: any) {
+        return { content: [{ type: "text" as const, text: `Error: Invalid cron expression "${cron}": ${err.message}` }] };
+      }
+    } else {
+      const triggerDate = new Date(one_time_at);
+      if (isNaN(triggerDate.getTime())) {
+        return { content: [{ type: "text" as const, text: `Error: Invalid datetime "${one_time_at}".` }] };
+      }
+      if (triggerDate <= new Date()) {
+        return { content: [{ type: "text" as const, text: "Error: That time is in the past. Specify a future time." }] };
+      }
+      nextTriggerAt = toSqliteDatetime(triggerDate);
+      oneTime = 1;
+    }
+
+    const originalInput = cron ? `[MCP] ${content} (cron: ${cron})` : `[MCP] ${content} (at: ${one_time_at})`;
+    addReminder(channel_id, user_id, bot_id, content, originalInput, cronExpression, oneTime, nextTriggerAt);
+
+    const scheduleDesc = cronExpression ? `recurring (cron: ${cronExpression})` : "one-time";
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Reminder created.\nContent: ${content}\nSchedule: ${scheduleDesc}\nNext trigger: ${nextTriggerAt}\nChannel: ${channel_id}`,
+        },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "claude_bot_list_reminders",
+  {
+    description: "List all active reminders for a user.",
+    inputSchema: {
+      user_id: z.string().optional().describe("Slack user ID (auto-detected from session context)"),
+    },
+  },
+  async (params: any) => {
+    const user_id = params.user_id || DEFAULT_USER_ID;
+    if (!user_id) {
+      return { content: [{ type: "text" as const, text: "Error: Missing user_id and no session context available." }] };
+    }
+    const reminders = getActiveReminders(user_id);
+    if (reminders.length === 0) {
+      return { content: [{ type: "text" as const, text: "No active reminders." }] };
+    }
+
+    const lines = reminders.map((r) => {
+      const schedule = r.cron_expression ? `cron: ${r.cron_expression}` : "one-time";
+      return `#${r.id} — ${r.content} (${schedule}, next: ${r.next_trigger_at}, channel: ${r.channel_id})`;
+    });
+
+    return { content: [{ type: "text" as const, text: `Active reminders:\n${lines.join("\n")}` }] };
+  }
+);
+
+server.registerTool(
+  "claude_bot_delete_reminder",
+  {
+    description: "Deactivate/delete a reminder by its ID.",
+    inputSchema: {
+      reminder_id: z.number().describe("The reminder ID to deactivate"),
+    },
+  },
+  async ({ reminder_id }: any) => {
+    deactivateReminder(reminder_id);
+    return { content: [{ type: "text" as const, text: `Reminder #${reminder_id} deactivated.` }] };
+  }
+);
+
+// ── Teaching tools ──────────────────────────────────────────
+
+server.registerTool(
+  "claude_bot_add_teaching",
+  {
+    description:
+      "Add a team knowledge instruction. Teachings are injected into all future Claude sessions as system prompts, letting you customize bot behavior across the workspace.",
+    inputSchema: {
+      instruction: z.string().describe("The instruction/teaching to add"),
+      added_by: z.string().optional().describe("Slack user ID (auto-detected from session context)"),
+      workspace_id: z.string().optional().describe("Workspace ID (defaults to 'default')"),
+    },
+  },
+  async ({ instruction, added_by, workspace_id }: any) => {
+    const userId = added_by || DEFAULT_USER_ID;
+    if (!userId) {
+      return { content: [{ type: "text" as const, text: "Error: Missing added_by and no session context available." }] };
+    }
+    addTeaching(instruction, userId, workspace_id || "default");
+    const count = getTeachingCount(workspace_id || "default");
+    return {
+      content: [{ type: "text" as const, text: `Teaching added. Total active teachings: ${count.count}` }],
+    };
+  }
+);
+
+server.registerTool(
+  "claude_bot_list_teachings",
+  {
+    description: "List all active team knowledge instructions.",
+    inputSchema: {
+      workspace_id: z.string().optional().describe("Workspace ID (defaults to 'default')"),
+    },
+  },
+  async ({ workspace_id }: any) => {
+    const teachings = getTeachings(workspace_id || "default");
+    if (teachings.length === 0) {
+      return { content: [{ type: "text" as const, text: "No active teachings." }] };
+    }
+
+    const lines = teachings.map(
+      (t) => `#${t.id} — ${t.instruction} (by ${t.added_by}, ${t.created_at})`
+    );
+    return { content: [{ type: "text" as const, text: `Active teachings:\n${lines.join("\n")}` }] };
+  }
+);
+
+server.registerTool(
+  "claude_bot_remove_teaching",
+  {
+    description: "Remove a team knowledge instruction by its ID.",
+    inputSchema: {
+      teaching_id: z.number().describe("The teaching ID to remove"),
+    },
+  },
+  async ({ teaching_id }: any) => {
+    removeTeaching(teaching_id);
+    return { content: [{ type: "text" as const, text: `Teaching #${teaching_id} removed.` }] };
+  }
+);
+
+// ── Channel default CWD tools ───────────────────────────────
+
+server.registerTool(
+  "claude_bot_get_channel_cwd",
+  {
+    description: "Get the default working directory for a Slack channel.",
+    inputSchema: {
+      channel_id: z.string().optional().describe("Slack channel ID (auto-detected from session context)"),
+    },
+  },
+  async (params: any) => {
+    const channel_id = params.channel_id || DEFAULT_CHANNEL_ID;
+    if (!channel_id) {
+      return { content: [{ type: "text" as const, text: "Error: Missing channel_id and no session context available." }] };
+    }
+    const result = getChannelDefault(channel_id);
+    if (!result) {
+      return { content: [{ type: "text" as const, text: `No default CWD set for channel ${channel_id}.` }] };
+    }
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Channel ${channel_id} default CWD: ${result.cwd} (set by ${result.set_by}, updated ${result.updated_at})`,
+        },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  "claude_bot_set_channel_cwd",
+  {
+    description: "Set the default working directory for a Slack channel.",
+    inputSchema: {
+      channel_id: z.string().optional().describe("Slack channel ID (auto-detected from session context)"),
+      cwd: z.string().describe("Absolute path to set as the default working directory"),
+      set_by: z.string().optional().describe("Slack user ID (auto-detected from session context)"),
+    },
+  },
+  async ({ channel_id, cwd, set_by }: any) => {
+    const resolvedChannel = channel_id || DEFAULT_CHANNEL_ID;
+    const resolvedUser = set_by || DEFAULT_USER_ID;
+    if (!resolvedChannel) {
+      return { content: [{ type: "text" as const, text: "Error: Missing channel_id and no session context available." }] };
+    }
+    setChannelDefault(resolvedChannel, cwd, resolvedUser);
+    return { content: [{ type: "text" as const, text: `Channel ${resolvedChannel} default CWD set to: ${cwd}` }] };
+  }
+);
+
+// ── Start ───────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("compass MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("MCP server fatal error:", err);
+  process.exit(1);
+});

package/src/types.ts

@@ -0,0 +1,118 @@
+import type { ChildProcess } from "child_process";
+
+// ── Database row types ──────────────────────────────────────
+
+export interface SessionRow {
+  channel_id: string;
+  session_id: string;
+  persisted: number;
+  cwd: string | null;
+  user_id: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CwdHistoryRow {
+  path: string;
+  last_used: string;
+}
+
+export interface ChannelDefaultRow {
+  channel_id: string;
+  cwd: string;
+  set_by: string | null;
+  updated_at: string;
+}
+
+export interface TeachingRow {
+  id: number;
+  instruction: string;
+  added_by: string;
+  workspace_id: string;
+  created_at: string;
+  active: number;
+}
+
+export interface ReminderRow {
+  id: number;
+  channel_id: string;
+  user_id: string;
+  bot_id: string;
+  content: string;
+  original_input: string;
+  cron_expression: string | null;
+  one_time: number;
+  next_trigger_at: string;
+  active: number;
+  created_at: string;
+}
+
+export interface UsageLogRow {
+  id: number;
+  session_key: string;
+  user_id: string;
+  model: string | null;
+  input_tokens: number;
+  output_tokens: number;
+  total_cost_usd: number;
+  duration_ms: number;
+  num_turns: number;
+  created_at: string;
+}
+
+export interface WorktreeRow {
+  session_key: string;
+  repo_path: string;
+  worktree_path: string;
+  branch_name: string;
+  locked: number;
+  created_at: string;
+  last_active_at: string;
+  cleaned_up: number;
+}
+
+export interface FeedbackRow {
+  id: number;
+  session_key: string;
+  user_id: string;
+  sentiment: string;
+  message_ts: string | null;
+  created_at: string;
+}
+
+export interface TeachingCountRow {
+  count: number;
+}
+
+// ── Runtime types ───────────────────────────────────────────
+
+export type ActiveProcessMap = Map<string, ChildProcess>;
+
+export interface Ref<T> {
+  value: T;
+}
+
+export interface HandleClaudeStreamOpts {
+  channelId: string;
+  threadTs: string;
+  userText: string;
+  userId: string;
+  client: any;
+  spawnCwd: string;
+  isResume: boolean;
+  sessionId: string;
+  setStatus: (status: string | { status: string; loading_messages?: string[] }) => Promise<void>;
+  activeProcesses: ActiveProcessMap;
+  cachedTeamId: string | null;
+  botUserId: string | null;
+}
+
+export interface GitInfo {
+  isGit: boolean;
+  repoRoot: string | null;
+}
+
+export interface WorktreeResult {
+  worktreePath: string;
+  branchName: string;
+}