feat(core): add session_list and session_read tools - #58445

Issue for this PR

No issue.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Adds two read-only tools to the opencode Code Mode namespace so the model can find and reread earlier conversations, including the parts compaction summarized away. Compaction never deletes rows from session_message, so the full history is still there to read.

session_list({ search?, limit?, cursor? }) lists sessions across projects, most recently updated first, with each session's message count. With search, it matches session titles and the text of user and assistant messages (every word, case-insensitive; tool output and reasoning are not searched). Each matching message comes back with its index and a snippet, up to 3 per session.

{
  "sessions": [
    {
      "sessionID": "ses_…",
      "title": "Compaction rework",
      "directory": "/Users/me/project",
      "updated": "2026-10-21T14:37:36.000Z",
      "messages": 2287,
      "matches": [
        { "index": 141, "snippet": "We dropped chains of accepts because the mapping breaks when…" },
        { "index": 139, "snippet": "why not chains of accepts?" }
      ]
    }
  ]
}

session_read({ sessionID, offset?, limit?, tools? }) reads a page of messages by index, counting from 0, and returns the session's total. Without offset it reads the latest messages. A match's index can be passed as offset, or a little lower to include the surrounding discussion. tools: true adds tool calls and their output.

{
  "total": 2287,
  "messages": [
    { "index": 139, "role": "user", "text": "why not chains of accepts?" },
    { "index": 141, "role": "assistant", "text": "We dropped chains of accepts because the mapping breaks when…" }
  ]
}

Details:

• Indexes are computed when reading (order by seq with offset) rather than taken from seq, which is the event sequence and is sparse. Reverts only delete the tail and forks copy the prefix, so indexes stay stable. Hidden messages such as agent switches still use an index, which the tool description mentions.
• Message text is capped at 10,000 characters with a note of how much was cut. Tool input and output reuse the existing 1,250-character cap.
• SessionStore gains page, counts, and search; Session exposes them, with page checking that the session exists.

How did you verify your code works?

• Added a test in packages/core/test/tool-opencode.test.ts that seeds a session with sparse seq values and a compaction, then checks title and message search, that tool output isn't matched, reading from a match across the compaction, reading the latest page, tools: true, and an offset past the end.
• bun run typecheck:tsc passes across the repo, and the core session and tool tests pass.
• Timed the queries on a copy of a real database (about 20K messages, largest session 2,287 messages): reading a page or counting messages takes under 1 ms, and a search across all sessions takes about 0.4 s.

Screenshots / recordings

Not a UI change.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Public API: adds the session_list and session_read tools to the opencode Code Mode namespace (backwards compatible)