@oyasmi/pipiclaw 0.5.7 → 0.5.9

package/dist/security/network.js

@@ -0,0 +1,246 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+export class NetworkGuardError extends Error {
+    constructor(options) {
+        super(options.message);
+        this.name = "NetworkGuardError";
+        this.url = options.url;
+        this.stage = options.stage;
+        this.category = options.category;
+        this.resolvedHost = options.resolvedHost;
+        this.resolvedAddress = options.resolvedAddress;
+    }
+}
+const BLOCKED_HOSTS = new Set(["localhost", "metadata.google.internal", "metadata", "169.254.169.254"]);
+const PRIVATE_IPV4_CIDRS = [
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "100.64.0.0/10",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+    "198.18.0.0/15",
+];
+const PRIVATE_IPV6_CIDRS = ["::1/128", "::/128", "fc00::/7", "fe80::/10"];
+function normalizeHost(host) {
+    return host.trim().replace(/\.$/, "").toLowerCase();
+}
+function parseIpv4(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4) {
+        return null;
+    }
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d+$/.test(part)) {
+            return null;
+        }
+        const octet = Number.parseInt(part, 10);
+        if (octet < 0 || octet > 255) {
+            return null;
+        }
+        value = (value << 8) | octet;
+    }
+    return value >>> 0;
+}
+function expandIpv6(ip) {
+    const normalized = ip.toLowerCase();
+    const hasEmbeddedIpv4 = normalized.includes(".");
+    let working = normalized;
+    if (hasEmbeddedIpv4) {
+        const lastColon = working.lastIndexOf(":");
+        if (lastColon === -1) {
+            return null;
+        }
+        const ipv4 = parseIpv4(working.slice(lastColon + 1));
+        if (ipv4 === null) {
+            return null;
+        }
+        const high = ((ipv4 >>> 16) & 0xffff).toString(16);
+        const low = (ipv4 & 0xffff).toString(16);
+        working = `${working.slice(0, lastColon)}:${high}:${low}`;
+    }
+    const pieces = working.split("::");
+    if (pieces.length > 2) {
+        return null;
+    }
+    const left = pieces[0] ? pieces[0].split(":").filter(Boolean) : [];
+    const right = pieces[1] ? pieces[1].split(":").filter(Boolean) : [];
+    if (left.length + right.length > 8) {
+        return null;
+    }
+    const fill = new Array(8 - left.length - right.length).fill("0");
+    const groups = pieces.length === 2 ? [...left, ...fill, ...right] : left;
+    return groups.length === 8 ? groups : null;
+}
+function parseIpv6(ip) {
+    const groups = expandIpv6(ip);
+    if (!groups) {
+        return null;
+    }
+    let value = 0n;
+    for (const group of groups) {
+        if (!/^[0-9a-f]{1,4}$/i.test(group)) {
+            return null;
+        }
+        value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+    }
+    return value;
+}
+function ipInCidr(ip, cidr) {
+    const [network, prefixText] = cidr.split("/");
+    const prefix = Number.parseInt(prefixText ?? "", 10);
+    if (!Number.isFinite(prefix)) {
+        return false;
+    }
+    const version = isIP(ip);
+    if (version === 4) {
+        const ipValue = parseIpv4(ip);
+        const networkValue = parseIpv4(network);
+        if (ipValue === null || networkValue === null || prefix < 0 || prefix > 32) {
+            return false;
+        }
+        const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+        return (ipValue & mask) === (networkValue & mask);
+    }
+    if (version === 6) {
+        const ipValue = parseIpv6(ip);
+        const networkValue = parseIpv6(network);
+        if (ipValue === null || networkValue === null || prefix < 0 || prefix > 128) {
+            return false;
+        }
+        const shift = 128 - prefix;
+        if (shift === 128) {
+            return true;
+        }
+        return ipValue >> BigInt(shift) === networkValue >> BigInt(shift);
+    }
+    return false;
+}
+function matchesAllowedHost(hostname, allowedHosts) {
+    const normalized = normalizeHost(hostname);
+    return allowedHosts.some((candidate) => normalizeHost(candidate) === normalized);
+}
+function matchesAllowedCidr(address, allowedCidrs) {
+    return allowedCidrs.some((cidr) => ipInCidr(address, cidr.trim()));
+}
+function isBlockedHost(hostname) {
+    const normalized = normalizeHost(hostname);
+    return normalized.endsWith(".localhost") || BLOCKED_HOSTS.has(normalized);
+}
+function isPrivateAddress(address) {
+    const version = isIP(address);
+    if (version === 4) {
+        return PRIVATE_IPV4_CIDRS.some((cidr) => ipInCidr(address, cidr));
+    }
+    if (version === 6) {
+        return PRIVATE_IPV6_CIDRS.some((cidr) => ipInCidr(address, cidr));
+    }
+    return false;
+}
+async function validateUrlTarget(rawUrl, context, stage) {
+    const url = (() => {
+        try {
+            return new URL(rawUrl);
+        }
+        catch {
+            throw new NetworkGuardError({
+                url: rawUrl,
+                stage,
+                category: "invalid-url",
+                message: `Invalid URL: ${rawUrl}`,
+            });
+        }
+    })();
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new NetworkGuardError({
+            url: rawUrl,
+            stage,
+            category: "unsupported-scheme",
+            message: `Only http/https URLs are allowed, got ${url.protocol || "unknown"}`,
+        });
+    }
+    const hostname = normalizeHost(url.hostname);
+    if (!hostname) {
+        throw new NetworkGuardError({
+            url: rawUrl,
+            stage,
+            category: "missing-host",
+            message: `URL is missing a hostname: ${rawUrl}`,
+        });
+    }
+    const { networkGuard } = context.config;
+    if (!networkGuard.enabled) {
+        return { url: url.toString(), hostname };
+    }
+    if (matchesAllowedHost(hostname, networkGuard.allowedHosts)) {
+        return { url: url.toString(), hostname };
+    }
+    if (isBlockedHost(hostname)) {
+        throw new NetworkGuardError({
+            url: rawUrl,
+            stage,
+            category: "blocked-host",
+            message: `Blocked host: ${hostname}`,
+            resolvedHost: hostname,
+        });
+    }
+    if (isIP(hostname)) {
+        if (!matchesAllowedCidr(hostname, networkGuard.allowedCidrs) && isPrivateAddress(hostname)) {
+            throw new NetworkGuardError({
+                url: rawUrl,
+                stage,
+                category: "private-address",
+                message: `Blocked private network address: ${hostname}`,
+                resolvedHost: hostname,
+                resolvedAddress: hostname,
+            });
+        }
+        return { url: url.toString(), hostname, resolvedAddress: hostname };
+    }
+    let records;
+    try {
+        records = (await lookup(hostname, { all: true, verbatim: true }));
+    }
+    catch (error) {
+        throw new NetworkGuardError({
+            url: rawUrl,
+            stage,
+            category: "dns-failure",
+            message: `Failed to resolve host ${hostname}: ${error instanceof Error ? error.message : String(error)}`,
+            resolvedHost: hostname,
+        });
+    }
+    if (records.length === 0) {
+        throw new NetworkGuardError({
+            url: rawUrl,
+            stage,
+            category: "dns-failure",
+            message: `Failed to resolve host ${hostname}`,
+            resolvedHost: hostname,
+        });
+    }
+    for (const record of records) {
+        if (matchesAllowedCidr(record.address, networkGuard.allowedCidrs)) {
+            return { url: url.toString(), hostname, resolvedAddress: record.address };
+        }
+        if (isPrivateAddress(record.address)) {
+            throw new NetworkGuardError({
+                url: rawUrl,
+                stage,
+                category: "private-address",
+                message: `Blocked private network address resolved from ${hostname}: ${record.address}`,
+                resolvedHost: hostname,
+                resolvedAddress: record.address,
+            });
+        }
+    }
+    return { url: url.toString(), hostname, resolvedAddress: records[0]?.address };
+}
+export async function validateNetworkTarget(url, context) {
+    return validateUrlTarget(url, context, "request");
+}
+export async function validateRedirectTarget(url, context) {
+    return validateUrlTarget(url, context, "redirect");
+}

