phi_core/agent_loop/

config.rs

use crate::context::{ContextConfig, ExecutionLimits};
use crate::provider::context_translation::ContextTranslationStrategy;
use crate::provider::{ModelConfig, ResponseFormat, StreamProvider};
use crate::types::*;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;

// ── Context transformation callbacks ────────────────────────────────────────
/// All hook types use `Arc` (shared ownership) so they can be cloned into closures
/// and stored without lifetime complications. `Box<dyn Fn>` would suffice for single-owner
/// cases but `Arc` makes it trivially cheap to share across async tasks.
/// Converts `AgentMessage[]` → `Message[]` before each LLM call.
pub type ConvertToLlmFn = Arc<dyn Fn(&[AgentMessage]) -> Vec<Message> + Send + Sync>;
/// Transforms the full context before `convert_to_llm` (for pruning, reordering, injection).
pub type TransformContextFn = Arc<dyn Fn(Vec<AgentMessage>) -> Vec<AgentMessage> + Send + Sync>;
/// Returns pending messages (steering interrupts or follow-up work) when polled.
pub type GetMessagesFn = Box<dyn Fn() -> Vec<AgentMessage> + Send + Sync>;

// ── 0.9.0 async lifecycle hooks ─────────────────────────────────────────────
//
// All lifecycle Fn types below are async-trait-style boxed futures. To
// construct one from a sync closure body:
//
// ```rust,ignore
// let hook: BeforeTurnFn = Arc::new(|messages, turn| {
//     Box::pin(async move {
//         // sync logic ...
//         true
//     })
// });
// ```
//
// For async closure bodies, simply `.await` inside the `async move` block.

/// Boxed-future return type used by all 0.9.0 async lifecycle hooks. `T` is the
/// hook's logical return value (often `bool` for veto-returning hooks or `()`
/// for fire-and-forget hooks).
pub type HookFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;

// ── Loop hooks ───────────────────────────────────────────────────────────────
/// Called once before the entire agent loop begins (before `AgentStart` is emitted).
///
/// Arguments: `(messages, loop_index)` — `messages` is the full context at the time of the call;
/// `loop_index` is always `0` (reserved for future multi-loop scenarios).
/// Return `false` to abort: `AgentEnd` is emitted immediately with an empty message list.
///
/// 0.9.0: async hook. Wrap sync bodies in `Box::pin(async move { ... })`.
pub type BeforeLoopFn =
    Arc<dyn for<'a> Fn(&'a [AgentMessage], usize) -> HookFuture<'a, bool> + Send + Sync>;
/// Called once after the entire agent loop ends (after `AgentEnd` is emitted).
///
/// Arguments: `(new_messages, accumulated_usage)` — `new_messages` are the messages produced
/// by this loop call; `accumulated_usage` sums input/output tokens across all turns.
///
/// 0.9.0: async hook.
pub type AfterLoopFn =
    Arc<dyn for<'a> Fn(&'a [AgentMessage], &'a Usage) -> HookFuture<'a, ()> + Send + Sync>;

// ── Turn hooks ───────────────────────────────────────────────────────────────
/// Called before each LLM turn (before `TurnStart` is emitted).
///
/// Arguments: `(messages, turn_index)` — `messages` is the full context (steering messages
/// queued for *this* turn are not yet visible); `turn_index` is 0-based.
/// Return `false` to abort the turn: no `TurnStart`/`TurnEnd` events are emitted,
/// but `AgentEnd` still fires normally.
///
/// 0.9.0: async hook.
pub type BeforeTurnFn =
    Arc<dyn for<'a> Fn(&'a [AgentMessage], usize) -> HookFuture<'a, bool> + Send + Sync>;
/// Called after each LLM turn (after `TurnEnd` is emitted).
///
/// Arguments: `(messages, turn_usage)` — `turn_usage` covers only this turn's tokens.
/// Fires on both the normal path and the error/abort path.
///
/// 0.9.0: async hook.
pub type AfterTurnFn =
    Arc<dyn for<'a> Fn(&'a [AgentMessage], &'a Usage) -> HookFuture<'a, ()> + Send + Sync>;

