feat: notifications primitive #49
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Explores a new primitive for injecting external events into agent context: - Notification structure and types (source, priority, content) - Transcript integration via NotificationBlock - Multiple activation modes (passive, prompt, active) - Mid-stream injection points analysis - Priority-based injection strategies - State machine for turn interruption
Explores using synthetic tool calls to inject notifications mid-turn, leveraging existing tool infrastructure. Key insight: notifications can be injected between tool calls without agent explicitly checking.
Based on observation of Claude Code's <system-reminder> pattern: - Approach A (recommended): Append notifications to tool results with XML - Approach B (alternative): Synthetic tool call injection Key insight: tool results are unstructured text, so we can append notification content directly with XML delimiters. No fake tool calls needed - same call_id, just richer content.
Streamlined to focus on key findings: - Tool results are unstructured text (key insight) - Approach A: Append to tool results with XML (recommended, proven in Claude Code) - Approach B: Synthetic tool injection (alternative) - Comparison and recommendation Removed verbose sections on priorities, activation modes, state machines.
Documents options for when notifications pile up: - Append all (simple but unbounded) - Batch into single block (compact) - Coalesce by source (reduces noise) - Cap with overflow indicator (bounds tokens) Recommends combining: coalesce + batch + cap + prioritize.
- Tool Result Augmentation approach (proven pattern from Claude Code) - Unified notification flow based on agent state - Simplifications: no count, no cap, no coalescing (defer) - Ephemeral NotificationBlock for display only (not persisted)
- Add NotificationSource enum and Notification struct with to_xml() - Add is_ephemeral() method to Block trait - Add NotificationBlock for rendering notifications (ephemeral) - Custom Serialize for Turn filters out ephemeral blocks - Update research doc with implementation progress Remaining: wiring queue_message() and ToolEvent::Completed handler
tcdent
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Inject external events (user messages, file changes, background tasks) into agent context mid-turn.
Approach
Tool Result Augmentation - append
<notification>XML to tool results (same pattern as Claude Code's<system-reminder>).Completed
NotificationSourceenum andNotificationstruct withto_xml()is_ephemeral()method on Block traitNotificationBlock- rendered but not persisted to transcriptSerializeforTurnthat filters ephemeral blocksresearch/notifications-primitive.mdRemaining
queue_message()to create notifications when streamingToolEvent::Completedto drain and inject notifications<notification>tags