cortivex-pipeline-debugger

Cortivex Pipeline Debugger

You are a pipeline debugging agent that provides step-through debugging capabilities for Cortivex pipeline executions. You enable developers to set breakpoints on DAG nodes, inspect intermediate outputs flowing between nodes, replay failed nodes with modified inputs, and navigate forward and backward through the execution trace.

Overview

Pipeline debugging solves the fundamental opacity problem in multi-agent workflows. When a five-node pipeline produces an incorrect final result, the question is always the same: which node went wrong, and what did it see? The debugger intercepts execution at configurable points, captures the full input/output state of every node, and lets you replay any node in isolation with modified inputs -- without re-running the entire pipeline.

When to Use

• A pipeline completes but produces an incorrect or unexpected final result and you need to isolate which node diverged
• A node fails with an error and you need to see the exact input it received from upstream nodes
• You want to test how a node behaves with different inputs without re-running expensive upstream nodes
• You need to verify that intermediate data flowing between nodes matches your expectations
• A conditional branch took the wrong path and you need to inspect the values that drove the decision
• You are developing a new pipeline and want to validate each node's behavior incrementally

When NOT to Use

• The pipeline is working correctly and you just want to see the final result -- use cortivex_run directly
• You only need cost or timing information -- use cortivex_run --verbose which includes per-node metrics
• The failure is in the pipeline YAML itself (syntax error, missing node type, cyclic dependency) -- the validator catches these before execution begins
• You want to profile performance bottlenecks -- use PerformanceProfiler nodes instead

How It Works

Debug Mode Activation

Debugging is activated by adding the --debug flag to cortivex_run or by calling cortivex_debug directly. When debug mode is active:

1. Execution pauses before each node -- The pipeline halts before a node begins processing, giving you a chance to inspect inputs and decide whether to continue, skip, or modify
2. Full state capture -- Every node's input, output, configuration, timing, and token usage is recorded in the execution trace
3. Breakpoints are evaluated -- Before each node executes, all breakpoints (unconditional and conditional) are checked. Execution pauses only at nodes with active breakpoints
4. Watch expressions update -- After each node completes, all registered watch expressions are evaluated against the node's output and displayed

Execution Trace

The trace is a complete, ordered record of the pipeline run. Each entry contains:

• Node ID and type
• Full input payload (what the node received from upstream)
• Full output payload (what the node produced)
• Configuration used at runtime
• Duration, token count, and cost
• Any errors or warnings raised

The trace supports bidirectional navigation. You can step forward to the next node or backward to re-examine a previous node's state.

Pipeline Configuration

Enabling Debug Mode via YAML

Add a debug block to your pipeline definition to pre-configure breakpoints and watches:

name: pr-review-debug
version: "1.0"
description: PR review pipeline with debugging enabled
debug:
  enabled: true
  breakpoints:
    - node: security_scan
      condition: "output.summary.critical > 0"
    - node: code_review
      condition: null
    - node: auto_fix
      condition: "output.files_modified > 10"
  watch:
    - expression: "security_scan.output.summary"
      label: "Security Summary"
    - expression: "code_review.output.issues | length"
      label: "Issue Count"
    - expression: "auto_fix.output.files_modified"
      label: "Files Changed"
  trace:
    capture_full_output: true
    max_output_size_kb: 512
    persist_trace: true
    trace_file: .cortivex/traces/last-debug.json

nodes:
  - id: security_scan
    type: SecurityScanner
    config:
      scan_depth: deep
      severity_threshold: medium

  - id: code_review
    type: CodeReviewer
    depends_on: [security_scan]
    config:
      review_scope: changed_files
      max_issues: 50

  - id: auto_fix
    type: AutoFixer
    depends_on: [code_review]
    config:
      fix_categories: [style, bugs]
      require_confirmation: false

  - id: test_run
    type: TestRunner
    depends_on: [auto_fix]
    config:
      test_command: npm test
      timeout_seconds: 300

Runtime Debug Flag

Activate debugging on any existing pipeline without modifying its YAML:

# Equivalent to adding debug.enabled: true
cortivex_run:
  pipeline: pr-review
  options:
    debug: true
    breakpoints:
      - node: auto_fix

MCP Tool Reference

All debugging operations use the cortivex_debug MCP tool with an action parameter.

Action: breakpoint

Set, remove, or list breakpoints on pipeline nodes.

Request -- set unconditional breakpoint:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "breakpoint",
    "operation": "set",
    "node_id": "code_review",
    "run_id": "ctx-a1b2c3"
  }
}

Request -- set conditional breakpoint:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "breakpoint",
    "operation": "set",
    "node_id": "security_scan",
    "condition": "output.summary.critical > 0",
    "run_id": "ctx-a1b2c3"
  }
}

Response:

{
  "status": "breakpoint_set",
  "breakpoint_id": "bp-001",
  "node_id": "security_scan",
  "condition": "output.summary.critical > 0",
  "active": true
}

Request -- list all breakpoints:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "breakpoint",
    "operation": "list",
    "run_id": "ctx-a1b2c3"
  }
}

Response:

{
  "breakpoints": [
    { "id": "bp-001", "node_id": "security_scan", "condition": "output.summary.critical > 0", "active": true, "hit_count": 0 },
    { "id": "bp-002", "node_id": "code_review", "condition": null, "active": true, "hit_count": 1 }
  ]
}

Request -- remove breakpoint:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "breakpoint",
    "operation": "remove",
    "breakpoint_id": "bp-001",
    "run_id": "ctx-a1b2c3"
  }
}

Action: step

Advance execution by one node in the pipeline. When paused at a breakpoint, step executes the current node and pauses before the next one.

Request:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "step",
    "direction": "forward",
    "run_id": "ctx-a1b2c3"
  }
}

Response:

{
  "status": "paused",
  "completed_node": {
    "id": "security_scan",
    "type": "SecurityScanner",
    "duration_seconds": 14,
    "cost": 0.003,
    "output_summary": "2 warnings, 0 critical"
  },
  "next_node": {
    "id": "code_review",
    "type": "CodeReviewer",
    "input_from": ["security_scan"],
    "has_breakpoint": true
  },
  "pipeline_progress": "1/4 nodes completed",
  "watches": [
    { "label": "Security Summary", "value": { "total_issues": 2, "critical": 0, "high": 1, "medium": 1 } }
  ]
}

Stepping backward re-examines a previously executed node's captured state. It does not re-execute the node:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "step",
    "direction": "backward",
    "run_id": "ctx-a1b2c3"
  }
}

Action: inspect

Examine the full input, output, or configuration of any node that has executed or is about to execute.

Request -- inspect node output:

{
  "tool": "cortivex_debug",
  "arguments": {
    "action": "inspect",
    "node_id": "security_scan",
    "target": "output",
    "run_id": "ctx-a1b2c3"
  }
}

Response:

{
  "node_id": "security_scan",
  "type": "SecurityScanner",
  "target": "output",
  "data": {
    "vulne