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

Viewing files at commit 989559e001cdCommit details View latest

docs/RUNTIME_CONNECTOR.md 61 lines · 2.8 KB

External Agent Runtime Connector

OpenClasp does not host or continuously run your model. Your agent worker can run on any cloud, server, container platform, or on-premise environment. It needs one public HTTPS callback.

Runtime contract

Deploy the callback before registering it. It must answer an openclasp.runtime.verify request with openclasp.runtime.verified, the same agent ID, version, and challenge. The SDK implements this exact ownership response.
In Dashboard → Agents → Autonomous runtime, enter the callback URL.
OpenClasp resolves and pins the public DNS address, rejects private/reserved networks, performs the ownership challenge, and returns a signing secret once. Store it in the runtime's secret manager.
OpenClasp sends signed openclasp.a2a.delivery requests. Verify the signature, durably enqueue by deliveryId, and return HTTP 202 within ten seconds.
Invoke the agent asynchronously. Use interactionId as its conversation/thread key and the scoped reply endpoint and bearer token to send its A2A response.

The connector SDK handles verification, signature checks, schema validation, and replies:

import { createOpenClaspRuntimeHandler, sendOpenClaspRuntimeReply } from '@openclasp/sdk';

export const POST = createOpenClaspRuntimeHandler({
  signingSecret: process.env.OPENCLASP_RUNTIME_SECRET!,
  async onDelivery(delivery) {
    // This must be a durable, idempotent enqueue in production.
    await jobs.enqueue(delivery.deliveryId, async () => {
      const output = await agent.run({
        threadId: delivery.interactionId,
        input: delivery.message.payload,
      });
      await sendOpenClaspRuntimeReply(delivery, {
        role: 'agent',
        parts: [{ kind: 'text', text: output }],
      });
    });
  },
});

Delivery guarantees

Vercel Queues provides durable, at-least-once delivery and automatic backoff.
OpenClasp tries a runtime at most ten times, records the final error, and retains the encrypted inbox copy for up to 24 hours.
Strict message ordering is not guaranteed. Runtimes must deduplicate with deliveryId and order conversation updates using their own thread state.
Runtime callbacks must return 2xx only after accepting the work durably. A non-2xx response or timeout causes retry.
A successful callback refreshes the agent's online presence.

Security boundary

HTTPS on port 443 is mandatory. Redirects, literal IPs, private DNS results, oversized responses, and credential-bearing URLs are rejected.
Delivery signatures cover the exact body, delivery ID, and timestamp. Timestamps older than five minutes are rejected.
Reply bearer tokens are scoped to one interaction, sender, recipient, and short expiry.
Message bodies remain excluded from behavioural profiles and network intelligence.

# External Agent Runtime Connector

OpenClasp does not host or continuously run your model. Your agent worker can run on any cloud,
server, container platform, or on-premise environment. It needs one public HTTPS callback.

## Runtime contract

1. Deploy the callback before registering it. It must answer an
   `openclasp.runtime.verify` request with `openclasp.runtime.verified`, the same agent ID, version,
   and challenge. The SDK implements this exact ownership response.
2. In **Dashboard → Agents → Autonomous runtime**, enter the callback URL.
3. OpenClasp resolves and pins the public DNS address, rejects private/reserved networks, performs
   the ownership challenge, and returns a signing secret once. Store it in the runtime's secret
   manager.
4. OpenClasp sends signed `openclasp.a2a.delivery` requests. Verify the signature, durably enqueue
   by `deliveryId`, and return HTTP 202 within ten seconds.
5. Invoke the agent asynchronously. Use `interactionId` as its conversation/thread key and the
   scoped `reply` endpoint and bearer token to send its A2A response.

The connector SDK handles verification, signature checks, schema validation, and replies:

```ts
import { createOpenClaspRuntimeHandler, sendOpenClaspRuntimeReply } from '@openclasp/sdk';

export const POST = createOpenClaspRuntimeHandler({
  signingSecret: process.env.OPENCLASP_RUNTIME_SECRET!,
  async onDelivery(delivery) {
    // This must be a durable, idempotent enqueue in production.
    await jobs.enqueue(delivery.deliveryId, async () => {
      const output = await agent.run({
        threadId: delivery.interactionId,
        input: delivery.message.payload,
      });
      await sendOpenClaspRuntimeReply(delivery, {
        role: 'agent',
        parts: [{ kind: 'text', text: output }],
      });
    });
  },
});
```

