Skip to main content

micromux_mcp/
lib.rs

1//! The micromux MCP server.
2//!
3//! A thin, near-stateless proxy: it discovers running micromux sessions over their local control
4//! endpoints and exposes them as MCP tools. It holds no supervision state — every tool connects to
5//! a session endpoint per call (cheap, local) and speaks the [`micromux_control`] protocol. All
6//! actions go through the same control plane the human uses in the TUI, so dependency gating, health
7//! re-probing, and restart policy are respected.
8//!
9//! The one tool that does more than connect is `start_session`: it spawns a detached, headless
10//! `micromux serve` for a project that has no live session. `stop_session` is its inverse — it asks
11//! a session to exit (freeing its ports), useful when switching between git worktrees that bind the
12//! same ports.
13
14mod 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;
75/// Default number of logical log entries returned by `get_logs` when the caller does not pass
76/// `tail`.
77const DEFAULT_LOG_TAIL: usize = 200;
78/// Upper bound on entries fetched from the session per call; also the window scanned when a filter is
79/// active, so `grep`/`min_level` can match against more than the returned count.
80const 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;
86/// Even if a change notification is missed (the subscription isn't registered server-side until
87/// after we connect, so it can drop the first one), re-poll the lossless model at least this often
88/// so a quiet, healthcheck-less service that becomes healthy is never stranded until the full
89/// timeout.
90const WAIT_POLL_FLOOR: Duration = Duration::from_secs(1);
91const WAIT_LOG_POLL: Duration = Duration::from_millis(250);
92/// Optional cursor capture must not materially delay the mutation it annotates.
93const 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/// The MCP server handler. Cheap to clone; holds no supervision state.
132#[derive(Clone)]
133pub struct McpServer {
134    cwd: PathBuf,
135    /// Where tools look for sessions.
136    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    /// Optional session selector: a session name, `name:<n>`, `pid:<n>`, `hash:<h>`, or omitted to
146    /// target the micromux running in the current project directory.
147    #[serde(default)]
148    session: Option<String>,
149}
150
151#[derive(Debug, Deserialize, JsonSchema)]
152struct SessionEnvArgs {
153    /// Optional session selector; omit for the current project.
154    #[serde(default)]
155    session: Option<String>,
156    /// The id of a service whose resolved environment to read; omit for the session's own
157    /// environment.
158    #[serde(default)]
159    service: Option<String>,
160    /// Variables to read.
161    ///
162    /// Without them, only the names come back, because values may hold secrets from env files.
163    #[serde(default)]
164    names: Option<Vec<String>>,
165}
166
167#[derive(Debug, Deserialize, JsonSchema)]
168struct ReconcileConfigArgs {
169    /// Optional session selector; omit for the current project.
170    #[serde(default)]
171    session: Option<String>,
172    /// Compute and return the semantic diff without changing the session.
173    #[serde(default)]
174    dry_run: bool,
175}
176
177#[derive(Debug, Deserialize, JsonSchema)]
178struct ServiceArgs {
179    /// The id of the target service.
180    service: String,
181    /// Optional session selector (see `list_sessions`); omit for the current project.
182    #[serde(default)]
183    session: Option<String>,
184}
185
186#[derive(Debug, Deserialize, JsonSchema)]
187struct ServiceEventsArgs {
188    /// The id of the target service, or `*` to merge events from every service.
189    service: String,
190    /// Optional session selector; omit for the current project.
191    #[serde(default)]
192    session: Option<String>,
193    /// Return events with a sequence strictly greater than this cursor.
194    #[serde(default)]
195    after_seq: Option<u64>,
196    /// Per-service cursors for `service="*"`; missing services start before their first event.
197    #[serde(default)]
198    after: Option<BTreeMap<String, u64>>,
199    /// Maximum events to return (default 50, capped at 256).
200    #[serde(default)]
201    tail: Option<usize>,
202}
203
204#[derive(Debug, Deserialize, JsonSchema)]
205struct DynamicServiceArgs {
206    /// Optional session selector; omit for the current project.
207    #[serde(default)]
208    session: Option<String>,
209    /// Dynamic service definition, clone source, lease, and idempotency key.
210    #[serde(flatten)]
211    params: micromux::DynamicServiceParams,
212}
213
214#[derive(Debug, Deserialize, JsonSchema)]
215struct ReplaceDynamicServiceArgs {
216    /// Revision currently observed by the caller.
217    expected_revision: u64,
218    /// Optional session selector; omit for the current project.
219    #[serde(default)]
220    session: Option<String>,
221    /// Replacement definition, clone source, lease, and idempotency key.
222    #[serde(flatten)]
223    params: micromux::DynamicServiceParams,
224}
225
226#[derive(Debug, Deserialize, JsonSchema)]
227struct RenewDynamicServiceArgs {
228    /// Dynamic service id.
229    service: String,
230    /// Revision currently observed by the caller.
231    expected_revision: u64,
232    /// Replacement lease; omit to renew with the session policy default.
233    #[serde(default)]
234    expires_after: Option<micromux::Lease>,
235    /// Optional session selector; omit for the current project.
236    #[serde(default)]
237    session: Option<String>,
238}
239
240#[derive(Debug, Deserialize, JsonSchema)]
241struct FindServiceArgs {
242    /// The service id or human name to locate across every running session.
243    service: String,
244}
245
246#[derive(Debug, Deserialize, JsonSchema)]
247struct LogFilterArgs {
248    /// Keep ANSI color escapes instead of stripping them. Default false (stripped) to save tokens.
249    #[serde(default)]
250    raw: bool,
251    /// Keep only entries matching this regex (applied after ANSI stripping).
252    #[serde(default)]
253    #[schemars(length(max = 65536))]
254    grep: Option<String>,
255    /// Include this many neighboring entries before and after each grep match (like grep -C).
256    /// Has no effect unless `grep` is set. Capped at 20.
257    #[serde(default)]
258    grep_context: Option<usize>,
259    /// Keep only structured-JSON log entries at or above this level
260    /// (`trace`<`debug`<`info`<`warn`<`error`<`fatal`). Entries that are not JSON with a level field
261    /// are dropped when this is set, so only use it for services that emit JSON logs.
262    #[serde(default)]
263    min_level: Option<String>,
264    /// Keep only entries at or after this time. Accepts RFC3339, Unix seconds/ms/us/ns, or relative
265    /// durations like `30s`, `2m`, `1h`, `500ms`.
266    #[serde(default)]
267    since: Option<String>,
268    /// Keep only entries at or after this Unix millisecond timestamp.
269    #[serde(default)]
270    since_unix_ms: Option<u64>,
271    /// Keep only entries containing this trace/correlation id.
272    #[serde(default)]
273    trace_id: Option<String>,
274    /// Output format. `compact` turns structured JSON records into token-efficient text plus typed
275    /// `message`/`fields`; `full` returns the cleaned logical record.
276    #[serde(default)]
277    format: logproc::LogFormat,
278}
279
280#[derive(Debug, Deserialize, JsonSchema)]
281struct LogsArgs {
282    /// The id of the target service, or `*` to merge the current visible logs from all services.
283    service: String,
284    /// Optional session selector; omit for the current project.
285    #[serde(default)]
286    session: Option<String>,
287    /// Optional run generation. Omit to read the bounded visible log stream; pass a retained run
288    /// generation to read a bounded tail from that disk-backed run.
289    #[serde(default)]
290    run_generation: Option<u64>,
291    /// Number of most recent logical log entries to return (default 200, capped at 2000).
292    #[serde(default)]
293    tail: Option<usize>,
294    #[serde(flatten)]
295    filters: LogFilterArgs,
296}
297
298#[derive(Debug, Deserialize, JsonSchema)]
299struct FollowArgs {
300    /// The id of the target service.
301    service: String,
302    /// Optional session selector; omit for the current project.
303    #[serde(default)]
304    session: Option<String>,
305    /// Optional run generation. Omit to follow the bounded visible log stream; pass a retained run
306    /// generation to page through that disk-backed run.
307    #[serde(default)]
308    run_generation: Option<u64>,
309    /// Return only log entries after this cursor. Pass the `next_seq` from the previous call to
310    /// resume without gaps or duplicates; pass 0 to start before the first entry. For the current
311    /// visible stream, omit to return its latest tail; for a retained run, omit to start at the
312    /// beginning.
313    #[serde(default)]
314    after_seq: Option<u64>,
315    #[serde(flatten)]
316    filters: LogFilterArgs,
317}
318
319#[derive(Debug, Deserialize, JsonSchema)]
320struct FollowAllArgs {
321    /// Optional session selector; omit for the current project.
322    #[serde(default)]
323    session: Option<String>,
324    /// Per-service cursors from the previous `follow_all_logs` call. Cursor 0 means "before this
325    /// service's first entry". Omit the whole map to return the latest merged tail; use
326    /// `log_cursors` before an action to capture a "since now" cursor map.
327    #[serde(default)]
328    after: BTreeMap<String, u64>,
329    /// Maximum merged entries to return (default 200, capped at 2000).
330    #[serde(default)]
331    limit: Option<usize>,
332    #[serde(flatten)]
333    filters: LogFilterArgs,
334}
335
336#[derive(Debug, Deserialize, JsonSchema)]
337struct StartArgs {
338    /// Project directory or config file to start a session for. A directory is searched upward for a
339    /// micromux config; omit to use the MCP server's working directory.
340    #[serde(default)]
341    path: Option<String>,
342}
343
344#[derive(Debug, Deserialize, JsonSchema)]
345struct ValidateConfigArgs {
346    /// Project directory or config file to validate. A directory is searched upward; omit to use
347    /// the MCP server's working directory.
348    #[serde(default)]
349    path: Option<String>,
350}
351
352#[derive(Debug, Deserialize, JsonSchema)]
353struct EnsureReadyArgs {
354    /// The id of the service to make ready.
355    service: String,
356    /// Optional session selector; omit for the current project.
357    #[serde(default)]
358    session: Option<String>,
359    /// Project directory or config file to start if no session is running.
360    #[serde(default)]
361    path: Option<String>,
362    /// Maximum seconds to wait (default 60, capped at 600).
363    #[serde(default)]
364    timeout_secs: Option<u64>,
365    /// Maximum likely-cause log entries used by follow-up diagnosis (default 5, capped at 20).
366    #[serde(default)]
367    log_limit: Option<usize>,
368}
369
370#[derive(Debug, Deserialize, JsonSchema)]
371struct WaitArgs {
372    /// The id of the target service.
373    service: String,
374    /// Optional session selector; omit for the current project.
375    #[serde(default)]
376    session: Option<String>,
377    /// Resolve only once a run with generation greater than this exists. Pass the `generation`
378    /// returned by `restart_service`/`enable_service` to wait for the new run, not the old one.
379    #[serde(default)]
380    after_generation: Option<u64>,
381    /// Maximum seconds to wait (default 60, capped at 600).
382    #[serde(default)]
383    timeout_secs: Option<u64>,
384}
385
386#[derive(Debug, Deserialize, JsonSchema)]
387struct WaitForExitArgs {
388    /// The id of the target service.
389    service: String,
390    /// Optional session selector; omit for the current project.
391    #[serde(default)]
392    session: Option<String>,
393    /// Resolve only once a run with generation greater than this exits.
394    #[serde(default)]
395    after_generation: Option<u64>,
396    /// Maximum seconds to wait (default 60, capped at 600).
397    #[serde(default)]
398    timeout_secs: Option<u64>,
399    /// Maximum compact log entries to return (default 100, capped at 1000).
400    #[serde(default)]
401    log_limit: Option<usize>,
402}
403
404#[derive(Debug, Deserialize, JsonSchema)]
405struct RestartAndWaitArgs {
406    /// The id of the target service.
407    service: String,
408    /// Optional session selector; omit for the current project.
409    #[serde(default)]
410    session: Option<String>,
411    /// Maximum seconds to wait (default 60, capped at 600).
412    #[serde(default)]
413    timeout_secs: Option<u64>,
414    /// Maximum compact log entries to return (default 100, capped at 1000).
415    #[serde(default)]
416    log_limit: Option<usize>,
417}
418
419#[derive(Debug, Deserialize, JsonSchema)]
420struct StartDynamicAndWaitArgs {
421    /// Optional session selector; omit for the current project.
422    #[serde(default)]
423    session: Option<String>,
424    /// Dynamic service definition, clone source, lease, and idempotency key.
425    #[serde(flatten)]
426    params: micromux::DynamicServiceParams,
427    /// Maximum seconds to wait (default 60, capped at 600).
428    #[serde(default)]
429    timeout_secs: Option<u64>,
430    /// Maximum compact log entries to return (default 100, capped at 1000).
431    #[serde(default)]
432    log_limit: Option<usize>,
433}
434
435#[derive(Debug, Deserialize, JsonSchema)]
436struct DiagnoseArgs {
437    /// Optional session selector; omit for the current project.
438    #[serde(default)]
439    session: Option<String>,
440    /// Maximum likely-cause log entries per diagnosed service (default 5, capped at 20).
441    #[serde(default)]
442    tail_per_service: Option<usize>,
443}
444
445#[derive(Debug, Deserialize, JsonSchema)]
446struct WaitLogArgs {
447    /// The id of the target service, or `*` to wait across all current visible service logs.
448    service: String,
449    /// Optional session selector; omit for the current project.
450    #[serde(default)]
451    session: Option<String>,
452    /// Single-service cursor. Omit to start waiting from the current end of that service's visible
453    /// log stream.
454    #[serde(default)]
455    after_seq: Option<u64>,
456    /// Cross-service cursors from `log_cursors` or `follow_all_logs.next`. Used only when
457    /// `service="*"`. Omit to start waiting from the current end of every service.
458    #[serde(default)]
459    after: BTreeMap<String, u64>,
460    /// Maximum seconds to wait (default 60, capped at 600).
461    #[serde(default)]
462    timeout_secs: Option<u64>,
463    /// Maximum matching entries to return once a match is found (default 20, capped at 2000).
464    #[serde(default)]
465    limit: Option<usize>,
466    #[serde(flatten)]
467    filters: LogFilterArgs,
468}
469
470#[derive(Debug, Deserialize, JsonSchema)]
471struct LogFilePathArgs {
472    /// The id of the target service.
473    service: String,
474    /// Optional session selector; omit for the current project.
475    #[serde(default)]
476    session: Option<String>,
477    /// Run generation to resolve. Omit to return the current retained run's file path.
478    #[serde(default)]
479    run_generation: Option<u64>,
480}
481
482/// Common session identity flattened into every mutation receipt.
483///
484/// Receipts name two known generations `previous_generation` and `run_generation`; when
485/// only the pre-action latch is known, they use `generation`.
486#[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    /// The service's last visible log seq, when it could be captured before the mutation was sent.
513    ///
514    /// Pass it to `follow_logs` as `after_seq` to read exactly the output this action caused.
515    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    /// Lifecycle timeline events for the restart (from the pre-restart generation onward), so a
552    /// failed wait explains itself (blocked dependency, backoff, spawn failure) without another call.
553    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    /// A copy-pasteable selector (`hash:<id>`) that resolves back to this exact session; pass it as
584    /// `session` on follow-up calls to avoid re-disambiguating.
585    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    /// The session's name.
598    session: String,
599    /// A copy-pasteable selector (`hash:<id>`) that targets this session.
600    session_selector: String,
601    /// The session's process id.
602    pid: u32,
603    /// The session's config path.
604    config_path: String,
605    /// The directory the session was launched in.
606    working_dir: String,
607    /// The matching service's current snapshot (state, health, run generation, command, advertised
608    /// ports), or `None` if the session did not return a snapshot for it (it stopped answering,
609    /// returned an error, or no longer supervises the service).
610    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    /// The started session's browser URLs and allocated ports.
679    #[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    /// The session's name, browser URLs, allocated ports, and routing status; absent for a
687    /// session too old to report them.
688    session: Option<micromux::SessionSummary>,
689}
690
691#[derive(Serialize, JsonSchema)]
692struct SessionEnvResult {
693    #[serde(flatten)]
694    session_ref: SessionRef,
695    /// The service whose environment this is; absent for the session's own environment.
696    #[serde(skip_serializing_if = "Option::is_none")]
697    service: Option<String>,
698    /// For a service, whether its definition changed since its running process started; the
699    /// variables are then those of the running process, not of its next run.
700    #[serde(skip_serializing_if = "Option::is_none")]
701    stale: Option<bool>,
702    /// The variables with their values, sorted by name; absent when only names are returned.
703    #[serde(skip_serializing_if = "Option::is_none")]
704    variables: Option<BTreeMap<String, String>>,
705    /// The variable names, sorted, when the values are withheld.
706    #[serde(skip_serializing_if = "Option::is_none")]
707    names: Option<Vec<String>>,
708    /// Requested names that are not set.
709    #[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    /// Retained probe attempts for the current or latest run, oldest first.
778    attempts: Vec<HealthAttempt>,
779}
780
781#[derive(Serialize, JsonSchema)]
782struct SingleServiceEventsResult {
783    #[serde(flatten)]
784    session_ref: SessionRef,
785    service: String,
786    /// Lifecycle timeline events, oldest first.
787    events: Vec<micromux::ServiceEvent>,
788    /// Highest event seq returned; pass as `after_seq` to follow incrementally.
789    next_seq: Option<u64>,
790    /// Whether older events were dropped by the tail bound or ring eviction.
791    truncated: bool,
792}
793
794#[derive(Serialize, JsonSchema)]
795struct SessionServiceEventsResult {
796    #[serde(flatten)]
797    session_ref: SessionRef,
798    service: String,
799    /// Lifecycle timeline events from every service, oldest first.
800    events: Vec<SessionServiceEvent>,
801    /// Per-service cursors; pass this map as `after` to follow incrementally.
802    next: BTreeMap<String, u64>,
803    /// Whether older events were dropped by the shared tail bound or ring eviction.
804    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    /// Ran a manual job that had not run, by restarting it.
820    RanJob,
821    Waited,
822}
823
824#[derive(Serialize, JsonSchema)]
825struct EnsureAction {
826    /// What the tool did on the caller's behalf.
827    kind: EnsureActionKind,
828    detail: String,
829}
830
831#[derive(Serialize, JsonSchema)]
832struct EnsureServiceReadyResult {
833    #[serde(flatten)]
834    session_ref: SessionRef,
835    service: String,
836    /// Every state change this call performed, in order; empty when already ready.
837    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    /// The resolved session's name.
848    session: String,
849    /// A copy-pasteable selector (`hash:<id>`) for the diagnosed session.
850    session_selector: String,
851    /// Current disk-log read capacity, when advertised by the session.
852    #[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    /// A job's run completed with exit status 0.
894    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    /// Whether the log tail was cut by the limit; fetch the rest with `follow_logs`.
918    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
1066/// A copy-pasteable session selector (`hash:<id>`) that resolves back to this exact session.
1067fn session_selector(info: &SessionInfo) -> String {
1068    format!("hash:{}", info.id)
1069}
1070
1071/// Whether `info` supervises a service matching `service` by stable id or human name. Used by
1072/// `find_service`, where discovery by human name is intended.
1073fn 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    // Older peers do not understand the targeted request. Their unbounded description contained
1093    // the complete service index, so only use the legacy roster request after that index matches.
1094    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
1119/// Enrich a bare `UnknownService` error with the sibling sessions that *do* resolve the service, so
1120/// the agent can retarget instead of guessing. Any other error passes through untouched. Best-effort:
1121/// a discovery failure leaves the error as-is rather than masking it.
1122async 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
1170/// Map a single-service control result into a tool result, enriching an `UnknownService` error with
1171/// the sibling sessions that do have the service so the agent can retarget in one hop.
1172/// Recent lifecycle events for one service, bounded by the model's retention.
1173async 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    /// Create a new server, capturing the working directory used for `Current` session resolution.
1247    #[must_use]
1248    pub fn new() -> Self {
1249        Self::with_session_start(false)
1250    }
1251
1252    /// Create a server and explicitly configure whether agents may spawn detached sessions.
1253    #[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 a session answers, this is a no-op. Otherwise let `serve` try the lifetime lock: that
1359        // keeps duplicate prevention in one place and lets it reclaim stale/bad socket files.
1360        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            // On a platform without the control transport, surface the canonical unsupported error
1369            // rather than a generic spawn failure.
1370            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    /// Shared pipeline for the three dynamic-service tools: resolve, capability pre-flight (a
1400    /// courtesy — the session enforces regardless), send, convert, wrap with the session ref.
1401    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
1422/// Captures the optional pre-mutation cursor on a disposable connection.
1423///
1424/// A timed-out read can leave a late response in the framing buffer. Keeping this observation
1425/// separate ensures neither its result nor its transport state can prevent or corrupt the
1426/// mutation.
1427async 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        // A session too old for a session-wide env file has its variables alone for its own
1531        // environment.
1532        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            // `None` lets the config's own `strict:` key decide, matching session startup.
1603            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        // Source sessions directly so a hard discovery error (e.g. unsupported platform) is
1682        // surfaced rather than masked as "no matches"; match by id or name for discovery.
1683        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        // A retained disk run defaults to a wide window (matching the session's own default); the
1732        // bounded visible stream defaults to 200.
1733        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        // When filtering, scan the whole window so matches aren't limited to the last `tail` lines.
1740        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        // A full fetched window that was filtered, or that yielded fewer entries than asked, may
1807        // hide older matches/entries beyond the scan — don't report a capped scan as complete.
1808        let mut truncated =
1809            server_truncated || (window_full && (filtering || entries.len() < requested_tail));
1810        // Tail here rather than inside shape so that a record splitting into more entries than
1811        // requested_tail is reported as truncated instead of silently dropping older records.
1812        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        // Reject before capturing cursors, mirroring restart_service's remote rejection of
1990        // disabled services (which still backstops the race where the service is disabled between
1991        // this check and the restart request).
1992        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        // Events only accompany a failed wait, mirroring the diagnosis block: on a healthy path
2237        // — including an idempotent replay of a long-lived service — the full retained history
2238        // would be noise, not evidence.
2239        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        // Confirm the session process has exited (its supervised services were stopped) before
2349        // returning, so the caller can usually start another session on the same ports. A service
2350        // that detaches from the session's process group can still outlive it — this is not a hard
2351        // guarantee every port is freed.
2352        #[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        // Cursor + gap are computed from the raw records (seq is per record), so `next_seq` advances
2419        // past filtered-out entries and following never re-fetches them.
2420        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        // The snapshot fetch first: it enriches an unknown-service error with sibling-session
2649        // pointers and gives the caller run context for the attempts.
2650        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                // A service evicted between ListServices and its GetEvents must not fail the
2724                // whole session-wide merge; skip it and let the survivors report.
2725                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        // Auto-start only for the ambient (cwd-derived) session: with an explicit selector a
3012        // NoSession must propagate, or the tool could silently start and then drive a session
3013        // for a different project than the one the caller named.
3014        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                // A start already in progress for this config has no session to wait on yet.
3027                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                // Enabling a job does not start a run: it returns to its outcome, or is pending
3109                // again, which a manual job leaves to the request below.
3110                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            // Naming a manual job that has not run asks for it to run.
3122            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    // Defined here so `#[tool_handler]` does not generate it as an `async fn` that never awaits.
3200    // Listing tools is synchronous, so the returned future is ready immediately.
3201    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        // Emit the same cache hints as `#[tool_handler]`; only protocol 2026-07-28 and later
3208        // define them.
3209        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
3237/// Compile an optional `grep` pattern, mapping a bad regex to an invalid-params error.
3238fn 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
3258/// Parse an optional `min_level`, mapping an unknown level to an invalid-params error.
3259fn 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
3370/// Serve the MCP server over stdio (JSON-RPC), blocking until the client disconnects.
3371///
3372/// # Errors
3373///
3374/// Returns an error if the stdio transport fails to initialize or the service loop errors.
3375pub 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
3384/// Waits for the session `spawned` to become reachable, and reports it, or why it did not.
3385///
3386/// The child gets [`START_READY_TIMEOUT`], and more while it reports waiting for a previous
3387/// session's cleanups or for an outdated proxy to exit, each for as long as that wait is bounded.
3388/// A child that exits gets only a short grace for a concurrent start to come up, unless it exited
3389/// because another session for the config is already starting: that session gets an ordinary
3390/// start, and is reported as still starting rather than stopped when it takes longer.
3391/// A child that is still running when the time is up is stopped, so it cannot hold the session's
3392/// ports unseen.
3393async 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        // Observe early exit before deciding whether an answering session is ours; after the
3408        // child is reaped, its pid is no longer a trustworthy ownership signal.
3409        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                // Reachable. Report `started` only when the answering process is the child this
3424                // call spawned; otherwise a concurrent start won the endpoint lock. If our child
3425                // is still around in that case, stop it so a duplicate session cannot linger.
3426                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                // A discovery error (e.g. an ambiguous selector) is caller-actionable and has
3435                // nothing to do with the child's stderr; keep the typed error.
3436                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        // A session that waits for a previous session's cleanups or for an outdated proxy to
3444        // exit is still starting, for as long as that wait is bounded.
3445        // Checking right before the deadline also catches a wait announced during the probe.
3446        if child_exit.is_none() {
3447            let reported = ReportedStart::read(&stderr_path);
3448            let now = tokio::time::Instant::now();
3449            // A cleanup that starts later can move the end of that wait out, which the session
3450            // reports again.
3451            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                // Still running but never bound — don't leak a session that may hold the ports.
3465                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
3491/// Reports the session that kept a spawned one from starting, as the spawned one's `error` names
3492/// it, once it did not become reachable within an ordinary start.
3493///
3494/// Another start for this config is in progress; it is not ours to stop.
3495fn 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            // Accept the cursor request but never answer it, modelling a wedged control read.
3588            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        /// The private runtime directory the session's control socket lives in.
3610        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        /// A server that discovers sessions only in this session's private runtime directory.
3630        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        // A port registry of the test's own, so the session never registers with the user's.
3694        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, &registry)?,
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        // A runtime directory of the test's own, so the session never shows up in the user's.
3707        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    /// Agents never type into a service: the control protocol carries PTY input and resizes for
4033    /// attached TUIs, but no MCP code may send them.
4034    #[test]
4035    fn mcp_never_sends_terminal_requests() -> eyre::Result<()> {
4036        // Spelled in halves so this test does not match itself.
4037        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    /// Boots a session whose session-wide and service env files hold secrets, and returns it
4210    /// with its selector.
4211    #[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    /// `get_session_env` arguments for the session `selector` names.
4229    #[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    /// The session's own environment, its env file included, comes back by name only unless
4239    /// the caller asks for names, and every result says which session answered.
4240    #[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        // Names only, so the env file's secret stays out of the transcript
4249        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        // Values for the requested names
4275        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    /// A service's environment comes back by name only unless the caller asks for names.
4299    #[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        // Names only, so its secrets stay out of the transcript
4308        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        // Values for the requested names, and the ones that are not set
4328        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        // An unknown service is a typed error.
4347        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        // A bundle reports the failure as its outcome, keeping what its mutation did.
4719        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    // The double-flattened bundles are exactly what these key-set pins protect: a colliding
5145    // field name in SessionRef, the ack, or the body would silently shadow on the wire.
5146    #[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                // None must be absent from the JSON, not null: the unbounded-lease shape.
5155                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        // A service whose human name differs from its id. UnknownService enrichment must match by
5247        // id only (the session resolves services by id), so a session reachable only by the *name*
5248        // is never suggested as a retarget — otherwise the caller loops back to the same session.
5249        let mut info = session_info("h", &[]);
5250        info.services = vec![ServiceBrief {
5251            id: "web".into(),
5252            name: "frontend".to_string(),
5253        }];
5254        // find_service discovery still matches either identifier.
5255        assert!(session_has_service(&info, "frontend"));
5256        assert!(session_has_service(&info, "web"));
5257        // Enrichment resolves by id only.
5258        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    /// A stand-in for a spawned session that never becomes reachable.
5714    struct StandIn {
5715        /// Whether it has exited, having written its reports at once, before the wait starts.
5716        exited: bool,
5717        /// What it writes to its stderr, and after how long.
5718        reports: Vec<(Duration, String)>,
5719    }
5720
5721    impl StandIn {
5722        /// A stand-in that keeps running and writes `reports` as it goes.
5723        fn running(reports: Vec<(Duration, String)>) -> Self {
5724            Self {
5725                exited: false,
5726                reports,
5727            }
5728        }
5729    }
5730
5731    /// Waits for `stand_in` and returns how long the wait lasted and how it ended.
5732    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            // The paused clock runs ahead of a real process, so the stand-in has exited, and
5757            // said why, before the wait starts; the exit stays observable once reaped.
5758            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    /// The line a session prints while it waits for an outdated proxy to exit.
5796    fn outdated_proxy() -> String {
5797        format!(
5798            "{} (pid 4242) to exit",
5799            micromux_proxy::WAITING_FOR_OUTDATED_PROXY
5800        )
5801    }
5802
5803    /// The line a session prints while it waits for a previous session's cleanups.
5804    fn previous_cleanup(bound: Duration) -> String {
5805        micromux::PreviousCleanupWait {
5806            services: vec!["infra".to_string()],
5807            bound,
5808        }
5809        .to_string()
5810    }
5811
5812    /// A spawned session gets the ordinary start time, and, once it says it waits for a previous
5813    /// session's cleanups or for an outdated proxy to exit, that wait plus an ordinary start, even
5814    /// when it says so at the last moment; a session that never comes up is stopped then.
5815    #[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        // Each check of the session takes a poll of 150 ms.
5820        let slack = Duration::from_secs(1);
5821        // Announced just before the ordinary start runs out
5822        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            // The proxy wait starts once the cleanups are done, and extends from there.
5841            (
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    /// A spawned session that finds another session of its config already starting exits, and the
5865    /// tool then gives that other session an ordinary start and reports it as still starting,
5866    /// rather than failing or stopping anything; one whose process is gone by then is reported
5867    /// as failed.
5868    #[tokio::test(start_paused = true)]
5869    async fn a_start_in_progress_is_reported_as_still_starting() -> eyre::Result<()> {
5870        // This test process stands in for the session that is starting.
5871        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        // A holder whose process has exited
5896        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}