core: simplify message history pagination with unified cursor API

Replace separate before/after query parameters with a single cursor that
carries direction info. Chat clients can now use 'start' or 'end' keywords
to jump to the beginning or newest messages, and navigate history with a
single cursor parameter instead of managing multiple pagination states.

Author: thdxr

packages/opencode/src/server/routes/instance/httpapi/api.ts

@@ -19,7 +19,7 @@ import { SessionApi } from "./groups/session"
 import { SyncApi } from "./groups/sync"
 import { TuiApi } from "./groups/tui"
 import { WorkspaceApi } from "./groups/workspace"
-import { V2Api } from "./v2"
+import { V2Api } from "./groups/v2"
 
 // SSE event schemas built from the same BusEvent/SyncEvent registries that
 // the Hono spec uses, so both specs emit identical Event/SyncEvent components.

…src/server/routes/instance/httpapi/v2.ts …ver/routes/instance/httpapi/groups/v2.tspackages/opencode/src/server/routes/instance/httpapi/v2.ts renamed to packages/opencode/src/server/routes/instance/httpapi/groups/v2.ts packages/opencode/src/server/routes/instance/httpapi/v2.ts renamed to packages/opencode/src/server/routes/instance/httpapi/groups/v2.ts

@@ -4,7 +4,7 @@ import { Prompt } from "@/v2/session-prompt"
 import { SessionV2 } from "@/v2/session"
 import { Schema } from "effect"
 import { HttpApi, HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
-import { Authorization } from "./middleware/authorization"
+import { Authorization } from "../middleware/authorization"
 
 export const V2Api = HttpApi.make("v2")
   .add(
@@ -23,31 +23,25 @@ export const V2Api = HttpApi.make("v2")
               description:
                 "Maximum number of messages to return. When omitted, the endpoint returns its default page size. Use limit without a cursor to fetch the newest page for chat history.",
             }),
-            before: Schema.optional(Schema.String).annotate({
+            cursor: Schema.optional(Schema.String).annotate({
               description:
-                "Opaque pagination cursor for the item at the start of the current window. Returns messages older than this cursor. Mutually exclusive with after.",
-            }),
-            after: Schema.optional(Schema.String).annotate({
-              description:
-                "Opaque pagination cursor for the item at the end of the current window. Returns messages newer than this cursor. Mutually exclusive with before.",
-            }),
-            from: Schema.optional(Schema.Literal("start")).annotate({
-              description:
-                "Start from the beginning of session history instead of the newest messages. Mutually exclusive with before and after.",
+                "Opaque pagination cursor returned as before or after in the previous response. The cursor encodes whether to fetch older or newer messages. Use start to read from the beginning or end to read from the latest messages; end is the default.",
             }),
           }).annotate({ identifier: "V2SessionMessagesQuery" }),
           success: Schema.Struct({
             items: Schema.Array(SessionMessage.Message),
-            before: Schema.String.pipe(Schema.optional),
-            after: Schema.String.pipe(Schema.optional),
+            cursor: Schema.Struct({
+              before: Schema.String.pipe(Schema.optional),
+              after: Schema.String.pipe(Schema.optional),
+            }),
           }).annotate({ identifier: "V2SessionMessagesResponse" }),
           error: HttpApiError.BadRequest,
         }).annotateMerge(
           OpenApi.annotations({
             identifier: "v2.session.messages",
             summary: "Get v2 session messages",
             description:
-              "Retrieve projected v2 messages for a session. For chat clients, request the latest page with limit, page backward through older history with before, and catch up with newer messages using after.",
+              "Retrieve projected v2 messages for a session. For chat clients, request the latest page with limit, page backward through older history with the before cursor, and catch up with newer messages using the after cursor.",
           }),
         ),
       )

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

