Cookbook

Task-shaped recipes. Each one states the trap it avoids, because most of these have an obvious wrong version that works until it doesn’t.

For the vocabulary — effect, disposition, label — see concepts. For why any of it is shaped this way, see architecture.

🧬 Build an agent

An agent here is not a class you subclass. It is skills (what it can do), a plan (which capability runs when), and a policy (what it may do) — held together by a Runtime that journals every step.

Start with a skill. The system prompt lives in the prompt value, not in a separate setting, because the prompt is part of the effect key: change the instruction and a replayed run reports divergence instead of quietly answering a different question.

use agentplane::core::{Outcome, Sensitivity, Skill, SkillDescriptor, SkillError, Tainted};
use agentplane::model::{ModelCall, ModelId, ModelProvider};
use agentplane::runtime::StepCtx;
use serde_json::{Value, json};
use std::sync::Arc;

#[derive(Debug)]
struct Triage {
    provider: Arc<dyn ModelProvider>,
}

#[async_trait::async_trait]
impl Skill for Triage {
    fn descriptor(&self) -> SkillDescriptor {
        // A skill that declares nothing answers its own name — the right
        // default for a first program. `.provides(..)` is declared here because
        // the plan below binds the *capability* `ticket.triage`, decoupling
        // what a step needs from who provides it — and swapping the
        // implementation is then a binding change. Declaring a capability
        // replaces the name default rather than adding to it.
        SkillDescriptor::new("triage").provides("ticket.triage")
    }

    async fn invoke(
        &self,
        cx: &mut StepCtx<'_>,
        input: Tainted<Value>,
    ) -> Result<Outcome, SkillError> {
        // `Tainted::object`, not `input.map(...)`. The two slots mean different
        // things and must not share a label: `/system` is the order the model
        // reasons *under*, and it is a protected field — untrusted text there is
        // refused before the model sees it. `messages` is content it reasons
        // *about*, and may stay untrusted.
        //
        // `map` cannot prove how a closure reshaped a value, so it taints the
        // whole result — instruction included. That is why building the prompt
        // this way is not a style preference.
        let prompt = Tainted::object([
            // Each driver spells the instruction the way its API does —
            // top-level `system` on Anthropic, `instructions` on OpenAI
            // Responses. Write it once.
            (
                "system".to_owned(),
                Tainted::trusted(json!(
                    "You triage support tickets. Answer only with the JSON asked for."
                )),
            ),
            (
                "messages".to_owned(),
                Tainted::array([input.map(|i| json!({ "role": "user", "content": i }))]),
            ),
        ]);
        // `sink_with` hands the labelled value to the effect and the gates in
        // one motion: the closure receives the inner value, so the bytes the
        // egress ceiling checks and the bytes the provider is sent cannot be
        // two versions of one prompt.
        let provider = Arc::clone(&self.provider);
        let completion = cx
            .sink_with(&prompt, |value| {
                ModelCall::new(provider, ModelId::new("anthropic", "claude-sonnet-5"), value)
                    // The ceiling that matters for a hosted model: a prompt
                    // assembled from a secret is an exfiltration whether or
                    // not anyone meant it.
                    .with_max_sensitivity(Sensitivity::Internal)
                    .expecting(json!({
                        "type": "object",
                        "properties": { "severity": { "type": "string" } },
                        "required": ["severity"],
                    }))
            })
            .await?;
        Ok(Outcome::done(completion.map(|c| {
            c.structured.unwrap_or(Value::Null)
        })))
    }
}

Then wire the skills together and run. A single-capability agent needs no plan at all; a multi-step one gets a PlanIR.

use agentplane::core::{ArgSource, PlanIR, PlanNode, StepId};
use agentplane::journal::JournalStore;
use agentplane::runtime::Runtime;
use agentplane::store::RedbStore;

let store: Arc<dyn JournalStore> = Arc::new(RedbStore::open_in_memory()?);

let rt = Runtime::builder(Arc::clone(&store))
    .owner("support-plane")
    .skill(Triage { provider: Arc::clone(&provider) })
    .skill(Notify)
    .build();

// One capability: no plan needed.
let out = rt.run("ticket.triage", Tainted::trusted(json!({ "text": "printer on fire" }))).await?;

// Several: name the order, and what feeds what.
let plan = PlanIR::new(vec![
    PlanNode::new(0, "ticket.triage").arg("input", ArgSource::run_input()),
    PlanNode::new(1, "ticket.notify")
        .arg("triage", ArgSource::node(StepId(0)))
        .terminal(),
]);
let out = rt.run_plan(plan, Tainted::trusted(json!({ "text": "printer on fire" }))).await?;

Which one: a plan, or a commission?

Both compose several steps, and the choice is not a matter of taste.

A plan is an authorization graph. Use it when the shape is known before the work starts: the steps, what feeds what, which one is terminal. It is frozen at admission and checked against the manifest, so a run cannot execute a step nobody authorized — and a failure unwinds it in reverse.

A commission is an effect. Use it when one agent needs an answer from another and the shape is decided while running — an editor that reads a brief and then decides it needs research. It is journaled like any other effect, the answer comes back untrusted, and the sub-run has its own journal and its own ceiling.

The rule of thumb: if you can draw the graph before you start, draw it. A plan is checkable in advance and a commission is not; the commission’s advantage is that it does not need to be.

Most agents need neither, and most of the examples in this repository are the evidence: rt.run(capability, Tainted::trusted(input)) is one capability and no graph.

Fan out to several specialists at once

The unit of concurrency is the plan node, not the call. Nodes with no edge between them are one ready set and are dispatched together, each with its own journal slice — so “ask every relevant specialist, then decide” is one plan:

let plan = PlanIR::fan_out(
    ["billing.anomaly", "billing.regulatory"],   // run concurrently
    "billing.decide",                            // then combine
);
let out = rt.run_plan(plan, Tainted::trusted(document)).await?;

The aggregator receives one argument per branch, keyed by the capability that produced it — so adding a specialist cannot silently renumber what it reads, which hand-wiring by StepId does.

Everything stays inside one run: one run id, one budget ledger, one case binding, and a strict replay that reassembles the whole fan-out without waking a single specialist.

Two things it deliberately does not do:

• It does not set topology. Whether a fan-out is collaboration depends on whether the branches are other agents or this agent’s own skills, and the plan cannot tell. Declare it if it is: parallel-disjoint is for branches over genuinely disjoint inputs — a fan-out over one shared input is not that, and the validator will say so — while distinct-authority is the reason that fits independent opinions from differently-privileged specialists.
• There is no race. Abandoning an in-flight branch leaves an announced effect with no terminal record — the unknown outcome the effect protocol exists to prevent — and makes the answer depend on which machine was less loaded. Every branch runs to completion and every outcome is on the record.

The trap: letting untrusted text become the instruction. A model reads its order and its data as the same undifferentiated text, so a document saying “ignore previous instructions” is obeyed like one if it lands in /system. Labelling the data and gating the sinks bounds what the model may then do — this crate does that — but it never answers who was allowed to give the order. /system is therefore protected: untrusted material belongs in messages.

This bites the moment an agent is exposed over A2A, because a peer’s message arrives untrusted while a locally-invoked run’s input is trusted. An agent built with input.map(...) works on your machine and is refused in production, which is the right way round but worth knowing before it happens.

The second trap: putting the system prompt in a config file that the run does not hash. The instruction is half of what the model was asked; if it can change without the effect key changing, a replay reads back an answer to a question that no longer exists, and nothing reports it.

Multimodal uses the provider’s inline image and document shapes. Inline bytes and OpenAI data URLs work; provider-native remote URL blocks are refused before dispatch. Two things to know before sending media, both consequences of the journal being the record of what happened:

• The prompt is stored in the journal, which is append-only and hash-chained, so an inlined image is kept forever and cannot be pruned. A record over Record::MAX_RECORD_BYTES (1 MiB) is refused, not truncated — put the bytes in a blob store and journal the digest instead (below).
• A media URL would be fetched by the provider, outside this plane’s egress allowlist and journal, so the model effect and built-in drivers reject it. Enable media and fetch it through cx.fetch_media: every DNS answer and redirect is checked, the checked addresses are pinned into the connection, and only a digest enters history.

“Only a digest” applies to the input artifact and effect identity. The model completion is still journaled for replay and a provider may quote, transcribe, or otherwise reproduce media content in that output. Governed media prevents the original blob from becoming immortal by construction; it cannot promise that generated output contains no personal data. Apply output classification, minimization, and retention policy accordingly.

use agentplane::media::{GovernedMedia, MediaPolicy};

let media = GovernedMedia::new(
    MediaPolicy::new()
        .allow_host("cdn.example.com")
        .allow_media_type("image/png")
        .max_bytes(5 * 1024 * 1024),
);

// URL selection is authority-bearing: untrusted/model-selected URLs need a
// typed policy-authorized release before this trusted selector can be used.
let fetched = cx
    .fetch_media(&media, Tainted::trusted("https://cdn.example.com/chart.png".to_owned()))
    .await?;

// Mapping preserves the fetched artifact's untrusted label and sensitivity.
// The prompt contains a digest marker, not the bytes.
let media_grant = fetched.peek().clone();
let prompt = fetched.map(|artifact| json!({
    "input": [{ "role": "user", "content": [artifact.openai_image()] }]
}));
let answer = cx
    .sink_with(&prompt, |value| {
        ModelCall::new(provider, model, value)
            .with_max_sensitivity(Sensitivity::Internal)
            .with_media(blobs.clone(), [&media_grant])
    })
    .await?;

Use artifact.anthropic_image() for Anthropic, artifact.openai_image() for OpenAI, and artifact.bedrock_image() or artifact.bedrock_document() for Bedrock Converse. All four produce digest markers that materialize only during live dispatch. Bedrock documents use the constant neutral name document; AWS explicitly treats caller-chosen document names as prompt-injection-bearing content. Unsupported media types and every remote/S3 provider source are refused rather than guessed.

Run cargo run --example media_run --features redb,fake-model,media for the offline, executable half of this contract: provider-URL refusal, an exact digest/type capability, live-only materialization, untrusted output, and strict replay with unchanged blob-read and provider-call counters. The example does not fake DNS or HTTP and says so explicitly; a fake connector cannot prove DNS pinning or per-hop redirect authorization.

The default retention regime requires the run to belong to a case and links the digest automatically. Outside a case, name the lifecycle controller explicitly with external_retention("policy/version"); an unnamed unlinked blob is refused. Externally retained bytes belong to that policy’s erasure unit even when the run has a case: they are not linked to it, erase_case does not reach them, and cx.media_blobs(&fetcher) is the handle that reads them back. HTTPS/443, no retries, identity encoding and three redirects are the defaults. Cleartext HTTP, another port, or retries each require a separate explicit grant. Automatic redirects, proxies, referrers, cookies and content decompression are not used. Common passive formats are checked by magic/parse; other exact media types require a versioned MediaValidator such as a malware scanner.

