rimuru-ai 1.19.0

package/src/server/routes/instance/httpapi/handlers/mcp.ts

@@ -0,0 +1,111 @@
+import { MCP } from "@/mcp"
+import { Effect, Schema } from "effect"
+import { HttpApiBuilder, HttpApiError } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+import { McpServerNotFoundError } from "../errors"
+import { AddPayload, AuthCallbackPayload, StatusMap, UnsupportedOAuthError } from "../groups/mcp"
+
+export const mcpHandlers = HttpApiBuilder.group(InstanceHttpApi, "mcp", (handlers) =>
+  Effect.gen(function* () {
+    const mcp = yield* MCP.Service
+
+    const status = Effect.fn("McpHttpApi.status")(function* () {
+      return yield* mcp.status()
+    })
+
+    const add = Effect.fn("McpHttpApi.add")(function* (ctx: { payload: typeof AddPayload.Type }) {
+      const result = (yield* mcp.add(ctx.payload.name, ctx.payload.config)).status
+      return yield* Schema.decodeUnknownEffect(StatusMap)(
+        "status" in result ? { [ctx.payload.name]: result } : result,
+      ).pipe(Effect.mapError(() => new HttpApiError.BadRequest({})))
+    })
+
+    const authStart = Effect.fn("McpHttpApi.authStart")(function* (ctx: { params: { name: string } }) {
+      return yield* Effect.gen(function* () {
+        if (!(yield* mcp.supportsOAuth(ctx.params.name))) {
+          return yield* new UnsupportedOAuthError({ error: `MCP server ${ctx.params.name} does not support OAuth` })
+        }
+        return yield* mcp.startAuth(ctx.params.name)
+      }).pipe(
+        Effect.catchTag("MCP.NotFoundError", (error) =>
+          Effect.fail(new McpServerNotFoundError({ name: error.name, message: `MCP server not found: ${error.name}` })),
+        ),
+      )
+    })
+
+    const authCallback = Effect.fn("McpHttpApi.authCallback")(function* (ctx: {
+      params: { name: string }
+      payload: typeof AuthCallbackPayload.Type
+    }) {
+      return yield* mcp
+        .finishAuth(ctx.params.name, ctx.payload.code)
+        .pipe(
+          Effect.catchTag("MCP.NotFoundError", (error) =>
+            Effect.fail(
+              new McpServerNotFoundError({ name: error.name, message: `MCP server not found: ${error.name}` }),
+            ),
+          ),
+        )
+    })
+
+    const authAuthenticate = Effect.fn("McpHttpApi.authAuthenticate")(function* (ctx: { params: { name: string } }) {
+      return yield* Effect.gen(function* () {
+        if (!(yield* mcp.supportsOAuth(ctx.params.name))) {
+          return yield* new UnsupportedOAuthError({ error: `MCP server ${ctx.params.name} does not support OAuth` })
+        }
+        return yield* mcp.authenticate(ctx.params.name)
+      }).pipe(
+        Effect.catchTag("MCP.NotFoundError", (error) =>
+          Effect.fail(new McpServerNotFoundError({ name: error.name, message: `MCP server not found: ${error.name}` })),
+        ),
+      )
+    })
+
+    const authRemove = Effect.fn("McpHttpApi.authRemove")(function* (ctx: { params: { name: string } }) {
+      const status = yield* mcp.status()
+      if (!(ctx.params.name in status))
+        return yield* new McpServerNotFoundError({
+          name: ctx.params.name,
+          message: `MCP server not found: ${ctx.params.name}`,
+        })
+      yield* mcp.removeAuth(ctx.params.name)
+      return { success: true as const }
+    })
+
+    const connect = Effect.fn("McpHttpApi.connect")(function* (ctx: { params: { name: string } }) {
+      yield* mcp
+        .connect(ctx.params.name)
+        .pipe(
+          Effect.catchTag("MCP.NotFoundError", (error) =>
+            Effect.fail(
+              new McpServerNotFoundError({ name: error.name, message: `MCP server not found: ${error.name}` }),
+            ),
+          ),
+        )
+      return true
+    })
+
+    const disconnect = Effect.fn("McpHttpApi.disconnect")(function* (ctx: { params: { name: string } }) {
+      yield* mcp
+        .disconnect(ctx.params.name)
+        .pipe(
+          Effect.catchTag("MCP.NotFoundError", (error) =>
+            Effect.fail(
+              new McpServerNotFoundError({ name: error.name, message: `MCP server not found: ${error.name}` }),
+            ),
+          ),
+        )
+      return true
+    })
+
+    return handlers
+      .handle("status", status)
+      .handle("add", add)
+      .handle("authStart", authStart)
+      .handle("authCallback", authCallback)
+      .handle("authAuthenticate", authAuthenticate)
+      .handle("authRemove", authRemove)
+      .handle("connect", connect)
+      .handle("disconnect", disconnect)
+  }),
+)

