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