@jacques-ai/server 0.0.7-alpha.1

package/dist/connection/session-discovery.js

@@ -0,0 +1,311 @@
+/**
+ * Session Discovery
+ *
+ * Finds and resolves metadata for JSONL session files in Claude's project directories.
+ * Uses a catalog-first strategy: reads pre-extracted metadata from Jacques session index
+ * when available, falls back to JSONL parsing for uncataloged sessions.
+ *
+ * @module connection/session-discovery
+ */
+import * as path from 'path';
+import { promises as fs } from 'fs';
+import { encodeProjectPath, getClaudeProjectsDir, parseJSONLContent, parseJSONL, getEntryStatistics, } from '@jacques-ai/core/session';
+import { detectModeAndPlans, } from '@jacques-ai/core/cache';
+import { ACTIVE_SESSION_THRESHOLD_MS, DEFAULT_CONTEXT_WINDOW_SIZE, } from './constants.js';
+import { detectGitInfo } from './git-info.js';
+/**
+ * Resolve metadata for a session file using catalog-first strategy.
+ *
+ * Priority 1: Use pre-extracted catalog metadata (fast, no file I/O)
+ * Priority 2: Fall back to JSONL parsing (slow, reads full file)
+ */
+async function resolveSessionMetadata(filePath, sessionId, modifiedAt, cwd, catalogMap) {
+    // Priority 1: Use existing Jacques catalog metadata
+    const catalogEntry = catalogMap.get(sessionId);
+    if (catalogEntry) {
+        let contextMetrics = null;
+        if (catalogEntry.tokens && catalogEntry.tokens.input > 0) {
+            const contextWindowSize = DEFAULT_CONTEXT_WINDOW_SIZE;
+            const usedPercentage = (catalogEntry.tokens.input / contextWindowSize) * 100;
+            contextMetrics = {
+                used_percentage: Math.min(usedPercentage, 100),
+                remaining_percentage: Math.max(100 - usedPercentage, 0),
+                context_window_size: contextWindowSize,
+                total_input_tokens: catalogEntry.tokens.input,
+                total_output_tokens: catalogEntry.tokens.output,
+                is_estimate: true,
+            };
+        }
+        // Always use live git detection for discovered sessions — catalog git info
+        // may be stale (e.g., detected from decoded project path instead of actual worktree)
+        const gitInfo = await detectGitInfo(cwd);
+        const gitBranch = gitInfo.branch || catalogEntry.gitBranch || null;
+        const gitWorktree = gitInfo.worktree || catalogEntry.gitWorktree || null;
+        const gitRepoRoot = gitInfo.repoRoot || catalogEntry.gitRepoRoot || null;
+        return {
+            filePath,
+            sessionId,
+            modifiedAt,
+            gitBranch,
+            gitWorktree,
+            gitRepoRoot,
+            title: catalogEntry.title,
+            contextMetrics,
+            mode: catalogEntry.mode || null,
+        };
+    }
+    // Priority 2: Fall back to JSONL parsing for uncataloged sessions
+    const metadata = await extractSessionMetadataFromJSONL(filePath);
+    if (!metadata.sessionId) {
+        return null;
+    }
+    const gitInfo = await detectGitInfo(cwd);
+    const mode = await detectSessionModeFromJSONL(filePath);
+    return {
+        filePath,
+        sessionId: metadata.sessionId,
+        modifiedAt,
+        gitBranch: metadata.gitBranch || gitInfo.branch,
+        gitWorktree: gitInfo.worktree,
+        gitRepoRoot: gitInfo.repoRoot,
+        title: metadata.title,
+        // Don't estimate context for discovered sessions - show null until hooks fire
+        contextMetrics: null,
+        mode,
+    };
+}
+/**
+ * Find all active session files for a given CWD.
+ * Uses catalog-first strategy: reads from Jacques session index when available,
+ * falls back to JSONL parsing for uncataloged sessions.
+ *
+ * @param cwd Working directory to find sessions for
+ * @param catalogMap Pre-loaded session catalog (sessionId -> SessionEntry)
+ * @returns Sessions modified within ACTIVE_SESSION_THRESHOLD_MS, sorted by recency
+ */
+export async function findActiveSessionFiles(cwd, catalogMap) {
+    const projectDir = getProjectDir(cwd);
+    try {
+        await fs.access(projectDir);
+    }
+    catch {
+        return [];
+    }
+    try {
+        const files = await fs.readdir(projectDir);
+        const jsonlFiles = files.filter((f) => f.endsWith('.jsonl'));
+        if (jsonlFiles.length === 0) {
+            return [];
+        }
+        const now = Date.now();
+        const activeSessions = [];
+        for (const filename of jsonlFiles) {
+            const filePath = path.join(projectDir, filename);
+            const stats = await fs.stat(filePath);
+            const mtime = stats.mtime.getTime();
+            if (now - mtime <= ACTIVE_SESSION_THRESHOLD_MS) {
+                const sessionId = path.basename(filename, '.jsonl');
+                const resolved = await resolveSessionMetadata(filePath, sessionId, stats.mtime, cwd, catalogMap);
+                if (resolved) {
+                    activeSessions.push(resolved);
+                }
+            }
+        }
+        // Sort by modification time (most recent first)
+        activeSessions.sort((a, b) => b.modifiedAt.getTime() - a.modifiedAt.getTime());
+        return activeSessions;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find the most recent session file for a CWD (fallback for inactive detection).
+ * Uses catalog-first strategy when available.
+ *
+ * @param cwd Working directory to find sessions for
+ * @param catalogMap Pre-loaded session catalog (sessionId -> SessionEntry)
+ */
+export async function findMostRecentSessionFile(cwd, catalogMap) {
+    const projectDir = getProjectDir(cwd);
+    try {
+        await fs.access(projectDir);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const files = await fs.readdir(projectDir);
+        const jsonlFiles = files.filter((f) => f.endsWith('.jsonl'));
+        if (jsonlFiles.length === 0) {
+            return null;
+        }
+        // Find most recent file
+        let mostRecent = null;
+        for (const filename of jsonlFiles) {
+            const filePath = path.join(projectDir, filename);
+            const stats = await fs.stat(filePath);
+            if (!mostRecent || stats.mtime > mostRecent.mtime) {
+                mostRecent = { filePath, mtime: stats.mtime, filename };
+            }
+        }
+        if (!mostRecent) {
+            return null;
+        }
+        const sessionId = path.basename(mostRecent.filename, '.jsonl');
+        return resolveSessionMetadata(mostRecent.filePath, sessionId, mostRecent.mtime, cwd, catalogMap);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find the N most recently modified session files for a CWD, regardless of activity threshold.
+ * Used when there are more running processes than active session files to discover idle sessions.
+ *
+ * @param cwd Working directory to find sessions for
+ * @param catalogMap Pre-loaded session catalog (sessionId -> SessionEntry)
+ * @param count Maximum number of files to return
+ * @param excludeIds Session IDs to skip (already registered)
+ * @returns Up to `count` most recent session files, sorted by recency
+ */
+export async function findRecentSessionFiles(cwd, catalogMap, count, excludeIds) {
+    const projectDir = getProjectDir(cwd);
+    try {
+        await fs.access(projectDir);
+    }
+    catch {
+        return [];
+    }
+    try {
+        const files = await fs.readdir(projectDir);
+        const jsonlFiles = files.filter((f) => f.endsWith('.jsonl'));
+        if (jsonlFiles.length === 0) {
+            return [];
+        }
+        // Stat all files and sort by recency
+        const fileStats = [];
+        for (const filename of jsonlFiles) {
+            const sessionId = path.basename(filename, '.jsonl');
+            if (excludeIds.has(sessionId))
+                continue;
+            const filePath = path.join(projectDir, filename);
+            const stats = await fs.stat(filePath);
+            fileStats.push({ filePath, mtime: stats.mtime, filename });
+        }
+        // Sort by most recent first, take top N
+        fileStats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+        const topN = fileStats.slice(0, count);
+        const results = [];
+        for (const { filePath, mtime, filename } of topN) {
+            const sessionId = path.basename(filename, '.jsonl');
+            const resolved = await resolveSessionMetadata(filePath, sessionId, mtime, cwd, catalogMap);
+            if (resolved) {
+                results.push(resolved);
+            }
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+// ============================================================
+// Internal Helpers
+// ============================================================
+/**
+ * Get the Claude project directory for a given CWD
+ */
+function getProjectDir(cwd) {
+    const claudeDir = getClaudeProjectsDir();
+    const encodedPath = encodeProjectPath(cwd);
+    return path.join(claudeDir, encodedPath);
+}
+/**
+ * Detect session mode (planning/execution) from JSONL file
+ */
+async function detectSessionModeFromJSONL(filePath) {
+    try {
+        const entries = await parseJSONL(filePath);
+        if (entries.length === 0)
+            return null;
+        const { mode } = detectModeAndPlans(entries);
+        return mode;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract session metadata from JSONL file (fallback for uncataloged sessions)
+ */
+async function extractSessionMetadataFromJSONL(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const lines = content.split('\n').filter((l) => l.trim());
+        let sessionId = null;
+        let gitBranch = null;
+        let title = null;
+        // Parse first few lines to get session metadata
+        for (let i = 0; i < Math.min(lines.length, 50); i++) {
+            try {
+                const entry = JSON.parse(lines[i]);
+                if (!sessionId && entry.sessionId) {
+                    sessionId = entry.sessionId;
+                }
+                if (!gitBranch && entry.data?.gitBranch) {
+                    gitBranch = entry.data.gitBranch;
+                }
+                if (!title && entry.type === 'user' && entry.message?.content) {
+                    const userContent = typeof entry.message.content === 'string'
+                        ? entry.message.content
+                        : entry.message.content[0]?.text || '';
+                    if (userContent &&
+                        !userContent.trim().startsWith('<local-command') &&
+                        !userContent.trim().startsWith('<command-')) {
+                        title = userContent.split('\n')[0].slice(0, 60);
+                        if (userContent.length > 60) {
+                            title += '...';
+                        }
+                    }
+                }
+                if (sessionId && gitBranch && title)
+                    break;
+            }
+            catch {
+                continue;
+            }
+        }
+        // Parse full content for statistics
+        let contextMetrics = null;
+        try {
+            const entries = parseJSONLContent(content);
+            const stats = getEntryStatistics(entries);
+            if (stats.lastInputTokens > 0) {
+                const contextWindowSize = DEFAULT_CONTEXT_WINDOW_SIZE;
+                const usedPercentage = (stats.lastInputTokens / contextWindowSize) * 100;
+                contextMetrics = {
+                    used_percentage: Math.min(usedPercentage, 100),
+                    remaining_percentage: Math.max(100 - usedPercentage, 0),
+                    context_window_size: contextWindowSize,
+                    total_input_tokens: stats.totalInputTokens,
+                    total_output_tokens: stats.totalOutputTokens,
+                    is_estimate: true,
+                };
+            }
+        }
+        catch {
+            // Statistics extraction failed, metrics remain null
+        }
+        return { sessionId, gitBranch, title, contextMetrics };
+    }
+    catch {
+        return {
+            sessionId: null,
+            gitBranch: null,
+            title: null,
+            contextMetrics: null,
+        };
+    }
+}
+//# sourceMappingURL=session-discovery.js.map

package/dist/connection/session-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-discovery.js","sourceRoot":"","sources":["../../src/connection/session-discovery.ts"],"names":[],"mappings":"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"}

package/dist/connection/terminal-key.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Terminal Key Utilities
+ *
+ * Unified parsing, building, and matching of terminal key identifiers.
+ * Terminal keys uniquely identify terminal sessions across different terminal emulators.
+ *
+ * @module connection/terminal-key
+ */
+import { TerminalKeyPrefix } from './constants.js';
+/**
+ * Parsed terminal key structure
+ */
+export interface ParsedTerminalKey {
+    /** The terminal key prefix (ITERM, TTY, PID, etc.) */
+    prefix: TerminalKeyPrefix;
+    /** The value portion after the prefix */
+    value: string;
+    /** Extracted PID if present in the key */
+    pid?: number;
+    /** Extracted UUID for iTerm keys */
+    uuid?: string;
+    /** Extracted TTY path */
+    tty?: string;
+    /** True if key has DISCOVERED: wrapper */
+    isDiscovered: boolean;
+    /** For DISCOVERED keys, the parsed inner key */
+    innerKey?: ParsedTerminalKey;
+}
+/**
+ * Information needed to build a terminal key
+ */
+export interface TerminalIdentity {
+    /** iTerm2 session ID (e.g., "w0t0p0:UUID") */
+    itermSessionId?: string;
+    /** TTY device path (e.g., "/dev/ttys001") */
+    tty?: string;
+    /** Process ID */
+    pid?: number;
+    /** Kitty window ID */
+    kittyWindowId?: string;
+    /** WezTerm pane ID */
+    weztermPaneId?: string;
+    /** Windows Terminal session ID */
+    wtSession?: string;
+    /** Terminal.app session ID */
+    termSessionId?: string;
+}
+/**
+ * Parse a terminal key string into its components.
+ *
+ * Handles all key formats:
+ * - ITERM:w0t0p0:UUID or ITERM:UUID
+ * - TTY:/dev/ttys001
+ * - PID:12345
+ * - KITTY:42
+ * - WEZTERM:pane:0
+ * - DISCOVERED:TTY:ttys001:12345
+ * - AUTO:session-uuid
+ *
+ * @param key The terminal key string to parse
+ * @returns Parsed terminal key structure
+ */
+export declare function parseTerminalKey(key: string): ParsedTerminalKey;
+/**
+ * Build a terminal key string from identity information.
+ *
+ * Priority order:
+ * 1. iTerm session ID
+ * 2. Kitty window ID
+ * 3. WezTerm pane ID
+ * 4. Windows Terminal session
+ * 5. TTY path
+ * 6. PID (fallback)
+ *
+ * @param info Terminal identity information
+ * @returns Terminal key string or null if no valid identity
+ */
+export declare function buildTerminalKey(info: TerminalIdentity): string | null;
+/**
+ * Extract PID from a terminal key if present.
+ *
+ * Handles formats:
+ * - PID:12345
+ * - DISCOVERED:PID:12345
+ * - DISCOVERED:TTY:ttys001:12345 (PID at end)
+ *
+ * @param key Terminal key string
+ * @returns PID number or null if not extractable
+ */
+export declare function extractPid(key: string): number | null;
+/**
+ * Extract the UUID from an iTerm session ID or terminal key.
+ *
+ * iTerm's ITERM_SESSION_ID format is "w0t0p0:UUID" where:
+ * - w0 = window index
+ * - t0 = tab index
+ * - p0 = pane index
+ * - UUID = unique session identifier
+ *
+ * AppleScript's `unique ID of session` returns just the UUID portion.
+ *
+ * @param value The iTerm session ID value (after ITERM: prefix) or full key
+ * @returns The UUID portion, or the input if no colon present
+ */
+export declare function extractItermUuid(value: string): string;
+/**
+ * Check if two terminal keys refer to the same terminal.
+ *
+ * Handles special cases:
+ * - iTerm keys match by UUID (ignoring w0t0p0 prefix differences)
+ * - DISCOVERED: wrapper is unwrapped for comparison
+ * - Exact string match as fallback
+ *
+ * @param keyA First terminal key
+ * @param keyB Second terminal key
+ * @returns True if keys match the same terminal
+ */
+export declare function matchTerminalKeys(keyA: string, keyB: string): boolean;
+/**
+ * Get a human-readable description of a terminal key.
+ *
+ * @param key Terminal key string
+ * @returns Human-readable description
+ */
+export declare function describeTerminalKey(key: string): string;
+//# sourceMappingURL=terminal-key.d.ts.map

package/dist/connection/terminal-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-key.d.ts","sourceRoot":"","sources":["../../src/connection/terminal-key.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,YAAY,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAyB/D;AA+DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAuBtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAqCrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyBvD"}