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 /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?, 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
POST /learn/candidates/{id}/rollbackR0.8 (wave 3): re-point the surface to the displaced version {run_id, cause, 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
GET /learn/versionsR0.8 (wave 3): the tenant’s version pointers, sorted by surface
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)
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)

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).

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.
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.
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).

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_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.