Expose session and tree browsing/editing to RPC protocol

[dnouri]

Reopening #1628 (auto-closed by bot).

---

Motivation

The RPC protocol already covers prompting, streaming, model/thinking configuration, compaction, forking, session switching, and message retrieval. What's missing is session discovery and tree-structured navigation, the operations the TUI's session selector and tree selector provide interactively.

This PR adds five new RPC commands that close that gap, plus a shared tool-call formatting module extracted from the TUI.

What this adds

RPC commands

Five new commands with typed client helpers, transport types, and docs:

• list_sessions: scope "current" or "all". Each session item always includes allMessagesText for client-side search.
• get_tree: lightweight projection of the session tree for browsing UIs. Bookkeeping entries (labels, session_info, custom) are filtered out and their children re-parented. See rpc.md > Tree Node Types for node variants.
• navigate_tree: delegates to AgentSession.navigateTree with normalized options. Supports optional branch summarization and labeling.
• set_label: set or clear a label on a tree entry. Whitespace-only strings clear the label, matching navigate_tree behavior.
• abort_branch_summary: cancels in-progress branch summarization. The existing abort command only aborts the agent loop, not the separate summarization AbortController.

Command shapes live in rpc-types.ts and are exported via modes/index.ts for SDK consumers.

Shared formatToolCall

Tool-call preview formatting was extracted from the TUI's tree-selector.ts into core/format-tool-call.ts and is now shared by both the TUI and RPC tree projection. Previews went from generic JSON truncation to human-readable bracket expressions:

[read: ~/projects/file.ts:10-29]
[bash: git status && git diff]
[grep: /TODO/ in src/]

Intentionally deferred

Two session management operations that the TUI supports are not included:

• rename_session: The TUI renames any session by temporarily opening the target file and writing a session_info entry. The existing set_session_name RPC command only works on the current session.
• delete_session: The TUI deletes sessions via the trash CLI with a fallback to unlink. No RPC equivalent exists.

Both are scoped out to keep this PR focused on read and navigate operations. They're straightforward to add as a follow-up.

Design decisions

Internal toolResult session entries carry only a toolCallId, not the tool name or arguments: those live on the originating assistant message. The projector resolves each tool_result against tool calls seen along its branch path, populating toolName, toolArgs, and formattedToolCall on the projected node. Branch-scoped resolution prevents cross-contamination when the same toolCallId appears in different branches.

Iterative traversal: Tree projection and leaf resolution use explicit stacks instead of recursion. Deep trees (long sessions with many branches) can exceed call-stack limits under recursion.

Architecture

Command handlers are inlined in rpc-mode.ts case bodies, matching the pattern of existing RPC commands. Two helper modules provide reusable logic:

• rpc-tree-projection.ts: projects the raw SessionTreeNode tree into transport-safe RpcTreeNode arrays, resolves tool-call metadata, and finds the projected leaf.
• rpc-command-wiring.ts: transport mapping (toRpcSessionListItem, toRpcNavigateTreeResult) and label normalization.

syncLocation() is added to SessionManager, called after setSessionFile() during session switches. The new list_sessions(scope="current") command reads cwd and sessionDir to scope results; without this, switching sessions via RPC would leave those fields pointing at the previous project.

Error handling: navigate_tree and set_label catch thrown errors (invalid entry IDs) and return typed RPC errors. The remaining new commands cannot fail under normal operation and propagate exceptions to the top-level handler.

[dnouri]

Here's a bit of a teaser video to show how this works out in the Emacs client:

rpc-browsing-surface.mp4

[badlogic]

Setting this to draft because it has a couple of issues.

I can't figure out why you split setSessionFile() into setSessionFile() and syncLocation(). That breaks the SessionManager invariant. After setSessionFile(), the manager can be in a split state where the loaded session file, entries, and session id belong to one session, but cwd and sessionDir still belong to another.

I'm afraid that won't fly. Can you explain why that split was needed?

[dnouri]

You're right, sorry for the confusion. I got confused by main's behaviour where switchSession does not update process.cwd() nor sessionManager.getCwd() when you switch across projects. This behaviour seems unintentional. If I resume a session from another project, I might expect tool calls in the new session to happen relative to its project folder, but as is they're still going to execute in the cwd of the session that I switched from. To that extent, I don't think the invariant that you describe is enforced on main.

The way this surfaced for me was that list_sessions with scope: "current" after a cross-project switch was listing sessions from the original project instead of the switched-to project. I added syncLocation() to fix that, but that only patched sessionManager.getCwd() and getSessionDir(). It doesn't touch agentSession._cwd, the tools (which capture cwd at creation time), or process.cwd(). So after the fix, session listing follows the switch but tool execution doesn't, which is arguably worse than main's behavior where at least everything consistently stays in the original directory.

Maybe the right thing to do is to change cross-project session switching such that it updates cwd everywhere and re-creates tools? For now I'll remove syncLocation() from this branch to avoid the half-consistent state.

[badlogic]

i'm currently refactoring all the things, and that will include rpc mode, which will likely sit on top of the new server mode. as such, rpc should have full feature parity going foward. will take a week or two to finisht. this will cover this PR.