core: add pagination support for session messages with cursor-based navigation

Enables loading messages in chunks for better performance with long conversations.
Users can now navigate through large session histories without loading all messages at once.
Includes before/after cursors for bi-directional pagination.

Author: thdxr

packages/opencode/src/cli/cmd/tui/context/sync-v2.tsx

@@ -254,10 +254,8 @@ export const { use: useSyncV2, provider: SyncProviderV2 } = createSimpleContext(
       session: {
         message: {
           async sync(sessionID: string) {
-            const response = await sdk.client.v2.session.messages({
-              sessionID,
-            })
-            setStore("messages", sessionID, reconcile(response.data ?? []))
+            const response = await sdk.client.v2.session.messages({ sessionID })
+            setStore("messages", sessionID, reconcile(response.data?.items ?? []))
           },
           fromSession(sessionID: string) {
             const messages = store.messages[sessionID]

packages/opencode/src/server/routes/instance/v2.ts

@@ -4,12 +4,43 @@ import { SessionV2 } from "@/v2/session"
 import { zod } from "@/util/effect-zod"
 import { lazy } from "@/util/lazy"
 import { Effect, Schema } from "effect"
+import * as DateTime from "effect/DateTime"
 import { Hono } from "hono"
 import { describeRoute, resolver, validator } from "hono-openapi"
+import { HTTPException } from "hono/http-exception"
 import z from "zod"
 import { errors } from "../../error"
 import { jsonRequest } from "./trace"
 
+const DefaultMessagesLimit = 50
+
+const Cursor = Schema.Struct({
+  id: SessionMessage.ID,
+  time: Schema.Number,
+  from: Schema.Union([Schema.Literal("start"), Schema.Literal("end")]),
+})
+
+const MessagesResponse = Schema.Struct({
+  items: Schema.Array(SessionMessage.Message),
+  cursor: Schema.Struct({
+    before: Schema.String.pipe(Schema.optional),
+    after: Schema.String.pipe(Schema.optional),
+  }),
+}).annotate({ identifier: "V2SessionMessagesResponse" })
+
+const decodeCursor = Schema.decodeUnknownSync(Cursor)
+
+const cursor = {
+  encode(message: SessionMessage.Message, from: "start" | "end") {
+    return Buffer.from(
+      JSON.stringify({ id: message.id, time: DateTime.toEpochMillis(message.time.created), from }),
+    ).toString("base64url")
+  },
+  decode(input: string) {
+    return decodeCursor(JSON.parse(Buffer.from(input, "base64url").toString("utf8")))
+  },
+}
+
 export const V2Routes = lazy(() =>
   new Hono().get(
     "/session/:sessionID/message",
@@ -22,20 +53,51 @@ export const V2Routes = lazy(() =>
           description: "List of v2 session messages",
           content: {
             "application/json": {
-              schema: resolver(zod(Schema.Array(SessionMessage.Message))),
+              schema: resolver(zod(MessagesResponse)),
             },
           },
         },
         ...errors(400, 404),
       },
     }),
     validator("param", z.object({ sessionID: SessionID.zod })),
+    validator(
+      "query",
+      z.object({
+        limit: z.coerce.number().int().min(1).max(200).optional(),
+        cursor: z.string().optional(),
+      }),
+    ),
     async (c) => {
       const sessionID = c.req.valid("param").sessionID
+      const query = c.req.valid("query")
+      const decoded = (() => {
+        try {
+          return query.cursor && query.cursor !== "start" && query.cursor !== "end"
+            ? cursor.decode(query.cursor)
+            : undefined
+        } catch {
+          throw new HTTPException(400)
+        }
+      })()
       return jsonRequest("V2Routes.messages", c, function* () {
         return yield* Effect.gen(function* () {
           const session = yield* SessionV2.Service
-          return yield* session.messages({ sessionID })
+          const messages = yield* session.messages({
+            sessionID,
+            limit: query.limit ?? DefaultMessagesLimit,
+            from: decoded?.from ?? (query.cursor === "start" ? "start" : "end"),
+            cursor: decoded ? { id: decoded.id, time: decoded.time } : undefined,
+          })
+          const oldest = messages[0]
+          const newest = messages.at(-1)
+          return {
+            items: messages,
+            cursor: {
+              before: oldest ? cursor.encode(oldest, "end") : undefined,
+              after: newest ? cursor.encode(newest, "start") : undefined,
+            },
+          }
         }).pipe(Effect.provide(SessionV2.defaultLayer))
       })
     },

packages/sdk/js/src/v2/gen/sdk.gen.ts

@@ -3192,6 +3192,8 @@ export class Session3 extends HeyApiClient {
       sessionID: string
       directory?: string
       workspace?: string
+      limit?: number
+      cursor?: string
     },
     options?: Options<never, ThrowOnError>,
   ) {
@@ -3203,6 +3205,8 @@ export class Session3 extends HeyApiClient {
             { in: "path", key: "sessionID" },
             { in: "query", key: "directory" },
             { in: "query", key: "workspace" },
+            { in: "query", key: "limit" },
+            { in: "query", key: "cursor" },
           ],
         },
       ],

packages/sdk/js/src/v2/gen/types.gen.ts

@@ -2842,6 +2842,14 @@ export type SessionMessage =
   | SessionMessageAssistant
   | SessionMessageCompaction
 
+export type V2SessionMessagesResponse = {
+  items: Array<SessionMessage>
+  cursor: {
+    before?: string
+    after?: string
+  }
+}
+
 export type Symbol = {
   name: string
   kind: number
@@ -5528,6 +5536,8 @@ export type V2SessionMessagesData = {
   query?: {
     directory?: string
     workspace?: string
+    limit?: number
+    cursor?: string
   }
   url: "/api/session/{sessionID}/message"
 }
@@ -5549,10 +5559,10 @@ export type V2SessionMessagesResponses = {
   /**
    * List of v2 session messages
    */
-  200: Array<SessionMessage>
+  200: V2SessionMessagesResponse
 }
 
-export type V2SessionMessagesResponse = V2SessionMessagesResponses[keyof V2SessionMessagesResponses]
+export type V2SessionMessagesResponse2 = V2SessionMessagesResponses[keyof V2SessionMessagesResponses]
 
 export type FindTextData = {
   body?: never