@yanlinglabs/winter-agent-sdk 0.0.35 → 0.0.38

package/README.md

@@ -128,6 +128,37 @@ runtime's own — same descriptions, same input schemas, same inner-call prompts
 Withdraw either with `disallowedTools`. `WebSearch` can also be switched off at the backend with
 `web.search.enabled: false`.
 
+- **`Search`** (opt-in, unreleased) takes `{query}` and returns Exa's answer mode: a written answer
+  and the pages it came from, in one call. It is offered only when `Options.tools` names it and
+  `web.search.authRef` names a key (the answer endpoint has no anonymous tier). The cited urls pass
+  the same `blockedDomains` floor, and a withheld source is counted in the result.
+
+All three report the icon of each site they name to the HOST only, as `winter_site_icons:
+[{url, icon_url}]` on the host-facing `tool_result` block. The model never sees it.
+
+### Shaping the tool surface (0.0.38)
+
+- **`Options.tools`** — claude's own option: the built-in tool set by name, or the `claude_code`
+  preset (the same as leaving it out). A visibility list: a built-in left out is not advertised, not
+  searchable, and refused at dispatch. MCP servers' tools are never filtered by it. Without `ToolSearch`
+  in it, nothing is deferred.
+- **`Options.deferTools`** — tools that start deferred while Tool Search is active (`toolSearchEnabled`),
+  loaded through `ToolSearch` on first use. This is the only way a built-in defers.
+- **`McpSdkServerConfig.toolNames`** — plain names for an in-process server's tools (`{ browser:
+  "Browser" }`). The model, the transcript, hooks and `canUseTool` all see the plain name. The call still
+  reaches the host as `sdk_mcp_call` with the server's own tool name, and the tool still defers like an
+  MCP tool. The `mcp__<server>__<tool>` spelling stays an equivalent identity for permission rules,
+  `disallowedTools` and hook matchers; when one of those names it, the call is evaluated under that
+  spelling, as for an alias. A plain name that collides with another tool refuses the session. The old
+  spelling also selects the tool in a model call, `ToolSearch`'s `select:` and an agent definition's
+  `tools`.
+- **`Options.legacyToolNames`** — `{ <old name>: <current tool name> }` for a host's own renamed tool:
+  the old name keeps working in calls, `select:`, agent definitions, rules, `disallowedTools` and hook
+  matchers.
+- **`Options.reservedMcpServerNames`** — server names only the host's own `type: "sdk"` servers may
+  take; any other server under one (settings, project, plugin, explicit non-sdk, `mcp_set_servers`) is
+  refused, and an agent definition's inline server is renamed.
+
 - **`Options.web`** — `search.enabled`, `search.authRef` (the backend key, used only once the
   anonymous tier is exhausted), `search.maxSearchesPerCall` / `search.anonymousMaxSearchesPerCall`,
   `fetch.digestModel` / `fetch.authRef` (the page-digest model and its own credential),

package/dist/index.js

@@ -419,7 +419,8 @@ function toWireMcpServers(servers) {
       type: "sdk",
       name: cfg.name,
       ...cfg.timeout !== undefined ? { timeout: cfg.timeout } : {},
-      ...isWinterMcpServerInstance(cfg.instance) ? { tools: cfg.instance.listTools() } : {}
+      ...isWinterMcpServerInstance(cfg.instance) ? { tools: cfg.instance.listTools() } : {},
+      ...cfg.toolNames !== undefined ? { toolNames: { ...cfg.toolNames } } : {}
     } : cfg;
   }
   return out;
@@ -630,6 +631,15 @@ function makeHookHandler(hooks, cwd, abortController) {
 function isModelFamilyListing(payload) {
   return typeof payload === "object" && payload !== null && Array.isArray(payload.families);
 }
+function abortedBeforeSpawn() {
+  return {
+    stdin: { write() {}, end() {} },
+    stdout: async function* () {}(),
+    kill() {},
+    exited: Promise.resolve({ code: null, signal: "SIGTERM" }),
+    pid: null
+  };
+}
 function query(args) {
   const { prompt, options } = args;
   if (options.canUseTool) {
@@ -689,6 +699,10 @@ function query(args) {
     ...options.toolSearchEnabled !== undefined ? { toolSearchEnabled: options.toolSearchEnabled } : {},
     ...options.insideSubagent !== undefined ? { insideSubagent: options.insideSubagent } : {},
     ...options.familyMetadata !== undefined ? { familyMetadata: options.familyMetadata } : {},
+    ...Array.isArray(options.tools) ? { tools: [...options.tools] } : {},
+    ...options.deferTools !== undefined ? { deferTools: [...options.deferTools] } : {},
+    ...options.legacyToolNames !== undefined ? { legacyToolNames: { ...options.legacyToolNames } } : {},
+    ...options.reservedMcpServerNames !== undefined ? { reservedMcpServerNames: [...options.reservedMcpServerNames] } : {},
     ...options.allowDangerouslySkipPermissions !== undefined ? { allowDangerouslySkipPermissions: options.allowDangerouslySkipPermissions } : {},
     ...runtimeHooksConfig !== undefined ? { hooks: runtimeHooksConfig } : {},
     ...options.includeHookEvents !== undefined ? { includeHookEvents: options.includeHookEvents } : {},
@@ -735,8 +749,33 @@ function query(args) {
     env: withTestKeychainRedirect(options.env) ?? process.env,
     ...options.abortController ? { signal: options.abortController.signal } : {}
   };
-  const proc = (options.spawnClaudeCodeProcess ?? defaultSpawn)(spawnOptions);
+  const proc = options.abortController?.signal.aborted === true ? abortedBeforeSpawn() : (options.spawnClaudeCodeProcess ?? defaultSpawn)(spawnOptions);
   const maxBufferSize = options.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+  let killRequested = false;
+  let spawnKillEscalation;
+  const killForAbort = () => {
+    if (killRequested)
+      return;
+    killRequested = true;
+    try {
+      proc.kill();
+    } catch {}
+    spawnKillEscalation = setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {}
+    }, KILL_GRACE_MS);
+    spawnKillEscalation.unref?.();
+    const clear = () => clearTimeout(spawnKillEscalation);
+    proc.exited.then(clear, clear);
+  };
+  let removeSpawnAbortListener = () => {};
+  if (options.abortController !== undefined && options.abortController.signal.aborted !== true) {
+    const signal = options.abortController.signal;
+    signal.addEventListener("abort", killForAbort, { once: true });
+    removeSpawnAbortListener = () => signal.removeEventListener("abort", killForAbort);
+    proc.exited.then(removeSpawnAbortListener, removeSpawnAbortListener);
+  }
   const pendingHostRequests = new Map;
   let generatorTerminated = false;
   function sendControlRequest(subtype, payload) {
@@ -877,9 +916,15 @@ function query(args) {
       if (aborted)
         return;
       aborted = true;
+      if (killRequested)
+        return;
+      killRequested = true;
       proc.kill();
       killTimer = setTimeout(() => proc.kill("SIGKILL"), KILL_GRACE_MS);
       killTimer.unref?.();
+      const timer = killTimer;
+      const clear = () => clearTimeout(timer);
+      proc.exited.then(clear, clear);
     };
     options.abortController?.signal.addEventListener("abort", onAbort);
     try {
@@ -979,8 +1024,7 @@ function query(args) {
     } finally {
       generatorTerminated = true;
       options.abortController?.signal.removeEventListener("abort", onAbort);
-      if (killTimer)
-        clearTimeout(killTimer);
+      removeSpawnAbortListener();
       try {
         proc.stdin.end();
       } catch {}
@@ -1136,7 +1180,7 @@ function withTestKeychainRedirect(env) {
   return { ...env, [TEST_KEYCHAIN_ENV]: redirect };
 }
 // src/version.ts
-var SDK_VERSION = "0.0.35";
+var SDK_VERSION = "0.0.38";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;

package/dist/options.d.ts

@@ -155,6 +155,29 @@ export interface Options {
     familyMetadata?: {
         taskNative?: boolean;
     };
+    /**
+     * claude's own `tools` option: the BUILT-IN tool set, by name -- an array, or the `claude_code` preset
+     * (every built-in, the same as leaving it out). It is a VISIBILITY list, unlike `allowedTools` (which
+     * pre-approves): a built-in left out is not advertised, not searchable, and refused at dispatch as a
+     * tool the model was not offered. MCP servers' tools (including an in-process server's plain-named
+     * ones, `McpSdkServerConfig.toolNames`) are never filtered by it -- name only built-ins here. Leaving
+     * `ToolSearch` out switches deferral off, as in claude. Opt-in built-ins (`Search`) are advertised only
+     * when this list names them. See `RuntimeConfig.tools`.
+     */
+    tools?: string[] | {
+        type: "preset";
+        preset: "claude_code";
+    };
+    /**
+     * DISCLOSED WINTER option: tools that start DEFERRED (loaded through `ToolSearch` on first use) while
+     * Tool Search is active -- the host's way to defer a BUILT-IN (`CronList`), which otherwise never
+     * defers. See `RuntimeConfig.deferTools`.
+     */
+    deferTools?: string[];
+    /** DISCLOSED WINTER option: a tool's old names, `{ <old>: <current> }`. See `RuntimeConfig.legacyToolNames`. */
+    legacyToolNames?: Record<string, string>;
+    /** DISCLOSED WINTER option: MCP server names only the host's own in-process servers may use. See `RuntimeConfig.reservedMcpServerNames`. */
+    reservedMcpServerNames?: string[];
     allowDangerouslySkipPermissions?: boolean;
     canUseTool?: CanUseTool;
     hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;

package/dist/protocol/config.d.ts

@@ -279,6 +279,28 @@ export interface McpSdkServerConfig {
     name: string;
     timeout?: number;
     tools?: WireMcpToolDefinition[];
+    /**
+     * WINTER-OWNED EXTENSION: advertise some of this in-process server's tools under a HOST-CHOSEN plain
+     * name instead of `mcp__<server>__<tool>` -- `{ <tool as listTools() names it>: <plain name> }`.
+     *
+     * A renamed tool is an ordinary-looking tool to the model (`Browser`, never `mcp__…`) and that ONE name
+     * is its identity everywhere a name is carried: the provider request, the transcript, the host's frames,
+     * hook inputs' `tool_name`, `canUseTool`, `permission_denials`. Underneath it is still this server's MCP
+     * tool: it defers like one (unless `_meta["anthropic/alwaysLoad"]`), the call still arrives at the host
+     * as `sdk_mcp_call {server, tool}` with the ORIGINAL tool name, and `winter_mcp_server` / `canUseTool`'s
+     * `mcpServer` still name the server. The old `mcp__<server>__<tool>` spelling stays an EQUIVALENT
+     * identity: a permission rule (`mcp__<server>__<tool>`, `mcp__<server>__*`), a bare `disallowedTools`
+     * entry or a hook matcher written against it governs the renamed tool too (strictest-of, as for an
+     * alias) -- and, as for an alias, the call is then evaluated UNDER that spelling: the hook it selected
+     * and the prompt its ask rule raised carry `mcp__<server>__<tool>` as `tool_name`. A model call under the
+     * old spelling (a resumed history) runs as the renamed tool.
+     *
+     * A plain name must look like a tool name (`[A-Za-z][A-Za-z0-9_-]*`, at most 64 characters), must not
+     * start with `mcp__`, and must not collide with any other registered tool -- a collision refuses the
+     * session at startup rather than shadowing a tool. Only an in-process (`sdk`) server may rename; the
+     * host owns it.
+     */
+    toolNames?: Record<string, string>;
 }
 export type McpServerConfigForProcessTransport = McpStdioServerConfig | McpHttpServerConfig | McpSSEServerConfig | McpSdkServerConfig;
 export type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
@@ -389,6 +411,44 @@ export interface RuntimeConfig {
     familyMetadata?: {
         taskNative?: boolean;
     };
+    /**
+     * `Options.tools` (claude's own option): the BUILT-IN tool set this session is offered, by name.
+     * Absent = every built-in (claude's `claude_code` preset, which the wrapper serializes as absent).
+     * Filters built-ins only -- an MCP server's tools, a host's plain-named in-process tools and
+     * host-generated tools (`StructuredOutput`) are never named here and never filtered by it. A built-in
+     * left out is not advertised, not in ToolSearch's pool and refused at dispatch as a tool the model
+     * was not offered. `ToolSearch` left out switches deferral off (claude's rule: no search tool, no
+     * deferred tools). A few built-ins (`Search`) are OPT-IN: advertised only when this list names them.
+     */
+    tools?: string[];
+    /**
+     * Winter extension: tools that START DEFERRED -- loaded through `ToolSearch` on first use -- when Tool
+     * Search is active. A built-in otherwise never defers; an MCP tool already does (unless its
+     * `_meta["anthropic/alwaysLoad"]`, which still wins). `ToolSearch` itself is never deferred.
+     * Inert while deferral is inactive (full injection).
+     */
+    deferTools?: string[];
+    /**
+     * Winter extension: a tool's OLD names -- `{ <old name>: <current tool name> }` -- for a host whose
+     * own tool became another one (a host's in-process `mcp__<server>__Search` became the `Search`
+     * built-in). The old name keeps working everywhere a name is read: a model call under it (a resumed
+     * history taught it) runs the current tool, `ToolSearch`'s `select:` finds it, an agent definition's
+     * `tools` list keeps it, a rule, bare `disallowedTools` entry or hook matcher naming it governs the
+     * current tool (strictest-of, as for an alias). A plain-named in-process tool's own
+     * `mcp__<server>__<tool>` spelling needs no entry here: it is resolved the same way by itself. A key
+     * that names a registered tool is ignored (the live tool wins).
+     */
+    legacyToolNames?: Record<string, string>;
+    /**
+     * Winter extension: MCP server NAMES no server may take in this session except the host's own
+     * in-process (`type: "sdk"`) servers in `mcpServers` -- whatever its origin: a settings scope, a plugin's
+     * `.mcp.json`, an explicit non-sdk entry, the live `mcp_set_servers` door (each refused typed
+     * `reserved_name` and never connected), and an agent definition's inline server (connected under a
+     * renamed `<name>_<n>`, as for any clash; an inline in-process one under a reserved name is not
+     * connected). For a host whose own tools are classified by their server (trust keyed on
+     * `mcp__<server>__*`), so no foreign server can wear that spelling.
+     */
+    reservedMcpServerNames?: string[];
     mcpServers?: Record<string, McpServerConfigForProcessTransport>;
     strictMcpConfig?: boolean;
     toolAliases?: Record<string, string>;

package/dist/protocol/frames.d.ts

@@ -306,6 +306,16 @@ export type WireContentBlock = {
     tool_use_id: string;
     content: string | WireContentBlock[];
     is_error?: boolean;
+    /**
+     * Winter-only, HOST-facing frame only (never model-visible, never in a transcript): the sites a web
+     * tool's result names and the icon the tool knows for each -- `WebFetch`'s page icon (the page's
+     * own declared `<link rel=icon>`, else its origin's `/favicon.ico`), `WebSearch`'s Exa `favicon`.
+     * At most 10 entries; every url https. Absent on every other result.
+     */
+    winter_site_icons?: Array<{
+        url: string;
+        icon_url: string;
+    }>;
     [k: string]: unknown;
 } | {
     type: "image";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-agent-sdk",
-  "version": "0.0.35",
+  "version": "0.0.38",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,15 +45,15 @@
     }
   },
   "dependencies": {
-    "@yanlinglabs/winter-provider-catalog": "0.0.35"
+    "@yanlinglabs/winter-provider-catalog": "0.0.38"
   },
   "optionalDependencies": {
-    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.35"
+    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.38"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "@yanlinglabs/winter-conformance": "0.0.35",
-    "@yanlinglabs/winter-agent-runtime": "0.0.35"
+    "@yanlinglabs/winter-agent-runtime": "0.0.38",
+    "@yanlinglabs/winter-conformance": "0.0.38"
   },
   "scripts": {}
 }