Adapter Mesh

The Adapter Mesh is the Action plane—the only path through which the Decision plane can produce side effects. Every external call traverses a Tool Gateway that validates identity, schemas, arguments, native action risk, approval state, idempotency, and result evidence.

Definition

A typed integration layer with three pieces: adapters that wrap external systems (MCP servers, A2A peers, OpenAPI services, internal functions, custom connectors), a Tool Gateway that mediates every call, and a registry that publishes capabilities to the Context Pack Compiler.

The Execution Contract adds exact action/approval binding, active boundary observations, data-flow policy, operation recovery and shared budget attachments without changing the v1 tool enums. The gateway must enforce these requirements in its actual runtime; the deterministic reference does not itself provide a credential broker, sandbox, egress proxy or provider transaction.

Why it exists

Tools are the highest-risk surface in any agent system. An ungoverned tool call is the path by which a model causes irreversible damage. The mesh exists so that the model proposes capabilities, but a deterministic boundary decides whether the call happens, on whose behalf, with which credentials, and what evidence the result must produce.

How it works

1. Register: an adapter is onboarded with capabilities, schemas, auth requirements, native ActionRisk, authority/destination ceilings, and a v1 approval_mode projection.
2. Discover: the Context Pack references the registry by capability; the gateway expands only the relevant tool schemas at compile time.
3. Plan-time check: the Critic verifies the plan only contains permitted tools with valid argument schemas.
4. Execute: the gateway brokers ingress identity (Run Context user + agent workload identity) and exchanges egress credentials (STS-style); validates inputs; executes; captures the typed result.
5. Observe: every call produces a ToolCallEnvelope / ToolResultEnvelope pair linked to the trace and the Decision Record.

Tool Gateway pattern

The Gateway is the single entry point between the Decision plane and the outside world. It standardizes:

• Onboarding paths — OpenAPI import, function (Lambda / internal worker), custom connector for non-HTTP systems.
• Protocol translation — MCP ↔ REST, A2A ↔ internal job queue, RPC ↔ tool envelope. Transport details never leak into prompts.
• Semantic discovery — tools are indexed by capability, domain, native risk, and required claims. Tool candidates resolve from intent + Context Pack instead of injecting a full catalog into prompts.
• Unified auth — ingress verifies the caller and workload according to the declared identity profile; egress exchanges short-lived credentials per tool and scope. Canonical envelopes propagate principal chains and opaque auth references; deployments may add signed claims.
• Operation identity and idempotency — persist stable logical operation identity and the complete normalized action before write dispatch. Provider-idempotent retry additionally requires a bound key, payload scope, mismatch behavior and retention contract. A provider without that guarantee needs an explicit lookup/manual reconciliation or no-retry strategy; a key alone does not establish exactly-once effects.
• Cached read-only aliases — well-used read-only tools may be exposed as cached, first-class aliases for prompt density. Aliases are conservative: cached discovery only, allow-listed tools only, execution still routes through the gateway.

Tool and extension supply chain

Discovery is not admission. A tool, MCP server, extension, or peer agent enters the registry only after its manifest is pinned and verified: owner, publisher/signature, dependencies, version, schemas, endpoints, capability classes, ActionRisk ceiling, compatibility approval mode, identity and tenant behavior, data and egress ceiling, retry/idempotency/compensation behavior, security tests, operational owner, and kill switch.

Generic proxy tools that turn unconstrained model text into arbitrary network, shell, browser, or database access are rejected. Read and write capabilities remain separately discoverable. Metadata and returned content are treated as untrusted evidence; neither can expand the registered capability or authority ceiling.

At runtime the gateway follows one validation order:

1. resolve the pinned manifest and verify its integrity;
2. verify actor, workload, principal chain, tenant, and freshness;
3. intersect delegated scopes with the manifest, policy, sandbox, and approval ceiling;
4. validate arguments, destination, data classification, budget, and idempotency key;
5. exchange a short-lived, call-bound credential;
6. dispatch the admitted attempt through the registered adapter under current ownership; and
7. validate the typed result, normalized effect, postcondition, citations, and recovery receipt.

Redirects, retries, callbacks, resumptions, and agent-to-agent handoffs repeat the relevant identity and policy checks. Prior validation never becomes ambient authority.

Uncertain effects and retry obligations

Admission of a write capability must establish its observable postcondition, idempotency scope and retention window, request-mismatch behavior, outcome lookup, and compensation or explicit non-recoverability. These belong to the versioned adapter profile already required by onboarding; they are not new v1 envelope fields.

Persist the logical operation identity and validated request before dispatch. Repeated attempts for that operation must not create fresh identities merely because a response was lost. Local deduplication coordinates local requests but cannot manufacture a remote transaction guarantee.

