The AI trust layer between agents: identity, agreements, safeguards, and outcome intelligence for A2A.

Viewing files at commit 296bb55574a2Commit details View latest

docs/ARCHITECTURE.md 40 lines · 2.0 KB

Architecture

OpenClasp is the control and assurance plane for direct A2A communication. It is not the conversation transport and does not store raw agent messages.

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 immutable contract, bilateral acceptances, runtime/session metadata, message hashes, structured claims, evidence references, corrections, terminal outcomes, receipts, and feedback. These records can update contextual behavioural profiles. Message bodies and private model reasoning stay with the agents.

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.

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

# Architecture

OpenClasp is the control and assurance plane for direct A2A communication. It is not the
conversation transport and does not store raw agent messages.

```text
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 immutable contract, bilateral acceptances, runtime/session metadata, message
hashes, structured claims, evidence references, corrections, terminal outcomes, receipts, and
feedback. These records can update contextual behavioural profiles. Message bodies and private model
reasoning stay with the agents.

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.

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

1	`# Architecture`
2
3	`OpenClasp is the control and assurance plane for direct A2A communication. It is not the`
4	`conversation transport and does not store raw agent messages.`
5
6	```text
7	`Agent A -> OpenClasp: contract + session request`
8	`OpenClasp -> Agent A and B: signed prepare offers`
9	`Agent A and B -> OpenClasp: live session endpoints`
10	`OpenClasp -> Agent B: activation + A endpoint + scoped credential`
11	`OpenClasp -> Agent A: activation + B endpoint + scoped credential`
12
13	`Agent A <========== direct A2A HTTPS ==========> Agent B`
14	`\ /`
15	`+---- signed structured events and hashes ----+`
16	`\|`
17	`OpenClasp history`
18	```
19
20	`Both runtimes must answer the prepare offer. The responder is activated first so it is ready before`
21	`the initiator begins. A failed or offline runtime prevents activation; conversation messages are not`
22	`queued for later delivery.`
23
24	`Platform-signed session credentials bind the interaction, sender, recipient, and expiry. Each`
25	`runtime validates the credential locally using the verification key supplied in its signed`
26	activation. `interactionId` is the durable thread key. The agents own message ordering, model state,
27	`and any internal job queue.`
28
29	`OpenClasp stores the immutable contract, bilateral acceptances, runtime/session metadata, message`
30	`hashes, structured claims, evidence references, corrections, terminal outcomes, receipts, and`
31	`feedback. These records can update contextual behavioural profiles. Message bodies and private model`
32	`reasoning stay with the agents.`
33
34	`The protocol package owns wire validation and cryptography. The core package keeps deterministic`
35	`authorization separate from suggestions. REST, SDK, MCP, sidecar, CLI, and dashboard call the same`
36	core behaviour. Hosted ownership is `Auth0 user → project → agent → MCP installation`; unrelated
37	`agents retain separate project context and history.`
38
39	Deterministic failures return `DENY`. Evidence or behavioural uncertainty returns `CHALLENGE`.
40	`ALLOW` remains contextual to task, authority, data, version, and evidence.