@neurocode-ai/protocol 1.18.9

package/package.json

@@ -0,0 +1,22 @@
+{
+    "$schema":  "https://json.schemastore.org/package.json",
+    "name":  "@neurocode-ai/protocol",
+    "type":  "module",
+    "license":  "MIT",
+    "exports":  {
+                    "./*":  "./src/*.ts"
+                },
+    "scripts":  {
+                    "typecheck":  "tsgo --noEmit"
+                },
+    "dependencies":  {
+                         "@neurocode-ai/schema":  "workspace:*",
+                         "effect":  "catalog:"
+                     },
+    "devDependencies":  {
+                            "@tsconfig/bun":  "catalog:",
+                            "@types/bun":  "catalog:",
+                            "@typescript/native-preview":  "catalog:"
+                        },
+    "version":  "1.18.9"
+}

package/src/api.ts

@@ -0,0 +1,86 @@
+import { Context } from "effect"
+import { HttpApi, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi"
+import { SchemaErrorMiddleware } from "./middleware/schema-error"
+import { MessageGroup } from "./groups/message"
+import { ModelGroup } from "./groups/model"
+import { ProviderGroup } from "./groups/provider"
+import { makeSessionGroup } from "./groups/session"
+import { makePermissionGroup } from "./groups/permission"
+import { FileSystemGroup } from "./groups/fs"
+import { CommandGroup } from "./groups/command"
+import { SkillGroup } from "./groups/skill"
+import { EventGroup, makeEventGroup } from "./groups/event"
+import type { Definition } from "@neurocode-ai/schema/event"
+import { AgentGroup } from "./groups/agent"
+import { HealthGroup } from "./groups/health"
+import { PtyGroup } from "./groups/pty"
+import { makeQuestionGroup } from "./groups/question"
+import { ReferenceGroup } from "./groups/reference"
+import { Authorization } from "./middleware/authorization"
+import { LocationGroup } from "./groups/location"
+import { IntegrationGroup } from "./groups/integration"
+import { CredentialGroup } from "./groups/credential"
+import { ProjectCopyGroup } from "./groups/project-copy"
+
+// Protocol owns middleware placement, while Server injects concrete keys so Core service identities stay downstream.
+const makeApiFromGroup = <
+  const Group extends HttpApiGroup.Any,
+  LocationId extends HttpApiMiddleware.AnyId,
+  LocationService,
+  SessionLocationId extends HttpApiMiddleware.AnyId,
+  SessionLocationService,
+>(
+  eventGroup: Group,
+  locationMiddleware: Context.Key<LocationId, LocationService>,
+  sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>,
+) =>
+  HttpApi.make("server")
+    .add(HealthGroup)
+    .add(LocationGroup.middleware(locationMiddleware))
+    .add(AgentGroup.middleware(locationMiddleware))
+    .add(makeSessionGroup(sessionLocationMiddleware))
+    .add(MessageGroup.middleware(sessionLocationMiddleware))
+    .add(ModelGroup.middleware(locationMiddleware))
+    .add(ProviderGroup.middleware(locationMiddleware))
+    .add(IntegrationGroup.middleware(locationMiddleware))
+    .add(CredentialGroup.middleware(locationMiddleware))
+    .add(makePermissionGroup(locationMiddleware, sessionLocationMiddleware))
+    .add(FileSystemGroup.middleware(locationMiddleware))
+    .add(CommandGroup.middleware(locationMiddleware))
+    .add(SkillGroup.middleware(locationMiddleware))
+    .add(eventGroup)
+    .add(PtyGroup.middleware(locationMiddleware))
+    .add(makeQuestionGroup(locationMiddleware, sessionLocationMiddleware))
+    .add(ReferenceGroup.middleware(locationMiddleware))
+    .add(ProjectCopyGroup.middleware(locationMiddleware))
+    .annotateMerge(
+      OpenApi.annotations({
+        title: "neurocode HttpApi",
+        version: "0.0.1",
+        description: "Experimental HttpApi surface for selected instance routes.",
+      }),
+    )
+    .middleware(Authorization)
+    .middleware(SchemaErrorMiddleware)
+
+export const makeApi = <
+  LocationId extends HttpApiMiddleware.AnyId,
+  LocationService,
+  SessionLocationId extends HttpApiMiddleware.AnyId,
+  SessionLocationService,
+>(options: {
+  readonly definitions: ReadonlyArray<Definition>
+  readonly locationMiddleware: Context.Key<LocationId, LocationService>
+  readonly sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>
+}) =>
+  makeApiFromGroup(makeEventGroup(options.definitions), options.locationMiddleware, options.sessionLocationMiddleware)
+
+export const makeDefaultApi = <
+  LocationId extends HttpApiMiddleware.AnyId,
+  LocationService,
+  SessionLocationId extends HttpApiMiddleware.AnyId,
+  SessionLocationService,
+>(options: {
+  readonly locationMiddleware: Context.Key<LocationId, LocationService>
+  readonly sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>
+}) => makeApiFromGroup(EventGroup, options.locationMiddleware, options.sessionLocationMiddleware)

package/src/errors.ts

@@ -0,0 +1,111 @@
+import { Schema } from "effect"
+
+export class InvalidRequestError extends Schema.TaggedErrorClass<InvalidRequestError>()(
+  "InvalidRequestError",
+  {
+    message: Schema.String,
+    kind: Schema.optional(Schema.String),
+    field: Schema.optional(Schema.String),
+  },
+  { httpApiStatus: 400 },
+) {}
+
+export class UnauthorizedError extends Schema.TaggedErrorClass<UnauthorizedError>()(
+  "UnauthorizedError",
+  { message: Schema.String },
+  { httpApiStatus: 401 },
+) {}
+
+export class ConflictError extends Schema.TaggedErrorClass<ConflictError>()(
+  "ConflictError",
+  {
+    message: Schema.String,
+    resource: Schema.optional(Schema.String),
+  },
+  { httpApiStatus: 409 },
+) {}
+
+export class ServiceUnavailableError extends Schema.TaggedErrorClass<ServiceUnavailableError>()(
+  "ServiceUnavailableError",
+  {
+    message: Schema.String,
+    service: Schema.optional(Schema.String),
+  },
+  { httpApiStatus: 503 },
+) {}
+
+export class UnknownError extends Schema.TaggedErrorClass<UnknownError>()(
+  "UnknownError",
+  {
+    message: Schema.String,
+    ref: Schema.optional(Schema.String),
+  },
+  { httpApiStatus: 500 },
+) {}
+
+export class ProviderNotFoundError extends Schema.TaggedErrorClass<ProviderNotFoundError>()(
+  "ProviderNotFoundError",
+  {
+    providerID: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}
+
+export class SessionNotFoundError extends Schema.TaggedErrorClass<SessionNotFoundError>()(
+  "SessionNotFoundError",
+  {
+    sessionID: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}
+
+export class MessageNotFoundError extends Schema.TaggedErrorClass<MessageNotFoundError>()(
+  "MessageNotFoundError",
+  {
+    sessionID: Schema.String,
+    messageID: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}
+
+export class InvalidCursorError extends Schema.TaggedErrorClass<InvalidCursorError>()(
+  "InvalidCursorError",
+  { message: Schema.String },
+  { httpApiStatus: 400 },
+) {}
+
+export class PermissionNotFoundError extends Schema.TaggedErrorClass<PermissionNotFoundError>()(
+  "PermissionNotFoundError",
+  {
+    requestID: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}
+
+export class QuestionNotFoundError extends Schema.TaggedErrorClass<QuestionNotFoundError>()(
+  "QuestionNotFoundError",
+  {
+    requestID: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}
+
+export class ForbiddenError extends Schema.TaggedErrorClass<ForbiddenError>()(
+  "ForbiddenError",
+  { message: Schema.String },
+  { httpApiStatus: 403 },
+) {}
+
+export class PtyNotFoundError extends Schema.TaggedErrorClass<PtyNotFoundError>()(
+  "PtyNotFoundError",
+  {
+    ptyID: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}

package/src/groups/agent.ts

@@ -0,0 +1,20 @@
+import { Agent } from "@neurocode-ai/schema/agent"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const AgentGroup = HttpApiGroup.make("server.agent").add(
+  HttpApiEndpoint.get("agent.list", "/api/agent", {
+    query: LocationQuery,
+    success: Location.response(Schema.Array(Agent.Info)),
+  })
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(
+      OpenApi.annotations({
+        identifier: "v2.agent.list",
+        summary: "List agents",
+        description: "Retrieve currently registered agents.",
+      }),
+    ),
+)

package/src/groups/command.ts

@@ -0,0 +1,27 @@
+import { Command } from "@neurocode-ai/schema/command"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const CommandGroup = HttpApiGroup.make("server.command")
+  .add(
+    HttpApiEndpoint.get("command.list", "/api/command", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Command.Info)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.command.list",
+          summary: "List commands",
+          description: "Retrieve currently registered commands.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "commands",
+      description: "Experimental command routes.",
+    }),
+  )

package/src/groups/credential.ts

@@ -0,0 +1,37 @@
+import { Credential } from "@neurocode-ai/schema/credential"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const CredentialGroup = HttpApiGroup.make("server.credential")
+  .add(
+    HttpApiEndpoint.patch("credential.update", "/api/credential/:credentialID", {
+      params: { credentialID: Credential.ID },
+      query: LocationQuery,
+      payload: Schema.Struct({ label: Schema.String }),
+      success: HttpApiSchema.NoContent,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.credential.update",
+          summary: "Update credential",
+          description: "Update a stored credential label.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.delete("credential.remove", "/api/credential/:credentialID", {
+      params: { credentialID: Credential.ID },
+      query: LocationQuery,
+      success: HttpApiSchema.NoContent,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.credential.remove",
+          summary: "Remove credential",
+          description: "Remove a stored integration credential.",
+        }),
+      ),
+  )

package/src/groups/event.ts

@@ -0,0 +1,56 @@
+import { Event } from "@neurocode-ai/schema/event"
+import { EventManifest } from "@neurocode-ai/schema/event-manifest"
+import { Location } from "@neurocode-ai/schema/location"
+import type { Definition } from "@neurocode-ai/schema/event"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+
+const fields = {
+  id: Event.ID,
+  metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  durable: Schema.optional(Schema.Struct({ aggregateID: Schema.String, seq: Schema.Int, version: Schema.Int })),
+  location: Schema.optional(Location.Ref),
+}
+
+const schema = <const Definitions extends ReadonlyArray<Definition>>(definitions: Definitions) =>
+  Schema.Union([
+    ...definitions,
+    ...(definitions.some((definition) => definition.type === "server.connected")
+      ? []
+      : [
+          Schema.Struct({
+            ...fields,
+            type: Schema.Literal("server.connected"),
+            data: Schema.Struct({}),
+          }).annotate({ identifier: "V2Event.server.connected" }),
+        ]),
+  ]).annotate({ identifier: "V2Event" })
+
+const make = <const Definitions extends ReadonlyArray<Definition>>(definitions: Definitions) => {
+  const EventSchema = schema(definitions)
+  return {
+    schema: EventSchema,
+    group: HttpApiGroup.make("server.event")
+      .add(
+        HttpApiEndpoint.get("event.subscribe", "/api/event", {
+          success: HttpApiSchema.StreamSse({ data: EventSchema }),
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.event.subscribe",
+            summary: "Subscribe to events",
+            description: "Subscribe to native event payloads for the server.",
+          }),
+        ),
+      )
+      .annotateMerge(OpenApi.annotations({ title: "events", description: "Experimental event stream route." })),
+  }
+}
+
+export const makeEventGroup = <const Definitions extends ReadonlyArray<Definition>>(definitions: Definitions) =>
+  make(definitions).group
+
+const event = make(EventManifest.ServerDefinitions)
+export const EventGroup = event.group
+export const OpenCodeEvent = event.schema
+export type OpenCodeEvent = typeof OpenCodeEvent.Type
+export type OpenCodeEventEncoded = typeof OpenCodeEvent.Encoded

package/src/groups/fs.ts

@@ -0,0 +1,68 @@
+import { FileSystem } from "@neurocode-ai/schema/filesystem"
+import { Location } from "@neurocode-ai/schema/location"
+import { PositiveInt, RelativePath } from "@neurocode-ai/schema/schema"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+const ListQuery = Schema.Struct({
+  ...LocationQuery.fields,
+  path: RelativePath.pipe(Schema.optional),
+})
+
+const FindQuery = Schema.Struct({
+  ...LocationQuery.fields,
+  query: FileSystem.FindInput.fields.query,
+  type: FileSystem.FindInput.fields.type,
+  limit: Schema.NumberFromString.pipe(Schema.decodeTo(PositiveInt), Schema.optional),
+})
+
+export const FileSystemGroup = HttpApiGroup.make("server.fs")
+  .add(
+    HttpApiEndpoint.get("fs.read", "/api/fs/read/*", {
+      query: LocationQuery,
+      success: Schema.Uint8Array.pipe(HttpApiSchema.asUint8Array()),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.fs.read",
+          summary: "Read file",
+          description: "Serve one file relative to the requested location.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.get("fs.list", "/api/fs/list", {
+      query: ListQuery,
+      success: Location.response(Schema.Array(FileSystem.Entry)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.fs.list",
+          summary: "List directory",
+          description: "List direct children of one directory relative to the requested location.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.get("fs.find", "/api/fs/find", {
+      query: FindQuery,
+      success: Location.response(Schema.Array(FileSystem.Entry)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.fs.find",
+          summary: "Find files",
+          description: "Find recursively ranked filesystem entries relative to the requested location.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "filesystem",
+      description: "Experimental location-scoped filesystem routes.",
+    }),
+  )

package/src/groups/health.ts

@@ -0,0 +1,14 @@
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+
+export const HealthGroup = HttpApiGroup.make("server.health").add(
+  HttpApiEndpoint.get("health.get", "/api/health", {
+    success: Schema.Struct({ healthy: Schema.Literal(true) }),
+  }).annotateMerge(
+    OpenApi.annotations({
+      identifier: "v2.health.get",
+      summary: "Check server health",
+      description: "Check whether the API server is ready to accept requests.",
+    }),
+  ),
+)

package/src/groups/integration.ts

@@ -0,0 +1,130 @@
+import { Integration } from "@neurocode-ai/schema/integration"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { InvalidRequestError } from "../errors"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+const Inputs = Schema.Record(Schema.String, Schema.String)
+
+export const IntegrationGroup = HttpApiGroup.make("server.integration")
+  .add(
+    HttpApiEndpoint.get("integration.list", "/api/integration", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Integration.Info)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.list",
+          summary: "List integrations",
+          description: "Retrieve available integrations and their authentication methods.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.get("integration.get", "/api/integration/:integrationID", {
+      params: { integrationID: Integration.ID },
+      query: LocationQuery,
+      success: Location.response(Schema.UndefinedOr(Integration.Info)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.get",
+          summary: "Get integration",
+          description: "Retrieve one integration and its authentication methods.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("integration.connect.key", "/api/integration/:integrationID/connect/key", {
+      params: { integrationID: Integration.ID },
+      query: LocationQuery,
+      payload: Schema.Struct({
+        key: Schema.String,
+        label: Schema.optional(Schema.String),
+      }),
+      success: HttpApiSchema.NoContent,
+      error: InvalidRequestError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.connect.key",
+          summary: "Connect with key",
+          description: "Run a key authentication method and store the resulting credential.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("integration.connect.oauth", "/api/integration/:integrationID/connect/oauth", {
+      params: { integrationID: Integration.ID },
+      query: LocationQuery,
+      payload: Schema.Struct({
+        methodID: Integration.MethodID,
+        inputs: Inputs,
+        label: Schema.optional(Schema.String),
+      }),
+      success: Location.response(Integration.Attempt),
+      error: InvalidRequestError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.connect.oauth",
+          summary: "Begin OAuth connection",
+          description: "Start an OAuth attempt and return the authorization details.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.get("integration.attempt.status", "/api/integration/attempt/:attemptID", {
+      params: { attemptID: Integration.AttemptID },
+      query: LocationQuery,
+      success: Location.response(Integration.AttemptStatus),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.attempt.status",
+          summary: "Get OAuth attempt status",
+          description: "Poll the current status of an OAuth attempt.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("integration.attempt.complete", "/api/integration/attempt/:attemptID/complete", {
+      params: { attemptID: Integration.AttemptID },
+      query: LocationQuery,
+      payload: Schema.Struct({ code: Schema.optional(Schema.String) }),
+      success: HttpApiSchema.NoContent,
+      error: InvalidRequestError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.attempt.complete",
+          summary: "Complete OAuth connection",
+          description: "Complete a code-based OAuth attempt and store the resulting credential.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.delete("integration.attempt.cancel", "/api/integration/attempt/:attemptID", {
+      params: { attemptID: Integration.AttemptID },
+      query: LocationQuery,
+      success: HttpApiSchema.NoContent,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.integration.attempt.cancel",
+          summary: "Cancel OAuth connection",
+          description: "Cancel an OAuth attempt and release its resources.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({ title: "integrations", description: "Integration discovery and authentication routes." }),
+  )

package/src/groups/location.ts

@@ -0,0 +1,42 @@
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+
+export const LocationQuery = Schema.Struct({
+  location: Schema.optional(
+    Schema.Struct({
+      directory: Schema.optional(Schema.String),
+      workspace: Schema.optional(Schema.String),
+    }),
+  ),
+}).annotate({ identifier: "LocationQuery" })
+
+export const locationQueryOpenApi = OpenApi.annotations({
+  transform: (operation) => {
+    const parameters = operation.parameters
+    if (!Array.isArray(parameters)) return operation
+    return {
+      ...operation,
+      parameters: parameters.map((parameter) =>
+        parameter?.name === "location" && parameter?.in === "query"
+          ? { ...parameter, style: "deepObject", explode: true }
+          : parameter,
+      ),
+    }
+  },
+})
+
+export const LocationGroup = HttpApiGroup.make("server.location").add(
+  HttpApiEndpoint.get("location.get", "/api/location", {
+    query: LocationQuery,
+    success: Location.Info,
+  })
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(
+      OpenApi.annotations({
+        identifier: "v2.location.get",
+        summary: "Get location",
+        description: "Resolve the requested location or the server default location.",
+      }),
+    ),
+)

package/src/groups/message.ts

@@ -0,0 +1,51 @@
+import { Session } from "@neurocode-ai/schema/session"
+import { SessionMessage } from "@neurocode-ai/schema/session-message"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { InvalidCursorError, SessionNotFoundError, UnknownError } from "../errors"
+
+export const SessionMessagesQuery = Schema.Struct({
+  limit: Schema.optional(
+    Schema.NumberFromString.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(200)),
+  ).annotate({
+    description: "Maximum number of messages to return. When omitted, the endpoint returns its default page size.",
+  }),
+  order: Schema.optional(Schema.Union([Schema.Literal("asc"), Schema.Literal("desc")])).annotate({
+    description: "Message order for the first page. Use desc for newest first or asc for oldest first.",
+  }),
+  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.",
+    }),
+  ),
+}).annotate({ identifier: "SessionMessagesQuery" })
+
+export const MessageGroup = HttpApiGroup.make("server.message")
+  .add(
+    HttpApiEndpoint.get("session.messages", "/api/session/:sessionID/message", {
+      params: { sessionID: Session.ID },
+      query: SessionMessagesQuery,
+      success: Schema.Struct({
+        data: Schema.Array(SessionMessage.Message),
+        cursor: Schema.Struct({
+          previous: Schema.String.pipe(Schema.optional),
+          next: Schema.String.pipe(Schema.optional),
+        }),
+      }).annotate({ identifier: "SessionMessagesResponse" }),
+      error: [InvalidCursorError, SessionNotFoundError, UnknownError],
+    }).annotateMerge(
+      OpenApi.annotations({
+        identifier: "v2.session.messages",
+        summary: "Get session messages",
+        description:
+          "Retrieve projected messages for a session. Items keep the requested order across pages; use cursor.next or cursor.previous to move through the ordered timeline.",
+      }),
+    ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "messages",
+      description: "Experimental message routes.",
+    }),
+  )