@yanlinglabs/winter-agent-runtime 0.0.27

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/propose-goal.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/propose-skills.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/push-notification.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/read-mcp-resource-dir-tool.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/read-mcp-resource-tool.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/read-notifications.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/refresh-mcp-tools.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/remote-trigger.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/report-findings.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/schedule-wakeup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/send-feedback.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/send-message.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/send-user-file.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/share-onboarding-guide.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/show-onboarding-role-picker.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/structured-output.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/task-create.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/task-get.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/task-list.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/task-output.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/task-stop.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/task-update.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/todo-write.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/wait-for-mcp-servers.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/web-fetch.d.ts

@@ -0,0 +1,8 @@
+/** The name `engine.ts`'s `toolSpecFor` branches on for the lean/full choice, mirroring `WEB_SEARCH_CANONICAL_NAME` -- so no tool name is a literal there. */
+export declare const WEB_FETCH_CANONICAL_NAME = "WebFetch";
+export declare const WEB_FETCH_DESCRIPTION_LEAN: string;
+export declare const WEB_FETCH_DESCRIPTION_FULL: string;
+/** claude's own `leanPrompt(model)` gate, applied to WebFetch's description exactly as `sessionLeanModel` applies it to the Agent tool's `whenToUseLean`. */
+export declare function webFetchDescriptionFor(leanModel: boolean): string;
+/** The schema to ADVERTISE: claude's own bytes for a first-party Anthropic session, the portable rendering for every other provider (see the block comment above). */
+export declare function webFetchInputSchemaFor(firstPartyAnthropic: boolean): Record<string, unknown>;

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

@@ -0,0 +1,15 @@
+/**
+ * Mirrors `provider/slots.ts`'s own `AGENT_TOOL_CANONICAL_NAME` precedent: `engine.ts`'s `toolSpecFor`
+ * recognises this descriptor by canonical name WITHOUT spelling `"WebSearch"` as a literal at its own
+ * call site. This file's `stub(descriptor)` call below is the only other place the name originates.
+ */
+export declare const WEB_SEARCH_CANONICAL_NAME = "WebSearch";
+/** `new Date().toLocaleString("en-US",{month:"long",year:"numeric"})`, e.g. "September 2026" -- claude's own `${t}`. */
+export declare function currentMonthYear(now?: () => Date): string;
+/**
+ * Renders WebSearch's description AT THE CALL SITE -- so the month is always today's, whether the
+ * caller is `toolSpecFor` at advertise time or a test. `now` is injectable for tests.
+ */
+export declare function webSearchDescription(lean: boolean, now?: () => Date): string;
+/** The schema to ADVERTISE: claude's own bytes for a first-party Anthropic session, the portable rendering for every other provider. */
+export declare function webSearchInputSchemaFor(firstPartyAnthropic: boolean): Record<string, unknown>;

package/dist/tools/descriptors/winter-list-agents.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/descriptors/winter-send-message.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,14 @@
+import type { WinterToolCaller } from "@yanlinglabs/winter-agent-sdk/tools";
+import type { ToolExecutionContext } from "../registry.js";
+/**
+ * The caller identity a messaging tool runs AS — from the execution context, never from the
+ * arguments. Taking it from the arguments would make the sender's identity something a model could
+ * write, and every fence in the messaging core is keyed on it.
+ *
+ * `ctx.toolUseId` is real (registry.ts threads `EngineToolCall.id` onto every context it builds), so
+ * WS-10 §12's retry-stable messageId derivation is live in production. It is passed through as
+ * possibly-undefined rather than defaulted here: the SDK's port allocates the fallback, once, for
+ * both hosts, and its posture is the one this runtime used to carry — a fresh id per call and NO
+ * dedupe, because two distinct model calls must never be mistaken for one retry of each other.
+ */
+export declare function callerContextFrom(ctx: ToolExecutionContext): WinterToolCaller;

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

