@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/tools/research/generate-plan.js

@@ -23,7 +23,7 @@
  * `Session`. The planner prompt injects the agent catalog and exposes the
  * terminal-tool surface above.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { formatAgentCatalog } from "../../agents/sandbox-catalog.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
@@ -36,21 +36,24 @@ import { createReadToolOutputTool } from "../read-tool-output.js";
 import { createListAvailablePackagesTool } from "../sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
 import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
+import { degenerateTerminalText } from "../terminal-text.js";
 import { searchGeoDatasetsTool } from "../bio/search-geo-datasets.js";
 import { createNcbiTools } from "../bio/keys.js";
+import { createKnowledgeTools } from "../knowledge/index.js";
 import { queryDocsTool, resolveLibraryIdTool } from "./context7-docs.js";
 import { searchArxivTool } from "./search-arxiv.js";
 import { createSearchGithubReposTool } from "./search-github-repos.js";
 import { createSearchSemanticScholarTool } from "./search-semantic-scholar.js";
 import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../../app/data-profile-orientation.js";
 import { DEFAULT_SANDBOX_MAX_STEPS } from "../../config/resource-limits.js";
+import { guardRepeatedCalls } from "../../loop/call-guard.js";
 import { plannerPrompt } from "../../prompts/planner.js";
 import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.js";
 import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { unwrapOrThrow } from "../../lib/result.js";
-import { hintForZodIssue } from "../../lib/zod-issues.js";
+import { decodeObjectString, hintForZodIssue } from "../../lib/zod-issues.js";
 import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.js";
 // ── Tool-level config ──────────────────────────────────────────────
 /** Sub-agent identity for the planner — provenance only. */
@@ -69,6 +72,14 @@ const PLANNER_AGENT_ID = "planner";
 const PLANNER_MAX_ITERATIONS = 300;
 /** Wall-clock guard for a single plan-generation invocation. */
 const PLAN_TIMEOUT_MS = 1_800_000;
+/**
+ * The refusals of the call guard that end the search phase of one plan. A
+ * planner that the guard refused this many times is not searching, it is
+ * looping, and the wrap-up plus the salvage turn give it the plan it has. Six
+ * is above any count a frontier planner reached in the Phase 0 campaign
+ * (zero) and far below the hundred-plus refused calls of a looping run.
+ */
+const PLANNER_REFUSAL_LIMIT = 6;
 // ── Diagnostic bounds ───────────────────────────────────────────────
 //
 // This tool runs on `passthroughStep`: it writes no ledger row and owns no
@@ -297,14 +308,150 @@ function zodIssuesToValidationIssues(error, input, rootPath = "plan") {
         hint: hintForZodIssue(i, input),
     }));
 }