// ── Tool execution hooks ─────────────────────────────────────────────────────
/// Called before each tool call (before `ToolExecutionStart` is emitted).
///
/// Arguments: `(tool_name, tool_call_id, args)`.
/// Return `false` to skip the call: an error `ToolResult` is synthesised so the LLM still
/// receives a response, but `ToolExecutionStart`/`End` are **not** emitted.
///
/// 0.9.0: async hook.
pub type BeforeToolExecutionFn = Arc<
    dyn for<'a> Fn(&'a str, &'a str, &'a serde_json::Value) -> HookFuture<'a, bool> + Send + Sync,
>;
/// Called after each tool call (after `ToolExecutionEnd` is emitted).
///
/// Arguments: `(tool_name, tool_call_id, is_error)`.
///
/// 0.9.0: async hook.
pub type AfterToolExecutionFn =
    Arc<dyn for<'a> Fn(&'a str, &'a str, bool) -> HookFuture<'a, ()> + Send + Sync>;
/// Called before each incremental tool update (before `ToolExecutionUpdate` is emitted).
///
/// Fires every time a tool calls `ctx.on_update(partial)` — potentially many times per call
/// (e.g. each line of bash output). Arguments: `(tool_name, tool_call_id, text_content)`.
/// Return `false` to suppress the streaming event; the tool keeps running and its final
/// `ToolResult` (what the LLM sees) is **unaffected**.
///
/// 0.10.0: async hook (matches the 9 other lifecycle Fns async-migrated at
/// 0.9.0). Wrap sync bodies in `Box::pin(async move { ... })`. The closure
/// fires from inside the synchronous `ToolUpdateFn` callback that tools
/// invoke during their async execute body; the agent loop bridges to the
/// async hook via a `futures::executor::block_on` shim at the call site —
/// see `agent_loop/tools.rs`.
pub type BeforeToolExecutionUpdateFn =
    Arc<dyn for<'a> Fn(&'a str, &'a str, &'a str) -> HookFuture<'a, bool> + Send + Sync>;
/// Called after each incremental tool update (after `ToolExecutionUpdate` is emitted).
///
/// Only fires when the update was *not* suppressed by `BeforeToolExecutionUpdateFn`.
/// Arguments: `(tool_name, tool_call_id, text_content)`.
///
/// 0.10.0: async hook. See [`BeforeToolExecutionUpdateFn`] for the
/// bridging-from-sync-ToolUpdateFn rationale.
pub type AfterToolExecutionUpdateFn =
    Arc<dyn for<'a> Fn(&'a str, &'a str, &'a str) -> HookFuture<'a, ()> + Send + Sync>;

/// Called when the LLM returns `StopReason::Error`. Argument: the error message string.
///
/// 0.9.0: async hook.
pub type OnErrorFn = Arc<dyn for<'a> Fn(&'a str) -> HookFuture<'a, ()> + Send + Sync>;

// ── Compaction hooks (G1) ───────────────────────────────────────────────────
/// Called before compaction starts.
///
/// Arguments: `(estimated_tokens, message_count)`.
/// Return `false` to skip compaction for this cycle.
///
/// 0.9.0: async hook.
pub type BeforeCompactionStartFn =
    Arc<dyn Fn(usize, usize) -> HookFuture<'static, bool> + Send + Sync>;
/// Called after compaction completes.
///
/// Arguments: `(messages_before, messages_after, tokens_before, tokens_after)`.
///
/// 0.9.0: async hook.
pub type AfterCompactionEndFn =
    Arc<dyn Fn(usize, usize, usize, usize) -> HookFuture<'static, ()> + Send + Sync>;

/// All static settings for a single [`agent_loop`] / [`agent_loop_continue`] call.
///
/// Build with the public fields directly or via [`crate::agent::Agent`]'s builder methods.
/// The config is borrowed (`&AgentLoopConfig`) throughout the loop — it is never mutated.
///
/// ## Lifecycle hooks
///
/// All hook fields are `Option<Arc<dyn Fn(...)>>`. `None` means "no hook" (zero overhead).
/// See the module-level doc for the guaranteed ordering relative to [`AgentEvent`]s.
pub struct AgentLoopConfig {
    /// Complete provider identity: model id, api_key, base_url, protocol, compat flags, cost rates.
    /// The agent loop resolves the concrete `StreamProvider` from `model_config.api` via
    /// `ProviderRegistry`. Set `provider_override` to bypass the registry for custom providers.
    pub model_config: ModelConfig,

