Crate mlua_swarm_server

Expand description

the server lib: axum Router + handler set. Split out as a library so it can be used from both main.rs (CLI) and integration tests.

§Endpoints

GET /v1/healthz
POST /v1/sessions / DELETE /v1/sessions (= operator attach / detach, Bearer sid)
POST /v1/tasks (= unified Flow-form entry, Operator inject supported; operator_sid explicitly pins the task to a registered Operator session, S2). Also creates a TaskRecord + RunRecord (issue #13 ID-hierarchy persistence) and echoes their ids in the response; see the tasks module doc. Always synchronous, guarded against hanging (GH #33) by a readiness precheck (503 when the launch resolves to an operator-delegate path with zero attached operators) and a tokio::time::timeout ceiling around the dispatch await (504 on expiry) — see run_flow_form’s doc comment.
GET /v1/tasks — list every persisted TaskRecord (newest first).
GET /v1/tasks/:id — a TaskRecord plus every RunRecord kicked from it.
POST /v1/tasks/:id/runs — re-kick an existing Task (new RunId, same blueprint_ref / input_ctx).
GET /v1/tasks/:id/runs/:run/steps / .../steps/:step / .../steps/:step/content — the metadata + content debug plane over a Run’s step OUTPUT (:run accepts latest or an explicit R-<hex>, projection::McpQueryAdapter); see the projection module doc. This is the operator / human-debug counterpart to the Worker axis’s context.steps pointer list on GET /v1/worker/prompt (projection-adapter ST5 — replaces the ST2/ST4 single-value GET /v1/tasks/:id/ctx).
GET /v1/runs/:id — a single RunRecord (its step_entries trace included).
POST /v1/operators / GET /v1/operators/:sid / DELETE /v1/operators/:sid / GET /v1/operators/:sid/ws (WS upgrade) — REST-like Operator login flow, Bearer-mandatory; the sole WS Operator session route. See operator_ws::login module doc.

The Enhance issue axis (/issues) lives in the issues module; callers merge build_issues_router to integrate it into the same server.

§The 3 faces of the Operator role (= registered directly on the engine SoT)

The engine stateless-executor refactor removed the three AppState registries (former HookRegistry / BridgeRegistry / OperatorRegistry); all registration now goes directly to the engine SoT via engine.register_spawn_hook / register_senior_bridge / register_operator. WSOperatorSession (in the operator_ws module) registers all three traits simultaneously under a single sid — one WS connection covers all 3 faces of the Operator role, the canonical pattern.

§`build_*` family

build_router — minimal entry (= default_registry())
build_router_with — caller provides a SpawnerRegistry and optional BlueprintStore

The engine should be started with default_layer_registry (= Engine::new_with_layers); otherwise Blueprint.spawner_hints is ignored.

Re-exports§

pub use blueprints::build_blueprints_router;
pub use blueprints::build_blueprints_router_with_refs;
pub use enhance_log::build_enhance_log_router;
pub use enhance_settings::build_enhance_settings_router;
pub use issues::build_issues_router;
pub use issues::GetIssueResponse;
pub use issues::PostIssueRequest;
pub use issues::PostIssueResponse;
pub use operator_ws::operators_create;
pub use operator_ws::operators_delete;
pub use operator_ws::operators_info;
pub use operator_ws::operators_ws_connect;
pub use operator_ws::ClientMsg;
pub use operator_ws::OperatorSessionEntry;
pub use operator_ws::ServerMsg;
pub use operator_ws::WSOperatorSession;
pub use projection::McpQueryAdapter;
pub use projection::ProjectionSource;
pub use projection::StepList;
pub use projection::StepPathQuery;
pub use projection::StepSummary;
pub use tasks::RunKickRequest;
pub use tasks::RunKickResponse;
pub use tasks::TaskDetailResponse;
pub use worker::worker_artifact;
pub use worker::worker_prompt;
pub use worker::worker_result;
pub use worker::ArtifactQuery;
pub use worker::PromptQuery;
pub use worker::WorkerResultReq;

Modules§

blueprints: HTTP surface for inspecting/registering Blueprint state (/v1/blueprints/*). HTTP surface for inspecting Blueprint state (= for debug / animation verification). /v1/blueprints/:id/head returns the head Blueprint JSON; /v1/blueprints/:id/history returns the commit-version list. Callers pass a shared Store via Arc and mount the router.
config: Server config file support (~/.mse/config.toml, CLI > file > default merge). Server config file support (~/.mse/config.toml by default).
data: /v1/data/* endpoints (v9 Big Response handling, Store-owner direct path). HTTP /v1/data/* endpoints (v9 Data path, for Big Response handling).
doctor: GET /v1/doctor — read-only startup config / Store snapshot. GET /v1/doctor — server-side infra info snapshot.
enhance_log: HTTP surface for the /v1/enhance/log axis. HTTP surface for the /v1/enhance/log axis.
enhance_settings: EnhanceSetting HTTP CRUD (/v1/enhance-settings*). EnhanceSetting HTTP CRUD (= K-V store entry + BPStore commit orchestration).
issues: HTTP surface for the Enhance issue axis (/v1/issues*). HTTP surface for the Enhance issue axis (current design).
operator_ws: WebSocket Operator Callback IF (/v1/operators*).
projection: GET /v1/tasks/:id/runs/:run/steps* (the metadata + content debug plane over a Run’s step OUTPUT — McpQueryAdapter, a server-side mlua_swarm::core::projection::ProjectionAdapter impl reading through the Data-plane OutputStore with a persisted RunRecord.result_ref fallback). See the module doc for how this relates to operator_ws::session’s in-flight FileProjectionAdapter hook and worker’s Worker-axis context.steps pointer assembly. McpQueryAdapter — server-side [ProjectionAdapter], and the REST hierarchy that serves a Run’s step OUTPUT as metadata + content (projection-adapter ST5’s HTTP debug plane — replaces the ST2/ST4 GET /v1/tasks/:id/ctx single-value endpoint / ProjectionResponse).
tasks: HTTP surface for the Task/Run persistence axis (issue #13 ID hierarchy; GET /v1/tasks, GET /v1/tasks/:id, POST /v1/tasks/:id/runs, GET /v1/runs/:id). POST /v1/tasks itself stays in this module (it is the entry point tasks_start shares with the flow-eval path) — see the tasks module doc for the split rationale. HTTP surface for the Task/Run persistence axis (issue #13 ID-hierarchy reconciliation: Blueprint → Task → Run → Step → Attempt).
worker: /v1/worker/* endpoints (SubAgent self-fetch path). HTTP /v1/worker/* endpoints (SubAgent self-fetch path).

Structs§

ApiError: Uniform error response type for the handlers in this module. Converts to a JSON {"error": message} body with the given status via IntoResponse.
AppState: Shared axum handler state for the whole router. Cloned per-request (all fields are Arc/cheap-clone), constructed once in build_router_with_ws_factory.
OperatorReq: Operator inject sub-schema of TaskLaunchRequest (kind / id / spawn_hook_id / senior_bridge_id / operator_backend_id / per_agent_kinds). pub for the same cross-crate schema-generation reason as TaskLaunchRequest.
SessionStore: In-memory session map backing /v1/sessions attach/detach.
StatusResponse: Response body for GET /v1/status (issue #35 ST4 — lifecycle occupancy guard). Cheap-to-poll summary of “is it safe to kill this server right now”.
TaskLaunchReply: tasks_start’s reply — a TaskLaunchResponse plus the HTTP status it rides out on (200 OK for the synchronous path, 202 Accepted for a detached launch, GH #37). A tuple struct with the body first so handler-level tests keep their established .0 access to the response body regardless of which path produced it.
TaskLaunchRequest: /v1/tasks POST schema. Uses the flow-eval path and supports Operator inject (kind / spawn_hook / senior_bridge). Expressing a one-shot task as a 1-Step Blueprint is the only correct model.
TaskLaunchResponse: /v1/tasks POST response body. pub for the same cross-crate schema-generation reason as TaskLaunchRequest.

Enums§

TtlSource: Which layer of the TTL cascade (request body → BP metadata → server default) resolved TaskLaunchResponse::effective_ttl_secs. pub for the same cross-crate schema-generation reason as TaskLaunchRequest.

Functions§

build_router: Minimal entry point: builds a router with default_registry and no BlueprintStore (Inline-only mode) or ws_operator_factory.
build_router_full: 8-argument variant of build_router_with_ws_factory_and_output. Passing base_url = Some(...) (e.g. "http://127.0.0.1:7777") makes WSOperatorSession render the actual server bind into the Spawn directive’s base_url line, so the receiving operator can copy the frame straight into a SubAgent prompt (issue #8). None preserves the historical fallback (<check with mse_doctor> placeholder). task_store / run_store swap the default InMemoryTaskStore / InMemoryRunStore (issue #13 ID-hierarchy persistence) for a caller-supplied backend (SqliteTaskStore / SqliteRunStore, for instance); None preserves the process-volatile default. sync_timeout_secs is the server-wide fallback ceiling for the POST /v1/tasks synchronous launch await (GH #33 Guard 2) — see AppState::sync_timeout_secs / run_flow_form’s doc comment.
build_router_with: Build form where the caller supplies a registry and an optional BlueprintStore. The Operator callback path (= external HTTP / WS callers acting as an Operator) must be pre-registered via engine.register_* (= the engine is the SoT). See the operator_ws module doc and OperatorInfo (engine-side ctx.rs) for details.
build_router_with_ws_factory: 4-argument variant of build_router_with. Passing ws_operator_factory = Some(arc) causes each WS connect to auto-register a new WSOperatorSession under its sid name with the factory (= a kind=operator AgentDef with operator_ref: <sid> can then bind to the WS client backend). Callers are expected to also install the same Arc into the SpawnerRegistry via reg.register::<OperatorSpawnerFactory>(arc.clone()).
build_router_with_ws_factory_and_output: 5-argument variant of build_router_with_ws_factory. Passing output_store = Some(arc) swaps the default InMemoryOutputStore for a caller-supplied backend (a SqliteOutputStore, for instance). None preserves the historical behaviour (fresh in-memory store per call).
default_layer_registry: Default LayerRegistry for the server. Hint keys:
default_registry: Default registry = Subprocess + RustFn (baseline identity worker pre-baked) + empty Operator factory.
default_registry_with_enhance_flow: Opt-in registry that merges default_registry with the enhance flow (Lua factory + AgentBlock factory).