fix(python): async custom_builtins work inside Jupyter / running event loop

[chaliy]

What

When execute_sync() is called from inside a running asyncio event loop
(Jupyter / IPython), Python raises RuntimeError: Cannot run the event loop while another loop is running — even for a brand-new private loop created
inside the Rust binding. Async custom_builtins callbacks silently failed
with exit_code=1 and a "coroutine was never awaited" warning.

Why

execute_sync() drives the Tokio future on the calling thread via
rt.block_on(). When that thread is Jupyter's event-loop thread, Python's
asyncio thread-local state marks it as "already running" and refuses any
run_until_complete call — even on a different loop object.

How

PyPrivateAsyncLoop::run_awaitable now checks asyncio.get_running_loop()
before calling run_until_complete. If a loop is already running on the
thread, it falls back to a daemon background thread with its own fresh
event loop. The coroutine is driven via context.run(loop.run_until_complete, coro) so ContextVars from the calling context propagate correctly. The Python
helper is cached on first use to avoid repeated module compilation.

The await execute() path is unaffected — async callbacks already run on the
caller's loop via pyo3_async_runtimes task scheduling.

Tests added

• tests/test_jupyter_compat.py — dedicated test file with two simulation
  patterns:

  • asyncio.run(cell()) — most explicit Jupyter analogue: boots a real event
    loop then calls execute_sync() from inside it (4 tests covering Bash,
    ScriptedTool, ContextVars, multiple sequential calls)
  • @pytest.mark.asyncio — exact Jupyter match via pytest's managed loop
    (5 tests: Bash, BashTool, ScriptedTool, ContextVars)
  • await execute() caller-loop verification (4 tests: Bash, BashTool,
    ContextVars)

• examples/jupyter_basics.ipynb — official root-level example notebook
  (async/sync execution, persistent VFS, sync and async custom_builtins,
  ContextVar tracing, ScriptedTool multi-tool pipeline); verified executable
  end-to-end with nbconvert

CI

• Added examples/*.ipynb to path triggers in python.yml
• Added nbconvert + jupyter-client + ipykernel to the examples job
• New "Run notebooks" step executes jupyter_basics.ipynb with a 120 s
  timeout; a cell error fails the job

Spec

specs/python-package.md updated with a custom_builtins async callback
section documenting the three dispatch paths and ContextVar propagation
semantics.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!