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)
| Endpoint | Purpose |
|---|---|
GET /ok | liveness |
GET /info | service version + registered graphs and their channels |
POST /threads | create a thread bound to a registered graph |
POST /threads/{id}/fork | time travel: copy the thread’s checkpoint history (full or up to checkpoint_id) into a new thread |
GET /threads/{id}/state | latest checkpoint as {values, next, checkpoint} (the checkpoint ref carries its pinned policy_version, R0.8 wave 4) |
POST /threads/{id}/state | write 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}/history | checkpoint list, newest first, limit/before |
POST /threads/{id}/runs | background run: 202 + run_id |
POST /threads/{id}/runs/wait | blocking run: terminal result as JSON |
POST /threads/{id}/runs/stream | run 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}/stream | attach to an existing run’s SSE stream: replay honoring Last-Event-ID, then live frames |
GET /runs/{id}/events | Flight 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}/fixture | Flight Recorder: download the run as a portable ReplayFixture bundle (journal + graph topology hash + final checkpoint) for CI replay |
POST /runs/replay | Flight 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 /assistants | create a named graph alias with config metadata |
GET /assistants / GET /assistants/{id} | list / fetch assistants |
POST /assistants/{id}/archive / POST /assistants/{id}/restore | reversibly 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}/versions | list the bounded immutable configuration lineage and active serving pointer |
POST /assistants/{id}/versions | stage 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}/activate | atomically activate or roll back to a reviewed version using an expected-active guard |
POST /crons | schedule recurring runs (interval secs or 5-field cron expr) |
GET /crons / DELETE /crons/{id} | list / delete crons |
POST /triggers | create 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}/webhook | signed 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}/events | the trigger’s event log (payload hash, action, run id, status), newest first |
GET /triggers/{id}/dead-letter | failed events, inspectable and replayable |
POST /triggers/{id}/events/{event_id}/replay | re-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 /tasks | R0.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/outbox | R0.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/claim | R0.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/metrics | R0.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}/heartbeat | R0.6: extend the held lease {worker_id, lease_ms} → {lease_expires_at}; 409 when the lease is lost |
POST /tasks/{id}/complete | R0.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}/fail | R0.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 /agents | R0.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}/mailbox | R0.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}/status | R0.7: the agent’s activation lease plus mailbox gauges (queued / in_flight / dead message counts) |
POST /agents/{id}/activate | R0.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/heartbeat | R0.7: renew the held activation {worker_id, fencing, lease_ms}; 409 on fencing loss |
POST /agents/{id}/activate/release | R0.7: drop the held activation {worker_id, fencing} so a draining host’s replacement activates promptly; 409 on fencing loss |
POST /agents/{id}/mailbox/next | R0.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}/supervision | R0.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}/cancel | R0.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}/restart | R0.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}/cancel | R0.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 /memory | R0.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/query | R0.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/corrections | R0.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/consolidate | R0.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/conflicts | R0.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/forget | R0.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_scope | R0.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/candidates | R0.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}/evaluate | R0.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}/promote | R0.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}/rollback | R0.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/versions | R0.8 (wave 3): the tenant’s version pointers, sorted by surface |
POST /registry/artifacts | R0.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}/commits | R0.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}/commits | R0.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/versions | R0.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/activations | R0.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/active | R0.8 (wave 4): the tenant’s active policy — the last activation’s body, or the floor when the registry never moved |
GET /policy/epochs | R0.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/drift | R0.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 /capsules | R0.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/resolve | R0.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/active | R0.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}/receipt | R0.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/verify | R0.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_keys | R0.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/rotate | R0.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/journal | R0.9 (wave 3): the deployment’s key-lineage journal — the chained signing_key_rotated events, integrity re-verified on read |
POST /mcp | R0.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.json | R0.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 /a2a | R0.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}/blob | R0.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 /connections | R0.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 /connections | R0.11 (wave 3): the tenant’s connection records (metadata only — sealed material never leaves the broker), sorted by id |
GET /connections/health | R0.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}/consent | R0.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}/revoke | R0.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}/health | R0.11 (wave 3): the connection’s status and health counters (last failure class, consecutive failures, last refresh) |
GET /broker/journal | R0.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/revisions | R0.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/environments | R0.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}/promote | R0.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}/rollback | R0.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}/pointer | R0.12 (wave 3): the environment’s serving picture (404 undeclared environment, or nothing ever promoted into it) |
PUT /deployments/environments/{name}/canary | R0.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}/canary | R0.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/journal | R0.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/secrets | R0.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/resolve | R0.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/shadows | R0.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/health | R0.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. - Directory
Dataset Source - 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. - Directory
Gate Policy Source - 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. - Eval
Candidate Evaluator - The wave-4 evaluation composition: core’s
CandidateEvaluatoroverrusty-eval’s public API, exactly the seam the trait documents —ExperimentRunnerover a versionedDatasetfor the report half, exact replay over the request’s fixtures for the divergence half,comparefor the verdict. Nothing about scoring, aggregation, or regression flagging is re-implemented here. - Eval
Revision Gate Evaluator - The wave-4 gate composition: core’s
RevisionGateEvaluatoroverrusty-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. - Graph
Registry - The set of graphs this server hosts — the Rust analog of the
graphsmap in LangGraph’slanggraph.json. Registration is compile-checked in user code; aGraphRegistryis heterogeneous (each entry carries its ownStateSpec), which is safe becauseStateis a JSON map at runtime. - Server
Config - Server configuration.
- Task
Quota - 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, andupdate_state’s atomicenqueuelist). Over quota answers429 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_shutdownlets in-flight requests, runs, and the outbox relay finish after the shutdown signal before the server stops anyway.
Traits§
- Dataset
Source - 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.
- Evaluation
Agent - 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).
- Gate
Policy Source - 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.
- Revision
Evaluation Agent - 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::EvaluationAgentsplit, one level up: the revision’s frozen pin set is what the agent applies.
Functions§
- router
- Build the axum
Routerfor a registry and config. Use this to embed the rusty-agent-server routes into a larger application, or to drive the API in tests viatower::ServiceExt::oneshot. - router_
with_ broker - Build the axum
Routerand hand back the credential broker it wired (R0.11 wave 4) — the app’s own broker, so in-process mediators (graph nodes carrying aCredentialMediator, 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 forrouter; embedders wanting cooperative drain composerouter_with_shutdownand read the broker off app state instead. - router_
with_ shutdown - Build the axum
Routerwith 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 onserve_with_shutdown. - serve_
with_ shutdown - Build the router, bind it to
config.bind_addr, and serve untilshutdownresolves, 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.