Interface: ProcessHooks

Defined in: packages/core/src/graph/types.ts:94

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

Only graph()-built Processables read this today — a lone Baleybot or a pipeline() chain ignores options.hooks entirely. See the deliberate scoping note on ProcessOptions.hooks in ../types.js before wiring this up elsewhere: step-boundary semantics don't generalize past graph's per-node model without inventing meaning for single-step invocations.

onStepEvent is not a separate emission channel — it rides on the same categorized subscribeToAll contract every Processable implements (core/stream-hub.ts's StreamHub/fanOutSubscribeToAll); this is purely an ordering/batching layer on top of that one real event stream.

Every callback may return Promise<void> — the runner awaits each before proceeding to the next step. This is the whole point: callers can order their persistence against execution (e.g. "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, the runner may execute parallel branches concurrently, so hook callbacks can interleave. Callers that need isolation partition on the context themselves.

Zero-cost: if options.hooks is absent, the runner skips event construction entirely. 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/graph/types.ts:107

Fires after a step completes successfully. Runner awaits before starting any downstream node — 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/graph/types.ts:111

Fires when a step errors. Runner awaits, then cascades skips to descendants as onStepSkipped({ kind: 'upstream_failed', ... }).

Parameters

ctx

NodeContext

error

Error

Returns

void | Promise<void>

---

onStepEvent?

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

Defined in: packages/core/src/graph/types.ts:102

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/graph/types.ts:116

Fires when a step is skipped — either because an ancestor errored, a filter upstream dropped the row, or the step itself is unrunnable (missing config). 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/graph/types.ts:97

Fires immediately before a step's run() is invoked. Runner awaits before streaming begins.

Parameters

ctx

NodeContext

input

unknown

Returns

void | Promise<void>