dsh-gpt-adapter 0.2.2 → 0.2.4

package/README.md

@@ -12,6 +12,7 @@ Install one plugin to reuse local Codex instructions, skills, enabled plugin res
 
 - Discover upstream models with `GET /models` and retain stale entries until explicit cleanup.
 - Provide the GPT reasoning preset `low / medium / high / xhigh / max / ultra` through the native Models page and conversation menu.
+- Provide per-model Default, 516K, 1M, and Custom context windows, with the effective capacity and its source shown in settings.
 - Offer independent Standard and Fast speed choices. Fast sends `service_tier: "priority"`; Ultrafast requires an explicit upstream declaration or override.
 - Preserve optional function arguments on GPT Responses requests by setting missing `strict` values to `false`.
 - Read Codex instruction files and refresh them at the next model step without repeating unchanged baselines.
@@ -22,9 +23,19 @@ Reasoning and speed presets are requests to the configured gateway, not guarante
 
 ## Compatibility and installation
 
-The native integration targets DSH `0.2.2-rc.1`, Cordis `4.1.0`, and the pinned adapter source hash. The development dependency uses Pi AI `1.3.0`. Installed third-party package files are never edited. The package has not been published to npm.
+The native integration targets DSH `0.2.2-rc.1`, Cordis `4.1.0`, and the pinned adapter source hash. The development dependency uses Pi AI `1.3.0`. Installed third-party package files are never edited. The package version is `dsh-gpt-adapter@0.2.4`.
 
-Requires Node.js `>=24.9.0` and pnpm.
+Requires Node.js `>=24.9.0` and DSH. Source builds also require pnpm.
+
+Install the published package in the web profile:
+
+```sh
+dsh plugin --profile web add dsh-gpt-adapter@0.2.4
+```
+
+Restart the DSH host after installing or upgrading. Configure GPT connections under **Settings → Models**; Codex environment reuse is enabled by default. The plugin extends the existing native settings and conversation controls.
+
+To install from source for development or verification:
 
 ```sh
 git clone https://github.com/lxjmaster/dsh-gpt-adapter.git
@@ -32,17 +43,16 @@ cd dsh-gpt-adapter
 pnpm install --frozen-lockfile
 mkdir -p artifacts
 pnpm pack --pack-destination artifacts
-dsh plugin --profile web add ./artifacts/dsh-gpt-adapter-0.2.2.tgz
+dsh plugin --profile web add ./artifacts/dsh-gpt-adapter-0.2.4.tgz
 ```
 
-`pnpm pack` runs the production build. Restart the DSH host after upgrading the installed package.
+`pnpm pack` runs the production build.
 
 ## Automated releases
 
 The `Release` workflow runs on pushes to `main` and manual dispatches. For a formal `X.Y.Z` version, it runs the test suite, creates `vX.Y.Z`, creates the matching GitHub Release, and publishes the package to npm. Prerelease versions are skipped, and existing tags or npm versions are reused safely.
 
-Add an npm access token as the repository secret `NPM_TOKEN` before the first release.
-Configure GPT connections as usual under **Settings → Models**. The plugin extends the existing native settings and conversation controls.
+Maintainers must provide the npm access token as the repository secret `NPM_TOKEN` for this workflow.
 
 ## Codex environment reuse
 
@@ -58,12 +68,14 @@ Codex compatibility is enabled by default. The root is the plugin's `codexHome`
 | Codex skills                   | Discover `skills/` and `skills/.system/`; bodies load on demand                                                                                   |
 | Shared/project skills          | Retain native discovery and include `.agents/skills` at every directory from cwd to repository root; nearer project skills take precedence        |
 | Skill enablement               | Honor ordered `skills.config` name/path selectors and `skills.bundled.enabled`                                                                    |
-| Enabled plugins                | Read declared skill roots and inline or file-referenced `mcpServers`; disabled plugins stay disabled                                              |
+| Enabled plugins                | Support portable root `plugin.json` / `mcp.json` and legacy declarations; disabled plugins stay disabled                                          |
 
 The compatibility layer reads project instructions through DSH's filesystem, selects candidates using Codex precedence, and replaces native messages only for covered scopes. Additional nested instruction updates remain applicable. It does not import Codex's built-in system prompt. Configured fallback filenames such as `CLAUDE.md` are used only when supplied in Codex configuration. Instructions are recorded as ordinary user context with a bounded byte budget, including an explicit zero budget; they do not override system, developer, or direct user instructions. Existing conversation history is retained when the plugin is removed.
 
 Plugin resources are resolved from the configured local marketplace, or the newest locally cached version in the matching marketplace. Nothing is downloaded automatically. Plugin skills use `<plugin>-<skill>` names to fit DSH's skill-name format and avoid cross-plugin collisions. Original skill paths and relative resources remain intact.
 
