task-o-matic 0.0.14 → 0.0.15

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

@@ -0,0 +1,288 @@
+"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}`, {
+                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);
+        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,
+                            },
+                        },
+                    },
+                }
+                : {}),
+        });
+        return await result.text;
+    }
+    /**
+     * 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)
+                    if (event.chunk?.type === "tool-result" &&
+                        event.chunk?.toolName === "get-library-docs") {
+                        const docs = event.chunk.output;
+                        if (docs && typeof docs === "object" && "content" in docs) {
+                            this.context7Client.saveContext7Documentation(event.chunk.input?.context7CompatibleLibraryID || "unknown", docs.content, event.chunk.input?.topic || "general");
+                        }
+                        else if (docs && typeof docs === "string") {
+                            this.context7Client.saveContext7Documentation(event.chunk.input?.context7CompatibleLibraryID || "unknown", docs, event.chunk.input?.topic || "general");
+                        }
+                    }
+                    // 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

@@ -21,4 +21,14 @@ 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

@@ -1 +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;AAEpE,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,CAkB3C;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAMlD;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C"}
+{"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

@@ -6,12 +6,14 @@ 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;
@@ -60,7 +62,9 @@ function getStorage() {
         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 new Error(`Not a task-o-matic project. Run 'task-o-matic init' first.`);
+            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();
     }
@@ -79,3 +83,17 @@ function resetServiceInstances() {
     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/cli-validators.d.ts

@@ -6,7 +6,7 @@
  * @param field2 - Second field name in options
  * @param field1Label - Display label for first field (defaults to field1)
  * @param field2Label - Display label for second field (defaults to field2)
- * @throws Error if neither or both fields are provided
+ * @throws TaskOMaticError if neither or both fields are provided
  *
  * @example
  * ```typescript
@@ -26,7 +26,7 @@ export interface FieldSpec {
  *
  * @param options - The command options object
  * @param fields - Array of field specifications
- * @throws Error if none or multiple fields are provided
+ * @throws TaskOMaticError if none or multiple fields are provided
  *
  * @example
  * ```typescript

package/dist/utils/cli-validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-validators.d.ts","sourceRoot":"","sources":["../../src/utils/cli-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAe,EAC5B,WAAW,GAAE,MAAe,GAC3B,IAAI,CAcN;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,GAAG,EACZ,GAAG,MAAM,EAAE,SAAS,EAAE,GACrB,IAAI,CAWN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD"}
+{"version":3,"file":"cli-validators.d.ts","sourceRoot":"","sources":["../../src/utils/cli-validators.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAe,EAC5B,WAAW,GAAE,MAAe,GAC3B,IAAI,CAgBN;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,GAAG,EACZ,GAAG,MAAM,EAAE,SAAS,EAAE,GACrB,IAAI,CAiBN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD"}

package/dist/utils/cli-validators.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateMutuallyExclusive = validateMutuallyExclusive;
 exports.validateOneRequired = validateOneRequired;
 exports.parseCsvOption = parseCsvOption;
+const task_o_matic_error_1 = require("./task-o-matic-error");
 /**
  * Validate that exactly one of two mutually exclusive options is provided
  *
@@ -11,7 +12,7 @@ exports.parseCsvOption = parseCsvOption;
  * @param field2 - Second field name in options
  * @param field1Label - Display label for first field (defaults to field1)
  * @param field2Label - Display label for second field (defaults to field2)
- * @throws Error if neither or both fields are provided
+ * @throws TaskOMaticError if neither or both fields are provided
  *
  * @example
  * ```typescript
@@ -22,10 +23,10 @@ function validateMutuallyExclusive(options, field1, field2, field1Label = field1
     const has1 = Boolean(options[field1]);
     const has2 = Boolean(options[field2]);
     if (!has1 && !has2) {
-        throw new Error(`Either --${field1Label} or --${field2Label} must be specified`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Either --${field1Label} or --${field2Label} must be specified`);
     }
     if (has1 && has2) {
-        throw new Error(`Cannot specify both --${field1Label} and --${field2Label}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Cannot specify both --${field1Label} and --${field2Label}`);
     }
 }
 /**
@@ -33,7 +34,7 @@ function validateMutuallyExclusive(options, field1, field2, field1Label = field1
  *
  * @param options - The command options object
  * @param fields - Array of field specifications
- * @throws Error if none or multiple fields are provided
+ * @throws TaskOMaticError if none or multiple fields are provided
  *
  * @example
  * ```typescript
@@ -48,11 +49,11 @@ function validateOneRequired(options, ...fields) {
     const provided = fields.filter((f) => Boolean(options[f.name]));
     if (provided.length === 0) {
         const labels = fields.map((f) => `--${f.label}`).join(", ");
-        throw new Error(`One of ${labels} must be specified`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `One of ${labels} must be specified`);
     }
     if (provided.length > 1) {
         const labels = provided.map((f) => `--${f.label}`).join(", ");
-        throw new Error(`Cannot specify multiple options: ${labels}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, `Cannot specify multiple options: ${labels}`);
     }
 }
 /**

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

@@ -39,7 +39,7 @@ export declare function formatError(error: unknown, context?: string): string;
  *
  * @param error - The original error
  * @param context - Context to add to the error
- * @returns A new Error instance with formatted message
+ * @returns A new TaskOMaticError instance with formatted message
  *
  * @example
  * ```typescript
@@ -50,7 +50,7 @@ export declare function formatError(error: unknown, context?: string): string;
  * }
  * ```
  */
