pi-qtools 0.2.2 → 0.3.0

package/README.md

@@ -131,6 +131,61 @@ Persisted to `<agentDir>/qtools.json` (migrated automatically from the older
 }
 ```
 
+## 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

package/extensions/qtools.ts

@@ -39,6 +39,58 @@ import {
 	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
 
@@ -1028,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 "";
 }
@@ -1130,6 +1188,12 @@ function buildItems(ctx: ExtensionContext, th: ThemeLike): SettingItem[] {
 			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",
@@ -1175,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-qtools",
-  "version": "0.2.2",
+  "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": [
@@ -57,6 +57,6 @@
     ]
   },
   "scripts": {
-    "test": "node --experimental-strip-types test/parse.check.mjs && node --experimental-strip-types test/caps.test.mjs"
+    "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/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;
+}