@@ -10,14 +10,15 @@ const DefaultMessagesLimit = 50
 const Cursor = Schema.Struct({
   id: SessionMessage.ID,
   time: Schema.Number,
+  from: Schema.Union([Schema.Literal("start"), Schema.Literal("end")]),
 })
 
 const decodeCursor = Schema.decodeUnknownSync(Cursor)
 
 const cursor = {
-  encode(message: SessionMessage.Message) {
+  encode(message: SessionMessage.Message, from: "start" | "end") {
     return Buffer.from(
-      JSON.stringify({ id: message.id, time: DateTime.toEpochMillis(message.time.created) }),
+      JSON.stringify({ id: message.id, time: DateTime.toEpochMillis(message.time.created), from }),
     ).toString("base64url")
   },
   decode(input: string) {
@@ -33,29 +34,27 @@ export const v2Handlers = HttpApiBuilder.group(InstanceHttpApi, "v2", (handlers)
       .handle(
         "messages",
         Effect.fn(function* (ctx) {
-          if (ctx.query.before && ctx.query.after) return yield* new HttpApiError.BadRequest({})
-          if (ctx.query.from && (ctx.query.before || ctx.query.after)) return yield* new HttpApiError.BadRequest({})
           const decoded = yield* Effect.try({
-            try: () => {
-              return {
-                before: ctx.query.before ? cursor.decode(ctx.query.before) : undefined,
-                after: ctx.query.after ? cursor.decode(ctx.query.after) : undefined,
-              }
-            },
+            try: () =>
+              ctx.query.cursor && ctx.query.cursor !== "start" && ctx.query.cursor !== "end"
+                ? cursor.decode(ctx.query.cursor)
+                : undefined,
             catch: () => new HttpApiError.BadRequest({}),
           })
           const messages = yield* session.messages({
             sessionID: ctx.params.sessionID,
             limit: ctx.query.limit ?? DefaultMessagesLimit,
-            cursor: decoded.before ?? decoded.after,
-            direction: decoded.after ? "after" : "before",
+            from: decoded?.from ?? (ctx.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,
-            before: oldest ? cursor.encode(oldest) : undefined,
-            after: newest ? cursor.encode(newest) : undefined,
+            cursor: {
+              before: oldest ? cursor.encode(oldest, "end") : undefined,
+              after: newest ? cursor.encode(newest, "start") : undefined,
+            },
           }
         }),
       )

packages/opencode/src/v2/session.ts

@@ -16,32 +16,16 @@ export type Delivery = Schema.Schema.Type<typeof Delivery>
 
 export const DefaultDelivery = "immediate" satisfies Delivery
 
-export type MessagesCursor = {
-  id: SessionMessage.ID
-  time: number
-}
-
-export type MessagesInput = {
-  sessionID: SessionID
-  limit?: number
-  cursor?: MessagesCursor
-  direction?: "before" | "after"
-}
-
-const older = (item: MessagesCursor) =>
-  or(
-    lt(SessionMessageTable.time_created, item.time),
-    and(eq(SessionMessageTable.time_created, item.time), lt(SessionMessageTable.id, item.id)),
-  )
-
-const newer = (item: MessagesCursor) =>
-  or(
-    gt(SessionMessageTable.time_created, item.time),
-    and(eq(SessionMessageTable.time_created, item.time), gt(SessionMessageTable.id, item.id)),
-  )
-
 export interface Interface {
-  readonly messages: (input: MessagesInput) => Effect.Effect<SessionMessage.Message[], never>
+  readonly messages: (input: {
+    sessionID: SessionID
+    limit?: number
+    from?: "start" | "end"
+    cursor?: {
+      id: SessionMessage.ID
+      time: number
+    }
+  }) => Effect.Effect<SessionMessage.Message[], never>
   readonly prompt: (input: {
     id?: Event.ID
     sessionID: SessionID
@@ -64,44 +48,45 @@ export const layer = Layer.effect(
 
     const result: Interface = {
       messages: Effect.fn("V2Session.messages")(function* (input) {
-        if (input.limit === undefined) {
-          const rows = Database.use((db) =>
-            db
-              .select()
-              .from(SessionMessageTable)
-              .where(eq(SessionMessageTable.session_id, input.sessionID))
-              .orderBy(asc(SessionMessageTable.time_created), asc(SessionMessageTable.id))
-              .all(),
-          )
-          return rows.map((row) => decode(row))
-        }
-
-        const limit = input.limit
-        const direction = input.direction ?? "before"
-        const where = input.cursor
-          ? and(
-              eq(SessionMessageTable.session_id, input.sessionID),
-              direction === "after" ? newer(input.cursor) : older(input.cursor),
-            )
+        const from = input.from ?? (input.limit === undefined && input.cursor === undefined ? "start" : "end")
+        const boundary = input.cursor
+          ? from === "start"
+            ? or(
+                gt(SessionMessageTable.time_created, input.cursor.time),
+                and(
+                  eq(SessionMessageTable.time_created, input.cursor.time),
+                  gt(SessionMessageTable.id, input.cursor.id),
+                ),
+              )
+            : or(
+                lt(SessionMessageTable.time_created, input.cursor.time),
+                and(
+                  eq(SessionMessageTable.time_created, input.cursor.time),
+                  lt(SessionMessageTable.id, input.cursor.id),
+                ),
+              )
+          : undefined
+        const where = boundary
+          ? and(eq(SessionMessageTable.session_id, input.sessionID), boundary)
           : eq(SessionMessageTable.session_id, input.sessionID)
+
         const rows = Database.use((db) => {
-          if (direction === "after") {
-            return db
+          if (from === "start") {
+            const query = db
               .select()
               .from(SessionMessageTable)
               .where(where)
               .orderBy(asc(SessionMessageTable.time_created), asc(SessionMessageTable.id))
-              .limit(limit)
-              .all()
+            return input.limit === undefined ? query.all() : query.limit(input.limit).all()
           }
-          const ids = db
+          const idsQuery = db
             .select({ id: SessionMessageTable.id })
             .from(SessionMessageTable)
             .where(where)
             .orderBy(desc(SessionMessageTable.time_created), desc(SessionMessageTable.id))
-            .limit(limit)
-            .all()
-            .map((row) => row.id)
+          const ids = (input.limit === undefined ? idsQuery.all() : idsQuery.limit(input.limit).all()).map(
+            (row) => row.id,
+          )
           if (ids.length === 0) return []
           return db
             .select()