@yanlinglabs/winter-agent-runtime 0.0.36 → 0.0.38

package/dist/{index-1nhzy5e2.js → index-8x4yjdg7.js}

@@ -9,14 +9,14 @@ import {
   resolveEngineSession2,
   resolveProductionWinterHome2,
   resolveProductionStoreHome
-} from "./index-c8j57y8v.js";
+} from "./index-5xe59vkt.js";
 import {
   registerDefaultChildEngineFactory,
   loadResumedChain,
   buildProductionWiring,
   withAutoSkillPermissions,
   restoreChildRoster
-} from "./index-83p1g9ap.js";
+} from "./index-z3970wsj.js";
 
 // src/embedded.ts
 import { splitFrames, encodeFrame } from "@yanlinglabs/winter-agent-sdk";

package/dist/{index-83p1g9ap.js → index-z3970wsj.js}

@@ -85,7 +85,7 @@ import {
   providerCredentialRef2,
   createModelClassifier2,
   selectClassifierRoute2
-} from "./index-c8j57y8v.js";
+} from "./index-5xe59vkt.js";
 import {
   createKeychainCredentialStore,
   createKeychainSecretReader,
@@ -311,7 +311,7 @@ function applySubagentToolPool(tools, opts) {
       return true;
     if (policyName === BACKGROUND_AGENT_ALWAYS_ALLOWED_TOOL)
       return true;
-    if (name.startsWith("mcp__") && !twins.has(name))
+    if (!twins.has(name) && (name.startsWith("mcp__") || getRegisteredTool(name)?.descriptor.source === "mcp"))
       return true;
     return allow.has(policyName);
   });
@@ -492,12 +492,14 @@ function renameMcpReference(entry, renames) {
   }
   return;
 }
