@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,170 @@
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import { Agent } from "undici";
+const ALLOW_PRIVATE = process.env.ALLOW_PRIVATE_FETCH === "1";
+/** Ranges that are not the public internet: this server, its networks, and special purposes. */
+const blocked = new BlockList();
+for (const [net, prefix] of [
+    ["0.0.0.0", 8], // "this" network
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10], // carrier-grade NAT
+    ["127.0.0.0", 8], // loopback
+    ["169.254.0.0", 16], // link-local, the cloud metadata service
+    ["172.16.0.0", 12], // also the Docker networks, the browser's DevTools among them
+    ["192.0.0.0", 24], // protocol assignments
+    ["192.0.2.0", 24], // documentation
+    ["192.88.99.0", 24], // 6to4 relays
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15], // benchmarking
+    ["198.51.100.0", 24], // documentation
+    ["203.0.113.0", 24], // documentation
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved, and the broadcast address
+]) {
+    blocked.addSubnet(net, prefix, "ipv4");
+}
+for (const [net, prefix] of [
+    ["::", 128], // unspecified
+    ["::1", 128], // loopback
+    ["64:ff9b:1::", 48], // NAT64 for local use
+    ["100::", 64], // discard
+    ["2001::", 32], // Teredo: a tunnel to an IPv4 address
+    ["2001:db8::", 32], // documentation
+    ["fc00::", 7], // unique local
+    ["fe80::", 10], // link-local
+    ["fec0::", 10], // site-local
+    ["ff00::", 8], // multicast
+]) {
+    blocked.addSubnet(net, prefix, "ipv6");
+}
+/** The eight 16-bit words of an IPv6 address (the caller has checked it is one). */
+function words(ip) {
+    let s = ip.split("%")[0].toLowerCase();
+    const v4 = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(s);
+    if (v4) {
+        const [a, b, c, d] = v4.slice(1).map(Number);
+        s = `${s.slice(0, v4.index)}${(a * 256 + b).toString(16)}:${(c * 256 + d).toString(16)}`;
+    }
+    const [head, tail] = s.split("::");
+    const part = (x) => x ? x.split(":").map((w) => Number.parseInt(w, 16)) : [];
+    const h = part(head);
+    const t = part(tail);
+    return tail === undefined ? h : [...h, ...new Array(8 - h.length - t.length).fill(0), ...t];
+}
+const dotted = (hi, lo) => [Math.floor(hi / 256), hi % 256, Math.floor(lo / 256), lo % 256].join(".");
+/**
+ * The IPv4 address an IPv6 address stands for: mapped (::ffff:a.b.c.d, also written
+ * ::ffff:a9fe:a9fe), translated, compatible (::a.b.c.d), NAT64 (64:ff9b::/96) and 6to4 (2002::/16).
+ * Connecting to any of them can reach that IPv4 address.
+ */
+function embeddedV4(w) {
+    const zero = (from, to) => w.slice(from, to).every((x) => x === 0);
+    if (zero(0, 5) && w[5] === 0xffff) {
+        return dotted(w[6], w[7]);
+    }
+    if (zero(0, 4) && w[4] === 0xffff && w[5] === 0) {
+        return dotted(w[6], w[7]);
+    }
+    if (zero(0, 6)) {
+        return dotted(w[6], w[7]);
+    }
+    if (w[0] === 0x64 && w[1] === 0xff9b && zero(2, 6)) {
+        return dotted(w[6], w[7]);
+    }
+    if (w[0] === 0x2002) {
+        return dotted(w[1], w[2]);
+    }
+    return null;
+}
+/** Whether an IP address is on the public internet. Anything that is not an IP address is not. */
+export function isPublicAddress(ip) {
+    const bare = ip.replace(/^\[|\]$/g, "");
+    const family = isIP(bare);
+    if (family === 4) {
+        return !blocked.check(bare, "ipv4");
+    }
+    if (family !== 6) {
+        return false;
+    }
+    const w = words(bare);
+    const v4 = embeddedV4(w);
+    if (v4) {
+        return isPublicAddress(v4);
+    }
+    return !blocked.check(w.map((x) => x.toString(16)).join(":"), "ipv6");
+}
+const PRIVATE = "Private addresses are not reachable from a wizard.";
+/** The host's addresses, each of them public; throws if any one is not. */
+async function publicAddresses(host) {
+    const family = isIP(host);
+    const addresses = family ? [{ address: host, family }] : await lookup(host, { all: true });
+    if (!ALLOW_PRIVATE && (!addresses.length || addresses.some((a) => !isPublicAddress(a.address)))) {
+        throw new Error(PRIVATE);
+    }
+    return addresses;
+}
+/** 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);
+    }
+    await publicAddresses(host);
+    return url;
+}
+/**
+ * Connects only to addresses that passed the check: the name is resolved and checked again at
+ * connect time, and the socket gets exactly those addresses, so a DNS answer that changes between
+ * the check and the connect (rebinding) cannot point it into the private network. TLS still
+ * verifies, and the Host header still names, the host of the URL.
+ */
+const pinned = new Agent({
+    connect: {
+        lookup(host, options, callback) {
+            publicAddresses(host).then((addresses) => {
+                const usable = options.family
+                    ? addresses.filter((a) => a.family === options.family)
+                    : addresses;
+                if (!usable.length) {
+                    callback(Object.assign(new Error(`No address for ${host}`), { code: "ENOTFOUND" }));
+                }
+                else if (options.all) {
+                    callback(null, usable);
+                }
+                else {
+                    callback(null, usable[0].address, usable[0].family);
+                }
+            }, callback);
+        },
+    },
+});
+/** 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",
+            dispatcher: pinned,
+        });
+        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/pages.js

@@ -0,0 +1,81 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { runPages, writeRunPage } from "../services/space-data.js";
+import { pageReadInput, readKnowledgePage } from "./project.js";
+import { attempt, clip } from "./shared.js";
+/**
+ * Pages for a step that lists "pages": Markdown its wizard keeps for every run — notes, a log, a
+ * summary that grows — its memory, shown in the studio's Memory tab and under Space → Data. Its
+ * page_read also reads the pages of Knowledge, by path. A test run reads the wizard's pages but
+ * writes into a copy of its own in the run's state, which goes with the run.
+ */
+export function pageTools(ctx) {
+    const projectId = ctx.project.id;
+    const wizardId = ctx.store.wizardId;
+    /** The wizard's pages as this run sees them: a test run's own writes over the real ones. */
+    const pages = async () => {
+        const real = await runPages(projectId, wizardId);
+        const copy = ctx.test ? (ctx.state.memory ?? {}) : {};
+        const lower = (t) => t.toLowerCase();
+        const written = Object.entries(copy).map(([title, markdown]) => ({ title, markdown }));
+        return [
+            ...real.filter((p) => !written.some((w) => lower(w.title) === lower(p.title))),
+            ...written,
+        ].sort((a, b) => a.title.localeCompare(b.title));
+    };
+    return {
+        page_read: createTool({
+            id: "page_read",
+            description: "Read a page: one this wizard wrote, by its title, or a page of Knowledge, by its path (pages/…). Without either it lists the wizard's pages.",
+            inputSchema: z.object({
+                title: z.string().optional().describe("A page this wizard wrote"),
+                path: pageReadInput.path.optional(),
+                section: pageReadInput.section,
+                from: pageReadInput.from,
+            }),
+            execute: ({ title, path, section, from }) => {
+                if (path?.trim()) {
+                    return readKnowledgePage(ctx, { path, section, from });
+                }
+                return attempt(async () => {
+                    const all = await pages();
+                    if (!title?.trim()) {
+                        return { pages: all.map((p) => ({ title: p.title, chars: p.markdown.length })) };
+                    }
+                    const page = all.find((p) => p.title.toLowerCase() === title.trim().toLowerCase());
+                    if (!page) {
+                        return { error: `No page "${title}".`, pages: all.map((p) => p.title) };
+                    }
+                    return { title: page.title, markdown: clip(page.markdown, 40_000) };
+                });
+            },
+        }),
+        page_write: createTool({
+            id: "page_write",
+            description: "Write a page of this wizard in Markdown, kept for every later run and shown to the admin in the studio. A page with the same title is replaced — or added to with append: true (a log, a list that grows). Pages of Knowledge are read-only.",
+            inputSchema: z.object({
+                title: z.string().min(1).max(200),
+                markdown: z.string().max(200_000),
+                append: z.boolean().optional(),
+            }),
+            execute: (input) => attempt(async () => {
+                if (ctx.test) {
+                    const title = input.title.trim();
+                    const before = (await pages()).find((p) => p.title.toLowerCase() === title.toLowerCase());
+                    const markdown = before && input.append
+                        ? `${before.markdown.trimEnd()}\n\n${input.markdown.trim()}`
+                        : input.markdown;
+                    ctx.state.memory = { ...ctx.state.memory, [before?.title ?? title]: markdown };
+                    await ctx.emit("tool", {
+                        code: "writesPage",
+                        params: { title: before?.title ?? title },
+                    });
+                    return { title: before?.title ?? title, chars: markdown.length, test: true };
+                }
+                const page = await writeRunPage(projectId, wizardId, input);
+                await ctx.emit("tool", { code: "writesPage", params: { title: page.title } });
+                return page;
+            }),
+        }),
+    };
+}

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

