@pentoshi/clai 0.10.4 → 0.11.0

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

@@ -0,0 +1,76 @@
+/**
+ * 64 KiB metadata budget enforcement for `web.fetch`.
+ *
+ * Requirement 2.35 caps the combined serialized size of the
+ * {@link HeaderMap}, {@link TlsInfo}, {@link TimingInfo},
+ * {@link RedirectChain}, and `cookies` array at
+ * {@link METADATA_BUDGET_BYTES} (64 KiB). When the assembled metadata
+ * exceeds the cap, this module reduces it deterministically using the
+ * order documented in `.kiro/specs/web-search-and-fetch/design.md`,
+ * "Truncation order at the 64 KiB cap":
+ *
+ * 1. Drop trailing cookies (last entry first) — Requirement 2.35.
+ * 2. Halve the longest header value (with the literal
+ *    {@link TRUNCATION_MARKER} appended) until every header value's
+ *    "content" portion is ≤ 1024 characters. Header keys are never
+ *    removed so the agent always sees which headers were present.
+ * 3. Drop trailing redirect hops one at a time.
+ *
+ * `tls` and `timing` are well under 1 KiB combined and are never touched
+ * by this loop. The function is pure: caller inputs are not mutated; the
+ * returned object holds fresh copies of any arrays/maps that were
+ * shortened.
+ *
+ * The implementation is bounded to a fixed iteration count so a
+ * pathological input (for example, hundreds of header values that are
+ * all ≤ 1024 chars yet collectively still exceed the cap) cannot wedge
+ * the agent. In that edge case the returned `metadataBytes` may exceed
+ * {@link METADATA_BUDGET_BYTES} — the caller can decide whether to
+ * surface the overflow or treat it as a soft warning.
+ */
+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;
+    timing?: TimingInfo | undefined;
+    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;
+    timing?: TimingInfo;
+    redirectChain?: RedirectChain;
+    cookies?: CookieInfo[];
+    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

@@ -0,0 +1,187 @@
+/**
+ * 64 KiB metadata budget enforcement for `web.fetch`.
+ *
+ * Requirement 2.35 caps the combined serialized size of the
+ * {@link HeaderMap}, {@link TlsInfo}, {@link TimingInfo},
+ * {@link RedirectChain}, and `cookies` array at
+ * {@link METADATA_BUDGET_BYTES} (64 KiB). When the assembled metadata
+ * exceeds the cap, this module reduces it deterministically using the
+ * order documented in `.kiro/specs/web-search-and-fetch/design.md`,
+ * "Truncation order at the 64 KiB cap":
+ *
+ * 1. Drop trailing cookies (last entry first) — Requirement 2.35.
+ * 2. Halve the longest header value (with the literal
+ *    {@link TRUNCATION_MARKER} appended) until every header value's
+ *    "content" portion is ≤ 1024 characters. Header keys are never
+ *    removed so the agent always sees which headers were present.
+ * 3. Drop trailing redirect hops one at a time.
+ *
+ * `tls` and `timing` are well under 1 KiB combined and are never touched
+ * by this loop. The function is pure: caller inputs are not mutated; the
+ * returned object holds fresh copies of any arrays/maps that were
+ * shortened.
+ *
+ * The implementation is bounded to a fixed iteration count so a
+ * pathological input (for example, hundreds of header values that are
+ * all ≤ 1024 chars yet collectively still exceed the cap) cannot wedge
+ * the agent. In that edge case the returned `metadataBytes` may exceed
+ * {@link METADATA_BUDGET_BYTES} — the caller can decide whether to
+ * surface the overflow or treat it as a soft warning.
+ */
+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;
+    const { tls, timing } = input;
+    const measure = () => Buffer.byteLength(JSON.stringify({ headers, tls, timing, redirectChain, cookies }), "utf8");
+    let metadataBytes = measure();
+    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;
+        }
+        if (!progress)
+            break;
+        metadataBytes = measure();
+    }
+    return assemble({
+        headers,
+        tls,
+        timing,
+        redirectChain,
+        cookies,
+        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)
+            return true;
+    }
+    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;
+    for (const [key, value] of Object.entries(headers)) {
+        const len = contentLength(value);
+        if (len > HEADER_VALUE_FLOOR && len > bestLen) {
+            bestKey = key;
+            bestLen = len;
+        }
+    }
+    if (bestKey === undefined)
+        return;
+    const current = headers[bestKey];
+    if (current === undefined)
+        return;
+    const content = stripMarker(current);
+    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,
+        cap: METADATA_BUDGET_BYTES,
+    };
+    if (state.headers !== undefined)
+        result.headers = state.headers;
+    if (state.tls !== undefined)
+        result.tls = state.tls;
+    if (state.timing !== undefined)
+        result.timing = state.timing;
+    if (state.redirectChain !== undefined)
+        result.redirectChain = state.redirectChain;
+    if (state.cookies !== undefined)
+        result.cookies = state.cookies;
+    return result;
+}
+//# sourceMappingURL=budget.js.map

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

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

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

