cleveragents/cleveragents-core

Fork 3

UAT: `RouteDefinition.detect_cycles()` returns incomplete cycle path — only last node appended, not full cycle #4819

New issue

Open

opened 2026-04-08 19:42:21 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 19:42:21 +00:00

Owner

Bug Report

Feature Area: Actor System — Actor YAML configuration schema, graph validation
Severity: Medium — cycle detection works (cycles are rejected) but error messages are misleading and incomplete
Found by: UAT tester instance uat-tester-actor-system
Spec reference: docs/specification.md §Graph Validation (line 20576)

What Was Tested

Code-level analysis of src/cleveragents/actor/schema.py — RouteDefinition.detect_cycles() (lines 621–657) and its usage in ActorConfigSchema.validate_type_requirements() (lines 843–853).

Expected Behavior (from spec)

The spec (line 20576) states:

The graph must be acyclic — cycles are detected via DFS and rejected at validation time.

When a cycle is detected, the error message should clearly identify all nodes involved in the cycle so developers can understand and fix the issue. For example, if nodes A → B → C → A form a cycle, the error should report [A, B, C] or A → B → C → A.

Actual Behavior (from code)

RouteDefinition.detect_cycles() at src/cleveragents/actor/schema.py:621–657:

def detect_cycles(self) -> list[str]:
    """
    Detect cycles in the graph using DFS.

    Returns:
        List of node IDs involved in cycles (empty if acyclic)
    """
    # Build adjacency list
    graph: dict[str, list[str]] = {node.id: [] for node in self.nodes}
    for edge in self.edges:
        graph[edge.from_node].append(edge.to_node)

    # DFS cycle detection
    visited: set[str] = set()
    rec_stack: set[str] = set()
    cycle_nodes: list[str] = []

    def dfs(node: str) -> bool:
        visited.add(node)
        rec_stack.add(node)

        for neighbor in graph.get(node, []):
            if neighbor not in visited:
                if dfs(neighbor):
                    return True
            elif neighbor in rec_stack:
                cycle_nodes.append(neighbor)  # ← BUG: only appends the LAST node
                return True

        rec_stack.remove(node)
        return False

    for node in graph:
        if node not in visited and dfs(node):
            break

    return cycle_nodes

The bug: When a cycle is detected (neighbor in rec_stack), only neighbor (the node where the cycle closes) is appended to cycle_nodes. The full cycle path (all nodes between neighbor and the current DFS position) is NOT captured.

For a cycle A → B → C → A:

When DFS reaches A again from C, only A is appended to cycle_nodes
The returned list is ["A"] instead of ["A", "B", "C"] or ["A → B → C → A"]

This produces a misleading error message in validate_type_requirements():

cycles = self.route.detect_cycles()
if cycles:
    nodes_str = " → ".join(cycles)
    msg = (
        f"route: graph contains a cycle involving "
        f"nodes: [{nodes_str}]. "
        f"Hint: remove or redirect edges to break the cycle."
    )
    raise ValueError(msg)

For a 3-node cycle, the error would say:

route: graph contains a cycle involving nodes: [A]. Hint: remove or redirect edges to break the cycle.

Instead of the expected:

route: graph contains a cycle involving nodes: [A → B → C]. Hint: remove or redirect edges to break the cycle.

Steps to Reproduce

from cleveragents.actor.schema import RouteDefinition, NodeDefinition, EdgeDefinition, NodeType

route = RouteDefinition(
    nodes=[
        NodeDefinition(id="a", type=NodeType.AGENT, name="A", description="Node A"),
        NodeDefinition(id="b", type=NodeType.AGENT, name="B", description="Node B"),
        NodeDefinition(id="c", type=NodeType.AGENT, name="C", description="Node C"),
    ],
    edges=[
        EdgeDefinition(from_node="a", to_node="b"),
        EdgeDefinition(from_node="b", to_node="c"),
        EdgeDefinition(from_node="c", to_node="a"),  # Creates cycle
    ],
    entry_node="a",
    exit_nodes=["c"],
)

cycles = route.detect_cycles()
print(cycles)  # Prints: ["a"] — only the cycle-closing node, not the full path
# Expected: ["a", "b", "c"] or similar full cycle representation

Code Location

src/cleveragents/actor/schema.py:621–657 — RouteDefinition.detect_cycles()
src/cleveragents/actor/schema.py:843–853 — ActorConfigSchema.validate_type_requirements() (uses the incomplete cycle list)
src/cleveragents/actor/compiler.py:263–265 — compile_actor() (also uses the incomplete cycle list)

Expected Fix

The detect_cycles() method should capture the full cycle path. One approach:

