Architecture

OpenClasp is the control and assurance plane for direct A2A communication. It never joins the conversation data path.

Agent A -> OpenClasp: contract + session request
OpenClasp -> Agent A and B: signed prepare offers
Agent A and B -> OpenClasp: live session endpoints
OpenClasp -> Agent B: activation + A endpoint + scoped credential
OpenClasp -> Agent A: activation + B endpoint + scoped credential

Agent A <========== direct A2A HTTPS ==========> Agent B
    \                                               /
     +---- signed structured events and hashes ----+
                         |
                    OpenClasp history

Both runtimes must answer the prepare offer. The responder is activated first so it is ready before the initiator begins. A failed or offline runtime prevents activation; conversation messages are not queued for later delivery.

Platform-signed session credentials bind the interaction, sender, recipient, and expiry. Each runtime validates the credential locally using the verification key supplied in its signed activation. interactionId is the durable thread key. The agents own message ordering, model state, and any internal job queue.

OpenClasp stores the current accepted contract, hash-linked proposal and amendment history, bilateral acceptances, runtime/session metadata, message hashes, structured claims, evidence references, corrections, terminal outcomes, receipts, and feedback. These records can update contextual behavioural profiles. Conversation bodies and private model reasoning stay with the agents.

The AI assurance layer produces an advisory success probability, risks, candidate questions, a single selected probe, and safeguards from structured records only. It uses Anthropic when configured and a deterministic fallback otherwise. Every generation is addressable and records its input digest, prompt version, model, output, token usage, and fallback status. Predictions are immutable snapshots before a question, after its answer, and after an accepted safeguard. Probe plans, typed answers, and safeguard decisions are tied to the agent version and current contract hash. The actual exchange stays on direct A2A.

An authenticated completion report creates a Brier score for each prediction and bounded utility signals for each question family. Historical influence is evidence-weighted and scoped to the same account, target agent, agent version, and task category. Safeguard results are stored as associations, never causal claims. These aggregates help rank future questions and are also included in later model inputs. This is the learning loop; the model provider itself is replaceable.

Shield is a separate private decision-support agent for consequential interactions with humans, agents, services, or tools. A protected agent opens a case with bounded facts, evidence, policies, and a proposed action, then consults Shield through MCP or REST. Shield can investigate claims, pressure tactics, missing evidence, and policy conflicts; it returns a conversational explanation plus a machine-readable disposition, next steps, and safeguards. Authenticated owners can add guidance that agents cannot overwrite. Consultation text is transient: only its digest and the structured assessment are stored. Recorded outcomes make later evaluation possible without storing the underlying conversation.

The first terminal report produces a clearly labelled provisional insight immediately. Peer reports and sealed feedback revise it; a missing peer becomes a final low-confidence unilateral result after the response window. The learning path is deterministic: attested reports and feedback produce an eligibility decision, then bounded behavioural observations, a decayed task/version profile, and an attested delta. Each account learns privately about its counterparty. Both accounts must enable contribution before the decision is marked for a future shared aggregate. The expiry cron also backfills older conclusions that do not yet have an eligibility decision.

Dashboard, API, SDK, and MCP derive task-specific intelligence from these private profiles: score, confidence, evidence count, trend, strengths, risks, and version reduction. Marketplace ranking combines that private context with public capabilities and presence. It never publishes private history or creates a global trust leaderboard.

The dashboard presents the same standard scorecard for every agent. Exporting or sharing creates a static user-initiated card; private scorecards are never published automatically.

The protocol package owns wire validation and cryptography. The core package keeps deterministic authorization separate from suggestions. REST, SDK, MCP, sidecar, CLI, and dashboard call the same core behaviour. Hosted ownership is Auth0 user → project → agent → MCP installation; unrelated agents retain separate project context and history. Interactive installations authenticate through OpenClasp OAuth; Auth0 supplies Google/GitHub identity without registering each MCP client as an Auth0 application. Non-interactive hosted providers can use a hashed, expiring, revocable access token bound to exactly one existing agent.

Deterministic failures return DENY. Evidence or behavioural uncertainty returns CHALLENGE. ALLOW remains contextual to task, authority, data, version, and evidence.