Copilot — events

Per-module slice of docs/events-catalog.md (auto-generated). Update both files when adding or removing events.

Published

Event	When	Payload keys
copilot.session.started	A chat session is created (POST /sessions).	clinic_id, conversation_id, user_id
copilot.session.ended	A chat session is closed (POST /sessions/{id}/end).	clinic_id, conversation_id
copilot.digest.sent	The morning digest is emailed to a recipient.	clinic_id, recipient_user_id, date, email_status

copilot.tool.invoked and copilot.budget.threshold_reached are declared in EventType but reserved for the dashboards milestone — not published in v1. (Every tool call is already recorded in agent_audit_logs.)

Subscribed

Event	Handler	Effect
appointment.cancelled	events.on_appointment_cancelled	Create a copilot_nudges row ("fill the freed slot from recalls?"), deduped per appointment with a same-day TTL. Subscription only — no import of the publisher (ADR 0003).

Adding a new event

1. Add the constant to backend/app/core/events/types.py (EventType).
2. Publish from a service method after flush() — the bus runs handlers inline, before the request commits. Pass db=db so transactional subscribers can join the transaction (ADR 0019, issue #183).
3. Add a row above and re-run python backend/scripts/generate_catalogs.py.