@cspeach/cli 0.6.0

package/dist/tools/update-method-intercept.js

@@ -0,0 +1,119 @@
+/**
+ * Preview interceptor for sap_update_method calls. Forge Rule 7a in practice:
+ * before any surgical method-source write reaches SAP, fetch the current
+ * source, extract the named method's body, render a unified diff vs the
+ * proposed source, and gate on a user-confirm hook. The REPL composes this
+ * with renderDiff (./repl/diff-display) and an inquirer confirm prompt.
+ *
+ * Pure orchestration — no I/O of its own. The caller passes in:
+ *   - `client`: a minimal MCP-tool wrapper that can call sap_get_source
+ *   - `call`: the proposed sap_update_method invocation (parameters)
+ *   - `hook`: receives current vs proposed and returns { confirmed }
+ *
+ * Returns the proposed call unchanged when the hook confirms, or throws
+ * a CancelledByUserError when the hook rejects.
+ */
+export class CancelledByUserError extends Error {
+    call;
+    constructor(call) {
+        super(`User declined sap_update_method on ${call.className}->${call.methodName}`);
+        this.call = call;
+        this.name = 'CancelledByUserError';
+    }
+}
+/**
+ * Runs the preview gate. On confirm, returns the original call. On rejection,
+ * throws CancelledByUserError. Throws if the class source can't be fetched
+ * (caller should treat as an unrecoverable error before any write).
+ */
+export async function interceptUpdateMethod(client, call, hook) {
+    const classSource = await client.getSource({ type: 'CLAS', name: call.className });
+    const currentBody = extractMethodBody(classSource, call.methodName);
+    const proposedBody = call.methodSource;
+    const result = await hook({
+        className: call.className,
+        methodName: call.methodName,
+        currentBody,
+        proposedBody,
+    });
+    if (!result.confirmed) {
+        throw new CancelledByUserError(call);
+    }
+    return call;
+}
+/**
+ * Extracts the source of a single method by name from a full class source.
+ * Returns the slice from `METHOD <methodName>.` through the matching
+ * `ENDMETHOD.` (inclusive). If the method isn't found, returns an empty
+ * string — callers can render that as "(method not found in current source)"
+ * which still produces a useful diff against the proposed body.
+ *
+ * The parser is line-based and respects:
+ *  - Case-insensitive keyword matching (METHOD, ENDMETHOD).
+ *  - Comment lines starting with `*` in column 1 (skipped during scanning).
+ *  - Inline `"` ABAP comments (text after `"` on a code line is ignored when
+ *    matching keywords).
+ *  - Quoted string literals `'...'` and ``...`` (their contents are ignored).
+ *
+ * Does NOT respect macros or includes — those would expand source from
+ * elsewhere and aren't materialized in the class-source GET response.
+ */
+export function extractMethodBody(classSource, methodName) {
+    const lines = classSource.split(/\r?\n/);
+    const target = methodName.toUpperCase();
+    const startRe = new RegExp(`^\\s*METHOD\\s+${escapeRegex(target)}\\s*[.(]`, 'i');
+    const endRe = /^\s*ENDMETHOD\s*\./i;
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = stripCommentsAndStrings(lines[i]);
+        if (line.trim().startsWith('*'))
+            continue;
+        if (startRe.test(line)) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return '';
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = stripCommentsAndStrings(lines[i]);
+        if (line.trim().startsWith('*'))
+            continue;
+        if (endRe.test(line)) {
+            return lines.slice(start, i + 1).join('\n');
+        }
+    }
+    // METHOD without matching ENDMETHOD — return the rest as a fallback so the
+    // diff still surfaces the partial body to the user.
+    return lines.slice(start).join('\n');
+}
+function stripCommentsAndStrings(line) {
+    // Walk the line and replace string-literal contents and trailing `"` comments
+    // with spaces so keyword matching ignores them. Cheap and good enough for
+    // ABAP's two quote styles.
+    let out = '';
+    let inSingle = false;
+    let inBacktick = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (!inSingle && !inBacktick && ch === '"') {
+            // Trailing comment — drop the rest.
+            break;
+        }
+        if (!inBacktick && ch === "'") {
+            inSingle = !inSingle;
+            out += ch;
+            continue;
+        }
+        if (!inSingle && ch === '`') {
+            inBacktick = !inBacktick;
+            out += ch;
+            continue;
+        }
+        out += inSingle || inBacktick ? ' ' : ch;
+    }
+    return out;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/tools/verify.js

