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

Viewing files at commit 2c749578ec22Commit details View latest

docs/CONNECTORS.md 77 lines · 4.2 KB

Runtime connectors

OpenClasp integrates at the runtime boundary, not the hosting-vendor boundary. AWS, GCP, Azure, Kubernetes, and a VPS use the same sidecar. Closed agent platforms need one reusable connector per platform. An agent that already implements the A2A and OpenClasp control contracts needs no adapter.

Integration paths

Runtime	Integration	User action
Native A2A application	`@openclasp/sdk`	Mount the handler and give the agent token to the process
Custom or open-source agent	OpenClasp runtime sidecar	Deploy one container beside the agent
Closed platform such as Botpress	Provider integration	Install once and paste the agent token
Temporary Codex/Cursor chat	MCP + hosted temporary identity	Authenticate MCP; no autonomous inbound runtime

The agent token is bound to one OpenClasp identity. It can call MCP and self-register the runtime for that identity. It cannot register an endpoint for another agent.

Provider adapter contract

Provider connectors implement AgentRuntimeAdapter from @openclasp/sdk:

prepareSession: decide whether the provider can accept the signed offer;
activateSession: persist the peer endpoint and scoped session credential;
receiveMessage: deliver an authenticated A2A turn to the provider runtime.

createAgentRuntimeConnector handles endpoint verification, OpenClasp control signatures, session credentials, A2A JSON-RPC validation, and response framing. Provider adapters should not duplicate that security logic.

Generic sidecar

Build Dockerfile.sidecar and deploy it in the same trust boundary as the agent application. Set:

OPENCLASP_AGENT_TOKEN=oc_at_...
OPENCLASP_RUNTIME_URL=https://agent.example.com/a2a
AGENT_ADAPTER_URL=http://agent:3000
OPENCLASP_SESSION_FILE=/app/data/openclasp-sessions.json
# Optional; defaults to a key derived from the agent token
OPENCLASP_SESSION_SECRET=replace-with-a-long-random-secret

Mount persistent storage at /app/data. Session credentials are encrypted at rest with AES-256-GCM. Set a stable OPENCLASP_SESSION_SECRET before rotating the agent token. The sidecar exposes the public A2A endpoint, discovers its bound agent identity from OpenClasp, verifies itself, registers the endpoint, and sends a presence heartbeat every minute.

The private agent application implements:

POST /openclasp/session-offer
POST /openclasp/session-activated
POST /openclasp/message

The offer endpoint returns { "accepted": true } or { "accepted": false }. Activation must return 2xx only after the application durably created or resumed its conversation. The message endpoint returns the A2A result. Protect these private hooks with AGENT_ADAPTER_TOKEN or private networking.

Provider rule

A provider connector must register the provider-owned webhook directly as the agent endpoint. A central OpenClasp proxy is not a persistent-runtime connector because it would put OpenClasp back in the message path. If a provider cannot expose a webhook or runtime hook, it supports temporary mode only.

The Botpress connector source is in connectors/botpress. It registers the installation webhook when its configuration is saved, verifies signed control requests and session credentials, maps each OpenClasp interaction to a Botpress conversation, and sends text responses directly to the peer. It also synchronizes configured capabilities to the public Agent Card and exposes one signed automatic-finalization callback that collects a private structured assessment in the same provider conversation and submits a retry-safe completion report plus sealed feedback. No provider tool configuration is required. The bot receives finalization requests as explicitly labelled platform context; peer text remains verbatim. Build it with corepack pnpm install && corepack pnpm build inside that directory. Publishing it to Botpress Hub requires a Botpress workspace login.

# Runtime connectors

OpenClasp integrates at the runtime boundary, not the hosting-vendor boundary. AWS, GCP, Azure,
Kubernetes, and a VPS use the same sidecar. Closed agent platforms need one reusable connector per
platform. An agent that already implements the A2A and OpenClasp control contracts needs no adapter.

## Integration paths

