Full catalog of lifecycle and runtime events emitted by the Routecraft context.

Event payload

All events share the same envelope:

{
  ts: string       // ISO timestamp
  context: CraftContext
  details: {...}   // event-specific fields (see tables below)
}

Context events

Route events

"Route" here refers to a registered capability internally.

Exchange events

Fired per exchange, scoped to the capability that owns it. routeId is the capability ID.

The exchangeId field is the exchange's own ID, not the correlation ID. Use correlationId to group related exchanges (e.g. a parent and its split children share the same correlation ID).

Lifecycle guarantee: every exchange:started is eventually followed by exactly one of completed, failed, or dropped.

Operation events

Operation events are scoped to a capability and an operation type. They fire for individual steps in the pipeline.

Adapter operations

The metadata field is populated by the adapter's getMetadata() method. For example, the HTTP adapter returns { method, url, statusCode, contentLength }.

Batch operations

reason is 'size' when the batch hit its size limit, 'time' when the flush interval elapsed.

Split and aggregate

Split and aggregate use standard step:started/step:completed events (not dedicated operation events). Operation-specific data is in the metadata field:

• Split step:completed includes metadata.childCount: the number of child exchanges created
• Aggregate step:completed includes metadata.inputCount: the number of exchanges merged

After a split, each child exchange emits its own exchange:started. When aggregate consumes children, it emits exchange:completed for each child before continuing on the parent exchange.

Retry operations

Choice operations

branchLabel is "when" or "otherwise". branchIndex is the zero-based index of the matched branch.

Error handler operations

scope is "route" for the catch-all set via .error() BEFORE .from(), and "step" for a wrapper attached AFTER .from(). stepLabel is the label of the wrapped step when scope === "step". Wildcard subscribers (route:*:error-handler:*) keep matching.

Agent operations

Emitted by agent() destinations. These are the coarse decision events: broadcast to every subscriber, no opt-in needed. For token-level streaming use AgentOptions.onDelta instead (a separate per-call channel).

Wildcard subscriptions (route:*:agent:tool:*, route:*:agent:finished) work for cross-cutting telemetry, dashboards, and TUIs.

ctx.on('route:*:agent:tool:invoked', ({ details }) => {
  log.info({ tool: details.toolName, input: details.input }, 'Agent called tool');
});

ctx.on('route:*:agent:finished', ({ details }) => {
  metrics.histogram('agent.tokens.total', details.totalTokens ?? 0);
});

Source-parse operations

Parsing source adapters (json, html, csv, jsonl, mail) defer parsing to a synthetic first pipeline step so parse failures become normal pipeline events. The synthetic step appears in the standard step:* events with operation: "parse".

What follows depends on the adapter's onParseError mode:

• 'fail' (default) → exchange:failed (or error:caught if a route .error() handler recovers).
• 'abort' → exchange:failed for the bad item, then the source aborts and context:error fires.
• 'drop' → exchange:dropped with reason: "parse-failed" (no step:failed fires; the parse step catches and drops cleanly).

Subscribe with a glob to count source parse failures across all routes:

ctx.on('route:*:step:failed', ({ details }) => {
  if (details.operation === 'parse') metrics.increment('source.parse.failed');
});
ctx.on('route:*:exchange:dropped', ({ details }) => {
  if (details.reason === 'parse-failed') metrics.increment('source.parse.dropped');
});

Plugin events

Plugin events are scoped to a plugin ID.

Authentication events

Emitted by auth-enabled adapters (currently MCP HTTP) on every auth attempt. The source field identifies which adapter emitted the event.

reason is one of "missing_header", "unsupported_scheme", or "invalid_token".

MCP plugin events

Events emitted by the MCP plugin during server and tool lifecycle. Subscribe with wildcards (e.g. plugin:mcp:tool:**) for broad observability.

Server events

Session events

Tool call events

Related