Session Observer Extension Points (session.on_receive / session.on_send) #2

New issue

Open

opened 2026-02-20 08:41:16 +00:00 by nazim · 0 comments

nazim commented

2026-02-20 08:41:16 +00:00

Contributor

Summary

Add observer extension points to the session layer, separate from existing provider points. Lets plugins observe message flow without interfering with the agent loop.

New Extension Points

session.on_receive — fired for each incoming message (full IncomingMessage)
session.on_send — fired after successful send (full OutgoingMessage)

Observer errors are caught and never break flow. on_send only fires on success.

Why

Currently there is no way for a plugin to say "I want to see every message that flows through" without hooking into agent-level hooks (which are correctly channel-ignorant by design). Channel awareness lives at the session layer — observers should too.

Enables

Lurker plugin (PR #31) — message archival
Audit logging
Analytics / rate limiting
Any future plugin that needs to observe without consuming

Design Principles

"Ignorance is bliss" — agent hooks stay channel-ignorant
Observer ≠ Provider — observers see messages, providers supply/deliver them
Observer errors never break message flow

Implementation

~20 lines added to session plugin:

Add extension point definitions
Call _notify_observers() in poll_all_channels() and send()

Related: PR #31 (lurker plugin)

## Summary Add **observer** extension points to the session layer, separate from existing provider points. Lets plugins observe message flow without interfering with the agent loop. ## New Extension Points - `session.on_receive` — fired for each incoming message (full `IncomingMessage`) - `session.on_send` — fired after successful send (full `OutgoingMessage`) Observer errors are caught and never break flow. `on_send` only fires on success. ## Why Currently there is no way for a plugin to say "I want to see every message that flows through" without hooking into agent-level hooks (which are correctly channel-ignorant by design). Channel awareness lives at the session layer — observers should too. ## Enables - Lurker plugin (PR #31) — message archival - Audit logging - Analytics / rate limiting - Any future plugin that needs to observe without consuming ## Design Principles - **"Ignorance is bliss"** — agent hooks stay channel-ignorant - **Observer ≠ Provider** — observers see messages, providers supply/deliver them - Observer errors never break message flow ## Implementation ~20 lines added to session plugin: 1. Add extension point definitions 2. Call `_notify_observers()` in `poll_all_channels()` and `send()` Related: PR #31 (lurker plugin)