Description

GET /session: Add ORDER BY time_updated DESC to Session.list() for deterministic ordering and correct limit behavior

Problem

The Session.list() function in packages/opencode/src/session/index.ts does not include an ORDER BY clause:

export function* list() {
    const rows = Database.use((db) =>
      db
        .select()
        .from(SessionTable)
        .where(eq(SessionTable.project_id, project.id))
        .all(),  // No ORDER BY
    )
    // ...
}

This causes two issues:

1. Undefined ordering — The GET /session endpoint returns sessions in SQLite's internal storage order, which is not guaranteed to be stable or meaningful.

2. limit truncates arbitrarily — When limit is used, clients receive an arbitrary subset of sessions rather than the most recently active ones. This makes the limit parameter unreliable for any practical use case (pagination, initial load, etc.).

Expected Behavior

Sessions should be returned in time_updated DESC order (most recently active first). This is consistent with:

• How the TUI already handles this (client-side .toSorted((a, b) => b.time.updated - a.time.updated))
• Standard UX expectations (chat apps, IDEs, etc.)
• Making limit useful — "give me the N most recent sessions"

Suggested Fix

Add ORDER BY at the database level in Session.list():

import { desc } from "../storage/db"

export function* list() {
    const project = Instance.project
    const rows = Database.use((db) =>
      db
        .select()
        .from(SessionTable)
        .where(eq(SessionTable.project_id, project.id))
        .orderBy(desc(SessionTable.time_updated))  // ← Add this
        .all(),
    )
    for (const row of rows) {
      yield fromRow(row)
    }
}

Bonus: offset support

For clients that need pagination (e.g., GUI apps showing session lists), adding an offset query parameter to GET /session would be very helpful:

// In route handler, after sorting at DB level:
if (query.offset !== undefined) {
    sessions = sessions.slice(query.offset)
}

Context

I'm building a GUI client for OpenCode. Currently I have to fetch all sessions and sort client-side because:

1. The API order is undefined
2. limit without ordering gives arbitrary results
3. There's no offset for pagination

Server-side ORDER BY + offset would significantly reduce client complexity and data transfer.

Plugins

No response

OpenCode version

1.1.55

Steps to reproduce

No response

Screenshot and/or share link

No response

Operating System

macos 26

Terminal

Ghostty