dsh-codex-ws 0.0.0-stage → 1.3.1

package/README.md

@@ -1,3 +1,69 @@
-# 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 路径目前仅发送文本，不会把图片原始内容发送给模型；不能视为与原生多模态适配器完全等价。
+- **默认继承 DSH 当前 OpenAI 渠道的接口地址与凭据**：通过 `llm/listConfigurableProviders` 定位 openai 路由的设置命名空间与 profile 路径，读取其 `baseURL`（缺省用渠道默认地址），`apiKeyEnv` 凭据引用经 credentials 服务解析——与 llm-pi-ai 适配器自身的解析方式一致。每次请求重新读取，渠道配置改动即时生效；不读取本地 Codex CLI 配置，也没有写死的中转地址。
+- 插件的 `baseURL` / `apiKey` / `apiKeyEnv` / `envFile` 留空即可继承。显式填写任意一项会进入独立覆盖模式，必须同时提供接口地址和 Key，不会与 DSH 的地址或凭据混用。
+  - 覆盖模式 Key 顺序：`apiKey` → `envFile` 中对应变量 → 显式指定的 `apiKeyEnv` 环境变量。
+  - `apiKeyEnv` 默认留空；仅配置 `envFile` 时默认读取文件中的 `OPENAI_API_KEY`。不会自动使用进程中的 `OPENAI_API_KEY`。
+  - 不再自动沿用 `~/.codex/config.toml`；若要使用同一服务，请在 DSH OpenAI 渠道中配置，或显式提供插件覆盖配置。
+  - 升级后若旧配置保存了 `apiKeyEnv: OPENAI_API_KEY`，请清空该字段及其他覆盖项以启用继承。
+  - 继承模式下渠道未配置或凭据无法解析时请求明确报错（`INVALID_CONFIGURATION`），不会退回其他端点或凭据。
+- 输入框右侧、模型选择器旁的 **WS / SSE** 小按钮实时切换传输模式（下一次模型请求生效），选择持久化在 `$DSH_HOME/codex-ws/state.json`。**按钮只在该会话当前模型位于 openai 渠道时出现**，其他模型旁不存在。
+
+### Fast 模式
+
+WS / SSE 按钮旁新增独立 **Fast** 按钮，默认关闭，开启后高亮。开关与传输模式分别保存，全局影响 OpenAI 请求，从下一次模型请求生效，重启后保留。
+
+- 开启时发送 `service_tier: "priority"`，不改变模型、推理强度或输出长度；是否支持、实际速度和额外费用由服务端决定。
+- WS / auto 及 auto 回退 SSE 均保留该参数。**SSE + Fast 由插件发起 Responses 请求，默认继承 DSH OpenAI 端点与凭据**，并继承插件的仅文本投影限制。关闭 Fast 后 SSE 恢复原样放行。
+- WS / auto / SSE + Fast 配置不完整时明确报错，不静默丢弃优先处理参数。切换 Fast 后增量 WS 请求配置指纹改变，自动全量发送。
+- 离线验证：`node test/fast.mjs`（不调用真实 API）。
+
+## 安装
+
+可运行 `npm pack dsh-codex-ws@1.3.1 --registry=https://registry.npmjs.org` 获取安装包，在 DSH 插件管理中安装本地包；或克隆仓库后从本地目录安装。安装后刷新插件和界面。
+
+### v1.3.1 升级说明
+
+- 默认继承 DSH OpenAI 渠道的接口地址和凭据，每次请求重新读取渠道配置。
+- 移除本地 Codex CLI 配置与内置中转地址回退；显式覆盖必须成对提供地址和 Key，避免混用端点与凭据。
+- **从旧版升级**：若插件中保存了 `apiKeyEnv: OPENAI_API_KEY`，请清空它及其他覆盖项以启用继承；如需独立覆盖，请同时配置 `baseURL` 和 Key。
+- 配置不完整时，WS / auto / SSE + Fast 明确报错；SSE 且 Fast 关闭仍由原生 OpenAI 适配器处理。
+
+## 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. 默认无需重复填写地址和 Key。插件配置（设置 → 插件 → 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.
+# Leave endpoint/credential fields empty to inherit the DSH OpenAI provider.
+# Explicit overrides require both an endpoint and credentials; no Codex CLI fallback.
+- 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,349 @@
+/**
+ * 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
+ * current DSH OpenAI endpoint and credentials (or a complete explicit plugin
+ * override). No Codex CLI configuration is read. 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, hasOverride, 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', 'settings']
+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, resolveRuntime, resolvePath) {
+  const { settings, transport } = await resolveRuntime()
+  if (settings.configurationError) {
+    yield {
+      type: 'finish',
+      reason: {
+        kind: 'error',
+        failure: {
+          message: settings.configurationError,
+          code: 'INVALID_CONFIGURATION',
+        },
+      },
+    }
+    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()
+
+  /**
+   * The DSH OpenAI provider's live endpoint and bearer credential, resolved the
+   * same way the pi-ai adapter resolves them: the configurable-provider
+   * directory names the settings namespace and profile path; the profile holds
+   * an optional baseURL (falling back to the route's catalog default) and an
+   * apiKeyEnv credential reference resolved through the credentials service
+   * (with the launch environment as a secondary source). Re-read per request
+   * so channel edits apply without a restart; every failure is contained and
+   * surfaces as the inherited-mode configuration error.
+   */
+  const inheritedProvider = async () => {
+    try {
+      const entry = ctx.llm.listConfigurableProviders().find((provider) => provider.provider === TARGET_PROVIDER)
+      if (!entry) return {}
+      let profile = {}
+      try {
+        const namespace = ctx.settings
+          ?.describe({ redactSecrets: true })
+          .find((candidate) => candidate.ns === entry.settingsNs)
+        let value = namespace?.value
+        for (const key of entry.settingsPath ?? []) value = value?.[key]
+        profile = value !== null && typeof value === 'object' ? value : {}
+      } catch {
+        /* settings service unavailable: fall back to the catalog default */
+      }
+      const baseURL = typeof profile.baseURL === 'string' ? profile.baseURL.trim() : ''
+      const reference = typeof profile.apiKeyEnv === 'string' ? profile.apiKeyEnv.trim() : ''
+      let apiKey = ''
+      if (reference) {
+        // Bare `ctx.credentials` throws on the Cordis context proxy when the
+        // service is not in this plugin's inject list ("cannot get property
+        // without inject"); ctx.get is the supported inject-free accessor and
+        // matches how llm-pi-ai itself reaches the credentials service.
+        let credentials
+        try {
+          credentials = typeof ctx.get === 'function' ? ctx.get('credentials') : undefined
+        } catch {
+          /* this composition mounts no credential plane */
+        }
+        try {
+          const resolved = credentials === undefined ? undefined : await credentials.resolve?.(reference)
+          if (typeof resolved?.value === 'string') apiKey = resolved.value.trim()
+        } catch {
+          /* an unresolvable reference surfaces as the inherited-mode error */
+        }
+        if (apiKey.length === 0) {
+          // Ambient fallback mirrors the adapter: the launch-environment
+          // snapshot (process / project .env / user .env layers), with raw
+          // process.env as the last resort for compositions without either.
+          let ambient
+          try {
+            const environment = typeof ctx.get === 'function' ? ctx.get('launchEnvironment') : undefined
+            ambient = environment?.get?.(reference)?.value
+          } catch {
+            /* optional service */
+          }
+          apiKey = (ambient ?? process.env[reference] ?? '').trim()
+        }
+      }
+      return {
+        baseURL: baseURL || (typeof entry.defaultBaseURL === 'string' ? entry.defaultBaseURL.trim() : ''),
+        apiKey,
+      }
+    } catch {
+      return {}
+    }
+  }
+
+  /** Sync transport/fast decision for the next request; never touches credentials. */
+  const runtimeSync = () => {
+    const { transport } = resolveSettings(config, {})
+    return { transport: state.override ?? transport, fast: state.fast }
+  }
+
+  /** Live settings plus the effective transport; the inherited endpoint and
+   * credential resolve asynchronously through the DSH services. */
+  const runtime = async () => {
+    const provider = hasOverride(config) ? {} : await inheritedProvider()
+    const settings = { ...resolveSettings(config, provider), fast: state.fast }
+    return { settings, transport: state.override ?? 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 { transport, fast } = runtimeSync()
+    if (transport === 'sse' && !fast) return next()
+    // Fail closed for incomplete overrides or unavailable inherited configuration.
+    // Never silently change endpoint, account, or requested transport.
+    return interceptedStream(options, runtime, fileReadPath)
+  })
+
+  const publicState = async () => {
+    const { settings, transport } = await 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, await 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, await publicState())
+          } catch (error) {
+            if (!res.headersSent) sendJson(res, 400, { error: error?.message ?? 'bad request' })
+            else res.end()
+          }
+        },
+      }),
+    `codex-ws: ${STATE_PATH}`,
+  )
+}