[Lancetnik]

Why are these changes needed?

This PR introduces typed observation/downlink events, BaseEvent.source_event, publication identity on usage records, and delivery-guard support in the stream. It includes the public event-property tests. Existing delegation and usage-rollup behavior remains unchanged here; the routing protocol is activated only in #3526 with all required migrations.

The stack is organized as independently checkable changes: event primitives → scoped variables → complete routing integration → documentation → supporting files. Required tests and compatibility adaptations are included with the code that needs them. CI workflows and required checks are unchanged.

Related issue number

Stack #3525: #3524 (events) → #3523 (variables) → #3526 (routing) → #3527 (documentation) → #3528 (support). No linked issue.

Checks

• I've included any doc changes needed for https://docs.ag2.ai/. See https://docs.ag2.ai/latest/docs/contributor-guide/documentation/ to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

Independently tested this rebased head on Python 3.13: 7862 passed, 9 skipped, 437 deselected, 2 xfailed. Mypy passed (255 source files).

The local full runs deselect four ACP advertised-address networking cases whose connection timeouts also reproduce on the original baseline. GitHub runs the normal, unmodified workflow matrix. This PR's GitHub CI checks passed, including the complete Ubuntu Python 3.10–3.14, macOS, Windows, and Anthropic 1.x test matrix, coverage aggregation, type checks, lint, docs build, and CodeQL. Repository documentation is in #3527; website integration/build has not been run locally.

AI assistance

Codex assisted with implementation, tests, documentation, and reorganizing the stack around independent changes. The original import/type-check CI failures were reproduced locally. Required migrations now accompany the code that changes their contracts; no workflow or test skips were added to hide failures.

• I understand the changes in this PR and can explain them in my own words.
• I have verified that the PR description accurately reflects the actual diff.
• If AI assistance was used, I reviewed, tested, and validated the generated code/text before submitting.

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ag2/stream.py	20.00%	2 Missing and 2 partials ⚠️

Files with missing lines	Coverage Δ
ag2/events/__init__.py	100.00% <100.00%> (ø)
ag2/events/base.py	97.56% <100.00%> (+0.04%)	⬆️
ag2/events/delegation.py	100.00% <100.00%> (ø)
ag2/events/types.py	94.49% <100.00%> (+0.05%)	⬆️
ag2/stream.py	94.80% <20.00%> (-2.52%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.