MUTATION_TESTING
AgentThe agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…
**Navigation**: [Agents package rules](../AGENTS.md) → **Planning, execution and sub-agents**
Claude Code
$ npx -y skills add nodetool-ai/nodetool --agent claude-code
Cursor
Cursor also loads subagents from .claude/agents, so copy this file there to use it in Cursor.
**Navigation**: [Agents package rules](../AGENTS.md) → **Planning, execution and sub-agents**
Paths are relative to `packages/agents/` unless they name another package.
`create_plan` decomposes an objective into parallel tasks via `TaskPlanner.planMultiTask()`, and `execute_plan` runs them. Tasks form a DAG — independent tasks run concurrently.
1. **Planning**: LLM generates a `TaskPlan` with multiple `Task` objects, each with `dependsOn` arrays 2. **Scheduling**: `ParallelTaskExecutor` hands the tasks to `scheduleDag` (`utils/dag-scheduler.ts`), which starts a task the moment its last dependency settles. `TaskExecutor` schedules its steps the same way. 3. **Merging**: `createDynamicMerge()` interleaves the streams and admits a newly-started node into the running merge (`utils/merge-generators.ts`) 4. **Completion**: A task's result reaches shared memory and its terminal `task_update` is emitted before its dependents are released; the stream ends when every task has settled
Scheduling is event-driven, not round-based. The executors used to dispatch in barrier rounds — start every ready node, wait for the slowest, recompute — so a plan ran as slow as its slowest sibling in every round, and the cap on rounds per plan and per task turned depth into failure. Both caps are gone: what bounds the work is the run budget, `maxStepIterations` per step, and the permit pool. A cycle never reaches the scheduler (`PlanBuilder` rejects it), and a node nothing could ever run settles failed with `unsatisfiable dependency` rather than hanging.
The aggregation step is the finish step's dependency on every other step in the task, not a deferral rule: it runs last because it waits for its siblings, and a sibling that fails blocks it (I-5) instead of aggregating over a hole.
interface TaskPlan {
title: string;
tasks: Task[]; // Multiple tasks forming a DAG
}
interface Task {
id: string;
title: string;
steps: Step[];
dependsOn?: string[]; // Task IDs this depends on ([] = independent)
}
interface Step {
id: string;
instructions: string;
dependsOn: string[]; // Step IDs within this task
tools?: string[]; // Restrict available tools
outputSchema?: string; // JSON schema for step result
}`execute_plan` takes the tasks as its argument, so a caller that already knows the decomposition passes it straight in and never calls `create_plan`. The shape is the `TaskPlan` above with snake_case keys (`depends_on`), validated by `buildPlanFromTasks` (`tools/plan-builder-tools.ts`) before anything runs.
Two bounds are left, both in `constants.ts`, both read by `parallel-task-executor.ts` and `task-executor.ts` when a caller names none: `DEFAULT_MAX_STEP_ITERATIONS` (action rounds per step) and `DEFAULT_MAX_CONCURRENT_AGENTS`. The round caps that sat beside them are gone (see the scheduling note above); the rest of what bounds a run is `RunBudget` below.
Nothing resolves a per-run policy object: `execute_plan` passes the run's budget and the parent's per-step iteration cap directly.
`maxConcurrentAgents` bounds one merge numerically (tasks per plan, steps per task), not the run. The run-level bound is the budget's permit pool below, and a permit stands for one open provider conversation, not one layer: a task takes none, each step holds one through `branchPool` (`subagent.ts`), and a child a step or sub-agent spawns runs on its parent's permit while the parent is idle in the spawning call and borrows from the run pool beyond that. A holder never queues for a second permit, so nesting cannot deadlock, and one pool bounds tasks, steps and sub-agents together (`run-budget-propagation.test.ts`, "bounds every layer"). `start_subtask` refuses past `MAX_BACKGROUND_SUBTASKS_PER_TURN` (`tools/start-subtask-tool.ts`) with `background_limit_reached`; a detached child still on its parent's permit can overlap the parent's next turn. Planning draws on the same budget: `TaskPlanner` takes a `budget` (falling back to the context's) and a refused turn stops planning naming the budget's reason.
A run's bounds are one object, created by the host and shared downward, never re-created by a child. `RunBudget` carries four:
| Bound | What refuses | Setting | |---|---|---| | `turns` | a turn whose worst case would cross the USD cap | `NODETOOL_AGENT_TURN_COST_CAP_USD` | | `deadline` | any turn or tool call after the wall clock runs out | `NODETOOL_AGENT_TURN_DEADLINE_MS` | | `concurrency` | a permit past the run's pool — tasks, steps, nested executors and sub-agents all draw from it, a holder's own permit counting as one | `NODETOOL_AGENT_MAX_CONCURRENCY` | | `turnCount` | a turn past the run's cumulative total | `NODETOOL_AGENT_MAX_TURNS` |
Spend admission is reserve-then-commit, because the next call's cost is only known afterwards: $0.49 spent under a $0.50 cap still admits a $0.30 call. `turns.reserve` is the single admission point and records the first reason it refuses; `exhausted` is set once, so a run that ran out of money and then ran out of time stopped for the money.
**A reservation is a handle, because the budget is shared.** `turns.reserve` answers a `TurnReservationHandle` carrying that turn's own worst case and its own pricing (or `null` when it refused), and `turns.commit(handle, actualUsd)` settles exactly that one — every other loop's reservation stays outstanding. One shared counter released whatever was in flight, so a chat turn committing its turn handed a concurrent sub-agent's headroom back and the cap stopped holding; a single `unpriced` flag likewise booked whichever turn committed first under the other's pricing.
**An unpriced model is not a free one.** A model the price catalog does not cover has
Open-source AI film studio · agent + node workflows Direct AI films, shot by shot. Start with one sentence. The agent writes the story, draws a still for every shot, and cuts the clips on a timeline.
The agent package's pure, deterministic core (the chat permission gate, the control-tool plumbing, JSON extraction, and the…
**Navigation**: [Agents package rules](../AGENTS.md) → **Capabilities and tool sources**
**Navigation**: [Agents package rules](../AGENTS.md) → **Running Agents from CLI**
**Navigation**: [Agents package rules](../AGENTS.md) → **CodeAct Execution**
**Navigation**: [Agents package rules](../AGENTS.md) → **Eval suites**
**Navigation**: [Agents package rules](../AGENTS.md) → **Graph authoring**
Agent for managing AI prompts on prompts.chat - search, save, improve, and organize your prompt library.
정밀(strict) 모드 1단계 진단 에이전트. 글 전체를 한 번에 보고 "가장 지배적인 AI 티 패턴 3~6개"를 taxonomy ID와 함께 진단한다. 불안정한 span 열거(0↔18개로 요동) 대신 "무엇이 이 글을…
Topic Clusters curator for the Claude Blog Brain. Maintains and answers from the Topic Clusters theme of the brain, grounded in…
Optional gallery research helper. Use when a caller wants to find references, explore styles, build a mood board, or needs…