1pub mod cache;
9pub mod contract;
10pub mod gate;
11pub mod provider;
12pub mod run;
13
14pub use cache::WriteCache;
15pub use provider::{LlmHandle, ModelIdent};
16pub use run::{OutputSpec, RunStats, TaskOutcome, WriteConfig, WriteOutcome, WriteTask, run_tasks};
17
18use std::path::{Path, PathBuf};
19use std::str::FromStr;
20
21#[derive(Debug, Clone, Default)]
23pub struct WriteOptions {
24 pub mode: LlmMode,
25 pub force: ForceScope,
26 pub dry_run: bool,
27 pub concurrency: Option<usize>,
28 pub max_llm_tokens: Option<u64>,
29 pub cache_dir: Option<PathBuf>,
30 pub no_prune: bool,
31 pub model: Option<String>,
32 pub explain: bool,
34}
35
36impl WriteOptions {
37 pub fn off() -> Self {
39 Self {
40 mode: LlmMode::Off,
41 ..Self::default()
42 }
43 }
44}
45
46pub struct WriteSession {
48 pub llm: LlmHandle,
49 pub cache: WriteCache,
50 pub cfg: WriteConfig,
51}
52
53impl WriteSession {
54 pub fn open(reflex_cache: &Path, opts: &WriteOptions) -> Self {
56 let mut settings = crate::pulse::config::load_pulse_config(reflex_cache)
57 .map(|c| c.write)
58 .unwrap_or_else(|e| {
59 log::warn!("ignoring invalid [pulse] config: {e:#}");
60 Default::default()
61 });
62 if opts.model.is_some() {
63 settings.model = opts.model.clone();
64 }
65 let cache_dir = opts
66 .cache_dir
67 .clone()
68 .or_else(|| settings.cache_dir.as_ref().map(PathBuf::from))
69 .unwrap_or_else(|| WriteCache::default_dir(reflex_cache));
70 let cfg = WriteConfig {
71 mode: opts.mode,
72 concurrency: opts.concurrency.unwrap_or(settings.concurrency),
73 max_llm_tokens: opts.max_llm_tokens.or(settings.max_llm_tokens),
74 force: opts.force.clone(),
75 dry_run: opts.dry_run,
76 keep_runs: settings.keep_runs,
77 prune: !opts.no_prune,
78 cache_model_agnostic: settings.cache_model_agnostic,
79 ..WriteConfig::default()
80 };
81 Self {
82 llm: provider::resolve(opts.mode, &settings),
83 cache: WriteCache::new(cache_dir),
84 cfg,
85 }
86 }
87
88 pub fn run(&self, tasks: Vec<WriteTask>) -> WriteOutcome {
89 run_tasks(tasks, &self.llm, &self.cache, &self.cfg)
90 }
91
92 pub fn run_one(&self, task: WriteTask) -> Option<String> {
94 let id = task.id.clone();
95 let out = self.run(vec![task]);
96 if out.degraded.is_some() {
97 eprintln!("{}", out.summary());
98 }
99 out.text(&id).map(str::to_string)
100 }
101}
102
103#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
105pub enum LlmMode {
106 #[default]
108 On,
109 Off,
111 CacheOnly,
113}
114
115impl FromStr for LlmMode {
116 type Err = String;
117
118 fn from_str(s: &str) -> Result<Self, Self::Err> {
119 match s.to_ascii_lowercase().as_str() {
120 "on" => Ok(Self::On),
121 "off" => Ok(Self::Off),
122 "cache-only" | "cache_only" | "cached" => Ok(Self::CacheOnly),
123 other => Err(format!(
124 "invalid --llm value '{other}' (expected on, off or cache-only)"
125 )),
126 }
127 }
128}
129
130#[derive(Debug, Clone, Default, PartialEq)]
132pub enum ForceScope {
133 #[default]
134 None,
135 All,
136 Only(Vec<String>),
138}
139
140impl ForceScope {
141 pub fn parse(spec: &str) -> Self {
143 let parts: Vec<String> = spec
144 .split(',')
145 .map(|p| p.trim().to_string())
146 .filter(|p| !p.is_empty())
147 .collect();
148 if parts.is_empty() {
149 Self::None
150 } else if parts.iter().any(|p| p == "all") {
151 Self::All
152 } else {
153 Self::Only(parts)
154 }
155 }
156
157 pub fn matches(&self, task: &WriteTask) -> bool {
158 match self {
159 Self::None => false,
160 Self::All => true,
161 Self::Only(parts) => parts.iter().any(|p| {
162 p == task.kind
163 || globset::Glob::new(p)
164 .map(|g| g.compile_matcher().is_match(&task.id))
165 .unwrap_or(false)
166 }),
167 }
168 }
169}
170
171#[cfg(test)]
172mod tests {
173 use super::*;
174 use crate::semantic::providers::ProviderErrorKind;
175 use crate::semantic::providers::mock::MockLlmProvider;
176 use std::sync::Arc;
177 use std::time::Duration;
178 use tempfile::TempDir;
179
180 const WORDS: &str = "one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen";
181
182 fn task(id: &str, kind: &'static str) -> WriteTask {
183 WriteTask::text(id, kind, "SYSTEM", format!("{WORDS} {id}"))
184 }
185
186 fn fast_cfg() -> WriteConfig {
187 WriteConfig {
188 base_backoff: Duration::from_millis(1),
189 ..WriteConfig::default()
190 }
191 }
192
193 fn echo() -> Arc<MockLlmProvider> {
194 Arc::new(MockLlmProvider::routed(|req| {
195 Ok(format!("text for {}", req.tag))
196 }))
197 }
198
199 fn handle(p: &Arc<MockLlmProvider>) -> LlmHandle {
200 LlmHandle::from_provider(p.clone())
201 }
202
203 #[test]
204 fn llm_mode_parse() {
205 assert_eq!("on".parse::<LlmMode>().unwrap(), LlmMode::On);
206 assert_eq!("OFF".parse::<LlmMode>().unwrap(), LlmMode::Off);
207 assert_eq!("cache-only".parse::<LlmMode>().unwrap(), LlmMode::CacheOnly);
208 assert!("maybe".parse::<LlmMode>().is_err());
209 }
210
211 #[test]
212 fn force_scope_parse_and_match() {
213 assert_eq!(ForceScope::parse(""), ForceScope::None);
214 assert_eq!(ForceScope::parse("all"), ForceScope::All);
215 let s = ForceScope::parse("overview, module:src/pulse*");
216 assert!(s.matches(&task("project-overview", "overview")));
217 assert!(s.matches(&task("module:src/pulse/write", "modules")));
218 assert!(!s.matches(&task("module:src/query", "modules")));
219 }
220
221 #[test]
222 fn calls_then_hits_the_cache_on_rerun() {
223 let dir = TempDir::new().unwrap();
224 let cache = WriteCache::new(dir.path());
225 let p = echo();
226 let tasks = vec![task("a", "modules"), task("b", "modules")];
227
228 let first = run_tasks(tasks.clone(), &handle(&p), &cache, &fast_cfg());
229 assert!(first.degraded.is_none(), "{:?}", first.degraded);
230 assert_eq!(first.stats.called, 2);
231 assert_eq!(first.text("a"), Some("text for a"));
232 assert_eq!(p.call_count(), 2);
233
234 let second = run_tasks(tasks, &handle(&p), &cache, &fast_cfg());
235 assert_eq!(second.stats.cached, 2);
236 assert_eq!(second.stats.called, 0);
237 assert_eq!(second.text("b"), Some("text for b"));
238 assert_eq!(p.call_count(), 2, "no new calls on a warm cache");
239 }
240
241 #[test]
242 fn system_and_user_are_sent_separately() {
243 let dir = TempDir::new().unwrap();
244 let p = echo();
245 run_tasks(
246 vec![task("a", "modules")],
247 &handle(&p),
248 &WriteCache::new(dir.path()),
249 &fast_cfg(),
250 );
251 let req = &p.requests()[0];
252 assert_eq!(req.system, "SYSTEM");
253 assert!(req.user.ends_with(" a"));
254 assert_eq!(req.output, "text");
255 }
256
257 #[test]
258 fn identical_requests_share_one_call() {
259 let dir = TempDir::new().unwrap();
260 let p = echo();
261 let a = WriteTask::text("a", "modules", "S", WORDS);
262 let b = WriteTask::text("b", "modules", "S", WORDS);
263 let out = run_tasks(
264 vec![a, b],
265 &handle(&p),
266 &WriteCache::new(dir.path()),
267 &fast_cfg(),
268 );
269 assert_eq!(p.call_count(), 1);
270 assert_eq!(out.text("a"), out.text("b"));
271 assert!(out.text("a").is_some());
272 }
273
274 #[test]
275 fn thin_input_is_suppressed_without_a_call() {
276 let dir = TempDir::new().unwrap();
277 let p = echo();
278 let thin = WriteTask::text("thin", "modules", "S", "too short");
279 let out = run_tasks(
280 vec![thin],
281 &handle(&p),
282 &WriteCache::new(dir.path()),
283 &fast_cfg(),
284 );
285 assert!(matches!(
286 out.results["thin"].outcome,
287 TaskOutcome::Suppressed(_)
288 ));
289 assert_eq!(p.call_count(), 0);
290 assert!(out.degraded.is_none());
291 }
292
293 #[test]
294 fn model_change_misses_unless_model_agnostic() {
295 let dir = TempDir::new().unwrap();
296 let cache = WriteCache::new(dir.path());
297 let t = vec![task("a", "modules")];
298 run_tasks(t.clone(), &handle(&echo()), &cache, &fast_cfg());
299
300 let other = Arc::new(MockLlmProvider::routed(|_| Ok("new".into())).with_model("other"));
301 let out = run_tasks(t.clone(), &handle(&other), &cache, &fast_cfg());
302 assert_eq!(out.stats.called, 1, "different model → different key");
303
304 let agnostic = WriteConfig {
305 cache_model_agnostic: true,
306 ..fast_cfg()
307 };
308 run_tasks(t.clone(), &handle(&echo()), &cache, &agnostic);
309 let again = Arc::new(MockLlmProvider::routed(|_| Ok("x".into())).with_model("third"));
310 let out = run_tasks(t, &handle(&again), &cache, &agnostic);
311 assert_eq!(out.stats.cached, 1);
312 assert_eq!(again.call_count(), 0);
313 }
314
315 #[test]
316 fn fatal_probe_degrades_the_whole_run_and_ignores_hits() {
317 let dir = TempDir::new().unwrap();
318 let cache = WriteCache::new(dir.path());
319 run_tasks(
321 vec![task("a", "modules")],
322 &handle(&echo()),
323 &cache,
324 &fast_cfg(),
325 );
326
327 let p = Arc::new(
328 MockLlmProvider::routed(|_| Ok("x".into())).fail_first(1, ProviderErrorKind::Auth),
329 );
330 let tasks = vec![
331 task("a", "modules"),
332 task("b", "modules"),
333 task("c", "modules"),
334 ];
335 let out = run_tasks(tasks, &handle(&p), &cache, &fast_cfg());
336 assert!(out.degraded.is_some());
337 assert_eq!(p.call_count(), 1, "nothing is sent after a fatal probe");
338 assert_eq!(
339 out.text("a"),
340 None,
341 "cache hits are not used in a degraded run"
342 );
343 assert!(!out.has_text());
344 }
345
346 #[test]
347 fn transient_errors_are_retried() {
348 let dir = TempDir::new().unwrap();
349 let p = Arc::new(
350 MockLlmProvider::routed(|_| Ok("ok".into()))
351 .fail_first(2, ProviderErrorKind::RateLimited),
352 );
353 let out = run_tasks(
354 vec![task("a", "modules")],
355 &handle(&p),
356 &WriteCache::new(dir.path()),
357 &fast_cfg(),
358 );
359 assert_eq!(out.text("a"), Some("ok"));
360 assert_eq!(out.stats.retries, 2);
361 assert_eq!(p.call_count(), 3);
362 }
363
364 #[test]
365 fn consecutive_failures_trip_the_breaker() {
366 let dir = TempDir::new().unwrap();
367 let p = Arc::new(MockLlmProvider::routed(|_| {
368 Err(MockLlmProvider::error(ProviderErrorKind::Server))
369 }));
370 let cfg = WriteConfig {
371 concurrency: 1,
372 max_attempts: 1,
373 breaker_threshold: 3,
374 ..fast_cfg()
375 };
376 let tasks: Vec<_> = (0..10)
377 .map(|i| task(&format!("t{i:02}"), "modules"))
378 .collect();
379 let out = run_tasks(tasks, &handle(&p), &WriteCache::new(dir.path()), &cfg);
380 assert!(out.degraded.as_deref().unwrap().contains("consecutive"));
381 assert!(
382 p.call_count() <= 4,
383 "stops soon after the breaker trips: {}",
384 p.call_count()
385 );
386 }
387
388 #[test]
389 fn low_success_rate_degrades_but_keeps_successes_cached() {
390 let dir = TempDir::new().unwrap();
391 let cache = WriteCache::new(dir.path());
392 let p = Arc::new(MockLlmProvider::routed(|req| {
393 if req.tag == "a" {
394 Ok("fine".into())
395 } else {
396 Err(MockLlmProvider::error(ProviderErrorKind::Server))
397 }
398 }));
399 let cfg = WriteConfig {
400 max_attempts: 1,
401 ..fast_cfg()
402 };
403 let tasks = vec![
404 task("a", "modules"),
405 task("b", "modules"),
406 task("c", "modules"),
407 ];
408 let out = run_tasks(tasks.clone(), &handle(&p), &cache, &cfg);
409 assert!(out.degraded.is_some());
410 assert_eq!(out.text("a"), None);
411
412 let rerun = run_tasks(vec![task("a", "modules")], &handle(&echo()), &cache, &cfg);
413 assert_eq!(rerun.results["a"].outcome, TaskOutcome::Cached);
414 }
415
416 #[test]
417 fn budget_defers_low_priority_tasks_deterministically() {
418 let dir = TempDir::new().unwrap();
419 let p = echo();
420 let one = task("x", "modules");
421 let cost = ((one.system.len() + one.user.len()) as f64 / 3.5).ceil() as u64
422 + (one.max_tokens as f64 * 0.6).ceil() as u64;
423 let tasks = vec![
424 task("low", "modules").with_priority(200),
425 task("high", "overview").with_priority(10),
426 task("mid", "modules").with_priority(50),
427 ];
428 let cfg = WriteConfig {
429 max_llm_tokens: Some(cost * 2 + 5),
430 ..fast_cfg()
431 };
432 let out = run_tasks(tasks, &handle(&p), &WriteCache::new(dir.path()), &cfg);
433 assert!(out.truncated);
434 assert_eq!(out.results["low"].outcome, TaskOutcome::Deferred);
435 assert_eq!(out.results["high"].outcome, TaskOutcome::Called);
436 assert_eq!(out.results["mid"].outcome, TaskOutcome::Called);
437 assert_eq!(out.stats.pruned, 0, "a truncated run never prunes");
438 }
439
440 #[test]
441 fn dry_run_makes_no_calls_and_reports_a_plan() {
442 let dir = TempDir::new().unwrap();
443 let p = echo();
444 let cfg = WriteConfig {
445 dry_run: true,
446 ..fast_cfg()
447 };
448 let out = run_tasks(
449 vec![task("a", "modules"), task("o", "overview")],
450 &handle(&p),
451 &WriteCache::new(dir.path()),
452 &cfg,
453 );
454 assert_eq!(p.call_count(), 0);
455 let table = out.plan_table();
456 assert!(table.contains("modules"), "{table}");
457 assert!(table.contains("total"), "{table}");
458 assert!(table.contains("mock/mock-model"), "{table}");
459 assert_eq!(out.text("a"), None);
460 }
461
462 #[test]
463 fn cache_only_uses_hits_and_never_calls() {
464 let dir = TempDir::new().unwrap();
465 let cache = WriteCache::new(dir.path());
466 run_tasks(
467 vec![task("a", "modules")],
468 &handle(&echo()),
469 &cache,
470 &fast_cfg(),
471 );
472
473 let ident_only = LlmHandle {
474 ident: handle(&echo()).ident,
475 provider: None,
476 unavailable: Some("cache-only mode".into()),
477 };
478 let cfg = WriteConfig {
479 mode: LlmMode::CacheOnly,
480 ..fast_cfg()
481 };
482 let out = run_tasks(
483 vec![task("a", "modules"), task("b", "modules")],
484 &ident_only,
485 &cache,
486 &cfg,
487 );
488 assert!(out.degraded.is_none());
489 assert_eq!(out.text("a"), Some("text for a"));
490 assert_eq!(out.results["b"].outcome, TaskOutcome::NotCached);
491 }
492
493 #[test]
494 fn forced_scope_recalls_only_that_scope() {
495 let dir = TempDir::new().unwrap();
496 let cache = WriteCache::new(dir.path());
497 let tasks = vec![task("m", "modules"), task("o", "overview")];
498 run_tasks(tasks.clone(), &handle(&echo()), &cache, &fast_cfg());
499
500 let p = echo();
501 let cfg = WriteConfig {
502 force: ForceScope::parse("overview"),
503 ..fast_cfg()
504 };
505 let out = run_tasks(tasks, &handle(&p), &cache, &cfg);
506 let tags: Vec<String> = p.requests().into_iter().map(|r| r.tag).collect();
507 assert_eq!(tags, vec!["o".to_string()]);
508 assert_eq!(out.results["m"].outcome, TaskOutcome::Cached);
509 }
510
511 #[test]
512 fn successful_run_prunes_stale_entries() {
513 let dir = TempDir::new().unwrap();
514 let cache = WriteCache::new(dir.path());
515 let cfg = WriteConfig {
516 keep_runs: 1,
517 ..fast_cfg()
518 };
519 run_tasks(vec![task("old", "modules")], &handle(&echo()), &cache, &cfg);
520 assert_eq!(cache.count(), 1);
521 let out = run_tasks(vec![task("new", "modules")], &handle(&echo()), &cache, &cfg);
522 assert_eq!(out.stats.pruned, 1);
523 assert_eq!(cache.count(), 1);
524 }
525
526 #[test]
527 fn off_mode_skips_everything() {
528 let dir = TempDir::new().unwrap();
529 let p = echo();
530 let cfg = WriteConfig {
531 mode: LlmMode::Off,
532 ..fast_cfg()
533 };
534 let out = run_tasks(
535 vec![task("a", "modules")],
536 &handle(&p),
537 &WriteCache::new(dir.path()),
538 &cfg,
539 );
540 assert_eq!(out.results["a"].outcome, TaskOutcome::Skipped);
541 assert_eq!(p.call_count(), 0);
542 assert!(out.degraded.is_none());
543 }
544}