@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/tools/research/guarded-address.js

@@ -0,0 +1,148 @@
+/**
+ * The guarded-address classifier of the web research tools.
+ *
+ * One pure function over one address: `isGuardedAddress` answers whether the
+ * address falls in a range that `web_fetch` asks the user about before it
+ * connects. The ranges are a pinned subset of the special-purpose address
+ * ranges of the IANA registries — loopback, private, shared, link-local,
+ * multicast, reserved, documentation, and benchmarking space, IPv4 and IPv6.
+ * A public unicast address is never guarded.
+ *
+ * The caller owns the question "which address does the connection use": the
+ * classifier never resolves a name and it never reads the network.
+ */
+import { isIP } from "node:net";
+/** Parse a dotted-quad IPv4 address into its 32-bit value. Anything else gives null. */
+function ipv4ToNumber(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return null;
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const octet = Number(part);
+        if (octet > 255)
+            return null;
+        value = (value << 8) | octet;
+    }
+    return value >>> 0;
+}
+/** Parse an IPv6 address into its 128-bit value. Anything else gives null. */
+function ipv6ToBigInt(ip) {
+    let text = ip.toLowerCase();
+    // An embedded IPv4 tail stands for its two low-order groups.
+    if (text.includes(".")) {
+        const lastColon = text.lastIndexOf(":");
+        const tail = ipv4ToNumber(text.slice(lastColon + 1));
+        if (tail === null)
+            return null;
+        const high = ((tail >>> 16) & 0xffff).toString(16);
+        const low = (tail & 0xffff).toString(16);
+        text = `${text.slice(0, lastColon + 1)}${high}:${low}`;
+    }
+    const groupsOf = (half) => {
+        if (half === "")
+            return [];
+        const groups = [];
+        for (const group of half.split(":")) {
+            if (!/^[0-9a-f]{1,4}$/.test(group))
+                return null;
+            groups.push(BigInt(`0x${group}`));
+        }
+        return groups;
+    };
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const left = groupsOf(halves[0] ?? "");
+    const right = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
+    if (left === null || right === null)
+        return null;
+    const fill = 8 - left.length - right.length;
+    if (halves.length === 2 ? fill < 0 : fill !== 0)
+        return null;
+    return [...left, ...new Array(Math.max(fill, 0)).fill(0n), ...right].reduce((acc, group) => (acc << 16n) | group, 0n);
+}
+const ipv4Span = (first, last) => {
+    const low = ipv4ToNumber(first);
+    const high = ipv4ToNumber(last);
+    if (low === null || high === null)
+        throw new Error(`Bad IPv4 range literal: ${first}..${last}`);
+    return { first: low, last: high };
+};
+const ipv6Span = (first, last) => {
+    const low = ipv6ToBigInt(first);
+    const high = ipv6ToBigInt(last);
+    if (low === null || high === null)
+        throw new Error(`Bad IPv6 range literal: ${first}..${last}`);
+    return { first: low, last: high };
+};
+/**
+ * The pinned IPv4 table. `240.0.0.0/4` holds the reserved and the broadcast
+ * space together, and it ends at the top of the address family.
+ */
+const GUARDED_IPV4_RANGES = [
+    ipv4Span("0.0.0.0", "0.255.255.255"), // 0.0.0.0/8
+    ipv4Span("10.0.0.0", "10.255.255.255"), // 10.0.0.0/8
+    ipv4Span("100.64.0.0", "100.127.255.255"), // 100.64.0.0/10
+    ipv4Span("127.0.0.0", "127.255.255.255"), // 127.0.0.0/8
+    ipv4Span("169.254.0.0", "169.254.255.255"), // 169.254.0.0/16
+    ipv4Span("172.16.0.0", "172.31.255.255"), // 172.16.0.0/12
+    ipv4Span("192.0.0.0", "192.0.0.255"), // 192.0.0.0/24
+    ipv4Span("192.0.2.0", "192.0.2.255"), // 192.0.2.0/24
+    ipv4Span("192.88.99.0", "192.88.99.255"), // 192.88.99.0/24
+    ipv4Span("192.168.0.0", "192.168.255.255"), // 192.168.0.0/16
+    ipv4Span("198.18.0.0", "198.19.255.255"), // 198.18.0.0/15
+    ipv4Span("198.51.100.0", "198.51.100.255"), // 198.51.100.0/24
+    ipv4Span("203.0.113.0", "203.0.113.255"), // 203.0.113.0/24
+    ipv4Span("224.0.0.0", "239.255.255.255"), // 224.0.0.0/4
+    ipv4Span("240.0.0.0", "255.255.255.255"), // 240.0.0.0/4
+];
+/**
+ * The pinned IPv6 table, without `::ffff:0:0/96`: an IPv4-mapped address
+ * normalizes to its IPv4 half first, thus that range classifies through the
+ * IPv4 table above.
+ */
+const GUARDED_IPV6_RANGES = [
+    ipv6Span("::", "::"), // ::/128
+    ipv6Span("::1", "::1"), // ::1/128
+    ipv6Span("64:ff9b::", "64:ff9b::ffff:ffff"), // 64:ff9b::/96
+    ipv6Span("64:ff9b:1::", "64:ff9b:1:ffff:ffff:ffff:ffff:ffff"), // 64:ff9b:1::/48
+    ipv6Span("100::", "100::ffff:ffff:ffff:ffff"), // 100::/64
+    ipv6Span("2001::", "2001:0:ffff:ffff:ffff:ffff:ffff:ffff"), // 2001::/32
+    ipv6Span("2001:db8::", "2001:db8:ffff:ffff:ffff:ffff:ffff:ffff"), // 2001:db8::/32
+    ipv6Span("2002::", "2002:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // 2002::/16
+    ipv6Span("fc00::", "fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // fc00::/7
+    ipv6Span("fe80::", "febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // fe80::/10
+    ipv6Span("ff00::", "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"), // ff00::/8
+];
+function isGuardedIpv4(value) {
+    return GUARDED_IPV4_RANGES.some((range) => value >= range.first && value <= range.last);
+}
+function isGuardedIpv6(value) {
+    return GUARDED_IPV6_RANGES.some((range) => value >= range.first && value <= range.last);
+}
+/**
+ * Is this address one the web tools guard? An IP literal of either family
+ * classifies against the pinned table; the IPv4-mapped IPv6 form
+ * (`::ffff:10.0.0.1`) classifies as its IPv4 half. A value that is not an IP
+ * address gives false — the caller resolves names before it reaches here.
+ */
+export function isGuardedAddress(ip) {
+    const family = isIP(ip);
+    if (family === 4) {
+        const value = ipv4ToNumber(ip);
+        return value !== null && isGuardedIpv4(value);
+    }
+    if (family === 6) {
+        const value = ipv6ToBigInt(ip);
+        if (value === null)
+            return false;
+        // The IPv4-mapped form, ::ffff:0:0/96, classifies as its IPv4 half.
+        if (value >> 32n === 0xffffn)
+            return isGuardedIpv4(Number(value & 0xffffffffn));
+        return isGuardedIpv6(value);
+    }
+    return false;
+}

package/dist/tools/research/inspect-data-profile.d.ts

@@ -161,7 +161,7 @@ interface FailedOutput {
 }
 export type InspectDataProfileOutput = OverviewOutput | GroupsOutput | FilesOutput | AbsentOutput | PendingOutput | FailedOutput;
 export declare function createInspectDataProfileTool(pool: Pool): import("../define-tool.js").Tool<{
-    scope?: "overview" | "groups" | "files" | undefined;
+    scope?: "groups" | "files" | "overview" | undefined;
     page?: number | undefined;
     pageSize?: number | undefined;
 }, InspectDataProfileOutput>;

package/dist/tools/research/inspect-run.d.ts

@@ -2,7 +2,7 @@
  * inspectRun — inspect workflow runs for the current analysis.
  *
  * Results are pull-only: workflows never append completion messages to a
- * conversation. List mode is active-first and paged. Targeted mode makes
+ * conversation. List mode puts the running runs first and is paged. Targeted mode makes
  * readiness explicit and can perform one bounded, abort-aware wait.
  */
 import type { Pool } from "pg";

package/dist/tools/research/inspect-run.js

@@ -2,7 +2,7 @@
  * inspectRun — inspect workflow runs for the current analysis.
  *
  * Results are pull-only: workflows never append completion messages to a
- * conversation. List mode is active-first and paged. Targeted mode makes
+ * conversation. List mode puts the running runs first and is paged. Targeted mode makes
  * readiness explicit and can perform one bounded, abort-aware wait.
  */
 import { setTimeout as sleep } from "node:timers/promises";
@@ -20,7 +20,7 @@ const systemClock = {
     wait: (ms, signal) => sleep(ms, undefined, { signal }),
 };
 function isTerminal(status) {
-    return status === "completed" || status === "partial" || status === "failed" || status === "canceled";
+    return status === "completed" || status === "partial" || status === "failed" || status === "canceled" || status === "suspended_insufficient_funds";
 }
 function formatRun(r, verbose, exposePaths = isTerminal(r.status)) {
     return {
@@ -98,10 +98,10 @@ export function createInspectRunTool(pool, clock = systemClock) {
     return defineTool({
         id: "inspect_run",
         description: "Inspect workflow runs for this analysis. A run never posts its completion into the conversation; this tool is how you read it. " +
-            "Without a runId, returns an active-first paged list (running, suspended, then terminal history) with total and hasMore. " +
-            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the run does not progress until it is resumed); " +
+            "Without a runId, returns a paged list (running runs first, then each other run) with total and hasMore. " +
+            "With a runId, returns the run, its steps, and an inspectionState: not_found; in_progress; suspended (the host suspended the run, it does not progress, and a new run of the plan can start); " +
             "or terminal (run.status completed, partial, failed, or canceled). " +
-            "Output paths appear only on a terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
+            "Output paths appear only on a suspended or terminal run: run.synthesisPath when synthesisStatus is produced, and the summaryPath of each step that ran. " +
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
             "A wait on the run that the caller itself runs inside returns at once with selfWaitPrevented. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
@@ -179,8 +179,8 @@ export function createInspectRunTool(pool, clock = systemClock) {
             if (run.status === "suspended_insufficient_funds") {
                 return ok({
                     inspectionState: "suspended",
-                    message: "This run is suspended and will not progress until it is resumed.",
-                    run: formatRun(run, verbose, false),
+                    message: "The host suspended this run. The run does not progress. A new run of the plan can start.",
+                    run: formatRun(run, verbose, true),
                     steps,
                     ...wait,
                 });

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 interface 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,120 @@
+/**
+ * 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";
+// 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}${parsed.pathname.replace(/\/+$/, "")}`;
+}
+/** 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 status = /^HTTP (\d+)$/.exec(error.lastError);
+            if (status) {
+                return {
+                    status: "retryable_status",
+                    httpStatus: Number(status[1]),
+                    text: `SearXNG answered HTTP ${status[1]} 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,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>;