ax-event-runtime

Ax Event Runtime

Use this skill when an Ax program should react to notifications, webhooks, timers, queues, task completion, or application events.

Mental Model

source -> inbox -> route -> target -> stored run -> sink

Sources never call an Ax program directly. A route must explicitly choose observe, invalidate, wake, or resume. Only the last two invoke a model.

Minimal Pattern

const source = new AxPushEventSource('application');
const target = eventTarget('triage')
  .program(triageAgent)
  .ai(llm)
  .input((input) => input.field('incident', eventPath.data()))
  .sink({ id: 'result', write: saveResult })
  .build();

const events = eventRuntime({
  sources: [source],
  routes: [
    eventRoute('incident-created')
      .types('incident.created')
      .wake(target)
      .build(),
  ],
});

await events.start();
await source.publish({ event, identity, trust: 'authenticated' });

Rules

• Supply identity from authenticated adapter state, never from event data.
• Treat events without verified identity as anonymous and untrusted.
• Map event data into signature inputs; do not synthesize a user message.
• Use eventPath.data('field') and other segment-safe selectors. Do not use dotted JSONPath strings or repurpose s() as a mapping language.
• Use .project(path) only for same-name signature projection. Explicit .field() mappings override projection; missing or invalid signature inputs dead-letter before model invocation.
• Use eventInput().project(...).field(...) when a declarative mapping should be callback-free and reusable, then pass that plan to .input(), .wakeInput(), or .resumeInput().
• Callback mapInput is an escape hatch, not a validation bypass: its result is normalized to the program signature and mapper failures dead-letter before invocation.
• Use .wakeInput() and .resumeInput() when the two actions need different contracts. Neither action silently uses the other action's mapping.
• Use observe for progress/logs and invalidate for catalog changes.
• Use resume only with an owned continuation correlation key.
• Use createProgram(instance) for stateful multi-tenant Agents.
• Declare retrySafety: 'idempotent' only when stable delivery keys protect every possible side effect.
• Persist outputs before final sink delivery; redrive sink failures separately.
• Use debounceMs and coalesce: 'latest' only when replacing intermediate events is part of the route's declared policy.
• Observe source failures with onSourceError.
• The in-memory store is volatile and single-process.
• For cooperating Node processes on one local disk, use AxSQLiteEventStore from @ax-llm/ax-tools/event/sqlite with explicit retention and coordination: 'multi-worker'. Never recommend SQLite on a network filesystem.
• Close the runtime and caller-owned protocol clients explicitly.
• Fan out to several Agents with several matching routes, not a multi-target route. This preserves independent authorization, ordering, retries, and runs.