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