configurable-tree-traversal

Dependency-aware building blocks for autonomous-agent workflows, plus general tree and DAG traversal for TypeScript and JavaScript.

Give CTT a graph of work and accepted completion facts. It determines what can run next, enforces work and structural-completion dependencies, and exposes progress without executing business work. Your host chooses agents, dispatches tasks, accepts results, and persists state.

Documentation map · Agent workflow guide · API reference · npm

Start with autonomous agents

| You want to… | Use CTT for… | Start here | | --- | --- | --- | | Coordinate research, implementation, testing, and review agents | Parallel branches and dependency joins | Quickstart | | Let a coordinator choose which agents run next | Deferred work and a readable ready frontier | Host-controlled execution | | Resume after a process restart or wait for human input | Reconstruction from accepted completion facts | Recovery and storage | | Review a composite task only after all its subtasks finish | dependsOnComplete | Work versus completion | | Fetch dependencies from a task catalog or service | resolvePrerequisite(id) | Discover prerequisites | | Walk or transform a repository index, AST, or JSON object | Iterative sync/async DFS, BFS, pruning, rewriting | Tree and object traversal |

CTT is an in-memory traversal engine. The host owns workflow meaning, agent/tool execution, claims, retries, timeouts, business outcomes, and durable storage. It can use SQLite, another database, or another storage provider without a CTT storage dependency.

Install

npm install configurable-tree-traversal

Current release: 0.11.0. Requires Node 22.12.0+, or Bun 1.4.4. CI covers the minimum Node runtime, current Node 22/24, and Bun. TypeScript consumers are checked with 4.7.4 and 4.9.5.

Quickstart: find the next agent tasks

After research completes, implement and testPlan can run independently. review waits for both. The catalog is flat; $c discovers tasks and dependsOn expresses the work graph.

research ──┬── implement ──┬── review
           └── testPlan ───┘

import {
  DagTraversal,
  DagTraversalOrder,
  DEFER_READY,
  type TreeTypeParameters,
} from 'configurable-tree-traversal';

type Workflow = TreeTypeParameters<string, string>;
const dependencies: Record<string, string[]> = {
  research: [],
  implement: ['research'],
  testPlan: ['research'],
  review: ['implement', 'testPlan'],
};
// In-memory stand-in for completion facts already accepted by your host.
const accepted = new Set(['research']);
function reconstruct() {
  const traversal = new DagTraversal<Workflow>({
    discovery: 'eager',
    syntheticRoot: true,
    completedWork: accepted,
    traversableGraph: {
      makeRoot: () => ({
        vertexContent: { $d: '', $c: Object.keys(dependencies) },
      }),
      makeVertex: (id) => ({
        vertexId: id,
        dependsOn: dependencies[id]!,
        vertexContent: { $d: id, $c: [] },
      }),
    },
  });
  traversal.addVisitorFor(DagTraversalOrder.ON_READY, () => DEFER_READY);
  return traversal.makeRunner().run();
}

const runner = reconstruct();
const snapshot = runner.summary();
console.log(snapshot.readyIds); // ['implement', 'testPlan']

The sole ON_READY visitor returns DEFER_READY, so run() discovers and validates the graph, then halts with eligible work still incomplete. A no-op visitor would mark work complete; summary() alone does not discover the graph. readyIds is dependency readiness, not a claim or evidence that an external agent is idle.

The host can now claim a candidate, dispatch an agent, validate and persist its result, and either settle the retained runner or reconstruct on the next tick. See the workflow guide and the executable example, which also checks settlement, duplicate reports, and restart reconstruction. The example uses an in-memory set; production durability belongs to the host.

Choose your next page

• Integrating an agent coordinator: Agent workflows, including execution models, persistence, retries, and common mistakes.
• Looking up a contract: API and behavior reference, including tree traversal, commands, identity, errors, and async semantics.
• Finding runnable code or source: Documentation index.
• Changing CTT: Repository agent guide and testing guide.
• Checking releases: Changelog.

Imports and compatibility

import { DagTraversal, DEFER_READY } from 'configurable-tree-traversal';

const { DagTraversal, DEFER_READY } = require('configurable-tree-traversal');

Native ESM .mjs entries and .d.mts declarations share one CommonJS implementation and canonical types. Named/default imports, classes, namespaces, and DEFER_READY preserve identity across loaders. ESM entries use Node-compatible createRequire; standalone browser ESM and tree shaking are not promised. Public subpaths and historical deep imports remain supported; see compatibility details.

Reference shortcuts

Existing README section links land here; each topic now has a dedicated location in the reference.

| Topic | Detailed guidance | | --- | --- | | DAG traversal | Read section | | Discovery and execution as separate phases | Read section | | Discovery and completed work | Read section | | Deferred DAG progress and reconciliation | Read section | | Host policy and traversal feedback | Read section | | Traverse an object | Read section | | Abstract trees | Read section | | Traversal orders | Read section | | Breadth-first traversal | Read section | | Async traversal | Read section | | Visitors and commands | Read section | | Pause and resume | Read section | | Inspection and execution | Read section | | Rewrite objects | Read section | | API compatibility | Read section | | Development | Read section |

MIT licensed.