task-o-matic-core 0.1.0

package/src/lib/ai-service/research-tools.ts

@@ -0,0 +1,207 @@
+import { tool, type Tool } from "ai";
+import { z } from "zod/v3";
+import { TaskRepository } from "../storage/types";
+import { getStorage } from "../../utils/ai-service-factory";
+
+export class ResearchTools {
+  private storage: TaskRepository = getStorage();
+  //   /**
+  //    * Creates a tool for getting cached Context7 content
+  //    */
+  // createCacheTool(): Tool {
+  //   const cacheTool: Tool<string, string> = tool({
+  //     description:
+  //       "Get cached Context7 content using the cache file path from .task-o-matic/docs/_cache/",
+  //     parameters: z.object({
+  //       cacheKey: z
+  //         .string()
+  //         .describe(
+  //           "The cache file path, e.g., 'react-hooks' or 'docs/_cache/react-hooks.json'"
+  //         ),
+  //     }),
+  //     execute: async () => {
+  //       try {
+  //         const normalizedKey = cacheKey
+  //           .replace(/^docs\/_cache\//, "")
+  //           .replace(/\.json$/, "");
+  //         const content =
+  //           await this.storage.getCachedDocumentation(normalizedKey);
+
+  //         if (!content) {
+  //           return `Cache content not found for key: ${normalizedKey}`;
+  //         }
+
+  //         return content;
+  //       } catch (error) {
+  //         return `Error retrieving cache content: ${error instanceof Error ? error.message : String(error)}`;
+  //       }
+  //     },
+  //   });
+  //   return cacheTool;
+  // }
+  //   /**
+  //    * Creates a tool for getting documentation file content
+  //    */
+  //   createDocumentationTool() {
+  //     return tool({
+  //       description: "Get documentation file content from .task-o-matic/docs/ directory",
+  //       inputSchema: z.object({
+  //         docKey: z
+  //           .string()
+  //           .describe("The documentation file path, e.g., 'react/components.md' or just 'components'"),
+  //       }),
+  //       execute: async ({ docKey }) => {
+  //         try {
+  //           // Handle both full path and just the filename
+  //           const normalizedKey = docKey.replace(/^docs\//, "");
+  //           const content = await this.storage.getDocumentationFile(normalizedKey);
+  //           if (!content) {
+  //             return {
+  //               success: false,
+  //               error: `Documentation file not found for key: ${normalizedKey}`,
+  //             };
+  //           }
+  //           return {
+  //             success: true,
+  //             content,
+  //             key: normalizedKey,
+  //           };
+  //         } catch (error) {
+  //           return {
+  //             success: false,
+  //             error: error instanceof Error ? error.message : String(error),
+  //           };
+  //         }
+  //       },
+  //     });
+  //   }
+  //   /**
+  //    * Creates a tool for listing available cache files
+  //    */
+  //   createListCacheTool() {
+  //     return tool({
+  //       description: "List all available cached Context7 files in .task-o-matic/docs/_cache/",
+  //       inputSchema: z.object({
+  //         filter: z
+  //           .string()
+  //           .optional()
+  //           .describe("Optional filter to search for specific cache files (e.g., 'react', 'nextjs')"),
+  //       }),
+  //       execute: async ({ filter }) => {
+  //         try {
+  //           const availableKeys = await this.getAvailableCacheKeys();
+  //           let filteredKeys = availableKeys;
+  //           if (filter) {
+  //             filteredKeys = availableKeys.filter(key =>
+  //               key.toLowerCase().includes(filter.toLowerCase())
+  //             );
+  //           }
+  //           return {
+  //             success: true,
+  //             cacheFiles: filteredKeys,
+  //             total: filteredKeys.length,
+  //             filter: filter || null,
+  //           };
+  //         } catch (error) {
+  //           return {
+  //             success: false,
+  //             error: error instanceof Error ? error.message : String(error),
+  //           };
+  //         }
+  //       },
+  //     });
+  //   }
+  //   /**
+  //    * Creates a tool for listing available documentation files
+  //    */
+  //   createListDocumentationTool() {
+  //     return tool({
+  //       description: "List all available documentation files in .task-o-matic/docs/ directory",
+  //       inputSchema: z.object({
+  //         filter: z
+  //           .string()
+  //           .optional()
+  //           .describe("Optional filter to search for specific documentation files (e.g., 'react', 'api')"),
+  //       }),
+  //       execute: async ({ filter }) => {
+  //         try {
+  //           const availableFiles = await this.getAvailableDocumentationFiles();
+  //           let filteredFiles = availableFiles;
+  //           if (filter) {
+  //             filteredFiles = availableFiles.filter(file =>
+  //               file.toLowerCase().includes(filter.toLowerCase())
+  //             );
+  //           }
+  //           return {
+  //             success: true,
+  //             documentationFiles: filteredFiles,
+  //             total: filteredFiles.length,
+  //             filter: filter || null,
+  //           };
+  //         } catch (error) {
+  //           return {
+  //             success: false,
+  //             error: error instanceof Error ? error.message : String(error),
+  //           };
+  //         }
+  //       },
+  //     });
+  //   }
+  //   /**
+  //    * Get all available cache keys
+  //    */
+  //   private async getAvailableCacheKeys(): Promise<string[]> {
+  //     try {
+  //       return await this.storage.listCachedDocumentationFiles();
+  //     } catch (error) {
+  //       console.error("Error getting available cache keys:", error);
+  //       return [];
+  //     }
+  //   }
+  //   /**
+  //    * Get all available documentation files
+  //    */
+  //   private async getAvailableDocumentationFiles(): Promise<string[]> {
+  //     try {
+  //       return await this.storage.listDocumentationFiles();
+  //     } catch (error) {
+  //       console.error("Error getting available documentation files:", error);
+  //       return [];
+  //     }
+  //   }
+  //   /**
+  //    * Get all research tools as a ToolSet
+  //    */
+  //   getResearchTools(): ToolSet {
+  //     return {
+  //       get_cache_context7: this.createCacheTool(),
+  //       get_documentation: this.createDocumentationTool(),
+  //       list_cache_files: this.createListCacheTool(),
+  //       list_documentation_files: this.createListDocumentationTool(),
+  //     };
+  //   }
+  //   /**
+  //    * Get tool descriptions for system prompt
+  //    */
+  //   getToolDescriptions(): string {
+  //     return `
+  // ## Available Research Tools:
+  // 1. **get_cache_context7**: Get cached Context7 content using cache file path
+  //    - Input: cacheKey (string) - e.g., 'react-hooks' or 'docs/_cache/react-hooks.json'
+  //    - Returns: Cached Context7 documentation content
+  // 2. **get_documentation**: Get documentation file content from docs directory
+  //    - Input: docKey (string) - e.g., 'components' or 'docs/components.md'
+  //    - Returns: Processed documentation file content
+  // 3. **list_cache_files**: List all available cached Context7 files
+  //    - Input: filter (optional string) - Filter results by keyword
+  //    - Returns: List of available cache files
+  // 4. **list_documentation_files**: List all available documentation files
+  //    - Input: filter (optional string) - Filter results by keyword
+  //    - Returns: List of available documentation files
+  // ## Usage Strategy:
+  // 1. Use list_* tools first to discover available content
+  // 2. Use get_* tools to retrieve specific content
+  // 3. Combine with Context7 MCP tools for comprehensive research
+  // `;
+  //   }
+}

