@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/research/literature-reviewer.d.ts

@@ -3,17 +3,18 @@
  *
  * The conversation agent delegates batch literature/biology research by
  * calling this tool. `execute` derives a child `Session` (`forSubAgent`)
- * and runs `runAgent` over a focused literature-reviewer agent: a research
+ * and runs `runLoop` over a focused literature-reviewer agent: a research
  * brief in, a structured evidence report out. The child's transcript is
  * ephemeral — it lives only for this call and is never persisted (see the harness-thread-store spec).
  *
  * This is the whole of sub-agent delegation in the harness. There is no
  * `agents: {}` config, no `messageFilter`, no `stripParentToolParts`: the
  * child cannot see the parent's tool history because it is simply handed
- * none — only the brief. The child loop uses `passthroughStep` because the
- * entire tool call is one step in the parent loop (PR #3 caches it whole,
- * so the child never replays).
+ * none — only the brief. Inside the body of a workflow the call starts a
+ * child workflow (`loop/sub-agent.ts`), thus each call of the child is a step
+ * of its own.
  */
+import type { SubAgentRegistrar } from "../../loop/sub-agent.js";
 import type { ToolOutputStore } from "../../loop/tool-output.js";
 import { type ChatProvider } from "../../providers/types.js";
 import { type Tool } from "../define-tool.js";
@@ -21,7 +22,7 @@ import { type BioToolKeys } from "../bio/keys.js";
 import type { Logger } from "../../lib/logger.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import type { CitationResolver } from "../../citations/types.js";
-export interface LiteratureReviewerDeps {
+export type LiteratureReviewerDeps = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /** The LLM seam the child loop runs on. */
@@ -36,6 +37,6 @@ export interface LiteratureReviewerDeps {
     readonly toolOutputStore?: ToolOutputStore;
     /** Shared bibliographic verification service; all agent surfaces share its pacing/cache. */
     readonly citationResolver: CitationResolver;
-}
+};
 /** Build the `literature_reviewer` delegation tool bound to its provider. */
-export declare function createLiteratureReviewerTool(deps: LiteratureReviewerDeps): Tool;
+export declare function createLiteratureReviewerTool(deps: LiteratureReviewerDeps, registerSubAgent: SubAgentRegistrar): Tool;

package/dist/tools/research/literature-reviewer.js

@@ -3,21 +3,20 @@
  *
  * The conversation agent delegates batch literature/biology research by
  * calling this tool. `execute` derives a child `Session` (`forSubAgent`)
- * and runs `runAgent` over a focused literature-reviewer agent: a research
+ * and runs `runLoop` over a focused literature-reviewer agent: a research
  * brief in, a structured evidence report out. The child's transcript is
  * ephemeral — it lives only for this call and is never persisted (see the harness-thread-store spec).
  *
  * This is the whole of sub-agent delegation in the harness. There is no
  * `agents: {}` config, no `messageFilter`, no `stripParentToolParts`: the
  * child cannot see the parent's tool history because it is simply handed
- * none — only the brief. The child loop uses `passthroughStep` because the
- * entire tool call is one step in the parent loop (PR #3 caches it whole,
- * so the child never replays).
+ * none — only the brief. Inside the body of a workflow the call starts a
+ * child workflow (`loop/sub-agent.ts`), thus each call of the child is a step
+ * of its own.
  */
 import { err, ok } from "neverthrow";
 import { z } from "zod";
-import { finalText, runAgent } from "../../loop/run-agent.js";
-import { passthroughStep } from "../../loop/run-step.js";
+import { finalText, runLoop } from "../../loop/run-loop.js";
 import { literatureReviewerPrompt } from "../../prompts/literature-reviewer.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
 import { forSubAgent } from "../../auth/types.js";
@@ -35,9 +34,9 @@ const AGENT_ID = "literature-reviewer";
 /** Multi-tool research budget — search → read → synthesize over many genes. */
 const REVIEWER_MAX_ITERATIONS = 30;
 /** Build the `literature_reviewer` delegation tool bound to its provider. */
