dsh-codex-connect 0.1.0-alpha.4.20 → 0.1.0-alpha.4.22

package/INSTALL.md

@@ -1,5 +1,7 @@
 # Installation Runbook for CLI Agents
 
+Alpha 4.22 is verified with DSH `0.1.2-alpha.2` and its declared pi-ai range `^0.84.2`; the verified registry installation resolves pi-ai `0.84.4`.
+
 Install `dsh-codex-connect` into one requested DeepSeek Harness profile without changing its current default model, search route, global configuration, or OAuth state.
 
 ## Safety requirements
@@ -12,16 +14,44 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 ## Install and validate
 
-The only verified combination is DSH plugin API packages `0.1.1-rc.2`, `@earendil-works/pi-ai` `0.82.1`, and Node.js `^22.19.0 || >=24.0.0`. Alpha 4.20 uses the rc.2 keyed Plugin configuration slot; users of older DSH API packages should upgrade the DSH API packages and pi-ai together, then rerun `dsh-codex-connect doctor --json` and `pnpm --silent run check:compatibility`; the contract does not make claims about future versions.
+### Select an exact version before installation
+
+Check `dsh --version` before changing the requested profile. Use `dsh --help` to locate the CLI if needed; from a Harness checkout use `pnpm dsh --version`. Select an exact pair from [verified-compatibility.json](verified-compatibility.json):
+
+| Installed DSH version | Codex Connect version to pin |
+| --- | --- |
+| `0.1.0-rc.7` | `0.1.0-alpha.4.14` |
+| `0.1.1-rc.2` | `0.1.0-alpha.4.21` |
+| `0.1.2-alpha.2` | `0.1.0-alpha.4.22` |
+
+If your exact DSH version is unknown or not listed, stop and verify the combination before installing. Do not blindly install `dsh-codex-connect@alpha`: `alpha` is a moving tag, not a compatibility guarantee. Do not infer support for newer DSH versions from these rows.
+
+Alpha 4.22's verified contract is DSH plugin API packages `0.1.2-alpha.2`, `@earendil-works/pi-ai` `^0.84.2` (resolved as `0.84.4` during verification), and Node.js `^22.19.0 || >=24.0.0`. Alpha 4.21 remains the verified choice for DSH `0.1.1-rc.2`; staying on DSH `0.1.0-rc.7` means selecting Alpha 4.14. Upgrading DSH is a separate decision: upgrade the DSH API packages and pi-ai together, then rerun `dsh-codex-connect doctor --json` and `pnpm --silent run check:compatibility` for the selected combination.
+
+These choices reflect the repository's existing verification record, not a new installation or runtime probe. This guidance does not fix upstream DSH compatibility or resolve [Issue #64](https://github.com/franksong2702/dsh-codex-connect/issues/64).
+
+### Install the selected version and validate
+
+1. Complete the version selection above. The commands below use `web`; substitute only the requested profile.
+2. Install the selected exact version. For DSH `0.1.0-rc.7`:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.14
+   ```
 
-1. Check `dsh --version` or `dsh --help`. From a Harness checkout use `pnpm dsh`.
-2. Install the package:
+   For DSH `0.1.1-rc.2`, use Alpha 4.21:
 
    ```sh
-   dsh plugin --profile web add dsh-codex-connect@alpha
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.21
    ```
 
-   After `0.1.0-alpha.4.20` is published, pin it exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.20`. If npm is unavailable after its matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.20'`.
+   After the matching package is published, use Alpha 4.22 with DSH `0.1.2-alpha.2`:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.22
+   ```
+
+   If npm is unavailable after the matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.21'` only for the DSH `0.1.1-rc.2` combination, or `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.22'` only for the DSH `0.1.2-alpha.2` combination.
 
 3. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
 4. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
@@ -33,6 +63,10 @@ The only verified combination is DSH plugin API packages `0.1.1-rc.2`, `@earendi
 
 6. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
 
+   Alpha 4.22 additionally offers the same account actions in **Settings → Models → Openai-Codex**, plus a shared **More settings** dialog for model visibility, proxy, search, image, and context-budget controls. The original Plugin settings entry remains available; neither entry automatically starts login or changes model/search defaults.
+
+   When signed out, select **Authorize**. When signed in, use **Sign out** or **View quota**; use **More settings** for plugin options. If authorization is abandoned, use **Reopen authorization** or **Cancel sign-in** and retry; cancellation does not delete an existing account. Pending authorization expires after 10 minutes by default (`oauthTimeoutMs` in plugin configuration, applied on load).
+
 ### Remote browser access
 
 The default Web OAuth boundary is loopback-only. When DSH runs on one device and you open it from another device on a trusted network through an IP address or domain, run the following on the device that runs DSH with the exact origin from the browser address bar:
@@ -76,6 +110,8 @@ Do not add the last two rows unless the user separately requested those routing
 
 ## Update and removal
 
+Before updating, repeat the exact-version selection above. Use `@alpha` only after verifying that the version it currently resolves to is compatible with the installed DSH; otherwise pin the selected version in the update command.
+
 ```sh
 dsh plugin --profile web update dsh-codex-connect@alpha
 dsh plugin --profile web remove dsh-codex-connect

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   git hash-object README.md docs/README.zh.md
-README.md: 29729f3c078749ca04dc1d648c496c7b57bf3b17
-docs/README.zh.md: a7141cd531059e44771f763a8e5b75d529fc3f83
+README.md: a70138a6cef1b38bf564eb3d187046a2388305a1
+docs/README.zh.md: f44a46b738a80bbb13765bb27f9424890c6d8663

