wizards 0.1.9

package/apps/runtime/dist/tools/connector.js

@@ -0,0 +1,204 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { refreshConnector, resolveConnector } from "../connectors/external.js";
+import { connectionContext } from "../connectors/index.js";
+import { attempt, clip } from "./shared.js";
+import { resolveFile } from "./store.js";
+const FILE_NOTE = " File content never passes through you: returned content is kept as a file and you get its path; to send a kept file, give `file:<path>` where an input asks for `*_base64`.";
+/** Above this many actions a connector is offered as "find an action, then call it". */
+const DIRECT_TOOLS = 24;
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+/**
+ * The actions of imported connectors a step may use, as tools. Reading is free; anything that
+ * changes the person's account waits for their yes — engenty's default policy for connectors
+ * (read: allow, write and destructive: ask), asked of the person who is running the wizard.
+ */
+export async function connectorTools(step, ctx, files) {
+    const tools = {};
+    const connections = (ctx.def.connections ?? []).filter((c) => c.connector && step.connections?.includes(c.id));
+    for (const connection of connections) {
+        Object.assign(tools, await toolsOf(connection, ctx, files));
+    }
+    return tools;
+}
+const MAGIC = [
+    ["%PDF", "application/pdf", "pdf"],
+    ["\x89PNG", "image/png", "png"],
+    ["\xff\xd8\xff", "image/jpeg", "jpg"],
+    ["GIF8", "image/gif", "gif"],
+    ["PK\x03\x04", "application/zip", "zip"],
+];
+/** What a file is, by its first bytes — connectors often hand over content without a name. */
+function sniff(data) {
+    const head = data.subarray(0, 8).toString("latin1");
+    const hit = MAGIC.find(([magic]) => head.startsWith(magic));
+    return hit ? { mime: hit[1], ext: hit[2] } : null;
+}
+/**
+ * A model cannot carry a file: content an action returns as base64 is kept in the wizard's
+ * files and the result names the path instead.
+ */
+async function keepContent(result, action, service, files) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        return result;
+    }
+    const out = { ...result };
+    for (const [key, value] of Object.entries(out)) {
+        if (!key.endsWith("_base64") || typeof value !== "string" || !value) {
+            continue;
+        }
+        const data = Buffer.from(value, "base64");
+        const kind = sniff(data);
+        const given = [out.name, out.filename, out.file_name].find((v) => typeof v === "string" && v.length > 0);
+        const name = given ?? `${action.id}-${Date.now().toString(36)}.${kind?.ext ?? "bin"}`;
+        const declared = [out.mime_type, out.mimeType, out.content_type].find((v) => typeof v === "string");
+        const kept = await files.keep(`${service}/${name}`, data, {
+            mime: declared ?? kind?.mime,
+            source: `${service}: ${action.summary || action.id}`,
+        });
+        delete out[key];
+        out.saved = kept.path;
+        out.note = "The content is kept as a file; read it with read_document.";
+    }
+    return out;
+}
+/** The other way round: `file:<path>` in a `*_base64` input sends a kept file or an upload. */
+async function sendContent(input, ctx) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        return input;
+    }
+    const out = { ...input };
+    for (const [key, value] of Object.entries(out)) {
+        if (key.endsWith("_base64") && typeof value === "string" && value.startsWith("file:")) {
+            const file = await resolveFile(ctx, value.slice("file:".length));
+            out[key] = Buffer.from(file.data).toString("base64");
+        }
+    }
+    return out;
+}
+/**
+ * Whether the person is asked before an action runs. The wizard's author can settle it per
+ * action (a server may call a plain lookup a change); deleting is never taken off the person.
+ */
+function asks(connection, action) {
+    if (action.group === "destructive") {
+        return true;
+    }
+    return (connection.policy?.[action.id] ?? (action.group === "read" ? "allow" : "ask")) === "ask";
+}
+async function toolsOf(connection, ctx, files) {
+    const projectId = ctx.project.id;
+    const id = connection.connector ?? "";
+    let resolved = await resolveConnector(projectId, id);
+    if (!resolved) {
+        return {};
+    }
+    const account = () => connectionContext(ctx.store, connection, projectId);
+    // An MCP server that lists its tools only to a signed-in account: ask it now that there is one.
+    if (resolved.imported && !resolved.connector.actions.length) {
+        const found = await account();
+        if (found) {
+            await refreshConnector(projectId, id, found.ctx.accessToken).catch(() => undefined);
+            resolved = (await resolveConnector(projectId, id)) ?? resolved;
+        }
+    }
+    const { connector, inputSchema } = resolved;
+    const usable = connection.actions
+        ? connector.actions.filter((a) => connection.actions?.includes(a.id))
+        : connector.actions.filter((a) => a.group === "read");
+    const service = connection.title ?? connector.name;
+    const call = (action, input) => attempt(async () => {
+        const found = await account();
+        if (!found) {
+            return {
+                error: `The person has not connected ${service}. Go on without it and say so in your result.`,
+            };
+        }
+        const key = `${connection.id}:${action.id}`;
+        if (asks(connection, action) && !ctx.resources.allowed.has(key)) {
+            const answer = await ctx.ask({
+                kind: "confirm",
+                reason: action.summary || action.id,
+                service,
+                action: {
+                    id: action.id,
+                    summary: action.summary,
+                    destructive: action.group === "destructive",
+                },
+                input: JSON.stringify(input ?? {}, null, 2).slice(0, 4000),
+            });
+            if (!answer) {
+                return {
+                    error: "Nobody is there to allow this change, so it was not made. Report it as open in your result.",
+                };
+            }
+            if (answer.type !== "done") {
+                return {
+                    error: "The person did not allow this change. Do not try it again; say in your result that it was not made.",
+                };
+            }
+            if (answer.remember) {
+                ctx.resources.allowed.add(key);
+            }
+        }
+        await ctx.emit("tool", `${service}: ${action.summary || action.id}`.slice(0, 120));
+        const result = await keepContent(await action.handler(await sendContent(input ?? {}, ctx), found.ctx), action, service, files);
+        const text = typeof result === "string" ? result : JSON.stringify(result);
+        return { result: clip(text ?? "", 8000) };
+    });
+    const prefix = connector.toolPrefix;
+    const direct = usable.length <= DIRECT_TOOLS && usable.every((a) => TOOL_NAME.test(`${prefix}_${a.id}`));
+    if (direct) {
+        return Object.fromEntries(usable.map((action) => [
+            `${prefix}_${action.id}`,
+            createTool({
+                id: `${prefix}_${action.id}`,
+                description: `${service}: ${action.description || action.summary}${asks(connection, action) ? " — the person is asked before this runs." : ""}${FILE_NOTE}`.slice(0, 1100),
+                inputSchema: action.inputSchema,
+                execute: (input) => call(action, input),
+            }),
+        ]));
+    }
+    return {
+        [`${prefix}_actions`]: createTool({
+            id: `${prefix}_actions`,
+            description: `${service} offers ${usable.length} actions. Find the ones you need by words from their name or purpose; you get each action's id, what it does and its input. Then call ${prefix}_call.`,
+            inputSchema: z.object({
+                query: z.string().describe("Words to look for, e.g. 'search pages' or 'invoice list'."),
+            }),
+            execute: ({ query }) => attempt(async () => {
+                const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+                const scored = usable
+                    .map((a) => {
+                    const text = `${a.id} ${a.summary} ${a.description}`.toLowerCase();
+                    return { a, score: words.filter((w) => text.includes(w)).length };
+                })
+                    .filter((x) => x.score > 0)
+                    .sort((x, y) => y.score - x.score)
+                    .slice(0, 12);
+                return {
+                    actions: scored.map(({ a }) => ({
+                        id: a.id,
+                        does: a.summary || a.description.slice(0, 200),
+                        asks_person_first: asks(connection, a),
+                        input: inputSchema(a.id),
+                    })),
+                };
+            }),
+        }),
+        [`${prefix}_call`]: createTool({
+            id: `${prefix}_call`,
+            description: `Run one ${service} action found with ${prefix}_actions. Some wait for the person's yes first.${FILE_NOTE}`,
+            inputSchema: z.object({
+                action: z.string(),
+                input: z.record(z.string(), z.unknown()).optional(),
+            }),
+            execute: ({ action: id, input }) => {
+                const action = usable.find((a) => a.id === id);
+                return action
+                    ? call(action, input)
+                    : Promise.resolve({ error: `No action "${id}". Use ${prefix}_actions to find one.` });
+            },
+        }),
+    };
+}

