Behavioral Contract Layer + arrival manifest: BR becomes legible to a cold frontier model

2026-05-24

apicapability-registrydiscovery

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints:

"GET /"
"GET /v1/capabilities/{capability_id}/describe"
"GET /.well-known/agent-card.json"

sdk_methods_updated: ["pending — phase 2 of plan"] mcp_tools_updated: ["none — REST-only discovery surface in this slice"] ---

What We Built

The first slice of the Agent Liaison Protocol plan: the Behavioral Contract Layer (BCL) schema and the arrival narrative a frontier model reads on its first round-trip.

The schema additions sit on defineCapability(): every capability may now declare a behavior block describing what it does to the caller's world (effects), what it costs (cost shape), what security profile it carries (data classes, guardrails, OCSF event classes emitted, MITRE ATT&CK relevance, compliance frameworks, required trust tier), what composes with it (typically-precedes/follows), and what to do when it fails (recovery vocabulary). The block is _advisory_ for planning and _enforced_ at runtime by guardrails, Guardian, OCSF projection, and the error envelope.

Three new endpoints make the contract legible:

GET / — the arrival manifest. One JSON document that tells a frontier

model what BR does, how to authenticate, where to find each subsystem, and what events BR will emit on its behalf.

GET /v1/capabilities/{capability_id}/describe — full BCL block per

capability, the surface a model reads to plan a workflow.

GET /.well-known/agent-card.json — A2A v1.0-conformant agent card with

the BCL block attached as x-br-behavior vendor extension. Agents that only speak A2A get a valid card; BR-aware agents get richer behavioral semantics on the same surface.

An overlay system (*.behavior.json files alongside source) lets the existing 86 capabilities gain a behavior block without touching their defineCapability call sites — separate, parallelizable PR.

Why It Matters

Every modern AI gateway publishes some flavor of discovery: A2A agent cards, MCP tool annotations, .well-known/ai-plugin.json. None of them carry enough vocabulary for a frontier model to plan a multi-step task on first contact. MCP gives three boolean hints (readOnlyHint, destructiveHint, idempotentHint). A2A gives skill names + examples. Neither tells the model what the call will _cost_, what OCSF event class it will _emit_, what data classes it will _touch_, what comes after it in a typical workflow, or what the recovery move is if it fails.

That is the gap. Until a frontier model can answer those questions from the documentation alone, multi-agent workflows require trial-and-error or human prompting. BCL closes it by extending the same wire shapes the ecosystem is already adopting — MCP _meta, A2A vendor extensions, OpenAPI vendor extensions — rather than forking a parallel schema. The field is x-br-behavior so A2A consumers ignore it; BR-aware consumers get the full taxonomy.

How It Works

// src/api/capability-def.ts (excerpt — full block shape)
behavior: {
  effects: [{ kind: "external_http", target: "anthropic.com", direction: "outbound", reversible: false }],
  cost: { shape: "variable", drivers: ["messages[].content.length"], bounded_by: ["X-BR-Plan-Id"], typical_usd: 0.002, p95_usd: 0.05 },
  security: {
    data_classes_touched: ["customer_pii_low"],
    guardrails_applied: ["pii_scan", "owasp_llm_top_10"],
    ocsf_events_emitted: [{ class_uid: 6003, type: "api_activity", activity: "create" }],
    mitre_attack_relevant: ["T1567"],
    compliance_frameworks: ["SOC2-CC6", "NIST-AI-RMF-MEASURE-2.6"],
    requires_principal_trust_tier: "bronze",
    auto_killswitch_on: ["anomaly_score>0.95"],
  },
  composition: { typically_followed_by: ["liaison.events"], typically_preceded_by: ["liaison.plan"], incompatible_with: [] },
  recovery: { cost_exceeded: { action: "renegotiate", hint: "open liaison, request larger ceiling" } },
  trace: ["model_selected", "principal_chain", "tokens_in", "tokens_out", "cost_usd"],
}

A behavior-overlay-loader walks the capabilities tree for *.behavior.json files, merges them into a single id → block map, validates each via the ContractZod-safe validateBehaviorBlock(), and surfaces inline-vs-overlay duplication as a warn finding. Discovery handlers read from a behavior-registry module that exposes the merged view; the registry is initialized once at server boot via initBehaviorRegistry(ALL_CAPABILITIES).

The agent-card emitter (buildAgentCard) walks the public REST-exposing capabilities, maps each to an A2A Skill, attaches the behavior block as x-br-behavior, and namespaces any other BR-specific metadata under x-br-*. A test (agent-card.test.ts:roundTrip) pins the invariant: BCL fields survive JSON serialization with zero information loss, so the wire shape is what an A2A peer actually sees.

The Numbers

