@engenty/wizards-runtime 0.7.11 → 0.8.0

package/apps/runtime/dist/sharing/state.js

@@ -0,0 +1,116 @@
+import { and, desc, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { db, schema } from "../db/client.js";
+import { pendingAsk } from "../engine/asks.js";
+import { signalChanged } from "../engine/events.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { serverText } from "../texts.js";
+/** Jobs this process is working on, by run. One at a time per run: they share its browser. */
+const working = new Map();
+export function workingJob(runId) {
+    return working.get(runId) ?? null;
+}
+export function setWorking(runId, job) {
+    if (job) {
+        working.set(runId, job);
+    }
+    else {
+        working.delete(runId);
+    }
+}
+async function view(row) {
+    return {
+        id: row.id,
+        target: row.target,
+        name: row.name,
+        icon: row.icon,
+        status: row.status,
+        events: row.events,
+        ask: row.status === "running" ? await pendingAsk(row.runId) : null,
+        result: row.result ?? null,
+        error: row.error,
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+/** A job left "running" by a server that stopped: nobody works on it any more. */
+async function settled(row) {
+    if (row.status !== "running" || working.get(row.runId)?.jobId === row.id) {
+        return row;
+    }
+    const error = serverText(row.request.lang ?? "en", "shareInterrupted");
+    await db
+        .update(schema.shareJob)
+        .set({ status: "failed", error, updatedAt: new Date() })
+        .where(eq(schema.shareJob.id, row.id));
+    return { ...row, status: "failed", error };
+}
+export async function createJob(input) {
+    const [row] = await db
+        .insert(schema.shareJob)
+        // The column's default counts whole seconds; jobs of one second must still keep their order.
+        .values({
+        id: nanoid(14),
+        tenantId: currentTenant(),
+        status: "running",
+        createdAt: new Date(),
+        ...input,
+    })
+        .returning();
+    signalChanged(input.runId);
+    return view(row);
+}
+export async function addJobEvent(runId, jobId, message) {
+    const row = await db.query.shareJob.findFirst({ where: eq(schema.shareJob.id, jobId) });
+    if (!row) {
+        return;
+    }
+    const events = [
+        ...row.events,
+        { at: new Date().toISOString(), message: message.slice(0, 300) },
+    ].slice(-40);
+    await db
+        .update(schema.shareJob)
+        .set({ events, updatedAt: new Date() })
+        .where(eq(schema.shareJob.id, jobId));
+    signalChanged(runId);
+}
+export async function finishJob(runId, jobId, end) {
+    await db
+        .update(schema.shareJob)
+        .set({
+        status: end.status,
+        result: end.status === "done" ? end.result : null,
+        error: end.status === "failed" ? end.error : null,
+        updatedAt: new Date(),
+    })
+        .where(and(eq(schema.shareJob.id, jobId), eq(schema.shareJob.status, "running")));
+    signalChanged(runId);
+}
+export async function shareJobs(runId, limit = 12) {
+    const rows = await db.query.shareJob.findMany({
+        where: eq(schema.shareJob.runId, runId),
+        orderBy: [desc(schema.shareJob.createdAt), desc(schema.shareJob.id)],
+        limit,
+    });
+    return Promise.all(rows.map(async (row) => view(await settled(row))));
+}
+/** The run's newest job: the one on its way, or the last one that arrived or failed. */
+export async function latestShareJob(runId) {
+    return (await shareJobs(runId, 1))[0] ?? null;
+}
+/** How many jobs a run has started, whatever became of them. */
+export async function jobCount(runId) {
+    const rows = await db.query.shareJob.findMany({
+        where: eq(schema.shareJob.runId, runId),
+        columns: { id: true },
+    });
+    return rows.length;
+}
+/** How often a target has sent for a run. */
+export async function sentCount(runId, target) {
+    const rows = await db.query.shareJob.findMany({
+        where: and(eq(schema.shareJob.runId, runId), eq(schema.shareJob.target, target), eq(schema.shareJob.status, "done")),
+        columns: { id: true },
+    });
+    return rows.length;
+}

package/apps/runtime/dist/sharing/targets/browser.js

@@ -0,0 +1,131 @@
+import { existsSync } from "node:fs";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { env } from "../../env.js";
+import { browserTools } from "../../tools/browser.js";
+import { runShareAgent } from "../agent.js";
+import { line } from "../types.js";
+const RULES = [
+    "You work in a browser the person watches. Open the address first, then find the place the request names.",
+    "Sign-ins are the person's: on a login form call browser_request_credentials, for anything else in the way (a captcha, 'continue with Google', a cookie wall) browser_request_user. Never type a password or a code yourself. When the person skips a sign-in, stop and report it.",
+    "Attach files with browser_upload.",
+    "Right before the step that makes it public or sends it (Post, Publish, Send, Submit), call confirm_publish with where and exactly what goes out. Go on only when it answers allowed. If the person asked for a draft, save the draft and publish nothing.",
+    "Afterwards look for the address of what you published and report it.",
+].join("\n");
+/** Leave to publish: the person sees where and what, and says yes or no. */
+function confirmTool(step, site) {
+    return createTool({
+        id: "confirm_publish",
+        description: "Ask the person for leave right before the step that makes the result public or sends it. They see where and what. WAITS for the person.",
+        inputSchema: z.object({
+            where: z
+                .string()
+                .min(1)
+                .max(200)
+                .describe("One sentence in the person's language: the site and the place it goes to."),
+            what: z.string().min(1).describe("The exact text and the files that will go out."),
+        }),
+        execute: async ({ where, what }) => {
+            const answer = await step.ask({
+                kind: "confirm",
+                reason: where,
+                service: site,
+                action: { id: "publish", summary: where, destructive: false },
+                input: what.slice(0, 4000),
+                once: true,
+            });
+            if (!answer) {
+                return {
+                    allowed: false,
+                    note: "Nobody is there to allow it. Publish nothing and report it.",
+                };
+            }
+            return answer.type === "done"
+                ? { allowed: true }
+                : {
+                    allowed: false,
+                    note: "The person did not allow it. Publish nothing; report that it was not published.",
+                };
+        },
+    });
+}
+const POST = line("sharePostInstructions");
+/**
+ * Free style: the wizard opens a website in its browser, the person signs in themselves, and an
+ * agent posts the result there the way the person describes it. For every place that has no
+ * connector.
+ */
+export const browserTarget = {
+    id: "browser",
+    name: "Website",
+    description: line("shareWebsiteDescription"),
+    icon: "globe",
+    takes: "files",
+    agent: true,
+    available: () => Boolean(env.browserCdpUrl) || existsSync(env.chromePath),
+    fields: [
+        {
+            id: "url",
+            kind: "url",
+            required: true,
+            label: line("shareWebsiteAddress"),
+            placeholder: "https://…",
+        },
+        {
+            id: "instructions",
+            kind: "textarea",
+            required: true,
+            label: line("shareWhatThere"),
+            placeholder: line("shareWhatTherePlaceholder"),
+        },
+    ],
+    presets: [
+        {
+            label: "LinkedIn",
+            values: {
+                url: "https://www.linkedin.com/feed/",
+                instructions: POST,
+            },
+        },
+        {
+            label: "X",
+            values: {
+                url: "https://x.com/compose/post",
+                instructions: POST,
+            },
+        },
+        {
+            label: "Facebook",
+            values: {
+                url: "https://www.facebook.com/",
+                instructions: POST,
+            },
+        },
+        {
+            label: "Instagram",
+            values: {
+                url: "https://www.instagram.com/",
+                instructions: POST,
+            },
+        },
+        {
+            label: "Meta Ads",
+            values: {
+                url: "https://adsmanager.facebook.com/",
+                instructions: line("shareAdInstructions"),
+            },
+        },
+    ],
+    send(input, ctx) {
+        const url = input.values.url.trim();
+        return runShareAgent(ctx, input, {
+            task: `On ${url}: ${input.values.instructions}`,
+            rules: RULES,
+            maxSteps: 60,
+            tools: (step, files) => ({
+                ...browserTools(step, [], files),
+                confirm_publish: confirmTool(step, new URL(url).hostname),
+            }),
+        });
+    },
+};

package/apps/runtime/dist/sharing/targets/connector.js

@@ -0,0 +1,63 @@
+import { refreshConnector, resolveConnector } from "../../connectors/external.js";
+import { toolsOf } from "../../tools/connector.js";
+import { runShareAgent } from "../agent.js";
+import { line, ShareError } from "../types.js";
+const RULES = [
+    "You work in the person's account through the service's actions. Look first (search, list) where the result belongs, then write.",
+    "Actions that change the account ask the person before they run. When they say no, stop and report it — do not try another way.",
+    "To send a file, give `file:<name>` with the file's name as listed, where an action's input asks for `*_base64`.",
+].join("\n");
+/**
+ * The result through any connector that can write: one the product ships, or one the project
+ * imported from the integrations registry (Notion, WordPress, an ads account …). The person
+ * says in their words what should happen; an agent does it with the connector's actions.
+ */
+export function connectorTarget(connector, imported) {
+    const id = `connector:${connector.id}`;
+    const connection = (actions) => ({
+        id: `share:${id}`,
+        connector: connector.id,
+        actions,
+        title: connector.name,
+    });
+    return {
+        id,
+        name: connector.name,
+        description: line("shareConnectorDescription"),
+        icon: "plug",
+        takes: "files",
+        agent: true,
+        // What the project imported it wants to use; what ships with the product is named by the wizard.
+        byDefault: imported,
+        connection: () => connection(connector.actions.map((a) => a.id)),
+        fields: [
+            {
+                id: "instructions",
+                kind: "textarea",
+                required: true,
+                label: line("shareWhatHappens"),
+                placeholder: line("shareWhatHappensPlaceholder"),
+            },
+        ],
+        async send(input, ctx) {
+            const account = await ctx.account();
+            if (!account) {
+                throw new ShareError(line("shareConnectFirst", { name: connector.name }));
+            }
+            // An MCP server that lists its tools only to a signed-in account: ask it now.
+            if (imported && !connector.actions.length) {
+                await refreshConnector(ctx.projectId, connector.id, account.ctx.accessToken).catch(() => undefined);
+            }
+            const current = (await resolveConnector(ctx.projectId, connector.id))?.connector ?? connector;
+            return runShareAgent(ctx, input, {
+                task: `In ${connector.name}: ${input.values.instructions}`,
+                rules: RULES,
+                tools: (step, files) => toolsOf(connection(current.actions.map((a) => a.id)), step, files),
+            });
+        },
+    };
+}
+/** A connector can carry a result somewhere when it has an action that writes. */
+export function canPublish(connector) {
+    return !connector.actions.length || connector.actions.some((a) => a.group !== "read");
+}

package/apps/runtime/dist/sharing/targets/email.js

@@ -0,0 +1,98 @@
+import { MAIL_SENDERS, MailTooLarge, sendAsAccount, sendFromServer, serverSender, } from "../../connectors/smtp.js";
+import { megabytes } from "../files.js";
+import { line, ShareError } from "../types.js";
+/** What mail providers take in one message, with room for the encoding. */
+const ATTACH_LIMIT = 18_000_000;
+/** From the server's own address, people without an account send this much per run. */
+const VISITOR_MAILS = 3;
+const VISITOR_RECIPIENTS = 3;
+const RECIPIENTS = 20;
+const ADDRESS = /^[^\s@<>,;]+@[^\s@<>,;]+\.[^\s@<>,;]+$/;
+/** "a@b.at, c@d.at; e@f.at" → the addresses; throws on one that is none. */
+export function parseRecipients(raw) {
+    const list = raw
+        .split(/[\s,;]+/)
+        .map((a) => a.trim())
+        .filter(Boolean);
+    const bad = list.find((a) => !ADDRESS.test(a));
+    if (bad) {
+        throw new ShareError(line("shareNotAnAddress", { address: bad }));
+    }
+    return [...new Set(list)];
+}
+/**
+ * The result by e-mail: the picked files as attachments. Sent from the mailbox the person
+ * connects (Gmail, Outlook, or any mailbox over SMTP) — or, where the server has an address of
+ * its own, without any account.
+ */
+export const emailTarget = {
+    id: "email",
+    name: line("shareEmailName"),
+    description: line("shareEmailDescription"),
+    icon: "mail",
+    takes: "files",
+    connection: () => serverSender()
+        ? null
+        : {
+            id: "share:email",
+            target: { connectors: [...MAIL_SENDERS] },
+            actions: ["send_message"],
+            title: "E-Mail",
+        },
+    fields: [
+        {
+            id: "to",
+            kind: "emails",
+            required: true,
+            label: line("shareTo"),
+            placeholder: line("shareToPlaceholder"),
+        },
+        { id: "subject", kind: "text", required: true, label: line("shareSubject") },
+        { id: "message", kind: "textarea", label: line("shareMessage") },
+    ],
+    defaults: (scope) => ({ subject: scope.title, message: scope.message ?? "" }),
+    async send({ values, files }, ctx) {
+        const to = parseRecipients(values.to ?? "");
+        if (!to.length) {
+            throw new ShareError(line("shareNoAddress"));
+        }
+        if (to.length > RECIPIENTS) {
+            throw new ShareError(line("shareTooManyAddresses", { max: RECIPIENTS }));
+        }
+        const size = files.reduce((n, f) => n + f.data.byteLength, 0);
+        if (size > ATTACH_LIMIT) {
+            throw new ShareError(line("shareAttachmentsTooLarge", { size: megabytes(size) }));
+        }
+        const message = {
+            to,
+            subject: (values.subject ?? "").trim() || ctx.title,
+            text: (values.message ?? "").trim(),
+            attachments: files.map((f) => ({ name: f.name, mime: f.mime, data: f.data })),
+        };
+        const account = await ctx.account();
+        if (account) {
+            await ctx.emit(line("shareSendingFrom", { account: account.label }));
+            try {
+                await sendAsAccount(account.connector, account.ctx, message);
+            }
+            catch (err) {
+                if (err instanceof MailTooLarge) {
+                    throw new ShareError(line("shareMailboxLimit"));
+                }
+                throw err;
+            }
+        }
+        else if (serverSender()) {
+            // The server's address is everyone's to send from: a visitor gets a few mails per run.
+            if (!ctx.member && (ctx.sentBefore >= VISITOR_MAILS || to.length > VISITOR_RECIPIENTS)) {
+                throw new ShareError(line("shareVisitorMails", { mails: VISITOR_MAILS, recipients: VISITOR_RECIPIENTS }));
+            }
+            await ctx.emit(line("shareSendingFrom", { account: serverSender() ?? "" }));
+            await sendFromServer(message);
+        }
+        else {
+            throw new ShareError(line("shareConnectMailbox"));
+        }
+        return { summary: line("shareSentTo", { to: to.join(", ") }) };
+    },
+};

package/apps/runtime/dist/sharing/targets/slack.js

@@ -0,0 +1,54 @@
+import { line, ShareError } from "../types.js";
+/**
+ * A message in a Slack channel, as the person: their text and the link to the result page.
+ * The connector posts text only, so files travel as the link.
+ */
+export const slackTarget = {
+    id: "slack",
+    name: "Slack",
+    description: line("shareSlackDescription"),
+    icon: "chat",
+    takes: "link",
+    connection: () => ({
+        id: "share:slack",
+        target: { connectors: ["slack"] },
+        actions: ["list_channels", "post_message"],
+        title: "Slack",
+    }),
+    fields: [
+        {
+            id: "channel",
+            kind: "select",
+            required: true,
+            fromAccount: true,
+            label: line("shareChannel"),
+        },
+        { id: "message", kind: "textarea", required: true, label: line("shareMessage") },
+    ],
+    defaults: (scope) => ({
+        message: [scope.title, scope.text?.slice(0, 2500)].filter(Boolean).join("\n\n"),
+    }),
+    async choices(field, ctx) {
+        const account = field === "channel" ? await ctx.account() : null;
+        const list = account?.connector.actions.find((a) => a.id === "list_channels");
+        if (!account || !list) {
+            return [];
+        }
+        const { channels } = (await list.handler({ limit: 50 }, account.ctx));
+        return channels
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((c) => ({ value: c.id, label: `${c.is_private ? "🔒 " : "#"}${c.name}` }));
+    },
+    async send({ values }, ctx) {
+        const account = await ctx.account();
+        const post = account?.connector.actions.find((a) => a.id === "post_message");
+        if (!account || !post) {
+            throw new ShareError(line("shareConnectFirst", { name: "Slack" }));
+        }
+        const link = await ctx.link();
+        const text = [values.message?.trim(), link].filter(Boolean).join("\n\n");
+        await ctx.emit(line("sharePostingAs", { account: account.label }));
+        await post.handler({ channel: values.channel, text }, account.ctx);
+        return { summary: line("sharePostedSlack") };
+    },
+};

package/apps/runtime/dist/sharing/targets/storage.js

@@ -0,0 +1,164 @@
+import { BUILTIN_CONNECTORS } from "../../connectors/builtin.js";
+import { line, ShareError } from "../types.js";
+async function call(ctx, url, init = {}) {
+    const res = await ctx.fetchImpl(url, {
+        ...init,
+        headers: { Authorization: `Bearer ${ctx.accessToken}`, ...init.headers },
+    });
+    if (!res.ok) {
+        throw new Error(`${new URL(url).hostname} (${res.status}): ${(await res.text()).slice(0, 200)}`);
+    }
+    return res;
+}
+const segments = (folder) => folder
+    .split("/")
+    .map((s) => s.trim())
+    .filter(Boolean);
+// --- Google Drive -----------------------------------------------------------------
+// With the scope `drive.file` the wizard sees only what it created itself: its folders are
+// found again by name, and nothing else in the Drive is readable.
+const DRIVE = "https://www.googleapis.com/drive/v3/files";
+const DRIVE_FOLDER = "application/vnd.google-apps.folder";
+async function driveFolder(ctx, name, parent) {
+    const q = [
+        `name = '${name.replace(/['\\]/g, "\\$&")}'`,
+        `mimeType = '${DRIVE_FOLDER}'`,
+        "trashed = false",
+        `'${parent ?? "root"}' in parents`,
+    ].join(" and ");
+    const found = (await (await call(ctx, `${DRIVE}?q=${encodeURIComponent(q)}&fields=files(id)&pageSize=1`)).json());
+    if (found.files?.[0]) {
+        return found.files[0].id;
+    }
+    const created = (await (await call(ctx, `${DRIVE}?fields=id`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            name,
+            mimeType: DRIVE_FOLDER,
+            ...(parent ? { parents: [parent] } : {}),
+        }),
+    })).json());
+    return created.id;
+}
+const driveUpload = async (ctx, folder, files, each) => {
+    let parent = null;
+    for (const name of segments(folder)) {
+        parent = await driveFolder(ctx, name, parent);
+    }
+    let link = parent ? `https://drive.google.com/drive/folders/${parent}` : null;
+    for (const file of files) {
+        await each(file);
+        const boundary = `wz${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+        const meta = JSON.stringify({ name: file.name, ...(parent ? { parents: [parent] } : {}) });
+        const body = Buffer.concat([
+            Buffer.from(`--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${meta}\r\n--${boundary}\r\nContent-Type: ${file.mime}\r\n\r\n`),
+            Buffer.from(file.data),
+            Buffer.from(`\r\n--${boundary}--`),
+        ]);
+        const made = (await (await call(ctx, "https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart&fields=id,webViewLink", {
+            method: "POST",
+            headers: { "Content-Type": `multipart/related; boundary=${boundary}` },
+            body: new Uint8Array(body),
+        })).json());
+        link ??= made.webViewLink ?? null;
+    }
+    return link;
+};
+// --- OneDrive -----------------------------------------------------------------------
+const GRAPH = "https://graph.microsoft.com/v1.0/me/drive";
+const oneDriveUpload = async (ctx, folder, files, each) => {
+    const path = segments(folder).map(encodeURIComponent).join("/");
+    let link = null;
+    for (const file of files) {
+        await each(file);
+        const at = [path, encodeURIComponent(file.name)].filter(Boolean).join("/");
+        const item = (await (await call(ctx, `${GRAPH}/root:/${at}:/content`, {
+            method: "PUT",
+            headers: { "Content-Type": file.mime },
+            body: new Uint8Array(file.data),
+        })).json());
+        link ??= item.webUrl ?? null;
+    }
+    if (path) {
+        const dir = await call(ctx, `${GRAPH}/root:/${path}`).then((res) => res.json(), () => null);
+        link = dir?.webUrl ?? link;
+    }
+    return link;
+};
+const UPLOADS = {
+    "google-drive": driveUpload,
+    "microsoft-onedrive": oneDriveUpload,
+};
+/** The action whose provider rights an upload needs, per connector. */
+const UPLOAD_ACTION = {
+    "google-drive": "create_file",
+    "microsoft-onedrive": "upload_file",
+};
+/** A connector that says itself how files are written into it (S3). */
+function capabilityUpload(connector) {
+    const storage = connector.storage;
+    if (!storage) {
+        return null;
+    }
+    return async (ctx, folder, files, each) => {
+        let link = null;
+        for (const file of files) {
+            await each(file);
+            const entry = await storage.write(ctx, {
+                folder_ref: segments(folder).join("/") || null,
+                name: file.name,
+                mime_type: file.mime,
+                content_base64: Buffer.from(file.data).toString("base64"),
+            });
+            link ??= entry.web_url ?? null;
+        }
+        return link;
+    };
+}
+/** The connectors files can be saved into: `storage:<id>` is a share target for each. */
+export function storageConnectors() {
+    return BUILTIN_CONNECTORS.filter((c) => UPLOADS[c.id] || c.storage);
+}
+/** The picked files, saved into a folder of the person's cloud storage. */
+export function storageTarget(connector) {
+    const upload = UPLOADS[connector.id] ?? capabilityUpload(connector);
+    if (!upload) {
+        return null;
+    }
+    const id = `storage:${connector.id}`;
+    return {
+        id,
+        name: connector.name,
+        description: line("shareStorageDescription"),
+        icon: "folder",
+        takes: "files",
+        needsFiles: true,
+        connection: () => ({
+            id: `share:${id}`,
+            target: { connectors: [connector.id] },
+            actions: UPLOAD_ACTION[connector.id] ? [UPLOAD_ACTION[connector.id]] : ["files_write"],
+            title: connector.name,
+        }),
+        fields: [
+            {
+                id: "folder",
+                kind: "text",
+                label: line("shareFolder"),
+                placeholder: line("shareFolderPlaceholder"),
+                help: line("shareFolderHelp"),
+            },
+        ],
+        defaults: (scope) => ({ folder: scope.run.definition.title.replace(/\//g, "-") }),
+        async send({ values, files }, ctx) {
+            const account = await ctx.account();
+            if (!account) {
+                throw new ShareError(line("shareConnectFirst", { name: connector.name }));
+            }
+            const folder = (values.folder ?? "").trim();
+            const link = await upload(account.ctx, folder, files, (file) => ctx.emit(line("shareUploading", { name: file.name })));
+            const where = [connector.name, folder].filter(Boolean).join(" › ");
+            return { summary: line("shareSavedFiles", { count: files.length, where }), url: link };
+        },
+    };
+}

package/apps/runtime/dist/sharing/types.js

@@ -0,0 +1,13 @@
+import { NotedError } from "../model-errors.js";
+import { serverText } from "../texts.js";
+export const line = (server, params) => ({
+    server,
+    params,
+});
+/** What is said, in a language. */
+export function sayIn(lang, said) {
+    return typeof said === "string" ? said : serverText(lang, said.server, said.params);
+}
+/** A failure the person can read and act on; anything else is reported as "did not work". */
+export class ShareError extends NotedError {
+}