dsh-workbuddy-connect 0.3.1 → 0.4.0

package/lib/index.js

@@ -1,12 +1,15 @@
-import { S as workbuddyOwnAuthPath, _ as WORKBUDDY_AUTH_FILE_ENV, a as readHostHeartbeat, b as defaultDesktopAuthPath, d as normalizeCredits, f as prepareChatBody, g as WORKBUDDY_AUTH_FILENAME, h as WorkBuddyCatalog, i as processStartTimeMs, l as WorkBuddyUpstreamClient, m as FALLBACK_WORKBUDDY_MODELS, n as clearHostHeartbeat, o as workbuddyHostHeartbeatPath, p as regionOf, r as isHeartbeatProcessAlive, s as writeHostHeartbeat, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, u as classifyUpstreamError, v as WorkBuddyCredentialStore, x as parseWorkBuddyAuth, y as defaultDesktopAuthCandidates } from "./host-heartbeat-9FtwMcIF.js";
+import { C as defaultDesktopAuthPath, S as defaultDesktopAuthCandidates, T as workbuddyOwnAuthPath, _ as FALLBACK_WORKBUDDY_MODELS, a as readHostHeartbeat, b as WORKBUDDY_AUTH_FILE_ENV, c as WORKBUDDY_CONNECT_VERSION, d as normalizeCredits, f as prepareChatBody, g as randomSentinel, h as probeModel, i as processStartTimeMs, l as WorkBuddyUpstreamClient, m as PROBE_EFFORT_CANDIDATES, n as clearHostHeartbeat, o as workbuddyHostHeartbeatPath, p as regionOf, r as isHeartbeatProcessAlive, s as writeHostHeartbeat, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, u as classifyUpstreamError, v as WorkBuddyCatalog, w as parseWorkBuddyAuth, x as WorkBuddyCredentialStore, y as WORKBUDDY_AUTH_FILENAME } from "./host-heartbeat-0UAWqWac.js";
 import z from "@deepseek-ai/schemastery";
+import { dirname, join, resolve } from "node:path";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { createProvider } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
-import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 //#region src/adapter.ts
 /**
 * The `workbuddy` pi-ai provider: one loopback-backed adapter registered
@@ -107,29 +110,40 @@ function withCatalogDisplay(name, info) {
 * `thinkingLevelMap` (every level pinned to its wire spelling or `null` for
 * unsupported), mirroring `dsh-llm-pi-ai`'s own `resolveModelReasoning`.
 *
-* Declared sets only: a thinking control is offered exactly when the upstream
-* catalog declares a `supportedEfforts` list, and it offers exactly the
-* declared values. Rows without a list (the older `{effort, summary}` shape)
-* get no control at all — their selectable set is client-side knowledge the
-* catalog does not carry (the desktop app differs per model there: GLM-5.2
-* gets a thinking control while MiniMax-M3 and Kimi-K2.6 do not, though their
-* catalog rows are identical), and another implementation against the same
-* upstream (workbuddy2api) gates on the declared set and downgrades
-* out-of-set values rather than passing them through, so sending an
-* undeclared value risks a 400. Such models never carry `reasoning_effort`
-* on the wire; the upstream applies its own default.
-* `off` is offered only when the model explicitly reports thinking can be
-* disabled (`canDisableThinking === true`).
+* Two sources, strictly ordered (`docs/reasoning-effort-probe-plan.md` §5):
+*
+* 1. **The declared set.** When the upstream declares a non-empty
+*    `supportedEfforts`, exactly those values are offered and nothing else.
+*    This always wins: an observation never widens or narrows a declared set.
+* 2. **A local observation.** Rows without a declared set (the older
+*    `{effort, summary}` shape) normally get no control at all — their
+*    selectable set is client-side knowledge the catalog does not carry, and
+*    the desktop app differs per model there. If the user authorized a probe
+*    and it established that the upstream *validates* the parameter, the
+*    verified spellings are offered.
+*
+* A `non-validating` observation deliberately yields no control: the upstream
+* accepts values that cannot exist (measured on `glm-5.2`), so every per-level
+* acceptance it produced would be a false positive.
+*
+* `off` is offered only when the upstream declares `canDisableThinking: true`.
+* It is never probed — disabling thinking is a separate capability, and the
+* per-model acceptance of `off` cannot be inferred from the row's shape.
+*
+* The offered set is described internally as "verified accepted", never as
+* "verified effective": acceptance proves the upstream did not reject the
+* spelling, not that it changes what the model does.
 */
