From 8c3b5f952bcb532499156da6330e5e4ddc06ebe2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 10 Nov 2025 17:39:30 +0100 Subject: [PATCH 1/6] RFD: resume existing sessions This document proposes the addition of a 'session/resume' command to allow users to resume existing sessions without returning previous messages, addressing the limitations of the current 'session/load' command. --- docs/rfds/resume-session.mdx | 100 +++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/rfds/resume-session.mdx diff --git a/docs/rfds/resume-session.mdx b/docs/rfds/resume-session.mdx new file mode 100644 index 0000000..7c024bc --- /dev/null +++ b/docs/rfds/resume-session.mdx @@ -0,0 +1,100 @@ +--- +title: "Resuming of existing sessions" +--- + +Author(s): [@josevalim](https://github.com/josevalim) + +## Elevator pitch + +> What are you proposing to change? + +We propose adding the ability to resume existing sessions. This is similar to session/load, +except it does not return previous messages. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +While the spec provides a "session/load" command, most coding agents do not implement it. +This means that, once you close your editor, browser, etc, you can't resume the conversation. + +An obvious answer to this question would be to implement "session/load" for existing coding +agents. For example, `claude-code-acp` could intercept all messages, write them to disk, +and emulate "session/load". We considered contributing this when we realized that, we already +store all messages in our own application, independent from ACP, given we want to provide +users to navigate or share old chats even if the coding agent is removed. And if we were to use +"session/load", we would likely just discard them anyway. + +In those cases, the ability to resume a session is beneficial because: + +* it is exactly what we need +* it is more straight-forward to implement for both clients and servers + +## What we propose to do about it + +> What are you proposing to improve the situation? + +Two possible options: + +* Add a "session/resume" command +* Add an option to "session/load" which allows us to continue even if + it doesn't return the previous conversation + +In the rest of the document, I will refer to the solution as "session/resume", +but it implies any of the solutions above. + +## Shiny future + +> How will things will play out once this feature exists? + +We will be able to resume existing conversations, providing a better user experience. + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + + + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + + + +### What alternative approaches did you consider, and why did you settle on this one? + +The biggest question is if it makes sense to support both "session/load" and +"session/resume". However, I do wonder: how portable "session/load" is in practice? + +When we start a new session over ACP, we introduce custom MCP tools and configuration. +This means that, while we could use "session/load" to load our own chats and chats +not started by us, I presume loading third-party chats would lead to a flawed user +experience, as our tools would not be available. And depending on the ACP implementation, +not even the capabilities would be respected. + +Therefore, I see functionality such as "session/load" and "session/list" being +useful for those who want to provide a different interface for coding agents, without +injecting custom functionality. Outside of that, the other benefit of "session/load" +is that we could rely on the coding agent's own storage, but unfortunately that does +not seem to be exposed at the moment. So if we have to emulate "session/load" at the +ACP layer, we may know have chats stored in the coding agent, in ACP, and in our +applications. + +If we can trivially implement "session/load" across agents, then I don't believe this +RFD has weight. But assuming we don't, we may need to deal with these trade-offs: + +* If "session/resume" exists, coding agents may avoid implementing "session/load", + hurting those who want a "session/list" and "session/load" style functionality + +* If "session/resume" does not exist, coding agents may still not implement "session/load" + anyway, and clients will be unable to resume conversations (this is where we are) + +## Revision history + + From 3f74e289d7e91da2dc79b775e6912520c26fb9ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 17 Nov 2025 07:24:02 -0800 Subject: [PATCH 2/6] Revise proposal for session resumption functionality Clarified the proposal for resuming sessions and its advantages and compatibility in relation to 'session/load'. --- docs/rfds/resume-session.mdx | 54 ++++++++++++++---------------------- 1 file changed, 21 insertions(+), 33 deletions(-) diff --git a/docs/rfds/resume-session.mdx b/docs/rfds/resume-session.mdx index 7c024bc..9502325 100644 --- a/docs/rfds/resume-session.mdx +++ b/docs/rfds/resume-session.mdx @@ -8,7 +8,7 @@ Author(s): [@josevalim](https://github.com/josevalim) > What are you proposing to change? -We propose adding the ability to resume existing sessions. This is similar to session/load, +We propose adding the ability to resume existing sessions. This is similar to "session/load", except it does not return previous messages. ## Status quo @@ -18,17 +18,9 @@ except it does not return previous messages. While the spec provides a "session/load" command, most coding agents do not implement it. This means that, once you close your editor, browser, etc, you can't resume the conversation. -An obvious answer to this question would be to implement "session/load" for existing coding -agents. For example, `claude-code-acp` could intercept all messages, write them to disk, -and emulate "session/load". We considered contributing this when we realized that, we already -store all messages in our own application, independent from ACP, given we want to provide -users to navigate or share old chats even if the coding agent is removed. And if we were to use -"session/load", we would likely just discard them anyway. - -In those cases, the ability to resume a session is beneficial because: - -* it is exactly what we need -* it is more straight-forward to implement for both clients and servers +Given resuming an existing conversation is already a capability in some agents and genereally +easier to implement in practice, we hope it will be better adopted. Not only that, resuming +could be used as a mechanism for proxies and adapter libraries to emulate "session/load". ## What we propose to do about it @@ -49,6 +41,12 @@ but it implies any of the solutions above. We will be able to resume existing conversations, providing a better user experience. +Not only that, if an agent does not implement "session/load" but it does implement +"session/resume", it is now possible to implement a proxy/adapter that intercepts +the agents messages and writes them to disk. Now when the client issues a +"session/load", the proxy/adapter converts it to a "session/resume", and then returns +the stored messages. + ## Implementation details and plan > Tell me more about your implementation. What is your detailed implementation plan? @@ -73,27 +71,17 @@ The biggest question is if it makes sense to support both "session/load" and "session/resume". However, I do wonder: how portable "session/load" is in practice? When we start a new session over ACP, we introduce custom MCP tools and configuration. -This means that, while we could use "session/load" to load our own chats and chats -not started by us, I presume loading third-party chats would lead to a flawed user -experience, as our tools would not be available. And depending on the ACP implementation, -not even the capabilities would be respected. - -Therefore, I see functionality such as "session/load" and "session/list" being -useful for those who want to provide a different interface for coding agents, without -injecting custom functionality. Outside of that, the other benefit of "session/load" -is that we could rely on the coding agent's own storage, but unfortunately that does -not seem to be exposed at the moment. So if we have to emulate "session/load" at the -ACP layer, we may know have chats stored in the coding agent, in ACP, and in our -applications. - -If we can trivially implement "session/load" across agents, then I don't believe this -RFD has weight. But assuming we don't, we may need to deal with these trade-offs: - -* If "session/resume" exists, coding agents may avoid implementing "session/load", - hurting those who want a "session/list" and "session/load" style functionality - -* If "session/resume" does not exist, coding agents may still not implement "session/load" - anyway, and clients will be unable to resume conversations (this is where we are) +This means that, while we could use "session/load" to load our own chats, loading +third-party chats would likely lead to a flawed user experience, as our tools would +not be available. And depending on the ACP implementation, not even the capabilities +would be respected (as loading a third-party session would not include our capabilities +in its history, misleading the agent). + +Therefore, if we assume "session/load" is for loading conversations started by the client +itself, "session/resume" is effectively a subset of "session/load", decoupled from storage +mechanics. If an agent implements "session/load", then it can be used directly, but if it +doesn't, a proxy or adapter can provide a reasonable fallback on top of "session/resume". +This argues "session/resume" is the basic primitive which "session/load" builds on top of. ## Revision history From f97efcf9a76bbf00adf6d4978ab792a4c6e97e7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 24 Nov 2025 19:01:07 +0100 Subject: [PATCH 3/6] Add session/load vs session/resume to FAQ --- docs/rfds/resume-session.mdx | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/rfds/resume-session.mdx b/docs/rfds/resume-session.mdx index 9502325..1a9c1b7 100644 --- a/docs/rfds/resume-session.mdx +++ b/docs/rfds/resume-session.mdx @@ -15,25 +15,19 @@ except it does not return previous messages. > How do things work today and what problems does this cause? Why would we change things? -While the spec provides a "session/load" command, most coding agents do not implement it. +While the spec provides a "session/load" command, not all coding agents implement it. This means that, once you close your editor, browser, etc, you can't resume the conversation. -Given resuming an existing conversation is already a capability in some agents and genereally -easier to implement in practice, we hope it will be better adopted. Not only that, resuming +This is particularly a problem for agents that do not directly implement ACP and the +functionality is implemented via a wrapper. In such cases, they may provide the ability +to resume (without history), which we would like to hook into. Not only that, resuming could be used as a mechanism for proxies and adapter libraries to emulate "session/load". ## What we propose to do about it > What are you proposing to improve the situation? -Two possible options: - -* Add a "session/resume" command -* Add an option to "session/load" which allows us to continue even if - it doesn't return the previous conversation - -In the rest of the document, I will refer to the solution as "session/resume", -but it implies any of the solutions above. +Add a "session/resume" command and a capability `resumeSession: true`. ## Shiny future @@ -68,7 +62,7 @@ the stored messages. ### What alternative approaches did you consider, and why did you settle on this one? The biggest question is if it makes sense to support both "session/load" and -"session/resume". However, I do wonder: how portable "session/load" is in practice? +"session/resume". When we start a new session over ACP, we introduce custom MCP tools and configuration. This means that, while we could use "session/load" to load our own chats, loading @@ -83,6 +77,18 @@ mechanics. If an agent implements "session/load", then it can be used directly, doesn't, a proxy or adapter can provide a reasonable fallback on top of "session/resume". This argues "session/resume" is the basic primitive which "session/load" builds on top of. +### Should we introduce a new operation (session/resume) or add an option to (session/load)? + +A separate method provides a few benefits: + +* for clients that for whatever reason don't want the history, they can just resume + +* for agents that can only supply resume, a proxy on top could provide load on top of it, + but the agent is still clear on what it supports + +* for agents who support both, it should be trivial to use the same resume functionality, + they just either replay events or do not + ## Revision history - +* 2025-11-24: Update FAQ to mention session/resume vs session/load From baaa1e1b5f9de591aa504c0783ab3eaa28cbe83d Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 26 Nov 2025 12:06:54 +0100 Subject: [PATCH 4/6] update capabilities and formatting --- ...{resume-session.mdx => session-resume.mdx} | 41 ++++++++----------- 1 file changed, 16 insertions(+), 25 deletions(-) rename docs/rfds/{resume-session.mdx => session-resume.mdx} (76%) diff --git a/docs/rfds/resume-session.mdx b/docs/rfds/session-resume.mdx similarity index 76% rename from docs/rfds/resume-session.mdx rename to docs/rfds/session-resume.mdx index 1a9c1b7..f3c07d2 100644 --- a/docs/rfds/resume-session.mdx +++ b/docs/rfds/session-resume.mdx @@ -2,7 +2,8 @@ title: "Resuming of existing sessions" --- -Author(s): [@josevalim](https://github.com/josevalim) +- Author(s): [@josevalim](https://github.com/josevalim) +- Champion: [@benbrandt](https://github.com/benbrandt) ## Elevator pitch @@ -21,13 +22,13 @@ This means that, once you close your editor, browser, etc, you can't resume the This is particularly a problem for agents that do not directly implement ACP and the functionality is implemented via a wrapper. In such cases, they may provide the ability to resume (without history), which we would like to hook into. Not only that, resuming -could be used as a mechanism for proxies and adapter libraries to emulate "session/load". +could be used as a mechanism for proxies and adapter libraries to emulate "session/load". ## What we propose to do about it > What are you proposing to improve the situation? -Add a "session/resume" command and a capability `resumeSession: true`. +Add a "session/resume" command and a capability `{ session: { resume: {} }`. ## Shiny future @@ -45,19 +46,21 @@ the stored messages. > Tell me more about your implementation. What is your detailed implementation plan? - - ## Frequently asked questions > What questions have arisen over the course of authoring this document or during subsequent discussions? - +### Should we introduce a new operation (session/resume) or add an option to (session/load)? + +A separate method provides a few benefits: + +- for clients that for whatever reason don't want the history, they can just resume + +- for agents that can only supply resume, a proxy on top could provide load on top of it, + but the agent is still clear on what it supports + +- for agents who support both, it should be trivial to use the same resume functionality, + they just either replay events or do not ### What alternative approaches did you consider, and why did you settle on this one? @@ -77,18 +80,6 @@ mechanics. If an agent implements "session/load", then it can be used directly, doesn't, a proxy or adapter can provide a reasonable fallback on top of "session/resume". This argues "session/resume" is the basic primitive which "session/load" builds on top of. -### Should we introduce a new operation (session/resume) or add an option to (session/load)? - -A separate method provides a few benefits: - -* for clients that for whatever reason don't want the history, they can just resume - -* for agents that can only supply resume, a proxy on top could provide load on top of it, - but the agent is still clear on what it supports - -* for agents who support both, it should be trivial to use the same resume functionality, - they just either replay events or do not - ## Revision history -* 2025-11-24: Update FAQ to mention session/resume vs session/load +- 2025-11-24: Update FAQ to mention session/resume vs session/load From 162c1dabd9085952e60e324111c1ee22be18b924 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 26 Nov 2025 12:08:36 +0100 Subject: [PATCH 5/6] Add to website --- docs/docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index edc26a4..f9662c9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -95,7 +95,8 @@ "rfds/session-list", "rfds/session-config-options", "rfds/session-fork", - "rfds/request-cancellation" + "rfds/request-cancellation", + "rfds/session-resume" ] }, { "group": "Preview", "pages": [] }, From c6026701646875477f546d8813367c81afd0b189 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 26 Nov 2025 12:09:40 +0100 Subject: [PATCH 6/6] Add update --- docs/updates.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/updates.mdx b/docs/updates.mdx index 13e0388..ba0ce87 100644 --- a/docs/updates.mdx +++ b/docs/updates.mdx @@ -4,6 +4,13 @@ description: Updates and announcements about the Agent Client Protocol rss: true --- + +## session/resume RFD moves to Draft stage + +The RFD for adding a "session/resume" method to the protocol has been moved to Draft stage. Please review the [RFD](./rfds/session-resume) for more information on the current proposal and provide feedback as work on the implementation begins. + + + ## $/cancelRequest RFD moves to Draft stage