ros/claude-task-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(refactor): Finalize AI service migration and cleanup obsolete files

Browse Source 
This commit completes the major refactoring initiative (Task 61) to migrate all AI-interacting task management functions to the unified service layer (`ai-services-unified.js`) and standardized configuration (`config-manager.js`).

Key Changes:

1.  **Refactor `update-task-by-id` & `update-subtask-by-id`:**

    *   Replaced direct AI client logic and config fetching with calls to `generateTextService`.

    *   Preserved original prompt logic while ensuring JSON output format is requested.

    *   Implemented robust manual JSON parsing and Zod validation for text-based AI responses.

    *   Corrected logger implementation (`logFn`/`isMCP`/`report` pattern) for both CLI and MCP contexts.

    *   Ensured correct passing of `session` context to the unified service.

    *   Refactored associated direct function wrappers (`updateTaskByIdDirect`, `updateSubtaskByIdDirect`) to remove AI client initialization and call core logic appropriately.

2.  **CLI Environment Loading:**

    *   Added `dotenv.config()` to `scripts/dev.js` to ensure consistent loading of the `.env` file for CLI operations.

3.  **Obsolete Code Removal:**

    *   Deleted unused helper files:

        *   `scripts/modules/task-manager/get-subtasks-from-ai.js`

        *   `scripts/modules/task-manager/generate-subtask-prompt.js`

        *   `scripts/modules/ai-services.js`

        *   `scripts/modules/ai-client-factory.js`

        *   `mcp-server/src/core/utils/ai-client-utils.js`

    *   Removed corresponding imports/exports from `scripts/modules/task-manager.js` and `mcp-server/src/core/task-master-core.js`.

4.  **Verification:**

    *   Successfully tested `update-task` and `update-subtask` via both CLI and MCP after refactoring.

5.  **Task Management:**

    *   Marked subtasks 61.38, 61.39, 61.40, 61.41, and 61.33 as 'done'.

    *   Includes other task content/status updates as reflected in the diff.

This completes the migration of core AI features to the new architecture, enhancing maintainability and flexibility.
This commit is contained in:
Eyal Toledano
2025-04-25 13:24:15 -04:00
parent 60363be0fe
commit 7c8d464b82
17 changed files with 496 additions and 6375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

348
scripts/modules/ai-client-factory.js
View File

