@tachu/extensions 1.0.0-beta.1 → 1.0.0-rc.0

package/dist/tools/web-fetch/descriptor.md

@@ -0,0 +1,198 @@
+---
+kind: tool
+id: web-fetch
+name: web-fetch
+version: "0.1.0"
+category: "web"
+dangerous: true
+description: |
+  通过 @tachu/web-fetch-server 远程渲染并结构化抓取 URL：服务端以 Bun.fetch（静态）或 Playwright（浏览器）拉取页面，经 Readability/Turndown 等管线输出标题、正文与可选链接/图片/JSON-LD；`renderMode` 为 auto 时可在静态不足时自动升级到浏览器重试一次。
+sideEffect: readonly
+idempotent: false
+requiresApproval: true
+timeout: 120000
+inputSchema:
+  type: object
+  properties:
+    url:
+      type: string
+      description: 目标 http(s) URL（协议层唯一必填；将发往服务端并由 SSRF 规则校验）
+    renderMode:
+      type: string
+      enum: [static, browser, auto]
+      description: 渲染模式；默认 auto（先 static，不满足条件时浏览器重试一次）
+    waitFor:
+      description: |
+        仅 browser 模式：等待策略。可为 load / domcontentloaded / networkidle，
+        或 { "selector": "<css>" } 等待元素可见，或 { "timeMs": <number> } 固定等待。
+      oneOf:
+        - type: string
+          enum: [load, domcontentloaded, networkidle]
+        - type: object
+          required: [selector]
+          properties:
+            selector:
+              type: string
+        - type: object
+          required: [timeMs]
+          properties:
+            timeMs:
+              type: number
+    waitTimeoutMs:
+      type: number
+      description: 渲染等待超时（毫秒）；默认 15000，硬上限 60000
+    scroll:
+      description: |
+        仅 browser：是否滚动以触发懒加载。false | true |
+        { "steps": number, "delayMs": number }
+      oneOf:
+        - type: boolean
+        - type: object
+          required: [steps, delayMs]
+          properties:
+            steps:
+              type: number
+            delayMs:
+              type: number
+    userAgent:
+      type: string
+      description: 覆盖 User-Agent；请求中可省略或显式传 null 以使用服务端 UA 池
+    extraHeaders:
+      type: object
+      additionalProperties:
+        type: string
+      description: 额外 HTTP 头；静态模式直传；浏览器模式作为 route 注入
+    cookies:
+      type: array
+      description: 注入 Cookie 列表（仅 browser 模式生效；元素形状由服务端解析）
+      items:
+        type: object
+        additionalProperties: true
+    blockResources:
+      type: array
+      description: |
+        仅 browser：资源拦截类型。未传时服务端默认 ["image","font","media"]；传 [] 表示不拦截。
+      items:
+        type: string
+        enum: [image, font, media, stylesheet, other]
+    stealth:
+      type: boolean
+      description: 可省略或传 null 继承服务级；传 true/false 为请求级覆盖
+    outputFormat:
+      type: string
+      enum: [markdown, text, html, structured]
+      description: 正文形态；markdown 为默认 GFM
+    includeLinks:
+      type: boolean
+      description: 是否在输出中包含 links[]
+    includeImages:
+      type: boolean
+      description: 是否在输出中包含 images[]
+    includeStructured:
+      type: boolean
+      description: 是否包含 JSON-LD structured 字段
+    maxBodyChars:
+      type: number
+      description: body 字符上限；默认 32768，硬上限 524288
+    traceId:
+      type: string
+      description: 可选追踪 ID；省略或 null 时由服务端生成
+  required: [url]
+outputSchema:
+  type: object
+  description: 对应 POST /v1/extract 200 响应（字段随选项省略）
+  properties:
+    url:
+      type: string
+    finalUrl:
+      type: string
+    status:
+      type: number
+    renderedWith:
+      type: string
+      enum: [static, browser]
+    renderedAtMs:
+      type: number
+    title:
+      type: string
+    description:
+      type: string
+    siteName:
+      type: string
+    lang:
+      type: string
+    byline:
+      type: string
+    publishedTime:
+      type: string
+    body:
+      type: string
+    wordCount:
+      type: number
+    truncated:
+      type: boolean
+    links:
+      type: array
+    images:
+      type: array
+    structured:
+      type: object
+      additionalProperties: true
+    warnings:
+      type: array
+      items:
+        type: string
+    traceId:
+      type: string
+execute: web-fetch
+---
+
+## 常用字段说明
+
+协议上仅 **`url`** 必填。实际调用中常与其他字段组合使用，例如：
+
+- **`renderMode`**：静态站用 `static` 省资源，强 JS 页用 `browser` 或默认 `auto`
+- **`outputFormat`**：需要 Markdown 摘要时用 `markdown`（默认），只要纯文本用 `text`
+- **`waitTimeoutMs` / `waitFor`**：浏览器渲染时的超时与就绪条件
+- **`maxBodyChars`**：控制返回给模型的正文长度，避免上下文爆炸
+- **`includeLinks` / `includeImages` / `includeStructured`**：按需打开结构化附属字段
+
+## 输出结构示例（200 成功，节选）
+
+```json
+{
+  "url": "https://example.com/article",
+  "finalUrl": "https://example.com/article",
+  "status": 200,
+  "renderedWith": "browser",
+  "renderedAtMs": 234,
+  "title": "示例文章",
+  "description": "页面 meta 描述",
+  "siteName": "Example",
+  "lang": "zh",
+  "byline": null,
+  "publishedTime": "2026-04-20T00:00:00.000Z",
+  "body": "# 示例文章\n\n正文 Markdown …",
+  "wordCount": 1234,
+  "truncated": false,
+  "links": [{ "text": "下一页", "href": "https://example.com/next" }],
+  "images": [],
+  "structured": null,
+  "warnings": [],
+  "traceId": "req_01HY..."
+}
+```
+
+## 安全提示
+
+1. **客户端须配置 Web Fetch Server 的 endpoint 与鉴权**：工具通过 HTTP 调用服务端；需正确设置服务地址与 `Authorization: Bearer <token>` 所用 token（与部署环境一致）。未配置 token 时服务端仅允许绑定本机回环，运维需按环境变量与网络策略部署。
+2. **URL 会经服务端 SSRF 校验**：私网、元数据地址、黑名单域名等会被拒绝（如 `SSRF_BLOCKED` / `DOMAIN_NOT_ALLOWED`）；请勿将本工具用于探测内网。
+3. **robots.txt 与爬取礼仪**：是否遵守 robots 及额外策略由 **服务端实现与配置** 决定，本工具不在客户端重复裁决。
+
+## 与 `fetch-url` 的区别
+
+| 维度 | `web-fetch` | `fetch-url` |
+| --- | --- | --- |
+| 数据形态 | 结构化正文（标题、Markdown/文本/HTML、可选链接与 JSON-LD） | 原始响应体 + 简单 HTML 清洗 |
+| 依赖 | 需要可用的 `@tachu/web-fetch-server` | 仅需受控直连，无需独立 fetch 服务 |
+| 渲染 | 支持静态与浏览器渲染管线 | 单次 HTTP，无浏览器渲染 |

