//! Agent loop engine — consumes `Action`s, drives the provider, dispatches tools, emits `Event`s. //! //! Unidirectional flow: `Engine::spawn()` returns `(ActionTx, EventRx)`. A background task //! owns the session + provider; on `SubmitUserMessage` it runs a **turn**, which is an //! inner agentic loop: append user msg → build request from the full active path → stream → //! append the assistant reply (text + tool calls) → if it called tools, run them, append the //! results, and loop so the model actually sees its tool output → stop when the model //! answers with no tool calls (or `max_tool_iterations` trips the runaway guard). //! //! `AgentEnd` fires exactly once per turn, in `Engine::run`, so the loop hooks //! (self-continuation, runaway guards, …) see one event per turn. use futures::StreamExt; use std::collections::{HashMap, HashSet}; use std::sync::atomic::{AtomicBool, AtomicU32}; use std::sync::Arc; use tokio::sync::{mpsc, watch}; use tracing::{debug, error, warn}; use crate::compaction::CompactionSettings; use crate::context::{PromptContext, SystemPromptBuilder}; use crate::event::{EngineState, Event, GuidedReviewFailure, ModelRef, SessionMessage, StopReason}; use crate::guided_review::{ ActiveReviewRecord, ActiveReviewRecordStore, AgentTurnId, GuideManifest, GuidedReview, GuidedReviewError, LastTurnRecord, LastTurnRecordStore, LocalGit, ReviewContextDraft, ReviewId, ReviewLoadRequestId, ReviewRevisionId, ReviewTarget, TurnBaselineArtifact, TurnBaselineId, UntrackedSourcePolicy, }; use crate::hook::{HookCtx, HookEvent, HookOutcome, HookPoint, HookRegistry}; use crate::message::{ContentBlock, Message, Role}; use crate::permission::{ AskResolution, Check, PermissionAction, PermissionReply, DOOM_LOOP, HOOK_ASK, }; use crate::provider::{CompletionRequest, Provider, ProviderError, ProviderEvent}; use crate::session::{EntryId, EntryKind, SessionError, SessionId, SessionStore}; use crate::todo::TodoStore; use crate::tool::{Tool, ToolContext, ToolRegistry, ToolResultData}; use crate::tool_pairing::Unfinished; /// The agent loop engine. pub struct Engine { config: EngineConfig, cancel_tx: watch::Sender, /// The mode the session is in, by name current_mode: tokio::sync::Mutex, /// The mode the model was last told about, which is the one the transcript says it is in. /// /// A switch is announced on the next message rather than when it happens, so toggling twice /// before sending tells the model nothing — and a new or loaded transcript starts from the /// default, since nothing in it says otherwise. announced_mode: tokio::sync::Mutex, /// Whether a `/review` is running, so a second request waits for the first review_running: std::sync::atomic::AtomicBool, /// The model this session is on, when it is not `config.model`. /// /// Set by `Action::SetModel` and by a mode's model. Always the *full* `ModelInfo`, so a /// switch to another model — or another provider — brings its own context window, thinking map /// and prices rather than borrowing the launch model's and reporting fiction. active_model_info: tokio::sync::Mutex>, /// The reasoning level this session runs at — the level *requested*, which both read sites clamp /// to what the active model can honor. Starts from the launch model's own configured level. active_thinking: tokio::sync::Mutex, /// Reasoning level the user asked for on each model this session, keyed by `provider/id`. /// /// What makes a model's configured starting level (`models.json`'s `thinking`) a default rather /// than a ceiling: switching away and back restores the level you chose for that model, while a /// model you have not touched still starts where its config says. Only an explicit /// `SetThinkingLevel` writes here — an automatic application must not look like a decision. chosen_thinking: tokio::sync::Mutex>, /// The model and thinking level a mode overrode, put back on the next mode switch. /// /// Without it a mode's override outlives the mode: plan on its own model, then build, leaves /// the build on the plan's model. `None` when no override is in force, and cleared by an /// explicit `SetModel` or `SetThinkingLevel`, since a choice made while in a mode is the user's /// and not the mode's. before_mode: tokio::sync::Mutex>, /// The current leaf entry — user messages and turns chain from here so the full /// conversation (not just the latest message) reaches the provider. `None` until the /// first turn resolves it from the session's last entry. current_leaf: tokio::sync::Mutex>, /// Mutable session id — updated when loading/resuming a session so the next turn chains /// from the resumed state, matching the `--resume` path. session_id: tokio::sync::Mutex, /// This process's claim on `session_id`, which keeps a second luxe from writing it too session_claim: std::sync::Mutex>, last_turn_baseline: tokio::sync::Mutex>, active_guided_review: Arc>, /// The one owner of the open review and its feedback session, running beside the engine review_desk: review_desk::ReviewDeskHandle, /// The desk's inbox, until `run` starts the desk with the event stream it reports on review_desk_inbox: std::sync::Mutex>, /// What each confirm confirms, under the request that prepared it previews: Arc>, accepted_feedback_submissions: HashSet, pending_feedback: HashMap, /// Set when a session with prior messages is loaded; its next message carries the briefing resume_briefing_pending: AtomicBool, /// Context the session's first message carries, once: an issue taken up with `--issue` pending_brief: tokio::sync::Mutex>, /// The read-only turn running, if one is: while set, the dispatch choke point lets only /// reading through read_only: Option, /// Which line of the ledger the running turn bills to: the agent's, except while drafting a /// review's summary, which is part of what that review cost turn_source: crate::usage::UsageSource, /// The drafting turn's final answer, which carries the draft draft_answer: tokio::sync::Mutex>, /// The conversation entries drafts have already carried, so a later one sends only what is new sent_digests: tokio::sync::Mutex, /// Live permission policy. Behind a mutex because a session "always" approval mutates it. permission: Arc>, /// How an `ask` decision is resolved (prompt the UI, or auto-allow/deny when headless). ask_resolution: crate::permission::AskResolution, /// Bridges a blocked tool dispatch to its `RespondPermission` reply. permission_broker: Arc, /// Bridges a blocked interactive `question` tool call to its `AnswerQuestion` reply. question_broker: Arc, /// Runtime auto-approve override: when set, `ask` collapses to allow regardless of /// `ask_resolution` (the `/permissions` toggle / walk-away mode). permission_auto_approve: Arc, /// Consecutive-identical-call counter (hash, count) backing the doom-loop guard. recent_tool_call: tokio::sync::Mutex>, /// `(consecutive failing test runs, already-nudged?)` backing the debugger nudge. test_failure_state: tokio::sync::Mutex<(u32, bool)>, /// Exact context occupancy (tokens) from the provider's most recent usage event; 0 until the /// first turn resolves it. Compaction prefers this over the char/4 estimate. last_context_tokens: AtomicU32, /// The system prompt this session sends, written on its first turn prompt_snapshot: std::sync::Mutex>, /// Estimated tokens the last request spent before any conversation — system prompt plus tool /// schemas. Recorded where the request is built, because that is the only place both halves /// are resolved, and read by compaction, which has to know how much of the window is already /// gone before it decides how much conversation may stay. last_prefix_tokens: AtomicU32, /// Consecutive auto-compaction failures. Trips a circuit breaker (see /// [`crate::compaction::compaction_circuit_open`]) so a persistently failing summarizer stops /// being retried every turn; a success resets it. compaction_failures: AtomicU32, /// Steering messages admitted mid-turn, waiting for the next inter-iteration checkpoint. /// /// A turn can't take a new message the instant it arrives — the provider call and its tool /// dispatch are already in flight — so a steer is buffered here and delivered as a real user /// message before the next provider call, in admission order. pending_steers: tokio::sync::Mutex>, /// Actions that arrived during a turn and wait for it, in the order they arrived. /// /// Drained by the main loop ahead of the channel, because everything in here arrived before /// anything still in the channel. Sent back into that channel, the turn's own loop would read /// them straight out again — spinning for the length of the turn and reordering them, so a /// cancel sent after its submission could land before it and cancel nothing. deferred_actions: std::sync::Mutex>, /// Actions the engine handed itself, lined up behind the channel by [`Engine::next_action`] continuations: std::sync::Mutex>, /// The session's running spend. Every provider call in the process records here — the turn /// loop, the review's guide pass, and the compaction summarizer alike — so no UI has to /// reconstruct a total from the event stream, and no call site can spend unobserved. usage_ledger: usage::SessionLedgers, /// Keeps the last request's prompt cache alive through a long wait (`agent.cache_warming`). cache_warmer: cache_warmer::CacheWarmer, } impl Engine { /// The directory whose instruction chain applies to this session. /// /// One owner, because three places ask: the prompt that injects `AGENTS.md`, the notice that /// reports a file it had to truncate, and `/context`'s accounting of the same. See /// [`EngineConfig::invoked_from`] for why it is not simply the process's directory. pub(crate) fn instruction_dir(&self) -> std::path::PathBuf { instruction_dir_of(self.config.invoked_from.as_deref()) } /// Raise or lower the turn's cancel flag. /// /// `watch::Sender::send` is a **no-op when nobody is subscribed** — it returns `Err` and /// leaves the value alone — and nobody is subscribed between turns, because every receiver /// here is a transient `subscribe()` taken by a provider stream or a tool dispatch. So the /// two things this flag must do, it did not do: a cancel raised during the gap was dropped, /// and the reset at the top of the next turn never lowered the flag a cancel had raised. That /// second one bricked sessions — the next turn's stream was born cancelled, produced no /// events, and committed an empty message the provider then rejected forever. pub(crate) fn set_cancelled(&self, cancelled: bool) { self.cancel_tx.send_replace(cancelled); } /// Whether the turn in flight has been told to stop. pub(crate) fn is_cancelled(&self) -> bool { *self.cancel_tx.borrow() } } pub use action::*; pub use config::*; pub use error::*; pub(crate) use review_state::{ActiveGuidedReview, RetainedTurnBaseline}; pub(crate) use turn::{malformed_arguments, parse_tool_arguments, ToolCallInfo}; pub use types::*; mod action; mod agent_turn; mod answering; mod cache_warmer; use agent_turn::TurnFlow; mod compact; mod composition; mod config; mod construction; mod dispatch; mod drafting; mod error; mod github_change; mod github_list; mod github_overview; mod github_post; mod guide_run; mod inbox; mod read_only; mod requested_review; mod review_feedback; mod session_turns; mod settings; pub use settings::Carryover; mod startup; pub use drafting::{DraftRequest, DraftTarget, FindingEvidence, ReviewDraft}; pub use github_change::{PullRequestChange, PullRequestWrite}; pub use github_post::GithubPost; pub use review_desk::{CommentDraft, ReviewEdit}; pub use review_feedback::PULL_REQUEST_FIXES_REFUSED; mod guided_review; mod lifecycle; mod nested_instructions; mod opening; mod posting; mod previews; mod project_reads; mod prompt; mod prompt_snapshot; mod restacking; mod review_commit; mod review_desk; mod review_state; mod run; mod stack_opening; mod turn; mod types; mod usage; /// [`Engine::instruction_dir`] over the one field it reads, so the fallback is testable without /// standing up an engine. fn instruction_dir_of(invoked_from: Option<&std::path::Path>) -> std::path::PathBuf { invoked_from .map(std::path::Path::to_path_buf) .or_else(|| std::env::current_dir().ok()) .unwrap_or_else(|| std::path::PathBuf::from(".")) } #[cfg(test)] mod instruction_dir_tests { use super::instruction_dir_of; /// A monorepo keeps shared rules at the root and specific ones beside the code, and `luxe` /// launched in `packages/app` is meant to get both. Since the launch moves the process to the /// project root, the only thing that still remembers which package that was is this field — /// drop it and the nested file goes quiet, with nothing failing to say so. #[test] fn the_launch_directory_outranks_the_one_the_process_moved_to() { let launched_in = std::path::Path::new("/work/monorepo/packages/app"); assert_eq!(instruction_dir_of(Some(launched_in)), launched_in); } /// An embedder never moved, so its own directory is the honest answer. #[test] fn nothing_recorded_falls_back_to_the_process() { let expected = std::env::current_dir().expect("a working directory"); assert_eq!(instruction_dir_of(None), expected); } } #[cfg(test)] mod tests;