@cmdctrl/claude-code 0.1.0

package/src/index.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { register } from './commands/register';
+import { unregister } from './commands/unregister';
+import { start } from './commands/start';
+import { status } from './commands/status';
+import { stop } from './commands/stop';
+
+const program = new Command();
+
+program
+  .name('cmdctrl-claude-code')
+  .description('Claude Code daemon - connects your workstation to the CmdCtrl orchestration server')
+  .version('0.1.0');
+
+program
+  .command('register')
+  .description('Register this device with a CmdCtrl server')
+  .option('-s, --server <url>', 'CmdCtrl server URL', 'http://localhost:4000')
+  .option('-n, --name <name>', 'Device name (defaults to hostname)')
+  .action(register);
+
+program
+  .command('unregister')
+  .description('Remove local registration data')
+  .action(unregister);
+
+program
+  .command('start')
+  .description('Start the daemon and connect to the CmdCtrl server')
+  .option('-f, --foreground', 'Run in foreground (don\'t daemonize)')
+  .action(start);
+
+program
+  .command('status')
+  .description('Check daemon connection status')
+  .action(status);
+
+program
+  .command('stop')
+  .description('Stop the running daemon')
+  .action(stop);
+
+program.parse();

package/src/message-reader.ts

@@ -0,0 +1,485 @@
+/**
+ * JSONL message reader with pagination support
+ * Reads messages from Claude Code session files
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { MessageEntry } from './client/messages';
+
+// Size of chunks to read when scanning for messages
+const CHUNK_SIZE = 64 * 1024; // 64KB
+
+// Safety limits to prevent memory exhaustion from bloated sessions (e.g., sessions with many large images)
+const MAX_FILE_SIZE = 20 * 1024 * 1024; // 20MB - warn threshold for large files
+const MAX_LINE_SIZE = 100 * 1024; // 100KB - truncate lines larger than this (likely contain base64 images)
+const LINE_TAIL_SIZE = 1024; // 1KB - also capture tail of long lines (uuid, timestamp are at the end)
+const TRUNCATED_LINE_MARKER = '\x00TRUNCATED\x00'; // Marker added to truncated lines
+const TRUNCATED_MID_MARKER = '\x00MID\x00'; // Separator between head and tail of truncated lines
+
+interface JournalEntry {
+  type: string;
+  uuid?: string;
+  sessionId?: string;
+  timestamp?: string;
+  message?: {
+    role?: string;
+    content?: unknown;
+  };
+}
+
+/**
+ * Extract readable text from message content (handles string or array of content blocks)
+ */
+function extractReadableText(content: unknown): string {
+  // Simple string
+  if (typeof content === 'string') {
+    return content.trim();
+  }
+
+  // Array of content blocks (Claude format)
+  if (Array.isArray(content)) {
+    const textParts: string[] = [];
+    for (const block of content) {
+      if (typeof block === 'string') {
+        textParts.push(block);
+      } else if (block && typeof block === 'object') {
+        // Text block: { type: 'text', text: '...' }
+        if (block.type === 'text' && typeof block.text === 'string') {
+          textParts.push(block.text);
+        }
+        // Skip tool_use, tool_result, image blocks etc.
+        // Tool calls are shown as verbose output during execution, not as permanent messages
+      }
+    }
+    return textParts.join(' ').trim();
+  }
+
+  // Object with text property
+  if (content && typeof content === 'object' && 'text' in content) {
+    const text = (content as { text: unknown }).text;
+    if (typeof text === 'string') {
+      return text.trim();
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Detect Claude Code compaction/summary messages and system notifications
+ * Note: Most bash-notification entries are type:"queue-operation" (filtered by type),
+ * but some appear as type:"user" with <bash-notification> content
+ */
+function isSystemMessage(content: string): boolean {
+  const systemPrefixes = [
+    'This session is being continued from a previous conversation',
+    'This conversation is being continued from a previous session',
+    '<system-reminder>',
+    '<bash-notification>',
+  ];
+  for (const prefix of systemPrefixes) {
+    if (content.startsWith(prefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Find the JSONL file for a given session ID
+ */
+export function findSessionFile(sessionId: string): string | null {
+  const claudeDir = path.join(os.homedir(), '.claude', 'projects');
+
+  if (!fs.existsSync(claudeDir)) {
+    return null;
+  }
+
+  const fileName = `${sessionId}.jsonl`;
+  const entries = fs.readdirSync(claudeDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const filePath = path.join(claudeDir, entry.name, fileName);
+    if (fs.existsSync(filePath)) {
+      return filePath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse a JSONL line into a MessageEntry if it's a displayable message
+ * For truncated lines (marked with TRUNCATED_LINE_MARKER), we extract UUID via regex
+ * and return a placeholder message instead of the full content
+ */
+function parseLineToMessage(line: string, index: number): MessageEntry | null {
+  try {
+    // Check if this line was truncated by the streaming reader
+    const isTruncated = line.endsWith(TRUNCATED_LINE_MARKER);
+
+    let entry: JournalEntry;
+    if (isTruncated) {
+      // Truncated line format: {head}TRUNCATED_MID_MARKER{tail}TRUNCATED_LINE_MARKER
+      // - head contains: type (near start)
+      // - tail contains: uuid, timestamp (at end of original line)
+      const lineWithoutEndMarker = line.slice(0, -TRUNCATED_LINE_MARKER.length);
+      const midIndex = lineWithoutEndMarker.indexOf(TRUNCATED_MID_MARKER);
+
+      let headPart: string;
+      let tailPart: string;
+      if (midIndex >= 0) {
+        headPart = lineWithoutEndMarker.slice(0, midIndex);
+        tailPart = lineWithoutEndMarker.slice(midIndex + TRUNCATED_MID_MARKER.length);
+      } else {
+        // Old format (no mid marker) - only have head
+        headPart = lineWithoutEndMarker;
+        tailPart = '';
+      }
+
+      // Type is in the head
+      const typeMatch = headPart.match(/"type"\s*:\s*"([^"]+)"/);
+      // UUID is in the tail (or occasionally in head if line wasn't too long)
+      const uuidMatch = tailPart.match(/"uuid"\s*:\s*"([^"]+)"/)
+                     || headPart.match(/"uuid"\s*:\s*"([^"]+)"/);
+      // Timestamp is also in the tail
+      const timestampMatch = tailPart.match(/"timestamp"\s*:\s*"([^"]+)"/);
+
+      if (!uuidMatch || !typeMatch) {
+        return null;
+      }
+
+      const type = typeMatch[1];
+      if (type !== 'user' && type !== 'assistant') {
+        return null;
+      }
+
+      // Return a placeholder for truncated messages (they contain images we can't display anyway)
+      return {
+        uuid: uuidMatch[1],
+        role: type === 'user' ? 'USER' : 'AGENT',
+        content: '[Message contains large content]',
+        timestamp: timestampMatch ? timestampMatch[1] : new Date().toISOString(),
+      };
+    }
+
+    entry = JSON.parse(line);
+
+    // Only process user and assistant messages
+    if (entry.type !== 'user' && entry.type !== 'assistant') {
+      return null;
+    }
+
+    // Extract content
+    const text = entry.message?.content
+      ? extractReadableText(entry.message.content)
+      : '';
+
+    // Skip entries with no displayable text
+    if (!text) {
+      return null;
+    }
+
+    // Determine role
+    let role: 'USER' | 'AGENT' | 'SYSTEM' = entry.type === 'user' ? 'USER' : 'AGENT';
+
+    // Detect system messages (compaction, bash notifications, etc.)
+    if (role === 'USER' && isSystemMessage(text)) {
+      role = 'SYSTEM';
+    }
+
+    return {
+      uuid: entry.uuid || `generated-${index}`,
+      role,
+      content: text,
+      timestamp: entry.timestamp || new Date().toISOString(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Truncate a line, keeping both head (for type) and tail (for uuid, timestamp)
+ * Format: {head}TRUNCATED_MID_MARKER{tail}TRUNCATED_LINE_MARKER
+ */
+function truncateLine(line: string): string {
+  const head = line.substring(0, MAX_LINE_SIZE);
+  const tail = line.substring(Math.max(MAX_LINE_SIZE, line.length - LINE_TAIL_SIZE));
+  return head + TRUNCATED_MID_MARKER + tail + TRUNCATED_LINE_MARKER;
+}
+
+/**
+ * Read the last N lines from a file using backward reading (tail-like)
+ * This is much faster than reading the entire file for large files
+ */
+function readLastLines(filePath: string, maxLines: number): string[] {
+  const fd = fs.openSync(filePath, 'r');
+  const stats = fs.fstatSync(fd);
+  const fileSize = stats.size;
+
+  if (fileSize === 0) {
+    fs.closeSync(fd);
+    return [];
+  }
+
+  const lines: string[] = [];
+  let position = fileSize;
+  let buffer = '';
+
+  // We need to read more lines than requested because many JSONL entries
+  // won't be displayable messages (tool_use, system events, etc.)
+  // Multiplier of 10x accounts for ~10% of entries being actual messages
+  const targetLines = maxLines * 10;
+
+  while (position > 0 && lines.length < targetLines) {
+    // Read in chunks from the end
+    const chunkSize = Math.min(CHUNK_SIZE, position);
+    position -= chunkSize;
+
+    const chunk = Buffer.alloc(chunkSize);
+    fs.readSync(fd, chunk, 0, chunkSize, position);
+    buffer = chunk.toString('utf-8') + buffer;
+
+    // Extract complete lines from buffer
+    const newlineIndex = buffer.lastIndexOf('\n');
+    if (newlineIndex !== -1) {
+      // Split into lines, keeping the incomplete first line in buffer
+      const completeLines = buffer.substring(0, newlineIndex).split('\n');
+      buffer = buffer.substring(newlineIndex + 1);
+
+      // Add lines in reverse order (we're reading backward)
+      for (let i = completeLines.length - 1; i >= 0; i--) {
+        const line = completeLines[i].trim();
+        if (line) {
+          // For oversized lines, keep both head and tail
+          if (line.length > MAX_LINE_SIZE) {
+            lines.unshift(truncateLine(line));
+          } else {
+            lines.unshift(line);
+          }
+        }
+      }
+    }
+  }
+
+  // Don't forget any remaining content in buffer
+  const trimmedBuffer = buffer.trim();
+  if (trimmedBuffer) {
+    if (trimmedBuffer.length > MAX_LINE_SIZE) {
+      lines.unshift(truncateLine(trimmedBuffer));
+    } else {
+      lines.unshift(trimmedBuffer);
+    }
+  }
+
+  fs.closeSync(fd);
+  return lines;
+}
+
+/**
+ * Read all lines from a file (streaming approach)
+ * For oversized lines, keeps both head (for type) and tail (for uuid, timestamp)
+ * Format for truncated: {head}TRUNCATED_MID_MARKER{tail}TRUNCATED_LINE_MARKER
+ * Safer than fs.readFileSync for files with potentially huge lines
+ */
+function readAllLinesSafe(filePath: string): string[] {
+  const stats = fs.statSync(filePath);
+
+  // For very large files, warn but still try to process
+  if (stats.size > MAX_FILE_SIZE) {
+    console.warn(`[MessageReader] File ${filePath} is ${(stats.size / 1024 / 1024).toFixed(1)}MB, exceeds ${MAX_FILE_SIZE / 1024 / 1024}MB limit. Processing may be slow.`);
+  }
+
+  const lines: string[] = [];
+  const fd = fs.openSync(filePath, 'r');
+  let position = 0;
+  let currentLineHead = '';  // First MAX_LINE_SIZE chars
+  let currentLineTail = '';  // Last LINE_TAIL_SIZE chars (sliding window)
+  let lineOverflowed = false;
+
+  try {
+    while (position < stats.size) {
+      const chunkSize = Math.min(CHUNK_SIZE, stats.size - position);
+      const chunk = Buffer.alloc(chunkSize);
+      fs.readSync(fd, chunk, 0, chunkSize, position);
+      position += chunkSize;
+
+      const text = chunk.toString('utf-8');
+
+      for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === '\n') {
+          const trimmedHead = currentLineHead.trim();
+          if (trimmedHead) {
+            // For truncated lines, include both head and tail with markers
+            if (lineOverflowed) {
+              lines.push(trimmedHead + TRUNCATED_MID_MARKER + currentLineTail.trim() + TRUNCATED_LINE_MARKER);
+            } else {
+              lines.push(trimmedHead);
+            }
+          }
+          currentLineHead = '';
+          currentLineTail = '';
+          lineOverflowed = false;
+        } else {
+          // Keep building head up to MAX_LINE_SIZE
+          if (currentLineHead.length < MAX_LINE_SIZE) {
+            currentLineHead += char;
+          } else {
+            // Once overflowed, start tracking the tail (sliding window)
+            lineOverflowed = true;
+            currentLineTail += char;
+            // Keep only the last LINE_TAIL_SIZE chars
+            if (currentLineTail.length > LINE_TAIL_SIZE) {
+              currentLineTail = currentLineTail.slice(-LINE_TAIL_SIZE);
+            }
+          }
+        }
+      }
+    }
+
+    // Handle final line without newline
+    const trimmedHead = currentLineHead.trim();
+    if (trimmedHead) {
+      if (lineOverflowed) {
+        lines.push(trimmedHead + TRUNCATED_MID_MARKER + currentLineTail.trim() + TRUNCATED_LINE_MARKER);
+      } else {
+        lines.push(trimmedHead);
+      }
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return lines;
+}
+
+/**
+ * Read messages from a session JSONL file
+ *
+ * @param sessionId - The session ID to read
+ * @param limit - Maximum number of messages to return
+ * @param beforeUuid - Optional UUID cursor - returns messages before this one (for loading older)
+ * @param afterUuid - Optional UUID cursor - returns messages after this one (for loading newer)
+ * @returns Messages array, has_more flag, oldest/newest UUIDs
+ */
+export function readMessages(
+  sessionId: string,
+  limit: number,
+  beforeUuid?: string,
+  afterUuid?: string
+): { messages: MessageEntry[]; hasMore: boolean; oldestUuid?: string; newestUuid?: string } {
+  const filePath = findSessionFile(sessionId);
+
+  if (!filePath) {
+    return { messages: [], hasMore: false };
+  }
+
+  // Fast path: no cursor, just want last N messages
+  // Use tail-like reading to avoid loading entire file
+  if (!beforeUuid && !afterUuid) {
+    const lines = readLastLines(filePath, limit);
+
+    // Parse ALL lines to messages (lines are oldest-to-newest)
+    // We must process all lines to find the most recent displayable messages
+    const messages: MessageEntry[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      const msg = parseLineToMessage(lines[i], i);
+      if (msg) {
+        messages.push(msg);
+      }
+    }
+
+    // Take the last 'limit' messages (they're in chronological order)
+    const resultMessages = messages.slice(-limit);
+
+    // We have "more" if we found more messages than the limit
+    const hasMore = messages.length > limit;
+
+    return {
+      messages: resultMessages,
+      hasMore,
+      oldestUuid: resultMessages.length > 0 ? resultMessages[0].uuid : undefined,
+      newestUuid: resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].uuid : undefined,
+    };
+  }
+
+  // Slow path: cursor-based pagination requires reading the full file
+  // to find the cursor position accurately
+  // Use safe reader that skips oversized lines (e.g., base64 images)
+  const lines = readAllLinesSafe(filePath);
+
+  // Parse all message entries
+  const allMessages: MessageEntry[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const msg = parseLineToMessage(lines[i], i);
+    if (msg) {
+      allMessages.push(msg);
+    }
+  }
+
+  // Handle afterUuid - return messages AFTER the given UUID (for incremental updates)
+  if (afterUuid) {
+    const cursorIndex = allMessages.findIndex(m => m.uuid === afterUuid);
+    if (cursorIndex >= 0) {
+      // Get messages after the cursor
+      const startIndex = cursorIndex + 1;
+      const endIndex = Math.min(startIndex + limit, allMessages.length);
+      const resultMessages = allMessages.slice(startIndex, endIndex);
+      const hasMore = endIndex < allMessages.length;
+
+      return {
+        messages: resultMessages,
+        hasMore,
+        oldestUuid: resultMessages.length > 0 ? resultMessages[0].uuid : undefined,
+        newestUuid: resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].uuid : undefined,
+      };
+    }
+    // Stale cursor (likely compacted away) - fall back to returning latest messages
+    // This ensures clients get current data even after session compaction
+    const endIndex = allMessages.length;
+    const beginIndex = Math.max(0, endIndex - limit);
+    const resultMessages = allMessages.slice(beginIndex, endIndex);
+    const hasMore = beginIndex > 0;
+
+    return {
+      messages: resultMessages,
+      hasMore,
+      oldestUuid: resultMessages.length > 0 ? resultMessages[0].uuid : undefined,
+      newestUuid: resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].uuid : undefined,
+    };
+  }
+
+  // Handle beforeUuid - return messages BEFORE the given UUID (for loading older)
+  let startIndex = allMessages.length;
+  if (beforeUuid) {
+    const cursorIndex = allMessages.findIndex(m => m.uuid === beforeUuid);
+    if (cursorIndex >= 0) {
+      startIndex = cursorIndex;
+    } else {
+      // Stale cursor (likely compacted away) - return empty for "load older"
+      // User's current view may be outdated; they should refresh to get current messages
+      return { messages: [], hasMore: false };
+    }
+  }
+
+  // Get messages before the cursor (or from end if no cursor)
+  const endIndex = startIndex;
+  const beginIndex = Math.max(0, endIndex - limit);
+
+  const resultMessages = allMessages.slice(beginIndex, endIndex);
+  const hasMore = beginIndex > 0;
+
+  return {
+    messages: resultMessages,
+    hasMore,
+    oldestUuid: resultMessages.length > 0 ? resultMessages[0].uuid : undefined,
+    newestUuid: resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].uuid : undefined,
+  };
+}