@oyasmi/pipiclaw 0.5.8 → 0.6.0

package/dist/tools/config.js

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { APP_HOME_DIR, TOOLS_CONFIG_PATH } from "../paths.js";
+import { isRecord } from "../shared/type-guards.js";
+const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "jina", "searxng", "duckduckgo"];
+export const DEFAULT_TOOLS_CONFIG = {
+    tools: {
+        web: {
+            enable: false,
+            proxy: null,
+            search: {
+                provider: "brave",
+                apiKey: "",
+                baseUrl: "",
+                maxResults: 5,
+                timeoutMs: 30_000,
+            },
+            fetch: {
+                maxChars: 50_000,
+                timeoutMs: 30_000,
+                maxImageBytes: 10 * 1024 * 1024,
+                maxResponseBytes: 5 * 1024 * 1024,
+                preferJina: false,
+                enableJinaFallback: false,
+                defaultExtractMode: "markdown",
+            },
+        },
+    },
+};
+function clampInteger(value, fallback, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    if (normalized < minimum) {
+        return fallback;
+    }
+    if (maximum !== undefined && normalized > maximum) {
+        return fallback;
+    }
+    return normalized;
+}
+function asTrimmedString(value, fallback = "") {
+    return typeof value === "string" ? value.trim() : fallback;
+}
+function asOptionalProxy(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function pushInvalidValueDiagnostic(diagnostics, configPath, field, message) {
+    diagnostics.push({
+        source: "tools",
+        path: configPath,
+        severity: "warning",
+        message: `${field}: ${message}`,
+    });
+}
+function mergeToolsConfig(source, configPath, diagnostics) {
+    if (!isRecord(source)) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "root", "expected a JSON object; using defaults");
+        return DEFAULT_TOOLS_CONFIG;
+    }
+    const tools = isRecord(source.tools) ? source.tools : {};
+    const web = isRecord(tools.web) ? tools.web : {};
+    const search = isRecord(web.search) ? web.search : {};
+    const fetch = isRecord(web.fetch) ? web.fetch : {};
+    const providerValue = asTrimmedString(search.provider, DEFAULT_TOOLS_CONFIG.tools.web.search.provider).toLowerCase();
+    const provider = WEB_SEARCH_PROVIDERS.includes(providerValue)
+        ? providerValue
+        : (() => {
+            if (search.provider !== undefined) {
+                pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.search.provider", `unknown provider "${String(search.provider)}"; using ${DEFAULT_TOOLS_CONFIG.tools.web.search.provider}`);
+            }
+            return DEFAULT_TOOLS_CONFIG.tools.web.search.provider;
+        })();
+    const defaultExtractMode = asTrimmedString(fetch.defaultExtractMode, DEFAULT_TOOLS_CONFIG.tools.web.fetch.defaultExtractMode);
+    if (web.proxy !== undefined && web.proxy !== null && typeof web.proxy !== "string") {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.proxy", "expected a string or null; using null");
+    }
+    if (search.maxResults !== undefined && clampInteger(search.maxResults, -1, 1, 10) === -1) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.search.maxResults", "expected an integer between 1 and 10; using default");
+    }
+    if (search.timeoutMs !== undefined && clampInteger(search.timeoutMs, -1, 1) === -1) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.search.timeoutMs", "expected a positive integer; using default");
+    }
+    if (fetch.maxChars !== undefined && clampInteger(fetch.maxChars, -1, 100) === -1) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.fetch.maxChars", "expected an integer >= 100; using default");
+    }
+    if (fetch.timeoutMs !== undefined && clampInteger(fetch.timeoutMs, -1, 1) === -1) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.fetch.timeoutMs", "expected a positive integer; using default");
+    }
+    if (fetch.maxImageBytes !== undefined && clampInteger(fetch.maxImageBytes, -1, 1) === -1) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.fetch.maxImageBytes", "expected a positive integer; using default");
+    }
+    if (fetch.maxResponseBytes !== undefined && clampInteger(fetch.maxResponseBytes, -1, 1) === -1) {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.fetch.maxResponseBytes", "expected a positive integer; using default");
+    }
+    if (fetch.defaultExtractMode !== undefined && defaultExtractMode !== "text" && defaultExtractMode !== "markdown") {
+        pushInvalidValueDiagnostic(diagnostics, configPath, "tools.web.fetch.defaultExtractMode", `expected "markdown" or "text"; using ${DEFAULT_TOOLS_CONFIG.tools.web.fetch.defaultExtractMode}`);
+    }
+    return {
+        tools: {
+            web: {
+                enable: typeof web.enable === "boolean" ? web.enable : DEFAULT_TOOLS_CONFIG.tools.web.enable,
+                proxy: asOptionalProxy(web.proxy),
+                search: {
+                    provider,
+                    apiKey: asTrimmedString(search.apiKey),
+                    baseUrl: asTrimmedString(search.baseUrl),
+                    maxResults: clampInteger(search.maxResults, DEFAULT_TOOLS_CONFIG.tools.web.search.maxResults, 1, 10),
+                    timeoutMs: clampInteger(search.timeoutMs, DEFAULT_TOOLS_CONFIG.tools.web.search.timeoutMs, 1),
+                },
+                fetch: {
+                    maxChars: clampInteger(fetch.maxChars, DEFAULT_TOOLS_CONFIG.tools.web.fetch.maxChars, 100),
+                    timeoutMs: clampInteger(fetch.timeoutMs, DEFAULT_TOOLS_CONFIG.tools.web.fetch.timeoutMs, 1),
+                    maxImageBytes: clampInteger(fetch.maxImageBytes, DEFAULT_TOOLS_CONFIG.tools.web.fetch.maxImageBytes, 1),
+                    maxResponseBytes: clampInteger(fetch.maxResponseBytes, DEFAULT_TOOLS_CONFIG.tools.web.fetch.maxResponseBytes, 1),
+                    preferJina: typeof fetch.preferJina === "boolean"
+                        ? fetch.preferJina
+                        : DEFAULT_TOOLS_CONFIG.tools.web.fetch.preferJina,
+                    enableJinaFallback: typeof fetch.enableJinaFallback === "boolean"
+                        ? fetch.enableJinaFallback
+                        : DEFAULT_TOOLS_CONFIG.tools.web.fetch.enableJinaFallback,
+                    defaultExtractMode: defaultExtractMode === "text" || defaultExtractMode === "markdown"
+                        ? defaultExtractMode
+                        : DEFAULT_TOOLS_CONFIG.tools.web.fetch.defaultExtractMode,
+                },
+            },
+        },
+    };
+}
+export function getToolsConfigPath(appHomeDir = APP_HOME_DIR) {
+    return appHomeDir === APP_HOME_DIR ? TOOLS_CONFIG_PATH : join(appHomeDir, "tools.json");
+}
+export function loadToolsConfigWithDiagnostics(appHomeDir = APP_HOME_DIR) {
+    const configPath = getToolsConfigPath(appHomeDir);
+    if (!existsSync(configPath)) {
+        return { config: DEFAULT_TOOLS_CONFIG, diagnostics: [] };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        const diagnostics = [];
+        return {
+            config: mergeToolsConfig(raw, configPath, diagnostics),
+            diagnostics,
+        };
+    }
+    catch (error) {
+        return {
+            config: DEFAULT_TOOLS_CONFIG,
+            diagnostics: [
+                {
+                    source: "tools",
+                    path: configPath,
+                    severity: "error",
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            ],
+        };
+    }
+}
+export function loadToolsConfig(appHomeDir = APP_HOME_DIR) {
+    return loadToolsConfigWithDiagnostics(appHomeDir).config;
+}

package/dist/tools/index.d.ts

@@ -4,6 +4,7 @@ import type { Executor, SandboxConfig } from "../sandbox.js";
 import type { SecurityConfig, SecurityRuntimeContext } from "../security/types.js";
 import type { PipiclawMemoryRecallSettings } from "../settings.js";
 import type { SubAgentDiscoveryResult } from "../subagents/discovery.js";
+import type { PipiclawToolsConfig } from "./config.js";
 export interface CreatePipiclawToolsOptions {
     executor: Executor;
     getCurrentModel: () => Model<Api>;
@@ -16,6 +17,8 @@ export interface CreatePipiclawToolsOptions {
     sandboxConfig: SandboxConfig;
     getSubAgentDiscovery: () => SubAgentDiscoveryResult;
     getMemoryRecallSettings: () => PipiclawMemoryRecallSettings;
+    securityConfig?: SecurityConfig;
+    toolsConfig?: PipiclawToolsConfig;
 }
 export interface CreatePipiclawBaseToolsOptions {
     securityConfig?: SecurityConfig;

package/dist/tools/index.js

@@ -2,8 +2,11 @@ import { APP_HOME_DIR } from "../paths.js";
 import { loadSecurityConfig } from "../security/config.js";
 import { createSubAgentTool } from "../subagents/tool.js";
 import { createBashTool } from "./bash.js";
+import { loadToolsConfig } from "./config.js";
 import { createEditTool } from "./edit.js";
 import { createReadTool } from "./read.js";
+import { createWebFetchTool } from "./web-fetch.js";
+import { createWebSearchTool } from "./web-search.js";
 import { createWriteTool } from "./write.js";
 export function createPipiclawBaseTools(executor, options = {}) {
     const hasSecurityOptions = options.securityConfig || options.securityContext || options.channelId;
@@ -22,7 +25,8 @@ export function createPipiclawBaseTools(executor, options = {}) {
     ];
 }
 export function createPipiclawTools(options) {
-    const securityConfig = loadSecurityConfig(APP_HOME_DIR);
+    const securityConfig = options.securityConfig ?? loadSecurityConfig(APP_HOME_DIR);
+    const toolsConfig = options.toolsConfig ?? loadToolsConfig(APP_HOME_DIR);
     const securityContext = {
         workspaceDir: options.workspaceDir,
         workspacePath: options.workspacePath,
@@ -33,8 +37,25 @@ export function createPipiclawTools(options) {
         securityContext,
         channelId: options.channelId,
     });
+    const webTools = toolsConfig.tools.web.enable === false
+        ? []
+        : [
+            createWebSearchTool({
+                webConfig: toolsConfig.tools.web,
+                securityConfig,
+                workspaceDir: options.workspaceDir,
+                channelId: options.channelId,
+            }),
+            createWebFetchTool({
+                webConfig: toolsConfig.tools.web,
+                securityConfig,
+                workspaceDir: options.workspaceDir,
+                channelId: options.channelId,
+            }),
+        ];
     return [
         ...baseTools,
+        ...webTools,
         createSubAgentTool({
             executor: options.executor,
             getCurrentModel: options.getCurrentModel,
@@ -45,6 +66,7 @@ export function createPipiclawTools(options) {
             getSubAgentDiscovery: options.getSubAgentDiscovery,
             getMemoryRecallSettings: options.getMemoryRecallSettings,
             securityConfig,
+            webConfig: toolsConfig.tools.web,
             runtimeContext: {
                 workspacePath: options.workspacePath,
                 channelId: options.channelId,

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

@@ -0,0 +1,17 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { SecurityConfig } from "../security/types.js";
+import type { PipiclawWebToolsConfig } from "./config.js";
+declare const webFetchSchema: import("@sinclair/typebox").TObject<{
+    label: import("@sinclair/typebox").TString;
+    url: import("@sinclair/typebox").TString;
+    extractMode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"markdown">, import("@sinclair/typebox").TLiteral<"text">]>>;
+    maxChars: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface WebFetchToolOptions {
+    webConfig: PipiclawWebToolsConfig;
+    securityConfig: SecurityConfig;
+    workspaceDir: string;
+    channelId?: string;
+}
+export declare function createWebFetchTool(options: WebFetchToolOptions): AgentTool<typeof webFetchSchema>;
+export {};

package/dist/tools/web-fetch.js

@@ -0,0 +1,29 @@
+import { Type } from "@sinclair/typebox";
+import { resolveWebFetchRequest } from "../web/config.js";
+import { runWebFetch } from "../web/fetch.js";
+const webFetchSchema = Type.Object({
+    label: Type.String({ description: "Brief description of what you're fetching and why (shown to user)" }),
+    url: Type.String({ description: "HTTP or HTTPS URL to fetch" }),
+    extractMode: Type.Optional(Type.Union([Type.Literal("markdown"), Type.Literal("text")], {
+        description: "Preferred text extraction format for HTML pages",
+    })),
+    maxChars: Type.Optional(Type.Number({ description: "Maximum extracted text characters to return" })),
+});
+export function createWebFetchTool(options) {
+    return {
+        name: "web_fetch",
+        label: "web_fetch",
+        description: "Fetch a public URL and extract readable content. Returns text for HTML/JSON/text pages and image content blocks for images.",
+        parameters: webFetchSchema,
+        execute: async (_toolCallId, { url, extractMode, maxChars, }, signal) => {
+            const request = resolveWebFetchRequest(options.webConfig.fetch, url, extractMode, maxChars);
+            const result = await runWebFetch({
+                webConfig: options.webConfig,
+                securityConfig: options.securityConfig,
+                workspaceDir: options.workspaceDir,
+                channelId: options.channelId,
+            }, request, signal);
+            return result;
+        },
+    };
+}

package/dist/tools/web-search.d.ts

@@ -0,0 +1,16 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { SecurityConfig } from "../security/types.js";
+import type { PipiclawWebToolsConfig } from "./config.js";
+declare const webSearchSchema: import("@sinclair/typebox").TObject<{
+    label: import("@sinclair/typebox").TString;
+    query: import("@sinclair/typebox").TString;
+    count: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface WebSearchToolOptions {
+    webConfig: PipiclawWebToolsConfig;
+    securityConfig: SecurityConfig;
+    workspaceDir: string;
+    channelId?: string;
+}
+export declare function createWebSearchTool(options: WebSearchToolOptions): AgentTool<typeof webSearchSchema>;
+export {};

package/dist/tools/web-search.js

@@ -0,0 +1,29 @@
+import { Type } from "@sinclair/typebox";
+import { resolveWebSearchRequest } from "../web/config.js";
+import { runWebSearch } from "../web/search.js";
+const webSearchSchema = Type.Object({
+    label: Type.String({ description: "Brief description of what you're searching for and why (shown to user)" }),
+    query: Type.String({ description: "Search query" }),
+    count: Type.Optional(Type.Number({ description: "Maximum number of results to return (1-10)" })),
+});
+export function createWebSearchTool(options) {
+    return {
+        name: "web_search",
+        label: "web_search",
+        description: "Search the public web and return titles, URLs, and snippets from the configured provider.",
+        parameters: webSearchSchema,
+        execute: async (_toolCallId, { query, count }, signal) => {
+            const request = resolveWebSearchRequest(options.webConfig.search, query, count);
+            const result = await runWebSearch({
+                webConfig: options.webConfig,
+                securityConfig: options.securityConfig,
+                workspaceDir: options.workspaceDir,
+                channelId: options.channelId,
+            }, request.query, request.count, signal);
+            return {
+                content: [{ type: "text", text: result.content }],
+                details: result.details,
+            };
+        },
+    };
+}

package/dist/web/client.d.ts

@@ -0,0 +1,41 @@
+import { Buffer } from "node:buffer";
+import type { SecurityConfig } from "../security/types.js";
+import type { PipiclawWebToolsConfig } from "../tools/config.js";
+export declare const WEB_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Pipiclaw/0.5";
+export interface WebRuntimeContext {
+    webConfig: PipiclawWebToolsConfig;
+    securityConfig: SecurityConfig;
+    workspaceDir: string;
+    channelId?: string;
+}
+export interface WebHttpResponse {
+    status: number;
+    finalUrl: string;
+    headers: Record<string, string>;
+    body: Buffer;
+}
+export interface WebHttpRequestOptions {
+    method?: "GET" | "POST";
+    url: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | boolean | undefined>;
+    data?: unknown;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    maxRedirects?: number;
+    maxResponseBytes?: number;
+}
+export declare class WebHttpClient {
+    private readonly context;
+    constructor(context: WebRuntimeContext);
+    request(options: WebHttpRequestOptions): Promise<WebHttpResponse>;
+    requestJson<T>(options: WebHttpRequestOptions): Promise<{
+        response: WebHttpResponse;
+        data: T;
+    }>;
+    requestText(options: WebHttpRequestOptions): Promise<{
+        response: WebHttpResponse;
+        text: string;
+    }>;
+}
+export declare function createWebHttpClient(context: WebRuntimeContext): WebHttpClient;

package/dist/web/client.js

@@ -0,0 +1,193 @@
+import { Buffer } from "node:buffer";
+import axios from "axios";
+import { HttpProxyAgent } from "http-proxy-agent";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { getProxyForUrl } from "proxy-from-env";
+import { SocksProxyAgent } from "socks-proxy-agent";
+import { logSecurityEvent } from "../security/logger.js";
+import { NetworkGuardError, validateNetworkTarget, validateRedirectTarget } from "../security/network.js";
+export const WEB_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Pipiclaw/0.5";
+const agentCache = new Map();
+function normalizeHeaders(headers) {
+    if (!headers || typeof headers !== "object") {
+        return {};
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "string") {
+            result[key.toLowerCase()] = value;
+        }
+        else if (Array.isArray(value)) {
+            result[key.toLowerCase()] = value.join(", ");
+        }
+        else if (value !== undefined && value !== null) {
+            result[key.toLowerCase()] = String(value);
+        }
+    }
+    return result;
+}
+function buildUrlWithParams(url, params) {
+    if (!params) {
+        return url;
+    }
+    const resolved = new URL(url);
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined) {
+            continue;
+        }
+        resolved.searchParams.set(key, String(value));
+    }
+    return resolved.toString();
+}
+function getProxyAgent(requestUrl, explicitProxy) {
+    const proxyUrl = explicitProxy?.trim() || getProxyForUrl(requestUrl);
+    if (!proxyUrl) {
+        return undefined;
+    }
+    const requestProtocol = new URL(requestUrl).protocol;
+    const proxyProtocol = new URL(proxyUrl).protocol;
+    const cacheKey = `${requestProtocol}|${proxyUrl}`;
+    const cached = agentCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    let agent;
+    if (proxyProtocol.startsWith("socks")) {
+        agent = new SocksProxyAgent(proxyUrl);
+    }
+    else if (requestProtocol === "https:") {
+        agent = new HttpsProxyAgent(proxyUrl);
+    }
+    else {
+        agent = new HttpProxyAgent(proxyUrl);
+    }
+    agentCache.set(cacheKey, agent);
+    return agent;
+}
+function logBlockedRequest(context, error) {
+    logSecurityEvent(context.workspaceDir, context.securityConfig, {
+        type: "network",
+        tool: "web",
+        channelId: context.channelId,
+        url: error.url,
+        stage: error.stage,
+        resolvedHost: error.resolvedHost,
+        resolvedAddress: error.resolvedAddress,
+        category: error.category,
+        reason: error.message,
+    });
+}
+function decodeBody(body) {
+    return new TextDecoder("utf-8", { fatal: false }).decode(body);
+}
+function isRedirectStatus(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+export class WebHttpClient {
+    constructor(context) {
+        this.context = context;
+    }
+    async request(options) {
+        const maxRedirects = options.maxRedirects ?? this.context.securityConfig.networkGuard.maxRedirects;
+        let currentUrl = buildUrlWithParams(options.url, options.params);
+        let method = options.method ?? "GET";
+        let data = options.data;
+        for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount++) {
+            try {
+                if (redirectCount === 0) {
+                    await validateNetworkTarget(currentUrl, { config: this.context.securityConfig });
+                }
+                else {
+                    await validateRedirectTarget(currentUrl, { config: this.context.securityConfig });
+                }
+            }
+            catch (error) {
+                if (error instanceof NetworkGuardError) {
+                    logBlockedRequest(this.context, error);
+                }
+                throw error;
+            }
+            const agent = getProxyAgent(currentUrl, this.context.webConfig.proxy);
+            let response;
+            try {
+                response = await axios.request({
+                    method,
+                    url: currentUrl,
+                    data,
+                    headers: {
+                        "User-Agent": WEB_USER_AGENT,
+                        Accept: "*/*",
+                        ...options.headers,
+                    },
+                    responseType: "arraybuffer",
+                    validateStatus: () => true,
+                    timeout: options.timeoutMs,
+                    signal: options.signal,
+                    maxRedirects: 0,
+                    maxContentLength: options.maxResponseBytes ?? Number.POSITIVE_INFINITY,
+                    proxy: false,
+                    httpAgent: agent,
+                    httpsAgent: agent,
+                });
+            }
+            catch (error) {
+                if (options.maxResponseBytes &&
+                    typeof error?.message === "string" &&
+                    error.message.includes("maxContentLength")) {
+                    throw new Error(`Response exceeds maxResponseBytes (${options.maxResponseBytes} bytes)`);
+                }
+                throw error;
+            }
+            const headers = normalizeHeaders(response.headers);
+            const body = Buffer.isBuffer(response.data) ? response.data : Buffer.from(response.data);
+            if (isRedirectStatus(response.status) && headers.location) {
+                if (redirectCount === maxRedirects) {
+                    throw new Error(`Too many redirects while fetching ${options.url}`);
+                }
+                currentUrl = new URL(headers.location, currentUrl).toString();
+                if (response.status === 303 ||
+                    ((response.status === 301 || response.status === 302) && method === "POST")) {
+                    method = "GET";
+                    data = undefined;
+                }
+                continue;
+            }
+            return {
+                status: response.status,
+                finalUrl: currentUrl,
+                headers,
+                body,
+            };
+        }
+        throw new Error(`Too many redirects while fetching ${options.url}`);
+    }
+    async requestJson(options) {
+        const response = await this.request({
+            ...options,
+            headers: {
+                Accept: "application/json",
+                ...options.headers,
+            },
+        });
+        const text = decodeBody(response.body);
+        try {
+            return {
+                response,
+                data: JSON.parse(text),
+            };
+        }
+        catch (error) {
+            throw new Error(`Expected JSON response from ${options.url}, got invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async requestText(options) {
+        const response = await this.request(options);
+        return {
+            response,
+            text: decodeBody(response.body),
+        };
+    }
+}
+export function createWebHttpClient(context) {
+    return new WebHttpClient(context);
+}

package/dist/web/config.d.ts

@@ -0,0 +1,19 @@
+import type { PipiclawWebFetchConfig, PipiclawWebSearchConfig, PipiclawWebToolsConfig } from "../tools/config.js";
+export interface ResolvedWebSearchRequest {
+    query: string;
+    count: number;
+    timeoutMs: number;
+}
+export interface ResolvedWebFetchRequest {
+    url: string;
+    extractMode: "markdown" | "text";
+    maxChars: number;
+    timeoutMs: number;
+    maxImageBytes: number;
+    maxResponseBytes: number;
+    preferJina: boolean;
+    enableJinaFallback: boolean;
+}
+export declare function resolveWebSearchRequest(config: PipiclawWebSearchConfig, query: string, count?: number): ResolvedWebSearchRequest;
+export declare function resolveWebFetchRequest(config: PipiclawWebFetchConfig, url: string, extractMode?: "markdown" | "text", maxChars?: number): ResolvedWebFetchRequest;
+export declare function isWebToolsEnabled(config: PipiclawWebToolsConfig): boolean;

package/dist/web/config.js

@@ -0,0 +1,35 @@
+export function resolveWebSearchRequest(config, query, count) {
+    return {
+        query: query.trim(),
+        count: clamp(count, config.maxResults, 1, 10),
+        timeoutMs: config.timeoutMs,
+    };
+}
+export function resolveWebFetchRequest(config, url, extractMode, maxChars) {
+    return {
+        url: url.trim(),
+        extractMode: extractMode === "text" ? "text" : extractMode === "markdown" ? "markdown" : config.defaultExtractMode,
+        maxChars: clamp(maxChars, config.maxChars, 100),
+        timeoutMs: config.timeoutMs,
+        maxImageBytes: config.maxImageBytes,
+        maxResponseBytes: config.maxResponseBytes,
+        preferJina: config.preferJina,
+        enableJinaFallback: config.enableJinaFallback,
+    };
+}
+export function isWebToolsEnabled(config) {
+    return config.enable !== false;
+}
+function clamp(value, fallback, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    if (normalized < minimum) {
+        return fallback;
+    }
+    if (maximum !== undefined && normalized > maximum) {
+        return fallback;
+    }
+    return normalized;
+}

package/dist/web/extract.d.ts

@@ -0,0 +1,7 @@
+export declare function htmlToText(html: string): string;
+export declare function htmlToMarkdown(html: string): string;
+export declare function extractReadableContent(html: string, url: string, extractMode: "markdown" | "text"): {
+    title: string;
+    content: string;
+    extractor: string;
+};