wizards 0.1.9

package/apps/runtime/dist/tenants/control.js

@@ -0,0 +1,106 @@
+import { and, count, eq, gte, inArray, or } from "drizzle-orm";
+import { control, controlDb } from "../db/client.js";
+import { env } from "../env.js";
+import { currentTenant } from "./tenant.js";
+/** Remembers which tenant a public token belongs to. */
+export async function putLink(token, kind, ref) {
+    await controlDb
+        .insert(control.link)
+        .values({ token, tenantId: currentTenant(), kind, ref })
+        .onConflictDoUpdate({
+        target: control.link.token,
+        set: { tenantId: currentTenant(), kind, ref },
+    });
+}
+export async function dropLinks(tokens) {
+    if (tokens.length) {
+        await controlDb.delete(control.link).where(inArray(control.link.token, tokens));
+    }
+}
+export async function tenantOfLink(token, kind) {
+    const row = await controlDb.query.link.findFirst({
+        where: and(eq(control.link.token, token), eq(control.link.kind, kind)),
+    });
+    return row?.tenantId ?? null;
+}
+// --- runs ----------------------------------------------------------------------
+const runTenants = new Map();
+export async function indexRun(input) {
+    const tenantId = currentTenant();
+    runTenants.set(input.runId, tenantId);
+    await controlDb.insert(control.runIndex).values({
+        runId: input.runId,
+        tenantId,
+        visitorId: input.visitorId ?? null,
+        ipHash: input.ipHash ?? null,
+    });
+}
+export async function tenantOfRun(runId) {
+    const known = runTenants.get(runId);
+    if (known) {
+        return known;
+    }
+    const row = await controlDb.query.runIndex.findFirst({
+        where: eq(control.runIndex.runId, runId),
+    });
+    if (row) {
+        runTenants.set(runId, row.tenantId);
+        if (runTenants.size > 5000) {
+            runTenants.delete(runTenants.keys().next().value);
+        }
+    }
+    return row?.tenantId ?? null;
+}
+export async function dropRuns(runIds) {
+    for (const id of runIds) {
+        runTenants.delete(id);
+    }
+    for (let i = 0; i < runIds.length; i += 200) {
+        await controlDb
+            .delete(control.runIndex)
+            .where(inArray(control.runIndex.runId, runIds.slice(i, i + 200)));
+    }
+}
+/** Marks a run as working, so a restart finds it again. */
+export async function markRunActive(runId, active) {
+    await controlDb.update(control.runIndex).set({ active }).where(eq(control.runIndex.runId, runId));
+}
+/** The runs that were working when the process stopped, with their tenants. */
+export async function activeRuns() {
+    return controlDb
+        .select({ runId: control.runIndex.runId, tenantId: control.runIndex.tenantId })
+        .from(control.runIndex)
+        .where(eq(control.runIndex.active, true));
+}
+/** A visitor's runs are counted across every wizard of every tenant. */
+export async function visitorOverLimit(visitorId, ipHash) {
+    const since = new Date(Date.now() - 3600_000);
+    const who = ipHash
+        ? or(eq(control.runIndex.visitorId, visitorId), eq(control.runIndex.ipHash, ipHash))
+        : eq(control.runIndex.visitorId, visitorId);
+    const [{ n }] = await controlDb
+        .select({ n: count() })
+        .from(control.runIndex)
+        .where(and(who, gte(control.runIndex.createdAt, since)));
+    return n >= env.limits.visitorRunsPerHour;
+}
+// --- tenants ---------------------------------------------------------------------
+export async function tenantStatus(id) {
+    const row = await controlDb.query.tenant.findFirst({ where: eq(control.tenant.id, id) });
+    return row?.status ?? null;
+}
+export async function setTenantStatus(id, status) {
+    await controlDb.update(control.tenant).set({ status }).where(eq(control.tenant.id, id));
+}
+/** Everything the control database knows about a tenant goes with it. */
+export async function forgetTenantRows(id) {
+    await controlDb.delete(control.link).where(eq(control.link.tenantId, id));
+    await controlDb.delete(control.runIndex).where(eq(control.runIndex.tenantId, id));
+    await controlDb.delete(control.session).where(eq(control.session.tenantId, id));
+    await controlDb.delete(control.tenant).where(eq(control.tenant.id, id));
+    for (const [runId, tenantId] of runTenants) {
+        if (tenantId === id) {
+            runTenants.delete(runId);
+        }
+    }
+}