After a timeout, crash, cancellation, or lost response, distinguish confirmed effect, confirmed no effect, and unresolved effect in retained evidence. These are effect observations, not additions to the ToolResultEnvelope.status enum. A transport failure alone establishes neither effect nor absence. Use provider evidence to reconcile; retry only when the declared contract makes redispatch safe and current authority still permits it. Otherwise stop automatic dispatch and route to an accountable recovery owner.

Audit replay remains transcript-only. Resuming live work is a separate operation that rechecks authority and external state. See result and recovery semantics for serialization boundaries.

The additive operation ledger uses not_dispatched, confirmed, not_applied, partial and unknown; those are separate from ToolResultEnvelope.status. claimOperation returns an intended store transition and requires current authorization before dispatch. recordEffectObservation can record a late verified fact without granting a stale worker ownership or settling budget. Atomic persistence, provider lookup and any target fence remain deployment obligations.

Active boundaries and actual data routes

Evaluate ExecutionBoundaryRequirement against current verified observations of the actual mode/configuration, filesystem/process restrictions, resource ceilings, credential mediation and network enforcement. Broker-only tools need a valid restricted boundary; code execution additionally needs the appropriate code isolation. Missing or failed requirements block without a weaker-backend fallback. Allowed business purpose cannot waive DNS/redirect restrictions or destination checks at egress.

Apply evaluateDataFlow to collection, inference, tool input/output, telemetry, cache, memory, export and delegation. Check the actual recipient tenant/domain, processor/residency, purpose and verified source labels. A release transformation binds its exact source/result, action, policy and destination; neither model labels nor provider names prove compliant routing. Reserve root/child capacity before work; cancellation with unknown usage retains the reservation. See Control Profiles for conditional requirements and Conformance for actual enforcement evidence.

Capability classification

Every capability declares a capability_class describing the kind of operation. Native ActionRisk describes independent effect, authority, reversibility, interaction, and data boundaries. The Compiler uses both for surfacing; the Critic and Gateway use them to verify the plan and call.

Why class + risk (and not just a mode)

• A single mode value (network) does not distinguish a verify (read against external truth) from an act (mutate external state) — both can carry network mode but only one produces a side effect.
• The Critic enforces: a plan whose intent is read_only may include observe / recall / think_support / verify capabilities but must not include any act step.
• The Compiler scoring favors verify capabilities over observe when evidence_refs are required, all else equal.

Skills

A Skill is a composable, named bundle of capabilities + a usage prompt + an evaluation suite. Skills sit one level above capabilities: they describe how a set of capabilities is used together to accomplish a recurring micro-task.

skill_id: skill.support.identity_verification
version: "1.2.0"
purpose: "Verify that the requesting customer matches the order's owner."
required_capabilities:
  - capability_class: verify
    name: adp_idv.verify
  - capability_class: observe
    name: adp_orders.lookup
preconditions:
  - "request.context.customer_id is present"
postconditions:
  - "evidence_refs includes idv.verified"
prompt_fragment_ref: "prompts/skills/identity_verification.v1.2"
evaluation_set_ref: "evals/skills/identity_verification.golden.v1"
owner_role: support_ops

Properties

• Skills are versioned, signed, and registered in the pack registry alongside Context Packs.
• The Planner can invoke a Skill as a typed sub-plan; the Skill expands inline into the parent Plan.
• Skill evaluation is independent of intent evaluation — the Skill’s golden set drives its own release gate.
• Skills cannot inject capabilities outside the pack’s tooling_layer.permissions; they compose what is already permitted.
• Skills are owned: the owner_role is responsible for the Skill’s correctness and is paged on scorecard regression.

Paired release gate. A skill release is evaluated on the same tasks and pinned harness tuple with the skill available and withheld. It must create positive verified Skill Lift, activate on relevant work, stay silent on irrelevant work, and avoid security, policy, latency, cost, and neighboring-skill regressions. The stored evidence includes skill availability and activation, files or instructions read, capabilities and identities used, calls and results, state diff, final response, grader provenance, and rollback target. Skill presence alone is never credited as improvement.

Native risk and v1 mode projection

Every new adapter capability declares native ActionRisk. Existing v1 envelopes also require a conservative mode projection from Governance:

Policy evaluates every native dimension and the actual arguments immediately before execution. It may select a lower effective v1 mode for a bounded request only when the native vector and capability ceiling permit it; the projection cannot understate risk. Approval routing is selected by policy obligations, not by assuming every network call needs a human gate.

Improvement surface

The Action plane exposes operational tuning surfaces, not authority tuning surfaces. Autotune may propose changes that improve reliability, latency, cost, or tool-result quality, but it cannot weaken the boundary that makes a tool call governed.

Native-risk ceilings, conservative v1 projections, argument constraints, credential exchange, tenant isolation, and declared operation/retry guarantees are invariants. Changing one requires a governed adapter or policy release.

MCP, A2A, and OpenAPI

