agentplane 0.46.0

[package]
name         = "agentplane"
version      = "0.46.0"
edition      = "2024"
rust-version = "1.94.1"
license      = "MIT OR Apache-2.0"
description  = "Durable, replayable agent runtime — the journal is the plan of record"
repository   = "https://github.com/hupe1980/agentplane"
homepage     = "https://hupe1980.github.io/agentplane/"
documentation = "https://docs.rs/agentplane"
readme       = "README.md"
keywords     = ["agent", "durable-execution", "replay", "runtime", "llm"]
categories   = ["asynchronous", "development-tools"]

# An allowlist, because a crates.io publish is immutable: a denylist has to
# predict every generated file, and a file that should not have shipped can
# only be yanked, not withdrawn.
#
# Leading slashes anchor to the package root; without them these are
# gitignore-style globs matching any depth.
include = [
    "/src/**/*.rs",
    "/examples/*.rs",
    # An example `include_str!`s a manifest, so without these the packaged crate
    # does not compile — and `cargo package --list` alone would not say so.
    "/examples/*.yaml",
    "/examples/*.cedar",
    "/src/bin/*.rs",
    # The dev page's shell, script and stylesheet, which `api::dev` embeds.
    "/src/api/dev/index.html",
    "/src/api/dev/app.js",
    "/src/api/dev/app.css",
    "/README.md",
    "/CHANGELOG.md",
    "/LICENSE-MIT",
    "/LICENSE-APACHE",
    "/clippy.toml",
]

# Most of this crate is behind a feature gate, and docs.rs builds with default
# features unless told otherwise.
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

[features]
default = ["redb"]