-export function createLiteratureReviewerTool(deps) {
+export function createLiteratureReviewerTool(deps, registerSubAgent) {
     const ncbi = createNcbiTools(deps.bioKeys);
-    const chemDb = createChemDbTools(deps.bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
+    const chemDb = createChemDbTools(deps.bioKeys, { logger: deps.logger });
     const reviewerTools = [
         searchGeneTool,
         searchProteinTool,
@@ -56,6 +55,17 @@ export function createLiteratureReviewerTool(deps) {
         tools: reviewerTools,
         maxIterations: REVIEWER_MAX_ITERATIONS,
     };
+    // A review ends with a report, or with the finish reason of a run that gave none.
+    const review = registerSubAgent(AGENT_ID, async ({ payload, ctx, loop }) => {
+        const { messages: transcript, finish } = await runLoop(agent, [{ role: "user", content: payload.brief }], forSubAgent(ctx.session, AGENT_ID), {
+            ...loop,
+            provider: deps.provider,
+            usageRecorder: deps.usageRecorder,
+            toolOutputStore: deps.toolOutputStore,
+        });
+        const report = finalText(transcript);
+        return report.trim() === "" ? { finishReason: finish.reason } : { report };
+    });
     return defineTool({
         id: "literature_reviewer",
         description: "Delegate batch literature/biology research to a sub-agent: looking up " +
@@ -78,29 +88,20 @@ export function createLiteratureReviewerTool(deps) {
                 "context. The reviewer sees only this — include everything it needs."),
         }),
         describeCall: "none",
+        startsWorkflow: true,
         execute: async ({ brief }, ctx) => {
-            const { messages: transcript, finish } = await runAgent(agent, [{ role: "user", content: brief }], forSubAgent(ctx.session, AGENT_ID), {
-                provider: deps.provider,
-                signal: ctx.signal,
-                emit: ctx.emit,
-                runStep: passthroughStep,
-                usageRecorder: deps.usageRecorder,
-                toolOutputStore: deps.toolOutputStore,
-                // Fold the child's calls into the turn total the root loop reports.
-                turnUsage: ctx.turnUsage,
-                // Keeps the usage record keys of two parallel reviews disjoint —
-                // same frame, same call path, same loop-local step names.
-                invocationId: ctx.invocationId,
-            });
-            const report = finalText(transcript);
+            const reviewed = await review({ brief }, ctx);
             // A child run can end with no final text. Examples are a terminal
-            // reply with no text block, and a capped-out run whose wrap-up is
-            // empty. An ok result with an empty report hides that failure, so
-            // the tool returns an error that names the finish reason.
-            if (report.trim() === "") {
-                return err({ error: `The literature reviewer gave no report (finish reason: ${finish.reason}). Retry, or narrow the brief.`, retryable: true });
+            // reply with no text block, and a run that reached its step cap. An
+            // ok result with an empty report hides that failure, so the tool
+            // returns an error that names the finish reason.
+            if ("finishReason" in reviewed) {
+                return err({
+                    error: `The literature reviewer gave no report (finish reason: ${reviewed.finishReason}). Retry, or narrow the brief.`,
+                    retryable: true,
+                });
             }
-            return ok({ report });
+            return ok({ report: reviewed.report });
         },
     });
 }

package/dist/tools/research/search-arxiv.d.ts

@@ -11,6 +11,6 @@ type SearchArxivOutput = {
 };
 export declare const searchArxivTool: import("../define-tool.js").Tool<{
     query: string;
-    limit: number;
     categories?: string[] | undefined;
+    limit: number;
 }, SearchArxivOutput>;

package/dist/tools/research/search-arxiv.js

@@ -26,7 +26,7 @@ export const searchArxivTool = defineTool({
     }),
     describeCall: "none",
     execute: async ({ query, categories, limit }, context) => {
-        const result = await source.search({ query, ...(categories === undefined ? {} : { categories }), limit }, context.signal);
+        const result = await source.search({ query, categories, limit }, context.signal);
         if (result.status !== "ok")
             return ok({ success: false, error: result.detail, papers: [] });
         return ok({ success: true, papers: result.value });

package/dist/tools/research/search-github-repos.d.ts

@@ -9,6 +9,8 @@
  * `language` as required and nullable, thus an absent value is an explicit
  * `null`. The OpenAPI document gives the modifier of each field.
  */
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 type SearchGithubReposOutput = {
     success: false;
     error: string;
@@ -17,20 +19,21 @@ type SearchGithubReposOutput = {
     success: true;
     repos: GithubRepo[];
 };
-export interface GithubRepo {
+export type GithubRepo = {
     url: string;
     fullName: string;
     description?: string;
     stars: number;
     language?: string;
     lastUpdated?: string;
-}
+};
 export declare function parseGithubReposResponse(raw: unknown): GithubRepo[];
+declare const SearchGithubReposInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
 export declare function createSearchGithubReposTool(deps: {
     githubToken?: string;
-}): import("../define-tool.js").Tool<{
-    query: string;
-    limit: number;
-    language?: string | undefined;
-}, SearchGithubReposOutput>;
+}): Tool<z.infer<typeof SearchGithubReposInputSchema>, SearchGithubReposOutput>;
 export {};

package/dist/tools/research/search-github-repos.js

@@ -13,6 +13,8 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
+import { isUnknownArray } from "../../lib/unknown-array.js";
 const BASE_URL = "https://api.github.com/search/repositories";
 // Raw GitHub search wire shape, validated at the fetch boundary. Every field is
 // optional — `parseGithubReposResponse` already filters out items missing the
@@ -33,23 +35,30 @@ const GithubReposResponseSchema = z.object({
         .optional(),
 });
 export function parseGithubReposResponse(raw) {
-    const items = raw?.items;
-    if (!Array.isArray(items))
+    const items = parseUnknownRecord(raw)?.items;
+    if (!isUnknownArray(items))
         return [];
-    return items
-        .filter((i) => typeof i === "object" &&
-        i !== null &&
-        typeof i.html_url === "string" &&
-        typeof i.full_name === "string")
-        .map((i) => ({
-        url: String(i.html_url),
-        fullName: String(i.full_name),
-        description: typeof i.description === "string" ? i.description : undefined,
-        stars: typeof i.stargazers_count === "number" ? i.stargazers_count : 0,
-        language: typeof i.language === "string" ? i.language : undefined,
-        lastUpdated: typeof i.updated_at === "string" ? i.updated_at : undefined,
-    }));
+    return items.flatMap((item) => {
+        const record = parseUnknownRecord(item);
+        if (record === undefined || typeof record.html_url !== "string" || typeof record.full_name !== "string")
+            return [];
+        return [
+            {
+                url: record.html_url,
+                fullName: record.full_name,
+                description: typeof record.description === "string" ? record.description : undefined,
+                stars: typeof record.stargazers_count === "number" ? record.stargazers_count : 0,
+                language: typeof record.language === "string" ? record.language : undefined,
+                lastUpdated: typeof record.updated_at === "string" ? record.updated_at : undefined,
+            },
+        ];
+    });
 }
+const SearchGithubReposInputSchema = z.object({
+    query: z.string().describe("GitHub search syntax. Plain text matches anywhere; qualifiers " + 'like "topic:bioinformatics" or "stars:>100" are supported.'),
+    language: z.string().optional().describe('Optional language filter (e.g., "python").'),
+    limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
+});
 export function createSearchGithubReposTool(deps) {
     return defineTool({
         id: "search_github_repos",
@@ -64,13 +73,7 @@ export function createSearchGithubReposTool(deps) {
             "and `success: false` with an `error` string means GitHub could not be " +
             "reached or refused the request (the low unauthenticated rate limit " +
             "lands here). Report either one and continue, do not retry unchanged.",
-        inputSchema: z.object({
-            query: z
-                .string()
-                .describe("GitHub search syntax. Plain text matches anywhere; qualifiers " + 'like "topic:bioinformatics" or "stars:>100" are supported.'),
-            language: z.string().optional().describe('Optional language filter (e.g., "python").'),
-            limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
-        }),
+        inputSchema: SearchGithubReposInputSchema,
         describeCall: "none",
         execute: async ({ query, language, limit }) => {
             const q = language ? `${query} language:${language}` : query;

package/dist/tools/research/search-semantic-scholar.js

@@ -9,7 +9,7 @@ export function createSearchSemanticScholarTool(options = {}) {
         maxRetries: 3,
         retryDelayMs: 1_000,
         timeoutMs: 90_000,
-        ...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+        apiKey: options.apiKey,
     });
     return defineTool({
         id: "search_semantic_scholar",

package/dist/tools/research/searxng-engine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The SearXNG realization of the `WebSearchEngine` capability.
+ *
+ * One SearXNG instance is the only engine the harness ships (the embedder owns
+ * it and builds this realization at its composition root). The call rides
+ * `apiFetchValidated` with a zod schema over the JSON envelope, and every
+ * failure lands on the error side of the `Result` as the data-status variant the
+ * tool reports — an HTTP error, a spent retryable status, a schema mismatch,
+ * and a body that is not JSON are answers, not errors of the turn.
+ */
+import { z } from "zod";
+import { type ApiError } from "../lib/api-utils.js";
+import type { WebSearchEngine, WebSearchEngineError, WebSearchPage } from "./web-search.js";
+export declare const SearxngSearchResponseSchema: z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        answer: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+/** Map a parsed SearXNG envelope to the rows the tool reports. */
+export declare function mapSearxngResponse(response: z.infer<typeof SearxngSearchResponseSchema>): WebSearchPage;
+/**
+ * Normalize the SearXNG base URL the embedder gives: `http`/`https` only, no
+ * user name and no password, and no query, fragment, or trailing slash. The
+ * value is a composition-root constant, thus a bad one throws here at wiring
+ * time and not inside a tool call.
+ */
+export declare function normalizeSearxngBaseUrl(raw: string): string;
+/** Map one `ApiError` of the helper to the error data variant it names. */
+export declare function describeSearchFailure(error: ApiError): WebSearchEngineError;
+export type SearxngEngineDeps = {
+    /** The base URL of the SearXNG instance the embedder runs. */
+    readonly baseUrl: string;
+};
+export declare function createSearxngEngine(deps: SearxngEngineDeps): WebSearchEngine;

package/dist/tools/research/searxng-engine.js

@@ -0,0 +1,122 @@
+/**
+ * The SearXNG realization of the `WebSearchEngine` capability.
+ *
+ * One SearXNG instance is the only engine the harness ships (the embedder owns
+ * it and builds this realization at its composition root). The call rides
+ * `apiFetchValidated` with a zod schema over the JSON envelope, and every
+ * failure lands on the error side of the `Result` as the data-status variant the
+ * tool reports — an HTTP error, a spent retryable status, a schema mismatch,
+ * and a body that is not JSON are answers, not errors of the turn.
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+import { apiFetchValidated } from "../lib/api-utils.js";
+import { isAllDigits, trimTrailingOf } from "../../lib/text.js";
+// SearXNG sends an explicit null for a snippet no engine produced, and it omits
+// a key no engine filled, thus each field is optional and nullable alike. The
+// fields an engine adds (`engine`, `score`, `publishedDate`, …) pass and strip.
+const SearxngResultSchema = z.object({
+    title: z.string().nullable().optional(),
+    url: z.string().nullable().optional(),
+    content: z.string().nullable().optional(),
+});
+// An answer is an object of a changing shape (`answer`, `url`, `template`,
+// `engine`, …), thus the schema keeps it loose and the mapper reads the two
+// fields the tool reports.
+export const SearxngSearchResponseSchema = z.object({
+    results: z.array(SearxngResultSchema).optional(),
+    answers: z.array(z.looseObject({ answer: z.string().nullable().optional(), url: z.string().nullable().optional() })).optional(),
+});
+/** Map a parsed SearXNG envelope to the rows the tool reports. */
+export function mapSearxngResponse(response) {
+    const answers = [];
+    for (const row of response.answers ?? []) {
+        const answer = typeof row.answer === "string" ? row.answer : undefined;
+        const url = typeof row.url === "string" ? row.url : undefined;
+        if (answer === undefined && url === undefined)
+            continue;
+        answers.push({ answer, url });
+    }
+    const results = [];
+    for (const row of response.results ?? []) {
+        if (typeof row.url !== "string" || typeof row.title !== "string")
+            continue;
+        results.push({ title: row.title, url: row.url, snippet: typeof row.content === "string" ? row.content : undefined });
+    }
+    return { answers, results };
+}
+/**
+ * Normalize the SearXNG base URL the embedder gives: `http`/`https` only, no
+ * user name and no password, and no query, fragment, or trailing slash. The
+ * value is a composition-root constant, thus a bad one throws here at wiring
+ * time and not inside a tool call.
+ */
+export function normalizeSearxngBaseUrl(raw) {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`The SearXNG base URL must use http or https: ${raw}`);
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        throw new Error(`The SearXNG base URL must carry no user name or password: ${raw}`);
+    }
+    return `${parsed.protocol}//${parsed.host}${trimTrailingOf(parsed.pathname, "/")}`;
+}
+/** The first 300 characters of a body, as the HTTP-error text reports it. */
+function bodyExcerpt(body) {
+    return body.length > 300 ? body.slice(0, 300) : body;
+}
+/** Map one `ApiError` of the helper to the error data variant it names. */
+export function describeSearchFailure(error) {
+    switch (error.type) {
+        case "http_status":
+            return {
+                status: "http_error",
+                httpStatus: error.status,
+                text: `SearXNG answered HTTP ${error.status}${error.body ? `: ${bodyExcerpt(error.body)}` : ""}`,
+            };
+        case "invalid_response":
+            return { status: "schema_mismatch", text: `SearXNG response did not match the expected schema: ${error.issues}` };
+        case "timeout":
+            return {
+                status: "not_json",
+                text: `SearXNG did not answer with a valid JSON body: the request timed out after ${error.timeoutMs}ms`,
+            };
+        case "exhausted": {
+            // A spent retryable status arrives as `exhausted` with an `HTTP <status>`
+            // last error, because the helper reports it there and not as `http_status`.
+            const statusText = error.lastError.startsWith("HTTP ") ? error.lastError.slice("HTTP ".length) : undefined;
+            const status = statusText !== undefined && isAllDigits(statusText) ? statusText : null;
+            if (status) {
+                return {
+                    status: "retryable_status",
+                    httpStatus: Number(status),
+                    text: `SearXNG answered HTTP ${status} and spent its retry attempt`,
+                };
+            }
+            // A transport failure and a body that will not parse share this bucket,
+            // and the text stays fixed so it never echoes a runtime parse message.
+            return {
+                status: "not_json",
+                text: "SearXNG did not answer with a valid JSON body",
+                detail: error.lastError,
+            };
+        }
+    }
+}
+export function createSearxngEngine(deps) {
+    const baseUrl = normalizeSearxngBaseUrl(deps.baseUrl);
+    return {
+        async search({ query, recencyFilter }) {
+            const params = new URLSearchParams({ q: query, format: "json" });
+            if (recencyFilter !== undefined)
+                params.set("time_range", recencyFilter);
+            const response = await apiFetchValidated(`${baseUrl}/search?${params}`, SearxngSearchResponseSchema, {
+                headers: { Accept: "application/json" },
+                maxRetries: 0,
+            });
+            if (response.isErr())
+                return err(describeSearchFailure(response.error));
+            return ok(mapSearxngResponse(response.value));
+        },
+    };
+}

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

@@ -0,0 +1,127 @@
+/**
+ * `web_fetch` — the page-reading step of the conversation agent's web research.
+ *
+ * One URL in, extracted text out: HTML becomes Markdown (Readability over a
+ * `linkedom` DOM, then Turndown, with the body text as the fallback), a PDF
+ * becomes the text of its first 100 pages through `pdf-parse`, and a text or
+ * JSON body passes through. A bad scheme, an internal address, an HTTP error, an
+ * oversized body, a redirect chain past the limit, and a body the tool cannot
+ * extract are all normal results on the ok channel — never a failure of the
+ * turn.
+ *
+ * The address guard reads the address the connection itself uses, because a
+ * separate name resolution before a `fetch` races the resolver (DNS rebinding):
+ * a literal host classifies before the request is sent — the connection layer
+ * runs no name lookup for a literal — and a name classifies inside the `lookup`
+ * hook of `node:http`/`node:https`, over every address of the resolution,
+ * because the connect layer falls back to a later address after an earlier one
+ * fails. A guarded hop is destroyed before it connects, and the call gives a
+ * refusal that names the origin. The tool asks nothing.
+ */
+import { type LookupAddress, type LookupAllOptions } from "node:dns";
+import { type LookupFunction } from "node:net";
+import { z } from "zod";
+import { type ToolOutputStore } from "../../loop/tool-output.js";
+import { type Tool } from "../define-tool.js";
+/** The response head and body stream of one hop, narrowed to what the tool reads. */
+export type WebFetchHopResponse = {
+    readonly statusCode?: number;
+    readonly headers: Record<string, string | string[] | undefined>;
+    on(event: "data", listener: (chunk: Buffer) => void): void;
+    on(event: "end", listener: () => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+    destroy(error?: Error): void;
+    /** A real response holds these; the decode path pauses the encoded side while the decoder drains. */
+    pause?(): void;
+    resume?(): void;
+};
+/** One hop request, narrowed to what the tool drives. */
+export type WebFetchHopRequestHandle = {
+    on(event: "response", listener: (response: WebFetchHopResponse) => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+    on(event: "timeout", listener: () => void): void;
+    end(): void;
+    destroy(error?: Error): void;
+};
+export type WebFetchHopRequestOptions = {
+    readonly headers: Record<string, string>;
+    readonly lookup?: LookupFunction;
+    readonly timeoutMs: number;
+};
+/** One HTTP hop. The default is the real `node:http`/`node:https` request; a test can substitute a recorded hop. */
+export type WebFetchHopRequest = (url: URL, options: WebFetchHopRequestOptions) => WebFetchHopRequestHandle;
+/** A name resolution that answers every address at once, the `all: true` shape of `dns.lookup`. */
+export type WebFetchLookup = (hostname: string, options: LookupAllOptions, callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void) => void;
+export type WebFetchKept = {
+    readonly ref: string;
+    readonly keptLength: number;
+};
+export type WebFetchPdfCut = {
+    readonly totalPages: number;
+    readonly pagesRead: number;
+};
+export type WebFetchOk = {
+    readonly status: "ok";
+    readonly finalUrl: string;
+    readonly contentType: string;
+    readonly text: string;
+    readonly totalLength: number;
+    readonly cut: boolean;
+    readonly pdfCut?: WebFetchPdfCut;
+    readonly kept?: WebFetchKept;
+    readonly remainderNotKept?: boolean;
+};
+export type WebFetchOutput = WebFetchOk | {
+    readonly status: "invalid_url";
+    readonly text: string;
+} | {
+    readonly status: "unsupported_scheme";
+    readonly scheme: string;
+    readonly text: string;
+} | {
+    readonly status: "refused";
+    readonly text: string;
+} | {
+    readonly status: "http_error";
+    readonly httpStatus: number;
+    readonly text: string;
+} | {
+    readonly status: "redirect_limit";
+    readonly text: string;
+} | {
+    readonly status: "body_too_large";
+    readonly limitBytes: number;
+    readonly contentType: string;
+    readonly text: string;
+} | {
+    readonly status: "unextractable";
+    readonly contentType: string;
+    readonly text: string;
+    readonly detail?: string;
+} | {
+    readonly status: "request_failed";
+    readonly text: string;
+    readonly detail?: string;
+};
+export type WebFetchToolDeps = {
+    readonly toolOutputStore?: ToolOutputStore;
+    /** Substitutes the name resolution, so a test answers a controlled address set. The default is `dns.lookup`. */
+    readonly lookup?: WebFetchLookup;
+    /** Substitutes one HTTP hop, so a test serves recorded bodies offline. The default is the real node hop. */
+    readonly hopRequest?: WebFetchHopRequest;
+};
+/**
+ * Estimate the deepest element nesting of an HTML document in one linear scan, without building a DOM.
+ * Deep nesting is the input shape that makes the linkedom/Readability pair burn CPU for minutes on a
+ * body under the byte limit, and the extraction is synchronous, so no deadline can interrupt it — the
+ * bound must gate the parse, not watch it. The estimate never parses: void elements and self-closing
+ * tags open no level, raw-text elements skip to their close, quoted attribute values hide their `<`,
+ * and an implied-close family pops its open peers, so a list or a table of any length stays flat and a
+ * stray close tag pops to its nearest matching open.
+ */
+export declare function htmlNestingDepth(html: string): number;
+declare const WebFetchInputSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+export declare function createWebFetchTool(deps?: WebFetchToolDeps): Tool<z.infer<typeof WebFetchInputSchema>, WebFetchOutput>;
+export {};