Struct LlmAgentBehavior 

pub struct LlmAgentBehavior { /* private fields */ }

Implementations

impl LlmAgentBehavior

pub fn new(llm: Arc<dyn LlmClient>, tools: Arc<ToolRegistry>) -> Self

pub fn with_reply_transformers(self, chain: OutboundReplyTransformChain) -> Self

Install the outbound reply transform chain. Replaces any previously-installed chain. Pass OutboundReplyTransformChain::empty() to disable.

pub fn with_plugin_skill_roots(self, roots: Vec<PathBuf>) -> Self

Install the plugin-contributed skill roots returned by wire_plugin_registry. Empty vec preserves legacy behavior (operator’s skills_dir is the only source). Operator-priority is preserved by the loader’s search order — see SkillLoader::candidate_paths.

pub fn with_mutation_hook( self, hook: Arc<dyn MemoryMutationHook>, tenant: impl Into<String>, ) -> Self

Wire the mutation observer. Successful compaction_store.insert calls fire a SqliteCompactions/Insert event onto nexo.memory.mutated.<agent_id> with the session id as the correlation key. Best-effort: hook failures are swallowed.

pub fn with_memory_extractor( self, extractor: Arc<dyn MemoryExtractor>, memory_dir: PathBuf, ) -> Self

Wire post-turn memory extraction. When set, every successful run_turn ticks the extractor and fires extraction against memory_dir. Mirrors driver-loop’s per-turn wire; both engines share the same Arc<ExtractMemories> so cadence + circuit breaker + in-progress mutex stay coherent across paths.

Provider-agnostic: Arc<dyn MemoryExtractor> keeps any concrete impl pluggable (today ExtractMemories from nexo-driver-loop).

pub fn with_compaction( self, summarizer: Arc<dyn LlmClient>, store: Arc<CompactionStore>, runtime: CompactionRuntime, ) -> Self

Wire the online compactor. All three handles must be supplied together; passing enabled: true in runtime without the wiring is a no-op (logged on first turn so the gap is visible). summarizer is the LLM client used to produce the summary itself — most operators reuse the agent’s main model; pass a dedicated cheaper client to save spend.

pub fn with_token_counter(self, counter: Arc<dyn TokenCounter>) -> Self

Attach a TokenCounter. Boot time pick this from nexo_llm::token_counter::build() based on llm.context_optimization.token_counter.backend. When omitted, pre-flight sizing is skipped (zero metrics, zero overhead).

pub fn with_workspace_cache(self, cache: Arc<WorkspaceCache>) -> Self

Attach the shared workspace cache. When set, run_turn reads the workspace bundle via WorkspaceCache::get (warm Arc, no disk I/O on the hot path); when omitted, falls back to a fresh WorkspaceLoader every turn (legacy / test path).

pub fn with_prompt_cache(self, enabled: bool) -> Self

Opt the agent into provider-level prompt caching. Driven from llm.context_optimization.prompt_cache.enabled (or the per-agent override). Defaults to false so the legacy non-cached path stays the safe fallback.

pub fn with_tool_policy(self, p: Arc<ToolPolicy>) -> Self

Attach a tool-execution policy. Controls caching + parallel execution of tool calls. Defaults to a no-op policy.

Pre-builds the relevance filter (if enabled) so the per-turn hot path stays O(1) instead of re-tokenizing the full tool catalog on every message.

pub async fn rebuild_tool_filter(&self)

Rebuild the relevance filter index — call after the tool set changes (extension hot-reload, runtime registration). Idempotent.

pub fn with_max_iterations(self, n: usize) -> Self

pub fn with_hooks(self, hooks: Arc<HookRegistry>) -> Self

Attach an extension hook registry. Without this, hook fire sites are no-ops and behavior is identical to pre-11.6 operation.

pub fn with_rate_limiter(self, rl: Arc<ToolRateLimiter>) -> Self

Attach per-tool rate limiter. Denied calls surface as outcome="rate_limited" and are not routed to the handler.

pub fn with_schema_validator(self, v: Arc<ToolArgsValidator>) -> Self

Attach the JSON Schema args validator. Denied calls surface as outcome="invalid_args" with the path of the offending field(s) in the result, so the LLM can retry.

Trait Implementations

impl AgentBehavior for LlmAgentBehavior

fn on_heartbeat<'life0, 'life1, 'async_trait>( &'life0 self, ctx: &'life1 AgentContext, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn on_message_control<'life0, 'life1, 'async_trait>( &'life0 self, ctx: &'life1 AgentContext, msg: InboundMessage, ) -> Pin<Box<dyn Future<Output = Result<AgentTurnControl>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn on_message<'life0, 'life1, 'async_trait>( &'life0 self, ctx: &'life1 AgentContext, msg: InboundMessage, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn decide<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ctx: &'life1 AgentContext, msg: &'life2 InboundMessage, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Stub for LLM reasoning. Returns empty string by default.

fn on_event<'life0, 'life1, 'async_trait>( &'life0 self, _ctx: &'life1 AgentContext, _event: Event, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,