Build with pap://

From prompt to mandate

The part people don't believe is that you can type a sentence and end up with delegated authority. Here is the honest answer: the sentence never becomes authority on its own. It gets classified into a named action, and then a human signs a mandate for that action. Two separate steps — and the second one is a person's key, not a model's guess.

Classification runs in three levels, cheapest first. A bare URL is a deterministic shortcut — it routes straight to a read action with no scoring at all. Anything else is ranked with BM25, the same term-frequency method a search engine uses, against the catalog of available agents: "book a hotel in Paris" scores against a lodging agent and resolves to a reserve action. Only when BM25 has no confident match does the prompt go to an NLU classifier for a considered read. Each level is inspectable; none of them is a black box that mints power.

Whatever the pipeline resolves to is just a proposal. It becomes a single ScopeAction, wrapped in a Scope, and the principal signs it. The signature is the grant. If the classifier misreads the prompt, the worst case is a mandate scoped to the wrong action — which the receiver can still reject, and which a delegation can only narrow, never widen. The prompt is evidence of intent; the human's key is what turns intent into authority.

use pap_core::mandate::Mandate;
use pap_core::scope::{DisclosureSet, Scope, ScopeAction};
use pap_did::PrincipalKeypair;

// 1. Classify the prompt into a schema.org action. Cheapest level first:
//      • bare URL           → "schema:ReadAction"     (deterministic)
//      • BM25 catalog match → e.g. "schema:ReserveAction"  (term-frequency rank)
//      • no confident match → NLU classifier ("schema:AnalyzeAction")
let prompt = "book a hotel in Paris";
let (resolved_action, _preferred_agent, _query) = route_intent(prompt, &catalog);
//   resolved_action == "schema:ReserveAction"

// 2. The resolved action is a PROPOSAL. It becomes one ScopeAction, and the
//    human principal signs the mandate. The signature is the grant of authority —
//    the scope is derived from classification, never hardcoded.
let principal = PrincipalKeypair::generate();
let mut mandate = Mandate::issue_root(
    principal.did(),
    orchestrator.did(),
    Scope::new(vec![ScopeAction::new(&resolved_action)]),
    DisclosureSet::empty(),
    ttl,
);
mandate.sign(principal.signing_key()).unwrap();

// A misread prompt can only produce a narrower, rejectable mandate —
// delegation can never widen scope past what was signed.

The resolved action becomes the mandate scope, then the principal signs it — adapted from examples/intent-routing. The scope is derived from classification, never hardcoded.

The prompt proposes. The signature grants. A misclassified prompt cannot widen scope past what was signed — it can only produce a narrower, rejectable mandate.

The six-phase handshake

A transaction between two agents is a six-phase handshake, driven by AgentClient against the receiver's AgentServer. Use run_full_handshake for standard sessions: it sequences the phases in the required order and makes Phase 5 — the co-signed receipt — mandatory, so a session cannot silently skip its accountability record.

The mandate TTL is checked before the network I/O of every phase, and any protocol error closes the session before returning. The low-level phase methods — present_token, exchange_did, send_disclosures, request_execution, exchange_receipt, close_session — are there for streaming or custom recovery, but they make it easy to omit Phase 5, so prefer the high-level call.

On the receiving side, implement the AgentHandler trait and serve it with AgentServer. The animated walk-through of all six phases lives on the protocol page. See the animated handshake →

use pap_transport::client::AgentClient;

let client = AgentClient::new("https://receiver.example");

// The recommended high-level call: it sequences all six phases in order
// and makes Phase 5 (the co-signed receipt) mandatory.
let (receipt, result) = client
    .run_full_handshake(
        token,                    // signed CapabilityToken authorising this interaction
        initiator_session_did,    // ephemeral: pap_did::SessionKeypair::generate()
        vec![],                   // SD-JWT disclosures — empty for a zero-disclosure session
        pre_signed_receipt,       // TransactionReceipt half-signed by the initiator
        mandate_expires_at,       // TTL, re-checked before every phase
    )
    .await?;

// `receipt` is co-signed by both parties; `result` is the Schema.org JSON-LD output.

run_full_handshake sequences all six phases and returns the co-signed receipt with the Schema.org result.

Sandboxed execution

Wrap any AgentHandler in SandboxedHandlerWrapper to run the approved action under OS-level confinement. A CapabilityPolicy sets the limits — execution timeout, and whether network, filesystem, and subprocess access are allowed. Everything defaults to denied.

What actually enforces those limits depends on where you run. The receipt never claims a protection that didn't run: the AttestationReceipt records an EnforcementBackend, and its CapabilityProof reports what was actually applied, never what the policy requested.

use std::sync::Arc;
use pap_sandbox::{CapabilityPolicy, SandboxedHandlerWrapper, new_spawner};

// Everything is denied by default. Grant only what the action needs.
let policy = CapabilityPolicy {
    execution_timeout_secs: 30,
    network_allowed: false,
    filesystem_allowed: false,
    subprocess_allowed: false,
    ..Default::default()
};

let wrapped = SandboxedHandlerWrapper::new(
    inner_handler,          // Arc<dyn AgentHandler>
    new_spawner(),          // picks the enforcement backend for this OS
    policy,
    true,                   // sandbox_enabled
    agent_did,
    agent_name,
    "schema:SearchAction",  // action_type
);

// After a run, the co-signed AttestationReceipt reports the EnforcementBackend
// that actually ran and, in its CapabilityProof, exactly what was applied —
// never what the policy merely requested.

See the execution boundary in motion →

A word on LangChain, CrewAI, and MCP

There is an integration guide that shows pap:// bolted onto these frameworks, and its code is accurate. We are keeping it honest by telling you what we found when we tried: these stacks can't actually behave with pap://, and the reason is architectural, not a missing feature.

They were built around one shared context that every agent in the graph can see, with a hosted model provider as the root of trust. pap:// exists to remove exactly those two things. A mandate check placed in front of a framework call can refuse the call, but it cannot un-share the context the framework already handed to the model, and it cannot confine execution the framework runs in-process. You get a signature on the doorway and an open floor plan behind it — half a trust model, which is the thing pap:// was built to end.

So our guidance is to not wrap these frameworks and call it done. Build against pap:// directly — issue the mandate, run the handshake, sandbox the execution — so both boundaries are real. The integration guide is there if you have existing code to bridge during a migration, but treat it as a transition, not a destination.