@@ -0,0 +1,25 @@
+/**
+ * One list entry, or one host/URL under test, as the canonical hostname the URL parser gives it --
+ * or `undefined` for something that names no host.
+ *
+ * Tolerant of what people actually write in a block-list: a leading `*.` or `.`, a scheme, userinfo,
+ * a port, a path, surrounding whitespace, a unicode name, a bare IPv6 address.
+ * `https://Ads.Example.com/track` and `*.ads.example.com` both become `ads.example.com`.
+ */
+export declare function normalizeDomain(entry: string): string | undefined;
+/** `host` is `domain`, or a subdomain of it when `domain` is a multi-label NAME. Both are normalised first. */
+export declare function hostMatchesDomain(host: string, domain: string): boolean;
+/** The first entry of `domains` that covers `hostOrUrl`, or `undefined`. */
+export declare function matchingDomain(hostOrUrl: string, domains: readonly string[]): string | undefined;
+export declare function isDomainBlocked(hostOrUrl: string, blockedDomains: readonly string[]): boolean;
+/** Normalised, de-duplicated union, in first-seen order. Entries that name no host are dropped. */
+export declare function mergeDomainLists(...lists: ReadonlyArray<readonly string[] | undefined>): string[];
+/**
+ * The subset of an (already merged) list that may be handed to a search BACKEND's own exclude filter:
+ * MULTI-LABEL NAMES ONLY. An IP literal and a single-label entry (`com`, `localhost`) match EXACTLY
+ * here, by this module's own rule -- but a backend's rule for them is unknown, and one that reads
+ * `com` as a suffix turns a typo'd entry into "no .com result, ever", silently. They are withheld from
+ * the backend and lose nothing: the caller still drops any hit they cover, locally, with
+ * `isDomainBlocked`, under the rule this module documents.
+ */
+export declare function backendExcludableDomains(domains: readonly string[]): string[];

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

