Skip to content

add separate resumeToken for session/resume #279

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

add separate resumeToken for session/resume #279

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/rfds/session-resume.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,48 @@ the stored messages.

> Tell me more about your implementation. What is your detailed implementation plan?

We propose to add a new "session/resume" method. Agents must declare this option is
available by including `sessionCapabilities: { resume : {} }` in its capabilities.
Copy link
Author

@SteffenDE SteffenDE Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I already used the new sessionCapabilities proposed by session/list. Happy to change that to a top level key.

The object is reserved to declare future capabilities.

To make implementation in existing and future agents easier, we propose to have a separate
token for resuming, which the agent can use to map to an internal session:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "session/resume",
"params": {
"resumeToken": "opaque-token"
}
}
```

And the agent would respond with optional data such as config options, the same as `session/load`.

When implementing `session/resume`, the agent sends a `session/update` notification with the token:

```json
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_123",
"update": {
"sessionUpdate": "resumeToken",
"resumeToken": "opaque-token"
},
}
}
```

Agents may update the `resumptionToken` at any time if necessary. Clients should use the latest
token received to continue the chat from where they left off.

Agents may only support resuming chats in some cases. Therefore, an agent may not send a `resumeToken`,
even if it declares the capability.
Copy link
Member

@benbrandt benbrandt Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The nice thing about using a token is that it would allow for us to have multiple resume points in the conversation i.e. for forking

But I guess this is somewhat different in that resume kind of always assumes resuming from whatever point the agent decides correct? Like the last message?

So, I guess in general i like the idea.. but I also feel like we are applying a band-aid at the protocol level for lack of support from the Claude Code SDK...

Because I guess what isn't clear to me is you would get this session/update shortly after starting the conversation and then it is somewhat unclear where you are actually resuming from...
And should this resume token be somehow returned by the session/list endpoint, if supported?

Copy link
Author

@SteffenDE SteffenDE Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I guess this is somewhat different in that resume kind of always assumes resuming from whatever point the agent decides correct? Like the last message?

Yes. I'd also say the main difference between resume and fork (with message id) is that fork assumes an already running session, while resume does not.

but I also feel like we are applying a band-aid at the protocol level for lack of support from the Claude Code SDK...

It would be nice if we don't need it, yes. The token approach feels very flexible though and as long as we document that resuming should always resume from the most recent interaction, I think we're good. "Resuming" from a different point in time is something I'd only consider for fork.

The "getting it shortly after starting the conversation" is somewhat similar to agent modes though, since those also don't change most of the time.

And should this resume token be somehow returned by the session/list endpoint, if supported?

I'd say so, yes!

Copy link
Member

@benbrandt benbrandt Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the resume token is just an indication that this session is now resumable?
vs just being able to call resume on a session?

Copy link
Member

@benbrandt benbrandt Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like i guess, if it is always from the most recent interaction, why wouldn't I just ask to resume a given session?


## Frequently asked questions

> What questions have arisen over the course of authoring this document or during subsequent discussions?
Expand Down