# Embedded journal + case store. Single-node; `postgres` backs active-active.
redb = ["dep:redb"]
# PostgreSQL-backed journal: several plane instances sharing one store, where
# fencing and exactly-once are arbitrated by the database rather than by hoping
# the writers agree.
postgres = ["dep:tokio-postgres", "dep:deadpool-postgres"]
# The agent declaration: tool grants, budgets, egress ceiling, injection
# pattern. Off by default — the runtime is usable wired by builder calls; the
# manifest is what makes those declarations reviewable.
manifest = ["dep:serde_yaml_ng", "dep:jsonschema", "dep:regex", "dep:unicode-normalization"]
# Everything the `agentplane` binary needs. `signing` and `witness-http` are
# here for the audit verbs, for one reason: an `audit`/`verify` that could not
# check a signature, or could not fetch an anchoring checkpoint from a witness,
# sends the independent party back to writing Rust — or back to the operator
# for the very checkpoint the check is about. `tokio/signal` is here because
# `serve` drains on `SIGTERM`, and as PID 1 in a container an unhandled one is
# discarded rather than fatal — so the handler is what makes `docker stop` work.
#
# **Never `testkit`.** The binary needs one thing from it — `provider: fake` —
# and that is `fake-model`. Taking the whole feature would ship fault injection,
# a self-minting signer and a plaintext-loopback exception in every published
# artifact, each documented at its definition as impossible in a production
# build. `no_shipped_feature_enables_testkit` holds it.
cli = ["manifest", "redb", "providers", "bedrock", "fake-model", "signing", "witness-http", "tokio/signal", "dep:tracing-subscriber", "dep:clap"]
# Content-addressed blobs on any backend OpenDAL reaches, for bytes too big for
# the chain to carry.
opendal = ["dep:opendal"]
# Envelope encryption for payload bytes, and the erasure it makes provable:
# destroying the wrapping key reaches every copy at once, which deleting a row
# cannot do.
keyring = ["dep:chacha20poly1305"]
# A key ring that is somebody else — Vault's transit engine. The wrapping key
# never leaves it, so erasure is something this crate asks for and cannot undo.
keyring-vault = ["keyring", "dep:reqwest"]
# A model provider with no model behind it: deterministic answers, real usage
# figures. It ships, because a stand-in *model* is a driver and not a control —
# see `model::fake`. What stands in for a control is `testkit`.
fake-model = []
# Fault injection and harness pieces. Never in a production build — nothing in
# `testkit` is reachable without it, and no feature a release enables pulls it
# in. `tests/guards/docs.rs` holds that second half.
testkit = ["fake-model"]
# Cedar as the authorization engine. The crate defines the policy seam and
# ships no evaluator.
cedar = ["dep:cedar-policy"]
# MCP transport, and only the wire: the tool seam and its safety model are
# unconditional, because what a tool may do must not depend on which transport
# is linked. The same split applies to `a2a`.
mcp = ["dep:rmcp"]
# Reach an MCP server by **running it** — the stdio child process most
# published servers are. Separate because it costs 8 crates plus
# `tokio/process`, which an embedder bringing their own transport should not
# pay for.
mcp-stdio = ["mcp", "rmcp/transport-child-process"]
# Serve this plane's agents *as* MCP tools and their instructions as prompts.
# Needs the manifest: what a catalogue offers is the declaration, never a
# second list beside it.
mcp-server = ["mcp", "manifest", "rmcp/server", "rmcp/transport-io", "dep:http"]
# The same catalogue over Streamable HTTP, behind this plane's authenticator,
# policy and `Host`/`Origin` checks — the door an agent framework in another
# language walks through. Separate because it costs rmcp's HTTP server stack,
# which an embedder serving over stdio should not pay for.
mcp-server-http = ["mcp-server", "http", "rmcp/transport-streamable-http-server"]
# Reach an MCP server over streamable HTTP — the transport remote servers
# speak. Separate for the same reason as `mcp-stdio`: it costs a reqwest
# stack an embedder bringing their own transport should not pay for.
mcp-http = ["mcp", "rmcp/transport-streamable-http-client-reqwest"]
# HTTP surface for operators: worklist, run status, event delivery. `tokio/net`
# and `rt-multi-thread` are the listener — the base tokio features are short of
# a server by exactly that.
http = ["dep:axum", "tokio/net", "tokio/rt-multi-thread"]
# `agentplane dev`: a page for trying an agent on the author's own machine —
# loopback only, behind a per-process token, over a store this mode created.
# No container image enables it, because it starts runs over HTTP. `tower` is
# already in the graph through `axum`; the page calls the operator router
# through it.
dev = ["cli", "http", "dep:tower"]
# Submitting checkpoints to a real witness — the half that gives the split-view
# guarantee a counterparty. `signing` is not optional: a cosignature nobody
# verifies is not evidence, and verifying one needs the primitive.
witness-http = ["dep:reqwest", "signing"]
# A2A transport: the JSON-RPC client, and the RFC 8693 token-exchange client a
# peer's credential source can use. See `mcp` for why this is a wire and not
# the seam.
a2a = ["dep:reqwest"]
# Mapping the Agent Client Protocol's session updates onto observation records.
# Types only, and no dependency on the protocol's own crate: the connection
# belongs to the editor that already holds the session, and `observe::acp` says
# why the types are written against a named revision instead.
acp = []
# Serve this plane as an A2A agent. `push` is not optional: A2A 1.0 defines
# push notification configs as part of the protocol.
a2a-server = ["http", "manifest", "push", "dep:async-stream"]
# Webhook delivery for A2A push notifications: a durable config store plus
# SSRF-guarded outbound POSTs.
push = ["dep:reqwest", "dep:hmac"]
# One concrete Ed25519 signer. The seam — `Signer`, `Verifier`, the attestation
# on every record — is unconditional.
signing = ["dep:ed25519-dalek"]
# Model provider drivers over HTTP. The `ModelProvider` trait and the metering
# rules are unconditional.
providers = ["dep:reqwest", "dep:jsonschema"]
# Amazon Bedrock's Converse API. Separate from `providers` because the AWS SDK
# graph is substantial and OpenAI/Anthropic users should not pay for it.
bedrock = ["dep:aws-config", "dep:aws-sdk-bedrockruntime", "dep:aws-smithy-types", "dep:jsonschema"]
# Governed remote-media ingestion. Separate because dereferencing an untrusted
# URL is its own security boundary: every DNS answer and redirect is checked
# and pinned before bytes enter blob storage.
media = ["dep:reqwest", "tokio/net"]

