Skip to main content

Interface: ProcessHooks

Defined in: packages/core/src/core/hooks.ts:166

Per-step lifecycle hooks. Passed via ProcessOptions.hooks at invocation time, NOT registered long-term.

onStepEvent is not a separate emission channel — a composite observes the child it is already running, via withStepEvents on options.onToken (core/stream-hub.ts's forwardToken), and this is an ordering/batching layer on top of that.

It is not the subscribeToAll stream, and the two do not carry the same events. subscribeToAll is filtered by Baleybot's categorizing callback, which today has no case for several event types and drops them; the onToken path is unfiltered. A source that sets emitsInvocationEvents takes the observer path above; only a subscription-only source is read through subscribeToAll.

Every callback may return Promise<void> — the runner awaits each before proceeding. That is the whole point: callers can order their persistence against execution ("write status=running before the model produces its first token", "write status=success before the next step reads our output").

Ordering within a single (nodeId, sourceRowId): onStepStart → 0+ onStepEvent → exactly one of onStepDone / onStepError / onStepSkipped

Concurrency: across (nodeId, sourceRowId) pairs a runner may execute branches concurrently, so callbacks can interleave. Callers that need isolation partition on the context themselves.

Zero-cost: if options.hooks is absent, nothing is constructed. Hot-path tokens don't allocate event objects that nobody reads.

Error policy: a throwing hook is logged and execution continues by default. Set ProcessOptions.hooksAreFatal = true to promote hook errors to run-rejecting failures.

Properties​

onStepDone?​

optional onStepDone?: (ctx, output) => void | Promise<void>

Defined in: packages/core/src/core/hooks.ts:177

Fires after a step completes successfully. Awaited before anything downstream starts, so persistence lands before the next step reads it.

Parameters​

ctx​

NodeContext

output​

unknown

Returns​

void | Promise<void>

onStepError?​

optional onStepError?: (ctx, error) => void | Promise<void>

Defined in: packages/core/src/core/hooks.ts:182

Fires when a step errors. Awaited, then skips cascade to descendants as onStepSkipped({ kind: 'upstream_failed', ... }) where the composite has descendants to cascade to.

Parameters​

ctx​

NodeContext

error​

Error

Returns​

void | Promise<void>

onStepEvent?​

optional onStepEvent?: (ctx, event) => void | Promise<void>

Defined in: packages/core/src/core/hooks.ts:173

Fires for each BaleybotStreamEvent produced by a step. Same shape as subscribeToAll's onStreamEvent, but awaitable — hot-path persistence should return quickly (defer the write to a queue if needed).

Parameters​

ctx​

NodeContext

event​

BaleybotStreamEvent

Returns​

void | Promise<void>

onStepSkipped?​

optional onStepSkipped?: (ctx, reason) => void | Promise<void>

Defined in: packages/core/src/core/hooks.ts:187

Fires when a step is skipped — an ancestor errored, a filter upstream dropped the row, or the step itself is unrunnable. The reason is typed so callers can match exhaustively.

Parameters​

ctx​

NodeContext

reason​

SkipReason

Returns​

void | Promise<void>

onStepStart?​

optional onStepStart?: (ctx, input) => void | Promise<void>

Defined in: packages/core/src/core/hooks.ts:168

Fires immediately before a step runs. Awaited before streaming begins.

Parameters​

ctx​

NodeContext

input​

unknown

Returns​

void | Promise<void>