wizards 0.1.10 → 0.2.0

package/README.md

@@ -177,6 +177,9 @@ More settings: [.env.example](.env.example).
 Development server, checks, how it is built, the managed mode:
 [docs/development.md](docs/development.md).
 
+Plugins add tools for steps, routes with their own tables and pages in the studio, without
+changing the runtime: [docs/plugins.md](docs/plugins.md).
+
 ## License
 
 [FSL-1.1-MIT](LICENSE): use it for yourself and your company, run it, change it — just don't

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

@@ -3,20 +3,22 @@ import { isTextMime } from "@engenty-wizards/shared/workspace";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
-import { connectorsLine, exampleWizard, mcpServersLine, PRINCIPLES, SCHEMA_DOC, WIDGET_GUIDE, } from "../authoring/guide.js";
+import { connectorsLine, exampleWizard, mcpServersLine, PRINCIPLES, pluginToolsLine, SCHEMA_DOC, WIDGET_GUIDE, } from "../authoring/guide.js";
 import { wizardOpSchema } from "../authoring/ops.js";
 import { importFromRegistry, listConnectors, searchRegistry } from "../connectors/external.js";
 import { attachTools, costOf, gatewayTools, textModel } from "../models.js";
+import { pluginToolsOf } from "../plugins/registry.js";
 import { htmlToMarkdown } from "../render/convert.js";
 import { ServiceError } from "../services/errors.js";
 import { deleteFile, listFiles, readFileText, writeFile } from "../services/files.js";
 import { checkDraftWidget } from "../services/widgets.js";
 import { editWizard, ownedWizard, writeDraft } from "../services/wizards.js";
+import { currentTenant } from "../tenants/tenant.js";
 import { assertPublicUrl, safeFetch } from "../tools/net-guard.js";
 import { runScript } from "../widgets/script.js";
 import { thoughtLine } from "./thought.js";
 const MAX_STEPS = 45;
