task-o-matic-core 0.1.0

package/dist/utils/ai-operation-utility.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIOperationUtility = void 0;
+const ai_1 = require("ai");
+const base_operations_1 = require("../lib/ai-service/base-operations");
+const task_o_matic_error_1 = require("./task-o-matic-error");
+/**
+ * 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);
+ * ```
+ */
+class AIOperationUtility extends base_operations_1.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(operationName, operation, options = {}) {
+        const startTime = Date.now();
+        let timeToFirstToken;
+        // 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 task_o_matic_error_1.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, userMessage, config, streamingOptions, tools) {
+        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) => {
+            // 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 (0, ai_1.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
+     */
+    wrapStreamingOptions(streamingOptions, startTime, onFirstToken) {
+        if (!streamingOptions) {
+            return undefined;
+        }
+        let firstTokenCaptured = false;
+        return {
+            ...streamingOptions,
+            onChunk: (chunk) => {
+                if (!firstTokenCaptured && chunk.trim()) {
+                    onFirstToken(Date.now() - startTime);
+                    firstTokenCaptured = true;
+                }
+                streamingOptions.onChunk?.(chunk);
+            },
+            onFinish: (result) => {
+                streamingOptions.onFinish?.(result);
+            },
+            onReasoning: (reasoning) => {
+                streamingOptions.onReasoning?.(reasoning);
+            },
+            onError: (error) => {
+                streamingOptions.onError?.(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
+     */
+    createStreamingConfig(streamingOptions) {
+        return {
+            onChunk: streamingOptions?.onChunk || streamingOptions?.onReasoning
+                ? (event) => {
+                    // 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) => {
+                    streamingOptions.onFinish({
+                        text: event.text,
+                        finishReason: event.finishReason,
+                        usage: event.usage,
+                        isAborted: false,
+                    });
+                }
+                : undefined,
+            onError: streamingOptions?.onError
+                ? (event) => {
+                    streamingOptions.onError(event.error);
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Extract token usage from AI result
+     *
+     * @private
+     */
+    extractTokenUsageFromResult(result) {
+        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
+     */
+    getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        else if (typeof error === "string") {
+            return error;
+        }
+        else {
+            return "Unknown error";
+        }
+    }
+}
+exports.AIOperationUtility = AIOperationUtility;

package/dist/utils/ai-service-factory.d.ts

@@ -0,0 +1,34 @@
+import { TaskRepository } from "../lib/storage/types";
+import { ContextBuilder, ContextCallbacks } from "../lib/context-builder";
+import { 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";
+export interface ServiceOptions {
+    storageCallbacks?: StorageCallbacks;
+    configCallbacks?: ConfigCallbacks;
+    contextCallbacks?: ContextCallbacks;
+    workingDirectory?: string;
+}
+/**
+ * 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 declare function initializeServices(options?: ServiceOptions): Promise<void>;
+export declare function getAIOperations(): AIOperations;
+export declare function getModelProvider(): ModelProvider;
+export declare function getStorage(): TaskRepository;
+export declare function getContextBuilder(): ContextBuilder;
+export declare function resetServiceInstances(): void;
+/**
+ * FOR TESTING ONLY: Inject mock instances
+ * This allows tests to provide mock implementations without complex module mocking
+ */
+export declare function injectTestInstances(instances: {
+    storage?: TaskRepository;
+    aiOperations?: AIOperations;
+    modelProvider?: ModelProvider;
+    contextBuilder?: ContextBuilder;
+}): void;
+//# sourceMappingURL=ai-service-factory.d.ts.map

package/dist/utils/ai-service-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-service-factory.d.ts","sourceRoot":"","sources":["../../src/utils/ai-service-factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAAiB,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAMpE,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAOD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,wBAAgB,eAAe,IAAI,YAAY,CAK9C;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAKhD;AAED,wBAAgB,UAAU,IAAI,cAAc,CAsB3C;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE;IAC7C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,GAAG,IAAI,CAKP"}

package/dist/utils/ai-service-factory.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeServices = initializeServices;
+exports.getAIOperations = getAIOperations;
+exports.getModelProvider = getModelProvider;
+exports.getStorage = getStorage;
+exports.getContextBuilder = getContextBuilder;
+exports.resetServiceInstances = resetServiceInstances;
+exports.injectTestInstances = injectTestInstances;
+const file_system_1 = require("../lib/storage/file-system");
+const context_builder_1 = require("../lib/context-builder");
+const fs_1 = require("fs");
+const config_1 = require("../lib/config");
+const ai_operations_1 = require("../lib/ai-service/ai-operations");
+const model_provider_1 = require("../lib/ai-service/model-provider");
+const task_o_matic_error_1 = require("./task-o-matic-error");
+let aiOperations = null;
+let modelProvider = null;
+let storage = null;
+let contextBuilder = 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.
+ */
+async function initializeServices(options = {}) {
+    if (options.workingDirectory) {
+        config_1.configManager.setWorkingDirectory(options.workingDirectory);
+    }
+    if (options.configCallbacks) {
+        config_1.configManager.setCallbacks(options.configCallbacks);
+    }
+    // Ensure config is loaded (async)
+    await config_1.configManager.load();
+    // Initialize storage
+    // If storageCallbacks provided, use them.
+    // If not, FileSystemStorage will use default callbacks (which use configManager.getTaskOMaticDir)
+    storage = new file_system_1.FileSystemStorage(options.storageCallbacks);
+    // Initialize context builder
+    contextBuilder = new context_builder_1.ContextBuilder(storage, options.contextCallbacks);
+    // Reset other services to ensure they use fresh dependencies if needed
+    aiOperations = null;
+    modelProvider = null;
+}
+function getAIOperations() {
+    if (!aiOperations) {
+        aiOperations = new ai_operations_1.AIOperations();
+    }
+    return aiOperations;
+}
+function getModelProvider() {
+    if (!modelProvider) {
+        modelProvider = new model_provider_1.ModelProvider();
+    }
+    return modelProvider;
+}
+function getStorage() {
+    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 = config_1.configManager.getTaskOMaticDir();
+        // Note: This check relies on FS. Web apps should call initializeServices first.
+        if (!(0, fs_1.existsSync)(taskOMaticDir)) {
+            throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.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 file_system_1.FileSystemStorage();
+    }
+    return storage;
+}
+function getContextBuilder() {
+    if (!contextBuilder) {
+        const storage = getStorage();
+        contextBuilder = new context_builder_1.ContextBuilder(storage);
+    }
+    return contextBuilder;
+}
+function resetServiceInstances() {
+    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
+ */
+function injectTestInstances(instances) {
+    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/dist/utils/error-utils.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 declare function getErrorMessage(error: unknown): string;
+/**
+ * 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 declare function formatError(error: unknown, context?: string): string;
+/**
+ * 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 declare function createContextError(error: unknown, context: string): import("./task-o-matic-error").TaskOMaticError;
+/**
+ * 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 declare function isError(error: unknown): error is 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 declare function toError(error: unknown): import("./task-o-matic-error").TaskOMaticError;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAkBtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,GACd,OAAO,sBAAsB,EAAE,eAAe,CAMhD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,OAAO,GACb,OAAO,sBAAsB,EAAE,eAAe,CAYhD"}

package/dist/utils/error-utils.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorMessage = getErrorMessage;
+exports.formatError = formatError;
+exports.createContextError = createContextError;
+exports.isError = isError;
+exports.toError = toError;
+const task_o_matic_error_1 = require("./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"
+ * }
+ * ```
+ */
+function getErrorMessage(error) {
+    // 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"
+ * }
+ * ```
+ */
+function formatError(error, context) {
+    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");
+ * }
+ * ```
+ */
+function createContextError(error, context) {
+    return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.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
+ */
+function isError(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
+ */
+function toError(error) {
+    if (error instanceof Error) {
+        return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, error.message, { cause: error });
+    }
+    return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, getErrorMessage(error));
+}