@engenty/wizards-runtime 0.7.10 → 0.8.0

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

@@ -0,0 +1,121 @@
+import { FORMATS, LIST_FORMATS, listRef, } from "@engenty-wizards/shared/definition";
+import { listDownload, renderDownload } from "../render/downloads.js";
+import { listRows, scopeOf } from "../store/index.js";
+import { line, ShareError } from "./types.js";
+/** The result step a finished run stands on. */
+export function resultStepOf(run) {
+    const steps = run.definition.steps;
+    const step = steps.find((s) => s.id === run.cursor && s.type === "result") ??
+        steps.findLast((s) => s.type === "result");
+    return step?.type === "result" ? step : null;
+}
+/** One output of a run as a file: a step's output or a stored list, in one format. */
+export async function resultFile(source, from, format) {
+    const { def, state, store } = source;
+    const deliverable = def.steps
+        .flatMap((s) => (s.type === "result" ? s.deliverables : []))
+        .find((d) => d.from === from);
+    const list = listRef(from);
+    if (list) {
+        const listDef = def.lists?.find((l) => l.id === list);
+        if (!listDef || !LIST_FORMATS.includes(format)) {
+            return null;
+        }
+        const label = deliverable?.label ?? listDef.title;
+        const download = await listDownload(listDef, await listRows(store, listDef), format, `${def.title} ${label}`);
+        return download ? { download, label } : null;
+    }
+    const step = def.steps.find((s) => s.id === from);
+    const output = step ? state.outputs[step.id] : undefined;
+    if (!step || !output) {
+        return null;
+    }
+    const label = deliverable?.label ?? step.title;
+    const download = await renderDownload(step, output, format, `${def.title} ${label}`);
+    return download ? { download, label } : null;
+}
+const RESULT_REF = /^result:(.+)\.([a-z0-9]+)$/;
+/** `result:<step>.<format>` — how an agent names an output of the run in a tool call. */
+export function parseResultRef(ref) {
+    const m = ref.match(RESULT_REF);
+    const format = m ? FORMATS.find((f) => f === m[2]) : undefined;
+    return m && format ? { from: m[1], format: format } : null;
+}
+function bytes(data) {
+    return typeof data === "string" ? new TextEncoder().encode(data) : data;
+}
+/**
+ * The files the person picked, rendered. Only what the result offers as a download can be sent:
+ * a deliverable, in one of its formats.
+ */
+export async function shareFiles(run, items) {
+    const result = resultStepOf(run);
+    const source = { def: run.definition, state: run.state, store: scopeOf(run) };
+    const files = [];
+    const names = new Set();
+    for (const item of items) {
+        const offered = result?.deliverables.find((d) => d.from === item.from && d.formats.includes(item.format));
+        if (!offered) {
+            throw new ShareError(line("shareNotInResult", { name: item.from, format: item.format }));
+        }
+        const found = await resultFile(source, item.from, item.format).catch(() => null);
+        if (!found) {
+            throw new ShareError(line("shareCannotRender", {
+                name: offered.label ?? item.from,
+                format: item.format.toUpperCase(),
+            }));
+        }
+        let name = found.download.filename;
+        for (let n = 2; names.has(name); n++) {
+            name = found.download.filename.replace(/(\.[^.]+)?$/, (ext) => `-${n}${ext}`);
+        }
+        names.add(name);
+        files.push({
+            name,
+            mime: found.download.mime,
+            data: bytes(found.download.data),
+            label: found.label,
+            ref: `result:${item.from}.${item.format}`,
+        });
+    }
+    return files;
+}
+/** The first written deliverable of the result, as text. */
+export function resultText(run) {
+    for (const d of resultStepOf(run)?.deliverables ?? []) {
+        const step = run.definition.steps.find((s) => s.id === d.from);
+        const text = run.state.outputs[d.from]?.text?.trim();
+        if (step?.type === "agent" && step.output.format !== "json" && text) {
+            return text;
+        }
+    }
+    return null;
+}
+/** What the result holds, for an agent that is to publish it: every deliverable, texts in full. */
+export function resultBrief(run) {
+    const lines = [];
+    for (const d of resultStepOf(run)?.deliverables ?? []) {
+        const step = run.definition.steps.find((s) => s.id === d.from);
+        const output = run.state.outputs[d.from];
+        if (!step || !output) {
+            continue;
+        }
+        const title = d.label ?? step.title;
+        if (step.type === "agent" && step.output.format === "json") {
+            lines.push(`## ${title} (data)\n${JSON.stringify(output.json, null, 2).slice(0, 6000)}`);
+        }
+        else if (step.type === "agent") {
+            lines.push(`## ${title} (text)\n${(output.text ?? "").slice(0, 12_000)}`);
+        }
+        else if (step.type === "generate") {
+            lines.push(`## ${title} (${step.asset})`);
+        }
+        else {
+            lines.push(`## ${title}`);
+        }
+    }
+    return lines.join("\n\n") || "(nothing)";
+}
+export function megabytes(n) {
+    return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 1 : 0)} MB`;
+}

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

@@ -0,0 +1,298 @@
+import { and, desc, eq } from "drizzle-orm";
+import { listConnectors, resolveConnector } from "../connectors/external.js";
+import { connectionViews, connectorOptions, registerConnectionSource, } from "../connectors/index.js";
+import { db, schema } from "../db/client.js";
+import { renderTemplate } from "../engine/template.js";
+import { scopeOf } from "../store/index.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { resultStepOf, resultText } from "./files.js";
+import { shareJobs } from "./state.js";
+import { browserTarget } from "./targets/browser.js";
+import { canPublish, connectorTarget } from "./targets/connector.js";
+import { emailTarget } from "./targets/email.js";
+import { slackTarget } from "./targets/slack.js";
+import { storageConnectors, storageTarget } from "./targets/storage.js";
+import { sayIn } from "./types.js";
+/**
+ * The share targets of this runtime. The fixed ones are listed here; every connector that
+ * stores files adds `storage:<connector>`, every connector that can write `connector:<connector>`.
+ * To add a target, write it in `./targets` and name it here.
+ */
+const FIXED = [emailTarget, slackTarget, browserTarget];
+/** A share target by its id; null when this project has none of that name. */
+export async function shareTarget(projectId, id) {
+    const fixed = FIXED.find((t) => t.id === id);
+    if (fixed) {
+        return fixed;
+    }
+    const cut = id.indexOf(":");
+    const [kind, connectorId] = [id.slice(0, cut), id.slice(cut + 1)];
+    if (kind === "storage") {
+        const connector = storageConnectors().find((c) => c.id === connectorId);
+        return connector ? storageTarget(connector) : null;
+    }
+    if (kind === "connector") {
+        const found = await resolveConnector(projectId, connectorId);
+        return found && canPublish(found.connector)
+            ? connectorTarget(found.connector, found.imported)
+            : null;
+    }
+    return null;
+}
+/** Every target of a project, in the order a result shows them. */
+async function projectTargets(projectId) {
+    const imported = (await listConnectors(projectId)).filter((c) => c.sourceKind !== "builtin");
+    const through = await Promise.all(imported.map((c) => shareTarget(projectId, `connector:${c.id}`)));
+    return [
+        emailTarget,
+        ...storageConnectors().flatMap((c) => storageTarget(c) ?? []),
+        slackTarget,
+        ...through.filter((t) => Boolean(t)),
+        browserTarget,
+    ];
+}
+/**
+ * Every target a wizard of the project can name on its result, for the editor and for whoever
+ * authors a wizard: the default ones, and one for each built-in connector that can write.
+ */
+export async function projectShareTargets(projectId, lang) {
+    const targets = await projectTargets(projectId);
+    const builtin = (await listConnectors(projectId)).filter((c) => c.sourceKind === "builtin");
+    for (const connector of builtin) {
+        const target = await shareTarget(projectId, `connector:${connector.id}`);
+        if (target) {
+            targets.push(target);
+        }
+    }
+    return Promise.all(targets.map(async (target) => ({
+        id: target.id,
+        name: sayIn(lang, target.name),
+        description: sayIn(lang, target.description),
+        icon: target.icon,
+        agent: Boolean(target.agent),
+        usable: await offerable(target, projectId),
+        byDefault: target.byDefault !== false,
+        fields: target.fields.map((f) => ({ id: f.id, label: sayIn(lang, f.label), kind: f.kind })),
+    })));
+}
+/** Whether a target can work here right now: what it drives is there, its account can be connected. */
+async function offerable(target, projectId) {
+    if (target.available && !(await target.available())) {
+        return false;
+    }
+    const connection = target.connection?.();
+    return !connection || (await connectorOptions(connection, projectId)).length > 0;
+}
+/**
+ * The targets a result names: its own list, else every target of the project a result offers
+ * by default. `missing` names listed targets this project does not have.
+ */
+async function namedTargets(run, projectId) {
+    const result = resultStepOf(run);
+    if (!result) {
+        return { entries: [], listed: true, missing: [] };
+    }
+    if (!result.share) {
+        const entries = (await projectTargets(projectId))
+            .filter((target) => target.byDefault !== false)
+            .map((target) => ({ key: target.id, target, values: {} }));
+        return { entries, listed: false, missing: [] };
+    }
+    const entries = [];
+    const missing = [];
+    for (const [i, option] of result.share.entries()) {
+        const target = await shareTarget(projectId, option.target);
+        if (target) {
+            entries.push({
+                key: `${i}:${option.target}`,
+                target,
+                label: option.label,
+                values: option.values ?? {},
+            });
+        }
+        else {
+            missing.push(option.label ?? option.target);
+        }
+    }
+    return { entries, listed: true, missing };
+}
+/**
+ * The targets a finished run offers. A wizard that lists them on its result decides; else every
+ * target that needs no model is offered, and the ones an agent drives only to the wizard's owner
+ * — they run on the wizard's credits.
+ */
+export async function offeredTargets(run, projectId, member) {
+    const { entries, listed } = await namedTargets(run, projectId);
+    const asked = entries.filter((e) => listed || !e.target.agent || member);
+    const usable = await Promise.all(asked.map((e) => offerable(e.target, projectId)));
+    return asked.filter((_, i) => usable[i]);
+}
+export function targetScope(run, projectId, lang) {
+    const result = resultStepOf(run);
+    return {
+        run,
+        projectId,
+        lang,
+        title: [result?.title, run.definition.title].filter(Boolean).join(" · "),
+        message: result?.message ?? null,
+        text: resultText(run),
+    };
+}
+async function templateScope(run, projectId) {
+    const project = await db.query.project.findFirst({ where: eq(schema.project.id, projectId) });
+    return {
+        def: run.definition,
+        state: run.state,
+        brand: project?.brand ?? {},
+    };
+}
+async function targetView(entry, scope, templates) {
+    const { target } = entry;
+    const { lang } = scope;
+    const connection = target.connection?.() ?? null;
+    const [account] = connection
+        ? await connectionViews([connection], scopeOf(scope.run), scope.projectId, lang)
+        : [null];
+    const defaults = (await target.defaults?.(scope)) ?? {};
+    return {
+        key: entry.key,
+        target: target.id,
+        name: entry.label ?? sayIn(lang, target.name),
+        description: sayIn(lang, target.description),
+        icon: target.icon,
+        connection: account,
+        fields: target.fields.map((f) => ({
+            ...f,
+            label: sayIn(lang, f.label),
+            placeholder: f.placeholder && sayIn(lang, f.placeholder),
+            help: f.help && sayIn(lang, f.help),
+            value: entry.values[f.id] !== undefined
+                ? renderTemplate(entry.values[f.id], templates)
+                : (defaults[f.id] ?? ""),
+        })),
+        takes: target.takes,
+        agent: Boolean(target.agent),
+        presets: (target.presets ?? []).map((p) => ({
+            label: p.label,
+            values: Object.fromEntries(Object.entries(p.values).map(([id, v]) => [id, sayIn(lang, v)])),
+        })),
+    };
+}
+/** What the share sheet shows: the targets of this result and what was sent before. */
+export async function shareOverview(run, projectId, member, lang) {
+    const scope = targetScope(run, projectId, lang);
+    const templates = await templateScope(run, projectId);
+    const offered = await offeredTargets(run, projectId, member);
+    const jobs = await shareJobs(run.id);
+    return {
+        targets: await Promise.all(offered.map((entry) => targetView(entry, scope, templates))),
+        jobs,
+    };
+}
+const PLACEHOLDER = /\{\{\s*([^}]+?)\s*\}\}/g;
+/** The placeholders of prefilled values that come out empty. */
+function emptyPlaceholders(values, templates) {
+    const empty = new Set();
+    for (const value of Object.values(values)) {
+        for (const [whole, ref] of value.matchAll(PLACEHOLDER)) {
+            if (!renderTemplate(whole, templates).trim()) {
+                empty.add(ref.trim());
+            }
+        }
+    }
+    return [...empty];
+}
+/** How much of a written deliverable the preview shows. */
+const EXCERPT = 1500;
+/** A run that never happened, for a wizard without a finished test run: the draft, no answers. */
+function standIn(wizard, userId) {
+    const now = new Date();
+    return {
+        id: `preview-${wizard.id}`,
+        wizardId: wizard.id,
+        tenantId: wizard.tenantId,
+        definition: wizard.draft,
+        files: [],
+        version: null,
+        mode: "test",
+        runner: null,
+        lang: null,
+        visitorId: null,
+        userId,
+        ipHash: null,
+        origin: null,
+        client: null,
+        status: "done",
+        cursor: null,
+        state: { values: {}, outputs: {}, history: [], notes: {} },
+        error: null,
+        ask: null,
+        answer: null,
+        unattended: false,
+        deviceOffer: null,
+        costMicros: 0,
+        shareToken: null,
+        sharedAt: null,
+        expiresAt: null,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * The draft's result page as a visitor (`member` false) or its owner gets it: its share targets,
+ * filled from the wizard's last finished test run, and what that run wrote. `resultId` picks the
+ * result step where the draft has several.
+ */
+export async function sharePreview(wizard, userId, resultId, member, lang) {
+    const last = await db.query.run.findFirst({
+        where: and(eq(schema.run.tenantId, currentTenant()), eq(schema.run.wizardId, wizard.id), eq(schema.run.mode, "test"), eq(schema.run.status, "done")),
+        orderBy: [desc(schema.run.createdAt)],
+    });
+    // The draft as it is now, on what the last test run answered and made.
+    const run = {
+        ...(last ?? standIn(wizard, userId)),
+        definition: wizard.draft,
+        cursor: resultId,
+    };
+    const scope = targetScope(run, wizard.projectId, lang);
+    const templates = await templateScope(run, wizard.projectId);
+    const { entries, listed, missing } = await namedTargets(run, wizard.projectId);
+    const targets = [];
+    const left = missing.map((name) => ({ name, why: "setup" }));
+    for (const entry of entries) {
+        const name = entry.label ?? sayIn(lang, entry.target.name);
+        if (!listed && entry.target.agent && !member) {
+            left.push({ name, why: "agent" });
+        }
+        else if (!(await offerable(entry.target, wizard.projectId))) {
+            left.push({ name, why: "setup" });
+        }
+        else {
+            targets.push({
+                ...(await targetView(entry, scope, templates)),
+                empty: emptyPlaceholders(entry.values, templates),
+            });
+        }
+    }
+    const outputs = {};
+    for (const d of resultStepOf(run)?.deliverables ?? []) {
+        const text = run.state.outputs[d.from]?.text?.trim();
+        if (text) {
+            outputs[d.from] = text.slice(0, EXCERPT);
+        }
+    }
+    return {
+        run: last ? { id: last.id, at: last.updatedAt.toISOString() } : null,
+        targets,
+        left,
+        outputs,
+    };
+}
+// The account a target sends with is a connection of its own, kept like the wizard's connections.
+registerConnectionSource(async (_run, connectionId, projectId) => {
+    if (!connectionId.startsWith("share:")) {
+        return null;
+    }
+    const target = await shareTarget(projectId, connectionId.slice("share:".length));
+    return target?.connection?.() ?? null;
+});

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

@@ -0,0 +1,186 @@
+import { noteText } from "@engenty-wizards/shared/run";
+import { connectionContext } from "../connectors/index.js";
+import { askPerson } from "../engine/asks.js";
+import { signalChanged } from "../engine/events.js";
+import { releaseResources } from "../engine/resources.js";
+import { loadProject, makeContext, projectIdOf } from "../engine/runner.js";
+import { env } from "../env.js";
+import { errorText } from "../model-errors.js";
+import { ServiceError } from "../services/errors.js";
+import { shareRun } from "../services/shares.js";
+import { scopeOf } from "../store/index.js";
+import { serverText } from "../texts.js";
+import { SHARE_STEP } from "./agent.js";
+import { shareFiles } from "./files.js";
+import { offeredTargets, targetScope } from "./index.js";
+import { addJobEvent, createJob, finishJob, jobCount, sentCount, setWorking, workingJob, } from "./state.js";
+import { parseRecipients } from "./targets/email.js";
+import { ShareError, sayIn } from "./types.js";
+/** What the person filled in does not do: per field, what is wrong. `_files` and `_account` name the other steps. */
+export class ShareInputError extends Error {
+    fields;
+    constructor(fields, said) {
+        super(Object.values(fields)[0] ?? said);
+        this.fields = fields;
+    }
+}
+/** Jobs one run of a person without an account may start. */
+const VISITOR_JOBS = 20;
+/** A link people elsewhere can open: not one that points at this machine. */
+function publicOrigin() {
+    const host = new URL(env.appUrl).hostname;
+    return !(host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".local") ||
+        host === "127.0.0.1" ||
+        host === "[::1]");
+}
+function contextOf(run, projectId, entry, who, job) {
+    const connection = entry.target.connection?.() ?? null;
+    const signal = job?.signal ?? new AbortController().signal;
+    const emit = (message) => job ? addJobEvent(run.id, job.id, sayIn(who.lang, message)) : Promise.resolve();
+    const ask = (question) => !job || run.unattended
+        ? Promise.resolve(null)
+        : askPerson(run.id, { ...question, stepId: SHARE_STEP }, signal);
+    return {
+        ...targetScope(run, projectId, who.lang),
+        signal,
+        member: who.member,
+        sentBefore: job?.sentBefore ?? 0,
+        emit,
+        ask,
+        account: () => connection ? connectionContext(scopeOf(run), connection, projectId) : Promise.resolve(null),
+        link: async () => (publicOrigin() ? (await shareRun(run)).url : null),
+        step: async () => makeContext(run, await loadProject(run), structuredClone(run.state), signal, {
+            stepId: SHARE_STEP,
+            emit: (_type, message) => emit(typeof message === "string" ? message : noteText(message, who.lang)),
+            ask,
+        }),
+    };
+}
+async function entryOf(run, projectId, key, member) {
+    const entry = (await offeredTargets(run, projectId, member)).find((e) => e.key === key);
+    if (!entry) {
+        throw new ServiceError("not_found", { server: "shareTargetUnknown" });
+    }
+    return entry;
+}
+/**
+ * Sends a finished result to one target. Answers as soon as the job stands; the work goes on in
+ * the background and shows in the run's view. One job per run at a time.
+ */
+export async function startShare(run, request, who) {
+    if (run.status !== "done") {
+        throw new ServiceError("refused", { server: "shareOnlyDone" });
+    }
+    if (workingJob(run.id)) {
+        throw new ServiceError("refused", { server: "shareBusy" });
+    }
+    // A run of someone without an account sends a limited number of times: it is no mail relay.
+    if (!who.member && (await jobCount(run.id)) >= VISITOR_JOBS) {
+        throw new ServiceError("refused", { server: "shareTooOften" });
+    }
+    const lang = request.lang ?? "en";
+    const projectId = await projectIdOf(run);
+    const entry = await entryOf(run, projectId, request.target, who.member);
+    const { target } = entry;
+    const values = {};
+    const errors = {};
+    for (const field of target.fields) {
+        const value = String(request.values[field.id] ?? "")
+            .trim()
+            .slice(0, field.kind === "textarea" ? 20_000 : 2000);
+        values[field.id] = value;
+        if (!value) {
+            if (field.required) {
+                errors[field.id] = serverText(lang, "shareRequired");
+            }
+            continue;
+        }
+        if (field.kind === "url" && !/^https?:\/\/[^\s/]+\.[^\s]+$/i.test(value)) {
+            errors[field.id] = serverText(lang, "shareNeedsHttps");
+        }
+        if (field.kind === "emails") {
+            try {
+                parseRecipients(value);
+            }
+            catch (err) {
+                errors[field.id] = errorText(err, lang);
+            }
+        }
+    }
+    const items = target.takes === "files" ? request.items.slice(0, 20) : [];
+    if (target.needsFiles && !items.length) {
+        errors._files = serverText(lang, "sharePickFile");
+    }
+    const connection = target.connection?.() ?? null;
+    if (connection && !(await connectionContext(scopeOf(run), connection, projectId))) {
+        errors._account = serverText(lang, "shareConnectAccount");
+    }
+    if (Object.keys(errors).length) {
+        throw new ShareInputError(errors, serverText(lang, "shareCheckInput"));
+    }
+    const job = await createJob({
+        runId: run.id,
+        target: target.id,
+        name: entry.label ?? sayIn(lang, target.name),
+        icon: target.icon,
+        request: { target: request.target, items, values, lang },
+    });
+    const abort = new AbortController();
+    setWorking(run.id, { jobId: job.id, abort });
+    const ctx = contextOf(run, projectId, entry, { member: who.member, lang }, { id: job.id, signal: abort.signal, sentBefore: await sentCount(run.id, target.id) });
+    void (async () => {
+        try {
+            if (items.length) {
+                await ctx.emit({ server: "sharePreparing" });
+            }
+            const files = await shareFiles(run, items);
+            const outcome = await target.send({ values, files }, ctx);
+            await finishJob(run.id, job.id, abort.signal.aborted
+                ? { status: "cancelled" }
+                : {
+                    status: "done",
+                    result: { summary: sayIn(lang, outcome.summary), url: outcome.url ?? null },
+                });
+        }
+        catch (err) {
+            if (!abort.signal.aborted && !(err instanceof ShareError)) {
+                console.error(`[share ${run.id} → ${target.id}]`, err);
+            }
+            await finishJob(run.id, job.id, abort.signal.aborted
+                ? { status: "cancelled" }
+                : {
+                    status: "failed",
+                    error: err instanceof ShareError
+                        ? errorText(err, lang)
+                        : `${serverText(lang, "shareFailed")}: ${String(err?.message ?? err).slice(0, 240)}`,
+                }).catch(() => undefined);
+        }
+        finally {
+            setWorking(run.id, null);
+            await releaseResources(run.id).catch(() => undefined);
+            signalChanged(run.id);
+        }
+    })();
+    return job;
+}
+/** Stops the job a run is working on; what it already sent stays sent. */
+export async function cancelShare(runId, jobId) {
+    const job = workingJob(runId);
+    if (!job || (jobId && job.jobId !== jobId)) {
+        return false;
+    }
+    job.abort.abort();
+    await finishJob(runId, job.jobId, { status: "cancelled" });
+    return true;
+}
+/** The choices of a form field that come from the connected account (Slack's channels). */
+export async function shareChoices(run, key, field, who) {
+    const projectId = await projectIdOf(run);
+    const entry = await entryOf(run, projectId, key, who.member);
+    if (!entry.target.choices) {
+        return [];
+    }
+    return entry.target.choices(field, contextOf(run, projectId, entry, who, null));
+}