dsh-codex-ws 0.0.0-stage → 1.3.0

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# dsh-codex-ws
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 DSH 里的 **OpenAI（GPT）模型走 Codex 风格的 Responses WebSocket 传输**（即 Codex CLI `supports_websockets = true` 的 "WS 模式"），而不是 SSE 流式。不注册额外模型渠道：按钮在 `openai` 渠道原地生效，非 OpenAI 模型旁不会出现。
+
+## 它做什么
+
+- **不新增模型渠道**。插件拦截 harness 的 `llm/stream` 水流：传输开关为 websocket / auto 时，`openai` 渠道的请求改走 `<baseURL>/responses` 的 Codex 风格传输；切回 SSE 且 Fast 关闭时原样放行给原有 openai 适配器（模型选择器始终只有一组 OpenAI）。
+  - **WS 模式**：`wss://<baseURL>/responses`，发送 `{ "type": "response.create", ... }` 后接收与 SSE 完全相同的 Responses 事件流；连接按池复用（干净结束后保留 3 分钟，50 分钟强制换新）。
+  - **SSE 模式**：Fast 关闭时不拦截，走 DSH 原有 openai 渠道的流式请求（auto 模式下的回退则是普通 `POST /responses` + `stream: true` 打到同一中转站）。
+  - 拦截层复刻了适配器边界的投影（文件 → 可读路径句柄、图片 → 文本占位、developer 消息丢弃、deferLoading 工具声明展开），WS 路径目前仅发送文本，不会把图片原始内容发送给模型；不能视为与原生多模态适配器完全等价。
+- 接口地址与 Key 的解析顺序（`lib/config.js`）：
+  1. 插件配置里的 `baseURL` / `apiKey`
+  2. `envFile`（.env）或环境变量 `apiKeyEnv`（默认 `OPENAI_API_KEY`）
+  3. **`~/.codex/config.toml`** 中 `supports_websockets = true` 的 `[model_providers.*]`（取其 `base_url` 与 `experimental_bearer_token`）
+  4. 内置默认（`https://sub.cxc2.cn/v1`）
+- 输入框右侧、模型选择器旁的 **WS / SSE** 小按钮实时切换传输模式（下一次模型请求生效），选择持久化在 `$DSH_HOME/codex-ws/state.json`。**按钮只在该会话当前模型位于 openai 渠道时出现**，其他模型旁不存在。
+
+### Fast 模式
+
+WS / SSE 按钮旁新增独立 **Fast** 按钮，默认关闭，开启后高亮。开关与传输模式分别保存，全局影响 OpenAI 请求，从下一次模型请求生效，重启后保留。
+
+- 开启时发送 `service_tier: "priority"`，不改变模型、推理强度或输出长度；是否支持、实际速度和额外费用由服务端决定。
+- WS / auto 及 auto 回退 SSE 均保留该参数。**SSE + Fast 使用插件配置的 Responses 端点与凭据，而非原生适配器**，并继承插件的仅文本投影限制。关闭 Fast 后 SSE 恢复原样放行。
+- 开启 Fast 但缺少插件凭据时明确报错，不静默丢弃优先处理参数。切换 Fast 后增量 WS 请求配置指纹改变，自动全量发送。
+- 离线验证：`node test/fast.mjs`（不调用真实 API）。
+
+## 安装
+
+npm 发布完成后，可运行 `npm pack dsh-codex-ws@1.3.0 --registry=https://registry.npmjs.org` 获取安装包，在 DSH 插件管理中安装本地包；或克隆仓库后从本地目录安装。安装后刷新插件和界面。
+
+## npm 发布维护
+
+仓库使用 `.github/workflows/publish.yml`，在推送 `v*` 标签时校验标签与版本一致、运行离线测试，再通过 GitHub Actions OIDC 发布到 npm。不配置长期 `NPM_TOKEN`。手动重试时必须选择对应版本标签，分支上的手动运行不会发布。
+
+首次发布需要维护者通过 `npm login --registry=https://registry.npmjs.org` 登录并执行 `npm publish --access public` 创建包。随后在 npm 包 Settings → Trusted Publisher 中选择 GitHub Actions：
+
+- Organization or user：`kiritoko1029`
+- Repository：`dsh-codex-ws`
+- Workflow filename：`publish.yml`（不含目录）
+- Environment name：留空
+- Allowed actions：允许 `npm publish`
+
+后续升级版本、提交并推送匹配版本的标签即可自动发布。不要再次发布已存在的 npm 版本。Trusted Publisher 配置完成不等于验证成功，应以一次实际 OIDC 发布成功为准；新绑定若有到期提示，按 npm 要求及时完成首次验证。
+
+参考：[npm Trusted Publishing 文档](https://docs.npmjs.com/trusted-publishers/)。
+
+## 使用
+
+1. 确认 openai 渠道（llm-pi-ai 的 `openai`）已配置好 Key；模型选择器里选任意 GPT 模型。
+2. 模型选择器旁会出现 WS / SSE 按钮：默认即 WS 模式（可配置）；点一下切回 SSE 流式，再点切回 WS。
+3. 插件配置（设置 → 插件 → Codex WS → 配置）可改：`transport`（websocket / sse / auto，auto = WS 连接失败自动回退流式）、`baseURL`、`apiKey`、`apiKeyEnv`、`envFile`、超时等。
+
+## 说明
+
+- **v1.2.0 增量 WS**：首次全量发送；同一会话、同一连接上，只有当前历史严格延续上次输入与已完成输出，且 instructions / tools / model 等请求配置未变时，才使用 `previous_response_id` 并只发送新增 input。仍保持 `store: false`。
+- 连接按完整凭据哈希、端点、会话隔离；并发调用独占连接，不共享正在执行的续传状态。空闲 3 分钟或连接总寿命 50 分钟后关闭，全局最多保留 32 个空闲连接。
+- 历史压缩、编辑、分支、模型或提示/工具配置变化、连接丢失时自动使用全量。明确收到上一响应不存在错误、且还没有输出时，只允许一次新连接全量重试；已发送后遇到普通网络错误不会盲目重发。取消、未完成、失败结果不保存续传状态。
+- 工具 schema 和 instructions 仍随每次请求发送；优化减少历史 input 上传量，不减少模型实际上下文长度，也不保证同等比例的计费下降。DSH 若每一步改写早期历史或系统提示，会触发保守全量发送。
+- 验证：`node test/continuation.mjs` 为离线边界测试；`bun test/continuation-live.mjs` 使用合成消息验证中转站续传与实际发送字节（会产生少量 API 调用）。一次实测为 14,242 → 511 字节，第二轮正确回忆第一轮标记；真实降幅取决于历史与固定请求配置大小。
+- Key 只在 Host 侧使用，浏览器端只拿到 `/codex-ws/state` 返回的开关状态与端点地址（不含 Key）。

package/client.js

@@ -0,0 +1,233 @@
+/**
+ * Client half of dsh-codex-ws: a compact WS/SSE toggle in the composer toolbar
+ * (`conversation.input.right`, next to the model selector). It renders ONLY while
+ * the session's current model sits on the `openai` provider — the transport it
+ * flips belongs to those models, so every other provider never sees the button.
+ * It reads and writes the plugin's Host state at GET/POST /codex-ws/state; the
+ * API key never reaches the browser.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-codex-ws',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const { useState, useEffect, useCallback, useSyncExternalStore } = React
+
+    const STATE_ROUTE = 'codex-ws/state'
+    const CACHE_KEY = 'dsh-codex-ws:v3'
+    const TARGET_PROVIDER = 'openai'
+
+    const subscribeNothing = () => () => {}
+    const snapshotNothing = () => null
+
+
+
+    const ICONS = {
+      ws: h(
+        'svg',
+        { viewBox: '0 0 24 24', width: 13, height: 13, 'aria-hidden': true },
+        h('path', { d: 'M13 2 3.5 13.5h6L8 22l10.5-12h-6L13.8 2z', fill: 'currentColor' }),
+      ),
+      sse: h(
+        'svg',
+        { viewBox: '0 0 24 24', width: 13, height: 13, 'aria-hidden': true },
+        h('path', {
+          d: 'M2.5 12h4l2.5-6.5L14 18.5 16.5 12h5',
+          fill: 'none',
+          stroke: 'currentColor',
+          'stroke-width': 2,
+          'stroke-linecap': 'round',
+          'stroke-linejoin': 'round',
+        }),
+      ),
+    }
+
+    function ensureStyles() {
+      if (document.getElementById('dsh-codex-ws-style')) return
+      const style = document.createElement('style')
+      style.id = 'dsh-codex-ws-style'
+      style.textContent = [
+        '.dsh-codex-ws-btn{display:inline-flex;align-items:center;gap:4px;height:24px;padding:0 9px;border-radius:9999px;border:1px solid color-mix(in srgb,currentColor 28%,transparent);background:transparent;color:inherit;font-size:11px;font-weight:600;line-height:1;cursor:pointer;user-select:none;transition:opacity .15s,background .15s,border-color .15s;white-space:nowrap}',
+        '.dsh-codex-ws-btn:hover{border-color:color-mix(in srgb,currentColor 55%,transparent)}',
+        '.dsh-codex-ws-btn:focus-visible{outline:2px solid currentColor;outline-offset:2px}',
+        '.dsh-codex-ws-btn[data-pending="true"]{opacity:.55;cursor:wait}',
+        '.dsh-codex-ws-btn[data-mode="websocket"]{background:color-mix(in srgb,#10a37f 16%,transparent);border-color:color-mix(in srgb,#10a37f 55%,transparent);color:#10a37f}',
+        '.dsh-codex-ws-btn[data-mode="websocket"]:hover{background:color-mix(in srgb,#10a37f 26%,transparent)}',
+        '.dsh-codex-ws-btn[data-error="true"]{color:#e5484d;border-color:color-mix(in srgb,#e5484d 60%,transparent)}',
+      ].join('\n')
+      document.head.appendChild(style)
+    }
+
+    function TransportToggle({ providerStore }) {
+      const [state, setState] = useState(null)
+      const [pending, setPending] = useState(false)
+      const [error, setError] = useState(false)
+      /** The session's live model provider ('openai' | … | null while unknown). */
+      const provider = useSyncExternalStore(
+        providerStore ? (onChange) => providerStore.subscribe(onChange) : subscribeNothing,
+        providerStore ? () => providerStore.getSnapshot() : snapshotNothing,
+        snapshotNothing,
+      )
+
+      useEffect(() => {
+        ensureStyles()
+        let alive = true
+        fetch(STATE_ROUTE, { accept: 'application/json' })
+          .then((response) => {
+
+            return response.ok ? response.json() : null
+          })
+          .then((data) => {
+            if (!alive || !data) return
+            setState(data)
+            try {
+              localStorage.setItem(CACHE_KEY, JSON.stringify(data))
+            } catch {}
+          })
+          .catch(() => {})
+        try {
+          const cached = localStorage.getItem(CACHE_KEY)
+          if (cached) setState(JSON.parse(cached))
+        } catch {}
+        return () => {
+          alive = false
+        }
+      }, [])
+
+      const toggle = useCallback(async (field) => {
+        if (!state || pending) return
+        const patch = field === 'fast'
+          ? { fast: state.fast !== true }
+          : { transport: state.transport === 'sse' ? 'websocket' : 'sse' }
+        setPending(true)
+        setError(false)
+        try {
+          const response = await fetch(STATE_ROUTE, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(patch),
+          })
+          if (!response.ok) throw new Error(`HTTP ${response.status}`)
+          const data = await response.json()
+          setState(data)
+          try {
+            localStorage.setItem(CACHE_KEY, JSON.stringify(data))
+          } catch {}
+        } catch {
+          setError(true)
+          setTimeout(() => setError(false), 1600)
+        } finally {
+          setPending(false)
+        }
+      }, [state, pending])
+
+      if (state === null) {
+
+        return null
+      }
+      if (state.providerAvailable === false) {
+
+        return null
+      }
+      // Only OpenAI models ride this transport; other providers never see the button.
+      // A blank session has no projection yet; the composer shows the default model then.
+      const current = provider?.provider ?? state.defaultProvider ?? null
+      if (!providerStore || current !== TARGET_PROVIDER) {
+        return null
+      }
+
+      const mode = state.transport === 'sse' ? 'sse' : 'ws'
+      const host = (() => {
+        try {
+          return new URL(state.endpoint?.baseURL ?? '').host
+        } catch {
+          return ''
+        }
+      })()
+      const keyHint = state.endpoint?.hasKey === false ? '（尚未解析到 API Key，WS 不会生效）' : ''
+      const title =
+        state.transport === 'sse'
+          ? `SSE 流式（${state.fast ? 'Fast：插件 Responses 接口，仅文本' : 'openai 渠道直连'}）· 点击让 OpenAI 模型改走 WS 模式${host ? `（${host}）` : ''}${keyHint}`
+          : `WS 模式 · OpenAI 模型经 ${host || '中转站'} WebSocket 传输 · 点击切回 SSE 流式${keyHint}`
+      return h('span', { style: { display: 'inline-flex', alignItems: 'center', gap: 4 } }, h(
+        'button',
+        {
+          type: 'button',
+          className: 'dsh-codex-ws-btn',
+          'data-mode': state.transport === 'sse' ? 'sse' : 'websocket',
+          'data-pending': pending ? 'true' : 'false',
+          'data-error': error ? 'true' : 'false',
+          title,
+          disabled: pending,
+          'aria-pressed': state.transport !== 'sse',
+          onClick: () => toggle('transport'),
+        },
+        ICONS[mode],
+        error ? '!' : mode === 'ws' ? 'WS' : 'SSE',
+      ), h('button', {
+        type: 'button',
+        className: 'dsh-codex-ws-btn',
+        'data-mode': state.fast === true ? 'websocket' : 'sse',
+        'data-pending': pending ? 'true' : 'false',
+        'data-error': error ? 'true' : 'false',
+        'aria-pressed': state.fast === true,
+        'aria-label': 'Fast 模式',
+        disabled: pending,
+        title: `Fast 模式${state.fast === true ? '已开启 · 点击关闭' : '已关闭 · 点击开启'}：优先处理（service_tier=priority），可能额外计费，需中转站支持。全局生效，下一次请求使用；SSE 下使用插件 Responses 接口（仅文本）。`,
+        onClick: () => toggle('fast'),
+      }, ICONS.ws, 'Fast'))
+    }
+
+    /** Wrap any {subscribe,getSnapshot} source into a referentially stable provider snapshot. */
+    function providerStoreOf(source, read) {
+      let last = { provider: null }
+      return {
+        subscribe: (onChange) => source.subscribe(onChange),
+        getSnapshot: () => {
+          const provider = read(source.getSnapshot()) ?? null
+          if (last.provider !== provider) last = { provider }
+          return last
+        },
+      }
+    }
+
+    return {
+      // 'sessions' is declared so the facade exposes it; the session's own
+      // modelSelection projection (what the model selector renders from) is a
+      // plain object graph, so reading it never crosses a context guard.
+      inject: ['slots', 'sessions'],
+      apply(ctx) {
+
+        ctx.slots.inject('conversation.input.right', () =>
+          ctx.slots.register(
+            {
+              name: 'conversation.input.right',
+              id: 'codex-ws-transport',
+              order: 40,
+              label: 'Codex WS',
+              /** The session's model-selection projection powers the button's visibility. */
+              inject: (sessionId) => {
+                if (typeof sessionId !== 'string') {
+
+                  return {}
+                }
+                try {
+                  const face = ctx.sessions.binding(sessionId).session.projections.faceOf('modelSelection')
+                  if (face !== undefined && typeof face.subscribe === 'function') {
+
+                    return { providerStore: providerStoreOf(face, (snap) => snap?.next?.provider) }
+                  }
+
+                } catch (error) {
+
+                }
+                return {}
+              },
+            },
+            TransportToggle,
+          ),
+        )
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# GPT (Codex backend) WebSocket mode for the OpenAI channel.
+# Every field is optional; empty values fall back to ~/.codex/config.toml
+# (model_providers.* with supports_websockets = true), then to the plugin defaults.
+- insert:
+    - id: codex-ws
+      name: 'dsh-codex-ws'
+      config:
+        # 'websocket' (WS 模式, openai 渠道原地拦截) | 'sse' (流式, 不拦截)
+        # | 'auto' (WS 优先, 连接失败回退流式)
+        transport: websocket

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#0f172a"/>
+  <path d="M30 10 L16 34 h11 l-3 20 L45 28 h-12 l2-18 z" fill="#10a37f"/>
+  <path d="M12 46 c4-3 8-3 12 0 s8 3 12 0" fill="none" stroke="#7dd3fc" stroke-width="3" stroke-linecap="round"/>
+  <path d="M16 53 c4-3 8-3 12 0 s8 3 12 0" fill="none" stroke="#7dd3fc" stroke-width="3" stroke-linecap="round" opacity=".55"/>
+</svg>

package/index.js

@@ -0,0 +1,274 @@
+/**
+ * dsh-codex-ws — GPT models over the Codex-style Responses WebSocket transport.
+ *
+ * The plugin does NOT register a parallel model channel. Instead it intercepts the
+ * harness `llm/stream` waterfall for the existing `openai` provider: while the
+ * transport toggle is on (websocket / auto), those requests speak the Responses
+ * protocol over WebSocket ("WS 模式", Codex CLI `supports_websockets`) against the
+ * relay the local Codex CLI uses (base URL + bearer token resolved from this
+ * plugin's config, then ~/.codex/config.toml, then defaults). SSE mode passes the
+ * request through to the normal openai adapter untouched, so OpenAI models stay a
+ * single channel and non-OpenAI models never see the toggle at all.
+ *
+ * A composer toolbar button (client half, shown only while the session's model is
+ * an OpenAI one) flips the transport at runtime through POST /codex-ws/state; the
+ * choice is persisted in $DSH_HOME/codex-ws/state.json and applies from the next
+ * model step. The API key never reaches the browser.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { Config, resolveSettings, TARGET_PROVIDER, TRANSPORTS } from './lib/config.js'
+import { ResponseStreamMapper, buildCreateBody, projectOptions, abortedFinish, errorFinish } from './lib/responses.js'
+import { runTransport, closeIdleSockets, TransportError } from './lib/transport.js'
+
+export const name = 'codex-ws'
+export const inject = ['llm', 'webServer', 'connection']
+export { Config }
+
+const STATE_PATH = '/codex-ws/state'
+
+// ---------------------------------------------------------------------------------------------
+// Toggle state ($DSH_HOME/codex-ws/state.json)
+// ---------------------------------------------------------------------------------------------
+
+function stateDir() {
+  return join(process.env.DSH_HOME && process.env.DSH_HOME !== '' ? process.env.DSH_HOME : join(homedir(), '.dsh'), 'codex-ws')
+}
+
+function readState() {
+  try {
+    const parsed = JSON.parse(readFileSync(join(stateDir(), 'state.json'), 'utf8'))
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeState(state) {
+  const dir = stateDir()
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'state.json'), `${JSON.stringify(state, null, 2)}\n`)
+}
+
+// ---------------------------------------------------------------------------------------------
+// Stream interception
+// ---------------------------------------------------------------------------------------------
+
+/** One openai-provider request over the Codex-style transport; yields harness chunks. */
+async function* interceptedStream(options, runtime, resolvePath) {
+  const { settings, transport } = runtime
+  if (settings.apiKey.length === 0) {
+    yield {
+      type: 'finish',
+      reason: {
+        kind: 'error',
+        failure: {
+          message: `codex-ws: no API key for the plugin Responses transport; set the key on the plugin's config page (or ${settings.apiKeyEnv} / ~/.codex/config.toml), or disable Fast and switch to SSE`,
+          code: 'MISSING_CREDENTIAL',
+        },
+      },
+    }
+    return
+  }
+  const projected = projectOptions(options, resolvePath)
+  const { body, requestId } = buildCreateBody(settings, projected, { transport })
+  const mapper = new ResponseStreamMapper()
+  try {
+    for await (const event of runTransport(settings, transport, { body, requestId, sessionId: options.sessionId, signal: options.signal })) {
+      for (const chunk of mapper.handleEvent(event)) yield chunk
+    }
+    if (!mapper.completed) {
+      yield errorFinish(new TransportError('stream ended without a terminal response event', { phase: 'stream' }), {
+        aborted: options.signal?.aborted === true,
+      })
+    }
+  } catch (error) {
+    if (options.signal?.aborted) {
+      yield abortedFinish()
+      return
+    }
+    if (error instanceof TransportError && error.phase === 'connect' && transport === 'websocket') {
+      yield errorFinish(
+        new TransportError(
+          `${error.message} — WebSocket 连接失败；可点输入框旁的按钮切到 SSE，或在插件配置里把 transport 设为 auto`,
+          { code: error.code },
+        ),
+      )
+      return
+    }
+    yield errorFinish(error)
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------------------------
+
+export function apply(ctx, config) {
+  const connection = Reflect.get(ctx, 'connection')
+  const state = { override: null, fast: false }
+
+  const loadState = () => {
+    const stored = readState()
+    state.override = TRANSPORTS.includes(stored.transport) ? stored.transport : null
+    state.fast = stored.fast === true
+  }
+  loadState()
+
+  /** Live settings plus the effective transport for the next request. */
+  const runtime = () => {
+    const settings = { ...resolveSettings(config), fast: state.fast }
+    const transport = state.override ?? settings.transport
+    return { settings, transport }
+  }
+
+  const persistState = (patch) => {
+    const transport = patch.transport ?? state.override
+    const fast = patch.fast ?? state.fast
+    // Commit memory only after persistence succeeds; partial updates preserve the other toggle.
+    writeState({ ...(transport !== null ? { transport } : {}), fast })
+    state.override = transport
+    state.fast = fast
+    if (transport === 'sse') closeIdleSockets()
+  }
+
+  /** Execution-world read path for a file attachment, when one is resolvable. */
+  const fileReadPath = (attachment) => {
+    if (attachment === null || typeof attachment !== 'object') return undefined
+    try {
+      const resolved = ctx.llm.fileReadPath?.(attachment)
+      return typeof resolved === 'string' ? resolved : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Take the openai provider over the Codex-style transport while WS is on.
+   * Registered without `prepend`, so core `llm/stream` listeners (session
+   * checkpointing, …) stay outside this veto and keep running.
+   */
+  ctx.on('llm/stream', (options, next) => {
+    if (options?.provider !== TARGET_PROVIDER) return next()
+    const { settings, transport } = runtime()
+    if (transport === 'sse' && !settings.fast) return next()
+    // Do not silently drop an explicitly requested priority tier when credentials are missing.
+    if (settings.apiKey.length === 0 && !settings.fast) return next()
+    return interceptedStream(options, { settings, transport }, fileReadPath)
+  })
+
+  const publicState = () => {
+    const { settings, transport } = runtime()
+    let providerAvailable = true
+    try {
+      providerAvailable = ctx.llm.listProviders().some((provider) => provider.id === TARGET_PROVIDER)
+    } catch {
+      /* optional metadata */
+    }
+    // A blank session has no model-selection projection yet; the composer then shows the
+    // default model, so the client falls back to this provider id (and nothing else).
+    let defaultProvider = null
+    try {
+      const selection = ctx.get('agentDefaultModel')?.currentSelection()
+      if (typeof selection?.provider === 'string') defaultProvider = selection.provider
+    } catch {
+      /* optional service */
+    }
+    return {
+      provider: TARGET_PROVIDER,
+      transport,
+      fast: settings.fast,
+      endpoint: { baseURL: settings.baseURL, hasKey: settings.apiKey.length > 0 },
+      providerAvailable,
+      defaultProvider,
+    }
+  }
+
+  const sendJson = (res, status, payload) => {
+    res.statusCode = status
+    res.setHeader('content-type', 'application/json; charset=utf-8')
+    res.setHeader('cache-control', 'no-store')
+    res.end(JSON.stringify(payload))
+  }
+
+  /** Answer an untrusted or unauthenticated request; true when it was rejected. */
+  const rejected = (req, res) => {
+    const rejection = connection?.requestRejection?.(req)
+    if (rejection === undefined) return false
+    res.statusCode = rejection
+    res.end()
+    return true
+  }
+
+  const readBody = (req) =>
+    new Promise((resolve, reject) => {
+      let size = 0
+      const chunks = []
+      req.on('data', (chunk) => {
+        size += chunk.length
+        if (size > 4096) {
+          reject(new Error('body too large'))
+          req.destroy()
+          return
+        }
+        chunks.push(chunk)
+      })
+      req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+      req.on('error', reject)
+    })
+
+
+
+  ctx.effect(
+    () =>
+      ctx.webServer.register({
+        kind: 'exact',
+        path: STATE_PATH,
+        handler: async (req, res) => {
+          try {
+            if (rejected(req, res)) return
+            if (req.method === 'GET') {
+              sendJson(res, 200, publicState())
+              return
+            }
+            if (req.method !== 'POST') {
+              res.statusCode = 405
+              res.setHeader('allow', 'GET, POST')
+              res.end()
+              return
+            }
+            const body = JSON.parse(await readBody(req))
+            if (!body || typeof body !== 'object' || Array.isArray(body) ||
+                (!Object.hasOwn(body, 'transport') && !Object.hasOwn(body, 'fast'))) {
+              sendJson(res, 400, { error: 'transport or fast is required' })
+              return
+            }
+            const patch = {}
+            if (Object.hasOwn(body, 'transport')) {
+              const transport = typeof body.transport === 'string' ? body.transport.toLowerCase() : ''
+              if (!TRANSPORTS.includes(transport)) {
+                sendJson(res, 400, { error: `transport must be one of ${TRANSPORTS.join(', ')}` })
+                return
+              }
+              patch.transport = transport
+            }
+            if (Object.hasOwn(body, 'fast')) {
+              if (typeof body.fast !== 'boolean') {
+                sendJson(res, 400, { error: 'fast must be a boolean' })
+                return
+              }
+              patch.fast = body.fast
+            }
+            persistState(patch)
+            sendJson(res, 200, publicState())
+          } catch (error) {
+            if (!res.headersSent) sendJson(res, 400, { error: error?.message ?? 'bad request' })
+            else res.end()
+          }
+        },
+      }),
+    `codex-ws: ${STATE_PATH}`,
+  )
+}