-function reasoningFields(info) {
+function reasoningFields(info, observed) {
 	const reasoning = info.reasoning;
 	if (reasoning === void 0 || reasoning.supports !== true) return { reasoning: false };
-	const efforts = reasoning.supportedEfforts;
-	if (efforts === void 0 || efforts.length === 0) return { reasoning: false };
+	const declared = reasoning.supportedEfforts;
+	const efforts = declared !== void 0 && declared.length > 0 ? declared : observed?.validation === "validating" && observed.efforts.length > 0 ? observed.efforts : void 0;
+	if (efforts === void 0) return { reasoning: false };
 	return {
 		reasoning: true,
 		thinkingLevelMap: {
-			off: reasoning.canDisableThinking === true ? "off" : null,
+			off: reasoning.canDisableThinking === true && declared !== void 0 && declared.length > 0 ? "off" : null,
 			minimal: null,
 			low: efforts.includes("low") ? "low" : null,
 			medium: efforts.includes("medium") ? "medium" : null,
@@ -140,7 +154,7 @@ function reasoningFields(info) {
 	};
 }
 /** Build one pi-ai model descriptor pointing at the loopback shim. */
-function toPiModel(info, baseUrl) {
+function toPiModel(info, baseUrl, observed) {
 	return {
 		id: info.id,
 		name: info.name,
@@ -148,7 +162,7 @@ function toPiModel(info, baseUrl) {
 		provider: WORKBUDDY_PROVIDER,
 		baseUrl,
 		input: info.supportsImages === true ? ["text", "image"] : ["text"],
-		...reasoningFields(info),
+		...reasoningFields(info, observed),
 		cost: NO_COST,
 		contextWindow: info.contextWindow,
 		maxTokens: info.maxTokens
@@ -158,12 +172,19 @@ function toPiModel(info, baseUrl) {
 * Assemble the adapter. The provider's `getModels` reads the live catalog,
 * and every model's `baseUrl` is re-resolved per read so the shim's
 * ephemeral port applies from the first snapshot after startup.
+*
+* The profile is constructed by hand rather than through dsh-llm-pi-ai's
+* internal `resolveProfiles()`: that helper is not part of the package's
+* public export surface (root entry, `lib/` deep imports blocked by the
+* exports map, `src/` not shipped), so hand-assembly is the only supported
+* path and every newly required field must be adopted here explicitly —
+* `modelErrors` since 0.1.5-alpha.2 (#12).
 */
 function createWorkBuddyAdapter(options) {
-	const { shim, store, catalog, resolveAttachments } = options;
+	const { shim, store, catalog, resolveAttachments, observe } = options;
 	const buildModels = () => {
 		const baseUrl = `${shim.baseUrl()}/v1`;
-		return catalog.current().map((info) => toPiModel(info, baseUrl));
+		return catalog.current().map((info) => toPiModel(info, baseUrl, observe?.(info.id)));
 	};
 	const provider = {
 		...createProvider({
@@ -190,6 +211,7 @@ function createWorkBuddyAdapter(options) {
 		streamIdleTimeoutMs: WORKBUDDY_STREAM_IDLE_TIMEOUT_MS,
 		retryPolicy: resolveRetryPolicy(void 0, "dsh-workbuddy-connect retryPolicy"),
 		configuredMaxTokens: /* @__PURE__ */ new Map(),
+		modelErrors: /* @__PURE__ */ new Map(),
 		...REQUEST_IMAGE_BUDGETS,
 		piProvider: provider
 	};
@@ -349,7 +371,7 @@ function writeOpenAIError(res, status, kind, message) {
 	} });
 }
 /** Read a request body with a size cap; over-limit bodies fail the request. */
-function readBody(req) {
+function readBody$1(req) {
 	return new Promise((resolve, reject) => {
 		const chunks = [];
 		let size = 0;
@@ -453,7 +475,7 @@ function createWorkBuddyShim(options) {
 			writeOpenAIError(res, 401, "not_signed_in", String(error));
 			return;
 		}
-		const raw = (await readBody(req)).toString("utf8");
+		const raw = (await readBody$1(req)).toString("utf8");
 		const prepared = prepareChatBody(raw);
 		const controller = new AbortController();
 		req.on("close", () => controller.abort());
@@ -491,17 +513,317 @@ function createWorkBuddyShim(options) {
 	};
 }
 //#endregion
+//#region src/probe-store.ts
+/**
+* Local record of reasoning-effort probes.
+*
+* What this stores is an *observation*, never a claim about the upstream: a
+* model's row is only consulted when the catalog carries no explicit
+* `supportedEfforts` set, and it always loses to a declared set. The plan this
+* implements (`docs/reasoning-effort-probe-plan.md` §5) requires that a result
+* is invalidated whenever the model's catalog row changes, so every record
+* carries a fingerprint of the fields the probe depended on.
+*
+* The file lives beside the plugin's own credential copy under `$DSH_HOME`,
+* never in the desktop app's files, and carries no token, prompt, or response
+* body — only model ids, effort spellings, and timestamps.
+*
+* @module dsh-workbuddy-connect/probe-store
+*/
+/** Basename of the probe record inside the Harness home. */
+const WORKBUDDY_PROBE_FILENAME = ".workbuddy-probe.json";
+/** On-disk format this reader accepts; other versions are discarded. */
+const PROBE_FORMAT_VERSION = 1;
+/**
+* How long an observation stays usable. Conservative on purpose: the plan's
+* whole argument is that upstream metadata moves fast, so a result that has
+* outlived its fingerprint's usefulness should not quietly keep granting a
+* picker entry.
+*/
+const DEFAULT_TTL_MS = 12096e5;
+/** Plugin-owned probe record path inside the Harness home. */
+function workbuddyProbePath() {
+	return join(resolveDshHome(), WORKBUDDY_PROBE_FILENAME);
+}
+/**
+* Fingerprint the catalog fields a probe depends on.
+*
+* Deliberately excludes display-only fields (`name`, `billing`, `contextWindow`)
+* so a rename or a promo badge does not throw away a valid observation, and
+* deliberately includes the whole reasoning object so any change to the
+* declared shape re-probes.
+*/
+function fingerprintModel(info) {
+	const basis = JSON.stringify({
+		id: info.id,
+		reasoning: info.reasoning ?? null,
+		supportsImages: info.supportsImages ?? null
+	});
+	return createHash("sha256").update(basis).digest("hex").slice(0, 16);
+}
+/** Read-and-validate the documents on disk; anything malformed reads as empty. */
+function readDocument(path) {
+	if (!existsSync(path)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	const wrapped = parsed;
+	if (wrapped["version"] !== PROBE_FORMAT_VERSION) return void 0;
+	const records = wrapped["records"];
+	if (typeof records !== "object" || records === null || Array.isArray(records)) return void 0;
+	return parsed;
+}
+/** One record's shape check; a bad row is dropped rather than trusted. */
+function isRecord(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const wrapped = value;
+	const validation = wrapped["validation"];
+	if (validation !== "validating" && validation !== "non-validating" && validation !== "unknown") return false;
+	if (typeof wrapped["fingerprint"] !== "string") return false;
+	if (typeof wrapped["probedAtMs"] !== "number" || !Number.isFinite(wrapped["probedAtMs"])) return false;
+	if (typeof wrapped["pluginVersion"] !== "string") return false;
+	const efforts = wrapped["efforts"];
+	if (!Array.isArray(efforts) || efforts.some((effort) => typeof effort !== "string")) return false;
+	return true;
+}
+/**
+* The plugin's probe records: read once, written atomically, never trusted
+* across a fingerprint change or past the TTL.
+*/
+var WorkBuddyProbeStore = class {
+	path;
+	ttlMs;
+	pluginVersion;
+	now;
+	records;
+	constructor(options) {
+		const opts = typeof options === "string" ? {
+			path: options,
+			pluginVersion: "0.0.0"
+		} : options;
+		this.path = opts.path ?? workbuddyProbePath();
+		this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+		this.pluginVersion = opts.pluginVersion;
+		this.now = opts.now ?? (() => Date.now());
+	}
+	/** Resolved state-file path, for the CLI and tests. */
+	filePath() {
+		return this.path;
+	}
+	load() {
+		if (this.records === void 0) {
+			const document = readDocument(this.path);
+			const records = {};
+			for (const [id, record] of Object.entries(document?.records ?? {})) if (isRecord(record)) records[id] = record;
+			this.records = records;
+		}
+		return this.records;
+	}
+	/**
+	* The usable record for a model, or `undefined` when there is none, it is
+	* expired, or it was taken against a different catalog row.
+	*/
+	get(modelId, fingerprint) {
+		const record = this.load()[modelId];
+		if (record === void 0) return void 0;
+		if (record.fingerprint !== fingerprint) return void 0;
+		if (this.now() - record.probedAtMs > this.ttlMs) return void 0;
+		return record;
+	}
+	/**
+	* Store one observation. Only a decisive answer (`validating` /
+	* `non-validating`) replaces an existing decisive record: a transient
+	* `unknown` must not erase knowledge the user already paid for.
+	*/
+	set(modelId, record) {
+		const records = this.load();
+		const existing = records[modelId];
+		if (record.validation === "unknown" && existing !== void 0 && existing.fingerprint === record.fingerprint && existing.validation !== "unknown") return;
+		records[modelId] = record;
+		this.persist();
+	}
+	/** Drop every record; used by the card's explicit "clear" action. */
+	clear() {
+		this.records = {};
+		this.persist();
+	}
+	/** Every record currently held, for status display. */
+	all() {
+		return { ...this.load() };
+	}
+	/** Build a record stamped with this store's clock and version. */
+	record(fingerprint, validation, efforts) {
+		return {
+			fingerprint,
+			validation,
+			efforts: validation === "validating" ? [...efforts] : [],
+			probedAtMs: this.now(),
+			pluginVersion: this.pluginVersion
+		};
+	}
+	/**
+	* Write through a temporary file and rename, so a crash mid-write cannot
+	* leave a half-parsed document that reads as "no records" and silently drops
+	* every observation.
+	*/
+	persist() {
+		const directory = dirname(this.path);
+		try {
+			if (!existsSync(directory)) mkdirSync(directory, { recursive: true });
+			const document = {
+				version: PROBE_FORMAT_VERSION,
+				records: this.load()
+			};
+			const temporary = resolve(`${this.path}.tmp`);
+			writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 384 });
+			renameSync(temporary, this.path);
+		} catch {}
+	}
+};
+/**
+* Order observations newest-first for display.
+*
+* The store keeps insertion order so the file reads chronologically, but the
+* card wants the most recent detection at the top: a sweep the user just ran
+* should not appear below every earlier one, which is what appending to an
+* insertion-ordered list does.
+*/
+function newestFirst(records) {
+	return [...records].sort((a, b) => b.probedAt - a.probedAt);
+}
+//#endregion
+//#region src/probe-service.ts
+/**
+* Serial probe runner. One instance is shared by the manual API and any
+* future automatic trigger, so the two can never overlap.
+*/
+var WorkBuddyProbeService = class {
+	options;
+	queue = Promise.resolve();
+	pending = /* @__PURE__ */ new Map();
+	running = false;
+	constructor(options) {
+		this.options = options;
+	}
+	/** Whether a sweep is in flight right now. */
+	isRunning() {
+		return this.running;
+	}
+	/**
+	* The record the adapter may use for this model, or `undefined`.
+	*
+	* Applies the plan's precedence (§5): a declared set always wins, so a model
+	* that declares `supportedEfforts` is never answered from an observation.
+	*/
+	recordFor(modelId) {
+		const info = this.options.catalog.current().find((model) => model.id === modelId);
+		if (info === void 0) return void 0;
+		if (info.reasoning?.supportedEfforts !== void 0 && info.reasoning.supportedEfforts.length > 0) return;
+		return this.options.store.get(modelId, fingerprintModel(info));
+	}
+	/**
+	* Probe one model, serially.
+	*
+	* The authenticated manual route supplies one-request consent after UI
+	* confirmation. Other callers must pass the configured consent gate.
+	* Manual consent never changes the automatic-probing configuration.
+	* Explicit requests bypass historical results, but share an ongoing run.
+	*/
+	async probe(modelId, manualConsent = false) {
+		if (!manualConsent && !this.options.consent()) return {
+			state: "unavailable",
+			reason: "probing is not authorized"
+		};
+		if (this.options.catalog.current().find((model) => model.id === modelId) === void 0) return {
+			state: "unavailable",
+			reason: `unknown model: ${modelId}`
+		};
+		const pending = this.pending.get(modelId);
+		if (pending !== void 0) return pending;
+		const run = this.queue.then(async () => {
+			const current = this.options.catalog.current().find((model) => model.id === modelId);
+			if (current === void 0) return {
+				state: "unavailable",
+				reason: `unknown model: ${modelId}`
+			};
+			if (!manualConsent && !this.options.consent()) return {
+				state: "unavailable",
+				reason: "probing is not authorized"
+			};
+			if (current.reasoning?.supports !== true || (current.reasoning.supportedEfforts?.length ?? 0) > 0) return {
+				state: "unavailable",
+				reason: "model does not need detection"
+			};
+			const cached = this.recordFor(modelId);
+			if (!manualConsent && cached !== void 0 && cached.validation !== "unknown") return {
+				state: "ok",
+				validation: cached.validation,
+				efforts: cached.efforts,
+				requests: 0
+			};
+			const credential = await this.options.credentials.current();
+			if (credential === void 0) return {
+				state: "unavailable",
+				reason: "no WorkBuddy credential"
+			};
+			const send = this.options.send === void 0 ? (effort, signal) => this.options.client.probeEffort(credential, modelId, effort, signal) : this.options.send(modelId);
+			this.running = true;
+			try {
+				const outcome = await probeModel({
+					send,
+					...this.options.sentinel === void 0 ? {} : { sentinel: this.options.sentinel }
+				});
+				const record = this.options.store.record(fingerprintModel(current), outcome.validation, outcome.efforts);
+				this.options.store.set(modelId, record);
+				if (outcome.validation === "unknown") return {
+					state: "unavailable",
+					reason: outcome.reason
+				};
+				return {
+					state: "ok",
+					validation: outcome.validation,
+					efforts: record.efforts,
+					requests: outcome.requests
+				};
+			} finally {
+				this.running = false;
+			}
+		});
+		this.queue = run.catch(() => void 0);
+		this.pending.set(modelId, run);
+		try {
+			return await run;
+		} finally {
+			this.pending.delete(modelId);
+		}
+	}
+};
+//#endregion
 //#region src/status-paths.ts
 /** Node-free constants and types shared by the Host and browser halves. */
 /** Plugin-owned status endpoint consumed by its browser half. */
 const WORKBUDDY_STATUS_PATH = "/plugins/dsh-workbuddy-connect/status";
+/**
+* Plugin-owned probe control endpoint.
+*
+* Separate from the status route because it accepts writes: the status route's
+* loopback Host/Origin guard protects against a DNS-rebinding *page*, which is
+* not the same as authorizing a state-changing action. This route therefore
+* also requires the in-process key the browser half receives with the status
+* document.
+*/
+const WORKBUDDY_PROBE_PATH = "/plugins/dsh-workbuddy-connect/probe";
 //#endregion
 //#region src/web-status.ts
 /** Redact token-like content before it crosses to the browser. */
 function safeMessage(error) {
 	return (error instanceof Error ? error.message : String(error)).replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[redacted token]").replace(/(\b(?:code|token|refresh_token|access_token)=)[^&\s]+/giu, "$1[redacted]").slice(0, 500);
 }
-function json(res, status, body) {
+function json$1(res, status, body) {
 	const payload = JSON.stringify(body);
 	res.writeHead(status, {
 		"Content-Type": "application/json",
@@ -533,52 +855,58 @@ async function workBuddyWebStatus(deps) {
 		...authStatus.source === void 0 ? {} : { source: authStatus.source },
 		...authStatus.expiresAtMs === void 0 ? {} : { expiresAt: authStatus.expiresAtMs }
 	};
-	const modelsField = deps.models().filter((model) => model.billing?.free === true || (model.billing?.badges?.length ?? 0) > 0).map((model) => {
+	const modelsField = deps.models().map((model) => {
 		const rate = normalizeCredits(model.billing?.credits);
 		return {
 			id: model.id,
 			name: model.name,
 			...model.billing?.free === true ? { free: true } : {},
 			...model.billing?.badges !== void 0 && model.billing.badges.length > 0 ? { badges: model.billing.badges } : {},
-			...rate === void 0 ? {} : { credits: rate }
+			...rate === void 0 ? {} : { credits: rate },
+			...typeof model.contextWindow === "number" && model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}
 		};
 	});
 	const statusWithModels = modelsField.length > 0 ? {
 		...status,
 		models: modelsField
 	} : status;
+	const probed = deps.probe === void 0 ? statusWithModels : {
+		...statusWithModels,
+		probe: deps.probe(),
+		...deps.probeKey === void 0 ? {} : { probeKey: deps.probeKey }
+	};
 	try {
 		const credential = await deps.store.current();
 		if (credential !== void 0) {
 			const credits = await deps.client.fetchCredits(credential);
 			return {
-				...statusWithModels,
+				...probed,
 				credits
 			};
 		}
 	} catch (error) {
 		return {
-			...statusWithModels,
+			...probed,
 			creditsError: safeMessage(error)
 		};
 	}
-	return statusWithModels;
+	return probed;
 }
 /** The status route's request handler, extracted so tests can mount it on a bare server. */
 function workBuddyStatusHandler(deps) {
 	return async (req, res) => {
 		if (req.method !== "GET") {
-			json(res, 405, { error: "method not allowed" });
+			json$1(res, 405, { error: "method not allowed" });
 			return;
 		}
 		if (!loopbackRequest(req)) {
-			json(res, 403, { error: "request-not-trusted" });
+			json$1(res, 403, { error: "request-not-trusted" });
 			return;
 		}
 		try {
-			json(res, 200, await workBuddyWebStatus(deps));
+			json$1(res, 200, await workBuddyWebStatus(deps));
 		} catch (error) {
-			json(res, 500, { error: safeMessage(error) });
+			json$1(res, 500, { error: safeMessage(error) });
 		}
 	};
 }
@@ -596,6 +924,136 @@ function registerWorkBuddyStatusRoute(ctx, deps) {
 	}, "dsh-workbuddy-connect: Web status route");
 }
 //#endregion
+//#region src/probe-route.ts
+/**
+* Probe control route: the only state-changing endpoint the plugin exposes.
+*
+* Two guards, because they stop different things (see `docs/reasoning-effort-probe-plan.md`
+* §6.4 and the v0.3.1 note in AGENTS.md about their exact scope):
+*
+* 1. **Loopback Host + Origin**, shared with the status route. This drops
+*    DNS-rebinding pages, whose requests arrive addressed to the attacker's
+*    domain.
+* 2. **An in-process random key**, minted per process and handed only to the
+*    same-origin card. Loopback alone is *not* authentication — any local
+*    process can write `Host: 127.0.0.1` — so a route that spends the user's
+*    credit must prove the caller was told the key.
+*
+* The route never accepts a prompt, a model id outside the live catalog, or a
+* sentinel from the browser: a probe request is assembled entirely host-side.
+*
+* @module dsh-workbuddy-connect/probe-route
+*/
+/** Largest control body accepted; these payloads are a few dozen bytes. */
+const MAX_BODY_BYTES = 4096;
+/** Mint the per-process control key. */
+function createProbeKey() {
+	return randomBytes(24).toString("hex");
+}
+/**
+* Constant-time key comparison; a length mismatch is a failure, not a crash.
+*/
+function keyMatches(expected, presented) {
+	if (presented === void 0 || presented.length !== expected.length) return false;
+	const a = Buffer.from(expected);
+	const b = Buffer.from(presented);
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+function json(res, status, body) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		"Content-Type": "application/json",
+		"Content-Length": Buffer.byteLength(payload)
+	});
+	res.end(payload);
+}
+/** Read the request body with a hard ceiling. */
+async function readBody(req) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		total += buffer.length;
+		if (total > MAX_BODY_BYTES) return void 0;
+		chunks.push(buffer);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Parse and shape-check an action; unknown fields are ignored, not trusted. */
+function parseAction(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	const wrapped = parsed;
+	const action = wrapped["action"];
+	if (action === "clear") return { action: "clear" };
+	if (action === "probe") {
+		const model = wrapped["model"];
+		if (typeof model !== "string" || model.trim() === "") return void 0;
+		return {
+			action: "probe",
+			model: model.trim()
+		};
+	}
+}
+/**
+* The control route's handler, extracted so tests can mount it on a bare
+* server with a known key.
+*/
+function workBuddyProbeHandler(deps, key) {
+	return async (req, res) => {
+		if (req.method !== "POST") {
+			json(res, 405, { error: "method not allowed" });
+			return;
+		}
+		if (!hostIsLoopback(req.headers.host) || !originIsLoopback(req.headers.origin)) {
+			json(res, 403, { error: "request-not-trusted" });
+			return;
+		}
+		if (!keyMatches(key, req.headers["x-workbuddy-probe-key"])) {
+			json(res, 403, { error: "invalid-probe-key" });
+			return;
+		}
+		const body = await readBody(req);
+		if (body === void 0) {
+			json(res, 413, { error: "body too large" });
+			return;
+		}
+		const action = parseAction(body);
+		if (action === void 0) {
+			json(res, 400, { error: "invalid action" });
+			return;
+		}
+		try {
+			if (action.action === "clear") {
+				deps.clear();
+				json(res, 200, { state: "cleared" });
+				return;
+			}
+			json(res, 200, await deps.probe(action.model));
+		} catch (error) {
+			json(res, 500, { error: error instanceof Error ? error.message : String(error) });
+		}
+	};
+}
+/** Mount the POST probe-control route on an optional webServer context. */
+function registerWorkBuddyProbeRoute(ctx, deps, key) {
+	ctx.effect(() => {
+		const dispose = ctx.webServer.register({
+			kind: "exact",
+			path: WORKBUDDY_PROBE_PATH,
+			handler: workBuddyProbeHandler(deps, key)
+		});
+		return () => {
+			dispose();
+		};
+	}, "dsh-workbuddy-connect: probe control route");
+}
+//#endregion
 //#region src/index.ts
 /** Stable Cordis plugin name. */
 const name = "llm-workbuddy";
@@ -614,7 +1072,10 @@ const inject = ["llm"];
 * their namespaces as plain string literals).
 */
 const WORKBUDDY_SETTINGS_NS = "workbuddy";
-const Config = z.object({ authFile: z.string().description("WorkBuddy desktop auth file (defaults to the app's own location)") });
+const Config = z.object({
+	authFile: z.string().description("WorkBuddy desktop auth file (defaults to the app's own location)"),
+	probeConsent: z.boolean().default(false).description("Authorize reasoning-effort probes (each probe sends real requests that may consume credit)")
+});
 /**
 * Start the loopback endpoint, register the `workbuddy` provider, and
 * refresh the model catalog from the upstream once credentials allow it.
@@ -634,12 +1095,73 @@ function apply(ctx, config) {
 		catalog,
 		logger: ctx.logger
 	});
-	ctx.inject(["webServer"], (webCtx) => registerWorkBuddyStatusRoute(webCtx, {
-		store,
-		client,
-		models: () => catalog.current()
-	}));
 	let current = () => config;
+	const probeStore = new WorkBuddyProbeStore({ pluginVersion: WORKBUDDY_CONNECT_VERSION });
+	const probeService = new WorkBuddyProbeService({
+		store: probeStore,
+		catalog,
+		credentials: store,
+		client,
+		consent: () => current().probeConsent === true
+	});
+	/**
+	* Whether a model can be probed by hand: it reasons and the upstream declares
+	* no effort set for it.
+	*
+	* Deliberately *not* filtered by whether a result already exists. Dropping a
+	* model once it has been detected made the list shrink with use, so
+	* re-detecting one model — after an upstream change, say — meant clearing
+	* every other result first. The list stays stable and the card marks which
+	* entries already have an answer.
+	*/
+	const isProbeCandidate = (info) => {
+		if (info.reasoning?.supports !== true) return false;
+		return (info.reasoning.supportedEfforts?.length ?? 0) === 0;
+	};
+	/** Compact probe state for the card: consent, candidates, observations. */
+	const probeSection = () => {
+		const config = current();
+		const models = catalog.current();
+		const results = models.flatMap((info) => {
+			const record = probeService.recordFor(info.id);
+			if (record === void 0) return [];
+			return [{
+				id: info.id,
+				name: info.name,
+				validation: record.validation,
+				efforts: record.efforts,
+				probedAt: record.probedAtMs
+			}];
+		});
+		return {
+			consent: config.probeConsent === true,
+			running: probeService.isRunning(),
+			candidates: models.filter(isProbeCandidate).map((info) => info.id),
+			results: newestFirst(results)
+		};
+	};
+	const probeKey = createProbeKey();
+	let refreshProbeModels = () => {};
+	ctx.inject(["webServer"], (webCtx) => {
+		registerWorkBuddyStatusRoute(webCtx, {
+			store,
+			client,
+			models: () => catalog.current(),
+			probe: () => probeSection(),
+			probeKey
+		});
+		registerWorkBuddyProbeRoute(webCtx, {
+			probe: async (modelId) => {
+				const result = await probeService.probe(modelId, true);
+				if (result.state === "ok") refreshProbeModels();
+				return result;
+			},
+			clear: () => {
+				probeStore.clear();
+				refreshProbeModels();
+			}
+		}, probeKey);
+	});
 	ctx.inject(["settings"], (settingsCtx) => {
 		settingsCtx.settings.installSection(ctx, WORKBUDDY_SETTINGS_NS, Config, config, {
 			setSource(source) {
@@ -665,9 +1187,15 @@ function apply(ctx, config) {
 				shim,
 				store,
 				catalog,
-				resolveAttachments: () => ctx.get("attachments")
+				resolveAttachments: () => ctx.get("attachments"),
+				observe: (modelId) => probeService.recordFor(modelId)
 			});
 			invalidate = workbuddy.invalidate;
+			refreshProbeModels = () => {
+				if (stopped) return;
+				workbuddy.invalidate();
+				ctx.emit("llm/adapters-updated");
+			};
 			let releaseAdapter;
 			let releaseDirectory;
 			try {
@@ -716,4 +1244,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, FALLBACK_WORKBUDDY_MODELS, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_PROVIDER, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WorkBuddyCatalog, WorkBuddyCredentialStore, WorkBuddyUpstreamClient, apply, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthPath, inject, isHeartbeatProcessAlive, name, normalizeCredits, parseWorkBuddyAuth, prepareChatBody, processStartTimeMs, readHostHeartbeat, regionOf, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath };
+export { Config, FALLBACK_WORKBUDDY_MODELS, PROBE_EFFORT_CANDIDATES, WORKBUDDY_AUTH_FILENAME, WORKBUDDY_AUTH_FILE_ENV, WORKBUDDY_HOST_HEARTBEAT_FILENAME, WORKBUDDY_PROBE_FILENAME, WORKBUDDY_PROVIDER, WORKBUDDY_SETTINGS_NS, WORKBUDDY_STREAM_IDLE_TIMEOUT_MS, WorkBuddyCatalog, WorkBuddyCredentialStore, WorkBuddyProbeService, WorkBuddyProbeStore, WorkBuddyUpstreamClient, apply, classifyUpstreamError, clearHostHeartbeat, createWorkBuddyAdapter, createWorkBuddyShim, defaultDesktopAuthCandidates, defaultDesktopAuthPath, fingerprintModel, inject, isHeartbeatProcessAlive, name, normalizeCredits, parseWorkBuddyAuth, prepareChatBody, probeModel, processStartTimeMs, randomSentinel, readHostHeartbeat, regionOf, workbuddyHostHeartbeatPath, workbuddyOwnAuthPath, workbuddyProbePath };