@yanlinglabs/winter-agent-runtime 0.0.35 → 0.0.38

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/monitor.d.ts

@@ -34,6 +34,8 @@ declare function buildMonitorRunCommandOptions(ctx: ToolExecutionContext): {
     home: string;
     /** Phase 5 fix wave, I1: the resolved winter root, distinct from the OS home above. */
     winterHome?: string;
+    /** WS-21 fix round 1, item 4: the shared store home -- see `ToolExecutionContext.storeHome`. */
+    storeHome?: string;
     /** P7a (D19): the session's brand -- the dot-dir names the seatbelt fences. */
     brand?: SandboxBrand;
     /** Fix round 16, item 2: `sandbox.filesystem.allowGitConfig` -- see `SandboxFilesystemSettings.allowGitConfig`'s own header. */

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

@@ -1,44 +1,3 @@
 import "../descriptors/index.ts";
-export type ReadBlock = {
-    type: "text";
-    text: string;
-} | {
-    type: "image";
-    media_type: string;
-    bytes: number;
-    width?: number;
-    height?: number;
-    data?: string;
-    note?: string;
-} | {
-    type: "pdf";
-    media_type: "application/pdf";
-    bytes: number;
-    totalPages?: number;
-    requestedPages?: {
-        start: number;
-        end: number;
-    };
-    data?: string;
-    note: string;
-};
-export interface ReadBlocksEnvelope {
-    winterReadBlocks: ReadBlock[];
-}
-export declare function parsePngDimensions(buf: Uint8Array): {
-    width: number;
-    height: number;
-} | undefined;
-export declare function parseGifDimensions(buf: Uint8Array): {
-    width: number;
-    height: number;
-} | undefined;
-export declare function parseBmpDimensions(buf: Uint8Array): {
-    width: number;
-    height: number;
-} | undefined;
-export declare function parseJpegDimensions(buf: Uint8Array): {
-    width: number;
-    height: number;
-} | undefined;
+export { IMAGE_MAX_LONG_EDGE, MODEL_DOES_NOT_SUPPORT_IMAGES, READ_IMAGE_MAX_BYTES, READ_IMAGE_MAX_DIMENSION, parseBmpDimensions, parseGifDimensions, parseJpegDimensions, parsePngDimensions, parseWebpDimensions, sniffImageType, } from "../image-prep.js";
 export declare function countPdfPages(bytes: Buffer): number | undefined;

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,11 +65,51 @@ export interface ToolDescriptor {
     alwaysLoad?: boolean;
     _meta?: Record<string, unknown>;
     interaction?: "required";
+    mcpName?: string;
 }
 export interface ToolResultPayload {
     output: string;
+    /**
+     * Code-mode images: what the MODEL is shown for this call, when it is more than text. Present only on
+     * a result that carries an image (the Read tool on an image file or a notebook with plot output);
+     * the engine then writes these blocks as the `tool_result`'s content array -- claude's own shape --
+     * in place of `output`. `output` stays a short TEXT rendering of the same result, and it is what every
+     * text-only consumer reads: the PostToolUse hook's `tool_response`, a log line, a flattening. Kept
+     * separate so no text channel ever carries base64 (a hook payload rides the same capped stdout line
+     * a frame does).
+     */
+    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
+ * `text` and `image` ContentBlock variants, so the engine carries them into history, the transcript and
+ * every provider adapter unchanged.
+ */
+export type ToolResultBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+};
 /** See `ToolExecutionContext.permission`. */
 export interface ToolCallPermission {
     explicitApproval: "prompt" | "rule";
@@ -132,6 +176,13 @@ export interface ToolExecutionContext {
      * ABSENT READS AS `WINTER_BRAND`, which is byte-identical to the behaviour before this field.
      */
     brand?: BrandProfile;
+    /**
+     * Code-mode images: whether the model the session is on RIGHT NOW accepts image input (its catalog
+     * row's `inputModalities` lists "image"). The Read tool answers an image file with a short text
+     * refusal instead of image blocks when this is `false`. Absent reads as "yes" -- a scripted double or
+     * a row with no modality facts, the same default `ModelDescription.readsImages` has.
+     */
+    modelReadsImages?: boolean;
     sessionId: string;
     readState: SessionReadState;
     emitFrame: (frame: BackgroundTaskMessage) => void;
@@ -282,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;
@@ -289,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`,
@@ -321,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";
@@ -359,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;
@@ -366,6 +455,8 @@ export interface EngineToolCall {
 }
 export interface EngineToolResult {
     output: string;
+    /** See `ToolResultPayload.blocks`: when present, the model-facing content of the `tool_result`. */
+    blocks?: ToolResultBlock[];
     /**
      * Spawn-surface parity (R-S4, research gap 6): the executor's own `isError`, carried to the engine
      * so the model-facing `tool_result` block says `is_error: true` -- claude's shape for every tool
@@ -373,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`. */
@@ -381,6 +474,8 @@ export interface EngineFacingToolExecutor {
 export interface RegistryToolExecutorDeps {
     sessionId: string;
     home: string;
+    /** Code-mode images: read per call, so a `set_model` since the last call is seen -- see `ToolExecutionContext.modelReadsImages`. */
+    modelReadsImages?: () => boolean;
     /** Phase 5 fix wave, I1: the resolved winter root -- see `ToolExecutionContext.winterHome`. */
     winterHome?: string;
     /** WS-21 fix round 1, item 4: the shared store home -- see `ToolExecutionContext.storeHome`. */

package/dist/tools/sandbox-run-inputs.d.ts

@@ -0,0 +1,41 @@
+import type { ToolExecutionContext } from "./registry.js";
+import { type GlobDenyEntry } from "../permissions/file-rules.js";
+import type { SandboxBrand } from "../sandbox/profile.js";
+/** Everything about the SESSION the seatbelt profile needs, for any tool that runs a shell command. */
+export interface SandboxRunInputs {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    settings: ToolExecutionContext["sandboxSettings"];
+    writableRoots: string[];
+    denyWritePaths?: string[];
+    denyReadPaths?: string[];
+    /** Fix round 11: glob-shaped denyWrite/denyRead entries, pre-converted to SBPL regex source -- see `splitDenyPathsByGlobShape`'s own header. */
+    denyWriteRegexes?: string[];
+    denyReadRegexes?: string[];
+    /** Fix round 12: each glob-shaped denyWrite/denyRead entry's own canonicalized fixed-prefix directory -- feeds the ancestor-rename-bypass fix. */
+    denyWriteGlobFixedPrefixes?: string[];
+    denyReadGlobFixedPrefixes?: string[];
+    /** Fix round 13: each glob-shaped denyRead entry, its regex PAIRED with its own fixed prefix -- feeds the read-deny-keep-in-place fix. */
+    denyReadGlobEntries?: GlobDenyEntry[];
+    home: string;
+    /** Phase 5 fix wave, I1: the resolved winter root, distinct from the OS home above. */
+    winterHome?: string;
+    /** WS-21 fix round 1, item 4: the shared store home -- see `ToolExecutionContext.storeHome`. */
+    storeHome?: string;
+    /** P7a (D19): the session's brand -- the dot-dir names the seatbelt fences. */
+    brand?: SandboxBrand;
+    /** Fix round 16, item 2: `sandbox.filesystem.allowGitConfig` -- see `SandboxFilesystemSettings.allowGitConfig`'s own header. */
+    allowGitConfigWrites?: boolean;
+}
+/**
+ * Where a spawn may write: the session scratch dir, the session's bounded roots (the cwd among them),
+ * the outputs dir when configured, and `filesystem.allowWrite` (WS-12 §12 Q5: additive, never a
+ * replacement).
+ */
+export declare function computeWritableRoots(ctx: ToolExecutionContext): string[];
+/** The child's environment: this process's, with `TMPDIR` (and `OUTDIR` when configured) pointed at the session's own dirs. */
+export declare function buildSandboxChildEnv(ctx: ToolExecutionContext): NodeJS.ProcessEnv;
+/** `filesystem.denyWrite`/`denyRead`, split into plain paths and glob-shaped regexes (C1 / fix rounds 11-13). */
+export declare function computeDenyPaths(ctx: ToolExecutionContext): Pick<SandboxRunInputs, "denyWritePaths" | "denyReadPaths" | "denyWriteRegexes" | "denyReadRegexes" | "denyWriteGlobFixedPrefixes" | "denyReadGlobFixedPrefixes" | "denyReadGlobEntries">;
+/** The session's sandbox inputs, identical for every tool that runs a shell command. */
+export declare function sandboxRunInputs(ctx: ToolExecutionContext): SandboxRunInputs;

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.35";
+export declare const RUNTIME_VERSION = "0.0.38";

package/dist/version.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var RUNTIME_VERSION = "0.0.35";
+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.35",
+  "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-agent-sdk": "0.0.35",
-    "@yanlinglabs/winter-provider-catalog": "0.0.35",
-    "@yanlinglabs/winter-provider-runtime": "0.0.35"
+    "@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"