+function rememberAnswer(memory, answer) {
+    memory.steps.clear();
+    memory.claims.clear();
+    memory.digest = answer.snapshot.digest;
+    for (const step of answer.plan_skeleton) {
+        memory.steps.set(step.id, step);
+        for (const claim of step.grounding.claims)
+            memory.claims.add(claim);
+        for (const alternative of step.alternatives)
+            for (const rule of alternative.rules)
+                memory.claims.add(rule);
+        if (step.disputed !== undefined)
+            memory.claims.add(step.disputed.rule);
+    }
+    for (const claim of answer.claims)
+        memory.claims.add(claim.id);
+    for (const flag of answer.flags)
+        memory.claims.add(flag.rule);
+}
+/** The rule of a claim id: `R-0001` of `R-0001@e7d0`. */
+function ruleOf(claim) {
+    return claim.split("@")[0] ?? claim;
+}
+/** One claim id per rule of the answer. A rule with two ids in one answer cannot be repaired, and it is absent. */
+function claimsByRule(claims) {
+    const byRule = new Map();
+    const ambiguous = new Set();
+    for (const claim of claims) {
+        const rule = ruleOf(claim);
+        if (byRule.has(rule))
+            ambiguous.add(rule);
+        else
+            byRule.set(rule, claim);
+    }
+    for (const rule of ambiguous)
+        byRule.delete(rule);
+    return byRule;
+}
+/**
+ * Restore the grounding fields the host owns on each candidate step, from the
+ * last answer. A model copies the skeleton into the plan, and it drops the
+ * template field at times, or it miscopies the 64-character digest or the
+ * hash of a claim id, while it keeps the claims and the settings.
+ *
+ * On a step that copies a skeleton step, by step id, the host stamps the
+ * snapshot digest of the answer and restores a dropped template: the digest
+ * is what pins the step to the snapshot, and the template is what the host
+ * binds the contract to. A step whose snapshot is `none` states that it does
+ * not use the answer, and it stays as it is. A step whose status is
+ * `ungrounded` states a departure from the answer: the digest is stamped,
+ * and no template is restored, because the template realizes the method the
+ * step left.
+ *
+ * On every step, a claim id the answer did not return is repaired when the
+ * answer holds one claim of the same rule: one snapshot holds one version of
+ * a rule, thus the rule names the claim. A claim of a rule the answer does
+ * not hold is an issue that rejects the plan, so the model cites a claim of
+ * the answer or removes it.
+ *
+ * A step the skeleton does not hold, for example a robustness step the model
+ * adds under its own id, gets the digest stamped too when one of its claims
+ * is a claim of the answer: the claim vouches that the step consulted the
+ * answer, and the digest it typed is as prone to a miscopy as any other. A
+ * step with no claim of the answer stays as the model wrote it, because
+ * nothing of the answer vouches for it. Returns the stamped steps, the
+ * restored steps, the repaired claims, and the issues beside the new
+ * candidate. A candidate that is not a plan-shaped object, or a plan with no
+ * answer, comes back as it is.
+ */
+function restoreSkeletonGrounding(candidate, memory) {
+    const decoded = decodeObjectString(candidate);
+    if (memory.steps.size === 0 || typeof decoded !== "object" || decoded === null || !Array.isArray(decoded.steps)) {
+        return { candidate: decoded, stamped: [], restored: [], repaired: [], unknown: [] };
+    }
+    const byRule = claimsByRule(memory.claims);
+    const stamped = [];
+    const restored = [];
+    const repaired = [];
+    const unknown = [];
+    const steps = decoded.steps.map((step, index) => {
+        if (typeof step !== "object" || step === null)
+            return step;
+        const { id, grounding } = step;
+        if (typeof grounding !== "object" || grounding === null)
+            return step;
+        const current = grounding;
+        const label = typeof id === "string" ? id : String(index);
+        let next = current;
+        const source = typeof id === "string" ? memory.steps.get(id) : undefined;
+        if (source !== undefined && current.snapshot !== "none") {
+            if (next.snapshot !== source.grounding.snapshot) {
+                stamped.push(label);
+                next = { ...next, snapshot: source.grounding.snapshot };
+            }
+            if (next.template === undefined && source.grounding.template !== undefined && current.status !== "ungrounded") {
+                restored.push(label);
+                next = { ...next, template: source.grounding.template };
+            }
+        }
+        if (Array.isArray(current.claims)) {
+            let changed = false;
+            const claims = current.claims.map((claim, position) => {
+                if (typeof claim !== "string" || memory.claims.has(claim))
+                    return claim;
+                const match = byRule.get(ruleOf(claim));
+                if (match !== undefined) {
+                    repaired.push({ step: label, from: claim, to: match });
+                    changed = true;
+                    return match;
+                }
+                unknown.push({
+                    path: `plan.steps.${index}.grounding.claims.${position}`,
+                    code: "semantic",
+                    message: `Claim ${claim} is not a claim of the knowledge_recommend answer of this run. Cite a claim id the answer returned, or remove it.`,
+                });
+                return claim;
+            });
+            if (changed)
+                next = { ...next, claims };
+        }
+        // The repaired claims are the ones compared, thus a step whose only claim was miscopied still gets the digest.
+        const vouched = Array.isArray(next.claims) && next.claims.some((claim) => typeof claim === "string" && memory.claims.has(claim));
+        if (source === undefined && vouched && memory.digest !== undefined && current.snapshot !== "none" && next.snapshot !== memory.digest) {
+            stamped.push(label);
+            next = { ...next, snapshot: memory.digest };
+        }
+        return next === current ? step : { ...step, grounding: next };
+    });
+    return { candidate: { ...decoded, steps }, stamped, restored, repaired, unknown };
+}
 /**
  * Full validation: Zod schema + semantic checks. The plan is valid only if
  * BOTH pass.
  */
 function fullyValidate(candidate, resourcePolicy) {
-    const parsed = PlannerPlanSchema.safeParse(candidate);
+    // The permissive arg schema of the planner tools accepts a string, thus the
+    // loop-boundary repair never sees a plan that a model sent as a JSON-encoded
+    // string. A small model does this on a large nested schema. Decode it here,
+    // the same as run-synthesis does, so the schema issues describe the plan
+    // inside the string and not the string.
+    const decoded = decodeObjectString(candidate);
+    const parsed = PlannerPlanSchema.safeParse(decoded);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, candidate) };
+        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, decoded) };
     }
     // Semantic checks operate on the AnalysisPlan shape — PlannerPlan omits
     // maxSteps, so inject the execution-time default to satisfy the validator.
@@ -336,7 +483,7 @@ function fullyValidate(candidate, resourcePolicy) {
  * shared `holder` so the outer `execute` reads the terminal outcome after the
  * loop finishes.
  */
-function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger) {
+function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger, memory) {
     const submitPlanTool = defineTool({
         id: "submit_plan",
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
@@ -375,10 +522,20 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
                 });
             }
             const attempt = ++trace.submitAttempts;