    /// Custom provider override. When `Some`, bypasses `ProviderRegistry` dispatch and uses
    /// this provider directly. Useful for testing (`MockProvider`) or custom implementations.
    /// When `None` (the default), the provider is resolved from `model_config.api`.
    pub provider_override: Option<Arc<dyn StreamProvider>>,

    pub thinking_level: ThinkingLevel,
    pub max_tokens: Option<u32>,
    pub temperature: Option<f32>,

    /// Convert AgentMessage[] → Message[] before each LLM call.
    /// Default: keep only LLM-compatible messages.
    pub convert_to_llm: Option<ConvertToLlmFn>,

    /// Transform context before convert_to_llm (for pruning, compaction).
    pub transform_context: Option<TransformContextFn>,

    /// Get steering messages (user interruptions mid-run).
    pub get_steering_messages: Option<GetMessagesFn>,

    /// Get follow-up messages (queued work after agent finishes).
    pub get_follow_up_messages: Option<GetMessagesFn>,

    /// Context window configuration (auto-compaction).
    /// Compaction strategies are now part of `ContextConfig.compaction` (G5 consolidation).
    pub context_config: Option<ContextConfig>,

    /// Execution limits (max turns, tokens, duration, cost).
    /// Cost is tracked automatically using `model_config.cost` rates after each turn.
    /// `ExecutionLimits.max_cost` enforcement is active whenever rates are non-zero.
    pub execution_limits: Option<ExecutionLimits>,

    /// Prompt caching configuration.
    pub cache_config: CacheConfig, //from types.rs

    /// Tool execution strategy (sequential, parallel, or batched).
    pub tool_execution: ToolExecutionStrategy, // from types.rs

    /// Per-tool execution timeout.
    ///
    /// When `Some(d)`, each individual `AgentTool::execute()` call is bounded by `d`.
    /// On expiry, the tool's child cancel token is signalled (cooperative cleanup) and a
    /// `ToolError::Timeout` is synthesised as the tool result — the LLM sees the failure
    /// and the agent loop continues. A per-tool override via `AgentTool::timeout()` takes
    /// precedence over this field. `None` (the default) means no per-tool timeout.
    pub tool_timeout: Option<std::time::Duration>,

    /// Retry configuration for transient provider errors.
    pub retry_config: crate::provider::retry::RetryConfig,

    //******* Callbacks Turn *******
    /// Called before each LLM turn. Return `false` to abort the turn.
    pub before_turn: Option<BeforeTurnFn>,
    /// Called after each LLM turn with the current messages and the turn's usage.
    pub after_turn: Option<AfterTurnFn>,

    //******* Callbacks Loop *******
    /// Called before each Agent loop. Return `false` to abort the loop.
    pub before_loop: Option<BeforeLoopFn>,
    /// Called after each Agent loop with the current messages and the loop's usage.
    pub after_loop: Option<AfterLoopFn>,

    //******* Callbacks Tool Execution *******
    /// Called before each tool execution. Return `false` to skip the tool call.
    pub before_tool_execution: Option<BeforeToolExecutionFn>,
    /// Called after each tool execution.
    pub after_tool_execution: Option<AfterToolExecutionFn>,
    /// Called before each ToolExecutionUpdate event. Return `false` to suppress the event.
    pub before_tool_execution_update: Option<BeforeToolExecutionUpdateFn>,
    /// Called after each ToolExecutionUpdate event.
    pub after_tool_execution_update: Option<AfterToolExecutionUpdateFn>,

    /// Called when the LLM returns a `StopReason::Error`.
    pub on_error: Option<OnErrorFn>,

    //******* Callbacks Compaction (G1) *******
    /// Called before compaction starts. Return `false` to skip compaction.
    pub before_compaction_start: Option<BeforeCompactionStartFn>,
    /// Called after compaction completes.
    pub after_compaction_end: Option<AfterCompactionEndFn>,

    /// Input filters applied to user messages before the LLM call.
    /// Filters run in order; first `Reject` wins and discards any accumulated
    /// warnings. `Warn` messages accumulate and are appended to the user message.
    pub input_filters: Vec<Arc<dyn InputFilter>>, // from types.rs

    /// The trigger type for the first TurnStart event in this run.
    /// Defaults to `TurnTrigger::User`; set to `SubAgent` by sub-agent callers.
    pub first_turn_trigger: TurnTrigger,