package/src/server/routes/instance/httpapi/handlers/permission.ts

@@ -0,0 +1,41 @@
+import { PermissionV1 } from "@rimurucode-ai/core/v1/permission"
+import { Permission } from "@/permission"
+import { Effect } from "effect"
+import { HttpApiBuilder } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+import { PermissionNotFoundError } from "../errors"
+
+export const permissionHandlers = HttpApiBuilder.group(InstanceHttpApi, "permission", (handlers) =>
+  Effect.gen(function* () {
+    const svc = yield* Permission.Service
+
+    const list = Effect.fn("PermissionHttpApi.list")(function* () {
+      return yield* svc.list()
+    })
+
+    const reply = Effect.fn("PermissionHttpApi.reply")(function* (ctx: {
+      params: { requestID: PermissionV1.ID }
+      payload: PermissionV1.ReplyBody
+    }) {
+      yield* svc
+        .reply({
+          requestID: ctx.params.requestID,
+          reply: ctx.payload.reply,
+          message: ctx.payload.message,
+        })
+        .pipe(
+          Effect.catchTag("Permission.NotFoundError", (error) =>
+            Effect.fail(
+              new PermissionNotFoundError({
+                requestID: String(error.requestID),
+                message: `Permission request not found: ${error.requestID}`,
+              }),
+            ),
+          ),
+        )
+      return true
+    })
+
+    return handlers.handle("list", list).handle("reply", reply)
+  }),
+)

package/src/server/routes/instance/httpapi/handlers/project-copy.ts

@@ -0,0 +1,83 @@
+import { Agent } from "@/agent/agent"
+import { Provider } from "@/provider/provider"
+import { LLM } from "@/session/llm"
+import { MessageID, SessionID } from "@/session/schema"
+import { Slug } from "@rimurucode-ai/core/util/slug"
+import { LLMEvent } from "@rimurucode-ai/llm"
+import { Effect, Stream } from "effect"
+import { HttpApiBuilder } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+
+const COPY_NAME_AGENT: Agent.Info = {
+  name: "project-copy-name",
+  mode: "primary",
+  permission: [],
+  options: {},
+  native: true,
+  prompt: "",
+}
+
+export const projectCopyHandlers = HttpApiBuilder.group(InstanceHttpApi, "projectCopyName", (handlers) =>
+  Effect.gen(function* () {
+    const llm = yield* LLM.Service
+    const provider = yield* Provider.Service
+
+    const generateName = Effect.fn("ProjectCopyHttpApi.generateName")(function* (context: string | undefined) {
+      const text = context?.trim()
+      if (!text) return Slug.create()
+      const fallback = yield* provider.defaultModel().pipe(Effect.catch(() => Effect.succeed(undefined)))
+      if (!fallback) return Slug.create()
+      const model =
+        (yield* provider.getSmallModel(fallback.providerID)) ??
+        (yield* provider.getModel(fallback.providerID, fallback.modelID))
+      const sessionID = SessionID.descending()
+      const result = yield* llm
+        .stream({
+          agent: COPY_NAME_AGENT,
+          user: {
+            id: MessageID.ascending(),
+            sessionID,
+            role: "user",
+            time: { created: Date.now() },
+            agent: COPY_NAME_AGENT.name,
+            model: { providerID: model.providerID, modelID: model.id },
+          },
+          system: [],
+          small: true,
+          tools: {},
+          model,
+          sessionID,
+          retries: 2,
+          messages: [{ role: "user", content: `Generate a short 2-3 word name that describes this task:\n${text}` }],
+        })
+        .pipe(
+          Stream.filter(LLMEvent.is.textDelta),
+          Stream.map((event) => event.text),
+          Stream.mkString,
+        )
+      const output = result.trim()
+      return output ? slugify(output.split(/\s+/).slice(0, 3).join(" ")) : Slug.create()
+    })
+
+    return handlers.handle("generateName", (ctx) =>
+      generateName(ctx.payload.context).pipe(
+        Effect.catchCause((cause) =>
+          Effect.logWarning("project copy name generation failed", {
+            projectID: ctx.params.projectID,
+            cause,
+          }).pipe(Effect.as(Slug.create())),
+        ),
+        Effect.map((name) => ({ name })),
+      ),
+    )
+  }),
+)
+
+function slugify(input: string) {
+  return input
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "")
+}