package/dist/tools/web-fetch/errors.d.ts

@@ -0,0 +1,32 @@
+import type { ErrorResponseBody, WebFetchErrorCode } from "./types";
+/**
+ * 客户端在解析失败或网络层错误时使用的扩展码（契约 §3 行为要求；不在纯 HTTP 错误体中出现）。
+ */
+export type WebFetchClientOnlyErrorCode = "MALFORMED_RESPONSE" | "NETWORK_ERROR";
+export type WebFetchClientErrorCode = WebFetchErrorCode | WebFetchClientOnlyErrorCode;
+/**
+ * `web-fetch` / `web-search` 工具在客户端抛出的统一错误类型。
+ *
+ * @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §4
+ */
+export declare class WebFetchClientError extends Error {
+    readonly code: WebFetchClientErrorCode;
+    readonly userMessage: string;
+    readonly detail?: unknown | undefined;
+    readonly name = "WebFetchClientError";
+    constructor(code: WebFetchClientErrorCode, userMessage: string, detail?: unknown | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 将服务端错误响应映射为 {@link WebFetchClientError}。
+ *
+ * @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §4.2
+ */
+export declare function mapServerErrorToClient(httpStatus: number, body: ErrorResponseBody | null, ctx: {
+    endpoint: string;
+}): WebFetchClientError;
+export declare function getMalformedResponseError(): WebFetchClientError;
+export declare function getNetworkError(endpoint: string, originalError: unknown): WebFetchClientError;
+export declare function getTimeoutError(timeoutMs: number): WebFetchClientError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/tools/web-fetch/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,GAAG,eAAe,CAAC;AAEjF,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,2BAA2B,CAAC;AAEtF;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAI1B,IAAI,EAAE,uBAAuB;aAC7B,WAAW,EAAE,MAAM;aACnB,MAAM,CAAC,EAAE,OAAO;IALlC,QAAQ,CAAC,IAAI,yBAAyB;gBAGpB,IAAI,EAAE,uBAAuB,EAC7B,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,OAAO,YAAA,EAChC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;AAkDD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,iBAAiB,GAAG,IAAI,EAC9B,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxB,mBAAmB,CAUrB;AAED,wBAAgB,yBAAyB,IAAI,mBAAmB,CAM/D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,mBAAmB,CAO7F;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAMtE"}

package/dist/tools/web-fetch/errors.js

@@ -0,0 +1,91 @@
+/**
+ * `web-fetch` / `web-search` 工具在客户端抛出的统一错误类型。
+ *
+ * @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §4
+ */
+export class WebFetchClientError extends Error {
+    code;
+    userMessage;
+    detail;
+    name = "WebFetchClientError";
+    constructor(code, userMessage, detail, options) {
+        super(userMessage, options);
+        this.code = code;
+        this.userMessage = userMessage;
+        this.detail = detail;
+    }
+}
+/** @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §5 */
+const HTTP_STATUS_TO_CODE = {
+    400: "INVALID_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "INVALID_REQUEST",
+    408: "REQUEST_TIMEOUT",
+    413: "REQUEST_TOO_LARGE",
+    422: "RENDER_FAILED",
+    429: "RATE_LIMITED",
+    500: "INTERNAL_ERROR",
+    502: "UPSTREAM_ERROR",
+    503: "BROWSER_POOL_EXHAUSTED",
+    504: "PROVIDER_TIMEOUT",
+};
+function inferCodeFromStatus(httpStatus) {
+    return HTTP_STATUS_TO_CODE[httpStatus] ?? "INTERNAL_ERROR";
+}
+const USER_MESSAGE_ZH = {
+    INVALID_REQUEST: "请求格式无效。请检查参数后重试。",
+    INVALID_URL: "URL 无效。请使用合法的 http/https 地址。",
+    UNAUTHORIZED: "鉴权失败。请检查 Web Fetch 服务的访问令牌配置。",
+    FORBIDDEN: "访问被拒绝。请确认令牌与权限配置是否正确。",
+    SSRF_BLOCKED: "出于安全策略，无法访问该地址。请仅使用允许的公网 URL。",
+    DOMAIN_NOT_ALLOWED: "域名不在允许列表中。请调整白名单或更换 URL。",
+    REQUEST_TIMEOUT: "请求处理超时。请稍后重试，或尝试缩短等待时间。",
+    REQUEST_TOO_LARGE: "请求体过大。请减小提交内容后重试。",
+    RESPONSE_TOO_LARGE: "目标页面响应过大。请尝试降低正文长度上限或更换页面。",
+    RENDER_FAILED: "页面渲染失败。可尝试更换渲染模式或稍后重试。",
+    RATE_LIMITED: "触发限流。请稍后再试或降低请求频率。",
+    INTERNAL_ERROR: "服务端出现内部错误。请稍后重试或联系管理员。",
+    UPSTREAM_ERROR: "上游站点返回异常。请稍后重试。",
+    BROWSER_POOL_EXHAUSTED: "浏览器资源繁忙。请降低并发或稍后重试。",
+    BROWSER_CRASHED: "浏览器进程异常。请立即重试，通常可以恢复。",
+    PROVIDER_NOT_CONFIGURED: "搜索提供方未配置。请检查搜索相关环境变量。",
+    PROVIDER_UPSTREAM_ERROR: "搜索提供方返回异常。请稍后重试。",
+    PROVIDER_TIMEOUT: "搜索提供方调用超时。请稍后重试。",
+    TIMEOUT_WEB_FETCH: "网页抓取超时。请缩短正文长度上限或更换 URL 后重试。",
+    TIMEOUT_WEB_SEARCH: "搜索超时。请缩短查询或减少抓取条数后重试。",
+    WEB_FETCH_SERVER_UNREACHABLE: "渲染服务不可达。请检查网络或服务端状态。",
+    WEB_FETCH_ENDPOINT_NOT_CONFIGURED: "未能连接到 Web Fetch 服务。请先启动渲染服务，或通过 TACHU_WEB_FETCH_ENDPOINT 配置远端地址。",
+    MALFORMED_RESPONSE: "服务返回了无法解析的响应。请检查服务端版本或稍后重试。",
+    NETWORK_ERROR: "网络请求失败。请检查网络连接与服务是否可用。",
+};
+/**
+ * 将服务端错误响应映射为 {@link WebFetchClientError}。
+ *
+ * @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §4.2
+ */
+export function mapServerErrorToClient(httpStatus, body, ctx) {
+    const code = body?.error.code ?? inferCodeFromStatus(httpStatus);
+    const userMessage = USER_MESSAGE_ZH[code] ?? body?.error.message ?? USER_MESSAGE_ZH.INTERNAL_ERROR;
+    const detail = {
+        ...(body?.error.detail ?? {}),
+        httpStatus,
+        endpoint: ctx.endpoint,
+        requestId: body?.error.requestId,
+    };
+    return new WebFetchClientError(code, userMessage, detail);
+}
+export function getMalformedResponseError() {
+    return new WebFetchClientError("MALFORMED_RESPONSE", USER_MESSAGE_ZH.MALFORMED_RESPONSE, undefined);
+}
+export function getNetworkError(endpoint, originalError) {
+    const original = originalError instanceof Error ? originalError.message : String(originalError);
+    return new WebFetchClientError("NETWORK_ERROR", USER_MESSAGE_ZH.NETWORK_ERROR, {
+        endpoint,
+        originalError: original,
+    }, { cause: originalError instanceof Error ? originalError : undefined });
+}
+export function getTimeoutError(timeoutMs) {
+    return new WebFetchClientError("REQUEST_TIMEOUT", USER_MESSAGE_ZH.REQUEST_TIMEOUT, { timeoutMs, phase: "fetch" });
+}
+//# sourceMappingURL=errors.js.map

package/dist/tools/web-fetch/errors.js.map

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

package/dist/tools/web-fetch/executor.d.ts

@@ -0,0 +1,10 @@
+import type { WebFetchToolInput, WebFetchToolOutput } from "./types";
+import type { ToolExecutionContext } from "../shared";
+/**
+ * 调用 Web Fetch Server `/v1/extract`，返回正文与元数据。
+ *
+ * @see packages/web-fetch-server/src/0003c-web-fetch-config.md §5.1
+ * @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §4
+ */
+export declare function executeWebFetch(input: WebFetchToolInput, ctx: ToolExecutionContext): Promise<WebFetchToolOutput>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/tools/web-fetch/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/executor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAsD,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACzH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAuHtD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,iBAAiB,EACxB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAmD7B"}

package/dist/tools/web-fetch/executor.js

@@ -0,0 +1,191 @@
+import { getMalformedResponseError, getNetworkError, getTimeoutError, mapServerErrorToClient, } from "./errors";
+import { assertNotAborted } from "../shared";
+let warnedMissingEndpoint = false;
+function getEndpointBase() {
+    const raw = process.env.TACHU_WEB_FETCH_ENDPOINT?.trim();
+    if (!raw) {
+        if (!warnedMissingEndpoint) {
+            warnedMissingEndpoint = true;
+            console.warn("[@tachu/extensions/web-fetch] TACHU_WEB_FETCH_ENDPOINT is not set; using default http://127.0.0.1:8787");
+        }
+        return "http://127.0.0.1:8787";
+    }
+    return raw.replace(/\/$/, "");
+}
+function readClientTimeoutMs(input) {
+    if (input.timeoutMs != null)
+        return input.timeoutMs;
+    const raw = process.env.TACHU_WEB_FETCH_TIMEOUT_MS?.trim();
+    if (!raw)
+        return 70000;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : 70000;
+}
+function toExtractRequest(input) {
+    const { timeoutMs: _timeoutMs, ...rest } = input;
+    return {
+        ...rest,
+        traceId: null,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isExtractResponse(value) {
+    if (!isRecord(value))
+        return false;
+    const keys = [
+        "url",
+        "finalUrl",
+        "status",
+        "renderedWith",
+        "renderedAtMs",
+        "body",
+        "wordCount",
+        "truncated",
+        "warnings",
+        "traceId",
+    ];
+    for (const k of keys) {
+        if (!(k in value))
+            return false;
+    }
+    if (typeof value.url !== "string")
+        return false;
+    if (typeof value.finalUrl !== "string")
+        return false;
+    if (typeof value.status !== "number")
+        return false;
+    if (value.renderedWith !== "static" && value.renderedWith !== "browser")
+        return false;
+    if (typeof value.renderedAtMs !== "number")
+        return false;
+    if (typeof value.body !== "string")
+        return false;
+    if (typeof value.wordCount !== "number")
+        return false;
+    if (typeof value.truncated !== "boolean")
+        return false;
+    if (!Array.isArray(value.warnings))
+        return false;
+    if (typeof value.traceId !== "string")
+        return false;
+    return true;
+}
+function toToolOutput(res) {
+    const out = {
+        url: res.url,
+        finalUrl: res.finalUrl,
+        status: res.status,
+        renderedWith: res.renderedWith,
+        body: res.body,
+        wordCount: res.wordCount,
+        truncated: res.truncated,
+        warnings: res.warnings,
+    };
+    if (res.title !== undefined)
+        out.title = res.title;
+    if (res.description !== undefined)
+        out.description = res.description;
+    if (res.siteName !== undefined)
+        out.siteName = res.siteName;
+    if (res.lang !== undefined)
+        out.lang = res.lang;
+    if (res.byline !== undefined)
+        out.byline = res.byline;
+    if (res.publishedTime !== undefined)
+        out.publishedTime = res.publishedTime;
+    if (res.links !== undefined) {
+        out.links = res.links.map((l) => ({ text: l.text, href: l.href }));
+    }
+    if (res.images !== undefined) {
+        out.images = res.images.map((im) => ({ alt: im.alt, src: im.src }));
+    }
+    if (res.structured !== undefined)
+        out.structured = res.structured;
+    return out;
+}
+function tryParseErrorBody(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed))
+            return null;
+        const err = parsed.error;
+        if (!isRecord(err))
+            return null;
+        if (typeof err.code !== "string")
+            return null;
+        if (typeof err.message !== "string")
+            return null;
+        if (typeof err.requestId !== "string")
+            return null;
+        const body = {
+            error: {
+                code: err.code,
+                message: err.message,
+                requestId: err.requestId,
+                ...(isRecord(err.detail) ? { detail: err.detail } : {}),
+            },
+        };
+        return body;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 调用 Web Fetch Server `/v1/extract`，返回正文与元数据。
+ *
+ * @see packages/web-fetch-server/src/0003c-web-fetch-config.md §5.1
+ * @see packages/web-fetch-server/src/0003d-web-fetch-errors.md §4
+ */
+export async function executeWebFetch(input, ctx) {
+    assertNotAborted(ctx.abortSignal);
+    const endpoint = getEndpointBase();
+    const url = `${endpoint}/v1/extract`;
+    const timeoutMs = readClientTimeoutMs(input);
+    const signal = AbortSignal.any([AbortSignal.timeout(timeoutMs), ctx.abortSignal]);
+    const headers = {
+        "Content-Type": "application/json; charset=utf-8",
+    };
+    const token = process.env.TACHU_WEB_FETCH_TOKEN?.trim();
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    let response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(toExtractRequest(input)),
+            signal,
+        });
+    }
+    catch (e) {
+        if (e instanceof Error && e.name === "AbortError") {
+            if (ctx.abortSignal.aborted) {
+                throw ctx.abortSignal.reason ?? e;
+            }
+            throw getTimeoutError(timeoutMs);
+        }
+        throw getNetworkError(endpoint, e);
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        const parsed = tryParseErrorBody(text);
+        throw mapServerErrorToClient(response.status, parsed, { endpoint });
+    }
+    const text = await response.text();
+    let parsedBody;
+    try {
+        parsedBody = JSON.parse(text);
+    }
+    catch {
+        throw getMalformedResponseError();
+    }
+    if (!isExtractResponse(parsedBody)) {
+        throw getMalformedResponseError();
+    }
+    return toToolOutput(parsedBody);
+}
+//# sourceMappingURL=executor.js.map

package/dist/tools/web-fetch/executor.js.map

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

package/dist/tools/web-fetch/index.d.ts

@@ -0,0 +1,4 @@
+export { executeWebFetch } from "./executor";
+export { WebFetchClientError, type WebFetchClientErrorCode, type WebFetchClientOnlyErrorCode, } from "./errors";
+export type { CookieInit, ErrorResponseBody, ExtractRequest, ExtractResponse, ImageRef, LinkRef, OutputFormat, RenderMode, ResourceType, ScrollStrategy, WaitStrategy, WebFetchErrorCode, WebFetchToolInput, WebFetchToolOutput, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/web-fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,GACjC,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/tools/web-fetch/index.js

@@ -0,0 +1,3 @@
+export { executeWebFetch } from "./executor";
+export { WebFetchClientError, } from "./errors";
+//# sourceMappingURL=index.js.map

package/dist/tools/web-fetch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/web-fetch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,mBAAmB,GAGpB,MAAM,UAAU,CAAC"}