@@ -0,0 +1,180 @@
+import { pluginToolOf } from "@engenty-wizards/shared/definition";
+import { note } from "@engenty-wizards/shared/run";
+import { createTool } from "@mastra/core/tools";
+import { StepError } from "../engine/types.js";
+import { loadedPlugin, pluginIdsOf, pluginsOf } from "../plugins/registry.js";
+import { attempt, clip } from "./shared.js";
+/** The model's name of a plugin's tool: `<plugin>_<tool>`, since a tool name takes no dot. */
+export function pluginToolName(plugin, tool) {
+    return `${plugin.replaceAll("-", "_")}_${tool}`;
+}
+/** What a plugin's tool learns of the step that calls it. */
+function toolContext(ctx) {
+    const space = { id: ctx.project.id, name: ctx.project.name };
+    return {
+        runId: ctx.runId,
+        stepId: ctx.stepId,
+        tenantId: ctx.tenantId,
+        space,
+        project: space,
+        wizard: { id: ctx.store.wizardId, title: ctx.def.title },
+        mode: ctx.test ? "test" : "live",
+        signal: ctx.signal,
+        emit: (message) => ctx.emit("tool", message),
+    };
+}
+/** A plugin's tool as an agent step calls it. */
+function stepTool(plugin, tool, ctx) {
+    return createTool({
+        id: pluginToolName(plugin, tool.name),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        execute: (input) => attempt(async () => tool.execute(input, toolContext(ctx))),
+    });
+}
+/** A plugin's tool by its `<plugin>.<tool>` id, as this tenant has it; a StepError where it does not. */
+async function toolOf(id, ctx) {
+    const named = pluginToolOf(id);
+    const has = named ? await pluginIdsOf(ctx.tenantId) : new Set();
+    const found = named && has.has(named.plugin) ? loadedPlugin(named.plugin)?.tools.get(named.tool) : undefined;
+    if (!(named && found)) {
+        const plugin = named?.plugin ?? id;
+        throw new StepError(note("stepNeedsToolPlugin", { id, plugin }));
+    }
+    return { plugin: named.plugin, tool: found };
+}
+/**
+ * Calls one plugin tool with its input as it is, no model between: a step's `call`. The input
+ * is checked against the tool's schema; what the tool throws is the step's error.
+ */
+export async function callPluginTool(id, input, ctx) {
+    const { tool } = await toolOf(id, ctx);
+    const parsed = tool.inputSchema.safeParse(input);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new StepError(note("pluginInvalidInput", {
+            id,
+            path: issue?.path.join(".") || "input",
+            problem: issue?.message ?? "",
+        }));
+    }
+    try {
+        return await tool.execute(parsed.data, toolContext(ctx));
+    }
+    catch (err) {
+        throw new StepError(String(err?.message ?? err).slice(0, 400));
+    }
+}
+/**
+ * The tools of plugins a step allowlists as `<plugin>.<tool>`. A step that names a tool this
+ * tenant does not have fails: the wizard was written for a runtime with that plugin.
+ */
+export async function pluginTools(step, ctx) {
+    const tools = {};
+    for (const id of step.tools.filter((t) => pluginToolOf(t) !== null)) {
+        const { plugin, tool } = await toolOf(id, ctx);
+        tools[pluginToolName(plugin, tool.name)] = stepTool(plugin, tool, ctx);
+    }
+    return tools;
+}
+/** A block of a plugin is cut here: the step's instructions stay the step's. */
+const MAX_BLOCK = 8000;
+const contexts = new WeakMap();
+/**
+ * What the tenant's plugins add to an AI step of a space's wizard (`registerSpaceContext`):
+ * asked once per step, for its instructions and for its tools — an agent step's, or an HTML
+ * step's blocks. A context that fails adds nothing.
+ */
+export function spaceContextOf(ctx) {
+    let found = contexts.get(ctx);
+    if (!found) {
+        found = gather(ctx);
+        contexts.set(ctx, found);
+    }
+    return found;
+}
+async function gather(ctx) {
+    const space = { id: ctx.project.id, name: ctx.project.name };
+    const result = { blocks: [], html: [], tools: {} };
+    for (const plugin of await pluginsOf(ctx.tenantId)) {
+        for (const context of plugin.contexts) {
+            const steps = context.steps ?? ["agent"];
+            const block = await Promise.resolve()
+                .then(() => context.block(space))
+                .catch((err) => {
+                console.error(`[plugin ${plugin.source.id}] space context:`, err);
+                return null;
+            });
+            if (!block?.trim()) {
+                continue;
+            }
+            if (steps.includes("html")) {
+                result.html.push(clip(block.trim(), MAX_BLOCK));
+            }
+            if (!steps.includes("agent")) {
+                continue;
+            }
+            result.blocks.push(clip(block.trim(), MAX_BLOCK));
+            for (const tool of context.tools ?? []) {
+                result.tools[pluginToolName(plugin.source.id, tool.name)] = stepTool(plugin.source.id, tool, ctx);
+            }
+        }
+    }
+    return result;
+}
+/** The tenant's plugins' tools of the space assistant (`registerAssistantTool`). */
+export async function assistantToolsOf(turn) {
+    const tools = {};
+    for (const plugin of await pluginsOf(turn.tenantId)) {
+        for (const tool of plugin.assistantTools.values()) {
+            const id = pluginToolName(plugin.source.id, tool.name);
+            tools[id] = createTool({
+                id,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                execute: (input) => attempt(async () => {
+                    const result = await tool.execute(input, {
+                        tenantId: turn.tenantId,
+                        space: turn.space,
+                        userId: turn.userId,
+                        signal: turn.signal,
+                        emit: turn.emit,
+                        changed: turn.changed,
+                    });
+                    if (tool.card) {
+                        turn.card({ plugin: plugin.source.id, tool: tool.name, data: result ?? null });
+                    }
+                    return result;
+                }),
+            });
+        }
+    }
+    return tools;
+}
+/**
+ * The admin talks to the space assistant from a plugin's own page: what the plugin says that page
+ * holds now, and its name. `null` when the tenant has no such plugin.
+ */
+export async function assistantPageOf(tenantId, pluginId, space) {
+    const plugin = (await pluginsOf(tenantId)).find((p) => p.source.id === pluginId);
+    if (!plugin) {
+        return null;
+    }
+    const blocks = [];
+    for (const page of plugin.assistantPages) {
+        try {
+            const text = await page.block(space);
+            if (text?.trim()) {
+                blocks.push(text.trim().slice(0, MAX_BLOCK));
+            }
+        }
+        catch (err) {
+            console.error(`[plugins] ${pluginId}: the assistant's page block failed:`, err);
+        }
+    }
+    return {
+        name: plugin.source.manifest.name,
+        description: plugin.source.manifest.description ?? null,
+        blocks,
+    };
+}

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