@@ -0,0 +1,122 @@
+import { connectMcpServer } from "../../mcp/client.js";
+import type { ToolSecretResult } from "../../provider/tool-secret.js";
+import type { WebSessionRuntime } from "../../web/session-runtime.js";
+export declare const EXA_MCP_ENDPOINT = "https://mcp.exa.ai/mcp";
+export declare const EXA_SEARCH_TOOL = "web_search_exa";
+export declare const EXA_ADVANCED_SEARCH_TOOL = "web_search_advanced_exa";
+/** The only two tools this client asks the server to expose (the endpoint's `tools=` selector). */
+export declare const EXA_ENABLED_TOOLS: readonly string[];
+export declare const EXA_API_KEY_HEADER = "x-api-key";
+/** How long the anonymous tier is skipped after it answers rate-limited, before it is re-probed. See the header. */
+export declare const EXA_ANONYMOUS_COOLDOWN_MS: number;
+/** The anonymous tier allows 2 calls per second; call STARTS are spaced at least this far apart, process-wide. */
+export declare const EXA_ANONYMOUS_MIN_INTERVAL_MS = 500;
+export declare const EXA_CONNECT_TIMEOUT_MS = 10000;
+export declare const EXA_CALL_TIMEOUT_MS = 25000;
+export declare const EXA_DEFAULT_NUM_RESULTS = 8;
+/** The ceiling on `numResults`, and on the hits handed on. Each hit is capped; without this the COUNT was not. */
+export declare const EXA_MAX_NUM_RESULTS = 20;
+export declare const EXA_TITLE_MAX_CHARACTERS = 300;
+/** A hit with a longer URL is DROPPED, never truncated -- a cut URL is a different, wrong URL. */
+export declare const EXA_URL_MAX_CHARACTERS = 2000;
+/** Per-result highlight budget asked of the server, and enforced again on what comes back. */
+export declare const EXA_HIGHLIGHTS_MAX_CHARACTERS = 1200;
+/** The advanced tool returns the whole page as `text` unless told otherwise; highlights are what is used. */
+export declare const EXA_TEXT_MAX_CHARACTERS = 300;
+/** The cap on one search's raw text, applied before parsing results are handed on. */
+export declare const EXA_MAX_RESULT_CHARS = 40000;
+export interface ExaSearchHit {
+    title: string;
+    url: string;
+    /** The result's highlight text, capped at `EXA_HIGHLIGHTS_MAX_CHARACTERS`. Empty when the backend sent none. */
+    highlight: string;
+    publishedDate?: string;
+}
+export interface ExaSearchParams {
+    query: string;
+    /** `web_search_exa` REQUIRES one; defaults to the query itself. */
+    objective?: string;
+    numResults?: number;
+    /** The call's own allow-list. Mutually exclusive with `excludeDomains` at the tool's surface. */
+    includeDomains?: readonly string[];
+    /** The call's own block-list. The host's `blockedDomains` floor is ADDED to it on every search. */
+    excludeDomains?: readonly string[];
+}
+export type ExaTier = "anonymous" | "key";
+/**
+ *   `quota-exhausted`   the anonymous tier is exhausted/rate-limited and NO key is configured.
+ *   `key-unreadable`    ...and a key IS configured but could not be read (the message says why).
+ *   `key-rate-limited`  the KEY tier answered rate-limited or out of credit.
+ *   `key-rejected`      the key tier answered 401/403.
+ *   `blocked-domains`   every allowed domain is on the host's block-list: nothing may be searched.
+ *   `timeout` / `aborted` / `unreachable` / `backend-error`   as named.
+ */
+export type ExaSearchFailureCode = "quota-exhausted" | "key-unreadable" | "key-rate-limited" | "key-rejected" | "blocked-domains" | "timeout" | "aborted" | "unreachable" | "backend-error";
+export type ExaSearchResult = {
+    ok: true;
+    hits: ExaSearchHit[];
+    tier: ExaTier;
+    tool: string; /** The payload's text, capped. */
+    rawText: string;
+    truncated: boolean;
+} | {
+    ok: false;
+    code: ExaSearchFailureCode;
+    message: string;
+};
+/**
+ * The anonymous tier's breaker and pacer. PROCESS-WIDE by default (`sharedExaBackendState`): the
+ * allowance is per network address, so every session in this process shares one. A test passes its own.
+ */
+export interface ExaBackendState {
+    /** When the anonymous tier last answered rate-limited; `undefined` while it is believed usable. */
+    anonymousRateLimitedAt?: number;
+    /** WHY it was last refused -- so a keyless caller is told the truth (an auth refusal is not an exhausted quota). Absent reads as `rate-limited`. */
+    anonymousRefusal?: "rate-limited" | "auth";
+    /** The earliest time the next anonymous call may START (pacing). */
+    nextAnonymousCallAt: number;
+    /** How many callers are asleep in the pacer RIGHT NOW -- what tells a deep queue from a clock step. Absent reads as 0. */
+    anonymousWaiting?: number;
+}
+export declare function createExaBackendState(): ExaBackendState;
+export declare const sharedExaBackendState: ExaBackendState;
+/** True while the anonymous tier is being skipped. After the cooldown it reads `false`, and the next call is the re-probe. */
+export declare function anonymousBreakerOpen(state: ExaBackendState, now: number): boolean;
+export interface ExaSearchClientOptions {
+    /**
+     * Resolves the fallback key, LAZILY: it is not called at all while the anonymous tier answers, so
+     * a session that never exhausts the free tier never touches the keychain. Called at most once per
+     * client. Absent means "no key is configured".
+     */
+    resolveKey?: () => Promise<ToolSecretResult>;
+    /** The host's `blockedDomains` floor: excluded from EVERY search, and any hit on it is dropped. */
+    blockedDomains?: readonly string[];
+    /** Overrides `EXA_MCP_ENDPOINT` -- a test points this at a loopback fixture. */
+    endpoint?: string;
+    state?: ExaBackendState;
+    now?: () => number;
+    /** Resolves after `ms`, or early (without throwing) when `signal` aborts. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    connect?: typeof connectMcpServer;
+    callTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    maxResultChars?: number;
+}
+export interface ExaSearchClient {
+    search(params: ExaSearchParams, opts?: {
+        signal?: AbortSignal;
+    }): Promise<ExaSearchResult>;
+    /** Closes both tiers' connections. Idempotent; never throws. */
+    close(): Promise<void>;
+}
+/** The lazy key resolver for a session: `web.search.authRef` through the session's tool-secret resolver. */
+export declare function exaKeyResolverFor(runtime: Pick<WebSessionRuntime, "web" | "resolveToolSecret">): (() => Promise<ToolSecretResult>) | undefined;
+/**
+ * Search hits out of one payload's text. Tolerant by design: JSON with a `results` array (the
+ * advanced tool), else `Title:`/`URL:` records (the basic tool), else NO hits -- never a throw. A
+ * result with no URL is dropped (there is nothing to link to); one with no title uses its URL.
+ */
+export declare function parseExaHits(text: string): ExaSearchHit[];
+/** The endpoint with its `tools=` selector. Built by hand so the comma list is sent exactly as documented, and so NOTHING else -- least of all a key -- can ride the query string. */
+export declare function exaEndpointUrl(endpoint?: string): string;
+export declare function createExaSearchClient(options?: ExaSearchClientOptions): ExaSearchClient;

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