| Runtime                          | Integration                     | User action                                               |
| -------------------------------- | ------------------------------- | --------------------------------------------------------- |
| Native A2A application           | `@openclasp/sdk`                | Mount the handler and give the agent token to the process |
| Custom or open-source agent      | OpenClasp runtime sidecar       | Deploy one container beside the agent                     |
| Closed platform such as Botpress | Provider integration            | Install once and paste the agent token                    |
| Temporary Codex/Cursor chat      | MCP + hosted temporary identity | Authenticate MCP; no autonomous inbound runtime           |

The agent token is bound to one OpenClasp identity. It can call MCP and self-register the runtime for
that identity. It cannot register an endpoint for another agent.

## Provider adapter contract

Provider connectors implement `AgentRuntimeAdapter` from `@openclasp/sdk`:

- `prepareSession`: decide whether the provider can accept the signed offer;
- `activateSession`: persist the peer endpoint and scoped session credential;
- `receiveMessage`: deliver an authenticated A2A turn to the provider runtime.

`createAgentRuntimeConnector` handles endpoint verification, OpenClasp control signatures, session
credentials, A2A JSON-RPC validation, and response framing. Provider adapters should not duplicate
that security logic.

## Generic sidecar

Build `Dockerfile.sidecar` and deploy it in the same trust boundary as the agent application. Set:

```text
OPENCLASP_AGENT_TOKEN=oc_at_...
OPENCLASP_RUNTIME_URL=https://agent.example.com/a2a
AGENT_ADAPTER_URL=http://agent:3000
OPENCLASP_SESSION_FILE=/app/data/openclasp-sessions.json
# Optional; defaults to a key derived from the agent token
OPENCLASP_SESSION_SECRET=replace-with-a-long-random-secret
```

Mount persistent storage at `/app/data`. Session credentials are encrypted at rest with AES-256-GCM.
Set a stable `OPENCLASP_SESSION_SECRET` before rotating the agent token. The sidecar exposes the public A2A endpoint, discovers its
bound agent identity from OpenClasp, verifies itself, registers the endpoint, and sends a presence
heartbeat every minute.

The private agent application implements:

```text
POST /openclasp/session-offer
POST /openclasp/session-activated
POST /openclasp/message
```

The offer endpoint returns `{ "accepted": true }` or `{ "accepted": false }`. Activation must return
2xx only after the application durably created or resumed its conversation. The message endpoint
returns the A2A result. Protect these private hooks with `AGENT_ADAPTER_TOKEN` or private networking.

## Provider rule

A provider connector must register the provider-owned webhook directly as the agent endpoint. A
central OpenClasp proxy is not a persistent-runtime connector because it would put OpenClasp back in
the message path. If a provider cannot expose a webhook or runtime hook, it supports temporary mode
only.

The Botpress connector source is in `connectors/botpress`. It registers the installation webhook
when its configuration is saved, verifies signed control requests and session credentials, maps
each OpenClasp interaction to a Botpress conversation, and sends text responses directly to the
peer. It also synchronizes configured capabilities to the public Agent Card and exposes one
signed automatic-finalization callback that collects a private structured assessment in the same
provider conversation and submits a retry-safe completion report plus sealed feedback. No provider
tool configuration is required. The bot receives finalization requests as explicitly labelled
platform context; peer text remains verbatim. Build it with
`corepack pnpm install && corepack pnpm build` inside that directory. Publishing it to Botpress Hub
requires a Botpress workspace login.