@@ -0,0 +1,154 @@
+import { whereSchema } from "@engenty-wizards/shared/knowledge";
+import { createTool } from "@mastra/core/tools";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+import { db, schema } from "../db/client.js";
+import { filePaths, knowledgeCounts, listForStep, readPage, readTable, resolvePath, } from "../services/knowledge.js";
+import { documentText, hasIndexEntries, searchKnowledge } from "../services/project-index.js";
+import { attempt, clip } from "./shared.js";
+/**
+ * Knowledge, for every agent step of the space's wizards: search it (a question, filtered by
+ * categories first, checked by a classifier after), list it by categories, read a page, a table
+ * or a file whole by its path. Hits and reads look like files — a path, front matter, Markdown or
+ * CSV — so a model reads them as it reads files. The search also finds what the space's plugins
+ * put into the index.
+ */
+const where = whereSchema
+    .optional()
+    .describe('Filter by categories before searching, by their names: a value ("Baustelle": "Graz Süd"), a list of values, a range of numbers ({ "gte": 20000 }) or of days ({ "after": "2026-03-01", "before": "2026-03-31" }), { "contains": "…" } for a text, true/false. project_list without arguments names the categories and their values.');
+export const pageReadInput = {
+    path: z.string().describe("The page's path, as project_search or project_list give it: pages/…"),
+    section: z
+        .string()
+        .optional()
+        .describe("Only this section: a heading of the page, or the start of one"),
+    from: z.number().int().min(0).optional().describe("Character to continue a long page at"),
+};
+/** A page of Knowledge by its path, for a step: its front matter and Markdown, in parts. */
+export function readKnowledgePage(ctx, input) {
+    return attempt(async () => {
+        const read = await readPage(ctx.project.id, input.path, input);
+        await ctx.emit("tool", { code: "reads", params: { name: read.path } });
+        return read;
+    });
+}
+export async function projectTools(ctx) {
+    const projectId = ctx.project.id;
+    const counts = await knowledgeCounts(projectId);
+    const entries = await hasIndexEntries(projectId);
+    if (!(counts.pages || counts.tables || counts.files || entries)) {
+        return {};
+    }
+    const tools = {
+        project_search: createTool({
+            id: "project_search",
+            description: "Search the space's Knowledge: its pages, tables and files, and what its plugins keep (wiki pages, questions and answers). Gives items with their path, categories and best section, each checked for relevance. Ask in their language, with the words they would use; filter with `where` when the task names a category's value. Then read the items you need whole with page_read or table_read.",
+            inputSchema: z.object({
+                query: z.string().describe("What to look for: a question or keywords"),
+                where,
+                limit: z.number().int().min(1).max(12).optional().describe("Items to get, 6 by default"),
+            }),
+            execute: (input) => attempt(async () => {
+                const found = await searchKnowledge(projectId, input.query, {
+                    where: input.where,
+                    limit: input.limit,
+                    signal: ctx.signal,
+                });
+                await ctx.emit("tool", {
+                    code: "searchesKnowledge",
+                    params: {
+                        query: input.query.slice(0, 60),
+                        relevant: found.hits.length,
+                        candidates: found.candidates,
+                    },
+                });
+                return {
+                    hits: found.hits.map((h) => ({
+                        ...(h.path ? { path: h.path } : {}),
+                        title: h.title,
+                        ...(h.categories.length ? { categories: h.categories } : {}),
+                        ...(h.heading ? { section: h.heading } : {}),
+                        ...(h.sheet ? { page: h.sheet } : {}),
+                        ...(h.relevance !== null ? { relevance: h.relevance } : {}),
+                        text: clip(h.text, 1500),
+                    })),
+                    checked: found.checked,
+                    candidates: found.candidates,
+                    ...(found.filtered !== null ? { filtered: found.filtered } : {}),
+                };
+            }),
+        }),
+        project_list: createTool({
+            id: "project_list",
+            description: "List Knowledge by its categories. Without `where`: the categories with their values and how many items each has. With `where`: the items it leaves, with their paths — all of them, where project_search gives the best few.",
+            inputSchema: z.object({ where }),
+            execute: (input) => attempt(async () => {
+                const listed = await listForStep(projectId, input.where);
+                await ctx.emit("tool", { code: "listsKnowledge" });
+                return listed;
+            }),
+        }),
+    };
+    if (counts.pages) {
+        tools.page_read = createTool({
+            id: "page_read",
+            description: "Read a page of Knowledge whole by its path: front matter (title, categories, its source and original, its parent and sub-pages) and its Markdown. Long pages come in parts: pass `from` to continue. `section` reads one section.",
+            inputSchema: z.object(pageReadInput),
+            execute: (input) => readKnowledgePage(ctx, input),
+        });
+    }
+    if (counts.tables) {
+        tools.table_read = createTool({
+            id: "table_read",
+            description: "Read a table of Knowledge by its path: its rows as CSV, filtered by its columns (by their names, like `where` of project_search). A few hundred rows at a time: pass `offset` to continue.",
+            inputSchema: z.object({
+                path: z.string().describe("The table's path: tables/…"),
+                where: whereSchema.optional().describe("Filter by columns, by their names"),
+                columns: z.array(z.string()).max(40).optional().describe("Only these columns"),
+                limit: z.number().int().min(1).max(1000).optional(),
+                offset: z.number().int().min(0).optional(),
+            }),
+            execute: (input) => attempt(async () => {
+                const read = await readTable(projectId, input.path, input);
+                await ctx.emit("tool", { code: "reads", params: { name: read.path } });
+                return read;
+            }),
+        });
+    }
+    if (counts.files) {
+        tools.project_document = createTool({
+            id: "project_document",
+            description: "Read a file of Knowledge as text by its path (files/…): a file that is not a page, or the original a page was read from. Long files come in parts: pass `from` to continue.",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("The file's path: files/…, as the page's front matter or a hit names it"),
+                from: z.number().int().min(0).optional().describe("Character to start at"),
+            }),
+            execute: ({ path, from }) => attempt(async () => {
+                const found = await resolvePath(projectId, path.startsWith("files/") ? path : `files/${path}`);
+                if (found?.kind !== "file") {
+                    const there = [...(await filePaths(projectId)).values()].slice(0, 40);
+                    throw new Error(`No file "${path}". There are: ${there.join(", ")}`);
+                }
+                const file = await db.query.projectFile.findFirst({
+                    where: and(eq(schema.projectFile.id, found.id), eq(schema.projectFile.projectId, projectId)),
+                });
+                if (!file) {
+                    throw new Error(`No file "${path}".`);
+                }
+                await ctx.emit("tool", { code: "reads", params: { name: file.name } });
+                const text = (await documentText(file)) || file.description;
+                const start = Math.min(from ?? 0, text.length);
+                const part = text.slice(start, start + 12_000);
+                return {
+                    path: found.path,
+                    text: clip(part, 12_000),
+                    next: start + part.length < text.length ? start + part.length : null,
+                    length: text.length,
+                };
+            }),
+        });
+    }
+    return tools;
+}

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

