fix: tests

Co-authored-by: Kit Langton <kit.langton@gmail.com>

packages/app/src/components/terminal.tsx

@@ -479,6 +479,27 @@ export const Terminal = (props: TerminalProps) => {
             return false
           })
 
+      const connectToken = async () => {
+        const result = await client.pty
+          .connectToken(
+            { ptyID: id, directory },
+            {
+              throwOnError: false,
+              headers: { "x-opencode-ticket": "1" },
+            },
+          )
+          .catch((err: unknown) => {
+            if (err instanceof Error && err.message.includes("Request is not supported")) return
+            throw err
+          })
+        if (!result) return
+        if (result.response.status === 200 && result.data?.ticket) return result.data.ticket
+        if (result.response.status === 404 || result.response.status === 405) return
+        if (result.response.status === 403)
+          throw new Error("PTY connect ticket rejected by origin or CSRF checks. Check the server CORS config.")
+        throw new Error(`PTY connect ticket failed with ${result.response.status}`)
+      }
+
       const retry = (err: unknown) => {
         if (disposed) return
         if (reconn !== undefined) return
@@ -498,12 +519,29 @@ export const Terminal = (props: TerminalProps) => {
         }, ms)
       }
 
-      const open = () => {
+      const open = async () => {
         if (disposed) return
         drop?.()
 
+        const ticket = await connectToken().catch((err) => {
+          fail(err)
+          return undefined
+        })
+        if (once.value) return
+        if (disposed) return
+
         const socket = new WebSocket(
-          terminalWebSocketURL({ url, id, directory, cursor: seek, sameOrigin, username, password }),
+          terminalWebSocketURL({
+            url,
+            id,
+            directory,
+            cursor: seek,
+            ticket,
+            sameOrigin,
+            username,
+            password,
+            authToken: server.current?.type === "http" ? server.current.authToken : false,
+          }),
         )
         socket.binaryType = "arraybuffer"
         ws = socket

packages/app/src/context/server.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test"
+import { resolveServerList, ServerConnection } from "./server"
+
+describe("resolveServerList", () => {
+  test("lets startup auth_token credentials override a persisted same-url server", () => {
+    const list = resolveServerList({
+      stored: [{ url: "https://server.example.test" }],
+      props: [
+        {
+          type: "http",
+          authToken: true,
+          http: {
+            url: "https://server.example.test",
+            username: "opencode",
+            password: "secret",
+          },
+        },
+      ],
+    })
+
+    expect(list).toHaveLength(1)
+    expect(list[0]?.type).toBe("http")
+    expect(list[0]?.http).toEqual({
+      url: "https://server.example.test",
+      username: "opencode",
+      password: "secret",
+    })
+    expect(list[0]?.type === "http" ? list[0].authToken : false).toBe(true)
+    expect(ServerConnection.key(list[0]!) as string).toBe("https://server.example.test")
+  })
+
+  test("keeps persisted credentials when startup has no auth_token", () => {
+    const list = resolveServerList({
+      stored: [
+        {
+          url: "https://server.example.test",
+          username: "opencode",
+          password: "saved",
+        },
+      ],
+      props: [{ type: "http", http: { url: "https://server.example.test" } }],
+    })
+
+    expect(list).toHaveLength(1)
+    expect(list[0]?.type).toBe("http")
+    expect(list[0]?.http).toEqual({
+      url: "https://server.example.test",
+      username: "opencode",
+      password: "saved",
+    })
+    expect(list[0]?.type === "http" ? list[0].authToken : true).toBeUndefined()
+  })
+})

packages/app/src/context/server.tsx

@@ -33,6 +33,33 @@ function isLocalHost(url: string) {
   if (host === "localhost" || host === "127.0.0.1") return "local"
 }
 
+export function resolveServerList(input: {
+  props?: Array<ServerConnection.Any>
+  stored: StoredServer[]
+}): Array<ServerConnection.Any> {
+  const servers = [
+    ...input.stored.map((value) =>
+      typeof value === "string"
+        ? {
+            type: "http" as const,
+            http: { url: value },
+          }
+        : value,
+    ),
+    ...(input.props ?? []),
+  ]
+
+  const deduped = new Map<ServerConnection.Key, ServerConnection.Any>()
+  for (const value of servers) {
+    const conn: ServerConnection.Any = "type" in value ? value : { type: "http", http: value }
+    const key = ServerConnection.key(conn)
+    if (deduped.has(key) && conn.type === "http" && !conn.authToken) continue
+    deduped.set(key, conn)
+  }
+
+  return [...deduped.values()]
+}
+
 export namespace ServerConnection {
   type Base = { displayName?: string }
 
@@ -46,6 +73,7 @@ export namespace ServerConnection {
   export type Http = {
     type: "http"
     http: HttpBase
+    authToken?: boolean
   } & Base
 
   export type Sidecar = {
@@ -113,26 +141,7 @@ export const { use: useServer, provider: ServerProvider } = createSimpleContext(
     const url = (x: StoredServer) => (typeof x === "string" ? x : "type" in x ? x.http.url : x.url)
 
     const allServers = createMemo((): Array<ServerConnection.Any> => {
-      const servers = [
-        ...(props.servers ?? []),
-        ...store.list.map((value) =>
-          typeof value === "string"
-            ? {
-                type: "http" as const,
-                http: { url: value },
-              }
-            : value,
-        ),
-      ]
-
-      const deduped = new Map(
-        servers.map((value) => {
-          const conn: ServerConnection.Any = "type" in value ? value : { type: "http", http: value }
-          return [ServerConnection.key(conn), conn]
-        }),
-      )
-
-      return [...deduped.values()]
+      return resolveServerList({ stored: store.list, props: props.servers })
     })
 
     const [state, setState] = createStore({
@@ -174,7 +183,7 @@ export const { use: useServer, provider: ServerProvider } = createSimpleContext(
     function add(input: ServerConnection.Http) {
       const url_ = normalizeServerUrl(input.http.url)
       if (!url_) return
-      const conn = { ...input, http: { ...input.http, url: url_ } }
+      const conn: ServerConnection.Http = { ...input, authToken: undefined, http: { ...input.http, url: url_ } }
       return batch(() => {
         const existing = store.list.findIndex((x) => url(x) === url_)
         if (existing !== -1) {

packages/app/src/context/terminal.test.ts

@@ -1,6 +1,9 @@
 import { beforeAll, describe, expect, mock, test } from "bun:test"
 
-let getWorkspaceTerminalCacheKey: (dir: string) => string
+type ServerKey = Parameters<typeof import("./terminal").getTerminalServerScope>[1]
+
+let getWorkspaceTerminalCacheKey: (dir: string, scope?: string) => string
+let getTerminalServerScope: typeof import("./terminal").getTerminalServerScope
 let getLegacyTerminalStorageKeys: (dir: string, legacySessionID?: string) => string[]
 let migrateTerminalState: (value: unknown) => unknown
 
@@ -17,6 +20,7 @@ beforeAll(async () => {
   }))
   const mod = await import("./terminal")
   getWorkspaceTerminalCacheKey = mod.getWorkspaceTerminalCacheKey
+  getTerminalServerScope = mod.getTerminalServerScope
   getLegacyTerminalStorageKeys = mod.getLegacyTerminalStorageKeys
   migrateTerminalState = mod.migrateTerminalState
 })
@@ -25,6 +29,45 @@ describe("getWorkspaceTerminalCacheKey", () => {
   test("uses workspace-only directory cache key", () => {
     expect(getWorkspaceTerminalCacheKey("/repo")).toBe("/repo:__workspace__")
   })
+
+  test("can include a server scope", () => {
+    expect(getWorkspaceTerminalCacheKey("/repo", "wsl:Debian")).toBe("wsl:Debian:/repo:__workspace__")
+  })
+})
+
+describe("getTerminalServerScope", () => {
+  test("preserves local server keys", () => {
+    expect(
+      getTerminalServerScope(
+        { type: "sidecar", variant: "base", http: { url: "http://127.0.0.1:4096" } },
+        "sidecar" as ServerKey,
+      ),
+    ).toBeUndefined()
+    expect(
+      getTerminalServerScope(
+        { type: "http", http: { url: "http://localhost:4096" } },
+        "http://localhost:4096" as ServerKey,
+      ),
+    ).toBeUndefined()
+    expect(
+      getTerminalServerScope({ type: "http", http: { url: "http://[::1]:4096" } }, "http://[::1]:4096" as ServerKey),
+    ).toBeUndefined()
+  })
+
+  test("scopes non-local server keys", () => {
+    expect(
+      getTerminalServerScope(
+        { type: "sidecar", variant: "wsl", distro: "Debian", http: { url: "http://127.0.0.1:4096" } },
+        "wsl:Debian" as ServerKey,
+      ),
+    ).toBe("wsl:Debian" as ServerKey)
+    expect(
+      getTerminalServerScope(
+        { type: "http", http: { url: "https://example.com" } },
+        "https://example.com" as ServerKey,
+      ),
+    ).toBe("https://example.com" as ServerKey)
+  })
 })
 
 describe("getLegacyTerminalStorageKeys", () => {

packages/app/src/context/terminal.tsx

@@ -4,6 +4,7 @@ import { batch, createEffect, createMemo, createRoot, on, onCleanup } from "soli
 import { useParams } from "@solidjs/router"
 import { useSDK } from "./sdk"
 import type { Platform } from "./platform"
+import { ServerConnection, useServer } from "./server"
 import { defaultTitle, titleNumber } from "./terminal-title"
 import { Persist, persisted, removePersisted } from "@/utils/persist"
 
@@ -82,10 +83,31 @@ export function migrateTerminalState(value: unknown) {
   }
 }
 
-export function getWorkspaceTerminalCacheKey(dir: string) {
+export function getWorkspaceTerminalCacheKey(dir: string, scope?: string) {
+  if (scope) return `${scope}:${dir}:${WORKSPACE_KEY}`
   return `${dir}:${WORKSPACE_KEY}`
 }
 
+export function getTerminalServerScope(conn: ServerConnection.Any | undefined, key: ServerConnection.Key) {
+  if (!conn) return
+  if (conn.type === "sidecar" && conn.variant === "base") return
+  if (conn.type === "http") {
+    try {
+      const url = new URL(conn.http.url)
+      if (
+        url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "::1" ||
+        url.hostname === "[::1]"
+      )
+        return
+    } catch {
+      return key
+    }
+  }
+  return key
+}
+
 export function getLegacyTerminalStorageKeys(dir: string, legacySessionID?: string) {
   if (!legacySessionID) return [`${dir}/terminal.v1`]
   return [`${dir}/terminal/${legacySessionID}.v1`, `${dir}/terminal.v1`]
@@ -110,15 +132,16 @@ const trimTerminal = (pty: LocalPTY) => {
   }
 }
 
-export function clearWorkspaceTerminals(dir: string, sessionIDs?: string[], platform?: Platform) {
-  const key = getWorkspaceTerminalCacheKey(dir)
+export function clearWorkspaceTerminals(dir: string, sessionIDs?: string[], platform?: Platform, scope?: string) {
+  const key = getWorkspaceTerminalCacheKey(dir, scope)
   for (const cache of caches) {
     const entry = cache.get(key)
     entry?.value.clear()
   }
 
-  void removePersisted(Persist.workspace(dir, "terminal"), platform)
+  void removePersisted(Persist.workspace(dir, scope ? `terminal:${scope}` : "terminal"), platform)
 
+  if (scope) return
   const legacy = new Set(getLegacyTerminalStorageKeys(dir))
   for (const id of sessionIDs ?? []) {
     for (const key of getLegacyTerminalStorageKeys(dir, id)) {
@@ -130,12 +153,17 @@ export function clearWorkspaceTerminals(dir: string, sessionIDs?: string[], plat
   }
 }
 
-function createWorkspaceTerminalSession(sdk: ReturnType<typeof useSDK>, dir: string, legacySessionID?: string) {
-  const legacy = getLegacyTerminalStorageKeys(dir, legacySessionID)
+function createWorkspaceTerminalSession(
+  sdk: ReturnType<typeof useSDK>,
+  dir: string,
+  legacySessionID?: string,
+  scope?: string,
+) {
+  const legacy = scope ? [] : getLegacyTerminalStorageKeys(dir, legacySessionID)
 
   const [store, setStore, _, ready] = persisted(
     {
-      ...Persist.workspace(dir, "terminal", legacy),
+      ...Persist.workspace(dir, scope ? `terminal:${scope}` : "terminal", legacy),
       migrate: migrateTerminalState,
     },
     createStore<{
@@ -357,8 +385,12 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
   gate: false,
   init: () => {
     const sdk = useSDK()
+    const server = useServer()
     const params = useParams()
     const cache = new Map<string, TerminalCacheEntry>()
+    const scope = createMemo(() => {
+      return getTerminalServerScope(server.current, server.key)
+    })
 
     caches.add(cache)
     onCleanup(() => caches.delete(cache))
@@ -382,9 +414,9 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
       }
     }
 
-    const loadWorkspace = (dir: string, legacySessionID?: string) => {
+    const loadWorkspace = (dir: string, legacySessionID: string | undefined, serverScope: string | undefined) => {
       // Terminals are workspace-scoped so tabs persist while switching sessions in the same directory.
-      const key = getWorkspaceTerminalCacheKey(dir)
+      const key = getWorkspaceTerminalCacheKey(dir, serverScope)
       const existing = cache.get(key)
       if (existing) {
         cache.delete(key)
@@ -393,7 +425,7 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
       }
 
       const entry = createRoot((dispose) => ({
-        value: createWorkspaceTerminalSession(sdk, dir, legacySessionID),
+        value: createWorkspaceTerminalSession(sdk, dir, legacySessionID, serverScope),
         dispose,
       }))
 
@@ -402,16 +434,16 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
       return entry.value
     }
 
-    const workspace = createMemo(() => loadWorkspace(params.dir!, params.id))
+    const workspace = createMemo(() => loadWorkspace(params.dir!, params.id, scope()))
 
     createEffect(
       on(
-        () => ({ dir: params.dir, id: params.id }),
+        () => ({ dir: params.dir, id: params.id, scope: scope() }),
         (next, prev) => {
           if (!prev?.dir) return
-          if (next.dir === prev.dir && next.id === prev.id) return
-          if (next.dir === prev.dir && next.id) return
-          loadWorkspace(prev.dir, prev.id).trimAll()
+          if (next.dir === prev.dir && next.id === prev.id && next.scope === prev.scope) return
+          if (next.dir === prev.dir && next.id && next.scope === prev.scope) return
+          loadWorkspace(prev.dir, prev.id, prev.scope).trimAll()
         },
         { defer: true },
       ),

packages/app/src/entry.tsx

@@ -7,6 +7,7 @@ import { type Platform, PlatformProvider } from "@/context/platform"
 import { dict as en } from "@/i18n/en"
 import { dict as zh } from "@/i18n/zh"
 import { handleNotificationClick } from "@/utils/notification-click"
+import { authFromToken } from "@/utils/server"
 import pkg from "../package.json"
 import { ServerConnection } from "./context/server"
 
@@ -111,6 +112,13 @@ const getDefaultUrl = () => {
   return getCurrentUrl()
 }
 
+const clearAuthToken = () => {
+  const params = new URLSearchParams(location.search)
+  if (!params.has("auth_token")) return
+  params.delete("auth_token")
+  history.replaceState(null, "", location.pathname + (params.size ? `?${params}` : "") + location.hash)
+}
+
 const platform: Platform = {
   platform: "web",
   version: pkg.version,
@@ -146,7 +154,16 @@ if (import.meta.env.VITE_SENTRY_DSN) {
 }
 
 if (root instanceof HTMLElement) {
-  const server: ServerConnection.Http = { type: "http", http: { url: getCurrentUrl() } }
+  const auth = authFromToken(new URLSearchParams(location.search).get("auth_token"))
+  clearAuthToken()
+  const server: ServerConnection.Http = {
+    type: "http",
+    authToken: !!auth,
+    http: {
+      url: getCurrentUrl(),
+      ...auth,
+    },
+  }
   render(
     () => (
       <PlatformProvider value={platform}>

packages/app/src/pages/layout.tsx

@@ -35,7 +35,7 @@ import type { DragEvent } from "@thisbeyond/solid-dnd"
 import { useProviders } from "@/hooks/use-providers"
 import { showToast, Toast, toaster } from "@opencode-ai/ui/toast"
 import { useGlobalSDK } from "@/context/global-sdk"
-import { clearWorkspaceTerminals } from "@/context/terminal"
+import { clearWorkspaceTerminals, getTerminalServerScope } from "@/context/terminal"
 import { dropSessionCaches, pickSessionCacheEvictions } from "@/context/global-sync/session-cache"
 import {
   clearSessionPrefetchInflight,
@@ -1557,6 +1557,7 @@ export default function Layout(props: ParentProps) {
       directory,
       sessions.map((s) => s.id),
       platform,
+      getTerminalServerScope(server.current, server.key),
     )
     await globalSDK.client.instance.dispose({ directory }).catch(() => undefined)
 

packages/app/src/pages/session/terminal-panel.tsx

@@ -37,6 +37,7 @@ export function TerminalPanel() {
   const [store, setStore] = createStore({
     autoCreated: false,
     activeDraggable: undefined as string | undefined,
+    recovered: {} as Record<string, boolean>,
     view: typeof window === "undefined" ? 1000 : (window.visualViewport?.height ?? window.innerHeight),
   })
 
@@ -145,6 +146,21 @@ export function TerminalPanel() {
   const all = terminal.all
   const ids = createMemo(() => all().map((pty) => pty.id))
 
+  const recoverTerminal = (key: string, id: string, clone: (id: string) => Promise<void>) => {
+    if (store.recovered[key]) return
+    setStore("recovered", key, true)
+    void clone(id)
+  }
+
+  const terminalRecoveryKey = (pty: { id: string; title: string; titleNumber: number }) => {
+    return String(pty.titleNumber || pty.title || pty.id)
+  }
+
+  const markTerminalConnected = (key: string, id: string, trim: (id: string) => void) => {
+    setStore("recovered", key, false)
+    trim(id)
+  }
+
   const handleTerminalDragStart = (event: unknown) => {
     const id = getDraggableId(event)
     if (!id) return
@@ -280,9 +296,9 @@ export function TerminalPanel() {
                             <Terminal
                               pty={pty()}
                               autoFocus={opened()}
-                              onConnect={() => ops.trim(id)}
+                              onConnect={() => markTerminalConnected(terminalRecoveryKey(pty()), id, ops.trim)}
                               onCleanup={ops.update}
-                              onConnectError={() => ops.clone(id)}
+                              onConnectError={() => recoverTerminal(terminalRecoveryKey(pty()), id, ops.clone)}
                             />
                           </div>
                         )}

packages/app/src/utils/server.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test"
+import { authFromToken, authTokenFromCredentials } from "./server"
+
+describe("authFromToken", () => {
+  test("decodes basic auth credentials from auth_token", () => {
+    expect(authFromToken(btoa("kit:secret"))).toEqual({ username: "kit", password: "secret" })
+  })
+
+  test("defaults blank username to opencode", () => {
+    expect(authFromToken(btoa(":secret"))).toEqual({ username: "opencode", password: "secret" })
+  })
+
+  test("ignores malformed tokens", () => {
+    expect(authFromToken("not base64")).toBeUndefined()
+    expect(authFromToken(btoa("missing-separator"))).toBeUndefined()
+  })
+})
+
+describe("authTokenFromCredentials", () => {
+  test("encodes credentials with the default username", () => {
+    expect(authTokenFromCredentials({ password: "secret" })).toBe(btoa("opencode:secret"))
+  })
+})

packages/app/src/utils/server.ts

@@ -1,5 +1,21 @@
 import { createOpencodeClient } from "@opencode-ai/sdk/v2/client"
 import type { ServerConnection } from "@/context/server"
+import { decode64 } from "@/utils/base64"
+
+export function authTokenFromCredentials(input: { username?: string; password: string }) {
+  return btoa(`${input.username ?? "opencode"}:${input.password}`)
+}
+
+export function authFromToken(token: string | null) {
+  const decoded = decode64(token ?? undefined)
+  if (!decoded) return
+  const separator = decoded.indexOf(":")
+  if (separator === -1) return
+  return {
+    username: decoded.slice(0, separator) || "opencode",
+    password: decoded.slice(separator + 1),
+  }
+}
 
 export function createSdkForServer({
   server,
@@ -10,7 +26,7 @@ export function createSdkForServer({
   const auth = (() => {
     if (!server.password) return
     return {
-      Authorization: `Basic ${btoa(`${server.username ?? "opencode"}:${server.password}`)}`,
+      Authorization: `Basic ${authTokenFromCredentials({ username: server.username, password: server.password })}`,
     }
   })()
 

packages/app/src/utils/terminal-websocket-url.test.ts

@@ -19,7 +19,7 @@ describe("terminalWebSocketURL", () => {
     expect(url.searchParams.get("auth_token")).toBe(btoa("opencode:secret"))
   })
 
-  test("omits query auth for same-origin websocket URL", () => {
+  test("omits query auth for same-origin saved credentials", () => {
     const url = terminalWebSocketURL({
       url: "https://app.example.test",
       id: "pty_test",
@@ -33,4 +33,20 @@ describe("terminalWebSocketURL", () => {
     expect(url.protocol).toBe("wss:")
     expect(url.searchParams.has("auth_token")).toBe(false)
   })
+
+  test("uses query auth for same-origin credentials from auth_token", () => {
+    const url = terminalWebSocketURL({
+      url: "https://app.example.test",
+      id: "pty_test",
+      directory: "/tmp/project",
+      cursor: 10,
+      sameOrigin: true,
+      username: "opencode",
+      password: "secret",
+      authToken: true,
+    })
+
+    expect(url.protocol).toBe("wss:")
+    expect(url.searchParams.get("auth_token")).toBe(btoa("opencode:secret"))
+  })
 })

packages/app/src/utils/terminal-websocket-url.ts

@@ -1,17 +1,28 @@
+import { authTokenFromCredentials } from "@/utils/server"
+
 export function terminalWebSocketURL(input: {
   url: string
   id: string
   directory: string
   cursor: number
-  sameOrigin: boolean
-  username: string
+  ticket?: string
+  sameOrigin?: boolean
+  username?: string
   password?: string
+  authToken?: boolean
 }) {
   const next = new URL(`${input.url}/pty/${input.id}/connect`)
   next.searchParams.set("directory", input.directory)
   next.searchParams.set("cursor", String(input.cursor))
   next.protocol = next.protocol === "https:" ? "wss:" : "ws:"
-  if (!input.sameOrigin && input.password)
-    next.searchParams.set("auth_token", btoa(`${input.username}:${input.password}`))
+  if (input.ticket) {
+    next.searchParams.set("ticket", input.ticket)
+    return next
+  }
+  if (input.password && (!input.sameOrigin || input.authToken))
+    next.searchParams.set(
+      "auth_token",
+      authTokenFromCredentials({ username: input.username, password: input.password }),
+    )
   return next
 }

packages/opencode/src/cli/cmd/providers.ts

@@ -1,9 +1,8 @@
 import { Auth } from "../../auth"
-import { AppRuntime } from "../../effect/app-runtime"
 import { cmd } from "./cmd"
-import { effectCmd } from "../effect-cmd"
-import * as prompts from "@clack/prompts"
+import { CliError, effectCmd, fail } from "../effect-cmd"
 import { UI } from "../ui"
+import * as Prompt from "../effect/prompt"
 import { ModelsDev } from "@/provider/models"
 
 import { map, pipe, sortBy, values } from "remeda"
@@ -14,44 +13,57 @@ import { Global } from "@opencode-ai/core/global"
 import { Plugin } from "../../plugin"
 import type { Hooks } from "@opencode-ai/plugin"
 import { Process } from "@/util/process"
+import { errorMessage } from "@/util/error"
 import { text } from "node:stream/consumers"
-import { Effect } from "effect"
+import { Effect, Option } from "effect"
 
 type PluginAuth = NonNullable<Hooks["auth"]>
 
-const put = (key: string, info: Auth.Info) =>
-  AppRuntime.runPromise(
-    Effect.gen(function* () {
-      const auth = yield* Auth.Service
-      yield* auth.set(key, info)
-    }),
-  )
+const promptValue = <Value>(value: Option.Option<Value>) => {
+  if (Option.isNone(value)) return Effect.die(new UI.CancelledError())
+  return Effect.succeed(value.value)
+}
 
-async function handlePluginAuth(plugin: { auth: PluginAuth }, provider: string, methodName?: string): Promise<boolean> {
-  let index = 0
-  if (methodName) {
+const put = Effect.fn("Cli.providers.put")(function* (key: string, info: Auth.Info) {
+  const auth = yield* Auth.Service
+  yield* Effect.orDie(auth.set(key, info))
+})
+
+const cliTry = <Value>(message: string, fn: () => PromiseLike<Value>) =>
+  Effect.tryPromise({
+    try: fn,
+    catch: (error) => new CliError({ message: message + errorMessage(error) }),
+  })
+
+const handlePluginAuth = Effect.fn("Cli.providers.pluginAuth")(function* (
+  plugin: { auth: PluginAuth },
+  provider: string,
+  methodName?: string,
+) {
+  const index = yield* Effect.gen(function* () {
+    if (!methodName) {
+      if (plugin.auth.methods.length <= 1) return 0
+      return yield* promptValue(
+        yield* Prompt.select({
+          message: "Login method",
+          options: plugin.auth.methods.map((x, index) => ({
+            label: x.label,
+            value: index,
+          })),
+        }),
+      )
+    }
     const match = plugin.auth.methods.findIndex((x) => x.label.toLowerCase() === methodName.toLowerCase())
     if (match === -1) {
-      prompts.log.error(
+      return yield* fail(
         `Unknown method "${methodName}" for ${provider}. Available: ${plugin.auth.methods.map((x) => x.label).join(", ")}`,
       )
-      process.exit(1)
     }
-    index = match
-  } else if (plugin.auth.methods.length > 1) {
-    const method = await prompts.select({
-      message: "Login method",
-      options: plugin.auth.methods.map((x, index) => ({
-        label: x.label,
-        value: index.toString(),
-      })),
-    })
-    if (prompts.isCancel(method)) throw new UI.CancelledError()
-    index = parseInt(method)
-  }
+    return match
+  })
   const method = plugin.auth.methods[index]
 
-  await new Promise((r) => setTimeout(r, 10))
+  yield* Effect.sleep("10 millis")
   const inputs: Record<string, string> = {}
   if (method.prompts) {
     for (const prompt of method.prompts) {
@@ -63,46 +75,44 @@ async function handlePluginAuth(plugin: { auth: PluginAuth }, provider: string,
       }
       if (prompt.condition && !prompt.condition(inputs)) continue
       if (prompt.type === "select") {
-        const value = await prompts.select({
+        const value = yield* Prompt.select({
           message: prompt.message,
           options: prompt.options,
         })
-        if (prompts.isCancel(value)) throw new UI.CancelledError()
-        inputs[prompt.key] = value
-      } else {
-        const value = await prompts.text({
-          message: prompt.message,
-          placeholder: prompt.placeholder,
-          validate: prompt.validate ? (v) => prompt.validate!(v ?? "") : undefined,
-        })
-        if (prompts.isCancel(value)) throw new UI.CancelledError()
-        inputs[prompt.key] = value
+        inputs[prompt.key] = yield* promptValue(value)
+        continue
       }
+      const value = yield* Prompt.text({
+        message: prompt.message,
+        placeholder: prompt.placeholder,
+        validate: prompt.validate ? (v) => prompt.validate!(v ?? "") : undefined,
+      })
+      inputs[prompt.key] = yield* promptValue(value)
     }
   }
 
   if (method.type === "oauth") {
-    const authorize = await method.authorize(inputs)
+    const authorize = yield* cliTry("Failed to authorize: ", () => method.authorize(inputs))
 
     if (authorize.url) {
-      prompts.log.info("Go to: " + authorize.url)
+      yield* Prompt.log.info("Go to: " + authorize.url)
     }
 
     if (authorize.method === "auto") {
       if (authorize.instructions) {
-        prompts.log.info(authorize.instructions)
+        yield* Prompt.log.info(authorize.instructions)
       }
-      const spinner = prompts.spinner()
-      spinner.start("Waiting for authorization...")
-      const result = await authorize.callback()
+      const spinner = Prompt.spinner()
+      yield* spinner.start("Waiting for authorization...")
+      const result = yield* cliTry("Failed to authorize: ", () => authorize.callback())
       if (result.type === "failed") {
-        spinner.stop("Failed to authorize", 1)
+        yield* spinner.stop("Failed to authorize", 1)
       }
       if (result.type === "success") {
         const saveProvider = result.provider ?? provider
         if ("refresh" in result) {
           const { type: _, provider: __, refresh, access, expires, ...extraFields } = result
-          await put(saveProvider, {
+          yield* put(saveProvider, {
             type: "oauth",
             refresh,
             access,
@@ -111,30 +121,30 @@ async function handlePluginAuth(plugin: { auth: PluginAuth }, provider: string,
           })
         }
         if ("key" in result) {
-          await put(saveProvider, {
+          yield* put(saveProvider, {
             type: "api",
             key: result.key,
           })
         }
-        spinner.stop("Login successful")
+        yield* spinner.stop("Login successful")
       }
     }
 
     if (authorize.method === "code") {
-      const code = await prompts.text({
+      const code = yield* Prompt.text({
         message: "Paste the authorization code here: ",
         validate: (x) => (x && x.length > 0 ? undefined : "Required"),
       })
-      if (prompts.isCancel(code)) throw new UI.CancelledError()
-      const result = await authorize.callback(code)
+      const authorizationCode = yield* promptValue(code)
+      const result = yield* cliTry("Failed to authorize: ", () => authorize.callback(authorizationCode))
       if (result.type === "failed") {
-        prompts.log.error("Failed to authorize")
+        yield* Prompt.log.error("Failed to authorize")
       }
       if (result.type === "success") {
         const saveProvider = result.provider ?? provider
         if ("refresh" in result) {
           const { type: _, provider: __, refresh, access, expires, ...extraFields } = result
-          await put(saveProvider, {
+          yield* put(saveProvider, {
             type: "oauth",
             refresh,
             access,
@@ -143,56 +153,57 @@ async function handlePluginAuth(plugin: { auth: PluginAuth }, provider: string,
           })
         }
         if ("key" in result) {
-          await put(saveProvider, {
+          yield* put(saveProvider, {
             type: "api",
             key: result.key,
           })
         }
-        prompts.log.success("Login successful")
+        yield* Prompt.log.success("Login successful")
       }
     }
 
-    prompts.outro("Done")
+    yield* Prompt.outro("Done")
     return true
   }
 
   if (method.type === "api") {
-    const key = await prompts.password({
+    const key = yield* Prompt.password({
       message: "Enter your API key",
       validate: (x) => (x && x.length > 0 ? undefined : "Required"),
     })
-    if (prompts.isCancel(key)) throw new UI.CancelledError()
+    const apiKey = yield* promptValue(key)
 
     const metadata = Object.keys(inputs).length ? { metadata: inputs } : {}
-    if (!method.authorize) {
-      await put(provider, {
+    const authorizeApi = method.authorize
+    if (!authorizeApi) {
+      yield* put(provider, {
         type: "api",
-        key,
+        key: apiKey,
         ...metadata,
       })
-      prompts.outro("Done")
+      yield* Prompt.outro("Done")
       return true
     }
 
-    const result = await method.authorize(inputs)
+    const result = yield* cliTry("Failed to authorize: ", () => authorizeApi(inputs))
     if (result.type === "failed") {
-      prompts.log.error("Failed to authorize")
+      yield* Prompt.log.error("Failed to authorize")
     }
     if (result.type === "success") {
       const saveProvider = result.provider ?? provider
-      await put(saveProvider, {
+      yield* put(saveProvider, {
         type: "api",
-        key: result.key ?? key,
+        key: result.key ?? apiKey,
         ...metadata,
       })
-      prompts.log.success("Login successful")
+      yield* Prompt.log.success("Login successful")
     }
-    prompts.outro("Done")
+    yield* Prompt.outro("Done")
     return true
   }
 
   return false
-}
+})
 
 export function resolvePluginProviders(input: {
   hooks: Hooks[]
@@ -244,16 +255,16 @@ export const ProvidersListCommand = effectCmd({
     const authPath = path.join(Global.Path.data, "auth.json")
     const homedir = os.homedir()
     const displayPath = authPath.startsWith(homedir) ? authPath.replace(homedir, "~") : authPath
-    prompts.intro(`Credentials ${UI.Style.TEXT_DIM}${displayPath}`)
+    yield* Prompt.intro(`Credentials ${UI.Style.TEXT_DIM}${displayPath}`)
     const results = Object.entries(yield* Effect.orDie(authSvc.all()))
     const database = yield* modelsDev.get()
 
     for (const [providerID, result] of results) {
       const name = database[providerID]?.name || providerID
-      prompts.log.info(`${name} ${UI.Style.TEXT_DIM}${result.type}`)
+      yield* Prompt.log.info(`${name} ${UI.Style.TEXT_DIM}${result.type}`)
     }
 
-    prompts.outro(`${results.length} credentials`)
+    yield* Prompt.outro(`${results.length} credentials`)
 
     const activeEnvVars: Array<{ provider: string; envVar: string }> = []
 
@@ -270,13 +281,13 @@ export const ProvidersListCommand = effectCmd({
 
     if (activeEnvVars.length > 0) {
       UI.empty()
-      prompts.intro("Environment")
+      yield* Prompt.intro("Environment")
 
       for (const { provider, envVar } of activeEnvVars) {
-        prompts.log.info(`${provider} ${UI.Style.TEXT_DIM}${envVar}`)
+        yield* Prompt.log.info(`${provider} ${UI.Style.TEXT_DIM}${envVar}`)
       }
 
-      prompts.outro(`${activeEnvVars.length} environment variable` + (activeEnvVars.length === 1 ? "" : "s"))
+      yield* Prompt.outro(`${activeEnvVars.length} environment variable` + (activeEnvVars.length === 1 ? "" : "s"))
     }
   }),
 })
@@ -301,36 +312,42 @@ export const ProvidersLoginCommand = effectCmd({
         type: "string",
       }),
   handler: Effect.fn("Cli.providers.login")(function* (args) {
-    const cfgSvc = yield* Config.Service
-    const pluginSvc = yield* Plugin.Service
-    const modelsDev = yield* ModelsDev.Service
     const authSvc = yield* Auth.Service
 
     UI.empty()
-    prompts.intro("Add credential")
+    yield* Prompt.intro("Add credential")
     if (args.url) {
       const url = args.url.replace(/\/+$/, "")
-      const wellknown = (yield* Effect.promise(() => fetch(`${url}/.well-known/opencode`).then((x) => x.json()))) as {
+      const wellknown = (yield* cliTry(`Failed to load auth provider metadata from ${url}: `, () =>
+        fetch(`${url}/.well-known/opencode`).then((x) => x.json()),
+      )) as {
         auth: { command: string[]; env: string }
       }
-      prompts.log.info(`Running \`${wellknown.auth.command.join(" ")}\``)
-      const proc = Process.spawn(wellknown.auth.command, { stdout: "pipe", stderr: "inherit" })
+      yield* Prompt.log.info(`Running \`${wellknown.auth.command.join(" ")}\``)
+      const abort = new AbortController()
+      const proc = Process.spawn(wellknown.auth.command, { stdout: "pipe", stderr: "inherit", abort: abort.signal })
       if (!proc.stdout) {
-        prompts.log.error("Failed")
-        prompts.outro("Done")
+        yield* Prompt.log.error("Failed")
+        yield* Prompt.outro("Done")
         return
       }
-      const [exit, token] = yield* Effect.promise(() => Promise.all([proc.exited, text(proc.stdout!)]))
+      const [exit, token] = yield* cliTry("Failed to run auth provider command: ", () =>
+        Promise.all([proc.exited, text(proc.stdout!)]),
+      ).pipe(Effect.ensuring(Effect.sync(() => abort.abort())))
       if (exit !== 0) {
-        prompts.log.error("Failed")
-        prompts.outro("Done")
+        yield* Prompt.log.error("Failed")
+        yield* Prompt.outro("Done")
         return
       }
       yield* Effect.orDie(authSvc.set(url, { type: "wellknown", key: wellknown.auth.env, token: token.trim() }))
-      prompts.log.success("Logged into " + url)
-      prompts.outro("Done")
+      yield* Prompt.log.success("Logged into " + url)
+      yield* Prompt.outro("Done")
       return
     }
+
+    const cfgSvc = yield* Config.Service
+    const pluginSvc = yield* Plugin.Service
+    const modelsDev = yield* ModelsDev.Service
     yield* Effect.ignore(modelsDev.refresh(true))
 
     const config = yield* cfgSvc.get()
@@ -392,53 +409,46 @@ export const ProvidersLoginCommand = effectCmd({
       const byName = options.find((x) => x.label.toLowerCase() === input.toLowerCase())
       const match = byID ?? byName
       if (!match) {
-        prompts.log.error(`Unknown provider "${input}"`)
-        process.exit(1)
+        return yield* fail(`Unknown provider "${input}"`)
       }
       provider = match.value
     } else {
-      const selected = yield* Effect.promise(() =>
-        prompts.autocomplete({
+      provider = yield* promptValue(
+        yield* Prompt.autocomplete({
           message: "Select provider",
           maxItems: 8,
           options: [...options, { value: "other", label: "Other" }],
         }),
       )
-      if (prompts.isCancel(selected)) yield* Effect.die(new UI.CancelledError())
-      provider = selected as string
     }
 
     const plugin = hooks.findLast((x) => x.auth?.provider === provider)
     if (plugin && plugin.auth) {
-      const handled = yield* Effect.promise(() => handlePluginAuth({ auth: plugin.auth! }, provider, args.method))
+      const handled = yield* handlePluginAuth({ auth: plugin.auth! }, provider, args.method)
       if (handled) return
     }
 
     if (provider === "other") {
-      const custom = yield* Effect.promise(() =>
-        prompts.text({
+      provider = (yield* promptValue(
+        yield* Prompt.text({
           message: "Enter provider id",
           validate: (x) => (x && x.match(/^[0-9a-z-]+$/) ? undefined : "a-z, 0-9 and hyphens only"),
         }),
-      )
-      if (prompts.isCancel(custom)) yield* Effect.die(new UI.CancelledError())
-      provider = (custom as string).replace(/^@ai-sdk\//, "")
+      )).replace(/^@ai-sdk\//, "")
 
       const customPlugin = hooks.findLast((x) => x.auth?.provider === provider)
       if (customPlugin && customPlugin.auth) {
-        const handled = yield* Effect.promise(() =>
-          handlePluginAuth({ auth: customPlugin.auth! }, provider, args.method),
-        )
+        const handled = yield* handlePluginAuth({ auth: customPlugin.auth! }, provider, args.method)
         if (handled) return
       }
 
-      prompts.log.warn(
+      yield* Prompt.log.warn(
         `This only stores a credential for ${provider} - you will need configure it in opencode.json, check the docs for examples.`,
       )
     }
 
     if (provider === "amazon-bedrock") {
-      prompts.log.info(
+      yield* Prompt.log.info(
         "Amazon Bedrock authentication priority:\n" +
           "  1. Bearer token (AWS_BEARER_TOKEN_BEDROCK or /connect)\n" +
           "  2. AWS credential chain (profile, access keys, IAM roles, EKS IRSA)\n\n" +
@@ -448,29 +458,27 @@ export const ProvidersLoginCommand = effectCmd({
     }
 
     if (provider === "opencode") {
-      prompts.log.info("Create an api key at https://opencode.ai/auth")
+      yield* Prompt.log.info("Create an api key at https://opencode.ai/auth")
     }
 
     if (provider === "vercel") {
-      prompts.log.info("You can create an api key at https://vercel.link/ai-gateway-token")
+      yield* Prompt.log.info("You can create an api key at https://vercel.link/ai-gateway-token")
     }
 
     if (["cloudflare", "cloudflare-ai-gateway"].includes(provider)) {
-      prompts.log.info(
+      yield* Prompt.log.info(
         "Cloudflare AI Gateway can be configured with CLOUDFLARE_GATEWAY_ID, CLOUDFLARE_ACCOUNT_ID, and CLOUDFLARE_API_TOKEN environment variables. Read more: https://opencode.ai/docs/providers/#cloudflare-ai-gateway",
       )
     }
 
-    const key = yield* Effect.promise(() =>
-      prompts.password({
-        message: "Enter your API key",
-        validate: (x) => (x && x.length > 0 ? undefined : "Required"),
-      }),
-    )
-    if (prompts.isCancel(key)) yield* Effect.die(new UI.CancelledError())
-    yield* Effect.orDie(authSvc.set(provider, { type: "api", key: key as string }))
+    const key = yield* Prompt.password({
+      message: "Enter your API key",
+      validate: (x) => (x && x.length > 0 ? undefined : "Required"),
+    })
+    const apiKey = yield* promptValue(key)
+    yield* Effect.orDie(authSvc.set(provider, { type: "api", key: apiKey }))
 
-    prompts.outro("Done")
+    yield* Prompt.outro("Done")
   }),
 })
 
@@ -485,24 +493,20 @@ export const ProvidersLogoutCommand = effectCmd({
 
     UI.empty()
     const credentials: Array<[string, Auth.Info]> = Object.entries(yield* Effect.orDie(authSvc.all()))
-    prompts.intro("Remove credential")
+    yield* Prompt.intro("Remove credential")
     if (credentials.length === 0) {
-      prompts.log.error("No credentials found")
+      yield* Prompt.log.error("No credentials found")
       return
     }
     const database = yield* modelsDev.get()
-    const selected = yield* Effect.promise(() =>
-      prompts.select({
-        message: "Select provider",
-        options: credentials.map(([key, value]) => ({
-          label: (database[key]?.name || key) + UI.Style.TEXT_DIM + " (" + value.type + ")",
-          value: key,
-        })),
-      }),
-    )
-    if (prompts.isCancel(selected)) yield* Effect.die(new UI.CancelledError())
-    const providerID = selected as string
-    yield* Effect.orDie(authSvc.remove(providerID))
-    prompts.outro("Logout successful")
+    const selected = yield* Prompt.select({
+      message: "Select provider",
+      options: credentials.map(([key, value]) => ({
+        label: (database[key]?.name || key) + UI.Style.TEXT_DIM + " (" + value.type + ")",
+        value: key,
+      })),
+    })
+    yield* Effect.orDie(authSvc.remove(yield* promptValue(selected)))
+    yield* Prompt.outro("Logout successful")
   }),
 })

packages/opencode/src/cli/effect/prompt.ts

@@ -6,15 +6,27 @@ export const outro = (msg: string) => Effect.sync(() => prompts.outro(msg))
 
 export const log = {
   info: (msg: string) => Effect.sync(() => prompts.log.info(msg)),
+  error: (msg: string) => Effect.sync(() => prompts.log.error(msg)),
+  warn: (msg: string) => Effect.sync(() => prompts.log.warn(msg)),
+  success: (msg: string) => Effect.sync(() => prompts.log.success(msg)),
+}
+
+const optional = <Value>(result: Value | symbol) => {
+  if (prompts.isCancel(result)) return Option.none<Value>()
+  return Option.some(result)
 }
 
 export const select = <Value>(opts: Parameters<typeof prompts.select<Value>>[0]) =>
-  Effect.tryPromise(() => prompts.select(opts)).pipe(
-    Effect.map((result) => {
-      if (prompts.isCancel(result)) return Option.none<Value>()
-      return Option.some(result)
-    }),
-  )
+  Effect.promise(() => prompts.select(opts)).pipe(Effect.map((result) => optional(result)))
+
+export const autocomplete = <Value>(opts: Parameters<typeof prompts.autocomplete<Value>>[0]) =>
+  Effect.promise(() => prompts.autocomplete(opts)).pipe(Effect.map((result) => optional(result)))
+
+export const text = (opts: Parameters<typeof prompts.text>[0]) =>
+  Effect.promise(() => prompts.text(opts)).pipe(Effect.map((result) => optional(result)))
+
+export const password = (opts: Parameters<typeof prompts.password>[0]) =>
+  Effect.promise(() => prompts.password(opts)).pipe(Effect.map((result) => optional(result)))
 
 export const spinner = () => {
   const s = prompts.spinner()

packages/opencode/src/effect/app-runtime.ts

@@ -46,6 +46,7 @@ import { Vcs } from "@/project/vcs"
 import { Workspace } from "@/control-plane/workspace"
 import { Worktree } from "@/worktree"
 import { Pty } from "@/pty"
+import { PtyTicket } from "@/pty/ticket"
 import { Installation } from "@/installation"
 import { ShareNext } from "@/share/share-next"
 import { SessionShare } from "@/share/session"
@@ -98,6 +99,7 @@ export const AppLayer = Layer.mergeAll(
   Workspace.defaultLayer,
   Worktree.appLayer,
   Pty.defaultLayer,
+  PtyTicket.defaultLayer,
   Installation.defaultLayer,
   ShareNext.defaultLayer,
   SessionShare.defaultLayer,

packages/opencode/src/plugin/codex.ts

@@ -14,7 +14,14 @@ const ISSUER = "https://auth.openai.com"
 const CODEX_API_ENDPOINT = "https://chatgpt.com/backend-api/codex/responses"
 const OAUTH_PORT = 1455
 const OAUTH_POLLING_SAFETY_MARGIN_MS = 3000
-const ALLOWED_MODELS = new Set(["gpt-5.5", "gpt-5.2", "gpt-5.3-codex", "gpt-5.4", "gpt-5.4-mini"])
+const ALLOWED_MODELS = new Set([
+  "gpt-5.5",
+  "gpt-5.2",
+  "gpt-5.3-codex",
+  "gpt-5.3-codex-spark",
+  "gpt-5.4",
+  "gpt-5.4-mini",
+])
 
 interface PkceCodes {
   verifier: string

packages/opencode/src/pty/ticket.ts

@@ -0,0 +1,68 @@
+export * as PtyTicket from "./ticket"
+
+import { WorkspaceID } from "@/control-plane/schema"
+import { InstanceRef, WorkspaceRef } from "@/effect/instance-ref"
+import { PtyID } from "@/pty/schema"
+import { PositiveInt } from "@/util/schema"
+import { Cache, Context, Duration, Effect, Layer, Schema } from "effect"
+
+const DEFAULT_TTL = Duration.seconds(60)
+const CAPACITY = 10_000
+
+export const ConnectToken = Schema.Struct({
+  ticket: Schema.String,
+  expires_in: PositiveInt,
+})
+
+export type Scope = {
+  readonly ptyID: PtyID
+  readonly directory?: string
+  readonly workspaceID?: WorkspaceID
+}
+
+export interface Interface {
+  issue(input: Scope): Effect.Effect<typeof ConnectToken.Type>
+  consume(input: Scope & { readonly ticket: string }): Effect.Effect<boolean>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/PtyTicket") {}
+
+function matches(record: Scope, input: Scope) {
+  return (
+    record.ptyID === input.ptyID && record.directory === input.directory && record.workspaceID === input.workspaceID
+  )
+}
+
+// Tickets are inserted via Cache.set and removed atomically via invalidateWhen. The lookup is
+// never invoked; it dies if it ever is, which would signal a misuse of the Service interface.
+const noLookup = () => Effect.die("PtyTicket cache must be used via set/invalidateWhen, never get")
+
+// Visible for tests so the TTL can be shortened. Production uses `layer` with the default TTL.
+export const make = (ttl: Duration.Input = DEFAULT_TTL) =>
+  Effect.gen(function* () {
+    const cache = yield* Cache.make<string, Scope>({ capacity: CAPACITY, lookup: noLookup, timeToLive: ttl })
+    const expiresIn = Math.max(1, Math.round(Duration.toSeconds(Duration.fromInputUnsafe(ttl))))
+    return Service.of({
+      issue: Effect.fn("PtyTicket.issue")(function* (input) {
+        const ticket = crypto.randomUUID()
+        yield* Cache.set(cache, ticket, input)
+        return { ticket, expires_in: expiresIn }
+      }),
+      consume: Effect.fn("PtyTicket.consume")(function* (input) {
+        return yield* Cache.invalidateWhen(cache, input.ticket, (stored) => matches(stored, input))
+      }),
+    })
+  })
+
+export const layer = Layer.effect(Service, make())
+
+export const defaultLayer = layer
+
+export const scope = Effect.gen(function* () {
+  const instance = yield* InstanceRef
+  const workspaceID = yield* WorkspaceRef
+  return {
+    directory: instance?.directory,
+    workspaceID,
+  }
+})

packages/opencode/src/server/cors.ts

@@ -1,7 +1,13 @@
+import { Context } from "effect"
+
 const opencodeOrigin = /^https:\/\/([a-z0-9-]+\.)*opencode\.ai$/
 
 export type CorsOptions = { readonly cors?: ReadonlyArray<string> }
 
+export const CorsConfig = Context.Reference<CorsOptions | undefined>("@opencode/ServerCorsConfig", {
+  defaultValue: () => undefined,
+})
+
 export function isAllowedCorsOrigin(input: string | undefined, opts?: CorsOptions) {
   if (!input) return true
   if (input.startsWith("http://localhost:")) return true
@@ -12,3 +18,17 @@ export function isAllowedCorsOrigin(input: string | undefined, opts?: CorsOption
   if (opencodeOrigin.test(input)) return true
   return opts?.cors?.includes(input) ?? false
 }
+
+export function isAllowedRequestOrigin(input: string | undefined, host: string | undefined, opts?: CorsOptions) {
+  if (!input) return true
+  if (host && sameHost(input, host)) return true
+  return isAllowedCorsOrigin(input, opts)
+}
+
+function sameHost(origin: string, host: string) {
+  try {
+    return new URL(origin).host === host
+  } catch {
+    return false
+  }
+}

packages/opencode/src/server/error.ts

@@ -21,6 +21,9 @@ export const ERRORS = {
       },
     },
   },
+  403: {
+    description: "Forbidden",
+  },
   404: {
     description: "Not found",
     content: {

packages/opencode/src/server/middleware.ts

@@ -12,6 +12,8 @@ import { cors } from "hono/cors"
 import { compress } from "hono/compress"
 import * as ServerBackend from "./backend"
 import { isAllowedCorsOrigin, type CorsOptions } from "./cors"
+import { isPtyConnectPath, PTY_CONNECT_TICKET_QUERY } from "./shared/pty-ticket"
+import { isPublicUIPath } from "./shared/public-ui"
 
 const log = Log.create({ service: "server" })
 
@@ -44,6 +46,8 @@ export const AuthMiddleware: MiddlewareHandler = (c, next) => {
   if (c.req.method === "OPTIONS") return next()
   const password = Flag.OPENCODE_SERVER_PASSWORD
   if (!password) return next()
+  if (isPublicUIPath(c.req.method, c.req.path)) return next()
+  if (isPtyConnectPath(c.req.path) && c.req.query(PTY_CONNECT_TICKET_QUERY)) return next()
   const username = Flag.OPENCODE_SERVER_USERNAME ?? "opencode"
 
   if (c.req.query("auth_token")) c.req.raw.headers.set("authorization", `Basic ${c.req.query("auth_token")}`)
@@ -58,6 +62,7 @@ export function LoggerMiddleware(backendAttributes: ServerBackend.Attributes): M
     const attributes = {
       method: c.req.method,
       path: c.req.path,
+      // If this logger grows full-URL fields, redact auth_token and ticket query params.
       ...backendAttributes,
     }
     log.info("request", attributes)

packages/opencode/src/server/routes/instance/httpapi/groups/pty.ts

@@ -1,4 +1,5 @@
 import { Pty } from "@/pty"
+import { PtyTicket } from "@/pty/ticket"
 import { PtyID } from "@/pty/schema"
 import { Schema } from "effect"
 import { HttpApi, HttpApiEndpoint, HttpApiError, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
@@ -23,6 +24,7 @@ export const PtyPaths = {
   get: `${root}/:ptyID`,
   update: `${root}/:ptyID`,
   remove: `${root}/:ptyID`,
+  connectToken: `${root}/:ptyID/connect-token`,
   connect: `${root}/:ptyID/connect`,
 } as const
 
@@ -93,6 +95,17 @@ export const PtyApi = HttpApi.make("pty")
             description: "Remove and terminate a specific pseudo-terminal (PTY) session.",
           }),
         ),
+        HttpApiEndpoint.post("connectToken", PtyPaths.connectToken, {
+          params: { ptyID: PtyID },
+          success: described(PtyTicket.ConnectToken, "WebSocket connect token"),
+          error: [HttpApiError.Forbidden, HttpApiError.NotFound],
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "pty.connectToken",
+            summary: "Create PTY WebSocket token",
+            description: "Create a short-lived ticket for opening a PTY WebSocket connection.",
+          }),
+        ),
       )
       .annotateMerge(OpenApi.annotations({ title: "pty", description: "Experimental HttpApi PTY routes." }))
       .middleware(InstanceContextMiddleware)
@@ -113,7 +126,7 @@ export const PtyConnectApi = HttpApi.make("pty-connect").add(
       HttpApiEndpoint.get("connect", PtyPaths.connect, {
         params: Params,
         success: described(Schema.Boolean, "Connected session"),
-        error: HttpApiError.NotFound,
+        error: [HttpApiError.Forbidden, HttpApiError.NotFound],
       }).annotateMerge(
         OpenApi.annotations({
           identifier: "pty.connect",

packages/opencode/src/server/routes/instance/httpapi/handlers/pty.ts

@@ -1,8 +1,15 @@
 import { Pty } from "@/pty"
 import { PtyID } from "@/pty/schema"
+import { PtyTicket } from "@/pty/ticket"
 import { handlePtyInput } from "@/pty/input"
 import { Shell } from "@/shell/shell"
 import { EffectBridge } from "@/effect/bridge"
+import { CorsConfig, isAllowedRequestOrigin, type CorsOptions } from "@/server/cors"
+import {
+  PTY_CONNECT_TICKET_QUERY,
+  PTY_CONNECT_TOKEN_HEADER,
+  PTY_CONNECT_TOKEN_HEADER_VALUE,
+} from "@/server/shared/pty-ticket"
 import { Effect } from "effect"
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
 import { HttpApiBuilder, HttpApiError } from "effect/unstable/httpapi"
@@ -11,9 +18,15 @@ import { InstanceHttpApi } from "../api"
 import { CursorQuery, Params, PtyPaths } 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)
+}
+
 export const ptyHandlers = HttpApiBuilder.group(InstanceHttpApi, "pty", (handlers) =>
   Effect.gen(function* () {
     const pty = yield* Pty.Service
+    const tickets = yield* PtyTicket.Service
+    const cors = yield* CorsConfig
 
     const shells = Effect.fn("PtyHttpApi.shells")(function* () {
       return yield* Effect.promise(() => Shell.list())
@@ -54,6 +67,14 @@ export const ptyHandlers = HttpApiBuilder.group(InstanceHttpApi, "pty", (handler
       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 HttpApiError.Forbidden({})
+      if (!(yield* pty.get(ctx.params.ptyID))) return yield* new HttpApiError.NotFound({})
+      return yield* tickets.issue({ ptyID: ctx.params.ptyID, ...(yield* PtyTicket.scope) })
+    })
+
     return handlers
       .handle("shells", shells)
       .handle("list", list)
@@ -61,12 +82,15 @@ export const ptyHandlers = HttpApiBuilder.group(InstanceHttpApi, "pty", (handler
       .handle("get", get)
       .handle("update", update)
       .handle("remove", remove)
+      .handle("connectToken", connectToken)
   }),
 )
 
 export const ptyConnectRoute = HttpRouter.use((router) =>
   Effect.gen(function* () {
     const pty = yield* Pty.Service
+    const tickets = yield* PtyTicket.Service
+    const cors = yield* CorsConfig
     yield* router.add(
       "GET",
       PtyPaths.connect,
@@ -75,12 +99,20 @@ export const ptyConnectRoute = HttpRouter.use((router) =>
         if (!(yield* pty.get(params.ptyID))) return HttpServerResponse.empty({ status: 404 })
 
         const query = yield* HttpServerRequest.schemaSearchParams(CursorQuery)
+        const request = yield* HttpServerRequest.HttpServerRequest
+        const ticket = new URL(request.url, "http://localhost").searchParams.get(PTY_CONNECT_TICKET_QUERY)
+        if (ticket) {
+          const valid = validOrigin(request, cors)
+            ? yield* tickets.consume({ ticket, ptyID: params.ptyID, ...(yield* PtyTicket.scope) })
+            : false
+          if (!valid) return HttpServerResponse.empty({ status: 403 })
+        }
         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 socket = yield* Effect.orDie(request.upgrade)
         const write = yield* socket.writer
         const closeAccepted = (event: Socket.CloseEvent) =>
           socket

packages/opencode/src/server/routes/instance/httpapi/middleware/authorization.ts

@@ -2,6 +2,8 @@ import { ServerAuth } from "@/server/auth"
 import { Effect, Encoding, Layer, Redacted } from "effect"
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
 import { HttpApiError, HttpApiMiddleware } from "effect/unstable/httpapi"
+import { hasPtyConnectTicketURL } from "@/server/shared/pty-ticket"
+import { isPublicUIPath } from "@/server/shared/public-ui"
 
 const AUTH_TOKEN_QUERY = "auth_token"
 const UNAUTHORIZED = 401
@@ -55,7 +57,11 @@ function decodeCredential(input: string) {
 }
 
 function credentialFromRequest(request: HttpServerRequest.HttpServerRequest) {
-  const token = new URL(request.url, "http://localhost").searchParams.get(AUTH_TOKEN_QUERY)
+  return credentialFromURL(new URL(request.url, "http://localhost"), request)
+}
+
+function credentialFromURL(url: URL, request: HttpServerRequest.HttpServerRequest) {
+  const token = url.searchParams.get(AUTH_TOKEN_QUERY)
   if (token) return decodeCredential(token)
   const match = /^Basic\s+(.+)$/i.exec(request.headers.authorization ?? "")
   if (match) return decodeCredential(match[1])
@@ -86,7 +92,10 @@ export const authorizationRouterMiddleware = HttpRouter.middleware()(
     return (effect) =>
       Effect.gen(function* () {
         const request = yield* HttpServerRequest.HttpServerRequest
-        return yield* credentialFromRequest(request).pipe(
+        const url = new URL(request.url, "http://localhost")
+        if (isPublicUIPath(request.method, url.pathname)) return yield* effect
+        if (hasPtyConnectTicketURL(url)) return yield* effect
+        return yield* credentialFromURL(url, request).pipe(
           Effect.flatMap((credential) => validateRawCredential(effect, credential, config)),
         )
       })

packages/opencode/src/server/routes/instance/httpapi/middleware/error.ts

@@ -0,0 +1,58 @@
+import { Provider } from "@/provider/provider"
+import { Session } from "@/session/session"
+import { NotFoundError } from "@/storage/storage"
+import { iife } from "@/util/iife"
+import { NamedError } from "@opencode-ai/core/util/error"
+import * as Log from "@opencode-ai/core/util/log"
+import { Cause, Effect } from "effect"
+import { HttpRouter, HttpServerError, HttpServerRespondable, HttpServerResponse } from "effect/unstable/http"
+
+const log = Log.create({ service: "server" })
+
+// Keep typed HttpApi failures on their declared error path; this boundary only replaces defect-only empty 500s.
+export const errorLayer = HttpRouter.middleware<{ handles: unknown }>()((effect) =>
+  effect.pipe(
+    Effect.catchCause((cause) => {
+      const defect = cause.reasons.filter(Cause.isDieReason).find((reason) => {
+        if (HttpServerResponse.isHttpServerResponse(reason.defect)) return false
+        if (HttpServerError.isHttpServerError(reason.defect)) return false
+        if (HttpServerRespondable.isRespondable(reason.defect)) return false
+        return true
+      })
+      if (!defect) return Effect.failCause(cause)
+
+      const error = defect.defect
+      log.error("failed", { error, cause: Cause.pretty(cause) })
+
+      if (error instanceof NamedError) {
+        return Effect.succeed(
+          HttpServerResponse.jsonUnsafe(error.toObject(), {
+            status: iife(() => {
+              if (error instanceof NotFoundError) return 404
+              if (error instanceof Provider.ModelNotFoundError) return 400
+              if (error.name === "ProviderAuthValidationFailed") return 400
+              if (error.name.startsWith("Worktree")) return 400
+              return 500
+            }),
+          }),
+        )
+      }
+      if (error instanceof Session.BusyError) {
+        return Effect.succeed(
+          HttpServerResponse.jsonUnsafe(new NamedError.Unknown({ message: error.message }).toObject(), {
+            status: 400,
+          }),
+        )
+      }
+
+      return Effect.succeed(
+        HttpServerResponse.jsonUnsafe(
+          new NamedError.Unknown({
+            message: error instanceof Error && error.stack ? error.stack : String(error),
+          }).toObject(),
+          { status: 500 },
+        ),
+      )
+    }),
+  ),
+).layer

packages/opencode/src/server/routes/instance/httpapi/server.ts

@@ -25,6 +25,7 @@ import { ProviderAuth } from "@/provider/auth"
 import { ModelsDev } from "@/provider/models"
 import { Provider } from "@/provider/provider"
 import { Pty } from "@/pty"
+import { PtyTicket } from "@/pty/ticket"
 import { Question } from "@/question"
 import { Session } from "@/session/session"
 import { SessionCompaction } from "@/session/compaction"
@@ -44,7 +45,7 @@ import { lazy } from "@/util/lazy"
 import { Vcs } from "@/project/vcs"
 import { Worktree } from "@/worktree"
 import { Workspace } from "@/control-plane/workspace"
-import { isAllowedCorsOrigin, type CorsOptions } from "@/server/cors"
+import { CorsConfig, isAllowedCorsOrigin, type CorsOptions } from "@/server/cors"
 import { serveUIEffect } from "@/server/shared/ui"
 import { ServerAuth } from "@/server/auth"
 import { InstanceHttpApi, RootHttpApi } from "./api"
@@ -72,6 +73,7 @@ import { workspaceRouterMiddleware, workspaceRoutingLayer } from "./middleware/w
 import { disposeMiddleware } from "./lifecycle"
 import { memoMap } from "@opencode-ai/core/effect/memo-map"
 import * as ServerBackend from "@/server/backend"
+import { errorLayer } from "./middleware/error"
 
 export const context = Context.makeUnsafe<unknown>(new Map())
 
@@ -143,6 +145,7 @@ const uiRoute = HttpRouter.use((router) =>
 export function createRoutes(corsOptions?: CorsOptions) {
   return Layer.mergeAll(rootApiRoutes, eventApiRoutes, instanceRoutes, uiRoute).pipe(
     Layer.provide([
+      errorLayer,
       cors(corsOptions),
       runtime,
       Account.defaultLayer,
@@ -163,6 +166,7 @@ export function createRoutes(corsOptions?: CorsOptions) {
       ProviderAuth.defaultLayer,
       Provider.defaultLayer,
       Pty.defaultLayer,
+      PtyTicket.defaultLayer,
       Question.defaultLayer,
       Ripgrep.defaultLayer,
       Session.defaultLayer,
@@ -187,6 +191,7 @@ export function createRoutes(corsOptions?: CorsOptions) {
       FetchHttpClient.layer,
       HttpServer.layerServices,
     ]),
+    Layer.provideMerge(Layer.succeed(CorsConfig)(corsOptions)),
     Layer.provideMerge(InstanceLayer.layer),
     Layer.provideMerge(Observability.layer),
   )

packages/opencode/src/server/routes/instance/index.ts

@@ -39,10 +39,11 @@ import { SessionPaths } from "./httpapi/groups/session"
 import { SyncPaths } from "./httpapi/groups/sync"
 import { TuiPaths } from "./httpapi/groups/tui"
 import { WorkspacePaths } from "./httpapi/groups/workspace"
+import type { CorsOptions } from "@/server/cors"
 
-export const InstanceRoutes = (upgrade: UpgradeWebSocket): Hono => {
+export const InstanceRoutes = (upgrade: UpgradeWebSocket, opts?: CorsOptions): Hono => {
   const app = new Hono()
-  const handler = ExperimentalHttpApiServer.webHandler().handler
+  const handler = ExperimentalHttpApiServer.webHandler(opts).handler
   const context = Context.empty() as Context.Context<unknown>
 
   app.all("/api/*", (c) => handler(c.req.raw, context))
@@ -107,6 +108,7 @@ export const InstanceRoutes = (upgrade: UpgradeWebSocket): Hono => {
     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.post(PtyPaths.connectToken, (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))
@@ -158,7 +160,7 @@ export const InstanceRoutes = (upgrade: UpgradeWebSocket): Hono => {
 
   return app
     .route("/project", ProjectRoutes())
-    .route("/pty", PtyRoutes(upgrade))
+    .route("/pty", PtyRoutes(upgrade, opts))
     .route("/config", ConfigRoutes())
     .route("/experimental", ExperimentalRoutes())
     .route("/session", SessionRoutes())

packages/opencode/src/server/routes/instance/pty.ts

@@ -1,4 +1,5 @@
 import { Hono } from "hono"
+import type { Context } from "hono"
 import { describeRoute, validator, resolver } from "hono-openapi"
 import type { UpgradeWebSocket } from "hono/ws"
 import { Effect, Schema } from "effect"
@@ -6,10 +7,19 @@ import z from "zod"
 import { AppRuntime } from "@/effect/app-runtime"
 import { Pty } from "@/pty"
 import { PtyID } from "@/pty/schema"
+import { PtyTicket } from "@/pty/ticket"
 import { Shell } from "@/shell/shell"
 import { NotFoundError } from "@/storage/storage"
 import { errors } from "../../error"
 import { jsonRequest, runRequest } from "./trace"
+import { HTTPException } from "hono/http-exception"
+import { isAllowedRequestOrigin, type CorsOptions } from "@/server/cors"
+import {
+  PTY_CONNECT_TICKET_QUERY,
+  PTY_CONNECT_TOKEN_HEADER,
+  PTY_CONNECT_TOKEN_HEADER_VALUE,
+} from "@/server/shared/pty-ticket"
+import { zod as effectZod } from "@/util/effect-zod"
 
 const ShellItem = z.object({
   path: z.string(),
@@ -18,7 +28,11 @@ const ShellItem = z.object({
 })
 const decodePtyID = Schema.decodeUnknownSync(PtyID)
 
-export function PtyRoutes(upgradeWebSocket: UpgradeWebSocket) {
+function validOrigin(c: Context, opts?: CorsOptions) {
+  return isAllowedRequestOrigin(c.req.header("origin"), c.req.header("host"), opts)
+}
+
+export function PtyRoutes(upgradeWebSocket: UpgradeWebSocket, opts?: CorsOptions) {
   return new Hono()
     .get(
       "/shells",
@@ -175,6 +189,43 @@ export function PtyRoutes(upgradeWebSocket: UpgradeWebSocket) {
           return true
         }),
     )
+    .post(
+      "/:ptyID/connect-token",
+      describeRoute({
+        summary: "Create PTY WebSocket token",
+        description: "Create a short-lived token for opening a PTY WebSocket connection.",
+        operationId: "pty.connectToken",
+        responses: {
+          200: {
+            description: "WebSocket connect token",
+            content: {
+              "application/json": {
+                schema: resolver(effectZod(PtyTicket.ConnectToken)),
+              },
+            },
+          },
+          ...errors(403, 404),
+        },
+      }),
+      validator("param", z.object({ ptyID: PtyID.zod })),
+      async (c) => {
+        if (c.req.header(PTY_CONNECT_TOKEN_HEADER) !== PTY_CONNECT_TOKEN_HEADER_VALUE || !validOrigin(c, opts))
+          throw new HTTPException(403)
+        const result = await runRequest(
+          "PtyRoutes.connectToken",
+          c,
+          Effect.gen(function* () {
+            const pty = yield* Pty.Service
+            const id = c.req.valid("param").ptyID
+            if (!(yield* pty.get(id))) return
+            const tickets = yield* PtyTicket.Service
+            return yield* tickets.issue({ ptyID: id, ...(yield* PtyTicket.scope) })
+          }),
+        )
+        if (!result) throw new NotFoundError({ message: "Session not found" })
+        return c.json(result)
+      },
+    )
     .get(
       "/:ptyID/connect",
       describeRoute({
@@ -190,7 +241,7 @@ export function PtyRoutes(upgradeWebSocket: UpgradeWebSocket) {
               },
             },
           },
-          ...errors(404),
+          ...errors(403, 404),
         },
       }),
       validator("param", z.object({ ptyID: PtyID.zod })),
@@ -201,14 +252,6 @@ export function PtyRoutes(upgradeWebSocket: UpgradeWebSocket) {
         }
 
         const id = decodePtyID(c.req.param("ptyID"))
-        const cursor = (() => {
-          const value = c.req.query("cursor")
-          if (!value) return
-          const parsed = Number(value)
-          if (!Number.isSafeInteger(parsed) || parsed < -1) return
-          return parsed
-        })()
-        let handler: Handler | undefined
         if (
           !(await runRequest(
             "PtyRoutes.connect",
@@ -219,8 +262,29 @@ export function PtyRoutes(upgradeWebSocket: UpgradeWebSocket) {
             }),
           ))
         ) {
-          throw new Error("Session not found")
+          throw new NotFoundError({ message: "Session not found" })
         }
+        const ticket = c.req.query(PTY_CONNECT_TICKET_QUERY)
+        if (ticket) {
+          if (!validOrigin(c, opts)) throw new HTTPException(403)
+          const valid = await runRequest(
+            "PtyRoutes.connect.ticket",
+            c,
+            Effect.gen(function* () {
+              const tickets = yield* PtyTicket.Service
+              return yield* tickets.consume({ ticket, ptyID: id, ...(yield* PtyTicket.scope) })
+            }),
+          )
+          if (!valid) throw new HTTPException(403)
+        }
+        const cursor = (() => {
+          const value = c.req.query("cursor")
+          if (!value) return
+          const parsed = Number(value)
+          if (!Number.isSafeInteger(parsed) || parsed < -1) return
+          return parsed
+        })()
+        let handler: Handler | undefined
 
         type Socket = {
           readyState: number

packages/opencode/src/server/server.ts

@@ -120,7 +120,7 @@ function createHono(opts: CorsOptions, selection: ServerBackend.Selection = Serv
       app: app
         .use(InstanceMiddleware(Flag.OPENCODE_WORKSPACE_ID ? WorkspaceID.make(Flag.OPENCODE_WORKSPACE_ID) : undefined))
         .use(FenceMiddleware)
-        .route("/", InstanceRoutes(runtime.upgradeWebSocket)),
+        .route("/", InstanceRoutes(runtime.upgradeWebSocket, opts)),
       runtime,
     }
   }
@@ -136,7 +136,7 @@ function createHono(opts: CorsOptions, selection: ServerBackend.Selection = Serv
     app: app
       .route("/", ControlPlaneRoutes())
       .route("/", workspaceApp)
-      .route("/", InstanceRoutes(runtime.upgradeWebSocket))
+      .route("/", InstanceRoutes(runtime.upgradeWebSocket, opts))
       .route("/", UIRoutes()),
     runtime,
   }

packages/opencode/src/server/shared/pty-ticket.ts

@@ -0,0 +1,15 @@
+export const PTY_CONNECT_TICKET_QUERY = "ticket"
+export const PTY_CONNECT_TOKEN_HEADER = "x-opencode-ticket"
+export const PTY_CONNECT_TOKEN_HEADER_VALUE = "1"
+
+const PTY_CONNECT_PATH = /^\/pty\/[^/]+\/connect$/
+
+// Auth middleware skips Basic Auth when this matches; the PTY connect handler
+// is then responsible for validating the ticket.
+export function isPtyConnectPath(pathname: string) {
+  return PTY_CONNECT_PATH.test(pathname)
+}
+
+export function hasPtyConnectTicketURL(url: URL) {
+  return isPtyConnectPath(url.pathname) && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY)
+}

packages/opencode/src/server/shared/public-ui.ts

@@ -0,0 +1,12 @@
+// Static UI assets the browser fetches without app-managed credentials, e.g.
+// the manifest link in <head>. These bypass auth so the page can install/render
+// the manifest icons even when a server password is configured.
+export const PUBLIC_UI_PATHS = new Set<string>([
+  "/site.webmanifest",
+  "/web-app-manifest-192x192.png",
+  "/web-app-manifest-512x512.png",
+])
+
+export function isPublicUIPath(method: string, pathname: string) {
+  return method === "GET" && PUBLIC_UI_PATHS.has(pathname)
+}

packages/opencode/src/server/shared/ui.ts

@@ -33,6 +33,7 @@ function proxyResponseHeaders(headers: Record<string, string>) {
   // transfer metadata makes browsers decode already-decoded assets again.
   result.delete("content-encoding")
   result.delete("content-length")
+  result.delete("transfer-encoding")
   return result
 }
 

packages/opencode/test/agent/plugin-agent-regression.test.ts

@@ -1,52 +1,65 @@
-import { afterEach, expect, test } from "bun:test"
+import { expect } from "bun:test"
+import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
+import { Effect, Layer } from "effect"
 import path from "path"
 import { pathToFileURL } from "url"
-import { AppRuntime } from "../../src/effect/app-runtime"
 import { Agent } from "../../src/agent/agent"
-import { Instance } from "../../src/project/instance"
-import { WithInstance } from "../../src/project/with-instance"
-import { disposeAllInstances, tmpdir } from "../fixture/fixture"
+import { InstanceRef } from "../../src/effect/instance-ref"
+import { InstanceLayer } from "../../src/project/instance-layer"
+import { InstanceStore } from "../../src/project/instance-store"
+import { tmpdirScoped } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
 
-afterEach(async () => {
-  await disposeAllInstances()
-})
+const pluginAgent = {
+  name: "plugin_added",
+  description: "Added by a plugin via the config hook",
+  mode: "subagent",
+} as const
 
-test("plugin-registered agents appear in Agent.list", async () => {
-  await using tmp = await tmpdir({
-    init: async (dir) => {
-      const pluginFile = path.join(dir, "plugin.ts")
-      await Bun.write(
-        pluginFile,
-        [
-          "export default async () => ({",
-          "  config: async (cfg) => {",
-          "    cfg.agent = cfg.agent ?? {}",
-          "    cfg.agent.plugin_added = {",
-          '      description: "Added by a plugin via the config hook",',
-          '      mode: "subagent",',
-          "    }",
-          "  },",
-          "})",
-          "",
-        ].join("\n"),
-      )
-      await Bun.write(
-        path.join(dir, "opencode.json"),
-        JSON.stringify({
-          $schema: "https://opencode.ai/config.json",
-          plugin: [pathToFileURL(pluginFile).href],
-        }),
-      )
-    },
-  })
+const it = testEffect(Layer.mergeAll(Agent.defaultLayer, InstanceLayer.layer, CrossSpawnSpawner.defaultLayer))
 
-  await WithInstance.provide({
-    directory: tmp.path,
-    fn: async () => {
-      const agents = await AppRuntime.runPromise(Agent.Service.use((svc) => svc.list()))
-      const added = agents.find((agent) => agent.name === "plugin_added")
-      expect(added?.description).toBe("Added by a plugin via the config hook")
-      expect(added?.mode).toBe("subagent")
-    },
-  })
-})
+it.live("plugin-registered agents appear in Agent.list", () =>
+  Effect.gen(function* () {
+    const dir = yield* tmpdirScoped()
+    const pluginFile = path.join(dir, "plugin.ts")
+
+    yield* Effect.promise(async () => {
+      await Promise.all([
+        Bun.write(
+          pluginFile,
+          [
+            "export default async () => ({",
+            "  config: async (cfg) => {",
+            "    cfg.agent = cfg.agent ?? {}",
+            `    cfg.agent[${JSON.stringify(pluginAgent.name)}] = {`,
+            `      description: ${JSON.stringify(pluginAgent.description)},`,
+            `      mode: ${JSON.stringify(pluginAgent.mode)},`,
+            "    }",
+            "  },",
+            "})",
+            "",
+          ].join("\n"),
+        ),
+        Bun.write(
+          path.join(dir, "opencode.json"),
+          JSON.stringify({
+            $schema: "https://opencode.ai/config.json",
+            plugin: [pathToFileURL(pluginFile).href],
+          }),
+        ),
+      ])
+    })
+
+    const agents = yield* InstanceStore.Service.use((store) =>
+      Effect.gen(function* () {
+        const ctx = yield* store.load({ directory: dir })
+        yield* Effect.addFinalizer(() => store.dispose(ctx).pipe(Effect.ignore))
+        return yield* Agent.Service.use((svc) => svc.list()).pipe(Effect.provideService(InstanceRef, ctx))
+      }),
+    )
+    const added = agents.find((agent) => agent.name === pluginAgent.name)
+
+    expect(added?.description).toBe(pluginAgent.description)
+    expect(added?.mode).toBe(pluginAgent.mode)
+  }),
+)

packages/opencode/test/pty/ticket.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { WorkspaceID } from "../../src/control-plane/schema"
+import { PtyID } from "../../src/pty/schema"
+import { PtyTicket } from "../../src/pty/ticket"
+import { testEffect } from "../lib/effect"
+
+const it = testEffect(PtyTicket.layer)
+const itExpiring = testEffect(Layer.effect(PtyTicket.Service, PtyTicket.make(5)))
+
+describe("PTY websocket tickets", () => {
+  it.live("consumes tickets once", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const scope = { ptyID: PtyID.ascending(), directory: "/tmp/a" }
+      const issued = yield* tickets.issue(scope)
+
+      expect(yield* tickets.consume({ ...scope, ticket: issued.ticket })).toBe(true)
+      expect(yield* tickets.consume({ ...scope, ticket: issued.ticket })).toBe(false)
+    }),
+  )
+
+  it.live("rejects tickets scoped to a different request", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const ptyID = PtyID.ascending()
+      const issued = yield* tickets.issue({ ptyID, directory: "/tmp/a" })
+
+      expect(yield* tickets.consume({ ptyID, directory: "/tmp/b", ticket: issued.ticket })).toBe(false)
+      expect(yield* tickets.consume({ ptyID, directory: "/tmp/a", ticket: issued.ticket })).toBe(true)
+    }),
+  )
+
+  itExpiring.live("rejects tickets after the TTL elapses", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const ptyID = PtyID.ascending()
+      const issued = yield* tickets.issue({ ptyID })
+
+      yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, 25)))
+
+      expect(yield* tickets.consume({ ptyID, ticket: issued.ticket })).toBe(false)
+    }),
+  )
+
+  it.live("rejects tickets scoped to a different workspace", () =>
+    Effect.gen(function* () {
+      const tickets = yield* PtyTicket.Service
+      const ptyID = PtyID.ascending()
+      const workspaceID = WorkspaceID.ascending()
+      const issued = yield* tickets.issue({ ptyID, workspaceID })
+
+      expect(yield* tickets.consume({ ptyID, workspaceID: WorkspaceID.ascending(), ticket: issued.ticket })).toBe(false)
+      expect(yield* tickets.consume({ ptyID, workspaceID, ticket: issued.ticket })).toBe(true)
+    }),
+  )
+})

packages/opencode/test/server/httpapi-listen.test.ts

@@ -31,8 +31,8 @@ afterEach(async () => {
   await resetDatabase()
 })
 
-async function startListener() {
-  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = true
+async function startListener(backend: "effect-httpapi" | "hono" = "effect-httpapi") {
+  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = backend === "effect-httpapi"
   Flag.OPENCODE_SERVER_PASSWORD = auth.password
   Flag.OPENCODE_SERVER_USERNAME = auth.username
   process.env.OPENCODE_SERVER_PASSWORD = auth.password
@@ -40,19 +40,53 @@ async function startListener() {
   return Server.listen({ hostname: "127.0.0.1", port: 0 })
 }
 
+async function startNoAuthListener() {
+  Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = false
+  Flag.OPENCODE_SERVER_PASSWORD = undefined
+  Flag.OPENCODE_SERVER_USERNAME = auth.username
+  delete process.env.OPENCODE_SERVER_PASSWORD
+  process.env.OPENCODE_SERVER_USERNAME = auth.username
+  return Server.listen({ hostname: "127.0.0.1", port: 0 })
+}
+
 function authorization() {
   return `Basic ${btoa(`${auth.username}:${auth.password}`)}`
 }
 
-function socketURL(listener: Awaited<ReturnType<typeof startListener>>, id: string, dir: string) {
+function socketURL(listener: Awaited<ReturnType<typeof startListener>>, id: string, dir: string, ticket?: string) {
   const url = new URL(PtyPaths.connect.replace(":ptyID", id), listener.url)
   url.protocol = "ws:"
   url.searchParams.set("directory", dir)
   url.searchParams.set("cursor", "-1")
-  url.searchParams.set("auth_token", btoa(`${auth.username}:${auth.password}`))
+  if (ticket) url.searchParams.set("ticket", ticket)
   return url
 }
 
+async function requestTicket(
+  listener: Awaited<ReturnType<typeof startListener>>,
+  id: string,
+  dir: string,
+  options?: { ticketHeader?: boolean; origin?: string },
+) {
+  const response = await fetch(new URL(PtyPaths.connectToken.replace(":ptyID", id), listener.url), {
+    method: "POST",
+    headers: {
+      authorization: authorization(),
+      "x-opencode-directory": dir,
+      ...(options?.ticketHeader === false ? {} : { "x-opencode-ticket": "1" }),
+      ...(options?.origin ? { origin: options.origin } : {}),
+    },
+  })
+
+  return response
+}
+
+async function connectTicket(listener: Awaited<ReturnType<typeof startListener>>, id: string, dir: string) {
+  const response = await requestTicket(listener, id, dir)
+  expect(response.status).toBe(200)
+  return (await response.json()) as { ticket: string; expires_in: number }
+}
+
 async function createCat(listener: Awaited<ReturnType<typeof startListener>>, dir: string) {
   const response = await fetch(new URL(PtyPaths.create, listener.url), {
     method: "POST",
@@ -81,6 +115,28 @@ async function openSocket(url: URL) {
   return ws
 }
 
+async function expectSocketRejected(url: URL, init?: { headers?: Record<string, string> }) {
+  // Bun's WebSocket accepts an init object with headers; standard DOM types don't reflect that.
+  const Ctor = WebSocket as unknown as new (url: URL, init?: { headers?: Record<string, string> }) => WebSocket
+  const ws = new Ctor(url, init)
+  await withTimeout(
+    new Promise<void>((resolve, reject) => {
+      ws.addEventListener(
+        "open",
+        () => {
+          ws.close(1000)
+          reject(new Error("websocket opened"))
+        },
+        { once: true },
+      )
+      ws.addEventListener("error", () => resolve(), { once: true })
+      ws.addEventListener("close", () => resolve(), { once: true })
+    }),
+    5_000,
+    "timed out waiting for websocket rejection",
+  )
+}
+
 function stop(listener: Awaited<ReturnType<typeof startListener>>, label: string) {
   return withTimeout(listener.stop(true), 10_000, label)
 }
@@ -125,7 +181,9 @@ describe("HttpApi Server.listen", () => {
       )
 
       const info = await createCat(listener, tmp.path)
-      const ws = await openSocket(socketURL(listener, info.id, tmp.path))
+      const ticket = await connectTicket(listener, info.id, tmp.path)
+      expect(ticket.expires_in).toBeGreaterThan(0)
+      const ws = await openSocket(socketURL(listener, info.id, tmp.path, ticket.ticket))
       const closed = new Promise<void>((resolve) => ws.addEventListener("close", () => resolve(), { once: true }))
 
       const message = waitForMessage(ws, (message) => message.includes("ping-listen"))
@@ -140,7 +198,8 @@ describe("HttpApi Server.listen", () => {
       const restarted = await startListener()
       try {
         const nextInfo = await createCat(restarted, tmp.path)
-        const nextWs = await openSocket(socketURL(restarted, nextInfo.id, tmp.path))
+        const nextTicket = await connectTicket(restarted, nextInfo.id, tmp.path)
+        const nextWs = await openSocket(socketURL(restarted, nextInfo.id, tmp.path, nextTicket.ticket))
         const nextMessage = waitForMessage(nextWs, (message) => message.includes("ping-restarted"))
         nextWs.send("ping-restarted\n")
         expect(await nextMessage).toContain("ping-restarted")
@@ -152,4 +211,107 @@ describe("HttpApi Server.listen", () => {
       if (!stopped) await stop(listener, "timed out cleaning up listener").catch(() => undefined)
     }
   })
+
+  testPty("serves PTY websocket tickets through legacy Hono Server.listen", async () => {
+    await using tmp = await tmpdir({ git: true, config: { formatter: false, lsp: false } })
+    const listener = await startListener("hono")
+    try {
+      const info = await createCat(listener, tmp.path)
+      const ticket = await connectTicket(listener, info.id, tmp.path)
+      const ws = await openSocket(socketURL(listener, info.id, tmp.path, ticket.ticket))
+      const message = waitForMessage(ws, (message) => message.includes("ping-hono-ticket"))
+      ws.send("ping-hono-ticket\n")
+      expect(await message).toContain("ping-hono-ticket")
+      ws.close(1000)
+    } finally {
+      await stop(listener, "timed out cleaning up hono listener").catch(() => undefined)
+    }
+  })
+
+  testPty("rejects unsafe PTY ticket mint and connect requests", async () => {
+    await using tmp = await tmpdir({ git: true, config: { formatter: false, lsp: false } })
+    const listener = await startListener()
+    try {
+      const info = await createCat(listener, tmp.path)
+
+      expect((await requestTicket(listener, info.id, tmp.path, { ticketHeader: false })).status).toBe(403)
+      expect((await requestTicket(listener, info.id, tmp.path, { origin: "https://evil.example" })).status).toBe(403)
+
+      await expectSocketRejected(socketURL(listener, info.id, tmp.path, "not-a-ticket"))
+
+      const reusable = await connectTicket(listener, info.id, tmp.path)
+      const ws = await openSocket(socketURL(listener, info.id, tmp.path, reusable.ticket))
+      await expectSocketRejected(socketURL(listener, info.id, tmp.path, reusable.ticket))
+      ws.close(1000)
+
+      const other = await createCat(listener, tmp.path)
+      const scoped = await connectTicket(listener, info.id, tmp.path)
+      await expectSocketRejected(socketURL(listener, other.id, tmp.path, scoped.ticket))
+
+      const crossOrigin = await connectTicket(listener, info.id, tmp.path)
+      await expectSocketRejected(socketURL(listener, info.id, tmp.path, crossOrigin.ticket), {
+        headers: { origin: "https://evil.example" },
+      })
+    } finally {
+      await stop(listener, "timed out cleaning up rejected ticket listener").catch(() => undefined)
+    }
+  })
+
+  // Regression for #25698 (Ope): the app's SDK call to
+  // `client.pty.connectToken({ ptyID })` originally omitted `directory`, so
+  // the server resolved the PTY in its own cwd context — where the project
+  // PTY isn't registered — and returned 404. The fix is to always pass
+  // `directory` from the app side; this test locks in two contracts:
+  //   1. Mint without directory cannot find a PTY registered in another dir.
+  //   2. Mint with the project directory succeeds; the resulting ticket
+  //      consumes cleanly when the WS upgrade carries the same directory.
+  testPty("PTY connect token requires matching directory across mint and connect", async () => {
+    await using tmp = await tmpdir({ git: true, config: { formatter: false, lsp: false } })
+    const listener = await startListener()
+    try {
+      const info = await createCat(listener, tmp.path)
+
+      // Mint without directory — server uses its own cwd, can't find the PTY.
+      const ambiguous = await fetch(new URL(PtyPaths.connectToken.replace(":ptyID", info.id), listener.url), {
+        method: "POST",
+        headers: { authorization: authorization(), "x-opencode-ticket": "1" },
+      })
+      expect(ambiguous.status).toBe(404)
+
+      // Mint with the project directory — succeeds, ticket binds to that scope.
+      const scoped = await fetch(
+        new URL(
+          `${PtyPaths.connectToken.replace(":ptyID", info.id)}?directory=${encodeURIComponent(tmp.path)}`,
+          listener.url,
+        ),
+        {
+          method: "POST",
+          headers: { authorization: authorization(), "x-opencode-ticket": "1" },
+        },
+      )
+      expect(scoped.status).toBe(200)
+      const mint = (await scoped.json()) as { ticket: string }
+
+      // Same directory on the WS upgrade → consume succeeds.
+      const ws = await openSocket(socketURL(listener, info.id, tmp.path, mint.ticket))
+      ws.close(1000)
+    } finally {
+      await stop(listener, "timed out cleaning up directory-scope listener").catch(() => undefined)
+    }
+  })
+
+  testPty("keeps PTY websocket tickets optional when server auth is disabled", async () => {
+    await using tmp = await tmpdir({ git: true, config: { formatter: false, lsp: false } })
+    const listener = await startNoAuthListener()
+    try {
+      const info = await createCat(listener, tmp.path)
+      const ws = await openSocket(socketURL(listener, info.id, tmp.path))
+      const message = waitForMessage(ws, (message) => message.includes("ping-no-auth"))
+      ws.send("ping-no-auth\n")
+      expect(await message).toContain("ping-no-auth")
+      ws.close(1000)
+    } finally {
+      await stop(listener, "timed out cleaning up no-auth listener").catch(() => undefined)
+    }
+  })
 })

packages/opencode/test/server/httpapi-ui.test.ts

@@ -184,6 +184,52 @@ describe("HttpApi UI fallback", () => {
     expect(await response.text()).toBe("console.log('ok')")
   })
 
+  // Regression for #25698 (Ope): upstream `transfer-encoding: chunked` was
+  // forwarded through the proxy while the proxy itself re-frames the body,
+  // causing browsers to fail with `ERR_INVALID_CHUNKED_ENCODING`.
+  test("strips upstream transfer-encoding header from proxied assets", async () => {
+    Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = true
+    Flag.OPENCODE_DISABLE_EMBEDDED_WEB_UI = true
+
+    const response = await Effect.runPromise(
+      Effect.gen(function* () {
+        const fs = yield* AppFileSystem.Service
+        const client = yield* HttpClient.HttpClient
+        return yield* serveUIEffect(HttpServerRequest.fromWeb(new Request("http://localhost/")), {
+          fs,
+          client,
+        })
+      }).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            AppFileSystem.defaultLayer,
+            Layer.succeed(
+              HttpClient.HttpClient,
+              HttpClient.make((request) =>
+                Effect.succeed(
+                  HttpClientResponse.fromWeb(
+                    request,
+                    new Response("<html>opencode</html>", {
+                      headers: {
+                        "transfer-encoding": "chunked",
+                        "content-type": "text/html",
+                      },
+                    }),
+                  ),
+                ),
+              ),
+            ),
+          ),
+        ),
+        Effect.map(HttpServerResponse.toWeb),
+      ),
+    )
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get("transfer-encoding")).toBeNull()
+    expect(await response.text()).toBe("<html>opencode</html>")
+  })
+
   test("serves embedded UI assets when Bun can read them but access reports missing", async () => {
     Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = true
     let readPath: string | undefined
@@ -257,6 +303,25 @@ describe("HttpApi UI fallback", () => {
     expect(response.status).toBe(200)
   })
 
+  // Regression for #25698 (Ope): the browser fetches the PWA manifest and
+  // its icons via flows that don't carry app-managed credentials (the
+  // `<link rel="manifest">` request is not under page-auth control), so the
+  // server returning 401 breaks PWA install. These specific public assets
+  // should bypass auth.
+  test("serves the PWA manifest without auth even when a server password is set", async () => {
+    Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = true
+    Flag.OPENCODE_DISABLE_EMBEDDED_WEB_UI = true
+
+    for (const path of ["/site.webmanifest", "/web-app-manifest-192x192.png", "/web-app-manifest-512x512.png"]) {
+      const response = await uiApp({
+        password: "secret",
+        username: "opencode",
+        client: httpClient(new Response("ok")),
+      }).request(path)
+      expect(response.status).not.toBe(401)
+    }
+  })
+
   test("allows web UI preflight without auth", async () => {
     Flag.OPENCODE_EXPERIMENTAL_HTTPAPI = true
 

packages/sdk/js/src/v2/gen/sdk.gen.ts

@@ -99,6 +99,8 @@ import type {
   ProviderOauthCallbackResponses,
   PtyConnectErrors,
   PtyConnectResponses,
+  PtyConnectTokenErrors,
+  PtyConnectTokenResponses,
   PtyCreateErrors,
   PtyCreateResponses,
   PtyGetErrors,
@@ -2345,6 +2347,38 @@ export class Pty extends HeyApiClient {
     })
   }
 
+  /**
+   * Create PTY WebSocket token
+   *
+   * Create a short-lived ticket for opening a PTY WebSocket connection.
+   */
+  public connectToken<ThrowOnError extends boolean = false>(
+    parameters: {
+      ptyID: string
+      directory?: string
+      workspace?: string
+    },
+    options?: Options<never, ThrowOnError>,
+  ) {
+    const params = buildClientParams(
+      [parameters],
+      [
+        {
+          args: [
+            { in: "path", key: "ptyID" },
+            { in: "query", key: "directory" },
+            { in: "query", key: "workspace" },
+          ],
+        },
+      ],
+    )
+    return (options?.client ?? this.client).post<PtyConnectTokenResponses, PtyConnectTokenErrors, ThrowOnError>({
+      url: "/pty/{ptyID}/connect-token",
+      ...options,
+      ...params,
+    })
+  }
+
   /**
    * Connect to PTY session
    *

packages/sdk/js/src/v2/gen/types.gen.ts

@@ -1563,6 +1563,10 @@ export type McpUnsupportedOAuthError = {
   error: string
 }
 
+export type EffectHttpApiErrorForbidden = {
+  _tag: "Forbidden"
+}
+
 export type ProviderAuthMethod = {
   type: "oauth" | "api"
   label: string
@@ -4671,6 +4675,43 @@ export type PtyUpdateResponses = {
 
 export type PtyUpdateResponse = PtyUpdateResponses[keyof PtyUpdateResponses]
 
+export type PtyConnectTokenData = {
+  body?: never
+  path: {
+    ptyID: string
+  }
+  query?: {
+    directory?: string
+    workspace?: string
+  }
+  url: "/pty/{ptyID}/connect-token"
+}
+
+export type PtyConnectTokenErrors = {
+  /**
+   * Forbidden
+   */
+  403: EffectHttpApiErrorForbidden
+  /**
+   * Not found
+   */
+  404: NotFoundError
+}
+
+export type PtyConnectTokenError = PtyConnectTokenErrors[keyof PtyConnectTokenErrors]
+
+export type PtyConnectTokenResponses = {
+  /**
+   * WebSocket connect token
+   */
+  200: {
+    ticket: string
+    expires_in: number
+  }
+}
+
+export type PtyConnectTokenResponse = PtyConnectTokenResponses[keyof PtyConnectTokenResponses]
+
 export type QuestionListData = {
   body?: never
   path?: never
@@ -6652,6 +6693,10 @@ export type PtyConnectData = {
 }
 
 export type PtyConnectErrors = {
+  /**
+   * Forbidden
+   */
+  403: EffectHttpApiErrorForbidden
   /**
    * Not found
    */

packages/sdk/openapi.json

@@ -3414,6 +3414,91 @@
         ]
       }
     },
+    "/pty/{ptyID}/connect-token": {
+      "post": {
+        "tags": ["pty"],
+        "operationId": "pty.connectToken",
+        "parameters": [
+          {
+            "name": "directory",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "workspace",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "ptyID",
+            "in": "path",
+            "schema": {
+              "type": "string",
+              "pattern": "^pty.*"
+            },
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "WebSocket connect token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "ticket": {
+                      "type": "string"
+                    },
+                    "expires_in": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0
+                    }
+                  },
+                  "required": ["ticket", "expires_in"],
+                  "additionalProperties": false,
+                  "description": "WebSocket connect token"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/effect_HttpApiError_Forbidden"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/NotFoundError"
+                }
+              }
+            }
+          }
+        },
+        "description": "Create a short-lived ticket for opening a PTY WebSocket connection.",
+        "summary": "Create PTY WebSocket token",
+        "x-codeSamples": [
+          {
+            "lang": "js",
+            "source": "import { createOpencodeClient } from \"@opencode-ai/sdk\n\nconst client = createOpencodeClient()\nawait client.pty.connectToken({\n  ...\n})"
+          }
+        ]
+      }
+    },
     "/question": {
       "get": {
         "tags": ["question"],
@@ -8327,6 +8412,16 @@
               }
             }
           },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/effect_HttpApiError_Forbidden"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Not found",
             "content": {
@@ -12752,6 +12847,17 @@
         "required": ["error"],
         "additionalProperties": false
       },
+      "effect_HttpApiError_Forbidden": {
+        "type": "object",
+        "properties": {
+          "_tag": {
+            "type": "string",
+            "enum": ["Forbidden"]
+          }
+        },
+        "required": ["_tag"],
+        "additionalProperties": false
+      },
       "ProviderAuthMethod": {
         "type": "object",
         "properties": {