MCP Dual-Cycle Reasoner

Instructions

Implementation Reference

• src/server.ts:342-383 (handler)

  The execute function of the process_trace_update tool handler. It validates input using MonitorCognitiveTraceInputSchema, delegates to DualCycleEngine.processTraceUpdate, reports progress, and returns the result as JSON.

  execute: async (args, { log, reportProgress, session }) => {
    try {
      const sessionEngine = this.getSessionEngine(session);
      const sessionId = this.sessionIds.get(session);
      const validatedArgs = MonitorCognitiveTraceInputSchema.parse(args);
  
      log.info('Processing trace update', {
        lastAction: validatedArgs.last_action,
        context: validatedArgs.current_context,
        goal: validatedArgs.goal,
        sessionId,
      });
  
      await reportProgress({ progress: 0, total: 3 });
  
      const result = await sessionEngine.processTraceUpdate(
        validatedArgs.last_action,
        validatedArgs.current_context,
        validatedArgs.goal,
        validatedArgs.window_size
      );
  
      await reportProgress({ progress: 3, total: 3 });
  
      log.info('Trace update processed', {
        loopDetected: result.loop_detected,
        interventionRequired: result.intervention_required,
      });
  
      if (result.loop_detected) {
        result.loop_detected.confidence = parseFloat(
          result.loop_detected.confidence.toFixed(2)
        );
      }
  
      return JSON.stringify(result, null, 2);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      log.error('Failed to process trace update', { error: errorMessage });
      throw new UserError(`Failed to process trace update: ${errorMessage}`);
    }
  },

• src/types.ts:136-141 (schema)

  Zod schema for validating inputs to the process_trace_update tool, used in the handler for parsing arguments.

  export const MonitorCognitiveTraceInputSchema = z.object({
    last_action: z.string().describe(DESCRIPTIONS.LAST_ACTION),
    current_context: z.string().optional().describe(DESCRIPTIONS.CURRENT_CONTEXT),
    goal: z.string().describe(DESCRIPTIONS.GOAL),
    window_size: z.number().default(10),
  });

• src/server.ts:321-385 (registration)

  Registration of the process_trace_update tool via FastMCP server's addTool method within addProcessTraceUpdateTool().

    this.server.addTool({
      name: 'process_trace_update',
      description: 'Process a cognitive trace update from the agent (main monitoring function)',
      parameters: z.object({
        last_action: z.string().describe(DESCRIPTIONS.LAST_ACTION),
        current_context: z
          .string()
          .optional()
          .describe(
            `${DESCRIPTIONS.CURRENT_CONTEXT}, in low dash format. Example: adding_product_item`
          ),
        goal: z.string().describe(DESCRIPTIONS.GOAL),
        window_size: z.number().optional().default(10).describe(DESCRIPTIONS.WINDOW_SIZE),
      }),
      annotations: {
        title: 'Process Cognitive Trace Update',
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
      execute: async (args, { log, reportProgress, session }) => {
        try {
          const sessionEngine = this.getSessionEngine(session);
          const sessionId = this.sessionIds.get(session);
          const validatedArgs = MonitorCognitiveTraceInputSchema.parse(args);
  
          log.info('Processing trace update', {
            lastAction: validatedArgs.last_action,
            context: validatedArgs.current_context,
            goal: validatedArgs.goal,
            sessionId,
          });
  
          await reportProgress({ progress: 0, total: 3 });
  
          const result = await sessionEngine.processTraceUpdate(
            validatedArgs.last_action,
            validatedArgs.current_context,
            validatedArgs.goal,
            validatedArgs.window_size
          );
  
          await reportProgress({ progress: 3, total: 3 });
  
          log.info('Trace update processed', {
            loopDetected: result.loop_detected,
            interventionRequired: result.intervention_required,
          });
  
          if (result.loop_detected) {
            result.loop_detected.confidence = parseFloat(
              result.loop_detected.confidence.toFixed(2)
            );
          }
  
          return JSON.stringify(result, null, 2);
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          log.error('Failed to process trace update', { error: errorMessage });
          throw new UserError(`Failed to process trace update: ${errorMessage}`);
        }
      },
    });
  }

• src/dual-cycle-engine.ts:84-149 (helper)

  Core helper method in DualCycleEngine that implements the metacognitive monitoring logic: accumulates actions, detects loops via sentinel.detectLoop, and determines if intervention is required.

  async processTraceUpdate(
    lastAction: string,
    currentContext?: string,
    goal?: string,
    windowSize?: number
  ): Promise<{
    intervention_required: boolean;
    loop_detected?: LoopDetectionResult;
    explanation?: string;
  }> {
    if (!this.isMonitoring) {
      return { intervention_required: false };
    }
  
    // Add the new action to the accumulated actions
    this.accumulatedActions.push(lastAction);
    this.currentTrace.last_action = lastAction;
  
    console.log(
      `🔍 DEBUG: Added action "${lastAction}" to accumulated actions. Total: ${this.accumulatedActions.length}`
    );
  
    // Update other trace properties if provided
    if (currentContext) {
      this.currentTrace.current_context = currentContext;
    }
    if (goal) {
      this.currentTrace.goal = goal;
    }
  
    console.log(
      chalk.gray(
        `\n📊 Processing trace update: Added "${lastAction}" (${this.accumulatedActions.length} total actions)`
      )
    );
  
    // METACOGNITIVE CYCLE - Phase 1: MONITOR
    const loopDetection = await this.monitorForLoops(this.currentTrace, windowSize ?? 10);
  
    if (!loopDetection.detected) {
      console.log(chalk.green('✅ No loops detected - cognitive cycle proceeding normally'));
      return {
        intervention_required: false,
        loop_detected: loopDetection,
      };
    }
  
    console.log(
      chalk.yellow(
        `⚠️  Loop detected: ${loopDetection.type} (confidence: ${(loopDetection.confidence * 100).toFixed(1)}%)`
      )
    );
    console.log(chalk.yellow(`   Details: ${loopDetection.details}`));
  
    this.interventionCount++;
  
    const explanation = this.generateInterventionExplanation(loopDetection);
  
    console.log(chalk.cyan(`\n💡 Intervention #${this.interventionCount}: ${explanation}`));
  
    return {
      intervention_required: true,
      loop_detected: loopDetection,
      explanation,
    };
  }