@@ -0,0 +1,201 @@
+/**
+ * `Capture` — pure observation builder for a single `web.fetch` invocation.
+ *
+ * The fetch transport in `fetch-core.ts` feeds events into this builder
+ * (DNS resolution, TCP connect, TLS handshake, response headers, redirect
+ * hops, `Set-Cookie` lines) and the builder accumulates the structured
+ * fields the {@link WebFetchMetadata} envelope needs:
+ *
+ * - {@link TimingInfo}: `dnsMs`, `tcpMs`, `tlsMs`, `ttfbMs`, `totalMs`
+ * - {@link TlsInfo} from the final hop's `tls.TLSSocket`
+ *   (`getProtocol()`, `getCipher().name`, `getPeerCertificate(true)`)
+ * - response headers (lowercased keys, repeat values joined with `, `)
+ * - the redirect chain (capped at {@link MAX_REDIRECT_HOPS})
+ * - the resolved IP and the final hostname
+ * - `Set-Cookie` cookies (capped at {@link MAX_COOKIES_CAPTURED})
+ *
+ * The builder performs **no I/O** — it never touches the network, the
+ * filesystem, or `auditLog`. It is a pure data sink so the transport
+ * layer in `fetch-core.ts` can be tested independently of the
+ * Node `https`/`tls` machinery.
+ *
+ * Per-hop semantics:
+ * - `setHopContext(hostname)` is called by the transport at the start of
+ *   each hop; the value of the *last* hop becomes
+ *   {@link CapturedFields.finalHostname}.
+ * - {@link Capture.markDnsResolved} replaces the running `dnsMs` /
+ *   `resolvedIp` so the values surfaced in {@link CapturedFields}
+ *   correspond to the *final* hop. Same for `tcpMs`, `tlsMs`, and
+ *   `ttfbMs` — only the last hop's measurements are returned.
+ * - {@link Capture.addRedirectHop} appends one entry per intermediate
+ *   3xx hop; the array is bounded at {@link MAX_REDIRECT_HOPS}.
+ * - {@link Capture.addSetCookieHeader} parses every observed
+ *   `Set-Cookie` line via {@link parseSetCookie}; the resulting array is
+ *   bounded at {@link MAX_COOKIES_CAPTURED}.
+ *
+ * Redaction and 4096-char header-value truncation are applied later by
+ * `redact.applyToHeaders` / `redact.applyToCookies` and the 64 KiB
+ * metadata budget by `budget.enforce`. This module only collects.
+ */
+import type { IncomingHttpHeaders } from "node:http";
+import type { TLSSocket } from "node:tls";
+import { type CookieInfo, type HeaderMap, type RedirectChain, type TimingInfo, type TlsInfo } from "./types.js";
+/**
+ * Snapshot of the structured fields the builder has accumulated when
+ * `fetch-core.ts` finalises the response. The shape matches the slice of
+ * {@link WebFetchMetadata} that depends on per-hop transport
+ * observation; the fetch handler combines this with `requestedUrl`,
+ * `finalUrl`, `mode`, `bytesReceived`, `truncated`, etc. before applying
+ * `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
+     * (lowercased and joined into a {@link HeaderMap}), and TTFB.
+     *
+     * `Set-Cookie` is preserved in `headers` joined with `, ` like every
+     * other repeated header so the audit/redact passes can act on it.
+     * Per-cookie capture happens via {@link addSetCookieHeader}, which
+     * `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;
+}