@apolloyh/apollo-agent 0.1.0

package/dist/tools/builtin.js

@@ -0,0 +1,898 @@
+import { execFile, spawn } from "node:child_process";
+import { lookup } from "node:dns/promises";
+import fs from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import path from "node:path";
+import { promisify } from "node:util";
+import { structuredPatch } from "diff";
+import { PRODUCT } from "../brand.js";
+import { safeRealResolve, stringify, truncate } from "../utils.js";
+import { ToolRegistry } from "./registry.js";
+import { listMemories, saveMemory, searchMemories } from "../memory/memdir.js";
+const execFileAsync = promisify(execFile);
+const EXA_CACHE_TTL_MS = 10 * 60 * 1000;
+const EXA_CACHE_MAX_ENTRIES = 100;
+const FILE_PREVIEW_LINES = 10;
+const FILE_DIFF_LINES = 40;
+// Above this, skip the inline diff entirely rather than load the old file into memory.
+const FILE_DIFF_MAX_BYTES = 1024 * 1024;
+const exaCache = new Map();
+export function createBuiltinRegistry(options) {
+    const registry = new ToolRegistry();
+    const { config, skillManager, mcpManager } = options;
+    registry.register({
+        name: "list_files",
+        description: "List files under the workspace. Can list outside the workspace only after human approval.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Relative directory path." },
+            },
+        },
+        execute: async (input, context) => {
+            const directory = stringInput(input, "directory", ".");
+            const fullPath = await resolvePathWithBoundaryApproval(config, context, directory, "list directory");
+            const entries = await fs.readdir(fullPath, { withFileTypes: true });
+            return {
+                content: entries
+                    .map((entry) => `${entry.isDirectory() ? "dir " : "file"} ${path.join(directory, entry.name)}`)
+                    .join("\n"),
+            };
+        },
+    });
+    registry.register({
+        name: "read_file",
+        description: "Read a UTF-8 file. Files outside the workspace require human approval.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                maxChars: { type: "number" },
+            },
+            required: ["path"],
+        },
+        execute: async (input, context) => {
+            const targetPath = requiredString(input, "path");
+            const fullPath = await resolvePathWithBoundaryApproval(config, context, targetPath, "read file");
+            await requireSensitiveReadApproval(context, fullPath);
+            const maxChars = numberInput(input, "maxChars", 20000);
+            return { content: truncate(await fs.readFile(fullPath, "utf8"), maxChars) };
+        },
+    });
+    registry.register({
+        name: "write_file",
+        description: "Write a UTF-8 file. Writes outside the workspace require explicit approval. Creates parent directories when needed.",
+        risk: "high",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                content: { type: "string" },
+            },
+            required: ["path", "content"],
+        },
+        execute: async (input, context) => {
+            const targetPath = requiredString(input, "path");
+            const fullPath = await resolvePathWithBoundaryApproval(config, context, targetPath, "write file");
+            const content = requiredString(input, "content");
+            // Read the old content only to diff it. Skip on large files so we don't hold
+            // previous+new+patch in memory just to render a preview that's capped anyway.
+            let previous;
+            const diffable = content.length <= FILE_DIFF_MAX_BYTES;
+            try {
+                const stat = diffable ? await fs.stat(fullPath) : undefined;
+                if (stat && stat.size <= FILE_DIFF_MAX_BYTES)
+                    previous = await fs.readFile(fullPath, "utf8");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            await fs.mkdir(path.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, content, "utf8");
+            const displayPath = path.relative(config.workspaceRoot, fullPath);
+            return {
+                content: `Wrote ${displayPath}`,
+                fileChange: diffable ? fileChangeDisplay(displayPath, previous, content) : undefined,
+            };
+        },
+    });
+    registry.register({
+        name: "shell_exec",
+        description: "Run a local shell command in the workspace for builds, tests, package scripts, or system inspection. Do not use for HTTP requests; use web_search or web_fetch instead.",
+        risk: "high",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: { type: "string" },
+                timeoutMs: { type: "number" },
+            },
+            required: ["command"],
+        },
+        execute: async (input, context) => {
+            const command = requiredString(input, "command");
+            const timeout = numberInput(input, "timeoutMs", 30000);
+            try {
+                const { stdout, stderr } = await execFileAsync("zsh", ["-lc", command], {
+                    cwd: config.workspaceRoot,
+                    timeout,
+                    maxBuffer: 1024 * 1024 * 4,
+                    signal: context.signal,
+                });
+                return { content: truncate([stdout, stderr].filter(Boolean).join("\n"), 12000) || "(no output)" };
+            }
+            catch (error) {
+                const execError = error;
+                const detail = [execError.stderr, execError.stdout]
+                    .filter((value) => Boolean(value?.trim()))
+                    .join("\n")
+                    .trim();
+                throw new Error(truncate(detail || execError.message, 12000));
+            }
+        },
+    });
+    registry.register({
+        name: "web_search",
+        description: "Search the public web for current external information. Use when facts may have changed recently or the user asks for online research.",
+        risk: "medium",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query." },
+                maxResults: { type: "number", description: "Maximum number of results to return. Default 5, max 10." },
+            },
+            required: ["query"],
+        },
+        execute: async (input) => {
+            const query = requiredString(input, "query");
+            const maxResults = Math.min(Math.max(Math.trunc(numberInput(input, "maxResults", 5)), 1), 10);
+            const results = await webSearch(query, maxResults);
+            return { content: stringify({ query, results }, 12000) };
+        },
+    });
+    registry.register({
+        name: "web_fetch",
+        description: "Fetch a public HTTP/HTTPS URL and return readable text. Use for specific URLs, GitHub API endpoints, raw files, READMEs, and pages found by web_search. Do not use shell_exec with curl/wget/python for web requests.",
+        risk: "medium",
+        input_schema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "Public HTTP or HTTPS URL to fetch." },
+                maxChars: { type: "number", description: "Maximum returned characters. Default 12000, max 30000." },
+            },
+            required: ["url"],
+        },
+        execute: async (input) => {
+            const url = requiredString(input, "url");
+            const maxChars = Math.min(Math.max(Math.trunc(numberInput(input, "maxChars", 12000)), 1000), 30000);
+            const fetched = await webFetch(url, maxChars, 30000);
+            return { content: stringify(fetched, maxChars + 1000) };
+        },
+    });
+    registry.register({
+        name: "git_status",
+        description: "Show git status for the workspace.",
+        risk: "low",
+        input_schema: { type: "object", properties: {} },
+        execute: () => git(config.workspaceRoot, ["status", "--short"]),
+    });
+    registry.register({
+        name: "git_diff",
+        description: "Show git diff for the workspace.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                staged: { type: "boolean" },
+            },
+        },
+        execute: (input) => git(config.workspaceRoot, input.staged === true ? ["diff", "--cached"] : ["diff"]),
+    });
+    registry.register({
+        name: "git_commit",
+        description: "Create a git commit for current staged changes.",
+        risk: "high",
+        input_schema: {
+            type: "object",
+            properties: {
+                message: { type: "string" },
+            },
+            required: ["message"],
+        },
+        execute: (input) => git(config.workspaceRoot, ["commit", "-m", requiredString(input, "message")]),
+    });
+    registry.register({
+        name: "email_send",
+        description: "Compose an email. By default writes an .eml file to .agent/outbox; sends only if AGENT_SENDMAIL_PATH is configured.",
+        risk: "high",
+        input_schema: {
+            type: "object",
+            properties: {
+                to: { type: "string" },
+                subject: { type: "string" },
+                body: { type: "string" },
+            },
+            required: ["to", "subject", "body"],
+        },
+        execute: async (input) => {
+            const to = requiredString(input, "to");
+            const subject = requiredString(input, "subject");
+            assertEmailHeader("to", to);
+            assertEmailHeader("subject", subject);
+            const body = requiredString(input, "body");
+            const outbox = path.join(config.workspaceRoot, ".agent", "outbox");
+            await fs.mkdir(outbox, { recursive: true });
+            const filename = `${new Date().toISOString().replace(/[:.]/g, "-")}.eml`;
+            const eml = `To: ${to}\nSubject: ${subject}\nContent-Type: text/plain; charset=utf-8\n\n${body}\n`;
+            const emlPath = path.join(outbox, filename);
+            await fs.writeFile(emlPath, eml, "utf8");
+            const sendmail = process.env.AGENT_SENDMAIL_PATH;
+            if (sendmail) {
+                await sendToProcess(sendmail, ["-t"], eml);
+                return { content: `Email sent and archived at ${path.relative(config.workspaceRoot, emlPath)}` };
+            }
+            return { content: `Email written to ${path.relative(config.workspaceRoot, emlPath)}. Set AGENT_SENDMAIL_PATH to send.` };
+        },
+    });
+    registry.register({
+        name: "request_human_approval",
+        description: "Ask the human to approve or decide a high-value action before continuing.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                question: { type: "string" },
+                context: { type: "string" },
+            },
+            required: ["question"],
+        },
+        execute: async (input, context) => {
+            const question = requiredString(input, "question");
+            const approved = await context.requestApproval({
+                toolName: "request_human_approval",
+                risk: "high",
+                reason: question,
+                input,
+            });
+            return { content: approved ? "Human approved." : "Human rejected.", isError: !approved };
+        },
+    });
+    registry.register({
+        name: "skill_search",
+        description: "Search local skills by keyword.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string" },
+            },
+        },
+        execute: async (input) => ({ content: stringify(await skillManager.search(stringInput(input, "query", ""))) }),
+    });
+    registry.register({
+        name: "skill_read",
+        description: "Read a skill file returned by skill_search.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+            },
+            required: ["path"],
+        },
+        execute: async (input) => ({ content: await skillManager.read(requiredString(input, "path")) }),
+    });
+    registry.register({
+        name: "skill_install",
+        description: "Install a local skill into the first configured skills directory. Source must be a SKILL.md file or a directory containing SKILL.md.",
+        risk: "high",
+        input_schema: {
+            type: "object",
+            properties: {
+                sourcePath: { type: "string", description: "Path to SKILL.md or a directory containing SKILL.md." },
+                name: { type: "string", description: "Optional installed skill name." },
+            },
+            required: ["sourcePath"],
+        },
+        execute: async (input) => {
+            const name = typeof input.name === "string" && input.name.trim() ? input.name : undefined;
+            return { content: stringify(await skillManager.installLocal(requiredString(input, "sourcePath"), name)) };
+        },
+    });
+    registry.register({
+        name: "mcp_list_tools",
+        description: "List tools exposed by configured MCP servers.",
+        risk: "medium",
+        input_schema: {
+            type: "object",
+            properties: {
+                server: { type: "string" },
+            },
+        },
+        execute: async (input) => ({ content: stringify(await mcpManager.listTools(stringInput(input, "server", ""))) }),
+    });
+    registry.register({
+        name: "mcp_call_tool",
+        description: "Call a tool on a configured MCP server.",
+        risk: "high",
+        input_schema: {
+            type: "object",
+            properties: {
+                server: { type: "string" },
+                tool: { type: "string" },
+                arguments: { type: "object" },
+            },
+            required: ["server", "tool", "arguments"],
+        },
+        execute: async (input) => ({
+            content: await mcpManager.callTool(requiredString(input, "server"), requiredString(input, "tool"), objectInput(input, "arguments")),
+        }),
+    });
+    registry.register({
+        name: "memory_search",
+        description: "Search durable project memories under .apollo/memory. Use for past decisions, conventions, and user preferences.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                query: { type: "string" },
+                limit: { type: "number" },
+            },
+            required: ["query"],
+        },
+        execute: async (input) => {
+            const q = requiredString(input, "query");
+            const limit = Math.min(Math.max(Math.trunc(numberInput(input, "limit", 8)), 1), 20);
+            const hits = await searchMemories(config.workspaceRoot, q, limit);
+            return { content: stringify({ query: q, count: hits.length, memories: hits }) };
+        },
+    });
+    registry.register({
+        name: "memory_save",
+        description: "Save a durable memory note for this project (title + content + optional tags).",
+        risk: "medium",
+        input_schema: {
+            type: "object",
+            properties: {
+                title: { type: "string" },
+                content: { type: "string" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["title", "content"],
+        },
+        execute: async (input) => {
+            const title = requiredString(input, "title");
+            const content = requiredString(input, "content");
+            const tags = Array.isArray(input.tags) ? input.tags.map(String) : [];
+            const note = await saveMemory(config.workspaceRoot, { title, content, tags });
+            return { content: stringify(note) };
+        },
+    });
+    registry.register({
+        name: "memory_list",
+        description: "List recent project memories.",
+        risk: "low",
+        input_schema: { type: "object", properties: {} },
+        execute: async () => ({ content: stringify(await listMemories(config.workspaceRoot)) }),
+    });
+    registry.register({
+        name: "ask_user_question",
+        description: "Ask the user a structured question when required information is missing. Provide a clear question and optional multiple-choice options. Prefer this over guessing.",
+        risk: "low",
+        input_schema: {
+            type: "object",
+            properties: {
+                question: { type: "string" },
+                options: { type: "array", items: { type: "string" }, description: "Optional choices" },
+            },
+            required: ["question"],
+        },
+        execute: async (input, context) => {
+            const question = requiredString(input, "question");
+            const options = Array.isArray(input.options) ? input.options.map(String) : undefined;
+            context.emit({ type: "user_question", question, options });
+            if (!context.askUser) {
+                return {
+                    content: "No interactive user available. Rephrase the question in your final answer instead.",
+                    isError: true,
+                };
+            }
+            const answer = await context.askUser(question, options);
+            context.emit({ type: "user_answer", answer });
+            return { content: `User answered: ${answer}` };
+        },
+    });
+    if (options.enableTask !== false && options.runTask) {
+        const typeNames = config.agents.map((a) => a.name).join(" | ");
+        registry.register({
+            name: "Task",
+            description: `Launch a fresh subagent (Claude Code Task model) for isolated multi-step work.
+
+Use for broad exploration, independent research/review, or specialist roles. Do NOT use for simple Q&A, reading a known file, or small edits.
+
+Parameters:
+- description: 3–5 words shown to the user (e.g. "find auth handlers")
+- prompt: full self-contained brief for the subagent (no chat history is shared)
+- subagent_type: ${typeNames || "general-purpose"}
+
+Results return to you only — synthesize the final user-facing answer yourself. Independent Tasks may run in parallel.`,
+            risk: "medium",
+            input_schema: {
+                type: "object",
+                properties: {
+                    description: {
+                        type: "string",
+                        description: "Short 3–5 word user-visible label for this task.",
+                    },
+                    prompt: {
+                        type: "string",
+                        description: "Full task brief for the subagent. Include goal, context, constraints, and expected output.",
+                    },
+                    subagent_type: {
+                        type: "string",
+                        description: `Subagent type: ${typeNames}`,
+                    },
+                },
+                required: ["description", "prompt", "subagent_type"],
+            },
+            execute: async (input, context) => {
+                if (!options.runTask) {
+                    return { content: "Task is not available in this context.", isError: true };
+                }
+                // Accept Claude Code names; tolerate legacy worker/task keys.
+                const subagentType = stringInput(input, "subagent_type", "") ||
+                    stringInput(input, "worker", "") ||
+                    "general-purpose";
+                const prompt = stringInput(input, "prompt", "") ||
+                    stringInput(input, "task", "");
+                if (!prompt)
+                    throw new Error("Missing string input: prompt");
+                const description = stringInput(input, "description", `${subagentType} task`);
+                const agent = config.agents.find((candidate) => candidate.name.toLowerCase() === subagentType.toLowerCase());
+                if (!agent) {
+                    const known = config.agents.map((a) => a.name).join(", ");
+                    return {
+                        content: `Unknown subagent_type "${subagentType}". Choose one of: ${known || "(none configured)"}`,
+                        isError: true,
+                    };
+                }
+                const taskId = `task-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`;
+                const startedAt = Date.now();
+                context.emit({
+                    type: "task_start",
+                    id: taskId,
+                    subagentType: agent.name,
+                    description,
+                });
+                const subEmit = (event) => {
+                    switch (event.type) {
+                        case "llm_request":
+                            context.emit({
+                                type: "task_progress",
+                                id: taskId,
+                                subagentType: agent.name,
+                                message: `thinking · turn ${event.turn}`,
+                            });
+                            break;
+                        case "tool_call":
+                            context.emit({
+                                type: "task_progress",
+                                id: taskId,
+                                subagentType: agent.name,
+                                message: `${event.tool}`,
+                            });
+                            break;
+                        case "tool_result":
+                            context.emit({
+                                type: "task_progress",
+                                id: taskId,
+                                subagentType: agent.name,
+                                message: event.isError ? `${event.tool} failed` : `${event.tool} ✓`,
+                            });
+                            break;
+                        default:
+                            break;
+                    }
+                };
+                const result = await options.runTask(agent, prompt, subEmit);
+                const durationMs = Date.now() - startedAt;
+                context.emit({
+                    type: "task_finish",
+                    id: taskId,
+                    subagentType: agent.name,
+                    description,
+                    result: truncate(result, 1000),
+                    durationMs,
+                });
+                return {
+                    content: [
+                        `## Task complete`,
+                        `- type: ${agent.name}`,
+                        `- description: ${description}`,
+                        `- duration: ${(durationMs / 1000).toFixed(1)}s`,
+                        ``,
+                        `### Report`,
+                        result,
+                    ].join("\n"),
+                };
+            },
+        });
+    }
+    // Enforce subagent tool allowlist (and never expose Task unless enableTask)
+    const allowed = options.allowedTools;
+    if (allowed && allowed.length > 0 && !allowed.includes("*")) {
+        return registry.pick(allowed.filter((name) => name !== "Task"));
+    }
+    return registry;
+}
+async function git(cwd, args) {
+    const { stdout, stderr } = await execFileAsync("git", args, { cwd, timeout: 30000, maxBuffer: 1024 * 1024 * 4 });
+    return { content: truncate([stdout, stderr].filter(Boolean).join("\n"), 12000) || "(no output)" };
+}
+function fileChangeDisplay(path, previous, content) {
+    if (previous === undefined) {
+        const lines = visibleLines(content);
+        return {
+            path,
+            kind: "create",
+            added: lines.length,
+            removed: 0,
+            lines: lines.slice(0, FILE_PREVIEW_LINES),
+            omitted: Math.max(0, lines.length - FILE_PREVIEW_LINES),
+        };
+    }
+    const patch = structuredPatch(path, path, previous, content, "", "", { context: 3 });
+    const lines = patch.hunks.flatMap((hunk) => [
+        `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`,
+        ...hunk.lines,
+    ]);
+    const added = patch.hunks.reduce((total, hunk) => total + hunk.lines.filter((line) => line.startsWith("+")).length, 0);
+    const removed = patch.hunks.reduce((total, hunk) => total + hunk.lines.filter((line) => line.startsWith("-")).length, 0);
+    return {
+        path,
+        kind: "update",
+        added,
+        removed,
+        lines: lines.slice(0, FILE_DIFF_LINES),
+        omitted: Math.max(0, lines.length - FILE_DIFF_LINES),
+    };
+}
+function visibleLines(content) {
+    if (!content)
+        return [];
+    const lines = content.split("\n");
+    if (content.endsWith("\n"))
+        lines.pop();
+    return lines;
+}
+async function resolvePathWithBoundaryApproval(config, context, targetPath, operation) {
+    let boundaryDetail = "";
+    try {
+        return await safeRealResolve(config.workspaceRoot, targetPath);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !error.message.startsWith("Path escapes workspace:")) {
+            throw error;
+        }
+        boundaryDetail = error.message.slice("Path escapes workspace:".length).trim();
+    }
+    const resolvedPath = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(config.workspaceRoot, targetPath);
+    const approved = await context.requestApproval({
+        toolName: "workspace_boundary",
+        risk: "high",
+        reason: `Allow ${operation} outside workspace: ${boundaryDetail || resolvedPath}`,
+        input: {
+            operation,
+            path: targetPath,
+            resolvedPath,
+            workspaceRoot: config.workspaceRoot,
+        },
+    });
+    if (!approved) {
+        throw new Error(`Permission denied for ${operation} outside workspace: ${resolvedPath}`);
+    }
+    return resolvedPath;
+}
+async function webSearch(query, maxResults) {
+    const now = Date.now();
+    const key = `${query.trim().toLowerCase().replace(/\s+/g, " ")}\n${maxResults}`;
+    const cached = exaCache.get(key);
+    if (cached && cached.expiresAt > now)
+        return cached.results;
+    if (cached)
+        exaCache.delete(key);
+    const apiKey = process.env.EXA_API_KEY;
+    if (!apiKey)
+        throw new Error("Missing EXA_API_KEY. Set it in the shell or an explicit --env-file.");
+    const results = await searchExa(query, maxResults, apiKey);
+    // ponytail: bounded process-local cache; use a shared cache only if multi-process hit rate justifies it.
+    while (exaCache.size >= EXA_CACHE_MAX_ENTRIES) {
+        const oldest = exaCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        exaCache.delete(oldest);
+    }
+    exaCache.set(key, { expiresAt: now + EXA_CACHE_TTL_MS, results });
+    return results;
+}
+async function searchExa(query, maxResults, apiKey) {
+    const response = await fetch("https://api.exa.ai/search", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": apiKey,
+        },
+        body: JSON.stringify({ query, type: "auto", numResults: maxResults, contents: { highlights: true } }),
+        signal: AbortSignal.timeout(20000),
+    });
+    const raw = await response.text();
+    if (!response.ok)
+        throw new Error(`Exa returned HTTP ${response.status}: ${truncate(raw, 500)}`);
+    const payload = JSON.parse(raw);
+    return (payload.results ?? []).slice(0, maxResults).flatMap((result) => {
+        const title = typeof result.title === "string" ? result.title : "";
+        const url = typeof result.url === "string" ? result.url : "";
+        if (!url)
+            return [];
+        const highlights = Array.isArray(result.highlights)
+            ? result.highlights.filter((value) => typeof value === "string").join(" ")
+            : "";
+        const text = typeof result.text === "string" ? result.text : "";
+        return [{ title: title || url, url, snippet: truncate(highlights || text, 1200) }];
+    });
+}
+async function webFetch(urlText, maxChars, timeoutMs) {
+    let url = new URL(urlText);
+    let response;
+    for (let redirects = 0; redirects <= 5; redirects += 1) {
+        const pinned = await resolvePublicHttpAddress(url);
+        try {
+            response = await requestPinned(url, pinned, timeoutMs, maxChars);
+        }
+        catch (error) {
+            if (error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError" || /timeout/i.test(error.message))) {
+                throw new Error(`web_fetch timed out after ${Math.round(timeoutMs / 1000)}s: ${url.toString()}`);
+            }
+            throw error;
+        }
+        if (![301, 302, 303, 307, 308].includes(response.status))
+            break;
+        const location = response.headers.get("location");
+        if (!location)
+            break;
+        if (redirects === 5)
+            throw new Error("web_fetch stopped after 5 redirects");
+        url = new URL(location, url);
+    }
+    if (!response)
+        throw new Error("web_fetch failed before receiving a response");
+    const contentType = response.headers.get("content-type") ?? "";
+    return {
+        url: response.url,
+        status: response.status,
+        contentType,
+        content: truncate(readableWebContent(response.body, contentType), maxChars),
+    };
+}
+export async function resolvePublicHttpAddress(url, resolve = async (hostname) => await lookup(hostname, { all: true })) {
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Unsupported URL protocol: ${url.protocol}`);
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (hostname === "localhost" || hostname.endsWith(".localhost")) {
+        throw new Error(`web_fetch blocked private address: ${hostname}`);
+    }
+    const literalFamily = isIP(hostname);
+    const addresses = literalFamily ? [{ address: hostname, family: literalFamily }] : await resolve(hostname);
+    if (addresses.length === 0 || addresses.some(({ address }) => isPrivateAddress(address))) {
+        throw new Error(`web_fetch blocked private address: ${hostname}`);
+    }
+    const selected = addresses[0];
+    const address = normalizeIpAddress(selected.address);
+    const family = isIP(address);
+    if (family !== 4 && family !== 6)
+        throw new Error(`web_fetch blocked invalid address: ${hostname}`);
+    return { address, family };
+}
+async function requestPinned(url, pinned, timeoutMs, maxChars) {
+    const pinnedLookup = (_hostname, options, callback) => {
+        if (options.all)
+            callback(null, [pinned]);
+        else
+            callback(null, pinned.address, pinned.family);
+    };
+    // UTF-8 is at most 4 bytes/char, so this many bytes always yields >= maxChars chars after truncate.
+    const maxBytes = maxChars * 4 + 1024;
+    const signal = AbortSignal.timeout(timeoutMs);
+    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
+    return await new Promise((resolve, reject) => {
+        const req = request(url, {
+            headers: {
+                "user-agent": `Mozilla/5.0 (compatible; ${PRODUCT.userAgent}; +https://localhost)`,
+                accept: "text/html,application/json,text/plain;q=0.9,*/*;q=0.8",
+            },
+            lookup: pinnedLookup,
+            signal,
+        }, (incoming) => {
+            const chunks = [];
+            let total = 0;
+            let capped = false;
+            const finish = () => {
+                const headers = new Headers();
+                for (let index = 0; index < incoming.rawHeaders.length; index += 2) {
+                    headers.append(incoming.rawHeaders[index], incoming.rawHeaders[index + 1] ?? "");
+                }
+                resolve({
+                    body: Buffer.concat(chunks).toString("utf8"),
+                    headers,
+                    status: incoming.statusCode ?? 0,
+                    url: url.toString(),
+                });
+            };
+            incoming.on("data", (chunk) => {
+                if (capped)
+                    return;
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                total += chunk.length;
+                if (total >= maxBytes) {
+                    capped = true;
+                    req.destroy();
+                    finish();
+                }
+            });
+            incoming.on("error", reject);
+            incoming.on("end", () => {
+                if (!capped)
+                    finish();
+            });
+        });
+        req.on("error", (error) => {
+            // Ignore the synthetic abort from our own req.destroy() after capping.
+            if (error.code === "ECONNRESET")
+                return;
+            reject(error);
+        });
+        req.end();
+    });
+}
+function isPrivateAddress(address) {
+    if (address.includes(":")) {
+        const normalized = normalizeIpAddress(address);
+        if (isIP(normalized) !== 6)
+            return true;
+        const mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+        if (mapped)
+            return isPrivateAddress(mapped);
+        return normalized.startsWith("::") || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("ff") || /^fe[89a-f]/.test(normalized) || normalized.startsWith("2001:db8:");
+    }
+    if (isIP(address) !== 4)
+        return true;
+    const octets = address.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value)))
+        return true;
+    const [a, b, c] = octets;
+    return a === 0 || a === 10 || a === 127 || a >= 224 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 192 && b === 0 && (c === 0 || c === 2)) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        (a === 198 && b === 51 && c === 100) ||
+        (a === 203 && b === 0 && c === 113);
+}
+function normalizeIpAddress(address) {
+    if (!address.includes(":"))
+        return address;
+    try {
+        return new URL(`http://[${address}]/`).hostname.slice(1, -1).toLowerCase();
+    }
+    catch {
+        return address.toLowerCase();
+    }
+}
+async function requireSensitiveReadApproval(context, fullPath) {
+    if (!isSensitivePath(fullPath))
+        return;
+    const approved = await context.requestApproval({
+        toolName: "sensitive_file_read",
+        risk: "high",
+        reason: `Allow reading sensitive file: ${fullPath}`,
+        input: { path: fullPath },
+    });
+    if (!approved)
+        throw new Error(`Permission denied for sensitive file: ${fullPath}`);
+}
+function isSensitivePath(filePath) {
+    const name = path.basename(filePath).toLowerCase();
+    if (name === ".env" || (name.startsWith(".env.") && name !== ".env.example"))
+        return true;
+    if (/^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/.test(name))
+        return true;
+    return /\.(key|pem|p12|pfx|jks|keystore)$/.test(name);
+}
+function assertEmailHeader(name, value) {
+    if (/[\r\n]/.test(value))
+        throw new Error(`Invalid email ${name}: line breaks are not allowed`);
+}
+function readableWebContent(raw, contentType) {
+    if (contentType.includes("application/json")) {
+        try {
+            return JSON.stringify(JSON.parse(raw), null, 2);
+        }
+        catch {
+            return raw;
+        }
+    }
+    if (contentType.includes("text/html")) {
+        return cleanHtml(raw
+            .replace(/<script[\s\S]*?<\/script>/gi, " ")
+            .replace(/<style[\s\S]*?<\/style>/gi, " ")
+            .replace(/<\/(p|div|li|h[1-6]|tr|section|article)>/gi, "\n"));
+    }
+    return raw;
+}
+function cleanHtml(value) {
+    return decodeHtml(value.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim());
+}
+function decodeHtml(value) {
+    return value
+        .replace(/&#(\d+);/g, (_match, code) => String.fromCharCode(Number(code)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_match, code) => String.fromCharCode(Number.parseInt(code, 16)))
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&#x27;/g, "'")
+        .replace(/&#x2F;/g, "/");
+}
+async function sendToProcess(command, args, input) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["pipe", "ignore", "pipe"] });
+        let stderr = "";
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            reject(new Error(`Timed out running ${command}`));
+        }, 30000);
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} exited with ${code}: ${stderr}`));
+        });
+        child.stdin.end(input);
+    });
+}
+function requiredString(input, key) {
+    const value = input[key];
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Missing string input: ${key}`);
+    return value;
+}
+function stringInput(input, key, fallback) {
+    const value = input[key];
+    return typeof value === "string" ? value : fallback;
+}
+function numberInput(input, key, fallback) {
+    const value = input[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function objectInput(input, key) {
+    const value = input[key];
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`Missing object input: ${key}`);
+    return value;
+}