@@ -0,0 +1,69 @@
+import { ServiceError } from "../services/errors.js";
+import { writeStoreFile } from "../store/index.js";
+export const TEXT_LIMIT = 8000;
+export function clip(s, limit = TEXT_LIMIT) {
+    return s.length > limit ? `${s.slice(0, limit)}\n…[truncated ${s.length - limit} chars]` : s;
+}
+/**
+ * A tool failure is something the model reads and reacts to, never a crashed step or turn. A
+ * service's refusal brings its data along (`issues`, `fields`, `column`), so the model can fix
+ * what it sent. The message is clipped to `limit` characters (400): a site or an API can answer
+ * with a whole page; the studio's agents, whose failures are the runtime's own, pass `Infinity`.
+ */
+export async function attempt(run, { limit = 400 } = {}) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        const error = String(err?.message ?? err).slice(0, limit);
+        return err instanceof ServiceError ? { error, ...err.data } : { error };
+    }
+}
+/**
+ * A tool's `toModelOutput` for a result that carries a picture: the base64 under `key` goes to the
+ * model as an image (of `mime`, else PNG), the rest as text beside it – as JSON, or as `text`
+ * makes it. A result without the picture, a failure among them, goes as JSON.
+ */
+export function imageOutput(key, text = (rest) => JSON.stringify(rest)) {
+    return (out) => {
+        if (!out || out.error || typeof out[key] !== "string" || !out[key]) {
+            return { type: "json", value: out };
+        }
+        const { [key]: data, mime, ...rest } = out;
+        return {
+            type: "content",
+            value: [
+                { type: "text", text: text(rest) },
+                { type: "image-data", data, mediaType: mime ?? "image/png" },
+            ],
+        };
+    };
+}
+/**
+ * Files a step collects go two places: the wizard's store (kept for next time) and the step's
+ * result (this run's download). One keeper per step, so a file saved twice is one result.
+ */
+export class FileKeeper {
+    ctx;
+    assets;
+    kept = new Map();
+    constructor(ctx, assets) {
+        this.ctx = ctx;
+        this.assets = assets;
+    }
+    async keep(rawPath, data, meta) {
+        const scope = this.ctx.store;
+        const file = await writeStoreFile(scope, rawPath, data, meta);
+        if (!this.kept.has(file.path)) {
+            const ref = await this.ctx.saveAsset({
+                kind: "file",
+                mime: file.mime,
+                name: file.path.split("/").pop() ?? "file",
+                data,
+            });
+            this.kept.set(file.path, ref);
+            this.assets.push(ref);
+        }
+        return { path: file.path, mime: file.mime, size: file.size };
+    }
+}