• MCP (Model Context Protocol) — use the MCP 2026-07-28 profile for stateless requests, per-request negotiation, multi-round-trip input, and optional durable tasks.
• A2A (Agent-to-Agent) — A2A 1.0 supplies messages, artifacts, task lifecycle, Agent Card discovery, and authentication metadata; ContextOS adds narrowing delegation and local policy at each hop.
• OpenAPI — schema imports normalized to the gateway’s tool envelope so internal services participate without bespoke connectors.
• Internal functions and custom connectors wrap callable code or non-HTTP systems behind the same envelope.

The mesh keeps MCP (agent-to-tool) and A2A (agent-to-agent) boundaries explicit in the trace and in policy decisions.

Interfaces

Inputs

• Adapter registry (capabilities, schemas, auth, native risk, v1 projection)
• Permissions per role / intent / environment
• Run Context (user delegation, agent workload identity, tenant, budgets)
• Policy decisions and approval gate state

Outputs

• ToolResultEnvelope receipts with citations, normalized effect and mutation refs, postcondition evidence, recovery status, policy_decision_id, and trace metadata
• Trace spans linked to the parent decision span
• Structured errors with retryability and remediation hints
• Idempotent replay confirmations

Failure modes

• Over-broad permissions enabling data exfiltration through a permitted capability.
• Schema drift between the registered tool and the live endpoint causing invalid calls.
• Missing idempotency on write-class capabilities producing duplicate side effects on retry.
• Silent timeouts without circuit breakers cascading into the planner’s loop guard.
• Delegation accepted in A2A flows without policy revalidation at the receiving agent.
• Cached read-only alias hiding a permission change after a policy update.
• Tool or extension metadata successfully granting itself an undeclared capability, credential scope, or destination.
• Adapter reports success while the external postcondition is absent or a partial effect is left uncompensated.

Operational concerns

• Adapter version pinning and protocol-version pinning per environment.
• Egress rate budgets per (tenant, capability) to prevent third-party throttling.
• Secrets rotation and credential-exchange hygiene at the gateway.
• Queue backpressure and dead-letter handling for long-running A2A tasks.
• Allow-list of tools eligible for cached aliasing; revalidate on policy change.
• Per-tool latency budgets enforced by the Run Context, not the adapter.
• Admission revalidation on publisher, signature, dependency, schema, endpoint, or ownership change.
• Recovery rehearsal for every reversible or compensatable write capability before production promotion.

Evaluation metrics

• Tool success rate by (adapter, capability).
• Native-risk coverage, dimension-level denial accuracy, and unsafe projection rate.
• Permission-violation rate (denied calls per 1k attempts).
• Mean and p99 latency by adapter.
• Idempotent-replay correctness on chaos-injected duplicates.
• Postcondition verification rate and uncompensated partial-effect rate.
• Skill Lift versus the paired no-skill baseline, with activation and safety guardrails.

Example

A capability registration with native risk and an explicit v1 projection:

{
  "permission_id": "perm_payments_refund_capped",
  "adapter_id": "adp_payments",
  "capability": "issue_refund",
  "allow": true,
  "action_risk": {
    "effect": "external_state",
    "authority": "user_delegated",
    "reversibility": "compensatable",
    "interaction": "api",
    "data_scope": "CONFIDENTIAL",
    "decision_ttl_seconds": 120
  },
  "approval_mode": "destructive",
  "arg_constraints": {
    "amount_inr": { "min": 1, "max": 50000 },
    "currency": { "enum": ["INR"] },
    "idempotency_key": { "required": true, "pattern": "^ik_[a-z0-9]{16}$" }
  },
  "decision_binding": "decision.support.refund.execute"
}

A ToolCallEnvelope produced at runtime, condensed:

{
  "envelope_version": "contextos.tool_call.v1",
  "tool_call_id": "tool_118",
  "run_id": "run_a1b2c3d4e5f60718",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "session_id": "sess_42f1",
  "capability_id": "adp_payments.issue_refund",
  "approval_mode_requested": "destructive",
  "approval_mode_effective": "destructive",
  "approval_mode_highest": "destructive",
  "policy_decision_id": "pol_9901",
  "args": { "order_id": "ord_881", "amount_inr": 4200, "currency": "INR", "idempotency_key": "ik_2x9k4j7m1q8w0p3z" },
  "principal_chain": [
    { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" },
    { "kind": "agent", "id": "agent:contextos/support-refund@1.2.0", "tenant_id": "tenant_acme_prod" }
  ],
  "evidence_refs": ["policy:POLICY_RETURNS_V1#R_HIGH_VALUE_REQUIRES_APPROVAL"],
  "idempotency_key": "ik_2x9k4j7m1q8w0p3z",
  "auth_ref": "claim_hash:sha256:..."
}

Common misconceptions

• Adapters are not API wrappers. They are policy-enforced execution boundaries with native risk, scoped authority, evidence, and credential exchange.
• The Gateway is not a router. It is the deterministic boundary that turns a model proposal into a governed effect.
• A2A is not free-form chat. It is typed coordination with policy revalidation at every hop.