Core agent execution engine. More...

#include <entropic/core/engine.h>

Classes
struct	DelegationCallbacks
	Grouped consumer-registered delegation callbacks (gh#29). More...

Public Member Functions
	AgentEngine (const InferenceInterface &inference, const LoopConfig &loop_config, const CompactionConfig &compaction_config)
	Construct an agent engine.

std::vector< Message >	run (std::vector< Message > messages, const std::string &tier_override="")
	Run the engine on a set of messages.

void	set_callbacks (const EngineCallbacks &callbacks)
	Set callback functions for loop events.

void	set_tool_executor (const ToolExecutionInterface &tool_exec)
	Set the tool execution interface.

void	set_tier_resolution (const TierResolutionInterface &tier_res)
	Set the tier resolution interface for delegation.

void	set_storage (const StorageInterface &storage)
	Set the storage interface for persistence.

void	set_hooks (const HookInterface &hooks)
	Set the hook dispatch interface.

void	set_project_dir (const std::filesystem::path &project_dir)
	Set the configured project directory (gh#31, v2.1.6).

void	set_stream_observer (TokenCallback observer, void *user_data)
	Set the global stream observer.

void	set_validation_provider (char (provider)(void ), void user_data)
	Register a JSON provider for the validation block in ON_COMPLETE hook context.

void	set_delegation_callbacks (ent_decision_t(on_start)(const ent_delegation_request_t , void ), ent_decision_t(on_complete)(const ent_delegation_result_t , void ), void *user_data)
	Register delegation start/complete callbacks (gh#29, v2.1.5).

DelegationCallbacks	delegation_callbacks_snapshot () const
	Atomically snapshot the registered delegation callbacks.

void	set_external_interrupt (void(cb)(void user_data), void *user_data)
	Register a callback invoked alongside interrupt().

void	run_loop (LoopContext &ctx, bool inherit_interrupt=false)
	Run the engine loop on a pre-built context.

const TierResolutionInterface &	tier_resolution () const
	Get the tier resolution interface.

void	interrupt ()
	Interrupt the running loop (thread-safe).

void	reset_interrupt ()
	Reset interrupt flag for next run.

void	pause ()
	Pause generation (thread-safe).

void	cancel_pause ()
	Cancel pause and interrupt completely.

std::pair< int, int >	context_usage (const std::vector< Message > &messages) const
	Get context usage for a message list.

EngineCallbacks &	callbacks ()
	Get mutable reference to engine callbacks.

const LoopConfig &	loop_config () const
	Get loop configuration.

DirectiveProcessor &	directive_processor ()
	Get directive processor for external hook wiring.

LoopMetrics	last_loop_metrics () const
	Get metrics from the most recent completed run.

std::unordered_map< std::string, LoopMetrics >	per_tier_metrics () const
	Per-tier aggregated metrics since engine start.

void	set_system_prompt (const std::string &prompt)
	Set the system prompt for conversation state.

void	set_session_logger (SessionLogger *logger)
	Set session logger for model transcript logging.

std::vector< Message >	run_turn (const std::string &input)
	Run a single conversation turn (stateful).

std::vector< Message >	run_turn_as (const std::string &tier, const std::string &input)
	Run a single turn under a named tier's grammar/identity (gh#99).

std::vector< Message >	run_turn (std::vector< Message > new_messages)
	Run a single conversation turn from a pre-built message list (gh#37).

void	seed_system_prompt (const std::vector< Message > &new_messages)
	Prepend the configured system prompt if this turn needs it.

std::vector< Message >	run_drain_loop (std::string pending, const std::string &tier_override)
	Shared drain loop for run_turn / run_turn_as (gh#99).

void	seed_system_prompt_for_tier (const std::string &tier)
	Seed a tier's system prompt on an empty conversation (gh#99).

bool	prepare_next_turn (std::vector< Message > &pending)
	Pull the next queued user message into `pending` (gh#40).

int	run_streaming (const std::string &input, TokenCallback on_token, void user_data, int cancel_flag)
	Run a streaming conversation turn (stateful).

int	run_streaming (std::vector< Message > new_messages, TokenCallback on_token, void user_data, int cancel_flag)
	Streaming conversation turn from a pre-built message list (gh#37).

void	clear_conversation ()
	Clear conversation history.

size_t	message_count () const
	Get conversation message count.

const std::vector< Message > &	get_messages () const
	Get conversation messages (read-only).

bool	queue_user_message (const std::string &message)
	Append a user message to the mid-gen queue.

size_t	user_message_queue_depth () const
	Snapshot of the queue depth.

void	clear_user_message_queue ()
	Drop all queued user messages.

void	set_message_queue_capacity (int cap)
	Set the runtime capacity of the mid-gen queue.

bool	is_running () const
	Whether a top-level run_turn is currently in progress.

void	set_queue_observer (void(observer)(const char , size_t, void ), void user_data)
	Register an observer that fires when a queued user message is consumed and seeded as the next turn.

void	set_state_observer (void(observer)(int state, void user_data), void *user_data)
	Register a persistent state-transition observer.

ToolExecutorHooks	build_directive_hooks ()
	Build ToolExecutorHooks wired to this engine's DirectiveProcessor.

void	set_tier_info (const std::string &name, const ChildContextInfo &info)
	Store pre-resolved tier context info.

bool	has_tier (const std::string &name) const
	Whether a tier name is known (gh#99).

const std::string &	tier_system_prompt (const std::string &name) const
	A tier's resolved system prompt (gh#98).

void	set_relay_single_delegate (const std::string &name)
	Mark a tier as relay-on-single-delegate.

void	set_handoff_rules (const std::unordered_map< std::string, std::vector< std::string > > &rules)
	Store handoff rules for tier delegation.

bool	tier_requires_explicit_completion (const std::string &tier) const
	Check if a tier requires an explicit entropic.complete / entropic.delegate tool call to conclude its turn.

bool	is_delegation_cycle (const LoopContext &ctx, const std::string &target) const
	Check whether pending delegation would close a cycle.

bool	is_delegation_repeat_blocked (const LoopContext &ctx, const std::string &target) const
	Predicate: should this delegation be blocked because the same target has just failed too many times? (gh#64)

int64_t	seconds_since_last_activity () const
	gh#35: seconds since the engine last serviced a run().

bool	fold_complete_into_assistant (LoopContext &ctx, const Message &tool_result_msg) const
	gh#68 (v2.3.4): fold entropic.complete summary into the prior assistant message, suppressing the JSON tool-result user message that would otherwise land in history.

void	defang_meta_action_envelope (Message &msg) const
	gh#88: reshape a meta-tool `{"action":...}` result so the model is not primed to parrot the call-shaped envelope.

CompactionManager &	compaction_manager ()
	Borrowed reference to the engine's built-in CompactionManager.

Static Public Attributes
static constexpr int	MAX_DELEGATION_DEPTH = 2
	Max delegation nesting depth (0=root, 1=child, 2=max).

Detailed Description

Core agent execution engine.

Owns all engine subsystems: ResponseGenerator, ContextManager, CompactionManager, DirectiveProcessor. Implements the agentic loop (plan-act-observe-repeat) with proper state management and termination conditions.

Version: 1.8.6

Definition at line 62 of file engine.h.

Constructor & Destructor Documentation

◆ AgentEngine()

entropic::AgentEngine::AgentEngine	(	const InferenceInterface &	inference,
		const LoopConfig &	loop_config,
		const CompactionConfig &	compaction_config
	)

Construct an agent engine.

Parameters

inference	Inference interface (function pointers).
loop_config	Loop configuration.
compaction_config	Compaction configuration.

Version: 1.8.4

Parameters

inference	Inference interface.
loop_config	Loop configuration.
compaction_config	Compaction configuration.

Definition at line 133 of file engine.cpp.

Member Function Documentation

◆ build_directive_hooks()

ToolExecutorHooks entropic::AgentEngine::build_directive_hooks ( )

Build ToolExecutorHooks wired to this engine's DirectiveProcessor.

Returns hooks with process_directives bridged to directive_processor(). Eliminates the need for facade bridge functions.

Returns: Configured ToolExecutorHooks.

Version: 2.0.2

Returns: Configured hooks.

Definition at line 3194 of file engine.cpp.

◆ callbacks()

EngineCallbacks & entropic::AgentEngine::callbacks ( )

inline

Get mutable reference to engine callbacks.

Used by ToolExecutor which holds a reference that survives set_callbacks() reassignment (same pattern as ResponseGenerator).

Returns: Reference to internal callbacks member. @utility

Version: 2.0.1

Definition at line 316 of file engine.h.

◆ cancel_pause()

void entropic::AgentEngine::cancel_pause ( )

Cancel pause and interrupt completely.

Cancel pause and interrupt.

Version: 1.8.4

Definition at line 1025 of file engine.cpp.

◆ clear_conversation()

void entropic::AgentEngine::clear_conversation ( )

Clear conversation history.

Version: 2.0.2

Definition at line 3046 of file engine.cpp.

◆ clear_user_message_queue()

void entropic::AgentEngine::clear_user_message_queue ( )

Drop all queued user messages.

Drop all queued messages atomically.

@threadsafety Thread-safe.

Version: 2.1.10

Definition at line 3107 of file engine.cpp.

◆ compaction_manager()

CompactionManager & entropic::AgentEngine::compaction_manager ( )

inline

Borrowed reference to the engine's built-in CompactionManager.

gh#76 (v2.3.27): the facade-level CompactorRegistry borrows this reference at construction so consumer-registered compactors can fall back to the built-in default. Lifetime: the CompactionManager outlives the registry because both are owned by the engine handle (registry is destroyed in entropic_destroy before the engine).

@utility

Version: 2.3.27

Definition at line 842 of file engine.h.

◆ context_usage()

std::pair< int, int > entropic::AgentEngine::context_usage ( const std::vector< Message > & messages ) const

Get context usage for a message list.

Get context usage.

Parameters

messages Message list.

Returns: (tokens_used, max_tokens).

Version: 1.8.4

Parameters

messages Message list.

Returns: (tokens_used, max_tokens).

Definition at line 1038 of file engine.cpp.

◆ defang_meta_action_envelope()

void entropic::AgentEngine::defang_meta_action_envelope ( Message & msg ) const

gh#88: reshape a meta-tool {"action":...} result so the model is not primed to parrot the call-shaped envelope.

gh#88 de-fang logic — see header.

delegate / pipeline (and peers) return their result as {"action":"x",...} JSON. Pushed verbatim into context, the model echoes that shape as its next "tool call" — which common_chat (PEG_GEMMA4) does not parse, so the call no-ops and the loop spirals to the iteration cap. The typed directive is already built by ToolExecutor::build_directive (target/task copied into the struct) before this runs, so the model-facing content can be replaced with a non-call prose status line without affecting dispatch. entropic.complete is de-fanged earlier by the fold above.

Public so unit tests can exercise the transform without spinning the full engine loop.

Parameters

msg	Tool-result message; content reshaped in place when it is an `entropic.*` meta-tool action envelope. @utility

Version: 2.7.1

@utility

Version: 2.7.1

Definition at line 1384 of file engine.cpp.

◆ delegation_callbacks_snapshot()

AgentEngine::DelegationCallbacks entropic::AgentEngine::delegation_callbacks_snapshot ( ) const

Atomically snapshot the registered delegation callbacks.

Hot path is execute_pending_delegation / execute_pending_pipeline: they grab the triple under the mutex once and pass it forward to the per-call DelegationManager. Prevents a torn read where the consumer reassigns the callbacks mid-delegation. (Hardening landed alongside the 2.1.5 verification pass.)

Returns: Copy of the current callback struct. @utility

Version: 2.1.5

Returns: Copy of the current callback triple.

Definition at line 249 of file engine.cpp.

◆ directive_processor()

DirectiveProcessor & entropic::AgentEngine::directive_processor ( )

inline

Get directive processor for external hook wiring.

Returns: Reference to internal directive processor. @utility

Version: 2.0.1

Definition at line 332 of file engine.h.

◆ fold_complete_into_assistant()

bool entropic::AgentEngine::fold_complete_into_assistant	(	LoopContext &	ctx,
		const Message &	tool_result_msg
	)		const

gh#68 (v2.3.4): fold entropic.complete summary into the prior assistant message, suppressing the JSON tool-result user message that would otherwise land in history.

gh#68 fold logic — see header.

Returns true when the message was folded (caller should NOT push it). Returns false when the message should be pushed as-is.

Conservative — only folds when ALL of:

msg.metadata["tool_name"] == "entropic.complete"
ctx.messages.back() exists and has role == "assistant"
that assistant message has empty content (typically the post-strip body when the model emitted only a tool_call)
ctx.metadata["explicit_completion_summary"] is populated (set by dir_complete before this runs)

If the model also emitted prose around the tool_call, the assistant body is non-empty and we leave both messages alone to avoid silently overwriting legitimate text.

Public so unit tests can exercise the predicate without spinning the full engine loop + mocking the tool executor.

@utility

Version: 2.3.4

@utility

Version: 2.3.7

Definition at line 856 of file engine.cpp.

◆ get_messages()

const std::vector< Message > & entropic::AgentEngine::get_messages ( ) const

Get conversation messages (read-only).

Get conversation messages.

Returns: Const reference to message vector.

Version: 2.0.2

Returns: Const reference to messages.

Definition at line 3067 of file engine.cpp.

◆ has_tier()

bool entropic::AgentEngine::has_tier ( const std::string & name ) const

Whether a tier name is known (gh#99).

Backs entropic_run_as's unknown-tier validation. True once the tier has resolved context info (set_tier_info ran for it at configure time).

Parameters

name	Tier name.

Returns: true if the tier is known.

Version: 2.8.0

Parameters

name	Tier name.

Returns: true if the tier has resolved context info.

Definition at line 3230 of file engine.cpp.

◆ interrupt()

void entropic::AgentEngine::interrupt ( )

Interrupt the running loop (thread-safe).

Interrupt the running loop.

Version: 1.8.4

Callable from any thread and polled per-token on the generation path, so interrupt() runs many times for a single Ctrl+C. Log only on the 0→1 transition to avoid flooding the session log. (P1-4, 2.0.6-rc16)

Definition at line 971 of file engine.cpp.

◆ is_delegation_cycle()

bool entropic::AgentEngine::is_delegation_cycle	(	const LoopContext &	ctx,
		const std::string &	target
	)		const

Check whether pending delegation would close a cycle.

Detect delegation cycles via ancestor chain check.

Exposed for unit tests. (P1-9, 2.0.6-rc16)

Parameters

ctx	Loop context (ancestor chain + locked tier).
target	Proposed delegation target tier.

Returns: true if target is already in the ancestor chain or matches the active locked_tier. @utility

Version: 2.0.6-rc16

Targets already present in delegation_ancestor_tiers or matching the active locked_tier would re-enter an ancestor loop, which the depth cap only catches after repeated waste. (P1-9, 2.0.6-rc16)

Parameters

ctx	Loop context.
target	Pending delegation target tier name.

Returns: true if target would close a cycle. @utility

Version: 2.0.6-rc16

Definition at line 830 of file engine.cpp.

◆ is_delegation_repeat_blocked()

bool entropic::AgentEngine::is_delegation_repeat_blocked	(	const LoopContext &	ctx,
		const std::string &	target
	)		const

Predicate: should this delegation be blocked because the same target has just failed too many times? (gh#64)

gh#64: predicate for the consecutive-failure cap.

Returns true when target matches ctx.last_failed_delegation_target and ctx.consecutive_failed_delegations >= loop_config_.max_consecutive_failed_delegations. Exposed so tests can exercise the guard without spinning a full child loop.

Parameters

ctx	Active loop context.
target	Proposed delegation target tier.

Returns: true if the delegation should be rejected before dispatch. @utility

Version: 2.3.0

See header. @utility

Version: 2.3.0

Definition at line 844 of file engine.cpp.

◆ is_running()

bool entropic::AgentEngine::is_running ( ) const

inline

Whether a top-level run_turn is currently in progress.

Used by the facade to reject entropic_queue_user_message with ENTROPIC_ERROR_INVALID_STATE when there is no in-flight turn to "queue behind." Thread-safe (atomic load).

Returns: true while a top-level run_turn is executing. @utility

Version: 2.1.10

Definition at line 598 of file engine.h.

◆ last_loop_metrics()

LoopMetrics entropic::AgentEngine::last_loop_metrics ( ) const

inline

Get metrics from the most recent completed run.

Returns a copy of the LoopMetrics snapped at the end of the last call to run() or run_turn(). Zero-initialized before any run has completed. Thread-safe: read-only copy is returned. (P2-15)

Returns: LoopMetrics from last run. @utility

Version: 2.0.6-rc16

Definition at line 345 of file engine.h.

◆ loop_config()

const LoopConfig & entropic::AgentEngine::loop_config ( ) const

inline

Get loop configuration.

Returns: Const reference to loop config. @utility

Version: 2.0.1

Definition at line 324 of file engine.h.

◆ message_count()

size_t entropic::AgentEngine::message_count ( ) const

Get conversation message count.

Returns: Number of messages.

Version: 2.0.2

Returns: Number of messages.

Definition at line 3057 of file engine.cpp.

◆ pause()

void entropic::AgentEngine::pause ( )

Pause generation (thread-safe).

Pause generation.

Version: 1.8.4

Definition at line 1015 of file engine.cpp.

◆ per_tier_metrics()

std::unordered_map< std::string, LoopMetrics > entropic::AgentEngine::per_tier_metrics ( ) const

inline

Per-tier aggregated metrics since engine start.

Keys are tier names ("lead", "eng", etc.). Values accumulate iterations/tool_calls/tokens_used/errors and sum duration_ms across every run_loop entered with that locked_tier. Empty map before any run. (P2-15 follow-up, 2.0.6-rc16.2)

Returns: Copy of the per-tier metrics map. @utility

Version: 2.0.6-rc16.2

Definition at line 360 of file engine.h.

◆ prepare_next_turn()

bool entropic::AgentEngine::prepare_next_turn ( std::vector< Message > & pending )

Pull the next queued user message into pending (gh#40).

Extracted from run_turn's drain loop. Pops one queued message, fires ON_QUEUE_CONSUMED, and replaces pending with it.

Parameters

pending Out: cleared and set to the next user turn.

Returns: true if a queued message was dequeued; false if empty.

Parameters

pending Out: cleared and set to the next user turn.

Returns: true if a queued message was dequeued; false if empty.

Definition at line 2863 of file engine.cpp.

◆ queue_user_message()

bool entropic::AgentEngine::queue_user_message ( const std::string & message )

Append a user message to the mid-gen queue.

Enqueue a user message subject to the configured cap.

Bounded FIFO. Enforces LoopConfig::message_queue_capacity. Drained between top-level run_turn invocations from inside run_turn itself — never at child-delegation boundaries.

Parameters

message User input to enqueue.

Returns: true if enqueued; false if the queue is at capacity. @threadsafety Thread-safe.

Version: 2.1.10

Definition at line 3078 of file engine.cpp.

◆ reset_interrupt()

void entropic::AgentEngine::reset_interrupt ( )

Reset interrupt flag for next run.

Reset interrupt flag.

Version: 1.8.4

Definition at line 1006 of file engine.cpp.

◆ run()

std::vector< Message > entropic::AgentEngine::run	(	std::vector< Message >	messages,
		const std::string &	tier_override = `""`
	)

Run the engine on a set of messages.

Run the engine on initial messages.

Parameters

messages	Initial messages (system + user).
tier_override	gh#99: if non-empty, lock this run to the named tier (skips routing) so its grammar/samplers apply; empty routes.

Returns: Final messages including all generated content.

Version: 2.8.0

Parameters

messages	System + user messages.
tier_override	gh#99: if non-empty, lock the run to this tier (lock_tier_if_needed honors a pre-set locked_tier and skips routing).

Returns: Final messages.

Definition at line 379 of file engine.cpp.

◆ run_drain_loop()

std::vector< Message > entropic::AgentEngine::run_drain_loop	(	std::string	pending,
		const std::string &	tier_override
	)

Shared drain loop for run_turn / run_turn_as (gh#99).

Appends pending as a user turn, runs the agentic loop under tier_override ("" = route), then drains any mid-generation queued user messages as further turns. Extracted so both entry points stay under the SLOC gate.

Parameters

pending	First user turn for this call.
tier_override	Tier to lock the run to ("" = route).

Returns: Result messages from the final turn.

Parameters

pending	First user turn for this call.
tier_override	Tier to lock the run to ("" = route).

Returns: Result messages from the final turn.

Definition at line 2797 of file engine.cpp.

◆ run_loop()

void entropic::AgentEngine::run_loop	(	LoopContext &	ctx,
		bool	inherit_interrupt = `false`
	)

Run the engine loop on a pre-built context.

Used by DelegationManager for child loops. Public so the delegation manager (same .so) can invoke it.

gh#81 (v2.4.3): inherit_interrupt controls whether the pre-existing interrupt flag is cleared at entry. Top-level turns clear it (a fresh turn starts un-interrupted). Delegation child loops pass inherit_interrupt=true so a parent interrupt raised before/at dispatch is NOT cleared — "stop the engine" must stop children too, not reset on each nested loop.

Parameters

ctx	Loop context to execute.
inherit_interrupt	When true, do not reset the interrupt flag at entry (child loops inherit the parent's state).

Version: 2.4.3

Parameters

ctx	Loop context to execute.
inherit_interrupt	When true, do not reset the interrupt flag.

Definition at line 343 of file engine.cpp.

◆ run_streaming() [1/2]

int entropic::AgentEngine::run_streaming	(	const std::string &	input,
		TokenCallback	on_token,
		void *	user_data,
		int *	cancel_flag
	)

Run a streaming conversation turn (stateful).

Same as run_turn but with streaming token output. Owns the StreamThinkFilter, cancel polling, and session logger wiring.

Parameters

input	User input string.
on_token	Consumer token callback (receives filtered UTF-8).
user_data	Consumer callback context.
cancel_flag	Polled per-token, nullable.

Returns: 0 on success, 1 if cancelled, 2 on error.

Version: 2.0.2

Parameters

input	User input.
on_token	Consumer callback (filtered, UTF-8 aligned).
user_data	Consumer context.
cancel_flag	Polled per-token, nullable.

Returns: 0=OK, 1=cancelled, 2=error.

Definition at line 2916 of file engine.cpp.

◆ run_streaming() [2/2]

int entropic::AgentEngine::run_streaming	(	std::vector< Message >	new_messages,
		TokenCallback	on_token,
		void *	user_data,
		int *	cancel_flag
	)

Streaming conversation turn from a pre-built message list (gh#37).

Multimodal-aware streaming run_turn overload (gh#37, v2.1.8).

Multimodal-aware streaming overload. Same content_parts preservation semantics as run_turn(vector<Message>), with token callback wiring identical to the single-string streaming variant.

Parameters

new_messages	Messages to add this turn.
on_token	Consumer token callback (filtered UTF-8).
user_data	Consumer callback context.
cancel_flag	Polled per-token, nullable.

Returns: 0 on success, 1 if cancelled, 2 on error.

Version: 2.1.8

Mirrors the single-string streaming variant — same stream filter, cancel polling, session logger wiring — but consumes a pre-built message list with content_parts preserved.

Parameters

new_messages	Messages to add this turn.
on_token	Filtered token callback.
user_data	Consumer context.
cancel_flag	Per-token cancel poll, nullable.

Returns: 0=OK, 1=cancelled, 2=error.

Definition at line 2995 of file engine.cpp.

◆ run_turn() [1/2]

std::vector< Message > entropic::AgentEngine::run_turn ( const std::string & input )

Run a single conversation turn (stateful).

Manages conversation history internally. Appends user message, runs the agentic loop, appends result messages.

Parameters

input User input string.

Returns: Full result messages from engine.

Version: 2.0.2

gh#40 (v2.1.10): after the agent loop reaches top-level COMPLETE, drains any messages enqueued mid-generation via queue_user_message as additional turns under the same call. gh#99 (v2.8.0): the drain loop is shared with run_turn_as via run_drain_loop.

Parameters

input User input string.

Returns: Result messages from engine.

Definition at line 2720 of file engine.cpp.

◆ run_turn() [2/2]

std::vector< Message > entropic::AgentEngine::run_turn ( std::vector< Message > new_messages )

Run a single conversation turn from a pre-built message list (gh#37).

Run a stateful turn, draining any queued user messages (gh#40).

Multimodal-aware overload. Each message in new_messages is appended to the engine's conversation history with its content_parts preserved (no string flattening). The agentic loop runs over the full conversation; replies are appended to history and returned.

If the conversation is currently empty AND none of new_messages carries role == "system", the engine prepends its configured system_prompt_ first — matching the single-string overload's behavior.

Parameters

new_messages Messages to add this turn (typically one user message; may include a system message on first turn).

Returns: Full result messages from the engine loop.

Version: 2.1.8

Parameters

new_messages Messages to add this turn.

Returns: Full result messages from the engine loop.

Definition at line 2882 of file engine.cpp.

◆ run_turn_as()

std::vector< Message > entropic::AgentEngine::run_turn_as	(	const std::string &	tier,
		const std::string &	input
	)

Run a single turn under a named tier's grammar/identity (gh#99).

Run one turn under a named tier's grammar/identity (gh#99).

Per-call tier selection on the shared resident model: seeds the tier's system prompt (from tier_info_) and locks the run to tier so its grammar + samplers apply — no 2nd model load, no reconfigure. Mirrors the delegation precedent (a child LoopContext with locked_tier + the tier's system prompt), scoped to one top-level call.

Parameters

tier	Tier name to run this call under.
input	User input string.

Returns: Full result messages from the engine.

Version: 2.8.0

The tier's grammar + samplers apply to THIS call (via the tier_override that pre-locks the tier, skipping routing). The tier's system prompt is seeded only when the conversation is empty (the first call on a fresh handle) — on a stateful handle that interleaves tiers, later calls switch grammar per call but keep the existing system prompt + accumulated history. For isolated per-kind runs (e.g. distinct game-agent identities), clear context between calls or use a fresh handle.

Parameters

tier	Tier to lock this call to.
input	User input string.

Returns: Result messages.

Definition at line 2754 of file engine.cpp.

◆ seconds_since_last_activity()

int64_t entropic::AgentEngine::seconds_since_last_activity ( ) const

gh#35: seconds since the engine last serviced a run().

gh#35: idle accessor.

Updated at the entry of every run()/run_turn() call. Hosts that want an idle-exit policy poll this and tear down the engine when the value exceeds their threshold. Returned as int64 (epoch seconds delta) so consumers can compare against any unit.

Returns: Seconds since last activity. Returns 0 if no run has ever happened (no activity to be idle relative to). @utility

Version: 2.3.0

See header. @utility

Version: 2.3.0

Definition at line 876 of file engine.cpp.

◆ seed_system_prompt()

void entropic::AgentEngine::seed_system_prompt ( const std::vector< Message > & new_messages )

Prepend the configured system prompt if this turn needs it.

Multimodal-aware run_turn overload (gh#37, v2.1.8).

Extracted from run_turn to keep it knots-clean. Seeds conversation_ with system_prompt_ only when the conversation is empty and the caller didn't supply its own system message.

Parameters

new_messages The messages the caller is adding this turn.

Takes a pre-built list of messages and preserves their content_parts end-to-end (no string flattening). Each input message is appended verbatim to the engine's conversation history before the agent loop runs. If the conversation is empty and the caller did not supply a system message, the engine's configured system_prompt_ is prepended first — matching the single-string overload's first-turn behavior.

Parameters

new_messages Messages to add this turn.

Returns: Result messages from the loop.

Prepend the configured system prompt if this turn needs it.

Parameters

new_messages The messages the caller is adding this turn.

Definition at line 2841 of file engine.cpp.

◆ seed_system_prompt_for_tier()

void entropic::AgentEngine::seed_system_prompt_for_tier ( const std::string & tier )

Seed a tier's system prompt on an empty conversation (gh#99).

Pushes tier_info_[tier].system_prompt as the system message when the conversation is empty; falls back to the global system_prompt_ when the tier carries no info.

Parameters

tier	Tier whose system prompt to seed.

Pushes tier_info_[tier].system_prompt; falls back to the global system_prompt_ when the tier carries no info. No-op once the conversation has started — like run_turn's first-turn seeding, the system prompt is NOT re-seeded mid-session when a later run_turn_as names a different tier (the grammar/samplers still switch; only the prompt persists). See run_turn_as.

Parameters

tier	Tier whose system prompt to seed.

Definition at line 2775 of file engine.cpp.

◆ set_callbacks()

void entropic::AgentEngine::set_callbacks ( const EngineCallbacks & callbacks )

Set callback functions for loop events.

Parameters

callbacks Callback configuration.

Version: 1.8.4

Parameters

callbacks Callback configuration.

Definition at line 158 of file engine.cpp.

◆ set_delegation_callbacks()

void entropic::AgentEngine::set_delegation_callbacks	(	ent_decision_t()(const ent_delegation_request_t , void *)	on_start,
		ent_decision_t()(const ent_delegation_result_t , void *)	on_complete,
		void *	user_data
	)

Register delegation start/complete callbacks (gh#29, v2.1.5).

Replaces the pre-2.1.5 silent auto-merge-to-parent behavior. The engine stores these C-style function pointers and forwards them into every DelegationManager it constructs (one per pending delegation or pipeline). Null callbacks are honored: on_start null = always ACCEPT; on_complete null = default-deny (write patch to ~/.entropic/sandbox/<session>/pending/<id>.patch).

Parameters

on_start	Pre-delegation gate (nullable clears).
on_complete	Post-delegation result (nullable clears).
user_data	Forwarded to both callbacks.

Version: 2.1.5

Parameters

on_start	Pre-delegation gate (nullable).
on_complete	Post-delegation result (nullable).
user_data	Forwarded to both callbacks.

Definition at line 232 of file engine.cpp.

◆ set_external_interrupt()

void entropic::AgentEngine::set_external_interrupt	(	void()(void user_data)	cb,
		void *	user_data
	)

Register a callback invoked alongside interrupt().

Register external transport interrupt callback.

Used to propagate Ctrl+C into external MCP transports so in-flight tool calls do not run to completion. Facade wires this to ServerManager::interrupt_external_tools(). (P1-10, 2.0.6-rc16)

Parameters

cb	Callback (nullable).
user_data	Forwarded to cb.

Version: 2.0.6-rc16

Facade wires this to ServerManager::interrupt_external_tools so AgentEngine::interrupt() unwinds tool dispatches within ~100ms. (P1-10, 2.0.6-rc16)

Parameters

cb	Callback (nullable).
user_data	Forwarded to cb.

Definition at line 995 of file engine.cpp.

◆ set_handoff_rules()

void entropic::AgentEngine::set_handoff_rules ( const std::unordered_map< std::string, std::vector< std::string > > & rules )

Store handoff rules for tier delegation.

Store handoff rules.

Parameters

rules Map of source tier → valid target tiers.

Version: 2.0.2

Parameters

rules Source tier → valid targets.

Definition at line 3264 of file engine.cpp.

◆ set_hooks()

void entropic::AgentEngine::set_hooks ( const HookInterface & hooks )

Set the hook dispatch interface.

Parameters

hooks Hook dispatch interface (wired by facade).

Version: 1.9.1

Parameters

hooks Hook dispatch interface.

Definition at line 201 of file engine.cpp.

◆ set_message_queue_capacity()

void entropic::AgentEngine::set_message_queue_capacity ( int cap )

Set the runtime capacity of the mid-gen queue.

Update the runtime cap (in-place on LoopConfig).

If cap is less than the current depth, excess pending messages are kept (no truncation) but no new enqueues succeed until the queue drains below the new cap. cap of 0 disables enqueue while leaving the queue otherwise functional.

Parameters

cap	New capacity. @threadsafety Thread-safe.

Version: 2.1.10

Definition at line 3121 of file engine.cpp.

◆ set_project_dir()

void entropic::AgentEngine::set_project_dir ( const std::filesystem::path & project_dir )

Set the configured project directory (gh#31, v2.1.6).

Store the project_dir resolved by entropic_configure_dir.

The facade calls this from entropic_configure_dir after the layered config loader has resolved the project root. get_repo_dir() uses this value in preference to std::filesystem::current_path(), so consumers whose launcher cwd differs from the target project (the common case for wrapper CLIs and IDE plugins) still snapshot the right tree into the sandbox.

Pre-2.1.6 the engine used CWD unconditionally, silently ignoring the project_dir argument to entropic_configure_dir. Setting an empty path resets the override so get_repo_dir() falls back to CWD (preserves the no-configure-dir caller's behavior).

Parameters

project_dir Project root (empty resets to CWD fallback). @threadsafety Serialized per-handle via the facade's api_mutex.

Version: 2.1.6

gh#31 (v2.1.6). See engine.h for rationale. Resets the cache so a subsequent get_repo_dir() call picks up the new value even if a previous lookup already settled on the CWD fallback.

Parameters

project_dir Project root (empty resets to CWD fallback).

Definition at line 2525 of file engine.cpp.

◆ set_queue_observer()

void entropic::AgentEngine::set_queue_observer	(	void()(const char , size_t, void *)	observer,
		void *	user_data
	)

Register an observer that fires when a queued user message is consumed and seeded as the next turn.

Persistent slot setter; survives set_callbacks() shuffles.

Persistent across set_callbacks() reassignments — the streaming entry points overwrite the EngineCallbacks struct per-call, so the queue observer needs a dedicated slot to survive both streaming and non-streaming runs.

Parameters

observer	Callback (consumed_text, remaining_depth, ud). Pass nullptr to clear.
user_data	Forwarded to observer. @threadsafety Thread-safe.

Version: 2.1.10

Definition at line 3160 of file engine.cpp.

◆ set_relay_single_delegate()

void entropic::AgentEngine::set_relay_single_delegate ( const std::string & name )

Mark a tier as relay-on-single-delegate.

When this tier is the active (lead) tier and exactly one delegate completes successfully, the delegate's summary is used as the final output without lead re-generating. Avoids redundant re-synthesis of already user-ready delegate responses.

Parameters

name	Tier name (typically "lead").

Version: 2.0.11

Parameters

name	Tier name.

Definition at line 3254 of file engine.cpp.

◆ set_session_logger()

void entropic::AgentEngine::set_session_logger ( SessionLogger * log )

Set session logger for model transcript logging.

Parameters

logger Non-owning pointer (nullable). Must outlive engine.

Version: 2.0.2

Parameters

log	Non-owning pointer (nullable).

Definition at line 2703 of file engine.cpp.

◆ set_state_observer()

void entropic::AgentEngine::set_state_observer	(	void()(int state, void user_data)	observer,
		void *	user_data
	)

Register a persistent state-transition observer.

Wire the persistent state-observer slot.

The legacy path (EngineCallbacks::on_state_change) is wiped for the duration of run_streaming because that method replaces the full callback struct to install its token sink. This persistent slot survives every set_callbacks() shuffle so consumers (notably the external MCP bridge that the entropic_set_state_observer docstring names) actually see transitions during streaming runs.

Fires alongside the legacy on_state_change slot — neither supersedes the other. Pass nullptr to clear.

Parameters

observer	State-change callback.
user_data	Forwarded to observer. @threadsafety Thread-safe.

Version: 2.1.10

Forwarded to ResponseGenerator so the PAUSED transition that ResponseGenerator emits during handle_pause also reaches the persistent slot. The legacy EngineCallbacks::on_state_change remains supported in parallel for in-tree callers (tests etc.).

Definition at line 3178 of file engine.cpp.

◆ set_storage()

void entropic::AgentEngine::set_storage ( const StorageInterface & storage )

Set the storage interface for persistence.

Parameters

storage Storage callbacks (wired by facade). Nullable — engine works without storage (in-memory only mode).

Version: 1.8.8

Parameters

storage Storage callbacks (nullable).

Definition at line 190 of file engine.cpp.

◆ set_stream_observer()

void entropic::AgentEngine::set_stream_observer	(	TokenCallback	observer,
		void *	user_data
	)

Set the global stream observer.

Fires for every token from every generation path — batch entropic_run, entropic_run_streaming, and delegate child-loop generations. Persists across per-call EngineCallbacks reassignment.

Parameters

observer	Token callback (nullable clears).
user_data	Forwarded to observer.

Version: 2.0.6-rc16

Delegates to ResponseGenerator which owns the choke point for every generation path (streaming, batch, and child-loop delegations).

Parameters

observer	Token callback (nullable).
user_data	Forwarded to observer.

Definition at line 219 of file engine.cpp.

◆ set_system_prompt()

void entropic::AgentEngine::set_system_prompt ( const std::string & prompt )

Set the system prompt for conversation state.

Parameters

prompt Assembled system prompt string.

Version: 2.0.2

Parameters

prompt Assembled system prompt.

Definition at line 2693 of file engine.cpp.

◆ set_tier_info()

void entropic::AgentEngine::set_tier_info	(	const std::string &	name,
		const ChildContextInfo &	info
	)

Store pre-resolved tier context info.

Called at configure time. The engine uses this data for delegation instead of external TierResolutionInterface callbacks.

Parameters

name	Tier name.
info	Pre-resolved context info (system prompt, tools, etc.).

Version: 2.0.2

Parameters

name	Tier name.
info	Context info.

Definition at line 3216 of file engine.cpp.

◆ set_tier_resolution()

void entropic::AgentEngine::set_tier_resolution ( const TierResolutionInterface & tier_res )

Set the tier resolution interface for delegation.

Set tier resolution interface for delegation.

Parameters

tier_res Tier resolution callbacks (wired by facade).

Version: 1.8.6

Parameters

tier_res Tier resolution callbacks.

Definition at line 179 of file engine.cpp.

◆ set_tool_executor()

void entropic::AgentEngine::set_tool_executor ( const ToolExecutionInterface & tool_exec )

Set the tool execution interface.

Parameters

tool_exec Tool execution interface (wired by facade).

Version: 1.8.5

Parameters

tool_exec Tool execution interface.

Definition at line 168 of file engine.cpp.

◆ set_validation_provider()

void entropic::AgentEngine::set_validation_provider	(	char ()(void *)	provider,
		void *	user_data
	)

Register a JSON provider for the validation block in ON_COMPLETE hook context.

Register validation JSON provider for ON_COMPLETE context.

The callback returns a malloc'd JSON object describing the validator's most recent result: {ran, verdict, violations, revisions_applied} The engine copies and frees the returned buffer. NULL return or nullptr callback means no validation block is emitted. (E3, 2.0.6-rc17)

Parameters

provider	JSON builder (nullable clears).
user_data	Forwarded to provider.

Version: 2.0.6-rc17

Parameters

provider	JSON builder callback (nullable).
user_data	Forwarded to provider.

Definition at line 261 of file engine.cpp.

◆ tier_requires_explicit_completion()

bool entropic::AgentEngine::tier_requires_explicit_completion ( const std::string & tier ) const

Check if a tier requires an explicit entropic.complete / entropic.delegate tool call to conclude its turn.

Check if a tier contractually requires explicit completion.

Exposed for unit tests. (P1-6, 2.0.6-rc16)

Parameters

tier	Tier name.

Returns: true if the tier has explicit_completion=true. @utility

Version: 2.0.6-rc16

Delegates to the TierResolutionInterface, falling back to false when no resolver is wired (preserves legacy behavior in tests that omit tier metadata).

Parameters

tier	Tier name.

Returns: true if the tier's explicit_completion flag is set. @utility

Version: 2.0.6-rc16.1

Definition at line 809 of file engine.cpp.

◆ tier_resolution()

const TierResolutionInterface & entropic::AgentEngine::tier_resolution ( ) const

Get the tier resolution interface.

Returns: Tier resolution interface reference.

Version: 1.8.6

Returns: Tier resolution interface.

Definition at line 273 of file engine.cpp.

◆ tier_system_prompt()

const std::string & entropic::AgentEngine::tier_system_prompt ( const std::string & name ) const

A tier's resolved system prompt (gh#98).

Backs the batch entry point, which builds each request's messages with its tier's system prompt so same-tier requests share a prompt prefix.

Parameters

name	Tier name.

Returns: The tier's system prompt, or "" if the tier is unknown.

Version: 2.8.0

Parameters

name	Tier name.

Returns: The tier's system prompt, or "" if unknown.

Definition at line 3241 of file engine.cpp.

◆ user_message_queue_depth()

size_t entropic::AgentEngine::user_message_queue_depth ( ) const

Snapshot of the queue depth.

Read queue depth under the queue mutex.

@threadsafety Thread-safe.

Version: 2.1.10

Definition at line 3097 of file engine.cpp.

Member Data Documentation

◆ MAX_DELEGATION_DEPTH

constexpr int entropic::AgentEngine::MAX_DELEGATION_DEPTH = 2

staticconstexpr

Max delegation nesting depth (0=root, 1=child, 2=max).

Version: 1.8.6

Definition at line 66 of file engine.h.

The documentation for this class was generated from the following files:

entropic/core/engine.h
core/engine.cpp

Classes

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AgentEngine()

Member Function Documentation

◆ build_directive_hooks()

◆ callbacks()

◆ cancel_pause()

◆ clear_conversation()

◆ clear_user_message_queue()

◆ compaction_manager()

◆ context_usage()

◆ defang_meta_action_envelope()

◆ delegation_callbacks_snapshot()

◆ directive_processor()

◆ fold_complete_into_assistant()

◆ get_messages()

◆ has_tier()

◆ interrupt()

◆ is_delegation_cycle()

◆ is_delegation_repeat_blocked()

◆ is_running()

◆ last_loop_metrics()

◆ loop_config()

◆ message_count()

◆ pause()

◆ per_tier_metrics()

◆ prepare_next_turn()

◆ queue_user_message()

◆ reset_interrupt()

◆ run()

◆ run_drain_loop()

◆ run_loop()

◆ run_streaming() [1/2]

◆ run_streaming() [2/2]

◆ run_turn() [1/2]

◆ run_turn() [2/2]

◆ run_turn_as()

◆ seconds_since_last_activity()

◆ seed_system_prompt()

◆ seed_system_prompt_for_tier()

◆ set_callbacks()

◆ set_delegation_callbacks()

◆ set_external_interrupt()

◆ set_handoff_rules()

◆ set_hooks()

◆ set_message_queue_capacity()

◆ set_project_dir()

◆ set_queue_observer()

◆ set_relay_single_delegate()

◆ set_session_logger()

◆ set_state_observer()

◆ set_storage()

◆ set_stream_observer()

◆ set_system_prompt()

◆ set_tier_info()

◆ set_tier_resolution()

◆ set_tool_executor()

◆ set_validation_provider()

◆ tier_requires_explicit_completion()

◆ tier_resolution()

◆ tier_system_prompt()

◆ user_message_queue_depth()

Member Data Documentation

◆ MAX_DELEGATION_DEPTH