-            const result = fullyValidate(input.plan, resourcePolicy);
-            if (!result.valid) {
+            const { candidate, stamped, restored, repaired, unknown } = restoreSkeletonGrounding(input.plan, memory);
+            if (stamped.length > 0)
+                logger.info("submit_plan stamped the snapshot digest of the answer on steps", { steps: stamped });
+            if (restored.length > 0)
+                logger.info("submit_plan restored the template of skeleton steps", { steps: restored });
+            if (repaired.length > 0)
+                logger.info("submit_plan repaired the claim ids of plan steps", { claims: repaired });
+            const result = fullyValidate(candidate, resourcePolicy);
+            // An unknown claim rejects a plan that the schema accepts, beside the
+            // schema issues when the schema rejects it, thus one attempt shows both.
+            if (!result.valid || unknown.length > 0) {
+                const issues = [...(result.valid ? [] : result.issues), ...unknown];
                 trace.rejectedAttempts++;
-                const rejection = toRejectionRecord(attempt, result.issues);
+                const rejection = toRejectionRecord(attempt, issues);
                 if (trace.rejections.length < MAX_LOGGED_REJECTIONS)
                     trace.rejections.push(rejection);
                 // `warn`, not `debug`: a rejection is non-terminal by design, so the model
@@ -386,7 +543,7 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
                 // an attempt was spent. A run that exhausts its budget on rejections ends
                 // looking identical to one that never tried, and this is the difference.
                 logger.warn("submit_plan rejected a plan", { ...rejection });
-                return ok({ accepted: false, issues: result.issues });
+                return ok({ accepted: false, issues });
             }
             const persisted = await persistPlan(result.plan, persistCtx, pool, logger);
             if (!persisted.ok) {
@@ -431,6 +588,11 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
         }),
         describeCall: "none",
         execute: async (input) => {
+            const degenerate = degenerateTerminalText(input.question);
+            if (degenerate) {
+                logger.warn("request_clarification refused a placeholder question", { question: input.question.slice(0, 80) });
+                return err({ error: `${degenerate} Ask the real question, or continue: submit the plan you have.`, retryable: true });
+            }
             if (holder.outcome !== null) {
                 trace.duplicateTerminalCalls++;
                 logger.warn("request_clarification called after a terminal outcome was recorded", {
@@ -657,7 +819,7 @@ const OUTCOME_LEVEL = {
  * A tool here never writes and never computes. Thus the worst outcome of a
  * needless call is latency, and the prompt is what bounds that.
  */
-function buildPlannerSearchTools(deps) {
+export function buildPlannerSearchTools(deps, hooks = {}) {
     const bioKeys = deps.bioKeys;
     const ncbi = createNcbiTools(bioKeys);
     return [
@@ -687,6 +849,15 @@ function buildPlannerSearchTools(deps) {
             ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
             ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
         }),
+        // The knowledge plane: one cited procedure per situation, and one check
+        // of the draft. Both attach only when the embedder binds a client.
+        ...createKnowledgeTools({
+            ...(deps.knowledge === undefined ? {} : { client: deps.knowledge }),
+            ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+            ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+            ...(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath }),
+            ...(hooks.onRecommend === undefined ? {} : { onRecommend: hooks.onRecommend }),
+        }),
     ];
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
@@ -872,12 +1043,28 @@ export function createGeneratePlanTool(deps) {
                 analysisId,
                 parentPlanId: input.parentPlanId ?? null,
             };
-            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger);
+            // The last recommend answer of this invocation, thus `submit_plan`
+            // stamps the snapshot digest, restores a template the model dropped,
+            // and repairs or refuses a claim id the answer did not return.
+            const memory = { steps: new Map(), claims: new Set() };
+            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger, memory);
             // Built here rather than at construction: a `describeCall` hook reads no
             // dep, thus the tool must stay constructible from an empty bag. The tool
             // definitions are identical across invocations, thus the request prefix
             // that the cache keys on does not move.
-            const searchTools = buildPlannerSearchTools(deps);
+            // The guard bounds the repeated calls of one plan: the third call with
+            // an input the plan already sent, or the call past the budget of one
+            // tool, answers a refusal that says to continue. The terminal tools
+            // stay outside it, because a refused submit would strand the plan.
+            let refusals = 0;
+            const searchTools = guardRepeatedCalls(buildPlannerSearchTools(deps, {
+                onRecommend: (answer) => rememberAnswer(memory, answer),
+            }), {
+                onRefusal: (refusal) => {
+                    refusals += 1;
+                    logger.warn("planner call refused by the guard", { ...refusal, refusals });
+                },
+            });
             const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
             const planner = {
                 id: PLANNER_AGENT_ID,
@@ -901,6 +1088,10 @@ export function createGeneratePlanTool(deps) {
                     emit: ctx.emit,
                     runStep: passthroughStep,
                     resolved: () => holder.outcome !== null,
+                    // A planner the guard refused too many times is looping:
+                    // the early cap ends the search, and the salvage turn
+                    // submits the plan it has.
+                    stopWhen: () => refusals >= PLANNER_REFUSAL_LIMIT,
                     // No forced tool choice: some Claude models reject it with a
                     // 400. The prompt names the terminal tools, and the salvage
                     // turn below recovers a run that ends on prose.

package/dist/tools/research/guarded-address.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function isGuardedAddress(ip: string): boolean;

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/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));
+        },
+    };
+}