@agentcomms/events
@agentcomms/events is the isomorphic library behind agent-communications’ local event emission: the version-1
event catalogue, pointer patterns, semantic formats, deterministic conditions, mapping templates and CloudEvents wire
format. Appendix A of the event-emission design
is its normative contract.
It has no I/O. The same build runs in Node and browser webviews, imports no node: module, and makes no network,
file-system, clock or randomness call. Sanitising, untrusted-content envelopes, signing and delivery belong to the
daemon that uses this library; this package reports source-field and mapped-value provenance instead.
It is published with every release from 0.16.0, with @agentcomms/events-daemon, the
local service that uses it.
API
Import the pieces you need from the package root. The barrel is the complete supported surface; internal modules are not public API.
JSON, text and errors
canonicalJson is byte-identical to core’s canonical JSON. It sorts object keys by UTF-16 code units, drops
undefined object members and refuses non-JSON input with EventsError; validators otherwise return Result<T> with
closed IssueCode values.
import { canonicalJson, codePointLength, isJsonValue } from '@agentcomms/events';
const value = { second: undefined, first: ['é'] };
if (isJsonValue(value)) {
canonicalJson(value); // '{"first":["é"]}'
codePointLength('🛰'); // 1
}
Event identity
eventId derives D3’s stable, account-scoped 32-character ID through WebCrypto. Keep its canonical preimage with
the ID so compareEventIdentities can distinguish a repeat from the theoretical truncated-hash collision.
import { eventId, eventIdPreimage } from '@agentcomms/events';
const identity = {
installationId: 'installation-id',
accountId: 'account-id',
eventType: 'gmail.message.received',
typeVersion: 1,
dedupeKey: '["provider-occurrence","message","received"]',
};
const preimage = eventIdPreimage(identity);
const id = await eventId(identity);
Unicode, domains and semantic formats
The library pins NFC, full case folding and IDNA handling to Unicode 15.1. toAsciiDomain returns a Result; use
isFormat for the catalogue’s five semantic formats.
import { UNICODE_VERSION, caseFold, isFormat, toAsciiDomain } from '@agentcomms/events';
UNICODE_VERSION; // '15.1.0'
caseFold('STRASSE'); // 'strasse'
toAsciiDomain('Bücher.example'); // { ok: true, value: 'xn--bcher-kva.example' }
isFormat('date-time', '2026-10-07T12:00:00Z'); // true
JSON Pointers and patterns
Pointers follow RFC 6901. Patterns add { any: true } only for array indices and expand to the concrete non-null
values present in an event.
import { expandPattern, getPointer } from '@agentcomms/events';
const source = { recipients: [{ address: '[email protected]' }] };
getPointer(source, '/recipients/0/address'); // { found: true, value: '[email protected]' }
expandPattern(['recipients', { any: true }, 'address'], source); // ['/recipients/0/address']
Catalogue and source schemas
CATALOGUE contains precisely the seven version-1 definitions. A definition owns its Zod schema, metadata patterns,
examples, source JSON Schema and named invariants.
import { CATALOGUE, catalogueEntry, sourceSchema, validateEvent } from '@agentcomms/events';
const found = catalogueEntry('gmail.message.received', 1);
if (found.ok) {
const event = found.value.examples[0];
validateEvent(found.value, event); // { ok: true, value: event }
sourceSchema(found.value); // JSON Schema 2020-12 for this exact source type
}
CATALOGUE.length; // 7
Conditions
Canonicalise a condition against the selected definition before persisting it. The omitted case-sensitivity flag
becomes explicit false, so canonical JSON and workflow digests are stable.
import { CATALOGUE, canonicaliseCondition, evaluateCondition } from '@agentcomms/events';
const definition = CATALOGUE[0];
const condition = canonicaliseCondition(definition, { path: '/subject', op: 'contains', value: 'status' });
if (condition.ok) evaluateCondition(definition, condition.value, definition.examples[0]);
canonicaliseAgenticCondition checks the static agentic form and its deterministic content-field prefilter. It does
not execute a judge.
Mapping and provenance
Mapping copies clean, typed source values; constants never inherit provenance. Classifying the mapped result tells a daemon exactly which output pointers are untrusted, addresses or scoped handles before it applies its chosen representation.
import { CATALOGUE, classifyMapped, compileMapping, evaluateMapping } from '@agentcomms/events';
const definition = CATALOGUE[0];
const mapped = compileMapping(definition, { subject: { $path: '/subject' } });
if (mapped.ok) {
const value = evaluateMapping(mapped.value, definition.examples[0]);
classifyMapped(definition, definition.examples[0], value);
}
deliverySchema and deliverySchemaId describe the exact plain or enveloped delivery representation. The daemon
selects that representation and its transport boundary; this package supplies the deterministic mapping primitives.
CloudEvents wire format
After mapping and representation, the daemon supplies stable delivery fields to buildCloudEvent. The library derives
the non-overridable type, subject, time and canonical agentcommsuntrusted extension; cloudEventBytes gives the
canonical JSON string to UTF-8 encode for transport.
import { CATALOGUE, buildCloudEvent, cloudEventBytes } from '@agentcomms/events';
const definition = CATALOGUE[0];
const event = definition.examples[0];
const envelope = buildCloudEvent(definition, event, {
deliveryId: 'delivery-id',
installationId: 'installation-id',
ruleId: 'rule-id',
ruleVersion: 1,
targetId: 'target-id',
targetVersion: 1,
data: { subject: event.subject },
untrusted: ['/subject'],
});
cloudEventBytes(envelope);
TEST_CLOUD_EVENT, TEST_CLOUD_EVENT_BYTES and JUDGE_TEST_INPUT are fixed test-only contract values, not source
events and not caller-configurable templates.
Workflow text
printRuleText writes a workflow (its document, a rule document in the code's names) as a short text a person can
read and edit, and parseRuleText reads it back to exactly the same document. Printing the same document always gives
the same text. Anything the readable form has no words for is written as raw JSON in its place, so nothing is
dropped. The parser checks the text only: the event service still checks the workflow when the document is submitted,
and the canonical JSON is still what is approved. The grammar is in
src/rule-text/GRAMMAR.md; from 0.36.0 the printer starts a document with workflow, and
the parser still reads the older rule. From 0.33.0 a target may be a Linear issue: linear issue billing-issues, version 1, in team CUE, label Billing, assigned to me, with its ids, title and description on the lines below.
import { parseRuleText, printRuleText } from '@agentcomms/events';
const text = printRuleText(ruleDocument);
// workflow invoices, version 4
//
// when a new message arrives in cue/gmail, in the inbox
// match any
// subject contains "invoice"
// subject contains "payment"
// …
const parsed = parseRuleText(text);
if (parsed.ok) parsed.doc; // deep-equals ruleDocument
else parsed.errors; // [{ line, column, message }], e.g. 'unknown keyword "thne"; did you mean "then"? …'
Unicode data and licence
The generated tables and their pinned sources are Unicode 15.1.0. In a repository checkout, run
pnpm sync:unicode to regenerate the checked-in tables from the pinned vendor files. The Unicode Character Database
is licensed under Unicode-3.0; its complete notice is in THIRD_PARTY_LICENSES.
Licence
MIT. See LICENSE and THIRD_PARTY_LICENSES.