Skip to content

fix(events): track the sync handler future when async handlers are registered - #8961

Open
hdu_zhou (zuizhuai) wants to merge 5 commits into
crewAIInc:mainfrom
zuizhuai:fix/event-bus-sync-handler-future
Open

hdu_zhou (zuizhuai) wants to merge 5 commits into
crewAIInc:mainfrom
zuizhuai:fix/event-bus-sync-handler-future

Conversation

@zuizhuai

@zuizhuai hdu_zhou (zuizhuai) commented Nov 3, 2026 •

Copy link
Copy Markdown

Fixes #8949.

Problem

CrewAIEventsBus.emit() submits the sync handlers to the thread-pool executor, but it only returns that future to _track_future() in the sync-only branch:

sync_future = self._sync_executor.submit(
    ctx.run, self._call_handlers, source, event, sync_handlers, state
)
if not async_handlers:
    return self._track_future(sync_future)

When an event has both sync and async handlers, the sync future is returned to nobody and never registered as pending, so flush() — and shutdown(wait=True), which calls flush() first — can report True while a sync handler is still running, and sync-handler errors can surface after the caller believes the emission finished. replay() already tracks the same future unconditionally before its if not async_handlers check, so the two dispatch paths disagreed on identical code.

Change

emit() now calls self._track_future(sync_future) unconditionally and returns that future when there are no async handlers, mirroring replay(). The value returned for a sync-only emission is the same future as before; mixed emissions still return the async future.

Intentionally not done:

  • no change to replay(), aemit(), or the dependency-aware path;
  • no reordering of sync/async dispatch — the two still run concurrently;
  • no change to how handler errors are printed.

Tests

New file lib/crewai/tests/events/test_event_bus_flush.py:

  • test_flush_waits_for_sync_handler_when_async_handler_is_also_registered: registers a sync handler that sleeps 0.2 s and sets a threading.Event, plus a no-op async handler, emits, then asserts flush(timeout=5) returns True and the event is set. On main this fails: flush() returns immediately while the handler is still inside time.sleep, so the event is unset.
  • test_flush_waits_for_sync_handler_without_async_handlers: control for the sync-only path, green before and after.

Local results (Windows 11, Python 3.13.1):

tests/events/test_event_bus_flush.py ..                                2 passed
tests/events/test_event_context.py tests/events/test_event_replay.py   2 failed, 29 passed, 2 errors

The 2 failures (test_pop_empty_stack_returns_none, test_depth_limit_exceeded_raises) and 2 errors (two Flow checkpoint-resume tests) reproduce identically on unmodified main with the same invocation, so they are pre-existing in this environment and unrelated to the change.

Lint: ruff check on the changed files → All checks passed!; ruff format --check → already formatted. Note the repository ruff config excludes lib/crewai/tests/, so the new test file is covered by neither.

Environment limitation: only lib/crewai was checked out here (sparse clone) and the package could not be installed editable (hatchling metadata step fails in this sandbox), so the suite was run with PYTHONPATH=lib/crewai/src and a hand-installed dependency subset. The LLM/VCR-based suites in tests/events/ (e.g. test_event_ordering.py) were therefore not executed — CI will be the first full run.


Note

Medium Risk
Changes core event dispatch completion semantics for mixed sync/async handlers; low code surface but affects shutdown and flush guarantees across the event bus.

Overview
Fixes a race where CrewAIEventsBus.emit() could finish flush() (and shutdown) while a sync handler was still running when the same event also had async handlers.

Previously the thread-pool future for sync handlers was only added to _pending_futures in the sync-only branch; mixed emissions returned only the async future, so flush() could succeed before slow sync work completed. emit() now always calls _track_future(sync_future) after submitting sync handlers (matching replay()), while still returning the async future when both handler types exist.

Adds test_event_bus_flush.py with a mixed-handler regression test and a sync-only control.

Reviewed by Cursor Bugbot for commit ca10f52. Bugbot is set up for automated code reviews on this repo. Configure here.

@strix-security

strix-security Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Strix Security Review

Warning

This pull request has 103 commits after the last Strix review (4186903). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

✅ No open security findings.

PR summary: Fixes event-bus flush semantics so `emit()` registers the sync-handler future even when async handlers are also present, letting `flush()`/`shutdown(wait=True)` wait for sync handlers; adds two tests covering mixed and sync-only emissions.

Review summary

The PR makes CrewAIEventsBus.emit() track the sync-handler future unconditionally so flush() and shutdown(wait=True) no longer return while a sync handler of a mixed sync+async emission is still running, matching what replay() already did. Reviewed the changed emit() path together with _track_future, _pending_futures, flush(), and replay(): tracking stays lock-protected with a completion callback that discards the future, so there is no new race or unbounded growth; the returned future object is unchanged; and no untrusted input, authorization, validation, or cryptographic behavior is touched. The new test file only exercises flush behavior. No security issues found in the changed code.

Ruled out (3)
  • Can unconditional future tracking introduce a race or unbounded memory growth in `_pending_futures`?
    `_track_future` adds under `_futures_lock` and registers a done-callback that discards the future, and the extra tracked futures are bounded by the 10-worker executor, so no race or leak is introduced.
  • Can tracking the sync future deadlock flush() by waiting on its own future?
    `flush()` waits with a timeout and the self-wait pattern already existed for sync-only emissions, with flush only invoked from crew/flow/telemetry lifecycle code rather than from handler bodies.
  • Does surfacing sync-handler exceptions for mixed emissions expose sensitive data?
    It reuses flush()'s existing console-print path used for sync-only and async futures and only prints exception text produced by library handler code, not attacker-controlled input.

Review 1 on this PR · 4186903 · requested Nov 3 04:32 UTC when the PR was opened


Reviewed by Strix
Re-run review · Configure security review settings

@zuizhuai

Copy link
Copy Markdown
Author

Vidit Ostwal (@Vidit-Ostwal) is this still wanted? flush() returns before a sync handler finishes when async handlers are registered — the sync handler is invoked without its future being tracked, so it drops out of the pending set and the turn is reported complete early. The fix registers that future alongside the async ones: 54 lines, 4 commits.

There is no other open PR against #8949 (#8962 was closed). If the event bus is being reworked and this doesn't fit the direction, say so and I'll close it rather than leave it parked.

This branch has not been deployed

No deployments
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.

[BUG] flush() returns before sync event handlers finish when async handlers are also registered

1 participant