@agent-relay/events 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+![Agent Relay](../../readme-banner.png)
+
+<div align="center">
+
+# @agent-relay/events
+
+Normalized event stream for proactive agents — Layer 2 of the Agent Relay runtime.
+
+[![npm](https://img.shields.io/npm/v/@agent-relay/events)](https://www.npmjs.com/package/@agent-relay/events)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+**Website:** [agentrelay.com](https://agentrelay.com) · **Docs:** [agentrelay.com/docs](https://agentrelay.com/docs)
+
+</div>
+
+## What it does
+
+`@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.
+
+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)).
+
+## Install
+
+```bash
+npm install @agent-relay/events
+```
+
+## Quick start
+
+```ts
+import { events } from '@agent-relay/events';
+
+const handle = events({
+  workspace: 'support',
+  apiKey: process.env.RELAY_API_KEY!,
+  onEvent: async (event) => {
+    console.log(event.type, event.resource.path);
+
+    const full = await event.expand('full');
+    // ... act on full.data
+  },
+});
+
+// ... later
+await handle.stop();
+```
+
+## Event envelope shape
+
+Every event arrives as a normalized `AgentEvent`:
+
+```ts
+type AgentEvent = {
+  id: string;                           // stable event id
+  workspace: string;
+  type: 'cron.tick' | 'startup' | 'relayfile.changed' | 'relaycast.message' | ...;
+  occurredAt: string;                   // ISO timestamp
+  attempt: number;                      // delivery attempt count
+  resource: { path: string; kind: string; id: string; provider: string };
+  summary: EventSummary;                // <1KB, PII-stripped
+  expand: (level: 'summary' | 'full' | 'diff' | 'thread') => Promise<Expansion>;
+  digest?: string;
+};
+```
+
+The envelope is the **shape your handler receives** — not the full provider payload. Call `event.expand('full')` to materialize the resource lazily.
+
+## Expansion levels
+
+| Level     | What you get                                            | Cost              |
+| --------- | ------------------------------------------------------- | ----------------- |
+| `summary` | Pre-included lightweight summary (already on the event) | free              |
+| `full`    | Full canonical resource via gateway / relayfile VFS     | one read          |
+| `diff`    | Changed fields vs prior state                           | one read          |
+| `thread`  | Paginated comments / replies                            | one or more reads |
+
+## Retry + NoRetry sentinel
+
+```ts
+import { events, NoRetry } from '@agent-relay/events';
+
+events({
+  workspace: 'support',
+  apiKey: process.env.RELAY_API_KEY!,
+  onEvent: async (event) => {
+    try {
+      // ... your work
+    } catch (err) {
+      if (isPermanent(err)) throw new NoRetry(err); // skip retry queue
+      throw err; // 5-attempt exp backoff
+    }
+  },
+});
+```
+
+## OpenTelemetry
+
+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`.
+
+## Related
+
+- [`@agent-relay/agent`](../agent) — Layer 3: workspace + ctx + `agent({...})` API on top of this stream
+- [`@agent-relay/sdk`](../sdk) — broker control + workflow orchestration
+- [Proactive Agent Runtime spec](https://github.com/AgentWorkforce/cloud/blob/main/docs/proactive-runtime/spec.md) — the design this implements
+
+## License
+
+Apache-2.0 — see [LICENSE](../../LICENSE).

package/dist/envelope.d.ts

@@ -0,0 +1,124 @@
+import type { AgentEvent, AgentEventMap, BaseAgentEvent, CronTickEvent, EventResource, EventSummary, EventType, Expansion, ThreadExpansionOptions, RelaycastMessageEvent, RelayfileChangeEvent, StartupReason, TransportErrorEvent } from './types.js';
+/**
+ * Serializable event record accepted by envelope constructors and transport code.
+ */
+export interface AgentEventRecord<TType extends EventType = EventType, TResource extends Partial<EventResource> | undefined = Partial<EventResource> | undefined> {
+    /** Optional stable event identifier. */
+    id?: string;
+    /** Workspace associated with the event. */
+    workspace: string;
+    /** Normalized event type. */
+    type: TType;
+    /** Optional occurrence timestamp override. */
+    occurredAt?: string;
+    /** Optional delivery attempt override. */
+    attempt?: number;
+    /** Optional explicit resource metadata. */
+    resource?: TResource;
+    /** Optional lightweight summary override. */
+    summary?: EventSummary;
+    /** Optional digest of the current resource state. */
+    digest?: string;
+    /** Cron schedule identifier or expression for `cron.tick`. */
+    schedule?: string;
+    /** Scheduled fire time for `cron.tick`. */
+    scheduledFor?: string;
+    /** Startup reason for `startup`. */
+    reason?: StartupReason;
+    /** Changed path for `relayfile.changed`. */
+    path?: string;
+    /** Matched watch glob for `relayfile.changed`. */
+    watch?: string;
+    /** Normalized action for `relayfile.changed`. */
+    action?: 'created' | 'updated' | 'deleted';
+    /** Optional relayfile agent id for agent-authored changes. */
+    agentId?: string;
+    /** Channel for `relaycast.message`. */
+    channel?: string;
+    /** Message id for `relaycast.message`. */
+    messageId?: string;
+    /** Thread id for `relaycast.message`. */
+    threadId?: string;
+    /** Transport error detail for `transport.error`. */
+    detail?: string;
+}
+/**
+ * Additional options used while constructing a normalized event envelope.
+ */
+export interface CreateAgentEventOptions {
+    /** Shared expansion cache keyed by `(event.id, level)`. */
+    expansionCache?: Map<string, Promise<Expansion>>;
+    /** Loader used by `expand("full")`. */
+    loadFull?: () => Promise<Expansion<'full'>>;
+    /** Loader used by `expand("diff")`. */
+    loadDiff?: () => Promise<Expansion<'diff'>>;
+    /** Loader used by `expand("thread")`. */
+    loadThread?: (options?: ThreadExpansionOptions) => Promise<Expansion<'thread'>>;
+}
+type ResolvedRecordResource<TResource extends Partial<EventResource> | undefined> = EventResource & (TResource extends Partial<EventResource> ? TResource : Record<string, never>);
+type CreatedAgentEvent<TType extends EventType, TResource extends Partial<EventResource> | undefined> = TType extends keyof AgentEventMap ? AgentEventMap[TType] : BaseAgentEvent<TType, ResolvedRecordResource<TResource>>;
+/**
+ * Creates a fully typed normalized event envelope.
+ */
+export declare function createAgentEvent<TType extends EventType, TResource extends Partial<EventResource> | undefined = Partial<EventResource> | undefined>(record: AgentEventRecord<TType, TResource>, options?: CreateAgentEventOptions): CreatedAgentEvent<TType, TResource>;
+/**
+ * Creates a cron tick event using the M1 synthetic resource conventions.
+ */
+export declare function createCronTickEvent(input: {
+    workspace: string;
+    schedule: string;
+    scheduledFor?: string;
+    id?: string;
+    attempt?: number;
+    occurredAt?: string;
+    digest?: string;
+    resourceId?: string;
+    summary?: EventSummary;
+}): CronTickEvent;
+/**
+ * Creates a startup event envelope.
+ */
+export declare function createStartupEvent(input: {
+    workspace: string;
+    reason?: StartupReason;
+    id?: string;
+    attempt?: number;
+    occurredAt?: string;
+    digest?: string;
+    summary?: EventSummary;
+}): AgentEvent<'startup'>;
+/**
+ * Creates a synthetic transport error event.
+ */
+export declare function createTransportErrorEvent(input: {
+    workspace: string;
+    detail: string;
+    id?: string;
+    occurredAt?: string;
+}): TransportErrorEvent;
+/**
+ * Converts a typed event back into the serializable record form.
+ */
+export declare function toAgentEventRecord(event: AgentEvent): AgentEventRecord;
+/**
+ * Type guard for `cron.tick`.
+ */
+export declare function isCronTickEvent(event: AgentEvent): event is CronTickEvent;
+/**
+ * Type guard for `startup`.
+ */
+export declare function isStartupEvent(event: AgentEvent): event is AgentEvent<'startup'>;
+/**
+ * Type guard for `relayfile.changed`.
+ */
+export declare function isRelayfileChangeEvent(event: AgentEvent): event is RelayfileChangeEvent;
+/**
+ * Type guard for `relaycast.message`.
+ */
+export declare function isRelaycastMessageEvent(event: AgentEvent): event is RelaycastMessageEvent;
+/**
+ * Type guard for `transport.error`.
+ */
+export declare function isTransportErrorEvent(event: AgentEvent): event is TransportErrorEvent;
+export {};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"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"}

package/dist/envelope.js

@@ -0,0 +1,447 @@
+import { createExpander } from './expand.js';
+/**
+ * Creates a fully typed normalized event envelope.
+ */
+export function createAgentEvent(record, options = {}) {
+    const id = record.id ?? createId(record.type);
+    const occurredAt = record.occurredAt ?? new Date().toISOString();
+    const resource = resolveResource(record, id);
+    const summary = sanitizeSummary(record.summary ?? defaultSummary(record, resource));
+    const base = {
+        id,
+        workspace: record.workspace,
+        type: record.type,
+        occurredAt,
+        attempt: record.attempt ?? 1,
+        resource,
+        summary,
+        expand: createExpander({
+            eventId: id,
+            path: resource.path,
+            summary,
+            cache: options.expansionCache,
+            loadFull: options.loadFull,
+            loadDiff: options.loadDiff,
+            loadThread: options.loadThread,
+        }),
+        digest: record.digest,
+    };
+    switch (record.type) {
+        case 'startup':
+            return {
+                ...base,
+                reason: record.reason ?? 'manual',
+            };
+        case 'cron.tick':
+            return {
+                ...base,
+                schedule: record.schedule ?? 'manual',
+                scheduledFor: record.scheduledFor ?? occurredAt,
+            };
+        case 'relaycast.message':
+            return {
+                ...base,
+                channel: record.channel ?? 'unknown',
+                messageId: record.messageId ?? resource.id,
+                threadId: record.threadId,
+            };
+        case 'transport.error':
+            return {
+                ...base,
+                detail: record.detail ?? 'transport.error',
+            };
+        case 'relayfile.changed':
+            return {
+                ...base,
+                path: resource.path,
+                watch: record.watch,
+                action: record.action,
+                agentId: record.agentId,
+                current: buildRelayfileCurrent(summary),
+            };
+        default:
+            return base;
+    }
+}
+/**
+ * Creates a cron tick event using the M1 synthetic resource conventions.
+ */
+export function createCronTickEvent(input) {
+    const resourceId = input.resourceId ?? sanitizeScheduleId(input.schedule);
+    return createAgentEvent({
+        workspace: input.workspace,
+        type: 'cron.tick',
+        id: input.id,
+        occurredAt: input.occurredAt,
+        attempt: input.attempt,
+        digest: input.digest,
+        schedule: input.schedule,
+        scheduledFor: input.scheduledFor,
+        summary: input.summary,
+        resource: {
+            path: `/_cron/${resourceId}`,
+            kind: 'cron.tick',
+            id: resourceId,
+            provider: 'internal',
+        },
+    });
+}
+/**
+ * Creates a startup event envelope.
+ */
+export function createStartupEvent(input) {
+    return createAgentEvent({
+        workspace: input.workspace,
+        type: 'startup',
+        id: input.id,
+        occurredAt: input.occurredAt,
+        attempt: input.attempt,
+        digest: input.digest,
+        reason: input.reason,
+        summary: input.summary,
+        resource: {
+            path: '/_system/startup',
+            kind: 'startup',
+            id: input.id ?? 'startup',
+            provider: 'internal',
+        },
+    });
+}
+/**
+ * Creates a synthetic transport error event.
+ */
+export function createTransportErrorEvent(input) {
+    return createAgentEvent({
+        workspace: input.workspace,
+        type: 'transport.error',
+        id: input.id,
+        occurredAt: input.occurredAt,
+        detail: input.detail,
+        resource: {
+            path: '/_system/transport',
+            kind: 'transport.error',
+            id: input.id ?? 'transport.error',
+            provider: 'internal',
+        },
+        summary: {
+            title: 'transport error',
+            status: input.detail,
+            tags: ['transport'],
+        },
+    });
+}
+/**
+ * Converts a typed event back into the serializable record form.
+ */
+export function toAgentEventRecord(event) {
+    const record = {
+        id: event.id,
+        workspace: event.workspace,
+        type: event.type,
+        occurredAt: event.occurredAt,
+        attempt: event.attempt,
+        resource: { ...event.resource },
+        summary: cloneSummary(event.summary),
+        digest: event.digest,
+    };
+    if (isCronTickEvent(event)) {
+        record.schedule = event.schedule;
+        record.scheduledFor = event.scheduledFor;
+    }
+    if (isStartupEvent(event)) {
+        record.reason = event.reason;
+    }
+    if (isRelayfileChangeEvent(event)) {
+        record.watch = event.watch;
+        record.action = event.action;
+        record.agentId = event.agentId;
+    }
+    if (isRelaycastMessageEvent(event)) {
+        record.channel = event.channel;
+        record.messageId = event.messageId;
+        record.threadId = event.threadId;
+    }
+    if (isTransportErrorEvent(event)) {
+        record.detail = event.detail;
+    }
+    return record;
+}
+/**
+ * Type guard for `cron.tick`.
+ */
+export function isCronTickEvent(event) {
+    return event.type === 'cron.tick';
+}
+/**
+ * Type guard for `startup`.
+ */
+export function isStartupEvent(event) {
+    return event.type === 'startup';
+}
+/**
+ * Type guard for `relayfile.changed`.
+ */
+export function isRelayfileChangeEvent(event) {
+    return event.type === 'relayfile.changed';
+}
+/**
+ * Type guard for `relaycast.message`.
+ */
+export function isRelaycastMessageEvent(event) {
+    return event.type === 'relaycast.message';
+}
+/**
+ * Type guard for `transport.error`.
+ */
+export function isTransportErrorEvent(event) {
+    return event.type === 'transport.error';
+}
+function resolveResource(record, fallbackId) {
+    if (record.resource?.path && record.resource.id && record.resource.kind && record.resource.provider) {
+        return {
+            path: record.resource.path,
+            id: record.resource.id,
+            kind: record.resource.kind,
+            provider: record.resource.provider,
+        };
+    }
+    switch (record.type) {
+        case 'cron.tick': {
+            const scheduleId = sanitizeScheduleId(record.schedule ?? fallbackId);
+            return {
+                path: record.resource?.path ?? `/_cron/${scheduleId}`,
+                kind: record.resource?.kind ?? 'cron.tick',
+                id: record.resource?.id ?? scheduleId,
+                provider: record.resource?.provider ?? 'internal',
+            };
+        }
+        case 'startup':
+            return {
+                path: record.resource?.path ?? '/_system/startup',
+                kind: record.resource?.kind ?? 'startup',
+                id: record.resource?.id ?? fallbackId,
+                provider: record.resource?.provider ?? 'internal',
+            };
+        case 'relayfile.changed': {
+            const path = record.resource?.path ?? record.path ?? `/_relayfile/${fallbackId}`;
+            const provider = record.resource?.provider ?? inferProviderFromPath(path);
+            return {
+                path,
+                kind: record.resource?.kind ?? inferRelayfileResourceKind(path, provider),
+                id: record.resource?.id ?? inferRelayfileResourceId(path, fallbackId),
+                provider,
+            };
+        }
+        case 'relaycast.message':
+            return {
+                path: record.resource?.path ??
+                    `/_relaycast/${record.channel ?? 'unknown'}/${record.messageId ?? fallbackId}`,
+                kind: record.resource?.kind ?? 'relaycast.message',
+                id: record.resource?.id ?? record.messageId ?? fallbackId,
+                provider: record.resource?.provider ?? 'relaycast',
+            };
+        case 'transport.error':
+            return {
+                path: record.resource?.path ?? '/_system/transport',
+                kind: record.resource?.kind ?? 'transport.error',
+                id: record.resource?.id ?? fallbackId,
+                provider: record.resource?.provider ?? 'internal',
+            };
+        default:
+            return {
+                path: record.resource?.path ?? `/_events/${record.type}/${fallbackId}`,
+                kind: record.resource?.kind ?? record.type,
+                id: record.resource?.id ?? fallbackId,
+                provider: record.resource?.provider ?? inferProvider(record.type),
+            };
+    }
+}
+function defaultSummary(record, resource) {
+    switch (record.type) {
+        case 'cron.tick':
+            return {
+                title: 'cron tick',
+                status: record.schedule ?? 'manual',
+                tags: ['cron'],
+            };
+        case 'startup':
+            return {
+                title: 'startup',
+                status: record.reason ?? 'manual',
+                tags: ['runtime'],
+            };
+        case 'transport.error':
+            return {
+                title: 'transport error',
+                status: record.detail ?? 'transport.error',
+                tags: ['transport'],
+            };
+        case 'relayfile.changed': {
+            const path = resource?.path ?? record.resource?.path ?? record.path;
+            const provider = resource?.provider ?? record.resource?.provider ?? (path ? inferProviderFromPath(path) : 'relayfile');
+            return {
+                ...(path ? { title: describePath(path) } : { title: 'relayfile.changed' }),
+                ...(record.action ? { status: record.action } : {}),
+                ...(provider && provider !== 'relayfile' ? { tags: [provider] } : {}),
+            };
+        }
+        default:
+            return {
+                title: record.type,
+            };
+    }
+}
+function inferProvider(type) {
+    const [provider] = type.split('.', 1);
+    return provider || 'internal';
+}
+function inferProviderFromPath(path) {
+    const segments = path.split('/').filter(Boolean);
+    const first = segments[0]?.toLowerCase();
+    return !first || first.startsWith('_') ? 'relayfile' : first;
+}
+function inferRelayfileResourceKind(path, provider) {
+    if (provider === 'relayfile') {
+        return 'relayfile.file';
+    }
+    const segments = path.split('/').filter(Boolean);
+    const collection = segments.length > 1 ? segments.at(-2) : undefined;
+    const normalized = normalizeResourceCollection(collection);
+    return normalized ? `${provider}.${normalized}` : `${provider}.resource`;
+}
+function inferRelayfileResourceId(path, fallbackId) {
+    const segments = path.split('/').filter(Boolean);
+    const leaf = segments.at(-1);
+    if (!leaf) {
+        return fallbackId;
+    }
+    const trimmed = leaf.replace(/\.(json|md|txt|yaml|yml)$/i, '').trim();
+    return trimmed || fallbackId;
+}
+function normalizeResourceCollection(segment) {
+    const normalized = segment?.trim().replace(/^_+/, '').toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    const aliases = {
+        notifications: 'notification',
+        prs: 'pull_request',
+        pulls: 'pull_request',
+        merge_requests: 'merge_request',
+        'merge-requests': 'merge_request',
+        records: 'record',
+        issues: 'issue',
+        comments: 'comment',
+        tickets: 'ticket',
+        pages: 'page',
+        tasks: 'task',
+        projects: 'project',
+        messages: 'message',
+        threads: 'thread',
+        files: 'file',
+        tables: 'table',
+        bases: 'base',
+    };
+    if (aliases[normalized]) {
+        return aliases[normalized];
+    }
+    if (normalized.endsWith('ies')) {
+        return `${normalized.slice(0, -3)}y`;
+    }
+    if (normalized.endsWith('s') && normalized.length > 1) {
+        return normalized.slice(0, -1);
+    }
+    return normalized;
+}
+function sanitizeScheduleId(schedule) {
+    return schedule.replace(/[^a-zA-Z0-9._-]+/g, '-');
+}
+function createId(type) {
+    return `${type}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`;
+}
+function buildRelayfileCurrent(summary) {
+    const current = {
+        ...(summary.title ? { title: summary.title } : {}),
+        ...(summary.status ? { status: summary.status } : {}),
+        ...(summary.priority ? { priority: summary.priority } : {}),
+        ...(summary.labels?.length ? { labels: [...summary.labels] } : {}),
+    };
+    return Object.keys(current).length > 0 ? current : undefined;
+}
+function cloneSummary(summary) {
+    return {
+        ...summary,
+        labels: summary.labels ? [...summary.labels] : undefined,
+        fieldsChanged: summary.fieldsChanged ? [...summary.fieldsChanged] : undefined,
+        tags: summary.tags ? [...summary.tags] : undefined,
+        actor: summary.actor ? { ...summary.actor } : undefined,
+    };
+}
+const MAX_LABELS = 8;
+const MAX_FIELDS_CHANGED = 16;
+const MAX_TAGS = 8;
+const MAX_TITLE_LENGTH = 120;
+const MAX_STATUS_LENGTH = 96;
+const MAX_PRIORITY_LENGTH = 48;
+const MAX_TOKEN_LENGTH = 96;
+function sanitizeSummary(summary) {
+    return {
+        ...(sanitizeText(summary.title, MAX_TITLE_LENGTH)
+            ? { title: sanitizeText(summary.title, MAX_TITLE_LENGTH) }
+            : {}),
+        ...(sanitizeText(summary.status, MAX_STATUS_LENGTH)
+            ? { status: sanitizeText(summary.status, MAX_STATUS_LENGTH) }
+            : {}),
+        ...(sanitizeText(summary.priority, MAX_PRIORITY_LENGTH)
+            ? { priority: sanitizeText(summary.priority, MAX_PRIORITY_LENGTH) }
+            : {}),
+        ...(sanitizeTokenList(summary.labels, MAX_LABELS)
+            ? { labels: sanitizeTokenList(summary.labels, MAX_LABELS) }
+            : {}),
+        ...(sanitizeTokenList(summary.fieldsChanged, MAX_FIELDS_CHANGED)
+            ? { fieldsChanged: sanitizeTokenList(summary.fieldsChanged, MAX_FIELDS_CHANGED) }
+            : {}),
+        ...(sanitizeTokenList(summary.tags, MAX_TAGS) ? { tags: sanitizeTokenList(summary.tags, MAX_TAGS) } : {}),
+        ...(summary.actor?.id?.trim()
+            ? {
+                actor: {
+                    id: summary.actor.id.trim(),
+                    ...(sanitizeText(summary.actor.displayName, MAX_TOKEN_LENGTH)
+                        ? { displayName: sanitizeText(summary.actor.displayName, MAX_TOKEN_LENGTH) }
+                        : {}),
+                },
+            }
+            : {}),
+    };
+}
+function sanitizeTokenList(values, max) {
+    if (!values?.length) {
+        return undefined;
+    }
+    const output = [];
+    for (const value of values) {
+        const normalized = sanitizeText(value, MAX_TOKEN_LENGTH);
+        if (!normalized || output.includes(normalized)) {
+            continue;
+        }
+        output.push(normalized);
+        if (output.length >= max) {
+            break;
+        }
+    }
+    return output.length > 0 ? output : undefined;
+}
+function sanitizeText(value, maxLength) {
+    const normalized = value?.replace(/\s+/g, ' ').trim();
+    if (!normalized) {
+        return undefined;
+    }
+    return normalized.length <= maxLength
+        ? normalized
+        : `${normalized.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}
+function describePath(path) {
+    const segments = path.split('/').filter(Boolean);
+    return segments.at(-1) || path || 'relayfile change';
+}
+//# sourceMappingURL=envelope.js.map