    /// Stable identity for this config, used as the middle segment of `loop_id`:
    ///   `loop_id = "{session_id}.{config_id}.{N}"`
    ///
    /// When `None` and the `Agent` wrapper is used, the identity is auto-derived by
    /// `Agent::next_loop_id()` from the provider, model, and thinking level:
    ///   `"{provider_id}.{model_slug}[.thinking]"`
    ///
    /// For direct callers of `agent_loop`, set `context.loop_id` explicitly — this field
    /// is only read by `Agent::next_loop_id()` and has no effect inside `agent_loop` itself.
    ///
    /// Set explicitly for human-readable or deterministic loop IDs, e.g.:
    ///   `config.config_id = Some("experiment-A".to_string());`
    ///   → loop IDs: `ses_xyz.experiment-A.1`, `ses_xyz.experiment-A.2`, …
    pub config_id: Option<String>,

    /// G8 — Optional context translation strategy for cross-provider compatibility.
    ///
    /// When set, messages are translated through this strategy before being sent to
    /// the LLM provider. This allows content types from one provider (e.g.,
    /// `Content::Thinking` from Anthropic) to be translated or removed when targeting
    /// a different provider. The translation is read-only — originals are never modified.
    pub context_translation: Option<Arc<dyn ContextTranslationStrategy>>,

    /// Shared state for PrunTool to communicate pruning requests to the loop.
    pub prun_pending: Option<Arc<std::sync::Mutex<Vec<crate::tools::prun::PrunRequest>>>>,

    /// Shared state for [`RevertTool`](crate::tools::RevertTool) to communicate
    /// revert requests to the loop. `Some` iff the agent was constructed via
    /// [`BasicAgent::with_revert_tool`](crate::agents::BasicAgent::with_revert_tool);
    /// `apply_revert` (Phase 3) is gated on this being `Some`, so the LLM has
    /// no path to invoke the tool when the builder did not opt in.
    pub revert_pending: Option<Arc<std::sync::Mutex<Vec<crate::tools::revert::RevertRequest>>>>,

    /// Shared slot recording the currently-executing tool.
    ///
    /// `Some(Arc<Mutex<Option<CurrentToolExecution>>>)` when the agent loop is
    /// constructed via [`BasicAgent`](crate::agents::BasicAgent) (always
    /// installed by `build_config`); `None` for direct callers of
    /// `agent_loop()` who do not need pause-time introspection.
    ///
    /// The agent loop's `execute_single_tool` writes
    /// `Some(CurrentToolExecution { name, timeout })` immediately before
    /// invoking `AgentTool::execute()` and resets to `None` on return. External
    /// consumers read the slot via the shared `Arc<Mutex<...>>` — see
    /// [`BasicAgent::current_tool_timeout`](crate::agents::BasicAgent::current_tool_timeout).
    ///
    /// Single-tool model: under parallel / batched execution the slot reflects
    /// the most-recently-started tool. See
    /// [`CurrentToolExecution`](crate::context::CurrentToolExecution) for the
    /// race-window characterization.
    pub current_tool: Option<Arc<std::sync::Mutex<Option<crate::context::CurrentToolExecution>>>>,

    /// Kind-aware render policy for Composition I trunk-context assembly.
    ///
    /// Consumed by the agent loop's context-build site
    /// (`stream_assistant_response`) only when revert mode is active
    /// (`active_node_id` is `Some`) — i.e. when the agent was constructed via
    /// [`BasicAgent::with_revert_tool`](crate::agents::BasicAgent::with_revert_tool)
    /// and `apply_revert` has set the active trunk pointer at least once.
    /// Outside revert mode this field has no effect; the linear
    /// [`build_working_context`](crate::types::AgentContext::build_working_context)
    /// path is byte-identical to pre-0.10 behaviour.
    ///
    /// Defaults to `RevertRenderPolicy::default()` (5-turn window,
    /// 3-tag-per-kind count cap). Override via
    /// [`BasicAgent::with_revert_render_policy`](crate::agents::BasicAgent::with_revert_render_policy)
    /// when downstream operators (e.g. i-phi's braking config) need a
    /// different decay window.
    pub revert_render_policy: RevertRenderPolicy,

    /// Desired LLM output shape. Default `Text` preserves the historical free-form
    /// behaviour; `JsonObject` / `JsonSchema` request constrained structured output
    /// from providers that support it. See `provider::ResponseFormat` and the
    /// capability matrix in `docs/specs/developer/provider.md`.
    pub response_format: ResponseFormat,
}