-function allocateChildScopedServers(declared, parentVisible, prefer, parentDeclared) {
+function allocateChildScopedServers(declared, parentVisible, prefer, parentDeclared, reserved) {
   const claimed = [];
-  const inUse = (name) => liveChildScopedServerNames.has(name) || parentVisible.has(name) || mcpServerHasRegistrations(name);
+  const reservedSet = new Set(reserved ?? []);
+  const inUse = (name) => liveChildScopedServerNames.has(name) || parentVisible.has(name) || mcpServerHasRegistrations(name) || reservedSet.has(name);
   const servers = {};
   const actual = new Map;
   const notes = [];
+  const reservedRenames = new Set;
   const claim = (name) => {
     liveChildScopedServerNames.add(name);
     claimed.push(name);
@@ -505,7 +507,7 @@ function allocateChildScopedServers(declared, parentVisible, prefer, parentDecla
   for (const [name, cfg] of Object.entries(declared)) {
     if (cfg.type === "sdk") {
       if (inUse(name)) {
-        notes.push(parentVisible.has(name) && parentDeclared?.[name]?.type === "sdk" ? `mcpServers declares the in-process server "${name}", which this session already has -- the session's "${name}" is used` : parentVisible.has(name) ? `mcpServers declares the in-process server "${name}", but this session's "${name}" is a different server -- this agent's own in-process "${name}" is not connected, and the session's is what this agent sees` : `mcpServers declares the in-process server "${name}", which another agent in this session is using -- this agent's own in-process "${name}" is not connected`);
+        notes.push(parentVisible.has(name) && parentDeclared?.[name]?.type === "sdk" ? `mcpServers declares the in-process server "${name}", which this session already has -- the session's "${name}" is used` : parentVisible.has(name) ? `mcpServers declares the in-process server "${name}", but this session's "${name}" is a different server -- this agent's own in-process "${name}" is not connected, and the session's is what this agent sees` : reservedSet.has(name) && !liveChildScopedServerNames.has(name) && !mcpServerHasRegistrations(name) ? `mcpServers declares the in-process server "${name}", a name this session's host reserves -- this agent's own in-process "${name}" is not connected` : `mcpServers declares the in-process server "${name}", which another agent in this session is using -- this agent's own in-process "${name}" is not connected`);
         continue;
       }
       claim(name);
@@ -523,6 +525,8 @@ function allocateChildScopedServers(declared, parentVisible, prefer, parentDecla
     claim(pick);
     servers[pick] = cfg;
     actual.set(name, pick);
+    if (pick !== name && reservedSet.has(name))
+      reservedRenames.add(name);
     if (pick !== name)
       notes.push(`mcpServers declares "${name}", which is already in use in this session -- this agent's own "${name}" is connected as "${pick}" (its tools are named mcp__${pick}__<tool>)`);
   }
@@ -531,6 +535,7 @@ function allocateChildScopedServers(declared, parentVisible, prefer, parentDecla
     servers,
     actual,
     notes,
+    reservedRenames,
     release: () => {
       if (released)
         return;
@@ -775,7 +780,7 @@ async function spawnChildEngine(req, inherit, runCtx, deps) {
           ...!ownServers && parentMcp?.stateSource !== undefined ? { mcpServerStateSource: parentMcp.stateSource } : {},
           ...!ownServers && parentMcp?.controlSeam !== undefined ? { mcpControlSeam: parentMcp.controlSeam } : {},
           ...(() => {
-            const merged = { ...parentMcp?.serverRenames ?? {}, ...Object.fromEntries(renames.map(([declared, actual]) => [actual, declared])) };
+            const merged = { ...parentMcp?.serverRenames ?? {}, ...Object.fromEntries(renames.filter(([declared]) => !servers.reservedRenames.has(declared)).map(([declared, actual]) => [actual, declared])) };
             return Object.keys(merged).length > 0 ? { mcpServerRenames: merged } : {};
           })(),
           ...parentMcp?.visibleServerNames !== undefined ? { inheritedMcpServerNames: ownServerNames.size === 0 ? parentMcp.visibleServerNames : () => parentMcp.visibleServerNames().filter((name) => !ownServerNames.has(name)) } : {},
@@ -886,7 +891,12 @@ async function spawnChildEngine(req, inherit, runCtx, deps) {
     const complementDeny = allToolNames.filter((name) => !allowSet.has(name));
     const disallowedTools = [...new Set([...complementDeny, ...req.definition?.disallowedTools ?? []])];
     const allowedAgentTypes = allowedAgentTypesFromTools(req.definition?.tools);
-    const capabilities = [...new Set(effectiveTools.flatMap((name) => getRegisteredTool(name)?.descriptor.capabilityRequirements ?? []))];
+    const capabilities = [
+      ...new Set(effectiveTools.flatMap((name) => {
+        const descriptor = getRegisteredTool(name)?.descriptor;
+        return [...descriptor?.capabilityRequirements ?? [], ...descriptor?.availability.requiresAnyCapability ?? []];
+      }))
+    ];
     const definitionWarnings = req.definition !== undefined ? validateAgentDefinition(req.definition) : [];
     const parentMcp = runCtx.getParentMcpState?.();
     const parentAgents = runCtx.getParentAgents?.();
@@ -955,6 +965,8 @@ async function spawnChildEngine(req, inherit, runCtx, deps) {
       ...deps.parentBrand !== undefined ? { brand: deps.parentBrand } : {},
       ...deps.parentAutoMemory !== undefined ? { autoMemory: deps.parentAutoMemory } : {},
       ...deps.parentWeb !== undefined ? { web: deps.parentWeb } : {},
+      ...deps.parentReservedMcpServerNames !== undefined ? { reservedMcpServerNames: deps.parentReservedMcpServerNames } : {},
+      ...deps.parentLegacyToolNames !== undefined ? { legacyToolNames: deps.parentLegacyToolNames } : {},
       model: resolvedModel.effectiveModel,
       permissionMode: inherit.policy.effectiveMode,
       allowDangerouslySkipPermissions: inherit.policy.effectiveMode === "bypassPermissions",
@@ -965,6 +977,7 @@ async function spawnChildEngine(req, inherit, runCtx, deps) {
       ...req.fork === true && inherit.effectiveEffort !== undefined && typeof inherit.effectiveEffort !== "number" ? { effort: inherit.effectiveEffort } : {},
       ...req.fork === true && inherit.effectiveThinking !== undefined ? { thinking: inherit.effectiveThinking } : {},
       disallowedTools,
+      tools: [...effectiveTools],
       capabilities,
       ...allowedAgentTypes !== undefined ? { allowedAgentTypes } : {},
       forwardSubagentText: deps.forwardSubagentText === true,
@@ -980,7 +993,7 @@ async function spawnChildEngine(req, inherit, runCtx, deps) {
     const resolvedSystemPrompt = [inherit.systemPrompt, req.fork === true ? undefined : req.definition?.prompt].filter((s) => s !== undefined && s.length > 0).join(`
 
 `);
-    let serverAllocation = allocateChildScopedServers(childScopedMcpServers, parentVisibleServers(), undefined, parentMcp?.declaredServers);
+    let serverAllocation = allocateChildScopedServers(childScopedMcpServers, parentVisibleServers(), undefined, parentMcp?.declaredServers, deps.parentReservedMcpServerNames);
     pendingServerRelease = serverAllocation.release;
     definitionWarnings.push(...serverAllocation.notes);
     const firstTurnText = req.fork === true ? buildForkDirectiveText({ prompt: req.prompt, ...req.isolation === "worktree" ? { worktree: { parentRoot: inherit.sessionRoot, worktreeRoot: workspace.root } } : {} }) : [req.definition?.initialPrompt, req.prompt, definitionWarnings.length > 0 ? `
@@ -1093,7 +1106,7 @@ async function spawnChildEngine(req, inherit, runCtx, deps) {
         pendingResume = undefined;
         if (ticket.stopped)
           return { status: "unavailable", messageId: msg.messageId, retryable: false, reason: `child ${agentId} was stopped while resuming` };
-        serverAllocation = allocateChildScopedServers(childScopedMcpServers, parentVisibleServers(), previous, parentMcp?.declaredServers);
+        serverAllocation = allocateChildScopedServers(childScopedMcpServers, parentVisibleServers(), previous, parentMcp?.declaredServers, deps.parentReservedMcpServerNames);
         const moved = [...serverAllocation.actual].filter(([declared, name]) => previous.get(declared) !== name).map(([declared, name]) => `this agent's own "${declared}" is now connected as "${name}" (its tools are named mcp__${name}__<tool>)`);
         startGeneration(generationConfig(resumeMode), rebuilt, moved.length > 0 ? `${msg.body}
 
@@ -1159,6 +1172,8 @@ function registerDefaultChildEngineFactory(opts) {
     ...config.brand !== undefined ? { parentBrand: config.brand } : {},
     ...config.autoMemory !== undefined ? { parentAutoMemory: config.autoMemory } : {},
     ...config.web !== undefined ? { parentWeb: config.web } : {},
+    ...config.reservedMcpServerNames !== undefined ? { parentReservedMcpServerNames: config.reservedMcpServerNames } : {},
+    ...config.legacyToolNames !== undefined ? { parentLegacyToolNames: config.legacyToolNames } : {},
     ...opts.systemPromptAssembler !== undefined ? { systemPromptAssembler: opts.systemPromptAssembler } : {},
     ...opts.skillRuntime !== undefined ? { skillRuntime: opts.skillRuntime } : {},
     ...opts.structuredOutput !== undefined ? { structuredOutput: opts.structuredOutput } : {},

package/dist/index.js

@@ -55,7 +55,7 @@ import {
   DEFAULT_CLASSIFIER_TIMEOUT_MS2,
   createModelClassifier2,
   selectClassifierRoute2
-} from "./index-c8j57y8v.js";
+} from "./index-5xe59vkt.js";
 import"./index-1hef2gff.js";
 import"./index-mwew595z.js";
 import"./index-2wgfv0pa.js";

package/dist/mcp/control.d.ts

@@ -2,4 +2,5 @@ import type { McpControlSeam } from "./control-seam.js";
 import type { McpLifecycleInternals } from "./lifecycle.js";
 export declare function createMcpControlSeam(internals: McpLifecycleInternals, opts?: {
     reservedServerName?: string;
+    hostReservedServerNames?: readonly string[];
 }): McpControlSeam;

package/dist/mcp/lifecycle.d.ts

@@ -85,6 +85,7 @@ export declare function resolveMcpServerSources(sources: readonly McpServerSourc
     strictMcpConfig?: boolean;
     trustedWorkspace: boolean;
     reservedServerName?: string;
+    hostReservedServerNames?: readonly string[];
 }): ResolveMcpServerSourcesResult;
 /** The text budget of an MCP result that carries images (≈ the default `MAX_MCP_OUTPUT_TOKENS` of 25000 at 4 characters a token). */
 export declare const MCP_IMAGE_RESULT_TEXT_CHARS = 100000;
@@ -111,6 +112,8 @@ export interface McpLifecycleDeps {
      * `addAndConnect` guard is the second door onto the same rule. Defaults to `WINTER_SERVER_NAME`.
      */
     reservedServerName?: string;
+    /** `RuntimeConfig.reservedMcpServerNames`, for the control seam's live `mcp_set_servers` guard: a non-sdk server is refused under any of them. */
+    hostReservedServerNames?: readonly string[];
     /** WS-23: the session cwd every stdio server of this lifecycle is spawned in (see `ConnectMcpServerOptions.cwd`). */
     cwd?: string;
     /**

package/dist/provider/mock.d.ts

@@ -27,7 +27,7 @@ export declare const P5_FIXTURE_SKILL_NAME = "p5probe";
  * `{"answer":"42","doubled":"4242"}` on every leg.
  */
 export declare const P5_WORKFLOW_SCRIPT: string;
-export type TestProviderName = "boom" | "tooluse" | "hang" | "reflect" | "modeswitch" | "bgtask" | "lanea" | "laneb" | "lanec" | "laned" | "lanee" | "mcpsdk" | "subagent" | "childmsg" | "subagentperm" | "toolsearch" | "p5compact" | "p5structured" | "p5structuredfail" | "p5skill" | "p5checkpoint" | "p5workflow" | "readimage";
+export type TestProviderName = "boom" | "tooluse" | "hang" | "reflect" | "modeswitch" | "bgtask" | "lanea" | "laneb" | "lanec" | "laned" | "lanee" | "mcpsdk" | "subagent" | "childmsg" | "subagentperm" | "toolsearch" | "p5compact" | "p5structured" | "p5structuredfail" | "p5skill" | "p5checkpoint" | "p5workflow" | "readimage" | "calls";
 export declare function isTestProviderName(v: string): v is TestProviderName;
 /**
  * The name the reserved `winter-test/<name>` namespace uses for the plain echo double.

package/dist/store/dialect.d.ts

@@ -478,7 +478,7 @@ export declare class TranscriptWriter implements SessionPersistence {
     private dialectRecord;
     static readBack(store: SessionStore, key: SessionKey): Promise<SessionStoreEntry[]>;
 }
-export declare const RUNTIME_ENGINE_VERSION = "0.0.36";
+export declare const RUNTIME_ENGINE_VERSION = "0.0.38";
 export interface ResolvedEngineSession {
     config: RuntimeConfig;
     store: SessionPersistence | undefined;

package/dist/subagents/child-engine.d.ts

@@ -130,6 +130,10 @@ export interface ChildEngineFactoryDeps {
      */
     parentAutoMemory?: RuntimeConfig["autoMemory"];
     parentWeb?: RuntimeConfig["web"];
+    /** `RuntimeConfig.reservedMcpServerNames`: an agent's own inline server never takes one (it is connected under a free name instead). */
+    parentReservedMcpServerNames?: RuntimeConfig["reservedMcpServerNames"];
+    /** `RuntimeConfig.legacyToolNames`, so a child resolves the host's old tool names as its parent does. */
+    parentLegacyToolNames?: RuntimeConfig["legacyToolNames"];
     /**
      * The session's pricing, stated-model and tool-secret seams, so a CHILD's engine has what its
      * parent's has. `priceUsage` is what makes a child's generations priced at all; the cost then
@@ -189,6 +193,27 @@ export interface ChildEngineFactoryDeps {
      */
     compactionControllerFactory?: () => CompactionController;
 }
+type ChildMcpServers = NonNullable<RuntimeConfig["mcpServers"]>;
+interface ChildServerAllocation {
+    /** The servers this generation connects itself, under the names it holds. */
+    servers: ChildMcpServers;
+    /** Declared name -> the name it is connected under (only for servers this generation connects). */
+    actual: Map<string, string>;
+    /** One legible line per server not connected under its declared name. */
+    notes: string[];
+    /**
+     * Declared names renamed because the HOST reserves them (`RuntimeConfig.reservedMcpServerNames`). Such a
+     * server is NOT "the server the definition named" for permission purposes: its declared spelling is the
+     * host's own server's, so it never becomes an extra identity (`mcpServerRenames`) — a saved rule on the
+     * host's `mcp__<reserved>__<tool>` must not reach it. Only its connected name governs it.
+     */
+    reservedRenames: Set<string>;
+    /** Releases every name this allocation claimed. Idempotent. */
+    release: () => void;
+}
+export declare function allocateChildScopedServers(declared: ChildMcpServers, parentVisible: ReadonlySet<string>, prefer?: ReadonlyMap<string, string>, parentDeclared?: Readonly<Record<string, {
+    type?: string;
+}>>, reserved?: readonly string[]): ChildServerAllocation;
 export declare function createChildEngineFactory(deps: ChildEngineFactoryDeps): ChildEngineFactory;
 /**
  * What a child reports when the SPENDING CEILING ended it (whole-branch review MINOR 9). One constant,
@@ -196,3 +221,4 @@ export declare function createChildEngineFactory(deps: ChildEngineFactoryDeps):
  * not be told a retry is worth trying: the ceiling is the session's, so a retry hits it again.
  */
 export declare const CHILD_BUDGET_STOP_TEXT = "The agent stopped because the session reached its spending limit (maxBudgetUsd), so no further model calls could be made. Retrying will not help -- continue with what it produced, or ask the user to raise the session's budget.";
+export {};

package/dist/testing.js

@@ -3,7 +3,7 @@ import {
   runEngine2,
   echoProvider2,
   resolveEngineSession2
-} from "./index-c8j57y8v.js";
+} from "./index-5xe59vkt.js";
 import"./index-1hef2gff.js";
 import"./index-mwew595z.js";
 import"./index-2wgfv0pa.js";
@@ -14,7 +14,7 @@ import {
   buildProductionWiring,
   withAutoSkillPermissions,
   restoreChildRoster
-} from "./index-83p1g9ap.js";
+} from "./index-z3970wsj.js";
 import {
   Queue
 } from "./index-97t2rmtf.js";

package/dist/tools/descriptors/index.d.ts

@@ -48,6 +48,7 @@ import "./task-output.ts";
 import "./task-stop.ts";
 import "./task-update.ts";
 import "./todo-write.ts";
+import "./search.ts";
 import "./tool-search.ts";
 import "./wait-for-mcp-servers.ts";
 import "./web-fetch.ts";

package/dist/tools/descriptors/search.d.ts

@@ -0,0 +1,4 @@
+export declare const SEARCH_CANONICAL_NAME = "Search";
+export declare const SEARCH_ANSWER_CAPABILITY = "winter.search-answer";
+/** The Winter daemon's own description, verbatim (it is the interface the models were shown). */
+export declare const SEARCH_DESCRIPTION = "Search the web and get back a written answer with its sources, in a single call. Ask a real question, not keywords \u2014 a search engine answers it and the answer comes back already synthesized, followed by the pages it came from. Use it freely whenever a fact might be newer than you are, or when the user asks about something current, and cite the URLs you used.";

package/dist/tools/impl/_exa-client.d.ts

@@ -31,6 +31,8 @@ export interface ExaSearchHit {
     /** The result's highlight text, capped at `EXA_HIGHLIGHTS_MAX_CHARACTERS`. Empty when the backend sent none. */
     highlight: string;
     publishedDate?: string;
+    /** The result's `favicon` when the backend sent one (Exa's /search reference: "The URL of the favicon for the search result's domain"), https only. Never model-visible: `WebSearch` hands it to the HOST as `ToolResultPayload.siteIcons`. Absent from the basic text form and, as measured 2026-09-18, from the advanced JSON form too -- read when present. */
+    favicon?: string;
 }
 export interface ExaSearchParams {
     query: string;

package/dist/tools/impl/_site-icons.d.ts

@@ -0,0 +1,17 @@
+import type { ToolResultSiteIcon } from "../registry.js";
+export declare const SITE_ICONS_MAX = 10;
+export declare const SITE_ICON_URL_MAX_LENGTH = 2048;
+/** A url a host may be handed: https, parseable, no credentials, re-serialised, within the cap. */
+export declare function siteIconHttpsUrl(value: unknown): string | undefined;
+/** A clean list: both urls of each entry checked, one entry per page url (first wins), capped. */
+export declare function collectSiteIcons(entries: Iterable<{
+    url: unknown;
+    iconUrl: unknown;
+}>): ToolResultSiteIcon[] | undefined;
+/**
+ * The icon `html` declares for the page at `pageUrl`, resolved against it: `apple-touch-icon` (large
+ * and opaque) over `icon` / `shortcut icon`, never a `mask-icon` (a monochrome stencil), an SVG (most
+ * hosts' image decoders cannot draw one) or a `data:` url. With none declared, the page origin's own
+ * `/favicon.ico`. Undefined when the page itself is not https (nothing is handed out for it).
+ */
+export declare function pageIconUrl(html: string, pageUrl: string): string | undefined;

package/dist/tools/impl/_web-fetch-cache.d.ts

@@ -9,6 +9,8 @@ export interface WebFetchCacheEntry {
     contentType: string;
     /** The URL actually fetched (after the https upgrade and any auto-followed same-host redirect) -- may differ from the cache key. */
     finalUrl: string;
+    /** The page's icon url (`_site-icons.ts`'s `pageIconUrl`), kept so a cache HIT still reports it to the host. */
+    iconUrl?: string;
 }
 export declare const WEB_FETCH_CACHE_TTL_MS: number;
 export declare const WEB_FETCH_CACHE_MAX_BYTES: number;

package/dist/tools/impl/index.d.ts

@@ -34,4 +34,5 @@ import "./skill.ts";
 import "./workflow.ts";
 import "./web-fetch.ts";
 import "./web-search.ts";
+import "./search.ts";
 export declare const EXECUTORS_WIRED = true;

package/dist/tools/impl/search.d.ts

@@ -0,0 +1,25 @@
+import "../descriptors/search.ts";
+import { type ToolExecutor } from "../registry.js";
+/** `/answer` SYNTHESIZES -- it runs a search and then writes a grounded answer over the results -- so it
+ *  is materially slower than a `/search` round trip; the daemon's 45 s, kept. */
+export declare const SEARCH_REQUEST_TIMEOUT_MS = 45000;
+/** The synthesized answer itself. */
+export declare const SEARCH_ANSWER_CHARS = 24000;
+/** Rendered as a sources list; the backend decides how many it used. */
+export declare const SEARCH_MAX_CITATIONS = 20;
+/** The whole response: the model's ENTIRE view of the search (a chat has no page-reading tool). */
+export declare const SEARCH_TOTAL_OUTPUT_CHARS = 30000;
+export declare const EXA_ANSWER_URL = "https://api.exa.ai/answer";
+/** One sentence per documented failure, each naming what clears it -- never the response body, which can
+ *  echo request headers (and so the key) and is third-party text besides. */
+export declare function searchStatusMessage(status: number): string;
+export declare const SEARCH_NO_KEY_MESSAGE = "Search needs an Exa API key (from exa.ai), and none is configured for this session";
+export interface SearchExecutorDeps {
+    /** Test seam: defaults to the global `fetch`. Tests point it at a loopback fixture. */
+    fetchFn?: typeof fetch;
+    /** Test seam: defaults to `EXA_ANSWER_URL`. */
+    endpoint?: string;
+    /** Test seam: defaults to `SEARCH_REQUEST_TIMEOUT_MS`. */
+    timeoutMs?: number;
+}
+export declare function createSearchExecutor(deps?: SearchExecutorDeps): ToolExecutor;

package/dist/tools/registry.d.ts

@@ -40,7 +40,11 @@ export interface AvailabilityPredicate {
     requiresToolSearchEnabled?: true;
     hiddenWhenFamilyTaskNative?: true;
     insideSubagent?: false;
+    optIn?: true;
+    requiresAnyCapability?: readonly string[];
 }
+/** Derived by the engine when the host's `deferTools` names anything: a built-in may then be deferred. */
+export declare const DEFERRED_BUILTINS_CAPABILITY = "winter.deferred-builtins";
 export type ToolDisposition = "implement-now" | "implement-later" | "correctly-absent" | "winter-backed-equivalent" | "winter-backed-later";
 export interface ToolDescriptor {
     canonicalName: string;
@@ -61,6 +65,7 @@ export interface ToolDescriptor {
     alwaysLoad?: boolean;
     _meta?: Record<string, unknown>;
     interaction?: "required";
+    mcpName?: string;
 }
 export interface ToolResultPayload {
     output: string;
@@ -75,6 +80,19 @@ export interface ToolResultPayload {
      */
     blocks?: ToolResultBlock[];
     isError?: boolean;
+    /**
+     * HOST-ONLY metadata, never model-visible: the sites this result names and the icon the tool knows
+     * for each (`WebFetch`: the page's own declared icon; `WebSearch`: Exa's `favicon`). The engine
+     * writes it ONLY onto the host-facing frame's `tool_result` block, as `winter_site_icons:
+     * [{url, icon_url}]` -- never into the model-facing content, the history, the transcript or a
+     * provider request. Built through `tools/impl/_site-icons.ts`'s `collectSiteIcons` (bounded, https).
+     */
+    siteIcons?: ToolResultSiteIcon[];
+}
+/** One `ToolResultPayload.siteIcons` entry: a page url the result names and its icon url. */
+export interface ToolResultSiteIcon {
+    url: string;
+    iconUrl: string;
 }
 /**
  * One block of a multimodal tool result (see `ToolResultPayload.blocks`). Structurally the engine's own
@@ -315,6 +333,20 @@ export interface McpToolDefinition {
     _meta?: Record<string, unknown>;
 }
 export declare function onRegistryChange(cb: () => void): () => void;
+/**
+ * A HOST'S PLAIN NAMES for some of one in-process server's tools (`McpSdkServerConfig.toolNames`):
+ * `{ <tool as the server lists it>: <plain name> }`. See that field's doc for the contract.
+ */
+export type McpServerToolNames = Readonly<Record<string, string>>;
+/** The search tool's name (descriptors/tool-search.ts): never deferred, and its absence from `tools` switches deferral off. */
+export declare const TOOL_SEARCH_TOOL_NAME = "ToolSearch";
+/** The `mcp__<server>__<tool>` spelling a plain-named MCP tool keeps as its equivalent identity, or `undefined`. */
+export declare function mcpSpellingOf(name: string): string | undefined;
+/**
+ * The registry name of `mcp__<server>__<tool>`: its plain name when the host renamed it, else the name itself.
+ * The inverse of `mcpSpellingOf`, for a reader handed the MCP spelling (a permission rule, a hook matcher).
+ */
+export declare function registeredNameForMcpSpelling(name: string): string;
 export declare function rebrandStandingServerTools(renames: ReadonlyArray<{
     from: string;
     to: string;
@@ -322,6 +354,7 @@ export declare function rebrandStandingServerTools(renames: ReadonlyArray<{
 export declare function registerMcpServerTools(server: string, incomingTools: readonly McpToolDefinition[], opts: {
     alwaysLoad?: boolean;
     deferredDefault: boolean | readonly PermissionMode[];
+    toolNames?: McpServerToolNames;
 }): void;
 /**
  * Fix round 20: the live MCP server that registered `canonicalName` through `registerMcpServerTools`,
@@ -354,6 +387,14 @@ export interface DeferralActivation {
     };
     providerSupportsToolSearch: boolean;
     deferrableContextShare: number;
+    /**
+     * The host's `deferTools` (`RuntimeConfig.deferTools`): names that START DEFERRED while deferral is
+     * active -- the one way a BUILT-IN defers (claude's own per-tool `shouldDefer`, chosen by the host here).
+     * `ToolSearch` is never deferred whatever this says, and an MCP tool's `alwaysLoad` still wins. Lives
+     * on the activation because every reader of `resolveDeferral` (the partition, the load-first boundary,
+     * ToolSearch's pool) already takes it, so none of them can disagree about it.
+     */
+    deferTools?: readonly string[];
 }
 export declare function isDeferralActive(activation: DeferralActivation): boolean;
 export declare function resolveDeferral(descriptor: ToolDescriptor, mode: PermissionMode, activation: DeferralActivation): "eager" | "deferred" | "hidden";
@@ -392,6 +433,21 @@ export declare function deriveRuntimeCapabilities(facts: SessionCapabilityFacts)
 export declare function resolveSessionCapabilities(hostSupplied: readonly string[] | undefined, facts: SessionCapabilityFacts): string[];
 export declare function isBareDenied(canonicalName: string, disallowedTools: readonly string[] | undefined): boolean;
 export declare function buildAdvertisedSet(cfg: AdvertisedSetInputs): ToolDescriptor[];
+/**
+ * `cfg.tools` (claude's own `tools` option -- `RuntimeConfig.tools`): it names the BUILT-IN set, so it
+ * filters built-ins only. An MCP server's tools (a plain-named in-process one included), the standing
+ * server's twins and host-generated tools are never named there and never removed by it -- the twins
+ * follow their native spelling through the alias pass instead (`hideAliasExcludedTwins`: a native the
+ * list leaves out is not advertised, so its twin is hidden). An OPT-IN built-in (`availability.optIn`)
+ * needs the list to name it; absent, the list is claude's default set, which carries none.
+ */
+export declare function isRequestedTool(descriptor: ToolDescriptor, tools: readonly string[] | undefined): boolean;
+/**
+ * A bare deny on the descriptor's own name OR on the `mcp__<server>__<tool>` spelling a plain-named
+ * in-process tool keeps (`ToolDescriptor.mcpName`): either spelling hides it, from advertisement and the
+ * ToolSearch pool alike (both read `buildAdvertisedSet`).
+ */
+export declare function isDescriptorBareDenied(descriptor: ToolDescriptor, disallowedTools: readonly string[] | undefined): boolean;
 export interface EngineToolCall {
     id: string;
     name: string;
@@ -408,6 +464,8 @@ export interface EngineToolResult {
      * success.
      */
     isError?: boolean;
+    /** See `ToolResultPayload.siteIcons`: host-only, written onto the host-facing frame and nowhere else. */
+    siteIcons?: ToolResultSiteIcon[];
 }
 export interface EngineFacingToolExecutor {
     /** Phase 6 Task 3 (R6-6): `opts.signal` is the engine's per-turn abort. It reaches a real executor as `ToolExecutionContext.signal`. */

package/dist/toolsearch/exposure.d.ts

@@ -6,6 +6,8 @@ export interface ExposureQuery {
     platform?: NodeJS.Platform;
     capabilities?: readonly string[];
     disallowedTools?: readonly string[];
+    /** The host's `tools` (claude's option, `RuntimeConfig.tools`): the built-in set -- the same filter `init.tools` applies. */
+    tools?: readonly string[];
     insideSubagent?: boolean;
     familyMetadata?: {
         taskNative?: boolean;

package/dist/toolsearch/search.d.ts

@@ -1,5 +1,5 @@
 import type { PermissionMode } from "@yanlinglabs/winter-agent-sdk";
-import type { DeferralActivation, ToolDescriptor } from "../tools/registry.js";
+import { type DeferralActivation, type ToolDescriptor } from "../tools/registry.js";
 import type { McpServerStateSource } from "../mcp/state.js";
 export interface FailedMcpServerEntry {
     name: string;
@@ -26,6 +26,10 @@ export interface ToolSearchDeps {
     platform?: NodeJS.Platform;
     capabilities?: readonly string[];
     disallowedTools?: readonly string[];
+    /** The host's `tools` (`RuntimeConfig.tools`): the built-in set, filtered exactly as `init.tools` is. */
+    tools?: readonly string[];
+    /** The engine's `currentToolName`: an old name (a renamed tool's MCP spelling, a host `legacyToolNames` entry) to the tool it means now. Default: the MCP-spelling half alone. */
+    resolveName?: (name: string) => string;
     insideSubagent?: boolean;
     familyMetadata?: {
         taskNative?: boolean;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.0.36";
+export declare const RUNTIME_VERSION = "0.0.38";

package/dist/version.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var RUNTIME_VERSION = "0.0.36";
+var RUNTIME_VERSION = "0.0.38";
 export {
   RUNTIME_VERSION
 };

package/dist/web/session-runtime.d.ts

@@ -74,6 +74,14 @@ export declare function inheritedWebSessionFacts(sessionId: string): Pick<WebSes
 export declare function resetWebSessionRuntimesForTest(): void;
 /** `winter.search-backend`'s session fact: the host has not switched the backend off. */
 export declare function searchBackendUsable(runtime: Pick<WebSessionRuntime, "web">): boolean;
+/**
+ * `winter.search-answer`'s session fact (the `Search` built-in): the backend is not switched off AND a
+ * key is NAMED (`web.search.authRef`) and there is a resolver to read it through. `/answer` has no
+ * anonymous tier, so a session without a key must never be offered a tool whose every call fails --
+ * whether the named key actually HOLDS material is only knowable asynchronously, and a missing one is a
+ * typed, actionable result at the first call.
+ */
+export declare function searchAnswerUsable(runtime: Pick<WebSessionRuntime, "web" | "resolveToolSecret">): boolean;
 /**
  * `winter.fetch-extractor`'s session fact: a digest model resolves.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-agent-runtime",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -73,9 +73,9 @@
     "@modelcontextprotocol/client": "^2.1.0",
     "ajv": "^8.20.0",
     "ignore": "7.0.5",
-    "@yanlinglabs/winter-provider-catalog": "0.0.36",
-    "@yanlinglabs/winter-provider-runtime": "0.0.36",
-    "@yanlinglabs/winter-agent-sdk": "0.0.36"
+    "@yanlinglabs/winter-agent-sdk": "0.0.38",
+    "@yanlinglabs/winter-provider-runtime": "0.0.38",
+    "@yanlinglabs/winter-provider-catalog": "0.0.38"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.1.0"