package/README.md

@@ -28,7 +28,14 @@ dsh plugin --profile web add dsh-codex-connect@alpha
 
 Expected result: the package is added to that profile. This does not change the profile's default model or global search route.
 
-To reproduce this release exactly, use `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.20`. If npm is unavailable after the matching GitHub prerelease exists, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.20'`. A local checkout can be installed as `link:/absolute/path/to/dsh-codex-connect`.
+After its matching package is published, install Alpha 4.22 exactly with `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.22`.
+
+### What's new in Alpha 4.22
+
+- Target the DSH `0.1.2-alpha.2` client settings and session-controller APIs together with its declared `@earendil-works/pi-ai` range `^0.84.2`.
+- Manage ChatGPT authorization, quota and shared Codex Connect settings from a compact **Openai-Codex** card in **Settings → Models**, while retaining the original Plugin settings entry.
+- Continue, cancel or retry an interrupted browser authorization without restarting DSH or deleting an existing credential. The full authorization flow has a configurable bounded deadline.
+- Adjust a bounded local context budget per visible Codex model with a linked slider and numeric input. Catalog defaults remain in effect until an override is saved; the configuration limit is not a claim about the service-side context capacity.
 
 ### Version updates
 
@@ -62,6 +69,10 @@ Expected result: the Harness web UI opens for the selected profile.
 
 Open **Settings → Plugins → Plugin configuration → Codex Connect**.
 
+Alpha 4.22 for DSH `0.1.2-alpha.2` also includes an **Openai-Codex** account card in **Settings → Models**, with the attribution “Powered by the Codex Connect plugin.” for ChatGPT sign-in, reauthorization, sign-out and quota. Both pages share one in-memory account state and polling owner. **More settings** opens the existing proxy, model visibility, search, image and context-budget configuration form in a dialog; the original Plugin settings entry remains available. Both entries save to the same settings scope. Close or Escape discards unsaved dialog edits. The Models footer is optional: profiles without that settings section retain the existing Plugin entry.
+
+The compact Models row shows **Authorize** when signed out, or **Sign out** and **View quota** when signed in. Expanding quota shows only the server-reported usage rows, without repeating account controls. If browser authorization is interrupted, use **Continue authorization** in Models (**Reopen authorization** in Plugins) to resume the pending login, or **Cancel sign-in** and retry from either settings page or another trusted browser. Cancellation preserves an existing signed-in account. An abandoned authorization expires after 10 minutes by default; the plugin's `oauthTimeoutMs` configuration accepts 1,000–1,800,000 milliseconds and applies when the plugin loads. The separate 30-second wait for the initial authorization URL remains bounded. Neither cancellation nor expiry restarts DSH.
+
 Expected result: a fresh installation shows **Not signed in** and a **Sign in with ChatGPT** button. The card is where you later manage optional capabilities too.
 
 <p align="center">
@@ -159,7 +170,7 @@ Choose **Use this proxy** only after reviewing a candidate, then click **Save ch
 
 - `enableSearch: true` registers Codex as an available search provider. It does not select the profile's global search route.
 - `enableImageTool: true` enables `view_image` for approved local reads and public-network image fetches on vision-capable models.
-- `enableImageGeneration: true` enables the prompt-only image generation tool. Use the image generation capability included with your current GPT subscription. Generated images are saved as DSH attachments and shown in the Codex Connect result gallery.
+- `enableImageGeneration: true` enables the prompt-only image generation tool. Use the image generation capability included with your current GPT subscription. Codex Connect preserves the exact generated file in plugin-owned storage and saves a DSH attachment as the conversation preview.
 
 The screenshot below is an example after someone has explicitly enabled capabilities. It does not show the fresh-install default. This English guide uses the English-localized capture; the Chinese guide shows the matching Chinese-localized state.
 
@@ -172,15 +183,17 @@ The screenshot below is an example after someone has explicitly enabled capabili
 1. Turn on **Enable GPT Image generation** in the Codex Connect card and select **Save changes**.
 2. Choose an `openai-codex` GPT model for the conversation.
 3. Describe the image you want in ordinary language. The agent can expand that request into the prompt sent to GPT Image.
-4. The completed image is stored as a DSH attachment and rendered directly in the conversation. The result card lets you review and copy the full prompt, download the image, and inspect image details.
+4. The exact generated file is preserved separately from the DSH attachment used to render the conversation preview. The result card lets you review and copy the full prompt, download the exact original or the preview, and compare their dimensions and file sizes.
 
 This capability uses the image generation access included with your current GPT subscription; it does not require an OpenAI Platform API key. Availability remains subject to the GPT plan and model selected for the conversation.
 
+Output dimensions are selected by the subscription service. The tool accepts a prompt only and does not offer a size setting or guarantee 4K output. Asking for "4K detail" does not establish the file's pixel dimensions; use the dimensions shown on the result card. Downloading the original preserves what the service returned, without upscaling it.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/image-generation.png" alt="English-localized Codex Connect GPT Image result with preview, copyable prompt, download action, and image details" width="780">
 </p>
 