def detect_cycles(self) -> list[str]:
    graph: dict[str, list[str]] = {node.id: [] for node in self.nodes}
    for edge in self.edges:
        graph[edge.from_node].append(edge.to_node)

    visited: set[str] = set()
    rec_stack: list[str] = []  # Use list to track path order
    rec_set: set[str] = set()
    cycle_path: list[str] = []

    def dfs(node: str) -> bool:
        visited.add(node)
        rec_stack.append(node)
        rec_set.add(node)

        for neighbor in graph.get(node, []):
            if neighbor not in visited:
                if dfs(neighbor):
                    return True
            elif neighbor in rec_set:
                # Found cycle: extract the cycle path from rec_stack
                cycle_start = rec_stack.index(neighbor)
                cycle_path.extend(rec_stack[cycle_start:])
                return True

        rec_stack.pop()
        rec_set.discard(node)
        return False

    for node in graph:
        if node not in visited and dfs(node):
            break

    return cycle_path

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** Actor System — Actor YAML configuration schema, graph validation **Severity:** Medium — cycle detection works (cycles are rejected) but error messages are misleading and incomplete **Found by:** UAT tester instance `uat-tester-actor-system` **Spec reference:** `docs/specification.md` §Graph Validation (line 20576) --- ### What Was Tested Code-level analysis of `src/cleveragents/actor/schema.py` — `RouteDefinition.detect_cycles()` (lines 621–657) and its usage in `ActorConfigSchema.validate_type_requirements()` (lines 843–853). ### Expected Behavior (from spec) The spec (line 20576) states: > The graph must be **acyclic** — cycles are detected via DFS and rejected at validation time. When a cycle is detected, the error message should clearly identify **all nodes involved in the cycle** so developers can understand and fix the issue. For example, if nodes A → B → C → A form a cycle, the error should report `[A, B, C]` or `A → B → C → A`. ### Actual Behavior (from code) `RouteDefinition.detect_cycles()` at `src/cleveragents/actor/schema.py:621–657`: ```python def detect_cycles(self) -> list[str]: """ Detect cycles in the graph using DFS. Returns: List of node IDs involved in cycles (empty if acyclic) """ # Build adjacency list graph: dict[str, list[str]] = {node.id: [] for node in self.nodes} for edge in self.edges: graph[edge.from_node].append(edge.to_node) # DFS cycle detection visited: set[str] = set() rec_stack: set[str] = set() cycle_nodes: list[str] = [] def dfs(node: str) -> bool: visited.add(node) rec_stack.add(node) for neighbor in graph.get(node, []): if neighbor not in visited: if dfs(neighbor): return True elif neighbor in rec_stack: cycle_nodes.append(neighbor) # ← BUG: only appends the LAST node return True rec_stack.remove(node) return False for node in graph: if node not in visited and dfs(node): break return cycle_nodes ``` **The bug**: When a cycle is detected (`neighbor in rec_stack`), only `neighbor` (the node where the cycle closes) is appended to `cycle_nodes`. The full cycle path (all nodes between `neighbor` and the current DFS position) is NOT captured. For a cycle `A → B → C → A`: - When DFS reaches `A` again from `C`, only `A` is appended to `cycle_nodes` - The returned list is `["A"]` instead of `["A", "B", "C"]` or `["A → B → C → A"]` This produces a misleading error message in `validate_type_requirements()`: ```python cycles = self.route.detect_cycles() if cycles: nodes_str = " → ".join(cycles) msg = ( f"route: graph contains a cycle involving " f"nodes: [{nodes_str}]. " f"Hint: remove or redirect edges to break the cycle." ) raise ValueError(msg) ``` For a 3-node cycle, the error would say: ``` route: graph contains a cycle involving nodes: [A]. Hint: remove or redirect edges to break the cycle. ``` Instead of the expected: ``` route: graph contains a cycle involving nodes: [A → B → C]. Hint: remove or redirect edges to break the cycle. ``` ### Steps to Reproduce ```python from cleveragents.actor.schema import RouteDefinition, NodeDefinition, EdgeDefinition, NodeType route = RouteDefinition( nodes=[ NodeDefinition(id="a", type=NodeType.AGENT, name="A", description="Node A"), NodeDefinition(id="b", type=NodeType.AGENT, name="B", description="Node B"), NodeDefinition(id="c", type=NodeType.AGENT, name="C", description="Node C"), ], edges=[ EdgeDefinition(from_node="a", to_node="b"), EdgeDefinition(from_node="b", to_node="c"), EdgeDefinition(from_node="c", to_node="a"), # Creates cycle ], entry_node="a", exit_nodes=["c"], ) cycles = route.detect_cycles() print(cycles) # Prints: ["a"] — only the cycle-closing node, not the full path # Expected: ["a", "b", "c"] or similar full cycle representation ``` ### Code Location - `src/cleveragents/actor/schema.py:621–657` — `RouteDefinition.detect_cycles()` - `src/cleveragents/actor/schema.py:843–853` — `ActorConfigSchema.validate_type_requirements()` (uses the incomplete cycle list) - `src/cleveragents/actor/compiler.py:263–265` — `compile_actor()` (also uses the incomplete cycle list) ### Expected Fix The `detect_cycles()` method should capture the full cycle path. One approach: ```python def detect_cycles(self) -> list[str]: graph: dict[str, list[str]] = {node.id: [] for node in self.nodes} for edge in self.edges: graph[edge.from_node].append(edge.to_node) visited: set[str] = set() rec_stack: list[str] = [] # Use list to track path order rec_set: set[str] = set() cycle_path: list[str] = [] def dfs(node: str) -> bool: visited.add(node) rec_stack.append(node) rec_set.add(node) for neighbor in graph.get(node, []): if neighbor not in visited: if dfs(neighbor): return True elif neighbor in rec_set: # Found cycle: extract the cycle path from rec_stack cycle_start = rec_stack.index(neighbor) cycle_path.extend(rec_stack[cycle_start:]) return True rec_stack.pop() rec_set.discard(node) return False for node in graph: if node not in visited and dfs(node): break return cycle_path ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 19:46:08 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 19:59:07 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:12:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:16:04 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:22:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added the

labels

2026-04-08 23:00:06 +00:00

HAL9000 commented

2026-04-09 03:03:00 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:03:02 +00:00

HAL9000 added this to the v3.5.0 milestone