📄 Write an agent with no Rust at all

If the agent is a prompt, a model and a result shape, the code adds nothing a reviewer can check — and it costs something they would want: the digest then covers only part of the agent.

# summariser.yaml — this file *is* the agent
apiVersion: agentplane.hupe1980.github.io/v1alpha1
kind: Agent
metadata: { name: summariser, version: "1.0.0" }
spec:
  execution: { kind: completion }
  identity:
    role: "Summarise a support ticket"
    constraints: "One sentence. No speculation."
  capabilities: { provides: [support.summarise] }
  models:
    privileged: { provider: anthropic, model: claude-sonnet-5 }
  output:
    schema:
      type: object
      additionalProperties: false
      required: [summary]
      properties: { summary: { type: string } }
  budgets: { max_tokens: 10000 }

let m = Manifest::parse(&std::fs::read_to_string("summariser.yaml")?)?;

// The only Rust: which driver answers to a provider name. That is deployment
// wiring — an agent's declaration must not change when its API key does.
let rt = Runtime::builder(store)
    .provider("anthropic", anthropic_driver)
    .agent(Agent::new(&m))
    .build();

let out = rt.run("support.summarise", Tainted::trusted(ticket)).await?;

Rust-generated declarations use Manifest::builder(name, version) with .configure(|spec| ...) or .spec(spec), then .build(). The builder is deliberately thin: nested values remain the same public typed Spec used by Serde, and build runs the same normalization and validation as YAML. Direct struct construction should finish with manifest.build(); otherwise the value has not earned the guarantees a parsed manifest has.

Add a human to the loop without writing the call:

spec:
  execution: { kind: completion }
  oversight:
    approval: required
    approvers: [role:compliance-officer]
    # The obligation bounding the wait; your Calendar decides what `kind` means.
    deadline: { name: klaerung, kind: working-days, params: { n: 2 } }
    on_expiry: deny           # the default; `proceed` needs allow_unattended

The agent opens a task carrying its answer as the proposal — not a description of it — and returns only on approval. Needs a case and .tasks(store).

For a tool-calling agent, gate the call instead: approval: tools-only with requires_approval: true on the grants a person must see opens the task before dispatch, carrying the exact tool and arguments — gating the answer there is a review that arrives after the money moved. A reviewer may also answer with the arguments: an approval’s amendment dispatches in the model’s place as the reviewer’s own trusted value (provenance task:agent.approve_call, which a source-bound field must list before it stands there). cargo run --example approved_call --features redb,fake-model,manifest runs the whole shape: suspend, worklist, approve, refuse or amend, and a strict replay that re-opens nothing.

The trap: expecting kind to grow keywords. It is a closed enum — completion, tool-calling, planned — and each is a behaviour the runtime implements and tests. What you will never find here is sequencing, conditions or loops — config that encodes control flow stops being config and becomes a poor programming language. If you need structure, use a plan, which is contract-validated data.

And no conditions. “Require approval when severity is high” is a predicate, and a predicate is one step from an if. An agent whose oversight depends on what it found is a skill — written in a language built for decisions.

The second trap: a provider name that is not registered. It is refused, not defaulted to whatever driver happens to be present — falling back would run the agent on a model its own declaration does not name.

cargo run --example blog_room --features redb,fake-model,manifest has two of these, and one orchestrator that is still Rust because it delegates.

🎫 Work with labelled values

Tainted<T> is the type every value in a skill arrives in. Reading is free; the gate is at sinks, so there is no unwrap:

let name = input.peek()["name"].as_str().unwrap_or_default();  // reading is fine
let label = input.label();                                     // trust, sensitivity, provenance

Build values so the labels stay per field rather than collapsing to the worst one:

let args = Tainted::object([
    ("recipient".to_owned(), Tainted::trusted(json!("treasury"))),
    ("memo".to_owned(), from_the_model),          // untrusted, and stays that way
]);

object and array keep each field’s label at its RFC 6901 path, which is what lets a protected /recipient be satisfied while /memo remains untrusted. map and zip cannot — the runtime cannot prove how a closure reshaped a value — so they keep the conservative whole-value label and drop field paths. Reach for object when the difference matters.

Labels join: combine anything untrusted and the result is untrusted; combine anything Confidential and the result is at least Confidential. Effect output is labelled at the source, untrusted by default, so this happens without a skill saying so.

The trap: Tainted::trusted(...) on something a model or a tool produced. It compiles, and it is the laundering every gate downstream depends on not happening. Trusted means from the operator, the manifest, or the run’s own trusted input; raising anything else is cx.release, which asks policy and leaves a record.

🔩 Reach a system this crate has never heard of

Tools, models and peers are effects with drivers written for them. Everything else is an Effect you write — the extension seam:

#[async_trait::async_trait]
impl Effect for ChargeCard {
    type Output = Receipt;

    fn descriptor(&self) -> EffectDescriptor {
        // Hashed with the position into the effect key: these arguments are
        // what makes this call *this* call on replay.
        EffectDescriptor::new("psp.charge", json!({ "order": self.order, "cents": self.cents }))
    }

    fn mutates(&self) -> bool { true }
    fn recovery(&self) -> Recovery { Recovery::Reconcile }

    async fn perform(&self) -> Result<Receipt, EffectError> {
        match self.client.post(&self.order).await {
            Ok(r)                      => Ok(r),
            Err(e) if e.is_connect()   => Err(EffectError::Unavailable {
                driver: "psp".into(), detail: e.to_string() }),
            Err(e) if e.is_timeout()   => Err(EffectError::Timeout {
                driver: "psp".into(), waited_ms: 30_000 }),
            Err(e)                     => Err(EffectError::Rejected(e.to_string())),
        }
    }
}

The one decision that matters is the error mapping, and it is a claim about the world, not about the wire: Unavailable and Rejected mean nothing was applied, so the runtime may retry; Timeout and Interrupted mean it may have landed, so it will not. Map a timeout to Rejected and a card gets charged twice.

One more distinction pays for itself on the failure path: Refused means the peer understood the request and said no — an answer, not a fault — and the runtime spends no retry on it. Use it for the refusals no repeat can change (a validation error, an unknown account); keep Rejected for the ones a repeat might (an overloaded gateway). Conflating them is how a wrong request burns every permitted attempt with backoff before failing anyway.

And when the peer says not now, come back at — a 429 with a Retry-After — say so, because it is the one failure where the schedule does not have to be a guess:

Err(EffectError::RateLimited {
    detail: format!("HTTP 429: {body}"),
    // Delta-seconds only. `None` when the peer named nothing, which is
    // ordinary — the effect's own schedule then applies.
    retry_after: response
        .headers()
        .get(reqwest::header::RETRY_AFTER)
        .and_then(|v| v.to_str().ok())
        .and_then(agentplane::core::retry_after_seconds)
        .map(Duration::from_secs),
})

The runtime waits the named window instead of its computed backoff, bounded by RetryPolicy::max_advice (60 s by default). A Rejected here would work and would retry after ~100 ms, three times, inside a window measured in tens of seconds — and then report the provider as down. The shipped model drivers do this for you.

recovery says what to do with a call that may have landed: Retry (safe to repeat), Reconcile (ask the provider what happened — implement reconcile), or RequiresOperator. A mutating effect that declares nothing gets RequiresOperator.

Declare trust() only if the output is not somebody else’s data — the default is untrusted, and it is the right default. If the effect carries an outbound value, dispatch it through the sink gate — cx.sink_with(&args, |v| ...) builds the effect from the labelled value in one motion, and the two-arg cx.sink(effect, &args) remains for an effect that binds its outbound value internally — rather than cx.effect, which refuses it. Provenance names the concrete source: source() defaults to effect:{kind}, and the effects whose outputs feed authority-bearing fields override it with the identity an operator actually grants — a tool call answers as tool://server/name, a model completion as model:{provider}/{model}, a commission as agent/{capability}. A family name would be too coarse for the rule that matters: “the recipient must come from the CRM lookup” is unsatisfiable when every granted tool answers under one family.

You do not need an effect for the ordinary nondeterminism: cx.now() is the journaled clock, cx.rng() is seeded per step and reproduces on replay, and cx.note("...") puts a line in the chain for whoever reads it later. SystemTime::now() and a thread RNG are lint errors here, because a replay that recomputed them would disagree with the history it claims to reproduce.

🤖 Call a model

use agentplane::model::{ModelCall, ModelProvider};

let prompt = input.map(|ticket| json!({ "task": "triage", "ticket": ticket }));
let completion = cx
    .sink_with(&prompt, |value| ModelCall::new(provider, model_id, value))
    .await?;   // Tainted<Completion>

The trap: treating a failed call as free. A model call has a third state between success and failure — it ran, generated four hundred tokens, and the stream died. The provider bills for those tokens. If the ceiling counts them as zero, a retry loop against a flaky provider spends real money against a limit reading nothing.

The drivers stream by default precisely so a severed call can report what it burned. You do not have to do anything to get that.

📐 Ask for structured output

let prompt = Tainted::trusted(prompt);
let completion = cx
    .sink_with(&prompt, |value| ModelCall::new(provider, model, value).expecting(schema))
    .await?;
let value = completion.peek().structured.as_ref().expect("a schema was declared");

The schema goes to the provider’s own constrained-decoding mode, where it is enforced during generation. A schema applied afterwards rejects an answer you have already paid for.

The trap: assuming every model supports it. They don’t, uniformly. Set the mode per model, not per driver — one driver serves many models over one key:

let provider = Anthropic::new(key)?
    .structured_via_for("claude-legacy-1", SchemaMode::ForcedTool);

🧰 Define a tool once

A tool is one type. Its arguments are its fields and its schema comes from those fields, so the model is shown exactly what the body deserializes. The description stays in the manifest because it steers model behaviour and therefore belongs in the digest-covered review artifact:

/// Read a ledger account's balance.
#[derive(Deserialize, JsonSchema)]
struct ReadBalance {
    /// The account to read.
    account: String,
}

#[async_trait]
impl Tool for ReadBalance {
    const SERVER: &'static str = "ledger";
    const NAME: &'static str = "read";
    fn mutates() -> bool { false }

    async fn call(self) -> Result<Value, ToolFailure> {
        Ok(json!({ "account": self.account, "balance": 42 }))
    }
}

let rt = Runtime::builder(store)
    .agent(Agent::new(&manifest))
    .toolbox(ToolBox::new().with::<ReadBalance>().with::<PostEntry>())
    .build();

