feat(plugin): cursor pagination for plugin session list and messages

packages/client/src/effect/api/api.ts

@@ -118,6 +118,7 @@ export type SessionListOperation<E = never> = (input?: Endpoint5_0Input) => Effe
 
 export type Endpoint5_1Input = {
   readonly id?: Session.ID | undefined
+  readonly title?: string | undefined
   readonly agent?: Agent.ID | undefined
   readonly model?: Model.Ref | undefined
   readonly location?: Location.Ref | undefined

packages/client/src/effect/generated/client.ts

@@ -299,7 +299,13 @@ const Endpoint5_0 = (raw: RawClient["server.session"]) => (input?: Endpoint5_0In
 const Endpoint5_1 = (raw: RawClient["server.session"]) => (input?: Endpoint5_1Input) =>
   preserveEffect<Endpoint5_1Output>()(
     raw["session.create"]({
-      payload: { id: input?.["id"], agent: input?.["agent"], model: input?.["model"], location: input?.["location"] },
+      payload: {
+        id: input?.["id"],
+        title: input?.["title"],
+        agent: input?.["agent"],
+        model: input?.["model"],
+        location: input?.["location"],
+      },
     }).pipe(
       Effect.mapError(mapClientError),
       Effect.map((value) => value.data),

packages/client/src/promise/generated/client.ts

@@ -462,6 +462,7 @@ export function make(options: ClientOptions) {
             path: `/api/session`,
             body: {
               id: input?.["id"],
+              title: input?.["title"],
               agent: input?.["agent"],
               model: input?.["model"],
               location: input?.["location"],

packages/client/src/promise/generated/types.ts

@@ -2662,24 +2662,35 @@ export type SessionListOutput = SessionsResponse
 export type SessionCreateInput = {
   readonly id?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
   }["id"]
+  readonly title?: {
+    readonly id?: string | null
+    readonly title?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
+    readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
+  }["title"]
   readonly agent?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
   }["agent"]
   readonly model?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null
   }["model"]
   readonly location?: {
     readonly id?: string | null
+    readonly title?: string | null
     readonly agent?: string | null
     readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string } | null
     readonly location?: { readonly directory: string; readonly workspaceID?: string } | null

packages/core/src/plugin/host.ts

@@ -4,6 +4,8 @@ import { Plugin } from "@opencode-ai/plugin/effect"
 import type { IntegrationMethodRegistration } from "@opencode-ai/plugin/effect/integration"
 import type { CredentialOAuth } from "@opencode-ai/sdk/v2/types"
 import { EventManifest } from "@opencode-ai/schema/event-manifest"
+import { SessionMessagesCursor } from "@opencode-ai/schema/session-messages-cursor"
+import { SessionsQuery } from "@opencode-ai/schema/sessions-query"
 import { App } from "../app"
 import { Effect, Schema, Stream } from "effect"
 import { Agent } from "../agent"
@@ -341,17 +343,54 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: import("../p
       create: (input) =>
         runtime.session.create({
           id: input?.id,
+          title: input?.title,
           agent: input?.agent,
           model: input?.model,
           location:
             input?.location ?? Location.Ref.make({ directory: location.directory, workspaceID: location.workspaceID }),
         }),
       get: (input) => runtime.session.get(input.sessionID),
+      list: (input) =>
+        Effect.gen(function* () {
+          const query =
+            input?.cursor !== undefined
+              ? yield* SessionsQuery.Cursor.parse(input.cursor).pipe(
+                  Effect.mapError(() => new Error("Invalid cursor")),
+                )
+              : (input ?? {})
+          const page = yield* runtime.session.list({
+            ...query,
+            workspaceID: query.workspace,
+            limit: input?.limit ?? SessionsQuery.DefaultLimit,
+          })
+          return { data: page.data, cursor: SessionsQuery.Cursor.page(query, page.data) }
+        }),
+      messages: (input) =>
+        Effect.gen(function* () {
+          if (input.cursor !== undefined && input.order !== undefined)
+            return yield* Effect.fail(new Error("Cursor cannot be combined with order"))
+          const decoded =
+            input.cursor !== undefined
+              ? yield* SessionMessagesCursor.parse(input.cursor).pipe(
+                  Effect.mapError(() => new Error("Invalid cursor")),
+                )
+              : undefined
+          const order = decoded?.order ?? input.order ?? "desc"
+          const data = yield* runtime.session.messages({
+            sessionID: input.sessionID,
+            limit: input.limit ?? SessionMessagesCursor.DefaultLimit,
+            order,
+            cursor: decoded ? { id: decoded.id, direction: decoded.direction } : undefined,
+          })
+          return { data, cursor: SessionMessagesCursor.page(data, order) }
+        }),
       prompt: runtime.session.prompt,
       generate: (input) => runtime.session.generate(input).pipe(Effect.map((text) => ({ text }))),
       command: runtime.session.command,
+      rename: runtime.session.rename,
       synthetic: runtime.session.synthetic,
       interrupt: (input) => runtime.session.interrupt(input.sessionID),
+      wait: (input) => runtime.session.wait(input.sessionID),
     },
   } satisfies Plugin.Context
 })

packages/core/src/plugin/runtime.ts

@@ -11,7 +11,18 @@ import { Session } from "../session"
 export interface Interface {
   readonly session: Pick<
     Session.Interface,
-    "get" | "create" | "messages" | "prompt" | "generate" | "command" | "resume" | "interrupt" | "synthetic"
+    | "get"
+    | "create"
+    | "list"
+    | "messages"
+    | "prompt"
+    | "generate"
+    | "command"
+    | "rename"
+    | "resume"
+    | "interrupt"
+    | "synthetic"
+    | "wait"
   >
   readonly job: Pick<Job.Interface, "start" | "wait" | "block" | "background" | "cancel">
   readonly location: {
@@ -48,13 +59,16 @@ export const layerWithCell = (cell: Cell) =>
       session: {
         get: (sessionID) => require(cell, (runtime) => runtime.session.get(sessionID)),
         create: (input) => require(cell, (runtime) => runtime.session.create(input)),
+        list: (input) => require(cell, (runtime) => runtime.session.list(input)),
         messages: (input) => require(cell, (runtime) => runtime.session.messages(input)),
         prompt: (input) => require(cell, (runtime) => runtime.session.prompt(input)),
         generate: (input) => require(cell, (runtime) => runtime.session.generate(input)),
         command: (input) => require(cell, (runtime) => runtime.session.command(input)),
+        rename: (input) => require(cell, (runtime) => runtime.session.rename(input)),
         resume: (sessionID) => require(cell, (runtime) => runtime.session.resume(sessionID)),
         interrupt: (sessionID) => require(cell, (runtime) => runtime.session.interrupt(sessionID)),
         synthetic: (input) => require(cell, (runtime) => runtime.session.synthetic(input)),
+        wait: (sessionID) => require(cell, (runtime) => runtime.session.wait(sessionID)),
       },
       job: {
         start: (input) => require(cell, (runtime) => runtime.job.start(input)),

packages/core/test/plugin/host.ts

@@ -103,11 +103,15 @@ export function host(overrides: Overrides = {}): Plugin.Context {
       hook: overrides.session?.hook ?? (() => Effect.die("unused session.hook")),
       create: overrides.session?.create ?? (() => Effect.die("unused session.create")),
       get: overrides.session?.get ?? (() => Effect.die("unused session.get")),
+      list: overrides.session?.list ?? (() => Effect.die("unused session.list")),
+      messages: overrides.session?.messages ?? (() => Effect.die("unused session.messages")),
       prompt: overrides.session?.prompt ?? (() => Effect.die("unused session.prompt")),
       generate: overrides.session?.generate ?? (() => Effect.die("unused session.generate")),
       command: overrides.session?.command ?? (() => Effect.die("unused session.command")),
+      rename: overrides.session?.rename ?? (() => Effect.die("unused session.rename")),
       synthetic: overrides.session?.synthetic ?? (() => Effect.die("unused session.synthetic")),
       interrupt: overrides.session?.interrupt ?? (() => Effect.die("unused session.interrupt")),
+      wait: overrides.session?.wait ?? (() => Effect.die("unused session.wait")),
     },
   }
 }

packages/plugin/src/effect/session.ts

@@ -1,4 +1,4 @@
-import type { SessionApi } from "@opencode-ai/client/effect/api"
+import type { MessageApi, SessionApi } from "@opencode-ai/client/effect/api"
 import type { Message, SystemPart } from "@opencode-ai/ai"
 import type { HttpRequest } from "@opencode-ai/ai/route"
 import type { Agent } from "@opencode-ai/schema/agent"
@@ -29,7 +29,9 @@ export interface SessionHooks {
 
 export type SessionDomain = Pick<
   SessionApi<unknown>,
-  "create" | "get" | "prompt" | "generate" | "command" | "synthetic" | "interrupt"
+  "create" | "get" | "list" | "prompt" | "generate" | "command" | "synthetic" | "interrupt" | "rename" | "wait"
 > & {
   readonly hook: Hooks<SessionHooks>
+  /** Read a session's projected message history, paginated like the HTTP message list endpoint. */
+  readonly messages: MessageApi<unknown>["list"]
 }

packages/protocol/src/groups/session.ts

@@ -4,7 +4,8 @@ import { PromptInput } from "@opencode-ai/schema/prompt-input"
 import { Session } from "@opencode-ai/schema/session"
 import { InstructionEntry } from "@opencode-ai/schema/instruction-entry"
 import { Project } from "@opencode-ai/schema/project"
-import { AbsolutePath, PositiveInt, RelativePath, statics } from "@opencode-ai/schema/schema"
+import { AbsolutePath, PositiveInt, RelativePath } from "@opencode-ai/schema/schema"
+import { SessionsQuery } from "@opencode-ai/schema/sessions-query"
 import { Event } from "@opencode-ai/schema/event"
 import { Workspace } from "@opencode-ai/schema/workspace"
 import { Context, Effect, Encoding, Result, Schema, SchemaGetter, Struct } from "effect"
@@ -29,76 +30,6 @@ import { Location } from "@opencode-ai/schema/location"
 import { SessionEvent } from "@opencode-ai/schema/session-event"
 import { EventLog } from "@opencode-ai/schema/event-log"
 
-const ParentIDFilter = Schema.Union([
-  Session.ID,
-  Schema.Null.pipe(
-    Schema.encodeTo(Schema.Literal("null"), {
-      decode: SchemaGetter.transform(() => null),
-      encode: SchemaGetter.transform(() => "null" as const),
-    }),
-  ),
-]).annotate({
-  description: "Filter by parent session. Use null to return only root sessions.",
-})
-
-const SessionsQueryFields = {
-  workspace: Workspace.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.",
-  }),
-  search: Schema.optional(Schema.String),
-  parentID: ParentIDFilter.pipe(Schema.optional),
-}
-
-const SessionsDirectoryQuery = Schema.Struct({
-  ...SessionsQueryFields,
-  directory: AbsolutePath,
-})
-
-const SessionsProjectQuery = Schema.Struct({
-  ...SessionsQueryFields,
-  project: Project.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: Session.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)
-const invalidCursor = "Invalid cursor" as const
-
-export const SessionsCursor = Schema.String.pipe(
-  Schema.brand("SessionsCursor"),
-  statics((schema) => {
-    const make = schema.make.bind(schema)
-    return {
-      make: (input: typeof SessionsCursorInput.Type) => make(Encoding.encodeBase64Url(encodeSessionsCursor(input))),
-      parse: (input: string) =>
-        Effect.suspend(() => {
-          const result = Encoding.decodeBase64UrlString(input)
-          return Result.isFailure(result)
-            ? Effect.fail(invalidCursor)
-            : decodeSessionsCursor(result.success).pipe(Effect.mapError(() => invalidCursor))
-        }),
-    }
-  }),
-)
-export type SessionsCursor = typeof SessionsCursor.Type
 
 const SessionActive = Schema.Struct({
   type: Schema.Literal("running"),
@@ -111,28 +42,17 @@ const BooleanFromString = Schema.Literals(["true", "false"]).pipe(
   }),
 )
 
-const SessionsQueryCursor = SessionsCursor.annotate({
-  description: "Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.",
-})
-
-export const SessionsQuery = Schema.Struct({
-  ...SessionsQueryFields,
-  directory: AbsolutePath.pipe(Schema.optional),
-  project: Project.ID.pipe(Schema.optional),
-  subpath: RelativePath.pipe(Schema.optional),
-  cursor: SessionsQueryCursor.pipe(Schema.optional),
-}).annotate({ identifier: "SessionsQuery" })
 
 export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLocationMiddleware: Context.Key<I, S>) =>
   HttpApiGroup.make("server.session")
     .add(
       HttpApiEndpoint.get("session.list", "/api/session", {
-        query: SessionsQuery,
+        query: SessionsQuery.Query,
         success: Schema.Struct({
           data: Schema.Array(Session.Info),
           cursor: Schema.Struct({
-            previous: SessionsCursor.pipe(Schema.optional),
-            next: SessionsCursor.pipe(Schema.optional),
+            previous: SessionsQuery.Cursor.pipe(Schema.optional),
+            next: SessionsQuery.Cursor.pipe(Schema.optional),
           }),
         }).annotate({ identifier: "SessionsResponse" }),
         error: [InvalidCursorError, InvalidRequestError],
@@ -149,6 +69,7 @@ export const makeSessionGroup = <I extends HttpApiMiddleware.AnyId, S>(sessionLo
       HttpApiEndpoint.post("session.create", "/api/session", {
         payload: Schema.Struct({
           id: Session.ID.pipe(Schema.optional),
+          title: Schema.String.pipe(Schema.optional),
           agent: Agent.ID.pipe(Schema.optional),
           model: Model.Ref.pipe(Schema.optional),
           location: Location.Ref.pipe(Schema.optional),

packages/protocol/test/session-cursor.test.ts

@@ -1,18 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { Effect } from "effect"
-import { SessionsCursor } from "../src/groups/session.js"
-import { Session } from "@opencode-ai/schema/session"
-
-describe("SessionsCursor", () => {
-  test("round trips without Node globals", async () => {
-    const input = {
-      workspace: undefined,
-      search: "protocol",
-      order: "desc" as const,
-      anchor: { id: Session.ID.make("ses_test"), time: 1, direction: "next" as const },
-    }
-    const cursor = SessionsCursor.make(input)
-
-    expect(await Effect.runPromise(SessionsCursor.parse(cursor))).toEqual(input)
-  })
-})

packages/schema/src/session-messages-cursor.ts

@@ -0,0 +1,48 @@
+export * as SessionMessagesCursor from "./session-messages-cursor.js"
+
+import { Effect, Encoding, Result, Schema } from "effect"
+import { SessionMessage } from "./session-message.js"
+
+/**
+ * Shared session message pagination cursor. Lives in schema so the protocol
+ * message handler and the core plugin host paginate identically. The encoded
+ * cursor carries the page order, so a cursor cannot be combined with an
+ * explicit order.
+ */
+
+export const DefaultLimit = 50
+
+export const Order = Schema.Literals(["asc", "desc"])
+export type Order = typeof Order.Type
+
+const Payload = Schema.Struct({
+  id: SessionMessage.ID,
+  order: Order,
+  direction: Schema.Literals(["previous", "next"]),
+})
+export type Payload = typeof Payload.Type
+
+const PayloadJson = Schema.fromJsonString(Payload)
+const encodePayload = Schema.encodeSync(PayloadJson)
+const decodePayload = Schema.decodeUnknownEffect(PayloadJson)
+const invalidCursor = "Invalid cursor" as const
+
+export const make = (input: Payload) => Encoding.encodeBase64Url(encodePayload(input))
+
+export const parse = (input: string) =>
+  Effect.suspend(() => {
+    const result = Encoding.decodeBase64UrlString(input)
+    return Result.isFailure(result)
+      ? Effect.fail(invalidCursor)
+      : decodePayload(result.success).pipe(Effect.mapError(() => invalidCursor))
+  })
+
+/** previous/next cursors for one returned page of messages. */
+export const page = (data: ReadonlyArray<SessionMessage.Info>, order: Order) => {
+  const first = data[0]
+  const last = data.at(-1)
+  return {
+    previous: first ? make({ id: first.id, order, direction: "previous" }) : undefined,
+    next: last ? make({ id: last.id, order, direction: "next" }) : undefined,
+  }
+}

packages/schema/src/sessions-query.ts

@@ -0,0 +1,125 @@
+export * as SessionsQuery from "./sessions-query.js"
+
+import { DateTime, Effect, Encoding, Result, Schema, SchemaGetter, Struct } from "effect"
+import { Project } from "./project.js"
+import { AbsolutePath, PositiveInt, RelativePath, statics } from "./schema.js"
+import { Session } from "./session.js"
+import { Workspace } from "./workspace.js"
+
+/**
+ * Shared session list query and cursor codec. Lives in schema so both the
+ * protocol session group and the core plugin host paginate identically.
+ */
+
+export const DefaultLimit = 50
+
+const ParentIDFilter = Schema.Union([
+  Session.ID,
+  Schema.Null.pipe(
+    Schema.encodeTo(Schema.Literal("null"), {
+      decode: SchemaGetter.transform(() => null),
+      encode: SchemaGetter.transform(() => "null" as const),
+    }),
+  ),
+]).annotate({
+  description: "Filter by parent session. Use null to return only root sessions.",
+})
+
+export const Fields = {
+  workspace: Workspace.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.",
+  }),
+  search: Schema.optional(Schema.String),
+  parentID: ParentIDFilter.pipe(Schema.optional),
+}
+
+const DirectoryQuery = Schema.Struct({
+  ...Fields,
+  directory: AbsolutePath,
+})
+
+const ProjectQuery = Schema.Struct({
+  ...Fields,
+  project: Project.ID,
+  subpath: RelativePath.pipe(Schema.optional),
+})
+
+const AllQuery = Schema.Struct(Fields)
+
+const withAnchor = <Fields extends Schema.Struct.Fields>(schema: Schema.Struct<Fields>) =>
+  schema.mapFields((fields) => ({
+    ...Struct.omit(fields, ["limit"]),
+    anchor: Session.ListAnchor,
+  }))
+
+const CursorInput = Schema.Union([withAnchor(DirectoryQuery), withAnchor(ProjectQuery), withAnchor(AllQuery)])
+const CursorJson = Schema.fromJsonString(CursorInput)
+const encodeCursor = Schema.encodeSync(CursorJson)
+const decodeCursor = Schema.decodeUnknownEffect(CursorJson)
+const invalidCursor = "Invalid cursor" as const
+
+type PageQuery = Omit<typeof Query.Type, "limit" | "cursor">
+
+export const Cursor = Schema.String.pipe(
+  Schema.brand("SessionsCursor"),
+  statics((schema) => {
+    const make = schema.make.bind(schema)
+    const makeCursor = (input: typeof CursorInput.Type) => make(Encoding.encodeBase64Url(encodeCursor(input)))
+    return {
+      make: makeCursor,
+      parse: (input: string) =>
+        Effect.suspend(() => {
+          const result = Encoding.decodeBase64UrlString(input)
+          return Result.isFailure(result)
+            ? Effect.fail(invalidCursor)
+            : decodeCursor(result.success).pipe(Effect.mapError(() => invalidCursor))
+        }),
+      /**
+       * previous/next cursors for one returned page, re-anchoring the
+       * originating query at the page's first and last items.
+       */
+      page: (query: PageQuery, data: ReadonlyArray<Session.Info>) => {
+        const first = data[0]
+        const last = data.at(-1)
+        return {
+          previous: first
+            ? makeCursor({
+                ...query,
+                anchor: {
+                  id: first.id,
+                  time: DateTime.toEpochMillis(first.time.updated),
+                  direction: "previous",
+                },
+              })
+            : undefined,
+          next: last
+            ? makeCursor({
+                ...query,
+                anchor: {
+                  id: last.id,
+                  time: DateTime.toEpochMillis(last.time.updated),
+                  direction: "next",
+                },
+              })
+            : undefined,
+        }
+      },
+    }
+  }),
+)
+export type Cursor = typeof Cursor.Type
+
+export const Query = Schema.Struct({
+  ...Fields,
+  directory: AbsolutePath.pipe(Schema.optional),
+  project: Project.ID.pipe(Schema.optional),
+  subpath: RelativePath.pipe(Schema.optional),
+  cursor: Cursor.annotate({
+    description: "Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response.",
+  }).pipe(Schema.optional),
+}).annotate({ identifier: "SessionsQuery" })
+export type Query = typeof Query.Type

packages/schema/test/sessions-query.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { SessionsQuery } from "../src/sessions-query.js"
+import { SessionMessagesCursor } from "../src/session-messages-cursor.js"
+import { SessionMessage } from "../src/session-message.js"
+import { Session } from "../src/session.js"
+
+describe("SessionsQuery.Cursor", () => {
+  test("round trips without Node globals", async () => {
+    const input = {
+      workspace: undefined,
+      search: "protocol",
+      order: "desc" as const,
+      anchor: { id: Session.ID.make("ses_test"), time: 1, direction: "next" as const },
+    }
+    const cursor = SessionsQuery.Cursor.make(input)
+
+    expect(await Effect.runPromise(SessionsQuery.Cursor.parse(cursor))).toEqual(input)
+  })
+})
+
+describe("SessionMessagesCursor", () => {
+  test("round trips", async () => {
+    const input = {
+      id: SessionMessage.ID.make("msg_test"),
+      order: "desc" as const,
+      direction: "next" as const,
+    }
+    const cursor = SessionMessagesCursor.make(input)
+
+    expect(await Effect.runPromise(SessionMessagesCursor.parse(cursor))).toEqual(input)
+  })
+})

packages/server/src/handlers/message.ts

@@ -1,29 +1,10 @@
-import { SessionMessage } from "@opencode-ai/core/session/message"
 import { Session } from "@opencode-ai/core/session"
-import { Effect, Schema } from "effect"
+import { SessionMessagesCursor } from "@opencode-ai/schema/session-messages-cursor"
+import { Effect } from "effect"
 import { HttpApiBuilder } from "effect/unstable/httpapi"
 import { Api } from "../api"
 import { InvalidCursorError, SessionNotFoundError, UnknownError } from "@opencode-ai/protocol/errors"
 
-const DefaultMessagesLimit = 50
-
-const Cursor = Schema.Struct({
-  id: SessionMessage.ID,
-  order: Schema.Union([Schema.Literal("asc"), Schema.Literal("desc")]),
-  direction: Schema.Union([Schema.Literal("previous"), Schema.Literal("next")]),
-})
-
-const decodeCursor = Schema.decodeUnknownSync(Cursor)
-
-const cursor = {
-  encode(message: SessionMessage.Info, order: "asc" | "desc", direction: "previous" | "next") {
-    return Buffer.from(JSON.stringify({ id: message.id, order, direction })).toString("base64url")
-  },
-  decode(input: string) {
-    return decodeCursor(JSON.parse(Buffer.from(input, "base64url").toString("utf8")))
-  },
-}
-
 export const MessageHandler = HttpApiBuilder.group(Api, "server.message", (handlers) =>
   Effect.gen(function* () {
     const session = yield* Session.Service
@@ -33,15 +14,16 @@ export const MessageHandler = HttpApiBuilder.group(Api, "server.message", (handl
       Effect.fn(function* (ctx) {
         if (ctx.query.cursor && ctx.query.order !== undefined)
           return yield* new InvalidCursorError({ message: "Cursor cannot be combined with order" })
-        const decoded = yield* Effect.try({
-          try: () => (ctx.query.cursor ? cursor.decode(ctx.query.cursor) : undefined),
-          catch: () => new InvalidCursorError({ message: "Invalid cursor" }),
-        })
+        const decoded = ctx.query.cursor
+          ? yield* SessionMessagesCursor.parse(ctx.query.cursor).pipe(
+              Effect.mapError(() => new InvalidCursorError({ message: "Invalid cursor" })),
+            )
+          : undefined
         const order = decoded?.order ?? ctx.query.order ?? "desc"
         const messages = yield* session
           .messages({
             sessionID: ctx.params.sessionID,
-            limit: ctx.query.limit ?? DefaultMessagesLimit,
+            limit: ctx.query.limit ?? SessionMessagesCursor.DefaultLimit,
             order,
             cursor: decoded ? { id: decoded.id, direction: decoded.direction } : undefined,
           })
@@ -66,14 +48,9 @@ export const MessageHandler = HttpApiBuilder.group(Api, "server.message", (handl
               )
             }),
           )
-        const first = messages[0]
-        const last = messages.at(-1)
         return {
           data: messages,
-          cursor: {
-            previous: first ? cursor.encode(first, order, "previous") : undefined,
-            next: last ? cursor.encode(last, order, "next") : undefined,
-          },
+          cursor: SessionMessagesCursor.page(messages, order),
         }
       }),
     )

packages/server/src/handlers/session.ts

@@ -3,7 +3,7 @@ import { InstructionEntry } from "@opencode-ai/core/session/instruction-entry"
 import { DateTime, Effect, Stream } from "effect"
 import { HttpApiBuilder, HttpApiSchema } from "effect/unstable/httpapi"
 import { Api } from "../api"
-import { SessionsCursor } from "@opencode-ai/protocol/groups/session"
+import { SessionsQuery } from "@opencode-ai/schema/sessions-query"
 import {
   ConflictError,
   CommandEvaluationError,
@@ -19,8 +19,6 @@ import {
 } from "@opencode-ai/protocol/errors"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 
-const DefaultSessionsLimit = 50
-
 export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handlers) =>
   Effect.gen(function* () {
     const session = yield* Session.Service
@@ -31,42 +29,18 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
         Effect.fn(function* (ctx) {
           const query =
             ctx.query.cursor !== undefined
-              ? yield* SessionsCursor.parse(ctx.query.cursor).pipe(
+              ? yield* SessionsQuery.Cursor.parse(ctx.query.cursor).pipe(
                   Effect.mapError(() => new InvalidCursorError({ message: "Invalid cursor" })),
                 )
               : ctx.query
           const page = yield* session.list({
             ...query,
             workspaceID: query.workspace,
-            limit: ctx.query.limit ?? DefaultSessionsLimit,
+            limit: ctx.query.limit ?? SessionsQuery.DefaultLimit,
           })
-          const sessions = page.data
-          const first = sessions[0]
-          const last = sessions.at(-1)
           return {
-            data: sessions,
-            cursor: {
-              previous: first
-                ? SessionsCursor.make({
-                    ...query,
-                    anchor: {
-                      id: first.id,
-                      time: DateTime.toEpochMillis(first.time.updated),
-                      direction: "previous",
-                    },
-                  })
-                : undefined,
-              next: last
-                ? SessionsCursor.make({
-                    ...query,
-                    anchor: {
-                      id: last.id,
-                      time: DateTime.toEpochMillis(last.time.updated),
-                      direction: "next",
-                    },
-                  })
-                : undefined,
-            },
+            data: page.data,
+            cursor: SessionsQuery.Cursor.page(query, page.data),
           }
         }),
       )
@@ -77,6 +51,7 @@ export const SessionHandler = HttpApiBuilder.group(Api, "server.session", (handl
             data: yield* session
               .create({
                 id: ctx.payload.id,
+                title: ctx.payload.title,
                 agent: ctx.payload.agent,
                 model: ctx.payload.model,
                 location: ctx.payload.location ?? { directory: AbsolutePath.make(process.cwd()) },

packages/tui/src/component/dialog-open.tsx

@@ -37,8 +37,8 @@ export function DialogOpen() {
   const dimensions = useTerminalDimensions()
   const shortcuts = Keymap.useShortcuts()
   const [filter, setFilter] = createSignal("")
+  const [selectionMoved, setSelectionMoved] = createSignal(false)
 
-  data.project.invalidate()
   void data.project.sync().catch(() => {})
 
   // One background fetch fills in recent sessions from other projects; the menu renders
@@ -52,8 +52,12 @@ export function DialogOpen() {
     { initialValue: [] },
   )
 
-  const openTabs = createMemo(() => new Set(sessionTabs.tabs().map((tab) => tab.sessionID)))
-  const currentSessionID = createMemo(() => (route.data.type === "session" ? route.data.sessionID : undefined))
+  const openTabs = createMemo(
+    () => new Set(sessionTabs.enabled() ? sessionTabs.tabs().map((tab) => tab.sessionID) : []),
+  )
+  const currentSessionID = createMemo(() =>
+    route.data.type === "session" ? data.session.root(route.data.sessionID) : undefined,
+  )
   const sessions = createMemo(() => {
     const seen = new Set<string>()
     return [...data.session.list(), ...fetched()]
@@ -69,7 +73,7 @@ export function DialogOpen() {
     const tabs = openTabs()
     // With an empty query the menu shows what is not already one keystroke away: open tabs are
     // visible in the strip, so recents exclude them. Typing widens the pool to every session so
-    // matching a tab by name still switches to it.
+    // matching a loaded tab by name still switches to it.
     const recent = filter().trim()
       ? sessions()
       : sessions()
@@ -78,7 +82,9 @@ export function DialogOpen() {
     const sessionOptions = recent.map((session) => {
       const project = data.project.get(session.projectID)
       const name = project?.canonical === "/" ? undefined : project?.name || path.basename(project?.canonical ?? "")
-      const running = data.session.family(session.id).some((id) => data.session.status(id) === "running")
+      const running =
+        data.session.status(session.id) === "running" ||
+        data.session.family(session.id).some((id) => data.session.status(id) === "running")
       return {
         title: withTimestampedFallback(session),
         value: { type: "session", sessionID: session.id } as OpenTarget,
@@ -98,7 +104,7 @@ export function DialogOpen() {
     const projectOptions = data.project
       .list()
       .filter((project) => {
-        if (project.canonical === "/" || project.id === current?.id || seen.has(project.canonical)) return false
+        if (project.canonical === "/" || seen.has(project.canonical)) return false
         seen.add(project.canonical)
         return true
       })
@@ -113,6 +119,10 @@ export function DialogOpen() {
           searchText: footer,
           value: { type: "project", directory: project.canonical } as OpenTarget,
           category: "Projects",
+          gutter:
+            project.canonical === current?.canonical
+              ? () => <text fg={theme.text.formfield.selected}>●</text>
+              : undefined,
         }
       })
 
@@ -128,6 +138,8 @@ export function DialogOpen() {
       options={options()}
       current={currentSessionID() ? ({ type: "session", sessionID: currentSessionID()! } as OpenTarget) : undefined}
       focusCurrent={false}
+      preserveSelection={selectionMoved()}
+      onMove={() => setSelectionMoved(true)}
       onFilter={setFilter}
       noMatchView={
         <box paddingLeft={4} paddingRight={4}>

packages/tui/src/component/dialog-session-list.tsx

@@ -89,7 +89,8 @@ export function DialogSessionList() {
   const sessions = createMemo(() => {
     const query = filter().trim()
     const local = localSessions()
-    if (query !== search().trim() || searchResults.loading) return searchResults.latest?.sessions ?? local
+    if (query !== search().trim()) return searchResults.latest?.sessions ?? local
+    if (searchResults.loading) return searchResults.latest?.sessions ?? []
     const result = searchResults()
     if (result?.query !== query || result.allProjects !== allProjects() || result.error) return local
     return result.sessions
@@ -154,11 +155,13 @@ export function DialogSessionList() {
         footer,
         bg: deleting ? theme.background.action.destructive.focused : undefined,
         fg: deleting ? theme.text.action.destructive.focused : undefined,
-        gutter: data.session.family(session.id).some((id) => data.session.status(id) === "running")
-          ? () => <Spinner />
-          : slot === undefined
-            ? undefined
-            : () => <text fg={theme.hue.accent[mode() === "light" ? 800 : 200]}>{slot}</text>,
+        gutter:
+          data.session.status(session.id) === "running" ||
+          data.session.family(session.id).some((id) => data.session.status(id) === "running")
+            ? () => <Spinner />
+            : slot === undefined
+              ? undefined
+              : () => <text fg={theme.hue.accent[mode() === "light" ? 800 : 200]}>{slot}</text>,
       }
     }
 

packages/tui/src/ui/dialog-select.tsx

@@ -245,7 +245,7 @@ export function DialogSelect<T>(props: DialogSelectProps<T>) {
     on(
       () => props.options,
       () => {
-        if (!props.preserveSelection && props.current === undefined) {
+        if (!props.preserveSelection && (props.current === undefined || props.focusCurrent === false)) {
           const count = flat().length
           if (count === 0) return
           const next = reconcileSelection(store.selected, count)
@@ -281,7 +281,11 @@ export function DialogSelect<T>(props: DialogSelectProps<T>) {
           setStore("selected", index)
           selection = option
           if (!moved) return
-          if ((!props.preserveSelection && props.current === undefined) || store.filter.length > 0) return
+          if (
+            (!props.preserveSelection && (props.current === undefined || props.focusCurrent === false)) ||
+            store.filter.length > 0
+          )
+            return
           scrollAfterLayout(false, option.value)
           return
         }

packages/tui/test/cli/tui/data.test.tsx

@@ -106,11 +106,18 @@ test("does not preload session summaries into the data context", async () => {
   }
 })
 
-test("proactively syncs project metadata", async () => {
+test("proactively syncs project metadata newest first", async () => {
   const events = createEventStream()
   const calls = createFetch((url) => {
     if (url.pathname !== "/api/project") return
     return json([
+      {
+        id: "proj_old",
+        canonical: "/old/project",
+        name: "Old project",
+        time: { created: 1, updated: 1 },
+        sandboxes: [],
+      },
       {
         id: "proj_test",
         canonical: worktree,
@@ -149,6 +156,13 @@ test("proactively syncs project metadata", async () => {
         time: { created: 1, updated: 2 },
         sandboxes: [],
       },
+      {
+        id: "proj_old",
+        canonical: "/old/project",
+        name: "Old project",
+        time: { created: 1, updated: 1 },
+        sandboxes: [],
+      },
     ])
   } finally {
     app.renderer.destroy()

packages/tui/test/cli/tui/dialog-open.test.tsx

@@ -18,16 +18,14 @@ import { StorageProvider } from "../../../src/context/storage"
 import { ThemeProvider } from "../../../src/context/theme"
 import { DialogProvider, useDialog } from "../../../src/ui/dialog"
 import { ToastProvider } from "../../../src/ui/toast"
-import { createApi, createEventStream, createFetch, json } from "../../fixture/tui-client"
+import { createApi, createEventStream, createFetch, json, type FetchHandler } from "../../fixture/tui-client"
 import { TestTuiContexts } from "../../fixture/tui-environment"
 import { createTuiResolvedConfig } from "../../fixture/tui-runtime"
 
 test("selecting an unhydrated session preserves its location", async () => {
-  const state = mkdtempSync(path.join(tmpdir(), "opencode-dialog-open-"))
-  const events = createEventStream()
   const remote = { directory: "/tmp/opencode/remote", workspaceID: "ws_remote" }
-  const calls = createFetch((url) => {
-    if (url.pathname !== "/api/session") return
+  const fixture = await renderOpen((url) => {
+    if (url.pathname !== "/api/session") return undefined
     return json({
       data: [
         {
@@ -42,7 +40,129 @@ test("selecting an unhydrated session preserves its location", async () => {
       ],
       cursor: {},
     })
-  }, events)
+  })
+
+  try {
+    await fixture.app.waitForFrame((frame) => frame.includes("Remote session"))
+    expect(fixture.data.session.get("ses_remote")).toBeUndefined()
+
+    fixture.app.mockInput.pressEnter()
+    await fixture.app.waitFor(() => fixture.route.data.type === "session")
+
+    expect(fixture.route.data).toEqual({ type: "session", sessionID: "ses_remote" })
+    expect(fixture.location.ref).toEqual(remote)
+  } finally {
+    fixture.dispose()
+  }
+})
+
+test("shows the current project and opens its root", async () => {
+  const root = "/tmp/opencode/project"
+  const subfolder = `${root}/packages/tui`
+  const fixture = await renderOpen(
+    (url) => {
+      if (url.pathname === "/api/project")
+        return json([
+          {
+            id: "proj_current",
+            canonical: root,
+            name: "OpenCode",
+            time: { created: 1, updated: 2 },
+            sandboxes: [],
+          },
+        ])
+      if (url.pathname === "/api/location")
+        return json({
+          directory: subfolder,
+          project: { id: "proj_current", directory: root, canonical: root },
+        })
+      return undefined
+    },
+    async ({ data, location }) => {
+      await data.location.sync({ directory: subfolder })
+      location.set({ directory: subfolder })
+    },
+  )
+
+  try {
+    const frame = await fixture.app.waitForFrame((value) => value.includes("OpenCode") && value.includes("●"))
+    expect(frame).toContain(root)
+
+    fixture.app.mockInput.pressEnter()
+    await fixture.app.waitFor(() => fixture.route.data.type === "home")
+
+    expect(fixture.route.data).toEqual({ type: "home", location: { directory: root } })
+    expect(fixture.location.ref).toEqual({ directory: root })
+  } finally {
+    fixture.dispose()
+  }
+})
+
+test("preserves a moved project when sessions arrive", async () => {
+  let resolveSessions!: (response: Response) => void
+  const sessions = new Promise<Response>((resolve) => (resolveSessions = resolve))
+  const fixture = await renderOpen((url) => {
+    if (url.pathname === "/api/session") return sessions
+    if (url.pathname === "/api/project")
+      return json([
+        {
+          id: "proj_first",
+          canonical: "/tmp/opencode/first",
+          name: "First project",
+          time: { created: 1, updated: 2 },
+          sandboxes: [],
+        },
+        {
+          id: "proj_second",
+          canonical: "/tmp/opencode/second",
+          name: "Second project",
+          time: { created: 1, updated: 1 },
+          sandboxes: [],
+        },
+      ])
+    return undefined
+  })
+
+  try {
+    await fixture.app.waitForFrame((frame) => frame.includes("Second project"))
+    fixture.app.mockInput.pressArrow("down")
+
+    resolveSessions(
+      json({
+        data: [
+          {
+            id: "ses_recent",
+            projectID: "proj_first",
+            cost: 0,
+            tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+            time: { created: 2, updated: 3 },
+            title: "Recent session",
+            location: { directory: "/tmp/opencode/first" },
+          },
+        ],
+        cursor: {},
+      }),
+    )
+    await fixture.app.waitForFrame((frame) => frame.includes("Recent session"))
+    fixture.app.mockInput.pressEnter()
+    await fixture.app.waitFor(() => fixture.route.data.type === "home")
+
+    expect(fixture.route.data).toEqual({ type: "home", location: { directory: "/tmp/opencode/second" } })
+  } finally {
+    fixture.dispose()
+  }
+})
+
+async function renderOpen(
+  handler: FetchHandler,
+  beforeOpen?: (contexts: {
+    data: ReturnType<typeof useData>
+    location: ReturnType<typeof useLocation>
+  }) => void | Promise<void>,
+) {
+  const state = mkdtempSync(path.join(tmpdir(), "opencode-dialog-open-"))
+  const events = createEventStream()
+  const calls = createFetch(handler, events)
   let route!: ReturnType<typeof useRoute>
   let location!: ReturnType<typeof useLocation>
   let data!: ReturnType<typeof useData>
@@ -52,7 +172,9 @@ test("selecting an unhydrated session preserves its location", async () => {
     route = useRoute()
     location = useLocation()
     data = useData()
-    onMount(() => dialog.replace(() => <DialogOpen />))
+    onMount(
+      () => void Promise.resolve(beforeOpen?.({ data, location })).then(() => dialog.replace(() => <DialogOpen />)),
+    )
     return null
   }
 
@@ -90,17 +212,20 @@ test("selecting an unhydrated session preserves its location", async () => {
   )
   app.renderer.start()
 
-  try {
-    await app.waitForFrame((frame) => frame.includes("Remote session"))
-    expect(data.session.get("ses_remote")).toBeUndefined()
-
-    app.mockInput.pressEnter()
-    await app.waitFor(() => route.data.type === "session")
-
-    expect(route.data).toEqual({ type: "session", sessionID: "ses_remote" })
-    expect(location.ref).toEqual(remote)
-  } finally {
-    app.renderer.destroy()
-    rmSync(state, { recursive: true, force: true })
+  return {
+    app,
+    get route() {
+      return route
+    },
+    get location() {
+      return location
+    },
+    get data() {
+      return data
+    },
+    dispose() {
+      app.renderer.destroy()
+      rmSync(state, { recursive: true, force: true })
+    },
   }
-})
+}

packages/tui/test/cli/tui/dialog-select.test.tsx

@@ -82,7 +82,12 @@ async function renderSelect(
   return app
 }
 
-async function mountSelect(root: string, initial: DialogSelectOption<string>[], current?: string) {
+async function mountSelect(
+  root: string,
+  initial: DialogSelectOption<string>[],
+  current?: string,
+  focusCurrent?: boolean,
+) {
   const state = path.join(root, "state")
   await mkdir(state, { recursive: true })
   const config = createTuiResolvedConfig()
@@ -118,6 +123,7 @@ async function mountSelect(root: string, initial: DialogSelectOption<string>[],
             title="Mutable options"
             options={options()}
             current={current}
+            focusCurrent={focusCurrent}
             onMove={(option) => moved.push(option.value)}
             onSelect={(option) => selected.push(option.value)}
           />
@@ -352,3 +358,24 @@ test("keeps the current option selected when options reorder", async () => {
     select.app.renderer.destroy()
   }
 })
+
+test("keeps the first row selected when current is only a marker", async () => {
+  await using tmp = await tmpdir()
+  const project = { title: "project", value: "project" }
+  const select = await mountSelect(tmp.path, [project], "current", false)
+
+  try {
+    select.replaceOptions([
+      { title: "recent session", value: "recent" },
+      project,
+      { title: "current session", value: "current" },
+    ])
+    await select.app.waitForFrame((frame) => frame.includes("recent session"))
+    select.app.mockInput.pressEnter()
+    await select.app.waitFor(() => select.selected.length === 1)
+
+    expect(select.selected).toEqual(["recent"])
+  } finally {
+    select.app.renderer.destroy()
+  }
+})

packages/www/content/docs/build/plugins.mdx

@@ -177,7 +177,7 @@ and plugin options.
 | `ctx.integration`      | `list`, `get`, `connect`, `attempt`, `transform`, `reload`, and connection lookup/resolution |
 | `ctx.plugin`           | `list` currently active plugin IDs                                                           |
 | `ctx.reference`        | `list`, `transform`, `reload`                                                                |
-| `ctx.session`          | `create`, `get`, `prompt`, `command`, `synthetic`, `interrupt`, and `hook`                   |
+| `ctx.session`          | `create`, `get`, `list`, `messages`, `prompt`, `command`, `rename`, `synthetic`, `interrupt`, `wait`, and `hook` |
 | `ctx.skill`            | `list`, `transform`, `reload`                                                                |
 | `ctx.tool`             | `transform` and `hook`                                                                       |
 | `ctx.aisdk`            | `hook`                                                                                       |