package/src/lib/ai-service/retry-handler.ts

@@ -0,0 +1,89 @@
+import { RetryConfig } from "../../types";
+import { logger } from "../logger";
+
+export class RetryHandler {
+  private getRetryConfig(): RetryConfig {
+    return {
+      maxAttempts: parseInt(process.env.AI_MAX_RETRY_ATTEMPTS || "3", 10),
+      baseDelay: parseInt(process.env.AI_RETRY_BASE_DELAY || "1000", 10),
+      maxDelay: parseInt(process.env.AI_RETRY_MAX_DELAY || "10000", 10),
+      backoffFactor: parseFloat(process.env.AI_RETRY_BACKOFF_FACTOR || "2"),
+      retryableErrors: [
+        "ECONNRESET",
+        "ENOTFOUND",
+        "ECONNREFUSED",
+        "ETIMEDOUT",
+        "NETWORK_ERROR",
+        "RATE_LIMIT",
+        "TEMPORARY_FAILURE",
+        "INTERNAL_ERROR",
+      ],
+    };
+  }
+
+  private shouldRetryError(error: unknown, retryableErrors: string[]): boolean {
+    if (!error) return false;
+
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorName = error instanceof Error ? error.name : "";
+
+    return retryableErrors.some(
+      (retryableError) =>
+        errorMessage.toUpperCase().includes(retryableError) ||
+        errorName.toUpperCase().includes(retryableError)
+    );
+  }
+
+  private async delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  async executeWithRetry<T>(
+    operation: () => Promise<T>,
+    retryConfig?: Partial<RetryConfig>,
+    operationName: string = "AI operation"
+  ): Promise<T> {
+    const finalRetryConfig = { ...this.getRetryConfig(), ...retryConfig };
+    const {
+      maxAttempts = 3,
+      baseDelay = 1000,
+      maxDelay = 10000,
+      backoffFactor = 2,
+      retryableErrors = [],
+    } = finalRetryConfig;
+
+    let lastError: unknown;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+
+        // Don't retry on the last attempt
+        if (attempt === maxAttempts) {
+          break;
+        }
+
+        // Check if error is retryable
+        if (!this.shouldRetryError(error, retryableErrors)) {
+          break;
+        }
+
+        // Calculate delay with exponential backoff
+        const delayMs = Math.min(
+          baseDelay * Math.pow(backoffFactor, attempt - 1),
+          maxDelay
+        );
+
+        logger.warn(
+          `${operationName} failed (attempt ${attempt}/${maxAttempts}), retrying in ${delayMs}ms: ${error}`
+        );
+        await this.delay(delayMs);
+      }
+    }
+
+    // Throw the original error - NO rebuilding bullshit
+    throw lastError;
+  }
+}