call takes self because the arguments are the tool: by the time it runs, the model’s JSON is this type or the call was refused. There is no Value left to index and no field name to misspell.

What a failure has to say

ToolFailure names the disposition, not a transport error, because that is the only thing the runtime does anything with — it decides whether a retry is a correction or a second real invocation:

async fn call(self) -> Result<Value, ToolFailure> {
    if !self.account.starts_with("AC-") {
        // Nothing was attempted. Safe to repeat.
        return Err(ToolFailure::DidNotHappen(format!("not an account: {}", self.account)));
    }
    match self.post().await {
        Ok(receipt)              => Ok(json!({ "receipt": receipt })),
        Err(e) if e.is_timeout() => Err(ToolFailure::InDoubt(e.to_string())),
        Err(e)                   => Err(ToolFailure::Landed(e.to_string())),
    }
}

The ToolId is attached by the box that dispatched the call, so a body cannot name a tool other than itself and there is no identity to repeat on every error path. Getting the choice wrong in the DidNotHappen direction is how a payment happens twice, so InDoubt is the honest answer whenever a request left this process and no acknowledgement came back. RequiresOperator on the grant then escalates it rather than guessing.

What the output is labelled

You do not label it, and you cannot. A tool’s result comes back Tainted<Value> and untrusted, because it is the outside world’s data — and nothing in the catalogue can change that, since the catalogue governs authority and not provenance. ToolSafety::output_sensitivity sets the sensitivity floor its results carry; there is no corresponding knob for trust.

That is deliberate even for the case that feels wrong — an internal registry lookup whose answer really is reliable. Trust is not a property of where a value came from in the deployer’s head; it is a claim that has to be journaled, and the way to make it is cx.release, which names the destination, basis and evidence and asks policy under data:release. A trusted: true field on a tool declaration would be the same claim with no record, no authorization and no reviewer.

This is the shape Python’s @tool, Pydantic AI, the OpenAI Agents SDK and Rig all arrived at, and the reasons are the same: a schema written twice is a schema that disagrees with itself. Those SDKs also derive the description from code, which is right when code is the declaration. Here the manifest is the reviewed, content-addressed declaration, so model-steering prose belongs there instead.

.toolbox(..) is one call rather than three, two of them optional. It derives the catalogue from each agent’s own declaration — the grants, their ceilings and their protected fields, stated once — and it refuses to build if the tools this binary implements and the manifests a reviewer approved have drifted in either direction: a tool implemented but not granted means the binary can do something its declaration does not admit; a grant with nothing behind it means the model is offered a tool that fails when chosen. Neither is caught by the dispatch gates, which refuse a call long after the disagreement shaped what the model was told it could do.

The check runs at build, not when the box is wired, and that is what makes it worth trusting: checking on the .toolbox(..) call would check against the agents registered so far, so writing .toolbox(..).agent(..) would pass by having nothing yet to disagree with. Every agent on the plane is checked, not the first.

The trap: believing the type is the security boundary. It is not — it is the shape. The manifest still declares what this deployment permits.

📜 Govern a skill you did write

The other tier. When the agent does real work — a solver, a database, something a model cannot be — the behaviour is a Skill, and the manifest governs its boundary: which model, which tools, what it may spend.

cargo add agentplane --features manifest

Everything in the zero-Rust manifest above applies; drop spec.execution and add what a coded agent needs:

spec:
  # no `execution:` — the behaviour is a skill you registered
  topology: { mode: single, role: specialist }
  security:
    max_sensitivity_egress: internal
    max_delegation_depth: 2
  models:
    # Pricing is yours to state — minor units per million tokens. A money
    # ceiling beside an unpriced role is refused at load.
    privileged:
      provider: anthropic
      model: claude-sonnet-5
      pricing: { input: 300, output: 1500, cache_read: 30, cache_write: 375 }
    quarantined:
      provider: anthropic
      model: claude-haiku-4-5
      pricing: { input: 100, output: 500, cache_read: 10, cache_write: 125 }
  tools:
    - ref: "tool://validator/apply_correction"
      mutates: true
      max_sensitivity: internal
      protected_fields:
        - path: /target
          require_trusted: true
        - path: /correction
          allowed_sources: [model:anthropic/claude-sonnet-5]
  budgets:
    max_tokens: 120000
    max_minor_units: 250      # cents, never a float

A source rule names the concrete source, because that is what an effect’s output carries as provenance: a tool call answers as tool://server/name, a model completion as model:{provider}/{model}, a commission as agent/{capability}. A family spelling like effect:model.complete matches nothing — a family is too coarse for the rule that matters, since “the correction must come from the privileged model” is unsatisfiable when every completion answers under one name.

use agentplane::manifest::Manifest;
use agentplane::runtime::Agent;

let m = Manifest::parse(&std::fs::read_to_string("auditor.yaml")?)?;
// The manifest binds to *an agent*, not to the plane: a runtime hosts several,
// each separately declared and separately bounded.
let runtime = Runtime::builder(store)
    .agent(Agent::new(&m).skill(Auditor))
    .build();

// "Which declaration governed this run" stays answerable after the file has
// moved on — including the prompt, because `spec.identity` is inside the digest.
let governed_by = m.digest()?;

Your skill reads the declaration from its context rather than holding a copy — an agent has skills, not the other way round:

let m = cx.manifest().expect("this agent runs under a manifest");
let system = m.spec.identity.as_ref().map(Identity::system_prompt).unwrap_or_default();

What binds, and what does not. This is the part worth knowing precisely, because a field read by convention is two copies of one decision:

There is no security.pattern field. Native skill code cannot be proven to follow an architectural injection pattern, so the schema refuses to imply that it can.

effect:declared is deliberately a different action from a Cedar denial: a policy denial is the deployment’s rules saying no to something the agent was built to do; a manifest refusal is the agent doing something its own reviewed file never mentioned, which is a defect in the code.

The trap: a permissive parser. max_tokns: 100 is not “a ceiling with a typo” — in a format that ignores unknown fields it means no ceiling at all, in the one document whose purpose was to make the ceiling reviewable. Every struct is deny_unknown_fields. For the same reason a manifest with no budgets is refused: unbounded is a decision, and budgets: {} is how you state it where a reviewer can object.

🗃️ Keep state across runs, not inside one

A month-long process is a case plus short runs. Start a run correlated by business key, and it joins the existing case or opens one:

rt.run_correlated("claim.assess", Tainted::trusted(input), "claim", &[CorrelationKey::new("claim", "CLM-9")]).await?;

Inside the skill, case state is versioned and every access is journaled:

let (state, version) = cx.case_state().await?;      // untrusted: many runs write it
let next = json!({ "stage": "assessed" });
cx.put_case_state(version, next).await?;            // refused if the case moved
cx.deadline("respond-by", &DeadlineSpec::days(5), None).await?;
cx.meet_deadline("respond-by").await?;
cx.set_case_status(CaseStatus::Closed).await?;      // refused with an open obligation

The trap: treating put_case_state like a setter. It names the version it read, and a concurrent run that wrote first makes it fail — which is the lost update it exists to prevent. Re-read and decide again; do not retry the same write. Closing releases the correlation keys, so a closed case stops collecting new matter.

🏷️ Send untrusted content without giving it authority

Protect the fields that choose what the world will do rather than requiring every descriptive byte to be trusted:

let args = Tainted::object([
    ("recipient".to_owned(), Tainted::trusted(json!("treasury"))),
    ("memo".to_owned(), model_written_memo),
]);
let safety = ToolSafety::default()
    .protect(ProtectedField::trusted("/recipient"));
// The plane's destination allowlist. `cx.call_tool` applies it for you; a
// skill building its own catalogue hands it through.
let egress = cx.tool_egress();
let result = cx
    .sink_with(&args, |value| {
        ToolCall::prepare(&catalog, client, tool, value, egress.as_deref())
    })
    .await?;

The recipient must remain trusted; the memo may remain untrusted. sink_with hands the labelled value to the call and the gates in one motion, and the byte-for-byte binding check still runs underneath — canonical JSON is compared, so a call cannot validate args and dispatch a different recipient. Effects carrying outbound values are rejected by cx.effect, making this gate mandatory rather than conventional.

When a trusted process authorizes a change, release the smallest possible field and name the decision:

let args = cx.release(
    args,
    Release::fields(
        ReleaseScope::trust(),
        ["/recipient".to_owned()],
        "operator matched settlement SET-42",
        "tool://ledger/transfer",
        ["approval:SET-42".to_owned()],
    ),
).await?;

Policy evaluates data:release; the journal records releaser, prior label, scope, field, destination, basis and evidence. Provenance is retained, unrelated fields are unchanged, and the result remains Tainted<Value>. Run the complete success/refusal/release trail with cargo run --example governed_transfer --features manifest.

🎛️ Let an untrusted choice pick from a menu — no code, no release

When every acceptable value is known at review time, no release is needed at all: enumerate them, and an untrusted influence may choose among them and nothing else. This is the select-from-a-menu pattern from the prompt-injection-defense literature, and it is fully declarative — a manifest alone expresses it:

tools:
  - ref: "tool://ledger/transfer"
    mutates: true
    description: "Move funds between internal accounts."
    protected_fields:
      - path: /recipient
        one_of: [ops-account, audit-account]   # reviewed; the model chooses which
      - path: /amount
        allowed_sources: ["run.input"]

The match is exact structural equality — a near miss is a refusal, never a correction — and the menu layers over any source rule on the same field rather than replacing it. Write a menu only when every entry is acceptable whichever one is chosen: which entry stands is exactly what an injected prompt gets to pick. For a value no list can enumerate — a recipient parsed out of a document, say — bind the field’s provenance to a coded validator instead (allowed_sources: ["tool://agent/validate.recipient"]) and let that specialist canonicalise, check, and release with evidence: the manifest declares the bounds, code makes the judgment.

🔔 Wire durable A2A push

Push is a deployment capability, not merely a Cargo feature. Supply the same tenant-scoped durable store used by the runtime and a transport with an explicit host grant, take the worker handle, and only then sign the card:

use agentplane::api::a2a::A2aServer;
use agentplane::push::{PushPolicy, PushSender, PushStore, PushTransport};
use std::sync::Arc;

let sender = Arc::new(PushSender::new(
    PushPolicy::new().allow_host("hooks.customer.example"),
));
let server = A2aServer::new(runtime, authenticator, &security, &manifest, public_url)?
    .with_push(
        store.clone() as Arc<dyn PushStore>,
        sender as Arc<dyn PushTransport>,
    )?;
let worker = server.push_worker().expect("push was just configured");
let router = server.signing_cards_with(&card_signer)?.router();

