pi-qtools 0.2.0 → 0.2.2

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,11 +122,12 @@ 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": []
 }
 ```
 
@@ -137,16 +138,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,14 @@ 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";
 
 // ------------------------------------------------------------------ capability
 
@@ -43,79 +51,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 +97,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 +113,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 +164,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 +210,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 +951,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 +964,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 +999,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":
@@ -1020,7 +1039,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 +1058,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 +1123,13 @@ 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: "provider",
 			label: "Provider",
@@ -1118,7 +1145,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 +1158,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;
@@ -1165,6 +1197,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 +1318,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 +1328,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.2.2",
   "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"
   }
 }

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));
+		},
+	};
+}