Extensions Reference

Field-level reference for Mandrel-specific governance controls and the spec.extensions plugin extension block.

This document covers two kinds of extensions in the Mandrel Spec:

  1. Mandrel governance fields — the built-in governance, network, and runtime blocks that extend the baseline A2A Agent Card.
  2. Plugin extensions (spec.extensions) — a free-form block where partner plugins attach their own configuration.

Governance (governance.*)

risk-profile

Defines the fallback posture during ambiguity.

ProfilePostureBehavioral Delta
safety-firstFail-ClosedTerminate execution if any constraint is ambiguous.
balancedChallengeTrigger Step-Up HITL for high-variance decisions.
efficiency-firstFail-OpenProceed and log for asynchronous audit.

enforcement-matrices

The primary engine for Tiered Governance.

  • type: threshold (numeric) or category (string match).
  • attribute: The context key to inspect (e.g., transaction.value).
  • tiers: Array of criteria paired with an action (autonomous, challenge, deny).

Network (network.*)

egress-spiffe-targets

Explicit declaration of downstream agents permitted to be called. Targets can be SPIFFE IDs or tag selectors.

ingress-spiffe-allow-list

L4/L7 mTLS allow-list for upstream workloads. Rejects non-SVID traffic or unauthorized machine identities.

Runtime (runtime.*)

max-hops-allowed

Maximum depth of delegation to prevent infinite loops. Validated by The Collet at Layer 1.

timeout-seconds

Global execution timeout per turn. Enforced via context deadlines in the Collet proxy handler.

Plugin Extensions (spec.extensions)

Partners and plugin authors can attach custom configuration blocks to any Mandrel Spec using the spec.extensions field inside the spec: section.

spec:
  extensions:
    acme.io/billing:
      tier: enterprise
      limits:
        daily: 10000
    acme.io/audit:
      enabled: true
      retention-days: 90

Key ownership

Each top-level key under extensions must be claimed by exactly one registered plugin validator. A validator declares ownership via OwnsExtensions() []string (in-process plugins) or the owned_extensions field of its manifest (subprocess plugins). Keys follow reverse-DNS convention (vendor.io/feature) to avoid collisions.

Default-Deny validation posture

ConditionDefault behaviourOverride
Key claimed by a registered validatorValidator runs; errors block generation—
Key present, no claiming validatorValidation error (fail-closed)--allow-unclaimed-extensions downgrades to warning
extensions present but not a YAML mappingLoad error (fail-closed)None; fix the spec

Value shape

Each value is a free-form YAML mapping decoded by the owning plugin. The Mandrel core does not interpret the values — they are passed as raw *yaml.Node to the plugin’s Validate and Generate methods.

Source: gitlab.com/the-mandrel-project/mandrel-spec