support session listing and loading

[travisjeffery]

Summary

This PR improves ACP session startup behavior and session selection UX.

It adds strategy-based session loading (latest, prompt, new), supports loading existing sessions when the agent advertises session/list + session/load (codex-acp for example), and has ** Start a new session ** as default.

What Changed

• Added new user option:
  • agent-shell-session-load-strategy (latest default, prompt, new).
• Persisted session capability detection during handshake:
  • tracks support for session/list.
  • tracks support for session/load.
• Updated session initialization flow:
  • if capabilities are present and strategy is not new, attempt session/list then session/load.
  • fallback to session/new on list/load errors or when no session is selected.
• Added session picker helpers:
  • human-readable session labels (title | updatedAt | sessionId).
  • prompt-based session selection.
  • dedicated sorter that pins ** Start a new session ** to the first position in completion display/cycle ordering.
• Refactored session setup internals to reduce duplication:
  • extracted helper for state hydration from response.
  • extracted helper for session-init finalization UI updates.

Tests

Added/updated ERT coverage for:

• list+load preferred path when supported.
• fallback to session/new when session/list fails.
• new strategy bypassing list/load.
• prompt session selection behavior.
• picker sort behavior keeping ** Start a new session ** first.

Targeted test run for these flows passes.

Docs / Follow-up Included in Branch

This branch also includes small documentation updates:

• checkdoc/docstring cleanup in agent-shell.el.
• README variable table entry for agent-shell-session-load-strategy.

Checklist

• I've read the README's Contributing section.
• I've filed a feature request/discussion for a new feature.
• My code follows the project style.
• I've added tests where applicable.
• I've updated documentation where necessary.
• I've run M-x checkdoc and M-x byte-compile-file.
• I've reviewed all code in PR myself and will vouch for its quality.

[xenodium]

Sorry for the delay. We have an existing PR for session loading in #248 (cc @farra). I need to spend some time comparing the two approaches to figure out how to move forward. Relatedly, I'm considering a non-comint buffer alternative which may simplify handshake for us (and possibly loading sessions).

I need to play with both implementations quite a bit. It's gonna take me a little while, sorry.

[xenodium]

@travisjeffery @farra looks like we'll be able to merge bits from both PRs and we get both loading (for Codex) and resume (for Claude Code). I'll share a branch soon so you both can try it out.

[xenodium]

@travisjeffery I noticed you implemented session deletion b1e94fe. I've not been able to try it out. Doesn't seem to be available in neither codex nor claude code? I've updated agents and acp counterparts.

Here's what my codex-acp reports:

▼ Agent capabilities

load session
prompt image, audio and embedded context
mcp http and sse
session list

Could you share details on your setup please?

[xenodium]

We have a misplaced paren at the end of this line.

[xenodium]

I'll share a branch soon so you both can try it out.

Here's the branch: https://github.com/xenodium/agent-shell/tree/pr263-resume-session It's got changes from #263 rebased onto main.

To try this branch out, you'll need the latest acp.el, including this commit xenodium/acp.el@e5dec95

With the main rebase, we no longer need to defer initialization until after sending a prompt. This improves the loading session flow on shell startup.

To try things out, you'll need these settings:

(setq agent-shell-deferred-initialization nil)
(setq agent-shell-session-load-strategy 'prompt)

You can then use C-u M-x agent-shell to create a new shell. Upon launch, it should prompt you for a session to resume (or create a new one).

[xenodium]

ps. I've yet to try deletion out as per #263 (comment), so I can't confirm this flow just yet.

[travisjeffery]

@travisjeffery I noticed you implemented session deletion b1e94fe. I've not been able to try it out. Doesn't seem to be available in neither codex nor claude code? I've updated agents and acp counterparts.

Here's what my codex-acp reports:

▼ Agent capabilities

load session prompt image, audio and embedded context mcp http and sse session list

Could you share details on your setup please?

Yeah it's still early and not well supported it seems like: https://agentclientprotocol.com/rfds/session-delete -- I put it in now so that I could clear out sessions from showing in the list. Later it'd be nice if whatever ACP you were running supported the call.

[travisjeffery]

I'll share a branch soon so you both can try it out.

Here's the branch: https://github.com/xenodium/agent-shell/tree/pr263-resume-session It's got changes from #263 rebased onto main.

To try this branch out, you'll need the latest acp.el, including this commit xenodium/acp.el@e5dec95

With the main rebase, we no longer need to defer initialization until after sending a prompt. This improves the loading session flow on shell startup.

To try things out, you'll need these settings:

(setq agent-shell-deferred-initialization nil)
(setq agent-shell-session-load-strategy 'prompt)

You can then use C-u M-x agent-shell to create a new shell. Upon launch, it should prompt you for a session to resume (or create a new one).

I'm trying the branch, it maintains same flow I had. The deferred init is nice. 👍

The other feature I wanted to look into was making Codex' collab mode available.

[xenodium]

I'm trying the branch, it maintains same flow I had. The deferred init is nice. 👍

Yep. The two flows work well together. Are you happy for me to continue cleaning up the branch and move forward from there to get things merged? I'll squash the branch commits and credit both you and @farra, if that's ok.

The other feature I wanted to look into was making Codex' collab mode available.

Separate PR please. Also could you file a feature request and describe the feature a bit before making the PR?

Yeah it's still early and not well supported it seems like: https://agentclientprotocol.com/rfds/session-delete -- I put it in now so that I could clear out sessions from showing in the list. Later it'd be nice if whatever ACP you were running supported the call.

Makes sense. I'll remove deletion from the branch for the time being. When we are able to validate the feature, we can apply the changes again.

[travisjeffery]

I'm trying the branch, it maintains same flow I had. The deferred init is nice. 👍

Yep. The two flows work well together. Are you happy for me to continue cleaning up the branch and move forward from there to get things merged? I'll squash the branch commits and credit both you and @farra, if that's ok.

The other feature I wanted to look into was making Codex' collab mode available.

Separate PR please. Also could you file a feature request and describe the feature a bit before making the PR?

Yeah it's still early and not well supported it seems like: https://agentclientprotocol.com/rfds/session-delete -- I put it in now so that I could clear out sessions from showing in the list. Later it'd be nice if whatever ACP you were running supported the call.

Makes sense. I'll remove deletion from the branch for the time being. When we are able to validate the feature, we can apply the changes again.

Yep sounds good to me.

[xenodium]

To try things out, you'll need these settings:

(setq agent-shell-deferred-initialization nil)
(setq agent-shell-session-load-strategy 'prompt)

You can then use C-u M-x agent-shell

@travisjeffery @farra give the latest in branch a try. Been working on polishing this part of the flow.