-function systemPrompt(mcp, connectors) {
+function systemPrompt(mcp, connectors, pluginTools) {
     return `You design wizards for "engenty wizards": a page-by-page flow an end user walks through, where AI steps research, write, draw images, render video, build documents, dashboards and interactive widgets, or write into other systems.
 
 You talk to the ADMIN who builds the wizard. Answer in the admin's language, briefly and warmly. Never mention JSON, ids, schemas, files or templates to them — talk about pages, questions, steps, the widget and results.
@@ -27,7 +29,7 @@ ${WIDGET_GUIDE}
 
 ${mcpServersLine(mcp)}
 
-${connectorsLine(connectors)}
+${connectorsLine(connectors)}${pluginToolsLine(pluginTools)}
 
 Example of a complete wizard:
 \`\`\`json
@@ -341,7 +343,7 @@ export async function runArchitect(input) {
         // The system prompt is long and identical on every turn: cache it.
         instructions: {
             role: "system",
-            content: systemPrompt(input.mcpServers, input.connectors),
+            content: systemPrompt(input.mcpServers, input.connectors, await pluginToolsOf(currentTenant())),
             providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } },
         },
         model: resolved.model,

package/apps/runtime/dist/app.js

@@ -18,6 +18,7 @@ import { PLUGIN_NAME, pluginArchive, pluginMarketplace } from "./plugin.js";
 import { apiRoutes } from "./routes/api.js";
 import { internalRoutes } from "./routes/internal.js";
 import { marketplaceStudio } from "./routes/marketplace.js";
+import { pluginRoutes } from "./routes/plugins.js";
 import { connectCallback, publicRoutes, runRoutes, shareRoutes } from "./routes/runs.js";
 import { studio } from "./routes/studio.js";
 import { wizardStream } from "./routes/wizard-stream.js";
@@ -99,6 +100,7 @@ app.on(["GET", "POST", "DELETE"], "/api/mcp", (c) => mcp(c.req.raw));
 app.on(["GET", "POST", "DELETE"], "/api/mcp/bridge/:token", (c) => bridgeRequest(c.req.param("token"), c.req.raw));
 app.route("/api/studio/wizards", wizardStream);
 app.route("/api/studio/marketplace", marketplaceStudio);
+app.route("/api/studio/plugins", pluginRoutes);
 app.route("/api/studio", studio);
 app.route("/api/v1", apiRoutes);
 app.route("/api/internal", internalRoutes);

package/apps/runtime/dist/authoring/guide.js

@@ -218,6 +218,14 @@ export function connectorsLine(connectors) {
     });
     return `Connectors a wizard of this project can use (built in, or imported from the integrations registry; find more with find_connectors + import_connector):\n${lines.join("\n")}`;
 }
+/** The tools this app's plugins add; nothing where there are none. */
+export function pluginToolsLine(tools) {
+    if (!tools.length) {
+        return "";
+    }
+    const lines = tools.map((t) => `- ${t.id} — ${t.description}`);
+    return `\n\nTools of this app's plugins. An agent step lists one in "tools" by its full id, next to the built-in ones; a wizard that uses one runs only where that plugin is installed:\n${lines.join("\n")}`;
+}
 export function mcpServersLine(mcp) {
     return `Project MCP servers available to agent steps: ${mcp.length ? mcp.map((m) => `${m.id} (${m.name})`).join(", ") : "none — if the admin wants to write into an external system that needs one, build the step with http or browser, and tell them they can connect a server in the project settings"}.`;
 }
@@ -225,7 +233,7 @@ export function exampleWizard() {
     return JSON.stringify(EXAMPLE_WIZARD, null, 2);
 }
 /** The guide an MCP client reads before it writes a wizard. */
-export function authoringGuide(mcp, connectors = []) {
+export function authoringGuide(mcp, connectors = [], pluginTools = []) {
     return `engenty wizards: a wizard is a page-by-page flow an end user walks through on a shared link. Pages ask questions; AI steps research, write, draw images, render video, build documents and dashboards, or write into other systems. You author the wizard as JSON; the person who asked you is the ADMIN, the people who later open the link are END USERS.
 
 ${SCHEMA_DOC}
@@ -234,7 +242,7 @@ ${WIDGET_GUIDE}
 
 ${mcpServersLine(mcp)}
 
-${connectorsLine(connectors)}
+${connectorsLine(connectors)}${pluginToolsLine(pluginTools)}
 
 Models: a step names the KIND of model it needs, never a model. Pick the cheapest class that does the job:
 - "classifier": routing, yes/no, picking from options, pulling a few values out of text.

package/apps/runtime/dist/cli/environment.js

@@ -35,6 +35,8 @@ const INHERITED = new Set([
     "SANDBOX",
     "SANDBOX_ENABLED",
     "SANDBOX_IMAGE",
+    "PLUGINS_DIR",
+    "PLUGINS_WATCH",
     "ACCOUNT_URL",
     "ACCOUNT_GATEWAY_URL",
     "CLOUD_URL",
@@ -67,7 +69,10 @@ export function runtimePath(paths, env, node = process.execPath) {
  */
 export function runtimeEnv(paths, start, env = process.env, fileEnv = {}, platform = process.platform) {
     const secretsGiven = env.SECRETS !== undefined || fileEnv.SECRETS !== undefined;
+    const pluginsGiven = env.PLUGINS_DIR !== undefined || fileEnv.PLUGINS_DIR !== undefined;
     return {
+        // Plugins live beside the data, in the install's own folder.
+        ...(pluginsGiven ? {} : { PLUGINS_DIR: paths.plugins }),
         ...inherited(env),
         PATH: runtimePath(paths, env),
         NODE_ENV: "production",

package/apps/runtime/dist/cli/home.js

@@ -21,6 +21,7 @@ export function layout(home = wizardsHome()) {
         tools: join(home, "tools"),
         clients: join(home, "clients"),
         bin: join(home, "bin"),
+        plugins: join(home, "plugins"),
     };
 }
 /** The folder this code was installed to: it holds `apps/`, `plugin/` and package.json. */

package/apps/runtime/dist/db/client.js

@@ -64,8 +64,21 @@ async function openTenant(id) {
     const db = makeTenantDb(client);
     // Every database is brought to the current schema when it is first opened.
     await migrate(db, { migrationsFolder: migrationsFolder("tenant") });
+    for (const hook of openHooks) {
+        await hook(id, client);
+    }
     return db;
 }
+const openHooks = [];
+/** Runs for every tenant database right after it was opened and migrated (plugins' own tables). */
+export function onTenantOpen(hook) {
+    openHooks.push(hook);
+}
+/** The tenant databases this process has open, once each of them finished opening. */
+export async function openTenantClients() {
+    await Promise.allSettled(opened.values());
+    return [...clients.entries()];
+}
 /** The only way to a tenant's tables. Opens the database once per process and migrates it then. */
 export function tenantDb(id) {
     let db = opened.get(id);

package/apps/runtime/dist/engine/runner.js

@@ -10,6 +10,7 @@ import { saveAsset } from "../files/storage.js";
 import { managed, tenantInfo } from "../manage.js";
 import { hasFfmpeg } from "../media/ffmpeg.js";
 import { ModelUnavailableError } from "../models.js";
+import { runEnded } from "../plugins/events.js";
 import { projectFiles } from "../services/project-files.js";
 import { projectProfile } from "../services/projects.js";
 import { listRows, scopeOf } from "../store/index.js";
@@ -112,6 +113,8 @@ async function updateRun(runId, patch) {
     // A run that ended needs no credits held for it any more.
     if (patch.status === "done" || patch.status === "failed" || patch.status === "cancelled") {
         await releaseRun(runId);
+        // Plugins hear of it; the run does not wait for them.
+        void runEnded(runId, patch.status);
     }
     signalChanged(runId);
 }

package/apps/runtime/dist/env.js

@@ -60,6 +60,11 @@ function agentOsInstalled() {
         return false;
     }
 }
+/** A comma-separated list. */
+const list = (key) => str(key)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
 const num = (key, fallback) => {
     const v = Number(process.env[key]);
     return Number.isFinite(v) && v > 0 ? v : fallback;
@@ -99,10 +104,7 @@ export const env = {
      */
     signedOutUrl: str("SIGNED_OUT_URL"),
     /** More host names this server answers under, besides APP_URL's and the loopback names. */
-    allowedHosts: str("ALLOWED_HOSTS")
-        .split(",")
-        .map((h) => h.trim())
-        .filter(Boolean),
+    allowedHosts: list("ALLOWED_HOSTS"),
     dataDir,
     /** The control database; empty = a libSQL file in the data folder. */
     databaseUrl: str("DATABASE_URL", ""),
@@ -190,6 +192,18 @@ export const env = {
         secretAccessKey: str("S3_SECRET_ACCESS_KEY"),
     },
     turnstile: { siteKey: str("TURNSTILE_SITE_KEY"), secret: str("TURNSTILE_SECRET_KEY") },
+    /** Plugins (docs/plugins.md). Code in these folders runs with the runtime's own rights. */
+    plugins: {
+        /** Folders to look in, besides the `modules/` this runtime ships with. */
+        dirs: list("PLUGINS_DIR").map((dir) => resolve(dir)),
+        /** Managed: plugins every tenant has. The Manage-App switches further ones on per tenant. */
+        defaults: list("PLUGINS_DEFAULT"),
+        /**
+         * A plugin loads again when one of its files changes. Default: on where the runtime runs
+         * alone. A runtime of a Manage-App never reloads: it would hit every tenant.
+         */
+        watch: !manageUrl && str("PLUGINS_WATCH", "1") === "1",
+    },
     limits: {
         visitorRunsPerHour: num("LIMIT_VISITOR_RUNS_PER_HOUR", 6),
         defaultDailyRuns: num("LIMIT_DEFAULT_DAILY_RUNS", 50),

package/apps/runtime/dist/index.js

@@ -6,6 +6,7 @@ import { resumeInterruptedRuns } from "./engine/runner.js";
 import { basePath, env } from "./env.js";
 import { managed } from "./manage.js";
 import { loadCatalog, loadLocalModels } from "./models.js";
+import { loadPlugins } from "./plugins/loader.js";
 import { closeBrowser } from "./render/chromium.js";
 import { clearRunning, writeRunning } from "./running.js";
 import { syncMarketplace } from "./services/marketplace.js";
@@ -14,6 +15,8 @@ import { purgeUnusedStores } from "./store/index.js";
 import { LOCAL_TENANT } from "./tenants/tenant.js";
 import { onRestart } from "./update.js";
 await migrateControlDb();
+// Before any tenant database opens: each gets the plugins' own tables as it does.
+await loadPlugins();
 if (managed) {
     // Every tenant database is brought to this release's schema; a new one migrates when first opened.
     void migrateAllTenants().then(({ migrated, failed }) => {

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

@@ -3,6 +3,7 @@ import { authoringGuide } from "../authoring/guide.js";
 import { wizardOpSchema } from "../authoring/ops.js";
 import { importFromRegistry, listConnectors, searchRegistry } from "../connectors/external.js";
 import { RunConflict } from "../engine/runner.js";
+import { pluginToolsOf } from "../plugins/registry.js";
 import { ServiceError } from "../services/errors.js";
 import { deleteFile, listFiles, readFileText, writeFile } from "../services/files.js";
 import { marketplaceWizard, searchMarketplace } from "../services/marketplace.js";
@@ -79,7 +80,7 @@ export function registerTools(server, who) {
         const project = projectId
             ? await ownedProject(who.userId, projectId)
             : await defaultProject(who.userId);
-        return authoringGuide(project.mcpServers.map((s) => ({ id: s.id, name: s.name })), await listConnectors(project.id));
+        return authoringGuide(project.mcpServers.map((s) => ({ id: s.id, name: s.name })), await listConnectors(project.id), await pluginToolsOf(who.tenantId));
     });
     // --- connectors ------------------------------------------------------------
     tool("find_connectors", "wizards:read", {

package/apps/runtime/dist/plugins/discovery.js

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, resolve, sep } from "node:path";
+import { PLUGIN_ID } from "@engenty-wizards/shared/definition";
+import { z } from "zod";
+/**
+ * Finding plugins. A folder of plugins holds, in any mix:
+ *
+ *   notify.ts                    one file: the server half, its id is the file's name
+ *   contacts/engenty.plugin.json a folder with a manifest: `src/plugin.ts`, `dist/client.js`
+ *   hello/index.ts               a folder without one: the server half, its id is the folder's name
+ *   node_modules/<package>       packages installed there that carry a manifest
+ */
+export const MANIFEST_FILE = "engenty.plugin.json";
+/** Further fields (an engenty module's `provides`, `capabilities`, …) are kept as they are. */
+const manifestSchema = z.looseObject({
+    id: z.string().regex(PLUGIN_ID),
+    name: z.string().min(1),
+    version: z.string().default("0.0.0"),
+    description: z.string().optional(),
+    server: z.string().optional(),
+    studio: z.string().optional(),
+    styles: z.string().optional(),
+});
+/** `.mjs` is left out: Node keeps such a file once imported, so a reload would not read it again. */
+const CODE = new Set([".ts", ".js"]);
+const SERVER_ENTRIES = ["src/plugin.ts", "src/plugin.js", "dist/plugin.js"];
+const INDEX_ENTRIES = ["index.ts", "index.js"];
+const isDir = (path) => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+const firstExisting = (root, names) => names.map((name) => join(root, name)).find((path) => existsSync(path)) ?? null;
+/** A path of the manifest must stay inside the plugin's folder. */
+function inside(root, relative) {
+    const path = resolve(root, relative);
+    return path.startsWith(root + sep) && existsSync(path) ? path : null;
+}
+function fromManifest(root) {
+    const parsed = manifestSchema.safeParse(JSON.parse(readFileSync(join(root, MANIFEST_FILE), "utf8")));
+    if (!parsed.success) {
+        throw new Error(`${MANIFEST_FILE}: ${z.prettifyError(parsed.error)}`);
+    }
+    const manifest = parsed.data;
+    const entry = manifest.server
+        ? inside(root, manifest.server)
+        : firstExisting(root, SERVER_ENTRIES);
+    if (manifest.server && !entry) {
+        throw new Error(`"server": ${manifest.server} is not a file of the plugin.`);
+    }
+    return {
+        id: manifest.id,
+        manifest,
+        root,
+        entry,
+        studio: inside(root, manifest.studio ?? "dist/client.js"),
+        styles: inside(root, manifest.styles ?? "dist/client.css"),
+        single: false,
+    };
+}
+/** A plugin without a manifest: its id is the name of its file or folder. */
+function bare(id, root, entry, single) {
+    if (!PLUGIN_ID.test(id)) {
+        throw new Error(`"${id}" is no plugin id: lower case, digits and "-", starting with a letter.`);
+    }
+    return {
+        id,
+        manifest: { id, name: id, version: "0.0.0" },
+        root,
+        entry,
+        studio: null,
+        styles: null,
+        single,
+    };
+}
+/** Packages below `node_modules` that are plugins: `<name>` and `@scope/<name>`. */
+function packagesIn(nodeModules) {
+    const out = [];
+    for (const name of readdirSync(nodeModules).sort()) {
+        if (name.startsWith(".")) {
+            continue;
+        }
+        const path = join(nodeModules, name);
+        const candidates = name.startsWith("@")
+            ? readdirSync(path)
+                .sort()
+                .map((child) => join(path, child))
+            : [path];
+        out.push(...candidates.filter((dir) => existsSync(join(dir, MANIFEST_FILE))));
+    }
+    return out;
+}
+function sourceAt(path) {
+    if (!isDir(path)) {
+        const ext = extname(path);
+        return CODE.has(ext) && !path.endsWith(".d.ts")
+            ? bare(basename(path, ext), resolve(path, ".."), path, true)
+            : null;
+    }
+    if (existsSync(join(path, MANIFEST_FILE))) {
+        return fromManifest(path);
+    }
+    const index = firstExisting(path, INDEX_ENTRIES);
+    return index ? bare(basename(path), path, index, false) : null;
+}
+/** The plugins in these folders. Of two with one id the first found stays. */
+export function discoverPlugins(dirs) {
+    const found = new Map();
+    const problems = [];
+    const take = (path) => {
+        try {
+            const source = sourceAt(path);
+            if (!source) {
+                return;
+            }
+            const first = found.get(source.id);
+            if (first) {
+                problems.push({
+                    path,
+                    message: `Plugin "${source.id}" is already loaded from ${first.root}.`,
+                });
+                return;
+            }
+            found.set(source.id, source);
+        }
+        catch (err) {
+            problems.push({ path, message: err.message });
+        }
+    };
+    for (const dir of dirs) {
+        if (!isDir(dir)) {
+            continue;
+        }
+        for (const name of readdirSync(dir).sort()) {
+            if (name.startsWith(".") || name.startsWith("_")) {
+                continue;
+            }
+            const path = join(dir, name);
+            if (name === "node_modules") {
+                packagesIn(path).forEach(take);
+            }
+            else {
+                take(path);
+            }
+        }
+    }
+    return { found: [...found.values()], problems };
+}

package/apps/runtime/dist/plugins/events.js

@@ -0,0 +1,40 @@
+import { eq } from "drizzle-orm";
+import { db, schema } from "../db/client.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { pluginsOf } from "./registry.js";
+/**
+ * Tells the tenant's plugins that a run reached its end. A plugin cannot fail a run: what a
+ * listener throws is logged and nothing more.
+ */
+export async function runEnded(runId, status) {
+    try {
+        const event = `run.${status}`;
+        const listening = (await pluginsOf(currentTenant())).filter((p) => p.listeners[event]?.length);
+        if (!listening.length) {
+            return;
+        }
+        const run = await db.query.run.findFirst({ where: eq(schema.run.id, runId) });
+        const wizard = run && (await db.query.wizard.findFirst({ where: eq(schema.wizard.id, run.wizardId) }));
+        if (!run || !wizard) {
+            return;
+        }
+        const payload = {
+            run: { id: run.id, wizardId: run.wizardId, mode: run.mode, status },
+            wizard: { id: wizard.id, title: run.definition.title, projectId: wizard.projectId },
+            values: run.state.values,
+        };
+        for (const plugin of listening) {
+            for (const listener of plugin.listeners[event] ?? []) {
+                try {
+                    await listener(payload);
+                }
+                catch (err) {
+                    console.error(`[plugin ${plugin.source.id}] ${event}:`, err);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error("[plugins] run event:", err);
+    }
+}