package/apps/runtime/dist/tools/index.js

@@ -0,0 +1,234 @@
+import { anthropic } from "@ai-sdk/anthropic";
+import { isTextMime } from "@engenty-wizards/shared/workspace";
+import { createTool } from "@mastra/core/tools";
+import { MCPClient } from "@mastra/mcp";
+import { z } from "zod";
+import { generateImageMedia } from "../media/generate.js";
+import { markMedia } from "../media/marking.js";
+import { gatewayTools, isHarnessVendor } from "../models.js";
+import { htmlToMarkdown } from "../render/convert.js";
+import { pythonToolDescription, sandboxCapabilities, shellToolDescription, } from "../sandbox/index.js";
+import { snapshotFile } from "../services/files.js";
+import { browserTools } from "./browser.js";
+import { connectorTools } from "./connector.js";
+import { mailTools } from "./mail.js";
+import { assertPublicUrl, safeFetch } from "./net-guard.js";
+import { projectTools } from "./project.js";
+import { clip, FileKeeper } from "./shared.js";
+import { storeTools } from "./store.js";
+/** The tools an agent step may use: exactly what its definition allowlists. */
+export async function buildStepTools(step, ctx, resolved, uploads) {
+    const tools = {};
+    const assets = [];
+    const allowed = new Set(step.tools);
+    let mcp = null;
+    if (allowed.has("web_search")) {
+        // Anthropic models search natively; other models search through the AI Gateway's tool.
+        if (resolved.vendor === "anthropic") {
+            tools.web_search = anthropic.tools.webSearch_20250305({ maxUses: 8 });
+        }
+        else if (isHarnessVendor(resolved.vendor)) {
+            // An installed client searches with its own tool; naming it here switches it on.
+            tools.web_search = createTool({
+                id: "web_search",
+                description: "Search the web.",
+                inputSchema: z.object({ query: z.string() }),
+                execute: async () => ({ error: "The client searches itself." }),
+            });
+        }
+        else if (resolved.gateway) {
+            tools.web_search = gatewayTools.perplexitySearch({ maxResults: 8 });
+        }
+    }
+    if (allowed.has("web_fetch") || allowed.has("web_search")) {
+        tools.web_fetch = createTool({
+            id: "web_fetch",
+            description: "Fetch a public web page or file and return its readable text (Markdown).",
+            inputSchema: z.object({ url: z.string().describe("Absolute http(s) URL") }),
+            execute: async ({ url }) => {
+                const safe = await assertPublicUrl(url);
+                await ctx.emit("tool", `Liest ${safe.hostname}`);
+                const res = await safeFetch(safe.toString(), {
+                    signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(20_000)]),
+                    headers: { "user-agent": "Mozilla/5.0 (compatible; engenty-wizards/0.1)" },
+                });
+                const type = res.headers.get("content-type") ?? "";
+                const body = await res.text();
+                const text = type.includes("html") ? htmlToMarkdown(body) : body;
+                return { status: res.status, url: res.url, content: clip(text) };
+            },
+        });
+    }
+    if (allowed.has("http")) {
+        tools.http_request = createTool({
+            id: "http_request",
+            description: "Call a public HTTP API. Use for REST endpoints the instructions name.",
+            inputSchema: z.object({
+                method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+                url: z.string(),
+                headers: z.record(z.string(), z.string()).optional(),
+                json: z.unknown().optional().describe("JSON body"),
+            }),
+            execute: async ({ method, url, headers, json }) => {
+                const safe = await assertPublicUrl(url);
+                await ctx.emit("tool", `${method} ${safe.hostname}${safe.pathname}`);
+                const res = await safeFetch(safe.toString(), {
+                    method,
+                    signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(30_000)]),
+                    headers: {
+                        ...(json !== undefined ? { "content-type": "application/json" } : {}),
+                        ...headers,
+                    },
+                    body: json !== undefined ? JSON.stringify(json) : undefined,
+                });
+                return { status: res.status, body: clip(await res.text(), 8000) };
+            },
+        });
+    }
+    const files = new FileKeeper(ctx, assets);
+    if (allowed.has("browser")) {
+        Object.assign(tools, browserTools(ctx, assets, files));
+    }
+    // The wizard's lists and files, the documents the person gave and the project's documents are
+    // always at hand.
+    Object.assign(tools, storeTools(ctx, uploads, files));
+    Object.assign(tools, projectTools(ctx));
+    Object.assign(tools, mailTools(step, ctx, files));
+    Object.assign(tools, await connectorTools(step, ctx, files));
+    const sandbox = sandboxCapabilities();
+    if (allowed.has("sandbox") && sandbox) {
+        const timeoutMs = (seconds) => Math.min((seconds ?? 120) * 1000, 600_000);
+        const report = (result) => ({
+            exitCode: result.exitCode,
+            stdout: clip(result.stdout, 8000),
+            stderr: clip(result.stderr, 4000),
+        });
+        tools.run_command = createTool({
+            id: "run_command",
+            description: shellToolDescription(sandbox),
+            inputSchema: z.object({ command: z.string(), timeoutSeconds: z.number().optional() }),
+            execute: async ({ command, timeoutSeconds }) => {
+                await ctx.emit("tool", `Führt aus: ${command.slice(0, 80)}`);
+                return report(await ctx.resources
+                    .sandboxHandle()
+                    .exec(command, { timeoutMs: timeoutMs(timeoutSeconds) }));
+            },
+        });
+        if (sandbox.python === "tool") {
+            tools.run_python = createTool({
+                id: "run_python",
+                description: pythonToolDescription(sandbox),
+                inputSchema: z.object({
+                    code: z.string(),
+                    packages: z.array(z.string()).optional().describe("PyPI packages the code imports"),
+                    timeoutSeconds: z.number().optional(),
+                }),
+                execute: async ({ code, packages, timeoutSeconds }) => {
+                    await ctx.emit("tool", "Führt Python aus");
+                    return report(await ctx.resources.sandboxHandle().runPython(code, {
+                        packages,
+                        timeoutMs: timeoutMs(timeoutSeconds),
+                    }));
+                },
+            });
+        }
+        tools.export_file = createTool({
+            id: "export_file",
+            description: "Hand a file from the sandbox to the person as a result (e.g. a chart PNG, a CSV).",
+            inputSchema: z.object({
+                path: z.string(),
+                mime: z.string().describe("e.g. image/png, text/csv"),
+            }),
+            execute: async ({ path, mime }) => {
+                let bytes;
+                try {
+                    bytes = await ctx.resources.sandboxHandle().readFile(path);
+                }
+                catch (err) {
+                    return { error: err.message || "file not found" };
+                }
+                const ref = await ctx.saveAsset({
+                    kind: mime.startsWith("image/") ? "image" : "file",
+                    mime,
+                    name: path.split("/").pop() ?? "file",
+                    data: Buffer.from(bytes),
+                });
+                assets.push(ref);
+                return { saved: true, assetId: ref.id };
+            },
+        });
+    }
+    if (allowed.has("image")) {
+        tools.generate_image = createTool({
+            id: "generate_image",
+            description: "Draw an image from a detailed visual prompt. The image is shown to the person.",
+            inputSchema: z.object({
+                prompt: z.string(),
+                aspectRatio: z.enum(["1:1", "16:9", "9:16", "4:5", "3:2", "2:3"]).optional(),
+            }),
+            execute: async ({ prompt, aspectRatio }) => {
+                await ctx.emit("tool", "Zeichnet ein Bild");
+                const media = await generateImageMedia({
+                    call: ctx.call,
+                    prompt,
+                    aspectRatio,
+                    abortSignal: ctx.signal,
+                });
+                await ctx.chargeUsd(media.costUsd);
+                const ref = await ctx.saveAsset({
+                    kind: "image",
+                    mime: media.mime,
+                    name: "image.png",
+                    data: markMedia(media.bytes, media.mime, { origin: "generated", system: media.system }),
+                    ai: "generated",
+                });
+                assets.push(ref);
+                return { saved: true, assetId: ref.id };
+            },
+        });
+    }
+    // The wizard's workspace (reference data, price lists, templates) is always readable.
+    if (ctx.files.length) {
+        tools.read_workspace_file = createTool({
+            id: "read_workspace_file",
+            description: `Read a file from the wizard's workspace. Files: ${ctx.files
+                .slice(0, 60)
+                .map((f) => f.path)
+                .join(", ")}`,
+            inputSchema: z.object({ path: z.string() }),
+            execute: async ({ path }) => {
+                const found = await snapshotFile(ctx.files, path);
+                if (!found) {
+                    return { error: `No file ${path}` };
+                }
+                return isTextMime(found.file.mime)
+                    ? { path, text: clip(found.data.toString("utf8"), 40_000) }
+                    : { path, mime: found.file.mime, size: found.file.size, note: "binary file" };
+            },
+        });
+    }
+    const servers = ctx.project.mcpServers.filter((s) => step.mcp?.includes(s.id));
+    if (servers.length) {
+        mcp = new MCPClient({
+            id: `run-${ctx.runId}-${step.id}`,
+            servers: Object.fromEntries(servers.map((s) => [
+                s.id,
+                { url: new URL(s.url), requestInit: { headers: s.headers ?? {} }, timeout: 60_000 },
+            ])),
+        });
+        try {
+            Object.assign(tools, await mcp.listTools());
+            await ctx.emit("tool", `Verbunden mit ${servers.map((s) => s.name).join(", ")}`);
+        }
+        catch (err) {
+            await ctx.emit("info", `MCP-Server nicht erreichbar: ${err.message}`);
+        }
+    }
+    return {
+        tools,
+        assets,
+        close: async () => {
+            await mcp?.disconnect().catch(() => undefined);
+        },
+    };
+}