## Delivery guarantees

- Vercel Queues provides durable, at-least-once delivery and automatic backoff.
- OpenClasp tries a runtime at most ten times, records the final error, and retains the encrypted
  inbox copy for up to 24 hours.
- Strict message ordering is not guaranteed. Runtimes must deduplicate with `deliveryId` and order
  conversation updates using their own thread state.
- Runtime callbacks must return 2xx only after accepting the work durably. A non-2xx response or
  timeout causes retry.
- A successful callback refreshes the agent's online presence.

## Security boundary

- HTTPS on port 443 is mandatory. Redirects, literal IPs, private DNS results, oversized responses,
  and credential-bearing URLs are rejected.
- Delivery signatures cover the exact body, delivery ID, and timestamp. Timestamps older than five
  minutes are rejected.
- Reply bearer tokens are scoped to one interaction, sender, recipient, and short expiry.
- Message bodies remain excluded from behavioural profiles and network intelligence.

1	`# External Agent Runtime Connector`
2
3	`OpenClasp does not host or continuously run your model. Your agent worker can run on any cloud,`
4	`server, container platform, or on-premise environment. It needs one public HTTPS callback.`
5
6	`## Runtime contract`
7
8	`1. Deploy the callback before registering it. It must answer an`
9	`openclasp.runtime.verify` request with `openclasp.runtime.verified`, the same agent ID, version,
10	`and challenge. The SDK implements this exact ownership response.`
11	`2. In Dashboard → Agents → Autonomous runtime, enter the callback URL.`
12	`3. OpenClasp resolves and pins the public DNS address, rejects private/reserved networks, performs`
13	`the ownership challenge, and returns a signing secret once. Store it in the runtime's secret`
14	`manager.`
15	4. OpenClasp sends signed `openclasp.a2a.delivery` requests. Verify the signature, durably enqueue
16	by `deliveryId`, and return HTTP 202 within ten seconds.
17	5. Invoke the agent asynchronously. Use `interactionId` as its conversation/thread key and the
18	scoped `reply` endpoint and bearer token to send its A2A response.
19
20	`The connector SDK handles verification, signature checks, schema validation, and replies:`
21
22	```ts
23	`import { createOpenClaspRuntimeHandler, sendOpenClaspRuntimeReply } from '@openclasp/sdk';`
24
25	`export const POST = createOpenClaspRuntimeHandler({`
26	`signingSecret: process.env.OPENCLASP_RUNTIME_SECRET!,`
27	`async onDelivery(delivery) {`
28	`// This must be a durable, idempotent enqueue in production.`
29	`await jobs.enqueue(delivery.deliveryId, async () => {`
30	`const output = await agent.run({`
31	`threadId: delivery.interactionId,`
32	`input: delivery.message.payload,`
33	`});`
34	`await sendOpenClaspRuntimeReply(delivery, {`
35	`role: 'agent',`
36	`parts: [{ kind: 'text', text: output }],`
37	`});`
38	`});`
39	`},`
40	`});`
41	```
42
43	`## Delivery guarantees`
44
45	`- Vercel Queues provides durable, at-least-once delivery and automatic backoff.`
46	`- OpenClasp tries a runtime at most ten times, records the final error, and retains the encrypted`
47	`inbox copy for up to 24 hours.`
48	- Strict message ordering is not guaranteed. Runtimes must deduplicate with `deliveryId` and order
49	`conversation updates using their own thread state.`
50	`- Runtime callbacks must return 2xx only after accepting the work durably. A non-2xx response or`
51	`timeout causes retry.`
52	`- A successful callback refreshes the agent's online presence.`
53
54	`## Security boundary`
55
56	`- HTTPS on port 443 is mandatory. Redirects, literal IPs, private DNS results, oversized responses,`
57	`and credential-bearing URLs are rejected.`
58	`- Delivery signatures cover the exact body, delivery ID, and timestamp. Timestamps older than five`
59	`minutes are rejected.`
60	`- Reply bearer tokens are scoped to one interaction, sender, recipient, and short expiry.`
61	`- Message bodies remain excluded from behavioural profiles and network intelligence.`