@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/assistant/knows.js

@@ -0,0 +1,353 @@
+import { createTool } from "@mastra/core/tools";
+import { and, desc, eq, inArray } from "drizzle-orm";
+import { z } from "zod";
+import { accountOverview, accountToken, linkedAccount } from "../auth/account.js";
+import { authoringGuide } from "../authoring/guide.js";
+import { listConnectors } from "../connectors/external.js";
+import { db, schema } from "../db/client.js";
+import { env } from "../env.js";
+import { detectHarnesses } from "../harness/index.js";
+import { managed, publicPlans, tenantInfo, tenantUsage } from "../manage.js";
+import { classWays, waysIn } from "../models.js";
+import { pluginToolsOf } from "../plugins/registry.js";
+import { earlierChats, readChat, searchChats } from "../services/assistant-chats.js";
+import { asLang, marketplaceDetail, searchMarketplace } from "../services/marketplace.js";
+import { listWizards } from "../services/wizards.js";
+import { serverText } from "../texts.js";
+import { attempt } from "../tools/shared.js";
+import { readDoc, searchDocs } from "./docs.js";
+/** Where the account lives: the runtime's Manage-App, or the account a local install links. */
+const accountBase = () => (managed ? env.manage.url : env.local.accountUrl);
+async function usageOf(tenantId) {
+    if (managed) {
+        return tenantUsage(tenantId, 3);
+    }
+    const token = await accountToken();
+    if (!token) {
+        return null;
+    }
+    const res = await fetch(`${env.local.accountUrl}/v1/me/usage?months=3`, {
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        throw new Error(`The account answered ${res.status}.`);
+    }
+    return (await res.json());
+}
+const NOT_LINKED = "This install is not linked to an account. Settings › Account signs one in; then credits, cloud publishing and plans apply. Docs and the gallery work without one.";
+export function knowsTools(ctx) {
+    const { user } = ctx;
+    // The entries this turn's searches found, so show_templates needs no second request.
+    const found = new Map();
+    return {
+        docs_search: createTool({
+            id: "docs_search",
+            description: "Search the engenty wizards user guide and plugin guide of this installed version. Gives the best sections with an excerpt and their engenty.ai/docs link. Use it before you explain how something works.",
+            inputSchema: z.object({ query: z.string().min(2).max(200) }),
+            execute: async ({ query }) => {
+                ctx.doing(serverText(ctx.lang, "doingReadGuide"));
+                return { hits: searchDocs(query) };
+            },
+        }),
+        docs_read: createTool({
+            id: "docs_read",
+            description: "Read one page of the guides by its id from docs_search (user/steps, dev/plugins/tools), from a character on.",
+            inputSchema: z.object({
+                page: z.string().min(1).max(200),
+                from: z.number().int().min(0).optional(),
+            }),
+            execute: async ({ page, from }) => {
+                ctx.doing(serverText(ctx.lang, "doingReadGuide"));
+                return readDoc(page, from ?? 0);
+            },
+        }),
+        authoring_guide: createTool({
+            id: "authoring_guide",
+            description: "The authoring guide the wizard editor and AI apps build with: how a wizard is written (steps, fields, flows, tools, outputs, model classes). Long: read it in parts with `from`.",
+            inputSchema: z.object({ from: z.number().int().min(0).optional() }),
+            execute: ({ from }) => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingAuthoringGuide"));
+                const guide = authoringGuide(ctx.project?.mcpServers ?? [], ctx.project ? await listConnectors(ctx.project.id) : [], await pluginToolsOf(user.tenantId));
+                const start = Math.min(from ?? 0, guide.length);
+                return {
+                    text: guide.slice(start, start + 14_000),
+                    next: start + 14_000 < guide.length ? start + 14_000 : null,
+                };
+            }),
+        }),
+        gallery_search: createTool({
+            id: "gallery_search",
+            description: "Search the gallery of wizard templates (engenty.ai/wizards and the plugins' starters): title, pitch, what it needs that this install has no model for, and its price per run in credits.",
+            inputSchema: z.object({ query: z.string().max(200).optional() }),
+            execute: ({ query }) => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingGallery"));
+                const hits = await searchMarketplace({
+                    q: query ?? "",
+                    lang: asLang(ctx.lang),
+                    limit: 8,
+                });
+                for (const e of hits.entries) {
+                    found.set(e.id, e);
+                }
+                return {
+                    total: hits.total,
+                    offline: hits.offline,
+                    entries: hits.entries.map((e) => ({
+                        id: e.id,
+                        title: e.title,
+                        pitch: e.pitch,
+                        formats: e.formats,
+                        steps: e.steps,
+                        credits: e.credits,
+                        missing: e.missing,
+                        needsPlugins: e.needs ?? [],
+                        plugin: e.plugin?.name,
+                    })),
+                };
+            }),
+        }),
+        gallery_detail: createTool({
+            id: "gallery_detail",
+            description: "One template of the gallery: what it does, its steps, what it makes and needs.",
+            inputSchema: z.object({ id: z.string().min(1).max(120) }),
+            execute: ({ id }) => attempt(async () => {
+                const detail = await marketplaceDetail(id, asLang(ctx.lang));
+                if (!detail) {
+                    return { error: "No such template." };
+                }
+                const { terms: _terms, hash: _hash, ...rest } = detail;
+                return rest;
+            }),
+        }),
+        show_templates: createTool({
+            id: "show_templates",
+            description: "Show templates of the gallery as cards under your answer, in the order given. A card shows the title, the pitch, the time, the cost and what it makes; the person opens it to see the steps and make a wizard of it.",
+            inputSchema: z.object({ ids: z.array(z.string().min(1).max(120)).min(1).max(6) }),
+            execute: ({ ids }) => attempt(async () => {
+                const entries = [];
+                for (const id of new Set(ids)) {
+                    const entry = found.get(id) ?? (await marketplaceDetail(id, asLang(ctx.lang)));
+                    if (!entry) {
+                        continue;
+                    }
+                    // The card needs the entry, not the outline the dialog loads by itself.
+                    const { terms: _terms, hash: _hash, description: _description, outline: _outline, results: _results, files: _files, ...shown } = entry;
+                    entries.push(shown);
+                }
+                if (!entries.length) {
+                    return { error: "None of these templates is in the gallery." };
+                }
+                ctx.card({ plugin: "", tool: "templates", data: { entries } });
+                return { shown: entries.map((e) => e.title) };
+            }),
+        }),
+        plans: createTool({
+            id: "plans",
+            description: "The plans teams can be on (Free, Pro, Team): price a month, monthly credits, limits, and the credit packages to buy on top. Live from the account service.",
+            inputSchema: z.object({}),
+            execute: () => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingPlans"));
+                const plans = await publicPlans(accountBase());
+                return { ...plans, billingPage: `${accountBase()}/billing` };
+            }),
+        }),
+        account: createTool({
+            id: "account",
+            description: "The person, their team, their role, the team's plan, the credit balance and credits that end on a date.",
+            inputSchema: z.object({}),
+            execute: () => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingAccount"));
+                if (managed) {
+                    const info = await tenantInfo(user.tenantId, true);
+                    return {
+                        person: { name: user.name, email: user.email, role: user.role },
+                        team: { name: info.name, plan: info.plan?.name ?? null, status: info.status },
+                        balanceCredits: Math.floor(info.balanceCredits),
+                        limits: info.limits,
+                        billingPage: `${env.manage.url}/billing`,
+                    };
+                }
+                if (!(await linkedAccount())) {
+                    return { linked: false, note: NOT_LINKED };
+                }
+                const overview = await accountOverview();
+                if (!overview) {
+                    return {
+                        linked: true,
+                        signedIn: false,
+                        note: "The sign-in ran out: Settings › Account signs in again.",
+                    };
+                }
+                return {
+                    linked: true,
+                    person: overview.user,
+                    team: { name: overview.tenant.name, role: overview.tenant.role },
+                    plan: overview.tenant.plan?.name ?? null,
+                    balanceCredits: Math.floor(overview.tenant.balanceCredits),
+                    expiring: overview.tenant.expiring ?? [],
+                    billingPage: `${env.local.accountUrl}/billing`,
+                };
+            }),
+        }),
+        usage: createTool({
+            id: "usage",
+            description: "Credits the team used per month (the last three), and the runs and wizards that cost the most.",
+            inputSchema: z.object({}),
+            execute: () => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingUsage"));
+                if (!(managed || (await linkedAccount()))) {
+                    return { linked: false, note: NOT_LINKED };
+                }
+                const usage = await usageOf(user.tenantId);
+                if (!usage) {
+                    return { note: "The sign-in ran out: Settings › Account signs in again." };
+                }
+                const runIds = [...new Set(usage.months.flatMap((m) => m.runs.map((r) => r.runId)))];
+                const runs = runIds.length
+                    ? await db
+                        .select({ id: schema.run.id, wizard: schema.wizard.title, mode: schema.run.mode })
+                        .from(schema.run)
+                        .innerJoin(schema.wizard, eq(schema.wizard.id, schema.run.wizardId))
+                        .where(inArray(schema.run.id, runIds))
+                    : [];
+                const byRun = new Map(runs.map((r) => [r.id, r]));
+                return {
+                    months: usage.months.map((m) => {
+                        const perWizard = new Map();
+                        for (const r of m.runs) {
+                            const title = byRun.get(r.runId)?.wizard ?? "(a run of another install)";
+                            perWizard.set(title, (perWizard.get(title) ?? 0) + r.credits);
+                        }
+                        return {
+                            month: m.month,
+                            credits: m.credits,
+                            wizards: [...perWizard.entries()]
+                                .map(([wizard, credits]) => ({
+                                wizard,
+                                credits: Math.round(credits * 100) / 100,
+                            }))
+                                .sort((a, b) => b.credits - a.credits)
+                                .slice(0, 10),
+                        };
+                    }),
+                };
+            }),
+        }),
+        wizards: createTool({
+            id: "wizards",
+            description: "The space's wizards: title, description, published or draft, whether its link is on, steps, last change.",
+            inputSchema: z.object({}),
+            execute: () => attempt(async () => {
+                if (!ctx.project) {
+                    return { note: "No space is open." };
+                }
+                return {
+                    wizards: (await listWizards(user.id, ctx.project.id)).map((w) => ({
+                        id: w.id,
+                        title: w.title,
+                        description: w.description,
+                        published: w.published,
+                        linkOn: w.shareEnabled,
+                        steps: w.stepCount,
+                        updatedAt: w.updatedAt,
+                        editor: `/edit/${w.id}`,
+                    })),
+                };
+            }),
+        }),
+        runs: createTool({
+            id: "runs",
+            description: "The space's latest runs, newest first: wizard, test or live, status, the error of a failed one.",
+            inputSchema: z.object({
+                status: z.enum(["failed", "done", "running", "waiting_input", "cancelled"]).optional(),
+                limit: z.number().int().min(1).max(40).optional(),
+            }),
+            execute: ({ status, limit }) => attempt(async () => {
+                if (!ctx.project) {
+                    return { note: "No space is open." };
+                }
+                const rows = await db
+                    .select({
+                    id: schema.run.id,
+                    wizard: schema.wizard.title,
+                    wizardId: schema.wizard.id,
+                    mode: schema.run.mode,
+                    status: schema.run.status,
+                    error: schema.run.error,
+                    runner: schema.run.runner,
+                    createdAt: schema.run.createdAt,
+                })
+                    .from(schema.run)
+                    .innerJoin(schema.wizard, eq(schema.wizard.id, schema.run.wizardId))
+                    .where(and(eq(schema.wizard.projectId, ctx.project.id), status ? eq(schema.run.status, status) : undefined))
+                    .orderBy(desc(schema.run.createdAt))
+                    .limit(limit ?? 15);
+                return {
+                    runs: rows.map((r) => ({
+                        ...r,
+                        error: r.error?.slice(0, 400) ?? null,
+                        createdAt: r.createdAt.toISOString(),
+                    })),
+                };
+            }),
+        }),
+        models: createTool({
+            id: "models",
+            description: "What thinks and makes for this install, per model class: an installed AI client, an own key, a local model, credits, or nothing (with the problem). Also which AI clients are installed and signed in.",
+            inputSchema: z.object({}),
+            execute: () => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingModels"));
+                return {
+                    classes: waysIn(await classWays(), "en"),
+                    clients: managed
+                        ? []
+                        : (await detectHarnesses()).map((h) => ({
+                            id: h.id,
+                            installed: Boolean(h.version),
+                            signedIn: h.auth !== "none",
+                        })),
+                    page: "/settings/models",
+                };
+            }),
+        }),
+        chats_search: createTool({
+            id: "chats_search",
+            description: "Search the person's earlier chats with you (their messages and summaries) for words: what was asked, changed or decided before.",
+            inputSchema: z.object({ query: z.string().min(3).max(200) }),
+            execute: ({ query }) => attempt(async () => {
+                ctx.doing(serverText(ctx.lang, "doingEarlierChats"));
+                const hits = (await searchChats(user, query)).filter((h) => h.chatId !== ctx.chatId);
+                return {
+                    hits,
+                    recent: hits.length
+                        ? undefined
+                        : (await earlierChats(user, 10)).map((c) => ({
+                            id: c.id,
+                            title: c.title,
+                            closedAt: c.closedAt,
+                        })),
+                };
+            }),
+        }),
+        chat_read: createTool({
+            id: "chat_read",
+            description: "Read one earlier chat by its id (from chats_search): its summary and messages.",
+            inputSchema: z.object({ id: z.string().min(1).max(40) }),
+            execute: ({ id }) => attempt(async () => {
+                const chat = await readChat(user, id);
+                return {
+                    title: chat.title,
+                    summary: chat.summary,
+                    startedAt: chat.startedAt,
+                    closedAt: chat.closedAt,
+                    messages: chat.messages.slice(-40).map((m) => ({
+                        role: m.role,
+                        text: m.content.slice(0, 2000),
+                        at: m.createdAt,
+                    })),
+                };
+            }),
+        }),
+    };
+}

