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