@inflexa-ai/harness 0.45.0 → 0.45.1

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

@@ -0,0 +1,124 @@
+/**
+ * `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, a denied approval, 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 the user is asked, and an approval
+ * re-sends the hop.
+ */
+import { type LookupAddress, type LookupAllOptions } from "node:dns";
+import { type LookupFunction } from "node:net";
+import { type ToolOutputStore } from "../../loop/tool-output.js";
+/** The response head and body stream of one hop, narrowed to what the tool reads. */
+export interface 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 interface 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 interface 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 interface WebFetchKept {
+    readonly ref: string;
+    readonly keptLength: number;
+}
+export interface WebFetchPdfCut {
+    readonly totalPages: number;
+    readonly pagesRead: number;
+}
+export interface 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 feedback?: 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 interface 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;
+export declare function createWebFetchTool(deps?: WebFetchToolDeps): import("../define-tool.js").Tool<{
+    url: string;
+}, WebFetchOutput>;