+Portable Agent Plugins use fixed `skills/` and `mcp.json` components, regardless of legacy `skills` or `mcpServers` declarations. OpenAI settings come from the root manifest's `extensions.com.openai` object, including an empty object; only when absent does `.codex-plugin/plugin.json` supply the overlay. Plugin identity always comes from the root manifest.
+
 ## MCP compatibility
 
 The plugin automatically starts enabled MCP commands and connects configured HTTP endpoints for each Agent session. It imports `mcp_servers` and the MCP resources declared by enabled plugins. Trusted project overrides apply within that Agent's scope; concurrent sessions do not share imported tool registrations. Untrusted project configuration is skipped.
@@ -77,6 +89,14 @@ Supported configuration includes:
 
 Global server names are retained where DSH permits them. Plugin servers use a plugin prefix. Unchanged connections are preserved. Changed or removed connections are disposed before replacement. Invalid configuration retains the last working snapshot, including individually invalid server entries. With automatic refresh enabled, failed startup retries with exponential backoff for up to ten attempts; a manual refresh resets that budget. The default two-second refresh detects configuration and plugin-resource changes; native skill watchers detect skill file changes.
 
+Plugin-scoped `plugins.<plugin>.mcp_servers.<server>` policies apply `enabled`, `enabled_tools`, `disabled_tools`, and per-tool disabling without overriding the plugin's executable, transport, or credentials. When plugin files are invalid, retained connections still receive current disabling and filtering restrictions; old restrictions are not relaxed until a valid declaration is available again.
+
+Stdio servers default to their Agent's project working directory and reconnect when that directory changes. An explicit `cwd` takes precedence. Without an explicit `cwd`, relative executable paths still resolve from the config or plugin root, independently of the process working directory. Plugin paths support `${PLUGIN_ROOT}`, `${CODEX_PLUGIN_ROOT}`, and `${CLAUDE_PLUGIN_ROOT}`.
+
+Imported MCP tools carry the current DSH session and turn in `tools/call` metadata under `_meta["x-codex-turn-metadata"]`. `session_id` is the Agent session ID; `turn_id` is `<session ID>:<turn/start event sequence>`. Calls in one turn share the same identity, new turns read a fresh boundary, and asynchronous sessions remain isolated. Diagnostic calls outside an active turn do not invent identities. These fields are transport metadata, never model-supplied tool arguments.
+
+The path is DSH Agent → imported tool execution context → MCP `tools/call` metadata → `node_repl` → browser service. This bridge addresses `Missing required Codex turn metadata: session_id, turn_id`; the browser extension, authentication, and App-specific services must still be available on the host. Unloading the plugin removes the bridge, and ordinary DSH MCP calls do not receive these fields.
+
 Credentials are not copied into DSH settings, plugin caches, or this repository. Status responses contain only resource names, states, and sanitized reason codes. Missing environment variables must exist in the DSH host environment to be inherited.
 
 This is environment compatibility, not a replacement Codex runtime. Codex OAuth/keychain sessions, Codex App IPC services, hooks, app components, permission policies, and proprietary commands are not automatically reproduced. Standard MCPs using configured headers/environment can be reused; servers requiring unavailable runtime authentication or services report a connection failure. Plugin hooks/apps/commands are reported as unsupported rather than executed. DSH retains its own approval and sandbox behavior.
@@ -106,6 +126,27 @@ An empty `mcpAllowlist` imports all enabled declared servers. A nonempty list fi
 
 Capability precedence is user override, explicit upstream metadata, external catalog, then preset. Catalog requests never receive the provider API key. Model-list responses may omit capability metadata. Reasoning is sent as `reasoning.effort` for Responses and `reasoning_effort` for Chat Completions; the selected protocol is preserved.
 