package/src/lib/ai-service/task-operations.ts

@@ -0,0 +1,342 @@
+import { streamText } from "ai";
+import type { ToolSet } from "ai";
+import {
+  AIConfig,
+  Task,
+  StreamingOptions,
+  RetryConfig,
+  ParsedAITask,
+} from "../../types";
+import { PromptBuilder } from "../prompt-builder";
+import { formatStackForContext } from "../../utils/stack-formatter";
+import {
+  TASK_BREAKDOWN_SYSTEM_PROMPT,
+  TASK_ENHANCEMENT_SYSTEM_PROMPT,
+  TASK_PLANNING_SYSTEM_PROMPT,
+} from "../../prompts";
+import { getContextBuilder } from "../../utils/ai-service-factory";
+import { filesystemTools } from "./filesystem-tools";
+import { BaseOperations } from "./base-operations";
+import { AIOperationUtility } from "../../utils/ai-operation-utility";
+import {
+  createStandardError,
+  TaskOMaticErrorCodes,
+} from "../../utils/task-o-matic-error";
+
+export class TaskOperations extends BaseOperations {
+  private aiOperationUtility = new AIOperationUtility();
+  async breakdownTask(
+    task: Task,
+    config?: Partial<AIConfig>,
+    promptOverride?: string,
+    userMessage?: string,
+    streamingOptions?: StreamingOptions,
+    retryConfig?: Partial<RetryConfig>,
+    fullContent?: string,
+    stackInfo?: string,
+    existingSubtasks?: Task[],
+    enableFilesystemTools?: boolean
+  ): Promise<
+    Array<{ title: string; content: string; estimatedEffort?: string }>
+  > {
+    // Build prompt
+    let prompt: string;
+    if (promptOverride) {
+      prompt = promptOverride;
+    } else {
+      const variables: Record<string, string> = {
+        TASK_TITLE: task.title,
+        TASK_DESCRIPTION: task.description || "No description",
+      };
+
+      if (fullContent) {
+        variables.TASK_CONTENT = fullContent;
+      }
+
+      if (existingSubtasks && existingSubtasks.length > 0) {
+        const existingSubtasksText = existingSubtasks
+          .map(
+            (subtask, index) =>
+              `${index + 1}. ${subtask.title}: ${
+                subtask.description || "No description"
+              }`
+          )
+          .join("\n");
+        variables.EXISTING_SUBTASKS = existingSubtasksText;
+      }
+
+      if (stackInfo) {
+        variables.STACK_INFO = stackInfo;
+      }
+
+      const promptResult = PromptBuilder.buildPrompt({
+        name: "task-breakdown",
+        type: "user",
+        variables,
+      });
+
+      if (!promptResult.success) {
+        throw createStandardError(
+          TaskOMaticErrorCodes.AI_OPERATION_FAILED,
+          `Failed to build task breakdown prompt: ${promptResult.error}`,
+          {
+            context: "Prompt building failed during task breakdown operation",
+            suggestions: [
+              "Verify prompt template exists",
+              "Check variable substitution",
+            ],
+          }
+        );
+      }
+
+      prompt = promptResult.prompt!;
+    }
+
+    // Execute AI operation with proper error handling
+    const result = await this.aiOperationUtility.executeAIOperation(
+      "Task breakdown",
+      async () => {
+        // Prepare tools if filesystem tools are enabled
+        const tools = enableFilesystemTools ? filesystemTools : undefined;
+
+        const response = await this.aiOperationUtility.streamTextWithTools(
+          TASK_BREAKDOWN_SYSTEM_PROMPT +
+            (enableFilesystemTools
+              ? `
+
+You have access to filesystem tools that allow you to:
+- readFile: Read the contents of any file in the project
+- listDirectory: List contents of directories
+
+Use these tools to understand the project structure, existing code, and dependencies when breaking down tasks into subtasks.`
+              : ""),
+          userMessage || prompt,
+          config,
+          streamingOptions,
+          tools
+        );
+
+        const parseResult = this.jsonParser.parseJSONFromResponse<
+          { subtasks?: ParsedAITask[]; tasks?: ParsedAITask[] } | ParsedAITask[]
+        >(response);
+
+        if (!parseResult.success) {
+          throw createStandardError(
+            TaskOMaticErrorCodes.AI_OPERATION_FAILED,
+            parseResult.error || "Failed to parse task breakdown response",
+            {
+              context: "AI response parsing failed during task breakdown",
+              suggestions: [
+                "Check AI response format",
+                "Verify JSON structure",
+              ],
+            }
+          );
+        }
+
+        const parsed = parseResult.data;
+        let subtasksList: ParsedAITask[] = [];
+
+        // Handle various output formats (Array, { subtasks: [] }, { tasks: [] })
+        if (Array.isArray(parsed)) {
+          subtasksList = parsed;
+        } else if (parsed && typeof parsed === "object") {
+          subtasksList = parsed.subtasks || parsed.tasks || [];
+        }
+
+        return subtasksList.map((subtask: ParsedAITask) => ({
+          title: subtask.title,
+          content: subtask.description || subtask.content || "",
+          estimatedEffort: subtask.effort,
+        }));
+      },
+      {
+        streamingOptions,
+        retryConfig,
+        aiConfig: config,
+        maxRetries: retryConfig?.maxAttempts || 2,
+      }
+    );
+
+    // Return the result directly (errors are thrown, not returned)
+    return result.result;
+  }
+
+  async enhanceTask(
+    title: string,
+    description?: string,
+    config?: Partial<AIConfig>,
+    promptOverride?: string,
+    userMessage?: string,
+    taskId?: string,
+    streamingOptions?: StreamingOptions,
+    retryConfig?: Partial<RetryConfig>
+  ): Promise<string> {
+    // Build context
+    let contextInfo = "";
+    let prdContent = "";
+
+    if (taskId) {
+      const contextBuilder = getContextBuilder();
+      try {
+        const context = await contextBuilder.buildContext(taskId);
+        if (context.documentation || context.stack || context.prdContent) {
+          contextInfo = "\n\nAvailable Context:\n";
+
+          if (context.stack) {
+            contextInfo += formatStackForContext(context.stack) + "\n";
+          }
+
+          if (context.documentation) {
+            contextInfo += `Documentation Available: ${context.documentation.recap}\n`;
+            if (context.documentation.files.length > 0) {
+              contextInfo += `Documentation Files: ${context.documentation.files
+                .map((f) => f.path)
+                .join(", ")}\n`;
+            }
+          }
+
+          if (context.prdContent) {
+            prdContent = context.prdContent;
+          }
+        }
+      } catch (error) {
+        throw error;
+      }
+    }
+
+    // Build prompt
+    let prompt: string;
+    if (promptOverride) {
+      prompt = promptOverride;
+    } else {
+      const promptResult = PromptBuilder.buildPrompt({
+        name: "task-enhancement",
+        type: "user",
+        variables: {
+          TASK_TITLE: title,
+          TASK_DESCRIPTION: description || "None",
+          CONTEXT_INFO: contextInfo,
+          PRD_CONTENT: prdContent || "No PRD content available",
+        },
+      });
+
+      if (!promptResult.success) {
+        throw createStandardError(
+          TaskOMaticErrorCodes.AI_OPERATION_FAILED,
+          `Failed to build task enhancement prompt: ${promptResult.error}`,
+          {
+            context: "Prompt building failed during task enhancement operation",
+            suggestions: [
+              "Verify prompt template exists",
+              "Check variable substitution",
+            ],
+          }
+        );
+      }
+
+      prompt = promptResult.prompt!;
+    }
+
+    // Execute AI operation with proper error handling
+    const result = await this.aiOperationUtility.executeAIOperation(
+      "Task enhancement",
+      async () => {
+        return await this.aiOperationUtility.streamText(
+          "",
+          config,
+          TASK_ENHANCEMENT_SYSTEM_PROMPT,
+          userMessage || prompt,
+          streamingOptions,
+          { maxAttempts: 1 }
+        );
+      },
+      {
+        streamingOptions,
+        retryConfig,
+        aiConfig: config,
+        maxRetries: retryConfig?.maxAttempts || 2,
+      }
+    );
+
+    // Return the result directly (errors are thrown, not returned)
+    return result.result;
+  }
+
+  async planTask(
+    taskContext: string,
+    taskDetails: string,
+    config?: Partial<AIConfig>,
+    promptOverride?: string,
+    userMessage?: string,
+    streamingOptions?: StreamingOptions,
+    retryConfig?: Partial<RetryConfig>
+  ): Promise<string> {
+    // Build prompt
+    let prompt: string;
+    if (promptOverride) {
+      prompt = promptOverride;
+    } else {
+      const promptResult = PromptBuilder.buildPrompt({
+        name: "task-planning",
+        type: "user",
+        variables: {
+          TASK_CONTEXT: taskContext,
+          TASK_DETAILS: taskDetails,
+        },
+      });
+
+      if (!promptResult.success) {
+        throw createStandardError(
+          TaskOMaticErrorCodes.AI_OPERATION_FAILED,
+          `Failed to build task planning prompt: ${promptResult.error}`,
+          {
+            context: "Prompt building failed during task planning operation",
+            suggestions: [
+              "Verify prompt template exists",
+              "Check variable substitution",
+            ],
+          }
+        );
+      }
+
+      prompt = promptResult.prompt!;
+    }
+
+    // Execute AI operation with proper error handling
+    const result = await this.aiOperationUtility.executeAIOperation(
+      "Task planning",
+      async () => {
+        const mcpTools = await this.context7Client.getMCPTools();
+        const allTools = {
+          ...(mcpTools as ToolSet),
+          ...filesystemTools,
+        };
+
+        return await this.aiOperationUtility.streamTextWithTools(
+          TASK_PLANNING_SYSTEM_PROMPT +
+            `
+
+You have access to filesystem tools that allow you to:
+- readFile: Read the contents of any file in the project
+- listDirectory: List contents of directories
+
+Use these tools to understand the project structure, existing code, and dependencies when creating implementation plans.`,
+          userMessage || prompt,
+          config,
+          streamingOptions,
+          allTools
+        );
+      },
+      {
+        streamingOptions,
+        retryConfig,
+        aiConfig: config,
+        maxRetries: retryConfig?.maxAttempts || 2,
+      }
+    );
+
+    // Return the result directly (errors are thrown, not returned)
+    return result.result;
+  }
+}