8.0 KiB
status, created, owner
| status | created | owner |
|---|---|---|
| shipped | 2026-07-24 | kandev |
Semantic Notifications
Why
Kandev currently treats every transition to a session's generic
WAITING_FOR_INPUT state as though the agent asked the user a question. That
state is also used before the first turn and after an ordinary completed turn,
so notifications can claim that input is required when it is not. The same
event is deduplicated once per session, which can let an early false positive
suppress a later real clarification request.
The notification settings page also snapshots an empty provider store during a cold load. Providers fetched immediately afterward remain absent from the rendered draft, making an intact configuration look lost.
What
- Notification settings expose two independent session events:
- Agent turn finished — notify after each completed agent turn.
- Agent needs an answer — notify when the agent explicitly requests a user response through Kandev's clarification flow.
- A user may enable either event, both events, or neither event for each notification provider.
- When a provider-create request omits its event selection, the clarification event is enabled by default and turn-finished remains opt-in. An explicitly empty selection enables neither event.
- Existing
session.waiting_for_inputsubscriptions migrate to Agent needs an answer only. Migration never opts a provider into Agent turn finished. - Session startup, readiness, idle state, and generic
WAITING_FOR_INPUTtransitions do not themselves send either notification. - A turn-finished notification uses:
- title:
Agent turn finished - body:
The agent finished a turn on "<task title>".
- title:
- A clarification notification uses:
- title:
Agent needs your answer - body:
The agent asked a question on "<task title>".
- title:
- The local browser and native desktop notification path uses the same semantic event and copy as remote providers such as Apprise.
- Native session-failure alerts remain an independent safety channel whenever the Local provider is enabled; they are not controlled by either semantic event checkbox.
- On a cold settings-page load, the provider list and saved event selections appear after the provider request completes. Initial hydration must not overwrite edits the user has already made.
Data Model
The durable provider subscription keys are:
session.turn_finishedsession.clarification_requested
Each delivery records both the task-session ID and a semantic occurrence ID:
- turn-finished occurrence ID: the completed turn ID;
- clarification occurrence ID: the clarification request's pending/request ID.
Delivery idempotency is scoped to provider, event type, and occurrence ID. Consequently, replaying one occurrence does not duplicate a delivery, while separate turns or clarification requests in the same session may each notify.
session.waiting_for_input is a legacy subscription key accepted only by the
data migration. It is not offered by the settings API after migration and is
not emitted as a new notification event.
API Surface
- The notification-provider API returns the two semantic events in its available-event catalog.
- Provider create and update requests persist the selected semantic event keys.
- An omitted create-time event field applies the clarification-only default; an explicitly empty event array persists no subscriptions.
- The WebSocket gateway may emit
session.turn_finishedandsession.clarification_requestedfor the local notification provider. - Local semantic notifications carry the occurrence ID through the WebSocket envelope/payload so native de-duplication uses the same identity as backend delivery de-duplication.
- Existing provider URLs, enabled state, and unrelated event subscriptions are unchanged.
State and Event Semantics
| Domain occurrence | Turn finished | Needs an answer |
|---|---|---|
| Session starts or becomes ready | No | No |
Session enters generic WAITING_FOR_INPUT |
No | No |
| An agent turn is durably completed | Yes, when selected | No |
| An agent-authored structured clarification request is created | No | Yes, when selected |
| The user answers a clarification | No | No |
| The same domain event is replayed | No duplicate | No duplicate |
| A later occurrence happens in the same session | Yes | Yes |
A clarification bundle containing several questions is one occurrence and produces at most one notification per provider. User-authored, system-authored, malformed, or unscoped clarification-shaped messages do not notify.
Permissions
Notification configuration continues to use the existing settings authorization rules. This change grants no additional access to task content. Notification bodies contain the task title but not the question text.
Failure Modes
- A provider send failure releases that occurrence's de-duplication claim so a replay may retry it. It does not mark a later occurrence as delivered.
- Replayed event-bus messages do not create duplicate deliveries for the same provider and occurrence.
- A provider refresh received while persisted-provider drafts are clean may hydrate their baseline. It must not replace unsaved edits to an existing provider. A pre-load new-provider form remains intact while the authoritative provider list hydrates around it.
Persistence Guarantees
- Existing provider records and credentials survive the schema migration.
- An enabled legacy
session.waiting_for_inputsubscription becomes an enabledsession.clarification_requestedsubscription. A disabled legacy subscription remains disabled unless an already-existing semantic subscription is enabled. - Migration is idempotent and does not create duplicate subscriptions.
- Existing delivery history remains available for audit, but legacy session-level deduplication does not suppress new semantic occurrences.
- The de-duplication claim is inserted atomically with its semantic occurrence identity. A failed provider send removes that exact provider/event/occurrence claim.
Scenarios
- GIVEN a provider subscribed to clarification requests, WHEN a session starts and waits for its first user turn, THEN no notification is sent.
- GIVEN a provider subscribed only to turn completion, WHEN an ordinary
agent turn completes, THEN it receives
Agent turn finishedand no copy claims that user input is required. - GIVEN a provider subscribed only to clarification requests, WHEN an
agent issues a structured question bundle, THEN it receives one
Agent needs your answernotification. - GIVEN two completed turns in one session, WHEN turn completion is selected, THEN each turn can produce one notification.
- GIVEN a clarification event is delivered and then replayed, WHEN both copies reach the notification service, THEN only one delivery is sent.
- GIVEN an existing provider subscribed to
session.waiting_for_input, WHEN the database is upgraded, THEN the provider is subscribed to clarification requests and not to turn completion. - GIVEN saved providers exist, WHEN the notifications settings route is opened from a cold frontend store, THEN the providers and their selections appear after loading without requiring a remount.
- GIVEN a 390px mobile viewport, WHEN both event rows are displayed, THEN a stacked mobile composition keeps every label, description, provider, and control readable and touch operable without horizontal scrolling.
Out of Scope
- Inferring that arbitrary prose ending in a question mark requires an answer.
- Including clarification text or other conversation content in notification payloads.
- Per-task notification policy, schedules, batching, or quiet hours.
- Retrying provider deliveries beyond the existing notification-provider behavior.
- Adding a new notification-settings fetch-error surface.
- Changing session lifecycle states or the chat waiting-state presentation.