pi-qtools 0.2.0 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ Requires a `qwen-token-plan*` provider authenticated in pi (`/login`).
 | `qwen_web_search` | `/responses` `web_search` | answer + queries issued + source URLs |
 | `qwen_web_extractor` | `/responses` `web_search` + `web_extractor` | page text filtered to a stated goal; the API requires the search tool alongside |
 | `qwen_code_interpreter` | `/responses` `code_interpreter` | returns the Python it ran, container id, real stdout |
-| `qwen_image_search` | `/responses` `web_search_image` | text → image URLs. **qwen3.8-max only** |
+| `qwen_image_search` | `/responses` `web_search_image` | text → image URLs. Runs on flash tiers too (see the matrix) |
 | `qwen_reverse_image_search` | `/responses` `image_search` | image URL or local file → similar images; accepts a local path and inlines it as a data URL (4 MB cap) |
 | `qwen_deep_search` | chat `search_strategy: "agent"` | multi-step research; very expensive (~340k prompt tokens observed) |
 | `qwen_generate_image` | native `multimodal-generation` | `wan2.7-image`, `wan2.7-image-pro`, `qwen-image-3.0-pro`; sync; `image` edits a reference picture; `save: true` writes into `<cwd>/out/qtools/` |
@@ -122,14 +122,70 @@ Persisted to `<agentDir>/qtools.json` (migrated automatically from the older
 ```json
 {
   "searchMode": "turbo",
-  "fallbackModel": "qwen3.7-max",
+  "fallbackModel": "qwen3.6-flash",
   "showReasoning": false,
   "deepSearchMaxTokens": 16384,
   "imageModel": "wan2.7-image",
-  "videoModel": "happyhorse-1.1-t2v"
+  "videoModel": "happyhorse-1.1-t2v",
+  "searchBlocklist": []
 }
 ```
 
+## Model catalog overlay
+
+pi ships its model list from a remote catalog that lags the plan. Measured against
+the live `/models` route: the plan serves **21** ids, pi's catalog knew **10**. Four
+of the missing ones are usable chat models that simply could not be selected.
+
+This package overlays its own measured list on top of pi's, adding only what pi
+lacks. It runs on every model refresh, so a pi update that drops or renames a model
+gets corrected on the next refresh without a manual edit.
+
+| added id | verified |
+|---|---|
+| `qwen4-max-preview` | chat, reasoning, image input, all 6 thinking levels |
+| `deepseek-v4.1-flash` | chat, reasoning, image input, all 6 thinking levels |
+| `deepseek-v4.1-flash-1017` | chat, reasoning, image input |
+| `auto` | plan router; chat, reasoning, image input |
+
+Every row was probed, not copied from a sibling model — the same rule the
+capability table follows after `glm-5.3` shipped unmeasured and 400'd every turn.
+That includes `enable_search`: all four accept it, and prompt-token inflation
+(235-387 vs a ~10-28 baseline) confirms search actually ran rather than the flag
+merely being tolerated. They inherit `search=true` from the Qwen family rule, so
+this had to be measured rather than assumed.
+`contextWindow`/`maxTokens` are plan-wide family values, not per-model measurements:
+the endpoint accepts `max_tokens=999999` without complaint, so it cannot reveal the
+real ceiling.
+
+**Scope: `qwen-token-plan` and `qwen-token-plan-individual` only.** Both share the
+ap-southeast-1 endpoint these rows were measured on. `qwen-token-plan-cn` serves
+cn-beijing, a different regional deployment whose model list has never been probed
+(the SG key returns 401 there), so it is deliberately excluded rather than handed
+SG-measured ids. Add it only after probing its `/models` route with a CN credential.
+
+**Generation and audio ids are deliberately excluded.** `wan2.7-image`,
+`qwen-image-3.0-pro`, `wan3.0-video` and `qwen-audio-3.0-*` are not chat models;
+adding them to pi's picker would create entries that 400 on every turn. This package
+already drives them through their native endpoints.
+
+### Two rules that keep it non-destructive
+
+pi's `refreshModels` return value **replaces the provider's entire model list**, so:
+
+1. pi's baseline is carried through verbatim, and **pi's own metadata wins** for any
+   id it already knows — its catalog is vendor-refreshed and may carry corrections.
+2. With no baseline to merge into, the overlay returns *nothing* and adds nothing.
+
+Rule 2 was learned the hard way. The first implementation returned `[]` on that
+path, which **wiped all 11 built-in plan models**. Measured with pi 1.5.0:
+`pi -ne --list-models` showed 11, the extension showed 0. Returning nothing keeps
+pi's list intact; the additions land on the next refresh once pi has a stored
+catalog. Nothing is persisted to `models-store.json` — that file belongs to pi's
+catalog refresh, and writing an overlay into it would corrupt its etag bookkeeping.
+
+`/qtools-config` reports what was added under **Added plan models**.
+
 ## Verified capability matrix
 
 Measured against the live endpoint rather than taken from docs, because the two
@@ -137,16 +193,128 @@ surfaces differ per model:
 
 | model | chat search | agent | chat code_int | `/responses` tools | `web_search_image` | `image_search` |
 |---|---|---|---|---|---|---|
-| qwen3.8-max | yes | no | no | all | **yes** | yes |
-| qwen3.8-flash | yes | no | no | s/c/e | no | yes |
-| qwen3.7-max | yes | yes | yes | s/c/e | no | no |
-| qwen3.7-plus | yes | yes | yes | s/c/e | no | yes |
-| qwen3.6-flash | yes | yes | yes | s/c/e | no | yes |
+| qwen3.8-max | yes | no | no | all | yes | yes |
+| qwen3.8-flash | yes | no | no | all | **yes** | yes |
+| qwen3.7-max | yes | yes | yes | s/c/e | **no** | **no** |
+| qwen3.7-plus | yes | yes | yes | all | **yes** | yes |
+| qwen3.6-flash | yes | yes | yes | all | **yes** | **yes** |
 | deepseek-v4-* | yes | yes | yes | s/c/e | no | no |
+| deepseek-v4.1-flash | yes | (inherited) | yes (streaming) | s/c/e | no | no |
 | glm-5.2 | **no** | no | no | s/c/e | no | no |
+| glm-5.3 | **no** | no | no | s/c/e | no | no |
+| auto (plan router) | yes | unknown | unknown | s/c/e | no | no |
+| anything unmeasured | **no** | no | no | s/c/e | no | no |
+
+Two corrections from the 2026-10-10 remeasurement, both of which were load-bearing bugs:
+
+- **`web_search_image` is not qwen3.8-max-only.** The table used to claim that, and it
+  is wrong: qwen3.6-flash, qwen3.7-plus and qwen3.8-flash all fire `web_search_image_call`.
+- **qwen3.7-max cannot run either image tool** — it 400s on both. Since it was the
+  hardcoded last resort in the pickers, a GLM model asking for image search used to be
+  routed to a model that then failed the call, on the most expensive tier on the plan.
+
+`agent` = chat `search_strategy: "agent"` (qwen_deep_search). `s/c/e` = `/responses`
+web_search / code_interpreter / web_extractor. Cells marked (inherited) come from the
+family rule, not from a direct measurement of that id.
+
+Capability state lives in `src/capabilities.ts` (the measured table, the family rules, the
+fail-safe default, the fallback chain) and imports nothing, so it is testable with no pi and
+no network. `extensions/qtools.ts` owns everything else: config file, HTTP, tools, TUI.
+
+`glm-5.2` and `glm-5.3` reject `enable_search` with a hard error, so injection is
+skipped for them; without that guard every turn would fail after a model switch. They
+can still *use* the search tools: `/responses` web_search, code_interpreter and
+web_extractor all run on a GLM model — only the passive chat injection is lost.
+
+### Which model runs a tool
+
+`requested -> active -> config.fallbackModel -> FALLBACK_CHAIN`, first capable id wins:
+
+- The **active** model is used whenever its row allows the tool, so selecting a model
+  is not a silent invitation to bill a different one — and the answering model is also
+  the model that writes the search queries and reads the pages.
+- Only when the active row says no does the chain step off it, and it steps onto the
+  **cheapest capable** id, not a fixed one. The chain is `qwen3.6-flash -> qwen3.8-flash
+  -> qwen3.7-plus -> deepseek-v4-flash -> deepseek-v4.1-flash -> qwen3.7-max ->
+  qwen3.8-max`, led by `config.fallbackModel` (default `qwen3.6-flash`, the cheapest id
+  measured running every surface). Max tiers sit at the end because the plan bills them
+  at several times a flash tier.
+- If nothing can serve the capability, the tool **errors with the list of models that
+  were tried** instead of quietly calling a model that will 400.
+
+Passive injection has no such choice: it rides inside the active model's own
+`/chat/completions` body, which is why the capability table exists at all.
+
+### How an unknown model id is handled
+
+Three layers, in this order. `node --experimental-strip-types test/caps.test.mjs`
+pins all of them.
+
+1. **Exact row** in `CAPS` (`extensions/qtools.ts`) — measured, authoritative.
+2. **Family rule** (`FAMILY_CAPS`) — a regex on the id, so a dated release like
+   `glm-5.4` or `qwen3.9-max-1105` inherits its family's shape instead of falling
+   through. The generation-only rule (`qwen-audio-*`, `qwen-image-*`, `wan*`,
+   `happyhorse*`) must stay first, or a future `qwen-audio` id would be read as a
+   chat model. `/qtools-config` -> per-model capabilities lists the rules, and the
+   active model's line says which layer answered for it.
+3. **Fail-safe default** — `UNKNOWN_CAPS.chat.search = false`. This is deliberate
+   and is the whole point of the layering: a wrong `true` broke *every* turn when
+   glm-5.3 shipped and matched nothing, while a wrong `false` only costs the passive
+   search bonus and `qwen_web_search` still works.
+
+If a *family guess* turns out wrong, the extension heals itself: the finalized
+assistant message carries the request model id and the upstream error text, so when
+that text mentions `enable_search` the id is appended to `config.searchBlocklist`
+and later turns skip the injection. One bad turn, not forever. Clear them in
+`/qtools-config` -> learned skips. Measured ids never learn — the table outranks the
+runtime, and a verified model that suddenly rejects search should surface as an
+error rather than be silently reconfigured around.
+
+### Adding a model the plan just shipped
+
+1. Check whether pi even lists it. The plan's own `/models` is not the same set as
+   the pi.dev catalogue; on 2026-10-09 the endpoint served `glm-5.3`,
+   `deepseek-v4.1-flash` and `auto` while pi's catalogue listed none of them. Add the
+   missing id to `~/.pi/agent/models.json` under the provider, mirroring a sibling
+   row's `compat`/`thinkingLevelMap`, and verify `reasoning_effort` levels by hand —
+   glm-5.3 accepts only `low|high|max` and 400s on `medium`/`xhigh`, and it silently
+   drops image parts, so declare `input: ["text"]`.
+2. Measure the chat surface: `enable_search`, and `enable_code_interpreter` **in
+   streaming mode** (non-streaming rejects it with a misleading 400).
+3. Measure the `/responses` surface with the real `tools[].type` strings, not the
+   console labels (see Known gaps).
+4. Add the row to `CAPS` in `src/capabilities.ts`, run `npm test`, then release. If the id
+   matches a `FAMILY_CAPS` rule, measure it anyway: family rules are inferences, and only a
+   `CAPS` row is reported as `measured`.
+
+## Testing
+
+```sh
+npm test                                  # parse guard + capability gating, no dependencies
+bash test/injection.e2e.sh                # live injection behaviour against a mock (needs pi)
+```
 
-`glm-5.2` rejects `enable_search` with a hard error, so injection is skipped for it;
-without that guard every turn would fail after a model switch.
+`npm test` is two dependency-free scripts, and that is deliberate: CI runs it with **no
+install step**, so a missing or mismatched pi package cannot break a release.
+
+- `test/parse.check.mjs` imports `extensions/qtools.ts` and counts `ERR_MODULE_NOT_FOUND` as
+  success, because module resolution happens only *after* the TypeScript is parsed. It exists
+  because a table extraction once left two copies of `export function learnedSearchSkips` in
+  the file, and pi only reported that at load time as
+  `Failed to load extension ... has already been declared`. A file that cannot parse must
+  never reach `npm publish`.
+- `test/caps.test.mjs` asserts the gating rules by importing `src/capabilities.ts` directly.
+
+The workflow also fails the build if `node_modules` is ever tracked again: a node_modules
+**symlink** is not caught by the usual `node_modules/` gitignore pattern (git stores symlinks
+as files, mode `120000`), and one once shipped an absolute path from a maintainer's laptop
+into the public repo. The ignore rule is `node_modules`, no trailing slash.
+
+`test/injection.e2e.sh` boots `test/mock_endpoint.py` on 127.0.0.1, runs real `pi -p`
+sessions in a throwaway `PI_CODING_AGENT_DIR`, and asserts whether `enable_search`
+reached the wire for a family-yes id, a glm id, an unmeasured id, and a deliberately
+wrong family guess (which must be learned after one rejected turn). Nothing leaves
+the machine and your own `~/.pi/agent` is never touched.
 
 ## Known gaps
 

package/extensions/qtools.ts

@@ -31,6 +31,66 @@ import { getAgentDir, getSelectListTheme, getSettingsListTheme } from "@earendil
 import { Container, type SelectItem, SelectList, type SettingItem, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import {
+	CAPS,
+	createCaps,
+	FAMILY_CAPS,
+	modelsSupporting,
+	UNKNOWN_CAPS,
+	type Caps,
+} from "../src/capabilities.ts";
+import { mergeCatalog, PLAN_PROVIDERS, QTOOLS_MODELS } from "../src/catalog.ts";
+
+// ------------------------------------------------------- token-plan catalog
+
+/**
+ * pi's remote model catalog lags the plan's /models route, so usable chat models
+ * are simply unselectable. This overlays the ids we have measured on top of pi's
+ * own list, adding only what pi lacks.
+ *
+ * Two rules make this safe:
+ *  - refreshModels' return value REPLACES the provider's whole list, so pi's
+ *    baseline is carried through verbatim and its metadata wins for known ids.
+ *  - with no baseline to merge into we register nothing, rather than replacing
+ *    pi's catalog with only our four rows.
+ *
+ * Nothing is persisted: models-store.json belongs to pi's catalog refresh, and
+ * writing our overlay into it would corrupt its etag/lastModified bookkeeping.
+ */
+const catalogAdded = new Map<string, string[]>();
+
+function registerCatalogOverlay(pi: ExtensionAPI): void {
+	for (const provider of PLAN_PROVIDERS) {
+		try {
+			pi.registerProvider(provider, {
+				async refreshModels(context) {
+					const merged = mergeCatalog(context.stored?.models);
+					if (merged.unsafe) {
+						// No baseline yet. Returning [] here is DESTRUCTIVE: measured with
+						// pi 1.5.0, an empty return wiped all 11 built-in plan models
+						// (pi -ne showed 11, this extension showed 0). Return nothing so pi
+						// keeps its own list; we add ours on the next refresh, once pi has
+						// a stored catalog to merge into. pi's own providers do the same.
+						catalogAdded.delete(provider);
+						return undefined as never;
+					}
+					if (merged.added.length > 0) catalogAdded.set(provider, merged.added);
+					else catalogAdded.delete(provider);
+					return merged.models as never[];
+				},
+			});
+		} catch {
+			// A provider pi does not know, or a registration it rejects, must never
+			// take the rest of the extension down with it.
+		}
+	}
+}
+
+/** What the overlay added, for /qtools-config. */
+function catalogReport(): string {
+	if (catalogAdded.size === 0) return "pi's catalog already covers every measured model";
+	return [...catalogAdded.entries()].map(([p, ids]) => `${p}: +${ids.join(", ")}`).join(" | ");
+}
 
 // ------------------------------------------------------------------ capability
 
@@ -43,79 +103,36 @@ const BASE_URLS: Record<string, string> = {
 };
 
 /**
- * The two surfaces have DIFFERENT support. Measured per model:
- *   chat      = /chat/completions params (enable_search, agent strategy, ci)
- *   responses = /responses built-in tools (web_search, code_interpreter, web_extractor)
- * Notably glm-5.2 rejects chat enable_search outright yet works on /responses,
- * and qwen3.8-* lack chat agent/code_interpreter but work on /responses.
+ * Capability decisions live in src/capabilities.ts, which imports nothing, so they are
+ * unit-testable without pi, without the network and without a config file. Read the
+ * runtime-mutable parts (learned skips, configured fallback head) through getters.
  */
-interface Caps {
-	chat: { search: boolean; agent: boolean; ci: boolean };
-	responses: {
-		web_search: boolean;
-		code_interpreter: boolean;
-		web_extractor: boolean;
-		web_search_image: boolean;
-		image_search: boolean;
-	};
-}
-
-const chat = (search: boolean, agent: boolean, ci: boolean) => ({ search, agent, ci });
-const c = (v: boolean) => v;
-const res = (ws: boolean, ci: boolean, we: boolean, wsi: boolean, is: boolean) => ({
-	web_search: ws,
-	code_interpreter: ci,
-	web_extractor: we,
-	web_search_image: wsi,
-	image_search: is,
+const { capsFor, capsSource, searchCapable, fallbackChain, candidateOrder, chooseModel } = createCaps({
+	blocklist: () => config.searchBlocklist,
+	fallbackModel: () => config.fallbackModel,
 });
-const ALL_RES = res(c(true), c(true), c(true), c(true), c(true));
-/** Every text model does search/code/extract; only some do the image tools. */
-const IMG = (wsi: boolean, is: boolean) => res(true, true, true, wsi, is);
-const NO_RES = res(false, false, false, false, false);
 
-/**
- * Measured per model. The two image tools are gated separately from each other:
- * `web_search_image` is qwen3.8-max only, while `image_search` also works on
- * qwen3.8-flash / 3.7-plus / 3.6-flash. Untested cells are left false.
- */
-const CAPS: Record<string, Caps> = {
-	"qwen3.8-max": { chat: chat(true, false, false), responses: ALL_RES },
-	"qwen3.8-flash": { chat: chat(true, false, false), responses: IMG(false, true) },
-	"qwen3.7-max": { chat: chat(true, true, true), responses: IMG(false, false) },
-	"qwen3.7-plus": { chat: chat(true, true, true), responses: IMG(false, true) },
-	"qwen3.6-flash": { chat: chat(true, true, true), responses: IMG(false, true) },
-	"deepseek-v4-pro": { chat: chat(true, true, true), responses: IMG(false, false) },
-	"deepseek-v4-pro-0813": { chat: chat(true, true, true), responses: IMG(false, false) },
-	"deepseek-v4-flash": { chat: chat(true, true, true), responses: IMG(false, false) },
-	"deepseek-v4-flash-0731": { chat: chat(true, true, true), responses: IMG(false, false) },
-	"glm-5.2": { chat: chat(false, false, false), responses: IMG(false, false) },
-	"wan2.7-image": { chat: chat(false, false, false), responses: NO_RES },
-	"wan2.7-image-pro": { chat: chat(false, false, false), responses: NO_RES },
-	"qwen-audio-3.0-tts-plus": { chat: chat(false, false, false), responses: NO_RES },
-	"qwen-audio-3.0-realtime-plus": { chat: chat(false, false, false), responses: NO_RES },
-};
 
-/** Which models actually run each /responses tool, for error messages. */
-export function modelsSupporting(tool: keyof Caps["responses"]): string[] {
-	return Object.entries(CAPS)
-		.filter(([, k]) => k.responses[tool])
-		.map(([id]) => id);
-}
-
-/** Unknown models: assume the common three, assume not the image tools. */
-const UNKNOWN_CAPS: Caps = { chat: chat(true, false, false), responses: IMG(false, false) };
 
-function capsFor(modelId: string): Caps {
-	return CAPS[modelId] ?? UNKNOWN_CAPS;
+/** Test/maintenance hook: the ids the runtime has learned to leave alone. */
+export function learnedSearchSkips(): string[] {
+	return [...config.searchBlocklist];
 }
 
 /**
- * glm-5.2 returns "This model does not support enable_search", which would break
- * EVERY turn rather than just searches, so the main-loop injection is gated.
+ * pi never fires after_provider_response for a non-2xx (the OpenAI SDK throws first), so the
+ * capability verdict comes from the finalized assistant message instead: it carries the request
+ * model id and the upstream error text, which names enable_search. Matching that text is what
+ * makes this safe — an input-length 400 cannot be mistaken for a capability verdict, and no
+ * request/response pairing or cross-request state is needed.
  */
-function searchCapable(modelId: string): boolean {
-	return capsFor(modelId).chat.search;
+const SEARCH_REJECTED = /enable_search/i;
+
+function learnSearchReject(modelId: string): boolean {
+	if (config.searchBlocklist.includes(modelId)) return false;
+	config.searchBlocklist = [...config.searchBlocklist, modelId];
+	saveConfig();
+	return true;
 }
 
 // --------------------------------------------------------------------- config
@@ -132,6 +149,12 @@ interface QwenToolsConfig {
 	/** Defaults for the generation models (native endpoints, not chat models). */
 	imageModel: string;
 	videoModel: string;
+	/**
+	 * Model ids that answered an injected enable_search with a 400. Learned at runtime
+	 * so one unmeasured model can never break every turn the way glm-5.3 did; cleared
+	 * by deleting entries from the file or with /qtools-config -> learned skips.
+	 */
+	searchBlocklist: string[];
 }
 
 /** Verified working on this plan via the native multimodal-generation endpoint. */
@@ -142,11 +165,12 @@ const VIDEO_SIZES = ["1280*720", "1920*1080", "832*480"];
 
 const DEFAULTS: QwenToolsConfig = {
 	searchMode: "turbo",
-	fallbackModel: "qwen3.7-max",
+	fallbackModel: "qwen3.6-flash",
 	showReasoning: false,
 	deepSearchMaxTokens: 16384,
 	imageModel: "wan2.7-image",
 	videoModel: "happyhorse-1.1-t2v",
+	searchBlocklist: [],
 };
 
 const MODE_NOTES: Record<SearchMode, string> = {
@@ -192,6 +216,9 @@ function loadConfig(): void {
 			fallbackModel: typeof raw.fallbackModel === "string" && raw.fallbackModel ? raw.fallbackModel : DEFAULTS.fallbackModel,
 			imageModel: IMAGE_MODELS.includes(raw.imageModel ?? "") ? raw.imageModel! : DEFAULTS.imageModel,
 			videoModel: VIDEO_MODELS.includes(raw.videoModel ?? "") ? raw.videoModel! : DEFAULTS.videoModel,
+			searchBlocklist: Array.isArray(raw.searchBlocklist)
+				? raw.searchBlocklist.filter((id): id is string => typeof id === "string" && id.length > 0)
+				: DEFAULTS.searchBlocklist,
 		};
 		// Migrate the old filename once so the new one is authoritative.
 		if (source !== p) saveConfig();
@@ -235,26 +262,35 @@ async function resolveEndpoint(ctx: ExtensionContext): Promise<{ baseUrl: string
 	return { baseUrl, apiKey };
 }
 
+function pickModel(ctx: ExtensionContext, eligible: (id: string) => boolean, requested?: string): string | undefined {
+	return chooseModel(eligible, ctx.model?.id, requested);
+}
+
 /** Chat-completions agent-mode side call (deep search): needs chat.agent support. */
 function pickChatCapable(ctx: ExtensionContext, requested?: string): string {
-	const active = ctx.model?.id ?? "";
-	for (const c of [requested, active, config.fallbackModel]) {
-		if (c && capsFor(c).chat.agent) return c;
-	}
-	return "qwen3.7-max";
+	const id = pickModel(ctx, (c) => capsFor(c).chat.agent, requested);
+	if (id) return id;
+	throw new Error(
+		`No model on this plan runs chat agent mode (search_strategy: "agent"). Candidates tried: ${candidateOrder(
+			ctx.model?.id,
+			requested,
+		).join(", ")}.`,
+	);
 }
 
 /**
- * /responses tools: keep the ACTIVE model. Every chat model on this plan runs all
- * three built-in tools there, so downgrading to the fallback would silently bill a
- * different model than the one the user selected.
+ * /responses tools: keep the ACTIVE model whenever it can serve the tool, so the model the
+ * user selected is the one billed and the one writing the answer. Only step off it when its
+ * row says no, and then step onto the cheapest capable id rather than a fixed expensive one.
  */
 function pickResponsesModel(ctx: ExtensionContext, tool: keyof Caps["responses"], requested?: string): string {
-	const active = ctx.model?.id ?? "";
-	for (const c of [requested, active, config.fallbackModel]) {
-		if (c && capsFor(c).responses[tool]) return c;
-	}
-	return "qwen3.7-max";
+	const id = pickModel(ctx, (c) => capsFor(c).responses[tool], requested);
+	if (id) return id;
+	const works = modelsSupporting(tool);
+	throw new Error(
+		`No model on this plan runs the /responses "${tool}" tool.` +
+			(works.length ? ` Measured working on: ${works.join(", ")}.` : " Nothing has been measured working on it yet."),
+	);
 }
 
 // --------------------------------------------------------------- /responses
@@ -967,7 +1003,12 @@ const TYPE_MAP: Array<{ label: string; type: string; tool: string }> = [
 	{ label: "i2i_search", type: "image_search", tool: "qwen_reverse_image_search" },
 ];
 
-function capabilityItems(): SelectItem[] {
+/**
+ * Real model ids with their measured rows. This is the list the fallback-model submenu
+ * offers, so it must stay id-only: a family rule or the "anything else" row is not a
+ * model id, and selecting one would write "family:0" into config.fallbackModel.
+ */
+function modelIdItems(): SelectItem[] {
 	return Object.entries(CAPS).map(([id, caps]) => ({
 		value: id,
 		label: id,
@@ -975,6 +1016,25 @@ function capabilityItems(): SelectItem[] {
 	}));
 }
 
+/**
+ * Read-only capability browser: measured rows first, then the family rules that catch ids
+ * nobody measured, then the fail-safe default, so provenance is visible without guessing.
+ */
+function capabilityItems(): SelectItem[] {
+	const rows: SelectItem[] = modelIdItems();
+	rows.push(...FAMILY_CAPS.map((rule, i) => ({
+		value: `family:${i}`,
+		label: `family ${rule.match.source}`,
+		description: `${capabilitySummary(rule.caps)} | inferred: ${rule.why}`,
+	})));
+	rows.push({
+		value: "unknown",
+		label: "anything else",
+		description: `${capabilitySummary(UNKNOWN_CAPS)} | fail-safe: nothing assumed about enable_search`,
+	});
+	return rows;
+}
+
 function typeMapItems(): SelectItem[] {
 	return TYPE_MAP.map((t) => ({
 		value: t.type,
@@ -991,16 +1051,27 @@ function descriptionFor(id: string, ctx: ExtensionContext): string {
 		case "searchMode":
 			return (
 				MODE_NOTES[config.searchMode] +
-				(caps.chat.search ? "" : ` — WARNING: ${model} rejects enable_search, so injection is skipped`)
+				(caps.chat.search
+					? ""
+					: ` — WARNING: ${model} rejects enable_search (${capsSource(model)}), so injection is skipped`) +
+				(config.searchBlocklist.length ? ` | learned skips: ${config.searchBlocklist.join(", ")}` : "")
 			);
 		case "fallbackModel":
-			return `Model the qwen_* tools run on only when the active model cannot. Currently ${config.fallbackModel}. (/responses tools use the active model — every chat model here supports them.)`;
+			return (
+				`Head of the cheap-first chain the qwen_* tools step onto when the ACTIVE model cannot serve a ` +
+				`tool. Currently ${config.fallbackModel}; chain tried in order: ${fallbackChain().join(" -> ")}. ` +
+				`The active model is always preferred, so this only matters for models with gaps (GLM rejects image tools).`
+			);
 		case "showReasoning":
 			return "Adds the model's own plan/rationale to tool results. More context, more tokens.";
 		case "deepSearchMaxTokens":
 			return `max_tokens cap for qwen_deep_search. It burned ~340k prompt tokens uncapped; limit is ${config.deepSearchMaxTokens} now.`;
 		case "capabilities":
 			return "Measured against the live endpoint. Note the two image tools are gated differently.";
+		case "learnedSkips":
+			return config.searchBlocklist.length
+				? `Unmeasured models that took a 400 on the injected enable_search: ${config.searchBlocklist.join(", ")}. Select clear to forget them.`
+				: "No runtime-learned skips. A 400 on an injected request for an unmeasured model lands here.";
 		case "imageModel":
 			return `Default for qwen_generate_image and /qimage. All three verified working via the native multimodal-generation endpoint.`;
 		case "videoModel":
@@ -1009,6 +1080,12 @@ function descriptionFor(id: string, ctx: ExtensionContext): string {
 			return "Console capability labels differ from the API tools[].type strings. Sending a label is silently ignored.";
 		case "provider":
 			return "Where the API key and base URL come from, plus whether the active model is a Qwen plan model.";
+		case "catalog":
+			return (
+				`Chat models this package adds on top of pi's own catalog, which lags the plan's /models route. ` +
+				`${QTOOLS_MODELS.length} measured rows; pi's metadata always wins for ids it already knows. ` +
+				`Generation/audio ids are deliberately excluded: they are not chat models and would 400 in the picker.`
+			);
 	}
 	return "";
 }
@@ -1020,7 +1097,8 @@ function buildItems(ctx: ExtensionContext, th: ThemeLike): SettingItem[] {
 	const capLine =
 		`${model}: chat ${y(caps.chat.search)}${y(caps.chat.agent)}${y(caps.chat.ci)}` +
 		` | res ${y(caps.responses.web_search)}${y(caps.responses.code_interpreter)}${y(caps.responses.web_extractor)}` +
-		`${y(caps.responses.web_search_image)}${y(caps.responses.image_search)}`;
+		`${y(caps.responses.web_search_image)}${y(caps.responses.image_search)}` +
+		` | ${capsSource(model)}`;
 	return [
 		{
 			id: "searchMode",
@@ -1038,7 +1116,7 @@ function buildItems(ctx: ExtensionContext, th: ThemeLike): SettingItem[] {
 			// closeSubmenu() leaves submenuComponent set, so the submenu never closes
 			// (onChange still fires, so it looks like a render hang). The cursor already
 			// returns to this row, so navigateTo buys nothing here.
-			submenu: (current, done) => makeSubmenu(th, "Built-in tool model", capabilityItems(), current, (v) => done(v)),
+			submenu: (current, done) => makeSubmenu(th, "Built-in tool model", modelIdItems(), current, (v) => done(v)),
 		},
 		{
 			id: "showReasoning",
@@ -1103,6 +1181,19 @@ function buildItems(ctx: ExtensionContext, th: ThemeLike): SettingItem[] {
 			currentValue: capLine,
 			submenu: (_current, done) => makeSubmenu(th, "Per-model capabilities", capabilityItems(), "", () => done(undefined)),
 		},
+		{
+			id: "learnedSkips",
+			label: "learned skips",
+			description: descriptionFor("learnedSkips", ctx),
+			currentValue: config.searchBlocklist.length ? config.searchBlocklist.join(", ") : "none",
+			values: ["clear"],
+		},
+		{
+			id: "catalog",
+			label: "Added plan models",
+			description: descriptionFor("catalog", ctx),
+			currentValue: catalogReport(),
+		},
 		{
 			id: "provider",
 			label: "Provider",
@@ -1118,7 +1209,9 @@ function applyChange(id: string, value: string): void {
 			if (SEARCH_MODES.includes(value as SearchMode)) config.searchMode = value as SearchMode;
 			break;
 		case "fallbackModel":
-			if (value) config.fallbackModel = value;
+			// Guard the submenu contract: anything that is not a measured id would silently
+			// demote the whole fallback chain to "no capable model found".
+			if (value && CAPS[value]) config.fallbackModel = value;
 			break;
 		case "showReasoning":
 			config.showReasoning = value === "enabled";
@@ -1129,6 +1222,9 @@ function applyChange(id: string, value: string): void {
 		case "videoModel":
 			if (VIDEO_MODELS.includes(value)) config.videoModel = value;
 			break;
+		case "learnedSkips":
+			if (value === "clear") config.searchBlocklist = [];
+			break;
 		case "deepSearchMaxTokens": {
 			const n = Number.parseInt(value, 10);
 			if (Number.isFinite(n) && n > 0) config.deepSearchMaxTokens = n;
@@ -1143,6 +1239,9 @@ function applyChange(id: string, value: string): void {
 loadConfig();
 
 export default function (pi: ExtensionAPI): void {
+	// Fill in plan models pi's catalog has not caught up with yet.
+	registerCatalogOverlay(pi);
+
 	// ---- main-loop web_search injection (chat/completions) ----
 	pi.on("before_provider_request", (event, ctx) => {
 		if (config.searchMode === "off" || !isQwen(ctx)) return undefined;
@@ -1165,6 +1264,34 @@ export default function (pi: ExtensionAPI): void {
 		};
 	});
 
+	// ---- self-heal: an enable_search error retires that model's passive search ----
+	pi.on("message_end", (event, ctx) => {
+		const message = event.message as {
+			role?: string;
+			provider?: string;
+			model?: string;
+			stopReason?: string;
+			errorMessage?: string;
+		};
+		if (message.role !== "assistant" || message.stopReason !== "error") return;
+		if (!(message.provider ?? "").startsWith(PROVIDER_PREFIX)) return;
+		const detail = message.errorMessage ?? "";
+		if (!SEARCH_REJECTED.test(detail)) return;
+		const id = message.model;
+		if (!id) return;
+		// Only unmeasured ids get to learn: the table is authoritative, and a measured model
+		// that suddenly rejects search is an upstream change the maintainer should see as an
+		// error rather than have silently reconfigured around.
+		if (CAPS[id]) return;
+		if (!learnSearchReject(id)) return;
+		ctx.ui.notify(
+			`qtools: ${id} is unmeasured and rejected the injected enable_search, so passive search is now ` +
+				`skipped for it (qwen_web_search still works). New ids belong in CAPS in src/capabilities.ts; ` +
+				`this skip is in config.searchBlocklist, clearable via /qtools-config -> learned skips.`,
+			"warning",
+		);
+	});
+
 	// ------------------------------------------------------------------- tools
 	pi.registerTool({
 		name: "qwen_web_search",
@@ -1258,7 +1385,9 @@ export default function (pi: ExtensionAPI): void {
 		description:
 			"Search the web for images matching a text description, using Qwen's server-side web_search_image " +
 			"tool. Returns the image URLs it found plus the queries it issued. Qwen runs the retrieval; results " +
-			"are real URLs, not model guesses. Supported by qwen3.8-max only on this plan.",
+			"are real URLs, not model guesses. Runs on the plan's flash tiers as well (qwen3.6-flash, " +
+			"qwen3.7-plus, qwen3.8-flash, qwen3.8-max); glm-* and deepseek-* cannot, and those calls are " +
+			"routed to a capable model for you.",
 		promptSnippet: "Find images on the web from a text description",
 		promptGuidelines: [
 			"Use qwen_image_search when the user wants pictures of something found on the web, as opposed to qwen_web_search which retrieves text sources.",
@@ -1266,7 +1395,7 @@ export default function (pi: ExtensionAPI): void {
 		],
 		parameters: Type.Object({
 			query: Type.String({ description: "What to find images of, as a short descriptive phrase." }),
-			model: Type.Optional(Type.String({ description: "Override model id (only qwen3.8-max supports this tool)." })),
+			model: Type.Optional(Type.String({ description: "Override model id (flash tiers work here)." })),
 		}),
 		async execute(_id, params, signal, onUpdate, ctx) {
 			onUpdate?.({ content: [{ type: "text", text: `image search: ${params.query}` }] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-qtools",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Qwen Token Plan bridge for pi: web search, scraping, code interpreter, image search, and image/video generation via DashScope built-in tools and native task endpoints.",
   "type": "module",
   "keywords": [
@@ -31,6 +31,7 @@
   },
   "files": [
     "extensions",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -54,5 +55,8 @@
     "extensions": [
       "./extensions/qtools.ts"
     ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types test/parse.check.mjs && node --experimental-strip-types test/caps.test.mjs && node --experimental-strip-types test/catalog.test.mjs"
   }
 }

package/src/capabilities.ts

@@ -0,0 +1,214 @@
+/**
+ * The capability layer, with NO imports at all — deliberately.
+ *
+ * Everything pi-specific (context, config file, TUI, HTTP) lives in ../extensions/qtools.ts.
+ * This file is the part that decides whether a model can take `enable_search` and which
+ * model runs a tool, and it is unit-tested without pi installed, without the network, and
+ * without a config file. That matters: when this table lived inside the extension, the test
+ * had to import the extension, which had to import `@earendil-works/pi-coding-agent`, so CI
+ * needed a full pi install just to assert a boolean.
+ *
+ * Measured against the live endpoint:
+ *   https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
+ *
+ * TWO API surfaces, different capabilities:
+ *   chat      = /chat/completions params (enable_search, agent strategy, code interpreter)
+ *   responses = /responses built-in tools (web_search, code_interpreter, web_extractor,
+ *               web_search_image, image_search)
+ */
+
+export interface Caps {
+	chat: { search: boolean; agent: boolean; ci: boolean };
+	responses: {
+		web_search: boolean;
+		code_interpreter: boolean;
+		web_extractor: boolean;
+		web_search_image: boolean;
+		image_search: boolean;
+	};
+}
+
+const chat = (search: boolean, agent: boolean, ci: boolean) => ({ search, agent, ci });
+const c = (v: boolean) => v;
+const res = (ws: boolean, ci: boolean, we: boolean, wsi: boolean, is: boolean) => ({
+	web_search: ws,
+	code_interpreter: ci,
+	web_extractor: we,
+	web_search_image: wsi,
+	image_search: is,
+});
+export const ALL_RES = res(c(true), c(true), c(true), c(true), c(true));
+/** Every text model does search/code/extract; only some do the image tools. */
+export const IMG = (wsi: boolean, is: boolean) => res(true, true, true, wsi, is);
+export const NO_RES = res(false, false, false, false, false);
+
+/**
+ * Measured per model. The two image tools are gated separately from each other.
+ * Re-measured 2026-10-10: `web_search_image` is NOT qwen3.8-max-only as this table first
+ * claimed — it also runs on qwen3.8-flash / 3.7-plus / 3.6-flash, and qwen3.7-max cannot
+ * run either image tool. Both mistakes pushed tool calls onto the plan's priciest tier.
+ * Untested cells are left false.
+ */
+export const CAPS: Record<string, Caps> = {
+	"qwen3.8-max": { chat: chat(true, false, false), responses: ALL_RES },
+	"qwen3.8-flash": { chat: chat(true, false, false), responses: IMG(true, true) },
+	"qwen3.7-max": { chat: chat(true, true, true), responses: IMG(false, false) },
+	"qwen3.7-plus": { chat: chat(true, true, true), responses: IMG(true, true) },
+	"qwen3.6-flash": { chat: chat(true, true, true), responses: IMG(true, true) },
+	"deepseek-v4-pro": { chat: chat(true, true, true), responses: IMG(false, false) },
+	"deepseek-v4-pro-0813": { chat: chat(true, true, true), responses: IMG(false, false) },
+	"deepseek-v4-flash": { chat: chat(true, true, true), responses: IMG(false, false) },
+	"deepseek-v4-flash-0731": { chat: chat(true, true, true), responses: IMG(false, false) },
+	"glm-5.2": { chat: chat(false, false, false), responses: IMG(false, false) },
+	// Measured 2026-10-10: chat enable_search -> 400 "This model does not support enable_search"
+	// in both streaming and non-streaming mode; /responses runs web_search + code_interpreter;
+	// both image tools rejected; reasoning_effort only accepts low|high|max (xhigh/medium 400).
+	"glm-5.3": { chat: chat(false, false, false), responses: IMG(false, false) },
+	// Measured 2026-10-10: chat enable_search accepted, all five /responses built-ins accepted
+	// (both image tools fired), and chat enable_code_interpreter needs STREAMING mode: a
+	// non-streaming probe 400s with "Non-streaming mode does not support Code interpreter",
+	// which reads like a capability rejection and is not one. pi always streams.
+	"deepseek-v4.1-flash": { chat: chat(true, true, true), responses: IMG(false, false) },
+	// "auto" is the plan's router alias. Measured 2026-10-10: chat enable_search accepted,
+	// /responses web_search accepted, all reasoning_effort levels accepted. It routes to some
+	// model I cannot see, so only the cells I actually exercised are set; assume nothing else.
+	"auto": { chat: chat(true, false, false), responses: IMG(false, false) },
+	"wan2.7-image": { chat: chat(false, false, false), responses: NO_RES },
+	"wan2.7-image-pro": { chat: chat(false, false, false), responses: NO_RES },
+	"qwen-audio-3.0-tts-plus": { chat: chat(false, false, false), responses: NO_RES },
+	"qwen-audio-3.0-realtime-plus": { chat: chat(false, false, false), responses: NO_RES },
+};
+
+/**
+ * Family defaults for ids missing from CAPS, so a dated release (glm-5.4,
+ * deepseek-v4.2-flash-1101, qwen3.9-max-...) inherits the family's measured shape instead
+ * of falling through to UNKNOWN_CAPS. First match wins, so the generation-only rule must
+ * stay ahead of the qwen chat rule.
+ */
+export const FAMILY_CAPS: Array<{ match: RegExp; caps: Caps; why: string }> = [
+	{
+		match: /^(qwen-(audio|image)|wan|happyhorse)/i,
+		caps: { chat: chat(false, false, false), responses: NO_RES },
+		why: "native generation endpoint, not a chat model",
+	},
+	{
+		// Every GLM on this plan so far rejects chat enable_search (glm-5.2, glm-5.3).
+		match: /^glm/i,
+		caps: { chat: chat(false, false, false), responses: IMG(false, false) },
+		why: "GLM runs /responses built-ins but rejects enable_search on chat",
+	},
+	{
+		match: /^deepseek/i,
+		caps: { chat: chat(true, true, true), responses: IMG(false, false) },
+		why: "DeepSeek on this plan takes chat search, agent mode and code interpreter",
+	},
+	{
+		match: /^qwen[-.\d]/i,
+		caps: { chat: chat(true, false, false), responses: IMG(false, false) },
+		why: "Qwen chat models take turbo/max search injection",
+	},
+];
+
+/**
+ * Unknown models: assume the /responses tools work, assume NOTHING about chat
+ * enable_search. The asymmetry is deliberate. A wrong `true` here was a poison pill:
+ * glm-5.3 shipped on the plan, matched no CAPS row, took the injected enable_search, and
+ * every single turn 400'd until the table was edited. A wrong `false` only costs the
+ * passive search bonus, and `qwen_web_search` still works.
+ */
+export const UNKNOWN_CAPS: Caps = { chat: chat(false, false, false), responses: IMG(false, false) };
+
+/**
+ * Cheap-first candidate order for the fallback chain. The plan bills a max tier at a
+ * several-times-higher ratio than a flash tier, so the chain is ordered by price, not by
+ * recency, and `qwen3.6-flash` leads because it is the cheapest id measured running every
+ * tool surface: chat search/agent/code plus all five /responses tools. Never hardcode an
+ * endpoint here; add an id and let capsFor() decide who is eligible.
+ */
+export const FALLBACK_CHAIN = [
+	"qwen3.6-flash",
+	"qwen3.8-flash",
+	"qwen3.7-plus",
+	"deepseek-v4-flash",
+	"deepseek-v4.1-flash",
+	"qwen3.7-max",
+	"qwen3.8-max",
+];
+
+/** Which models actually run each /responses tool, for error messages. */
+export function modelsSupporting(tool: keyof Caps["responses"]): string[] {
+	return Object.entries(CAPS)
+		.filter(([, k]) => k.responses[tool])
+		.map(([id]) => id);
+}
+
+function familyCaps(modelId: string): { caps: Caps; why: string } | undefined {
+	return FAMILY_CAPS.find((rule) => rule.match.test(modelId));
+}
+
+function baseCaps(modelId: string): Caps {
+	return CAPS[modelId] ?? familyCaps(modelId)?.caps ?? UNKNOWN_CAPS;
+}
+
+export interface CapsReader {
+	capsFor(modelId: string): Caps;
+	capsSource(modelId: string): string;
+	searchCapable(modelId: string): boolean;
+	fallbackChain(): string[];
+	candidateOrder(active?: string, requested?: string): string[];
+	chooseModel(eligible: (id: string) => boolean, active?: string, requested?: string): string | undefined;
+}
+
+/**
+ * Read capability state through getters instead of importing state, because the caller owns
+ * persistence: `config.searchBlocklist` and `config.fallbackModel` come from <agentDir>/qtools.json
+ * and change at runtime. Tests pass a fixed list, or none at all.
+ */
+export function createCaps(
+	options: { blocklist?: () => readonly string[]; fallbackModel?: () => string } = {},
+): CapsReader {
+	const blocked = () => options.blocklist?.() ?? [];
+	const head = () => options.fallbackModel?.() ?? FALLBACK_CHAIN[0]!;
+
+	function capsFor(modelId: string): Caps {
+		const caps = baseCaps(modelId);
+		// The runtime blocklist only ever removes a capability, never grants one.
+		if (!blocked().includes(modelId)) return caps;
+		return { ...caps, chat: { ...caps.chat, search: false } };
+	}
+
+	function candidateOrder(active?: string, requested?: string): string[] {
+		const chain = [head(), ...FALLBACK_CHAIN.filter((id) => id !== head())];
+		return [requested, active, ...chain].filter((id): id is string => typeof id === "string" && id.length > 0);
+	}
+
+	return {
+		capsFor,
+		/** Where a model's caps came from, for the /qtools-config capability readout. */
+		capsSource(modelId: string): string {
+			if (blocked().includes(modelId)) return "learned: rejects enable_search";
+			if (CAPS[modelId]) return "measured";
+			return familyCaps(modelId)?.why ?? "unknown model, no capabilities assumed";
+		},
+		/**
+		 * glm-5.2 and glm-5.3 return "This model does not support enable_search", which breaks
+		 * EVERY turn rather than just searches, so the main-loop injection is gated on this.
+		 */
+		searchCapable(modelId: string): boolean {
+			return capsFor(modelId).chat.search;
+		},
+		/** Exported so the TUI and the tests show the same chain the pickers walk. */
+		fallbackChain(): string[] {
+			return [head(), ...FALLBACK_CHAIN.filter((id) => id !== head())];
+		},
+		candidateOrder,
+		/**
+		 * The pure half of the pickers: walk requested -> active -> fallback chain, first
+		 * capable id wins. undefined means nothing on the plan can run the capability, and the
+		 * caller must say so rather than call a model that will 400.
+		 */
+		chooseModel(eligible: (id: string) => boolean, active?: string, requested?: string): string | undefined {
+			return candidateOrder(active, requested).find((id) => eligible(id));
+		},
+	};
+}

package/src/catalog.ts

@@ -0,0 +1,166 @@
+/**
+ * The Token Plan model catalog, with NO imports at all — same discipline as
+ * capabilities.ts: pi-specific wiring lives in ../extensions/qtools.ts, and the
+ * decision logic here is unit-tested without pi, without the network, without a
+ * config file.
+ *
+ * WHY THIS EXISTS
+ * pi ships its model list from a remote catalog that lags the endpoint. Measured
+ * 2026-10-10 against the live /models route: the plan serves 21 ids, pi's catalog
+ * knew 10. The 11 missing included four usable chat models (qwen4-max-preview,
+ * deepseek-v4.1-flash, deepseek-v4.1-flash-1017, auto) that simply could not be
+ * selected in pi.
+ *
+ * WHAT IS DELIBERATELY NOT HERE
+ * The generation ids the endpoint also lists — wan2.7-image, wan2.7-image-pro,
+ * qwen-image-3.0-pro, wan3.0-video, qwen-audio-3.0-* — are NOT chat models. Adding
+ * them to pi's chat picker would create entries that 400 on every turn. This
+ * package already drives them through their native endpoints (qwen_generate_image,
+ * qwen_generate_video), which is the only surface they answer on.
+ *
+ * Every row below was probed, not copied from a sibling model: chat completion,
+ * reasoning_content, image input, and all six reasoning_effort levels. That is the
+ * same rule capabilities.ts follows after glm-5.3 shipped unmeasured and 400'd every
+ * turn. contextWindow/maxTokens are the plan-wide family values, not per-model
+ * measurements — the endpoint accepts max_tokens=999999 without complaint, so it
+ * cannot be used to discover the real ceiling.
+ */
+
+/** Shape pi's registerProvider/refreshModels expects for a chat model. */
+export interface CatalogModel {
+	id: string;
+	name: string;
+	type: "chat";
+	api: string;
+	reasoning: boolean;
+	input: Array<"text" | "image">;
+	contextWindow: number;
+	maxTokens: number;
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	compat: Record<string, unknown>;
+	thinkingLevelMap: Record<string, string | null>;
+}
+
+/** Subscription plan: tokens are prepaid, so per-token cost is zero. */
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+/** Verified on every plan model probed; matches pi's own qwen3.8-max entry. */
+const QWEN_COMPAT = {
+	supportsStrictMode: true,
+	thinkingFormat: "qwen",
+	supportsDeveloperRole: false,
+	supportsStore: false,
+	supportsReasoningEffort: true,
+};
+
+/** All six levels returned 200 on every model below, so none are mapped to null. */
+const ALL_LEVELS = {
+	off: null,
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "max",
+};
+
+const model = (id: string, name: string, maxTokens: number): CatalogModel => ({
+	id,
+	name,
+	type: "chat",
+	api: "openai-completions",
+	reasoning: true,
+	input: ["text", "image"],
+	contextWindow: 1000000,
+	maxTokens,
+	cost: ZERO_COST,
+	compat: QWEN_COMPAT,
+	thinkingLevelMap: ALL_LEVELS,
+});
+
+/**
+ * Chat models the plan serves that pi's catalog may lack.
+ * Probed 2026-10-10: all four answer chat, emit reasoning_content, accept image
+ * input (each correctly identified a test PNG as a pig), and accept every
+ * reasoning_effort level.
+ */
+export const QTOOLS_MODELS: readonly CatalogModel[] = [
+	model("qwen4-max-preview", "Qwen4 Max (preview)", 131072),
+	model("deepseek-v4.1-flash", "DeepSeek V4.1 Flash", 131072),
+	model("deepseek-v4.1-flash-1017", "DeepSeek V4.1 Flash 1017", 131072),
+	// Router id: the plan picks the backing model per request.
+	model("auto", "Qwen Auto (plan router)", 131072),
+];
+
+/**
+ * Provider ids this overlay applies to.
+ *
+ * Deliberately NOT all three plan providers: `qwen-token-plan-cn` serves
+ * cn-beijing, a different regional deployment whose model list has never been
+ * measured (the SG key returns 401 there). Pushing the SG-measured ids onto it
+ * would be exactly the unmeasured assumption that made glm-5.3 400 every turn.
+ * Both ids below share the ap-southeast-1 endpoint these rows were probed on.
+ * Add CN only after probing its /models route with a CN credential.
+ */
+export const PLAN_PROVIDERS = [
+	"qwen-token-plan",
+	"qwen-token-plan-individual",
+] as const;
+
+export interface MergeResult {
+	/** The full list to hand back to pi: baseline first, additions appended. */
+	models: unknown[];
+	/** Ids actually added, for logging and for the /qtools-config report. */
+	added: string[];
+	/**
+	 * True when there was no baseline to merge into. Registering then would REPLACE
+	 * pi's catalog with only our four rows, deleting every model pi knows about —
+	 * so the caller must skip registration instead.
+	 */
+	unsafe: boolean;
+}
+
+/**
+ * Merge our curated rows into pi's existing catalog, adding only ids pi lacks.
+ *
+ * pi's `models`/refreshModels return value REPLACES the provider's whole list, so
+ * the baseline must be carried through verbatim. pi's own metadata always wins for
+ * an id it already knows: its catalog is refreshed from the vendor and may carry
+ * corrections (context windows, compat flags) that our static rows do not.
+ */
+export function mergeCatalog(
+	baseline: readonly unknown[] | undefined,
+	curated: readonly CatalogModel[] = QTOOLS_MODELS,
+): MergeResult {
+	if (!baseline || baseline.length === 0) {
+		return { models: [], added: [], unsafe: true };
+	}
+	// Dedupe the baseline too, first occurrence wins: pi's catalog should not contain
+	// repeats, but a duplicate id reaching registerProvider is worse than a dropped
+	// copy, and keeping the first preserves pi's own metadata and ordering.
+	const seen = new Set<string>();
+	const models: unknown[] = [];
+	for (const entry of baseline) {
+		const id = (entry as { id?: unknown })?.id;
+		if (typeof id === "string") {
+			if (seen.has(id)) continue;
+			seen.add(id);
+		}
+		models.push(entry);
+	}
+	const additions = curated.filter((m) => !seen.has(m.id));
+	for (const m of additions) seen.add(m.id);
+	return {
+		models: [...models, ...additions],
+		added: additions.map((m) => m.id),
+		unsafe: false,
+	};
+}
+
+/** Ids our catalog would add, without building the merged list. */
+export function missingIds(
+	baseline: readonly unknown[] | undefined,
+	curated: readonly CatalogModel[] = QTOOLS_MODELS,
+): string[] {
+	return mergeCatalog(baseline, curated).added;
+}