@@ -0,0 +1,23 @@
+import type { ExaSearchClient } from "./_exa-client.js";
+/**
+ * The session's own client -- built by `factory()` on the first call for this `sessionId` and reused
+ * by every later one, REGARDLESS of whatever options a later call's `factory` closure would have
+ * built (a session's search wiring -- credential ref, blocked-domain floor, test endpoint -- is fixed
+ * for the life of one engine run, the same assumption `web/session-runtime.ts`'s own registry makes).
+ *
+ * `undefined` means this session's client was CLOSED and nothing may build another one for it (the
+ * tombstone, see the module header) -- the caller answers with an ordinary error result.
+ */
+export declare function exaSearchClientForSession(sessionId: string, factory: () => ExaSearchClient): ExaSearchClient | undefined;
+/**
+ * Closes and forgets `sessionId`'s client, if it ever built one, and TOMBSTONES the id either way --
+ * "no client had been built yet" is exactly the state in which a late child would build one.
+ * Idempotent; never throws.
+ */
+export declare function closeExaSearchClientForSession(sessionId: string): Promise<void>;
+/** Lifts the tombstone: a ROOT run starting (or RESUMING) this session id may search again. Idempotent. */
+export declare function reopenExaSearchClientsForSession(sessionId: string): void;
+/** Test/diagnostic only: is this session id tombstoned? */
+export declare function exaSearchClientIsClosedForTest(sessionId: string): boolean;
+/** Test hygiene only: forgets every cached client WITHOUT closing it -- a test's own fixture teardown closes its client itself -- and lifts every tombstone. */
+export declare function resetExaSessionClientsForTest(): void;

package/dist/tools/impl/_inner-model.d.ts

