task-o-matic-core 0.1.0

package/src/utils/ai-operation-utility.ts

@@ -0,0 +1,380 @@
+import { streamText } from "ai";
+import type { ToolSet } from "ai";
+import { AIConfig, StreamingOptions, RetryConfig } from "../types";
+import { BaseOperations } from "../lib/ai-service/base-operations";
+import { TaskOMaticError } from "./task-o-matic-error";
+
+export interface AIOperationResult<T> {
+  result: T;
+  metrics: {
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number;
+  };
+}
+
+export interface AIOperationOptions {
+  streamingOptions?: StreamingOptions;
+  retryConfig?: Partial<RetryConfig>;
+  aiConfig?: Partial<AIConfig>;
+  enableFilesystemTools?: boolean;
+  context?: Record<string, unknown>;
+  maxRetries?: number;
+}
+
+/**
+ * AIOperationUtility - Centralized utility for AI operations with metrics and error handling
+ *
+ * Extends BaseOperations to inherit core AI functionality (streamText, model provider, etc.)
+ * and adds standardized metrics collection, error handling, and retry logic.
+ *
+ * @example
+ * ```typescript
+ * const utility = new AIOperationUtility();
+ *
+ * // Execute operation with metrics
+ * const result = await utility.executeAIOperation(
+ *   "Task breakdown",
+ *   async () => performBreakdown(task),
+ *   {
+ *     maxRetries: 3,
+ *     streamingOptions: { onChunk: console.log }
+ *   }
+ * );
+ *
+ * console.log(result.metrics.duration);
+ * console.log(result.metrics.timeToFirstToken);
+ * ```
+ */
+export class AIOperationUtility extends BaseOperations {
+  /**
+   * Execute an AI operation with standardized metrics, error handling, and streaming support
+   *
+   * This method wraps AI operations to provide:
+   * - Automatic retry logic with configurable attempts
+   * - Metrics collection (duration, token usage, time to first token)
+   * - Error handling with TaskOMaticError wrapping
+   * - Streaming support with metrics capture
+   *
+   * @param operationName - Human-readable name for the operation (used in errors)
+   * @param operation - The async operation to execute
+   * @param options - Configuration options for retry, streaming, and AI config
+   * @returns Promise resolving to AIOperationResult with result and metrics
+   * @throws {TaskOMaticError} If operation fails after all retry attempts
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const result = await utility.executeAIOperation(
+   *     "Task enhancement",
+   *     async () => enhanceTask(task),
+   *     { maxRetries: 2 }
+   *   );
+   *   console.log(`Operation took ${result.metrics.duration}ms`);
+   * } catch (error) {
+   *   if (error instanceof TaskOMaticError) {
+   *     console.error(error.getDetails());
+   *   }
+   * }
+   * ```
+   */
+  async executeAIOperation<T>(
+    operationName: string,
+    operation: () => Promise<T>,
+    options: AIOperationOptions = {}
+  ): Promise<AIOperationResult<T>> {
+    const startTime = Date.now();
+    let timeToFirstToken: number | undefined;
+
+    // Create wrapped streaming options to capture metrics
+    const wrappedStreamingOptions = this.wrapStreamingOptions(
+      options.streamingOptions,
+      startTime,
+      (time) => {
+        timeToFirstToken = time;
+      }
+    );
+
+    try {
+      // Execute with retry logic
+      const result = await this.retryHandler.executeWithRetry(
+        async () => {
+          // Execute operation - note: operations should use the streaming options
+          // passed through the closure, not directly from options
+          return await operation();
+        },
+        {
+          maxAttempts:
+            options.maxRetries || options.retryConfig?.maxAttempts || 2,
+          ...options.retryConfig,
+        },
+        operationName
+      );
+
+      const duration = Date.now() - startTime;
+
+      return {
+        result,
+        metrics: {
+          duration,
+          timeToFirstToken,
+          tokenUsage: this.extractTokenUsageFromResult(result),
+        },
+      };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const typedError =
+        error instanceof Error ? error : new Error(String(error));
+
+      // THROW error instead of returning it
+      throw new TaskOMaticError(
+        `AI operation failed: ${operationName} - ${this.getErrorMessage(
+          typedError
+        )}`,
+        {
+          code: "AI_OPERATION_FAILED",
+          context: JSON.stringify({
+            operation: operationName,
+            duration,
+            error: this.getErrorMessage(typedError),
+          }),
+          cause: typedError,
+          suggestions: [
+            "Check AI configuration",
+            "Verify network connectivity",
+            "Review operation parameters",
+            "Check API keys and endpoints",
+          ],
+          metadata: {
+            operationName,
+            duration,
+            attemptedRetries: options.maxRetries || 2,
+          },
+        }
+      );
+    }
+  }
+
+  /**
+   * Standardized streaming text operation with tool support
+   *
+   * This method provides a unified interface for AI text generation with:
+   * - Optional tool integration (filesystem, MCP, etc.)
+   * - Streaming support with callbacks
+   * - Context7 documentation caching
+   * - Metrics collection
+   * - Error handling
+   *
+   * @param systemPrompt - System prompt for the AI
+   * @param userMessage - User message/prompt
+   * @param config - Optional AI configuration overrides
+   * @param streamingOptions - Optional streaming callbacks
+   * @param tools - Optional tool set to provide to the AI
+   * @returns Promise resolving to the generated text
+   *
+   * @example
+   * ```typescript
+   * const result = await utility.streamTextWithTools(
+   *   "You are a helpful assistant",
+   *   "Explain quantum computing",
+   *   undefined,
+   *   { onChunk: (chunk) => console.log(chunk) },
+   *   filesystemTools
+   * );
+   * ```
+   */
+  async streamTextWithTools(
+    systemPrompt: string,
+    userMessage: string,
+    config?: Partial<AIConfig>,
+    streamingOptions?: StreamingOptions,
+    tools?: ToolSet
+  ): Promise<string> {
+    const aiConfig = this.mergeAIConfig(config);
+    const model = this.modelProvider.getModel(aiConfig);
+
+    // Create streaming configuration with Context7 handling and callbacks
+    const streamConfig = this.createStreamingConfig(streamingOptions);
+
+    let accumulatedText = "";
+    const originalOnChunk = streamConfig.onChunk;
+
+    // Wrap onChunk to accumulate text locally
+    streamConfig.onChunk = (event: any) => {
+      // Debug log for chunk structure
+      // console.log(
+      //   `[DEBUG] Chunk type: ${event.chunk?.type} | keys: ${Object.keys(
+      //     event.chunk || {}
+      //   ).join(",")}`
+      // );
+
+      if (
+        event.chunk?.type === "text-delta" &&
+        typeof event.chunk.text === "string"
+      ) {
+        accumulatedText += event.chunk.text;
+        // } else {
+        // console.log(
+        //   `[DEBUG] Ignored chunk content:`,
+        //   JSON.stringify(event.chunk)
+        // );
+      }
+
+      if (originalOnChunk) {
+        originalOnChunk(event);
+      }
+    };
+
+    const result = await streamText({
+      model,
+      tools: tools || {},
+      system: systemPrompt,
+      messages: [{ role: "user", content: userMessage }],
+      maxRetries: 0,
+      ...streamConfig,
+      ...(aiConfig.provider === "openrouter" &&
+      aiConfig.reasoning &&
+      aiConfig.reasoning.maxTokens
+        ? {
+            providerOptions: {
+              openrouter: {
+                reasoning: {
+                  max_tokens: aiConfig.reasoning.maxTokens,
+                },
+              },
+            },
+          }
+        : {}),
+    });
+
+    const fullText = await result.text;
+    return fullText || accumulatedText;
+  }
+
+  /**
+   * Wrap streaming options to capture metrics
+   *
+   * @private
+   */
+  private wrapStreamingOptions(
+    streamingOptions: StreamingOptions | undefined,
+    startTime: number,
+    onFirstToken: (time: number) => void
+  ): StreamingOptions | undefined {
+    if (!streamingOptions) {
+      return undefined;
+    }
+
+    let firstTokenCaptured = false;
+
+    return {
+      ...streamingOptions,
+      onChunk: (chunk: string) => {
+        if (!firstTokenCaptured && chunk.trim()) {
+          onFirstToken(Date.now() - startTime);
+          firstTokenCaptured = true;
+        }
+        streamingOptions.onChunk?.(chunk);
+      },
+      onFinish: (result: any) => {
+        streamingOptions.onFinish?.(result);
+      },
+      onReasoning: (reasoning: string) => {
+        streamingOptions.onReasoning?.(reasoning);
+      },
+      onError: (error: unknown) => {
+        streamingOptions.onError?.(error as Error);
+      },
+    };
+  }
+
+  /**
+   * Create streaming configuration with Context7 handling and callbacks
+   *
+   * This method creates a unified streaming configuration that:
+   * - Always handles Context7 tool-result events (even without streaming UI)
+   * - Forwards text-delta events to onChunk callback
+   * - Forwards reasoning-delta events to onReasoning callback
+   * - Handles errors with onError callback
+   * - Provides onFinish callback with completion data
+   *
+   * @private
+   */
+  private createStreamingConfig(streamingOptions?: StreamingOptions) {
+    return {
+      onChunk:
+        streamingOptions?.onChunk || streamingOptions?.onReasoning
+          ? (event: any) => {
+              // Handle Context7 tool results ALWAYS (critical for caching)
+              this.handleContext7ToolResult(event.chunk);
+
+              // Forward text deltas to user callback
+              if (event.chunk?.type === "text-delta") {
+                streamingOptions?.onChunk?.(event.chunk.text);
+              }
+
+              // Forward reasoning deltas to user callback
+              if (event.chunk?.type === "reasoning-delta") {
+                streamingOptions?.onReasoning?.(event.chunk.text);
+              }
+            }
+          : undefined,
+      onFinish: streamingOptions?.onFinish
+        ? (event: any) => {
+            streamingOptions.onFinish!({
+              text: event.text,
+              finishReason: event.finishReason,
+              usage: event.usage,
+              isAborted: false,
+            });
+          }
+        : undefined,
+      onError: streamingOptions?.onError
+        ? (event: any) => {
+            streamingOptions.onError!(event.error);
+          }
+        : undefined,
+    };
+  }
+
+  /**
+   * Extract token usage from AI result
+   *
+   * @private
+   */
+  private extractTokenUsageFromResult(result: any):
+    | {
+        prompt: number;
+        completion: number;
+        total: number;
+      }
+    | undefined {
+    if (result && result.usage) {
+      return {
+        prompt: result.usage.prompt_tokens || 0,
+        completion: result.usage.completion_tokens || 0,
+        total: result.usage.total_tokens || 0,
+      };
+    }
+    return undefined;
+  }
+
+  /**
+   * Get error message from any error type
+   *
+   * @private
+   */
+  private getErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    } else if (typeof error === "string") {
+      return error;
+    } else {
+      return "Unknown error";
+    }
+  }
+}