package/apps/runtime/dist/assistant/primer.js

@@ -0,0 +1,26 @@
+/**
+ * What engenty wizards is, on one page, in every turn of the studio assistant. Written from the
+ * user guide (docs/content/user/index.md and the pages it links); the details are a docs_search
+ * away.
+ */
+export const PRIMER = `ENGENTY WIZARDS IN ONE PAGE
+engenty wizards turns something done again and again into a wizard: pages that ask what it needs, AI steps that do the work, and a link to share. It runs on the person's own computer (a "local install" at ~/.engenty/wizards, studio at /studio) or in the cloud at engenty.ai with an account.
+
+Words
+- Studio: where wizards are built. Home lists the space's wizards; the editor (/edit/<id>) shows a wizard's flow as a diagram with its own chat (the architect) that builds and changes it.
+- Wizard: a flow of steps a person walks through on a link. Step kinds: a page (fields to fill in), an AI step (an agent with tools: web search, reading files, writing documents, images, video, pages, other services), a review, and the result.
+- Run: one person going through a wizard once. Results lists every run that reached its result.
+- Space: what all wizards of a team know. Its page has four parts: Info & brand (title, about, logos, colours, assets, facts), Knowledge (pages, tables and files the AI steps look things up in, kept apart by typed categories), Data (tables and pages the wizards keep) and Results (finished runs).
+- Model class: the kind of model a step needs (Classifier, Standard, High, Highest for text; Image, Video, Speech, Audio). Which model serves a class is a setting (Settings › Models), not part of the wizard.
+
+Thinking: an installed AI client on the person's subscription (Claude Code, Codex, Antigravity, Cursor Agent), own API keys (OpenAI, Anthropic, Google, fal.ai, ElevenLabs, Replicate, Vercel AI Gateway), a local model (Ollama), or engenty credits from an account. Settings › Models shows which way serves each class and what is missing.
+
+Sharing: Test runs a draft. Publish makes a version live behind a link. Share holds the link, the tag for a website, a QR code, channels (the page, the chat, and what plugins add: WhatsApp, SMS, calls) and the link's settings (on/off, runs per day, a new address). With an account, what is published on a local install also runs in the cloud, on the account's credits, while the computer is off.
+
+AI apps: the install is an MCP server; Claude Desktop, Cursor, Codex and others build and run wizards through it (Settings › AI apps).
+
+Plugins add pages to the studio (a Shop, a Termin-Planer), settings sections, sections of the space page, tools for AI steps and for this assistant, and channels. Settings › Plugins lists what is installed.
+
+Account and plans: an account is optional on a local install; it brings credits, cloud publishing, sync and Pro modules. In the cloud, teams are on a plan (Free, Pro, Team) with monthly credits; credits can be topped up on the account's billing page. Plans, prices and the balance come from the account (tools: plans, account, usage), never from memory.
+
+Studio addresses: / (home), /new (a new wizard), /edit/<id> (the editor), /space/info, /space/knowledge, /space/data, /space/results, /settings/account, /settings/team (cloud), /settings/connectors, /settings/models, /settings/integrate (AI apps), /settings/plugins, and the pages plugins add.`;

