@engenty/wizards-runtime 0.0.0-stage → 0.7.6

package/apps/runtime/dist/secrets/signing.js

@@ -0,0 +1,52 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { env } from "../env.js";
+/** The query the signature covers: everything but exp/sig, sorted, so parameter order never matters. */
+function payload(url, exp) {
+    const params = [...url.searchParams.entries()]
+        .filter(([k]) => k !== "exp" && k !== "sig")
+        .sort(([a], [b]) => a.localeCompare(b));
+    return `${url.pathname}?${new URLSearchParams(params)}|${exp}`;
+}
+function sign(data) {
+    return createHmac("sha256", env.authSecret).update(data).digest("base64url");
+}
+/**
+ * A link that opens one GET path without a session — for clients that have no studio cookie,
+ * such as an MCP client handing a download to the admin.
+ */
+export function signedUrl(path, ttlSeconds = 3600) {
+    const url = new URL(path, env.appUrl);
+    const exp = String(Math.floor(Date.now() / 1000) + ttlSeconds);
+    url.searchParams.set("exp", exp);
+    url.searchParams.set("sig", sign(payload(url, exp)));
+    return url.toString();
+}
+function sameSignature(data, sig) {
+    const expected = Buffer.from(sign(data));
+    const given = Buffer.from(sig);
+    return expected.length === given.length && timingSafeEqual(expected, given);
+}
+export function verifySignedUrl(href) {
+    const url = new URL(href, env.appUrl);
+    const exp = url.searchParams.get("exp");
+    const sig = url.searchParams.get("sig");
+    if (!exp || !sig || Number(exp) * 1000 < Date.now()) {
+        return false;
+    }
+    return sameSignature(payload(url, exp), sig);
+}
+/**
+ * A ticket to one run's routes without a session: the widget an AI app shows runs on the host's
+ * origin and reaches the run with it. Sent as `?rt=`, since an EventSource sends no headers.
+ */
+export function runTicket(runId, ttlSeconds = 12 * 3600) {
+    const exp = String(Math.floor(Date.now() / 1000) + ttlSeconds);
+    return `${exp}.${sign(`run:${runId}|${exp}`)}`;
+}
+export function runTicketValid(runId, ticket) {
+    const [exp, sig] = (ticket ?? "").split(".");
+    if (!exp || !sig || Number(exp) * 1000 < Date.now()) {
+        return false;
+    }
+    return sameSignature(`run:${runId}|${exp}`, sig);
+}