@@ -0,0 +1,135 @@
+import type { CredentialRef } from "@yanlinglabs/winter-agent-sdk";
+import type { ProviderUsage } from "../../engine.js";
+import type { ToolExecutionContext } from "../registry.js";
+import { type WebSessionRuntime } from "../../web/session-runtime.js";
+/**
+ * Which model runs the inner pass.
+ *
+ * `session` (the default) is the SESSION'S OWN live model: always resolvable, no second credential.
+ * `tag` is a STATED model -- a provider-qualified key or a slot name -- resolved under the
+ * cross-provider credential rule with `authRef` as the route's own credential. A stated tag that
+ * cannot resolve is a typed failure, NEVER a fallback onto the session's model.
+ */
+export type InnerModelSelector = {
+    kind: "session";
+} | {
+    kind: "tag";
+    tag: string;
+    authRef?: CredentialRef;
+};
+/** The ONE function tool the inner model may call. */
+export interface InnerToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface InnerToolCallInfo {
+    /** 1-based index of this handler call within the loop. */
+    index: number;
+    /** The inner model's own id for the call. */
+    toolUseId: string;
+    /** The turn's abort signal. A handler doing I/O must honour it. */
+    signal?: AbortSignal;
+}
+/** Runs one inner tool call. Must RETURN an error (`isError: true`) rather than throw; a throw is caught and reported to the inner model as an error result. */
+export type InnerToolHandler = (input: unknown, info: InnerToolCallInfo) => Promise<{
+    output: string;
+    isError?: boolean;
+}>;
+export interface InnerModelRequest {
+    /** Defaults to `{ kind: "session" }`. */
+    model?: InnerModelSelector;
+    /** The inner pass's own system prompt. Omitted entirely when absent -- never an empty string. */
+    system?: string;
+    /** The single user message. */
+    prompt: string;
+    /**
+     * PRESENT -> the BOUNDED TOOL LOOP, every round `toolChoice: auto`. ABSENT -> one generation with no
+     * tools.
+     *
+     * WS-23: ROUND 1 IS NO LONGER FORCED. It used to be sent with `toolChoice: {type: "tool", name}` so
+     * the model could not answer from memory; Opus 5.5 and Fable 5.1 reject a forced choice (a documented
+     * 400, downgraded to `auto` by the Anthropic adapter), so on those models the "guarantee" silently
+     * became a suggestion. A caller that needs the tool to run at least once runs it itself before the
+     * pass and hands the model the result (WebSearch's seed search does exactly that).
+     */
+    tool?: InnerToolSpec;
+    /** Required with `tool`. */
+    handler?: InnerToolHandler;
+    /**
+     * The most HANDLER calls the loop will make (every call in a parallel tool-use turn counts).
+     * Calls beyond it are answered with a limit notice and never reach the handler, and the model gets
+     * exactly ONE further generation to write its answer. Required with `tool`; values below 1 read as 1.
+     */
+    maxToolCalls?: number;
+}
+/**
+ * The inner pass's transcript, IN STREAM ORDER -- what a caller assembles its output from. A
+ * `tool_call` step carries the call AND its result, because every consumer needs them together and
+ * in the position the call was made.
+ */
+export type InnerModelStep = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "tool_call";
+    toolUseId: string;
+    input: unknown;
+    output: string;
+    isError: boolean;
+    executed: boolean;
+};
+/**
+ *   `not-wired`            no session runtime is registered for this call (a host wiring gap).
+ *   `invalid-request`      `tool` without `handler`/`maxToolCalls` -- a CALLER bug, reported not thrown.
+ *   `model-unresolvable`   a STATED model tag was refused; `detail` is the resolver's own code.
+ *   `no-credential`        the model resolved but no credential exists for its provider.
+ *   `provider-error`       the provider failed (HTTP error, refusal to serve, malformed stream).
+ *   `aborted`              the turn was interrupted before or during the pass.
+ */
+export type InnerModelFailureCode = "not-wired" | "invalid-request" | "model-unresolvable" | "no-credential" | "provider-error" | "aborted";
+export interface InnerModelFailure {
+    ok: false;
+    code: InnerModelFailureCode;
+    /** Safe to show the model: never a credential, never provider opaque state. */
+    message: string;
+    /** The underlying typed code where there is one (`unknown-model`, `slot-unservable`, `rate_limit`, ...). */
+    detail?: string;
+    /** Whatever the pass produced before it failed -- a partial loop's searches are still real. */
+    steps: InnerModelStep[];
+    toolCalls: number;
+}
+export interface InnerModelSuccess {
+    ok: true;
+    /** Every text step joined by a blank line. For the single-shot shape this is simply the answer. */
+    text: string;
+    steps: InnerModelStep[];
+    /** Handler calls actually made. */
+    toolCalls: number;
+    /** `answer`: the model ended with text. `tool-call-limit`: it was still calling the tool after its closing generation. */
+    stoppedBy: "answer" | "tool-call-limit";
+    /** The key usage was accounted under. */
+    modelKey: string | undefined;
+    /** The sum over every generation in the pass (already accounted; reported for the caller's own use). */
+    usage: ProviderUsage;
+}
+export type InnerModelResult = InnerModelSuccess | InnerModelFailure;
+/** What the loop needs from the session, narrowed so a test hands in three functions and no engine. */
+export type InnerModelRuntime = Pick<WebSessionRuntime, "sessionModel" | "resolveAuxiliaryModel" | "accountUsage" | "budgetExceeded">;
+/** The notice an over-limit call is answered with. Exported so a caller can recognise (and not re-report) it. */
+export declare const INNER_TOOL_LIMIT_NOTICE = "The tool-call limit for this request has been reached. Do not call the tool again; answer now from the results you already have.";
+/**
+ * The `detail` a SESSION-BUDGET stop carries. A budget crossing is reported under the existing
+ * `aborted` code (the pass was stopped BY the session, not by a failure -- and the code union the two
+ * tools switch on does not grow), so this string is the ONLY thing that tells it from a genuine
+ * interrupt. Exported so a consumer matches the constant, never its own spelling of it.
+ */
+export declare const INNER_MODEL_BUDGET_EXCEEDED_DETAIL = "budget-exceeded";
+/**
+ * Runs a tool's inner model pass. See the module header for the contract; in one line: resolves the
+ * model, threads the abort signal, accounts every generation's usage, and never throws for an
+ * expected failure.
+ *
+ * `runtime` is for tests; an executor passes only `ctx` and the session's own registration is used.
+ */
+export declare function runInnerModel(ctx: Pick<ToolExecutionContext, "sessionId" | "agentId" | "signal">, request: InnerModelRequest, runtime?: InnerModelRuntime): Promise<InnerModelResult>;

