feat(httpapi): bridge pty routes (#24547)

5 files changed, 296 insertions, 6 deletions

diff --git a/packages/opencode/specs/effect/http-api.md b/packages/opencode/specs/effect/http-api.md
index 6536ac947..bbfc7bade 100644
--- a/packages/opencode/specs/effect/http-api.md
+++ b/packages/opencode/specs/effect/http-api.md
@@ -320,12 +320,12 @@ This checklist tracks bridge parity only. Checked routes are available through t
 
 ### PTY Routes
 
-- [ ] `GET /pty` - list PTY sessions.
-- [ ] `POST /pty` - create PTY session.
-- [ ] `GET /pty/:ptyID` - get PTY session.
-- [ ] `PUT /pty/:ptyID` - update PTY session.
-- [ ] `DELETE /pty/:ptyID` - remove PTY session.
-- [ ] `GET /pty/:ptyID/connect` - PTY websocket; replace with raw Effect HTTP/websocket support.
+- [x] `GET /pty` - list PTY sessions.
+- [x] `POST /pty` - create PTY session.
+- [x] `GET /pty/:ptyID` - get PTY session.
+- [x] `PUT /pty/:ptyID` - update PTY session.
+- [x] `DELETE /pty/:ptyID` - remove PTY session.
+- [x] `GET /pty/:ptyID/connect` - PTY websocket; replace with raw Effect HTTP/websocket support.
 
 ### TUI Routes
 
diff --git a/packages/opencode/src/server/routes/instance/httpapi/pty.ts b/packages/opencode/src/server/routes/instance/httpapi/pty.ts
new file mode 100644
index 000000000..de29d9609
--- /dev/null
+++ b/packages/opencode/src/server/routes/instance/httpapi/pty.ts
@@ -0,0 +1,205 @@
+import { EffectBridge } from "@/effect"
+import { Pty } from "@/pty"
+import { PtyID } from "@/pty/schema"
+import { Effect, Layer, Schema } from "effect"
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
+import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiError, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import * as Socket from "effect/unstable/socket/Socket"
+import { Authorization } from "./auth"
+
+const root = "/pty"
+const Params = Schema.Struct({
+  ptyID: PtyID,
+})
+const CursorQuery = Schema.Struct({
+  cursor: Schema.optional(Schema.String),
+})
+
+export const PtyPaths = {
+  list: root,
+  create: root,
+  get: `${root}/:ptyID`,
+  update: `${root}/:ptyID`,
+  remove: `${root}/:ptyID`,
+  connect: `${root}/:ptyID/connect`,
+} as const
+
+export const PtyApi = HttpApi.make("pty")
+  .add(
+    HttpApiGroup.make("pty")
+      .add(
+        HttpApiEndpoint.get("list", PtyPaths.list, {
+          success: Schema.Array(Pty.Info),
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "pty.list",
+            summary: "List PTY sessions",
+            description: "Get a list of all active pseudo-terminal (PTY) sessions managed by OpenCode.",
+          }),
+        ),
+        HttpApiEndpoint.post("create", PtyPaths.create, {
+          payload: Pty.CreateInput,
+          success: Pty.Info,
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "pty.create",
+            summary: "Create PTY session",
+            description: "Create a new pseudo-terminal (PTY) session for running shell commands and processes.",
+          }),
+        ),
+        HttpApiEndpoint.get("get", PtyPaths.get, {
+          params: { ptyID: PtyID },
+          success: Pty.Info,
+          error: HttpApiError.NotFound,
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "pty.get",
+            summary: "Get PTY session",
+            description: "Retrieve detailed information about a specific pseudo-terminal (PTY) session.",
+          }),
+        ),
+        HttpApiEndpoint.put("update", PtyPaths.update, {
+          params: { ptyID: PtyID },
+          payload: Pty.UpdateInput,
+          success: Pty.Info,
+          error: HttpApiError.NotFound,
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "pty.update",
+            summary: "Update PTY session",
+            description: "Update properties of an existing pseudo-terminal (PTY) session.",
+          }),
+        ),
+        HttpApiEndpoint.delete("remove", PtyPaths.remove, {
+          params: { ptyID: PtyID },
+          success: Schema.Boolean,
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "pty.remove",
+            summary: "Remove PTY session",
+            description: "Remove and terminate a specific pseudo-terminal (PTY) session.",
+          }),
+        ),
+      )
+      .annotateMerge(
+        OpenApi.annotations({
+          title: "pty",
+          description: "Experimental HttpApi PTY routes.",
+        }),
+      )
+      .middleware(Authorization),
+  )
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "opencode experimental HttpApi",
+      version: "0.0.1",
+      description: "Experimental HttpApi surface for selected instance routes.",
+    }),
+  )
+
+export const ptyHandlers = Layer.unwrap(
+  Effect.gen(function* () {
+    const pty = yield* Pty.Service
+
+    const list = Effect.fn("PtyHttpApi.list")(function* () {
+      return yield* pty.list()
+    })
+
+    const create = Effect.fn("PtyHttpApi.create")(function* (ctx: { payload: typeof Pty.CreateInput.Type }) {
+      const bridge = yield* EffectBridge.make()
+      return yield* Effect.promise(() =>
+        bridge.promise(
+          pty.create({
+            ...ctx.payload,
+            args: ctx.payload.args ? [...ctx.payload.args] : undefined,
+            env: ctx.payload.env ? { ...ctx.payload.env } : undefined,
+          }),
+        ),
+      )
+    })
+
+    const get = Effect.fn("PtyHttpApi.get")(function* (ctx: { params: { ptyID: PtyID } }) {
+      const info = yield* pty.get(ctx.params.ptyID)
+      if (!info) return yield* new HttpApiError.NotFound({})
+      return info
+    })
+
+    const update = Effect.fn("PtyHttpApi.update")(function* (ctx: {
+      params: { ptyID: PtyID }
+      payload: typeof Pty.UpdateInput.Type
+    }) {
+      const info = yield* pty.update(ctx.params.ptyID, {
+        ...ctx.payload,
+        size: ctx.payload.size ? { ...ctx.payload.size } : undefined,
+      })
+      if (!info) return yield* new HttpApiError.NotFound({})
+      return info
+    })
+
+    const remove = Effect.fn("PtyHttpApi.remove")(function* (ctx: { params: { ptyID: PtyID } }) {
+      yield* pty.remove(ctx.params.ptyID)
+      return true
+    })
+
+    return HttpApiBuilder.group(PtyApi, "pty", (handlers) =>
+      handlers
+        .handle("list", list)
+        .handle("create", create)
+        .handle("get", get)
+        .handle("update", update)
+        .handle("remove", remove),
+    )
+  }),
+)
+
+export const ptyConnectRoute = HttpRouter.add(
+  "GET",
+  PtyPaths.connect,
+  Effect.gen(function* () {
+    const pty = yield* Pty.Service
+    const params = yield* HttpRouter.schemaPathParams(Params)
+    if (!(yield* pty.get(params.ptyID))) return HttpServerResponse.empty({ status: 404 })
+
+    const query = yield* HttpServerRequest.schemaSearchParams(CursorQuery)
+    const parsedCursor = query.cursor === undefined ? undefined : Number(query.cursor)
+    const cursor =
+      parsedCursor !== undefined && Number.isSafeInteger(parsedCursor) && parsedCursor >= -1 ? parsedCursor : undefined
+    const socket = yield* Effect.orDie((yield* HttpServerRequest.HttpServerRequest).upgrade)
+    const write = yield* socket.writer
+    let closed = false
+    const adapter = {
+      get readyState() {
+        return closed ? 3 : 1
+      },
+      send: (data: string | Uint8Array | ArrayBuffer) => {
+        if (closed) return
+        Effect.runFork(
+          write(data instanceof ArrayBuffer ? new Uint8Array(data) : data).pipe(Effect.catch(() => Effect.void)),
+        )
+      },
+      close: (code?: number, reason?: string) => {
+        if (closed) return
+        closed = true
+        Effect.runFork(write(new Socket.CloseEvent(code, reason)).pipe(Effect.catch(() => Effect.void)))
+      },
+    }
+    const handler = yield* pty.connect(params.ptyID, adapter, cursor)
+    if (!handler) return HttpServerResponse.empty()
+
+    yield* socket
+      .runRaw((message) => {
+        handler.onMessage(typeof message === "string" ? message : message.slice().buffer)
+      })
+      .pipe(
+        Effect.catchReason("SocketError", "SocketCloseError", () => Effect.void),
+        Effect.ensuring(
+          Effect.sync(() => {
+            closed = true
+            handler.onClose()
+          }),
+        ),
+        Effect.orDie,
+      )
+    return HttpServerResponse.empty()
+  }).pipe(Effect.provide(Pty.defaultLayer)),
+)
diff --git a/packages/opencode/src/server/routes/instance/httpapi/server.ts b/packages/opencode/src/server/routes/instance/httpapi/server.ts
index 1e8b23f55..719f5801b 100644
--- a/packages/opencode/src/server/routes/instance/httpapi/server.ts
+++ b/packages/opencode/src/server/routes/instance/httpapi/server.ts
@@ -6,6 +6,7 @@ import { InstanceRef, WorkspaceRef } from "@/effect/instance-ref"
 import { Observability } from "@/effect"
 import { InstanceBootstrap } from "@/project/bootstrap"
 import { Instance } from "@/project/instance"
