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": [] }, diff --git a/docs/rfds/session-resume.mdx b/docs/rfds/session-resume.mdx new file mode 100644 index 0000000..f3c07d2 --- /dev/null +++ b/docs/rfds/session-resume.mdx @@ -0,0 +1,85 @@ +--- +title: "Resuming of existing sessions" +--- + +- Author(s): [@josevalim](https://github.com/josevalim) +- Champion: [@benbrandt](https://github.com/benbrandt) + +## 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, not all coding agents implement it. +This means that, once you close your editor, browser, etc, you can't resume the conversation. + +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? + +Add a "session/resume" command and a capability `{ session: { resume: {} }`. + +## 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. + +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? + +## 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? + +The biggest question is if it makes sense to support both "session/load" and +"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 +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 + +- 2025-11-24: Update FAQ to mention session/resume vs session/load 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