diff --git a/docs/docs.json b/docs/docs.json index 783220c1..7ad41e69 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -119,7 +119,8 @@ "rfds/rust-sdk-v1", "rfds/logout-method", "rfds/session-delete", - "rfds/message-id" + "rfds/message-id", + "rfds/diff-delete" ] }, { diff --git a/docs/rfds/diff-delete.mdx b/docs/rfds/diff-delete.mdx new file mode 100644 index 00000000..bccdc05f --- /dev/null +++ b/docs/rfds/diff-delete.mdx @@ -0,0 +1,78 @@ +--- +title: "Represent deleted files in diff" +--- + +Author(s): [anna239](https://github.com/benbrandt) + +## Elevator pitch + +> What are you proposing to change? + +Add flag `deleted` to [Diff](https://agentclientprotocol.com/protocol/tool-calls#diffs) entity type for the case of a deleted file. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +Currently, in Diff entity type `newText` is not nullable, so it's not possible to distinguish between a deleted file and empty file. + +## What we propose to do about it + +> What are you proposing to improve the situation? + +Add flag `deleted` to [Diff](https://agentclientprotocol.com/protocol/tool-calls#diffs) entity type for the case of a deleted file. + +**Current structure (cannot distinguish deleted file from empty file):** + +```json +{ + "type": "diff", + "path": "/home/user/project/src/config.json", + "oldText": "{\n \"debug\": false\n}", + "newText": "" +} +``` + +**Proposed structure with `deleted` flag:** + +```json +{ + "type": "diff", + "path": "/home/user/project/src/config.json", + "oldText": "{\n \"debug\": false\n}", + "newText": "", + "deleted": true +} +``` + +Note: we would ideally make newText nullable, but that would break existing clients. + +## Shiny future + +> How will things will play out once this feature exists? + +It is possible for the agent to distinguish between a deleted file and an empty file. + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + +Adding the new field will be a non-breaking change, and clients that update can better distinguish between deleted and empty files. + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + +**Do we need to represent moved files?** + +An agent could represent that with a deleted file at the old path and a new file at the new path. + +We need to rework the entire diff structure to handle more cases, and binary files, but in the meantime this provides a stop-gap until we can implement a more comprehensive solution. + +### What alternative approaches did you consider, and why did you settle on this one? + +We considered making newText nullable, but that would break existing clients. + +## Revision history + +2026-02-20: Initial draft diff --git a/docs/updates.mdx b/docs/updates.mdx index 76a08d0d..1bcc4b80 100644 --- a/docs/updates.mdx +++ b/docs/updates.mdx @@ -4,6 +4,13 @@ description: Updates and announcements about the Agent Client Protocol rss: true --- + +## Delete in Diff RFD moves to Draft stage + +The RFD for indicating whether a diff resulted in a file deletion has been moved to Draft stage. Please review the [RFD](./rfds/diff-delete) for more information on the current proposal and provide feedback as work on the implementation begins. + + + ## Sergey Ignatov is now a Lead Maintainer