// Run this from the deployment's scheduler on every instance. A saturated
// sweep means more due registrations exist, so drain another bounded batch
// immediately; otherwise wait until the next scheduler tick.
loop {
    // Unix seconds come from this operational scheduler's clock. The worker
    // never reaches for ambient time, which keeps backoff tests deterministic.
    let report = worker.run_once(scheduler_now, 100).await?;
    if !report.saturated {
        break;
    }
}

There is deliberately no hidden Tokio worker. Lifecycle, shutdown, frequency and alerting belong to the process supervisor. Delivery is at least once: a crash after the receiver accepts but before cursor persistence repeats the event, and receivers must be idempotent — every POST carries a webhook-id for exactly that. The journal is the outbox, so there is no task-transition/outbox dual write to lose. Configure push before card signing because pushNotifications is part of the signed document.

report.needs_attention() is what to alert on: it is true when the sweep was saturated or when it parked a registration, and false for an ordinary backoff — a receiver that is merely rebooting and one that will never answer again produce the same retries: 1 otherwise. Parked rows keep their cursors; read them with PushStore::parked and re-arm with PushStore::unpark.

📦 Keep large bytes out of the chain

The journal refuses a record over 1 MiB, because an append-only hash chain can never take it back. Bytes that big go in a content-addressed store, and the digest goes in the journal.

use agentplane::blob::{BlobStore, MemoryBlobs};      // or OpenDalBlobs, feature `opendal`

let blobs: Arc<dyn BlobStore> = Arc::new(MemoryBlobs::new());

// The store hashes the bytes; a caller does not get to say where they live.
let digest = blobs.put(&image_bytes).await?;

// Journal the address, not the payload.
let call = ModelCall::new(provider, model, json!({
    "system": "describe the attached screenshot",
    "screenshot": digest.to_hex(),
}));

For real deployments, OpenDalBlobs puts them on anything OpenDAL reaches — filesystem, S3, GCS, Azure:

cargo add agentplane --features opendal

use agentplane::blob::OpenDalBlobs;

let op = opendal::Operator::new(opendal::services::S3::default().bucket("agent-blobs"))?;
let blobs = OpenDalBlobs::new(op, "runs");

The trap: a reference that is not a digest. This is the claim check pattern every durable engine converges on, with one difference that carries the weight — because the address is the hash, the chain still commits to the exact bytes it does not contain. get re-hashes before returning, so a blob edited on disk is refused rather than served. A token pointing at mutable storage would move the tamper-evidence boundary without saying so, and the journal would still look sound.

Store through the context, not the store. cx.store_blob records which case the bytes belong to — a digest cannot be reversed later to find that out, so the association has to be made now or never:

let digest = cx.store_blob(&image_bytes).await?;   // linked to this case

Erasing later. A request names a person, which resolves to a case — never to a digest. So erase by case:

use agentplane::blob::erase_case;

let n = erase_case(Some(blobs.as_ref()), cases.as_ref(), &tenant, case, now, "art-17 request").await?;

Every blob that case produced is tombstoned; other cases are untouched, even ones holding identical bytes. For a single artifact, blobs.expire(digest, …) does the same for one address.

The chain still verifies — it committed to the digest, not the content — so you keep the proof of what happened without keeping the data. A read afterwards returns BlobError::Expired with the date and reason, never NotFound: retention doing its job and a blob nobody can account for are different answers, and only one of them is worth waking somebody for.

What it does not solve: scheduling, and anything already inside a record. There is no TTL — you decide when to call expire. And personal data written into a journal record cannot be removed at all, because the chain is append-only. The 1 MiB refusal keeps bulk content out by construction, but a short string still fits, so keep identifiers out of records deliberately.

📌 Pin a version so nobody can swap it

use agentplane::manifest::{MemoryRegistry, Registry};

let registry = MemoryRegistry::new();
registry.publish(&m).await?;

// Republishing 2.0.0 with different content is refused, not overwritten.
// Republishing *identical* content succeeds — a retried deploy is not an attack.

let m = registry
    .resolve_pinned("pattern-compliance-auditor", "2.0.0", governed_by)
    .await?;

Sign it, so the registry proves who as well as what:

registry.publish_signed(&m, &signer).await?;

let (m, key_id) = registry
    .resolve_verified("pattern-compliance-auditor", "2.0.0", &verifier)
    .await?;

resolve_verified returns the key that signed, because “it verified” is not the whole answer — which identity signed is what you decide to trust, and this crate never decides that for you. Unsigned and badly-signed come back as different errors: the first usually means it was published before signing was configured, the second means somebody tampered or a key rotated wrongly.

Signing can be enabled after an identical unsigned version was published: publish_signed attaches that artifact’s first publisher signature without changing its digest. Once present, publisher evidence is immutable too; another signer gets PublisherChanged rather than silently taking authorship. A version has at most one publisher.

The signature is over a domain-separated hash, not the manifest digest. A bare digest signature is structurally identical whatever it was about, so without this a record signature could be presented as a publisher’s blessing of an agent.

Pinning is not the same as trusting the registry. Immutability is a promise the registry makes about itself, so it is worth nothing if the registry is the compromised party. resolve_pinned is the caller declining to need that promise. Prefer it anywhere the answer decides what an agent may do.

MemoryRegistry is deliberately process-local; the redb and Postgres stores are the durable registries (below), and the Registry trait is the seam for a remote one.

🗂️ Keep the inventory where the agents are

MemoryRegistry proves the rules and dies with the process. Which agents does this organisation run — the first question a governance function asks — needs an inventory that outlives one, and a second registry kept beside the files drifts from them.

Both shipped stores are registries:

let store = Arc::new(RedbStore::open("./journal.redb")?);
store.publish_signed(&manifest, &signer).await?;

for name in store.names().await? {
    for version in store.versions(&name).await? {
        println!("{name} {version}");
    }
}

Everything the in-memory one refuses, these refuse identically — the rules live in one place (manifest::registry::decide_publish) and each backend only performs the decision, because three hand-written copies of “may this replace what is there” are three chances to get it subtly different.

The trap: read-then-write. Immutability is a claim about a race as much as about a rule — two publishes of different content both seeing “nothing there” is exactly the outcome it exists to prevent — so the read, the decision and the write are one transaction on both backends.

Registries are tenant-scoped, like every other table: metadata.name is whatever an author typed, so two tenants choosing one name is ordinary rather than exotic.

🏷️ Put the registry entry in the manifest

A governance catalogue wants business owner, technical owner, risk class and a ticket. A document closed by deny_unknown_fields cannot hold them as fields, and a second registry kept beside it drifts.

metadata:
  name: pattern-compliance-auditor
  version: "2.0.0"
  annotations:
    example.com/business-owner: "Compliance, F. Meier"
    example.com/risk-class: "C"
    example.com/ticket: "GRC-2291"

The runtime never reads it. No key here reaches a gate, a grant, a prompt or a decision, and there is no accessor that turns one into behaviour — so nothing here can become a security decision, which is what an advisory control would be.

The digest covers it, so changing an owner is a version bump with a reviewer on it. That is exactly what a governance process wants from an ownership record and what a wiki page cannot give it.

The trap: an unqualified key. owner is precisely the name a future first-class field wants, so keys must be prefix/name with a dotted prefix you control; agentplane.hupe1980.github.io/ is reserved for the same reason. A blank value is refused too — a key that answers nothing reads, to a reviewer, like a question that was answered.

Making it a rule rather than a convention. Because the runtime never reads the map, nothing in it can notice that a production agent shipped without an owner. That check belongs in review, and validate does it:

agentplane validate agent.yaml \
  --require-annotation example.com/business-owner \
  --require-annotation example.com/risk-class

Repeatable, exits 1 naming each agent and key that is absent, and checked per agent — in a room, “one of them has an owner” is not the rule anybody meant. The runtime still reads nothing: the keys stay your vocabulary and the enforcement is a job you run, which is the division --policy already draws.

🧯 Build a plane from a manifest you did not write

build() panics on a wiring mistake, and for a binary wiring its own skills that is right: every refusal is a bug in code the author is looking at, and ?-propagating it to a main that prints it is ceremony around an abort.

A manifest resolved from a registry is different. It is an input — possibly one tenant’s, in a process serving many — and there a panic reports one tenant’s typo by taking down every other tenant’s in-flight run. Use try_build:

use agentplane::runtime::{Agent, BuildError, Runtime};

let plane = match Runtime::builder(store)
    .agent(Agent::new(&resolved))
    .provider("anthropic", driver)
    .try_build()
{
    Ok(plane) => plane,
    // The variant matters, not just the failure: "this tenant named a provider
    // we do not have" is a message back to them, and a capability collision
    // between two of their agents is a different message.
    Err(BuildError::UnknownProvider { agent, provider }) => {
        return Err(onboarding_error(agent, provider));
    }
    Err(other) => return Err(other.into()),
};

Both entry points run the same checks — build is try_build with an expect, so the two cannot come to disagree about what is refused. Every variant is listed on BuildError, and each is a wiring mistake with a fix and no recovery: a capability nothing provides, two agents claiming one capability, two skills sharing a name, a catalogue laxer than a reviewed grant, a declarative agent naming an unregistered provider, or a plane whose store serves another tenant.

📚 Embed a directory of manifests

One file per agent, embedded in the binary, keyed by what each document declares:

let agents = agentplane::manifests![
    "agents/obligation-watch.yaml",
    "agents/clearing-triage.yaml",
]?;

let rt = agents.values().fold(Runtime::builder(store), |b, m| {
    b.agent(Agent::new(m))
}).try_build()?;

Manifest::parse_all is for a room — several agents in one file, because they are one deployable thing. This is the other layout, and the macro replaces the table an embedder would otherwise write by hand:

const AGENTS: &[(&str, &str)] = &[
    ("obligation-watch", include_str!(agents/obligation-watch.yaml)),
    ...
];

Two defects, both silent. The name beside each path is already in the document as metadata.name, so it is one fact written twice with nothing checking that the two agree. And a file included under two constants — which is what happens while adding the next agent — builds, runs, and registers one agent twice while the other is simply absent. The macro keys on the declared name and refuses a duplicate, naming both paths.

There is deliberately no glob: a macro that expanded a directory listing would make the set of agents a plane runs depend on what is on disk at build time rather than on what is in the source a reviewer reads.

✨ Use Google Gemini

let gemini = Gemini::from_env()?                      // GEMINI_API_KEY, or GOOGLE_API_KEY
    .safety(SafetySettings::new().block(
        HarmCategory::DangerousContent,
        HarmBlockThreshold::LowAndAbove,
    ));

Runtime::builder(store).provider("gemini", Arc::new(gemini)).build();

models:
  privileged: { provider: gemini, model: "gemini-3.5-flash" }

