pi-qtools 0.1.1 → 0.2.2

package/README.md

@@ -16,10 +16,10 @@ 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; `save: true` writes into `<cwd>/out/qtools/` |
+| `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/` |
 | `qwen_generate_video` | native `video-generation` + task polling | `happyhorse-1.1-t2v` / `-i2v` / `-r2v`; async, ~90-120s; `save: true` writes the mp4 |
 
 ## Passive main-loop search
@@ -40,10 +40,31 @@ sends one. That is why those two capabilities are standalone tools instead.
 ## Commands
 
 - `/qtools-config` — settings TUI (search mode, model defaults, capability matrix)
-- `/qimage <prompt> [-m model] [-s WxH]` — saves into `out/qtools/`
+- `/qimage <prompt> [-i img] [-m model] [-s WxH]` — saves into `out/qtools/`
 - `/qvideo <prompt> [-i <path|url>] [-m model] [-s WxH]` — `-i` selects image-to-video; saves into `out/qtools/`
 
-### Getting parameter hints
+### Image editing (measured)
+
+Passing a reference image turns the same endpoint from text-to-image into
+image+prompt editing. The shape is one extra content part:
+
+```json
+{ "input": { "messages": [ { "role": "user", "content": [
+  { "image": "https://... or data:image/png;base64,..." },
+  { "text": "turn this into a red panda, keep the flat vector style" }
+] } ] } }
+```
+
+Verified: a flat-vector pig + that prompt came back a red panda **in the same
+style**, and a local file inlined as a data URL worked too. Two reference images
+in one message are accepted.
+
+The trap here is that a wrong request shape still returns a valid image, just
+generated from the text alone. Every claim above was checked by asking a vision
+model (`qwen3.8-max`, which has real image input on this plan) to describe the
+output, not by trusting the HTTP 200.
+
+## Getting parameter hints
 
 pi exposes no `argumentHint` for extension commands, so `/qimage` and `/qvideo` make
 themselves discoverable three ways:
@@ -101,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": []
 }
 ```
 
@@ -116,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
@@ -643,18 +627,40 @@ function extractImageUrls(body: any): string[] {
 /** Shared core so the tool and the /qimage command behave identically. */
 async function generateImage(
 	ctx: ExtensionContext,
-	opts: { prompt: string; model?: string; negativePrompt?: string; size?: string; signal?: AbortSignal },
-): Promise<{ model: string; urls: string[]; raw: unknown }> {
+	opts: {
+		prompt: string;
+		model?: string;
+		negativePrompt?: string;
+		size?: string;
+		/** Reference image to edit: local path, http(s) URL, or data: URL. */
+		image?: string;
+		signal?: AbortSignal;
+	},
+): Promise<{ model: string; urls: string[]; raw: unknown; edited?: string }> {
 	const model = opts.model && IMAGE_MODELS.includes(opts.model) ? opts.model : config.imageModel;
 	const parameters: Record<string, unknown> = { result_format: "message" };
 	if (opts.size) parameters.size = opts.size;
 	if (opts.negativePrompt) parameters.negative_prompt = opts.negativePrompt;
+
+	// Verified shape: an extra {image} content part next to the text switches this
+	// endpoint from text-to-image to image+prompt editing. Confirmed by vision:
+	// a flat-vector pig + "turn this into a red panda" came back a red panda in the
+	// same style, and a local file inlined as a data URL worked too.
+	const content: Array<Record<string, unknown>> = [];
+	let edited: string | undefined;
+	if (opts.image?.trim()) {
+		const ref = toImageUrl(opts.image.trim());
+		content.push({ image: ref });
+		edited = ref.startsWith("data:") ? `inline image (${Math.round(ref.length / 1024)} KB base64)` : ref;
+	}
+	content.push({ text: opts.prompt });
+
 	const r = await nativeCall(ctx, MG_PATH, {
 		model,
-		input: { messages: [{ role: "user", content: [{ text: opts.prompt }] }] },
+		input: { messages: [{ role: "user", content }] },
 		parameters,
 	}, { signal: opts.signal });
-	return { model, urls: extractImageUrls(r.body), raw: r.body };
+	return { model, urls: extractImageUrls(r.body), raw: r.body, edited };
 }
 
 /**
@@ -761,9 +767,11 @@ function genUsage(kind: "image" | "video", cwd: string): string {
 	const outDir = join(cwd, "out", "qtools");
 	if (kind === "image") {
 		return [
-			"/qimage <prompt> [-m model] [-s WxH]",
+			"/qimage <prompt> [-i img] [-m model] [-s WxH]",
 			"",
 			"  prompt   what to draw. No quotes needed: flags are stripped, the rest is the prompt.",
+			"  -i       reference image to edit (local path, http(s) or data URL).",
+			"           With -i this is image+prompt editing, not text-to-image.",
 			`  -m       model: ${IMAGE_MODELS.join(", ")}   (default: ${config.imageModel})`,
 			"  -s       e.g. 1024x1024. Must be 589824-16777216 total pixels (768x768 .. 4096x4096).",
 			"  --help   this text",
@@ -943,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,
@@ -951,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,
@@ -967,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":
@@ -996,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",
@@ -1014,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",
@@ -1079,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",
@@ -1094,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";
@@ -1105,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;
@@ -1141,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",
@@ -1234,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.",
@@ -1242,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}` }] });
@@ -1342,14 +1428,23 @@ export default function (pi: ExtensionAPI): void {
 		description:
 			"Generate images with the Qwen plan's image models (wan2.7-image, wan2.7-image-pro, qwen-image-3.0-pro) " +
 			"through the native multimodal-generation endpoint. These are not chat models, so they are unreachable " +
-			"from pi's normal model list. Returns temporary hosted image URLs.",
-		promptSnippet: "Generate images with Qwen/Wan image models",
+			"from pi's normal model list. Pass `image` to edit an existing picture instead of drawing from scratch: " +
+			"the reference plus the prompt produce a new image that keeps the source's style and subject layout. " +
+			"Returns temporary hosted image URLs.",
+		promptSnippet: "Generate or edit images with Qwen/Wan image models",
 		promptGuidelines: [
 			"Use qwen_generate_image when the user asks to create or draw an image; report the returned URLs as links and note they are temporary hosted files.",
+			"Use qwen_generate_image with the image parameter when the user wants an existing picture restyled, edited, or used as a reference.",
 			"qwen_generate_image cannot render images in the terminal, so hand the user the URL rather than describing pixels you cannot see.",
 		],
 		parameters: Type.Object({
-			prompt: Type.String({ description: "What to draw." }),
+			prompt: Type.String({ description: "What to draw, or how to change the reference image." }),
+			image: Type.Optional(
+				Type.String({
+					description:
+						"Reference image to edit: http(s) URL, data: URL, or local file path. Omit for text-to-image.",
+				}),
+			),
 			model: Type.Optional(Type.String({ description: `Override model. One of: ${IMAGE_MODELS.join(", ")}.` })),
 			negativePrompt: Type.Optional(Type.String({ description: "What to avoid." })),
 			size: Type.Optional(Type.String({ description: "Pixel size, e.g. 1024*1024. Must be 589824-16777216 total pixels (768² to 4096²)." })),
@@ -1366,7 +1461,7 @@ export default function (pi: ExtensionAPI): void {
 				files = await Promise.all(r.urls.map((u) => saveMedia(ctx, u, r.model, signal)));
 				text += `\n\nSaved:\n${files.map((f) => `  ${f}`).join("\n")}`;
 			}
-			return { content: [{ type: "text", text }], details: { model: r.model, urls: r.urls, files } };
+			return { content: [{ type: "text", text }], details: { model: r.model, urls: r.urls, files, edited: r.edited } };
 		},
 	});
 
