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 single Tool Gateway that brokers identity, validates schemas, enforces approval-mode tiers, and emits the trace.

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.

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 its capability set, schemas, auth requirements, and declared approval_mode.
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, risk tier, and required claims. Tool candidates resolve from intent + Context Pack at runtime instead of injecting a full catalog into prompts.
• Unified auth — ingress verifies caller identity (delegated user token + agent workload identity); egress exchanges short-lived credentials per tool and scope. Tenant, subject, scopes, and policy decision IDs propagate in signed metadata.
• Idempotency — every write-class call carries an idempotency_key; replays are absorbed safely.
• 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.

Capability classification

Beyond approval_mode (which is the risk dimension), every capability declares a capability_class (the kind of operation). The Compiler uses class to surface the right tools for the intent; the Critic uses class to verify the plan respects intent shape.

Why class + mode (and not just 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.

Approval-mode binding on capabilities

Every adapter capability declares the highest approval mode it can produce. The taxonomy is the canonical Approval-mode tiers from Governance:

Policy may select a lower effective approval mode for a specific bounded request when the capability’s declared maximum allows it (for example, a refund capability whose maximum is destructive may execute as delegated below a configured threshold). Policy cannot raise a call above the capability’s declared maximum or invent a mode outside the taxonomy. The Orchestrator routes network, delegated, and destructive calls through a propose -> approve -> execute sub-sequence so the approval surface is consistent across workflows.

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.

Approval-mode maxima, argument schema constraints, credential exchange, tenant isolation, and idempotency keys are invariants. If a proposal needs to change one of those, it is not an autotune candidate; it is a governed adapter or policy release.

MCP, A2A, and OpenAPI

• MCP (Model Context Protocol) — typed tool contracts, resource discovery, structured errors with retryability hints, scoped auth, versioned compatibility, transport flexibility (stdio / streamable HTTP).
• A2A (Agent-to-Agent) — typed coordination between agents or services with explicit message contracts, agent-card discovery, correlation IDs, and approval-mode-aware delegation.
• 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 (capability set, schemas, auth, approval_mode)
• 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, mutation refs, 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.

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.

Evaluation metrics

• Tool success rate by (adapter, capability).
• Approval-mode misclassification rate and rejected effective-mode selections.
• Permission-violation rate (denied calls per 1k attempts).
• Mean and p99 latency by adapter.
• Idempotent-replay correctness on chaos-injected duplicates.

Example

A capability registration with explicit approval-mode binding:

{
  "permission_id": "perm_payments_refund_capped",
  "adapter_id": "adp_payments",
  "capability": "issue_refund",
  "allow": true,
  "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 declared approval modes 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.