Skip to content

feat(engine): add on_enter node-entry hook#37

Merged
wavekat-eason merged 3 commits into
mainfrom
feat/node-enter-hook
Jul 21, 2026
Merged

feat(engine): add on_enter node-entry hook#37
wavekat-eason merged 3 commits into
mainfrom
feat/node-enter-hook

Conversation

@wavekat-eason

Copy link
Copy Markdown
Contributor

Adds FlowEffects::on_enter(node, kind), called once as the engine
enters each node in run_node, before that node's own effects run.
Default no-op, so it's backward-compatible — existing FlowEffects
impls compile and behave unchanged.

Why

A consumer (wavekat-voice's live call-screening UI) needs to light up
the current node on the flow graph as a call moves through it. The
existing effect calls (speak, collect_digit, record_message, …)
can't drive that on their own: node kinds repeat (multiple greetings /
menus), so an effect can't name which node is active, and an
effect-less node like hours fires no effect at all and would be
skipped on the map. on_enter carries the node's id and kind at
the one moment that unambiguously identifies it — arrival.

It fires for every visited node, including hours, and exactly once
per entry (a node re-entered by a menu retry loop fires again on each
real re-entry, not on internal retries).

Changes

  • FlowEffects::on_enter(&mut self, node: &NodeId, kind: &'static str)
    with a default no-op.
  • run_node calls fx.on_enter(id, kind) right after resolving the
    node's kind.
  • MockEffects records entries; new test
    on_enter_reports_each_node_as_the_engine_reaches_it pins entry
    order across the open/closed paths and the menu-retry case.
  • Version bump 0.0.4 → 0.0.5.

Release

The downstream consumer pins wavekat-flow = "0.0.5" behind a local
[patch.crates-io] for iteration. Publish 0.0.5 to crates.io after
this merges
, so the consumer can drop the patch and resolve the pin
from the registry.

36 tests pass.

The engine's per-node record was only available at run end (the trace).
A live consumer that wants to show which node is executing *right now* —
and the path the caller has taken so far — had no signal until the call
was over.

Add `FlowEffects::on_enter(node, kind)`, called once as the engine
reaches each node, before that node's own effects run. It fires for
every visited node, including `hours` (which runs no other effect) and
a node re-entered by a goto; a menu's internal retries do not re-fire
it. Default no-op, so existing impls are unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Hj93UCb3RKjF6mBwzhsp9f
Comment thread crates/wavekat-flow/Cargo.toml Outdated
Comment thread Cargo.lock Outdated
@wavekat-eason
wavekat-eason marked this pull request as ready for review July 21, 2026 10:14
@wavekat-eason
wavekat-eason merged commit 5bb37c1 into main Jul 21, 2026
3 checks passed
@wavekat-eason
wavekat-eason deleted the feat/node-enter-hook branch July 21, 2026 10:14
@github-actions github-actions Bot mentioned this pull request Jul 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant