import { PersistentPty } from "@opencode/schema/persistent-pty" import { Pty } from "@opencode/schema/pty" import { PtyTicket } from "@opencode/schema/pty-ticket" import { Session } from "@opencode/schema/session" import { Schema } from "effect" import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/http-api" import { ForbiddenError, InvalidRequestError, PtyFeatureUnsupportedError, PtyNotFoundError, ServiceUnavailableError, } from "../errors.js" import { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE } from "./pty.js" export { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE } export const PERSISTENT_PTY_CONNECT_PATH = "/api/experimental/persistent-pty/:ptyID/connect" const PERSISTENT_PTY_CONNECT_URL = /^\/api\/experimental\/persistent-pty\/[^/]+\/connect$/ export function hasPersistentPtyConnectTicketURL(url: URL) { return PERSISTENT_PTY_CONNECT_URL.test(url.pathname) && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY) } const errors = [InvalidRequestError, ServiceUnavailableError] as const const terminalErrors = [PtyNotFoundError, ServiceUnavailableError] as const export const PersistentPtyGroup = HttpApiGroup.make("server.experimental") .add( HttpApiEndpoint.get("persistentPty.read", "/api/experimental/session/:sessionID/terminal/read", { params: { sessionID: Session.ID }, query: { lines: Schema.NumberFromString.pipe(Schema.decodeTo(PersistentPty.ReadLines), Schema.optional), }, success: Schema.Struct({ data: Schema.NullOr(PersistentPty.ReadResult) }), error: [ServiceUnavailableError], }).annotateMerge( OpenApi.annotations({ identifier: "experimental.persistentPty.read", summary: "Read the session's most recently controlled terminal", description: "Read the last physical rows without changing selection or taking control. Omitted lines uses the live terminal height; larger counts include retained history. Blank rows are preserved. Screen dimensions and cursor remain relative to the live screen. Returns null when no current terminal exists. Selection is server-local and resets on restart. Experimental: may change without compatibility guarantees.", }), ), ) .add( HttpApiEndpoint.get("persistentPty.list", "/api/experimental/session/:sessionID/terminal", { params: { sessionID: Session.ID }, success: Schema.Struct({ data: Schema.Array(PersistentPty.Info) }), error: errors, }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.list" })), ) .add( HttpApiEndpoint.post("persistentPty.create", "/api/experimental/session/:sessionID/terminal", { params: { sessionID: Session.ID }, payload: PersistentPty.CreateInput, success: Schema.Struct({ data: PersistentPty.Info }), error: errors, }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.create" })), ) .add( HttpApiEndpoint.post("persistentPty.shutdown", "/api/experimental/persistent-pty/shutdown", { success: HttpApiSchema.NoContent, error: [ServiceUnavailableError], }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.shutdown" })), ) .add( HttpApiEndpoint.post("persistentPty.handoff", "/api/experimental/persistent-pty/handoff", { success: Schema.Struct({ handoff: Schema.NullOr(PersistentPty.Handoff) }), error: [ServiceUnavailableError], }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.handoff" })), ) .add( HttpApiEndpoint.get("persistentPty.get", "/api/experimental/persistent-pty/:ptyID", { params: { ptyID: Pty.ID }, success: Schema.Struct({ data: PersistentPty.Info }), error: terminalErrors, }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.get" })), ) .add( HttpApiEndpoint.put("persistentPty.update", "/api/experimental/persistent-pty/:ptyID", { params: { ptyID: Pty.ID }, payload: PersistentPty.UpdateInput, success: Schema.Struct({ data: PersistentPty.Info }), error: [...terminalErrors, PtyFeatureUnsupportedError], }).annotateMerge( OpenApi.annotations({ identifier: "experimental.persistentPty.update", description: "Resize when size is present and rename when title is present; a null title clears the user title so the shell's title shows again. Renaming fails with 501 while the terminal service predates renaming.", }), ), ) .add( HttpApiEndpoint.get("persistentPty.snapshot", "/api/experimental/persistent-pty/:ptyID/snapshot", { params: { ptyID: Pty.ID }, success: Schema.Struct({ data: PersistentPty.Snapshot }), error: terminalErrors, }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.snapshot" })), ) .add( HttpApiEndpoint.delete("persistentPty.remove", "/api/experimental/persistent-pty/:ptyID", { params: { ptyID: Pty.ID }, success: HttpApiSchema.NoContent, error: terminalErrors, }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.remove" })), ) .add( HttpApiEndpoint.post("persistentPty.connectToken", "/api/experimental/persistent-pty/:ptyID/connect-token", { params: { ptyID: Pty.ID }, headers: Schema.Struct({ [PTY_CONNECT_TOKEN_HEADER]: Schema.optional(Schema.String) }), success: Schema.Struct({ data: PtyTicket.ConnectToken }), error: [ForbiddenError, PtyNotFoundError, ServiceUnavailableError], }).annotateMerge(OpenApi.annotations({ identifier: "experimental.persistentPty.connectToken" })), ) .add( HttpApiEndpoint.get("persistentPty.connect", PERSISTENT_PTY_CONNECT_PATH, { params: { ptyID: Pty.ID }, success: Schema.Boolean, error: [ForbiddenError, PtyNotFoundError, ServiceUnavailableError], }).annotateMerge( OpenApi.annotations({ identifier: "experimental.persistentPty.connect", summary: "Connect to a persistent PTY", description: "Stream persistent PTY output through the OpenCode server.", transform: (operation) => ({ ...operation, "x-websocket": true, parameters: [ ...(operation.parameters ?? []), ...["cursor", "role", "attachment_id", "takeover", "input_protocol", PTY_CONNECT_TICKET_QUERY].map( (name) => ({ in: "query", name, schema: { type: "string" } }), ), ], }), }), ), ) .annotateMerge(OpenApi.annotations({ title: "persistentPty", description: "Prototype persistent PTY routes." }))