Struct TaskGraph 

pub struct TaskGraph { /* private fields */ }

A directed acyclic graph (DAG) of TaskNodes.

Invariants (enforced by add_task)

1. Every node ID is unique.
2. Every referenced dependency ID must already exist in the graph.
3. No cycles — checked by running Kahn’s algorithm after every insert.

Storage

Nodes are stored in a Vec (preserving insertion order) together with an ID→index map for O(1) lookups. The dependency lists are the adjacency representation; we build a reverse map on demand for algorithms that need it.

Implementations

impl TaskGraph

pub fn new() -> Self

Create an empty graph.

pub fn add_task(&mut self, node: TaskNode) -> Result<()>

Add a new task node to the graph.

Errors

• Duplicate ID
• Unknown dependency ID (must be added before the dependent node)
• Cycle detection (added after all edges are registered)

pub fn mark_running(&mut self, id: &str) -> Result<()>

Mark a task as Running.

Errors

• Task ID not found
• Task is not in Pending state (can only start from Pending)

pub fn mark_completed(&mut self, id: &str, result: AgentResult) -> Result<()>

Mark a task as successfully Completed and store its result.

Errors

• Task ID not found

pub fn mark_failed(&mut self, id: &str, error: String) -> Result<()>

Mark a task as Failed.

The retries counter in the Failed variant is initialised to 0 if the task was previously Pending/Running, or incremented if it was already Failed (i.e. this is a retry that also failed).

Errors

• Task ID not found

pub fn mark_cancelled(&mut self, id: &str) -> Result<()>

Mark a task as Cancelled.

Errors

• Task ID not found

pub fn reset_for_retry(&mut self, id: &str) -> Result<()>

Reset a failed task back to Pending so it can be retried.

The executor calls this before re-queueing a Failed task.

Errors

• Task ID not found
• Task is not in Failed state

pub fn nodes(&self) -> impl Iterator<Item = &TaskNode>

Returns an iterator over all nodes in insertion order.

pub fn len(&self) -> usize

Returns the number of nodes in the graph.

pub fn is_empty(&self) -> bool

Returns true if the graph has no nodes.

pub fn get(&self, id: &str) -> Option<&TaskNode>

Look up a node by ID. Returns None if not found.

pub fn topological_sort(&self) -> Result<Vec<String>>

Topological sort using Kahn’s BFS algorithm.

Returns a linearised ordering of all task IDs such that every task appears after all of its dependencies. If multiple orderings are valid (i.e. there are independent tasks), the result is deterministic but arbitrary — use compute_waves to get explicit parallel batches.

Errors

Returns an error if a cycle is detected (should not happen if nodes were added via add_task, which validates on insert).

pub fn compute_waves(&self) -> Result<Vec<Vec<String>>>

Compute parallel execution waves.

A “wave” is a group of tasks that:

1. Have all dependencies in earlier waves (so they can run immediately once the previous wave finishes), AND
2. Are independent of each other within the wave (no edge between them).

This is the critical function for “完全安全托管” — the executor uses these waves to maximise concurrency: it runs all tasks in wave 0 in parallel, waits for all to complete, then runs wave 1 in parallel, etc.

Algorithm: assign each node a “wave number” = 1 + max(wave numbers of its dependencies). Nodes with no dependencies get wave 0. This is a standard “longest path in a DAG” computation.

Returns

A Vec<Vec<String>> where:

• result[0] = IDs of tasks that can run immediately (no deps)
• result[1] = IDs of tasks whose deps are all in result[0]
• …and so on

Errors

Propagates any cycle error from topological_sort.

pub fn next_ready(&self) -> Vec<&TaskNode>

Returns all tasks that are currently eligible to run.

A task is “ready” when:

• Its status is Pending, AND
• Every task in depends_on has status Completed.

The executor calls this after each task completes to find new tasks to dispatch.

pub fn is_finished(&self) -> bool

Returns true when every node in the graph is in a terminal state.

The executor uses this as its loop termination condition.

pub fn is_all_completed(&self) -> bool

Returns true when every node has status Completed.

pub fn status_counts(&self) -> (usize, usize, usize, usize, usize)

Counts tasks by status category (for progress display).

Returns (pending, running, completed, failed, cancelled).

impl TaskGraph

pub fn rebuild_index(&mut self)

Rebuild the id_to_index map after deserialisation.

serde skips id_to_index (marked #[serde(skip)]) so we must rebuild it when loading a saved graph. Call this immediately after deserialising:

let mut graph: TaskGraph = serde_json::from_str(&json)?;
graph.rebuild_index();

Trait Implementations

impl Debug for TaskGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TaskGraph

fn default() -> TaskGraph

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for TaskGraph

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for TaskGraph

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.