@agent-relay/events-shim 0.0.0-stage → 18.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -2
- package/package.json +48 -4
package/README.md
CHANGED
|
@@ -1,3 +1,55 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @agent-relay/events-shim
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
One MCP URL that wakes your agent when a webhook arrives.
|
|
4
|
+
|
|
5
|
+
A person adds a single MCP server to their agent (`claude mcp add --transport http webhooks <mcp url>`)
|
|
6
|
+
and points any sender at the paired webhook URL. Each post becomes an Agent Relay message:
|
|
7
|
+
|
|
8
|
+
- **Under Agent Relay** the agent links the inbox to its session's own relay webhook
|
|
9
|
+
(`agent-relay-probe webhook --socket <socket>`, then the `link_relay_wake` tool). Every later post is
|
|
10
|
+
forwarded there and Agent Relay injects it into the session, **waking it even when idle**.
|
|
11
|
+
- **Without Agent Relay** the agent runs `wait_for_webhook` in the background (it blocks until a post
|
|
12
|
+
arrives) or reads with `get_webhook_events`.
|
|
13
|
+
|
|
14
|
+
## Tools
|
|
15
|
+
|
|
16
|
+
| Tool | What it does |
|
|
17
|
+
| -------------------- | ------------------------------------------------------------------ |
|
|
18
|
+
| `watch_webhooks` | Start here: webhook URLs, wake state, waiting posts and next steps |
|
|
19
|
+
| `link_relay_wake` | Link the session's relay webhook (checked with a test post first) |
|
|
20
|
+
| `unlink_relay_wake` | Stop forwarding |
|
|
21
|
+
| `get_webhook_events` | Unread posts (marks them read), or one post by id |
|
|
22
|
+
| `wait_for_webhook` | Block until a post arrives (≤ 50 s), then return it |
|
|
23
|
+
|
|
24
|
+
## Webhook URLs
|
|
25
|
+
|
|
26
|
+
`<base>/h/<token>` accepts anyone holding the URL. `/github`, `/stripe`, `/linear` and `/bearer` suffixes
|
|
27
|
+
check the sender against a secret set for that mode. A retried post with the same `Idempotency-Key` (or
|
|
28
|
+
the provider's delivery id) arrives once. Limits (`EVENTS_SHIM_LIMITS`): 60 posts/hour, 500/day,
|
|
29
|
+
64 KB bodies, 50 posts in the feed, 7 days idle expiry.
|
|
30
|
+
|
|
31
|
+
## Nudges: wake agents from your own MCP
|
|
32
|
+
|
|
33
|
+
Post `Content-Type: text/plain` to an authenticated URL (`/bearer`, `/github`, `/stripe`, `/linear`) and the
|
|
34
|
+
agent receives exactly that text, e.g. `New task t_42 — read it with get_task on the acme MCP`. Your data stays
|
|
35
|
+
behind your MCP; the shim only carries the pointer. Open URLs always wrap the body as untrusted data.
|
|
36
|
+
|
|
37
|
+
## Hosting
|
|
38
|
+
|
|
39
|
+
Hosts implement `EventsShimStore` (see `MemoryEventsShimStore`) and mount one handler:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { handleEventsShimRequest } from '@agent-relay/events-shim';
|
|
43
|
+
|
|
44
|
+
const response = await handleEventsShimRequest(request, pathAfterMount, {
|
|
45
|
+
deps: { store, fetchImpl: fetch },
|
|
46
|
+
urls: {
|
|
47
|
+
mcpUrl: (token) => `${base}/t/${token}/mcp`,
|
|
48
|
+
hookUrl: (token, mode) => `${base}/h/${token}${mode === 'open' ? '' : `/${mode}`}`,
|
|
49
|
+
},
|
|
50
|
+
beforeCreate: perIpRateLimit,
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Wake links may only point at an allowed Relaycast origin (`relayOrigins`, default
|
|
55
|
+
`https://cast.agentrelay.com`), so a holder of the MCP URL cannot make the host post elsewhere.
|
package/package.json
CHANGED
|
@@ -1,6 +1,50 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-relay/events-shim",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "18.1.0",
|
|
4
|
+
"description": "One MCP URL that turns webhook posts into Agent Relay messages that wake an idle agent session",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js",
|
|
12
|
+
"default": "./dist/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist",
|
|
17
|
+
"README.md",
|
|
18
|
+
"package.json"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"build": "tsc",
|
|
22
|
+
"clean": "rm -rf dist",
|
|
23
|
+
"test": "vitest run --root ../.. packages/events-shim/src",
|
|
24
|
+
"test:watch": "vitest --root ../.. packages/events-shim/src",
|
|
25
|
+
"prepack": "npm run build"
|
|
26
|
+
},
|
|
27
|
+
"peerDependencies": {
|
|
28
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
29
|
+
"zod": "^4.4.3"
|
|
30
|
+
},
|
|
31
|
+
"devDependencies": {
|
|
32
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
33
|
+
"@types/node": "^22.19.3",
|
|
34
|
+
"typescript": "^5.9.3",
|
|
35
|
+
"vitest": "^4.1.0",
|
|
36
|
+
"zod": "^4.4.3"
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=22.0.0"
|
|
40
|
+
},
|
|
41
|
+
"publishConfig": {
|
|
42
|
+
"access": "public"
|
|
43
|
+
},
|
|
44
|
+
"repository": {
|
|
45
|
+
"type": "git",
|
|
46
|
+
"url": "git+https://github.com/AgentWorkforce/relay.git",
|
|
47
|
+
"directory": "packages/events-shim"
|
|
48
|
+
},
|
|
49
|
+
"license": "Apache-2.0"
|
|
50
|
+
}
|