Struct AppState 

pub struct AppState { /* private fields */ }

The shared, cheaply cloned handle every route works through.

Implementations

impl AppState

pub fn new(store: Arc<dyn EventStore>, factory: AgentFactory) -> Self

Builds server state over store, using factory to turn submitted definitions into live agents. Auth is off and the clock and random source are the runtime defaults until set with the with_* methods.

pub fn with_client_lease_ttl(self, ttl: Duration) -> Self

Sets how long a client-driven run’s lease stays current without the driver presenting its token again (default 60s). Past this, the run reports no attached driver. Additive and off-default; a test or a seed shortens it to make a driverless client run observable quickly, exactly as with_poll_interval shortens the stream poll. salvor serve reads it from SALVOR_CLIENT_LEASE_TTL_SECS.

pub fn with_auth_token(self, token: impl Into<String>) -> Self

Requires Authorization: Bearer <token> on every request. Without this, the server trusts its caller (the reverse-proxy posture).

pub fn with_model_executor(self, executor: Arc<dyn ModelExecutor>) -> Self

Injects the general model executor the server performs a client-driven run’s model step through. Additive and off by default (the existing new leaves it unset), so no caller that predates it changes behavior. salvor serve wires a default here; another host injects its own, exactly as it supplies its own AgentFactory.

pub fn with_tool_registry(self, registry: Arc<ToolRegistry>) -> Self

Injects the general tool registry the server performs a client-driven run’s tool step through. Additive and off by default (the existing new leaves it unset), so no caller that predates it changes behavior. salvor serve wires an empty registry here; another host injects one holding its own tools, exactly as it supplies its own AgentFactory and ModelExecutor.

pub fn with_hooks(self, clock: ClockFn, random: RandomFn) -> Self

Injects the clock and random source every Runtime this state builds uses. Deterministic tests pass fixed functions so full logs compare equal across a control run and a recovered one.

pub fn with_poll_interval(self, interval: Duration) -> Self

Sets how often the event stream polls the store for new events (default 50ms). Tests shorten it so a streamed run completes quickly.

pub fn store(&self) -> Arc<dyn EventStore>

The event store every request reads from and writes through.

pub fn auth_token(&self) -> Option<&str>

The expected bearer token, when auth is required.

pub fn poll_interval(&self) -> Duration

How often the event stream polls for new events.

pub fn model_executor(&self) -> Option<Arc<dyn ModelExecutor>>

The injected model executor, if a host wired one. None means the server cannot perform a model step and the endpoint says so.

pub fn tool_registry(&self) -> Option<Arc<ToolRegistry>>

The injected tool registry, if a host wired one. None means the server cannot perform a tool step and the endpoint says so; a wired-but-empty registry instead reports each tool as unknown_tool.

pub fn now(&self) -> OffsetDateTime

Reads the current instant from this state’s injected clock, or the real UTC clock when none was injected. This stamps envelopes the server records itself (the model-step intent and completion), the same clock edge a Runtime would use, so deterministic tests still compare logs.

pub fn runtime(&self) -> Runtime

A fresh runtime over the shared store, with this state’s clock and random source.

pub async fn build_agent( &self, definition: AgentDefinition, ) -> Result<BuiltAgent, String>

Builds a live agent from a submitted definition, through the factory.

Errors

The factory’s human message when the definition will not build.

pub fn register_agent(&self, registered: RegisteredAgent) -> String

Records a registered agent under its content hash, returning that hash.

pub fn agent(&self, hash: &str) -> Option<RegisteredAgent>

The definition registered under hash, if any.

pub fn agent_hashes(&self) -> Vec<String>

Every registered agent’s hash, sorted for a stable listing.

pub fn store_graph(&self, hash: String, graph: Graph) -> bool

Records a validated graph document under hash, returning whether it was newly stored (true) or already present (false). Re-storing the identical document is idempotent: the second call keeps the first and reports false, the graph counterpart of an agent register’s created.

pub fn graph(&self, hash: &str) -> Option<Graph>

The graph document stored under hash, if any. None is the unknown_graph case.

pub fn graph_hashes(&self) -> Vec<String>

Every stored graph’s hash, sorted for a stable listing.

pub fn run_ctx( &self, run_id: RunId, log: Vec<EventEnvelope>, ) -> Result<RunCtx, RuntimeError>

Builds a per-run RunCtx over log, with this state’s clock and random source, so the graph engine can drive a run through the same durability substrate the built-in loop uses. This is the graph counterpart of runtime: the built-in loop reaches the store through a Runtime; the graph engine reaches it through a RunCtx it drives directly, and both share the exact clock/random hooks so a deterministic test’s logs still compare equal.

Errors

RuntimeError::Replay when log is not a well-formed run history.

pub fn begin_run(&self, run_id: RunId)

Marks a run as being driven. Call this synchronously before spawning the driver task, so a stream opened at the same instant sees the run as active rather than racing the task’s first store write.

pub fn set_handle(&self, run_id: RunId, handle: JoinHandle<()>)

Records the driver task’s handle, for aborting at shutdown.

pub fn end_run(&self, run_id: RunId)

Marks a run’s drive as ended and drops its handle. The task calls this as its last act, whether it completed, parked, or errored.

pub fn is_run_active(&self, run_id: RunId) -> bool

Whether a run is still being driven by a task in this process.

pub fn lease_client_run(&self, run_id: RunId, record_prompts: bool) -> String

Records (or re-leases) a client-driven run, returning a fresh drive token. Called by the open endpoint both for a new run and for a re-open, so a resuming tab always receives a current lease and any earlier lease is superseded (the single-writer rule from Q5).

pub fn touch_client_run(&self, run_id: RunId)

Refreshes a client-driven run’s last_seen to now, the driver’s proof of life. Called by the lease gate on every guarded operation (the driver presented its token, so it is alive); a no-op for a run this process holds no lease for.

pub fn client_run_driver_live(&self, run_id: RunId) -> bool

Whether a live driver is currently attached to a client-driven run: this process holds a lease for it AND the driver presented its token within the lease TTL. A lapsed lease (the tab closed, the SDK exited) reports false — the client-driven half of the liveness evidence GET /v1/runs carries.

pub fn client_run(&self, run_id: RunId) -> Option<ClientRunLease>

The lease for a client-driven run, if this process opened one under run_id.

pub fn is_client_run(&self, run_id: RunId) -> bool

Whether run_id names a client-driven run this process opened.

pub fn abort_all(&self)

Aborts every in-flight driver task. Durability is unaffected: each event was persisted before the task moved on, so an aborted run is recoverable exactly as after a kill -9.

Trait Implementations

impl Clone for AppState

fn clone(&self) -> AppState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.