package/src/server/routes/instance/httpapi/handlers/project.ts

@@ -0,0 +1,63 @@
+import * as InstanceState from "@/effect/instance-state"
+import { Project } from "@/project/project"
+import { ProjectV2 } from "@rimurucode-ai/core/project"
+import { Effect } from "effect"
+import { HttpApiBuilder } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+import { ProjectNotFoundError } from "../errors"
+import { markInstanceForReload } from "../lifecycle"
+
+export const projectHandlers = HttpApiBuilder.group(InstanceHttpApi, "project", (handlers) =>
+  Effect.gen(function* () {
+    const svc = yield* Project.Service
+    const project = yield* ProjectV2.Service
+
+    const list = Effect.fn("ProjectHttpApi.list")(function* () {
+      return yield* svc.list()
+    })
+
+    const current = Effect.fn("ProjectHttpApi.current")(function* () {
+      return (yield* InstanceState.context).project
+    })
+
+    const initGit = Effect.fn("ProjectHttpApi.initGit")(function* () {
+      const ctx = yield* InstanceState.context
+      const next = yield* svc.initGit({ directory: ctx.directory, project: ctx.project })
+      if (next.id === ctx.project.id && next.vcs === ctx.project.vcs && next.worktree === ctx.project.worktree)
+        return next
+      yield* markInstanceForReload(ctx, {
+        directory: ctx.directory,
+        worktree: ctx.directory,
+        project: next,
+      })
+      return next
+    })
+
+    const update = Effect.fn("ProjectHttpApi.update")(function* (ctx: {
+      params: { projectID: ProjectV2.ID }
+      payload: Project.UpdatePayload
+    }) {
+      return yield* svc.update({ ...ctx.payload, projectID: ctx.params.projectID }).pipe(
+        Effect.catchTag("Project.NotFoundError", (error) =>
+          Effect.fail(
+            new ProjectNotFoundError({
+              projectID: error.projectID,
+              message: `Project not found: ${error.projectID}`,
+            }),
+          ),
+        ),
+      )
+    })
+
+    const directories = Effect.fn("ProjectHttpApi.directories")((ctx: { params: { projectID: ProjectV2.ID } }) =>
+      project.directories({ projectID: ctx.params.projectID }),
+    )
+
+    return handlers
+      .handle("list", list)
+      .handle("current", current)
+      .handle("initGit", initGit)
+      .handle("update", update)
+      .handle("directories", directories)
+  }),
+)

package/src/server/routes/instance/httpapi/handlers/provider.ts