package/dist/tools/impl/_search-budget.d.ts

@@ -0,0 +1,36 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+type EnvBrand = Pick<BrandProfile, "envPrefix">;
+export declare const DEFAULT_MAX_WEB_SEARCHES_PER_SESSION = 200;
+/**
+ * claude's own env name is `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` (research file, verbatim); this
+ * is Winter's copy of the MECHANISM (a session-cap override), branded through `envName` like every
+ * other product env name in this codebase -- never a literal `WINTER_...` string (brand-gate rule 9/10).
+ */
+export declare function maxWebSearchesPerSessionEnvName(brand?: EnvBrand): string;
+export declare function resolveMaxWebSearchesPerSession(env?: Record<string, string | undefined>, brand?: EnvBrand): number;
+export interface WebSearchBudgetReservation {
+    ok: boolean;
+    /** Calls already spent BEFORE this reservation (never incremented by a refusal). */
+    used: number;
+    cap: number;
+}
+/**
+ * Reserves ONE WebSearch call against `sessionId`'s budget -- called BEFORE the search runs, so a
+ * call that is never reserved (an input-validation failure, a wiring gap) never counts against it,
+ * matching claude's own `validateInput`-before-`call` ordering.
+ *
+ * `ok: false` leaves the counter UNCHANGED: the 201st call and the 202nd both read "200 of 200", not
+ * "201 of 200" -- the refusal is a repeatable fact about the session, not an escalating one.
+ */
+export declare function reserveWebSearchCall(sessionId: string, cap: number): WebSearchBudgetReservation;
+export declare function webSearchCallsUsed(sessionId: string): number;
+/**
+ * claude's own refusal text (research file, verbatim), with the env var name substituted for
+ * Winter's branded one. A RESULT, never an error: `durationSeconds:0, searchCount:0` in claude's own
+ * structured output, which this runtime does not carry -- the string alone is what reaches the model.
+ */
+export declare function webSearchBudgetRefusalText(used: number, cap: number, brand?: EnvBrand): string;
+/** Forgets `sessionId`'s spend (whole-branch review MINOR 4). Called from the ROOT run's teardown; idempotent. */
+export declare function forgetWebSearchBudgetForSession(sessionId: string): void;
+export declare function resetWebSearchBudgetForTest(): void;
+export {};

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