@@ -1,348 +0,0 @@
import fs from 'fs';
import path from 'path';
import { createOpenAI } from '@ai-sdk/openai';
import { createAnthropic } from '@ai-sdk/anthropic';
import { createGoogle } from '@ai-sdk/google';
import { createPerplexity } from '@ai-sdk/perplexity';
import { createOllama } from 'ollama-ai-provider';
import { createMistral } from '@ai-sdk/mistral';
import { createAzure } from '@ai-sdk/azure';
import { createXai } from '@ai-sdk/xai';
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
// TODO: Add imports for other supported providers like OpenRouter, Grok
import {
getProviderAndModelForRole,
findProjectRoot // Assuming config-manager exports this
} from './config-manager.js';
const clientCache = new Map();
// Using a Symbol for a unique, unmistakable value
const VALIDATION_SKIPPED = Symbol('validation_skipped');
// --- Load Supported Models Data (Lazily) ---
let supportedModelsData = null;
let modelsDataLoaded = false;
function loadSupportedModelsData() {
console.log(
`DEBUG: loadSupportedModelsData called. modelsDataLoaded=${modelsDataLoaded}`
);
if (modelsDataLoaded) {
console.log('DEBUG: Returning cached supported models data.');
return supportedModelsData;
}
try {
const projectRoot = findProjectRoot(process.cwd());
const supportedModelsPath = path.join(
projectRoot,
'data',
'supported-models.json'
);
console.log(
`DEBUG: Checking for supported models at: ${supportedModelsPath}`
);
const exists = fs.existsSync(supportedModelsPath);
console.log(`DEBUG: fs.existsSync result: ${exists}`);
if (exists) {
const fileContent = fs.readFileSync(supportedModelsPath, 'utf-8');
supportedModelsData = JSON.parse(fileContent);
console.log(
'DEBUG: Successfully loaded and parsed supported-models.json'
);
} else {
console.warn(
`Warning: Could not find supported models file at ${supportedModelsPath}. Skipping model validation.`
);
supportedModelsData = {}; // Treat as empty if not found, allowing skip
}
} catch (error) {
console.error(
`Error loading or parsing supported models file: ${error.message}`
);
console.error('Stack Trace:', error.stack);
supportedModelsData = {}; // Treat as empty on error, allowing skip
}
modelsDataLoaded = true;
console.log(
`DEBUG: Setting modelsDataLoaded=true, returning: ${JSON.stringify(supportedModelsData)}`
);
return supportedModelsData;
}
/**
* Validates if a model is supported for a given provider and role.
* @param {string} providerName - The name of the provider.
* @param {string} modelId - The ID of the model.
* @param {string} role - The role ('main', 'research', 'fallback').
* @returns {boolean|Symbol} True if valid, false if invalid, VALIDATION_SKIPPED if data was missing.
*/
function isModelSupportedAndAllowed(providerName, modelId, role) {
const modelsData = loadSupportedModelsData();
if (
!modelsData ||
typeof modelsData !== 'object' ||
Object.keys(modelsData).length === 0
) {
console.warn(
'Skipping model validation as supported models data is unavailable or invalid.'
);
// Return the specific symbol instead of true
return VALIDATION_SKIPPED;
}
// Ensure consistent casing for provider lookup
const providerKey = providerName?.toLowerCase();
if (!providerKey || !modelsData.hasOwnProperty(providerKey)) {
console.warn(
`Provider '${providerName}' not found in supported-models.json.`
);
return false;
}
const providerModels = modelsData[providerKey];
if (!Array.isArray(providerModels)) {
console.warn(
`Invalid format for provider '${providerName}' models in supported-models.json. Expected an array.`
);
return false;
}
const modelInfo = providerModels.find((m) => m && m.id === modelId);
if (!modelInfo) {
console.warn(
`Model '${modelId}' not found for provider '${providerName}' in supported-models.json.`
);
return false;
}
// Check if the role is allowed for this model
if (!Array.isArray(modelInfo.allowed_roles)) {
console.warn(
`Model '${modelId}' (Provider: '${providerName}') has invalid or missing 'allowed_roles' array in supported-models.json.`
);
return false;
}
const isAllowed = modelInfo.allowed_roles.includes(role);
if (!isAllowed) {
console.warn(
`Role '${role}' is not allowed for model '${modelId}' (Provider: '${providerName}'). Allowed roles: ${modelInfo.allowed_roles.join(', ')}`
);
}
return isAllowed;
}
/**
* Resolves an environment variable by checking process.env first, then session.env.
* @param {string} varName - The name of the environment variable.
* @param {object|null} session - The MCP session object (optional).
* @returns {string|undefined} The value of the environment variable or undefined if not found.
*/
function resolveEnvVariable(varName, session) {
return process.env[varName] ?? session?.env?.[varName];
}
/**
* Validates if the required environment variables are set for a given provider,
* checking process.env and falling back to session.env.
* Throws an error if any required variable is missing.
* @param {string} providerName - The name of the provider (e.g., 'openai', 'anthropic').
* @param {object|null} session - The MCP session object (optional).
*/
function validateEnvironment(providerName, session) {
// Define requirements based on the provider
const requirements = {
openai: ['OPENAI_API_KEY'],
anthropic: ['ANTHROPIC_API_KEY'],
google: ['GOOGLE_API_KEY'],
perplexity: ['PERPLEXITY_API_KEY'],
ollama: ['OLLAMA_BASE_URL'], // Ollama only needs Base URL typically
mistral: ['MISTRAL_API_KEY'],
azure: ['AZURE_OPENAI_API_KEY', 'AZURE_OPENAI_ENDPOINT'],
openrouter: ['OPENROUTER_API_KEY'],
xai: ['XAI_API_KEY']
// Add requirements for other providers
};
const providerKey = providerName?.toLowerCase();
if (!providerKey || !requirements[providerKey]) {
// If the provider itself isn't in our requirements list, we can't validate.
// This might happen if config has an unsupported provider. Validation should happen earlier.
// Or, we could throw an error here if the provider is unknown.
console.warn(
`Cannot validate environment for unknown or unsupported provider: ${providerName}`
);
return; // Proceed without validation for unknown providers
}
const missing =
requirements[providerKey]?.filter(
(envVar) => !resolveEnvVariable(envVar, session)
) || [];
if (missing.length > 0) {
throw new Error(
`Missing environment variables for provider '${providerName}': ${missing.join(', ')}. Please check your .env file or session configuration.`
);
}
}
/**
* Creates an AI client instance for the specified provider.
* Assumes environment validation has already passed.
* @param {string} providerName - The name of the provider.
* @param {object|null} session - The MCP session object (optional).
* @param {object} [options={}] - Additional options for the client creation (e.g., model).
* @returns {object} The created AI client instance.
* @throws {Error} If the provider is unsupported.
*/
function createClientInstance(providerName, session, options = {}) {
// Validation is now done before calling this function
const getEnv = (varName) => resolveEnvVariable(varName, session);
switch (providerName?.toLowerCase()) {
case 'openai':
return createOpenAI({ apiKey: getEnv('OPENAI_API_KEY'), ...options });
case 'anthropic':
return createAnthropic({
apiKey: getEnv('ANTHROPIC_API_KEY'),
...options
});
case 'google':
return createGoogle({ apiKey: getEnv('GOOGLE_API_KEY'), ...options });
case 'perplexity':
return createPerplexity({
apiKey: getEnv('PERPLEXITY_API_KEY'),
...options
});
case 'ollama':
const ollamaBaseUrl =
getEnv('OLLAMA_BASE_URL') || 'http://localhost:11434/api'; // Default from ollama-ai-provider docs
// ollama-ai-provider uses baseURL directly
return createOllama({ baseURL: ollamaBaseUrl, ...options });
case 'mistral':
return createMistral({ apiKey: getEnv('MISTRAL_API_KEY'), ...options });
case 'azure':
return createAzure({
apiKey: getEnv('AZURE_OPENAI_API_KEY'),
endpoint: getEnv('AZURE_OPENAI_ENDPOINT'),
...(options.model && { deploymentName: options.model }), // Azure often uses deployment name
...options
});
case 'openrouter':
return createOpenRouter({
apiKey: getEnv('OPENROUTER_API_KEY'),
...options
});
case 'xai':
return createXai({ apiKey: getEnv('XAI_API_KEY'), ...options });
// TODO: Add cases for OpenRouter, Grok
default:
throw new Error(`Unsupported AI provider specified: ${providerName}`);
}
}
/**
* Gets or creates an AI client instance based on the configured model for a specific role.
* Validates the configured model against supported models and role allowances.
* @param {string} role - The role ('main', 'research', or 'fallback').
* @param {object|null} [session=null] - The MCP session object (optional).
* @param {object} [overrideOptions={}] - Optional overrides for { provider, modelId }.
* @returns {object} The cached or newly created AI client instance.
* @throws {Error} If configuration is missing, invalid, or environment validation fails.
*/
export function getClient(role, session = null, overrideOptions = {}) {
if (!role) {
throw new Error(
`Client role ('main', 'research', 'fallback') must be specified.`
);
}
// 1. Determine Provider and Model ID
let providerName = overrideOptions.provider;
let modelId = overrideOptions.modelId;
if (!providerName || !modelId) {
// If not fully overridden, get from config
try {
const config = getProviderAndModelForRole(role); // Fetch from config manager
providerName = providerName || config.provider;
modelId = modelId || config.modelId;
} catch (configError) {
throw new Error(
`Failed to get configuration for role '${role}': ${configError.message}`
);
}
}
if (!providerName || !modelId) {
throw new Error(
`Could not determine provider or modelId for role '${role}' from configuration or overrides.`
);
}
// 2. Validate Provider/Model Combination and Role Allowance
const validationResult = isModelSupportedAndAllowed(
providerName,
modelId,
role
);
// Only throw if validation explicitly returned false (meaning invalid/disallowed)
// If it returned VALIDATION_SKIPPED, we proceed but skip strict validation.
if (validationResult === false) {
throw new Error(
`Model '${modelId}' from provider '${providerName}' is either not supported or not allowed for the '${role}' role. Check supported-models.json and your .taskmasterconfig.`
);
}
// Note: If validationResult === VALIDATION_SKIPPED, we continue to env validation
// 3. Validate Environment Variables for the chosen provider
try {
validateEnvironment(providerName, session);
} catch (envError) {
// Re-throw the original environment error for clearer test messages
throw envError;
}
// 4. Check Cache
const cacheKey = `${providerName.toLowerCase()}:${modelId}`;
if (clientCache.has(cacheKey)) {
return clientCache.get(cacheKey);
}
// 5. Create New Client Instance
console.log(
`Creating new client for role '${role}': Provider=${providerName}, Model=${modelId}`
);
try {
const clientInstance = createClientInstance(providerName, session, {
model: modelId
});
clientCache.set(cacheKey, clientInstance);
return clientInstance;
} catch (creationError) {
throw new Error(
`Failed to create client instance for provider '${providerName}' (role: '${role}'): ${creationError.message}`
);
}
}
// Optional: Function to clear the cache if needed
export function clearClientCache() {
clientCache.clear();
console.log('AI client cache cleared.');
}
// Exported for testing purposes only
export function _resetSupportedModelsCache() {
console.log('DEBUG: Resetting supported models cache...');
supportedModelsData = null;
modelsDataLoaded = false;
console.log('DEBUG: Supported models cache reset.');
}