@@ -1422,20 +1517,20 @@ export default function (pi: ExtensionAPI): void {
 
 	// ---------------------------------------------------------------- commands
 	pi.registerCommand("qimage", {
-		description: `Generate an image — /qimage <prompt> [-m model] [-s WxH] (default: ${config.imageModel})`,
-		getArgumentCompletions: (prefix) => genCompletions(prefix, { models: IMAGE_MODELS, sizes: [], image: false }),
+		description: `Generate or edit an image — /qimage <prompt> [-i img] [-m model] [-s WxH]`,
+		getArgumentCompletions: (prefix) => genCompletions(prefix, { models: IMAGE_MODELS, sizes: [], image: true }),
 		handler: async (args, ctx) => {
 			if (wantsHelp(args)) {
 				ctx.ui.notify(genUsage("image", ctx.cwd), "info");
 				return;
 			}
-			const { prompt, model, size } = parseGenArgs(args, IMAGE_MODELS);
+			const { prompt, model, size, image } = parseGenArgs(args, IMAGE_MODELS);
 			if (!prompt) {
 				ctx.ui.notify(genUsage("image", ctx.cwd), "error");
 				return;
 			}
-			ctx.ui.notify(`Generating image with ${model || config.imageModel}...`, "info");
-			const r = await generateImage(ctx, { prompt, model, size });
+			ctx.ui.notify(`${image ? "Editing" : "Generating"} image with ${model || config.imageModel}...`, "info");
+			const r = await generateImage(ctx, { prompt, model, size, image });
 			if (!r.urls.length) {
 				ctx.ui.notify(`No image URL from ${r.model}`, "error");
 				return;

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "pi-qtools",
-  "version": "0.1.1",
+  "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": ["pi-package", "pi", "pi-coding-agent", "qwen", "dashscope", "web-search", "web-scraping", "code-interpreter", "image-search", "image-generation", "video-generation"],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "qwen",
+    "dashscope",
+    "web-search",
+    "web-scraping",
+    "code-interpreter",
+    "image-search",
+    "image-generation",
+    "video-generation"
+  ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -17,18 +29,34 @@
   "bugs": {
     "url": "https://github.com/YasribProyas/pi-qtools/issues"
   },
-  "files": ["extensions", "README.md", "LICENSE"],
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "@earendil-works/pi-tui": { "optional": true },
-    "typebox": { "optional": true }
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "pi": {
-    "extensions": ["./extensions/qtools.ts"]
+    "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));
+		},
+	};
+}