@@ -0,0 +1,37 @@
+export interface WebFetchCacheEntry {
+    /** The converted content's own UTF-8 byte length -- the cache's weight unit. */
+    bytes: number;
+    /** Always a 2xx status: redirects and errors are never cached (the caller enforces this by never calling `set` for them). */
+    code: number;
+    codeText: string;
+    /** The CONVERTED content (markdown, or raw text/passthrough) -- never the inner model's answer, which is why a cache hit still re-runs the digest pass. */
+    content: string;
+    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;
+}
+export declare const WEB_FETCH_CACHE_TTL_MS: number;
+export declare const WEB_FETCH_CACHE_MAX_BYTES: number;
+export type ClockFn = () => number;
+export declare class WebFetchCache {
+    private readonly sessions;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly maxBytes;
+    constructor(opts?: {
+        now?: ClockFn;
+        ttlMs?: number;
+        maxBytes?: number;
+    });
+    get(sessionId: string, url: string): WebFetchCacheEntry | undefined;
+    set(sessionId: string, url: string, entry: WebFetchCacheEntry): void;
+    /**
+     * Drops everything cached for `sessionId` (whole-branch review MINOR 4). Called from the ROOT run's
+     * teardown; idempotent, and unknown session ids are a no-op.
+     */
+    forgetSession(sessionId: string): void;
+    /** Test/diagnostic only: how many sessions currently hold at least one live entry. */
+    sessionCountForTest(): number;
+}
+/** The module-load default: one process-wide cache instance, sessions partitioned by key as documented above. */
+export declare const webFetchCache: WebFetchCache;

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

@@ -0,0 +1,26 @@
+export declare const WEB_FETCH_HTML_TRUNCATION_NOTICE = "\n\n[Content truncated due to length...]";
+/**
+ * Security review minor: `�` and `�` (a lone UTF-16 surrogate, `0xD800..0xDFFF`) previously
+ * round-tripped to U+0000 and an actual lone surrogate respectively -- both are exactly what the HTML
+ * spec's own numeric-character-reference algorithm maps to U+FFFD instead, and a lone surrogate in
+ * particular is a well-known way to make a downstream JSON/UTF-8 encode step (here: the digest
+ * REQUEST to the inner model) fail outright on otherwise ordinary-looking input.
+ */
+export declare function decodeHtmlEntities(input: string): string;
+export declare class HtmlBudgetExceededError extends Error {
+}
+/**
+ * Converts `html` to markdown using the rules above, driven by Bun's `HTMLRewriter` as a SAX walk
+ * (see the module header). Never throws for malformed markup on its own -- `HTMLRewriter` tolerates
+ * it the way a real HTML5 parser does -- but a genuine internal failure (including
+ * `HtmlBudgetExceededError`, security review finding N2) is caught and reported so the caller can
+ * fall back to the raw HTML, matching claude's own "turndown throwing -> raw HTML" rule.
+ */
+export declare function htmlToMarkdown(html: string): Promise<string>;
+/**
+ * The full conversion claude's own WebFetch applies: cap the RAW HTML at 1,048,576 chars first (so a
+ * pathological document costs conversion no more than that), convert what remains, and append the
+ * verbatim truncation notice when it was capped. A conversion failure falls back to the (possibly
+ * capped) raw HTML, per claude's own "turndown throwing -> raw HTML."
+ */
+export declare function convertFetchedHtml(html: string): Promise<string>;