[dependencies]
async-trait = "0.1"
# One base64 implementation, unconditional. The alternative is a hand-rolled
# codec in the modules that parse a checkpoint note without a feature flag —
# and a second decoder is a second answer to "is this the canonical spelling",
# which is the whole guarantee where a signature covers the text.
# `crate::core::b64` names the two dialects this crate speaks; nothing else
# reaches for the engine.
base64 = "0.23"
serde       = { version = "1", features = ["derive"] }
# NOTE: this crate must not ask for `preserve_order`, and cannot assume nobody
# else does — cargo unifies features across the graph and cedar-policy enables
# it. Canonical order is therefore produced by `core::canon` itself rather than
# inherited from serde_json::Map. See that module.
serde_json  = "1"
# Schema *from the type*, so a tool's arguments have one declaration rather
# than a hand-written copy in a manifest and a hand-indexed copy in the body.
schemars    = "1"
jsonschema  = { version = "0.56.0", default-features = false, optional = true }
futures-core = "0.3"
thiserror   = "2"
ulid        = { version = "3", features = ["serde"] }
sha2        = "0.11"
# HMAC for signed push bodies: the audited construction, not hand-rolled
# RFC 2104. Pinned to 0.13 to share `digest` 0.11 with `sha2` above.
hmac        = { version = "0.13", optional = true }
hex         = "0.4"
# Secrets are wiped when they drop. `String` leaves the bytes in freed heap and
# reallocates copies on growth, which no `Debug` impl fixes. Unconditional: an
# API key is not an optional-feature concern.
zeroize     = { version = "1", features = ["alloc", "derive"] }
time        = { version = "0.3", features = ["serde-well-known", "macros", "formatting", "parsing"] }
# `chacha` for `ChaCha8Rng`, the deterministic source behind `StepCtx::rng`.
# Through `rand` rather than a separate `rand_chacha`, so one crate declares the
# generator that produces a replayed run's numbers; two would resolve apart.
rand        = { version = "0.10", features = ["chacha"] }
tokio       = { version = "1", features = ["sync", "rt", "macros", "time"] }
# Two combinators: `join_all` to dispatch a ready set concurrently, and
# `buffer_unordered` where the set is a backlog rather than a frontier and has
# to be bounded. Deliberately not `futures` proper: this is a short list, not an
# ecosystem.
futures-util = { version = "0.3", default-features = false, features = ["std", "async-await"] }
async-stream = { version = "0.3", optional = true }
tracing     = "0.1"
# Some controls are quiet toward the caller and loud toward the operator — an
# A2A decline names the determining policy in a `tracing` event and tells the
# peer nothing. Without a subscriber installed, that half reaches nobody.
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "registry", "env-filter", "json"], optional = true }
# The binary's argument parser. A flag lives on its subcommand's struct, so
# passing a `serve` flag to `run` fails to parse rather than being accepted and
# ignored. +9 crates on `cli`, +0 on the library; re-derive with `cargo tree
# --no-default-features --features cli -e normal --prefix none | sort -u | wc -l`.
clap = { version = "4", default-features = false, features = ["derive", "std", "help", "usage", "error-context", "suggestions", "env", "wrap_help"], optional = true }
redb        = { version = "4", optional = true }
# The maintained fork of serde_yaml, which is deprecated. Ten crates deep.
serde_yaml_ng = { version = "0.10", optional = true }
# Content rules: the linear-time engine (no backreferences, no look-around), so
# a declared pattern cannot make a gate's cost depend on its input's shape.
regex = { version = "1", optional = true }
unicode-normalization = { version = "0.1", optional = true }
# `default-features = false`: the defaults pull in a long list of service
# backends. An embedder picks the one they use; `services-fs` is the only one
# that makes sense to assume.
chacha20poly1305 = { version = "0.11", default-features = false, features = ["alloc", "getrandom"], optional = true }
opendal     = { version = "0.59", default-features = false, features = ["services-fs"], optional = true }
# The lower bound is load-bearing: `first_unreachable` matches
# `ValidationWarning::InvalidActionApplication`, which 4.13.0 is the first
# release to have. Earlier ones do not compile.
cedar-policy = { version = "4.13.0", default-features = false, optional = true }
tokio-postgres = { version = "0.7.18", optional = true, features = [
  # `jsonb` parameters for a co-located resource. Without it `SqlValue::Json`
  # would have to be bound as text, and a resource updating a jsonb column
  # would get a type error at runtime rather than a value.
  "with-serde_json-1",
] }
deadpool-postgres = { version = "0.14.1", optional = true }
rmcp = { version = "3.1", default-features = false, features = ["client", "transport-io"], optional = true }
# The request type rmcp's HTTP server puts on a served request, read by
# `mcp-server` to refuse one that arrives over HTTP with no caller — whoever
# mounted the catalogue. Already in the graph wherever that server is.
http = { version = "1", optional = true }
# `query` for `?outcome=…` on the run list. Kept to the four features that
# are actually used: axum's default set pulls in a router's worth of
# extractors this surface never touches.
axum = { version = "0.8.9", default-features = false, features = ["json", "http1", "tokio", "query"], optional = true }
tower = { version = "0.5.3", default-features = false, features = ["util"], optional = true }
# `rustls` rather than the platform's TLS: one static binary is a design
# commitment, and linking OpenSSL puts a system dependency back in.
# `rand_core` off: keys come from the deployment, and a signer that can mint its
# own identity is a signer whose signatures mean nothing.
ed25519-dalek = { version = "3", default-features = false, features = ["alloc", "zeroize", "signature"], optional = true }
# `rustls`, not `native-tls`: one TLS stack, in Rust, so a deployment's threat
# model need not include OpenSSL's. `stream` gates `Response::bytes_stream`,
# which is how a driver learns what a severed call burned — without it the only
# honest report is "cost unknown" and the runaway-provider ceiling reads zero.
#
# The **trust anchor is the operating system's store**, via
# `rustls-platform-verifier`. That is a decision, not a default: the operator
# already administers a CA policy, and a runtime that ignored it would break
# every corporate inspection proxy while claiming to be more secure. Do not add
# `webpki-roots` — reqwest declares it as an optional dependency and never
# writes `dep:webpki-roots`, so Cargo synthesises an implicit feature that links
# Mozilla's whole bundle while the verifier stays the platform one. A guard in
# `tests/guards/docs.rs` keeps it gone.
reqwest = { version = "0.13", default-features = false, features = ["json", "rustls", "http2", "charset", "stream"], optional = true }
# Defaults declined on both AWS crates for one reason: the SDK's `rustls` feature
# is `legacy-rustls-ring`, pinning `rustls` 0.21 and `rustls-webpki` 0.101,
# which carry live RUSTSEC advisories against certificate validation.
# `default-https-client` selects the maintained `rustls-aws-lc` stack. A TLS
# client must not be whatever a transitive default picks; `just audit` keeps it
# honest.
# aws-config's default feature set restated explicitly, plus
# `credentials-login`, so a changed default cannot arrive or vanish
# unreviewed. The gated credential providers: `sso` (IAM Identity Center
# profiles), `credentials-process` (external helpers), `credentials-login`
# (`aws login` console-session profiles — a `login_session` profile fails to
# resolve without it). STS assume-role, web identity, IMDS/ECS roles and the
# `AWS_BEARER_TOKEN_BEDROCK` API-key path are not feature-gated.
aws-config = { version = "1.11.0", default-features = false, features = ["default-https-client", "rt-tokio", "credentials-process", "sso", "credentials-login", "behavior-version-latest"], optional = true }
aws-sdk-bedrockruntime = { version = "1.139.0", default-features = false, features = ["default-https-client", "rt-tokio", "behavior-version-latest"], optional = true }
aws-smithy-types = { version = "1.6.1", optional = true }

