zeph_core/agent/state/mod.rs
1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Sub-struct definitions for the `Agent` struct.
5//!
6//! Each struct groups a related cluster of `Agent` fields.
7//! All types are `pub(super)` — visible only within the `agent` module.
8
9use std::collections::{HashMap, HashSet, VecDeque};
10use std::path::PathBuf;
11use std::sync::{Arc, RwLock};
12use std::time::Instant;
13
14use tokio::sync::{Notify, mpsc, watch};
15use tokio_util::sync::CancellationToken;
16use zeph_llm::any::AnyProvider;
17use zeph_llm::provider::Message;
18use zeph_llm::stt::SpeechToText;
19
20use crate::config::{ProviderEntry, SecurityConfig, SkillPromptMode, TimeoutConfig};
21use crate::config_watcher::ConfigEvent;
22use crate::context::EnvironmentContext;
23use crate::cost::CostTracker;
24use crate::file_watcher::FileChangedEvent;
25use crate::instructions::{InstructionBlock, InstructionEvent, InstructionReloadState};
26use crate::metrics::MetricsSnapshot;
27use crate::vault::Secret;
28use zeph_config;
29use zeph_memory::TokenCounter;
30use zeph_memory::semantic::SemanticMemory;
31use zeph_sanitizer::ContentSanitizer;
32use zeph_sanitizer::quarantine::QuarantinedSummarizer;
33use zeph_skills::matcher::SkillMatcherBackend;
34use zeph_skills::registry::SkillRegistry;
35use zeph_skills::watcher::SkillEvent;
36
37use super::message_queue::QueuedMessage;
38
39pub(crate) struct MemoryState {
40 pub(crate) memory: Option<Arc<SemanticMemory>>,
41 pub(crate) conversation_id: Option<zeph_memory::ConversationId>,
42 pub(crate) history_limit: u32,
43 pub(crate) recall_limit: usize,
44 pub(crate) summarization_threshold: usize,
45 pub(crate) cross_session_score_threshold: f32,
46 pub(crate) autosave_assistant: bool,
47 pub(crate) autosave_min_length: usize,
48 pub(crate) tool_call_cutoff: usize,
49 pub(crate) unsummarized_count: usize,
50 pub(crate) document_config: crate::config::DocumentConfig,
51 pub(crate) graph_config: crate::config::GraphConfig,
52 pub(crate) compression_guidelines_config: zeph_memory::CompressionGuidelinesConfig,
53 pub(crate) shutdown_summary: bool,
54 pub(crate) shutdown_summary_min_messages: usize,
55 pub(crate) shutdown_summary_max_messages: usize,
56 pub(crate) shutdown_summary_timeout_secs: u64,
57 /// When `true`, hard compaction uses `AnchoredSummary` (structured JSON) instead of
58 /// free-form prose. Falls back to prose on any LLM or validation failure.
59 pub(crate) structured_summaries: bool,
60 /// Top-1 semantic recall score from the most recent `prepare_context` cycle.
61 /// Used by MAR (Memory-Augmented Routing) to bias the bandit toward cheap providers
62 /// when memory confidence is high. Reset to `None` at the start of each turn.
63 pub(crate) last_recall_confidence: Option<f32>,
64 /// Session digest configuration (#2289).
65 pub(crate) digest_config: crate::config::DigestConfig,
66 /// Cached session digest text and its token count, loaded at session start.
67 pub(crate) cached_session_digest: Option<(String, usize)>,
68 /// Context assembly strategy (#2288).
69 pub(crate) context_strategy: crate::config::ContextStrategy,
70 /// Turn threshold for `Adaptive` strategy crossover (#2288).
71 pub(crate) crossover_turn_threshold: u32,
72 /// D-MEM RPE router. `Some` when `graph_config.rpe.enabled = true`.
73 /// Protected by `std::sync::Mutex` for non-async access from `maybe_spawn_graph_extraction`.
74 pub(crate) rpe_router: Option<std::sync::Mutex<zeph_memory::RpeRouter>>,
75 /// Goal text for the current user turn, derived from raw user input (#2483).
76 /// Passed to A-MAC admission control to enable goal-conditioned write gating.
77 /// Reset at the start of each user turn. `None` only before the first user message.
78 pub(crate) goal_text: Option<String>,
79}
80
81pub(crate) struct SkillState {
82 pub(crate) registry: std::sync::Arc<std::sync::RwLock<SkillRegistry>>,
83 pub(crate) skill_paths: Vec<PathBuf>,
84 pub(crate) managed_dir: Option<PathBuf>,
85 pub(crate) trust_config: crate::config::TrustConfig,
86 pub(crate) matcher: Option<SkillMatcherBackend>,
87 pub(crate) max_active_skills: usize,
88 pub(crate) disambiguation_threshold: f32,
89 pub(crate) min_injection_score: f32,
90 pub(crate) embedding_model: String,
91 pub(crate) skill_reload_rx: Option<mpsc::Receiver<SkillEvent>>,
92 pub(crate) active_skill_names: Vec<String>,
93 pub(crate) last_skills_prompt: String,
94 pub(crate) prompt_mode: SkillPromptMode,
95 /// Custom secrets available at runtime: key=hyphenated name, value=secret.
96 pub(crate) available_custom_secrets: HashMap<String, Secret>,
97 pub(crate) cosine_weight: f32,
98 pub(crate) hybrid_search: bool,
99 pub(crate) bm25_index: Option<zeph_skills::bm25::Bm25Index>,
100 pub(crate) two_stage_matching: bool,
101 /// Threshold for confusability warnings (0.0 = disabled).
102 pub(crate) confusability_threshold: f32,
103 /// `SkillOrchestra` RL routing head. `Some` when `rl_routing_enabled = true` and
104 /// weights are loaded or initialized. `None` when RL routing is disabled.
105 pub(crate) rl_head: Option<zeph_skills::rl_head::RoutingHead>,
106 /// Blend weight for RL routing: `final = (1-rl_weight)*cosine + rl_weight*rl_score`.
107 pub(crate) rl_weight: f32,
108 /// Skip RL blending for the first N updates (cold-start warmup).
109 pub(crate) rl_warmup_updates: u32,
110 /// Directory where `/skill create` writes generated skills.
111 /// Defaults to `managed_dir` if `None`.
112 pub(crate) generation_output_dir: Option<std::path::PathBuf>,
113 /// Provider name for `/skill create` generation. Empty = primary.
114 pub(crate) generation_provider_name: String,
115}
116
117pub(crate) struct McpState {
118 pub(crate) tools: Vec<zeph_mcp::McpTool>,
119 pub(crate) registry: Option<zeph_mcp::McpToolRegistry>,
120 pub(crate) manager: Option<std::sync::Arc<zeph_mcp::McpManager>>,
121 pub(crate) allowed_commands: Vec<String>,
122 pub(crate) max_dynamic: usize,
123 /// Receives elicitation requests from MCP server handlers during tool execution.
124 /// When `Some`, the agent loop must process these concurrently with tool result awaiting
125 /// to avoid deadlock (tool result waits for elicitation, elicitation waits for agent loop).
126 pub(crate) elicitation_rx: Option<tokio::sync::mpsc::Receiver<zeph_mcp::ElicitationEvent>>,
127 /// Shared with `McpToolExecutor` so native `tool_use` sees the current tool list.
128 ///
129 /// Two methods write to this `RwLock` — ordering matters:
130 /// - `sync_mcp_executor_tools()`: writes the **full** `self.mcp.tools` set.
131 /// - `apply_pruned_mcp_tools()`: writes the **pruned** subset (used after pruning).
132 ///
133 /// Within a turn, `sync_mcp_executor_tools` must always run **before**
134 /// `apply_pruned_mcp_tools`. The normal call order guarantees this: tool-list
135 /// change events call `sync_mcp_executor_tools` (inside `check_tool_refresh`,
136 /// `handle_mcp_add`, `handle_mcp_remove`), and pruning runs later inside
137 /// `rebuild_system_prompt`. See also: `apply_pruned_mcp_tools`.
138 pub(crate) shared_tools: Option<std::sync::Arc<std::sync::RwLock<Vec<zeph_mcp::McpTool>>>>,
139 /// Receives full flattened tool list after any `tools/list_changed` notification.
140 pub(crate) tool_rx: Option<tokio::sync::watch::Receiver<Vec<zeph_mcp::McpTool>>>,
141 /// Per-server connection outcomes from the initial `connect_all()` call.
142 pub(crate) server_outcomes: Vec<zeph_mcp::ServerConnectOutcome>,
143 /// Per-message cache for MCP tool pruning results (#2298).
144 ///
145 /// Reset at the start of each user turn and whenever the MCP tool list
146 /// changes (via `tools/list_changed`, `/mcp add`, or `/mcp remove`).
147 pub(crate) pruning_cache: zeph_mcp::PruningCache,
148 /// Dedicated provider for MCP tool pruning LLM calls.
149 ///
150 /// `None` means fall back to the agent's primary provider.
151 /// Resolved from `[[llm.providers]]` at build time using `pruning_provider`
152 /// from `ToolPruningConfig`.
153 pub(crate) pruning_provider: Option<zeph_llm::any::AnyProvider>,
154 /// Whether MCP tool pruning is enabled. Mirrors `ToolPruningConfig::enabled`.
155 pub(crate) pruning_enabled: bool,
156 /// Pruning parameters snapshot. Derived from `ToolPruningConfig` at build time.
157 pub(crate) pruning_params: zeph_mcp::PruningParams,
158 /// Pre-computed semantic tool index for embedding-based discovery (#2321).
159 ///
160 /// Built at connect time via `rebuild_semantic_index()`, rebuilt on tool list change.
161 /// `None` when strategy is not `Embedding` or when build failed (fallback to all tools).
162 pub(crate) semantic_index: Option<zeph_mcp::SemanticToolIndex>,
163 /// Active discovery strategy and parameters. Derived from `ToolDiscoveryConfig`.
164 pub(crate) discovery_strategy: zeph_mcp::ToolDiscoveryStrategy,
165 /// Discovery parameters snapshot. Derived from `ToolDiscoveryConfig` at build time.
166 pub(crate) discovery_params: zeph_mcp::DiscoveryParams,
167 /// Dedicated embedding provider for tool discovery. `None` = fall back to the
168 /// agent's primary embedding provider.
169 pub(crate) discovery_provider: Option<zeph_llm::any::AnyProvider>,
170 /// When `true`, show a security warning before prompting for fields whose names
171 /// match sensitive patterns (password, token, secret, key, credential, etc.).
172 pub(crate) elicitation_warn_sensitive_fields: bool,
173}
174
175pub(crate) struct IndexState {
176 pub(crate) retriever: Option<std::sync::Arc<zeph_index::retriever::CodeRetriever>>,
177 pub(crate) repo_map_tokens: usize,
178 pub(crate) cached_repo_map: Option<(String, std::time::Instant)>,
179 pub(crate) repo_map_ttl: std::time::Duration,
180}
181
182/// Snapshot of adversarial policy gate configuration for status display.
183#[derive(Debug, Clone)]
184pub struct AdversarialPolicyInfo {
185 pub provider: String,
186 pub policy_count: usize,
187 pub fail_open: bool,
188}
189
190pub(crate) struct RuntimeConfig {
191 pub(crate) security: SecurityConfig,
192 pub(crate) timeouts: TimeoutConfig,
193 pub(crate) model_name: String,
194 /// Configured name from `[[llm.providers]]` (the `name` field), set at startup and on
195 /// `/provider` switch. Falls back to the provider type string when empty.
196 pub(crate) active_provider_name: String,
197 pub(crate) permission_policy: zeph_tools::PermissionPolicy,
198 pub(crate) redact_credentials: bool,
199 pub(crate) rate_limiter: super::rate_limiter::ToolRateLimiter,
200 pub(crate) semantic_cache_enabled: bool,
201 pub(crate) semantic_cache_threshold: f32,
202 pub(crate) semantic_cache_max_candidates: u32,
203 /// Dependency config snapshot stored for per-turn boost parameters.
204 pub(crate) dependency_config: zeph_tools::DependencyConfig,
205 /// Adversarial policy gate runtime info for /status display.
206 pub(crate) adversarial_policy_info: Option<AdversarialPolicyInfo>,
207 /// Current spawn depth of this agent instance (0 = top-level, 1 = first sub-agent, etc.).
208 /// Used by `build_spawn_context()` to propagate depth to children.
209 pub(crate) spawn_depth: u32,
210 /// Inject `<budget>` XML into the volatile system prompt section (#2267).
211 pub(crate) budget_hint_enabled: bool,
212 /// Per-channel skill allowlist. Skills not matching the allowlist are excluded from the
213 /// prompt. An empty `allowed` list means all skills are permitted (default).
214 pub(crate) channel_skills: zeph_config::ChannelSkillsConfig,
215}
216
217/// Groups feedback detection subsystems: correction detector, judge detector, and LLM classifier.
218pub(crate) struct FeedbackState {
219 pub(crate) detector: super::feedback_detector::FeedbackDetector,
220 pub(crate) judge: Option<super::feedback_detector::JudgeDetector>,
221 /// LLM-backed zero-shot classifier for `DetectorMode::Model`.
222 /// When `Some`, `spawn_judge_correction_check` uses this instead of `JudgeDetector`.
223 pub(crate) llm_classifier: Option<zeph_llm::classifier::llm::LlmClassifier>,
224}
225
226/// Groups security-related subsystems (sanitizer, quarantine, exfiltration guard).
227pub(crate) struct SecurityState {
228 pub(crate) sanitizer: ContentSanitizer,
229 pub(crate) quarantine_summarizer: Option<QuarantinedSummarizer>,
230 /// Whether this agent session is serving an ACP client.
231 /// When `true` and `mcp_to_acp_boundary` is enabled, MCP tool results
232 /// receive unconditional quarantine and cross-boundary audit logging.
233 pub(crate) is_acp_session: bool,
234 pub(crate) exfiltration_guard: zeph_sanitizer::exfiltration::ExfiltrationGuard,
235 pub(crate) flagged_urls: HashSet<String>,
236 /// URLs explicitly provided by the user across all turns in this session.
237 /// Populated from raw user message text; cleared on `/clear`.
238 /// Shared with `UrlGroundingVerifier` to check `fetch`/`web_scrape` calls at dispatch time.
239 pub(crate) user_provided_urls: Arc<RwLock<HashSet<String>>>,
240 pub(crate) pii_filter: zeph_sanitizer::pii::PiiFilter,
241 /// NER classifier for PII detection (`classifiers.ner_model`). When `Some`, the PII path
242 /// runs both regex (`pii_filter`) and NER, then merges spans before redaction.
243 /// `None` when `classifiers` feature is disabled or `classifiers.enabled = false`.
244 #[cfg(feature = "classifiers")]
245 pub(crate) pii_ner_backend: Option<std::sync::Arc<dyn zeph_llm::classifier::ClassifierBackend>>,
246 /// Per-call timeout for the NER PII classifier in milliseconds.
247 #[cfg(feature = "classifiers")]
248 pub(crate) pii_ner_timeout_ms: u64,
249 /// Maximum number of bytes passed to the NER PII classifier per call.
250 ///
251 /// Large tool outputs (e.g. `search_code`) can produce 150+ `DeBERTa` chunks and exceed
252 /// the per-call timeout. Input is truncated at a valid UTF-8 boundary before classification.
253 #[cfg(feature = "classifiers")]
254 pub(crate) pii_ner_max_chars: usize,
255 /// Circuit-breaker threshold: number of consecutive timeouts before NER is disabled.
256 /// `0` means the circuit breaker is disabled (NER is always attempted).
257 #[cfg(feature = "classifiers")]
258 pub(crate) pii_ner_circuit_breaker_threshold: u32,
259 /// Number of consecutive NER timeouts observed since the last successful call.
260 #[cfg(feature = "classifiers")]
261 pub(crate) pii_ner_consecutive_timeouts: u32,
262 /// Set to `true` when the circuit breaker trips. NER is skipped for the rest of the session.
263 #[cfg(feature = "classifiers")]
264 pub(crate) pii_ner_tripped: bool,
265 pub(crate) memory_validator: zeph_sanitizer::memory_validation::MemoryWriteValidator,
266 /// LLM-based prompt injection pre-screener (opt-in).
267 pub(crate) guardrail: Option<zeph_sanitizer::guardrail::GuardrailFilter>,
268 /// Post-LLM response verification layer.
269 pub(crate) response_verifier: zeph_sanitizer::response_verifier::ResponseVerifier,
270 /// Temporal causal IPI analyzer (opt-in, disabled when `None`).
271 pub(crate) causal_analyzer: Option<zeph_sanitizer::causal_ipi::TurnCausalAnalyzer>,
272}
273
274/// Groups debug/diagnostics subsystems (dumper, trace collector, anomaly detector, logging config).
275pub(crate) struct DebugState {
276 pub(crate) debug_dumper: Option<crate::debug_dump::DebugDumper>,
277 pub(crate) dump_format: crate::debug_dump::DumpFormat,
278 pub(crate) trace_collector: Option<crate::debug_dump::trace::TracingCollector>,
279 /// Monotonically increasing counter for `process_user_message` calls.
280 /// Used to key spans in `trace_collector.active_iterations`.
281 pub(crate) iteration_counter: usize,
282 pub(crate) anomaly_detector: Option<zeph_tools::AnomalyDetector>,
283 /// Whether to emit `reasoning_amplification` warnings for quality failures from reasoning
284 /// models. Mirrors `AnomalyConfig::reasoning_model_warning`. Default: `true`.
285 pub(crate) reasoning_model_warning: bool,
286 pub(crate) logging_config: crate::config::LoggingConfig,
287 /// Base dump directory — stored so `/dump-format trace` can create a `TracingCollector` (CR-04).
288 pub(crate) dump_dir: Option<PathBuf>,
289 /// Service name for `TracingCollector` created via runtime format switch (CR-04).
290 pub(crate) trace_service_name: String,
291 /// Whether to redact in `TracingCollector` created via runtime format switch (CR-04).
292 pub(crate) trace_redact: bool,
293 /// Span ID of the currently executing iteration — used by LLM/tool span wiring (CR-01).
294 /// Set to `Some` at the start of `process_user_message`, cleared at end.
295 pub(crate) current_iteration_span_id: Option<[u8; 8]>,
296}
297
298/// Groups agent lifecycle state: shutdown signaling, timing, and I/O notification channels.
299pub(crate) struct LifecycleState {
300 pub(crate) shutdown: watch::Receiver<bool>,
301 pub(crate) start_time: Instant,
302 pub(crate) cancel_signal: Arc<Notify>,
303 pub(crate) cancel_token: CancellationToken,
304 pub(crate) config_path: Option<PathBuf>,
305 pub(crate) config_reload_rx: Option<mpsc::Receiver<ConfigEvent>>,
306 pub(crate) warmup_ready: Option<watch::Receiver<bool>>,
307 pub(crate) update_notify_rx: Option<mpsc::Receiver<String>>,
308 pub(crate) custom_task_rx: Option<mpsc::Receiver<String>>,
309 /// Last known process cwd. Compared after each tool call to detect changes.
310 pub(crate) last_known_cwd: PathBuf,
311 /// Receiver for file-change events from `FileChangeWatcher`. `None` when no paths configured.
312 pub(crate) file_changed_rx: Option<mpsc::Receiver<FileChangedEvent>>,
313 /// Keeps the `FileChangeWatcher` alive for the agent's lifetime. Dropping it aborts the watcher task.
314 pub(crate) file_watcher: Option<crate::file_watcher::FileChangeWatcher>,
315}
316
317/// Minimal config snapshot needed to reconstruct a provider at runtime via `/provider <name>`.
318///
319/// Secrets are stored as plain strings because [`Secret`] intentionally does not implement
320/// `Clone`. They are re-wrapped in `Secret` when passed to `build_provider_for_switch`.
321pub struct ProviderConfigSnapshot {
322 pub claude_api_key: Option<String>,
323 pub openai_api_key: Option<String>,
324 pub gemini_api_key: Option<String>,
325 pub compatible_api_keys: std::collections::HashMap<String, String>,
326 pub llm_request_timeout_secs: u64,
327 pub embedding_model: String,
328}
329
330/// Groups provider-related state: alternate providers, runtime switching, and compaction flags.
331pub(crate) struct ProviderState {
332 pub(crate) summary_provider: Option<AnyProvider>,
333 /// Shared slot for runtime model switching; set by external caller (e.g. ACP).
334 pub(crate) provider_override: Option<Arc<std::sync::RwLock<Option<AnyProvider>>>>,
335 pub(crate) judge_provider: Option<AnyProvider>,
336 /// Dedicated provider for compaction probe LLM calls. Falls back to `summary_provider`
337 /// (or primary) when `None`.
338 pub(crate) probe_provider: Option<AnyProvider>,
339 /// Dedicated provider for `compress_context` LLM calls (#2356).
340 /// Falls back to the primary provider when `None`.
341 pub(crate) compress_provider: Option<AnyProvider>,
342 pub(crate) cached_prompt_tokens: u64,
343 /// Whether the active provider has server-side compaction enabled (Claude compact-2026-01-12).
344 /// When true, client-side compaction is skipped.
345 pub(crate) server_compaction_active: bool,
346 pub(crate) stt: Option<Box<dyn SpeechToText>>,
347 /// Snapshot of `[[llm.providers]]` entries for runtime `/provider` switching.
348 pub(crate) provider_pool: Vec<ProviderEntry>,
349 /// Resolved secrets and timeout settings needed to reconstruct providers at runtime.
350 pub(crate) provider_config_snapshot: Option<ProviderConfigSnapshot>,
351}
352
353/// Groups metrics and cost tracking state.
354pub(crate) struct MetricsState {
355 pub(crate) metrics_tx: Option<watch::Sender<MetricsSnapshot>>,
356 pub(crate) cost_tracker: Option<CostTracker>,
357 pub(crate) token_counter: Arc<TokenCounter>,
358 /// Set to `true` when Claude extended context (`enable_extended_context = true`) is active.
359 /// Read from config at build time, not derived from provider internals.
360 pub(crate) extended_context: bool,
361 /// Shared classifier latency ring buffer. Populated by `ContentSanitizer` (injection, PII)
362 /// and `LlmClassifier` (feedback). `None` when classifiers are not configured.
363 pub(crate) classifier_metrics: Option<Arc<zeph_llm::ClassifierMetrics>>,
364}
365
366/// Groups task orchestration and subagent state.
367pub(crate) struct OrchestrationState {
368 /// On `OrchestrationState` (not `ProviderState`) because this provider is used exclusively
369 /// by `LlmPlanner` during orchestration, not shared across subsystems.
370 pub(crate) planner_provider: Option<AnyProvider>,
371 /// Provider for `PlanVerifier` LLM calls. `None` falls back to the primary provider.
372 /// On `OrchestrationState` for the same reason as `planner_provider`.
373 pub(crate) verify_provider: Option<AnyProvider>,
374 /// Graph waiting for `/plan confirm` before execution starts.
375 pub(crate) pending_graph: Option<crate::orchestration::TaskGraph>,
376 /// Cancellation token for the currently executing plan. `None` when no plan is running.
377 /// Created fresh in `handle_plan_confirm()`, cancelled in `handle_plan_cancel()`.
378 ///
379 /// # Known limitation
380 ///
381 /// Token plumbing is ready; the delivery path requires the agent message loop to be
382 /// restructured so `/plan cancel` can be received while `run_scheduler_loop` holds
383 /// `&mut self`. See follow-up issue #1603 (SEC-M34-002).
384 pub(crate) plan_cancel_token: Option<CancellationToken>,
385 /// Manages spawned sub-agents.
386 pub(crate) subagent_manager: Option<crate::subagent::SubAgentManager>,
387 pub(crate) subagent_config: crate::config::SubAgentConfig,
388 pub(crate) orchestration_config: crate::config::OrchestrationConfig,
389 /// Lazily initialized plan template cache. `None` until first use or when
390 /// memory (`SQLite`) is unavailable.
391 pub(crate) plan_cache: Option<crate::orchestration::PlanCache>,
392 /// Goal embedding from the most recent `plan_with_cache()` call. Consumed by
393 /// `finalize_plan_execution()` to cache the completed plan template.
394 pub(crate) pending_goal_embedding: Option<Vec<f32>>,
395}
396
397/// Groups instruction hot-reload state.
398pub(crate) struct InstructionState {
399 pub(crate) blocks: Vec<InstructionBlock>,
400 pub(crate) reload_rx: Option<mpsc::Receiver<InstructionEvent>>,
401 pub(crate) reload_state: Option<InstructionReloadState>,
402}
403
404/// Groups experiment feature state (gated behind `experiments` feature flag).
405pub(crate) struct ExperimentState {
406 pub(crate) config: crate::config::ExperimentConfig,
407 /// Cancellation token for a running experiment session. `Some` means an experiment is active.
408 pub(crate) cancel: Option<tokio_util::sync::CancellationToken>,
409 /// Pre-built config snapshot used as the experiment baseline (agent path).
410 pub(crate) baseline: crate::experiments::ConfigSnapshot,
411 /// Dedicated judge provider for evaluation. When `Some`, the evaluator uses this provider
412 /// instead of the agent's primary provider, eliminating self-judge bias.
413 pub(crate) eval_provider: Option<AnyProvider>,
414 /// Receives completion/error messages from the background experiment engine task.
415 /// Always present so the select! branch compiles unconditionally.
416 pub(crate) notify_rx: Option<tokio::sync::mpsc::Receiver<String>>,
417 /// Sender end paired with `experiment_notify_rx`. Cloned into the background task.
418 pub(crate) notify_tx: tokio::sync::mpsc::Sender<String>,
419}
420
421/// Output of a background subgoal extraction LLM call.
422pub(crate) struct SubgoalExtractionResult {
423 /// Current subgoal the agent is working toward.
424 pub(crate) current: String,
425 /// Just-completed subgoal, if the LLM detected a transition (`COMPLETED:` non-NONE).
426 pub(crate) completed: Option<String>,
427}
428
429/// Groups context-compression feature state (gated behind `context-compression` feature flag).
430pub(crate) struct CompressionState {
431 /// Cached task goal for TaskAware/MIG pruning. Set by `maybe_compact()`,
432 /// invalidated when the last user message hash changes.
433 pub(crate) current_task_goal: Option<String>,
434 /// Hash of the last user message when `current_task_goal` was populated.
435 pub(crate) task_goal_user_msg_hash: Option<u64>,
436 /// Pending background task for goal extraction. Spawned fire-and-forget when the user message
437 /// hash changes; result applied at the start of the next Soft compaction (#1909).
438 pub(crate) pending_task_goal: Option<tokio::task::JoinHandle<Option<String>>>,
439 /// Pending `SideQuest` eviction result from the background LLM call spawned last turn.
440 /// Applied at the START of the next turn before compaction (PERF-1 fix).
441 pub(crate) pending_sidequest_result: Option<tokio::task::JoinHandle<Option<Vec<usize>>>>,
442 /// In-memory subgoal registry for `Subgoal`/`SubgoalMig` pruning strategies (#2022).
443 pub(crate) subgoal_registry: crate::agent::compaction_strategy::SubgoalRegistry,
444 /// Pending background subgoal extraction task.
445 pub(crate) pending_subgoal: Option<tokio::task::JoinHandle<Option<SubgoalExtractionResult>>>,
446 /// Hash of the last user message when subgoal extraction was scheduled.
447 pub(crate) subgoal_user_msg_hash: Option<u64>,
448}
449
450/// Groups per-session I/O and policy state.
451pub(crate) struct SessionState {
452 pub(crate) env_context: EnvironmentContext,
453 pub(crate) response_cache: Option<std::sync::Arc<zeph_memory::ResponseCache>>,
454 /// Parent tool call ID when this agent runs as a subagent inside another agent session.
455 /// Propagated into every `LoopbackEvent::ToolStart` / `ToolOutput` so the IDE can build
456 /// a subagent hierarchy.
457 pub(crate) parent_tool_use_id: Option<String>,
458 /// Optional status channel for sending spinner/status messages to TUI or stderr.
459 pub(crate) status_tx: Option<tokio::sync::mpsc::UnboundedSender<String>>,
460 /// LSP context injection hooks. Fires after native tool execution, injects
461 /// diagnostics/hover notes as `Role::System` messages before the next LLM call.
462 pub(crate) lsp_hooks: Option<crate::lsp_hooks::LspHookRunner>,
463 /// Snapshot of the policy config for `/policy` command inspection.
464 pub(crate) policy_config: Option<zeph_tools::PolicyConfig>,
465 /// `CwdChanged` hook definitions extracted from `[hooks]` config.
466 pub(crate) hooks_config: HooksConfigSnapshot,
467}
468
469/// Extracted hook lists from `[hooks]` config, stored in `SessionState`.
470#[derive(Default)]
471pub(crate) struct HooksConfigSnapshot {
472 /// Hooks fired when working directory changes.
473 pub(crate) cwd_changed: Vec<zeph_config::HookDef>,
474 /// Hooks fired when a watched file changes.
475 pub(crate) file_changed_hooks: Vec<zeph_config::HookDef>,
476}
477
478// Groups message buffering and image staging state.
479pub(crate) struct MessageState {
480 pub(crate) messages: Vec<Message>,
481 // QueuedMessage is pub(super) in message_queue — same visibility as this struct; lint suppressed.
482 #[allow(private_interfaces)]
483 pub(crate) message_queue: VecDeque<QueuedMessage>,
484 /// Image parts staged by `/image` commands, attached to the next user message.
485 pub(crate) pending_image_parts: Vec<zeph_llm::provider::MessagePart>,
486}
487
488#[cfg(test)]
489mod tests;