api: add after cursor for forward pagination on /session/:id/message

The v1 messages endpoint previously only supported backward
pagination via the `before` cursor. Adding an `after` cursor enables
the TUI to recover messages that have been evicted from the in-memory
window when the user scrolls back toward the live tail.

- MessageV2.page accepts an optional `after` cursor (mutually
  exclusive with `before`); when set, it returns the next page in
  ascending chronological order using a `newer()` predicate.
- Handler validates that only one of `before`/`after` is supplied,
  decodes the cursor, and emits the `Link` / `X-Next-Cursor` headers
  with the correct direction parameter.
- MessagesQuery schema gains an optional `after` field.
- Tests cover forward pagination across multiple pages and the
  before+after-together rejection path.

Author: vpetrigo

packages/opencode/src/server/routes/instance/httpapi/groups/session.ts

@@ -41,6 +41,7 @@ export const MessagesQuery = Schema.Struct({
   ...WorkspaceRoutingQueryFields,
   limit: Schema.optional(Schema.NumberFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0))),
   before: Schema.optional(Schema.String),
+  after: Schema.optional(Schema.String),
 })
 export const StatusMap = Schema.Record(Schema.String, SessionStatus.Info)
 export const UpdatePayload = Schema.Struct({

packages/opencode/src/server/routes/instance/httpapi/handlers/session.ts

@@ -94,14 +94,23 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
       params: { sessionID: SessionID }
       query: typeof MessagesQuery.Type
     }) {
-      if (ctx.query.before && ctx.query.limit === undefined) return yield* new HttpApiError.BadRequest({})
+      if ((ctx.query.before || ctx.query.after) && ctx.query.limit === undefined)
+        return yield* new HttpApiError.BadRequest({})
+      if (ctx.query.before && ctx.query.after) return yield* new HttpApiError.BadRequest({})
       if (ctx.query.before) {
         const before = ctx.query.before
         yield* Effect.try({
           try: () => MessageV2.cursor.decode(before),
           catch: () => new HttpApiError.BadRequest({}),
         })
       }
+      if (ctx.query.after) {
+        const after = ctx.query.after
+        yield* Effect.try({
+          try: () => MessageV2.cursor.decode(after),
+          catch: () => new HttpApiError.BadRequest({}),
+        })
+      }
       yield* SessionError.mapStorageNotFound(session.get(ctx.params.sessionID))
       if (ctx.query.limit === undefined || ctx.query.limit === 0) {
         return yield* session.messages({ sessionID: ctx.params.sessionID })
@@ -111,6 +120,7 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
         sessionID: ctx.params.sessionID,
         limit: ctx.query.limit,
         before: ctx.query.before,
+        after: ctx.query.after,
       })
       if (!page.cursor) return page.items
 
@@ -119,7 +129,8 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session",
       // header echoes the real origin instead of a hard-coded localhost.
       const url = Option.getOrElse(HttpServerRequest.toURL(request), () => new URL(request.url, "http://localhost"))
       url.searchParams.set("limit", ctx.query.limit.toString())
