@wrongstack/tools 0.313.0 → 0.316.1

package/dist/chunk-IXMNTNW5.js

@@ -0,0 +1,238 @@
+import {
+  ALLOW_PRIVATE,
+  assertNotPrivate,
+  guardedFetch
+} from "./chunk-NBDZMMG2.js";
+import {
+  truncateMiddle
+} from "./chunk-D33S4RQG.js";
+
+// src/fetch.ts
+import { FetchError, ToolError, ToolValidationError } from "@wrongstack/core/types";
+import TurndownService from "turndown";
+var TD = new TurndownService({
+  // Use `# Title` for headings, not setext underline style (`Title\n=====`).
+  headingStyle: "atx",
+  // Don't wrap code blocks in <pre> — render them as triple-backtick blocks.
+  codeBlockStyle: "fenced"
+});
+TD.addRule("stripDangerousElements", {
+  filter: ["script", "style", "noscript"],
+  replacement: () => ""
+});
+var PRUNED_BOILERPLATE_TAGS = /* @__PURE__ */ new Set(["nav", "header", "footer", "aside", "svg", "iframe"]);
+TD.remove((node) => PRUNED_BOILERPLATE_TAGS.has(node.nodeName.toLowerCase()));
+var MAX_BYTES = 131072;
+var TIMEOUT_MS = 2e4;
+var combineSignals = (signals) => AbortSignal.any(signals);
+var fetchTool = {
+  name: "fetch",
+  category: "Network",
+  description: "Fetch a URL and return its content. HTML pages are automatically converted to clean markdown. This tool has strong SSRF protections (private IPs, localhost, and cloud metadata endpoints are blocked by default).",
+  usageHint: "Use this when you need external information (documentation, API responses, web pages, etc.).\n\nSecurity notes:\n- Only HTTPS is allowed by default.\n- Internal/private networks are blocked unless explicitly enabled via environment variable.\n- Redirects are followed but re-validated at each hop.\n- Output is capped (128KB by default) to avoid flooding context.\nPrefer this over raw `bash curl` or `bash wget`.",
+  permission: "auto",
+  mutating: false,
+  capabilities: ["net.outbound"],
+  icon: "web",
+  // Trust rules for fetch match on the literal URL — declare it explicitly
+  // so a user can trust `https://api.example.com/*` without accidentally
+  // matching that pattern on any other tool that happens to have a `url`
+  // input field.
+  subjectKey: "url",
+  timeoutMs: TIMEOUT_MS,
+  maxOutputBytes: MAX_BYTES,
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "The target URL (must use https://)."
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "text", "raw"],
+        description: 'Output format. "markdown" is recommended for HTML pages; for non-HTML content types it falls back to plain text (JSON is pretty-printed).'
+      }
+    },
+    required: ["url"]
+  },
+  async execute(input, ctx, opts) {
+    let final;
+    const executeStream = fetchTool.executeStream;
+    if (!executeStream) {
+      throw new ToolError({
+        message: "fetchTool: stream execution unavailable",
+        code: "TOOL_EXECUTION_FAILED",
+        toolName: "fetch"
+      });
+    }
+    for await (const ev of executeStream(input, ctx, opts)) {
+      if (ev.type === "final") final = ev.output;
+    }
+    if (!final) {
+      throw new ToolError({
+        message: "fetch: stream ended without final event",
+        code: "TOOL_EXECUTION_FAILED",
+        toolName: "fetch"
+      });
+    }
+    return final;
+  },
+  async *executeStream(input, ctx, opts) {
+    if (!input?.url) {
+      throw new ToolValidationError({
+        message: "fetch: url is required",
+        field: "url"
+      });
+    }
+    const u = new URL(input.url);
+    if (u.username || u.password) {
+      throw new ToolValidationError({
+        message: "fetch: URLs with embedded credentials (user:pass@host) are not allowed",
+        field: "url"
+      });
+    }
+    if (u.protocol !== "https:" && u.protocol !== "http:") {
+      throw new ToolValidationError({
+        message: `fetch: unsupported protocol "${u.protocol}"`,
+        field: "url"
+      });
+    }
+    if (u.protocol === "http:" && !ALLOW_PRIVATE) {
+      throw new ToolValidationError({
+        message: "fetch: http:// blocked (HTTPS required by default)",
+        field: "url"
+      });
+    }
+    await assertNotPrivate(u.hostname);
+    yield { type: "log", text: `GET ${input.url}` };
+    const ctrl = new AbortController();
+    const timer = setTimeout(
+      () => ctrl.abort(
+        new ToolError({
+          message: "fetch timeout",
+          code: "TOOL_TIMEOUT",
+          toolName: "fetch"
+        })
+      ),
+      TIMEOUT_MS
+    );
+    const combined = combineSignals([opts.signal, ctrl.signal]);
+    try {
+      let res;
+      try {
+        res = await guardedFetch(input.url, 5, combined);
+      } catch (err) {
+        if (opts.signal.aborted) throw err;
+        throw describeFetchError(err, input.url, ctrl.signal.aborted);
+      }
+      const ct = res.headers.get("content-type") ?? "application/octet-stream";
+      if (/^image\/|^audio\/|^video\/|application\/octet-stream/.test(ct)) {
+        throw new FetchError({
+          message: `fetch: refusing to read binary content-type "${ct}"`,
+          status: res.status,
+          context: { url: res.url, contentType: ct }
+        });
+      }
+      yield {
+        type: "log",
+        text: `HTTP ${res.status} ${ct}`,
+        data: { status: res.status, contentType: ct }
+      };
+      const reader = res.body?.getReader();
+      let received = 0;
+      const chunks = [];
+      let pendingBytes = 0;
+      const FLUSH_AT = 4 * 1024;
+      if (reader) {
+        for (; ; ) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (!value) continue;
+          received += value.byteLength;
+          pendingBytes += value.byteLength;
+          chunks.push(value);
+          if (pendingBytes >= FLUSH_AT) {
+            const recent = Buffer.from(value).toString("utf-8");
+            yield {
+              type: "partial_output",
+              text: recent,
+              data: { received }
+            };
+            pendingBytes = 0;
+          }
+          if (received > MAX_BYTES) break;
+        }
+      }
+      const text = Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8");
+      const format = input.format ?? (ct.includes("text/html") ? "markdown" : "text");
+      let content;
+      if (format === "raw") content = text;
+      else if (format === "markdown" && ct.includes("text/html")) content = TD.turndown(text);
+      else if (ct.includes("application/json")) content = prettyJson(text);
+      else content = text;
+      yield {
+        type: "final",
+        output: {
+          content: truncateMiddle(content, MAX_BYTES),
+          status: res.status,
+          content_type: ct,
+          url: res.url
+        }
+      };
+      ctx.recordSideEffect?.({
+        toolUseId: `fetch-${Date.now()}`,
+        toolName: "fetch",
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        input: { url: input.url, format: input.format },
+        outcome: `HTTP ${res.status} (${ct})`,
+        risk: "network"
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function describeFetchError(err, url, timedOut) {
+  if (timedOut) {
+    return new ToolError({
+      message: `fetch: GET ${url} timed out after ${TIMEOUT_MS}ms`,
+      code: "TOOL_TIMEOUT",
+      toolName: "fetch",
+      context: { url, timedOut: true, timeoutMs: TIMEOUT_MS },
+      cause: err
+    });
+  }
+  const parts = [];
+  const seen = /* @__PURE__ */ new Set();
+  let cur = err;
+  while (cur instanceof Error && !seen.has(cur)) {
+    seen.add(cur);
+    const code = cur.code;
+    const label = code ? `${code}: ${cur.message}` : cur.message;
+    if (label && label !== "fetch failed" && !parts.includes(label)) parts.push(label);
+    cur = cur.cause;
+  }
+  const detail = parts.length > 0 ? parts.join(" \u2192 ") : "fetch failed";
+  return new FetchError({
+    message: `fetch: GET ${url} failed \u2014 ${detail}`,
+    status: 502,
+    context: { url, timedOut: false, transportErrors: parts },
+    // Preserve the original undici / DNS / TLS chain so callers can inspect
+    // it via `err.cause` and structured `instanceof` checks. The flattened
+    // text version stays in the message for human readability.
+    cause: err
+  });
+}
+function prettyJson(s) {
+  try {
+    return JSON.stringify(JSON.parse(s), null, 2);
+  } catch {
+    return s;
+  }
+}
+
+export {
+  fetchTool
+};
+//# sourceMappingURL=chunk-IXMNTNW5.js.map