@@ -0,0 +1,39 @@
+/**
+ * Verify helpers — syntax check gate and activation-status gate.
+ *
+ * AdtClient.syntaxCheck(type, name) → SyntaxResult { hasErrors, hasWarnings, messages[] }
+ *   messages[].severity: string  ('error' | 'warning' | 'info')
+ *   messages[].line: number
+ *   messages[].text: string
+ *
+ * AdtClient.inactiveObjects() → InactiveObject[] { name, type, uri, user }
+ *
+ * (Confirmed from sap-client/src/adt-client.ts lines 82-87, 224-228, 547.)
+ */
+/**
+ * Run a syntax check and return a normalised VerifyResult.
+ * Errors block activation; warnings are surfaced but do not block.
+ */
+export async function verifySyntax(adt, name, type) {
+    const res = await adt.syntaxCheck(type, name);
+    return {
+        ok: !res.hasErrors,
+        errors: res.messages
+            .filter((m) => m.severity === 'error')
+            .map((m) => `L${m.line}: ${m.text}`),
+        warnings: res.messages
+            .filter((m) => m.severity === 'warning')
+            .map((m) => `L${m.line}: ${m.text}`),
+    };
+}
+export async function verifyActive(adt, name, type) {
+    let inactive;
+    try {
+        inactive = await adt.inactiveObjects();
+    }
+    catch (err) {
+        return { active: false, verifyError: String(err?.message ?? err) };
+    }
+    const stillInactive = inactive.some((o) => o.name.toUpperCase() === name.toUpperCase() && o.type.toUpperCase() === type.toUpperCase());
+    return { active: !stillInactive };
+}

package/dist/tools/web/_web-shared.js

