@gswangg/duncan-cc 0.1.0

package/src/discovery.ts

@@ -0,0 +1,340 @@
+/**
+ * Session Discovery
+ * 
+ * Finds CC session files on disk, supports routing modes:
+ * - project: all sessions in the same project dir (same cwd)
+ * - global: all sessions across all projects
+ * - specific: a named session file
+ * 
+ * Also discovers subagent transcripts.
+ */
+
+import { readdirSync, statSync, existsSync, openSync, readSync, closeSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { homedir } from "node:os";
+
+// ============================================================================
+// Path resolution — mirrors CC's path layout
+// ============================================================================
+
+/** Get CC's projects directory */
+export function getProjectsDir(): string {
+  return join(homedir(), ".claude", "projects");
+}
+
+/** Get project dir for a given cwd (hashed) */
+export function getProjectDir(cwd: string): string | null {
+  const projectsDir = getProjectsDir();
+  if (!existsSync(projectsDir)) return null;
+
+  // CC hashes the cwd into the directory name
+  // The format is: the cwd with / replaced by - and leading - stripped
+  // e.g., /Users/foo/bar → -Users-foo-bar
+  const hashed = cwd.replace(/\//g, "-");
+
+  const fullPath = join(projectsDir, hashed);
+  if (existsSync(fullPath)) return fullPath;
+
+  // Try to find by scanning (the hash might differ slightly)
+  try {
+    const dirs = readdirSync(projectsDir, { withFileTypes: true });
+    for (const d of dirs) {
+      if (!d.isDirectory()) continue;
+      // Check if the directory name ends with the last component(s) of cwd
+      if (d.name === hashed || d.name.endsWith(hashed)) {
+        return join(projectsDir, d.name);
+      }
+    }
+  } catch {}
+
+  return null;
+}
+
+// ============================================================================
+// Session file discovery
+// ============================================================================
+
+export interface SessionFileInfo {
+  path: string;
+  sessionId: string;
+  mtime: Date;
+  size: number;
+  projectDir: string;
+}
+
+/** List all session files in a project directory */
+export function listSessionFiles(projectDir: string): SessionFileInfo[] {
+  if (!existsSync(projectDir)) return [];
+
+  try {
+    const entries = readdirSync(projectDir, { withFileTypes: true });
+    const sessions: SessionFileInfo[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+      const fullPath = join(projectDir, entry.name);
+      try {
+        const stat = statSync(fullPath);
+        sessions.push({
+          path: fullPath,
+          sessionId: entry.name.replace(".jsonl", ""),
+          mtime: stat.mtime,
+          size: stat.size,
+          projectDir,
+        });
+      } catch {}
+    }
+
+    // Sort by mtime, newest first
+    sessions.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+    return sessions;
+  } catch {
+    return [];
+  }
+}
+
+/** List all session files across all projects */
+export function listAllSessionFiles(): SessionFileInfo[] {
+  const projectsDir = getProjectsDir();
+  if (!existsSync(projectsDir)) return [];
+
+  const allSessions: SessionFileInfo[] = [];
+
+  try {
+    const projectDirs = readdirSync(projectsDir, { withFileTypes: true });
+    for (const d of projectDirs) {
+      if (!d.isDirectory()) continue;
+      const sessions = listSessionFiles(join(projectsDir, d.name));
+      allSessions.push(...sessions);
+    }
+  } catch {}
+
+  // Sort by mtime, newest first
+  allSessions.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return allSessions;
+}
+
+/** List subagent transcript files for a session */
+export function listSubagentFiles(sessionFile: string): SessionFileInfo[] {
+  const sessionId = basename(sessionFile, ".jsonl");
+  const sessionDir = join(dirname(sessionFile), sessionId, "subagents");
+
+  if (!existsSync(sessionDir)) return [];
+
+  const files: SessionFileInfo[] = [];
+
+  try {
+    // Subagents can be in subdirectories
+    function scanDir(dir: string) {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+          try {
+            const stat = statSync(fullPath);
+            files.push({
+              path: fullPath,
+              sessionId: entry.name.replace(".jsonl", ""),
+              mtime: stat.mtime,
+              size: stat.size,
+              projectDir: dirname(sessionFile),
+            });
+          } catch {}
+        } else if (entry.isDirectory()) {
+          scanDir(fullPath);
+        }
+      }
+    }
+    scanDir(sessionDir);
+  } catch {}
+
+  return files;
+}
+
+// ============================================================================
+// Routing
+// ============================================================================
+
+export type RoutingMode = "project" | "global" | "session" | "self" | "ancestors";
+
+export interface RoutingParams {
+  mode: RoutingMode;
+  /** For "project" mode: the cwd to find sessions for */
+  cwd?: string;
+  /** For "project" mode: explicit project dir path */
+  projectDir?: string;
+  /** For "session" mode: specific session file path or ID */
+  sessionId?: string;
+  /** Include subagent transcripts */
+  includeSubagents?: boolean;
+  /** Max sessions to return */
+  limit?: number;
+  /** Offset for pagination */
+  offset?: number;
+}
+
+export interface RoutingResult {
+  sessions: SessionFileInfo[];
+  totalCount: number;
+  hasMore: boolean;
+}
+
+/** Resolve session files based on routing parameters */
+export function resolveSessionFiles(params: RoutingParams): RoutingResult {
+  const limit = params.limit ?? 50;
+  const offset = params.offset ?? 0;
+  let allSessions: SessionFileInfo[];
+
+  switch (params.mode) {
+    case "project": {
+      const projectDir = params.projectDir ?? (params.cwd ? getProjectDir(params.cwd) : null);
+      if (!projectDir) {
+        return { sessions: [], totalCount: 0, hasMore: false };
+      }
+      allSessions = listSessionFiles(projectDir);
+
+      // Optionally include subagents
+      if (params.includeSubagents) {
+        const withSubagents: SessionFileInfo[] = [];
+        for (const s of allSessions) {
+          withSubagents.push(s);
+          withSubagents.push(...listSubagentFiles(s.path));
+        }
+        allSessions = withSubagents;
+      }
+      break;
+    }
+
+    case "global": {
+      allSessions = listAllSessionFiles();
+      break;
+    }
+
+    case "session": {
+      if (!params.sessionId) {
+        return { sessions: [], totalCount: 0, hasMore: false };
+      }
+      // Try as full path first
+      if (existsSync(params.sessionId)) {
+        const stat = statSync(params.sessionId);
+        allSessions = [{
+          path: params.sessionId,
+          sessionId: basename(params.sessionId, ".jsonl"),
+          mtime: stat.mtime,
+          size: stat.size,
+          projectDir: dirname(params.sessionId),
+        }];
+      } else {
+        // Try to find by session ID across all projects
+        const all = listAllSessionFiles();
+        allSessions = all.filter((s) => s.sessionId === params.sessionId);
+      }
+      break;
+    }
+
+    default:
+      return { sessions: [], totalCount: 0, hasMore: false };
+  }
+
+  const totalCount = allSessions.length;
+  const sessions = allSessions.slice(offset, offset + limit);
+  const hasMore = offset + limit < totalCount;
+
+  return { sessions, totalCount, hasMore };
+}
+
+// ============================================================================
+// Self-exclusion — find the calling session by toolUseId
+// ============================================================================
+
+/** Size of tail chunk to scan for toolUseId (bytes). */
+const TAIL_SCAN_BYTES = 32_768;
+
+/**
+ * Scan the tail of a JSONL file for a tool_use ID string.
+ * Returns true if found. Only reads the last TAIL_SCAN_BYTES of the file
+ * to keep I/O minimal — the tool_use that triggered the MCP call will be
+ * near the very end of the active session file.
+ */
+function tailContains(filePath: string, needle: string): boolean {
+  let fd: number | undefined;
+  try {
+    const stat = statSync(filePath);
+    const size = stat.size;
+    if (size === 0) return false;
+
+    const readSize = Math.min(size, TAIL_SCAN_BYTES);
+    const offset = size - readSize;
+    const buf = Buffer.alloc(readSize);
+
+    fd = openSync(filePath, "r");
+    readSync(fd, buf, 0, readSize, offset);
+    closeSync(fd);
+    fd = undefined;
+
+    return buf.includes(needle);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch {}
+    }
+  }
+}
+
+/**
+ * Find the session that contains a specific tool_use ID.
+ * 
+ * When CC calls an MCP tool, it writes the assistant message (containing
+ * the tool_use block) to the session JSONL *before* invoking the tool.
+ * CC passes the tool_use ID in the MCP request's `_meta` field as
+ * `"claudecode/toolUseId"`. We scan the tail of candidate session files
+ * to find the one containing that ID — that's the calling session.
+ * 
+ * @param toolUseId  The tool_use ID from MCP request `_meta`
+ * @param candidates Session files to search (pre-filtered by routing mode)
+ * @returns The matching session's ID, or null if not found
+ */
+export function findCallingSession(
+  toolUseId: string,
+  candidates: SessionFileInfo[],
+): string | null {
+  if (!toolUseId) return null;
+
+  for (const session of candidates) {
+    if (tailContains(session.path, toolUseId)) {
+      return session.sessionId;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve session files with self-exclusion.
+ * 
+ * Like `resolveSessionFiles` but also accepts a `toolUseId` to identify
+ * and exclude the calling session from results.
+ */
+export function resolveSessionFilesExcludingSelf(
+  params: RoutingParams & { toolUseId?: string },
+): RoutingResult & { excludedSessionId: string | null } {
+  const result = resolveSessionFiles(params);
+
+  if (!params.toolUseId || result.sessions.length === 0) {
+    return { ...result, excludedSessionId: null };
+  }
+
+  const excludedId = findCallingSession(params.toolUseId, result.sessions);
+  if (!excludedId) {
+    return { ...result, excludedSessionId: null };
+  }
+
+  const filtered = result.sessions.filter((s) => s.sessionId !== excludedId);
+  return {
+    sessions: filtered,
+    totalCount: result.totalCount - 1,
+    hasMore: result.hasMore,
+    excludedSessionId: excludedId,
+  };
+}

package/src/mcp-server.ts

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+/**
+ * Duncan CC — MCP Server
+ * 
+ * Exposes duncan session querying as an MCP tool that Claude Code can call.
+ * Uses stdio transport.
+ * 
+ * Usage:
+ *   npx tsx src/mcp-server.ts
+ *   # or after build:
+ *   node dist/mcp-server.js
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { processSessionFile, processSessionWindows } from "./pipeline.js";
+import { resolveSessionFiles, resolveSessionFilesExcludingSelf, getProjectsDir, listAllSessionFiles } from "./discovery.js";
+import { querySingleWindow, queryBatch, querySelf, queryAncestors } from "./query.js";
+
+// ============================================================================
+// Server setup
+// ============================================================================
+
+const server = new Server(
+  { name: "duncan-cc", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+// ============================================================================
+// Tool definitions
+// ============================================================================
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "duncan_query",
+      description:
+        "Query dormant Claude Code sessions to recall information from previous conversations. " +
+        "Loads session context and asks the target session's model whether it has relevant information. " +
+        "Use when you need to find something discussed in a previous CC session.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          question: {
+            type: "string",
+            description: "The question to ask previous sessions. Be specific and self-contained.",
+          },
+          mode: {
+            type: "string",
+            enum: ["project", "global", "session", "self", "ancestors"],
+            description:
+              "Routing mode. 'project': sessions from a specific project dir. " +
+              "'global': all sessions across all projects (newest first). " +
+              "'session': a specific session file. " +
+              "'self': query own active window N times for sampling diversity. " +
+              "'ancestors': query own prior compaction windows (excluding active).",
+          },
+          projectDir: {
+            type: "string",
+            description: "For 'project' mode: explicit project directory path. If omitted, uses cwd.",
+          },
+          sessionId: {
+            type: "string",
+            description: "For 'session' mode: session file path or session ID.",
+          },
+          cwd: {
+            type: "string",
+            description: "Working directory for context resolution (CLAUDE.md, git status). Defaults to process.cwd().",
+          },
+          limit: {
+            type: "number",
+            description: "Max sessions to query (default: 10).",
+          },
+          offset: {
+            type: "number",
+            description: "Skip this many sessions for pagination (default: 0).",
+          },
+          includeSubagents: {
+            type: "boolean",
+            description: "Include subagent transcripts in search (default: false).",
+          },
+          copies: {
+            type: "number",
+            description: "For 'self' mode: number of parallel queries for sampling diversity (default: 3).",
+          },
+        },
+        required: ["question", "mode"],
+      },
+    },
+    {
+      name: "duncan_list_sessions",
+      description: "List available Claude Code sessions. Use to discover sessions before querying.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          mode: {
+            type: "string",
+            enum: ["project", "global"],
+            description: "'project': sessions from a project dir. 'global': all sessions.",
+          },
+          projectDir: {
+            type: "string",
+            description: "For 'project' mode: project directory path.",
+          },
+          cwd: {
+            type: "string",
+            description: "For 'project' mode: working directory to resolve project dir.",
+          },
+          limit: {
+            type: "number",
+            description: "Max sessions to list (default: 20).",
+          },
+        },
+        required: ["mode"],
+      },
+    },
+  ],
+}));
+
+// ============================================================================
+// Tool handlers
+// ============================================================================
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args, _meta } = request.params;
+
+  // CC passes tool_use ID in _meta — used for self-exclusion
+  const toolUseId = (_meta as Record<string, unknown> | undefined)?.["claudecode/toolUseId"] as string | undefined;
+
+  switch (name) {
+    case "duncan_query":
+      return handleDuncanQuery(args as any, toolUseId);
+    case "duncan_list_sessions":
+      return handleListSessions(args as any);
+    default:
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true,
+      };
+  }
+});
+
+async function handleDuncanQuery(args: {
+  question: string;
+  mode: string;
+  projectDir?: string;
+  sessionId?: string;
+  cwd?: string;
+  limit?: number;
+  offset?: number;
+  includeSubagents?: boolean;
+  copies?: number;
+}, toolUseId?: string) {
+  try {
+    // Self mode: query own active window N times for sampling diversity
+    if (args.mode === "self") {
+      if (!toolUseId) {
+        return {
+          content: [{ type: "text", text: "Self mode requires toolUseId from _meta (only available when called from CC)." }],
+          isError: true,
+        };
+      }
+      const result = await querySelf(args.question, {
+        toolUseId,
+        copies: args.copies ?? 3,
+        apiKey: undefined,
+      });
+
+      if (result.results.length === 0) {
+        return {
+          content: [{ type: "text", text: "Could not find calling session for self-query." }],
+          isError: true,
+        };
+      }
+
+      // Format: show all N answers
+      const answers = result.results.map((r, i) => {
+        return `### Sample ${i + 1}\n${r.result.answer}\n*— ${r.model}*`;
+      }).join("\n\n---\n\n");
+
+      const contextCount = result.results.filter(r => r.result.hasContext).length;
+      return {
+        content: [{ type: "text", text: `**${args.question}** (${result.results.length} samples)\n\n${answers}\n\n*${contextCount}/${result.results.length} had relevant context. queryId: ${result.queryId}*` }],
+      };
+    }
+
+    // Ancestors mode: query prior compaction windows of the calling session
+    if (args.mode === "ancestors") {
+      if (!toolUseId) {
+        return {
+          content: [{ type: "text", text: "Ancestors mode requires toolUseId from _meta (only available when called from CC)." }],
+          isError: true,
+        };
+      }
+      const result = await queryAncestors(args.question, {
+        toolUseId,
+        limit: args.limit ?? 50,
+        offset: args.offset ?? 0,
+        apiKey: undefined,
+      });
+
+      if (result.results.length === 0) {
+        return {
+          content: [{ type: "text", text: "No ancestor windows found. This session has no compaction boundaries." }],
+        };
+      }
+
+      const withContext = result.results.filter(r => r.result.hasContext);
+      const relevant = withContext.length > 0 ? withContext : result.results;
+
+      const answers = relevant.map((r) => {
+        const label = relevant.length === 1 ? "" : `### Window ${r.windowIndex}\n`;
+        return `${label}${r.result.answer}\n*— ${r.model}*`;
+      }).join("\n\n---\n\n");
+
+      const parts = [`**${args.question}**\n\n${answers}`];
+
+      if (result.hasMore) {
+        const nextOffset = (args.offset ?? 0) + (args.limit ?? 50);
+        const remaining = result.totalWindows - nextOffset;
+        parts.push(`\n\n---\n*Queried ${result.results.length} of ${result.totalWindows} windows. ${remaining} more available — call again with offset: ${nextOffset}.*`);
+      }
+
+      const contextCount = withContext.length;
+      parts.push(`\n\n*${contextCount}/${result.results.length} windows had relevant context. queryId: ${result.queryId}*`);
+
+      return { content: [{ type: "text", text: parts.join("") }] };
+    }
+
+    const result = await queryBatch(
+      args.question,
+      {
+        mode: args.mode as any,
+        projectDir: args.projectDir,
+        sessionId: args.sessionId,
+        cwd: args.cwd,
+        limit: args.limit ?? 10,
+        offset: args.offset ?? 0,
+        includeSubagents: args.includeSubagents ?? false,
+        toolUseId, // for self-exclusion
+      },
+      {
+        apiKey: undefined,
+      },
+    );
+
+    if (result.results.length === 0) {
+      return {
+        content: [{ type: "text", text: "No sessions found matching the routing criteria." }],
+      };
+    }
+
+    const errors = result.results.filter((r) => r.result.answer.startsWith("Error: "));
+    const nonErrors = result.results.filter((r) => !r.result.answer.startsWith("Error: "));
+    const withContext = nonErrors.filter((r) => r.result.hasContext);
+    const relevant = withContext.length > 0 ? withContext : nonErrors.length > 0 ? nonErrors : result.results;
+
+    const answers = relevant
+      .map((r) => {
+        const label = relevant.length === 1
+          ? ""
+          : `### ${r.sessionId.slice(0, 12)} (window ${r.windowIndex})\n`;
+        const modelLine = `\n*— ${r.model}*`;
+        return `${label}${r.result.answer}${modelLine}`;
+      })
+      .join("\n\n---\n\n");
+
+    const parts = [`**${args.question}**\n\n${answers}`];
+
+    if (errors.length > 0) {
+      const errorLines = errors.map((r) => `- ${r.sessionId.slice(0, 12)} (window ${r.windowIndex}): ${r.result.answer}`).join("\n");
+      parts.push(`\n\n---\n**${errors.length} error(s):**\n${errorLines}`);
+    }
+
+    if (result.hasMore) {
+      const nextOffset = (args.offset ?? 0) + (args.limit ?? 10);
+      const remaining = result.totalWindows - nextOffset;
+      parts.push(
+        `\n\n---\n*Queried ${result.results.length} of ${result.totalWindows} windows. ${remaining} more available — call again with offset: ${nextOffset}.*`,
+      );
+    }
+
+    const contextCount = withContext.length;
+    const totalCount = result.results.length;
+    parts.push(`\n\n*${contextCount}/${totalCount} sessions had relevant context. queryId: ${result.queryId}*`);
+
+    return {
+      content: [{ type: "text", text: parts.join("") }],
+    };
+  } catch (err: any) {
+    return {
+      content: [{ type: "text", text: `Duncan query error: ${err.message}` }],
+      isError: true,
+    };
+  }
+}
+
+async function handleListSessions(args: {
+  mode: string;
+  projectDir?: string;
+  cwd?: string;
+  limit?: number;
+}) {
+  try {
+    const resolved = resolveSessionFiles({
+      mode: args.mode as any,
+      projectDir: args.projectDir,
+      cwd: args.cwd,
+      limit: args.limit ?? 20,
+    });
+
+    if (resolved.sessions.length === 0) {
+      return {
+        content: [{ type: "text", text: "No sessions found." }],
+      };
+    }
+
+    const lines = resolved.sessions.map((s) => {
+      const date = s.mtime.toISOString().slice(0, 16);
+      const size = s.size > 1024 * 1024
+        ? `${(s.size / 1024 / 1024).toFixed(1)}MB`
+        : `${(s.size / 1024).toFixed(0)}KB`;
+      return `${s.sessionId.slice(0, 12)}  ${date}  ${size}  ${s.projectDir.split("/").slice(-1)[0]}`;
+    });
+
+    const header = `${resolved.totalCount} sessions${resolved.hasMore ? ` (showing ${resolved.sessions.length})` : ""}:`;
+    return {
+      content: [{ type: "text", text: `${header}\n\n${lines.join("\n")}` }],
+    };
+  } catch (err: any) {
+    return {
+      content: [{ type: "text", text: `Error listing sessions: ${err.message}` }],
+      isError: true,
+    };
+  }
+}
+
+// ============================================================================
+// Start server
+// ============================================================================
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("duncan-cc MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});