CRASH - Cascaded Reasoning with Adaptive Step Handling

Instructions

Implementation Reference

• src/server.ts:402-596 (handler)

  The `processStep` method in the `CrashServer` class is the core handler that executes the 'crash' tool logic. It validates the input CrashStep, handles revisions, branching, sessions, dependencies, updates history, formats output, and returns the MCP-compliant response.
  public async processStep(input: unknown): Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean; }> { try { const step = input as CrashStep; const stepStartTime = Date.now(); // Validate required fields with detailed error messages const fieldValidation = this.validateRequiredFields(step); if (!fieldValidation.valid) { throw new Error(`Missing or invalid required fields: ${fieldValidation.missing.join(', ')}`); } // Validate confidence bounds const confidenceValidation = this.validateConfidence(step); if (!confidenceValidation.valid) { throw new Error(confidenceValidation.error); } // Apply strict mode if enabled if (this.config.validation.strictMode) { if (!this.validateThoughtPrefix(step.thought)) { throw new Error(`Thought must start with one of: ${VALID_PREFIXES.join(', ')} (strict mode)`); } if (!this.validateRationale(step.rationale)) { throw new Error('Rationale must start with "To " (strict mode)'); } if (!this.validatePurpose(step.purpose)) { throw new Error(`Invalid purpose "${step.purpose}". Valid: ${VALID_PURPOSES.join(', ')} (strict mode)`); } } else { // Flexible validation if (!this.validatePurpose(step.purpose)) { console.error(`⚠️ Using custom purpose: ${step.purpose}`); } } // Add timestamp step.timestamp = new Date().toISOString(); // Handle session management with batched cleanup if (step.session_id && this.config.features.enableSessions) { this.cleanupExpiredSessions(); // Uses batched cleanup internally if (!this.sessions.has(step.session_id)) { this.sessions.set(step.session_id, { history: this.createNewHistory(), lastAccessed: Date.now() }); } const sessionEntry = this.sessions.get(step.session_id)!; sessionEntry.lastAccessed = Date.now(); this.history = sessionEntry.history; // Rebuild indexes from session's history (fixes desync bug) this.stepIndex.clear(); this.stepNumbers.clear(); this.toolsUsedSet.clear(); this.stepToBranchMap.clear(); this.branchDepthCache.clear(); for (const existingStep of this.history.steps) { this.stepIndex.set(existingStep.step_number, existingStep); this.stepNumbers.add(existingStep.step_number); // Rebuild step-to-branch map if step is in a branch if (existingStep.branch_id) { this.stepToBranchMap.set(existingStep.step_number, existingStep.branch_id); } } if (this.history.metadata?.tools_used) { for (const tool of this.history.metadata.tools_used) { this.toolsUsedSet.add(tool); } } } // Validate dependencies (uses cached stepNumbers) const depValidation = this.validateDependencies(step); if (depValidation.circular) { throw new Error(`Circular dependency detected for step ${step.step_number}`); } if (!depValidation.valid) { console.error(`⚠️ Proceeding with missing dependencies: ${depValidation.missing.join(', ')}`); } // Check if completed - explicit flag takes priority if (step.is_final_step === true) { this.history.completed = true; } else { // Fallback to phrase detection using pre-computed lowercase phrases const thoughtLower = step.thought.toLowerCase(); if (COMPLETION_PHRASES_LOWER.some(phrase => thoughtLower.includes(phrase))) { this.history.completed = true; } } // Handle revision with validation const revisionResult = this.handleRevision(step); if (!revisionResult.valid) { throw new Error(revisionResult.error); } // Handle branching with depth validation const branchResult = this.handleBranching(step); if (!branchResult.success) { throw new Error(branchResult.error); } // Track tools used efficiently with Set const toolsUsed = this.extractToolsUsed(step); for (const tool of toolsUsed) { this.toolsUsedSet.add(tool); } if (this.history.metadata) { this.history.metadata.tools_used = Array.from(this.toolsUsedSet); } // Add to history and update indexes this.history.steps.push(step); this.stepIndex.set(step.step_number, step); this.stepNumbers.add(step.step_number); // Update metadata if (this.history.metadata) { step.duration_ms = Date.now() - stepStartTime; this.history.metadata.total_duration_ms = Date.now() - this.startTime; } this.history.updated_at = new Date().toISOString(); // Trim history if needed (with orphaned reference cleanup) this.trimHistory(); // Display formatted step const formattedOutput = this.formatOutput(step); console.error(formattedOutput); // Show confidence warning if low if (step.confidence !== undefined && step.confidence < LOW_CONFIDENCE_THRESHOLD) { console.error(`⚠️ Low confidence (${Math.round(step.confidence * 100)}%): ${step.uncertainty_notes || 'Consider verification'}`); } // Prepare response const responseData: any = { step_number: step.step_number, estimated_total: step.estimated_total, completed: this.history.completed, total_steps: this.history.steps.length, next_action: step.next_action, }; // Add optional response fields if (step.confidence !== undefined) { responseData.confidence = step.confidence; } if (step.revises_step) { responseData.revised_step = step.revises_step; } if (step.branch_id) { responseData.branch = { id: step.branch_id, name: step.branch_name, from: step.branch_from }; } return { content: [ { type: 'text', text: JSON.stringify(responseData, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify( { error: error instanceof Error ? error.message : String(error), status: 'failed', hint: this.config.validation.strictMode ? 'Strict mode is enabled. Set CRASH_STRICT_MODE=false for flexible validation.' : 'Check that all required fields are provided.', }, null, 2 ), }, ], isError: true, }; } }
• src/schema.ts:24-159 (schema)

  Defines the 'crash' tool schema including name, detailed description, and comprehensive inputSchema with required fields and optional features for structured reasoning steps.
  export const CRASH_TOOL: Tool = { name: 'crash', description: TOOL_DESCRIPTION, inputSchema: { type: 'object', properties: { // Core required fields step_number: { type: 'integer', description: 'Sequential step number starting from 1. Increment for each new reasoning step.', minimum: 1 }, estimated_total: { type: 'integer', description: 'Current estimate of total steps needed. Adjust as you learn more about the problem.', minimum: 1 }, purpose: { type: 'string', description: 'Category of this reasoning step. Standard values: analysis (examining information), action (taking an action), reflection (reviewing progress), decision (making a choice), summary (consolidating findings), validation (checking results), exploration (investigating options), hypothesis (forming theories), correction (fixing errors), planning (outlining approach). Custom strings allowed in flexible mode.' }, context: { type: 'string', description: 'What is already known or has been completed. Include relevant findings from previous steps to avoid redundant work.' }, thought: { type: 'string', description: 'Your current reasoning process. Express naturally - describe what you are thinking and why.' }, outcome: { type: 'string', description: 'The expected or actual result from this step. What did you learn or accomplish?' }, next_action: { oneOf: [ { type: 'string', description: 'Simple description of your next action' }, { type: 'object', description: 'Structured action with tool details', properties: { tool: { type: 'string', description: 'Name of tool to use' }, action: { type: 'string', description: 'Specific action to perform' }, parameters: { type: 'object', description: 'Parameters to pass to the tool' }, expectedOutput: { type: 'string', description: 'What you expect this action to return' } }, required: ['action'] } ], description: 'What you will do next. Can be a simple string or structured object with tool details.' }, rationale: { type: 'string', description: 'Why you chose this next action. Explain your reasoning for the approach.' }, // Completion is_final_step: { type: 'boolean', description: 'Set to true to explicitly mark this as the final reasoning step. The reasoning chain will be marked complete.' }, // Confidence tracking confidence: { type: 'number', description: 'Your confidence in this step (0-1 scale). Use lower values when uncertain: 0.3 = low confidence, 0.5 = moderate, 0.8+ = high confidence.', minimum: 0, maximum: 1 }, uncertainty_notes: { type: 'string', description: 'Describe specific uncertainties or doubts. What assumptions are you making? What could be wrong?' }, // Revision support revises_step: { type: 'integer', description: 'Step number you are revising or correcting. The original step will be marked as revised.', minimum: 1 }, revision_reason: { type: 'string', description: 'Why you are revising the earlier step. What was wrong or incomplete?' }, // Branching support branch_from: { type: 'integer', description: 'Step number to branch from for exploring an alternative approach. Creates a new solution path.', minimum: 1 }, branch_id: { type: 'string', description: 'Unique identifier for this branch. Auto-generated if not provided.' }, branch_name: { type: 'string', description: 'Human-readable name for this branch (e.g., "Alternative A: Use caching")' }, // Tool integration tools_used: { type: 'array', items: { type: 'string' }, description: 'List of tools you used during this step for tracking purposes.' }, external_context: { type: 'object', description: 'External data or tool outputs relevant to this step. Store important results here.' }, dependencies: { type: 'array', items: { type: 'integer' }, description: 'Step numbers this step depends on. Validated against existing steps in history.' }, // Session support session_id: { type: 'string', description: 'Session identifier for grouping related reasoning chains. Sessions expire after configured timeout.' } }, required: [ 'step_number', 'estimated_total', 'purpose', 'context', 'thought', 'outcome', 'next_action', 'rationale' ] } };
• src/index.ts:52-70 (registration)

  Registers the 'crash' tool in the MCP server: provides CRASH_TOOL in ListToolsResponse and routes CallTool requests for 'crash' to CrashServer.processStep.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [CRASH_TOOL], })); server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name === 'crash') { return crashServer.processStep(request.params.arguments); } return { content: [ { type: 'text', text: `Unknown tool: ${request.params.name}`, }, ], isError: true, }; });