Mutable state carried through the agentic loop. More...

#include <entropic/core/engine_types.h>

Collaboration diagram for entropic::LoopContext:

Public Attributes
std::vector< Message >	messages
	Conversation history.

std::vector< ToolCall >	pending_tool_calls
	Pending tool calls (v1.8.5)

AgentState	state = AgentState::IDLE
	Current state.

LoopMetrics	metrics
	Timing and counts.

int	consecutive_errors = 0
	Error streak counter.

int	consecutive_duplicate_attempts = 0
	Stuck-model detector.

int	effective_tool_calls = 0
	Non-blocked calls this iteration.

bool	has_pending_tool_results = false
	Tool results awaiting presentation.

std::string	locked_tier
	Tier locked for this loop ("" = none)

std::string	task_id
	External task ID (MCP integration)

std::string	session_key
	Caller-scoped session this turn belongs to (gh#144, v2.12.0).

std::string	active_root
	Directory this loop's tools are currently pointed at (gh#160).

std::string	conversation_id
	Conversation ID for storage (v1.8.8)

std::string	source = "human"
	Message source.

std::string	base_system
	Base system prompt (pre-tier formatting)

std::unordered_map< std::string, std::string >	metadata
	Runtime metadata.

int	delegation_depth = 0
	0 = root, 1+ = child

std::vector< std::string >	delegation_ancestor_tiers
	Tier stack from root to this loop (P1-9, 2.0.6-rc16)

std::string	parent_conversation_id
	Parent conv ID (delegation)

std::vector< std::string >	child_conversation_ids
	Spawned child IDs.

std::string	active_phase = "default"
	Active inference phase.

std::unordered_map< std::string, std::string >	recent_tool_calls
	Duplicate detection cache (v1.8.5)

std::unordered_map< std::string, int >	failed_tool_calls
	How often each exact call (tool + sorted args) has FAILED.

std::optional< PendingDelegation >	pending_delegation
	Stored by dir_delegate (v1.8.6)

std::optional< PendingPipeline >	pending_pipeline
	Stored by dir_pipeline (v1.8.6)

int	effective_max_iterations = -1
	Per-identity override (-1 = LoopConfig, P3-18)

int	effective_max_tool_calls_per_turn = -1
	Per-identity override (-1 = LoopConfig, P3-18)

int	delegated_max_turns = -1
	gh#182 (v2.13.0): the `max_turns` the MODEL asked for when it issued this child's `entropic.delegate` call.

std::string	pending_validation_feedback
	One-shot reminder text consumed by the next per-turn system prompt assembly.

std::string	pending_anti_spiral_warning
	One-shot anti-spiral reminder for the next per-turn system prompt.

std::string	last_tool_name
	Name of the most recently dispatched tool.

int	consecutive_same_tool_calls = 0
	Count of CONSECUTIVE successful calls to the same tool (last_tool_name).

int	budget_tokens_since_tool = 0
	gh#80 (v2.5.0): tokens generated since the last tool call (mode `tokens`).

double	budget_window_start_s = 0.0
	gh#80 (v2.5.0): wall-clock epoch-seconds marking the start of the current tool-call-free window (mode `wall_clock`).

bool	budget_completion_nudged = false
	gh#80 (v2.5.0): true once the engine has emitted the "emit completion now" nudge for the current budget window.

std::string	last_failed_delegation_target
	gh#64: target tier of the most recent FAILED delegation (DelegationResult.success == false).

int	consecutive_failed_delegations = 0
	gh#64: count of consecutive failed delegations against last_failed_delegation_target.

Detailed Description

Mutable state carried through the agentic loop.

All mutable loop state lives here. The engine itself is stateless between run() calls (except context_anchors which persist).

Version: 2.0.6-rc16

Definition at line 362 of file engine_types.h.

Member Data Documentation

◆ active_phase

std::string entropic::LoopContext::active_phase = "default"

Active inference phase.

Definition at line 396 of file engine_types.h.

◆ active_root

std::string entropic::LoopContext::active_root

Directory this loop's tools are currently pointed at (gh#160).

Empty for a loop running against the session's own root. Set by DelegationManager on a child context when that child runs inside a sandbox, so a NESTED delegation restores its parent's sandbox rather than the project root when it finishes. Pre-gh#160 the restore target was always the repo root, which handed the outer delegation's remaining turns straight back to the user's working tree.

Definition at line 387 of file engine_types.h.

◆ base_system

std::string entropic::LoopContext::base_system

Base system prompt (pre-tier formatting)

Definition at line 390 of file engine_types.h.

◆ budget_completion_nudged

bool entropic::LoopContext::budget_completion_nudged = false

gh#80 (v2.5.0): true once the engine has emitted the "emit completion now" nudge for the current budget window.

The next exhaustion without a tool call escalates to a hard cut. Reset to false on any tool call.

Version: 2.5.0

Definition at line 470 of file engine_types.h.

◆ budget_tokens_since_tool

int entropic::LoopContext::budget_tokens_since_tool = 0

gh#80 (v2.5.0): tokens generated since the last tool call (mode tokens).

Reset to 0 whenever a tool call is dispatched.

Version: 2.5.0

Definition at line 456 of file engine_types.h.

◆ budget_window_start_s

double entropic::LoopContext::budget_window_start_s = 0.0

gh#80 (v2.5.0): wall-clock epoch-seconds marking the start of the current tool-call-free window (mode wall_clock).

0.0 means "no open window" — set on the first tool-call-free generation, reset to 0.0 on any tool call.

Version: 2.5.0

Definition at line 463 of file engine_types.h.

◆ child_conversation_ids

std::vector<std::string> entropic::LoopContext::child_conversation_ids

Spawned child IDs.

Definition at line 395 of file engine_types.h.

◆ consecutive_duplicate_attempts

int entropic::LoopContext::consecutive_duplicate_attempts = 0

Stuck-model detector.

Definition at line 368 of file engine_types.h.

◆ consecutive_errors

int entropic::LoopContext::consecutive_errors = 0

Error streak counter.

Definition at line 367 of file engine_types.h.

◆ consecutive_failed_delegations

int entropic::LoopContext::consecutive_failed_delegations = 0

gh#64: count of consecutive failed delegations against last_failed_delegation_target.

Reset on success or target switch (intentionally NOT reset on a non-delegation tool call — if a lead reads files between two attempts at the same failing target, we still want to enforce the cap). Compared against LoopConfig::max_consecutive_failed_delegations.

Definition at line 483 of file engine_types.h.

◆ consecutive_same_tool_calls

int entropic::LoopContext::consecutive_same_tool_calls = 0

Count of CONSECUTIVE successful calls to the same tool (last_tool_name).

Reset to 0 when a different tool runs. Compared against LoopConfig::max_consecutive_same_tool. (Demo ask #5, v2.1.0)

Definition at line 451 of file engine_types.h.

◆ conversation_id

std::string entropic::LoopContext::conversation_id

Conversation ID for storage (v1.8.8)

Definition at line 388 of file engine_types.h.

◆ delegated_max_turns

int entropic::LoopContext::delegated_max_turns = -1

gh#182 (v2.13.0): the max_turns the MODEL asked for when it issued this child's entropic.delegate call.

-1 (or any value < 1) means the argument was omitted, which leaves the bound exactly where it was before this field existed.

Deliberately NOT folded into effective_max_iterations: that field is the OPERATOR's setting (identity frontmatter, else LoopConfig), and the two are resolved together by resolve_max_iterations, which takes the STRICTER. Keeping them apart is what makes "a model may lower a bound, never raise one" a property of the resolver rather than of the order in which two writers happened to run.

Version: 2.13.0

Definition at line 424 of file engine_types.h.

◆ delegation_ancestor_tiers

std::vector<std::string> entropic::LoopContext::delegation_ancestor_tiers

Tier stack from root to this loop (P1-9, 2.0.6-rc16)

Definition at line 393 of file engine_types.h.

◆ delegation_depth

int entropic::LoopContext::delegation_depth = 0

0 = root, 1+ = child

Definition at line 392 of file engine_types.h.

◆ effective_max_iterations

int entropic::LoopContext::effective_max_iterations = -1

Per-identity override (-1 = LoopConfig, P3-18)

Definition at line 410 of file engine_types.h.

◆ effective_max_tool_calls_per_turn

int entropic::LoopContext::effective_max_tool_calls_per_turn = -1

Per-identity override (-1 = LoopConfig, P3-18)

Definition at line 411 of file engine_types.h.

◆ effective_tool_calls

int entropic::LoopContext::effective_tool_calls = 0

Non-blocked calls this iteration.

Definition at line 369 of file engine_types.h.

◆ failed_tool_calls

std::unordered_map<std::string, int> entropic::LoopContext::failed_tool_calls

How often each exact call (tool + sorted args) has FAILED.

v2.13.0: record_tool_call deliberately keeps error results out of recent_tool_calls so a transient failure does not poison the call for the rest of the turn (v1.8.5). Correct for one retry, but it left the retry count unbounded — a delegated child re-issued one byte-identical refused read four times and died on its timeout. Counted separately so the transient retry survives and only the repeat is bounded.

Definition at line 407 of file engine_types.h.

◆ has_pending_tool_results

bool entropic::LoopContext::has_pending_tool_results = false

Tool results awaiting presentation.

Definition at line 370 of file engine_types.h.

◆ last_failed_delegation_target

std::string entropic::LoopContext::last_failed_delegation_target

gh#64: target tier of the most recent FAILED delegation (DelegationResult.success == false).

Empty when last delegation succeeded, no delegation has run, or a non-delegation tool ran.

Definition at line 475 of file engine_types.h.

◆ last_tool_name

std::string entropic::LoopContext::last_tool_name

Name of the most recently dispatched tool.

Used to detect runs of the same tool for the anti-spiral primitive. Reset to "" when a different tool runs. (Demo ask #5, v2.1.0)

Definition at line 445 of file engine_types.h.

◆ locked_tier

std::string entropic::LoopContext::locked_tier

Tier locked for this loop ("" = none)

Definition at line 371 of file engine_types.h.

◆ messages

std::vector<Message> entropic::LoopContext::messages

Conversation history.

Definition at line 363 of file engine_types.h.

◆ metadata

std::unordered_map<std::string, std::string> entropic::LoopContext::metadata

Runtime metadata.

Definition at line 391 of file engine_types.h.

◆ metrics

LoopMetrics entropic::LoopContext::metrics

Timing and counts.

Definition at line 366 of file engine_types.h.

◆ parent_conversation_id

std::string entropic::LoopContext::parent_conversation_id

Parent conv ID (delegation)

Definition at line 394 of file engine_types.h.

◆ pending_anti_spiral_warning

std::string entropic::LoopContext::pending_anti_spiral_warning

One-shot anti-spiral reminder for the next per-turn system prompt.

Populated by ToolExecutor when consecutive_same_tool_calls reaches LoopConfig .max_consecutive_same_tool; ResponseGenerator emits as a "[engine] anti-spiral: <tool> called N times consecutively; pivot or complete next turn." line; engine clears post-emit. (Demo ask #5, v2.1.0)

Definition at line 439 of file engine_types.h.

◆ pending_delegation

std::optional<PendingDelegation> entropic::LoopContext::pending_delegation

Stored by dir_delegate (v1.8.6)

Definition at line 408 of file engine_types.h.

◆ pending_pipeline

std::optional<PendingPipeline> entropic::LoopContext::pending_pipeline

Stored by dir_pipeline (v1.8.6)

Definition at line 409 of file engine_types.h.

◆ pending_tool_calls

std::vector<ToolCall> entropic::LoopContext::pending_tool_calls

Pending tool calls (v1.8.5)

Definition at line 364 of file engine_types.h.

◆ pending_validation_feedback

std::string entropic::LoopContext::pending_validation_feedback

One-shot reminder text consumed by the next per-turn system prompt assembly.

Engine populates after a rejected validation; ResponseGenerator emits as a "[engine] previous turn rejected: …" line and the engine clears it post-emit. (Demo ask #2, v2.1.0)

Definition at line 430 of file engine_types.h.

◆ recent_tool_calls

std::unordered_map<std::string, std::string> entropic::LoopContext::recent_tool_calls

Duplicate detection cache (v1.8.5)

Definition at line 397 of file engine_types.h.

◆ session_key

std::string entropic::LoopContext::session_key

Caller-scoped session this turn belongs to (gh#144, v2.12.0).

Distinct from conversation_id below, which is a STORAGE FK minted fresh on every run() and is neither caller-supplied nor stable. This is opaque, caller-supplied and stable — the backend maps it to a KV sequence.

Definition at line 378 of file engine_types.h.

◆ source

std::string entropic::LoopContext::source = "human"

Message source.

Definition at line 389 of file engine_types.h.

◆ state

AgentState entropic::LoopContext::state = AgentState::IDLE

Current state.

Definition at line 365 of file engine_types.h.

◆ task_id

std::string entropic::LoopContext::task_id

External task ID (MCP integration)

Definition at line 372 of file engine_types.h.

The documentation for this struct was generated from the following file:

entropic/core/engine_types.h

Public Attributes