package/src/utils/ai-service-factory.ts

@@ -0,0 +1,125 @@
+import { FileSystemStorage } from "../lib/storage/file-system";
+import { TaskRepository } from "../lib/storage/types";
+import { ContextBuilder, ContextCallbacks } from "../lib/context-builder";
+import { existsSync } from "fs";
+import { configManager, ConfigCallbacks } from "../lib/config";
+import { AIOperations } from "../lib/ai-service/ai-operations";
+import { ModelProvider } from "../lib/ai-service/model-provider";
+import { StorageCallbacks } from "../lib/storage/storage-callbacks";
+import {
+  createStandardError,
+  TaskOMaticErrorCodes,
+} from "./task-o-matic-error";
+
+export interface ServiceOptions {
+  storageCallbacks?: StorageCallbacks;
+  configCallbacks?: ConfigCallbacks;
+  contextCallbacks?: ContextCallbacks;
+  workingDirectory?: string;
+}
+
+let aiOperations: AIOperations | null = null;
+let modelProvider: ModelProvider | null = null;
+let storage: TaskRepository | null = null;
+let contextBuilder: ContextBuilder | null = null;
+
+/**
+ * Initialize services with optional custom callbacks.
+ * This is the entry point for web applications or custom environments.
+ * It also ensures configuration is loaded asynchronously.
+ */
+export async function initializeServices(
+  options: ServiceOptions = {}
+): Promise<void> {
+  if (options.workingDirectory) {
+    configManager.setWorkingDirectory(options.workingDirectory);
+  }
+
+  if (options.configCallbacks) {
+    configManager.setCallbacks(options.configCallbacks);
+  }
+
+  // Ensure config is loaded (async)
+  await configManager.load();
+
+  // Initialize storage
+  // If storageCallbacks provided, use them.
+  // If not, FileSystemStorage will use default callbacks (which use configManager.getTaskOMaticDir)
+  storage = new FileSystemStorage(options.storageCallbacks);
+
+  // Initialize context builder
+  contextBuilder = new ContextBuilder(storage, options.contextCallbacks);
+
+  // Reset other services to ensure they use fresh dependencies if needed
+  aiOperations = null;
+  modelProvider = null;
+}
+
+export function getAIOperations(): AIOperations {
+  if (!aiOperations) {
+    aiOperations = new AIOperations();
+  }
+  return aiOperations;
+}
+
+export function getModelProvider(): ModelProvider {
+  if (!modelProvider) {
+    modelProvider = new ModelProvider();
+  }
+  return modelProvider;
+}
+
+export function getStorage(): TaskRepository {
+  if (!storage) {
+    // Default behavior for CLI (if initializeServices wasn't called)
+
+    // Ensure we're in a task-o-matic project before creating storage
+    // We use configManager (sync path) to check existence.
+    const taskOMaticDir = configManager.getTaskOMaticDir();
+
+    // Note: This check relies on FS. Web apps should call initializeServices first.
+    if (!existsSync(taskOMaticDir)) {
+      throw createStandardError(
+        TaskOMaticErrorCodes.CONFIGURATION_ERROR,
+        "Not a task-o-matic project. Run 'task-o-matic init' first.",
+        {
+          suggestions: ["Run `task-o-matic init` in your project root."],
+        }
+      );
+    }
+
+    storage = new FileSystemStorage();
+  }
+  return storage;
+}
+
+export function getContextBuilder(): ContextBuilder {
+  if (!contextBuilder) {
+    const storage = getStorage();
+    contextBuilder = new ContextBuilder(storage);
+  }
+  return contextBuilder;
+}
+
+export function resetServiceInstances(): void {
+  aiOperations = null;
+  modelProvider = null;
+  storage = null;
+  contextBuilder = null;
+}
+
+/**
+ * FOR TESTING ONLY: Inject mock instances
+ * This allows tests to provide mock implementations without complex module mocking
+ */
+export function injectTestInstances(instances: {
+  storage?: TaskRepository;
+  aiOperations?: AIOperations;
+  modelProvider?: ModelProvider;
+  contextBuilder?: ContextBuilder;
+}): void {
+  if (instances.storage) storage = instances.storage;
+  if (instances.aiOperations) aiOperations = instances.aiOperations;
+  if (instances.modelProvider) modelProvider = instances.modelProvider;
+  if (instances.contextBuilder) contextBuilder = instances.contextBuilder;
+}

