@pentoshi/clai 0.10.5 → 0.11.0

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

@@ -0,0 +1,265 @@
+/**
+ * SSRF guard — classifies an address (or a hostname literal) as belonging
+ * to a private/loopback/link-local/cloud-metadata/CGNAT range.
+ *
+ * The structured {@link classify} / {@link classifyHost} helpers are used
+ * by the `web.fetch` pipeline (synchronous classifier branch + per-hop
+ * resolution check) and by the safety classifier in
+ * `src/safety/classifier.ts`.
+ *
+ * The boolean {@link isBlockedAddress} re-export preserves the legacy shape
+ * used by `src/tools/http.ts` so existing `http.fetch` semantics are
+ * unchanged.
+ *
+ * Per the design (see `.kiro/specs/web-search-and-fetch/design.md`,
+ * "Sequencing of changes" step 2 and "Safety classifier integration"), this
+ * module is the single source of truth for address classification — both
+ * the legacy `http.fetch` SSRF check and the new `web.fetch` checks
+ * delegate here.
+ */
+import net from "node:net";
+/**
+ * Return `true` iff `url` parses as an absolute URL whose scheme is exactly
+ * `http:` or `https:`. Returns `false` for any other scheme (including
+ * `ftp:`, `file:`, `data:`, `javascript:`, `gopher:`), for empty strings,
+ * for malformed inputs that fail `new URL()` parsing, and for non-string
+ * inputs.
+ *
+ * This is the synchronous half of the "scheme allowlist" check enforced
+ * by the `web.fetch` pipeline (see Requirement 5.4 / 2.1). It is the
+ * single source of truth for the scheme allow-list so the safety
+ * classifier branch and the fetch-core argument validator stay in sync.
+ */
+export function isAllowedScheme(url) {
+    if (typeof url !== "string" || url.length === 0)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    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;
+    if (net.isIPv4(ip))
+        return classifyIpv4(ip);
+    if (net.isIPv6(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))
+        return { class: "loopback" };
+    return classify(stripped);
+}
+/**
+ * Legacy boolean shape preserved for the existing `http.fetch` SSRF check.
+ *
+ * Returns `true` whenever {@link classifyHost} would return a non-null
+ * classification, plus a small additional set of historically-blocked
+ * ranges (currently `0.0.0.0/8`, the "this network" range) that are kept
+ * for backward compatibility with the previous `http.ts` implementation
+ * but are not enumerated in the public {@link AddressClass} list.
+ */
+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]);
+        if (Number.isInteger(first) && first === 0)
+            return true;
+    }
+    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 &&
+                hextets[3] === 0 &&
+                hextets[4] === 0 &&
+                hextets[5] === 0xffff) {
+                const embeddedFirstOctet = (hextets[6] >> 8) & 0xff;
+                if (embeddedFirstOctet === 0)
+                    return true;
+            }
+        }
+    }
+    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;
+    if (a === 127)
+        return { class: "loopback" };
+    if (a === 10)
+        return { class: "rfc1918" };
+    if (a === 172 && b >= 16 && b <= 31)
+        return { class: "rfc1918" };
+    if (a === 192 && b === 168)
+        return { class: "rfc1918" };
+    if (a === 169 && b === 254)
+        return { class: "ipv4-link-local" };
+    if (a === 100 && b >= 64 && b <= 127)
+        return { class: "cgnat" };
+    return null;
+}
+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 &&
+        hextets[3] === 0 &&
+        hextets[4] === 0 &&
+        hextets[5] === 0 &&
+        hextets[6] === 0 &&
+        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 &&
+        hextets[3] === 0 &&
+        hextets[4] === 0 &&
+        hextets[5] === 0xffff) {
+        const a = (hextets[6] >> 8) & 0xff;
+        const b = hextets[6] & 0xff;
+        const c = (hextets[7] >> 8) & 0xff;
+        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 &&
+        hextets[3] === 0 &&
+        hextets[4] === 0 &&
+        hextets[5] === 0 &&
+        hextets[6] === 0 &&
+        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];
+        const v4Parts = v4Match[2].split(".").map((p) => Number(p));
+        if (v4Parts.length !== 4 ||
+            v4Parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) {
+            return null;
+        }
+        const hex1 = ((v4Parts[0] << 8) | v4Parts[1]).toString(16);
+        const hex2 = ((v4Parts[2] << 8) | v4Parts[3]).toString(16);
+        normalized = `${prefix}${hex1}:${hex2}`;
+    }
+    const parts = normalized.split("::");
+    if (parts.length > 2)
+        return null;
+    const head = parts[0].length > 0 ? parts[0].split(":") : [];
+    const tail = parts.length === 2 && parts[1].length > 0 ? parts[1].split(":") : [];
+    const hasCompression = parts.length === 2;
+    if (!hasCompression && head.length !== 8)
+        return null;
+    const missing = 8 - head.length - tail.length;
+    if (missing < 0)
+        return null;
+    if (hasCompression && missing < 1)
+        return null;
+    const middle = hasCompression ? Array(missing).fill("0") : [];
+    const all = [...head, ...middle, ...tail];
+    if (all.length !== 8)
+        return null;
+    const hextets = [];
+    for (const h of all) {
+        if (!/^[0-9a-f]{1,4}$/.test(h))
+            return null;
+        hextets.push(parseInt(h, 16));
+    }
+    return hextets;
+}
+//# sourceMappingURL=ssrf-guard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.js","sourceRoot":"","sources":["../../../src/tools/web/ssrf-guard.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,331 @@
+/**
+ * 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";
+/** Convenience tuple form of the {@link SearchProviderId} union. */
+export declare const searchProviderIds: readonly SearchProviderId[];
+/**
+ * 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 as UTF-8 with replacement, truncated to
+ *   `maxBytes` (Requirement 2.29).
+ */
+export type ResponseMode = "readable" | "raw";
+/** Allowed values for `WebFetchArgs.responseMode`. */
+export declare const RESPONSE_MODES: readonly ResponseMode[];
+/**
+ * Arguments accepted by the `web.fetch` tool.
+ *
+ * Defaults applied when an optional argument is omitted:
+ * - `maxBytes`             → {@link DEFAULT_MAX_BYTES}        (Requirement 2.2)
+ * - `includeHeaders`       → `true`                           (Requirement 2.15)
+ * - `includeTls`           → `true` for `https://`, `false` for `http://`
+ *                             (Requirement 2.16)
+ * - `includeTiming`        → `true`                           (Requirement 2.17)
+ * - `includeRedirectChain` → `true`                           (Requirement 2.18)
+ * - `responseMode`         → `"readable"`                     (Requirement 2.19)
+ * - `redactSensitive`      → `true`                           (Requirement 2.20)
+ */
+export interface WebFetchArgs {
+    url: string;
+    maxBytes?: number;
+    includeHeaders?: boolean;
+    includeTls?: boolean;
+    includeTiming?: boolean;
+    includeRedirectChain?: boolean;
+    responseMode?: ResponseMode;
+    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 = true;
+/** Default value applied when `WebFetchArgs.includeTiming` is omitted. */
+export declare const DEFAULT_INCLUDE_TIMING = true;
+/** Default value applied when `WebFetchArgs.includeRedirectChain` is omitted. */
+export declare const DEFAULT_INCLUDE_REDIRECT_CHAIN = true;
+/** 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 = 30000;
+/** Total wall-clock timeout in milliseconds for a `web.search` invocation. */
+export declare const SEARCH_TIMEOUT_MS = 15000;
+/**
+ * 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;
+    tlsMs?: number;
+    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
+ * the fetch. Cookie values are replaced with {@link REDACTED_PLACEHOLDER}
+ * when `redactSensitive=true` (Requirement 2.32).
+ */
+export interface CookieInfo {
+    name: string;
+    /** Raw cookie value; equals {@link REDACTED_PLACEHOLDER} when redacted. */
+    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;
+    body: string;
+    error?: WebFetchError;
+}

package/dist/tools/web/types.js

@@ -0,0 +1,71 @@
+/**
+ * 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",
+];
+/** 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 = true;
+/** Default value applied when `WebFetchArgs.includeTiming` is omitted. */
+export const DEFAULT_INCLUDE_TIMING = true;
+/** Default value applied when `WebFetchArgs.includeRedirectChain` is omitted. */
+export const DEFAULT_INCLUDE_REDIRECT_CHAIN = true;
+/** 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 = 30_000;
+/** Total wall-clock timeout in milliseconds for a `web.search` invocation. */
+export const SEARCH_TIMEOUT_MS = 15_000;
+//# sourceMappingURL=types.js.map