package/apps/runtime/dist/secrets/vault.js

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { env } from "../env.js";
+import { seal, unseal } from "./crypto.js";
+const run = promisify(execFile);
+/**
+ * Secrets of a runtime that runs alone: the keys the person entered and the linked account's
+ * refresh token. In the desktop app (`SECRETS=keychain`) they live in the macOS Keychain, never
+ * in the database; elsewhere in an encrypted file in the data folder.
+ */
+const SERVICE = "engenty-wizards";
+const keychain = process.env.SECRETS === "keychain" && process.platform === "darwin";
+const file = join(env.dataDir, "vault");
+function readFileVault() {
+    if (!existsSync(file)) {
+        return {};
+    }
+    return unseal(readFileSync(file, "utf8").trim()) ?? {};
+}
+function writeFileVault(all) {
+    writeFileSync(file, seal(all), { mode: 0o600 });
+}
+export async function vaultGet(name) {
+    if (!keychain) {
+        return readFileVault()[name] ?? null;
+    }
+    try {
+        const { stdout } = await run("security", [
+            "find-generic-password",
+            "-s",
+            SERVICE,
+            "-a",
+            name,
+            "-w",
+        ]);
+        return stdout.replace(/\n$/, "") || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function vaultSet(name, value) {
+    if (!keychain) {
+        writeFileVault({ ...readFileVault(), [name]: value });
+        return;
+    }
+    await run("security", ["add-generic-password", "-U", "-s", SERVICE, "-a", name, "-w", value]);
+}
+export async function vaultDelete(name) {
+    if (!keychain) {
+        const all = readFileVault();
+        delete all[name];
+        writeFileVault(all);
+        return;
+    }
+    await run("security", ["delete-generic-password", "-s", SERVICE, "-a", name]).catch(() => undefined);
+}

package/apps/runtime/dist/services/access.js

@@ -0,0 +1,88 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { note } from "@engenty-wizards/shared/run";
+import { and, eq } from "drizzle-orm";
+import { db, schema } from "../db/client.js";
+import { managed, tenantInfo } from "../manage.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { ServiceError } from "./errors.js";
+/**
+ * Who may change what on this runtime. A project a local install synced (`origin: "local"`) is
+ * changed only by that install's next sync: here it is shown and run. And a tenant the
+ * Manage-App gives no building (`limits.build: false`) makes and changes nothing on this
+ * runtime. Every write of a project or a wizard asks here, whichever way it came in: studio,
+ * MCP client or API.
+ */
+const sync = new AsyncLocalStorage();
+/** Runs the writes of a sync: they are the one way a synced project changes. */
+export function asSync(fn) {
+    return sync.run(true, fn);
+}
+const syncing = () => sync.getStore() === true;
+// --- roles -----------------------------------------------------------------------------
+// In a team, an owner or admin makes and deletes (wizards, spaces, connectors); a member edits
+// the wizards there are. A runtime that runs alone has one person, who does everything.
+const actor = new AsyncLocalStorage();
+/** Runs a request as the person's role in the tenant; set once per entry, like the tenant. */
+export function asRole(role, fn) {
+    return actor.run(role, fn);
+}
+/** The role of who acts now. A context without one (a job, a sync) acts as the owner. */
+export function currentRole() {
+    return actor.getStore() ?? "owner";
+}
+export const isAdminRole = (role) => role === "owner" || role === "admin";
+export const MEMBERS_EDIT_ONLY = note("onlyTeamAdmins");
+/** Refuses a member: making and deleting is for the owner and the admins of the team. */
+export async function requireAdmin() {
+    if (syncing() || !managed || isAdminRole(currentRole())) {
+        return;
+    }
+    throw new ServiceError("forbidden", MEMBERS_EDIT_ONLY);
+}
+/** Whether the person makes and deletes here: builds at all, and is no mere member. */
+export async function mayCreate() {
+    return (await mayBuild()) && (!managed || isAdminRole(currentRole()));
+}
+/** Whether the tenant builds wizards on this runtime. A runtime that runs alone always does. */
+export async function mayBuild() {
+    if (!managed) {
+        return true;
+    }
+    const info = await tenantInfo(currentTenant()).catch(() => null);
+    // An older Manage-App does not say: then it builds. One that cannot be reached: nothing changes.
+    return info ? info.limits.build !== false : false;
+}
+export const READ_ONLY_PROJECT = note("spaceEditedLocally");
+export const READ_ONLY_TENANT = note("wizardsRunOncePublished");
+/** Refuses when the tenant builds nothing here. */
+export async function requireBuild() {
+    if (syncing() || (await mayBuild())) {
+        return;
+    }
+    throw new ServiceError("read_only", READ_ONLY_TENANT);
+}
+/** Refuses a change of a synced project, and any change by a tenant that builds nothing here. */
+export async function requireWritable(project) {
+    if (syncing()) {
+        return;
+    }
+    if (project.origin === "local") {
+        throw new ServiceError("read_only", READ_ONLY_PROJECT);
+    }
+    await requireBuild();
+}
+export async function requireWritableProject(projectId) {
+    if (syncing()) {
+        return;
+    }
+    const project = await db.query.project.findFirst({
+        where: and(eq(schema.project.id, projectId), eq(schema.project.tenantId, currentTenant())),
+        columns: { origin: true },
+    });
+    // A project that is not there is the caller's "not found", not ours.
+    await requireWritable(project ?? { origin: null });
+}
+/** Whether the person may change this project's wizards and settings here. */
+export async function projectWritable(project) {
+    return project.origin !== "local" && (await mayBuild());
+}

package/apps/runtime/dist/services/api.js

@@ -0,0 +1,248 @@
+import { textLang, wizardLang, } from "@engenty-wizards/shared/definition";
+import { standaloneEntry } from "@engenty-wizards/shared/fit";
+import { pluginsOf } from "@engenty-wizards/shared/marketplace";
+import { noteText } from "@engenty-wizards/shared/run";
+import { and, count, desc, eq, gte, inArray, isNotNull, or, sql } from "drizzle-orm";
+import { MICROS_PER_CREDIT } from "../credits/credits.js";
+import { db, schema } from "../db/client.js";
+import { env } from "../env.js";
+import { wizardUnavailable } from "../limits.js";
+import { codeOf } from "../tenants/control.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { serverText } from "../texts.js";
+import { mayBuild, projectWritable, READ_ONLY_TENANT } from "./access.js";
+import { mainLogoId } from "./brand.js";
+import { notFound, ServiceError } from "./errors.js";
+import { knowledgeCounts } from "./knowledge.js";
+import { listProjects, ownedProject } from "./projects.js";
+import { runReport } from "./runs.js";
+import { shareUrlFor } from "./shares.js";
+import { shareUrl, studioUrl } from "./wizards.js";
+/** The spaces the caller works with, as the studio lists them, and whether each may change here. */
+export async function apiSpaces(userId) {
+    const projects = await listProjects(userId);
+    return Promise.all(projects.map(async (p) => ({
+        id: p.id,
+        name: p.name,
+        title: p.brand.name ?? "",
+        wizards: p.wizardCount,
+        writable: await projectWritable(p),
+    })));
+}
+/** The space a call names, or the one a caller means when it names none: the first one listed. */
+export async function apiSpace(userId, spaceId) {
+    if (spaceId) {
+        return ownedProject(userId, spaceId);
+    }
+    const [first] = await listProjects(userId);
+    if (!first) {
+        // A plan that builds nothing here has a space only once its local install synced one.
+        if (!(await mayBuild())) {
+            throw new ServiceError("read_only", READ_ONLY_TENANT);
+        }
+        throw notFound();
+    }
+    return first;
+}
+/** The space's own details: what it says about itself, and what its wizards look things up in. */
+export async function apiSpaceDetails(userId, spaceId) {
+    const p = await apiSpace(userId, spaceId);
+    const logo = await mainLogoId(p.id);
+    return {
+        id: p.id,
+        name: p.name,
+        title: p.brand.name ?? "",
+        about: p.brand.about ?? "",
+        colors: p.brand.colors ?? [],
+        facts: p.facts.map(({ label, value }) => ({ label, value })),
+        logoUrl: logo ? `${env.publicUrl}/api/public/logos/${logo}` : null,
+        knowledge: await knowledgeCounts(p.id),
+        writable: await projectWritable(p),
+        studioUrl: `${env.appUrl}/studio/space`,
+    };
+}
+/**
+ * The wizards of the caller's spaces, newest change first. A published one carries what a website
+ * embeds it with: its link's token and the ID the mobile app takes.
+ */
+export async function apiWizards(userId, spaceId) {
+    const spaces = (await listProjects(userId)).filter((p) => !spaceId || p.id === spaceId);
+    if (!spaces.length) {
+        return [];
+    }
+    const rows = await db.query.wizard.findMany({
+        where: and(eq(schema.wizard.tenantId, currentTenant()), inArray(schema.wizard.projectId, spaces.map((p) => p.id))),
+        orderBy: [desc(schema.wizard.updatedAt)],
+    });
+    const published = rows.filter((w) => w.publishedVersion !== null);
+    const versions = published.length
+        ? await db.query.wizardVersion.findMany({
+            where: or(...published.map((w) => and(eq(schema.wizardVersion.wizardId, w.id), eq(schema.wizardVersion.version, w.publishedVersion)))),
+            columns: { wizardId: true, definition: true },
+        })
+        : [];
+    return Promise.all(rows.map(async (w) => {
+        const live = versions.find((v) => v.wizardId === w.id)?.definition;
+        const def = live ?? w.draft;
+        const reason = live ? await wizardUnavailable(w) : null;
+        return {
+            id: w.id,
+            spaceId: w.projectId,
+            title: def.title,
+            description: def.description ?? "",
+            avatar: def.avatar ?? null,
+            published: Boolean(live),
+            publishedVersion: w.publishedVersion,
+            token: live ? w.shareToken : null,
+            code: live ? await codeOf(w.shareToken) : null,
+            shareUrl: live ? shareUrl(w.shareToken) : null,
+            shareEnabled: w.shareEnabled,
+            iconUrl: live
+                ? `${env.publicUrl}/api/public/wizards/${w.shareToken}/icons/icon-192.png`
+                : null,
+            available: Boolean(live) && !reason,
+            unavailableReason: reason && noteText(reason, wizardLang(def)),
+            dailyRunLimit: w.dailyRunLimit,
+            /** The plugins its steps call: a wizard that books needs `appointments`. */
+            plugins: pluginsOf(def),
+            /** Whether it runs on a website by itself, in the gallery's words (packages/shared/src/fit.ts). */
+            standalone: standaloneEntry(def),
+            studioUrl: studioUrl(w.id),
+            updatedAt: w.updatedAt.toISOString(),
+        };
+    }));
+}
+/** A value as one line of text, in the wizard's language: what the person typed or picked. */
+function answerText(field, value, lang) {
+    if (value === undefined || value === null || value === "") {
+        return "";
+    }
+    if (typeof value === "boolean") {
+        return serverText(lang, value ? "yes" : "no");
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        if (["file", "image", "audio", "signature"].includes(field.kind)) {
+            return serverText(lang, "fileCount", { count: value.length });
+        }
+        return value
+            .map((v) => (typeof v === "object" && v ? Object.values(v).join(" ") : String(v)))
+            .join(", ");
+    }
+    if (typeof value === "object") {
+        const v = value;
+        const said = v.label ?? v.address ?? v.text ?? v.name ?? v.start;
+        return typeof said === "string" ? said : JSON.stringify(value).slice(0, 200);
+    }
+    return "";
+}
+/** What the person answered on the run's pages, by the fields' labels, in the order asked. */
+function answersOf(run) {
+    const answers = [];
+    const lang = textLang(wizardLang(run.definition));
+    for (const step of run.definition.steps) {
+        if (step.type !== "page") {
+            continue;
+        }
+        for (const field of step.fields) {
+            const value = answerText(field, run.state.values[field.id], lang);
+            if (value) {
+                answers.push({ field: field.id, label: field.label, kind: field.kind, value });
+            }
+        }
+    }
+    return answers;
+}
+/** The person's address where a page asked for one: the first e-mail field answered. */
+function emailOf(answers) {
+    return (answers.find((a) => a.kind === "email")?.value ??
+        answers.find((a) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(a.value))?.value ??
+        null);
+}
+const PAGE = 50;
+/** The live runs of the caller's wizards, newest first, by pages of 50: what visitors left. */
+export async function apiRuns(userId, filter = {}) {
+    const wizards = await apiWizards(userId, filter.spaceId);
+    const ids = wizards.map((w) => w.id).filter((id) => !filter.wizardId || id === filter.wizardId);
+    const page = Math.max(1, filter.page ?? 1);
+    if (!ids.length) {
+        return { runs: [], page, pages: 0, total: 0 };
+    }
+    const q = filter.q?.trim().toLowerCase();
+    const like = q ? `%${q.replace(/[\\%_]/g, (c) => `\\${c}`)}%` : null;
+    const status = filter.status ?? "done";
+    const where = and(inArray(schema.run.wizardId, ids), eq(schema.run.mode, "live"), status === "done"
+        ? eq(schema.run.status, "done")
+        : status === "open"
+            ? inArray(schema.run.status, ["waiting_input", "running"])
+            : undefined, filter.days
+        ? gte(schema.run.createdAt, new Date(Date.now() - filter.days * 86_400_000))
+        : undefined, like
+        ? or(sql `lower(${schema.run.state}) like ${like} escape '\\'`, sql `lower(coalesce(${schema.run.origin}, '')) like ${like} escape '\\'`)
+        : undefined);
+    const [{ total }] = await db.select({ total: count() }).from(schema.run).where(where);
+    const rows = await db.query.run.findMany({
+        where,
+        orderBy: [desc(schema.run.createdAt)],
+        limit: PAGE,
+        offset: (page - 1) * PAGE,
+    });
+    const assets = rows.length
+        ? await db
+            .select({ runId: schema.asset.runId, n: count() })
+            .from(schema.asset)
+            .where(and(isNotNull(schema.asset.runId), inArray(schema.asset.runId, rows.map((r) => r.id))))
+            .groupBy(schema.asset.runId)
+        : [];
+    return {
+        runs: rows.map((r) => {
+            const answers = answersOf(r);
+            return {
+                id: r.id,
+                wizardId: r.wizardId,
+                wizard: wizards.find((w) => w.id === r.wizardId)?.title ?? r.definition.title,
+                status: r.status,
+                step: r.definition.steps.find((s) => s.id === r.cursor)?.title ?? null,
+                createdAt: r.createdAt.toISOString(),
+                updatedAt: r.updatedAt.toISOString(),
+                origin: r.origin,
+                email: emailOf(answers),
+                /** The first answers, for a line in a list. */
+                summary: answers
+                    .slice(0, 3)
+                    .map((a) => a.value)
+                    .join(" · ")
+                    .slice(0, 200),
+                credits: Math.ceil(r.costMicros / MICROS_PER_CREDIT),
+                files: assets.find((a) => a.runId === r.id)?.n ?? 0,
+            };
+        }),
+        page,
+        pages: Math.ceil(total / PAGE),
+        total,
+    };
+}
+/** One run with everything a reader of the result needs: the answers, the outputs, the downloads. */
+export async function apiRun(userId, runId) {
+    // Refuses what is no live run of the tenant.
+    const report = await runReport(userId, runId, 0, "live");
+    const run = await db.query.run.findFirst({
+        where: and(eq(schema.run.id, runId), eq(schema.run.tenantId, currentTenant())),
+    });
+    if (!run) {
+        throw notFound();
+    }
+    const answers = answersOf(run);
+    return {
+        ...report,
+        wizard: run.definition.title,
+        createdAt: run.createdAt.toISOString(),
+        updatedAt: run.updatedAt.toISOString(),
+        origin: run.origin,
+        email: emailOf(answers),
+        answers: answers.map(({ label, kind, value }) => ({ label, kind, value })),
+        shareUrl: run.shareToken ? shareUrlFor(run.shareToken) : null,
+    };
+}

package/apps/runtime/dist/services/architect.js

@@ -0,0 +1,95 @@
+import { eq } from "drizzle-orm";
+import { runArchitect } from "../agents/architect.js";
+import { chatEngine, subscriptionTurn } from "../agents/subscription.js";
+import { listConnectors } from "../connectors/external.js";
+import { db, schema } from "../db/client.js";
+import { managed } from "../manage.js";
+import { hasTextModel } from "../models.js";
+import { serverText } from "../texts.js";
+import { draftFiles, readFile } from "./files.js";
+import { ownedProject } from "./projects.js";
+import { addMessage, draftIssues, ownedWizard, wizardMessages, writableWizard } from "./wizards.js";
+/** The formats a model can look at; an SVG it reads as text. */
+const VISIBLE = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+/** A picture larger than this would pass the model's limit once base64-encoded. */
+const VISIBLE_BYTES = 3_700_000;
+/** The pictures a message attaches ("Angehängt: a.png, b.pdf"), read from the workspace. */
+async function attachedImages(userId, wizardId, message) {
+    const names = message.match(/(?:^|\n\n)(?:Angehängt|Attached): ([^\n]+)$/)?.[1]?.split(", ");
+    const images = [];
+    for (const name of names?.slice(0, 8) ?? []) {
+        try {
+            const { file, data } = await readFile(userId, wizardId, name);
+            if (VISIBLE.has(file.mime) && data.byteLength <= VISIBLE_BYTES) {
+                images.push({ path: file.path, mime: file.mime, data });
+            }
+        }
+        catch {
+            // A name that is no workspace file stays text.
+        }
+    }
+    return images;
+}
+/** One studio chat turn: the architect reads the draft, its workspace and the thread, and changes them with tools. */
+export async function architectTurn(userId, wizardId, message, 
+/** The language the admin reads: the lines about what it does, and its stock replies. */
+lang, io) {
+    // Asked before the first model call: a wizard that is not changed here costs nothing to refuse.
+    const w = await writableWizard(userId, wizardId);
+    const history = await wizardMessages(w.id);
+    const project = await ownedProject(userId, w.projectId);
+    const images = await attachedImages(userId, w.id, message);
+    const userMessageId = await addMessage(w.id, { role: "user", content: message });
+    try {
+        // A runtime that runs alone can answer the chat on the admin's own Claude subscription.
+        const engine = managed ? "models" : await chatEngine(await hasTextModel());
+        const result = engine === "claude"
+            ? {
+                ...(await subscriptionTurn({
+                    wizardId: w.id,
+                    message,
+                    signal: io.signal,
+                    onText: io.onText,
+                    onActivity: io.onActivity,
+                    onThought: io.onThought,
+                    onBuilding: io.onBuilding,
+                    images,
+                    lang,
+                })),
+                unfinished: false,
+            }
+            : await runArchitect({
+                userId,
+                wizardId: w.id,
+                message,
+                history: history.map((m) => ({ role: m.role, content: m.content })),
+                mcpServers: project.mcpServers.map((s) => ({ id: s.id, name: s.name })),
+                connectors: await listConnectors(project.id),
+                signal: io.signal,
+                onText: io.onText,
+                onActivity: io.onActivity,
+                onThought: io.onThought,
+                onBuilding: io.onBuilding,
+                images,
+                lang,
+            });
+        const reply = result.unfinished
+            ? `${result.reply ? `${result.reply}\n\n` : ""}${serverText(lang, "notFinished")}`
+            : result.reply || serverText(lang, result.changed ? "done" : "notUnderstood");
+        await addMessage(w.id, { role: "assistant", content: reply, changed: result.changed });
+        const after = await ownedWizard(userId, wizardId);
+        return {
+            reply,
+            changed: result.changed,
+            draft: after.draft,
+            revision: after.revision,
+            files: await draftFiles(after.id),
+            issues: await draftIssues(after),
+        };
+    }
+    catch (err) {
+        // An unanswered turn would repeat in the next turn's history.
+        await db.delete(schema.wizardMessage).where(eq(schema.wizardMessage.id, userMessageId));
+        throw err;
+    }
+}