Session history

[remorses]

Add session history endpoints to ACP, enabling clients to access conversations from any ACP agent (Claude Code, Gemini CLI, etc).

Problem

Users work with AI agents across multiple tools, creating isolated conversation histories. Current ACP only handles active sessions, not historical data.

Proposed API

1. List Sessions

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/list",
  "params": {
    "limit": 20,
    "offset": 0,
    "search": "debugging"
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessions": [{
      "sessionId": "sess_abc123",
      "title": "Fix Redis timeout",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastModified": "2024-01-15T11:45:00Z",
      "source": "claude-code-cli",
      "messageCount": 12
    }],
    "total": 145
  }
}

2. Get Session Content

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/get",
  "params": {
    "sessionId": "sess_abc123"
  }
}

// Response - Uses existing ACP content format
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessionId": "sess_abc123",
    "title": "Fix Redis timeout",
    "createdAt": "2024-01-15T10:30:00Z",
    "turns": [
      {
        "role": "user",
        "timestamp": "2024-01-15T10:30:00Z",
        "content": [{
          "type": "text",
          "text": "Redis keeps timing out"
        }]
      },
      {
        "role": "assistant", 
        "timestamp": "2024-01-15T10:30:15Z",
        "content": [{
          "type": "text",
          "text": "I'll check your Redis config"
        }],
        "toolCalls": [{
          "toolCallId": "call_001",
          "title": "Read redis.conf",
          "status": "completed"
        }]
      }
    ]
  }
}

3. Capability Discovery

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionHistory": {
        "supported": true,
        "maxResults": 1000
      }
    }
  }
}

Benefits

• Unified history across all AI tools
• Context reuse for similar problems
• Backwards compatible - optional feature
• Simple implementation - reuses existing content types

Implementation

Agents store sessions locally (SQLite, JSON files) and expose via new endpoints. No changes to existing ACP flows.

[agu-z]

It isn't implemented in clients yet, but we already have session/load (docs), which uses the existing notifications to stream the conversation as if they were the result of session/prompt. This makes it much easier to implement, as the Client can collect the content in the same way they already do, and we don't need to send all content at once in a single message.

Adding something like session/list would make a lot of sense because it means the Client doesn't have to keep track of past sessions and can discover ones from other clients. So I'm in favor, but there are a few other features we want to stabilize first.

[remorses]

Something to keep in mind when implementing this: currently Claude code chat history is different for every working directory, there should be a way to pass the current working directory to show all chats created inside that folder and its children. Passing / would show all chats ever created, which is useful for clients that need to see the full chat history

[ahmedhesham6]

How can we prioritize session/list and where can I contribute?

I'd love to help move session/list forward. We currently have session/new and session/load, but no way to discover what sessions exist—leaving history fragmented across clients.

[benbrandt]

@ahmedhesham6 creating an RFD like you did is the perfect next step! I'll move the conversation over there, thanks for kicking this off!

[codefromthecrypt]

I wasn't quite sure where to place this thought, but as the session/list proposal has a title, I was thinking if it should be made explicit somewhere the rationale of who owns that title. If I were to guess, it is the agent who is owning it at the moment.

Not knowing exactly where to go with this I made a comment on a change by @alexhancock on Goose, which is starting to integrate the session ID (which I like for many reasons including telemetry coherence). The session title/name is still opaque in ACP IIUC.

Let's use Zed as a case study. IIUC Zed uses its llm logic to title the session exclusively if ACP is not in use. In ACP, this set_title function is stubbed out. So, basically when ACP is in use Zed is not in control of the session title.

If we think the Agent should own making the title, should the inputs also be owned by the agent (opaque to ACP)? For example, not all editors use LLMs to make a title right now, and there are impacts (e.g. junk titles, latency, tokens, etc).

Meanwhile, there's a strong argument to have the editor own the title, as then there would be coherence for sure in the naming of things. Editors could own the session title even if they don't control generation parameters. For example, a set_title feature would allow the editor to decide when and if to rename the session to something more useful. This allows it to control threading more directly for example.

I ack this is more than the basics of session/list, but I think the session title is a key concern of the session/list and wondered if this nuance should be left as field docs? Or should the session title itself be a top-level spec? lemme know.