+### Context windows
+
+Under **Settings → Models**, expand **Context window** in the provider's GPT adaptation section. Each managed GPT model has four choices:
+
+| Choice | Capacity in tokens |
+| --- | --- |
+| Default | Resolve automatically for this model and provider. |
+| 516K | `516000` |
+| 1M | `1000000` |
+| Custom | A positive safe integer entered by the user. |
+
+These use decimal units. The displayed capacity includes its source. Default uses a distinguishable explicit provider default, upstream model metadata, the configured capability catalog, the shipped exact-model preset, then the native catalog/DSH fallback. A native fallback is labeled as such. Shipped presets are dated data, not a live fetch from OpenAI: `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6.1-terra`, `gpt-6-luna`, and `gpt-5.4` use `1050000`; `gpt-4.1` uses `1047576`; `gpt-4o` uses `128000`. Only documented snapshot aliases share these presets. References and verification dates are in [the preset table](src/context-window.ts).
+
+Existing native per-model values, including catalog `modelOverrides`, and legacy JSON context overrides remain effective until deliberately edited. Saving a preset uses the native model field and clears only that model's legacy context override; Default removes both per-model overrides while retaining provider defaults and other settings. Saving unrelated settings or discovering models does not turn automatic values into manual overrides. Identical model IDs on different providers are independent. Saving Custom at a preset's exact value shows that preset after saving or reloading.
+
+Providers using native catalog `modelOverrides` keep their catalog configuration during synchronization. Discovery and stale cleanup update the plugin snapshot without creating an incompatible explicit `models` list or deleting native overrides.
+
+Native forms reject stale drafts when their automatic capacities change; refresh the form before retrying. The preset controls retain drafts across unrelated saves. If the same model changes, review its current value and use the keep-draft action before saving again.
+
+Changes apply to the next prepared call; calls already prepared retain their captured capacity. Model information, the inference model, overflow detection, and native compaction use the same effective window. Maximum output tokens and DSH's compaction policy remain independent. A larger local window does not increase the gateway's accepted limit.
+
 Preset reasoning fields are projected into the native UI rather than persisted into native model configuration. Disabling GPT adaptation restores the native model values and schema. Speed selections are persisted per session. Synchronization failures retain the previous snapshot; absent models remain stale until explicit cleanup.
 
 GPT model snapshots and speed selections are stored under `$DSH_HOME/storages/gpt-adapter`. Codex source files and imported MCP credentials are not copied there. The DSH host owns normal session transcripts and logs.

package/README.zh-CN.md

@@ -12,6 +12,7 @@
 
 - 通过 `GET /models` 发现上游模型；失效模型保留到用户主动清理。
 - 在原生模型设置页和对话菜单中提供 `low / medium / high / xhigh / max / ultra` 六档思考预设。
+- 为每个模型提供「默认、516K、1M、自定义」四档上下文窗口，展示实际容量与来源。
 - 提供独立的 Standard 和 Fast 速度选择。Fast 发送 `service_tier: "priority"`；Ultrafast 由上游明确声明或用户覆盖提供。
 - 为 GPT Responses 函数工具补齐缺失的 `strict: false`，保留可选参数。
 - 读取 Codex 指令，在下一模型步骤更新；内容不变时不重复注入。
@@ -22,9 +23,19 @@
 
 ## 兼容性与安装
 
-原生集成面向 DSH `0.2.2-rc.1`、Cordis `4.1.0`，并校验适配器源码指纹。开发依赖固定 Pi AI `1.3.0`。插件不会修改已安装的第三方包文件，目前未发布到 npm。
+原生集成面向 DSH `0.2.2-rc.1`、Cordis `4.1.0`，并校验适配器源码指纹。开发依赖固定 Pi AI `1.3.0`。插件不会修改已安装的第三方包文件。插件版本为 `dsh-gpt-adapter@0.2.4`。
 
-需要 Node.js `>=24.9.0` 和 pnpm。
+需要 Node.js `>=24.9.0` 和 DSH。源码构建另外需要 pnpm。
+
+在 `web` 配置档（profile）中安装已发布的 npm 包：
+
+```sh
+dsh plugin --profile web add dsh-gpt-adapter@0.2.4
+```
+
+安装或升级后重启 DSH 宿主。在「设置 → 模型」中配置 GPT 连接；Codex 环境复用默认开启。插件扩展现有原生设置与对话控件。
+
+如需从源码安装进行开发或验证：
 
 ```sh
 git clone https://github.com/lxjmaster/dsh-gpt-adapter.git
@@ -32,17 +43,16 @@ cd dsh-gpt-adapter
 pnpm install --frozen-lockfile
 mkdir -p artifacts
 pnpm pack --pack-destination artifacts
-dsh plugin --profile web add ./artifacts/dsh-gpt-adapter-0.2.2.tgz
+dsh plugin --profile web add ./artifacts/dsh-gpt-adapter-0.2.4.tgz
 ```
 
