aicodeman 0.2.8

package/dist/task-tracker.d.ts

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview Background Task Tracker for Claude Code sessions
+ *
+ * This module tracks background tasks (subagents) spawned by Claude Code
+ * during session execution. It parses both JSON messages and terminal output
+ * to detect when tasks are created, updated, and completed.
+ *
+ * ## Task Hierarchy
+ *
+ * Tasks can be nested (parent-child relationships) when Claude spawns
+ * a subagent from within another subagent. The tracker maintains a stack
+ * to track nesting and a tree structure for visualization.
+ *
+ * ## Detection Methods
+ *
+ * 1. **JSON Messages**: Parses `tool_use` blocks for Task tool invocations
+ *    and `tool_result` blocks for completion
+ * 2. **Terminal Output**: Fallback pattern matching for launch/complete messages
+ *
+ * @module task-tracker
+ */
+import { EventEmitter } from 'node:events';
+/**
+ * Content block for tool_use messages from Claude.
+ * Emitted when Claude invokes a tool.
+ */
+interface ClaudeToolUseBlock {
+    type: 'tool_use';
+    /** Unique identifier for this tool invocation */
+    id: string;
+    /** Name of the tool being invoked */
+    name: string;
+    /** Parameters passed to the tool */
+    input?: {
+        description?: string;
+        prompt?: string;
+        subagent_type?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Content block for tool_result messages from Claude.
+ * Emitted when a tool completes execution.
+ */
+interface ClaudeToolResultBlock {
+    type: 'tool_result';
+    /** ID of the tool_use this result corresponds to */
+    tool_use_id: string;
+    /** Whether the tool execution resulted in an error */
+    is_error?: boolean;
+    /** Result content (string or structured data) */
+    content?: string | unknown;
+}
+/**
+ * Union type for content blocks we care about.
+ */
+type ClaudeContentBlock = ClaudeToolUseBlock | ClaudeToolResultBlock | {
+    type: string;
+};
+/**
+ * Claude JSON message structure.
+ * This is the format Claude Code outputs for streaming events.
+ */
+interface ClaudeMessage {
+    message?: {
+        content?: ClaudeContentBlock[];
+    };
+}
+/**
+ * Represents a background task spawned by Claude Code.
+ *
+ * Tasks form a tree structure where a parent task can spawn child tasks.
+ * This enables tracking of nested agent invocations.
+ */
+export interface BackgroundTask {
+    /** Unique task identifier (usually the tool_use ID from Claude) */
+    id: string;
+    /** Parent task ID if this is a nested task, null for root tasks */
+    parentId: string | null;
+    /** Human-readable description of what the task is doing */
+    description: string;
+    /** Type of subagent (e.g., 'explore', 'bash', 'general-purpose') */
+    subagentType: string;
+    /** Current execution status */
+    status: 'running' | 'completed' | 'failed';
+    /** Timestamp when task was created (milliseconds since epoch) */
+    startTime: number;
+    /** Timestamp when task finished (milliseconds since epoch) */
+    endTime?: number;
+    /** Output/result from the task execution */
+    output?: string;
+    /** IDs of child tasks spawned by this task */
+    children: string[];
+}
+/**
+ * Events emitted by TaskTracker.
+ *
+ * @event taskCreated - New task detected and added
+ * @event taskUpdated - Task state changed (rarely used)
+ * @event taskCompleted - Task finished successfully
+ * @event taskFailed - Task finished with error
+ */
+export interface TaskTrackerEvents {
+    /** New task created */
+    taskCreated: (task: BackgroundTask) => void;
+    /** Task state updated */
+    taskUpdated: (task: BackgroundTask) => void;
+    /** Task completed successfully */
+    taskCompleted: (task: BackgroundTask) => void;
+    /** Task failed with error */
+    taskFailed: (task: BackgroundTask, error: string) => void;
+}
+/**
+ * TaskTracker - Detects and tracks background tasks in Claude Code sessions.
+ *
+ * ## How It Works
+ *
+ * Claude Code outputs JSON messages when executing. When it spawns a subagent
+ * via the Task tool, we see:
+ *
+ * 1. `tool_use` block with `name: "Task"` and input parameters
+ * 2. ... task execution output ...
+ * 3. `tool_result` block with the result or error
+ *
+ * The tracker maintains:
+ * - A map of all tasks by ID
+ * - A stack of currently running tasks (for nesting)
+ * - Parent-child relationships between tasks
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const tracker = new TaskTracker();
+ *
+ * tracker.on('taskCreated', (task) => {
+ *   console.log(`New task: ${task.description}`);
+ * });
+ *
+ * tracker.on('taskCompleted', (task) => {
+ *   console.log(`Task done: ${task.id}`);
+ * });
+ *
+ * // Feed in Claude messages
+ * tracker.processMessage(claudeJsonMessage);
+ *
+ * // Or terminal output as fallback
+ * tracker.processTerminalOutput(ptyData);
+ * ```
+ *
+ * @extends EventEmitter
+ */
+export declare class TaskTracker extends EventEmitter {
+    /** Map of task ID to task object */
+    private tasks;
+    /** Stack of active task IDs for tracking nesting depth */
+    private taskStack;
+    /** Pending tool_use blocks waiting for results (with timestamp for cleanup) */
+    private pendingToolUses;
+    /**
+     * Creates a new TaskTracker instance.
+     */
+    constructor();
+    /**
+     * Process a Claude JSON message to detect task events.
+     *
+     * Looks for `tool_use` blocks with `name: "Task"` and `tool_result` blocks
+     * to track task lifecycle.
+     *
+     * @param msg - Parsed Claude JSON message object
+     * @fires taskCreated - When a new task is detected
+     * @fires taskCompleted - When a task finishes successfully
+     * @fires taskFailed - When a task finishes with error
+     */
+    processMessage(msg: ClaudeMessage | null | undefined): void;
+    /**
+     * Process raw terminal output to detect task patterns.
+     *
+     * This is a fallback for when JSON parsing doesn't capture everything.
+     * Uses pre-compiled patterns to detect launch and completion messages.
+     *
+     * Note: May create duplicate tasks in some cases; deduplication is
+     * handled by checking for existing running tasks of the same type.
+     *
+     * @param data - Raw terminal output string
+     * @fires taskCreated - When a launch pattern is matched
+     * @fires taskCompleted - When a complete pattern is matched
+     */
+    processTerminalOutput(data: string): void;
+    /**
+     * Handle a tool_use block for the Task tool.
+     * Creates a new task and pushes it onto the stack.
+     *
+     * @param block - The tool_use content block
+     * @fires taskCreated
+     */
+    private handleTaskToolUse;
+    /**
+     * Handle a tool_result block.
+     * Marks the corresponding task as completed or failed.
+     *
+     * @param block - The tool_result content block
+     * @fires taskCompleted - If result is success
+     * @fires taskFailed - If result is error
+     */
+    private handleToolResult;
+    /**
+     * Remove old pending tool uses that never received results.
+     * Prevents unbounded growth if tool_results never arrive.
+     */
+    private cleanupOldPendingToolUses;
+    /**
+     * Remove old completed/failed tasks when exceeding the limit
+     * Keeps running tasks and the most recent completed tasks
+     */
+    private cleanupCompletedTasks;
+    /**
+     * Create a task from terminal pattern detection.
+     * Used as fallback when JSON messages aren't available.
+     *
+     * @param agentType - Type of agent detected
+     * @param context - Terminal context for debugging
+     * @fires taskCreated
+     */
+    private createTaskFromTerminal;
+    /**
+     * Mark a task as completed.
+     *
+     * @param taskId - ID of task to complete
+     * @fires taskCompleted - If task was running
+     */
+    private completeTask;
+    /**
+     * Get the most recently started running task.
+     * Returns the task at the top of the stack (most nested).
+     *
+     * @returns Most recent running task, or undefined if none
+     */
+    private getMostRecentRunningTask;
+    /**
+     * Get root-level tasks as a list.
+     *
+     * Child tasks can be accessed via the `children` array on each task.
+     * Use this for displaying a task tree in the UI.
+     *
+     * @returns Array of tasks without parents (root level)
+     */
+    getTaskTree(): BackgroundTask[];
+    /**
+     * Lightweight task tree for SSE broadcasts — strips large `output` strings
+     * to avoid serializing 5-10MB of task results every 500ms.
+     * Full task details available via getTaskTree().
+     *
+     * @returns Array of root tasks with output truncated to 200 chars
+     */
+    getTaskTreeLight(): Omit<BackgroundTask, 'output'>[];
+    /**
+     * Get all tasks as a flat Map.
+     *
+     * @returns Copy of the internal tasks map (safe to modify)
+     */
+    getAllTasks(): Map<string, BackgroundTask>;
+    /**
+     * Get a specific task by its ID.
+     *
+     * @param taskId - The task ID to look up
+     * @returns The task if found, undefined otherwise
+     */
+    getTask(taskId: string): BackgroundTask | undefined;
+    /**
+     * Get the count of currently running tasks.
+     *
+     * @returns Number of tasks with status 'running'
+     */
+    getRunningCount(): number;
+    /**
+     * Get aggregated statistics about all tracked tasks.
+     *
+     * @returns Object with counts:
+     *   - total: Total number of tracked tasks
+     *   - running: Tasks currently executing
+     *   - completed: Successfully finished tasks
+     *   - failed: Tasks that ended with errors
+     */
+    getStats(): {
+        total: number;
+        running: number;
+        completed: number;
+        failed: number;
+    };
+    /**
+     * Clear all tracked tasks.
+     *
+     * Use when the session is cleared or closed.
+     * Resets the task map, stack, and pending tool uses.
+     */
+    clear(): void;
+    /**
+     * Clean up resources and release memory.
+     *
+     * Call this when the session is being destroyed to prevent memory leaks.
+     * Clears all data and removes all event listeners.
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=task-tracker.d.ts.map

package/dist/task-tracker.d.ts.map

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