|
| 1 | + |
| 2 | + |
| 3 | +<div align="center"> |
| 4 | + |
| 5 | +# @agent-relay/events |
| 6 | + |
| 7 | +Normalized event stream for proactive agents — Layer 2 of the Agent Relay runtime. |
| 8 | + |
| 9 | +[](https://www.npmjs.com/package/@agent-relay/events) |
| 10 | +[](../../LICENSE) |
| 11 | + |
| 12 | +**Website:** [agentrelay.com](https://agentrelay.com) · **Docs:** [agentrelay.com/docs](https://agentrelay.com/docs) |
| 13 | + |
| 14 | +</div> |
| 15 | + |
| 16 | +## What it does |
| 17 | + |
| 18 | +`@agent-relay/events` turns the three proactive primitives (cron, watch, inbox) into one normalized event stream. Subscribe with a single `onEvent` handler; receive lightweight envelopes that you can lazily `expand()` to full payloads. |
| 19 | + |
| 20 | +It is the transport-agnostic core: no workspace concept, no scheduling, no cloud assumptions — pure event stream plus retry policy plus OpenTelemetry tracing. Compose it directly for hosted webhooks, or build a higher-level runtime on top (see [`@agent-relay/agent`](../agent)). |
| 21 | + |
| 22 | +## Install |
| 23 | + |
| 24 | +```bash |
| 25 | +npm install @agent-relay/events |
| 26 | +``` |
| 27 | + |
| 28 | +## Quick start |
| 29 | + |
| 30 | +```ts |
| 31 | +import { events } from '@agent-relay/events'; |
| 32 | + |
| 33 | +const handle = events({ |
| 34 | + workspace: 'support', |
| 35 | + apiKey: process.env.RELAY_API_KEY!, |
| 36 | + onEvent: async (event) => { |
| 37 | + console.log(event.type, event.resource.path); |
| 38 | + |
| 39 | + const full = await event.expand('full'); |
| 40 | + // ... act on full.data |
| 41 | + }, |
| 42 | +}); |
| 43 | + |
| 44 | +// ... later |
| 45 | +await handle.stop(); |
| 46 | +``` |
| 47 | + |
| 48 | +## Event envelope shape |
| 49 | + |
| 50 | +Every event arrives as a normalized `AgentEvent`: |
| 51 | + |
| 52 | +```ts |
| 53 | +type AgentEvent = { |
| 54 | + id: string; // stable event id |
| 55 | + workspace: string; |
| 56 | + type: 'cron.tick' | 'startup' | 'relayfile.changed' | 'relaycast.message' | ...; |
| 57 | + occurredAt: string; // ISO timestamp |
| 58 | + attempt: number; // delivery attempt count |
| 59 | + resource: { path: string; kind: string; id: string; provider: string }; |
| 60 | + summary: EventSummary; // <1KB, PII-stripped |
| 61 | + expand: (level: 'summary' | 'full' | 'diff' | 'thread') => Promise<Expansion>; |
| 62 | + digest?: string; |
| 63 | +}; |
| 64 | +``` |
| 65 | + |
| 66 | +The envelope is the **shape your handler receives** — not the full provider payload. Call `event.expand('full')` to materialize the resource lazily. |
| 67 | + |
| 68 | +## Expansion levels |
| 69 | + |
| 70 | +| Level | What you get | Cost | |
| 71 | +| --------- | ------------------------------------------------------- | ----------------- | |
| 72 | +| `summary` | Pre-included lightweight summary (already on the event) | free | |
| 73 | +| `full` | Full canonical resource via gateway / relayfile VFS | one read | |
| 74 | +| `diff` | Changed fields vs prior state | one read | |
| 75 | +| `thread` | Paginated comments / replies | one or more reads | |
| 76 | + |
| 77 | +## Retry + NoRetry sentinel |
| 78 | + |
| 79 | +```ts |
| 80 | +import { events, NoRetry } from '@agent-relay/events'; |
| 81 | + |
| 82 | +events({ |
| 83 | + workspace: 'support', |
| 84 | + apiKey: process.env.RELAY_API_KEY!, |
| 85 | + onEvent: async (event) => { |
| 86 | + try { |
| 87 | + // ... your work |
| 88 | + } catch (err) { |
| 89 | + if (isPermanent(err)) throw new NoRetry(err); // skip retry queue |
| 90 | + throw err; // 5-attempt exp backoff |
| 91 | + } |
| 92 | + }, |
| 93 | +}); |
| 94 | +``` |
| 95 | + |
| 96 | +## OpenTelemetry |
| 97 | + |
| 98 | +Every dispatched event is wrapped in a `SpanKind.CONSUMER` span tagged with the event id, type, workspace, and attempt. Configure your exporter (e.g. `OTEL_EXPORTER_OTLP_ENDPOINT`) — `@agent-relay/events` plugs into the global tracer provider via `@opentelemetry/api`. |
| 99 | + |
| 100 | +## Related |
| 101 | + |
| 102 | +- [`@agent-relay/agent`](../agent) — Layer 3: workspace + ctx + `agent({...})` API on top of this stream |
| 103 | +- [`@agent-relay/sdk`](../sdk) — broker control + workflow orchestration |
| 104 | +- [Proactive Agent Runtime spec](https://github.com/AgentWorkforce/cloud/blob/main/docs/proactive-runtime/spec.md) — the design this implements |
| 105 | + |
| 106 | +## License |
| 107 | + |
| 108 | +Apache-2.0 — see [LICENSE](../../LICENSE). |
0 commit comments