-`pnpm pack` 会自动执行生产构建。升级安装包后重启 DSH 宿主。
+`pnpm pack` 会自动执行生产构建。
 
 ## 自动发布
 
 `Release` 工作流会在推送到 `main` 或手动运行时执行。版本号为正式的 `X.Y.Z` 时，工作流会运行测试、创建 `vX.Y.Z` 标签、创建对应的 GitHub Release，并将包发布到 npm。预发布版本会跳过；已有标签或 npm 版本会安全复用。
 
-首次发布前，请在仓库 Secrets 中添加 npm 访问令牌 `NPM_TOKEN`。
-在「设置 → 模型」中照常配置 GPT 连接；插件扩展现有原生设置与对话控件。
+维护者需要在仓库 Secrets 中提供 npm 访问令牌 `NPM_TOKEN`，工作流才能发布。
 
 ## 复用 Codex 环境
 
@@ -58,12 +68,14 @@ dsh plugin --profile web add ./artifacts/dsh-gpt-adapter-0.2.2.tgz
 | Codex 技能         | 发现 `skills/` 和 `skills/.system/`，正文按需加载                                                   |
 | 共享与项目技能     | 保留原生发现机制，并补齐当前目录到仓库根每一级 `.agents/skills`；更近的项目技能优先                 |
 | 技能开关           | 遵循有序的 `skills.config` 名称/路径选择器，以及 `skills.bundled.enabled`                           |
-| 已启用插件         | 读取声明的技能目录和内联或文件引用形式的 `mcpServers`；禁用插件不加载                               |
+| 已启用插件         | 支持新版根目录 `plugin.json`、`mcp.json` 和旧版声明；禁用插件不加载                                 |
 
 兼容层通过 DSH 文件系统读取项目指令，按 Codex 优先级选择候选文件，只替换已覆盖作用域内的原生指令消息；额外发现的子目录指令更新仍然保留。它不会导入 Codex 内置系统提示词。`CLAUDE.md` 等后备文件仅在 Codex 配置明确声明时使用。指令以有字节预算的普通用户上下文写入会话，明确配置的零预算也会生效；指令不覆盖系统、开发者或用户直接指令。移除插件不会删除已有会话历史。
 
 插件资源优先来自已配置的本地市场目录，否则使用匹配市场中最新的本地缓存版本，不会自动下载。插件技能使用 `<插件名>-<技能名>`，以符合 DSH 命名格式并避免跨插件冲突。技能原始路径和相对资源引用保持不变。
 
+新版 Agent Plugins 使用固定的 `skills/` 与 `mcp.json`，不受旧版 `skills`、`mcpServers` 声明改写。OpenAI 扩展优先使用根清单的 `extensions.com.openai` 对象（包括空对象），缺省时才使用 `.codex-plugin/plugin.json`；插件名称仍取自根清单。
+
 ## MCP 兼容
 
 插件会为每个会话代理（Agent）自动启动已启用的 MCP 命令并连接已配置的 HTTP 端点。导入来源包括 `mcp_servers` 和已启用插件声明的 MCP 资源。受信任项目的覆盖配置只在该会话代理的作用域内生效，并行会话不会共用导入工具的注册；未受信任项目的配置会跳过。
@@ -77,6 +89,14 @@ dsh plugin --profile web add ./artifacts/dsh-gpt-adapter-0.2.2.tgz
 
 全局服务器名称在 DSH 允许时原样保留，插件服务器增加插件名前缀。未变化的连接继续复用；变更或删除的连接先卸载再替换。配置损坏时保留上一份有效快照，单个服务器配置无效时也会保留其可用连接。开启自动刷新时，启动失败会按指数退避间隔重试，最多尝试十次；手动刷新会重置次数。默认每两秒检查配置与插件资源变化，技能文件变化由原生监视器处理。
 
