@yanlinglabs/winter-agent-sdk 0.0.16 → 0.0.20

package/README.md

@@ -84,6 +84,7 @@ build (`BrandProfile.envPrefix`); a rebranded host reads the identical suffix un
 | `WINTER_DISABLE_EXPLORE_INHERIT_CAP` | off | Truthy opts a first-party Anthropic session out of the Explore built-in's own model cap (which otherwise caps a Fable-tier session's Explore spawn down to Opus). |
 | `WINTER_FORK_SUBAGENT` | off | Truthy enables `subagent_type: "fork"` for the session (mirrors `CLAUDE_CODE_FORK_SUBAGENT`). `Options.forkSubagent` (below) wins over this variable in either direction. |
 | `WINTER_WEB_FETCH_AGENT` | off | Truthy makes the `web-fetch` built-in agent type available (off by default, like claude's own). |
+| `WINTER_MAX_WEB_SEARCHES_PER_SESSION` | `200` | How many `WebSearch` calls one session may make, counted before each search and shared with every descendant subagent (the analogue of `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`). Past it, a call answers with a plain refusal result rather than an error. |
 | `WINTER_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | off | Truthy withholds every built-in `subagent_type` (gated or not) for the session. |
 | `WINTER_DISABLE_EXPLORE_PLAN_AGENTS` | off | Truthy withholds the `Explore` and `Plan` built-ins together. |
 | `WINTER_DISABLE_AGENT_VIEW` | off | Truthy withholds the `claude` catch-all built-in (mirrors `CLAUDE_CODE_DISABLE_AGENT_VIEW`). |
@@ -107,6 +108,43 @@ never the full universe of types its parent session could otherwise reach. Absen
 session, and any child whose parent definition named no `Agent(...)` restriction) means
 unrestricted, the behavior every session had before this field existed.
 
+### The built-in web tools (since 0.0.17)
+
+`WebFetch` and `WebSearch` ship in every default `init.tools`, as copies of the pinned `claude`
+runtime's own — same descriptions, same input schemas, same inner-call prompts, same output assembly.
+
+- **`WebFetch`** takes `{url, prompt}`, fetches the page from this machine (`http` is upgraded to
+  `https` unconditionally, and a hostname with fewer than two dot-separated labels is refused — so
+  `localhost` and IPv6 literals are not fetchable, exactly as in claude), converts HTML to markdown,
+  and answers `prompt` over it with a small fast model. Responses are cached for 15 minutes per
+  session. Rules are `WebFetch(domain:<host>)`; an allow rule naming an exact host is standing consent
+  for that host wherever it resolves.
+- **`WebSearch`** takes `{query, allowed_domains?, blocked_domains?}` and runs one inner pass over the
+  search backend, returning titles and urls only. The budget is 200 calls per session
+  (`WINTER_MAX_WEB_SEARCHES_PER_SESSION`), shared with every descendant. Its only rule form is the
+  bare `WebSearch`; a scoped `WebSearch(...)` in `Options.allowedTools`/`disallowedTools` throws at
+  startup (a settings file drops it and warns).
+
+Withdraw either with `disallowedTools`. `WebSearch` can also be switched off at the backend with
+`web.search.enabled: false`.
+
+- **`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),
+  `fetch.privateAddressPolicy` (`"ask"` by default, `"deny"` / `"allow"`), and one `blockedDomains`
+  floor both tools honour (suffix match on a label boundary: `example.com` covers
+  `docs.example.com`). Every field is optional; `resolveWebToolsConfig` + `WEB_TOOLS_DEFAULTS` are
+  exported for a host that wants the resolved shape. **An unattended host should set
+  `fetch.privateAddressPolicy: "deny"`** — under the default a private or loopback target raises a real
+  permission prompt, and a session that cannot prompt refuses the call.
+- **`Options.autoMemory`** — `enabled` and `directory` for the auto-memory section, for a host that
+  runs with `settingSources: []` and therefore cannot reach `autoMemoryEnabled` /
+  `autoMemoryDirectory` in a settings file. Precedence per field: this option, then the settings key,
+  then the computed default (`<home>/projects/<memory-key>/memory`, enabled). A relocated directory
+  under the home's own `projects/` tree stays write-denied.
+
+Subagents inherit both.
+
 ### The 0.0.16 background-default change
 
 Before 0.0.16, an Agent tool call with no `run_in_background` ran in the **foreground** (this call

package/dist/index.d.ts

@@ -4,6 +4,9 @@ export type { QueryInternal, ControlRequestHandler, ControlRequestHandlerResult
 export type { Options } from "./options.js";
 export { SYSTEM_PROMPT_DYNAMIC_BOUNDARY, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_PLANS_DIRECTORY, DEFAULT_OUTPUT_STYLE } from "./options.js";
 export { DEFAULT_PROVIDER_STALL_TIMEOUT_MS, DEFAULT_KEYCHAIN_SERVICE } from "./options.js";
+export { WEB_TOOLS_DEFAULTS, resolveWebToolsConfig } from "./options.js";
+export type { ResolvedWebToolsConfig } from "./options.js";
+export type { WebToolsConfig, WebSearchConfig, WebFetchConfig, WebPrivateAddressPolicy, AutoMemoryConfig } from "./protocol/config.js";
 export type { ProviderSelection, ProviderConnectionConfig, CredentialRef, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, ModelInfo, AgentInfo, AccountInfo } from "./protocol/config.js";
 export type { SlotView, ActiveSlotSet, ModelFamilyListing, ModelSlotSetting, ModelRowServable } from "./protocol/config.js";
 export type { SdkPluginConfig, SystemPromptOption, SystemPromptPreset, OutputFormat, JsonSchemaOutputFormat, SkillsOption, RewindFilesResult, RewindFilesRequest, InitPluginInfo } from "./protocol/config.js";
@@ -24,7 +27,7 @@ export { SDK_VERSION } from "./version.js";
 export { MESSAGING_CONTROL_SUBTYPES, MESSAGING_CONTROL_SUBTYPE_LIST, MESSAGING_HOST_REQUEST_SUBTYPES, MESSAGING_RUNTIME_REQUEST_SUBTYPES, resolveFacetTarget } from "./protocol/messaging.js";
 export { isRuntimeAddress, isGlobalAgentMessage, isDeliveryOutcome, isListedRuntimeObjectArray, isPermissionClassLabel, isMessagingDeliverRequest, isMessagingChildRequest, isMessagingSubscribeIdleRequest, isMessagingReadNotificationsRequest, isMessagingNotificationsPage, isMessagingIdleNoticePayload, isNotificationRecord, } from "./protocol/messaging.js";
 export type { MessagingControlSubtype, MessagingDeliverRequest, MessagingChildRequest, MessagingSubscribeIdleRequest, MessagingSenderClassResponse, MessagingReadNotificationsRequest, MessagingNotificationsPage, MessagingIdleNoticePayload, } from "./protocol/messaging.js";
-export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, SDKSessionStateChangedMessage, WireContentBlock, WireStreamEvent, WireStreamEventDelta, SDKPartialAssistantMessage, SDKAssistantMessageError, SDKAPIRetryMessage, SDKRateLimitEvent, SDKRateLimitInfo, SDKAuthStatusMessage, SDKThinkingTokensMessage, SDKModelRefusalFallbackMessage, SDKModelRefusalNoFallbackMessage, SDKReasoningSummaryMessage, SDKModelSwitchMessage, SDKContinuityWarningMessage, } from "./protocol/frames.js";
+export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, ControlCancelRequestFrame, WireResultUsage, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, SDKSessionStateChangedMessage, WireContentBlock, WireStreamEvent, WireStreamEventDelta, SDKPartialAssistantMessage, SDKAssistantMessageError, SDKAPIRetryMessage, SDKRateLimitEvent, SDKRateLimitInfo, SDKAuthStatusMessage, SDKThinkingTokensMessage, SDKModelRefusalFallbackMessage, SDKModelRefusalNoFallbackMessage, SDKReasoningSummaryMessage, SDKModelSwitchMessage, SDKContinuityWarningMessage, } from "./protocol/frames.js";
 export { resolveWinterHome, resolveKeychainServiceForProfile, isUnset } from "./paths/home.js";
 export { transcriptProjectKey, TRANSCRIPT_PROJECT_KEY_MAX_LENGTH, isVendorCompliantProjectKey } from "./paths/project-key.js";
 export { compatibilityKeys } from "./paths/keys.js";

