dsh-web-search-enhanced 0.2.0 → 0.2.2

package/lib/index.js

@@ -1,13 +1,15 @@
 import { WebError } from "@deepseek-ai/dsh-web";
 import z from "@deepseek-ai/schemastery";
+import { createTypertRemoteInfo } from "@deepseek-ai/dsh-typert-protocol/remote-info";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { Remote, RemoteError, TypertRemoteService, remoteErrorOf } from "@deepseek-ai/dsh-typert-protocol";
-import { createTypertRemoteInfo } from "@deepseek-ai/dsh-typert-protocol/remote-info";
 import { scopeOf } from "@deepseek-ai/dsh-scope";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { DEEPSEEK_DEFAULT_API_VERSION, DEEPSEEK_DEFAULT_BASE_URL, DEEPSEEK_DEFAULT_MAX_TOKENS, DEEPSEEK_DEFAULT_MAX_USES, DEEPSEEK_DEFAULT_MODEL, DeepSeekSearchProvider } from "@deepseek-ai/dsh-web-search-deepseek";
 import { DEEPSEEK_DEFAULT_COUNT, DEEPSEEK_WEB_API_BASE_URL, DeepSeekSearchApiProvider } from "@deepseek-ai/dsh-web-deepseek-api";
+import { WEB_SEARCH_MAX_QUERIES, WEB_SEARCH_MAX_RESULTS, formatSearchOutput, searchMetaFromValue } from "@deepseek-ai/dsh-tool-web";
+import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -241,8 +243,8 @@ function runAdapter(io, wire, target, input, signal) {
 async function adapterCredential(io, ref, signal) {
 	try {
 		return await io.errors.abortable(io.credential(ref), signal);
-	} catch (error) {
-		if (error instanceof WebError) throw error;
+	} catch {
+		io.errors.throwIfAborted(signal);
 		throw new Error("Adapter credential resolution failed");
 	}
 }
@@ -14146,6 +14148,10 @@ const TEXT_MAX_LENGTH = 2e3;
 const BUILTIN_PREFIX = "builtin:";
 /** Operator-defined connection ids: `custom:` plus a short, readable name. */
 const CUSTOM_CONNECTION_ID = /^custom:[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/u;
+/** Catalog connection ids: `builtin:` plus a lower-case, hyphenated catalog key. */
+const BUILTIN_CONNECTION_ID = /^builtin:[a-z0-9]{1,50}(?:-[a-z0-9]{1,50}){0,5}$/u;
+/** Whether a string, such as an untrusted tool argument, has the grammar of a connection id; it may still name nothing. */
+const isConnectionId = (value) => BUILTIN_CONNECTION_ID.test(value) || CUSTOM_CONNECTION_ID.test(value);
 /** A DSH Credentials reference, the only form a key is ever stored in. */
 const CREDENTIAL_REF = /^[A-Za-z_][A-Za-z0-9_]*$/u;
 const builtinId = (key) => `${BUILTIN_PREFIX}${key}`;
@@ -14196,6 +14202,7 @@ const SETTINGS_FIELDS = [
 	"version",
 	"defaultConnection",
 	"showSelector",
+	"enhancedTools",
 	"defaults",
 	"connections"
 ];
@@ -14238,16 +14245,25 @@ function migrateDocument(document, migrations = SETTINGS_MIGRATIONS) {
 	}
 	return result;
 }
-const text$2 = string$1().trim().min(1).max(TEXT_MAX_LENGTH);
-const label = string$1().trim().min(1).max(200);
-const credentialRef$1 = text$2.regex(CREDENTIAL_REF, "must be a credential reference such as EXA_API_KEY");
-const endpoint = text$2.refine(isEndpoint, "must be an absolute http(s) URL without credentials, query or fragment");
+/**
+* Operator text shown as one line (a label in menus, error messages and the
+* Agent's provider list): control characters and line or paragraph separators
+* become spaces, runs of whitespace one space, the ends trimmed.
+*/
+function singleLine(value) {
+	return value.replaceAll(/[\p{Cc}\p{Zl}\p{Zp}]/gu, " ").replaceAll(/\s+/gu, " ").trim();
+}
+const text$3 = string$1().trim().min(1).max(TEXT_MAX_LENGTH);
+const label = string$1().transform(singleLine).pipe(string$1().min(1).max(200));
+const credentialRef$1 = text$3.regex(CREDENTIAL_REF, "must be a credential reference such as EXA_API_KEY");
+const endpoint = text$3.refine(isEndpoint, "must be an absolute http(s) URL without credentials, query or fragment");
 const options = record(string$1(), unknown());
 function documentSchema(defaults, currentVersion = 2) {
 	return strictObject({
 		version: literal(currentVersion).optional(),
 		defaultConnection: string$1().min(1).max(200).optional(),
 		showSelector: boolean$1().optional(),
+		enhancedTools: boolean$1().optional(),
 		defaults: defaults.optional(),
 		connections: record(string$1().max(200), unknown()).refine((value) => Object.keys(value).length <= 200, "must contain at most 200 connections").optional()
 	});
@@ -14309,7 +14325,7 @@ function resolveDocument({ catalog, document, defaults, capabilityLabel, protoco
 	const customSchema = customConnectionSchema(adapterKeys, protocolKeys);
 	const connections = /* @__PURE__ */ new Map();
 	const rejectId = (id, path) => fail(path, "unknown connection id \"" + id + "\"; this release does not read 0.1.x settings; remove the field or use Reset on the settings page");
-	const resolve = (id, key, override, customEndpoint) => {
+	const resolve = (id, key, override, origin) => {
 		const info = catalog[key];
 		const path = "connections." + id;
 		const access = info.kind === "model" ? "api-key" : override.access ?? defaultAccess(info.access);
@@ -14321,11 +14337,12 @@ function resolveDocument({ catalog, document, defaults, capabilityLabel, protoco
 		if (problems.length > 0) fail(path + ".options", problems.join("; ") + "; this release does not read 0.1.x settings; remove the field or use Reset on the settings page");
 		const trustedEndpoint = override.trustedEndpoint ?? false;
 		for (const [name, rule] of Object.entries(info.options)) if (rule.kind === "url" && values[name] !== void 0 && values[name] !== info.endpoint && !trustedEndpoint) fail(path + ".trustedEndpoint", "a non-official " + name + " needs trustedEndpoint: true");
+		const disabled = override.disabled ?? (origin.kind === "builtin" ? info.optIn : false);
 		const base = {
 			id,
 			catalogKey: key,
 			label: override.label ?? info.label,
-			disabled: override.disabled ?? false,
+			disabled,
 			remote: info.remote,
 			trustedEndpoint,
 			options: values
@@ -14342,7 +14359,7 @@ function resolveDocument({ catalog, document, defaults, capabilityLabel, protoco
 		};
 		if (info.kind !== "native" && info.kind !== "adapter") return fail(path + ".kind", "unsupported catalog kind");
 		if (!info.access.apiKey || info.endpoint === void 0) return fail(path, "remote catalog entry needs credentials and an endpoint");
-		const url = customEndpoint ?? info.endpoint;
+		const url = origin.kind === "custom" && origin.endpoint !== void 0 ? origin.endpoint : info.endpoint;
 		if (url !== info.endpoint && !trustedEndpoint) fail(path + ".trustedEndpoint", "a custom endpoint needs trustedEndpoint: true");
 		return {
 			...base,
@@ -14363,7 +14380,7 @@ function resolveDocument({ catalog, document, defaults, capabilityLabel, protoco
 			]) if (Object.hasOwn(raw, field)) fail("connections." + id + "." + field, "this connection takes its route from the Session model");
 		}
 		const override = raw === void 0 ? {} : parse(builtinOverrideSchema, raw, "connections." + id);
-		connections.set(id, resolve(id, key, override));
+		connections.set(id, resolve(id, key, override, { kind: "builtin" }));
 	}
 	for (const [id, raw] of Object.entries(overrides)) {
 		if (connections.has(id)) continue;
@@ -14373,7 +14390,10 @@ function resolveDocument({ catalog, document, defaults, capabilityLabel, protoco
 		if (custom.kind === "adapter") connections.set(id, resolve(id, custom.adapter, {
 			...custom,
 			access: "api-key"
-		}, custom.endpoint));
+		}, {
+			kind: "custom",
+			endpoint: custom.endpoint
+		}));
 		else {
 			const info = protocols[custom.protocol];
 			const values = custom.options ?? {};
@@ -14404,6 +14424,7 @@ function resolveDocument({ catalog, document, defaults, capabilityLabel, protoco
 		version: migrations.currentVersion,
 		defaultConnection,
 		showSelector: settings.showSelector ?? true,
+		enhancedTools: settings.enhancedTools ?? false,
 		defaults: settings.defaults ?? parse(defaults.schema, {}, "defaults"),
 		connections
 	};
@@ -14650,175 +14671,17 @@ function toolJson(value) {
 		throw error;
 	}
 }
-function nextModel(ctx, agent) {
-	const pending = ctx.get("sessionProjections")?.stateOf(agent.session, "modelSelection")?.pending;
-	if (pending !== void 0 && pending !== null) return complete(pending);
-	const request = agent.session.requestHeader();
-	return complete(request === void 0 ? agent.options : request.config);
-}
-function complete(value) {
-	if (!value.provider || !value.model) return void 0;
-	return {
-		provider: value.provider,
-		model: value.model
-	};
-}
-/** The resolved route used for native account authentication; pending choices do not authenticate. */
-function requestModel(agent) {
-	const request = agent.session.requestContext();
-	return request === void 0 ? void 0 : complete(request);
-}
-//#endregion
-//#region ../core/src/host/credentials.ts
-/** Credentials is authoritative; absence does not fall back to process.env. */
-async function resolveApiKey(ctx, ref) {
-	const credentials = ctx.get("credentials");
-	if (credentials === void 0) return void 0;
-	const found = await credentials.resolve(credentialRef(ref));
-	return found === void 0 ? void 0 : found.value;
-}
-/** Route authentication retains DSH's launch-plane fallback only when Credentials is absent. */
-async function routeApiKey(ctx, ref) {
-	if (ctx.get("credentials") !== void 0) return resolveApiKey(ctx, ref);
-	const ambient = launchEnvironmentOf(ctx).get(credentialRef(ref));
-	return ambient !== void 0 && ambient.value.length > 0 ? ambient.value : void 0;
-}
-/** Readiness follows the same source boundary as routeApiKey, without resolving secrets. */
-async function routeKeyConfigured(ctx, ref, source) {
-	const credentials = ctx.get("credentials");
-	if (credentials !== void 0) return (await credentials.describe(credentialRef(ref))).configured;
-	if (source === "credentials") return false;
-	const ambient = launchEnvironmentOf(ctx).get(credentialRef(ref));
-	return ambient !== void 0 && ambient.value.length > 0;
-}
-/** Native providers use the same credential source as DSH model routes. */
-function nativeAuth(ctx, ref, secrets = /* @__PURE__ */ new Set()) {
-	const apiKeyEnv = credentialRef(ref);
-	let resolverFailed = false;
-	const tracked = async (resolve) => {
-		try {
-			const value = await resolve();
-			if (value !== void 0) secrets.add(value);
-			return value;
-		} catch {
-			resolverFailed = true;
-			throw new Error("Native credential resolution failed");
-		}
-	};
-	return {
-		apiKeyEnv,
-		secrets,
-		resolverFailed: () => resolverFailed,
-		resolveAccountToken: (endpoint) => tracked(async () => {
-			const resolve = accountTokenFor(ctx, ctx.get("agents")?.currentInitiator());
-			return resolve === void 0 ? void 0 : await resolve(endpoint);
-		}),
-		resolveApiKey: () => tracked(() => routeApiKey(ctx, ref))
-	};
-}
-/** Account readiness uses the next selected model, while request authentication uses its frozen route. */
-async function credentialReadiness(ctx, agent, options) {
-	const account = options.endpoint !== void 0 && nextModel(ctx, agent)?.provider === "deepseek-account" ? ctx.get("deepseekAccount") : void 0;
-	if (account !== void 0 && await account.resolveToken(options.endpoint) !== void 0) return {
-		access: "account",
-		status: "ready"
-	};
-	const credentials = ctx.get("credentials");
-	return {
-		access: "api-key",
-		status: (credentials === void 0 ? void 0 : await credentials.describe(credentialRef(options.credentialRef)))?.configured === true ? "ready" : "needs-credential"
-	};
-}
-/** Account tokens are available only on a resolved deepseek-account request route. */
-function accountTokenFor(ctx, agent) {
-	if (agent === void 0 || requestModel(agent)?.provider !== "deepseek-account") return void 0;
-	const account = ctx.get("deepseekAccount");
-	return account === void 0 ? void 0 : (endpoint) => account.resolveToken(endpoint);
-}
-//#endregion
-//#region ../core/src/host/pairings.ts
-const keyOf = ({ provider, model }) => JSON.stringify([provider, model]);
-const modelKey = tuple([string$1(), string$1()]);
-var Pairings = class {
-	storage;
-	constructor(storage) {
-		this.storage = storage;
-	}
-	async get(model) {
-		const record = (await this.storage.domain()).table("pairings").get(keyOf(model));
-		return record === void 0 ? void 0 : record.connectionId;
-	}
-	async set(model, connectionId) {
-		await (await this.storage.domain()).table("pairings").put(keyOf(model), { connectionId });
-	}
-	async list() {
-		return [...(await this.storage.domain()).table("pairings").entries()].map(([key, value]) => {
-			const [provider, model] = modelKey.parse(JSON.parse(key));
-			return {
-				provider,
-				model,
-				connectionId: value.connectionId
-			};
-		});
-	}
-	async forget(model) {
-		await (await this.storage.domain()).table("pairings").delete(keyOf(model));
-	}
-};
-//#endregion
-//#region ../core/src/host/plans.ts
-function planFor(selection) {
-	const { connectionId, options } = selection;
-	if (connectionId === null) return { kind: "off" };
-	return {
-		kind: "ready",
-		connectionId,
-		options: structuredClone(options)
-	};
-}
-/** Concurrent capture is shared; only failed captures may retry in the same step. */
-var Snapshots = class {
-	steps = /* @__PURE__ */ new WeakMap();
-	capture(agent, turn, step, plan) {
-		const previous = this.steps.get(agent);
-		if (previous !== void 0 && previous.turn === turn && previous.step === step) {
-			if (previous.kind === "capturing") return previous.pending;
-			if (previous.plan.kind !== "failed") return Promise.resolve();
-		}
-		const pending = plan().then((result) => {
-			if (this.steps.get(agent) === snapshot) this.steps.set(agent, {
-				turn,
-				step,
-				kind: "captured",
-				plan: result
-			});
-		}, (error) => {
-			if (this.steps.get(agent) === snapshot) this.steps.delete(agent);
-			throw error;
-		});
-		const snapshot = {
-			turn,
-			step,
-			kind: "capturing",
-			pending
-		};
-		this.steps.set(agent, snapshot);
-		return pending;
-	}
-	get(agent) {
-		const snapshot = this.steps.get(agent);
-		return snapshot?.kind === "captured" ? snapshot.plan : void 0;
-	}
-	forget(agent) {
-		this.steps.delete(agent);
-	}
-};
 //#endregion
 //#region ../core/src/shared/ids.ts
 const SEARCH = {
 	packageName: "dsh-web-search-enhanced",
 	rowId: "web-search-enhanced",
-	providerId: "search-enhanced"
+	providerId: "search-enhanced",
+	tools: {
+		action: "web_search_enhanced",
+		list: "list_web_search_providers"
+	},
+	command: "setup-search"
 };
 //#endregion
 //#region ../core/src/shared/route.ts
@@ -15002,48 +14865,560 @@ function selectionContract(spec) {
 	};
 }
 //#endregion
-//#region ../core/src/host/selectable.ts
-/** One eligibility rule for memories, Remote changes, plans and per-call policy. */
-function isSelectable(connection) {
-	return connection !== void 0 && !connection.disabled;
+//#region ../core/src/host/enhanced-parts/wording.ts
+/** Why an id the operator added after the conversation started is unknown here (the list is fixed per conversation). */
+const LATER_PROVIDERS = ". Providers added or turned on after this conversation started are available only in new conversations.";
+/** At most this many ready ids are named in one message; the list tool shows the rest. */
+const READY_SHOWN = 20;
+/**
+* The tail of a message naming the ready providers the Agent can switch to:
+* `ready providers: <ids>` without `except`, at most twenty in list order, or
+* `no other provider is ready` in place of the whole clause. When readiness could
+* not be read, the list tool is named instead, so "none" is never claimed unread.
+*/
+function readyClause(voice, ready, except) {
+	if (ready.kind === "unread") return `${voice.identity.tools.list} shows the ready providers`;
+	const others = ready.ids.filter((id) => id !== except);
+	if (others.length === 0) return "no other provider is ready";
+	const hidden = others.length - READY_SHOWN;
+	const more = hidden > 0 ? ` and ${hidden} more (${voice.identity.tools.list})` : "";
+	return `ready providers: ${others.slice(0, READY_SHOWN).join(", ")}${more}`;
+}
+/** Word a refusal core reported before any backend ran; `unavailable` passes core's own error on unchanged. */
+function rejectionError(voice, reason) {
+	const { error } = capabilityErrors(voice.identity.packageName);
+	switch (reason.kind) {
+		case "unknown": return error("WEB_PROVIDER_CONFIGURED_MISSING", `unknown provider "${reason.connectionId}"; ${readyClause(voice, reason.ready, reason.connectionId)}${LATER_PROVIDERS}`);
+		case "removed": return error("WEB_PROVIDER_CONFIGURED_MISSING", `provider "${reason.connectionId}" was removed by the user; ${readyClause(voice, reason.ready, reason.connectionId)}`);
+		case "off": return error("WEB_PROVIDER_UNAVAILABLE", `${voice.capability} is off for this session; only the user can turn it back on (composer menu). Do not retry.`);
+		case "withdrawn": return error("WEB_PROVIDER_UNAVAILABLE", `${voice.identity.tools.action} is unavailable now; use ${voice.nativeTool}.`);
+		case "unavailable": return reason.error;
+	}
+}
+/**
+* Point a backend failure at the list tool: the hint ends the first paragraph,
+* before any untrusted upstream explanation, after a full stop when that paragraph
+* has no sentence end; the code and the rest of the message stay as the execution
+* layer wrote them. Cancellation, and failures `unhinted` marks, pass on unchanged.
+*/
+function providerFailure(voice, cause, connectionId, unhinted) {
+	if (!(cause instanceof WebError) || cause.code === "WEB_ABORTED" || unhinted(cause)) return cause;
+	const hint = ` Provider "${connectionId}" failed; ${voice.identity.tools.list} shows the others.`;
+	const end = cause.message.indexOf("\n\n");
+	const first = end === -1 ? cause.message : cause.message.slice(0, end);
+	const rest = end === -1 ? "" : cause.message.slice(end);
+	const stop = /[.!?]$/u.test(first) ? "" : ".";
+	return new WebError(first + stop + hint + rest, cause.code);
+}
+/** An argument error in DSH's own form, without the package prefix. */
+function invalidArguments(problem) {
+	return /* @__PURE__ */ new Error(`invalid arguments: ${problem}`);
+}
+/** DSH accepts extra properties on the open argument root; the enhanced tools refuse them without echoing the name. */
+function rejectUnknownProperties(args, known) {
+	if (Object.keys(args).some((key) => !known.includes(key))) throw invalidArguments("unknown property");
+}
+/** The caller DSH reports for this execution; a call without an Agent never falls back to a default connection. */
+function explicitCall(tool, exec) {
+	if (exec.agent === void 0) throw new Error(`${tool} can only be called by an Agent`);
+	return {
+		agent: exec.agent,
+		signal: exec.signal
+	};
+}
+/**
+* The model's `provider` argument, once it has the grammar of a connection id.
+* A malformed value is never echoed; the error names the ready providers instead.
+*/
+async function providerArgument(voice, value, access, call) {
+	if (value.length > 0 && value.length <= 128 && isConnectionId(value)) return value;
+	throw invalidArguments(`provider must be an id such as builtin:<key> or custom:<name>; ${readyClause(voice, await access.ready(call))}`);
+}
+/**
+* Run one request on the named provider: a refusal is worded for the model,
+* a backend failure gets the switch-provider hint (docs/design.md, "增强工具的错误").
+*/
+async function runOnProvider(voice, access, connectionId, request, call, unhinted = () => false) {
+	let outcome;
+	try {
+		outcome = await access.run(connectionId, request, call);
+	} catch (cause) {
+		throw providerFailure(voice, cause, connectionId, unhinted);
+	}
+	if (outcome.kind === "rejected") throw rejectionError(voice, outcome.reason);
+	return outcome.value;
 }
 //#endregion
-//#region ../core/src/host/sessions.ts
-var SelectionConflict = class extends Error {
-	constructor() {
-		super("the selection changed since it was read");
+//#region ../core/src/host/enhanced-parts/listing.ts
+/** The recipient `sendsTo` names for fetch `local`; the text says `fetches from this machine`. */
+const THIS_MACHINE = "this machine";
+const SESSION_MODEL = "the service behind the session model";
+const HOST_MAX = 253;
+/** Why the session model cannot search, in English; the execution layer's error and the listing share it. */
+const UNSUPPORTED_REASON_TEXT = {
+	"no-model": "no session model is available",
+	"unknown-route": "the model route is unknown",
+	protocol: "the route does not declare a supported protocol",
+	endpoint: "the route has no supported endpoint",
+	headers: "the route uses custom request headers",
+	credential: "the route has no supported credential reference"
+};
+const text$2 = {
+	type: "string",
+	required: true
+};
+function entrySchema(extra) {
+	const common = {
+		id: text$2,
+		name: text$2,
+		use: { type: "string" },
+		sendsTo: text$2,
+		...extra
+	};
+	return { oneOf: [
+		{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				...common,
+				status: {
+					type: "string",
+					required: true,
+					const: "ready"
+				}
+			}
+		},
+		{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				...common,
+				status: {
+					type: "string",
+					required: true,
+					const: "needs-key"
+				}
+			}
+		},
+		{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				...common,
+				status: {
+					type: "string",
+					required: true,
+					const: "needs-sign-in"
+				}
+			}
+		},
+		{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				...common,
+				status: {
+					type: "string",
+					required: true,
+					const: "unavailable"
+				},
+				reason: text$2
+			}
+		}
+	] };
+}
+const session = {
+	sessionProvider: text$2,
+	sessionProviderTurnedOff: {
+		type: "boolean",
+		required: true
 	}
 };
-var Sessions = class {
-	ctx;
-	settings;
-	storage;
-	pairings;
-	restriction;
-	describe;
-	queues = /* @__PURE__ */ new Map();
-	constructor(ctx, settings, storage, pairings, restriction, describe = async () => []) {
-		this.ctx = ctx;
-		this.settings = settings;
-		this.storage = storage;
-		this.pairings = pairings;
-		this.restriction = restriction;
-		this.describe = describe;
+function searchListingSchema() {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...session,
+			freshness: {
+				type: "string",
+				required: true,
+				enum: FRESHNESS
+			},
+			providers: {
+				type: "array",
+				required: true,
+				items: entrySchema({ appliesFreshness: {
+					type: "boolean",
+					required: true
+				} })
+			}
+		}
+	};
+}
+/** This conversation's providers, or the worded refusal. */
+async function listProviders(voice, access, call) {
+	const outcome = await access.list(call);
+	if (outcome.kind === "rejected") throw rejectionError(voice, outcome.reason);
+	return outcome.value;
+}
+function searchListingValue(listing) {
+	return {
+		...sessionOf(listing),
+		freshness: listing.options.freshness,
+		providers: listing.providers.map((entry) => ({
+			...listedBase(entry),
+			appliesFreshness: entry.facts.appliesFreshness === true,
+			...readiness(entry)
+		}))
+	};
+}
+/** One line per provider, `<id> — <name> · …`, without a heading (docs/design.md, "列出工具"). */
+function renderSearchListing(voice, value) {
+	const uncached = value.freshness !== "auto";
+	return renderLines(voice, value, uncached ? ["The user asked for uncached (fresh) page content; only providers marked \"uncached\" apply it."] : [], {
+		marks: (entry) => uncached && entry.appliesFreshness ? ["uncached"] : [],
+		notes: () => []
+	});
+}
+function renderLines(voice, value, head, parts) {
+	const entries = value.providers.map((entry) => {
+		const line = [statusText$1(entry)];
+		if (entry.id === value.sessionProvider) line.push("selected for this session");
+		if (entry.use !== void 0) line.push(entry.use);
+		line.push(...parts.marks(entry));
+		if (entry.sendsTo === "this machine") line.push("fetches from this machine");
+		else if (entry.sendsTo !== entry.name) line.push(`${voice.sends} go to ${entry.sendsTo}`);
+		line.push(...parts.notes(entry));
+		return `${entry.id} — ${entry.name} · ${line.join(" · ")}`;
+	});
+	const tail = value.sessionProviderTurnedOff ? [`This session's selection, ${value.sessionProvider}, is turned off; ${voice.nativeTool} will fail until the user changes it.`] : [];
+	return [
+		...head,
+		...entries.length === 0 ? ["(no providers)"] : entries,
+		...tail
+	].join("\n");
+}
+function statusText$1(entry) {
+	switch (entry.status) {
+		case "ready": return "ready";
+		case "needs-key": return "needs an API key (ask the user)";
+		case "needs-sign-in": return "needs the user to sign in to DeepSeek again";
+		case "unavailable": return `unavailable: ${entry.reason}`;
 	}
-	current(agent) {
-		return this.exclusive(agent.session.id, async () => this.read(agent, await this.table()));
+}
+function sessionOf(listing) {
+	return {
+		sessionProvider: listing.session.connectionId,
+		sessionProviderTurnedOff: !listing.session.selectable
+	};
+}
+function listedBase(entry) {
+	const { use, recipient } = entry.facts;
+	return {
+		id: entry.id,
+		name: oneLine(entry.name, 200),
+		...use === void 0 ? {} : { use },
+		sendsTo: recipientText(recipient)
+	};
+}
+function recipientText(recipient) {
+	switch (recipient.kind) {
+		case "this-machine": return THIS_MACHINE;
+		case "session-model": return recipient.provider === void 0 ? SESSION_MODEL : `${SESSION_MODEL} (${oneLine(recipient.provider, 200)})`;
+		case "service": return recipient.host === void 0 ? oneLine(recipient.service, 200) : oneLine(recipient.host, HOST_MAX);
+	}
+}
+function readiness(entry) {
+	switch (entry.status) {
+		case "ready": return { status: "ready" };
+		case "needs-credential": return { status: entry.credential === "account" ? "needs-sign-in" : "needs-key" };
+		case "unsupported": return {
+			status: "unavailable",
+			reason: UNSUPPORTED_REASON_TEXT[entry.reason]
+		};
+	}
+}
+/** Collapse line breaks, controls and runs of white space, then cut at `max` characters without splitting a surrogate pair. */
+function oneLine(value, max) {
+	const flat = value.replace(/[\p{Cc}\p{Zl}\p{Zp}\s]+/gu, " ").trim();
+	if (flat.length <= max) return flat;
+	const last = flat.charCodeAt(max - 2);
+	return flat.slice(0, last >= 55296 && last <= 56319 ? max - 2 : max - 1) + "…";
+}
+function nextModel(ctx, agent) {
+	const pending = ctx.get("sessionProjections")?.stateOf(agent.session, "modelSelection")?.pending;
+	if (pending !== void 0 && pending !== null) return complete(pending);
+	const request = agent.session.requestHeader();
+	return complete(request === void 0 ? agent.options : request.config);
+}
+function complete(value) {
+	if (!value.provider || !value.model) return void 0;
+	return {
+		provider: value.provider,
+		model: value.model
+	};
+}
+/** The resolved route used for native account authentication; pending choices do not authenticate. */
+function requestModel(agent) {
+	const request = agent.session.requestContext();
+	return request === void 0 ? void 0 : complete(request);
+}
+//#endregion
+//#region ../core/src/host/credentials.ts
+/** Credentials is authoritative; absence does not fall back to process.env. */
+async function resolveApiKey(ctx, ref) {
+	const credentials = ctx.get("credentials");
+	if (credentials === void 0) return void 0;
+	const found = await credentials.resolve(credentialRef(ref));
+	return found === void 0 ? void 0 : found.value;
+}
+/** Route authentication retains DSH's launch-plane fallback only when Credentials is absent. */
+async function routeApiKey(ctx, ref) {
+	if (ctx.get("credentials") !== void 0) return resolveApiKey(ctx, ref);
+	const ambient = launchEnvironmentOf(ctx).get(credentialRef(ref));
+	return ambient !== void 0 && ambient.value.length > 0 ? ambient.value : void 0;
+}
+/** Readiness follows the same source boundary as routeApiKey, without resolving secrets. */
+async function routeKeyConfigured(ctx, ref, source) {
+	const credentials = ctx.get("credentials");
+	if (credentials !== void 0) return (await credentials.describe(credentialRef(ref))).configured;
+	if (source === "credentials") return false;
+	const ambient = launchEnvironmentOf(ctx).get(credentialRef(ref));
+	return ambient !== void 0 && ambient.value.length > 0;
+}
+/** Native providers use the same credential source as DSH model routes. */
+function nativeAuth(ctx, ref, secrets = /* @__PURE__ */ new Set()) {
+	const apiKeyEnv = credentialRef(ref);
+	let resolverFailed = false;
+	const tracked = async (resolve) => {
+		try {
+			const value = await resolve();
+			if (value !== void 0) secrets.add(value);
+			return value;
+		} catch {
+			resolverFailed = true;
+			throw new Error("Native credential resolution failed");
+		}
+	};
+	return {
+		apiKeyEnv,
+		secrets,
+		resolverFailed: () => resolverFailed,
+		resolveAccountToken: (endpoint) => tracked(async () => {
+			const resolve = accountTokenFor(ctx, ctx.get("agents")?.currentInitiator());
+			return resolve === void 0 ? void 0 : await resolve(endpoint);
+		}),
+		resolveApiKey: () => tracked(() => routeApiKey(ctx, ref))
+	};
+}
+/** Account readiness uses the next selected model, while request authentication uses its frozen route. */
+async function credentialReadiness(ctx, model, options) {
+	const account = options.endpoint !== void 0 && model?.provider === "deepseek-account" ? ctx.get("deepseekAccount") : void 0;
+	if (account !== void 0 && await account.resolveToken(options.endpoint) !== void 0) return {
+		access: "account",
+		status: "ready"
+	};
+	const credentials = ctx.get("credentials");
+	return {
+		access: "api-key",
+		status: (credentials === void 0 ? void 0 : await credentials.describe(credentialRef(options.credentialRef)))?.configured === true ? "ready" : "needs-credential"
+	};
+}
+/** Account tokens are available only on a resolved deepseek-account request route. */
+function accountTokenFor(ctx, agent) {
+	if (agent === void 0 || requestModel(agent)?.provider !== "deepseek-account") return void 0;
+	const account = ctx.get("deepseekAccount");
+	return account === void 0 ? void 0 : (endpoint) => account.resolveToken(endpoint);
+}
+//#endregion
+//#region ../core/src/host/pairings.ts
+const keyOf = ({ provider, model }) => JSON.stringify([provider, model]);
+const modelKey = tuple([string$1(), string$1()]);
+var Pairings = class {
+	storage;
+	constructor(storage) {
+		this.storage = storage;
+	}
+	async get(model) {
+		const record = (await this.storage.domain()).table("pairings").get(keyOf(model));
+		return record === void 0 ? void 0 : record.connectionId;
+	}
+	async set(model, connectionId) {
+		await (await this.storage.domain()).table("pairings").put(keyOf(model), { connectionId });
+	}
+	async list() {
+		return [...(await this.storage.domain()).table("pairings").entries()].map(([key, value]) => {
+			const [provider, model] = modelKey.parse(JSON.parse(key));
+			return {
+				provider,
+				model,
+				connectionId: value.connectionId
+			};
+		});
+	}
+	async forget(model) {
+		await (await this.storage.domain()).table("pairings").delete(keyOf(model));
+	}
+};
+//#endregion
+//#region ../core/src/host/plans.ts
+function planFor(selection) {
+	const { connectionId, options } = selection;
+	if (connectionId === null) return { kind: "off" };
+	return {
+		kind: "ready",
+		connectionId,
+		options: structuredClone(options)
+	};
+}
+/** Concurrent capture is shared; only failed captures may retry in the same step. */
+var Snapshots = class {
+	steps = /* @__PURE__ */ new WeakMap();
+	capture(agent, turn, step, plan) {
+		const previous = this.steps.get(agent);
+		if (previous !== void 0 && previous.turn === turn && previous.step === step) {
+			if (previous.kind === "capturing") return previous.pending;
+			if (previous.plan.kind !== "failed") return Promise.resolve();
+		}
+		const pending = plan().then((result) => {
+			if (this.steps.get(agent) === snapshot) this.steps.set(agent, {
+				turn,
+				step,
+				kind: "captured",
+				plan: result
+			});
+		}, (error) => {
+			if (this.steps.get(agent) === snapshot) this.steps.delete(agent);
+			throw error;
+		});
+		const snapshot = {
+			turn,
+			step,
+			kind: "capturing",
+			pending
+		};
+		this.steps.set(agent, snapshot);
+		return pending;
+	}
+	get(agent) {
+		const snapshot = this.steps.get(agent);
+		return snapshot?.kind === "captured" ? snapshot.plan : void 0;
+	}
+	forget(agent) {
+		this.steps.delete(agent);
+	}
+};
+//#endregion
+//#region ../core/src/host/session-origin.ts
+function sessionOrigin(header) {
+	const { parentSession: parent, isSeeded: seeded, origin } = header;
+	if (origin === "subagent") return {
+		kind: "subagent",
+		parent,
+		seeded
+	};
+	return parent === void 0 ? {
+		kind: "top-level",
+		seeded
+	} : {
+		kind: "fork",
+		parent,
+		seeded
+	};
+}
+function parentOf(origin) {
+	return origin.kind === "top-level" ? void 0 : origin.parent;
+}
+//#endregion
+//#region ../core/src/host/provider-lists.ts
+/** Live setup/created events do not make a new conversation a restored one. */
+function isNewConversation(session) {
+	const origin = sessionOrigin(session.header);
+	return parentOf(origin) === void 0 && !origin.seeded && session.firstLiveSeq === 0 && session.firstLifecycleSeq === 0;
+}
+/** Immutable conversation authorization, sharing the selection queue and storage lifetime. */
+var ProviderLists = class {
+	storage;
+	constructor(storage) {
+		this.storage = storage;
+	}
+	read(agent) {
+		return this.storage.exclusive(agent.session.id, async () => {
+			const table = (await this.storage.domain()).table("provider_lists");
+			return this.nonempty(table.get(agent.session.id));
+		});
+	}
+	create(agent, initial) {
+		return this.storage.exclusive(agent.session.id, async () => {
+			const table = (await this.storage.domain()).table("provider_lists");
+			const stored = table.get(agent.session.id);
+			if (stored !== void 0) return this.nonempty(stored);
+			const parent = parentOf(sessionOrigin(agent.session.header));
+			let ids;
+			if (parent !== void 0) {
+				await this.storage.settled(parent);
+				ids = table.get(parent);
+			} else ids = initial;
+			if (ids === void 0) return void 0;
+			await table.put(agent.session.id, [...ids]);
+			return this.nonempty(ids);
+		});
+	}
+	nonempty(ids) {
+		return ids === void 0 || ids.length === 0 ? void 0 : [...ids];
+	}
+};
+//#endregion
+//#region ../core/src/host/selectable.ts
+/** One eligibility rule for memories, Remote changes, plans and per-call policy. */
+function isSelectable(connection) {
+	return connection !== void 0 && !connection.disabled;
+}
+//#endregion
+//#region ../core/src/host/sessions.ts
+function liveSession(agent) {
+	return {
+		kind: "live",
+		id: agent.session.id,
+		header: agent.session.header,
+		agent
+	};
+}
+var SelectionConflict = class extends Error {
+	constructor() {
+		super("the selection changed since it was read");
+	}
+};
+var Sessions = class {
+	ctx;
+	settings;
+	storage;
+	pairings;
+	restriction;
+	describe;
+	constructor(ctx, settings, storage, pairings, restriction, describe = async () => []) {
+		this.ctx = ctx;
+		this.settings = settings;
+		this.storage = storage;
+		this.pairings = pairings;
+		this.restriction = restriction;
+		this.describe = describe;
+	}
+	current(target) {
+		return this.exclusive(target.id, async () => this.read(target, await this.table()));
 	}
 	/** Resolve visibility without creating records or materializing inherited/default options. */
-	peek(agent) {
-		return this.exclusive(agent.session.id, async () => this.read(agent, await this.table(), false));
+	peek(target) {
+		return this.exclusive(target.id, async () => this.read(target, await this.table(), false));
 	}
-	change(agent, change, expectedRevision) {
-		return this.exclusive(agent.session.id, async () => {
+	change(target, change, expectedRevision) {
+		return this.exclusive(target.id, async () => {
 			const table = await this.table();
-			await this.read(agent, table);
+			await this.read(target, table);
 			const { connectionId, ...options } = change;
 			const record = this.storage.optionsCodec.toRecord(options);
-			const updated = await table.update(agent.session.id, (current) => {
+			const updated = await table.update(target.id, (current) => {
 				if (current.revision !== expectedRevision) throw new SelectionConflict();
 				return {
 					...current,
@@ -15052,9 +15427,10 @@ var Sessions = class {
 					revision: current.revision + 1
 				};
 			});
-			this.restriction.sync(agent, updated.connectionId);
-			if (connectionId !== void 0) {
-				const model = nextModel(this.ctx, agent);
+			const agent = this.ctx.get("agents")?.get(target.id);
+			if (agent !== void 0) this.restriction.sync(agent, updated.connectionId);
+			if (connectionId !== void 0 && sessionOrigin(target.header).kind !== "subagent") {
+				const model = this.model(target);
 				if (model !== void 0) {
 					const memory = await this.pairings.set(model, updated.connectionId).then(() => ({ kind: "stored" }), (error) => ({
 						kind: "failed",
@@ -15069,37 +15445,34 @@ var Sessions = class {
 			};
 		});
 	}
-	connections(agent) {
-		return this.describe(this.settings(), agent);
+	connections(target) {
+		return this.describe(this.settings(), this.model(target));
 	}
 	selectable(connectionId) {
 		return isSelectable(this.settings().connections.get(connectionId));
 	}
+	model(target) {
+		return target.kind === "live" ? nextModel(this.ctx, target.agent) : void 0;
+	}
 	async table() {
 		return (await this.storage.domain()).table("selections");
 	}
 	exclusive(id, work) {
-		const previous = this.queues.get(id);
-		const run = previous === void 0 ? work() : previous.then(work);
-		const tail = run.then(() => {}, () => {});
-		this.queues.set(id, tail);
-		tail.then(() => {
-			if (this.queues.get(id) === tail) this.queues.delete(id);
-		});
-		return run;
+		return this.storage.exclusive(id, work);
 	}
-	async read(agent, table, persist = true) {
+	async read(target, table, persist = true) {
 		const settings = this.settings();
 		const codec = this.storage.optionsCodec;
-		const id = agent.session.id;
+		const id = target.id;
 		let stored = table.get(id);
-		const { parentSession, isSeeded } = agent.session.header;
-		const seeded = parentSession !== void 0 && isSeeded;
+		const origin = sessionOrigin(target.header);
+		const parentSession = parentOf(origin);
+		const seeded = parentSession !== void 0 && origin.seeded;
 		let inherited = stored !== void 0 && seeded && (stored.inherited ?? table.get(parentSession) !== void 0);
 		if (stored === void 0 && seeded) {
 			const parentAgent = this.ctx.get("agents")?.get(parentSession);
-			if (parentAgent !== void 0 && persist) await this.current(parentAgent);
-			else await this.queues.get(parentSession);
+			if (parentAgent !== void 0 && persist) await this.current(liveSession(parentAgent));
+			else await this.storage.settled(parentSession);
 			const parent = table.get(parentSession);
 			if (parent !== void 0) {
 				stored = {
@@ -15122,7 +15495,7 @@ var Sessions = class {
 				source: next.revision > 0 ? "session" : "inherited"
 			};
 		}
-		const fallback = await this.defaultFor(agent, settings);
+		const fallback = await this.defaultFor(target, settings);
 		const options = stored === void 0 ? codec.initial(settings) : codec.fromRecord(stored, settings);
 		const next = {
 			...codec.toRecord(options),
@@ -15136,8 +15509,8 @@ var Sessions = class {
 			source: fallback.source
 		};
 	}
-	async defaultFor(agent, settings) {
-		const model = nextModel(this.ctx, agent);
+	async defaultFor(target, settings) {
+		const model = this.model(target);
 		const paired = model === void 0 ? void 0 : await this.pairings.get(model);
 		if (paired === null) return {
 			connectionId: null,
@@ -15164,6 +15537,24 @@ function sameRecord(left, right) {
 	return left !== void 0 && JSON.stringify(left) === JSON.stringify(right);
 }
 //#endregion
+//#region ../core/src/host/selection-write.ts
+/** The shared eligibility check and revisioned write for commands and Remote set. */
+async function writeSelection(sessions, target, change, expectedRevision) {
+	if (typeof change.connectionId === "string" && !sessions.selectable(change.connectionId)) return {
+		kind: "unavailable",
+		connectionId: change.connectionId
+	};
+	try {
+		return {
+			kind: "written",
+			current: await sessions.change(target, change, expectedRevision)
+		};
+	} catch (error) {
+		if (error instanceof SelectionConflict) return { kind: "conflict" };
+		throw error;
+	}
+}
+//#endregion
 //#region ../core/src/host/remote.ts
 var __runInitializers = function(thisArg, initializers, value) {
 	var useValue = arguments.length > 2;
@@ -15311,27 +15702,22 @@ function createConnectionsService(ctx, spec) {
 			async get(request) {
 				return boundary("get", async () => {
 					const { sessionId } = parse(selectionRequest, request);
-					const agent = await this.agent(sessionId);
-					return this.view(agent, await spec.sessions.current(agent));
+					const target = await this.target(sessionId);
+					return this.view(target, await spec.sessions.current(target));
 				});
 			}
 			async set(request) {
 				return boundary("set", async () => {
 					const { sessionId, connectionId, options, expectedRevision } = parse(spec.contract.selectionChange, request);
-					const agent = await this.agent(sessionId);
-					if (typeof connectionId === "string" && !spec.sessions.selectable(connectionId)) throw new RemoteError(spec.namespace + "/unavailable", "the connection is missing, disabled or unsupported", { connectionId });
-					let current;
-					try {
-						const change = {
-							...options,
-							...connectionId === void 0 ? {} : { connectionId }
-						};
-						current = await spec.sessions.change(agent, change, expectedRevision);
-					} catch (error) {
-						if (error instanceof SelectionConflict) throw new RemoteError(spec.namespace + "/conflict", "the selection changed elsewhere; re-read it and retry", {});
-						throw error;
-					}
-					return this.view(agent, current);
+					const target = await this.target(sessionId);
+					const change = {
+						...options,
+						...connectionId === void 0 ? {} : { connectionId }
+					};
+					const result = await writeSelection(spec.sessions, target, change, expectedRevision);
+					if (result.kind === "unavailable") throw new RemoteError(spec.namespace + "/unavailable", "the connection is missing, disabled or unsupported", { connectionId: result.connectionId });
+					if (result.kind === "conflict") throw new RemoteError(spec.namespace + "/conflict", "the selection changed elsewhere; re-read it and retry", {});
+					return this.view(target, result.current);
 				});
 			}
 			async provider(request) {
@@ -15353,15 +15739,27 @@ function createConnectionsService(ctx, spec) {
 					return { pairings: await spec.pairings.list() };
 				});
 			}
-			async agent(sessionId) {
-				const found = await this.ctx.sessionController.resolveAgent(sessionId);
+			async target(sessionId) {
+				const id = sessionId;
+				const agent = this.ctx.agents.get(id);
+				if (agent !== void 0) return liveSession(agent);
+				const persistence = this.ctx.get("sessionPersistence");
+				if (persistence !== void 0) {
+					const stored = await persistence.stat(id);
+					if (stored !== void 0 && sessionOrigin(stored.header).kind === "subagent") return {
+						kind: "cold",
+						id,
+						header: stored.header
+					};
+				}
+				const found = await this.ctx.sessionController.resolveAgent(id);
 				if ("error" in found) throw found.error;
-				return found.agent;
+				return liveSession(found.agent);
 			}
-			async view(agent, current) {
+			async view(target, current) {
 				return {
 					...current,
-					connections: await spec.sessions.connections(agent)
+					connections: await spec.sessions.connections(target)
 				};
 			}
 		};
@@ -15369,55 +15767,210 @@ function createConnectionsService(ctx, spec) {
 }
 //#endregion
 //#region ../core/src/host/restriction.ts
-/** An instance owns only its own restrictions; disposed work can never install new ones. */
+/** Owns registration and both masks, including their single ordered teardown. */
 var ToolRestriction = class {
+	ctx;
 	options;
 	lifts = /* @__PURE__ */ new Map();
+	enhancedLifts = /* @__PURE__ */ new Map();
 	known = /* @__PURE__ */ new Map();
+	states = /* @__PURE__ */ new Map();
 	forgotten = /* @__PURE__ */ new WeakSet();
+	removes = [];
+	definitions;
+	generation = 0;
 	disposed = false;
+	enhancedContext;
 	constructor(ctx, options) {
+		this.ctx = ctx;
 		this.options = options;
 		ctx.on("settings/document-updated", async (ns) => {
-			if (ns !== "web" || this.disposed) return;
-			const agents = [.../* @__PURE__ */ new Set([...this.known.keys(), ...this.lifts.keys()])];
-			const selection = options.routed() ? options.selection : void 0;
-			const results = await Promise.allSettled(agents.map(async (agent) => {
-				const connectionId = selection === void 0 ? this.known.get(agent) : await selection(agent);
-				if (connectionId !== void 0) this.sync(agent, connectionId);
-			}));
-			for (const result of results) if (result.status === "rejected") ctx.logger.warn("%s: refreshing tool restriction failed: %s", options.tool, result.reason);
+			if (this.disposed) return;
+			const enhanced = options.enhanced;
+			if (ns !== "web" && (enhanced === void 0 || ns !== enhanced.rowId)) return;
+			const newlyRegistered = this.reconcile();
+			const nativeAgents = ns === "web" ? [...this.known.keys()] : [];
+			if (!options.routed()) for (const agent of nativeAgents) this.native(agent, this.known.get(agent));
+			const agents = new Set(newlyRegistered);
+			if (this.registered) for (const agent of this.states.keys()) agents.add(agent);
+			if (options.routed()) for (const agent of nativeAgents) agents.add(agent);
+			await Promise.all([...agents].map((agent) => this.refresh(agent, nativeAgents.includes(agent))));
 		});
 		ctx.effect(() => () => {
 			this.disposed = true;
 			for (const lift of this.lifts.values()) lift();
 			this.lifts.clear();
 			this.known.clear();
-		}, options.tool + " tool restriction");
+			this.states.clear();
+		}, options.tool + " visibility");
 	}
 	get active() {
 		return !this.disposed;
 	}
+	get registered() {
+		return this.removes.length !== 0;
+	}
+	offered() {
+		return this.active && this.enhancedContext !== void 0 && this.options.routed() && this.options.enhanced !== void 0 && this.options.enhanced.enabled();
+	}
+	/** Call only after all runtime closures exist. Hot-start reads never create records. */
+	async start() {
+		if (this.options.enhanced === void 0) return;
+		await this.ctx.inject(["tools", "agents"], async (scope) => {
+			this.enhancedContext = scope;
+			scope.effect(() => () => {
+				this.withdraw();
+				this.enhancedContext = void 0;
+			}, this.options.tool + " enhanced visibility");
+			const agents = this.reconcile();
+			await Promise.all(agents.map((agent) => this.refresh(agent, false)));
+		});
+	}
+	created(agent) {
+		if (!this.active || this.forgotten.has(agent)) return;
+		this.states.set(agent, {
+			version: 0,
+			choice: "unknown",
+			providers: "unknown"
+		});
+		this.apply(agent);
+	}
+	begin(agent) {
+		const state = this.state(agent);
+		state.version++;
+		return {
+			generation: this.generation,
+			version: state.version
+		};
+	}
+	captured(agent, read, connectionId, providers) {
+		this.commit(agent, read, connectionId === null ? "off" : "on", this.providerState(providers), connectionId);
+	}
+	providerState(read) {
+		if (read.kind === "unread") return "unknown";
+		return read.ids === void 0 ? "absent" : "present";
+	}
+	failed(agent, read) {
+		this.commit(agent, read, "unknown", "unknown");
+	}
 	sync(agent, connectionId) {
-		if (this.disposed || this.forgotten.has(agent)) return;
-		this.known.set(agent, connectionId);
-		const lift = this.lifts.get(agent);
+		if (!this.active || this.forgotten.has(agent)) return;
+		const read = this.begin(agent);
+		this.commit(agent, read, connectionId === null ? "off" : "on", this.state(agent).providers, connectionId);
+	}
+	forget(agent) {
+		this.forgotten.add(agent);
+		this.known.delete(agent);
+		this.states.delete(agent);
+		this.lift(this.lifts, agent);
+		this.lift(this.enhancedLifts, agent);
+	}
+	state(agent) {
+		let state = this.states.get(agent);
+		if (state === void 0) {
+			state = {
+				version: 0,
+				choice: "unknown",
+				providers: "unknown"
+			};
+			this.states.set(agent, state);
+		}
+		return state;
+	}
+	reconcile() {
+		if (!this.offered()) {
+			if (this.registered) this.withdraw();
+			return [];
+		}
+		if (this.registered) return [];
+		const enhanced = this.options.enhanced;
+		if (this.definitions === void 0) this.definitions = enhanced.tools();
+		this.generation++;
+		const scope = this.enhancedContext;
+		const removes = [];
+		try {
+			removes.push(scope.tools.register(this.definitions.action));
+			removes.push(scope.tools.register(this.definitions.list));
+		} catch {
+			for (const remove of removes.toReversed()) remove();
+			this.ctx.logger.warn("%s: enhanced tool registration failed", this.options.tool);
+			return [];
+		}
+		this.removes = removes;
+		const agents = scope.agents.list();
+		for (const agent of agents) {
+			this.state(agent);
+			this.apply(agent);
+		}
+		return agents;
+	}
+	withdraw() {
+		this.generation++;
+		for (const remove of this.removes.splice(0)) remove();
+		for (const lift of this.enhancedLifts.values()) lift();
+		this.enhancedLifts.clear();
+	}
+	async refresh(agent, native) {
+		if (!this.active || this.forgotten.has(agent)) return;
+		const read = this.begin(agent);
+		try {
+			const selection = this.options.selection;
+			const connectionId = selection === void 0 ? this.known.get(agent) : await selection(agent);
+			if (connectionId === void 0) return;
+			const enhanced = this.options.enhanced;
+			let providers = { kind: "unread" };
+			if (this.registered && this.offered() && enhanced !== void 0) try {
+				providers = {
+					kind: "read",
+					ids: await enhanced.providers(agent)
+				};
+			} catch {
+				this.ctx.logger.warn("%s: conversation provider list could not be read", this.options.tool);
+			}
+			this.commit(agent, read, connectionId === null ? "off" : "on", this.providerState(providers), native ? connectionId : void 0);
+		} catch (error) {
+			this.failed(agent, read);
+			this.ctx.logger.warn("%s: refreshing tool restriction failed: %s", this.options.tool, error);
+		}
+	}
+	commit(agent, read, choice, providers, native) {
+		const state = this.states.get(agent);
+		if (!this.active || this.forgotten.has(agent) || state === void 0 || read.generation !== this.generation || read.version !== state.version) return;
+		if (this.registered && !this.offered()) {
+			this.withdraw();
+			return;
+		}
+		state.choice = choice;
+		state.providers = providers;
+		if (native !== void 0) {
+			this.known.set(agent, native);
+			this.native(agent, native);
+		}
+		this.apply(agent);
+	}
+	apply(agent) {
+		if (!this.registered) return;
+		const state = this.state(agent);
+		if (state.choice === "on" && state.providers === "present") this.lift(this.enhancedLifts, agent);
+		else if (!this.enhancedLifts.has(agent)) {
+			const names = this.options.enhanced.names;
+			this.enhancedLifts.set(agent, agent.ctx.tools.restrict({ deny: [names.action, names.list] }));
+		}
+	}
+	native(agent, connectionId) {
 		if (connectionId !== null || !this.options.routed()) {
-			this.lifts.delete(agent);
-			if (lift !== void 0) lift();
+			this.lift(this.lifts, agent);
 			return;
 		}
-		if (lift !== void 0) return;
+		if (this.lifts.has(agent)) return;
 		const tools = agent.ctx.get("tools");
 		const scope = scopeOf(agent.ctx);
 		if (scope === void 0 || tools === void 0 || tools.get(this.options.tool, scope) === void 0) return;
 		this.lifts.set(agent, tools.restrict({ deny: [this.options.tool] }));
 	}
-	forget(agent) {
-		this.forgotten.add(agent);
-		this.known.delete(agent);
-		const lift = this.lifts.get(agent);
-		this.lifts.delete(agent);
+	lift(lifts, agent) {
+		const lift = lifts.get(agent);
+		lifts.delete(agent);
 		if (lift !== void 0) lift();
 	}
 };
@@ -15438,6 +15991,207 @@ function routeFacts(ctx, field, providerId) {
 	return routeOf(value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0, field, environment(field), providerId);
 }
 //#endregion
+//#region ../core/src/host/explicit.ts
+const rejected = (reason) => ({
+	kind: "rejected",
+	reason
+});
+function explicitAccess(ctx, capability, runtime, errors, unavailable) {
+	const availabilityError = () => errors.error("WEB_PROVIDER_ERROR", "provider availability could not be read; retry the request");
+	const diagnostic = () => {
+		ctx.logger.warn("%s: provider availability could not be read", capability.identity.rowId);
+	};
+	function check() {
+		if (!runtime.active()) return rejected({
+			kind: "unavailable",
+			error: unavailable()
+		});
+		let settings;
+		try {
+			settings = capability.settings();
+		} catch (error) {
+			return rejected({
+				kind: "unavailable",
+				error: error instanceof WebError ? error : unavailable()
+			});
+		}
+		if (!runtime.offered()) return rejected({ kind: "withdrawn" });
+		return {
+			kind: "done",
+			value: settings
+		};
+	}
+	async function prepare(call) {
+		errors.throwIfAborted(call.signal);
+		const checked = check();
+		if (checked.kind === "rejected") return checked;
+		const plan = runtime.plan(call.agent);
+		if (plan === void 0) return rejected({
+			kind: "unavailable",
+			error: unavailable()
+		});
+		if (plan.kind === "failed") return rejected({
+			kind: "unavailable",
+			error: plan.error
+		});
+		if (plan.kind === "off") return rejected({ kind: "off" });
+		let ids;
+		try {
+			ids = await errors.abortable(runtime.providers(call.agent), call.signal);
+		} catch {
+			errors.throwIfAborted(call.signal);
+			ctx.logger.warn("%s: conversation provider list could not be read", capability.identity.rowId);
+			return rejected({
+				kind: "unavailable",
+				error: unavailable()
+			});
+		}
+		errors.throwIfAborted(call.signal);
+		const current = check();
+		if (current.kind === "rejected") return current;
+		if (ids === void 0) return rejected({ kind: "withdrawn" });
+		return {
+			kind: "done",
+			value: {
+				settings: current.value,
+				plan,
+				ids
+			}
+		};
+	}
+	async function views(prepared, call) {
+		errors.throwIfAborted(call.signal);
+		const connections = /* @__PURE__ */ new Map();
+		for (const id of prepared.ids) {
+			const connection = prepared.settings.connections.get(id);
+			if (connection !== void 0) connections.set(id, {
+				...connection,
+				disabled: false
+			});
+		}
+		try {
+			const described = await errors.abortable(capability.describe({
+				...prepared.settings,
+				connections
+			}, nextModel(ctx, call.agent)), call.signal);
+			errors.throwIfAborted(call.signal);
+			return new Map(described.map((view) => [view.id, view]));
+		} catch {
+			errors.throwIfAborted(call.signal);
+			diagnostic();
+			throw availabilityError();
+		}
+	}
+	function readiness(view) {
+		if (view === void 0) throw availabilityError();
+		switch (view.status) {
+			case "ready": return { status: "ready" };
+			case "needs-credential": return {
+				status: "needs-credential",
+				credential: view.access === "account" ? "account" : "api-key"
+			};
+			case "unsupported":
+				if (view.reason !== void 0) return {
+					status: "unsupported",
+					reason: view.reason
+				};
+				throw availabilityError();
+			case "disabled": throw availabilityError();
+		}
+	}
+	async function readyPrepared(prepared, call) {
+		try {
+			const described = await views(prepared, call);
+			errors.throwIfAborted(call.signal);
+			return {
+				kind: "read",
+				ids: prepared.ids.filter((id) => prepared.settings.connections.has(id) && described.get(id)?.status === "ready")
+			};
+		} catch {
+			return { kind: "unread" };
+		}
+	}
+	return {
+		async run(connectionId, request, call) {
+			const result = await prepare(call);
+			errors.throwIfAborted(call.signal);
+			if (result.kind === "rejected") return result;
+			const prepared = result.value;
+			const connection = prepared.settings.connections.get(connectionId);
+			const refusal = !prepared.ids.includes(connectionId) ? "unknown" : connection === void 0 ? "removed" : void 0;
+			if (refusal !== void 0) {
+				const ready = await readyPrepared(prepared, call);
+				errors.throwIfAborted(call.signal);
+				return rejected({
+					kind: refusal,
+					connectionId,
+					ready
+				});
+			}
+			return ctx.get("agents").withInitiator(call.agent, async () => {
+				errors.throwIfAborted(call.signal);
+				const execution = {
+					ctx,
+					agent: call.agent,
+					signal: call.signal
+				};
+				const target = capability.target(connection, prepared.plan.options, execution);
+				return {
+					kind: "done",
+					value: await capability.execute(target, request, execution)
+				};
+			});
+		},
+		async list(call) {
+			const result = await prepare(call);
+			errors.throwIfAborted(call.signal);
+			if (result.kind === "rejected") return result;
+			const prepared = result.value;
+			const described = await views(prepared, call);
+			errors.throwIfAborted(call.signal);
+			try {
+				const providers = prepared.ids.flatMap((id) => {
+					const connection = prepared.settings.connections.get(id);
+					if (connection === void 0) return [];
+					const view = described.get(id);
+					const state = readiness(view);
+					return [{
+						id,
+						name: view.label,
+						facts: capability.enhanced.listing(connection, call),
+						...state
+					}];
+				});
+				errors.throwIfAborted(call.signal);
+				return {
+					kind: "done",
+					value: {
+						session: {
+							connectionId: prepared.plan.connectionId,
+							selectable: isSelectable(prepared.settings.connections.get(prepared.plan.connectionId))
+						},
+						options: prepared.plan.options,
+						providers
+					}
+				};
+			} catch {
+				errors.throwIfAborted(call.signal);
+				diagnostic();
+				throw availabilityError();
+			}
+		},
+		async ready(call) {
+			try {
+				const prepared = await prepare(call);
+				errors.throwIfAborted(call.signal);
+				return prepared.kind === "rejected" ? { kind: "unread" } : await readyPrepared(prepared.value, call);
+			} catch {
+				return { kind: "unread" };
+			}
+		}
+	};
+}
+//#endregion
 //#region ../core/src/host/storage.ts
 function selectionDomain(name) {
 	const selection = looseObject({
@@ -15451,7 +16205,8 @@ function selectionDomain(name) {
 		version: 1,
 		tables: {
 			selections: domainTable(selection),
-			pairings: domainTable(pairing)
+			pairings: domainTable(pairing),
+			provider_lists: domainTable(array(string$1()))
 		}
 	});
 }
@@ -15492,6 +16247,7 @@ function openDomain(ctx, name, unavailable = () => capabilityErrors(name).error(
 var SessionStorage = class {
 	optionsCodec;
 	access;
+	queues = /* @__PURE__ */ new Map();
 	constructor(ctx, name, optionsCodec, unavailable) {
 		this.optionsCodec = optionsCodec;
 		this.access = openDomain(ctx, name, unavailable);
@@ -15499,7 +16255,202 @@ var SessionStorage = class {
 	domain() {
 		return this.access.domain();
 	}
+	exclusive(id, work) {
+		const previous = this.queues.get(id);
+		const run = previous === void 0 ? work() : previous.then(work);
+		const tail = run.then(() => {}, () => {});
+		this.queues.set(id, tail);
+		tail.then(() => {
+			if (this.queues.get(id) === tail) this.queues.delete(id);
+		});
+		return run;
+	}
+	settled(id) {
+		return this.queues.get(id);
+	}
+};
+//#endregion
+//#region ../core/src/host/command.ts
+var SelectionOperationError = class extends Error {};
+const SOURCES = {
+	session: "chosen in this session",
+	inherited: "copied from the parent session",
+	model: "remembered for this model",
+	default: "the default connection"
 };
+function registerCommand(ctx, capability, sessions) {
+	const { command, providerId, rowId } = capability.identity;
+	const noun = capability.tool === "web_search" ? "web search" : "web fetch";
+	const capital = capability.tool === "web_search" ? "Web search" : "Web fetch";
+	const options = capability.commandOptions;
+	const hint = options === void 0 ? "[off | <connection id>]" : "[off | <connection id> | freshness auto|fresh|realtime]";
+	const failure = "The " + noun + " selection could not be read or saved; retry, or check the Host logs.";
+	const error = (text) => ({
+		kind: "error",
+		text
+	});
+	const selectionOperation = async (work) => {
+		try {
+			return await work();
+		} catch (cause) {
+			if (cause instanceof InvalidSettingsError) throw cause;
+			ctx.logger.warn("%s command selection read or write failed: %s", rowId, cause);
+			throw new SelectionOperationError("selection read or write failed");
+		}
+	};
+	const route = () => routeFacts(ctx, capability.field, providerId);
+	const routing = () => routingText(route(), capability.tool, providerId);
+	const unavailable = (id) => error(id + " is missing or turned off in the settings. Run /" + command + " to list the connections.");
+	const success = (text) => ({
+		kind: "success",
+		text: text + (route().kind === "this" ? "" : "\n" + routing())
+	});
+	const run = async (invocation) => {
+		const raw = invocation.rawInput.trim();
+		const args = raw === "" ? [] : raw.split(/\s+/u);
+		const usage = () => error("Unknown argument \"" + oneLine(raw, 64) + "\". Usage: /" + command + " " + hint);
+		const keyword = args.length === 0 ? "" : args[0].toLowerCase();
+		const freshnessValue = args.length === 2 ? args[1].toLowerCase() : "";
+		const freshness = options !== void 0 && args.length === 2 && keyword === "freshness";
+		if (args.length > 0 && !freshness && !(args.length === 1 && (keyword === "off" || isConnectionId(args[0])))) return usage();
+		if (freshness && !FRESHNESS.some((value) => value === freshnessValue)) return error("Unknown freshness \"" + oneLine(args[1], 64) + "\". Use auto, fresh or realtime.");
+		const target = liveSession(invocation.agent);
+		const settings = capability.settings();
+		const current = await selectionOperation(() => sessions.current(target));
+		if (args.length === 0) {
+			const views = await sessions.connections(target);
+			const id = current.selection.connectionId;
+			const selected = id === null ? void 0 : views.find((view) => view.id === id);
+			let summary = id === null ? "Off" : selected === void 0 || !sessions.selectable(id) ? id : oneLine(selected.label, 200) + " (" + id + ")";
+			summary += " · " + SOURCES[current.source];
+			if (id !== null && !sessions.selectable(id)) summary += " · missing or turned off in the settings; " + capability.tool + " fails until another connection is chosen";
+			if (options !== void 0) summary += " · freshness: " + options.freshness(current.selection.options);
+			const entries = [];
+			for (const view of views) {
+				const connection = settings.connections.get(view.id);
+				if (!isSelectable(connection)) continue;
+				const name = oneLine(view.label, 200);
+				const parts = [statusText(view)];
+				if (view.id === id) parts.push("current");
+				if (view.freshness === true) parts.push("applies freshness");
+				const recipient = recipientText(capability.enhanced.listing(connection, {
+					agent: invocation.agent,
+					signal: invocation.signal
+				}).recipient);
+				if (recipient === "this machine") parts.push("fetches from this machine");
+				else if (recipient !== name) parts.push((capability.tool === "web_search" ? "queries" : "URLs") + " go to " + recipient);
+				entries.push("- " + view.id + " — " + name + " · " + parts.join(" · "));
+			}
+			if (entries.length === 0) entries.push("- (none; turn connections on in the row settings)");
+			const tail = "Turn off: /" + command + " off" + (options === void 0 ? "" : " · Freshness: /" + command + " freshness auto|fresh|realtime (connections marked \"applies freshness\")");
+			return {
+				kind: "success",
+				text: [
+					summary,
+					routing(),
+					"Connections (/" + command + " <id> chooses one):",
+					...entries,
+					tail
+				].join("\n")
+			};
+		}
+		let change;
+		let message;
+		if (freshness && options !== void 0) {
+			const selected = (await sessions.connections(target)).find((view) => view.id === current.selection.connectionId);
+			if (selected === void 0 || selected.freshness !== true || !sessions.selectable(selected.id)) return error("The current connection does not apply freshness. Choose one marked \"applies freshness\" first.");
+			const value = FRESHNESS.find((mode) => mode === freshnessValue);
+			change = options.changeFreshness(value);
+			message = "Freshness is " + value + " from the next model request.";
+		} else if (keyword === "off") {
+			change = { connectionId: null };
+			message = capital + " is off for this session from the next model request.";
+		} else {
+			const id = args[0];
+			if (!sessions.selectable(id)) return unavailable(id);
+			const selected = (await sessions.connections(target)).find((view) => view.id === id);
+			change = { connectionId: id };
+			message = "Now using " + oneLine(selected.label, 200) + " (" + id + ") for " + noun + " from the next model request.";
+		}
+		const result = await selectionOperation(() => writeSelection(sessions, target, change, current.selection.revision));
+		if (result.kind === "unavailable") return unavailable(result.connectionId);
+		if (result.kind === "conflict") return error("The selection changed while this command ran. Run /" + command + " to see it, then try again.");
+		return success(message);
+	};
+	ctx.effect(() => ctx.commands.register({
+		name: command,
+		description: "Show or change this session's " + noun + " connection",
+		input: { hint },
+		async handler(invocation) {
+			try {
+				return await run(invocation);
+			} catch (cause) {
+				if (cause instanceof SelectionOperationError) return error(failure);
+				ctx.logger.warn("%s command failed: %s", rowId, cause);
+				if (cause instanceof InvalidSettingsError) return error("The " + noun + " settings are invalid; fix them in the Enhanced " + noun + " row settings.");
+				throw new Error("The " + noun + " command failed; retry, or check the Host logs.");
+			}
+		}
+	}));
+}
+function routingText(route, tool, providerId) {
+	switch (route.kind) {
+		case "this": return "Routing: " + tool + " goes to this plugin.";
+		case "other": return "Routing: " + tool + " goes to " + oneLine(route.provider, 200) + ", so this selection has no effect until the web row routes it to " + providerId + ".";
+		case "auto": return "Routing: the web row pins no " + tool + " provider, so this selection has no effect until it routes " + tool + " to " + providerId + ".";
+		case "unknown": return "Routing: the web row could not be read, so this selection may have no effect.";
+	}
+}
+function statusText(view) {
+	switch (view.status) {
+		case "ready": return "ready";
+		case "needs-credential": return view.access === "account" ? "needs DeepSeek sign-in" : "needs an API key";
+		case "unsupported": return "unavailable: " + UNSUPPORTED_REASON_TEXT[view.reason];
+		case "disabled": return "missing or turned off in the settings";
+	}
+}
+//#endregion
+//#region ../core/src/host/terminal.ts
+function registerTerminal(ctx, root, noun, settings, freshness) {
+	ctx.effect(() => ctx.tuiCommandTrees.register({
+		root,
+		children(path) {
+			if (path[0] !== root) return [];
+			if (freshness && path.length === 2 && path[1] === "freshness") return [
+				{
+					name: "auto",
+					description: "Auto"
+				},
+				{
+					name: "fresh",
+					description: "Within 24 hours"
+				},
+				{
+					name: "realtime",
+					description: "Live"
+				}
+			];
+			if (path.length !== 1) return [];
+			const nodes = [{
+				name: "off",
+				description: "Turn " + noun + " off for this session"
+			}];
+			try {
+				for (const connection of settings().connections.values()) if (isSelectable(connection)) nodes.push({
+					name: connection.id,
+					description: oneLine(connection.label, 200)
+				});
+			} catch (error) {
+				if (!(error instanceof InvalidSettingsError)) throw error;
+			}
+			if (freshness) nodes.push({
+				name: "freshness",
+				description: "Content freshness, for connections that apply it"
+			});
+			return nodes;
+		}
+	}));
+}
 //#endregion
 //#region ../core/src/host/runtime.ts
 /** Install the sole Seat, session lifecycle, route-guarded restrictions and Remote service. */
@@ -15510,24 +16461,56 @@ function installCapability(ctx, capability) {
 	const invalid = () => errors.error("WEB_PROVIDER_CONFIGURED_UNAVAILABLE", "the selected " + kind + " connection is unavailable; ask the user to enable it or choose another connection");
 	const storage = new SessionStorage(ctx, capability.storageDomain, capability.optionsCodec, () => errors.error("WEB_PROVIDER_ERROR", kind + " selection storage is unavailable; retry or ask the user to check the DSH storage backend"));
 	const pairings = new Pairings(storage);
+	const lists = new ProviderLists(storage);
+	const snapshots = new Snapshots();
+	const access = explicitAccess(ctx, capability, {
+		active: () => restriction.active,
+		offered: () => restriction.offered(),
+		plan: (agent) => snapshots.get(agent),
+		providers: (agent) => lists.read(agent)
+	}, errors, contextUnavailable);
 	const restriction = new ToolRestriction(ctx, {
 		tool: capability.tool,
 		routed: () => routeFacts(ctx, capability.field, capability.identity.providerId).kind === "this",
-		selection: async (agent) => (await sessions.peek(agent)).selection.connectionId
+		selection: async (agent) => (await sessions.peek(liveSession(agent))).selection.connectionId,
+		enhanced: {
+			rowId: capability.identity.rowId,
+			names: capability.enhanced.names,
+			enabled: () => {
+				try {
+					return capability.settings().enhancedTools;
+				} catch (error) {
+					if (error instanceof InvalidSettingsError) return false;
+					throw error;
+				}
+			},
+			tools: () => capability.enhanced.tools(access),
+			providers: (agent) => lists.read(agent)
+		}
 	});
-	const sessions = new Sessions(ctx, () => capability.settings(), storage, pairings, restriction, (settings, agent) => capability.describe(settings, agent));
-	const snapshots = new Snapshots();
+	const sessions = new Sessions(ctx, () => capability.settings(), storage, pairings, restriction, (settings, model) => capability.describe(settings, model));
 	const capture = async (agent, signal) => {
+		const operation = restriction.begin(agent);
 		try {
-			const read = sessions.current(agent);
+			const read = sessions.current(liveSession(agent));
 			const { selection } = signal === void 0 ? await read : await errors.abortable(read, signal);
 			if (!restriction.active) return {
 				kind: "failed",
 				error: contextUnavailable()
 			};
-			restriction.sync(agent, selection.connectionId);
+			let providers = { kind: "unread" };
+			if (restriction.registered && restriction.offered()) try {
+				providers = {
+					kind: "read",
+					ids: await lists.read(agent)
+				};
+			} catch {
+				ctx.logger.warn("%s: conversation provider list could not be read", capability.identity.rowId);
+			}
+			restriction.captured(agent, operation, selection.connectionId, providers);
 			return planFor(selection);
 		} catch (error) {
+			restriction.failed(agent, operation);
 			ctx.logger.warn("%s: capturing %s selection failed: %s", capability.identity.rowId, kind, error);
 			return {
 				kind: "failed",
@@ -15540,13 +16523,33 @@ function installCapability(ctx, capability) {
 		return next();
 	});
 	ctx.on("agent/created", async ({ agent }) => {
+		restriction.created(agent);
+		const initial = isNewConversation(agent.session) ? restriction.offered() ? [...capability.settings().connections.values()].filter(isSelectable).map((connection) => connection.id) : [] : void 0;
+		try {
+			await lists.create(agent, initial);
+		} catch {
+			ctx.logger.warn("%s: conversation provider list could not be read", capability.identity.rowId);
+		}
 		await snapshots.capture(agent, -1, -1, () => capture(agent));
 	});
+	restriction.start().catch((error) => {
+		ctx.logger.warn("%s: starting tool visibility failed: %s", capability.identity.rowId, error);
+	});
 	ctx.on("agent/disposed", ({ agent }) => {
 		snapshots.forget(agent);
 		restriction.forget(agent);
 	});
-	ctx.inject(["sessionController", "typert"], (scope) => {
+	ctx.inject(["commands"], (scope) => {
+		registerCommand(scope, capability, sessions);
+	});
+	ctx.inject(["tuiCommandTrees"], (scope) => {
+		registerTerminal(scope, capability.identity.command, "web " + kind, () => capability.settings(), capability.commandOptions !== void 0);
+	});
+	ctx.inject([
+		"sessionController",
+		"typert",
+		"agents"
+	], (scope) => {
 		createConnectionsService(scope, {
 			namespace: capability.remoteNamespace,
 			contract: capability.contract,
@@ -16428,7 +17431,7 @@ const { withDeadline, readJson, requestJson, invalidResponse } = transport;
 const mcp = createMcpClient(transport, searchErrors, {
 	clientInfo: {
 		name: SEARCH.packageName,
-		version: "0.2.0"
+		version: "0.2.2"
 	},
 	messages: {
 		toolFailed: (label, detail) => label + " could not complete the search; retry later or choose another search connection" + upstreamSuffix(label, detail),
@@ -16534,6 +17537,7 @@ const location = {
 const MODEL_PROTOCOLS = {
 	"anthropic-messages": {
 		label: "Anthropic Messages",
+		use: "the model searches and answers",
 		options: {
 			maxTokens,
 			anthropicTool,
@@ -16549,6 +17553,7 @@ const MODEL_PROTOCOLS = {
 	},
 	"openai-responses": {
 		label: "OpenAI Responses",
+		use: "the model searches and answers",
 		options: {
 			maxTokens,
 			responsesTool,
@@ -16562,6 +17567,7 @@ const MODEL_PROTOCOLS = {
 	},
 	"openai-chat-completions": {
 		label: "OpenAI Chat Completions",
+		use: "the model searches and answers",
 		options: {
 			maxTokens,
 			searchContextSize,
@@ -16593,6 +17599,8 @@ const CATALOG = {
 		label: "DeepSeek Messages",
 		kind: "native",
 		remote: true,
+		optIn: false,
+		use: "answers with a summary and sources",
 		endpoint: "https://api.deepseek.com/anthropic/v1",
 		homepage: "https://platform.deepseek.com",
 		access: nativeAccess,
@@ -16623,6 +17631,7 @@ const CATALOG = {
 		label: "DeepSeek Search API",
 		kind: "native",
 		remote: true,
+		optIn: true,
 		endpoint: "https://api.deepseek.com/v1/tools",
 		homepage: "https://platform.deepseek.com",
 		access: nativeAccess,
@@ -16641,6 +17650,8 @@ const CATALOG = {
 		label: "Session model",
 		kind: "model",
 		remote: true,
+		optIn: false,
+		use: "the session model searches and answers",
 		access: {
 			keyless: false,
 			apiKey: false,
@@ -16660,6 +17671,7 @@ const CATALOG = {
 		},
 		kind: "adapter",
 		remote: true,
+		optIn: true,
 		freshness: ["api-key"],
 		homepage: "https://exa.ai",
 		options: { type: {
@@ -16682,6 +17694,7 @@ const CATALOG = {
 		},
 		kind: "adapter",
 		remote: true,
+		optIn: true,
 		freshness: ["keyless", "api-key"],
 		homepage: "https://www.firecrawl.dev",
 		options: {
@@ -16707,6 +17720,7 @@ const CATALOG = {
 		},
 		kind: "adapter",
 		remote: true,
+		optIn: true,
 		freshness: [],
 		homepage: "https://www.tavily.com",
 		options: {
@@ -16739,6 +17753,7 @@ const CATALOG = {
 		},
 		kind: "adapter",
 		remote: true,
+		optIn: true,
 		freshness: [],
 		homepage: "https://www.tinyfish.ai",
 		options: {
@@ -16775,8 +17790,10 @@ const CATALOG = {
 		},
 		kind: "adapter",
 		remote: true,
+		optIn: true,
 		freshness: [],
 		homepage: "https://openalex.org",
+		use: "scholarly works (papers, citations); keyword queries",
 		options: {
 			sort: {
 				kind: "text",
@@ -16805,8 +17822,10 @@ const CATALOG = {
 		},
 		kind: "adapter",
 		remote: true,
+		optIn: true,
 		freshness: [],
 		homepage: "https://www.semanticscholar.org/product/api",
+		use: "academic papers (citations, TL;DR); keyword queries",
 		options: {
 			year: {
 				kind: "text",
@@ -17066,17 +18085,9 @@ function sourceFields(source) {
 }
 //#endregion
 //#region src/model/execute.ts
-const UNSUPPORTED = {
-	"no-model": "no session model is available",
-	"unknown-route": "the model route is unknown",
-	protocol: "the route does not declare a supported protocol",
-	endpoint: "the route has no supported endpoint",
-	headers: "the route uses custom request headers",
-	credential: "the route has no supported credential reference"
-};
 async function executeModelSearch(target, request, deps, signal) {
 	throwIfAborted(signal);
-	if (target.route.kind === "unsupported") throw searchError("WEB_PROVIDER_CONFIGURED_UNAVAILABLE", "the session model cannot run web search: " + UNSUPPORTED[target.route.reason] + "; choose another search connection");
+	if (target.route.kind === "unsupported") throw searchError("WEB_PROVIDER_CONFIGURED_UNAVAILABLE", "the session model cannot run web search: " + UNSUPPORTED_REASON_TEXT[target.route.reason] + "; choose another search connection");
 	const route = target.route.route;
 	let matcher;
 	try {
@@ -17114,15 +18125,24 @@ async function executeModelSearch(target, request, deps, signal) {
 async function credential(route, deps, signal) {
 	const { auth } = route;
 	if (auth.kind === "account") {
-		const token = await abortable(deps.accountToken(modelUrl(route.protocol, route.baseURL)), signal);
+		const endpoint = modelUrl(route.protocol, route.baseURL);
+		const token = await readCredential(() => deps.accountToken(endpoint), signal);
 		if (token === void 0 || !/^[\x20-\x7e]+$/u.test(token)) throw searchError("WEB_PROVIDER_CREDENTIAL_MISSING", "the DeepSeek account sign-in is unavailable for this search; ask the user to sign in again or choose another search connection");
 		return token;
 	}
-	const stored = storedApiKey(await abortable(deps.apiKey(auth.credentialRef, auth.source), signal));
+	const stored = storedApiKey(await readCredential(() => deps.apiKey(auth.credentialRef, auth.source), signal));
 	if (stored.kind === "missing") throw searchError("WEB_PROVIDER_CREDENTIAL_MISSING", credentialMissing(auth.credentialRef, auth.source));
 	if (stored.kind === "malformed") throw searchError("WEB_PROVIDER_CREDENTIAL_MISSING", credentialInvalid(auth.credentialRef, auth.source));
 	return stored.key;
 }
+async function readCredential(resolve, signal) {
+	try {
+		return await abortable(resolve(), signal);
+	} catch {
+		throwIfAborted(signal);
+		throw new Error("Model credential resolution failed");
+	}
+}
 //#endregion
 //#region src/contract.ts
 const contract = selectionContract({
@@ -17216,15 +18236,287 @@ function createSearchSeat(id, select) {
 	};
 }
 //#endregion
+//#region src/host/listing.ts
+/**
+* What list_web_search_providers says about one connection (docs/design.md, "列出工具"):
+* its catalog use, who receives the query and whether it applies the Session's
+* freshness. Reads only settings and public model facts; no I/O, no secrets.
+*/
+function searchListing(ctx, connection, call) {
+	switch (connection.kind) {
+		case "native": {
+			const info = CATALOG[connection.native];
+			const { baseURL } = connection.options;
+			return {
+				use: info.use,
+				recipient: service(info.label, typeof baseURL === "string" ? baseURL : info.endpoint, info.endpoint),
+				appliesFreshness: false
+			};
+		}
+		case "adapter": {
+			const info = CATALOG[connection.adapter];
+			const endpoint = connection.access === "keyless" ? info.endpoint : connection.endpoint;
+			return {
+				use: info.use,
+				recipient: service(info.label, endpoint, info.endpoint),
+				appliesFreshness: honorsFreshness(connection.adapter, connection.access)
+			};
+		}
+		case "model": {
+			if (connection.route.kind === "session") {
+				const model = nextModel(ctx, call.agent);
+				return {
+					use: CATALOG["session-model"].use,
+					recipient: {
+						kind: "session-model",
+						provider: model === void 0 ? void 0 : model.provider
+					},
+					appliesFreshness: false
+				};
+			}
+			const protocol = MODEL_PROTOCOLS[connection.route.protocol];
+			return {
+				use: protocol.use,
+				recipient: {
+					kind: "service",
+					service: protocol.label,
+					host: new URL(connection.route.endpoint).hostname
+				},
+				appliesFreshness: false
+			};
+		}
+	}
+}
+/** The catalog service; an operator endpoint that differs from the catalog's is named by its hostname. */
+function service(label, endpoint, catalogEndpoint) {
+	return {
+		kind: "service",
+		service: label,
+		host: endpoint === catalogEndpoint ? void 0 : new URL(endpoint).hostname
+	};
+}
+//#endregion
+//#region src/tools/queries.ts
+/**
+* The multi-query part of `web_search`, copied from `@deepseek-ai/dsh-tool-web`
+* 0.2.1-rc.2 (packages/web/tool-web/src/search.ts: `parseSearchArgs`,
+* `runSearchQueries`, `mergeSearchResults`, `projectSource`) and
+* `@deepseek-ai/dsh-web` (packages/web/web/src/index.ts: `capSources`), which do
+* not export them. The enhanced tool bypasses `ctx.web`, so it applies the
+* seam's `capSources` itself. Keep in step with DSH on baseline upgrades;
+* tests/tools-search.spec.ts compares the result with the real tool-web.
+*/
+/** tool-web's `parseSearchArgs`: 1–4 non-blank queries, exact duplicates collapsed after the bound check. */
+function parseQueries(queries) {
+	if (queries.length === 0) throw invalidArguments("queries must contain at least one query");
+	if (queries.length > WEB_SEARCH_MAX_QUERIES) throw invalidArguments(`queries must contain at most ${WEB_SEARCH_MAX_QUERIES} queries`);
+	if (queries.some((query) => query.trim().length === 0)) throw invalidArguments("each query must be a non-empty string");
+	return [...new Set(queries)];
+}
+/**
+* tool-web's `runSearchQueries`: one query keeps its (capped) result; several
+* run concurrently and merge. A failed search aborts its siblings, and the
+* first failure is rethrown once every search has settled.
+*/
+async function searchQueries(queries, run, signal) {
+	const search = async (query, querySignal) => capSources(await run({
+		query,
+		maxResults: WEB_SEARCH_MAX_RESULTS
+	}, querySignal), WEB_SEARCH_MAX_RESULTS);
+	const [only] = queries;
+	if (queries.length === 1 && only !== void 0) return search(only, signal);
+	const controller = new AbortController();
+	const batchSignal = AbortSignal.any([signal, controller.signal]);
+	let firstFailure;
+	const results = [];
+	const searches = queries.map(async (query, index) => {
+		try {
+			results[index] = await search(query, batchSignal);
+		} catch (error) {
+			if (firstFailure === void 0) firstFailure = { error };
+			controller.abort(error);
+			throw error;
+		}
+	});
+	await Promise.allSettled(searches);
+	if (firstFailure !== void 0) throw firstFailure.error;
+	return mergeSearchResults(queries, results, WEB_SEARCH_MAX_RESULTS);
+}
+/** tool-web's `mergeSearchResults`: round-robin by rank, deduplicated by URL, capped; answers joined under `### <query>`. */
+function mergeSearchResults(queries, results, maxResults) {
+	const seen = /* @__PURE__ */ new Set();
+	const sources = [];
+	let sourceRanks = 0;
+	for (const result of results) sourceRanks = Math.max(sourceRanks, result.sources.length);
+	let droppedSource = false;
+	merge: for (let rank = 0; rank < sourceRanks; rank++) for (const result of results) {
+		const source = result.sources[rank];
+		if (source !== void 0 && !seen.has(source.url)) {
+			seen.add(source.url);
+			if (sources.length === maxResults) {
+				droppedSource = true;
+				break merge;
+			}
+			sources.push(source);
+		}
+	}
+	const contents = results.flatMap((result, index) => {
+		if (result.content === void 0 || result.content.length === 0) return [];
+		return [`### ${queries[index]}\n\n${result.content}`];
+	});
+	return {
+		...contents.length > 0 ? { content: contents.join("\n\n") } : {},
+		sources,
+		truncated: results.some((result) => result.truncated) || droppedSource
+	};
+}
+/** dsh-web's `capSources`: the seam's cut of an over-returning provider. */
+function capSources(result, maxResults) {
+	if (result.sources.length <= maxResults) return result;
+	return {
+		...result,
+		sources: result.sources.slice(0, maxResults),
+		truncated: true
+	};
+}
+/** tool-web's `projectSource`: `{ url }` plus each present optional field. */
+function projectSource(source) {
+	return {
+		url: source.url,
+		...source.title !== void 0 ? { title: source.title } : {},
+		...source.snippet !== void 0 ? { snippet: source.snippet } : {},
+		...source.publishedAt !== void 0 ? { publishedAt: source.publishedAt } : {}
+	};
+}
+//#endregion
+//#region src/tools/definitions.ts
+const { action, list } = SEARCH.tools;
+const VOICE = {
+	identity: SEARCH,
+	capability: "web search",
+	nativeTool: "web_search",
+	sends: "queries"
+};
+/** Slightly longer than the remote backends' 90 s deadline, so their worded timeout arrives first (docs/design.md, "工具与输出"). */
+const SEARCH_TIMEOUT_MS = 1e5;
+/** `web_search`'s output schema plus the provider that served the call. */
+const SEARCH_RESULT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		provider: {
+			type: "string",
+			required: true
+		},
+		content: { type: "string" },
+		sources: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					url: {
+						type: "string",
+						required: true
+					},
+					title: { type: "string" },
+					snippet: { type: "string" },
+					publishedAt: { type: "string" }
+				}
+			}
+		},
+		truncated: {
+			type: "boolean",
+			required: true
+		}
+	}
+};
+/** The two static search definitions (docs/design.md, "工具与输出"); available providers never enter them. */
+function searchTools(access) {
+	return {
+		action: defineTool({
+			name: action,
+			description: `Search the web through a provider you choose. Use web_search unless you need a specific provider: one the user named, a specialized index, or another after web_search fails.`,
+			parameters: {
+				queries: {
+					type: "array",
+					required: true,
+					items: { type: "string" },
+					description: `1–${WEB_SEARCH_MAX_QUERIES} search queries; their results are merged.`
+				},
+				provider: {
+					type: "string",
+					required: true,
+					description: `Provider id exactly as listed by ${list}.`
+				}
+			},
+			output: {
+				schema: SEARCH_RESULT_SCHEMA,
+				render: (_args, value) => [{
+					type: "text",
+					text: `Provider: ${value.provider}\n\n${formatSearchOutput(value)}`
+				}],
+				presentationMeta: (_args, value) => searchMetaFromValue(value)
+			},
+			timeoutMs: SEARCH_TIMEOUT_MS,
+			isConcurrencySafe: () => true,
+			async execute(args, exec) {
+				rejectUnknownProperties(args, ["queries", "provider"]);
+				const queries = parseQueries(args.queries);
+				const call = explicitCall(action, exec);
+				const provider = await providerArgument(VOICE, args.provider, access, call);
+				const result = await searchQueries(queries, (request, signal) => runOnProvider(VOICE, access, provider, request, {
+					agent: call.agent,
+					signal
+				}), call.signal);
+				return {
+					provider,
+					...result.content !== void 0 ? { content: result.content } : {},
+					sources: result.sources.map(projectSource),
+					truncated: result.truncated
+				};
+			}
+		}),
+		list: defineTool({
+			name: list,
+			description: `List the providers ${action} accepts, with what each is for and whether it is ready.`,
+			parameters: {},
+			output: {
+				schema: searchListingSchema(),
+				render: (_args, value) => [{
+					type: "text",
+					text: renderSearchListing(VOICE, value)
+				}]
+			},
+			isConcurrencySafe: () => true,
+			async execute(args, exec) {
+				rejectUnknownProperties(args, []);
+				return searchListingValue(await listProviders(VOICE, access, explicitCall(list, exec)));
+			}
+		})
+	};
+}
+//#endregion
+//#region src/tools/index.ts
+/** The search side of the enhanced tools (docs/design.md, "增强工具"). */
+function searchEnhanced(ctx) {
+	return {
+		names: SEARCH.tools,
+		tools: searchTools,
+		listing: (connection, call) => searchListing(ctx, connection, call)
+	};
+}
+//#endregion
 //#region src/host/connections.ts
-async function describeConnections(ctx, settings, agent) {
+async function describeConnections(ctx, settings, model) {
 	return Promise.all([...settings.connections.values()].map(async (connection) => {
 		const base = baseOf(connection);
 		if (connection.kind === "model") {
 			const target = connection.route.kind === "fixed" ? {
 				kind: "route",
 				route: fixedRoute(connection.route)
-			} : sessionRoute(ctx, nextModel(ctx, agent));
+			} : sessionRoute(ctx, model);
 			const access = target.kind === "route" ? target.route.auth.kind : "api-key";
 			if (connection.disabled) return {
 				...base,
@@ -17257,7 +18549,7 @@ async function describeConnections(ctx, settings, agent) {
 		const endpoint = connection.kind === "native" ? typeof connection.options.baseURL === "string" ? connection.options.baseURL : CATALOG[connection.native].endpoint : void 0;
 		return {
 			...base,
-			...await credentialReadiness(ctx, agent, {
+			...await credentialReadiness(ctx, model, {
 				endpoint,
 				credentialRef: connection.credentialRef
 			})
@@ -17302,7 +18594,11 @@ function searchCapability(ctx, settings) {
 		contract,
 		optionsCodec,
 		settings,
-		describe: (current, agent) => describeConnections(ctx, current, agent),
+		commandOptions: {
+			freshness: (options) => options.freshness,
+			changeFreshness: (freshness) => ({ freshness })
+		},
+		describe: (current, model) => describeConnections(ctx, current, model),
 		target: (connection, options, call) => {
 			switch (connection.kind) {
 				case "adapter": return {
@@ -17349,7 +18645,8 @@ function searchCapability(ctx, settings) {
 				available: () => true,
 				search: invoke
 			})));
-		}
+		},
+		enhanced: searchEnhanced(ctx)
 	};
 }
 function installSearch(ctx, settings) {