It speaks generateContent/streamGenerateContent natively rather than Google’s OpenAI-compatible endpoint, and the difference is not cosmetic. Gemini’s thinking models attach an encrypted thought signature to the parts they emit and reject a follow-up turn that does not carry it back. This driver keeps the model’s turn verbatim as opaque continuation state — the same way the OpenAI driver carries encrypted reasoning and Anthropic carries signed thinking — so there is no field to know about and none to lose.

reasoning_effort maps to Gemini’s thinking levels: minimal, low, medium and high exactly, and none, xhigh and max are refused rather than bent to the nearest one that exists — Google documents that thinking cannot be switched off on the Gemini 3 models. Schemas go to responseJsonSchema and are enforced during generation, never rewritten into Gemini’s trimmed dialect.

safety(..) passes the deployment’s own thresholds through, exactly as Bedrock::guardrail(..) does: this crate ships no classifier — a deployment’s own plugs in as a content checker — and what the runtime owns is that the thresholds are effect identity — loosening one between a run and its replay is divergence — and that an intervention is a metered refusal rather than an answer. A blocked prompt names its reason; a SAFETY stop carries the tokens it burned.

No sampling parameter (temperature, topP, topK, seed) is ever sent: none is in Request, so none could be in the effect key, and a knob outside effect identity is one a replay cannot account for.

🏠 Run a Hugging Face model locally

The de-facto wire of self-hosted inference is the OpenAI-compatible /v1/chat/completions endpoint — TGI (Hugging Face’s own server), vLLM, Ollama, llama.cpp’s server and LM Studio all speak it, and Hugging Face’s hosted router is one. So one driver reaches every local host, and the model stays behind a process boundary where an inference engine belongs — the plane never carries weights, a GPU toolchain, or an engine’s faults.

ollama pull llama3.2            # or: TGI, vLLM, llama-server, LM Studio…

use agentplane::model::chat_completions::ChatCompletions;

let local = ChatCompletions::new("http://localhost:11434")?;
let runtime = Runtime::builder(store)
    .provider("chat-completions", Arc::new(local))
    .agent(Agent::new(&manifest).skill(Triage))
    .build();

Or with no Rust at all — the same manifest runs against Ollama on a laptop, TGI on a GPU box, or Hugging Face’s hosted router, and its digest never changes, because where a model is served is deployment wiring, not part of the declaration:

  models:
    privileged: { provider: chat-completions, model: "llama3.2" }

CHAT_COMPLETIONS_BASE_URL=http://localhost:11434 \
    agentplane run triage.yaml --input '{"ticket": "printer on fire"}'

# The identical declaration against Hugging Face's hosted endpoint:
CHAT_COMPLETIONS_BASE_URL=https://router.huggingface.co/v1 \
CHAT_COMPLETIONS_API_KEY=$HF_TOKEN \
    agentplane run triage.yaml --input '{"ticket": "printer on fire"}'

The trap: believing “compatible” covers semantics. Every compatible server implements the shape; not every one counts. Usage is metered as reported — a server that reports none meters zero, visibly, rather than being backfilled with a guess — and structured output defaults to the forced-tool fallback because whether a server honours json_schema is exactly what cannot be assumed. A deployment that knows its server enforces it opts up with .structured_via(SchemaMode::Native). Two controls are refused outright rather than silently dropped: reasoning_effort (no neutral spelling on this wire) and governed media (a per-server dialect). Against api.openai.com itself, use the openai driver — Responses is the current primitive there.

🔁 Act on an at-least-once message exactly once

match rt.run_correlated_once(
    "claim.assess",
    Tainted::from_source(body, SourceId::new("bus")),   // it came from outside
    "claim",
    &[CorrelationKey::new("claim", &claim_id)],
    &event.dedup_key(),          // source ␟ id — the message's own identity
).await? {
    Admission::Fresh(outcome)    => /* we admitted it */,
    Admission::Replayed(outcome) => /* already done, or already waiting */,
    Admission::InFlight(run)     => /* already running — answer 202, not 500 */,
}

An emitter that retries until it sees a 2xx will redeliver on any lost response. The store claims the key in the same transaction that writes the run’s first record, so a redelivery cannot admit a second run — not on a retry, not across a restart, not from another instance sharing the store.

Correlation and the key answer different questions: correlation decides which matter the message belongs to, the key decides whether it is acted on at all. Correlation alone joins the duplicate to the right case and then starts a second run inside it.

The trap: a key that does not name its producer. An id is unique only within one emitter, so keying on a bare id lets two counterparties swallow each other’s messages as apparent retries — and the loser’s message is dropped silently. InboundEvent::dedup_key() is the ready-made spelling.

The other trap: reaching for EventStore::buffer instead. It also reports “already seen” for a (source, id) over the same store, and it looks like the primitive. It is not: an event nobody subscribes to is dead-lettered by the sweep, and a non-empty dead-letter list means a correlation key is wrong somewhere. Using the buffer as an idempotency ledger dead-letters nearly every message admitted directly, so SweepReport::needs_attention() is permanently true and that signal is spent buying deduplication.

A Replayed outcome carries the original’s status and reason but no output: a step’s result is reconstructed by replay rather than stored. Re-derive it with rt.replay(run, Mode::Strict), which performs no external effect. And note that a suspended run is a resting point — a redelivery of a message whose run is parked on a four-eyes decision is told this is already waiting for you, rather than opening a second identical approval.

spawn_correlated_once is the non-blocking form and returns Spawned { run, fresh }. Any other combination — a case binding, a chain per run — goes through spawn_under with RunTerms, which composes all of them.

The third trap: an empty key. A missing header or an unset variable arrives as "", and "" is a perfectly good key — the first message claims it and every later message is answered with the first one’s run, silently. It is refused, as is a key over MAX_ADMISSION_KEY_BYTES: the emitter chooses the key, so its size is not theirs to decide.

Retention. Keys are kept until you retire them. forget_admissions(older_than) is the verb, and the window must exceed your emitter’s retry horizon — a redelivery arriving after its key is retired admits a second run, which is the failure the key exists to prevent, delivered on a timer. There is deliberately no default: other runtimes bound this window automatically (Restate expires a key a day after completion, Temporal’s is its namespace retention), and both are making the same trade in the direction that can surprise you.

⏸️ Wait for a reply that may arrive first

let ack = cx.await_event(
    &AwaitSpec::new("acknowledgement.received", "acknowledgement")
        .correlate(CorrelationKey::new("document", &document)),
).await?;

The trap: the arrive-before-wait race. The obvious implementation matches inbound events against registered subscriptions on arrival and drops a miss — so a reply that beats its run to the wait is lost, and the run waits forever for something that already happened. A fast counterparty wins that race routinely.

Delivery here is buffer-first: every event is durably buffered on arrival, and a wait consults the buffer after registering. Both orderings converge on one delivery. You get this for free; the recipe is just to use await_event rather than rolling your own.

Every wait must name a deadline. An unbounded wait is a plan-contract violation, which is how “the process just stalled” stops being a category of incident.

The other trap: a correlation key is a business value, and any producer allowed to deliver the kind who knows it can answer your wait. When one party is expected to reply, name it — .from("peer:billing-svc") — and an event from any other source, by broadcast, from the buffer or delivered to the run, leaves the wait open. The name is the sender as this plane authenticated it: an event that arrives over the API or A2A carries peer:<actor>, where <actor> is what your authenticator returned for the caller (a CloudEvent’s own source attribute is not it), and one passed to Runtime::deliver in process carries the source its caller built it with.

👤 Require a human, with four eyes

let decision = cx.task(
    &TaskSpec::new("rejection-handling", justification, "decision")
        .role("compliance-officer")
        .excluding("agent:switch-bot")     // barred too; whoever asked for the run always is
        .on_expiry(Expiry::escalate_to(["compliance-lead"])),
).await?;

The trap: letting the request name the actor. Four-eyes is enforced against an actor, so a body that can name one is a bypass. The actor comes from the authenticated caller, and the wire type has no field for it — a caller cannot spoof what they cannot express.

The other trap: acting because nobody answered. It is spelled Expiry::ProceedUnattended and nothing else, so “the human didn’t answer so we did it anyway” is greppable. An escalation carries its roles (Expiry::escalate_to([..])) — one naming nobody is refused at the task.

From a terminal, agentplane tasks --store … lists the worklist (--role to see it as a reviewer holding that role does, --show <task> for one task whole) and agentplane decide <task> approve|reject --reason … --actor … answers it.

🔍 Show a reviewer the consequences, not the instruction

requires_approval: true shows the exact call — which for transfer(to: "GB-4471", amount: 12000) is the whole change. It stops being so when one call changes many things at once: archive(older_than: "2024-01-01") shows an instruction, and the four thousand records it will touch are nowhere on the reviewer’s screen.

The runtime cannot compute that preview; it needs the tool’s own dry run. What a manifest can do is name one:

tools:
  - ref: "tool://archive/purge"
    mutates: true
    description: "Delete every record older than a date."
    requires_approval: true
    preview: "tool://archive/purge_preview"
    protected_fields:
      - path: /older_than
        allowed_sources: [model:anthropic/claude-sonnet-5]
        max_sensitivity: internal
  # The preview receives the same arguments, so it needs its own ceiling: every
  # sink gate runs on it exactly as on the call it previews.
  - ref: "tool://archive/purge_preview"
    mutates: false
    max_sensitivity: internal
    description: "Count what a purge would delete."

The preview is dispatched before the task opens and its answer lands in Justification.evidence — an ordinary effect, so it is journaled, gated, metered, and replayed rather than repeated. What the reviewer saw is on the record beside what they decided; a long answer is cut at 64 KiB with the total and a digest of the whole stated on the row, never silently.

And it arrives labelled. A preview is the tool’s own answer over the caller’s data, which makes it the most persuasive line on the task and the one a compromised tool would write. evidence is Vec<Tainted<String>>, so it sits beside the runtime’s own notes without being mistaken for one, and GET /tasks/{task} reports has_untrusted_prose so a reviewer’s client cannot render the text and quietly skip the labels.

The trap: a preview that is not read-only. A dry run that changes the world is the opposite of a dry run, so a preview naming a grant this manifest declares mutates: true is refused at parse — along with a preview without requires_approval (nothing would call it) and one naming a tool the manifest does not grant (a call with no declared safety, ceiling or field rules).

If the preview fails, the task opens anyway and says so in the evidence. Refusing the call because its preview was unavailable would turn a read-only convenience into a second thing that can stop a payment.

🔔 Tell a desk without stopping the run

cx.task asks and blocks, which is right when the answer decides what happens next and wrong when nothing does. An agent that has finished, whose finding a compliance desk must see, does not need its run suspended — it needs a row in a worklist. Gating the answer to achieve that costs one suspended run per finding, at whatever rate the world produces them.