package/dist/index.js

@@ -66,6 +66,38 @@ var DEFAULT_PLANS_DIRECTORY = `${WINTER_BRAND2.projectDirName}/plans`;
 var DEFAULT_OUTPUT_STYLE = "default";
 var DEFAULT_PROVIDER_STALL_TIMEOUT_MS = 120000;
 var DEFAULT_KEYCHAIN_SERVICE = WINTER_BRAND2.keychainService;
+var WEB_TOOLS_DEFAULTS = {
+  searchEnabled: true,
+  maxSearchesPerCall: 8,
+  anonymousMaxSearchesPerCall: 3,
+  privateAddressPolicy: "ask"
+};
+function positiveIntegerOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback;
+}
+var PRIVATE_ADDRESS_POLICIES = ["allow", "ask", "deny"];
+function resolveWebToolsConfig(web) {
+  const rawDigest = web?.fetch?.digestModel;
+  const digestModel = typeof rawDigest === "string" ? rawDigest.trim() : undefined;
+  const rawPolicy = web?.fetch?.privateAddressPolicy;
+  const privateAddressPolicy = PRIVATE_ADDRESS_POLICIES.find((policy) => policy === rawPolicy) ?? WEB_TOOLS_DEFAULTS.privateAddressPolicy;
+  const rawEnabled = web?.search?.enabled;
+  const rawBlocked = web?.blockedDomains;
+  return {
+    search: {
+      enabled: rawEnabled === undefined ? WEB_TOOLS_DEFAULTS.searchEnabled : rawEnabled === true,
+      ...web?.search?.authRef !== undefined ? { authRef: web.search.authRef } : {},
+      maxSearchesPerCall: positiveIntegerOr(web?.search?.maxSearchesPerCall, WEB_TOOLS_DEFAULTS.maxSearchesPerCall),
+      anonymousMaxSearchesPerCall: positiveIntegerOr(web?.search?.anonymousMaxSearchesPerCall, WEB_TOOLS_DEFAULTS.anonymousMaxSearchesPerCall)
+    },
+    fetch: {
+      ...digestModel !== undefined && digestModel.length > 0 ? { digestModel } : {},
+      ...web?.fetch?.authRef !== undefined ? { authRef: web.fetch.authRef } : {},
+      privateAddressPolicy
+    },
+    blockedDomains: (Array.isArray(rawBlocked) ? rawBlocked : []).filter((d) => typeof d === "string" && d.trim().length > 0)
+  };
+}
 function isWinterMcpServerInstance(value) {
   if (typeof value !== "object" || value === null)
     return false;
@@ -601,6 +633,8 @@ function query(args) {
     ...brand.keychainService !== WINTER_BRAND2.keychainService || options.keychainService !== undefined ? { keychainService: brand.keychainService } : {},
     ...options.autoClassifier !== undefined ? { autoClassifier: options.autoClassifier } : {},
     ...options.advisor !== undefined ? { advisor: options.advisor } : {},
+    ...options.web !== undefined ? { web: options.web } : {},
+    ...options.autoMemory !== undefined ? { autoMemory: options.autoMemory } : {},
     brand
   };
   const command = options.spawnClaudeCodeProcess ? options.pathToClaudeCodeExecutable ?? "winter" : resolveRuntimeExecutable(options);
@@ -632,6 +666,7 @@ function query(args) {
     proc.stdin.write(encodeFrame(frame));
   }
   const controlRequestHandlers = new Map;
+  const incomingRequestAborts = new Map;
   async function handleIncomingControlRequest(cf) {
     try {
       const handler = controlRequestHandlers.get(cf.subtype);
@@ -644,8 +679,12 @@ function query(args) {
         });
         return;
       }
+      const cancel = new AbortController;
+      incomingRequestAborts.set(cf.requestId, cancel);
       try {
-        const result = await handler(cf.payload);
+        const result = await handler(cf.payload, { signal: cancel.signal });
+        if (cancel.signal.aborted)
+          return;
         if (result.ok) {
           writeControlResponse({
             type: "control_response",
@@ -657,19 +696,27 @@ function query(args) {
           writeControlResponse({ type: "control_response", requestId: cf.requestId, ok: false, error: result.error });
         }
       } catch (err) {
+        if (cancel.signal.aborted)
+          return;
         const message = err instanceof Error ? err.message : String(err);
         writeControlResponse({ type: "control_response", requestId: cf.requestId, ok: false, error: { code: "handler_threw", message } });
+      } finally {
+        incomingRequestAborts.delete(cf.requestId);
       }
     } catch {}
   }
   function makePermissionHandler(canUseTool) {
-    return async (payload) => {
+    return async (payload, handlerCtx) => {
       const req = payload;
       const controller = new AbortController;
       if (options.abortController?.signal.aborted)
         controller.abort();
       else
         options.abortController?.signal.addEventListener("abort", () => controller.abort(), { once: true });
+      if (handlerCtx?.signal.aborted === true)
+        controller.abort();
+      else
+        handlerCtx?.signal.addEventListener("abort", () => controller.abort(), { once: true });
       let result;
       try {
         result = await canUseTool(req.toolName, req.input, {
@@ -794,6 +841,13 @@ function query(args) {
               }
               continue;
             }
+            if (frame.type === "control_cancel_request") {
+              const cancelledId = frame.requestId ?? "";
+              const cancelled = incomingRequestAborts.get(cancelledId);
+              incomingRequestAborts.delete(cancelledId);
+              cancelled?.abort();
+              continue;
+            }
             if (frame.type === "control_request") {
               handleIncomingControlRequest(frame);
               continue;
@@ -967,7 +1021,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.16";
+var SDK_VERSION = "0.0.20";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -1010,13 +1064,41 @@ function resolveCanonical(raw) {
   }
 }
 function gitCommonRoot(resolvedCwd) {
+  let commonDir;
+  try {
+    const raw = runGit(["-C", resolvedCwd, "rev-parse", "--git-common-dir"]);
+    commonDir = platformNormalize(realpathSync(isAbsolute(raw) ? raw : resolvePath(resolvedCwd, raw)));
+  } catch {
+    return null;
+  }
+  const candidate = dirname2(commonDir);
+  if (isWithin(resolvedCwd, candidate))
+    return candidate;
+  if (registeredWorktrees(commonDir).some((worktree) => isWithin(resolvedCwd, worktree)))
+    return candidate;
+  const configured = configuredWorktree(commonDir);
+  if (configured !== null && isWithin(resolvedCwd, configured))
+    return configured;
+  return null;
+}
+function runGit(args) {
+  return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+function isWithin(path, dir) {
+  return path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`);
+}
+function registeredWorktrees(commonDir) {
+  try {
+    return runGit(["--git-dir", commonDir, "worktree", "list", "--porcelain"]).split(`
+`).filter((line) => line.startsWith("worktree ")).map((line) => resolveCanonical(line.slice("worktree ".length)));
+  } catch {
+    return [];
+  }
+}
+function configuredWorktree(commonDir) {
   try {
-    const raw = execFileSync("git", ["-C", resolvedCwd, "rev-parse", "--git-common-dir"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    const commonDir = isAbsolute(raw) ? raw : resolvePath(resolvedCwd, raw);
-    return platformNormalize(dirname2(realpathSync(commonDir)));
+    const raw = runGit(["--git-dir", commonDir, "config", "--get", "core.worktree"]);
+    return raw.length > 0 ? resolveCanonical(isAbsolute(raw) ? raw : resolvePath(commonDir, raw)) : null;
   } catch {
     return null;
   }
@@ -1690,6 +1772,7 @@ export {
   SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
   SessionNotFoundError,
   TRANSCRIPT_PROJECT_KEY_MAX_LENGTH,
+  WEB_TOOLS_DEFAULTS,
   WINTER_BRAND2 as WINTER_BRAND,
   WinterCompatibilitySessionStore2 as WinterCompatibilitySessionStore,
   WinterRpcError,
@@ -1738,6 +1821,7 @@ export {
   resolveRuntimeExecutable,
   resolveSettings,
   resolveSettingsDetailed,
+  resolveWebToolsConfig,
   resolveWinterHome2 as resolveWinterHome,
   settingsPathFor,
   splitFrames,

package/dist/options.d.ts

@@ -1,12 +1,13 @@
 import type { SpawnClaudeCodeProcess } from "./transport.js";
 import type { PermissionMode, CanUseTool, HookEvent, HookCallbackMatcher } from "./permissions/types.js";
-import type { SandboxSettingsConfig, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, RuntimeAgentDefinition, SdkPluginConfig, SystemPromptOption, OutputFormat, SkillsOption, ProviderSelection, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig } from "./protocol/config.js";
+import type { SandboxSettingsConfig, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, RuntimeAgentDefinition, SdkPluginConfig, SystemPromptOption, OutputFormat, SkillsOption, ProviderSelection, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, WebToolsConfig, WebPrivateAddressPolicy, AutoMemoryConfig, CredentialRef } from "./protocol/config.js";
 import type { SettingSource } from "./settings/types.js";
 import type { SessionStore } from "./store/session-store.js";
 import { type BrandProfile } from "./brand.js";
 export type { BrandProfile, BrandValidation } from "./brand.js";
 export type { SdkPluginConfig, SystemPromptOption, OutputFormat, JsonSchemaOutputFormat, SkillsOption } from "./protocol/config.js";
 export type { ProviderSelection, ProviderConnectionConfig, CredentialRef, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig } from "./protocol/config.js";
+export type { WebToolsConfig, WebSearchConfig, WebFetchConfig, WebPrivateAddressPolicy, AutoMemoryConfig } from "./protocol/config.js";
 export declare const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__";
 export declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 200000;
 export declare const DEFAULT_COMPACTION_THRESHOLD = 0.92;
@@ -14,6 +15,42 @@ export declare const DEFAULT_PLANS_DIRECTORY: string;
 export declare const DEFAULT_OUTPUT_STYLE = "default";
 export declare const DEFAULT_PROVIDER_STALL_TIMEOUT_MS = 120000;
 export declare const DEFAULT_KEYCHAIN_SERVICE: string;
+/**
+ * Every web-tool default, spelled ONCE. A reader function resolves an absent field against this --
+ * no consumer writes a literal of its own.
+ *
+ * `maxSearchesPerCall: 8` is the pinned tool's own per-call bound. `anonymousMaxSearchesPerCall: 3`
+ * is Winter's: see `WebSearchConfig.anonymousMaxSearchesPerCall`. `privateAddressPolicy: "ask"` is
+ * the conservative interactive posture; a host that can never ask sets `"deny"`.
+ */
+export declare const WEB_TOOLS_DEFAULTS: {
+    readonly searchEnabled: true;
+    readonly maxSearchesPerCall: 8;
+    readonly anonymousMaxSearchesPerCall: 3;
+    readonly privateAddressPolicy: "ask";
+};
+/** `WebToolsConfig` with every default applied -- what a consumer reads instead of the raw option. */
+export interface ResolvedWebToolsConfig {
+    search: {
+        enabled: boolean;
+        authRef?: CredentialRef;
+        maxSearchesPerCall: number;
+        anonymousMaxSearchesPerCall: number;
+    };
+    fetch: {
+        digestModel?: string;
+        authRef?: CredentialRef;
+        privateAddressPolicy: WebPrivateAddressPolicy;
+    };
+    blockedDomains: string[];
+}
+/**
+ * THE one reader of `WebToolsConfig`. Pure, dependency-free and total: an absent block, an absent
+ * field, a non-positive or non-finite bound and a whitespace-only `digestModel` all resolve to the
+ * default rather than to a value no consumer can act on (a bound of `0` would make a tool that is
+ * advertised and can never search; disabling search is `search.enabled: false`).
+ */
+export declare function resolveWebToolsConfig(web: WebToolsConfig | undefined): ResolvedWebToolsConfig;
 export interface McpSdkServerConfigWithInstance extends McpSdkServerConfig {
     instance: unknown;
 }
@@ -238,7 +275,9 @@ export interface Options {
     autoClassifier?: AutoClassifierConfig;
     /**
      * DISCLOSED WINTER option (P2 carry, wired in T10): the advisor/reviewer backend's model, same
-     * selection path. Its optional `authRef` (fix wave, Ruling E-1) is the advisor's OWN credential:
+     * selection path -- a provider-qualified tag (`<providerId>/<model>`) names its own provider, so a
+     * reviewer on another provider than the session's is just that tag plus that provider's credential
+     * (the `web.fetch.digestModel` shape). Its optional `authRef` (fix wave, Ruling E-1) is the advisor's OWN credential:
      * a target on another provider than the session's never inherits the session's -- it uses the
      * route's ref, else the target provider's own keychain record (`<providerId>:default`), else a
      * typed `no-credential-for-provider` refusal at its first generation.
@@ -246,6 +285,20 @@ export interface Options {
      * The MODEL may also come from `settings.advisor.model` (D30, hot); `Options.advisor.model` wins.
      */
     advisor?: AdvisorConfig;
+    /**
+     * DISCLOSED WINTER option: the `WebSearch` / `WebFetch` tools' configuration -- the search
+     * backend's fallback key and per-call bounds, the page-digest model and its credential, the
+     * private-address policy, and the ONE `blockedDomains` floor both tools honour. Every field is
+     * optional; `resolveWebToolsConfig` applies `WEB_TOOLS_DEFAULTS`. See `WebToolsConfig`.
+     */
+    web?: WebToolsConfig;
+    /**
+     * DISCLOSED WINTER option: the host's say over the auto-memory section -- whether it is on, and
+     * which directory it names. Wins over the settings keys, which win over the computed default; it
+     * is how a host that disables settings files (`settingSources: []`) still makes the session agree
+     * with it about where memory lives. See `AutoMemoryConfig`.
+     */
+    autoMemory?: AutoMemoryConfig;
     /**
      * DISCLOSED WINTER option (P7a, D19): THE BRAND PROFILE — every Winter-owned name this session
      * runs under, as a partial that folds onto Winter's own defaults (brand.ts's `WINTER_BRAND`).

package/dist/protocol/config.d.ts

@@ -322,6 +322,10 @@ export interface RuntimeConfig {
     keychainService?: string;
     autoClassifier?: AutoClassifierConfig;
     advisor?: AdvisorConfig;
+    /** The wire twin of `Options.web` -- see `WebToolsConfig`. Pure passthrough; absent means every default in `WEB_TOOLS_DEFAULTS`. */
+    web?: WebToolsConfig;
+    /** The wire twin of `Options.autoMemory` -- see `AutoMemoryConfig`. Pure passthrough; absent means "settings, then the computed default". */
+    autoMemory?: AutoMemoryConfig;
     /**
      * P7a (D19): the RESOLVED brand profile — every Winter-owned name this session runs under.
      *
@@ -469,9 +473,154 @@ export interface AutoClassifierConfig {
  * advisor's provider, the advisor's provider refuses with a typed `no-credential-for-provider`.
  */
 export interface AdvisorConfig {
+    /**
+     * The reviewer's model: a PROVIDER-QUALIFIED TAG (`<providerId>/<model>`, e.g.
+     * `codex-oauth/gpt-5.6-sol`) or a slot name, resolved through the SAME selection path as the
+     * session model -- exactly as `WebFetchConfig.digestModel` is.
+     *
+     * THE TAG IS THE PROVIDER IDENTITY; there is deliberately no second field for it. A qualified tag
+     * resolves under ITS OWN provider, never under the session's (`Options.provider`), so an advisor on
+     * another provider than the session's needs nothing but that tag and, in `authRef`, that provider's
+     * own credential. A host that splits the tag down to a bare model id before passing it has thrown
+     * the provider away: a bare id is read as a slot name or canonical id and resolved by the session's
+     * slot rules, which is a different question.
+     */
     model: string;
     authRef?: CredentialRef;
 }
+/**
+ * What to do when `WebFetch` is pointed at a loopback, private-range or link-local address.
+ *
+ *   `"ask"`    raise the ordinary permission prompt for that host before anything is fetched;
+ *   `"deny"`   refuse with a typed tool result and fetch nothing;
+ *   `"allow"`  fetch it like any public host.
+ *
+ * WHY THIS IS A HOST DECISION AND NOT A CONSTANT. A sandboxed shell has no network, so `WebFetch` is
+ * the only door from a session to the services on the user's own machine and LAN -- an admin page, a
+ * metadata endpoint. Whether that door opens silently depends on whether the session can ask a human
+ * at all: an interactive host can, an unattended one cannot and must refuse.
+ *
+ * WHAT `"allow"` AND AN APPROVAL CAN AND CANNOT REACH. `WebFetch` upgrades `http` to `https`
+ * unconditionally and refuses any hostname with fewer than two dot-separated labels -- both are the
+ * reference runtime's own rules, kept. So this policy governs an `https` service at an IPv4 literal
+ * (`https://127.0.0.1:8443/`) or at a name the URL parser leaves with two or more labels
+ * (`printer.local`, `api.localhost`). A plain-`http` port and every IPv6 literal (`[::1]` is one
+ * label) are unfetchable whatever this says -- a session pointed at one gets `Invalid URL` from the
+ * tool, and no approval is raised for it, because no answer could make it work.
+ */
+export type WebPrivateAddressPolicy = "allow" | "ask" | "deny";
+/** `WebSearch`'s own configuration. Every field is optional; see `WEB_TOOLS_DEFAULTS` (options.ts) for what absent means. */
+export interface WebSearchConfig {
+    /**
+     * The host's explicit OFF switch for the search BACKEND. Absent means enabled.
+     *
+     * The backend's anonymous tier needs no credential, so "is a search backend usable" is `true` for
+     * every session by default -- which would make the tool's capability gate a constant. This is the
+     * one fact that can make it `false`: a host that must not let a session reach the backend at all
+     * (an offline deployment, a policy that forbids the third-party endpoint). With `false` the tool is
+     * not advertised, and a call that reaches it anyway answers with a typed refusal.
+     *
+     * NOT a substitute for `disallowedTools`, which hides a tool the runtime has; this says the
+     * backend behind it is not there.
+     */
+    enabled?: boolean;
+    /**
+     * A reference to the search backend's API key -- the FALLBACK, used only once the anonymous tier
+     * is exhausted or rate-limited. A locator, never the key: the runtime resolves it at the last
+     * responsible moment and accepts EITHER JSON credential material (`{"kind":"api-key","key":...}`)
+     * OR a bare non-empty string, because a host that shares this keychain slot with another client
+     * cannot change what is stored in it. Absent means anonymous-only: an exhausted quota is then a
+     * typed "add a key" result, never an error that ends the turn.
+     */
+    authRef?: CredentialRef;
+    /**
+     * The most backend searches ONE `WebSearch` call may run while a key is in use (the inner model
+     * decides how many it needs, up to this). Absent means `WEB_TOOLS_DEFAULTS.maxSearchesPerCall`.
+     */
+    maxSearchesPerCall?: number;
+    /**
+     * The same bound while the call is riding the ANONYMOUS tier. Separate, and lower by default,
+     * because the anonymous tier is a small shared daily allowance: eight searches per call would
+     * spend it in a handful of calls and push every later one onto the key (or onto the "quota
+     * exhausted" result when there is no key). Absent means
+     * `WEB_TOOLS_DEFAULTS.anonymousMaxSearchesPerCall`.
+     */
+    anonymousMaxSearchesPerCall?: number;
+}
+/** `WebFetch`'s own configuration. Every field is optional; see `WEB_TOOLS_DEFAULTS` (options.ts) for what absent means. */
+export interface WebFetchConfig {
+    /**
+     * The model that digests a fetched page against the caller's prompt -- a provider-qualified tag
+     * (`<providerId>/<model>`) or a slot name, resolved through the SAME selection path as the session
+     * model.
+     *
+     * THE DEFAULT, stated plainly: when the host names none, the digest runs on the SESSION'S OWN
+     * MODEL. That is the one choice that is always resolvable and needs no second credential. There is
+     * deliberately no "cheapest slot" heuristic -- a family's slots are not reliably ranked
+     * strongest-to-weakest, so picking one by position would be a guess presented as a rule.
+     *
+     * A STATED model that cannot be resolved (unknown tag, disabled provider, no credential) is a
+     * typed refusal surfaced as the tool's RESULT. It is never a silent fallback onto the session's
+     * model: a host that named a small model did so to bound cost, and quietly spending the session
+     * model's price instead is the failure this field exists to prevent.
+     */
+    digestModel?: string;
+    /**
+     * The digest model's OWN credential, for a digest model on another provider than the session's
+     * (the cross-provider credential rule every auxiliary route follows: the route's own ref, else the
+     * session's material only when the provider is the same, else the target provider's
+     * `<providerId>:default` keychain record, else a typed `no-credential-for-provider`). The session's
+     * key is never sent to another provider. Ignored when `digestModel` is absent.
+     */
+    authRef?: CredentialRef;
+    /** See `WebPrivateAddressPolicy`. Absent means `WEB_TOOLS_DEFAULTS.privateAddressPolicy`. */
+    privateAddressPolicy?: WebPrivateAddressPolicy;
+}
+/**
+ * DISCLOSED WINTER option: the two web tools' configuration.
+ *
+ * `blockedDomains` sits at THIS level, not under either tool, because it is ONE list with ONE
+ * meaning -- the host's domain floor -- and both tools must honour it: `WebFetch` refuses a listed
+ * host outright, and `WebSearch` sends the list as the backend's exclusion filter on EVERY inner
+ * search, so a blocked domain can neither be fetched nor be surfaced as a link to fetch. Two lists
+ * would be two chances to update one and forget the other.
+ *
+ * MATCHING IS BY SUFFIX ON A LABEL BOUNDARY: listing `example.com` blocks `example.com` and every
+ * subdomain of it (`docs.example.com`), and does not block `notexample.com`. Entries are compared
+ * case-insensitively; a leading `*.` or `.` and a trailing `.` are ignored.
+ */
+export interface WebToolsConfig {
+    search?: WebSearchConfig;
+    fetch?: WebFetchConfig;
+    blockedDomains?: string[];
+}
+/**
+ * DISCLOSED WINTER option: the host's say over the auto-memory section.
+ *
+ * WHY IT EXISTS. The runtime computes the memory directory itself and reads `autoMemoryEnabled` /
+ * `autoMemoryDirectory` from SETTINGS FILES only. A host that turns settings files off
+ * (`settingSources: []`) therefore had no way to make the session agree with it about where memory
+ * lives, or to turn the section off -- the two sides could only agree by computing the same path by
+ * coincidence.
+ *
+ * PRECEDENCE, per field: this option, then the settings key, then the computed default
+ * (`<home>/projects/<memory-key>/memory`, enabled).
+ *
+ *   `enabled: false`  the auto-memory section and its index are omitted entirely, whatever settings
+ *                     say; `enabled: true` turns it on even over a settings `false`.
+ *   `directory`       REPLACES the computed path outright, with no per-project nesting beneath it
+ *                     (`~` and a cwd-relative path are expanded exactly as the settings key's are).
+ *                     Whitespace-only counts as absent.
+ *
+ * NOTE FOR A HOST RELOCATING THE DIRECTORY: the write-permission carve-out for memory files is keyed
+ * to the DEFAULT `projects/<key>/memory` shape under the home. A directory elsewhere under the
+ * home's `projects/` tree is still write-denied; one outside the home meets no floor at all and
+ * follows the session's ordinary write rules.
+ */
+export interface AutoMemoryConfig {
+    enabled?: boolean;
+    directory?: string;
+}
 /**
  * The pinned `ModelInfo` (`sdk.d.ts:1261-1300`): three required fields, six optional.
  *

package/dist/protocol/frames.d.ts

@@ -42,11 +42,56 @@ export interface ControlResponseFrame {
         message: string;
     };
 }
+/**
+ * Runtime -> host: "I stopped waiting for control_request `requestId`" (lane C, C2 -- claude parity:
+ * claude's structuredIO writes `control_cancel_request` when a pending request's signal aborts, e.g.
+ * a turn interrupted while a permission prompt is open). The host aborts the callback it is running
+ * for that request (`canUseTool`'s `signal`) and owes no response; one sent anyway is dropped.
+ */
+/**
+ * `result.usage`: claude's `NonNullableUsage` (every `BetaUsage` field, none null), carrying THIS
+ * turn's main-loop generations -- claude builds a fresh QueryEngine per prompt in SDK mode, so its
+ * `totalUsage` starts at EMPTY_USAGE each turn. The four token counts are real; the rest is filled the
+ * way the pinned binary's own EMPTY_USAGE fills a value it has no data for, and says so:
+ *   - `cache_creation`: every cache write Winter marks is the default 5-minute ephemeral one (the
+ *     adapters send `{type: "ephemeral"}` with no ttl), so `ephemeral_5m_input_tokens` equals
+ *     `cache_creation_input_tokens` and `ephemeral_1h_input_tokens` is 0;
+ *   - `server_tool_use`: Winter's WebSearch/WebFetch run client-side, never as billed server tools: 0/0;
+ *   - `output_tokens_details.thinking_tokens`: 0 -- providers' reasoning-token counts are not threaded
+ *     through Winter's usage yet (they are included in `output_tokens`);
+ *   - `service_tier: "standard"`, `inference_geo: ""`, `iterations: []`, `speed: "standard"`: the
+ *     pinned EMPTY_USAGE's own values.
+ */
+export interface WireResultUsage {
+    output_tokens_details: {
+        thinking_tokens: number;
+    };
+    input_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+    output_tokens: number;
+    server_tool_use: {
+        web_search_requests: number;
+        web_fetch_requests: number;
+    };
+    service_tier: "standard" | "priority" | "batch";
+    cache_creation: {
+        ephemeral_1h_input_tokens: number;
+        ephemeral_5m_input_tokens: number;
+    };
+    inference_geo: string;
+    iterations: unknown[];
+    speed: "standard" | "fast";
+}
+export interface ControlCancelRequestFrame {
+    type: "control_cancel_request";
+    requestId: string;
+}
 export interface UnknownFrame {
     type: string;
     [k: string]: unknown;
 }
-export type WinterFrame = InitFrame | UserFrame | DataFrame | ControlRequestFrame | ControlResponseFrame | UnknownFrame;
+export type WinterFrame = InitFrame | UserFrame | DataFrame | ControlRequestFrame | ControlResponseFrame | ControlCancelRequestFrame | UnknownFrame;
 export interface SDKHookStartedMessage {
     type: "system";
     subtype: "hook_started";
@@ -618,6 +663,8 @@ export type SdkMessage = {
     structured_output?: unknown;
     terminal_reason?: "structured_output_retry_exhausted" | "api_error" | string;
     api_error_status?: number | null;
+    /** THIS turn's main-loop usage -- claude's `result.usage` (dist-session fixes C1); see `WireResultUsage`. */
+    usage?: WireResultUsage;
     permission_denials: SDKPermissionDenial[];
     [k: string]: unknown;
 } | {

package/dist/query.d.ts

@@ -21,7 +21,14 @@ export type ControlRequestHandlerResult = {
         message: string;
     };
 };
-export type ControlRequestHandler = (payload: unknown) => Promise<ControlRequestHandlerResult>;
+/**
+ * A handler for one runtime-originated control_request subtype. `ctx.signal` aborts when the runtime
+ * CANCELS the request (`control_cancel_request` -- lane C, C2, claude parity): the handler should stop
+ * waiting, and whatever it returns afterwards is not sent (the runtime already stopped waiting).
+ */
+export type ControlRequestHandler = (payload: unknown, ctx?: {
+    signal: AbortSignal;
+}) => Promise<ControlRequestHandlerResult>;
 export interface QueryInternal {
     registerControlRequestHandler(subtype: string, handler: ControlRequestHandler): void;
     respondPermission(requestId: string, result: PermissionResult): void;

package/package.json

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