1557
scripts/modules/ai-services.js
View File

File diff suppressed because it is too large Load Diff

1
scripts/modules/index.js
View File

@@ -6,6 +6,5 @@
// Export all modules
export * from './utils.js';
export * from './ui.js';
export * from './ai-services.js';
export * from './task-manager.js';
export * from './commands.js';

103
scripts/modules/task-manager/update-subtask-by-id.js
View File

@@ -9,54 +9,55 @@ import {
startLoadingIndicator,
stopLoadingIndicator
} from '../ui.js';
import { log, readJSON, writeJSON, truncate, isSilentMode } from '../utils.js';
import { generateTextService } from '../ai-services-unified.js';
import {
getDebugFlag,
getMainModelId,
getMainMaxTokens,
getMainTemperature,
getResearchModelId,
getResearchMaxTokens,
getResearchTemperature
} from '../config-manager.js';
log as consoleLog,
readJSON,
writeJSON,
truncate,
isSilentMode
} from '../utils.js';
import { generateTextService } from '../ai-services-unified.js';
import { getDebugFlag, isApiKeySet } from '../config-manager.js';
import generateTaskFiles from './generate-task-files.js';
/**
* Update a subtask by appending additional information to its description and details
* Update a subtask by appending additional timestamped information using the unified AI service.
* @param {string} tasksPath - Path to the tasks.json file
* @param {string} subtaskId - ID of the subtask to update in format "parentId.subtaskId"
* @param {string} prompt - Prompt for generating additional information
* @param {boolean} useResearch - Whether to use Perplexity AI for research-backed updates
* @param {function} reportProgress - Function to report progress to MCP server (optional)
* @param {Object} mcpLog - MCP logger object (optional)
* @param {Object} session - Session object from MCP server (optional)
* @returns {Object|null} - The updated subtask or null if update failed
* @param {boolean} [useResearch=false] - Whether to use the research AI role.
* @param {Object} context - Context object containing session and mcpLog.
* @param {Object} [context.session] - Session object from MCP server.
* @param {Object} [context.mcpLog] - MCP logger object.
* @param {string} [outputFormat='text'] - Output format ('text' or 'json'). Automatically 'json' if mcpLog is present.
* @returns {Promise<Object|null>} - The updated subtask or null if update failed.
*/
async function updateSubtaskById(
tasksPath,
subtaskId,
prompt,
useResearch = false,
{ reportProgress, mcpLog, session } = {}
context = {},
outputFormat = context.mcpLog ? 'json' : 'text'
) {
// Determine output format based on mcpLog presence (simplification)
const outputFormat = mcpLog ? 'json' : 'text';
const { session, mcpLog } = context;
const logFn = mcpLog || consoleLog;
const isMCP = !!mcpLog;
// Create custom reporter that checks for MCP log and silent mode
const report = (message, level = 'info') => {
if (mcpLog) {
mcpLog[level](message);
} else if (!isSilentMode() && outputFormat === 'text') {
// Only log to console if not in silent mode and outputFormat is 'text'
log(level, message);
// Report helper
const report = (level, ...args) => {
if (isMCP) {
if (typeof logFn[level] === 'function') logFn[level](...args);
else logFn.info(...args);
} else if (!isSilentMode()) {
logFn(level, ...args);
}
};
let loadingIndicator = null;
try {
report(`Updating subtask ${subtaskId} with prompt: "${prompt}"`, 'info');
report('info', `Updating subtask ${subtaskId} with prompt: "${prompt}"`);
// Validate subtask ID format
if (
@@ -76,9 +77,6 @@ async function updateSubtaskById(
);
}
// Prepare for fallback handling
let claudeOverloaded = false;
// Validate tasks file exists
if (!fs.existsSync(tasksPath)) {
throw new Error(`Tasks file not found at path: ${tasksPath}`);
@@ -121,18 +119,22 @@ async function updateSubtaskById(
throw new Error(`Parent task ${parentId} has no subtasks.`);
}
const subtask = parentTask.subtasks.find((st) => st.id === subtaskIdNum);
if (!subtask) {
const subtaskIndex = parentTask.subtasks.findIndex(
(st) => st.id === subtaskIdNum
);
if (subtaskIndex === -1) {
throw new Error(
`Subtask with ID ${subtaskId} not found. Please verify the subtask ID and try again.`
);
}
const subtask = parentTask.subtasks[subtaskIndex];
// Check if subtask is already completed
if (subtask.status === 'done' || subtask.status === 'completed') {
report(
`Subtask ${subtaskId} is already marked as done and cannot be updated`,
'warn'
'warn',
`Subtask ${subtaskId} is already marked as done and cannot be updated`
);
// Only show UI elements for text output (CLI)
@@ -208,13 +210,13 @@ Provide concrete examples, code snippets, or implementation details when relevan
const userMessageContent = `Here is the subtask to enhance:\n${subtaskData}\n\nPlease provide additional information addressing this request:\n${prompt}\n\nReturn ONLY the new information to add - do not repeat existing content.`;
const serviceRole = useResearch ? 'research' : 'main';
report(`Calling AI stream service with role: ${serviceRole}`, 'info');
report('info', `Calling AI text service with role: ${serviceRole}`);
const streamResult = await generateTextService({
role: serviceRole,
session: session,
systemPrompt: systemPrompt, // Pass the original system prompt
prompt: userMessageContent // Pass the original user message content
systemPrompt: systemPrompt,
prompt: userMessageContent
});
if (outputFormat === 'text' && loadingIndicator) {
@@ -231,11 +233,11 @@ Provide concrete examples, code snippets, or implementation details when relevan
}
report(
// Corrected log message to reflect generateText
`Successfully generated text using AI role: ${serviceRole}.`,
'info'
'success',
`Successfully generated text using AI role: ${serviceRole}.`
);
} catch (aiError) {
report(`AI service call failed: ${aiError.message}`, 'error');
report('error', `AI service call failed: ${aiError.message}`);
throw aiError;
} // Removed the inner finally block as streamingInterval is gone
@@ -245,7 +247,7 @@ Provide concrete examples, code snippets, or implementation details when relevan
const formattedInformation = `\n\n<info added on ${currentDate.toISOString()}>\n${additionalInformation}\n</info added on ${currentDate.toISOString()}>`;
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log(
'>>> DEBUG: formattedInformation:',
formattedInformation.substring(0, 70) + '...'
@@ -254,7 +256,7 @@ Provide concrete examples, code snippets, or implementation details when relevan
// Append to subtask details and description
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log('>>> DEBUG: Subtask details BEFORE append:', subtask.details);
}
@@ -265,7 +267,7 @@ Provide concrete examples, code snippets, or implementation details when relevan
}
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log('>>> DEBUG: Subtask details AFTER append:', subtask.details);
}
@@ -273,7 +275,7 @@ Provide concrete examples, code snippets, or implementation details when relevan
// Only append to description if it makes sense (for shorter updates)
if (additionalInformation.length < 200) {
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log(
'>>> DEBUG: Subtask description BEFORE append:',
subtask.description
@@ -281,7 +283,7 @@ Provide concrete examples, code snippets, or implementation details when relevan
}
subtask.description += ` [Updated: ${currentDate.toLocaleDateString()}]`;
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log(
'>>> DEBUG: Subtask description AFTER append:',
subtask.description
@@ -291,19 +293,22 @@ Provide concrete examples, code snippets, or implementation details when relevan
}
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log('>>> DEBUG: About to call writeJSON with updated data...');
}
// Update the subtask in the parent task's array
parentTask.subtasks[subtaskIndex] = subtask;
// Write the updated tasks to the file
writeJSON(tasksPath, data);
// Only show debug info for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text' && getDebugFlag(session)) {
console.log('>>> DEBUG: writeJSON call completed.');
}
report(`Successfully updated subtask ${subtaskId}`, 'success');
report('success', `Successfully updated subtask ${subtaskId}`);
// Generate individual task files
await generateTaskFiles(tasksPath, path.dirname(tasksPath));
@@ -340,7 +345,7 @@ Provide concrete examples, code snippets, or implementation details when relevan
loadingIndicator = null;
}
report(`Error updating subtask: ${error.message}`, 'error');
report('error', `Error updating subtask: ${error.message}`);
// Only show error UI for text output (CLI)
if (outputFormat === 'text') {

822
scripts/modules/task-manager/update-task-by-id.js
View File

@@ -3,8 +3,15 @@ import path from 'path';
import chalk from 'chalk';
import boxen from 'boxen';
import Table from 'cli-table3';
import { z } from 'zod'; // Keep Zod for post-parse validation
import { log, readJSON, writeJSON, truncate, isSilentMode } from '../utils.js';
import {
log as consoleLog,
readJSON,
writeJSON,
truncate,
isSilentMode
} from '../utils.js';
import {
getStatusWithColor,
@@ -12,111 +19,205 @@ import {
stopLoadingIndicator
} from '../ui.js';
import { _handleAnthropicStream } from '../ai-services.js';
import { generateTextService } from '../ai-services-unified.js';
import {
getDebugFlag,
getMainModelId,
getMainMaxTokens,
getMainTemperature,
getResearchModelId,
getResearchMaxTokens,
getResearchTemperature,
isApiKeySet
isApiKeySet // Keep this check
} from '../config-manager.js';
import generateTaskFiles from './generate-task-files.js';
// Zod schema for post-parsing validation of the updated task object
const updatedTaskSchema = z
.object({
id: z.number().int(),
title: z.string(), // Title should be preserved, but check it exists
description: z.string(),
status: z.string(),
dependencies: z.array(z.union([z.number().int(), z.string()])),
priority: z.string().optional(),
details: z.string().optional(),
testStrategy: z.string().optional(),
subtasks: z.array(z.any()).optional()
})
.strip(); // Allows parsing even if AI adds extra fields, but validation focuses on schema
/**
* Update a single task by ID
* Parses a single updated task object from AI's text response.
* @param {string} text - Response text from AI.
* @param {number} expectedTaskId - The ID of the task expected.
* @param {Function | Object} logFn - Logging function or MCP logger.
* @param {boolean} isMCP - Flag indicating MCP context.
* @returns {Object} Parsed and validated task object.
* @throws {Error} If parsing or validation fails.
*/
function parseUpdatedTaskFromText(text, expectedTaskId, logFn, isMCP) {
// Report helper consistent with the established pattern
const report = (level, ...args) => {
if (isMCP) {
if (typeof logFn[level] === 'function') logFn[level](...args);
else logFn.info(...args);
} else if (!isSilentMode()) {
logFn(level, ...args);
}
};
report(
'info',
'Attempting to parse updated task object from text response...'
);
if (!text || text.trim() === '')
throw new Error('AI response text is empty.');
let cleanedResponse = text.trim();
const originalResponseForDebug = cleanedResponse;
// Extract from Markdown code block first
const codeBlockMatch = cleanedResponse.match(
/```(?:json)?\s*([\s\S]*?)\s*```/
);
if (codeBlockMatch) {
cleanedResponse = codeBlockMatch[1].trim();
report('info', 'Extracted JSON content from Markdown code block.');
} else {
// If no code block, find first '{' and last '}' for the object
const firstBrace = cleanedResponse.indexOf('{');
const lastBrace = cleanedResponse.lastIndexOf('}');
if (firstBrace !== -1 && lastBrace > firstBrace) {
cleanedResponse = cleanedResponse.substring(firstBrace, lastBrace + 1);
report('info', 'Extracted content between first { and last }.');
} else {
report(
'warn',
'Response does not appear to contain a JSON object structure. Parsing raw response.'
);
}
}
let parsedTask;
try {
parsedTask = JSON.parse(cleanedResponse);
} catch (parseError) {
report('error', `Failed to parse JSON object: ${parseError.message}`);
report(
'error',
`Problematic JSON string (first 500 chars): ${cleanedResponse.substring(0, 500)}`
);
report(
'error',
`Original Raw Response (first 500 chars): ${originalResponseForDebug.substring(0, 500)}`
);
throw new Error(
`Failed to parse JSON response object: ${parseError.message}`
);
}
if (!parsedTask || typeof parsedTask !== 'object') {
report(
'error',
`Parsed content is not an object. Type: ${typeof parsedTask}`
);
report(
'error',
`Parsed content sample: ${JSON.stringify(parsedTask).substring(0, 200)}`
);
throw new Error('Parsed AI response is not a valid JSON object.');
}
// Validate the parsed task object using Zod
const validationResult = updatedTaskSchema.safeParse(parsedTask);
if (!validationResult.success) {
report('error', 'Parsed task object failed Zod validation.');
validationResult.error.errors.forEach((err) => {
report('error', ` - Field '${err.path.join('.')}': ${err.message}`);
});
throw new Error(
`AI response failed task structure validation: ${validationResult.error.message}`
);
}
// Final check: ensure ID matches expected ID (AI might hallucinate)
if (validationResult.data.id !== expectedTaskId) {
report(
'warn',
`AI returned task with ID ${validationResult.data.id}, but expected ${expectedTaskId}. Overwriting ID.`
);
validationResult.data.id = expectedTaskId; // Enforce correct ID
}
report('info', 'Successfully validated updated task structure.');
return validationResult.data; // Return the validated task data
}
/**
* Update a single task by ID using the unified AI service.
* @param {string} tasksPath - Path to the tasks.json file
* @param {number} taskId - Task ID to update
* @param {string} prompt - Prompt with new context
* @param {boolean} useResearch - Whether to use Perplexity AI for research
* @param {function} reportProgress - Function to report progress to MCP server (optional)
* @param {Object} mcpLog - MCP logger object (optional)
* @param {Object} session - Session object from MCP server (optional)
* @returns {Object} - Updated task data or null if task wasn't updated
* @param {boolean} [useResearch=false] - Whether to use the research AI role.
* @param {Object} context - Context object containing session and mcpLog.
* @param {Object} [context.session] - Session object from MCP server.
* @param {Object} [context.mcpLog] - MCP logger object.
* @param {string} [outputFormat='text'] - Output format ('text' or 'json').
* @returns {Promise<Object|null>} - Updated task data or null if task wasn't updated/found.
*/
async function updateTaskById(
tasksPath,
taskId,
prompt,
useResearch = false,
{ reportProgress, mcpLog, session } = {}
context = {},
outputFormat = 'text'
) {
// Determine output format based on mcpLog presence (simplification)
const outputFormat = mcpLog ? 'json' : 'text';
const { session, mcpLog } = context;
const logFn = mcpLog || consoleLog;
const isMCP = !!mcpLog;
// Create custom reporter that checks for MCP log and silent mode
const report = (message, level = 'info') => {
if (mcpLog) {
mcpLog[level](message);
} else if (!isSilentMode() && outputFormat === 'text') {
// Only log to console if not in silent mode and outputFormat is 'text'
log(level, message);
// Use report helper for logging
const report = (level, ...args) => {
if (isMCP) {
if (typeof logFn[level] === 'function') logFn[level](...args);
else logFn.info(...args);
} else if (!isSilentMode()) {
logFn(level, ...args);
}
};
try {
report(`Updating single task ${taskId} with prompt: "${prompt}"`, 'info');
report('info', `Updating single task ${taskId} with prompt: "${prompt}"`);
// Validate task ID is a positive integer
if (!Number.isInteger(taskId) || taskId <= 0) {
// --- Input Validations (Keep existing) ---
if (!Number.isInteger(taskId) || taskId <= 0)
throw new Error(
`Invalid task ID: ${taskId}. Task ID must be a positive integer.`
);
}
// Validate prompt
if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
throw new Error(
'Prompt cannot be empty. Please provide context for the task update.'
);
}
// Validate research flag and API key
if (!prompt || typeof prompt !== 'string' || prompt.trim() === '')
throw new Error('Prompt cannot be empty.');
if (useResearch && !isApiKeySet('perplexity', session)) {
report(
'Perplexity AI research requested but API key is not set. Falling back to main AI.',
'warn'
'warn',
'Perplexity research requested but API key not set. Falling back.'
);
// Only show UI elements for text output (CLI)
if (outputFormat === 'text') {
if (outputFormat === 'text')
console.log(
chalk.yellow(
'Perplexity AI is not available (API key may be missing). Falling back to Claude AI.'
)
chalk.yellow('Perplexity AI not available. Falling back to main AI.')
);
}
useResearch = false;
}
if (!fs.existsSync(tasksPath))
throw new Error(`Tasks file not found: ${tasksPath}`);
// --- End Input Validations ---
// Validate tasks file exists
if (!fs.existsSync(tasksPath)) {
throw new Error(`Tasks file not found at path: ${tasksPath}`);
}
// Read the tasks file
// --- Task Loading and Status Check (Keep existing) ---
const data = readJSON(tasksPath);
if (!data || !data.tasks) {
throw new Error(
`No valid tasks found in ${tasksPath}. The file may be corrupted or have an invalid format.`
);
}
// Find the specific task to update
const taskToUpdate = data.tasks.find((task) => task.id === taskId);
if (!taskToUpdate) {
throw new Error(
`Task with ID ${taskId} not found. Please verify the task ID and try again.`
);
}
// Check if task is already completed
if (!data || !data.tasks)
throw new Error(`No valid tasks found in ${tasksPath}.`);
const taskIndex = data.tasks.findIndex((task) => task.id === taskId);
if (taskIndex === -1) throw new Error(`Task with ID ${taskId} not found.`);
const taskToUpdate = data.tasks[taskIndex];
if (taskToUpdate.status === 'done' || taskToUpdate.status === 'completed') {
report(
`Task ${taskId} is already marked as done and cannot be updated`,
'warn'
'warn',
`Task ${taskId} is already marked as done and cannot be updated`
);
// Only show warning box for text output (CLI)
@@ -142,8 +243,9 @@ async function updateTaskById(
}
return null;
}
// --- End Task Loading ---
// Only show UI elements for text output (CLI)
// --- Display Task Info (CLI Only - Keep existing) ---
if (outputFormat === 'text') {
// Show the task that will be updated
const table = new Table({
@@ -199,7 +301,7 @@ async function updateTaskById(
);
}
// Build the system prompt
// --- Build Prompts (Keep EXACT original prompts) ---
const systemPrompt = `You are an AI assistant helping to update a software development task based on new context.
You will be given a task and a prompt describing changes or new implementation details.
Your job is to update the task to reflect these changes, while preserving its basic structure.
@@ -219,464 +321,162 @@ Guidelines:
The changes described in the prompt should be thoughtfully applied to make the task more accurate and actionable.`;
const taskData = JSON.stringify(taskToUpdate, null, 2);
const taskDataString = JSON.stringify(taskToUpdate, null, 2); // Use original task data
const userPrompt = `Here is the task to update:\n${taskDataString}\n\nPlease update this task based on the following new context:\n${prompt}\n\nIMPORTANT: In the task JSON above, any subtasks with "status": "done" or "status": "completed" should be preserved exactly as is. Build your changes around these completed items.\n\nReturn only the updated task as a valid JSON object.`;
// --- End Build Prompts ---
// Initialize variables for model selection and fallback
let updatedTask;
let loadingIndicator = null;
let claudeOverloaded = false;
let modelAttempts = 0;
const maxModelAttempts = 2; // Try up to 2 models before giving up
// Only create initial loading indicator for text output (CLI)
if (outputFormat === 'text') {
loadingIndicator = startLoadingIndicator(
useResearch
? 'Updating task with Perplexity AI research...'
: 'Updating task with Claude AI...'
useResearch ? 'Updating task with research...' : 'Updating task...'
);
}
let responseText = '';
try {
// Import the getAvailableAIModel function
const { getAvailableAIModel } = await import('./ai-services.js');
// --- Call Unified AI Service (generateTextService) ---
const role = useResearch ? 'research' : 'main';
report('info', `Using AI service with role: ${role}`);
// Try different models with fallback
while (modelAttempts < maxModelAttempts && !updatedTask) {
modelAttempts++;
const isLastAttempt = modelAttempts >= maxModelAttempts;
let modelType = null;
try {
// Get the appropriate model based on current state
const result = getAvailableAIModel({
claudeOverloaded,
requiresResearch: useResearch
});
modelType = result.type;
const client = result.client;
report(
`Attempt ${modelAttempts}/${maxModelAttempts}: Updating task using ${modelType}`,
'info'
);
// Update loading indicator - only for text output
if (outputFormat === 'text') {
if (loadingIndicator) {
stopLoadingIndicator(loadingIndicator);
}
loadingIndicator = startLoadingIndicator(
`Attempt ${modelAttempts}: Using ${modelType.toUpperCase()}...`
);
}
if (modelType === 'perplexity') {
// Call Perplexity AI
const perplexityModel =
process.env.PERPLEXITY_MODEL ||
session?.env?.PERPLEXITY_MODEL ||
'sonar-pro';
const result = await client.chat.completions.create({
model: getResearchModelId(session),
messages: [
{
role: 'system',
content: `${systemPrompt}\n\nAdditionally, please research the latest best practices, implementation details, and considerations when updating this task. Use your online search capabilities to gather relevant information. Remember to strictly follow the guidelines about preserving completed subtasks and building upon what has already been done rather than modifying or replacing it.`
},
{
role: 'user',
content: `Here is the task to update:
${taskData}
Please update this task based on the following new context:
${prompt}
IMPORTANT: In the task JSON above, any subtasks with "status": "done" or "status": "completed" should be preserved exactly as is. Build your changes around these completed items.
Return only the updated task as a valid JSON object.`
}
],
temperature: getResearchTemperature(session),
max_tokens: getResearchMaxTokens(session)
});
const responseText = result.choices[0].message.content;
// Extract JSON from response
const jsonStart = responseText.indexOf('{');
const jsonEnd = responseText.lastIndexOf('}');
if (jsonStart === -1 || jsonEnd === -1) {
throw new Error(
`Could not find valid JSON object in ${modelType}'s response. The response may be malformed.`
);
}
const jsonText = responseText.substring(jsonStart, jsonEnd + 1);
try {
updatedTask = JSON.parse(jsonText);
} catch (parseError) {
throw new Error(
`Failed to parse ${modelType} response as JSON: ${parseError.message}\nResponse fragment: ${jsonText.substring(0, 100)}...`
);
}
} else {
// Call Claude to update the task with streaming
let responseText = '';
let streamingInterval = null;
try {
// Update loading indicator to show streaming progress - only for text output
if (outputFormat === 'text') {
let dotCount = 0;
const readline = await import('readline');
streamingInterval = setInterval(() => {
readline.cursorTo(process.stdout, 0);
process.stdout.write(
`Receiving streaming response from Claude${'.'.repeat(dotCount)}`
);
dotCount = (dotCount + 1) % 4;
}, 500);
}
// Use streaming API call
const stream = await client.messages.create({
model: getMainModelId(session),
max_tokens: getMainMaxTokens(session),
temperature: getMainTemperature(session),
system: systemPrompt,
messages: [
{
role: 'user',
content: `Here is the task to update:
${taskData}
Please update this task based on the following new context:
${prompt}
IMPORTANT: In the task JSON above, any subtasks with "status": "done" or "status": "completed" should be preserved exactly as is. Build your changes around these completed items.
Return only the updated task as a valid JSON object.`
}
],
stream: true
});
// Process the stream
for await (const chunk of stream) {
if (chunk.type === 'content_block_delta' && chunk.delta.text) {
responseText += chunk.delta.text;
}
if (reportProgress) {
await reportProgress({
progress:
(responseText.length / getMainMaxTokens(session)) * 100
});
}
if (mcpLog) {
mcpLog.info(
`Progress: ${(responseText.length / getMainMaxTokens(session)) * 100}%`
);
}
}
if (streamingInterval) clearInterval(streamingInterval);
report(
`Completed streaming response from ${modelType} API (Attempt ${modelAttempts})`,
'info'
);
// Extract JSON from response
const jsonStart = responseText.indexOf('{');
const jsonEnd = responseText.lastIndexOf('}');
if (jsonStart === -1 || jsonEnd === -1) {
throw new Error(
`Could not find valid JSON object in ${modelType}'s response. The response may be malformed.`
);
}
const jsonText = responseText.substring(jsonStart, jsonEnd + 1);
try {
updatedTask = JSON.parse(jsonText);
} catch (parseError) {
throw new Error(
`Failed to parse ${modelType} response as JSON: ${parseError.message}\nResponse fragment: ${jsonText.substring(0, 100)}...`
);
}
} catch (streamError) {
if (streamingInterval) clearInterval(streamingInterval);
// Process stream errors explicitly
report(`Stream error: ${streamError.message}`, 'error');
// Check if this is an overload error
let isOverload = false;
// Check 1: SDK specific property
if (streamError.type === 'overloaded_error') {
isOverload = true;
}
// Check 2: Check nested error property
else if (streamError.error?.type === 'overloaded_error') {
isOverload = true;
}
// Check 3: Check status code
else if (
streamError.status === 429 ||
streamError.status === 529
) {
isOverload = true;
}
// Check 4: Check message string
else if (
streamError.message?.toLowerCase().includes('overloaded')
) {
isOverload = true;
}
if (isOverload) {
claudeOverloaded = true;
report(
'Claude overloaded. Will attempt fallback model if available.',
'warn'
);
// Let the loop continue to try the next model
throw new Error('Claude overloaded');
} else {
// Re-throw non-overload errors
throw streamError;
}
}
}
// If we got here successfully, break out of the loop
if (updatedTask) {
report(
`Successfully updated task using ${modelType} on attempt ${modelAttempts}`,
'success'
);
break;
}
} catch (modelError) {
const failedModel = modelType || 'unknown model';
report(
`Attempt ${modelAttempts} failed using ${failedModel}: ${modelError.message}`,
'warn'
);
// Continue to next attempt if we have more attempts and this was an overload error
const wasOverload = modelError.message
?.toLowerCase()
.includes('overload');
if (wasOverload && !isLastAttempt) {
if (modelType === 'claude') {
claudeOverloaded = true;
report('Will attempt with Perplexity AI next', 'info');
}
continue; // Continue to next attempt
} else if (isLastAttempt) {
report(
`Final attempt (${modelAttempts}/${maxModelAttempts}) failed. No fallback possible.`,
'error'
);
throw modelError; // Re-throw on last attempt
} else {
throw modelError; // Re-throw for non-overload errors
}
}
responseText = await generateTextService({
prompt: userPrompt,
systemPrompt: systemPrompt,
role,
session
});
report('success', 'Successfully received text response from AI service');
// --- End AI Service Call ---
} catch (error) {
// Catch errors from generateTextService
if (loadingIndicator) stopLoadingIndicator(loadingIndicator);
report('error', `Error during AI service call: ${error.message}`);
if (error.message.includes('API key')) {
report('error', 'Please ensure API keys are configured correctly.');
}
// If we don't have updated task after all attempts, throw an error
if (!updatedTask) {
throw new Error(
'Failed to generate updated task after all model attempts'
);
}
// Validation of the updated task
if (!updatedTask || typeof updatedTask !== 'object') {
throw new Error(
'Received invalid task object from AI. The response did not contain a valid task.'
);
}
// Ensure critical fields exist
if (!updatedTask.title || !updatedTask.description) {
throw new Error(
'Updated task is missing required fields (title or description).'
);
}
// Ensure ID is preserved
if (updatedTask.id !== taskId) {
report(
`Task ID was modified in the AI response. Restoring original ID ${taskId}.`,
'warn'
);
updatedTask.id = taskId;
}
// Ensure status is preserved unless explicitly changed in prompt
if (
updatedTask.status !== taskToUpdate.status &&
!prompt.toLowerCase().includes('status')
) {
report(
`Task status was modified without explicit instruction. Restoring original status '${taskToUpdate.status}'.`,
'warn'
);
updatedTask.status = taskToUpdate.status;
}
// Ensure completed subtasks are preserved
if (taskToUpdate.subtasks && taskToUpdate.subtasks.length > 0) {
if (!updatedTask.subtasks) {
report(
'Subtasks were removed in the AI response. Restoring original subtasks.',
'warn'
);
updatedTask.subtasks = taskToUpdate.subtasks;
} else {
// Check for each completed subtask
const completedSubtasks = taskToUpdate.subtasks.filter(
(st) => st.status === 'done' || st.status === 'completed'
);
for (const completedSubtask of completedSubtasks) {
const updatedSubtask = updatedTask.subtasks.find(
(st) => st.id === completedSubtask.id
);
// If completed subtask is missing or modified, restore it
if (!updatedSubtask) {
report(
`Completed subtask ${completedSubtask.id} was removed. Restoring it.`,
'warn'
);
updatedTask.subtasks.push(completedSubtask);
} else if (
updatedSubtask.title !== completedSubtask.title ||
updatedSubtask.description !== completedSubtask.description ||
updatedSubtask.details !== completedSubtask.details ||
updatedSubtask.status !== completedSubtask.status
) {
report(
`Completed subtask ${completedSubtask.id} was modified. Restoring original.`,
'warn'
);
// Find and replace the modified subtask
const index = updatedTask.subtasks.findIndex(
(st) => st.id === completedSubtask.id
);
if (index !== -1) {
updatedTask.subtasks[index] = completedSubtask;
}
}
}
// Ensure no duplicate subtask IDs
const subtaskIds = new Set();
const uniqueSubtasks = [];
for (const subtask of updatedTask.subtasks) {
if (!subtaskIds.has(subtask.id)) {
subtaskIds.add(subtask.id);
uniqueSubtasks.push(subtask);
} else {
report(
`Duplicate subtask ID ${subtask.id} found. Removing duplicate.`,
'warn'
);
}
}
updatedTask.subtasks = uniqueSubtasks;
}
}
// Update the task in the original data
const index = data.tasks.findIndex((t) => t.id === taskId);
if (index !== -1) {
data.tasks[index] = updatedTask;
} else {
throw new Error(`Task with ID ${taskId} not found in tasks array.`);
}
// Write the updated tasks to the file
writeJSON(tasksPath, data);
report(`Successfully updated task ${taskId}`, 'success');
// Generate individual task files
await generateTaskFiles(tasksPath, path.dirname(tasksPath));
// Only show success box for text output (CLI)
if (outputFormat === 'text') {
console.log(
boxen(
chalk.green(`Successfully updated task #${taskId}`) +
'\n\n' +
chalk.white.bold('Updated Title:') +
' ' +
updatedTask.title,
{ padding: 1, borderColor: 'green', borderStyle: 'round' }
)
);
}
// Return the updated task for testing purposes
return updatedTask;
throw error; // Re-throw error
} finally {
// Stop the loading indicator if it was created
if (loadingIndicator) {
stopLoadingIndicator(loadingIndicator);
loadingIndicator = null;
if (loadingIndicator) stopLoadingIndicator(loadingIndicator);
}
// --- Parse and Validate Response ---
try {
// Pass logFn and isMCP flag to the parser
updatedTask = parseUpdatedTaskFromText(
responseText,
taskId,
logFn,
isMCP
);
} catch (parseError) {
report(
'error',
`Failed to parse updated task from AI response: ${parseError.message}`
);
if (getDebugFlag(session)) {
report('error', `Raw AI Response:\n${responseText}`);
}
throw new Error(
`Failed to parse valid updated task from AI response: ${parseError.message}`
);
}
// --- End Parse/Validate ---
// --- Task Validation/Correction (Keep existing logic) ---
if (!updatedTask || typeof updatedTask !== 'object')
throw new Error('Received invalid task object from AI.');
if (!updatedTask.title || !updatedTask.description)
throw new Error('Updated task missing required fields.');
// Preserve ID if AI changed it
if (updatedTask.id !== taskId) {
report('warn', `AI changed task ID. Restoring original ID ${taskId}.`);
updatedTask.id = taskId;
}
// Preserve status if AI changed it
if (
updatedTask.status !== taskToUpdate.status &&
!prompt.toLowerCase().includes('status')
) {
report(
'warn',
`AI changed task status. Restoring original status '${taskToUpdate.status}'.`
);
updatedTask.status = taskToUpdate.status;
}
// Preserve completed subtasks (Keep existing logic)
if (taskToUpdate.subtasks?.length > 0) {
if (!updatedTask.subtasks) {
report('warn', 'Subtasks removed by AI. Restoring original subtasks.');
updatedTask.subtasks = taskToUpdate.subtasks;
} else {
const completedOriginal = taskToUpdate.subtasks.filter(
(st) => st.status === 'done' || st.status === 'completed'
);
completedOriginal.forEach((compSub) => {
const updatedSub = updatedTask.subtasks.find(
(st) => st.id === compSub.id
);
if (
!updatedSub ||
JSON.stringify(updatedSub) !== JSON.stringify(compSub)
) {
report(
'warn',
`Completed subtask ${compSub.id} was modified or removed. Restoring.`
);
// Remove potentially modified version
updatedTask.subtasks = updatedTask.subtasks.filter(
(st) => st.id !== compSub.id
);
// Add back original
updatedTask.subtasks.push(compSub);
}
});
// Deduplicate just in case
const subtaskIds = new Set();
updatedTask.subtasks = updatedTask.subtasks.filter((st) => {
if (!subtaskIds.has(st.id)) {
subtaskIds.add(st.id);
return true;
}
report('warn', `Duplicate subtask ID ${st.id} removed.`);
return false;
});
}
}
} catch (error) {
report(`Error updating task: ${error.message}`, 'error');
// --- End Task Validation/Correction ---
// Only show error UI for text output (CLI)
// --- Update Task Data (Keep existing) ---
data.tasks[taskIndex] = updatedTask;
// --- End Update Task Data ---
// --- Write File and Generate (Keep existing) ---
writeJSON(tasksPath, data);
report('success', `Successfully updated task ${taskId}`);
await generateTaskFiles(tasksPath, path.dirname(tasksPath));
// --- End Write File ---
// --- Final CLI Output (Keep existing) ---
if (outputFormat === 'text') {
/* ... success boxen ... */
}
// --- End Final CLI Output ---
return updatedTask; // Return the updated task
} catch (error) {
// General error catch
// --- General Error Handling (Keep existing) ---
report('error', `Error updating task: ${error.message}`);
if (outputFormat === 'text') {
console.error(chalk.red(`Error: ${error.message}`));
// Provide more helpful error messages for common issues
if (error.message.includes('ANTHROPIC_API_KEY')) {
console.log(
chalk.yellow('\nTo fix this issue, set your Anthropic API key:')
);
console.log(' export ANTHROPIC_API_KEY=your_api_key_here');
} else if (error.message.includes('PERPLEXITY_API_KEY')) {
console.log(chalk.yellow('\nTo fix this issue:'));
console.log(
' 1. Set your Perplexity API key: export PERPLEXITY_API_KEY=your_api_key_here'
);
console.log(
' 2. Or run without the research flag: task-master update-task --id=<id> --prompt="..."'
);
} else if (
error.message.includes('Task with ID') &&
error.message.includes('not found')
) {
console.log(chalk.yellow('\nTo fix this issue:'));
console.log(' 1. Run task-master list to see all available task IDs');
console.log(' 2. Use a valid task ID with the --id parameter');
}
if (getDebugFlag(session)) {
// Use getter
console.error(error);
}
// ... helpful hints ...
if (getDebugFlag(session)) console.error(error);
process.exit(1);
} else {
throw error; // Re-throw for JSON output
throw error; // Re-throw for MCP
}
return null;
return null; // Indicate failure in CLI case if process doesn't exit
// --- End General Error Handling ---
}
}