[dev-dependencies]
# The connector seam `model::canned_http` builds a stub over. Deliberately not
# `aws-smithy-http-client`'s `test-util`: its one useful function costs a hyper
# stack and a CBOR codec in every example this crate builds.
aws-smithy-runtime-api = { version = "1", features = ["client"] }
aws-smithy-types = { version = "1" }
# An **independent** A2A server, so this crate's *client* has an outside
# authority to talk to — the one interoperability gap the conformance kit
# cannot close, since it validates servers. Pre-1.0 churn is acceptable here
# because nothing in `src/` links these. `default-features = false`: the
# default pulls a TLS stack a loopback double needs for nothing.
a2a-lf = { version = "0.3.0", default-features = false }
a2a-server-lf = { version = "0.4.1", default-features = false }
# For the streaming driver tests: the stub server hands axum a body stream of
# `Bytes`, including one that errors partway so a severed response can be tested
# without a real network.
bytes = "1"
futures-util = { version = "0.3", default-features = false, features = ["std", "async-await"] }
http = "1"
# The operator API's wire suite validates every body it receives against the
# published OpenAPI document, in the `http,redb` build too, where the library's
# own copy (behind `manifest`) is absent. Same version as the library's.
jsonschema = { version = "0.56.0", default-features = false }
rmcp = { version = "3.1", default-features = false, features = ["server", "transport-io", "macros"] }
testcontainers-modules = { version = "0.15.0", features = ["postgres"] }
tokio = { version = "1", features = ["full"] }
tower = { version = "0.5.3", features = ["util"] }
# So the telemetry tests can assert what was *emitted*, not merely what the
# source contains. An instrumentation test that greps is checking the author's
# intent; this checks the runtime's behaviour.
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "registry"] }