+import { Pty } from "@/pty"
 import { lazy } from "@/util/lazy"
 import { Filesystem } from "@/util"
 import { authorizationLayer } from "./auth"
@@ -17,6 +18,7 @@ import { InstanceApi, instanceHandlers } from "./instance"
 import { McpApi, mcpHandlers } from "./mcp"
 import { PermissionApi, permissionHandlers } from "./permission"
 import { ProjectApi, projectHandlers } from "./project"
+import { PtyApi, ptyConnectRoute, ptyHandlers } from "./pty"
 import { ProviderApi, providerHandlers } from "./provider"
 import { QuestionApi, questionHandlers } from "./question"
 import { SessionApi, sessionHandlers } from "./session"
@@ -68,12 +70,14 @@ const instance = HttpRouter.middleware()(
 
 export const routes = Layer.mergeAll(
   eventRoute,
+  ptyConnectRoute,
   HttpApiBuilder.layer(ConfigApi).pipe(Layer.provide(configHandlers)),
   HttpApiBuilder.layer(ExperimentalApi).pipe(Layer.provide(experimentalHandlers)),
   HttpApiBuilder.layer(FileApi).pipe(Layer.provide(fileHandlers)),
   HttpApiBuilder.layer(InstanceApi).pipe(Layer.provide(instanceHandlers)),
   HttpApiBuilder.layer(McpApi).pipe(Layer.provide(mcpHandlers)),
   HttpApiBuilder.layer(ProjectApi).pipe(Layer.provide(projectHandlers)),
+  HttpApiBuilder.layer(PtyApi).pipe(Layer.provide(ptyHandlers), Layer.provide(Pty.defaultLayer)),
   HttpApiBuilder.layer(QuestionApi).pipe(Layer.provide(questionHandlers)),
   HttpApiBuilder.layer(PermissionApi).pipe(Layer.provide(permissionHandlers)),
   HttpApiBuilder.layer(ProviderApi).pipe(Layer.provide(providerHandlers)),
diff --git a/packages/opencode/src/server/routes/instance/index.ts b/packages/opencode/src/server/routes/instance/index.ts
index c2e89c14e..f0bd3f842 100644
--- a/packages/opencode/src/server/routes/instance/index.ts
+++ b/packages/opencode/src/server/routes/instance/index.ts
@@ -16,6 +16,7 @@ import { QuestionRoutes } from "./question"
 import { PermissionRoutes } from "./permission"
 import { Flag } from "@opencode-ai/core/flag/flag"
 import { ExperimentalHttpApiServer } from "./httpapi/server"
+import { PtyPaths } from "./httpapi/pty"
 import { EventPaths } from "./httpapi/event"
 import { ExperimentalPaths } from "./httpapi/experimental"
 import { FilePaths } from "./httpapi/file"
@@ -96,6 +97,12 @@ export const InstanceRoutes = (upgrade: UpgradeWebSocket): Hono => {
     app.post(SyncPaths.start, (c) => handler(c.req.raw, context))
     app.post(SyncPaths.replay, (c) => handler(c.req.raw, context))
     app.post(SyncPaths.history, (c) => handler(c.req.raw, context))
+    app.get(PtyPaths.list, (c) => handler(c.req.raw, context))
+    app.post(PtyPaths.create, (c) => handler(c.req.raw, context))
+    app.get(PtyPaths.get, (c) => handler(c.req.raw, context))
+    app.put(PtyPaths.update, (c) => handler(c.req.raw, context))
+    app.delete(PtyPaths.remove, (c) => handler(c.req.raw, context))
+    app.get(PtyPaths.connect, (c) => handler(c.req.raw, context))
     app.get(SessionPaths.list, (c) => handler(c.req.raw, context))
     app.get(SessionPaths.status, (c) => handler(c.req.raw, context))
     app.get(SessionPaths.get, (c) => handler(c.req.raw, context))
diff --git a/packages/opencode/test/server/httpapi-pty.test.ts b/packages/opencode/test/server/httpapi-pty.test.ts
new file mode 100644
index 000000000..00aa8e21f
--- /dev/null
+++ b/packages/opencode/test/server/httpapi-pty.test.ts
@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import type { UpgradeWebSocket } from "hono/ws"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import { PtyID } from "../../src/pty/schema"
+import { Instance } from "../../src/project/instance"
+import { InstanceRoutes } from "../../src/server/routes/instance"
+import { PtyPaths } from "../../src/server/routes/instance/httpapi/pty"
+import { Log } from "../../src/util"
+import { resetDatabase } from "../fixture/db"
+import { tmpdir } from "../fixture/fixture"
+
+void Log.init({ print: false })
+
+const original = Flag.OPENCODE_EXPERIMENTAL_HTTPAPI
+const websocket = (() => () => new Response(null, { status: 501 })) as unknown as UpgradeWebSocket
+const testPty = process.platform === "win32" ? test.skip : test
+
+function app() {
+  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = true
+  return InstanceRoutes(websocket)
+}
+
+afterEach(async () => {
+  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = original
+  await Instance.disposeAll()
+  await resetDatabase()
+})
+
+describe("pty HttpApi bridge", () => {
+  testPty("serves PTY JSON routes through experimental Effect routes", async () => {
+    await using tmp = await tmpdir({ git: true, config: { formatter: false, lsp: false } })
+    const headers = { "x-opencode-directory": tmp.path }
+    const list = await app().request(PtyPaths.list, { headers })
+    expect(list.status).toBe(200)
+    expect(await list.json()).toEqual([])
+
+    const created = await app().request(PtyPaths.create, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json" },
+      body: JSON.stringify({ command: "/usr/bin/env", args: ["sh", "-c", "sleep 5"], title: "demo" }),
+    })
+    expect(created.status).toBe(200)
+    const info = await created.json()
+
+    try {
+      expect(info).toMatchObject({ title: "demo", command: "/usr/bin/env", status: "running" })
+
+      const found = await app().request(PtyPaths.get.replace(":ptyID", info.id), { headers })
+      expect(found.status).toBe(200)
+      expect(await found.json()).toMatchObject({ id: info.id, title: "demo" })
+
+      const updated = await app().request(PtyPaths.update.replace(":ptyID", info.id), {
+        method: "PUT",
+        headers: { ...headers, "content-type": "application/json" },
+        body: JSON.stringify({ title: "renamed", size: { cols: 80, rows: 24 } }),
+      })
+      expect(updated.status).toBe(200)
+      expect(await updated.json()).toMatchObject({ id: info.id, title: "renamed" })
+    } finally {
+      await app().request(PtyPaths.remove.replace(":ptyID", info.id), { method: "DELETE", headers })
+    }
+
+    const missing = await app().request(PtyPaths.get.replace(":ptyID", info.id), { headers })
+    expect(missing.status).toBe(404)
+  })
+
+  test("returns 404 for missing PTY websocket before upgrade", async () => {
+    await using tmp = await tmpdir({ git: true, config: { formatter: false, lsp: false } })
+    const response = await app().request(PtyPaths.connect.replace(":ptyID", PtyID.ascending()), {
+      headers: { "x-opencode-directory": tmp.path },
+    })
+    expect(response.status).toBe(404)
+  })
+})