docs(rfd): Add next edit suggestions RFD

[scotteveritt]

Summary

This RFD proposes adding support for next edit suggestions (tab-completions / predictive edits) to ACP. The proposal enables agents to proactively suggest:

• Edits the user might want to make next
• Navigation targets (cursor jumps) to where the next edit will occur
• Chained sequences of edits (tab-tab-tab flow)

Key Features

Feature	Description
Navigation suggestions	Predict cursor jumps alongside edits
Partial acceptance	Word-by-word, line-by-line tracking
Retention tracking	Track if suggestions are kept/modified/deleted
Chained suggestions	hasFollowUp for tab-tab-tab flow
Invalidation	Client-owned via documentVersion
Extensibility	Custom kinds (x- prefix) and metadata field

New Protocol Methods

• editContext/didChange - Context updates (Client → Agent)
• suggestions/request - Request suggestions (Client → Agent)
• suggestions/accept / reject / dismiss - User actions (Client → Agent)
• suggestions/retained - Retention tracking (Client → Agent)
• suggestions/offer / invalidate - Proactive suggestions (Agent → Client)

Research

Based on technical analysis of:

• Cursor Tab (edit + navigation prediction, tab-tab-tab sequences)
• GitHub Copilot NES (low-latency task-specific model)
• Supermaven (250ms latency, edit-diff context)
• Sourcegraph Cody (retention tracking, partial acceptance)

Changelog

2025-12-11: Major revision based on community feedback (@olegtaratuhin)

Streaming Removed:

• Removed suggestions/stream and suggestions/streamEnd methods entirely
• No production NES tool (Copilot, Cursor, Supermaven) uses character-by-character streaming
• Streaming deletions/modifications is semantically unclear
• Batch responses simplify both protocol and implementation

EditContext Made More Flexible:

• Only uri, documentVersion, and selections are now required
• All other fields (languageId, visibleRange, recentFiles, recentEdits) are optional
• Added extensions field for agent-specific context needs

Invalidation Clarified (Client-Owned):

• Clients own validity state via documentVersion
• Added validForDocumentVersion field to suggestions
• suggestions/invalidate is now advisory, not required
• Agents don't need to maintain complex caching

Extensibility Added:

• Added x- prefix pattern for custom EditSuggestionKind values
• Added metadata field to EditSuggestion for agent-specific data

Test plan

• Review RFD structure and completeness
• Validate protocol design against existing ACP patterns
• Discuss scope (edits + navigation vs broader "next action")
• Consider integration with existing RFDs (cancellation, session modes)

[ignatov]

@scotteveritt wow! you're reading our minds! Thanks for the contribution!

[olegtaratuhin]

Thanks for putting this proposal together! It’s a solid start, though given the size of this feature space, there are naturally quite a few details we'll need to sort out before moving forward.

A few initial thoughts:

EditContext: The current context definition feels a bit too specific/opinionated. Since most implementations will likely have their own unique context sources, including non-essential parts here might complicate the protocol without adding value for the majority of adopters.

Partial Results: Making partial results a strict requirement might not be realistic. Depending on how a "nes agent" represents outputs internally, mapping them to incremental file changes isn't always technically feasible.

Suggestion Responses: These feel a bit restrictive, though it might be a reasonable starting point. We can likely assume that some client/agent pairs will end up needing non-standard additional suggestion types anyway.

Streaming: This is the biggest area for improvement. Streaming in UI in the editor is very distracting, somewhat of a proof of this is that no vendor on the market currently does it this and Supermaven backtracked on this UX very quickly after the initial release. It is also unclear how streaming deletions or modifications would work. Mandating this assumes specific internal representations, which severely constrains how "nes agents" can be built.

Invalidation: There is a potential issue here regarding state management. If clients act on assumptions about what invalidates the agent (e.g., treating any typing as a cancellation), it forces agents to maintain complex internal caching, likely duplicating effort across implementations.

[scotteveritt]

Thanks @olegtaratuhin for the detailed feedback. I've taken a couple days to try and address your comments and landed on the following:

Streaming (Removed):
You were right that streaming is the biggest issue. After researching the landscape:

• No production NES tool (Copilot, Cursor, Supermaven) appears to use character-by-character streaming for ghost text
• Streaming deletions/modifications is semantically unclear
• The UX can be distracting rather than helpful

I've removed streaming entirely from this RFD. Suggestions are now returned as complete responses. This simplifies the protocol and aligns with how production implementations actually work.

EditContext:

• Made most fields optional (only uri, documentVersion, selections required)
• Added extensions field for agent-specific context needs
• Added comment clarifying which fields are required vs optional

Invalidation:

• Client owns validity state via documentVersion
• Added explicit validForDocumentVersion field to suggestions
• suggestions/invalidate is now advisory/optional, not required
• Removed need for agents to maintain complex caching

Suggestion Types:

• Added x- prefix pattern for custom kinds
• Added metadata field for agent-specific data

Let me know if these changes address your concerns, or if there are other aspects you'd like to discuss.