package/apps/runtime/dist/tenants/tenant.js

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** The tenant a request, a run or a background job works for. Set once per entry, never from a request body. */
+const current = new AsyncLocalStorage();
+export class NoTenantError extends Error {
+    constructor() {
+        super("No tenant in context: tenant tables are reached only inside inTenant().");
+    }
+}
+export function inTenant(tenantId, fn) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(tenantId)) {
+        throw new Error("bad tenant id");
+    }
+    return current.run({ tenantId }, fn);
+}
+export function currentTenant() {
+    const store = current.getStore();
+    if (!store) {
+        throw new NoTenantError();
+    }
+    return store.tenantId;
+}
+export function currentTenantOrNull() {
+    return current.getStore()?.tenantId ?? null;
+}
+/** The one tenant of a runtime that runs alone (desktop app, own machine). */
+export const LOCAL_TENANT = "local";

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

@@ -0,0 +1,380 @@
+import { readFile } from "node:fs/promises";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { assertPublicUrl } from "./net-guard.js";
+import { attempt, clip } from "./shared.js";
+const ref = (n) => `[data-wz-ref="${n}"]`;
+/** The page as an agent reads it: its text and its interactive elements, numbered. */
+export async function pageSnapshot(page) {
+    const data = await page.evaluate(() => {
+        const els = Array.from(document.querySelectorAll("a[href], button, input, textarea, select, [role=button], [role=link], [contenteditable=true]")).filter((el) => {
+            const r = el.getBoundingClientRect();
+            return r.width > 0 && r.height > 0 && el.type !== "hidden";
+        });
+        for (const old of Array.from(document.querySelectorAll("[data-wz-ref]"))) {
+            old.removeAttribute("data-wz-ref");
+        }
+        const items = els.slice(0, 120).map((el, i) => {
+            el.setAttribute("data-wz-ref", String(i));
+            const input = el;
+            const button = ["submit", "button", "reset"].includes(input.type);
+            const field = (el.tagName === "INPUT" && !button) || el.tagName === "TEXTAREA";
+            // What stands in a field may be something the person typed: the model learns that a
+            // field is filled, never with what.
+            const label = el.getAttribute("aria-label") ||
+                input.placeholder ||
+                (field ? "" : el.innerText || (button ? input.value : "")) ||
+                el.getAttribute("name") ||
+                "";
+            const tag = el.tagName.toLowerCase();
+            const kind = tag === "input" ? `input(${input.type || "text"})` : tag;
+            const filled = field && input.value ? " (filled)" : "";
+            return `[${i}] ${kind} ${label.trim().replace(/\s+/g, " ").slice(0, 80)}${filled}`;
+        });
+        return { text: document.body?.innerText ?? "", items };
+    });
+    return {
+        url: page.url(),
+        title: await page.title(),
+        text: clip(data.text, 6000),
+        elements: data.items.join("\n"),
+    };
+}
+function originOf(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A wait that timed out is a rejection, so waits can be raced. */
+function found(wait) {
+    const p = wait.then((v) => v ?? Promise.reject(new Error("none")));
+    p.catch(() => undefined);
+    return p;
+}
+const settle = (page) => page.waitForLoadState("domcontentloaded", { timeout: 10_000 }).catch(() => undefined);
+/**
+ * Fetches a URL with the browser's sign-in, outside any page. Page requests pass the context's
+ * host guard; this one does not, so every redirect hop is checked here.
+ */
+async function signedInGet(page, url) {
+    let next = url;
+    for (let hop = 0; hop < 6; hop++) {
+        const safe = await assertPublicUrl(next);
+        const res = await page
+            .context()
+            .request.get(safe.toString(), { timeout: 60_000, maxRedirects: 0 });
+        const location = res.headers().location;
+        if (res.status() < 300 || res.status() >= 400 || !location) {
+            return res;
+        }
+        next = new URL(location, safe).toString();
+    }
+    throw new Error("Too many redirects.");
+}
+const credentialField = z.object({
+    ref: z.number().describe("The field's [number] from your latest page snapshot."),
+    label: z.string().min(1).max(60).describe("What the person sees, e.g. E-Mail."),
+    kind: z
+        .enum(["username", "password", "otp", "text"])
+        .describe("password only fills a password input."),
+});
+/**
+ * Types the person's values into the page. A password goes only into a password input, and
+ * only while the page is still the site the person was shown. Failures are codes: a browser
+ * error message could quote the value it failed to type.
+ */
+async function fillCredentials(page, origin, fields, values) {
+    if (originOf(page.url()) !== origin) {
+        return { error: "origin_changed" };
+    }
+    const filled = [];
+    for (const [index, field] of fields.entries()) {
+        const value = values[`field_${index + 1}`];
+        if (typeof value !== "string" || !value) {
+            continue;
+        }
+        const locator = page.locator(ref(field.ref)).first();
+        const element = await locator
+            .evaluate((el) => ({ tag: el.tagName, type: el.type ?? "" }), undefined, {
+            timeout: 5000,
+        })
+            .catch(() => null);
+        if (!element) {
+            return { error: "field_missing" };
+        }
+        if (element.tag !== "INPUT" && element.tag !== "TEXTAREA") {
+            return { error: "not_an_input" };
+        }
+        if (field.kind === "password" && element.type !== "password") {
+            return { error: "not_a_password_field" };
+        }
+        try {
+            await locator.fill(value, { timeout: 10_000 });
+        }
+        catch {
+            return { error: "fill_failed" };
+        }
+        filled.push(field.label);
+    }
+    return { filled };
+}
+const NOBODY = "Nobody is at the keyboard for this run, so a sign-in cannot be asked for. Go on without it and report what the person has to do.";
+const DECLINED = "The person did not sign in. Do not ask again for this site; go on without it and say in your result what is missing and what the person can do.";
+export function browserTools(ctx, assets, files) {
+    const page = () => ctx.resources.browserPage();
+    const tools = {};
+    // There is one page. A model may ask for several browser actions at once; they run one after
+    // the other, in the order asked — else a navigation would cut a download short.
+    let queue = Promise.resolve();
+    const inTurn = (run) => {
+        const next = queue.then(() => attempt(run));
+        queue = next;
+        return next;
+    };
+    tools.browser_open = createTool({
+        id: "browser_open",
+        description: "Open a URL in the browser and return its text plus numbered interactive elements. Sites the person signed in to on an earlier run may still be signed in.",
+        inputSchema: z.object({ url: z.string() }),
+        execute: ({ url }) => inTurn(async () => {
+            const safe = await assertPublicUrl(url);
+            await ctx.emit("tool", `Öffnet ${safe.hostname}`);
+            const p = await page();
+            await p.goto(safe.toString(), { waitUntil: "domcontentloaded", timeout: 30_000 });
+            await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => undefined);
+            return pageSnapshot(p);
+        }),
+    });
+    tools.browser_click = createTool({
+        id: "browser_click",
+        description: "Click an element by its [number] from the last snapshot.",
+        inputSchema: z.object({ ref: z.number() }),
+        execute: ({ ref: n }) => inTurn(async () => {
+            const p = await page();
+            await ctx.emit("tool", "Klickt im Browser");
+            const popup = p
+                .context()
+                .waitForEvent("page", { timeout: 3000 })
+                .catch(() => null);
+            await p.locator(ref(n)).first().click({ timeout: 10_000 });
+            const opened = await popup;
+            if (opened) {
+                ctx.resources.adopt(opened);
+                await settle(opened);
+                return pageSnapshot(opened);
+            }
+            await settle(p);
+            return pageSnapshot(p);
+        }),
+    });
+    tools.browser_type = createTool({
+        id: "browser_type",
+        description: "Type text into an input by its [number]; set submit to press Enter afterwards. Never for passwords or codes — those the person enters through browser_request_credentials.",
+        inputSchema: z.object({ ref: z.number(), text: z.string(), submit: z.boolean().optional() }),
+        execute: ({ ref: n, text, submit }) => inTurn(async () => {
+            const p = await page();
+            await ctx.emit("tool", "Tippt im Browser");
+            const el = p.locator(ref(n)).first();
+            await el.fill(text, { timeout: 10_000 });
+            if (submit) {
+                await el.press("Enter");
+                await settle(p);
+            }
+            return pageSnapshot(p);
+        }),
+    });
+    tools.browser_screenshot = createTool({
+        id: "browser_screenshot",
+        description: "Look at the current page: returns a picture of it to you. Use it when the text snapshot is not enough (charts, a layout you cannot make sense of, a captcha or cookie wall). Set save to also hand the picture to the person as part of the result.",
+        inputSchema: z.object({ save: z.boolean().optional(), name: z.string().optional() }),
+        execute: ({ save, name }) => inTurn(async () => {
+            const p = await page();
+            await ctx.emit("tool", "Sieht sich die Seite an");
+            const png = await p.screenshot({ type: "png" });
+            let saved;
+            if (save) {
+                const asset = await ctx.saveAsset({
+                    kind: "image",
+                    mime: "image/png",
+                    name: name ?? "screenshot.png",
+                    data: png,
+                });
+                assets.push(asset);
+                saved = asset.id;
+            }
+            return { url: p.url(), saved, screenshot: Buffer.from(png).toString("base64") };
+        }),
+        toModelOutput: (out) => {
+            if (!out?.screenshot) {
+                return { type: "json", value: out };
+            }
+            const { screenshot, ...rest } = out;
+            return {
+                type: "content",
+                value: [
+                    { type: "text", text: JSON.stringify(rest) },
+                    { type: "image-data", data: screenshot, mediaType: "image/png" },
+                ],
+            };
+        },
+    });
+    const handOver = async (input) => {
+        const p = await page();
+        const origin = originOf(p.url());
+        if (!origin) {
+            return { error: "no_site", note: "Open the site's sign-in page first." };
+        }
+        for (const field of input.fields) {
+            if (!(await p.locator(ref(field.ref)).count())) {
+                return {
+                    error: "fields_not_found",
+                    note: `[${field.ref}] is not on the page any more. Open or re-read the page and ask again with its numbers.`,
+                };
+            }
+        }
+        await ctx.emit("tool", `Wartet auf deine Anmeldung bei ${new URL(origin).hostname}`);
+        const answer = await ctx.ask({
+            kind: "login",
+            reason: input.reason,
+            site: { host: new URL(origin).hostname, title: await p.title() },
+            fields: input.fields.map((f, i) => ({
+                id: `field_${i + 1}`,
+                label: f.label,
+                secret: f.kind === "password",
+            })),
+        });
+        if (!answer) {
+            return { status: "needs_person", note: NOBODY };
+        }
+        if (answer.type === "skip" || answer.type === "timeout") {
+            return { status: "declined", note: DECLINED };
+        }
+        // The person may have gone on in a tab the site opened.
+        const current = ctx.resources.openPage() ?? p;
+        let note = "The person signed in on the page themselves.";
+        if (answer.type === "fill") {
+            const result = await fillCredentials(current, origin, input.fields, answer.values);
+            if ("error" in result) {
+                return {
+                    error: result.error,
+                    note: "Nothing you can read was entered. Re-read the page and ask again with its current numbers.",
+                };
+            }
+            if (result.filled.length && input.submitRef !== undefined) {
+                await current
+                    .locator(ref(input.submitRef))
+                    .first()
+                    .click({ timeout: 10_000 })
+                    .catch(() => undefined);
+            }
+            await settle(current);
+            await current.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => undefined);
+            note = `The person entered ${result.filled.join(", ")} straight into the page${input.submitRef !== undefined ? " and it was submitted" : ""}. You do not see what they typed and must not try to read it back.`;
+        }
+        if (answer.remember) {
+            await ctx.resources.keepSession().catch(() => undefined);
+        }
+        return { status: "done", note, page: await pageSnapshot(current) };
+    };
+    tools.browser_request_credentials = createTool({
+        id: "browser_request_credentials",
+        description: "THE way to get a login into a page: ask the person to enter a username, e-mail, password or one-time code into fields on your current page, WITHOUT you seeing it. The person gets a picture of the page, the site's address and a form; what they type goes straight into the page, never to you. Give each field's [number] from your latest snapshot, and submit_ref to press the sign-in or next button afterwards. A login spread over several pages (e-mail, then password, then code) is one call per page. WAITS for the person. Never ask for a password any other way.",
+        inputSchema: z.object({
+            reason: z
+                .string()
+                .min(1)
+                .max(300)
+                .describe("One sentence for the person, in their language: which site and why."),
+            fields: z.array(credentialField).min(1).max(4),
+            submit_ref: z
+                .number()
+                .optional()
+                .describe("[number] of the button to press once the fields are filled."),
+        }),
+        execute: ({ reason, fields, submit_ref }) => inTurn(() => handOver({ reason, fields, submitRef: submit_ref })),
+    });
+    tools.browser_request_user = createTool({
+        id: "browser_request_user",
+        description: "Hand the page to the person for something no form can do: a captcha, 'continue with Google', a passkey, a cookie wall you cannot get past. They click and type in a picture of the page and say when they are done. For a plain login form use browser_request_credentials instead. WAITS for the person.",
+        inputSchema: z.object({
+            reason: z
+                .string()
+                .min(1)
+                .max(300)
+                .describe("One sentence for the person, in their language: what to do on the page."),
+        }),
+        execute: ({ reason }) => inTurn(() => handOver({ reason, fields: [] })),
+    });
+    tools.browser_download = createTool({
+        id: "browser_download",
+        description: "Download a file (an invoice PDF, an export) with the browser's sign-in and keep it: click the element with this [number], or fetch this URL. The file is stored under `path` in the wizard's files and added to this step's result.",
+        inputSchema: z.object({
+            ref: z.number().optional().describe("[number] of the download link or button."),
+            url: z.string().optional().describe("Direct URL of the file, instead of ref."),
+            path: z
+                .string()
+                .describe("Where to keep it, e.g. invoices/2026-09/2026-09-03_Notion_INV-123.pdf"),
+            source: z.string().optional().describe("Where it came from, in words, for the person."),
+        }),
+        execute: ({ ref: n, url, path, source }) => inTurn(async () => {
+            const p = await page();
+            await ctx.emit("tool", `Lädt ${path.split("/").pop()} herunter`);
+            let data;
+            let mime;
+            if (url) {
+                const res = await signedInGet(p, new URL(url, p.url()).toString());
+                if (!res.ok()) {
+                    return { error: `The server answered ${res.status()}.` };
+                }
+                data = await res.body();
+                mime = res.headers()["content-type"]?.split(";")[0];
+            }
+            else if (n !== undefined) {
+                // A click may start a download, open the file in a new tab, or both.
+                const download = found(p.waitForEvent("download", { timeout: 12_000 }));
+                const popup = found(p.context().waitForEvent("page", { timeout: 5000 }));
+                await p.locator(ref(n)).first().click({ timeout: 10_000 });
+                const opened = await Promise.race([popup, download.then(() => null)]).catch(() => null);
+                const got = await Promise.any([
+                    download,
+                    ...(opened ? [found(opened.waitForEvent("download", { timeout: 8000 }))] : []),
+                ]).catch(() => null);
+                if (got) {
+                    data = await readFile(await got.path());
+                    await opened?.close().catch(() => undefined);
+                }
+                else {
+                    // No download event: the click opened the file in a tab (a PDF viewer).
+                    const target = opened ?? p;
+                    await settle(target);
+                    const res = await signedInGet(p, target.url());
+                    mime = res.headers()["content-type"]?.split(";")[0];
+                    if (!res.ok() || mime === "text/html") {
+                        await opened?.close().catch(() => undefined);
+                        return {
+                            error: "The click did not give a file.",
+                            page: await pageSnapshot(p),
+                        };
+                    }
+                    data = await res.body();
+                    await opened?.close().catch(() => undefined);
+                }
+            }
+            else {
+                return { error: "Give ref or url." };
+            }
+            if (mime === "text/html") {
+                return { error: "That is a web page, not a file — you may not be signed in." };
+            }
+            const kept = await files.keep(path, data, {
+                mime,
+                source: source ?? `Download von ${new URL(p.url()).hostname}`,
+            });
+            return { saved: kept.path, mime: kept.mime, size: kept.size };
+        }),
+    });
+    return tools;
+}