-export declare function createContextError(error: unknown, context: string): Error;
+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.
  *
@@ -66,5 +66,5 @@ export declare function isError(error: unknown): error is Error;
  * @param error - Value to convert
  * @returns An Error instance
  */
-export declare function toError(error: unknown): Error;
+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

@@ -1 +1 @@
-{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;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,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAK7C"}
+{"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

@@ -5,6 +5,7 @@ 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.
@@ -64,7 +65,7 @@ function formatError(error, context) {
  *
  * @param error - The original error
  * @param context - Context to add to the error
- * @returns A new Error instance with formatted message
+ * @returns A new TaskOMaticError instance with formatted message
  *
  * @example
  * ```typescript
@@ -76,7 +77,7 @@ function formatError(error, context) {
  * ```
  */
 function createContextError(error, context) {
-    return new Error(formatError(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.
@@ -97,7 +98,7 @@ function isError(error) {
  */
 function toError(error) {
     if (error instanceof Error) {
-        return error;
+        return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, error.message, { cause: error });
     }
-    return new Error(getErrorMessage(error));
+    return (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, getErrorMessage(error));
 }

package/dist/utils/file-utils.d.ts

@@ -4,12 +4,12 @@
  *
  * @param filePath - Path to the file to validate
  * @param customMessage - Optional custom error message
- * @throws Error if file doesn't exist
+ * @throws TaskOMaticError if file doesn't exist
  *
  * @example
  * ```typescript
  * validateFileExists("./config.json", "Configuration file not found");
- * // Throws: Error("Configuration file not found") if file doesn't exist
+ * // Throws: TaskOMaticError with code INVALID_INPUT if file doesn't exist
  * ```
  */
 export declare function validateFileExists(filePath: string, customMessage?: string): void;
@@ -19,12 +19,12 @@ export declare function validateFileExists(filePath: string, customMessage?: str
  *
  * @param filePath - Path to the file to validate
  * @param customMessage - Optional custom error message
- * @throws Error if file doesn't exist
+ * @throws TaskOMaticError if file doesn't exist
  *
  * @example
  * ```typescript
  * await validateFileExistsAsync("./data.json");
- * // Throws: Error("File not found: ./data.json") if file doesn't exist
+ * // Throws: TaskOMaticError with code INVALID_INPUT if file doesn't exist
  * ```
  */
 export declare function validateFileExistsAsync(filePath: string, customMessage?: string): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAIN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE"}
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAUN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE"}

package/dist/utils/file-utils.js

@@ -6,23 +6,26 @@ exports.fileExists = fileExists;
 exports.fileExistsAsync = fileExistsAsync;
 const fs_1 = require("fs");
 const promises_1 = require("fs/promises");
+const task_o_matic_error_1 = require("./task-o-matic-error");
 /**
  * Validates that a file exists at the given path (synchronous).
  * Throws an error with a custom message if the file doesn't exist.
  *
  * @param filePath - Path to the file to validate
  * @param customMessage - Optional custom error message
- * @throws Error if file doesn't exist
+ * @throws TaskOMaticError if file doesn't exist
  *
  * @example
  * ```typescript
  * validateFileExists("./config.json", "Configuration file not found");
- * // Throws: Error("Configuration file not found") if file doesn't exist
+ * // Throws: TaskOMaticError with code INVALID_INPUT if file doesn't exist
  * ```
  */
 function validateFileExists(filePath, customMessage) {
     if (!(0, fs_1.existsSync)(filePath)) {
-        throw new Error(customMessage || `File not found: ${filePath}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, customMessage || `File not found: ${filePath}`, {
+            suggestions: ["Verify the file path is correct."],
+        });
     }
 }
 /**
@@ -31,12 +34,12 @@ function validateFileExists(filePath, customMessage) {
  *
  * @param filePath - Path to the file to validate
  * @param customMessage - Optional custom error message
- * @throws Error if file doesn't exist
+ * @throws TaskOMaticError if file doesn't exist
  *
  * @example
  * ```typescript
  * await validateFileExistsAsync("./data.json");
- * // Throws: Error("File not found: ./data.json") if file doesn't exist
+ * // Throws: TaskOMaticError with code INVALID_INPUT if file doesn't exist
  * ```
  */
 async function validateFileExistsAsync(filePath, customMessage) {
@@ -44,7 +47,9 @@ async function validateFileExistsAsync(filePath, customMessage) {
         await (0, promises_1.access)(filePath, promises_1.constants.F_OK);
     }
     catch {
-        throw new Error(customMessage || `File not found: ${filePath}`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.INVALID_INPUT, customMessage || `File not found: ${filePath}`, {
+            suggestions: ["Verify the file path is correct."],
+        });
     }
 }
 /**

package/dist/utils/id-generator.d.ts

@@ -54,7 +54,7 @@ export declare class TaskIDGenerator {
      * @param prefix - Prefix for the ID
      * @param maxAttempts - Maximum number of generation attempts
      * @returns Unique task ID
-     * @throws Error if unable to generate unique ID after maxAttempts
+     * @throws TaskOMaticError if unable to generate unique ID after maxAttempts
      */
     static generateUnique(existingIds: Set<string>, prefix?: string, maxAttempts?: number): string;
     /**

package/dist/utils/id-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAE,MAAe,GAAG,MAAM;IAMhD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA0BpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO;IAI9D;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAc,CACnB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,GAAE,MAAe,EACvB,WAAW,GAAE,MAAW,GACvB,MAAM;IAaT;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,mBAAmB,CACxB,EAAE,EAAE,MAAM,GACT;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAcnD"}
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAE,MAAe,GAAG,MAAM;IAMhD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA0BpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO;IAI9D;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAc,CACnB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,GAAE,MAAe,EACvB,WAAW,GAAE,MAAW,GACvB,MAAM;IAoBT;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,mBAAmB,CACxB,EAAE,EAAE,MAAM,GACT;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAcnD"}

package/dist/utils/id-generator.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TaskIDGenerator = void 0;
 const crypto_1 = require("crypto");
+const task_o_matic_error_1 = require("./task-o-matic-error");
 /**
  * Generates unique task IDs with consistent format.
  * Uses timestamp + random hex for uniqueness.
@@ -84,7 +85,7 @@ class TaskIDGenerator {
      * @param prefix - Prefix for the ID
      * @param maxAttempts - Maximum number of generation attempts
      * @returns Unique task ID
-     * @throws Error if unable to generate unique ID after maxAttempts
+     * @throws TaskOMaticError if unable to generate unique ID after maxAttempts
      */
     static generateUnique(existingIds, prefix = "task", maxAttempts = 10) {
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
@@ -93,7 +94,12 @@ class TaskIDGenerator {
                 return id;
             }
         }
-        throw new Error(`Failed to generate unique ID after ${maxAttempts} attempts`);
+        throw (0, task_o_matic_error_1.createStandardError)(task_o_matic_error_1.TaskOMaticErrorCodes.UNEXPECTED_ERROR, `Failed to generate unique ID after ${maxAttempts} attempts`, {
+            context: `Could not find a unique ID with prefix '${prefix}' after ${maxAttempts} attempts.`,
+            suggestions: [
+                "Increase maxAttempts if you have a very large number of tasks.",
+            ],
+        });
     }
     /**
      * Generates a hierarchical child ID from a parent ID.

package/dist/utils/model-executor-parser.d.ts

@@ -12,7 +12,7 @@ export declare const VALID_EXECUTORS: ExecutorTool[];
  *
  * @param value - Comma-separated model/executor specifications
  * @returns Array of model attempt configurations
- * @throws Error if an invalid executor is specified
+ * @throws TaskOMaticError if an invalid executor is specified
  *
  * @example
  * ```typescript

package/dist/utils/model-executor-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-executor-parser.d.ts","sourceRoot":"","sources":["../../src/utils/model-executor-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,YAAY,EAKzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA2BlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,YAAY,CAE3E"}
+{"version":3,"file":"model-executor-parser.d.ts","sourceRoot":"","sources":["../../src/utils/model-executor-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAM5D;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,YAAY,EAKzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA4BlE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,YAAY,CAE3E"}