Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(models): per-model fast mode, gated on client support (#326)

Yaowei Zheng35feb6dba092
diff --git a/changelog/unreleased/2026-08-18-model-fast-mode.md b/changelog/unreleased/2026-08-18-model-fast-mode.md
new file mode 100644
index 00000000..155289af
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-model-fast-mode.md
@@ -0,0 +1,42 @@
+# Per-model fast mode
+
+- **Date:** 2026-08-18
+- **Type:** feature
+- **Scope:** `core`, `server`, `web`, `cli`, `model-catalog`
+- **PR:** [#326](https://github.com/Prism-Shadow/penguin-harness/pull/326)
+
+[中文版](2026-08-18-model-fast-mode.zh.md)
+
+Model entries gained an optional fast-mode setting that opts a model's session requests into the provider's faster serving tier at premium pricing, carried by AgentHub's UniConfig `fast_mode` (agenthub [#171](https://github.com/Prism-Shadow/agenthub/pull/171)): OpenAI-protocol clients send `service_tier: "priority"`, Anthropic-protocol clients send `speed: "fast"` with the fast-mode beta header. It defaults off and only `true` is ever persisted (`fast_mode = true` on the entry), so existing configs were left untouched. The toggle is offered only on models whose resolved AgentHub client can actually serve fast mode, turning it on asks for confirmation first because of the premium billing, and a model that rejects the parameter anyway fails the run immediately with an actionable message instead of retrying.
+
+## Core
+
+`fastModeProtocol(modelId, clientType?, baseUrl?)` (`state/model-catalog.ts`, beside `resolveModelEnv`) answers whether a model can carry fast mode at all and on which protocol — `"openai"` for the clients that send `service_tier`, `"anthropic"` for those that send `speed`, `undefined` for the rest. It mirrors AgentHub's `AutoLLMClient` branch order rather than listing models, so catalog rows added later inherit the right answer: routing reads `client_type` or, when unset, the model id (which does not always agree with the provider group), and the two claude5 carve-outs — a `bedrock://` base URL and any id containing `4-6` — are checked against the raw entry, matching the client. Ids AgentHub cannot route report `undefined` too: no client, no fast tier.
+
+`ModelEntry.fast_mode` flows through `GenerativeModelConfig.fastMode` into `buildUniConfig`, which sets `UniConfig.fast_mode` only when enabled — the key stays off the wire otherwise. It rides the session LLM, compaction rebuilds included; the bare/meta LLM (title generation) and the `describe_image` vision describer were left off it, so those background requests keep working while the annotation is enabled on a model that rejects it.
+
+AgentHub clients without a fast tier (Gemini, GLM, Kimi, DeepSeek, `openai_embedding`, and claude5 on Bedrock or Claude 4.6 ids) throw `UnsupportedParameterError` before any network I/O. `GenerativeModel` detects that one deterministic rejection — scoped to `parameter === "fast_mode"`, and only when its own config enabled fast mode — and reports `failed` with a new `LLMOutcome.permanent: true` hint plus a message naming the fix ("… turn it off in the model settings …"). The engine aborts the run immediately on a permanent failure, the same terminal handling as `auth` but without gating input, and announces no retry countdown for it. Every other failure keeps the retry-everything-but-auth policy unchanged.
+
+## Server
+
+`ModelInfo` / `ModelUpdateEntry` gained `fastMode`: GET reports `true` only for an annotated entry, and PUT persists only `true`, so an omitted or `false` field clears the annotation under the full-table replace semantics. `POST /models/test` accepts a `fastMode` override that falls back to the stored annotation, so the connectivity test exercises exactly the serving tier sessions would use and surfaces a fast-mode rejection before saving.
+
+## Web App
+
+The model dialog gained a "Fast mode" toggle, default off, rendered only for models whose routed AgentHub client can serve it — `fastModeState` recomputes from the live form, so editing the id, protocol or base URL updates it as it is typed. A custom or user-defined group is resolved through the protocol its entry will be saved with (`protocolForPersist`) rather than by model id, so a group that persists on the compatible client keeps the switch whatever upstream id is typed into it, while preset and vendor groups stay on AgentHub's id routing. It takes the same inline-switch shape as the vision toggle and shares one row with it, in the two-up grid the dialog already uses for the context-window and max-output-tokens fields, with a hint line while ON (and as the label's hover title) saying it is faster output at premium pricing and that the recorded prices stay standard. Neither switch is guaranteed to be present — vision is read-only catalog metadata on preset models and fast mode is withheld wherever the client rejects it — so the row is dropped when neither applies, and whichever one remains spans the full width instead of sitting in a half-width cell (`capabilityRow`).
+
+Switching it **on** raises a confirmation first (the shared `ConfirmModal`, stacked on the dialog like the save and remove ones): the premium billing — MiniMax at 1.5x standard, separate premium price lists at OpenAI and Anthropic — the entry's recorded per-token prices not following it, so the Cost center under-reports the usage, and for Anthropic-protocol models that fast mode there is a limited research preview returning 429 until the organization is granted access. Switching it **off** stays one click, and a row that already stores `fast_mode = true` keeps its switch even where the rule would not have offered one, marked unsupported, so the runtime message's "turn it off in the model settings" holds.
+
+A model with fast mode on is badged in the model list. The connectivity test sends the form's current toggle state, catalog sync treats fast mode as user-owned and never clobbers it, and the strings ship in both locales.
+
+## CLI
+
+`penguin config model add` gained tri-state `--fast-mode` / `--no-fast-mode`: neither flag keeps the current value, and `--no-fast-mode` clears the stored annotation rather than writing `false`. Enabling it on a model whose client rejects the parameter still writes the entry and warns on stderr, naming `--no-fast-mode` — an entry can point at an endpoint whose capability is not visible from the config.
+
+## Docs
+
+The bilingual models page gained a "Fast mode" section: the semantics, the premium pricing that the recorded per-token prices do not reflect, a per-client support table with the routing rule that produces it, the two things the toggle cannot check (Anthropic's research-preview 429, and `CLIENT_TYPE` / `ANTHROPIC_BASE_URL` overriding the entry from the server's environment), and the excluded background requests. The configuration, CLI, web-app and interfaces pages documented the new field, the flags, the toggle and its confirmation, and `LLMOutcome.permanent`.
+
+## Cost reporting
+
+Nothing records the serving tier on a usage record, and cost stays computed at query time from the entry's single price triple, so while fast mode is on every cost surface — usage cards, the trend, the chat header chip, the trace viewer — under-reports that model's spend. Per-tier pricing was left for a follow-up; the confirmation and the models page state the gap instead.
diff --git a/changelog/unreleased/2026-08-18-model-fast-mode.zh.md b/changelog/unreleased/2026-08-18-model-fast-mode.zh.md
new file mode 100644
index 00000000..e9847c72
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-model-fast-mode.zh.md
@@ -0,0 +1,42 @@
+# 按模型设置的快速模式
+
+- **Date:** 2026-08-18
+- **Type:** feature
+- **Scope:** `core`, `server`, `web`, `cli`, `model-catalog`
+- **PR:** [#326](https://github.com/Prism-Shadow/penguin-harness/pull/326)
+
+[English](2026-08-18-model-fast-mode.md)
+
+模型条目新增一项可选的快速模式设置:开启后,该模型的会话请求进入厂商更快的推理档位,按溢价计费,由 AgentHub 的 UniConfig `fast_mode` 承载(agenthub [#171](https://github.com/Prism-Shadow/agenthub/pull/171))——OpenAI 协议 client 发送 `service_tier: "priority"`,Anthropic 协议 client 发送 `speed: "fast"` 并附带 fast-mode beta 请求头。默认关闭,且只会持久化 `true`(条目上的 `fast_mode = true`),既有配置不受影响。开关只在模型所解析出的 AgentHub client 确实能提供快速档位时才出现;打开它会先要求确认,因为快速模式按溢价计费;而模型若仍然拒绝这个参数,本次运行会立即失败并给出可操作的提示,而不是继续重试。
+
+## Core
+
+`fastModeProtocol(modelId, clientType?, baseUrl?)`(`state/model-catalog.ts`,与 `resolveModelEnv` 相邻)回答一个模型究竟能否携带快速模式、以及走哪种协议——发送 `service_tier` 的那些 client 返回 `"openai"`,发送 `speed` 的返回 `"anthropic"`,其余返回 `undefined`。它不是列举模型,而是照搬 AgentHub 中 `AutoLLMClient` 的分支顺序,因此日后新增的目录条目能自动得到正确答案:路由先看 `client_type`,未设置时看 model id(后者与 Provider 分组并不总是一致),claude5 的两处例外——`bedrock://` 的 base URL,以及 id 中含 `4-6`——则与 client 一样,对着原始条目判定。AgentHub 根本无法路由的 id 同样返回 `undefined`:没有 client,就没有快速档位。
+
+`ModelEntry.fast_mode` 经 `GenerativeModelConfig.fastMode` 传入 `buildUniConfig`,只有在开启时才写入 `UniConfig.fast_mode`——否则这个字段根本不会出现在请求里。它跟随会话 LLM,压缩重建也包含在内;裸 LLM / meta LLM(标题生成)与 `describe_image` 代读则不带它,因此当注解开在一个会拒绝该参数的模型上时,这些后台请求照常工作。
+
+没有快速档位的 AgentHub client(Gemini、GLM、Kimi、DeepSeek、`openai_embedding`,以及走 Bedrock 或 Claude 4.6 id 的 claude5)会在任何网络 I/O 之前抛出 `UnsupportedParameterError`。`GenerativeModel` 能识别这一种确定性的拒绝——限定在 `parameter === "fast_mode"`,且仅当自身配置开启了快速模式时——并以 `failed` 上报,附带新增的 `LLMOutcome.permanent: true` 标记,以及一句点明处理方式的提示("… turn it off in the model settings …")。引擎遇到永久性失败会立即中止本次运行,终止方式与 `auth` 相同,但不会锁住输入,也不再播报重试倒计时。其余失败仍沿用「除 auth 外一律重试」的策略。
+
+## Server
+
+`ModelInfo` / `ModelUpdateEntry` 新增 `fastMode`:GET 只对带有该注解的条目返回 `true`,PUT 也只持久化 `true`,因此在整表替换的语义下,省略该字段或传 `false` 即为清除注解。`POST /models/test` 接受 `fastMode` 覆盖值,未传时回退到已存的注解,于是连通性测试所走的档位与会话请求完全一致,能在保存前暴露快速模式被拒的问题。
+
+## Web App
+
+模型对话框新增「快速模式」开关,默认关闭,且只对路由后的 AgentHub client 能提供该档位的模型渲染——`fastModeState` 依表单的实时取值重算,因此编辑 id、协议或 base URL 时,开关会随输入即时增减。自定义分组与用户自建分组按条目实际保存时所用的协议判定(`protocolForPersist`),而不按 model id 判定:这类分组保存在通用 client 上,因此无论往里填什么上游 id,开关都会保留;预设分组与厂商分组则仍沿用 AgentHub 的 id 路由。它与视觉开关采用同样的行内 switch 形态,并与之共处一行——用的就是对话框里上下文窗口与最大输出 Token 那对字段已有的两列栅格;处于开启状态时带一行提示(同时作为标签的悬停 title),说明这是以溢价换更快的输出,而条目记录的价格仍按标准档。两个开关都不是一定会出现的:预设模型的视觉标记来自内置目录,只读不可改;快速模式则在 client 不接受该参数时不予提供。因此两个都不适用时整行不渲染,只剩一个时它独占整行宽度,而不是缩在半格里(`capabilityRow`)。
+
+**打开**它会先弹出确认(复用共享的 `ConfirmModal`,与保存、删除一样叠在对话框之上):溢价计费——MiniMax 为标准价的 1.5 倍,OpenAI 与 Anthropic 另有溢价价目表——条目记录的按 Token 单价不会随之调整,因此成本中心会低估这部分用量;Anthropic 协议的模型还会多一条提示:那边的快速模式是限量的 research preview,在组织获得授权之前请求会返回 429。**关闭**它仍是一键完成;而已经存有 `fast_mode = true` 的条目,即便按规则本不该出现开关也会保留它,并标注为不受支持,好让运行时那句「turn it off in the model settings」始终成立。
+
+模型列表中,开启了快速模式的模型带有角标。连通性测试发送对话框当前的开关状态;预设同步把快速模式视为用户所有,从不覆盖;相关文案中英文都已提供。
+
+## CLI
+
+`penguin config model add` 新增三态的 `--fast-mode` / `--no-fast-mode`:两个都不给则保持原值,`--no-fast-mode` 是清除已存的注解,而不是写入 `false`。若在一个 client 会拒绝该参数的模型上开启,命令仍会写入条目,但在 stderr 上给出警告并点名 `--no-fast-mode`——条目完全可能指向一个从配置里看不出其能力的端点。
+
+## Docs
+
+中英文模型页新增「快速模式」小节:语义、条目记录的按 Token 单价并不反映的溢价计费、按 client 划分的支持情况表格及其背后的路由规则、开关无法替你检查的两件事(Anthropic 的 research preview 429,以及服务端环境变量 `CLIENT_TYPE` / `ANTHROPIC_BASE_URL` 会覆盖条目配置),以及被排除在外的后台请求。configuration、CLI、web-app 与 interfaces 各页也记录了新增字段、命令行参数、开关及其确认弹窗,还有 `LLMOutcome.permanent`。
+
+## 成本统计
+
+用量记录里没有任何字段记下请求实际走的档位,成本仍在查询时依条目那一组三档价格计算,因此只要快速模式处于开启状态,各处成本展示——用量卡片、趋势图、对话头部的成本小标、Trace 查看器——都会低估该模型的花费。按档位定价留待后续处理;当前由确认弹窗与模型文档把这一缺口说明清楚。
diff --git a/packages/cli/src/commands/config.ts b/packages/cli/src/commands/config.ts
index 2d5f976a..4942651c 100644
--- a/packages/cli/src/commands/config.ts
+++ b/packages/cli/src/commands/config.ts
@@ -40,6 +40,7 @@ import {
type ProjectConfig,
addModel,
catalogEntryFor,
+ fastModeProtocol,
formatModelRef,
getModel,
loadAgentVault,
@@ -129,6 +130,9 @@ export function registerConfigCommand(program: Command, t: Messages): void {
// Tri-state: --vision marks it supported / --no-vision marks it unsupported / neither given keeps the existing value (defaults to supported).
.option("--vision", t.config.addVision)
.option("--no-vision", t.config.addNoVision)
+ // Tri-state like --vision: --fast-mode enables it / --no-fast-mode clears it / neither keeps the existing value (defaults to off; only `true` is persisted).
+ .option("--fast-mode", t.config.addFastMode)
+ .option("--no-fast-mode", t.config.addNoFastMode)
.option("--price-cache-read <n>", t.config.addPriceCacheRead, parseFloatArg)
.option("--price-cache-write <n>", t.config.addPriceCacheWrite, parseFloatArg)
.option("--price-output <n>", t.config.addPriceOutput, parseFloatArg)
@@ -182,6 +186,7 @@ export function registerConfigCommand(program: Command, t: Messages): void {
...(maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
...(clientType !== undefined ? { client_type: clientType } : {}),
...(opts.vision !== undefined ? { vision: opts.vision } : {}),
+ ...(opts.fastMode !== undefined ? { fast_mode: opts.fastMode } : {}),
...(Object.keys(pricing).length > 0 ? { pricing } : {}),
...(opts.apiKey !== undefined ? { api_key: opts.apiKey } : {}),
...(baseUrl !== undefined ? { base_url: baseUrl } : {}),
@@ -193,6 +198,19 @@ export function registerConfigCommand(program: Command, t: Messages): void {
? t.modelUpdated(formatModelRef(ref), defaultRef)
: t.modelAdded(formatModelRef(ref), defaultRef);
process.stdout.write(`${line}\n`);
+ // Fast mode on a model whose AgentHub client cannot carry it makes every session
+ // request fail. The Web dialog does not offer the switch there at all, so this flag is
+ // the remaining way into that state: warn rather than silently write a config that only
+ // reveals itself at request time. A warning, not a refusal — the entry may point at an
+ // endpoint whose capability we cannot see from here (see fastModeProtocol).
+ const saved = getModel(cfg, ref);
+ if (
+ opts.fastMode === true &&
+ saved !== undefined &&
+ fastModeProtocol(saved.model_id, saved.client_type, saved.base_url) === undefined
+ ) {
+ process.stderr.write(`${t.config.fastModeUnsupported(formatModelRef(ref))}\n`);
+ }
});
model
diff --git a/packages/cli/src/i18n.ts b/packages/cli/src/i18n.ts
index 95390fd1..56d8ae02 100644
--- a/packages/cli/src/i18n.ts
+++ b/packages/cli/src/i18n.ts
@@ -52,6 +52,9 @@ export interface Messages {
addClientType: string;
addVision: string;
addNoVision: string;
+ addFastMode: string;
+ addNoFastMode: string;
+ fastModeUnsupported: (ref: string) => string;
addPriceCacheRead: string;
addPriceCacheWrite: string;
addPriceOutput: string;
@@ -362,6 +365,11 @@ const en: Messages = {
"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",
+ addFastMode:
+ "Enable fast mode: faster output at premium pricing (models without a fast tier reject requests carrying it)",
+ addNoFastMode: "Disable fast mode (the default); omit both to keep current",
+ fastModeUnsupported: (ref: string): string =>
+ `Warning: ${ref} cannot serve fast mode — AgentHub's client for it rejects the parameter, so its requests will fail. Re-run with --no-fast-mode to turn it off.`,
addPriceCacheRead: "Price per 1M tokens: cache read (USD)",
addPriceCacheWrite: "Price per 1M tokens: cache write (USD)",
addPriceOutput: "Price per 1M tokens: output (USD)",
@@ -635,6 +643,10 @@ const zh: Messages = {
addClientType: "AgentHub 客户端协议(如 openai-chat);缺省按 provider 分组的语义取值",
addVision: "标注该模型支持图片输入(视觉)",
addNoVision: "标注该模型不支持图片输入;两者都不给则保留原值",
+ addFastMode: "开启快速模式:输出更快、按溢价计费(不支持 fast 档位的模型会拒绝请求)",
+ addNoFastMode: "关闭快速模式(缺省即关闭);两者都不给则保留原值",
+ fastModeUnsupported: (ref: string): string =>
+ `警告:${ref} 不支持快速模式——AgentHub 为它选用的 client 会拒绝该参数,其请求都会失败。请用 --no-fast-mode 重新执行以关闭。`,
addPriceCacheRead: "每百万 token 价格:缓存读取(USD)",
addPriceCacheWrite: "每百万 token 价格:缓存写入(USD)",
addPriceOutput: "每百万 token 价格:输出(USD)",
diff --git a/packages/cli/test/config-model.test.ts b/packages/cli/test/config-model.test.ts
index 6967173e..f963f6e0 100644
--- a/packages/cli/test/config-model.test.ts
+++ b/packages/cli/test/config-model.test.ts
@@ -303,6 +303,92 @@ describe("penguin config model add/list (--root plus provider / model_id stored
expect((await entryOf())?.max_tokens).toBe(8000);
});
+ it("--fast-mode round-trips as fast_mode=true; --no-fast-mode clears it; neither keeps current", async () => {
+ const entryOf = async () => {
+ const parsed = parseToml(
+ await fs.readFile(projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID), "utf8"),
+ ) as { models: Array<Record<string, unknown>> };
+ return parsed.models.find((m) => m.provider === "custom" && m.model_id === "fast-1");
+ };
+ const add = await runModel([
+ "add",
+ "--model-id",
+ "fast-1",
+ "--provider",
+ "custom",
+ "--base-url",
+ "http://127.0.0.1:8000/v1",
+ "--fast-mode",
+ "--root",
+ tmpRoot,
+ ]);
+ expect(add.code).toBe(0);
+ expect((await entryOf())?.fast_mode).toBe(true);
+
+ // Upsert without either flag keeps the annotation (same merge policy as --vision).
+ const keep = await runModel([
+ "add",
+ "--model-id",
+ "fast-1",
+ "--provider",
+ "custom",
+ "--context-window",
+ "32768",
+ "--root",
+ tmpRoot,
+ ]);
+ expect(keep.code).toBe(0);
+ expect((await entryOf())?.fast_mode).toBe(true);
+
+ // --no-fast-mode clears the stored annotation entirely: only `true` is ever persisted
+ // (absent = off), so no `fast_mode = false` is written either.
+ const off = await runModel([
+ "add",
+ "--model-id",
+ "fast-1",
+ "--provider",
+ "custom",
+ "--no-fast-mode",
+ "--root",
+ tmpRoot,
+ ]);
+ expect(off.code).toBe(0);
+ expect("fast_mode" in ((await entryOf()) ?? {})).toBe(false);
+ });
+
+ it("--fast-mode on a model whose client rejects it warns on stderr but still writes", async () => {
+ // The Web dialog withholds the switch entirely for these models, so the flag is the way
+ // into a config that fails every request; it stays a warning rather than a refusal
+ // because an entry may point at an endpoint whose capability is not visible from here.
+ const warned = await runModel([
+ "add",
+ "--model-id",
+ "kimi-k3",
+ "--provider",
+ "moonshot",
+ "--fast-mode",
+ "--root",
+ tmpRoot,
+ ]);
+ expect(warned.code).toBe(0);
+ expect(warned.err).toContain("cannot serve fast mode");
+ expect(warned.err).toContain("--no-fast-mode");
+
+ // A model that can serve it is written without any warning.
+ const quiet = await runModel([
+ "add",
+ "--model-id",
+ "claude-fable-5",
+ "--provider",
+ "anthropic",
+ "--fast-mode",
+ "--root",
+ tmpRoot,
+ ]);
+ expect(quiet.code).toBe(0);
+ expect(quiet.err).toBe("");
+ });
+
it("model default sets the default model under the --root data root (--model-id upstream id + --provider as a pair)", async () => {
const set = await runModel([
"default",
diff --git a/packages/core/src/agent.ts b/packages/core/src/agent.ts
index 385eb100..3e0d361a 100644
--- a/packages/core/src/agent.ts
+++ b/packages/core/src/agent.ts
@@ -851,6 +851,12 @@ export class Agent {
? { contextWindow: modelEntry.context_window }
: {}),
...(maxTokens !== undefined ? { maxTokens } : {}),
+ // Fast mode is a session-request annotation: it rides llmConfig (and therefore the
+ // post-compaction rebuild), while the bare/meta LLM below and the vision describer
+ // deliberately skip it — their background requests gain nothing user-facing from a
+ // premium tier, and skipping keeps them working (titles included) even while the
+ // annotation is enabled on a model that rejects it.
+ ...(modelEntry.fast_mode === true ? { fastMode: true } : {}),
...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
...(this.state.systemConfig.model?.timeoutMs !== undefined
? { requestTimeoutMs: this.state.systemConfig.model.timeoutMs }
diff --git a/packages/core/src/engine/context-engine.ts b/packages/core/src/engine/context-engine.ts
index 82b2ffe7..8d2e64f4 100644
--- a/packages/core/src/engine/context-engine.ts
+++ b/packages/core/src/engine/context-engine.ts
@@ -360,7 +360,9 @@ function downgradeCarriedGoalInput(msg: OmniMessage): OmniMessage {
/**
* LLM outcomes that reconnect in-run — everything but `auth`, which cannot be retried into
- * working. `failed` is included on purpose: the classifier producing it is an allowlist of
+ * working, and a `failed` carrying `permanent: true` (a deterministic client-side rejection,
+ * see LLMOutcome.permanent), which the turn loop aborts on before consulting this set.
+ * `failed` is otherwise included on purpose: the classifier producing it is an allowlist of
* known transport codes and message vocabulary, so a gateway phrasing a transient fault its
* own way lands here; retrying a genuinely permanent error costs the ladder and ends the same
* way, while aborting a transient one destroys the turn.
@@ -675,6 +677,18 @@ export class ContextEngine {
yield* this.emitAbort(`llm request error: ${turn.outcome.errorMessage ?? "unknown"}`);
return;
}
+ // A permanent `failed` is the other non-retried terminal: a deterministic
+ // client-side rejection thrown before any network I/O (fast_mode on a model
+ // without a fast tier — see LLMOutcome.permanent), where the identical request can
+ // never succeed and the fix is a config change. The general retry-everything
+ // rationale below doesn't apply: this isn't a gateway phrasing a transient fault
+ // its own way, it's AgentHub's own typed error, so the ladder would only delay the
+ // actionable message.
+ if (turn.outcome.status === "failed" && turn.outcome.permanent) {
+ this.pendingCarryOver = this.buildCarryOver(attemptInput, turn);
+ yield* this.emitAbort(`llm request error: ${turn.outcome.errorMessage ?? "unknown"}`);
+ return;
+ }
// Completed normally.
if (turn.outcome.status === "completed") break;
@@ -896,6 +910,9 @@ export class ContextEngine {
cap: number,
retries: readonly StopReason[],
): number | undefined {
+ // A permanent failure is aborted on, never retried (see the turn loop): announcing a
+ // countdown for it would be a lie.
+ if (outcome.permanent) return undefined;
if (!retries.includes(outcome.status)) return undefined;
if (reconnectsSoFar >= cap) return undefined;
return reconnectDelayMs(
diff --git a/packages/core/src/interfaces.ts b/packages/core/src/interfaces.ts
index 5a7aed34..0184b575 100644
--- a/packages/core/src/interfaces.ts
+++ b/packages/core/src/interfaces.ts
@@ -135,6 +135,14 @@ export interface GenerativeModelConfig {
* llm/context-limits.ts) so small-window models never fail provider validation.
*/
maxTokens?: number;
+ /**
+ * Per-model fast mode (from the model entry's `fast_mode` annotation): when true, every
+ * request opts into the provider's faster serving tier at premium pricing (AgentHub
+ * UniConfig `fast_mode`). Off by default. Models without a fast tier reject the parameter
+ * before any network I/O (AgentHub `UnsupportedParameterError`); `streamGenerate` reports
+ * that as a permanent `failed` outcome so the engine surfaces it instead of retrying.
+ */
+ fastMode?: boolean;
/** Construction-time default thinking level; a per-request `GenerativeModelParameters.thinkingLevel` overrides it for that request. */
thinkingLevel?: ThinkingLevelName;
/** LLM Request timeout (ms): from system_config.model.timeoutMs; <=0 disables it. Defaults to 120000. */
@@ -191,6 +199,15 @@ export interface LLMOutcome {
* can show the real reason behind a retried request.
*/
errorMessage?: string;
+ /**
+ * Marks a `failed` outcome as deterministic: a client-side rejection thrown before any
+ * network I/O (currently AgentHub's `UnsupportedParameterError` for `fast_mode` on a model
+ * without a fast tier), which the identical request can never retry into working. The
+ * engine skips the reconnect ladder for it and aborts the run with `errorMessage` — the
+ * same terminal handling as `auth`, but the fix is a config change (turn off fast mode for
+ * the model), not a credential update, so it stays a `failed` and hosts don't gate input.
+ */
+ permanent?: boolean;
}
/**
diff --git a/packages/core/src/llm/generative-model.ts b/packages/core/src/llm/generative-model.ts
index acf7e269..eeccf194 100644
--- a/packages/core/src/llm/generative-model.ts
+++ b/packages/core/src/llm/generative-model.ts
@@ -18,7 +18,10 @@
* transport-shaped errors (network/transport drops, timeouts, 429/5xx, see
* `isRetryableError`) end with `timeout`; AgentHub JSON parse errors end with
* `malformed`; everything else — provider 4xx rejections included — ends with
- * `failed`, and the engine reconnects on all three the same. User interruption ends
+ * `failed`, and the engine reconnects on all three the same. One `failed` shape is
+ * additionally marked `permanent`: AgentHub's fast-mode UnsupportedParameterError
+ * (see `isFastModeUnsupportedError`), a deterministic client-side rejection the
+ * engine aborts on instead of retrying. User interruption ends
* with `aborted`; credentials failures end with their own terminal status `auth` (see
* `isAuthenticationError`) — the one status the engine refuses to retry, and the one
* hosts key on to gate input.
@@ -31,6 +34,7 @@ import {
EmptyResponseError,
ThinkingLevel,
ToolCallArgumentParseError,
+ UnsupportedParameterError,
} from "@prismshadow/agenthub";
import type {
ContentItem,
@@ -891,6 +895,33 @@ export function isAuthenticationError(error: unknown): boolean {
});
}
+/**
+ * Determines whether an error is AgentHub's `UnsupportedParameterError` for `fast_mode`:
+ * clients without a fast tier (and claude5 on Bedrock / Claude 4.6 ids) reject the
+ * parameter by throwing **before any network I/O**, so with the same frozen config the
+ * failure is deterministic — retrying the identical request can never succeed. Deliberately
+ * scoped to `parameter === "fast_mode"`: other UnsupportedParameterError sources keep the
+ * default `failed` classification (and the engine's ladder) unchanged. Judged by exception
+ * type with a `name` fallback (covers cross-realm or deserialization-reconstructed errors,
+ * same approach as isMalformedJsonParseError), probing down the `cause` chain.
+ */
+export function isFastModeUnsupportedError(error: unknown): boolean {
+ return anyInCauseChain(error, (level) => {
+ const err = level as { name?: unknown; parameter?: unknown };
+ const isUnsupportedParameter =
+ level instanceof UnsupportedParameterError || err.name === "UnsupportedParameterError";
+ return isUnsupportedParameter && err.parameter === "fast_mode";
+ });
+}
+
+/**
+ * Actionable tail appended to a fast-mode rejection's error text: the raw AgentHub message
+ * says what is unsupported ("Kimi does not support fast mode."); this says where the switch
+ * lives. Exported for the outcome-classification tests.
+ */
+export const FAST_MODE_UNSUPPORTED_GUIDANCE =
+ "Fast mode is enabled for this model; turn it off in the model settings to use this model.";
+
/**
* Determines whether an error is transport-shaped — the `timeout` vs `failed` LABEL for
* an errored request, not the retry gate: the engine retries every LLM error except
@@ -1136,7 +1167,11 @@ export class GenerativeModel implements LLMInterface {
* - **Every other error** (parameters etc., and input that never assembled into a
* request): `finishInterrupted("failed")` closes out, produces no usage → `failed`
* (carrying `message`), which `context_engine` reconnects on as well — the
- * classification stays honest, the retry decision is the engine's.
+ * classification stays honest, the retry decision is the engine's. Exception: a
+ * fast-mode rejection (`isFastModeUnsupportedError`, thrown deterministically before
+ * any network I/O when this config enables `fast_mode` on a model without a fast
+ * tier) is a `failed` marked `permanent: true`, which the engine aborts on with the
+ * actionable message instead of retrying.
*
* Timeout detection: the idle timer resets on every event received; once idle exceeds
* `requestTimeoutMs`, the underlying stream is aborted and handled as needing reconnection
@@ -1275,6 +1310,18 @@ export class GenerativeModel implements LLMInterface {
// config on load) apart from a one-off failure. Checked before the retryable
// branch as a belt — isRetryableError itself already refuses auth signals.
outcome = { status: "auth", errorMessage: describeError(error) };
+ } else if (this.uniConfig.fast_mode === true && isFastModeUnsupportedError(error)) {
+ // Fast mode rejected by a model without a fast tier: AgentHub throws its
+ // UnsupportedParameterError before any network I/O, so with this object's frozen
+ // config the failure is deterministic — marked permanent so the engine surfaces
+ // the message immediately instead of burning the reconnect ladder on a request
+ // that can never succeed. The guard on our own config keeps the special case
+ // honest: without fast_mode on the wire this error cannot be ours to explain.
+ outcome = {
+ status: "failed",
+ permanent: true,
+ errorMessage: `${describeError(error)} ${FAST_MODE_UNSUPPORTED_GUIDANCE}`,
+ };
} else if (isRetryableError(error)) {
// Transport-shaped failure (network drop, 429/5xx) -> labeled timeout. The detail
// rides on the outcome so observability (request_end -> the Cost center's errors
@@ -1427,5 +1474,11 @@ export function buildUniConfig(config: GenerativeModelConfig): UniConfig {
if (config.maxTokens !== undefined && config.maxTokens > 0) {
uniConfig.max_tokens = config.maxTokens;
}
+ // Fast mode (the model entry's `fast_mode` annotation): only ever set when enabled — the
+ // key stays off the config otherwise, so models without a fast tier are unaffected by
+ // default (AgentHub rejects the parameter wherever no fast tier exists).
+ if (config.fastMode === true) {
+ uniConfig.fast_mode = true;
+ }
return uniConfig;
}
diff --git a/packages/core/src/llm/index.ts b/packages/core/src/llm/index.ts
index 94d86dc7..a763affe 100644
--- a/packages/core/src/llm/index.ts
+++ b/packages/core/src/llm/index.ts
@@ -16,6 +16,8 @@ export {
isIncompleteStreamError,
isRetryableError,
isAuthenticationError,
+ isFastModeUnsupportedError,
+ FAST_MODE_UNSUPPORTED_GUIDANCE,
mapThinkingLevel,
toolDefinitionsToSchemas,
buildUniConfig,
diff --git a/packages/core/src/state/model-catalog.ts b/packages/core/src/state/model-catalog.ts
index 11613597..6e4fe635 100644
--- a/packages/core/src/state/model-catalog.ts
+++ b/packages/core/src/state/model-catalog.ts
@@ -1307,6 +1307,82 @@ export function resolveModelEnv(modelId: string, clientType?: string): ModelEnvI
return undefined;
}
+/**
+ * The wire protocol that would carry AgentHub's `fast_mode` for a model: `"openai"` for the
+ * OpenAI-protocol clients (openai_chat / openai_responses / gpt5_6 / minimax_m3), which send
+ * `service_tier: "priority"`, and `"anthropic"` for the Anthropic-protocol ones (ant_messages
+ * / claude5), which send `speed: "fast"` plus the `fast-mode-2026-02-01` beta header. The two
+ * differ in what the user must be warned about, not just in wire shape (see fastModeProtocol).
+ */
+export type FastModeProtocol = "openai" | "anthropic";
+
+/**
+ * Whether a model can carry fast mode at all, and on which protocol - `undefined` means no.
+ *
+ * The fast tier is a property of the **client AgentHub routes to**, never of the catalog row:
+ * the registry carries no fast-tier capability flag, but the routing is deterministic, so the
+ * answer is too. This mirrors AutoLLMClient's branch order exactly (the same discipline as
+ * resolveModelEnv above) and reports what the selected client does with the parameter:
+ *
+ * - maps it -> the protocol, and the toggle may be offered;
+ * - raises UnsupportedParameterError (gemini3_7, glm5_3, kimi_k3, deepseek_v4,
+ * openai_embedding, and claude5 on Bedrock or a Claude 4.6 id) -> `undefined`;
+ * - routes nowhere (AutoLLMClient throws for an id it cannot place; there is no openai_chat
+ * fallback) -> `undefined` as well, since a model that cannot run has no fast tier either.
+ *
+ * A rule rather than a per-model list on purpose: catalog rows added later inherit the right
+ * answer without anyone remembering to update a table.
+ *
+ * Routing reads `(clientType || modelId).toLowerCase()`, exactly as AutoLLMClient resolves it,
+ * so an entry that pins no client_type self-routes on its model id - which does not always
+ * agree with its provider group (`anthropic/claude-fable-5` with a blank client_type reaches
+ * the native claude5 client, not openai_chat, and the dotted `anthropic/claude-opus-4.8`
+ * matches no branch at all). The two claude5 carve-outs are therefore checked against the raw
+ * `modelId` / `baseUrl`, not against the routing token: the client tests its own `_model` for
+ * `"4-6"` and its base URL for the `bedrock://` prefix.
+ *
+ * `"anthropic"` is reported for every Claude the client serves, including ids outside the
+ * research preview's Opus allowlist: Anthropic answers those with a 429 at request time, which
+ * is something to warn about before enabling, not grounds to hide the setting.
+ *
+ * Two runtime inputs stay invisible to a pure function of the config and can still flip the
+ * answer: the server's `CLIENT_TYPE` env var overrides the entry's client type, and
+ * `ANTHROPIC_BASE_URL` supplies the base URL when the entry leaves it blank (so a `bedrock://`
+ * there sends Claude to Bedrock, which has no fast tier). Third-party OpenAI-compatible
+ * endpoints are a third: they accept `service_tier` and may quietly serve the standard tier.
+ * That residue is why llm/generative-model.ts still handles the rejection at runtime.
+ */
+export function fastModeProtocol(
+ modelId: string,
+ clientType?: string,
+ baseUrl?: string,
+): FastModeProtocol | undefined {
+ const t = clientType?.toLowerCase() || modelId.toLowerCase();
+ // Branch order mirrors AutoLLMClient. Every test is a substring of `t` except minimax-m3,
+ // which the router matches by exact equality; no trimming, matching the router.
+ if (t === "minimax-m3") return "openai";
+ if (t.includes("gemini-3") || t.includes("gemini-embedding")) return undefined;
+ if (
+ t.includes("claude") &&
+ (t.includes("4-6") || t.includes("4-7") || t.includes("4-8") || t.includes("-5"))
+ ) {
+ // claude5 refuses fast mode on Bedrock and across the Claude 4.6 family; both tests run
+ // against what the client was constructed with, not against the routing token.
+ if (baseUrl?.startsWith("bedrock://")) return undefined;
+ if (modelId.includes("4-6")) return undefined;
+ return "anthropic";
+ }
+ if (t.includes("gpt-5.4") || t.includes("gpt-5.5") || t.includes("gpt-5.6")) return "openai";
+ if (t.includes("glm-5")) return undefined;
+ if (t.includes("kimi-k3") || t.includes("kimi-k2.5") || t.includes("kimi-k2.6")) return undefined;
+ if (t.includes("deepseek-v4")) return undefined;
+ if (t.includes("ant-messages")) return "anthropic";
+ if (t.includes("openai-responses")) return "openai";
+ if (t.includes("openai") && t.includes("embedding")) return undefined;
+ if (t.includes("openai")) return "openai";
+ return undefined;
+}
+
/**
* Catalog -> preset ModelEntry list (shared by defaultProjectConfig and the server's initial
* config, avoiding duplicate hand-written copies). `provider` and `model_id` are persisted as
diff --git a/packages/core/src/state/project-config.ts b/packages/core/src/state/project-config.ts
index 50c10d1e..28ccf0fc 100644
--- a/packages/core/src/state/project-config.ts
+++ b/packages/core/src/state/project-config.ts
@@ -101,6 +101,16 @@ export interface ModelEntry {
* the Agent value. User-only, never preset by the builtin catalog.
*/
max_tokens?: number;
+ /**
+ * Per-model fast mode (AgentHub UniConfig `fast_mode`): opts session requests into the
+ * provider's faster serving tier at premium pricing (OpenAI-protocol clients send
+ * `service_tier: "priority"`, Anthropic-protocol clients send `speed: "fast"`). Only `true`
+ * is ever persisted; absent = off (the default). Models without a fast tier reject the
+ * parameter (AgentHub raises UnsupportedParameterError), which ends the request with a
+ * clear non-retried failure (see llm/generative-model.ts). User-only, never preset by the
+ * builtin catalog.
+ */
+ fast_mode?: boolean;
/** Pricing info; absent means this Model's cost isn't counted. */
pricing?: ModelPricing;
/** API key (inlined credential); left empty falls back to the vendor's environment variable. */
@@ -397,6 +407,8 @@ export async function addModel(
vision?: boolean;
/** Per-model max output tokens (wins over the Agent config); keeps the existing value by default (unset = inherit the Agent value). */
max_tokens?: number;
+ /** Per-model fast mode; keeps the existing value by default. Only `true` is persisted: an explicit `false` clears the annotation (absent = off). */
+ fast_mode?: boolean;
/** Price input may cover only some buckets; merged and written as a complete `ModelPricing`. */
pricing?: Partial<ModelPricing>;
api_key?: string;
@@ -438,6 +450,12 @@ export async function addModel(
if (maxTokens !== undefined) {
modelEntry.max_tokens = maxTokens;
}
+ // Only `true` is persisted (absent = off): an explicit `false` clears the stored annotation
+ // instead of writing `fast_mode = false`, and a hand-edited `false` normalizes to absent.
+ const fastMode = entry.fast_mode ?? existing?.fast_mode;
+ if (fastMode === true) {
+ modelEntry.fast_mode = true;
+ }
// The three price buckets are merged field by field: an unspecified bucket keeps its existing
// value (the same policy as context_window/credential); the unit is fixed to usd_per_mtok, and
// the complete pricing is written as long as any bucket is present.
diff --git a/packages/core/test/agent.test.ts b/packages/core/test/agent.test.ts
index ca6edd31..bccd750d 100644
--- a/packages/core/test/agent.test.ts
+++ b/packages/core/test/agent.test.ts
@@ -706,6 +706,71 @@ describe("Agent.createSession max output tokens (per-model cap wins over the Age
});
});
+describe("Agent.createSession fast mode (session requests only, never the meta ones)", () => {
+ const uniConfigOf = (llm: unknown) =>
+ (llm as { uniConfig?: { fast_mode?: boolean } }).uniConfig ?? {};
+
+ it("the entry's fast_mode reaches the session LLM and is withheld from the meta LLM", async () => {
+ // The scoping decision the whole feature rests on: the premium tier is what the user is
+ // waiting on, so it rides the session's own requests, while background one-shots (title
+ // generation here; the describe_image describer builds from the *vision* model's entry and
+ // so cannot inherit it at all) stay on the standard tier. Without this test the split is
+ // asserted only by comments, and a refactor that hoists fastMode into a shared config
+ // helper would start billing every session title at premium rates with all suites green.
+ await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
+ provider: "custom",
+ model_id: "fast-on",
+ client_type: "openai",
+ fast_mode: true,
+ });
+ const agent = await createAgent();
+ const ws = path.join(tmpRoot, "ws-fast-mode");
+ await fs.mkdir(ws, { recursive: true });
+
+ const session = await agent.createSession({
+ workspaceDir: ws,
+ modelId: "fast-on",
+ provider: "custom",
+ });
+ try {
+ await bootstrapped(session);
+ const llm = (session as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
+ expect(uniConfigOf(llm).fast_mode).toBe(true);
+ // The title one-shot on the same model must not carry it.
+ const bare = (session as unknown as { createBareLLM?: () => unknown }).createBareLLM?.();
+ expect("fast_mode" in uniConfigOf(bare)).toBe(false);
+ } finally {
+ session.dispose();
+ }
+ });
+
+ it("an unannotated entry puts no fast_mode key on the wire at all", async () => {
+ // Absent, not false: models without a fast tier reject the parameter, so every existing
+ // config has to stay byte-identical on the wire.
+ await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
+ provider: "custom",
+ model_id: "fast-off",
+ client_type: "openai",
+ });
+ const agent = await createAgent();
+ const ws = path.join(tmpRoot, "ws-fast-mode-off");
+ await fs.mkdir(ws, { recursive: true });
+
+ const session = await agent.createSession({
+ workspaceDir: ws,
+ modelId: "fast-off",
+ provider: "custom",
+ });
+ try {
+ await bootstrapped(session);
+ const llm = (session as unknown as { engine: { deps: { llm: unknown } } }).engine.deps.llm;
+ expect("fast_mode" in uniConfigOf(llm)).toBe(false);
+ } finally {
+ session.dispose();
+ }
+ });
+});
+
describe("Agent.createSession vault injection", () => {
it("injects vault key names (never values) into the assembled system prompt", async () => {
// Write the Agent vault to disk first; createSession reads that Agent's own .vault.toml.
diff --git a/packages/core/test/engine.test.ts b/packages/core/test/engine.test.ts
index 249eb519..47090803 100644
--- a/packages/core/test/engine.test.ts
+++ b/packages/core/test/engine.test.ts
@@ -1909,6 +1909,73 @@ describe("ContextEngine LLM timeout / network interruption (PRN-012)", () => {
expect((abort!.payload as { reason?: string }).reason).toContain("llm request error");
});
+ it("a permanent failed (fast-mode rejection) stops the run without burning the ladder", async () => {
+ let calls = 0;
+ const llm: LLMInterface = {
+ // GenerativeModel marks AgentHub's fast_mode UnsupportedParameterError as a permanent
+ // failed (see llm.test.ts): thrown before any network I/O, deterministic for the
+ // session's frozen config, so retrying the identical request can never succeed. The
+ // engine must abort with the actionable message instead of costing the ladder.
+ // eslint-disable-next-line require-yield
+ async *streamGenerate() {
+ calls += 1;
+ return {
+ status: "failed" as const,
+ permanent: true,
+ errorMessage:
+ "Kimi does not support fast mode. Fast mode is enabled for this model; " +
+ "turn it off in the model settings to use this model.",
+ };
+ },
+ };
+ const environment = new Environment({
+ workspaceDir: workspace,
+ toolConfig: execCommandToolConfig(),
+ });
+ const engine = new ContextEngine({ llm, environment, maxReconnects: 3, reconnectBackoffMs: 1 });
+
+ const all = await collectRun(engine, [userText("go")], allowAll);
+ expect(calls).toBe(1); // Deterministic client-side rejection: one attempt, no reconnects.
+ // The classification stays an honest `failed` on the wire (not auth: hosts must not
+ // gate input for a credential fix — the fix is the model's fast-mode setting).
+ const end = all.find((m) => (m.payload as { type?: string }).type === "request_end");
+ expect((end!.payload as { status?: string }).status).toBe("failed");
+ // No planned retry is announced: the frontend must not render a countdown for a
+ // retry that never comes.
+ expect((end!.payload as { retry_in_ms?: number }).retry_in_ms).toBeUndefined();
+ const abort = all.find((m) => (m.payload as { type?: string }).type === "abort");
+ expect(abort).toBeDefined();
+ const reason = (abort!.payload as { reason?: string }).reason ?? "";
+ expect(reason).toContain("llm request error");
+ expect(reason).toContain("turn it off in the model settings");
+ });
+
+ it("a plain failed outcome (no permanent flag) still takes the ladder", async () => {
+ // The permanent flag is opt-in and narrowly scoped: an ordinary failed without it keeps
+ // the retry-everything policy (the classifier is an allowlist; a gateway phrasing a
+ // transient fault its own way must still reconnect).
+ let calls = 0;
+ const llm: LLMInterface = {
+ async *streamGenerate() {
+ calls += 1;
+ if (calls === 1) return { status: "failed" as const, errorMessage: "flaky gateway" };
+ yield assistantText("recovered");
+ return { status: "completed" as const };
+ },
+ };
+ const engine = new ContextEngine({
+ llm,
+ environment: new Environment({
+ workspaceDir: workspace,
+ toolConfig: execCommandToolConfig(),
+ }),
+ reconnectBackoffMs: 0,
+ });
+ const all = await collectRun(engine, [userText("go")], allowAll);
+ expect(calls).toBe(2);
+ expect(all.find((m) => (m.payload as { type?: string }).type === "abort")).toBeUndefined();
+ });
+
it("a bare 403 (classified failed) retries within the default cap and succeeds", async () => {
let calls = 0;
const llm: LLMInterface = {
diff --git a/packages/core/test/llm.test.ts b/packages/core/test/llm.test.ts
index ac6d2916..3a8214e6 100644
--- a/packages/core/test/llm.test.ts
+++ b/packages/core/test/llm.test.ts
@@ -14,6 +14,7 @@ import {
EmptyResponseError,
ThinkingLevel,
ToolCallArgumentParseError,
+ UnsupportedParameterError,
} from "@prismshadow/agenthub";
import type { UniConfig, UniEvent, UniMessage, UsageMetadata } from "@prismshadow/agenthub";
import type { LLMOutcome, ThinkingLevelName } from "../src/interfaces.js";
@@ -26,8 +27,10 @@ import {
buildUniConfig,
isAuthenticationError,
isIncompleteStreamError,
+ isFastModeUnsupportedError,
isMalformedJsonParseError,
isRetryableError,
+ FAST_MODE_UNSUPPORTED_GUIDANCE,
mapThinkingLevel,
mergeOmniToUniMessage,
stripToolCallIdSuffix,
@@ -1075,6 +1078,18 @@ describe("config helpers", () => {
const withTools = buildUniConfig({ modelId: "m", tools: [{ name: "t", description: "d" }] });
expect("tool_choice" in withTools).toBe(false);
});
+
+ it("sets fast_mode only when enabled: the key stays off the config otherwise", () => {
+ // Enabled: the entry's fast_mode annotation reaches the wire as UniConfig.fast_mode.
+ const on = buildUniConfig({ modelId: "m", tools: [], fastMode: true });
+ expect(on.fast_mode).toBe(true);
+ // Off / absent: the key must be ABSENT, not false — models without a fast tier reject
+ // the parameter, so an unset annotation must leave existing configs bit-identical.
+ const off = buildUniConfig({ modelId: "m", tools: [], fastMode: false });
+ expect("fast_mode" in off).toBe(false);
+ const unset = buildUniConfig({ modelId: "m", tools: [] });
+ expect("fast_mode" in unset).toBe(false);
+ });
});
describe("isRetryableError (the timeout-vs-failed label; the engine retries every non-auth error)", () => {
@@ -1205,6 +1220,50 @@ describe("isAuthenticationError", () => {
});
});
+describe("isFastModeUnsupportedError (fast_mode rejected by a model without a fast tier)", () => {
+ const fastModeError = () =>
+ new UnsupportedParameterError({
+ client: "KimiK3Client",
+ parameter: "fast_mode",
+ message: "Kimi does not support fast mode.",
+ });
+
+ it("detects AgentHub's UnsupportedParameterError for fast_mode, including the cause chain", () => {
+ expect(isFastModeUnsupportedError(fastModeError())).toBe(true);
+ // Wrapped one level up (a higher layer annotating the request) is still found.
+ expect(
+ isFastModeUnsupportedError(new Error("request failed", { cause: fastModeError() })),
+ ).toBe(true);
+ // Cross-realm / reconstructed errors match by name + parameter without the class identity.
+ expect(
+ isFastModeUnsupportedError({
+ name: "UnsupportedParameterError",
+ parameter: "fast_mode",
+ message: "Bedrock does not support fast mode.",
+ }),
+ ).toBe(true);
+ });
+
+ it("stays scoped to fast_mode: other unsupported parameters and unrelated errors do not match", () => {
+ // Another UnsupportedParameterError source (e.g. temperature) keeps the default failed
+ // classification and the engine's retry ladder — this detector must not widen the
+ // permanent special case.
+ expect(
+ isFastModeUnsupportedError(
+ new UnsupportedParameterError({
+ client: "Gemini37Client",
+ parameter: "temperature",
+ message: "temperature is not supported.",
+ }),
+ ),
+ ).toBe(false);
+ // Message vocabulary alone is not a signal: only the typed error (or its name) counts.
+ expect(isFastModeUnsupportedError(new Error("model does not support fast mode"))).toBe(false);
+ expect(isFastModeUnsupportedError({ status: 400 })).toBe(false);
+ expect(isFastModeUnsupportedError(null)).toBe(false);
+ });
+});
+
describe("isMalformedJsonParseError", () => {
it("detects JSON.parse SyntaxError by exception type, including the cause chain", () => {
// AgentHub uses JSON.parse internally; a parse failure throws a SyntaxError, so it can be
@@ -1741,6 +1800,57 @@ describe("GenerativeModel.streamGenerate outcome classification (PRN-013)", () =
expect(outcome2.status).toBe("failed");
});
+ it("marks a fast-mode rejection as permanent failed with actionable guidance (guarded on its own config)", async () => {
+ // AgentHub throws UnsupportedParameterError before any network I/O when fast_mode is
+ // enabled on a model without a fast tier: deterministic for this object's frozen config,
+ // so it is the one failed shape the engine aborts on instead of retrying
+ // (LLMOutcome.permanent; the engine side is covered in engine.test.ts).
+ async function* fastModeRejected(): AsyncGenerator<UniEvent> {
+ throw new UnsupportedParameterError({
+ client: "KimiK3Client",
+ parameter: "fast_mode",
+ message: "Kimi does not support fast mode.",
+ });
+ }
+ class FastSeamModel extends GenerativeModel {
+ constructor(fastMode: boolean) {
+ // A real AutoLLMClient is constructed even though openStream is overridden, and the
+ // Kimi client's OpenAI SDK demands a credential at construction time. The key is
+ // passed explicitly so the config is frozen here rather than read from the ambient
+ // environment (see test/provider-keys.ts); nothing is ever sent.
+ super({
+ modelId: "kimi-k3",
+ tools: [],
+ fastMode,
+ requestTimeoutMs: 10000,
+ apiKey: "test-key-not-used",
+ });
+ }
+ protected override openStream(): AsyncIterable<UniEvent> {
+ return fastModeRejected();
+ }
+ }
+ const model = new FastSeamModel(true);
+ const { messages, outcome } = await drain(
+ model.streamGenerate({ newMessages: [userText("go")] }),
+ );
+ expect(outcome.status).toBe("failed");
+ expect(outcome.permanent).toBe(true);
+ // The surfaced text keeps AgentHub's own words and appends where the switch lives.
+ expect(outcome.errorMessage).toContain("Kimi does not support fast mode.");
+ expect(outcome.errorMessage).toContain(FAST_MODE_UNSUPPORTED_GUIDANCE);
+ expect(messages.map(typeOf)).not.toContain("token_usage");
+
+ // Guard: the same error on a config that never sent fast_mode cannot be ours to
+ // explain — it stays a plain failed (no permanent) and rides the engine's ladder.
+ const model2 = new FastSeamModel(false);
+ const { outcome: outcome2 } = await drain(
+ model2.streamGenerate({ newMessages: [userText("go")] }),
+ );
+ expect(outcome2.status).toBe("failed");
+ expect(outcome2.permanent).toBeUndefined();
+ });
+
it("an explicit auth signal wins whatever the message says: status auth, never retried", async () => {
// 403 + body code invalid_api_key + a message mentioning the subscription: the
// explicit credential signal decides — auth is the one terminal status, and no
diff --git a/packages/core/test/model-catalog.test.ts b/packages/core/test/model-catalog.test.ts
index 048ffb3d..fd72a904 100644
--- a/packages/core/test/model-catalog.test.ts
+++ b/packages/core/test/model-catalog.test.ts
@@ -11,6 +11,7 @@ import {
catalogEntryFor,
presetModelEntries,
providerInfo,
+ fastModeProtocol,
resolveModelEnv,
} from "../src/state/index.js";
@@ -713,3 +714,103 @@ describe("resolveModelEnv (PRN-021: env fallback resolved by AgentHub routing ru
expect(modelHomepageUrl("my-own-gateway", "x")).toBeUndefined();
});
});
+
+describe("fastModeProtocol (which models may be offered AgentHub's fast_mode, and on which protocol)", () => {
+ it("OpenAI-protocol clients carry it: openai_chat / openai_responses / gpt5_6 / minimax_m3", () => {
+ // Bare "openai" is the alias the web pins on custom, user-defined and gateway rows.
+ expect(fastModeProtocol("anything-at-all", "openai")).toBe("openai");
+ expect(fastModeProtocol("local-qwen", "openai-responses")).toBe("openai");
+ // minimax-m3 is the one branch AgentHub matches by exact equality, not substring.
+ expect(fastModeProtocol("MiniMax-M3", "minimax-m3")).toBe("openai");
+ expect(fastModeProtocol("MiniMax-M3")).toBe("openai");
+ // The gpt-5.x branch precedes the openai catch-all, and both map service_tier.
+ expect(fastModeProtocol("gpt-5.5-pro")).toBe("openai");
+ expect(fastModeProtocol("gpt-5.4-mini")).toBe("openai");
+ expect(fastModeProtocol("gpt-5.6")).toBe("openai");
+ });
+
+ it("Anthropic-protocol clients carry it as speed=fast", () => {
+ expect(fastModeProtocol("claude-fable-5")).toBe("anthropic");
+ expect(fastModeProtocol("claude-sonnet-5")).toBe("anthropic");
+ expect(fastModeProtocol("claude-opus-4-8")).toBe("anthropic");
+ expect(fastModeProtocol("some-proxy-id", "ant-messages")).toBe("anthropic");
+ // Outside the research preview's Opus allowlist the client still sends it and Anthropic
+ // answers 429 — a warning before enabling, not a reason to withhold the setting.
+ expect(fastModeProtocol("claude-opus-4-7")).toBe("anthropic");
+ });
+
+ it("clients that reject the parameter get no toggle: Gemini, GLM, Kimi, DeepSeek, embeddings", () => {
+ expect(fastModeProtocol("gemini-3.5-flash")).toBeUndefined();
+ expect(fastModeProtocol("gemini-3.1-pro-preview")).toBeUndefined();
+ expect(fastModeProtocol("gemini-embedding-001")).toBeUndefined();
+ expect(fastModeProtocol("glm-5.2")).toBeUndefined();
+ expect(fastModeProtocol("kimi-k3")).toBeUndefined();
+ expect(fastModeProtocol("kimi-k2.6")).toBeUndefined();
+ expect(fastModeProtocol("kimi-k2.5")).toBeUndefined();
+ expect(fastModeProtocol("deepseek-v4-pro")).toBeUndefined();
+ expect(fastModeProtocol("text-embedding-3-large", "openai-embedding")).toBeUndefined();
+ // A future first-party generation inherits the verdict from its family substring, so a
+ // catalog row added later needs no change here (agenthub routes glm-5.3 / gemini-3.7 to
+ // the same rejecting clients).
+ expect(fastModeProtocol("glm-5.3")).toBeUndefined();
+ expect(fastModeProtocol("gemini-3.7-pro")).toBeUndefined();
+ });
+
+ it("claude5 carve-outs are tested against the model id and base URL, not the routing token", () => {
+ // Claude 4.6 is refused by name even though claude5 serves the family.
+ expect(fastModeProtocol("claude-sonnet-4-6")).toBeUndefined();
+ expect(fastModeProtocol("Claude-Sonnet-4-6")).toBeUndefined();
+ // Routing may come from client_type while the 4-6 refusal reads the model id...
+ expect(fastModeProtocol("my-claude-sonnet-4-6-proxy", "claude-5")).toBeUndefined();
+ // ...and conversely a 4-6 client_type with a served model id keeps fast mode.
+ expect(fastModeProtocol("claude-sonnet-5", "claude-4-6")).toBe("anthropic");
+ // Bedrock has no fast tier; the prefix lives in the base URL, which is why the rule needs it.
+ expect(fastModeProtocol("claude-fable-5", undefined, "bedrock://us-east-1")).toBeUndefined();
+ expect(fastModeProtocol("claude-fable-5", undefined, "https://api.anthropic.com")).toBe(
+ "anthropic",
+ );
+ });
+
+ it("an id AgentHub cannot route gets no toggle either (no client, so no fast tier)", () => {
+ // AutoLLMClient throws for an unmatched token — there is no openai_chat fallback.
+ expect(fastModeProtocol("totally-unknown-model")).toBeUndefined();
+ expect(fastModeProtocol("MiniMax-M4")).toBeUndefined();
+ // Dotted OpenRouter Anthropic ids match no branch at all when no client_type is pinned
+ // (neither "4-8" nor "-5"), unlike their dashed first-party spellings.
+ expect(fastModeProtocol("anthropic/claude-opus-4.8")).toBeUndefined();
+ // The same row as the catalog ships it — client_type pinned — is served over openai_chat.
+ expect(fastModeProtocol("anthropic/claude-opus-4.8", "openai")).toBe("openai");
+ // Self-routing can disagree with the provider group: a blank client_type sends this id to
+ // the native claude5 client, flipping the protocol that would carry the parameter.
+ expect(fastModeProtocol("anthropic/claude-fable-5")).toBe("anthropic");
+ expect(fastModeProtocol("anthropic/claude-fable-5", "openai")).toBe("openai");
+ });
+
+ it("catalog invariant: every built-in row's verdict follows its client family", () => {
+ for (const m of MODEL_CATALOG) {
+ const verdict = fastModeProtocol(m.modelId, m.clientType, m.baseUrl);
+ if (m.clientType === "openai") {
+ // Every gateway row pins the OpenAI protocol, which always carries service_tier.
+ expect(verdict, `${m.provider}/${m.modelId}`).toBe("openai");
+ } else if (["google", "zhipu", "moonshot", "deepseek"].includes(m.provider)) {
+ // These groups' first-party clients have no fast tier at all: rows added to them
+ // later (a new Gemini or GLM generation) stay excluded without touching this rule.
+ expect(verdict, `${m.provider}/${m.modelId}`).toBeUndefined();
+ }
+ }
+ // The direct first-party rows that do serve it, named so a regression is legible.
+ const verdictOf = (provider: string, modelId: string) => {
+ const m = catalogEntryFor(provider, modelId)!;
+ return fastModeProtocol(m.modelId, m.clientType, m.baseUrl);
+ };
+ expect(verdictOf("anthropic", "claude-fable-5")).toBe("anthropic");
+ expect(verdictOf("anthropic", "claude-sonnet-5")).toBe("anthropic");
+ expect(verdictOf("anthropic", "claude-opus-4-8")).toBe("anthropic");
+ expect(verdictOf("anthropic", "claude-opus-4-7")).toBe("anthropic");
+ // The one Anthropic row the client refuses by name.
+ expect(verdictOf("anthropic", "claude-sonnet-4-6")).toBeUndefined();
+ expect(verdictOf("openai", "gpt-5.5")).toBe("openai");
+ expect(verdictOf("openai", "gpt-5.4-pro")).toBe("openai");
+ expect(verdictOf("minimax", "MiniMax-M3")).toBe("openai");
+ });
+});
diff --git a/packages/docs/content/cli.en.md b/packages/docs/content/cli.en.md
index 151bab32..0fa7ffa0 100644
--- a/packages/docs/content/cli.en.md
+++ b/packages/docs/content/cli.en.md
@@ -96,6 +96,7 @@ penguin config model add --provider deepseek --model-id deepseek-v4-pro --api-ke
| `--max-tokens <n>` | Per-model max output tokens (positive integer). Overrides the Agent's `model.max_tokens` when set; omit to inherit — lower it for small-context models |
| `--client-type <type>` | Client protocol type |
| `--vision` / `--no-vision` | Mark vision input as supported / unsupported |
+| `--fast-mode` / `--no-fast-mode` | Enable / disable fast mode (faster output at premium pricing; off by default). Enabling it on a model whose AgentHub client rejects the parameter still writes the entry but warns on stderr. Omit both to keep the current value |
| `--price-cache-read <n>` | Cache-read price |
| `--price-cache-write <n>` | Cache-write price |
| `--price-output <n>` | Output price |
diff --git a/packages/docs/content/cli.zh.md b/packages/docs/content/cli.zh.md
index cde8ca2c..7c9ea4ec 100644
--- a/packages/docs/content/cli.zh.md
+++ b/packages/docs/content/cli.zh.md
@@ -96,6 +96,7 @@ penguin config model add --provider deepseek --model-id deepseek-v4-pro --api-ke
| `--max-tokens <n>` | 该模型的最大输出长度(正整数)。设置后覆盖 Agent 的 `model.max_tokens`,缺省沿用;小上下文模型建议调低 |
| `--client-type <type>` | 客户端协议类型 |
| `--vision` / `--no-vision` | 标记是否支持视觉输入 |
+| `--fast-mode` / `--no-fast-mode` | 开启 / 关闭快速模式(输出更快、按溢价计费;默认关闭)。在 AgentHub client 会拒绝该参数的模型上开启时,条目照常写入,但会在 stderr 给出警告。两者都不给则保留原值 |
| `--price-cache-read <n>` | 缓存读价格 |
| `--price-cache-write <n>` | 缓存写价格 |
| `--price-output <n>` | 输出价格 |
diff --git a/packages/docs/content/configuration.en.md b/packages/docs/content/configuration.en.md
index 6947b0d7..3a4590d7 100644
--- a/packages/docs/content/configuration.en.md
+++ b/packages/docs/content/configuration.en.md
@@ -63,6 +63,7 @@ Model entry (`[[models]]`) fields:
| `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 |
+| `fast_mode` | Per-model fast mode (premium faster serving tier); off by default, only `true` is persisted. Offered only for models whose AgentHub client can serve it; the others reject requests carrying it — see [Models](/models#fast-mode) |
| `pricing` | Three price buckets `cache_read` / `cache_write` / `output`, in USD per million Tokens (`unit = "usd_per_mtok"`) |
| `api_key` | Inline credential; when empty, falls back to the provider environment variable |
| `base_url` | Custom base URL; preset by the built-in catalog for gateways and direct MiniMax models |
diff --git a/packages/docs/content/configuration.zh.md b/packages/docs/content/configuration.zh.md
index 62a0b915..2b8c0712 100644
--- a/packages/docs/content/configuration.zh.md
+++ b/packages/docs/content/configuration.zh.md
@@ -63,6 +63,7 @@ openrouter、fireworks、siliconflow、qwen-token-plan、qwen-pay-as-you-go 与
| `display_name` | 展示名;仅在与内置目录不同时持久化 |
| `vision` | 是否支持图片输入;缺省视为支持 |
| `max_tokens` | 单模型最大输出 Token;设置后覆盖 Agent 的 `model.max_tokens`,缺省则继承 |
+| `fast_mode` | 单模型快速模式(厂商的溢价快速推理档位);默认关闭,只持久化 `true`。只对 AgentHub client 支持该档位的模型开放,其余模型会拒绝携带该参数的请求——见[模型与 Provider](/models#快速模式) |
| `pricing` | 三档价格 `cache_read` / `cache_write` / `output`,单位 USD 每百万 Token(`unit = "usd_per_mtok"`) |
| `api_key` | 内联凭证;留空回退到 Provider 环境变量 |
| `base_url` | 自定义 Base URL;内置目录会为网关与直连 MiniMax 模型预置 |
diff --git a/packages/docs/content/interfaces.en.md b/packages/docs/content/interfaces.en.md
index 312458d3..8d0e4741 100644
--- a/packages/docs/content/interfaces.en.md
+++ b/packages/docs/content/interfaces.en.md
@@ -54,6 +54,9 @@ interface LLMOutcome {
message?: string; // failure detail: on failed/auth, and on timeout/malformed when a
// concrete error was caught — carried onto request_end so the
// errors panel shows the real reason behind a retried request
+ permanent?: boolean; // marks a failed as deterministic (client-side rejection thrown before
+ // any network I/O, e.g. fast_mode on a model without a fast tier):
+ // the engine aborts with the message instead of retrying
}
```
@@ -62,7 +65,7 @@ interface LLMOutcome {
| `completed` | finished normally (token_usage already emitted) | proceed |
| `timeout` | timeout / transport disconnect | auto-reconnect within the run |
| `malformed` | response parse failure | auto-reconnect within the run |
-| `failed` | an error the classifier did not judge transient (params, …) | auto-reconnect within the run as well — the status is still reported as `failed` |
+| `failed` | an error the classifier did not judge transient (params, …) | auto-reconnect within the run as well — the status is still reported as `failed`. Exception: with `permanent: true` (a deterministic client-side rejection, e.g. fast mode on a model without a fast tier) the run stops immediately with the message |
| `aborted` | user interrupt | stop, hand back to the user |
| `auth` | credentials rejected | stop, hand back to the user — the one LLM status that never retries; hosts gate input until the model's API key is updated |
@@ -82,6 +85,7 @@ interface GenerativeModelConfig {
systemPrompt?: string; // fully assembled system prompt, placeholders substituted
contextWindow?: number;
maxTokens?: number;
+ fastMode?: boolean; // per-model fast mode (AgentHub fast_mode; premium faster tier), off by default
thinkingLevel?: ThinkingLevelName; // construction default (a per-request parameter can override); "none" | "low" | "medium" | "high" | "xhigh"
requestTimeoutMs?: number; // per-Request timeout, default 120000; <=0 disables
toolCallIds?: ToolCallIdAllocator; // Session-level tool_call_id registry (pass the same instance across compaction)
diff --git a/packages/docs/content/interfaces.zh.md b/packages/docs/content/interfaces.zh.md
index 0e84cd9b..1da894ca 100644
--- a/packages/docs/content/interfaces.zh.md
+++ b/packages/docs/content/interfaces.zh.md
@@ -54,6 +54,9 @@ interface LLMOutcome {
message?: string; // 失败详情:failed/auth 时携带;timeout/malformed 捕获到具体
// 错误时也携带——透传到 request_end,错误面板据此展示被重试
// 请求背后的真实原因
+ permanent?: boolean; // 标记该 failed 为确定性失败(发起网络请求前在客户端就被拒绝,
+ // 如在没有 fast 档位的模型上启用 fast_mode):引擎直接带消息
+ // 终止,不再重试
}
```
@@ -62,7 +65,7 @@ interface LLMOutcome {
| `completed` | 正常完成(已产出 token_usage) | 继续下一步 |
| `timeout` | 超时/传输层断连 | 同一 run 内自动重连 |
| `malformed` | 响应解析失败 | 同一 run 内自动重连 |
-| `failed` | 分类器未判定为瞬时的错误(参数等) | 同样在同一 run 内自动重连——状态本身仍如实上报为 `failed` |
+| `failed` | 分类器未判定为瞬时的错误(参数等) | 同样在同一 run 内自动重连——状态本身仍如实上报为 `failed`。例外:携带 `permanent: true`(确定性的客户端拒绝,如在没有 fast 档位的模型上启用快速模式)时立即带消息停止 |
| `aborted` | 用户中断 | 停止交还用户 |
| `auth` | 凭据被拒绝 | 停止交还用户——唯一从不重试的 LLM 终态;宿主据此禁用输入,直到该模型的 API key 被更新 |
@@ -82,6 +85,7 @@ interface GenerativeModelConfig {
systemPrompt?: string; // 占位符替换完成后的完整系统提示词
contextWindow?: number;
maxTokens?: number;
+ fastMode?: boolean; // 单模型快速模式(AgentHub fast_mode;溢价快速档位),默认关闭
thinkingLevel?: ThinkingLevelName; // 构造期默认档位(逐请求参数可覆盖);"none" | "low" | "medium" | "high" | "xhigh"
requestTimeoutMs?: number; // 单次 Request 超时,默认 120000;<=0 关闭
toolCallIds?: ToolCallIdAllocator; // Session 级 tool_call_id 唯一性登记表(压缩重建时传同一实例)
diff --git a/packages/docs/content/models.en.md b/packages/docs/content/models.en.md
index ba8f5396..9b3b4a39 100644
--- a/packages/docs/content/models.en.md
+++ b/packages/docs/content/models.en.md
@@ -26,6 +26,7 @@ Each Project's available models are recorded in the hidden `.project_config.toml
| `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. Custom endpoints use one of those three generic protocol clients, and the Web dialog can detect which one a base URL serves. 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 |
+| `fast_mode` | Optional fast mode (off by default): opts the model's session requests into the provider's faster serving tier at premium pricing. Only `true` is ever persisted — omitting the field on a Web full-table save clears it. Models without a fast tier reject requests carrying it (see [Fast mode](#fast-mode)) |
| `pricing` | Three price buckets (unit `usd_per_mtok`, USD per million tokens): `cache_read` / `cache_write` / `output` |
| `api_key` / `base_url` | Inlined credentials, both optional; when blank, AgentHub falls back to environment variables |
@@ -111,6 +112,34 @@ For MiniMax M3, `none` maps directly to `reasoning.effort = "none"`.
Five levels: `none | low | medium | high | xhigh`, configured per Agent as `model.thinking_level` in `system_config.yaml`, default medium. The Web pickers offer `low` and above only (many models cannot disable thinking; `none` stays a valid stored value and still displays). The chat draft view offers a quick picker next to the model selector: a picked level is written back to the selected Agent's setting immediately (the switched-to level becomes that Agent's new default and applies from the next session). Inside an active session the thinking level is a **per-turn parameter**: the composer's picker lists only the levels and starts out showing the Agent config's level — while the user hasn't picked one it auto-follows the config (sends omit the level, so config edits keep taking effect); once picked, the level sticks for that session and rides on every subsequent send (it applies to that session's subsequent Tasks only and never writes back to the Agent config). See [Configuration](/configuration).
+## Fast mode
+
+Each model entry can opt into the provider's faster serving tier ("Fast mode" toggle in the Web model dialog, `--fast-mode` / `--no-fast-mode` on `penguin config model add`, `fast_mode = true` in the entry). Off by default; existing configs are unaffected. Switching it on asks for confirmation first, because it changes what the model costs.
+
+When enabled, session requests carry AgentHub's `fast_mode` flag: OpenAI-protocol clients send `service_tier: "priority"`, Anthropic-protocol clients send `speed: "fast"` with the fast-mode beta header. Fast tiers are billed at the provider's premium price list (MiniMax charges 1.5x its standard rate; OpenAI and Anthropic publish separate premium rates), and the recorded per-token pricing does not adjust for it — costs shown for fast-mode usage are underestimated unless you raise the entry's price buckets.
+
+### Which models offer it
+
+Whether a fast tier exists is decided by the AgentHub client a model routes to, not by the model entry, so the toggle appears only where that client actually sends the parameter:
+
+| Routed client | Fast mode |
+| --- | --- |
+| OpenAI protocol (`openai_chat`, `openai_responses`, `gpt5_6`, `minimax_m3`) | sent as `service_tier: "priority"` |
+| Anthropic protocol (`ant_messages`, `claude5`) | sent as `speed: "fast"` plus the beta header |
+| Gemini, GLM, Kimi, DeepSeek, OpenAI embeddings | rejected — no toggle |
+| Claude on Bedrock, or a Claude 4.6 id | rejected — no toggle |
+
+Routing follows the entry's `client_type`, or its `model_id` when none is set, so the same upstream id can land in different places: a Kimi model added under a gateway group (`client_type = "openai"`) can serve fast mode, while the same id routed to Kimi's own client cannot. A custom model behind your own base URL keeps the toggle — it speaks the OpenAI protocol and may well be OpenAI — but a third-party server is free to accept the parameter and serve the standard tier anyway.
+
+Two things the toggle cannot check for you:
+
+- Anthropic's fast mode is a limited research preview: until your organization is granted access, requests return a 429 rate-limit error. The confirmation says so for Anthropic-protocol models.
+- `CLIENT_TYPE` and `ANTHROPIC_BASE_URL` in the server's environment override the entry, and can route a model somewhere the toggle did not anticipate.
+
+If a request does reach a client that rejects `fast_mode`, AgentHub refuses it **before any network request**: the session ends that turn immediately with the provider's message plus a pointer to the setting, and a deterministic rejection is never retried. An entry that stores `fast_mode = true` on a model that cannot serve it keeps its toggle in the dialog, marked unsupported, so it can always be switched off.
+
+The connectivity test sends the dialog's current toggle state, so "Test connection" surfaces a fast-mode rejection before saving. Background requests (session title generation, `describe_image` proxy reads) never carry fast mode — only the session's own requests do.
+
## Models decoupled from Agents
An Agent never binds a model: the model is chosen when a Session is created and stays locked for that Session; the same Agent can run different Sessions on different models. The in-session `/model` command changes models handoff-style: it opens a new session for the same Agent on the new model, keeping the current Workspace, whose first message carries a `[model_switch_from]` source block (the source session id and its Trace file path) — the history is not injected into the new context (some models require thinking payloads and `fidelity` on history replay, which cannot cross models); the model reads the Trace file itself when it needs it, and the source session stays untouched. The three `pricing` buckets feed the usage/cost center's per-Token accounting.
diff --git a/packages/docs/content/models.zh.md b/packages/docs/content/models.zh.md
index 018f84f2..8a99cb01 100644
--- a/packages/docs/content/models.zh.md
+++ b/packages/docs/content/models.zh.md
@@ -26,6 +26,7 @@ description: 经 AgentHub 单一网关接入模型,以 (provider, model_id)
| `client_type` | 协议提示(`openai-chat` 对应 Chat Completions、`openai-responses` 对应 Responses API、`ant-messages` 对应 Anthropic Messages 等);缺省由 AgentHub 按 model id 推断。自定义端点使用这三种通用协议客户端之一,Web 对话框可按 base URL 检测其中哪一种。0.4.2 之前的旧写法 `openai` 为已废弃别名,读取配置时归一化为 `openai-chat` |
| `display_name` | 显示名 |
| `vision` | 是否支持图像输入,默认 true |
+| `fast_mode` | 可选的快速模式(默认关闭):让该模型的会话请求进入厂商的快速推理档位,按溢价计费。只会持久化 `true`——Web 整表保存时省略该字段即清除。没有 fast 档位的模型会拒绝携带该参数的请求(见 [快速模式](#快速模式)) |
| `pricing` | 三档价格(单位 `usd_per_mtok`,USD 每百万 Token):`cache_read` / `cache_write` / `output` |
| `api_key` / `base_url` | 内联凭证,可留空;留空时 AgentHub 回退读环境变量 |
@@ -111,6 +112,34 @@ Custom 与自建分组走 AgentHub 的通用协议客户端,Web 对话框会
思考等级共五档:`none | low | medium | high | xhigh`,按 Agent 在 `system_config.yaml` 的 `model.thinking_level` 配置,默认 medium。Web 拾取器只提供 `low` 及以上档位(多数模型不支持关闭思考;`none` 仍是合法的已存值,能正常显示)。对话草稿页在模型选择器旁提供快捷拾取器:选定档位立即写回所选 Agent 的该项配置(切换后的档位即成为该 Agent 的新默认,自下一个 Session 生效)。进行中的会话里,思考等级是**逐轮参数**:输入区拾取器只列出各档位,初始即显示 Agent 配置的档位——用户未手动选择时自动跟随配置下发(请求不携带档位,配置的修改持续生效);选定某档后即固定为该会话的档位,随之后每次发送携带(仅作用于该会话的后续 Task,不写回 Agent 配置)。见 [配置参考](/configuration)。
+## 快速模式
+
+每个模型条目都可以选择进入厂商的快速推理档位(Web 模型弹窗中的「快速模式」开关、`penguin config model add` 的 `--fast-mode` / `--no-fast-mode`,或条目里的 `fast_mode = true`)。默认关闭;既有配置不受影响。打开开关会先弹出确认提示,因为它会改变该模型的计费。
+
+开启后,会话请求携带 AgentHub 的 `fast_mode` 参数:OpenAI 协议 client 发送 `service_tier: "priority"`,Anthropic 协议 client 发送 `speed: "fast"` 并附带 fast-mode beta 请求头。快速档位按厂商的溢价价目计费(MiniMax 为标准价的 1.5 倍,OpenAI 与 Anthropic 另有溢价价目表),而条目记录的按 Token 单价不会随之调整——不上调三档价格的话,快速模式用量的成本统计会偏低。
+
+### 哪些模型会出现该开关
+
+是否存在快速档位,由该模型路由到的 AgentHub client 决定,而不是由模型条目决定,因此开关只在该 client 确实会发送这个参数时才出现:
+
+| 路由到的 client | 快速模式 |
+| --- | --- |
+| OpenAI 协议(`openai_chat`、`openai_responses`、`gpt5_6`、`minimax_m3`) | 发送 `service_tier: "priority"` |
+| Anthropic 协议(`ant_messages`、`claude5`) | 发送 `speed: "fast"` 并附带 beta 请求头 |
+| Gemini、GLM、Kimi、DeepSeek、OpenAI embedding | 拒绝——不提供开关 |
+| Bedrock 上的 Claude,或 Claude 4.6 系列 id | 拒绝——不提供开关 |
+
+路由按条目的 `client_type` 判定,未设置时按 `model_id` 判定,所以同一个上游 id 可能落到不同 client:在网关分组下添加的 Kimi 模型(`client_type = "openai"`)可以使用快速模式,同一个 id 路由到 Kimi 自己的 client 时则不行。自建 base URL 的自定义模型仍然保留开关——它走 OpenAI 协议,背后也可能就是 OpenAI——但第三方服务端完全可能接受该参数却仍按标准档位处理。
+
+有两件事开关无法替你检查:
+
+- Anthropic 的快速模式是限量的 research preview:在你的组织获得授权之前,请求会返回 429 限流错误。Anthropic 协议的模型在确认弹窗里会给出这条提示。
+- 服务端环境变量 `CLIENT_TYPE` 与 `ANTHROPIC_BASE_URL` 会覆盖条目的配置,可能把模型路由到开关未曾预期的地方。
+
+如果请求最终仍到达了拒绝 `fast_mode` 的 client,AgentHub 会在**发起网络请求之前**拒绝:该轮会话立即结束,错误信息带上厂商原文与设置入口指引,确定性的拒绝不会重试。若某个条目在不支持的模型上存有 `fast_mode = true`,弹窗仍会显示该开关并标注不支持,以便随时关闭。
+
+连通性测试会携带弹窗当前的开关状态,因此「测试连通性」能在保存前暴露快速模式被拒的问题。后台请求(会话标题生成、`describe_image` 代读)不携带快速模式——只有会话自身的请求携带。
+
## 模型与 Agent 解耦
Agent 从不绑定模型:模型在创建 Session 时选定,并在该 Session 内锁定不变;同一个 Agent 可以在不同 Session 用不同模型运行。会话内的 `/model` 命令按 handoff 方式换模型:在同一 Agent 下新建一个使用新模型、沿用当前 Workspace 的会话,首条消息携带 `[model_switch_from]` 源块(源会话 id 与其 Trace 文件路径)——历史不注入新上下文(部分模型回放历史时必须携带 thinking 与 `fidelity`,不能跨模型),模型需要时按路径自行读取;原会话保持不变。`pricing` 三档价格供用量/成本中心按 Token 计费。
diff --git a/packages/docs/content/web-app.en.md b/packages/docs/content/web-app.en.md
index 80f74913..ad7c9b1b 100644
--- a/packages/docs/content/web-app.en.md
+++ b/packages/docs/content/web-app.en.md
@@ -94,7 +94,7 @@ Browse the Skill library by group, install Skills onto an Agent, or quick-invoke
## Model Configuration (/models)
-A per-Project model table grouped by provider. Models can be added and edited: identity is the `(provider, model_id)` pair, credentials are masked, and context window, max output tokens (a per-model cap overriding the Agent's `model.max_tokens` — lower it for small-context models), pricing, and the vision flag are configurable. You can set the default model and the vision model (which reads images on behalf of session models without image input), and run a connectivity test on any entry. Only Project owners can edit. For concepts, see [Models and Providers](/models).
+A per-Project model table grouped by provider. Models can be added and edited: identity is the `(provider, model_id)` pair, credentials are masked, and context window, max output tokens (a per-model cap overriding the Agent's `model.max_tokens` — lower it for small-context models), pricing, the vision flag, and fast mode (off by default: faster output at the provider's premium tier — the toggle is shown only for models whose AgentHub client can serve it, and switching it on confirms the premium billing first) are configurable. A model with fast mode on is badged in the list. You can set the default model and the vision model (which reads images on behalf of session models without image input), and run a connectivity test on any entry — the test carries the dialog's current fast-mode toggle, so a rejection surfaces before saving. Only Project owners can edit. For concepts, see [Models and Providers](/models).
## Usage (/usage)
diff --git a/packages/docs/content/web-app.zh.md b/packages/docs/content/web-app.zh.md
index 99805af7..5de2caa6 100644
--- a/packages/docs/content/web-app.zh.md
+++ b/packages/docs/content/web-app.zh.md
@@ -93,7 +93,7 @@ Memory 标签页的开关拨动即写入,不参与标签页的保存按钮,
## 模型配置(/models)
-按 Provider 分组展示当前 Project 的模型表格。支持添加与编辑模型:以 `(provider, model_id)` 为唯一标识,凭据以掩码显示,可配置上下文窗口、最大输出长度(按模型的输出上限,覆盖 Agent 的 `model.max_tokens`——小上下文模型建议调低)、定价与视觉(vision)标记;可设置默认模型与视觉模型(在会话模型不支持图片输入时代为读图),并对任一模型做连通性测试。仅 Project Owner 可编辑,概念说明见[模型与 Provider](/models)。
+按 Provider 分组展示当前 Project 的模型表格。支持添加与编辑模型:以 `(provider, model_id)` 为唯一标识,凭据以掩码显示,可配置上下文窗口、最大输出长度(按模型的输出上限,覆盖 Agent 的 `model.max_tokens`——小上下文模型建议调低)、定价、视觉(vision)标记与快速模式(默认关闭:进入厂商的溢价快速档位、输出更快——该开关只对 AgentHub client 支持该档位的模型显示,打开时会先确认溢价计费);开启了快速模式的模型会在列表中带角标;可设置默认模型与视觉模型(在会话模型不支持图片输入时代为读图),并对任一模型做连通性测试——测试会携带弹窗当前的快速模式开关状态,被拒时在保存前即可发现。仅 Project Owner 可编辑,概念说明见[模型与 Provider](/models)。
## 用量统计(/usage)
diff --git a/packages/server/src/api/types.ts b/packages/server/src/api/types.ts
index ad21a511..e816f5cf 100644
--- a/packages/server/src/api/types.ts
+++ b/packages/server/src/api/types.ts
@@ -304,6 +304,13 @@ export interface ModelInfo {
* seeded per-Agent default (32000), which cannot fit into e.g. a 32k context window.
*/
maxTokens?: number;
+ /**
+ * Per-model fast mode (TOML `fast_mode` annotation; user-only, never preset by the
+ * built-in catalog): when true, session requests opt into the provider's faster serving
+ * tier at premium pricing (AgentHub UniConfig `fast_mode`). Only `true` is reported;
+ * unset = off. Models without a fast tier reject requests carrying it.
+ */
+ fastMode?: boolean;
pricing?: ModelPricingDto;
/** Environment variable name to fall back to when api_key is empty (e.g. ANTHROPIC_API_KEY); unset if no known fallback. */
envKey?: string;
@@ -348,6 +355,8 @@ export interface ModelUpdateEntry {
vision?: boolean;
/** Per-model max output tokens, a positive integer (wins over the Agent config); omitted = inherit the Agent value (the annotation is cleared). */
maxTokens?: number;
+ /** Per-model fast mode: only `true` is persisted; omitted or `false` clears the annotation (absent = off). */
+ fastMode?: boolean;
pricing?: ModelPricingDto;
/** Providing it overwrites and updates createdAt; omitting it keeps the existing value. */
apiKey?: string;
@@ -390,6 +399,12 @@ export interface ModelTestRequest {
baseUrl?: string | null;
/** AgentHub client protocol; required for unsaved custom models (otherwise the id can't be auto-routed). */
clientType?: string;
+ /**
+ * Test with fast mode (the frontend always sends the form's current value, so an unsaved
+ * toggle — either direction — is what gets tested); omitted falls back to the stored
+ * annotation. Lets "Test connection" surface a fast-mode rejection before saving.
+ */
+ fastMode?: boolean;
}
/**
diff --git a/packages/server/src/http/routes/models.ts b/packages/server/src/http/routes/models.ts
index 65288c80..2802b73e 100644
--- a/packages/server/src/http/routes/models.ts
+++ b/packages/server/src/http/routes/models.ts
@@ -103,6 +103,12 @@ function parseModelsUpdate(body: Record<string, unknown>): ModelsUpdateRequest {
}
entry.maxTokens = m.maxTokens;
}
+ if (m.fastMode !== undefined) {
+ if (typeof m.fastMode !== "boolean") {
+ throw badRequest(`models[${i}].fastMode must be a boolean.`);
+ }
+ entry.fastMode = m.fastMode;
+ }
if (m.pricing !== undefined) {
const p = m.pricing as Record<string, unknown>;
if (p === null || typeof p !== "object" || Array.isArray(p)) {
@@ -228,6 +234,10 @@ export function modelsRoutes(deps: AppDeps): Hono<AppEnv> {
if (typeof body.clientType !== "string") throw badRequest("clientType must be a string.");
if (body.clientType) req.clientType = body.clientType;
}
+ if (body.fastMode !== undefined) {
+ if (typeof body.fastMode !== "boolean") throw badRequest("fastMode must be a boolean.");
+ req.fastMode = body.fastMode;
+ }
return c.json(await deps.projectConfigService.testModel(projectId, req));
});
diff --git a/packages/server/src/services/project-config-service.ts b/packages/server/src/services/project-config-service.ts
index 3eb8a8a4..38ee1212 100644
--- a/packages/server/src/services/project-config-service.ts
+++ b/packages/server/src/services/project-config-service.ts
@@ -485,6 +485,11 @@ export class ProjectConfigService {
// 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));
+ // Fast mode follows the form draft like baseUrl (the frontend always sends the current
+ // toggle), falling back to the stored annotation: the probe then exercises exactly the
+ // serving tier sessions would use, so a model rejecting fast_mode fails the test with
+ // the actionable message before the config is saved.
+ const fastMode = req.fastMode ?? entry.fast_mode === true;
const startedAt = Date.now();
try {
@@ -499,6 +504,7 @@ export class ProjectConfigService {
...(apiKey ? { apiKey } : {}),
...(baseUrl ? { baseUrl } : {}),
...(clientType ? { clientType } : {}),
+ ...(fastMode ? { fastMode: true } : {}),
tools: [],
thinkingLevel: "none",
// Speed mode pairs a raised cap with a prompt that keeps generating (see
@@ -622,6 +628,8 @@ export class ProjectConfigService {
const vision = typeof m.vision === "boolean" ? m.vision : cat?.supportsVision;
// Output cap: TOML annotation only (user-owned; the built-in catalog never presets it).
const maxTokens = optNum(m.max_tokens);
+ // Fast mode: TOML annotation only (user-owned); only `true` is reported — absent = off.
+ const fastMode = m.fast_mode === true ? true : undefined;
// Display name: the explicit TOML field (user-edited) takes priority, then the built-in catalog.
const displayName = optStr(m.display_name) ?? cat?.displayName;
// credential is inlined on the entry: a credential block is emitted if either api_key or base_url is present.
@@ -642,6 +650,7 @@ export class ProjectConfigService {
...(clientType ? { clientType } : {}),
...(vision !== undefined ? { vision } : {}),
...(maxTokens !== undefined ? { maxTokens } : {}),
+ ...(fastMode !== undefined ? { fastMode } : {}),
...(envKey ? { envKey } : {}),
...(pricingDto ? { pricing: pricingDto } : {}),
...(apiKey !== undefined || credBaseUrl !== undefined
@@ -719,6 +728,7 @@ export class ProjectConfigService {
delete next.client_type;
delete next.vision;
delete next.max_tokens;
+ delete next.fast_mode;
delete next.pricing;
delete next.display_name;
// Leftover key from the old concatenated format (request_model_id): defensively stripped, never written to disk again.
@@ -740,6 +750,8 @@ export class ProjectConfigService {
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).
if (entry.maxTokens !== undefined) next.max_tokens = entry.maxTokens;
+ // Off by default: only `true` is written to disk (absent = off); omitted or false clears the annotation.
+ if (entry.fastMode === true) next.fast_mode = true;
if (entry.pricing !== undefined) {
next.pricing = {
unit: "usd_per_mtok",
diff --git a/packages/server/test/models-fast-mode.test.ts b/packages/server/test/models-fast-mode.test.ts
new file mode 100644
index 00000000..d215cb92
--- /dev/null
+++ b/packages/server/test/models-fast-mode.test.ts
@@ -0,0 +1,78 @@
+/**
+ * Round-trip of a model's fast_mode annotation (premium faster serving tier) through
+ * PUT/GET: only `true` is persisted and read back; false or omission clears it (absent =
+ * off — existing configs are untouched by the feature); a non-boolean value returns 400.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { ModelsResponse, ProjectCreateResponse } from "../src/api/types.js";
+import { apiClient, createTestApp, provisionUser } from "./helpers.js";
+import type { TestApp } from "./helpers.js";
+
+describe("models fast-mode annotation", () => {
+ let t: TestApp;
+ let owner: ReturnType<typeof apiClient>;
+ let projectId: string;
+
+ beforeEach(async () => {
+ t = await createTestApp();
+ const a = await provisionUser(t.app, "owner_f");
+ owner = apiClient(t.app, a.cookie);
+ const created = (await (
+ await owner.post("/api/projects", { projectId: "owner_f-fast", name: "fast project" })
+ ).json()) as ProjectCreateResponse;
+ projectId = created.project.projectId;
+ });
+ afterEach(async () => {
+ await t.cleanup();
+ });
+
+ it("fastMode=true persists and reads back; false or omitted = off (no field)", async () => {
+ const put = await owner.put(`/api/projects/${projectId}/models`, {
+ models: [
+ { provider: "custom", modelId: "fast-model", fastMode: true },
+ // Explicit false is accepted but never persisted: absent = off is the contract.
+ { provider: "custom", modelId: "slow-model", fastMode: false },
+ { provider: "custom", modelId: "plain-model" },
+ ],
+ });
+ expect(put.status).toBe(200);
+ const body = (await put.json()) as ModelsResponse;
+ const byId = (id: string) =>
+ body.models.find((m) => m.provider === "custom" && m.modelId === id)!;
+ expect(byId("fast-model").fastMode).toBe(true);
+ expect("fastMode" in byId("slow-model")).toBe(false);
+ expect("fastMode" in byId("plain-model")).toBe(false);
+
+ // A fresh GET reads the same annotation back from disk.
+ const get = (await (
+ await owner.get(`/api/projects/${projectId}/models`)
+ ).json()) as ModelsResponse;
+ expect(
+ get.models.find((m) => m.provider === "custom" && m.modelId === "fast-model")!.fastMode,
+ ).toBe(true);
+
+ // PUT again without fastMode: whole-table replace semantics clear the annotation
+ // (back to the default of off).
+ const put2 = await owner.put(`/api/projects/${projectId}/models`, {
+ models: [{ provider: "custom", modelId: "fast-model" }],
+ });
+ const body2 = (await put2.json()) as ModelsResponse;
+ expect("fastMode" in body2.models[0]!).toBe(false);
+ });
+
+ it("a preset model takes the annotation too (user-owned; the catalog never presets it)", async () => {
+ const put = await owner.put(`/api/projects/${projectId}/models`, {
+ models: [{ provider: "deepseek", modelId: "deepseek-v4-pro", fastMode: true }],
+ });
+ expect(put.status).toBe(200);
+ const body = (await put.json()) as ModelsResponse;
+ expect(body.models[0]!.fastMode).toBe(true);
+ });
+
+ it("non-boolean fastMode returns 400", async () => {
+ const bad = await owner.put(`/api/projects/${projectId}/models`, {
+ models: [{ provider: "custom", modelId: "m-1", fastMode: "yes" }],
+ });
+ expect(bad.status).toBe(400);
+ });
+});
diff --git a/packages/web/src/features/models/catalog-sync.ts b/packages/web/src/features/models/catalog-sync.ts
index 5d9fe33a..eb2b9dac 100644
--- a/packages/web/src/features/models/catalog-sync.ts
+++ b/packages/web/src/features/models/catalog-sync.ts
@@ -32,9 +32,11 @@ function presetToRow(p: PresetEntry): RowState {
modelId: p.model_id,
original: null,
...presetFields(p),
- // The output cap is user-owned, not catalog-owned (deliberately outside presetFields,
- // so a sync never clobbers it on existing rows): fresh rows inherit the Agent setting.
+ // The output cap and fast mode are user-owned, not catalog-owned (deliberately outside
+ // presetFields, so a sync never clobbers them on existing rows): fresh rows inherit the
+ // Agent setting / default to off.
maxTokens: "",
+ fastMode: false,
originalBaseUrl: "",
apiKeyInput: "",
clearApiKey: false,
diff --git a/packages/web/src/features/models/models-page.tsx b/packages/web/src/features/models/models-page.tsx
index f7a245b5..d14b1ef5 100644
--- a/packages/web/src/features/models/models-page.tsx
+++ b/packages/web/src/features/models/models-page.tsx
@@ -68,11 +68,12 @@ import {
MODEL_PROVIDERS,
canonicalClientType,
catalogEntryFor,
+ fastModeProtocol,
modelHomepageUrl,
providerInfo,
resolveModelEnv,
} from "@prismshadow/penguin-core/model-catalog";
-import type { ModelProviderInfo } from "@prismshadow/penguin-core/model-catalog";
+import type { FastModeProtocol, ModelProviderInfo } from "@prismshadow/penguin-core/model-catalog";
import { groupModelRows, isFreeModel, sameModelRef, userProviderInfo } from "./model-grouping";
import { protocolPathForModel } from "./protocol-path";
import { ProtocolSuffixMenu } from "./protocol-suffix";
@@ -224,6 +225,12 @@ 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;
+ /**
+ * Per-model fast mode (premium faster serving tier, AgentHub `fast_mode`): off by default;
+ * user-only, never preset by the catalog, editable on every model (preset ones included).
+ * Models without a fast tier reject requests carrying it, hence the standing hint while ON.
+ */
+ fastMode: boolean;
/**
* AgentHub client protocol. Empty for preset models (auto-routed from the model id) and
* for a NEW custom model, which starts with nothing selected until the user picks from
@@ -321,6 +328,7 @@ export function toRow(m: ModelsResponse["models"][number]): RowState {
vision: m.vision !== false,
contextWindow: m.contextWindow !== undefined ? String(m.contextWindow) : "",
maxTokens: m.maxTokens !== undefined ? String(m.maxTokens) : "",
+ fastMode: m.fastMode === true,
clientType: m.clientType ?? "",
cacheRead: m.pricing ? String(m.pricing.cacheRead) : "",
cacheWrite: m.pricing ? String(m.pricing.cacheWrite) : "",
@@ -336,6 +344,58 @@ export function toRow(m: ModelsResponse["models"][number]): RowState {
return row;
}
+/**
+ * Whether the model dialog offers the fast-mode switch for a draft row, and on which protocol
+ * the parameter would travel.
+ *
+ * `protocol` is AgentHub's own answer (see fastModeProtocol): `undefined` means the routed
+ * client rejects `fast_mode` — or the id routes to no client at all — so arming the switch
+ * could only produce a turn-killing error, and it is not offered. `show` adds the one
+ * exception: a row that already stores fast mode keeps its switch regardless, because a
+ * value that arrived another way (a hand-edited config, `penguin config model add
+ * --fast-mode`, or an upstream id renamed afterwards) has to remain switchable off — the
+ * runtime rejection tells the user to turn it off in the model settings, and that has to be
+ * true. `protocol` also picks the warning copy: only Anthropic's fast mode is a gated
+ * research preview.
+ *
+ * The client type is resolved through protocolForPersist — the one the entry will actually
+ * be SAVED with — rather than the raw field, for the same reason envHintClientType exists: a
+ * custom-like group leaves the protocol empty until detection or a manual pick fills it in,
+ * and fastModeProtocol then falls back to routing by model id. Typing an id that routes to a
+ * client with no fast tier (`kimi-k3`, `gemini-3-pro`) into a custom group would hide a
+ * switch that the persisted `openai-chat` entry can in fact serve. An empty result keeps the
+ * id-based routing the preset and vendor groups genuinely use.
+ */
+export function fastModeState(
+ row: Pick<RowState, "provider" | "modelId" | "clientType" | "baseUrl" | "fastMode">,
+): { protocol: FastModeProtocol | undefined; show: boolean } {
+ const protocol = fastModeProtocol(
+ row.modelId.trim(),
+ protocolForPersist(row.provider, row.clientType) || undefined,
+ row.baseUrl.trim() || undefined,
+ );
+ return { protocol, show: protocol !== undefined || row.fastMode };
+}
+
+/**
+ * Layout of the dialog's capability row, which carries the vision-support and fast-mode
+ * switches side by side in the two-up grid.
+ *
+ * Neither switch is guaranteed to be there: vision is read-only catalog metadata on preset
+ * models (no switch at all), and fast mode is withheld wherever the routed client rejects the
+ * parameter (see fastModeState). So the pair is a coincidence, not an invariant, and the row
+ * degrades in both directions — with neither switch it must not be rendered at all (an empty
+ * grid still draws the parent's `space-y` gap), and with exactly one the lone switch spans
+ * both columns rather than sitting in a half-width cell next to dead space.
+ */
+export function capabilityRow(present: { vision: boolean; fastMode: boolean }): {
+ show: boolean;
+ cellClass: string | undefined;
+} {
+ const both = present.vision && present.fastMode;
+ return { show: present.vision || present.fastMode, cellClass: both ? undefined : "col-span-2" };
+}
+
/** Row edit state -> wire entry (exported for unit tests): the single funnel into the config PUT. */
export function rowToEntry(row: RowState): ModelUpdateEntry {
// provider and modelId are always submitted as separate fields ((provider, modelId) is the entry's unique key, no concatenation).
@@ -358,6 +418,8 @@ export function rowToEntry(row: RowState): ModelUpdateEntry {
// Output cap ("" = inherit the Agent setting): submitted only when filled; omitting clears the stored annotation.
const mt = Number(row.maxTokens.trim());
if (row.maxTokens.trim() && Number.isFinite(mt) && mt > 0) entry.maxTokens = mt;
+ // Off by default: submitted only when enabled (omitting clears the stored annotation; the server never persists false).
+ if (row.fastMode) entry.fastMode = true;
const cr = Number(row.cacheRead.trim());
const cwr = Number(row.cacheWrite.trim());
const out = Number(row.output.trim());
@@ -1042,6 +1104,10 @@ function ModelCard({
{isFreeModel(row) && <Badge tone="yellow">{S.models.freeBadge}</Badge>}
{row.vision && <Badge tone="green">{S.models.visionBadge}</Badge>}
{isVisionModel && <Badge tone="amber">{S.models.visionModelBadge}</Badge>}
+ {/* Fast mode moves the model onto a premium price list that the recorded prices do not
+ reflect, so it has to be visible without opening the dialog (amber, like the other
+ badge that flags a standing cost/behavior choice). */}
+ {row.fastMode && <Badge tone="amber">{S.models.fastModeBadge}</Badge>}
</span>
{/* Upstream id in small text (grouping already separates by group, no composite id is
shown anymore); when there's no display name, the main line is already the
@@ -1137,6 +1203,7 @@ function ModelDialog({
vision: !isCustomLikeGroup(addProvider),
contextWindow: "",
maxTokens: "",
+ fastMode: false,
// No protocol is preselected for a custom / user-defined group: it is detected from
// the endpoint (on demand, or on save while still unset) or picked by hand. Vendor
// groups auto-route by model id, and gateways keep their preset Chat Completions pin.
@@ -1160,6 +1227,8 @@ function ModelDialog({
* (Adding a new custom model isn't confirmed: opening the dialog is itself a clear intent.)
*/
const [confirming, setConfirming] = useState<DialogAction | null>(null);
+ /** Fast mode is being switched ON and awaits the premium-billing warning's confirmation. */
+ const [confirmingFastMode, setConfirmingFastMode] = useState(false);
/** Protocol detection in progress (custom / user-defined groups only). */
const [detecting, setDetecting] = useState(false);
/**
@@ -1187,6 +1256,18 @@ function ModelDialog({
const isNew = row === null;
const preset = row !== null && isPreset(row);
+ // Read from the live form, not the saved row, so editing the upstream id, the protocol or
+ // the base URL updates the answer as it is typed.
+ const { protocol: fastProtocol, show: showFastMode } = fastModeState(form);
+
+ // Vision support and fast mode share one row; either can be missing, so the row's own
+ // presence and the cell width follow from which switches are actually there (capabilityRow).
+ const showVision = !preset;
+ const { show: showCapabilityRow, cellClass: toggleCellClass } = capabilityRow({
+ vision: showVision,
+ fastMode: showFastMode,
+ });
+
const set = (patch: Partial<RowState>) => {
setForm((prev) => ({ ...prev, ...patch }));
// Clear the error marker for whichever field was changed (keys match RowState field names).
@@ -1223,6 +1304,10 @@ function ModelDialog({
if (key) body.apiKey = key;
else if (form.clearApiKey) body.clearApiKey = true;
if (form.clientType.trim()) body.clientType = form.clientType.trim();
+ // Like base URL, the form's current value is always sent (not just when true): an
+ // unsaved toggle-off must override a stored fast_mode=true, so the probe tests
+ // exactly the draft's serving tier.
+ body.fastMode = form.fastMode;
const res = await api.testModel(projectId, body);
if (res.ok) toastSuccess(S.models.testOk(res.latencyMs ?? 0));
else toastError(S.models.testFailed(res.message ?? ""));
@@ -2107,59 +2192,145 @@ function ModelDialog({
</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 the
- label (per owner: no full-row stretch, no standing explanation text). Only the OFF
- state shows one small muted line: images are then read via the configured vision
- proxy model (describe_image). */}
- {!preset && (
- <div>
- {/* Detect sits inline after the switch — the protocol control's idiom, but next
- to the setting it fills in rather than at a field's top-right, since this row
- has no field to hang off. Always clickable, single-flight, toast-only, like
- protocol detection; it just costs a real (tiny) completion, so it never runs
- on its own. */}
- <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
- <label
- className={`inline-flex items-center gap-2 ${canEdit ? "cursor-pointer" : "cursor-not-allowed"}`}
- >
- <span className="text-xs font-semibold text-gray-600 dark:text-gray-400">
- {S.models.vision}
- </span>
- <Switch
- checked={form.vision}
- disabled={!canEdit}
- onChange={(vision) => set({ vision })}
- aria-label={S.models.vision}
- />
- </label>
- {canEdit && (
- <button
- type="button"
- disabled={visionDetecting}
- onClick={() => void detectVisionFromButton()}
- title={S.models.detectVisionHint}
- className="flex shrink-0 items-center gap-1 text-xs text-brand-600 underline-offset-2 hover:underline disabled:cursor-not-allowed disabled:text-gray-400 disabled:no-underline dark:text-brand-300 dark:disabled:text-gray-500"
- >
- {visionDetecting && (
- <span
- aria-hidden
- className="inline-block h-2.5 w-2.5 shrink-0 animate-spin rounded-full border border-current border-t-transparent"
+ {/* 6) Capability switches — vision support and fast mode side by side on one row,
+ reusing the dialog's two-up grid (same `grid grid-cols-2 items-start gap-2` as the
+ context-window / max-tokens row above, which already carries two full inputs at
+ phone width; two compact switches are strictly narrower). `items-start` keeps both
+ cells top-aligned when only one of them grows a muted hint line, and the hint text
+ wraps inside its half-width cell rather than overflowing. Each switch is optional,
+ so the row itself is conditional and a lone switch takes the whole width
+ (toggleCellClass) — the layout must not depend on both being present. */}
+ {showCapabilityRow && (
+ <div className="grid grid-cols-2 items-start gap-2">
+ {/* Vision capability: for preset models it's flagged by the built-in catalog
+ (read-only, so no cell at all); custom models toggle it here — an iOS-style
+ switch sitting inline right next to the label (per owner: no full-row stretch,
+ no standing explanation text). Only the OFF state shows one small muted line:
+ images are then read via the configured vision proxy model (describe_image). */}
+ {showVision && (
+ <div className={toggleCellClass}>
+ {/* Detect sits inline after the switch — the protocol control's idiom, but next
+ to the setting it fills in rather than at a field's top-right, since this row
+ has no field to hang off. Always clickable, single-flight, toast-only, like
+ protocol detection; it just costs a real (tiny) completion, so it never runs
+ on its own. `flex-wrap` is what lets the switch and the trigger share a
+ half-width cell: when they do not both fit, the trigger drops onto its own
+ line inside the cell instead of widening the grid column. */}
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+ <label
+ className={`inline-flex items-center gap-2 ${canEdit ? "cursor-pointer" : "cursor-not-allowed"}`}
+ >
+ <span className="text-xs font-semibold text-gray-600 dark:text-gray-400">
+ {S.models.vision}
+ </span>
+ <Switch
+ checked={form.vision}
+ disabled={!canEdit}
+ onChange={(vision) => set({ vision })}
+ aria-label={S.models.vision}
/>
+ </label>
+ {canEdit && (
+ <button
+ type="button"
+ disabled={visionDetecting}
+ onClick={() => void detectVisionFromButton()}
+ title={S.models.detectVisionHint}
+ className="flex shrink-0 items-center gap-1 text-xs text-brand-600 underline-offset-2 hover:underline disabled:cursor-not-allowed disabled:text-gray-400 disabled:no-underline dark:text-brand-300 dark:disabled:text-gray-500"
+ >
+ {visionDetecting && (
+ <span
+ aria-hidden
+ className="inline-block h-2.5 w-2.5 shrink-0 animate-spin rounded-full border border-current border-t-transparent"
+ />
+ )}
+ {visionDetecting ? S.models.detectingVision : S.models.detectVision}
+ </button>
)}
- {visionDetecting ? S.models.detectingVision : S.models.detectVision}
- </button>
- )}
- </div>
- {!form.vision && (
- <p className="mt-1 text-xs text-gray-400 dark:text-gray-500">
- {S.models.visionOffProxyHint}
- </p>
+ </div>
+ {!form.vision && (
+ <p className="mt-1 text-xs text-gray-400 dark:text-gray-500">
+ {S.models.visionOffProxyHint}
+ </p>
+ )}
+ </div>
+ )}
+
+ {/* Fast mode: per-model opt-in to the provider's faster serving tier (premium
+ pricing). Offered only where AgentHub's routed client actually puts the
+ parameter on the wire (fastModeProtocol) — a model whose client rejects it
+ would otherwise arm a switch that kills the next turn. Same inline-switch shape
+ as vision; the one small muted line appears in the non-default (ON) state, and
+ the label's hover title reveals it before toggling. Enabling is confirmed
+ (premium billing), disabling is immediate. */}
+ {showFastMode && (
+ <div className={toggleCellClass}>
+ <label
+ className={`inline-flex items-center gap-2 ${canEdit ? "cursor-pointer" : "cursor-not-allowed"}`}
+ title={S.models.fastModeHint}
+ >
+ <span className="text-xs font-semibold text-gray-600 dark:text-gray-400">
+ {S.models.fastMode}
+ </span>
+ <Switch
+ checked={form.fastMode}
+ disabled={!canEdit}
+ onChange={(fastMode) => {
+ // Only the ON direction is confirmed: it is the one that starts spending
+ // at premium rates. Turning it off costs nothing and must stay one click
+ // — it is the documented escape from a model that rejects the parameter.
+ if (fastMode) setConfirmingFastMode(true);
+ else set({ fastMode: false });
+ }}
+ aria-label={S.models.fastMode}
+ />
+ </label>
+ {form.fastMode && (
+ <p className="mt-1 text-xs text-gray-400 dark:text-gray-500">
+ {S.models.fastModeHint}
+ </p>
+ )}
+ {/* Reachable only for a stored annotation the rule would not have offered (a
+ hand-edited config, `--fast-mode`, or an id renamed after the fact): the
+ switch is kept visible precisely so it can be turned off, and says why it
+ should be. */}
+ {form.fastMode && fastProtocol === undefined && (
+ <p className="mt-1 text-xs text-amber-600 dark:text-amber-500">
+ {S.models.fastModeUnsupported}
+ </p>
+ )}
+ </div>
)}
</div>
)}
</div>
+ {/* Premium-billing warning, stacked on the config dialog the same way: fast mode moves
+ the model onto the provider's premium price list while the recorded per-token prices
+ stay standard, so the Cost center under-reports it — and on the Anthropic protocol
+ access is a gated research preview that answers 429 until granted. Warning tone (the
+ alert triangle) rather than the save pencil: nothing is being written yet, the point
+ is what enabling costs. */}
+ {confirmingFastMode && (
+ <ConfirmModal
+ open
+ title={S.models.fastModeConfirmTitle}
+ tone="danger"
+ onClose={() => setConfirmingFastMode(false)}
+ onConfirm={() => {
+ setConfirmingFastMode(false);
+ set({ fastMode: true });
+ }}
+ >
+ <p className="text-sm text-gray-700 dark:text-gray-300">{S.models.fastModeConfirmBody}</p>
+ {fastProtocol === "anthropic" && (
+ <p className="mt-2 text-sm text-gray-700 dark:text-gray-300">
+ {S.models.fastModeConfirmPreview}
+ </p>
+ )}
+ </ConfirmModal>
+ )}
+
{/* Confirmation before writing config (save / set default / set as vision proxy model / remove): stacked on top of the config dialog. */}
{confirming && (
<ConfirmModal
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index dda57f8d..fd49ae9f 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -540,6 +540,17 @@ export const en: Strings = {
detectVisionOk: "This model accepts images; vision turned on",
detectVisionNo: "This model does not accept images; vision left off",
visionOffProxyHint: "Images are read via the vision proxy model",
+ fastMode: "Fast mode",
+ fastModeHint:
+ "Faster output, billed at the provider's premium tier; the Cost center still counts it at the entry's standard prices",
+ fastModeUnsupported:
+ "This model does not support fast mode — turn it off, or its requests will fail",
+ fastModeConfirmTitle: "Enable fast mode",
+ fastModeConfirmBody:
+ "Fast mode is billed at the provider's premium price list (MiniMax charges 1.5x standard; OpenAI and Anthropic publish separate premium rates). The entry's recorded per-token prices are not adjusted, so the Cost center will under-report this usage.",
+ fastModeConfirmPreview:
+ "Anthropic's fast mode is a limited research preview: until your organization is granted access, requests return a 429 rate-limit error.",
+ fastModeBadge: "Fast",
visionBadge: "Vision",
freeBadge: "Free",
visionModelBadge: "Proxy vision",
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 8e9b1833..7beb76dc 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -518,6 +518,22 @@ export const zh = {
detectVisionNo: "该模型不接受图片输入,视觉保持关闭",
/** Shown only while the vision switch is OFF: images are then read via the configured vision proxy model (describe_image). */
visionOffProxyHint: "使用视觉代理模型读图",
+ /** Switch label for the per-model fast mode (the provider's premium faster serving tier); the switch is only rendered for models whose AgentHub client can carry the parameter. */
+ fastMode: "快速模式",
+ /** Shown while the fast-mode switch is ON (and as the label's hover title): what it buys, and that the recorded prices do not follow the premium rate. */
+ fastModeHint: "输出更快,按厂商的溢价档位计费;成本中心仍按条目记录的标准单价统计",
+ /** Amber line under an ON switch on a model whose client rejects the parameter (a hand-edited config or a renamed id): the switch stays visible only so it can be turned off. */
+ fastModeUnsupported: "该模型不支持快速模式,请关闭,否则请求会失败",
+ /** Accessible name of the warning dialog raised when the fast-mode switch is turned ON. */
+ fastModeConfirmTitle: "开启快速模式",
+ /** Body of that warning: premium billing, and that the recorded prices do not follow it. */
+ fastModeConfirmBody:
+ "快速模式按厂商的溢价价目计费(MiniMax 为标准价的 1.5 倍,OpenAI 与 Anthropic 另有溢价价目表)。条目记录的按 Token 单价不会随之调整,成本中心会低估这部分用量。",
+ /** Extra paragraph shown only for Anthropic-protocol models: fast mode there is a gated research preview. */
+ fastModeConfirmPreview:
+ "Anthropic 的快速模式目前是限量的 research preview:在你的组织获得授权之前,请求会返回 429 限流错误。",
+ /** Badge on a model row whose fast mode is on: a standing premium-billing choice should be visible without opening the dialog. */
+ fastModeBadge: "快速",
visionBadge: "视觉",
/** Light-yellow badge on zero-cost models (all three price buckets 0, e.g. the :free variants and openrouter/free). */
freeBadge: "免费",
diff --git a/packages/web/test/catalog-sync.test.ts b/packages/web/test/catalog-sync.test.ts
index 28f63a73..549b612f 100644
--- a/packages/web/test/catalog-sync.test.ts
+++ b/packages/web/test/catalog-sync.test.ts
@@ -17,6 +17,7 @@ function makeRow(partial: Partial<RowState> & Pick<RowState, "provider" | "model
vision: true,
contextWindow: "",
maxTokens: "",
+ fastMode: false,
clientType: "",
cacheRead: "",
cacheWrite: "",
diff --git a/packages/web/test/models-input.test.ts b/packages/web/test/models-input.test.ts
index 1640b24e..938839eb 100644
--- a/packages/web/test/models-input.test.ts
+++ b/packages/web/test/models-input.test.ts
@@ -12,9 +12,11 @@
*/
import { describe, expect, it } from "vitest";
import {
+ capabilityRow,
clientTypeAfterProviderChange,
decimalOnly,
digitsOnly,
+ fastModeState,
nextPointers,
rowRef,
toRow,
@@ -88,6 +90,18 @@ describe("toRow (DTO → row edit state)", () => {
const plain = toRow({ provider: "custom", modelId: "local-qwen", isDefault: false });
expect(plain.maxTokens).toBe("");
});
+
+ it("carries the per-model fast mode through; absent = off (the toggle's default)", () => {
+ const fast = toRow({
+ provider: "custom",
+ modelId: "local-qwen",
+ fastMode: true,
+ isDefault: false,
+ });
+ expect(fast.fastMode).toBe(true);
+ const plain = toRow({ provider: "custom", modelId: "local-qwen", isDefault: false });
+ expect(plain.fastMode).toBe(false);
+ });
});
describe("nextPointers (where the default/vision-agent model pointers land after save; always paired)", () => {
@@ -182,3 +196,165 @@ describe("nextPointers (where the default/vision-agent model pointers land after
});
});
});
+
+describe("fastModeState (whether the dialog offers the fast-mode switch, and on which protocol)", () => {
+ // The provider defaults to a real vendor group, whose entries are auto-routed by a
+ // catalog-known model id — the custom-like groups, which resolve to a protocol instead,
+ // are exercised explicitly below.
+ const draft = (partial: {
+ modelId: string;
+ provider?: string;
+ clientType?: string;
+ baseUrl?: string;
+ fastMode?: boolean;
+ }) => ({
+ provider: partial.provider ?? "anthropic",
+ modelId: partial.modelId,
+ clientType: partial.clientType ?? "",
+ baseUrl: partial.baseUrl ?? "",
+ fastMode: partial.fastMode ?? false,
+ });
+
+ it("offers it where AgentHub's routed client carries the parameter, with the protocol", () => {
+ // Gateway / custom rows pin the OpenAI protocol; first-party Claude ids take the
+ // Anthropic one, which is what selects the research-preview paragraph in the warning.
+ expect(fastModeState(draft({ modelId: "z-ai/glm-5.2", clientType: "openai" }))).toEqual({
+ protocol: "openai",
+ show: true,
+ });
+ expect(fastModeState(draft({ modelId: "claude-fable-5" }))).toEqual({
+ protocol: "anthropic",
+ show: true,
+ });
+ expect(fastModeState(draft({ modelId: "gpt-5.5" })).protocol).toBe("openai");
+ });
+
+ it("withholds it where the client would reject the parameter", () => {
+ // The whole point of the gate: these ids would fail the next turn with fast mode on.
+ for (const modelId of ["gemini-3.5-flash", "glm-5.2", "kimi-k3", "deepseek-v4-pro"]) {
+ expect(fastModeState(draft({ modelId })), modelId).toEqual({
+ protocol: undefined,
+ show: false,
+ });
+ }
+ // Claude 4.6 is refused by name even though the client serves the family, and Bedrock
+ // has no fast tier at all — the base URL is read from the draft, not the saved row.
+ expect(fastModeState(draft({ modelId: "claude-sonnet-4-6" })).show).toBe(false);
+ expect(
+ fastModeState(draft({ modelId: "claude-fable-5", baseUrl: "bedrock://us-east-1" })).show,
+ ).toBe(false);
+ });
+
+ it("keeps the switch on a row that already stores fast mode, so it can always be turned off", () => {
+ // A value that arrived by hand-edited TOML or `--fast-mode` must stay switchable off:
+ // the runtime rejection tells the user to turn it off in the model settings.
+ const stranded = fastModeState(draft({ modelId: "kimi-k3", fastMode: true }));
+ expect(stranded.show).toBe(true);
+ // ...but the protocol stays undefined, which is what raises the "not supported" warning
+ // line instead of pretending the model can serve it.
+ expect(stranded.protocol).toBeUndefined();
+ });
+
+ it("follows the draft as it is typed: an unsaved protocol change flips the answer", () => {
+ // Same upstream id, different client: routed to Kimi it is rejected, pinned to the
+ // OpenAI protocol (a gateway reselling it) it is served.
+ expect(fastModeState(draft({ modelId: "moonshotai/kimi-k3" })).show).toBe(false);
+ expect(fastModeState(draft({ modelId: "moonshotai/kimi-k3", clientType: "openai" }))).toEqual({
+ protocol: "openai",
+ show: true,
+ });
+ // Whitespace-only fields are treated as absent, matching what the form submits.
+ expect(fastModeState(draft({ modelId: "claude-fable-5", clientType: " " })).protocol).toBe(
+ "anthropic",
+ );
+ });
+
+ it("resolves a custom-like group through the protocol it will be saved with, not its model id", () => {
+ // A custom / user-defined group starts with no protocol and is persisted on the
+ // compatible client (protocolForPersist -> DEFAULT_CUSTOM_CLIENT_TYPE), which carries
+ // fast mode. Routing those ids by name instead would withhold the switch from an entry
+ // that can serve it — nothing about such a group routes by model id.
+ for (const provider of ["custom", "my-group"]) {
+ expect(fastModeState(draft({ provider, modelId: "my-model" })), provider).toEqual({
+ protocol: "openai",
+ show: true,
+ });
+ // Ids that WOULD route to a client with no fast tier if they were read by name: the
+ // group still saves them on the compatible client, so the switch stays offered.
+ for (const modelId of ["kimi-k3", "gemini-3.5-flash", "deepseek-v4-pro"]) {
+ expect(fastModeState(draft({ provider, modelId })), `${provider}/${modelId}`).toEqual({
+ protocol: "openai",
+ show: true,
+ });
+ }
+ }
+ // An explicitly picked protocol still wins over the fallback, on either family.
+ expect(
+ fastModeState(draft({ provider: "custom", modelId: "my-model", clientType: "ant-messages" }))
+ .protocol,
+ ).toBe("anthropic");
+ expect(
+ fastModeState(
+ draft({ provider: "custom", modelId: "my-model", clientType: "openai-responses" }),
+ ).protocol,
+ ).toBe("openai");
+ // The Bedrock carve-out belongs to the claude5 client, so it applies where routing
+ // actually reaches that client: a vendor group withholds the switch, while the same id
+ // and base URL under a custom group is pinned to the compatible client and keeps it.
+ // The gate mirrors AutoLLMClient's routing; it does not promise the endpoint honours
+ // the parameter, which no dialog-side rule can know.
+ expect(
+ fastModeState(
+ draft({ provider: "anthropic", modelId: "claude-fable-5", baseUrl: "bedrock://us-east-1" }),
+ ).show,
+ ).toBe(false);
+ expect(
+ fastModeState(
+ draft({ provider: "custom", modelId: "claude-fable-5", baseUrl: "bedrock://us-east-1" }),
+ ).protocol,
+ ).toBe("openai");
+ });
+
+ it("leaves preset and vendor groups on id-based routing when no protocol is set", () => {
+ // The fallback is scoped to custom-like groups: a vendor group with an empty protocol
+ // must keep deferring to AgentHub's id routing, so a no-fast-tier id stays withheld.
+ expect(fastModeState(draft({ provider: "moonshot", modelId: "kimi-k3" }))).toEqual({
+ protocol: undefined,
+ show: false,
+ });
+ expect(
+ fastModeState(draft({ provider: "anthropic", modelId: "claude-fable-5" })).protocol,
+ ).toBe("anthropic");
+ });
+});
+
+describe("capabilityRow (vision support + fast mode sharing one row)", () => {
+ it("splits the row into two half-width cells when both switches are there", () => {
+ expect(capabilityRow({ vision: true, fastMode: true })).toEqual({
+ show: true,
+ cellClass: undefined,
+ });
+ });
+
+ it("gives a lone switch the full width, in either direction", () => {
+ // The pair is a coincidence, not an invariant. Fast mode is withheld for every model
+ // whose routed client rejects the parameter (the common case), and the vision switch has
+ // to keep rendering on its own — full width, not squeezed into half a row beside a hole.
+ expect(capabilityRow({ vision: true, fastMode: false })).toEqual({
+ show: true,
+ cellClass: "col-span-2",
+ });
+ // The mirror image: a preset model annotated by the catalog shows no vision switch, so
+ // fast mode is alone.
+ expect(capabilityRow({ vision: false, fastMode: true })).toEqual({
+ show: true,
+ cellClass: "col-span-2",
+ });
+ });
+
+ it("drops the row entirely when neither switch is there", () => {
+ // A preset model whose client rejects fast mode has no capability switches at all: the
+ // grid must not render, or the dialog's space-y would draw a gap around an empty box.
+ expect(capabilityRow({ vision: false, fastMode: false }).show).toBe(false);
+ });
+});
diff --git a/packages/web/test/protocol-detect.test.ts b/packages/web/test/protocol-detect.test.ts
index 70363af5..6ed44277 100644
--- a/packages/web/test/protocol-detect.test.ts
+++ b/packages/web/test/protocol-detect.test.ts
@@ -183,6 +183,7 @@ describe("rowToEntry (the persistence funnel)", () => {
vision: true,
contextWindow: "",
maxTokens: "",
+ fastMode: false,
clientType: "",
cacheRead: "",
cacheWrite: "",