+插件级 `plugins.<插件>.mcp_servers.<服务器>` 的 `enabled`、`enabled_tools`、`disabled_tools` 和单工具禁用设置会覆盖声明中的策略，但不能改写插件的命令、传输或凭证。插件文件损坏时，保留的旧连接仍应用最新禁用和过滤限制；有效声明恢复前，不会放宽旧快照已有的限制。
+
+stdio 服务器默认从所属 Agent 的项目工作目录启动，切换项目时重建连接；显式 `cwd` 配置优先。未显式配置 `cwd` 时，相对可执行文件路径仍按配置或插件根目录解析，避免与运行目录混淆。插件根目录替换同时支持 `${PLUGIN_ROOT}`、`${CODEX_PLUGIN_ROOT}` 和 `${CLAUDE_PLUGIN_ROOT}`。
+
+导入的 MCP 工具会在 `tools/call` 的 `_meta["x-codex-turn-metadata"]` 中携带当前 DSH 会话和轮次信息。`session_id` 使用 Agent 的会话 ID，`turn_id` 使用 `<会话 ID>:<turn/start 事件序号>`；同一轮的调用保持一致，新轮次重新读取，异步并发会话相互隔离。没有活动轮次的诊断调用不生成虚假标识。这些字段不进入工具参数，也不要求模型填写。
+
+调用链为：DSH Agent → 导入工具的异步调用上下文 → MCP `tools/call` 元数据 → `node_repl` → 浏览器服务。此桥接修复浏览器服务因缺少 `session_id`、`turn_id` 抛出的 `Missing required Codex turn metadata`；浏览器扩展、认证和 App 专属服务仍需在宿主可用。插件卸载时撤销桥接，普通 DSH MCP 调用不注入这些字段。
+
 凭证不会复制到 DSH 设置、插件缓存或本仓库。状态接口只返回资源名、状态和经过脱敏的原因代码。需要继承的环境变量必须存在于 DSH 宿主环境中。
 
 本插件提供环境兼容，不会重新实现 Codex 运行时。Codex 的 OAuth/钥匙串会话、App 专属进程通信服务、Hooks、应用组件、权限策略和专用命令不会自动重现。使用配置中的请求头或环境变量认证的标准 MCP 可以复用；依赖缺失认证或运行时服务的服务器会报告连接失败。插件的 Hooks、应用和命令明确标为不支持，不会自动执行。审批和沙箱仍由 DSH 自身管理。
@@ -106,6 +126,27 @@ codexCompatibility:
 
 能力优先级为用户覆盖、上游明确元数据、外部能力目录、预设。能力目录请求不携带提供商 API 密钥；模型列表可以不包含能力元数据。Responses 使用 `reasoning.effort`，Chat Completions 使用 `reasoning_effort`，保留用户选定的协议。
 
+### 上下文窗口
+
+在「设置 → 模型」中，展开提供商卡片的 GPT 自动适配区域内的「上下文窗口」，即可逐个模型设置：
+
+| 选项 | 容量（词元数） |
+| --- | --- |
+| 默认 | 根据当前模型与提供商自动解析。 |
+| 516K | `516000` |
+| 1M | `1000000` |
+| 自定义 | 用户输入的正安全整数。 |
+
+固定档使用十进制单位。界面展示实际容量和来源。「默认」依次采用可辨识的显式提供商默认值、上游模型元数据、已配置的能力目录、插件内置的精确模型预设、原生目录或 DSH 后备值；后备值会如实标注来源。内置预设是带核验日期的数据，不会实时抓取 OpenAI 页面：`gpt-6-astra`、`gpt-6.1-sol`、`gpt-6.1-terra`、`gpt-6-luna`、`gpt-5.4` 为 `1050000`，`gpt-4.1` 为 `1047576`，`gpt-4o` 为 `128000`；仅为有文档依据的快照别名复用预设。参考页面和核验日期见[预设表](src/context-window.ts)。
+
+已有原生模型数值（包括目录模型的 `modelOverrides`）和旧版 JSON 上下文覆盖继续生效，直到用户主动编辑。保存预设会使用原生模型字段，并仅清除该模型的旧版上下文覆盖；选择「默认」会删除两处逐模型覆盖，保留提供商默认值和其他设置。保存无关设置或发现模型不会把自动值固化为手动覆盖。同名模型在不同提供商下独立设置。自定义数值若恰好等于固定档，保存或重新加载后会显示对应固定档。
+
+使用原生目录 `modelOverrides` 的提供商在同步时保留目录配置。模型发现和失效清理只更新插件快照，不会生成不兼容的显式 `models` 列表，也不会删除原生覆盖。
+
+原生表单的自动容量变化后，过期草稿会被拒绝，刷新表单再保存即可。预设控件会在其他模型保存后保留草稿并续用新版本；同一模型发生变化时，先核对当前值，再点击「保留草稿继续编辑」后重新保存。
+
+修改对下一次准备的调用生效，已准备的调用继续使用原有容量。模型信息、推理模型、溢出判断和原生上下文压缩采用同一有效窗口；最大输出词元设置与 DSH 原生压缩策略保持独立。扩大本地窗口不会提高网关实际接受的上限。
+
 思考预设只投影到原生界面，不写入原生模型配置。关闭 GPT 自动适配后恢复原生值和参数结构。速度选择按会话持久化。同步失败保留旧快照，失效模型保留到主动清理。
 
 GPT 模型快照与速度选择保存在 `$DSH_HOME/storages/gpt-adapter`。Codex 源文件和导入的 MCP 凭证不会复制到该位置。正常会话记录和日志由 DSH 宿主管理。