cx.open_task(
    &TaskSpec::new("deadline.breach", justification, "triage-breach")
        .role("grid-operations")
        .priority(Priority::High),
).await?;
// The run keeps going. Nothing resumes on the decision, because nothing waits.

Declaratively, that is spec.oversight.triage — a predicate over the declared output.schema and an audience:

oversight:
  approval: none
  deadline: { name: unused, kind: hours, params: { n: 4 } }
  triage:
    - name: breach
      summary: "a regulatory deadline was missed"
      audience: [grid-operations]
      when:
        - { path: /deadline_status, equals: BREACH }
      deadline: { name: triage-breach, kind: working-days, params: { n: 2 } }

The trap: expecting the taint gate to apply. It does not, on either path. A worklist row’s whole purpose is to put untrusted content in front of a person, so refusing untrusted content there would mean a task could only ever carry findings nobody needs to review. The label is still on the run’s journal; the control the reviewer is is the review.

The other trap: approval: none with an empty triage. That is an oversight block that performs nothing while reading in review as a human control, and it is refused at parse.

😴 Sleep for five working days

let at = cx.deadline("klaerung", &DeadlineSpec::new("working-days", json!({"n": 5})), None).await?;

The trap: tokio::sleep. A held task forgets everything on restart, and a process waiting five working days cannot be a thread. cx.sleep/cx.deadline persist the frame and let a sweep wake the run — a row on disk, not a task.

The subtler trap: recomputing the instant on replay. Calendars change — a corrected holiday table, a new regulatory notice — and recomputation would silently move a legally binding deadline under an audit. The resolved instant is journaled, so it is the fact forever.

Domain knowledge lives in your Calendar implementation. The engine does not know what a working day is.

↩️ Undo work when a later step fails

// Declare what a step's place in the unwind is.
Compensation::Compensatable   // reversible
Compensation::Pivot           // the point of no return; nothing before it unwinds
Compensation::Unnecessary     // nothing to undo
Compensation::Undeclared      // the default — judged on journal evidence

The trap: assuming an undeclared step has nothing to undo. Undeclared is resolved by reading the journal for mutating effects in that step’s forward phase. A step that changed nothing has nothing to undo and the journal proves it; a step that did change something and declared nothing stops the unwind and escalates, naming the step. Silently skipping a charge while reversing everything around it is exactly what the mechanism exists to prevent.

A run in doubt is never unwound. Compensating a payment that may never have gone out creates a refund for money nobody took.

Each compensatable skill implements compensate; the runtime invokes completed steps in reverse and journals those effects under Phase::Compensating. The complete runnable checkout example reserves inventory, charges payment, fails fulfilment, refunds, releases inventory, verifies the journal, and proves strict replay makes zero calls:

cargo run --example saga_checkout

🧬 Undo work when a call fails, not a whole step

A step-level compensation is handed the step’s output, and a step that failed does not have one. So a step that reserved inventory, authorised a card and then failed asks its own compensate to guess. Group the calls instead:

let mut g = cx.group("checkout", ["inventory", "payments", "notify"]).await?;

// Runs now. The reversal closes over what this call actually returned.
let hold = g.reversible("inventory", Reserve::new(&sku, 2), |out| {
    Release::new(out["hold"].as_str().unwrap_or_default())
}).await?;

let auth = g.reversible("payments", Authorize::new(amount), |out| {
    Void::new(out["auth"].as_str().unwrap_or_default())
}).await?;

// A read declares no reversal, because it has nothing to take back.
let stock = g.read("inventory", Look::new(&sku)).await?;

// Held at the gate: an aborted group never sends it.
g.deferred("notify", Notify::new("order confirmed"))?;

// The frontier. Past here nothing unwinds.
g.commit(&[Invariant::new("the hold covers the order", covered)]).await?;

The trap: putting the irreversible send in reversible with an apology as its undo. deferred is the stronger tool and costs nothing to use — the member does not run until the group is certain, so an abort leaves no trace anyone saw. A compensating email is a second email.

The second trap: treating the resource list as documentation. Every member names its resource and one outside the declared set is refused before it runs. A group that could touch anything has committed to nothing, and the frontier would be a boundary around nothing.

The third trap: reaching for a member that must go through cx.sink. An effect binding its own outbound arguments needs a labelled value checked against them, and a group has none to offer on its behalf. Do the sink call outside the group and let a plain effect be the member.

The fourth trap: expecting ? to leave the group alone. It does not — the executor reverses what the abandoned handle left standing, and a step that returns successfully with a group still open is reversed and failed. A group that commits by being forgotten would make the most consequential thing it does the thing that happens when you write nothing.

Reversals go through the ordinary effect path, so they are journaled, retried and metered like any other call and a replay does not perform them twice. Doubt reverses nothing: a member whose outcome cannot be established quarantines the run rather than unwinding around it.

🧱 Commit a member with the journal

If the table lives in the same Postgres as the journal, do not compensate — be atomic:

#[async_trait]
impl AtomicResource for PostEntry {
    fn descriptor(&self) -> EffectDescriptor {
        EffectDescriptor::new("ledger.post", json!({ "account": self.account }))
    }

    async fn apply(&self, tx: &dyn AtomicTx) -> Result<Value, EffectError> {
        tx.execute(
            "UPDATE ledger SET balance = balance + $2 WHERE account = $1",
            &[SqlValue::from(self.account.as_str()), SqlValue::from(self.amount)],
        ).await?;
        Ok(json!({ "posted": self.amount }))
    }
}

let mut g = cx.group("checkout", ["inventory", "ledger"]).await?;
g.reversible("inventory", Reserve::new(&sku), |o| Release::new(o))?.await?;
g.atomic("ledger", Arc::new(PostEntry { account, amount }))?;
g.commit(&[]).await?;

The member’s write and the record that it happened commit together. Nothing is externalised and taken back, so no reversal can fail; there is no in-doubt state, because a transaction either committed or did not; and if it refuses, the group is taken back whole — the cheap path, not a quarantine.

The trap: expecting the result. An atomic member returns nothing to the caller, because it has not happened yet when you register it and cannot be seen before the frontier it commits with. If a later member needs the value, it is not an atomic member — it is a reversible one.

The second trap: reaching for it on an embedded store. RedbStore has no notion of a foreign table, so it lends no transaction and the member is refused at registration. That is a capability being absent, and it is refused where refusing costs nothing rather than after the eager members have run.

🤝 Consult another agent, from a file

A grant spelled tool://agent/<capability> offers another agent’s capability to a tool-calling model — so a multi-agent room needs no Rust at all:

# editor.yaml — the only agent permitted to delegate, and it says why
spec:
  topology: { mode: collaborative, role: orchestrator, reason: distinct-authority }
  security: { max_delegation_depth: 1, max_sensitivity_egress: internal }
  capabilities: { provides: [blog.report] }
  models: { privileged: { provider: chat-completions, model: "llama3.2" } }
  tools:
    - ref: tool://agent/research.summarise
      description: Ask the researcher to summarise a topic.
      arguments:
        type: object
        properties: { topic: { type: string } }
        required: [topic]
  execution: { kind: tool-calling, max_turns: 4 }
  budgets: {}

# researcher.yaml — a specialist, structurally unable to delegate further
spec:
  topology: { mode: single, role: specialist }
  security: { max_sensitivity_egress: internal }
  capabilities: { provides: [research.summarise] }
  models: { privileged: { provider: chat-completions, model: "llama3.2" } }
  execution: { kind: completion }
  budgets: {}

Dispatch is commission, not a transport: the consultation is a journaled delegation effect, so a strict replay reassembles the whole room without waking anyone, the researcher’s answer arrives labelled untrusted, its spend bills the editor’s run, the depth ceiling sees the hop, and the journaled answer names the researcher’s sub-run (run). The agent server name is reserved — wiring a transport under it is refused at build, and a grant naming a capability no agent on the plane provides refuses the build too, rather than offering the model a consultation that fails when chosen.

The blog_room example runs both shapes side by side — a coded editor that dictates the sequence, and this desk, on one plane. And the whole YAML room lives in one file: examples/room.yaml holds all three manifests separated by ---, so the CLI runs it directly — agentplane run examples/room.yaml --input '{"topic": "..."}' — starting at the room’s one declared orchestrator. Each document keeps its own digest; the file is packaging, not identity.

The trap: treating the grant like a transported tool. It is not one, and the parser says so: mutates: false is refused (what the specialist does to the world is its declaration’s statement to make), and protected_fields / max_sensitivity are refused because the commission path never passes the sink gate those act at — declare ceilings on the consulted agent instead. Two ceilings interact by design: a commissioned input is Internal at least, so both agents need max_sensitivity_egress: internal or the room refuses its own point. requires_approval: true works exactly as on any grant — a person sees the capability and the arguments before any specialist runs, and beside them what the specialist’s own declaration lets it do; the approval covers that revision (security).

🌐 Call another plane’s agent, from a file or a skill

A peer is a server name a grant can carry. Register it on the plane — where it is, what it is granted, which credential reaches it — and a manifest grants its capabilities like any tool’s:

# desk.yaml — consults a reviewer that runs somewhere else
spec:
  topology: { mode: collaborative, role: orchestrator, reason: distinct-authority }
  security: { max_delegation_depth: 1, max_sensitivity_egress: internal }
  capabilities: { provides: [desk.answer] }
  models: { privileged: { provider: openai, model: gpt-4o-mini } }
  tools:
    - ref: tool://reviewer/audit.check      # `reviewer` is a registered peer
      mutates: false
      max_sensitivity: internal
      description: Ask the reviewer to check an invoice.
      arguments:
        type: object
        properties: { invoice: { type: string } }
        required: [invoice]
  execution: { kind: tool-calling, max_turns: 4 }
  budgets: {}

AGENTPLANE_PEER_TOKEN_REVIEWER=... \
agentplane run desk.yaml --input '{"invoice": "INV-9"}' \
  --peer reviewer=https://reviewer.example/a2a --acting-as alice

--peer wires the A2A client for that name (needs --features cli,a2a, or the :full image); the registry scope is exactly the capabilities the manifests grant under tool://reviewer/…, the registration is read-only when every such grant says mutates: false, and the bearer token comes from the environment, never the command line. --acting-as is required beside it: a peer call is made on somebody’s behalf, so the run’s chain is rooted at that subject and scoped to what the file declares — the capabilities it provides and the ones it grants under a peer’s name — and the peer receives that chain plus one link naming it. --peer without it does not parse, rather than letting the model be offered a peer every call to which is refused. In Rust the same wiring is one builder call, and a coded skill reaches the peer through the plane rather than through a client it carries:

