ExecutionTree

Defined in: core/execution-tree.ts:225

The Execution Tree - single source of truth for all execution state.

Features:

• Stores all nodes (LLM calls, gadgets) in a hierarchical structure
• Emits events on mutations
• Provides query methods for aggregation (costs, media, descendants)
• Supports single shared tree model for nested subagents

Example

const tree = new ExecutionTree();

// Add root LLM call
const llmNode = tree.addLLMCall({ iteration: 1, model: "sonnet" });

// Add gadget under the LLM call
const gadgetNode = tree.addGadget({
  invocationId: "gc_1",
  name: "ReadFile",
  parameters: { path: "/foo.txt" },
  parentId: llmNode.id,
});

// Complete the gadget
tree.completeGadget(gadgetNode.id, { result: "file contents", executionTimeMs: 50 });

// Query total cost
console.log(tree.getTotalCost());

Constructors

Constructor

new ExecutionTree(options?): ExecutionTree

Defined in: core/execution-tree.ts:249

Parameters

options?

baseDepth?

number

parentNodeId?

string | null

Returns

ExecutionTree

Properties

baseDepth

readonly baseDepth: number

Defined in: core/execution-tree.ts:241

Base depth for all nodes in this tree. Used when this tree is a subagent’s view into a parent tree.

---

parentNodeId

readonly parentNodeId: string | null

Defined in: core/execution-tree.ts:247

Parent node ID for subagent trees. All root nodes in this tree will have this as their parentId.

Methods

addGadget()

addGadget(params): GadgetNode

Defined in: core/execution-tree.ts:445

Add a new gadget node to the tree.

Parameters

params

AddGadgetParams

Returns

GadgetNode

---

addLLMCall()

addLLMCall(params): LLMCallNode

Defined in: core/execution-tree.ts:334

Add a new LLM call node to the tree.

Parameters

params

AddLLMCallParams

Returns

LLMCallNode

---

appendLLMResponse()

appendLLMResponse(nodeId, chunk): void

Defined in: core/execution-tree.ts:381

Add text to an LLM call’s response (for streaming).

Parameters

nodeId

string

chunk

string

Returns

void

---

complete()

complete(): void

Defined in: core/execution-tree.ts:940

Mark the tree as complete (no more events will be emitted).

Returns

void

---

completeGadget()

completeGadget(nodeId, params): void

Defined in: core/execution-tree.ts:514

Complete a gadget node successfully.

Parameters

nodeId

string

params

CompleteGadgetParams

Returns

void

---

completeLLMCall()

completeLLMCall(nodeId, params): void

Defined in: core/execution-tree.ts:399

Complete an LLM call node.

Parameters

nodeId

string

params

CompleteLLMCallParams

Returns

void

---

emitText()

emitText(content, llmCallNodeId): void

Defined in: core/execution-tree.ts:603

Emit a text event (notification only, not stored in tree).

Parameters

content

string

llmCallNodeId

string

Returns

void

---

events()

events(): AsyncGenerator<ExecutionEvent>

Defined in: core/execution-tree.ts:909

Get async iterable of all events. Events are yielded as they occur.

Returns

AsyncGenerator<ExecutionEvent>

---

failLLMCall()

failLLMCall(nodeId, error, recovered): void

Defined in: core/execution-tree.ts:425

Mark an LLM call as failed.

Parameters

nodeId

string

error

Error

recovered

boolean

Returns

void

---

getAncestors()

getAncestors(id): ExecutionNode[]

Defined in: core/execution-tree.ts:660

Get ancestors of a node (from root to parent).

Parameters

id

string

Returns

ExecutionNode[]

---

getChildren()

getChildren(id): ExecutionNode[]

Defined in: core/execution-tree.ts:649

Get children of a node.

Parameters

id

string

Returns

ExecutionNode[]

---

getCurrentLLMCallId()

getCurrentLLMCallId(): string | undefined

Defined in: core/execution-tree.ts:705

Get the current (most recent incomplete) LLM call node.

Returns

string | undefined

---

getDescendants()

getDescendants(id, type?): ExecutionNode[]

Defined in: core/execution-tree.ts:681

Get all descendants of a node.

Parameters

id

string

type?

ExecutionNodeType

Returns

ExecutionNode[]

---

getNode()

getNode(id): ExecutionNode | undefined

Defined in: core/execution-tree.ts:623

Get a node by ID.

Parameters

id

string

Returns

ExecutionNode | undefined

---

getNodeByInvocationId()

getNodeByInvocationId(invocationId): GadgetNode | undefined

Defined in: core/execution-tree.ts:630

Get a gadget node by invocation ID.

Parameters

invocationId

string

Returns

GadgetNode | undefined

---

getNodeCount()

getNodeCount(): object

Defined in: core/execution-tree.ts:853

Get node counts.

Returns

object

gadgets

gadgets: number

llmCalls

llmCalls: number

---

getRoots()

getRoots(): ExecutionNode[]

Defined in: core/execution-tree.ts:640

Get all root nodes (depth 0 for this tree).

Returns

ExecutionNode[]

---

getSubtreeCost()

getSubtreeCost(nodeId): number

Defined in: core/execution-tree.ts:738

Get total cost for a subtree (node and all descendants).

Parameters

nodeId

string

Returns

number

---

getSubtreeMedia()

getSubtreeMedia(nodeId): GadgetMediaOutput[]

Defined in: core/execution-tree.ts:815

Collect all media from a subtree.

Parameters

nodeId

string

Returns

GadgetMediaOutput[]

---

getSubtreeTokens()

getSubtreeTokens(nodeId): object

Defined in: core/execution-tree.ts:788

Get token usage for a subtree.

Parameters

nodeId

string

Returns

object

cached

cached: number

input

input: number

output

output: number

---

getTotalCost()

getTotalCost(): number

Defined in: core/execution-tree.ts:723

Get total cost for entire tree.

Returns

number

---

getTotalTokens()

getTotalTokens(): object

Defined in: core/execution-tree.ts:766

Get token usage for entire tree.

Returns

object

cached

cached: number

input

input: number

output

output: number

---

isComplete()

isComplete(): boolean

Defined in: core/execution-tree.ts:952

Check if the tree is complete.

Returns

boolean

---

isSubtreeComplete()

isSubtreeComplete(nodeId): boolean

Defined in: core/execution-tree.ts:838

Check if a subtree is complete (all nodes finished).

Parameters

nodeId

string

Returns

boolean

---

on()

on(type, listener): () => void

Defined in: core/execution-tree.ts:886

Subscribe to events of a specific type. Returns unsubscribe function.

Parameters

type

ExecutionEventType

Event type to subscribe to (use ”*” for all events)

listener

EventListener

Callback function that receives matching events

Returns

Unsubscribe function

(): void

Returns

void

Example

const unsubscribe = tree.on("gadget_complete", (event) => {
  if (event.type === "gadget_complete") {
    console.log(`Gadget ${event.name} completed`);
  }
});

---

onAll()

onAll(listener): () => void

Defined in: core/execution-tree.ts:901

Subscribe to all events.

Parameters

listener

EventListener

Returns

(): void

Returns

void

---

skipGadget()

skipGadget(nodeId, failedDependency, failedDependencyError, reason): void

Defined in: core/execution-tree.ts:561

Mark a gadget as skipped due to dependency failure.

Parameters

nodeId

string

failedDependency

string

failedDependencyError

string

reason

"dependency_failed" | "controller_skip"

Returns

void

---

startGadget()

startGadget(nodeId): void

Defined in: core/execution-tree.ts:494

Mark a gadget as started (running).

Parameters

nodeId

string

Returns

void