How it works

One turn, end to end

For a call such as:

const result = await agent.run("Inspect the parser and fix the failing test.");

Agent performs the following sequence.

1. Append the goal

The goal is linked to the previous frontier. On the first turn, the runtime also creates the system contract.

system ─┐
        ├→ goal
frontier┘

A content identity is computed from node kind, sorted parents, payload, and optional resource key. Timestamp and sequence are metadata, not identity.

2. Compile working context

The compiler begins with mandatory state:

latest system and goal;
every frontier head;
current resource heads;
ten recent non-superseded nodes;
up to two levels of operational parents.

It then ranks older candidates by lexical relevance and recency, adds their bounded operational closure, and stops at the node budget. Equivalent repeated reads, calls, results, and protocol errors collapse only in this projection. The projection includes a deterministic whole-graph digest so omitted history still contributes stable counts, resource heads, activity, and recent recorded inference notes.

CAUSAL_WEAVE/1
frontier: …

[graph digest]
…

[selected nodes]
…

The default target is 16,000 estimated tokens. The hard default ceiling is 64,000.

3. Call the model

The provider receives:

input.prompt: the compiled causal view;
input.system: the action protocol and tool descriptions;
an abort signal;
provider parameters from the adapter.

The model returns one action:

TOOL_CALL {"name":"read_file","args":{"file_path":"src/parser.ts"}}

or:

FINAL: The parser now accepts the valid form and the focused test passes.

The model does not return graph edges.

4. Record the inference

Before executing an action, the runtime appends an inference node. Its parents are exactly the IDs emitted by the compiler in step 2.

selected nodes → inference

This is the defining causal link.

5. Execute or retry

For a tool action, StateWeave:

validates the tool name and Zod schema;
records tool_call;
executes the tool;
records tool_result;
extracts resource or verification evidence when the result exposes it;
compiles the next causal view.

Invalid output becomes protocol_error and the loop continues. Tool failures remain evidence for the next inference. When completion evidence is enabled, unsupported coding-task finals are rejected until the graph contains the required inspection, mutation, restart, or verification evidence.

6. Commit transactionally

A successful final appends answer, produces AgentRunResult, and replaces the agent’s committed state. A failed or aborted run throws AgentRunError. Its diagnostic state, graph, trace, and metrics remain available on the error, but the stateful agent keeps the previous successful state. Concurrent stateful calls are serialized in invocation order. Passing options.state runs against that explicit snapshot without mutating the agent-owned session.

Commit rule

Successful runs advance session state. Failed and aborted runs do not.

Limits are behavior

Option	Default	Meaning
`maxIterations`	`30`	Maximum model/action steps in one turn
`projectionTargetTokens`	`16_000`	Preferred compiled context size
`maxPromptTokens`	`64_000`	Hard compiled prompt ceiling
`maxNoProgressIterations`	unset	Optional repeated-state watchdog

See AgentState for the data model and Agent reference for exact runtime options.

Start

Understand

Build

Reference

One turn, end to end

1. Append the goal

2. Compile working context

3. Call the model

4. Record the inference

5. Execute or retry

6. Commit transactionally

Limits are behavior

​One turn, end to end

​1. Append the goal

​2. Compile working context

​3. Call the model

​4. Record the inference

​5. Execute or retry

​6. Commit transactionally

​Limits are behavior

One turn, end to end

1. Append the goal

2. Compile working context

3. Call the model

4. Record the inference

5. Execute or retry

6. Commit transactionally

Limits are behavior