Skip to main content

microclaw_engine/
headless.rs

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