package/apps/runtime/dist/tools/mail.js

@@ -0,0 +1,104 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { connectionContext } from "../connectors/index.js";
+import { mailAction, mailSearchInput, } from "../connectors/mail.js";
+import { htmlToPdf } from "../render/convert.js";
+import { guardHtml } from "../render/guard.js";
+import { attempt, clip } from "./shared.js";
+const NOT_CONNECTED = "The person has not connected a mailbox. Go on without mail and say in your result that the mailbox is not connected.";
+/**
+ * Read-only mail for a step that names a mail connection. The tools are the same whichever
+ * provider the person connected; attachments never pass through the model — they are saved.
+ */
+export function mailTools(step, ctx, files) {
+    const connection = (ctx.def.connections ?? []).find((c) => c.kind === "mail" && step.connections?.includes(c.id));
+    if (!connection) {
+        return {};
+    }
+    const open = async () => {
+        const found = await connectionContext(ctx.store, connection, ctx.project.id);
+        if (!found) {
+            throw new Error(NOT_CONNECTED);
+        }
+        return found;
+    };
+    const tools = {};
+    tools.mail_search = createTool({
+        id: "mail_search",
+        description: "Search the person's mailbox (read-only), newest first. Returns id, date, sender, subject, snippet and attachments (id, name, size) of each mail. Search broadly with several terms at once rather than one call per word.",
+        inputSchema: mailSearchInput,
+        execute: (input) => attempt(async () => {
+            const { connector, ctx: actionCtx, label } = await open();
+            await ctx.emit("tool", `Durchsucht ${label}`);
+            const { mails } = await mailAction(connector, "search", input, actionCtx);
+            return {
+                mailbox: label,
+                total: mails.length,
+                mails: mails.map((m) => ({ ...m, snippet: m.snippet.slice(0, 200) })),
+            };
+        }),
+    });
+    tools.mail_read = createTool({
+        id: "mail_read",
+        description: "Read one mail in full: sender, recipients, text, attachments.",
+        inputSchema: z.object({ id: z.string() }),
+        execute: ({ id }) => attempt(async () => {
+            const { connector, ctx: actionCtx } = await open();
+            const mail = await mailAction(connector, "read", { id }, actionCtx);
+            const { html: _html, ...rest } = mail;
+            return { ...rest, text: clip(mail.text, 6000) };
+        }),
+    });
+    tools.mail_save = createTool({
+        id: "mail_save",
+        description: "Keep mail attachments (invoice PDFs) as files, several at once: each is stored under `path` in the wizard's files and added to this step's result. Leave attachment_id out to keep the mail itself as a PDF — for receipts that only exist as mail text. Then read them with scan_documents or read_document.",
+        inputSchema: z.object({
+            items: z
+                .array(z.object({
+                id: z.string().describe("Mail id from mail_search."),
+                attachment_id: z.string().optional(),
+                path: z.string().describe("e.g. invoices/2026-09/2026-09-03_Notion_INV-123.pdf"),
+            }))
+                .min(1)
+                .max(40),
+        }),
+        execute: ({ items }) => attempt(async () => {
+            const { connector, ctx: actionCtx, label } = await open();
+            await ctx.emit("tool", `Speichert ${items.length} Belege aus ${label}`);
+            const saved = [];
+            for (const item of items) {
+                try {
+                    if (item.attachment_id) {
+                        const a = await mailAction(connector, "get_attachment", { id: item.id, attachment_id: item.attachment_id }, actionCtx);
+                        const kept = await files.keep(item.path, Buffer.from(a.data_base64, "base64"), {
+                            mime: a.mime,
+                            source: `E-Mail-Anhang „${a.name}“ aus ${label}`,
+                        });
+                        saved.push({ id: item.id, saved: kept.path, size: kept.size });
+                    }
+                    else {
+                        const mail = await mailAction(connector, "read", { id: item.id }, actionCtx);
+                        const page = mail.html ??
+                            `<pre style="white-space:pre-wrap;font:14px system-ui">${escapeHtml(mail.text)}</pre>`;
+                        const head = `<div style="font:13px system-ui;color:#444;border-bottom:1px solid #ddd;padding-bottom:8px;margin-bottom:12px">${escapeHtml(mail.from ?? "")}<br>${escapeHtml(mail.date ?? "")}<br><b>${escapeHtml(mail.subject ?? "")}</b></div>`;
+                        // The mail's own HTML is rendered offline: its remote images and scripts never load.
+                        const pdf = await htmlToPdf(guardHtml(`<!doctype html><html><body>${head}${page}</body></html>`));
+                        const kept = await files.keep(item.path.replace(/(\.pdf)?$/i, ".pdf"), pdf, {
+                            mime: "application/pdf",
+                            source: `E-Mail „${mail.subject ?? ""}“ aus ${label}`,
+                        });
+                        saved.push({ id: item.id, saved: kept.path, size: kept.size });
+                    }
+                }
+                catch (err) {
+                    saved.push({ id: item.id, error: String(err.message).slice(0, 200) });
+                }
+            }
+            return { saved };
+        }),
+    });
+    return tools;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/apps/runtime/dist/tools/net-guard.js

@@ -0,0 +1,59 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+const ALLOW_PRIVATE = process.env.ALLOW_PRIVATE_FETCH === "1";
+function privateV4(ip) {
+    const [a, b] = ip.split(".").map(Number);
+    return (a === 10 ||
+        a === 127 ||
+        a === 0 ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 100 && b >= 64 && b <= 127));
+}
+function privateV6(ip) {
+    const s = ip.toLowerCase();
+    return (s === "::1" || s === "::" || s.startsWith("fc") || s.startsWith("fd") || s.startsWith("fe80"));
+}
+/** Agents may reach the public internet, never this server's own network. */
+export async function assertPublicUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`Not a valid URL: ${raw}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("Only http and https URLs are allowed.");
+    }
+    if (ALLOW_PRIVATE) {
+        return url;
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) {
+        throw new Error("Private addresses are not reachable from a wizard.");
+    }
+    const addresses = isIP(host)
+        ? [{ address: host, family: isIP(host) }]
+        : await lookup(host, { all: true });
+    for (const a of addresses) {
+        if (a.family === 4 ? privateV4(a.address) : privateV6(a.address)) {
+            throw new Error("Private addresses are not reachable from a wizard.");
+        }
+    }
+    return url;
+}
+/** fetch that re-checks every redirect hop, so a public URL cannot bounce into the private network. */
+export async function safeFetch(raw, init = {}) {
+    let url = await assertPublicUrl(raw);
+    for (let hop = 0; hop < 6; hop++) {
+        const res = await fetch(url, { ...init, redirect: "manual" });
+        const location = res.headers.get("location");
+        if (res.status < 300 || res.status >= 400 || !location) {
+            return res;
+        }
+        url = await assertPublicUrl(new URL(location, url).toString());
+    }
+    throw new Error("Too many redirects.");
+}

package/apps/runtime/dist/tools/project.js

@@ -0,0 +1,53 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { documentText, searchProject } from "../services/project-index.js";
+import { attempt, clip } from "./shared.js";
+/** The project's documents, for every agent step of its wizards: search the index, read one whole. */
+export function projectTools(ctx) {
+    const docs = ctx.projectFiles.filter((f) => f.kind === "document");
+    if (!docs.length) {
+        return {};
+    }
+    return {
+        project_search: createTool({
+            id: "project_search",
+            description: "Search the project's documents (the knowledge its owner gave for all wizards) and get the passages that fit best. Ask in the documents' language, with the words they would use.",
+            inputSchema: z.object({
+                query: z.string().describe("What to look for: a question or keywords"),
+                limit: z.number().int().min(1).max(12).optional(),
+            }),
+            execute: ({ query, limit }) => attempt(async () => {
+                await ctx.emit("tool", `Sucht in den Dokumenten: ${query.slice(0, 60)}`);
+                const hits = await searchProject(ctx.project.id, query, limit ?? 6);
+                return {
+                    passages: hits.map((h) => ({ document: h.name, part: h.index, text: h.text })),
+                };
+            }),
+        }),
+        project_document: createTool({
+            id: "project_document",
+            description: "Read one of the project's documents as text. Long documents come in parts: pass `from` to continue.",
+            inputSchema: z.object({
+                name: z.string().describe("The document's name, as listed"),
+                from: z.number().int().min(0).optional().describe("Character to start at"),
+            }),
+            execute: ({ name, from }) => attempt(async () => {
+                const doc = docs.find((d) => d.name === name) ??
+                    docs.find((d) => d.name.toLowerCase().includes(name.toLowerCase()));
+                if (!doc) {
+                    throw new Error(`No document "${name}". There are: ${docs.map((d) => d.name).join(", ")}`);
+                }
+                await ctx.emit("tool", `Liest ${doc.name}`);
+                const text = await documentText(doc);
+                const start = Math.min(from ?? 0, text.length);
+                const part = text.slice(start, start + 12_000);
+                return {
+                    document: doc.name,
+                    text: clip(part, 12_000),
+                    next: start + part.length < text.length ? start + part.length : null,
+                    length: text.length,
+                };
+            }),
+        }),
+    };
+}