feat(server): add form routes (#35099)

Co-authored-by: Luke Parker <10430890+Hona@users.noreply.github.com>

packages/protocol/src/api.ts

@@ -8,6 +8,7 @@ import { ProviderGroup } from "./groups/provider.js"
 import { makeSessionGroup } from "./groups/session.js"
 import { makePermissionGroup } from "./groups/permission.js"
 import { FileSystemGroup } from "./groups/fs.js"
+import { makeFormGroup } from "./groups/form.js"
 import { CommandGroup } from "./groups/command.js"
 import { SkillGroup } from "./groups/skill.js"
 import { EventGroup, makeEventGroup } from "./groups/event.js"
@@ -59,6 +60,7 @@ type MixedMiddlewareGroups<
   | ReturnType<
       typeof makePermissionGroup<LocationId, LocationService, SessionLocationId, SessionLocationService>
     >
+  | ReturnType<typeof makeFormGroup<LocationId, LocationService, SessionLocationId, SessionLocationService>>
   | ReturnType<typeof makeQuestionGroup<LocationId, LocationService, SessionLocationId, SessionLocationService>>
 
 type ApiGroups<
@@ -119,6 +121,7 @@ const makeApiFromGroup = <
     .add(McpGroup.middleware(locationMiddleware))
     .add(CredentialGroup.middleware(locationMiddleware))
     .add(ProjectGroup.middleware(locationMiddleware))
+    .add(makeFormGroup(locationMiddleware, sessionLocationMiddleware))
     .add(makePermissionGroup(locationMiddleware, sessionLocationMiddleware))
     .add(FileSystemGroup.middleware(locationMiddleware))
     .add(CommandGroup.middleware(locationMiddleware))

packages/protocol/src/client.ts

@@ -39,6 +39,7 @@ export const groupNames = {
   "server.provider": "provider",
   "server.integration": "integration",
   "server.credential": "credential",
+  "server.form": "form",
   "server.permission": "permission",
   "server.fs": "file",
   "server.command": "command",
@@ -68,6 +69,7 @@ export const endpointNames = {
   "permission.request.list": "listRequests",
   "permission.saved.list": "listSaved",
   "permission.saved.remove": "removeSaved",
+  "form.request.list": "listRequests",
   "question.request.list": "listRequests",
 } as const
 

packages/protocol/src/errors.ts

@@ -131,6 +131,33 @@ export class QuestionNotFoundError extends Schema.TaggedErrorClass<QuestionNotFo
   { httpApiStatus: 404 },
 ) {}
 
+export class FormNotFoundError extends Schema.TaggedErrorClass<FormNotFoundError>()(
+  "FormNotFoundError",
+  {
+    id: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 404 },
+) {}
+
+export class FormAlreadySettledError extends Schema.TaggedErrorClass<FormAlreadySettledError>()(
+  "FormAlreadySettledError",
+  {
+    id: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 409 },
+) {}
+
+export class FormInvalidAnswerError extends Schema.TaggedErrorClass<FormInvalidAnswerError>()(
+  "FormInvalidAnswerError",
+  {
+    id: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 400 },
+) {}
+
 export class ForbiddenError extends Schema.TaggedErrorClass<ForbiddenError>()(
   "ForbiddenError",
   { message: Schema.String },

packages/protocol/src/groups/form.ts

@@ -0,0 +1,144 @@
+import { Form } from "@opencode-ai/schema/form"
+import { Location } from "@opencode-ai/schema/location"
+import { Session } from "@opencode-ai/schema/session"
+import { Context, Schema } from "effect"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import {
+  ConflictError,
+  FormAlreadySettledError,
+  FormInvalidAnswerError,
+  FormNotFoundError,
+  InvalidRequestError,
+  SessionNotFoundError,
+} from "../errors.js"
+import { LocationQuery, locationQueryOpenApi } from "./location.js"
+
+const CreatePayload = Schema.Struct({
+  id: Form.ID.pipe(Schema.optional),
+  title: Form.FormInfo.fields.title,
+  metadata: Form.FormInfo.fields.metadata,
+  mode: Schema.Literals(["form", "url"]),
+  fields: Form.FormInfo.fields.fields.pipe(Schema.optional),
+  url: Form.UrlInfo.fields.url.pipe(Schema.optional),
+}).annotate({ identifier: "Form.CreatePayload" })
+
+export type CreatePayload = typeof CreatePayload.Type
+
+export const makeFormGroup = <
+  LocationId extends HttpApiMiddleware.AnyId,
+  LocationService,
+  SessionLocationId extends HttpApiMiddleware.AnyId,
+  SessionLocationService,
+>(
+  locationMiddleware: Context.Key<LocationId, LocationService>,
+  sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>,
+) =>
+  HttpApiGroup.make("server.form")
+    .add(
+      HttpApiEndpoint.get("form.request.list", "/api/form/request", {
+        query: LocationQuery,
+        success: Location.response(Schema.Array(Form.Info)),
+      })
+        .annotateMerge(locationQueryOpenApi)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.form.request.list",
+            summary: "List pending form requests",
+            description: "Retrieve pending forms for a location.",
+          }),
+        ),
+    )
+    .middleware(locationMiddleware)
+    .add(
+      HttpApiEndpoint.get("session.form.list", "/api/session/:sessionID/form", {
+        params: { sessionID: Session.ID },
+        success: Schema.Struct({ data: Schema.Array(Form.Info) }),
+        error: SessionNotFoundError,
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.form.list",
+            summary: "List session forms",
+            description: "Retrieve pending forms for a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.form.create", "/api/session/:sessionID/form", {
+        params: { sessionID: Session.ID },
+        payload: CreatePayload,
+        success: Schema.Struct({ data: Form.Info }),
+        error: [SessionNotFoundError, ConflictError, InvalidRequestError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.form.create",
+            summary: "Create session form",
+            description: "Create a form for a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.form.get", "/api/session/:sessionID/form/:formID", {
+        params: { sessionID: Session.ID, formID: Form.ID },
+        success: Schema.Struct({ data: Form.Info }),
+        error: [SessionNotFoundError, FormNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.form.get",
+            summary: "Get session form",
+            description: "Retrieve a form for a session.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.get("session.form.state", "/api/session/:sessionID/form/:formID/state", {
+        params: { sessionID: Session.ID, formID: Form.ID },
+        success: Schema.Struct({ data: Form.State }),
+        error: [SessionNotFoundError, FormNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.form.state",
+            summary: "Get form state",
+            description: "Retrieve the current state for a form.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.form.reply", "/api/session/:sessionID/form/:formID/reply", {
+        params: { sessionID: Session.ID, formID: Form.ID },
+        payload: Form.Reply,
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, FormAlreadySettledError, FormInvalidAnswerError, FormNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.form.reply",
+            summary: "Reply to form",
+            description: "Submit an answer to a pending form.",
+          }),
+        ),
+    )
+    .add(
+      HttpApiEndpoint.post("session.form.cancel", "/api/session/:sessionID/form/:formID/cancel", {
+        params: { sessionID: Session.ID, formID: Form.ID },
+        success: HttpApiSchema.NoContent,
+        error: [SessionNotFoundError, FormAlreadySettledError, FormNotFoundError],
+      })
+        .middleware(sessionLocationMiddleware)
+        .annotateMerge(
+          OpenApi.annotations({
+            identifier: "v2.session.form.cancel",
+            summary: "Cancel form",
+            description: "Cancel a pending form.",
+          }),
+        ),
+    )
+    .annotateMerge(OpenApi.annotations({ title: "forms", description: "Session form routes." }))