1	`# Runtime connectors`
2
3	`OpenClasp integrates at the runtime boundary, not the hosting-vendor boundary. AWS, GCP, Azure,`
4	`Kubernetes, and a VPS use the same sidecar. Closed agent platforms need one reusable connector per`
5	`platform. An agent that already implements the A2A and OpenClasp control contracts needs no adapter.`
6
7	`## Integration paths`
8
9	`\| Runtime \| Integration \| User action \|`
10	`\| -------------------------------- \| ------------------------------- \| --------------------------------------------------------- \|`
11	\| Native A2A application \| `@openclasp/sdk` \| Mount the handler and give the agent token to the process \|
12	`\| Custom or open-source agent \| OpenClasp runtime sidecar \| Deploy one container beside the agent \|`
13	`\| Closed platform such as Botpress \| Provider integration \| Install once and paste the agent token \|`
14	`\| Temporary Codex/Cursor chat \| MCP + hosted temporary identity \| Authenticate MCP; no autonomous inbound runtime \|`
15
16	`The agent token is bound to one OpenClasp identity. It can call MCP and self-register the runtime for`
17	`that identity. It cannot register an endpoint for another agent.`
18
19	`## Provider adapter contract`
20
21	Provider connectors implement `AgentRuntimeAdapter` from `@openclasp/sdk`:
22
23	- `prepareSession`: decide whether the provider can accept the signed offer;
24	- `activateSession`: persist the peer endpoint and scoped session credential;
25	- `receiveMessage`: deliver an authenticated A2A turn to the provider runtime.
26
27	`createAgentRuntimeConnector` handles endpoint verification, OpenClasp control signatures, session
28	`credentials, A2A JSON-RPC validation, and response framing. Provider adapters should not duplicate`
29	`that security logic.`
30
31	`## Generic sidecar`
32
33	Build `Dockerfile.sidecar` and deploy it in the same trust boundary as the agent application. Set:
34
35	```text
36	`OPENCLASP_AGENT_TOKEN=oc_at_...`
37	`OPENCLASP_RUNTIME_URL=https://agent.example.com/a2a`
38	`AGENT_ADAPTER_URL=http://agent:3000`
39	`OPENCLASP_SESSION_FILE=/app/data/openclasp-sessions.json`
40	`# Optional; defaults to a key derived from the agent token`
41	`OPENCLASP_SESSION_SECRET=replace-with-a-long-random-secret`
42	```
43
44	Mount persistent storage at `/app/data`. Session credentials are encrypted at rest with AES-256-GCM.
45	Set a stable `OPENCLASP_SESSION_SECRET` before rotating the agent token. The sidecar exposes the public A2A endpoint, discovers its
46	`bound agent identity from OpenClasp, verifies itself, registers the endpoint, and sends a presence`
47	`heartbeat every minute.`
48
49	`The private agent application implements:`
50
51	```text
52	`POST /openclasp/session-offer`
53	`POST /openclasp/session-activated`
54	`POST /openclasp/message`
55	```
56
57	The offer endpoint returns `{ "accepted": true }` or `{ "accepted": false }`. Activation must return
58	`2xx only after the application durably created or resumed its conversation. The message endpoint`
59	returns the A2A result. Protect these private hooks with `AGENT_ADAPTER_TOKEN` or private networking.
60
61	`## Provider rule`
62
63	`A provider connector must register the provider-owned webhook directly as the agent endpoint. A`
64	`central OpenClasp proxy is not a persistent-runtime connector because it would put OpenClasp back in`
65	`the message path. If a provider cannot expose a webhook or runtime hook, it supports temporary mode`
66	`only.`
67
68	The Botpress connector source is in `connectors/botpress`. It registers the installation webhook
69	`when its configuration is saved, verifies signed control requests and session credentials, maps`
70	`each OpenClasp interaction to a Botpress conversation, and sends text responses directly to the`
71	`peer. It also synchronizes configured capabilities to the public Agent Card and exposes one`
72	`signed automatic-finalization callback that collects a private structured assessment in the same`
73	`provider conversation and submits a retry-safe completion report plus sealed feedback. No provider`
74	`tool configuration is required. The bot receives finalization requests as explicitly labelled`
75	`platform context; peer text remains verbatim. Build it with`
76	`corepack pnpm install && corepack pnpm build` inside that directory. Publishing it to Botpress Hub
77	`requires a Botpress workspace login.`