# The CLI that makes the declarative tier need no Rust at all.
#
# Feature-gated because the library is the product, and a binary pulling in
# HTTP drivers is not something every dependant wants compiled.
# `cargo install agentplane --features cli` opts in.
[[bin]]
name              = "agentplane"
path              = "src/bin/agentplane.rs"
required-features = ["cli"]

[[example]]
name              = "openai_live"
required-features = ["redb", "providers"]

# The dual-model (CaMeL) shape against real models, so what each role is allowed
# to read is checked at the wire rather than against a fake that cannot disagree.
[[example]]
name              = "camel_live"
required-features = ["redb", "providers", "manifest"]

[[example]]
name              = "bedrock_live"
required-features = ["bedrock"]

[[example]]
name              = "gate_bench"
required-features = ["redb", "cedar"]

[[example]]
name              = "hello_skill"
required-features = ["redb"]

[[example]]
name              = "durable_pipeline"
required-features = ["redb"]

[[example]]
name              = "effect_group"
required-features = ["redb"]

[[example]]
name              = "tool_loop"
required-features = ["redb", "fake-model", "manifest"]

# A person approves the exact tool call — `requires_approval` end to end:
# suspend, worklist, approve or refuse, and a strict replay that re-opens
# nothing.
[[example]]
name              = "approved_call"
required-features = ["redb", "fake-model", "manifest"]

[[example]]
name              = "planned_run"
required-features = ["redb", "fake-model", "manifest"]

[[example]]
name              = "sealed_run"
required-features = ["redb", "testkit", "keyring"]

[[example]]
name              = "clearing_case"
required-features = ["redb"]

[[example]]
name              = "plan_graph"
required-features = ["redb"]

[[example]]
name              = "governed_transfer"
required-features = ["redb", "manifest"]

[[example]]
name              = "saga_checkout"
required-features = ["redb"]

[[example]]
name              = "memory_run"
required-features = ["redb"]

# One act made of many: a windowed pass, an item-granular resume, and a partial
# failure that is terminal rather than a degraded success.
[[example]]
name              = "batch_run"
required-features = ["redb"]

# Exhaustion is a pause with a protocol: refused, resumed under the same
# ceiling (still refused, not duplicated), readmitted under a raise, verified.
[[example]]
name              = "budget_pause"
required-features = ["redb"]

# The conclusion an operator could not act on, and the two verbs that answer it.
[[example]]
name              = "answered_doubt"
required-features = ["redb"]

# Two brakes: cancel one run (it unwinds, and the journal names who asked) and
# the store-backed emergency stop that halts new admissions on every instance.
[[example]]
name              = "operator_stop"
required-features = ["redb"]

# The last mile between instrumented and monitored: a real subscriber that
# excludes replays from latency, shows that gauges only exist once something
# queries the stores, and keys an alert on `needs_attention()`. No exporter is
# linked — the OTLP wiring is in the example's own docs, verbatim — because
# picking a collector is the embedder's decision, not this crate's.
[[example]]
name              = "observability"
required-features = ["redb"]

# An instance dies mid-run; the survivor's sweep finds the lapsed lease, takes
# the run over with fencing, and finishes it — no stage repeated. ~3s: a real
# lease has to lapse.
[[example]]
name              = "recovered_run"
required-features = ["redb"]