package/apps/runtime/dist/assistant/runs.js

@@ -0,0 +1,24 @@
+const running = new Map();
+export function startRun(runId, userId) {
+    running.set(runId, { userId, inbox: [] });
+}
+export function endRun(runId) {
+    running.delete(runId);
+}
+/** Puts a message into the person's running turn; false when that turn is over. */
+export function signalRun(userId, runId, signal) {
+    const run = running.get(runId);
+    if (!run || run.userId !== userId) {
+        return false;
+    }
+    run.inbox.push(signal);
+    return true;
+}
+/** The messages that came in since the turn last looked, oldest first. */
+export function takeSignals(runId) {
+    const run = running.get(runId);
+    if (!run?.inbox.length) {
+        return [];
+    }
+    return run.inbox.splice(0);
+}

package/apps/runtime/dist/auth/account.js

@@ -0,0 +1,175 @@
+import { createHash, randomBytes } from "node:crypto";
+import { env } from "../env.js";
+import { discovery, tokenRequest, unverifiedClaims } from "../manage.js";
+import { seal, unseal } from "../secrets/crypto.js";
+import { vaultDelete, vaultGet, vaultSet } from "../secrets/vault.js";
+import { deleteSetting, readSetting, writeSetting } from "../settings.js";
+/**
+ * The account a runtime that runs alone is linked to: sign-in (or sign-up) happens in the system
+ * browser at the Manage-App, the code comes back to this server on the loopback interface. The
+ * account is optional; it unlocks credits through the gateway and publishing to the cloud.
+ */
+export const CLIENT = { id: "wizards-desktop" };
+const REFRESH = "account.refresh";
+export const SCOPE = "openid profile email offline_access wizards:read wizards:write wizards:publish";
+/** The team of the linked account as the Manage-App last named it, for lines that must not wait on it. */
+const TEAM = "account.team";
+/** Loopback redirect on the port this server listens on (RFC 8252). */
+function redirectUri() {
+    return `http://127.0.0.1:${env.port}/api/auth/callback`;
+}
+/**
+ * The address that links an account. `signup`: the person has none yet — the account's sign-up
+ * page takes the invitation code (`code` fills it in) and goes on to the same sign-in.
+ */
+export async function startLink(options = {}) {
+    const d = await discovery(env.local.accountUrl);
+    const verifier = randomBytes(32).toString("base64url");
+    const state = { verifier, redirect: redirectUri(), exp: Date.now() + 15 * 60_000 };
+    const url = new URL(d.authorization_endpoint);
+    url.search = new URLSearchParams({
+        response_type: "code",
+        client_id: CLIENT.id,
+        redirect_uri: state.redirect,
+        scope: SCOPE,
+        resource: env.local.cloudUrl,
+        code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+        code_challenge_method: "S256",
+        state: seal(state),
+    }).toString();
+    if (!options.signup) {
+        return url.toString();
+    }
+    const signUp = new URL("/sign-up", env.local.accountUrl);
+    const code = options.code?.trim();
+    if (code) {
+        signUp.searchParams.set("code", code);
+    }
+    // The sign-up page goes on only to a path of its own origin.
+    signUp.searchParams.set("next", url.pathname + url.search);
+    return signUp.toString();
+}
+let cached = null;
+/**
+ * Keeps what the token endpoint handed out: the refresh token in the vault, the account in the
+ * settings. The browser flow (finishLink) and the device flow (device.ts) end here alike.
+ */
+export async function keep(tokens) {
+    const claims = unverifiedClaims(tokens.access_token);
+    if (!claims) {
+        throw new Error("The account's token names no tenant.");
+    }
+    if (tokens.refresh_token) {
+        await vaultSet(REFRESH, tokens.refresh_token);
+    }
+    cached = {
+        token: tokens.access_token,
+        expiresAt: Date.now() + (tokens.expires_in ?? 600) * 1000,
+    };
+    const account = {
+        userId: claims.userId,
+        tenantId: claims.tenantId,
+        name: claims.name,
+        email: claims.email,
+    };
+    await writeSetting("account", account);
+    return account;
+}
+export async function finishLink(code, rawState) {
+    const state = unseal(rawState);
+    if (!state || state.exp < Date.now()) {
+        throw new Error("This sign-in has expired.");
+    }
+    const tokens = await tokenRequest({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: state.redirect,
+        code_verifier: state.verifier,
+        resource: env.local.cloudUrl,
+    }, CLIENT, env.local.accountUrl);
+    return keep(tokens);
+}
+export function linkedAccount() {
+    return readSetting("account");
+}
+/** A fresh access token of the linked account, or null when none is linked (or it was revoked). */
+export async function accountToken() {
+    if (cached && cached.expiresAt - Date.now() > 60_000) {
+        return cached.token;
+    }
+    // One refresh at a time: a refresh token is used once, a second caller would be refused.
+    refreshing ??= refreshAccount().finally(() => {
+        refreshing = null;
+    });
+    return refreshing;
+}
+let refreshing = null;
+async function refreshAccount() {
+    const refresh = await vaultGet(REFRESH);
+    if (!refresh) {
+        return null;
+    }
+    try {
+        const tokens = await tokenRequest({ grant_type: "refresh_token", refresh_token: refresh, resource: env.local.cloudUrl }, CLIENT, env.local.accountUrl);
+        await keep(tokens);
+        return tokens.access_token;
+    }
+    catch {
+        return null;
+    }
+}
+export async function unlink() {
+    const refresh = await vaultGet(REFRESH);
+    if (refresh) {
+        const d = await discovery(env.local.accountUrl).catch(() => null);
+        if (d?.revocation_endpoint) {
+            await fetch(d.revocation_endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({ token: refresh, client_id: CLIENT.id }),
+                signal: AbortSignal.timeout(10_000),
+            }).catch(() => undefined);
+        }
+    }
+    cached = null;
+    await vaultDelete(REFRESH);
+    await deleteSetting("account");
+    await deleteSetting(TEAM);
+}
+/** The team as the Manage-App last named it: `wizards status` and the menu show it without a round trip. */
+export function knownTeam() {
+    return readSetting(TEAM);
+}
+let rememberedTeam = null;
+async function rememberTeam(tenant) {
+    const same = `${tenant.id}\n${tenant.name}\n${tenant.balanceCredits}`;
+    if (same === rememberedTeam) {
+        return;
+    }
+    rememberedTeam = same;
+    await writeSetting(TEAM, {
+        tenantId: tenant.id,
+        name: tenant.name,
+        balanceCredits: tenant.balanceCredits,
+        at: new Date().toISOString(),
+    });
+}
+/** Balance and tenants of the linked account, straight from the Manage-App. */
+export async function accountOverview() {
+    const token = await accountToken();
+    if (!token) {
+        return null;
+    }
+    const res = await fetch(`${env.local.accountUrl}/v1/me`, {
+        headers: { authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(10_000),
+    }).catch(() => null);
+    if (!res?.ok) {
+        return null;
+    }
+    const overview = (await res.json());
+    if (overview?.tenant) {
+        await rememberTeam(overview.tenant).catch(() => undefined);
+    }
+    return overview;
+}