Crate salvor_server 

Salvor control plane: an HTTP and server-sent-events server over the durable runtime.

This crate is a thin network surface: submit an agent definition, start a run, stream its events, resume or recover or resolve it, list and inspect runs. Durability stays where it belongs, in the one Rust process that owns the event store; the server holds handles and constructs a salvor_runtime::Runtime per request, so nothing about a run lives in the process that a restart would lose. Clients (the v0.3 Python and TypeScript SDKs, the dashboard) are thin because the guarantees are not theirs to keep.

The HTTP contract, every route and shape and the event framing, is the deliverable those clients build against. It is specified in API.md alongside this source, and each handler module documents its own routes.

Shape of the crate

• AppState is the shared handle: the store, the agent registry, the run-driver bookkeeping, and the AgentFactory seam that turns a submitted definition into a live agent.
• build_router wires the routes and the auth layer; serve binds and runs them.
• dispatch holds the state-to-verb mapping shared with the CLI, so the two surfaces agree on what a run’s state means.
• The handler modules (agents, runs, sse) own their endpoints; error::ApiError is the one error envelope they all return.

Auth

One optional shared-secret bearer, a single-tenant posture. With a token set on the state, every route requires Authorization: Bearer <token>; without one, the server trusts its caller and a reverse proxy owns auth. No user model, no RBAC.

Re-exports

pub use dispatch::Disposition;

pub use dispatch::ResumeKind;

pub use dispatch::classify;

pub use error::ApiError;

pub use executor::LlmModelExecutor;

pub use executor::ModelExecutor;

pub use executor::ModelStream;

pub use state::AgentDefinition;

pub use state::AgentFactory;

pub use state::AppState;

pub use state::BuildFuture;

pub use state::BuiltAgent;

pub use state::ClientRunLease;

pub use state::DefFormat;

pub use state::RegisteredAgent;

pub use tool_registry::ToolRegistry;

Modules

agents

The agent-definition endpoints: register a definition, list registered ones, and read one back.

auth

Bearer-token auth, the whole of it.

client_runs

The client-driven run surface: open or resume a run, read its log, and the generic guarded append for control and deterministic-context events.

dispatch

The one place that maps a run’s derived state to the verb that continues it. Both the CLI’s resume command and the server’s resume endpoint call classify, so the two surfaces cannot drift on what a given state means.

error

ApiError: the one error type every handler returns, and the JSON envelope it serializes to.

executor

The model-executor seam: the general injection point a host supplies so the server can perform a model call on a client-driven run’s behalf.

graph

The graph control plane: submit and inspect graph documents, start graph runs, and project a graph run’s per-node progress.

json

Turning derived run state into the JSON shapes the control-plane returns.

runs

The run endpoints and the task that drives a run server-side.

sse

GET /v1/runs/{id}/events: the event stream. This is the control plane’s headline feature, so its framing and its cursor are spelled out here.

state

AppState: the shared handle every request works through, plus the AgentFactory seam that turns a submitted definition into a live agent.

tool_registry

The tool-registry seam: the general injection point a host supplies so the server can perform a tool call on a client-driven run’s behalf.

Functions

build_router

Builds the control-plane router over state, with the bearer-auth layer in front of every route.

serve

Serves the control plane on listener until the process ends.