1use std::collections::HashMap;
10use std::path::Path;
11use std::sync::Arc;
12
13use tokio::sync::{mpsc, RwLock};
14
15use crate::agent_engine::{run_agent_turn, AgentEvent, AgentRequestContext, AgentTurn};
16use crate::chat_turn_queue::PendingMessage;
17use crate::config::Config;
18use crate::hooks::HookManager;
19use crate::internal::channels::channel_adapter::ChannelRegistry;
20use crate::internal::runtime::{ExecutionContext, ExecutionResult, RunExecutor};
21use crate::internal::storage::db::{call_blocking, Database, StoredMessage};
22use crate::memory::MemoryManager;
23use crate::memory_backend::{MemoryBackend, MemoryMcpClient};
24use crate::runtime::AppState;
25use crate::skill_management::{archive_skill, install_skill, SkillInstallOutcome};
26use crate::skills::{SkillAvailability, SkillManager};
27use crate::tools::ToolRegistry;
28use crate::{embedding, llm};
29use microclaw_core::run_protocol::{
30 AgentProfile, RunRequest, RuntimeCapabilities, RuntimeControl, RuntimeError, RuntimeErrorCode,
31 SessionId,
32};
33use microclaw_core::runtime_event::RuntimeEventEnvelope;
34
35pub const HEADLESS_CHANNEL: &str = "headless";
36pub const CODE_CHANNEL: &str = "code";
37pub const INTERACTIVE_APPROVALS_KEY: &str = "interactive_approvals";
40
41#[derive(Debug, Clone)]
42pub struct HeadlessRunRequest {
43 pub prompt: String,
44 pub session: Option<String>,
45 pub sender_name: String,
46 pub run_id: Option<String>,
47 pub caller_channel: String,
48 pub image: Option<(String, String)>,
50}
51
52impl HeadlessRunRequest {
53 pub fn cli(prompt: String, session: Option<String>) -> Self {
54 Self {
55 prompt,
56 session,
57 sender_name: "cli".into(),
58 run_id: None,
59 caller_channel: HEADLESS_CHANNEL.into(),
60 image: None,
61 }
62 }
63
64 pub fn code(prompt: String, session: Option<String>, run_id: String) -> Self {
65 Self {
66 prompt,
67 session,
68 sender_name: "code".into(),
69 run_id: Some(run_id),
70 caller_channel: CODE_CHANNEL.into(),
71 image: None,
72 }
73 }
74}
75
76pub const IMAGE_KEY: &str = "image";
79
80fn image_from_metadata(
81 metadata: &std::collections::BTreeMap<String, serde_json::Value>,
82) -> Option<(String, String)> {
83 let image = metadata.get(IMAGE_KEY)?;
84 let data = image.get("data")?.as_str()?.to_string();
85 let media_type = image.get("media_type")?.as_str()?.to_string();
86 (!data.is_empty() && media_type.starts_with("image/")).then_some((data, media_type))
87}
88
89#[derive(Debug, Clone)]
90pub struct HeadlessRunResult {
91 pub run_id: String,
92 pub chat_id: i64,
93 pub response: String,
94}
95
96#[derive(Debug, Clone, PartialEq, Eq)]
98pub struct HeadlessSessionMessage {
99 pub from_agent: bool,
101 pub content: String,
102 pub timestamp: String,
103}
104
105#[derive(Debug, Clone, PartialEq, Eq)]
107pub struct HeadlessCheckpoint {
108 pub commit: String,
109 pub label: String,
110 pub timestamp: String,
111}
112
113#[derive(Debug, Clone, Default, PartialEq, Eq)]
115pub struct HeadlessUsage {
116 pub requests: i64,
117 pub input_tokens: i64,
118 pub output_tokens: i64,
119 pub by_model: Vec<(String, i64, i64, i64)>,
121}
122
123#[derive(Debug, Clone, Copy, PartialEq, Eq)]
127pub struct SessionMark {
128 pub messages: usize,
130 pub fingerprint: u64,
132}
133
134fn conversation_fingerprint(messages: &[serde_json::Value]) -> u64 {
136 use std::hash::{Hash, Hasher};
137 let mut hasher = std::collections::hash_map::DefaultHasher::new();
138 for message in messages {
139 message.to_string().hash(&mut hasher);
140 }
141 hasher.finish()
142}
143
144#[derive(Debug, Clone, PartialEq, Eq)]
146pub struct HeadlessCompaction {
147 pub messages_before: usize,
148 pub messages_after: usize,
149 pub tokens_before: usize,
150 pub tokens_after: usize,
151 pub method: String,
153}
154
155#[derive(Debug, Clone, PartialEq, Eq)]
157pub struct HeadlessContextUsage {
158 pub model: String,
159 pub window: usize,
160 pub reserved_output: usize,
161 pub auto_compact_threshold: usize,
163 pub last_request_tokens: Option<usize>,
166 pub conversation: crate::context_window::ContextBreakdown,
168 pub prompt_cache_ttl: Option<std::time::Duration>,
171}
172
173pub fn anthropic_cache_ttl(ttl: &str) -> std::time::Duration {
175 if ttl.trim() == "1h" {
176 std::time::Duration::from_secs(3600)
177 } else {
178 std::time::Duration::from_secs(300)
179 }
180}
181
182impl HeadlessContextUsage {
183 pub fn used(&self) -> usize {
186 self.last_request_tokens
187 .unwrap_or_else(|| self.conversation.total())
188 .max(self.conversation.total())
189 }
190}
191
192#[derive(Debug, Clone, PartialEq, Eq)]
194pub struct HeadlessSubagentRun {
195 pub run_id: String,
196 pub parent_run_id: Option<String>,
197 pub depth: u32,
198 pub label: Option<String>,
199 pub task: String,
200 pub status: String,
201 pub progress: Option<String>,
202 pub result: Option<String>,
203 pub error: Option<String>,
204 pub created_at: String,
205 pub started_at: Option<String>,
206 pub finished_at: Option<String>,
207 pub cancel_requested: bool,
208}
209
210#[derive(Clone)]
216pub struct HeadlessRuntime {
217 state: Arc<AppState>,
218}
219
220pub struct HeadlessRunExecutor {
226 runtime: HeadlessRuntime,
227 caller_channel: String,
228}
229
230impl HeadlessRunExecutor {
231 pub fn new(runtime: HeadlessRuntime, caller_channel: impl Into<String>) -> Self {
232 Self {
233 runtime,
234 caller_channel: caller_channel.into(),
235 }
236 }
237}
238
239#[async_trait::async_trait]
240impl RunExecutor for HeadlessRunExecutor {
241 async fn execute(
242 &self,
243 profile: AgentProfile,
244 request: RunRequest,
245 mut context: ExecutionContext,
246 ) -> Result<ExecutionResult, RuntimeError> {
247 let session = request
248 .session_id
249 .clone()
250 .unwrap_or_else(|| SessionId::new("default"));
251 let interactive_approvals = request
255 .metadata
256 .get(INTERACTIVE_APPROVALS_KEY)
257 .and_then(serde_json::Value::as_bool)
258 .unwrap_or(false);
259 let approval_chat_id = if interactive_approvals {
260 Some(
261 self.runtime
262 .resolve_session_chat_id(session.as_str())
263 .await
264 .map_err(runtime_internal_error)?,
265 )
266 } else {
267 None
268 };
269 let _approval_broker = approval_chat_id
270 .map(|chat_id| crate::approval_broker::register(&self.caller_channel, chat_id));
271 let (legacy_event_tx, mut legacy_event_rx) = mpsc::unbounded_channel();
272 let run = self.runtime.run_with_profile(
273 HeadlessRunRequest {
274 image: image_from_metadata(&request.metadata),
275 prompt: request.prompt,
276 session: Some(session.to_string()),
277 sender_name: self.caller_channel.clone(),
278 run_id: Some(context.run_id().to_string()),
279 caller_channel: self.caller_channel.clone(),
280 },
281 profile,
282 Some(legacy_event_tx),
283 );
284 tokio::pin!(run);
285
286 let result = loop {
287 tokio::select! {
288 result = &mut run => break result,
289 event = legacy_event_rx.recv() => {
290 if let Some(envelope) = event {
291 forward_runtime_event(&context, envelope.event)?;
292 }
293 }
294 control = context.next_control_request() => {
295 if let Some(control) = control {
296 match control.control().clone() {
297 RuntimeControl::Cancel { .. } => {
298 let cancelled = self.runtime
299 .cancel_session_for_channel(&self.caller_channel, session.as_str())
300 .await
301 .map_err(runtime_internal_error)?;
302 if cancelled > 0 {
303 control.accept();
304 } else {
305 control.reject(RuntimeError {
306 code: RuntimeErrorCode::Unavailable,
307 message: "the run finished before cancellation was accepted".into(),
308 retryable: false,
309 });
310 }
311 }
312 RuntimeControl::Steer { message, .. } => {
313 let accepted = self.runtime
314 .steer_session_for_channel(
315 &self.caller_channel,
316 session.as_str(),
317 &message,
318 )
319 .await
320 .map_err(runtime_internal_error)?;
321 if accepted {
322 control.accept();
323 } else {
324 control.reject(RuntimeError {
325 code: RuntimeErrorCode::Unavailable,
326 message: "the run finished before the update could be queued".into(),
327 retryable: false,
328 });
329 }
330 }
331 RuntimeControl::ResolveApproval { approval_id, decision, .. } => {
332 let Some(chat_id) = approval_chat_id else {
333 control.reject(RuntimeError {
334 code: RuntimeErrorCode::Unavailable,
335 message: format!(
336 "in-run approvals are off for this run; set request metadata `{INTERACTIVE_APPROVALS_KEY}: true`"
337 ),
338 retryable: false,
339 });
340 continue;
341 };
342 let Some(decision) = crate::approval_broker::ApprovalDecision::parse(&decision) else {
343 control.reject(RuntimeError {
344 code: RuntimeErrorCode::InvalidRequest,
345 message: format!(
346 "unknown approval decision `{decision}` (use 1/approve, 2/always, 3/deny or defer)"
347 ),
348 retryable: false,
349 });
350 continue;
351 };
352 if crate::approval_broker::resolve(
353 &self.caller_channel,
354 chat_id,
355 &approval_id,
356 decision,
357 ) {
358 control.accept();
359 } else {
360 control.reject(RuntimeError {
361 code: RuntimeErrorCode::Unavailable,
362 message: format!("no pending approval `{approval_id}`"),
363 retryable: false,
364 });
365 }
366 }
367 }
368 }
369 }
370 }
371 }
372 .map_err(runtime_internal_error)?;
373
374 while let Ok(envelope) = legacy_event_rx.try_recv() {
375 forward_runtime_event(&context, envelope.event)?;
376 }
377
378 let mut output = ExecutionResult::new(session, result.response);
379 output.metadata.insert(
380 "chat_id".into(),
381 serde_json::Value::Number(result.chat_id.into()),
382 );
383 Ok(output)
384 }
385
386 fn capabilities(&self) -> RuntimeCapabilities {
387 RuntimeCapabilities {
388 streaming: true,
389 cancellation: true,
390 steering: true,
391 approvals: true,
392 skills: true,
393 subagents: true,
394 remote_workers: false,
395 }
396 }
397}
398
399fn forward_runtime_event(
400 context: &ExecutionContext,
401 event: microclaw_core::runtime_event::RuntimeEvent,
402) -> Result<(), RuntimeError> {
403 if matches!(
404 event,
405 microclaw_core::runtime_event::RuntimeEvent::FinalResponse { .. }
406 | microclaw_core::runtime_event::RuntimeEvent::Cancelled { .. }
407 ) {
408 return Ok(());
409 }
410 context.emit(event)
411}
412
413fn runtime_internal_error(error: impl std::fmt::Display) -> RuntimeError {
414 RuntimeError {
415 code: RuntimeErrorCode::Internal,
416 message: error.to_string(),
417 retryable: false,
418 }
419}
420
421impl HeadlessRuntime {
422 pub fn skill_catalog(&self, include_unavailable: bool) -> Vec<SkillAvailability> {
425 self.state
426 .skills
427 .discover_skills_with_status(include_unavailable)
428 }
429
430 pub fn reload_skill_catalog(&self, include_unavailable: bool) -> Vec<SkillAvailability> {
432 self.state.skills.reload();
433 self.skill_catalog(include_unavailable)
434 }
435
436 pub fn set_skill_enabled(&self, name: &str, enabled: bool) -> Result<(), String> {
438 self.state.skills.set_enabled(name, enabled)?;
439 self.state.skills.reload();
440 Ok(())
441 }
442
443 pub async fn install_skill(&self, reference: &str) -> Result<SkillInstallOutcome, String> {
445 install_skill(&self.state.config, &self.state.skills, reference).await
446 }
447
448 pub fn archive_skill(&self, name: &str) -> Result<std::path::PathBuf, String> {
450 archive_skill(&self.state.skills, name)
451 }
452
453 pub fn subagent_runs(
455 &self,
456 session: &str,
457 limit: usize,
458 ) -> anyhow::Result<Vec<HeadlessSubagentRun>> {
459 let external_chat_id = format!("headless:{}", session.trim());
460 let Some(chat_id) = self
461 .state
462 .db
463 .find_chat_id(HEADLESS_CHANNEL, &external_chat_id)?
464 else {
465 return Ok(Vec::new());
466 };
467 Ok(self
468 .state
469 .db
470 .list_subagent_runs(chat_id, limit.clamp(1, 1_000))?
471 .into_iter()
472 .map(|run| HeadlessSubagentRun {
473 run_id: run.run_id,
474 parent_run_id: run.parent_run_id,
475 depth: run.depth.max(0) as u32,
476 label: run.label,
477 task: run.task,
478 status: run.status,
479 progress: run.progress_text,
480 result: run.result_text,
481 error: run.error_text,
482 created_at: run.created_at,
483 started_at: run.started_at,
484 finished_at: run.finished_at,
485 cancel_requested: run.cancel_requested,
486 })
487 .collect())
488 }
489
490 pub fn session_messages(
494 &self,
495 session: &str,
496 limit: usize,
497 ) -> anyhow::Result<Vec<HeadlessSessionMessage>> {
498 let external_chat_id = format!("headless:{}", session.trim());
499 let Some(chat_id) = self
500 .state
501 .db
502 .find_chat_id(HEADLESS_CHANNEL, &external_chat_id)?
503 else {
504 return Ok(Vec::new());
505 };
506 Ok(self
507 .state
508 .db
509 .get_recent_messages(chat_id, limit.clamp(1, 10_000))?
510 .into_iter()
511 .map(|message| HeadlessSessionMessage {
512 from_agent: message.is_from_bot,
513 content: message.content,
514 timestamp: message.timestamp,
515 })
516 .collect())
517 }
518
519 async fn existing_session_chat_id(&self, session: &str) -> anyhow::Result<Option<i64>> {
520 let external_chat_id = format!("headless:{}", session.trim());
521 let db = self.state.db.clone();
522 Ok(call_blocking(db, move |db| {
523 db.find_chat_id(HEADLESS_CHANNEL, &external_chat_id)
524 })
525 .await?)
526 }
527
528 fn checkpoint_paths(
529 &self,
530 channel: &str,
531 chat_id: i64,
532 ) -> anyhow::Result<(std::path::PathBuf, std::path::PathBuf)> {
533 if !self.state.config.checkpoints_enabled {
534 anyhow::bail!("checkpoints are disabled for this runtime");
535 }
536 let working_dir = crate::internal::tool_runtime::runtime::working_dir_for_context(
537 Path::new(&self.state.config.working_dir),
538 self.state.config.working_dir_isolation,
539 channel,
540 chat_id,
541 );
542 let shadow_root = std::path::PathBuf::from(&self.state.config.data_dir).join("checkpoints");
543 let shadow_repo = crate::checkpoint::shadow_repo_path(&shadow_root, &working_dir);
544 Ok((shadow_repo, working_dir))
545 }
546
547 pub async fn checkpoint_session(
551 &self,
552 channel: &str,
553 session: &str,
554 label: &str,
555 ) -> anyhow::Result<Option<HeadlessCheckpoint>> {
556 let chat_id = self.resolve_session_chat_id(session).await?;
557 let (shadow_repo, working_dir) = self.checkpoint_paths(channel, chat_id)?;
558 crate::checkpoint::snapshot(&shadow_repo, &working_dir, label)
559 .await
560 .map_err(anyhow::Error::msg)?;
561 Ok(crate::checkpoint::list(&shadow_repo, &working_dir, 1)
562 .await
563 .map_err(anyhow::Error::msg)?
564 .into_iter()
565 .next()
566 .map(|c| HeadlessCheckpoint {
567 commit: c.commit,
568 label: c.label,
569 timestamp: c.timestamp,
570 }))
571 }
572
573 pub async fn session_checkpoints(
575 &self,
576 channel: &str,
577 session: &str,
578 limit: usize,
579 ) -> anyhow::Result<Vec<HeadlessCheckpoint>> {
580 let chat_id = self.resolve_session_chat_id(session).await?;
581 let (shadow_repo, working_dir) = self.checkpoint_paths(channel, chat_id)?;
582 Ok(
583 crate::checkpoint::list(&shadow_repo, &working_dir, limit.clamp(1, 500))
584 .await
585 .map_err(anyhow::Error::msg)?
586 .into_iter()
587 .map(|c| HeadlessCheckpoint {
588 commit: c.commit,
589 label: c.label,
590 timestamp: c.timestamp,
591 })
592 .collect(),
593 )
594 }
595
596 pub async fn restore_session_checkpoint(
599 &self,
600 channel: &str,
601 session: &str,
602 commit: &str,
603 ) -> anyhow::Result<Option<HeadlessCheckpoint>> {
604 let before = self
605 .checkpoint_session(channel, session, &format!("before restoring {commit}"))
606 .await?;
607 let chat_id = self.resolve_session_chat_id(session).await?;
608 let (shadow_repo, working_dir) = self.checkpoint_paths(channel, chat_id)?;
609 crate::checkpoint::restore(&shadow_repo, &working_dir, commit)
610 .await
611 .map_err(anyhow::Error::msg)?;
612 Ok(before)
613 }
614
615 pub async fn session_usage(&self, session: &str) -> anyhow::Result<HeadlessUsage> {
617 let Some(chat_id) = self.existing_session_chat_id(session).await? else {
618 return Ok(HeadlessUsage::default());
619 };
620 let db = self.state.db.clone();
621 Ok(call_blocking(db, move |db| {
622 let summary = db.get_llm_usage_summary(Some(chat_id))?;
623 let by_model = db
624 .get_llm_usage_by_model(Some(chat_id), None, Some(20))?
625 .into_iter()
626 .map(|m| (m.model, m.requests, m.input_tokens, m.output_tokens))
627 .collect();
628 Ok::<_, microclaw_core::error::MicroClawError>(HeadlessUsage {
629 requests: summary.requests,
630 input_tokens: summary.input_tokens,
631 output_tokens: summary.output_tokens,
632 by_model,
633 })
634 })
635 .await?)
636 }
637
638 pub async fn session_model(&self, channel: &str, session: &str) -> anyhow::Result<String> {
640 let chat_id = self.resolve_session_chat_id(session).await?;
641 Ok(
642 crate::agent_engine::resolve_effective_provider_and_model(
643 &self.state,
644 channel,
645 chat_id,
646 )
647 .await
648 .1,
649 )
650 }
651
652 pub async fn set_session_model(
655 &self,
656 channel: &str,
657 session: &str,
658 model: Option<&str>,
659 ) -> anyhow::Result<String> {
660 let chat_id = self.resolve_session_chat_id(session).await?;
661 let key = crate::chat_commands::chat_scoped_override_key(channel, chat_id);
662 {
663 let mut overrides = self.state.llm_model_overrides.write().await;
664 match model {
665 Some(model) => {
666 let model = crate::config::normalize_model_name(model)
667 .ok_or_else(|| anyhow::anyhow!("invalid model name `{model}`"))?;
668 overrides.insert(key, model);
669 }
670 None => {
671 overrides.remove(&key);
672 }
673 }
674 }
675 self.session_model(channel, session).await
676 }
677
678 pub async fn session_mark(&self, session: &str) -> anyhow::Result<SessionMark> {
681 let Some(chat_id) = self.existing_session_chat_id(session).await? else {
682 return Ok(SessionMark {
683 messages: 0,
684 fingerprint: conversation_fingerprint(&[]),
685 });
686 };
687 let db = self.state.db.clone();
688 let json = call_blocking(db, move |db| db.load_session(chat_id)).await?;
689 let messages: Vec<serde_json::Value> = match json {
690 Some((json, _)) => serde_json::from_str(&json)?,
691 None => Vec::new(),
692 };
693 Ok(SessionMark {
694 messages: messages.len(),
695 fingerprint: conversation_fingerprint(&messages),
696 })
697 }
698
699 pub async fn rewind_session_to(
704 &self,
705 channel: &str,
706 session: &str,
707 mark: &SessionMark,
708 ) -> anyhow::Result<usize> {
709 let Some(chat_id) = self.existing_session_chat_id(session).await? else {
710 anyhow::bail!("session `{session}` has no conversation");
711 };
712 let db = self.state.db.clone();
713 let json = call_blocking(db, move |db| db.load_session(chat_id)).await?;
714 let mut values: Vec<serde_json::Value> = match json {
715 Some((json, _)) => serde_json::from_str(&json)?,
716 None => Vec::new(),
717 };
718 if values.len() < mark.messages
719 || conversation_fingerprint(&values[..mark.messages]) != mark.fingerprint
720 {
721 anyhow::bail!(
722 "the conversation was compacted or changed since that point, so it cannot be cut back there"
723 );
724 }
725 let removed = values.len() - mark.messages;
726 if removed == 0 {
727 return Ok(0);
728 }
729 if let Ok(messages) = serde_json::from_value::<Vec<microclaw_core::llm_types::Message>>(
730 serde_json::Value::Array(values.clone()),
731 ) {
732 crate::agent_engine::archive_conversation(
733 &self.state.config.data_dir,
734 channel,
735 chat_id,
736 &messages,
737 );
738 }
739 values.truncate(mark.messages);
740 let json = serde_json::to_string(&values)?;
741 let db = self.state.db.clone();
742 call_blocking(db, move |db| db.save_session(chat_id, &json)).await?;
743 Ok(removed)
744 }
745
746 pub async fn compact_session(
750 &self,
751 channel: &str,
752 session: &str,
753 keep_recent: usize,
754 focus: Option<&str>,
755 ) -> anyhow::Result<HeadlessCompaction> {
756 let Some(chat_id) = self.existing_session_chat_id(session).await? else {
757 anyhow::bail!("session `{session}` has no conversation yet");
758 };
759 let db = self.state.db.clone();
760 let Some((json, _)) = call_blocking(db, move |db| db.load_session(chat_id)).await? else {
761 anyhow::bail!("session `{session}` has no conversation yet");
762 };
763 let messages: Vec<microclaw_core::llm_types::Message> = serde_json::from_str(&json)?;
764 let before = messages.len();
765 crate::agent_engine::archive_conversation(
766 &self.state.config.data_dir,
767 channel,
768 chat_id,
769 &messages,
770 );
771 let outcome = crate::agent_engine::compact_conversation(
772 &self.state,
773 channel,
774 chat_id,
775 &messages,
776 crate::agent_engine::CompactOptions {
777 keep_recent: keep_recent.max(2),
778 focus: focus.map(str::to_string),
779 force_summary: true,
780 target_tokens: None,
781 },
782 )
783 .await;
784 if outcome.changed() {
785 let json = serde_json::to_string(&outcome.messages)?;
786 let db = self.state.db.clone();
787 call_blocking(db, move |db| db.save_session(chat_id, &json)).await?;
788 }
789 Ok(HeadlessCompaction {
790 messages_before: before,
791 messages_after: outcome.messages.len(),
792 tokens_before: outcome.tokens_before,
793 tokens_after: outcome.tokens_after,
794 method: outcome.method.to_string(),
795 })
796 }
797
798 pub async fn context_usage(
802 &self,
803 channel: &str,
804 session: &str,
805 ) -> anyhow::Result<HeadlessContextUsage> {
806 let chat_id = self.resolve_session_chat_id(session).await?;
807 let (profile, model, _) = crate::agent_engine::resolve_effective_provider_and_model(
808 &self.state,
809 channel,
810 chat_id,
811 )
812 .await;
813 let budget = crate::context_window::ContextBudget::for_model(&self.state.config, &model);
814 let prompt_cache_ttl = profile
815 .provider
816 .trim()
817 .eq_ignore_ascii_case("anthropic")
818 .then(|| anthropic_cache_ttl(&self.state.config.anthropic_prompt_cache_ttl));
819 let mut usage = HeadlessContextUsage {
820 model: model.clone(),
821 window: budget.window,
822 reserved_output: budget.reserved_output,
823 auto_compact_threshold: budget.threshold,
824 last_request_tokens: None,
825 conversation: Default::default(),
826 prompt_cache_ttl,
827 };
828 let Some(chat_id) = self.existing_session_chat_id(session).await? else {
829 return Ok(usage);
830 };
831 let db = self.state.db.clone();
832 let (stored, latest) = call_blocking(db, move |db| {
833 Ok::<_, microclaw_core::error::MicroClawError>((
834 db.load_session(chat_id)?,
835 db.latest_agent_request(chat_id)?,
836 ))
837 })
838 .await?;
839 if let Some((json, _)) = stored {
840 let messages: Vec<microclaw_core::llm_types::Message> =
841 serde_json::from_str(&json).unwrap_or_default();
842 usage.conversation = crate::context_window::breakdown(&messages);
843 }
844 usage.last_request_tokens = latest
845 .filter(|(_, last_model)| last_model == &model)
846 .map(|(tokens, _)| tokens.max(0) as usize);
847 Ok(usage)
848 }
849
850 pub async fn fork_session(&self, from: &str, to: &str) -> anyhow::Result<()> {
853 let Some(from_id) = self.existing_session_chat_id(from).await? else {
854 anyhow::bail!("session `{from}` has no conversation to fork");
855 };
856 let to_id = self.resolve_session_chat_id(to).await?;
857 let parent_key = format!("headless:{}", from.trim());
858 let db = self.state.db.clone();
859 call_blocking(db, move |db| {
860 if db.load_session(to_id)?.is_some() {
861 return Err(microclaw_core::error::MicroClawError::Config(
862 "the target session already has a conversation".into(),
863 ));
864 }
865 for message in db.get_all_messages(from_id)? {
866 db.store_message(&StoredMessage {
867 id: uuid::Uuid::new_v4().to_string(),
868 chat_id: to_id,
869 ..message
870 })?;
871 }
872 if let Some((json, _)) = db.load_session(from_id)? {
873 let fork_point = serde_json::from_str::<Vec<serde_json::Value>>(&json)
874 .map(|m| m.len() as i64)
875 .ok();
876 db.save_session_with_meta(to_id, &json, Some(&parent_key), fork_point, None)?;
877 }
878 Ok(())
879 })
880 .await?;
881 Ok(())
882 }
883
884 pub async fn handoff_session(
888 &self,
889 channel: &str,
890 from: &str,
891 to: &str,
892 goal: &str,
893 ) -> anyhow::Result<usize> {
894 let Some(from_id) = self.existing_session_chat_id(from).await? else {
895 anyhow::bail!("session `{from}` has no conversation to hand off");
896 };
897 let db = self.state.db.clone();
898 let Some((json, _)) = call_blocking(db, move |db| db.load_session(from_id)).await? else {
899 anyhow::bail!("session `{from}` has no conversation to hand off");
900 };
901 let messages: Vec<microclaw_core::llm_types::Message> = serde_json::from_str(&json)?;
902 let to_id = self.resolve_session_chat_id(to).await?;
903 let previous = crate::context_window::previous_summary(&messages);
904 let focus = format!(
905 "Only what matters for the next task: {}. Leave out finished work that does not affect it.",
906 goal.trim()
907 );
908 let mut summary = previous.clone();
909 for chunk in crate::context_window::chunk_text(
910 &crate::context_window::render_for_summary(&messages),
911 60_000,
912 ) {
913 let request = crate::context_window::summary_request(
914 summary.as_deref(),
915 &chunk,
916 Some(&focus),
917 self.state.config.compact_instructions.as_deref(),
918 );
919 match crate::agent_engine::summarize_once(&self.state, channel, from_id, request).await
920 {
921 Ok(text) if !text.trim().is_empty() => summary = Some(text),
922 _ => {
923 summary = Some(crate::context_window::fallback_summary(&messages));
924 break;
925 }
926 }
927 }
928 let summary = summary.unwrap_or_else(|| crate::context_window::fallback_summary(&messages));
929 let mut text = crate::context_window::summary_message_text(&summary, &messages);
930 text.push_str(&format!(
931 "\n## Next task\n{}\n(This session was started from a handoff of session `{}`.)\n",
932 goal.trim(),
933 from.trim()
934 ));
935 let seeded = vec![
936 microclaw_core::llm_types::Message {
937 role: "user".into(),
938 content: microclaw_core::llm_types::MessageContent::Text(text),
939 },
940 microclaw_core::llm_types::Message {
941 role: "assistant".into(),
942 content: microclaw_core::llm_types::MessageContent::Text(
943 "Understood. I have the handoff summary and the next task.".into(),
944 ),
945 },
946 ];
947 let tokens = crate::context_window::estimate_messages_tokens(&seeded);
948 let json = serde_json::to_string(&seeded)?;
949 let parent_key = format!("headless:{}", from.trim());
950 let db = self.state.db.clone();
951 call_blocking(db, move |db| {
952 if db.load_session(to_id)?.is_some() {
953 return Err(microclaw_core::error::MicroClawError::Config(
954 "the target session already has a conversation".into(),
955 ));
956 }
957 db.save_session_with_meta(to_id, &json, Some(&parent_key), None, None)
958 })
959 .await?;
960 Ok(tokens)
961 }
962
963 pub fn cancel_subagent(&self, session: &str, run_id: &str) -> anyhow::Result<bool> {
965 let external_chat_id = format!("headless:{}", session.trim());
966 let Some(chat_id) = self
967 .state
968 .db
969 .find_chat_id(HEADLESS_CHANNEL, &external_chat_id)?
970 else {
971 return Ok(false);
972 };
973 Ok(crate::tools::subagents::request_subagent_cancel(
974 &self.state.config,
975 &self.state.db,
976 chat_id,
977 run_id,
978 )?)
979 }
980
981 fn process_session(
984 &self,
985 caller_channel: &str,
986 session: &str,
987 ) -> anyhow::Result<
988 Option<(
989 std::sync::Arc<crate::tools::background_process::ProcessRegistry>,
990 String,
991 )>,
992 > {
993 let Some(processes) = self.state.tools.processes() else {
994 return Ok(None);
995 };
996 let external_chat_id = format!("headless:{}", session.trim());
997 let Some(chat_id) = self
998 .state
999 .db
1000 .find_chat_id(HEADLESS_CHANNEL, &external_chat_id)?
1001 else {
1002 return Ok(None);
1003 };
1004 Ok(Some((
1005 processes,
1006 crate::tools::background_process::session_key_for(caller_channel, chat_id),
1007 )))
1008 }
1009
1010 pub fn background_jobs(
1012 &self,
1013 caller_channel: &str,
1014 session: &str,
1015 ) -> anyhow::Result<Vec<crate::tools::background_process::BackgroundJob>> {
1016 Ok(self
1017 .process_session(caller_channel, session)?
1018 .map(|(processes, key)| processes.jobs(&key))
1019 .unwrap_or_default())
1020 }
1021
1022 pub fn detach_foreground_commands(
1025 &self,
1026 caller_channel: &str,
1027 session: &str,
1028 ) -> anyhow::Result<Vec<String>> {
1029 Ok(self
1030 .process_session(caller_channel, session)?
1031 .map(|(processes, key)| processes.detach_foreground(&key))
1032 .unwrap_or_default())
1033 }
1034
1035 pub fn background_job_output(
1037 &self,
1038 caller_channel: &str,
1039 session: &str,
1040 id: &str,
1041 max_bytes: usize,
1042 ) -> anyhow::Result<String> {
1043 let (processes, key) = self
1044 .process_session(caller_channel, session)?
1045 .ok_or_else(|| anyhow::anyhow!("no background processes in this session"))?;
1046 processes
1047 .output_tail(&key, id, max_bytes)
1048 .map_err(|e| anyhow::anyhow!(e))
1049 }
1050
1051 pub async fn kill_background_job(
1053 &self,
1054 caller_channel: &str,
1055 session: &str,
1056 id: &str,
1057 ) -> anyhow::Result<String> {
1058 let (processes, key) = self
1059 .process_session(caller_channel, session)?
1060 .ok_or_else(|| anyhow::anyhow!("no background processes in this session"))?;
1061 processes
1062 .kill(&key, id)
1063 .await
1064 .map_err(|e| anyhow::anyhow!(e))
1065 }
1066
1067 pub async fn load(mut config: Config) -> anyhow::Result<Self> {
1072 let data_root = config.data_root_dir();
1073 let runtime_data_dir = config.runtime_data_dir();
1074 let skills_data_dir = config.skills_data_dir();
1075 crate::builtin_skills::ensure_builtin_skills(Path::new(&skills_data_dir))?;
1076
1077 let db = Database::new(&runtime_data_dir)?;
1078 let memory = MemoryManager::new(&runtime_data_dir);
1079 let skills = SkillManager::from_skills_and_runtime(&skills_data_dir, &runtime_data_dir)
1080 .with_config_verification(&config);
1081 let mut mcp_paths = crate::mcp::collect_config_paths(&data_root);
1082 mcp_paths.extend(
1083 config
1084 .extra_mcp_configs
1085 .iter()
1086 .map(std::path::PathBuf::from),
1087 );
1088 let mcp_manager = crate::mcp::McpManager::from_config_paths(
1089 &mcp_paths,
1090 config.mcp_request_timeout_secs(),
1091 )
1092 .await;
1093
1094 config.data_dir = runtime_data_dir;
1095 config.skills_dir = Some(skills_data_dir);
1096 Ok(Self::new(config, db, memory, skills, mcp_manager))
1097 }
1098
1099 pub fn new(
1100 config: Config,
1101 db: Database,
1102 memory: MemoryManager,
1103 skills: SkillManager,
1104 mcp_manager: crate::mcp::McpManager,
1105 ) -> Self {
1106 let db = Arc::new(db);
1107 let llm = llm::create_provider(&config);
1108 let embedding = embedding::create_provider(&config);
1109 let channel_registry = Arc::new(ChannelRegistry::new());
1110
1111 let memory_backend = Arc::new(MemoryBackend::new(
1112 db.clone(),
1113 MemoryMcpClient::discover(&mcp_manager),
1114 &config.data_dir,
1115 ));
1116 let mut tools = ToolRegistry::new(
1117 &config,
1118 channel_registry.clone(),
1119 db.clone(),
1120 memory_backend.clone(),
1121 );
1122 tools.register_mcp_tools(&mcp_manager);
1123
1124 let chat_turn_queue = Arc::new(crate::chat_turn_queue::ChatTurnQueue::new(
1125 config.chat_turn_queue_max_pending,
1126 ));
1127 let (skill_review_queue, _skill_review_worker) =
1128 crate::skill_review::build_skill_review_channel();
1129 let state = Arc::new(AppState {
1130 config: config.clone(),
1131 channel_registry,
1132 db: db.clone(),
1133 memory: Arc::new(memory),
1134 skills: Arc::new(skills),
1135 hooks: Arc::new(HookManager::from_config(&config).with_db(db.clone())),
1136 llm: Arc::from(llm),
1137 llm_provider_overrides: Arc::new(RwLock::new(HashMap::new())),
1138 llm_model_overrides: Arc::new(RwLock::new(HashMap::new())),
1139 embedding,
1140 memory_backend,
1141 tools: Arc::new(tools),
1142 chat_turn_queue,
1143 skill_review_queue,
1144 metric_exporter: None,
1145 trace_exporter: None,
1146 log_exporter: None,
1147 });
1148 Self { state }
1149 }
1150
1151 pub fn into_embedded_runtime(
1153 self,
1154 caller_channel: impl Into<String>,
1155 max_concurrent_runs: usize,
1156 ) -> Result<crate::internal::runtime::Runtime, crate::internal::runtime::RuntimeBuildError>
1157 {
1158 crate::internal::runtime::Runtime::builder()
1159 .executor(HeadlessRunExecutor::new(self, caller_channel))
1160 .max_concurrent_runs(max_concurrent_runs)
1161 .build()
1162 }
1163
1164 pub async fn run(
1165 &self,
1166 request: HeadlessRunRequest,
1167 event_tx: Option<mpsc::UnboundedSender<RuntimeEventEnvelope>>,
1168 ) -> anyhow::Result<HeadlessRunResult> {
1169 self.run_with_profile(request, AgentProfile::default(), event_tx)
1170 .await
1171 }
1172
1173 pub async fn run_with_profile(
1174 &self,
1175 request: HeadlessRunRequest,
1176 profile: AgentProfile,
1177 event_tx: Option<mpsc::UnboundedSender<RuntimeEventEnvelope>>,
1178 ) -> anyhow::Result<HeadlessRunResult> {
1179 let session_name = request
1180 .session
1181 .clone()
1182 .unwrap_or_else(|| "default".to_string());
1183 let chat_id = self.resolve_session_chat_id(&session_name).await?;
1184 let caller_channel = request.caller_channel;
1185
1186 let stored = StoredMessage {
1187 id: uuid::Uuid::new_v4().to_string(),
1188 chat_id,
1189 sender_name: request.sender_name,
1190 content: request.prompt,
1191 is_from_bot: false,
1192 timestamp: chrono::Utc::now().to_rfc3339(),
1193 };
1194 let _ = call_blocking(self.state.db.clone(), move |db| db.store_message(&stored)).await;
1195
1196 let run_id = request
1197 .run_id
1198 .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
1199 let (raw_event_tx, bridge) = match event_tx {
1200 Some(envelope_tx) => {
1201 let (raw_tx, raw_rx) = mpsc::unbounded_channel();
1202 let bridge = spawn_event_envelope_bridge(run_id.clone(), raw_rx, envelope_tx);
1203 (Some(raw_tx), Some(bridge))
1204 }
1205 None => (None, None),
1206 };
1207 let response = run_agent_turn(
1208 &self.state,
1209 AgentTurn::new(AgentRequestContext {
1210 caller_channel: &caller_channel,
1211 chat_id,
1212 chat_type: "private",
1213 })
1214 .events(raw_event_tx.as_ref())
1215 .profile(profile)
1216 .image(request.image.clone()),
1217 )
1218 .await;
1219 drop(raw_event_tx);
1220 if let Some(bridge) = bridge {
1221 bridge.await?;
1222 }
1223 let response = response?;
1224
1225 let bot_msg = StoredMessage {
1226 id: uuid::Uuid::new_v4().to_string(),
1227 chat_id,
1228 sender_name: "microclaw".to_string(),
1229 content: response.clone(),
1230 is_from_bot: true,
1231 timestamp: chrono::Utc::now().to_rfc3339(),
1232 };
1233 let _ = call_blocking(self.state.db.clone(), move |db| db.store_message(&bot_msg)).await;
1234
1235 Ok(HeadlessRunResult {
1236 run_id,
1237 chat_id,
1238 response,
1239 })
1240 }
1241
1242 pub async fn cancel_session(&self, session: &str) -> anyhow::Result<usize> {
1248 self.cancel_session_for_channel(HEADLESS_CHANNEL, session)
1249 .await
1250 }
1251
1252 pub async fn cancel_code_session(&self, session: &str) -> anyhow::Result<usize> {
1253 self.cancel_session_for_channel(CODE_CHANNEL, session).await
1254 }
1255
1256 async fn cancel_session_for_channel(
1257 &self,
1258 channel: &str,
1259 session: &str,
1260 ) -> anyhow::Result<usize> {
1261 let chat_id = self.resolve_session_chat_id(session).await?;
1262 Ok(crate::run_control::abort_runs(channel, chat_id).await)
1263 }
1264
1265 pub async fn steer_session(&self, session: &str, content: &str) -> anyhow::Result<bool> {
1271 self.steer_session_for_channel(HEADLESS_CHANNEL, session, content)
1272 .await
1273 }
1274
1275 pub async fn steer_code_session(&self, session: &str, content: &str) -> anyhow::Result<bool> {
1276 self.steer_session_for_channel(CODE_CHANNEL, session, content)
1277 .await
1278 }
1279
1280 async fn steer_session_for_channel(
1281 &self,
1282 channel: &str,
1283 session: &str,
1284 content: &str,
1285 ) -> anyhow::Result<bool> {
1286 let content = content.trim();
1287 if content.is_empty() {
1288 anyhow::bail!("steering update must not be empty");
1289 }
1290 let chat_id = self.resolve_session_chat_id(session).await?;
1291 let message_id = uuid::Uuid::new_v4().to_string();
1292 let timestamp = chrono::Utc::now().to_rfc3339();
1293 let pending = PendingMessage {
1294 sender_name: "code".into(),
1295 content: content.to_string(),
1296 message_id: message_id.clone(),
1297 timestamp: timestamp.clone(),
1298 };
1299 if !self
1300 .state
1301 .chat_turn_queue
1302 .enqueue_if_busy(channel, chat_id, pending)
1303 .await
1304 {
1305 return Ok(false);
1306 }
1307
1308 let stored = StoredMessage {
1309 id: message_id,
1310 chat_id,
1311 sender_name: "code".into(),
1312 content: content.to_string(),
1313 is_from_bot: false,
1314 timestamp,
1315 };
1316 call_blocking(self.state.db.clone(), move |db| db.store_message(&stored)).await?;
1317 Ok(true)
1318 }
1319
1320 async fn resolve_session_chat_id(&self, session: &str) -> anyhow::Result<i64> {
1321 let external_chat_id = format!("headless:{session}");
1322 let title = format!("headless-{session}");
1323 Ok(call_blocking(self.state.db.clone(), move |db| {
1324 db.resolve_or_create_chat_id(
1325 HEADLESS_CHANNEL,
1326 &external_chat_id,
1327 Some(&title),
1328 "headless",
1329 )
1330 })
1331 .await?)
1332 }
1333}
1334
1335fn spawn_event_envelope_bridge(
1336 run_id: String,
1337 mut raw_rx: mpsc::UnboundedReceiver<AgentEvent>,
1338 envelope_tx: mpsc::UnboundedSender<RuntimeEventEnvelope>,
1339) -> tokio::task::JoinHandle<()> {
1340 tokio::spawn(async move {
1341 let mut sequence = 0_u64;
1342 while let Some(event) = raw_rx.recv().await {
1343 sequence = sequence.saturating_add(1);
1344 if envelope_tx
1345 .send(RuntimeEventEnvelope::new(&run_id, sequence, event))
1346 .is_err()
1347 {
1348 break;
1349 }
1350 }
1351 })
1352}
1353
1354#[allow(clippy::too_many_arguments)]
1355pub async fn run_once(
1356 config: Config,
1357 db: Database,
1358 memory: MemoryManager,
1359 skills: SkillManager,
1360 mcp_manager: crate::mcp::McpManager,
1361 prompt: String,
1362 session: Option<String>,
1363 json: bool,
1364) -> anyhow::Result<i32> {
1365 let runtime = HeadlessRuntime::new(config, db, memory, skills, mcp_manager)
1366 .into_embedded_runtime(HEADLESS_CHANNEL, 1)?;
1367 let mut request = RunRequest::new(prompt);
1368 request.session_id = session.map(SessionId::new);
1369 let result = runtime
1370 .agent(AgentProfile {
1371 name: "MicroClaw CLI".into(),
1372 ..AgentProfile::default()
1373 })
1374 .run(request)
1375 .result()
1376 .await;
1377
1378 match result {
1379 Ok(result) => {
1380 let chat_id = result
1381 .metadata
1382 .get("chat_id")
1383 .and_then(serde_json::Value::as_i64);
1384 if json {
1385 println!(
1386 "{}",
1387 serde_json::json!({
1388 "ok": true,
1389 "response": result.final_text,
1390 "chat_id": chat_id,
1391 "run_id": result.run_id.to_string(),
1392 })
1393 );
1394 } else {
1395 println!("{}", result.final_text);
1396 }
1397 Ok(0)
1398 }
1399 Err(e) => {
1400 if json {
1401 println!(
1402 "{}",
1403 serde_json::json!({"ok": false, "error": e.to_string()})
1404 );
1405 } else {
1406 eprintln!("Error: {e}");
1407 }
1408 Ok(1)
1409 }
1410 }
1411}
1412
1413#[cfg(test)]
1414mod tests {
1415 use super::*;
1416 use crate::config::WorkingDirIsolation;
1417 use crate::llm::LlmProvider;
1418 use microclaw_core::error::MicroClawError;
1419 use microclaw_core::llm_types::{
1420 Message, MessagesResponse, ResponseContentBlock, ToolDefinition,
1421 };
1422 use microclaw_core::runtime_event::RuntimeEvent;
1423
1424 static RUNTIME_TEST_LOCK: std::sync::LazyLock<tokio::sync::Mutex<()>> =
1425 std::sync::LazyLock::new(|| tokio::sync::Mutex::new(()));
1426
1427 struct FakeLlm;
1428
1429 struct SlowLlm;
1430
1431 struct CapturingLlm {
1432 system_prompt: Arc<std::sync::Mutex<String>>,
1433 }
1434
1435 struct ToolCapturingLlm {
1436 tools: Arc<std::sync::Mutex<Vec<String>>>,
1437 }
1438
1439 struct SteeringLlm {
1440 calls: Arc<std::sync::atomic::AtomicUsize>,
1441 first_call_started: Arc<tokio::sync::Notify>,
1442 saw_update: Arc<std::sync::atomic::AtomicBool>,
1443 }
1444
1445 #[async_trait::async_trait]
1446 impl LlmProvider for FakeLlm {
1447 async fn send_message(
1448 &self,
1449 _system: &str,
1450 _messages: Vec<Message>,
1451 _tools: Option<Vec<ToolDefinition>>,
1452 ) -> Result<MessagesResponse, MicroClawError> {
1453 Ok(MessagesResponse {
1454 content: vec![ResponseContentBlock::Text {
1455 text: "real agent loop response".into(),
1456 }],
1457 stop_reason: Some("end_turn".into()),
1458 usage: None,
1459 })
1460 }
1461 }
1462
1463 #[async_trait::async_trait]
1464 impl LlmProvider for SlowLlm {
1465 async fn send_message(
1466 &self,
1467 _system: &str,
1468 _messages: Vec<Message>,
1469 _tools: Option<Vec<ToolDefinition>>,
1470 ) -> Result<MessagesResponse, MicroClawError> {
1471 tokio::time::sleep(std::time::Duration::from_secs(30)).await;
1472 unreachable!("the cancellation test must stop the pending model call")
1473 }
1474 }
1475
1476 #[async_trait::async_trait]
1477 impl LlmProvider for CapturingLlm {
1478 async fn send_message(
1479 &self,
1480 system: &str,
1481 _messages: Vec<Message>,
1482 _tools: Option<Vec<ToolDefinition>>,
1483 ) -> Result<MessagesResponse, MicroClawError> {
1484 *self.system_prompt.lock().unwrap() = system.to_string();
1485 Ok(MessagesResponse {
1486 content: vec![ResponseContentBlock::Text {
1487 text: "profile applied".into(),
1488 }],
1489 stop_reason: Some("end_turn".into()),
1490 usage: None,
1491 })
1492 }
1493 }
1494
1495 #[async_trait::async_trait]
1496 impl LlmProvider for ToolCapturingLlm {
1497 async fn send_message(
1498 &self,
1499 _system: &str,
1500 _messages: Vec<Message>,
1501 tools: Option<Vec<ToolDefinition>>,
1502 ) -> Result<MessagesResponse, MicroClawError> {
1503 *self.tools.lock().unwrap() = tools
1504 .unwrap_or_default()
1505 .into_iter()
1506 .map(|tool| tool.name)
1507 .collect();
1508 Ok(MessagesResponse {
1509 content: vec![ResponseContentBlock::Text {
1510 text: "policy applied".into(),
1511 }],
1512 stop_reason: Some("end_turn".into()),
1513 usage: None,
1514 })
1515 }
1516 }
1517
1518 #[async_trait::async_trait]
1519 impl LlmProvider for SteeringLlm {
1520 async fn send_message(
1521 &self,
1522 _system: &str,
1523 messages: Vec<Message>,
1524 _tools: Option<Vec<ToolDefinition>>,
1525 ) -> Result<MessagesResponse, MicroClawError> {
1526 let call = self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
1527 if call == 0 {
1528 self.first_call_started.notify_one();
1529 tokio::time::sleep(std::time::Duration::from_millis(100)).await;
1530 return Ok(MessagesResponse {
1531 content: vec![ResponseContentBlock::ToolUse {
1532 id: "todo-read-1".into(),
1533 name: "todo_read".into(),
1534 input: serde_json::json!({}),
1535 thought_signature: None,
1536 }],
1537 stop_reason: Some("tool_use".into()),
1538 usage: None,
1539 });
1540 }
1541 let rendered = format!("{messages:?}");
1542 self.saw_update.store(
1543 rendered.contains("Focus on the parser first"),
1544 std::sync::atomic::Ordering::SeqCst,
1545 );
1546 Ok(MessagesResponse {
1547 content: vec![ResponseContentBlock::Text {
1548 text: "steering applied".into(),
1549 }],
1550 stop_reason: Some("end_turn".into()),
1551 usage: None,
1552 })
1553 }
1554 }
1555
1556 fn runtime_with_fake_llm(base: &Path) -> HeadlessRuntime {
1557 runtime_with_llm(base, Box::new(FakeLlm))
1558 }
1559
1560 fn runtime_with_llm(base: &Path, llm: Box<dyn LlmProvider>) -> HeadlessRuntime {
1561 let runtime_dir = base.join("runtime");
1562 std::fs::create_dir_all(&runtime_dir).unwrap();
1563 let mut config = Config::test_defaults();
1564 config.data_dir = runtime_dir.display().to_string();
1565 config.working_dir = base.display().to_string();
1566 config.working_dir_isolation = WorkingDirIsolation::Shared;
1567 let runtime_dir = runtime_dir.display().to_string();
1568 let db = Arc::new(Database::new(&runtime_dir).unwrap());
1569 let memory_backend = Arc::new(MemoryBackend::local_only(db.clone()));
1570 let channel_registry = Arc::new(ChannelRegistry::new());
1571 HeadlessRuntime {
1572 state: Arc::new(AppState {
1573 config: config.clone(),
1574 channel_registry: channel_registry.clone(),
1575 db: db.clone(),
1576 memory: Arc::new(MemoryManager::new(&runtime_dir)),
1577 skills: Arc::new(SkillManager::from_skills_dir(&config.skills_data_dir())),
1578 hooks: Arc::new(HookManager::from_config(&config)),
1579 llm: Arc::from(llm),
1580 llm_provider_overrides: Arc::new(RwLock::new(HashMap::new())),
1581 llm_model_overrides: Arc::new(RwLock::new(HashMap::new())),
1582 embedding: None,
1583 memory_backend: memory_backend.clone(),
1584 tools: Arc::new(ToolRegistry::new(
1585 &config,
1586 channel_registry,
1587 db,
1588 memory_backend,
1589 )),
1590 chat_turn_queue: Arc::new(crate::chat_turn_queue::ChatTurnQueue::new(20)),
1591 skill_review_queue: crate::skill_review::build_skill_review_channel().0,
1592 metric_exporter: None,
1593 trace_exporter: None,
1594 log_exporter: None,
1595 }),
1596 }
1597 }
1598
1599 #[tokio::test]
1600 async fn event_bridge_adds_stable_run_id_and_monotonic_sequence() {
1601 let (raw_tx, raw_rx) = mpsc::unbounded_channel();
1602 let (envelope_tx, mut envelope_rx) = mpsc::unbounded_channel();
1603 let bridge = spawn_event_envelope_bridge("work-run-1".into(), raw_rx, envelope_tx);
1604
1605 raw_tx
1606 .send(RuntimeEvent::Iteration { iteration: 1 })
1607 .unwrap();
1608 raw_tx
1609 .send(RuntimeEvent::FinalResponse {
1610 text: "done".into(),
1611 })
1612 .unwrap();
1613 drop(raw_tx);
1614 bridge.await.unwrap();
1615
1616 let first = envelope_rx.recv().await.unwrap();
1617 let second = envelope_rx.recv().await.unwrap();
1618 assert_eq!(first.run_id, "work-run-1");
1619 assert_eq!(first.sequence, 1);
1620 assert_eq!(second.run_id, "work-run-1");
1621 assert_eq!(second.sequence, 2);
1622 assert!(envelope_rx.recv().await.is_none());
1623 }
1624
1625 #[tokio::test]
1626 async fn reusable_runtime_executes_real_agent_loop_and_emits_envelopes() {
1627 let _guard = RUNTIME_TEST_LOCK.lock().await;
1628 let directory = tempfile::tempdir().unwrap();
1629 let runtime = runtime_with_fake_llm(directory.path());
1630 let (event_tx, mut event_rx) = mpsc::unbounded_channel();
1631
1632 let result = runtime
1633 .run(
1634 HeadlessRunRequest::code(
1635 "answer through the shared loop".into(),
1636 Some("work-test".into()),
1637 "work-run-test".into(),
1638 ),
1639 Some(event_tx),
1640 )
1641 .await
1642 .unwrap();
1643 let mut events = Vec::new();
1644 while let Some(event) = event_rx.recv().await {
1645 events.push(event);
1646 }
1647
1648 assert_eq!(result.run_id, "work-run-test");
1649 assert_eq!(result.response, "real agent loop response");
1650 assert!(!events.is_empty());
1651 assert!(events.iter().enumerate().all(|(index, envelope)| {
1652 envelope.run_id == "work-run-test" && envelope.sequence == index as u64 + 1
1653 }));
1654 assert!(events.iter().any(|envelope| matches!(
1655 envelope.event,
1656 RuntimeEvent::FinalResponse { ref text } if text == "real agent loop response"
1657 )));
1658 }
1659
1660 #[tokio::test]
1661 async fn durable_subagents_are_observable_and_cancellable_through_headless_runtime() {
1662 use crate::storage::db::subagents::CreateSubagentRunParams;
1663
1664 let _guard = RUNTIME_TEST_LOCK.lock().await;
1665 let directory = tempfile::tempdir().unwrap();
1666 let runtime = runtime_with_fake_llm(directory.path());
1667 let chat_id = runtime
1668 .resolve_session_chat_id("sdk-session")
1669 .await
1670 .unwrap();
1671 runtime
1672 .state
1673 .db
1674 .create_subagent_run(CreateSubagentRunParams {
1675 run_id: "delegated-1",
1676 parent_run_id: Some("main-1"),
1677 depth: 1,
1678 token_budget: 10_000,
1679 chat_id,
1680 caller_channel: HEADLESS_CHANNEL,
1681 task: "inspect the parser",
1682 context: "",
1683 provider: "test",
1684 model: "test",
1685 label: Some("parser review"),
1686 })
1687 .unwrap();
1688
1689 let tasks = runtime.subagent_runs("sdk-session", 20).unwrap();
1690 assert_eq!(tasks.len(), 1);
1691 assert_eq!(tasks[0].parent_run_id.as_deref(), Some("main-1"));
1692 assert_eq!(tasks[0].depth, 1);
1693 assert_eq!(tasks[0].label.as_deref(), Some("parser review"));
1694 assert!(runtime
1695 .cancel_subagent("sdk-session", "delegated-1")
1696 .unwrap());
1697 assert!(runtime.subagent_runs("sdk-session", 20).unwrap()[0].cancel_requested);
1698 }
1699
1700 #[tokio::test]
1701 async fn embedded_agent_profile_applies_prompt_and_selected_skills() {
1702 let _guard = RUNTIME_TEST_LOCK.lock().await;
1703 let directory = tempfile::tempdir().unwrap();
1704 let captured = Arc::new(std::sync::Mutex::new(String::new()));
1705 let headless = runtime_with_llm(
1706 directory.path(),
1707 Box::new(CapturingLlm {
1708 system_prompt: captured.clone(),
1709 }),
1710 );
1711 let skill_dir = headless.state.skills.skills_dir().join("rust-review");
1712 std::fs::create_dir_all(&skill_dir).unwrap();
1713 std::fs::write(
1714 skill_dir.join("SKILL.md"),
1715 "---\nname: rust-review\ndescription: Review Rust\n---\nCHECK_AGENT_SKILL_BODY\n",
1716 )
1717 .unwrap();
1718 let runtime = headless.into_embedded_runtime(CODE_CHANNEL, 1).unwrap();
1719 let profile = AgentProfile {
1720 name: "reviewer".into(),
1721 system_prompt: Some("CHECK_AGENT_PROFILE_PROMPT".into()),
1722 skills: vec!["rust-review".into()],
1723 ..AgentProfile::default()
1724 };
1725
1726 let result = runtime
1727 .agent(profile)
1728 .run(RunRequest::new("review this crate"))
1729 .result()
1730 .await
1731 .unwrap();
1732
1733 assert_eq!(result.final_text, "profile applied");
1734 let system = captured.lock().unwrap();
1735 assert!(system.contains("CHECK_AGENT_PROFILE_PROMPT"), "{system}");
1736 assert!(system.contains("CHECK_AGENT_SKILL_BODY"), "{system}");
1737 }
1738
1739 #[tokio::test]
1740 async fn embedded_read_only_profile_hides_mutating_tools() {
1741 let _guard = RUNTIME_TEST_LOCK.lock().await;
1742 let directory = tempfile::tempdir().unwrap();
1743 let captured = Arc::new(std::sync::Mutex::new(Vec::new()));
1744 let runtime = runtime_with_llm(
1745 directory.path(),
1746 Box::new(ToolCapturingLlm {
1747 tools: captured.clone(),
1748 }),
1749 )
1750 .into_embedded_runtime(CODE_CHANNEL, 1)
1751 .unwrap();
1752 let profile = AgentProfile {
1753 name: "reviewer".into(),
1754 tool_policy: microclaw_core::run_protocol::ToolPolicy::ReadOnly,
1755 ..AgentProfile::default()
1756 };
1757
1758 runtime
1759 .agent(profile)
1760 .run(RunRequest::new("inspect this project"))
1761 .result()
1762 .await
1763 .unwrap();
1764
1765 let tools = captured.lock().unwrap();
1766 assert!(tools.iter().any(|name| name == "read_file"), "{tools:?}");
1767 assert!(!tools.iter().any(|name| name == "write_file"), "{tools:?}");
1768 assert!(!tools.iter().any(|name| name == "bash"), "{tools:?}");
1769 }
1770
1771 #[tokio::test]
1772 async fn cancelling_a_headless_session_stops_the_real_agent_loop() {
1773 let _guard = RUNTIME_TEST_LOCK.lock().await;
1774 let directory = tempfile::tempdir().unwrap();
1775 let runtime = Arc::new(runtime_with_llm(directory.path(), Box::new(SlowLlm)));
1776 let (event_tx, mut event_rx) = mpsc::unbounded_channel();
1777 let running_runtime = runtime.clone();
1778 let run = tokio::spawn(async move {
1779 running_runtime
1780 .run(
1781 HeadlessRunRequest::code(
1782 "wait for cancellation".into(),
1783 Some("cancel-test".into()),
1784 "cancel-run-test".into(),
1785 ),
1786 Some(event_tx),
1787 )
1788 .await
1789 });
1790
1791 tokio::time::timeout(std::time::Duration::from_secs(5), async {
1792 loop {
1793 if runtime.cancel_code_session("cancel-test").await.unwrap() > 0 {
1794 break;
1795 }
1796 tokio::time::sleep(std::time::Duration::from_millis(10)).await;
1797 }
1798 })
1799 .await
1800 .expect("run should register for cancellation");
1801
1802 let result = tokio::time::timeout(std::time::Duration::from_secs(5), run)
1803 .await
1804 .expect("cancelled run should finish promptly")
1805 .unwrap()
1806 .unwrap();
1807 assert_eq!(result.response, crate::run_control::STOPPED_TEXT);
1808
1809 let mut cancelled = false;
1810 while let Some(envelope) = event_rx.recv().await {
1811 cancelled |= matches!(envelope.event, RuntimeEvent::Cancelled { .. });
1812 }
1813 assert!(cancelled);
1814 }
1815
1816 #[tokio::test]
1817 async fn steering_uses_the_active_agent_turn_queue() {
1818 let _guard = RUNTIME_TEST_LOCK.lock().await;
1819 let directory = tempfile::tempdir().unwrap();
1820 let runtime = runtime_with_fake_llm(directory.path());
1821 let chat_id = runtime.resolve_session_chat_id("steer-test").await.unwrap();
1822 let turn = runtime
1823 .state
1824 .chat_turn_queue
1825 .acquire(HEADLESS_CHANNEL, chat_id)
1826 .await
1827 .unwrap();
1828
1829 assert!(runtime
1830 .steer_session("steer-test", "Focus on the parser first")
1831 .await
1832 .unwrap());
1833 let pending = runtime
1834 .state
1835 .chat_turn_queue
1836 .drain_pending(HEADLESS_CHANNEL, chat_id)
1837 .await;
1838 assert_eq!(pending.len(), 1);
1839 assert_eq!(pending[0].sender_name, "code");
1840 assert_eq!(pending[0].content, "Focus on the parser first");
1841 drop(turn);
1842
1843 assert!(!runtime
1844 .steer_session("steer-test", "This run is already idle")
1845 .await
1846 .unwrap());
1847 }
1848
1849 #[tokio::test]
1850 async fn steering_reaches_the_real_agent_loop_after_a_tool_breakpoint() {
1851 let _guard = RUNTIME_TEST_LOCK.lock().await;
1852 let directory = tempfile::tempdir().unwrap();
1853 let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
1854 let first_call_started = Arc::new(tokio::sync::Notify::new());
1855 let saw_update = Arc::new(std::sync::atomic::AtomicBool::new(false));
1856 let runtime = Arc::new(runtime_with_llm(
1857 directory.path(),
1858 Box::new(SteeringLlm {
1859 calls: calls.clone(),
1860 first_call_started: first_call_started.clone(),
1861 saw_update: saw_update.clone(),
1862 }),
1863 ));
1864 let running_runtime = runtime.clone();
1865 let run = tokio::spawn(async move {
1866 running_runtime
1867 .run(
1868 HeadlessRunRequest::code(
1869 "Start with the whole task".into(),
1870 Some("live-steer".into()),
1871 "live-steer-run".into(),
1872 ),
1873 None,
1874 )
1875 .await
1876 });
1877
1878 tokio::time::timeout(
1879 std::time::Duration::from_secs(5),
1880 first_call_started.notified(),
1881 )
1882 .await
1883 .expect("first model call should start");
1884 assert!(runtime
1885 .steer_code_session("live-steer", "Focus on the parser first")
1886 .await
1887 .unwrap());
1888 let result = run.await.unwrap().unwrap();
1889
1890 assert_eq!(result.response, "steering applied");
1891 assert!(calls.load(std::sync::atomic::Ordering::SeqCst) >= 2);
1892 assert!(saw_update.load(std::sync::atomic::Ordering::SeqCst));
1893 }
1894
1895 struct ApprovalLlm {
1897 calls: Arc<std::sync::atomic::AtomicUsize>,
1898 }
1899
1900 #[async_trait::async_trait]
1901 impl LlmProvider for ApprovalLlm {
1902 async fn send_message(
1903 &self,
1904 _system: &str,
1905 messages: Vec<Message>,
1906 _tools: Option<Vec<ToolDefinition>>,
1907 ) -> Result<MessagesResponse, MicroClawError> {
1908 let call = self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
1909 if call == 0 {
1910 return Ok(MessagesResponse {
1911 content: vec![ResponseContentBlock::ToolUse {
1912 id: "bash-1".into(),
1913 name: "bash".into(),
1914 input: serde_json::json!({"command": "echo in-run-ok"}),
1915 thought_signature: None,
1916 }],
1917 stop_reason: Some("tool_use".into()),
1918 usage: None,
1919 });
1920 }
1921 let rendered = format!("{messages:?}");
1922 let text = if rendered.contains("[approval_granted]") {
1923 "saw grant"
1924 } else if rendered.contains("[approval_denied]") {
1925 "saw text denial"
1926 } else if rendered.contains("denied this bash call") {
1927 "saw denial"
1928 } else if rendered.contains("in-run-ok") {
1929 "saw output"
1930 } else {
1931 "saw nothing"
1932 };
1933 Ok(MessagesResponse {
1934 content: vec![ResponseContentBlock::Text { text: text.into() }],
1935 stop_reason: Some("end_turn".into()),
1936 usage: None,
1937 })
1938 }
1939 }
1940
1941 async fn run_with_in_run_answer(session: &str, answer: Option<&str>) -> (String, usize) {
1942 let directory = tempfile::tempdir().unwrap();
1943 let calls = Arc::new(std::sync::atomic::AtomicUsize::new(0));
1944 let engine = runtime_with_llm(
1945 directory.path(),
1946 Box::new(ApprovalLlm {
1947 calls: calls.clone(),
1948 }),
1949 );
1950 let runtime = engine.into_embedded_runtime(CODE_CHANNEL, 1).unwrap();
1951 let mut request = RunRequest::new("run the command");
1952 request.session_id = Some(SessionId::new(session));
1953 if answer.is_some() {
1954 request.metadata.insert(
1955 INTERACTIVE_APPROVALS_KEY.into(),
1956 serde_json::Value::Bool(true),
1957 );
1958 }
1959 let mut run = runtime.agent(AgentProfile::default()).run(request);
1960 let controller = run.controller();
1961 let mut approvals = 0;
1962 tokio::time::timeout(std::time::Duration::from_secs(20), async {
1963 while let Some(envelope) = run.next_event().await {
1964 if let RuntimeEvent::ApprovalRequired { approval_id, .. } = envelope.event {
1965 approvals += 1;
1966 if let Some(answer) = answer.filter(|_| approvals == 1) {
1969 controller
1970 .resolve_approval_confirmed(approval_id, answer)
1971 .await
1972 .unwrap();
1973 }
1974 }
1975 }
1976 })
1977 .await
1978 .expect("run should finish");
1979 let result = run.result().await.unwrap();
1980 (result.final_text, approvals)
1981 }
1982
1983 #[tokio::test]
1984 async fn in_run_approval_continues_the_same_run() {
1985 let _guard = RUNTIME_TEST_LOCK.lock().await;
1986 let (text, approvals) = run_with_in_run_answer("in-run-approve", Some("1")).await;
1987 assert_eq!(approvals, 1);
1988 assert_eq!(text, "saw output");
1989 }
1990
1991 #[tokio::test]
1992 async fn in_run_denial_reaches_the_model_without_running_the_tool() {
1993 let _guard = RUNTIME_TEST_LOCK.lock().await;
1994 let (text, approvals) = run_with_in_run_answer("in-run-deny", Some("deny")).await;
1995 assert_eq!(approvals, 1);
1996 assert_eq!(text, "saw denial");
1997 }
1998
1999 #[tokio::test]
2000 async fn a_deferred_approval_ends_the_run_with_the_text_prompt() {
2001 let _guard = RUNTIME_TEST_LOCK.lock().await;
2002 let (text, approvals) = run_with_in_run_answer("in-run-defer", Some("defer")).await;
2003 assert_eq!(approvals, 2);
2005 assert!(text.contains("bash"), "{text}");
2006 }
2007
2008 #[tokio::test]
2009 async fn without_the_opt_in_an_approval_still_ends_the_run() {
2010 let _guard = RUNTIME_TEST_LOCK.lock().await;
2011 let (text, approvals) = run_with_in_run_answer("text-approval", None).await;
2012 assert_eq!(approvals, 1);
2013 assert!(text.contains("bash"), "{text}");
2014 assert!(!crate::approval_broker::is_registered(CODE_CHANNEL, 1));
2015 }
2016
2017 async fn answer_text_approval(session: &str, reply: &str) -> String {
2020 let directory = tempfile::tempdir().unwrap();
2021 let engine = runtime_with_llm(
2022 directory.path(),
2023 Box::new(ApprovalLlm {
2024 calls: Arc::new(std::sync::atomic::AtomicUsize::new(0)),
2025 }),
2026 );
2027 let runtime = engine.into_embedded_runtime(CODE_CHANNEL, 1).unwrap();
2028 for prompt in ["run the command", reply] {
2029 let mut request = RunRequest::new(prompt);
2030 request.session_id = Some(SessionId::new(session));
2031 let mut run = runtime.agent(AgentProfile::default()).run(request);
2032 tokio::time::timeout(std::time::Duration::from_secs(20), async {
2033 while run.next_event().await.is_some() {}
2034 })
2035 .await
2036 .expect("run should finish");
2037 let result = run.result().await.unwrap();
2038 if prompt == reply {
2039 return result.final_text;
2040 }
2041 }
2042 unreachable!()
2043 }
2044
2045 #[tokio::test]
2046 async fn a_text_approval_reply_is_spelled_out_for_the_model() {
2047 let _guard = RUNTIME_TEST_LOCK.lock().await;
2048 assert_eq!(answer_text_approval("text-approve", "1").await, "saw grant");
2049 }
2050
2051 #[tokio::test]
2052 async fn a_text_denial_reply_is_spelled_out_for_the_model() {
2053 let _guard = RUNTIME_TEST_LOCK.lock().await;
2054 assert_eq!(
2055 answer_text_approval("text-deny", "3").await,
2056 "saw text denial"
2057 );
2058 }
2059
2060 #[tokio::test]
2061 async fn rewinding_a_session_cuts_the_conversation_back_to_a_mark() {
2062 let _guard = RUNTIME_TEST_LOCK.lock().await;
2063 let directory = tempfile::tempdir().unwrap();
2064 let runtime = runtime_with_fake_llm(directory.path());
2065 let empty = runtime.session_mark("s").await.unwrap();
2066 assert_eq!(empty.messages, 0);
2067 runtime
2068 .run(
2069 HeadlessRunRequest::code("first".into(), Some("s".into()), "r1".into()),
2070 None,
2071 )
2072 .await
2073 .unwrap();
2074 let after_first = runtime.session_mark("s").await.unwrap();
2075 assert!(after_first.messages >= 2);
2076 runtime
2077 .run(
2078 HeadlessRunRequest::code("second".into(), Some("s".into()), "r2".into()),
2079 None,
2080 )
2081 .await
2082 .unwrap();
2083 let removed = runtime
2084 .rewind_session_to(CODE_CHANNEL, "s", &after_first)
2085 .await
2086 .unwrap();
2087 assert!(removed >= 2, "removed {removed}");
2088 assert_eq!(runtime.session_mark("s").await.unwrap(), after_first);
2089 assert_eq!(
2091 runtime
2092 .rewind_session_to(CODE_CHANNEL, "s", &after_first)
2093 .await
2094 .unwrap(),
2095 0
2096 );
2097 let stale = SessionMark {
2099 messages: after_first.messages,
2100 fingerprint: after_first.fingerprint ^ 1,
2101 };
2102 assert!(runtime
2103 .rewind_session_to(CODE_CHANNEL, "s", &stale)
2104 .await
2105 .is_err());
2106 runtime
2108 .rewind_session_to(CODE_CHANNEL, "s", &empty)
2109 .await
2110 .unwrap();
2111 assert_eq!(runtime.session_mark("s").await.unwrap().messages, 0);
2112 }
2113
2114 #[tokio::test]
2115 async fn sessions_fork_switch_models_and_compact() {
2116 let _guard = RUNTIME_TEST_LOCK.lock().await;
2117 let directory = tempfile::tempdir().unwrap();
2118 let runtime = runtime_with_fake_llm(directory.path());
2119 runtime
2120 .run(
2121 HeadlessRunRequest::code("first".into(), Some("orig".into()), "r1".into()),
2122 None,
2123 )
2124 .await
2125 .unwrap();
2126 runtime.fork_session("orig", "copy").await.unwrap();
2127 let copied = runtime.session_messages("copy", 10).unwrap();
2128 assert_eq!(copied.len(), 2);
2129 assert_eq!(copied[0].content, "first");
2130 assert!(runtime.fork_session("orig", "copy").await.is_err());
2131 assert!(runtime.fork_session("missing", "x").await.is_err());
2132
2133 let default_model = runtime.session_model(CODE_CHANNEL, "copy").await.unwrap();
2134 assert_eq!(
2135 runtime
2136 .set_session_model(CODE_CHANNEL, "copy", Some("other-model"))
2137 .await
2138 .unwrap(),
2139 "other-model"
2140 );
2141 assert_eq!(
2142 runtime.session_model(CODE_CHANNEL, "orig").await.unwrap(),
2143 default_model
2144 );
2145 assert_eq!(
2146 runtime
2147 .set_session_model(CODE_CHANNEL, "copy", None)
2148 .await
2149 .unwrap(),
2150 default_model
2151 );
2152
2153 let short = runtime
2154 .compact_session(CODE_CHANNEL, "orig", 8, None)
2155 .await
2156 .unwrap();
2157 assert_eq!(short.messages_before, short.messages_after);
2158 assert!(runtime
2159 .compact_session(CODE_CHANNEL, "never-ran", 8, None)
2160 .await
2161 .is_err());
2162 }
2163
2164 struct SummarizingLlm {
2167 summary_requests: Arc<std::sync::Mutex<Vec<String>>>,
2168 fail_summaries: bool,
2169 }
2170
2171 #[async_trait::async_trait]
2172 impl LlmProvider for SummarizingLlm {
2173 async fn send_message(
2174 &self,
2175 system: &str,
2176 messages: Vec<Message>,
2177 _tools: Option<Vec<ToolDefinition>>,
2178 ) -> Result<MessagesResponse, MicroClawError> {
2179 let text = if system == crate::context_window::SUMMARY_SYSTEM_PROMPT {
2180 let request = messages
2181 .iter()
2182 .map(crate::agent_engine::message_to_text)
2183 .collect::<Vec<_>>()
2184 .join("\n");
2185 self.summary_requests.lock().unwrap().push(request);
2186 if self.fail_summaries {
2187 return Err(MicroClawError::LlmApi("summarizer down".into()));
2188 }
2189 "## Goal and constraints\nSUMMARY-OK".to_string()
2190 } else {
2191 "done".to_string()
2192 };
2193 Ok(MessagesResponse {
2194 content: vec![ResponseContentBlock::Text { text }],
2195 stop_reason: Some("end_turn".into()),
2196 usage: None,
2197 })
2198 }
2199 }
2200
2201 async fn run_turns(runtime: &HeadlessRuntime, session: &str, prompts: &[String]) {
2202 for (index, prompt) in prompts.iter().enumerate() {
2203 runtime
2204 .run(
2205 HeadlessRunRequest::code(
2206 prompt.clone(),
2207 Some(session.into()),
2208 format!("{session}-{index}"),
2209 ),
2210 None,
2211 )
2212 .await
2213 .unwrap();
2214 }
2215 }
2216
2217 fn stored_session(runtime: &HeadlessRuntime, session: &str) -> Vec<Message> {
2218 let chat_id = runtime
2219 .state
2220 .db
2221 .find_chat_id(HEADLESS_CHANNEL, &format!("headless:{session}"))
2222 .ok()
2223 .flatten()
2224 .expect("session chat");
2225 let (json, _) = runtime.state.db.load_session(chat_id).unwrap().unwrap();
2226 serde_json::from_str(&json).unwrap()
2227 }
2228
2229 #[test]
2230 fn anthropic_cache_lifetimes() {
2231 assert_eq!(anthropic_cache_ttl("5m").as_secs(), 300);
2232 assert_eq!(anthropic_cache_ttl("1h").as_secs(), 3600);
2233 assert_eq!(anthropic_cache_ttl("weird").as_secs(), 300);
2234 }
2235
2236 #[tokio::test]
2237 async fn manual_compaction_summarizes_with_focus_and_keeps_user_words() {
2238 let _guard = RUNTIME_TEST_LOCK.lock().await;
2239 let directory = tempfile::tempdir().unwrap();
2240 let requests = Arc::new(std::sync::Mutex::new(Vec::new()));
2241 let runtime = runtime_with_llm(
2242 directory.path(),
2243 Box::new(SummarizingLlm {
2244 summary_requests: requests.clone(),
2245 fail_summaries: false,
2246 }),
2247 );
2248 let mut prompts = vec!["Rule: always use pnpm, never npm.".to_string()];
2249 prompts.extend((0..5).map(|i| format!("step {i}")));
2250 run_turns(&runtime, "long", &prompts).await;
2251
2252 let usage = runtime.context_usage(CODE_CHANNEL, "long").await.unwrap();
2253 assert_eq!(usage.conversation.messages, 12);
2254 assert!(usage.window > 0 && usage.auto_compact_threshold > 0);
2255 assert_eq!(
2257 usage.prompt_cache_ttl,
2258 Some(std::time::Duration::from_secs(300))
2259 );
2260
2261 let compaction = runtime
2262 .compact_session(CODE_CHANNEL, "long", 2, Some("the package manager"))
2263 .await
2264 .unwrap();
2265 assert_eq!(compaction.method, "summarized");
2266 assert!(compaction.messages_after < compaction.messages_before);
2267 let request = requests.lock().unwrap().last().cloned().unwrap();
2268 assert!(request.contains("the package manager"), "{request}");
2269 assert!(request.contains("## Goal and constraints"));
2270
2271 let stored = stored_session(&runtime, "long");
2272 let first = crate::agent_engine::message_to_text(&stored[0]);
2273 assert!(first.starts_with(crate::context_window::SUMMARY_MARKER));
2274 assert!(first.contains("SUMMARY-OK"));
2275 assert!(first.contains("always use pnpm, never npm."), "{first}");
2276
2277 run_turns(
2279 &runtime,
2280 "long",
2281 &["step 9".to_string(), "step 10".to_string()],
2282 )
2283 .await;
2284 runtime
2285 .compact_session(CODE_CHANNEL, "long", 2, None)
2286 .await
2287 .unwrap();
2288 let request = requests.lock().unwrap().last().cloned().unwrap();
2289 assert!(request.contains("The summary so far"), "{request}");
2290 assert!(request.contains("SUMMARY-OK"));
2291 }
2292
2293 #[tokio::test]
2294 async fn handoff_seeds_a_new_session_from_a_focused_summary() {
2295 let _guard = RUNTIME_TEST_LOCK.lock().await;
2296 let directory = tempfile::tempdir().unwrap();
2297 let requests = Arc::new(std::sync::Mutex::new(Vec::new()));
2298 let runtime = runtime_with_llm(
2299 directory.path(),
2300 Box::new(SummarizingLlm {
2301 summary_requests: requests.clone(),
2302 fail_summaries: false,
2303 }),
2304 );
2305 run_turns(
2306 &runtime,
2307 "src",
2308 &["Use tabs in the Makefile.".to_string(), "step".to_string()],
2309 )
2310 .await;
2311 runtime
2312 .handoff_session(CODE_CHANNEL, "src", "next", "add a release target")
2313 .await
2314 .unwrap();
2315 let request = requests.lock().unwrap().last().cloned().unwrap();
2316 assert!(request.contains("add a release target"));
2317 let seeded = stored_session(&runtime, "next");
2318 assert_eq!(seeded.len(), 2);
2319 let text = crate::agent_engine::message_to_text(&seeded[0]);
2320 assert!(
2321 text.contains("## Next task\nadd a release target"),
2322 "{text}"
2323 );
2324 assert!(text.contains("Use tabs in the Makefile."));
2325 assert_eq!(stored_session(&runtime, "src").len(), 4);
2327 assert!(runtime
2328 .handoff_session(CODE_CHANNEL, "src", "next", "again")
2329 .await
2330 .is_err());
2331 }
2332
2333 struct RewindingLlm {
2336 calls: Arc<std::sync::atomic::AtomicUsize>,
2337 last_seen: Arc<std::sync::Mutex<Vec<Message>>>,
2338 }
2339
2340 #[async_trait::async_trait]
2341 impl LlmProvider for RewindingLlm {
2342 async fn send_message(
2343 &self,
2344 _system: &str,
2345 messages: Vec<Message>,
2346 _tools: Option<Vec<ToolDefinition>>,
2347 ) -> Result<MessagesResponse, MicroClawError> {
2348 let call = self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
2349 *self.last_seen.lock().unwrap() = messages;
2350 let tool = |id: &str, name: &str, input: serde_json::Value| MessagesResponse {
2351 content: vec![ResponseContentBlock::ToolUse {
2352 id: id.into(),
2353 name: name.into(),
2354 input,
2355 thought_signature: None,
2356 }],
2357 stop_reason: Some("tool_use".into()),
2358 usage: None,
2359 };
2360 Ok(match call {
2361 0 => tool("n1", "context_note", serde_json::json!({"note": "start"})),
2362 1 => tool("g1", "glob", serde_json::json!({"pattern": "**/*.nothing"})),
2363 2 => tool(
2364 "r1",
2365 "rewind_context",
2366 serde_json::json!({"checkpoint": "cp-1", "note": "glob found nothing"}),
2367 ),
2368 _ => MessagesResponse {
2369 content: vec![ResponseContentBlock::Text {
2370 text: "done".into(),
2371 }],
2372 stop_reason: Some("end_turn".into()),
2373 usage: None,
2374 },
2375 })
2376 }
2377 }
2378
2379 #[tokio::test]
2380 async fn rewind_context_drops_steps_after_the_checkpoint() {
2381 let _guard = RUNTIME_TEST_LOCK.lock().await;
2382 let directory = tempfile::tempdir().unwrap();
2383 let last_seen = Arc::new(std::sync::Mutex::new(Vec::new()));
2384 let mut runtime = runtime_with_llm(
2385 directory.path(),
2386 Box::new(RewindingLlm {
2387 calls: Arc::new(std::sync::atomic::AtomicUsize::new(0)),
2388 last_seen: last_seen.clone(),
2389 }),
2390 );
2391 Arc::get_mut(&mut runtime.state)
2392 .unwrap()
2393 .config
2394 .context_tools = true;
2395 let result = runtime
2396 .run(
2397 HeadlessRunRequest::code("find it".into(), Some("rw".into()), "rw-1".into()),
2398 None,
2399 )
2400 .await
2401 .unwrap();
2402 assert!(result.response.contains("done"), "{}", result.response);
2403 let seen = last_seen.lock().unwrap().clone();
2404 let text: Vec<String> = seen
2405 .iter()
2406 .map(crate::agent_engine::message_to_text)
2407 .collect();
2408 let joined = text.join("\n");
2409 assert!(
2410 !joined.contains("[tool_use: glob("),
2411 "the glob step should be gone: {joined}"
2412 );
2413 assert!(
2414 joined.contains("Note from your later self: glob found nothing"),
2415 "{joined}"
2416 );
2417 assert!(joined.contains("Checkpoint cp-1 saved"));
2418 }
2419
2420 #[tokio::test]
2421 async fn an_attached_image_reaches_the_model() {
2422 let _guard = RUNTIME_TEST_LOCK.lock().await;
2423 let directory = tempfile::tempdir().unwrap();
2424 let last_seen = Arc::new(std::sync::Mutex::new(Vec::new()));
2425 let runtime = runtime_with_llm(
2426 directory.path(),
2427 Box::new(RewindingLlm {
2428 calls: Arc::new(std::sync::atomic::AtomicUsize::new(3)),
2430 last_seen: last_seen.clone(),
2431 }),
2432 );
2433 let mut request =
2434 HeadlessRunRequest::code("what is this?".into(), Some("img".into()), "img-1".into());
2435 request.image = Some(("iVBORw==".into(), "image/png".into()));
2436 runtime.run(request, None).await.unwrap();
2437 let seen = last_seen.lock().unwrap().clone();
2438 let has_image = seen.iter().any(|m| match &m.content {
2439 microclaw_core::llm_types::MessageContent::Blocks(blocks) => blocks.iter().any(|b| {
2440 matches!(b, microclaw_core::llm_types::ContentBlock::Image { source } if source.media_type == "image/png")
2441 }),
2442 microclaw_core::llm_types::MessageContent::Text(_) => false,
2443 });
2444 assert!(has_image, "{seen:?}");
2445 assert_eq!(
2446 image_from_metadata(&std::collections::BTreeMap::from([(
2447 IMAGE_KEY.to_string(),
2448 serde_json::json!({"media_type": "image/png", "data": "x"})
2449 )])),
2450 Some(("x".to_string(), "image/png".to_string()))
2451 );
2452 }
2453
2454 #[tokio::test]
2455 async fn failed_summaries_fall_back_to_a_digest_instead_of_dropping_history() {
2456 let _guard = RUNTIME_TEST_LOCK.lock().await;
2457 let directory = tempfile::tempdir().unwrap();
2458 let runtime = runtime_with_llm(
2459 directory.path(),
2460 Box::new(SummarizingLlm {
2461 summary_requests: Arc::new(std::sync::Mutex::new(Vec::new())),
2462 fail_summaries: true,
2463 }),
2464 );
2465 let mut prompts = vec!["Never touch the public API.".to_string()];
2466 prompts.extend((0..4).map(|i| format!("step {i}")));
2467 run_turns(&runtime, "fb", &prompts).await;
2468 let compaction = runtime
2469 .compact_session(CODE_CHANNEL, "fb", 2, None)
2470 .await
2471 .unwrap();
2472 assert_eq!(compaction.method, "fallback");
2473 let first = crate::agent_engine::message_to_text(&stored_session(&runtime, "fb")[0]);
2474 assert!(first.contains("Never touch the public API."), "{first}");
2475 assert!(first.contains("mechanical digest"), "{first}");
2476 }
2477
2478 #[tokio::test]
2479 async fn sessions_compact_automatically_by_tokens() {
2480 let _guard = RUNTIME_TEST_LOCK.lock().await;
2481 let directory = tempfile::tempdir().unwrap();
2482 let mut runtime = runtime_with_llm(
2483 directory.path(),
2484 Box::new(SummarizingLlm {
2485 summary_requests: Arc::new(std::sync::Mutex::new(Vec::new())),
2486 fail_summaries: false,
2487 }),
2488 );
2489 {
2490 let config = &mut Arc::get_mut(&mut runtime.state).unwrap().config;
2491 config.max_session_messages = 0;
2492 config.model_context_window = 6_000;
2493 config.max_tokens = 500;
2494 config.compact_keep_recent_tokens = 300;
2495 }
2496 let prompts: Vec<String> = (0..8)
2498 .map(|i| format!("turn {i}: {}", "lorem ipsum dolor ".repeat(110)))
2499 .collect();
2500 run_turns(&runtime, "auto", &prompts).await;
2501 let stored = stored_session(&runtime, "auto");
2502 assert!(
2503 crate::context_window::is_summary_message(&stored[0]),
2504 "expected an automatic summary, got {} messages",
2505 stored.len()
2506 );
2507 assert!(stored.len() < 16);
2508 }
2509
2510 #[tokio::test]
2511 async fn session_checkpoints_restore_the_workspace() {
2512 let _guard = RUNTIME_TEST_LOCK.lock().await;
2513 let directory = tempfile::tempdir().unwrap();
2514 let mut runtime = runtime_with_fake_llm(directory.path());
2515 Arc::get_mut(&mut runtime.state)
2516 .unwrap()
2517 .config
2518 .checkpoints_enabled = true;
2519 let workspace = directory.path().join("shared");
2520 std::fs::create_dir_all(&workspace).unwrap();
2521 std::fs::write(workspace.join("a.txt"), "one").unwrap();
2522
2523 let first = runtime
2524 .checkpoint_session(CODE_CHANNEL, "cp", "start")
2525 .await
2526 .unwrap()
2527 .unwrap();
2528 let again = runtime
2530 .checkpoint_session(CODE_CHANNEL, "cp", "again")
2531 .await
2532 .unwrap()
2533 .unwrap();
2534 assert_eq!(again.commit, first.commit);
2535
2536 std::fs::write(workspace.join("a.txt"), "two").unwrap();
2537 std::fs::write(workspace.join("b.txt"), "new").unwrap();
2538 let before = runtime
2539 .restore_session_checkpoint(CODE_CHANNEL, "cp", &first.commit)
2540 .await
2541 .unwrap()
2542 .unwrap();
2543 assert_eq!(
2544 std::fs::read_to_string(workspace.join("a.txt")).unwrap(),
2545 "one"
2546 );
2547 assert!(!workspace.join("b.txt").exists());
2548 runtime
2550 .restore_session_checkpoint(CODE_CHANNEL, "cp", &before.commit)
2551 .await
2552 .unwrap();
2553 assert_eq!(
2554 std::fs::read_to_string(workspace.join("a.txt")).unwrap(),
2555 "two"
2556 );
2557 assert!(workspace.join("b.txt").exists());
2558 assert!(
2559 runtime
2560 .session_checkpoints(CODE_CHANNEL, "cp", 10)
2561 .await
2562 .unwrap()
2563 .len()
2564 >= 3
2565 );
2566 }
2567}