3 new endpoints (root manifest, capability describe, agent card)
22 new unit tests (BCL schema validation, overlay loader merge semantics,

agent-card emission, A2A conformance check, JSON round-trip)

124/124 capability tests pass across the full surface (registry

completeness, no-inline-routes, dispatch loop, all migrated capabilities)

0 changes to existing capability behavior — the BCL field is optional
BCL schema fields: effects, cost, security, composition, recovery,

trace (6 sub-blocks)

Behavior contract coverage at landing: 3/86 capabilities (the three new

discovery caps declared inline). Distillation pass for the remaining 83 is a separate PR.

Competitive Edge

OpenRouter, Portkey, Lasso, Together — all expose some flavor of capability list. None of them give a frontier model enough vocabulary to plan a multi-step task without prompting. The BCL block plus the arrival manifest puts BR ahead on the dimension that the 2026 agent ecosystem (A2A, MCP, ANP, AGNTCY) is converging on but not yet shipping: per-call behavioral semantics in vocabulary the model already understands.

This is also the foundation for the rest of the Agent Liaison Protocol — the binding pre-flight contract, the live trace envelope, the OCSF-streamed liaison, the inbound XDR remediation API. Every later phase reads from the BCL block; this slice is what they all stand on.

What's Next (per the Liaison plan)

v1.C: Liaison Session capabilities (open, plan, commit, events, delegate,

close) — adds binding pre-flight contract enforcement to Guardian + the streaming writer.

v1.D: Inbound Remediation API (/v1/remediation/*) — typed OCSF-shaped

wrappers over the existing killswitch / lifecycle / cert revocation capabilities so CrowdStrike Fusion / Sentinel / Cortex / Splunk SOAR can build remediation playbooks against one contract.

v1.E: Distillation pass — propose *.behavior.json overlays for the 83

existing capabilities, reviewable in parallel.

v1.F: TS + Python SDKs for the discovery + liaison surface.

v1.C addendum (same PR) — Liaison Session core

Shipped alongside the BCL foundation in commit 9f78d40:

POST /v1/liaison/open — mint signed liaison_id (HS256 JWT via existing issueAgentJwt) + SSE downlink URL + TTL.
POST /v1/liaison/{id}/plan — mint plan_id + HMAC-SHA256 over canonical envelope {plan_id, liaison_id, tenant_id, model, ceiling_usd, prompt_fingerprint, issued_at, ttl_seconds}, signed with AGENT_JWT_SECRET. x402-forward-compatible envelope shape.
POST /v1/liaison/{id}/close — finalize, emit cost summary + trace digest.
Runtime enforcement in guardianMiddleware (around line 289): when X-BR-Plan-Id + X-BR-Liaison headers are present, BR verifies HMAC, TTL, prompt fingerprint, and enforces ceiling_usd as the pre-request cap. Signed plans are mode-independent — the contract is non-negotiable once issued.
Every failure mode returns 400/402 with recovery_action: "renegotiate" in the canonical error envelope.

Supporting modules:

src/api/services/liaison-store.ts — LruMap (cap 10k) + Redis hydration seam (deferred to v2).
src/api/services/liaison-contract-signer.ts — canonical JSON serialization + HMAC-SHA256 + constant-time verify.
10 new tests on the signer alone (round-trip + tamper-evidence on every field + length mismatch + wrong secret + base64url validation).

SDK lockstep:

TS — client.liaison.open() / .plan(id, …) / .close(id), registered in the routing domain.
Py — sync + async parallels.

What's Next (per the Liaison plan)

v1.C-rest: Remaining liaison endpoints — events (SSE downlink), update, delegate, accept-delegation, principals. Wire _liaisonPlan commit lifecycle in the streaming writer for mid-stream ceiling abort.
v1.D: Inbound Remediation API (/v1/remediation/*) — typed OCSF-shaped wrappers over the existing killswitch / lifecycle / cert revocation capabilities so CrowdStrike Fusion / Sentinel / Cortex / Splunk SOAR can build remediation playbooks against one contract.
v1.E: Distillation pass — propose *.behavior.json overlays for the 83 existing capabilities, reviewable in parallel.
v1.F: Expanded SDK + examples (binding-contract, sub-agent-delegation, xdr-remediation).

Lockstep Checklist

[x] API Routes: src/api/capabilities/discovery/ (new) — three capabilities; src/api/capabilities/liaison/ (new) — three capabilities.
[x] TS SDK: packages/sdk-ts/src/resources/discovery.ts + liaison.ts updated; client.liaison.{open,plan,close} + client.discovery.{rootManifest,describeCapability,agentCard} registered.
[x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/discovery.py + liaison.py (sync + async).
[x] MCP Schemas: Discovery + liaison surface is REST-only by design; no MCP tools.
[x] Master Record: Updated via the BCL behavior block on each new capability.