refactor(core): simplify session pagination

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

@@ -2,7 +2,10 @@ import { SessionID } from "@/session/schema"
 import { SessionMessage } from "@opencode-ai/core/session/message"
 import { Prompt } from "@opencode-ai/core/session/prompt"
 import { SessionV2 } from "@opencode-ai/core/session"
-import { Schema } from "effect"
+import { ProjectV2 } from "@opencode-ai/core/project"
+import { AbsolutePath, PositiveInt, RelativePath, withStatics } from "@opencode-ai/core/schema"
+import { WorkspaceV2 } from "@opencode-ai/core/workspace"
+import { Schema, Struct } from "effect"
 import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
 import {
   InvalidCursorError,
@@ -12,29 +15,73 @@ import {
   UnknownError,
 } from "../../errors"
 import { V2Authorization } from "../../middleware/authorization"
-import { WorkspaceRoutingQuery, WorkspaceRoutingQueryFields } from "../../middleware/workspace-routing"
-import { QueryBoolean } from "../query"
+import { WorkspaceRoutingQuery } from "../../middleware/workspace-routing"
 
-export const SessionsQuery = Schema.Struct({
-  ...WorkspaceRoutingQueryFields,
-  limit: Schema.optional(
-    Schema.NumberFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(200)),
-  ).annotate({
+const SessionsQueryFields = {
+  workspace: WorkspaceV2.ID.pipe(Schema.optional),
+  limit: Schema.NumberFromString.pipe(Schema.decodeTo(PositiveInt), Schema.optional).annotate({
     description: "Maximum number of sessions to return. Defaults to the newest 50 sessions.",
   }),
   order: Schema.optional(Schema.Union([Schema.Literal("asc"), Schema.Literal("desc")])).annotate({
     description: "Session order for the first page. Use desc for newest first or asc for oldest first.",
   }),
-  path: Schema.optional(Schema.String),
-  roots: Schema.optional(QueryBoolean),
-  start: Schema.optional(Schema.NumberFromString),
   search: Schema.optional(Schema.String),
-  cursor: Schema.optional(
-    Schema.String.annotate({
-      description:
-        "Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response. Do not combine with order or filters.",
-    }),
-  ),
+}
+
+const SessionsDirectoryQuery = Schema.Struct({
+  ...SessionsQueryFields,
+  directory: AbsolutePath,
+})
+
+const SessionsProjectQuery = Schema.Struct({
+  ...SessionsQueryFields,
+  project: ProjectV2.ID,
+  subpath: RelativePath.pipe(Schema.optional),
+})
+
+const SessionsAllQuery = Schema.Struct(SessionsQueryFields)
+
+const withCursor = <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) =>
+  schema.mapFields((fields) => ({
+    ...Struct.omit(fields, ["limit"]),
+    anchor: SessionV2.ListAnchor,
+  }))
+
+const SessionsCursorInput = Schema.Union([
+  withCursor(SessionsDirectoryQuery),
+  withCursor(SessionsProjectQuery),
+  withCursor(SessionsAllQuery),
+])
+const SessionsCursorJson = Schema.fromJsonString(SessionsCursorInput)
+const encodeSessionsCursor = Schema.encodeSync(SessionsCursorJson)
+const decodeSessionsCursor = Schema.decodeUnknownEffect(SessionsCursorJson)
+
+export const SessionsCursor = Schema.String.pipe(
+  Schema.brand("V2SessionsCursor"),
+  withStatics((schema) => {
+    const make = schema.make
+    return {
+      make: (input: typeof SessionsCursorInput.Type) =>
+        make(Buffer.from(encodeSessionsCursor(input)).toString("base64url")),
+      parse: (input: string) => decodeSessionsCursor(Buffer.from(input, "base64url").toString("utf8")),
+    }
+  }),
+)
+export type SessionsCursor = typeof SessionsCursor.Type
+
+const SessionsCursorQuery = Schema.Struct({
+  cursor: SessionsCursor.annotate({
+    description: "Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.",
+  }),
+  limit: SessionsQueryFields.limit,
+})
+
+export const SessionsQuery = Schema.Struct({
+  ...SessionsQueryFields,
+  directory: AbsolutePath.pipe(Schema.optional),
+  project: ProjectV2.ID.pipe(Schema.optional),
+  subpath: RelativePath.pipe(Schema.optional),
+  cursor: SessionsCursorQuery.fields.cursor.pipe(Schema.optional),
 }).annotate({ identifier: "V2SessionsQuery" })
 
 export const SessionGroup = HttpApiGroup.make("v2.session")
@@ -44,8 +91,8 @@ export const SessionGroup = HttpApiGroup.make("v2.session")
       success: Schema.Struct({
         items: Schema.Array(SessionV2.Info),
         cursor: Schema.Struct({
-          previous: Schema.String.pipe(Schema.optional),
-          next: Schema.String.pipe(Schema.optional),
+          previous: SessionsCursor.pipe(Schema.optional),
+          next: SessionsCursor.pipe(Schema.optional),
         }),
       }).annotate({ identifier: "V2SessionsResponse" }),
       error: [InvalidCursorError, InvalidRequestError],

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

@@ -1,95 +1,12 @@
-import { WorkspaceV2 } from "@opencode-ai/core/workspace"
 import { SessionV2 } from "@opencode-ai/core/session"
-import { AbsolutePath } from "@opencode-ai/core/schema"
-import { DateTime, Effect, Option, Schema } from "effect"
+import { DateTime, Effect } from "effect"
 import { HttpApiBuilder, HttpApiSchema } from "effect/unstable/httpapi"
 import { InstanceHttpApi } from "../../api"
-import {
-  InvalidCursorError,
-  InvalidRequestError,
-  ServiceUnavailableError,
-  SessionNotFoundError,
-  UnknownError,
-} from "../../errors"
+import { SessionsCursor } from "../../groups/v2/session"
+import { InvalidCursorError, ServiceUnavailableError, SessionNotFoundError, UnknownError } from "../../errors"
 
 const DefaultSessionsLimit = 50
 
-const SessionCursor = Schema.Struct({
-  id: SessionV2.Info.fields.id,
-  time: Schema.Finite,
-  order: Schema.Union([Schema.Literal("asc"), Schema.Literal("desc")]),
-  direction: Schema.Union([Schema.Literal("previous"), Schema.Literal("next")]),
-  directory: Schema.String.pipe(Schema.optional),
-  path: Schema.String.pipe(Schema.optional),
-  workspaceID: WorkspaceV2.ID.pipe(Schema.optional),
-  roots: Schema.Boolean.pipe(Schema.optional),
-  start: Schema.Finite.pipe(Schema.optional),
-  search: Schema.String.pipe(Schema.optional),
-})
-type SessionCursor = typeof SessionCursor.Type
-
-const decodeCursor = Schema.decodeUnknownSync(SessionCursor)
-
-function hasCursorFilter(query: {
-  readonly order?: unknown
-  readonly path?: unknown
-  readonly roots?: unknown
-  readonly start?: unknown
-  readonly search?: unknown
-}) {
-  return (
-    query.order !== undefined ||
-    query.path !== undefined ||
-    query.roots !== undefined ||
-    query.start !== undefined ||
-    query.search !== undefined
-  )
-}
-
-function hasCursorRoutingMismatch(
-  query: { readonly directory?: string; readonly workspace?: string },
-  decoded: SessionCursor | undefined,
-) {
-  if (!decoded) return false
-  if (query.directory !== undefined && query.directory !== decoded.directory) return true
-  return query.workspace !== undefined && query.workspace !== decoded.workspaceID
-}
-
-const sessionCursor = {
-  encode(
-    session: SessionV2.Info,
-    order: "asc" | "desc",
-    direction: "previous" | "next",
-    filters: Pick<SessionCursor, "directory" | "path" | "workspaceID" | "roots" | "start" | "search">,
-  ) {
-    return Buffer.from(
-      JSON.stringify({
-        ...filters,
-        id: session.id,
-        time: DateTime.toEpochMillis(session.time.updated),
-        order,
-        direction,
-      }),
-    ).toString("base64url")
-  },
-  decode(input: string) {
-    return decodeCursor(JSON.parse(Buffer.from(input, "base64url").toString("utf8")))
-  },
-}
-
-function decodeWorkspaceID(input: string | undefined) {
-  if (input === undefined) return Effect.succeed(undefined)
-  const workspaceID = Schema.decodeUnknownOption(WorkspaceV2.ID)(input)
-  if (Option.isSome(workspaceID)) return Effect.succeed(workspaceID.value)
-  return Effect.fail(
-    new InvalidRequestError({
-      message: "Invalid workspace query parameter",
-      kind: "Query",
-      field: "workspace",
-    }),
-  )
-}
-
 export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "v2.session", (handlers) =>
   Effect.gen(function* () {
     const session = yield* SessionV2.Service
@@ -98,45 +15,42 @@ export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "v2.session
       .handle(
         "sessions",
         Effect.fn(function* (ctx) {
-          if (ctx.query.cursor && hasCursorFilter(ctx.query))
-            return yield* new InvalidCursorError({ message: "Cursor cannot be combined with order or filters" })
-          const decoded = yield* Effect.try({
-            try: () => (ctx.query.cursor ? sessionCursor.decode(ctx.query.cursor) : undefined),
-            catch: () => new InvalidCursorError({ message: "Invalid cursor" }),
-          })
-          if (hasCursorRoutingMismatch(ctx.query, decoded))
-            return yield* new InvalidCursorError({ message: "Cursor does not match requested directory or workspace" })
-          const order = decoded?.order ?? ctx.query.order ?? "desc"
-          const filters = decoded ?? {
-            directory: ctx.query.directory,
-            path: ctx.query.path,
-            workspaceID: yield* decodeWorkspaceID(ctx.query.workspace),
-            roots: ctx.query.roots,
-            start: ctx.query.start,
-            search: ctx.query.search,
-          }
-          const input = {
+          const query =
+            ctx.query.cursor !== undefined
+              ? yield* SessionsCursor.parse(ctx.query.cursor).pipe(
+                  Effect.mapError(() => new InvalidCursorError({ message: "Invalid cursor" })),
+                )
+              : ctx.query
+          const sessions = yield* session.list({
+            ...query,
+            workspaceID: query.workspace,
             limit: ctx.query.limit ?? DefaultSessionsLimit,
-            order,
-            workspaceID: filters.workspaceID,
-            search: filters.search,
-            cursor: decoded ? { id: decoded.id, time: decoded.time, direction: decoded.direction } : undefined,
-          }
-          const sessions = yield* session.list(
-            filters.directory
-              ? {
-                  ...input,
-                  directory: AbsolutePath.make(filters.directory),
-                }
-              : input,
-          )
+          })
           const first = sessions[0]
           const last = sessions.at(-1)
           return {
             items: sessions,
             cursor: {
-              previous: first ? sessionCursor.encode(first, order, "previous", filters) : undefined,
-              next: last ? sessionCursor.encode(last, order, "next", filters) : undefined,
+              previous: first
+                ? SessionsCursor.make({
+                    ...query,
+                    anchor: {
+                      id: first.id,
+                      time: DateTime.toEpochMillis(first.time.created),
+                      direction: "previous",
+                    },
+                  })
+                : undefined,
+              next: last
+                ? SessionsCursor.make({
+                    ...query,
+                    anchor: {
+                      id: last.id,
+                      time: DateTime.toEpochMillis(last.time.created),
+                      direction: "next",
+                    },
+                  })
+                : undefined,
             },
           }
         }),