@pentoshi/clai 4.11.7 → 4.11.8

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

@@ -1,32 +1,10 @@
-/**
- * Audit-log payload builders for `web.search` and `web.fetch`. Single
- * source of truth for the entry shape; `search.ts`/`fetch.ts` pass the
- * result straight to `auditLog`.
- *
- * Two invariants matter here: header/cookie values always go through
- * {@link stripForAudit} (sensitive headers dropped entirely, cookies
- * reduced to name/domain/path/flags — never the value), and the search
- * query text is never logged, only its length.
- */
 import { type AuditSafeCookie } from "./redact.js";
 import type { HeaderMap, ResponseMode, SearchProviderId, WebFetchOutcome, WebSearchOutcome } from "./types.js";
-/**
- * Categorical error description embedded in either audit payload when
- * `outcome.ok === false`. The `kind` discriminator mirrors the matching
- * `Web*ErrorKind` union from `types.ts` so consumers (and the property
- * tests in 7.6) can switch on it without re-parsing the message.
- */
 export interface AuditError {
     kind: string;
     message: string;
     status?: number;
 }
-/**
- * Subset of {@link TlsInfo} surfaced to the audit log. The full
- * `subjectAltNames` list and `notBefore` are intentionally omitted —
- * the requirements (5.8) call for the seven fields below and nothing
- * else; including more would only widen the audit log surface.
- */
 export interface AuditTlsInfo {
     protocol: string;
     cipher: string;
@@ -35,11 +13,9 @@ export interface AuditTlsInfo {
     notAfter: string;
     fingerprintSha256: string;
 }
-/** Per-phase millisecond timings copied straight from {@link TimingInfo}. */
 export interface AuditTimingInfo {
     dnsMs: number;
     tcpMs: number;
-    /** Present iff the URL was `https://` (Requirement 5.9). */
     tlsMs?: number;
     ttfbMs: number;
     totalMs: number;
@@ -54,14 +30,6 @@ export interface AuditRedirectHop {
     url: string;
     status: number;
 }
-/**
- * Audit payload shape emitted for `tool.web_search`. Mirrors the field
- * list in Requirement 5.5: provider id, integer query length, integer
- * result count, outcome status (`ok`), and a categorical error block
- * when the invocation failed.
- *
- * The query text itself never appears here.
- */
 export interface SearchAuditPayload {
     ok: boolean;
     provider: SearchProviderId;
@@ -69,35 +37,7 @@ export interface SearchAuditPayload {
     resultCount: number;
     error?: AuditError;
 }
-/**
- * Build the audit payload for a single `web.search` invocation.
- *
- * The caller passes the trimmed query length explicitly because the
- * outcome object does not carry it (the query text is dropped before
- * the outcome leaves the handler, by design — see Requirement 5.5).
- * `queryLength` is clamped to `>= 0` and coerced to a non-negative
- * integer so a malformed caller cannot inject a string or negative
- * value into the audit log.
- */
 export declare function buildSearchAuditPayload(outcome: WebSearchOutcome, queryLength: number): SearchAuditPayload;
-/**
- * Audit payload shape emitted for `tool.web_fetch`. Required fields are
- * always present (Requirements 5.6–5.7); the optional sub-objects are
- * present iff the corresponding metadata stage produced output:
- *
- *  - `tls`           when {@link WebFetchMetadata.tls} is defined
- *                      (Requirement 5.8).
- *  - `timing`        when {@link WebFetchMetadata.timing} is defined
- *                      (Requirement 5.9).
- *  - `redirectChain` when {@link WebFetchMetadata.redirectChain} is
- *                      defined and non-empty (Requirement 5.10).
- *  - `headers`       when {@link WebFetchMetadata.headers} is defined,
- *                      with sensitive header keys stripped entirely
- *                      (Requirement 5.12).
- *  - `cookies`       when {@link WebFetchMetadata.cookies} is defined
- *                      and non-empty, reduced to the
- *                      {@link AuditSafeCookie} shape (Requirement 5.11).
- */
 export interface FetchAuditPayload {
     ok: boolean;
     requestedUrl: string;
@@ -115,18 +55,4 @@ export interface FetchAuditPayload {
     redirectChain?: AuditRedirectHop[];
     error?: AuditError;
 }
-/**
- * Build the audit payload for a single `web.fetch` invocation.
- *
- * Routes `outcome.metadata.headers` and `outcome.metadata.cookies`
- * through {@link stripForAudit} unconditionally so the audit log
- * never carries a `Cookie` / `Set-Cookie` / `Authorization` /
- * `Proxy-Authorization` value, nor any cookie's `value`,
- * `expires`, or `maxAge` (Requirements 5.11, 5.12).
- *
- * The `body` field of the outcome is intentionally never read here —
- * the response body is excluded from the audit log per Requirement 5.6
- * and the request body never enters the outcome shape per
- * Requirement 5.13.
- */
 export declare function buildFetchAuditPayload(outcome: WebFetchOutcome): FetchAuditPayload;

package/dist/tools/web/audit.js

@@ -1,24 +1,4 @@
-/**
- * Audit-log payload builders for `web.search` and `web.fetch`. Single
- * source of truth for the entry shape; `search.ts`/`fetch.ts` pass the
- * result straight to `auditLog`.
- *
- * Two invariants matter here: header/cookie values always go through
- * {@link stripForAudit} (sensitive headers dropped entirely, cookies
- * reduced to name/domain/path/flags — never the value), and the search
- * query text is never logged, only its length.
- */
 import { stripForAudit } from "./redact.js";
-/**
- * Build the audit payload for a single `web.search` invocation.
- *
- * The caller passes the trimmed query length explicitly because the
- * outcome object does not carry it (the query text is dropped before
- * the outcome leaves the handler, by design — see Requirement 5.5).
- * `queryLength` is clamped to `>= 0` and coerced to a non-negative
- * integer so a malformed caller cannot inject a string or negative
- * value into the audit log.
- */
 export function buildSearchAuditPayload(outcome, queryLength) {
     const safeLength = Number.isFinite(queryLength)
         ? Math.max(0, Math.trunc(queryLength))
@@ -41,25 +21,9 @@ export function buildSearchAuditPayload(outcome, queryLength) {
     }
     return payload;
 }
-/**
- * Build the audit payload for a single `web.fetch` invocation.
- *
- * Routes `outcome.metadata.headers` and `outcome.metadata.cookies`
- * through {@link stripForAudit} unconditionally so the audit log
- * never carries a `Cookie` / `Set-Cookie` / `Authorization` /
- * `Proxy-Authorization` value, nor any cookie's `value`,
- * `expires`, or `maxAge` (Requirements 5.11, 5.12).
- *
- * The `body` field of the outcome is intentionally never read here —
- * the response body is excluded from the audit log per Requirement 5.6
- * and the request body never enters the outcome shape per
- * Requirement 5.13.
- */
 export function buildFetchAuditPayload(outcome) {
     const meta = outcome.metadata;
     // Always-on redaction of headers and cookies for audit. See the
-    // module-level invariant (1): the audit log never sees sensitive
-    // header *values* nor any cookie *value*, regardless of the user's
     // `redactSensitive` choice.
     const safe = stripForAudit(meta.headers, meta.cookies);
     const payload = {
@@ -102,9 +66,6 @@ export function buildFetchAuditPayload(outcome) {
         payload.timing = t;
     }
     if (meta.redirectChain && meta.redirectChain.length > 0) {
-        // Requirement 5.10: chronological, capped at 5. The pipeline already
-        // caps at MAX_REDIRECT_HOPS, but slice defensively to make this
-        // helper safe to call from tests with synthetic outcomes.
         payload.redirectChain = meta.redirectChain.slice(0, 5).map((hop) => ({
             url: hop.url,
             status: Math.trunc(hop.status) || 0,

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

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

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

@@ -1,19 +1,4 @@
-/**
- * Caps the combined serialized size of `web.fetch` metadata (headers, TLS,
- * timing, redirect chain, cookies) at {@link METADATA_BUDGET_BYTES} (64 KiB),
- * trimming in order: trailing cookies, then longest header values (down to
- * 1024 chars, keys always kept), then trailing redirect hops. Pure function;
- * bounded iteration count so a pathological input can't loop indefinitely.
- */
 import { type CookieInfo, type HeaderMap, type RedirectChain, type TimingInfo, type TlsInfo, METADATA_BUDGET_BYTES } from "./types.js";
-/**
- * Inputs accepted by {@link enforce}.
- *
- * Each field corresponds to one slice of {@link WebFetchMetadata}.
- * Fields that the caller chose not to include (for example because the
- * user passed `includeHeaders=false`) may be omitted or set to
- * `undefined`; they are passed through to the result unchanged.
- */
 export interface BudgetInput {
     headers?: HeaderMap | undefined;
     tls?: TlsInfo | undefined;
@@ -21,15 +6,6 @@ export interface BudgetInput {
     redirectChain?: RedirectChain | undefined;
     cookies?: CookieInfo[] | undefined;
 }
-/**
- * Result returned by {@link enforce}. Optional fields are present iff
- * the corresponding input field was present (an empty array is still
- * "present"). `metadataBytes` is the UTF-8 byte length of
- * `JSON.stringify({headers, tls, timing, redirectChain, cookies})` after
- * the truncation loop has finished. `cap` mirrors the constant from
- * `types.ts` so consumers can render `metadataBytes / cap` without
- * importing it themselves.
- */
 export interface BudgetResult {
     headers?: HeaderMap;
     tls?: TlsInfo;
@@ -39,15 +15,4 @@ export interface BudgetResult {
     metadataBytes: number;
     cap: typeof METADATA_BUDGET_BYTES;
 }
-/**
- * Enforce the 64 KiB metadata budget on the supplied fields.
- *
- * Returns a fresh {@link BudgetResult} containing (possibly shortened)
- * copies of `headers`, `redirectChain`, and `cookies`, alongside `tls`
- * and `timing` passed through unchanged, plus the final
- * `metadataBytes` count.
- *
- * The returned arrays/maps are independent of the caller's inputs — the
- * function does not mutate `input`.
- */
 export declare function enforce(input: BudgetInput): BudgetResult;

package/dist/tools/web/budget.js

@@ -1,45 +1,7 @@
-/**
- * Caps the combined serialized size of `web.fetch` metadata (headers, TLS,
- * timing, redirect chain, cookies) at {@link METADATA_BUDGET_BYTES} (64 KiB),
- * trimming in order: trailing cookies, then longest header values (down to
- * 1024 chars, keys always kept), then trailing redirect hops. Pure function;
- * bounded iteration count so a pathological input can't loop indefinitely.
- */
 import { METADATA_BUDGET_BYTES, TRUNCATION_MARKER, } from "./types.js";
-/**
- * Per-header-value floor below which the budget loop will not halve any
- * further. Once every header value's "content" portion (length excluding
- * the trailing {@link TRUNCATION_MARKER}, when present) is at or below
- * this number of characters, the loop moves on to dropping redirect
- * hops.
- *
- * Matches the design pseudocode "any header value not yet truncated to
- * 1024".
- */
 const HEADER_VALUE_FLOOR = 1024;
-/**
- * Hard upper bound on the number of reduction steps the budget loop will
- * perform per invocation. Each step either drops one cookie, halves one
- * header value, or drops one redirect hop. With realistic inputs the
- * loop terminates within a few dozen iterations; the cap exists purely
- * to defend against pathological inputs that would otherwise loop
- * forever.
- */
 const MAX_ITERATIONS = 10_000;
-/**
- * Enforce the 64 KiB metadata budget on the supplied fields.
- *
- * Returns a fresh {@link BudgetResult} containing (possibly shortened)
- * copies of `headers`, `redirectChain`, and `cookies`, alongside `tls`
- * and `timing` passed through unchanged, plus the final
- * `metadataBytes` count.
- *
- * The returned arrays/maps are independent of the caller's inputs — the
- * function does not mutate `input`.
- */
 export function enforce(input) {
-    // Shallow-copy any mutable structures so the caller's data is left
-    // untouched even when the loop pops or halves entries.
     const headers = input.headers !== undefined ? { ...input.headers } : undefined;
     const cookies = input.cookies !== undefined ? [...input.cookies] : undefined;
     const redirectChain = input.redirectChain !== undefined ? [...input.redirectChain] : undefined;
@@ -49,17 +11,14 @@ export function enforce(input) {
     for (let i = 0; i < MAX_ITERATIONS && metadataBytes > METADATA_BUDGET_BYTES; i++) {
         let progress = false;
         if (cookies !== undefined && cookies.length > 0) {
-            // Step 1: drop trailing cookies first (Requirement 2.35).
             cookies.pop();
             progress = true;
         }
         else if (headers !== undefined && hasHalveableHeader(headers)) {
-            // Step 2: halve the longest header value with content > 1024 chars.
             halveLongestHeaderValue(headers);
             progress = true;
         }
         else if (redirectChain !== undefined && redirectChain.length > 0) {
-            // Step 3: drop trailing redirect hops as the last resort.
             redirectChain.pop();
             progress = true;
         }
@@ -76,14 +35,6 @@ export function enforce(input) {
         metadataBytes,
     });
 }
-// ---------------------------------------------------------------------------
-// Internals
-// ---------------------------------------------------------------------------
-/**
- * Return `true` iff at least one header value's content portion (length
- * excluding the trailing {@link TRUNCATION_MARKER}, when present)
- * exceeds {@link HEADER_VALUE_FLOOR}.
- */
 function hasHalveableHeader(headers) {
     for (const value of Object.values(headers)) {
         if (contentLength(value) > HEADER_VALUE_FLOOR)
@@ -91,14 +42,6 @@ function hasHalveableHeader(headers) {
     }
     return false;
 }
-/**
- * Find the header whose content portion is currently longest (ties
- * resolved by iteration order, which is stable in V8 for string keys),
- * halve that content in place, and append the
- * {@link TRUNCATION_MARKER}. Header values whose content is already
- * ≤ {@link HEADER_VALUE_FLOOR} are skipped; the function is a no-op when
- * no such value exists.
- */
 function halveLongestHeaderValue(headers) {
     let bestKey;
     let bestLen = -1;
@@ -118,32 +61,14 @@ function halveLongestHeaderValue(headers) {
     const halved = content.slice(0, Math.floor(content.length / 2));
     headers[bestKey] = `${halved}${TRUNCATION_MARKER}`;
 }
-/**
- * Length of `value`'s "content" portion in characters: the full string
- * length minus the {@link TRUNCATION_MARKER} suffix when one is
- * present. Used so repeated halving of the same header value reduces
- * the underlying content rather than treating the marker itself as
- * shrinkable text.
- */
 function contentLength(value) {
     return stripMarker(value).length;
 }
-/**
- * Strip a single trailing {@link TRUNCATION_MARKER} from `value` if one
- * is present. Returns `value` unchanged otherwise. Used by the halving
- * step so the marker is not duplicated when a header is truncated more
- * than once across loop iterations.
- */
 function stripMarker(value) {
     return value.endsWith(TRUNCATION_MARKER)
         ? value.slice(0, value.length - TRUNCATION_MARKER.length)
         : value;
 }
-/**
- * Build the {@link BudgetResult} from the working state. Optional input
- * fields that were not supplied are left absent on the result (rather
- * than set to `undefined`) to satisfy `exactOptionalPropertyTypes`.
- */
 function assemble(state) {
     const result = {
         metadataBytes: state.metadataBytes,

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

@@ -1 +1 @@
-{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../src/tools/web/budget.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../src/tools/web/budget.ts"],"names":[],"mappings":"AACA,OAAO,EAML,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,MAAM,cAAc,GAAG,MAAM,CAAC;AAoB9B,MAAM,UAAU,OAAO,CAAC,KAAkB;IACxC,MAAM,OAAO,GACX,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,MAAM,OAAO,GACX,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/D,MAAM,aAAa,GACjB,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAE9B,MAAM,OAAO,GAAG,GAAW,EAAE,CAC3B,MAAM,CAAC,UAAU,CACf,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAChE,MAAM,CACP,CAAC;IAEJ,IAAI,aAAa,GAAG,OAAO,EAAE,CAAC;IAE9B,KACE,IAAI,CAAC,GAAG,CAAC,EACT,CAAC,GAAG,cAAc,IAAI,aAAa,GAAG,qBAAqB,EAC3D,CAAC,EAAE,EACH,CAAC;QACD,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChD,OAAO,CAAC,GAAG,EAAE,CAAC;YACd,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;aAAM,IAAI,OAAO,KAAK,SAAS,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YAChE,uBAAuB,CAAC,OAAO,CAAC,CAAC;YACjC,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;aAAM,IAAI,aAAa,KAAK,SAAS,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnE,aAAa,CAAC,GAAG,EAAE,CAAC;YACpB,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;QAED,IAAI,CAAC,QAAQ;YAAE,MAAM;QACrB,aAAa,GAAG,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED,OAAO,QAAQ,CAAC;QACd,OAAO;QACP,GAAG;QACH,MAAM;QACN,aAAa;QACb,OAAO;QACP,aAAa;KACd,CAAC,CAAC;AACL,CAAC;AAGD,SAAS,kBAAkB,CAAC,OAAkB;IAC5C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,IAAI,aAAa,CAAC,KAAK,CAAC,GAAG,kBAAkB;YAAE,OAAO,IAAI,CAAC;IAC7D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,uBAAuB,CAAC,OAAkB;IACjD,IAAI,OAA2B,CAAC;IAChC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;IACjB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,GAAG,GAAG,kBAAkB,IAAI,GAAG,GAAG,OAAO,EAAE,CAAC;YAC9C,OAAO,GAAG,GAAG,CAAC;YACd,OAAO,GAAG,GAAG,CAAC;QAChB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAElC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAElC,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,OAAO,CAAC,GAAG,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AACnC,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QACtC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC;QACzD,CAAC,CAAC,KAAK,CAAC;AACZ,CAAC;AAED,SAAS,QAAQ,CAAC,KAOjB;IACC,MAAM,MAAM,GAAiB;QAC3B,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,GAAG,EAAE,qBAAqB;KAC3B,CAAC;IACF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAChE,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;QAAE,MAAM,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACpD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC7D,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS;QACnC,MAAM,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAChE,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -22,110 +22,35 @@ import { type CookieInfo, type HeaderMap, type RedirectChain, type TimingInfo, t
  * `redact.applyToHeaders` / `redact.applyToCookies` and `budget.enforce`.
  */
 export interface CapturedFields {
-    /** IP address contacted on the final hop. */
     resolvedIp: string;
-    /** Hostname of the final hop (the one whose body is returned). */
     finalHostname: string;
-    /** Integer HTTP status of the final response. */
     status: number;
-    /** Lowercased response headers from the final hop, repeats joined. */
     headers: HeaderMap;
-    /** TLS session details from the final hop, when the scheme was https. */
     tls?: TlsInfo;
-    /** Per-phase timings; `tlsMs` is omitted on http:// requests. */
     timing: TimingInfo;
-    /** Up to {@link MAX_REDIRECT_HOPS} hops in chronological order. */
     redirectChain: RedirectChain;
-    /** Up to {@link MAX_COOKIES_CAPTURED} cookies parsed from `Set-Cookie`. */
     cookies: CookieInfo[];
 }
-/**
- * Pure builder that records the per-hop observations made by
- * `fetch-core.ts` and assembles them into a {@link CapturedFields}
- * snapshot via {@link Capture.finalize}.
- *
- * The builder is single-use: callers should construct one `Capture` per
- * `web.fetch` invocation and discard it after `finalize`.
- */
 export declare class Capture {
-    /** Final-hop DNS-resolution time in milliseconds. */
     private dnsMs;
-    /** Final-hop TCP-connect time in milliseconds. */
     private tcpMs;
-    /** Final-hop TLS-handshake time in milliseconds (https only). */
     private tlsMs;
-    /** Final-hop time-to-first-byte in milliseconds. */
     private ttfbMs;
-    /** Final-hop resolved IP, set by {@link markDnsResolved}. */
     private resolvedIp;
-    /** Final-hop hostname, set by {@link setHopContext}. */
     private finalHostname;
-    /** Final-hop HTTP status, set by {@link markResponse}. */
     private status;
-    /** Final-hop normalised headers, set by {@link markResponse}. */
     private headers;
-    /** Final-hop TLS info (https only), set by {@link markTlsHandshaked}. */
     private tls;
-    /** Redirect hops, capped at {@link MAX_REDIRECT_HOPS}. */
     private readonly redirectChain;
-    /** Captured cookies, capped at {@link MAX_COOKIES_CAPTURED}. */
     private readonly cookies;
-    /**
-     * Whether the current invocation is an `https://` fetch. When `false`,
-     * `tlsMs` is omitted from {@link TimingInfo} and `tls` from
-     * {@link CapturedFields} per Requirements 2.16, 2.24, and 2.25.
-     */
     private readonly isHttps;
-    /**
-     * Construct a fresh builder.
-     *
-     * @param opts.isHttps - Whether the request URL used `https://`.
-     *   Controls whether `timing.tlsMs` and `tls` are populated.
-     * @param opts.finalHostname - Optional initial hostname; the transport
-     *   will overwrite this via {@link setHopContext} as redirects are
-     *   followed.
-     */
     constructor(opts: {
         isHttps: boolean;
         finalHostname?: string;
     });
-    /**
-     * Record the hostname of the hop the transport is about to issue.
-     *
-     * Called once per hop, before {@link markDnsResolved}. The most-recent
-     * value becomes {@link CapturedFields.finalHostname}.
-     */
     setHopContext(hostname: string): void;
-    /**
-     * Record the DNS-resolution outcome for the current hop.
-     *
-     * The most-recent values overwrite any earlier ones so the values
-     * surfaced in {@link TimingInfo.dnsMs} and
-     * {@link CapturedFields.resolvedIp} correspond to the final hop.
-     */
     markDnsResolved(ms: number, ip: string): void;
-    /**
-     * Record the TCP-connect time for the current hop. The most-recent
-     * value wins (see class-level docstring for per-hop semantics).
-     */
     markTcpConnected(ms: number): void;
-    /**
-     * Record the TLS handshake time and extract {@link TlsInfo} from the
-     * final-hop `tls.TLSSocket`.
-     *
-     * - `protocol`           ← `socket.getProtocol()` (`""` if null).
-     * - `cipher`             ← `socket.getCipher().name` (`""` if missing).
-     * - `subjectCN/issuerCN` ← `cert.subject.CN` / `cert.issuer.CN`.
-     * - `subjectAltNames`    ← parsed from `cert.subjectaltname`.
-     * - `notBefore/notAfter` ← `cert.valid_from` / `cert.valid_to` parsed
-     *                          to ISO 8601 (falls back to the raw value).
-     * - `fingerprintSha256`  ← lowercase, colon-separated SHA-256 of
-     *                          `cert.raw` via `node:crypto`.
-     *
-     * Calling this method on an http:// fetch is harmless but pointless —
-     * the constructor's `isHttps=false` flag suppresses the field in
-     * {@link finalize} regardless.
-     */
     markTlsHandshaked(ms: number, socket: TLSSocket): void;
     /**
      * Record the final-hop response: HTTP status, raw headers
@@ -137,38 +62,7 @@ export declare class Capture {
      * `fetch-core.ts` calls once per `Set-Cookie` line observed.
      */
     markResponse(status: number, rawHeaders: IncomingHttpHeaders, ttfbMs: number): void;
-    /**
-     * Append a redirect hop to the chronological chain.
-     *
-     * Hops in excess of {@link MAX_REDIRECT_HOPS} are silently dropped so
-     * the array always satisfies the cap from Requirement 2.26.
-     * `fetch-core.ts` is responsible for surfacing the
-     * `redirect-limit` error when the cap is reached; this builder just
-     * stops accumulating.
-     */
     addRedirectHop(url: string, status: number, location?: string): void;
-    /**
-     * Parse one `Set-Cookie` header value via {@link parseSetCookie} and
-     * append the resulting {@link CookieInfo}, bounded at
-     * {@link MAX_COOKIES_CAPTURED}.
-     *
-     * Cookies in excess of the cap are silently dropped, matching
-     * Requirement 2.31.
-     */
     addSetCookieHeader(value: string): void;
-    /**
-     * Produce the {@link CapturedFields} snapshot.
-     *
-     * @param totalMs - Wall-clock duration of the whole invocation, in
-     *   milliseconds. Stored in {@link TimingInfo.totalMs}.
-     *
-     * Optional fields obey the design's "include flags applied at the
-     * adapter, not at the builder" principle: this method always emits
-     * every field it observed, including `tls` (when `isHttps=true` and a
-     * handshake was captured). The fetch handler in `fetch.ts` is
-     * responsible for honouring `includeTls` / `includeTiming` /
-     * `includeRedirectChain` by stripping fields from the assembled
-     * {@link WebFetchMetadata} *after* this snapshot is produced.
-     */
     finalize(totalMs: number): CapturedFields;
 }