# RFD 011: System Notification Queue - **Status**: Discussion - **Category**: Design - **Authors**: Jean Mertz - **Date**: 2026-02-23 - **Requires**: [RFD 005], [RFD 009] - **Required by**: [RFD 037] ## Summary This RFD introduces a system notification queue that allows JP's internal subsystems to deliver asynchronous notifications to the assistant. Notifications are recorded in the conversation event stream and delivered at the next available communication opportunity — piggybacking on existing messages rather than fabricating new events. This solves the "stateful tool finished but nobody asked" problem from [RFD 009] and provides a general-purpose channel for any subsystem that needs to inform the assistant of out-of-band events. ## Motivation Several JP subsystems produce events that the assistant should know about but that don't fit neatly into the request/response conversation model: - **Stateful tool handles** ([RFD 009]): A background `cargo check` finishes while the assistant is doing other work. The assistant should know the result is ready, but the event model requires `ToolCallRequest → ToolCallResponse` pairs — JP can't inject a response without a request. - **MCP server events**: A server disconnects or becomes unresponsive. The assistant might be relying on tools from that server. - **Workspace changes**: A file the assistant is working with is modified externally (e.g., by the user in their editor). - **Configuration changes**: A mid-conversation config reload affects available tools or model parameters. - **Resource limits**: Token budget approaching exhaustion, rate limit warnings. Today, none of these have a delivery path. Some are logged (and thus invisible to the assistant), others are silently dropped. [RFD 009] recommended assistant-driven polling for stateful tools, which works but is fragile — the assistant must remember to check. The system notification queue provides a delivery mechanism without bending the conversation event model. Notifications piggyback on messages that JP is already sending, so no fabricated events are needed. ## Design ### Notifications A notification is a small, human-readable message from a JP subsystem: ```rust /// A system notification from a JP subsystem. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct SystemNotification { /// The kind of notification, identifying the source subsystem and /// event type. Used for configuration filtering. pub kind: NotificationKind, /// The severity level of the notification. #[serde(default, skip_serializing_if = "NotificationLevel::is_info")] pub level: NotificationLevel, /// Human-readable message for the assistant. pub message: String, } /// Identifies the source and type of a system notification. /// /// The `Display` implementation produces the dotted form `"{source}.{name}"` /// (e.g. `"tool.stopped"`). `FromStr` parses it back. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct NotificationKind { /// The subsystem that produced this notification. /// e.g. "tool", "mcp" pub source: String, /// The event type within that subsystem. /// e.g. "stopped", "disconnected" pub name: String, } /// The severity level of a system notification. /// /// Levels serve two purposes: they help the LLM prioritize which /// notifications to act on, and they control delivery urgency — /// `Critical` notifications trigger forced delivery rather than waiting /// for the next natural contact point. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum NotificationLevel { /// Informational. No action expected from the assistant. #[default] Info, /// Something may need attention soon. Warning, /// Something failed or needs attention. Error, /// Immediate attention required. Triggers forced delivery. Critical, } ``` Notifications are intentionally minimal. The `kind` field drives configuration filtering (see [Configuration](#configuration)). The `level` field controls delivery urgency and helps the LLM prioritize. The `message` field is what the assistant sees. No unique ID, timestamp, or structured data — the event envelope provides the timestamp, and there is no current need for the rest. These can be added later if a concrete use case arises. Both `source` and `name` are free-form strings rather than enums. The set of producers will grow over time as subsystems are added, and future plugins may produce their own notification kinds. String fields keep the type open for extension without code changes. ### Event stream integration Notifications are tracked through the conversation event stream using a new event type and by embedding delivered notifications in carrier events. #### Queueing When a subsystem produces a notification, JP records it in the event stream: ```rust /// A queued system notification event. /// /// This event records that a notification has been produced by a subsystem /// and is waiting for delivery to the assistant. The inner notification is /// delivered by embedding it in the next carrier event (ChatRequest or /// ToolCallResponse). #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct SystemNotificationQueued { /// The notification to deliver. #[serde(flatten)] pub notification: SystemNotification, } ``` `SystemNotificationQueued` wraps `SystemNotification` so the notification type is defined once and reused in both the queue event and the carrier events. `#[serde(flatten)]` keeps the serialized JSON flat. A new `EventKind` variant is added: ```rust pub enum EventKind { // ... existing variants ... /// A system notification has been queued for delivery. /// /// This is an internal bookkeeping event. It is not provider-visible — /// providers never see this event directly. Instead, the notification /// content is embedded in the next carrier event. SystemNotificationQueued(SystemNotificationQueued), } ``` This variant returns `false` from `is_provider_visible()`, so it is filtered out before any provider's message conversion logic runs. #### Delivery Notifications are delivered by embedding them in carrier events. `ChatRequest` and `ToolCallResponse` gain a `notifications` field: ```rust pub struct ChatRequest { pub content: String, pub schema: Option>, /// The source of this chat request. #[serde(default)] pub source: ChatRequestSource, /// System notifications delivered with this message. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub notifications: Vec, } /// The origin of a chat request. #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum ChatRequestSource { /// User-initiated chat request (the default). #[default] User, /// System-initiated chat request (e.g., critical notification delivery). System, } pub struct ToolCallResponse { pub id: String, pub result: Result, /// System notifications delivered with this message. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub notifications: Vec, } ``` Embedding the full `SystemNotification` in the carrier event (rather than referencing it by ID) means each event is self-contained. When inspecting the stream JSON, the delivered notifications are visible right there in the carrier event, alongside the content they were delivered with. The duplication is minimal — notifications are short text messages. #### Determining pending notifications At a delivery point, JP collects all `SystemNotificationQueued` events that appear after the last `ChatRequest` or `ToolCallResponse` in the stream. These are the pending notifications. Delivery always drains the full set — there is no partial delivery. The event stream is typically under 1000 events, so a linear scan at each delivery point is sufficient. No caching or indexing is needed. ### Delivery points Notifications are delivered at four points — moments where JP is already composing a message to the assistant, plus a forced delivery path for critical notifications: 1. **Tool call responses.** When JP sends `ToolCallResponse`(s) back to the assistant after a tool execution cycle, any pending notifications are included in the first response's `notifications` field. 2. **User-initiated in-turn messages.** When the user interrupts the stream (Ctrl+C) and chooses to reply, pending notifications are included in the user's `ChatRequest`. 3. **Turn boundaries.** When a turn ends and a new turn begins (the user sends a new query), any remaining notifications are included in the new `ChatRequest`. 4. **Forced delivery (Critical).** When a `Critical` notification is queued JP forces immediate delivery rather than waiting for a natural contact point. If the assistant is mid-stream, JP aborts the stream and sends a system-initiated `ChatRequest` containing the critical notification(s) plus any other pending notifications. This avoids the scenario where a critical event (e.g., a tool error, a resource failure) goes undelivered until the user's next message. See [Forced delivery for Critical notifications](#forced-delivery-for-critical-notifications) for details. At each point, JP checks for pending notifications. If there are none, the `notifications` field remains empty and is omitted from serialization. If there are pending notifications, they are collected into the carrier event's `notifications` field and passed to the provider as part of the query. ### Forced delivery for Critical notifications When a `Critical` notification is queued, JP forces delivery rather than waiting for the next natural contact point. The mechanism depends on what JP is currently doing: - **Between turns (waiting for user input).** JP immediately sends a system-initiated `ChatRequest` with the pending notifications and a short context message explaining the interruption. - **Mid-stream (assistant is generating a response).** JP aborts the current stream, records the partial response as a truncated `ChatResponse`, then immediately sends the system-initiated `ChatRequest`. This ensures the assistant isn't left generating a response based on stale assumptions — e.g., if a tool it was relying on just failed. The abort must be distinguished from a transient provider error so the retry logic is not triggered. - **During tool execution.** The notification is delivered with the tool responses at the next natural contact point, since tool execution already provides a delivery opportunity. A system-initiated `ChatRequest` is distinguished from a user-initiated one by its `source` field (`ChatRequestSource::System` vs `ChatRequestSource::User`). The turn loop treats it like any other `ChatRequest`, so the assistant can respond, call tools, or acknowledge the notification as it sees fit. The `source` field also allows the turn loop and UI to handle system-initiated turns distinctly if needed (e.g., visual treatment, interruptibility). ### Provider-level formatting Providers decide how to surface notifications to the LLM. The notifications are included in the query alongside the message content, similar to how attachments are handled. Each provider can choose the most appropriate delivery mechanism for its API: - **OpenAI**: Use the `developer` role to send notifications as a separate message preceding the user/tool message. - **Anthropic**: Use a system message injection or prepend to content. - **Fallback**: Format notifications as a markdown block and prepend to the message content. A `SystemNotifications` wrapper type implements `Display` to provide consistent default formatting for providers that don't have a dedicated mechanism: ```rust /// A collection of system notifications, with a `Display` implementation /// that formats them as a markdown block suitable for prepending to message /// content. pub struct SystemNotifications<'a>(pub &'a [SystemNotification]); impl fmt::Display for SystemNotifications<'_> { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { // Renders the markdown block shown below. } } ``` The default markdown format groups notifications by level: ```markdown --- **JP System Notifications** These are automated system messages from JP, unrelated to the response which follows below. They are delivered in this message to make you aware of them. You can ignore irrelevant notifications — they will NOT be delivered again. **Critical:** - Tool `cargo_check` failed with exit code 101. **Error:** - MCP server `github` has disconnected. **Info:** - Tool `cargo_check` (handle `h_3`) has stopped with result available. - Tool `git` (handle `h_1`) is waiting for input. --- ``` Providers that want structured access to individual notifications can iterate over the slice directly. Providers that just need a string use `Display`. ### Notification lifecycle 1. **Enqueue**: A subsystem produces a notification. JP writes a `SystemNotificationQueued` event to the conversation stream. 2. **Accumulate**: The notification sits in the stream as a pending event until a delivery point is reached. 3. **Deliver**: At a delivery point, all pending notifications are collected into the carrier event's `notifications` field. The provider formats and delivers them alongside the message content. For `Critical` notifications, delivery is forced immediately rather than waiting for a natural contact point. 4. **Done**: The carrier event in the stream serves as proof of delivery. The notification will not be delivered again. Notifications are fire-and-forget. The queue does not track acknowledgment. ### Crash recovery Because notifications are persisted as events in the stream, they survive crashes. If JP crashes after writing a `SystemNotificationQueued` event but before writing the carrier event that delivers it, the notification is still pending on restart. The next delivery point will pick it up. ### Producers Any JP subsystem can produce notifications. Initial producers: | Producer | Source | Name | Level | When | | -------------------- | ------ | -------------- | ------- | ---------------------------------------- | | Tool handle registry | `tool` | `stopped` | Info | A stateful tool reaches `Stopped` | | | | | | without being polled | | Tool handle registry | `tool` | `waiting` | Warning | A stateful tool enters `Waiting` without | | | | | | being polled | | Tool handle registry | `tool` | `failed` | Error | A stateful tool fails unexpectedly | | MCP client | `mcp` | `disconnected` | Error | An MCP server connection drops | | MCP client | `mcp` | `reconnected` | Info | An MCP server reconnects | Future producers might include: workspace file watcher, token budget tracker, configuration reload system. ### Configuration Notification delivery is configurable at two levels: #### Per-tool notification control Tools can declare which notification names they emit, and users can configure which are delivered. The source is implicit — it's scoped to the tool — so only the notification name is needed: ```toml [conversation.tools.cargo_check] source = "builtin" stateful = true # Control which notifications this tool can deliver. # Default: all notifications enabled. [conversation.tools.cargo_check.notifications] stopped = true waiting = false failed = true ``` #### Global notification control Users can filter notifications by source, or by source and name: ```toml # Source-level filtering: disable all notifications from a source. [conversation.notifications.kinds.mcp] enable = false # Name-level filtering within a source. [conversation.notifications.kinds.tool] stopped = true waiting = true failed = true [conversation.notifications.kinds.mcp] disconnected = true reconnected = false # don't bother the assistant with reconnects ``` The nested TOML structure maps directly to the `NotificationKind` struct's `source` and `name` fields. This enables both source-level control (disable all `mcp` notifications) and fine-grained per-name control within a source. Configuration filtering is applied at delivery time, not at enqueue time. A `SystemNotificationQueued` event is always written to the stream regardless of configuration — this ensures the stream is a complete record of what happened. Filtered notifications simply never appear in a carrier event's `notifications` field. ## Drawbacks **Delivery latency for non-critical notifications.** If the turn ends without hitting any delivery point (e.g., the assistant responds with no tool calls and the user doesn't interrupt), non-critical notifications are carried to the next turn's first message. In the worst case, a notification sits in the queue until the next user query. `Critical` notifications mitigate this through forced delivery, but `Info`/`Warning`/`Error` notifications may be delayed. **Formatting fragility.** The default markdown block format depends on the assistant recognizing and correctly interpreting it. Different models may handle the "ignore irrelevant notifications" instruction differently. Provider-level formatting mitigates this by allowing each provider to use the best available mechanism (e.g., OpenAI's `developer` role), but the fallback format should be validated with multiple providers. ## Alternatives ### In-memory queue only Maintain notifications in an in-memory queue without persisting them as events. Drain the queue at delivery points and embed the formatted text directly in message content. **Rejected because:** An in-memory queue loses all pending notifications on crash. Notifications are not independently queryable or auditable. Conversation forking requires special handling to carry over pending notifications. The event-stream approach solves all of these naturally. ### Deliver notifications as synthetic tool calls Fabricate `ToolCallRequest`/`ToolCallResponse` pairs for notifications. **Rejected because:** It violates the event model (the assistant didn't request these tool calls) and would confuse providers that validate tool call ID matching. It also pollutes the conversation history with fake tool calls. ### Push notifications via streaming Inject notification events into the LLM's response stream, interrupting the assistant's output. **Rejected because:** This would require pausing the stream, injecting content, and resuming — complex and likely to cause rendering artifacts. The assistant also can't act on a notification mid-stream (it's still generating its response). ### Separate `SystemNotificationDelivered` event Instead of embedding notifications in carrier events, emit a separate `SystemNotificationDelivered` event that references notification IDs. **Rejected because:** It creates a temporal coupling between two events that must stay in sync. If JP writes the carrier event but crashes before writing the `Delivered` event, the stream is inconsistent. Embedding in the carrier event makes delivery atomic — one event write, one source of truth. It also removes a layer of indirection when inspecting the stream and removes the need for notification IDs. ## Non-Goals - **Notification acknowledgment.** The queue is fire-and-forget. No mechanism for the assistant to acknowledge or dismiss notifications. - **User-facing notification display.** This RFD covers delivery to the assistant, not to the user's terminal. User-facing notifications (e.g., "MCP server disconnected" shown in the terminal) are a separate concern. - **Structured notification data.** Notifications carry a human-readable `message` only. Structured data (e.g., JSON payloads) can be added later if a concrete use case arises. ## Risks and Open Questions ### Token budget impact Each notification adds ~20-50 tokens to the message. With 10 notifications, that's 200-500 tokens of overhead. For conversations near the context window limit, this could push out useful context. Should notifications be subject to a token budget? ### Provider formatting validation Different providers have different mechanisms for delivering system-level messages. The `developer` role (OpenAI), system message injection (Anthropic), and content prepending (fallback) should be tested across models to determine which approach produces the best assistant behavior. The `SystemNotifications` `Display` format should also be validated for clarity across models. ### Queue ordering Should notifications be delivered in chronological order (oldest first) or reverse (newest first)? Chronological is more natural, but the assistant reads top-to-bottom and the most recent notification is likely the most relevant. ### Interaction with conversation compaction When conversation compaction ([RFD 036]) is implemented, `SystemNotificationQueued` events and their corresponding carrier events will be subject to compaction. Old notifications are stale by definition, so dropping them during compaction is appropriate. The explicit event types make this straightforward — a compaction pass can identify and handle notification events without parsing message content. ### System-initiated turn semantics The forced delivery mechanism for `Critical` notifications introduces the concept of a system-initiated turn — a turn not triggered by the user (`ChatRequestSource::System`). The `source` field makes these turns explicitly identifiable, but questions remain: how is the system-initiated `ChatRequest` content phrased? Should it be visually distinct in the conversation UI? Can the user interrupt a system-initiated turn the same way as a regular turn? ## Implementation Plan ### Phase 1: Event types and formatting 1. Define `SystemNotification`, `NotificationKind`, and `NotificationLevel` in `jp_conversation`. 2. Define `SystemNotificationQueued` event and add the `EventKind` variant. 3. Add `notifications: Vec` to `ChatRequest` and `ToolCallResponse`. 4. Implement `SystemNotifications` wrapper with `Display` formatting (grouped by level). 5. Ensure `SystemNotificationQueued` returns `false` from `is_provider_visible()`. 6. Unit tests for serialization, formatting, and `is_provider_visible`. Can be merged independently. No behavioral changes. ### Phase 2: Delivery point integration 1. Implement pending notification collection (scan stream for `SystemNotificationQueued` events after the last carrier event). 2. Wire into tool call response delivery — populate `notifications` on the first `ToolCallResponse`. 3. Wire into `ChatRequest` construction — populate `notifications` when the user sends a new message or interrupts. 4. Implement provider-level formatting for at least two providers (one using a dedicated mechanism like `developer` role, one using the `Display` fallback). 5. Integration tests verifying delivery at each point. Depends on Phase 1. All notifications queue normally at this phase — no forced delivery yet. ### Phase 3: Tool handle producer 1. The tool handle registry (from [RFD 009]) writes `SystemNotificationQueued` events when a handle changes state without being polled (`tool.stopped`, `tool.waiting`, `tool.failed`). 2. Integration tests with a stateful tool that finishes in the background. Depends on Phase 2 and [RFD 009] Phase 4. ### Phase 4: Configuration 1. Add `conversation.notifications.kinds` config section with nested source/name structure. 2. Add per-tool `notifications` config (name-level filtering). 3. Wire configuration into the delivery logic (filter at delivery time). Depends on Phase 3. Can be iterated independently. ### Phase 5: Critical notification forced delivery 1. Implement the forced delivery path for `Critical` notifications. 2. Handle the three contexts: between turns, mid-stream, during tool execution. 3. System-initiated `ChatRequest` construction and turn loop integration. 4. Integration tests for forced delivery in each context. Depends on Phase 2. Can be developed in parallel with Phases 3-4. ### Phase 6: Additional producers Add MCP event producers, and any other subsystems that benefit from notifications. Each producer is independent and can be added incrementally. ## References - [RFD 009: Stateful Tool Protocol][RFD 009] — defines stateful tool handles and identifies the proactive delivery problem that this RFD solves. - [RFD 010: PTY Infrastructure and Interactive Tool SDK][RFD 010] — interactive tools that benefit from notifications when sessions finish. - [RFD 036: Conversation Compaction][RFD 036] — compaction of conversation history, which interacts with notification event lifecycle. - [Query Stream Pipeline] — the turn loop and delivery points where notifications are injected. - [RFD 028: Structured Inquiry System][RFD 028] — the inquiry system, a potential future notification producer. [Query Stream Pipeline]: ../architecture/query-stream-pipeline.md [RFD 005]: 005-first-class-inquiry-events.md [RFD 009]: 009-stateful-tool-protocol.md [RFD 010]: 010-pty-infrastructure-and-interactive-tool-sdk.md [RFD 028]: 028-structured-inquiry-system-for-tool-questions.md [RFD 036]: 036-conversation-compaction.md [RFD 037]: 037-await-tool-for-stateful-handle-synchronization.md