package/dist/security/types.d.ts

@@ -14,6 +14,12 @@ export interface SecurityConfig {
         writeDeny: string[];
         resolveSymlinks: boolean;
     };
+    networkGuard: {
+        enabled: boolean;
+        allowedCidrs: string[];
+        allowedHosts: string[];
+        maxRedirects: number;
+    };
     audit: {
         logBlocked: boolean;
         logFile?: string;
@@ -63,4 +69,13 @@ export interface BlockedCommandLogEvent extends SecurityLogEventBase {
     reason?: string;
     matchedText?: string;
 }
-export type SecurityLogEvent = BlockedPathLogEvent | BlockedCommandLogEvent;
+export interface BlockedNetworkLogEvent extends SecurityLogEventBase {
+    type: "network";
+    url: string;
+    stage: "request" | "redirect";
+    resolvedHost?: string;
+    resolvedAddress?: string;
+    category?: string;
+    reason?: string;
+}
+export type SecurityLogEvent = BlockedPathLogEvent | BlockedCommandLogEvent | BlockedNetworkLogEvent;

package/dist/shared/shell-escape.d.ts

@@ -3,3 +3,10 @@
  * Wraps in single quotes and escapes internal single quotes.
  */
 export declare function shellEscape(s: string): string;
+/**
+ * Normalize filesystem paths for POSIX-style shells.
+ * On Windows we convert backslashes to forward slashes so Git Bash/MSYS tools
+ * can consume the path consistently.
+ */
+export declare function toShellPath(path: string): string;
+export declare function shellEscapePath(path: string): string;

package/dist/shared/shell-escape.js

@@ -5,3 +5,14 @@
 export function shellEscape(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
+/**
+ * Normalize filesystem paths for POSIX-style shells.
+ * On Windows we convert backslashes to forward slashes so Git Bash/MSYS tools
+ * can consume the path consistently.
+ */
+export function toShellPath(path) {
+    return process.platform === "win32" ? path.replace(/\\/g, "/") : path;
+}
+export function shellEscapePath(path) {
+    return shellEscape(toShellPath(path));
+}

package/dist/subagents/discovery.d.ts

@@ -1,5 +1,5 @@
 import type { Api, Model } from "@mariozechner/pi-ai";
-declare const ALLOWED_SUB_AGENT_TOOLS: readonly ["read", "bash", "edit", "write"];
+declare const ALLOWED_SUB_AGENT_TOOLS: readonly ["read", "bash", "edit", "write", "web_search", "web_fetch"];
 declare const ALLOWED_CONTEXT_MODES: readonly ["isolated", "contextual"];
 declare const ALLOWED_MEMORY_MODES: readonly ["none", "session", "relevant"];
 export type SubAgentToolName = (typeof ALLOWED_SUB_AGENT_TOOLS)[number];

package/dist/subagents/discovery.js

@@ -3,7 +3,7 @@ import { existsSync, readdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { findExactModelReferenceMatch, formatModelReference } from "../models/utils.js";
 import { SUB_AGENTS_DIR_NAME } from "../paths.js";
-const ALLOWED_SUB_AGENT_TOOLS = ["read", "bash", "edit", "write"];
+const ALLOWED_SUB_AGENT_TOOLS = ["read", "bash", "edit", "write", "web_search", "web_fetch"];
 const DEFAULT_SUB_AGENT_TOOLS = ["read", "bash"];
 const DEFAULT_MAX_TURNS = 24;
 const DEFAULT_MAX_TOOL_CALLS = 48;

package/dist/subagents/tool.d.ts

@@ -4,6 +4,7 @@ import type { Executor } from "../sandbox.js";
 import type { SecurityConfig } from "../security/types.js";
 import type { PipiclawMemoryRecallSettings } from "../settings.js";
 import type { UsageTotals } from "../shared/types.js";
+import type { PipiclawWebToolsConfig } from "../tools/config.js";
 import { type ResolvedSubAgentConfig, type SubAgentDiscoveryResult } from "./discovery.js";
 declare const subagentSchema: import("@sinclair/typebox").TObject<{
     label: import("@sinclair/typebox").TString;
@@ -44,6 +45,7 @@ export interface SubAgentToolOptions {
     getSubAgentDiscovery?: () => SubAgentDiscoveryResult;
     getMemoryRecallSettings?: () => PipiclawMemoryRecallSettings;
     securityConfig?: SecurityConfig;
+    webConfig?: PipiclawWebToolsConfig;
     runtimeContext: {
         workspacePath: string;
         channelId: string;

package/dist/subagents/tool.js

@@ -11,6 +11,8 @@ import { clipText, extractAssistantText, extractLabelFromArgs, HAN_REGEX } from
 import { createBashTool } from "../tools/bash.js";
 import { createEditTool } from "../tools/edit.js";
 import { createReadTool } from "../tools/read.js";
+import { createWebFetchTool } from "../tools/web-fetch.js";
+import { createWebSearchTool } from "../tools/web-search.js";
 import { createWriteTool } from "../tools/write.js";
 import { formatSubAgentList, resolveSubAgentConfig, validateSubAgentTask, } from "./discovery.js";
 const subagentSchema = Type.Object({
@@ -118,6 +120,25 @@ function createToolSet(executor, bashTimeoutSec, options) {
         }),
     ];
 }
+function createNamedToolSet(executor, bashTimeoutSec, options) {
+    const tools = createToolSet(executor, bashTimeoutSec, options);
+    const byName = Object.fromEntries(tools.map((tool) => [tool.name, tool]));
+    if (options.webConfig && options.webConfig.enable !== false) {
+        byName.web_search = createWebSearchTool({
+            webConfig: options.webConfig,
+            securityConfig: options.securityConfig ?? DEFAULT_SECURITY_CONFIG,
+            workspaceDir: options.workspaceDir,
+            channelId: options.runtimeContext.channelId,
+        });
+        byName.web_fetch = createWebFetchTool({
+            webConfig: options.webConfig,
+            securityConfig: options.securityConfig ?? DEFAULT_SECURITY_CONFIG,
+            workspaceDir: options.workspaceDir,
+            channelId: options.runtimeContext.channelId,
+        });
+    }
+    return byName;
+}
 function buildSubAgentTask(task, config, runtimeContext, contextBlocks) {
     const taskText = task.trim();
     const lines = [
@@ -288,17 +309,18 @@ export function createSubAgentTool(options) {
                     details: createDetails(config, usage, assistantTurns, toolCalls, Date.now() - startedAt, Boolean(failureReason), failureReason),
                 });
             };
+            const availableTools = Object.values(createNamedToolSet(options.executor, config.bashTimeoutSec, options));
             const worker = options.createWorker?.({
                 subAgent: config,
                 apiKey,
-                tools: filterToolsByName(createToolSet(options.executor, config.bashTimeoutSec, options), config.tools),
+                tools: filterToolsByName(availableTools, config.tools),
             }) ??
                 new Agent({
                     initialState: {
                         systemPrompt: config.systemPrompt,
                         model: config.model,
                         thinkingLevel: "off",
-                        tools: filterToolsByName(createToolSet(options.executor, config.bashTimeoutSec, options), config.tools),
+                        tools: filterToolsByName(availableTools, config.tools),
                     },
                     convertToLlm,
                     getApiKey: async () => apiKey,

package/dist/tools/config.d.ts

@@ -0,0 +1,30 @@
+export type WebSearchProvider = "brave" | "tavily" | "jina" | "searxng" | "duckduckgo";
+export interface PipiclawWebSearchConfig {
+    provider: WebSearchProvider;
+    apiKey: string;
+    baseUrl: string;
+    maxResults: number;
+    timeoutMs: number;
+}
+export interface PipiclawWebFetchConfig {
+    maxChars: number;
+    timeoutMs: number;
+    maxImageBytes: number;
+    preferJina: boolean;
+    enableJinaFallback: boolean;
+    defaultExtractMode: "markdown" | "text";
+}
+export interface PipiclawWebToolsConfig {
+    enable: boolean;
+    proxy: string | null;
+    search: PipiclawWebSearchConfig;
+    fetch: PipiclawWebFetchConfig;
+}
+export interface PipiclawToolsConfig {
+    tools: {
+        web: PipiclawWebToolsConfig;
+    };
+}
+export declare const DEFAULT_TOOLS_CONFIG: PipiclawToolsConfig;
+export declare function getToolsConfigPath(appHomeDir?: string): string;
+export declare function loadToolsConfig(appHomeDir?: string): PipiclawToolsConfig;

package/dist/tools/config.js

@@ -0,0 +1,114 @@
+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,
+                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 mergeToolsConfig(source) {
+    if (!isRecord(source)) {
+        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
+        : DEFAULT_TOOLS_CONFIG.tools.web.search.provider;
+    const defaultExtractMode = asTrimmedString(fetch.defaultExtractMode, 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),
+                    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 loadToolsConfig(appHomeDir = APP_HOME_DIR) {
+    const configPath = getToolsConfigPath(appHomeDir);
+    if (!existsSync(configPath)) {
+        return DEFAULT_TOOLS_CONFIG;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        return mergeToolsConfig(raw);
+    }
+    catch (error) {
+        console.warn(`Failed to load tools config from ${configPath}: ${error}`);
+        return DEFAULT_TOOLS_CONFIG;
+    }
+}

package/dist/tools/edit.js

@@ -3,7 +3,7 @@ import * as Diff from "diff";
 import { DEFAULT_SECURITY_CONFIG } from "../security/config.js";
 import { logSecurityEvent } from "../security/logger.js";
 import { guardPath } from "../security/path-guard.js";
-import { shellEscape } from "../shared/shell-escape.js";
+import { shellEscapePath } from "../shared/shell-escape.js";
 import { writeContent } from "./write-content.js";
 /**
  * Generate a unified diff string with line numbers and context
@@ -123,7 +123,7 @@ export function createEditTool(executor, options = {}) {
                 }
             }
             // Read the file
-            const readResult = await executor.exec(`cat ${shellEscape(path)}`, { signal });
+            const readResult = await executor.exec(`cat ${shellEscapePath(path)}`, { signal });
             if (readResult.code !== 0) {
                 throw new Error(readResult.stderr || `File not found: ${path}`);
             }

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;
@@ -23,6 +26,7 @@ export function createPipiclawBaseTools(executor, options = {}) {
 }
 export function createPipiclawTools(options) {
     const securityConfig = loadSecurityConfig(APP_HOME_DIR);
+    const 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/read.js

@@ -3,7 +3,7 @@ import { extname } from "path";
 import { DEFAULT_SECURITY_CONFIG } from "../security/config.js";
 import { logSecurityEvent } from "../security/logger.js";
 import { guardPath } from "../security/path-guard.js";
-import { shellEscape } from "../shared/shell-escape.js";
+import { shellEscapePath, toShellPath } from "../shared/shell-escape.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "./truncate.js";
 /**
  * Map of file extensions to MIME types for common image formats
@@ -70,7 +70,7 @@ export function createReadTool(executor, options = {}) {
             const mimeType = isImageFile(path);
             if (mimeType) {
                 // Read as image (binary) - use base64
-                const result = await executor.exec(`base64 < ${shellEscape(path)}`, { signal });
+                const result = await executor.exec(`base64 < ${shellEscapePath(path)}`, { signal });
                 if (result.code !== 0) {
                     throw new Error(result.stderr || `Failed to read file: ${path}`);
                 }
@@ -84,7 +84,7 @@ export function createReadTool(executor, options = {}) {
                 };
             }
             // Get total line count first
-            const countResult = await executor.exec(`wc -l < ${shellEscape(path)}`, { signal });
+            const countResult = await executor.exec(`wc -l < ${shellEscapePath(path)}`, { signal });
             if (countResult.code !== 0) {
                 throw new Error(countResult.stderr || `Failed to read file: ${path}`);
             }
@@ -99,10 +99,10 @@ export function createReadTool(executor, options = {}) {
             // Read content with offset
             let cmd;
             if (startLine === 1) {
-                cmd = `cat ${shellEscape(path)}`;
+                cmd = `cat ${shellEscapePath(path)}`;
             }
             else {
-                cmd = `tail -n +${startLine} ${shellEscape(path)}`;
+                cmd = `tail -n +${startLine} ${shellEscapePath(path)}`;
             }
             const result = await executor.exec(cmd, { signal });
             if (result.code !== 0) {
@@ -124,7 +124,7 @@ export function createReadTool(executor, options = {}) {
             if (truncation.firstLineExceedsLimit) {
                 // First line at offset exceeds 50KB - tell model to use bash
                 const firstLineSize = formatSize(Buffer.byteLength(selectedContent.split("\n")[0], "utf-8"));
-                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+                outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${toShellPath(path)} | head -c ${DEFAULT_MAX_BYTES}]`;
                 details = { truncation };
             }
             else if (truncation.truncated) {

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 {};