@neurocode-ai/protocol 1.18.9

package/src/groups/model.ts

@@ -0,0 +1,29 @@
+import { Model } from "@neurocode-ai/schema/model"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { ServiceUnavailableError } from "../errors"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const ModelGroup = HttpApiGroup.make("server.model")
+  .add(
+    HttpApiEndpoint.get("model.list", "/api/model", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Model.Info)),
+      error: ServiceUnavailableError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.model.list",
+          summary: "List models",
+          description: "Retrieve available models ordered by release date.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "models",
+      description: "Experimental model routes.",
+    }),
+  )

package/src/groups/permission.ts

@@ -0,0 +1,137 @@
+import { Agent } from "@neurocode-ai/schema/agent"
+import { Location } from "@neurocode-ai/schema/location"
+import { Permission } from "@neurocode-ai/schema/permission"
+import { PermissionSaved } from "@neurocode-ai/schema/permission-saved"
+import { Project } from "@neurocode-ai/schema/project"
+import { Session } from "@neurocode-ai/schema/session"
+import { Context, Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { PermissionNotFoundError, SessionNotFoundError } from "../errors"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const makePermissionGroup = <
+  LocationId extends HttpApiMiddleware.AnyId,
+  LocationService,
+  SessionLocationId extends HttpApiMiddleware.AnyId,
+  SessionLocationService,
+>(
+  locationMiddleware: Context.Key<LocationId, LocationService>,
+  sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>,
+) =>
+  HttpApiGroup.make("server.permission")
+    .add(
+      HttpApiEndpoint.get("permission.request.list", "/api/permission/request", {
+        query: LocationQuery,
+        success: Location.response(Schema.Array(Permission.Request)),
+      })
+        .annotateMerge(locationQueryOpenApi)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.permission.request.list",
+            summary: "List pending permission requests",
+            description: "Retrieve pending permission requests for a location.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("permission.saved.list", "/api/permission/saved", {
+        query: Schema.Struct({ projectID: Project.ID.pipe(Schema.optional) }),
+        success: Schema.Struct({ data: Schema.Array(PermissionSaved.Info) }),
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.permission.saved.list",
+          summary: "List saved permissions",
+          description: "Retrieve saved permissions, optionally filtered by project.",
+        }),
+      ),
+    )
+    .add(
+      HttpApiEndpoint.delete("permission.saved.remove", "/api/permission/saved/:id", {
+        params: { id: PermissionSaved.ID },
+        success: HttpApiSchema.NoContent,
+      }).annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.permission.saved.remove",
+          summary: "Remove saved permission",
+          description: "Remove a saved permission by ID.",
+        }),
+      ),
+    )
+    // Effect applies group middleware only to endpoints already added; session endpoints use session placement below.
+    .middleware(locationMiddleware)
+    .add(
+      HttpApiEndpoint.post("session.permission.create", "/api/session/:sessionID/permission", {
+        params: { sessionID: Session.ID },
+        payload: Schema.Struct({
+          id: Permission.ID.pipe(Schema.optional),
+          action: Permission.Request.fields.action,
+          resources: Permission.Request.fields.resources,
+          save: Permission.Request.fields.save,
+          metadata: Permission.Request.fields.metadata,
+          source: Permission.Request.fields.source,
+          agent: Agent.ID.pipe(Schema.optional),
+        }),
+        success: Schema.Struct({
+          data: Schema.Struct({ id: Permission.ID, effect: Permission.Effect }),
+        }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.permission.create",
+            summary: "Create permission request",
+            description: "Evaluate and, when approval is required, create a permission request for a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.permission.list", "/api/session/:sessionID/permission", {
+        params: { sessionID: Session.ID },
+        success: Schema.Struct({ data: Schema.Array(Permission.Request) }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.permission.list",
+            summary: "List session permission requests",
+            description: "Retrieve pending permission requests owned by a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.permission.get", "/api/session/:sessionID/permission/:requestID", {
+        params: { sessionID: Session.ID, requestID: Permission.ID },
+        success: Schema.Struct({ data: Permission.Request }),
+        error: [SessionNotFoundError, PermissionNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.permission.get",
+            summary: "Get permission request",
+            description: "Retrieve a pending permission request owned by a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.permission.reply", "/api/session/:sessionID/permission/:requestID/reply", {
+        params: { sessionID: Session.ID, requestID: Permission.ID },
+        payload: Schema.Struct({
+          reply: Permission.Reply,
+          message: Schema.String.pipe(Schema.optional),
+        }),
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, PermissionNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.permission.reply",
+            summary: "Reply to pending permission request",
+            description: "Respond to a pending permission request owned by a session.",
+          }),
+        ),
+    )
+    .annotateMerge(OpenApi.annotations({ title: "permissions", description: "Experimental permission routes." }))

package/src/groups/project-copy.ts

@@ -0,0 +1,56 @@
+import { ProjectCopy } from "@neurocode-ai/schema/project-copy"
+import { Project } from "@neurocode-ai/schema/project"
+import { Schema, Struct } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+const root = "/experimental/project/:projectID/copy"
+
+export class ProjectCopyError extends Schema.ErrorClass<ProjectCopyError>("ProjectCopyError")(
+  {
+    name: Schema.Literal("ProjectCopyError"),
+    data: Schema.Struct({
+      message: Schema.String,
+      forceRequired: Schema.optional(Schema.Boolean),
+    }),
+  },
+  { httpApiStatus: 400 },
+) {}
+
+const CreatePayload = Schema.Struct(Struct.omit(ProjectCopy.CreateInput.fields, ["projectID", "sourceDirectory"]))
+const RemovePayload = Schema.Struct(Struct.omit(ProjectCopy.RemoveInput.fields, ["projectID"]))
+
+export const ProjectCopyGroup = HttpApiGroup.make("server.projectCopy")
+  .add(
+    HttpApiEndpoint.post("projectCopy.create", root, {
+      params: { projectID: Project.ID },
+      query: LocationQuery,
+      payload: CreatePayload,
+      success: ProjectCopy.Copy,
+      error: ProjectCopyError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(OpenApi.annotations({ identifier: "v2.projectCopy.create" })),
+  )
+  .add(
+    HttpApiEndpoint.delete("projectCopy.remove", root, {
+      params: { projectID: Project.ID },
+      query: LocationQuery,
+      payload: RemovePayload,
+      success: HttpApiSchema.NoContent,
+      error: ProjectCopyError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(OpenApi.annotations({ identifier: "v2.projectCopy.remove" })),
+  )
+  .add(
+    HttpApiEndpoint.post("projectCopy.refresh", `${root}/refresh`, {
+      params: { projectID: Project.ID },
+      query: LocationQuery,
+      success: HttpApiSchema.NoContent,
+      error: ProjectCopyError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(OpenApi.annotations({ identifier: "v2.projectCopy.refresh" })),
+  )
+  .annotateMerge(OpenApi.annotations({ title: "projectCopy", description: "Project copy management routes." }))

package/src/groups/provider.ts

@@ -0,0 +1,45 @@
+import { Provider } from "@neurocode-ai/schema/provider"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { ProviderNotFoundError, ServiceUnavailableError } from "../errors"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const ProviderGroup = HttpApiGroup.make("server.provider")
+  .add(
+    HttpApiEndpoint.get("provider.list", "/api/provider", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Provider.Info)),
+      error: ServiceUnavailableError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.provider.list",
+          summary: "List providers",
+          description: "Retrieve active AI providers so clients can show provider availability and configuration.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.get("provider.get", "/api/provider/:providerID", {
+      params: { providerID: Provider.ID },
+      query: LocationQuery,
+      success: Location.response(Provider.Info),
+      error: [ProviderNotFoundError, ServiceUnavailableError],
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.provider.get",
+          summary: "Get provider",
+          description: "Retrieve a single AI provider so clients can inspect its availability and endpoint settings.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "providers",
+      description: "Experimental provider routes.",
+    }),
+  )

package/src/groups/pty.ts

@@ -0,0 +1,143 @@
+import { Pty } from "@neurocode-ai/schema/pty"
+import { PtyTicket } from "@neurocode-ai/schema/pty-ticket"
+import { Location } from "@neurocode-ai/schema/location"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { ForbiddenError, PtyNotFoundError } from "../errors"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const PTY_CONNECT_TICKET_QUERY = "ticket"
+export const PTY_CONNECT_TOKEN_HEADER = "x-neurocode-ticket"
+export const PTY_CONNECT_TOKEN_HEADER_VALUE = "1"
+
+const PTY_CONNECT_PATH = /^\/api\/pty\/[^/]+\/connect$/
+
+// Authorization middleware skips credential checks when this matches; the PTY connect handler
+// is then responsible for consuming and validating the ticket.
+export function hasPtyConnectTicketURL(url: URL) {
+  return PTY_CONNECT_PATH.test(url.pathname) && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY)
+}
+
+export const PtyGroup = HttpApiGroup.make("server.pty")
+  .add(
+    HttpApiEndpoint.get("pty.list", "/api/pty", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Pty.Info)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.pty.list",
+          summary: "List PTY sessions",
+          description: "List PTY sessions for a location, including exited sessions retained until removal.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("pty.create", "/api/pty", {
+      query: LocationQuery,
+      payload: Pty.CreateInput,
+      success: Location.response(Pty.Info),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.pty.create",
+          summary: "Create PTY session",
+          description: "Create a pseudo-terminal session for a location.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.get("pty.get", "/api/pty/:ptyID", {
+      params: { ptyID: Pty.ID },
+      query: LocationQuery,
+      success: Location.response(Pty.Info),
+      error: PtyNotFoundError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.pty.get",
+          summary: "Get PTY session",
+          description: "Get one PTY session, including its exit code once exited.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.put("pty.update", "/api/pty/:ptyID", {
+      params: { ptyID: Pty.ID },
+      query: LocationQuery,
+      payload: Pty.UpdateInput,
+      success: Location.response(Pty.Info),
+      error: PtyNotFoundError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.pty.update",
+          summary: "Update PTY session",
+          description: "Update the title or viewport size of one PTY session.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.delete("pty.remove", "/api/pty/:ptyID", {
+      params: { ptyID: Pty.ID },
+      query: LocationQuery,
+      success: HttpApiSchema.NoContent,
+      error: PtyNotFoundError,
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.pty.remove",
+          summary: "Remove PTY session",
+          description: "Terminate and remove one PTY session.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("pty.connectToken", "/api/pty/:ptyID/connect-token", {
+      params: { ptyID: Pty.ID },
+      query: LocationQuery,
+      success: Location.response(PtyTicket.ConnectToken),
+      error: [ForbiddenError, PtyNotFoundError],
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.pty.connectToken",
+          summary: "Create PTY WebSocket token",
+          description: "Create a short-lived single-use ticket for opening a PTY WebSocket connection.",
+        }),
+      ),
+  )
+  .add(
+    // Query fields are decoded in the raw handler after the existence check so a missing
+    // session responds with an empty 404 before any upgrade work.
+    HttpApiEndpoint.get("pty.connect", "/api/pty/:ptyID/connect", {
+      params: { ptyID: Pty.ID },
+      success: Schema.Boolean,
+      error: [ForbiddenError, PtyNotFoundError],
+    }).annotateMerge(
+      OpenApi.annotations({
+        identifier: "v2.pty.connect",
+        summary: "Connect to PTY session",
+        description: "Establish a WebSocket connection streaming PTY output and accepting terminal input.",
+        transform: (operation) => ({
+          ...operation,
+          "x-websocket": true,
+          parameters: [
+            ...(operation.parameters ?? []),
+            ...["location[directory]", "location[workspace]", "cursor", PTY_CONNECT_TICKET_QUERY].map((name) => ({
+              in: "query",
+              name,
+              schema: { type: "string" },
+            })),
+          ],
+        }),
+      }),
+    ),
+  )
+  .annotateMerge(OpenApi.annotations({ title: "pty", description: "Experimental location-scoped PTY routes." }))

package/src/groups/question.ts

@@ -0,0 +1,84 @@
+import { Question } from "@neurocode-ai/schema/question"
+import { Location } from "@neurocode-ai/schema/location"
+import { Session } from "@neurocode-ai/schema/session"
+import { Context, Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { QuestionNotFoundError, SessionNotFoundError } from "../errors"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const makeQuestionGroup = <
+  LocationId extends HttpApiMiddleware.AnyId,
+  LocationService,
+  SessionLocationId extends HttpApiMiddleware.AnyId,
+  SessionLocationService,
+>(
+  locationMiddleware: Context.Key<LocationId, LocationService>,
+  sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>,
+) =>
+  HttpApiGroup.make("server.question")
+    .add(
+      HttpApiEndpoint.get("question.request.list", "/api/question/request", {
+        query: LocationQuery,
+        success: Location.response(Schema.Array(Question.Request)),
+      })
+        .annotateMerge(locationQueryOpenApi)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.question.request.list",
+            summary: "List pending question requests",
+            description: "Retrieve pending question requests for a location.",
+          }),
+        ),
+    )
+    .annotateMerge(OpenApi.annotations({ title: "questions", description: "Experimental question routes." }))
+    // Effect applies group middleware only to endpoints already added; session endpoints use session placement below.
+    .middleware(locationMiddleware)
+    .add(
+      HttpApiEndpoint.get("session.question.list", "/api/session/:sessionID/question", {
+        params: { sessionID: Session.ID },
+        success: Schema.Struct({ data: Schema.Array(Question.Request) }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.question.list",
+            summary: "List session question requests",
+            description: "Retrieve pending question requests owned by a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.question.reply", "/api/session/:sessionID/question/:requestID/reply", {
+        params: { sessionID: Session.ID, requestID: Question.ID },
+        payload: Question.Reply,
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, QuestionNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.question.reply",
+            summary: "Reply to pending question request",
+            description: "Answer a pending question request owned by a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.question.reject", "/api/session/:sessionID/question/:requestID/reject", {
+        params: { sessionID: Session.ID, requestID: Question.ID },
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, QuestionNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.question.reject",
+            summary: "Reject pending question request",
+            description: "Reject a pending question request owned by a session.",
+          }),
+        ),
+    )
+    .annotateMerge(
+      OpenApi.annotations({ title: "session questions", description: "Experimental session question routes." }),
+    )

package/src/groups/reference.ts

@@ -0,0 +1,27 @@
+import { Location } from "@neurocode-ai/schema/location"
+import { Reference } from "@neurocode-ai/schema/reference"
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { LocationQuery, locationQueryOpenApi } from "./location"
+
+export const ReferenceGroup = HttpApiGroup.make("server.reference")
+  .add(
+    HttpApiEndpoint.get("reference.list", "/api/reference", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Reference.Info)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.reference.list",
+          summary: "List references",
+          description: "List references available in the requested location.",
+        }),
+      ),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "reference",
+      description: "Location-scoped project references.",
+    }),
+  )