@@ -0,0 +1,113 @@
+import { ProviderAuth } from "@/provider/auth"
+import { Config } from "@/config/config"
+import { ModelsDev } from "@rimurucode-ai/core/models-dev"
+import { Provider } from "@/provider/provider"
+
+import { mapValues } from "remeda"
+import { Effect, Schema } from "effect"
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
+import { HttpApiBuilder } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+import { ProviderAuthApiError } from "../groups/provider"
+import { ProviderV2 } from "@rimurucode-ai/core/provider"
+
+function mapProviderAuthError<A, R>(self: Effect.Effect<A, ProviderAuth.Error, R>) {
+  return self.pipe(
+    Effect.mapError((error) => {
+      if (error instanceof ProviderAuth.OauthMissing) {
+        return new ProviderAuthApiError({ name: error._tag, data: { providerID: error.providerID } })
+      }
+      if (error instanceof ProviderAuth.OauthCodeMissing) {
+        return new ProviderAuthApiError({ name: error._tag, data: { providerID: error.providerID } })
+      }
+      if (error instanceof ProviderAuth.OauthCallbackFailed) {
+        return new ProviderAuthApiError({ name: error._tag, data: {} })
+      }
+      if (error instanceof ProviderAuth.ValidationFailed) {
+        return new ProviderAuthApiError({ name: error._tag, data: { field: error.field, message: error.message } })
+      }
+      return new ProviderAuthApiError({ name: "BadRequest", data: {} })
+    }),
+  )
+}
+
+export const providerHandlers = HttpApiBuilder.group(InstanceHttpApi, "provider", (handlers) =>
+  Effect.gen(function* () {
+    const cfg = yield* Config.Service
+    const provider = yield* Provider.Service
+    const svc = yield* ProviderAuth.Service
+
+    const list = Effect.fn("ProviderHttpApi.list")(function* () {
+      const config = yield* cfg.get()
+      const all = yield* ModelsDev.Service.use((s) => s.get())
+      const disabled = new Set(config.disabled_providers ?? [])
+      const enabled = config.enabled_providers ? new Set(config.enabled_providers) : undefined
+      const filtered: Record<string, (typeof all)[string]> = {}
+      for (const [key, value] of Object.entries(all)) {
+        if ((enabled ? enabled.has(key) : true) && !disabled.has(key)) filtered[key] = value
+      }
+      const connected = yield* provider.list()
+      const providers = Object.assign(
+        mapValues(filtered, (item) => Provider.fromModelsDevProvider(item)),
+        connected,
+      )
+      return {
+        all: Object.values(providers).map(Provider.toPublicInfo),
+        default: Provider.defaultModelIDs(providers),
+        connected: Object.keys(connected),
+      }
+    })
+
+    const auth = Effect.fn("ProviderHttpApi.auth")(function* () {
+      return yield* svc.methods()
+    })
+
+    const authorize = Effect.fn("ProviderHttpApi.authorize")(function* (ctx: {
+      params: { providerID: ProviderV2.ID }
+      payload: ProviderAuth.AuthorizeInput
+    }) {
+      return yield* mapProviderAuthError(
+        svc.authorize({
+          providerID: ctx.params.providerID,
+          method: ctx.payload.method,
+          inputs: ctx.payload.inputs,
+        }),
+      )
+    })
+
+    const authorizeRaw = Effect.fn("ProviderHttpApi.authorizeRaw")(function* (ctx: {
+      params: { providerID: ProviderV2.ID }
+      request: HttpServerRequest.HttpServerRequest
+    }) {
+      const body = yield* Effect.orDie(ctx.request.text)
+      const payload = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(ProviderAuth.AuthorizeInput))(body).pipe(
+        Effect.mapError(() => new ProviderAuthApiError({ name: "BadRequest", data: {} })),
+      )
+      // Match legacy route behavior: when authorize() resolves without a
+      // result (e.g. no further redirect), serialize as JSON `null` instead
+      // of an empty body so clients can `.json()` parse the response.
+      const result = yield* authorize({ params: ctx.params, payload })
+      return HttpServerResponse.jsonUnsafe(result ?? null)
+    })
+
+    const callback = Effect.fn("ProviderHttpApi.callback")(function* (ctx: {
+      params: { providerID: ProviderV2.ID }
+      payload: ProviderAuth.CallbackInput
+    }) {
+      yield* mapProviderAuthError(
+        svc.callback({
+          providerID: ctx.params.providerID,
+          method: ctx.payload.method,
+          code: ctx.payload.code,
+        }),
+      )
+      return true
+    })
+
+    return handlers
+      .handle("list", list)
+      .handle("auth", auth)
+      .handleRaw("authorize", authorizeRaw)
+      .handle("callback", callback)
+  }),
+)

package/src/server/routes/instance/httpapi/handlers/pty.ts