let registry = PeerRegistry::new().allow(
    PeerId::new("reviewer"),
    PeerGrant::new(Scope::of(["audit.*"]))
        .read_only()
        .with_credential(&PeerId::new("reviewer"), credential),
);
let client = A2aClient::new(Endpoint::new("https://reviewer.example/a2a"))?;
let rt = Runtime::builder(store)
    .peers(registry, Arc::new(client))
    .acting_as(chain)
    .skill(Desk)
    .build();

// inside `Desk::invoke`
let verdict = cx.call_peer(&PeerId::new("reviewer"), "audit.check", &input).await?;

What governs the hop is the point. It is checked against the run’s chain plus one link naming the peer — the caller’s chain on a served plane, cx.acting_as() — so a chain with no room for another hop refuses at the desk. The peer receives the credential, not the chain, and its own authenticator decides what it acts under. The grant governs the hop as it governs a tool: its protected_fields and max_sensitivity are checked at the sink, mutates: true puts the whole-value taint gate in front of it, requires_approval puts a person in front of it. The answer comes back untrusted, labelled tool://reviewer/audit.check, so a source rule downstream can name this peer’s word and nobody else’s. And it is an effect — journaled, metered, counted against max_delegation_depth, read back on strict replay without a request leaving.

Three things are refused at build rather than on every run: a peer name that is also a wired tool server (a grant would mean two things), a manifest grant naming a capability outside the peer’s registry scope, and a peer grant on a specialist (a hop is delegation). A run admitted under no chain has nothing to extend and is refused at the call — admit it with RunTerms::acting_as, build the plane with RuntimeBuilder::acting_as, or pass --acting-as to agentplane run.

The peer_call example runs both planes in one process: a served reviewer on a loopback port and a desk that consults it with a credential naming the run’s owner, so the reviewer acts for Alice through the desk — then a strict replay of the desk’s run that the reviewer never hears about.

🗺️ Plan once, then execute without the model

When the task’s shape is known up front and the data the tools return is hostile, kind: planned beats the loop: one privileged call fixes the steps before anything untrusted is read, and step outputs travel between steps as references no model reads.

spec:
  execution: { kind: planned, max_turns: 4 }
  models:
    privileged:   { provider: anthropic, model: claude-sonnet-5 }
    quarantined:  { provider: anthropic, model: claude-haiku-4-5 }

The planner answers with steps like { "tool": "crm__lookup", "args": "{\"id\": \"$input/customer\"}" } — the references are resolved by the runtime, labels intact, and args is JSON text because constrained decoding has no free-form object. A parse step hands a prior output to the quarantined model under a bounded schema.

Freezing control flow is half the defence; the grant carries the other half. Because a reference arrives at the sink with the provenance of the value it names, a rule like the recipient must be what the CRM returned is genuinely enforceable — declare the mailer mutates: true with protected_fields: [{ path: /to, allowed_sources: ["tool://crm/lookup"] }], and a recipient the planner writes as a literal is refused at the sink: a model completion is not among the allowed sources, however well-shaped the string. Run cargo run --example planned_run --features redb,fake-model,manifest to watch both: a prompt injection arrive in a tool output and find no reader, and a planner-invented recipient stop at the field rule. just camel-live runs the same shape against two real OpenAI models and asserts, at the wire, that the injection was in the quarantined prompt and in no other.

The trap: planning over untrusted input. It is refused outright — the planner reads the input to write the plan, so hand hostile content to a tool or a parse step instead, or use tool-calling.

🧱 Where are the built-in tools?

There are none.

The tools they ship are mostly provider-hosted — ADK’s Google Search and Code Execution, the OpenAI Agents SDK’s WebSearchTool and CodeInterpreterTool. Those run on the provider’s servers during generation. Here a world-visible action is an effect: announced durably before it acts, authorized against the agent’s declaration, metered against a budget, and read back from the journal on replay. A hosted tool is none of those and cannot be made into any of them, because by the time the completion comes back the call has already happened. Accepting one would put an action outside the journal, which is the single thing this runtime exists to prevent.

For tools that run in this process, the domain-neutral ones already have governed homes: fetching a URL is the media feature, with SSRF, DNS-pinning and content controls a generic http_get would have to reimplement badly; running untrusted code belongs behind an OS process boundary as an MCP server, not inside the deterministic zone. What is left is a connector catalogue — and a catalogue is authority somebody has to review, entry by entry, forever.

What you get instead: execution.kind is the built-in behaviour — completion, tool-calling and planned are the prebuilt agent loops, minus the part that runs outside the journal — and a typed Tool is about fifteen lines.

🛠️ Call a tool from a skill you wrote

Use cx.call_tool. It dispatches over the plane’s own catalogue — the one try_build already checked against every agent’s declaration:

let overdue = cx
    .call_tool(
        ToolId::new("obsd", "list_overdue_processes"),
        Tainted::trusted(json!({ "since": cutoff })),
    )
    .await?;

The trap it removes: building a ToolCatalog inside the skill. That is the obvious thing to write, it compiles, it runs, and nothing binds it to the manifest governing the skill — so the reach it grants is whatever the code says. Worse, it can be laxer: ToolSafety::read_only for a tool the manifest calls mutating exempts it from the whole-value taint gate and carries Recovery::Retry, so a timed-out money-moving call is sent a second time. try_build refuses exactly that divergence for the plane’s catalogue; a catalogue constructed inside a skill never passed under that check.

Where a skill genuinely needs its own — assembled before a runtime exists, or one for a test — derive it with ToolCatalog::from_manifest(&m), which reads the reach off the declaration instead of restating it. See examples/governed_transfer.rs.

🔌 Call tools on an MCP server you already run

The tool tier is not “your tools, MCP-shaped”. tools::McpClient is a real MCP client: point it at a running server and its tools become callable under the ordinary governed path — declaration, protected fields, egress ceiling, budget, disposition and all.

Wiring is two lines. McpClient::connect takes the transport — stdio, a child process, streamable HTTP — and runs the lifecycle; where the transport goes is yours to state, because this crate never dereferences an MCP URL:

use agentplane::tools::{Destination, McpClient, ToolBox};

// One name per server. It is *your* name for it, not one the server chose:
// the catalogue keys on it, and a server able to rename itself could step
// into another server's entry.
let tickets = Arc::new(
    McpClient::connect("tickets", transport, Destination::remote("mcp.tickets.example")).await?,
);

let rt = Runtime::builder(store)
    .agent(Agent::new(&manifest))
    .toolbox(ToolBox::new().with::<ReadBalance>())   // tools in this binary
    .tool_server("tickets", tickets)                 // tools on that server
    .egress(Egress::new().allow("mcp.tickets.example"))
    .build();

The trap: starting the client yourself with rmcp’s .serve(transport). That is the initialize handshake, which 2026-07-28 replaced with server/discover, so a plain initialize negotiates down to a legacy dialect every time — tools/call keeps working, the tasks extension and structured results simply never appear, and nothing says why. connect discovers first and falls back to initialize only when the server is legacy; the version it landed on is readable as negotiated_version(), and agentplane serve prints it. McpClient::new wraps a service you already started, for an embedder whose transport is running.

The client profile connect offers (McpClient::host_info()) negotiates the Tasks extension and nothing else: elicitation, sampling, roots and subscriptions are absent, because none has a governed runtime callback.

MCP context is available without turning it into a tool. Exact grants may live in the manifest:

context:
  prompts:
    - server: templates
      name: summarize
      max_input_sensitivity: internal
  resources:
    - server: knowledge
      uri: kb://support/rules
      output_sensitivity: internal

Derive the deployment catalogue with McpAccess::from_manifest("templates", &manifest), then use McpClient::prompt or McpClient::resource and dispatch the returned value via cx.effect (or cx.sink for prompt arguments). Both results are untrusted and strict replay performs no second MCP request.

An asynchronous tool result is not flattened into an apparent answer. McpTask::from_result preserves its handle; client.task(handle) prepares a journaled tasks/get effect. update_task binds the exact labelled input responses and defaults to operator recovery, while cancel_task is an idempotent cooperative request followed by another poll. The cancellation ack is never presented as evidence that the server stopped.

The manifest grants both the same way, because a reference names which tool and never which wire carries it:

tools:
  - ref: tool://ledger/read      # a typed Rust tool in this binary
    mutates: false
    description: Read a ledger account's balance.
  - ref: tool://tickets/read     # a tool on the MCP server above
    mutates: false
    description: Read a support ticket.

That is also why one manifest can run against an in-process double in a test and a real server in production: the transport is a deployment decision, not something the reviewed file claims.

One client per server, resolved by name. A ToolRouter does the resolving, and it matters more than it looks: a single client handed every tool id cannot tell tool://ledger/read from tool://tickets/read, so a plane that granted one and wired the other would get a successful answer from the wrong server under the first one’s operator safety. A server nobody wired is Unreachable, and a grant naming one is refused at build rather than at the first call.

discover() is a diff, not a source

An MCP server advertises its tools with annotations — readOnlyHint, destructiveHint, idempotentHint — and the obvious convenience is to import that list and build a catalogue from it. That is the one thing this client will not do, and the specification agrees: clients must consider annotations untrusted.

The composition is what makes it dangerous here rather than merely untidy. readOnlyHint: true would mean the effect does not mutate; a non-mutating effect defaults to Recovery::Retry; and a retried call is a second real call. So a server that marked its own money-moving tool read-only would be choosing, from the far side of the trust boundary, the one condition under which this runtime does something twice.

So discover() returns what the server says for comparison:

for (id, advertised) in tickets.discover().await? {
    if let Some(safety) = catalog.safety(&id) {
        // Not an error — a server is entitled to describe itself and an
        // operator is entitled to disagree. It is worth an alert because a
        // server that *starts* claiming to be read-only after an update is
        // what a swapped-out or compromised server looks like from here.
        if advertised.overclaims(safety) {
            tracing::warn!(%id, "server claims more safety than the operator granted");
        }
    }
}

The trap: treating discovery as configuration. A tool absent from the operator’s catalogue cannot be called however the server advertises it, and that is the property. Auto-import would let a server widen its own authority — which is exactly what Advertised versus ToolSafety exists to prevent.

🧾 When the two parties really do differ

.toolbox(..) covers the common case, where the tools a binary implements are the tools its agents declare. The two-party split is still there when it is real: an operator who wants to say something different from the agent’s author builds the catalogue themselves and passes it with the client:

let catalog = ToolCatalog::from_manifest(&manifest)
    .allow(ToolId::new("ledger", "read"), ToolSafety::read_only());

let rt = Runtime::builder(store)
    .agent(Agent::new(&manifest))
    .tools(Arc::new(catalog), client)
    .build();

The manifest’s own grant is re-checked at dispatch either way, so a catalogue can only narrow what a declaration asked for, never widen it.

Wiring both forms on one plane is refused, not merged: one would silently replace the other’s grants and nothing would say which won.