-The detailed image prompt is authored by the selected GPT model. Codex Connect does not silently add image parameters: it validates the prompt-only request, forwards it through the ChatGPT subscription capability, and stores the returned image as a DSH attachment. On the result card you can scroll through and copy the complete prompt. **Try again** and **Generate another** send that card's own prompt again, so an older card is not accidentally regenerated from a newer conversation message. **Modify this image** first asks what you want to change, then continues from that card's prompt.
+The detailed image prompt is authored by the selected GPT model. Codex Connect does not silently add image parameters: it validates the prompt-only request and forwards it through the ChatGPT subscription capability. The exact returned bytes are stored below `$DSH_HOME/dsh-codex-connect/images/v1`; an additional DSH attachment is the preview used by the conversation and may be resized or re-encoded by the active DSH attachment policy. The **Download original** action always uses the plugin-owned exact file, while **Download preview** returns that DSH representation. Originals are owner-only, integrity-checked before download, and available to the creating session and forks that inherited the image result, including after session restoration. Forks made before that result and unrelated sessions cannot download it. Disabling image generation or uninstalling the plugin does not automatically delete the files; downloading through the result card requires the plugin to remain installed. On the result card you can scroll through and copy the complete prompt. **Try again** and **Generate another** send that card's own prompt again, so an older card is not accidentally regenerated from a newer conversation message. **Modify this image** first asks what you want to change, then continues from that card's prompt.
 
 ### Usage limits in Plugin configuration
 
@@ -221,6 +234,7 @@ Selecting Codex as the profile's global search route is another explicit change:
 | `models` | full catalog | Codex model id array; empty hides all entries |
 | `enableProxy` | `false` | boolean; direct connection unless explicitly enabled |
 | `proxyUrl` | `http://127.0.0.1:7890` (inactive placeholder) | Credential-free HTTP(S) proxy origin |
+| `contextWindowOverrides` | none | Per-model context-window override map; see below |
 | `enableSearch` | `false` | boolean |
 | `enableImageTool` | `false` | boolean |
 | `enableImageGeneration` | `false` | boolean |
@@ -229,6 +243,34 @@ Selecting Codex as the profile's global search route is another explicit change:
 | `searchContextSize` | `medium` | `low`, `medium`, `high` |
 | `searchMaxOutputTokens` | `10000` | positive integer |
 