# Needs `fake-model`, not a key. Deliberately: an example that called a real
# model would need an API key to run, and the claim it demonstrates — that
# a completion replays from the journal rather than being asked again — would
# stay a sentence in the README instead of something anyone can execute.
[[example]]
name              = "model_run"
required-features = ["redb", "fake-model"]

# Digest-only multimodal dispatch and strict zero-I/O replay, with a fake model
# and an in-memory blob store so the security contract is runnable offline.
[[example]]
name              = "media_run"
required-features = ["redb", "fake-model", "media"]

# The manifest example reads `examples/triage.yaml` and runs the agent it
# declares, so it needs the parser as well as the fake provider.
[[example]]
name              = "manifest_run"
required-features = ["redb", "fake-model", "manifest"]

# A real MCP server in-process beside a typed tool, so the two-transport shape
# is runnable rather than only described. `rmcp`'s server half is a
# dev-dependency, which examples may use.
[[example]]
name              = "mcp_tools"
required-features = ["redb", "fake-model", "manifest", "mcp"]

# Three agents, three manifests, three runtimes.
[[example]]
name              = "blog_room"
required-features = ["redb", "fake-model", "manifest"]

# `tower::oneshot` drives the router in-process, so the A2A round trip is real
# without a port, a key, or a second process.
[[example]]
name              = "a2a_peer"
required-features = ["redb", "a2a-server", "manifest"]

[[example]]
name              = "peer_call"
required-features = ["redb", "testkit", "manifest", "a2a", "a2a-server"]

# Serves the A2A surface for the official conformance kit — `just test-a2a-tck`
# boots it and runs the kit's MUST battery against the live socket.
[[example]]
name              = "a2a_tck_live"
# `testkit` too, for the loopback push exception: the kit's webhook receiver is
# an `http://localhost:PORT` server, so without it the ten push MUSTs cannot run
# at all. The exception exists only under `testkit`, which never ships.
required-features = ["redb", "a2a-server", "manifest", "testkit"]

# The ceiling that outlives a run, end to end: cumulative across runs,
# exhausted, then revoked — with the terms still readable afterwards.
[[example]]
name              = "standing_authority"
required-features = ["redb", "fake-model"]

# Live deltas beside a single journaled completion — the one part of the model
# seam a fake could not reach until `FakeProvider::streaming`.
[[example]]
name              = "streaming_run"
required-features = ["redb", "fake-model"]

# The plane as an MCP server. `mcp` as well as `mcp-server`, because the example
# drives it with the SDK's own client over an in-process pipe — what a desktop
# host runs, rather than a hand-written expectation of what the server sends.
[[example]]
name              = "serve_mcp"
required-features = ["redb", "mcp", "mcp-server", "manifest"]

[[example]]
name              = "retention_hold"
required-features = ["redb"]

[lints.rust]
unsafe_code = "forbid"
missing_debug_implementations = "warn"

[lints.clippy]
# Ambient non-determinism is denied crate-wide in clippy.toml: every clock, RNG
# and ID read must go through StepCtx, which journals it.
all       = { level = "warn", priority = -1 }
pedantic  = { level = "warn", priority = -1 }
module_name_repetitions = "allow"
missing_errors_doc      = "allow"
missing_panics_doc      = "allow"
must_use_candidate      = "allow"

# Named individually rather than by group, because each of these catches
# something *wrong* rather than merely unusual: work done on a path that
# discards it, a clone nothing needs, a `&mut` that does not mutate, a doc
# summary too long to read in an index.
#
# The group itself is not enabled. Most of its volume here is
# `missing_const_for_fn`, which is a promise about a function's future as much
# as its present, and `derive_partial_eq_without_eq`, where `Eq` is a claim
# about the type rather than a formality; `option_if_let_else` and
# `redundant_pub_crate` argue for spellings this codebase does not use.
needless_collect             = "warn"
needless_pass_by_ref_mut     = "warn"
or_fun_call                  = "warn"
redundant_clone              = "warn"
string_lit_as_bytes          = "warn"
too_long_first_doc_paragraph = "warn"
use_self                     = "warn"