package/dist/src/client/context-window.d.ts

@@ -0,0 +1,9 @@
+import { type ContextWindowResolution } from '../context-window.js';
+export declare function ContextWindowControl({ provider, modelId, value, revision, busy, save, }: {
+    provider: string;
+    modelId: string;
+    value: ContextWindowResolution;
+    revision: number;
+    busy: boolean;
+    save(args: Record<string, unknown>): Promise<boolean | undefined>;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/src/codex-config.d.ts

@@ -8,6 +8,7 @@ export type CompatibilityItem = {
 export type CodexMcpConfig = {
     serverName: string;
     source: string;
+    originalName?: string;
     transport: 'stdio' | 'streamable-http';
     command?: string;
     args?: string[];
@@ -47,7 +48,7 @@ export declare function projectText(path: string, fs?: ProjectFileSystem, signal
 /** Repository root to cwd; without a repository only cwd participates. */
 export declare function projectDirectories(cwd: string, fs?: ProjectFileSystem, signal?: AbortSignal): Promise<string[]>;
 export declare function readCodexConfig(home: string, cwd?: string, fs?: ProjectFileSystem, signal?: AbortSignal): Promise<JsonObject>;
-export declare function normalizeCodexMcp(name: string, value: unknown, source: string, base: string, environment?: NodeJS.ProcessEnv): CodexMcpConfig | undefined;
+export declare function normalizeCodexMcp(name: string, value: unknown, source: string, base: string, environment?: NodeJS.ProcessEnv, defaultCwd?: string): CodexMcpConfig | undefined;
 export declare function discoverCodexSnapshot(home: string, options: {
     importPluginResources: boolean;
     mcpAllowlist: string[];

package/dist/src/codex-mcp-metadata.d.ts

@@ -0,0 +1,12 @@
+export type CodexTurnMetadata = {
+    session_id: string;
+    turn_id: string;
+};
+/**
+ * DSH 0.2.2-rc.1 has no per-call MCP metadata hook. Scope the SDK seam to
+ * imported tool executions so its native lifecycle and result handling remain intact.
+ */
+export declare function installCodexMcpMetadata(): {
+    run<T>(metadata: CodexTurnMetadata | undefined, operation: () => T): T;
+    dispose(): void;
+};

package/dist/src/context-window.d.ts

@@ -0,0 +1,25 @@
+export type ContextWindowMode = 'default' | '516k' | '1m' | 'custom';
+export type ContextWindowSource = 'legacy-override' | 'native-user' | 'provider-default' | 'upstream' | 'capability-catalog' | 'official-preset' | 'native-default';
+export type ContextWindowResolution = {
+    mode: ContextWindowMode;
+    effectiveTokens: number;
+    defaultTokens: number;
+    source: ContextWindowSource;
+};
+export declare const OFFICIAL_CONTEXT_WINDOWS: Record<string, {
+    tokens: number;
+    url: string;
+    verifiedAt: string;
+}>;
+export declare function validContextWindow(value: unknown): value is number;
+export declare function contextWindowMode(tokens: number): ContextWindowMode;
+export declare function contextWindowTokens(mode: ContextWindowMode, customTokens?: number): number | undefined;
+export declare function resolveContextWindow(options: {
+    modelId: string;
+    legacy?: unknown;
+    native?: unknown;
+    providerDefault?: unknown;
+    upstream?: unknown;
+    catalog?: unknown;
+    nativeDefault?: unknown;
+}): ContextWindowResolution;

package/dist/src/host.d.ts

@@ -2,6 +2,8 @@ import { Service, type Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { bindTypertRemote } from '@deepseek-ai/dsh-typert-protocol';
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import { type ContextWindowMode, type ContextWindowResolution } from './context-window.js';
+import { type ContextWindowEdit, type ContextWindowWriter } from './settings-overlay.js';
 import { type CodexCompatibilityConfig, type CodexCompatibilityRuntime } from './codex.js';
 import type { ModelCapabilities, ServiceTier } from './types.js';
 type RouteOptions = {
@@ -51,6 +53,7 @@ export declare class GptModels extends Service {
     private readonly options;
     private readonly settingsNs;
     codex?: CodexCompatibilityRuntime;
+    contextWriter: ContextWindowWriter | undefined;
     readonly typertRemote: ReturnType<typeof bindTypertRemote>;
     private readonly runners;
     private readonly snapshots;
@@ -85,12 +88,24 @@ export declare class GptModels extends Service {
         capabilities: {
             [x: string]: ModelCapabilities;
         };
+        contextWindows: {
+            [k: string]: ContextWindowResolution;
+        };
+        contextRevision: number;
         options: RouteOptions;
     };
     configure(provider: string, enabled: boolean): Promise<void>;
     updateOptions(provider: string, refreshIntervalMs: number, capabilityCatalogUrl: string, overridesJSON: string): Promise<void>;
     refresh(provider: string): Promise<void>;
     removeStale(provider: string): Promise<void>;
+    /** Resolve raw metadata separately from merged capabilities and cached overrides. */
+    contextWindow(provider: string, modelId: string, nativeDefault?: number): ContextWindowResolution;
+    contextWriteRevision(): number | undefined;
+    /** Public form revisions also cover changes to projected model capacities. */
+    private modelsRevision;
+    /** Remove only legacy context fields after the matching native save commits. */
+    clearLegacyContext(edits: ContextWindowEdit[], expected?: number): Promise<void>;
+    setContextWindow(provider: string, modelId: string, mode: ContextWindowMode, customTokens?: number, expectedRevision?: number): Promise<void>;
     setSpeed(sessionId: SessionId, provider: string, modelId: string, tier: ServiceTier): Promise<void>;
     speed(sessionId: SessionId, provider: string, modelId: string): {
         selected: ServiceTier;

package/dist/src/settings-overlay.d.ts

@@ -5,9 +5,21 @@ type SettingsLike = {
     write?: (ns: string, change: (current: any, base: any, schema: any) => any, expected?: number, paths?: string[][]) => Promise<void>;
 };
 export type CapabilityResolver = (provider: string, model: JsonObject, profile?: JsonObject) => ModelCapabilities | undefined;
-export declare function projectModel(provider: string, model: JsonObject, resolve: CapabilityResolver, profile?: JsonObject): JsonObject;
+export type ContextWindowEdit = {
+    provider: string;
+    modelId: string;
+    previousTokens: number | undefined;
+};
+type ContextWrites = {
+    revision(): number | undefined;
+    saved(edits: ContextWindowEdit[], revision: number | undefined): Promise<void>;
+};
+export type ContextWindowWriter = (provider: string, modelId: string, tokens: number | undefined, expected?: number) => Promise<void>;
+export declare function projectModel(provider: string, model: JsonObject, resolve: CapabilityResolver, profile?: JsonObject, includeContext?: boolean): JsonObject;
 /** A view of native configuration; the original object and its stored fields stay intact. */
 export declare function projectConfiguration(value: JsonObject | undefined, resolve: CapabilityResolver): JsonObject | undefined;
 /** Dispose returns the native settings page to its original schema and values. */
-export declare function installSettingsOverlay(settings: SettingsLike, resolve: CapabilityResolver): () => void;
+export declare function installSettingsOverlay(settings: SettingsLike, resolve: CapabilityResolver, contextWrites?: ContextWrites): (() => void) & {
+    setContextWindow: ContextWindowWriter;
+};
 export {};