dsh-packycode-api 1.0.7 → 1.1.0

package/lib/index.js

@@ -1,19 +1,167 @@
 import { randomUUID } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
 import { isAbsolute, join, posix, win32 } from "node:path";
-import { LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
-import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
-import { defineTool } from "@deepseek-ai/dsh-tools";
 import z from "@deepseek-ai/schemastery";
-import { homedir, tmpdir } from "node:os";
+import { HarnessError, LlmAdapter, LlmError, QUOTA_EXCEEDED_CODE, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { defineTool } from "@deepseek-ai/dsh-tools";
 import { credentialKey } from "@deepseek-ai/dsh-credentials";
-import { readFile, readdir, realpath } from "node:fs/promises";
+import { readFile, readdir, realpath, rename, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
 import { createProvider } from "@earendil-works/pi-ai";
 import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/request.js
+/**
+* The host-side HTTP plumbing every reader shares: fetch resolved at call
+* time, one request bounded by a timeout and the caller's cancellation with
+* redirects refused, and a shared request one caller's cancellation cannot
+* abort for the others.
+*
+* @module dsh-packycode-api/request
+*/
+/**
+* Resolve fetch at call time. A sibling plugin may wrap `globalThis.fetch`
+* and later dismantle that wrapper; a binding captured during `apply()` would
+* keep the dead wrapper for the process lifetime.
+*/
+function ambientFetch(input, init) {
+	const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
+	if (!headers.has("accept-encoding")) headers.set("accept-encoding", "identity");
+	return globalThis.fetch(input, {
+		...init,
+		headers
+	});
+}
+/** One caller's cancellation must not abort a request other callers share. */
+function waitForSharedRequest(promise, signal) {
+	if (signal === void 0) return promise;
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+/**
+* A request that got no answer. Node's fetch reports every transport fault as
+* a bare `fetch failed`; the message names the part a reader can act on.
+*/
+var TransportError = class extends Error {
+	/**
+	* @param cause - what fetch threw.
+	* @param state - whether the timeout or the caller ended the request.
+	*/
+	constructor(cause, { timedOut, aborted, timeoutMs }) {
+		const code = typeof cause?.cause?.code === "string" ? cause.cause.code : typeof cause?.code === "string" ? cause.code : void 0;
+		const text = cause instanceof Error ? cause.message : String(cause);
+		super(timedOut ? `no answer within ${Math.round(timeoutMs / 1e3)}s` : code === void 0 ? text : `${text} (${code})`, { cause });
+		this.name = "TransportError";
+		/** The system error code, when the transport reported one. */
+		this.code = code;
+		/** The timeout ended the request. */
+		this.timedOut = timedOut;
+		/** The caller ended the request. */
+		this.aborted = aborted;
+	}
+};
+/**
+* One request, bounded by `timeoutMs` and the caller's `signal`, refusing
+* redirects. A transport failure throws a {@link TransportError}.
+* @param url - the target.
+* @param init - fetch options; `redirect` and `signal` are set here.
+* @param options - the fetch to use, the timeout, and the caller's signal.
+* @returns the response, whatever its status.
+*/
+async function boundedFetch(url, init, { fetchImpl = ambientFetch, timeoutMs, signal } = {}) {
+	const timeout = AbortSignal.timeout(timeoutMs);
+	const requestSignal = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+	try {
+		return await fetchImpl(url, {
+			...init,
+			redirect: "error",
+			signal: requestSignal
+		});
+	} catch (error) {
+		const aborted = signal?.aborted === true;
+		throw new TransportError(error, {
+			aborted,
+			timedOut: !aborted && timeout.aborted,
+			timeoutMs
+		});
+	}
+}
+//#endregion
+//#region src/cached-read.js
+/**
+* The read cache the balance, group, and version readers share.
+*
+* A read inside the TTL answers from the cache. Concurrent unforced reads
+* share one request, and one caller cancelling does not abort it for the
+* others. A forced read always goes out under the caller's own signal. A read
+* that started before an invalidation never repopulates the cache.
+*
+* @module dsh-packycode-api/cached-read
+*/
+const clone = (value) => structuredClone(value);
+/**
+* @param load - `(signal) => Promise<value>`; the value carries `fetchedAt`.
+* @param options - the TTL and clock.
+* @returns `{ read({ force, signal }), snapshot(), peek(), invalidate() }`.
+*/
+function createCachedRead(load, { ttlMs, now = Date.now }) {
+	let cached;
+	let inFlight;
+	let generation = 0;
+	const start = (signal) => {
+		const observed = generation;
+		return load(signal).then((value) => {
+			if (generation === observed) cached = value;
+			return value;
+		});
+	};
+	return Object.freeze({
+		/** A copy of the current value; fresh from the network when forced or expired. */
+		async read({ force = false, signal } = {}) {
+			signal?.throwIfAborted();
+			if (!force && cached !== void 0 && now() - cached.fetchedAt < ttlMs) return clone(cached);
+			if (force) return clone(await start(signal));
+			if (inFlight === void 0) {
+				const pending = start();
+				inFlight = pending;
+				const clear = () => {
+					if (inFlight === pending) inFlight = void 0;
+				};
+				pending.then(clear, clear);
+			}
+			return clone(await waitForSharedRequest(inFlight, signal));
+		},
+		/** A copy of the last value, however old, without a request. */
+		snapshot() {
+			return cached === void 0 ? void 0 : clone(cached);
+		},
+		/** The last value itself, for synchronous lookups that do not keep it. */
+		peek() {
+			return cached;
+		},
+		/** Drop the value; a read already in flight will not restore it. */
+		invalidate() {
+			generation += 1;
+			cached = void 0;
+		}
+	});
+}
+//#endregion
 //#region src/constants.js
 /**
 * Identities and defaults this plugin owns.
@@ -61,6 +209,63 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 2e4;
 /** Effort level the route requests when a session names none. */
 const DEFAULT_REASONING_LEVEL = "high";
 //#endregion
+//#region src/hosts.js
+/**
+* Which hosts a read goes to.
+*
+* PackyCode serves models and the billing endpoints from `cf.api.fan`, and
+* the per-key `/api/*` family plus public pricing from the PackyAPI site
+* (`cf.api.fan` answers 404 there). A saved legacy status host
+* (`www.packyapi.com`, DNS-poisoned on mainland networks) is tried after the
+* current default, never before it.
+*
+* @module dsh-packycode-api/hosts
+*/
+/** Accept an absolute http(s) origin and drop a trailing slash. */
+function normalizeHost(value, fallback) {
+	const text = typeof value === "string" ? value.trim() : "";
+	if (text === "") return fallback;
+	let url;
+	try {
+		url = new URL(text);
+	} catch {
+		return fallback;
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") return fallback;
+	return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
+}
+const unique = (hosts) => [...new Set(hosts.filter((host) => typeof host === "string" && host !== ""))];
+/**
+* The status hosts one per-key read tries, in order: an explicit override,
+* the current default, the legacy defaults, then the model hosts.
+* @param hosts - the resolved host settings.
+* @returns unique origins.
+*/
+function statusHostOrder(hosts) {
+	const configured = hosts?.statusHost;
+	const override = configured === void 0 || LEGACY_STATUS_HOSTS.includes(configured) ? [] : [configured];
+	return unique([
+		...override,
+		DEFAULT_STATUS_HOST,
+		...LEGACY_STATUS_HOSTS,
+		hosts?.apiHost,
+		DEFAULT_API_HOST
+	]);
+}
+/**
+* The hosts the account read tries: the model hosts first (they serve the
+* billing endpoints), then the status hosts.
+* @param hosts - the resolved host settings.
+* @returns unique origins.
+*/
+function accountHostOrder(hosts) {
+	return unique([
+		hosts?.apiHost,
+		DEFAULT_API_HOST,
+		...statusHostOrder(hosts)
+	]);
+}
+//#endregion
 //#region src/balance.js
 /**
 * Account and per-key balance.
@@ -78,8 +283,7 @@ const DEFAULT_REASONING_LEVEL = "high";
 *
 * @module dsh-packycode-api/balance
 */
-const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-const clone$1 = (value) => structuredClone(value);
+const record$2 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 function number(value) {
 	if (typeof value === "number" && Number.isFinite(value)) return value;
 	if (typeof value === "string" && value.trim() !== "") {
@@ -107,8 +311,8 @@ function quotaFields(prefix, quota) {
 * @returns a small projection, or undefined when the shape is unrecognized.
 */
 function parseTokenUsage(payload) {
-	const data = record(payload?.data) ? payload.data : payload;
-	if (!record(data)) return void 0;
+	const data = record$2(payload?.data) ? payload.data : payload;
+	if (!record$2(data)) return void 0;
 	if (![
 		"name",
 		"quota_limit",
@@ -132,7 +336,7 @@ function parseTokenUsage(payload) {
 }
 /** Normalize `/v1/dashboard/billing/subscription`. */
 function parseBillingSubscription(payload) {
-	if (!record(payload)) return void 0;
+	if (!record$2(payload)) return void 0;
 	return {
 		...number(payload.soft_limit_usd) === void 0 ? {} : { softLimitUsd: number(payload.soft_limit_usd) },
 		...number(payload.hard_limit_usd) === void 0 ? {} : { hardLimitUsd: number(payload.hard_limit_usd) },
@@ -142,7 +346,7 @@ function parseBillingSubscription(payload) {
 }
 /** Normalize `/v1/dashboard/billing/usage`. */
 function parseBillingUsage(payload) {
-	if (!record(payload)) return void 0;
+	if (!record$2(payload)) return void 0;
 	const total = number(payload.total_usage);
 	return total === void 0 ? {} : { totalUsageUsd: Math.round(total * 1e6) / 1e6 };
 }
@@ -152,68 +356,24 @@ function statusMessage(status) {
 	if (status === 429) return "the gateway is rate limiting balance reads (429)";
 	return `the gateway answered HTTP ${status}`;
 }
-/**
-* Say why a request never got an answer. Node's fetch reports every transport
-* fault as a bare `fetch failed`; the cause carries the part a reader can act
-* on (a DNS failure, a refused or reset connection, a certificate problem).
-*/
-function transportMessage(error, timeoutSignal, timeoutMs) {
-	if (timeoutSignal.aborted) return `no answer within ${Math.round(timeoutMs / 1e3)}s`;
-	const cause = error?.cause;
-	const code = typeof cause?.code === "string" ? cause.code : typeof error?.code === "string" ? error.code : void 0;
-	const message = error instanceof Error ? error.message : String(error);
-	return code === void 0 ? message : `${message} (${code})`;
-}
 async function getJson(url, key, { fetchImpl, timeoutMs, signal }) {
-	const timeoutSignal = AbortSignal.timeout(timeoutMs);
-	const requestSignal = signal === void 0 ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
 	let response;
 	try {
-		response = await fetchImpl(url, {
-			headers: {
-				Authorization: `Bearer ${key}`,
-				Accept: "application/json"
-			},
-			redirect: "error",
-			signal: requestSignal
+		response = await boundedFetch(url, { headers: {
+			Authorization: `Bearer ${key}`,
+			Accept: "application/json"
+		} }, {
+			fetchImpl,
+			timeoutMs,
+			signal
 		});
 	} catch (error) {
-		if (signal?.aborted === true) throw error;
-		throw new Error(transportMessage(error, timeoutSignal, timeoutMs), { cause: error });
+		if (error.aborted) throw error.cause;
+		throw new Error(error.message, { cause: error });
 	}
 	if (!response.ok) throw new Error(statusMessage(response.status));
 	return response.json();
 }
-/**
-* The status hosts one per-key read tries, in order: an explicit override,
-* the current default, the legacy defaults, then the model hosts.
-* @param hosts - the resolved host settings.
-* @returns unique origins.
-*/
-function statusHostOrder(hosts) {
-	const configured = hosts?.statusHost;
-	const override = configured === void 0 || LEGACY_STATUS_HOSTS.includes(configured) ? [] : [configured];
-	return [...new Set([
-		...override,
-		DEFAULT_STATUS_HOST,
-		...LEGACY_STATUS_HOSTS,
-		hosts?.apiHost,
-		DEFAULT_API_HOST
-	].filter((host) => typeof host === "string" && host !== ""))];
-}
-/**
-* The hosts the account read tries: the model hosts first (they serve the
-* billing endpoints), then the status hosts.
-* @param hosts - the resolved host settings.
-* @returns unique origins.
-*/
-function accountHostOrder(hosts) {
-	return [...new Set([
-		hosts?.apiHost,
-		DEFAULT_API_HOST,
-		...statusHostOrder(hosts)
-	].filter((host) => typeof host === "string" && host !== ""))];
-}
 async function withFallback(hosts, path, key, options) {
 	const tried = [];
 	for (const host of hosts) try {
@@ -237,12 +397,9 @@ async function withFallback(hosts, path, key, options) {
 * @param options - key listing, host resolution, and transport knobs.
 * @returns `{ read({force, signal}), invalidate() }`.
 */
-function createBalanceReader({ listKeys, getHosts, fetchImpl = fetch, now = Date.now, ttlMs = DEFAULT_BALANCE_TTL_MS, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+function createBalanceReader({ listKeys, getHosts, fetchImpl = ambientFetch, now = Date.now, ttlMs = DEFAULT_BALANCE_TTL_MS, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
 	if (typeof listKeys !== "function") throw new Error("PackyCode balance reader requires listKeys");
 	if (typeof getHosts !== "function") throw new Error("PackyCode balance reader requires getHosts");
-	let cached;
-	let inFlight;
-	let generation = 0;
 	/** Last successful per-key usage, by key id, and the last account figures. */
 	const lastGood = /* @__PURE__ */ new Map();
 	let lastAccount;
@@ -359,70 +516,225 @@ function createBalanceReader({ listKeys, getHosts, fetchImpl = fetch, now = Date
 			fetchedAt: now()
 		};
 	};
+	const cache = createCachedRead(load, {
+		ttlMs,
+		now
+	});
 	return Object.freeze({
-		async read({ force = false, signal } = {}) {
-			signal?.throwIfAborted();
-			if (!force && cached !== void 0 && now() - cached.fetchedAt < ttlMs) return clone$1(cached);
-			const createPending = (requestSignal) => {
-				const observedGeneration = generation;
-				return load(requestSignal).then((value) => {
-					if (generation === observedGeneration) cached = value;
-					return value;
-				});
-			};
-			if (force) return clone$1(await createPending(signal));
-			const pending = inFlight ?? createPending();
-			if (inFlight === void 0) {
-				inFlight = pending;
-				const clear = () => {
-					if (inFlight === pending) inFlight = void 0;
-				};
-				pending.then(clear, clear);
-			}
-			return clone$1(await pending);
-		},
-		invalidate() {
-			generation += 1;
-			cached = void 0;
-		}
+		read: (options) => cache.read(options),
+		invalidate: () => cache.invalidate()
 	});
 }
 //#endregion
-//#region src/failures.js
+//#region src/catalog.js
 /**
-* Failure classification for the two conditions that move the key ring along.
+* The built-in PackyCode model catalog.
 *
-* The gateway reports an exhausted key and a rejected key in Chinese, and the
-* harness classifies failures by fixed English/status wording it recognizes
-* (`isQuotaExceededError`, `\b401\b`). Normalizing here is what makes the
-* harness's retry policy re-run the step — and therefore what lets the retry
-* pick up the next key. Rewriting is honest about what happened: this plugin
-* knows the key's condition from the gateway's own words plus its balance
-* reader, so the sentence it substitutes says no more than that.
+* The gateway's own guidance for these routes, which the base URLs and pinned
+* protocols below exist to satisfy:
+* - OpenAI/Codex traffic takes `/v1` in the base URL and never an endpoint
+*   path — the SDK appends `/responses` or `/chat/completions` itself.
+* - Anthropic traffic takes `https://cf.api.fan` with **no** `/v1`: the
+*   Anthropic client appends `/v1/messages` itself.
+* - A model asked over the wrong protocol does not fail cleanly; the stream
+*   ends early. So every model pins the protocol its vendor serves here.
 *
-* @module dsh-packycode-api/failures
+* Effort levels come from each vendor's documentation, because an effort the
+* model does not support is refused before the request is sent: Claude Opus
+* 5.5 (platform.claude.com effort docs), GPT-6.1 Sol and GPT-6 Astra
+* `reasoning.effort` (developers.openai.com model pages), DeepSeek thinking
+* mode (`thinking` toggle plus `low|high|max` effort).
+*
+* @module dsh-packycode-api/catalog
 */
-/** Terminal quota, balance, or credit wording, in the gateway's own languages. */
-const QUOTA_WORDING = /额度|余额|配额|欠费|insufficient[\s_-]+(?:quota|balance|credits?)|quota[\s_-]+(?:exceeded|exhausted|reached)|out[\s_-]+of[\s_-]+(?:credits?|budget)/iu;
-/** A rejected key names itself; a bare 403 does not, and must not disable one. */
-const INVALID_KEY_WORDING = /无效的令牌|令牌无效|无效密钥|密钥无效|invalid[\s_-]+api[\s_-]*key|invalid_authentication|api key is invalid/iu;
-const INVALID_KEY_STATUS = /\b401\b/;
+/** pi-ai never reads this gateway's pricing; the harness zeroes cost anyway. */
+const NO_COST = Object.freeze({
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0
+});
+const COMPLETIONS_BASE = `${DEFAULT_API_HOST}/v1`;
+const RESPONSES_BASE = `${DEFAULT_API_HOST}/v1`;
+const MESSAGES_BASE = DEFAULT_API_HOST;
 /**
-* A gateway group that only serves its vendor's official client. These arrive
-* as 403, which the harness reads as an authentication failure and renders as
-* an invalid-API-key problem — the opposite of what happened, and a condition
-* no retry can clear.
+* pi-ai thinking-level maps. A level pinned to `null` is unsupported; an
+* absent key keeps pi-ai's own default for that level, which is how `off`
+* stays available for DeepSeek (`off` sends nothing and the deepseek dialect
+* then emits `thinking: disabled`).
 */
-const CLIENT_POLICY_WORDING = /only accessible via the official|only accepts requests from the official|official\s+claude(?:\s+code)?\s+cli|官方\s*claude(?:\s*code)?\s*cli|请使用标准\s*codex\s*客户端|客户端存在异常|二次分发|API\s*转接/iu;
-/** The key's quota is exhausted; move to the next key. */
-const QUOTA_FAILURE = "quota";
-/** The gateway rejected the key itself; move to the next key. */
-const INVALID_KEY_FAILURE = "invalid-key";
+const DEEPSEEK_LEVELS = Object.freeze({
+	minimal: null,
+	low: "low",
+	medium: null,
+	high: "high",
+	xhigh: null,
+	max: "max"
+});
 /**
-* Whether the gateway is refusing this client rather than this credential.
-* @param message - provider failure text, as pi-ai carries it.
-* @returns true when the route is gated to a vendor's official client.
-*/
+* Claude 5.5 models, GPT-6.1 Sol, and GPT-6 Astra cannot disable reasoning, so `off` is
+* pinned unsupported. The Claude models run through the CLI, which picks its
+* own effort, so for them these levels only shape the picker.
+*/
+const ALWAYS_THINKING_LEVELS = Object.freeze({
+	off: null,
+	minimal: null,
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "max"
+});
+const PACKYCODE_MODELS = Object.freeze([
+	Object.freeze({
+		id: "deepseek-flash",
+		name: "DeepSeek Flash",
+		api: "openai-completions",
+		provider: PROVIDER,
+		baseUrl: COMPLETIONS_BASE,
+		reasoning: true,
+		input: Object.freeze(["text"]),
+		cost: NO_COST,
+		contextWindow: 1e6,
+		maxTokens: 384e3,
+		thinkingLevelMap: DEEPSEEK_LEVELS,
+		compat: Object.freeze({
+			thinkingFormat: "deepseek",
+			maxTokensField: "max_tokens",
+			requiresReasoningContentOnAssistantMessages: true,
+			supportsDeveloperRole: false
+		})
+	}),
+	Object.freeze({
+		id: "gpt-6.1-sol",
+		name: "GPT-6.1 Sol",
+		api: "openai-responses",
+		provider: PROVIDER,
+		baseUrl: RESPONSES_BASE,
+		reasoning: true,
+		input: Object.freeze(["text", "image"]),
+		cost: NO_COST,
+		contextWindow: 105e4,
+		maxTokens: 128e3,
+		thinkingLevelMap: ALWAYS_THINKING_LEVELS
+	}),
+	Object.freeze({
+		id: "gpt-6-astra",
+		name: "GPT-6 Astra",
+		api: "openai-responses",
+		provider: PROVIDER,
+		baseUrl: RESPONSES_BASE,
+		reasoning: true,
+		input: Object.freeze(["text", "image"]),
+		cost: NO_COST,
+		contextWindow: 105e4,
+		maxTokens: 128e3,
+		thinkingLevelMap: ALWAYS_THINKING_LEVELS
+	}),
+	Object.freeze({
+		id: "claude-opus-5-5",
+		name: "Claude Opus 5.5",
+		api: "anthropic-messages",
+		provider: PROVIDER,
+		baseUrl: MESSAGES_BASE,
+		reasoning: true,
+		input: Object.freeze(["text", "image"]),
+		cost: NO_COST,
+		contextWindow: 1e6,
+		maxTokens: 128e3,
+		thinkingLevelMap: ALWAYS_THINKING_LEVELS,
+		compat: Object.freeze({
+			forceAdaptiveThinking: true,
+			supportsTemperature: false
+		})
+	}),
+	Object.freeze({
+		id: "claude-sonnet-5-5",
+		name: "Claude Sonnet 5.5",
+		api: "anthropic-messages",
+		provider: PROVIDER,
+		baseUrl: MESSAGES_BASE,
+		reasoning: true,
+		input: Object.freeze(["text", "image"]),
+		cost: NO_COST,
+		contextWindow: 1e6,
+		maxTokens: 128e3,
+		thinkingLevelMap: ALWAYS_THINKING_LEVELS,
+		compat: Object.freeze({
+			forceAdaptiveThinking: true,
+			supportsTemperature: false
+		})
+	}),
+	Object.freeze({
+		id: "claude-haiku-5-5",
+		name: "Claude Haiku 5.5",
+		api: "anthropic-messages",
+		provider: PROVIDER,
+		baseUrl: MESSAGES_BASE,
+		reasoning: true,
+		input: Object.freeze(["text", "image"]),
+		cost: NO_COST,
+		contextWindow: 1e6,
+		maxTokens: 128e3,
+		thinkingLevelMap: ALWAYS_THINKING_LEVELS,
+		compat: Object.freeze({
+			forceAdaptiveThinking: true,
+			supportsTemperature: false
+		})
+	})
+]);
+/** Every model id this catalog advertises, in picker order. */
+const PACKYCODE_MODEL_IDS = Object.freeze(PACKYCODE_MODELS.map((model) => model.id));
+//#endregion
+//#region src/failures.js
+/**
+* Failure classification for the two conditions that move the key ring along.
+*
+* The gateway reports an exhausted key and a rejected key in Chinese, and the
+* harness classifies failures by fixed English/status wording it recognizes
+* (`isQuotaExceededError`, `\b401\b`). Normalizing here is what makes the
+* harness's retry policy re-run the step — and therefore what lets the retry
+* pick up the next key. Rewriting is honest about what happened: this plugin
+* knows the key's condition from the gateway's own words plus its balance
+* reader, so the sentence it substitutes says no more than that.
+*
+* @module dsh-packycode-api/failures
+*/
+/** Terminal quota, balance, or credit wording, in the gateway's own languages. */
+const QUOTA_WORDING = /额度|余额|配额|欠费|insufficient[\s_-]+(?:quota|balance|credits?)|quota[\s_-]+(?:exceeded|exhausted|reached)|out[\s_-]+of[\s_-]+(?:credits?|budget)/iu;
+/** A rejected key names itself; a bare 403 does not, and must not disable one. */
+const INVALID_KEY_WORDING = /无效的令牌|令牌无效|无效密钥|密钥无效|invalid[\s_-]+api[\s_-]*key|invalid_authentication|api key is invalid/iu;
+const INVALID_KEY_STATUS = /\b401\b/;
+/**
+* A gateway group that only serves its vendor's official client. These arrive
+* as 403, which the harness reads as an authentication failure and renders as
+* an invalid-API-key problem — the opposite of what happened, and a condition
+* no retry can clear.
+*/
+const CLIENT_POLICY_WORDING = /only accessible via the official|only accepts requests from the official|official\s+claude(?:\s+code)?\s+cli|官方\s*claude(?:\s*code)?\s*cli|请使用标准\s*codex\s*客户端|客户端存在异常|二次分发|API\s*转接/iu;
+/**
+* The gateway's answer when a key's groups do not include the model's
+* supplier: `model_not_found` / 当前令牌未覆盖供应商. The key is fine for other
+* models, so it is never moved aside for this.
+*/
+const COVERAGE_WORDING = /model_not_found|未覆盖供应商|无可用渠道|no available channel/iu;
+/**
+* Whether the gateway refused the model for this key's groups.
+* @param message - the failure text.
+* @returns true for a group-coverage refusal.
+*/
+function classifyCoverage(message) {
+	return COVERAGE_WORDING.test(typeof message === "string" ? message : "");
+}
+/** The key's quota is exhausted; move to the next key. */
+const QUOTA_FAILURE = "quota";
+/** The gateway rejected the key itself; move to the next key. */
+const INVALID_KEY_FAILURE = "invalid-key";
+/**
+* Whether the gateway is refusing this client rather than this credential.
+* @param message - provider failure text, as pi-ai carries it.
+* @returns true when the route is gated to a vendor's official client.
+*/
 function classifyClientPolicy(message) {
 	return CLIENT_POLICY_WORDING.test(typeof message === "string" ? message : "");
 }
@@ -507,6 +819,24 @@ function explainCliClientPolicyFailure(message) {
 	return `PackyCode 的上游拒绝了这次 Claude Code CLI 请求，认为它不是官方 Claude Code CLI 发出的。这不是 API Key 失效。请先把插件和 Claude Code CLI 都更新到最新版本再试；仍然失败时，请把下面的原始错误（含 request id）发给 PackyCode 客服，确认所用分组是否支持 Claude Code 的 -p（非交互）模式。 / The gateway refused this Claude Code CLI request as not coming from the official CLI; the API key is fine. Gateway said: ${(typeof message === "string" ? message : "").replace(/^Claude Code CLI failed:\s*/u, "").replace(/\b(?:401|403)\b/gu, "HTTP").slice(0, 600)}`;
 }
 /**
+* Explain a CLI refusal that came from the key, not the CLI: the key's groups
+* cannot reach the requested model. PackyCode answers such a Claude request
+* with the same "only the official Claude Code CLI" wording a real client
+* fault gets, so without the key's groups it read as a CLI problem and sent
+* the user to update the CLI.
+* @param key - the run's key: label, groups, the model, and the groups that
+*   can serve it, as the group reader last saw them.
+* @param message - the CLI failure text.
+* @returns the replacement sentence, with the gateway's own words kept.
+*/
+function explainCliGroupFailure(key, message) {
+	const detail = (typeof message === "string" ? message : "").replace(/^Claude Code CLI failed:\s*/u, "").replace(/\b(?:400|401|403)\b/gu, "HTTP").slice(0, 400);
+	const groups = Array.isArray(key?.groups) && key.groups.length > 0 ? key.groups.join("、") : "未读到";
+	const required = Array.isArray(key?.required) && key.required.length > 0 ? key.required.join(" / ") : "cc / cc-sale / cc-expensive / claude-officially";
+	const model = typeof key?.model === "string" && key.model !== "" ? key.model : "Claude";
+	return `PackyCode 拒绝了这次 ${model} 请求：本轮使用的 Key「${key?.label ?? "?"}」所在分组（${groups}）不包含能用 ${model} 的分组（${required}）。这不是 Claude Code CLI 的问题，不需要更新 CLI。请在 设置 → PackyCode 添加分组包含上述分组的 Key（每个 Key 后面会列出它的分组），插件会自动用它跑 Claude；或在 PackyCode 控制台给这个 Key 加上对应分组。 / The key "${key?.label ?? "?"}" is in no group that serves ${model} (needs one of: ${required}); the CLI is fine. Gateway said: ${detail}`;
+}
+/**
 * Rewrite a failure message so the harness classifies it as quota or auth.
 *
 * A bare status token is neutralized first: an exhausted balance arrives as
@@ -529,100 +859,441 @@ function neutralizeAuthStatus(text) {
 	return text.replace(/\b(?:401|403)\b/gu, "HTTP");
 }
 //#endregion
-//#region src/claude-adapter.js
+//#region src/groups.js
 /**
-* Route Claude models through the local Claude Code CLI.
+* Which PackyCode token groups each stored key belongs to, and which catalog
+* models those groups can serve.
 *
-* PackyCode's `cc` group serves its Claude models only to the official CLI, so
-* selecting one of those models runs that CLI instead of an HTTP request. The
-* other models on the route keep using the pi-ai adapter untouched — this
-* adapter only dispatches.
+* PackyCode routes a request by the token's groups: a key without a Claude
+* Code group (`cc`, `cc-sale`, …) is refused for Claude, a key without a Codex
+* group for GPT. None of that is visible from the key itself, so a key that
+* cannot serve the selected model looked exactly like a client or CLI fault.
 *
-* A CLI-backed turn is a *delegation*: the CLI runs its own agent loop with
-* its own tools and returns one answer. The CLI cannot call the harness's
-* tools, so `options.tools` is deliberately not forwarded, and the harness's
-* system prompt is dropped in favour of the CLI's own. The delegation
-* instructions travel as `--append-system-prompt`; the recent conversation
-* travels as one user message whose images are real image blocks, read from
-* the attachment store, so the CLI's model sees them as images. While it
-* works, its thinking and tool activity stream into a reasoning block and its
-* answer streams as text.
+* Three host-side reads answer it, none of them billed:
+* - the gateway refuses a model id it cannot route before contacting any
+*   upstream, and its refusal names the token's groups
+*   (`已选分组=[codex deepseek-officially kimi-sale]`);
+* - `/v1/models` lists the models the key can reach;
+* - the public `/api/pricing` lists each model's groups and each group's
+*   description.
 *
-* A session-title request is not a delegation: it runs on the small model,
-* read-only and outside the workspace, with the title instructions appended,
-* so naming a session does not cost an Opus agent turn.
+* Every request is bounded by a timeout and refuses redirects. Nothing here
+* returns key material: the projection carries group names, their public
+* descriptions, and per-model booleans.
 *
-* @module dsh-packycode-api/claude-adapter
+* @module dsh-packycode-api/groups
 */
-/** Models this route serves through the CLI rather than an HTTP API. */
-const CLI_BACKED_MODEL_IDS = Object.freeze([
-	"claude-opus-5-5",
-	"claude-sonnet-5-5",
-	"claude-haiku-5-5"
-]);
-/** The model a session title is generated with when the session runs on the CLI. */
-const TITLE_MODEL_ID = "claude-haiku-5-5";
+/** A model id no gateway routes; its refusal is what names the groups. */
+const GROUP_PROBE_MODEL = "dsh-packycode-group-probe";
+/** Group membership changes rarely; a forced read bypasses this. */
+const DEFAULT_GROUP_TTL_MS = 10 * 6e4;
+const SELECTED_GROUPS = /已选分组\s*[=＝:：]\s*\[([^\]]*)\]/u;
+const GROUP_NAME = /^[A-Za-z0-9._-]{1,64}$/u;
+const INVALID_KEY = /无效的令牌|令牌无效|invalid[\s_-]+api[\s_-]*key|invalid_authentication/iu;
+const MAX_GROUPS = 32;
+const MAX_DESCRIPTION = 80;
+/** Keys read at once. */
+const KEY_CONCURRENCY = 4;
+const record$1 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Run `task` over `items`, at most `limit` at a time, keeping their order. */
+async function mapLimited(items, limit, task) {
+	const results = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const index = next;
+			next += 1;
+			results[index] = await task(items[index], index);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return results;
+}
+/** The gateway refused the key itself; it reaches no model at all. */
+var RejectedKeyError = class extends Error {
+	constructor() {
+		super("the gateway rejected this key");
+	}
+};
 /**
-* HTTP models whose session titles run on another model of the same route.
-* A title is a few words, so the flagship `gpt-6-astra` hands it to
-* `gpt-6.1-sol`, which the same Codex group serves; the session's own turns
-* are untouched.
+* Read the token's groups out of the gateway's routing refusal.
+* @param message - the refusal text.
+* @returns the group names, or undefined when the text names none.
 */
-const TITLE_MODEL_ROUTES = Object.freeze({ "gpt-6-astra": "gpt-6.1-sol" });
-/** How much of the conversation a delegated prompt carries. */
-const MAX_PROMPT_CHARS$1 = 48e3;
-const MAX_BLOCK_CHARS = 8e3;
-const TRUNCATED_MARK = "…（较早对话已截断）";
+function parseSelectedGroups(message) {
+	const match = SELECTED_GROUPS.exec(typeof message === "string" ? message : "");
+	if (match === null) return void 0;
+	return [...new Set(match[1].split(/[\s,，、]+/u).filter((name) => GROUP_NAME.test(name)))].slice(0, MAX_GROUPS);
+}
 /**
-* Image bounds for one delegated turn. Each image is re-encoded by the
-* attachment store to the same request version the HTTP route sends (at most
-* 2048×2048 pixels, about 1 MiB); the oldest images are left out once the turn
-* would carry more than 20 of them or 20 MiB of base64.
+* Normalize `/api/pricing`: the groups each catalog model is enabled in, and
+* each group's public description.
+* @param payload - the parsed pricing body.
+* @returns `{ modelGroups, descriptions }`, or undefined when unrecognized.
 */
-const CLI_IMAGE_LIMITS = Object.freeze({
-	maxPixels: 2048 * 2048,
-	maxBytesPerImage: 1024 * 1024,
-	maxTotalBase64Bytes: 20 * 1024 * 1024,
-	maxImages: 20
-});
-/** The vendor's per-image cap on base64 data; a fallback read above it is not sent. */
-const MAX_IMAGE_BASE64_BYTES = 5 * 1024 * 1024;
-const base64Length = (bytes) => Math.ceil(bytes / 3) * 4;
-/** A short name for an image or file a reader can match to the chat. */
-function attachmentName(ref) {
-	if (typeof ref?.name === "string" && ref.name !== "") return ref.name;
-	const id = String(ref?.attachmentId ?? "");
-	return id.startsWith("sha256:") ? id.slice(7, 15) : id.slice(0, 8);
+function parsePricing(payload) {
+	if (!record$1(payload) || !Array.isArray(payload.data)) return void 0;
+	const modelGroups = {};
+	for (const item of payload.data) {
+		if (!record$1(item) || !PACKYCODE_MODEL_IDS.includes(item.model_name) || !Array.isArray(item.enable_groups)) continue;
+		modelGroups[item.model_name] = [...new Set(item.enable_groups.filter((name) => typeof name === "string" && GROUP_NAME.test(name)))].sort();
+	}
+	const descriptions = {};
+	if (record$1(payload.usable_group)) for (const [name, description] of Object.entries(payload.usable_group)) {
+		if (!GROUP_NAME.test(name) || typeof description !== "string") continue;
+		const clean = description.replace(/\s+/gu, " ").trim().slice(0, MAX_DESCRIPTION);
+		if (clean !== "") descriptions[name] = clean;
+	}
+	return {
+		modelGroups,
+		descriptions
+	};
 }
-/** The host path of a stored attachment, when the store is file-backed. */
-function hostPath(lookup) {
+/**
+* Which catalog models a key can reach. Either source decides: a model the
+* key's groups are enabled for, or one its model list shows. A model is only
+* marked unreachable on evidence; with neither source it is left unknown.
+* @param options - the key's groups, its model ids, and pricing's model groups.
+* @returns catalog model id → reachable, for the models with evidence.
+*/
+function catalogCoverage({ groups, models, modelGroups }) {
+	const coverage = {};
+	for (const id of PACKYCODE_MODEL_IDS) {
+		const enabled = modelGroups?.[id];
+		const byGroups = groups === void 0 || enabled === void 0 ? void 0 : enabled.some((name) => groups.includes(name));
+		const byModels = models === void 0 ? void 0 : models.has(id);
+		if (byGroups === true || byModels === true) coverage[id] = true;
+		else if (byGroups === false || byModels === false) coverage[id] = false;
+	}
+	return coverage;
+}
+async function bodyText(response) {
 	try {
-		const value = lookup();
-		return typeof value === "string" && value !== "" ? value : void 0;
+		return await response.text();
 	} catch {
-		return;
+		return "";
 	}
 }
+function errorMessage(text) {
+	try {
+		const parsed = JSON.parse(text);
+		const message = parsed?.error?.message ?? parsed?.message;
+		if (typeof message === "string") return message;
+	} catch {}
+	return text;
+}
 /**
-* Flatten one message's content into ordered parts: text, image, and file.
-* Tool calls and results become short text so a turn that started on another
-* model still reads coherently; reasoning is not carried.
+* Cached, single-flight group reader.
+* @param options - key listing, host resolution, and transport knobs.
+* @returns `{ read, snapshot, covers, requiredGroups, invalidate }`.
 */
-function collectParts(blocks, parts) {
-	for (const block of Array.isArray(blocks) ? blocks : []) {
-		if (block === null || typeof block !== "object") continue;
-		switch (block.type) {
-			case "text":
-				if (typeof block.text === "string" && block.text !== "") parts.push({
-					kind: "text",
-					text: block.text
-				});
-				break;
-			case "image":
-				if (block.attachment !== void 0) parts.push({
-					kind: "image",
-					ref: block.attachment
-				});
+function createGroupReader({ listKeys, getHosts, fetchImpl = ambientFetch, now = Date.now, ttlMs = DEFAULT_GROUP_TTL_MS, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = {}) {
+	if (typeof listKeys !== "function") throw new Error("PackyCode group reader requires listKeys");
+	if (typeof getHosts !== "function") throw new Error("PackyCode group reader requires getHosts");
+	/** Last good reading per key id, kept when a later read of that key fails. */
+	const lastGood = /* @__PURE__ */ new Map();
+	let lastPricing;
+	const request = (url, init, signal) => boundedFetch(url, init, {
+		fetchImpl,
+		timeoutMs,
+		signal
+	});
+	const loadPricing = async (hosts, signal) => {
+		const tried = [];
+		for (const host of statusHostOrder(hosts)) try {
+			const response = await request(`${host}/api/pricing`, { headers: { Accept: "application/json" } }, signal);
+			if (!response.ok) throw new Error(`HTTP ${response.status}`);
+			const pricing = parsePricing(await response.json());
+			if (pricing === void 0) throw new Error("unrecognized pricing payload");
+			return pricing;
+		} catch (error) {
+			signal?.throwIfAborted();
+			tried.push(`${host}: ${error.message}`);
+		}
+		throw new Error(tried.join("; "));
+	};
+	/** The token's groups, from the gateway's refusal of a model it cannot route. */
+	const loadGroups = async (entry, hosts, signal) => {
+		const response = await request(`${hosts.apiHost}/v1/chat/completions`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${entry.key}`,
+				Accept: "application/json",
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({
+				model: GROUP_PROBE_MODEL,
+				max_tokens: 1,
+				messages: [{
+					role: "user",
+					content: "."
+				}]
+			})
+		}, signal);
+		const message = errorMessage(await bodyText(response));
+		if (response.status === 401 || INVALID_KEY.test(message)) throw new RejectedKeyError();
+		return parseSelectedGroups(message);
+	};
+	/** The models the key can reach. */
+	const loadModels = async (entry, hosts, signal) => {
+		const response = await request(`${hosts.apiHost}/v1/models`, { headers: {
+			Authorization: `Bearer ${entry.key}`,
+			Accept: "application/json"
+		} }, signal);
+		if (response.status === 401) throw new RejectedKeyError();
+		if (!response.ok) return void 0;
+		const payload = await response.json();
+		if (!Array.isArray(payload?.data)) return void 0;
+		return new Set(payload.data.map((item) => item?.id).filter((id) => typeof id === "string"));
+	};
+	/**
+	* One key's groups and model list. The two are independent evidence: one
+	* failing in transit does not discard the other, and a rejection from
+	* either means the gateway refuses the key itself.
+	*/
+	const readKey = async (entry, hosts, signal) => {
+		const results = await Promise.allSettled([loadGroups(entry, hosts, signal), loadModels(entry, hosts, signal)]);
+		if (results.some((result) => result.status === "rejected" && result.reason instanceof RejectedKeyError)) return { rejected: true };
+		const [groups, models] = results.map((result) => result.status === "fulfilled" ? result.value : void 0);
+		if (groups === void 0 && models === void 0) throw results.find((result) => result.status === "rejected")?.reason ?? /* @__PURE__ */ new Error("the gateway named no groups for this key");
+		return {
+			groups,
+			models
+		};
+	};
+	/**
+	* Pricing and every key are read concurrently (a few keys at a time), so a
+	* slow or broken key does not hold up the reading for the others.
+	*/
+	const load = async (signal) => {
+		signal?.throwIfAborted();
+		const hosts = getHosts();
+		const keys = await listKeys();
+		for (const id of lastGood.keys()) if (!keys.some((entry) => entry.id === id)) lastGood.delete(id);
+		const pricingTask = loadPricing(hosts, signal).then((pricing) => {
+			lastPricing = pricing;
+			return pricing;
+		}, () => {
+			signal?.throwIfAborted();
+			return lastPricing;
+		});
+		const readings = await mapLimited(keys, KEY_CONCURRENCY, (entry) => readKey(entry, hosts, signal).then((value) => ({ value }), (error) => ({ error })));
+		const pricing = await pricingTask;
+		signal?.throwIfAborted();
+		return {
+			keys: keys.map((entry, index) => {
+				const { value, error } = readings[index];
+				if (value?.rejected === true) {
+					lastGood.delete(entry.id);
+					return {
+						id: entry.id,
+						rejected: true,
+						coverage: Object.fromEntries(PACKYCODE_MODEL_IDS.map((id) => [id, false])),
+						error: new RejectedKeyError().message
+					};
+				}
+				if (value !== void 0) {
+					const reading = {
+						id: entry.id,
+						...value.groups === void 0 ? {} : { groups: value.groups },
+						coverage: catalogCoverage({
+							groups: value.groups,
+							models: value.models,
+							modelGroups: pricing?.modelGroups
+						})
+					};
+					lastGood.set(entry.id, {
+						value: reading,
+						fetchedAt: now()
+					});
+					return reading;
+				}
+				const message = error instanceof Error ? error.message : String(error);
+				const previous = lastGood.get(entry.id);
+				return previous === void 0 ? {
+					id: entry.id,
+					coverage: {},
+					error: message
+				} : {
+					...previous.value,
+					stale: {
+						fetchedAt: previous.fetchedAt,
+						error: message
+					}
+				};
+			}),
+			descriptions: pricing?.descriptions ?? {},
+			requirements: pricing?.modelGroups ?? {},
+			fetchedAt: now()
+		};
+	};
+	const cache = createCachedRead(load, {
+		ttlMs,
+		now
+	});
+	const keyEntry = (keyId) => cache.peek()?.keys.find((candidate) => candidate.id === keyId);
+	return Object.freeze({
+		/**
+		* Read every key's groups; cached for the TTL unless forced.
+		* @returns the projection the settings panel shows.
+		*/
+		read: (options) => cache.read(options),
+		/** The last reading, however old, without touching the network. */
+		snapshot: () => cache.snapshot(),
+		/** Whether any reading exists yet. */
+		hasReading: () => cache.peek() !== void 0,
+		/**
+		* Whether a key's groups reach a model, from the last reading.
+		* @returns true, false, or undefined when there is no evidence.
+		*/
+		covers(keyId, modelId) {
+			const value = keyEntry(keyId)?.coverage?.[modelId];
+			return typeof value === "boolean" ? value : void 0;
+		},
+		/** The groups pricing lists for a model, from the last reading. */
+		requiredGroups(modelId) {
+			const groups = cache.peek()?.requirements?.[modelId];
+			return Array.isArray(groups) ? [...groups] : void 0;
+		},
+		/** The groups the last reading found for a key. */
+		groupsOf(keyId) {
+			const groups = keyEntry(keyId)?.groups;
+			return Array.isArray(groups) ? [...groups] : void 0;
+		},
+		/** Drop the reading so the next read goes to the network. */
+		invalidate: () => cache.invalidate()
+	});
+}
+/**
+* Pick the key a request for `modelId` runs with.
+*
+* The active key serves every model it is not known to be excluded from.
+* When the last reading shows its groups cannot reach the model, the next
+* usable key in ring order that can — or, failing that, one with no evidence
+* either way — serves this request instead. The active pointer itself does
+* not move; with no better key the active one is returned, marked uncovered.
+* @param modelId - the catalog model of this request.
+* @param active - the ring's active key.
+* @param usable - the ring's usable keys, in ring order.
+* @param covers - `(keyId, modelId) => true | false | undefined`.
+* @returns the chosen key, with `switchedFrom` or `uncovered` when it is not
+*   simply the active key.
+*/
+function pickKeyForModel(modelId, active, usable, covers) {
+	if (active === void 0) return void 0;
+	if (typeof modelId !== "string" || covers(active.id, modelId) !== false) return { ...active };
+	const start = usable.findIndex((entry) => entry.id === active.id);
+	const others = start < 0 ? usable.filter((entry) => entry.id !== active.id) : [...usable.slice(start + 1), ...usable.slice(0, start)];
+	const pick = others.find((entry) => covers(entry.id, modelId) === true) ?? others.find((entry) => covers(entry.id, modelId) === void 0);
+	if (pick === void 0) return {
+		...active,
+		uncovered: true
+	};
+	return {
+		id: pick.id,
+		label: pick.label,
+		key: pick.key,
+		switchedFrom: {
+			id: active.id,
+			label: active.label
+		}
+	};
+}
+//#endregion
+//#region src/claude-adapter.js
+/**
+* Route Claude models through the local Claude Code CLI.
+*
+* PackyCode's `cc` group serves its Claude models only to the official CLI, so
+* selecting one of those models runs that CLI instead of an HTTP request. The
+* other models on the route keep using the pi-ai adapter untouched — this
+* adapter only dispatches.
+*
+* A CLI-backed turn is a *delegation*: the CLI runs its own agent loop with
+* its own tools and returns one answer. The CLI cannot call the harness's
+* tools, so `options.tools` is deliberately not forwarded, and the harness's
+* system prompt is dropped in favour of the CLI's own. The delegation
+* instructions travel as `--append-system-prompt`; the recent conversation
+* travels as one user message whose images are real image blocks, read from
+* the attachment store, so the CLI's model sees them as images. While it
+* works, its thinking and tool activity stream into a reasoning block and its
+* answer streams as text.
+*
+* A session-title request is not a delegation: it runs on the small model,
+* read-only and outside the workspace, with the title instructions appended,
+* so naming a session does not cost an Opus agent turn.
+*
+* @module dsh-packycode-api/claude-adapter
+*/
+/** Models this route serves through the CLI rather than an HTTP API. */
+const CLI_BACKED_MODEL_IDS = Object.freeze([
+	"claude-opus-5-5",
+	"claude-sonnet-5-5",
+	"claude-haiku-5-5"
+]);
+/** The model a session title is generated with when the session runs on the CLI. */
+const TITLE_MODEL_ID = "claude-haiku-5-5";
+/**
+* HTTP models whose session titles run on another model of the same route.
+* A title is a few words, so the flagship `gpt-6-astra` hands it to
+* `gpt-6.1-sol`, which the same Codex group serves; the session's own turns
+* are untouched.
+*/
+const TITLE_MODEL_ROUTES = Object.freeze({ "gpt-6-astra": "gpt-6.1-sol" });
+/** How much of the conversation a delegated prompt carries. */
+const MAX_PROMPT_CHARS$1 = 48e3;
+const MAX_BLOCK_CHARS = 8e3;
+const TRUNCATED_MARK = "…（较早对话已截断）";
+/**
+* Image bounds for one delegated turn. Each image is re-encoded by the
+* attachment store to the same request version the HTTP route sends (at most
+* 2048×2048 pixels, about 1 MiB); the oldest images are left out once the turn
+* would carry more than 20 of them or 20 MiB of base64.
+*/
+const CLI_IMAGE_LIMITS = Object.freeze({
+	maxPixels: 2048 * 2048,
+	maxBytesPerImage: 1024 * 1024,
+	maxTotalBase64Bytes: 20 * 1024 * 1024,
+	maxImages: 20
+});
+/** The vendor's per-image cap on base64 data; a fallback read above it is not sent. */
+const MAX_IMAGE_BASE64_BYTES = 5 * 1024 * 1024;
+const base64Length = (bytes) => Math.ceil(bytes / 3) * 4;
+/** A short name for an image or file a reader can match to the chat. */
+function attachmentName(ref) {
+	if (typeof ref?.name === "string" && ref.name !== "") return ref.name;
+	const id = String(ref?.attachmentId ?? "");
+	return id.startsWith("sha256:") ? id.slice(7, 15) : id.slice(0, 8);
+}
+/** The host path of a stored attachment, when the store is file-backed. */
+function hostPath(lookup) {
+	try {
+		const value = lookup();
+		return typeof value === "string" && value !== "" ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Flatten one message's content into ordered parts: text, image, and file.
+* Tool calls and results become short text so a turn that started on another
+* model still reads coherently; reasoning is not carried.
+*/
+function collectParts(blocks, parts) {
+	for (const block of Array.isArray(blocks) ? blocks : []) {
+		if (block === null || typeof block !== "object") continue;
+		switch (block.type) {
+			case "text":
+				if (typeof block.text === "string" && block.text !== "") parts.push({
+					kind: "text",
+					text: block.text
+				});
+				break;
+			case "image":
+				if (block.attachment !== void 0) parts.push({
+					kind: "image",
+					ref: block.attachment
+				});
 				else parts.push({
 					kind: "text",
 					text: "[图片]"
@@ -996,6 +1667,23 @@ function turnUsage(lastRequest, finished) {
 		cacheWriteTokens: finished?.cacheWriteTokens ?? 0
 	};
 }
+/**
+* One line naming the key a CLI run uses — by its label only — so a key
+* switch is visible on the very next turn, and a key passed over for its
+* groups is never a silent change.
+* @param key - the runner's `key` event.
+* @returns the reasoning note, newline-terminated.
+*/
+function keyNote(key) {
+	const model = typeof key.model === "string" && key.model !== "" ? key.model : "Claude";
+	const groups = Array.isArray(key.groups) && key.groups.length > 0 ? `（分组：${key.groups.join("、")}）` : "";
+	if (key.switchedFrom !== void 0) return `▸ 当前 Key「${key.switchedFrom}」的分组不能用 ${model}，本轮改用 Key「${key.label}」${groups}\n`;
+	if (key.uncovered === true) {
+		const required = Array.isArray(key.required) && key.required.length > 0 ? `（需要 ${key.required.join(" / ")}）` : "";
+		return `▸ 使用 Key「${key.label}」${groups}——注意：已存的 Key 都没有能用 ${model} 的分组${required}\n`;
+	}
+	return `▸ 使用 Key「${key.label}」${groups}\n`;
+}
 /** One line describing a retry the CLI is making on its own. */
 function retryNote(event) {
 	return `网关返回 ${event.status === void 0 ? "出错" : `HTTP ${event.status}`}${typeof event.error === "string" && event.error !== "" ? `（${event.error}）` : ""}，CLI 自动重试${event.attempt === void 0 ? "" : event.maxRetries === void 0 ? ` ${event.attempt}` : ` ${event.attempt}/${event.maxRetries}`}${event.delayMs === void 0 ? "" : `，${(event.delayMs / 1e3).toFixed(1)} 秒后`}`;
@@ -1033,11 +1721,12 @@ async function cliCall(options, { titleModel, cwdOf, modeOf, attachmentsOf, imag
 *
 * @param options - the inner adapter, the CLI runner, the CLI-backed model ids,
 *   the model session titles run on, the HTTP models whose titles run on
-*   another model, the mode and working directory each turn runs with, and the
-*   attachment store images are read from.
+*   another model, the mode and working directory each turn runs with, the
+*   attachment store images are read from, and an optional refresh of a run's
+*   key description (its groups) for explaining a refusal.
 * @returns an adapter with the same provider surface.
 */
-function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS, titleModel = TITLE_MODEL_ID, titleRoutes = TITLE_MODEL_ROUTES, resolveMode, resolveCwd, resolveAttachments, imageLimits = CLI_IMAGE_LIMITS }) {
+function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS, titleModel = TITLE_MODEL_ID, titleRoutes = TITLE_MODEL_ROUTES, resolveMode, resolveCwd, resolveAttachments, imageLimits = CLI_IMAGE_LIMITS, explainKey }) {
 	if (inner === void 0 || inner === null) throw new Error("the CLI adapter needs an inner adapter");
 	if (runner === void 0 || runner === null) throw new Error("the CLI adapter needs a runner");
 	const cliModels = new Set(modelIds);
@@ -1060,6 +1749,34 @@ function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS
 			return;
 		}
 	};
+	/**
+	* Say why a CLI run failed. The request came from the official CLI, so a
+	* client-policy refusal gets its own explanation rather than the HTTP
+	* route's advice. PackyCode refuses a key without a Claude group either as
+	* a routing miss (400 未覆盖供应商, which names the key's groups) or with the
+	* official-CLI wording (403); either way the key is the cause, not the CLI.
+	* When the run started before the key's groups were known, a fresh reading
+	* is consulted first. A busy gateway is named as such after the CLI's own
+	* retries ran out.
+	*/
+	async function explainFailure(raw, runKey, { model, retries }) {
+		const policy = classifyClientPolicy(raw);
+		const coverage = classifyCoverage(raw);
+		if (!policy && !coverage) return classifyCapacity(raw) ? explainCliCapacityFailure(raw, retries) : raw;
+		let key = runKey === void 0 ? void 0 : {
+			model,
+			...runKey
+		};
+		if (key !== void 0 && key.covers !== true && typeof explainKey === "function") key = await explainKey(key).catch(() => key) ?? key;
+		if (coverage) return explainCliGroupFailure({
+			model,
+			...key,
+			groups: parseSelectedGroups(raw) ?? key?.groups
+		}, raw);
+		if (key?.covers === false) return explainCliGroupFailure(key, raw);
+		const used = key === void 0 ? "" : `（本轮使用 Key「${key.label}」${Array.isArray(key.groups) ? `，分组：${key.groups.join("、")}` : ""}）`;
+		return `${explainCliClientPolicyFailure(raw)}${used}`;
+	}
 	async function* cliStream(options) {
 		const quiet = options?.purpose === "session-title";
 		const blocks = createBlockWriter();
@@ -1095,6 +1812,8 @@ function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS
 			return true;
 		};
 		let retries = 0;
+		/** The key this run uses, as the runner described it (never the token). */
+		let runKey;
 		try {
 			let finished;
 			let lastRequest;
@@ -1102,6 +1821,10 @@ function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS
 				...call,
 				signal: options.signal
 			})) switch (event.type) {
+				case "key":
+					runKey = event;
+					if (!quiet) yield* blocks.note(keyNote(event));
+					break;
 				case "started":
 					if (!quiet) {
 						const detail = [event.version, event.model].filter((part) => typeof part === "string" && part !== "").join(" · ");
@@ -1146,14 +1869,16 @@ function createClaudeCliAdapter({ inner, runner, modelIds = CLI_BACKED_MODEL_IDS
 			};
 		} catch (error) {
 			yield* blocks.close();
-			const raw = String(error?.message ?? error);
 			yield {
 				type: "finish",
 				reason: {
 					kind: "error",
 					failure: {
 						code: "PI_AI_ERROR",
-						message: classifyClientPolicy(raw) ? explainCliClientPolicyFailure(raw) : classifyCapacity(raw) ? explainCliCapacityFailure(raw, retries) : raw
+						message: await explainFailure(String(error?.message ?? error), runKey, {
+							model: options.model,
+							retries
+						})
 					}
 				}
 			};
@@ -1721,6 +2446,31 @@ function readClaudeStreamEvents(event) {
 	}];
 	return [];
 }
+const nameList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string" && item !== "").slice(0, 32) : void 0;
+/**
+* What a run may say about the key it used: its ring id and label, why it was
+* chosen, and the groups involved. Never the token.
+* @param credential - what `resolveCredential` answered.
+* @returns the description, or undefined when the credential carries no label.
+*/
+function describeRunKey(credential) {
+	if (credential === null || typeof credential !== "object") return void 0;
+	const label = typeof credential.label === "string" && credential.label !== "" ? credential.label.slice(0, 60) : void 0;
+	if (label === void 0) return void 0;
+	const groups = nameList(credential.groups);
+	const required = nameList(credential.required);
+	const from = typeof credential.switchedFrom?.label === "string" && credential.switchedFrom.label !== "" ? credential.switchedFrom.label.slice(0, 60) : void 0;
+	return {
+		...typeof credential.id === "string" && credential.id !== "" ? { id: credential.id } : {},
+		label,
+		...typeof credential.model === "string" && credential.model !== "" ? { model: credential.model } : {},
+		...groups === void 0 ? {} : { groups },
+		...required === void 0 ? {} : { required },
+		...typeof credential.covers === "boolean" ? { covers: credential.covers } : {},
+		...from === void 0 ? {} : { switchedFrom: from },
+		...credential.uncovered === true ? { uncovered: true } : {}
+	};
+}
 /**
 * A Claude Code CLI runner.
 * @param options - binary (a path, or a function resolving one per run so a
@@ -1748,7 +2498,8 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 			content,
 			stream
 		});
-		const { baseUrl, token } = await resolveCredential();
+		const credential = await resolveCredential({ model });
+		const { baseUrl, token } = credential;
 		const program = typeof binary === "function" ? await binary() : binary;
 		const command = resolveSpawnCommand(program, { platform });
 		const env = withProgramDirOnPath(buildClaudeEnvironment({
@@ -1852,7 +2603,8 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 			child,
 			state,
 			closed,
-			kill
+			kill,
+			key: describeRunKey(credential)
 		};
 	};
 	return Object.freeze({
@@ -1901,7 +2653,7 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 			let buffer = "";
 			let sawResult;
 			const lines = [];
-			const { state, closed, kill } = await start({
+			const { state, closed, kill, key } = await start({
 				prompt,
 				content,
 				mode,
@@ -1920,6 +2672,10 @@ function createClaudeRunner({ binary = findClaudeBinary(), configDir = DEFAULT_C
 					}
 				}
 			});
+			if (key !== void 0) yield {
+				type: "key",
+				...key
+			};
 			const drain = function* () {
 				while (lines.length > 0) {
 					const line = lines.shift().trim();
@@ -2355,72 +3111,355 @@ function createClaudeCliManager({ explicitPath = () => "", platform = process.pl
 	});
 }
 //#endregion
-//#region src/key-ring.js
+//#region src/permission.js
 /**
-* The PackyCode key ring.
+* The Claude Code CLI mode a session's own permissions allow.
 *
-* Keys live in one DSH credential *record* (`packycode-api/keys`), which is
-* the cross-process-serialized read-decide-replace space the credential
-* service owns. A key the gateway exhausts or rejects is marked unusable and
-* the ring moves the active pointer to the next usable key, so the next
-* attempt — the harness retry of the failed step — resolves a different key
-* through the adapter's per-request `resolveApiKey`.
+* A CLI-backed turn runs the CLI's own tool loop, outside the harness sandbox
+* and approval flow. Deriving its mode from the session's permission preset
+* means the user grants it once, in the place they already grant the harness
+* itself, instead of in a separate plugin setting.
 *
-* @module dsh-packycode-api/key-ring
+* @module dsh-packycode-api/permission
 */
-/** Printable ASCII without spaces: what an HTTP header can carry unchanged. */
-const LEGAL_KEY = /^[\x21-\x7E]+$/u;
-const RECORD_VERSION = 1;
-const MAX_KEYS = 32;
-const RECORD_KEY = typeof credentialKey === "function" ? credentialKey(PLUGIN_ID, KEY_RECORD_ID) : void 0;
-const text = (value) => typeof value === "string" ? value : "";
-/** Validate a pasted key before it is stored; the gateway never sees a bad one from us. */
-function assertApiKey(value) {
-	const key = text(value).trim();
-	if (key.length < 8 || key.length > 512 || !LEGAL_KEY.test(key)) throw new Error("PackyCode API key must be 8-512 printable ASCII characters without spaces");
-	return key;
-}
-function entry(value) {
-	if (value === null || typeof value !== "object") return void 0;
-	const key = text(value.key);
-	if (key === "" || !LEGAL_KEY.test(key)) return void 0;
-	const id = text(value.id);
-	return {
-		id: id === "" ? randomUUID().slice(0, 8) : id,
-		label: text(value.label),
-		key,
-		addedAt: Number.isFinite(value.addedAt) ? value.addedAt : 0,
-		...Number.isFinite(value.disabledAt) ? { disabledAt: value.disabledAt } : {},
-		...text(value.disabledReason) === "" ? {} : { disabledReason: text(value.disabledReason) }
-	};
-}
-/** Tolerate a hand-edited or older record instead of failing the whole route. */
-function normalizeState(record) {
-	const payload = record !== null && typeof record === "object" && record.kind === "grant" && record.payload !== null && typeof record.payload === "object" ? record.payload : void 0;
-	const keys = (Array.isArray(payload?.keys) ? payload.keys : []).map(entry).filter((candidate) => candidate !== void 0);
-	const activeId = text(payload?.activeId);
-	return {
-		activeId: keys.some((candidate) => candidate.id === activeId) ? activeId : keys[0]?.id,
-		keys
-	};
-}
+/** Configured value meaning "follow the session's permission preset". */
+const AUTO_CLAUDE_MODE = "auto";
+const RANK = Object.freeze({
+	"read-only": 0,
+	edit: 1,
+	full: 2
+});
 /**
-* The next free `Key N` name. The ring shrinks on removal, so numbering follows
-* the highest name in use instead of the current key count — otherwise removing
-* the first key and adding another produces a second "Key 2".
-* @param keys - the stored keys.
-* @returns an unused default label.
+* Map the harness's two permission knobs onto a CLI mode.
+*
+* The CLI cannot ask the harness user for approval, so it skips its own
+* permission checks only when the session itself neither sandboxes nor asks.
+* @param sandbox - the session's resolved sandbox mode.
+* @param approval - the session's effective approval policy.
+* @returns a CLI mode, or `undefined` for an unknown sandbox mode.
 */
-function nextDefaultLabel(keys) {
-	const used = new Set(keys.map((candidate) => candidate.label));
-	let index = keys.length + 1;
-	while (used.has(`Key ${index}`)) index += 1;
-	return `Key ${index}`;
+function claudeModeFor(sandbox, approval) {
+	switch (sandbox) {
+		case "read-only": return "read-only";
+		case "workspace-write": return "edit";
+		case "danger-full-access": return approval === "never" ? "full" : "edit";
+		default: return;
+	}
 }
-/** The public shape: what a browser or a log may see, never key material. */
-function projection(state) {
-	return {
-		activeId: state.activeId,
+/**
+* Read a session's CLI mode from the host's permission services.
+* @param ctx - the plugin context; services are read without an inject requirement.
+* @param session - the session whose permission state is read.
+* @returns a CLI mode, or `undefined` when the session or the services are absent.
+*/
+function claudeModeForSession(ctx, session) {
+	if (session === void 0 || session === null) return void 0;
+	try {
+		const sandbox = ctx.get?.("sandboxPolicy")?.resolve?.({ session })?.mode;
+		const approval = ctx.get?.("approval")?.effectivePolicy?.(session);
+		return claudeModeFor(sandbox, approval);
+	} catch {
+		return;
+	}
+}
+/**
+* The narrower of two modes; an unknown ceiling leaves the request as it is.
+* @param requested - the mode a caller asked for.
+* @param ceiling - the most the session allows.
+* @returns the mode the CLI runs with.
+*/
+function capClaudeMode(requested, ceiling) {
+	if (ceiling === void 0 || RANK[ceiling] === void 0) return requested;
+	if (requested === void 0 || RANK[requested] === void 0) return ceiling;
+	return RANK[requested] > RANK[ceiling] ? ceiling : requested;
+}
+//#endregion
+//#region src/claude-tool.js
+/**
+* The explicit `claude_code` delegation tool, for asking Claude Code for
+* something while another model drives the session. It shares the runner the
+* CLI-backed models use.
+*
+* @module dsh-packycode-api/claude-tool
+*/
+/** What a `claude_code` tool run is told about where its task came from. */
+const CLAUDE_TOOL_INSTRUCTIONS = "This task was delegated to Claude Code by another agent in DeepSeek Harness through its claude_code tool. The task text is self-contained; complete it with your own tools and reply with the final result only.";
+/**
+* @param options - the CLI runner, and the most a run may do for a session.
+* @returns the tool definition to register.
+*/
+function createClaudeCodeTool({ runner, modeCeiling }) {
+	return defineTool({
+		name: "claude_code",
+		description: "Delegate a task to the local Claude Code CLI (the official `claude` binary), which runs it with its own tools and returns its final answer. Use it when the user asks for Claude or when a task suits Claude Code. The child runs with this plugin's PackyCode endpoint and API key, in an isolated config home. `mode` bounds what it may do on its own: \"read-only\" (Read/Grep/Glob), \"edit\" (also Edit/Write), \"full\" (bypasses the CLI's permission checks, including shell commands); it defaults to, and is capped at, what this session's permission preset allows. It starts a fresh CLI session per call, takes tens of seconds, and bills through the same PackyCode key. Its internal tool calls are not part of this session's transcript — only the returned answer is.",
+		parameters: {
+			prompt: {
+				type: "string",
+				required: true,
+				description: "The task for Claude Code, written as a self-contained instruction (it does not see this conversation)."
+			},
+			mode: {
+				type: "string",
+				enum: Object.keys(CLAUDE_CLI_MODES),
+				description: "What the CLI may do on its own. Defaults to the most this session's permission preset allows; a wider mode is capped to it. Ask for \"full\" only when the task genuinely needs shell commands."
+			},
+			model: {
+				type: "string",
+				description: "Model id passed to the CLI (for example \"claude-opus-5-5\", \"claude-sonnet-5-5\", or \"claude-haiku-5-5\"). Omit to use the CLI's own default."
+			},
+			cwd: {
+				type: "string",
+				description: "Working directory for the CLI. Defaults to this session's workspace; a relative path resolves against it."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					result: {
+						type: "string",
+						required: true
+					},
+					model: {
+						type: "string",
+						required: true
+					},
+					mode: {
+						type: "string",
+						required: true
+					},
+					costUsd: {
+						type: "number",
+						required: true
+					},
+					durationMs: {
+						type: "number",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `${value.result}\n\n— Claude Code CLI · ${value.model || "default model"} · ${value.mode} · ${Math.round(value.durationMs / 1e3)}s · $${value.costUsd.toFixed(4)}`
+			}]
+		},
+		async execute(args, exec) {
+			const sessionCwd = exec?.agent?.session?.header?.cwd;
+			const requested = typeof args.cwd === "string" ? args.cwd.trim() : "";
+			const cwd = requested === "" ? sessionCwd : isAbsolute(requested) ? requested : sessionCwd === void 0 ? requested : join(sessionCwd, requested);
+			return await runner.run({
+				prompt: args.prompt,
+				mode: capClaudeMode(args.mode, modeCeiling(exec?.agent?.session)) ?? "edit",
+				model: args.model,
+				appendSystemPrompt: CLAUDE_TOOL_INSTRUCTIONS,
+				cwd,
+				signal: exec?.signal
+			});
+		}
+	});
+}
+//#endregion
+//#region src/key-chooser.js
+/**
+* Which stored key a request runs with, and what happens when the gateway
+* rejects one.
+*
+* The ring's active key serves every request it can. A request for a model
+* the active key's groups cannot reach — as the last group reading shows —
+* runs on the next stored key that can; the active pointer itself does not
+* move. A key the gateway reports as exhausted or invalid is marked unusable
+* and the ring moves on, so the retry of the failed step resolves the next
+* key. Only keys stored in this plugin's ring are ever chosen.
+*
+* @module dsh-packycode-api/key-chooser
+*/
+/** How long a request with a choice of keys waits for the first group reading. */
+const DEFAULT_GROUP_WAIT_MS = 6e3;
+/**
+* @param options - the key ring, the group reader, what to do after a key
+*   moved aside, a logger, and how long to wait for the first group reading.
+* @returns the chooser.
+*/
+function createKeyChooser({ ring, groups, onRotated, logger, waitMs = DEFAULT_GROUP_WAIT_MS }) {
+	/**
+	* Key material to ring id. A failure is reported from inside a stream, which
+	* carries the request's key but not its id; this index is refreshed on every
+	* resolution so the right key is the one that moves aside.
+	*/
+	const idByKey = /* @__PURE__ */ new Map();
+	/** The ring as of the last resolution, for the synchronous per-request choice. */
+	let snapshot = [];
+	const remember = async () => {
+		const entries = await ring.secrets();
+		snapshot = entries;
+		for (const entry of entries) idByKey.set(entry.key, entry.id);
+	};
+	const usable = () => snapshot.filter((entry) => entry.disabled !== true);
+	const covers = (keyId, modelId) => groups.covers(keyId, modelId);
+	/**
+	* Keep the group reading fresh for the choice. It only matters with two
+	* usable keys or more; the first reading is awaited for at most `waitMs`,
+	* later ones refresh in the background.
+	*/
+	const warm = async () => {
+		if (usable().length < 2) return;
+		const pending = groups.read().catch(() => void 0);
+		if (groups.hasReading()) return;
+		let timer;
+		await Promise.race([pending, new Promise((resolve) => {
+			timer = setTimeout(resolve, waitMs);
+		})]);
+		clearTimeout(timer);
+	};
+	/** The active key, after refreshing the ring and, when it matters, the groups. */
+	const active = async () => {
+		await remember();
+		const key = await ring.activeKey();
+		if (key !== void 0) await warm();
+		return key;
+	};
+	return Object.freeze({
+		remember,
+		covers,
+		active,
+		/**
+		* The key one HTTP request for `modelId` runs with, given the active key
+		* pi-ai resolved. Synchronous because pi-ai opens its stream synchronously;
+		* it reads the ring and groups as of the last {@link active}.
+		* @returns the key material to send.
+		*/
+		forRequest(modelId, apiKey) {
+			const current = snapshot.find((entry) => entry.key === apiKey);
+			if (current === void 0) return apiKey;
+			const chosen = pickKeyForModel(modelId, current, usable(), covers);
+			if (chosen?.switchedFrom !== void 0) logger?.info?.("packycode-api: key %s cannot reach %s by its last group reading; this request uses key %s", current.id, modelId, chosen.id);
+			return chosen?.key ?? apiKey;
+		},
+		/**
+		* The key one CLI run for `modelId` uses, with what the run may say about
+		* it: its label, its groups, the groups the model needs, and why it was
+		* chosen.
+		* @returns the choice, or undefined when no usable key is stored.
+		*/
+		async forRun(modelId) {
+			const current = await active();
+			if (current === void 0) return void 0;
+			const chosen = pickKeyForModel(modelId, current, usable(), covers);
+			return {
+				...chosen,
+				model: modelId,
+				groups: groups.groupsOf(chosen.id),
+				required: groups.requiredGroups(modelId),
+				covers: covers(chosen.id, modelId)
+			};
+		},
+		/**
+		* Refresh what a run said about its key from the group reading, waiting
+		* at most `waitMs` for a reading in flight.
+		* @param runKey - the run's key description (`id`, `model`, …).
+		* @returns the description with the reading's groups and coverage.
+		*/
+		async describe(runKey) {
+			let timer;
+			await Promise.race([groups.read().catch(() => void 0), new Promise((resolve) => {
+				timer = setTimeout(resolve, waitMs);
+			})]);
+			clearTimeout(timer);
+			if (typeof runKey?.id !== "string") return runKey;
+			return {
+				...runKey,
+				groups: groups.groupsOf(runKey.id) ?? runKey.groups,
+				required: groups.requiredGroups(runKey.model) ?? runKey.required,
+				covers: covers(runKey.id, runKey.model) ?? runKey.covers
+			};
+		},
+		/**
+		* The gateway exhausted or rejected a key: mark it unusable so the ring
+		* moves on, then let the caller drop what depended on it.
+		* @param kind - `quota` or `invalid-key`.
+		* @param _message - the failure text (unused; the kind decides).
+		* @param key - the key material the failed request carried.
+		* @param knownId - the key's ring id, when the caller has it.
+		*/
+		onKeyFailure(kind, _message, key, knownId) {
+			const id = knownId ?? (key === void 0 ? void 0 : idByKey.get(key));
+			if (id === void 0) {
+				logger?.warn?.("packycode-api: %s reported for an unidentified key; not rotating", kind);
+				return;
+			}
+			logger?.warn?.("packycode-api: %s on key %s; the next key serves the retry", kind, id);
+			ring.disable(id, kind).then(() => onRotated?.()).catch((error) => logger?.warn?.("packycode-api: could not move past key %s: %s", id, error.message));
+		}
+	});
+}
+//#endregion
+//#region src/key-ring.js
+/**
+* The PackyCode key ring.
+*
+* Keys live in one DSH credential *record* (`packycode-api/keys`), which is
+* the cross-process-serialized read-decide-replace space the credential
+* service owns. A key the gateway exhausts or rejects is marked unusable and
+* the ring moves the active pointer to the next usable key, so the next
+* attempt — the harness retry of the failed step — resolves a different key
+* through the adapter's per-request `resolveApiKey`.
+*
+* @module dsh-packycode-api/key-ring
+*/
+/** Printable ASCII without spaces: what an HTTP header can carry unchanged. */
+const LEGAL_KEY = /^[\x21-\x7E]+$/u;
+const RECORD_VERSION = 1;
+const MAX_KEYS = 32;
+const RECORD_KEY = typeof credentialKey === "function" ? credentialKey(PLUGIN_ID, KEY_RECORD_ID) : void 0;
+const text$1 = (value) => typeof value === "string" ? value : "";
+/** Validate a pasted key before it is stored; the gateway never sees a bad one from us. */
+function assertApiKey(value) {
+	const key = text$1(value).trim();
+	if (key.length < 8 || key.length > 512 || !LEGAL_KEY.test(key)) throw new Error("PackyCode API key must be 8-512 printable ASCII characters without spaces");
+	return key;
+}
+function entry(value) {
+	if (value === null || typeof value !== "object") return void 0;
+	const key = text$1(value.key);
+	if (key === "" || !LEGAL_KEY.test(key)) return void 0;
+	const id = text$1(value.id);
+	return {
+		id: id === "" ? randomUUID().slice(0, 8) : id,
+		label: text$1(value.label),
+		key,
+		addedAt: Number.isFinite(value.addedAt) ? value.addedAt : 0,
+		...Number.isFinite(value.disabledAt) ? { disabledAt: value.disabledAt } : {},
+		...text$1(value.disabledReason) === "" ? {} : { disabledReason: text$1(value.disabledReason) }
+	};
+}
+/** Tolerate a hand-edited or older record instead of failing the whole route. */
+function normalizeState(record) {
+	const payload = record !== null && typeof record === "object" && record.kind === "grant" && record.payload !== null && typeof record.payload === "object" ? record.payload : void 0;
+	const keys = (Array.isArray(payload?.keys) ? payload.keys : []).map(entry).filter((candidate) => candidate !== void 0);
+	const activeId = text$1(payload?.activeId);
+	return {
+		activeId: keys.some((candidate) => candidate.id === activeId) ? activeId : keys[0]?.id,
+		keys
+	};
+}
+/**
+* The next free `Key N` name. The ring shrinks on removal, so numbering follows
+* the highest name in use instead of the current key count — otherwise removing
+* the first key and adding another produces a second "Key 2".
+* @param keys - the stored keys.
+* @returns an unused default label.
+*/
+function nextDefaultLabel(keys) {
+	const used = new Set(keys.map((candidate) => candidate.label));
+	let index = keys.length + 1;
+	while (used.has(`Key ${index}`)) index += 1;
+	return `Key ${index}`;
+}
+/** The public shape: what a browser or a log may see, never key material. */
+function projection(state) {
+	return {
+		activeId: state.activeId,
 		keys: state.keys.map((candidate) => ({
 			id: candidate.id,
 			label: candidate.label,
@@ -2501,7 +3540,7 @@ var PackyCodeKeyRing = class {
 	}
 	async add(key, label) {
 		const value = assertApiKey(key);
-		const name = text(label).trim().slice(0, 60);
+		const name = text$1(label).trim().slice(0, 60);
 		return projection(await this.#write((state) => {
 			if (state.keys.length >= MAX_KEYS) throw new Error(`PackyCode accepts at most ${MAX_KEYS} keys`);
 			if (state.keys.some((candidate) => candidate.key === value)) throw new Error("That PackyCode API key is already stored");
@@ -2518,7 +3557,7 @@ var PackyCodeKeyRing = class {
 		}));
 	}
 	async rename(id, label) {
-		const name = text(label).trim().slice(0, 60);
+		const name = text$1(label).trim().slice(0, 60);
 		if (name === "") throw new Error("That PackyCode key name cannot be empty");
 		return projection(await this.#write((state) => {
 			if (!state.keys.some((candidate) => candidate.id === id)) throw new Error("Unknown PackyCode key");
@@ -2581,7 +3620,7 @@ var PackyCodeKeyRing = class {
 			const keys = state.keys.map((candidate) => candidate.id === id ? {
 				...candidate,
 				disabledAt: now,
-				disabledReason: text(reason) === "" ? "unusable" : text(reason)
+				disabledReason: text$1(reason) === "" ? "unusable" : text$1(reason)
 			} : candidate);
 			if (!keys.some((candidate) => candidate.id === id)) return {
 				activeId: state.activeId,
@@ -2595,69 +3634,6 @@ var PackyCodeKeyRing = class {
 	}
 };
 //#endregion
-//#region src/permission.js
-/**
-* The Claude Code CLI mode a session's own permissions allow.
-*
-* A CLI-backed turn runs the CLI's own tool loop, outside the harness sandbox
-* and approval flow. Deriving its mode from the session's permission preset
-* means the user grants it once, in the place they already grant the harness
-* itself, instead of in a separate plugin setting.
-*
-* @module dsh-packycode-api/permission
-*/
-/** Configured value meaning "follow the session's permission preset". */
-const AUTO_CLAUDE_MODE = "auto";
-const RANK = Object.freeze({
-	"read-only": 0,
-	edit: 1,
-	full: 2
-});
-/**
-* Map the harness's two permission knobs onto a CLI mode.
-*
-* The CLI cannot ask the harness user for approval, so it skips its own
-* permission checks only when the session itself neither sandboxes nor asks.
-* @param sandbox - the session's resolved sandbox mode.
-* @param approval - the session's effective approval policy.
-* @returns a CLI mode, or `undefined` for an unknown sandbox mode.
-*/
-function claudeModeFor(sandbox, approval) {
-	switch (sandbox) {
-		case "read-only": return "read-only";
-		case "workspace-write": return "edit";
-		case "danger-full-access": return approval === "never" ? "full" : "edit";
-		default: return;
-	}
-}
-/**
-* Read a session's CLI mode from the host's permission services.
-* @param ctx - the plugin context; services are read without an inject requirement.
-* @param session - the session whose permission state is read.
-* @returns a CLI mode, or `undefined` when the session or the services are absent.
-*/
-function claudeModeForSession(ctx, session) {
-	if (session === void 0 || session === null) return void 0;
-	try {
-		const sandbox = ctx.get?.("sandboxPolicy")?.resolve?.({ session })?.mode;
-		const approval = ctx.get?.("approval")?.effectivePolicy?.(session);
-		return claudeModeFor(sandbox, approval);
-	} catch {
-		return;
-	}
-}
-/**
-* The narrower of two modes; an unknown ceiling leaves the request as it is.
-* @param requested - the mode a caller asked for.
-* @param ceiling - the most the session allows.
-* @returns the mode the CLI runs with.
-*/
-function capClaudeMode(requested, ceiling) {
-	if (ceiling === void 0 || RANK[ceiling] === void 0) return requested;
-	if (requested === void 0 || RANK[requested] === void 0) return ceiling;
-	return RANK[requested] > RANK[ceiling] ? ceiling : requested;
-}
-//#endregion
 //#region src/plugin-version.js
 /**
 * Version self-knowledge for the settings panel.
@@ -2675,36 +3651,6 @@ const NPM_REGISTRY_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/late
 const DEFAULT_VERSION_TTL_MS = 5 * 6e4;
 const DEFAULT_VERSION_TIMEOUT_MS = 1e4;
 const DEFAULT_UPDATE_TIMEOUT_MS = 18e4;
-const clone = (value) => structuredClone(value);
-/**
-* Resolve fetch at call time. A sibling plugin may wrap `globalThis.fetch`
-* and later dismantle that wrapper; a binding captured during `apply()` would
-* keep the dead wrapper for the process lifetime.
-*/
-function ambientFetch(input, init) {
-	const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
-	if (!headers.has("accept-encoding")) headers.set("accept-encoding", "identity");
-	return globalThis.fetch(input, {
-		...init,
-		headers
-	});
-}
-/** One caller's cancellation must not abort the shared registry read. */
-function waitForSharedRequest(promise, signal) {
-	if (signal === void 0) return promise;
-	signal.throwIfAborted();
-	return new Promise((resolve, reject) => {
-		const onAbort = () => reject(signal.reason);
-		signal.addEventListener("abort", onAbort, { once: true });
-		promise.then((value) => {
-			signal.removeEventListener("abort", onAbort);
-			resolve(value);
-		}, (error) => {
-			signal.removeEventListener("abort", onAbort);
-			reject(error);
-		});
-	});
-}
 /** Parse a strict `x.y.z[-pre][+build]` version; anything else is undefined. */
 function parseSemver(value) {
 	if (typeof value !== "string") return void 0;
@@ -2906,22 +3852,17 @@ function createPackyCodePluginManager({ fetchImpl = ambientFetch, runCommand = s
 		argv,
 		execPath
 	});
-	let cached;
-	let inFlight;
-	let generation = 0;
 	let updating = false;
 	const fetchLatest = async (signal) => {
-		const timeoutSignal = AbortSignal.timeout(timeoutMs);
-		const requestSignal = signal === void 0 ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
 		let response;
 		try {
-			response = await fetchImpl(registryUrl, {
-				headers: { Accept: "application/json" },
-				redirect: "error",
-				signal: requestSignal
+			response = await boundedFetch(registryUrl, { headers: { Accept: "application/json" } }, {
+				fetchImpl,
+				timeoutMs,
+				signal
 			});
 		} catch (error) {
-			if (signal?.aborted) throw error;
+			if (error.aborted) throw error.cause;
 			throw new Error("PackyCode plugin version check failed");
 		}
 		if (!response.ok) throw new Error("PackyCode plugin version check failed");
@@ -2957,36 +3898,20 @@ function createPackyCodePluginManager({ fetchImpl = ambientFetch, runCommand = s
 			fetchedAt: now()
 		};
 	};
+	const cache = createCachedRead(load, {
+		ttlMs,
+		now
+	});
 	return Object.freeze({
-		async read({ force = false, signal } = {}) {
+		read: (options) => cache.read(options),
+		async update({ signal } = {}) {
 			signal?.throwIfAborted();
-			if (!force && cached !== void 0 && now() - cached.fetchedAt < ttlMs) return clone(cached);
-			const createPending = (requestSignal) => {
-				const observedGeneration = generation;
-				return load(requestSignal).then((value) => {
-					if (generation === observedGeneration) cached = value;
-					return value;
-				});
-			};
-			if (force) return clone(await createPending(signal));
-			const pending = inFlight ?? createPending();
-			if (inFlight === void 0) {
-				inFlight = pending;
-				const clear = () => {
-					if (inFlight === pending) inFlight = void 0;
-				};
-				pending.then(clear, clear);
-			}
-			return clone(await waitForSharedRequest(pending, signal));
-		},
-		async update({ signal } = {}) {
-			signal?.throwIfAborted();
-			if (updating) throw new Error("PackyCode plugin update is already running");
-			updating = true;
-			try {
-				const install = await findInstall({
-					dshHome,
-					ownPackageJsonUrl
+			if (updating) throw new Error("PackyCode plugin update is already running");
+			updating = true;
+			try {
+				const install = await findInstall({
+					dshHome,
+					ownPackageJsonUrl
 				});
 				if (install.kind === "link") throw new Error("PackyCode plugin is installed from a local checkout");
 				if (install.kind !== "npm" || install.profile === void 0) throw new Error("PackyCode plugin update could not find the owning profile");
@@ -3018,8 +3943,7 @@ function createPackyCodePluginManager({ fetchImpl = ambientFetch, runCommand = s
 					expected: latest,
 					settleDelayMs
 				});
-				generation += 1;
-				cached = void 0;
+				cache.invalidate();
 				return {
 					version: latest,
 					profile: install.profile
@@ -3028,172 +3952,88 @@ function createPackyCodePluginManager({ fetchImpl = ambientFetch, runCommand = s
 				updating = false;
 			}
 		},
-		invalidate() {
-			generation += 1;
-			cached = void 0;
-		}
+		invalidate: () => cache.invalidate()
 	});
 }
 //#endregion
-//#region src/catalog.js
+//#region src/preferences.js
 /**
-* The built-in PackyCode model catalog.
-*
-* The gateway's own guidance for these routes, which the base URLs and pinned
-* protocols below exist to satisfy:
-* - OpenAI/Codex traffic takes `/v1` in the base URL and never an endpoint
-*   path — the SDK appends `/responses` or `/chat/completions` itself.
-* - Anthropic traffic takes `https://cf.api.fan` with **no** `/v1`: the
-*   Anthropic client appends `/v1/messages` itself.
-* - A model asked over the wrong protocol does not fail cleanly; the stream
-*   ends early. So every model pins the protocol its vendor serves here.
+* Where the plugin's preferences are read from and written to, on both
+* settings generations DSH has shipped.
 *
-* Effort levels come from each vendor's documentation, because an effort the
-* model does not support is refused before the request is sent: Claude Opus
-* 5.5 (platform.claude.com effort docs), GPT-6.1 Sol and GPT-6 Astra
-* `reasoning.effort` (developers.openai.com model pages), DeepSeek thinking
-* mode (`thinking` toggle plus `low|high|max` effort).
+* - DSH 0.1.5 installs a settings *section*: the section hands back a live
+*   source and writes go through `settings.update(namespace, patch)`.
+* - DSH 0.2 has no sections: a preference is a *volatile* Config field of the
+*   plugin's own row, read through a live reference, written through
+*   `settings.update(rowId, patch)`, and announced by `loader/volatile-update`.
+*   Only volatile fields are writable there, so the host overrides stay
+*   read-only while the web search preference is editable.
 *
-* @module dsh-packycode-api/catalog
+* @module dsh-packycode-api/preferences
 */
-/** pi-ai never reads this gateway's pricing; the harness zeroes cost anyway. */
-const NO_COST = Object.freeze({
-	input: 0,
-	output: 0,
-	cacheRead: 0,
-	cacheWrite: 0
-});
-const COMPLETIONS_BASE = `${DEFAULT_API_HOST}/v1`;
-const RESPONSES_BASE = `${DEFAULT_API_HOST}/v1`;
-const MESSAGES_BASE = DEFAULT_API_HOST;
 /**
-* pi-ai thinking-level maps. A level pinned to `null` is unsupported; an
-* absent key keeps pi-ai's own default for that level, which is how `off`
-* stays available for DeepSeek (`off` sends nothing and the deepseek dialect
-* then emits `thinking: disabled`).
+* Mark a preference editable without restarting the plugin. DSH 0.2 stores
+* plugin preferences as volatile Config fields and writes only those; an older
+* schema library has no `volatile()` and keeps a plain field.
 */
-const DEEPSEEK_LEVELS = Object.freeze({
-	minimal: null,
-	low: "low",
-	medium: null,
-	high: "high",
-	xhigh: null,
-	max: "max"
-});
+const live = (schema) => typeof schema.volatile === "function" ? schema.volatile() : schema;
+/** Read a Config field that may arrive as a volatile reference. */
+const fieldValue = (value) => value !== null && typeof value === "object" && typeof value.get === "function" ? value.get() : value;
+/** A preference target nothing can write to yet. */
+function unwritable(message) {
+	return {
+		writable: false,
+		set: async () => {
+			throw new Error(message);
+		}
+	};
+}
 /**
-* Claude 5.5 models, GPT-6.1 Sol, and GPT-6 Astra cannot disable reasoning, so `off` is
-* pinned unsupported. The Claude models run through the CLI, which picks its
-* own effort, so for them these levels only shape the picker.
+* Connect the preferences to the settings service the host provides.
+* @param settingsCtx - the scope the `settings` inject handed over.
+* @param options - the plugin context and Config, the section namespace, the
+*   current source and how to replace it, what to do when the section changes,
+*   and the two preference targets this fills in (host overrides, search).
 */
-const ALWAYS_THINKING_LEVELS = Object.freeze({
-	off: null,
-	minimal: null,
-	low: "low",
-	medium: "medium",
-	high: "high",
-	xhigh: "xhigh",
-	max: "max"
-});
-const PACKYCODE_MODELS = Object.freeze([
-	Object.freeze({
-		id: "deepseek-flash",
-		name: "DeepSeek Flash",
-		api: "openai-completions",
-		provider: PROVIDER,
-		baseUrl: COMPLETIONS_BASE,
-		reasoning: true,
-		input: Object.freeze(["text"]),
-		cost: NO_COST,
-		contextWindow: 1e6,
-		maxTokens: 384e3,
-		thinkingLevelMap: DEEPSEEK_LEVELS,
-		compat: Object.freeze({
-			thinkingFormat: "deepseek",
-			maxTokensField: "max_tokens",
-			requiresReasoningContentOnAssistantMessages: true,
-			supportsDeveloperRole: false
-		})
-	}),
-	Object.freeze({
-		id: "gpt-6.1-sol",
-		name: "GPT-6.1 Sol",
-		api: "openai-responses",
-		provider: PROVIDER,
-		baseUrl: RESPONSES_BASE,
-		reasoning: true,
-		input: Object.freeze(["text", "image"]),
-		cost: NO_COST,
-		contextWindow: 105e4,
-		maxTokens: 128e3,
-		thinkingLevelMap: ALWAYS_THINKING_LEVELS
-	}),
-	Object.freeze({
-		id: "gpt-6-astra",
-		name: "GPT-6 Astra",
-		api: "openai-responses",
-		provider: PROVIDER,
-		baseUrl: RESPONSES_BASE,
-		reasoning: true,
-		input: Object.freeze(["text", "image"]),
-		cost: NO_COST,
-		contextWindow: 105e4,
-		maxTokens: 128e3,
-		thinkingLevelMap: ALWAYS_THINKING_LEVELS
-	}),
-	Object.freeze({
-		id: "claude-opus-5-5",
-		name: "Claude Opus 5.5",
-		api: "anthropic-messages",
-		provider: PROVIDER,
-		baseUrl: MESSAGES_BASE,
-		reasoning: true,
-		input: Object.freeze(["text", "image"]),
-		cost: NO_COST,
-		contextWindow: 1e6,
-		maxTokens: 128e3,
-		thinkingLevelMap: ALWAYS_THINKING_LEVELS,
-		compat: Object.freeze({
-			forceAdaptiveThinking: true,
-			supportsTemperature: false
-		})
-	}),
-	Object.freeze({
-		id: "claude-sonnet-5-5",
-		name: "Claude Sonnet 5.5",
-		api: "anthropic-messages",
-		provider: PROVIDER,
-		baseUrl: MESSAGES_BASE,
-		reasoning: true,
-		input: Object.freeze(["text", "image"]),
-		cost: NO_COST,
-		contextWindow: 1e6,
-		maxTokens: 128e3,
-		thinkingLevelMap: ALWAYS_THINKING_LEVELS,
-		compat: Object.freeze({
-			forceAdaptiveThinking: true,
-			supportsTemperature: false
-		})
-	}),
-	Object.freeze({
-		id: "claude-haiku-5-5",
-		name: "Claude Haiku 5.5",
-		api: "anthropic-messages",
-		provider: PROVIDER,
-		baseUrl: MESSAGES_BASE,
-		reasoning: true,
-		input: Object.freeze(["text", "image"]),
-		cost: NO_COST,
-		contextWindow: 1e6,
-		maxTokens: 128e3,
-		thinkingLevelMap: ALWAYS_THINKING_LEVELS,
-		compat: Object.freeze({
-			forceAdaptiveThinking: true,
-			supportsTemperature: false
-		})
-	})
-]);
-/** Every model id this catalog advertises, in picker order. */
-const PACKYCODE_MODEL_IDS = Object.freeze(PACKYCODE_MODELS.map((model) => model.id));
+function connectSettings(settingsCtx, { ctx, Config, namespace, source, setSource, onChange, hostPreference, searchPreference }) {
+	const settings = settingsCtx.settings;
+	if (typeof settings?.installSection === "function") {
+		try {
+			settings.installSection(ctx, namespace, Config, source(), {
+				setSource: (current) => setSource(typeof current === "function" ? () => current() ?? {} : () => current ?? {}),
+				onChange
+			});
+			if (typeof settings.update === "function") {
+				const write = (patch) => settings.update(namespace, patch);
+				Object.assign(hostPreference, {
+					writable: true,
+					set: write
+				});
+				Object.assign(searchPreference, {
+					writable: true,
+					set: write
+				});
+			}
+		} catch (error) {
+			ctx.logger?.warn?.("packycode-api: host overrides unavailable, defaults stand: %s", error.message);
+		}
+		return;
+	}
+	if (typeof settings?.update !== "function") return;
+	const rowId = ctx.fiber?.entry?.options?.id ?? namespace;
+	Object.assign(searchPreference, {
+		writable: settings.writable !== false,
+		set: (patch) => settings.update(rowId, patch)
+	});
+	if (typeof settings.configure === "function") {
+		const scope = typeof settingsCtx.effect === "function" ? settingsCtx : ctx;
+		try {
+			scope.effect(() => settings.configure({ auto: false }, ctx.fiber), "packycode-api: settings page policy");
+		} catch (error) {
+			ctx.logger?.warn?.("packycode-api: could not hide the generated settings page: %s", error.message);
+		}
+	}
+}
 //#endregion
 //#region src/provider.js
 /**
@@ -3313,190 +4153,36 @@ function guardKeyRotation(stream, { onKeyFailure, key } = {}) {
 	} });
 }
 //#endregion
-//#region src/rpc.js
+//#region src/route.js
 /**
-* The loopback RPC surface behind the settings panel and the composer chip.
-*
-* Every reply carries only what this plugin owns: key labels and state, the
-* balance projection the host built, host overrides, and whether this device
-* has the Claude Code CLI. Key material never crosses this boundary.
+* The HTTP model route: the pi-ai provider profile and the adapter that
+* serves the catalog's HTTP models (DeepSeek and GPT) with the ring's keys.
 *
-* @module dsh-packycode-api/rpc
+* @module dsh-packycode-api/route
 */
-const ok = (value) => ({
-	ok: true,
-	value
-});
-const failed = (message) => ({
-	ok: false,
-	error: { message }
+/**
+* Request-level bounds from the shipped pi-ai adapter: a bounded image payload
+* keeps a long session completing requests instead of being refused by a
+* gateway size cap.
+*/
+const REQUEST_LIMITS = Object.freeze({
+	streamIdleTimeoutMs: 600 * 1e3,
+	maxRequestImageBytes: 20 * 1024 * 1024,
+	requestImagePixelBudget: 2048 * 2048,
+	requestImageMaxBytes: 1024 * 1024
 });
-/** Only sentences this plugin authored may reach the browser. */
-const SAFE_MESSAGE = /^(?:PackyCode|That |Unknown |PackyCode's |add |the )[\s\S]{0,180}$/u;
-/** Accept an absolute http(s) origin and drop a trailing slash. */
-function normalizeHost(value, fallback) {
-	const text = typeof value === "string" ? value.trim() : "";
-	if (text === "") return fallback;
-	let url;
-	try {
-		url = new URL(text);
-	} catch {
-		return fallback;
-	}
-	if (url.protocol !== "https:" && url.protocol !== "http:") return fallback;
-	return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
-}
 /**
-* Build the RPC handler.
-* @param options - the key ring, balance reader, host preference, and the
-*   Claude Code CLI manager (optional: without it the CLI endpoints refuse).
-* @returns a handler for `connection.rpc.handle(CHANNEL, handler)`.
+* pi-ai's credential store over the key ring.
+*
+* Reads answer with the active key so pi-ai's own auth reporting stays honest,
+* while writes are refused: the ring owns them, because only the ring can move
+* the active pointer past a key the gateway rejected.
+* @param ring - the plugin's key ring.
+* @returns a pi-ai `CredentialStore`.
 */
-function createPackyCodeRpc({ ring, balance, hosts, preference, claudeCli, pluginManager }) {
-	const requireCli = () => {
-		if (claudeCli === void 0) throw new Error("PackyCode Claude Code CLI support is unavailable in this runtime");
-		return claudeCli;
-	};
-	const requireManager = () => {
-		if (pluginManager === void 0) throw new Error("PackyCode plugin version is unavailable");
-		return pluginManager;
-	};
-	const status = async () => ({
-		...await ring.list(),
-		hosts: hosts(),
-		writable: preference.writable === true,
-		defaults: {
-			apiHost: DEFAULT_API_HOST,
-			statusHost: DEFAULT_STATUS_HOST
-		}
-	});
-	return async (endpoint, payload, signal) => {
-		try {
-			switch (endpoint) {
-				case "status": return ok(await status());
-				case "keys/add":
-					await ring.add(payload?.key, payload?.label);
-					balance.invalidate();
-					return ok(await status());
-				case "keys/rename":
-					await ring.rename(String(payload?.id ?? ""), payload?.label);
-					balance.invalidate();
-					return ok(await status());
-				case "keys/remove":
-					await ring.remove(String(payload?.id ?? ""));
-					balance.invalidate();
-					return ok(await status());
-				case "keys/remove-all":
-					await ring.removeAll();
-					balance.invalidate();
-					return ok(await status());
-				case "keys/select":
-					await ring.select(String(payload?.id ?? ""));
-					balance.invalidate();
-					return ok(await status());
-				case "keys/enable":
-					await ring.enable(String(payload?.id ?? ""));
-					balance.invalidate();
-					return ok(await status());
-				case "balance": {
-					const [value, state] = await Promise.all([balance.read({ force: payload?.force === true }), ring.list()]);
-					return ok({
-						...value,
-						activeId: state.activeId
-					});
-				}
-				case "hosts/update":
-					if (preference.writable !== true) throw new Error("PackyCode host overrides are not writable in this profile");
-					await preference.set({
-						apiHost: normalizeHost(payload?.apiHost, hosts().apiHost),
-						statusHost: normalizeHost(payload?.statusHost, hosts().statusHost)
-					});
-					balance.invalidate();
-					return ok(await status());
-				case "claude-cli/status": return ok(await requireCli().status({ force: payload?.force === true }));
-				case "claude-cli/install": {
-					const cli = requireCli();
-					cli.install();
-					return ok(await cli.status());
-				}
-				case "plugin/version": return ok(await requireManager().read({
-					force: payload?.force === true,
-					signal
-				}));
-				case "plugin/update": return ok(await requireManager().update({ signal }));
-				default: return failed("Unknown PackyCode endpoint");
-			}
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return failed(SAFE_MESSAGE.test(message) ? message : "PackyCode request failed");
-		}
-	};
-}
-//#endregion
-//#region src/index.js
-/**
-* dsh-packycode-api — a self-contained PackyCode route for DeepSeek Harness.
-*
-* The plugin builds its own pi-ai provider, model catalog, key ring, and
-* balance reader, then registers the route through the same public
-* `llm.registerAdapter` API the shipped adapters use. Nothing here reads the
-* profile's composition config, so installing the package is the whole setup:
-* the picker shows the models and the user only pastes API keys.
-*
-* @module dsh-packycode-api
-*/
-const name = PLUGIN_ID;
-/**
-* Only the model route is mandatory. `connection` carries the browser RPC
-* surface, and `settings` the host overrides: a profile without them (a
-* headless run, for one) must still boot with a working route instead of
-* blocking on a service it will never see.
-*/
-const inject = ["llm", "credentials"];
-/** What a `claude_code` tool run is told about where its task came from. */
-const CLAUDE_TOOL_INSTRUCTIONS = "This task was delegated to Claude Code by another agent in DeepSeek Harness through its claude_code tool. The task text is self-contained; complete it with your own tools and reply with the final result only.";
-/** Host overrides; a profile that never installs this section keeps the defaults. */
-const Config = z.object({
-	apiHost: z.string().default(DEFAULT_API_HOST),
-	statusHost: z.string().default(DEFAULT_STATUS_HOST),
-	/** Path to the Claude Code CLI binary; empty means "look in the usual places, then PATH". */
-	claudeCliPath: z.string().default(""),
-	/**
-	* What the CLI may do on its own during a CLI-backed turn. `auto` follows the
-	* session's permission preset, so nothing needs configuring here.
-	*/
-	claudeCliMode: z.union([
-		AUTO_CLAUDE_MODE,
-		"read-only",
-		"edit",
-		"full"
-	]).default(AUTO_CLAUDE_MODE),
-	/** Working directory for CLI-backed turns; empty means "the session's workspace". */
-	claudeCliCwd: z.string().default("")
-});
-/**
-* Request-level bounds from the shipped pi-ai adapter: a bounded image payload
-* keeps a long session completing requests instead of being refused by a
-* gateway size cap.
-*/
-const REQUEST_LIMITS = Object.freeze({
-	streamIdleTimeoutMs: 600 * 1e3,
-	maxRequestImageBytes: 20 * 1024 * 1024,
-	requestImagePixelBudget: 2048 * 2048,
-	requestImageMaxBytes: 1024 * 1024
-});
-/**
-* pi-ai's credential store over the key ring.
-*
-* Reads answer with the active key so pi-ai's own auth reporting stays honest,
-* while writes are refused: the ring owns them, because only the ring can move
-* the active pointer past a key the gateway rejected.
-* @param ring - the plugin's key ring.
-* @returns a pi-ai `CredentialStore`.
-*/
-function ringCredentialStore(ring) {
-	const managed = () => {
-		throw new Error("PackyCode API keys are managed in the PackyCode settings section");
+function ringCredentialStore(ring) {
+	const managed = () => {
+		throw new Error("PackyCode API keys are managed in the PackyCode settings section");
 	};
 	return {
 		async read() {
@@ -3551,21 +4237,1108 @@ function createPackyCodeProfile(provider) {
 		}, `${PLUGIN_ID}.retryPolicy`)
 	});
 }
-function apply(ctx, config) {
-	const balanceReaderOptions = {};
-	const ring = new PackyCodeKeyRing(ctx.credentials);
+/**
+* The HTTP route's adapter.
+*
+* Each request resolves the active key, then runs on the key the chooser picks
+* for its model; a key-level failure in the stream moves that key aside.
+* @param options - the key ring and chooser, the session id used when a caller
+*   supplies none, and the attachment store image input is read from.
+* @returns a `PiAiAdapter` serving the `packycode` route.
+*/
+function createRouteAdapter({ ring, keys, fallbackSessionId, resolveAttachments }) {
+	const raw = createPackyCodeProvider();
 	/**
-	* Key material to ring id. A failure is reported from inside a stream, which
-	* carries the request's key but not its id; this index is refreshed on every
-	* resolution so the right key is the one that moves aside.
+	* The gateway's Codex-group check refuses a Responses request that carries
+	* no `prompt_cache_key` with a 403, which pi-ai derives from the session id.
+	* The harness supplies one for every agent turn; the fallback covers a
+	* caller that does not, so the route never fails for a missing cache key.
 	*/
-	const idByKey = /* @__PURE__ */ new Map();
-	const rememberKeys = async () => {
-		for (const entry of await ring.secrets()) idByKey.set(entry.key, entry.id);
+	const requestOptions = (model, options) => {
+		const withId = options === void 0 || options.sessionId !== void 0 ? options : {
+			...options,
+			sessionId: fallbackSessionId
+		};
+		if (typeof withId?.apiKey !== "string") return withId;
+		const key = keys.forRequest(model?.id, withId.apiKey);
+		return key === withId.apiKey ? withId : {
+			...withId,
+			apiKey: key
+		};
+	};
+	const guarded = (method) => (model, context, options) => {
+		const routed = requestOptions(model, options);
+		return guardKeyRotation(raw[method](model, context, routed), {
+			key: routed?.apiKey,
+			onKeyFailure: keys.onKeyFailure
+		});
+	};
+	const provider = Object.freeze({
+		...raw,
+		stream: guarded("stream"),
+		streamSimple: guarded("streamSimple")
+	});
+	const profiles = /* @__PURE__ */ new Map([[PROVIDER, createPackyCodeProfile(provider)]]);
+	return new PiAiAdapter({
+		profiles: () => profiles,
+		resolveApiKey: async () => {
+			const active = await keys.active();
+			if (active === void 0) throw new LlmError("No usable PackyCode API key: add one under Settings → PackyCode, or re-enable the keys this plugin moved past.", "MISSING_CREDENTIAL");
+			return active.key;
+		},
+		auth: Object.freeze({
+			credentials: ringCredentialStore(ring),
+			authContext: Object.freeze({
+				env: async () => void 0,
+				fileExists: async () => false
+			})
+		}),
+		resolveAttachments
+	});
+}
+//#endregion
+//#region src/rpc.js
+/**
+* The loopback RPC surface behind the settings panel and the composer chip.
+*
+* Every reply carries only what this plugin owns: key labels and state, the
+* balance and group projections the host built, host overrides, whether this
+* device has the Claude Code CLI, the plugin version, and the web search
+* preference. Key material never crosses this boundary.
+*
+* @module dsh-packycode-api/rpc
+*/
+const ok = (value) => ({
+	ok: true,
+	value
+});
+const failed = (message) => ({
+	ok: false,
+	error: { message }
+});
+/** Only sentences this plugin authored may reach the browser. */
+const SAFE_MESSAGE = /^(?:PackyCode|That |Unknown |PackyCode's |add |the )[\s\S]{0,180}$/u;
+const keyId = (payload) => String(payload?.id ?? "");
+/**
+* Build the RPC handler.
+* @param options - the key ring, the balance and group readers, the host
+*   preference, and the optional Claude Code CLI manager, plugin manager, and
+*   web search controller (without one, its endpoints refuse).
+* @returns a handler for `connection.rpc.handle(CHANNEL, handler)`.
+*/
+function createPackyCodeRpc({ ring, balance, groups, hosts, preference, claudeCli, pluginManager, search }) {
+	const need = (service, message) => {
+		if (service === void 0) throw new Error(message);
+		return service;
+	};
+	const cli = () => need(claudeCli, "PackyCode Claude Code CLI support is unavailable in this runtime");
+	const manager = () => need(pluginManager, "PackyCode plugin version is unavailable");
+	const webSearch = () => need(search, "PackyCode web search is unavailable in this runtime");
+	const groupReader = () => need(groups, "PackyCode key groups are unavailable in this runtime");
+	const status = async () => ({
+		...await ring.list(),
+		hosts: hosts(),
+		writable: preference.writable === true,
+		defaults: {
+			apiHost: DEFAULT_API_HOST,
+			statusHost: DEFAULT_STATUS_HOST
+		}
+	});
+	/**
+	* Key mutations, each answered with the new status. Every one drops the
+	* cached balance; one that changes which keys exist also drops the groups.
+	*/
+	const keyMutations = {
+		"keys/add": {
+			run: (payload) => ring.add(payload?.key, payload?.label),
+			changesKeys: true
+		},
+		"keys/rename": { run: (payload) => ring.rename(keyId(payload), payload?.label) },
+		"keys/remove": {
+			run: (payload) => ring.remove(keyId(payload)),
+			changesKeys: true
+		},
+		"keys/remove-all": {
+			run: () => ring.removeAll(),
+			changesKeys: true
+		},
+		"keys/select": { run: (payload) => ring.select(keyId(payload)) },
+		"keys/enable": { run: (payload) => ring.enable(keyId(payload)) }
 	};
+	const endpoints = {
+		status: () => status(),
+		balance: async (payload) => {
+			const [value, state] = await Promise.all([balance.read({ force: payload?.force === true }), ring.list()]);
+			return {
+				...value,
+				activeId: state.activeId
+			};
+		},
+		groups: (payload) => groupReader().read({ force: payload?.force === true }),
+		"hosts/update": async (payload) => {
+			if (preference.writable !== true) throw new Error("PackyCode host overrides are not writable in this profile");
+			await preference.set({
+				apiHost: normalizeHost(payload?.apiHost, hosts().apiHost),
+				statusHost: normalizeHost(payload?.statusHost, hosts().statusHost)
+			});
+			balance.invalidate();
+			groups?.invalidate();
+			return status();
+		},
+		"claude-cli/status": (payload) => cli().status({ force: payload?.force === true }),
+		"claude-cli/install": () => {
+			cli().install();
+			return cli().status();
+		},
+		"plugin/version": (payload, signal) => manager().read({
+			force: payload?.force === true,
+			signal
+		}),
+		"plugin/update": (_payload, signal) => manager().update({ signal }),
+		"search/status": () => webSearch().status(),
+		"search/update": (payload) => webSearch().update({
+			searchProvider: payload?.searchProvider,
+			searchBackend: payload?.searchBackend
+		})
+	};
+	return async (endpoint, payload, signal) => {
+		try {
+			const mutation = Object.hasOwn(keyMutations, endpoint) ? keyMutations[endpoint] : void 0;
+			if (mutation !== void 0) {
+				await mutation.run(payload);
+				balance.invalidate();
+				if (mutation.changesKeys) groups?.invalidate();
+				return ok(await status());
+			}
+			const handle = Object.hasOwn(endpoints, endpoint) ? endpoints[endpoint] : void 0;
+			if (handle === void 0) return failed("Unknown PackyCode endpoint");
+			return ok(await handle(payload, signal));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return failed(SAFE_MESSAGE.test(message) ? message : "PackyCode request failed");
+		}
+	};
+}
+//#endregion
+//#region src/search.js
+/**
+* PackyCode web search for the DSH `web` seam.
+*
+* Two search providers register with `ctx.web`:
+* - `packycode-api` searches through PackyCode for every request.
+* - `packycode-api-auto` searches through PackyCode only when the initiating
+*   session runs on a PackyCode model, and hands every other request to the
+*   provider DSH would have used without this plugin.
+*
+* PackyCode has no dedicated search endpoint; a search is one model call with
+* the vendor's server-side search tool. The user picks the backend:
+* - `deepseek`: Anthropic Messages at `/v1/messages`, `deepseek-flash`, with
+*   the `web_search_20250305` server tool. Results come from its structured
+*   `web_search_tool_result` blocks, never from prose.
+* - `gpt`: OpenAI Responses at `/v1/responses`, `gpt-6.1-sol`, with the
+*   hosted `web_search` tool. Results come from `url_citation` annotations and
+*   the `web_search_call` actions.
+*
+* Only keys stored in this plugin's key ring authenticate a search; there is no
+* fallback to another credential. A key the gateway reports as exhausted or
+* rejected is moved aside exactly as on the model route, and the search tries
+* the next usable key.
+*
+* @module dsh-packycode-api/search
+*/
+/** Search provider that always searches through PackyCode. */
+const PACKYCODE_SEARCH_PROVIDER_ID = "packycode-api";
+/** Search provider that routes by the initiating session's model provider. */
+const PACKYCODE_AUTO_SEARCH_PROVIDER_ID = "packycode-api-auto";
+/** Both ids this plugin registers; neither may serve as its own fallback. */
+const OWN_SEARCH_PROVIDER_IDS = Object.freeze([PACKYCODE_SEARCH_PROVIDER_ID, PACKYCODE_AUTO_SEARCH_PROVIDER_ID]);
+/** DSH's built-in search provider, the fallback when nothing else is known. */
+const DSH_SEARCH_PROVIDER_FALLBACK = "deepseek-official";
+/** Search routing the user picks. */
+const SEARCH_MODE_DEFAULT = "default";
+const SEARCH_MODES = Object.freeze([
+	SEARCH_MODE_DEFAULT,
+	"auto",
+	"packycode"
+]);
+/** Search backends the user picks between. */
+const SEARCH_BACKEND_DEEPSEEK = "deepseek";
+const SEARCH_BACKENDS = Object.freeze([SEARCH_BACKEND_DEEPSEEK, "gpt"]);
+/**
+* DeepSeek is the default: a search costs a few thousand tokens there, and its
+* group answered the server tool in the live check. GPT search reads far more
+* (about 26K input tokens per search) and needs a key whose group the gateway
+* currently routes GPT models to.
+*/
+const DEFAULT_SEARCH_BACKEND = SEARCH_BACKEND_DEEPSEEK;
+/** The model each backend searches with. */
+const SEARCH_BACKEND_MODELS = Object.freeze({
+	[SEARCH_BACKEND_DEEPSEEK]: "deepseek-flash",
+	["gpt"]: "gpt-6.1-sol"
+});
+/** Bound on one search request, below the `web_search` tool's 60 s budget. */
+const DEFAULT_SEARCH_TIMEOUT_MS = 55e3;
+/** Upper bound on server-side searches inside one DeepSeek request. */
+const DEEPSEEK_MAX_USES = 3;
+const MAX_OUTPUT_TOKENS = 4096;
+const ANTHROPIC_VERSION = "2023-06-01";
+/** Distinct keys one search may try before reporting the last failure. */
+const MAX_KEY_ATTEMPTS = 4;
+const MAX_CONTENT_CHARS = 4e3;
+const MAX_SNIPPET_CHARS = 500;
+const MAX_TITLE_CHARS = 200;
+const MAX_SOURCES = 20;
+const MAX_ERROR_DETAIL_CHARS = 400;
+/**
+* Error shape of the DSH web seam. `@deepseek-ai/dsh-web` defines `WebError`
+* as a bare `HarnessError` subclass with a machine-routable `code`; consumers
+* route on that code, so this mirror avoids a peer dependency on the package.
+*/
+var WebError = class extends HarnessError {};
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" ? value : "";
+function bounded(value, maximum) {
+	const clean = text(value).replace(/\s+/gu, " ").trim();
+	if (clean === "") return void 0;
+	return clean.length <= maximum ? clean : `${clean.slice(0, maximum - 1)}…`;
+}
+function boundedBlock(value, maximum) {
+	const clean = text(value).trim();
+	if (clean === "") return void 0;
+	return clean.length <= maximum ? clean : `${clean.slice(0, maximum - 1)}…`;
+}
+function httpUrl(value) {
+	const url = text(value);
+	if (url === "") return void 0;
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** Accumulates sources by URL, first sighting wins, missing fields filled later. */
+function sourceList() {
+	const byUrl = /* @__PURE__ */ new Map();
+	return {
+		add({ url, title, snippet, publishedAt }) {
+			const parsed = httpUrl(url);
+			if (parsed === void 0) return;
+			const key = parsed.href;
+			const existing = byUrl.get(key);
+			if (existing === void 0) {
+				if (byUrl.size >= MAX_SOURCES) return;
+				byUrl.set(key, {
+					url: text(url),
+					title: bounded(title, MAX_TITLE_CHARS) ?? parsed.hostname,
+					...bounded(snippet, MAX_SNIPPET_CHARS) === void 0 ? {} : { snippet: bounded(snippet, MAX_SNIPPET_CHARS) },
+					...bounded(publishedAt, 64) === void 0 ? {} : { publishedAt: bounded(publishedAt, 64) }
+				});
+				return;
+			}
+			if (existing.title === parsed.hostname && bounded(title, MAX_TITLE_CHARS) !== void 0) existing.title = bounded(title, MAX_TITLE_CHARS);
+			if (existing.snippet === void 0 && bounded(snippet, MAX_SNIPPET_CHARS) !== void 0) existing.snippet = bounded(snippet, MAX_SNIPPET_CHARS);
+			if (existing.publishedAt === void 0 && bounded(publishedAt, 64) !== void 0) existing.publishedAt = bounded(publishedAt, 64);
+		},
+		values: () => [...byUrl.values()]
+	};
+}
+function result(sources, content) {
+	return {
+		...content === void 0 ? {} : { content },
+		sources,
+		truncated: false
+	};
+}
+/**
+* Map an Anthropic Messages response with native search to a search result.
+* Sources come from `web_search_tool_result` blocks; a text block's citation
+* excerpt becomes its source's snippet; the answer text becomes `content`.
+* @param response - parsed Messages response body.
+* @returns the normalized search result.
+* @throws {WebError} when the response carries no search result block.
+*/
+function parseMessagesSearchResponse(response) {
+	const blocks = Array.isArray(response?.content) ? response.content : [];
+	const resultBlocks = blocks.filter((block) => block?.type === "web_search_tool_result");
+	if (resultBlocks.length === 0) throw new WebError("PackyCode search returned no web_search_tool_result block; the model did not run a web search", "WEB_PROVIDER_ERROR");
+	const sources = sourceList();
+	const errors = [];
+	for (const block of resultBlocks) {
+		if (!Array.isArray(block.content)) {
+			if (record(block.content) && text(block.content.error_code) !== "") errors.push(block.content.error_code);
+			continue;
+		}
+		for (const item of block.content) {
+			if (item?.type !== "web_search_result") continue;
+			sources.add({
+				url: item.url,
+				title: item.title,
+				publishedAt: item.page_age
+			});
+		}
+	}
+	for (const block of blocks) {
+		if (block?.type !== "text" || !Array.isArray(block.citations)) continue;
+		for (const cite of block.citations) sources.add({
+			url: cite?.url,
+			title: cite?.title,
+			snippet: cite?.cited_text
+		});
+	}
+	const found = sources.values();
+	if (found.length === 0 && errors.length > 0) throw new WebError(`PackyCode search failed upstream (${errors.join(", ")})`, "WEB_PROVIDER_ERROR");
+	return result(found, boundedBlock(blocks.filter((block) => block?.type === "text").map((block) => text(block.text)).join(""), MAX_CONTENT_CHARS));
+}
+/**
+* Map an OpenAI Responses response with the hosted search tool to a search
+* result. Cited URLs come first with their titles, then every other URL the
+* search actions surfaced; the final message becomes `content`.
+* @param response - parsed Responses body.
+* @returns the normalized search result.
+* @throws {WebError} when the model ran no web search.
+*/
+function parseResponsesSearchResponse(response) {
+	const output = Array.isArray(response?.output) ? response.output : [];
+	const calls = output.filter((item) => item?.type === "web_search_call");
+	if (calls.length === 0) throw new WebError("PackyCode search returned no web_search_call; the model did not run a web search", "WEB_PROVIDER_ERROR");
+	const sources = sourceList();
+	let answer;
+	for (const item of output) {
+		if (item?.type !== "message" || !Array.isArray(item.content)) continue;
+		const parts = [];
+		for (const part of item.content) {
+			if (part?.type !== "output_text") continue;
+			parts.push(text(part.text));
+			for (const annotation of Array.isArray(part.annotations) ? part.annotations : []) if (annotation?.type === "url_citation") sources.add({
+				url: annotation.url,
+				title: annotation.title
+			});
+		}
+		const joined = parts.join("");
+		if (joined.trim() !== "") answer = joined;
+	}
+	for (const call of calls) {
+		const action = record(call.action) ? call.action : {};
+		if (text(action.url) !== "") sources.add({ url: action.url });
+		for (const source of Array.isArray(action.sources) ? action.sources : []) sources.add({
+			url: source?.url,
+			title: source?.title
+		});
+	}
+	return result(sources.values(), boundedBlock(answer, MAX_CONTENT_CHARS));
+}
+/** Build one backend's request; the key is attached by the caller. */
+function buildSearchRequest(backend, { apiHost, query, sessionId }) {
+	const model = SEARCH_BACKEND_MODELS[backend];
+	if (backend === "gpt") return {
+		url: `${apiHost}/v1/responses`,
+		model,
+		headers: (key) => ({ authorization: `Bearer ${key}` }),
+		body: {
+			model,
+			input: [{
+				role: "user",
+				content: [{
+					type: "input_text",
+					text: `Search the web for: ${query}\n\nReply with a concise factual summary of what the sources say, citing them.`
+				}]
+			}],
+			tools: [{ type: "web_search" }],
+			tool_choice: "required",
+			include: ["web_search_call.action.sources"],
+			reasoning: { effort: "low" },
+			max_output_tokens: MAX_OUTPUT_TOKENS,
+			store: false,
+			...typeof sessionId === "string" && sessionId !== "" ? { prompt_cache_key: sessionId } : {}
+		},
+		parse: parseResponsesSearchResponse
+	};
+	if (backend === "deepseek") return {
+		url: `${apiHost}/v1/messages`,
+		model,
+		headers: (key) => ({
+			"x-api-key": key,
+			"anthropic-version": ANTHROPIC_VERSION
+		}),
+		body: {
+			model,
+			max_tokens: MAX_OUTPUT_TOKENS,
+			messages: [{
+				role: "user",
+				content: `Perform a web search for the query: ${query}\n\nThen reply with a concise factual summary of what the results say.`
+			}],
+			tools: [{
+				type: "web_search_20250305",
+				name: "web_search",
+				max_uses: DEEPSEEK_MAX_USES
+			}]
+		},
+		parse: parseMessagesSearchResponse
+	};
+	throw new WebError(`PackyCode search backend "${String(backend)}" is not supported`, "WEB_PROVIDER_UNAVAILABLE");
+}
+/** Read a failure body as bounded text, preferring the gateway's own message. */
+async function failureText(response) {
+	let raw = "";
+	try {
+		raw = await response.text();
+	} catch {
+		return "";
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		const message = typeof parsed?.error === "string" ? parsed.error : parsed?.error?.message ?? parsed?.message;
+		if (typeof message === "string" && message !== "") return `${typeof parsed?.error?.code === "string" && parsed.error.code !== "" ? `${parsed.error.code}: ` : ""}${message}`.slice(0, MAX_ERROR_DETAIL_CHARS);
+	} catch {}
+	return raw.replace(/\s+/gu, " ").trim().slice(0, MAX_ERROR_DETAIL_CHARS);
+}
+const mask = (message, key) => typeof key === "string" && key.length >= 8 ? message.split(key).join(`…${key.slice(-4)}`) : message;
+function isAbort(error, signal) {
+	return signal?.aborted === true || error?.name === "AbortError";
+}
+/**
+* Create the provider that searches through PackyCode on every request.
+* @param options - the key ring, the host resolution, the backend preference,
+*   the key-failure sink shared with the model route, and test seams.
+* @returns a DSH web search provider.
+*/
+function createPackyCodeSearchProvider({ ring, hosts, backend = () => DEFAULT_SEARCH_BACKEND, onKeyFailure, covers, resolveSessionId, fetchImpl = ambientFetch, timeoutMs = DEFAULT_SEARCH_TIMEOUT_MS } = {}) {
+	if (ring === void 0 || typeof ring.activeKey !== "function") throw new Error("PackyCode search requires the key ring");
+	if (typeof hosts !== "function") throw new Error("PackyCode search requires the host resolution");
+	/** One request with one key; classified failures come back as values. */
+	const attempt = async (request, key, signal) => {
+		if (signal?.aborted === true) throw new WebError("PackyCode search aborted", "WEB_ABORTED", { cause: signal.reason });
+		let response;
+		try {
+			response = await boundedFetch(request.url, {
+				method: "POST",
+				headers: {
+					...request.headers(key),
+					accept: "application/json",
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(request.body)
+			}, {
+				fetchImpl,
+				timeoutMs,
+				signal
+			});
+		} catch (error) {
+			if (error.aborted) throw new WebError("PackyCode search aborted", "WEB_ABORTED", { cause: error });
+			if (error.timedOut) throw new WebError(`PackyCode search got no answer within ${Math.round(timeoutMs / 1e3)}s`, "WEB_PROVIDER_ERROR", { cause: error });
+			throw new WebError(`PackyCode search request failed (${mask(error.code ?? error.message, key)})`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) return {
+			failure: mask(await failureText(response), key),
+			status: response.status
+		};
+		let body;
+		try {
+			body = await response.json();
+		} catch (error) {
+			if (isAbort(error, signal)) throw new WebError("PackyCode search aborted", "WEB_ABORTED", { cause: error });
+			throw new WebError("PackyCode search returned an unreadable response", "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (record(body?.error)) return {
+			failure: mask(text(body.error.message) || JSON.stringify(body.error).slice(0, MAX_ERROR_DETAIL_CHARS), key),
+			status: response.status
+		};
+		return { value: request.parse(body) };
+	};
+	return Object.freeze({
+		id: PACKYCODE_SEARCH_PROVIDER_ID,
+		available: () => true,
+		async search(searchRequest, signal) {
+			if (signal?.aborted === true) throw new WebError("PackyCode search aborted", "WEB_ABORTED", { cause: signal.reason });
+			const query = text(searchRequest?.query).trim();
+			if (query === "") throw new WebError("PackyCode search needs a non-empty query", "WEB_PROVIDER_ERROR");
+			const chosen = SEARCH_BACKENDS.includes(backend()) ? backend() : DEFAULT_SEARCH_BACKEND;
+			const request = buildSearchRequest(chosen, {
+				apiHost: hosts().apiHost,
+				query,
+				sessionId: resolveSessionId?.()
+			});
+			const candidates = await orderedKeys(ring, request.model, covers);
+			let lastFailure;
+			let uncovered = false;
+			for (const key of candidates.slice(0, MAX_KEY_ATTEMPTS)) {
+				const outcome = await attempt(request, key.key, signal);
+				if (outcome.value !== void 0) return outcome.value;
+				const failure = outcome.failure === "" ? `HTTP ${outcome.status}` : outcome.failure;
+				lastFailure = failure;
+				if (classifyClientPolicy(failure)) throw new WebError(explainClientPolicyFailure(), "WEB_PROVIDER_ERROR");
+				const kind = classifyGatewayFailure(failure) ?? (outcome.status === 401 ? "invalid-key" : void 0);
+				if (kind !== void 0) {
+					onKeyFailure?.(kind, failure, key.key, key.id);
+					continue;
+				}
+				if (classifyCoverage(failure)) {
+					uncovered = true;
+					continue;
+				}
+				throw new WebError(`PackyCode search failed (HTTP ${outcome.status}): ${failure}`, "WEB_PROVIDER_ERROR");
+			}
+			if (candidates.length === 0) throw new WebError("PackyCode search has no usable API key; add one under Settings → PackyCode", "WEB_PROVIDER_CREDENTIAL_MISSING");
+			if (uncovered) {
+				const other = chosen === "gpt" ? SEARCH_BACKEND_DEEPSEEK : "gpt";
+				throw new WebError(`PackyCode search: no stored API key's group covers ${request.model} (${chosen} backend). Switch the search backend to "${other}" under Settings → PackyCode → Web search, or add a key whose group includes it. Gateway said: ${lastFailure}`, "WEB_PROVIDER_ERROR");
+			}
+			throw new WebError(`PackyCode search: every usable key was refused (${lastFailure ?? "no detail"})`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+		}
+	});
+}
+/**
+* The keys one search tries, in order: the active key, then the other usable
+* keys in ring order — except that a key the group reading shows cannot reach
+* the backend's model goes last, behind every key that can or may.
+* @param ring - the key ring.
+* @param modelId - the backend's model.
+* @param covers - `(keyId, modelId) => true | false | undefined`, optional.
+* @returns the candidates, without key material beyond what the request needs.
+*/
+async function orderedKeys(ring, modelId, covers) {
+	const active = await ring.activeKey();
+	if (active === void 0) return [];
+	const usable = typeof ring.secrets === "function" ? (await ring.secrets()).filter((entry) => !entry.disabled) : [];
+	const start = usable.findIndex((entry) => entry.id === active.id);
+	const rest = start < 0 ? usable.filter((entry) => entry.id !== active.id) : [...usable.slice(start + 1), ...usable.slice(0, start)];
+	const rank = (entry) => {
+		const value = covers?.(entry.id, modelId);
+		return value === true ? 0 : value === false ? 2 : 1;
+	};
+	return [active, ...rest].map((entry, index) => ({
+		entry,
+		index,
+		rank: index === 0 && rank(entry) !== 2 ? -1 : rank(entry)
+	})).sort((left, right) => left.rank - right.rank || left.index - right.index).map(({ entry }) => ({
+		id: entry.id,
+		label: entry.label,
+		key: entry.key
+	}));
+}
+/** Marks a request already passing through the auto provider's fallback. */
+const delegating = new AsyncLocalStorage();
+/**
+* Create the provider that searches through PackyCode for PackyCode sessions
+* only. Every other request goes to the fallback provider: the search provider
+* the web row selected before this plugin's patch, or DSH's built-in search.
+*
+* Another plugin's router may delegate back to this one (its own fallback is
+* the web row's base, which this plugin's patch points here). A request that
+* re-enters while already delegating goes straight to DSH's built-in search
+* instead of looping.
+* @param options - the PackyCode provider, the initiating model provider, a
+*   lookup of registered search providers, and the fallback id.
+* @returns a DSH web search provider.
+*/
+function createPackyCodeAutoSearchProvider({ packycode, resolveModelProvider, resolveProvider, resolveFallbackId }) {
+	return Object.freeze({
+		id: PACKYCODE_AUTO_SEARCH_PROVIDER_ID,
+		available: () => true,
+		async search(request, signal) {
+			if (resolveModelProvider?.() === "packycode") return packycode.search(request, signal);
+			const wanted = delegating.getStore() === true ? DSH_SEARCH_PROVIDER_FALLBACK : resolveFallbackId?.() ?? "deepseek-official";
+			const id = OWN_SEARCH_PROVIDER_IDS.includes(wanted) ? DSH_SEARCH_PROVIDER_FALLBACK : wanted;
+			const provider = resolveProvider?.(id);
+			if (provider === void 0 || OWN_SEARCH_PROVIDER_IDS.includes(provider.id) || provider.available?.() !== true) throw new WebError(`PackyCode auto search: the fallback search provider "${id}" is unavailable`, "WEB_PROVIDER_UNAVAILABLE");
+			return delegating.run(true, () => provider.search(request, signal));
+		}
+	});
+}
+//#endregion
+//#region src/search-composition.js
+/**
+* Point the DSH web row's base search provider at this plugin.
+*
+* The web runtime has one search slot. Subscription plugins (Codex, Kimi)
+* rewrite that slot at runtime whenever the web row restarts, and fall back to
+* the row's *base* config for models they do not own. Writing the runtime slot
+* here as well would make two switchers restart each other forever. Instead
+* this plugin keeps one marked `- id: web` entry in the owning profile's
+* `cordis.patch.yml`: the boot layer hot-applies the file, the base config then
+* names a PackyCode provider, and every router — or the bare slot, when no
+* router holds it — reaches PackyCode for the requests it does not own.
+*
+* Only the marked entry is ever touched. It is rewritten in place, so a
+* sibling plugin that appends its own entry after it never sees this file
+* reorder; an unchanged entry is never rewritten. A profile patch replaces the
+* whole matched config, so the entry restates the web row's other scalar
+* fields. It also records, as a comment, the provider the base named before
+* the entry existed, which is where the auto provider sends requests it does
+* not serve.
+*
+* @module dsh-packycode-api/search-composition
+*/
+const SEARCH_PATCH_FILE = "cordis.patch.yml";
+const BLOCK_BEGIN = "# >>> dsh-packycode-api: web search provider (managed in Settings → PackyCode → Web search)";
+const BLOCK_END = "# <<< dsh-packycode-api: web search provider";
+const BEGIN_PREFIX = "# >>> dsh-packycode-api: web search provider";
+const FALLBACK_LINE = /^#\s*fallback:\s*(\S+)\s*$/u;
+const PROVIDER_ID = /^[A-Za-z0-9._-]+$/u;
+const EMPTY_LIST = /^\[\]\s*$/u;
+const LIST_ITEM = /^-(?:\s|$)/u;
+const ITEM_HEAD = /^- id: web\s*$/u;
+const CONTINUATION = /^\s+\S/u;
+const isBegin = (line) => line.trim().startsWith(BEGIN_PREFIX);
+const isEnd = (line) => line.trim() === BLOCK_END;
+/**
+* Find this plugin's entry: the begin marker, its comment lines, the single
+* `- id: web` item with its indented lines, and an end marker directly after.
+* Anything else — including another entry a YAML rewrite moved inside the
+* markers — is not part of it.
+* @param lines - the file split into lines.
+* @returns the half-open line range and the recorded fallback, or undefined.
+*/
+function locate(lines) {
+	const start = lines.findIndex(isBegin);
+	if (start < 0) return void 0;
+	let index = start + 1;
+	let fallback;
+	while (index < lines.length && lines[index].startsWith("#") && !isEnd(lines[index]) && !isBegin(lines[index])) {
+		const match = FALLBACK_LINE.exec(lines[index]);
+		if (match !== null) fallback = match[1];
+		index += 1;
+	}
+	let provider;
+	if (index < lines.length && ITEM_HEAD.test(lines[index])) {
+		index += 1;
+		while (index < lines.length && CONTINUATION.test(lines[index])) {
+			const match = /^\s+searchProvider:\s*['"]?([A-Za-z0-9._-]+)['"]?\s*$/u.exec(lines[index]);
+			if (match !== null) provider = match[1];
+			index += 1;
+		}
+	}
+	if (index < lines.length && isEnd(lines[index])) index += 1;
+	return {
+		start,
+		end: index,
+		fallback,
+		provider
+	};
+}
+/** Drop the located entry and any stray end marker left elsewhere. */
+function strip(lines) {
+	const found = locate(lines);
+	return (found === void 0 ? [...lines] : [...lines.slice(0, found.start), ...lines.slice(found.end)]).filter((line) => !isEnd(line));
+}
+function yamlScalar(value) {
+	if (typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return String(value);
+	return /^[A-Za-z0-9._-]+$/u.test(value) ? value : JSON.stringify(value);
+}
+/** The entry's lines; the web row's other scalar fields are restated, sorted. */
+function entryLines(providerId, fallback, baseConfig) {
+	const fields = {};
+	for (const [key, value] of Object.entries(baseConfig ?? {})) {
+		if (key === "searchProvider" || !/^[A-Za-z0-9_]+$/u.test(key)) continue;
+		if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) fields[key] = value;
+	}
+	fields.searchProvider = providerId;
+	return [
+		BLOCK_BEGIN,
+		`# fallback: ${fallback}`,
+		"- id: web",
+		"  config:",
+		...Object.keys(fields).sort().map((key) => `    ${key}: ${yamlScalar(fields[key])}`),
+		BLOCK_END
+	];
+}
+/** A provider id the auto provider may fall back to. */
+function usableFallback(id) {
+	return typeof id === "string" && PROVIDER_ID.test(id) && !OWN_SEARCH_PROVIDER_IDS.includes(id) ? id : DSH_SEARCH_PROVIDER_FALLBACK;
+}
+/**
+* Refuse a file this line-level editor cannot extend safely: a flow sequence
+* with entries, or a top-level line that is not a list item or comment.
+*/
+function assertBlockSequence(lines) {
+	for (const line of lines) {
+		if (line.trim() === "" || line.trimStart().startsWith("#") || CONTINUATION.test(line) || LIST_ITEM.test(line) || EMPTY_LIST.test(line)) continue;
+		throw new Error("PackyCode web search could not edit the profile patch: it is not a plain YAML list; set the web search provider by hand");
+	}
+}
+/**
+* Maintain this plugin's entry in the owning profile's patch file.
+* @param options - where the file is, the web row's current base config, an
+*   optional exclusive section (DSH's reload lock), and file-system seams.
+* @returns the composition: read the entry, apply a provider, remove it.
+*/
+function createSearchComposition({ resolvePatchPath, readBaseConfig, runExclusive = (run) => run(), fs = {
+	readFile,
+	writeFile,
+	rename
+} } = {}) {
+	if (typeof resolvePatchPath !== "function") throw new Error("PackyCode search composition requires resolvePatchPath");
+	if (typeof readBaseConfig !== "function") throw new Error("PackyCode search composition requires readBaseConfig");
+	let chain = Promise.resolve();
+	const serialized = (run) => {
+		const next = chain.then(() => runExclusive(run));
+		chain = next.then(() => void 0, () => void 0);
+		return next;
+	};
+	const load = async () => {
+		const path = await resolvePatchPath();
+		if (typeof path !== "string" || path === "") throw new Error("PackyCode web search could not find the profile patch file");
+		let content = "";
+		try {
+			content = await fs.readFile(path, "utf8");
+		} catch (error) {
+			if (error?.code !== "ENOENT") throw error;
+		}
+		const eol = content.includes("\r\n") ? "\r\n" : "\n";
+		const lines = content === "" ? [] : content.split(/\r?\n/u);
+		if (lines.length > 0 && lines.at(-1) === "") lines.pop();
+		return {
+			path,
+			content,
+			eol,
+			lines
+		};
+	};
+	const render = ({ eol }, lines) => lines.length === 0 ? "" : `${lines.join(eol)}${eol}`;
+	const save = async (file, lines) => {
+		const next = render(file, lines);
+		if (next === file.content) return false;
+		const temporary = `${file.path}.packycode-api.tmp`;
+		await fs.writeFile(temporary, next, { mode: 384 });
+		await fs.rename(temporary, file.path);
+		return true;
+	};
+	/** The file with this plugin's entry pointing at `providerId`. */
+	const applied = (file, providerId) => {
+		const found = locate(file.lines);
+		assertBlockSequence(found === void 0 ? file.lines : [...file.lines.slice(0, found.start), ...file.lines.slice(found.end)]);
+		const base = readBaseConfig() ?? {};
+		const fallback = found?.fallback !== void 0 ? usableFallback(found.fallback) : usableFallback(base.searchProvider);
+		const entry = entryLines(providerId, fallback, base);
+		if (found !== void 0) {
+			const before = file.lines.slice(0, found.start).filter((line) => !isEnd(line));
+			const after = file.lines.slice(found.end).filter((line) => !isEnd(line));
+			while (after.length > 0 && after.at(-1).trim() === "") after.pop();
+			return {
+				fallback,
+				lines: [
+					...before,
+					...entry,
+					...after
+				]
+			};
+		}
+		const lines = file.lines.filter((line) => !EMPTY_LIST.test(line) && !isEnd(line));
+		while (lines.length > 0 && lines.at(-1).trim() === "") lines.pop();
+		return {
+			fallback,
+			lines: [...lines, ...entry]
+		};
+	};
+	/** The file without this plugin's entry, or undefined when it holds none. */
+	const removed = (file) => {
+		if (locate(file.lines) === void 0 && !file.lines.some(isEnd)) return void 0;
+		const lines = strip(file.lines);
+		while (lines.length > 0 && lines.at(-1).trim() === "") lines.pop();
+		if (!lines.some((line) => LIST_ITEM.test(line)) && !lines.some((line) => EMPTY_LIST.test(line))) lines.push("[]");
+		return lines;
+	};
+	return Object.freeze({
+		/** The entry as the file holds it now. */
+		async read() {
+			const { lines } = await load();
+			const found = locate(lines);
+			return found === void 0 ? { present: false } : {
+				present: true,
+				provider: found.provider,
+				fallback: usableFallback(found.fallback)
+			};
+		},
+		/**
+		* Point the base search provider at `providerId`, keeping the recorded
+		* fallback when the entry already exists.
+		* @returns whether the file changed, and the fallback the entry records.
+		*/
+		async apply(providerId) {
+			if (!OWN_SEARCH_PROVIDER_IDS.includes(providerId)) throw new Error(`PackyCode web search cannot select "${String(providerId)}"`);
+			const current = await load();
+			const planned = applied(current, providerId);
+			if (render(current, planned.lines) === current.content) return {
+				changed: false,
+				fallback: planned.fallback
+			};
+			return serialized(async () => {
+				const file = await load();
+				const next = applied(file, providerId);
+				return {
+					changed: await save(file, next.lines),
+					fallback: next.fallback
+				};
+			});
+		},
+		/** Remove the entry, leaving an empty list when nothing else remains. */
+		async remove() {
+			if (removed(await load()) === void 0) return { changed: false };
+			return serialized(async () => {
+				const file = await load();
+				const lines = removed(file);
+				return { changed: lines === void 0 ? false : await save(file, lines) };
+			});
+		}
+	});
+}
+/**
+* Run `operation` inside DSH's reload transaction, so a patch write never
+* overlaps a profile reload or a settings write. A reconcile started from
+* inside one of those (a web restart during a reload, a volatile update
+* during a settings write) inherits its context, and DSH refuses to nest the
+* transaction; that one runs unlocked, after the transaction that started it.
+* @param hmr - DSH's `hmr` service, when the host has one.
+* @param operation - the write.
+* @returns the operation's result.
+*/
+async function runInReloadTransaction(hmr, operation) {
+	if (typeof hmr?.runExclusive !== "function") return operation();
+	let started = false;
+	try {
+		return await hmr.runExclusive(() => {
+			started = true;
+			return operation();
+		});
+	} catch (error) {
+		if (!started && /cannot be nested/u.test(error?.message ?? "")) return operation();
+		throw error;
+	}
+}
+/**
+* The composition for the profile this plugin runs in.
+* @param options - the plugin context (for `profileContext` and `hmr`), the
+*   web row's Loader entry, and where to look for the owning profile when the
+*   host does not name its patch file.
+* @returns the composition.
+*/
+function createProfileSearchComposition({ ctx, webEntry, dshHome, ownPackageJsonUrl }) {
+	return createSearchComposition({
+		resolvePatchPath: async () => {
+			const profile = ctx.get?.("profileContext");
+			if (typeof profile?.patchPath === "string" && profile.patchPath !== "") return profile.patchPath;
+			const install = await findInstall({
+				dshHome,
+				ownPackageJsonUrl
+			});
+			return install.profile === void 0 ? void 0 : join(dshHome, "profiles", install.profile, SEARCH_PATCH_FILE);
+		},
+		readBaseConfig: () => webEntry()?.options?.config ?? {},
+		runExclusive: (operation) => runInReloadTransaction(ctx.get?.("hmr"), operation)
+	});
+}
+//#endregion
+//#region src/search-controller.js
+/**
+* Web search wiring: the two search providers, the user's routing and backend
+* preference, the profile-patch entry that makes DSH reach them, and the
+* projection the settings panel reads.
+*
+* @module dsh-packycode-api/search-controller
+*/
+/** Routers other subscription plugins register; shown so the user knows who holds the slot. */
+const FOREIGN_ROUTERS = Object.freeze({
+	codex: "codex-subscription-auto",
+	kimi: "kimi-subscription-auto"
+});
+/** Normalize a stored preference; anything unknown reads as the default. */
+function readSearchChoice(value) {
+	return {
+		mode: SEARCH_MODES.includes(value?.searchProvider) ? value.searchProvider : SEARCH_MODE_DEFAULT,
+		backend: SEARCH_BACKENDS.includes(value?.searchBackend) ? value.searchBackend : DEFAULT_SEARCH_BACKEND
+	};
+}
+/** Only sentences this plugin wrote reach the browser. */
+function safeMessage(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return /^PackyCode /u.test(message) ? message.slice(0, 240) : "PackyCode web search could not update the profile patch";
+}
+/**
+* @param options - the key ring and hosts the search runs with, the key-failure
+*   sink and group coverage shared with the model route, the preference reader
+*   and writer, the initiating session's provider and id, the web row's Loader
+*   entry, the profile-patch composition, a logger, and an optional fetch.
+*/
+function createSearchController({ ring, hosts, onKeyFailure, covers, readPreference, writePreference, isWritable = () => typeof writePreference === "function", resolveModelProvider, resolveSessionId, webEntry = () => void 0, composition, logger, fetchImpl }) {
+	let web;
+	let fallbackId;
+	let applied = { state: "idle" };
+	let chain = Promise.resolve();
+	const preference = () => readSearchChoice(readPreference?.());
+	const packycode = createPackyCodeSearchProvider({
+		ring,
+		hosts,
+		backend: () => preference().backend,
+		onKeyFailure,
+		covers,
+		resolveSessionId,
+		...fetchImpl === void 0 ? {} : { fetchImpl }
+	});
+	const auto = createPackyCodeAutoSearchProvider({
+		packycode,
+		resolveModelProvider,
+		resolveProvider: (id) => web?.searchProviders?.get?.(id),
+		resolveFallbackId: () => fallbackId ?? usableFallback(webEntry()?.options?.config?.searchProvider)
+	});
+	/** Make the profile patch match the preference; serialized, idempotent. */
+	const reconcile = () => {
+		const run = async () => {
+			if (web === void 0 || composition === void 0) {
+				applied = { state: "unavailable" };
+				return;
+			}
+			const { mode } = preference();
+			try {
+				if (mode === "default") {
+					await composition.remove();
+					fallbackId = void 0;
+					applied = { state: "removed" };
+				} else {
+					const outcome = await composition.apply(mode === "auto" ? PACKYCODE_AUTO_SEARCH_PROVIDER_ID : PACKYCODE_SEARCH_PROVIDER_ID);
+					fallbackId = outcome.fallback;
+					applied = {
+						state: "applied",
+						fallback: outcome.fallback
+					};
+				}
+			} catch (error) {
+				applied = {
+					state: "failed",
+					error: safeMessage(error)
+				};
+				logger?.warn?.("packycode-api: could not apply the web search selection: %s", error?.message ?? String(error));
+			}
+		};
+		const next = chain.then(run);
+		chain = next.then(() => void 0, () => void 0);
+		return next;
+	};
+	const status = () => {
+		const { mode, backend } = preference();
+		const entry = webEntry();
+		const base = entry?.options?.config?.searchProvider;
+		const runtime = entry?.fiber?.config?.searchProvider;
+		return {
+			searchProvider: mode,
+			searchBackend: backend,
+			writable: isWritable() === true,
+			available: web !== void 0,
+			models: { ...SEARCH_BACKEND_MODELS },
+			effective: {
+				...typeof base === "string" ? { base } : {},
+				...typeof runtime === "string" ? { runtime } : {}
+			},
+			applied: { ...applied },
+			foreign: Object.fromEntries(Object.entries(FOREIGN_ROUTERS).map(([name, id]) => [name, web?.searchProviders?.has?.(id) === true]))
+		};
+	};
+	return Object.freeze({
+		packycode,
+		auto,
+		/**
+		* Register both providers with the web service and reconcile once.
+		* @param service - the `web` service, as the inject scope hands it over.
+		* @param effect - that scope's effect registrar.
+		*/
+		register(service, effect) {
+			effect(() => {
+				web = service;
+				const disposePackycode = service.registerSearchProvider(packycode);
+				const disposeAuto = service.registerSearchProvider(auto);
+				return () => {
+					disposeAuto?.();
+					disposePackycode?.();
+					if (web === service) web = void 0;
+				};
+			}, "packycode-api: web search providers");
+			reconcile();
+		},
+		reconcile,
+		status,
+		/** Validate, persist, and apply a preference change. */
+		async update(patch) {
+			const next = {};
+			if (patch?.searchProvider !== void 0) {
+				if (!SEARCH_MODES.includes(patch.searchProvider)) throw new Error("That PackyCode search option is not supported");
+				next.searchProvider = patch.searchProvider;
+			}
+			if (patch?.searchBackend !== void 0) {
+				if (!SEARCH_BACKENDS.includes(patch.searchBackend)) throw new Error("That PackyCode search backend is not supported");
+				next.searchBackend = patch.searchBackend;
+			}
+			if (Object.keys(next).length === 0) return status();
+			if (isWritable() !== true || typeof writePreference !== "function") throw new Error("PackyCode settings are not writable in this profile");
+			try {
+				await writePreference(next);
+			} catch (error) {
+				logger?.warn?.("packycode-api: could not save the web search preference: %s", error?.message ?? String(error));
+				throw new Error("PackyCode could not save the web search preference", { cause: error });
+			}
+			await reconcile();
+			return status();
+		}
+	});
+}
+//#endregion
+//#region src/index.js
+/**
+* dsh-packycode-api — a self-contained PackyCode route for DeepSeek Harness.
+*
+* The plugin builds its own pi-ai provider, model catalog, key ring, balance
+* and group readers, then registers the route through the same public
+* `llm.registerAdapter` API the shipped adapters use. Nothing here reads the
+* profile's composition config, so installing the package is the whole setup:
+* the picker shows the models and the user only pastes API keys.
+*
+* This module only composes; each concern lives in its own module.
+*
+* @module dsh-packycode-api
+*/
+const name = PLUGIN_ID;
+/**
+* Only the model route is mandatory. `settings`, `web`, `connection`, and
+* `tools` are requested through `ctx.inject`: a profile without them (a
+* headless run, for one) must still boot with a working route instead of
+* blocking on a service it will never see.
+*/
+const inject = ["llm", "credentials"];
+/** The model a CLI run without one is matched against for its key's groups. */
+const CLI_GROUP_MODEL = "claude-opus-5-5";
+/** Host overrides and preferences; a profile that never sets them keeps the defaults. */
+const Config = z.object({
+	apiHost: z.string().default(DEFAULT_API_HOST),
+	statusHost: z.string().default(DEFAULT_STATUS_HOST),
+	/** Path to the Claude Code CLI binary; empty means "look in the usual places, then PATH". */
+	claudeCliPath: z.string().default(""),
+	/**
+	* What the CLI may do on its own during a CLI-backed turn. `auto` follows the
+	* session's permission preset, so nothing needs configuring here.
+	*/
+	claudeCliMode: z.union([
+		AUTO_CLAUDE_MODE,
+		"read-only",
+		"edit",
+		"full"
+	]).default(AUTO_CLAUDE_MODE),
+	/** Working directory for CLI-backed turns; empty means "the session's workspace". */
+	claudeCliCwd: z.string().default(""),
+	/**
+	* Web search routing: `default` leaves DSH's search alone, `auto` searches
+	* through PackyCode for PackyCode sessions only, `packycode` for every
+	* request DSH's own search would have served.
+	*/
+	searchProvider: live(z.union([...SEARCH_MODES]).default(SEARCH_MODE_DEFAULT)),
+	/** Which PackyCode model runs a search: `deepseek` or `gpt`. */
+	searchBackend: live(z.union([...SEARCH_BACKENDS]).default(DEFAULT_SEARCH_BACKEND))
+});
+function apply(ctx, config) {
+	const ring = new PackyCodeKeyRing(ctx.credentials);
 	let source = () => ({
 		apiHost: normalizeHost(config?.apiHost, DEFAULT_API_HOST),
-		statusHost: normalizeHost(config?.statusHost, DEFAULT_STATUS_HOST)
+		statusHost: normalizeHost(config?.statusHost, DEFAULT_STATUS_HOST),
+		searchProvider: fieldValue(config?.searchProvider),
+		searchBackend: fieldValue(config?.searchBackend)
 	});
 	const hosts = () => {
 		const current = source() ?? {};
@@ -3575,69 +5348,63 @@ function apply(ctx, config) {
 		};
 	};
 	const balance = createBalanceReader({
-		...balanceReaderOptions,
 		listKeys: () => ring.secrets(),
 		getHosts: hosts
 	});
-	const onKeyFailure = (kind, _message, key) => {
-		const id = key === void 0 ? void 0 : idByKey.get(key);
-		if (id === void 0) {
-			ctx.logger?.warn?.("packycode-api: %s reported for an unidentified key; not rotating", kind);
+	/**
+	* Which token groups each key is in, and so which models it can reach.
+	* Nothing reads it at boot: the settings panel asks for it, and a request
+	* with a choice of keys waits briefly for the first reading.
+	*/
+	const groups = createGroupReader({
+		listKeys: () => ring.secrets(),
+		getHosts: hosts
+	});
+	const keys = createKeyChooser({
+		ring,
+		groups,
+		logger: ctx.logger,
+		onRotated: () => balance.invalidate()
+	});
+	/** The session of the agent this turn runs for, when one is in scope. */
+	const currentSession = () => {
+		try {
+			return ctx.get?.("agents")?.currentInitiator?.()?.session;
+		} catch {
 			return;
 		}
-		ctx.logger?.warn?.("packycode-api: %s on key %s; the next key serves the retry", kind, id);
-		ring.disable(id, kind).then(() => balance.invalidate()).catch((error) => ctx.logger?.warn?.("packycode-api: could not move past key %s: %s", id, error.message));
 	};
-	const raw = createPackyCodeProvider();
-	/**
-	* The gateway's Codex-group check refuses a Responses request that carries no
-	* `prompt_cache_key` with a 403, which pi-ai derives from the session id. The
-	* harness supplies one for every agent turn; this fallback covers a caller
-	* that does not, so the route never fails for a missing cache key.
-	*/
-	const fallbackSessionId = `${PLUGIN_ID}-${randomUUID()}`;
-	const withSessionId = (options) => options === void 0 || options.sessionId !== void 0 ? options : {
-		...options,
-		sessionId: fallbackSessionId
+	/** One Loader entry by row id, or undefined outside a Loader composition. */
+	const loaderEntry = (id) => {
+		try {
+			return [...ctx.get?.("loader")?.entries?.() ?? []].find((entry) => entry?.options?.id === id);
+		} catch {
+			return;
+		}
 	};
-	const profile = createPackyCodeProfile(Object.freeze({
-		...raw,
-		stream: (model, context, options) => guardKeyRotation(raw.stream(model, context, withSessionId(options)), {
-			key: options?.apiKey,
-			onKeyFailure
-		}),
-		streamSimple: (model, context, options) => guardKeyRotation(raw.streamSimple(model, context, withSessionId(options)), {
-			key: options?.apiKey,
-			onKeyFailure
-		})
-	}));
-	const profiles = /* @__PURE__ */ new Map([[PROVIDER, profile]]);
+	const fallbackSessionId = `${PLUGIN_ID}-${randomUUID()}`;
+	const attachments = () => ctx.get?.("attachments") ?? ctx.attachments;
 	/**
-	* The Claude Code CLI runner. PackyCode's `cc` group serves its Claude
-	* models only to the official CLI, so CLI-backed models below are run by
-	* that CLI itself — with this plugin's endpoint and key, in an isolated
-	* config home.
+	* The Claude Code CLI runner. PackyCode serves its Claude models only to the
+	* official CLI, so CLI-backed models are run by that CLI itself — with this
+	* plugin's endpoint and a ring key, in an isolated config home. Each run
+	* uses the active key unless its groups cannot reach the run's Claude model
+	* and another stored key's can, and reports which key it used by label.
 	*/
 	const claudeCli = createClaudeCliManager({ explicitPath: () => config?.claudeCliPath });
 	const claudeRunner = createClaudeRunner({
 		binary: () => claudeCli.binary(),
-		resolveCredential: async () => {
-			const active = await ring.activeKey();
-			if (active === void 0) throw new Error("Claude Code CLI needs a usable PackyCode API key; add one under Settings → PackyCode");
+		resolveCredential: async ({ model } = {}) => {
+			const choice = await keys.forRun(PACKYCODE_MODEL_IDS.includes(model) ? model : CLI_GROUP_MODEL);
+			if (choice === void 0) throw new Error("Claude Code CLI needs a usable PackyCode API key; add one under Settings → PackyCode");
+			const { key, ...described } = choice;
 			return {
+				...described,
 				baseUrl: hosts().apiHost,
-				token: active.key
+				token: key
 			};
 		}
 	});
-	/** The session of the agent this turn runs for, when one is in scope. */
-	const currentSession = () => {
-		try {
-			return ctx.get?.("agents")?.currentInitiator?.()?.session;
-		} catch {
-			return;
-		}
-	};
 	/** The session's own workspace, so a CLI turn edits the project in view. */
 	const resolveCliCwd = () => {
 		const configured = typeof config?.claudeCliCwd === "string" ? config.claudeCliCwd.trim() : "";
@@ -3649,76 +5416,102 @@ function apply(ctx, config) {
 	* The most a CLI turn may do: an explicit setting when the profile names
 	* one, otherwise what the session's permission preset allows.
 	*/
-	const configuredCliMode = () => {
+	const cliModeCeiling = (session) => {
 		const configured = config?.claudeCliMode;
-		return configured === void 0 || configured === "auto" ? void 0 : configured;
+		return configured === void 0 || configured === "auto" ? claudeModeForSession(ctx, session) : configured;
 	};
-	const cliModeCeiling = (session) => configuredCliMode() ?? claudeModeForSession(ctx, session);
-	const resolveCliMode = () => cliModeCeiling(currentSession()) ?? "edit";
-	/**
-	* Dispatch per model: CLI-backed ids run the Claude Code CLI, everything
-	* else keeps the pi-ai path.
-	*/
-	const adapter = createClaudeCliAdapter({
-		inner: new PiAiAdapter({
-			profiles: () => profiles,
-			resolveApiKey: async () => {
-				await rememberKeys();
-				const active = await ring.activeKey();
-				if (active === void 0) throw new LlmError("No usable PackyCode API key: add one under Settings → PackyCode, or re-enable the keys this plugin moved past.", "MISSING_CREDENTIAL");
-				return active.key;
-			},
-			auth: Object.freeze({
-				credentials: ringCredentialStore(ring),
-				authContext: Object.freeze({
-					env: async () => void 0,
-					fileExists: async () => false
-				})
-			}),
-			resolveAttachments: () => ctx.get?.("attachments") ?? ctx.attachments
+	ctx.llm.registerAdapter([PROVIDER], createClaudeCliAdapter({
+		inner: createRouteAdapter({
+			ring,
+			keys,
+			fallbackSessionId,
+			resolveAttachments: attachments
 		}),
 		runner: claudeRunner,
-		resolveMode: resolveCliMode,
+		resolveMode: () => cliModeCeiling(currentSession()) ?? "edit",
 		resolveCwd: resolveCliCwd,
-		resolveAttachments: () => ctx.get?.("attachments") ?? ctx.attachments
-	});
-	ctx.llm.registerAdapter([PROVIDER], adapter);
+		resolveAttachments: attachments,
+		explainKey: (runKey) => keys.describe(runKey)
+	}));
 	ctx.llm.registerConfigurableProviders([{
 		provider: PROVIDER,
 		displayName: DISPLAY_NAME,
 		settingsNs: SETTINGS_NAMESPACE,
 		settingsPath: []
 	}]);
-	const preference = {
+	const hostPreference = unwritable("PackyCode host overrides are not writable in this profile");
+	const searchPreference = {
 		writable: false,
-		set: async () => {
-			throw new Error("PackyCode host overrides are not writable in this profile");
-		}
+		set: void 0
 	};
-	ctx.inject(["settings"], (settingsCtx) => {
-		try {
-			settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, Config, source(), {
-				setSource: (current) => {
-					source = typeof current === "function" ? () => current() ?? {} : () => current ?? {};
-				},
-				onChange: () => balance.invalidate()
-			});
-			if (typeof settingsCtx.settings.update === "function") {
-				preference.writable = true;
-				preference.set = (patch) => settingsCtx.settings.update(SETTINGS_NAMESPACE, patch);
+	const dshHome = typeof process.env.DSH_HOME === "string" && process.env.DSH_HOME !== "" ? process.env.DSH_HOME : join(homedir(), ".dsh");
+	const search = createSearchController({
+		ring,
+		hosts,
+		onKeyFailure: keys.onKeyFailure,
+		covers: keys.covers,
+		readPreference: () => source() ?? {},
+		writePreference: (patch) => searchPreference.set(patch),
+		isWritable: () => searchPreference.writable === true && typeof searchPreference.set === "function",
+		resolveModelProvider: () => {
+			try {
+				return currentSession()?.requestContext?.()?.provider;
+			} catch {
+				return;
 			}
-		} catch (error) {
-			ctx.logger?.warn?.("packycode-api: host overrides unavailable, defaults stand: %s", error.message);
-		}
+		},
+		resolveSessionId: () => {
+			const id = currentSession()?.id;
+			return typeof id === "string" && id !== "" ? id : fallbackSessionId;
+		},
+		webEntry: () => loaderEntry("web"),
+		composition: createProfileSearchComposition({
+			ctx,
+			webEntry: () => loaderEntry("web"),
+			dshHome,
+			ownPackageJsonUrl: new URL("../package.json", import.meta.url)
+		}),
+		logger: ctx.logger
+	});
+	ctx.inject(["settings"], (settingsCtx) => connectSettings(settingsCtx, {
+		ctx,
+		Config,
+		namespace: SETTINGS_NAMESPACE,
+		source: () => source(),
+		setSource: (next) => {
+			source = next;
+		},
+		onChange: () => {
+			balance.invalidate();
+			groups.invalidate();
+			search.reconcile();
+		},
+		hostPreference,
+		searchPreference
+	}));
+	ctx.on?.("loader/volatile-update", () => {
+		search.reconcile();
+	});
+	/**
+	* Both search providers register with the web service whenever one exists.
+	* Registration alone changes nothing; the preference decides whether the
+	* profile patch points DSH at them.
+	*/
+	ctx.inject(["web"], (webCtx) => {
+		if (typeof webCtx.web?.registerSearchProvider !== "function") return;
+		const scope = typeof webCtx.effect === "function" ? webCtx : ctx;
+		search.register(webCtx.web, (callback, label) => scope.effect(callback, label));
 	});
-	rememberKeys().catch(() => void 0);
+	keys.remember().catch(() => void 0);
 	const handler = createPackyCodeRpc({
 		ring,
 		balance,
+		groups,
 		hosts,
-		preference,
+		preference: hostPreference,
 		claudeCli,
-		pluginManager: createPackyCodePluginManager()
+		pluginManager: createPackyCodePluginManager(),
+		search
 	});
 	/**
 	* Connection registers a channel through `owner.webServer`, read on its own
@@ -3731,82 +5524,12 @@ function apply(ctx, config) {
 	ctx.inject(["connection", "webServer"], (connectionCtx) => {
 		ctx.effect(() => connectionCtx.connection.rpc.handle(CHANNEL, handler), "packycode-api: loopback account RPC");
 	});
-	/**
-	* The explicit delegation tool, for asking Claude Code for something while
-	* another model drives the session. It shares the runner the CLI-backed
-	* models use.
-	*/
 	ctx.inject(["tools"], (toolsCtx) => {
-		ctx.effect(() => toolsCtx.tools.register(defineTool({
-			name: "claude_code",
-			description: "Delegate a task to the local Claude Code CLI (the official `claude` binary), which runs it with its own tools and returns its final answer. Use it when the user asks for Claude or when a task suits Claude Code. The child runs with this plugin's PackyCode endpoint and API key, in an isolated config home. `mode` bounds what it may do on its own: \"read-only\" (Read/Grep/Glob), \"edit\" (also Edit/Write), \"full\" (bypasses the CLI's permission checks, including shell commands); it defaults to, and is capped at, what this session's permission preset allows. It starts a fresh CLI session per call, takes tens of seconds, and bills through the same PackyCode key. Its internal tool calls are not part of this session's transcript — only the returned answer is.",
-			parameters: {
-				prompt: {
-					type: "string",
-					required: true,
-					description: "The task for Claude Code, written as a self-contained instruction (it does not see this conversation)."
-				},
-				mode: {
-					type: "string",
-					enum: Object.keys(CLAUDE_CLI_MODES),
-					description: "What the CLI may do on its own. Defaults to the most this session's permission preset allows; a wider mode is capped to it. Ask for \"full\" only when the task genuinely needs shell commands."
-				},
-				model: {
-					type: "string",
-					description: "Model id passed to the CLI (for example \"claude-opus-5-5\", \"claude-sonnet-5-5\", or \"claude-haiku-5-5\"). Omit to use the CLI's own default."
-				},
-				cwd: {
-					type: "string",
-					description: "Working directory for the CLI. Defaults to this session's workspace; a relative path resolves against it."
-				}
-			},
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: {
-						result: {
-							type: "string",
-							required: true
-						},
-						model: {
-							type: "string",
-							required: true
-						},
-						mode: {
-							type: "string",
-							required: true
-						},
-						costUsd: {
-							type: "number",
-							required: true
-						},
-						durationMs: {
-							type: "number",
-							required: true
-						}
-					}
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: `${value.result}\n\n— Claude Code CLI · ${value.model || "default model"} · ${value.mode} · ${Math.round(value.durationMs / 1e3)}s · $${value.costUsd.toFixed(4)}`
-				}]
-			},
-			async execute(args, exec) {
-				const sessionCwd = exec?.agent?.session?.header?.cwd;
-				const requested = typeof args.cwd === "string" ? args.cwd.trim() : "";
-				const cwd = requested === "" ? sessionCwd : isAbsolute(requested) ? requested : sessionCwd === void 0 ? requested : join(sessionCwd, requested);
-				return await claudeRunner.run({
-					prompt: args.prompt,
-					mode: capClaudeMode(args.mode, cliModeCeiling(exec?.agent?.session)) ?? "edit",
-					model: args.model,
-					appendSystemPrompt: CLAUDE_TOOL_INSTRUCTIONS,
-					cwd,
-					signal: exec?.signal
-				});
-			}
+		ctx.effect(() => toolsCtx.tools.register(createClaudeCodeTool({
+			runner: claudeRunner,
+			modeCeiling: cliModeCeiling
 		})), "packycode-api: claude_code tool");
 	});
 }
 //#endregion
-export { AUTO_CLAUDE_MODE, CHANNEL, CLAUDE_CLI_MODES, CLAUDE_INSTALL_COMMAND, CLAUDE_MISSING_MESSAGE, CLAUDE_NPM_PACKAGE, CLI_BACKED_MODEL_IDS, CLI_IMAGE_LIMITS, Config, DEFAULT_API_HOST, DEFAULT_APPEND_SYSTEM_PROMPT, DEFAULT_STATUS_HOST, DISPLAY_NAME, LEGACY_STATUS_HOSTS, PACKYCODE_MODELS, PACKYCODE_MODEL_IDS, PLUGIN_ID, PROVIDER, PackyCodeKeyRing, SETTINGS_NAMESPACE, TITLE_MODEL_ID, TITLE_MODEL_ROUTES, accountHostOrder, apply, assertApiKey, buildClaudeArgs, buildClaudeEnvironment, buildClaudeInput, buildDelegatedContent, capClaudeMode, classifyClientPolicy, classifyGatewayFailure, claudeBinaryCandidates, claudeModeFor, claudeModeForSession, createBalanceReader, createClaudeCliAdapter, createClaudeCliManager, createClaudeRunner, createPackyCodeProfile, createPackyCodeProvider, createPackyCodeRpc, delegationInstructions, explainCliClientPolicyFailure, explainClientPolicyFailure, explainNpmFailure, findClaudeBinary, guardKeyRotation, inject, locateClaudeBinary, locateNpm, name, normalizeFailureMessage, normalizeHost, npmCandidates, parseBillingSubscription, parseBillingUsage, parseClaudeResult, parseClaudeVersion, parseTokenUsage, readClaudeStreamEvents, renderAuxiliaryPrompt, renderDelegatedPrompt, resolveSpawnCommand, statusHostOrder, summarizeToolUse };
+export { AUTO_CLAUDE_MODE, CHANNEL, CLAUDE_CLI_MODES, CLAUDE_INSTALL_COMMAND, CLAUDE_MISSING_MESSAGE, CLAUDE_NPM_PACKAGE, CLAUDE_TOOL_INSTRUCTIONS, CLI_BACKED_MODEL_IDS, CLI_IMAGE_LIMITS, Config, DEFAULT_API_HOST, DEFAULT_APPEND_SYSTEM_PROMPT, DEFAULT_SEARCH_BACKEND, DEFAULT_STATUS_HOST, DISPLAY_NAME, LEGACY_STATUS_HOSTS, PACKYCODE_AUTO_SEARCH_PROVIDER_ID, PACKYCODE_MODELS, PACKYCODE_MODEL_IDS, PACKYCODE_SEARCH_PROVIDER_ID, PLUGIN_ID, PROVIDER, PackyCodeKeyRing, SEARCH_BACKENDS, SEARCH_BACKEND_MODELS, SEARCH_MODES, SETTINGS_NAMESPACE, TITLE_MODEL_ID, TITLE_MODEL_ROUTES, accountHostOrder, apply, assertApiKey, buildClaudeArgs, buildClaudeEnvironment, buildClaudeInput, buildDelegatedContent, buildSearchRequest, capClaudeMode, catalogCoverage, classifyClientPolicy, classifyGatewayFailure, claudeBinaryCandidates, claudeModeFor, claudeModeForSession, createBalanceReader, createClaudeCliAdapter, createClaudeCliManager, createClaudeCodeTool, createClaudeRunner, createGroupReader, createKeyChooser, createPackyCodeAutoSearchProvider, createPackyCodeProfile, createPackyCodeProvider, createPackyCodeRpc, createPackyCodeSearchProvider, createProfileSearchComposition, createRouteAdapter, createSearchComposition, createSearchController, delegationInstructions, describeRunKey, explainCliClientPolicyFailure, explainCliGroupFailure, explainClientPolicyFailure, explainNpmFailure, findClaudeBinary, guardKeyRotation, inject, keyNote, locateClaudeBinary, locateNpm, name, normalizeFailureMessage, normalizeHost, npmCandidates, parseBillingSubscription, parseBillingUsage, parseClaudeResult, parseClaudeVersion, parseMessagesSearchResponse, parsePricing, parseResponsesSearchResponse, parseSelectedGroups, parseTokenUsage, pickKeyForModel, readClaudeStreamEvents, readSearchChoice, renderAuxiliaryPrompt, renderDelegatedPrompt, resolveSpawnCommand, statusHostOrder, summarizeToolUse };