@cmdctrl/cursor-cli 0.2.1 → 0.2.2

package/dist/session-watcher.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Cursor CLI Session Watcher
+ *
+ * Polls cursor-agent JSONL transcript files for new messages and emits events.
+ * Used with the SDK's onWatchSession / onUnwatchSession hooks.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CursorSessionWatcher = void 0;
+const fs = __importStar(require("fs"));
+const session_discovery_1 = require("./session-discovery");
+const POLL_INTERVAL_MS = 500;
+const COMPLETION_DELAY_MS = 5000;
+class CursorSessionWatcher {
+    watchedSessions = new Map();
+    completionTimers = new Map();
+    pollTimer = null;
+    onEvent;
+    onCompletion;
+    constructor(onEvent, onCompletion) {
+        this.onEvent = onEvent;
+        this.onCompletion = onCompletion || null;
+    }
+    watchSession(sessionId, filePath) {
+        if (this.watchedSessions.has(sessionId))
+            return;
+        if (!fs.existsSync(filePath)) {
+            console.warn(`[CursorWatcher] File not found: ${filePath}`);
+            return;
+        }
+        try {
+            const stat = fs.statSync(filePath);
+            const messages = (0, session_discovery_1.parseTranscriptFile)(filePath);
+            const lastAgent = [...messages].reverse().find(m => m.role === 'agent');
+            this.watchedSessions.set(sessionId, {
+                sessionId,
+                filePath,
+                lastSize: stat.size,
+                processedCount: messages.length,
+                messageCount: messages.length,
+                lastMessage: lastAgent?.content.slice(0, 200) || '',
+            });
+            console.log(`[CursorWatcher] Started watching session ${sessionId} (${messages.length} existing messages)`);
+            if (!this.pollTimer)
+                this.startPolling();
+        }
+        catch (err) {
+            console.error(`[CursorWatcher] Failed to watch ${filePath}:`, err);
+        }
+    }
+    unwatchSession(sessionId) {
+        this.cancelCompletionTimer(sessionId);
+        if (this.watchedSessions.delete(sessionId)) {
+            console.log(`[CursorWatcher] Stopped watching session ${sessionId}`);
+        }
+        if (this.watchedSessions.size === 0 && this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    unwatchAll() {
+        for (const timer of this.completionTimers.values())
+            clearTimeout(timer);
+        this.completionTimers.clear();
+        this.watchedSessions.clear();
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    get watchCount() {
+        return this.watchedSessions.size;
+    }
+    startPolling() {
+        this.pollTimer = setInterval(() => {
+            for (const session of this.watchedSessions.values()) {
+                this.checkSession(session);
+            }
+        }, POLL_INTERVAL_MS);
+    }
+    checkSession(session) {
+        try {
+            if (!fs.existsSync(session.filePath)) {
+                this.unwatchSession(session.sessionId);
+                return;
+            }
+            const stat = fs.statSync(session.filePath);
+            if (stat.size === session.lastSize)
+                return;
+            session.lastSize = stat.size;
+            const allMessages = (0, session_discovery_1.parseTranscriptFile)(session.filePath);
+            const newMessages = allMessages.slice(session.processedCount);
+            if (newMessages.length === 0)
+                return;
+            let sawAgent = false;
+            for (const msg of newMessages) {
+                const uuid = (0, session_discovery_1.stableUuid)(session.sessionId + ':' + msg.id);
+                this.onEvent({
+                    type: msg.role === 'user' ? 'USER_MESSAGE' : 'AGENT_RESPONSE',
+                    sessionId: session.sessionId,
+                    uuid,
+                    content: msg.content,
+                });
+                if (msg.role === 'agent') {
+                    sawAgent = true;
+                    session.lastMessage = msg.content.slice(0, 200);
+                }
+                session.messageCount++;
+            }
+            session.processedCount = allMessages.length;
+            if (sawAgent)
+                this.startCompletionTimer(session);
+        }
+        catch (err) {
+            console.error(`[CursorWatcher] Error checking session ${session.sessionId}:`, err);
+        }
+    }
+    startCompletionTimer(session) {
+        this.cancelCompletionTimer(session.sessionId);
+        if (!this.onCompletion)
+            return;
+        const timer = setTimeout(() => {
+            this.completionTimers.delete(session.sessionId);
+            this.onCompletion?.({
+                sessionId: session.sessionId,
+                filePath: session.filePath,
+                lastMessage: session.lastMessage,
+                messageCount: session.messageCount,
+            });
+        }, COMPLETION_DELAY_MS);
+        this.completionTimers.set(session.sessionId, timer);
+    }
+    cancelCompletionTimer(sessionId) {
+        const timer = this.completionTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.completionTimers.delete(sessionId);
+        }
+    }
+}
+exports.CursorSessionWatcher = CursorSessionWatcher;
+//# sourceMappingURL=session-watcher.js.map

package/dist/session-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-watcher.js","sourceRoot":"","sources":["../src/session-watcher.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,uCAAyB;AACzB,2DAAsE;AAEtE,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,mBAAmB,GAAG,IAAI,CAAC;AA4BjC,MAAa,oBAAoB;IACvB,eAAe,GAAgC,IAAI,GAAG,EAAE,CAAC;IACzD,gBAAgB,GAAgC,IAAI,GAAG,EAAE,CAAC;IAC1D,SAAS,GAA0B,IAAI,CAAC;IACxC,OAAO,CAAgB;IACvB,YAAY,CAA4B;IAEhD,YAAY,OAAsB,EAAE,YAAiC;QACnE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,YAAY,GAAG,YAAY,IAAI,IAAI,CAAC;IAC3C,CAAC;IAED,YAAY,CAAC,SAAiB,EAAE,QAAgB;QAC9C,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO;QAEhD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,mCAAmC,QAAQ,EAAE,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACnC,MAAM,QAAQ,GAAG,IAAA,uCAAmB,EAAC,QAAQ,CAAC,CAAC;YAC/C,MAAM,SAAS,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;YAExE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE;gBAClC,SAAS;gBACT,QAAQ;gBACR,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,cAAc,EAAE,QAAQ,CAAC,MAAM;gBAC/B,YAAY,EAAE,QAAQ,CAAC,MAAM;gBAC7B,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE;aACpD,CAAC,CAAC;YAEH,OAAO,CAAC,GAAG,CAAC,4CAA4C,SAAS,KAAK,QAAQ,CAAC,MAAM,qBAAqB,CAAC,CAAC;YAE5G,IAAI,CAAC,IAAI,CAAC,SAAS;gBAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,mCAAmC,QAAQ,GAAG,EAAE,GAAG,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,cAAc,CAAC,SAAiB;QAC9B,IAAI,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,4CAA4C,SAAS,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtD,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAED,UAAU;QACR,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACxE,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;QAC9B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;IACH,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;IACnC,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;YAChC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,EAAE,CAAC;gBACpD,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACvB,CAAC;IAEO,YAAY,CAAC,OAAuB;QAC1C,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACvC,OAAO;YACT,CAAC;YAED,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,QAAQ;gBAAE,OAAO;YAE3C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;YAE7B,MAAM,WAAW,GAAG,IAAA,uCAAmB,EAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC1D,MAAM,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;YAC9D,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAErC,IAAI,QAAQ,GAAG,KAAK,CAAC;YAErB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;gBAC9B,MAAM,IAAI,GAAG,IAAA,8BAAU,EAAC,OAAO,CAAC,SAAS,GAAG,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC1D,IAAI,CAAC,OAAO,CAAC;oBACX,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB;oBAC7D,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,IAAI;oBACJ,OAAO,EAAE,GAAG,CAAC,OAAO;iBACrB,CAAC,CAAC;gBAEH,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBACzB,QAAQ,GAAG,IAAI,CAAC;oBAChB,OAAO,CAAC,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBAClD,CAAC;gBAED,OAAO,CAAC,YAAY,EAAE,CAAC;YACzB,CAAC;YAED,OAAO,CAAC,cAAc,GAAG,WAAW,CAAC,MAAM,CAAC;YAE5C,IAAI,QAAQ;gBAAE,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0CAA0C,OAAO,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAEO,oBAAoB,CAAC,OAAuB;QAClD,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,YAAY;YAAE,OAAO;QAE/B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,YAAY,EAAE,OAAO,CAAC,YAAY;aACnC,CAAC,CAAC;QACL,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAExB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IAEO,qBAAqB,CAAC,SAAiB;QAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF;AA9ID,oDA8IC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmdctrl/cursor-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CmdCtrl daemon for Cursor CLI - connects your workstation to the CmdCtrl orchestration server",
   "main": "./dist/index.js",
   "bin": {

package/src/commands/start.ts

@@ -2,7 +2,8 @@ import { readFileSync } from 'fs';
 import { join } from 'path';
 import { DaemonClient, ConfigManager } from '@cmdctrl/daemon-sdk';
 import { CursorAdapter } from '../adapter/cursor-cli';
-import { MessageStore } from '../message-store';
+import { discoverSessions, readSessionMessages } from '../session-discovery';
+import { CursorSessionWatcher } from '../session-watcher';
 
 const configManager = new ConfigManager('cursor-cli');
 
@@ -39,9 +40,33 @@ export async function start(): Promise<void> {
 
   configManager.writePidFile(process.pid);
 
-  const messageStore = new MessageStore();
-  const pendingInstructions = new Map<string, string>();
-  const taskSessionMap = new Map<string, string>();
+  // Managed session IDs (started via task_start) – excluded from native discovery
+  const managedSessionIds = new Set<string>();
+
+  const sessionWatcher = new CursorSessionWatcher(
+    (event) => {
+      // Only send activity for user messages – agent responses are the final
+      // answer already shown via the transcript; sending them here duplicates.
+      if (event.type !== 'USER_MESSAGE') return;
+      client.sendSessionActivity(
+        event.sessionId,
+        '',
+        event.content,
+        1,
+        false,
+        new Date().toISOString()
+      );
+    },
+    (completion) => {
+      client.sendSessionActivity(
+        completion.sessionId,
+        completion.filePath,
+        completion.lastMessage,
+        completion.messageCount,
+        true
+      );
+    }
+  );
 
   // Event callback wired into the DaemonClient below
   let sendEvent: (taskId: string, eventType: string, data: Record<string, unknown>) => void;
@@ -49,21 +74,8 @@ export async function start(): Promise<void> {
   const adapter = new CursorAdapter((taskId, eventType, data) => {
     const sessionId = data.session_id as string | undefined;
 
-    // Store initial user message when session starts
     if (eventType === 'SESSION_STARTED' && sessionId) {
-      const instruction = pendingInstructions.get(taskId);
-      if (instruction) {
-        messageStore.storeMessage(sessionId, 'USER', instruction);
-        pendingInstructions.delete(taskId);
-      }
-    }
-
-    // Store agent response on completion
-    if (eventType === 'TASK_COMPLETE' && data.result) {
-      const sid = (data.session_id as string) || taskSessionMap.get(taskId);
-      if (sid) {
-        messageStore.storeMessage(sid, 'AGENT', data.result as string);
-      }
+      managedSessionIds.add(sessionId);
     }
 
     sendEvent(taskId, eventType, data);
@@ -77,10 +89,13 @@ export async function start(): Promise<void> {
     version: daemonVersion,
   });
 
-  // Wire up sendEvent to the client's internal method
+  client.setSessionsProvider(() => discoverSessions(managedSessionIds));
+
   sendEvent = (taskId, eventType, data) => {
-    // Use the client to send events — the SDK handles this via task handles,
-    // but since the adapter uses a callback pattern, we send raw events
+    // cursor-agent writes all content to transcript files – suppress OUTPUT events
+    // and strip result from TASK_COMPLETE to avoid duplicating transcript content.
+    if (eventType === 'OUTPUT') return;
+    if (eventType === 'TASK_COMPLETE') data = { ...data, result: '' };
     (client as any).send({
       type: 'event',
       task_id: taskId,
@@ -89,8 +104,15 @@ export async function start(): Promise<void> {
     });
   };
 
+  client.onWatchSession((sessionId, filePath) => {
+    sessionWatcher.watchSession(sessionId, filePath);
+  });
+
+  client.onUnwatchSession((sessionId) => {
+    sessionWatcher.unwatchSession(sessionId);
+  });
+
   client.onTaskStart(async (task) => {
-    pendingInstructions.set(task.taskId, task.instruction);
     try {
       await adapter.startTask(task.taskId, task.instruction, task.projectPath);
     } catch (err: unknown) {
@@ -99,8 +121,6 @@ export async function start(): Promise<void> {
   });
 
   client.onTaskResume(async (task) => {
-    messageStore.storeMessage(task.sessionId, 'USER', task.message);
-    taskSessionMap.set(task.taskId, task.sessionId);
     try {
       await adapter.resumeTask(task.taskId, task.sessionId, task.message, task.projectPath);
     } catch (err: unknown) {
@@ -112,19 +132,9 @@ export async function start(): Promise<void> {
     await adapter.cancelTask(taskId);
   });
 
+  // cursor-agent always writes to transcript files – use them as the single source of truth
   client.onGetMessages((req) => {
-    const result = messageStore.getMessages(
-      req.sessionId,
-      req.limit,
-      req.beforeUuid,
-      req.afterUuid
-    );
-    return {
-      messages: result.messages,
-      hasMore: result.hasMore,
-      oldestUuid: result.oldestUuid,
-      newestUuid: result.newestUuid,
-    };
+    return readSessionMessages(req.sessionId, req.limit, req.beforeUuid, req.afterUuid);
   });
 
   client.onVersionStatus((msg) => {
@@ -135,6 +145,7 @@ export async function start(): Promise<void> {
 
   const shutdown = async () => {
     console.log('\nShutting down...');
+    sessionWatcher.unwatchAll();
     await adapter.stopAll();
     await client.disconnect();
     configManager.deletePidFile();

package/src/session-discovery.ts

@@ -0,0 +1,328 @@
+/**
+ * Cursor CLI Session Discovery
+ *
+ * Scans ~/.cursor/projects/<encoded-path>/agent-transcripts/<session-id>.jsonl
+ * to discover existing cursor-agent sessions.
+ *
+ * File format – each line is a JSON object:
+ *   { role: "user" | "assistant", message: { content: [{ type: "text", text: "..." }] } }
+ *
+ * User messages have text wrapped in <user_query>...</user_query> tags.
+ * Session ID = filename (UUID, without .jsonl).
+ * Project path = decoded from the project directory name (hyphens → slashes).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+
+const ACTIVE_THRESHOLD_MS = 30 * 1000;
+
+export interface ExternalSession {
+  session_id: string;
+  slug: string;
+  title: string;
+  project: string;
+  project_name: string;
+  file_path: string;
+  last_message: string;
+  last_activity: string;
+  is_active: boolean;
+  message_count: number;
+}
+
+export interface ParsedMessage {
+  id: string;
+  role: 'user' | 'agent';
+  content: string;
+}
+
+// Cache: file path → { session, fileMtime }
+const sessionCache = new Map<string, { session: ExternalSession; fileMtime: number }>();
+
+// Cache: file path → { messages, fileMtime }
+const messageCache = new Map<string, { messages: ParsedMessage[]; fileMtime: number }>();
+
+/**
+ * Strip <user_query>...</user_query> wrapper added by cursor-agent.
+ */
+function stripUserQueryTags(text: string): string {
+  return text.replace(/^\s*<user_query>\s*/i, '').replace(/\s*<\/user_query>\s*$/i, '').trim();
+}
+
+/**
+ * Extract plain text from a cursor-agent message content array.
+ */
+function extractText(content: Array<{ type: string; text?: string }>): string {
+  return content
+    .filter(b => b.type === 'text' && b.text)
+    .map(b => b.text!)
+    .join('')
+    .trim();
+}
+
+/**
+ * Parse all messages from a cursor-agent transcript JSONL file.
+ */
+export function parseTranscriptFile(filePath: string): ParsedMessage[] {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const lines = raw.split('\n').filter(l => l.trim());
+    const messages: ParsedMessage[] = [];
+    let idx = 0;
+
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line) as {
+          role: string;
+          message: { content: Array<{ type: string; text?: string }> };
+        };
+
+        if (!obj.role || !obj.message?.content) continue;
+
+        let text = extractText(obj.message.content);
+        if (!text) continue;
+
+        if (obj.role === 'user') {
+          text = stripUserQueryTags(text);
+          if (!text) continue;
+          messages.push({ id: `user-${idx++}`, role: 'user', content: text });
+        } else if (obj.role === 'assistant') {
+          // cursor-agent appends thinking after the first blank line – keep only the answer
+          const answerEnd = text.indexOf('\n\n');
+          if (answerEnd !== -1) text = text.slice(0, answerEnd).trim();
+          if (!text) continue;
+          messages.push({ id: `agent-${idx++}`, role: 'agent', content: text });
+        }
+      } catch {
+        // skip invalid lines
+      }
+    }
+
+    return messages;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Attempt to decode a cursor project directory name back to a filesystem path.
+ * The encoding replaces '/' with '-' and drops the leading '/'.
+ * e.g. "Users-mrwoof-src-testing" → "/Users/mrwoof/src/testing"
+ *
+ * We try all possible slash placements and return the first existing path.
+ * Falls back to returning the encoded name if nothing exists.
+ */
+function decodeProjectPath(encoded: string): string {
+  // Simple heuristic: replace all hyphens with slashes and prepend /
+  const candidate = '/' + encoded.replace(/-/g, '/');
+  if (fs.existsSync(candidate)) return candidate;
+
+  // Walk all subdirs of ~/ looking for the encoded name match
+  // (handles paths with hyphens in component names by trying common prefixes)
+  const home = os.homedir();
+  const homeEncoded = home.replace(/^\//, '').replace(/\//g, '-');
+  if (encoded.startsWith(homeEncoded + '-')) {
+    const rest = encoded.slice(homeEncoded.length + 1);
+    const restPath = rest.replace(/-/g, '/');
+    const tryPath = path.join(home, restPath);
+    if (fs.existsSync(tryPath)) return tryPath;
+  }
+
+  return candidate;
+}
+
+/**
+ * Generate title from first user message.
+ */
+function generateTitle(text: string): string {
+  const firstLine = text.split('\n')[0].trim();
+  if (firstLine.length <= 50) return firstLine;
+  const truncated = firstLine.slice(0, 50);
+  const lastSpace = truncated.lastIndexOf(' ');
+  if (lastSpace > 30) return truncated.slice(0, lastSpace) + '...';
+  return truncated + '...';
+}
+
+/**
+ * Discover all cursor-agent sessions on this device.
+ * Scans ~/.cursor/projects/<project>/agent-transcripts/<session>.jsonl
+ */
+export function discoverSessions(excludeSessionIDs: Set<string> = new Set()): ExternalSession[] {
+  const projectsDir = path.join(os.homedir(), '.cursor', 'projects');
+  const sessions: ExternalSession[] = [];
+
+  if (!fs.existsSync(projectsDir)) return sessions;
+
+  let projectDirs: string[];
+  try {
+    projectDirs = fs.readdirSync(projectsDir);
+  } catch {
+    return sessions;
+  }
+
+  for (const projectDir of projectDirs) {
+    const transcriptsDir = path.join(projectsDir, projectDir, 'agent-transcripts');
+    if (!fs.existsSync(transcriptsDir)) continue;
+
+    const projectPath = decodeProjectPath(projectDir);
+    const projectName = path.basename(projectPath);
+
+    let transcriptFiles: string[];
+    try {
+      transcriptFiles = fs.readdirSync(transcriptsDir).filter(f => f.endsWith('.jsonl'));
+    } catch {
+      continue;
+    }
+
+    for (const file of transcriptFiles) {
+      const sessionId = file.replace('.jsonl', '');
+      if (excludeSessionIDs.has(sessionId)) continue;
+
+      const filePath = path.join(transcriptsDir, file);
+
+      try {
+        const stat = fs.statSync(filePath);
+        const fileMtime = stat.mtimeMs;
+
+        const cached = sessionCache.get(filePath);
+        if (cached && cached.fileMtime === fileMtime) {
+          const session = { ...cached.session };
+          session.is_active = Date.now() - new Date(session.last_activity).getTime() < ACTIVE_THRESHOLD_MS;
+          sessions.push(session);
+          continue;
+        }
+
+        const messages = parseTranscriptFile(filePath);
+        if (messages.length === 0) continue;
+
+        const firstUser = messages.find(m => m.role === 'user');
+        const lastUser = [...messages].reverse().find(m => m.role === 'user');
+        const title = generateTitle(firstUser?.content || '') || sessionId.slice(0, 8);
+        const lastMessage = lastUser?.content.slice(0, 100) || '';
+        const lastActivity = new Date(stat.mtimeMs).toISOString();
+        const isActive = Date.now() - stat.mtimeMs < ACTIVE_THRESHOLD_MS;
+
+        const session: ExternalSession = {
+          session_id: sessionId,
+          slug: '',
+          title,
+          project: projectPath,
+          project_name: projectName,
+          file_path: filePath,
+          last_message: lastMessage,
+          last_activity: lastActivity,
+          is_active: isActive,
+          message_count: messages.length,
+        };
+
+        sessionCache.set(filePath, { session, fileMtime });
+        sessions.push(session);
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  sessions.sort((a, b) =>
+    new Date(b.last_activity).getTime() - new Date(a.last_activity).getTime()
+  );
+
+  return sessions;
+}
+
+/**
+ * Find the file path for a given session ID.
+ */
+export function findSessionFile(sessionId: string): string | null {
+  for (const [filePath, cached] of sessionCache.entries()) {
+    if (cached.session.session_id === sessionId) return filePath;
+  }
+
+  const projectsDir = path.join(os.homedir(), '.cursor', 'projects');
+  if (!fs.existsSync(projectsDir)) return null;
+
+  try {
+    for (const projectDir of fs.readdirSync(projectsDir)) {
+      const candidate = path.join(projectsDir, projectDir, 'agent-transcripts', `${sessionId}.jsonl`);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  } catch {
+    // ignore
+  }
+
+  return null;
+}
+
+/**
+ * Read messages from a cursor-agent session for the CmdCtrl get_messages protocol.
+ */
+export function readSessionMessages(
+  sessionId: string,
+  limit: number,
+  beforeUuid?: string,
+  afterUuid?: string
+): { messages: Array<{ uuid: string; role: 'USER' | 'AGENT'; content: string; timestamp: string }>; hasMore: boolean; oldestUuid?: string; newestUuid?: string } {
+  const filePath = findSessionFile(sessionId);
+  if (!filePath) return { messages: [], hasMore: false };
+
+  try {
+    const stat = fs.statSync(filePath);
+    const fileMtime = stat.mtimeMs;
+
+    let parsed: ParsedMessage[];
+    const cached = messageCache.get(filePath);
+    if (cached && cached.fileMtime === fileMtime) {
+      parsed = cached.messages;
+    } else {
+      parsed = parseTranscriptFile(filePath);
+      messageCache.set(filePath, { messages: parsed, fileMtime });
+    }
+
+    // Assign sequential timestamps 1s apart, ending at file mtime, to preserve order
+    const total = parsed.filter(m => m.content.length > 0).length;
+    let seq = 0;
+    let messages = parsed.map(msg => ({
+      uuid: stableUuid(sessionId + ':' + msg.id),
+      role: (msg.role === 'user' ? 'USER' : 'AGENT') as 'USER' | 'AGENT',
+      content: msg.content,
+      timestamp: new Date(stat.mtimeMs - (total - seq++) * 1000).toISOString(),
+    })).filter(m => m.content.length > 0);
+
+    if (beforeUuid) {
+      const idx = messages.findIndex(m => m.uuid === beforeUuid);
+      if (idx > 0) messages = messages.slice(0, idx);
+    }
+    if (afterUuid) {
+      const idx = messages.findIndex(m => m.uuid === afterUuid);
+      if (idx >= 0) messages = messages.slice(idx + 1);
+    }
+
+    const hasMore = messages.length > limit;
+    const limited = messages.slice(-limit);
+
+    return {
+      messages: limited,
+      hasMore,
+      oldestUuid: limited[0]?.uuid,
+      newestUuid: limited[limited.length - 1]?.uuid,
+    };
+  } catch {
+    return { messages: [], hasMore: false };
+  }
+}
+
+/**
+ * Generate a stable UUID from an input string.
+ */
+export function stableUuid(input: string): string {
+  const hash = crypto.createHash('sha256').update(input).digest('hex');
+  return [
+    hash.slice(0, 8),
+    hash.slice(8, 12),
+    '4' + hash.slice(13, 16),
+    '8' + hash.slice(17, 20),
+    hash.slice(20, 32),
+  ].join('-');
+}