sidekick-shared 0.27.5 → 0.28.0

package/dist/esm/parsers/subagentScanner.js

@@ -0,0 +1,360 @@
+/**
+ * @fileoverview Scanner for subagent JSONL files (sidekick-shared).
+ *
+ * This module provides functionality to scan Claude Code subagent session files
+ * located in <sessionDir>/<sessionId>/subagents/agent-*.jsonl and extract
+ * tool calls made by subagents.
+ *
+ * @module parsers/subagentScanner
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ClaudeUsageDeduper, dedupedRawClaudeUsage } from '../usage/claudeUsageDedupe';
+import { addUsageToSubagent } from '../usage/subagentUsage';
+import { cachedSubagentStats } from './subagentStatsCache';
+/**
+ * Pattern for matching subagent JSONL files.
+ * Files are named like: agent-<hash>.jsonl
+ */
+const AGENT_FILE_PATTERN = /^agent-(.+)\.jsonl$/;
+/**
+ * Reads `agent-<id>.meta.json` (written by Claude Code next to the transcript)
+ * for the spawn's agent type and description. Missing or malformed files
+ * yield an empty object.
+ */
+export function readAgentMeta(agentFilePath) {
+    try {
+        const metaPath = agentFilePath.replace(/\.jsonl$/, '.meta.json');
+        const parsed = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+        return {
+            ...(typeof parsed.agentType === 'string' && parsed.agentType
+                ? { agentType: parsed.agentType }
+                : {}),
+            ...(typeof parsed.description === 'string' && parsed.description
+                ? { description: parsed.description }
+                : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** Task-related tool names */
+const TASK_TOOLS = ['TaskCreate', 'TaskUpdate', 'TaskGet', 'TaskList'];
+/**
+ * Extracts task ID from TaskCreate result content.
+ *
+ * Looks for "Task #N" or JSON taskId patterns in the result string.
+ */
+function extractTaskIdFromResult(resultContent) {
+    const resultStr = typeof resultContent === 'string' ? resultContent : JSON.stringify(resultContent || '');
+    // Try to match "Task #N" pattern
+    const taskIdMatch = resultStr.match(/Task #(\d+)/i);
+    if (taskIdMatch) {
+        return taskIdMatch[1];
+    }
+    // Try to match taskId in JSON-like content
+    const jsonIdMatch = resultStr.match(/"taskId"\s*:\s*"?(\d+)"?/i);
+    if (jsonIdMatch) {
+        return jsonIdMatch[1];
+    }
+    return null;
+}
+/** Tracks directories already reported as missing to avoid log spam */
+const reportedMissing = new Set();
+/**
+ * Scans subagent directory for agent JSONL files and extracts tool calls.
+ *
+ * Subagent files are located at: <sessionDir>/<sessionId>/subagents/agent-*.jsonl
+ *
+ * @param sessionDir - Directory containing the session file
+ * @param sessionId - Session ID (filename without .jsonl extension)
+ * @param logger - Optional logging function; messages are silently discarded if not provided
+ * @returns Array of SubagentStats with tool calls, empty array if no subagents
+ *
+ * @example
+ * ```typescript
+ * const stats = scanSubagentDir('/home/user/.claude/projects/myproject', 'abc123');
+ * for (const agent of stats) {
+ *   console.log(`Agent ${agent.agentId}: ${agent.toolCalls.length} tool calls`);
+ * }
+ * ```
+ */
+export function scanSubagentDir(sessionDir, sessionId, logger, skipFiles = new Set()) {
+    const log = logger || (() => { });
+    const subagentsDir = path.join(sessionDir, sessionId, 'subagents');
+    const results = [];
+    try {
+        if (!fs.existsSync(subagentsDir)) {
+            if (!reportedMissing.has(subagentsDir)) {
+                reportedMissing.add(subagentsDir);
+                log(`[SubagentScanner] No subagents directory: ${subagentsDir}`);
+            }
+            return results;
+        }
+        // Directory appeared — clear the missing flag so future disappearances get logged
+        reportedMissing.delete(subagentsDir);
+        const files = fs.readdirSync(subagentsDir);
+        log(`[SubagentScanner] Found ${files.length} files: ${files.join(', ')}`);
+        for (const file of files) {
+            if (skipFiles.has(file))
+                continue;
+            const match = file.match(AGENT_FILE_PATTERN);
+            if (!match) {
+                continue;
+            }
+            const agentId = match[1];
+            const filePath = path.join(subagentsDir, file);
+            const agentStats = cachedSubagentStats(filePath, () => parseAgentFile(filePath, agentId, log));
+            if (agentStats) {
+                log(`[SubagentScanner] Agent ${agentId}: ${agentStats.toolCalls.length} tool calls`);
+                results.push(agentStats);
+            }
+            else {
+                log(`[SubagentScanner] Agent ${agentId}: no stats returned`);
+            }
+        }
+    }
+    catch {
+        // Directory read failed - subagents dir may not exist yet
+        log(`Failed to scan subagents directory: ${subagentsDir}`);
+    }
+    log(`[SubagentScanner] Returning ${results.length} subagent stats`);
+    return results;
+}
+/**
+ * Parses a single subagent JSONL file and extracts tool calls and task state.
+ *
+ * @param filePath - Path to the agent JSONL file
+ * @param agentId - Agent ID extracted from filename
+ * @param log - Logging function
+ * @returns SubagentStats or null if parsing fails
+ */
+function parseAgentFile(filePath, agentId, log) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n').filter((line) => line.trim());
+        const toolCalls = [];
+        let agentType;
+        let description;
+        const tokens = { agentId, toolCalls: [], inputTokens: 0, outputTokens: 0 };
+        const usageDeduper = new ClaudeUsageDeduper();
+        let startTime;
+        let endTime;
+        // Task tracking state
+        const taskState = {
+            tasks: new Map(),
+            activeTaskId: null,
+        };
+        const pendingTaskCreates = new Map();
+        for (const line of lines) {
+            try {
+                const event = JSON.parse(line);
+                const eventTimestamp = new Date(event.timestamp || Date.now());
+                // Track start/end times
+                if (!startTime)
+                    startTime = eventTimestamp;
+                endTime = eventTimestamp;
+                // Extract token usage from assistant messages. Split lines of one
+                // response repeat its usage, so count each response once.
+                const usage = dedupedRawClaudeUsage(event, usageDeduper);
+                if (usage)
+                    addUsageToSubagent(tokens, usage);
+                // Extract agent type and description from Task tool invocation
+                // This appears in the parent session, but we can also look for it
+                // in the first system message or context
+                if (event.type === 'system' && event.message?.content) {
+                    const contentStr = typeof event.message.content === 'string'
+                        ? event.message.content
+                        : JSON.stringify(event.message.content);
+                    // Try to extract agent type from system message
+                    const typeMatch = contentStr.match(/subagent_type['":\s]+(\w+)/i);
+                    if (typeMatch) {
+                        agentType = typeMatch[1];
+                    }
+                }
+                // Look for tool_use events in assistant messages
+                if (event.type === 'assistant' && event.message?.content) {
+                    const contentArray = Array.isArray(event.message.content) ? event.message.content : [];
+                    for (const block of contentArray) {
+                        if (block && typeof block === 'object' && block.type === 'tool_use') {
+                            const toolUse = block;
+                            const toolCall = {
+                                name: toolUse.name,
+                                input: toolUse.input || {},
+                                timestamp: eventTimestamp,
+                            };
+                            // Handle task tools
+                            if (toolUse.name === 'TaskCreate') {
+                                pendingTaskCreates.set(toolUse.id, {
+                                    subject: String(toolUse.input.subject || ''),
+                                    description: toolUse.input.description
+                                        ? String(toolUse.input.description)
+                                        : undefined,
+                                    activeForm: toolUse.input.activeForm
+                                        ? String(toolUse.input.activeForm)
+                                        : undefined,
+                                    timestamp: eventTimestamp,
+                                });
+                            }
+                            else if (toolUse.name === 'TaskUpdate') {
+                                handleTaskUpdate(taskState, toolUse.input, eventTimestamp);
+                            }
+                            // Associate non-task tool calls with active task
+                            if (!TASK_TOOLS.includes(toolUse.name) && taskState.activeTaskId) {
+                                const activeTask = taskState.tasks.get(taskState.activeTaskId);
+                                if (activeTask) {
+                                    activeTask.associatedToolCalls.push(toolCall);
+                                }
+                            }
+                            toolCalls.push(toolCall);
+                            // If this is a Task tool call (spawning another subagent), extract info
+                            if (toolUse.name === 'Task' && toolUse.input) {
+                                if (toolUse.input.subagent_type && !agentType) {
+                                    agentType = String(toolUse.input.subagent_type);
+                                }
+                                if (toolUse.input.description && !description) {
+                                    description = String(toolUse.input.description);
+                                }
+                            }
+                        }
+                    }
+                }
+                // Look for tool_result events in user messages
+                if (event.type === 'user' && event.message?.content) {
+                    const contentArray = Array.isArray(event.message.content) ? event.message.content : [];
+                    for (const block of contentArray) {
+                        if (block && typeof block === 'object' && block.type === 'tool_result') {
+                            const toolResult = block;
+                            // Handle TaskCreate results
+                            const pendingCreate = pendingTaskCreates.get(toolResult.tool_use_id);
+                            if (pendingCreate && !toolResult.is_error) {
+                                const taskId = extractTaskIdFromResult(toolResult.content);
+                                if (taskId) {
+                                    const task = {
+                                        taskId,
+                                        subject: pendingCreate.subject,
+                                        description: pendingCreate.description,
+                                        status: 'pending',
+                                        createdAt: pendingCreate.timestamp,
+                                        updatedAt: eventTimestamp,
+                                        activeForm: pendingCreate.activeForm,
+                                        blockedBy: [],
+                                        blocks: [],
+                                        associatedToolCalls: [],
+                                    };
+                                    taskState.tasks.set(taskId, task);
+                                }
+                                pendingTaskCreates.delete(toolResult.tool_use_id);
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        // Claude Code writes the spawn's type and description beside the transcript.
+        const meta = readAgentMeta(filePath);
+        agentType = meta.agentType ?? agentType;
+        description = meta.description ?? description;
+        // If we found any tool calls, return the stats
+        if (toolCalls.length > 0 || agentType || description || (tokens.totalTokens ?? 0) > 0) {
+            const durationMs = startTime && endTime ? endTime.getTime() - startTime.getTime() : undefined;
+            return {
+                agentId,
+                agentType,
+                description,
+                toolCalls,
+                taskState: taskState.tasks.size > 0 ? taskState : undefined,
+                inputTokens: tokens.inputTokens,
+                outputTokens: tokens.outputTokens,
+                cacheReadTokens: tokens.cacheReadTokens ?? 0,
+                cacheWriteTokens: tokens.cacheWriteTokens ?? 0,
+                reasoningTokens: tokens.reasoningTokens ?? 0,
+                totalTokens: tokens.totalTokens ?? 0,
+                startTime,
+                endTime,
+                durationMs,
+            };
+        }
+        return null;
+    }
+    catch {
+        log(`Failed to parse agent file: ${filePath}`);
+        return null;
+    }
+}
+/**
+ * Handles TaskUpdate tool input and updates task state.
+ */
+export function handleTaskUpdate(taskState, input, timestamp) {
+    const taskId = String(input.taskId || '');
+    let task = taskState.tasks.get(taskId);
+    if (!task) {
+        // Create placeholder task for unknown TaskUpdate
+        task = {
+            taskId,
+            subject: input.subject ? String(input.subject) : `Task ${taskId}`,
+            description: input.description ? String(input.description) : undefined,
+            status: 'pending',
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            blockedBy: [],
+            blocks: [],
+            associatedToolCalls: [],
+        };
+        taskState.tasks.set(taskId, task);
+    }
+    // Update task fields
+    if (input.status) {
+        const newStatus = input.status;
+        const oldStatus = task.status;
+        task.status = newStatus;
+        // Track active task transitions
+        if (newStatus === 'in_progress' && oldStatus !== 'in_progress') {
+            taskState.activeTaskId = taskId;
+        }
+        else if (oldStatus === 'in_progress' && newStatus !== 'in_progress') {
+            if (taskState.activeTaskId === taskId) {
+                taskState.activeTaskId = null;
+            }
+        }
+    }
+    if (input.subject)
+        task.subject = String(input.subject);
+    if (input.description)
+        task.description = String(input.description);
+    if (input.activeForm)
+        task.activeForm = String(input.activeForm);
+    if (Array.isArray(input.addBlockedBy)) {
+        for (const id of input.addBlockedBy) {
+            const idStr = String(id);
+            if (!task.blockedBy.includes(idStr)) {
+                task.blockedBy.push(idStr);
+            }
+        }
+    }
+    if (Array.isArray(input.addBlocks)) {
+        for (const id of input.addBlocks) {
+            const idStr = String(id);
+            if (!task.blocks.includes(idStr)) {
+                task.blocks.push(idStr);
+            }
+        }
+    }
+    task.updatedAt = timestamp;
+}
+/**
+ * Extracts agent type and description from a Task tool call input.
+ *
+ * @param input - Task tool input parameters
+ * @returns Object with agentType and description if found
+ */
+export function extractTaskInfo(input) {
+    return {
+        agentType: input.subagent_type ? String(input.subagent_type) : undefined,
+        description: input.description ? String(input.description) : undefined,
+    };
+}

package/dist/esm/parsers/subagentStatsCache.js

@@ -0,0 +1,45 @@
+/**
+ * Memoizes per-transcript subagent stats by file size and mtime.
+ *
+ * Dashboards rescan a session's subagents on a timer, and one parent can own
+ * a hundred subagent transcripts of several MB each. An unchanged transcript
+ * now costs one `stat` instead of a full parse. Callers treat the returned
+ * stats as read-only.
+ *
+ * Node-only: stats files.
+ *
+ * @module parsers/subagentStatsCache
+ */
+import * as fs from 'fs';
+const MAX_ENTRIES = 1024;
+const cache = new Map();
+/** Stats for one subagent transcript, parsed again only when the file changed. */
+export function cachedSubagentStats(filePath, compute) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        cache.delete(filePath);
+        return compute();
+    }
+    const hit = cache.get(filePath);
+    if (hit && hit.size === stat.size && hit.mtimeMs === stat.mtimeMs) {
+        cache.delete(filePath);
+        cache.set(filePath, hit);
+        return hit.stats;
+    }
+    const stats = compute();
+    cache.delete(filePath);
+    cache.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs, stats });
+    if (cache.size > MAX_ENTRIES) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+    return stats;
+}
+/** @internal Test hook. */
+export function clearSubagentStatsCache() {
+    cache.clear();
+}