@pentoshi/clai 4.11.5 → 4.11.8

package/dist/tools/web/ssrf-guard.js

@@ -6,11 +6,6 @@
  * `http.fetch` check (via {@link isBlockedAddress}) all delegate here.
  */
 import net from "node:net";
-/**
- * `true` iff `url` parses as an absolute URL with scheme `http:`/`https:`.
- * Single source of truth for the scheme allow-list so the safety classifier
- * and the fetch-core argument validator stay in sync.
- */
 export function isAllowedScheme(url) {
     if (typeof url !== "string" || url.length === 0)
         return false;
@@ -23,27 +18,13 @@ export function isAllowedScheme(url) {
     }
     return parsed.protocol === "http:" || parsed.protocol === "https:";
 }
-/**
- * Hostname literals that are known to refer to the local host without any
- * DNS lookup. Lower-cased for case-insensitive comparison.
- */
 const LOOPBACK_HOSTNAMES = new Set([
     "localhost",
     "localhost.localdomain",
     "ip6-localhost",
     "ip6-loopback",
 ]);
-/** IPv4 cloud-metadata address (AWS EC2, GCP, Azure all share this). */
 const IPV4_CLOUD_METADATA = "169.254.169.254";
-/**
- * Classify a literal IP address (IPv4 or IPv6).
- *
- * Returns `{ class }` when the address falls into one of the
- * {@link AddressClass} buckets, or `null` when the input is a
- * globally-routable address (or fails to parse as either family).
- *
- * The check is fully synchronous and never performs DNS.
- */
 export function classify(ip) {
     if (typeof ip !== "string" || ip.length === 0)
         return null;
@@ -53,21 +34,9 @@ export function classify(ip) {
         return classifyIpv6(ip);
     return null;
 }
-/**
- * Classify a hostname or IP literal without performing DNS resolution.
- *
- * - For literal IPv4/IPv6 addresses (with or without surrounding `[…]`
- *   brackets), this delegates to {@link classify}.
- * - For known-bad hostname literals (`localhost`, `localhost.localdomain`,
- *   `ip6-localhost`, `ip6-loopback`), this returns `{ class: "loopback" }`.
- * - For every other hostname, this returns `null` (the caller is
- *   responsible for the DNS-resolved second pass; see
- *   `src/tools/web/fetch-core.ts`).
- */
 export function classifyHost(hostname) {
     if (typeof hostname !== "string" || hostname.length === 0)
         return null;
-    // Strip IPv6 brackets if the caller passed `[::1]` style.
     const stripped = hostname.replace(/^\[|\]$/g, "");
     const lower = stripped.toLowerCase();
     if (LOOPBACK_HOSTNAMES.has(lower))
@@ -86,10 +55,6 @@ export function classifyHost(hostname) {
 export function isBlockedAddress(host) {
     if (classifyHost(host) !== null)
         return true;
-    // Preserve legacy semantics: `0.0.0.0/8` was blocked by the previous
-    // implementation in `src/tools/http.ts`. It is not exposed via the
-    // public `classify` enum because it is rarely useful as a fetch target
-    // and is not called out by Requirement 5.3, but we keep blocking it.
     const stripped = host.replace(/^\[|\]$/g, "");
     if (net.isIPv4(stripped)) {
         const first = Number(stripped.split(".")[0]);
@@ -99,7 +64,6 @@ export function isBlockedAddress(host) {
     if (net.isIPv6(stripped)) {
         const hextets = ipv6Hextets(stripped);
         if (hextets) {
-            // ::ffff:<v4> with embedded `0.x.x.x` legacy block.
             if (hextets[0] === 0 &&
                 hextets[1] === 0 &&
                 hextets[2] === 0 &&
@@ -114,17 +78,12 @@ export function isBlockedAddress(host) {
     }
     return false;
 }
-// ---------------------------------------------------------------------------
-// Internals
-// ---------------------------------------------------------------------------
 function classifyIpv4(ip) {
     const parts = ip.split(".").map((p) => Number(p));
     if (parts.length !== 4 ||
         parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) {
         return null;
     }
-    // Cloud-metadata literal must win over the broader 169.254.0.0/16
-    // link-local range so the class returned is the most specific one.
     if (ip === IPV4_CLOUD_METADATA)
         return { class: "cloud-metadata" };
     const [a, b] = parts;
@@ -146,7 +105,6 @@ function classifyIpv6(ip) {
     const hextets = ipv6Hextets(ip);
     if (!hextets)
         return null;
-    // ::1 (loopback): all-zero except last hextet === 1.
     if (hextets[0] === 0 &&
         hextets[1] === 0 &&
         hextets[2] === 0 &&
@@ -157,8 +115,6 @@ function classifyIpv6(ip) {
         hextets[7] === 1) {
         return { class: "loopback" };
     }
-    // IPv4-mapped IPv6 (::ffff:0:0/96): recurse on the embedded v4 address
-    // so the embedded address gets the most specific class.
     if (hextets[0] === 0 &&
         hextets[1] === 0 &&
         hextets[2] === 0 &&
@@ -171,8 +127,6 @@ function classifyIpv6(ip) {
         const d = hextets[7] & 0xff;
         return classifyIpv4(`${a}.${b}.${c}.${d}`);
     }
-    // IPv6 cloud-metadata literal `fd00:ec2::254` must be checked before the
-    // generic ULA match, otherwise it would be classified as rfc1918.
     if (hextets[0] === 0xfd00 &&
         hextets[1] === 0x0ec2 &&
         hextets[2] === 0 &&
@@ -183,29 +137,18 @@ function classifyIpv6(ip) {
         hextets[7] === 0x0254) {
         return { class: "cloud-metadata" };
     }
-    // fe80::/10 (IPv6 link-local): top 10 bits == 1111 1110 10.
     if ((hextets[0] & 0xffc0) === 0xfe80) {
         return { class: "ipv6-link-local" };
     }
-    // fc00::/7 (Unique Local Addresses, the IPv6 cousin of RFC1918).
     if ((hextets[0] & 0xfe00) === 0xfc00) {
         return { class: "rfc1918" };
     }
     return null;
 }
-/**
- * Expand an IPv6 address (string form) into its 8 hextets as integers.
- *
- * Supports `::` compression and the IPv4-in-last-32-bits form
- * (e.g. `::ffff:127.0.0.1`). Returns `null` if the input does not parse
- * as a valid IPv6 address.
- */
 function ipv6Hextets(addr) {
     if (!net.isIPv6(addr))
         return null;
     let normalized = addr.toLowerCase();
-    // Translate any embedded IPv4 dotted-quad in the last 32 bits into two
-    // hextets so the rest of the parser can deal with a uniform format.
     const v4Match = normalized.match(/^(.*:)([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3})$/);
     if (v4Match) {
         const prefix = v4Match[1];

package/dist/tools/web/ssrf-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"ssrf-guard.js","sourceRoot":"","sources":["../../../src/tools/web/ssrf-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ssrf-guard.js","sourceRoot":"","sources":["../../../src/tools/web/ssrf-guard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,GAAG,MAAM,UAAU,CAAC;AAc3B,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACrE,CAAC;AAED,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IACtD,WAAW;IACX,uBAAuB;IACvB,eAAe;IACf,cAAc;CACf,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAE9C,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,YAAY,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,YAAY,CAAC,EAAE,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAChE,OAAO,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,OAAO,EAAE,CAAC;YACZ,IACE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;gBAChB,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,EACrB,CAAC;gBACD,MAAM,kBAAkB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;gBACrD,IAAI,kBAAkB,KAAK,CAAC;oBAAE,OAAO,IAAI,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAGD,SAAS,YAAY,CAAC,EAAU;IAC9B,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,IACE,KAAK,CAAC,MAAM,KAAK,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,EAC3D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,EAAE,KAAK,mBAAmB;QAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IACnE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAyC,CAAC;IACzD,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACjE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAChE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG;QAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAChE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,EAAU;IAC9B,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,IACE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAChB,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC/B,CAAC;IAED,IACE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,EACrB,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACpC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC;QAC7B,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACpC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC;QAC7B,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,IACE,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM;QACrB,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM;QACrB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;QAChB,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,EACrB,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC9B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAC9B,yDAAyD,CAC1D,CAAC;IACF,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,IACE,OAAO,CAAC,MAAM,KAAK,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,EAC7D,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC7D,UAAU,GAAG,GAAG,MAAM,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,MAAM,IAAI,GACR,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;IAE1C,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9C,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,cAAc,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/C,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,KAAK,CAAS,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC1C,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/tools/web/types.d.ts

@@ -1,130 +1,43 @@
-/**
- * Shared TypeScript types for the `web.search` and `web.fetch` tools.
- *
- * Field shapes, ranges, and defaults match the "Data Models" section of
- * `.kiro/specs/web-search-and-fetch/design.md` and the acceptance
- * criteria in Requirements 1, 2, and 7.
- */
-/**
- * Identifier of a search provider supported by the Web_Search_Tool.
- *
- * The set is intentionally independent of the LLM `ProviderId` union so the
- * two keyspaces stay decoupled.
- */
 export type SearchProviderId = "brave" | "tavily" | "duckduckgo" | "exa";
-/** Convenience tuple form of the {@link SearchProviderId} union. */
 export declare const searchProviderIds: readonly SearchProviderId[];
-/**
- * Exa `/search` retrieval strategy, ordered by increasing latency and depth.
- *
- * `instant`/`fast`/`auto` are single-shot retrieval tiers; `deep-lite`,
- * `deep`, and `deep-reasoning` are the deep-search variants that run multiple
- * query passes and rank the combined results. The value is provider-scoped
- * configuration (see `ClaiConfig.exaSearchType`) and is forwarded verbatim as
- * the `type` field on the Exa request.
- */
 export type ExaSearchType = "instant" | "fast" | "auto" | "deep-lite" | "deep" | "deep-reasoning";
-/** Convenience tuple form of {@link ExaSearchType}, low-to-high latency. */
 export declare const exaSearchTypes: readonly ExaSearchType[];
-/**
- * Default Exa search type. `deep-lite` trades a few seconds of latency for
- * markedly better relevance than the single-shot tiers, which suits the
- * research and CVE-lookup workflows Exa is selected for.
- */
 export declare const DEFAULT_EXA_SEARCH_TYPE: ExaSearchType;
-/** Short human descriptions for each {@link ExaSearchType}, shown in pickers. */
 export declare const exaSearchTypeDescriptions: Record<ExaSearchType, string>;
-/** Narrow an arbitrary string to an {@link ExaSearchType}, or `undefined`. */
 export declare function asExaSearchType(value: string): ExaSearchType | undefined;
-/**
- * Arguments accepted by the `web.search` tool.
- *
- * - `query`: 1..400 chars after trimming leading/trailing whitespace
- *   (Requirement 1.1).
- * - `maxResults`: integer in `[1, 20]`; defaults to 5 when omitted
- *   (Requirement 1.2).
- */
 export interface WebSearchArgs {
     query: string;
     maxResults?: number;
 }
-/** Default value applied when `WebSearchArgs.maxResults` is omitted. */
 export declare const DEFAULT_MAX_RESULTS = 5;
-/** Inclusive minimum allowed for `WebSearchArgs.maxResults`. */
 export declare const MIN_MAX_RESULTS = 1;
-/** Inclusive maximum allowed for `WebSearchArgs.maxResults`. */
 export declare const MAX_MAX_RESULTS = 20;
-/** Inclusive minimum allowed for `WebSearchArgs.query` length after trim. */
 export declare const MIN_QUERY_LENGTH = 1;
-/** Inclusive maximum allowed for `WebSearchArgs.query` length after trim. */
 export declare const MAX_QUERY_LENGTH = 400;
-/**
- * A single search hit returned by `web.search`.
- *
- * - `title`: 1..512 chars (Requirement 1.3).
- * - `url`: absolute URL with scheme `http://` or `https://`, no whitespace,
- *   no ASCII control characters (Requirements 1.3, 7.1, 7.3).
- * - `snippet`: 0..2048 chars (Requirement 1.3).
- */
 export interface SearchResult {
     title: string;
     url: string;
     snippet: string;
 }
-/** Inclusive minimum allowed for `SearchResult.title` length. */
 export declare const MIN_TITLE_LENGTH = 1;
-/** Inclusive maximum allowed for `SearchResult.title` length. */
 export declare const MAX_TITLE_LENGTH = 512;
-/** Inclusive minimum allowed for `SearchResult.snippet` length. */
 export declare const MIN_SNIPPET_LENGTH = 0;
-/** Inclusive maximum allowed for `SearchResult.snippet` length. */
 export declare const MAX_SNIPPET_LENGTH = 2048;
-/**
- * Categorical kinds of failures the `web.search` pipeline can surface.
- *
- * The mapping to acceptance criteria is:
- * - `auth`        → Requirement 6.1 (401/403)
- * - `rate-limit`  → Requirement 6.2 (429)
- * - `network`     → Requirement 6.3 (DNS/connect/TLS)
- * - `parse`       → Requirement 6.5 (bad provider response)
- * - `server`      → Requirement 6.6 (5xx)
- * - `http`        → Requirement 1.9 (other non-2xx)
- * - `timeout`     → Requirement 1.8 (>15 s elapsed)
- * - `missing-key` → Requirement 3.4
- * - `validation`  → Requirements 1.5, 1.6
- */
 export type WebSearchErrorKind = "auth" | "rate-limit" | "network" | "parse" | "server" | "http" | "timeout" | "missing-key" | "validation";
-/** Structured failure detail accompanying an `ok=false` search outcome. */
 export interface WebSearchError {
     kind: WebSearchErrorKind;
     provider: SearchProviderId;
     status?: number;
     message: string;
 }
-/**
- * Internal typed result of a `web.search` invocation, prior to being
- * adapted into a `ToolResult` by the registry handler.
- */
 export interface WebSearchOutcome {
     ok: boolean;
     provider: SearchProviderId;
-    /** At most `maxResults` entries; may be empty (Requirement 1.7). */
     results: SearchResult[];
     error?: WebSearchError;
 }
-/**
- * Mode controlling how the `web.fetch` tool emits the response body.
- *
- * - `readable`: HTML/XHTML stripped to text; non-HTML text passed through
- *   (Requirements 2.4, 2.5, 2.28).
- * - `raw`: response bytes decoded using the declared Content-Type charset,
- *   an HTML meta charset fallback, or UTF-8 with replacement; truncated to
- *   `maxBytes` (Requirement 2.29).
- */
 export type ResponseMode = "readable" | "raw";
-/** Which portion of the rendered response should be returned. */
 export type ResponsePart = "full" | "headers" | "body";
-/** Allowed values for `WebFetchArgs.responseMode`. */
 export declare const RESPONSE_MODES: readonly ResponseMode[];
 /**
  * Arguments accepted by the `web.fetch` tool.
@@ -141,7 +54,6 @@ export declare const RESPONSE_MODES: readonly ResponseMode[];
 export interface WebFetchArgs {
     url: string;
     maxBytes?: number;
-    /** Wall-clock timeout in milliseconds. Defaults to 40 seconds. */
     timeoutMs?: number;
     includeHeaders?: boolean;
     includeTls?: boolean;
@@ -154,103 +66,44 @@ export interface WebFetchArgs {
     maxOutputBytes?: number;
     redactSensitive?: boolean;
 }
-/** Default value applied when `WebFetchArgs.maxBytes` is omitted. */
 export declare const DEFAULT_MAX_BYTES = 262144;
-/** Inclusive minimum allowed for `WebFetchArgs.maxBytes`. */
 export declare const MIN_MAX_BYTES = 1024;
-/** Inclusive maximum allowed for `WebFetchArgs.maxBytes`. */
 export declare const MAX_MAX_BYTES = 1048576;
-/** Default value applied when `WebFetchArgs.includeHeaders` is omitted. */
 export declare const DEFAULT_INCLUDE_HEADERS = false;
-/** Default value applied when `WebFetchArgs.includeTiming` is omitted. */
 export declare const DEFAULT_INCLUDE_TIMING = false;
-/** Default value applied when `WebFetchArgs.includeRedirectChain` is omitted. */
 export declare const DEFAULT_INCLUDE_REDIRECT_CHAIN = false;
-/** Default value applied when `WebFetchArgs.responseMode` is omitted. */
 export declare const DEFAULT_RESPONSE_MODE: ResponseMode;
 /** Default value applied when `WebFetchArgs.redactSensitive` is omitted. */
 export declare const DEFAULT_REDACT_SENSITIVE = true;
-/** Maximum number of redirect hops followed per `web.fetch` invocation. */
 export declare const MAX_REDIRECT_HOPS = 5;
-/** Maximum number of `Set-Cookie` entries captured per invocation. */
 export declare const MAX_COOKIES_CAPTURED = 32;
-/** Per-header-value character cap before `[...truncated]` is appended. */
 export declare const MAX_HEADER_VALUE_LENGTH = 4096;
-/** Marker appended to any header value or body preview shortened by the tool. */
 export declare const TRUNCATION_MARKER = "[...truncated]";
 /** Literal placeholder used wherever sensitive values are redacted. */
 export declare const REDACTED_PLACEHOLDER = "[REDACTED]";
-/** Combined serialized-size cap for fetch metadata in bytes. */
 export declare const METADATA_BUDGET_BYTES = 65536;
-/** Maximum size in bytes of the `bodyPreview` returned for HTTP errors. */
 export declare const HTTP_ERROR_BODY_PREVIEW_BYTES = 4096;
-/** Total wall-clock timeout in milliseconds for a `web.fetch` invocation. */
 export declare const FETCH_TIMEOUT_MS = 40000;
 export declare const MIN_FETCH_TIMEOUT_MS = 1000;
 export declare const MAX_FETCH_TIMEOUT_MS = 1800000;
-/** Total wall-clock timeout in milliseconds for a `web.search` invocation. */
 export declare const SEARCH_TIMEOUT_MS = 40000;
-/**
- * Lower-cased map of HTTP response header names to string values.
- *
- * Each value is truncated to {@link MAX_HEADER_VALUE_LENGTH} characters with
- * the literal {@link TRUNCATION_MARKER} appended when shortened. Repeat
- * headers per RFC 7230 are joined with `", "`. (Requirement 2.21.)
- */
 export type HeaderMap = Record<string, string>;
-/**
- * TLS session details captured from the final hop of an `https://` fetch.
- *
- * Populated only when the request used `https://` and the user did not opt
- * out via `includeTls=false` (Requirements 2.23, 2.24).
- */
 export interface TlsInfo {
-    /** Negotiated protocol version, e.g. `"TLSv1.3"`. */
     protocol: string;
-    /** Cipher suite name, e.g. `"TLS_AES_128_GCM_SHA256"`. */
     cipher: string;
-    /** Subject Common Name from the leaf certificate. */
     subjectCN: string;
-    /** Issuer Common Name from the leaf certificate. */
     issuerCN: string;
-    /** Subject Alternative Names parsed from the leaf certificate. */
     subjectAltNames: string[];
-    /** ISO 8601 timestamp from the leaf certificate's `notBefore` field. */
     notBefore: string;
-    /** ISO 8601 timestamp from the leaf certificate's `notAfter` field. */
     notAfter: string;
-    /**
-     * Lowercase, colon-separated SHA-256 fingerprint of the leaf certificate's
-     * DER bytes (e.g. `"ab:cd:..."`).
-     */
     fingerprintSha256: string;
 }
-/**
- * One hop in the {@link RedirectChain}.
- *
- * - `url`: the URL that was requested at this hop.
- * - `status`: integer HTTP status returned by that request.
- * - `location`: value of the `Location` header on the redirect response, if
- *   the response was a redirect that produced a subsequent hop.
- */
 export interface RedirectHop {
     url: string;
     status: number;
     location?: string;
 }
-/**
- * Ordered list of redirect hops, capped at {@link MAX_REDIRECT_HOPS}.
- *
- * The first entry is the originally requested URL; the last entry is the URL
- * whose response body is returned to the caller. (Requirement 2.26.)
- */
 export type RedirectChain = RedirectHop[];
-/**
- * Per-phase millisecond timing measurements captured during a fetch.
- *
- * `tlsMs` is present iff the requested URL used `https://`
- * (Requirement 2.25).
- */
 export interface TimingInfo {
     dnsMs: number;
     tcpMs: number;
@@ -258,7 +111,6 @@ export interface TimingInfo {
     ttfbMs: number;
     totalMs: number;
 }
-/** Allowed values for {@link CookieInfo.sameSite}. */
 export type CookieSameSite = "Strict" | "Lax" | "None";
 /**
  * Public-attribute view of a cookie observed in a `Set-Cookie` header during
@@ -271,90 +123,41 @@ export interface CookieInfo {
     value: string;
     domain?: string;
     path?: string;
-    /** ISO 8601 timestamp from the `Expires` attribute, when present. */
     expires?: string;
-    /** Numeric `Max-Age` attribute in seconds, when present. */
     maxAge?: number;
     httpOnly?: boolean;
     secure?: boolean;
     sameSite?: CookieSameSite;
 }
-/**
- * Structured metadata describing a completed `web.fetch` invocation.
- *
- * The `headers`, `tls`, `timing`, `redirectChain`, and `cookies` fields are
- * jointly capped at {@link METADATA_BUDGET_BYTES} when serialized
- * (Requirement 2.35), with the truncation order defined in
- * `design.md` "Truncation order at the 64 KiB cap".
- */
 export interface WebFetchMetadata {
-    /** URL exactly as requested by the caller. */
     requestedUrl: string;
-    /** URL that returned the body (after any redirects). */
     finalUrl: string;
-    /** Integer HTTP status code of the final response. */
     status: number;
-    /** Final response `Content-Type`, when the server returned one. */
     contentType?: string;
-    /** IP address contacted on the final hop (Requirement 2.27). */
     resolvedIp: string;
-    /** Hostname of `finalUrl` (Requirement 2.27). */
     finalHostname: string;
-    /** Effective response mode used to build `body`. */
     mode: ResponseMode;
-    /** Number of body bytes the tool actually received. */
     bytesReceived: number;
-    /** True iff `bytesReceived` reached `maxBytes` and the body was cut. */
     truncated: boolean;
-    /** Byte offset at which truncation occurred, when `truncated=true`. */
     truncatedAt?: number;
     headers?: HeaderMap;
     tls?: TlsInfo;
     timing?: TimingInfo;
     redirectChain?: RedirectChain;
-    /** At most {@link MAX_COOKIES_CAPTURED} entries (Requirement 2.31). */
     cookies?: CookieInfo[];
-    /** Bookkeeping for the 64 KiB metadata cap. */
     budget: {
         metadataBytes: number;
         cap: typeof METADATA_BUDGET_BYTES;
     };
 }
-/**
- * Categorical kinds of failures the `web.fetch` pipeline can surface.
- *
- * The mapping to acceptance criteria is:
- * - `validation`      → Requirements 2.12, 2.13, 2.33, 2.34
- * - `blocked-scheme`  → Requirements 2.1 / 5.4
- * - `blocked-address` → Requirements 2.8 / 5.3
- * - `binary-content`  → Requirements 2.9, 2.30
- * - `redirect-limit`  → Requirement 2.14
- * - `timeout`         → Requirement 2.10
- * - `http-error`      → Requirement 6.4 (4xx/5xx terminal)
- * - `network`         → Requirement 6.3 (DNS/connect/TLS underlying failure)
- * - `decode`          → raw decode failed (rare)
- */
 export type WebFetchErrorKind = "validation" | "blocked-scheme" | "blocked-address" | "binary-content" | "redirect-limit" | "timeout" | "http-error" | "network" | "decode";
-/** Structured failure detail accompanying an `ok=false` fetch outcome. */
 export interface WebFetchError {
     kind: WebFetchErrorKind;
     message: string;
     status?: number;
-    /** Last URL attempted before the failure surfaced. */
     url?: string;
-    /**
-     * Up to {@link HTTP_ERROR_BODY_PREVIEW_BYTES} bytes of the failing
-     * response body, included for `http-error` outcomes (Requirement 6.4).
-     */
     bodyPreview?: string;
 }
-/**
- * Internal typed result of a `web.fetch` invocation, prior to being adapted
- * into a `ToolResult` by the registry handler.
- *
- * `body` carries either readable text or raw decoded UTF-8, depending on the
- * resolved {@link ResponseMode}.
- */
 export interface WebFetchOutcome {
     ok: boolean;
     metadata: WebFetchMetadata;

package/dist/tools/web/types.js

@@ -1,18 +1,9 @@
-/**
- * Shared TypeScript types for the `web.search` and `web.fetch` tools.
- *
- * Field shapes, ranges, and defaults match the "Data Models" section of
- * `.kiro/specs/web-search-and-fetch/design.md` and the acceptance
- * criteria in Requirements 1, 2, and 7.
- */
-/** Convenience tuple form of the {@link SearchProviderId} union. */
 export const searchProviderIds = [
     "brave",
     "tavily",
     "duckduckgo",
     "exa",
 ];
-/** Convenience tuple form of {@link ExaSearchType}, low-to-high latency. */
 export const exaSearchTypes = [
     "instant",
     "fast",
@@ -21,13 +12,7 @@ export const exaSearchTypes = [
     "deep",
     "deep-reasoning",
 ];
-/**
- * Default Exa search type. `deep-lite` trades a few seconds of latency for
- * markedly better relevance than the single-shot tiers, which suits the
- * research and CVE-lookup workflows Exa is selected for.
- */
 export const DEFAULT_EXA_SEARCH_TYPE = "deep-lite";
-/** Short human descriptions for each {@link ExaSearchType}, shown in pickers. */
 export const exaSearchTypeDescriptions = {
     instant: "~250 ms · quick lookups, autocomplete",
     fast: "~450 ms · low latency, good relevance",
@@ -36,70 +21,44 @@ export const exaSearchTypeDescriptions = {
     deep: "4-15 s · thorough research and enrichment",
     "deep-reasoning": "12-40 s · hardest multi-step synthesis",
 };
-/** Narrow an arbitrary string to an {@link ExaSearchType}, or `undefined`. */
 export function asExaSearchType(value) {
     const normalized = value.trim().toLowerCase();
     return exaSearchTypes.includes(normalized)
         ? normalized
         : undefined;
 }
-/** Default value applied when `WebSearchArgs.maxResults` is omitted. */
 export const DEFAULT_MAX_RESULTS = 5;
-/** Inclusive minimum allowed for `WebSearchArgs.maxResults`. */
 export const MIN_MAX_RESULTS = 1;
-/** Inclusive maximum allowed for `WebSearchArgs.maxResults`. */
 export const MAX_MAX_RESULTS = 20;
-/** Inclusive minimum allowed for `WebSearchArgs.query` length after trim. */
 export const MIN_QUERY_LENGTH = 1;
-/** Inclusive maximum allowed for `WebSearchArgs.query` length after trim. */
 export const MAX_QUERY_LENGTH = 400;
-/** Inclusive minimum allowed for `SearchResult.title` length. */
 export const MIN_TITLE_LENGTH = 1;
-/** Inclusive maximum allowed for `SearchResult.title` length. */
 export const MAX_TITLE_LENGTH = 512;
-/** Inclusive minimum allowed for `SearchResult.snippet` length. */
 export const MIN_SNIPPET_LENGTH = 0;
-/** Inclusive maximum allowed for `SearchResult.snippet` length. */
 export const MAX_SNIPPET_LENGTH = 2048;
-/** Allowed values for `WebFetchArgs.responseMode`. */
 export const RESPONSE_MODES = [
     "readable",
     "raw",
 ];
-/** Default value applied when `WebFetchArgs.maxBytes` is omitted. */
 export const DEFAULT_MAX_BYTES = 262_144;
-/** Inclusive minimum allowed for `WebFetchArgs.maxBytes`. */
 export const MIN_MAX_BYTES = 1024;
-/** Inclusive maximum allowed for `WebFetchArgs.maxBytes`. */
 export const MAX_MAX_BYTES = 1_048_576;
-/** Default value applied when `WebFetchArgs.includeHeaders` is omitted. */
 export const DEFAULT_INCLUDE_HEADERS = false;
-/** Default value applied when `WebFetchArgs.includeTiming` is omitted. */
 export const DEFAULT_INCLUDE_TIMING = false;
-/** Default value applied when `WebFetchArgs.includeRedirectChain` is omitted. */
 export const DEFAULT_INCLUDE_REDIRECT_CHAIN = false;
-/** Default value applied when `WebFetchArgs.responseMode` is omitted. */
 export const DEFAULT_RESPONSE_MODE = "readable";
 /** Default value applied when `WebFetchArgs.redactSensitive` is omitted. */
 export const DEFAULT_REDACT_SENSITIVE = true;
-/** Maximum number of redirect hops followed per `web.fetch` invocation. */
 export const MAX_REDIRECT_HOPS = 5;
-/** Maximum number of `Set-Cookie` entries captured per invocation. */
 export const MAX_COOKIES_CAPTURED = 32;
-/** Per-header-value character cap before `[...truncated]` is appended. */
 export const MAX_HEADER_VALUE_LENGTH = 4096;
-/** Marker appended to any header value or body preview shortened by the tool. */
 export const TRUNCATION_MARKER = "[...truncated]";
 /** Literal placeholder used wherever sensitive values are redacted. */
 export const REDACTED_PLACEHOLDER = "[REDACTED]";
-/** Combined serialized-size cap for fetch metadata in bytes. */
 export const METADATA_BUDGET_BYTES = 65_536;
-/** Maximum size in bytes of the `bodyPreview` returned for HTTP errors. */
 export const HTTP_ERROR_BODY_PREVIEW_BYTES = 4096;
-/** Total wall-clock timeout in milliseconds for a `web.fetch` invocation. */
 export const FETCH_TIMEOUT_MS = 40_000;
 export const MIN_FETCH_TIMEOUT_MS = 1_000;
 export const MAX_FETCH_TIMEOUT_MS = 1_800_000;
-/** Total wall-clock timeout in milliseconds for a `web.search` invocation. */
 export const SEARCH_TIMEOUT_MS = 40_000;
 //# sourceMappingURL=types.js.map

package/dist/tools/web/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tools/web/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/tools/web/types.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,iBAAiB,GAAgC;IAC5D,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,KAAK;CACG,CAAC;AAUX,MAAM,CAAC,MAAM,cAAc,GAA6B;IACtD,SAAS;IACT,MAAM;IACN,MAAM;IACN,WAAW;IACX,MAAM;IACN,gBAAgB;CACR,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAkB,WAAW,CAAC;AAElE,MAAM,CAAC,MAAM,yBAAyB,GAAkC;IACtE,OAAO,EAAE,uCAAuC;IAChD,IAAI,EAAE,uCAAuC;IAC7C,IAAI,EAAE,qCAAqC;IAC3C,WAAW,EAAE,yCAAyC;IACtD,IAAI,EAAE,2CAA2C;IACjD,gBAAgB,EAAE,wCAAwC;CAC3D,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAQ,cAAoC,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC/D,CAAC,CAAE,UAA4B;QAC/B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAOD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAElC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAQpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAgCvC,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD,UAAU;IACV,KAAK;CACG,CAAC;AA8BX,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAEzC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC;AAElC,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AAEvC,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAE7C,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAE5C,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,CAAC;AAEpD,MAAM,CAAC,MAAM,qBAAqB,GAAiB,UAAU,CAAC;AAE9D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AAElD,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC;AAElD,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AACvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC"}

package/dist/tools/web/validate-args.d.ts

@@ -0,0 +1,11 @@
+import { NormalisedArgs } from "./request-loop.js";
+import type { WebFetchArgs, WebFetchError } from "./types.js";
+type ValidationResult = {
+    ok: true;
+    value: NormalisedArgs;
+} | {
+    ok: false;
+    error: WebFetchError;
+};
+export declare function validateArgs(args: WebFetchArgs): ValidationResult;
+export {};