+### Context-window overrides
+
+Use `contextWindowOverrides` to opt into a per-model client context budget when you have evidence that the bundled catalog does not fit your deployment. It cannot enlarge the OpenAI backend's context capacity. Overrides default off; this feature does not verify the community-reported larger windows.
+
+In Plugin configuration and **Models → More settings**, each model row shows its numeric context budget and keeps its visibility checkbox. **Context → Adjust** opens a synchronized slider and integer input, with the installed catalog default and a configuration ceiling. **Restore default** uses the catalog value even if composition supplies an override. Hiding a model preserves its budget. **Save** applies staged edits; **Discard** abandons them. An empty input is invalid, not a reset.
+
+Configuration ceilings follow the [official Codex catalog snapshot](https://github.com/openai/codex/blob/7625343977154efed8c0dadba956374992a1580b/codex-rs/models-manager/models.json), checked on 2026-08-28: GPT-5.6 Sol/Terra/Luna allow up to 872,000 tokens, GPT-5.4 up to 1,000,000, and GPT-5.5/GPT-5.4 mini up to 272,000. Models without a recorded ceiling, including Spark, are capped at their installed provider default. A provider default newer than and larger than the recorded ceiling also becomes the cap. The UI identifies the source; these values are not fetched from the user's account and are not measured server capacities. Defaults remain unchanged. Going above the default displays a quota and request-failure warning; account and route limits may differ.
+
+```yaml
+- id: llm-openai-codex
+  config:
+    contextWindowOverrides:
+      # Illustration only: 350000 is not a verified or recommended server limit.
+      gpt-5.6-sol: 350000
+```
+
+Keys must exactly match models in the installed Codex catalog. Maps accept at most 256 entries and positive safe-integer token counts within each model's configuration ceiling. Unknown ids and out-of-range values reject configuration or settings registration/writes with an explicit error; existing out-of-range overrides must be reduced or reset with `null`, not silently clamped. Other models keep their catalog metadata. Output-token limits, transport (SSE), and DSH's compaction policy are unchanged. Leave room for output and protocol overhead below your independently verified server limit. For a deployment configured to compact at 80%, a client window of `350000` gives a nominal threshold of `280000`; this arithmetic is not evidence that the server accepts that input size.
+
+Persisted Host settings are applied on plugin load, and changes affect the next model resolution or prepared request. Already prepared requests retain their captured budget. The original catalog is never mutated.
+
+To restore defaults, distinguish the settings layers:
+
+- A resolved empty map `{}` or no override uses catalog windows.
+- DSH recursively merges settings maps. Updating an existing map with `{}` is therefore not a clear operation.
+- Set `contextWindowOverrides: null` to explicitly disable all overrides, including values inherited from composition.
+- Set a model entry to `null` to restore only that model's catalog default while preserving other overrides. The UI saves explicit per-model masks so restored defaults do not re-inherit composition values.
+- Removing the stored field re-inherits composition settings; with no composition override, it restores catalog windows. Removing one stored model entry similarly restores that model's composition or catalog value.
+
 ## Reauthentication, diagnostics, and conflicts
 
 - If the card says **Sign in again** or the server asks for reauthentication, click that action and complete the same safe browser flow. It preserves this plugin's capability settings and does not silently change your default model or global search route. Do not run `logout` just to renew a session.
@@ -248,9 +290,25 @@ Selecting Codex as the profile's global search route is another explicit change:
 - If startup reports an `openai-codex` collision, an old `dsh-codex` bundle or manual provider row may already own the adapter. Inspect the effective configuration and remove only the confirmed conflicting owner. Do not delete auth files or unrelated providers.
 - Removing the package does not delete OAuth state. Run `logout` only when credential removal is intended.
 
+### On-demand capability report
+
+Run the separate `capabilities` command from the intended plugin installation. Without `--probe`, it reads local host package versions and credential-file metadata only; it does not open the credential document or send network requests. Existing `doctor` behavior and the settings compatibility card are unchanged.
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect capabilities --model gpt-5.6-sol --json
+dsh plugin --profile web exec dsh-codex-connect capabilities --model gpt-5.6-sol --probe --json
+```
+
+`--probe` explicitly sends one fixed short request to the ordinary Codex Responses route and may consume quota. It reads an unexpired stored credential without refreshing or writing it. The command uses a direct connection unless you pass `--proxy <http(s)-origin>`; it does not load the active profile's proxy settings or environment proxy variables. The default deadline is 30000 ms; `--timeout-ms <1..60000>` overrides it. There are no redirects or retries, the response is capped at 64 KiB, and owned connections are destroyed before return. A deadline or size limit does not guarantee that server-side generation stopped. The reusable diagnostic instance caches only completed responses and explicit request rejections for at most 60 seconds in memory, scoped to credential, model, versions, and network policy. Separate CLI invocations do not share cached evidence.
+
+The report labels each check `supported`, `rejected`, or `unknown`, with a reason and corrective action. Runtime support means the declared host package versions match, not that the Web profile or an exact Node patch was integration-tested. A catalog entry or private credential file leaves model access and OAuth validity `unknown`. Only an HTTP 200 finite SSE response with a complete, nonempty assistant output for the selected model confirms the standalone route; redirects, timeouts, rate limits, and incomplete streams remain `unknown`. HTTP 400/404 reject the particular request, not every model or optional feature; HTTP 401/403 also reject authorization for that request. Reports omit tokens, account ids, paths, proxy origins, response ids, headers, and generated text.
+
+This report covers only the standalone route, not active profile routing, search/image tools, browser compatibility, provider retry behavior, or session recovery. Automatic provider failover is `rejected` because this plugin does not implement it; select an alternative provider explicitly. WebSocket-to-SSE fallback is inactive with the finite SSE default. `contextManagement` and continuation remain `unknown`; native compaction and WebSocket reuse are `rejected` by the current integration policy. No diagnostic result enables these capabilities or changes Harness history. Exit codes cover runtime, OAuth, selected model, Responses, and SSE only: `0` means all five were supported, `1` means at least one was rejected, and `2` means unknown evidence, invalid options, or an inspection failure. Rejected optional capabilities do not change that exit code.
+
 ## Compatibility and security boundary
 
-- The only verified compatibility combination is DSH plugin API packages `0.1.1-rc.2`, `@earendil-works/pi-ai` `0.82.1`, and Node.js `^22.19.0 || >=24.0.0`; see [compatibility.json](compatibility.json). Alpha 4.20 uses the rc.2 keyed Plugin configuration slot; users of older DSH API packages should upgrade to the rc.2 API packages.
+- Alpha 4.22 is verified with DSH plugin API packages `0.1.2-alpha.2`, `@earendil-works/pi-ai` `^0.84.2` (resolved as `0.84.4` during verification), and Node.js `^22.19.0 || >=24.0.0`. Published Alpha 4.21 remains verified with DSH `0.1.1-rc.2` and pi-ai `0.82.1`. [verified-compatibility.json](verified-compatibility.json) records the exact pairs; see [INSTALL.md](INSTALL.md) for installation commands.
+- The new DSH client splits its former runtime into Session Controller, Settings, Store, and Renderer packages. Codex Connect uses those public interfaces for settings and image actions. DSH owns normalized preview encoding and dimensions; Codex Connect retains the exact original image separately.
 - Upgrade the DSH plugin API packages and `@earendil-works/pi-ai` as one group, then run `dsh-codex-connect doctor --json` and the compatibility check again. This contract does not make claims about future versions.
 - When the daily upstream check finds a new `latest` or `next` DSH candidate, it installs Codex Connect into an isolated profile, boots the installed model runtime without OAuth credentials, verifies model and reasoning-effort discovery, and confirms provider disposal. Live sign-in, quota, and model requests still require manual validation in the test profile.
 - ChatGPT plan eligibility, model access, quotas, and backend behavior are controlled by OpenAI and may change.

package/compatibility.json

@@ -4,7 +4,7 @@
     "node": "^22.19.0 || >=24.0.0"
   },
   "dshPluginApi": {
-    "version": "0.1.1-rc.2",
+    "version": "0.1.2-alpha.2",
     "packages": [
       "@deepseek-ai/dsh-agent",
       "@deepseek-ai/dsh-atomic-write",
@@ -18,11 +18,12 @@
       "@deepseek-ai/dsh-session",
       "@deepseek-ai/dsh-settings",
       "@deepseek-ai/dsh-tools",
+      "@deepseek-ai/dsh-util-values",
       "@deepseek-ai/dsh-web"
     ]
   },
   "piAi": {
     "package": "@earendil-works/pi-ai",
-    "version": "0.82.1"
+    "version": "^0.84.2"
   }
 }

package/docs/README.zh.md

@@ -28,7 +28,14 @@ dsh plugin --profile web add dsh-codex-connect@alpha
 
 预期结果：包被加入该 profile。这个动作不会更改 profile 的默认模型或全局搜索路由。
 
-如需精确复现这个版本，使用 `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.20`。对应 GitHub prerelease 已创建但 npm 不可用时，可使用 `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.20'`。本地 checkout 可安装为 `link:/absolute/path/to/dsh-codex-connect`。
+匹配的 npm 包发布后，使用 `dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.22` 可以精确安装 Alpha 4.22。
+
+### Alpha 4.22 更新内容
+
+- 同时适配 DSH `0.1.2-alpha.2` 的客户端设置、会话控制器接口及其声明的 `@earendil-works/pi-ai` 版本范围 `^0.84.2`。
+- 在 **设置 → 模型** 中提供紧凑的 **Openai-Codex** 卡片，用于 ChatGPT 授权、额度和共享 Codex Connect 设置，同时保留原插件设置入口。
+- 浏览器授权中断后，可以继续、取消或重试，不需要重启 DSH，也不会删除已有凭据；完整授权流程使用可配置且有范围限制的期限。
+- 使用联动的滑条和数字输入框，逐模型调整有范围限制的本地上下文预算。保存覆盖值前继续使用目录默认值；配置上限不代表服务端上下文容量。
 
 ### 版本更新提醒
 
@@ -62,6 +69,10 @@ dsh web
 
 打开 **设置 → 插件 → 插件配置 → Codex Connect**。
 
+面向 DSH `0.1.2-alpha.2` 的 Alpha 4.22 还在 **设置 → 模型** 中提供 **Openai-Codex** 账户卡，辅助文案标注“由 Codex Connect 插件提供支持。”，用于 ChatGPT 登录、重新授权、退出和查看额度。两个页面共用同一份内存账户状态及轮询。**更多设置** 会在弹窗中打开现有的代理、模型显示、搜索、图片和上下文预算配置表单，原插件设置入口仍保留。两处保存到同一份配置；关闭弹窗或按 Escape 会放弃弹窗内未保存的修改。模型页底部入口是可选增强：没有该设置分区的 profile 仍保留原插件入口。
+
+模型页紧凑卡片在未登录时显示 **授权**，已登录时显示 **退出登录** 和 **查看额度**。展开后只显示服务端返回的额度条目，不再重复账户操作。浏览器授权中断后，可以点击模型页的 **继续授权**（插件页为 **重新打开授权**）继续原登录，或点击 **取消登录** 后，从任一设置页或另一个受信任浏览器重试。取消不会退出已有账户。未完成的授权默认在 10 分钟后到期；插件配置 `oauthTimeoutMs` 可设为 1,000–1,800,000 毫秒，在插件加载时生效。获取初始授权链接仍有独立的 30 秒等待上限。取消和到期都不需要重启 DSH。
+
 预期结果：新安装时账户区显示 **尚未登录**，并出现 **使用 ChatGPT 登录** 按钮。之后管理可选能力也在同一张卡片中完成。
 
 <p align="center">
@@ -159,7 +170,7 @@ Codex Connect 默认使用**直连**。代理是可选项，只作用于本插
 
 - `enableSearch: true` 会把 Codex 注册为可选择的搜索提供方，不会把它选为 profile 的全局搜索路由。
 - `enableImageTool: true` 会为具备视觉能力的模型启用 `view_image`，用于审批后的本地读取和公网图片获取。
-- `enableImageGeneration: true` 会启用只接受文字描述的图片生成工具。使用你当前 GPT 订阅计划提供的图片生成能力。生成结果会保存为 DSH 附件，并通过 Codex Connect 结果画廊展示。
+- `enableImageGeneration: true` 会启用只接受文字描述的图片生成工具。使用你当前 GPT 订阅计划提供的图片生成能力。Codex Connect 会把生成结果的精确原文件保存到插件自有存储，同时另存一份 DSH 附件作为对话预览。
 
 下图是有人显式开启能力之后的配置示例，不是新安装的默认状态。本中文指南使用中文本地化截图；English 版展示同一状态的英文截图。
 
@@ -172,15 +183,17 @@ Codex Connect 默认使用**直连**。代理是可选项，只作用于本插
 1. 在 Codex Connect 卡片中开启 **启用 GPT Image 图片生成**，然后点击 **保存更改**。
 2. 为当前对话选择一个 `openai-codex` GPT 模型。
 3. 用自然语言描述你想要的图片；Agent 可以在调用 GPT Image 前将这段描述扩展为更完整的提示词。
-4. 图片生成后会保存为 DSH 附件，并直接显示在对话中。你可以在结果卡片里查看和复制完整提示词、下载图片，以及展开图片详情。
+4. 图片生成后，精确原文件会与用于对话展示的 DSH 附件分开保存。你可以在结果卡片里查看和复制完整提示词、分别下载原文件或预览，并比较两者的尺寸与文件大小。
 
 此能力使用你当前 GPT 订阅计划提供的图片生成权限，不需要 OpenAI Platform API Key；具体可用性仍取决于当前对话所选的 GPT 套餐和模型。
 
+输出尺寸由订阅服务决定。工具只接受提示词，不提供尺寸设置，也不保证生成 4K 图片。要求“4K 级细节”不代表文件具有 4K 像素尺寸，请以结果卡片显示的尺寸为准。下载原文件会保留服务实际返回的图片，不会将其放大。
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/zh/image-generation.png" alt="Codex Connect 中文 GPT Image 结果卡片，包含图片预览、可复制提示词、下载操作和图片详情" width="780">
 </p>
 
-图片的详细提示词由当前选择的 GPT 模型生成。Codex Connect 不会偷偷添加图片参数：它只校验“提示词”请求，通过 ChatGPT 订阅提供的图片能力发送，并把返回图片保存为 DSH 附件。结果卡片里的提示词可以滚动查看和复制。点击 **再次尝试** 或 **再生成一张** 时，会重新发送这张卡片自己的提示词，不会因为后来出现了新的对话消息而误用最新上下文。点击 **基于此图修改** 时，模型会先询问你想改什么，再基于这张卡片的提示词继续处理。
+图片的详细提示词由当前选择的 GPT 模型生成。Codex Connect 不会偷偷添加图片参数：它只校验“提示词”请求，并通过 ChatGPT 订阅提供的图片能力发送。服务返回的精确字节保存在 `$DSH_HOME/dsh-codex-connect/images/v1`；对话中使用的是另一份 DSH 附件预览，可能按照当前 DSH 附件策略缩放或重新编码。点击 **下载原文件** 得到的一定是插件保存的精确文件，**下载预览** 得到的是 DSH 表示。原文件仅允许文件所有者访问，下载前会校验完整性；创建图片的会话以及继承了该图片结果的 fork 会话均可下载，恢复会话后仍然有效。在该结果之前创建的 fork 会话和无关会话不能下载。关闭图片生成或卸载插件不会自动删除这些文件；通过结果卡片下载仍需安装插件。结果卡片里的提示词可以滚动查看和复制。点击 **再次尝试** 或 **再生成一张** 时，会重新发送这张卡片自己的提示词，不会因为后来出现了新的对话消息而误用最新上下文。点击 **基于此图修改** 时，模型会先询问你想改什么，再基于这张卡片的提示词继续处理。
 
 ### 插件配置中的额度说明
 
@@ -221,6 +234,7 @@ Codex Connect 默认使用**直连**。代理是可选项，只作用于本插
 | `models` | 完整目录 | Codex model id 数组；空数组隐藏全部条目 |
 | `enableProxy` | `false` | boolean；除非显式启用，否则使用直连 |
 | `proxyUrl` | `http://127.0.0.1:7890`（未启用的占位值） | 不带凭据的 HTTP(S) proxy origin |
+| `contextWindowOverrides` | 无 | 按模型覆盖 contextWindow 的映射；见下文 |
 | `enableSearch` | `false` | boolean |
 | `enableImageTool` | `false` | boolean |
 | `enableImageGeneration` | `false` | boolean |
@@ -229,6 +243,34 @@ Codex Connect 默认使用**直连**。代理是可选项，只作用于本插
 | `searchContextSize` | `medium` | `low`、`medium`、`high` |
 | `searchMaxOutputTokens` | `10000` | 正整数 |
 
+### 上下文窗口覆盖
+
+当你有证据表明内置目录不适合当前部署时，可通过 `contextWindowOverrides` 主动设置每个模型的客户端上下文预算。它不能扩大 OpenAI 后端的上下文容量。默认不启用；此功能并未验证社区报告的更大窗口。
+
+在插件配置和“模型 → 更多设置”中，每个模型行显示具体的上下文预算，并保留显示勾选框。“上下文 → 调整”展开双向同步的滑条和整数输入框，同时显示已安装目录的默认值及配置上限。“恢复默认”使用目录值，即使启动配置中有覆盖值也不例外。隐藏模型会保留其预算。“保存”提交暂存修改，“放弃”撤销修改。清空输入框属于无效输入，不等于恢复默认。
+
+配置上限依据于 2026-08-28 核对的 [Codex 官方目录快照](https://github.com/openai/codex/blob/7625343977154efed8c0dadba956374992a1580b/codex-rs/models-manager/models.json)：GPT-5.6 Sol/Terra/Luna 为 872,000 tokens，GPT-5.4 为 1,000,000，GPT-5.5/GPT-5.4 mini 为 272,000。没有已记录上限的模型（包括 Spark）暂以已安装提供方目录的默认值为上限；如果更新后的提供方默认值高于已记录上限，也以该默认值为上限。界面会标明依据；这些数值不是从用户账号动态获取的，也不是实测的服务端容量。默认值保持不变；超过默认值会提示额度消耗及请求失败风险，账号和通道限制可能不同。
+
+```yaml
+- id: llm-openai-codex
+  config:
+    contextWindowOverrides:
+      # 仅为示例：350000 不是已验证或推荐的服务端上限。
+      gpt-5.6-sol: 350000
+```
+
+键必须与已安装 Codex 目录中的模型 ID 完全一致。映射最多包含 256 项，token 数必须是模型配置上限内的正安全整数。未知 ID 或超范围数值会使配置或设置注册、写入明确报错；已有的超范围覆盖值需要调低或用 `null` 恢复默认，不会被静默截断。其他模型保留目录元数据。输出 token 上限、SSE 传输和 DSH 的压缩策略不变。请在独立验证过的服务端上限内，为输出及协议开销预留空间。如果部署设置为在 80% 时压缩，客户端窗口 `350000` 对应的名义阈值是 `280000`；这个算式不证明服务端接受这么大的输入。
+
+插件加载时会应用持久化的 Host 设置，运行中修改会作用于下一次模型解析或请求准备。已经准备好的请求保留当时的预算快照。原始模型目录不会被修改。
+
+恢复默认值时，需要区分配置层：
+
+- 最终生效的映射为 `{}` 或没有覆盖时，使用目录窗口。
+- DSH 会递归合并设置映射，因此用 `{}` 更新已有映射不等于清空。
+- 设置 `contextWindowOverrides: null` 可明确关闭所有覆盖，包括从启动配置继承的值。
+- 将某个模型条目设为 `null`，可只恢复该模型的目录默认值，保留其他覆盖。界面保存时会为默认模型写入明确的空值标记，防止恢复默认后重新继承启动配置值。
+- 删除持久化字段会重新继承启动配置；启动配置没有覆盖时，恢复目录窗口。删除某个持久化模型条目，同样会恢复该模型的启动配置值或目录值。
+
 ## 重新登录、诊断与冲突
 
 - 卡片显示 **重新登录**，或服务端要求重新认证时，点击该操作并完成同一套安全的浏览器流程。它会保留本插件的能力配置，不会偷偷改动默认模型或全局搜索路由。不要为了刷新会话而运行 `logout`。
@@ -248,9 +290,25 @@ Codex Connect 默认使用**直连**。代理是可选项，只作用于本插
 - 启动报告 `openai-codex` 冲突时，旧 `dsh-codex` bundle 或手动 provider 配置可能已占用该 adapter。先检查有效配置，只移除已确认的冲突所有者。不要删除认证文件或无关 provider。
 - 移除包不会删除 OAuth 状态；只有确实需要删除凭据时才运行 `logout`。
 
+### 按需能力报告
+
+请从目标插件安装位置运行独立的 `capabilities` 命令。不传 `--probe` 时，它只读取本地主机包版本与认证文件元数据，不打开认证文件内容，也不发送网络请求。现有 `doctor` 行为和设置页兼容性卡不变。
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect capabilities --model gpt-5.6-sol --json
+dsh plugin --profile web exec dsh-codex-connect capabilities --model gpt-5.6-sol --probe --json
+```
+
+`--probe` 显式向普通 Codex Responses 路由发送一条固定短请求，可能消耗额度。它读取尚未过期的已存凭据，但不刷新或写入凭据。除非传入 `--proxy <http(s)-origin>`，否则命令使用直连，不读取正在运行的 profile 代理设置或环境代理变量。默认期限为 30000 ms，可通过 `--timeout-ms <1..60000>` 调整。命令不跟随重定向、不重试，响应上限为 64 KiB，并在返回前销毁自有连接。达到期限或大小上限不保证服务端生成已经停止。可复用诊断实例仅将完整响应和明确请求拒绝在内存中缓存至多 60 秒，按凭据、模型、版本与网络策略隔离。不同 CLI 调用之间不共享缓存证据。
+
+报告为每项检查标注 `supported`（可用）、`rejected`（拒绝）或 `unknown`（未验证），并提供原因与修复动作。运行时可用仅表示声明的主机包版本匹配，不代表 Web profile 或某个 Node 补丁版本经过集成验证。模型目录条目或私有认证文件只能令模型权限与 OAuth 有效性保持 `unknown`。只有 HTTP 200 有限 SSE 响应包含所选模型完整、非空的助手输出，才能确认独立路由；重定向、超时、限流和不完整流仍为 `unknown`。HTTP 400/404 拒绝的是本次请求，并非所有模型或可选功能；HTTP 401/403 还表示本次请求的授权被拒绝。报告省略 token、账号 ID、路径、代理 origin、响应 ID、headers 和生成文本。
+
+本报告仅涵盖独立路由，不验证活动 profile 路由、搜索/图片工具、浏览器兼容性、provider 重试行为或会话恢复。本插件没有实现自动 provider 故障切换，因此该项为 `rejected`，需要用户明确选择其他 provider。有限 SSE 默认路径不会触发 WebSocket 到 SSE 的回退。`contextManagement` 和续接仍为 `unknown`；原生 compaction 和 WebSocket reuse 在当前集成策略下为 `rejected`。诊断结果不会启用这些能力，也不会更改 Harness 历史。退出码只覆盖运行时、OAuth、所选模型、Responses 和 SSE：`0` 表示五项均可用，`1` 表示至少一项被拒绝，`2` 表示证据未知、选项无效或检查失败。被拒绝的可选能力不影响该退出码。
+
 ## 兼容性与安全边界
 
-- 当前唯一已验证的兼容组合是 DSH 插件 API packages `0.1.1-rc.2`、`@earendil-works/pi-ai` `0.82.1` 和 Node.js `^22.19.0 || >=24.0.0`；详见 [compatibility.json](../compatibility.json)。Alpha 4.20 使用 rc.2 的 keyed 插件配置 slot；旧版 DSH API packages 用户应升级到 rc.2 API packages。
+- Alpha 4.22 已与 DSH 插件 API packages `0.1.2-alpha.2`、`@earendil-works/pi-ai` `^0.84.2`（验证时解析为 `0.84.4`）和 Node.js `^22.19.0 || >=24.0.0` 完成验证。已发布 Alpha 4.21 仍与 DSH `0.1.1-rc.2` 和 pi-ai `0.82.1` 保持已验证状态。[verified-compatibility.json](../verified-compatibility.json) 记录精确组合；安装命令见 [INSTALL.md](../INSTALL.md)。
+- 新版 DSH 将原来的 client runtime 拆分为 Session Controller、Settings、Store 和 Renderer 包。Codex Connect 通过这些公开接口接入设置和图片操作。规范化预览的编码与尺寸由 DSH 决定；Codex Connect 另行保留字节完全一致的原图。
 - 升级时请将 DSH 插件 API packages 与 `@earendil-works/pi-ai` 作为一组升级，再运行 `dsh-codex-connect doctor --json` 和兼容性检查。本契约不对未来版本作判断。
 - 每日上游检查发现新的 DSH `latest` 或 `next` 候选版本时，会把 Codex Connect 安装到隔离 Profile 中，在没有 OAuth 凭据的情况下启动已安装的模型运行时，验证模型与推理强度发现，并确认提供方可被正确卸载。真实登录、额度和模型请求仍需在测试 Profile 中人工验证。
 - ChatGPT 套餐资格、模型权限、额度和后端行为由 OpenAI 控制，可能变化。

package/docs/agent-notes/original-image-fork-access.md

@@ -0,0 +1,7 @@
+# Agent Note: Original image access from forked sessions
+
+Original image files retain their creating session ID and immutable byte metadata. DSH forks copy tool-result events into a new session whose durable header records `parentSession` and `seedLength`. The download route accepts a cross-owner read only when that session's inherited event prefix contains a decoded Codex image result with the requested original reference, and every reference field matches the stored metadata. The HTTP caller supplies only session and asset IDs, never an inheritance proof.
+
+Checking only the immediate parent would fail nested forks and restored sessions whose ancestors are not loaded. Granting access to every ancestor asset would expose images created after the fork boundary. The inherited event prefix supplies the narrower authorization without a second grant database or a new stored-reference format. Session records are trusted local DSH state; malformed presentation metadata is rejected by the existing decoder. Files remain subject to permission, format, dimensions, byte count and SHA-256 verification.
+
+The route tests exercise the real DSH `SessionStore.fork` and `Session.fromRestore` paths with file-backed original storage. They cover exact downloads from nested/restored forks, absent ancestors, earlier forks, live references outside the inherited prefix, unrelated sessions, and mismatched stored metadata. They make no ChatGPT request and do not require a running profile. Existing presentation tests cover legacy preview-only records; no model-visible output or reference schema changes are introduced by this access fix.

package/docs/design.i18n.yaml

@@ -1,4 +1,4 @@
 # Bilingual-pair consistency record for the design document. Re-record with:
 #   git hash-object docs/design.md docs/design.zh.md
-design.md: c03949ff0c973040401b558cadf34f92cdccf568
-design.zh.md: 2bd55edd9b6a6f079775eaf6dcc5892755ef6fda
+design.md: 981c5097e5aa008ce087b3cbd9651e60e0b0dffc
+design.zh.md: 81327b8268011fe2bb80b203c2e430610911d0f7

package/docs/design.md

@@ -26,4 +26,4 @@ Before registration the plugin checks current provider ids. An existing `openai-
 
 ## Compatibility boundary
 
-The Alpha pins Harness `0.1.1-rc.2` development dependencies and uses its keyed `settings.plugin.item` contract; supported Node.js is `^22.19.0 || >=24.0.0`. It pins `@earendil-works/pi-ai` `0.82.1`. Backend eligibility, quotas, models, and protocol details remain controlled upstream. Tests use temporary OAuth documents and mocked network responses; CI does not perform real authentication.
+Alpha 4.22 pins Harness `0.1.2-alpha.2` development dependencies and follows its pi-ai range `^0.84.2`; the verified release lockfile selects pi-ai `0.84.4`. Supported Node.js remains `^22.19.0 || >=24.0.0`. The keyed `settings.plugin.item` integration remains, while client types come from their Session Controller, Settings, Store, and Renderer owners instead of the removed client-runtime package. The published compatibility record lists the exact Alpha 4.22 and DSH `0.1.2-alpha.2` pair. Backend eligibility, quotas, models, service-side context capacity, and protocol details remain controlled upstream. Tests use temporary OAuth documents and mocked network responses; CI does not perform real authentication.

package/docs/design.zh.md

@@ -22,4 +22,4 @@ Host 将 `llm-openai-codex` 注册为插件自有的能力 settings namespace。
 
 注册前检查现有 provider id；发现 `openai-codex` 已被占用时，给出旧 bundle 或手动 provider 配置的定向迁移提示。boot-free CLI doctor 只报告包/运行时版本、OAuth 路径元数据、能力默认值和安全提示。
 
-Alpha 固定使用 Harness `0.1.1-rc.2` 开发依赖，并采用其 keyed `settings.plugin.item` 契约；Node.js 支持 `^22.19.0 || >=24.0.0`。`@earendil-works/pi-ai` 固定为 `0.82.1`。资格、额度、模型和后端协议仍由上游控制。测试仅使用临时 OAuth 文档和模拟网络响应，CI 不执行真实认证。
+Alpha 4.22 固定使用 Harness `0.1.2-alpha.2` 开发依赖，并跟随其 pi-ai 版本范围 `^0.84.2`；已验证的发布锁文件选择 pi-ai `0.84.4`。Node.js 支持范围仍为 `^22.19.0 || >=24.0.0`。keyed `settings.plugin.item` 集成保持不变，客户端类型改从 Session Controller、Settings、Store 和 Renderer 的所属包导入，不再依赖已移除的 client-runtime 包。已发布兼容性记录列出 Alpha 4.22 与 DSH `0.1.2-alpha.2` 的精确组合。资格、额度、模型、服务端上下文容量和后端协议仍由上游控制。测试仅使用临时 OAuth 文档和模拟网络响应，CI 不执行真实认证。