@@ -0,0 +1,273 @@
+import * as InstanceState from "@/effect/instance-state"
+import { registerDisposer } from "@/effect/instance-registry"
+import { InstanceRef, WorkspaceRef } from "@/effect/instance-ref"
+import { Plugin } from "@/plugin"
+import { Pty } from "@rimurucode-ai/core/pty"
+import { PtyProtocol } from "@rimurucode-ai/core/pty/protocol"
+import { PtyID } from "@rimurucode-ai/core/pty/schema"
+import { PtyTicket } from "@rimurucode-ai/core/pty/ticket"
+import { LocationServiceMap } from "@rimurucode-ai/core/location-layer"
+import { Location } from "@rimurucode-ai/core/location"
+import { AbsolutePath } from "@rimurucode-ai/core/schema"
+import { Shell } from "@rimurucode-ai/core/shell"
+import { CorsConfig, isAllowedRequestOrigin, type CorsOptions } from "@rimurucode-ai/server/cors"
+import {
+  PTY_CONNECT_TICKET_QUERY,
+  PTY_CONNECT_TOKEN_HEADER,
+  PTY_CONNECT_TOKEN_HEADER_VALUE,
+} from "@/server/shared/pty-ticket"
+import { Effect, Layer, Option, Queue, Schema } from "effect"
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
+import { HttpApiBuilder } from "effect/unstable/httpapi"
+import * as Socket from "effect/unstable/socket/Socket"
+import { InstanceHttpApi } from "../api"
+import * as ApiError from "../errors"
+import { CursorQuery, PtyConnectApi } from "../groups/pty"
+import { WebSocketTracker } from "../websocket-tracker"
+
+function validOrigin(request: HttpServerRequest.HttpServerRequest, opts: CorsOptions | undefined) {
+  return isAllowedRequestOrigin(request.headers.origin, request.headers.host, opts)
+}
+
+const ticketScope = Effect.gen(function* () {
+  const instance = yield* InstanceRef
+  const workspaceID = yield* WorkspaceRef
+  return { directory: instance?.directory, workspaceID }
+})
+
+// Legacy surface compatibility: before exited-session retention, sessions vanished the moment
+// their process exited. These routes preserve that observable behavior — exited sessions are
+// invisible here — while the canonical /api/pty surface exposes them until removal.
+export const ptyHandlers = HttpApiBuilder.group(InstanceHttpApi, "pty", (handlers) =>
+  Effect.gen(function* () {
+    const tickets = yield* PtyTicket.Service
+    const cors = yield* CorsConfig
+    const plugin = yield* Plugin.Service
+    const locations = yield* LocationServiceMap
+    const unregister = registerDisposer((directory) =>
+      Effect.runPromise(locations.invalidate(Location.Ref.make({ directory: AbsolutePath.make(directory) }))),
+    )
+    yield* Effect.addFinalizer(() => Effect.sync(unregister))
+
+    const pty = Effect.fnUntraced(function* <A, E, R>(effect: Effect.Effect<A, E, R>) {
+      return yield* effect.pipe(
+        Effect.provide(
+          locations.get(Location.Ref.make({ directory: AbsolutePath.make((yield* InstanceState.context).directory) })),
+        ),
+      )
+    })
+
+    const shells = Effect.fn("PtyHttpApi.shells")(function* () {
+      return yield* Effect.promise(() => Shell.list())
+    })
+
+    const list = Effect.fn("PtyHttpApi.list")(function* () {
+      const sessions = yield* pty(Pty.Service.use((service) => service.list()))
+      return sessions.filter((info) => info.status === "running")
+    })
+
+    const create = Effect.fn("PtyHttpApi.create")(function* (ctx: { payload: typeof Pty.CreateInput.Type }) {
+      const cwd = ctx.payload.cwd || (yield* InstanceState.context).directory
+      const shell = yield* plugin.trigger("shell.env", { cwd }, { env: {} as Record<string, string> })
+      return yield* pty(
+        Pty.Service.use((service) =>
+          service.create({
+            ...ctx.payload,
+            args: ctx.payload.args ? [...ctx.payload.args] : undefined,
+            cwd,
+            env: { ...ctx.payload.env, ...shell.env },
+          }),
+        ),
+      )
+    })
+
+    const get = Effect.fn("PtyHttpApi.get")(function* (ctx: { params: { ptyID: PtyID } }) {
+      return yield* pty(Pty.Service.use((service) => service.get(ctx.params.ptyID))).pipe(
+        Effect.catchTag(
+          "Pty.NotFoundError",
+          (error) =>
+            new ApiError.PtyNotFoundError({
+              ptyID: error.ptyID,
+              message: `PTY session not found: ${error.ptyID}`,
+            }),
+        ),
+        Effect.flatMap((info) =>
+          info.status === "running"
+            ? Effect.succeed(info)
+            : new ApiError.PtyNotFoundError({
+                ptyID: ctx.params.ptyID,
+                message: `PTY session not found: ${ctx.params.ptyID}`,
+              }),
+        ),
+      )
+    })
+
+    const update = Effect.fn("PtyHttpApi.update")(function* (ctx: {
+      params: { ptyID: PtyID }
+      payload: typeof Pty.UpdateInput.Type
+    }) {
+      yield* get(ctx)
+      return yield* pty(
+        Pty.Service.use((service) =>
+          service.update(ctx.params.ptyID, {
+            ...ctx.payload,
+            size: ctx.payload.size ? { ...ctx.payload.size } : undefined,
+          }),
+        ),
+      ).pipe(
+        Effect.catchTag(
+          "Pty.NotFoundError",
+          (error) =>
+            new ApiError.PtyNotFoundError({
+              ptyID: error.ptyID,
+              message: `PTY session not found: ${error.ptyID}`,
+            }),
+        ),
+      )
+    })
+
+    const remove = Effect.fn("PtyHttpApi.remove")(function* (ctx: { params: { ptyID: PtyID } }) {
+      yield* get(ctx)
+      yield* pty(Pty.Service.use((service) => service.remove(ctx.params.ptyID))).pipe(
+        Effect.catchTag(
+          "Pty.NotFoundError",
+          (error) =>
+            new ApiError.PtyNotFoundError({
+              ptyID: error.ptyID,
+              message: `PTY session not found: ${error.ptyID}`,
+            }),
+        ),
+      )
+      return true
+    })
+
+    const connectToken = Effect.fn("PtyHttpApi.connectToken")(function* (ctx: { params: { ptyID: PtyID } }) {
+      const request = yield* HttpServerRequest.HttpServerRequest
+      if (request.headers[PTY_CONNECT_TOKEN_HEADER] !== PTY_CONNECT_TOKEN_HEADER_VALUE || !validOrigin(request, cors))
+        return yield* new ApiError.PtyForbiddenError({ message: "Invalid PTY connect token request" })
+      yield* get(ctx)
+      return yield* tickets.issue({ ptyID: ctx.params.ptyID, ...(yield* ticketScope) })
+    })
+
+    return handlers
+      .handle("shells", shells)
+      .handle("list", list)
+      .handle("create", create)
+      .handle("get", get)
+      .handle("update", update)
+      .handle("remove", remove)
+      .handle("connectToken", connectToken)
+  }),
+).pipe(Layer.provide(LocationServiceMap.layer))
+
+export const ptyConnectHandlers = HttpApiBuilder.group(PtyConnectApi, "pty-connect", (handlers) =>
+  Effect.gen(function* () {
+    const tickets = yield* PtyTicket.Service
+    const cors = yield* CorsConfig
+    const locations = yield* LocationServiceMap
+    const unregister = registerDisposer((directory) =>
+      Effect.runPromise(locations.invalidate(Location.Ref.make({ directory: AbsolutePath.make(directory) }))),
+    )
+    yield* Effect.addFinalizer(() => Effect.sync(unregister))
+
+    const pty = Effect.fnUntraced(function* <A, E, R>(effect: Effect.Effect<A, E, R>) {
+      return yield* effect.pipe(
+        Effect.provide(
+          locations.get(Location.Ref.make({ directory: AbsolutePath.make((yield* InstanceState.context).directory) })),
+        ),
+      )
+    })
+
+    return handlers.handleRaw(
+      "connect",
+      Effect.fn("PtyHttpApi.connect")(function* (ctx: {
+        params: { ptyID: PtyID }
+        request: HttpServerRequest.HttpServerRequest
+      }) {
+        const exists = yield* pty(Pty.Service.use((service) => service.get(ctx.params.ptyID))).pipe(
+          Effect.map((info) => info.status === "running"),
+          Effect.catchTag("Pty.NotFoundError", () => Effect.succeed(false)),
+        )
+        if (!exists) return HttpServerResponse.empty({ status: 404 })
+
+        const query = Schema.decodeUnknownOption(CursorQuery)(yield* HttpServerRequest.ParsedSearchParams)
+        if (Option.isNone(query)) return HttpServerResponse.empty({ status: 400 })
+        const ticket = new URL(ctx.request.url, "http://localhost").searchParams.get(PTY_CONNECT_TICKET_QUERY)
+        if (ticket) {
+          const valid = validOrigin(ctx.request, cors)
+            ? yield* tickets.consume({ ticket, ptyID: ctx.params.ptyID, ...(yield* ticketScope) })
+            : false
+          if (!valid) return HttpServerResponse.empty({ status: 403 })
+        }
+        const parsedCursor = query.value.cursor === undefined ? undefined : Number(query.value.cursor)
+        const cursor =
+          parsedCursor !== undefined && Number.isSafeInteger(parsedCursor) && parsedCursor >= -1
+            ? parsedCursor
+            : undefined
+        const socket = yield* Effect.orDie(ctx.request.upgrade)
+        const write = yield* socket.writer
+        const closeAccepted = (event: Socket.CloseEvent) =>
+          socket
+            .runRaw(() => Effect.void, { onOpen: write(event).pipe(Effect.catch(() => Effect.void)) })
+            .pipe(
+              Effect.timeout("1 second"),
+              Effect.catchReason("SocketError", "SocketCloseError", () => Effect.void),
+              Effect.catch(() => Effect.void),
+            )
+        const registered = yield* WebSocketTracker.register(write(WebSocketTracker.SERVER_CLOSING_EVENT()))
+        if (!registered) {
+          yield* closeAccepted(WebSocketTracker.SERVER_CLOSING_EVENT())
+          return HttpServerResponse.empty()
+        }
+
+        // Outbound frames flow through one queue drained by a single writer so replay, live
+        // output, and the close frame keep their order.
+        const outbox = yield* Queue.unbounded<string | Uint8Array | Socket.CloseEvent>()
+        const attachment = yield* pty(
+          Pty.Service.use((service) =>
+            service.attach(ctx.params.ptyID, {
+              cursor,
+              onData: (chunk) => Queue.offerUnsafe(outbox, chunk),
+              onEnd: () => Queue.offerUnsafe(outbox, new Socket.CloseEvent(1000)),
+            }),
+          ),
+        ).pipe(
+          Effect.catchTags({
+            "Pty.NotFoundError": () =>
+              closeAccepted(new Socket.CloseEvent(4404, "session not found")).pipe(Effect.as(undefined)),
+            "Pty.ExitedError": () =>
+              closeAccepted(new Socket.CloseEvent(4404, "session not found")).pipe(Effect.as(undefined)),
+          }),
+        )
+        if (!attachment) return HttpServerResponse.empty()
+
+        for (const chunk of PtyProtocol.chunks(attachment.replay)) Queue.offerUnsafe(outbox, chunk)
+        Queue.offerUnsafe(outbox, PtyProtocol.metaFrame(attachment.cursor))
+        attachment.activate()
+
+        const drain = Effect.gen(function* () {
+          while (true) {
+            const item = yield* Queue.take(outbox)
+            yield* write(item)
+            if (item instanceof Socket.CloseEvent) return
+          }
+        })
+
+        // The reader runs concurrently with the writer; whichever finishes first ends the
+        // connection and the attachment is always released.
+        yield* Effect.race(
+          drain,
+          socket.runRaw((message) => {
+            const decoded = PtyProtocol.decodeInput(message)
+            if (decoded !== undefined) attachment.write(decoded)
+          }),
+        ).pipe(
+          Effect.catchReason("SocketError", "SocketCloseError", () => Effect.void),
+          Effect.ensuring(Effect.sync(() => attachment.detach())),
+          Effect.orDie,
+        )
+        return HttpServerResponse.empty()
+      }),
+    )
+  }),
+).pipe(Layer.provide(LocationServiceMap.layer))