A local-first multi-agent app development platform, built on PenguinHarness
feat(core,web,server,cli,skills,docs): refresh model catalog for AgentHub 0.4.2 (#325)
Yaowei Zhengb8b9bf541d38
diff --git a/changelog/unreleased/2026-08-18-model-catalog-refresh.md b/changelog/unreleased/2026-08-18-model-catalog-refresh.mdnew file mode 100644index 00000000..c3c768ba--- /dev/null+++ b/changelog/unreleased/2026-08-18-model-catalog-refresh.md@@ -0,0 +1,51 @@+# Model catalog refresh for AgentHub 0.4.2++- **Date:** 2026-08-18+- **Type:** feature+- **Scope:** `model-catalog`, `core`, `web`, `cli`, `skills`+- **PR:** [#325](https://github.com/Prism-Shadow/penguin-harness/pull/325)+- **Issue:** [#313](https://github.com/Prism-Shadow/penguin-harness/issues/313)++[中文版](2026-08-18-model-catalog-refresh.zh.md)++The built-in model catalog was refreshed against the AgentHub 0.4.2 line-up: Gemini 3.7, GLM-5.3 and the GPT-5.6 generation joined the direct provider groups along with their OpenRouter counterparts, a delisted free row was dropped, the DeepSeek rows were re-priced from the current official list, and the generic Chat Completions client type was renamed to `openai-chat`.++## New presets++- **Gemini 3.7** — `gemini-3.7-flash` in the direct Google group: 1,048,576-token context, vision, $0.15 / $1.50 / $7.50 per MTok (cache read / input / output), served by AgentHub 0.4.2's native `gemini-3.7` client. Google's launch discount halves those rates through 2026-12-31 and is not stored, following the catalog's convention of keeping direct rows on list price.+- **GLM-5.3** — the direct Z.AI group gained a 1,000,000-token, text-only row at Z.AI's published $0.26 / $1.40 / $4.40, the same rates as GLM-5.2, served by AgentHub 0.4.2's unified GLM client.+- **GPT-5.6** — the direct OpenAI group gained `gpt-5.6` (the bare id routes to the sol tier upstream and is priced as that tier), `gpt-5.6-terra` and `gpt-5.6-luna`, all 1,050,000-token context with vision, at $0.50 / $5 / $30, $0.20 / $2 / $12 and $0.02 / $0.20 / $1.20, served by the native `gpt-5.6` client.+- **OpenRouter counterparts** — `google/gemini-3.7-flash` at the discounted rates the gateway actually bills ($0.0375 / $0.375 / $1.875), `z-ai/glm-5.3` ($0.26 / $1.40 / $4.40, matching the direct row to the cent, as the gateway runs no discount on it), `x-ai/grok-4.6` ($0.50 / $2 / $6, 500K context, vision) and `deepseek/deepseek-v4-pro-0813` ($0.022 / $0.66 / $1.98, text-only). The five missing OpenAI ids — `openai/gpt-5.5-pro`, `openai/gpt-5.4`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-nano` and `openai/gpt-5.4-pro` — were added, so every direct OpenAI model has an `openai/<id>` gateway row and vice versa; a new test pins that parity. All rates were re-read on 2026-08-18 from the model pages and the per-model endpoints API.++## Removals and re-pricing++- The `inclusionai/ling-3.0-flash:free` OpenRouter preset was removed after the model was delisted upstream, and the free-model docs list dropped it.+- The direct DeepSeek group was re-priced from the updated official list at https://api-docs.deepseek.com/quick_start/pricing/, storing the off-peak tier — the lower published price: `deepseek-v4-flash` at ¥0.05 / ¥1.5 / ¥4.5 and `deepseek-v4-pro` at ¥0.15 / ¥4.5 / ¥13.5 per MTok (cache hit / input / output). Peak hours, Beijing 09:00–12:00 and 14:00–18:00, bill double.+- The stale OpenRouter DeepSeek rows were re-read the same day: `deepseek/deepseek-v4-flash` $0.0168 / $0.0679 / $0.168, `deepseek/deepseek-v4-flash-0731` $0.0157 / $0.0786 / $0.1572 and `deepseek/deepseek-v4-pro` $0.022 / $0.66 / $1.98.+- Three OpenRouter GPT-5.6 rows that had drifted by 2x were corrected on that re-read: `openai/gpt-5.6-luna` ($0.02 / $0.25 / $1.20) and `openai/gpt-5.6-terra` ($0.20 / $2.50 / $12) were still storing a promotion that has since lapsed, and `openai/gpt-5.6-sol` ($0.25 / $3.125 / $15) moved onto one. Gateway rows record what OpenRouter bills rather than the vendor's list price, so each discounted row now names the rate to restore when its promotion ends.++## OpenRouter's OpenAI rows on the Responses protocol++The nine `openai/*` OpenRouter presets pin `client_type: "openai-responses"` in place of `openai-chat`, so their requests go to `{base}/responses` and reasoning items are round-tripped rather than flattened. OpenRouter serves the Responses API at the same `https://openrouter.ai/api/v1` base URL those presets already carry, and AgentHub 0.4.2's `openai-responses` client speaks it.++The pin is limited to the OpenAI family. The Responses client leans on OpenAI-specific reasoning-item semantics — replaying `encrypted_content` / `signature` / `summary` and the assistant `phase` — so every non-OpenAI OpenRouter row (Anthropic, Google, DeepSeek, xAI, Z.AI, Moonshot, MiniMax, Qwen, the `:free` rows and the Free Models Router) stayed on Chat Completions, as did the four other gateways, which carry no OpenAI ids. Both protocols read the same `OPENAI_API_KEY` / `OPENAI_BASE_URL`, so credential handling and the env-var fallback were left unchanged; the Web base-URL hint shows `/responses` for these rows.++A new test pins the related invariant that every gateway row carries an explicit `client_type`. AgentHub's router matches raw substrings against `client_type || model_id` and never inspects `base_url`, so an unpinned gateway id would be routed by its own spelling: `openai/gpt-5.6-sol` would reach the first-party GPT-5.6 client pointed at a gateway, and the dotted `anthropic/claude-opus-4.8` would throw outright.++## `openai-chat` client type++AgentHub 0.4.2 renamed the generic Chat Completions client to `openai-chat`, keeping bare `openai` as a deprecated alias. The harness converged on the canonical name end to end:++- Every gateway preset — OpenRouter, Fireworks AI, SiliconFlow, Qwen Token Plan and Qwen Pay-As-You-Go — pins `client_type: "openai-chat"`, apart from the OpenRouter `openai/*` rows above. The CLI `model add` group default and the Web add-model dialog emit `openai-chat` as well.+- The Web protocol-path hint learned AgentHub 0.4.2's generic protocol clients: `openai-responses` maps to `/responses` and `ant-messages` to `/v1/messages`, both previously mis-hinted, and `resolveModelEnv` resolves their env fallbacks (`OPENAI_*` / `ANTHROPIC_*`) as well as the GPT-5.6 generation.++## Compatibility++The rename does not break stored configuration. A new core helper, `canonicalClientType`, normalizes the `openai` spelling on read — core config load, and the server's model GET, PUT and test-model paths — and on write in core's `addModel`, so a pre-rename `.project_config.toml` loads and runs unchanged and picks up the canonical spelling the next time it is saved. Bare `openai` also remains a working alias upstream in AgentHub.++Removing the Ling preset leaves existing Projects alone as well: presets are copied into `.project_config.toml` at creation and nothing rewrites them, and "sync presets" appends and updates catalog-owned fields without deleting. A config already holding the row keeps its context window, pricing, vision flag, base URL and API key — all of which live in the config rather than the catalog — so only the catalog display name is lost, the row falls back to showing its upstream id, and it stays selectable, editable and valid as the default model. A regression test pins that.++## Docs and skill++- The `agenthub-models` skill (v12) synced its model-id table to the AgentHub 0.4.2 registry — Gemini 3.7, GLM-5.3, the GPT-5.4/5.5/5.6 gateway ids, `z-ai/glm-5.3`, MiniMax M3, Kimi K2.7 Code and the new DeepSeek and Claude gateway ids. Its routing section documents `openai-chat`, `openai-responses` and `ant-messages`, warns that gateway ids must always pass an explicit `clientType`, and documents `fast_mode` (UniConfig) with its per-client support matrix.+- The bilingual `models` and `configuration` docs pages moved their `client_type` examples and their gateway and local-endpoint guidance to `openai-chat` (with a note on the alias), named `openai-responses` and `ant-messages`, explained the OpenRouter `openai/*` Responses pin, and mentioned the new models and DeepSeek's off-peak pricing convention.diff --git a/changelog/unreleased/2026-08-18-model-catalog-refresh.zh.md b/changelog/unreleased/2026-08-18-model-catalog-refresh.zh.mdnew file mode 100644index 00000000..dba8fcc3--- /dev/null+++ b/changelog/unreleased/2026-08-18-model-catalog-refresh.zh.md@@ -0,0 +1,51 @@+# 面向 AgentHub 0.4.2 的模型目录刷新++- **Date:** 2026-08-18+- **Type:** feature+- **Scope:** `model-catalog`, `core`, `web`, `cli`, `skills`+- **PR:** [#325](https://github.com/Prism-Shadow/penguin-harness/pull/325)+- **Issue:** [#313](https://github.com/Prism-Shadow/penguin-harness/issues/313)++[English](2026-08-18-model-catalog-refresh.md)++内置模型目录按 AgentHub 0.4.2 的模型阵容做了一次刷新:Gemini 3.7、GLM-5.3 与 GPT-5.6 系列进入各直连 Provider 分组,其 OpenRouter 对应条目同步加入;下架的免费条目被移除;DeepSeek 各条目按最新官方价目表重新定价;通用的 Chat Completions 客户端类型改名为 `openai-chat`。++## 新增预设++- **Gemini 3.7**——直连 Google 分组新增 `gemini-3.7-flash`:1,048,576 Token 上下文,支持视觉,每百万 Token $0.15 / $1.50 / $7.50(缓存读取 / 输入 / 输出),由 AgentHub 0.4.2 原生的 `gemini-3.7` 客户端提供服务。Google 的上线折扣在 2026-12-31 之前将上述费率减半,这里不予记录,遵循目录中直连条目一律按标价记录的惯例。+- **GLM-5.3**——直连 Z.AI 分组新增一个 1,000,000 Token 上下文、纯文本的条目,采用 Z.AI 公布的 $0.26 / $1.40 / $4.40,与 GLM-5.2 同价,由 AgentHub 0.4.2 统一的 GLM 客户端提供服务。+- **GPT-5.6**——直连 OpenAI 分组新增 `gpt-5.6`(裸 id 在上游路由到 sol 档,价格也按该档记录)、`gpt-5.6-terra` 与 `gpt-5.6-luna`,三者均为 1,050,000 Token 上下文并支持视觉,费率分别为 $0.50 / $5 / $30、$0.20 / $2 / $12 和 $0.02 / $0.20 / $1.20,由原生的 `gpt-5.6` 客户端提供服务。+- **OpenRouter 对应条目**——`google/gemini-3.7-flash` 按网关实际计费的折后价记录($0.0375 / $0.375 / $1.875)、`z-ai/glm-5.3`($0.26 / $1.40 / $4.40,网关对它没有折扣,因此与直连条目分毫不差)、`x-ai/grok-4.6`($0.50 / $2 / $6,500K 上下文,支持视觉)以及 `deepseek/deepseek-v4-pro-0813`($0.022 / $0.66 / $1.98,纯文本)。此前缺失的五个 OpenAI id——`openai/gpt-5.5-pro`、`openai/gpt-5.4`、`openai/gpt-5.4-mini`、`openai/gpt-5.4-nano` 与 `openai/gpt-5.4-pro`——一并补齐,于是每个直连 OpenAI 模型都有对应的 `openai/<id>` 网关条目,反之亦然;新增的测试固定了这一对应关系。所有费率都于 2026-08-18 从模型页面与按模型的 endpoints API 重新读取。++## 移除与重新定价++- OpenRouter 预设 `inclusionai/ling-3.0-flash:free` 在上游下架后被移除,免费模型文档列表也随之删去该项。+- 直连 DeepSeek 分组按 https://api-docs.deepseek.com/quick_start/pricing/ 更新后的官方价目表重新定价,记录的是**非高峰档**(公布价格中较低的一档):`deepseek-v4-flash` 为每百万 Token ¥0.05 / ¥1.5 / ¥4.5,`deepseek-v4-pro` 为 ¥0.15 / ¥4.5 / ¥13.5(缓存命中 / 输入 / 输出)。高峰时段(北京时间 09:00–12:00 与 14:00–18:00)按双倍计费。+- 已经过期的 OpenRouter DeepSeek 条目在同一天重新读取:`deepseek/deepseek-v4-flash` $0.0168 / $0.0679 / $0.168,`deepseek/deepseek-v4-flash-0731` $0.0157 / $0.0786 / $0.1572,`deepseek/deepseek-v4-pro` $0.022 / $0.66 / $1.98。+- 这次重读同时修正了三个偏差达 2 倍的 OpenRouter GPT-5.6 条目:`openai/gpt-5.6-luna`($0.02 / $0.25 / $1.20)与 `openai/gpt-5.6-terra`($0.20 / $2.50 / $12)此前仍存着一个已经结束的促销价,而 `openai/gpt-5.6-sol`($0.25 / $3.125 / $15)则新进入促销。网关条目记录的是 OpenRouter 实际计费的价格而非厂商标价,因此处在促销中的条目都注明了促销结束后应恢复的费率。++## OpenRouter 的 OpenAI 条目改走 Responses 协议++九个 `openai/*` OpenRouter 预设不再使用 `openai-chat`,改为固定 `client_type: "openai-responses"`,于是请求发往 `{base}/responses`,推理条目也得以完整往返,而不会被摊平。OpenRouter 在这些预设本就携带的同一个 `https://openrouter.ai/api/v1` base URL 上提供 Responses API,AgentHub 0.4.2 的 `openai-responses` 客户端正好能讲这套协议。++这项固定只限于 OpenAI 系列。Responses 客户端依赖 OpenAI 特有的推理条目语义——回放 `encrypted_content` / `signature` / `summary` 以及 assistant 的 `phase`——因此所有非 OpenAI 的 OpenRouter 条目(Anthropic、Google、DeepSeek、xAI、Z.AI、Moonshot、MiniMax、Qwen、各 `:free` 条目以及 Free Models Router)继续走 Chat Completions,另外四个网关也一样,它们本就不含 OpenAI id。两种协议读取的都是同一组 `OPENAI_API_KEY` / `OPENAI_BASE_URL`,因此凭证处理与环境变量回退保持不变;Web 的 base URL 提示会对这些条目显示 `/responses`。++新增的测试还固定了一条相关不变式:每个网关条目都必须显式携带 `client_type`。AgentHub 的路由是拿原始子串去匹配 `client_type || model_id`,从不检查 `base_url`,所以未固定的网关 id 会按自己的拼写被路由:`openai/gpt-5.6-sol` 会落到指向网关的第一方 GPT-5.6 客户端上,而带点号的 `anthropic/claude-opus-4.8` 会直接抛错。++## `openai-chat` 客户端类型++AgentHub 0.4.2 把通用的 Chat Completions 客户端改名为 `openai-chat`,裸 `openai` 保留为已废弃的别名。Harness 端全链路统一到这个规范名称:++- 所有网关预设——OpenRouter、Fireworks AI、SiliconFlow、Qwen Token Plan 与 Qwen Pay-As-You-Go——都固定 `client_type: "openai-chat"`,上文那些 OpenRouter `openai/*` 条目除外。CLI `model add` 的分组默认值与 Web 添加模型对话框同样产出 `openai-chat`。+- Web 的协议路径提示学会了 AgentHub 0.4.2 的通用协议客户端:`openai-responses` 对应 `/responses`,`ant-messages` 对应 `/v1/messages`,此前这两者都提示错了;`resolveModelEnv` 也能解析它们的环境变量回退(`OPENAI_*` / `ANTHROPIC_*`)以及 GPT-5.6 系列。++## 兼容性++这次改名不会破坏已存储的配置。新增的 core 辅助函数 `canonicalClientType` 会在读取时(core 配置加载,以及服务端的模型 GET、PUT 与 test-model 路径)和写入时(core 的 `addModel`)把 `openai` 这一拼写规范化,因此改名之前的 `.project_config.toml` 照常加载、照常运行,并在下一次保存时自动换成规范拼写。裸 `openai` 在 AgentHub 上游也仍然是可用的别名。++移除 Ling 预设同样不影响既有 Project:预设是在创建时复制进 `.project_config.toml` 的,此后没有任何机制会改写它们,而「同步预设」只会追加并更新目录所有的字段,不会删除。已经存有该条目的配置会保留它的上下文窗口、价格、视觉标记、base URL 与 API key——这些本来就存在配置里而不在目录中——所以丢失的只是目录提供的展示名,该条目回退为显示其上游 id,依旧可以选中、编辑,也依旧可以作为有效的默认模型。回归测试固定了这一点。++## 文档与 Skill++- `agenthub-models` skill(v12)把 model id 表同步到 AgentHub 0.4.2 的注册表——Gemini 3.7、GLM-5.3、GPT-5.4/5.5/5.6 的网关 id、`z-ai/glm-5.3`、MiniMax M3、Kimi K2.7 Code,以及新增的 DeepSeek 与 Claude 网关 id。其路由章节记录了 `openai-chat`、`openai-responses` 与 `ant-messages`,提醒网关 id 必须始终显式传入 `clientType`,并补充了 `fast_mode`(UniConfig)及其按客户端的支持矩阵。+- 中英文 `models` 与 `configuration` 文档页把 `client_type` 示例以及网关、本地端点相关的说明改用 `openai-chat`(并注明别名),点出 `openai-responses` 与 `ant-messages`,解释了 OpenRouter `openai/*` 固定 Responses 的做法,并提到了新增模型与 DeepSeek 非高峰计价的口径。diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.tsindex 3e1f710c..2d5f976a 100644--- a/packages/cli/src/commands/config.ts+++ b/packages/cli/src/commands/config.ts@@ -17,8 +17,8 @@* **no string concatenation is ever performed**. `--provider` is **required** on every model* subcommand that names an entry: the group is never guessed, so `--api-key` can never land on* a vendor the user did not name. For `model add`, a new entry's client_type defaults according- * to the group's semantics (not set for first-party vendors; openai for custom / self-hosted- * groups / gateways, with the gateway's endpoint base URL pre-filled). For `model default`+ * to the group's semantics (not set for first-party vendors; openai-chat for custom /+ * self-hosted groups / gateways, with the gateway's endpoint base URL pre-filled). For `model default`* / `model vision`, core validation raises an error when the reference is not* found in models; `model remove` reports the same condition itself, since removal is* idempotent in core, and clears the default / vision pointers that named the removed entry.@@ -157,13 +157,14 @@ export function registerConfigCommand(program: Command, t: Messages): void {// client_type default rule, only injected for new entries (updating an// existing entry never overrides an explicit config): not set for first-party// vendor groups (AgentHub auto-routes by upstream id, with env fallback keyed on- // id); defaults to openai for custom / self-hosted / gateway groups, with the- // gateway's endpoint base URL pre-filled as well.+ // id); defaults to openai-chat for custom / self-hosted / gateway groups, with the+ // gateway's endpoint base URL pre-filled as well. (An explicit --client-type is+ // passed through; core's addModel normalizes the deprecated bare "openai" alias.)const pInfo = providerInfo(provider);const openAiDefault =pInfo === undefined || pInfo.id === "custom" || pInfo.gatewayBaseUrl !== undefined;const clientType: string | undefined =- opts.clientType ?? (!existed && openAiDefault ? "openai" : undefined);+ opts.clientType ?? (!existed && openAiDefault ? "openai-chat" : undefined);const baseUrl: string | undefined =opts.baseUrl ?? (!existed ? pInfo?.gatewayBaseUrl : undefined);// Only collect explicitly given price fields, letting addModel merge them with the existing pricing per-field.diff --git a/packages/cli/src/i18n.ts b/packages/cli/src/i18n.tsindex 3c5e2b6b..9fc6ff57 100644--- a/packages/cli/src/i18n.ts+++ b/packages/cli/src/i18n.ts@@ -328,7 +328,8 @@ const en: Messages = {addContextWindow: "Context window size (tokens)",addMaxTokens:"Per-model max output tokens (positive integer); when set it overrides the Agent's max_tokens, omit to inherit — lower it for small-context models",- addClientType: "AgentHub client type (e.g. openai); defaults by provider group when omitted",+ addClientType:+ "AgentHub client type (e.g. openai-chat); defaults by provider group when omitted",addVision: "Mark the model as supporting image input (vision)",addNoVision: "Mark the model as NOT supporting image input; omit both to keep current",addPriceCacheRead: "Price per 1M tokens: cache read (USD)",@@ -587,7 +588,7 @@ const zh: Messages = {addContextWindow: "上下文窗口大小(token 数)",addMaxTokens:"该模型的最大输出长度(正整数);设置后覆盖 Agent 的 max_tokens,缺省沿用——小上下文模型建议调低",- addClientType: "AgentHub 客户端协议(如 openai);缺省按 provider 分组的语义取值",+ addClientType: "AgentHub 客户端协议(如 openai-chat);缺省按 provider 分组的语义取值",addVision: "标注该模型支持图片输入(视觉)",addNoVision: "标注该模型不支持图片输入;两者都不给则保留原值",addPriceCacheRead: "每百万 token 价格:缓存读取(USD)",diff --git a/packages/cli/test/config-model.test.ts b/packages/cli/test/config-model.test.tsindex 6cd97b74..6967173e 100644--- a/packages/cli/test/config-model.test.ts+++ b/packages/cli/test/config-model.test.ts@@ -175,7 +175,7 @@ describe("penguin config model add/list (--root plus provider / model_id storedexpect(list.out.split("\n").some((l) => /anthropic\s+claude-sonnet-4-6/.test(l))).toBe(true);});- it("client_type defaults by grouping semantics (PRN-021): custom / self-hosted / gateway get openai, first-party providers get none", async () => {+ it("client_type defaults by grouping semantics (PRN-021): custom / self-hosted / gateway get openai-chat, first-party providers get none", async () => {// The custom group and self-hosted groups (--provider not a catalog value): default to client_type=openai.await runModel(["add",@@ -197,7 +197,7 @@ describe("penguin config model add/list (--root plus provider / model_id stored"--root",tmpRoot,]);- // Gateway group: openai + the gateway's endpoint base URL pre-filled.+ // Gateway group: openai-chat + the gateway's endpoint base URL pre-filled.await runModel(["add","--model-id",@@ -225,10 +225,10 @@ describe("penguin config model add/list (--root plus provider / model_id stored) as { models: Array<Record<string, unknown>> };const by = (p: string, id: string) =>parsed.models.find((m) => m.provider === p && m.model_id === id)!;- expect(by("custom", "my-openai-proxy").client_type).toBe("openai");- expect(by("mylab", "in-house-1").client_type).toBe("openai");+ expect(by("custom", "my-openai-proxy").client_type).toBe("openai-chat");+ expect(by("mylab", "in-house-1").client_type).toBe("openai-chat");expect(by("deepseek", "my-fine-tune").client_type).toBeUndefined();- expect(by("openrouter", "acme/some-model").client_type).toBe("openai");+ expect(by("openrouter", "acme/some-model").client_type).toBe("openai-chat");expect(by("openrouter", "acme/some-model").base_url).toBe("https://openrouter.ai/api/v1");expect(by("mylab", "special-1").client_type).toBe("verbatim-type");});diff --git a/packages/core/src/interfaces.ts b/packages/core/src/interfaces.tsindex f83a117b..0f9c7291 100644--- a/packages/core/src/interfaces.ts+++ b/packages/core/src/interfaces.ts@@ -112,9 +112,10 @@ export interface GenerativeModelConfig {apiKey?: string;baseUrl?: string;/**- * AgentHub client protocol (`openai` / `claude-4-8` / `deepseek-v4` / …). If omitted, AgentHub- * infers it from `modelId`; custom-named models or third-party models using the OpenAI protocol- * must specify it explicitly.+ * AgentHub client protocol (`openai-chat` / `openai-responses` / `claude-4-8` /+ * `deepseek-v4` / …; the bare `openai` spelling is a deprecated alias of `openai-chat`). If+ * omitted, AgentHub infers it from `modelId`; custom-named models or third-party models+ * using an OpenAI protocol must specify it explicitly.*/clientType?: string;tools: ToolDefinition[];diff --git a/packages/core/src/llm/generative-model.ts b/packages/core/src/llm/generative-model.tsindex c2f4d40c..acf7e269 100644--- a/packages/core/src/llm/generative-model.ts+++ b/packages/core/src/llm/generative-model.ts@@ -1023,9 +1023,10 @@ export class GenerativeModel implements LLMInterface {constructor(config: GenerativeModelConfig) {// Omit apiKey / baseUrl when undefined, letting AgentHub read them from environment- // variables. clientType determines which protocol to speak (`openai` means OpenAI Chat- // Completions compatible); when omitted, AgentHub infers it from model_id, so it only needs- // to be specified explicitly for custom-named models.+ // variables. clientType determines which protocol to speak (`openai-chat` means OpenAI+ // Chat Completions compatible; the bare `openai` spelling is a deprecated upstream alias);+ // when omitted, AgentHub infers it from model_id, so it only needs to be specified+ // explicitly for custom-named models.this.client = new AutoLLMClient({model: config.modelId,...(config.apiKey !== undefined ? { apiKey: config.apiKey } : {}),diff --git a/packages/core/src/state/model-catalog.ts b/packages/core/src/state/model-catalog.tsindex 4de665cb..b65582e0 100644--- a/packages/core/src/state/model-catalog.ts+++ b/packages/core/src/state/model-catalog.ts@@ -1,7 +1,9 @@/*** Built-in model catalog (single source of truth): official chat models that AgentHub can* auto-route, shared by core's default config, server's initial config, and web/cli display.- * Data verified as of 2026-07-10 (Qwen Token Plan entries: 2026-07-20; MiniMax: 2026-08-03, per each provider's docs).+ * Data verified as of 2026-07-10 (Qwen Token Plan entries: 2026-07-20; MiniMax: 2026-08-03;+ * DeepSeek, Gemini 3.7, GLM-5.3 and the whole OpenAI line-up (direct + OpenRouter):+ * 2026-08-18, per each provider's docs).* Docs: packages/docs/content/models.{zh,en}.md (site path /docs/models) documents the* provider groups and credential resolution described here.*@@ -18,12 +20,24 @@* Scope: excludes deepseek-chat / deepseek-reasoner legacy aliases that AgentHub cannot* auto-route (deprecated 2026-07-24), glm-5v-turbo (image input unsupported by AgentHub's GLM* client), the OpenRouter z-ai/glm-5.1 and SiliconFlow Pro/zai-org/GLM-5.1 gateway listings- * (delisted 2026-08-06; the Z.AI direct glm-5.1 remains), non-chat models (embedding / image- * generation / TTS), and Bedrock. Direct-vendor ids are auto-routed by AgentHub and leave- * client_type unset; the five gateway groups (OpenRouter, Fireworks AI, SiliconFlow, Qwen- * Token Plan, Qwen Pay-As-You-Go) can't be auto-routed, so they set `client_type: "openai"`- * and inline their preset base URL. The MiniMax M3 preset pins AgentHub's first-party- * `minimax-m3` protocol and direct API endpoint.+ * (delisted 2026-08-06; the Z.AI direct glm-5.1 remains), the OpenRouter+ * inclusionai/ling-3.0-flash:free listing (delisted from OpenRouter, removed 2026-08-18),+ * non-chat models (embedding / image generation / TTS), and Bedrock. Direct-vendor ids are+ * auto-routed by AgentHub and leave client_type unset; the five gateway groups (OpenRouter,+ * Fireworks AI, SiliconFlow, Qwen Token Plan, Qwen Pay-As-You-Go) can't be auto-routed, so+ * every gateway row **always pins an explicit client_type** and inlines its preset base URL.+ * That pin is load-bearing, not decoration: AgentHub's AutoLLMClient matches raw substrings+ * against `client_type || model_id` and never looks at base_url, so an unpinned gateway id+ * would be routed by its own spelling — `openai/gpt-5.6-sol` would reach the first-party+ * GPT-5.6 client aimed at a gateway, and `anthropic/claude-opus-4.8` would throw outright+ * (dotted "4.8" matches neither "4-8" nor "-5"). Two protocols are pinned:+ * - `openai-chat` for most rows (AgentHub 0.4.2's canonical name for the generic Chat+ * Completions client — the bare "openai" spelling is a deprecated upstream alias, see+ * canonicalClientType);+ * - `openai-responses` for the OpenRouter `openai/*` rows, whose upstream really is an+ * OpenAI Responses server (see the OpenRouter block comment for why only those rows).+ * The MiniMax M3 preset pins AgentHub's first-party `minimax-m3` protocol and direct API+ * endpoint.** This file imports no Node built-ins (type-only imports only), so it can be bundled directly* for the browser.@@ -92,10 +106,12 @@ export const MODEL_PROVIDERS: ModelProviderInfo[] = [apiKeyUrl: "https://platform.deepseek.com/api_keys",modelsUrl: "https://api-docs.deepseek.com/quick_start/pricing",},- // Gateways (their model ids can't be auto-routed by AgentHub, so they always use- // client_type=openai + a preset base URL): they go through AgentHub's OpenAI client, so when- // credential is blank the SDK reads **OPENAI_API_KEY / OPENAI_BASE_URL** (not the provider's- // own var names) - the env fallback hint must reflect that accurately.+ // Gateways (their model ids can't be auto-routed by AgentHub, so they always pin an+ // explicit client_type + a preset base URL): they go through one of AgentHub's generic+ // OpenAI-protocol clients - openai-chat (Chat Completions) for most rows, openai-responses+ // for the OpenRouter openai/* rows - and *both* read **OPENAI_API_KEY / OPENAI_BASE_URL**+ // when the credential is blank (not the provider's own var names), so the env fallback hint+ // is the same either way and must reflect that accurately.{id: "openrouter",label: "OpenRouter",@@ -217,13 +233,18 @@ function usd(cacheRead: number, cacheWrite: number, output: number): ModelPricin* order is precomputed by hand right here — no runtime sorting anywhere.*/export const MODEL_CATALOG: ModelCatalogEntry[] = [- // -- DeepSeek (official CNY pricing: cache hit / cache miss / output) --+ // -- DeepSeek (official CNY pricing: cache hit / cache miss / output). Re-read 2026-08-18+ // from api-docs.deepseek.com/quick_start/pricing after the official price increase+ // introduced time-based tiers: the rows store the OFF-PEAK tier (the lower published+ // price, issue #313's display choice); peak hours (Beijing 9:00-12:00 and 14:00-18:00)+ // bill exactly double every bucket, so peak usage is underestimated 2x (same single-rate+ // limitation as the long-context surcharges in the file header). --{modelId: "deepseek-v4-flash",displayName: "DeepSeek V4 Flash",provider: "deepseek",contextWindow: 1000000,- pricing: cny(0.02, 1, 2),+ pricing: cny(0.05, 1.5, 4.5),supportsVision: false,},{@@ -231,20 +252,42 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [displayName: "DeepSeek V4 Pro",provider: "deepseek",contextWindow: 1000000,- pricing: cny(0.025, 3, 6),+ pricing: cny(0.15, 4.5, 13.5),supportsVision: false,},// -- OpenRouter (gateway: OpenAI-compatible protocol, preset base URL). Prices re-read in// one pass on 2026-08-07 from the models API (/api/v1/models; the API is authoritative- // where a model's web page disagrees): cache_read stores the published input_cache_read- // (falling back to the input price for the few rows without one — the :free rows); cache_write stores+ // where a model's web page disagrees); the DeepSeek rows, the rows added on 2026-08-18+ // (gemini-3.7-flash, grok-4.6, deepseek-v4-pro-0813, glm-5.3, the openai/* additions) and+ // every pre-existing openai/* and google/* row were re-read on 2026-08-18 from the model+ // pages and the per-model endpoints API.+ //+ // Protocol: rows pin `openai-chat` except the `openai/*` rows, which pin+ // `openai-responses` - OpenRouter serves the Responses API at {base}/responses (the same+ // https://openrouter.ai/api/v1 base URL these rows already carry), and AgentHub 0.4.2+ // verified that pairing live. The switch is deliberately limited to the OpenAI family:+ // OpenRouter will translate /responses for any upstream, but the Responses client leans on+ // OpenAI-specific reasoning-item round-tripping (replaying encrypted_content / signature /+ // summary and the assistant `phase`), which is only guaranteed when the upstream is+ // genuinely OpenAI. Non-OpenAI rows therefore stay on Chat Completions.+ //+ // Price buckets: cache_read stores the published input_cache_read+ // (falling back to the input price for the rows without one — the :free rows and the+ // GPT Pro tiers, which publish no cache discount); cache_write stores// input_cache_write only when it is a genuine per-token write premium (the Anthropic, GPT// and qwen3.8-max rows, 1.25x input) —// Gemini's field is an hourly cache-STORAGE rate, not a per-token price, so those rows// keep the input price — and otherwise also carries the input price. The :free tier and// the openrouter/free Free Models Router store a genuine $0 price (not "unknown"), so// costs correctly compute to 0. GPT models are uniformly vision-capable (OpenAI- // product-line policy) even where the gateway page omits the modality. --+ // product-line policy) even where the gateway page omits the modality.+ //+ // Discounts: these rows store what OpenRouter actually BILLS, so an active promotion is+ // stored at its discounted rate (unlike the direct-vendor rows, which keep the list price).+ // The endpoints API exposes the running promotion as `pricing.discount` on the default+ // endpoint; rows sitting on one say so and name the rate to restore, because a lapsed+ // promotion silently doubles the real cost — that is exactly how the gpt-5.6-terra and+ // gpt-5.6-luna rows drifted 2x low before the 2026-08-18 re-read. --{modelId: "anthropic/claude-fable-5",displayName: "Claude Fable 5",@@ -252,7 +295,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(1, 12.5, 50),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -262,7 +305,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.5, 6.25, 25),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -272,7 +315,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.5, 6.25, 25),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -282,7 +325,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.5, 6.25, 25),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -292,7 +335,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.2, 2.5, 10),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -300,9 +343,9 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [displayName: "DeepSeek V4 Flash 0731",provider: "openrouter",contextWindow: 1000000,- pricing: usd(0.018, 0.09, 0.18),+ pricing: usd(0.0157192, 0.078596, 0.157192),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -310,9 +353,22 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [displayName: "DeepSeek V4 Flash",provider: "openrouter",contextWindow: 1000000,- pricing: usd(0.01764, 0.0882, 0.1764),+ pricing: usd(0.0168, 0.0679, 0.168),+ supportsVision: false,+ clientType: "openai-chat",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ // The 0813 general-availability release of DeepSeek V4 Pro (OpenRouter listing dated+ // 2026-08-12); the default routed endpoint is DeepSeek's own API, so the price matches+ // the official USD list, and the context window is the default endpoint's 1,048,576.+ modelId: "deepseek/deepseek-v4-pro-0813",+ displayName: "DeepSeek V4 Pro 0813",+ provider: "openrouter",+ contextWindow: 1048576,+ pricing: usd(0.022, 0.66, 1.98),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -320,9 +376,25 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [displayName: "DeepSeek V4 Pro",provider: "openrouter",contextWindow: 1000000,- pricing: usd(0.003625, 0.435, 0.87),+ pricing: usd(0.022, 0.66, 1.98),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ // Same Gemini cache conventions as the gemini-3.6-flash row below. The stored rates are+ // what OpenRouter currently bills: the default Google endpoint runs `discount: 0.75` off+ // the $0.15/$1.50/$7.50 list price (Google's launch discount through 2026-12-31, which+ // OpenRouter deepens further), so it bills $0.0375/$0.375/$1.875 — re-read when the+ // discount ends, and restore the $0.15/$1.50/$7.50 list then (the direct-vendor row+ // stores that list price already).+ modelId: "google/gemini-3.7-flash",+ displayName: "Gemini 3.7 Flash",+ provider: "openrouter",+ contextWindow: 1048576,+ pricing: usd(0.0375, 0.375, 1.875),+ supportsVision: true,+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -336,7 +408,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: usd(0.15, 1.5, 7.5),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -346,7 +418,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: usd(0.15, 1.5, 9),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -358,20 +430,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: usd(0.03, 0.3, 2.5),supportsVision: true,- clientType: "openai",- baseUrl: OPENROUTER_BASE_URL,- },- {- // inclusionAI's free tier of Ling-3.0-flash (released 2026-07-23): 124B-param MoE with- // ~5.1B active params per token, text-only; context and $0 pricing per the OpenRouter- // models API (2026-07-24).- modelId: "inclusionai/ling-3.0-flash:free",- displayName: "Ling 3.0 Flash (free)",- provider: "openrouter",- contextWindow: 262144,- pricing: usd(0, 0, 0),- supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -382,7 +441,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: usd(0.06, 0.3, 1.2),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -392,7 +451,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.3, 3, 15),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -402,7 +461,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: usd(0.0992, 0.589, 2.48),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -412,50 +471,109 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0, 0, 0),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},+ // The openai/* rows below mirror the direct OpenAI group one-for-one, and are the only+ // gateway rows on the Responses protocol (see the block comment). Their context windows+ // are OpenRouter's published 1,050,000 / 400,000, matching the direct rows.{- // The page shows the $0.10/$0.60 rate under a "50% off" banner; the models API bills the- // same numbers (with real hit/write prices), so this row stores them — re-read when the- // promotion ends.+ // The 50% promotion this row used to store has ended: OpenRouter now bills the full+ // $0.20/$1.20 rate (endpoints API `discount: 0`), so the stored rates doubled on the+ // 2026-08-18 re-read.modelId: "openai/gpt-5.6-luna",displayName: "GPT-5.6 Luna",provider: "openrouter",- contextWindow: 1000000,- pricing: usd(0.01, 0.125, 0.6),+ contextWindow: 1050000,+ pricing: usd(0.02, 0.25, 1.2),supportsVision: true,- clientType: "openai",+ clientType: "openai-responses",baseUrl: OPENROUTER_BASE_URL,},{+ // Running a `discount: 0.5` promotion as of 2026-08-18, so OpenRouter bills half the+ // $0.50/$6.25/$30 list price — restore the list rates when the promotion ends.modelId: "openai/gpt-5.6-sol",displayName: "GPT-5.6 Sol",provider: "openrouter",- contextWindow: 1000000,- pricing: usd(0.5, 6.25, 30),+ contextWindow: 1050000,+ pricing: usd(0.25, 3.125, 15),supportsVision: true,- clientType: "openai",+ clientType: "openai-responses",baseUrl: OPENROUTER_BASE_URL,},{+ // Same lapsed promotion as the luna row: now billed at the full $2/$12 rate.modelId: "openai/gpt-5.6-terra",displayName: "GPT-5.6 Terra",provider: "openrouter",- contextWindow: 1000000,- pricing: usd(0.1, 1.25, 6),+ contextWindow: 1050000,+ pricing: usd(0.2, 2.5, 12),supportsVision: true,- clientType: "openai",+ clientType: "openai-responses",baseUrl: OPENROUTER_BASE_URL,},{modelId: "openai/gpt-5.5",displayName: "GPT-5.5",provider: "openrouter",- contextWindow: 1000000,+ contextWindow: 1050000,pricing: usd(0.5, 5, 30),supportsVision: true,- clientType: "openai",+ clientType: "openai-responses",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ // No published cache discount (the Pro tiers bill cached input at the standard rate), so+ // cache_read carries the input price — same convention as the direct gpt-5.5-pro row.+ modelId: "openai/gpt-5.5-pro",+ displayName: "GPT-5.5 Pro",+ provider: "openrouter",+ contextWindow: 1050000,+ pricing: usd(30, 30, 180),+ supportsVision: true,+ clientType: "openai-responses",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ modelId: "openai/gpt-5.4",+ displayName: "GPT-5.4",+ provider: "openrouter",+ contextWindow: 1050000,+ pricing: usd(0.25, 2.5, 15),+ supportsVision: true,+ clientType: "openai-responses",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ modelId: "openai/gpt-5.4-mini",+ displayName: "GPT-5.4 mini",+ provider: "openrouter",+ contextWindow: 400000,+ pricing: usd(0.075, 0.75, 4.5),+ supportsVision: true,+ clientType: "openai-responses",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ modelId: "openai/gpt-5.4-nano",+ displayName: "GPT-5.4 nano",+ provider: "openrouter",+ contextWindow: 400000,+ pricing: usd(0.02, 0.2, 1.25),+ supportsVision: true,+ clientType: "openai-responses",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ // No published cache discount, as with gpt-5.5-pro above.+ modelId: "openai/gpt-5.4-pro",+ displayName: "GPT-5.4 Pro",+ provider: "openrouter",+ contextWindow: 1050000,+ pricing: usd(30, 30, 180),+ supportsVision: true,+ clientType: "openai-responses",baseUrl: OPENROUTER_BASE_URL,},{@@ -472,7 +590,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 128000,pricing: usd(0, 0, 0),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -482,7 +600,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.25, 2.5, 6),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -492,7 +610,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: usd(0.05, 0.14, 1),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -503,7 +621,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 256000,pricing: usd(0.04, 0.2, 1.15),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -513,7 +631,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: usd(0.033, 0.132, 0.528),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -526,7 +644,19 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.17, 1, 4.05),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ // xAI's Grok 4.6 (OpenRouter listing dated 2026-08-12): same $2/$6 input/output rates as+ // Grok 4.5 with a raised $0.50 cache-hit price.+ modelId: "x-ai/grok-4.6",+ displayName: "Grok 4.6",+ provider: "openrouter",+ contextWindow: 500000,+ pricing: usd(0.5, 2, 6),+ supportsVision: true,+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -536,7 +666,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 500000,pricing: usd(0.3, 2, 6),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -546,7 +676,20 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: usd(0.0028, 0.14, 0.28),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",+ baseUrl: OPENROUTER_BASE_URL,+ },+ {+ // The gateway listing of the direct glm-5.3 row below; OpenRouter's single Z.AI endpoint+ // passes Z.AI's published price straight through (no discount), which is why the two+ // rows agree to the cent. Text-only, per the listing's modalities.+ modelId: "z-ai/glm-5.3",+ displayName: "GLM-5.3",+ provider: "openrouter",+ contextWindow: 1048576,+ pricing: usd(0.26, 1.4, 4.4),+ supportsVision: false,+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},{@@ -556,7 +699,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.1261, 0.679, 2.134),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: OPENROUTER_BASE_URL,},// -- Fireworks AI (gateway, standard serverless USD pricing: cached input / uncached@@ -569,7 +712,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.028, 0.14, 0.28),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -579,7 +722,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.03, 0.14, 0.28),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -589,7 +732,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.15, 1.74, 3.48),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -599,7 +742,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.14, 1.4, 4.4),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -611,7 +754,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.17, 1, 4.05),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -621,7 +764,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: usd(0.3, 3, 15),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -631,7 +774,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: usd(0.19, 0.95, 4),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},{@@ -641,7 +784,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 524288,pricing: usd(0.06, 0.3, 1.2),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: FIREWORKS_BASE_URL,},// -- SiliconFlow (gateway, official CNY pricing: cache hit / input / output) --@@ -652,7 +795,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.02, 1, 2),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},{@@ -662,7 +805,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.1, 12, 24),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},{@@ -672,7 +815,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.1, 5, 20),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},{@@ -682,7 +825,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: cny(1.3, 6.5, 27),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},// The Pro/ and Qwen/ entries below were unpriced until 2026-08-03 (SiliconFlow's price@@ -695,7 +838,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: cny(1.1, 6.5, 27),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},{@@ -706,7 +849,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 262144,pricing: cny(1.8, 1.8, 10.8),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},{@@ -716,7 +859,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(2, 8, 28),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: SILICONFLOW_BASE_URL,},// -- Qwen Token Plan (subscription gateway; vision flags per the plan's supported-model@@ -731,7 +874,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.2, 1, 2),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_TOKEN_PLAN_BASE_URL,},{@@ -741,7 +884,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(1, 12, 24),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_TOKEN_PLAN_BASE_URL,},{@@ -751,7 +894,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: cny(2, 8, 28),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_TOKEN_PLAN_BASE_URL,},{@@ -761,7 +904,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(1.5, 12, 36),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_TOKEN_PLAN_BASE_URL,},{@@ -771,7 +914,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.4, 2, 8),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_TOKEN_PLAN_BASE_URL,},// -- Qwen Pay-As-You-Go (DashScope's OpenAI-compatible pay-per-token marketplace; official@@ -785,7 +928,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.2, 1, 2),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_PAYG_BASE_URL,},{@@ -795,7 +938,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: cny(2, 20, 100),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_PAYG_BASE_URL,},{@@ -805,7 +948,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(1.5, 12, 36),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_PAYG_BASE_URL,},{@@ -815,7 +958,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1000000,pricing: cny(0.4, 2, 8),supportsVision: true,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_PAYG_BASE_URL,},{@@ -825,7 +968,7 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [contextWindow: 1048576,pricing: cny(2, 8, 28),supportsVision: false,- clientType: "openai",+ clientType: "openai-chat",baseUrl: QWEN_PAYG_BASE_URL,},// -- MiniMax (direct M3 Responses client; official USD pay-as-you-go list prices, standard@@ -841,6 +984,18 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [baseUrl: MINIMAX_BASE_URL,},// -- Google Gemini (official USD pricing) --+ {+ // Official list price, identical to gemini-3.6-flash (per AgentHub 0.4.2's registry and+ // Google's price page). Google halves all three rates as a launch discount through+ // 2026-12-31; like other limited-time promotions the discount is not stored (the+ // OpenRouter row bills — and stores — the halved rates instead).+ modelId: "gemini-3.7-flash",+ displayName: "Gemini 3.7 Flash",+ provider: "google",+ contextWindow: 1048576,+ pricing: usd(0.15, 1.5, 7.5),+ supportsVision: true,+ },{modelId: "gemini-3.6-flash",displayName: "Gemini 3.6 Flash",@@ -932,6 +1087,34 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [supportsVision: true,},// -- OpenAI (official USD pricing) --+ {+ // The bare gpt-5.6 id routes to gpt-5.6-sol upstream and is priced as that tier; served+ // by AgentHub 0.4.2's native gpt-5.6 client. The three rows here mirror the openai/*+ // OpenRouter rows above, which carry the gateway's (currently discounted) rates instead+ // of this list price.+ modelId: "gpt-5.6",+ displayName: "GPT-5.6",+ provider: "openai",+ contextWindow: 1050000,+ pricing: usd(0.5, 5, 30),+ supportsVision: true,+ },+ {+ modelId: "gpt-5.6-luna",+ displayName: "GPT-5.6 Luna",+ provider: "openai",+ contextWindow: 1050000,+ pricing: usd(0.02, 0.2, 1.2),+ supportsVision: true,+ },+ {+ modelId: "gpt-5.6-terra",+ displayName: "GPT-5.6 Terra",+ provider: "openai",+ contextWindow: 1050000,+ pricing: usd(0.2, 2, 12),+ supportsVision: true,+ },{modelId: "gpt-5.5",displayName: "GPT-5.5",@@ -983,6 +1166,17 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [supportsVision: true,},// -- Z.AI (GLM) --+ {+ // Announced 2026-08-14 and served by AgentHub 0.4.2's unified GLM client. Z.AI's price+ // list (docs.z.ai/guides/overview/pricing, read 2026-08-18) publishes the same USD rates+ // as glm-5.2 / glm-5.1.+ modelId: "glm-5.3",+ displayName: "GLM-5.3",+ provider: "zhipu",+ contextWindow: 1000000,+ pricing: usd(0.26, 1.4, 4.4),+ supportsVision: false,+ },{modelId: "glm-5.2",displayName: "GLM-5.2",@@ -1034,6 +1228,20 @@ export const MODEL_CATALOG: ModelCatalogEntry[] = [},];+/**+ * Canonical spelling of an AgentHub client-type string. AgentHub 0.4.2 renamed the generic+ * Chat Completions client from `openai` to `openai-chat`; the bare `openai` spelling still+ * routes upstream as a deprecated alias, but the harness converges on the canonical name —+ * config reads/writes and API request handling all normalize through here, so configs saved+ * before the rename keep working while comparisons (legacy-protocol display, catalog sync)+ * see one spelling. Any other value (including `openai-responses` / `openai-embedding`,+ * which merely contain "openai") passes through unchanged.+ */+export function canonicalClientType(clientType: string | undefined): string | undefined {+ if (clientType === undefined) return undefined;+ return clientType.trim().toLowerCase() === "openai" ? "openai-chat" : clientType;+}+/** Looks up a catalog entry by (provider, upstream id) pair (**the sole catalog-matching entry point**); returns undefined if not in the catalog. */export function catalogEntryFor(provider: string,@@ -1075,15 +1283,25 @@ export function resolveModelEnv(modelId: string, clientType?: string): ModelEnvI) {return env("ANTHROPIC");}- if (t.includes("gpt-5.4") || t.includes("gpt-5.5")) return env("OPENAI");+ if (t.includes("gpt-5.4") || t.includes("gpt-5.5") || t.includes("gpt-5.6")) {+ return env("OPENAI");+ }+ // agenthub 0.4.2's unified GLM client serves the whole glm-5 series (5.3 included).if (t.includes("glm-5")) return env("ZAI");- // agenthub 0.4.1 routes kimi-k3 to its own client, which reads the same MOONSHOT_* pair.- if (t.includes("kimi-k3")) return env("MOONSHOT");- if (t.includes("kimi-k2.5") || t.includes("kimi-k2.6")) return env("MOONSHOT");+ // agenthub 0.4.2's unified Kimi client serves the whole K2.5+ series; every spelling reads+ // the same MOONSHOT_* pair.+ if (t.includes("kimi-k3") || t.includes("kimi-k2.5") || t.includes("kimi-k2.6")) {+ return env("MOONSHOT");+ }if (t === "minimax-m3" && modelId.toLowerCase() === "minimax-m3") {return env("MINIMAX");}if (t.includes("deepseek-v4")) return env("DEEPSEEK");+ // agenthub 0.4.2's generic Anthropic Messages protocol client reads the ANTHROPIC_* pair.+ if (t.includes("ant-messages")) return env("ANTHROPIC");+ // The generic OpenAI-protocol clients — openai-chat (canonical since agenthub 0.4.2, with+ // bare "openai" as a deprecated alias), openai-responses and openai-embedding — all read+ // the OPENAI_* pair.if (t.includes("openai")) return env("OPENAI");return undefined;}@@ -1093,8 +1311,9 @@ export function resolveModelEnv(modelId: string, clientType?: string): ModelEnvI* config, avoiding duplicate hand-written copies). `provider` and `model_id` are persisted as* separate fields (`model_id` is the plain upstream id); models whose upstream id can be* auto-routed by AgentHub leave client_type unset; gateway models (OpenRouter / SiliconFlow)- * explicitly set client_type=openai and inline a preset base_url. The direct MiniMax M3 entry- * also pins its protocol and endpoint. No secrets are included, so only an API key is needed.+ * always pin a client_type — openai-chat, or openai-responses for the OpenRouter openai/*+ * rows — and inline a preset base_url. The direct MiniMax M3 entry also pins its protocol and+ * endpoint. No secrets are included, so only an API key is needed.*/export function presetModelEntries(): ModelEntry[] {return MODEL_CATALOG.map((m) => ({diff --git a/packages/core/src/state/project-config.ts b/packages/core/src/state/project-config.tsindex 52278fcd..d1284bd7 100644--- a/packages/core/src/state/project-config.ts+++ b/packages/core/src/state/project-config.ts@@ -28,7 +28,7 @@ import fs from "node:fs/promises";import path from "node:path";import { parse as parseToml, stringify as stringifyToml } from "smol-toml";import type { ThinkingLevelName } from "../interfaces.js";-import { presetModelEntries } from "./model-catalog.js";+import { canonicalClientType, presetModelEntries } from "./model-catalog.js";import { projectConfigPath } from "./paths.js";/** Model reference: a `(provider, model_id)` pair (never string-concatenated anywhere). */@@ -69,9 +69,11 @@ export interface ModelEntry {model_id: string;context_window?: number;/**- * AgentHub client protocol (`openai` / `claude-4-8` / `deepseek-v4` / …); defaults to being- * inferred by AgentHub from the request id (`model_id`). A third-party model speaking the- * OpenAI protocol should set this to `openai`.+ * AgentHub client protocol (`openai-chat` / `claude-4-8` / `deepseek-v4` / …); defaults to+ * being inferred by AgentHub from the request id (`model_id`). A third-party model speaking+ * the OpenAI Chat Completions protocol should set this to `openai-chat` (the bare `openai`+ * spelling from configs saved before AgentHub 0.4.2's rename is normalized to it on read —+ * see canonicalClientType).*/client_type?: string;/**@@ -202,7 +204,7 @@ function parseRefField(file: string, name: string, value: unknown): ModelRef | u/** Validates a model entry: both provider and model_id must be strings (an old-format entry is missing provider). */function assertModelEntry(file: string, entry: unknown): ModelEntry {- const m = entry as { provider?: unknown; model_id?: unknown };+ const m = entry as { provider?: unknown; model_id?: unknown; client_type?: unknown };if (typeof entry !== "object" ||entry === null ||@@ -213,6 +215,16 @@ function assertModelEntry(file: string, entry: unknown): ModelEntry {`A models entry in .project_config.toml is in a legacy/invalid format (provider and model_id must be two separate fields): ${file}. ${OLD_FORMAT_HINT}`,);}+ // Backward compatibility for configs saved before AgentHub 0.4.2 renamed the generic Chat+ // Completions client: a stored `client_type = "openai"` is normalized to the canonical+ // "openai-chat" on read (copied, never mutated in place — callers may hand in a cached+ // parse), so old configs keep working and every consumer sees one spelling.+ if (typeof m.client_type === "string") {+ const canonical = canonicalClientType(m.client_type);+ if (canonical !== m.client_type) {+ return { ...(entry as ModelEntry), client_type: canonical };+ }+ }return entry as ModelEntry;}@@ -406,7 +418,9 @@ export async function addModel(if (contextWindow !== undefined) {modelEntry.context_window = contextWindow;}- const clientType = entry.client_type ?? existing?.client_type;+ // Normalized on write as well as on read (canonicalClientType), so a caller passing the+ // pre-0.4.2 "openai" spelling still persists the canonical "openai-chat".+ const clientType = canonicalClientType(entry.client_type ?? existing?.client_type);if (clientType !== undefined) {modelEntry.client_type = clientType;}diff --git a/packages/core/test/model-catalog.test.ts b/packages/core/test/model-catalog.test.tsindex dfad4fc7..ac4eaf4b 100644--- a/packages/core/test/model-catalog.test.ts+++ b/packages/core/test/model-catalog.test.ts@@ -6,6 +6,7 @@ import { describe, expect, it } from "vitest";import {MODEL_CATALOG,MODEL_PROVIDERS,+ canonicalClientType,modelHomepageUrl,catalogEntryFor,presetModelEntries,@@ -49,6 +50,8 @@ describe("model-catalog", () => {expect(ids).not.toContain("z-ai/glm-5.1");expect(ids).not.toContain("Pro/zai-org/GLM-5.1");expect(ids).toContain("glm-5.1");+ // Ling 3.0 Flash's free tier was delisted from OpenRouter (removed 2026-08-18).+ expect(ids).not.toContain("inclusionai/ling-3.0-flash:free");});it("every provider is in MODEL_PROVIDERS (custom only groups user-defined models; the catalog never uses it)", () => {@@ -163,11 +166,12 @@ describe("model-catalog", () => {"anthropic/claude-sonnet-5","deepseek/deepseek-v4-flash-0731","deepseek/deepseek-v4-flash",+ "deepseek/deepseek-v4-pro-0813","deepseek/deepseek-v4-pro",+ "google/gemini-3.7-flash","google/gemini-3.6-flash","google/gemini-3.5-flash","google/gemini-3.5-flash-lite",- "inclusionai/ling-3.0-flash:free","minimax/minimax-m3","moonshotai/kimi-k3","moonshotai/kimi-k2.6",@@ -176,20 +180,38 @@ describe("model-catalog", () => {"openai/gpt-5.6-sol","openai/gpt-5.6-terra","openai/gpt-5.5",+ "openai/gpt-5.5-pro",+ "openai/gpt-5.4",+ "openai/gpt-5.4-mini",+ "openai/gpt-5.4-nano",+ "openai/gpt-5.4-pro","openrouter/free","qwen/qwen3.8-max","qwen/qwen3.6-35b-a3b","stepfun/step-3.7-flash","tencent/hy3","thinkingmachines/inkling",+ "x-ai/grok-4.6","x-ai/grok-4.5","xiaomi/mimo-v2.5",+ "z-ai/glm-5.3","z-ai/glm-5.2",]);for (const m of or) {- expect(m.clientType).toBe("openai");+ // Every gateway row pins a client type — never left to AgentHub's id-substring routing,+ // which would send openai/gpt-5.6-* to the first-party GPT client and throw outright on+ // the dotted anthropic/claude-opus-4.8. The openai/* rows speak the Responses protocol+ // (OpenRouter serves it at {base}/responses); everything else is Chat Completions.+ expect(m.clientType, m.modelId).toBe(+ m.modelId.startsWith("openai/") ? "openai-responses" : "openai-chat",+ );expect(m.baseUrl).toBe("https://openrouter.ai/api/v1");}+ // Both protocols read the same OPENAI_* pair, so the env-fallback hint is unaffected by+ // the split.+ for (const m of or) {+ expect(resolveModelEnv(m.modelId, m.clientType)?.envKey, m.modelId).toBe("OPENAI_API_KEY");+ }const fw = MODEL_CATALOG.filter((m) => m.provider === "fireworks");expect(fw.map((m) => [m.modelId, m.supportsVision])).toEqual([["accounts/fireworks/models/deepseek-v4-flash-0731", false],@@ -202,7 +224,7 @@ describe("model-catalog", () => {["accounts/fireworks/models/minimax-m3", true],]);for (const m of fw) {- expect(m.clientType).toBe("openai");+ expect(m.clientType).toBe("openai-chat");expect(m.baseUrl).toBe("https://api.fireworks.ai/inference/v1");}const sf = MODEL_CATALOG.filter((m) => m.provider === "siliconflow");@@ -218,7 +240,7 @@ describe("model-catalog", () => {"zai-org/GLM-5.2",]);for (const m of sf) {- expect(m.clientType).toBe("openai");+ expect(m.clientType).toBe("openai-chat");expect(m.baseUrl).toBe("https://api.siliconflow.cn/v1");}const qtp = MODEL_CATALOG.filter((m) => m.provider === "qwen-token-plan");@@ -230,7 +252,7 @@ describe("model-catalog", () => {"qwen3.7-plus",]);for (const m of qtp) {- expect(m.clientType).toBe("openai");+ expect(m.clientType).toBe("openai-chat");expect(m.baseUrl).toBe("https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1");}// Vision flags per the plan's supported-model table: 3.8-max and 3.7-plus see images.@@ -250,7 +272,7 @@ describe("model-catalog", () => {["ZHIPU/GLM-5.2", false],]);for (const m of qpayg) {- expect(m.clientType).toBe("openai");+ expect(m.clientType).toBe("openai-chat");expect(m.baseUrl).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");}const minimax = MODEL_CATALOG.filter((m) => m.provider === "minimax");@@ -351,7 +373,7 @@ describe("model-catalog", () => {it("direct-vendor groups: auto-routed (no client_type / base_url), newest series first", () => {// These groups' ids are auto-routed by AgentHub, so they carry neither client_type nor a// preset base URL — the opposite of the gateway groups above.- for (const id of ["google", "anthropic", "moonshot"]) {+ for (const id of ["google", "anthropic", "zhipu", "moonshot"]) {for (const m of MODEL_CATALOG.filter((e) => e.provider === id)) {expect(m.clientType, m.modelId).toBeUndefined();expect(m.baseUrl, m.modelId).toBeUndefined();@@ -360,6 +382,7 @@ describe("model-catalog", () => {// Dictionary order by tier with newer versions of a tier first (same rule the OpenRouter// block follows for the identical Claude line-up).expect(MODEL_CATALOG.filter((m) => m.provider === "google").map((m) => m.modelId)).toEqual([+ "gemini-3.7-flash","gemini-3.6-flash","gemini-3.5-flash","gemini-3.5-flash-lite",@@ -367,6 +390,48 @@ describe("model-catalog", () => {"gemini-3.1-pro-preview","gemini-3-flash-preview",]);+ expect(MODEL_CATALOG.filter((m) => m.provider === "zhipu").map((m) => m.modelId)).toEqual([+ "glm-5.3",+ "glm-5.2",+ "glm-5.1",+ "glm-5",+ ]);+ // Gemini 3.7 Flash: the direct row stores Google's official list price (the launch+ // discount that halves it through 2026-12-31 is not stored, matching the catalog's+ // no-promotions policy), while the OpenRouter row stores what the gateway actually+ // bills — a `discount: 0.75` off that same list price, i.e. a quarter of it.+ const g37 = catalogEntryFor("google", "gemini-3.7-flash")!;+ expect([g37.contextWindow, g37.supportsVision]).toEqual([1048576, true]);+ expect([g37.pricing!.cache_read, g37.pricing!.cache_write, g37.pricing!.output]).toEqual([+ 0.15, 1.5, 7.5,+ ]);+ const g37or = catalogEntryFor("openrouter", "google/gemini-3.7-flash")!;+ expect([g37or.contextWindow, g37or.supportsVision]).toEqual([1048576, true]);+ expect([g37or.pricing!.cache_read, g37or.pricing!.cache_write, g37or.pricing!.output]).toEqual([+ 0.0375, 0.375, 1.875,+ ]);+ // GLM-5.3 is listed both directly and on OpenRouter; the gateway runs no discount, so+ // the two rows agree on price and differ only in context window and protocol pin.+ const glm53or = catalogEntryFor("openrouter", "z-ai/glm-5.3")!;+ expect([glm53or.contextWindow, glm53or.supportsVision]).toEqual([1048576, false]);+ expect([+ glm53or.pricing!.cache_read,+ glm53or.pricing!.cache_write,+ glm53or.pricing!.output,+ ]).toEqual([0.26, 1.4, 4.4]);+ // GLM-5.3 (AgentHub 0.4.2's unified GLM client): text-only, 1M context, and Z.AI's+ // published USD price — identical to glm-5.2.+ const glm53 = catalogEntryFor("zhipu", "glm-5.3")!;+ expect([glm53.contextWindow, glm53.supportsVision]).toEqual([1000000, false]);+ expect(glm53.pricing).toEqual(catalogEntryFor("zhipu", "glm-5.2")!.pricing);+ // Grok 4.6 keeps Grok 4.5's input/output rates with a raised cache-hit price.+ const grok46 = catalogEntryFor("openrouter", "x-ai/grok-4.6")!;+ expect([grok46.contextWindow, grok46.supportsVision]).toEqual([500000, true]);+ expect([+ grok46.pricing!.cache_read,+ grok46.pricing!.cache_write,+ grok46.pricing!.output,+ ]).toEqual([0.5, 2, 6]);expect(MODEL_CATALOG.filter((m) => m.provider === "anthropic").map((m) => m.modelId)).toEqual(["claude-fable-5","claude-opus-4-8",@@ -416,9 +481,15 @@ describe("model-catalog", () => {it("DeepSeek and Kimi are initialized from official CNY prices (stored in USD; x7 recovers the official price)", () => {const cnyOf = (usdV: number) => Math.round(usdV * 7 * 1000) / 1000;- const pro = MODEL_CATALOG.find((m) => m.modelId === "deepseek-v4-pro")!.pricing!;+ // DeepSeek rows carry the official OFF-PEAK tier (the lower published price; peak hours+ // bill double) — re-read 2026-08-18 after the official price increase (issue #313).+ const flash = catalogEntryFor("deepseek", "deepseek-v4-flash")!.pricing!;+ expect([cnyOf(flash.cache_read), cnyOf(flash.cache_write), cnyOf(flash.output)]).toEqual([+ 0.05, 1.5, 4.5,+ ]);+ const pro = catalogEntryFor("deepseek", "deepseek-v4-pro")!.pricing!;expect([cnyOf(pro.cache_read), cnyOf(pro.cache_write), cnyOf(pro.output)]).toEqual([- 0.025, 3, 6,+ 0.15, 4.5, 13.5,]);const k3 = MODEL_CATALOG.find((m) => m.provider === "moonshot" && m.modelId === "kimi-k3",@@ -429,6 +500,102 @@ describe("model-catalog", () => {1.1, 6.5, 27,]);});++ it("OpenRouter DeepSeek rows carry the gateway's own 2026-08-18 prices (the 0813 GA release bills the official USD list)", () => {+ const pro0813 = catalogEntryFor("openrouter", "deepseek/deepseek-v4-pro-0813")!;+ expect([pro0813.contextWindow, pro0813.supportsVision]).toEqual([1048576, false]);+ expect([+ pro0813.pricing!.cache_read,+ pro0813.pricing!.cache_write,+ pro0813.pricing!.output,+ ]).toEqual([0.022, 0.66, 1.98]);+ // The undated pro listing routes to the same officially priced endpoints.+ const pro = catalogEntryFor("openrouter", "deepseek/deepseek-v4-pro")!.pricing!;+ expect([pro.cache_read, pro.cache_write, pro.output]).toEqual([0.022, 0.66, 1.98]);+ const flash = catalogEntryFor("openrouter", "deepseek/deepseek-v4-flash")!.pricing!;+ expect([flash.cache_read, flash.cache_write, flash.output]).toEqual([0.0168, 0.0679, 0.168]);+ const flash0731 = catalogEntryFor("openrouter", "deepseek/deepseek-v4-flash-0731")!.pricing!;+ expect([flash0731.cache_read, flash0731.cache_write, flash0731.output]).toEqual([+ 0.0157192, 0.078596, 0.157192,+ ]);+ });++ it("the OpenAI line-up is listed both directly and on OpenRouter, and only the gateway rows speak Responses", () => {+ // Every direct OpenAI model has an OpenRouter counterpart and vice versa: `openai/<id>`+ // is exactly the gateway spelling, so the two groups must stay in lockstep when either+ // gains a model.+ const direct = MODEL_CATALOG.filter((m) => m.provider === "openai").map((m) => m.modelId);+ expect(direct).toEqual([+ "gpt-5.6",+ "gpt-5.6-luna",+ "gpt-5.6-terra",+ "gpt-5.5",+ "gpt-5.5-pro",+ "gpt-5.4",+ "gpt-5.4-mini",+ "gpt-5.4-nano",+ "gpt-5.4-pro",+ ]);+ const gateway = MODEL_CATALOG.filter(+ (m) => m.provider === "openrouter" && m.modelId.startsWith("openai/"),+ ).map((m) => m.modelId);+ // The bare `gpt-5.6` alias has no gateway listing of its own — OpenRouter spells that+ // tier out as `openai/gpt-5.6-sol`, which is what the alias resolves to upstream.+ expect([...gateway].sort()).toEqual(+ [...direct.map((id) => (id === "gpt-5.6" ? "openai/gpt-5.6-sol" : `openai/${id}`))].sort(),+ );+ // Direct rows are auto-routed by id (AgentHub 0.4.2's native gpt-5.6 client); only the+ // gateway rows pin a protocol, and they pin Responses.+ for (const m of MODEL_CATALOG.filter((m) => m.provider === "openai")) {+ expect(m.clientType, m.modelId).toBeUndefined();+ expect(m.baseUrl, m.modelId).toBeUndefined();+ expect(m.supportsVision, m.modelId).toBe(true);+ }+ // Direct rows carry OpenAI's list price; the two 5.6 tiers below sol were re-read from+ // OpenRouter's undiscounted OpenAI/Azure endpoints, which agree with the list.+ const price = (provider: string, id: string): number[] => {+ const p = catalogEntryFor(provider, id)!.pricing!;+ return [p.cache_read, p.cache_write, p.output];+ };+ expect(price("openai", "gpt-5.6")).toEqual([0.5, 5, 30]);+ expect(price("openai", "gpt-5.6-terra")).toEqual([0.2, 2, 12]);+ expect(price("openai", "gpt-5.6-luna")).toEqual([0.02, 0.2, 1.2]);+ // Gateway rows store what OpenRouter bills, so they diverge from the list price wherever+ // a promotion is running: sol is at `discount: 0.5`, terra and luna are back at full rate+ // after theirs lapsed (the 2x drift this re-read corrected).+ expect(price("openrouter", "openai/gpt-5.6-sol")).toEqual([0.25, 3.125, 15]);+ expect(price("openrouter", "openai/gpt-5.6-terra")).toEqual([0.2, 2.5, 12]);+ expect(price("openrouter", "openai/gpt-5.6-luna")).toEqual([0.02, 0.25, 1.2]);+ // The 5.4/5.5 rows run no promotion, so gateway and direct agree except on cache_write,+ // where the gateway publishes GPT's genuine 1.25x write premium and the direct rows use+ // the standard input price.+ for (const id of ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"]) {+ const [dr, , dOut] = price("openai", id);+ const [gr, , gOut] = price("openrouter", `openai/${id}`);+ expect([gr, gOut], id).toEqual([dr, dOut]);+ }+ // The Pro tiers publish no cache discount at all, so cache_read carries the input price.+ for (const p of [price("openai", "gpt-5.5-pro"), price("openrouter", "openai/gpt-5.5-pro")]) {+ expect(p).toEqual([30, 30, 180]);+ }+ expect(price("openrouter", "openai/gpt-5.4-pro")).toEqual([30, 30, 180]);+ // Context windows match OpenRouter's published values and the direct rows.+ expect(catalogEntryFor("openrouter", "openai/gpt-5.4-mini")!.contextWindow).toBe(400000);+ expect(catalogEntryFor("openrouter", "openai/gpt-5.5")!.contextWindow).toBe(1050000);+ });++ it("canonicalClientType: the deprecated bare openai alias converges on openai-chat; everything else passes through", () => {+ expect(canonicalClientType("openai")).toBe("openai-chat");+ // Case/whitespace-insensitive match (AgentHub lowercases client types before routing).+ expect(canonicalClientType(" OpenAI ")).toBe("openai-chat");+ expect(canonicalClientType("openai-chat")).toBe("openai-chat");+ // Other client types containing "openai" are different protocols and must pass through.+ expect(canonicalClientType("openai-responses")).toBe("openai-responses");+ expect(canonicalClientType("openai-embedding")).toBe("openai-embedding");+ expect(canonicalClientType("ant-messages")).toBe("ant-messages");+ expect(canonicalClientType("minimax-m3")).toBe("minimax-m3");+ expect(canonicalClientType(undefined)).toBeUndefined();+ });});describe("resolveModelEnv (PRN-021: env fallback resolved by AgentHub routing rules)", () => {@@ -438,13 +605,19 @@ describe("resolveModelEnv (PRN-021: env fallback resolved by AgentHub routing ruexpect(resolveModelEnv("claude-sonnet-4-6")?.envKey).toBe("ANTHROPIC_API_KEY");expect(resolveModelEnv("gemini-3.5-flash")?.envKey).toBe("GEMINI_API_KEY");expect(resolveModelEnv("gpt-5.5-pro")?.envKey).toBe("OPENAI_API_KEY");+ // The GPT-5.6 generation (agenthub 0.4.2) reads the same OPENAI_* pair.+ expect(resolveModelEnv("gpt-5.6-luna")?.envKey).toBe("OPENAI_API_KEY");expect(resolveModelEnv("glm-5.2")?.envKey).toBe("ZAI_API_KEY");+ // glm-5.3 is served by agenthub 0.4.2's unified GLM client (same ZAI_* pair).+ expect(resolveModelEnv("glm-5.3")?.envKey).toBe("ZAI_API_KEY");expect(resolveModelEnv("kimi-k2.6")?.envBaseUrlKey).toBe("MOONSHOT_BASE_URL");- // agenthub 0.4.1 routes these to their own clients; both read the same env pair as the- // family they belong to, so the id must still resolve (kimi-k3 matches no k2.x substring).+ // agenthub 0.4.2 unified the Kimi clients; every spelling reads the same env pair+ // (kimi-k3 matches no k2.x substring, so it must resolve on its own).expect(resolveModelEnv("kimi-k3")?.envKey).toBe("MOONSHOT_API_KEY");expect(resolveModelEnv("kimi-k3")?.envBaseUrlKey).toBe("MOONSHOT_BASE_URL");expect(resolveModelEnv("gemini-3.6-flash")?.envKey).toBe("GEMINI_API_KEY");+ // The Gemini 3.7 generation is served by the same unified client (gemini-3 substring).+ expect(resolveModelEnv("gemini-3.7-flash")?.envKey).toBe("GEMINI_API_KEY");expect(resolveModelEnv("gemini-3.5-flash-lite")?.envKey).toBe("GEMINI_API_KEY");expect(resolveModelEnv("claude-fable-5")?.envKey).toBe("ANTHROPIC_API_KEY");expect(resolveModelEnv("claude-sonnet-5")?.envKey).toBe("ANTHROPIC_API_KEY");@@ -453,8 +626,17 @@ describe("resolveModelEnv (PRN-021: env fallback resolved by AgentHub routing ru});it("explicit client_type selects the protocol, while model-scoped clients still validate the id", () => {+ expect(resolveModelEnv("deepseek-v4-pro", "openai-chat")?.envKey).toBe("OPENAI_API_KEY");+ expect(resolveModelEnv("zai-org/GLM-5.2", "openai-chat")?.envKey).toBe("OPENAI_API_KEY");+ // The deprecated bare "openai" alias (pre-0.4.2 configs) still resolves the same pair.expect(resolveModelEnv("deepseek-v4-pro", "openai")?.envKey).toBe("OPENAI_API_KEY");- expect(resolveModelEnv("zai-org/GLM-5.2", "openai")?.envKey).toBe("OPENAI_API_KEY");+ // agenthub 0.4.2's generic protocol clients: openai-responses reads OPENAI_*,+ // ant-messages reads ANTHROPIC_* (matching the client implementations).+ expect(resolveModelEnv("deepseek-v4-pro", "openai-responses")?.envKey).toBe("OPENAI_API_KEY");+ expect(resolveModelEnv("deepseek-v4-pro", "ant-messages")?.envKey).toBe("ANTHROPIC_API_KEY");+ expect(resolveModelEnv("deepseek-v4-pro", "ant-messages")?.envBaseUrlKey).toBe(+ "ANTHROPIC_BASE_URL",+ );expect(resolveModelEnv("MiniMax-M3", "minimax-m3")?.envBaseUrlKey).toBe("MINIMAX_BASE_URL");expect(resolveModelEnv("custom-model", "minimax-m3")).toBeUndefined();});diff --git a/packages/core/test/state.test.ts b/packages/core/test/state.test.tsindex 14afd4d7..0090cd4b 100644--- a/packages/core/test/state.test.ts+++ b/packages/core/test/state.test.ts@@ -963,6 +963,51 @@ describe("project-config round trip", () => {expect(getModel(loaded, { provider: "custom", model_id: "unknown-model" })).toBeUndefined();});+ it('normalizes the pre-0.4.2 client_type = "openai" alias to openai-chat on read and write', async () => {+ // A config saved before AgentHub 0.4.2 renamed the generic Chat Completions client must+ // keep working: the stored bare "openai" spelling reads back as the canonical+ // "openai-chat" (normalize-on-read, no error and no disk rewrite required).+ const file = projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID);+ await fs.mkdir(path.dirname(file), { recursive: true });+ await fs.writeFile(+ file,+ [+ "[[models]]",+ 'provider = "custom"',+ 'model_id = "legacy-model"',+ 'client_type = "openai"',+ 'base_url = "https://example.com/v1"',+ ].join("\n"),+ "utf8",+ );+ const loaded = await loadProjectConfig(tmpRoot, DEFAULT_PROJECT_ID);+ expect(getModel(loaded, { provider: "custom", model_id: "legacy-model" })?.client_type).toBe(+ "openai-chat",+ );+ // Writes normalize too: an addModel caller passing the deprecated alias persists the+ // canonical spelling.+ await addModel(tmpRoot, DEFAULT_PROJECT_ID, {+ provider: "custom",+ model_id: "another-model",+ client_type: "openai",+ });+ const reloaded = await loadProjectConfig(tmpRoot, DEFAULT_PROJECT_ID);+ expect(getModel(reloaded, { provider: "custom", model_id: "another-model" })?.client_type).toBe(+ "openai-chat",+ );+ expect(await fs.readFile(file, "utf8")).toContain('client_type = "openai-chat"');+ // Non-alias client types pass through untouched (openai-responses is a different protocol).+ await addModel(tmpRoot, DEFAULT_PROJECT_ID, {+ provider: "custom",+ model_id: "responses-model",+ client_type: "openai-responses",+ });+ const third = await loadProjectConfig(tmpRoot, DEFAULT_PROJECT_ID);+ expect(getModel(third, { provider: "custom", model_id: "responses-model" })?.client_type).toBe(+ "openai-responses",+ );+ });+it("addModel files the entry under the provider it was given, never one of its own choosing", async () => {// provider is a required field: nothing is inferred from the builtin catalog, so a model// outside the known groups is filed under custom only because the caller said so. glm-5.2diff --git a/packages/docs/content/configuration.en.md b/packages/docs/content/configuration.en.mdindex 89b7c2cc..955b18aa 100644--- a/packages/docs/content/configuration.en.md+++ b/packages/docs/content/configuration.en.md@@ -59,7 +59,7 @@ Model entry (`[[models]]`) fields:| `provider` | Provider group; together with `model_id` forms the entry's unique key || `model_id` | Upstream request id, sent to AgentHub unchanged || `context_window` | Context window size |-| `client_type` | AgentHub client protocol; inferred from `model_id` by default — third-party OpenAI-compatible models should set `openai` |+| `client_type` | AgentHub client protocol; inferred from `model_id` by default — third-party OpenAI-compatible models should set `openai-chat` (the pre-0.4.2 `openai` spelling is a deprecated alias, normalized on read) || `display_name` | Display name; persisted only when it differs from the built-in catalog || `vision` | Whether image input is supported; defaults to supported || `max_tokens` | Per-model max output tokens; overrides the Agent's `model.max_tokens` when set, omitted = inherit it |diff --git a/packages/docs/content/configuration.zh.md b/packages/docs/content/configuration.zh.mdindex fa8a1ef7..26d9eb80 100644--- a/packages/docs/content/configuration.zh.md+++ b/packages/docs/content/configuration.zh.md@@ -59,7 +59,7 @@ openrouter、fireworks、siliconflow、qwen-token-plan、qwen-pay-as-you-go 与| `provider` | Provider 分组;与 `model_id` 共同构成条目唯一键 || `model_id` | 上游请求 id,原样发送给 AgentHub || `context_window` | 上下文窗口大小 |-| `client_type` | AgentHub 客户端协议;缺省由 `model_id` 推断,OpenAI 兼容的第三方模型应设为 `openai` |+| `client_type` | AgentHub 客户端协议;缺省由 `model_id` 推断,OpenAI 兼容的第三方模型应设为 `openai-chat`(0.4.2 之前的旧写法 `openai` 为已废弃别名,读取时归一化) || `display_name` | 展示名;仅在与内置目录不同时持久化 || `vision` | 是否支持图片输入;缺省视为支持 || `max_tokens` | 单模型最大输出 Token;设置后覆盖 Agent 的 `model.max_tokens`,缺省则继承 |diff --git a/packages/docs/content/models.en.md b/packages/docs/content/models.en.mdindex 16b42ef5..f09c895f 100644--- a/packages/docs/content/models.en.md+++ b/packages/docs/content/models.en.md@@ -23,7 +23,7 @@ Each Project's available models are recorded in the hidden `.project_config.toml| `model_id` | Upstream request id || `context_window` | Context window (tokens). Load-bearing, not just display: each request's effective output cap and the compaction threshold are derived from it, so requests never ask for more output than the window still fits. Unset (or implausibly small, under 4096): the output clamp turns off and compaction derives from an assumed 128000 — set the real value for models with smaller windows || `max_tokens` | Optional per-model output cap (max output tokens per request). When set it overrides the Agent's `model.max_tokens`; unset inherits it. The cap is a ceiling, not the literal wire value: each request sends `min(max_tokens, context_window − estimated input − safety margin)`, so small-window models work without hand-tuning it. Omitting the field on a Web full-table save clears it |-| `client_type` | Protocol hint (e.g. `openai`); inferred by AgentHub from the model id when omitted |+| `client_type` | Protocol hint (`openai-chat` for Chat Completions, `openai-responses` for the Responses API, `ant-messages` for Anthropic Messages, …); inferred by AgentHub from the model id when omitted. The pre-0.4.2 spelling `openai` is a deprecated alias and is normalized to `openai-chat` when the config is read || `display_name` | Display name || `vision` | Whether image input is supported, default true || `pricing` | Three price buckets (unit `usd_per_mtok`, USD per million tokens): `cache_read` / `cache_write` / `output` |@@ -45,7 +45,7 @@ context_window = 1000000[[models]]provider = "custom"model_id = "my-model"-client_type = "openai"+client_type = "openai-chat"base_url = "https://llm.example.com/v1"api_key = "sk-..."```@@ -72,15 +72,15 @@ Built-in groups and their env-var fallbacks (catalog source: `packages/core/src/| minimax | `MINIMAX_API_KEY` | Direct MiniMax M3 Responses client (`client_type = "minimax-m3"`): `MiniMax-M3` with a 1,000,000-token context window and vision; preset base URL `https://api.minimax.io/v1`; accepts a Token Plan Subscription Key or pay-as-you-go API key || custom | `OPENAI_API_KEY` | Any OpenAI-protocol endpoint |-The gateway groups (openrouter / fireworks / siliconflow / qwen-token-plan / qwen-pay-as-you-go) go through AgentHub's OpenAI client, so with blank credentials they read `OPENAI_API_KEY` — not a gateway-specific variable. The direct MiniMax M3 client reads `MINIMAX_API_KEY`. The built-in MiniMax preset pins `https://api.minimax.io/v1`; `MINIMAX_BASE_URL` is consulted only for entries without an inline `base_url`. M3 pricing records MiniMax's standard pay-as-you-go tier at 512K input tokens or below; every rate doubles above that and the priority tier is 1.5x, so long-context and priority usage is underestimated — the same base-tier convention already used for OpenAI (>272K) and Gemini 3.1 Pro (>200K).+The gateway groups (openrouter / fireworks / siliconflow / qwen-token-plan / qwen-pay-as-you-go) go through AgentHub's generic OpenAI-protocol clients, so with blank credentials they read `OPENAI_API_KEY` — not a gateway-specific variable. Most gateway presets pin the Chat Completions client (`client_type = "openai-chat"`); the OpenRouter `openai/*` presets pin the Responses client (`client_type = "openai-responses"`) instead, because OpenRouter serves the Responses API at the same base URL and those rows' upstream is OpenAI itself. Both clients read the same `OPENAI_*` variables, so the credential rules are identical either way. The direct MiniMax M3 client reads `MINIMAX_API_KEY`. The built-in MiniMax preset pins `https://api.minimax.io/v1`; `MINIMAX_BASE_URL` is consulted only for entries without an inline `base_url`. M3 pricing records MiniMax's standard pay-as-you-go tier at 512K input tokens or below; every rate doubles above that and the priority tier is 1.5x, so long-context and priority usage is underestimated — the same base-tier convention already used for OpenAI (>272K) and Gemini 3.1 Pro (>200K).-The preset catalog also carries OpenRouter's free tier: `:free` model variants (e.g. `inclusionai/ling-3.0-flash:free`, `nvidia/nemotron-3-ultra-550b-a55b:free`) and the `openrouter/free` unified Free Models Router. They cost nothing, but are subject to OpenRouter's free-tier rate limits and data policy.+The preset catalog also carries OpenRouter's free tier: the `:free` model variant `nvidia/nemotron-3-ultra-550b-a55b:free` and the `openrouter/free` unified Free Models Router. They cost nothing, but are subject to OpenRouter's free-tier rate limits and data policy.-Some models in the preset catalog: deepseek-v4-pro / deepseek-v4-flash, MiniMax-M3, gemini-3.1-pro-preview, claude-opus-4-8 / claude-sonnet-4-6, gpt-5.5, glm-5.2, kimi-k2.6, qwen3.8-max (not exhaustive).+Some models in the preset catalog: deepseek-v4-pro / deepseek-v4-flash, MiniMax-M3, gemini-3.7-flash, claude-opus-4-8 / claude-sonnet-5, gpt-5.6 / gpt-5.5, glm-5.3, kimi-k3, qwen3.8-max (not exhaustive). The whole OpenAI line-up is listed twice — directly (your own OpenAI key, list prices) and on OpenRouter as `openai/<id>` (the gateway's rates, which follow its running promotions). DeepSeek's direct-group prices record the official off-peak tier (peak hours, Beijing 9:00–12:00 and 14:00–18:00, bill double).## Local / self-hosted OpenAI-compatible endpoints (e.g. vLLM)-A local inference server is just a `custom` entry: `client_type = "openai"`, `base_url` pointing at the server (e.g. `http://127.0.0.1:8000/v1`), and the served model name as `model_id`. Two settings make it run smoothly:+A local inference server is just a `custom` entry: `client_type = "openai-chat"`, `base_url` pointing at the server (e.g. `http://127.0.0.1:8000/v1`), and the served model name as `model_id`. Two settings make it run smoothly:- **Enable tool calling server-side.** For vLLM, start the server with `--enable-auto-tool-choice` and the `--tool-call-parser` matching your model (e.g. `hermes` for Qwen, `llama3_json` for Llama 3.x); without them tool calls arrive as plain text and the agent loop cannot execute anything.- **Set the entry's `context_window` to the server's real window** — for vLLM, the `--max-model-len` value (e.g. `32768`). The per-request output cap and the compaction threshold both derive from this window automatically: requests clamp `max_tokens` to what the window still fits, and compaction fires before the window overflows, so no hand-tuned `max_tokens` is needed. Left unset, the per-request output clamp is off and compaction assumes a 128000 window, so a smaller real window will reject requests.diff --git a/packages/docs/content/models.zh.md b/packages/docs/content/models.zh.mdindex 77ed638e..d1bc3957 100644--- a/packages/docs/content/models.zh.md+++ b/packages/docs/content/models.zh.md@@ -23,7 +23,7 @@ description: 经 AgentHub 单一网关接入模型,以 (provider, model_id)| `model_id` | 上游请求 id || `context_window` | 上下文窗口(Token 数)。不只用于展示:每次请求的实际输出上限与压缩阈值都由它推导,请求不会索要超出窗口剩余空间的输出。缺省(或小于 4096 的非常规值)时输出收敛关闭、压缩按 128000 假定推导——窗口更小的模型务必填真实值 || `max_tokens` | 可选的按模型输出上限(单次请求最大输出 Token 数)。设置后覆盖 Agent 的 `model.max_tokens`,缺省沿用。该值是天花板而非逐字上线值:每次请求实际发送 `min(max_tokens, context_window − 估算输入 − 安全余量)`,小窗口模型无需手工调低。Web 整表保存时省略该字段即清除 |-| `client_type` | 协议提示(如 `openai`);缺省由 AgentHub 按 model id 推断 |+| `client_type` | 协议提示(`openai-chat` 对应 Chat Completions、`openai-responses` 对应 Responses API、`ant-messages` 对应 Anthropic Messages 等);缺省由 AgentHub 按 model id 推断。0.4.2 之前的旧写法 `openai` 为已废弃别名,读取配置时归一化为 `openai-chat` || `display_name` | 显示名 || `vision` | 是否支持图像输入,默认 true || `pricing` | 三档价格(单位 `usd_per_mtok`,USD 每百万 Token):`cache_read` / `cache_write` / `output` |@@ -45,7 +45,7 @@ context_window = 1000000[[models]]provider = "custom"model_id = "my-model"-client_type = "openai"+client_type = "openai-chat"base_url = "https://llm.example.com/v1"api_key = "sk-..."```@@ -72,15 +72,15 @@ api_key = "sk-..."| minimax | `MINIMAX_API_KEY` | 直连 MiniMax M3 Responses 客户端(`client_type = "minimax-m3"`):`MiniMax-M3` 支持 1,000,000 Token 上下文和视觉输入;预置 base URL `https://api.minimax.io/v1`;接受 Token Plan Subscription Key 或按量付费 API Key || custom | `OPENAI_API_KEY` | 任意 OpenAI 协议端点 |-网关分组(openrouter / fireworks / siliconflow / qwen-token-plan / qwen-pay-as-you-go)经 AgentHub 的 OpenAI 客户端请求,因此凭证留空时读取的是 `OPENAI_API_KEY`,而非网关自己的变量名。直连 MiniMax M3 客户端读取 `MINIMAX_API_KEY`。内置 MiniMax 预设固定使用 `https://api.minimax.io/v1`;仅当模型条目未内联 `base_url` 时才读取 `MINIMAX_BASE_URL`。M3 价格取 MiniMax 按量付费的标准档、输入不超过 512K Token 的牌价;超过 512K 后各档价格翻倍,priority 档另为 1.5 倍,因此长上下文与 priority 用量会被低估——与 OpenAI(>272K)、Gemini 3.1 Pro(>200K)沿用的基准档口径一致。+网关分组(openrouter / fireworks / siliconflow / qwen-token-plan / qwen-pay-as-you-go)经 AgentHub 的通用 OpenAI 协议客户端请求,因此凭证留空时读取的是 `OPENAI_API_KEY`,而非网关自己的变量名。多数网关预置固定 Chat Completions 客户端(`client_type = "openai-chat"`);OpenRouter 的 `openai/*` 预置则固定 Responses 客户端(`client_type = "openai-responses"`)——OpenRouter 在同一 base URL 上提供 Responses API,且这些条目的上游本就是 OpenAI。两种客户端读取相同的 `OPENAI_*` 变量,凭证规则完全一致。直连 MiniMax M3 客户端读取 `MINIMAX_API_KEY`。内置 MiniMax 预设固定使用 `https://api.minimax.io/v1`;仅当模型条目未内联 `base_url` 时才读取 `MINIMAX_BASE_URL`。M3 价格取 MiniMax 按量付费的标准档、输入不超过 512K Token 的牌价;超过 512K 后各档价格翻倍,priority 档另为 1.5 倍,因此长上下文与 priority 用量会被低估——与 OpenAI(>272K)、Gemini 3.1 Pro(>200K)沿用的基准档口径一致。-预置目录还收录了 OpenRouter 的免费档:`:free` 模型变体(如 `inclusionai/ling-3.0-flash:free`、`nvidia/nemotron-3-ultra-550b-a55b:free`)与统一路由 `openrouter/free`(Free Models Router),零成本可用,但受 OpenRouter 免费档速率限制与数据政策约束。+预置目录还收录了 OpenRouter 的免费档:`:free` 模型变体 `nvidia/nemotron-3-ultra-550b-a55b:free` 与统一路由 `openrouter/free`(Free Models Router),零成本可用,但受 OpenRouter 免费档速率限制与数据政策约束。-预置目录中的部分模型:deepseek-v4-pro / deepseek-v4-flash、MiniMax-M3、gemini-3.1-pro-preview、claude-opus-4-8 / claude-sonnet-4-6、gpt-5.5、glm-5.2、kimi-k2.6、qwen3.8-max 等(非完整清单)。+预置目录中的部分模型:deepseek-v4-pro / deepseek-v4-flash、MiniMax-M3、gemini-3.7-flash、claude-opus-4-8 / claude-sonnet-5、gpt-5.6 / gpt-5.5、glm-5.3、kimi-k3、qwen3.8-max 等(非完整清单)。OpenAI 全系列都收录了两份——直连(用自己的 OpenAI Key,记牌价)与 OpenRouter 上的 `openai/<id>`(记网关实际计费价,会随其促销浮动)。DeepSeek 直连分组的价格记录官方低谷时段档(高峰时段——北京时间 9:00–12:00、14:00–18:00——按双倍计费)。## 本地 / 自建 OpenAI 兼容端点(如 vLLM)-本地推理服务就是一条 `custom` 条目:`client_type = "openai"`、`base_url` 指向服务地址(如 `http://127.0.0.1:8000/v1`)、`model_id` 填服务端的模型名。两处设置决定运行是否顺畅:+本地推理服务就是一条 `custom` 条目:`client_type = "openai-chat"`、`base_url` 指向服务地址(如 `http://127.0.0.1:8000/v1`)、`model_id` 填服务端的模型名。两处设置决定运行是否顺畅:- **服务端要开启工具调用。** vLLM 需以 `--enable-auto-tool-choice` 启动,并按模型选择对应的 `--tool-call-parser`(如 Qwen 用 `hermes`、Llama 3.x 用 `llama3_json`);不开启时工具调用会以纯文本返回,Agent 循环无法执行任何工具。- **条目的 `context_window` 填服务端的真实窗口**——vLLM 即 `--max-model-len` 的值(如 `32768`)。每次请求的输出上限与压缩阈值都会由该窗口自动推导:请求把 `max_tokens` 收敛到窗口剩余空间以内,压缩也会在撞上窗口硬限制之前触发,无需手工调低 `max_tokens`。不填时不做逐请求输出收敛、压缩按 128000 假定,真实窗口更小会导致请求被拒。diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.tsindex 1b421e38..8fc78585 100644--- a/packages/server/src/api/types.ts+++ b/packages/server/src/api/types.ts@@ -289,7 +289,7 @@ export interface ModelInfo {/** Display name: explicit TOML field (user-edited) takes priority, then the built-in catalog; falls back to unset (frontend shows modelId). */displayName?: string;contextWindow?: number;- /** AgentHub client protocol (`openai`, etc.); defaults to AgentHub inferring it from modelId. */+ /** AgentHub client protocol (`openai-chat`, `openai-responses`, etc.); defaults to AgentHub inferring it from modelId. */clientType?: string;/*** Whether image input (vision/multimodal) is supported: the TOML `vision` annotation takesdiff --git a/packages/server/src/services/project-config-service.ts b/packages/server/src/services/project-config-service.tsindex b6e31ff3..efa0bb75 100644--- a/packages/server/src/services/project-config-service.ts+++ b/packages/server/src/services/project-config-service.ts@@ -30,6 +30,7 @@ import {CHAT_APPROVAL_MODES,DEFAULT_CHAT_THINKING_LEVELS,GenerativeModel,+ canonicalClientType,catalogEntryFor,defaultProjectConfig,projectConfigFromTable,@@ -402,7 +403,9 @@ export class ProjectConfigService {const apiKey = req.clearApiKey ? undefined : (req.apiKey ?? savedKey);const savedBaseUrl = optStr(entry.base_url);const baseUrl = req.baseUrl === null ? undefined : (req.baseUrl ?? savedBaseUrl);- const clientType = req.clientType ?? optStr(entry.client_type);+ // The pre-0.4.2 "openai" spelling (request or stored entry) is normalized to the+ // canonical "openai-chat" (deprecated upstream alias; see canonicalClientType).+ const clientType = canonicalClientType(req.clientType ?? optStr(entry.client_type));const startedAt = Date.now();try {@@ -497,7 +500,10 @@ export class ProjectConfigService {output: optNum(pricing.output) ?? 0,}: undefined;- const clientType = optStr(m.client_type);+ // Normalized on read: entries stored before AgentHub 0.4.2's openai -> openai-chat+ // rename report the canonical spelling without a disk rewrite (the next models PUT+ // persists it).+ const clientType = canonicalClientType(optStr(m.client_type));const cat = catalogEntryFor(provider, modelId);// The env fallback is reported as-is: follows the same rule as// AgentHub routing — an explicit client_type takes priority (the openai@@ -619,7 +625,9 @@ export class ProjectConfigService {next.display_name = entry.displayName;}if (entry.contextWindow !== undefined) next.context_window = entry.contextWindow;- if (entry.clientType) next.client_type = entry.clientType;+ // Stored canonically: a client sending the deprecated "openai" alias persists+ // "openai-chat" (see canonicalClientType).+ if (entry.clientType) next.client_type = canonicalClientType(entry.clientType);// Treated as supported by default: only written to disk when explicitly annotated (both true/false are kept; false drives a frontend blocking hint).if (entry.vision !== undefined) next.vision = entry.vision;// Inherit-the-Agent-value by default: only written to disk when explicitly annotated (omitted on a full-table PUT = the annotation is cleared).diff --git a/packages/server/test/models.test.ts b/packages/server/test/models.test.tsindex 3eaf0495..49c1c615 100644--- a/packages/server/test/models.test.ts+++ b/packages/server/test/models.test.ts@@ -10,7 +10,7 @@*/import { createServer } from "node:http";import type { AddressInfo } from "node:net";-import { readFile, stat } from "node:fs/promises";+import { readFile, stat, writeFile } from "node:fs/promises";import path from "node:path";import { afterEach, beforeEach, describe, expect, it } from "vitest";import { MODEL_CATALOG, userText } from "@prismshadow/penguin-core";@@ -118,9 +118,9 @@ describe("models preset & catalog enrichment", () => {expect(pick(body, "deepseek", "deepseek-v4-flash").isDefault).toBe(true);// OpenRouter gateway model: the upstream id contains `/`, but under column storage it's just a- // plain string; openai protocol + a preset base URL inlined on the entry (no secret).+ // plain string; openai-chat protocol + a preset base URL inlined on the entry (no secret).const mimo = pick(body, "openrouter", "xiaomi/mimo-v2.5");- expect(mimo.clientType).toBe("openai");+ expect(mimo.clientType).toBe("openai-chat");expect(mimo.credential?.baseUrl).toBe("https://openrouter.ai/api/v1");expect(mimo.credential?.apiKeyMasked).toBeUndefined();});@@ -141,7 +141,9 @@ describe("models preset & catalog enrichment", () => {expect(mine.displayName).toBeUndefined();expect(mine.vision).toBe(false);expect(mine.envKey).toBe("OPENAI_API_KEY");- expect(mine.clientType).toBe("openai");+ // The request carried the deprecated bare "openai" alias (pre-0.4.2 clients/configs):+ // it is normalized to the canonical "openai-chat" on write and reported canonically.+ expect(mine.clientType).toBe("openai-chat");// Off-catalog model without client_type: no env-var fallback; with no vision annotation the field is omitted (default = supported).const opaque = pick(body, "custom", "opaque-model");@@ -152,9 +154,14 @@ describe("models preset & catalog enrichment", () => {// AgentHub's openai client actually reads OPENAI_API_KEY, so the env fallback reports that, not the vendor's var name.expect(pick(body, "anthropic", "claude-via-gateway").envKey).toBe("OPENAI_API_KEY");- // GET again: vision was persisted (not just echoed from the request body).+ // GET again: vision was persisted (not just echoed from the request body), and the disk+ // stores the canonical client-type spelling.const again = (await (await api.get(url())).json()) as ModelsResponse;expect(pick(again, "custom", "my-model").vision).toBe(false);+ expect(pick(again, "custom", "my-model").clientType).toBe("openai-chat");+ const toml = await readFile(path.join(t.root, projectId, ".project_config.toml"), "utf8");+ expect(toml).toContain('client_type = "openai-chat"');+ expect(toml).not.toContain('"openai"');// vision shape check: non-boolean → 400.const bad = await api.put(url(), {@@ -167,6 +174,98 @@ describe("models preset & catalog enrichment", () => {expect(noProvider.status).toBe(400);});+ it('a config stored before the AgentHub 0.4.2 rename (client_type = "openai") keeps working: GET reports the canonical openai-chat', async () => {+ // Simulate an existing user config written by an older harness version: the deprecated+ // bare "openai" spelling on disk. Reading must not error and must report the canonical+ // spelling (normalize-on-read, no disk rewrite needed until the next PUT).+ const cfgFile = path.join(t.root, projectId, ".project_config.toml");+ await writeFile(+ cfgFile,+ [+ "[[models]]",+ 'provider = "custom"',+ 'model_id = "legacy-openai-model"',+ 'client_type = "openai"',+ 'base_url = "https://legacy.example/v1"',+ ].join("\n"),+ "utf8",+ );+ const body = (await (await api.get(url())).json()) as ModelsResponse;+ const legacy = pick(body, "custom", "legacy-openai-model");+ expect(legacy.clientType).toBe("openai-chat");+ // The env fallback resolves like any openai-chat entry.+ expect(legacy.envKey).toBe("OPENAI_API_KEY");+ });++ it("a configured model that has since been dropped from the built-in catalog still loads, keeps its data, and stays usable", async () => {+ // Migration guard for catalog removals (the 2026-08-18 inclusionai/ling-3.0-flash:free+ // delisting is the live example): a user who configured the preset before it was removed+ // keeps a row on disk that catalogEntryFor no longer matches. Everything presetModelEntries+ // persisted must survive — only display_name lived solely in the catalog — and the row must+ // stay a normal, selectable entry rather than being pruned, rejected or blanked.+ const cfgFile = path.join(t.root, projectId, ".project_config.toml");+ await writeFile(+ cfgFile,+ [+ "[[models]]",+ 'provider = "openrouter"',+ 'model_id = "vendor/removed-from-catalog:free"',+ "context_window = 262144",+ 'client_type = "openai-chat"',+ 'base_url = "https://openrouter.ai/api/v1"',+ 'api_key = "sk-still-here"',+ "vision = false",+ "",+ "[models.pricing]",+ 'unit = "usd_per_mtok"',+ "cache_read = 0.0",+ "cache_write = 0.0",+ "output = 0.0",+ ].join("\n"),+ "utf8",+ );+ // Sanity: the id really is absent from the built-in catalog, so this exercises the+ // off-catalog path rather than an accidental match.+ expect(+ MODEL_CATALOG.some(+ (m) => m.provider === "openrouter" && m.modelId === "vendor/removed-from-catalog:free",+ ),+ ).toBe(false);++ const body = (await (await api.get(url())).json()) as ModelsResponse;+ const orphan = pick(body, "openrouter", "vendor/removed-from-catalog:free");+ // Everything stored in TOML is read straight back — pricing and context window come from+ // the file, not the catalog, so a $0 free-tier row keeps costing 0 rather than going+ // "unknown".+ expect(orphan.contextWindow).toBe(262144);+ expect(orphan.pricing).toEqual({ cacheRead: 0, cacheWrite: 0, output: 0 });+ expect(orphan.vision).toBe(false);+ expect(orphan.clientType).toBe("openai-chat");+ expect(orphan.envKey).toBe("OPENAI_API_KEY");+ // The credential survives, masked; the base URL is still inlined on the entry.+ expect(orphan.credential?.baseUrl).toBe("https://openrouter.ai/api/v1");+ expect(orphan.credential?.apiKeyMasked).toBeTruthy();+ // The one real loss: display_name only ever lived in the catalog, so the UI falls back to+ // the raw upstream id.+ expect(orphan.displayName).toBeUndefined();++ // Still a legal default-model target — nothing validates the pair against the catalog.+ const put = await api.put(url(), {+ models: [+ {+ provider: "openrouter",+ modelId: "vendor/removed-from-catalog:free",+ contextWindow: 262144,+ clientType: "openai-chat",+ },+ ],+ defaultModel: { provider: "openrouter", modelId: "vendor/removed-from-catalog:free" },+ });+ expect(put.status).toBe(200);+ const after = (await (await api.get(url())).json()) as ModelsResponse;+ expect(pick(after, "openrouter", "vendor/removed-from-catalog:free").isDefault).toBe(true);+ });+it("PUT maxTokens: persisted as max_tokens and read back through GET; omitting it table-wide clears it; 0 / negative / non-numeric 400", async () => {const put = await api.put(url(), {models: [diff --git a/packages/skills/skills/agenthub-models/SKILL.md b/packages/skills/skills/agenthub-models/SKILL.mdindex 39aec028..5e8c6cef 100644--- a/packages/skills/skills/agenthub-models/SKILL.md+++ b/packages/skills/skills/agenthub-models/SKILL.md@@ -3,8 +3,8 @@ name: agenthub-modelsdescription: Call model APIs through @prismshadow/agenthub — streaming text generation, image generation, speech synthesis, embeddings and the supported-model registry with one client.short_description: Call model APIs with one AgentHub client.short_description_zh: 用一个 AgentHub 客户端调用模型 API。-version: 11-updated: 2026-08-06T11:51:12Z+version: 12+updated: 2026-08-18T21:40:00Z---# AgentHub Model APIs@@ -34,7 +34,7 @@ If the user's message only invokes this skill (e.g. "use agenthub-models skill")Check for a usable API key before writing code — the client needs one for whichever provider you target:```bash-env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI)_API_KEY" || echo none+env | grep -oE "(DEEPSEEK|OPENAI|ANTHROPIC|GEMINI|ZAI|MOONSHOT|MINIMAX)_API_KEY" || echo none```Vault keys also appear in your Vault Keys section. **Only two sources count as a usable key**: a vault-injected environment variable (the check above), or — when the app stores its own model config — a key already configured in the app's own data root (`penguin config model list --root <data_dir>`). Keys living in the global `~/.penguin` or any other `.penguin` directory do **not** count — a bare `penguin config model list` (no `--root`) reads the global store, because the CLI defaults to the global root unless `--root` is given, so a key showing up there proves nothing for your script and must never be used or copied.@@ -49,18 +49,23 @@ Use exact model ids. If an id is not in the table below and the user has not giv| Family | Official IDs | Gateway variants || ---------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |+| Gemini 3.7 | `gemini-3.7-flash` | OpenRouter `google/gemini-3.7-flash` || Gemini 3.6 | `gemini-3.6-flash`, `gemini-3.5-flash-lite` | — || Gemini 3 | `gemini-3.1-pro-preview`, `gemini-3.5-flash`, `gemini-3.1-flash-lite` | — || Gemini 3 image | `gemini-3.1-flash-image`, `gemini-3-pro-image-preview` | — || Gemini 3 TTS | `gemini-3.1-flash-tts-preview` | — || Gemini embedding | `gemini-embedding-2` | — |-| Claude 5 | `claude-fable-5`, `claude-sonnet-5` | OpenRouter `anthropic/claude-fable-5`, `anthropic/claude-sonnet-5` |+| Claude 5 | `claude-fable-5`, `claude-sonnet-5` | OpenRouter `anthropic/claude-fable-5`, `anthropic/claude-opus-5`, `anthropic/claude-sonnet-5` || Claude 4 | `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-opus-4-8` | OpenRouter `anthropic/claude-opus-4.8`, `anthropic/claude-opus-4.7` |-| GPT | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5` | — |+| GPT-5.6 | `gpt-5.6` (routes to sol), `gpt-5.6-terra`, `gpt-5.6-luna` | OpenRouter `openai/gpt-5.6-sol`, `openai/gpt-5.6-terra`, `openai/gpt-5.6-luna` |+| GPT-5.5 / 5.4 | `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano` | OpenRouter `openai/gpt-5.5`, `openai/gpt-5.5-pro`, `openai/gpt-5.4`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-nano`, `openai/gpt-5.4-pro` || OpenAI embedding | `text-embedding-3-small`, `text-embedding-3-large` | — |+| MiniMax M3 | `MiniMax-M3` | OpenRouter `minimax/minimax-m3` || Kimi K3 | `kimi-k3` | OpenRouter `moonshotai/kimi-k3` |+| Kimi K2.7 Code | — | SiliconFlow `moonshotai/Kimi-K2.7-Code`; Fireworks AI `accounts/fireworks/models/kimi-k2p7-code` || Kimi K2.6 | `kimi-k2.6` | OpenRouter `moonshotai/kimi-k2.6`; SiliconFlow `Pro/moonshotai/Kimi-K2.6` |-| DeepSeek V4 | `deepseek-v4-pro`, `deepseek-v4-flash` | OpenRouter `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-flash-0731`; Fireworks AI `accounts/fireworks/models/deepseek-v4-flash-0731`; SiliconFlow `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` |+| DeepSeek V4 | `deepseek-v4-pro`, `deepseek-v4-flash` | OpenRouter `deepseek/deepseek-v4-pro-0813`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `deepseek/deepseek-v4-flash-0731`; Fireworks AI `accounts/fireworks/models/deepseek-v4-flash-0731`; SiliconFlow `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` |+| GLM 5.3 | `glm-5.3` | OpenRouter `z-ai/glm-5.3` || GLM 5.2 | `glm-5.2` | OpenRouter `z-ai/glm-5.2`; SiliconFlow `zai-org/GLM-5.2` || GLM 5.1 | `glm-5.1` | — || Qwen 3.8 Max | — | OpenRouter `qwen/qwen3.8-max` |@@ -96,10 +101,14 @@ The registry is the curated current line-up, so prefer it when picking a model o## Routing and credentials-- Without `clientType`, the client auto-routes by model id substring, in this order: `gemini-3.6` / `gemini-3.5-flash-lite`, then `gemini-3*` / `gemini-embedding`, `claude` 4-6/4-7/4-8/-5, `gpt-5.4`/`gpt-5.5`, `glm-5.2`, `glm-5`, `kimi-k3`, `kimi-k2.5`/`kimi-k2.6`, `deepseek-v4`, `openai`+`embedding` (embeddings), `openai`. Ids matching none of these throw. The gateway variants in the table above hit the same substrings, so they route to the right family — just set `baseUrl` to the gateway endpoint.-- Exception: a Gemini id served by an OpenAI-compatible gateway (e.g. OpenRouter's `google/gemini-3.6-flash`) still matches the Gemini substring and would auto-route to the Google protocol client. Pass `clientType: "openai"` explicitly for those.-- For any other OpenAI chat-completion compatible model (e.g. Qwen series via OpenRouter or SiliconFlow), pass `clientType: "openai"` plus `baseUrl` (embeddings endpoints use a different client type — see Embeddings below).-- API key: constructor parameter first, then the provider environment variable — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_API_KEY`. Base URLs read the same names with `_BASE_URL`.+- Without `clientType`, the client auto-routes by model id substring, in this order: `minimax-m3` (exact), `gemini-3*` / `gemini-embedding`, `claude` 4-6/4-7/4-8/-5, `gpt-5.4`/`gpt-5.5`/`gpt-5.6`, `glm-5` (whole series, 5.3 included), `kimi-k3`/`kimi-k2.5`/`kimi-k2.6`, `deepseek-v4`, `ant-messages`, `openai-responses`, `openai`+`embedding` (embeddings), `openai` (chat). Ids matching none of these throw. Most gateway variants in the table above hit the same substrings, so they route to the right family — just set `baseUrl` to the gateway endpoint.+- Three generic protocol clients cover everything else (all take `baseUrl` + `apiKey`):+ - `clientType: "openai-chat"` — any OpenAI Chat Completions compatible endpoint (gateway models, Qwen via OpenRouter/SiliconFlow, local vLLM, …). Renamed from `openai` in AgentHub 0.4.2; the bare `openai` string still routes as a deprecated alias.+ - `clientType: "openai-responses"` — OpenAI Responses-compatible endpoints (OpenAI, OpenRouter, DeepSeek, Z.AI, MiniMax all serve one).+ - `clientType: "ant-messages"` — Anthropic Messages-compatible endpoints (Anthropic, OpenRouter `https://openrouter.ai/api`, DeepSeek `https://api.deepseek.com/anthropic`, Z.AI, MiniMax).+- Exception: an id served by an OpenAI-compatible gateway that still matches a first-party substring (e.g. OpenRouter's `google/gemini-3.7-flash`, `anthropic/claude-sonnet-5` or `openai/gpt-5.6-sol` on the `/api/v1` endpoint) would auto-route to the vendor protocol client — and a dotted id like `anthropic/claude-opus-4.8` matches nothing and throws. Always pass an explicit `clientType` for gateway ids; never rely on the id. Routing reads `clientType` (or the model id) as a plain lowercased string and never looks at `baseUrl`, so the vendor prefix gives no protection.+- OpenRouter serves both protocols at `https://openrouter.ai/api/v1`, so its `openai/*` ids work with `clientType: "openai-responses"` as well as `"openai-chat"`; use Responses when you want reasoning items round-tripped.+- API key: constructor parameter first, then the provider environment variable — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY` (also for `ant-messages`), `OPENAI_API_KEY` (also for `openai-chat`/`openai-responses`), `GEMINI_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_API_KEY`. Base URLs read the same names with `_BASE_URL`.## Streaming text@@ -115,7 +124,7 @@ for await (const event of client.streamingResponseStateful({```- Each `event` is a `UniEvent`: `event_type` is `start` | `delta` | `stop`, and `content_items` carry the increments.-- `config` accepts `max_tokens`, `temperature`, `system_prompt`, `thinking_level` (the `ThinkingLevel` enum, `NONE` to `XHIGH`), `tool_choice`, `prompt_caching` and `tools`.+- `config` accepts `max_tokens`, `temperature`, `system_prompt`, `thinking_level` (the `ThinkingLevel` enum, `NONE` to `XHIGH`), `tool_choice`, `prompt_caching`, `fast_mode` and `tools`.- `streamingResponseStateful` keeps conversation history inside the client; manage it with `getHistory()` / `setHistory(history)` / `clearHistory()`. The stateless variant is `streamingResponse({ messages, config })`.## Config parameters the model may reject@@ -132,10 +141,11 @@ try {}```-- `thinking_level` never throws: every client maps each level onto the closest one the model supports. Kimi K3 reasons unconditionally, so `NONE` degrades to its lowest effort rather than disabling thinking; GLM-5.2 sends `reasoning_effort` alongside its `thinking` block and only `NONE` disables it.-- `temperature` is rejected outright by Gemini 3.6 — that generation deprecated the sampling parameters, so the client refuses them instead of sending a value the API ignores. GPT-5.5, Claude 4.8/5, DeepSeek V4, Kimi K2.6 and Kimi K3 accept only the protocol default `1.0` and reject any other value. Gemini 3, Claude 4.6, GLM and the generic OpenAI client pass it through.-- `tool_choice`: `"auto"` is safe everywhere. Claude accepts a single forced tool name; DeepSeek V4 and Kimi K2.6 allow `"auto"` / `"none"`; Kimi K3 adds `"required"` but refuses a specific tool; GLM only accepts `"auto"`.+- `thinking_level` never throws: every client maps each level onto the closest one the model supports. Kimi K3 reasons unconditionally, so `NONE` degrades to its lowest effort rather than disabling thinking; GLM-5.2 sends `reasoning_effort` alongside its `thinking` block and only `NONE` disables it. GLM-5.3 thinks unconditionally (`NONE` degrades to the light `low` effort) and clamps `reasoning_effort` to `low`/`high`/`max`; `gemini-3.7-*` clamps to `low`/`medium`/`high` (`NONE` degrades to `low`).+- `temperature` is rejected outright by Gemini 3.6/3.7 — those generations deprecated the sampling parameters, so the client refuses them instead of sending a value the API ignores. GPT-5.5/5.6, the whole Claude 4.6+ family (4.6 included since AgentHub 0.4.2), DeepSeek V4, Kimi K2.6 and Kimi K3 accept only the protocol default `1.0` and reject any other value. Gemini 3, GLM and the generic protocol clients (`openai-chat` / `openai-responses` / `ant-messages`) pass it through.+- `tool_choice`: `"auto"` is safe everywhere. Claude accepts a single forced tool name; DeepSeek V4 and Kimi K2.6 allow `"auto"` / `"none"`; Kimi K3 adds `"required"` but refuses a specific tool (K2.x also rejects `"required"`); GLM only accepts `"auto"`.- `prompt_caching`: every client accepts `PromptCaching.ENABLE` and rejects the other values — caching is on by default and Kimi K3 caches context automatically.+- `fast_mode` (`UniConfig`, AgentHub 0.4.2): fast processing at premium pricing. OpenAI-protocol clients (`openai-chat`, `openai-responses`, `gpt-5.6`, `minimax-m3`) map it to `service_tier: "priority"`; Anthropic-protocol clients (`ant-messages`, `claude-5`) map it to `speed: "fast"` with a beta header (an Anthropic research preview limited to Claude Opus 5 / Opus 4.8 — organizations without access get a 429). Clients without a fast tier (Gemini, GLM, Kimi, DeepSeek, embeddings, Claude 4.6 models) raise `UnsupportedParameterError`; DeepSeek and Z.AI's OpenAI-compatible endpoints simply ignore the tier.Leave a parameter unset and the protocol default applies, which is the portable choice when a script must run against several families.diff --git a/packages/web/src/features/models/models-page.tsx b/packages/web/src/features/models/models-page.tsxindex 1f0f04af..4a4816fc 100644--- a/packages/web/src/features/models/models-page.tsx+++ b/packages/web/src/features/models/models-page.tsx@@ -64,6 +64,7 @@ import { EmptyState } from "../../components/ui/empty-state";import { formatDateTime, humanizeTokens } from "../../lib/format";import {MODEL_PROVIDERS,+ canonicalClientType,catalogEntryFor,modelHomepageUrl,providerInfo,@@ -158,9 +159,9 @@ export function decimalOnly(v: string): string {return i === -1 ? cleaned : cleaned.slice(0, i + 1) + cleaned.slice(i + 1).replace(/\./g, "");}-/** Moving an existing model to Custom switches it to the OpenAI-compatible client. */+/** Moving an existing model to Custom switches it to the generic OpenAI Chat Completions client. */export function clientTypeAfterProviderChange(provider: string, current: string): string {- return provider === "custom" ? "openai" : current;+ return provider === "custom" ? "openai-chat" : current;}/** Local edit state for one model row (string-typed for form use; parsed uniformly on save). */@@ -194,7 +195,7 @@ export interface RowState {contextWindow: string;/** Per-model max output tokens ("" = inherit the Agent setting): caps output per request; user-only, never preset by the catalog. */maxTokens: string;- /** AgentHub client protocol: defaults for preset models (auto-routed), "openai" for new custom models; kept as-is, not user-editable. */+ /** AgentHub client protocol: defaults for preset models (auto-routed), "openai-chat" for new custom models; kept as-is, not user-editable. */clientType: string;cacheRead: string;cacheWrite: string;@@ -1074,7 +1075,7 @@ function ModelDialog({// New model: protocol follows group semantics — a first-party vendor group// doesn't persist client_type (AgentHub auto-routes by upstream id, with env fallback// resolved live from the id); custom / user-defined groups / gateways use a fixed- // openai protocol (env fallback OPENAI_*), and gateways additionally pre-fill their+ // openai-chat protocol (env fallback OPENAI_*), and gateways additionally pre-fill their// endpoint base URL. provider keeps the entry point's original value (a user-defined// group must not collapse into custom), stored as a separate field from model_id, with// no concatenation on save.@@ -1088,7 +1089,7 @@ function ModelDialog({vision: true,contextWindow: "",maxTokens: "",- clientType: vendorAdd ? "" : "openai",+ clientType: vendorAdd ? "" : "openai-chat",cacheRead: "",cacheWrite: "",output: "",@@ -1724,12 +1725,17 @@ function ModelDialog({{/* 5) Identity: model id (renamable) + display name and group (side by side) */}{!isNew && identityFields}- {/* Legacy entries carrying a non-openai client_type (historical config): read-only display. */}- {!isNew && !preset && form.clientType && form.clientType !== "openai" && (- <p className="text-xs text-gray-400 dark:text-gray-500">- {S.models.clientTypeLocked(form.clientType)}- </p>- )}+ {/* Legacy entries carrying a client_type other than the standard openai-chat+ (historical config): read-only display. Compared canonically so the deprecated+ bare "openai" spelling (pre-0.4.2 configs) is not flagged as legacy either. */}+ {!isNew &&+ !preset &&+ form.clientType &&+ canonicalClientType(form.clientType) !== "openai-chat" && (+ <p className="text-xs text-gray-400 dark:text-gray-500">+ {S.models.clientTypeLocked(form.clientType)}+ </p>+ )}{/* Vision capability: for preset models it's flagged by the built-in catalog (read-only);custom models toggle it here — an iOS-style switch sitting inline right next to thediff --git a/packages/web/src/features/models/protocol-path.ts b/packages/web/src/features/models/protocol-path.tsindex d7b12f1f..3573a77a 100644--- a/packages/web/src/features/models/protocol-path.ts+++ b/packages/web/src/features/models/protocol-path.ts@@ -1,26 +1,29 @@/*** Protocol-path suffix for the config dialog's base URL field: the path the AgentHub* client appends to a custom base URL, shown inside the field so the user knows which- * endpoint shape the URL must serve. Verified against the vendored agenthub 0.4.1+ * endpoint shape the URL must serve. Verified against the vendored agenthub 0.4.2* clients and the SDKs they construct:* - Anthropic direct (claude-* clients, `@anthropic-ai/sdk`): POST {base}/v1/messages —* the SDK's default base URL (https://api.anthropic.com) carries no /v1; the request- * path does, so a custom base URL gains the full /v1/messages.+ * path does, so a custom base URL gains the full /v1/messages. The generic Anthropic+ * Messages protocol client (`client_type: "ant-messages"`) serves the same shape.* - OpenAI direct (gpt-* clients): the Responses API, POST {base}/responses (the SDK's* default base URL https://api.openai.com/v1 already ends in /v1, and a custom base- * URL replaces it whole).+ * URL replaces it whole). The generic Responses protocol client+ * (`client_type: "openai-responses"`) serves the same shape.* - Google direct (gemini-* clients, `@google/genai`): {base}/v1beta/models/<id>:… —* the SDK joins base URL + API version (v1beta) + the models path.* - MiniMax direct (minimax-m3 client): MiniMax's Responses API, POST {base}/responses* (its default base URL https://api.minimax.io/v1 already ends in /v1).- * - Every OpenAI-compatible client — explicit `client_type: "openai"` (gateways,- * custom and user-defined groups) plus the DeepSeek / GLM / Kimi direct clients —- * POST {base}/chat/completions.+ * - Every OpenAI Chat Completions compatible client — explicit+ * `client_type: "openai-chat"` (gateways, custom and user-defined groups; the bare+ * "openai" spelling is a deprecated pre-0.4.2 alias) plus the DeepSeek / GLM / Kimi+ * direct clients — POST {base}/chat/completions.*//*** The protocol path appended to the base URL for a model entry. An explicit client- * type wins over group membership (a `client_type: "openai"` entry inside a vendor+ * type wins over group membership (a `client_type: "openai-chat"` entry inside a vendor* group still goes through the generic OpenAI-compatible client); with no client type* the entry is auto-routed within its vendor group, so the group implies the client* family. Pure display logic: the empty-input hint must work before anything is typed,@@ -28,6 +31,11 @@*/export function protocolPathForModel(provider: string, clientType: string): string {const t = clientType.trim().toLowerCase();+ // The generic protocol clients (agenthub 0.4.2): checked before the substring matches+ // below — "openai-responses" also contains "openai" but speaks the Responses API.+ if (t.includes("ant-messages")) return "/v1/messages";+ if (t.includes("openai-responses")) return "/responses";+ // openai-chat / openai-embedding / the deprecated bare "openai" alias.if (t.includes("openai")) return "/chat/completions";// Legacy explicit client types (historical config): pin the family like auto-routing would.if (t.includes("claude")) return "/v1/messages";diff --git a/packages/web/test/catalog-sync.test.ts b/packages/web/test/catalog-sync.test.tsindex 739d3273..28f63a73 100644--- a/packages/web/test/catalog-sync.test.ts+++ b/packages/web/test/catalog-sync.test.ts@@ -46,7 +46,7 @@ const PRESET: PresetEntry[] = [provider: "qwen-token-plan",model_id: "glm-5.2",context_window: 1048576,- client_type: "openai",+ client_type: "openai-chat",pricing: { unit: "usd_per_mtok", cache_read: 0.285714, cache_write: 1.142857, output: 4 },vision: false,base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",@@ -56,7 +56,7 @@ const PRESET: PresetEntry[] = [provider: "qwen-token-plan",model_id: "qwen3.8-max-preview",context_window: 1000000,- client_type: "openai",+ client_type: "openai-chat",base_url: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",},];@@ -68,7 +68,7 @@ describe("syncRowsWithCatalog", () => {expect(updated).toBe(0);const glm = rows.find((r) => r.provider === "qwen-token-plan" && r.modelId === "glm-5.2")!;expect(glm.original).toBeNull();- expect(glm.clientType).toBe("openai");+ expect(glm.clientType).toBe("openai-chat");expect(glm.baseUrl).toBe("https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1");expect(glm.originalBaseUrl).toBe(""); // differs from baseUrl -> the PUT submits the preset URLexpect(glm.cacheRead).toBe("0.285714");@@ -148,7 +148,7 @@ describe("syncRowsWithCatalog", () => {provider: "qwen-token-plan",modelId: "qwen3.8-max-preview",contextWindow: "1000000",- clientType: "openai",+ clientType: "openai-chat",baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",cacheRead: "1",cacheWrite: "2",diff --git a/packages/web/test/models-input.test.ts b/packages/web/test/models-input.test.tsindex df174a51..1640b24e 100644--- a/packages/web/test/models-input.test.ts+++ b/packages/web/test/models-input.test.ts@@ -43,10 +43,10 @@ describe("decimalOnly (price)", () => {});describe("clientTypeAfterProviderChange", () => {- it("uses openai when moving to Custom and otherwise preserves the current client", () => {- expect(clientTypeAfterProviderChange("custom", "")).toBe("openai");- expect(clientTypeAfterProviderChange("custom", "claude-5")).toBe("openai");- expect(clientTypeAfterProviderChange("google", "openai")).toBe("openai");+ it("uses openai-chat when moving to Custom and otherwise preserves the current client", () => {+ expect(clientTypeAfterProviderChange("custom", "")).toBe("openai-chat");+ expect(clientTypeAfterProviderChange("custom", "claude-5")).toBe("openai-chat");+ expect(clientTypeAfterProviderChange("google", "openai-chat")).toBe("openai-chat");});});diff --git a/packages/web/test/protocol-path.test.ts b/packages/web/test/protocol-path.test.tsindex b0b3db57..ffb8b123 100644--- a/packages/web/test/protocol-path.test.ts+++ b/packages/web/test/protocol-path.test.ts@@ -27,7 +27,7 @@ describe("protocolPathForModel", () => {expect(protocolPathForModel("moonshot", "")).toBe("/chat/completions");});- it("gateway groups always carry client_type openai and get /chat/completions", () => {+ it("gateway groups always carry client_type openai-chat and get /chat/completions", () => {for (const provider of ["openrouter","fireworks",@@ -35,19 +35,33 @@ describe("protocolPathForModel", () => {"qwen-token-plan","qwen-pay-as-you-go",]) {- expect(protocolPathForModel(provider, "openai")).toBe("/chat/completions");+ expect(protocolPathForModel(provider, "openai-chat")).toBe("/chat/completions");}});it("custom and user-defined groups get /chat/completions (with or without the explicit client type)", () => {+ expect(protocolPathForModel("custom", "openai-chat")).toBe("/chat/completions");+ // The deprecated bare "openai" alias (configs saved before AgentHub 0.4.2) means the same client.expect(protocolPathForModel("custom", "openai")).toBe("/chat/completions");// Legacy TOML entries in a user-defined group may lack client_type; the group still means the OpenAI protocol.expect(protocolPathForModel("myproxy", "")).toBe("/chat/completions");});- it("an explicit openai client type wins over vendor-group membership", () => {- expect(protocolPathForModel("anthropic", "openai")).toBe("/chat/completions");- expect(protocolPathForModel("google", "openai")).toBe("/chat/completions");+ it("an explicit openai-chat client type wins over vendor-group membership", () => {+ expect(protocolPathForModel("anthropic", "openai-chat")).toBe("/chat/completions");+ expect(protocolPathForModel("google", "openai-chat")).toBe("/chat/completions");+ });++ it("the generic protocol clients (agenthub 0.4.2) map to their own endpoint shapes", () => {+ // openai-responses contains "openai" but speaks the Responses API; ant-messages speaks+ // the Anthropic Messages API — both must win over the generic openai substring match.+ expect(protocolPathForModel("custom", "openai-responses")).toBe("/responses");+ expect(protocolPathForModel("custom", "ant-messages")).toBe("/v1/messages");+ expect(protocolPathForModel("deepseek", "openai-responses")).toBe("/responses");+ expect(protocolPathForModel("myproxy", " Ant-Messages ")).toBe("/v1/messages");+ // The built-in OpenRouter openai/* presets pin openai-responses, so the gateway's base+ // URL must be hinted with /responses rather than the group's usual /chat/completions.+ expect(protocolPathForModel("openrouter", "openai-responses")).toBe("/responses");});it("legacy explicit client types pin the family like auto-routing would", () => {