package/src/utils/error-utils.ts

@@ -0,0 +1,124 @@
+import {
+  createStandardError,
+  TaskOMaticErrorCodes,
+} from "./task-o-matic-error";
+
+/**
+ * Extracts a readable error message from an unknown error value.
+ * Handles Error objects, strings, objects with message property, and unknown types.
+ *
+ * @param error - The error value to extract message from
+ * @returns A string error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   throw new Error("Something went wrong");
+ * } catch (error) {
+ *   console.log(getErrorMessage(error)); // "Something went wrong"
+ * }
+ * ```
+ */
+export function getErrorMessage(error: unknown): string {
+  // Error instance
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  // String error
+  if (typeof error === "string") {
+    return error;
+  }
+
+  // Object with message property
+  if (error && typeof error === "object" && "message" in error) {
+    return String(error.message);
+  }
+
+  // Unknown type - convert to string
+  return "Unknown error occurred";
+}
+
+/**
+ * Formats an error with optional context information.
+ * Useful for adding context to error messages when rethrowing.
+ *
+ * @param error - The error value
+ * @param context - Optional context string to prepend to the error message
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetchData();
+ * } catch (error) {
+ *   throw new Error(formatError(error, "Failed to fetch data"));
+ *   // Result: "Failed to fetch data: Connection timeout"
+ * }
+ * ```
+ */
+export function formatError(error: unknown, context?: string): string {
+  const message = getErrorMessage(error);
+  return context ? `${context}: ${message}` : message;
+}
+
+/**
+ * Creates an error with a formatted message including context.
+ *
+ * @param error - The original error
+ * @param context - Context to add to the error
+ * @returns A new TaskOMaticError instance with formatted message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await operation();
+ * } catch (error) {
+ *   throw createContextError(error, "Operation failed");
+ * }
+ * ```
+ */
+export function createContextError(
+  error: unknown,
+  context: string
+): import("./task-o-matic-error").TaskOMaticError {
+  return createStandardError(
+    TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+    formatError(error, context),
+    { cause: error instanceof Error ? error : undefined }
+  );
+}
+
+/**
+ * Type guard to check if an error is an Error instance.
+ *
+ * @param error - Value to check
+ * @returns true if error is an Error instance
+ */
+export function isError(error: unknown): error is Error {
+  return error instanceof Error;
+}
+
+/**
+ * Safely converts any value to an Error instance.
+ * If the value is already an Error, returns it unchanged.
+ * Otherwise, creates a new Error with the string representation.
+ *
+ * @param error - Value to convert
+ * @returns An Error instance
+ */
+export function toError(
+  error: unknown
+): import("./task-o-matic-error").TaskOMaticError {
+  if (error instanceof Error) {
+    return createStandardError(
+      TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+      error.message,
+      { cause: error }
+    );
+  }
+  return createStandardError(
+    TaskOMaticErrorCodes.UNEXPECTED_ERROR,
+    getErrorMessage(error)
+  );
+}