The trap: believing the catalogue is the security boundary on its own. It is one of two: the manifest is inside the agent’s digest, the catalogue is the deployment’s. A tool absent from either is not callable.

⚖️ Turn on a policy engine

The policy text is in security; this is the wiring.

use agentplane::policy::CedarEngine;

let engine = CedarEngine::new(std::fs::read_to_string("policy.cedar")?.as_str())?;
let runtime = Runtime::builder(store)
    .policy(Arc::new(engine) as Arc<dyn PolicyEngine>)
    .skill(MySkill)
    .build();

CedarEngine::from_bundle takes a schema and static entities too, and validates the policies against the schema at startup — a policy set that cannot compile should fail when you deploy it, not on the first request that needs it.

Three things bite:

• There is no AllowAll. No engine wired means no gate; a permissive engine and no engine are the same behaviour, so having two spellings is how a plane ends up with a policy layer everyone believes is on.
• A broken policy denies everything, and says so differently. Cedar is total, so a rule that fails to evaluate simply does not contribute and the answer is a clean Deny. That is reported as malformed rather than as a refusal — policy_error=true in the tracing event — because “the rules say no” and “the rules are broken and nobody noticed” call for opposite responses.
• The runtime’s gates see no caller roles. run:admit and effect:perform are asked by the runtime, which has a plan and a delegation chain, not an HTTP request. context.roles exists on the api:* and a2a:* actions only; to key the runtime’s gates on who asked, give the caller a delegation chain — a scope on its token-file entry, or Caller::acting_as from your own Authenticator — and its owner/subject/scope are merged into those requests for every run that caller starts. A caller whose credential carries no chain acts under none: the plane’s own RuntimeBuilder::acting_as is for the runs its embedder starts, and is never lent to a served caller. It is still the caller’s ceiling — a chainless caller asking for a skill outside the plane’s chain is declined, and its commissions count depth from the plane’s — without anything of it reaching the policy context or the journal. A surface that serves strangers therefore also probes the runtime’s gates in the no-chain shape at startup, and refuses a rule set that cannot evaluate it.

📡 Host an agent as an A2A peer

agentplane serve examples/served.yaml \
  --url https://agent.example.com/a2a --addr 0.0.0.0:8080 \
  --policy policy.cedar --tokens tokens.yaml --store ./served.redb \
  --operator-addr 127.0.0.1:9090 --push-host hooks.example.com

Serves the public Agent Card and the A2A 1.0 methods, sweeps deadlines and due timers every 30s, and — on a separate listener — the operator surface: GET /runs?outcome=quarantined, the worklist, task decisions. The two are separated by policy — the example bundle gives peer the A2A actions and operator the API ones it uses — so the port split is defence in depth rather than the control.

The worklist’s claim protocol has three verbs, and the third has its own policy action on purpose. A reviewer claims a task and only the holder can release it — which leaves the absent-holder case: a task claimed by someone who is not coming back is parked until its deadline breaches. POST /tasks/{task}/takeover (api:task.takeover) displaces a named holder — the body’s from is a compare-and-swap, so a stale queue view fails rather than displacing whoever holds it now — and re-checks eligibility in full: a take-over is a claim, and four-eyes exclusion does not thin because the previous reviewer left. Its own verb means a policy set can hand it to a queue lead without handing displacement to every reviewer.

--policy, --tokens and --store have no defaults. A served task’s id is a promise it can be fetched again, which an in-memory journal breaks at the next restart. Needs --features cli,a2a-server,cedar, or the :full image. The full walkthrough is in getting started.

A token-file entry may carry the caller’s own authority:

- token: "3f9c…"                    # openssl rand -hex 32; under 32 bytes is refused
  actor: peer-a
  roles: [peer]
  scope: [support.*]                # what runs peer-a may start
  not_after: 2027-01-01T00:00:00Z   # refused at admission once passed

Every run peer-a starts is then admitted under a chain rooted at peer-a, bound to this plane’s tenant, and the journal’s IdentityBound names peer-a — not the plane. A message naming a skill outside the scope is declined; a message after the instant is refused with the expiry named. Leave both out and the caller has no chain: its runs act under none, bounded by whatever chain the plane was built with — which for serve is none.

🛑 Stop an instance without turning it into a crash

agentplane serve does this for you on SIGTERM — the recipe is for an embedder serving the plane from their own process.

use std::time::Duration;

// Both at once, and that is the point. Your server's graceful shutdown finishes
// the requests already being served — including a run one of them is awaiting —
// while `drain` closes admission and waits for the runs this plane put on a task
// of its own. Serialising them deadlocks one on the other.
let (report, served) = tokio::join!(
    runtime.drain(Duration::from_secs(25)),
    axum::serve(listener, app).with_graceful_shutdown(async { stop.notified().await }),
);
served?;
if !report.is_complete() {
    tracing::warn!(
        settled = report.settled(),
        unfinished = ?report.unfinished,
        "the grace period ended with runs still executing"
    );
}

Why it is worth the twenty lines: an announcement goes into the journal before a call leaves, so a process killed in between leaves an outcome nothing can decide — and the effect’s declared Recovery has to answer, which for anything not safe to repeat means a person. Draining turns the ordinary case of a deploy back into an ordinary conclusion.

The grace period is a bound, not a promise. Runs still executing when it ends keep their leases, stop being renewed, and are taken over by the recovery sweep on the path a crash takes — which is why drain does not hand those leases back: a release says takeover is safe, and the next owner would re-perform a call still in flight here.

What it does not wait for: a run you await yourself belongs to your task, and your server’s graceful shutdown is what finishes it. What it does not refuse: resumes, and an agent commissioning another one — both are work this plane already owns.

If you serve the A2A surface, closing admission is also what ends open subscriptions. A stream is a long poll over the journal, so one watching a run that has not concluded would keep its connection — and your graceful shutdown — open for as long as that run lasts.

📤 Emit an event per run, without an outbox table

A2A push is caller-shaped: the URL comes from whoever created the task, which is why three controls sit around it. The shape a service wants beside it is the mirror — one destination the deployment configured, receiving one payload the embedder shapes, for every run.

use agentplane::push::{Destination, DeliveryWorker, Outbox, PushSender, RunCompleted};

let outbox = Arc::new(Outbox::new(
    Arc::clone(&store) as Arc<dyn PushStore>,
    vec![Destination::new("bus", "http://events.internal/ingest")],
));
let rt = Runtime::builder(store).agent(..).outbox(Arc::clone(&outbox)).try_build()?;

// Scheduled by the operator, like every other sweep.
let worker = DeliveryWorker::new(
    Arc::clone(rt.journal()),
    Arc::clone(&store) as Arc<dyn PushStore>,
    Arc::new(PushSender::for_operator_destinations(outbox.destinations())),
    Arc::new(RunCompleted::new("urn:mako:agentd")),
);
let report = worker.run_once(now_secs, 100).await?;

Each destination is registered against a run at admission, so there is no window in which a run exists and nothing is watching it; delivery then reads the run’s own records past a durable cursor that advances only on 2xx. There is no outbox table to fall out of sync with the history — the journal is the outbox, which is the point.

RunCompleted emits one CloudEvents 1.0 message per sealed run — posted as Content-Type: application/cloudevents+json; charset=UTF-8, which is what a CloudEvents receiver routes on — carrying the run id, the case, the outcome and the chain head. It deliberately does not carry the answer: a run’s output is domain data with a label on it, and a default that shipped it would make an egress decision nobody declared. Implement Projection to shape your own; a PushMessage carries its own media type and its own id, so your wire is not the default’s.

Every delivery also carries webhook-id and webhook-timestamp. The id is the receiver’s idempotency key — at-least-once delivery repeats events on an ordinary crash, so a receiver that cannot recognise a repeat runs the same work twice.

What is relaxed, and why it is not a weakening. An operator destination skips the host allowlist (there is no caller to check — the URL is in the deployment’s own configuration), HTTPS (an in-cluster collector on plaintext HTTP is ordinary, and refusing it pushes operators toward a TLS-terminating sidecar that forwards in clear) and the public-address check (resolving inward is the entire point). The cursor discipline, the retry ceiling, the park-and-report on a permanent refusal, and the no-proxy/no-redirect posture are all unchanged.

When a receiver stops answering. 410 Gone stops delivery at once — it is the one status no wait improves. Everything else is transient (a 404 mid-deploy and a 401 mid-rotation are answers that change), retried on an exponential schedule spread by a hash of the registration so a recovering receiver is not hit by its whole backlog at one instant, and honouring Retry-After up to an hour when the receiver named one. Past the ceiling — or on a permanent answer — the registration is parked, not deleted: it keeps its cursor, drops out of the due order, and shows up in PushStore::parked. An operator who fixes the receiver calls PushStore::unpark, and delivery resumes at the first record that receiver never acknowledged.

for row in store.parked(100).await? {
    tracing::warn!(task = %row.config.task, id = %row.config.id, error = ?row.last_error);
    store.unpark(row.config.task, &row.config.id, now_secs).await?;
}

The trap: reusing an id in the operator namespace. Both kinds of registration share one store and are told apart by the operator: prefix; the A2A server refuses a caller-supplied pushNotificationConfig.id that begins with it, because operator destinations are exempt from the URL controls precisely on the grounds that there is no caller involved.

✍️ Sign the body a destination receives

A bearer header proves the sender held a token — a claim about the connection, not about the bytes — and that token transits every hop between here and the receiver. Signing is the other claim, and destinations take both:

let bus = Destination::new("bus", "http://events.internal/ingest")
    .authenticated("Bearer", Secret::new(std::env::var("BUS_TOKEN")?))
    .signed_with(&Secret::new(std::env::var("BUS_SIGNING_KEY")?));

This is Standard Webhooks, so a receiver verifies with a library it did not write. Every delivery carries three headers:

Mid-rotation, chain .also_signed_with(&new_secret) onto the destination: every delivery is then signed under both keys, a receiver holding either verifies, and the old secret retires at the receiver’s pace instead of on a flag day.

The id and the timestamp are inside the signed content, which is the point: a signature over the body alone is a genuine body genuinely signed, so a captured POST replays forever. A receiver that refuses timestamps outside a tolerance window and deduplicates on webhook-id has a delivery that expires — neither half works alone.

A secret spelled whsec_<base64> names base64 of the key, which is what a receiver’s library will decode; anything else is the key itself. Keys shorter than 24 bytes are refused where they are configured. The key is never written to the push store: it is deployment configuration read at every start, so there is no copy of a forge-anything key sitting in a row per run, and rotating it takes effect on the next sweep rather than on the next admission. That is why for_operator_destinations takes the destinations — a sender built without them would deliver unsigned, and only the receiver could ever notice.