@@ -0,0 +1,251 @@
+// cspeach-cli/src/tools/web/_web-shared.ts
+/**
+ * Phase 3 / Chunk 3C — shared URL validator + DNS pin-lookup helper.
+ *
+ * Used by web_fetch (this chunk) and, eventually, web_search (chunk-3C2).
+ * Centralising the SSRF defenses in one module means the security guard
+ * cannot drift per-tool — any web tool calls validateUrl() and passes
+ * the returned pinnedLookup to https.request.
+ *
+ * Threat model (full table in 2026-05-11-track-b-phase-3-chunk-3c-plan.md):
+ *   - HTTPS-only protocol
+ *   - hostname-string blocklist (localhost, *.local, metadata.google.internal)
+ *   - DNS-resolved-IP blocklist (IPv4 RFC1918 + loopback + link-local +
+ *     multicast + reserved; IPv6 loopback + ULA + link-local + unspecified)
+ *   - DNS pinning — the resolved address is passed back as a `lookup`
+ *     callback so https.request doesn't re-resolve the hostname at
+ *     connect time (closes the DNS-rebinding hole)
+ *
+ * Escape hatch: CSPEACH_WEB_ALLOW_PRIVATE=on lifts the private-IP check
+ * (still HTTPS-only). Off by default.
+ */
+import { promises as dnsPromises } from 'node:dns';
+import * as net from 'node:net';
+export class MalformedUrlError extends Error {
+    constructor(input, reason) {
+        super(`Malformed URL "${input}": ${reason}`);
+        this.name = 'MalformedUrlError';
+    }
+}
+export class BlockedProtocolError extends Error {
+    constructor(protocol) {
+        super(`Protocol "${protocol}" is not allowed (HTTPS only).`);
+        this.name = 'BlockedProtocolError';
+    }
+}
+export class BlockedHostError extends Error {
+    constructor(host, reason) {
+        super(`Host "${host}" is blocked: ${reason}`);
+        this.name = 'BlockedHostError';
+    }
+}
+/**
+ * Hostname-string blocklist. Applied BEFORE DNS resolution. These names
+ * are always private regardless of how a hostile resolver answers, so we
+ * fail fast on the literal name.
+ *
+ * Suffix matches: '*.local' (mDNS), '*.localhost' (RFC 6761), '*.localdomain'.
+ * Exact matches: 'localhost', 'localhost6', 'metadata.google.internal',
+ * 'metadata' (some Azure setups), '0' (Linux-legacy alias for 0.0.0.0).
+ */
+const BLOCKED_HOSTNAME_EXACT = new Set([
+    'localhost',
+    'localhost6',
+    'localhost.localdomain',
+    'metadata',
+    'metadata.google.internal',
+    'metadata.azure.com',
+    '0',
+    'ip6-localhost',
+    'ip6-loopback',
+]);
+const BLOCKED_HOSTNAME_SUFFIXES = [
+    '.local',
+    '.localhost',
+    '.localdomain',
+];
+function isBlockedHostname(hostname) {
+    const h = hostname.toLowerCase();
+    if (BLOCKED_HOSTNAME_EXACT.has(h))
+        return true;
+    for (const suffix of BLOCKED_HOSTNAME_SUFFIXES) {
+        if (h.endsWith(suffix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Private-range IP check. Covers both IPv4 and IPv6 ranges that an
+ * attacker might target via SSRF. Returns true if the address is private,
+ * loopback, link-local, multicast, reserved, or otherwise non-public.
+ */
+export function isPrivateIp(addr) {
+    const family = net.isIP(addr);
+    if (family === 4)
+        return isPrivateIpv4(addr);
+    if (family === 6)
+        return isPrivateIpv6(addr);
+    // Not a valid IP at all — treat as suspicious.
+    return true;
+}
+function isPrivateIpv4(addr) {
+    const parts = addr.split('.').map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255))
+        return true;
+    const [a, b] = parts;
+    // 0.0.0.0/8 — "this network"
+    if (a === 0)
+        return true;
+    // 10.0.0.0/8 — RFC1918
+    if (a === 10)
+        return true;
+    // 100.64.0.0/10 — CGNAT / shared address space (RFC 6598)
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    // 127.0.0.0/8 — loopback
+    if (a === 127)
+        return true;
+    // 169.254.0.0/16 — link-local + cloud metadata
+    if (a === 169 && b === 254)
+        return true;
+    // 172.16.0.0/12 — RFC1918 (b in [16, 31])
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16 — RFC1918
+    if (a === 192 && b === 168)
+        return true;
+    // 224.0.0.0/4 — multicast
+    if (a >= 224 && a <= 239)
+        return true;
+    // 240.0.0.0/4 — reserved
+    if (a >= 240)
+        return true;
+    return false;
+}
+function isPrivateIpv6(addr) {
+    // Normalize: lowercase, expand the most common shortcuts. Node's net.isIP
+    // has already accepted this as IPv6, so we trust the shape — we just need
+    // to check well-known private prefixes.
+    const a = addr.toLowerCase();
+    // Loopback
+    if (a === '::1')
+        return true;
+    // Unspecified
+    if (a === '::' || a === '0:0:0:0:0:0:0:0')
+        return true;
+    // IPv4-mapped IPv6 (::ffff:X.X.X.X) — check the embedded IPv4
+    const v4mapped = a.match(/^::ffff:([0-9.]+)$/);
+    if (v4mapped)
+        return isPrivateIpv4(v4mapped[1]);
+    // ::ffff:X.X.X.X (dotted-decimal form) — caught by existing regex above
+    // ::ffff:XXXX:XXXX (hex form — Node URL parser normalizes to this) — must catch here
+    const v4mappedHex = a.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (v4mappedHex) {
+        const hi = parseInt(v4mappedHex[1], 16);
+        const lo = parseInt(v4mappedHex[2], 16);
+        if (Number.isNaN(hi) || Number.isNaN(lo) || hi > 0xffff || lo > 0xffff)
+            return true;
+        const ipv4 = `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+        return isPrivateIpv4(ipv4);
+    }
+    // fc00::/7 — Unique local addresses
+    if (a.startsWith('fc') || a.startsWith('fd'))
+        return true;
+    // fe80::/10 — Link-local (fe80, fe81, ..., febf). The fourth nibble is
+    // mandatory: 'fe8:' / 'feb:' are public global unicast, not link-local.
+    if (a.match(/^fe[89ab][0-9a-f]:/))
+        return true;
+    // ff00::/8 — Multicast
+    if (a.startsWith('ff'))
+        return true;
+    return false;
+}
+const DEFAULT_DEPS = {
+    resolveAll: async (hostname) => dnsPromises.lookup(hostname, { all: true, verbatim: true }),
+};
+/**
+ * Parse, validate, and DNS-pin a URL for safe outbound fetching.
+ *
+ * Steps (each is a security boundary; failure throws):
+ *   1. Parse — throws MalformedUrlError on invalid URL string.
+ *   2. Protocol check — must be HTTPS — throws BlockedProtocolError.
+ *   3. Hostname-string blocklist — throws BlockedHostError.
+ *   4. DNS resolve (deps.resolveAll) — single round-trip, all addresses.
+ *   5. Per-address private-range check — throws BlockedHostError if any
+ *      resolved address is private, UNLESS process.env.CSPEACH_WEB_ALLOW_PRIVATE
+ *      is exactly the string 'on'.
+ *   6. Build pinnedLookup closure over the first resolved address.
+ *
+ * The deps.resolveAll injection point exists for tests; production
+ * callers pass nothing and DEFAULT_DEPS calls dnsPromises.lookup.
+ */
+export async function validateUrl(input, opts = {}) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new MalformedUrlError(input, 'invalid URL syntax');
+    }
+    if (url.protocol !== 'https:') {
+        throw new BlockedProtocolError(url.protocol);
+    }
+    const hostname = url.hostname;
+    // Strip IPv6 brackets if any — net.isIP doesn't want them, and our
+    // hostname blocklist is for textual names not bracketed IPs.
+    const cleanHost = hostname.startsWith('[') && hostname.endsWith(']')
+        ? hostname.slice(1, -1)
+        : hostname;
+    const allowPrivate = process.env.CSPEACH_WEB_ALLOW_PRIVATE === 'on';
+    // If hostname IS a literal IP, skip DNS — just check the IP directly.
+    const ipFamily = net.isIP(cleanHost);
+    if (ipFamily !== 0) {
+        if (!allowPrivate && isPrivateIp(cleanHost)) {
+            throw new BlockedHostError(cleanHost, `IP address is in a private/loopback/reserved range`);
+        }
+        return buildValidated(url, cleanHost, ipFamily);
+    }
+    // Hostname-string blocklist — applied BEFORE DNS so we never query
+    // for known-private names.
+    if (isBlockedHostname(cleanHost)) {
+        throw new BlockedHostError(cleanHost, `hostname is on the literal-name blocklist`);
+    }
+    const deps = opts.deps ?? DEFAULT_DEPS;
+    let addresses;
+    try {
+        addresses = await deps.resolveAll(cleanHost);
+    }
+    catch (err) {
+        throw new BlockedHostError(cleanHost, `DNS lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (addresses.length === 0) {
+        throw new BlockedHostError(cleanHost, 'DNS returned no addresses');
+    }
+    if (!allowPrivate) {
+        for (const a of addresses) {
+            if (isPrivateIp(a.address)) {
+                throw new BlockedHostError(cleanHost, `resolved to private address ${a.address} (any private address in the set fails the check)`);
+            }
+        }
+    }
+    return buildValidated(url, addresses[0].address, addresses[0].family);
+}
+function buildValidated(url, pinnedAddress, pinnedAddressFamily) {
+    return {
+        url,
+        pinnedAddress,
+        pinnedAddressFamily,
+        pinnedLookup: (hostname, _opts, cb) => {
+            // We don't care about opts.family / opts.hints — we already validated
+            // the address. Return it verbatim. Caller passes the hostname that
+            // matches url.hostname; if it doesn't, surface as ENOTFOUND.
+            if (hostname !== url.hostname) {
+                const e = new Error(`pinnedLookup called with hostname "${hostname}" but pinned hostname is "${url.hostname}"`);
+                e.code = 'ENOTFOUND';
+                cb(e);
+                return;
+            }
+            cb(null, pinnedAddress, pinnedAddressFamily);
+        },
+    };
+}

package/dist/tools/web/web_fetch.js

@@ -0,0 +1,257 @@
+// cspeach-cli/src/tools/web/web_fetch.ts
+/**
+ * web_fetch — Phase 3 / Chunk 3C web tool.
+ *
+ * Fetches an arbitrary HTTPS resource (SAP help pages, OSS Notes,
+ * GitHub raw content, etc.) with hardened SSRF defenses. Defers all
+ * URL / DNS / private-range validation to _web-shared.validateUrl;
+ * this file handles the network round-trip, content-type filtering,
+ * size cap, timeout, and redirect-loop control.
+ *
+ * Defaults:
+ *   - HTTPS only
+ *   - 10s wall-clock timeout per hop
+ *   - 1 MB response cap (streamed; request destroyed when threshold crossed)
+ *   - 5 redirect hops max; each hop re-runs full validateUrl
+ *   - Content-Type allowlist: text/*, application/json, application/xml
+ *   - User-Agent: cspeach/0.5 (+https://cspeach.dev)
+ *
+ * Escape hatch: CSPEACH_WEB_ALLOW_PRIVATE=on lifts the private-IP check
+ * (still HTTPS-only). Off by default.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_WEB_FETCH=on.
+ * isMutating: false — reads only.
+ */
+import * as https from 'node:https';
+import { registerTool } from '../index.js';
+import { validateUrl, BlockedHostError, BlockedProtocolError, MalformedUrlError, } from './_web-shared.js';
+export const USER_AGENT = 'cspeach/0.5 (+https://cspeach.dev)';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_REDIRECTS = 5;
+/**
+ * Content-Type prefixes we accept. The full header is matched as
+ * prefix + ';' or end-of-string so 'application/jsonblah' won't match
+ * but 'application/json; charset=utf-8' will.
+ */
+const ALLOWED_CONTENT_TYPES = [
+    'text/',
+    'application/json',
+    'application/xml',
+];
+function isAllowedContentType(header) {
+    if (!header)
+        return false;
+    const h = header.toLowerCase().trim();
+    for (const allowed of ALLOWED_CONTENT_TYPES) {
+        if (allowed.endsWith('/')) {
+            // Prefix match (text/, etc.)
+            if (h.startsWith(allowed))
+                return true;
+        }
+        else {
+            // Exact prefix followed by either ';' (params) or end-of-string
+            if (h === allowed || h.startsWith(`${allowed};`) || h.startsWith(`${allowed} `))
+                return true;
+        }
+    }
+    return false;
+}
+async function fetchOnce(validated, timeoutMs) {
+    return new Promise((resolve) => {
+        const url = validated.url;
+        let buf = '';
+        let bufBytes = 0;
+        let truncated = false;
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const req = https.request({
+            method: 'GET',
+            hostname: url.hostname,
+            port: url.port ? Number(url.port) : 443,
+            path: `${url.pathname}${url.search}`,
+            // ValidatedUrl.pinnedLookup is typed against `LookupOneOptions`
+            // (the form we need — single-address callback). Node's
+            // https.request `lookup` field is typed `LookupFunction` whose
+            // options use `LookupOptions` (`all?: boolean`). The two are
+            // structurally compatible at runtime — Node calls the lookup
+            // with whichever options object it builds and passes the result
+            // to our (err, address, family) callback. The cast bridges the
+            // type-system gap without weakening the validated guarantee.
+            lookup: validated.pinnedLookup,
+            headers: {
+                'User-Agent': USER_AGENT,
+                Accept: 'text/*, application/json, application/xml',
+                'Accept-Encoding': 'identity', // disable gzip — keeps the streaming cap accurate
+            },
+            // Reject non-2xx is not used; we surface the status to the caller.
+        }, (res) => {
+            const statusCode = res.statusCode ?? 0;
+            const headers = {};
+            for (const [k, v] of Object.entries(res.headers)) {
+                if (typeof v === 'string')
+                    headers[k] = v;
+                else if (Array.isArray(v))
+                    headers[k] = v.join(', ');
+            }
+            // Redirect — surface to caller, no body capture.
+            if (statusCode >= 300 && statusCode < 400 && headers['location']) {
+                res.destroy?.();
+                settle({ kind: 'redirect', statusCode, location: headers['location'] });
+                return;
+            }
+            // Content-Type filter — applies to 2xx responses. Error responses
+            // can be any type; we still surface a small body for the agent.
+            if (statusCode >= 200 && statusCode < 300) {
+                if (!isAllowedContentType(headers['content-type'])) {
+                    res.destroy?.();
+                    settle({
+                        kind: 'error',
+                        message: `response content-type "${headers['content-type'] ?? 'missing'}" is not in the allowlist (text/*, application/json, application/xml)`,
+                    });
+                    return;
+                }
+            }
+            // Content-Encoding guard — we sent Accept-Encoding: identity, but a
+            // misbehaving CDN may gzip anyway. toString('utf-8') on compressed
+            // bytes produces U+FFFD garbage that would poison the model's
+            // context window. Reject explicitly instead. Only meaningful for
+            // responses that carry a body (2xx); 3xx redirects are surfaced
+            // above and don't reach this point.
+            const contentEncoding = headers['content-encoding']?.toLowerCase();
+            if (contentEncoding && contentEncoding !== 'identity') {
+                res.destroy?.();
+                settle({
+                    kind: 'error',
+                    message: `server returned unsupported Content-Encoding "${headers['content-encoding']}" — only "identity" is accepted (Accept-Encoding: identity sent)`,
+                });
+                return;
+            }
+            res.on('data', (chunk) => {
+                if (truncated)
+                    return;
+                const remaining = MAX_RESPONSE_BYTES - bufBytes;
+                // Truncation paths must settle the promise NOW — Node's
+                // stream.destroy() emits 'close' but NOT 'end', so relying
+                // on the 'end' handler to settle would hang the promise
+                // until req.setTimeout fires (~10s) and surface as a
+                // spurious timeout instead of a truncated-success result.
+                // settle()'s once-guard makes the call idempotent.
+                if (remaining <= 0) {
+                    // Buffer already at cap (a prior chunk landed exactly on
+                    // the boundary) — drop this chunk entirely.
+                    truncated = true;
+                    res.destroy?.();
+                    settle({ kind: 'response', statusCode, headers, body: buf, truncated: true });
+                    return;
+                }
+                if (chunk.length <= remaining) {
+                    buf += chunk.toString('utf-8');
+                    bufBytes += chunk.length;
+                }
+                else {
+                    // This chunk pushes past the cap — keep the head, drop the tail.
+                    buf += chunk.slice(0, remaining).toString('utf-8');
+                    bufBytes += remaining;
+                    truncated = true;
+                    res.destroy?.();
+                    settle({ kind: 'response', statusCode, headers, body: buf, truncated: true });
+                }
+            });
+            res.on('end', () => {
+                settle({ kind: 'response', statusCode, headers, body: buf, truncated });
+            });
+            res.on('error', (err) => {
+                settle({ kind: 'error', message: `response stream error: ${err.message}` });
+            });
+        });
+        req.setTimeout(timeoutMs, () => {
+            settle({ kind: 'error', message: `timeout after ${timeoutMs} ms — request aborted` });
+            // Node's ClientRequest.destroy() is documented as idempotent and
+            // does not throw — no try/catch needed.
+            req.destroy();
+        });
+        req.on('error', (err) => {
+            settle({ kind: 'error', message: `request error: ${err.message}` });
+        });
+        req.end();
+    });
+}
+export async function webFetchHandler(args, _ctx, opts = {}) {
+    if (!args.url || typeof args.url !== 'string') {
+        return { content: 'error: url is required (non-empty string)', is_error: true };
+    }
+    const timeoutMs = opts._timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let currentUrl = args.url;
+    let redirects = 0;
+    for (;;) {
+        let validated;
+        try {
+            validated = await validateUrl(currentUrl, { deps: opts._deps });
+        }
+        catch (err) {
+            if (err instanceof BlockedProtocolError || err instanceof BlockedHostError || err instanceof MalformedUrlError) {
+                return { content: `error: ${err.message}`, is_error: true };
+            }
+            return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+        const hop = await fetchOnce(validated, timeoutMs);
+        if (hop.kind === 'error') {
+            return { content: `error: ${hop.message}`, is_error: true };
+        }
+        if (hop.kind === 'redirect') {
+            if (redirects >= MAX_REDIRECTS) {
+                return { content: `error: redirect limit (${MAX_REDIRECTS}) exceeded — last hop ${hop.statusCode} → ${hop.location}`, is_error: true };
+            }
+            redirects++;
+            // Resolve relative redirects against the current URL.
+            let nextUrl;
+            try {
+                nextUrl = new URL(hop.location, validated.url.toString()).toString();
+            }
+            catch {
+                return { content: `error: redirect Location header "${hop.location}" is not a valid URL`, is_error: true };
+            }
+            currentUrl = nextUrl;
+            continue;
+        }
+        // hop.kind === 'response'
+        const hdrLines = Object.entries(hop.headers)
+            .filter(([k]) => ['content-type', 'content-length', 'etag', 'last-modified', 'location'].includes(k.toLowerCase()))
+            .map(([k, v]) => `${k}: ${v}`)
+            .join('\n');
+        const trailer = hop.truncated ? `\n[truncated — exceeded ${MAX_RESPONSE_BYTES} byte cap]` : '';
+        const redirectLine = redirects > 0 ? `\nredirects: ${redirects}` : '';
+        const finalUrlLine = redirects > 0 ? `\nfinal url: ${validated.url.toString()}` : '';
+        return {
+            content: `status: ${hop.statusCode}${redirectLine}${finalUrlLine}\n${hdrLines}\n\n${hop.body}${trailer}`,
+        };
+    }
+}
+registerTool({
+    name: 'web_fetch',
+    description: 'Fetch an HTTPS URL and return its body + status + headers. HTTPS only; ' +
+        'private IPs / loopback / cloud-metadata addresses blocked (escape hatch: ' +
+        'CSPEACH_WEB_ALLOW_PRIVATE=on). 10s timeout, 1 MB response cap, up to 5 ' +
+        'redirects (each hop re-validated). Allowed content-types: text/*, ' +
+        'application/json, application/xml.',
+    isMutating: false,
+    category: 'web',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            url: {
+                type: 'string',
+                description: 'Full HTTPS URL to fetch. Must be public; private IPs / loopback / cloud-metadata addresses are refused.',
+            },
+        },
+        required: ['url'],
+    },
+    handler: (args, ctx) => webFetchHandler(args, ctx),
+});