Skip to main content

Crate rusty_agent_server

Crate rusty_agent_server 

Source
Expand description

§rusty-agent-server

The network face of rusty_agent_runtime: an axum-based HTTP + SSE server implementing a pragmatic Agent-Protocol subset (see docs/rusty-server-design.md). The server ships as a library — users build their graphs, register them in a GraphRegistry, and call serve (or router to embed the routes in a larger application):

use rusty_agent_runtime::prelude::*;
use rusty_agent_server::{serve, GraphRegistry, ServerConfig};

let mut registry = GraphRegistry::new();
registry.register("my_agent", graph, spec);

let config = ServerConfig::new(
    "127.0.0.1:8080".parse().unwrap(),
    "./data/checkpoints",
);
serve(registry, config).await

§Endpoint inventory (v0.5)

EndpointPurpose
GET /okliveness
GET /infoservice version + registered graphs and their channels
POST /threadscreate a thread bound to a registered graph
POST /threads/{id}/forktime travel: copy the thread’s checkpoint history (full or up to checkpoint_id) into a new thread
GET /threads/{id}/statelatest checkpoint as {values, next, checkpoint} (the checkpoint ref carries its pinned policy_version, R0.8 wave 4)
POST /threads/{id}/statewrite a new checkpoint (update_state analog; as_node is accepted for LangGraph compatibility but not recorded; optional enqueue: [...] submits tasks atomically with the checkpoint through the R0.6 wave-2b transactional outbox — one transaction on Postgres, outbox-first best-effort ordering on the JSON-file backend)
POST /threads/{id}/historycheckpoint list, newest first, limit/before
POST /threads/{id}/runsbackground run: 202 + run_id
POST /threads/{id}/runs/waitblocking run: terminal result as JSON
POST /threads/{id}/runs/streamrun with SSE streaming (updates/values/messages/metadata/error/end); a fresh run starts a new frame sequence, so Last-Event-ID is ignored here
GET /runs/{id}/streamattach to an existing run’s SSE stream: replay honoring Last-Event-ID, then live frames
GET /runs/{id}/eventsFlight Recorder: the run’s journaled RunEvents as {run_id, events, complete} (snapshot flushed per checkpoint boundary and at run completion; persisted under {store_path}/journals/ or the server_journals table; fetchable by run id even after the live run record is evicted or the process restarts)
GET /runs/{id}/fixtureFlight Recorder: download the run as a portable ReplayFixture bundle (journal + graph topology hash + final checkpoint) for CI replay
POST /runs/replayFlight Recorder: re-drive a journaled run against its registered graph and verify the replayed evidence → {run_id, verified, expected_events, actual_events, first_divergence} (422 when the graph is not registered in this process or the journal carries recorded effect calls)
GET /runs/diff?base=&branch=Flight Recorder: structural diff of two runs’ journals (core’s BranchDiff shape: first_divergent_seq, added/removed events, per-step channel diffs, token/cost totals)
DELETE /threads/{id}/runs/{run_id}rollback: delete a finished run’s checkpoints (JSON-file checkpointer only; 409 on Postgres)
GET /runs/{run_id}run status polling (plus output/error/interrupt once terminal)
POST /assistantscreate a named graph alias with config metadata
GET /assistants / GET /assistants/{id}list / fetch assistants
POST /assistants/{id}/archive / POST /assistants/{id}/restorereversibly retire or return an assistant using an expected-active-version guard; archived assistants retain their immutable lineage and history but reject new runs
GET /assistants/{id}/versionslist the bounded immutable configuration lineage and active serving pointer
POST /assistants/{id}/versionsstage an immutable child version against the exact active base (never activates it)
GET /assistants/{id}/versions/{version_id}fetch one exact immutable configuration version for review
POST /assistants/{id}/versions/{version_id}/activateatomically activate or roll back to a reviewed version using an expected-active guard
POST /cronsschedule recurring runs (interval secs or 5-field cron expr)
GET /crons / DELETE /crons/{id}list / delete crons
POST /triggerscreate an event-driven trigger: name, target (assistant or thread), action (start_run / resume_thread / send_message), {{event.*}} input template, per-trigger webhook secret, optional debounce window
GET /triggers / GET /triggers/{id} / PATCH /triggers/{id} / DELETE /triggers/{id}trigger registry (tenant-scoped)
POST /triggers/{id}/webhooksigned event ingress: HMAC-SHA256 over the raw body, X-Rusty-Signature: sha256=<hex>, constant-time compare; 401 unsigned/invalid. Not behind the API-key layer — the signature is the credential and resolves the owning tenant
GET /triggers/{id}/eventsthe trigger’s event log (payload hash, action, run id, status), newest first
GET /triggers/{id}/dead-letterfailed events, inspectable and replayable
POST /triggers/{id}/events/{event_id}/replayre-execute a logged event immediately (the replay is itself logged)
PUT /store/{ns}/{key}upsert a JSON value in a namespace (201 create, 200 replace)
GET /store/{ns}/{key} / DELETE /store/{ns}/{key}fetch / delete one item
GET /store/{ns}list a namespace’s items
POST /tasksR0.6 durable task queue: enqueue a task {kind, payload, pool?, max_attempts?, idempotency_key?, worker_version?} → 201 {task_id, deduplicated} (200 + deduplicated: true when the idempotency key already names a live task in this tenant; 429 quota_exceeded when the tenant is over its wave-3 task quota — see ServerConfig::with_task_quota)
POST /tasks/outboxR0.6 wave 2b: enqueue through the transactional outbox (same payload as POST /tasks, same quota gate) → 202 {task_id, deduplicated}; the relay publishes the task into the queue within one poll interval, at-least-once, deduped on the idempotency key
POST /tasks/claimR0.6: claim the oldest claimable task {worker_id, pools?, worker_version?, lease_ms} → 200 {task} with a fresh lease, 204 when nothing is claimable. Wave 3: pools at their configured concurrency limit (ServerConfig::with_pool_limit) hand out nothing, and a task pinned with worker_version is leased only to a worker advertising that exact version
GET /tasks/metricsR0.6 wave 3: the autoscaling signals, tenant-scoped — per-pool queue depth, live leases, lease saturation against the configured limit, and oldest-visible-task age. Metrics, not a mechanism: the autoscaler is the operator’s
POST /tasks/{id}/heartbeatR0.6: extend the held lease {worker_id, lease_ms} → {lease_expires_at}; 409 when the lease is lost
POST /tasks/{id}/completeR0.6: settle the held lease {worker_id, result, receipt?} → updated task record; 409 when the lease is lost. The optional receipt (wave 2b: {provider, provider_id, idempotency_key, task_id?}) is the worker’s report of an idempotent effect’s provider confirmation; the server journals it into the task’s run as an effect_receipt event
POST /tasks/{id}/failR0.6: record a failed attempt {worker_id, error_class, message, retryable} → {requeued, next_attempt_at, dead, escalation} (backoff + jitter requeue, or dead-letter); 409 when the lease is lost. R0.7 wave 2: a failed agent turn (non-cancelled) also feeds the agent’s supervision policy — escalation reports where the escalation notice landed when the restart intensity was exceeded
GET /tasks/{id}R0.6: the task record (404 unknown/cross-tenant)
GET /tasks?status=…R0.6: the tenant’s tasks, oldest first; status=dead is the DLQ listing
POST /agentsR0.7 Agent Fabric (wave 1): register an agent {agent_id, manifest, metadata?} — the manifest is a core CapabilityManifest (agent_kind, manifest_version, accepts, …) → 201; 409 when the id is taken
GET /agents / GET /agents/{id}R0.7: list the tenant’s agents / fetch one registration (404 unknown/cross-tenant)
POST /agents/{id}/mailboxR0.7: send a message into the agent’s mailbox {kind, payload, idempotency_key?, …} → 201 {task_id, deduplicated} (200 when the key already names a live message); 400 when the manifest’s accepts does not declare the kind; same quota gate as POST /tasks
GET /agents/{id}/statusR0.7: the agent’s activation lease plus mailbox gauges (queued / in_flight / dead message counts)
POST /agents/{id}/activateR0.7: claim the agent’s single activation lease {worker_id, lease_ms} → 200 {owner, fencing, lease_expires_at}; 409 + the current lease when another host holds it live (expired leases are stolen, fencing bumped)
POST /agents/{id}/activate/heartbeatR0.7: renew the held activation {worker_id, fencing, lease_ms}; 409 on fencing loss
POST /agents/{id}/activate/releaseR0.7: drop the held activation {worker_id, fencing} so a draining host’s replacement activates promptly; 409 on fencing loss
POST /agents/{id}/mailbox/nextR0.7: claim the oldest queued mailbox message as one turn {worker_id, fencing, lease_ms} → 200 {task} leased to the worker, 204 when empty or a turn is already in flight (one message at a time per agent is server-enforced), 409 when the activation lease is not held. The turn settles through the ordinary `/tasks/{id}/heartbeat
GET /agents/{id}/supervisionR0.7 wave 2: the agent’s supervision evidence — declared policy, latches, full attempt history, and the journaled SupervisionEvent / AgentExit events of its supervision journal (integrity re-verified on read)
POST /agents/{id}/cancelR0.7 wave 2: cancel the agent’s outstanding mailbox traffic — queued/retry-scheduled messages go terminal-cancelled, the leased turn keeps its lease with cancel_requested set — and journal an AgentExit; idempotent (200 with empty lists when nothing is outstanding)
POST /agents/{id}/restartR0.7 wave 2: the operator’s manual restart — records a manual_restart supervision attempt, clears the escalation/deadline latches, and journals the event so the agent’s next turn runs fresh
POST /teams/{team_id}/cancelR0.7 wave 2: cancel every agent registered with the team_id label, member by member with the agent-cancel semantics; 404 when no tenant agent declares the team
POST /memoryR0.8 Rusty Learn (wave 1): write a governed memory record {kind, scope, content, author, key?, tags?, priority?, confidence?, written_at?, valid_from?, valid_until?, expires_at?, supersedes?, evidence?, run_id?, parent?} → 201 {memory_id, created, record} (200 + created: false when the content address is already stored — writes are idempotent by construction). Gates: run scope is runtime-only (400); agent scope requires the agent registered with StateScope::Private declared (404 / 403); tenant scope id must be the caller’s tenant (403); confidence defaults to 1.0 for human authors and is required otherwise (400). With run_id, the write is journaled into that run as a memory_write event (best-effort)
GET /memory/{memory_id}R0.8: fetch one record by content address (404 unknown/cross-tenant); artifact-spilled bodies are re-inlined, so the served record is self-contained
POST /memory/queryR0.8: structured retrieval — the MemoryQuery filters plus optional budget, run_id, parent. as_of resolves at read time. With budget, answers the deterministic token-bounded MemoryAssembly (422 when a hard budget overflows); without, the rank-ordered records. With run_id (budget required), the read is journaled into that run as a memory_read event (best-effort)
POST /memory/correctionsR0.8 (wave 2): submit a human correction {correction_id, author, target, corrected, scope, rationale?, run_id?, parent?} → 201 {correction_id, attribution, candidate, memory_id, created, record, superseded, example_id}. Author attribution is mandatory (validated at deserialization). Run scope adopts directly; agent scope or wider yields an attributed candidate (candidacy: pending, queryable via candidates_only). A run_event target additionally yields an example-kind record — the journaled input plus the corrected behavior — journaled into the corrected run through the memory-write seam; a memory target inherits the target’s key, and same-key correction writes auto-supersede the prior record
POST /memory/consolidateR0.8 (wave 2): enqueue a consolidation as a durable memory_consolidation task {scope, memory_ids, distiller, key?, tags?, priority?, pool?, run_id?, parent?} → 201 {task_id, deduplicated, kind} (deduped on scope + sorted source set). The claiming worker owns the distillation semantics and writes the summary record through the governed write path with the sources in evidence.source_memory_ids (which supersedes them) and the task payload’s written_at; the task settles through the unchanged lease protocol
POST /memory/conflictsR0.8 (wave 2): the conflict review listing {scope?} → {conflicts: [{scope, key, memory_ids, overlap}]} — live same-key records with overlapping validity and contradictory content. Flags only; nothing is resolved
POST /memory/forgetR0.8 (wave 2): erase one record {memory_id, reason, run_id?, parent?} → 200 {forgotten, invalidated, tombstone}. Real deletion; dependent summaries are invalidated (deleted) transitively; a metadata-only memory_forget tombstone is journaled into the named run (best-effort)
POST /memory/forget_scopeR0.8 (wave 2): erase every record at a scope address {scope, reason, run_id?, parent?} → 200 {forgotten, invalidated, tombstones} — one tombstone per forgotten record; idempotent (empty scope → 200 with empty lists); tenant scope is self-only (403)
POST /learn/candidatesR0.8 (wave 3): register a distilled candidate {candidate, run_id, parent?} → 201 {candidate_id, created, record} (200 + created: false when the content address is already stored — creation converges). The address is verified (422); the candidate_created event is journaled into run_id’s journal before the store write — hard-fail: an unresolvable run stops the transition (404)
GET /learn/candidates / GET /learn/candidates/{id}R0.8 (wave 3): the tenant’s candidates (sorted by id) / fetch one record (404 unknown/cross-tenant)
POST /learn/candidates/{id}/evaluateR0.8 (wave 3): drive the configured CandidateEvaluator {request, run_id, parent?} → 200 {candidate_id, status, evaluation}; 409 when no evaluator is configured or the lifecycle forbids re-evaluation; 422 when the evaluation fails or violates the seam contract (it must name this candidate and the request’s dataset version)
POST /learn/candidates/{id}/promoteR0.8 (wave 3): run the promotion gate {run_id, approval?, tag?, parent?} → 200 {candidate_id, status, receipt, pointer}. 403 on approval failures (out-of-envelope promotion needs an ApprovalToken scoped to the candidate’s promotion effect id — non-transferable), 422 on evidence failures, 409 when the candidate is not evaluated. The status flip and the version-pointer move are one store transition. R0.11 (wave 1): the optional tag moves the pointer on the environment-tagged surface (prompt:system@prod) through the unchanged machinery; absent is the untagged, pre-R0.11 behavior
POST /learn/candidates/{id}/rollbackR0.8 (wave 3): re-point the surface to the displaced version {run_id, cause, tag?, parent?} → 200 {candidate_id, status, receipt, pointer}; 409 when the candidate is not promoted or the pointer no longer serves it. Byte-exact: the pointer’s to is the promotion’s recorded previous, and candidates are content-addressed — the restored version is the version that served. R0.11 (wave 1): tag rolls back the tagged surface’s pointer
GET /learn/versionsR0.8 (wave 3): the tenant’s version pointers, sorted by surface
POST /registry/artifactsR0.11 (wave 1): declare a registry artifact {family, name, owner} → 201 {surface, created, artifact} (200 converged on an identical re-declaration; 409 when the surface is taken under a different family or owner; 422 on a name outside the naming rules). The artifact is an index over the candidate pipeline — a commit is a candidate, never a fork
GET /registry/artifacts?family= / GET /registry/artifacts/{family}/{name}R0.11 (wave 1): the tenant’s artifacts (optionally one family’s, sorted by surface) / fetch one (404 unknown/cross-tenant)
POST /registry/artifacts/{family}/{name}/commitsR0.11 (wave 1): commit a candidate {candidate_id, committed_at?} → 200 {surface, committed, commit, commits} (200 + committed: false when already committed; 404 unknown artifact/candidate; 422 family or surface mismatch; 409 concurrent commit)
GET /registry/artifacts/{family}/{name}/commitsR0.11 (wave 1): the history walk — commits oldest first, joined with each candidate’s status and author
GET /registry/artifacts/{family}/{name}/diff?from=&to=R0.11 (wave 1): the diff view between two committed versions, computed on read (never stored) — line diff for prompts, structural canonical-JSON diff for JSON families; 422 when either candidate is not committed to this artifact
POST /policy/versionsR0.8 (wave 4): register an immutable executor policy body {version?, policy} → 201 {version, record} (200 converged when the version already names exactly this body; 409 when it names a different one — registry immutability; 400 invalid version). Without version, the content-derived policy-{hash12} name is minted. The reserved static-v0 floor is never registerable
GET /policy/versions / GET /policy/versions/{version}R0.8 (wave 4): the tenant’s registered policy bodies (sorted by version) / fetch one (404 unknown/cross-tenant; the floor resolves as a synthetic record)
POST /policy/activationsR0.8 (wave 4): move the active-version pointer {version} → 200 {version, active}; 422 when the version is not registered (the floor is always activatable — reverting to pre-learning behavior needs no candidate)
GET /policy/activeR0.8 (wave 4): the tenant’s active policy — the last activation’s body, or the floor when the registry never moved
GET /policy/epochsR0.8 (wave 4): the epoch history — each activation’s reign window plus the admission bindings recorded inside it (and the implicit floor epoch covering pre-activation bindings)
GET /policy/driftR0.10 (wave 4): the drift check — the named (default active) candidate-derived version’s journaled production decisions measured against the twin baseline it was promoted on; 422 for the floor and API-registered bodies (no promotion baseline)
POST /capsulesR0.9 Rusty Capsules (wave 1): register an immutable capsule manifest {manifest} → 201 {capsule_id, record} (200 converged when the content address already names exactly this manifest; 409 when the (name, version) pin is claimed by a different address — registry immutability; 422 when the manifest fails validation). The manifest’s content address is derived; callers never mint ids
GET /capsules / GET /capsules/{id}R0.9 (wave 1): the tenant’s registered capsule manifests (sorted by content address) / fetch one (404 unknown/cross-tenant)
POST /capsules/resolveR0.9 (wave 1): resolve a run’s capsule pins {pins: {name: version}, run_id, parent?} → 200 {resolutions} — each pin’s stored manifest re-derives its content address before answering (a tampered record fails closed, 422; an unknown pin is 404), and one capsule_resolved event per pin is journaled into run_id’s journal (hard-fail: an unresolvable run is 404). R0.9 wave 2 adds the optional budget field and, with the capsules feature, the admission composition: Cedar decides the admission and each declared grant (403 on refusal, one journaled capsule_denied per forbidden grant), overlays intersect the effective grants, and budgets compose (422 on a token/cost overspend)
POST /capsule_policies/versions / GET /capsule_policies/versions / GET /capsule_policies/versions/{version}R0.9 (wave 2, feature capsules): register an immutable Cedar policy body {policy_text, version?} → 201 {version, record} (200 converged; 409 when the version names a different body; 422 unparseable) / list the tenant’s bodies (sorted by version) / fetch one (404 unknown/cross-tenant). Without the feature: 503 capsule_policy_unavailable
GET /capsule_policies/active / POST /capsule_policies/activeR0.9 (wave 2, feature capsules): the tenant’s active policy body (404 in the unconfigured posture) / move the active-version pointer {version} → 200 {active} (422 unregistered version); the move eagerly refreshes the revocation cache. Without the feature: 503 capsule_policy_unavailable
POST /capsules/overlays / GET /capsules/overlays / GET /capsules/overlays/{name}R0.9 (wave 2, feature capsules): attach (or replace) a tenant overlay {overlay} → 201 new / 200 replaced (403 when the active policy refuses a widening attach; 422 invalid) / list the tenant’s overlays (sorted by name) / fetch one (404 unknown/cross-tenant). Without the feature: 503 capsule_policy_unavailable
GET /runs/{id}/receiptR0.9 (wave 3): the run’s signed RunReceipt — minted on first request over the run’s reverified journal (manifest and executor policy read back from its last checkpoint header), then stored and served while the journal’s head stands; a run whose journal advanced gets a fresh receipt. 409 when nothing is persisted yet (queued or pre-checkpoint); 404 unknown/cross-tenant
POST /receipts/verifyR0.9 (wave 3): verify caller-supplied evidence {snapshot, receipt, key_id?} → 200 with the typed VerifiedRun summary, or 422 receipt_verification_failed naming the mismatched component (journal_head / manifest_digest / effect_ledger / denials_ledger / capsule_resolutions / capsule_policies / signer_key_id / signature). The public key resolves from the deployment’s key history by key_id (default: the receipt’s signer); an unknown key id is 404
GET /receipt_keysR0.9 (wave 3): the deployment’s signing-key history (public keys, registration and retirement instants) plus the active key id — what an auditor needs to verify receipts offline
POST /receipt_keys/rotateR0.9 (wave 3): rotate the signing key → 201 {previous_key_id, key_id, public_key, event_id}; the new key id is journaled as a signing_key_rotated event in the deployment’s receipts journal, and receipts signed by the retired key keep verifying against the history
GET /receipt_keys/journalR0.9 (wave 3): the deployment’s key-lineage journal — the chained signing_key_rotated events, integrity re-verified on read
POST /mcpR0.9 (wave 4): the MCP bridge (pinned revision 2025-03-26) — every registered graph as one tool. initialize / ping / notifications/* / tools/list (tool schemas derived from each graph’s state spec: append channels are arrays, deep-merge channels objects) / tools/call (runs the graph on a fresh thread; plain-JSON answer, or SSE notifications/progress + the final response when the request accepts text/event-stream; a mid-stream disconnect cancels the run). JSON-RPC errors in the envelope with HTTP 200; notifications answer 202
GET /.well-known/agent-card.jsonR0.9 (wave 4): the A2A agent card (pinned spec 0.3.0), derived from the registry on every read — one skill per registered graph; deterministic, no timestamps
POST /a2aR0.9 (wave 4): the A2A JSON-RPC task surface — message/send (enqueue a durable task, kind = "a2a", idempotent on messageId; a capsule data part {"capsule": {name, version}, "input"} routes to the in-process executor over the a2a-capsule pool, plain messages queue on a2a for external workers) / message/stream (the same plus SSE status events) / tasks/get / tasks/cancel. The context id maps to one Flight Recorder journal (a2a-{tenant}-{contextId}), so capsule executions leave their evidence on the native /runs/{id}/events and /fixture endpoints
PUT /capsules/{id}/blobR0.9 (wave 4): upload the component bytes a registered manifest’s build_digest commits to (raw body) → 201 {capsule_id, sha256, bytes}; 404 unknown capsule, 422 digest mismatch, 409 different bytes under a taken address (registry immutability over bytes)
POST /connectionsR0.11 (wave 3): register a connection {provider, subject?, scopes, token} → 201 {connection}; the token material is envelope-encrypted before it touches the store and the registration journaled — the bytes never travel beyond the broker. Wave 4: {provider, subject?, scopes, authorization_code} exchanges the code through the deployment’s OAuth provider (ServerConfig::with_oauth_provider; 409 when none is configured) and seals the grant — the two credential paths are mutually exclusive (422)
GET /connectionsR0.11 (wave 3): the tenant’s connection records (metadata only — sealed material never leaves the broker), sorted by id
GET /connections/healthR0.11 (wave 4): the tenant-wide health surface — every connection with its status and health counters, sorted by id
GET /connections/{id}R0.11 (wave 3): one connection record → 200 {connection}; 404 unknown/cross-tenant
POST /connections/{id}/consentR0.11 (wave 3): record a consent act {scopes?, token?} (one required, 422 otherwise) → 200 {connection, journaled}; a scope-set change journals connection_consented, material-only connection_refreshed; re-recording the same fact converges without a second event. Re-activates a needs_reauth connection — this is the re-auth path. Wave 4: authorization_code is a third, mutually exclusive material path — exchanged through the OAuth provider and sealed
POST /connections/{id}/revokeR0.11 (wave 3): revoke {reason?} → 200 {connection, event_id?} (re-revocation converges with no event_id); outstanding handles fail at their next use with a typed, journaled connection_revoked denial
DELETE /connections/{id}R0.11 (wave 3): revoke-then-erase → 200 {deleted: true}; the sealed material is really deleted, and resolution fails closed unknown_connection thereafter
GET /connections/{id}/healthR0.11 (wave 3): the connection’s status and health counters (last failure class, consecutive failures, last refresh)
GET /broker/journalR0.11 (wave 3): the deployment’s broker evidence chain — registrations, consents, refreshes, revocations, issuances, uses, denials, and (wave 4) connection_needs_reauth terminal-refusal transitions, integrity re-verified on read (the receipt_keys/journal precedent for a second control plane)
POST /deployments/revisionsR0.12 (wave 3): register an immutable, content-addressed revision {graph, assistant?, source_environment, surfaces, author} → 201 {created, revision} (200 + created: false converged on an identical re-registration — the content address makes it the same declaration; 404 unknown graph/assistant or undeclared source environment; 422 a surface with no active version there to freeze, or a declaration outside the contract). The pins freeze the source environment’s ACTIVE pointers; the server computes the graph’s current topology hash at registration. The revision_registered act journals before the store write (hard-fail)
GET /deployments/revisions / GET /deployments/revisions/{id}R0.12 (wave 3): the tenant’s revisions (sorted by id) / fetch one (404 unknown/cross-tenant)
POST /deployments/environmentsR0.12 (wave 3): declare an environment {name, gate?, approval_required, author} → 201 {created, environment} (200 + created: false converged on an identical re-declaration; 409 a different rule under the same name — declarations are immutable; 400 invalid name). Gate and approval declarations are enforced from wave 4 (below). The environment_declared act journals before the store write (hard-fail)
GET /deployments/environments / GET /deployments/environments/{name}R0.12 (wave 3): the tenant’s environments (sorted by name) / fetch one (404 unknown/cross-tenant)
POST /deployments/environments/{name}/promoteR0.12 (wave 3): move the environment’s deployment pointer to a registered revision {revision_id, author, approval?} → 201 {applied, journaled, event_id, pointer} (200 {applied: false} on a converged re-issue — no journal noise; 404 undeclared environment or unknown revision; 422 a revision failing its content-address check; 409 a lost race after exactly one rebuild — re-read and retry, never a lost move). Journal-then-pointer under the chain lock; the store’s CAS arbitrates the move. Wave 4: a declared gate runs first — the decision journaled, allowed or refused (422 a blocking verdict, 409 an unavailable gate — the fail-closed read); an approval-required environment then demands a token scoped to this revision’s promotion effect id (403 otherwise — a token minted for any other revision admits nothing here)
POST /deployments/environments/{name}/rollbackR0.12 (wave 3): re-point the environment byte-exactly at what served before {author, cause} → 201 with the moved pointer (200 converged; 400 empty cause — a rollback names its cause; 404 undeclared environment; 409 nothing serves, or no journaled history to restore to). The target re-derives from the chain’s transition replay — the immutable revision that served, never a reconstruction
GET /deployments/environments/{name}/pointerR0.12 (wave 3): the environment’s serving picture (404 undeclared environment, or nothing ever promoted into it)
PUT /deployments/environments/{name}/canaryR0.12 (wave 4): bind a revision to the environment’s canary slot {revision_id, fraction, author} → 201 with the moved pointer (200 {applied: false} on an identical re-declaration — the binding already holds; 404 undeclared environment or unknown revision; 422 a fraction outside (0, 1] — never a clamp). A declared gate runs first, exactly as on promote — the gate protects the environment, not the pointer slot. The active keeps serving; bound runs split by the seeded draw, journaled on each run’s own resolution
DELETE /deployments/environments/{name}/canaryR0.12 (wave 4): clear the canary slot {author} → 201 with the moved pointer (200 {applied: false} when the slot is already empty — an empty slot is the state, not an error). The canary_cleared act names the binding it ended
GET /deployments/journalR0.12 (wave 3): the deployment evidence chain — revision registrations, environment declarations, promotions, rollbacks, secret acts and denials — integrity re-verified on read (422 when it does not verify; the receipt_keys/journal and broker/journal precedent for a control plane)
PUT /deployments/secretsR0.12 (wave 3): set or rotate an environment secret {name, environment, value, author} → 201 {created, record} (200 + created: false on rotation — rotated_at marks it; 404 undeclared environment; 422 a name outside the naming rules). The value seals (XChaCha20-Poly1305 envelope under the deployment’s esk- master key) before anything writes; the store only ever holds the envelope, the env_secret_set act journals before the write, and the response is metadata — the value never comes back through this route
GET /deployments/secrets?environment=R0.12 (wave 3): the tenant’s secret metadata (never envelopes — a listing is an audit view), optionally one environment’s, sorted by (environment, name)
POST /deployments/secrets/resolveR0.12 (wave 3): open a secret at use, inside its declared scope {name, environment, holder} → 200 {name, environment, value}; 403 environment_scope_denied — typed AND journaled — when the holder is not the scope; 404 unknown secret; 500 when this host does not hold the sealing key. Every failure fails closed
DELETE /deployments/secrets/{environment}/{name}R0.12 (wave 3): revoke by deletion {author} → 204 (404 unknown/cross-tenant); the env_secret_revoked tombstone journals before the delete — the tombstone is the evidence the scope once held a value
POST /deployments/shadowsR0.12 (wave 4): run a recorded run’s twin under a candidate revision, behind the shadow admission boundary {revision_id, source, input?, author} — source is the journal snapshot, inline, so shadow evidence is self-contained → 201 {shadow_run_id, verdict}; 404 unknown revision; 422 a revision failing its content-address check, a source snapshot failing integrity, or a failed run (the verdict journals either way — a failed shadow is evidence about the candidate). Pure and read-only effects execute; everything above is refused (typed, classified, journaled) and served from the recorded world when the source journal holds the outcome; the verdict names matched, unserved, and unrequested outcomes. The shadow journals under its own run id and holds no thread — a receipt request for it is a 404 by construction
GET /deployments/healthR0.12 (wave 4): the health board — every environment’s pointer, canary state with its bound-run tally, and the last gate decision the chain recorded for it, derived from journaled data alone (no new store)

Runs support command.resume (HITL), config.recursion_limit, the reject / enqueue multitask strategies (one active run per thread), assistant_id (resolved to its bound graph, with the assistant’s config.recursion_limit as a default), and checkpoint.checkpoint_id (time-travel replay from that checkpoint instead of the latest). Runs may also declare their configuration at submission: registry (R0.11 wave 2) binds named artifacts through their environment-tagged version pointers, and deployment (R0.12 wave 3) binds the revision an environment serves — each resolved at admission (a resolution failure stops the run before it starts) and journaled ahead of the run’s own events, so the evidence names exactly what served.

Modules§

capsule_policy
The capsule authorization plane (R0.9 Rusty Capsules, wave 2): Cedar policies, tenant overlays, and the versioning store both backends keep.

Structs§

ApiError
An API error rendered as { "error": <kind>, "message": <detail> } with the matching HTTP status.
DirectoryDatasetSource
Datasets as JSONL files under one directory, named {dataset_name}@{version}.jsonl — rusty-eval’s canonical serialization (Dataset::save), so dataset versions diff cleanly in git and the file layout is the versioning.
DirectoryGatePolicySource
Gate policies as JSON files under one directory, named {policy_name}.json — rusty-eval’s canonical serialization (GatePolicy::to_json), so policies diff cleanly in git and the file layout is the naming.
EvalCandidateEvaluator
The wave-4 evaluation composition: core’s CandidateEvaluator over rusty-eval’s public API, exactly the seam the trait documents — ExperimentRunner over a versioned Dataset for the report half, exact replay over the request’s fixtures for the divergence half, compare for the verdict. Nothing about scoring, aggregation, or regression flagging is re-implemented here.
EvalRevisionGateEvaluator
The wave-4 gate composition: core’s RevisionGateEvaluator over rusty-eval’s public API. The candidate experiment runs under the revision being promoted; the baseline experiment runs under the environment’s serving revision when one serves, giving the gate’s comparative checks their evidence and arming the paired statistical check.
GraphRegistry
The set of graphs this server hosts — the Rust analog of the graphs map in LangGraph’s langgraph.json. Registration is compile-checked in user code; a GraphRegistry is heterogeneous (each entry carries its own StateSpec), which is safe because State is a JSON map at runtime.
ServerConfig
Server configuration.
TaskQuota
Tenant quota for the durable task queue (R0.6 wave 3): three gauges, each capped independently — tasks queued, tasks in flight, dead-letter depth — enforced at submission (POST /tasks, POST /tasks/outbox, and update_state’s atomic enqueue list). Over quota answers 429 quota_exceeded, the honest shape for “retry this submission later”.

Enums§

RunStatus
Lifecycle status of a run.

Constants§

DEFAULT_SHUTDOWN_GRACE
Default bound on graceful shutdown (25 s): how long serve_with_shutdown lets in-flight requests, runs, and the outbox relay finish after the shutdown signal before the server stops anyway.

Traits§

DatasetSource
Where versioned evaluation datasets come from. A request names a version; the source resolves it; both experiment reports name that version back. Datasets are immutable per version — re-running an evaluation must mean re-reading the same evidence.
EvaluationAgent
The application-owned half of an evaluation: how to build the agent under test. The evaluator owns the evidence discipline (the versioned dataset, the run counts, the replay fixtures, the comparison thresholds); the agent owns what the baseline and the candidate are as runnable graphs — the same application/runtime split as the distiller contract (design open question 2).
GatePolicySource
Where named gate policies come from. A declaration names a policy; the source resolves it. Policies are immutable per name — re-running a gate must mean re-reading the same rule, so a source that edits in place breaks the audit the gate journals.
RevisionEvaluationAgent
The application-owned half of a gate evaluation: how to build the agent one revision runs as. The evaluator owns the evidence discipline (the versioned dataset, the run counts, the policy, the statistical config); the agent owns what baseline and candidate revisions are as runnable graphs — the crate::learn::EvaluationAgent split, one level up: the revision’s frozen pin set is what the agent applies.

Functions§

router
Build the axum Router for a registry and config. Use this to embed the rusty-agent-server routes into a larger application, or to drive the API in tests via tower::ServiceExt::oneshot.
router_with_broker
Build the axum Router and hand back the credential broker it wired (R0.11 wave 4) — the app’s own broker, so in-process mediators (graph nodes carrying a CredentialMediator, capsule hosts) issue and resolve against the same custody and the same evidence chain the HTTP connection routes drive. The release proof’s runs connector-resolve exactly this way. Drain control is internal and never fires, as for router; embedders wanting cooperative drain compose router_with_shutdown and read the broker off app state instead.
router_with_shutdown
Build the axum Router with an explicit drain control (R0.6 wave 2c).
serve
Build the router and bind it to config.bind_addr. Blocks until the server shuts down: SIGINT or SIGTERM starts the graceful drain described on serve_with_shutdown.
serve_with_shutdown
Build the router, bind it to config.bind_addr, and serve until shutdown resolves, then drain gracefully (R0.6 wave 2c). The drain is ordered so the common case of a rolling deploy strands nothing:
shutdown_signal
The default shutdown signal for serve: resolves on SIGINT or SIGTERM (the two signals orchestrators and terminals actually send). Exposed so binaries that compose their own shutdown logic can reuse it.