dsh-model-input-toggle 0.0.0-stage → 1.0.0

package/tools/test-host.mjs

@@ -0,0 +1,761 @@
+/**
+ * dsh-model-input-toggle — host-half integration test.
+ *
+ * WHAT THIS PROVES
+ * ----------------
+ * It mounts the REAL `apply()` from lib/index.js against fake `settings`,
+ * `llm`, `webServer` and `webRuntime` services, then drives the real HTTP
+ * handler. The fake settings service implements the shipped `applyPathOp` /
+ * `mergeLayers` semantics (see ./settings-semantics.mjs), so a wrong path or a
+ * mis-shaped op fails here exactly as it would against the real service.
+ *
+ * Covered: inventory classification, both pi-ai write branches, DeepSeek write,
+ * conflict retry, the error taxonomy, the trust fence, and the endpoint probe.
+ *
+ * Run: node tools/test-host.mjs
+ */
+
+import { EventEmitter } from "node:events";
+import { assert, assertDeepEqual, applyPathOps, mergeLayers } from "./settings-semantics.mjs";
+
+const plugin = await import("../lib/index.js");
+
+// ── test harness ───────────────────────────────────────────────────────────
+
+let passed = 0;
+let failed = 0;
+
+/** Run one named async test, reporting pass/fail without stopping the suite. */
+async function test(name, fn) {
+	try {
+		await fn();
+		passed += 1;
+		process.stdout.write(`  ok   ${name}\n`);
+	} catch (error) {
+		failed += 1;
+		process.stdout.write(`  FAIL ${name}\n       ${String(error?.message ?? error).replace(/\n/g, "\n       ")}\n`);
+	}
+}
+
+// ── fake services ──────────────────────────────────────────────────────────
+
+const SETTINGS_CONFLICT = Symbol("conflict");
+
+/** Settings service stub with the shipped conflict + layering semantics. */
+function makeSettings(sections, options = {}) {
+	const state = new Map();
+	for (const [ns, section] of Object.entries(sections)) {
+		state.set(ns, { user: section, revision: 0, base: options.bases?.[ns] ?? {}, resolve: options.resolvers?.[ns] ?? ((u) => u) });
+	}
+	let conflictsLeft = options.conflictsLeft ?? 0;
+	const writes = [];
+	return {
+		writes,
+		/** Test-visible current user layer for one namespace. */
+		userOf(ns) {
+			return state.get(ns)?.user;
+		},
+		/** Test-visible resolved value for one namespace. */
+		valueOf(ns) {
+			const entry = state.get(ns);
+			return entry === undefined ? undefined : entry.resolve(entry.user);
+		},
+		describe() {
+			const out = [];
+			for (const [ns, entry] of state) {
+				out.push({
+					ns,
+					revision: entry.revision,
+					value: entry.resolve(entry.user),
+					user: entry.user,
+					base: entry.base,
+					applies: "live"
+				});
+			}
+			return out;
+		},
+		async mutate(ns, ops, expectedRevision) {
+			const entry = state.get(ns);
+			if (entry === undefined) throw new Error(`settings namespace "${ns}" is not registered`);
+			if (entry.revision !== expectedRevision) {
+				const error = new Error(`settings namespace "${ns}" changed since it was read`);
+				error.code = "SETTINGS_CONFLICT";
+				error.expected = expectedRevision;
+				error.actual = entry.revision;
+				throw error;
+			}
+			if (conflictsLeft > 0) {
+				conflictsLeft -= 1;
+				entry.revision += 1; // move it so the retry's read is fresh
+				const error = new Error(`settings namespace "${ns}" changed since it was read`);
+				error.code = "SETTINGS_CONFLICT";
+				throw error;
+			}
+			entry.user = applyPathOps(entry.user, ops);
+			entry.revision += 1;
+			writes.push({ ns, ops });
+		},
+		section(ns) {
+			return state.get(ns)?.user;
+		},
+		/** Exposed so a test can model the conflict symbol. */
+		conflict: SETTINGS_CONFLICT
+	};
+}
+
+/**
+ * A faithful-enough model of what llm-pi-ai resolves for the fields this plugin
+ * reads: `defaultInput`, per-model `input` (user -> catalog -> default), plus
+ * the route's display/transport facts.
+ */
+function resolvePiAi(user, catalog) {
+	const providers = {};
+	const userProviders = user.providers ?? {};
+	for (const [route, configured] of Object.entries(userProviders)) {
+		const known = catalog[route];
+		const catalogBacked = known !== undefined && configured.catalogBacked !== true;
+		const defaultInput = Array.isArray(configured.defaultInput)
+			? configured.defaultInput
+			: Array.isArray(known?.defaultInput)
+				? known.defaultInput
+				: ["text"];
+		const models = (Array.isArray(configured.models) ? configured.models : []).map((model) => {
+			const fromCatalog = known?.models?.find((candidate) => candidate.id === model.id);
+			return {
+				...model,
+				name: model.name ?? fromCatalog?.name ?? model.id,
+				input: model.input ?? fromCatalog?.input ?? defaultInput
+			};
+		});
+		providers[route] = {
+			displayName: configured.displayName ?? route,
+			baseURL: configured.baseURL,
+			api: configured.api ?? "openai-completions",
+			apiKeyEnv: configured.apiKeyEnv,
+			defaultInput,
+			models,
+			catalogBacked
+		};
+	}
+	// Routes the installed catalog serves and the user has not declared.
+	for (const [route, known] of Object.entries(catalog)) {
+		if (providers[route] !== undefined) continue;
+		providers[route] = {
+			displayName: route,
+			baseURL: known.baseURL,
+			api: "openai-completions",
+			defaultInput: known.defaultInput ?? ["text"],
+			models: (known.models ?? []).map((model) => ({
+				...model,
+				name: model.name ?? model.id,
+				input: model.input ?? (known.defaultInput ?? ["text"])
+			})),
+			catalogBacked: true
+		};
+	}
+	return { providers };
+}
+
+/** llm stub: a configurable-provider directory plus resolveModelInfo. */
+function makeLlm(settings, catalog) {
+	const resolvePi = () => resolvePiAi(settings.userOf("llm-pi-ai") ?? {}, catalog);
+	return {
+		listConfigurableProviders() {
+			const resolved = resolvePi();
+			return Object.entries(resolved.providers).map(([route, profile]) => ({
+				provider: route,
+				displayName: profile.displayName,
+				settingsNs: "llm-pi-ai",
+				settingsPath: ["providers", route],
+				declared: profile.catalogBacked !== true
+			}));
+		},
+		async resolveModelInfo(provider, model) {
+			if (provider === "deepseek-official") {
+				const ds = settings.userOf("llm-deepseek") ?? {};
+				const entry = (ds.models ?? []).find((candidate) => candidate.id === model);
+				return { provider, id: model, name: model, inputModalities: entry?.inputModalities ?? ["text"] };
+			}
+			const resolved = resolvePi().providers[provider];
+			if (resolved === undefined) throw new Error(`no adapter for provider "${provider}"`);
+			const entry = resolved.models.find((candidate) => candidate.id === model);
+			if (entry === undefined) throw new Error(`unknown model "${model}"`);
+			return { provider, id: model, name: entry.name, inputModalities: [...entry.input] };
+		}
+	};
+}
+
+/** Mount the plugin against fake services and return the route handler. */
+function mount(settings, llm) {
+	const routes = [];
+	const ctx = {
+		get(name) {
+			if (name === "settings") return settings;
+			if (name === "llm") return llm;
+			return undefined;
+		},
+		effect(callback, label) {
+			const disposer = callback();
+			return disposer ?? (() => void label);
+		},
+		webServer: {
+			register(route) {
+				routes.push(route);
+				return () => void 0;
+			}
+		},
+		webRuntime: { trustedHosts: [] }
+	};
+	plugin.apply(ctx);
+	assert(routes.length === 1, "exactly one route should be registered");
+	assert(routes[0].kind === "prefix", "the route should be a prefix route");
+	return routes[0].handler;
+}
+
+/** Build a fake request carrying a JSON body. */
+function makeReq(body, headers = {}) {
+	const emitter = new EventEmitter();
+	emitter.method = "POST";
+	emitter.headers = {
+		host: "127.0.0.1:3080",
+		"content-type": "application/json",
+		...headers
+	};
+	emitter.destroy = () => void 0;
+	process.nextTick(() => {
+		emitter.emit("data", Buffer.from(JSON.stringify(body)));
+		emitter.emit("end");
+	});
+	return emitter;
+}
+
+/** Invoke the handler and decode the JSON reply. */
+function call(handler, body, headers) {
+	return new Promise((resolve, reject) => {
+		const res = {
+			status: 0,
+			body: undefined,
+			writeHead(status) {
+				this.status = status;
+			},
+			end(text) {
+				try {
+					this.body = JSON.parse(text);
+				} catch (error) {
+					reject(error);
+					return;
+				}
+				resolve({ status: this.status, body: this.body });
+			}
+		};
+		handler(makeReq(body, headers), res).catch(reject);
+	});
+}
+
+// ── fixtures ───────────────────────────────────────────────────────────────
+
+/** The user's own providers: two models, one with an explicit contextWindow. */
+function piAiFixture(extra = {}) {
+	return {
+		providers: {
+			agnes: {
+				apiKeyEnv: "AGNES_API_KEY",
+				api: "openai-completions",
+				baseURL: "https://apihub.agnes-ai.cn/v1",
+				models: [{ id: "agnes-3.0-flash", contextWindow: 512000 }, { id: "agnes-2.5-flash" }],
+				defaultInput: ["text"]
+			},
+			...extra
+		}
+	};
+}
+
+// A catalog-backed route: the user never declared it, so llm-pi-ai serves it
+// straight from its installed catalog. Its id must NOT collide with the
+// llm-deepseek provider id below, or `resolveModelInfo` (which routes by
+// provider id) could not tell the two adapters apart.
+const CATALOG = {
+	openrouter: {
+		baseURL: "https://openrouter.ai/api/v1",
+		defaultInput: ["text"],
+		models: [
+			{ id: "acme-vision-1", input: ["text", "image"] },
+			{ id: "acme-text-1", input: ["text"] }
+		]
+	}
+};
+
+/** Resolver pair for the standard fixture. */
+function standard(piUser, dsUser = {}, catalog = CATALOG) {
+	const settings = makeSettings(
+		{ "llm-pi-ai": piUser, "llm-deepseek": dsUser },
+		{ resolvers: { "llm-pi-ai": (user) => resolvePiAi(user, catalog) } }
+	);
+	const llm = makeLlm(settings, catalog);
+	return { settings, llm };
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+process.stdout.write("dsh-model-input-toggle host tests\n");
+
+await test("list: reports each model's effective modalities and source", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "list" });
+	assert(reply.status === 200, "200");
+	assert(reply.body.ok === true, "ok");
+	const agnes = reply.body.providers.find((entry) => entry.provider === "agnes");
+	assert(agnes !== undefined, "agnes should be listed");
+	assertDeepEqual(agnes.namespace, "llm-pi-ai", "namespace");
+	assertDeepEqual(
+		agnes.models.map((model) => model.id),
+		["agnes-3.0-flash", "agnes-2.5-flash"],
+		"model ids"
+	);
+	// defaultInput is ["text"], so no model declares image.
+	assertDeepEqual(agnes.models[0].effective, ["text"], "effective modalities");
+	assert(agnes.models[0].locked === false, "a user route is not locked");
+	assertDeepEqual(agnes.models[0].source, "defaultInput", "source");
+});
+
+await test("list: a catalog-declared vision model is checked and locked", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "list" });
+	const official = reply.body.providers.find((entry) => entry.provider === "openrouter" && entry.namespace === "llm-pi-ai");
+	assert(official !== undefined, "the catalog route should be listed");
+	const vision = official.models.find((model) => model.id === "acme-vision-1");
+	assert(vision !== undefined, "the vision model should be listed");
+	assertDeepEqual(vision.effective, ["text", "image"], "catalog image declaration");
+	assert(vision.locked === true, "a catalog declaration is locked");
+	assertDeepEqual(vision.source, "catalog", "source");
+});
+
+await test("list: the llm-deepseek namespace is listed separately", async () => {
+	const { settings, llm } = standard(piAiFixture(), {
+		models: [
+			{ id: "deepseek-flash", inputModalities: ["text", "image"] },
+			{ id: "deepseek-v4-flash", inputModalities: ["text"] }
+		]
+	});
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "list" });
+	const ds = reply.body.providers.find((entry) => entry.namespace === "llm-deepseek");
+	assert(ds !== undefined, "the deepseek provider should be listed");
+	assertDeepEqual(ds.provider, "deepseek-official", "provider id");
+	assertDeepEqual(ds.models.map((model) => model.effective), [["text", "image"], ["text"]], "modalities");
+});
+
+await test("set: writes input onto the user's models entry, preserving every sibling", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, {
+		method: "set",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash",
+		supportsImage: true
+	});
+	assert(reply.body.ok === true, `expected ok, got ${JSON.stringify(reply.body)}`);
+	assertDeepEqual(reply.body.declared, ["text", "image"], "verified declaration");
+	assert(reply.body.verified === true, "the adapter must confirm the change");
+
+	// The op must target the whole array (array indices are unreachable).
+	const write = settings.writes.at(-1);
+	assertDeepEqual(write.ops[0].path, ["providers", "agnes", "models"], "op path");
+	const models = settings.userOf("llm-pi-ai").providers.agnes.models;
+	// The edited row carries input AND its original contextWindow.
+	assertDeepEqual(models[0], { id: "agnes-3.0-flash", contextWindow: 512000, input: ["text", "image"] }, "edited row");
+	// The untouched sibling is byte-identical.
+	assertDeepEqual(models[1], { id: "agnes-2.5-flash" }, "sibling row");
+	// defaultInput is not clobbered by an entry-level write.
+	assertDeepEqual(settings.userOf("llm-pi-ai").providers.agnes.defaultInput, ["text"], "defaultInput preserved");
+});
+
+await test("set: disabling writes [\"text\"] back", async () => {
+	const fixture = piAiFixture();
+	fixture.providers.agnes.models[0].input = ["text", "image"];
+	const { settings, llm } = standard(fixture);
+	const handler = mount(settings, llm);
+	const reply = await call(handler, {
+		method: "set",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash",
+		supportsImage: false
+	});
+	assert(reply.body.ok === true, "ok");
+	assertDeepEqual(settings.userOf("llm-pi-ai").providers.agnes.models[0].input, ["text"], "written input");
+	assert(reply.body.verified === true, "verification follows the write down too");
+});
+
+await test("set: with no user models list, writes modelOverrides instead", async () => {
+	const { settings, llm } = standard({
+		providers: {
+			plain: { api: "openai-completions", baseURL: "https://example.test/v1", defaultInput: ["text"] }
+		}
+	});
+	const handler = mount(settings, llm);
+	const reply = await call(handler, {
+		method: "set",
+		namespace: "llm-pi-ai",
+		provider: "plain",
+		modelId: "some-vision-model",
+		supportsImage: true
+	});
+	assert(reply.body.ok === true, `expected ok, got ${JSON.stringify(reply.body)}`);
+	const write = settings.writes.at(-1);
+	assertDeepEqual(
+		write.ops[0].path,
+		["providers", "plain", "modelOverrides", "some-vision-model", "input"],
+		"op path"
+	);
+	// The op must never materialize a `models` list: llm-pi-ai rejects
+	// modelOverrides beside a models list.
+	assert(settings.userOf("llm-pi-ai").providers.plain.models === undefined, "no models list is created");
+	assertDeepEqual(
+		settings.userOf("llm-pi-ai").providers.plain.modelOverrides["some-vision-model"].input,
+		["text", "image"],
+		"override input"
+	);
+});
+
+await test("set: a user models list keeps the override branch unreachable", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	await call(handler, { method: "set", namespace: "llm-pi-ai", provider: "agnes", modelId: "agnes-2.5-flash", supportsImage: true });
+	const user = settings.userOf("llm-pi-ai").providers.agnes;
+	assert(user.modelOverrides === undefined, "modelOverrides must not be introduced beside a models list");
+});
+
+await test("set: unknown provider fails cleanly", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "set", namespace: "llm-pi-ai", provider: "ghost", modelId: "x", supportsImage: true });
+	assert(reply.body.ok === false, "must fail");
+	assertDeepEqual(reply.body.code, "provider-missing", "code");
+	assert(settings.writes.length === 0, "nothing may be written");
+});
+
+await test("set: unknown model in a user models list fails cleanly", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "set", namespace: "llm-pi-ai", provider: "agnes", modelId: "ghost", supportsImage: true });
+	assert(reply.body.ok === false, "must fail");
+	assertDeepEqual(reply.body.code, "model-missing", "code");
+	assert(settings.writes.length === 0, "nothing may be written");
+});
+
+await test("set: an unsupported namespace is refused", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "set", namespace: "llm-other", provider: "agnes", modelId: "x", supportsImage: true });
+	assertDeepEqual(reply.body.code, "unsupported-namespace", "code");
+});
+
+await test("set: a conflict is retried once and then succeeds", async () => {
+	const fixture = piAiFixture();
+	const settings = makeSettings(
+		{ "llm-pi-ai": fixture, "llm-deepseek": {} },
+		{ conflictsLeft: 1, resolvers: { "llm-pi-ai": (user) => resolvePiAi(user, CATALOG) } }
+	);
+	const llm = makeLlm(settings, CATALOG);
+	const handler = mount(settings, llm);
+	const reply = await call(handler, {
+		method: "set",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash",
+		supportsImage: true
+	});
+	assert(reply.body.ok === true, `the retry should succeed: ${JSON.stringify(reply.body)}`);
+	assertDeepEqual(settings.userOf("llm-pi-ai").providers.agnes.models[0].input, ["text", "image"], "written after retry");
+});
+
+await test("set: a persistent conflict reports a manual-refresh instruction", async () => {
+	const settings = makeSettings(
+		{ "llm-pi-ai": piAiFixture(), "llm-deepseek": {} },
+		{ conflictsLeft: 5, resolvers: { "llm-pi-ai": (user) => resolvePiAi(user, CATALOG) } }
+	);
+	const llm = makeLlm(settings, CATALOG);
+	const handler = mount(settings, llm);
+	const reply = await call(handler, {
+		method: "set",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash",
+		supportsImage: true
+	});
+	assertDeepEqual(reply.body.code, "conflict", "code");
+	assert(reply.body.message.includes("手动刷新"), "the message must tell the user what to do");
+});
+
+await test("set: writes the deepseek inputModalities field", async () => {
+	const { settings, llm } = standard(piAiFixture(), {
+		models: [{ id: "deepseek-v4-flash", inputModalities: ["text"] }]
+	});
+	const handler = mount(settings, llm);
+	const reply = await call(handler, {
+		method: "set",
+		namespace: "llm-deepseek",
+		provider: "deepseek-official",
+		modelId: "deepseek-v4-flash",
+		supportsImage: true
+	});
+	assert(reply.body.ok === true, `expected ok, got ${JSON.stringify(reply.body)}`);
+	assertDeepEqual(reply.body.declared, ["text", "image"], "declared");
+	const models = settings.userOf("llm-deepseek").models;
+	assertDeepEqual(models[0].inputModalities, ["text", "image"], "inputModalities written");
+	// The pi-ai namespace must be untouched.
+	assertDeepEqual(settings.userOf("llm-pi-ai"), piAiFixture(), "pi-ai untouched");
+});
+
+await test("resolved layering: the user's array replaces the base array wholesale", async () => {
+	// Proves the op lands in the USER layer with the semantics mergeLayers gives
+	// arrays: a lower layer cannot resurrect the old value, because a
+	// non-plain-object (an array) replaces rather than merges.
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	await call(handler, { method: "set", namespace: "llm-pi-ai", provider: "agnes", modelId: "agnes-2.5-flash", supportsImage: true });
+	const base = { providers: { agnes: { models: [{ id: "agnes-2.5-flash", input: ["text"] }] } } };
+	const merged = mergeLayers(base, settings.userOf("llm-pi-ai"));
+	// The user array wins entirely, so index 0 is the user's *first* model, not
+	// the base's — and the edited model sits at index 1.
+	assertDeepEqual(
+		merged.providers.agnes.models.map((model) => model.id),
+		["agnes-3.0-flash", "agnes-2.5-flash"],
+		"the user array replaced the base array"
+	);
+	assertDeepEqual(merged.providers.agnes.models[1].input, ["text", "image"], "the edited entry keeps its new declaration");
+});
+
+await test("trust fence: a cross-site request is refused", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "list" }, { "sec-fetch-site": "cross-site" });
+	assert(reply.status === 403, "403");
+	assertDeepEqual(reply.body.code, "forbidden", "code");
+});
+
+await test("trust fence: a foreign Host header is refused", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "list" }, { host: "evil.example.com" });
+	assert(reply.status === 403, "403");
+});
+
+await test("protocol: GET and a wrong content-type are refused", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const emitter = new EventEmitter();
+	emitter.method = "GET";
+	emitter.headers = { host: "127.0.0.1:3080", "content-type": "application/json" };
+	emitter.destroy = () => void 0;
+	const getReply = await new Promise((resolve) => {
+		handler(emitter, { writeHead(s) { this.status = s; }, end(t) { resolve({ status: this.status, body: JSON.parse(t) }); } });
+	});
+	assert(getReply.status === 405, "405 for GET");
+	const wrongType = await call(handler, { method: "list" }, { "content-type": "text/plain" });
+	assert(wrongType.status === 415, "415 for a non-JSON content-type");
+});
+
+await test("protocol: an unknown method is a clean 404", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	const reply = await call(handler, { method: "nope" });
+	assert(reply.status === 404, "404");
+	assertDeepEqual(reply.body.code, "not-found", "code");
+});
+
+// ── endpoint verification (mocked fetch) ───────────────────────────────────
+
+/** Run one verify call with a scripted fetch response. */
+async function withFetch(script, fn) {
+	const original = globalThis.fetch;
+	// `script` describes one response, or `script.responses` a sequence — the
+	// verifier deliberately sends a second, image-free control request, so any
+	// test exercising a non-200 path must script both.
+	const queue = Array.isArray(script.responses) ? script.responses.slice() : null;
+	const next = () => (queue === null ? script : (queue.shift() ?? { status: 500, text: "{}" }));
+	script.calls = [];
+	globalThis.fetch = async (url, init) => {
+		const step = next();
+		script.lastUrl = url;
+		script.lastBody = JSON.parse(init.body);
+		script.lastHeaders = init.headers;
+		script.calls.push({ url, body: script.lastBody });
+		if (step.throws !== undefined) throw step.throws;
+		return {
+			ok: step.status >= 200 && step.status < 300,
+			status: step.status,
+			async text() {
+				return step.text ?? "";
+			}
+		};
+	};
+	try {
+		return await fn();
+	} finally {
+		globalThis.fetch = original;
+	}
+}
+
+await test("verify: HTTP 200 is reported as supported", async () => {
+	const fixture = piAiFixture();
+	fixture.providers.agnes.apiKeyEnv = "TEST_KEY";
+	const { settings, llm } = standard(fixture);
+	const handler = mount(settings, llm);
+	process.env.TEST_KEY = "sk-test";
+	const script = { status: 200, text: "{}" };
+	const reply = await withFetch(script, () => call(handler, {
+		method: "verify",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash"
+	}));
+	assertDeepEqual(reply.body.verdict, "supported", "verdict");
+	assert(script.lastUrl === "https://apihub.agnes-ai.cn/v1/chat/completions", `url: ${script.lastUrl}`);
+	assertDeepEqual(script.lastHeaders.authorization, "Bearer sk-test", "authorization");
+	// The probe must be a real image-bearing OpenAI payload.
+	const parts = script.lastBody.messages[1].content;
+	assertDeepEqual(parts[1].type, "image_url", "image part");
+	assert(parts[1].image_url.url.startsWith("data:image/png;base64,"), "inline data URI");
+	// The probe leads with a system message: gateways such as this profile's
+	// jiuling/CodeBuddy proxy reject a request whose first message is not one,
+	// which would otherwise be misread as "does not support images".
+	assertDeepEqual(script.lastBody.messages[0].role, "system", "the probe leads with a system message");
+	// A 200 needs no control request: the image was demonstrably accepted.
+	assert(script.calls.length === 1, "a success sends exactly one request");
+	delete process.env.TEST_KEY;
+});
+
+await test("verify: an image-only rejection is reported as rejected", async () => {
+	const fixture = piAiFixture();
+	fixture.providers.agnes.apiKeyEnv = "TEST_KEY";
+	const { settings, llm } = standard(fixture);
+	const handler = mount(settings, llm);
+	process.env.TEST_KEY = "sk-test";
+	// The image request is refused, but the same request without the image
+	// succeeds — that difference is what proves the image is the problem.
+	const script = {
+		responses: [
+			{ status: 400, text: JSON.stringify({ error: { message: "unexpected content type" } }) },
+			{ status: 200, text: "{}" }
+		]
+	};
+	const reply = await withFetch(script, () => call(handler, {
+		method: "verify",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash"
+	}));
+	assertDeepEqual(reply.body.verdict, "rejected", "verdict");
+	assert(reply.body.message.includes("unexpected content type"), "the endpoint's own words are surfaced");
+	// The control request must genuinely differ: it carries no image part.
+	assert(script.calls.length === 2, "a rejection is confirmed by a control request");
+	const controlParts = script.calls[1].body.messages[1].content;
+	assert(typeof controlParts === "string", "the control request drops the image parts entirely");
+	delete process.env.TEST_KEY;
+});
+
+await test("verify: a failure that also hits the image-free request is inconclusive", async () => {
+	const fixture = piAiFixture();
+	fixture.providers.agnes.apiKeyEnv = "TEST_KEY";
+	const { settings, llm } = standard(fixture);
+	const handler = mount(settings, llm);
+	process.env.TEST_KEY = "sk-test";
+	// Both requests fail identically — a gateway/availability problem, not an
+	// image problem. Accusing the model of lacking vision here would be wrong.
+	const script = {
+		responses: [
+			{
+				status: 502,
+				text: JSON.stringify({
+					error: { message: 'CodeBuddy 上游 HTTP 400：{"code":11102,"msg":"model [glm-5.3-flash] service info not found"}' }
+				})
+			},
+			{ status: 502, text: JSON.stringify({ error: { message: "same failure" } }) }
+		]
+	};
+	const reply = await withFetch(script, () => call(handler, {
+		method: "verify",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash"
+	}));
+	assertDeepEqual(reply.body.verdict, "inconclusive", "verdict");
+	assertDeepEqual(reply.body.ok, false, "an inconclusive probe is not a success");
+	assert(reply.body.message.includes("与图片无关"), `the message must not blame the image: ${reply.body.message}`);
+	// The wrapped JSON must be unwrapped to the one useful sentence.
+	assert(
+		reply.body.message.includes("model [glm-5.3-flash] service info not found"),
+		"the nested upstream message is surfaced"
+	);
+	assert(!reply.body.message.includes('\\"code\\"'), "the raw JSON envelope is not dumped");
+	delete process.env.TEST_KEY;
+});
+
+await test("verify: 401 is unauthorized, 404 is not-found", async () => {
+	const fixture = piAiFixture();
+	fixture.providers.agnes.apiKeyEnv = "TEST_KEY";
+	const { settings, llm } = standard(fixture);
+	const handler = mount(settings, llm);
+	process.env.TEST_KEY = "sk-test";
+	const unauthorized = await withFetch({ status: 401, text: "{}" }, () => call(handler, {
+		method: "verify",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash"
+	}));
+	assertDeepEqual(unauthorized.body.verdict, "unauthorized", "401 verdict");
+	const missing = await withFetch({ status: 404, text: "{}" }, () => call(handler, {
+		method: "verify",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash"
+	}));
+	assertDeepEqual(missing.body.verdict, "not-found", "404 verdict");
+	delete process.env.TEST_KEY;
+});
+
+await test("verify: a network failure is reported, not thrown", async () => {
+	const fixture = piAiFixture();
+	fixture.providers.agnes.apiKeyEnv = "TEST_KEY";
+	const { settings, llm } = standard(fixture);
+	const handler = mount(settings, llm);
+	process.env.TEST_KEY = "sk-test";
+	const reply = await withFetch({ throws: new Error("connect ECONNREFUSED") }, () => call(handler, {
+		method: "verify",
+		namespace: "llm-pi-ai",
+		provider: "agnes",
+		modelId: "agnes-3.0-flash"
+	}));
+	assertDeepEqual(reply.body.verdict, "network", "verdict");
+	assert(reply.body.message.includes("ECONNREFUSED"), "the cause is surfaced");
+	delete process.env.TEST_KEY;
+});
+
+await test("verify: a missing credential is reported before any request", async () => {
+	const { settings, llm } = standard(piAiFixture());
+	const handler = mount(settings, llm);
+	let called = false;
+	const original = globalThis.fetch;
+	globalThis.fetch = async () => {
+		called = true;
+		throw new Error("must not be called");
+	};
+	try {
+		delete process.env.AGNES_API_KEY;
+		const reply = await call(handler, { method: "verify", namespace: "llm-pi-ai", provider: "agnes", modelId: "agnes-3.0-flash" });
+		assertDeepEqual(reply.body.code, "no-credential", "code");
+		assert(called === false, "no request may be attempted without a credential");
+	} finally {
+		globalThis.fetch = original;
+	}
+});
+
+// ── summary ────────────────────────────────────────────────────────────────
+
+process.stdout.write(`\n${passed} passed, ${failed} failed\n`);
+process.exit(failed === 0 ? 0 : 1);