1mod convert;
15mod logproc;
16mod select;
17mod tools;
18
19use std::collections::BTreeMap;
20use std::path::{Path, PathBuf};
21use std::sync::Arc;
22use std::time::{Duration, SystemTime, UNIX_EPOCH};
23
24use micromux::{DependencyFailure, Desired, Execution, Health, HealthAttempt, ServiceSnapshot};
25use micromux_control::{
26 Client, ControlEndpoint, ControlError, ENVIRONMENT_PROTOCOL_VERSION, ErrorCode, Request,
27 Response, SESSION_ENV_FILE_PROTOCOL_VERSION, SessionInfo, SocketProbeDetails, endpoint_for,
28 transport_supported, usable_runtime_dirs,
29};
30use regex::{Regex, RegexBuilder};
31use rmcp::{
32 ErrorData, RoleServer, ServerHandler, ServiceExt,
33 handler::server::{
34 router::tool::ToolRouter,
35 wrapper::{Json, Parameters},
36 },
37 model::{
38 CacheScope, Implementation, ListToolsResult, PaginatedRequestParams, ProtocolVersion,
39 ServerCapabilities, ServerConfig,
40 },
41 service::{MaybeSendFuture, RequestContext},
42 tool, tool_handler, tool_router,
43};
44use schemars::JsonSchema;
45use serde::{Deserialize, Serialize};
46
47use crate::select::ToolError;
48use crate::tools::events::{ServiceEventPage, SessionServiceEvent, merge_service_events};
49use crate::tools::health::{
50 ServiceDiagnosis, SnapshotWait, WaitConclusion, bounded_attempt, dependency_failed_error,
51 diagnose_service, health_history, idle_error, latest_health_for_snapshot,
52 retired_service_message, service_needs_diagnosis, service_snapshot, timeout_hint,
53 unavailable_error, wait_for_health, wait_for_snapshot,
54};
55use crate::tools::logs::{
56 FollowGap, ServiceFollowGap, compact_logs_since, current_cursors, current_service_cursor,
57 fetch_and_shape_tail, follow_all_current_logs, follow_gap, next_follow_cursor,
58 truncate_wait_matches,
59};
60use crate::tools::sessions::{
61 CHILD_EXIT_GRACE, OUTDATED_PROXY_START_BUDGET, ReportedStart, START_READY_TIMEOUT,
62 already_running_any, already_starting_pid, holder_may_run, reachable_session_for_start,
63 remove_captured_stderr, spawn_detached_serve, start_failure_message, start_session_report,
64};
65#[cfg(unix)]
66use crate::tools::sessions::{ProcessExitWatch, STOP_CONFIRM_TIMEOUT};
67use micromux_control::wait::{self, WaitFor, WaitVerdict};
68
69type ToolResult<T> = Result<Json<T>, ErrorData>;
70
71const DEFAULT_WAIT_TIMEOUT_SECS: u64 = 60;
72const MAX_WAIT_TIMEOUT_SECS: u64 = 600;
73const DEFAULT_RESTART_LOG_LIMIT: usize = 100;
74const MAX_RESTART_LOG_LIMIT: usize = 1000;
75const DEFAULT_LOG_TAIL: usize = 200;
78const MAX_LOG_TAIL: usize = 2000;
81const DEFAULT_EVENT_TAIL: usize = 50;
82const MAX_EVENT_TAIL: usize = micromux::EVENT_HISTORY;
83const DEFAULT_DIAGNOSE_TAIL: usize = 5;
84const MAX_DIAGNOSE_TAIL: usize = 20;
85const DIAGNOSE_LOG_SCAN: usize = 500;
86const WAIT_POLL_FLOOR: Duration = Duration::from_secs(1);
91const WAIT_LOG_POLL: Duration = Duration::from_millis(250);
92const MUTATION_CURSOR_TIMEOUT: Duration = Duration::from_millis(250);
94const MAX_SESSION_STARTS_PER_WINDOW: usize = 8;
95const SESSION_START_WINDOW: Duration = Duration::from_mins(1);
96const GREP_REGEX_SIZE_LIMIT: usize = 256 * 1024;
97const GREP_PATTERN_MAX_BYTES: usize = 64 * 1024;
98
99const INSTRUCTIONS: &str = "Discover and control running micromux sessions. When no `session` is \
100given, tools target the current project's session. Use `find_service` to locate a service across \
101sessions; service-scoped errors also point at matching sibling sessions. Read a session's browser \
102URLs and allocated ports from `get_session_urls` instead of guessing them. When you run a dev task \
103yourself, such as a migration or a seed against the session's database, read the session's \
104environment or a service's resolved environment with `get_session_env`; values come back only for \
105the `names` you ask for. `start_dynamic_service` remains the way to run a command under \
106the session. Validate a candidate file with `validate_config`; for an active session's on-disk \
107edits, call `reconcile_config` with \
108`dry_run=true` before applying it. Reconciliation adds, retires, and updates configured services but \
109does not restart changed processes. Before creating a runtime service, use `list_sessions` and check \
110`capabilities.dynamic_services`. Supply an `idempotency_key` so creation retries are safe. Leases \
111are bounded by session policy unless it explicitly permits `expires_after=\"none\"`; use \
112`renew_dynamic_service` to extend a live lease without restarting. For servers, use \
113`start_dynamic_service_and_wait` for the create/wait/log/events/diagnosis bundle, or compose \
114`start_dynamic_service`, `wait_for_healthy(after_generation=observed_generation)`, and \
115`follow_logs`. A service with `kind: Job` runs to completion: it reports `Completed` (exit 0) or \
116`Failed`, `wait_for_healthy` and `ensure_service_ready` treat completion as ready, and \
117`restart_service` runs it again, a `manual` one included; use `wait_for_exit` when you need the \
118exit code and output of any one-shot run. \
119`ensure_service_ready` can start a missing session, enable a disabled configured service, and wait \
120for readiness in one call. Use `get_service_events` for startup forensics; pass `service=\"*\"` \
121with its per-service cursor map to follow ordering across the session. `restart_service` and \
122`enable_service` return a generation for `wait_for_healthy`; `restart_service_and_wait` bundles the \
123usual cursor/restart/wait/log flow. Use `wait_for_log` after external actions, `diagnose` for a \
124one-shot failure summary, `get_health_history` when a flapping probe needs more than the latest \
125attempt, `list_log_runs` for retained runs, and `log_cursors` plus \
126`follow_all_logs` around hot reloads. Log tools strip ANSI by default and support regex, context, \
127time, trace-id, compact JSON, and minimum-level filters. Actions go through micromux and retain its \
128dependency and restart semantics. Use `start_session` to create a project's headless session; a \
129human can run `micromux attach` to observe it. Use `stop_session` to stop it explicitly.";
130
131#[derive(Clone)]
133pub struct McpServer {
134 cwd: PathBuf,
135 discovery: select::Discovery,
137 allow_session_start: bool,
138 session_start: Arc<tokio::sync::Semaphore>,
139 session_start_budget: Arc<tokio::sync::Semaphore>,
140 tool_router: ToolRouter<Self>,
141}
142
143#[derive(Debug, Deserialize, JsonSchema)]
144struct SessionArgs {
145 #[serde(default)]
148 session: Option<String>,
149}
150
151#[derive(Debug, Deserialize, JsonSchema)]
152struct SessionEnvArgs {
153 #[serde(default)]
155 session: Option<String>,
156 #[serde(default)]
159 service: Option<String>,
160 #[serde(default)]
164 names: Option<Vec<String>>,
165}
166
167#[derive(Debug, Deserialize, JsonSchema)]
168struct ReconcileConfigArgs {
169 #[serde(default)]
171 session: Option<String>,
172 #[serde(default)]
174 dry_run: bool,
175}
176
177#[derive(Debug, Deserialize, JsonSchema)]
178struct ServiceArgs {
179 service: String,
181 #[serde(default)]
183 session: Option<String>,
184}
185
186#[derive(Debug, Deserialize, JsonSchema)]
187struct ServiceEventsArgs {
188 service: String,
190 #[serde(default)]
192 session: Option<String>,
193 #[serde(default)]
195 after_seq: Option<u64>,
196 #[serde(default)]
198 after: Option<BTreeMap<String, u64>>,
199 #[serde(default)]
201 tail: Option<usize>,
202}
203
204#[derive(Debug, Deserialize, JsonSchema)]
205struct DynamicServiceArgs {
206 #[serde(default)]
208 session: Option<String>,
209 #[serde(flatten)]
211 params: micromux::DynamicServiceParams,
212}
213
214#[derive(Debug, Deserialize, JsonSchema)]
215struct ReplaceDynamicServiceArgs {
216 expected_revision: u64,
218 #[serde(default)]
220 session: Option<String>,
221 #[serde(flatten)]
223 params: micromux::DynamicServiceParams,
224}
225
226#[derive(Debug, Deserialize, JsonSchema)]
227struct RenewDynamicServiceArgs {
228 service: String,
230 expected_revision: u64,
232 #[serde(default)]
234 expires_after: Option<micromux::Lease>,
235 #[serde(default)]
237 session: Option<String>,
238}
239
240#[derive(Debug, Deserialize, JsonSchema)]
241struct FindServiceArgs {
242 service: String,
244}
245
246#[derive(Debug, Deserialize, JsonSchema)]
247struct LogFilterArgs {
248 #[serde(default)]
250 raw: bool,
251 #[serde(default)]
253 #[schemars(length(max = 65536))]
254 grep: Option<String>,
255 #[serde(default)]
258 grep_context: Option<usize>,
259 #[serde(default)]
263 min_level: Option<String>,
264 #[serde(default)]
267 since: Option<String>,
268 #[serde(default)]
270 since_unix_ms: Option<u64>,
271 #[serde(default)]
273 trace_id: Option<String>,
274 #[serde(default)]
277 format: logproc::LogFormat,
278}
279
280#[derive(Debug, Deserialize, JsonSchema)]
281struct LogsArgs {
282 service: String,
284 #[serde(default)]
286 session: Option<String>,
287 #[serde(default)]
290 run_generation: Option<u64>,
291 #[serde(default)]
293 tail: Option<usize>,
294 #[serde(flatten)]
295 filters: LogFilterArgs,
296}
297
298#[derive(Debug, Deserialize, JsonSchema)]
299struct FollowArgs {
300 service: String,
302 #[serde(default)]
304 session: Option<String>,
305 #[serde(default)]
308 run_generation: Option<u64>,
309 #[serde(default)]
314 after_seq: Option<u64>,
315 #[serde(flatten)]
316 filters: LogFilterArgs,
317}
318
319#[derive(Debug, Deserialize, JsonSchema)]
320struct FollowAllArgs {
321 #[serde(default)]
323 session: Option<String>,
324 #[serde(default)]
328 after: BTreeMap<String, u64>,
329 #[serde(default)]
331 limit: Option<usize>,
332 #[serde(flatten)]
333 filters: LogFilterArgs,
334}
335
336#[derive(Debug, Deserialize, JsonSchema)]
337struct StartArgs {
338 #[serde(default)]
341 path: Option<String>,
342}
343
344#[derive(Debug, Deserialize, JsonSchema)]
345struct ValidateConfigArgs {
346 #[serde(default)]
349 path: Option<String>,
350}
351
352#[derive(Debug, Deserialize, JsonSchema)]
353struct EnsureReadyArgs {
354 service: String,
356 #[serde(default)]
358 session: Option<String>,
359 #[serde(default)]
361 path: Option<String>,
362 #[serde(default)]
364 timeout_secs: Option<u64>,
365 #[serde(default)]
367 log_limit: Option<usize>,
368}
369
370#[derive(Debug, Deserialize, JsonSchema)]
371struct WaitArgs {
372 service: String,
374 #[serde(default)]
376 session: Option<String>,
377 #[serde(default)]
380 after_generation: Option<u64>,
381 #[serde(default)]
383 timeout_secs: Option<u64>,
384}
385
386#[derive(Debug, Deserialize, JsonSchema)]
387struct WaitForExitArgs {
388 service: String,
390 #[serde(default)]
392 session: Option<String>,
393 #[serde(default)]
395 after_generation: Option<u64>,
396 #[serde(default)]
398 timeout_secs: Option<u64>,
399 #[serde(default)]
401 log_limit: Option<usize>,
402}
403
404#[derive(Debug, Deserialize, JsonSchema)]
405struct RestartAndWaitArgs {
406 service: String,
408 #[serde(default)]
410 session: Option<String>,
411 #[serde(default)]
413 timeout_secs: Option<u64>,
414 #[serde(default)]
416 log_limit: Option<usize>,
417}
418
419#[derive(Debug, Deserialize, JsonSchema)]
420struct StartDynamicAndWaitArgs {
421 #[serde(default)]
423 session: Option<String>,
424 #[serde(flatten)]
426 params: micromux::DynamicServiceParams,
427 #[serde(default)]
429 timeout_secs: Option<u64>,
430 #[serde(default)]
432 log_limit: Option<usize>,
433}
434
435#[derive(Debug, Deserialize, JsonSchema)]
436struct DiagnoseArgs {
437 #[serde(default)]
439 session: Option<String>,
440 #[serde(default)]
442 tail_per_service: Option<usize>,
443}
444
445#[derive(Debug, Deserialize, JsonSchema)]
446struct WaitLogArgs {
447 service: String,
449 #[serde(default)]
451 session: Option<String>,
452 #[serde(default)]
455 after_seq: Option<u64>,
456 #[serde(default)]
459 after: BTreeMap<String, u64>,
460 #[serde(default)]
462 timeout_secs: Option<u64>,
463 #[serde(default)]
465 limit: Option<usize>,
466 #[serde(flatten)]
467 filters: LogFilterArgs,
468}
469
470#[derive(Debug, Deserialize, JsonSchema)]
471struct LogFilePathArgs {
472 service: String,
474 #[serde(default)]
476 session: Option<String>,
477 #[serde(default)]
479 run_generation: Option<u64>,
480}
481
482#[derive(Serialize, JsonSchema)]
487struct SessionRef {
488 session: String,
489 id: String,
490 pid: u32,
491 config_path: String,
492}
493
494impl From<&SessionInfo> for SessionRef {
495 fn from(info: &SessionInfo) -> Self {
496 Self {
497 session: info.name.clone(),
498 id: info.id.clone(),
499 pid: info.pid,
500 config_path: info.config_path.clone(),
501 }
502 }
503}
504
505#[derive(Serialize, JsonSchema)]
506struct MutationResult {
507 #[serde(flatten)]
508 session_ref: SessionRef,
509 accepted: Vec<micromux::ServiceCommandAck>,
510 service: String,
511 generation: Option<u64>,
512 log_cursor: Option<u64>,
516}
517
518#[derive(Serialize, JsonSchema)]
519struct DynamicMutationResult {
520 #[serde(flatten)]
521 session_ref: SessionRef,
522 #[serde(flatten)]
523 receipt: micromux_control::DynamicServiceAck,
524}
525
526struct DynamicMutation {
527 resolved: select::Resolved,
528 receipt: micromux_control::DynamicServiceAck,
529}
530
531impl DynamicMutation {
532 fn into_result(self) -> DynamicMutationResult {
533 DynamicMutationResult {
534 session_ref: SessionRef::from(&self.resolved.info),
535 receipt: self.receipt,
536 }
537 }
538}
539
540#[derive(Serialize, JsonSchema)]
541struct RestartAndWaitResult {
542 #[serde(flatten)]
543 session_ref: SessionRef,
544 service: String,
545 previous_generation: u64,
546 run_generation: u64,
547 outcome: WaitResult,
548 snapshot: ServiceSnapshot,
549 logs: Vec<logproc::ProcessedEntry>,
550 logs_truncated: bool,
551 events: Vec<micromux::ServiceEvent>,
554 #[serde(skip_serializing_if = "Option::is_none")]
555 diagnosis: Option<ServiceDiagnosis>,
556}
557
558#[derive(Serialize, JsonSchema)]
559struct StartDynamicAndWaitResult {
560 #[serde(flatten)]
561 session_ref: SessionRef,
562 #[serde(flatten)]
563 receipt: micromux_control::DynamicServiceAck,
564 outcome: WaitResult,
565 snapshot: ServiceSnapshot,
566 logs: Vec<logproc::ProcessedEntry>,
567 logs_truncated: bool,
568 events: Vec<micromux::ServiceEvent>,
569 #[serde(skip_serializing_if = "Option::is_none")]
570 diagnosis: Option<ServiceDiagnosis>,
571}
572
573#[derive(Serialize, JsonSchema)]
574struct SessionListResult {
575 sessions: Vec<SessionInfo>,
576 diagnostics: select::DiscoveryDiagnostics,
577}
578
579#[derive(Serialize, JsonSchema)]
580struct ServiceListResult {
581 config_path: String,
582 session: String,
583 session_selector: String,
586 services: Vec<ServiceSnapshot>,
587}
588
589#[derive(Serialize, JsonSchema)]
590struct FindServiceResult {
591 service: String,
592 matches: Vec<ServiceLocation>,
593}
594
595#[derive(Serialize, JsonSchema)]
596struct ServiceLocation {
597 session: String,
599 session_selector: String,
601 pid: u32,
603 config_path: String,
605 working_dir: String,
607 snapshot: Option<ServiceSnapshot>,
611}
612
613#[derive(Serialize, JsonSchema)]
614struct LogsResult {
615 service: String,
616 run_generation: Option<u64>,
617 config_path: String,
618 entries: Vec<logproc::ProcessedEntry>,
619 truncated: bool,
620}
621
622#[derive(Serialize, JsonSchema)]
623struct LogRunsResult {
624 service: String,
625 config_path: String,
626 runs: Vec<micromux::LogRunSummary>,
627}
628
629#[derive(Serialize, JsonSchema)]
630struct LogFilePathResult {
631 service: String,
632 config_path: String,
633 run_generation: u64,
634 path: String,
635}
636
637#[derive(Serialize, JsonSchema)]
638struct SessionMutationResult {
639 #[serde(flatten)]
640 session_ref: SessionRef,
641 accepted: Vec<micromux::ServiceCommandAck>,
642}
643
644#[derive(Serialize, JsonSchema)]
645struct ReconcileConfigResult {
646 #[serde(flatten)]
647 session_ref: SessionRef,
648 dry_run: bool,
649 actions: Vec<micromux::ReconcileAction>,
650}
651
652#[derive(Serialize, JsonSchema)]
653struct StopSessionResult {
654 stopped: bool,
655 #[serde(flatten)]
656 session_ref: SessionRef,
657 note: Option<&'static str>,
658}
659
660#[derive(Debug, Serialize, JsonSchema)]
661struct StartSessionResult {
662 started: bool,
663 #[serde(skip_serializing_if = "Option::is_none")]
664 already_running: Option<bool>,
665 #[serde(skip_serializing_if = "Option::is_none")]
666 reachable: Option<bool>,
667 config_path: String,
668 #[serde(skip_serializing_if = "Option::is_none")]
669 session: Option<String>,
670 #[serde(skip_serializing_if = "Option::is_none")]
671 id: Option<String>,
672 #[serde(skip_serializing_if = "Option::is_none")]
673 pid: Option<u32>,
674 #[serde(skip_serializing_if = "Option::is_none")]
675 endpoint: Option<String>,
676 #[serde(skip_serializing_if = "Option::is_none")]
677 reason: Option<String>,
678 #[serde(skip_serializing_if = "Option::is_none")]
680 urls: Option<micromux::SessionSummary>,
681}
682
683#[derive(Serialize, JsonSchema)]
684struct SessionUrlsResult {
685 config_path: String,
686 session: Option<micromux::SessionSummary>,
689}
690
691#[derive(Serialize, JsonSchema)]
692struct SessionEnvResult {
693 #[serde(flatten)]
694 session_ref: SessionRef,
695 #[serde(skip_serializing_if = "Option::is_none")]
697 service: Option<String>,
698 #[serde(skip_serializing_if = "Option::is_none")]
701 stale: Option<bool>,
702 #[serde(skip_serializing_if = "Option::is_none")]
704 variables: Option<BTreeMap<String, String>>,
705 #[serde(skip_serializing_if = "Option::is_none")]
707 names: Option<Vec<String>>,
708 #[serde(skip_serializing_if = "Vec::is_empty")]
710 missing: Vec<String>,
711 #[serde(skip_serializing_if = "Option::is_none")]
712 hint: Option<&'static str>,
713}
714
715#[derive(Serialize, JsonSchema)]
716struct FollowLogsResult {
717 service: String,
718 run_generation: Option<u64>,
719 entries: Vec<logproc::ProcessedEntry>,
720 next_seq: Option<u64>,
721 gap: Option<FollowGap>,
722 truncated: bool,
723}
724
725#[derive(Serialize, JsonSchema)]
726struct FollowAllLogsResult {
727 config_path: String,
728 entries: Vec<logproc::ProcessedEntry>,
729 next: BTreeMap<String, u64>,
730 gaps: Vec<ServiceFollowGap>,
731 truncated: bool,
732}
733
734#[derive(Serialize, JsonSchema)]
735struct WaitForLogResult {
736 status: WaitForLogStatus,
737 service: String,
738 config_path: String,
739 entries: Vec<logproc::ProcessedEntry>,
740 #[serde(skip_serializing_if = "Option::is_none")]
741 next_seq: Option<u64>,
742 #[serde(skip_serializing_if = "BTreeMap::is_empty")]
743 next: BTreeMap<String, u64>,
744 truncated: bool,
745 #[serde(skip_serializing_if = "Option::is_none")]
746 waited_secs: Option<u64>,
747 #[serde(skip_serializing_if = "Option::is_none")]
748 hint: Option<&'static str>,
749}
750
751#[derive(Serialize, JsonSchema)]
752#[serde(rename_all = "snake_case")]
753enum WaitForLogStatus {
754 Matched,
755 Timeout,
756}
757
758#[derive(Serialize, JsonSchema)]
759struct LogCursorsResult {
760 config_path: String,
761 cursors: BTreeMap<String, u64>,
762}
763
764#[derive(Serialize, JsonSchema)]
765struct HealthResult {
766 config_path: String,
767 service: String,
768 snapshot: ServiceSnapshot,
769 latest_healthcheck: Option<HealthAttempt>,
770}
771
772#[derive(Serialize, JsonSchema)]
773struct HealthHistoryResult {
774 config_path: String,
775 service: String,
776 snapshot: ServiceSnapshot,
777 attempts: Vec<HealthAttempt>,
779}
780
781#[derive(Serialize, JsonSchema)]
782struct SingleServiceEventsResult {
783 #[serde(flatten)]
784 session_ref: SessionRef,
785 service: String,
786 events: Vec<micromux::ServiceEvent>,
788 next_seq: Option<u64>,
790 truncated: bool,
792}
793
794#[derive(Serialize, JsonSchema)]
795struct SessionServiceEventsResult {
796 #[serde(flatten)]
797 session_ref: SessionRef,
798 service: String,
799 events: Vec<SessionServiceEvent>,
801 next: BTreeMap<String, u64>,
803 truncated: bool,
805}
806
807#[derive(Serialize, JsonSchema)]
808#[serde(untagged)]
809enum ServiceEventsResult {
810 Single(SingleServiceEventsResult),
811 Session(SessionServiceEventsResult),
812}
813
814#[derive(Serialize, JsonSchema)]
815#[serde(rename_all = "snake_case")]
816enum EnsureActionKind {
817 StartedSession,
818 EnabledService,
819 RanJob,
821 Waited,
822}
823
824#[derive(Serialize, JsonSchema)]
825struct EnsureAction {
826 kind: EnsureActionKind,
828 detail: String,
829}
830
831#[derive(Serialize, JsonSchema)]
832struct EnsureServiceReadyResult {
833 #[serde(flatten)]
834 session_ref: SessionRef,
835 service: String,
836 actions: Vec<EnsureAction>,
838 outcome: WaitResult,
839 snapshot: ServiceSnapshot,
840 #[serde(skip_serializing_if = "Option::is_none")]
841 diagnosis: Option<ServiceDiagnosis>,
842}
843
844#[derive(Serialize, JsonSchema)]
845struct DiagnoseResult {
846 config_path: String,
847 session: String,
849 session_selector: String,
851 #[serde(skip_serializing_if = "Option::is_none")]
853 disk_log_reads: Option<micromux_control::DiskLogReadHealth>,
854 services: Vec<ServiceDiagnosis>,
855}
856
857#[derive(Serialize, JsonSchema)]
858#[serde(transparent)]
859struct Nullable<T>(Option<T>);
860
861#[derive(Serialize, JsonSchema)]
862struct WaitResult {
863 status: WaitStatus,
864 service: String,
865 #[serde(skip_serializing_if = "Option::is_none")]
866 generation: Option<u64>,
867 #[serde(skip_serializing_if = "Option::is_none")]
868 exit_code: Option<Nullable<i32>>,
869 #[serde(skip_serializing_if = "Option::is_none")]
870 waited_secs: Option<u64>,
871 #[serde(skip_serializing_if = "Option::is_none")]
872 execution: Option<Execution>,
873 #[serde(skip_serializing_if = "Option::is_none")]
874 run_generation: Option<u64>,
875 #[serde(skip_serializing_if = "Option::is_none")]
876 healthcheck_configured: Option<bool>,
877 #[serde(skip_serializing_if = "Option::is_none")]
878 health: Option<Nullable<Health>>,
879 #[serde(skip_serializing_if = "Option::is_none")]
880 uptime_secs: Option<Nullable<u64>>,
881 #[serde(skip_serializing_if = "Option::is_none")]
882 latest_healthcheck: Option<Nullable<HealthAttempt>>,
883 #[serde(skip_serializing_if = "Option::is_none")]
884 dependency_failure: Option<DependencyFailure>,
885 #[serde(skip_serializing_if = "Option::is_none")]
886 hint: Option<&'static str>,
887}
888
889#[derive(Serialize, JsonSchema)]
890#[serde(rename_all = "snake_case")]
891enum WaitStatus {
892 Healthy,
893 Completed,
895 Exited,
896 DependencyFailed,
897 Timeout,
898}
899
900#[derive(Serialize, JsonSchema)]
901#[serde(rename_all = "snake_case")]
902enum WaitForExitStatus {
903 Exited,
904 Timeout,
905}
906
907#[derive(Serialize, JsonSchema)]
908struct WaitForExitResult {
909 #[serde(flatten)]
910 session_ref: SessionRef,
911 service: String,
912 status: WaitForExitStatus,
913 exit_code: Option<i32>,
914 run_generation: u64,
915 snapshot: ServiceSnapshot,
916 logs: Vec<logproc::ProcessedEntry>,
917 logs_truncated: bool,
919 waited_secs: u64,
920}
921
922impl WaitResult {
923 fn from_conclusion(service: String, timeout: Duration, conclusion: &WaitConclusion) -> Self {
924 match conclusion {
925 WaitConclusion::Healthy(snapshot) => Self::healthy(service, snapshot.run_generation),
926 WaitConclusion::Completed(snapshot) => {
927 let mut result = Self::healthy(service, snapshot.run_generation);
928 result.status = WaitStatus::Completed;
929 result.exit_code = Some(Nullable(Some(0)));
930 result
931 }
932 WaitConclusion::Exited(snapshot) => {
933 Self::exited(service, snapshot.last_exit_code, snapshot.run_generation)
934 }
935 WaitConclusion::DependencyFailed { snapshot, failure } => {
936 Self::dependency_failed(service, snapshot, failure.clone())
937 }
938 WaitConclusion::Timeout {
939 snapshot,
940 latest_healthcheck,
941 } => Self::timeout(
942 service,
943 timeout.as_secs(),
944 snapshot,
945 latest_healthcheck.clone(),
946 ),
947 }
948 }
949
950 fn healthy(service: String, generation: u64) -> Self {
951 Self {
952 status: WaitStatus::Healthy,
953 service,
954 generation: Some(generation),
955 exit_code: None,
956 waited_secs: None,
957 execution: None,
958 run_generation: None,
959 healthcheck_configured: None,
960 health: None,
961 uptime_secs: None,
962 latest_healthcheck: None,
963 dependency_failure: None,
964 hint: None,
965 }
966 }
967
968 fn exited(service: String, exit_code: Option<i32>, run_generation: u64) -> Self {
969 Self {
970 status: WaitStatus::Exited,
971 service,
972 generation: None,
973 exit_code: Some(Nullable(exit_code)),
974 waited_secs: None,
975 execution: None,
976 run_generation: Some(run_generation),
977 healthcheck_configured: None,
978 health: None,
979 uptime_secs: None,
980 latest_healthcheck: None,
981 dependency_failure: None,
982 hint: Some("the run exited before becoming healthy — inspect get_logs for why"),
983 }
984 }
985
986 fn dependency_failed(
987 service: String,
988 snapshot: &ServiceSnapshot,
989 failure: DependencyFailure,
990 ) -> Self {
991 Self {
992 status: WaitStatus::DependencyFailed,
993 service,
994 generation: None,
995 exit_code: None,
996 waited_secs: None,
997 execution: Some(snapshot.execution),
998 run_generation: Some(snapshot.run_generation),
999 healthcheck_configured: None,
1000 health: None,
1001 uptime_secs: None,
1002 latest_healthcheck: None,
1003 dependency_failure: Some(failure),
1004 hint: Some(
1005 "the service is blocked behind a dependency that cannot meet its condition — \
1006 restart or enable the dependency named in dependency_failure",
1007 ),
1008 }
1009 }
1010
1011 fn timeout(
1012 service: String,
1013 waited_secs: u64,
1014 snapshot: &ServiceSnapshot,
1015 latest_healthcheck: Option<HealthAttempt>,
1016 ) -> Self {
1017 Self {
1018 status: WaitStatus::Timeout,
1019 service,
1020 generation: None,
1021 exit_code: None,
1022 waited_secs: Some(waited_secs),
1023 execution: Some(snapshot.execution),
1024 run_generation: Some(snapshot.run_generation),
1025 healthcheck_configured: Some(snapshot.healthcheck_configured),
1026 health: Some(Nullable(snapshot.health)),
1027 uptime_secs: Some(Nullable(snapshot.uptime.map(|uptime| uptime.as_secs()))),
1028 latest_healthcheck: Some(Nullable(latest_healthcheck)),
1029 dependency_failure: None,
1030 hint: Some(timeout_hint(snapshot)),
1031 }
1032 }
1033}
1034
1035async fn send_request(endpoint: &ControlEndpoint, request: Request) -> Result<Response, ToolError> {
1036 let mut client = Client::connect(endpoint).await?;
1037 Ok(client.request(request).await?)
1038}
1039
1040struct SessionConn {
1041 endpoint: ControlEndpoint,
1042 client: Client,
1043}
1044
1045impl SessionConn {
1046 async fn connect(endpoint: &ControlEndpoint) -> Result<Self, ToolError> {
1047 Ok(Self {
1048 endpoint: endpoint.clone(),
1049 client: Client::connect(endpoint).await?,
1050 })
1051 }
1052
1053 async fn request(&mut self, request: Request) -> Result<Response, ToolError> {
1054 let retry_safe = request.is_retry_safe();
1055 match self.client.request(request.clone()).await {
1056 Ok(response) => Ok(response),
1057 Err(ControlError::Io(_) | ControlError::Closed) if retry_safe => {
1058 self.client = Client::connect(&self.endpoint).await?;
1059 Ok(self.client.request(request).await?)
1060 }
1061 Err(err) => Err(err.into()),
1062 }
1063 }
1064}
1065
1066fn session_selector(info: &SessionInfo) -> String {
1068 format!("hash:{}", info.id)
1069}
1070
1071fn session_has_service(info: &SessionInfo, service: &str) -> bool {
1074 info.services
1075 .iter()
1076 .any(|brief| brief.id == service || brief.name == service)
1077}
1078
1079fn matching_service(services: Vec<ServiceSnapshot>, selector: &str) -> Option<ServiceSnapshot> {
1080 let index = services
1081 .iter()
1082 .position(|snapshot| snapshot.id == selector)
1083 .or_else(|| {
1084 services
1085 .iter()
1086 .position(|snapshot| snapshot.name == selector)
1087 })?;
1088 services.into_iter().nth(index)
1089}
1090
1091async fn service_in_session(resolved: &select::Resolved, service: &str) -> Option<ServiceSnapshot> {
1092 if resolved.info.protocol_version.minor() >= 5 {
1095 if !resolved.info.services_truncated && !session_has_service(&resolved.info, service) {
1096 return None;
1097 }
1098 return send_request(
1099 &resolved.endpoint,
1100 Request::GetService {
1101 service: service.to_string(),
1102 },
1103 )
1104 .await
1105 .ok()
1106 .and_then(|response| convert::service(response).ok());
1107 }
1108
1109 if !session_has_service(&resolved.info, service) {
1110 return None;
1111 }
1112 send_request(&resolved.endpoint, Request::ListServices)
1113 .await
1114 .ok()
1115 .and_then(|response| convert::services(response).ok())
1116 .and_then(|services| matching_service(services, service))
1117}
1118
1119async fn enrich_unknown_service(
1123 discovery: &select::Discovery,
1124 service: &str,
1125 mut err: ToolError,
1126) -> ToolError {
1127 let ToolError::Remote {
1128 code: ErrorCode::UnknownService,
1129 message,
1130 } = &mut err
1131 else {
1132 return err;
1133 };
1134 let siblings = discovery
1135 .answering_sessions()
1136 .await
1137 .unwrap_or_default()
1138 .into_iter();
1139 let mut matching_siblings = Vec::new();
1140 for resolved in siblings {
1141 if service_in_session(&resolved, service)
1142 .await
1143 .is_some_and(|snapshot| snapshot.id == service)
1144 {
1145 matching_siblings.push(resolved);
1146 }
1147 }
1148 let siblings = matching_siblings;
1149 if !siblings.is_empty() {
1150 let locations = siblings
1151 .iter()
1152 .map(|resolved| {
1153 format!(
1154 "{} (config {})",
1155 session_selector(&resolved.info),
1156 resolved.info.config_path
1157 )
1158 })
1159 .collect::<Vec<_>>()
1160 .join(", ");
1161 *message = format!(
1162 "{message}. `{service}` was not found in the selected session but exists in {} other \
1163 answering session(s); retarget by passing one as `session`: {locations}",
1164 siblings.len()
1165 );
1166 }
1167 err
1168}
1169
1170async fn service_events_tail(
1174 discovery: &select::Discovery,
1175 conn: &mut SessionConn,
1176 service: &str,
1177) -> Result<Vec<micromux::ServiceEvent>, ErrorData> {
1178 let response = conn
1179 .request(Request::GetEvents {
1180 service: service.to_string(),
1181 after: None,
1182 tail: Some(micromux::EVENT_HISTORY),
1183 })
1184 .await
1185 .map_err(error_data)?;
1186 let (events, _) = service_result(discovery, service, convert::events(response)).await?;
1187 Ok(events)
1188}
1189
1190async fn service_result<T>(
1191 discovery: &select::Discovery,
1192 service: &str,
1193 result: Result<T, ToolError>,
1194) -> Result<T, ErrorData> {
1195 match result {
1196 Ok(value) => Ok(value),
1197 Err(err) => Err(error_data(
1198 enrich_unknown_service(discovery, service, err).await,
1199 )),
1200 }
1201}
1202
1203struct LogFilters {
1204 grep: Option<Regex>,
1205 grep_context: usize,
1206 min_level: Option<logproc::Level>,
1207 since_unix_ms: Option<u64>,
1208 trace_id: Option<String>,
1209 format: logproc::LogFormat,
1210}
1211
1212impl LogFilters {
1213 fn from_args(args: &LogFilterArgs) -> Result<Self, ErrorData> {
1214 Ok(Self {
1215 grep: compile_grep(args.grep.as_deref())?,
1216 grep_context: args.grep_context.unwrap_or(0).min(20),
1217 min_level: parse_min_level(args.min_level.as_deref())?,
1218 since_unix_ms: parse_since(args.since.as_deref(), args.since_unix_ms)?,
1219 trace_id: args.trace_id.clone(),
1220 format: args.format,
1221 })
1222 }
1223
1224 fn shape(&self, raw: bool, limit: Option<usize>) -> logproc::Shape<'_> {
1225 logproc::Shape {
1226 raw,
1227 grep: self.grep.as_ref(),
1228 context: self.grep_context,
1229 min_level: self.min_level,
1230 since_unix_ms: self.since_unix_ms,
1231 trace_id: self.trace_id.as_deref(),
1232 limit,
1233 format: self.format,
1234 }
1235 }
1236
1237 fn filters_records(&self) -> bool {
1238 self.grep.is_some()
1239 || self.min_level.is_some()
1240 || self.since_unix_ms.is_some()
1241 || self.trace_id.is_some()
1242 }
1243}
1244
1245impl McpServer {
1246 #[must_use]
1248 pub fn new() -> Self {
1249 Self::with_session_start(false)
1250 }
1251
1252 #[must_use]
1254 pub fn with_session_start(allow_session_start: bool) -> Self {
1255 let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
1256 Self {
1257 cwd,
1258 discovery: select::Discovery::default(),
1259 allow_session_start,
1260 session_start: Arc::new(tokio::sync::Semaphore::new(1)),
1261 session_start_budget: Arc::new(tokio::sync::Semaphore::new(
1262 MAX_SESSION_STARTS_PER_WINDOW,
1263 )),
1264 tool_router: Self::tool_router(),
1265 }
1266 }
1267
1268 async fn mutate(
1269 &self,
1270 session: Option<String>,
1271 request: Request,
1272 service: &str,
1273 ) -> ToolResult<MutationResult> {
1274 let resolved = self
1275 .discovery
1276 .resolve(&self.cwd, session)
1277 .await
1278 .map_err(error_data)?;
1279 let log_cursor = capture_mutation_cursor(&resolved.endpoint, service).await;
1280 let mut conn = SessionConn::connect(&resolved.endpoint)
1281 .await
1282 .map_err(error_data)?;
1283 let response = conn.request(request).await.map_err(error_data)?;
1284 let acks = service_result(&self.discovery, service, convert::accepted(response)).await?;
1285 let generation = acks
1286 .iter()
1287 .find(|ack| ack.service == service)
1288 .map(|ack| ack.observed_generation);
1289 Ok(Json(MutationResult {
1290 session_ref: SessionRef::from(&resolved.info),
1291 accepted: acks,
1292 service: service.to_string(),
1293 generation,
1294 log_cursor,
1295 }))
1296 }
1297
1298 async fn start_for_target(&self, target: PathBuf) -> Result<StartSessionResult, ErrorData> {
1299 if !self.allow_session_start {
1300 return Err(ErrorData::invalid_params(
1301 "session startup is disabled; launch `micromux mcp --allow-session-start` to permit process spawning",
1302 None,
1303 ));
1304 }
1305 let _serial = Arc::clone(&self.session_start)
1306 .try_acquire_owned()
1307 .map_err(|_| {
1308 ErrorData::invalid_params("another session-start request is in progress", None)
1309 })?;
1310 let budget = Arc::clone(&self.session_start_budget)
1311 .try_acquire_owned()
1312 .map_err(|_| {
1313 ErrorData::invalid_params(
1314 "session-start rate limit reached; wait before spawning another session",
1315 None,
1316 )
1317 })?;
1318 tokio::spawn(async move {
1319 tokio::time::sleep(SESSION_START_WINDOW).await;
1320 drop(budget);
1321 });
1322 self.start_for_target_unchecked(target).await
1323 }
1324
1325 async fn start_for_target_unchecked(
1326 &self,
1327 target: PathBuf,
1328 ) -> Result<StartSessionResult, ErrorData> {
1329 if !transport_supported() {
1330 return Err(error_data(ToolError::Unsupported));
1331 }
1332 let config_path = select::config_for_target(&target).await.ok_or_else(|| {
1333 ErrorData::invalid_params(
1334 format!("no micromux config found at or above {}", target.display()),
1335 None,
1336 )
1337 })?;
1338 let dir_statuses = self.discovery.runtime_dir_statuses();
1339 let runtime_dirs = usable_runtime_dirs(&dir_statuses);
1340 if runtime_dirs.is_empty() {
1341 let diagnostics = select::discovery_diagnostics(
1342 &self.cwd,
1343 "no runtime directory could be resolved".to_string(),
1344 Some(&config_path),
1345 &dir_statuses,
1346 SocketProbeDetails::default(),
1347 );
1348 return Err(ErrorData::internal_error(
1349 "no runtime directory could be resolved",
1350 serde_json::to_value(diagnostics).ok(),
1351 ));
1352 }
1353 let endpoints = runtime_dirs
1354 .iter()
1355 .map(|runtime_dir| endpoint_for(runtime_dir, &config_path))
1356 .collect::<Vec<_>>();
1357
1358 if let Some(report) = already_running_any(&endpoints, &config_path)
1361 .await
1362 .map_err(error_data)?
1363 {
1364 return Ok(report);
1365 }
1366
1367 let spawned = spawn_detached_serve(&config_path).map_err(|err| {
1368 if err.kind() == std::io::ErrorKind::Unsupported {
1371 error_data(ToolError::Unsupported)
1372 } else {
1373 ErrorData::internal_error(format!("failed to spawn `micromux serve`: {err}"), None)
1374 }
1375 })?;
1376 await_spawned_session(spawned, &endpoints, &config_path).await
1377 }
1378
1379 fn require_dynamic_capability(info: &SessionInfo) -> Result<(), ErrorData> {
1380 let enabled = info
1381 .capabilities
1382 .as_ref()
1383 .and_then(|capabilities| capabilities.dynamic_services.as_ref())
1384 .is_some();
1385 if enabled {
1386 Ok(())
1387 } else {
1388 Err(ErrorData::invalid_params(
1389 format!(
1390 "PolicyDenied: dynamic services are disabled for this session; set \
1391 control.dynamic_services.enabled: true in {} and restart the session",
1392 info.config_path
1393 ),
1394 None,
1395 ))
1396 }
1397 }
1398
1399 async fn dynamic_mutation(
1402 &self,
1403 session: Option<String>,
1404 service: &str,
1405 request: Request,
1406 ) -> Result<DynamicMutation, ErrorData> {
1407 let resolved = self
1408 .discovery
1409 .resolve(&self.cwd, session)
1410 .await
1411 .map_err(error_data)?;
1412 Self::require_dynamic_capability(&resolved.info)?;
1413 let response = send_request(&resolved.endpoint, request)
1414 .await
1415 .map_err(error_data)?;
1416 let receipt =
1417 service_result(&self.discovery, service, convert::dynamic_service(response)).await?;
1418 Ok(DynamicMutation { resolved, receipt })
1419 }
1420}
1421
1422async fn capture_mutation_cursor(endpoint: &ControlEndpoint, service: &str) -> Option<u64> {
1428 let capture = async {
1429 let mut conn = SessionConn::connect(endpoint).await?;
1430 current_service_cursor(&mut conn, service).await
1431 };
1432 if let Ok(cursor) = tokio::time::timeout(MUTATION_CURSOR_TIMEOUT, capture).await {
1433 return best_effort_mutation_cursor(service, cursor);
1434 }
1435 tracing::warn!(
1436 service,
1437 timeout_ms = %MUTATION_CURSOR_TIMEOUT.as_millis(),
1438 "timed out capturing the pre-mutation log cursor"
1439 );
1440 None
1441}
1442
1443fn best_effort_mutation_cursor(service: &str, cursor: Result<u64, ToolError>) -> Option<u64> {
1444 match cursor {
1445 Ok(cursor) => Some(cursor),
1446 Err(err) => {
1447 tracing::warn!(
1448 service,
1449 error = %err,
1450 "could not capture the pre-mutation log cursor"
1451 );
1452 None
1453 }
1454 }
1455}
1456
1457#[tool_router(router = tool_router)]
1458impl McpServer {
1459 #[tool(
1460 description = "List all micromux sessions currently running for this user, with their \
1461 name, pid, config path, working directory, advertised capabilities, discovery \
1462 diagnostics, and under `session` their browser URLs (`routes[].url`), allocated ports, \
1463 routing status, and optional Git branch and cached open PR number (`session.git`)."
1464 )]
1465 async fn list_sessions(&self) -> ToolResult<SessionListResult> {
1466 let list = self.discovery.list_sessions().await.map_err(error_data)?;
1467 Ok(Json(SessionListResult {
1468 sessions: list.sessions,
1469 diagnostics: list.diagnostics,
1470 }))
1471 }
1472
1473 #[tool(
1474 description = "Show a session's browser URLs, allocated ports, and whether the shared \
1475 proxy serves its routes right now, plus optional Git branch and cached open PR context. \
1476 Open the URLs (such as http://app.<session>.localhost) \
1477 in a browser or Playwright; services reach each other on 127.0.0.1:<port> instead, since \
1478 only browsers resolve *.localhost everywhere. Read URLs from here instead of guessing them."
1479 )]
1480 async fn get_session_urls(
1481 &self,
1482 args: Parameters<SessionArgs>,
1483 ) -> ToolResult<SessionUrlsResult> {
1484 let Parameters(args) = args;
1485 let resolved = self
1486 .discovery
1487 .resolve(&self.cwd, args.session)
1488 .await
1489 .map_err(error_data)?;
1490 Ok(Json(SessionUrlsResult {
1491 config_path: resolved.info.config_path,
1492 session: resolved.info.session.map(|session| *session),
1493 }))
1494 }
1495
1496 #[tool(
1497 description = "Read a running session's environment, to run a dev task yourself with \
1498 exactly what its services get, such as a migration or seed against the session's \
1499 database. Without `service`, returns the session's own environment: the top-level \
1500 env_file, read from disk now, with the session variables over it (MICROMUX_SESSION, \
1501 MICROMUX_SESSION_DOMAIN, MICROMUX_PROXY_PORT, MICROMUX_HOST_SUFFIX, and every allocated \
1502 port). With `service` (its id), returns that service's resolved env_file and \
1503 environment entries with the session variables applied, as its running process got \
1504 them; `stale` says whether its config changed since. Values may hold secrets from env \
1505 files, so it returns only names unless you pass `names`. Requested names that are not \
1506 set are listed in `missing`. The result names the session and config it read from."
1507 )]
1508 async fn get_session_env(
1509 &self,
1510 args: Parameters<SessionEnvArgs>,
1511 ) -> ToolResult<SessionEnvResult> {
1512 let Parameters(args) = args;
1513 let resolved = self
1514 .discovery
1515 .resolve(&self.cwd, args.session)
1516 .await
1517 .map_err(error_data)?;
1518 let version = resolved.info.protocol_version;
1519 if !version.supports(ENVIRONMENT_PROTOCOL_VERSION) {
1520 return Err(ErrorData::invalid_params(
1521 format!(
1522 "session `{}` speaks control protocol {version}, but get_session_env needs \
1523 {ENVIRONMENT_PROTOCOL_VERSION} or later; restart the session with this \
1524 micromux",
1525 resolved.info.name
1526 ),
1527 None,
1528 ));
1529 }
1530 let request =
1533 if args.service.is_none() && version.supports(SESSION_ENV_FILE_PROTOCOL_VERSION) {
1534 Request::GetSessionEnvironment
1535 } else {
1536 Request::GetEnvironment {
1537 service: args.service.clone(),
1538 }
1539 };
1540 let response = send_request(&resolved.endpoint, request)
1541 .await
1542 .map_err(error_data)?;
1543 let environment = match &args.service {
1544 Some(service) => {
1545 service_result(&self.discovery, service, convert::environment(response)).await?
1546 }
1547 None => convert::environment(response).map_err(error_data)?,
1548 };
1549 let micromux::ResolvedEnvironment {
1550 mut variables,
1551 stale,
1552 } = environment;
1553 let mut result = SessionEnvResult {
1554 session_ref: SessionRef::from(&resolved.info),
1555 stale: args.service.as_ref().map(|_| stale),
1556 service: args.service,
1557 variables: None,
1558 names: None,
1559 missing: Vec::new(),
1560 hint: None,
1561 };
1562 if let Some(names) = args.names {
1563 result.missing = names
1564 .iter()
1565 .filter(|name| !variables.contains_key(*name))
1566 .cloned()
1567 .collect();
1568 variables.retain(|key, _| names.contains(key));
1569 result.variables = Some(variables);
1570 } else {
1571 result.names = Some(variables.into_keys().collect());
1572 result.hint = Some("pass `names` to read values");
1573 }
1574 Ok(Json(result))
1575 }
1576
1577 #[tool(
1578 description = "Validate a micromux config without starting a session. Runs the same parse, \
1579 service normalization, environment-file/interpolation, port, and dependency-graph checks \
1580 used at startup and returns structured plus ANSI-free rendered diagnostics. A `${VAR}` \
1581 reference that cannot be resolved is an error naming the service, field, and variable, \
1582 and every optional env file that was skipped is reported as a note. Interpolation uses \
1583 the MCP process environment, so unset-variable errors and which optional env files are \
1584 found can differ from the eventual session environment."
1585 )]
1586 async fn validate_config(
1587 &self,
1588 args: Parameters<ValidateConfigArgs>,
1589 ) -> ToolResult<micromux::ValidationReport> {
1590 let Parameters(args) = args;
1591 let target = args
1592 .path
1593 .as_deref()
1594 .map_or_else(|| self.cwd.clone(), PathBuf::from);
1595 let config_path = select::config_for_target(&target).await.ok_or_else(|| {
1596 ErrorData::invalid_params(
1597 format!("no micromux config found at or above {}", target.display()),
1598 None,
1599 )
1600 })?;
1601 let report = tokio::task::spawn_blocking(move || {
1602 micromux::validate_config_file(&config_path, None)
1604 })
1605 .await
1606 .map_err(|err| ErrorData::internal_error(format!("validation task failed: {err}"), None))?
1607 .map_err(|err| ErrorData::invalid_params(err.to_string(), None))?;
1608 Ok(Json(report))
1609 }
1610
1611 #[tool(
1612 description = "Reconcile a running session's configured services with its on-disk \
1613 micromux.yaml. Run with dry_run=true first to inspect the semantic add/remove/change diff; \
1614 validate_config provides a no-session pre-flight. Changed services are not restarted, so \
1615 follow with restart_service or restart_service_and_wait when the new definition should run."
1616 )]
1617 async fn reconcile_config(
1618 &self,
1619 args: Parameters<ReconcileConfigArgs>,
1620 ) -> ToolResult<ReconcileConfigResult> {
1621 let Parameters(args) = args;
1622 let resolved = self
1623 .discovery
1624 .resolve(&self.cwd, args.session)
1625 .await
1626 .map_err(error_data)?;
1627 let response = send_request(
1628 &resolved.endpoint,
1629 Request::ReconcileConfig {
1630 dry_run: args.dry_run,
1631 },
1632 )
1633 .await
1634 .map_err(error_data)?;
1635 let receipt = convert::reconcile(response).map_err(error_data)?;
1636 Ok(Json(ReconcileConfigResult {
1637 session_ref: SessionRef::from(&resolved.info),
1638 dry_run: receipt.dry_run,
1639 actions: receipt.actions,
1640 }))
1641 }
1642
1643 #[tool(
1644 description = "List the services in a session with their desired/execution state, health, \
1645 advertised ports, pid, start time, config drift, uptime, restart state/policy, last exit \
1646 code, run generation, configured/dynamic origin and revision, resolved command (argv), and \
1647 working directory. The result carries a copy-pasteable session_selector."
1648 )]
1649 async fn list_services(&self, args: Parameters<SessionArgs>) -> ToolResult<ServiceListResult> {
1650 let Parameters(args) = args;
1651 let resolved = self
1652 .discovery
1653 .resolve(&self.cwd, args.session)
1654 .await
1655 .map_err(error_data)?;
1656 let response = send_request(&resolved.endpoint, Request::ListServices)
1657 .await
1658 .map_err(error_data)?;
1659 let services = convert::services(response).map_err(error_data)?;
1660 let session_selector = session_selector(&resolved.info);
1661 Ok(Json(ServiceListResult {
1662 config_path: resolved.info.config_path,
1663 session: resolved.info.name,
1664 session_selector,
1665 services,
1666 }))
1667 }
1668
1669 #[tool(
1670 description = "Locate a service by id or name across every running micromux session. \
1671 Returns each matching session's copy-pasteable selector, config path, working directory, \
1672 and the service's current snapshot (state, health, run generation, command, advertised \
1673 ports and configured/dynamic origin), so dynamic services appear like every other roster \
1674 entry and can be targeted without the list_sessions -> pick a hash -> list_services dance."
1675 )]
1676 async fn find_service(
1677 &self,
1678 args: Parameters<FindServiceArgs>,
1679 ) -> ToolResult<FindServiceResult> {
1680 let Parameters(args) = args;
1681 let sessions = self
1684 .discovery
1685 .answering_sessions()
1686 .await
1687 .map_err(error_data)?;
1688 let mut matches = Vec::new();
1689 for resolved in sessions {
1690 let Some(snapshot) = service_in_session(&resolved, &args.service).await else {
1691 continue;
1692 };
1693 let session_selector = session_selector(&resolved.info);
1694 let info = resolved.info;
1695 matches.push(ServiceLocation {
1696 session: info.name,
1697 session_selector,
1698 pid: info.pid,
1699 config_path: info.config_path,
1700 working_dir: info.working_dir,
1701 snapshot: Some(snapshot),
1702 });
1703 }
1704 Ok(Json(FindServiceResult {
1705 service: args.service,
1706 matches,
1707 }))
1708 }
1709
1710 #[tool(
1711 description = "Read recent log entries for one service, or pass service=\"*\" to merge the \
1712 current visible logs from all services with timestamp-guided, cursor-safe ordering. Omit \
1713 run_generation for the visible bounded log stream; pass a retained run_generation from list_log_runs to inspect a \
1714 bounded tail of a current or previous disk-backed run (single-service only). Use follow_logs to page through a \
1715 retained run with a cursor. ANSI color is stripped by default (raw=true keeps it), terminal \
1716 padding is trimmed, and tail counts logical log entries, not wrapped terminal rows. Filter \
1717 with grep (regex), grep_context, since, trace_id, or, for JSON-log services, min_level. Use \
1718 format=\"compact\" for token-efficient structured JSON logs; entries carry micromux \
1719 ingestion timestamps, a detected `level`, optional parsed service timestamp, and parsed \
1720 `message`/`fields` for structured JSON logs."
1721 )]
1722 async fn get_logs(&self, args: Parameters<LogsArgs>) -> ToolResult<LogsResult> {
1723 let Parameters(args) = args;
1724 let filters = LogFilters::from_args(&args.filters)?;
1725 let resolved = self
1726 .discovery
1727 .resolve(&self.cwd, args.session)
1728 .await
1729 .map_err(error_data)?;
1730 let filtering = filters.filters_records();
1731 let default_tail = if args.run_generation.is_some() {
1734 MAX_LOG_TAIL
1735 } else {
1736 DEFAULT_LOG_TAIL
1737 };
1738 let requested_tail = args.tail.unwrap_or(default_tail).min(MAX_LOG_TAIL);
1739 let fetch_tail = if filtering {
1741 MAX_LOG_TAIL
1742 } else {
1743 requested_tail
1744 };
1745 if args.service == "*" {
1746 if args.run_generation.is_some() {
1747 return Err(ErrorData::invalid_params(
1748 "service=\"*\" only supports the current visible log stream; retained \
1749 run_generation is service-scoped",
1750 None,
1751 ));
1752 }
1753 let mut conn = SessionConn::connect(&resolved.endpoint)
1754 .await
1755 .map_err(error_data)?;
1756 let response = conn
1757 .request(Request::ListServices)
1758 .await
1759 .map_err(error_data)?;
1760 let services = convert::services(response).map_err(error_data)?;
1761 let mut entries = Vec::new();
1762 let mut truncated = false;
1763 for service in services {
1764 let (mut shaped, window_full, server_truncated) = fetch_and_shape_tail(
1765 &self.discovery,
1766 &mut conn,
1767 &service.id,
1768 None,
1769 fetch_tail,
1770 &filters,
1771 args.filters.raw,
1772 )
1773 .await?;
1774 truncated |= server_truncated || (window_full && filtering);
1775 for entry in &mut shaped {
1776 entry.service = Some(service.id.clone());
1777 }
1778 entries.extend(shaped);
1779 }
1780 let mut entries = logproc::merge_preserving_service_order(entries);
1781 if entries.len() > requested_tail {
1782 truncated |=
1783 logproc::tail_preserving_record_boundaries(&mut entries, requested_tail);
1784 }
1785 return Ok(Json(LogsResult {
1786 service: args.service,
1787 run_generation: args.run_generation,
1788 config_path: resolved.info.config_path,
1789 entries,
1790 truncated,
1791 }));
1792 }
1793 let mut conn = SessionConn::connect(&resolved.endpoint)
1794 .await
1795 .map_err(error_data)?;
1796 let (mut entries, window_full, server_truncated) = fetch_and_shape_tail(
1797 &self.discovery,
1798 &mut conn,
1799 &args.service,
1800 args.run_generation,
1801 fetch_tail,
1802 &filters,
1803 args.filters.raw,
1804 )
1805 .await?;
1806 let mut truncated =
1809 server_truncated || (window_full && (filtering || entries.len() < requested_tail));
1810 if entries.len() > requested_tail {
1813 truncated |= logproc::tail_preserving_record_boundaries(&mut entries, requested_tail);
1814 }
1815 Ok(Json(LogsResult {
1816 service: args.service,
1817 run_generation: args.run_generation,
1818 config_path: resolved.info.config_path,
1819 entries,
1820 truncated,
1821 }))
1822 }
1823
1824 #[tool(
1825 description = "List retained log runs for a service, including run generations and \
1826 sequence ranges. Use a returned run_generation with get_logs/follow_logs to inspect or \
1827 page through disk-backed run logs."
1828 )]
1829 async fn list_log_runs(&self, args: Parameters<ServiceArgs>) -> ToolResult<LogRunsResult> {
1830 let Parameters(args) = args;
1831 let resolved = self
1832 .discovery
1833 .resolve(&self.cwd, args.session)
1834 .await
1835 .map_err(error_data)?;
1836 let response = send_request(
1837 &resolved.endpoint,
1838 Request::ListLogRuns {
1839 service: args.service.clone(),
1840 },
1841 )
1842 .await
1843 .map_err(error_data)?;
1844 let runs =
1845 service_result(&self.discovery, &args.service, convert::log_runs(response)).await?;
1846 Ok(Json(LogRunsResult {
1847 service: args.service,
1848 config_path: resolved.info.config_path,
1849 runs,
1850 }))
1851 }
1852
1853 #[tool(
1854 description = "Return the disk JSONL file path for a retained service run. Omit \
1855 run_generation to return the current retained run. This is intended as a fallback for \
1856 shell-based inspection when MCP log tools are unavailable."
1857 )]
1858 async fn get_log_file_path(
1859 &self,
1860 args: Parameters<LogFilePathArgs>,
1861 ) -> ToolResult<LogFilePathResult> {
1862 let Parameters(args) = args;
1863 let resolved = self
1864 .discovery
1865 .resolve(&self.cwd, args.session)
1866 .await
1867 .map_err(error_data)?;
1868 let response = send_request(
1869 &resolved.endpoint,
1870 Request::ListLogRuns {
1871 service: args.service.clone(),
1872 },
1873 )
1874 .await
1875 .map_err(error_data)?;
1876 let runs =
1877 service_result(&self.discovery, &args.service, convert::log_runs(response)).await?;
1878 let run = match args.run_generation {
1879 Some(run_generation) => runs
1880 .into_iter()
1881 .find(|run| run.run_generation == run_generation),
1882 None => runs.into_iter().find(|run| run.current),
1883 }
1884 .ok_or_else(|| {
1885 error_data(ToolError::Remote {
1886 code: ErrorCode::UnknownRun,
1887 message: format!(
1888 "service `{}` has no retained run `{}`",
1889 args.service,
1890 args.run_generation.map_or_else(
1891 || "current".to_string(),
1892 |generation| generation.to_string()
1893 )
1894 ),
1895 })
1896 })?;
1897 let path = run.path.clone().ok_or_else(|| {
1898 error_data(ToolError::InvalidState(format!(
1899 "service `{}` run `{}` is not disk-backed",
1900 args.service, run.run_generation
1901 )))
1902 })?;
1903 Ok(Json(LogFilePathResult {
1904 service: args.service,
1905 config_path: resolved.info.config_path,
1906 run_generation: run.run_generation,
1907 path,
1908 }))
1909 }
1910
1911 #[tool(
1912 description = "Return the current visible-log cursor for every service. Call this before \
1913 an action, then pass the returned `cursors` as `after` to follow_all_logs to see what the \
1914 action caused across services. Services with no entries return cursor 0."
1915 )]
1916 async fn log_cursors(&self, args: Parameters<SessionArgs>) -> ToolResult<LogCursorsResult> {
1917 let Parameters(args) = args;
1918 let resolved = self
1919 .discovery
1920 .resolve(&self.cwd, args.session)
1921 .await
1922 .map_err(error_data)?;
1923 let mut conn = SessionConn::connect(&resolved.endpoint)
1924 .await
1925 .map_err(error_data)?;
1926 let cursors = current_cursors(&mut conn).await.map_err(error_data)?;
1927 Ok(Json(LogCursorsResult {
1928 config_path: resolved.info.config_path,
1929 cursors,
1930 }))
1931 }
1932
1933 #[tool(
1934 description = "Restart a service. Returns the run generation *before* the restart; pass \
1935 it to wait_for_healthy as after_generation. When available, log_cursor is the pre-restart \
1936 log position; pass it to follow_logs as after_seq to read exactly the new run's output. \
1937 Cursor capture is best-effort and never prevents the restart. Reloads the latest micromux \
1938 config before spawning the replacement, so edited command flags, healthchecks, and log \
1939 retention take effect. Restarting a disabled service is rejected."
1940 )]
1941 async fn restart_service(&self, args: Parameters<ServiceArgs>) -> ToolResult<MutationResult> {
1942 let Parameters(args) = args;
1943 self.mutate(
1944 args.session,
1945 Request::Restart {
1946 service: args.service.clone(),
1947 },
1948 &args.service,
1949 )
1950 .await
1951 }
1952
1953 #[tool(
1954 description = "Convenience wrapper that captures log cursors, restarts one service, waits \
1955 for the replacement run, and returns its snapshot plus compact new logs, lifecycle events, \
1956 and failure diagnosis. The primitive tools remain the right choice for finer control. Do not use this \
1957 for hot-reload services, which never restart; use log_cursors followed by follow_all_logs \
1958 for those."
1959 )]
1960 async fn restart_service_and_wait(
1961 &self,
1962 args: Parameters<RestartAndWaitArgs>,
1963 ) -> ToolResult<RestartAndWaitResult> {
1964 let Parameters(args) = args;
1965 let resolved = self
1966 .discovery
1967 .resolve(&self.cwd, args.session)
1968 .await
1969 .map_err(error_data)?;
1970 let timeout = Duration::from_secs(
1971 args.timeout_secs
1972 .unwrap_or(DEFAULT_WAIT_TIMEOUT_SECS)
1973 .min(MAX_WAIT_TIMEOUT_SECS),
1974 );
1975 let log_limit = args
1976 .log_limit
1977 .unwrap_or(DEFAULT_RESTART_LOG_LIMIT)
1978 .clamp(1, MAX_RESTART_LOG_LIMIT);
1979 let mut conn = SessionConn::connect(&resolved.endpoint)
1980 .await
1981 .map_err(error_data)?;
1982
1983 let before = service_result(
1984 &self.discovery,
1985 &args.service,
1986 service_snapshot(&mut conn, &args.service).await,
1987 )
1988 .await?;
1989 if before.desired == Desired::Disabled {
1993 return Err(error_data(ToolError::InvalidState(format!(
1994 "service `{}` is disabled and cannot be restarted; use enable_service to start it",
1995 args.service
1996 ))));
1997 }
1998 let cursors = current_cursors(&mut conn).await.map_err(error_data)?;
1999 let response = conn
2000 .request(Request::Restart {
2001 service: args.service.clone(),
2002 })
2003 .await
2004 .map_err(error_data)?;
2005 let acks =
2006 service_result(&self.discovery, &args.service, convert::accepted(response)).await?;
2007 let previous_generation = acks
2008 .iter()
2009 .find(|ack| ack.service == args.service)
2010 .map(|ack| ack.observed_generation)
2011 .ok_or_else(|| {
2012 error_data(ToolError::Unexpected(format!(
2013 "restart acknowledgement omitted service `{}`",
2014 args.service
2015 )))
2016 })?;
2017
2018 let conclusion = service_result(
2019 &self.discovery,
2020 &args.service,
2021 wait_for_health(
2022 &resolved.endpoint,
2023 &mut conn,
2024 &args.service,
2025 Some(previous_generation),
2026 timeout,
2027 )
2028 .await,
2029 )
2030 .await?;
2031 let snapshot = conclusion.snapshot().clone();
2032 let cursor = cursors.get(&args.service).copied().unwrap_or(0);
2033 let (logs, logs_truncated) = service_result(
2034 &self.discovery,
2035 &args.service,
2036 compact_logs_since(&mut conn, &args.service, cursor, log_limit).await,
2037 )
2038 .await?;
2039 let diagnosis = if conclusion.needs_diagnosis() {
2040 Some(
2041 service_result(
2042 &self.discovery,
2043 &args.service,
2044 diagnose_service(
2045 &mut conn,
2046 &self.discovery,
2047 snapshot.clone(),
2048 DEFAULT_DIAGNOSE_TAIL,
2049 )
2050 .await,
2051 )
2052 .await?,
2053 )
2054 } else {
2055 None
2056 };
2057 let events = service_events_tail(&self.discovery, &mut conn, &args.service)
2058 .await?
2059 .into_iter()
2060 .filter(|event| event.run_generation >= previous_generation)
2061 .collect();
2062 let outcome = WaitResult::from_conclusion(args.service.clone(), timeout, &conclusion);
2063
2064 Ok(Json(RestartAndWaitResult {
2065 session_ref: SessionRef::from(&resolved.info),
2066 service: args.service,
2067 previous_generation,
2068 run_generation: snapshot.run_generation,
2069 outcome,
2070 snapshot,
2071 logs,
2072 logs_truncated,
2073 events,
2074 diagnosis,
2075 }))
2076 }
2077
2078 #[tool(
2079 description = "Restart all enabled services in a session, including live dynamic services \
2080 (disabled and retired services are skipped). Reloads the latest micromux config before \
2081 requesting restarts. This receipt has no per-service log cursor; use log_cursors before \
2082 restart_all when you need logs since the action."
2083 )]
2084 async fn restart_all(
2085 &self,
2086 args: Parameters<SessionArgs>,
2087 ) -> ToolResult<SessionMutationResult> {
2088 let Parameters(args) = args;
2089 let resolved = self
2090 .discovery
2091 .resolve(&self.cwd, args.session)
2092 .await
2093 .map_err(error_data)?;
2094 let response = send_request(&resolved.endpoint, Request::RestartAll)
2095 .await
2096 .map_err(error_data)?;
2097 let acks = convert::accepted(response).map_err(error_data)?;
2098 Ok(Json(SessionMutationResult {
2099 session_ref: SessionRef::from(&resolved.info),
2100 accepted: acks,
2101 }))
2102 }
2103
2104 #[tool(
2105 description = "Enable (and start) a service. Returns the run generation before enabling \
2106 plus the pre-enable log position in log_cursor when cursor capture succeeds (pass it to \
2107 follow_logs as after_seq). Cursor capture is best-effort and never prevents the enable. \
2108 Reloads the latest micromux config before spawning, so edited command flags, healthchecks, \
2109 and log retention take effect."
2110 )]
2111 async fn enable_service(&self, args: Parameters<ServiceArgs>) -> ToolResult<MutationResult> {
2112 let Parameters(args) = args;
2113 self.mutate(
2114 args.session,
2115 Request::Enable {
2116 service: args.service.clone(),
2117 },
2118 &args.service,
2119 )
2120 .await
2121 }
2122
2123 #[tool(description = "Disable a service (stop it and keep it stopped).")]
2124 async fn disable_service(&self, args: Parameters<ServiceArgs>) -> ToolResult<MutationResult> {
2125 let Parameters(args) = args;
2126 self.mutate(
2127 args.session,
2128 Request::Disable {
2129 service: args.service.clone(),
2130 },
2131 &args.service,
2132 )
2133 .await
2134 }
2135
2136 #[tool(
2137 description = "Create and start a runtime service in the target session. Requires \
2138 control.dynamic_services.enabled in that session's micromux.yaml. Dynamic services stop \
2139 with the session; leases are bounded unless policy explicitly permits expires_after=\"none\". \
2140 from_service clones any existing service (configured or dynamic) server-side, including \
2141 environment values that are never displayed. When replacing, pass from_service equal to \
2142 service to start from its current spec and override only provided fields. Put stable flags \
2143 in command: extra_args re-append on every self-referential replace (and for CMD-SHELL they \
2144 are shell positional parameters, not appended script text). Pass idempotency_key when \
2145 retrying. Then call wait_for_healthy with after_generation=observed_generation."
2146 )]
2147 async fn start_dynamic_service(
2148 &self,
2149 args: Parameters<DynamicServiceArgs>,
2150 ) -> ToolResult<DynamicMutationResult> {
2151 let Parameters(args) = args;
2152 let service = args.params.service.clone();
2153 let mutation = self
2154 .dynamic_mutation(
2155 args.session,
2156 &service,
2157 Request::StartDynamicService {
2158 params: args.params,
2159 },
2160 )
2161 .await?;
2162 Ok(Json(mutation.into_result()))
2163 }
2164
2165 #[tool(
2166 description = "Create a runtime service, wait for its existing or newly created run, and \
2167 return the mutation receipt, compact logs, lifecycle events, and failure diagnosis. This \
2168 preserves start_dynamic_service policy and idempotency semantics; an idempotent replay \
2169 waits on the original run. Use the primitive tools when finer control is needed."
2170 )]
2171 async fn start_dynamic_service_and_wait(
2172 &self,
2173 args: Parameters<StartDynamicAndWaitArgs>,
2174 ) -> ToolResult<StartDynamicAndWaitResult> {
2175 let Parameters(args) = args;
2176 let service = args.params.service.clone();
2177 let timeout = Duration::from_secs(
2178 args.timeout_secs
2179 .unwrap_or(DEFAULT_WAIT_TIMEOUT_SECS)
2180 .min(MAX_WAIT_TIMEOUT_SECS),
2181 );
2182 let log_limit = args
2183 .log_limit
2184 .unwrap_or(DEFAULT_RESTART_LOG_LIMIT)
2185 .clamp(1, MAX_RESTART_LOG_LIMIT);
2186 let mutation = self
2187 .dynamic_mutation(
2188 args.session,
2189 &service,
2190 Request::StartDynamicService {
2191 params: args.params,
2192 },
2193 )
2194 .await?;
2195 let mut conn = SessionConn::connect(&mutation.resolved.endpoint)
2196 .await
2197 .map_err(error_data)?;
2198 let conclusion = service_result(
2199 &self.discovery,
2200 &service,
2201 wait_for_health(
2202 &mutation.resolved.endpoint,
2203 &mut conn,
2204 &service,
2205 Some(mutation.receipt.observed_generation),
2206 timeout,
2207 )
2208 .await,
2209 )
2210 .await?;
2211 let snapshot = conclusion.snapshot().clone();
2212 let (logs, logs_truncated) = service_result(
2213 &self.discovery,
2214 &service,
2215 compact_logs_since(&mut conn, &service, 0, log_limit).await,
2216 )
2217 .await?;
2218 let diagnosis = if conclusion.needs_diagnosis() {
2219 Some(
2220 service_result(
2221 &self.discovery,
2222 &service,
2223 diagnose_service(
2224 &mut conn,
2225 &self.discovery,
2226 snapshot.clone(),
2227 DEFAULT_DIAGNOSE_TAIL,
2228 )
2229 .await,
2230 )
2231 .await?,
2232 )
2233 } else {
2234 None
2235 };
2236 let events = if conclusion.needs_diagnosis() {
2240 service_events_tail(&self.discovery, &mut conn, &service).await?
2241 } else {
2242 Vec::new()
2243 };
2244 let outcome = WaitResult::from_conclusion(service, timeout, &conclusion);
2245
2246 Ok(Json(StartDynamicAndWaitResult {
2247 session_ref: SessionRef::from(&mutation.resolved.info),
2248 receipt: mutation.receipt,
2249 outcome,
2250 snapshot,
2251 logs,
2252 logs_truncated,
2253 events,
2254 diagnosis,
2255 }))
2256 }
2257
2258 #[tool(
2259 description = "Replace or revive a runtime service using optimistic concurrency. Requires \
2260 control.dynamic_services.enabled in the target session's micromux.yaml. Dynamic services \
2261 stop with the session and receive a fresh bounded or explicitly unbounded lease after \
2262 replacement. from_service clones any existing service server-side, including environment \
2263 values that are never displayed. Pass from_service equal to service to start from its \
2264 current spec and override only provided fields. Put stable flags in command: extra_args \
2265 re-append on every self-referential replace. Pass idempotency_key when retrying, then \
2266 compose with wait_for_healthy(after_generation=observed_generation)."
2267 )]
2268 async fn replace_dynamic_service(
2269 &self,
2270 args: Parameters<ReplaceDynamicServiceArgs>,
2271 ) -> ToolResult<DynamicMutationResult> {
2272 let Parameters(args) = args;
2273 let service = args.params.service.clone();
2274 let request = Request::ReplaceDynamicService {
2275 service: service.clone(),
2276 expected_revision: args.expected_revision,
2277 params: args.params,
2278 };
2279 let mutation = self
2280 .dynamic_mutation(args.session, &service, request)
2281 .await?;
2282 Ok(Json(mutation.into_result()))
2283 }
2284
2285 #[tool(
2286 description = "Renew a live runtime service's lease without restarting it or changing its \
2287 revision. Requires control.dynamic_services.enabled in the target session's \
2288 micromux.yaml. Omit expires_after to apply the policy default; request 'none' for a \
2289 session-lifetime lease where policy permits it. A receipt replayed from an earlier \
2290 idempotent create may show a stale expiry after renewal; the service snapshot is the \
2291 expiry authority."
2292 )]
2293 async fn renew_dynamic_service(
2294 &self,
2295 args: Parameters<RenewDynamicServiceArgs>,
2296 ) -> ToolResult<DynamicMutationResult> {
2297 let Parameters(args) = args;
2298 let request = Request::RenewDynamicService {
2299 service: args.service.clone(),
2300 expected_revision: args.expected_revision,
2301 expires_after: args.expires_after,
2302 };
2303 let mutation = self
2304 .dynamic_mutation(args.session, &args.service, request)
2305 .await?;
2306 Ok(Json(mutation.into_result()))
2307 }
2308
2309 #[tool(
2310 description = "Retire a runtime service while preserving its bounded logs and snapshot for \
2311 post-mortem inspection. Requires control.dynamic_services.enabled in the target session's \
2312 micromux.yaml. Stop is idempotent; the service also stops with the session, and its lease \
2313 (unless the policy permitted expires_after=\"none\") would retire it on expiry anyway."
2314 )]
2315 async fn stop_dynamic_service(
2316 &self,
2317 args: Parameters<ServiceArgs>,
2318 ) -> ToolResult<DynamicMutationResult> {
2319 let Parameters(args) = args;
2320 let request = Request::StopDynamicService {
2321 service: args.service.clone(),
2322 };
2323 let mutation = self
2324 .dynamic_mutation(args.session, &args.service, request)
2325 .await?;
2326 Ok(Json(mutation.into_result()))
2327 }
2328
2329 #[tool(
2330 description = "Stop a whole micromux session: every service is stopped and the session \
2331 process exits (graceful, like Ctrl-C), freeing its ports. Select with `session` (see \
2332 list_sessions); omit for the current project. Use this before start_session for another \
2333 worktree that binds the same ports. Returns `stopped: true` once the process has exited."
2334 )]
2335 async fn stop_session(&self, args: Parameters<SessionArgs>) -> ToolResult<StopSessionResult> {
2336 let Parameters(args) = args;
2337 let resolved = self
2338 .discovery
2339 .resolve(&self.cwd, args.session)
2340 .await
2341 .map_err(error_data)?;
2342 #[cfg(unix)]
2343 let process_exit = ProcessExitWatch::new(resolved.info.pid);
2344 let response = send_request(&resolved.endpoint, Request::Shutdown)
2345 .await
2346 .map_err(error_data)?;
2347 convert::shutting_down(response).map_err(error_data)?;
2348 #[cfg(unix)]
2353 let stopped = process_exit.wait(STOP_CONFIRM_TIMEOUT).await;
2354 #[cfg(not(unix))]
2355 let stopped = true;
2356 let note = if stopped {
2357 None
2358 } else {
2359 Some(
2360 "shutdown was acknowledged but the process was still terminating after the confirm \
2361 window; its ports may take another moment to free",
2362 )
2363 };
2364 Ok(Json(StopSessionResult {
2365 stopped,
2366 session_ref: SessionRef::from(&resolved.info),
2367 note,
2368 }))
2369 }
2370
2371 #[tool(
2372 description = "Start a new headless micromux session for a project (brings its services \
2373 up). Spawns `micromux serve` detached for the project's config and returns once the session \
2374 is reachable, which takes longer while the session first waits for a previous session's \
2375 cleanups or for an outdated shared proxy to exit; a no-op if one is already running for \
2376 that config, and a session that is still starting is reported with reachable=false \
2377 instead of being started twice. `path` is a project directory or a config file — omit \
2378 for the MCP server's directory. If another worktree's session binds the same ports, stop \
2379 it first with stop_session."
2380 )]
2381 async fn start_session(&self, args: Parameters<StartArgs>) -> ToolResult<StartSessionResult> {
2382 let Parameters(args) = args;
2383 let target = args
2384 .path
2385 .as_deref()
2386 .map_or_else(|| self.cwd.clone(), PathBuf::from);
2387 self.start_for_target(target).await.map(Json)
2388 }
2389
2390 #[tool(
2391 description = "Read log entries after a cursor for incremental following. Returns the new \
2392 entries and a next_seq; pass next_seq as after_seq on the next call. If retention already \
2393 evicted unread entries, the response includes a gap object. Pass run_generation for a full \
2394 disk-backed retained run page; omit it for the bounded visible stream. For the visible \
2395 stream, omitting after_seq returns the latest tail; pass 0 to start at the first retained \
2396 visible entry. Supports the same raw/grep/grep_context/min_level/since/trace_id/format filters as get_logs; next_seq still \
2397 advances past filtered-out entries."
2398 )]
2399 async fn follow_logs(&self, args: Parameters<FollowArgs>) -> ToolResult<FollowLogsResult> {
2400 let Parameters(args) = args;
2401 let filters = LogFilters::from_args(&args.filters)?;
2402 let resolved = self
2403 .discovery
2404 .resolve(&self.cwd, args.session)
2405 .await
2406 .map_err(error_data)?;
2407 let response = send_request(
2408 &resolved.endpoint,
2409 Request::FollowLogs {
2410 service: args.service.clone(),
2411 run_generation: args.run_generation,
2412 after: args.after_seq,
2413 },
2414 )
2415 .await
2416 .map_err(error_data)?;
2417 let logs = service_result(&self.discovery, &args.service, convert::logs(response)).await?;
2418 let next_seq = next_follow_cursor(&logs.lines, args.after_seq);
2421 let gap = follow_gap(
2422 &logs.lines,
2423 logs.first_retained_seq,
2424 args.after_seq,
2425 args.run_generation,
2426 );
2427 let entries = logproc::shape(&logs.lines, &filters.shape(args.filters.raw, None));
2428 Ok(Json(FollowLogsResult {
2429 service: args.service,
2430 run_generation: args.run_generation,
2431 entries,
2432 next_seq,
2433 gap,
2434 truncated: logs.truncated,
2435 }))
2436 }
2437
2438 #[tool(
2439 description = "Follow current visible logs across all services with a per-service cursor \
2440 map. Pass `after` from log_cursors or from the previous follow_all_logs `next` value. \
2441 Returns entries merged by parsed service timestamp when present, otherwise micromux \
2442 ingestion timestamp, while preserving each service's cursor order. This is additive to \
2443 follow_logs; retained run paging stays single-service because run_generation and seq are \
2444 service-scoped. Supports the same raw/grep/grep_context/min_level/since/trace_id/format filters as \
2445 get_logs."
2446 )]
2447 async fn follow_all_logs(
2448 &self,
2449 args: Parameters<FollowAllArgs>,
2450 ) -> ToolResult<FollowAllLogsResult> {
2451 let Parameters(args) = args;
2452 let filters = LogFilters::from_args(&args.filters)?;
2453 let raw = args.filters.raw;
2454 let limit = args
2455 .limit
2456 .unwrap_or(DEFAULT_LOG_TAIL)
2457 .clamp(1, MAX_LOG_TAIL);
2458 let resolved = self
2459 .discovery
2460 .resolve(&self.cwd, args.session)
2461 .await
2462 .map_err(error_data)?;
2463 let mut conn = SessionConn::connect(&resolved.endpoint)
2464 .await
2465 .map_err(error_data)?;
2466 let merged = follow_all_current_logs(&mut conn, &args.after, raw, &filters, limit)
2467 .await
2468 .map_err(error_data)?;
2469 Ok(Json(FollowAllLogsResult {
2470 config_path: resolved.info.config_path,
2471 entries: merged.entries,
2472 next: merged.next,
2473 gaps: merged.gaps,
2474 truncated: merged.truncated,
2475 }))
2476 }
2477
2478 #[tool(
2479 description = "Wait until a matching log entry appears, then return the matching entries \
2480 and updated cursors. By default this starts at the current end of the log stream, making it \
2481 useful for 'perform an action, then wait for the backend log evidence'. Pass service=\"*\" \
2482 with `after` from log_cursors/follow_all_logs to wait across all services. Supports the \
2483 same raw/grep/grep_context/min_level/since/trace_id/format filters as get_logs."
2484 )]
2485 async fn wait_for_log(&self, args: Parameters<WaitLogArgs>) -> ToolResult<WaitForLogResult> {
2486 let Parameters(args) = args;
2487 let filters = LogFilters::from_args(&args.filters)?;
2488 let raw = args.filters.raw;
2489 let limit = args.limit.unwrap_or(20).clamp(1, MAX_LOG_TAIL);
2490 let timeout = Duration::from_secs(
2491 args.timeout_secs
2492 .unwrap_or(DEFAULT_WAIT_TIMEOUT_SECS)
2493 .min(MAX_WAIT_TIMEOUT_SECS),
2494 );
2495 let resolved = self
2496 .discovery
2497 .resolve(&self.cwd, args.session)
2498 .await
2499 .map_err(error_data)?;
2500 let mut conn = SessionConn::connect(&resolved.endpoint)
2501 .await
2502 .map_err(error_data)?;
2503 let deadline = tokio::time::Instant::now() + timeout;
2504
2505 if args.service == "*" {
2506 let mut cursors = if args.after.is_empty() {
2507 current_cursors(&mut conn).await.map_err(error_data)?
2508 } else {
2509 args.after
2510 };
2511 loop {
2512 let merged = follow_all_current_logs(&mut conn, &cursors, raw, &filters, limit)
2513 .await
2514 .map_err(error_data)?;
2515 if !merged.entries.is_empty() {
2516 return Ok(Json(WaitForLogResult {
2517 status: WaitForLogStatus::Matched,
2518 service: "*".to_string(),
2519 config_path: resolved.info.config_path,
2520 entries: merged.entries,
2521 next_seq: None,
2522 next: merged.next,
2523 truncated: merged.truncated,
2524 waited_secs: None,
2525 hint: None,
2526 }));
2527 }
2528 cursors = merged.next;
2529 if tokio::time::Instant::now() >= deadline {
2530 return Ok(Json(WaitForLogResult {
2531 status: WaitForLogStatus::Timeout,
2532 service: "*".to_string(),
2533 config_path: resolved.info.config_path,
2534 entries: Vec::new(),
2535 next_seq: None,
2536 next: cursors,
2537 truncated: merged.truncated,
2538 waited_secs: Some(timeout.as_secs()),
2539 hint: Some("no matching log entry arrived before timeout_secs"),
2540 }));
2541 }
2542 tokio::time::sleep(WAIT_LOG_POLL).await;
2543 }
2544 }
2545
2546 let mut cursor = match args.after_seq {
2547 Some(cursor) => cursor,
2548 None => current_service_cursor(&mut conn, &args.service)
2549 .await
2550 .map_err(error_data)?,
2551 };
2552 loop {
2553 let response = conn
2554 .request(Request::FollowLogs {
2555 service: args.service.clone(),
2556 run_generation: None,
2557 after: Some(cursor),
2558 })
2559 .await
2560 .map_err(error_data)?;
2561 let logs =
2562 service_result(&self.discovery, &args.service, convert::logs(response)).await?;
2563 let raw_next_seq = next_follow_cursor(&logs.lines, Some(cursor)).unwrap_or(cursor);
2564 let mut entries = logproc::shape(&logs.lines, &filters.shape(raw, None));
2565 if !entries.is_empty() {
2566 let (next_seq, truncated) =
2567 truncate_wait_matches(&mut entries, raw_next_seq, logs.truncated, limit);
2568 return Ok(Json(WaitForLogResult {
2569 status: WaitForLogStatus::Matched,
2570 service: args.service,
2571 config_path: resolved.info.config_path,
2572 entries,
2573 next_seq: Some(next_seq),
2574 next: BTreeMap::new(),
2575 truncated,
2576 waited_secs: None,
2577 hint: None,
2578 }));
2579 }
2580 cursor = raw_next_seq;
2581 if tokio::time::Instant::now() >= deadline {
2582 return Ok(Json(WaitForLogResult {
2583 status: WaitForLogStatus::Timeout,
2584 service: args.service,
2585 config_path: resolved.info.config_path,
2586 entries: Vec::new(),
2587 next_seq: Some(cursor),
2588 next: BTreeMap::new(),
2589 truncated: logs.truncated,
2590 waited_secs: Some(timeout.as_secs()),
2591 hint: Some("no matching log entry arrived before timeout_secs"),
2592 }));
2593 }
2594 tokio::time::sleep(WAIT_LOG_POLL).await;
2595 }
2596 }
2597
2598 #[tool(
2599 description = "Show a service's runtime snapshot and latest healthcheck attempt for its \
2600 current live run (command, result, and bounded output), plus the session config path."
2601 )]
2602 async fn get_health(&self, args: Parameters<ServiceArgs>) -> ToolResult<HealthResult> {
2603 let Parameters(args) = args;
2604 let resolved = self
2605 .discovery
2606 .resolve(&self.cwd, args.session)
2607 .await
2608 .map_err(error_data)?;
2609 let mut conn = SessionConn::connect(&resolved.endpoint)
2610 .await
2611 .map_err(error_data)?;
2612 let snapshot = service_result(
2613 &self.discovery,
2614 &args.service,
2615 service_snapshot(&mut conn, &args.service).await,
2616 )
2617 .await?;
2618 let latest_healthcheck = latest_health_for_snapshot(&mut conn, &snapshot)
2619 .await
2620 .map(bounded_attempt);
2621 Ok(Json(HealthResult {
2622 config_path: resolved.info.config_path,
2623 service: args.service,
2624 snapshot,
2625 latest_healthcheck,
2626 }))
2627 }
2628
2629 #[tool(
2630 description = "Show a service's retained healthcheck attempt history for its current or \
2631 latest run, oldest first, with per-attempt bounded output. Use when the latest attempt \
2632 from get_health is not enough — e.g. to see whether a flapping probe fails the same way \
2633 every time."
2634 )]
2635 async fn get_health_history(
2636 &self,
2637 args: Parameters<ServiceArgs>,
2638 ) -> ToolResult<HealthHistoryResult> {
2639 let Parameters(args) = args;
2640 let resolved = self
2641 .discovery
2642 .resolve(&self.cwd, args.session)
2643 .await
2644 .map_err(error_data)?;
2645 let mut conn = SessionConn::connect(&resolved.endpoint)
2646 .await
2647 .map_err(error_data)?;
2648 let snapshot = service_result(
2651 &self.discovery,
2652 &args.service,
2653 service_snapshot(&mut conn, &args.service).await,
2654 )
2655 .await?;
2656 let attempts = service_result(
2657 &self.discovery,
2658 &args.service,
2659 health_history(&mut conn, &args.service).await,
2660 )
2661 .await?
2662 .into_iter()
2663 .map(bounded_attempt)
2664 .collect();
2665 Ok(Json(HealthHistoryResult {
2666 config_path: resolved.info.config_path,
2667 service: args.service,
2668 snapshot,
2669 attempts,
2670 }))
2671 }
2672
2673 #[tool(
2674 description = "Return retained scheduler lifecycle events. Use after_seq for one service, \
2675 or pass service=\"*\" with the previous per-service `next` map as `after` to merge every \
2676 service's timeline. Events include dependency gating, spawn/exit, health transitions, \
2677 restart backoff, config reloads, and dynamic-service lifecycle changes."
2678 )]
2679 async fn get_service_events(
2680 &self,
2681 args: Parameters<ServiceEventsArgs>,
2682 ) -> ToolResult<ServiceEventsResult> {
2683 let Parameters(args) = args;
2684 let resolved = self
2685 .discovery
2686 .resolve(&self.cwd, args.session)
2687 .await
2688 .map_err(error_data)?;
2689 if args.service == "*" {
2690 if args.after_seq.is_some() {
2691 return Err(ErrorData::invalid_params(
2692 "after_seq is service-scoped; use the per-service after map with service=\"*\"",
2693 None,
2694 ));
2695 }
2696 let limit = args
2697 .tail
2698 .unwrap_or(DEFAULT_EVENT_TAIL)
2699 .clamp(1, MAX_EVENT_TAIL);
2700 let tail_mode = args.after.is_none();
2701 let mut conn = SessionConn::connect(&resolved.endpoint)
2702 .await
2703 .map_err(error_data)?;
2704 let response = conn
2705 .request(Request::ListServices)
2706 .await
2707 .map_err(error_data)?;
2708 let services = convert::services(response).map_err(error_data)?;
2709 let mut pages = Vec::with_capacity(services.len());
2710 for service in services {
2711 let after_seq = args
2712 .after
2713 .as_ref()
2714 .map(|cursors| cursors.get(&service.id).copied().unwrap_or(0));
2715 let response = conn
2716 .request(Request::GetEvents {
2717 service: service.id.clone(),
2718 after: after_seq,
2719 tail: Some(limit),
2720 })
2721 .await
2722 .map_err(error_data)?;
2723 let (events, truncated) = match convert::events(response) {
2726 Ok(page) => page,
2727 Err(ToolError::Remote {
2728 code: ErrorCode::UnknownService,
2729 ..
2730 }) => continue,
2731 Err(err) => return Err(error_data(err)),
2732 };
2733 pages.push(ServiceEventPage {
2734 service: service.id,
2735 after_seq,
2736 events,
2737 truncated,
2738 });
2739 }
2740 let merged = merge_service_events(pages, limit, tail_mode);
2741 return Ok(Json(ServiceEventsResult::Session(
2742 SessionServiceEventsResult {
2743 session_ref: SessionRef::from(&resolved.info),
2744 service: args.service,
2745 events: merged.events,
2746 next: merged.next,
2747 truncated: merged.truncated,
2748 },
2749 )));
2750 }
2751 if args.after.is_some() {
2752 return Err(ErrorData::invalid_params(
2753 "after is only valid with service=\"*\"; use after_seq for one service",
2754 None,
2755 ));
2756 }
2757 let response = send_request(
2758 &resolved.endpoint,
2759 Request::GetEvents {
2760 service: args.service.clone(),
2761 after: args.after_seq,
2762 tail: args.tail,
2763 },
2764 )
2765 .await
2766 .map_err(error_data)?;
2767 let (events, truncated) =
2768 service_result(&self.discovery, &args.service, convert::events(response)).await?;
2769 let next_seq = events.last().map(|event| event.seq).or(args.after_seq);
2770 Ok(Json(ServiceEventsResult::Single(
2771 SingleServiceEventsResult {
2772 session_ref: SessionRef::from(&resolved.info),
2773 service: args.service,
2774 events,
2775 next_seq,
2776 truncated,
2777 },
2778 )))
2779 }
2780
2781 #[tool(
2782 description = "Summarize services that need attention in one call. Returns exited, \
2783 starting/pending/stopping, or unhealthy services with their full state snapshot, current \
2784 live-run healthcheck output when applicable, recent lifecycle events, factual \
2785 supervisor-state signals, and a compact tail of likely-cause log lines."
2786 )]
2787 async fn diagnose(&self, args: Parameters<DiagnoseArgs>) -> ToolResult<DiagnoseResult> {
2788 let Parameters(args) = args;
2789 let resolved = self
2790 .discovery
2791 .resolve(&self.cwd, args.session)
2792 .await
2793 .map_err(error_data)?;
2794 let tail = args
2795 .tail_per_service
2796 .unwrap_or(DEFAULT_DIAGNOSE_TAIL)
2797 .clamp(1, MAX_DIAGNOSE_TAIL);
2798 let mut conn = SessionConn::connect(&resolved.endpoint)
2799 .await
2800 .map_err(error_data)?;
2801 let response = conn
2802 .request(Request::ListServices)
2803 .await
2804 .map_err(error_data)?;
2805 let services = convert::services(response).map_err(error_data)?;
2806 let mut diagnoses = Vec::new();
2807 for snapshot in services.into_iter().filter(service_needs_diagnosis) {
2808 diagnoses.push(
2809 diagnose_service(&mut conn, &self.discovery, snapshot, tail)
2810 .await
2811 .map_err(error_data)?,
2812 );
2813 }
2814 let session_selector = session_selector(&resolved.info);
2815 let disk_log_reads = resolved
2816 .info
2817 .capabilities
2818 .as_ref()
2819 .and_then(|capabilities| capabilities.disk_log_reads);
2820 Ok(Json(DiagnoseResult {
2821 config_path: resolved.info.config_path,
2822 session: resolved.info.name,
2823 session_selector,
2824 disk_log_reads,
2825 services: diagnoses,
2826 }))
2827 }
2828
2829 #[tool(
2830 description = "Wait until a service becomes healthy (or its run exits, or a timeout). \
2831 Pass after_generation (from restart_service/enable_service) to wait for the new run. A \
2832 disabled service fails immediately, and so does one blocked behind a dependency that \
2833 exited for good or is disabled or retired; the error names that dependency, its state, \
2834 and its exit code."
2835 )]
2836 async fn wait_for_healthy(&self, args: Parameters<WaitArgs>) -> ToolResult<WaitResult> {
2837 let Parameters(args) = args;
2838 let resolved = self
2839 .discovery
2840 .resolve(&self.cwd, args.session)
2841 .await
2842 .map_err(error_data)?;
2843 let timeout = Duration::from_secs(
2844 args.timeout_secs
2845 .unwrap_or(DEFAULT_WAIT_TIMEOUT_SECS)
2846 .min(MAX_WAIT_TIMEOUT_SECS),
2847 );
2848 let mut conn = SessionConn::connect(&resolved.endpoint)
2849 .await
2850 .map_err(error_data)?;
2851 let conclusion = match wait_for_health(
2852 &resolved.endpoint,
2853 &mut conn,
2854 &args.service,
2855 args.after_generation,
2856 timeout,
2857 )
2858 .await
2859 {
2860 Ok(conclusion) => conclusion,
2861 Err(err) => {
2862 return Err(error_data(
2863 enrich_unknown_service(&self.discovery, &args.service, err).await,
2864 ));
2865 }
2866 };
2867 if let WaitConclusion::DependencyFailed { failure, .. } = conclusion {
2868 return Err(error_data(dependency_failed_error(&args.service, failure)));
2869 }
2870 Ok(Json(WaitResult::from_conclusion(
2871 args.service,
2872 timeout,
2873 &conclusion,
2874 )))
2875 }
2876
2877 #[tool(
2878 description = "Wait for a service run to exit and return its exit code plus compact logs \
2879 produced after this call began. Intended for one-shot jobs; use wait_for_healthy for \
2880 servers. Pass after_generation to require a newer run. A disabled or retired service with \
2881 no qualifying run in flight, or one blocked behind a dependency that can no longer meet its \
2882 condition, fails immediately."
2883 )]
2884 async fn wait_for_exit(
2885 &self,
2886 args: Parameters<WaitForExitArgs>,
2887 ) -> ToolResult<WaitForExitResult> {
2888 let Parameters(args) = args;
2889 let resolved = self
2890 .discovery
2891 .resolve(&self.cwd, args.session)
2892 .await
2893 .map_err(error_data)?;
2894 let timeout = Duration::from_secs(
2895 args.timeout_secs
2896 .unwrap_or(DEFAULT_WAIT_TIMEOUT_SECS)
2897 .min(MAX_WAIT_TIMEOUT_SECS),
2898 );
2899 let log_limit = args
2900 .log_limit
2901 .unwrap_or(DEFAULT_RESTART_LOG_LIMIT)
2902 .clamp(1, MAX_RESTART_LOG_LIMIT);
2903 let mut conn = SessionConn::connect(&resolved.endpoint)
2904 .await
2905 .map_err(error_data)?;
2906 let cursor = service_result(
2907 &self.discovery,
2908 &args.service,
2909 current_service_cursor(&mut conn, &args.service).await,
2910 )
2911 .await?;
2912 let started = tokio::time::Instant::now();
2913 let waited = service_result(
2914 &self.discovery,
2915 &args.service,
2916 wait_for_snapshot(
2917 &resolved.endpoint,
2918 &mut conn,
2919 &args.service,
2920 timeout,
2921 |snapshot| wait::evaluate(snapshot, WaitFor::Exit, args.after_generation),
2922 )
2923 .await,
2924 )
2925 .await?;
2926 let (status, exit_code, snapshot) = match waited {
2927 SnapshotWait::Matched {
2928 snapshot,
2929 verdict: WaitVerdict::Exited(exit_code),
2930 } => (WaitForExitStatus::Exited, exit_code, snapshot),
2931 SnapshotWait::Matched {
2932 snapshot,
2933 verdict: WaitVerdict::Unavailable,
2934 } => {
2935 return Err(error_data(unavailable_error(
2936 &args.service,
2937 &snapshot,
2938 || {
2939 format!(
2940 "service `{}` is disabled with no qualifying run in flight",
2941 args.service
2942 )
2943 },
2944 )));
2945 }
2946 SnapshotWait::Matched {
2947 verdict: WaitVerdict::DependencyFailed(failure),
2948 ..
2949 } => {
2950 return Err(error_data(dependency_failed_error(&args.service, failure)));
2951 }
2952 SnapshotWait::Matched {
2953 snapshot,
2954 verdict: WaitVerdict::Idle,
2955 } => {
2956 return Err(error_data(idle_error(&args.service, &snapshot)));
2957 }
2958 SnapshotWait::Matched {
2959 verdict: WaitVerdict::Healthy | WaitVerdict::Completed,
2960 ..
2961 } => {
2962 return Err(error_data(ToolError::Unexpected(
2963 "an exit wait resolved without an exit".to_string(),
2964 )));
2965 }
2966 SnapshotWait::Timeout(snapshot) => (WaitForExitStatus::Timeout, None, snapshot),
2967 };
2968 let (logs, logs_truncated) = service_result(
2969 &self.discovery,
2970 &args.service,
2971 compact_logs_since(&mut conn, &args.service, cursor, log_limit).await,
2972 )
2973 .await?;
2974
2975 Ok(Json(WaitForExitResult {
2976 session_ref: SessionRef::from(&resolved.info),
2977 service: args.service,
2978 status,
2979 exit_code,
2980 run_generation: snapshot.run_generation,
2981 snapshot,
2982 logs_truncated,
2983 logs,
2984 waited_secs: started.elapsed().as_secs(),
2985 }))
2986 }
2987
2988 #[tool(
2989 description = "Ensure a service is ready by composing session startup, explicit enabling, \
2990 and the generation-aware health wait. Every action taken is reported. An already-healthy \
2991 service returns immediately with no actions; an exit or timeout includes bounded failure \
2992 diagnosis. Starting a missing session requires the operator to enable session spawning. \
2993 Retired dynamic services must be revived with replace_dynamic_service. A job is ready once \
2994 it completed; a manual job that has not run is run."
2995 )]
2996 async fn ensure_service_ready(
2997 &self,
2998 args: Parameters<EnsureReadyArgs>,
2999 ) -> ToolResult<EnsureServiceReadyResult> {
3000 let Parameters(args) = args;
3001 let timeout = Duration::from_secs(
3002 args.timeout_secs
3003 .unwrap_or(DEFAULT_WAIT_TIMEOUT_SECS)
3004 .min(MAX_WAIT_TIMEOUT_SECS),
3005 );
3006 let log_limit = args
3007 .log_limit
3008 .unwrap_or(DEFAULT_DIAGNOSE_TAIL)
3009 .clamp(1, MAX_DIAGNOSE_TAIL);
3010 let mut actions = Vec::new();
3011 let explicit_selector = args.session.is_some();
3015 let resolved = match self.discovery.resolve(&self.cwd, args.session).await {
3016 Ok(resolved) => resolved,
3017 Err(ToolError::NoSession(diagnostics)) if explicit_selector => {
3018 return Err(error_data(ToolError::NoSession(diagnostics)));
3019 }
3020 Err(ToolError::NoSession(_)) => {
3021 let target = args
3022 .path
3023 .as_deref()
3024 .map_or_else(|| self.cwd.clone(), PathBuf::from);
3025 let report = self.start_for_target(target).await?;
3026 if report.reachable == Some(false)
3028 && let Some(reason) = &report.reason
3029 {
3030 return Err(ErrorData::internal_error(reason.clone(), None));
3031 }
3032 let id = report.id.clone().ok_or_else(|| {
3033 ErrorData::internal_error(
3034 "start_session did not identify the reachable session",
3035 None,
3036 )
3037 })?;
3038 actions.push(EnsureAction {
3039 kind: EnsureActionKind::StartedSession,
3040 detail: if report.started {
3041 "started the micromux session".to_string()
3042 } else {
3043 "found the session started concurrently".to_string()
3044 },
3045 });
3046 self.discovery
3047 .resolve(&self.cwd, Some(format!("hash:{id}")))
3048 .await
3049 .map_err(error_data)?
3050 }
3051 Err(err) => return Err(error_data(err)),
3052 };
3053 let mut conn = SessionConn::connect(&resolved.endpoint)
3054 .await
3055 .map_err(error_data)?;
3056 let mut snapshot = match service_snapshot(&mut conn, &args.service).await {
3057 Ok(snapshot) => snapshot,
3058 Err(err) => {
3059 return Err(error_data(
3060 enrich_unknown_service(&self.discovery, &args.service, err).await,
3061 ));
3062 }
3063 };
3064 let ready = match wait::evaluate(&snapshot, WaitFor::Healthy, None) {
3065 Some(WaitVerdict::Healthy) => Some(WaitConclusion::Healthy(snapshot.clone())),
3066 Some(WaitVerdict::Completed) => Some(WaitConclusion::Completed(snapshot.clone())),
3067 _ => None,
3068 };
3069 if let Some(ready) = ready {
3070 return Ok(Json(EnsureServiceReadyResult {
3071 session_ref: SessionRef::from(&resolved.info),
3072 service: args.service.clone(),
3073 actions,
3074 outcome: WaitResult::from_conclusion(args.service, Duration::ZERO, &ready),
3075 snapshot,
3076 diagnosis: None,
3077 }));
3078 }
3079 if let Some(reason) = snapshot.retired {
3080 return Err(error_data(ToolError::InvalidState(
3081 retired_service_message(&args.service, reason),
3082 )));
3083 }
3084 let job = snapshot.kind == micromux::ServiceKind::Job;
3085 let after_generation = if snapshot.desired == Desired::Disabled {
3086 let response = conn
3087 .request(Request::Enable {
3088 service: args.service.clone(),
3089 })
3090 .await
3091 .map_err(error_data)?;
3092 let acks = convert::accepted(response).map_err(error_data)?;
3093 let generation = acks
3094 .iter()
3095 .find(|ack| ack.service == args.service)
3096 .map(|ack| ack.observed_generation)
3097 .ok_or_else(|| {
3098 ErrorData::internal_error(
3099 format!("enable acknowledgement omitted service `{}`", args.service),
3100 None,
3101 )
3102 })?;
3103 actions.push(EnsureAction {
3104 kind: EnsureActionKind::EnabledService,
3105 detail: format!("enabled service from generation {generation}"),
3106 });
3107 if job {
3108 snapshot = service_snapshot(&mut conn, &args.service)
3111 .await
3112 .map_err(error_data)?;
3113 None
3114 } else {
3115 Some(generation)
3116 }
3117 } else {
3118 None
3119 };
3120 let after_generation = if snapshot.manual && snapshot.execution == Execution::Pending {
3121 let response = conn
3123 .request(Request::Restart {
3124 service: args.service.clone(),
3125 })
3126 .await
3127 .map_err(error_data)?;
3128 let generation = convert::accepted(response)
3129 .map_err(error_data)?
3130 .iter()
3131 .find(|ack| ack.service == args.service)
3132 .map(|ack| ack.observed_generation)
3133 .ok_or_else(|| {
3134 ErrorData::internal_error(
3135 format!("restart acknowledgement omitted service `{}`", args.service),
3136 None,
3137 )
3138 })?;
3139 actions.push(EnsureAction {
3140 kind: EnsureActionKind::RanJob,
3141 detail: format!("ran the manual job from generation {generation}"),
3142 });
3143 Some(generation)
3144 } else {
3145 after_generation
3146 };
3147 let conclusion = match wait_for_health(
3148 &resolved.endpoint,
3149 &mut conn,
3150 &args.service,
3151 after_generation,
3152 timeout,
3153 )
3154 .await
3155 {
3156 Ok(conclusion) => conclusion,
3157 Err(err) => {
3158 return Err(error_data(
3159 enrich_unknown_service(&self.discovery, &args.service, err).await,
3160 ));
3161 }
3162 };
3163 snapshot = conclusion.snapshot().clone();
3164 let diagnosis = if conclusion.needs_diagnosis() {
3165 Some(
3166 service_result(
3167 &self.discovery,
3168 &args.service,
3169 diagnose_service(&mut conn, &self.discovery, snapshot.clone(), log_limit).await,
3170 )
3171 .await?,
3172 )
3173 } else {
3174 None
3175 };
3176 actions.push(EnsureAction {
3177 kind: EnsureActionKind::Waited,
3178 detail: format!("waited for service readiness up to {}s", timeout.as_secs()),
3179 });
3180 Ok(Json(EnsureServiceReadyResult {
3181 session_ref: SessionRef::from(&resolved.info),
3182 service: args.service.clone(),
3183 actions,
3184 outcome: WaitResult::from_conclusion(args.service, timeout, &conclusion),
3185 snapshot,
3186 diagnosis,
3187 }))
3188 }
3189}
3190
3191impl Default for McpServer {
3192 fn default() -> Self {
3193 Self::new()
3194 }
3195}
3196
3197#[tool_handler(router = self.tool_router)]
3198impl ServerHandler for McpServer {
3199 fn list_tools(
3202 &self,
3203 _request: Option<PaginatedRequestParams>,
3204 context: RequestContext<RoleServer>,
3205 ) -> impl Future<Output = Result<ListToolsResult, ErrorData>> + MaybeSendFuture + '_ {
3206 let result = ListToolsResult::with_all_items(self.tool_router.list_all());
3207 let supports_cache_hints = context
3210 .protocol_version()
3211 .is_some_and(|version| version >= ProtocolVersion::V_2026_07_28);
3212 let result = if supports_cache_hints {
3213 result.with_ttl_ms(0).with_cache_scope(CacheScope::Public)
3214 } else {
3215 result
3216 };
3217 std::future::ready(Ok(result))
3218 }
3219
3220 fn get_info(&self) -> ServerConfig {
3221 let mut info = ServerConfig::new(ServerCapabilities::builder().enable_tools().build());
3222 info.server_info = Implementation::from_build_env();
3223 info.server_info.name = "micromux".to_string();
3224 info.server_info.version = env!("CARGO_PKG_VERSION").to_string();
3225 let mut instructions = INSTRUCTIONS.to_string();
3226 if !self.allow_session_start {
3227 instructions.push_str(
3228 " This server does not permit process spawning: start_session is disabled unless \
3229 the operator launches `micromux mcp --allow-session-start`.",
3230 );
3231 }
3232 info.instructions = Some(instructions);
3233 info
3234 }
3235}
3236
3237fn compile_grep(pattern: Option<&str>) -> Result<Option<Regex>, ErrorData> {
3239 pattern
3240 .map(|pattern| {
3241 if pattern.len() > GREP_PATTERN_MAX_BYTES {
3242 return Err(ErrorData::invalid_params(
3243 format!("grep regex exceeds the {GREP_PATTERN_MAX_BYTES}-byte input limit"),
3244 None,
3245 ));
3246 }
3247 RegexBuilder::new(pattern)
3248 .size_limit(GREP_REGEX_SIZE_LIMIT)
3249 .dfa_size_limit(GREP_REGEX_SIZE_LIMIT)
3250 .build()
3251 .map_err(|err| {
3252 ErrorData::invalid_params(format!("invalid grep regex: {err}"), None)
3253 })
3254 })
3255 .transpose()
3256}
3257
3258fn parse_min_level(level: Option<&str>) -> Result<Option<logproc::Level>, ErrorData> {
3260 level
3261 .map(|level| {
3262 logproc::Level::parse(level).ok_or_else(|| {
3263 ErrorData::invalid_params(
3264 format!("unknown level `{level}` (use trace|debug|info|warn|error|fatal)"),
3265 None,
3266 )
3267 })
3268 })
3269 .transpose()
3270}
3271
3272fn parse_since(since: Option<&str>, since_unix_ms: Option<u64>) -> Result<Option<u64>, ErrorData> {
3273 match (since, since_unix_ms) {
3274 (None, None) => Ok(None),
3275 (None, Some(timestamp)) => Ok(Some(timestamp)),
3276 (Some(_), Some(_)) => Err(ErrorData::invalid_params(
3277 "pass either since or since_unix_ms, not both",
3278 None,
3279 )),
3280 (Some(raw), None) => parse_since_text(raw).map(Some),
3281 }
3282}
3283
3284fn parse_since_text(raw: &str) -> Result<u64, ErrorData> {
3285 let raw = raw.trim();
3286 if raw.is_empty() {
3287 return Err(ErrorData::invalid_params("since must not be empty", None));
3288 }
3289 if let Some(duration) = parse_relative_duration(raw) {
3290 return Ok(unix_now_ms().saturating_sub(duration_to_millis(duration)));
3291 }
3292 if let Ok(timestamp) = chrono::DateTime::parse_from_rfc3339(raw)
3293 && let Ok(ms) = u64::try_from(timestamp.timestamp_millis())
3294 {
3295 return Ok(ms);
3296 }
3297 if let Ok(number) = raw.parse::<u64>() {
3298 return Ok(user_timestamp_to_unix_ms(number));
3299 }
3300 Err(ErrorData::invalid_params(
3301 "since must be RFC3339, Unix seconds/ms/us/ns, or a relative duration like 30s, 2m, 1h, 500ms",
3302 None,
3303 ))
3304}
3305
3306fn user_timestamp_to_unix_ms(value: u64) -> u64 {
3307 micromux::numeric_timestamp_to_unix_ms(value).unwrap_or_else(|| value.saturating_mul(1000))
3308}
3309
3310fn parse_relative_duration(raw: &str) -> Option<Duration> {
3311 const UNITS: &[(&str, u64)] = &[("ms", 1), ("s", 1_000), ("m", 60_000), ("h", 3_600_000)];
3312
3313 let raw = raw.trim();
3314 for (suffix, multiplier) in UNITS {
3315 let Some(number) = raw.strip_suffix(suffix) else {
3316 continue;
3317 };
3318 let value = number.trim().parse::<u64>().ok()?;
3319 return Some(Duration::from_millis(value.checked_mul(*multiplier)?));
3320 }
3321 None
3322}
3323
3324fn duration_to_millis(duration: Duration) -> u64 {
3325 u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
3326}
3327
3328fn unix_now_ms() -> u64 {
3329 let duration = SystemTime::now()
3330 .duration_since(UNIX_EPOCH)
3331 .unwrap_or_default();
3332 duration_to_millis(duration)
3333}
3334
3335fn error_data(err: ToolError) -> ErrorData {
3336 match err {
3337 ToolError::NoSession(details) => {
3338 let message = format!("no session: {}", details.summary);
3339 let data = serde_json::to_value(details).ok();
3340 ErrorData::invalid_params(message, data)
3341 }
3342 ToolError::Ambiguous(message) => {
3343 ErrorData::invalid_params(format!("ambiguous selector: {message}"), None)
3344 }
3345 ToolError::Busy(message) => {
3346 ErrorData::internal_error(format!("session busy: {message}"), None)
3347 }
3348 ToolError::InvalidState(message) => {
3349 ErrorData::invalid_params(format!("invalid state: {message}"), None)
3350 }
3351 ToolError::DependencyFailed { message, failure } => ErrorData::invalid_params(
3352 format!("dependency failed: {message}"),
3353 serde_json::to_value(failure).ok(),
3354 ),
3355 ToolError::ConfigReload(message) => {
3356 ErrorData::invalid_params(format!("config reload failed: {message}"), None)
3357 }
3358 ToolError::Unsupported => ErrorData::internal_error(
3359 "UnsupportedPlatform: the micromux control plane is not supported on this platform",
3360 None,
3361 ),
3362 ToolError::Remote { code, message } => {
3363 ErrorData::invalid_params(format!("{code:?}: {message}"), None)
3364 }
3365 ToolError::Control(err) => ErrorData::internal_error(err.to_string(), None),
3366 ToolError::Unexpected(message) => ErrorData::internal_error(message, None),
3367 }
3368}
3369
3370pub async fn serve_stdio(
3376 allow_session_start: bool,
3377) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
3378 let server = McpServer::with_session_start(allow_session_start);
3379 let service = server.serve(rmcp::transport::stdio()).await?;
3380 service.waiting().await?;
3381 Ok(())
3382}
3383
3384async fn await_spawned_session(
3394 spawned: tools::sessions::SpawnedServe,
3395 endpoints: &[ControlEndpoint],
3396 config_path: &Path,
3397) -> Result<StartSessionResult, ErrorData> {
3398 let mut child = spawned.child;
3399 let stderr_path = spawned.stderr_path;
3400 let spawned_at = tokio::time::Instant::now();
3401 let mut deadline = spawned_at + START_READY_TIMEOUT;
3402 let mut child_exit: Option<std::process::ExitStatus> = None;
3403 let mut previous_cleanup_waits = 0;
3404 let mut waits_for_outdated_proxy = false;
3405 let mut already_starting: Option<String> = None;
3406 loop {
3407 if child_exit.is_none()
3410 && let Ok(Some(status)) = child.try_wait()
3411 {
3412 child_exit = Some(status);
3413 already_starting = ReportedStart::read(&stderr_path).already_starting;
3414 deadline = if already_starting.is_some() {
3415 tokio::time::Instant::now() + START_READY_TIMEOUT
3416 } else {
3417 deadline.min(tokio::time::Instant::now() + CHILD_EXIT_GRACE)
3418 };
3419 }
3420 let child_pid = child_exit.is_none().then(|| child.id()).flatten();
3421 match reachable_session_for_start(endpoints, config_path, child_pid).await {
3422 Ok(Some((started, info))) => {
3423 if !started && child_exit.is_none() {
3427 let _ = child.kill().await;
3428 }
3429 remove_captured_stderr(&stderr_path);
3430 return Ok(start_session_report(&info, started));
3431 }
3432 Ok(None) => {}
3433 Err(err) => {
3434 if child_exit.is_none() {
3437 let _ = child.kill().await;
3438 }
3439 remove_captured_stderr(&stderr_path);
3440 return Err(error_data(err));
3441 }
3442 }
3443 if child_exit.is_none() {
3447 let reported = ReportedStart::read(&stderr_path);
3448 let now = tokio::time::Instant::now();
3449 if reported.previous_cleanup_waits.len() > previous_cleanup_waits
3452 && let Some(bound) = reported.previous_cleanup_waits.last()
3453 {
3454 previous_cleanup_waits = reported.previous_cleanup_waits.len();
3455 deadline = deadline.max(now + *bound + START_READY_TIMEOUT);
3456 }
3457 if !waits_for_outdated_proxy && reported.outdated_proxy_wait {
3458 waits_for_outdated_proxy = true;
3459 deadline = deadline.max(now + OUTDATED_PROXY_START_BUDGET);
3460 }
3461 }
3462 if tokio::time::Instant::now() >= deadline {
3463 if child_exit.is_none() {
3464 let _ = child.kill().await;
3466 }
3467 if let Some(error) = already_starting {
3468 remove_captured_stderr(&stderr_path);
3469 return still_starting(&error, config_path);
3470 }
3471 let base = match child_exit {
3472 Some(status) => format!(
3473 "`micromux serve` for {} exited ({status}) before becoming reachable",
3474 config_path.display(),
3475 ),
3476 None => format!(
3477 "`micromux serve` for {} did not become reachable within {}s and was stopped",
3478 config_path.display(),
3479 spawned_at.elapsed().as_secs(),
3480 ),
3481 };
3482 return Err(ErrorData::internal_error(
3483 start_failure_message(&base, &stderr_path),
3484 None,
3485 ));
3486 }
3487 tokio::time::sleep(Duration::from_millis(150)).await;
3488 }
3489}
3490
3491fn still_starting(error: &str, config_path: &Path) -> Result<StartSessionResult, ErrorData> {
3496 let pid = already_starting_pid(error);
3497 if !holder_may_run(pid) {
3498 return Err(ErrorData::internal_error(
3499 format!("{error}; that session exited before it became reachable"),
3500 None,
3501 ));
3502 }
3503 Ok(StartSessionResult {
3504 started: false,
3505 already_running: Some(true),
3506 reachable: Some(false),
3507 config_path: config_path.display().to_string(),
3508 session: None,
3509 id: None,
3510 pid,
3511 endpoint: None,
3512 reason: Some(format!(
3513 "{error}; it has not become reachable within {}s: it is still starting, so call \
3514 start_session again to check on it, or it runs without a control plane, such as a \
3515 TUI started with `--no-control`",
3516 START_READY_TIMEOUT.as_secs()
3517 )),
3518 urls: None,
3519 })
3520}
3521
3522#[cfg(test)]
3523mod tests {
3524 use super::{
3525 DynamicMutationResult, GREP_PATTERN_MAX_BYTES, McpServer, MutationResult,
3526 RestartAndWaitResult, SessionMutationResult, SessionRef, StartDynamicAndWaitResult,
3527 StopSessionResult, WaitForExitResult, WaitForExitStatus, WaitResult,
3528 best_effort_mutation_cursor, compile_grep, matching_service, parse_since_text,
3529 session_has_service, session_selector,
3530 };
3531 use crate::select::ToolError;
3532 use crate::tools::health::health_attempt_matches_snapshot;
3533 use crate::tools::logs::{
3534 MergedFollowPage, follow_all_after_seq, follow_gap, merge_follow_pages, next_follow_cursor,
3535 truncate_wait_matches,
3536 };
3537 use color_eyre::eyre;
3538 use micromux::{Execution, HealthAttempt, LogLine, ServiceCommandAck, ServiceSnapshot};
3539 use micromux_control::{PROTOCOL_VERSION, ServiceBrief, SessionInfo};
3540 use similar_asserts::assert_eq;
3541 use std::collections::BTreeMap;
3542 use std::time::Duration;
3543
3544 #[test]
3545 fn mutations_continue_without_the_optional_log_cursor() {
3546 assert_eq!(
3547 best_effort_mutation_cursor(
3548 "api",
3549 Err(ToolError::Busy("disk log reader unavailable".to_string()))
3550 ),
3551 None
3552 );
3553 assert_eq!(best_effort_mutation_cursor("api", Ok(42)), Some(42));
3554 }
3555
3556 #[cfg(unix)]
3557 use super::{
3558 DynamicServiceArgs, EnsureAction, EnsureActionKind, EnsureReadyArgs, LogFilterArgs,
3559 LogsArgs, ReconcileConfigArgs, RenewDynamicServiceArgs, ReplaceDynamicServiceArgs,
3560 RestartAndWaitArgs, ServiceArgs, ServiceEventsArgs, ServiceEventsResult, SessionArgs,
3561 SessionEnvArgs, SessionServiceEventsResult, StartDynamicAndWaitArgs, WaitArgs,
3562 WaitForExitArgs, WaitStatus, capture_mutation_cursor,
3563 };
3564
3565 #[cfg(unix)]
3566 use micromux::{DynamicServiceParams, HealthcheckSpec, Lease, PartialServiceSpec, SpecField};
3567
3568 #[cfg(unix)]
3569 use rmcp::handler::server::wrapper::{Json, Parameters};
3570
3571 #[cfg(unix)]
3572 use std::sync::Arc;
3573
3574 #[cfg(unix)]
3575 #[tokio::test]
3576 async fn mutation_cursor_capture_is_bounded_by_its_own_timeout() -> eyre::Result<()> {
3577 let dir = tempfile::Builder::new()
3578 .prefix("micromux-mcp-cursor-")
3579 .tempdir_in("/tmp")?;
3580 let endpoint =
3581 micromux_control::ControlEndpoint::Unix(dir.path().join("unresponsive.sock"));
3582 let micromux_control::ControlEndpoint::Unix(path) = &endpoint else {
3583 eyre::bail!("expected Unix control endpoint");
3584 };
3585 let listener = tokio::net::UnixListener::bind(path)?;
3586 let peer = tokio::spawn(async move {
3587 if let Ok((stream, _)) = listener.accept().await {
3589 let _stream = stream;
3590 std::future::pending::<()>().await;
3591 }
3592 });
3593 let started = tokio::time::Instant::now();
3594
3595 let cursor = capture_mutation_cursor(&endpoint, "api").await;
3596
3597 assert_eq!(cursor, None);
3598 assert!(
3599 started.elapsed() < Duration::from_secs(1),
3600 "optional cursor capture delayed the mutation path"
3601 );
3602 peer.abort();
3603 let _ = peer.await;
3604 Ok(())
3605 }
3606
3607 #[cfg(unix)]
3608 struct RunningMcpSession {
3609 runtime_dir: std::path::PathBuf,
3611 shutdown: micromux::CancellationToken,
3612 runner: Option<tokio::task::JoinHandle<Result<(), micromux::Error>>>,
3613 server: Option<tokio::task::JoinHandle<Result<(), micromux_control::ControlError>>>,
3614 }
3615
3616 #[test]
3617 fn grep_regex_compilation_has_an_explicit_memory_bound() {
3618 assert!(compile_grep(Some("error|warn")).is_ok());
3619
3620 let oversized_input = "a".repeat(GREP_PATTERN_MAX_BYTES + 1);
3621 assert!(compile_grep(Some(&oversized_input)).is_err());
3622
3623 let oversized = "a?".repeat(100_000);
3624 assert!(compile_grep(Some(&oversized)).is_err());
3625 }
3626
3627 #[cfg(unix)]
3628 impl RunningMcpSession {
3629 fn server(&self) -> McpServer {
3631 McpServer {
3632 discovery: crate::select::Discovery::in_runtime_dirs(vec![
3633 self.runtime_dir.clone(),
3634 ]),
3635 ..McpServer::new()
3636 }
3637 }
3638
3639 async fn finish(mut self) -> eyre::Result<()> {
3640 self.shutdown.cancel();
3641 if let Some(runner) = self.runner.take() {
3642 runner.await??;
3643 }
3644 if let Some(server) = self.server.take() {
3645 server.await??;
3646 }
3647 Ok(())
3648 }
3649 }
3650
3651 #[cfg(unix)]
3652 impl Drop for RunningMcpSession {
3653 fn drop(&mut self) {
3654 self.shutdown.cancel();
3655 }
3656 }
3657
3658 #[cfg(unix)]
3659 fn boot_dynamic_mcp_session(
3660 project_dir: &std::path::Path,
3661 ) -> eyre::Result<(RunningMcpSession, String)> {
3662 let yaml = r#"version: 1
3663control:
3664 dynamic_services:
3665 enabled: true
3666 allowed_working_roots: [.]
3667 max_services: 2
3668 max_lifetime: 1m
3669services:
3670 base:
3671 command: ["sh", "-c", "sleep 60"]
3672 disabled:
3673 command: ["sh", "-c", "sleep 60"]
3674 disabled: true
3675"#;
3676 boot_mcp_session_with_yaml(project_dir, "mcp-dynamic-test", yaml)
3677 }
3678
3679 #[cfg(unix)]
3680 fn boot_mcp_session_with_yaml(
3681 project_dir: &std::path::Path,
3682 name: &str,
3683 yaml: &str,
3684 ) -> eyre::Result<(RunningMcpSession, String)> {
3685 let config_path = project_dir.join("micromux.yaml");
3686 std::fs::write(&config_path, yaml)?;
3687 let config_path = micromux_control::CanonicalConfigPath::new(config_path)?;
3688 let mut diagnostics = Vec::new();
3689 let mut config = micromux::from_str(yaml, project_dir, 0usize, None, &mut diagnostics)
3690 .map_err(|err| eyre::eyre!("parse config: {err}"))?;
3691 config.config_path = Some(config_path.as_path().to_path_buf());
3692
3693 let registry = micromux::PortRegistry::at(project_dir.join("registry"));
3695 let mux = Arc::new(
3696 micromux::Micromux::with_session(
3697 &config,
3698 micromux::Session::establish(&config, ®istry)?,
3699 )?
3700 .with_cache_directory(project_dir.join("cache")),
3701 );
3702 let shutdown = micromux::CancellationToken::new();
3703 let (runner, handles) = mux.clone().start(shutdown.clone());
3704 let runner = tokio::spawn(runner);
3705
3706 let runtime_dir = project_dir.join("run");
3708 {
3709 use std::os::unix::fs::DirBuilderExt as _;
3710
3711 std::fs::DirBuilder::new()
3712 .recursive(true)
3713 .mode(0o700)
3714 .create(&runtime_dir)?;
3715 }
3716 let endpoint = micromux_control::endpoint_for(&runtime_dir, &config_path);
3717 let guard = micromux_control::bind(&endpoint)?
3718 .ok_or_else(|| eyre::eyre!("control endpoint is already owned"))?;
3719 let identity =
3720 micromux_control::SessionIdentity::new(name.to_string(), project_dir, &config_path);
3721 let selector = format!("hash:{}", identity.id);
3722 let server = Arc::new(micromux_control::ControlServer::new(
3723 handles.reader.clone(),
3724 handles.service_control(),
3725 identity,
3726 handles.dynamic_services.clone(),
3727 ));
3728 let server = tokio::spawn({
3729 let shutdown = shutdown.clone();
3730 async move { server.serve(guard, shutdown).await }
3731 });
3732
3733 Ok((
3734 RunningMcpSession {
3735 runtime_dir,
3736 shutdown,
3737 runner: Some(runner),
3738 server: Some(server),
3739 },
3740 selector,
3741 ))
3742 }
3743
3744 #[cfg(unix)]
3745 fn dynamic_params_for(
3746 service: &str,
3747 command: &[&str],
3748 idempotency_key: Option<&str>,
3749 ) -> DynamicServiceParams {
3750 DynamicServiceParams {
3751 service: service.to_string(),
3752 spec: PartialServiceSpec {
3753 command: Some(command.iter().map(|part| (*part).to_string()).collect()),
3754 ..PartialServiceSpec::default()
3755 },
3756 from_service: None,
3757 extra_args: Vec::new(),
3758 expires_after: Some(Lease::After(Duration::from_secs(30))),
3759 owner: Some("mcp-integration-test".to_string()),
3760 idempotency_key: idempotency_key.map(str::to_string),
3761 }
3762 }
3763
3764 #[cfg(unix)]
3765 fn dynamic_params(idempotency_key: Option<&str>) -> DynamicServiceParams {
3766 dynamic_params_for(
3767 "debug",
3768 &["sh", "-c", "echo dynamic-mcp-log; sleep 60"],
3769 idempotency_key,
3770 )
3771 }
3772
3773 #[cfg(unix)]
3774 async fn dynamic_log_visible(server: &McpServer, selector: &str) -> eyre::Result<bool> {
3775 let result = server
3776 .get_logs(Parameters(LogsArgs {
3777 service: "debug".to_string(),
3778 session: Some(selector.to_string()),
3779 run_generation: None,
3780 tail: Some(20),
3781 filters: LogFilterArgs {
3782 raw: false,
3783 grep: None,
3784 grep_context: None,
3785 min_level: None,
3786 since: None,
3787 since_unix_ms: None,
3788 trace_id: None,
3789 format: crate::logproc::LogFormat::Full,
3790 },
3791 }))
3792 .await
3793 .map_err(|err| eyre::eyre!(err.message))?;
3794 let Json(result) = result;
3795 Ok(result
3796 .entries
3797 .iter()
3798 .any(|entry| entry.line.contains("dynamic-mcp-log")))
3799 }
3800
3801 #[cfg(unix)]
3802 async fn assert_dynamic_renewal_and_events(
3803 server: &McpServer,
3804 selector: &str,
3805 ) -> eyre::Result<()> {
3806 let Json(renewed) = server
3807 .renew_dynamic_service(Parameters(RenewDynamicServiceArgs {
3808 service: "debug".to_string(),
3809 expected_revision: 1,
3810 expires_after: Some(Lease::After(Duration::from_secs(45))),
3811 session: Some(selector.to_string()),
3812 }))
3813 .await
3814 .map_err(|err| eyre::eyre!(err.message))?;
3815 assert_eq!(renewed.receipt.revision, 1);
3816
3817 let Json(events) = server
3818 .get_service_events(Parameters(ServiceEventsArgs {
3819 service: "debug".to_string(),
3820 session: Some(selector.to_string()),
3821 after_seq: None,
3822 after: None,
3823 tail: Some(20),
3824 }))
3825 .await
3826 .map_err(|err| eyre::eyre!(err.message))?;
3827 let ServiceEventsResult::Single(events) = events else {
3828 eyre::bail!("single-service event request returned a session-wide page");
3829 };
3830 assert!(
3831 events
3832 .events
3833 .iter()
3834 .any(|event| event.kind == micromux::ServiceEventKind::Created)
3835 );
3836 assert!(
3837 events
3838 .events
3839 .iter()
3840 .any(|event| event.kind == micromux::ServiceEventKind::LeaseRenewed)
3841 );
3842 assert!(events.next_seq.is_some());
3843 assert!(!events.truncated);
3844 Ok(())
3845 }
3846
3847 #[cfg(unix)]
3848 async fn start_event_test_services(server: &McpServer, selector: &str) -> eyre::Result<()> {
3849 for service in ["first", "second"] {
3850 let idempotency_key = format!("create-{service}");
3851 server
3852 .start_dynamic_service(Parameters(DynamicServiceArgs {
3853 session: Some(selector.to_string()),
3854 params: dynamic_params_for(
3855 service,
3856 &["sh", "-c", "sleep 60"],
3857 Some(&idempotency_key),
3858 ),
3859 }))
3860 .await
3861 .map_err(|err| eyre::eyre!(err.message))?;
3862 tokio::time::sleep(Duration::from_millis(2)).await;
3863 }
3864 Ok(())
3865 }
3866
3867 #[cfg(unix)]
3868 async fn renew_event_test_services(
3869 server: &McpServer,
3870 selector: &str,
3871 services: &[&str],
3872 lease_secs: u64,
3873 ) -> eyre::Result<()> {
3874 for service in services {
3875 server
3876 .renew_dynamic_service(Parameters(RenewDynamicServiceArgs {
3877 service: (*service).to_string(),
3878 expected_revision: 1,
3879 expires_after: Some(Lease::After(Duration::from_secs(lease_secs))),
3880 session: Some(selector.to_string()),
3881 }))
3882 .await
3883 .map_err(|err| eyre::eyre!(err.message))?;
3884 tokio::time::sleep(Duration::from_millis(2)).await;
3885 }
3886 Ok(())
3887 }
3888
3889 #[cfg(unix)]
3890 async fn wildcard_event_page(
3891 server: &McpServer,
3892 selector: &str,
3893 after: Option<BTreeMap<String, u64>>,
3894 ) -> eyre::Result<SessionServiceEventsResult> {
3895 let Json(page) = server
3896 .get_service_events(Parameters(ServiceEventsArgs {
3897 service: "*".to_string(),
3898 session: Some(selector.to_string()),
3899 after_seq: None,
3900 after,
3901 tail: Some(micromux::EVENT_HISTORY),
3902 }))
3903 .await
3904 .map_err(|err| eyre::eyre!(err.message))?;
3905 let ServiceEventsResult::Session(page) = page else {
3906 eyre::bail!("wildcard event request returned a single-service page");
3907 };
3908 Ok(page)
3909 }
3910
3911 #[cfg(unix)]
3912 fn assert_initial_event_page(page: &SessionServiceEventsResult) -> eyre::Result<()> {
3913 assert!(!page.truncated);
3914 assert!(page.events.windows(2).all(|events| {
3915 let left = &events[0];
3916 let right = &events[1];
3917 (left.event.at_unix_ms, left.service.as_str(), left.event.seq)
3918 <= (
3919 right.event.at_unix_ms,
3920 right.service.as_str(),
3921 right.event.seq,
3922 )
3923 }));
3924 let lifecycle = page
3925 .events
3926 .iter()
3927 .filter(|event| {
3928 ["first", "second"].contains(&event.service.as_str())
3929 && matches!(
3930 event.event.kind,
3931 micromux::ServiceEventKind::Created
3932 | micromux::ServiceEventKind::LeaseRenewed
3933 )
3934 })
3935 .map(|event| (event.service.as_str(), event.event.kind))
3936 .collect::<Vec<_>>();
3937 assert_eq!(
3938 lifecycle,
3939 vec![
3940 ("first", micromux::ServiceEventKind::Created),
3941 ("second", micromux::ServiceEventKind::Created),
3942 ("first", micromux::ServiceEventKind::LeaseRenewed),
3943 ("second", micromux::ServiceEventKind::LeaseRenewed),
3944 ]
3945 );
3946 for service in ["first", "second"] {
3947 let returned_cursor = page
3948 .events
3949 .iter()
3950 .filter(|event| event.service == service)
3951 .map(|event| event.event.seq)
3952 .max();
3953 assert_eq!(page.next.get(service).copied(), returned_cursor);
3954 }
3955 let encoded = serde_json::to_value(&page.events)?;
3956 assert!(
3957 encoded
3958 .as_array()
3959 .is_some_and(
3960 |events| events.iter().all(|event| event.get("service").is_some()
3961 && event.get("seq").is_some()
3962 && event.get("event").is_none())
3963 )
3964 );
3965 Ok(())
3966 }
3967
3968 #[cfg(unix)]
3969 fn assert_incremental_event_page(
3970 page: &SessionServiceEventsResult,
3971 previous: &BTreeMap<String, u64>,
3972 ) {
3973 assert!(
3974 page.events.iter().all(|event| {
3975 event.event.seq > previous.get(&event.service).copied().unwrap_or(0)
3976 })
3977 );
3978 let renewed = page
3979 .events
3980 .iter()
3981 .filter(|event| {
3982 event.event.kind == micromux::ServiceEventKind::LeaseRenewed
3983 && ["first", "second"].contains(&event.service.as_str())
3984 })
3985 .map(|event| event.service.as_str())
3986 .collect::<Vec<_>>();
3987 assert_eq!(renewed, vec!["second", "first"]);
3988 for event in &page.events {
3989 assert!(
3990 page.next
3991 .get(&event.service)
3992 .is_some_and(|cursor| *cursor >= event.event.seq)
3993 );
3994 }
3995 }
3996
3997 #[cfg(unix)]
3998 #[tokio::test]
3999 async fn session_events_merge_and_page_with_per_service_cursors() -> eyre::Result<()> {
4000 let project = tempfile::tempdir()?;
4001 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4002 let mut server = session.server();
4003 server.cwd = project.path().to_path_buf();
4004
4005 start_event_test_services(&server, &selector).await?;
4006 renew_event_test_services(&server, &selector, &["first", "second"], 45).await?;
4007 let first_page = wildcard_event_page(&server, &selector, None).await?;
4008 assert_initial_event_page(&first_page)?;
4009
4010 let previous = first_page.next;
4011 renew_event_test_services(&server, &selector, &["second", "first"], 50).await?;
4012 let next_page = wildcard_event_page(&server, &selector, Some(previous.clone())).await?;
4013 assert_incremental_event_page(&next_page, &previous);
4014
4015 let invalid = server
4016 .get_service_events(Parameters(ServiceEventsArgs {
4017 service: "*".to_string(),
4018 session: Some(selector),
4019 after_seq: Some(1),
4020 after: None,
4021 tail: None,
4022 }))
4023 .await
4024 .err()
4025 .ok_or_else(|| eyre::eyre!("wildcard scalar cursor was accepted"))?;
4026 assert!(invalid.message.contains("after_seq is service-scoped"));
4027
4028 session.finish().await?;
4029 Ok(())
4030 }
4031
4032 #[test]
4035 fn mcp_never_sends_terminal_requests() -> eyre::Result<()> {
4036 let forbidden = [concat!("Send", "Input"), concat!("Resize", "Terminal")];
4038 let mut pending = vec![std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src")];
4039 let mut scanned = 0;
4040 while let Some(path) = pending.pop() {
4041 if path.is_dir() {
4042 for entry in std::fs::read_dir(&path)? {
4043 pending.push(entry?.path());
4044 }
4045 continue;
4046 }
4047 if path.extension().is_none_or(|extension| extension != "rs") {
4048 continue;
4049 }
4050 let source = std::fs::read_to_string(&path)?;
4051 scanned += 1;
4052 for name in forbidden {
4053 assert!(
4054 !source.contains(name),
4055 "{} references the terminal request {name}",
4056 path.display()
4057 );
4058 }
4059 }
4060 assert!(scanned > 1, "found no MCP sources to scan");
4061 Ok(())
4062 }
4063
4064 #[test]
4065 fn server_builds_typed_tool_schemas() -> eyre::Result<()> {
4066 let server = McpServer::new();
4067 let tools = server.tool_router.list_all();
4068 let restart = tools
4069 .iter()
4070 .find(|tool| tool.name == "restart_service_and_wait")
4071 .ok_or_else(|| eyre::eyre!("missing restart_service_and_wait tool"))?;
4072 assert!(
4073 restart
4074 .description
4075 .as_deref()
4076 .is_some_and(|description| description.contains("hot-reload"))
4077 );
4078 let input_properties = restart
4079 .input_schema
4080 .get("properties")
4081 .and_then(serde_json::Value::as_object)
4082 .ok_or_else(|| eyre::eyre!("missing input properties"))?;
4083 assert!(input_properties.contains_key("service"));
4084 assert!(input_properties.contains_key("timeout_secs"));
4085 assert!(input_properties.contains_key("log_limit"));
4086
4087 let output_schema =
4088 serde_json::to_string(&schemars::schema_for!(super::RestartAndWaitResult))?;
4089 assert!(output_schema.contains("previous_generation"));
4090 assert!(output_schema.contains("run_generation"));
4091 assert!(output_schema.contains("snapshot"));
4092 assert!(output_schema.contains("diagnosis"));
4093 assert!(output_schema.contains("session"));
4094 assert!(!output_schema.contains("session_ref"));
4095 let ensure_schema =
4096 serde_json::to_string(&schemars::schema_for!(super::EnsureServiceReadyResult))?;
4097 assert!(ensure_schema.contains("diagnosis"));
4098 for name in [
4099 "start_dynamic_service",
4100 "start_dynamic_service_and_wait",
4101 "replace_dynamic_service",
4102 "renew_dynamic_service",
4103 "stop_dynamic_service",
4104 "get_service_events",
4105 "validate_config",
4106 "reconcile_config",
4107 "ensure_service_ready",
4108 "wait_for_exit",
4109 "get_health_history",
4110 "get_session_env",
4111 ] {
4112 assert!(
4113 tools.iter().any(|tool| tool.name == name),
4114 "missing {name} tool"
4115 );
4116 }
4117 for name in ["start_dynamic_service", "replace_dynamic_service"] {
4118 let description = tools
4119 .iter()
4120 .find(|tool| tool.name == name)
4121 .and_then(|tool| tool.description.as_deref())
4122 .ok_or_else(|| eyre::eyre!("missing {name} description"))?;
4123 assert!(description.contains("from_service equal to service"));
4124 assert!(description.contains("extra_args re-append"));
4125 }
4126 for surface in [
4127 "capabilities.dynamic_services",
4128 "start_dynamic_service_and_wait",
4129 "idempotency_key",
4130 "renew_dynamic_service",
4131 "reconcile_config",
4132 "validate_config",
4133 "get_service_events",
4134 "ensure_service_ready",
4135 "wait_for_exit",
4136 "get_health_history",
4137 "get_session_env",
4138 "start_dynamic_service` remains the way to run a command under the session",
4139 "micromux attach",
4140 ] {
4141 assert!(
4142 super::INSTRUCTIONS.contains(surface),
4143 "missing {surface} guidance"
4144 );
4145 }
4146 Ok(())
4147 }
4148
4149 #[cfg(unix)]
4150 #[tokio::test]
4151 async fn get_health_history_returns_attempts_oldest_first() -> eyre::Result<()> {
4152 let project = tempfile::tempdir()?;
4153 let yaml = r#"version: 1
4154services:
4155 svc:
4156 command: ["sh", "-c", "sleep 60"]
4157 healthcheck:
4158 test: ["CMD-SHELL", "echo probe-output; exit 1"]
4159 start_delay: "10ms"
4160 interval: "50ms"
4161 timeout: "1s"
4162 retries: 50
4163"#;
4164 let (session, selector) =
4165 boot_mcp_session_with_yaml(project.path(), "mcp-health-history-test", yaml)?;
4166 let mut server = session.server();
4167 server.cwd = project.path().to_path_buf();
4168
4169 let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
4170 let result = loop {
4171 let Json(result) = server
4172 .get_health_history(Parameters(ServiceArgs {
4173 service: "svc".to_string(),
4174 session: Some(selector.clone()),
4175 }))
4176 .await
4177 .map_err(|err| eyre::eyre!("get_health_history: {err:?}"))?;
4178 if result.attempts.len() >= 2 {
4179 break result;
4180 }
4181 if tokio::time::Instant::now() >= deadline {
4182 eyre::bail!("healthcheck history did not accumulate two attempts");
4183 }
4184 tokio::time::sleep(Duration::from_millis(25)).await;
4185 };
4186
4187 assert_eq!(result.service, "svc");
4188 assert_eq!(result.snapshot.id, "svc");
4189 assert!(
4190 result
4191 .attempts
4192 .windows(2)
4193 .all(|pair| pair[0].attempt < pair[1].attempt)
4194 );
4195 let completed = result
4196 .attempts
4197 .iter()
4198 .find(|attempt| attempt.result.is_some())
4199 .ok_or_else(|| eyre::eyre!("no completed attempt in history"))?;
4200 assert!(
4201 completed
4202 .output
4203 .iter()
4204 .any(|line| line.line.contains("probe-output"))
4205 );
4206 session.finish().await
4207 }
4208
4209 #[cfg(unix)]
4212 fn boot_env_session(project: &std::path::Path) -> eyre::Result<(RunningMcpSession, String)> {
4213 std::fs::write(project.join("svc.env"), "FROM_ENV_FILE=from-file\n")?;
4214 std::fs::write(project.join("session.env"), "SESSION_SECRET=s3ss10n\n")?;
4215 let yaml = r#"version: 1
4216allocate_ports: [MCP_ENV_TEST_PORT]
4217env_file: session.env
4218services:
4219 svc:
4220 command: ["sh", "-c", "sleep 60"]
4221 env_file: svc.env
4222 environment:
4223 SECRET: "s3cr3t"
4224"#;
4225 boot_mcp_session_with_yaml(project, "mcp-env-test", yaml)
4226 }
4227
4228 #[cfg(unix)]
4230 fn env_args(selector: &str, service: Option<&str>, names: Option<&[&str]>) -> SessionEnvArgs {
4231 SessionEnvArgs {
4232 session: Some(selector.to_string()),
4233 service: service.map(str::to_string),
4234 names: names.map(|names| names.iter().map(ToString::to_string).collect()),
4235 }
4236 }
4237
4238 #[cfg(unix)]
4241 #[tokio::test]
4242 async fn get_session_env_discloses_session_values_only_when_asked() -> eyre::Result<()> {
4243 let project = tempfile::tempdir()?;
4244 let (session, selector) = boot_env_session(project.path())?;
4245 let mut server = session.server();
4246 server.cwd = project.path().to_path_buf();
4247
4248 let Json(names_only) = server
4250 .get_session_env(Parameters(env_args(&selector, None, None)))
4251 .await
4252 .map_err(|err| eyre::eyre!(err.message))?;
4253 assert_eq!(names_only.session_ref.session, "mcp-env-test");
4254 assert_eq!(
4255 names_only.session_ref.config_path,
4256 project
4257 .path()
4258 .canonicalize()?
4259 .join("micromux.yaml")
4260 .to_string_lossy()
4261 );
4262 assert!(!serde_json::to_string(&names_only)?.contains("s3ss10n"));
4263 assert_eq!(
4264 (names_only.service, names_only.stale, names_only.variables),
4265 (None, None, None)
4266 );
4267 let names = names_only
4268 .names
4269 .ok_or_else(|| eyre::eyre!("session names are missing"))?;
4270 for name in ["MCP_ENV_TEST_PORT", "MICROMUX_SESSION", "SESSION_SECRET"] {
4271 assert!(names.iter().any(|listed| listed == name), "{name}");
4272 }
4273
4274 let Json(values) = server
4276 .get_session_env(Parameters(env_args(
4277 &selector,
4278 None,
4279 Some(&["MCP_ENV_TEST_PORT", "SESSION_SECRET"]),
4280 )))
4281 .await
4282 .map_err(|err| eyre::eyre!(err.message))?;
4283 let variables = values
4284 .variables
4285 .ok_or_else(|| eyre::eyre!("session values are missing"))?;
4286 let port = variables
4287 .get("MCP_ENV_TEST_PORT")
4288 .ok_or_else(|| eyre::eyre!("the allocated port is missing"))?;
4289 assert!(port.parse::<u16>().is_ok(), "{port}");
4290 assert_eq!(
4291 variables.get("SESSION_SECRET").map(String::as_str),
4292 Some("s3ss10n")
4293 );
4294
4295 session.finish().await
4296 }
4297
4298 #[cfg(unix)]
4300 #[tokio::test]
4301 async fn get_session_env_discloses_service_values_only_when_asked() -> eyre::Result<()> {
4302 let project = tempfile::tempdir()?;
4303 let (session, selector) = boot_env_session(project.path())?;
4304 let mut server = session.server();
4305 server.cwd = project.path().to_path_buf();
4306
4307 let Json(names_only) = server
4309 .get_session_env(Parameters(env_args(&selector, Some("svc"), None)))
4310 .await
4311 .map_err(|err| eyre::eyre!(err.message))?;
4312 assert!(!serde_json::to_string(&names_only)?.contains("s3cr3t"));
4313 assert!(names_only.variables.is_none());
4314 assert_eq!(names_only.stale, Some(false));
4315 let names = names_only
4316 .names
4317 .ok_or_else(|| eyre::eyre!("service names are missing"))?;
4318 for name in [
4319 "FROM_ENV_FILE",
4320 "MCP_ENV_TEST_PORT",
4321 "SECRET",
4322 "SESSION_SECRET",
4323 ] {
4324 assert!(names.iter().any(|listed| listed == name), "{name}");
4325 }
4326
4327 let Json(values) = server
4329 .get_session_env(Parameters(env_args(
4330 &selector,
4331 Some("svc"),
4332 Some(&["SECRET", "NOT_SET"]),
4333 )))
4334 .await
4335 .map_err(|err| eyre::eyre!(err.message))?;
4336 assert_eq!(
4337 values.variables,
4338 Some(BTreeMap::from([(
4339 "SECRET".to_string(),
4340 "s3cr3t".to_string()
4341 )]))
4342 );
4343 assert_eq!(values.missing, ["NOT_SET"]);
4344 assert_eq!(values.service.as_deref(), Some("svc"));
4345
4346 let unknown = server
4348 .get_session_env(Parameters(env_args(&selector, Some("nope"), None)))
4349 .await;
4350 assert!(
4351 unknown
4352 .as_ref()
4353 .is_err_and(|err| err.message.contains("UnknownService")),
4354 "{:?}",
4355 unknown.map(|_| ())
4356 );
4357
4358 session.finish().await
4359 }
4360
4361 #[cfg(unix)]
4362 #[tokio::test]
4363 async fn reconcile_config_round_trips_through_the_mcp_tool() -> eyre::Result<()> {
4364 let project = tempfile::tempdir()?;
4365 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4366 let mut server = session.server();
4367 server.cwd = project.path().to_path_buf();
4368 std::fs::write(
4369 project.path().join("micromux.yaml"),
4370 r#"version: 1
4371control:
4372 dynamic_services:
4373 enabled: true
4374 allowed_working_roots: [.]
4375 max_services: 2
4376 max_lifetime: 1m
4377services:
4378 base:
4379 command: ["sh", "-c", "sleep 60"]
4380 disabled:
4381 command: ["sh", "-c", "sleep 60"]
4382 disabled: true
4383 added:
4384 command: ["sh", "-c", "sleep 60"]
4385"#,
4386 )?;
4387
4388 let Json(dry_run) = server
4389 .reconcile_config(Parameters(ReconcileConfigArgs {
4390 session: Some(selector.clone()),
4391 dry_run: true,
4392 }))
4393 .await
4394 .map_err(|err| eyre::eyre!(err.message))?;
4395 assert!(dry_run.dry_run);
4396 assert_ne!(dry_run.session_ref.id, "");
4397 assert_eq!(dry_run.actions.len(), 1);
4398 assert_eq!(dry_run.actions[0].service, "added");
4399 assert_eq!(
4400 dry_run.actions[0].action,
4401 micromux::ReconcileActionKind::Added
4402 );
4403 assert_json_keys(
4404 &dry_run,
4405 &["session", "id", "pid", "config_path", "dry_run", "actions"],
4406 )?;
4407 let Json(before_apply) = server
4408 .list_services(Parameters(SessionArgs {
4409 session: Some(selector.clone()),
4410 }))
4411 .await
4412 .map_err(|err| eyre::eyre!(err.message))?;
4413 assert!(
4414 before_apply
4415 .services
4416 .iter()
4417 .all(|snapshot| snapshot.id != "added")
4418 );
4419
4420 let Json(applied) = server
4421 .reconcile_config(Parameters(ReconcileConfigArgs {
4422 session: Some(selector.clone()),
4423 dry_run: false,
4424 }))
4425 .await
4426 .map_err(|err| eyre::eyre!(err.message))?;
4427 assert!(!applied.dry_run);
4428 assert_eq!(applied.actions, dry_run.actions);
4429 let Json(after_apply) = server
4430 .list_services(Parameters(SessionArgs {
4431 session: Some(selector),
4432 }))
4433 .await
4434 .map_err(|err| eyre::eyre!(err.message))?;
4435 assert!(
4436 after_apply
4437 .services
4438 .iter()
4439 .any(|snapshot| snapshot.id == "added")
4440 );
4441
4442 session.finish().await?;
4443 Ok(())
4444 }
4445
4446 #[cfg(unix)]
4447 #[tokio::test]
4448 async fn start_dynamic_and_wait_returns_success_failure_and_replay_context() -> eyre::Result<()>
4449 {
4450 let project = tempfile::tempdir()?;
4451 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4452 let mut server = session.server();
4453 server.cwd = project.path().to_path_buf();
4454 let mut healthy_params = dynamic_params_for(
4455 "healthy-job",
4456 &[
4457 "sh",
4458 "-c",
4459 "echo bundled-ready; touch bundle.ready; sleep 60",
4460 ],
4461 Some("bundle-healthy"),
4462 );
4463 healthy_params.spec.healthcheck = SpecField::Value(HealthcheckSpec {
4464 test: vec![
4465 "sh".to_string(),
4466 "-c".to_string(),
4467 "test -f bundle.ready".to_string(),
4468 ],
4469 interval: Duration::from_millis(10),
4470 timeout: Duration::from_secs(1),
4471 ..HealthcheckSpec::default()
4472 });
4473
4474 let Json(healthy) = server
4475 .start_dynamic_service_and_wait(Parameters(StartDynamicAndWaitArgs {
4476 session: Some(selector.clone()),
4477 params: healthy_params.clone(),
4478 timeout_secs: Some(5),
4479 log_limit: Some(20),
4480 }))
4481 .await
4482 .map_err(|err| eyre::eyre!(err.message))?;
4483 assert!(matches!(healthy.outcome.status, WaitStatus::Healthy));
4484 assert!(
4485 healthy
4486 .logs
4487 .iter()
4488 .any(|entry| entry.line.contains("bundled-ready"))
4489 );
4490 assert!(healthy.diagnosis.is_none());
4491
4492 let Json(replayed) = server
4493 .start_dynamic_service_and_wait(Parameters(StartDynamicAndWaitArgs {
4494 session: Some(selector.clone()),
4495 params: healthy_params,
4496 timeout_secs: Some(5),
4497 log_limit: Some(20),
4498 }))
4499 .await
4500 .map_err(|err| eyre::eyre!(err.message))?;
4501 assert!(replayed.receipt.idempotent_replay);
4502 assert!(matches!(replayed.outcome.status, WaitStatus::Healthy));
4503
4504 let failing_params = dynamic_params_for(
4505 "failing-job",
4506 &["micromux-definitely-missing-command"],
4507 None,
4508 );
4509 let Json(failed) = server
4510 .start_dynamic_service_and_wait(Parameters(StartDynamicAndWaitArgs {
4511 session: Some(selector),
4512 params: failing_params,
4513 timeout_secs: Some(5),
4514 log_limit: Some(20),
4515 }))
4516 .await
4517 .map_err(|err| eyre::eyre!(err.message))?;
4518 assert!(matches!(failed.outcome.status, WaitStatus::Exited));
4519 assert_eq!(failed.snapshot.last_exit_code, Some(-1));
4520 assert!(failed.diagnosis.is_some());
4521 assert!(
4522 failed
4523 .events
4524 .iter()
4525 .any(|event| event.kind == micromux::ServiceEventKind::SpawnFailed)
4526 );
4527
4528 session.finish().await?;
4529 Ok(())
4530 }
4531
4532 #[cfg(unix)]
4533 #[tokio::test]
4534 async fn wait_for_exit_returns_job_output_times_out_and_rejects_disabled() -> eyre::Result<()> {
4535 let project = tempfile::tempdir()?;
4536 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4537 let mut server = session.server();
4538 server.cwd = project.path().to_path_buf();
4539 let params = dynamic_params_for("job", &["sh", "-c", "sleep 0.2; echo done; exit 3"], None);
4540 let Json(started) = server
4541 .start_dynamic_service(Parameters(DynamicServiceArgs {
4542 session: Some(selector.clone()),
4543 params,
4544 }))
4545 .await
4546 .map_err(|err| eyre::eyre!(err.message))?;
4547
4548 let Json(exited) = server
4549 .wait_for_exit(Parameters(WaitForExitArgs {
4550 service: "job".to_string(),
4551 session: Some(selector.clone()),
4552 after_generation: Some(started.receipt.observed_generation),
4553 timeout_secs: Some(5),
4554 log_limit: Some(20),
4555 }))
4556 .await
4557 .map_err(|err| eyre::eyre!(err.message))?;
4558 assert!(matches!(exited.status, WaitForExitStatus::Exited));
4559 assert_eq!(exited.exit_code, Some(3));
4560 assert!(exited.logs.iter().any(|entry| entry.line.contains("done")));
4561
4562 let Json(timed_out) = server
4563 .wait_for_exit(Parameters(WaitForExitArgs {
4564 service: "base".to_string(),
4565 session: Some(selector.clone()),
4566 after_generation: None,
4567 timeout_secs: Some(1),
4568 log_limit: Some(20),
4569 }))
4570 .await
4571 .map_err(|err| eyre::eyre!(err.message))?;
4572 assert!(matches!(timed_out.status, WaitForExitStatus::Timeout));
4573 assert_eq!(timed_out.exit_code, None);
4574
4575 let disabled = server
4576 .wait_for_exit(Parameters(WaitForExitArgs {
4577 service: "disabled".to_string(),
4578 session: Some(selector),
4579 after_generation: None,
4580 timeout_secs: Some(1),
4581 log_limit: Some(20),
4582 }))
4583 .await
4584 .err()
4585 .ok_or_else(|| eyre::eyre!("disabled service unexpectedly waited"))?;
4586 assert!(disabled.message.contains("disabled with no qualifying run"));
4587
4588 session.finish().await?;
4589 Ok(())
4590 }
4591
4592 #[cfg(unix)]
4593 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
4594 async fn ensure_ready_runs_jobs_to_completion() -> eyre::Result<()> {
4595 let project = tempfile::tempdir()?;
4596 let yaml = r#"version: 1
4597services:
4598 seed:
4599 kind: job
4600 command: ["sh", "-c", "sleep 2"]
4601 reset:
4602 kind: job
4603 run: manual
4604 command: ["sh", "-c", "true"]
4605 off:
4606 kind: job
4607 disabled: true
4608 command: ["sh", "-c", "true"]
4609"#;
4610 let (session, selector) =
4611 boot_mcp_session_with_yaml(project.path(), "mcp-jobs-test", yaml)?;
4612 let mut server = session.server();
4613 server.cwd = project.path().to_path_buf();
4614
4615 for (service, expected) in [
4616 ("seed", &[EnsureActionKind::Waited][..]),
4617 (
4618 "reset",
4619 &[EnsureActionKind::RanJob, EnsureActionKind::Waited][..],
4620 ),
4621 (
4622 "off",
4623 &[EnsureActionKind::EnabledService, EnsureActionKind::Waited][..],
4624 ),
4625 ] {
4626 let Json(ready) = server
4627 .ensure_service_ready(Parameters(EnsureReadyArgs {
4628 service: service.to_string(),
4629 session: Some(selector.clone()),
4630 path: None,
4631 timeout_secs: Some(10),
4632 log_limit: Some(2),
4633 }))
4634 .await
4635 .map_err(|err| eyre::eyre!(err.message))?;
4636 assert!(
4637 matches!(ready.outcome.status, WaitStatus::Completed),
4638 "{service} did not complete: {:?} {:?}",
4639 ready.snapshot.execution,
4640 ready.snapshot.kind
4641 );
4642 assert_eq!(ready.snapshot.execution, Execution::Completed);
4643 let kinds = ready
4644 .actions
4645 .iter()
4646 .map(|action| serde_json::to_value(&action.kind))
4647 .collect::<Result<Vec<_>, _>>()?;
4648 let expected = expected
4649 .iter()
4650 .map(serde_json::to_value)
4651 .collect::<Result<Vec<_>, _>>()?;
4652 assert_eq!(kinds, expected, "{service}");
4653 }
4654
4655 session.finish().await?;
4656 Ok(())
4657 }
4658
4659 #[cfg(unix)]
4660 #[tokio::test]
4661 async fn waits_fail_fast_behind_a_dependency_that_will_not_restart() -> eyre::Result<()> {
4662 let project = tempfile::tempdir()?;
4663 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4664 let mut server = session.server();
4665 server.cwd = project.path().to_path_buf();
4666 let Json(seed) = server
4667 .start_dynamic_service(Parameters(DynamicServiceArgs {
4668 session: Some(selector.clone()),
4669 params: dynamic_params_for("seed", &["sh", "-c", "exit 4"], None),
4670 }))
4671 .await
4672 .map_err(|err| eyre::eyre!(err.message))?;
4673 server
4674 .wait_for_exit(Parameters(WaitForExitArgs {
4675 service: "seed".to_string(),
4676 session: Some(selector.clone()),
4677 after_generation: Some(seed.receipt.observed_generation),
4678 timeout_secs: Some(5),
4679 log_limit: Some(1),
4680 }))
4681 .await
4682 .map_err(|err| eyre::eyre!(err.message))?;
4683 let mut api = dynamic_params_for("api", &["sh", "-c", "sleep 60"], None);
4684 api.spec.depends_on = Some(vec![micromux::DependencySpec {
4685 service: "seed".to_string(),
4686 condition: Some(micromux::DependencyCondition::CompletedSuccessfully),
4687 }]);
4688 server
4689 .start_dynamic_service(Parameters(DynamicServiceArgs {
4690 session: Some(selector.clone()),
4691 params: api,
4692 }))
4693 .await
4694 .map_err(|err| eyre::eyre!(err.message))?;
4695
4696 let started = tokio::time::Instant::now();
4697 let healthy = server
4698 .wait_for_healthy(Parameters(WaitArgs {
4699 service: "api".to_string(),
4700 session: Some(selector.clone()),
4701 after_generation: None,
4702 timeout_secs: Some(30),
4703 }))
4704 .await
4705 .err()
4706 .ok_or_else(|| eyre::eyre!("a health wait behind a failed dependency resolved"))?;
4707 let exit = server
4708 .wait_for_exit(Parameters(WaitForExitArgs {
4709 service: "api".to_string(),
4710 session: Some(selector.clone()),
4711 after_generation: None,
4712 timeout_secs: Some(30),
4713 log_limit: Some(1),
4714 }))
4715 .await
4716 .err()
4717 .ok_or_else(|| eyre::eyre!("an exit wait behind a failed dependency resolved"))?;
4718 let Json(bundle) = server
4720 .restart_service_and_wait(Parameters(RestartAndWaitArgs {
4721 service: "api".to_string(),
4722 session: Some(selector.clone()),
4723 timeout_secs: Some(30),
4724 log_limit: Some(1),
4725 }))
4726 .await
4727 .map_err(|err| eyre::eyre!(err.message))?;
4728 assert!(matches!(
4729 bundle.outcome.status,
4730 WaitStatus::DependencyFailed
4731 ));
4732 assert_eq!(
4733 bundle
4734 .outcome
4735 .dependency_failure
4736 .as_ref()
4737 .map(|failure| (failure.service.as_str(), failure.exit_code)),
4738 Some(("seed", Some(4)))
4739 );
4740 assert!(
4741 bundle
4742 .events
4743 .iter()
4744 .any(|event| event.kind == micromux::ServiceEventKind::DependencyFailed)
4745 );
4746 assert!(started.elapsed() < Duration::from_secs(10));
4747 for error in [healthy, exit] {
4748 assert!(
4749 error
4750 .message
4751 .contains("dependency `seed` exited with code 4 and will not restart"),
4752 "{}",
4753 error.message
4754 );
4755 assert_eq!(
4756 error.data.as_ref().and_then(|data| data.get("exit_code")),
4757 Some(&serde_json::json!(4))
4758 );
4759 }
4760
4761 session.finish().await?;
4762 Ok(())
4763 }
4764
4765 fn session_info(id: &str, services: &[&str]) -> SessionInfo {
4766 SessionInfo {
4767 session: None,
4768 protocol_version: PROTOCOL_VERSION,
4769 id: id.to_string(),
4770 pid: 4321,
4771 start_time: 0,
4772 name: "proj".to_string(),
4773 working_dir: "/w".to_string(),
4774 config_path: "/w/micromux.yaml".to_string(),
4775 services: services
4776 .iter()
4777 .map(|name| ServiceBrief {
4778 id: (*name).into(),
4779 name: (*name).to_string(),
4780 })
4781 .collect(),
4782 services_truncated: false,
4783 micromux_version: env!("CARGO_PKG_VERSION").to_string(),
4784 capabilities: None,
4785 }
4786 }
4787
4788 fn test_session_ref() -> SessionRef {
4789 SessionRef {
4790 session: "proj".to_string(),
4791 id: "abc".to_string(),
4792 pid: 123,
4793 config_path: "/w/micromux.yaml".to_string(),
4794 }
4795 }
4796
4797 fn assert_json_keys(value: &impl serde::Serialize, expected: &[&str]) -> eyre::Result<()> {
4798 let value = serde_json::to_value(value)?;
4799 let mut actual = value
4800 .as_object()
4801 .map(|object| object.keys().map(String::as_str).collect::<Vec<_>>())
4802 .ok_or_else(|| eyre::eyre!("receipt did not serialize as an object"))?;
4803 actual.sort_unstable();
4804 let mut expected = expected.to_vec();
4805 expected.sort_unstable();
4806 assert_eq!(actual, expected);
4807 Ok(())
4808 }
4809
4810 #[test]
4811 fn dynamic_capability_preflight_names_the_target_config() -> eyre::Result<()> {
4812 let info = session_info("h", &["svc"]);
4813
4814 let error = McpServer::require_dynamic_capability(&info)
4815 .err()
4816 .ok_or_else(|| eyre::eyre!("missing capability was accepted"))?;
4817
4818 assert!(error.message.contains("PolicyDenied"));
4819 assert!(error.message.contains("/w/micromux.yaml"));
4820 Ok(())
4821 }
4822
4823 #[cfg(unix)]
4824 #[tokio::test]
4825 async fn dynamic_service_lifecycle_crosses_the_mcp_tool_layer() -> eyre::Result<()> {
4826 let project = tempfile::tempdir()?;
4827 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4828 let mut server = session.server();
4829 server.cwd = project.path().to_path_buf();
4830 let params = dynamic_params(Some("create-debug"));
4831
4832 let Json(created) = server
4833 .start_dynamic_service(Parameters(DynamicServiceArgs {
4834 session: Some(selector.clone()),
4835 params: params.clone(),
4836 }))
4837 .await
4838 .map_err(|err| eyre::eyre!(err.message))?;
4839 assert_eq!(created.receipt.service, "debug");
4840 assert_eq!(created.receipt.revision, 1);
4841 assert!(!created.receipt.idempotent_replay);
4842
4843 let Json(replayed) = server
4844 .start_dynamic_service(Parameters(DynamicServiceArgs {
4845 session: Some(selector.clone()),
4846 params,
4847 }))
4848 .await
4849 .map_err(|err| eyre::eyre!(err.message))?;
4850 assert!(replayed.receipt.idempotent_replay);
4851 assert_eq!(replayed.receipt.revision, created.receipt.revision);
4852
4853 let Json(listed) = server
4854 .list_services(Parameters(SessionArgs {
4855 session: Some(selector.clone()),
4856 }))
4857 .await
4858 .map_err(|err| eyre::eyre!(err.message))?;
4859 let dynamic = listed
4860 .services
4861 .iter()
4862 .find(|snapshot| snapshot.id == "debug")
4863 .ok_or_else(|| eyre::eyre!("dynamic service is missing from roster"))?;
4864 assert_eq!(dynamic.origin, micromux::OriginKind::Dynamic);
4865 assert_eq!(dynamic.dynamic.as_ref().map(|info| info.revision), Some(1));
4866
4867 assert_dynamic_renewal_and_events(&server, &selector).await?;
4868
4869 let stale = server
4870 .replace_dynamic_service(Parameters(ReplaceDynamicServiceArgs {
4871 expected_revision: 0,
4872 session: Some(selector.clone()),
4873 params: dynamic_params(None),
4874 }))
4875 .await
4876 .err()
4877 .ok_or_else(|| eyre::eyre!("stale replacement was accepted"))?;
4878 assert!(stale.message.contains("RevisionMismatch"));
4879
4880 let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
4881 while !dynamic_log_visible(&server, &selector).await? {
4882 if tokio::time::Instant::now() >= deadline {
4883 eyre::bail!("dynamic service log did not become visible");
4884 }
4885 tokio::time::sleep(Duration::from_millis(20)).await;
4886 }
4887
4888 let Json(stopped) = server
4889 .stop_dynamic_service(Parameters(ServiceArgs {
4890 service: "debug".to_string(),
4891 session: Some(selector.clone()),
4892 }))
4893 .await
4894 .map_err(|err| eyre::eyre!(err.message))?;
4895 assert!(!stopped.receipt.already_retired);
4896
4897 let Json(listed) = server
4898 .list_services(Parameters(SessionArgs {
4899 session: Some(selector.clone()),
4900 }))
4901 .await
4902 .map_err(|err| eyre::eyre!(err.message))?;
4903 let retired = listed
4904 .services
4905 .iter()
4906 .find(|snapshot| snapshot.id == "debug")
4907 .and_then(|snapshot| snapshot.retired);
4908 assert_eq!(retired, Some(micromux::RetiredReason::Stopped));
4909 assert!(dynamic_log_visible(&server, &selector).await?);
4910
4911 session.finish().await?;
4912 Ok(())
4913 }
4914
4915 #[cfg(unix)]
4916 #[tokio::test]
4917 async fn ensure_ready_enables_waits_short_circuits_and_enriches_misses() -> eyre::Result<()> {
4918 let project = tempfile::tempdir()?;
4919 let (session, selector) = boot_dynamic_mcp_session(project.path())?;
4920 let mut server = session.server();
4921 server.cwd = project.path().to_path_buf();
4922
4923 let Json(enabled) = server
4924 .ensure_service_ready(Parameters(EnsureReadyArgs {
4925 service: "disabled".to_string(),
4926 session: Some(selector.clone()),
4927 path: None,
4928 timeout_secs: Some(5),
4929 log_limit: Some(2),
4930 }))
4931 .await
4932 .map_err(|err| eyre::eyre!(err.message))?;
4933 assert!(matches!(
4934 enabled.actions.as_slice(),
4935 [
4936 EnsureAction {
4937 kind: EnsureActionKind::EnabledService,
4938 ..
4939 },
4940 EnsureAction {
4941 kind: EnsureActionKind::Waited,
4942 ..
4943 }
4944 ]
4945 ));
4946 assert!(matches!(enabled.outcome.status, WaitStatus::Healthy));
4947
4948 let Json(already_ready) = server
4949 .ensure_service_ready(Parameters(EnsureReadyArgs {
4950 service: "disabled".to_string(),
4951 session: Some(selector.clone()),
4952 path: None,
4953 timeout_secs: Some(5),
4954 log_limit: Some(2),
4955 }))
4956 .await
4957 .map_err(|err| eyre::eyre!(err.message))?;
4958 assert!(already_ready.actions.is_empty());
4959 assert!(matches!(already_ready.outcome.status, WaitStatus::Healthy));
4960
4961 let missing = server
4962 .ensure_service_ready(Parameters(EnsureReadyArgs {
4963 service: "missing".to_string(),
4964 session: Some(selector),
4965 path: None,
4966 timeout_secs: Some(1),
4967 log_limit: Some(2),
4968 }))
4969 .await
4970 .err()
4971 .ok_or_else(|| eyre::eyre!("unknown service was accepted"))?;
4972 assert!(missing.message.contains("UnknownService"));
4973 assert!(missing.message.contains("missing"));
4974
4975 session.finish().await?;
4976 Ok(())
4977 }
4978
4979 #[test]
4980 fn session_selector_is_the_hash_form() {
4981 let info = session_info("b8b6127be329991b", &["rag-ui"]);
4982 assert_eq!(session_selector(&info), "hash:b8b6127be329991b");
4983 }
4984
4985 #[test]
4986 fn session_has_service_matches_by_id_or_name_only() {
4987 let info = session_info("h", &["rag-ui"]);
4988 assert!(session_has_service(&info, "rag-ui"));
4989 assert!(!session_has_service(&info, "api"));
4990 assert!(!session_has_service(&info, "rag"));
4991 }
4992
4993 #[test]
4994 fn mutation_result_serializes_flat_session_fields() -> eyre::Result<()> {
4995 let result = MutationResult {
4996 session_ref: test_session_ref(),
4997 accepted: vec![ServiceCommandAck {
4998 service: "api".to_string(),
4999 observed_generation: 7,
5000 }],
5001 service: "api".to_string(),
5002 generation: Some(7),
5003 log_cursor: Some(42),
5004 };
5005
5006 let value = serde_json::to_value(result)?;
5007 assert_eq!(value.get("session"), Some(&serde_json::json!("proj")));
5008 assert_eq!(value.get("id"), Some(&serde_json::json!("abc")));
5009 assert_eq!(value.get("pid"), Some(&serde_json::json!(123)));
5010 assert_eq!(
5011 value.get("config_path"),
5012 Some(&serde_json::json!("/w/micromux.yaml"))
5013 );
5014 assert_eq!(value.get("service"), Some(&serde_json::json!("api")));
5015 assert_eq!(value.get("generation"), Some(&serde_json::json!(7)));
5016 assert_eq!(value.get("log_cursor"), Some(&serde_json::json!(42)));
5017 let mut keys = value
5018 .as_object()
5019 .map(|object| object.keys().map(String::as_str).collect::<Vec<_>>())
5020 .unwrap_or_default();
5021 keys.sort_unstable();
5022 assert_eq!(
5023 keys,
5024 vec![
5025 "accepted",
5026 "config_path",
5027 "generation",
5028 "id",
5029 "log_cursor",
5030 "pid",
5031 "service",
5032 "session"
5033 ]
5034 );
5035 Ok(())
5036 }
5037
5038 #[test]
5039 fn session_mutation_receipts_have_exact_flat_key_sets() -> eyre::Result<()> {
5040 let restart_all = SessionMutationResult {
5041 session_ref: test_session_ref(),
5042 accepted: Vec::new(),
5043 };
5044 assert_json_keys(
5045 &restart_all,
5046 &["accepted", "config_path", "id", "pid", "session"],
5047 )?;
5048
5049 let stop = StopSessionResult {
5050 stopped: true,
5051 session_ref: test_session_ref(),
5052 note: None,
5053 };
5054 assert_json_keys(
5055 &stop,
5056 &["config_path", "id", "note", "pid", "session", "stopped"],
5057 )?;
5058 Ok(())
5059 }
5060
5061 #[test]
5062 fn dynamic_and_bundle_receipts_have_exact_flat_key_sets() -> eyre::Result<()> {
5063 let dynamic = DynamicMutationResult {
5064 session_ref: test_session_ref(),
5065 receipt: micromux_control::DynamicServiceAck {
5066 service: "debug".to_string(),
5067 revision: 2,
5068 observed_generation: 1,
5069 expires_at_unix_ms: Some(1234),
5070 command: vec!["true".to_string()],
5071 working_dir: Some("/w".to_string()),
5072 ports: Vec::new(),
5073 env_keys: Vec::new(),
5074 restart: micromux::RestartPolicy::Never,
5075 healthcheck_configured: false,
5076 already_retired: false,
5077 idempotent_replay: false,
5078 },
5079 };
5080 assert_json_keys(
5081 &dynamic,
5082 &[
5083 "already_retired",
5084 "command",
5085 "config_path",
5086 "env_keys",
5087 "expires_at_unix_ms",
5088 "healthcheck_configured",
5089 "id",
5090 "idempotent_replay",
5091 "observed_generation",
5092 "pid",
5093 "ports",
5094 "restart",
5095 "revision",
5096 "service",
5097 "session",
5098 "working_dir",
5099 ],
5100 )?;
5101
5102 let snapshot = ServiceSnapshot::initial(
5103 "svc".to_string(),
5104 "svc".to_string(),
5105 Vec::new(),
5106 None,
5107 micromux::RestartPolicy::Never,
5108 Vec::new(),
5109 None,
5110 );
5111 let bundle = RestartAndWaitResult {
5112 session_ref: test_session_ref(),
5113 service: "svc".to_string(),
5114 previous_generation: 1,
5115 run_generation: 2,
5116 outcome: WaitResult::healthy("svc".to_string(), 2),
5117 snapshot,
5118 logs: Vec::new(),
5119 logs_truncated: false,
5120 events: Vec::new(),
5121 diagnosis: None,
5122 };
5123 assert_json_keys(
5124 &bundle,
5125 &[
5126 "config_path",
5127 "events",
5128 "id",
5129 "logs",
5130 "logs_truncated",
5131 "outcome",
5132 "pid",
5133 "previous_generation",
5134 "run_generation",
5135 "service",
5136 "session",
5137 "snapshot",
5138 ],
5139 )?;
5140
5141 Ok(())
5142 }
5143
5144 #[test]
5147 fn wait_bundles_have_exact_flat_key_sets() -> eyre::Result<()> {
5148 let start_bundle = StartDynamicAndWaitResult {
5149 session_ref: test_session_ref(),
5150 receipt: micromux_control::DynamicServiceAck {
5151 service: "debug".to_string(),
5152 revision: 1,
5153 observed_generation: 0,
5154 expires_at_unix_ms: None,
5156 command: vec!["true".to_string()],
5157 working_dir: None,
5158 ports: Vec::new(),
5159 env_keys: Vec::new(),
5160 restart: micromux::RestartPolicy::Never,
5161 healthcheck_configured: false,
5162 already_retired: false,
5163 idempotent_replay: false,
5164 },
5165 outcome: WaitResult::healthy("debug".to_string(), 1),
5166 snapshot: ServiceSnapshot::initial(
5167 "debug".to_string(),
5168 "debug".to_string(),
5169 Vec::new(),
5170 None,
5171 micromux::RestartPolicy::Never,
5172 Vec::new(),
5173 None,
5174 ),
5175 logs: Vec::new(),
5176 logs_truncated: false,
5177 events: Vec::new(),
5178 diagnosis: None,
5179 };
5180 assert_json_keys(
5181 &start_bundle,
5182 &[
5183 "already_retired",
5184 "command",
5185 "config_path",
5186 "env_keys",
5187 "events",
5188 "healthcheck_configured",
5189 "id",
5190 "idempotent_replay",
5191 "logs",
5192 "logs_truncated",
5193 "observed_generation",
5194 "outcome",
5195 "pid",
5196 "ports",
5197 "restart",
5198 "revision",
5199 "service",
5200 "session",
5201 "snapshot",
5202 ],
5203 )?;
5204
5205 let exit = WaitForExitResult {
5206 session_ref: test_session_ref(),
5207 service: "job".to_string(),
5208 status: WaitForExitStatus::Exited,
5209 exit_code: Some(3),
5210 run_generation: 1,
5211 snapshot: ServiceSnapshot::initial(
5212 "job".to_string(),
5213 "job".to_string(),
5214 Vec::new(),
5215 None,
5216 micromux::RestartPolicy::Never,
5217 Vec::new(),
5218 None,
5219 ),
5220 logs: Vec::new(),
5221 logs_truncated: false,
5222 waited_secs: 1,
5223 };
5224 assert_json_keys(
5225 &exit,
5226 &[
5227 "config_path",
5228 "exit_code",
5229 "id",
5230 "logs",
5231 "logs_truncated",
5232 "pid",
5233 "run_generation",
5234 "service",
5235 "session",
5236 "snapshot",
5237 "status",
5238 "waited_secs",
5239 ],
5240 )?;
5241 Ok(())
5242 }
5243
5244 #[test]
5245 fn enrichment_resolves_by_id_not_name() {
5246 let mut info = session_info("h", &[]);
5250 info.services = vec![ServiceBrief {
5251 id: "web".into(),
5252 name: "frontend".to_string(),
5253 }];
5254 assert!(session_has_service(&info, "frontend"));
5256 assert!(session_has_service(&info, "web"));
5257 let snapshot = ServiceSnapshot::initial(
5259 "web".to_string(),
5260 "frontend".to_string(),
5261 Vec::new(),
5262 None,
5263 micromux::RestartPolicy::Never,
5264 Vec::new(),
5265 None,
5266 );
5267 assert!(
5268 matching_service(vec![snapshot], "frontend")
5269 .is_some_and(|snapshot| snapshot.id != "frontend")
5270 );
5271 }
5272
5273 #[test]
5274 fn targeted_service_lookup_prefers_an_exact_id_over_an_earlier_name() {
5275 let named = ServiceSnapshot::initial(
5276 "api".to_string(),
5277 "web".to_string(),
5278 Vec::new(),
5279 None,
5280 micromux::RestartPolicy::Never,
5281 Vec::new(),
5282 None,
5283 );
5284 let exact = ServiceSnapshot::initial(
5285 "web".to_string(),
5286 "frontend".to_string(),
5287 Vec::new(),
5288 None,
5289 micromux::RestartPolicy::Never,
5290 Vec::new(),
5291 None,
5292 );
5293
5294 let matched = matching_service(vec![named, exact], "web");
5295
5296 assert_eq!(matched.map(|snapshot| snapshot.id), Some("web".to_string()));
5297 }
5298
5299 #[test]
5300 fn wait_result_keeps_present_null_fields() -> eyre::Result<()> {
5301 let exited = serde_json::to_value(WaitResult::exited("svc".to_string(), None, 7))?;
5302 assert!(
5303 exited
5304 .get("exit_code")
5305 .is_some_and(serde_json::Value::is_null)
5306 );
5307
5308 let mut snapshot = ServiceSnapshot::initial(
5309 "svc".to_string(),
5310 "svc".to_string(),
5311 Vec::new(),
5312 None,
5313 micromux::RestartPolicy::Never,
5314 Vec::new(),
5315 None,
5316 );
5317 snapshot.execution = Execution::Running;
5318 snapshot.run_generation = 7;
5319 let timeout =
5320 serde_json::to_value(WaitResult::timeout("svc".to_string(), 1, &snapshot, None))?;
5321 assert!(
5322 timeout
5323 .get("health")
5324 .is_some_and(serde_json::Value::is_null)
5325 );
5326 assert!(
5327 timeout
5328 .get("uptime_secs")
5329 .is_some_and(serde_json::Value::is_null)
5330 );
5331 assert!(
5332 timeout
5333 .get("latest_healthcheck")
5334 .is_some_and(serde_json::Value::is_null)
5335 );
5336 Ok(())
5337 }
5338
5339 #[test]
5340 fn health_enrichment_is_current_running_generation_only() {
5341 let mut snapshot = ServiceSnapshot::initial(
5342 "svc".to_string(),
5343 "svc".to_string(),
5344 Vec::new(),
5345 Some(micromux::HealthcheckConfig {
5346 retries: 1,
5347 interval: Duration::from_secs(1),
5348 timeout: Duration::from_secs(1),
5349 }),
5350 micromux::RestartPolicy::Never,
5351 Vec::new(),
5352 None,
5353 );
5354 snapshot.execution = Execution::Running;
5355 snapshot.run_generation = 2;
5356 let mut healthcheck = HealthAttempt {
5357 run_generation: 2,
5358 attempt: 1,
5359 command: "curl -fsS localhost".to_string(),
5360 output: Vec::new(),
5361 result: None,
5362 };
5363
5364 assert!(health_attempt_matches_snapshot(&snapshot, &healthcheck));
5365
5366 healthcheck.run_generation = 3;
5367 assert!(!health_attempt_matches_snapshot(&snapshot, &healthcheck));
5368
5369 healthcheck.run_generation = 2;
5370 snapshot.execution = Execution::Exited;
5371 assert!(!health_attempt_matches_snapshot(&snapshot, &healthcheck));
5372 }
5373
5374 #[test]
5375 fn follow_cursor_is_last_delivered_seq_for_strict_after_protocol() {
5376 let lines = vec![
5377 LogLine {
5378 seq: 10,
5379 run_generation: 1,
5380 timestamp_unix_ms: 1_700_000_000_010,
5381 line: "a".to_string(),
5382 },
5383 LogLine {
5384 seq: 11,
5385 run_generation: 1,
5386 timestamp_unix_ms: 1_700_000_000_011,
5387 line: "b".to_string(),
5388 },
5389 ];
5390
5391 assert_eq!(next_follow_cursor(&lines, Some(9)), Some(11));
5392 assert_eq!(next_follow_cursor(&[], Some(11)), Some(11));
5393 assert_eq!(next_follow_cursor(&[], None), None);
5394 }
5395
5396 #[test]
5397 fn follow_gap_reports_evicted_lines() {
5398 let lines = vec![LogLine {
5399 seq: 15,
5400 run_generation: 2,
5401 timestamp_unix_ms: 1_700_000_000_015,
5402 line: "newest retained".to_string(),
5403 }];
5404
5405 assert!(follow_gap(&lines, None, Some(10), None).is_some());
5406 assert!(follow_gap(&lines, None, Some(14), None).is_none());
5407 assert!(follow_gap(&[], None, Some(10), None).is_none());
5408 assert!(follow_gap(&[], Some(15), Some(10), None).is_some());
5409 assert!(follow_gap(&lines, None, None, None).is_none());
5410 assert!(follow_gap(&lines, None, Some(10), Some(2)).is_none());
5411 }
5412
5413 #[test]
5414 fn wait_log_limit_advances_only_to_last_returned_match() {
5415 let mut entries = vec![
5416 entry("api", 11, 100),
5417 entry("api", 12, 101),
5418 entry("api", 13, 102),
5419 ];
5420
5421 let (next_seq, truncated) = truncate_wait_matches(&mut entries, 20, false, 2);
5422
5423 assert!(truncated);
5424 assert_eq!(next_seq, 12);
5425 assert_eq!(entries.len(), 2);
5426 }
5427
5428 #[test]
5429 fn wait_log_limit_preserves_split_record_boundary() {
5430 let mut entries = vec![
5431 entry("api", 11, 100),
5432 entry("api", 11, 101),
5433 entry("api", 12, 102),
5434 ];
5435
5436 let (next_seq, truncated) = truncate_wait_matches(&mut entries, 20, false, 1);
5437
5438 assert!(truncated);
5439 assert_eq!(next_seq, 11);
5440 assert_eq!(
5441 entries.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
5442 vec![11, 11]
5443 );
5444 }
5445
5446 #[test]
5447 fn wait_log_split_record_without_dropped_matches_advances_to_raw_cursor() {
5448 let mut entries = vec![entry("api", 11, 100), entry("api", 11, 101)];
5449
5450 let (next_seq, truncated) = truncate_wait_matches(&mut entries, 20, false, 1);
5451
5452 assert!(!truncated);
5453 assert_eq!(next_seq, 20);
5454 assert_eq!(
5455 entries.iter().map(|entry| entry.seq).collect::<Vec<_>>(),
5456 vec![11, 11]
5457 );
5458 }
5459
5460 #[test]
5461 fn wait_log_complete_page_advances_past_filtered_records() {
5462 let mut entries = vec![entry("api", 11, 100)];
5463
5464 let (next_seq, truncated) = truncate_wait_matches(&mut entries, 20, false, 2);
5465
5466 assert!(!truncated);
5467 assert_eq!(next_seq, 20);
5468 assert_eq!(entries.len(), 1);
5469 }
5470
5471 #[test]
5472 fn since_numeric_accepts_epoch_seconds() {
5473 assert_eq!(parse_since_text("0").unwrap(), 0);
5474 assert_eq!(parse_since_text("42").unwrap(), 42_000);
5475 assert_eq!(
5476 parse_since_text("1782911696789").unwrap(),
5477 1_782_911_696_789
5478 );
5479 }
5480
5481 #[test]
5482 fn follow_all_cursor_map_reserves_zero_for_before_first_entry() {
5483 let mut cursors = BTreeMap::new();
5484 assert_eq!(follow_all_after_seq(&cursors, "api"), None);
5485
5486 cursors.insert("api".to_string(), 12);
5487 assert_eq!(follow_all_after_seq(&cursors, "api"), Some(12));
5488 assert_eq!(follow_all_after_seq(&cursors, "worker"), Some(0));
5489 }
5490
5491 fn entry(service: &str, seq: u64, timestamp_unix_ms: u64) -> crate::logproc::ProcessedEntry {
5492 crate::logproc::ProcessedEntry {
5493 service: Some(service.to_string()),
5494 seq,
5495 run_generation: 1,
5496 timestamp_unix_ms,
5497 source_timestamp_unix_ms: None,
5498 line: format!("{service}-{seq}"),
5499 level: None,
5500 message: None,
5501 fields: BTreeMap::new(),
5502 }
5503 }
5504
5505 fn source_entry(
5506 service: &str,
5507 seq: u64,
5508 timestamp_unix_ms: u64,
5509 source_timestamp_unix_ms: u64,
5510 ) -> crate::logproc::ProcessedEntry {
5511 crate::logproc::ProcessedEntry {
5512 source_timestamp_unix_ms: Some(source_timestamp_unix_ms),
5513 ..entry(service, seq, timestamp_unix_ms)
5514 }
5515 }
5516
5517 fn page(
5518 service: &str,
5519 after_seq: Option<u64>,
5520 raw_next_seq: Option<u64>,
5521 entries: Vec<crate::logproc::ProcessedEntry>,
5522 ) -> MergedFollowPage {
5523 MergedFollowPage {
5524 service: service.to_string(),
5525 after_seq,
5526 raw_next_seq,
5527 gap: None,
5528 entries,
5529 truncated: false,
5530 }
5531 }
5532
5533 #[test]
5534 fn merged_follow_initial_tail_advances_every_service_cursor() {
5535 let merged = merge_follow_pages(
5536 vec![
5537 page("api", None, Some(10), vec![entry("api", 8, 300)]),
5538 page("worker", None, Some(7), vec![entry("worker", 7, 100)]),
5539 page("empty", None, None, Vec::new()),
5540 ],
5541 1,
5542 true,
5543 );
5544
5545 assert!(merged.truncated);
5546 assert_eq!(merged.entries.len(), 1);
5547 assert_eq!(
5548 merged
5549 .entries
5550 .first()
5551 .and_then(|entry| entry.service.as_deref()),
5552 Some("api")
5553 );
5554 assert_eq!(merged.next.get("api"), Some(&10));
5555 assert_eq!(merged.next.get("worker"), Some(&7));
5556 assert_eq!(merged.next.get("empty"), Some(&0));
5557 }
5558
5559 #[test]
5560 fn merged_follow_truncated_page_only_advances_returned_entries() {
5561 let merged = merge_follow_pages(
5562 vec![
5563 page(
5564 "api",
5565 Some(4),
5566 Some(20),
5567 vec![entry("api", 5, 100), entry("api", 6, 400)],
5568 ),
5569 page("worker", Some(9), Some(30), vec![entry("worker", 10, 200)]),
5570 ],
5571 2,
5572 false,
5573 );
5574
5575 assert!(merged.truncated);
5576 let returned = merged
5577 .entries
5578 .iter()
5579 .map(|entry| (entry.service.as_deref(), entry.seq))
5580 .collect::<Vec<_>>();
5581 assert_eq!(returned, vec![(Some("api"), 5), (Some("worker"), 10)]);
5582 assert_eq!(merged.next.get("api"), Some(&5));
5583 assert_eq!(merged.next.get("worker"), Some(&10));
5584 }
5585
5586 #[test]
5587 fn merged_follow_limit_preserves_split_record_boundary() {
5588 let merged = merge_follow_pages(
5589 vec![page(
5590 "api",
5591 Some(4),
5592 Some(6),
5593 vec![
5594 entry("api", 5, 100),
5595 entry("api", 5, 101),
5596 entry("api", 6, 102),
5597 ],
5598 )],
5599 1,
5600 false,
5601 );
5602
5603 assert!(merged.truncated);
5604 assert_eq!(
5605 merged
5606 .entries
5607 .iter()
5608 .map(|entry| entry.seq)
5609 .collect::<Vec<_>>(),
5610 vec![5, 5]
5611 );
5612 assert_eq!(merged.next.get("api"), Some(&5));
5613 }
5614
5615 #[test]
5616 fn merged_follow_tail_limit_preserves_split_record_boundary() {
5617 let merged = merge_follow_pages(
5618 vec![page(
5619 "api",
5620 None,
5621 Some(6),
5622 vec![
5623 entry("api", 5, 100),
5624 entry("api", 6, 101),
5625 entry("api", 6, 102),
5626 ],
5627 )],
5628 1,
5629 true,
5630 );
5631
5632 assert!(merged.truncated);
5633 assert_eq!(
5634 merged
5635 .entries
5636 .iter()
5637 .map(|entry| entry.seq)
5638 .collect::<Vec<_>>(),
5639 vec![6, 6]
5640 );
5641 assert_eq!(merged.next.get("api"), Some(&6));
5642 }
5643
5644 #[test]
5645 fn merged_follow_preserves_service_sequence_order_over_source_timestamps() {
5646 let merged = merge_follow_pages(
5647 vec![page(
5648 "api",
5649 Some(4),
5650 Some(6),
5651 vec![
5652 source_entry("api", 5, 200, 300),
5653 source_entry("api", 6, 250, 100),
5654 ],
5655 )],
5656 1,
5657 false,
5658 );
5659
5660 assert!(merged.truncated);
5661 assert_eq!(merged.entries.first().map(|entry| entry.seq), Some(5));
5662 assert_eq!(merged.next.get("api"), Some(&5));
5663 }
5664
5665 #[test]
5666 fn merged_follow_truncated_page_advances_services_with_no_matches() {
5667 let mut noisy = page("noisy", Some(40), Some(50), Vec::new());
5668 noisy.truncated = true;
5669 let merged = merge_follow_pages(
5670 vec![
5671 noisy,
5672 page("api", Some(4), Some(5), vec![entry("api", 5, 100)]),
5673 ],
5674 1,
5675 false,
5676 );
5677
5678 assert!(merged.truncated);
5679 assert_eq!(merged.next.get("api"), Some(&5));
5680 assert_eq!(merged.next.get("noisy"), Some(&50));
5681 }
5682
5683 #[test]
5684 fn server_truncated_page_advances_past_filtered_records_when_merged_page_is_complete() {
5685 let mut filtered = page("api", Some(4), Some(50), vec![entry("api", 5, 100)]);
5686 filtered.truncated = true;
5687 let merged = merge_follow_pages(vec![filtered], 10, false);
5688
5689 assert!(merged.truncated);
5690 assert_eq!(merged.entries.len(), 1);
5691 assert_eq!(merged.next.get("api"), Some(&50));
5692 }
5693
5694 #[tokio::test]
5695 async fn session_start_is_disabled_by_default() {
5696 let result = McpServer::new()
5697 .start_for_target(std::path::PathBuf::from("."))
5698 .await;
5699
5700 assert!(result.is_err());
5701 }
5702}
5703
5704#[cfg(all(test, unix))]
5705mod start_tests {
5706 use std::time::Duration;
5707
5708 use color_eyre::eyre;
5709 use similar_asserts::assert_eq;
5710
5711 use crate::tools::sessions::{START_READY_TIMEOUT, SpawnedServe};
5712
5713 struct StandIn {
5715 exited: bool,
5717 reports: Vec<(Duration, String)>,
5719 }
5720
5721 impl StandIn {
5722 fn running(reports: Vec<(Duration, String)>) -> Self {
5724 Self {
5725 exited: false,
5726 reports,
5727 }
5728 }
5729 }
5730
5731 async fn wait_for(
5733 stand_in: StandIn,
5734 ) -> eyre::Result<(Duration, Result<crate::StartSessionResult, String>)> {
5735 let directory = tempfile::tempdir()?;
5736 let config_path = directory.path().join("micromux.yaml");
5737 std::fs::write(&config_path, "version: 1\n")?;
5738 let config_path = micromux_control::CanonicalConfigPath::new(&config_path)?;
5739 let endpoints = [micromux_control::endpoint_for(
5740 directory.path(),
5741 &config_path,
5742 )];
5743 let stderr_path = directory.path().join("serve.stderr");
5744 std::fs::write(&stderr_path, "")?;
5745 let mut child =
5746 tokio::process::Command::new(if stand_in.exited { "true" } else { "sleep" })
5747 .args(if stand_in.exited {
5748 &[][..]
5749 } else {
5750 &["600"][..]
5751 })
5752 .kill_on_drop(true)
5753 .spawn()?;
5754 let mut reports = stand_in.reports;
5755 if stand_in.exited {
5756 let mut written = String::new();
5759 for (_, line) in reports.drain(..) {
5760 written.push_str(&line);
5761 written.push('\n');
5762 }
5763 std::fs::write(&stderr_path, written)?;
5764 child.wait().await?;
5765 }
5766 let report = {
5767 let stderr_path = stderr_path.clone();
5768 async move {
5769 let mut written = String::new();
5770 for (after, line) in reports {
5771 tokio::time::sleep(after).await;
5772 written.push_str(&line);
5773 written.push('\n');
5774 std::fs::write(&stderr_path, &written)?;
5775 }
5776 Ok::<_, std::io::Error>(())
5777 }
5778 };
5779 let started = tokio::time::Instant::now();
5780 let (result, reported) = tokio::join!(
5781 super::await_spawned_session(
5782 SpawnedServe { child, stderr_path },
5783 &endpoints,
5784 &config_path,
5785 ),
5786 report
5787 );
5788 reported?;
5789 Ok((
5790 started.elapsed(),
5791 result.map_err(|err| err.message.to_string()),
5792 ))
5793 }
5794
5795 fn outdated_proxy() -> String {
5797 format!(
5798 "{} (pid 4242) to exit",
5799 micromux_proxy::WAITING_FOR_OUTDATED_PROXY
5800 )
5801 }
5802
5803 fn previous_cleanup(bound: Duration) -> String {
5805 micromux::PreviousCleanupWait {
5806 services: vec!["infra".to_string()],
5807 bound,
5808 }
5809 .to_string()
5810 }
5811
5812 #[tokio::test(start_paused = true)]
5816 async fn a_waiting_start_gets_the_time_its_waits_need() -> eyre::Result<()> {
5817 let proxy_budget = micromux_proxy::OUTDATED_PROXY_WAIT + START_READY_TIMEOUT;
5818 let cleanup = Duration::from_secs(200);
5819 let slack = Duration::from_secs(1);
5821 let late = START_READY_TIMEOUT.saturating_sub(Duration::from_millis(100));
5823 let cases = [
5824 ("no wait", vec![], START_READY_TIMEOUT),
5825 (
5826 "outdated proxy",
5827 vec![(Duration::ZERO, outdated_proxy())],
5828 proxy_budget,
5829 ),
5830 (
5831 "late outdated proxy",
5832 vec![(late, outdated_proxy())],
5833 late + proxy_budget,
5834 ),
5835 (
5836 "previous cleanup",
5837 vec![(Duration::ZERO, previous_cleanup(cleanup))],
5838 cleanup + START_READY_TIMEOUT,
5839 ),
5840 (
5842 "previous cleanup, then outdated proxy",
5843 vec![
5844 (Duration::ZERO, previous_cleanup(cleanup)),
5845 (Duration::from_secs(150), outdated_proxy()),
5846 ],
5847 Duration::from_secs(150) + proxy_budget,
5848 ),
5849 ];
5850 for (case, reports, budget) in cases {
5851 let (waited, result) = wait_for(StandIn::running(reports)).await?;
5852 assert!(
5853 waited >= budget && waited < budget + slack,
5854 "{case}: waited {waited:?}, expected {budget:?}"
5855 );
5856 assert!(
5857 matches!(&result, Err(message) if message.contains("did not become reachable")),
5858 "{case}: {result:?}"
5859 );
5860 }
5861 Ok(())
5862 }
5863
5864 #[tokio::test(start_paused = true)]
5869 async fn a_start_in_progress_is_reported_as_still_starting() -> eyre::Result<()> {
5870 let holder = std::process::id();
5872 let held = micromux_control::ClaimError::Held { pid: Some(holder) }.to_string();
5873 let (waited, result) = wait_for(StandIn {
5874 exited: true,
5875 reports: vec![(Duration::ZERO, format!("Error: {held}"))],
5876 })
5877 .await?;
5878 let report = result.map_err(|message| eyre::eyre!(message))?;
5879 assert!(!report.started);
5880 assert_eq!(report.reachable, Some(false));
5881 assert_eq!(report.pid, Some(holder));
5882 assert!(
5883 report
5884 .reason
5885 .as_deref()
5886 .is_some_and(|reason| reason.contains(micromux_control::SESSION_ALREADY_STARTING)),
5887 "{:?}",
5888 report.reason
5889 );
5890 assert!(
5891 waited >= START_READY_TIMEOUT && waited < START_READY_TIMEOUT + Duration::from_secs(1),
5892 "{waited:?}"
5893 );
5894
5895 let mut gone = tokio::process::Command::new("true").spawn()?;
5897 let gone_pid = gone
5898 .id()
5899 .ok_or_else(|| eyre::eyre!("the process has no pid"))?;
5900 gone.wait().await?;
5901 let held = micromux_control::ClaimError::Held {
5902 pid: Some(gone_pid),
5903 }
5904 .to_string();
5905 let (_, result) = wait_for(StandIn {
5906 exited: true,
5907 reports: vec![(Duration::ZERO, format!("Error: {held}"))],
5908 })
5909 .await?;
5910 assert!(
5911 matches!(&result, Err(message) if message.contains("exited before it became reachable")),
5912 "{result:?}"
5913 );
5914 Ok(())
5915 }
5916}