-      url.searchParams.set("before", page.cursor)
+      const direction = ctx.query.after ? "after" : "before"
+      url.searchParams.set(direction, page.cursor)
       return HttpServerResponse.jsonUnsafe(page.items, {
         headers: {
           "Access-Control-Expose-Headers": "Link, X-Next-Cursor",

packages/opencode/src/session/message-v2.ts

@@ -12,6 +12,8 @@ import { desc } from "drizzle-orm"
 import { eq } from "drizzle-orm"
 import { inArray } from "drizzle-orm"
 import { lt } from "drizzle-orm"
+import { gt } from "drizzle-orm"
+import { asc } from "drizzle-orm"
 import { or } from "drizzle-orm"
 import { MessageTable, PartTable, SessionTable } from "./session.sql"
 import * as ProviderError from "@/provider/error"
@@ -595,6 +597,9 @@ const part = (row: typeof PartTable.$inferSelect) =>
 const older = (row: Cursor) =>
   or(lt(MessageTable.time_created, row.time), and(eq(MessageTable.time_created, row.time), lt(MessageTable.id, row.id)))
 
+const newer = (row: Cursor) =>
+  or(gt(MessageTable.time_created, row.time), and(eq(MessageTable.time_created, row.time), gt(MessageTable.id, row.id)))
+
 function hydrate(rows: (typeof MessageTable.$inferSelect)[]) {
   const ids = rows.map((row) => row.id)
   const partByMessage = new Map<string, Part[]>()
@@ -919,17 +924,25 @@ export function toModelMessages(
   return Effect.runPromise(toModelMessagesEffect(input, model, options).pipe(Effect.provide(EffectLogger.layer)))
 }
 
-export function page(input: { sessionID: SessionID; limit: number; before?: string }) {
+export function page(input: { sessionID: SessionID; limit: number; before?: string; after?: string }) {
+  if (input.before && input.after)
+    throw new Error("page: only one of `before` or `after` may be provided")
   const before = input.before ? cursor.decode(input.before) : undefined
+  const after = input.after ? cursor.decode(input.after) : undefined
   const where = before
     ? and(eq(MessageTable.session_id, input.sessionID), older(before))
-    : eq(MessageTable.session_id, input.sessionID)
+    : after
+      ? and(eq(MessageTable.session_id, input.sessionID), newer(after))
+      : eq(MessageTable.session_id, input.sessionID)
   const rows = Database.use((db) =>
     db
       .select()
       .from(MessageTable)
       .where(where)
-      .orderBy(desc(MessageTable.time_created), desc(MessageTable.id))
+      .orderBy(
+        after ? asc(MessageTable.time_created) : desc(MessageTable.time_created),
+        after ? asc(MessageTable.id) : desc(MessageTable.id),
+      )
       .limit(input.limit + 1)
       .all(),
   )
@@ -947,12 +960,12 @@ export function page(input: { sessionID: SessionID; limit: number; before?: stri
   const more = rows.length > input.limit
   const slice = more ? rows.slice(0, input.limit) : rows
   const items = hydrate(slice)
-  items.reverse()
-  const tail = slice.at(-1)
+  if (!after) items.reverse()
+  const cursorRow = slice.at(-1)
   return {
     items,
     more,
-    cursor: more && tail ? cursor.encode({ id: tail.id, time: tail.time_created }) : undefined,
+    cursor: more && cursorRow ? cursor.encode({ id: cursorRow.id, time: cursorRow.time_created }) : undefined,
   }
 }
 

packages/opencode/test/session/messages-pagination.test.ts

@@ -286,6 +286,51 @@ describe("MessageV2.page", () => {
     }),
   )
 
+  test("pages forward with after cursor", async () => {
+    await WithInstance.provide({
+      directory: root,
+      fn: async () => {
+        const session = await svc.create({})
+        const ids = await fill(session.id, 6)
+
+        // Anchor at "before everything": all messages are newer than time 0
+        const anchor = MessageV2.cursor.encode({ id: MessageID.ascending(), time: 0 })
+
+        const a = MessageV2.page({ sessionID: session.id, limit: 2, after: anchor })
+        expect(a.items.map((item) => item.info.id)).toEqual(ids.slice(0, 2))
+        expect(a.more).toBe(true)
+        expect(a.cursor).toBeTruthy()
+
+        const b = MessageV2.page({ sessionID: session.id, limit: 2, after: a.cursor! })
+        expect(b.items.map((item) => item.info.id)).toEqual(ids.slice(2, 4))
+        expect(b.more).toBe(true)
+        expect(b.cursor).toBeTruthy()
+
+        const c = MessageV2.page({ sessionID: session.id, limit: 2, after: b.cursor! })
+        expect(c.items.map((item) => item.info.id)).toEqual(ids.slice(4, 6))
+        expect(c.more).toBe(false)
+        expect(c.cursor).toBeUndefined()
+
+        await svc.remove(session.id)
+      },
+    })
+  })
+
+  test("rejects requests with both before and after", async () => {
+    await WithInstance.provide({
+      directory: root,
+      fn: async () => {
+        const session = await svc.create({})
+        await fill(session.id, 2)
+        const dummyCursor = MessageV2.cursor.encode({ id: MessageID.ascending(), time: 0 })
+        expect(() =>
+          MessageV2.page({ sessionID: session.id, limit: 2, before: dummyCursor, after: dummyCursor }),
+        ).toThrow()
+        await svc.remove(session.id)
+      },
+    })
+  })
+
   it.instance("large limit returns all messages without cursor", () =>
     withSession(({ sessionID }) =>
       Effect.gen(function* () {